前言¶

在 DeepSeek Harness（DSH）里让智能体处理 PDF，常见需求是合并报告、按页拆分、打水印、读元数据或导出文本层——若每次都走外部 SaaS 或手写脚本，既要配 API、又要考虑文件上传与权限。社区插件 dsh-pdf-toolbox（维护者 glentao-dev）把这类操作注册为 DSH 工具：9 个工具覆盖 14 项操作，依赖 pdf-lib 做结构改写、pdfjs-dist 读文本层，全程在本机进程内完成，无 API key、无上传、无 token 成本。下面介绍它的定位、安装方式与用法边界。

这是什么¶

dsh-pdf-toolbox 是面向 DSH 的 PDF 结构操作插件：合并、拆分、压缩、加水印、页面的提取/删除/旋转/插入、元数据读写、加密检测、文本提取与文档信息概览。它不负责 PDF 转 Office/图片（那是 dsh-file-convert 的职责），也不做 OCR（扫描件需先用如 dsh-pdf-extractor 等工具得到文字层后再处理）。插件以 MIT 许可证发布，当前 package 版本为 1.0.0，要求 Node ^22.19.0 || >=24.0.0。

核心功能¶

README 将能力归纳为 9 个工具；页码相关参数统一为 从 1 开始，逗号分隔，支持区间，或用 all 表示全部页（与留空等价），例如 1-3,5,8-10。

安装与启用¶

在档案中安装（命令来自项目 README，勿自行拼接 github:owner/repo 形式）：

dsh plugin --profile <你的档案> add dsh-pdf-toolbox

本地开发或未发布到目录时，可用 file: 路径添加，例如：

dsh plugin --profile <你的档案> add "file:D:/软件/自制软件/PDF 工具新版本"

卸载：

dsh plugin --profile <你的档案> remove dsh-pdf-toolbox

dsh plugin 会写入 $DSH_HOME/profiles/<档案>/package.json。若出现 EPERM: operation not permitted，说明当前沙箱只允许写工作区，需要在允许写 ~/.dsh 的模式下重跑。

可选配置写在档案的 cordis.patch.yml 中，按插件 id 覆盖：

- id: dsh-pdf-toolbox
  config:
    timeoutMs: 600000        # 单个操作超时（大文件合并/超大文档时调大）
    maxInputMb: 1024         # 输入大小上限
    overwrite: true          # 允许覆盖已存在输出
    watermarkOpacity: 0.25   # 水印不透明度
    watermarkRotate: 45      # 水印角度

常用配置项默认值（摘自 README）：timeoutMs 180000、maxInputMb 1024、maxPages 2000、outputRoots 空数组（不限制显式输出目录）、overwrite false、watermarkFont Helvetica-Bold、watermarkOpacity 0.3、watermarkRotate 45。

典型用法¶

智能体或你在 DSH 中调用工具时，参数为 JSON 形态；README 给出了可对照的自然语言场景。

合并两个 PDF 到指定绝对路径：

pdf_merge { files: ["D:\\reports\\a.pdf", "D:\\reports\\b.pdf"], output: "D:\\out\\merged.pdf" }

只合并每个输入文件的第 1–5 页（pages 会应用到每个输入文件）：

pdf_merge { files: ["D:\\reports\\a.pdf", "D:\\reports\\b.pdf"], pages: "1-5" }

每 10 页拆成一个文件：

pdf_split { input: "D:\\r\\report.pdf", every: 10, outputDir: "D:\\out" }

仅第 1 页打水印：

pdf_watermark { input: "D:\\c\\合同.pdf", text: "CONFIDENTIAL", pages: "1" }

提取、删除页面：

pdf_pages { input: "D:\\s\\scan.pdf", action: "extract", pages: "2-4", output: "D:\\out\\ex.pdf" }
pdf_pages { input: "D:\\b\\book.pdf", action: "delete", pages: "1" }

读元数据、导出全文文本：

pdf_metadata { input: "D:\\m\\meta.pdf", action: "read" }
pdf_text { input: "D:\\r\\report.pdf", output: "D:\\out\\report.txt" }

输出路径规则（调用前建议记牢）：

• 未给 output 时，默认写在输入文件旁，文件名加动作后缀（如 a-merged.pdf）。
• 给了 output 时必须是绝对路径；相对路径会报错。
• 已存在的输出文件默认拒绝覆盖，需配置 overwrite: true 或先删除旧文件。
• outputRoots 可将显式输出限制在指定目录内；默认输入旁边不受限。

适用场景与注意¶

适合谁：需要在 DSH 工作流里做 PDF 页级编排、轻量压缩、水印、元数据与文本层导出，且希望数据不出本机的开发者或团队。

权限与安全：插件以当前 DSH 进程的文件系统权限运行；安装前应在 GitHub 阅读源码与 MIT 许可证，确认路径与 outputRoots 策略符合你的环境。社区目录 SkillHub 插件页 与 DeepSeek / 幻方无官方从属关系，属于社区生态「一切皆插件」的一部分。

已知边界（README 明确列出，插件不会伪造结果）：

1. 中文水印：pdf-lib 标准 14 字体仅 ASCII；传中文会退化为 WATERMARK 并在结果中说明。中文水印需外部字体嵌入，暂未实现。
2. 设置打开密码：pdf-lib 1.x 不能写 /Encrypt；pdf_encrypt 仅检测与输出无保护副本，真正加密可用本机 qpdf 或 Ghostscript。
3. 解密：不支持用密码解密内容，只能重排输出。
4. 格式转换与 OCR：见上文与 dsh-file-convert、dsh-pdf-extractor 的分工。

删除页前可用 pdf_info 查看总页数；不支持负数页码。

结尾¶

dsh-pdf-toolbox 把合并、拆分、压缩、水印、页操作、元数据、加密检测和文本提取收进同一 DSH 插件，本地 pdf-lib + pdfjs-dist 实现，适合作为智能体工具链里的 PDF 结构层。进一步了解可访问社区目录页 glentao-dev/dsh-pdf-toolbox 与源码仓库 github.com/glentao-dev/dsh-pdf-toolbox。