前言¶
在 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
