@amaster.ai/pi-lark 0.1.6 → 0.1.8

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

@@ -1,174 +1,78 @@
-
 # docs +update（更新飞书云文档）
 
-> **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：
-> 1. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）
-> 2. [`lark-doc-style.md`](style/lark-doc-style.md) — 写作原则（默认段落、按体裁、组件克制）
-> 3. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、单 Agent 串行改写）
->
-> **未读完以上文件就生成内容会导致格式错误。**
-
-通过八种指令精确更新飞书云文档。支持字符串级别和 block 级别的操作。
-
-> **⚠️ 格式选择规则：**
-> - **局部精修**（`str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after`）：优先使用 XML（默认）。XML 能稳定表达 block 结构和样式，精准编辑更可控；不要因为 Markdown 写起来更简单就自行切换。
-> - **整段写入**（`append` / `overwrite`）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件或明确要求 Markdown 时直接用 Markdown；否则默认 XML。
->
-> **Markdown 局限 & block ID 前提：** Markdown 不携带 block ID，也无样式（颜色、对齐、callout 等）。需要按 block ID 定位（`block_*` 指令的 `--block-id`）时，先 `docs +fetch --detail with-ids` **配合 `--scope`（`outline` / `range` / `keyword` / `section`）局部获取**目标段落，不要全量 fetch。拿到 block ID 后 `--content` 仍可用 Markdown，只是写入内容不带样式。
-
-## 参数
-
-| 参数 | 必填 | 说明 |
-|------|------|------|
-| `--doc` | 是 | 文档 URL 或 token |
-| `--command` | 是 | 操作指令（见下方指令速查表） |
-| `--doc-format` | 否 | 内容格式：`xml`（默认，始终优先使用）\| `markdown`（仅用户明确要求时） |
-| `--content` | 视指令 | 写入内容（`str_replace` 传空字符串可实现删除） |
-| `--reference-map` | 否 | 结构化 `reference_map` JSON object；必须与 `--content` 一起使用。普通写入优先把结构写在正文里；该参数主要用于保留或回放已有 `document.reference_map`。支持直接 JSON、`@reference-map.json`（相对路径）或 `-` 从 stdin 读取。 |
-| `--pattern` | 视指令 | 匹配文本（str_replace） |
-| `--block-id` | 视指令 | 目标 block ID（block_* 操作），逗号分隔可批量删除，-1 表示末尾 |
-| `--src-block-ids` | 视指令 | 源 block ID（逗号分隔），用于 block_copy_insert_after / block_move_after |
-| `--revision-id` | 否 | 基准版本号，-1 = 最新（默认 `-1`） |
-
-## 指令速查表
-
-| 指令 | 说明 | 必需参数 |
-|------|------|----------|
-| `str_replace` | 全文文本查找替换（replacement 支持富文本标签；`--content` 传空字符串即为删除） | `--pattern` `--content` |
-| `block_insert_after` | 在指定 block 之后插入新内容 | `--block-id` `--content` |
-| `block_copy_insert_after` | 复制源 block 并插入到锚点之后（源块不变） | `--block-id` `--src-block-ids` |
-| `block_replace` | 替换指定 block（同一 block 仅限一次） | `--block-id` `--content` |
-| `block_delete` | 删除指定 block（逗号分隔可批量） | `--block-id` |
-| `overwrite` | ⚠️ 清空文档后全文重写（可能丢失图片、评论） | `--content` |
-| `append` | ⚠️ 在文档**末尾**追加内容（等价于 `block_insert_after --block-id -1`）。**不适用于逐章填充**——逐章写入请用 `block_insert_after` 并指定对应标题的 `--block-id` | `--content` |
-| `block_move_after` | 移动已有 block 到指定位置 | `--block-id` `--src-block-ids` |
+使用文本或 block 指令精确更新飞书云文档。默认使用 XML；仅在用户明确要求或必须保真 Markdown 时使用 Markdown。
 
