@amaster.ai/pi-lark 0.1.7 → 0.1.9

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

@@ -0,0 +1,76 @@
+# `docs +script`
+
+## 脚本列表
+
+| `--command` | 用途 |
+|-|-|
+| `init-draft` | 创建带 Presentation Decision 基线的独占工作区，并预留尚不存在的 XML 路径。 |
+| `parse` | 解析本地或在线文档，返回画像并检查决策与资源。 |
+
+每个脚本只使用其小节列出的专用参数；所有脚本均可使用文末的通用参数。
+
+## `init-draft`
+
+### 参数
+
+| 参数 | 必填 | 用法 |
+|-|-|-|
+| `--command init-draft` | 是 | 选择本脚本。 |
+| `--presentation-decision` | 是 | 完整决策 JSON；接受内联 JSON、`@./decision.json` 形式的 CWD 下相对路径或 `-`（stdin）。 |
+
+```bash
+lark-cli docs +script --command init-draft \
+  --presentation-decision '<完整 Presentation Decision JSON>' \
+  --format json
+```
+
+`data` 的结构如下；实际随机段为 8 位十六进制字符：
+
+```json
+{
+  "workspace": "draft_a1b2c3d4_folder",
+  "draft_path": "draft_a1b2c3d4_folder/draft.xml",
+  "tip": "The workspace directory has been created successfully. draft_path points to a new XML file that does not exist yet. Create and write the file directly without reading it first."
+}
+```
+
+- 在生成正文前执行；不要自行创建工作目录或决策文件。CLI 固定生成 `draft_<8位十六进制字符>_folder/draft.xml`，以返回的实际路径为准。
+- 决策必须是单个 JSON 对象，包含 `audience`、`reader_task`、`genre_contract`、`adapter`、`presentation_mode` 和 `visual_plan`。`presentation_mode` 取 `formal|normal|rich`；`genre_contract`、`adapter` 使用固定短名、`"none"` 或 `null`。
+- `visual_plan` 包含非空 `reason` 和 `blocks` 数组；每项为 `{type,min_count,purpose}`，`type` 不重复，`min_count` 为正整数。按本 Skill 创建文档时，`blocks` 只对 `whiteboard`、`img`、`html5-block` 设置最低数量，其他表达按内容需要使用但不设数量约束；三类均无需约束时写 `[]`。CLI 为外部决策兼容 `type: "list"`，检查时将 `<ul>` 与 `<ol>` 的数量相加。仅有字数要求时添加 `word_count: {min,max}`；未指定的一侧写 `null`，至少一侧为正整数，且 `min <= max`。
+- 返回 `data.workspace`（已创建的随机工作区）、`data.draft_path`（可直接写入的 XML 路径）和英文操作提示 `data.tip`。工作区及其中的 `.presentation-decision.json` 已存在，但 XML 尚不存在；遵循提示直接使用文件创建/写入能力在 `draft_path` 写入完整 XML，首次写入前不要读取该路径。
+- 后续始终使用 `draft_path`，不得另建 XML、复用其他任务的路径或修改工作区中的 `.presentation-decision.json`；使用完后精确删除 `workspace`。
+
+## `parse`
+
+### 参数
+
+| 参数 | 必填 | 用法 |
+|-|-|-|
+| `--command parse` | 是 | 选择本脚本。 |
+| `--content` | 二选一 | 本地 XML 的字面内容、`@./document.xml` 形式的 CWD 下相对路径或 `-`（stdin）。 |
+| `--doc` | 二选一 | 在线 Docx/Wiki URL 或 token；与 `--content` 互斥。 |
+| `--presentation-decision` | 否 | 用于检查当前输入的完整决策 JSON；支持内联、`@./decision.json` 形式的 CWD 下相对路径或 `-`。 |
+
+```bash
+lark-cli docs +script --command parse --content "@./document.xml" --format json
+lark-cli docs +script --command parse --doc "<Docx/Wiki URL 或 token>" --format json
+lark-cli docs +script --command parse --content "@./document.xml" --presentation-decision '<JSON>' --format json
+```
+
+- `--content` 与 `--presentation-decision` 同时使用时，最多一个参数读取 stdin。
+- 决策必须包含 `audience`、`reader_task`、`genre_contract`、`adapter`、`presentation_mode` 和 `visual_plan`；`presentation_mode` 取 `formal|normal|rich`。`visual_plan` 包含非空 `reason` 和不重复的 `{type,min_count,purpose}` 数组；兼容的 `list` 约束按 `<ul>` 与 `<ol>` 的合计数量检查。仅有字数要求时添加合法的 `word_count: {min,max}`。
+- 使用 `--content "@./<init-draft 返回的 data.draft_path>"` 时自动加载保存的决策；显式 `--presentation-decision` 优先。
+- `--doc` 需要 `docx:document:readonly`；`--content` 不调用 OpenAPI。
+- 返回 `data.assessment.status`、`data.profile` 和按需出现的 `data.diagnostics[]`；profile 包含 `word_count`、`char_count`、`block_count` 和 `blocks[]`。顶层 `ok` 只表示命令是否成功执行。画像、决策或资源预检未通过时，命令仍以 `ok:true` 和退出码 0 返回，但 `assessment.status` 为 `failed`；每条 diagnostic 提供 `severity`、稳定 `code`、`msg`、可选 `expected` / `actual` 和 `suggested`。同一原因失败的远程图片合并为一条 diagnostic，并在 `image_indices[]` 中列出图片序号，避免重复提示。修复后重新解析，直到 `assessment.status` 为 `passed`。
+- `parse` 不是 XML/SDK schema validator。成功且无 warning 也不保证服务端接受；写入前仍须按 XML 规则复查。
+
+## 所有脚本通用参数
+
+| 参数 | 用法 |
+|-|-|
+| `--as user|bot` | 选择身份。 |
+| `--dry-run` | 只返回执行计划，不联网、解析或写文件。 |
+| `--format` | 输出格式：`json|pretty|table|ndjson|csv`；模型使用默认的 `json`。 |
+| `--json` | `--format json` 的别名。 |
+| `--jq` / `-q` | 裁剪 JSON；不得与非 JSON 格式同时使用。 |
+| `-h` / `--help` | 查看帮助。 |

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

