前言¶

把一份年報 PDF、一張掃描發票或一份 Excel 丟給智能體，最常見的做法是先上傳到雲端解析服務，再把文本貼回對話。這條鏈路能用，但合同、財報、內部掃描件一旦離開本機，權限邊界就不好收。純文本模型也讀不了二進制文檔：沒有本地解析，agent 只能看到文件名。

DeepSeek Harness（dsh）是 DeepSeek AI 開源的智能體框架，官方口號是「一切皆插件」：模型、工具、會話、沙箱和界面都可以在配置層增刪，不必改核心源碼。社區因此出現了一批只做一件事的插件。dsh-docs 做的就是文檔這一側——在本機把 PDF、Office、圖片和掃描件轉成 Markdown、純文本或結構化 JSON，離線 OCR，不走 HTTP 服務，也不要 API Key。

本文按社區插件目錄頁、GitHub 倉庫 README / README.zh-CN.md / INSTALL.md / package.json，以及官方 deepseek-ai/deepseek-harness 交叉覈對後整理。社區插件目錄 deepseek-harness-plugin.com 是獨立站點，與 DeepSeek / 幻方沒有官方從屬關係，不能當成官方應用商店。Harness 目前仍是開發者預覽，插件可能隨核心升級出現不兼容變更。

這是什麼¶

dsh-docs 是一款面向 DeepSeek Harness 的文檔智能插件，由 GitHub 用戶 Sqhao-O 維護，倉庫許可證爲 MIT，主要語言是 TypeScript。社區目錄把它歸在「記憶」分類：它並不做跨會話知識圖譜，而是把本地文檔解析成模型能讀的文本，相當於給 agent 補上一塊可讀的文件記憶。

有幾個名字需要先分清，避免裝錯包：

• GitHub 倉庫名是 dsh-docs。
• 發佈到 npm 的包名、插件 id 是 dsh-doc（沒有末尾的 s）。
• 工具名統一爲 dshdoc_*。
• 初版曾用 dsh-docling / docling_*，現已更名。

package.json 當前版本是 0.1.1。截至 2026-08-18，GitHub API 顯示該倉庫 9 星；社區目錄頁同期展示爲 6 星，以下以 GitHub 一手數據爲準。運行前置是可用的 dsh CLI，Node 版本要求爲 ^22.19 或 >= 24。

它要解決的問題很具體：把 PDF、Word、Excel、PowerPoint 交給本機引擎，拿回乾淨文本；把掃描件或圖片交給離線 Tesseract，讀出其中的字。倉庫明確寫了「無需 Docker、無需 HTTP 服務、無需 API Key，文檔永不離開你的磁盤」。

核心功能¶

倉庫 README 列出的已覆蓋輸入如下。集成測試會在臨時目錄生成 PDF、DOCX、XLSX、PPTX、PNG 與掃描 PDF 並走真實解析；其他 Xberg 支持的格式，作者建議用自己的語料先驗證再上生產。

1. 辦公與文本文件：PDF、DOCX、XLSX、PPTX、Markdown、HTML、CSV、純文本。
2. 圖片與掃描件：PNG、JPEG、TIFF、WebP，以及掃描 PDF，走本地 OCR。
3. 三種輸出：返回給模型的 Markdown、純文本，或 JSON 結構化 Tool Result。默認輸出格式是 md。

解析引擎分兩條路徑，這一點對能不能開 OCR 很關鍵：

• Windows x64 完整路徑：隨包提供固定版本、自包含的 Python + Xberg 運行時。預構建產物含 CPython 3.11.9、xberg==1.0.14，以及固定的 eng / chi_sim Tesseract 語言包。下載會做 SHA-256 校驗，並帶 manifest、NOTICE、SPDX 清單，不改動全局 Python。這是倉庫寫明的「完整離線 OCR」路徑。
• 任意平臺的 Node 回退：原生 Xberg Node 綁定，用來做 PDF / Office / 文本解析。defaultOcr 默認爲 false。若要在 Node 引擎上開 OCR，必須把 tessdataPath 指到已經審覈過、含全部所需 .traineddata 的本地目錄；缺少語言包會返回 ENGINE_OCR_UNAVAILABLE，不會去下載模型。

對外工具一共四個：