-## Block ID 生命周期
+写入前必须按 `--doc-format` 读取对应格式参考：`xml` 读取 [`lark-doc-xml.md`](lark-doc-xml.md)，`markdown` 读取 [`lark-doc-md.md`](lark-doc-md.md)；
 
-写操作后不要默认复用之前 fetch 到的 block ID：
-
-- `overwrite` / `block_replace` / `block_delete`：受影响旧 ID 失效，继续 block 级操作前重新 fetch
-- `block_insert_after` / `append` / `block_copy_insert_after`：锚点 / 源 ID 通常保留，新内容是新 ID；要操作新内容先重新 fetch
-- `block_move_after`：被移动 ID 通常保留，但位置、章节、range 语义变化；后续依赖位置时重新 fetch
-- `str_replace`：简单行内替换通常不改变 ID；跨行 / 大段替换后如继续 block 级操作，先重新 fetch
-
-## 指令示例
-
-### str_replace — 全文文本替换
-
-> **匹配范围：**
-> - **XML 模式（默认）**：`--pattern` 只支持**行内匹配**，不能跨 block / 跨段落匹配。涉及整段或多 block 的改动，请改用 `block_replace`。
-> - **Markdown 模式**（`--doc-format markdown`）：`--pattern` 同时支持**行内和跨行匹配**，可以用多行字符串匹配并替换一整段内容。
->   - 还支持**`前缀...后缀` 省略号语法**：用 `...`（三个英文句点）串联起始与结束片段，匹配从前缀到后缀之间的全部内容（含中间被省略部分）。适合一段很长、但首尾特征明显的文本，避免把整段都塞进 `--pattern`。
->   - 前缀、后缀本身仍遵循 Markdown 转义规则；省略号中间的内容**会被替换**为 `--content` 的完整文本，不会被保留。
+## 常用示例
 
 ```bash
-# 简单文本替换
-lark-cli docs +update --doc "<doc_id>" --command str_replace \
-  --pattern "张三" --content "李四"
-
-# 替换为富文本（加粗 + 链接）
-lark-cli docs +update --doc "<doc_id>" --command str_replace \
-  --pattern "旧链接" --content '<b>新链接</b> <a href="https://example.com">点击查看</a>'
-
-# 仅当用户明确要求时才使用 Markdown
-lark-cli docs +update --doc "<doc_id>" --command str_replace \
-  --doc-format markdown --pattern "旧内容" --content "新内容"
-
-# Markdown 模式下支持跨行匹配（--pattern 与 --content 都需要真实换行；"..."/'...' 里的 \n 是字面量）
-# 多行内容推荐 heredoc 或 --content @file.md，避免 shell 转义踩坑
-lark-cli docs +update --doc "<doc_id>" --command str_replace \
-  --doc-format markdown \
-  --pattern "$(printf '## 旧标题\n\n第一段原文\n\n第二段原文')" \
-  --content - <<'EOF'
-## 新标题
+# 先定位内容并获取最新 block ID
+lark-cli docs +fetch --doc "文档URL或token" --scope keyword --keyword "key1|key2" --detail with-ids
 
-改写后的第一段
+# 替换文本；--content "" 可删除文本
+lark-cli docs +update --doc "xx" --command str_replace --pattern "旧内容" --content "新内容"
 
-改写后的第二段
-EOF
+# 替换或插入 block
+lark-cli docs +update --doc "xx" --command block_replace --block-id blkTarget --content '<p>新段落</p>'
+lark-cli docs +update --doc "xx" --command block_insert_after --block-id blkAnchor --content '<h2>新章节</h2><p>章节内容</p>'
 
-# Markdown 模式下使用 `前缀...后缀` 省略号匹配首尾特征明显的大段内容
-# 下例会把「## 旧标题」到「结束语。」之间的所有内容整体替换
-lark-cli docs +update --doc "<doc_id>" --command str_replace \
-  --doc-format markdown \
-  --pattern "## 旧标题...结束语。" \
-  --content - <<'EOF'
-## 新标题
-
-重写后的正文...
-
-新的结束语。
-EOF
-
-# 删除文本：--content 传空字符串即可
-lark-cli docs +update --doc "<doc_id>" --command str_replace \
-  --pattern "废弃的内容" --content ""
+# 删除多个 block
+lark-cli docs +update --doc "xx" --command block_delete --block-id "blkA,blkB"
 ```
 
