前言¶
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 仓库。