HTTP(S) 輸入只會被識別並拒絕。若要解析遠程文檔，需要先用已審覈的下載流程存到允許目錄，再調用本插件。插件不會把 URL 交給 Xberg 或 Python worker，避免重定向和 DNS 重綁定。

轉換時還可以帶這些選項：

• page_range：從 1 開始、兩端包含的頁碼，適用於 Markdown 和純文本；JSON 輸出會刻意保留完整結構化文檔。
• ocr_languages：按請求覆蓋語言集，例如 ["chi_sim", "eng"]。
• 引擎上報時，結果會標註 OCR: applied / OCR: not used。開啓 OCR 不會覆蓋 PDF 裏完好的內嵌文本層。

安全邊界也寫在 README 裏，不是口號：路徑會 realpath 後比對白名單根目錄和會話工作區，阻斷 ..、符號鏈接逃逸、根目錄、非文件和超大文件；授權後立刻讀一次字節快照，解析用的是快照而不是之後可能被替換的路徑；Node 與 Python 引擎都只收 bytes，不創建監聽端口、URL 下載器、容器或外部解析服務。默認輸入上限 maxFileBytes 爲 52428800（50 MiB），返回給模型的上限 maxOutputChars 爲 32000。

安裝與啓用¶

社區目錄頁給出的安裝命令如下，以頁面原文爲準：

dsh plugin add github:Sqhao-O/dsh-docs

如需可復現安裝，目錄頁建議固定 commit 哈希：

dsh plugin add github:Sqhao-O/dsh-docs#commit

把 #commit 換成實際提交哈希。目錄頁同時提醒：插件以當前 dsh 進程的權限運行，安裝時可能執行代碼；安裝前應檢查源代碼倉庫和許可證。

倉庫 INSTALL.md 寫得更細。dsh web 始終使用 web profile，裝到 default 再開網頁界面是看不到的。作者推薦的發佈包裝法是：

dsh plugin --profile web add dsh-doc

僅 Windows x64 需要再拉一份預構建離線 OCR 運行時，放到 node_modules 之外的穩定目錄，避免插件升級時被刪掉。YAML 裏的路徑要寫成絕對路徑，不要依賴 ~：

node $HOME/.dsh/profiles/web/node_modules/dsh-doc/scripts/fetch-runtime-win32-x64.mjs $HOME/.dsh/runtimes/dshdoc-runtime-win32-x64

然後在該 profile 的 cordis.patch.yml 裏新增或更新這一條，保留已有條目：

- id: dsh-doc
  config:
    engine: python
    runtimeDir: $HOME/.dsh/runtimes/dshdoc-runtime-win32-x64
    defaultOcr: true
    maxOutputChars: 32000

把 $HOME 換成你的主目錄絕對路徑。會話工作區默認可讀，不必先配 allowedLocalRoots；這個字段只用於工作區之外的共享文檔庫等持久目錄。allowWorkspaceFiles: false 則回到純白名單鎖定。

其他平臺跳過運行時下載，改用：

- id: dsh-doc
  config:
    engine: node
    defaultOcr: false
    maxOutputChars: 32000

裝完後用下面這條覈對合成配置，再重啓 dsh web：

dsh --profile web --dump-config

INSTALL.md 提醒：dump 配置時 DSH 可能改寫 profile 層，正式配置最好納入版本控制，或先備份。重啓之後先讓 agent 調用 dshdoc_health，再解析工作區下的文件。

倉庫還提供一段可直接貼進 dsh web 會話的安裝提示詞，由 agent 在終端裏逐步完成安裝、拉運行時、改 YAML 並驗證。硬性約束寫得很清楚：不要安裝、啓動或配置 Docling Serve、Docker、容器或任何遠程文檔轉換服務；不要配置可下載的 OCR 後端，也不允許解析時下載模型。舊 profile 裏的 baseUrl、apiKey、enableRemoteUrls、allowPrivateUrls 僅爲遷移兼容而接受，不能重新開啓遠程解析。

典型用法¶

重啓 dsh web 後，相對路徑按 DSH 會話工作目錄 解析，不是你啓動 dsh web 時所在的那個目錄。只有會話工作目錄或 allowedLocalRoots 下的文件可讀。倉庫給出的自然語言示例是：

