refactor(adk): replace go-fitz with go-pdfium (WASM) for MultiModalRead (#869)

Switch PDF processing in agentkit and local backends from
github.com/gen2brain/go-fitz to github.com/klippa-app/go-pdfium with the
WebAssembly backend, aligning with aisandbox_v2.go. Removes the CGO/MuPDF
dependency entirely.

The change introduces a process-global pdfium worker pool (lazy-init) and
a new PDFiumPoolConfig with MinIdle/MaxIdle/MaxTotal/AcquireTimeout knobs
exposed via MultiModalReadConfig. Each go module maintains its own pool
since they cannot share an internal package across module boundaries.

Author: JonXSnow

.github/workflows/tests.yml

@@ -21,7 +21,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
         with:
-          go-version: "1.22"
+          go-version: "1.25.6"
       # - name: Go test for every module
       #   run: |
       #     modules=`find . -name "go.mod" -exec dirname {} \;`

adk/backend/agentkit/README.md

@@ -10,16 +10,24 @@ A secure filesystem backend for EINO ADK that executes operations in Volcengine'
 go get github.com/cloudwego/eino-ext/adk/backend/agentkit
 ```
 
-#### Native dependency for `MultiModalRead` (PDF rendering)
+#### PDF rendering for `MultiModalRead`
 
-`MultiModalRead` rasterises PDF pages via [`go-fitz`](https://github.com/gen2brain/go-fitz),
-which loads MuPDF at runtime through `purego`. Install MuPDF before running:
+`MultiModalRead` rasterises PDF pages via [`klippa-app/go-pdfium`](https://github.com/klippa-app/go-pdfium)
+on its **WebAssembly** backend (executed in-process by [`wazero`](https://github.com/tetratelabs/wazero)).
+No CGO toolchain or system-level MuPDF/PDFium libraries are required — it works out of the box
+across Linux, macOS and Windows.
 
-- macOS: `brew install mupdf`
-- Ubuntu/Debian: `sudo apt-get install -y libmupdf-dev`
-- CentOS/RHEL: `sudo yum install -y mupdf-devel`
+Behaviour notes:
 
-If you don't use `MultiModalRead`, MuPDF is not required at runtime.
+- A process-global PDFium worker pool is initialised lazily on the first paged-PDF request
+  (a few hundred ms one-time cost) and reused thereafter. Each WASM worker uses tens of MB
+  of memory; default `MaxTotal` is `max(NumCPU, 2)`.
+- The pool is a single shared instance per process; if a second backend passes a different
+  `PDFiumPool` sizing, the second config is ignored and a `WARN` log is emitted.
+- The `agentkit` and `local` backends live in independent Go modules and therefore each
+  maintain their **own** process-global pool. Apps importing both will run two pdfium WASM
+  runtimes concurrently.
+- Sizing can be tuned via `MultiModalReadConfig.PDFiumPool` (see below).
 
 ### Basic Usage
 
@@ -85,11 +93,27 @@ type Config struct {
 }
 
 type MultiModalReadConfig struct {
-    MaxImageSizeMB        int     // image read size limit (MB).      Default 10,  hard-cap 2048
-    MaxPDFSizeMB          int     // full PDF read size limit (MB).   Default 20,  hard-cap 2048
-    MaxPagedPDFSizeMB     int     // paged PDF read size limit (MB).  Default 100, hard-cap 2048
-    MaxPDFPagesPerRequest int     // max pages per paged read.        Default 20,  hard-cap 1000
-    PDFRenderDPI          float64 // DPI when rasterising PDF pages.  Default 150, hard-cap 600
+    MaxImageSizeMB        int           // image read size limit (MB).      Default 10,  hard-cap 2048
+    MaxPDFSizeMB          int           // full PDF read size limit (MB).   Default 20,  hard-cap 2048
+    MaxPagedPDFSizeMB     int           // paged PDF read size limit (MB).  Default 100, hard-cap 2048
+    MaxPDFPagesPerRequest int           // max pages per paged read.        Default 20,  hard-cap 1000
+    PDFRenderDPI          int           // DPI when rasterising PDF pages.  Default 150, hard-cap 600
+
+    // PDFiumPool tunes the process-global PDFium worker pool used for paged PDF rendering.
+    // Only honoured on the first lazy initialisation; subsequent callers passing a different
+    // sizing trigger a WARN log and continue with the existing pool.
+    PDFiumPool PDFiumPoolConfig
+
+    // PDFiumAcquireTimeout caps how long MultiModalRead waits for a pdfium worker
+    // when the caller's ctx has no deadline. Per-read setting (different callers
+    // may use different values). Default 30s.
+    PDFiumAcquireTimeout time.Duration
+}
+
+type PDFiumPoolConfig struct {
+    MinIdle  int // minimum idle workers kept alive.   Default 1
+    MaxIdle  int // maximum idle workers kept alive.   Default 2
+    MaxTotal int // maximum total workers (>= 2).      Default max(2, NumCPU)
 }
 ```
 

adk/backend/agentkit/README_zh.md

@@ -10,16 +10,22 @@
 go get github.com/cloudwego/eino-ext/adk/backend/agentkit
 ```
 
-#### `MultiModalRead` 的本机依赖（PDF 渲染）
+#### `MultiModalRead` 的 PDF 渲染
 
-`MultiModalRead` 通过 [`go-fitz`](https://github.com/gen2brain/go-fitz) 渲染 PDF
-页面，运行时通过 `purego` 加载 MuPDF。运行前请安装 MuPDF：
+`MultiModalRead` 通过 [`klippa-app/go-pdfium`](https://github.com/klippa-app/go-pdfium)
+的 **WebAssembly** 后端（由 [`wazero`](https://github.com/tetratelabs/wazero) 在进程内执行）
+光栅化 PDF 页面。**无需 CGO 工具链，也无需 MuPDF/PDFium 等系统级原生库**，在 Linux、
+macOS 和 Windows 上开箱即用。
 
-- macOS：`brew install mupdf`
-- Ubuntu/Debian：`sudo apt-get install -y libmupdf-dev`
-- CentOS/RHEL：`sudo yum install -y mupdf-devel`
+行为说明：
 
-如果不使用 `MultiModalRead`，则运行时无需 MuPDF。
+- 进程内会在第一次分页 PDF 请求时延迟初始化一个全局 PDFium worker pool（首次约几百
+  毫秒），后续调用复用。每个 WASM worker 占用约数十 MB 内存，默认 `MaxTotal=max(NumCPU, 2)`。
+- pool 在整个进程内是单例；若第二个 backend 传入不同的 `PDFiumPool` sizing，第二份配置
+  会被忽略并打印 `WARN` 日志。
+- `agentkit` 与 `local` backend 分别属于独立 Go module，因此 **各自维护一份** 进程级 pool。
+  同时引入两个 backend 的应用会运行两套 pdfium WASM runtime。
+- 可通过 `MultiModalReadConfig.PDFiumPool` 调整 pool 大小（见下文）。
 
 ### 基本用法
 
@@ -85,11 +91,25 @@ type Config struct {
 }
 
 type MultiModalReadConfig struct {
-    MaxImageSizeMB        int     // 图片读取大小上限（MB）。       默认 10，硬上限 2048
-    MaxPDFSizeMB          int     // PDF 全量读取大小上限（MB）。   默认 20，硬上限 2048
-    MaxPagedPDFSizeMB     int     // PDF 分页读取大小上限（MB）。   默认 100，硬上限 2048
-    MaxPDFPagesPerRequest int     // 单次分页读取最多页数。         默认 20，硬上限 1000
-    PDFRenderDPI          float64 // PDF 页面渲染 DPI。            默认 150，硬上限 600
+    MaxImageSizeMB        int           // 图片读取大小上限（MB）。       默认 10，硬上限 2048
+    MaxPDFSizeMB          int           // PDF 全量读取大小上限（MB）。   默认 20，硬上限 2048
+    MaxPagedPDFSizeMB     int           // PDF 分页读取大小上限（MB）。   默认 100，硬上限 2048
+    MaxPDFPagesPerRequest int           // 单次分页读取最多页数。         默认 20，硬上限 1000
+    PDFRenderDPI          int           // PDF 页面渲染 DPI。            默认 150，硬上限 600
+
+    // PDFiumPool 用于调整分页 PDF 渲染所使用的进程级 PDFium worker pool。
+    // 仅在首次延迟初始化时生效；后续调用方传入不同 sizing 会触发 WARN 日志，沿用已有 pool。
+    PDFiumPool PDFiumPoolConfig
+
+    // PDFiumAcquireTimeout 限制调用方 ctx 无 deadline 时获取 pdfium worker 的等待上限。
+    // 是 per-read 配置（不同调用方可使用不同值）。默认 30s。
+    PDFiumAcquireTimeout time.Duration
+}
+
+type PDFiumPoolConfig struct {
+    MinIdle  int // 保持存活的最小空闲 worker 数。      默认 1
+    MaxIdle  int // 保持存活的最大空闲 worker 数。      默认 2
+    MaxTotal int // 最大 worker 数（>= 2）。            默认 max(2, NumCPU)
 }
 ```
 

adk/backend/agentkit/go.mod

@@ -1,13 +1,11 @@
 module github.com/cloudwego/eino-ext/adk/backend/agentkit
 
-go 1.23.0
-
-toolchain go1.23.12
+go 1.25.0
 
 require (
 	github.com/bytedance/sonic v1.15.0
 	github.com/cloudwego/eino v0.9.1
-	github.com/gen2brain/go-fitz v1.24.15
+	github.com/klippa-app/go-pdfium v1.19.3
 	github.com/slongfield/pyfmt v0.0.0-20220222012616-ea85ff4c361f
 	github.com/stretchr/testify v1.11.1
 )
@@ -21,12 +19,11 @@ require (
 	github.com/cloudwego/base64x v0.1.6 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
-	github.com/ebitengine/purego v0.8.4 // indirect
 	github.com/eino-contrib/jsonschema v1.0.3 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/goph/emperror v0.17.2 // indirect
+	github.com/jolestar/go-commons-pool/v2 v2.1.2 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
-	github.com/jupiterrider/ffi v0.5.0 // indirect
 	github.com/klauspost/cpuid/v2 v2.2.9 // indirect
 	github.com/kr/pretty v0.2.0 // indirect
 	github.com/mailru/easyjson v0.7.7 // indirect
@@ -37,13 +34,15 @@ require (
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/sirupsen/logrus v1.9.3 // indirect
+	github.com/tetratelabs/wazero v1.11.0 // indirect
 	github.com/twitchyliquid64/golang-asm v0.15.1 // indirect
 	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
 	github.com/yargevad/filepathx v1.0.0 // indirect
 	golang.org/x/arch v0.11.0 // indirect
-	golang.org/x/crypto v0.32.0 // indirect
 	golang.org/x/exp v0.0.0-20230713183714-613f0c0eb8a1 // indirect
-	golang.org/x/sys v0.33.0 // indirect
+	golang.org/x/net v0.53.0 // indirect
+	golang.org/x/sys v0.43.0 // indirect
+	golang.org/x/text v0.37.0 // indirect
 	gopkg.in/check.v1 v1.0.0-20190902080502-41f04d3bba15 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )