diff --git a/skills/lark-doc/SKILL.md b/skills/lark-doc/SKILL.md
index 478be8bb9f..bd72e8cc42 100644
--- a/skills/lark-doc/SKILL.md
+++ b/skills/lark-doc/SKILL.md
@@ -37,6 +37,7 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '
- 先判定任务路径：找文档 / 导入导出走 [`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
diff --git a/skills/lark-doc/references/lark-doc-create.md b/skills/lark-doc/references/lark-doc-create.md
index 461e76ec01..fb40063b82 100644
--- a/skills/lark-doc/references/lark-doc-create.md
+++ b/skills/lark-doc/references/lark-doc-create.md
@@ -58,8 +58,8 @@ lark-cli docs +create --doc-format markdown --title "项目计划" --content $'#
| 参数 | 必填 | 说明 |
| ------------------- | -- |---------------------------------------------|
-| `--title` | 否 | 文档标题，Markdown 导入时使用；XML 创建推荐在 `--content` 开头写 `
...`；多个标题仅保留第一个并在 `warnings` / `degrade_details` 提示 |
-| `--content` | 视情况 | 文档内容（XML 或 Markdown 格式）；不传 `--content` 时必须传 `--title` |
+| `--title` | 否 | 文档标题，XML 和 Markdown 均可使用；传入时它是权威标题。若 XML 内容已经用 `` 提供标题，则不要再传 `--title` |
+| `--content` | 视情况 | 文档内容（XML 或 Markdown 格式）；不传 `--content` 时必须传 `--title`。未传 `--title` 的 XML 可在开头写 `<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` 互斥） |
@@ -67,6 +67,7 @@ lark-cli docs +create --doc-format markdown --title "项目计划" --content $'#
## 最佳实践
+- **标题只有一个来源**：优先使用 `--title`；如果 XML 文件已经在开头包含 ``，则省略 `--title`。读取 `@file.xml` 前先确认标题来源，避免重复
- **较长文档**：参考 [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) 先建骨架再分段写入；短文档可一次写完整内容
- **表达形式**：由用户目标和内容决定。需要结构化表达时可参考 [`lark-doc-style.md`](style/lark-doc-style.md)，但不要默认套用固定开头、固定富 block 比例或固定图表
diff --git a/skills/lark-doc/references/lark-doc-update.md b/skills/lark-doc/references/lark-doc-update.md
index 905d69175a..ffa968d7b9 100644
--- a/skills/lark-doc/references/lark-doc-update.md
+++ b/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 级更新
diff --git a/skills/lark-doc/references/lark-doc-whiteboard.md b/skills/lark-doc/references/lark-doc-whiteboard.md
index ab296130a2..6f8df8a23e 100644
--- a/skills/lark-doc/references/lark-doc-whiteboard.md
+++ b/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 插入图表
diff --git a/skills/lark-doc/references/lark-doc-xml.md b/skills/lark-doc/references/lark-doc-xml.md
index f5408ecdae..3a1826a5f2 100644
--- a/skills/lark-doc/references/lark-doc-xml.md
+++ b/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 语义不变
+## 正文文本转义
+
+标签保持原样，只转义标签内部的正文文本。正文中的 `<` 和 `&` **必须**分别写成 `<` 和 `&`，否则 XML 无法解析；`>` 通常可以原样保留，但为了生成规则一致也可以写成 `>`。换行使用 `<br/>`。
+
+```xml
+<!-- ❌ 把标签本身转义了 -->
+<p>内容</p>
+
+<!-- ❌ 正文中的 < 和 & 没有转义 -->
+<p>A & B，且 1 < 2</p>
+
+<!-- ✅ 标签原样，正文字符转义 -->
+<p>A & B，且 1 < 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： 💡(默认)✅❌📝❓❗👍❤️📌🏁⭐
-# 七、**重要规则**
-## 转义规则：标签本身 **禁止转义**，只有标签内部的文本内容才需要转义
-
-**错误** ❌：`<p>内容</p>`（把标签也转义了）
-**正确** ✅：`<p>A & B 的对比：1 < 2</p>`（标签保持原样，文本中的 `&` 和 `<` 才转义）
-
-转义字符表：
-- `<` → `<`
-- `>` → `>`
-- `&` → `&`
-- `\n`（换行符） → `<br/>`
-
-
-# 八、完整示例
+# 七、完整示例
```xml
<title>文档标题
一级标题
-加粗文本，绿色文本
+加粗文本，绿色文本；示例：a < b，A & B
高亮框内容，子块仅支持文本/标题/列表/待办/引用