前言¶
在 DeepSeek Harness (DSH) 生态中，处理本地文档通常面临隐私顾虑或网络请求的复杂性。下面介绍一个由 ralfsqual 维护的插件，它通过纯本地解析的方式，为 Agent 增加了 read_pdf 工具，解决了在不经过网络的情况下直接读取本地 PDF 文本的需求。
什么是 dsh-pdf-reader¶
这是一个 DeepSeek Harness 插件，核心功能是注册 read_pdf 工具，利用 pdfjs-dist 库逐页提取 PDF 文本。该工具完全在本地运行，不涉及文件上传或网络请求，路径严格限定在当前工作区。
核心功能¶
- 本地 PDF 文本提取
- 逐页解析（使用
--- page N ---分隔符） - 无上传、无网络请求
- 路径限定工作区
安装与启用¶
通过官方命令安装：
dsh plugin --profile web add github:ralfsqual/dsh-pdf-reader
或者从本地安装：
dsh plugin --profile web add /path/to/dsh-pdf-reader
安装后需重启 dsh web，新会话中 Agent 即可调用该工具。
工具参数¶
path(string): PDF 路径，支持相对当前工作目录或工作区内的绝对路径。maxPages(number): 最多提取页数，默认为500，设为0表示无限制。maxChars(number): 最多返回字符数，默认为120000。
典型用法¶
Agent 在接收到指令后调用工具，示例：
Read @docs/spec.pdf and summarize the requirements.
读取 @docs/report.pdf 并总结要点。
工作原理与安全¶
该工具通过 defineTool 注册，底层使用 pdfjs-dist (版本 2.6.347) 进行解析。解析结果为包含 pages、extractedPages、truncated、empty、text 的结构化对象。
安全方面，它严格遵循以下限制：
- 只读与本地：仅读取文件，绝不写入或执行命令；解析在主机完成，无网络请求。
- 路径隔离：path 必须在工作区路径内，防止越界访问（如 ../ 会被拒绝）。
环境要求与已知限制¶
环境要求：
- 需要运行 DeepSeek Harness 的 web（或具备 Agent 能力）Profile。
- Node.js 版本需 >= 22.19。
已知限制：
- 仅提取文本层，扫描件或图片 PDF 无法提取（需 OCR）。
- 与 @ 插件合用时，path 不能以 @ 开头。
- 大文件受 maxPages 和 maxChars 限制，输出会被截断。
参考资料¶
- GitHub: https://github.com/ralfsqual/dsh-pdf-reader
- 生态目录: https://www.skillhub.cn/plugins/ralfsqual/dsh-pdf-reader
