doco-agent-cli

doco-agent-cli

Doco 知识库命令行工具与 MCP 服务器——一条命令，把你的 Agent 接到知识库。

快速开始

# 1. 登录（浏览器设备授权，和 GitHub CLI 一样的心智模型）
npx doco-agent-cli login

# 2. 用起来
npx doco-agent-cli whoami
npx doco-agent-cli docs ls
npx doco-agent-cli docs cat <docId> -f md
npx doco-agent-cli edit <docId>            # 拉 Markdown 到 $EDITOR，保存自动回写

接入 Agent（MCP）

claude mcp add doco -- npx -y doco-agent-cli mcp

Cursor：在 MCP 设置粘贴

{ "doco": { "command": "npx", "args": ["-y", "doco-agent-cli", "mcp"] } }

MCP 工具集（29 个，刻意克制）：doco_whoami / doco_list_knowledge_bases / doco_get_tree / doco_list_documents / doco_search / doco_search_v2 / doco_get_document / doco_outline / doco_read / doco_get_blocks / doco_patch_block / doco_insert_blocks / doco_delete_block / doco_batch_edit / doco_create_document / doco_upload_attachment / doco_changes / doco_traverse / doco_create_relation / doco_summary / doco_save_summary / doco_rebuild_summary / doco_update_document / doco_concepts / doco_edit_concepts / doco_refresh_concept_candidates / doco_translations / doco_translation_units / doco_review_translation_unit。概念与多语言能力均按 action 聚合，避免把 CRUD 展开成工具爆炸。另提供可枚举、可订阅的 resources：doco://kb/<id>、doco://doc/<id>.md、doco://doc/<id>/outline.json。

MCP 场景可用环境变量代替 doco login：DOCO_TOKEN、DOCO_BASE_URL。

命令一览

doco login [--base-url <url>] [--token <token>] [--scope read_write|read_only] [--no-browser]
doco logout
doco whoami
doco docs ls [--kb <id>] [--folder <id>] [--q <关键词>] [--locale <BCP47>] [--include-variants] [--limit <n>]
doco docs languages <docId>
doco docs cat <docId> [-f md|json|html] [--locale <BCP47>]
doco docs new --title <标题> (--kb <id>|--folder <id>) [--body -]   # --body - 从 stdin 灌 Markdown
doco blocks ls <docId> [--recursive]
doco blocks patch <docId> <blockId> --node @node.json [--attrs '<json>'] [--content '<json>']
doco blocks insert <docId> --nodes @nodes.json [--after <blockId>|--before <blockId>|--parent <blockId>|--start|--end]
doco blocks delete <docId> <blockId>
doco changes <docId> [--after <cursor>] [--locale <BCP47>] [--limit <n>]
doco read <docId> [--view markdown|tiptap-json|plain-text|outline] [--locale <BCP47>] [--around <blockId>] [--max-tokens <n>] [--cursor <cursor>]
doco search --q <关键词> [--mode topk|exhaustive] [--locale <BCP47|all>] [--kb <id>] [--limit <n>] [--cursor <cursor>]
doco links ls <docId> [--direction outgoing|incoming|both] [--predicate <type>]
doco links add <docId> <sourceBlockId> --target <doco://doc/...> [--predicate <type>] [--anchor <text>]
doco links delete <relationId>
doco summary get <id> [--scope document|folder|knowledge-base] [--block <blockId>] [--q <问题>]
doco summary set <id> --text <摘要> [--scope document|folder|knowledge-base] [--block <blockId>] [--pinned]
doco summary rebuild <id> [--scope document|folder|knowledge-base] [--block <blockId>] [--generator deterministic|model]
doco summary job <jobId>
doco concepts ls [--kb <id>] [--q <关键词>] [--status <状态>] [--limit <n>] [--cursor <cursor>]
doco concepts get <conceptId>
doco concepts create --kb <id> --name <名称> [--description <说明>] [--aliases <json|@file>]
doco concepts update <conceptId> [--name <名称>] [--description <说明>] [--aliases <json|@file>]
doco concepts sources <conceptId> --sources <json|@file>
doco concepts relate <conceptId> --relations <json|@file>
doco concepts merge <sourceConceptId> <targetConceptId>
doco concepts traverse <conceptId> [--direction outgoing|incoming|both] [--predicate <type>]
doco concepts candidates [--kb <id>] [--status pending|accepted|rejected] [--min-confidence <0..1>]
doco concepts extract --target <documentId>
doco concepts accept <candidateId> [--concept <conceptId>] [--name <名称>]
doco concepts reject <candidateId> [--reason <原因>]
doco edit <docId> [--block <blockId>]
doco mcp
doco skill [install] [--target codex|claude]  # 输出 / 安装完整 Doco 操作 Agent

全局 --json 输出机器可解析 JSON；人类模式默认。

并发安全（内化乐观并发）

所有写入命令自动完成黄金循环：

• 先读当前 version（ETag）；
• 写入带 If-Match；
• 遇到 409 冲突 → 自动重读最新版 → 用同样的修改重试（最多 3 轮）。

概念更新、补来源/关系、合并与候选审核同样自动读取 ETag 并发送 If-Match；概念创建、候选抽取及上述修改均自动生成 Idempotency-Key。复杂的 aliases / sources / relations 数组既可传内联 JSON，也可用 @data.json 从文件读取。

doco edit 冲突时会重新打开编辑器并载入最新内容，你的上一轮编辑保存为 document.conflict-N.md 供合并参考——永不盲写覆盖。

配置

默认连接 https://api.doco.showme.talk/api/v1；本地开发或自托管实例可通过 --base-url / DOCO_BASE_URL 覆盖。配置保存在 ~/.config/doco/config.json（权限 0600）：

{ "base_url": "https://api.doco.showme.talk/api/v1", "token": "doco_tok_…" }

环境变量优先于配置文件：DOCO_BASE_URL、DOCO_TOKEN、DOCO_CONFIG_DIR。

Agent Skill

doco skill install --target codex   # 安装到 ~/.codex/skills/doco/
doco skill install --target claude  # 安装到 ~/.claude/skills/doco/

安装包包含操作协议、UI 元数据、全场景验收矩阵与隔离验证脚本。Agent 会按“发现、取证、执行、复核、报告”流程工作，并执行 ETag/If-Match 黄金循环。

限频

Token 总请求 120/min，写入 30/min，单文档写入 10/min；429 时读 Retry-After。