用 PaperPilot 给 Agent 装一套纯本地 PDF 工具箱：MCP、命令行与本机 REST 三条路

从 GitHub 发布页下载对应平台的可执行文件，放到 PATH 里即可；想自己编译则克隆仓库后构建命令行、MCP 与网关三个 crate。源码构建要求 Rust 1.75 及以上，桌面应用另需 Node.js 与 pnpm。它刻意不依赖 Chromium、不依赖 C++ 运行时、也不发起云端调用，底层用的是 lopdf、pdf_oxide 与 rten 这些 Rust crate。

# 方式一：从发布页下载对应平台的二进制，放入 PATH

# 方式二：源码构建（需要 Rust 1.75+，桌面应用另需 Node.js 与 pnpm）
git clone https://github.com/KrushnaVardhanReddy/PaperPilot.git
cd PaperPilot
cargo build --release -p paperpilot-cli -p paperpilot-mcp -p paperpilot-gateway

这里有一件必须先做的事：认准仓库所有者。同名的仓库不止一个，其中一个是用 TypeScript 写的同名项目，代码完全不同。另外各聚合站给出的星数与文件数口径也不一致，README 本身没有标注版本号，只写了当前功能线是 v0.6。这些都不影响使用，但会影响你判断它的成熟度——把它当成一个正在快速演进的年轻项目来对待，比当成一件基础设施要稳妥。

接客户端这一步它做得比多数 MCP 服务省事：从源码构建出的 MCP 二进制可以直接打印出针对某个客户端的、可合并的配置片段，支持 codex、claude-code、kimi-code、pi、claude-desktop 与 cursor 等；仓库里还有一份面向各编码 Agent 的配置与验证说明。手工写法则是把二进制路径填进客户端配置的 mcpServers 里，重启后就能用。

# 打印针对某个客户端的现成配置
paperpilot-mcp --client-config codex
# 另有：claude-code, kimi-code, pi, claude-desktop, cursor

# 手工写法（claude_desktop_config.json）
{
  "mcpServers": {
    "paperpilot": {
      "command": "/path/to/paperpilot-mcp"
    }
  }
}

重启客户端之后，用一句自然语言验证它真的挂上了，比如「把这两个 PDF 合并并压缩结果」。README 没有把 MCP 暴露的工具名逐条列出来，具体名称以你客户端里列出的工具清单为准，因此这里更可靠的验证方式是先跑一句自然语言，看它选的工具是否与命令行子命令一一对应。这一点也解释了它的设计意图：五种形态共用一套 Rust 内核，行为应当一致，所以命令行里跑通的操作，在 MCP 里应当得到同样结果。

凡是「一批文件做同一件事」的场景，命令行比 MCP 更合适：它可以进脚本、进 CI，也能被 Agent 自己写成循环调用。常用三条是合并、压缩与旋转，参数名都很直白——输入、输出，加上各自的选项。

# 合并
paperpilot merge --inputs doc1.pdf doc2.pdf --output merged.pdf

# 压缩（quality 越低体积越小）
paperpilot compress --input in.pdf --quality 75 --output compressed.pdf

# 旋转：把第 1、3 到 5 页旋转 90 度
paperpilot rotate --input in.pdf --pages 1,3-5 --angle 90 --output out.pdf

v0.6 这一版能做的事可以分成五组：整理（合并、拆分、旋转、删页、重排、抽取页面、书帖拼版、N-up 拼版）、优化（压缩）、抽取（纯文本，以及经 rten 跑的纯 Rust PaddleOCR 做 OCR）、安全（水印、验签、去签、PII 扫描、深度脱敏）、以及办公数据（Excel 转 JSON 与 CSV）。先把这批命令在 Shell 里跑一遍并核对产物，再交给 Agent 去组合，排查成本会低很多。

如果你的自动化跑在 n8n、Python 或 Node 里，起一个本地网关更顺手：服务监听 7823 端口，合并接口接受一个 JSON，文档在 /docs。它走的是本机的 Axum 服务，文件不出机器，因此适合那种「扫描件进来、压缩后的 PDF 出去、再交给下游」的固定管线。

# 起服务
paperpilot serve --port 7823

# 调一次合并
curl -X POST http://localhost:7823/api/v1/pdf/merge \
  -H "Content-Type: application/json" \
  -d '{"inputs": ["a.pdf", "b.pdf"], "output": "out.pdf"}'

# 接口文档
# http://localhost:7823/docs

把它接进流水线时有两条实用经验。一条是输出路径要写绝对路径或者相对于服务进程工作目录的路径，否则你会遇到「明明成功了却找不到文件」。另一条是把它当成本地服务来管：不要把它暴露到局域网以外，README 没有描述认证机制，默认的定位就是本机调用；真要给团队共用，请自己在前面加一层反向代理与鉴权。

真正让这个工具值得单独写一篇的，是安全那一组：PII 扫描与深度脱敏。处理合同、病历、报销单据这类文件时的正确顺序是——先在本地扫描出个人身份信息，再做深度脱敏，之后才把结果交给模型或上传到任何别的地方。顺序反了，信息已经出去了，脱敏再彻底也没有意义。

处理敏感 PDF 的推荐顺序

1) PII scan        扫出身份证号、手机号、账号等个人身份信息
2) deep sanitize   深度脱敏：清掉元数据、隐藏内容与残留对象
3) 校验结果        再扫一遍，并抽取纯文本确认没有残留
4) 才交给模型      此时即使上下文被记录，也不含原始个人信息

安全组其余能力：水印、验签、去签

还有一件事值得在验收时亲自确认：README 给出的自证方法是打开浏览器开发者工具的网络面板，在网页版里处理一份文件，看有没有文件字节被上传。这个方法很朴素，但正因为朴素才可信——它验证的是处理路径，而不是承诺。同样的判断适用于任何「本地优先」的同类工具。

把它放进方案之前，把「还不能做」的部分一起写进去，这样才不会在演示之后才发现缺了关键一步。按 ROADMAP，PDF 与 Markdown、HTML、JSON 的互转排在 v0.7；转 Word、Excel、PowerPoint 在 v0.8；加密、解密、签名、涂黑、表单与批注在 v0.9；渲染、展平、修复、比对、PDF/A 与 Bates 编号要到 v1.0。也就是说，眼下它擅长页面级操作与压缩、抽取、脱敏，还不擅长格式转换与渲染。

v0.6 已有                     v0.7 及以后（尚未提供）
整理：合并/拆分/旋转/删页/     v0.7  PDF 与 Markdown / HTML / JSON 互转
      重排/抽页/拼版/ N-up     v0.8  转 Word / Excel / PowerPoint
优化：压缩                     v0.9  加密/解密/签名/涂黑/表单/批注
抽取：纯文本 + OCR             v1.0  渲染/展平/修复/比对/PDF-A/Bates
安全：水印/验签/去签/PII/脱敏
办公：Excel 转 JSON / CSV

最后是性能预期。仓库提供了基准脚本与报告入口，但 README 正文没有给出数字；第三方站点引用过一份作者自测，称 22 个工具在 WASM 里平均约 65 毫秒，样本是合成的小文件，并且提到其中一些工具按路线图要到后续版本才有——这类自测数字请当作调度开销的参考，不要当成大文件扫描的耗时。企业版（SSO、权限、审计、DLP）是另一个单独开发的产品，与这个 Apache-2.0 的社区版不是一回事。