docs: clarify lark doc warning prevention

skills/lark-doc/SKILL.md

@@ -37,6 +37,7 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '<p>
 - 先判定任务路径：找文档 / 导入导出走 [`lark-drive`](../lark-drive/SKILL.md)；只读 / 摘要用 `docs +fetch` 默认 `simple`；明确旧文本 → 新文本直接 `str_replace`；只有 block 链接、评论锚点、插入 / 替换 / 删除 / 移动才局部 fetch `with-ids`；保真改写已有内容才读 `full`
 - block 直达链接格式：`文档基础 URL#block_id`；没有 block_id 时局部 fetch `with-ids`
 - 连续执行多个文档写操作时，必须按 [`lark-doc-update.md`](references/lark-doc-update.md) 的「Block ID 生命周期」判断旧 block ID 是否还能复用；`overwrite` / `block_replace` / `block_delete` 后不要复用受影响的旧 ID，插入 / 复制后要重新 fetch 才能拿到新 block ID
+- 写入返回 `4030004_no_document_permission` 时，说明当前 user/bot 对目标文档或知识空间节点没有编辑 ACL；这不是 `/wiki/` URL 本身的问题。不要用 `--dry-run` 或只读 fetch 冒充写权限探测，也不要切换身份绕过权限；停止重试并请用户授予当前身份编辑权限，或在用户明确同意后复制到有权限的位置再编辑
 - 用户需要在文档内**创建、复制或移动**资源块（画板、电子表格、多维表格等）时，必须先读取 [`lark-doc-xml.md`](references/lark-doc-xml.md) 的「三、资源块」章节
 - 写文档时，由内容和用户意图决定表达形式；流程、架构、路线图、关键指标等信息可以使用画板，但不要默认把重要信息都画板化
 - 新增或更新画板时，按 [`lark-doc-whiteboard.md`](references/lark-doc-whiteboard.md) 选型；Mermaid 可由主 Agent 直接插入，SVG / 复杂图 / 已有画板更新按其中流程隔离到 SubAgent

skills/lark-doc/references/lark-doc-create.md

@@ -58,15 +58,16 @@ lark-cli docs +create --doc-format markdown --title "项目计划" --content $'#
 
 | 参数                  | 必填 | 说明                                          |
 | ------------------- | -- |---------------------------------------------|
-| `--title`           | 否  | 文档标题，Markdown 导入时使用；XML 创建推荐在 `--content` 开头写 `<title>...</title>`；多个标题仅保留第一个并在 `warnings` / `degrade_details` 提示 |
-| `--content`         | 视情况 | 文档内容（XML 或 Markdown 格式）；不传 `--content` 时必须传 `--title` |
+| `--title`           | 否  | 文档标题，XML 和 Markdown 均可使用；传入时它是权威标题。若 XML 内容已经用 `<title>` 提供标题，则不要再传 `--title` |
+| `--content`         | 视情况 | 文档内容（XML 或 Markdown 格式）；不传 `--content` 时必须传 `--title`。未传 `--title` 的 XML 可在开头写 `<title>...</title>`。XML 正文中的 `<` 和 `&` 必须转义，详见 [`lark-doc-xml.md`](lark-doc-xml.md)「正文文本转义」 |
 | `--reference-map` | 否 | 结构化 `reference_map` JSON object；必须与 `--content` 一起使用。普通写入优先把结构写在正文里；该参数主要用于保留或回放已有 `document.reference_map`。支持直接 JSON、`@reference-map.json`（相对路径）或 `-` 从 stdin 读取。 |
 | `--doc-format`      | 否  | 内容格式：`xml`（默认，始终优先使用）\| `markdown`（仅用户明确要求时） |
 | `--parent-token`    | 否  | 父文件夹或知识库节点 token（与 `--parent-position` 互斥）  |
 | `--parent-position` | 否  | 父节点位置，如 `my_library`（与 `--parent-token` 互斥） |
 
 ## 最佳实践
 
+- **标题只有一个来源**：优先使用 `--title`；如果 XML 文件已经在开头包含 `<title>`，则省略 `--title`。读取 `@file.xml` 前先确认标题来源，避免重复
 - **较长文档**：参考 [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) 先建骨架再分段写入；短文档可一次写完整内容
 - **表达形式**：由用户目标和内容决定。需要结构化表达时可参考 [`lark-doc-style.md`](style/lark-doc-style.md)，但不要默认套用固定开头、固定富 block 比例或固定图表
 

skills/lark-doc/references/lark-doc-update.md

@@ -23,7 +23,7 @@
 | `--doc` | 是 | 文档 URL 或 token |
 | `--command` | 是 | 操作指令（见下方指令速查表） |
 | `--doc-format` | 否 | 内容格式：`xml`（默认，始终优先使用）\| `markdown`（仅用户明确要求时） |
