lark-doc — Skillopedia

docs (v2) ⚠️ API 版本：本 skill 使用 v2 API。所有、、命令必须携带。前置条件 — 执行操作前必读 CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可： 1. — 认证、权限处理、全局参数（所有操作通用） 2. 读取文档（） → 必读（ / 选择、局部读取策略、 / 输出结构） 3. 创建或编辑文档内容 → 必读（XML 语法规则，仅当用户明确要求 Markdown 时改读）；从零创建时加读；编辑已有文档时加读未读完以上文件就执行相应操作会导致参数选择错误、格式错误或样式不达标。格式选择规则（全局）： - 创建 / 导入场景（，或的整段写入）：XML 和 Markdown 都可以。用户提供本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML（可用 callout、grid、checkbox 等富 block）。 - 精准编辑场景（的 / / / / 等局部精修指令）：优先使用 XML（，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。快速决策 - 用户需要“某个 block 的直达链接 / 锚点链接”时：返回。如果当前只有文档 URL 没有 block id，先用…

# 项目计划\\n\\n## 目标\\n\\n- 目标 1\\n- 目标 2'\n```\n\n## 返回值\n\n```json\n{\n \"ok\": true,\n \"identity\": \"user\",\n \"data\": {\n \"document\": {\n \"document_id\": \"doxcnXXXXXXXXXXXXXXXXXXX\",\n \"revision_id\": 1,\n \"url\": \"https://xxx.feishu.cn/docx/doxcnXXXXXXXXXXXXXXXXXXX\",\n \"new_blocks\": [\n { \"block_id\": \"blkcnXXXX\", \"block_type\": \"whiteboard\", \"block_token\": \"boardXXXX\" }\n ]\n }\n }\n}\n```\n\n- **`document.new_blocks`**：本次操作新增的 block 列表（如画板）。`block_id` 可用于 `docs +update` 的 `--block-id` 做精确编辑；`block_token` 是资源块（如画板）的 token，可交给 `lark-whiteboard` 等 skill 继续操作\n\n> \\[!IMPORTANT]\n> 如果文档是**以应用身份（bot）创建**的，如 `lark-cli docs +create --as bot` 在文档创建成功后，CLI 会**尝试为当前 CLI 用户自动授予该文档的 `full_access`（可管理权限）**。\n>\n> 以应用身份创建时，结果里会额外返回 `permission_grant` 字段，明确说明授权结果：\n> - `status = granted`：当前 CLI 用户已获得该文档的可管理权限\n> - `status = skipped`：本地没有可用的当前用户 `open_id`，因此不会自动授权；可提示用户先完成 `lark-cli auth login`，再让 AI / agent 继续使用应用身份（bot）授予当前用户权限\n> - `status = failed`：文档已创建成功，但自动授权用户失败；会带上失败原因，并提示稍后重试或继续使用 bot 身份处理该文档\n>\n> `permission_grant.perm = full_access` 表示该资源已授予”可管理权限”。\n>\n> **不要擅自执行 owner 转移。** 如果用户需要把 owner 转给自己，必须单独确认。\n\n## 参数\n\n| 参数 | 必填 | 说明 |\n| ------------------- | -- |---------------------------------------------|\n| `--api-version` | 是 | 固定传 `v2` |\n| `--content` | 是 | 文档内容（XML 或 Markdown 格式） |\n| `--doc-format` | 否 | 内容格式：`xml`（默认，始终优先使用）\\| `markdown`（仅用户明确要求时） |\n| `--parent-token` | 否 | 父文件夹或知识库节点 token（与 `--parent-position` 互斥） |\n| `--parent-position` | 否 | 父节点位置，如 `my_library`（与 `--parent-token` 互斥） |\n\n## 最佳实践\n\n- 文档标题从内容中自动提取（XML `\u003ctitle>` 或 Markdown `#`），不要在内容开头重复写标题\n- **创建较长的文档时只建骨架**：`--content` 仅传标题 + 各级 heading + 简短占位摘要；正文留给后续 `docs +update --command append` 或 `block_insert_after` 分段追加。一次性塞超长 `--content` 既容易触发参数限制，调试也更难。\n- **视觉丰富度**：必须遵循 [`lark-doc-style.md`](style/lark-doc-style.md) 中的样式指南，主动使用结构化 block 丰富文档\n\n## 参考\n\n- [`lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md) — 从零创作工作流（Code-Act Loop、并行执行策略）\n- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档样式指南（元素选择 + 丰富度规则 + 颜色语义）\n- [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范\n- [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档\n- [`lark-doc-update.md`](lark-doc-update.md) — 更新文档\n- [`lark-doc-media-insert.md`](lark-doc-media-insert.md) — 插入图片/文件到文档\n- [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) — 认证和全局参数\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":5460,"content_sha256":"eda35f0b1d9dedf59cabbaed2b20d09b2ddc3cf4275fa1053e8e8d7e1463a11c"},{"filename":"references/lark-doc-fetch.md","content":"\n# docs +fetch（获取飞书云文档）\n\n> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。\n\n## 命令\n\n```bash\n# 获取文档（默认 XML，simple）\nlark-cli docs +fetch --api-version v2 --doc \"https://xxx.feishu.cn/docx/Z1Fj...tnAc\"\n\n# Markdown 格式\nlark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc --doc-format markdown\n\n# 带 block ID（用于后续 block 级更新）\nlark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc --detail with-ids\n\n# 只拿目录\nlark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc --scope outline --max-depth 3\n\n# 按 block id 区间精读\nlark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \\\n --scope range --start-block-id blkA --end-block-id blkB --detail with-ids\n\n# 读整个章节（以标题 id 为锚点，自动展开到下一个同级/更高级标题前）\nlark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \\\n --scope section --start-block-id \u003c标题id> --detail with-ids\n\n# 按关键词定位（多关键词用 | 分隔，任一命中即返回）\nlark-cli docs +fetch --api-version v2 --doc Z1Fj...tnAc \\\n --scope keyword --keyword \"部署|发布|上线\"\n```\n\n## 选 `--detail`（每块详细度）\n\n| 意图 | `--detail` | 说明 |\n|------|-----------|------|\n| **只读**：浏览或总结文档内容 | `simple`（默认） | 简洁 XML/Markdown，不含 block ID、样式属性、引用元数据 |\n| **定位**：需要 block ID 与其他业务交互 | `with-ids` | 包含 block ID（如 `\u003cp id=\"blkcnXXXX\">`），可用于 `+update` 的 `--block-id`，也可用于拼接 `文档URL#block_id` 形式的直达链接 |\n| **编辑**：任何修改文档内容的需求 | `full` | 包含 block ID + 样式属性 + 引用元数据，提供完整文档结构信息 |\n\n## 选 `--scope`（读取范围）\n\n`--scope` 和 `--detail` 正交可组合。**省略 `--scope` 即读整篇；获取一小节时优先用局部读取。**\n\n| 模式 | 何时用 | 关键参数 | 行为要点 |\n|-|-|-|-|\n| `outline` | 不知道结构，先看目录 | `--max-depth`（标题层级上限） | 扁平列出所有标题，**包括嵌在容器里的内嵌标题**（如 callout 里的 h3）；这些 id 可直接作后续 `section` / `range` 端点 |\n| `section` | 读某个标题对应的整节 | `--start-block-id`（必填） | 顶层标题 → 展开到下一同级/更高级标题前；容器内节点（含内嵌标题） → 按\"最小包容单元\"返回容器/表格切片，不做 heading 扩展；顶层非标题块 → 仅该块 |\n| `range` | 已知精确起止 | `--start-block-id` / `--end-block-id` 至少一个；`-1` = 读到末尾 | 两端同顶层 → 顶层序列切片；两端同一容器 → 容器整体；两端同一表格 → 瘦身切片；**跨顶层 → 端点所在顶层块整块输出，不做瘦身** |\n| `keyword` | 只有模糊关键词 | `--keyword`（**多级自动 fallback**：子串 → 归一化 → 分词形变 → RE2 正则；`\\|` 分隔多分支 OR） | 每处命中按\"最小包容单元\"输出；**自动去重**（同容器多命中 → 单个容器，同表格多行命中 → 合并切片） |\n\n> 💡 **多关键词用 `\\|` 拼接（OR 语义，任一命中即返回）**：例 `\"部署\\|发布\\|上线\"`，三词任一命中都进结果，适合**同义词/别名/多业务术语**一次召回（如 `bug\\|缺陷\\|故障`）。\n\n**设置 `--scope` 时共用** `--context-before` / `--context-after` / `--max-depth`。\n\n- `--max-depth`：`outline` = 标题层级上限（3 = h1~h3）；其它模式 = 被选块的子树遍历深度（`-1` 不限，`0` 仅块自身）。\n- `--context-before/--context-after`：**只对整块顶层单元生效**；命中落在容器/表格内（返回容器或切片）时 before/after 被忽略，需要更大范围改用 `section` / `range` 显式指定。\n\n**决策顺序**（核心原则：**局部获取优于全量获取**，根据需求形态选起点，必要时多步组合收敛范围）：\n1. 需求**直接给出待查的具体术语/错误码/标识** → 直接走 `keyword` 粗匹配（多级 fallback 自动覆盖形变），需要更大上下文时用返回的 `top-block-id` 走 `section` / `range`\n2. 需求**指向某个章节/标题**（\"修改 XX 章\"、\"总结第 3 节\"、\"关于 xx 的内容\"）→ 先 `outline --max-depth 3` 拿目录 → `section --start-block-id \u003c标题id>` 精读\n3. 已知**精确起止 / 跨节连续区间** → `range`\n4. **结构未知且无明确关键词/章节线索** → `outline` 探测，再回到 2/3\n5. **兜底**：仅在确需整篇时才省略 `--scope`；不要为省事直接读整篇\n\n## 局部读取的输出结构：`\u003cfragment>` 与 `\u003cexcerpt>`\n\n设置 `--scope` 时返回的 `content` 被一个 `\u003cfragment>` 节点包裹，属性包含 `mode` / `requested-start` / `requested-end` / `keyword`（按需）。子节点只有两种形态：\n\n- **顶层块**：完整块直接作为 `\u003cfragment>` 的子节点，无额外包裹。\n- **`\u003cexcerpt top-block-id=\"...\" parent-block-path=\"...\">`**：非顶层节选（容器整体 / 表格瘦身切片）。\n - `top-block-id`：所在顶层块 id，想看该块全貌时作 `section` / `range` 锚点再拉一次。\n - `parent-block-path`：从顶层块到 excerpt 内容直接父节点的 id 路径，`/` 分隔（表格切片时即表格自身 id）。\n\n**看到 `\u003cexcerpt>` 即意味着这是节选**，不能假设看到了该顶层块的全貌。\n\n**表格默认瘦身**：即便 `\u003ctable>` 本身是顶层块也只返回 thead + 命中 tr。想拿整张表 → `range --start-block-id \u003ctable-id> --end-block-id \u003ctable-id>`；切片范围恰好覆盖全部 tr 时 SDK 自动升级为整块、不包 `\u003cexcerpt>`。\n\n## 返回值\n\n```json\n{\n \"ok\": true,\n \"identity\": \"user\",\n \"data\": {\n \"document\": {\n \"document_id\": \"doxcnXXXX\",\n \"revision_id\": 12,\n \"content\": \"\u003ctitle>标题\u003c/title>\u003cp>文档内容...\u003c/p>\"\n }\n }\n}\n```\n\n`content` 的格式由 `--doc-format` 决定。设置 `--scope` 时会被 `\u003cfragment>` 包裹，详见上文\"局部读取的输出结构\"。\n\n## 参数\n\n| 参数 | 必填 | 说明 |\n|------|------|------|\n| `--api-version` | 是 | 固定传 `v2` |\n| `--doc` | 是 | 文档 URL 或 token（支持 `/docx/` 和 `/wiki/`） |\n| `--doc-format` | 否 | `xml`（默认）\\| `markdown` \\| `text` |\n| `--detail` | 否 | `simple`（默认）\\| `with-ids` \\| `full` |\n| `--revision-id` | 否 | 文档版本号，`-1` = 最新（默认） |\n| `--scope` | 否 | `outline` \\| `range` \\| `keyword` \\| `section`（省略 = 读整篇） |\n| `--start-block-id` | 否 | `range`/`section` 起始/锚点 id（`section` 必填） |\n| `--end-block-id` | 否 | `range` 结束 id；`-1` 表示读到末尾 |\n| `--keyword` | 否 | `keyword` 模式关键词，**4 层自动 fallback**（子串 → 归一化 → 分词形变 → RE2 正则）；`\\|` 分隔多分支 OR |\n| `--context-before` | 否 | 命中前拉几个兄弟块（仅对顶层单元生效，默认 `0`） |\n| `--context-after` | 否 | 命中后拉几个兄弟块（仅对顶层单元生效，默认 `0`） |\n| `--max-depth` | 否 | `outline` = 标题层级上限；其它 = 子树深度（`-1` 不限，默认） |\n| `--format` | 否 | `json`（默认）\\| `pretty` |\n\n## 图片、文件、画板的处理\n\n**文档中的素材以 XML 标签形式出现：**\n\n```xml\n\u003cimg token=\"...\" url=\"https://...\" width=\"...\" height=\"...\"/>\n\u003csource token=\"...\" url=\"https://...\" name=\"skills.zip\"/>\n\u003cwhiteboard token=\"...\"/>\n```\n\n- `\u003cimg>` / `\u003csource>` 带 `url` 时，直接用该 URL 下载即可（普通 HTTP GET），无需走 shortcut。\n- 没有 `url`、或只想预览 → `docs +media-preview --token \u003ctoken> --output ./preview_media`\n- 明确下载，或目标是 `\u003cwhiteboard>`（画板只能走 shortcut） → `docs +media-download --token \u003ctoken> --output ./downloaded_media`\n\n## 嵌入电子表格 / 多维表格\n\n返回中可能含 `\u003csheet>`、`\u003cbitable>`、`\u003ccite file-type=\"sheets|bitable\">`。内部数据无法通过 `docs +fetch --api-version v2` 获取，提取 `token` 等属性后切到 [`lark-sheets`](../../lark-sheets/SKILL.md) / [`lark-base`](../../lark-base/SKILL.md) 下钻，详见 [SKILL.md 快速决策](../SKILL.md) 路由表。\n\n## 参考\n\n- [lark-doc-create](lark-doc-create.md) — 创建文档\n- [lark-doc-update](lark-doc-update.md) — 更新文档\n- [lark-doc-media-preview](lark-doc-media-preview.md) — 预览素材\n- [lark-doc-media-download](lark-doc-media-download.md) — 下载素材/画板缩略图\n- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":8629,"content_sha256":"c0f932226103f37fa1270c5a50c81577ddcb49db5b80b8b124ec63d58e29d728"},{"filename":"references/lark-doc-md.md","content":"# Markdown 格式参考\n\n`docs +fetch --api-version v2` / `docs +create --api-version v2` / `docs +update --api-version v2` 使用 `--doc-format markdown` 时适用。\n\n## 转义规则\n\n> **⚠️ 当文本中包含以下字符且不想触发 Markdown 语法时**，需用 `\\` 前缀转义。转义分为**无条件转义**（行内任意位置生效）和**位置敏感转义**（仅特定位置才需要）两类。\n\n### 无条件转义（行内生效，任何位置都要转义）\n\n| 符号 | Markdown 语法用途 | 转义写法 | 示例 |\n|------|-------------------|----------|------|\n| `\\` | 转义符本身 | `\\\\` | `C:\\\\Users` → C:\\Users |\n| `` ` `` | 行内代码 | `` \\` `` | `` 用 \\` 包裹 `` |\n| `*` | 斜体 / 加粗 | `\\*` | `3 \\* 5 = 15` → 3 \\* 5 = 15 |\n| `_` | 斜体 / 加粗 | `\\_` | `foo\\_bar\\_baz` → foo\\_bar\\_baz |\n| `[` `]` | 链接文本 | `\\[` `\\]` | `\\[非链接\\]` |\n| ` lark-doc — Skillopedia | 数学公式定界 | `\\ lark-doc — Skillopedia | `价格 \\$100` |\n| `~` | 删除线（GFM `~~text~~`） | `\\~` | `a\\~\\~b\\~\\~c` → a~~b~~c |\n| `\u003c` | XML 标签起始（`\u003cb>`、`\u003cimg>` 等会被当作标签解析并生效） | `\\\u003c` | 字面量 `\u003cb>` 须写为 `\\\u003cb>`；`a \u003c b` 建议写为 `a \\\u003c b` |\n\n### 位置敏感转义（仅在特定位置才需要转义）\n\n| 符号 | Markdown 语法用途 | 转义条件 | 示例 |\n|------|-------------------|----------|------|\n| `#` | 标题 | **仅行首**（去除前导空白后）| 行首 `\\# 这不是标题`；行内 `A # B` 无需转义 |\n| `+` | 无序列表 | **仅行首**（去除前导空白后）| 行首 `\\+ item`；行内 `1 + 2` 无需转义 |\n| `-` | 无序列表 / 分隔线 | **仅行首**（去除前导空白后）| 行首 `\\- item`；行内 `A - B` 无需转义 |\n| `>` | 引用块 | **仅行首**（去除前导空白后）| 行首 `\\> 不是引用`；行内 `a > b` 无需转义 |\n| `\\|` | 表格 cell 分隔 | **仅在 GFM 表格 cell 内** | cell 内 `A \\| B`；行内普通文本 `a \\| b` 无需转义 |\n\n**不需要转义的场景：**\n- 在 `` ` `` 行内代码或 ` ``` ` 代码块内，所有符号均为字面量，无需转义\n- `$... lark-doc — Skillopedia 数学公式内部，符号为 LaTeX 语法，不受 Markdown 转义影响\n\n**导出已转义，不要反转义：**\n`docs +fetch --api-version v2 --doc-format markdown` 导出的内容中，特殊字符**已经被转义过了**（例如 `\\[`、`\\|`、`\\\\` 等）。这些 `\\` 是有意义的——去掉会导致后续写入时字符被 Markdown 语法吞掉。**不要反转义或去掉 `\\`。**\n\n**写入时必须转义：**\n使用 `docs +create` 或 `docs +update` 的 `--doc-format markdown` 写入内容时，字面文本中的特殊字符同样必须转义。`--pattern` 参数中也必须使用转义形式才能正确匹配。\n\n**导出 → 更新工作流示例：**\n\n1. `docs +fetch --api-version v2` 导出得到 `C:\\\\Users\\\\test\\[1\\]`\n2. 用 `str_replace --pattern 'C:\\\\Users\\\\test\\[1\\]'` 匹配（直接使用导出的转义形式）\n3. `--content` 中的替换内容也要保持转义：`C:\\\\Users\\\\prod\\[2\\]`\n\n自行构造 Markdown 内容写入时同理：如字面文本 `a]b` 应写为 `a\\]b`，`C:\\Users` 应写为 `C:\\\\Users`。\n\n## Shell 传参\n- **首选文件传参**：`--content` 支持 `@path/to/file.md`（读文件）和 `-`（读 stdin），彻底绕开 shell 转义；多行、含特殊字符、长文本强烈推荐。字面量以 `@` 开头时用 `@@` 转义（`--pattern` 不支持 `@file`）\n- **默认用单引号 `'...'`**：完全字面量，` lark-doc — Skillopedia 、`` ` ``、`\\`、`>`、`\\\u003cb>` 等全部原样保留\n- **双引号 `\"...\"`**：会展开 `$变量`、反引号和 `$(...)` 命令替换，`\\` 仍参与转义，易踩坑\n- **`

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

