@yandy0725/pi-lark 0.1.0

package/skills/lark-doc/references/lark-doc-media-insert.md

@@ -0,0 +1,114 @@
+
+# docs +media-insert（文档末尾插入图片/文件）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+把"创建空 block → 上传文件 → 设置 token"三步合并成一个命令，在**文档末尾**插入本地图片或文件。
+
+## 来源选择（Agent 必读）
+
+> **最高优先级：用户明确指定了来源，就严格按用户的来。** 下面的启发式只在用户没表态时生效。
+>
+> - 用户说"把这张截图插进去"、"用剪切板里的图"、"我刚复制的" → 无条件走 `--from-clipboard`。
+> - 用户说"用 `~/Downloads/foo.png`"、"插本地这个文件"、给了具体路径 → 无条件走 `--file`。
+> - 用户两者都没说清 → 按下表的启发式推断。
+>
+> 即使推断看起来更"优"（比如用户说了路径但你觉得走剪切板更省事），也**不要自作主张**换来源。要换，先问。
+
+按下列顺序判断，**不要反向做**：
+
+| 用户的图片来源 | 命令 | 禁止做法 |
+|----------------|------|----------|
+| 图片已经在剪切板里（截图快捷键、从飞书/浏览器复制、从设计稿复制） | `--from-clipboard` | ❌ 不要先把剪切板存到本地文件再用 `--file`。多一步文件 I/O，还得清理临时文件。 |
+| 图片是磁盘上的真实文件 | `--file <path>` | — |
+| 图片是 URL | 先下载到本地 → `--file`；或用 `drive` 相关命令 | — |
+
+`--from-clipboard` 走进程内存直传，不产生临时文件；macOS / Windows 内置支持，Linux 需要 `xclip` 或 `wl-paste` 或 `xsel` 任一。
+
+### 剪切板为空时的 fallback
+
+`--from-clipboard` 失败（剪切板里不是图片 / 没有图片 / Linux 上三个工具都没装）时，命令会返回 `clipboard contains no image data`（或类似的平台错误）。**这不是错误退出理由，而是 fallback 信号。**
+
+**Agent 的标准处置顺序**（每一步失败再进下一步，不要并行）：
+
+1. 先用 `--from-clipboard` 试一次。
+2. 如果返回"no image data"类错误，**向用户明确说明剪切板里没有可识别的图片**，请用户提供本地文件路径或重新复制一张图。
+3. 拿到本地路径后，用 `--file <path>` 重试**同一条插入命令**（其他参数如 `--doc` / `--align` / `--caption` 保持不变）。
+
+**禁止做法**：
+- ❌ 不要悄悄把空剪切板当"成功但没插入"处理。必须提示用户。
+- ❌ 不要在剪切板失败后自行瞎猜某个本地文件路径（比如最近修改的 png）。必须让用户给路径。
+- ❌ 不要用"先让用户保存剪切板到磁盘再 `--file`"的建议绕过 `--from-clipboard`，当且仅当剪切板确实没图片时才退回本地路径。
+
+## 命令
+
+```bash
+# 🟢 推荐：从剪切板直接插入（无需先存盘）
+lark-cli docs +media-insert --doc doxcnXXX --from-clipboard
+
+# 从本地文件插入
+# 除了上传本地文件，还可以在 `docs +update` 时直接通过网络 URL 插入图片，无需先下载到本地：
+lark-cli docs +update --doc "<doc_id>" --command block_insert_after \
+  --block-id "目标 block_id" \
+  --content '<img href="https://example.com/photo.png"/>'
+
+# 插入图片（默认）
+lark-cli docs +media-insert --doc doxcnXXX --file ./image.png
+
+# doc 支持直接传 docx URL（自动提取 document_id）
+lark-cli docs +media-insert --doc "https://xxx.feishu.cn/docx/doxcnXXX" --from-clipboard
+
+# 如果上一步是 create-doc，优先传返回值里的 doc_id
+# 不要把 /wiki/... 形式的 doc_url 直接传给 docs +media-insert
+lark-cli docs +media-insert --doc doxcnReturnedByCreateDoc --file ./image.png
+
+# 插入文件（非图片）
+lark-cli docs +media-insert --doc doxcnXXX --file ./spec.pdf --type file
+
+# 图片对齐与描述（caption）
+lark-cli docs +media-insert --doc doxcnXXX --from-clipboard --align center --caption "架构图"
+
+# Insert image with explicit display width (height auto-computed from aspect ratio)
+lark-cli docs +media-insert --doc doxcnXXX --file ./banner.png --width 800 --align center
+
+# Insert image with explicit width and height
+lark-cli docs +media-insert --doc doxcnXXX --from-clipboard --width 800 --height 447 --caption "architecture diagram"
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--doc <id>` | 是 | 文档 ID 或 docx URL（仅支持 `/docx/<document_id>` 形式自动提取；**不支持 `/wiki/...` URL 自动提取**） |
+| `--from-clipboard` | 二选一 | 从系统剪切板读取图片（与 `--file` 互斥）。macOS/Windows 内置支持，Linux 需要 `xclip` / `wl-paste` / `xsel` 之一。 |
+| `--file <path>` | 二选一 | 本地文件路径（文件大于 20MB 时自动切换分片上传） |
+| `--type <type>` | 否 | `image`（默认）或 `file`。`--from-clipboard` 目前只产出 image。 |
+| `--align <align>` | 否 | 仅图片：`left` / `center`（默认）/ `right` |
+| `--caption <text>` | 否 | 仅图片：图片描述 |
+| `--width <px>` | 否 | Image display width in pixels (only for `--type=image`). If `--height` is omitted, it is auto-computed from the source image aspect ratio. Supported auto-detection formats: PNG, JPEG, GIF; other formats (WebP, BMP, etc.) require both `--width` and `--height`. |
+| `--height <px>` | 否 | Image display height in pixels (only for `--type=image`). If `--width` is omitted, it is auto-computed from the source image aspect ratio. Supported auto-detection formats: PNG, JPEG, GIF; other formats (WebP, BMP, etc.) require both `--width` and `--height`. |
+
+> [!IMPORTANT]
+> 如果上一步是 [`lark-doc-create`](lark-doc-create.md)，并且它在知识库/知识空间场景下返回的是 `/wiki/...` 形式的 `doc_url`，后续调用 `docs +media-insert` 时应优先传 `doc_id`，不要直接传这个 `doc_url`。
+
+## 平台注意（仅 `--from-clipboard`）
+
+| 平台 | 依赖 | 典型错误 |
+|------|------|---------|
+| macOS | osascript（内置） | 剪切板为空 / 不是图片 → "clipboard contains no image data" |
+| Windows | PowerShell + System.Windows.Forms（内置） | 同上 |
+| Linux | `xclip` 或 `wl-paste` 或 `xsel` 任一 | 都没安装 → 报错会提示用发行版包管理器安装 |
+
+命令不支持读取 TIFF 等非 PNG/JPEG/GIF/WebP/BMP 的冷门格式；遇到这类剪切板会返回 "contains no image data"，此时才考虑先用系统工具转成文件再 `--file`。
+
+## 输出
+
+命令成功后会输出 JSON，包含：`document_id`、`block_id`、`file_token`、`file_name`（剪切板路径下为 `clipboard.png`）、`type`。
+
+> [!CAUTION]
+> 这是**写入操作**（会修改文档内容）—— 执行前必须确认用户意图。
+
+## 参考
+
+- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（可用于确认插入后的结果、以及提取媒体 token）
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/skills/lark-doc/references/lark-doc-media-preview.md