-| `--content` | 视指令 | 写入内容（`str_replace` 传空字符串可实现删除） |
+| `--content` | 视指令 | 写入内容（`str_replace` 传空字符串可实现删除）。XML 正文中的 `<` 和 `&` 必须转义，详见 [`lark-doc-xml.md`](lark-doc-xml.md)「正文文本转义」 |
 | `--reference-map` | 否 | 结构化 `reference_map` JSON object；必须与 `--content` 一起使用。普通写入优先把结构写在正文里；该参数主要用于保留或回放已有 `document.reference_map`。支持直接 JSON、`@reference-map.json`（相对路径）或 `-` 从 stdin 读取。 |
 | `--pattern` | 视指令 | 匹配文本（str_replace） |
 | `--block-id` | 视指令 | 目标 block ID（block_* 操作），逗号分隔可批量删除，-1 表示末尾 |
@@ -52,6 +52,8 @@
 - `block_move_after`：被移动 ID 通常保留，但位置、章节、range 语义变化；后续依赖位置时重新 fetch
 - `str_replace`：简单行内替换通常不改变 ID；跨行 / 大段替换后如继续 block 级操作，先重新 fetch
 
+批量删除前必须使用当前 revision 的 fetch 结果确认每个 block ID 仍存在。任何会删除或替换目标块的写操作之后，都要重新 fetch，再构造下一批 `block_delete`；不要凭历史输出猜测 ID，也不要给批量大小编造未经服务端确认的固定上限。
+
 ## 指令示例
 
 ### str_replace — 全文文本替换
@@ -60,7 +62,9 @@
 > - **XML 模式（默认）**：`--pattern` 只支持**行内匹配**，不能跨 block / 跨段落匹配。涉及整段或多 block 的改动，请改用 `block_replace`。
 > - **Markdown 模式**（`--doc-format markdown`）：`--pattern` 同时支持**行内和跨行匹配**，可以用多行字符串匹配并替换一整段内容。
 >   - 还支持**`前缀...后缀` 省略号语法**：用 `...`（三个英文句点）串联起始与结束片段，匹配从前缀到后缀之间的全部内容（含中间被省略部分）。适合一段很长、但首尾特征明显的文本，避免把整段都塞进 `--pattern`。
->   - 前缀、后缀本身仍遵循 Markdown 转义规则；省略号中间的内容**会被替换**为 `--content` 的完整文本，不会被保留。
+>   - 前缀、后缀本身仍遵循 Markdown 转义规则，并且组合后必须唯一定位一个范围；省略号中间的内容**会被替换**为 `--content` 的完整文本，不会被保留。
+> - 同一个 pattern 命中多处时会返回 `1014_str_replace_multiple_matches`，不会自动选择第一处或替换全部。增加前后文，或改用带 block ID 的 `block_replace`。
+> - 如果 `--pattern` 与 `--content` 相同，本次调用没有实质变化；直接跳过，不要发送。
 
 ```bash
 # 简单文本替换
@@ -197,6 +201,13 @@ lark-cli docs +update --doc "<doc_id>" --command block_move_after \
 | `warnings` | 警告信息列表 |
 | `document.new_blocks` | 本次操作新增的 block 列表（如画板）。`block_id` 可用于后续精确编辑；`block_token` 是资源块 token（如画板）可交给 `lark-whiteboard` 等 skill 继续操作 |
 
+### 结果判读
+
+- `result = success` 且 `warnings = []`：完全成功。
+- `result = success` 或 `partial_success` 且有 warnings：不要仅凭 result 判断是否发生写入；先按 warning 类型检查最终文档，再决定是否需要修正输入。
+- warnings 包含 `1011_no_document_changes` 且 `updated_blocks_count = 0`：本次调用是 no-op。不要重试相同请求；检查目标内容是否已经是最终状态，或 pattern 与 replacement 是否相同。若同时出现其他 warning 或更新计数非零，先检查最终文档再判断影响。
+- `updated_blocks_count = 0` 且有其他 warning：根据具体 degrade code 修正输入，不能把“0 个更新”当成成功写入。
+
 ## 典型工作流
 
 ### 精确 block 级更新

skills/lark-doc/references/lark-doc-whiteboard.md

@@ -6,8 +6,8 @@
 
 | Skill             | 核心职责                                                      | 约束                              |
 |-------------------|-----------------------------------------------------------|---------------------------------|
-| `lark-doc`        | 识别画板机会、使用 Mermaid/SVG 创建图表、调度 SubAgent、插入简单 SVG 画板或复杂空白画板 | 主 Agent 不直接创作画板内容；              |
-| `lark-whiteboard` | 查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板  | 仅特别复杂的图表或已有画板更新时由独立 SubAgent 读取 |
+| `lark-doc`        | 识别画板机会；主 Agent 可直接生成并插入简单 Mermaid；调度 SubAgent 处理 SVG、复杂图表和已有画板更新 | 简单 Mermaid 写入前仍需验证语法 |
+| `lark-whiteboard` | 查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板 | SVG、复杂图表或已有画板更新时由独立 SubAgent 读取 |
 
 ## 画板适用规则
 
@@ -37,13 +37,18 @@ SubAgent 插入 SVG。
 
 ### 步骤 2A: 使用 mermaid 插入图表
 
-```xml
+简单 Mermaid 由主 Agent 直接生成并插入，不需要启动 SubAgent；复杂图表仍按职责边界交给 SubAgent。
 
