Under the Hood

给 Agent 的，
不只是一个接口

四条通道进得来，块级契约改得准，版本快照回得去。以下每一条今天都在线上跑。

阅读 API 文档

Ways In

进来的路，
不止一条

装好一次，剩下的它自己会。四条路通向同一套接口。

MCP

挂上就能用

Claude Code、Cursor 一条命令挂上，14 个文档工具即时到位。支持 resources 的客户端还能把文档直接挂成上下文。

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

Skill

教它守规矩

先读、记版本、带 If-Match 写、撞车重读——安全写入的规矩装在文件里，不靠提示词临场发挥。

npx -y --package doco-agent-cli doco skill install

CLI

像改本地文件

把某一节拉进 $EDITOR，保存自动回写。版本号与冲突重试都在命令内部处理完，脚本里加 --json 即可消费。

npx -y --package doco-agent-cli doco edit <docId> --heading "Deploy runbook"

API

自己写也行

块级读写、批量事务、搜索、回滚，端点全部开放。任何语言、任何框架都能接。

curl -H "Authorization: Bearer $DOCO_TOKEN" \
  $DOCO_BASE_URL/api/v1/documents/:id/blocks

MCP 工具集

doco_whoamidoco_list_knowledge_basesdoco_get_treedoco_list_documentsdoco_get_documentdoco_update_documentdoco_create_documentdoco_get_blocksdoco_patch_blockdoco_insert_blocksdoco_delete_blockdoco_batch_editdoco_searchdoco_upload_attachment

doco login 走浏览器授权，和 gh auth login一样。

其他 Agent 客户端

同一个 MCP 包，
再开三扇门

所有客户端都启动同一个 stdio server。保留客户端确认、先给只读权限，验收连接后再开放写入。

Codex CLI / IDE

共用 MCP 配置，可选安装操作 Skill

把 stdio server 写入 ~/.codex/config.toml，或受信任项目的 .codex/config.toml。再安装 Doco Skill，让 Codex 掌握读取 → 记版本 → 保护写入的黄金循环。

先运行 codex mcp list 或 /mcp 验收，再让它读取文档。

查看客户端官方文档

# ~/.codex/config.toml
[mcp_servers.doco]
command = "npx"
args = ["-y", "--package", "doco-agent-cli", "doco", "mcp"]

npx -y --package doco-agent-cli doco skill install --target codex

三种客户端都启动同一个 doco-agent-cli 进程，发现同一套 29 个工具；变化的只有外层配置格式。

Protocol

不必吞下全文，
只取要改的那一段

按段读取

每段都有位置无关的稳定 ID，拖动、折叠、跨端同步后依然指向同一段。取回整棵段落树，Markdown 也能带上块锚点。

精确写入

插入、替换、删除都只动那一段。多处改动走 /batch 单事务，全有或全无；创建类操作带幂等键，重试不会写两次。

撞车不丢字

写入必须带 If-Match，版本对不上就 409，重读合并再提交。每次写前自动留快照。

1 · 按块读取，记下版本

curl -H "Authorization: Bearer $DOCO_TOKEN" \
  https://doco.example/api/v1/documents/spec-v2/blocks
# 200 · 4 blocks · ETag "sha256:9f2c…"

2 · 只替换「部署流程」那一段

curl -X PATCH .../blocks/block_01JXK3F7… \
  -H 'If-Match: "sha256:9f2c…"' \
  -d '{"node":{"type":"paragraph",…}}'
# 200 · new version "sha256:a41d…"

3 · 版本对不上？重读合并，不覆盖

●409 conflict → 重新 GET → 合并 → 重试
  改坏了：POST /versions/12/rollback

Traceable

改了什么看得见，
改坏了回得去

放手之前，你本来就该拿到的东西。

每次写入自动留档

写入前自动存快照，哪一段被改过一目了然。

一键回到上一笔

选中任意一版回滚，带并发保护地写回去。

对着段落追问

批注锚在具体段落上，不必推倒重写。

GET /api/v1/documents/:id/versionsPOST /api/v1/documents/:id/versions/:seq/rollbackPOST /api/v1/documents/:id/batchGET /api/v1/search

Architecture

人和 Agent，
走的是同一条路

API 写入不是旁路——它和编辑器落进同一个 Yjs 文档，所以才不会互相覆盖。

Ⅰ

浏览器本地

IndexedDB 主存储，断网可写；Yjs 文档是唯一事实来源。

Ⅱ

增量同步

Hocuspocus 长连接只交换二进制增量，不传整篇。

Ⅲ

服务端落库

API 写入同样进 Yjs 文档，与编辑器走同一条合并路径。

回到首页完整 API 文档

给 Agent 的，不只是一个接口

进来的路，不止一条