dsh-crwu-workbench 0.0.10

package/skills/dws/dingtalk-doc/references/doc/doc-read.md

@@ -0,0 +1,56 @@
+# 读取文档：`+fetch` Golden Route
+
+## 唯一推荐入口
+
+```bash
+dws doc +fetch --node <DOC_ID_OR_URL> --format json
+dws doc +fetch --query "项目周报" --scope keyword --keyword "结论" --format json
+dws doc +fetch --node <PUBLIC_URL> --password <ACCESS_PASSWORD> --format json
+dws doc +fetch --node <DOC_ID> --version <VERSION> --format json
+```
+
+- 已知 ID 或 URL：传 `--node`。
+- 只知道标题：传 `--query`；跨页解析必须唯一命中，否则停止并要求用户选择。
+- `--node` 与 `--query` 必须且只能提供一个。
+- 默认 `--detail simple --scope full`，适合普通阅读，避免加载不必要的 JSONML。
+
+## 互联网公开文档与历史版本
+
+- **互联网公开文档**：公开链接直接传 `--node`；文档开启了密码保护时，通过 `--password <ACCESS_PASSWORD>` 提供访问密码，普通文档无需传入。密码只进入读取请求，不会回显在读取结果里（`--dry-run` 预览会包含所传参数，注意输出环境）。
+- **历史版本**：`--version <N>` 读取指定历史版本内容；版本号从 `dws doc +version-list` 获取，`0` 表示文档初始版本，需要文档编辑权限（EDITOR 及以上）；缺省读最新版。注意区分：`revision` 是文档编辑版本号（JSONML 读取响应返回、供 `+update --expected-revision` 条件写使用），不是历史版本号，`+fetch` 不支持 `--revision`。
+- **跨组织文档**：非互联网公开的跨组织文档，`+fetch` 整体被组织边界拦截（提示「不支持跨组织访问数据」），最新版与历史版本内容都读不到；互联网公开（含密码）文档的 `+fetch` 不受影响，但 `+version-list` 与写操作仍会被拦截，版本号无法从列表获取。
+- 只要看历史内容、不打算恢复时用 `--version`；要把文档整体恢复到历史版本才用 `+version-revert`（危险操作，需确认）。
+
+## 局部读取
+
+```bash
+dws doc +fetch --node <DOC_ID> --scope outline --detail with-ids --format json
+dws doc +fetch --node <DOC_ID> --scope section --start-block-id <BLOCK_ID> --detail full --format json
+dws doc +fetch --node <DOC_ID> --scope range --start-block-id <A> --end-block-id <B> --detail full --format json
+dws doc +fetch --node <DOC_ID> --scope tags --tags table,img --detail full --format json
+dws doc +fetch --node <DOC_ID> --scope keyword --keyword "风险|结论" --context-before 120 --context-after 240 --format json
+```
+
+只有需要块 ID、revision 或 JSONML 保真结构时才提高 `--detail`；先读取最小必要范围，避免把整篇大文档放入上下文。
+
+整篇读取使用默认 scope 或 `--scope full`；`full` 不是关键词，禁止写成 `--keyword full`。
+
+## 最小读取漏斗
+
+按用户已经给出的线索选最短路径，不先拉全文：
+
+1. 已知稳定 ID/URL，且任务确实涉及整篇：直接默认 `full + simple`，一次返回 Markdown。
+2. 用户给出具体术语、错误码或同义词：直接 `keyword`；`foo|bar` 是 OR，`context-before/after` 是字符数。该模式会缩小 Agent 输出与 token，但当前 Runtime 仍需取得正文后做本地投影，不把它误述为减少上游传输。
+3. 用户指向某章但没有 block ID：先 `outline --detail with-ids`，再用返回的真实标题 ID 执行 `section`。通常两次小结果比反复处理整篇更稳定。
+4. 已知起止 block：直接 `range`；只找表格、图片等结构时用 `tags`。
+5. 只有确需全文总结、全局一致性检查或整篇保真改写时，才读取完整内容。
+
+`simple` 用于阅读；`with-ids` 用于定位下一次写操作；`full` 只用于必须保留样式、引用或 JSONML 结构的编辑。局部结果只能证明所选范围，不得据此声称已检查整篇。
+
+## 后续路由
+
+- 读后修改：把稳定的 `nodeId` 交给 [`doc-update.md`](doc-update.md) 的 `+update` 或 `+checkpoint-update`。
+- 附件/图片：先用 [`doc-media.md`](doc-media.md) 的 `+media-list` 取得稳定 `resourceId`，再下载；不要复用正文中的临时签名 URL。
+- 富结构专家编辑：确实需要原始 JSONML 或 shortcut 未公开的参数时，先读取精确 leaf Schema，再使用原子 `doc read`/`doc block`。
+
+禁止把原子 `doc read` 当作默认入口，也不要在读取后无条件整篇回写。筛选结果只用于读取，不能把虚拟 fragment 容器整体写回文档；同一次任务里已拿到稳定 `nodeId` 后，后续调用直接复用，避免再次按标题搜索。

