/docs

name: docs
description: 用户要一份文档时用：报告、提案、计划、简历、求职信、信件、合同、制度、表单、模板、作文、手册、指南、操作说明、速查表这类要保留、共享、评论、导出或打印的文字。用 docs_* 工具在工作目录建一份文档，先发骨架再一节一节填，线程里出现文档卡片，用户在功能区编辑与评论。也用于按文档评论或请求改已有文档。聊天里问的计划、对比、摘要留在聊天；幻灯片用 slides，视觉设计用 design。
version: 1.0.0

文档

一份文档是会话工作目录里的一个目录 `<doc>/`（`doc.json`、每个标签页一份 `tabs/<id>.json`、`comments.json`、`assets/`），在功能区的文档标签里用文档编辑器打开：用户在里面直接改字、评论、勾选任务、选下拉项，改动即时保存。**这些文件全部归 BaoCut**：绝不用文件工具或 shell 读写它们，只用 docs_* 工具；你的修改即时出现在用户开着的编辑器里。

文档里有标签页（tab），每个标签页有一份正文（prose）：段落、标题、列表、任务、表格、引用、代码块、图片与 chip（日期、提及、下拉选项、待填块）。**没有**图表、示意图与 widget：数字与结构用表格、列表或编号步骤表达，`docs_*` 收到图表或 widget 会拒绝（`unsupported`）。

工具

每个工具都带 `doc`：文档目录，相对工作目录（例如 `q3-launch-plan`）。其余参数照搬 Claude Docs 的连接器：`container`、`ref`、`engine`、`payload`、`batch`、`answering`。

• docs_batch：新建文档（`container.create`），或在一份文档上原子地执行一组成员（任一条被拒，什么也不改）。
• docs_read：不带 `ref` 读文档本身（`files[]`：每个标签页的 id 与正文 id）；带正文 `ref` 按 `payload` 读大纲、一段、搜索或某个 rev 以来的变化。
• docs_update：改正文（`payload.ops`）或文档本身（标签页的名字、顺序、层级：`{"kind":"patch"}`）。
• docs_create：评论与回复（`utterance`）、下拉选项（`enum`）、标签页（`file`）、正文（`node`）。
• docs_query：列评论线程。docs_delete：删标签页、自己的评论或下拉选项。
• docs_upload：工作目录里的文件 → 文档的素材，返回正文里引用它的 `blob/<id>`（见 `references/uploads.md`）。
• docs_export：导出 Markdown（结果里，或写成工作目录里的 `.md`）。Word、PDF：告诉用户在文档编辑器里导出。

下文 `C` = `{"kind":"project","id":"<文档 id>"}`（文档 id 在新建的回执与 docs_read 的结果里）；ids 都是**一个**示例：用你自己读到的。

先建骨架，再一节一节填

用户要一份文档（哪怕是用问句问的）→ 一份文档，绝不把正文贴在聊天里；一个简单问题 → 聊天里答。只在用户要文档时建文档，而且**先建**：这一回合的**第一个**工具调用就是骨架（标题、byline、每节一个 `pending` 块），在任何搜索、读文件、规划之前发出；骨架开着之后再想。

docs_batch(
  doc = "q3-launch-plan",
  container = {"kind":"project","create":{"name":"Q3 launch plan",
    "doc":{"blocks":{"asof":{"type":"date","value":"2026-09-04"},
                     "me":{"type":"mention","user":"me"},
                     "due":{"type":"date","value":"2026-09-29"},
                     "s1":{"type":"pending","intent":"Goals: the three outcomes this quarter commits to"},
                     "s2":{"type":"pending","intent":"Staffing: who owns each workstream"},
                     "s3":{"type":"pending","intent":"Open questions: checking the launch thread and last week's notes"}},
           "markdown":"# Q3 launch plan\n\n<?claude block asof?> · <?claude block me?>\n\nQ3 ships the connector to all workspaces and takes weekly active teams to 500 by <?claude block due?>.\n\n<?claude block s1?>\n\n<?claude block s2?>\n\n<?claude block s3?>"}}},
  batch = [])

• `doc` = 新目录：按标题起一个简短的名字，不以点开头，不存在或是空的；同一个会话里的第二份文档用它自己的目录。回执的 `lids` 给出标签页 `f` 与它的正文 `n`；`n` 的回执是写下的大纲：标题、byline、导语，每节一个 `<pending id=… intent=…/>`。线程里随即出现文档卡片：用一行告诉用户文档开好了、正在写什么，他们多半开着它看你填。
• byline = **恰好** `<?claude block asof?> · <?claude block me?>`（as-of 日期 · 作者 = 用户）：不放状态词、来源、范围或说明。
• 大纲 = 第一次的 markdown，定稿：标题、byline（需求给了导语就加导语），然后每节**一个** pending 块，`intent` 用平白的话说这一节放什么、或你要去查什么；有形状的内容在 intent 里点名它的表或列表。不写 `##` 行：每个标题随它的填充一起来。一张表就能答的 = 标题、byline、导语、那一个块；短备忘 = 标题加几段，整篇，不分节。
• 填：每节**一次** docs_update，按阅读顺序，第一次紧跟着骨架；每次之间在聊天里用一行说你在写哪一节。`replace` 那一节自己的 pending 块，内容是 `## <标题>` 加正文：

