前言¶
在 DeepSeek Harness（DSH）裏讓智能體讀 PDF、Word、Excel 或掃描件，常見做法是接遠程文檔轉換服務、起 Docker 容器，或把文件上傳到帶 API Key 的雲端 OCR。這些路徑要麼依賴網絡與額外部署，要麼會把文檔送出本機。
dsh-doc（GitHub 倉庫 Sqhao-O/dsh-docs）走另一條路：在 DSH 進程內用本地引擎解析文檔，Windows x64 上還可掛載預構建的離線 Python + Xberg 運行時，配合本地 Tesseract 語言包做 OCR。不需要 Docker、HTTP 服務或 API Key，文檔不離開磁盤。
下面介紹插件定位、能力邊界、安裝步驟與典型用法。事實均來自項目 README、package.json 與 SkillHub 目錄頁。
這是什麼¶
dsh-doc 是維護者 Sqhao-O 發佈的 DSH 插件，npm 包名與插件 id 均爲 dsh-doc（工具前綴 dshdoc_*；早期曾用 dsh-docling / docling_* 命名，現已更名）。SkillHub 分類爲「模型推理」，倉庫約 12 stars，許可證 MIT，當前發佈版本 0.1.1。
一句話定位：給 DSH 智能體提供全本地的文檔智能能力——把 PDF、Office、圖片或掃描件解析爲 Markdown、純文本或結構化 JSON，供後續推理與問答使用。
核心功能¶
支持的輸入格式¶
README 列明並已通過集成測試驗證的格式包括：
- 文檔：PDF、DOCX、XLSX、PPTX、Markdown、HTML、CSV 及純文本
- 圖片與掃描件：PNG、JPEG、TIFF、WebP，以及需 OCR 的掃描版 PDF
其他 Xberg 支持的格式可在自有語料上自行驗證後再用於生產。
輸出形態¶
轉換結果可爲 Markdown、純文本，或 JSON 結構的 Tool Result。page_range 對 Markdown/純文本按從 1 開始的頁碼做區間截取；JSON 輸出保留完整結構化文檔。
雙引擎架構¶
| 平臺 | 推薦引擎 | OCR |
|---|---|---|
| Windows x64 | engine: python，指向預構建 runtime |
默認開啓（defaultOcr: true），內置英文與簡體中文 Tesseract 數據 |
| 其他平臺 | engine: node（Xberg Node 綁定） |
默認關閉；若需 OCR 須本地配置 tessdataPath，缺語言包返回 ENGINE_OCR_UNAVAILABLE，不會自動下載模型 |
Windows 預構建運行時包含 CPython 3.11.9、xberg==1.0.14 及固定的 eng / chi_sim 語言包；下載與解壓均做 SHA-256 校驗。Python worker 僅通過 stdio 接收文件字節快照、顯示名、MIME 與轉換選項，不接收用戶路徑或 URL，離線運行且禁用文檔派生 OCR 緩存。
提供的工具¶
| 工具 | 用途 |
|---|---|
dshdoc_health |
檢查當前所選本地引擎是否就緒 |
dshdoc_extract |
解析本地文件的便捷入口（推薦） |
dshdoc_convert_file |
解析白名單內的本地文件 |
dshdoc_convert_url |
兼容樁，對 HTTP(S) 輸入返回 UNSUPPORTED_URL |
插件檢測到 URL 輸入會直接拒絕，避免把遠程地址轉發給 Xberg 或 Python。遠程文檔須先下載到允許讀取的本地目錄，再調用本地解析工具。
路徑與權限¶
會話工作區默認可讀。若需訪問工作區以外的持久目錄（例如共享文檔庫），在 cordis.patch.yml 中配置 allowedLocalRoots。相對路徑相對於 DSH 會話工作區解析，而非 dsh web 啓動時的 shell 目錄。
安裝與啓用¶
前置條件：本機已安裝可用的 dsh CLI，Node 版本爲 ^22.19 或 >= 24。
1. 安裝插件包¶
在目標 profile（以下以 web 爲例）安裝已發佈的 npm 包：
dsh plugin --profile web add dsh-doc
2. Windows x64：下載離線 OCR 運行時¶
將預構建運行時放到 node_modules 之外，避免插件升級時刪除：
node <home>/.dsh/profiles/web/node_modules/dsh-doc/scripts/fetch-runtime-win32-x64.mjs <home>/.dsh/runtimes/dshdoc-runtime-win32-x64
將 <home> 替換爲本機用戶主目錄的絕對路徑。腳本會校驗壓縮包 SHA-256，並對解壓文件做 manifest 校驗。非 Windows x64 平臺跳過此步，後續使用 engine: node。
3. 編輯 profile 配置¶
在 <home>/.dsh/profiles/web/cordis.patch.yml 中保留已有條目，新增或更新：
Windows x64（完整 OCR 能力）：
- id: dsh-doc
config:
engine: python
runtimeDir: <home>/.dsh/runtimes/dshdoc-runtime-win32-x64
maxFileBytes: 52428800
maxOutputChars: 32000
defaultOcr: true
defaultTableMode: accurate
defaultOutputFormat: md
其他平臺（Node 回退，無默認 OCR）：
- id: dsh-doc
config:
engine: node
defaultOcr: false
maxOutputChars: 32000
4. 驗證並重啓¶
確認配置已生效：
dsh --profile web --dump-config
檢查輸出中 dsh-doc 條目是否攜帶預期 config。重啓 dsh web 後，調用 dshdoc_health 確認引擎狀態。
README 還提供一段「一鍵安裝」提示詞，可粘貼到運行中的 DSH 會話，由智能體在終端完成上述步驟；詳見倉庫 INSTALL.md。
典型用法¶
安裝完成並重啓 dsh web 後，可在會話中讓智能體讀取工作區內的本地文件，例如：
Read ./reports/annual-report.pdf and give me the three main risks.
Extract the tables from ./financials.xlsx.
Read the text from ./scanned-invoice.png.
也可在工具層直接調用 dshdoc_extract 解析指定路徑。僅工作區或 allowedLocalRoots 下的路徑可讀。
適用場景與注意¶
適合誰
- 需要在 DSH 工作流中處理合同、報表、幻燈片、掃描發票等本地文檔，且希望數據不出本機的開發者
- Windows x64 用戶需要開箱即用的離線 OCR（中英）時，優先使用 Python 引擎路徑
- 不願維護 Docling Serve、Docker 或遠程文檔 API 的團隊
使用注意
- 插件以當前
dsh進程的權限運行，安裝前應審閱 源碼 與 MIT 許可證。 - 不要將 Docling Serve、Docker 容器或可下載 OCR 後端接入此插件；項目明確禁止這類遠程或自動拉取模型的配置。
- 非 Windows 平臺默認無離線 OCR；若業務強依賴掃描件識別，應在 Windows x64 上部署 Python 運行時，或自行準備經審查的本地
tessdataPath。 - 單文件大小受
maxFileBytes（默認 52428800 字節）與maxOutputChars（示例配置 32000）限制，超大文檔需分段或調高配置。 - SkillHub 目錄頁（skillhub.cn/plugins/Sqhao-O/dsh-docs）爲社區收錄站點，與 DeepSeek / 幻方無官方從屬關係；安裝命令以 README 與 npm 包
dsh-doc爲準。
結尾¶
dsh-doc 把 PDF、Office、圖片與掃描件的解析收攏到 DSH 插件內，在 Windows x64 上提供完整的離線 OCR 路徑，在其他平臺上以 Node 引擎覆蓋非 OCR 解析需求。若你的智能體需要「讀本地文檔再推理」，可按上文步驟安裝並先用 dshdoc_health 確認環境。
- SkillHub 目錄：https://www.skillhub.cn/plugins/Sqhao-O/dsh-docs
- GitHub 倉庫：https://github.com/Sqhao-O/dsh-docs