@@ -1,174 +1,82 @@
-
 # 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 生命周期
-
-写操作后不要默认复用之前 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'
-## 新标题
-
-改写后的第一段
-
-改写后的第二段
-EOF
-
-# 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_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>'
-```
+写入前必须按 `--doc-format` 读取对应格式参考：`xml` 读取 [`lark-doc-xml.md`](lark-doc-xml.md)，`markdown` 读取 [`lark-doc-md.md`](lark-doc-md.md)；
 
-### block_replace — 替换指定 block
+## 常用示例
 
 ```bash
-lark-cli docs +update --doc "<doc_id>" --command block_replace \
-  --block-id "目标 block_id" \
-  --content '<p>替换后的段落内容</p>'
-```
+# 先定位内容并获取最新 block ID
+lark-cli docs +fetch --doc "文档URL或token" --scope keyword --keyword "key1|key2" --detail with-ids
 
-### block_delete — 删除指定 block
+# 替换文本；--content "" 可删除文本
+lark-cli docs +update --doc "xx" --command str_replace --pattern "旧内容" --content "新内容"
 
-```bash
-# 删除多个块时用逗号 "," 分隔
-lark-cli docs +update --doc "<doc_id>" --command block_delete \
-  --block-id "block_id_1,block_id_2,block_id_3"
-```
+# 替换单个 block，或同父连续范围内的 block
+lark-cli docs +update --doc "xx" --command block_replace --block-id blkTarget --content '<p>新段落</p>'
+lark-cli docs +update --doc "xx" --command block_replace --start-block-id blkFirst --end-block-id blkLast --content '<p></p>'
 
-### overwrite — 全文覆盖
+lark-cli docs +update --doc "xx" --command block_insert_after --block-id blkAnchor --content '<h2>新章节</h2><p>章节内容</p>'
 
-```bash
-lark-cli docs +update --doc "<doc_id>" --command overwrite \
-  --content '<title>全新文档</title><h1>概述</h1><p>新的内容</p>'
+# 删除单个 block 或范围内的 block
+lark-cli docs +update --doc "xx" --command block_delete --block-id blkA
+lark-cli docs +update --doc "xx" --command block_delete --start-block-id blkFirst --end-block-id blkLast
 ```
 
-> ⚠️ 会清空文档后重写，可能丢失图片、评论等。仅在需要完全重建文档时使用。
+## 推荐流程
 
-### append — 在文档末尾追加
+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-id`，同一直接父节点下的连续 block 用 `--start-block-id`/`--end-block-id`。连续范围适用于 `block_replace` 和 `block_delete`。整段/整块重写用 `block_replace`；增补章节用 `block_insert_after`；删冗余用 `block_delete`；调整顺序用 `block_move_after`。
+4. **Patch（精确修改）**：按 block / section 执行局部命令。替换内容必须符合目标父容器的结构；例如替换列表项范围时使用 `<li>...</li>`。保护 `<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 append \
-  --content '<h2>新增章节</h2><p>追加的内容</p>'
-```
+除非用户明确要求完全重建，或原文已无保留价值，否则不要使用 `overwrite`；它可能丢失评论和暂不支持的资源。
 