...'` ANSI-C 引号**：按 C 转义解析，`\\n`=换行、`\\\\`=单个 `\\`；**zsh 下未知转义（如 `\\\u003c`）的 `\\` 会被吞**，要保留字面 `\\` 必须写 `\\\\`。只在确实需要 `\\n`/`\\t` 时用\n- **多行内容**：用 `\u003c\u003c'EOF'` heredoc，EOF 必须带引号，否则仍展开 ` lark-doc — Skillopedia \n- **`\\n` 在 `'...'` 和 `\"...\"` 里都是字面量**，不是换行；要真换行用 `

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

...\\n...'` 或 heredoc\n\n## 图片语法\n\nMarkdown 格式支持通过 URL 插入网络图片，图片将自动从 HTTP 下载：\n```markdown\n![alt text](https://example.com/photo.png)\n```\n- `alt text` 为图片描述（可选，可留空）\n- URL 支持 `http://` 和 `https://` 协议\n- 对应的 XML 格式为：`\u003cimg href=\"https://example.com/photo.png\"/>`\n\n## Markdown 不支持的 Block 类型\n\n非原生 Markdown 语法的内容（如下划线、高亮框(Callout)、勾选框、多维表格、画板、思维导图、电子表格、网格布局、引用(@文档/@人)、按钮、日期提醒、行内文件、文字颜色/背景色、同步块等）采用 XML 语法表示，详见 [`lark-doc-xml.md`](lark-doc-xml.md)。\n> **⚠️ XML 标签会被解析并生效**：即使在 `--doc-format markdown` 下，`\u003cb>`、`\u003cu>`、`\u003cimg>` 等 XML 标签也会被识别为对应的富文本节点，**不会**按字面量显示。如需字面量输出尖括号包裹的文本（例如示例中的 `\u003ctag>`），必须转义左尖括号：`\\\u003cb>`、`\\\u003cimg>`。\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":5104,"content_sha256":"7b0e0e132d93f2974264c359d066f3a21f957cafe9a13b0637bca69e8e7486b9"},{"filename":"references/lark-doc-media-download.md","content":"\n# docs +media-download（下载文档素材/画板缩略图）\n\n> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。\n\n下载文档中的图片/文件素材（`file_token`），或下载画板缩略图（`whiteboard_id`）。当 `--output` 不带扩展名时，会根据响应的 `Content-Type` 自动补全扩展名。\n\n## 选择规则\n\n- 用户明确说“下载素材”时，使用 `docs +media-download`\n- 用户只是想查看、预览图片或文件素材时，优先使用 [`docs +media-preview`](lark-doc-media-preview.md)\n- 如果目标明确是画板 / whiteboard / 画板缩略图，继续使用 `docs +media-download --type whiteboard`；`+media-preview` 不支持画板\n\n## 命令\n\n```bash\n# 下载图片/文件素材（默认 type=media）\nlark-cli docs +media-download --token \"Z1Fjxxxxxxxx\" --output ./asset\n\n# 指定输出文件名（带扩展名则不会自动补全）\nlark-cli docs +media-download --token \"Z1Fjxxxxxxxx\" --output ./asset.png\n\n# 下载画板缩略图（whiteboard token）\nlark-cli docs +media-download --type whiteboard --token \"wbcnxxxxxxxx\" --output ./whiteboard\n```\n\n## 参数\n\n| 参数 | 必填 | 说明 |\n|------|------|------|\n| `--token \u003ctoken>` | 是 | 资源 token：素材为 `file_token`，画板为 `whiteboard_id` |\n| `--output \u003cpath>` | 是 | 本地保存路径；不带扩展名会自动补全 |\n| `--type \u003ctype>` | 否 | `media`（默认）或 `whiteboard` |\n\n## token 从哪里来\n\n- 若你是从文档内容里提取：`lark-doc-fetch` 返回的 Markdown 里可能包含：\n - 图片：`\u003cimage token=\"...\" .../>`\n - 文件：`\u003cfile token=\"...\" name=\"...\"/>`\n - 画板：`\u003cwhiteboard token=\"...\"/>`\n\n## 排障\n\n- 如果报错返回的信息包含 `HTTP 403`，且目标是图片/文件素材，可以改成调用 [`docs +media-preview`](lark-doc-media-preview.md) 看是否能先预览内容\n\n## 参考\n\n- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（用于提取 token）\n- [lark-doc-media-preview](lark-doc-media-preview.md) — 预览素材\n- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2169,"content_sha256":"d4c7f67d07b907106a037500e5809405ce74ee4b642767af3e417c5edd527277"},{"filename":"references/lark-doc-media-insert.md","content":"\n# docs +media-insert（文档末尾插入图片/文件）\n\n> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。\n\n把\"创建空 block → 上传文件 → 设置 token\"三步合并成一个命令，在**文档末尾**插入本地图片或文件。\n\n## 来源选择（Agent 必读）\n\n> **最高优先级：用户明确指定了来源，就严格按用户的来。** 下面的启发式只在用户没表态时生效。\n>\n> - 用户说\"把这张截图插进去\"、\"用剪切板里的图\"、\"我刚复制的\" → 无条件走 `--from-clipboard`。\n> - 用户说\"用 `~/Downloads/foo.png`\"、\"插本地这个文件\"、给了具体路径 → 无条件走 `--file`。\n> - 用户两者都没说清 → 按下表的启发式推断。\n>\n> 即使推断看起来更\"优\"（比如用户说了路径但你觉得走剪切板更省事），也**不要自作主张**换来源。要换，先问。\n\n按下列顺序判断，**不要反向做**：\n\n| 用户的图片来源 | 命令 | 禁止做法 |\n|----------------|------|----------|\n| 图片已经在剪切板里（截图快捷键、从飞书/浏览器复制、从设计稿复制） | `--from-clipboard` | ❌ 不要先把剪切板存到本地文件再用 `--file`。多一步文件 I/O，还得清理临时文件。 |\n| 图片是磁盘上的真实文件 | `--file \u003cpath>` | — |\n| 图片是 URL | 先下载到本地 → `--file`；或用 `drive` 相关命令 | — |\n\n`--from-clipboard` 走进程内存直传，不产生临时文件；macOS / Windows 内置支持，Linux 需要 `xclip` 或 `wl-paste` 或 `xsel` 任一。\n\n### 剪切板为空时的 fallback\n\n`--from-clipboard` 失败（剪切板里不是图片 / 没有图片 / Linux 上三个工具都没装）时，命令会返回 `clipboard contains no image data`（或类似的平台错误）。**这不是错误退出理由，而是 fallback 信号。**\n\n**Agent 的标准处置顺序**（每一步失败再进下一步，不要并行）：\n\n1. 先用 `--from-clipboard` 试一次。\n2. 如果返回\"no image data\"类错误，**向用户明确说明剪切板里没有可识别的图片**，请用户提供本地文件路径或重新复制一张图。\n3. 拿到本地路径后，用 `--file \u003cpath>` 重试**同一条插入命令**（其他参数如 `--doc` / `--align` / `--caption` 保持不变）。\n\n**禁止做法**：\n- ❌ 不要悄悄把空剪切板当\"成功但没插入\"处理。必须提示用户。\n- ❌ 不要在剪切板失败后自行瞎猜某个本地文件路径（比如最近修改的 png）。必须让用户给路径。\n- ❌ 不要用\"先让用户保存剪切板到磁盘再 `--file`\"的建议绕过 `--from-clipboard`，当且仅当剪切板确实没图片时才退回本地路径。\n\n## 命令\n\n```bash\n# 🟢 推荐：从剪切板直接插入（无需先存盘）\nlark-cli docs +media-insert --doc doxcnXXX --from-clipboard\n\n# 从本地文件插入\n# 除了上传本地文件，还可以在 `docs +update` 时直接通过网络 URL 插入图片，无需先下载到本地：\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command block_insert_after \\\n --block-id \"目标 block_id\" \\\n --content '\u003cimg href=\"https://example.com/photo.png\"/>'\n\n# 插入图片（默认）\nlark-cli docs +media-insert --doc doxcnXXX --file ./image.png\n\n# doc 支持直接传 docx URL（自动提取 document_id）\nlark-cli docs +media-insert --doc \"https://xxx.feishu.cn/docx/doxcnXXX\" --from-clipboard\n\n# 如果上一步是 create-doc，优先传返回值里的 doc_id\n# 不要把 /wiki/... 形式的 doc_url 直接传给 docs +media-insert\nlark-cli docs +media-insert --doc doxcnReturnedByCreateDoc --file ./image.png\n\n# 插入文件（非图片）\nlark-cli docs +media-insert --doc doxcnXXX --file ./spec.pdf --type file\n\n# 图片对齐与描述（caption）\nlark-cli docs +media-insert --doc doxcnXXX --from-clipboard --align center --caption \"架构图\"\n\n# Insert image with explicit display width (height auto-computed from aspect ratio)\nlark-cli docs +media-insert --doc doxcnXXX --file ./banner.png --width 800 --align center\n\n# Insert image with explicit width and height\nlark-cli docs +media-insert --doc doxcnXXX --from-clipboard --width 800 --height 447 --caption \"architecture diagram\"\n```\n\n## 参数\n\n| 参数 | 必填 | 说明 |\n|------|------|------|\n| `--doc \u003cid>` | 是 | 文档 ID 或 docx URL（仅支持 `/docx/\u003cdocument_id>` 形式自动提取；**不支持 `/wiki/...` URL 自动提取**） |\n| `--from-clipboard` | 二选一 | 从系统剪切板读取图片（与 `--file` 互斥）。macOS/Windows 内置支持，Linux 需要 `xclip` / `wl-paste` / `xsel` 之一。 |\n| `--file \u003cpath>` | 二选一 | 本地文件路径（文件大于 20MB 时自动切换分片上传） |\n| `--type \u003ctype>` | 否 | `image`（默认）或 `file`。`--from-clipboard` 目前只产出 image。 |\n| `--align \u003calign>` | 否 | 仅图片：`left` / `center`（默认）/ `right` |\n| `--caption \u003ctext>` | 否 | 仅图片：图片描述 |\n| `--width \u003cpx>` | 否 | 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`. |\n| `--height \u003cpx>` | 否 | 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`. |\n\n> [!IMPORTANT]\n> 如果上一步是 [`lark-doc-create`](lark-doc-create.md)，并且它在知识库/知识空间场景下返回的是 `/wiki/...` 形式的 `doc_url`，后续调用 `docs +media-insert` 时应优先传 `doc_id`，不要直接传这个 `doc_url`。\n\n## 平台注意（仅 `--from-clipboard`）\n\n| 平台 | 依赖 | 典型错误 |\n|------|------|---------|\n| macOS | osascript（内置） | 剪切板为空 / 不是图片 → \"clipboard contains no image data\" |\n| Windows | PowerShell + System.Windows.Forms（内置） | 同上 |\n| Linux | `xclip` 或 `wl-paste` 或 `xsel` 任一 | 都没安装 → 报错会提示用发行版包管理器安装 |\n\n命令不支持读取 TIFF 等非 PNG/JPEG/GIF/WebP/BMP 的冷门格式；遇到这类剪切板会返回 \"contains no image data\"，此时才考虑先用系统工具转成文件再 `--file`。\n\n## 输出\n\n命令成功后会输出 JSON，包含：`document_id`、`block_id`、`file_token`、`file_name`（剪切板路径下为 `clipboard.png`）、`type`。\n\n> [!CAUTION]\n> 这是**写入操作**（会修改文档内容）—— 执行前必须确认用户意图。\n\n## 参考\n\n- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（可用于确认插入后的结果、以及提取媒体 token）\n- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":6944,"content_sha256":"1c1e4f799ba056e51a7cb84188da3d3c4b22d687403b43d4bb8971551b455dfd"},{"filename":"references/lark-doc-media-preview.md","content":"\n# docs +media-preview（预览文档素材）\n\n> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。\n\n优先用于查看、预览文档中的图片或文件素材（`file_token`）。命令会把素材保存到本地路径，便于后续打开查看内容。\n\n## 选择规则\n\n- 用户说“看一下素材 / 图片 / 附件”“预览一下”时，优先使用 `docs +media-preview`\n- 用户明确说“下载”时，使用 [`docs +media-download`](lark-doc-media-download.md)\n- 如果目标明确是画板 / whiteboard / 画板缩略图，不要使用 `+media-preview`，改用 `docs +media-download --type whiteboard`\n\n## 命令\n\n```bash\n# 预览图片/文件素材\nlark-cli docs +media-preview --token \"Z1Fjxxxxxxxx\" --output ./asset\n\n# 指定输出文件名（带扩展名则不会自动补全）\nlark-cli docs +media-preview --token \"Z1Fjxxxxxxxx\" --output ./asset.png\n```\n\n## 参数\n\n| 参数 | 必填 | 说明 |\n|------|------|------|\n| `--token \u003ctoken>` | 是 | 素材 token，即 `file_token` |\n| `--output \u003cpath>` | 是 | 本地保存路径；不带扩展名会自动补全 |\n\n## token 从哪里来\n\n- 若你是从文档内容里提取：`lark-doc-fetch` 返回的 Markdown 里可能包含：\n - 图片：`\u003cimage token=\"...\" .../>`\n - 文件：`\u003cfile token=\"...\" name=\"...\"/>`\n\n## 参考\n\n- [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（用于提取 token）\n- [lark-doc-media-download](lark-doc-media-download.md) — 明确下载素材，或下载画板缩略图\n- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":1647,"content_sha256":"ebecf432d6ad0dbfa249cbf3dab91e7e20e25ee29e1c4874a039aa2bb8194200"},{"filename":"references/lark-doc-update.md","content":"\n# docs +update（更新飞书云文档）\n\n> **前置条件（MUST READ）：** 生成文档内容前，必须先用 Read 工具读取以下文件，缺一不可：\n> 1. [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) — 认证、全局参数和安全规则\n> 2. [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规则（使用 Markdown 格式时改读 [`lark-doc-md.md`](lark-doc-md.md)）\n> 3. [`lark-doc-style.md`](style/lark-doc-style.md) — 排版指南（元素选择、丰富度规则、颜色语义）\n> 4. [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略）\n>\n> **未读完以上文件就生成内容会导致格式错误或样式不达标。**\n\n通过八种指令精确更新飞书云文档。支持字符串级别和 block 级别的操作。\n\n> **⚠️ 格式选择规则：**\n> - **局部精修**（`str_replace` / `block_insert_after` / `block_replace` / `block_delete` / `block_move_after`）：优先使用 XML（默认）。XML 能稳定表达 block 结构和样式，精准编辑更可控；不要因为 Markdown 写起来更简单就自行切换。\n> - **整段写入**（`append` / `overwrite`）：XML 和 Markdown 都可以。用户提供 `.md` 本地文件或明确要求 Markdown 时直接用 Markdown；否则默认 XML。\n>\n> **Markdown 局限 & block ID 前提：** Markdown 不携带 block ID，也无样式（颜色、对齐、callout 等）。需要按 block ID 定位（`block_*` 指令的 `--block-id`）时，先 `docs +fetch --api-version v2 --detail with-ids` **配合 `--scope`（`outline` / `range` / `keyword` / `section`）局部获取**目标段落，不要全量 fetch。拿到 block ID 后 `--content` 仍可用 Markdown，只是写入内容不带样式。\n\n## 参数\n\n| 参数 | 必填 | 说明 |\n|------|------|------|\n| `--api-version` | 是 | 固定传 `v2` |\n| `--doc` | 是 | 文档 URL 或 token |\n| `--command` | 是 | 操作指令（见下方指令速查表） |\n| `--doc-format` | 否 | 内容格式：`xml`（默认，始终优先使用）\\| `markdown`（仅用户明确要求时） |\n| `--content` | 视指令 | 写入内容（`str_replace` 传空字符串可实现删除） |\n| `--pattern` | 视指令 | 匹配文本（str_replace） |\n| `--block-id` | 视指令 | 目标 block ID（block_* 操作）,-1 表示末尾 |\n| `--src-block-ids` | 视指令 | 源 block ID（逗号分隔），用于 block_copy_insert_after / block_move_after |\n| `--revision-id` | 否 | 基准版本号，-1 = 最新（默认 `-1`） |\n\n## 指令速查表\n\n| 指令 | 说明 | 必需参数 |\n|------|------|----------|\n| `str_replace` | 全文文本查找替换（replacement 支持富文本标签；`--content` 传空字符串即为删除） | `--pattern` `--content` |\n| `block_insert_after` | 在指定 block 之后插入新内容 | `--block-id` `--content` |\n| `block_copy_insert_after` | 复制源 block 并插入到锚点之后（源块不变） | `--block-id` `--src-block-ids` |\n| `block_replace` | 替换指定 block（同一 block 仅限一次） | `--block-id` `--content` |\n| `block_delete` | 删除指定 block（逗号分隔可批量） | `--block-id` |\n| `overwrite` | ⚠️ 清空文档后全文重写（可能丢失图片、评论） | `--content` |\n| `append` | 在文档末尾追加内容（等价于 `block_insert_after --block-id -1`） | `--content` |\n| `block_move_after` | 移动已有 block 到指定位置 | `--block-id` + (`--content` 或 `--src-block-ids`) |\n\n## 指令示例\n\n### str_replace — 全文文本替换\n\n> **匹配范围：**\n> - **XML 模式（默认）**：`--pattern` 只支持**行内匹配**，不能跨 block / 跨段落匹配。涉及整段或多 block 的改动，请改用 `block_replace`。\n> - **Markdown 模式**（`--doc-format markdown`）：`--pattern` 同时支持**行内和跨行匹配**，可以用多行字符串匹配并替换一整段内容。\n> - 还支持**`前缀...后缀` 省略号语法**：用 `...`（三个英文句点）串联起始与结束片段，匹配从前缀到后缀之间的全部内容（含中间被省略部分）。适合一段很长、但首尾特征明显的文本，避免把整段都塞进 `--pattern`。\n> - 前缀、后缀本身仍遵循 Markdown 转义规则；省略号中间的内容**会被替换**为 `--content` 的完整文本，不会被保留。\n\n```bash\n# 简单文本替换\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command str_replace \\\n --pattern \"张三\" --content \"李四\"\n\n# 替换为富文本（加粗 + 链接）\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command str_replace \\\n --pattern \"旧链接\" --content '\u003cb>新链接\u003c/b> \u003ca href=\"https://example.com\">点击查看\u003c/a>'\n\n# 仅当用户明确要求时才使用 Markdown\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command str_replace \\\n --doc-format markdown --pattern \"旧内容\" --content \"新内容\"\n\n# Markdown 模式下支持跨行匹配（--pattern 与 --content 都需要真实换行；\"...\"/'...' 里的 \\n 是字面量）\n# 多行内容推荐 heredoc 或 --content @file.md，避免 shell 转义踩坑\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command str_replace \\\n --doc-format markdown \\\n --pattern \"$(printf '## 旧标题\\n\\n第一段原文\\n\\n第二段原文')\" \\\n --content - \u003c\u003c'EOF'\n## 新标题\n\n改写后的第一段\n\n改写后的第二段\nEOF\n\n# Markdown 模式下使用 `前缀...后缀` 省略号匹配首尾特征明显的大段内容\n# 下例会把「## 旧标题」到「结束语。」之间的所有内容整体替换\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command str_replace \\\n --doc-format markdown \\\n --pattern \"## 旧标题...结束语。\" \\\n --content - \u003c\u003c'EOF'\n## 新标题\n\n重写后的正文...\n\n新的结束语。\nEOF\n\n# 删除文本：--content 传空字符串即可\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command str_replace \\\n --pattern \"废弃的内容\" --content \"\"\n```\n\n### block_insert_after — 在指定 block 之后插入\n\n```bash\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command block_insert_after \\\n --block-id \"目标 block_id\" \\\n --content '\u003ch2>新章节\u003c/h2>\u003cul>\u003cli>要点 1\u003c/li>\u003cli>要点 2\u003c/li>\u003c/ul>'\n```\n\n### block_replace — 替换指定 block\n\n```bash\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command block_replace \\\n --block-id \"目标 block_id\" \\\n --content '\u003cp>替换后的段落内容\u003c/p>'\n```\n\n### block_delete — 删除指定 block\n\n```bash\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command block_delete \\\n --block-id \"目标 block_id\"\n```\n\n### overwrite — 全文覆盖\n\n```bash\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command overwrite \\\n --content '\u003ctitle>全新文档\u003c/title>\u003ch1>概述\u003c/h1>\u003cp>新的内容\u003c/p>'\n```\n\n> ⚠️ 会清空文档后重写，可能丢失图片、评论等。仅在需要完全重建文档时使用。\n\n### append — 在文档末尾追加\n\n```bash\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command append \\\n --content '\u003ch2>新增章节\u003c/h2>\u003cp>追加的内容\u003c/p>'\n```\n\n> 等价于 `block_insert_after --block-id -1`，无需先获取 block ID。\n\n### block_copy_insert_after — 复制块并插入\n\n将一个或多个源块复制到锚点块之后，源块保持不变。`--src-block-ids` 为逗号分隔的源块 ID，按顺序依次插入到锚点之后。\n\n```bash\n# 复制多个块（按顺序插入：anchor → a → b → c）\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command block_copy_insert_after \\\n --block-id \"锚点 block_id\" \\\n --src-block-ids \"block_a,block_b,block_c\"\n```\n\n### block_move_after — 移动已有 block\n\n将文档中已有的 block 移动到指定锚点之后。使用 `--src-block-ids` 指定要移动的块 ID，无需 `--content`。\n\n```bash\n# 移动到页面末尾\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command block_move_after \\\n --block-id \"-1表示末尾，page_id表示开头，blk\" \\\n --src-block-ids \"block_a,block_b\"\n```\n\n## 返回值\n\n```json\n{\n \"ok\": true,\n \"identity\": \"user\",\n \"data\": {\n \"document\": {\n \"revision_id\": 13,\n \"new_blocks\": [\n { \"block_id\": \"blkcnXXXX\", \"block_type\": \"whiteboard\", \"block_token\": \"boardXXXX\" }\n ]\n },\n \"result\": \"success\",\n \"updated_blocks_count\": 3,\n \"warnings\": []\n }\n}\n```\n\n| 字段 | 说明 |\n|------|------|\n| `result` | `success` \\| `partial_success` \\| `failed` |\n| `updated_blocks_count` | 实际更新的 block 数量 |\n| `warnings` | 警告信息列表 |\n| `document.new_blocks` | 本次操作新增的 block 列表（如画板）。`block_id` 可用于后续精确编辑；`block_token` 是资源块 token（如画板）可交给 `lark-whiteboard` 等 skill 继续操作 |\n\n## 典型工作流\n\n### 精确 block 级更新\n\n1. **获取文档内容和 block ID**：\n ```bash\n lark-cli docs +fetch --api-version v2 --doc \"\u003cdoc_id>\" --detail with-ids\n ```\n\n2. **定位目标 block**：从返回的 XML 中找到要修改的 block 及其 `id` 属性\n\n3. **执行更新**：\n ```bash\n # 替换特定 block\n lark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command block_replace \\\n --block-id \"blkcnXXXX\" --content \"\u003cp>新内容\u003c/p>\"\n\n # 在某 block 后插入\n lark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command block_insert_after \\\n --block-id \"blkcnXXXX\" --content \"\u003ch2>追加的章节\u003c/h2>\"\n ```\n\n### 简单文本替换\n\n不需要 block ID，直接匹配替换：\n\n```bash\nlark-cli docs +update --api-version v2 --doc \"\u003cdoc_id>\" --command str_replace \\\n --pattern \"v1.0\" --content \"v2.0\"\n```\n\n## 画板处理\n\n> **`docs +update` 不能直接编辑已有画板的内容。** 本命令只能**新增**画板块；要修改已有画板，先用 `docs +fetch --api-version v2` 取到 `\u003cwhiteboard token=\"...\">`，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 读取 [`lark-whiteboard`](../../lark-whiteboard/SKILL.md) 并写入。\n\n画板的语法选型与插入示例见 [`lark-doc-style.md`](style/lark-doc-style.md) 的「画板语法与插入」章节。\n\n## 最佳实践\n\n- **精确操作优于全文覆盖**：使用 `block_replace`/`block_insert_after` 精确修改，避免 `overwrite` 全文覆盖\n- **str_replace 的匹配范围取决于格式**：\n - **XML 模式（默认）**：`--pattern` 只支持**行内**匹配，不支持跨行 / 跨 block。段落、整块或容器级（列表、表格、分栏、引用块等）改动请改用 `block_replace` 指定 block_id 重建。\n - **Markdown 模式**（`--doc-format markdown`）：`--pattern` 同时支持**行内和跨行**匹配，还支持 `前缀...后缀` 省略号语法（用 `...` 串联首尾片段匹配一大段内容），可以一次替换多行文本；但仍建议优先按最小片段匹配，跨 block 容器级重写仍优先用 `block_replace`，避免副作用。\n- **保护不可重建的内容**：图片、画板、电子表格等以 token 形式存储，替换时避开这些 block\n- **str_replace 的 replacement 支持富文本**：可以用行内标签 `\u003cb>`、`\u003ca>`、`\u003ccite>`、`\u003clatex>` 等替换普通文本为富文本\n- **同一 block 只能被 replace 一次**：多次修改同一 block 请合并为一次 block_replace\n- **block_delete 支持批量**：用逗号分隔多个 block_id 一次删除\n- **复杂结构重组**：将多个段落转换为 grid / table 等复杂布局时，分步操作比 overwrite 更安全：\n 1. 用 `block_insert_after` 在目标位置插入新的富文本结构\n 2. 用 `block_delete` 批量删除旧的 block\n 3. 这样可以保留文档中其他不相关的内容（图片、评论等）\n- **视觉丰富度**：插入或替换内容时，同样遵循 [`lark-doc-style.md`](style/lark-doc-style.md) 中的样式指南，主动使用结构化 block\n\n## 参考\n\n- [`lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) — 改写增强工作流（Code-Act Loop、并行执行策略）\n- [`lark-doc-style.md`](style/lark-doc-style.md) — 文档样式指南（元素选择 + 丰富度规则 + 颜色语义）\n- [`lark-doc-xml.md`](lark-doc-xml.md) — XML 语法规范\n- [`lark-doc-fetch.md`](lark-doc-fetch.md) — 获取文档\n- [`lark-doc-create.md`](lark-doc-create.md) — 创建文档\n- [`lark-doc-media-insert.md`](lark-doc-media-insert.md) — 插入图片/文件到文档\n- [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) — 认证和全局参数\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":12548,"content_sha256":"9cfba006b8cc7f17de604775cbbd120eed29a79c279fdd04e9544363f8459344"},{"filename":"references/lark-doc-whiteboard.md","content":"# lark-doc 画板处理指南\n\n> **前置条件：** 先阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。\n\n## 两个 Skill 的职责边界\n\n| Skill | 核心职责 | 约束 |\n|-------------------|-----------------------------------------------------------|---------------------------------|\n| `lark-doc` | 识别画板机会、使用 Mermaid/SVG 创建图表、调度 SubAgent、插入简单 SVG 画板或复杂空白画板 | 主 Agent 不直接创作画板内容； |\n| `lark-whiteboard` | 查询/导出已有画板；复杂图表生成（Mermaid/DSL/SVG 路由、场景选型、渲染验证）；写入已有/空白画板 | 仅特别复杂的图表或已有画板更新时由独立 SubAgent 读取 |\n\n## 画板优先规则\n\n写文档时，重要信息优先画板化。遇到核心流程、系统架构、方案对比、风险链路、里程碑、指标趋势、因果归因、组织关系、能力分层等内容，不要只用段落或表格承载；除非内容只是一次性补充说明，否则应规划为画板。\n\n同一篇文档可以有多个画板。优先设计多个聚焦画板，而不是把所有信息塞进一张大图。\n\n## 文档与画板协同流程\n\n### 步骤 1：识别画板机会\n\n| 场景 | 入口 |\n|-------------------------|-----------------------------------------------------------|\n| 文档中需要思维导图、时序图、类图、饼图、甘特图 | 步骤 2A:使用 mermaid 插入图表 |\n| 文档中需要插入其他图表/自定义图形 | 步骤 2B: 使用 SVG 插入图表 |\n| 已有画板需要更新内容 | 先 `docs +fetch --api-version v2` 获取 `board_token`，跳至步骤 3B |\n| 只查看 / 下载已有画板 | 切换至 `lark-whiteboard`，不走本流程 |\n\n> [!IMPORTANT]\n> ⚠️ **分别对每个图表进行决策**\n\n如果有多个位置需要插入图表，你需要根据每个图表的内容**分别决定**采用步骤 2A 还是 2B\n中的方式插入这个图表。在需要插入思维导图、时序图、类图、饼图、甘特图的时候可以插入 mermaid 块，在需要插入其他类型图表时启动\nSubAgent 插入 SVG。\n\n建议优先使用 SVG 插入图表，除非其属于思维导图、时序图、类图、饼图、甘特图这类可以直接使用 mermaid 语法描述，且不适宜用 SVG 绘制的图表\n\n### 步骤 2A: 使用 mermaid 插入图表\n\n```xml\n\n\u003cwhiteboard type=\"mermaid\">\n mermaid 代码...\n\u003c/whiteboard>\n```\n\n### 步骤 2B: SubAgent 使用 SVG 插入图表\n\n主 Agent 启动 SubAgent，让它用 `docs +create --api-version v2` / `docs +update --api-version v2` 插入：\n\n```xml\n\n\u003cwhiteboard type=\"svg\">\n \u003csvg...>...\n \u003c/svg>\n\u003c/whiteboard>\n```\n\nSub Agent 需要携带以下的最小上下文，以及后续的 [SVG 设计 Workflow] 章节指南：\n\n- doc token、插入位置（标题 / block_id / command）\n- 图表目标、受众、源段落或数据\n- 要求读取 `lark-doc-xml.md`；不需要读取 `lark-whiteboard`\n- SVG 必须完整自包含：包含 `\u003csvg>` 根节点和 `viewBox`，不引用外部图片、脚本、远程资源\n\n#### 画板 SVG 设计指南\n\n使用 SVG 插入画板时，最终交付是**画板跨越重排渲染的节点**(你写 SVG → 画板解析)\n**核心心智纠正 (重要)**：\n\n- 大多数 AI 如果只考虑“绝对不报错/完美映射”, 最终给出的都是全篇纯白底色加单层 `\u003crect>` 的方正卡片网格, 极其死板单调, *\n *这将被视为不及格！**\n- **SVG 给你了完全的设计自由**, 请大胆使用你脑内的图标路径 (`\u003cpath>`), 连接指引 (`流畅的 \u003cpath>`), 各种环境氛围点缀,\n 大胆一点, 充分信任你的品味, 发挥出你的顶级艺术创造力！\n\n##### SVG 设计 Workflow\n\n###### 1. 想清楚要画什么\n\n- **核心信息是什么？** 能做到一图胜千言, 绝对不要只生成平平无奇的文字表格, 要有设计感\n- **内容充实度**：如果用户描述稀疏简略, 利用你的领域知识扩展, 保证信息维度和内容充实, 但不要过度堆砌, 淹没重点\n- **视觉层级与隐喻**：这个没有固定的形式, 你自由判断, 比如: 给重要的节点加光环, 加高亮背景；给对比项设计天平或对称结构\n\n###### 2. 写 SVG\n\n> [!IMPORTANT]\n> 布局, 配色, 信息密度, 装饰物——**全部由你判断**, 打破单调的 `\u003crect>` 牢笼, 严禁通篇用矩形和文字应付用户\n> 操作边界约束：\n\n- **语言跟随用户**：图表文字的语言与用户 prompt 保持一致, 技术术语用行业里通用的写法, 不机械翻译\n- 文字用 `\u003ctext>`(不是 `\u003cpath>`), 容器宽度留够——画板按 CJK ≈ 1em / Latin ≈ 0.6em 重排\n- 连线使用正交折线替代斜直线(`\u003cpolyline>` 带水平/垂直折点)视觉效果更好\n- 可自由使用 `translate`, `rotate`, `scale`但请尽量避免使用 `skewX` / `skewY` / `matrix(...)` 发生空间级扭曲\n\n###### 画板怎么处理 SVG\n\n画板的 svg-parser 把可识别元素转成可编辑节点, 其余降级为内嵌图片(渲染没问题, 虽然不可编辑, 但是可以正常显示)；但\n`\u003cradialGradient>` / `\u003cfilter>` / `\u003cclipPath>` 等装饰特性画板完全不支持，会导致渲染问题（见下方⚠️）\n**不需要所有元素都可编辑, 但必须避免使用不支持的装饰特性, 且要兼顾可编辑和美观漂亮**\n\n**可识别的元素**\n\n- 形状：`\u003crect>` / `\u003ccircle>` / `\u003cellipse>` / `\u003cpolygon>`\n- 连线：`\u003cline>` / `\u003cpolyline>` / `\u003cpath>`(自动识别为直线 / 折线 / 曲线)\n- 文本：`\u003ctext>` / `\u003ctspan>` 画板硬编码 Noto Sans SC **文字必须用 `\u003ctext>`**\n- 分组：`\u003cg>` / `\u003ca>` / `\u003cuse>` 引用 `\u003csymbol>`\n- 变换：`translate` / `rotate` / `scale` 正常；`skewX` / `skewY` / `matrix(...)` 降级\n\n> [!IMPORTANT]\n> ⚠️ ** 不支持的装饰特性**\n\n- `\u003cradialGradient>` / `\u003cfilter>` / `\u003cpattern>` / `\u003cclipPath>` / `\u003cmask>` → 画板都不支持，**请避免使用，否则会导致画板渲染问题\n **\n\n###### 3.插入后审查\n\n插入画板后，可以从返回值使用 lark-cli 指令，将画板内容导出为 png\n图片。若是对设计不满意，可以修改后，删除原来的画板再重新插入，或是调用 [\n`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md) 编辑。\n\n```bash\nlark-cli whiteboard +query \\\n --whiteboard-token \"wbcnxxxxxxxx\" \\\n --output_as image \\\n --output ./preview.png\n```\n\n### 步骤 3B：编辑已有画板 — 启动 lark-whiteboard SubAgent\n\n复杂图和已有画板更新必须启动 SubAgent。主 Agent 只传最小上下文，不直接执行 `lark-whiteboard` 的渲染和写入流程。\n\n复杂图 SubAgent 的最小上下文：\n\n- board_token\n- 图表目标、推荐画板类型、受众\n- 与图表直接相关的源段落或数据\n- 要求读取 [`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)，按其完整流程写入该 board_token\n\n多个画板互不依赖时，可并行启动多个 SubAgent；每个 SubAgent 只负责一个画板或一个 SVG 插入点，不要互相复用上下文。\n\n### 步骤 4：完成校验\n\n- Mermaid: 确认插入的是 `\u003cwhiteboard type=\"mermaid\">`，且内容 mermaid 语法完整\n- SVG: 确认插入的是 `\u003cwhiteboard type=\"svg\">`，且内容是完整 `\u003csvg ...>...\u003c/svg>`\n- 不保留空白占位画板；复杂路径只有空白画板而无内容视为任务未完成\n\n---\n\n\n---\n\n## 关联参考\n\n- 画板查询/创作/修改/渲染写入：[`../../lark-whiteboard/SKILL.md`](../../lark-whiteboard/SKILL.md)\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":7853,"content_sha256":"0c0fdf2d3abf9cd73beac217a72229c6c263ac7e833347e3e2f6ec58619cccf0"},{"filename":"references/lark-doc-xml.md","content":"基于 HTML 子集的 XML 格式描述飞书文档内容。\n\n# 一、标准 HTML 标签\np, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr, img, b, em, u, del, a, br, span 语义不变\n\n# 二、扩展标签速查表\n## 块级标签\n|标签|说明|关键属性|\n|-|-|-|\n| `\u003ctitle>` | 文档标题（每篇唯一）| `align` |\n| `\u003ccheckbox>` | 待办项| `done=\"true\"\\|\"false\"` |\n\n## 容器标签\n|标签|说明|关键属性|\n|-|-|-|\n| `\u003ccallout>` | 高亮框，子块仅支持文本、标题、列表、待办、引用 | `emoji`(默认 bulb), `background-color`, `border-color`, `text-color` |\n| `\u003cgrid>` + `\u003ccolumn>` | 分栏布局，各列 width-ratio 之和为 1 | `width-ratio` |\n| `\u003cwhiteboard>` | 嵌入画板 | `type`: `blank` \\| `mermaid` \\| `plantuml` \\| `svg` |\n| `\u003cpre>` | （代码块，内含 `code`）| `lang`, `caption` |\n| `\u003cfigure>` | 视图容器 | `view-type` |\n| `\u003cbookmark>` | 书签链接 | `\u003cbookmark name=\"标题\" href=\"https://...\">\u003c/bookmark>`，必传 name 和 href |\n\n## 行内组件\n| 标签 | 说明 | 关键属性 |\n|-|-|-|\n| `\u003ccite type=\"user\">` | @人 | `\u003ccite type=\"user\" user-id=\"userID\">\u003c/cite>` |\n| `\u003ccite type=\"doc\">` | @文档 | `\u003ccite type=\"doc\" doc-id=\"docx_token\">\u003c/cite>` |\n| `\u003clatex>` | 行内公式 | `\u003clatex>E = mc^2\u003c/latex>` |\n| `\u003cimg>` | 图片（可独立成块或内联） | `\u003cimg width=\"800\" height=\"600\" caption=\"说明\" name=\"图.png\" href=\"http 或 https\"/>` |\n| `\u003csource>` | 文件附件（可独立成块或内联） | `\u003csource name=\"报告.pdf\"/>` |\n| `\u003ca type=\"url-preview\">` | 预览卡片 | `\u003ca type=\"url-preview\" href=\"...\">标题\u003c/a>` |\n| `\u003cbutton>` | 操作按钮 | `background-color`、`src`，必须包含 `action=OpenLink\\|DuplicatePage\\|FollowPage` |\n| `\u003ctime>` | 提醒 | 必包含 `expire-time`、`notify-time`（毫秒时间戳）、`should-notify=true\\|false` |\n\n## 文本块通用属性\n- `align` — `\"left\"`|`\"center\"`|`\"right\"`（适用于 p / h1-h9 / li / checkbox）\n- 有序列表项用 `seq=\"auto\"` 自动编号\n\n# 三、资源块\n\n文档中可嵌入外部资源块（属于容器标签的特殊形式），需要额外语法创建：\n\n- `\u003cimg>` — `\u003cimg href=\"https://...\"/>` 上传网络图片\n- `\u003cwhiteboard>` — 简单图由 SubAgent 直接插入 `\u003cwhiteboard type=\"svg\">完整自包含 SVG\u003c/whiteboard>`；复杂图使用 `\u003cwhiteboard type=\"blank\">\u003c/whiteboard>` 先创建空白画板，再按 [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) 启动 SubAgent 调用 `lark-whiteboard` 写入；\n- `\u003csheet>` — `\u003csheet type=\"blank\">\u003c/sheet>` 空白；`\u003csheet sheet-id=\"SID\" token=\"TOKEN\">\u003c/sheet>` 复制已有\n- `\u003ctask>` — `\u003ctask task-id=\"GUID\">\u003c/task>`，必传 task-id（任务 guid）\n- `\u003cchat_card>` — `\u003cchat_card chat-id=\"CHAT_ID\">\u003c/chat_card>`，必传 chat-id\n- bitable、base_ref、synced_reference、synced_source、okr — 不可创建，仅支持移动\n\n# 四、块级复制与移动\n\n## 移动（block_move_after）\n支持**所有**块类型（块级标签、容器标签、行内组件、资源块），使用 `docs +update --command block_move_after --block-id \"\u003c锚点>\" --src-block-ids \"id1,id2\"`。\n\n## 复制（block_copy_insert_after）\n- **基础标签**（块级标签、容器标签、行内组件）：均支持复制\n- **资源块**：仅 img、source、whiteboard、sheet、chat_card 支持复制；task、bitable、base_ref、synced_reference、synced_source、okr 不支持复制\n\n使用 `docs +update --command block_copy_insert_after --block-id \"\u003c锚点>\" --src-block-ids \"id1,id2\"`。\n\n> 详见 [lark-doc-update.md](lark-doc-update.md)。\n\n# 五、补充规则\n\n## 富文本样式嵌套顺序\n- 行内样式标签必须按以下固定顺序嵌套（外 → 内），关闭顺序严格反转：`\u003ca> → \u003cb> → \u003cem> → \u003cdel> → \u003cu> → \u003ccode> → \u003cspan> → 文本内容`\n\n## 列表分组\n- 连续同类型列表项自动合并为一个 `\u003cul>` 或 `\u003col>`\n- 嵌套子列表放在 `\u003cli>` 内部\n- 新增列表项必须包在 `\u003cul>` 或 `\u003col>` 内：\n ```xml\n \u003cul>\n \u003cli>第一项\u003c/li>\n \u003cli>第二项\u003c/li>\n \u003c/ul>\n ```\n\n\n## 表格扩展\n标准 HTML table 结构不变，扩展点：\n- `\u003ccolgroup>` / `\u003ccol>` 定义列宽，紧跟 `\u003ctable>` 之后：`\u003ccol span=\"2\" width=\"100\"/>`\n- `\u003cth>` / `\u003ctd>` 增加 `background-color` 和 `vertical-align`（top | middle | bottom）\n- 有表头时第一行在 `\u003cthead>` 用 `\u003cth>`，其余在 `\u003ctbody>` 用 `\u003ctd>`\n- 合并单元格仅起始格输出 `colspan` / `rowspan`，被合并的格不出现\n\n# 六、美化系统\n- 颜色优先使用命名色，也可写 `rgb(r,g,b)` / `rgba(r,g,b,a)`。**基础色（7 色）**：red, orange, yellow, green, blue, purple, gray\n | 属性 | 支持的命名色 | \n |-|-|\n | 文字颜色 `\u003cspan text-color>` | 基础色 |\n | 高亮框字色 `\u003ccallout text-color>` | 基础色 |\n | 高亮框边框 `\u003ccallout border-color>` | 基础色 | \n | 文字背景 `\u003cspan background-color>` | 基础色 + `light-{色}` + `medium-gray` | \n | 高亮框填充 `\u003ccallout background-color>` | `gray` + `light-{色}` + `medium-{色}` | \n | 单元格背景 `\u003cth/td background-color>` | 同文字背景 | \n | 按钮背景 `\u003cbutton background-color>` | 同文字背景 |\n- 常用 emoji： 💡(默认)✅❌⚠️📝❓❗👍❤️📌🏁⭐\n\n# 七、**重要规则**\n## 转义规则：标签本身 **禁止转义**，只有标签内部的文本内容才需要转义\n\n**错误** ❌：`<p>内容</p>`（把标签也转义了）\n**正确** ✅：`\u003cp>A & B 的对比：1 < 2\u003c/p>`（标签保持原样，文本中的 `&` 和 `\u003c` 才转义）\n\n转义字符表：\n- `\u003c` → `<`\n- `>` → `>`\n- `&` → `&`\n- `\\n`（换行符） → `\u003cbr/>`\n\n\n# 八、完整示例\n\n```xml\n\u003ctitle>文档标题\u003c/title>\n\n\u003ch1>一级标题\u003c/h1>\n\n\u003cp>\u003cb>加粗文本\u003c/b>，\u003cspan text-color=\"green\">绿色文本\u003c/span>\u003c/p>\n\n\u003ccallout emoji=\"💡\" background-color=\"light-yellow\" border-color=\"yellow\">\n \u003cp>高亮框内容，子块仅支持文本/标题/列表/待办/引用\u003c/p>\n\u003c/callout>\n\n\u003ccheckbox done=\"true\">已完成事项\u003c/checkbox>\n\u003ccheckbox done=\"false\">未完成事项\u003c/checkbox>\n\n\u003cgrid>\n \u003ccolumn width-ratio=\"0.5\">\n \u003cp>左栏\u003c/p>\n \u003c/column>\n \u003ccolumn width-ratio=\"0.5\">\n \u003cp>右栏\u003c/p>\n \u003c/column>\n\u003c/grid>\n\n\u003ctable>\n \u003ccolgroup>\u003ccol span=\"2\" width=\"120\"/>\u003c/colgroup>\n \u003cthead>\u003ctr>\u003cth background-color=\"light-gray\">表头\u003c/th>\u003cth background-color=\"light-gray\">表头\u003c/th>\u003c/tr>\u003c/thead>\n \u003ctbody>\u003ctr>\u003ctd>单元格\u003c/td>\u003ctd>单元格\u003c/td>\u003c/tr>\u003c/tbody>\n\u003c/table>\n\n\u003cp>\u003ccite type=\"doc\" doc-id=\"DOC_TOKEN\">\u003c/cite> \u003ccite type=\"user\" user-id=\"USER_ID\">\u003c/cite>\u003c/p>\n\n\u003col>\u003cli seq=\"auto\">第一项\u003c/li>\u003cli seq=\"auto\">第二项\u003c/li>\u003c/ol>\n\n\u003cp>\u003ca type=\"url-preview\" href=\"https://example.com\">链接标题\u003c/a>\u003c/p>\n\n\u003cp>\u003clatex>E = mc^2\u003c/latex>\u003c/p>\n\n\u003cpre lang=\"go\" caption=\"示例\">\u003ccode>fmt.Println(\"hello\")\u003c/code>\u003c/pre>\n\n\u003chr/>\n\n\u003csource name=\"文件名.pdf\"/>\n\u003cimg src=\"IMG_TOKEN\" width=\"800\" height=\"400\" caption=\"说明\" name=\"图.png\"/>\n\u003cimg href=\"https://example.com/photo.png\"/>\n\n\u003cbutton action=\"OpenLink\" src=\"https://example.com\">按钮文字\u003c/button>\n\n\u003ctime expire-time=\"1775916000000\" notify-time=\"1775912400000\" should-notify=\"false\">时间戳毫秒\u003c/time>\n\n\u003ccite type=\"citation\">\u003ca href=\"https://example.com\">引文标题\u003c/a>\u003c/cite>\n\u003cbookmark name=\"书签标题\" href=\"https://example.com\">\u003c/bookmark>\n\n\u003ctask task-id=\"TASK_GUID\">\u003c/task>\n\u003cchat_card chat-id=\"CHAT_ID\">\u003c/chat_card>\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":8250,"content_sha256":"0b89e88f26f15d0477dc57cd5971405f4c3a2ee45dca309101805c93bed098c3"},{"filename":"references/style/lark-doc-create-workflow.md","content":"# 从零创作工作流\n\n用户提供主题、需求或简要说明，需要生成一份新的飞书文档时，遵循本工作流。\n\n## 核心方法论 — Code-Act Loop\n\n通过自适应的 **Code-Act Loop** 驱动文档创作，而非固定模板式的工作流。每次任务都循环执行：\n\n1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么\n2. **Execute（执行）** — 运行相应的 `lark-cli docs` 命令，或 **spawn** Agent 子任务并行推进\n3. **Observe（观察）** — 检查命令输出，验证正确性，核查样式是否达标\n4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环\n\n循环在文档达到质量标准且满足用户需求时结束。不要试图一次性产出完美内容——迭代打磨效果更好。根据用户实际需求灵活决定文档结构和版块，而不是套用固定模板。\n\n\n## 典型 Code-Act Loop 流程\n\n### 第一波 — 规划与骨架（串行）\n\n1. 分析用户需求：受众、目的、范围\n2. 设计大纲——每个 h1/h2 章节至少规划 1 个非文本 block；承载重要信息的章节优先规划画板\n3. `docs +create --api-version v2` **只建骨架**：标题 + 开头 `\u003ccallout>` + 各级标题 + 每节一句占位摘要\n - ⚠️ **不要**一次性把完整章节内容塞进 `--content`。超长 `--content` 容易触发字符/参数限制。\n - 完整内容留到第二波，由各 Agent 用 `docs +update --command append` 或 `block_insert_after` 分段写入。\n\n### 第二波 — 内容撰写（并行 Agent）\n\n4. Spawn Agent 并行撰写各章节。每个 Agent 需收到：\n - 文档 token、负责的章节范围、期望的 block 类型\n - `lark-doc-xml.md` 和 `lark-doc-style.md` 的完整路径（Agent 须先读取）\n - 使用 `docs +update --command append` 或 `block_insert_after` 写入\n\n### 第三波 — 整合审查 + 画板意图识别（串行）\n\n5. `docs +fetch --api-version v2 --detail with-ids` 获取文档，审查整体效果\n6. 评估样式达标（富 block 密度、元素多样性、连续 `\u003cp>` 数量）\n7. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断是否有段落适合用图表达。重要信息优先画板化，记录需要插图的章节、推荐画板类型、mermaid/SVG 路径和用于画图的源内容\n\n### 第四波 — 画板与润色（并行 Agent）\n\n8. **优先处理第三波识别出的画板需求**：\n 参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。\n9. Spawn 内容改写 Agent 定向润色：\n - 文字密集章节转为 `\u003ctable>`/`\u003cgrid>`/`\u003ccallout>`\n - 主要章节间补充 `\u003chr/>`\n - 本地图片使用 `docs +media-insert` 插入\n\n\n## Agent 子任务要求\n\n内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、具体的 `docs +update` command 和 `--block-id`。\n\nMermaid 图由主 Agent 直接插入 `\u003cwhiteboard type=\"mermaid\">...\u003c/whiteboard>`，无需 SubAgent。\n\nSVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径，以及[lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的 \"SVG 设计 Workflow\" 指南。它只负责插入一个 `\u003cwhiteboard type=\"svg\">...\u003c/whiteboard>`，不改其他正文，也不读取 `lark-whiteboard`。\n\n已有画板更新 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":3707,"content_sha256":"f59e907789b111cbf5911ce83e5b7ecbbb7833ab42c86d06854e1b3498dae99a"},{"filename":"references/style/lark-doc-style.md","content":"# 文档样式指南\n\n创建或编辑文档时，必须遵循本指南，使用结构化 block 提升可读性和视觉层次。\n\n## 一、核心原则\n\n1. **结构优于文字**：能用结构化 block 表达的信息，不用纯文本段落\n2. **Front-load 结论**：文档以 `\u003ccallout>` 开头概括核心结论；每章节首段点明要旨\n3. **视觉节奏**：连续纯文本不超过 3 段；不同主题章节间用 `\u003chr/>` 分隔\n4. **最少惊讶**：同类信息使用同类元素，全篇风格统一\n5. **重要信息画板化**：核心流程、架构、对比、风险、路线图、指标趋势等重要信息优先使用画板表达\n\n## 二、元素选择指南\n\n涉及图表需求时，按类型选择插入方式：思维导图/时序图/类图/饼图/甘特图用 `\u003cwhiteboard type=\"mermaid\">` 直接内嵌；其他新图表启动 SubAgent 插入 `\u003cwhiteboard type=\"svg\">完整 SVG\u003c/whiteboard>`；只有编辑**已有**画板时才调用 **lark-whiteboard** skill。\n\n| 场景 | 推荐方案 |\n|--------------------------------------------|---------------------------------------|\n| 核心结论 / 摘要 / 注意事项 | `\u003ccallout>` + emoji + 背景色 |\n| 重要方案对比 / 优劣势 / Before vs After | `\u003cgrid>` 2 列分栏；SVG SubAgent |\n| 简短低风险对比 | `\u003cgrid>` 2 列分栏 |\n| 3+ 属性的结构化数据 / 指标表 | `\u003ctable>` + 表头背景色 |\n| 任务清单 / 检查项 | `\u003ccheckbox>` |\n| 代码片段 | `\u003cpre lang=\"x\" caption=\"说明\">` |\n| 引用 / 公式 | `\u003cblockquote>` / `\u003clatex>` |\n| 操作入口 / 跳转链接 | `\u003cbutton>` / `\u003ca type=\"url-preview\">` |\n| 流程图 / 时间线 / 示意图 / 自定义图形 / 架构图 / 数据图 /思维导图等 | 画板图表 |\n\n\n### 画板意图识别\n\n撰写或审查每个段落/章节时，**必须判断该内容是否适合用图表达**。满足以下任一特征时，应使用画板而非纯文本；如果该内容承载章节核心结论、关键决策或主要论据，即使结构较简单也优先画板化：\n\n| 内容特征 | 信号词 / 模式 | 推荐画板类型 |\n|-|-|-|\n| 多步骤的操作流程或决策路径 | \"先…然后…最后\"、\"步骤 1/2/3\"、\"如果…则…否则\" | 流程图 / 泳道图 |\n| 系统或模块间的依赖与交互 | \"调用\"、\"依赖\"、\"上游/下游\"、\"请求→响应\" | 架构图 |\n| 上下级或从属关系 | \"汇报给\"、\"下属\"、\"隶属\"、\"团队结构\" | 组织架构图 |\n| 时间线或阶段演进 | \"Q1/Q2\"、\"里程碑\"、\"阶段一→阶段二\"、日期序列 | 时间线 / 里程碑 |\n| 因果分析或问题归因 | \"根因\"、\"原因\"、\"导致\"、\"影响因素\" | 鱼骨图 |\n| 两个及以上方案/对象的多维度对比 | \"vs\"、\"方案 A/B\"、\"优劣\"、\"对比\" | 对比图 |\n| 层级递进或优先级排序 | \"基础→进阶→高级\"、\"L1/L2/L3\"、\"核心→外围\" | 金字塔图 |\n| 数值趋势或周期变化 | 带数字的时间序列、\"增长/下降\"、百分比变化 | 折线图 / 柱状图 |\n| 漏斗或转化率 | \"转化率\"、\"漏斗\"、\"从…到…留存\" | 漏斗图 |\n| 发散或归纳的思维结构 | \"要点\"、\"维度\"、\"分支\"、多层嵌套列表 | 思维导图 |\n| 循环或飞轮效应 | \"正循环\"、\"飞轮\"、\"闭环\"、\"A 驱动 B 驱动 C\" | 飞轮图 |\n| 占比分布 | \"占比\"、\"份额\"、\"分布\"、百分比加总 ≈100% | 饼图 / 树状图 |\n\n**判断规则：**\n- 重要信息能图示就图示；不要为了省步骤把关键流程、架构、对比、风险链路写成纯文本\n- 低重要度、局部辅助信息才用 `\u003ctable>` / `\u003cgrid>` / `\u003ccallout>` 承载\n- 确定需要插入哪些图表后，参照 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的方式，插入图表画板。\n\n## 三、颜色语义\n\n全篇保持语义一致，同一语义必须使用同一颜色：\n\n| 语义 | emoji 前缀 | callout 背景色 | 文字色 |\n|-|-|-|-|\n| 信息、说明 | ℹ️ \"说明：\" | `light-blue` | `blue` |\n| 成功、推荐 | ✅ \"推荐：\" | `light-green` | `green` |\n| 警告 / 错误 / 风险 | ⚠️❌ | `light-red` | `red` |\n| 注意、待确认 | ❗\"注意：\" | `light-yellow` | `yellow` |\n| 中性、辅助 | — | `light-gray` | — |\n\n- 表头统一 `background-color=\"light-gray\"`\n- 关键指标用 `\u003cspan text-color=\"green/red\">` 突出，**必须同时用 ↑↓ 或 +/- 标注方向**（色觉无障碍）\n\n## 四、排版规范\n\n- 标题层级 ≤ 4 层，段落单段 ≤ 5 行，列表嵌套 ≤ 2 层，Grid ≤ 3 列\n- 文档开头用 `\u003ccallout>` front-load 结论；\n\n## 五、丰富度自检\n\n生成内容后必须自检，**未达标时主动优化**：\n\n| 指标 | 达标标准 |\n|-|-|\n| 富 block 密度 | ≥ 40%（非纯文本 block 数 ÷ 总 block 数） |\n| 元素多样性 | ≥ 3 种不同 block 类型 |\n| 连续纯文本 | ≤ 3 段连续 `\u003cp>` |\n| 章节丰富度 | 每 h1/h2 ≥ 1 个非纯文本 block |\n| 开头 callout | 必须 |\n| 视觉节奏 | 不同主题章节间有 `\u003chr/>` |\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":5421,"content_sha256":"6b91a846a828e33f871a0513b658451078576c39a5c8d74b81497bf9927829b8"},{"filename":"references/style/lark-doc-update-workflow.md","content":"# 改写增强工作流\n\n用户提供已有文档链接或 token，需要改写、润色、补充或重排版时，遵循本工作流。\n\n## 核心方法论 — Code-Act Loop\n通过自适应的 **Code-Act Loop** 驱动文档改写，而非固定模板式的工作流。每次任务都循环执行：\n1. **Plan（规划）** — 根据用户目标和文档当前状态，评估下一步该做什么\n2. **Execute（执行）** — 运行相应的 `lark-cli docs` 命令，或 **spawn** Agent 子任务并行推进\n3. **Observe（观察）** — 检查命令输出，验证正确性，核查样式是否达标\n4. **Iterate（迭代）** — 如需调整，回到 Plan 继续循环\n\n## 核心原则：精准手术优于全量覆盖\n1. **精准手术**：只改用户指定的 block，不改其他 block。\n2. **全量覆盖**：如果用户明确要改整篇，才用 `overwrite` 命令。\n3. **保真约束**：改写时原文里的 `\u003ccite type=\"user\">`（@人）、`\u003ccite type=\"doc\">`（@文档）、`\u003cimg>`、`\u003csource>`、`\u003cwhiteboard>`、`\u003csheet>`、`\u003cbitable>`、`\u003csynced_reference>` 等行内组件和资源块一律原样保留（含所有 token / user-id / doc-id 属性），不许替换成纯文本姓名、链接或占位符。\n\n## 工作流程\n\n### 第一波 — 分析 + 画板意图识别（串行）\n\n1. **选择读取范围**（节省上下文的关键）：\n - 用户只改某一节 / 文档较大 → 先 `docs +fetch --api-version v2 --scope outline --max-depth 2` 拿目录，再 `docs +fetch --api-version v2 --scope section --start-block-id \u003c目标标题id> --detail with-ids` 精读该节（`section` 会自动展开到下一个同级/更高级标题前，不用手动算结束 block id）\n - 需要精确跨节区间 → `docs +fetch --api-version v2 --scope range --start-block-id xxx --end-block-id yyy`（或 `--end-block-id -1` 读到末尾）\n - 用户只给了模糊关键词 → `docs +fetch --api-version v2 --scope keyword --keyword xxx --context-before 1 --context-after 1 --detail with-ids`\n - 用户明确要改整篇 → `docs +fetch --api-version v2 --detail with-ids`\n - 详见 [`lark-doc-fetch.md`](../lark-doc-fetch.md) \"意图引导：选择正确的 --scope\"\n2. 系统性评估：结构清晰度、富 block 密度（≥40%）、元素多样性（≥3种）、连续 `\u003cp>` 是否超过 3 段、是否有开头 callout 和章节 `\u003chr/>`\n3. **画板意图识别**：逐章节扫描，按 `lark-doc-style.md`「画板意图识别」表判断哪些段落的信息适合用图表达。重要信息优先画板化，记录需要插图的章节（block ID）、推荐画板类型、mermaid/SVG路径和源内容片段\n4. 向用户简要说明改进计划（包含识别出的画板机会）\n\n### 第二波 — 定向改写（并行 Agent）\n\n5. **优先处理第一波识别出的画板候选段落**：\n 参考 [lark-doc-whiteboard.md](../lark-doc-whiteboard.md)中的方式，插入图表画板。\n6. Spawn 内容改写 Agent 在不重叠的章节上并行改进，各 Agent 收到文档 token 和特定 block ID：（见 `lark-doc-style.md`）\n - 开头适当添加 `\u003ccallout>`、重组引言\n - 纯文本转为 `\u003cgrid>`/`\u003ctable>`/`\u003ccallout>`\n - 添加低重要度对比分栏、关键提示等富 block；画板类需求只走第 5 步\n\n### 第三波 — 验证（串行）\n\n7. 获取更新后文档局部内容，重新检查样式指标\n8. 未达标则定向修正，向用户呈现结果\n\n## Agent 子任务要求\n\n内容改写 Agent 必须收到：文档 token、章节范围（标题/block ID）、`lark-doc-xml.md` 和 `lark-doc-style.md` 路径、具体的 `docs +update` command 和 `--block-id`。\n\nMermaid 图由主 Agent 直接插入 `\u003cwhiteboard type=\"mermaid\">...\u003c/whiteboard>`，无需 SubAgent。\n\nSVG SubAgent 必须收到：文档 token、插入位置（标题/block ID）、图表目标、源内容片段、`lark-doc-xml.md` 路径，以及[lark-doc-whiteboard.md](../lark-doc-whiteboard.md) 中的 \"SVG 设计 Workflow\" 指南。它只负责插入一个 `\u003cwhiteboard type=\"svg\">...\u003c/whiteboard>`，不改其他正文，也不读取 `lark-whiteboard`。\n\n已有画板更新 SubAgent 必须收到：board_token、图表目标、推荐画板类型、源内容片段、[`../../../lark-whiteboard/SKILL.md`](../../../lark-whiteboard/SKILL.md) 路径。它只负责写入画板，不改文档正文。\n\n**上下文节省提示**：Agent 如需在自己负责的章节内重新读取内容，优先用 `docs +fetch --api-version v2 --scope section --start-block-id \u003c章节标题id>`（自动覆盖整节），或 `--scope range --start-block-id xxx --end-block-id yyy` 精确区间，只拉自己的章节，不要重复拉全文。\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":4699,"content_sha256":"e147322764fd0daa88d778bfd1ee47dc944be6bc3758d5be946aa3ab55516ac6"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"docs (v2)","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"⚠️ API 版本：本 skill 使用 v2 API。所有 ","type":"text","marks":[{"type":"strong"}]},{"text":"docs +create --api-version v2","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":"、","type":"text","marks":[{"type":"strong"}]},{"text":"docs +fetch --api-version v2","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":"、","type":"text","marks":[{"type":"strong"}]},{"text":"docs +update --api-version v2","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" 命令必须携带 ","type":"text","marks":[{"type":"strong"}]},{"text":"--api-version v2","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":"。","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# 常用示例\nlark-cli docs +fetch --api-version v2 --doc \"文档URL或token\"\nlark-cli docs +create --api-version v2 --content '\u003ctitle>标题\u003c/title>\u003cp>内容\u003c/p>'\nlark-cli docs +update --api-version v2 --doc \"文档URL或token\" --command append --content '\u003cp>内容\u003c/p>'","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"前置条件 — 执行操作前必读","type":"text"}]},{"type":"paragraph","content":[{"text":"CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"../lark-shared/SKILL.md","type":"text","marks":[{"type":"link","attrs":{"href":"../lark-shared/SKILL.md","title":null}},{"type":"code_inline"}]},{"text":" — 认证、权限处理、全局参数（所有操作通用）","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"读取文档（","type":"text","marks":[{"type":"strong"}]},{"text":"docs +fetch --api-version v2","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":"）","type":"text","marks":[{"type":"strong"}]},{"text":" → 必读 ","type":"text"},{"text":"lark-doc-fetch.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/lark-doc-fetch.md","title":null}},{"type":"code_inline"}]},{"text":"（","type":"text"},{"text":"--scope","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--detail","type":"text","marks":[{"type":"code_inline"}]},{"text":" 选择、局部读取策略、","type":"text"},{"text":"\u003cfragment>","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"\u003cexcerpt>","type":"text","marks":[{"type":"code_inline"}]},{"text":" 输出结构）","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"创建或编辑文档内容","type":"text","marks":[{"type":"strong"}]},{"text":" → 必读 ","type":"text"},{"text":"lark-doc-xml.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/lark-doc-xml.md","title":null}},{"type":"code_inline"}]},{"text":"（XML 语法规则，仅当用户明确要求 Markdown 时改读 ","type":"text"},{"text":"lark-doc-md.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/lark-doc-md.md","title":null}},{"type":"code_inline"}]},{"text":"）；从零创建时加读 ","type":"text"},{"text":"lark-doc-create-workflow.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/style/lark-doc-create-workflow.md","title":null}},{"type":"code_inline"}]},{"text":"；编辑已有文档时加读 ","type":"text"},{"text":"lark-doc-update-workflow.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/style/lark-doc-update-workflow.md","title":null}},{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"未读完以上文件就执行相应操作会导致参数选择错误、格式错误或样式不达标。","type":"text","marks":[{"type":"strong"}]}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"格式选择规则（全局）：","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"创建 / 导入场景","type":"text","marks":[{"type":"strong"}]},{"text":"（","type":"text"},{"text":"docs +create","type":"text","marks":[{"type":"code_inline"}]},{"text":"，或 ","type":"text"},{"text":"docs +update --command append/overwrite","type":"text","marks":[{"type":"code_inline"}]},{"text":" 的整段写入）：XML 和 Markdown 都可以。用户提供 ","type":"text"},{"text":".md","type":"text","marks":[{"type":"code_inline"}]},{"text":" 本地文件、或明确说\"导入 Markdown\"时，直接用 Markdown；否则默认 XML（可用 callout、grid、checkbox 等富 block）。","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"精准编辑场景","type":"text","marks":[{"type":"strong"}]},{"text":"（","type":"text"},{"text":"docs +update","type":"text","marks":[{"type":"code_inline"}]},{"text":" 的 ","type":"text"},{"text":"str_replace","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"block_insert_after","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"block_replace","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"block_delete","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"block_move_after","type":"text","marks":[{"type":"code_inline"}]},{"text":" 等局部精修指令）：优先使用 XML（","type":"text"},{"text":"--doc-format xml","type":"text","marks":[{"type":"code_inline"}]},{"text":"，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"快速决策","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"用户需要“某个 block 的直达链接 / 锚点链接”时：返回 ","type":"text"},{"text":"文档基础 URL#block_id","type":"text","marks":[{"type":"code_inline"}]},{"text":"。如果当前只有文档 URL 没有 block_id，先用 ","type":"text"},{"text":"docs +fetch --detail with-ids","type":"text","marks":[{"type":"code_inline"}]},{"text":" 拿到目标 block 的 id","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"例：","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"已知文档 URL = ","type":"text"},{"text":"https://xxx.feishu.cn/docx/doxcn123","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"已知 block_id = ","type":"text"},{"text":"blkcn456","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"应返回 ","type":"text"},{"text":"https://xxx.feishu.cn/docx/doxcn123#blkcn456","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"用户需要在文档内","type":"text"},{"text":"创建、复制或移动","type":"text","marks":[{"type":"strong"}]},{"text":"资源块（画板、电子表格、多维表格等）时，必须先读取 ","type":"text"},{"text":"lark-doc-xml.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/lark-doc-xml.md","title":null}},{"type":"code_inline"}]},{"text":" 的「三、资源块」章节","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"写文档时，重要信息（核心流程、架构、对比、风险、路线图、关键指标、因果关系）优先规划为画板，不要只用文字或表格承载","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"新增画板必须隔离到 SubAgent：简单图由 SubAgent 直接插入 ","type":"text"},{"text":"\u003cwhiteboard type=\"svg\">完整 SVG\u003c/whiteboard>","type":"text","marks":[{"type":"code_inline"}]},{"text":"，不读 ","type":"text"},{"text":"lark-whiteboard","type":"text","marks":[{"type":"code_inline"}]},{"text":"；复杂图才由主 Agent 先建 ","type":"text"},{"text":"\u003cwhiteboard type=\"blank\">\u003c/whiteboard>","type":"text","marks":[{"type":"code_inline"}]},{"text":"，再启动 SubAgent 读取 ","type":"text"},{"text":"lark-whiteboard","type":"text","marks":[{"type":"code_inline"}]},{"text":" 写入","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"用户说\"看一下文档里的图片/附件/素材\"\"预览素材\" → 用 ","type":"text"},{"text":"lark-cli docs +media-preview","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"用户明确说\"下载素材\" → 用 ","type":"text"},{"text":"lark-cli docs +media-download","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"如果目标是画板/whiteboard/画板缩略图 → 只能用 ","type":"text"},{"text":"lark-cli docs +media-download --type whiteboard","type":"text","marks":[{"type":"code_inline"}]},{"text":"（不要用 ","type":"text"},{"text":"+media-preview","type":"text","marks":[{"type":"code_inline"}]},{"text":"）","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"拿到 spreadsheet URL/token 后 → 切到 ","type":"text"},{"text":"lark-sheets","type":"text","marks":[{"type":"code_inline"}]},{"text":" 做对象内部操作","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"用户说\"给文档加评论\"\"查看评论\"\"回复评论\"\"给评论加/删除表情 reaction\" → 切到 ","type":"text"},{"text":"lark-drive","type":"text","marks":[{"type":"code_inline"}]},{"text":" 处理","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"文档内容中出现嵌入的 ","type":"text"},{"text":"\u003csheet>","type":"text","marks":[{"type":"code_inline"}]},{"text":"、","type":"text"},{"text":"\u003cbitable>","type":"text","marks":[{"type":"code_inline"}]},{"text":" 或 ","type":"text"},{"text":"\u003ccite file-type=\"sheets|bitable\">","type":"text","marks":[{"type":"code_inline"}]},{"text":" 标签时 → ","type":"text"},{"text":"必须主动提取 token 并切到对应技能下钻读取内部数据","type":"text","marks":[{"type":"strong"}]},{"text":"，不能只呈现标签本身","type":"text"}]}]}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"标签 / 属性","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"提取字段","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"切到技能","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003csheet token=\"...\" sheet-id=\"...\">","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"token","type":"text","marks":[{"type":"code_inline"}]},{"text":" -> spreadsheet_token, ","type":"text"},{"text":"sheet-id","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"lark-sheets","type":"text","marks":[{"type":"link","attrs":{"href":"../lark-sheets/SKILL.md","title":null}},{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003cbitable token=\"...\" table-id=\"...\">","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"token","type":"text","marks":[{"type":"code_inline"}]},{"text":" -> app_token, ","type":"text"},{"text":"table-id","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"lark-base","type":"text","marks":[{"type":"link","attrs":{"href":"../lark-base/SKILL.md","title":null}},{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003ccite type=\"doc\" file-type=\"sheets\" token=\"...\" sheet-id=\"...\">","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"同 ","type":"text"},{"text":"\u003csheet>","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"lark-sheets","type":"text","marks":[{"type":"link","attrs":{"href":"../lark-sheets/SKILL.md","title":null}},{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003ccite type=\"doc\" file-type=\"bitable\" token=\"...\" table-id=\"...\">","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"同 ","type":"text"},{"text":"\u003cbitable>","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"lark-base","type":"text","marks":[{"type":"link","attrs":{"href":"../lark-base/SKILL.md","title":null}},{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003csynced_reference src-token=\"...\" src-block-id=\"...\">","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"src-token","type":"text","marks":[{"type":"code_inline"}]},{"text":" -> doc_token, ","type":"text"},{"text":"src-block-id","type":"text","marks":[{"type":"code_inline"}]},{"text":" -> block_id","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"用 ","type":"text"},{"text":"docs +fetch --api-version v2","type":"text","marks":[{"type":"code_inline"}]},{"text":" 读取 src-token 文档，定位 block","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Shortcuts（推荐优先使用）","type":"text"}]},{"type":"paragraph","content":[{"text":"Shortcut 是对常用操作的高级封装（","type":"text"},{"text":"lark-cli docs +\u003cverb> [flags]","type":"text","marks":[{"type":"code_inline"}]},{"text":"）。有 Shortcut 的操作优先使用。","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Shortcut","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"说明","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"+create","type":"text","marks":[{"type":"link","attrs":{"href":"references/lark-doc-create.md","title":null}},{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Create a Lark document (XML / Markdown)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"+fetch","type":"text","marks":[{"type":"link","attrs":{"href":"references/lark-doc-fetch.md","title":null}},{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Fetch Lark document content (XML / Markdown)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"+update","type":"text","marks":[{"type":"link","attrs":{"href":"references/lark-doc-update.md","title":null}},{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Update a Lark document (str_replace / block_insert_after / block_replace / ...)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"+media-insert","type":"text","marks":[{"type":"link","attrs":{"href":"references/lark-doc-media-insert.md","title":null}},{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Insert a local image or file at the end of a Lark document (4-step orchestration + auto-rollback). Prefer ","type":"text"},{"text":"--from-clipboard","type":"text","marks":[{"type":"code_inline"}]},{"text":" when the image is already on the system clipboard (screenshots, copy from Feishu/browser); use ","type":"text"},{"text":"--file","type":"text","marks":[{"type":"code_inline"}]},{"text":" only for on-disk sources.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"+media-download","type":"text","marks":[{"type":"link","attrs":{"href":"references/lark-doc-media-download.md","title":null}},{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Download document media or whiteboard thumbnail (auto-detects extension)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"+media-preview","type":"text","marks":[{"type":"link","attrs":{"href":"references/lark-doc-media-preview.md","title":null}},{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Preview document media file (auto-detects extension)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"+whiteboard-update","type":"text","marks":[{"type":"link","attrs":{"href":"../lark-whiteboard/references/lark-whiteboard-update.md","title":null}},{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Alias of ","type":"text"},{"text":"whiteboard +update","type":"text","marks":[{"type":"code_inline"}]},{"text":". Update an existing whiteboard with DSL, Mermaid or PlantUML. Prefer ","type":"text"},{"text":"whiteboard +update","type":"text","marks":[{"type":"code_inline"}]},{"text":"; refer to lark-whiteboard skill for details.","type":"text"}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"lark-doc","author":"@skillopedia","source":{"stars":13247,"repo_name":"cli","origin_url":"https://github.com/larksuite/cli/blob/HEAD/skills/lark-doc/SKILL.md","repo_owner":"larksuite","body_sha256":"90fcded26e70d776f24d81494ba27c66df9a35b68ac1de17e17de208b7e34d53","cluster_key":"7066c338189509014e25c41f559917b669fbc98cd64495db13b3fa82d5ac856d","clean_bundle":{"format":"clean-skill-bundle-v1","source":"larksuite/cli/skills/lark-doc/SKILL.md","attachments":[{"id":"4da07963-6ca2-51e2-b4cb-d60850dc70cf","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4da07963-6ca2-51e2-b4cb-d60850dc70cf/attachment.md","path":"references/lark-doc-create.md","size":5460,"sha256":"eda35f0b1d9dedf59cabbaed2b20d09b2ddc3cf4275fa1053e8e8d7e1463a11c","contentType":"text/markdown; charset=utf-8"},{"id":"4d3b5f7a-b038-575a-8658-b59bf626cab1","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4d3b5f7a-b038-575a-8658-b59bf626cab1/attachment.md","path":"references/lark-doc-fetch.md","size":8629,"sha256":"c0f932226103f37fa1270c5a50c81577ddcb49db5b80b8b124ec63d58e29d728","contentType":"text/markdown; charset=utf-8"},{"id":"7e684dd0-c606-599e-8808-7455f8bc6de9","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7e684dd0-c606-599e-8808-7455f8bc6de9/attachment.md","path":"references/lark-doc-md.md","size":5104,"sha256":"7b0e0e132d93f2974264c359d066f3a21f957cafe9a13b0637bca69e8e7486b9","contentType":"text/markdown; charset=utf-8"},{"id":"023bc73b-9ee8-56f0-a60c-6af87e8bad5a","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/023bc73b-9ee8-56f0-a60c-6af87e8bad5a/attachment.md","path":"references/lark-doc-media-download.md","size":2169,"sha256":"d4c7f67d07b907106a037500e5809405ce74ee4b642767af3e417c5edd527277","contentType":"text/markdown; charset=utf-8"},{"id":"ddcec56d-d54b-5262-a49a-3a57a8f659b7","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/ddcec56d-d54b-5262-a49a-3a57a8f659b7/attachment.md","path":"references/lark-doc-media-insert.md","size":6944,"sha256":"1c1e4f799ba056e51a7cb84188da3d3c4b22d687403b43d4bb8971551b455dfd","contentType":"text/markdown; charset=utf-8"},{"id":"a996c97e-b62a-5e92-adf5-da4ef4da6d09","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a996c97e-b62a-5e92-adf5-da4ef4da6d09/attachment.md","path":"references/lark-doc-media-preview.md","size":1647,"sha256":"ebecf432d6ad0dbfa249cbf3dab91e7e20e25ee29e1c4874a039aa2bb8194200","contentType":"text/markdown; charset=utf-8"},{"id":"61c1d1af-6b6c-5492-bbc0-3404ffb79bc7","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/61c1d1af-6b6c-5492-bbc0-3404ffb79bc7/attachment.md","path":"references/lark-doc-update.md","size":12548,"sha256":"9cfba006b8cc7f17de604775cbbd120eed29a79c279fdd04e9544363f8459344","contentType":"text/markdown; charset=utf-8"},{"id":"84e8726f-61c7-57bb-a7f0-79e041def8bc","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/84e8726f-61c7-57bb-a7f0-79e041def8bc/attachment.md","path":"references/lark-doc-whiteboard.md","size":7853,"sha256":"0c0fdf2d3abf9cd73beac217a72229c6c263ac7e833347e3e2f6ec58619cccf0","contentType":"text/markdown; charset=utf-8"},{"id":"61a3164b-c8c6-5048-b79a-47fa59e64360","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/61a3164b-c8c6-5048-b79a-47fa59e64360/attachment.md","path":"references/lark-doc-xml.md","size":8250,"sha256":"0b89e88f26f15d0477dc57cd5971405f4c3a2ee45dca309101805c93bed098c3","contentType":"text/markdown; charset=utf-8"},{"id":"b1b24f72-912d-5f04-bf44-52ff57f8d67f","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b1b24f72-912d-5f04-bf44-52ff57f8d67f/attachment.md","path":"references/style/lark-doc-create-workflow.md","size":3707,"sha256":"f59e907789b111cbf5911ce83e5b7ecbbb7833ab42c86d06854e1b3498dae99a","contentType":"text/markdown; charset=utf-8"},{"id":"a260c0b0-735e-55de-bec8-7316bdd54452","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a260c0b0-735e-55de-bec8-7316bdd54452/attachment.md","path":"references/style/lark-doc-style.md","size":5421,"sha256":"6b91a846a828e33f871a0513b658451078576c39a5c8d74b81497bf9927829b8","contentType":"text/markdown; charset=utf-8"},{"id":"17dc56fb-beb1-5027-85c8-0f996c960f90","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/17dc56fb-beb1-5027-85c8-0f996c960f90/attachment.md","path":"references/style/lark-doc-update-workflow.md","size":4699,"sha256":"e147322764fd0daa88d778bfd1ee47dc944be6bc3758d5be946aa3ab55516ac6","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"70ce96a8205bdec816625e64bca008ebf57dc36dc4cdeb925e4f8529f4593c1e","attachment_count":12,"text_attachments":12,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"skills/lark-doc/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"documents-office","category_label":"Documents"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"documents-office","metadata":{"cliHelp":"lark-cli docs --api-version v2 --help; lark-cli docs +create --api-version v2 --help; lark-cli docs +fetch --api-version v2 --help; lark-cli docs +update --api-version v2 --help","requires":{"bins":["lark-cli"]}},"import_tag":"clean-skills-v1","description":"飞书云文档 / Docx / 知识库 Wiki 文档（v2）：创建、打开、读取、获取、查看、总结、整理、改写、翻译、审阅和编辑飞书文档内容。当用户给出飞书文档 URL/token，或说查看/读取/打开某个文档、提取文档内容、总结文档、生成/创建文档、追加/替换/删除/移动内容、调整排版、插入或下载文档图片/附件/素材/画板缩略图时使用。文档内容中出现嵌入电子表格、多维表格、需要将重要信息可视化为画板（含 SVG 画板）、引用或同步块时，也先用本 skill 读取和提取 token，再切到对应 skill 下钻。使用本 skill 时，docs +create、docs +fetch、docs +update 必须携带 --api-version v2；默认使用 DocxXML，也支持 Markdown。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。"}},"renderedAt":1782980514279}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.