docs_update( doc = "q3-launch-plan", ref = {"object":"node","id":"<lids.n>"}, engine = "prose", container = C,
  payload = {"ops":[
    {"op":"replace","target":{"kind":"blocks","ids":["kq2b7w3m9pa.105"]},
     "with":{"from":{"kind":"inline","content":"## Goals\n\n- Ship the connector to every workspace\n- 500 weekly active teams by GA"},"as":"markdown"}} ]} )

`ref` 是正文 **node**（`lids.n`），绝不是块 id；pending 块的 id 放 `target.ids`；pending 块的填充不需要 guard。回执给出新标题与正文的 id（之后改它们用这些 id，不再用 pending id），一条 `pending_ended` 通知说明它了结了哪个 pending 块。

• 要去查才写得出的东西（要研究的一节、要建的表）：**先**在它要落的地方种一个 pending 块（intent = 要来的内容），再 `replace` 成内容：用户先看到计划，再看着它填满。
• 一份文档 = **一个**简洁的标签页，来源放在末尾的 Sources 一节；另开标签页只给有自己分量的材料（工作笔记、原始数据、大量来源）。需求本身就是一组标签页（每个会议、每个伙伴、每一天）→ 全部在新建时一起建：`references/tabs.md`。

改一份文档

在**那份**文档上改，也就是用户或本次对话指明的那个目录（线程里的一张文档卡片、一个路径、一个 Space 条目）：绝不另建一份。只改被要求改的，其余每个字保持原样；事实只来自文档、用户与评论者。

docs_read( doc = "q3-launch-plan" )
  → files:[{id:"afc001d0-ce07", name:"Q3 launch plan", content:{kind:"node", id:"be1476b2-62c1", engine:"prose"}}]（标签页 id、正文 id）
docs_read( doc = "q3-launch-plan", ref = {"object":"node","id":"be1476b2-62c1"}, engine = "prose", container = C, payload = {"projection":"outline"} )
  → <doc rev='12'><paragraph id='mq2x81a0kfd.0' heading='1'>Q3 launch …</paragraph><paragraph id='.16' h='cddc588b'>Q3 ships …</paragraph><list id='.40' kind='bullet'><gap blocks='2'/></list><table id='.90'>…
docs_update( doc = "q3-launch-plan", ref = {"object":"node","id":"be1476b2-62c1"}, engine = "prose", container = C,
  payload = {"ops":[
    {"op":"replace","target":{"kind":"find","text":"500 weekly active teams"},
     "with":{"from":{"kind":"inline","content":"750 weekly active teams"},"as":"text"}},
    {"op":"insert","target":{"kind":"blocks","ids":["mq2x81a0kfd.90"]},"side":"after",
     "source":{"from":{"kind":"inline","content":"## Risks\n\n- GA slips if legal review runs long"},"as":"markdown"}} ]} )

• 删除、移动、表格的行与列、找回被删的文字（它在文档的历史里，绝不凭记忆重打）→ **先**读 `references/editing.md`，它写了这些 op 的形状；绝不猜。
• 目标：能引用的文字用 `{"kind":"find","text":"…"}`，不用先读（重复时加 `"nth":2`）；照抄上次读到或回执里的原文，转述会 `find_none`。整块用大纲里的完整 id；整块的 `replace`/`delete` 在 `"op"` 旁边**同时**带 `"ifHash"`（它最新的 `h`）与 `"ifRev"`（显示它的那次**读**的 `rev`），或者被要求覆盖时 `"force":true`；不带 → `missing_guard`。
• `insert` 用 `"source":{from, as}`，`replace` 用 `"with":{from, as}`；`from` 永远是 `{"kind":"inline","content":"…"}`。`"as":"text"` 原地改字，保留 chip、换行、格式与评论；`"as":"markdown"` 是整个列表、表格或一节，重发全部条目或行，只保留它重新写出的。`side`：`"before"` | `"after"` 一个块；`{"kind":"root"}` + `"end"` = 标签页末尾；标题 id + `"end"` = 那一节的末尾。一次可以带多个 op。
• 长文档绝不整篇读：先大纲，再 `{"kind":"view","parentId":"<块 id>"}`（一张表或一个列表全文）或 `{"kind":"search","text":"…"}`。
• 文档在你的回合之间和回合之中都会变：书签 = 你上次读的 `rev`（还没读过：上次回执的）；之后的回合碰这份文档时先 `{"kind":"view","sinceRev":<书签>}` → 只给变了的块。你自己连续写之间不读。`guard_mismatch` / `find_none` = 那个块被人改了 → 他们的改动算数，绝不用 `force` 重发，说明你保留了什么（`references/editing.md`）。
• 被拒 = 什么也没改；错误码（`code`，可能带 `path`）说明怎么修 → 改好后重发**整个**调用。各个拒绝码的处理见 `