-> 等价于 `block_insert_after --block-id -1`，无需先获取 block ID。
+## 生成 block 直达链接
 
-### block_copy_insert_after — 复制块并插入
+用户需要某个 block 的直达链接时，只定位 block，不执行文档写操作：
 
-将一个或多个源块复制到锚点块之后，源块保持不变。`--src-block-ids` 为逗号分隔的源块 ID，按顺序依次插入到锚点之后。
+1. 使用局部 `docs +fetch --detail with-ids` 获取目标 `block_id`。
+2. 返回 `文档基础 URL#block_id`；没有 `block_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` 表示文档开头（仅适用于支持这些锚点的指令）|
+|`--start-block-id` / `--end-block-id`|视指令|`block_replace` / `block_delete` 的同父连续闭区间，必须成对使用，且不能与 `--block-id` 混用；`--start-block-id` 用 `0` 表示从文档开头开始，`--end-block-id` 用 `-1` 表示到文档末尾结束|
+|`--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-id`）或同父连续闭区间（`--start-block-id`/`--end-block-id`）；不支持跨容器或反向区间|`--content`，以及 `--block-id` 或 `--start-block-id`+`--end-block-id`|
+|`block_delete`|删除单个 block（`--block-id`）或同父连续闭区间（`--start-block-id`/`--end-block-id`）；不支持跨容器或反向区间|`--block-id` 或 `--start-block-id`+`--end-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 +86,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] 章节指南：
 

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

@@ -2,9 +2,19 @@
 
 本文件用于补充说明 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"></html5-block>`；已有 `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` 文件。
+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
@@ -26,24 +36,19 @@
 
 ### 布局与高度
 
-- `lark-cli` 会读取 `.html` 文件并原样写入 `reference_map`，不会解析或校验 `html-box-height-mode`；创建或更新文档前在 `<head>` 中显式声明 `auto` 或 `viewport`。
-- 生成时只使用 `auto` 或 `viewport`，不要臆造 `fixed`、`initial` 或像素值等其他 mode。
-- 文档常见可用宽度约 `820px`；根容器使用 `width: 100%`、`max-width: 100%`、`box-sizing: border-box`。
-
-四种策略：
-
-1. 内容自然撑开：`auto` + 普通文档流；根容器不设固定高度或 `overflow: hidden`。
-2. 仅按初始内容定高：`auto` + 首次渲染后不再追加或展开内容。
-3. 固定像素操作区：`auto` + 业务容器按场景设置固定的 CSS `height` 和 `overflow: auto`；高度数值不写进 meta。
-4. 单屏应用：`viewport` + `100vh` + 内部滚动、切页或缩放；适用于游戏、幻灯片、Dashboard、canvas 编辑器。
+只使用 `auto` 或 `viewport`：正文需要在文档中完整展开时使用 `auto`；内容需要在 HTML Block 内滚动或单屏呈现时使用 `viewport`。`lark-cli` 会将 HTML 原样写入 `reference_map`，不会校验该字段，因此创建或更新前必须在 `<head>` 中显式声明。
 
-正文需要在飞书文档中完整展开时选 `auto`；内容应在 HTML Block 内滚动时选 `viewport`。`lark-cli` 不参与页面加载后的高度刷新，不要臆造相关 CLI flag。
+- `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 子树。