-### block_insert_after — 在指定 block 之后插入
-
-```bash
-lark-cli docs +update --doc "<doc_id>" --command block_insert_after \
-  --block-id "目标 block_id" \
-  --content '<h2>新章节</h2><ul><li>要点 1</li><li>要点 2</li></ul>'
-```
+## 推荐流程
 
-### block_replace — 替换指定 block
+1. **Observe（读取现状）**：先 `docs +fetch` 读取当前文档状态，并按意图选择最小范围。
+   - 改某一节或大文档：先 `--scope outline --max-depth 2` 找章节，再 `--scope section --start-block-id <标题id> --detail with-ids`
+   - 精确跨节区间：用 `--scope range --start-block-id xxx --end-block-id yyy`
+   - 只有模糊关键词：用 `--scope keyword --keyword "key1|key2" --context-before 1 --context-after 1 --detail with-ids`
+   - 明确整篇重构才读 `--detail with-ids` 全文；只读摘要或确认事实时用更轻的 fetch
+2. **Diagnose（诊断问题）**：判断用户目标、当前结构、语气、重复、断流、事实口径和需要保留的资源；识别哪些 block 必须原样保留。
+3. **Patch Plan（制定局部计划）**：把修改拆成最小安全操作：简单行内文本替换用 `str_replace`，但它不支持资源替换，涉及多个 block 时优先使用 `block_replace`；整段/整块重写用 `block_replace`；增补章节用 `block_insert_after`；删冗余用 `block_delete`；调整顺序用 `block_move_after`。
+4. **Patch（精确修改）**：按 block / section 执行局部命令。保护 `<cite>`、`<img>`、`<source>`、`<whiteboard>`、`<sheet>`、`<bitable>`、`<synced_reference>` 等 token 化内容，不要改成纯文本或占位符。同一 block 的多处修改合并成一次 `block_replace`。
+5. **Verify（fetch 验证）**：每轮写操作后按影响范围重新 fetch，检查用户要求、结构、语气、事实、资源块和 block ID 是否符合预期；不满足就基于最新 fetch 结果继续 Diagnose / Patch，不要沿用上一轮 block ID。
 
-```bash
-lark-cli docs +update --doc "<doc_id>" --command block_replace \
-  --block-id "目标 block_id" \
-  --content '<p>替换后的段落内容</p>'
-```
+除非用户明确要求完全重建，或原文已无保留价值，否则不要使用 `overwrite`；它可能丢失评论和暂不支持的资源。
 
-### block_delete — 删除指定 block
-
-```bash
-# 删除多个块时用逗号 "," 分隔
-lark-cli docs +update --doc "<doc_id>" --command block_delete \
-  --block-id "block_id_1,block_id_2,block_id_3"
-```
-
-### overwrite — 全文覆盖
-
-```bash
-lark-cli docs +update --doc "<doc_id>" --command overwrite \
-  --content '<title>全新文档</title><h1>概述</h1><p>新的内容</p>'
-```
+## 生成 block 直达链接
 
-> ⚠️ 会清空文档后重写，可能丢失图片、评论等。仅在需要完全重建文档时使用。
+用户需要某个 block 的直达链接时，只定位 block，不执行文档写操作：
 
-### append — 在文档末尾追加
+1. 使用局部 `docs +fetch --detail with-ids` 获取目标 `block_id`。
+2. 返回 `文档基础 URL#block_id`；没有 `block_id` 时不得猜测。
 
