doco-dsh
Doco 知识库的 DeepSeek Harness（dsh）原生插件。用 6 个工具把 Agent 接到你的 Doco 知识库上：块级寻址、按 token 预算精读、乐观并发写入草稿、来源引用，全部复用 doco-agent-cli 的 DocoClient（HTTP / ETag / Token 逻辑不复制）。
默认只读；写入走 dsh 原生审批 + scope 门禁，绝不静默提交。
能力
| 工具 | 读/写 | 说明 |
|---|
doco_status | 读 | 连接自检：当前用户、scope、API 地址、读写能力 |
doco_list_knowledge_bases | 读 | 列出可见知识库（选 knowledge_base_id） |
doco_search | 读 | Search v2 全文搜索，带完整性证明（projection.complete / freshness） |
doco_outline | 读 | 文档结构大纲（稳定 block_id + heading path），先规划再精读 |
doco_read | 读 | 按 token 预算局部读取正文（around / cursor 续读） |
doco_save_draft | 写 | 把 Agent 产出存成新草稿（preview → 确认 → commit） |
回答里的事实命中有来源引用（document_uri / web_url）；doco_search 返回 complete=false 或 freshness=stale 时，插件会显式标注「结果不完整」，禁止 Agent 据此断言「知识库里没有」。
安装
doco-dsh 依赖：
doco-agent-cli@^0.1.3（npm 运行时依赖）；@deepseek-ai/dsh-tools / @deepseek-ai/cordis（peer dep，由宿主 dsh 提供，本插件不捆绑）。
装包并自动挂载（推荐）——本包声明了 dsh.bundle.patch，dsh plugin add 装完即自动挂进 profile 层栈：
dsh plugin --profile <name> add doco-dsh
手动挂载（备选）两步：
pnpm add doco-dsh # 或 npm i doco-dsh，装到 dsh 项目里供 composition 解析
再在 dsh 的 Composition YAML（如 agent.cordis.yml）里追加一条——name 既可用 npm 包名，也可用本地相对路径：
# 挂到你的 composition（追加一条）
- id: doco
name: 'doco-dsh'
（最简形式也可只写 - name: 'doco-dsh'。挂载语法细节见 dsh 教程《07 · Into the Harness》。）
挂载完成后，apply 会：
- 解析配置（见下）；
- 注册 6 个工具（命名带
doco_ 前缀，可配 DOCO_DSH_TOOL_PREFIX 覆盖）；
- 注入系统提示词分段（仅规则，不注入内容/Token）；
- 注册
/doco 命令。
配置走环境变量与 doco-agent-cli 的 loadConfig()（见下方「配置」），不通过 YAML config: 块。
若 @deepseek-ai/dsh-tools 缺失或版本不兼容，插件会在加载期抛稳定错误码 doco_dsh_incompatible（不静默降级）。
授权（设备登录流）
/doco connect # 默认 read_only
/doco connect --access read_write # 需要写入时选 read_write
命令会打开系统浏览器完成设备授权，Token 写入 ~/.config/doco/config.json（0600），并自动重载插件状态。
/doco status / disconnect / set-kb <kb_id>
Token 只走 POST 请求体与浏览器；绝不进入工具结果、日志、错误栈或提交。
配置
优先级（高 → 低）：dsh 启动参数 > doco-agent-cli 的 loadConfig()（~/.config/doco/config.json + DOCO_BASE_URL/DOCO_TOKEN）> 插件级环境变量 > 内置默认。
| 环境变量 | 默认 | 说明 |
|---|
DOCO_API_BASE_URL | https://api.doco.page/api/v1 | API 地址（仅 http/https） |
DOCO_API_TOKEN | — | 令牌（也可用 doco-agent-cli 登录） |
DOCO_DEFAULT_KB | — | 默认知识库 id |
DOCO_WEB_ORIGIN | https://doco.page | 引用链接的 Web 源 |
DOCO_READ_MAX_TOKENS | 4000 | doco_read 默认预算（64–50000） |
DOCO_READ_CONTEXT_BEFORE / AFTER | 2 / 4 | 上下文块默认（0–100） |
DOCO_DSH_TOOL_PREFIX | doco | 工具名前缀 |
DOCO_DSH_ALLOW_WRITES | false | 写入总开关（仍受 scope + 用户确认双重门禁） |
写入安全（三层）
- 同步 guard：
DOCO_DSH_ALLOW_WRITES 未开启时，任何 commit 被单调拒绝（doco_write_not_confirmed）。
- pre-execute 审批：commit 前校验
documents:write scope，随后 ask 用户确认（dsh 原生审批）。
- execute 防御：即使被直接顶层调用，
doco_save_draft 也再校验 scope 并返回稳定错误码。
doco_save_draft 只 创建新草稿：不删除、不移动、不整篇覆盖；用唯一 Idempotency-Key，冲突即返回 doco_version_conflict，从不强覆盖。
doco 服务（供上层插件消费）
自 0.2.0 起，apply 在装配早期通过 ctx.provide('doco', createDocoService(state, { toolPrefix })) 暴露一个 doco 服务，把客户端、身份、scope、错误契约与配置以统一服务面开放给同进程的其他插件：
getConfig() / getClient() — 实时配置与 DocoClient（reconfigure 后整体替换，活引用）；ensureIdentity() / hasToken() / hasScope(scopes, scope) / scopes — 身份与权限面；errorValue / toErrorValue / mapApiError / DocoPluginError — 统一错误契约；toolPrefix / pluginName / version — 运行时元信息。
消费方用 Cordis 依赖注入声明 inject: ['doco']，插件会等待该服务就绪后才启动。当前消费者：
不消费 doco 服务也完全不影响 doco-dsh 自身 6 个工具：服务是纯增量面。
与 Doco MCP 的关系
doco-agent-cli 自带一套 29 工具的 MCP server。本插件复用同一 DocoClient，并在读/搜索工具上采用同名前缀：若二者被同时加载，registerTools 检测到重名会跳过而非覆盖，避免同一个知识库以两套名字重复注册、重复消耗上下文。推荐二选一（原生插件更省一跳 RPC 且能用上 dsh 原生写入审批；MCP 更通用）。详见 docs/adr-001-native-vs-mcp.md。
错误契约
工具失败「返回而非抛出」结构化错误值 { kind:'doco_error', code, message, next_step }，让模型能读到 next_step 自行纠偏。稳定错误码见 src/errors.js（如 doco_auth_required、doco_insufficient_scope、doco_rate_limited、doco_version_conflict、doco_read_cursor_stale）。
开发
pnpm install
pnpm test # 68 个测试：单测 + 真实 dsh-tools/cordis 冒烟 + 装配集成