@@ -0,0 +1,41 @@
+
+# docs +media-preview（预览文档素材）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+优先用于查看、预览文档中的图片或文件素材（`file_token`）。命令会把素材保存到本地路径，便于后续打开查看内容。
+
+## 选择规则
+
+- 用户说“看一下素材 / 图片 / 附件”“预览一下”时，优先使用 `docs +media-preview`
+- 用户明确说“下载”时，使用 [`docs +media-download`](lark-doc-media-download.md)
+- 如果目标明确是画板 / whiteboard / 画板缩略图，不要使用 `+media-preview`，改用 `docs +media-download --type whiteboard`
+
+## 命令
+
+```bash
+# 预览图片/文件素材
+lark-cli docs +media-preview --token "Z1Fjxxxxxxxx" --output ./asset
+
+# 指定输出文件名（带扩展名则不会自动补全）
+lark-cli docs +media-preview --token "Z1Fjxxxxxxxx" --output ./asset.png
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--token <token>` | 是 | 素材 token，即 `file_token` |
+| `--output <path>` | 是 | 本地保存路径；不带扩展名会自动补全 |
+
+## token 从哪里来
+
+- 若你是从文档内容里提取：`lark-doc-fetch` 返回的 Markdown 里可能包含：
+  - 图片：`<image token="..." .../>`
+  - 文件：`<file token="..." name="..."/>`
+
+## 参考
+
+- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（用于提取 token）
+- [lark-doc-media-download](lark-doc-media-download.md) — 明确下载素材，或下载画板缩略图
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/skills/lark-doc/references/lark-doc-resource-cover.md

