first commit

2026-09-02 11:44:52 +08:00
commit 0c8fa2653e
309 changed files with 57278 additions and 0 deletions
@@ -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) 回读 |