前言¶
DeepSeek Harness (DSH) 的核心理念是「一切皆插件」。當智能體需要連接外部知識庫時，開發者通常面臨集成複雜、權限管理粗放的問題。doco-dsh 是 DeepSeek Harness 的原生插件，旨在爲 Agent 提供 Doco 知識庫的塊級尋址、全文檢索、結構化閱讀以及草稿保存能力。
是什麼¶
doco-dsh 是由 songofhawk 維護的 Doco 知識庫原生插件。它通過 9 個工具將 DeepSeek Harness 與 Doco 連接起來，支持 block-level addressing（塊級尋址）。
該插件複用了 doco-agent-cli 的 DocoClient 邏輯（HTTP / ETag / Token），並依賴宿主提供的 @deepseek-ai/dsh-tools 和 @deepseek-ai/cordis。默認模式下只讀，寫入操作需要經過 DSH 原生審批和 Scope 門禁。
核心功能¶
插件提供以下 9 個工具，分爲讀取和寫入兩類：
讀取能力¶
- doco_status：連接自檢，顯示當前用戶、Scope、API 地址及讀寫能力。
- doco_list_knowledge_bases：列出 Agent 可見的知識庫 ID。
- doco_search：調用 Search v2 進行全文搜索，返回完整性證明（
projection.complete/freshness）。 - doco_outline：獲取文檔結構大綱，返回穩定的
block_id和 heading 路徑。 - doco_read：按 Token 預算局部讀取正文，支持
around/cursor續讀。 - doco_get_spreadsheet：獲取工作表結構、激活頁、尺寸與頂層 version。
- doco_get_cells：讀取指定範圍單元格的原始字符串。
寫入能力¶
- doco_update_cells：原子批量提交單元格更新，需配合
if_match版本校驗。 - doco_save_draft：將 Agent 產出存爲新草稿，使用冪等性 Key，絕不覆蓋現有草稿。
安裝與啓用¶
推薦通過 DSH 的插件管理器直接安裝，該包聲明瞭 dsh.bundle.patch，安裝後會自動掛載進 profile 層棧。
dsh plugin --profile <name> add doco-dsh
若需手動掛載，需先安裝依賴：
pnpm add doco-dsh # 或 npm i doco-dsh
隨後在 DSH 的 Composition YAML 中追加配置（name 可爲包名或本地路徑）：
- id: doco
name: 'doco-dsh'
依賴說明：
- 運行時依賴：doco-agent-cli@^0.1.3
- Peer 依賴：@deepseek-ai/dsh-tools / @deepseek-ai/cordis（由宿主 DSH 提供）
配置¶
插件不支持 YAML config: 塊，所有配置通過環境變量完成。優先級爲：啓動參數 > doco-agent-cli 配置 > 插件級環境變量 > 內置默認。
| 環境變量 | 默認值 | 說明 |
|---|---|---|
DOCO_API_BASE_URL |
https://api.doco.page/api/v1 |
API 地址 |
DOCO_API_TOKEN |
— | 認證令牌（也可通過 /doco connect 登錄獲取） |
DOCO_DEFAULT_KB |
— | 默認知識庫 ID |
DOCO_WEB_ORIGIN |
https://doco.page |
引用鏈接的 Web 源 |
DOCO_READ_MAX_TOKENS |
4000 |
doco_read 默認預算 |
DOCO_READ_CONTEXT_BEFORE / AFTER |
2 / 4 |
上下文塊默認數量 |
DOCO_DSH_TOOL_PREFIX |
doco |
工具名前綴 |
DOCO_DSH_ALLOW_WRITES |
false |
寫入總開關 |
典型用法¶
連接與鑑權¶
首次使用需授權。默認只讀，寫入需顯式指定權限。
/doco connect # 默認 read_only
/doco connect --access read_write # 需要寫入時選 read_write
授權成功後，Token 會寫入 ~/.config/doco/config.json。後續可通過以下命令管理狀態：
/doco status
/doco disconnect
/doco set-kb <kb_id>
電子表格操作流程¶
對於 document_type=spreadsheet 的文檔，必須使用專用工具流，禁止通用 TipTap 寫入或瀏覽器操作。
- 獲取結構：調用
doco_get_spreadsheet獲取頂層version和 sheet ID。 - 讀取數據：調用
doco_get_cells讀取目標範圍。 - 更新數據：調用
doco_update_cells，傳入cells和if_match（讀取的 version 或 ETag）。
示例更新操作：
cells={"C15":"10","C16":"20","C17":"=SUM(C15:C16)","C18":""}
注意事項¶
- 寫入安全：默認只讀。寫入需開啓
DOCO_DSH_ALLOW_WRITES，並經過 dsh 原生審批和 Scope 校驗。doco_save_draft僅創建新草稿，不會覆蓋舊草稿。 - 電子表格限制：Spreadsheet 類型的文檔必須使用
doco_get_spreadsheet/doco_get_cells/doco_update_cells工具。 - 錯誤處理：工具失敗時返回結構化錯誤值（
kind:'doco_error'），包含next_step指引，而不是拋出異常。 - MCP 衝突：若同時加載了 Doco MCP，同名工具會跳過註冊以避免衝突。推薦使用原生插件。
結語¶
doco-dsh 爲 DeepSeek Harness 提供了與 Doco 知識庫深度集成的能力。通過塊級尋址和結構化工具，開發者可以更安全、精細地控制 Agent 對知識庫的讀取與寫入操作。完整文檔與源碼可查看項目目錄與 GitHub 倉庫。