-```bash
-lark-cli docs +update --doc "<doc_id>" --command append \
-  --content '<h2>新增章节</h2><p>追加的内容</p>'
-```
-
-> 等价于 `block_insert_after --block-id -1`，无需先获取 block ID。
-
-### block_copy_insert_after — 复制块并插入
-
-将一个或多个源块复制到锚点块之后，源块保持不变。`--src-block-ids` 为逗号分隔的源块 ID，按顺序依次插入到锚点之后。
-
-```bash
-# 复制多个块（按顺序插入：anchor → a → b → c）
-lark-cli docs +update --doc "<doc_id>" --command block_copy_insert_after \
-  --block-id "锚点 block_id" \
-  --src-block-ids "block_a,block_b,block_c"
-```
-
-### block_move_after — 移动已有 block
+## 参数
 
-将文档中已有的 block 移动到指定锚点之后。使用 `--src-block-ids` 指定要移动的块 ID，无需 `--content`。
-
-```bash
-# 移动到页面末尾
-lark-cli docs +update --doc "<doc_id>" --command block_move_after \
-  --block-id "-1表示末尾，page_id表示开头，blk" \
-  --src-block-ids "block_a,block_b"
-```
+|参数|必填|说明|
+|-|-|-|
+|`--doc`|是|文档 URL 或 token|
+|`--command`|是|更新指令，见下表|
+|`--doc-format`|否|`xml`（默认）或 `markdown`|
+|`--content`|视指令|写入内容；`str_replace` 传空字符串可删除文本|
+|`--pattern`|视指令|`str_replace` 的简单行内匹配文本；不要用于多行、整段或多个 block|
+|`--block-id`|视指令|目标 block ID；批量删除时用逗号分隔；`-1` 表示文档末尾，`0` 表示文档开头（仅适用于支持这些锚点的指令）|
+|`--src-block-ids`|视指令|要复制或移动的源 block ID，多个 ID 用逗号分隔|
+|`--reference-map`|否|保留或回放既有 `reference_map`，需与 `--content` 配合；支持 JSON、任务目录内的相对 `@file` 或 stdin `-`|
+|`--revision-id`|否|基准版本号，默认 `-1`（最新版本）|
+
+## 指令速查
+
+|指令|用途与限制|必需参数|
+|-|-|-|
+|`str_replace`|全文查找替换；支持富文本内的文本替换，但不支持资源替换；涉及多个 block 时建议用 `block_replace`；空 `--content` 表示删除|`--pattern`、`--content`|
+|`block_insert_after`|在指定 block 后插入内容；逐章填充时指定对应标题的 block ID|`--block-id`、`--content`|
+|`block_copy_insert_after`|按 ID 顺序复制源 block，源 block 不变；基础标签均支持，资源块仅支持 `img`、`source`、`whiteboard`、`sheet`、`chat_card`、`sub-page-list`，不支持 `task`、`bitable`、`base_ref`、`synced_reference`、`synced_source`、`okr`|`--block-id`、`--src-block-ids`|
+|`block_replace`|替换指定 block；同一 block 一次操作中只能替换一次|`--block-id`、`--content`|
+|`block_delete`|删除一个或多个 block|`--block-id`|
+|`block_move_after`|移动已有 block，支持所有块类型；|`--block-id`、`--src-block-ids`|
+|`append`|仅在文末追加，等价于 `block_insert_after --block-id -1`|`--content`|
+|`overwrite`|清空后重写全文，丢失图片、评论等内容，非必要不使用|`--content`|
+
+## 通用安全规则
+
+- 每次写操作后都按 block ID 已变化处理。新插入或复制的内容一定使用新 ID；替换、删除和覆盖会使旧 ID 失效；移动会改变章节与 range 语义。
+- 同一 block 有多处修改时，应合并为一次 `block_replace`，避免连续使用旧 ID。
 
 ## 返回值
 