@@ -0,0 +1,70 @@
+# docs +resource-*（Docx 封面图资源）
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+Docx 封面图不是正文里的 `<img token="...">` 素材块。读取、更新、删除文档封面图时，使用 `docs +resource-download/+resource-update/+resource-delete --type cover`，不要使用 `+media-insert` 或 `+media-download --token <cover.token>` 让用户手动拼步骤。
+
+## 选择规则
+
+- 用户要下载文档封面图：`docs +resource-download --type cover`
+- 用户要设置/替换文档封面图：`docs +resource-update --type cover`
+- 用户要删除文档封面图：`docs +resource-delete --type cover`
+- 用户要下载正文图片、附件、画板缩略图：继续使用 [`docs +media-download`](lark-doc-media-download.md)
+
+## 命令
+
+```bash
+# 下载封面图。CLI 会先读取 document.cover.token，再下载图片内容并保存到本地。
+lark-cli docs +resource-download --doc doxcnXXX --type cover --output ./cover
+
+# 使用本地文件更新封面图。
+lark-cli docs +resource-update --doc doxcnXXX --type cover --file ./cover.png
+
+# 使用剪切板图片更新封面图。
+lark-cli docs +resource-update --doc doxcnXXX --type cover --from-clipboard
+
+# 使用 HTTPS URL 更新封面图。CLI 会先下载 URL 内容，再上传并写入 cover.token。
+lark-cli docs +resource-update --doc doxcnXXX --type cover --url "https://example.com/cover.png"
+
+# 可选：设置封面图裁切偏移。
+lark-cli docs +resource-update --doc doxcnXXX --type cover --file ./cover.png --offset-ratio-x 0.2 --offset-ratio-y 0.8
+
+# 删除封面图；当文档本来没有封面图时也成功返回。
+lark-cli docs +resource-delete --doc doxcnXXX --type cover
+```
+
+## 参数
+
+| 命令 | 参数 | 必填 | 说明 |
+|------|------|------|------|
+| all | `--doc <id>` | 是 | 文档 ID、docx URL，或可解析为 docx 的 wiki URL |
+| all | `--type cover` | 否 | 当前只支持 `cover`；默认值也是 `cover` |
+| download | `--output <path>` | 是 | 本地保存路径；不带扩展名会根据响应类型自动补全 |
+| download | `--overwrite` | 否 | 覆盖已存在的输出文件 |
+| update | `--file <path>` | 三选一 | 磁盘上的真实图片文件；大于 20MiB 自动使用分片上传 |
+| update | `--from-clipboard` | 三选一 | 从系统剪切板读取图片 |
+| update | `--url <https-url>` | 三选一 | 从 HTTPS URL 下载图片后上传 |
+| update | `--offset-ratio-x <number>` | 否 | 视图相对原图中心的横向偏移比例：水平偏移 px / 原图宽度 px；0 为居中，正数向右，负数向左 |
+| update | `--offset-ratio-y <number>` | 否 | 视图相对原图中心的纵向偏移比例：垂直偏移 px / 原图高度 px；0 为居中，正数向上，负数向下 |
+
+## 输出契约
+
+- `+resource-download` 成功时 stdout JSON 的 `data` 包含 `document_id`、`type`、`saved_path`、`size_bytes`、`content_type`、`cover.token`。如果文档没有封面图，命令失败退出，错误包含 `document has no cover` 和脱敏 `document_id`，不会创建输出文件。
+- `+resource-update` 成功时 stdout JSON 的 `data` 包含完整 `file_token` 和 `cover.token`；stderr 只打印脱敏 token。
+- `+resource-delete` 成功时 stdout JSON 的 `data.deleted` 表示本次是否真的发起删除，`data.already_empty` 表示删除前是否没有封面图。空封面图是幂等成功，不报错。
+
+## URL 来源安全边界
+
+`+resource-update --url` 只用于下载公开 HTTPS 图片：
+
+- 只允许 `https://`，拒绝 HTTP、空 host 和 URL userinfo。
+- 拒绝解析到 private、loopback、link-local、multicast、unspecified 地址的 host。
+- 最多跟随 3 次跳转，每次跳转都重新校验 URL。
+- 响应 `Content-Type` 只允许 `image/png`、`image/jpeg`、`image/gif`、`image/webp`。
+- 响应体最大 20MiB。
+
+## 参考
+
+- [lark-doc-media-download](lark-doc-media-download.md) — 下载正文素材或画板缩略图
+- [lark-doc-media-insert](lark-doc-media-insert.md) — 在正文插入图片/文件
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

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