閱讀 ./reports/annual-report.pdf，列出三個主要風險。
提取 ./financials.xlsx 的表格。
讀取 ./scanned-invoice.png 的文字。

更穩妥的順序是：先讓 agent 跑 dshdoc_health，確認當前引擎和 OCR 語言包就緒，再用 dshdoc_extract 解析具體文件。完整 OCR 配置示例（Windows x64）還可以帶上表格模式和輸出格式：

- id: dsh-doc
  config:
    engine: python
    runtimeDir: /absolute/path/to/dshdoc-runtime-win32-x64
    maxFileBytes: 52428800
    maxOutputChars: 32000
    defaultOcr: true
    defaultTableMode: accurate
    defaultOutputFormat: md

engine 默認爲 auto：已配置內嵌 Python 運行時就走 Python，否則走 Node Xberg。defaultOcr 默認是 false，只應在已經配好本地 tessdata 時打開。defaultTableMode 可選 fast 或 accurate。timeoutMs 默認 120000。

如果要把運行時拷到另一臺 Windows 機器，倉庫要求先跑：

node ./scripts/verify-runtime-win32-x64.mjs

校驗 payload 哈希後再把 runtimeDir 指過去。從源碼審計並重建運行時則用 node ./scripts/build-runtime-win32-x64.mjs，產物默認落在 Git 忽略的 .dsh-runtime/runtime-win32-x64。

Python worker 只經 stdio 接收文件字節快照、顯示名稱、MIME 和選項，不接收用戶路徑或 URL；缺少 OCR 語言包會安全失敗，並禁用文檔派生的 OCR 緩存。

適用場景與注意事項¶

比較適合這幾類用法：

• 本機已經有 PDF / Office 資料，希望 dsh web 直接讀，而不是先手動轉文本。
• 掃描件、拍照發票、截圖裏的字需要進對話，但不想走雲端 OCR。
• Windows x64 環境，願意下載一份固定哈希的離線運行時，換完整的 PDF / Office / OCR 覆蓋。
• Linux / macOS 上主要解析帶文本層的 PDF 和 Office，可以接受 Node 回退、默認關閉 OCR。

使用前有幾條邊界需要看清：

1. 權限與來源。插件以當前 dsh 進程的權限運行，安裝時可能執行構建腳本。裝之前應閱讀 Sqhao-O/dsh-docs 源碼和 MIT 許可證；需要可復現安裝時固定 commit。
2. 平臺差異。完整離線 OCR 目前按倉庫說明針對 Windows x64 預構建；其他平臺的默認路徑是 Node 引擎且 defaultOcr: false。不要默認「裝上就能識別掃描件」。
3. 可讀範圍。相對路徑相對會話工作區，不是啓動目錄。工作區之外的目錄必須寫進 allowedLocalRoots。
4. 分類名容易誤會。目錄把它放在「記憶」，它解決的是本地文檔可讀，不是 graph-memory 那類跨會話經驗庫。同生態裏還有一個 dsh-docs-panel，做的是 Web UI 裏讀 Markdown 筆記面板，和本插件不是一回事。
5. 遠程文檔。dshdoc_convert_url 會拒絕 URL。先下載到允許目錄再解析。
6. 結果長度。返回給模型的文本默認截到 32000 字符；JSON 限長時用的是模型真正看到的格式化文本。超長年報可能需要 page_range 分段。
7. 運行時位置。OCR 運行時不要放在 node_modules 裏，插件升級會把它清掉。
8. 版本仍早。當前 npm 版本是 0.1.1，測試覆蓋了常見辦公格式和掃描 PDF；倉庫仍建議對未列入測試的格式先用自己的語料驗證。

小結¶

dsh-docs 給 DeepSeek Harness 補的是本機文檔入口：PDF、Office、圖片和掃描件在授權目錄內解析，Windows x64 可以走固定哈希的離線 Python / Tesseract 運行時，其他平臺還能用 Node Xberg 做非 OCR 回退。社區目錄安裝命令是 dsh plugin add github:Sqhao-O/dsh-docs；日常在 dsh web 裏使用時，倉庫更推薦 dsh plugin --profile web add dsh-doc，並按平臺決定要不要拉 OCR 運行時。

目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-docs/

GitHub：https://github.com/Sqhao-O/dsh-docs