first commit

.agents/skills/dingtalk-doc/references/doc/style/doc-create-workflow.md

@@ -0,0 +1,414 @@
+# 钉钉文档创建流程
+
+本文只处理文档结构和排版设计。普通创建的执行入口固定为 `dws doc +create`，命令内置分片与回读验证；原子 `doc create/read/update` 仅用于 shortcut 未公开所需参数的专家路径，使用前必须读取精确 leaf Schema。
+
+> **路由硬约束：** 正文文件使用 `--content @./相对路径 --doc-format markdown|jsonml`；禁止 `/tmp`、绝对路径、已删除的 Python 脚本以及“创建后再额外 read”固定流水。
+
+> 改写已有文档见 [doc-update-workflow.md](./doc-update-workflow.md)。排版规范见 [doc-style-guideline.md](./doc-style-guideline.md)。
+
+## 前置必读
+
+> **同时读取 [doc-style-guideline.md](./doc-style-guideline.md)：**
+> - **§2.0 类型判断决策表** → 锁定文档类型（决策型 / 执行型 / 说明型 / 知识沉淀型）和骨架
+> - **§1 硬规则** → 全程生效（`--name` 已是 H1、不编造 URL、Markdown 草稿不写 callout 等）
+
+### 关键词速查（用户意图 → 起稿路径）
+
+| 用户关键词 | 文档类型 | 起稿路径 |
+|-----------|---------|---------|
+| 汇报 / 周报 / 月报 / 复盘 / 方案选型 / 决策 / 对比 | §2.1 决策型 | **→ JSONML 起稿** |
+| 调研 / 技术方案 / 复盘报告（含对比/数据） | §2.4 知识沉淀型 | **→ JSONML 起稿** |
+| SOP / Runbook / 接入指南 / 升级 / 操作手册 | §2.2 执行型 | → Markdown 起稿 |
+| 接口文档 / 能力清单 / 参数说明 / 错误码 | §2.3 说明型 | → Markdown 起稿 |
+| 用户原文含：颜色/高亮/美观/醒目/重点突出/像PPT | 任意类型 | **→ JSONML 起稿** |
+
+## 适用边界
+
+进入本文前，必须已经确认用户要创建的是钉钉文档 (`adoc`)。如果用户要的是钉钉表格、AI表格、文件上传、知识库空间管理或消息发送，不要套用本文。
+
+本文覆盖：
+
+- 文档标题和创建位置确认
+- 正文草稿准备
+- `+create` 写入并自动回读验收
+- 内容缺失时的补救写入
+
+本文不覆盖：
+
+- 从群聊、日志、听记、表格等来源采集资料
+- 生成日报、周报、月报等业务报告口径
+- 文档权限分享、消息通知或待办创建
+- 非钉钉文档的新建流程
+
+## 创建前检查
+
+创建前先锁定四个输入：
+
+| 项目 | 要求 |
+|------|------|
+| 标题 | 用 `--name` 传入；正文不要再重复同名一级标题 |
+| 位置 | 默认创建到我的文档；指定目录时只接受文档文件夹 `nodeId` 或 alidocs 文件夹 URL |
+| 正文 | 多行、表格、代码块、特殊字符或长度 >= 2KB 时必须写入 UTF-8 临时 `.md` 文件 |
+| 格式 | 按 §JSONML 起稿判定 决定起稿路径：命中 JSONML 起稿条件时**直接用 JSONML 构造**（跳过 markdown）；未命中时用 Markdown 起稿，创建后按 [doc-update-workflow.md](./doc-update-workflow.md) 精修 |
+
+禁止把纯数字 `dentryId`、drive `parent-id` 或 spaceId 填进 `--folder`。
+
+## JSONML 起稿判定
+
+在正文准备之前，先判断是否直接用 JSONML 起稿。**命中以下任一条件即走 JSONML 起稿路径**（跳过 markdown 草稿阶段）：
+
+### 文档类型触发
+
+| 类型 | 触发条件 |
+|------|---------|
+| 决策型（§2.1） | **默认触发** — 汇报/方案/对比需要摘要 callout、彩色表头、决策时限标注 |
+| 知识沉淀型（§2.4） | 含对比分析、多维度数据可视化、需要关键节点彩色 callout |
+
+### 意图关键词触发
+
+用户原文或需求描述中出现以下任一关键词：
+
+- 颜色 / 配色 / 上色 / 高亮 / 醒目
+- 字号 / 字体 / 加大 / 缩小
+- 视觉效果 / 排版精美 / 好看 / 美观
+- callout / 分栏 / 对比色 / 彩色表头
+- "像 PPT 那样" / "有设计感" / "重点突出"
+
+---
+
+## 设计规划（JSONML 起稿前必做）
+
+判定走 JSONML 路径后，**禁止立即动手写 JSONML**。先完成以下两阶段规划，各自产出一个持久文件作为后续阶段的锚点。
+
+### 设计原则（全程生效）
+
+1. **结构即信息** — 标题层级、表格 vs 分栏 vs 列表、callout 位置都应编码内容逻辑。问自己：“去掉这个结构元素，读者会丢失信息或体验变差吗？”— 丢失信息则必保留；不丢失信息但能提升可读性或美观度（如分割线分隔章节、分栏对比排版）也应保留；既不携带信息也不提升体验的装饰元素才删除。
+2. **视觉层级引导阅读** — 每一屏必须让读者瞥一眼就能回答：“这块最重要的是什么？”字号/粗体/颜色形成明确梯度：标题 > 重点数据 > 正文 > 辅助信息。
+3. **克制产生质感** — 遵循 60-30-10 配色比例：60% 中性底色（白/浅灰）、30% 辅助色、10% 强调色。多色系共存时需保持**同等饱和度**并各有语义角色（如淡蓝=信息、淡黄=提示、淡红=风险），同一色系内深浅变化自由。callout 不超过 2 个。
+4. **设计先于执行** — 从规划阶段起每个结构块的样式就已确定，执行时（无论直接 JSONML 还是脚手架精修）只是落地已有设计，不是边写边想。
+5. **同类同色、一色多阶** — 同类信息必须使用相同色系；单一色系按元素角色展开为深/中/浅/极浅四级（标题文字用深色、强调用中色、高亮/表头用浅色、背景用极浅色），不要全篇只用一个 hex 值。
+
+### Phase 1：RFC — 需求理解与设计方向
+
+**目标**：明确“做什么”和“为什么这样做”，形成方向性锚点。
+
+#### 1.1 需求提取（全量列出用户显式要求）
+
+通读用户 prompt，抽取两类要求并编为清单：
+
+**内容要求**：
+- 标题、字数、章节划分
+- 数据来源、受众
+- 语气/风格（如“大气”“专业”“轻松”）
+
+**样式要求**（每一条都必须在最终输出中体现，不得遗漏）：
+- 字体：映射为 font-family 名称（参照 cookbook 字体映射表），区分“全文字体”和“特定元素字体”
+- 字号、行距、对齐、颜色
+- 强调手段（加粗、高亮、配色…）
+- 约束（如“每部分不省略”）
+
+> 用户没有明确指定的维度（如未指定行距、未指定表格样式）由 Phase 2 补充设计决策。
+
+#### 1.2 内容-表现适配（每个章节的内容适合用什么元素）
+
+对每个章节回答：“这个内容的核心是什么类型的信息？”→ 选择最佳元素：
+
+**块级结构元素**：
+
+| 信息类型 | 首选元素 | 不适合 |
+|----------|---------|--------|
+| 多个同类实体对比（≥ 4 项或 ≥ 3 维度） | 彩色表头表格 | 纯文本段落 |
+| 少量实体对比（2-3 项× 少量维度） | 分栏（每栏一个实体，可设边框/背景色） | 大宽表格 |
+| 时间序列/流程（行程/步骤） | 有序列表 + 粗体时间标签 | 无序列表 |
+| 单个结论/推荐/重要提示 | callout（“花大胆”的地方） | 普通段落 |
+| 描述性文字（背景/说明） | 正文段落 + 关键词粗体 | 表格 |
+| 分类列举（特色/亮点） | 无序列表 | 表格（数据不够多列时） |
+| 数值强调（评分/价格/统计） | 加粗 + 着色 | 跳过不强调 |
+| 引用原文（用户评价/网友点评/官方说明） | 引用块 | 普通段落 |
+| 任务/待办清单 | checklist（`- [ ]`） | 普通列表 |
+| 章节分隔/主题转换 | 分割线（`hr`） | 空行 |
+| 板块内子区域分隔（同一单元格/容器内多个逻辑段） | hr 内部分隔（在 tc 或 container 内部使用） | 空行或留白 |
+| 结构化元信息（人/时间/地点/属性清单） | 键值对表格（窄标签列 ~15-20% + 宽内容列） | 多行段落 |
+| 分类标签/状态标记 | 标签元素（tag） | 纯文本标记 |
+
+**行内强调元素**：
+- **emoji** — 用于 callout 前缀、状态标记、H2/H3 标题前；不在普通段落和列表项中滥用
+- **加粗/高亮/着色** — 强调关键数据和结论
+- **highlight 色带** — 在标题 span 上设 `"highlight": "#浅色"` 形成轻量色条标记，比 callout 更轻，适合区分多个并列板块的主题色
+- **灰色辅助文字** — 用浅灰色（如 `#979A9B`）标记示例/说明/占位文字，与正文形成明确的主次层级
+- **图片** — 实景照片、截图、示意图能显著提升理解时使用
+
+**分栏选型补充**：分栏栏数无上限，但推荐 2-4 栏（≥5 栏会比较拥挤），可设置边框和背景色。**建议设置 `fill` 背景色**（纯白底分栏视觉上与普通段落无异，读者不易感知分栏结构）。适合场景：
+- 2-3 个同类实体并排展示（每栏一个实体，含标题 + 描述 + 关键数据）
+- 轻量对比：“优点 vs 缺点”、“方案 A vs B”、“Day 1 vs Day 2”
+- 网格布局：多次插入同栏数分栏可形成卡片网格（如 2×3、3×2），适合 4-9 个结构相同、内容等长的卡片式实体。**约束**：每个格子内容必须结构一致且长度相近，否则高低不齐会很丑；实体数不能整除栏数时不使用
+
+例如：“5 个实体多维度对比” → **彩色表头表格**；“两组信息并排” → **分栏**；“6 个结构相同的卡片” → **2×3 分栏网格**。
+
+#### 1.3 起稿策略选择
+
+根据文档复杂度和上方适配结果，确定起稿路径：直接 JSONML / Markdown 脚手架 + JSONML 精修 / 直接 JSONML 分段构造。具体条件和流程见下方「起稿」节的策略表。
+
+#### 落盘
+
+将以上内容写入 `<name>-rfc.md`，包括：
+- 需求摘要（内容要求 + 样式要求）
+- 每章展现策略 + 选择理由
+- 起稿策略
+
+---
+
+### Phase 2：Spec — 精确设计参数
+
+**目标**：将 RFC 的方向决策转化为可直接执行的参数。
+
+#### 2.1 视觉体系设计（确定全局设计变量）
+
+在以下四个维度做出明确选择，每个选择都必须能解释为什么适合这篇文档：
+
+**色彩**（选定主色后展开为色阶）：
+
+用户指定颜色时（如"蓝色""绿色"），不要全篇只用一个 hex 值。将其展开为 4 级色阶，按元素角色分配：
+
+| 角色 | 用途 | 色阶要求 |
+|------|------|----------|
+| 深色 | 标题文字、重点数据 `color` | 白底上高对比可读 |
+| 中色 | 正文强调、链接 `color` | 辨识度高但不抢标题 |
+| 浅色 | highlight 色带、表头 fill | 底色柔和，上方深色文字可读 |
+| 极浅 | container bgcolor、大面积背景 | 接近白色，仅提供区域感 |
+
+**规则**：
+- 深→浅的层级关系不可颠倒（不能用极浅色做标题文字、不能用深色做背景）
+- 同类板块/同类标题必须使用完全相同的色阶组合，通过色彩的重复形成视觉韵律
+- 不同类别可用不同色系区分（如：任务=蓝系、风险=红系、成果=绿系）
+- 遵循 60-30-10 配色比例：60% 中性底色、30% 辅助色、10% 强调色；用户指定的颜色值优先
+
+**字体梯度**（形成明确层级）：
+- 主标题（h2）：字体 / 字号 / 粗体 / 颜色
+- 正文：字体 / 字号 / 行距
+- 强调文字：粗体 + 颜色或高亮
+- 辅助信息（注释/来源）：字号偏小 / 灰色
+
+**表格风格**（有表格时）：
+- 表头：底色 + 文字色 + 是否粗体
+- 单元格：默认对齐 / 字号
+
+**视觉重心**（克制原则落地）：
+全篇选 1-2 处给予最强视觉处理（配色 callout / 彩色表头 / 分栏对比），其余元素保持朴素。不要处处强调 — 处处强调等于没有强调。
+
+callout 可通过 `"showstk": true, "sticker": "图标名"` 配置顶部贴纸图标（如“灯泡”“火”“钉子”），增强语义标识。设置了 sticker 后，高亮块内首个段落不要再以 emoji 开头，避免紧邻的位置出现两个图标。
+
+#### 落盘与回验
+
+1. 将以上内容写入 `<name>-design.md`，包括：
+   - 逐章元素映射（用什么标签、什么属性）
+   - 色阶具体 hex 值
+   - 字体梯度参数
+   - 表格风格细节
+
+2. **回验**：Read `<name>-rfc.md`，逐条确认：
+   - [ ] RFC 中每条需求在 Spec 中有对应实现
+   - [ ] 展现策略在 Spec 中有具体参数支撑
+   - [ ] 配色遵循 60-30-10 比例、callout ≤ 2 个、多色系饱和度一致且有语义角色
+
+回验通过后进入下一节开始构造 JSONML。
+
+---
+
+## JSONML 起稿（命中判定时使用）
+
+根据 RFC 中确定的起稿策略执行：
+
+| 策略 | 条件 | 执行流程 |
+|------|------|----------|
+| **直接 JSONML** | 短文档（≤ 15 块级节点）且结构简单 | 在 `./drafts/<name>.json` 编写完整 JSONML 树 → `+create --content @./drafts/<name>.json --doc-format jsonml` |
+| **Markdown 脚手架 + JSONML 精修** | 长文档且结构较线性 | ① Markdown 建立内容骨架 → `+create` ② 需要精修时用 `+fetch --detail full` 拉回 JSONML ③ 逐章执行结构变换与样式叠加 |
+| **直接 JSONML 分段构造** | 长文档且含大量富结构 | 按章节分段构造 JSONML，每段写完校验通过后再写下一段，最后拼接 |
+
+> **脚手架策略警示**：Markdown 无法表达分栏/callout/色彩表头，拉回的 JSONML 只有纯文本骨架。精修阶段不是“在现有结构上加色”，而是“参照 RFC/Spec 重组结构”。
+
+> **MUST READ**：动手写 JSONML 前，必须先用 Read 工具读取 [doc-jsonml-cookbook.md](../format/doc-jsonml-cookbook.md) — 其中 §决策型文档骨架范例 有可直接复制修改的完整模板。
+> 节点类型和属性的权威定义见 [doc-jsonml-schema.md](../format/doc-jsonml-schema.md)。
+
+### ⚠️ JSONML 降级约束
+
+**禁止因一次校验失败就放弃 JSONML 降级为 Markdown。** 当用户需求已触发 JSONML 起稿判定时，JSONML 是实现其样式要求的首选路径。失败时的处理策略：
+
+1. **校验报错** → 读取错误信息，定位具体节点，修复后重试
+2. **JSON 语法错误** → 检查括号匹配、逗号、引号，修复后重试
+3. **反复失败（≥3 次）** → 尝试简化结构（减少嵌套、拆分复杂节点）再试
+4. **仍然失败** → 退化为「Markdown 脚手架 + JSONML 精修」路径（流程同上方策略表），并告知用户当前状况
+
+> “由于 JSONML 结构复杂且容易出错，改用 Markdown” — 这不是合法降级理由。必须先充分重试，且降级后仍需通过精修补回样式。
+
+### ⚠️ JSONML 结构严格约束（生成时必须遵守）
+
+每个节点是一个 JSON 数组：`[tagName, attributes?, ...children]`
+
+- **第一个元素**是字符串，表示标签名（如 `"p"`, `"h1"`, `"span"`, `"container"`）
+- **第二个元素**（可选）是一个 JSON 对象，表示属性（如 `{"uuid": "abc"}`）。如果无属性，可以直接进入子节点
+- **随后的元素**是子节点，可以是纯字符串（仅限 leaf span 内），也可以是另一个 JSONML 数组
+- **所有 `[` 必须有对应 `]`，所有 `{` 必须有对应 `}`，数组元素之间用 `,` 分隔，最后一个元素后不加 `,`**
+
+常见 LLM 生成错误（务必避免）：
+
+| 错误类型 | 示例 | 后果 |
+|---------|------|------|
+| 缺少闭合 `]` | `["p", {}, ["span", ...]` | JSON 解析失败 |
+| 多余逗号 | `["p", {},]` | JSON 解析失败 |
+| 缺少逗号 | `["p", {} ["span"]]` | JSON 解析失败 |
+| 引号不匹配 | `["p", {"uuid": "abc}]` | JSON 解析失败 |
+| 有序列表每项都设 `start:1` | `{"start":1}` 在每项重复 | 所有项编号重置为 1（显示为 a/a/a） |
+| 列表 `level` 从 1 开始 | `"level": 1` 作为顶级 | 顶级列表项多一层缩进；建议：顶级 `"level": 0`，子级 `"level": 1` |
+| 用 `fontFamily` 设字体 | `"fontFamily": "Arial"` | 校验报错；正确写法：`"fonts": {"ascii": "Arial", "eastAsia": "..."}` |
+| 用多个 span “换行” | 同一 `p` 内放两个 `span` | 不会产生换行；每个换行必须是独立的 `p` 节点 |
+
+### 基础结构
+
+文件内容是一个裸 JSONML 数组，根节点为 `"root"`：
+
+```json
+["root", {},
+  ["h2", {}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "章节标题"]]],
+  ["p", {}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "正文段落"]]]
+]
+```
+
+- 根节点固定 `"root"`（不是 `"body"`）
+- `--name` 已是 H1，JSONML 从 `h2` 开始
+- 表格结构是 `table → tr → tc`（无 `th`/`td`）
+- 分栏是 `table` + `"sr": true`，`tc` 建议设 `fill` 背景色
+- 有序列表：仅第一项设 `"start": 1`，后续项不设 `start`（系统自动递增）
+- 列表 `level` 建议从 0 开始：顶级项 `"level": 0`，子项 `"level": 1`，以此类推
+- uuid 必须显式提供（CLI 不自动生成）
+- **每行内容对应一个 `p` 节点** — 同一 `p` 内的多个 `span` 不会换行，只会横向拼接；需要换行时必须拆分为多个 `p`
+
+### 视觉设计要点
+
+构造时主动使用这些属性实现视觉效果：
+- **文字着色**：leaf 上 `"color": "#hex"`、`"highlight": "#hex"`
+- **highlight 色带**：标题 leaf 上 `"highlight": "#浅色"` 可形成色条效果（比 callout 更轻量的板块标记）
+- **字号**：leaf 上 `"sz": 14, "szUnit": "pt"`
+- **callout**：`["container", {"subType": "colorBlocks", "metadata": {"bgcolor": "#E8F5E9", "border": "left"}}, ...blocks]`
+- **callout + sticker**：`["container", {"subType": "colorBlocks", "metadata": {"bgcolor": "#FEF3F3", "showstk": true, "sticker": "火"}}, ...blocks]`
+- **表格单元格底色**：tc 上 `"fill": "#hex"`
+
+### 写入
+
+```bash
+dws doc +create --name "<文档名>" --content @./drafts/<name>.json --doc-format jsonml
+```
+
+### 验收
+
+读取 `+create` 返回的 `verified`、`steps`、`nodeId` 和验证结果。只有返回 `verified=false` 或结构化 partial/unknown 错误时，才进入恢复流程。
+
+---
+
+## 正文准备（未命中 JSONML 判定时）
+
+正文草稿先在工作目录内的 Markdown 文件中完成，推荐路径形如 `./drafts/<name>.md`。
+
+准备规则：
+
+- 只使用用户已提供或对话中已确认的正文素材。
+- 如果正文素材不足，先补齐文档目标、受众、章节和缺口；不要在本文中临时扩展跨产品采集流程。
+- **先按 [doc-style-guideline.md §2.0 类型判断决策表](./doc-style-guideline.md) 确定文档类型，再用对应类型的骨架样板（§2.1 决策型 / §2.2 执行型 / §2.3 说明型 / §2.4 知识沉淀型）**。不要套通用三段式。
+- **`--name` 已是 H1，正文从 `##` 开始**；正文内不要再写 `#` 一级标题（除非确实需要正文内再造一级 H1 并说明动机）。
+- 摘要、bullet、引用块、callout 等元素的使用边界以 style-guideline §3-§7 为准。
+- 同类信息保持一致：风险、状态、行动项各用一种元素 + 一种视觉语义（style-guideline §1.2 / §5）。
+- 临时文件必须保留真实换行，不能把换行写成字面量 `\n`。
+- Markdown 草稿阶段**不要**写 callout / 分栏 / 附件——这些留到「创建后的精修」用 `doc block insert` 操作（style-guideline §1.3）。
+- **图片素材闭环（硬规则）**：正文需求含图片/截图/图文并茂时，Markdown 只写文本骨架和图片占位说明；创建后用 `dws doc +media-insert --node <nodeId> --file ./相对路径` 插入，再用 `+media-list` 验证稳定 `resourceId`。禁止正文临时 URL、绝对路径、curl/wget 和本地依赖安装兜底。
+
+## 创建写入
+
+优先用工作目录相对文件一次创建并写入：
+
+```bash
+dws doc +create --name "<文档名>" --content @./drafts/<name>.md --doc-format markdown
+```
+
+创建到指定文件夹：
+
+```bash
+dws doc +create --name "<文档名>" --content @./drafts/<name>.md --folder <DOC_FOLDER_NODE_ID> --doc-format markdown
+```
+
+创建到知识库：
+
+```bash
+dws doc +create --name "<文档名>" --content @./drafts/<name>.md --workspace <WS_ID> --doc-format markdown
+```
+
+短纯文本才允许直接传 `--content`：
+
+```bash
+dws doc +create --name "<文档名>" --content "短内容" --doc-format markdown
+```
+
+返回后立即记录：
+
+| 字段 | 用法 |
+|------|------|
+| `nodeId` | 后续 `doc read`、`doc update`、`doc block`、`doc media` 的目标 |
+| `docUrl` | 最终交付给用户的链接；缺失时用 `doc info` 补查 |
+| `chunksWritten` | 判断是否触发自动分片；大于 1 时重点检查章节顺序 |
+
+## 内置回读验收
+
+`+create` 已在同一执行内回读验证，禁止再固定追加一次 `doc read`。检查结构化返回：
+
+验收要点：
+
+- 开头摘要、关键章节、表格表头、末尾章节都存在。
+- 回读文本顺序和临时 Markdown 一致。
+- 没有把字面量 `\n` 渲染成一整行。
+- 如果返回 `chunksWritten > 1`，看 `degradations`：为空即表示分片没有改变渲染结构，无需人工核对边界；非空时按其中的 `kind` 与 `line` 定点检查（如 `table_split` 表示该表被拆成多张、每张带重发的表头）。
+- 最终回复必须给用户 `docUrl`；如果只拿到 `nodeId`，说明链接字段未返回，并报告已尝试 `doc info`。
+
+## 缺失补救
+
+DWS 写入管道会自动处理长内容分片。只有出现以下情况才手工补片：
+
+- 返回 `doc_write_commit_unknown`（分片超时，提交状态未知）
+- 命令超时或只写入部分分片
+- 回读发现后半段缺失、章节乱序或表格损坏
+
+补救流程：
+
+1. 用 `+fetch` 的最小 scope 确认已经写到哪个章节。
+2. 从原始 Markdown 中截取缺失部分，写入 `./drafts/<name>-resume.md`。
+3. 追加缺失内容：
+
+```bash
+dws doc +update --node <nodeId> --command append --content @./drafts/<name>-resume.md --doc-format markdown
+```
+
+4. 使用 `+update` 返回的验证结果确认缺失章节已补齐；结果未知时再定点 `+fetch`。
+
+## 创建后的精修
+
+创建流程本身优先完成整篇正文。只有需要局部补充、插入附件、加 callout / 分栏、或无损结构调整时，才进入精修——**精修路径统一走 [doc-update-workflow.md](./doc-update-workflow.md)**。
+
+精修常见入口（**按 [doc-update-workflow.md §1.3](./doc-update-workflow.md) 优先级排序：JSONML 首选**）：
+
+- 单 block JSONML 精修（首选）：`doc block list --node <id> --content-format jsonml --block-id <uuid>` 取子树 → `doc block update --node <id> --block-id <uuid> --content-format jsonml --element '[...]'` 写回（uuid 必须 == --block-id；写入端默认执行 schema validate，详见 [doc-update-workflow.md §4.4](./doc-update-workflow.md)）
+- 整篇 JSONML 无损：`doc update --content-format jsonml --mode overwrite`（默认直接覆盖，适合一次改多处或改 root sectPr；担心并发覆盖时加 `--revision <N>` 触发并发检查）
+- 插入附件 / 图片：`+media-insert`，之后用 `+media-list` 验证稳定 `resourceId`
+- element JSON 次选：`doc block insert` / `doc block update` 不带 `--content-format jsonml` 时按老接口 JSON 解析；仅在 JSONML 不支持某字段时使用
+- markdown 兜底：`doc update --mode append`（末尾追加纯文本段落，无富结构需保留时）
+
+字段结构以 [`doc.md`](../../doc.md) 为准；何时用何种精修路径见 [doc-update-workflow.md §3「改写路径速查」](./doc-update-workflow.md)。
+
+## 交付口径
+
+只报告已经验证过的信息：
+
+- 文档标题
+- `docUrl` 或 `nodeId`
+- 已写入的正文范围
+- 回读验收结果
+- 如有缺失，说明缺失位置和补救状态
+
+未回读前，不要说内容完整或任务完成。