package/skills/dws/dingtalk-doc/references/doc/doc-update.md

@@ -0,0 +1,87 @@
+# 更新在线文字文档
+
+## 唯一推荐入口
+
+普通追加、覆盖和 block 编辑统一使用 `+update`：
+
+`--command` 只接受下列枚举值，不接受 JSON、自然语言或拼接子命令；动作参数必须分别传给 `--content/--old/--new/--block-id/--before-block-id/--after-block-id`。
+
+```bash
+dws doc +update --node <DOC_ID> --command append --content "补充说明" --format json
+dws doc +update --node <DOC_ID> --command append --content @append.md --format json
+dws doc +update --node <DOC_ID> --command overwrite --content @full.md --format json
+dws doc +update --node <DOC_ID> --command overwrite --doc-format jsonml --content @full.json --expected-revision <REVISION> --format json
+dws doc +update --node <DOC_ID> --command block_insert_before --before-block-id <BLOCK_ID> --content "发布说明" --heading-level 1 --format json
+dws doc +update --node <DOC_ID> --command block_replace --block-id <BLOCK_ID> --content "新内容" --format json
+```
+
+重要覆盖或明确要求恢复点时使用：
+
+```bash
+dws doc +checkpoint-update --node <DOC_ID> --mode overwrite --content @full.md --format json
+```
+
+`+checkpoint-update` 负责保存版本、写入和回读，不要手工编排 `version save → update → read`。
+
+## 动作与输入
+
+| `--command` | 用途 | 必要参数 |
+|---|---|---|
+| `append` | 末尾追加 | `--content` |
+| `overwrite` | 整篇覆盖 | `--content`；JSONML 可加 `--expected-revision` 做服务端原子条件写 |
+| `block_insert_before` | 在指定 block 前插入段落或标题 | `--before-block-id --content`；标题加 `--heading-level 1..6` |
+| `block_insert_after` | 在指定 block 后插入段落或标题 | `--after-block-id --content`；标题加 `--heading-level 1..6` |
+| `block_replace` | 替换指定 block | `--block-id --content` |
+| `block_delete` | 删除指定 block | `--block-id` |
+| `str_replace` | 唯一普通文本替换 | `--old --new` |
+| `block_copy_insert_after` | 复制 block 后插入 | `--block-id --after-block-id` |
+
+统一输入协议：已有或临时文件先暂存到当前工作目录后传 `@相对文件`；单次生成文本可用 `--content -` 从 stdin 读取。禁止绝对路径、`..`，也不要猜测 `--content-file`、`--content-format` 或 `replace_all`。
+
+block ID 必须来自 `+fetch --detail with-ids` 或真实 block 列表，禁止编造。
+
+`--expected-revision` 只允许 `--command overwrite --doc-format jsonml`。Markdown、append 和 block 接口没有服务端原子 revision 契约，禁止用写前读取模拟乐观锁。
+
+## 新增结构化标题
+
+“新增/插入标题”与“修改现有块文字”不是同一动作。`+update block_replace --content "# 标题"` 会替换原块并可能落成普通 paragraph，不能用它冒充 heading。
+
+需要在已有首块前新增标题时，先用 `+fetch --detail with-ids` 取得真实首块 ID，再走结构化插入：
+
+```bash
+dws doc block insert --node <DOC_ID> --heading "发布说明 v1.0" --level 1 --ref-block <FIRST_BLOCK_ID> --where before --format json
+```
+
+插入回执有新 block ID 时定点 `block list --block-id`；只有插入 index 时执行一次完整 `block list --content-format jsonml` 并按 index 验证 `blockType=heading`、回读投影 `heading.level="heading-1"` 和文字。`block list` 没有 `--limit`，禁止通过 Help 猜参数；CLI 写入仍用 `--level 1`。只核对可见文字不算结构验收。已有标题改级别或改文字时使用结构化 `doc block update --heading/--level`；更多块边界见 [`doc-block.md`](doc-block.md)。
+
+## 最小改写决策
+
+| 已知条件 | 推荐路径 | 成本与成功率理由 |
+|---|---|---|
+| 用户明确要求在末尾追加 | 直接 `append` | 不为找末尾先拉全文；需要语气衔接时只读末节 |
+| 已知唯一旧文本与新文本 | 直接 `str_replace --old --new` | 省掉 block 解析；旧文本不唯一时 Runtime 必须失败，不放宽匹配 |
+| 指定章节但没有 block ID | `+fetch outline` → `+fetch section --detail with-ids` → block 动作 | 两个小读取换取稳定锚点，避免全文 token 和误改相邻章节 |
+| 已知真实 block ID | 直接 `block_replace/delete/insert_before/insert_after` | 最小副作用；不改无关 block |
+| 多个待删除 block ID 已全部取得 | 在同一个 fail-fast 工具轮中按顺序执行全部 `block_delete` | 中间不重读 Reference、不重复 fetch；任一失败立即停止并保留未执行清单 |
+| 多处富结构保真修改 | `+fetch --detail full` 后定点 JSONML 更新 | 保留图片、附件、引用、表格和样式；不要从 Markdown 有损重建 |
+| 整篇重要覆盖 | `+checkpoint-update --mode overwrite` | 自动保存恢复点、执行并回读；普通 overwrite 只用于明确不需恢复点的场景 |
+
+同一篇文档的正文由一个主上下文串行维护：Plan（确定最小变更）→ Execute（一次写）→ Observe（先消费回执）→ Iterate（只修未达标部分）。不要按章节并行写同一文档，也不要每次迭代都重新读取全文或 Schema。
+
+## Block ID 生命周期与保真
+
+- `block_replace` 成功后 Runtime 使用同一 `blockId` 回读验证，该 ID 可继续作为锚点；验证失败时先局部 `+fetch` 核对现状。`block_delete` 成功后旧 ID 失效，不得继续复用。
+- `block_insert_before` / `block_insert_after` / `block_copy_insert_after` 后，原锚点通常仍可识别，但新 block 的 ID 必须来自真实返回或局部回读，禁止按顺序猜测。
+- `str_replace` 的简单行内替换通常不要求重新取 ID；若后续依赖块结构，仍以局部回读为准。
+- 从 Markdown 读取后覆盖整篇可能丢失图片、附件、@人/@文档、评论锚点、表格样式和嵌套块。只改局部时使用 block 手术；确需整篇保真改写时使用 `full` JSONML，并以 `--expected-revision` 防止覆盖并发修改。
+
+## 确认与验证
+
+- `+update` 与 `+checkpoint-update` 当前都要求用户确认。目标、动作、内容范围或参数变化后必须重新确认；只有发现本地文档与 live leaf 漂移时才查一次精确 Schema，禁止每次写入都重复发现。
+- `+update` 已负责回读验证。除非结果为 `unknown` 或任务需要额外结构验收，不要再做一次全篇读取。
+- `doc_write_verification_failed` 表示写入已经发生，必须先读取现状；禁止直接重复写入。
+- `partial_success` 只恢复未完成步骤，不能重放成功步骤。
+
+## 高级通道
+
+只有 shortcut 未公开底层参数或必须保留原始响应时，才读取精确 leaf Schema 后使用 `dws doc update` / `doc block`。富结构保真按需读取 [doc-update-workflow.md](style/doc-update-workflow.md)，但执行入口仍优先使用 `+update/+checkpoint-update`。

