前言¶
DSH（DeepSeek Harness）採用「一切皆插件」的架構，擴展能力通過插件實現。在構建基於文檔的知識庫或研究工作流時，開發者需要處理文件檢索、內容搜索、元數據查詢、批量上傳、格式轉換等重複性工作。手工編寫這些功能耗時且容易出錯。wct-lab/dsh-docchain 是一個面向 DSH 的文檔檢索與轉換插件，它將常見的文檔操作封裝爲可複用的技能（skill），開發者安裝一次即可在任意機器上使用，無需手動複製文件到 ~/.agents/skills。
插件定位¶
這是一個基於 docchain 構建的 DSH 知識庫和文檔轉換插件，提供文件名/內容/元數據搜索、主題列表、批量上傳、文檔轉 Markdown、圖像相似性搜索以及多子智能體深度研究工作流。插件通過插件配置頁面管理多個 docchain 環境，每個環境擁有獨立的地址和憑證，支持按環境預選主題。
核心功能¶
插件提供以下技能（skill），每個技能由 SKILL.md 說明和對應的 Node.js 腳本組成：
docchain-filename-search：按關鍵詞在主題範圍內搜索文件名docchain-content-search：按關鍵詞搜索文檔內容，返回行號和內容，支持or/and操作符docchain-meta-search：通過自定義元數據字段查詢文檔（字符串/數字/時間類型，支持精確匹配和範圍查詢）docchain-topic-info：列出 docchain 主題，支持分頁和按名稱或 ID 過濾docchain-upload：將本地文件或整個文件夾批量上傳到指定主題doc2markdown：將 docx/doc/pdf/pptx/xlsx/images 等多種格式轉換爲 Markdown，結果與源文件並排docchain-image-search：通過示例圖片查找相似圖片，返回匹配圖片及其主題、文檔和相似度分數deep-research-advanced：多子智能體深度研究工作流編排器（純指令，無腳本）
安裝與啓用¶
插件需要根據運行 DSH 的方式選擇對應的安裝命令：
| 運行方式 | 命令 |
|---|---|
| 桌面應用 | dsh plugin --profile desktop add github:wct-lab/dsh-docchain |
dsh web |
dsh plugin --profile web add github:wct-lab/dsh-docchain |
安裝完成後需重啓 DSH，使宿主和客戶端重新加載。
配置（必需）¶
插件不包含預置憑證。除 doc2markdown 外，所有腳本在運行前都需要配置 docchain 服務端點和 API 密鑰；doc2markdown 可使用內置默認端點匿名上傳。配置字段包括：
| 字段 | 說明 | 是否必需 |
|—|—|
| docchain_url | docchain 服務地址，例如 http://<host>:7100/llmdoc | 是 |
| docchain_api_key | API 認證密鑰 | 是 |
配置提供方式按優先級排序：
- 環境變量
DOCCHAIN_URL和DOCCHAIN_API_KEY - 單個技能的配置文件
<skill>/scripts/config.json - 插件狀態文件
~/.dsh/storages/docchain-config.json（由插件配置頁面寫入） - 包級
skills/docchain_config.json（文件分發時的回退，插件僅提供docchain_config.example.json模板）
配置文件格式示例：
{
"docchain_url": "http://<host>:7100/llmdoc",
"docchain_api_key": "your-api-key-here"
}
所有腳本依賴 Node.js，調用方式爲在技能基礎目錄執行 node scripts/<script>.js …，具體參數見各 SKILL.md。
插件配置（推薦）¶
插件在 DSH web 客戶端提供配置頁面：在 dsh web 左側欄打開「Plugins」，找到 dsh-docchain 插件，點擊行上的配置按鈕。該頁面管理一組已保存的環境，每個環境包含地址和憑證引用，並預選主題。當前生效的環境顯示在單行中，點擊可查看列表、添加/編輯/刪除條目。切換環境立即生效，無需保存或重啓。
配置頁面遵循官方憑證模式，配置模式聲明以下字段：
| 字段 | 說明 |
|---|---|
docchain_url |
未激活環境時使用的服務端點，與當前環境同步 |
docchain_api_key_ref |
憑證引用名稱，默認爲 DOCCHAIN_API_KEY |
docchain_api_key |
回退明文密鑰（不推薦，存儲優先） |
docchain_environments |
已保存環境列表（JSON），每條包含名稱、URL、憑證引用和預選主題 |
密鑰值存儲在憑證存儲 ~/.dsh/.credentials.yaml 的 refs 部分（僅所有者權限）。通過配置頁面保存或直接編輯該文件即可生效，修改會熱重載。激活時，每次存儲憑證變更或行設置保存後，解析後的值會寫入 ~/.dsh/storages/docchain-config.json（權限 0600），該文件是當前解析的純投影。密鑰解析順序爲：憑證存儲（啓動環境 > 存儲文件）> 行中的 docchain_api_key。
引用名稱本身即配置：不配置 docchain_api_key_ref 是有效狀態，此時頁面報告無密鑰，腳本會以配置錯誤退出，而不是回退到其他引用。保留但錯誤的密鑰會靜默查詢錯誤的賬戶，比失敗更難察覺。
切換環境¶
配置頁面維護一組已保存環境，切換不同 docchain 服務時無需重複輸入 URL 和密鑰：
- 頁面顯示當前生效的環境行，點擊可展開列表
- 選擇條目立即生效，無需保存或重啓
- 每個環境存儲獨立的 URL 和憑證引用，切換回時不再請求密鑰
- 憑證引用保留在憑證存儲中，僅寫入不讀取
- 頁面僅管理環境，地址和密鑰是環境的屬性，編輯在行內完成
- 無保存條目時，行顯示「no environment selected」，
docchain_url和docchain_api_key_ref作爲回退值（可在cordis.patch.yml中編輯） - 刪除條目會刪除其憑證，除非另一環境仍使用該引用或該引用是回退引用；生效條目不能刪除，需先切換
數據位置¶
| 內容 | 位置 |
|---|---|
| 環境列表（名稱、URL、憑證引用、預選主題） | 插件配置頁面 |
| 密鑰值 | ~/.dsh/.credentials.yaml（refs 部分） |
| 解析後的配置投影 | ~/.dsh/storages/docchain-config.json |
典型用法¶
以下示例展示常見操作：
- 在
dsh web中安裝插件並重啓 - 打開 Plugins 頁面，配置
dsh-docchain，添加一個環境，輸入地址和密鑰，預選主題 - 在技能列表中調用
docchain-filename-search，按關鍵詞搜索文件名 - 使用
docchain-content-search搜索文檔內容，關鍵詞用or/and組合 - 通過
docchain-upload批量上傳本地文件到指定主題 - 使用
doc2markdown將文檔轉換爲 Markdown，結果與源文件並排
適用場景與注意事項¶
適合需要與 docchain 服務交互的 DSH 用戶，包括知識庫管理、文檔檢索、批量上傳、格式轉換和基於文檔的研究工作流。
使用時需注意：插件以當前 dsh 進程的權限運行；安裝前應檢查源碼與許可證；配置密鑰時注意解析順序和引用名稱配置；doc2markdown 不依賴配置，其他腳本必需配置；憑證引用未配置時腳本會報錯而非回退。
小結¶
wct-lab/dsh-docchain 將文檔檢索與轉換能力標準化爲 DSH 技能，通過配置頁面管理多環境切換，支持批量操作和深度研究工作流。開發者安裝一次即可在任意機器複用這些能力，避免重複實現。更多詳情見插件目錄頁與 GitHub 倉庫。
