PdfCraft（PDF 处理）

在编码智能体中检查、编辑、OCR 与交付 PDF。保留原件，逐页核对顺序、几何与可搜索文本。

版本：0.1.0-dev.20261024.2 · 许可证：Apache-2.0 · 技能：20 个 · MCP 服务：1 个

English · 安装 · 快速开始 · 项目结构

项目定位

PdfCraft 面向需要把 PDF 真正处理完、而不是只生成一段脚本的用户。它不重新实现 PDF 引擎，而是固定并校验 pdfcraft-cli 0.2.1，用 20 个技能和一层轻量 Harness 把检查、页面操作、表单、脱敏、OCR、书签、印前检查和编辑器串起来。

适用场景：

• 页面重排、旋转、删除、拆分与合并
• 扫描件 OCR 与可搜索文本检查
• 表单字段填写、导出与回读
• 内容脱敏、水印与审阅稿
• 书签、内部链接与目录
• 印前检查与交付核验

不适用：

• 替代专业排版软件做复杂版面设计
• 在没有原件或明确授权的情况下修改他人文档
• 把进程退出码 0 当成交付完成

一眼看懂

输入 PDF / 扫描件 / 表单
        │
        ▼
PdfCraft 技能（检查 → 计划 → 执行 → 回读）
        │
        ├── pdfcraft-cli（固定版本，原生 PDF 操作）
        ├── OCR / Tesseract（仅扫描件需要）
        └── MCP 编辑器（浏览器内查看与局部调整）
        │
        ▼
新文件 + 回执 + 逐页复核

能力与边界

能力	说明	边界
检查	页数、元数据、文本、扫描/OCR 状态	空文本不等于空白页
页面操作	旋转、重排、删除、拆分、合并	写入新文件，不覆盖原件
表单	填写、导出、回读字段值	字段缺失或类型不符时停止
脱敏	指定区域或文本删除	需明确范围与复核
OCR	扫描件增加可搜索文本层	中文 OCR 需显式 Tesseract 后端
书签/链接	目录、书签、内部跳转	页码变化后需重建
印前检查	页面框、字体、图像、出血	不替代印刷厂最终检查
编辑器	浏览器内打开当前工作区	保存后仍需重新打开核验

架构与核心流程

宿主 / Agent
   │  调用技能
   ▼
skills/pdfcraft-*  ──►  skills/pdfcraft-harness
                              │
                              ▼
                     pdfcraft-cli 0.2.1
                              │
                              ▼
                     PDF 输出 + receipt.json
                              │
                              ▼
                     回读、逐页检查、人工复核

核心原则：

1. 先只读检查，再计划，再执行。
2. 每次写入产生新文件，原件保持不变。
3. 退出码 0 只表示命令完成，交付状态仍是 REVIEW_REQUIRED。
4. 结果不确定时标记 UNKNOWN，只做只读核对，不自动重放。

兼容性

项目	状态
已验证安装器	macOS arm64
上游 CLI 原生运行	Linux x64/arm64、Windows x64、macOS Intel/arm64
宿主	Codex 有完整安装与模型证据；Claude Code、Gemini、OpenCode、Kimi 未验证
Python	3.11+
Node.js	24+（编辑器）
中文 OCR	Tesseract 5.5.3 + tessdata_fast 4.1.0（macOS arm64 记录）

安装

前置条件

• Python 3.11 或更新版本
• Node.js 24 或更新版本（仅编辑器需要）
• 可访问 GitHub Releases，用于下载固定版本 CLI

从市场安装

codex plugin marketplace add partme-ai/full-aigc-plugins
codex plugin add pdfcraft@full-aigc-plugins

安装后重启宿主，在新任务中先做只读检查：

检查这份 PDF 的页数、元数据、文本和 OCR 状态，不要修改。

快速开始

1. 只读检查：确认页数、页面尺寸、文本层和扫描状态。
2. 一次有界修改：例如“旋转第 2 页，把顺序改为 3、1、2，另存为新文件，重新打开核对页序和几何”。
3. 核对回执：查看输出文件、大小、摘要和页级结果。
4. 重新打开：在新进程中回读，确认不是只改了内存状态。
5. 视觉复核：对版面、遮挡、字体和可读性做人工检查。

配置

变量	用途	默认
CRAFT_EDITOR_UPDATE	设为 off 跳过编辑器增强包下载	开启
CRAFT_WORKSPACE_ROOT	编辑器绑定的工作区	当前项目
CRAFT_PANEL_METADATA_FILE	编辑器面板元数据	插件内置

密钥、令牌和私有路径不要写入计划文件或回执。

扩展契约

新增技能时应：

• 使用 pdfcraft- 前缀（迁移完成后）
• 在 SKILL.md 中声明触发条件和边界
• 通过 Harness 调用固定 CLI，不直接拼接 shell
• 写入后必须回读并给出可核验结果
• 不把“命令成功”写成“交付完成”

重试、幂等与恢复

• 失败后先读取 receipt.json，确认已完成到哪一步。
• 不自动重放已产生副作用的操作。
• 需要重试时使用新的输出路径，保留旧回执。
• UNKNOWN 状态只做只读核对，不重复执行。

数据与状态

• 输入文件只读。
• 输出文件、回执和临时目录分开存放。
• 回执包含命令、输入、输出、摘要和状态。
• 删除临时文件前先确认回执已保存。

安全

• 脱敏结果必须人工复核，不能只看命令成功。
• 不上传未授权的文档到第三方服务。
• OCR 语言包和外部二进制需来自可信来源。
• 发现敏感信息泄露时先轮换凭据，再清理文件。

可观测性与运行

• 每次操作保留命令、退出码、stdout/stderr 和回执。
• 页面级结果记录页码、尺寸和文本状态。
• 交付前检查输出文件是否存在、可打开、页数正确。

开发与验证

node --test
python3 -m pytest

提交前至少验证：

• 技能清单与目录一致
• CLI 版本与摘要固定
• 安装器在支持平台可运行
• README 命令与实际入口一致

打包与发布

• 版本号与 plugin.json、市场清单、release tag 一致。
• ZIP 根目录为 pdfcraft-plugin。
• 发布后重新安装并做一次只读检查。

升级与迁移

• 从旧 pdfcraft 安装迁移时，先卸载旧插件，再安装 pdfcraft。
• 旧任务目录和回执保留，不覆盖。
• 技能名迁移完成后，旧 pdfcraft-* 名称不再作为入口。

故障排查

现象	检查
命令找不到	确认插件已安装、宿主已重启
OCR 无文本	检查 Tesseract 与语言包
编辑器空白	检查 Node.js 版本与工作区权限
输出页序错误	重新打开输出文件，核对页级回执
中文乱码	检查字体与 OCR 语言包

项目结构

pdfcraft-plugin/
├── .zcode-plugin/        # ZCode 清单与 UI surface
├── .codex-plugin/        # Codex 清单
├── .claude-plugin/       # Claude 清单
├── skills/               # 20 个技能
├── ui/                   # MCP Apps 编辑器
├── commands/open.md      # 打开编辑器命令
├── docs/                 # 架构、回执、宿主支持
└── assets/               # 图标与静态资源

深入文档

• 架构
• 任务回执
• 编辑器集成
• 宿主支持

贡献与支持

提交问题前请附上：插件版本、宿主、操作系统、输入类型、命令、回执和预期结果。不要附真实敏感文档。

许可证

Apache-2.0，见 LICENSE。