@@ -178,83 +82,27 @@ lark-cli docs +update --doc "<doc_id>" --command block_move_after \
   "identity": "user",
   "data": {
     "document": {
-      "revision_id": 13,
+      "revision_id": 2,
       "new_blocks": [
         { "block_id": "blkcnXXXX", "block_type": "whiteboard", "block_token": "boardXXXX" }
       ]
     },
     "result": "success",
-    "updated_blocks_count": 3,
-    "warnings": []
+    "updated_blocks_count": 1,
+    "warnings": [],
+    "tips": ""
   }
 }
 ```
 
-| 字段 | 说明 |
-|------|------|
-| `result` | `success` \| `partial_success` \| `failed` |
-| `updated_blocks_count` | 实际更新的 block 数量 |
-| `warnings` | 警告信息列表 |
-| `document.new_blocks` | 本次操作新增的 block 列表（如画板）。`block_id` 可用于后续精确编辑；`block_token` 是资源块 token（如画板）可交给 `lark-whiteboard` 等 skill 继续操作 |
-
-## 典型工作流
-
-### 精确 block 级更新
-
-1. **获取文档内容和 block ID**：
-   ```bash
-   lark-cli docs +fetch --doc "<doc_id>" --detail with-ids
-   ```
-
-2. **定位目标 block**：从返回的 XML 中找到要修改的 block 及其 `id` 属性
-
-3. **执行更新**：
-   ```bash
-   # 替换特定 block
-   lark-cli docs +update --doc "<doc_id>" --command block_replace \
-     --block-id "blkcnXXXX" --content "<p>新内容</p>"
-
-   # 在某 block 后插入
-   lark-cli docs +update --doc "<doc_id>" --command block_insert_after \
-     --block-id "blkcnXXXX" --content "<h2>追加的章节</h2>"
-   ```
-
-### 简单文本替换
-
-不需要 block ID，直接匹配替换：
-
-```bash
-lark-cli docs +update --doc "<doc_id>" --command str_replace \
-  --pattern "v1.0" --content "v2.0"
-```
-
-## 画板处理
-
-> **`docs +update` 不能直接编辑已有画板的内容。** 本命令只能**新增**画板块；要修改已有画板，先用 `docs +fetch` 取到 `<whiteboard token="...">`，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 读取 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 并写入。
-
-画板的语法选型与插入示例见 [`lark-doc-xml.md`](lark-doc-xml.md) 与 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md)。
-
-## 最佳实践
-
-- **精确操作优于全文覆盖**：使用 `block_replace`/`block_insert_after` 精确修改，避免 `overwrite` 全文覆盖
-- **str_replace 的匹配范围取决于格式**：
-  - **XML 模式（默认）**：`--pattern` 只支持**行内**匹配，不支持跨行 / 跨 block。段落、整块或容器级（列表、表格、分栏、引用块等）改动请改用 `block_replace` 指定 block_id 重建。
-  - **Markdown 模式**（`--doc-format markdown`）：`--pattern` 同时支持**行内和跨行**匹配，还支持 `前缀...后缀` 省略号语法（用 `...` 串联首尾片段匹配一大段内容），可以一次替换多行文本；但仍建议优先按最小片段匹配，跨 block 容器级重写仍优先用 `block_replace`，避免副作用。
-- **保护不可重建的内容**：图片、画板、电子表格等以 token 形式存储，替换时避开这些 block
-- **str_replace 的 replacement 支持富文本**：可以用行内标签 `<b>`、`<a>`、`<cite>`、`<latex>` 等替换普通文本为富文本
-- **同一 block 只能被 replace 一次**：多次修改同一 block 请合并为一次 block_replace
-- **block_delete 支持批量**：用逗号分隔多个 block_id 一次删除
-- **复杂结构重组**：将多个段落转换为 grid / table 等复杂布局时，分步操作比 overwrite 更安全：
-  1. 用 `block_insert_after` 在目标位置插入新的富文本结构
-  2. 用 `block_delete` 批量删除旧的 block
-  3. 这样可以保留文档中其他不相关的内容（图片、评论等）
-- **表达形式**：插入或替换内容时，优先沿用用户要求和已有文档风格；需要结构化表达时可参考 [`lark-doc-style.md`](style/lark-doc-style.md)，但不要为了固定丰富度主动添加组件
+|字段|说明|
+|-|-|
+|`result`|`success` \| `partial_success` \| `failed`|
+|`updated_blocks_count`|实际更新的 block 数量|
+|`warnings`|服务端返回的警告列表；即使 `result=success` 也要检查是否存在降级或未完全处理的内容|
+|`tips`|服务端返回的后续处理建议；为空表示没有额外建议，非空本身不表示更新失败|
+|`document.new_blocks`|新增 block；`block_id` 用于后续编辑，资源块的 `block_token` 可交给对应 skill 继续处理|
 
-## 参考
+## 需要查文档
 
-- [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、单 Agent 串行改写）
-- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档写作原则（默认段落、按体裁、组件克制）
-- [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范
-- [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档
-- [`lark-doc-create.md`](lark-doc-create.md) — 创建文档
-- [`lark-doc-media-insert.md`](lark-doc-media-insert.md) — 插入图片/文件到文档
+可查看 [`+fetch`](lark-doc-fetch.md)。

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

@@ -1,12 +1,10 @@
 # lark-doc 画板处理指南
 
-> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
-
 ## 两个 Skill 的职责边界
 
 | Skill             | 核心职责                                                      | 约束                              |
 |-------------------|-----------------------------------------------------------|---------------------------------|
-| `lark-doc`        | 识别画板机会、使用 Mermaid/SVG 创建图表、调度 SubAgent、插入简单 SVG 画板或复杂空白画板 | 主 Agent 不直接创作画板内容；              |
+| `lark-doc`        | 识别画板机会、使用 Mermaid/SVG 创建图表、调度 SubAgent、插入简单图表或复杂空白画板 | 简单图可由主 Agent 直接写入；复杂图再隔离到 SubAgent |
 | `lark-whiteboard` | 查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板  | 仅特别复杂的图表或已有画板更新时由独立 SubAgent 读取 |
 
 ## 画板适用规则
@@ -29,11 +27,9 @@
 > [!IMPORTANT]
 > ⚠️ **分别对每个图表进行决策**
 
-如果有多个位置需要插入图表，你需要根据每个图表的内容**分别决定**采用步骤 2A 还是 2B
-中的方式插入这个图表。在需要插入思维导图、时序图、类图、饼图、甘特图的时候可以插入 mermaid 块，在需要插入其他类型图表时启动
-SubAgent 插入 SVG。
+如果有多个位置需要插入图表，你需要根据每个图表的内容**分别决定**采用步骤 2A 还是 2B。思维导图、时序图、类图、饼图、甘特图可插入 mermaid 块；其他类型图表使用 SVG，简单图由主 Agent 直接写入，复杂图再启动 SubAgent。
 
-建议优先使用 SVG 插入图表，除非其属于思维导图、时序图、类图、饼图、甘特图这类可以直接使用 mermaid 语法描述，且不适宜用 SVG 绘制的图表
+简单 Mermaid / SVG 图可由主 Agent 直接写入本地 XML；需要专门视觉设计、信息密度较高或容易布局翻车的 SVG，再启动 SubAgent 产出完整片段。
 
 ### 步骤 2A: 使用 mermaid 插入图表
 
@@ -44,7 +40,7 @@ SubAgent 插入 SVG。
 </whiteboard>
 ```
 