-<whiteboard type="mermaid">
-    mermaid 代码...
+```xml
+<whiteboard type="mermaid">flowchart TD
+    A["开始"] --> B["处理"]
+    B -->|"是"| C["结束"]
+    B -->|"否"| A
 </whiteboard>
 ```
 
+Mermaid 内容保持为纯 Mermaid 语法。Unicode、空格或含标点的节点/连线标签统一用双引号包裹；复杂语法在写入前先用 Mermaid 兼容的本地渲染器验证。不要把“某一种未加引号的中文写法”描述成服务端必然失败——以实际 parser 校验结果为准。
+
 如果 Mermaid 已在本地文件中，可写成 `<whiteboard type="mermaid" path="@diagram.mmd"></whiteboard>`；CLI 会在写入前读取文件并展开为内联内容。
 
 ### 步骤 2B: SubAgent 使用 SVG 插入图表

skills/lark-doc/references/lark-doc-xml.md

@@ -3,6 +3,35 @@
 # 一、标准 HTML 标签
 p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr, img, b, em, u, del, a, br, span 语义不变
 
+## 正文文本转义
+
+标签保持原样，只转义标签内部的正文文本。正文中的 `<` 和 `&` **必须**分别写成 `&lt;` 和 `&amp;`，否则 XML 无法解析；`>` 通常可以原样保留，但为了生成规则一致也可以写成 `&gt;`。换行使用 `<br/>`。
+
+```xml
+<!-- ❌ 把标签本身转义了 -->
+&lt;p&gt;内容&lt;/p&gt;
+
+<!-- ❌ 正文中的 < 和 & 没有转义 -->
+<p>A & B，且 1 < 2</p>
+
+<!-- ✅ 标签原样，正文字符转义 -->
+<p>A &amp; B，且 1 &lt; 2</p>
+```
+
+## 常见的不支持标签及替代方案
+
+只使用上面的白名单；不要把“HTML 子集”理解成完整 HTML。
+
+| 不支持写法 | 替代方案 |
+|-|-|
+| `<strong>` | `<b>` |
+| `<i>` | `<em>` |
+| `<sub>` / `<sup>` | 简单上下标使用 Unicode（如 H₂O、x²）；复杂公式使用 `<latex>` |
+| `<font color="...">` | `<span text-color="...">` |
+| `<div>` / `<section>` / `<article>` | 使用段落与标题组织内容 |
+
+不支持的标签会被降级或产生 `4007_unsupported_tag` warning。
+
 # 二、扩展标签速查表
 ## 块级标签
 |标签|说明|关键属性|
@@ -13,7 +42,7 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 ## 容器标签
 |标签|说明|关键属性|
 |-|-|-|
-| `<callout>` | 高亮框，子块仅支持文本、标题、列表、待办、引用 | `emoji`(默认 bulb), `background-color`, `border-color`, `text-color` |
+| `<callout>` | 高亮框；直接子节点必须是受支持的文本块、标题、列表、待办或引用，不能放裸文本 | `emoji`(默认 bulb), `background-color`, `border-color`, `text-color` |
 | `<grid>` + `<column>` | 分栏布局，各列 width-ratio 之和为 1 | `width-ratio` |
 | `<whiteboard>` | 嵌入画板 | `type`: `blank` \| `mermaid` \| `plantuml` \| `svg` |
 | `<pre>` | （代码块，内含 `code`）| `lang`, `caption` |
@@ -36,11 +65,34 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 - `align` — `"left"`|`"center"`|`"right"`（适用于 p / h1-h9 / li / checkbox）
 - 有序列表项用 `seq="auto"` 自动编号
 