@@ -0,0 +1,259 @@
+
+# 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、并行执行策略）
+>
+> **未读完以上文件就生成内容会导致格式错误。**
+
+通过八种指令精确更新飞书云文档。支持字符串级别和 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` 传空字符串可实现删除） |
+| `--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 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>'
+```
+
+### block_replace — 替换指定 block
+
+```bash
+lark-cli docs +update --doc "<doc_id>" --command block_replace \
+  --block-id "目标 block_id" \
+  --content '<p>替换后的段落内容</p>'
+```
+
+### 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>'
+```
+
+> ⚠️ 会清空文档后重写，可能丢失图片、评论等。仅在需要完全重建文档时使用。
+
+### append — 在文档末尾追加
+
+```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"
+```
+
+## 返回值
+
+```json
+{
+  "ok": true,
+  "identity": "user",
+  "data": {
+    "document": {
+      "revision_id": 13,
+      "new_blocks": [
+        { "block_id": "blkcnXXXX", "block_type": "whiteboard", "block_token": "boardXXXX" }
+      ]
+    },
+    "result": "success",
+    "updated_blocks_count": 3,
+    "warnings": []
+  }
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `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-style.md`](style/lark-doc-style.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)，但不要为了固定丰富度主动添加组件
+
+## 参考
+
+- [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略）
+- [`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) — 插入图片/文件到文档

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