package/skills/dws/dingtalk-doc/references/doc/format/doc-jsonml-cookbook.md

@@ -0,0 +1,469 @@
+# JSONML Cookbook
+
+> 本文档提供 JSONML **结构范例**。正常执行入口是 `+create --content @./相对文件 --doc-format jsonml` 与 `+update --content @./相对文件 --doc-format jsonml`；原子 `doc create/update/block` 仅用于 shortcut 未公开字段的专家路径，使用前读取精确 leaf Schema。
+> 所有示例均基于真实文档 serialize 输出验证。节点结构详细定义见 [doc-jsonml-schema.md](./doc-jsonml-schema.md)。
+> 合法节点类型和属性的权威参考为 `wukong/products/jsonml-schema-v2.json`。
+
+## 决策型文档骨架范例（doc create 用）
+
+以下是一个"方案对比汇报"的完整 JSONML 文件内容，展示摘要 callout + 彩色表格 + 状态高亮。
+**可保存到工作目录内的 `./drafts/<name>.json`，再用 `dws doc +create --name "..." --content @./drafts/<name>.json --doc-format jsonml` 创建。**
+
+```json
+["root", {},
+  ["container", {"subType": "colorBlocks", "metadata": {"bgcolor": "#E8F5E9", "border": "left"}},
+    ["p", {}, ["span", {"data-type": "text"},
+      ["span", {"data-type": "leaf", "bold": true, "sz": 14, "szUnit": "pt"}, "✅ 推荐方案 A：上线快、依赖已有流程"]
+    ]],
+    ["p", {}, ["span", {"data-type": "text"},
+      ["span", {"data-type": "leaf"}, "主要风险：权限配置需补 ｜ 决策时限：本周五前"]
+    ]]
+  ],
+  ["h2", {}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "方案对比"]]],
+  ["table", {"colsWidth": [120, 200, 200]},
+    ["tr", {},
+      ["tc", {"fill": "#F5F5F5"}, ["p", {}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf", "bold": true}, "维度"]]]],
+      ["tc", {"fill": "#E8F5E9"}, ["p", {}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf", "bold": true}, "方案 A（推荐）"]]]],
+      ["tc", {}, ["p", {}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf", "bold": true}, "方案 B"]]]]
+    ],
+    ["tr", {},
+      ["tc", {}, ["p", {}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "上线周期"]]]],
+      ["tc", {}, ["p", {}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf", "color": "#2E7D32"}, "1 周"]]]],
+      ["tc", {}, ["p", {}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "3 周"]]]]
+    ],
+    ["tr", {},
+      ["tc", {}, ["p", {}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "风险"]]]],
+      ["tc", {}, ["p", {}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "低"]]]],
+      ["tc", {}, ["p", {}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf", "color": "#C62828"}, "高：需新流程审批"]]]]
+    ]
+  ],
+  ["h2", {}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "下一步"]]],
+  ["p", {}, ["span", {"data-type": "text"},
+    ["span", {"data-type": "leaf"}, "• "],
+    ["span", {"data-type": "leaf", "highlight": "#FFF9C4"}, "待确认"],
+    ["span", {"data-type": "leaf"}, " @负责人 完成权限配置"]
+  ]]
+]
+```
+
+**设计要点**：
+- 根节点固定 `"root"`，不是 `"body"`
+- 摘要用 `container`（callout），`metadata.bgcolor` 选浅绿表示"推荐结论"
+- 表格用 `table → tr → tc`（无 th/td），表头底色用 `tc` 的 `"fill"` 属性
+- 关键数据着色用 leaf 的 `"color"`（绿=好 / 红=风险）
+- 状态标记用 leaf 的 `"highlight"`（黄=待确认、绿=完成、红=阻塞）
+- uuid 必须显式提供——CLI 不再自动补充
+
+## ⚠️ 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 解析失败 |
+
+## 文本节点格式（最重要）
+
+钉钉文档的文本是**三层结构**，不是裸字符串：
+
+```json
+["p", {"uuid": "xxx"},
+  ["span", {"data-type": "text"},
+    ["span", {"data-type": "leaf"}, "文本内容"]
+  ]
+]
+```
+
+- **text 容器**：`["span", {"data-type": "text"}, ...leaves]` — 包裹所有文本 leaf
+- **leaf 节点**：`["span", {"data-type": "leaf", ...格式属性}, "文字"]` — 实际文本，可带 bold/italic 等
+- 一个 block 节点只有一个 text 容器，但可以有多个 leaf（不同格式的文字片段）
+
+**简写**：无格式纯文本可以省略格式属性：
+```json
+["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "纯文本"]]
+```
+
+## 核心规则
+
+1. **每个 block 节点应有 uuid**：`["tag", {"uuid": "唯一ID"}, ...children]`
+   - insert 时必须提供 uuid（可自行生成任意唯一字符串，后端会自动分配正式 uuid）
+   - update 时 uuid **必须**与 `--block-id` 一致
+   - uuid 必须显式提供，不再自动补充
+2. **文本必须用 span + leaf 三层结构**，不要直接写裸字符串
+   - ✅ `["p", {"uuid": "x"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "hello"]]]`
+   - ❌ `["p", {"uuid": "x"}, "hello"]` — validator 会报错，请手动包成 ✅ 的形式
+   - ⚠️ `["p", {"uuid": "x"}, ["text", {}, "hello"]]` — `text` 是历史 inline tag，validator 不会报错，但建议改写为 ✅ 形式以与 `dws doc read --content-format jsonml` 的输出保持一致
+3. **attrs 对象必须存在**（即使为空）：`["p", {}, ...]` 不能省略 `{}`
+
+> **严格模式（缺省）**：CLI 不做结构修复，裸字符串等错误会被 validator 以 `JSONPath + Suggestion` 形式逐条报错。如果输入来自 LLM 且可能有 JSON 语法错误（缺括号/逗号），用 `--fix-jsonml` 启用 JSON 语法修复。
+
+## 段落 (p)
+
+```bash
+# 纯文本段落
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["p", {"uuid": "new1"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "这是一段普通文本"]]]'
+
+# 带格式文本（多个 leaf）
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["p", {"uuid": "new2"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf", "bold": true}, "加粗"], ["span", {"data-type": "leaf"}, "普通"], ["span", {"data-type": "leaf", "italic": true}, "斜体"]]]'
+
+# 多行文本（每行一个 p，同一 p 内的多个 span 不会换行）
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["p", {"uuid": "line1"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf", "bold": true}, "第一行标题"]]]' \
+  --element '["p", {"uuid": "line2"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "第二行正文内容"]]]'
+
+# 带链接（link 是与 text 并列的子节点）
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["p", {"uuid": "new3"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "请访问"]], ["a", {"href": "https://example.com"}, "链接文字"]]'
+```
+
+**leaf 支持的格式属性**：
+- `bold: true` — 加粗
+- `italic: true` — 斜体
+- `underline: {"value": "single"}` — 下划线（value: `single`/`dash`/`wave`/`double`/`none`，可选 `color`）
+- `strike: true` — 删除线
+- `dstrike: true` — 双删除线
+- `color: "#ff0000"` — 文字颜色（`#rrggbb` 格式）
+- `highlight: "#ffff00"` — 高亮背景色
+- `sz: 14` / `szUnit: "pt"` — 字号（szUnit 默认 `"px"`，推荐显式写 `"pt"`）
+ `fonts: {"ascii": "Arial", "eastAsia": "SimHei"}` — 字体（四分区：ascii/hAnsi/cs/eastAsia，值必须使用 font-family 名称，见下方字体表）
+- `vertAlign: "superscript"` — 上标（`"subscript"` 下标，`"baseline"` 基线）
+- `spacing: 2` — 字间距（单位 pt）
+
+**字体名称映射**（`fonts` 字段必须使用 font-family 值，不能写中文名）：
+
+| 用户说法 | font-family 值 | 用户说法 | font-family 值 |
+|---------|---------------|---------|---------------|
+| 宋体 | `SimSun` | 黑体 | `SimHei` |
+| 微软雅黑 | `Microsoft YaHei` | 微软雅黑UI | `Microsoft YaHei UI` |
+| 仿宋 | `FangSong` | 仿宋_GB2312 | `FangSong_GB2312` |
+| 楷体 | `KaiTi` | 楷体_GB2312 | `KaiTi_GB2312` |
+| 等线 | `DengXian` | 新宋体 | `NSimSun` |
+| 宋体-简 | `SimSun SC` | 宋体-繁 | `SimSun TC` |
+| 黑体-简 | `Heiti SC` | 黑体-繁 | `Heiti TC` |
+| 华文宋体 | `STSong` | 华文黑体 | `STHeiti` |
+| 华文楷体 | `STKaiti` | 华文仿宋 | `STFangsong` |
+| 华文中宋 | `STZhongsong` | 华文行楷 | `STXingkai` |
+| 华文隶书 | `STLiti` | 华文新魏 | `STXinwei` |
+| 华文细黑 | `STXihei` | 华文琥珀 | `STHupo` |
+| 苹方-简 | `PingFang SC` | 苹方-繁 | `PingFang TC` |
+| 苹方-港 | `PingFang HK` | 冬青黑-简 | `Hiragino Sans GB` |
+| 兰亭黑-简 | `Lantinghei SC` | 兰亭黑-繁 | `Lantinghei TC` |
+| 凌慧体-简 | `LingWai SC` | 幼圆 | `YouYuan` |
+| 思源黑体 | `Source Han Sans CN` | 思源宋体 | `Source Han Serif CN` |
+| 思源等宽 | `Source Han Mono SC` | 思源黑体Regular | `Source Han Sans CN Regular` |
+| 阿里普惠体2.0 | `"Alibaba PuHuiTi 2.0"` | 阿里普惠体3.0 | `"Alibaba PuHuiTi 3.0"` |
+| 钉钉进步体 | `DingTalk JinBuTi` | Adobe仿宋 | `Adobe 仿宋 Std` |
+| 方正小标宋_GBK | `FZXiaoBiaoSong-B05` | 方正小标宋简体 | `FZXiaoBiaoSong-B05S` |
+| 方正黑体 | `FZHei-B01S` | 方正楷体 | `FZKai-Z03S` |
+| 方正仿宋 | `FZFangSong-Z02S` | 方正仿宋_GBK | `FZFangSong-Z02` |
+| PMingLiU | `PMingLiU` | — | — |
+
+**英文字体**（font-family 值即为字体名）：
+`Arial` ・ `Calibri` ・ `Cambria` ・ `Centaur` ・ `Comfortaa` ・ `Comic Sans MS` ・ `Courier New` ・ `Franklin Gothic` ・ `Garamond` ・ `Georgia` ・ `Helvetica` ・ `Impact` ・ `Lora` ・ `Lucida Sans` ・ `Merriweather` ・ `Montserrat` ・ `Nunito` ・ `Oswald` ・ `Playfair Display` ・ `Roboto` ・ `Spectral` ・ `Times New Roman` ・ `Trebuchet MS` ・ `Verdana`
+
+> **规则**：优先从上表匹配；用户指定的字体不在列表时，使用该字体在操作系统中的真实 font-family 名称（如"更纱黑体" → `Sarasa Gothic SC`）。
+
+**leaf 组合示例**：
+
+```json
+["span", {"data-type": "leaf", "bold": true, "color": "#C62828", "sz": 16, "szUnit": "pt"}, "红色加粗大字"]
+["span", {"data-type": "leaf", "strike": true, "color": "#9E9E9E"}, "已废弃内容"]
+["span", {"data-type": "leaf", "vertAlign": "superscript"}, "[1]"]
+["span", {"data-type": "leaf", "fonts": {"ascii": "Courier New", "eastAsia": "DengXian"}}, "等宽字体"]
+```
+
+**段落级排版属性**（写在 p/h1-h6 的 attrs 上）：
+- `jc: "center"` — 对齐（`left`/`center`/`right`/`both`/`justify`）
+- `spacing: {"line": 1.5, "lineRule": "auto"}` — 行距（lineRule=auto 时 line 为倍数：1=单倍、1.5=1.5倍、2=双倍）
+- `spacing: {"before": 12, "after": 8}` — 段前/段后间距（单位 pt）
+- `ind: {"firstLine": 32}` — 首行缩进（≈ 2 中文字符）
+- `ind: {"left": 96}` — 左缩进
+
+**段落排版示例**：
+
+```json
+["p", {"uuid": "p1", "jc": "center"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "居中段落"]]]
+["p", {"uuid": "p2", "spacing": {"line": 1.5, "lineRule": "auto"}}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "1.5倍行距"]]]
+["p", {"uuid": "p3", "spacing": {"line": 2, "lineRule": "auto", "before": 12, "after": 8}}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "双倍行距+段前后间距"]]]
+```
+
+## 标题 (h1-h6)
+
+```bash
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["h1", {"uuid": "new4"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "一级标题"]]]'
+
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["h2", {"uuid": "new5"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "二级标题"]]]'
+
+# 更新已有标题
+dws doc block update --node <DOC_ID> --block-id <BLOCK_ID> --content-format jsonml \
+  --element '["h2", {"uuid": "<BLOCK_ID>"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "修改后的标题"]]]'
+```
+
+## 列表 (list)
+
+列表在 JSONML 中是 **带 `list` 属性的 `p` 节点**，不是独立 tag。
+
+```bash
+# 无序列表项
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["p", {"uuid": "li1", "list": {"listId": "mylist1", "level": 0, "isOrdered": false}}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "无序列表第一项"]]]'
+
+# 有序列表项（仅第一项设 start，后续项不设，系统自动递增）
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["p", {"uuid": "li2", "list": {"listId": "mylist2", "level": 0, "isOrdered": true, "start": 1}}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "有序列表第一项"]]]'
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["p", {"uuid": "li2b", "list": {"listId": "mylist2", "level": 0, "isOrdered": true}}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "有序列表第二项"]]]'
+
+# 缩进子项（level: 1）
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["p", {"uuid": "li3", "list": {"listId": "mylist2", "level": 1, "isOrdered": true}}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "子列表项"]]]'
+
+# 待办列表（checkbox）
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["p", {"uuid": "li4", "list": {"listId": "todo1", "level": 0, "isOrdered": false, "isTaskList": true, "isChecked": false}}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "待办事项"]]]'
+```
+
+## 引用 (blockquote)
+
+引用是 **带 `quote` 属性的 `p` 节点**。
+
+```bash
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["p", {"uuid": "q1", "quote": true}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "这是一段引用文字"]]]'
+```
+
+## 高亮块 / Callout (container)
+
+```bash
+# 蓝色高亮块
+dws doc block insert --node <DOC_ID> --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"}, "这是一段提示内容"]]]]'
+
+# 黄色警告块（多段落）
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["container", {"uuid": "co2", "subType": "colorBlocks", "metadata": {"bgcolor": "#FFF2CC", "border": "#FFE599"}}, ["p", {"uuid": "co2p1"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "⚠️ 注意事项"]]], ["p", {"uuid": "co2p2"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "请仔细阅读以下内容"]]]]'
+```
+
+**常用颜色预设**：
+
+| 含义 | bgcolor | border |
+|------|---------|--------|
+| 信息（蓝） | `#E8F2FE` | `#B3D4FC` |
+| 成功（绿） | `#E6F7E6` | `#B7EB8F` |
+| 警告（黄） | `#FFF2CC` | `#FFE599` |
+| 危险（红） | `#FFF1F0` | `#FFA39E` |
+| 紫色 | `#F3E8FF` | `#D3ADF7` |
+
+## 代码块 (code)
+
+代码内容存在 attrs.code 中，不需要 text/leaf 子节点。
+
+```bash
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["code", {"uuid": "cd1", "syntax": "javascript", "code": "function hello() {\n  return \"world\";\n}"}]'
+
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["code", {"uuid": "cd2", "syntax": "python", "code": "print(\"hello\")", "showLineNumber": true, "theme": "dracula"}]'
+```
+
+## 分割线 (hr)
+
+```bash
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["hr", {"uuid": "hr1"}]'
+```
+
+## 表格 (table)
+
+> colsWidth 单位为 **pt**（页宽约 650pt）。如配合 `tblW: {"type": "pct"}` 则为百分比权重。
+
+```bash
+# 2行2列表格（各列 200pt）
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["table", {"uuid": "tb1", "colsWidth": [200, 200]}, ["tr", {"uuid": "tr1"}, ["tc", {"uuid": "tc1", "colSpan": 1, "rowSpan": 1}, ["p", {"uuid": "tcp1"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "标题A"]]]], ["tc", {"uuid": "tc2", "colSpan": 1, "rowSpan": 1}, ["p", {"uuid": "tcp2"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "标题B"]]]]], ["tr", {"uuid": "tr2"}, ["tc", {"uuid": "tc3", "colSpan": 1, "rowSpan": 1}, ["p", {"uuid": "tcp3"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "数据1"]]]], ["tc", {"uuid": "tc4", "colSpan": 1, "rowSpan": 1}, ["p", {"uuid": "tcp4"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "数据2"]]]]]]]'
+```
+
+> 表格较复杂时建议写入文件后用 `--element "$(cat table.json)"` 传入。
+
+## 图片 (img)
+
+> `img` 是 inline 元素，必须包裹在 `p` 段落中才能作为 block 插入。
+
+```bash
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["p", {"uuid": "p-img1"}, ["img", {"uuid": "img1", "src": "https://example.com/photo.png", "width": 400, "height": 300}], ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, ""]]]'
+```
+
+## 分栏布局 (columns)
+
+分栏复用 table tag，通过 `sr: true` 区分。分栏的 `tc` 可设置 `fill`（背景色）和 `border`（边框）属性提升视觉效果。
+
+```bash
+# 两栏布局（带背景色）
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["table", {"uuid": "col1", "sr": true, "colsWidth": [300, 300]}, ["tr", {"uuid": "coltr"}, ["tc", {"uuid": "coltc1", "fill": "#EEF6FF", "vAlign": "top"}, ["p", {"uuid": "colp1"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "左栏内容"]]]], ["tc", {"uuid": "coltc2", "fill": "#FFF3E0", "vAlign": "top"}, ["p", {"uuid": "colp2"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "右栏内容"]]]]]]'
+```
+
+**分栏视觉属性**：
+- `fill` — 单元格背景色（推荐淡色，如 `#EEF6FF` / `#FFF8E1` / `#F3E5F5`）
+- `border` — 边框配置（可选）
+- 分栏建议始终设置 `fill` 背景色，纯白底分栏视觉上与普通段落无异，读者无法感知分栏结构
+
+## 嵌入块 (embed)
+
+通用文件/iframe 嵌入。`embed` 是 void 块，仅含 attrs，无子节点。
+
+```bash
+# 嵌入文件预览
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["embed", {"uuid": "em1", "name": "design.pdf", "type": "pdf", "src": "https://example.com/design.pdf", "size": 524288, "viewType": "preview", "previewSize": {"height": 600}}]'
+```
+
+**关键 attrs**：
+- `src`（**必填**）— 资源 URL
+- `type` — `pdf` / `xlsx` / `html` 等
+- `name` — 展示名
+- `previewSize.height` — 预览高度（px）
+
+## 在线视频 (onlineVideo)
+
+外链视频（B 站 / 优酷 / 自定义 mp4 等）。
+
+```bash
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["onlineVideo", {"uuid": "ov1", "src": "https://player.bilibili.com/player.html?aid=12345", "type": "bilibili", "poster": "https://example.com/poster.jpg"}]'
+```
+
+**关键 attrs**：
+- `src`（**必填**）— 视频播放页或 mp4 URL
+- `type` — 平台标识（`bilibili` / `youku` / `mp4` 等）
+- `poster` — 封面图 URL
+
+## 卡片 (card)
+
+群名片 / 应用卡片等富交互卡片。`cardType` 决定渲染形态，`metadata` 内容随类型变化。
+
+```bash
+# 群名片
+dws doc block insert --node <DOC_ID> --content-format jsonml \
+  --element '["card", {"uuid": "cd1", "cardType": "groupChatCard", "metadata": {"id": "63953109506", "name": "测试组", "inviteUrl": "https://qr.dingtalk.com/...", "expires": 1810865989}}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, ""]]]'
+```
+
+> 注意：服务端 serialize 出来的 card 通常带一个空的 span/leaf 占位子节点，建议保留以避免反序列化差异。
+
+## 目录 (toc)
+
+目录块 attrs 上必带 4 个字段：`title` / `mode` / `styles` / `content`。如果不知道怎么填，**最简方式**是先在 web 端插入一个 toc，然后 `block list --content-format jsonml` 把现成结构拿下来改。
+
+```bash
+dws doc block insert --node <DOC_ID> --content-format jsonml --element '
+["toc", {
+  "uuid": "toc1",
+  "title": "目录",
+  "mode": "outline",
+  "styles": {
+    "global": {"maxLevel": 5, "bgColor": "#F0EBF7", "css": {}},
+    "title": {"font": "DingTalk JinBuTi", "color": "#6940A5", "numbering": true, "css": {"fontWeight": "normal"}},
+    "item": {"symbol": "disc", "css": {}}
+  },
+  "content": []
+}]'
+```
+
+**关键 attrs**：
+- `mode` — `outline`（大纲）/ `column`（分栏）
+- `styles.global.maxLevel` — 最大显示层级
+- `content` — 目录条目数组；**留空数组即可**，服务端会基于文档 heading 自动重建
+
+## 引用块 (refblock)
+
+引用另一文档的内容片段。`refblock` 像容器一样包子节点。
+
+```bash
+dws doc block insert --node <DOC_ID> --content-format jsonml --element '
+["refblock", {"uuid": "rb1", "docKey": "OTHER_DOC_NODE_ID", "refblockUUID": "BLOCK_UUID_IN_OTHER_DOC"},
+  ["p", {"uuid": "rb1p1"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "（引用预览内容，服务端会回填）"]]]
+]'
+```
+
+**关键 attrs**：
+- `docKey` — 被引用文档的 nodeId
+- `refblockUUID` — 被引用块的 uuid
+
+> 引用块的子节点是「快照」，真实内容由服务端按 docKey/refblockUUID 拉取覆写。
+
+## 表格单元格嵌套块 (tableCell with nested blocks)
+
+`tc` 的子节点是**块级节点**（不仅是 `p`）。可以塞多个段落、列表、代码块、甚至嵌套表格。
+
+```bash
+# 单元格内含多段落 + 代码块
+dws doc block insert --node <DOC_ID> --content-format jsonml --element '
+["table", {"uuid": "tbn1", "colsWidth": [400]},
+  ["tr", {"uuid": "tbn1r1"},
+    ["tc", {"uuid": "tbn1c1", "colSpan": 1, "rowSpan": 1},
+      ["p", {"uuid": "tbn1p1"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "标题段落"]]],
+      ["p", {"uuid": "tbn1p2", "list": {"listId": "tbn1list", "level": 0, "isOrdered": false}}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "列表项 1"]]],
+      ["p", {"uuid": "tbn1p3", "list": {"listId": "tbn1list", "level": 0, "isOrdered": false}}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "列表项 2"]]],
+      ["code", {"uuid": "tbn1code", "syntax": "bash", "code": "echo hello"}]
+    ]
+  ]
+]'
+```
+
+**规则**：
+- `tc` 子节点 **必须是块节点数组**，不能直接放 `span` 或裸字符串
+- 至少包含一个 `["p", {...}, ...]`（即使空也要），否则单元格无法渲染光标
+- 单元格可嵌套 `table`，但嵌套时务必保证内层每个 `tc` 也满足上述规则
+
+## Update 操作注意事项
+
+1. **uuid 必须与 --block-id 一致**
+2. Update 是**整块替换**，不是 patch — 需提供完整节点结构
+3. 推荐流程：先 `block list --content-format jsonml --block-id <ID>` 获取当前结构，修改后写回
+
+```bash
+# 典型 update 流程
+# 1. 获取当前结构
+dws doc block list --node <DOC_ID> --content-format jsonml --block-id <BLOCK_ID>
+
+# 2. 修改后写回（uuid 不变）
+dws doc block update --node <DOC_ID> --block-id <BLOCK_ID> --content-format jsonml \
+  --element '["p", {"uuid": "<BLOCK_ID>"}, ["span", {"data-type": "text"}, ["span", {"data-type": "leaf"}, "修改后的内容"]]]'
+```
+
+## 常见错误
+
+| 错误写法 | 问题 | 正确写法 |
+|---------|------|---------|
+| `["p", {}, "文字"]` | 裸字符串。validator 会报 `段落子节点不能是裸字符串`，请手动包成右侧形式 | `["p", {}, ["span", {"data-type":"text"}, ["span", {"data-type":"leaf"}, "文字"]]]` |
+| `["p", {}, ["text", {}, "文字"]]` | `text` 是历史 inline tag，validator 不报错但服务端实际渲染的 canonical 形式是 span/leaf；为与 `doc read` 输出一致，建议改写 | 同上，用 span + data-type |
+| `["callout", {}, ...]` | 不存在 callout tag | `["container", {"subType": "colorBlocks", ...}, ...]` |
+| `["list", {}, ...]` | 不存在 list tag | `["p", {"list": {...}}, ...]` |
+| `["blockquote", {}, ...]` | 不存在 blockquote tag | `["p", {"quote": true}, ...]` |
+| `["ul", {}, ["li", ...]]` | 不存在 ul/li tag | 多个 `["p", {"list": {...}}, ...]` |
+
+## 快捷模板
+
+为方便使用，以下是最常用节点的最小完整模板：
+
+```
+纯文本段落:  ["p", {"uuid":"U"}, ["span", {"data-type":"text"}, ["span", {"data-type":"leaf"}, "TEXT"]]]
+标题:        ["h2", {"uuid":"U"}, ["span", {"data-type":"text"}, ["span", {"data-type":"leaf"}, "TITLE"]]]
+代码块:      ["code", {"uuid":"U", "syntax":"LANG", "code":"CODE"}]
+分割线:      ["hr", {"uuid":"U"}]
+```