-如果 Mermaid 已在本地文件中，可写成 `<whiteboard type="mermaid" path="@diagram.mmd"></whiteboard>`；CLI 会在写入前读取文件并展开为内联内容。
+如果 Mermaid 已在本地文件中，可写成 `<whiteboard type="mermaid" path="@./diagram.mmd"></whiteboard>`；CLI 会在写入前读取文件并展开为内联内容。
 
 ### 步骤 2B: SubAgent 使用 SVG 插入图表
 
@@ -58,7 +54,7 @@ SubAgent 插入 SVG。
 </whiteboard>
 ```
 
-如果 SVG 已在本地文件中，可写成 `<whiteboard type="svg" path="@diagram.svg"></whiteboard>`；PlantUML 文件同理使用 `<whiteboard type="plantuml" path="@sequence.puml"></whiteboard>`。
+如果 SVG 已在本地文件中，可写成 `<whiteboard type="svg" path="@./diagram.svg"></whiteboard>`；PlantUML 文件同理使用 `<whiteboard type="plantuml" path="@./sequence.puml"></whiteboard>`。
 
 Sub Agent 需要携带以下的最小上下文，以及后续的 [SVG 设计 Workflow] 章节指南：
 
@@ -98,8 +94,8 @@ Sub Agent 需要携带以下的最小上下文，以及后续的 [SVG 设计 Wor
 
 ###### 画板怎么处理 SVG
 
-画板的 svg-parser 把可识别元素转成可编辑节点, 其余降级为内嵌图片(渲染没问题, 虽然不可编辑, 但是可以正常显示)；但
-`<radialGradient>` / `<filter>` / `<clipPath>` 等装饰特性画板完全不支持，会导致渲染问题（见下方⚠️）
+画板的 svg-parser 把可识别元素转成可编辑节点, 其余降级为内嵌图片(渲染没问题, 虽然不可编辑, 但是可以正常显示)；但非阴影用途的
+`<filter>` / `<pattern>` / `<clipPath>` / `<mask>` 等装饰特性画板不支持（见下方⚠️）
 **不需要所有元素都可编辑, 但必须避免使用不支持的装饰特性, 且要兼顾可编辑和美观漂亮**
 
 **可识别的元素**
@@ -109,12 +105,14 @@ Sub Agent 需要携带以下的最小上下文，以及后续的 [SVG 设计 Wor
 - 文本：`<text>` / `<tspan>` 画板硬编码 Noto Sans SC **文字必须用 `<text>`**
 - 分组：`<g>` / `<a>` / `<use>` 引用 `<symbol>`
 - 变换：`translate` / `rotate` / `scale` 正常；`skewX` / `skewY` / `matrix(...)` 降级
+- 阴影：`<filter>` 里放 `<feDropShadow>` 或标准 drop/inner primitive 链 (`<feGaussianBlur in="SourceAlpha">` + `<feOffset>` + `<feFlood>` + `<feComposite>` + `<feMerge>`), 会被识别成节点阴影, drop 至多 1 个, inner 至多 1 个; 其余 filter 效果不识别
+- 渐变：`<linearGradient>` / `<radialGradient>` 在 `<defs>` 中定义, 通过 `fill="url(#id)"` 引用 (载体限 `<rect>` / `<circle>` / `<ellipse>` / `<polygon>` / `<path>`), 需要至少 2 个 `<stop>`, `gradientUnits` 只支持默认的 `objectBoundingBox` (不写即可)
 
 > [!IMPORTANT]
-> ⚠️ ** 不支持的装饰特性**
+> ⚠️ **不支持的装饰特性**
 
-- `<radialGradient>` / `<filter>` / `<pattern>` / `<clipPath>` / `<mask>` → 画板都不支持，**请避免使用，否则会导致画板渲染问题
-  **
+- `<pattern>` / `<clipPath>` / `<mask>` / 非阴影用途的 `<filter>` (blur / hue-rotate / 复合合成 / `flood-color=url(...)` / 多个 `<feDropShadow>` 等) → 画板不支持，**请避免使用，否则会导致画板渲染问题**
+- 渐变边界：`gradientUnits="userSpaceOnUse"` / `spreadMethod="reflect|repeat"` / stops 少于 2 个 / 复杂 `gradientTransform` 会变成不可编辑图片, 视觉正确但失去可编辑性, 若无必要请沿用默认 `objectBoundingBox`
 
 ###### 3.插入后审查
 
@@ -123,9 +121,9 @@ Sub Agent 需要携带以下的最小上下文，以及后续的 [SVG 设计 Wor
 `../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md) 编辑。
 
 ```bash
-lark-cli whiteboard +query \
+lark-cli whiteboard +export \
   --whiteboard-token "wbcnxxxxxxxx" \
-  --output_as image \
+  --output-type preview \
   --output ./preview.png
 ```
 