+### callout 内容边界
+
+- 文本必须放在 `<p>`、标题、列表、`<checkbox>` 或 `<blockquote>` 等块中，不能直接写裸文本。
+- 表格、图片、代码块、分栏和画板不要嵌套进 `<callout>`；需要强调时，在资源块前放一个短 callout，再把资源块作为相邻顶层块写入。
+- 列表使用完整的 `<ul><li>...</li></ul>` 或 `<ol><li seq="auto">...</li></ol>`，不要把孤立 `<li>` 直接放入 callout。
+
+```xml
+<!-- ❌ 裸文本 -->
+<callout>重要提示</callout>
+
+<!-- ✅ 文本块 -->
+<callout><p>重要提示</p></callout>
+
+<!-- ✅ 表格与 callout 相邻，而不是互相嵌套 -->
+<callout><p>下表列出关键指标。</p></callout>
+<table><tbody><tr><td>指标</td><td>值</td></tr></tbody></table>
+```
+
+### `<ol>` / `<li>` 属性
+
+- `<ol>` 不使用 HTML 的 `start="N"` 属性；需要连续编号时使用一个完整的 `<ol>`。
+- `<li>` 的自动编号写成 `seq="auto"`，不要写 `seq="true"` 或数字字符串。
+
 # 三、资源块
 
 文档中可嵌入外部资源块（属于容器标签的特殊形式），需要额外语法创建：
 
-- `<img>` — `<img href="https://..."/>` 上传网络图片
+- `<img>` — `<img href="https://..."/>` 上传稳定的公网图片；本地文件、剪贴板内容或需要权限的飞书素材优先使用 [`docs +media-insert`](lark-doc-media-insert.md)
 - `<whiteboard>` — 简单图由 SubAgent 直接插入 `<whiteboard type="svg">完整自包含 SVG</whiteboard>`；也可用本地文件简写 `<whiteboard type="svg" path="@diagram.svg"></whiteboard>`、`<whiteboard type="mermaid" path="@flow.mmd"></whiteboard>`、`<whiteboard type="plantuml" path="@sequence.puml"></whiteboard>`，CLI 会写入前展开为内联内容；复杂图使用 `<whiteboard type="blank"></whiteboard>` 先创建空白画板，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 调用 `lark-whiteboard` 写入；
 - `<sheet>` — `<sheet type="blank"></sheet>` 空白；`<sheet sheet-id="SID" token="TOKEN"></sheet>` 复制已有
 - `<task>` — `<task task-id="GUID"></task>`，必传 task-id（任务 guid）
@@ -96,6 +148,16 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 - `<th>` / `<td>` 增加 `background-color` 和 `vertical-align`（top | middle | bottom）
 - 有表头时第一行在 `<thead>` 用 `<th>`，其余在 `<tbody>` 用 `<td>`
 - 合并单元格仅起始格输出 `colspan` / `rowspan`，被合并的格不出现
+- `<td>` / `<th>` 可以直接包含文本，也可以使用受支持的行内样式或块内容；不要把额外包 `<p>` 当成强制规则。
+- `<tr>` / `<td>` / `<th>` / `<colgroup>` 不能作为 create/append/block_insert_after 的孤立根块；必须放在完整 `<table>` 中。
+- `<col span="N">` 本身代表 N 列；不要按 `<col>` 元素个数机械判断表格列数。
+
+### 图片来源
+
+- `<img href>` 只用于无需登录、服务端可直接下载的稳定 HTTP(S) URL。
+- 从飞书消息、文档或 Drive 复制出的带临时授权参数的下载 URL 不可移植；先通过对应 skill 下载为本地文件，再用 `docs +media-insert --file` 上传。
+- 剪贴板中的截图直接使用 `docs +media-insert --from-clipboard`。
+- 不要把“URL 中含 query 参数”等同于必然失败；关键是服务端能否在写入时匿名、稳定地访问资源。
 
 # 六、美化系统
 - 颜色优先使用命名色，也可写 `rgb(r,g,b)` / `rgba(r,g,b,a)`。**基础色（7 色）**：red, orange, yellow, green, blue, purple, gray
@@ -110,27 +172,14 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
   | 按钮背景 `<button background-color>` | 同文字背景 |
 - 常用 emoji： 💡(默认)✅❌📝❓❗👍❤️📌🏁⭐
 
-# 七、**重要规则**
-## 转义规则：标签本身 **禁止转义**，只有标签内部的文本内容才需要转义
-
-**错误** ❌：`&lt;p&gt;内容&lt;/p&gt;`（把标签也转义了）
-**正确** ✅：`<p>A &amp; B 的对比：1 &lt; 2</p>`（标签保持原样，文本中的 `&` 和 `<` 才转义）
-
-转义字符表：
-- `<` → `&lt;`
-- `>` → `&gt;`
-- `&` → `&amp;`
-- `\n`（换行符） → `<br/>`
-
-
-# 八、完整示例
+# 七、完整示例
 
 ```xml
 <title>文档标题</title>
 
 <h1>一级标题</h1>
 
-<p><b>加粗文本</b>，<span text-color="green">绿色文本</span></p>
+<p><b>加粗文本</b>，<span text-color="green">绿色文本</span>；示例：a &lt; b，A &amp; B</p>
 
 <callout emoji="💡" background-color="light-yellow" border-color="yellow">
   <p>高亮框内容，子块仅支持文本/标题/列表/待办/引用</p>