@qzhike/pdf-parse

OpenClaw 插件：通过 DocumentParse（上游 MinerU）将 workspace 内 PDF 异步转为 Markdown。

安装后随包加载 Skill qzhike-pdf-parse，指导 Agent 使用 qzhike_parse_pdf + qzhike_parse_pdf_status。

工具

| 工具 | 用途 | |------|------| | qzhike_parse_pdf | 提交 workspace 相对路径 PDF → 返回 jobId | | qzhike_parse_pdf_status | 轮询任务；done 时写入 parsed-pdfs/…/document.md 并返回 markdownPath / preview |

配置路径：plugins.entries.qzhike-pdf-parse.config（OpenClaw 从 ~/.openclaw/.env 解析 ${DOCUMENT_PARSE_*}；插件不读 process.env）。

安装

openclaw plugins install @qzhike/pdf-parse
openclaw gateway restart
openclaw plugins inspect qzhike-pdf-parse --runtime --json

tools.alsoAllow（自动）：npm postinstall 会合并插件 id 与两个工具名到 ~/.openclaw/openclaw.json。若 npm 使用 --ignore-scripts，手动执行：

npx --yes @qzhike/pdf-parse openclaw-qzhike-pdf-parse-setup
openclaw gateway restart

跳过自动合并：OPENCLAW_QZHIKE_SKIP_SETUP=1。openclaw.json 须为严格 JSON（JSON5/注释会导致 merge 跳过）。

本地开发（link）：

openclaw plugins install --link /absolute/path/to/qzhike-pdf-parse
node /absolute/path/to/qzhike-pdf-parse/bin/openclaw-qzhike-pdf-parse-setup.js
openclaw gateway restart

环境变量

在 ~/.openclaw/.env：

# DocumentParse 服务 origin（无尾斜杠）
DOCUMENT_PARSE_BASE_URL=http://127.0.0.1:20338
# 与 DocumentParse 服务 .env 中 DOCUMENT_PARSE_API_KEY 相同
DOCUMENT_PARSE_API_KEY=change-me

| 环境 | DOCUMENT_PARSE_BASE_URL 示例 | |------|-------------------------------| | deskmini 同机 | http://127.0.0.1:20338 | | zjsw claw → srv | http://<zjsw_srv>:20338 或 Tailscale 主机名 |

OpenClaw 配置

openclaw.json 片段（setup 脚本会自动 merge；手改时参考）：

{
  plugins: {
    allow: ["qzhike-pdf-parse"],
    entries: {
      "qzhike-pdf-parse": {
        enabled: true,
        config: {
          baseUrl: "${DOCUMENT_PARSE_BASE_URL}",
          apiKey: "${DOCUMENT_PARSE_API_KEY}",
          timeoutSeconds: 120,
          previewMaxChars: 2000,
          workspaceOutputSubdir: "parsed-pdfs",
        },
      },
    },
  },
  tools: {
    alsoAllow: [
      "qzhike-pdf-parse",
      "qzhike_parse_pdf",
      "qzhike_parse_pdf_status",
    ],
  },
}

合并进现有 openclaw.json 时勿整文件覆盖。若已有 tools.profile，保留 profile，用 tools.alsoAllow 追加工具名。

两处存储（勿混淆）：

| 路径 | 用途 | |------|------| | ~/.openclaw/cache/qzhike-pdf-parse/{scopeHash}/{jobId}.json | 插件本地 job 索引（jobId、状态、markdownPath 等），供轮询与恢复 | | {workspace}/parsed-pdfs/{scopeHash}/{jobId}/ | 解析产物（document.md、images/、source.pdf），Agent 应读这里 |

旧版配置若仍为 workspaceOutputSubdir: "cache/parsed-pdfs"，setup 脚本与运行时均会归一化为 parsed-pdfs。

飞书使用

1. 在群聊或私聊发送 PDF 附件，并说明意图（如「解析并总结这份 PDF」）。
2. Agent 应调用 qzhike_parse_pdf（filePath 为 workspace 相对路径，常见 uploads/…）。
3. 轮询 qzhike_parse_pdf_status 直到 done（MinerU 可能需数分钟）。
4. 基于 markdownPath 或 preview 回答。

群聊 scope：默认 feishu:group:{chatId}，同群共享解析缓存；一般不要传 scopeKey。

建议在 workspace AGENTS.md 粘贴仓库开源版 examples/workspace/AGENTS.pdf-parse.snippet.md 中的段落，强制 PDF 走本插件。

Bundled Skill

本包含 skills/qzhike-pdf-parse/SKILL.md，在 openclaw.plugin.json 中声明；启用插件并 restart Gateway 后自动加载，一般无需 symlink 到 ~/.openclaw/skills/。

Skill 约定：

• 用户附 PDF 或要求读 PDF → qzhike_parse_pdf，再 qzhike_parse_pdf_status
• 勿用 read / cat 直接读 PDF 二进制
• 长任务分 turn：先提交，再轮询

详见包内 skills/qzhike-pdf-parse/references/feishu-workflow.md。

工具 API（摘要）

qzhike_parse_pdf

| 参数 | 说明 | |------|------| | filePath | 必填，workspace 相对路径，须 .pdf | | scopeKey | 可选，调试覆盖；飞书场景通常省略 |

qzhike_parse_pdf_status

| 参数 | 说明 | |------|------| | jobId | 必填，qzhike_parse_pdf 返回值 | | scopeKey | 可选，须与提交时一致 |

排错

| 现象 | 检查 | |------|------| | 工具未出现 | plugins.allow 含 qzhike-pdf-parse；tools.alsoAllow 含两个工具名；gateway restart | | alsoAllow 未合并 | openclaw.json 是否为严格 JSON；npm 是否 --ignore-scripts | | document_parse_unreachable | 从 claw 主机 curl $DOCUMENT_PARSE_BASE_URL/health | | file_not_found | 飞书附件是否已落到 workspace；路径是否为相对路径 | | 解析很慢 | 正常；大 PDF + MinerU pipeline 可能数分钟 |

要求

• Node >= 22
• OpenClaw >= 2026.5.12
• 可达的 DocumentParse 服务（见兄弟项目 DocumentParse）

License

MIT