@@ -150,7 +148,6 @@ lark-cli whiteboard +query \
 
 ---
 
-
 ---
 
 ## 关联参考

package/skills/lark-doc/references/lark-doc-xml-extended-blocks.md

@@ -2,7 +2,53 @@
 
 本文件用于补充说明 block XML 扩展能力。常用标签和通用规则见 [`lark-doc-xml.md`](lark-doc-xml.md)；后续新增其他 block 说明时可继续追加到本文件。
 
+## 拓展标签
+- `<bookmark name="示例站点" href="https://example.com"></bookmark>`
+- `<button action="OpenLink" src="https://example.com">操作按钮</button>`：`action` 可为 `OpenLink`、`DuplicatePage` 或 `FollowPage`；可选 `background-color`、`src`。
+- `<time expire-time="1775916000000" notify-time="1775912400000" should-notify="false">提醒</time>`：使用毫秒时间戳。
+- `<sheet type="blank"/>`：创建空白表格；`<sheet sheet-id="SHEET_ID" token="SPREADSHEET_TOKEN"/>`：复制已有表格。
+- `<task task-id="TASK_GUID"/>`：挂载任务，`task-id` 为任务 GUID。
+- `<chat_card chat-id="CHAT_ID"/>`：挂载聊天卡片。
+- `<sub-page-list/>`：子页面列表块，仅 wiki 文档可插入。
+
+
+## HTML5 block
+
+1. 写入 HTML 内容块时，把完整单文件 HTML 存为本地 `.html` 文件，XML 写 `<html5-block path="@./widget.html"/>`；已有 `data-ref` 时配合 `--reference-map @./reference-map.json`。读取时 `<html5-block data-ref="html5_1"></html5-block>` 只是占位，必须从 `document.reference_map["html5-block"]["html5_1"].data` 读取 HTML；若 entry 是 `path`，读取对应 `@./doc-fetch-resources/...html` 文件。
+2. 格式如下：
+
+```html
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="use-iframe" content="true">
+  <meta name="html-box-height-mode" content="auto">
+  <meta name="description" content="内容摘要，会导出为 html5-block 的 alt 属性，帮助模型理解该 HTML 块的用途">
+  <title></title>
+</head>
+<body>
+  ...
+</body>
+</html>
+```
+
+### 布局与高度
+
+只使用 `auto` 或 `viewport`：正文需要在文档中完整展开时使用 `auto`；内容需要在 HTML Block 内滚动或单屏呈现时使用 `viewport`。`lark-cli` 会将 HTML 原样写入 `reference_map`，不会校验该字段，因此创建或更新前必须在 `<head>` 中显式声明。
+
+- `auto`：使用普通文档流，不给根容器设置固定高度或 `overflow: hidden`。需要固定操作区时，在业务容器上设置 CSS `height` 和 `overflow: auto`，不要把像素值写入 meta。
+- `viewport`：使用 `100vh` 和内部滚动、切页或缩放，适用于游戏、幻灯片、Dashboard、canvas 编辑器。
+- 页面加载后的内容追加或展开不会由 `lark-cli` 刷新高度，不要臆造相关 CLI flag。
+- 文档常见可用宽度约 `820px`；根容器使用 `width: 100%`、`max-width: 100%`、`box-sizing: border-box`。
+
+### 内容限制
+
+- HTML 总长度上限为 500KB。不要内联大图片、Base64、字体、长 JSON/CSV 或大量 mock 数据。
+
 ## OKR block
+`<okr cycle-id="CYCLE_ID"></okr>`：创建时仅支持 root-only。
 
 OKR block 可用 XML 格式完整表达。创建前先参考 [`lark-okr`](../../lark-okr/SKILL.md) 确认可用周期；创建时只写 root-only `<okr cycle-id="..."/>` 挂载已有 OKR，不构造 Objective/KR/Progress 子树。