.agents/skills/dingtalk-doc/references/doc/style/doc-style-guideline.md

@@ -0,0 +1,404 @@
+# 钉钉文档排版规范
+
+本文规定 DWS 创建或编辑钉钉文档时的排版判断方法。核心流程：**确定文档类型 → 选骨架 → 按读者任务选元素 → 按视觉语义统一表达 → 软约束自检**。
+
+> 本文只定义内容结构和视觉规范，不定义命令路由。写入统一使用 `+create/+update/+checkpoint-update`，读取使用 `+fetch`，媒体使用 `+media-*`；原子命令仅用于精确 Schema 支持的专家路径。流程见 [doc-create-workflow.md](./doc-create-workflow.md) 和 [doc-update-workflow.md](./doc-update-workflow.md)。
+
+## 快速入口
+
+按任务定位章节，不必通读全文：
+
+| 任务 | 必读章节 |
+|------|---------|
+| 起稿前必读 | §2.0 + §2.0.1 + §3.0 |
+| 不确定文档类型 | §2.0 类型判断决策表 |
+| 写决策型（日报/汇报/方案选型） | §2.1 + §3 + §5 + §7 |
+| 写执行型（SOP/Runbook/接入指南） | §2.2 + §3 + §4.4 + §5 + §7 |
+| 写说明型（接口文档/能力清单） | §2.3 + §3 + §4.3/§4.4 + §7 |
+| 写知识沉淀（调研/技术方案/复盘） | §2.4 + §3 + §4.6 |
+| 颜色 / emoji 选择 | §5 |
+| 何时插图 | §6 |
+| 改写老文档 | 直接看 [doc-update-workflow.md](./doc-update-workflow.md) |
+| 写完自检 | §8 判定表 |
+
+---
+
+## 一、硬规则
+
+1. **`--name` 是 H1**：正文从 `##` 开始；正文内不写 `#`（除非确需正文内再造一级 H1 并说明动机）
+2. **同类信息同表达**：风险、状态、行动项、证据，每类只用一种元素 + 一种视觉语义（见 §5）
+3. **Markdown 草稿阶段只用稳定元素**：标题、段落、列表、checklist、表格、代码块；callout / 分栏 / 附件 / 复杂嵌套留到创建后用 `doc block insert` / `doc media insert` 精修
+4. **引用块只用于原文**：用户原话、会议摘录、外部材料原文；不许包装作者自己的结论
+5. **不编造 URL**：图片、链接、文档 ID 不确定时留 TODO 占位，向用户求证
+6. **以 shortcut 内置验证为准**：正常成功不追加整篇回读；partial/unknown 或富结构定点检查才使用最小范围 `+fetch`
+
+---
+
+## 二、按文档类型选骨架
+
+### 2.0 类型判断决策表
+
+按读者**第一个动作**选类型。若同时符合多类，按表中第一行优先：
+
+| 读者第一个动作 | 类型 | 推荐格式 | 视觉锚点 | 跳转 |
+|----|----|----|----|----|
+| 按步骤操作（升级、部署、接入、上手） | 执行型 | markdown 起稿 + JSONML 精修（callout 标高风险） | 有序列表 / 代码块 / ⚠️ 高风险 callout | §2.2 |
+| 拿结论做选择 / 决策 / 汇报判断 | 决策型 | **直接 JSONML 起稿**（不走 markdown → 精修；见 [doc-create-workflow.md §JSONML 起稿](./doc-create-workflow.md#jsonml-起稿判定)） | ✅ 推荐 callout / 对比表 / 数据加粗 | §2.1 |
+| 查参数 / 能力 / 限制 / 错误码 | 说明型 | markdown（表格密集、callout 偶尔） | 参数表 / 错误码表 | §2.3 |
+| 看推理链路 / 分析 / 调研过程 | 知识沉淀型 | 含对比/数据可视化时**直接 JSONML 起稿**；纯叙事时 markdown + 精修（见 [doc-create-workflow.md §JSONML 起稿](./doc-create-workflow.md#jsonml-起稿判定)） | ℹ️ 信息 callout / 引用块（原话）/ 流程图 | §2.4 |
+| 以上都不像 | 兜底走知识沉淀型 §2.4 | — | — | — |
+
+> **推荐格式列**：起稿统一用 markdown，富结构（callout/分栏/带颜色的对比/sectPr）一律走精修阶段的 JSONML；JSONML 形态优先级与命令见 [doc-update-workflow.md §1.3](./doc-update-workflow.md)。决策型默认进 JSONML 优先，因为汇报/方案的视觉锚点（callout + 彩色表头）markdown 表达不出来。
+
+### 2.0.1 写前三问（草稿前 30 秒自答）
+
+下笔前先答三句话；答不出第二、三句说明信息不足，回 [doc-create-workflow.md «创建前检查»](./doc-create-workflow.md) 补齐：
+
+1. **读者**：谁打开这篇文档？读完要做什么动作（操作 / 选择 / 查参数 / 看推理）？
+2. **唯一记忆点**：读者关掉文档后，最想让他记住的一句话是什么？这句话决定开头摘要 / callout 该写什么。
+3. **形态**：按 §2.0 推荐格式列 + [doc-create-workflow.md §JSONML 起稿判定](./doc-create-workflow.md#jsonml-起稿判定) 决定路径。命中判定条件（决策型 / 含对比的知识沉淀型 / 用户意图关键词）→ **直接 JSONML 起稿**（但必须先完成 [doc-create-workflow.md §设计规划](./doc-create-workflow.md#设计规划jsonml-起稿前必做) 的 4 步规划）；未命中 → markdown 起稿 + 创建后精修。
+
+写完自检时回看这三个答案：开头有没有兑现「记忆点」、形态有没有兑现「推荐格式」。两条任一不兑现，按 §8 自检表对应行动。
+
+### 2.1 决策型（日报、月报、复盘、方案选型、汇报）
+
+**适用**：读者读完要拿到判断或做选择。
+
+| 段位 | 内容 | 推荐元素 |
+|------|------|----------|
+| 开头 | 结论、推荐方案、关键数据 | 2-4 条 bullet 摘要 |
+| 主体 | 选项 / 维度 / 风险 / 数据 | 对比表、风险表、关键指标 |
+| 收尾 | 下一步、需用户决策事项 | callout（仅决策有时限或重大风险）|
+
+**反推荐**：长背景铺垫、连续叙事、结论藏在文末。
+
+样板：
+
+~~~~markdown
+## 摘要
+- 推荐方案 A：上线快、依赖已有流程
+- 主要风险：权限配置需补
+- 决策时限：本周五前
+
+## 方案对比
+| 维度 | 方案 A | 方案 B | 建议 |
+|------|--------|--------|------|
+| ... | ... | ... | ... |
+
+## 下一步
+- [ ] @负责人 完成权限配置
+~~~~
+
+### 2.2 执行型（SOP、TODO、行动方案、接入指南、Runbook）
+
+**适用**：读者读完要按步骤操作。
+
+| 段位 | 内容 | 推荐元素 |
+|------|------|----------|
+| 开头 | 目标、范围、前置条件 | 短段落 + checklist（前置条件）|
+| 主体 | 顺序步骤、操作命令、校验方法 | 有序列表、代码块、流程截图 |
+| 收尾 | 异常处理、回滚方法 | 表格（错误码 → 处理）或 callout（高风险动作）|
+
+**反推荐**：多动作压成一段、缺负责人、缺校验方法。
+
+样板：
+
+~~~~markdown
+## 目标
+将服务 X 从 v1 升级到 v2，零宕机切换。
+
+## 前置条件
+- [ ] 备份当前配置
+- [ ] 通知下游
+
+## 操作步骤
+1. 拉取最新镜像：`docker pull x:v2`
+2. 灰度切流：5% → 50% → 100%
+3. 每步校验：观察 dashboard，错误率 < 0.1%
+
+## 异常处理
+| 错误码 | 含义 | 处理 |
+|--------|------|------|
+| ... | ... | ... |
+~~~~
+
+### 2.3 说明型(产品说明、新人手册、接口文档、能力清单)
+
+**适用**：读者按需查阅，不一定从头读到尾。
+
+| 段位 | 内容 | 推荐元素 |
+|------|------|----------|
+| 开头 | 适用对象、能力概要 | 短段落或 bullet |
+| 主体 | 功能矩阵、参数表、使用示例 | 表格、代码块（带语言标识）|
+| 收尾 | 限制、注意事项、变更记录 | callout（限制）、表格（变更记录）|
+
+**反推荐**：长结论、未分类的功能混排、缺示例。
+
+样板（其中"调用示例"位置应放一个 `bash` 语言标识的代码块演示 dws 命令）：
+
+~~~~markdown
+## 适用对象
+本接口供 DWS 内部模块调用，不暴露给外部租户。
+
+## 能力清单
+| 能力 | 说明 | 必要参数 |
+|------|------|----------|
+| ... | ... | ... |
+
+## 调用示例
+（此处放一个 bash 代码块演示 dws 命令）
+
+## 限制
+> ⚠️ 单次返回最多 1000 个 block，超出请分页。
+~~~~
+
+### 2.4 知识沉淀型（调研报告、技术方案、项目复盘、学习笔记）
+
+**适用**：读者要看到推理链路，理解为什么是这个结论。
+
+| 段位 | 内容 | 推荐元素 |
+|------|------|----------|
+| 开头 | 背景、问题、目标 | 短段落 |
+| 主体 | 分析过程、对比、推理 | 小标题分层、表格、引用块（外部原文）|
+| 收尾 | 结论、证据链、附件 | 附件（原始材料）|
+
+**反推荐**：结论先行但缺证据链、引用块包装作者自己的判断。
+
+---
+
+## 三、按读者任务选元素（五列表）
+
+### 3.0 AI 文档常见反模式
+
+下笔前快速扫一遍，命中任何一条立刻按右列改：
+
+| 反模式 | 信号 | 改法 |
+|------|------|------|
+| 万篇一律的「摘要-细节-总结」三段式 | 每篇文档第一节都是「## 摘要」+ 三条 bullet | 按 §2.0 选骨架；执行型不要写摘要，开门见山列前置条件 |
+| 全篇 H2 平铺 | 标题层级单一、没有 H3 收纳同主题 block | 按 §7 量化标尺拆 §N.N 子标题 |
+| 全列表无表无 callout | 风险、对比、数据全部塞进 bullet | 对比改表（§4.2）、风险改 callout（§4.7）、数据加粗（§5）|
+| 结论藏文末 | 关键判断在最后一段才出现 | 按 §2.1 决策型骨架，结论 / 推荐方案前置到摘要 bullet |
+| markdown 包不住富结构却硬包 | 草稿里出现 `> ⚠️ ...`、`【callout】`、表格里塞颜色 hex | 按 §2.0 推荐格式切到 JSONML 精修阶段；草稿留占位 |
+| 同一语义两种视觉表达 | 风险既用 ⚠️ 又用红色文字也加 callout | §5 收敛到一组（emoji + 颜色 + 元素都按表对齐）|
+| 装饰性 emoji 满天飞 | 段落、列表项、普通段每行都带 emoji | §5 规则：emoji 只在 callout / 状态标记 / `H2/H3` 标题前 |
+| 编造 URL / 文档 ID / 图片地址 | 出现 `https://example.com/...`、`docs.dingtalk.com/xxx` 占位形 | §4.5 / §6 留 TODO 占位，向用户求证 |
+
+### 3.1 读者任务对照
+
+骨架定好后按读者要完成的具体动作选元素。扫"常见误用"列，命中则按"修复"列调整。
+
+| 读者任务 | 推荐版式 | 避免 | 常见误用 | 修复方法 |
+|----------|----------|------|----------|----------|
+| 快速了解重点 | 开头 2-4 条 bullet 摘要；重大风险用 callout | 长背景；引用块包装摘要 | 三段式硬套，背景写了 5 段才到结论 | 结论提前到第一条 bullet，背景挪到末尾或删 |
+| 做选择 | 多维比较用表格；轻量两项可分栏（精修阶段）| 只两个对象做大宽表 | 两个方案做 6 列对比表，每列一句话 | 改为两段并列短文，或保留 3 维核心对比 |
+| 看状态 | 状态表（事项/状态/阻塞/下一步）或 checklist | 长段落描述多个状态 | "A 在做、B 卡住、C 完成…" 写一段 | 转为状态表，每行一个事项 |
+| 执行动作 | 有序列表；待办用 checklist；分支用条件表 | 一段话写多个动作 | "先备份再升级然后切流" 写一段 | 拆为有序列表，每步独立 |
+| 理解关系 | 小标题分层；复杂关系用图示或附件 | 把复杂关系压成连续段落 | 系统依赖关系写了三段叙事 | 建议用户上传架构图（§6）|
+| 查证事实 | 引用块保留原文；真实文件用附件 | 引用块包装改写后的总结 | 作者自己的结论加 `>` 装成引用 | 改为普通段落或加粗 |
+| 阅读背景 | 小标题 + 短段落；过长时拆列表 | 为结构化把叙事硬塞表格 | 把"项目历史"硬做时间表 | 用小标题分段叙事 |
+
+**推荐表头**：
+
+- 风险表：`风险 / 影响 / 缓解 / 负责人`
+- 状态表：`事项 / 状态 / 阻塞点 / 下一步`
+- 对比表：`维度 / 方案 A / 方案 B / 建议`
+
+---
+
+## 四、元素边界规范
+
+### 4.1 标题与段落
+
+- 正文从 `##` 开始（H1 已被 `--name` 占用）
+- 标题层级 ≤ 4 层（§7）
+- 单段过长先拆段，再考虑换元素
+
+### 4.2 列表与 checklist
+
+- 普通列表：并列要点
+- 有序列表：顺序步骤
+- checklist：待办状态（含 `- [ ]` / `- [x]`）
+
+列表项里开始出现"负责人 / 截止时间 / 状态"这类字段时，改用表格。
+
+### 4.3 表格
+
+表格用于字段稳定的信息。
+
+- 单元格写短句；解释超过两行放表格下方段落
+- 列数 ≤ 6，行数 ≤ 20（§7 给具体拆法）
+
+### 4.4 代码块
+
+必须带语言标识（`bash` / `python` / `json` / `go` 等）；无对应语言时用 `text`。
+
+形如（用 \`\`\` 三反引号围栏 + 紧跟语言名 + 闭合 \`\`\`）：
+
+~~~~markdown
+```bash
+dws doc +fetch --node abc123
+```
+~~~~
+
+约束：
+
+- 单块 ≤ 80 行；超长时拆为多个语义独立的块，或作为附件上传
+- 与正文有强关联时，在代码块前后用一句话说明用途
+- **禁止**在代码块里写敏感信息（token、密码、内部 IP）
+
+### 4.5 链接与卡片
+
+| 场景 | 用法 | 典型例 |
+|------|------|--------|
+| 行内引用 | `[文字](url)` | PR/Issue/外部博客 |
+| 强调外部资源 | 创建后 `doc block insert` 插入卡片 | 外部 PRD、Figma、Notion 主页 |
+| 引用钉钉文档 | 直接粘贴 alidocs URL | @文档（DWS 自动渲染卡片）|
+
+**禁止**：编造看似真实的 URL；不确定的链接留 TODO。
+
+### 4.6 引用块
+
+只用于需保留原貌的内容：用户原话、会议摘录、外部材料原文、API 错误信息原文。
+
+**禁止**把作者自己的摘要、推荐结论或判断写成引用块。
+
+### 4.7 Callout
+
+每篇文档 0-2 个（§7）。
+
+| 场景 | 处理 |
+|------|------|
+| 创建前必须确认的限制 | ✅ 用 callout |
+| 会改变结论的风险 | ✅ 用 callout |
+| 需要用户立即决策的分歧 | ✅ 用 callout |
+| 普通章节说明 | ❌ 普通段落 |
+| 装饰性章节开头提示 | ❌ 删除 |
+| 可放进摘要 bullet 的一般结论 | ❌ 放摘要 |
+
+callout 是块级元素，**Markdown 草稿阶段不支持**。创建后用 `doc block insert` 精修。
+
+**形态优先级（按 [doc-update-workflow.md §1.3](./doc-update-workflow.md)）**：
+
+1. **首选 JSONML**：`doc block insert --content-format jsonml --element '["container",{"uuid":"...","subType":"colorBlocks","metadata":{"bgcolor":"...","border":"..."}},["p",...]]'`，bgcolor/border 取本文 §5 颜色表
+2. **次选 element JSON**：`doc block insert --element '{"blockType":"callout","callout":{...}}'`，字段以 [doc.md](../../doc.md) 为准；JSONML 节点完整结构见 [doc-jsonml-schema.md](../format/doc-jsonml-schema.md) 的 `container[subType="colorBlocks"]`，可复制范例见 [doc-jsonml-cookbook.md](../format/doc-jsonml-cookbook.md)
+
+### 4.8 分栏（精修阶段）
+
+分栏适合两个对象的轻量并置。**Markdown 草稿阶段无法直接写入**，必须创建后用 `doc block insert`。
+
+**形态优先级（按 [doc-update-workflow.md §1.3](./doc-update-workflow.md)）**：
+
+1. **首选 JSONML**（保真度最高、和现有 block 结构一致）：
+
+```bash
+dws doc block insert --node <nodeId> --content-format jsonml \
+  --element '["container",{"uuid":"cols1","subType":"columns","metadata":{"size":"2"}},["container",{"uuid":"cols1c1","subType":"column"},["p",{"uuid":"cols1c1p"},["span",{"data-type":"text"},["span",{"data-type":"leaf"},"左栏"]]]],["container",{"uuid":"cols1c2","subType":"column"},["p",{"uuid":"cols1c2p"},["span",{"data-type":"text"},["span",{"data-type":"leaf"},"右栏"]]]]]'
+```
+
+2. **次选 element JSON**（老接口，仅当 JSONML 不便构造时）：
+
+```bash
+dws doc block insert --node <nodeId> --content-format element \
+  --element '{"blockType":"columns","columns":{"size":2},"children":[{"blockType":"paragraph","paragraph":{"text":"左栏"}},{"blockType":"paragraph","paragraph":{"text":"右栏"}}]}'
+```
+
+每栏需要多个字段时**改用表格**。轻量两项对比优先并列短段落，分栏只在视觉强对照需要时使用。完整 JSONML 字段见 [doc-jsonml-schema.md](../format/doc-jsonml-schema.md) 的 `container[subType="columns"]`，可复制范例见 [doc-jsonml-cookbook.md](../format/doc-jsonml-cookbook.md)。
+
+### 4.9 附件与图片
+
+```bash
+dws doc +media-insert --node <nodeId> --file ./diagram.png
+```
+
+- 插入后在前后用一句话说明它支持哪个结论
+- 插入后用 `doc block list` 验证存在
+- **禁止**在 Markdown 里编造无法访问的图片 URL
+- **禁止**把 `alidocs.dingtalk.com/i/nodes/...`、`alidocs.dingtalk.com/i/document/...` 或任何文档/节点页面 URL 当作图片 src。图片必须位于工作目录内，再通过 `dws doc +media-insert --node <docId> --file ./相对路径` 插入
+- 何时主动建议用户提供图见 §6
+
+---
+
+## 五、颜色与视觉语义
+
+**全篇必须保持语义一致**——同一语义只用同一组视觉表达。
+
+| 语义 | emoji 前缀 | callout bgcolor (hex) | callout border (hex) | 文字加粗 | 典型用法 |
+|------|----------|------------------------|----------------------|---------|----------|
+| 信息说明 | ℹ️ | `#E8F2FE`（淡蓝）| `#B3D4FC` | — | 普通提示、说明性补充 |
+| 推荐结论 | ✅ | `#E3F8E2`（淡绿）| `#B7E4B5` | 是 | 推荐方案、已确认结论 |
+| 风险/错误 | ⚠️ / ❌ | `#FDE2E0`（淡红）| `#F5C2C7` | 是 | 风险、错误码、不可逆操作 |
+| 待确认 | ❗ | `#FFF6D9`（淡黄）| `#FFE69C` | — | 待用户决策、待补齐信息 |
+| 中性辅助 | — | `#F4F5F7`（淡灰）| `#DEE2E6` | — | 非关键背景、变更记录 |
+
+调用规则：
+
+- callout 字段格式以 [doc.md](../../doc.md) / [doc-jsonml-schema.md](../format/doc-jsonml-schema.md) 为准
+- 调 `doc block insert --element` 插入 callout 前若字段名不确定，先用 `doc block list --node <id> --block-type callout` 抓现有实例确认字段
+- 颜色属性值只接受 hex；**禁止**把语义名（如 `light-blue`）当属性值
+- 关键指标用加粗 + ↑↓ 或 +/- 同时标注方向（不仅依赖颜色，兼容色觉无障碍）
+- emoji 只在 callout、状态标记、`H2/H3` 标题前使用，不在普通段落和列表项里滥用
+
+---
+
+## 六、何时使用图示
+
+以下信息特征出现时，**主动建议用户提供截图或示意图**，不用纯文本承载：
+
+| 内容特征 | 信号词 | 建议图示 |
+|----------|--------|----------|
+| 多步骤流程（≥4 步）| "先…然后…最后"、"步骤 1/2/3" | 流程图截图 |
+| 系统/模块依赖 | "调用"、"依赖"、"上游/下游"、"请求→响应" | 架构图截图 |
+| 时间线/里程碑 | "Q1/Q2"、"阶段一→阶段二"、日期序列 | 时间线图 |
+| 数值趋势 | 带数字的时间序列、"增长/下降"、百分比变化 | 折线图/柱状图截图 |
+| 占比分布 | "占比"、"份额"、百分比加总 ≈100% | 饼图/树状图截图 |
+| 层级递进 | "基础→进阶→高级"、"L1/L2/L3"、"核心→外围" | 金字塔图 |
+| 因果/根因 | "导致"、"根因"、"原因"、"影响因素" | 鱼骨图 |
+| 闭环/飞轮 | "正循环"、"驱动"、"闭环"、"反馈" | 飞轮图 |
+
+**规则**：
+
+1. 关键流程/架构/趋势能图示就图示，不用纯文本承载
+2. **禁止**在 Markdown 里编造图片 URL（如 `![](https://example.com/diagram.png)`）
+3. 正文里留占位（如 `📌 待补充：架构图`），向用户主动询问能否提供截图
+4. 用户提供后用 `dws doc +media-insert --node <id> --file ./xxx.png` 插入，并在图前后补一句说明
+
+---
+
+## 七、量化标尺（软约束）
+
+超出时不一定要重写，但要按"超出处理"列采取具体动作：
+
+| 维度 | 建议上限 | 超出处理（具体动作）|
+|------|---------|---------------------|
+| 单段行数 | ≤ 5 行 | 按句号拆段；或抽出并列要点转 bullet 列表 |
+| 单章节 block 数 | ≤ 12 | 按子主题拆 `### N.N` 子标题；合并冗余 block |
+| 标题层级 | ≤ 4 层 | 把最深层标题降级为加粗段落或列表 |
+| 表格列数 | ≤ 6 | 按"维度类别"拆为多个子表，前 2 列保留作锚 |
+| 表格行数 | ≤ 20 | 拆表（按类别）；或转附件 `doc media insert --file table.xlsx` |
+| callout 数量 | ≤ 2 / 篇 | 同语义 callout 合并；非关键 callout 降级为加粗或行内 emoji |
+| 代码块行数 | ≤ 80 | 按"功能段"拆为多个独立块；超长输出转附件 |
+| 连续纯文本段 | ≤ 3 段 | 中间穿插 `##/###` 标题、bullet、或表格分组 |
+
+---
+
+## 八、自检判定表
+
+写完后逐条扫描，命中"判定"列的情况按"动作"列处理：
+
+| 判定 | 动作 |
+|------|------|
+| 命中 §3.0 任一反模式 | 按 §3.0 对应行改 |
+| 文档类型不属于 §2 四类之一 | 回 §2.0 决策表归类；仍归不出走 §2.4 兜底 |
+| `--name` 之外正文里还有 `#` 一级标题 | 改为 `##`，除非确需且已说明动机（§4.1）|
+| callout 数 > 2 | 按 §4.7 合并同语义；非关键 callout 降级 |
+| 单段 > 5 行 | 按 §7 拆段或转列表 |
+| 单章节 block 数 > 12 | 按 §7 拆 `### N.N` 子标题 |
+| 表格列 > 6 或行 > 20 | 按 §7 拆表或转附件 |
+| 代码块缺语言标识 | 补语言标识；无对应语言用 `text`（§4.4）|
+| 代码块 > 80 行 | 按功能段拆，或转附件（§7）|
+| 同一语义出现 ≥2 种视觉表达 | 按 §5 收敛到同一组 |
+| 引用块里写的是作者自己的结论 | 改为加粗段落或普通段落（§4.6）|
+| Markdown 草稿里写了 callout / 分栏 | 删掉，转到精修阶段用 `doc block insert`（§4.7 / §4.8）|
+| 内容含 "先…然后…"、"调用/依赖"、"Q1/Q2"、"导致/根因" 等信号词但写成纯文本 | 按 §6 询问用户能否补图 |
+| 出现编造的图片 URL / 文档 URL | 删除或改为 TODO 占位（§4.5 / §6）|
+| 写入完成但未回读 | 按 [doc-create-workflow.md «回读验收»](./doc-create-workflow.md) 或 [doc-update-workflow.md §6](./doc-update-workflow.md) 回读 |

.agents/skills/dingtalk-doc/references/doc/style/doc-update-workflow.md

@@ -0,0 +1,316 @@
+# 钉钉文档改写流程
+
+本文只处理已有文档的结构和排版策略。普通执行入口固定为 `+fetch`、`+update` 或 `+checkpoint-update`；这些 shortcut 统一确认、写入与验证。原子 `doc read/update/block` 只保留给 shortcut 未公开参数的 JSONML 专家路径，使用前必须读取精确 leaf Schema。
+
+## 适用边界
+
+进入本文前，必须已经确认用户要改写的是已有钉钉文档 (`adoc`)。如果用户要新建、要操作表格 / AI 表格 / 文件 / 知识库空间 / 发消息，不要套用本文。
+
+本文覆盖：
+
+- 已有文档的局部改写、润色、章节补充
+- 段落 ↔ 列表 ↔ 表格 的形态转换
+- 块级精修（callout、分栏、附件插入）
+- overwrite 整篇改写的风险提示与执行
+- JSONML 无损结构改写的入口
+
+本文不覆盖：
+
+- 新建文档（见 [doc-create-workflow.md](./doc-create-workflow.md)）
+- 知识库空间管理
+- 文档权限、消息分发、待办分派
+
+---
+
+## 一、核心原则
+
+### 1.1 精准手术优于全量覆盖
+
+**默认走精准手术**——只改用户指定的章节或 block，不动其他内容。具体路径见 §3 速查表。
+
+### 1.2 保真约束
+
+改写时必须**原样保留**以下要素，**不许**替换为纯文本/姓名/链接/占位符：
+
+- `@人` 引用（用户、机器人、群）
+- `@文档` / `@群` 等卡片引用
+- 已上传的附件、图片
+- 用户原话引用块
+- 表格表头（除非语义错误且用户确认）
+
+JSONML 模式下这些元素的节点结构见 [doc-jsonml-schema.md](../format/doc-jsonml-schema.md)。
+
+### 1.3 编辑形态优先级
+
+**改写已有文档优先 JSONML，markdown / element 只在 JSONML 不适用时兜底**：
+
+| 优先级 | 形态 | 适用 |
+|--------|------|------|
+| ① 首选 | `--content-format jsonml` | 保真度最高；callout / 分栏 / 表格 / @人 / 附件 / 颜色 / 嵌套结构都能 1:1 round-trip；写入端有 validator 兜底（§4.4） |
+| ② 次选 | `--content-format element`（JSON，老接口） | JSONML 不支持某个块字段时；或快速插入 callout / 分栏不想构造 JSONML 时；不保真改写正文 |
+| ③ 兜底 | markdown（不带 `--content-format` 即默认）| 纯文本追加、整篇重排骨架；callout / 分栏 / 颜色 / 部分属性会被 markdown 还原过程丢失 |
+
+实操判断：
+
+- 用户给已有 nodeId 要「改一段、改属性、加 callout、动结构」——走 §4.4 JSONML 路径
+- 用户要「在末尾追加一节纯文本 / 整篇按新骨架重写」——走 §4.2 / §4.5 markdown 路径
+- 同一次任务里两类需求都有——分别走对应路径，**不要**为了省事全部 markdown overwrite
+
+### 1.4 写入风险提示
+
+`doc update` 在以下场景可能产生**静默失败**（返回 success=true 但实际写入不完整）：
+
+- **overwrite 降级为 append**：大文档 overwrite 被后端静默降级，导致旧内容未清除、新内容追加在末尾
+- **分块 append 内容截断**：超长文档分片写入时部分片段丢失或顺序错乱
+- **编码/通道问题**：特殊终端下 UTF-8 内容传输乱码
+
+因此写入必须通过带确认与验证的 shortcut。`+update/+checkpoint-update` 返回的验证结果是主证据；禁止无条件追加一次原子 `doc read`，只有 partial/unknown 或需要定点结构检查时才用 `+fetch`。
+
+---
+
+## 二、读取策略
+
+改写前必须先读现有内容，但要节省上下文。按粒度选读取方式（按 §1.3 优先级排序，**优先 JSONML**）：
+
+| 用户需求 | 读取方式 | 定位方法 |
+|----------|----------|----------|
+| 单块精修（首选）| `doc block list --node <id> --content-format jsonml` → 拿 uuid → `doc block list --node <id> --content-format jsonml --block-id <uuid>` 读子树 | 节点结构见 [doc-jsonml-schema.md](../format/doc-jsonml-schema.md) |
+| 多处保真改写 / 改 root sectPr | `+fetch --node <id> --detail full` | 解析 JSONML；担心并发覆盖时记下 revision |
+| 整篇按新骨架重写（纯文本场景）| `+fetch --node <id>` | 直接处理 markdown 全文 |
+| 末尾追加纯文本章节 | 不必读全文，直接 §4.2 append | 必要时 `+fetch --scope section` 看末尾衔接 |
+| 老接口快速找 BLOCK_ID（无需 jsonml 时）| `doc block list --node <id>` | 默认输出 JSON；用 `grep -B2 -A2 "<关键词>"` 在 children 里定位（结构 `{"blocks":[{...,"children":[...]}]}`，jq 需 `..\|.text? // empty` 递归查文本） |
+
+读取后，把改写计划告诉用户（要改哪几节、走 JSONML 还是 markdown、改成什么形态），等用户确认后再写。
+
+---
+
+## 三、改写路径速查
+
+按用户请求形态查表，跳到对应详细节执行（**按 §1.3 优先级排序：JSONML 路径在前，markdown / element 兜底在后**）：
+
+| 用户请求 | 推荐路径 | 详细节 |
+|----------|----------|--------|
+| 改某一章 / 某一节（首选） | block list 拿 uuid → block update --content-format jsonml | §4.4 路径 B |
+| 改属性 / 改 mark / 改颜色不动文本 | block update --content-format jsonml | §4.4 路径 B |
+| 插入 callout / 分栏 / 嵌套结构（首选） | block insert --content-format jsonml --element '[...]' | §4.4 路径 B |
+| 多处保真改写 / 改 root sectPr | 整篇 JSONML overwrite（默认不带 --revision；并发敏感时再加） | §4.4 路径 A |
+| 中间插一段纯文本 | block insert（element JSON 或 jsonml） | §4.3 / §4.4 |
+| 末尾追加一节纯文本 | doc update --mode append（markdown） | §4.2 |
+| 整篇按新骨架重写 | overwrite 全文（优先 JSONML；纯文本可用 markdown） | §4.5 |
+| 段落转表格 / 表格转段落 | block update --content-format jsonml；或 markdown overwrite 单段 | §4.4 / §4.1 |
+| 插入附件 / 图片 | doc media insert | §4.3 |
+| 一次追加 >200KB 内容 | 分块 append + 用户风险确认 + 逐片记录 | §4.6 |
+| 兜底：纯文本快速替换某段 | doc update --content overwrite（markdown） | §4.1 |
+
+---
+
+## 四、改写路径详细
+
+> **首选 JSONML（§4.4）**——保真度最高且 validator 兜底；本节其余路径（markdown / element）仅在 §1.3 列出的"次选 / 兜底"场景下使用。
+
+### 4.1 段落级 overwrite（markdown 兜底路径）
+
+> 适用范围：**纯文本**改写一段或替换某节内容。若该段含 callout / 分栏 / 颜色 / @人 / 附件 / 嵌套结构，**改走 §4.4 路径 B**——markdown 还原会丢失这些元素。
+
+```bash
+dws doc +update --node <nodeId> --command overwrite --content "<新内容>" --doc-format markdown
+```
+
+或写入临时文件：
+
+```bash
+dws doc +update --node <nodeId> --command overwrite --content @./drafts/<name>-section.md --doc-format markdown
+```
+
+> ⚠️ **overwrite 须用户确认**——尤其是整篇文档 overwrite。
+
+### 4.2 追加章节（markdown）
+
+> 适用范围：在文档末尾加 X 章 / 补充纯文本段落。追加内容若含 callout / 分栏等富结构，先用本节 append 一个占位段落，再用 §4.4 路径 B 的 `block insert --content-format jsonml` 替换/精修。
+
+```bash
+dws doc +update --node <nodeId> --command append --content @./drafts/<name>-append.md --doc-format markdown
+```
+
+按 [doc-style-guideline.md](./doc-style-guideline.md) 的元素选择规则准备追加内容。
+
+### 4.3 块级精修（element JSON 次选路径）
+
+> 适用范围：JSONML 不支持某个字段时，或快速插入 callout / 分栏不想构造 JSONML 时。**默认优先 §4.4 路径 B**（block update/insert `--content-format jsonml`），本节是老接口次选路径。
+
+```bash
+# 列出所有 block，定位 BLOCK_ID
+dws doc block list --node <nodeId>
+
+# 改一个 block 的文本
+dws doc block update --node <nodeId> --block-id <BLOCK_ID> --content "替换后的内容" --content-format element
+
+# 在某个 block 后插入
+dws doc block insert --node <nodeId> --ref-block <BLOCK_ID> --where after --heading "补充说明" --level 2 --content-format element
+
+# 插入复杂块（callout / 分栏）—— element 默认按 JSON 解析
+dws doc block insert --node <nodeId> --ref-block <BLOCK_ID> --where after --content-format element \
+  --element '{"blockType":"callout","callout":{"emoji":"⚠️","bgColor":"#FDE2E0","content":[{"text":"高风险操作，先备份"}]}}'
+
+# 若改写过程已经在用 JSONML，整段精修也可走 jsonml 路径（uuid 必须 == --block-id）
+dws doc block insert --node <nodeId> --ref-block <BLOCK_ID> --where after --content-format jsonml \
+  --element '["container",{"uuid":"co_new","subType":"colorBlocks","metadata":{"bgcolor":"#FDE2E0","border":"#F5C2C7"}},["p",{"uuid":"co_new_p1"},["span",{"data-type":"text"},["span",{"data-type":"leaf"},"高风险操作，先备份"]]]]'
+```
+
+字段结构以 [doc-block.md](../doc-block.md) 为准，不要猜。callout 字段名不确定时，先用 `doc block list --node <id> --block-type callout` 抓现有 callout 实例看真实字段。整段 JSONML 形态与可复制范例见 §4.4 与 [doc-jsonml-cookbook.md](../format/doc-jsonml-cookbook.md)。
+
+### 4.4 JSONML 无损改写（**首选路径**）
+
+> 改写已有文档**默认走本节**——保真度最高，callout / 分栏 / 表格 / @人 / 附件 / 颜色 / 嵌套都能 1:1 round-trip；写入端有 validator 兜底。其他路径（§4.1/4.2/4.3/4.5 markdown）仅在 §1.3 列出的"次选 / 兜底"场景下使用。
+
+两条子路径：
+
+**路径 B：单 block JSONML 精修（最常用——只动一个 block 时的默认选择）**
+
+```bash
+# 1. 列出所有 block 拿到 uuid
+dws doc block list --node <nodeId> --content-format jsonml
+
+# 2. 读单个 block 完整子树
+dws doc block list --node <nodeId> --content-format jsonml --block-id <BLOCK_UUID>
+
+# 3. 改完后写回（uuid 必须 == --block-id）
+dws doc block update --node <nodeId> --block-id <BLOCK_UUID> --content-format jsonml \
+  --element '["p", {"uuid": "<BLOCK_UUID>"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "新内容"]]]'
+
+# 在某个 block 前/后插入新 block
+dws doc block insert --node <nodeId> --ref-block <BLOCK_UUID> --where after --content-format jsonml \
+  --element '["container", {"uuid": "co1", "subType": "colorBlocks", "metadata": {"bgcolor": "#E8F2FE", "border": "#B3D4FC"}}, ["p", {"uuid": "co1p1"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "提示内容"]]]]'
+```
+
+**路径 A：整篇 JSONML overwrite（一次改多处、改 root 级 sectPr 才用）**
+
+```bash
+# 1. 读出完整 JSONML 结构（输出含 revision，普通改写场景下不需要）
+dws doc +fetch --node <nodeId> --detail full --format json
+
+# 2. 解析 JSON，修改 jsonml 数组中的目标节点
+#    节点结构见 doc-jsonml-schema.md，可复制范例见 doc-jsonml-cookbook.md
+
+# 3. 写回工作目录内相对文件 ./drafts/doc_modified.json，格式 {"jsonml": [...]}
+
+# 4. 提交修改（默认直接覆盖，不做并发检查）
+dws doc +update --node <nodeId> --command overwrite --content @./drafts/doc_modified.json \
+  --doc-format jsonml
+```
+
+> **并发安全模式（担心被并发覆盖时使用）**：如果担心多 agent 同时改这篇文档，可以把第 1 步 read 返回的 `revision` 通过 `--revision <N>` 透传给第 4 步：服务端会做并发检查，版本不一致返回 `VersionConflict`，此时回到第 1 步重读重写即可。普通单 agent 改写场景默认不传 `--revision`。
+
+#### JSONML 写入端的 validator
+
+写入命令（`doc create/update` + `doc block insert/update`）走 **validate** 一步，不做结构修复：
+
+| 行为 | 缺省 | `--fix-jsonml` |
+|------|------|----------------|
+| JSON 语法修复（括号/逗号补全） | ✗ | ✓（打印 `[FIX]`） |
+| validator 阻断（HasErrors → 拒发） | ✓ | ✓ |
+| root 校验（仅 doc create/update） | ✓ | ✓ |
+
+报错格式（agent 友好）：
+
+```
+$[2][2]: paragraph child must be span wrapper, got raw string.
+Suggestion: ["span",{"data-type":"text"},["span",{"data-type":"leaf"},"<your text>"]]
+```
+
+设计要点：
+
+- 缺省为严格模式：不做结构修复，裸字符串、缺 uuid 等错误会被 validator 抦下。
+- `doc create/update` 要求 body 必须以 `["root", ...]` 为根节点，缺少会报错。`doc block insert/update` 不要求 root。
+- `--fix-jsonml`：启用 JSON 语法修复（修复 LLM 遗漏的括号/逗号），推荐 agent 调用。
+
+**何时不走本节、改用 markdown**：纯文本追加章节（§4.2）、整篇按全新骨架重写（§4.5，且无富结构需要保留时）、只在乎"加一段文字"且确认目标段落无 callout / 分栏 / 颜色 / @人 / 附件。其余场景默认本节。
+
+字段细节见 [doc-jsonml-schema.md](../format/doc-jsonml-schema.md)；可复制范例见 [doc-jsonml-cookbook.md](../format/doc-jsonml-cookbook.md)。
+
+### 4.5 整篇 overwrite
+
+适合「按新风格重写整篇」「按新骨架重组结构」。
+
+**形态选择（按 §1.3 优先级）**：
+
+- 若原文档含 callout / 分栏 / 颜色 / @人 / 附件 / 嵌套结构且需要保留——**走 §4.4 路径 A**（整篇 JSONML overwrite；默认不带 `--revision`，担心并发时再加）
+- 若是纯文本骨架重写、原文档没有富结构需要保真——走本节 markdown overwrite
+
+执行前必须先向用户**显式提示**：
+
+> 注意：本次操作将覆盖整篇文档内容（约 {size}）。可能存在以下风险：
+> - 大文档 overwrite 可能被后端静默降级为 append，导致**旧内容残留 + 新内容追加在末尾**
+> - markdown overwrite 会丢失原文档的 callout / 分栏 / 颜色等富结构；如需保真改走 §4.4 路径 A
+> - 写入完成后我会回读校验，发现异常会主动报告
+>
+> 是否继续？
+
+得到确认后执行（markdown 兜底路径）：
+
+```bash
+dws doc +checkpoint-update --node <nodeId> --mode overwrite --content @./drafts/<name>-full.md
+```
+
+读取 `+checkpoint-update` 的 checkpoint、write、verify 步骤；只有 partial/unknown 时才按 §6 恢复。
+
+### 4.6 超长内容追加（分块 append）
+
+当一次性追加内容 **超过 200KB** 时，必须拆分为多片 `--mode append`，并在执行第一片**之前**向用户发出截断风险提示等待确认。
+
+完整规范（提示话术模板、触发条件、失败处理）见 [04-document.md «分块 append 截断风险提示»](../../04-document.md)。
+
+update 场景下的额外约束：
+
+1. 按段落/标题边界切分，**禁止**在表格、代码块、列表内部截断
+2. 每写一片记录已写入的最后一个标题/段落标记，供 §6 回读比对
+3. 与既有内容衔接位置不能产生悬空标题或断列表
+
+---
+
+## 五、改写时的样式约束
+
+按 [doc-style-guideline.md](./doc-style-guideline.md) 处理：
+
+- **文档类型保持不变**；用户明确要求转型时除外（如从「执行型 SOP」改成「说明型接口文档」）
+- **同类信息保持一致**：改写时不要把原本统一的元素改为多种表达
+- **颜色/emoji 语义**：改写后仍满足 style guideline §5「颜色与视觉语义」的一致性
+- **不删除附件/图片**；用户明确要求时除外
+
+---
+
+## 六、回读验收
+
+`+update/+checkpoint-update` 已统一确认与验证。正常成功禁止额外整篇读取；partial/unknown 或确需检查富结构时，使用最小范围 `+fetch`。
+
+校验要点：
+
+- 改写章节的关键标题、段落首句、表格表头是否符合预期
+- overwrite 后旧内容是否真的被清除
+- append 后新内容是否在期望位置
+- 表格、代码块、列表跨块元素是否完整
+- @人、附件、图片等保真要素是否原样保留
+
+### 异常处理
+
+| 现象 | 可能原因 | 处理 |
+|------|----------|------|
+| overwrite 后旧内容残留 + 新内容追加在末尾 | overwrite 被静默降级为 append | 告知用户 overwrite 降级，按下方「先清空再重建」路径修复 |
+| append 后部分片段缺失 | 分块写入丢失 | 定位缺失片段，针对该段单独再 append 一次 |
+| @人 / 附件被替换为纯文本 | 改写时未走保真约束 | 用 JSONML 无损编辑修复（§4.4）|
+| 整篇内容乱序 | 写入顺序异常 | 报告给用户；若可重做，按下方「先清空再重建」路径修复 |
+
+**禁止**在未回读的情况下向用户报告"已完成"。
+
+---
+
+## 七、交付口径
+
+只报告已经验证过的信息：
+
+- 改写涉及的章节范围
+- 改写后的 nodeId 与 docUrl
+- 回读验收结果（哪些章节确认改写成功、保真要素是否完整）
+- 如有缺失或异常，说明具体位置和已采取的修复动作
+
+未回读前，不要说「内容完整」「改写完成」。