前言¶
在 DeepSeek Harness（DSH）裏處理 PDF，常見做法是整份丟給模型或自己寫腳本調 Poppler。前者難以精確到頁碼和掃描頁，後者又要維護工具鏈和對話裏的引用格式。dsh-pdf-reader 是面向 DSH Desktop 的獨立 Harness 插件：不改桌面殼、不拉 npm 運行時依賴、不做後臺索引或自動下載模型，通過官方工具註冊表把「按頁閱讀、檢索、局部 OCR、整頁或裁剪圖附件」接到智能體工作流裏。下面介紹它的定位、能力與安裝用法。
這是什麼¶
dsh-pdf-reader（GitHub：SkanderBog/dsh-pdf-reader，維護者 SkanderBog）是 Harness 宿主插件（pluginType: feature），當前發佈版本 0.1.4（MIT）。它利用 Harness 的文件系統、系統提示與附件服務，在本地調用 Poppler 與可選的 Tesseract，實現頁級 PDF 閱讀、字面量搜索、掃描頁選擇性 OCR，以及把整頁或放大裁剪區域作爲真實 Harness 圖像附件交給對話。
DeepSeek 官網聊天應用/網站是另一套產品，不會加載此類 Harness 插件；需在帶插件機制的 DSH Desktop 或對應 CLI profile 上使用。
核心工具¶
插件向智能體暴露五類工具（名稱以 README 爲準）：
| 工具 | 作用 |
|---|---|
pdf_status |
檢查 Poppler、Tesseract 及已安裝的 OCR 語言包是否可用。 |
pdf_inspect |
頁數、各頁是否有可選中文本、掃描頁警告與覆蓋率。 |
pdf_read |
按頁範圍讀取，保留表格間距，對掃描頁選擇性 OCR，並報告截斷情況。 |
pdf_search |
在嵌入文本中做字面量搜索，返回頁引用，並標明掃描覆蓋缺口。 |
pdf_render |
將整頁或放大裁剪區域作爲 Harness 圖像附件輸出。 |
插件還會在 system prompt 里加入一段簡短的 PDF 閱讀工作流說明。當前 Agent 預設必須允許這些工具；若受限預設隱藏了插件工具，需換用允許 plugin tools 的預設。
環境與兼容¶
運行時要求（來自 package.json / README）：
- Node 22.19+ 或 24+
- DeepSeek Harness ≥ 0.2.0-rc.2，或在 manifest 中聲明的
0.2.1-alpha.1/0.2.1-alpha.2/0.2.1-rc.2
已文檔化的驗證情況（非窮盡）：
- Linux 上 DSH Tauri Desktop + Harness
0.2.0-rc.2：維護者稱已安裝啓用並通過集成與 OCR 測試。 - macOS 原生插件執行：0.1.1 打包插件在 GitHub Actions（Node 24、Poppler、Tesseract）中通過 22 項集成測試。
- 官方 DeepSeek Harness Desktop 使用相同插件機制；官方源碼在 2026-10-02 審閱時爲
0.2.0-rc.2，在具備所需服務與原生依賴時期望兼容，但 打包版官方桌面 GUI 與 Windows 執行尚未在此項目內完整驗證。
Poppler 與 Tesseract 爲 系統級原生程序，插件不捆綁。GUI 應用的 PATH 可能與終端不同；若 pdf_status 報缺失，可在插件 Cordis config 中爲各二進制配置絕對路徑（README 以 Tesseract 爲例）。Apple Silicon 上 Homebrew 常見路徑爲 /opt/homebrew/bin，Intel Mac 爲 /usr/local/bin。
安裝與啓用¶
分發方式爲 GitHub Release v0.1.4 中的 dsh-pdf-reader-0.1.4.tgz。npm 上未 scoped 的 dsh-pdf-reader 屬於其他作者，應使用本倉庫的歸檔包或 GitHub 源碼安裝。
官方桌面（優先）： 在桌面的 Plugins 頁面安裝該 .tgz 並啓用 dsh-pdf-reader。
若使用官方桌面自帶的 dsh 命令：先啓動桌面一次以初始化 profile，完全退出後執行（路徑改爲本機絕對路徑）：
dsh plugin --profile desktop add /absolute/path/dsh-pdf-reader-0.1.4.tgz
命令結束後重新打開桌面。社區 shell 除非實際擁有 desktop profile，否則不要用 desktop 作 profile 名。若 profile 不支持熱重載，需重啓 Harness core。
命名 CLI profile：
dsh plugin --profile YOUR_PROFILE add /absolute/path/dsh-pdf-reader-0.1.4.tgz
請使用桌面實際運行的 profile 名稱（不一定是 web 或 desktop）。禁用或卸載通過同一插件管理器完成；禁用會移除工具與工作流，內存中的覆蓋信息與臨時工作 PDF 會被丟棄，已生成並進入對話的圖像附件仍由 Harness 管理。
原生依賴安裝¶
Poppler 提供 pdfinfo、pdftotext、pdfimages、pdftoppm；本地 OCR 需要 Tesseract 及對應語言數據，純渲染與可選中文本不強制 Tesseract。
Ubuntu/Debian：
sudo apt install poppler-utils tesseract-ocr tesseract-ocr-eng tesseract-ocr-chi-sim
macOS（CI 中測過原生工具；打包桌面 GUI 未在此驗證）：
brew install poppler tesseract tesseract-lang
Windows 需自備對應架構的可執行文件與 OCR 語言數據；Linux 側的 OCR 封裝不可直接移植。
典型用法¶
正常附件掛上 PDF 後，可按 README 示例向智能體說明意圖（英文提示詞，行爲等價於「先用工具再總結」）：
Use the PDF tools to read this document. Inspect its pages first, OCR scanned pages in English and Chinese, and inspect relevant figures. Explain the findings with PDF page references. Tell me which pages or regions you could not read.
針對表格頁：
Read PDF page 6 with layout preserved, then render a crop of the table and check the numbers against the text. Cite the page.
建議流程：先用 pdf_inspect 瞭解頁結構與掃描情況，再用 pdf_read / pdf_search 取文本並引用頁碼，對圖或表格用 pdf_render 做視覺覈對；無法讀取的頁或區域應在回覆中明確說明。
權限與安全邊界（安裝前須知）¶
插件以 當前 DSH 進程的用戶權限 運行，並非 OS 級沙箱。README 與 Store 兼容性說明中的要點：
- 源 PDF：經 Harness 文件系統服務只讀訪問，每次調用校驗，不修改源文件。
- 本地寫入：私有 OS 臨時目錄中的文檔/OCR 中間文件；渲染圖經宿主附件服務存儲；卸載會清理工作副本，硬崩潰可能遺留 OS 臨時文件。
- 子進程：僅調用 Poppler 與 Tesseract，固定參數、
shell: false，帶取消、超時與輸出上限；管理員配置的絕對路徑二進制需視爲可信。 - 網絡：插件本身不發起直接網絡請求；Harness 可能把返回的文本/圖像發給當前對話所選模型提供商。
- 環境：子進程使用顯式 allowlist 的運行時路徑/字體/OCR 配置，不轉發 API 密鑰、
NODE_OPTIONS、LD_PRELOAD及動態庫搜索路徑覆蓋等。
DSH STORE 在 2026-10-15 的審閱中因原生依賴的獨立驗證等原因，安裝仍可能被攔截；manifest 中的聲明不等於商店批准或獨立安全認證。安裝前應自行審閱源碼與 MIT 許可證，並確認 Poppler/Tesseract 來源可信。
適用場景¶
- 在 DSH Desktop 或 CLI 會話裏分析技術 PDF、合同、掃描件，需要 頁碼引用 與 掃描頁本地 OCR（如英/中）。
- 需要把 表格佈局 與 裁剪圖 一併交給多模態模型覈對，而不是隻粘貼純文本。
- 希望 無 npm 運行時依賴、無後臺索引，依賴本機已安裝的 Poppler/Tesseract。
不太適合：僅使用 DeepSeek 網頁/ App、無法安裝 Harness 插件的環境；尚未驗證的 Windows 或任意 Harness 版本；期望插件自帶 OCR 引擎、無需系統安裝 Tesseract 的場景。
鏈接¶
- 社區目錄頁：https://www.skillhub.cn/plugins/SkanderBog/dsh-pdf-reader
- 源碼與 README：https://github.com/SkanderBog/dsh-pdf-reader
- 當前安裝包：https://github.com/SkanderBog/dsh-pdf-reader/releases/tag/v0.1.4
dsh-pdf-reader 把頁級 PDF 閱讀、搜索、本地 OCR 與可視化裁剪收斂爲一組 Harness 工具，適合在已部署 DSH 且本機具備 Poppler/Tesseract 的開發者與智能體工作流中使用。