@@ -0,0 +1,154 @@
+# lark-doc 画板处理指南
+
+> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+## 两个 Skill 的职责边界
+
+| Skill             | 核心职责                                                      | 约束                              |
+|-------------------|-----------------------------------------------------------|---------------------------------|
+| `lark-doc`        | 识别画板机会、使用 Mermaid/SVG 创建图表、调度 SubAgent、插入简单 SVG 画板或复杂空白画板 | 主 Agent 不直接创作画板内容；              |
+| `lark-whiteboard` | 查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板  | 仅特别复杂的图表或已有画板更新时由独立 SubAgent 读取 |
+
+## 画板适用规则
+
+写文档时，核心流程、系统架构、方案对比、风险链路、里程碑、指标趋势、因果归因、组织关系、能力分层等内容，如果图示能明显降低理解成本，可以规划为画板；结构简单或文字更清楚的内容不必强行画板化。
+
+同一篇文档可以有多个画板。确有多个独立图示点时，可拆成多个聚焦画板，而不是把所有信息塞进一张大图。
+
+## 文档与画板协同流程
+
+### 步骤 1：识别画板机会
+
+| 场景                      | 入口                                                        |
+|-------------------------|-----------------------------------------------------------|
+| 文档中需要思维导图、时序图、类图、饼图、甘特图 | 步骤 2A:使用 mermaid 插入图表                                     |
+| 文档中需要插入其他图表/自定义图形       | 步骤 2B: 使用 SVG 插入图表                                        |
+| 已有画板需要更新内容              | 先 `docs +fetch` 获取 `board_token`，跳至步骤 3B |
+| 只查看 / 下载已有画板            | 切换至 `lark-whiteboard`，不走本流程                               |
+
+> [!IMPORTANT]
+> ⚠️ **分别对每个图表进行决策**
+
+如果有多个位置需要插入图表，你需要根据每个图表的内容**分别决定**采用步骤 2A 还是 2B
+中的方式插入这个图表。在需要插入思维导图、时序图、类图、饼图、甘特图的时候可以插入 mermaid 块，在需要插入其他类型图表时启动
+SubAgent 插入 SVG。
+
+建议优先使用 SVG 插入图表，除非其属于思维导图、时序图、类图、饼图、甘特图这类可以直接使用 mermaid 语法描述，且不适宜用 SVG 绘制的图表
+
+### 步骤 2A: 使用 mermaid 插入图表
+
+```xml
+
+<whiteboard type="mermaid">
+    mermaid 代码...
+</whiteboard>
+```
+
+### 步骤 2B: SubAgent 使用 SVG 插入图表
+
+主 Agent 启动 SubAgent，让它用 `docs +create` / `docs +update` 插入：
+
+```xml
+
+<whiteboard type="svg">
+    <svg...>...
+    </svg>
+</whiteboard>
+```
+
+Sub Agent 需要携带以下的最小上下文，以及后续的 [SVG 设计 Workflow] 章节指南：
+
+- doc token、插入位置（标题 / block_id / command）
+- 图表目标、受众、源段落或数据
+- 要求读取 `lark-doc-xml.md`；不需要读取 `lark-whiteboard`
+- SVG 必须完整自包含：包含 `<svg>` 根节点和 `viewBox`，不引用外部图片、脚本、远程资源
+
+#### 画板 SVG 设计指南
+
+使用 SVG 插入画板时，最终交付是**画板跨越重排渲染的节点**(你写 SVG → 画板解析)
+**核心心智纠正 (重要)**：
+
+- 大多数 AI 如果只考虑“绝对不报错/完美映射”, 最终给出的都是全篇纯白底色加单层 `<rect>` 的方正卡片网格, 极其死板单调, *
+  *这将被视为不及格！**
+- **SVG 给你了完全的设计自由**, 请大胆使用你脑内的图标路径 (`<path>`), 连接指引 (`流畅的 <path>`), 各种环境氛围点缀,
+  大胆一点, 充分信任你的品味, 发挥出你的顶级艺术创造力！
+
+##### SVG 设计 Workflow
+
+###### 1. 想清楚要画什么
+
+- **核心信息是什么？** 能做到一图胜千言, 绝对不要只生成平平无奇的文字表格, 要有设计感
+- **内容充实度**：如果用户描述稀疏简略, 利用你的领域知识扩展, 保证信息维度和内容充实, 但不要过度堆砌, 淹没重点
+- **视觉层级与隐喻**：这个没有固定的形式, 你自由判断, 比如: 给重要的节点加光环, 加高亮背景；给对比项设计天平或对称结构
+
+###### 2. 写 SVG
+
+> [!IMPORTANT]
+> 布局, 配色, 信息密度, 装饰物——**全部由你判断**, 打破单调的 `<rect>` 牢笼, 严禁通篇用矩形和文字应付用户
+> 操作边界约束：
+
+- **语言跟随用户**：图表文字的语言与用户 prompt 保持一致, 技术术语用行业里通用的写法, 不机械翻译
+- 文字用 `<text>`(不是 `<path>`), 容器宽度留够——画板按 CJK ≈ 1em / Latin ≈ 0.6em 重排
+- 连线使用正交折线替代斜直线(`<polyline>` 带水平/垂直折点)视觉效果更好
+- 可自由使用 `translate`, `rotate`, `scale`但请尽量避免使用 `skewX` / `skewY` / `matrix(...)` 发生空间级扭曲
+
+###### 画板怎么处理 SVG
+
+画板的 svg-parser 把可识别元素转成可编辑节点, 其余降级为内嵌图片(渲染没问题, 虽然不可编辑, 但是可以正常显示)；但
+`<radialGradient>` / `<filter>` / `<clipPath>` 等装饰特性画板完全不支持，会导致渲染问题（见下方⚠️）
+**不需要所有元素都可编辑, 但必须避免使用不支持的装饰特性, 且要兼顾可编辑和美观漂亮**
+
+**可识别的元素**
+
+- 形状：`<rect>` / `<circle>` / `<ellipse>` / `<polygon>`
+- 连线：`<line>` / `<polyline>` / `<path>`(自动识别为直线 / 折线 / 曲线)
+- 文本：`<text>` / `<tspan>` 画板硬编码 Noto Sans SC **文字必须用 `<text>`**
+- 分组：`<g>` / `<a>` / `<use>` 引用 `<symbol>`
+- 变换：`translate` / `rotate` / `scale` 正常；`skewX` / `skewY` / `matrix(...)` 降级
+
+> [!IMPORTANT]
+> ⚠️ ** 不支持的装饰特性**
+
+- `<radialGradient>` / `<filter>` / `<pattern>` / `<clipPath>` / `<mask>` → 画板都不支持，**请避免使用，否则会导致画板渲染问题
+  **
+
+###### 3.插入后审查
+
+插入画板后，可以从返回值使用 lark-cli 指令，将画板内容导出为 png
+图片。若是对设计不满意，可以修改后，删除原来的画板再重新插入，或是调用 [
+`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md) 编辑。
+
+```bash
+lark-cli whiteboard +query \
+  --whiteboard-token "wbcnxxxxxxxx" \
+  --output_as image \
+  --output ./preview.png
+```
+
+### 步骤 3B：编辑已有画板 — 启动 lark-whiteboard SubAgent
+
+复杂图和已有画板更新必须启动 SubAgent。主 Agent 只传最小上下文，不直接执行 `lark-whiteboard` 的渲染和写入流程。
+
+复杂图 SubAgent 的最小上下文：
+
+- board_token
+- 图表目标、推荐画板类型、受众
+- 与图表直接相关的源段落或数据
+- 要求读取 [`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)，按其完整流程写入该 board_token
+
+多个画板互不依赖时，可并行启动多个 SubAgent；每个 SubAgent 只负责一个画板或一个 SVG 插入点，不要互相复用上下文。
+
+### 步骤 4：完成校验
+
+- Mermaid: 确认插入的是 `<whiteboard type="mermaid">`，且内容 mermaid 语法完整
+- SVG: 确认插入的是 `<whiteboard type="svg">`，且内容是完整 `<svg ...>...</svg>`
+- 不保留空白占位画板；复杂路径只有空白画板而无内容视为任务未完成
+
+---
+
+
+---
+
+## 关联参考
+
+- 画板查询/创作/修改/渲染写入：[`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)