Lark Doc

docs (v1)

CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理

核心概念

文档类型与 Token

飞书开放平台中，不同类型的文档有不同的 URL 格式和 Token 处理方式。在进行文档操作（如添加评论、下载文件等）时，必须先获取正确的 file_token。

文档 URL 格式与 Token 处理

Wiki 链接特殊处理（关键！）

知识库链接（/wiki/TOKEN）背后可能是云文档、电子表格、多维表格等不同类型的文档。不能直接假设 URL 中的 token 就是 file_token，必须先查询实际类型和真实 token。

处理流程

1. 使用 `wiki.spaces.get_node` 查询节点信息

   lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

2. 从返回结果中提取关键信息

• node.obj_type：文档类型（docx/doc/sheet/bitable/slides/file/mindnote）
• node.obj_token：真实的文档 token（用于后续操作）
• node.title：文档标题

3. 根据 `obj_type` 使用对应的 API

查询示例

# 查询 wiki 节点
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'

返回结果示例：

{
   "node": {
      "obj_type": "docx",
      "obj_token": "xxxx",
      "title": "标题",
      "node_type": "origin",
      "space_id": "12345678910"
   }
}

资源关系

Wiki Space (知识空间)
└── Wiki Node (知识库节点)
    ├── obj_type: docx (新版文档)
    │   └── obj_token (真实文档 token)
    ├── obj_type: doc (旧版文档)
    │   └── obj_token (真实文档 token)
    ├── obj_type: sheet (电子表格)
    │   └── obj_token (真实文档 token)
    ├── obj_type: bitable (多维表格)
    │   └── obj_token (真实文档 token)
    └── obj_type: file/slides/mindnote
        └── obj_token (真实文档 token)

Drive Folder (云空间文件夹)
└── File (文件/文档)
    └── file_token (直接使用)

重要说明：画板编辑

⚠️ lark-doc skill 不能直接编辑已有画板内容，但 `docs +update` 可以新建空白画板

场景 1：已通过 docs +fetch 获取到文档内容和画板 token

如果用户已经通过 docs +fetch 拉取了文档内容，并且文档中已有画板（返回的 markdown 中包含 <whiteboard token="xxx"/> 标签），请引导用户： 1. 记录画板的 token 2. 查看 `../lark-whiteboard/SKILL.md` 了解如何编辑画板内容

场景 2：刚创建画板，需要编辑

如果用户刚通过 docs +update 创建了空白画板，需要编辑时： 步骤 1：按空白画板语法创建

• 在 --markdown 中直接传 <whiteboard type="blank"></whiteboard>
• 需要多个空白画板时，在同一个 --markdown 里重复多个 whiteboard 标签

步骤 2：从响应中记录 token

• docs +update 成功后，读取响应字段 data.board_tokens
• data.board_tokens 是新建画板的 token 列表，后续编辑直接使用这里的 token

步骤 3：引导编辑

• 记录需要编辑的画板 token
• 查看 `../lark-whiteboard/SKILL.md` 了解如何编辑画板内容

注意事项

• 已有画板内容无法通过 lark-doc 的 docs +update 直接编辑
• 编辑画板需要使用专门的 `../lark-whiteboard/SKILL.md`

快速决策

• 用户说“找一个表格”“按名称搜电子表格”“找报表”“最近打开的表格”，先用 lark-cli docs +search 做资源发现。
• docs +search 不是只搜文档 / Wiki；结果里会直接返回 SHEET 等云空间对象。
• 拿到 spreadsheet URL / token 后，再切到 lark-sheets 做对象内部读取、筛选、写入等操作。

补充说明

docs +search 除了搜索文档 / Wiki，也承担“先定位云空间对象，再切回对应业务 skill 操作”的资源发现入口角色；当用户口头说“表格 / 报表”时，也优先从这里开始。

Shortcuts（推荐优先使用）

Shortcut 是对常用操作的高级封装（lark-cli docs +<verb> [flags]）。有 Shortcut 的操作优先使用。

docs +create（创建飞书云文档）

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

从 Lark-flavored Markdown 内容创建一个新的飞书云文档。

命令

# 创建简单文档
lark-cli docs +create --title "项目计划" --markdown "## 目标\n\n- 目标 1\n- 目标 2"

# 创建到指定文件夹
lark-cli docs +create --title "会议纪要" --folder-token fldcnXXXX --markdown "## 讨论议题\n\n1. 进度\n2. 计划"

# 创建到知识库节点下
lark-cli docs +create --title "技术文档" --wiki-node wikcnXXXX --markdown "## API 说明"

# 创建到知识空间根目录
lark-cli docs +create --title "概览" --wiki-space 7000000000000000000 --markdown "## 项目概览"

# 创建到个人知识库
lark-cli docs +create --title "学习笔记" --wiki-space my_library --markdown "## 笔记"

返回值

工具成功执行后，返回一个 JSON 对象，包含以下字段：

• `doc_id`（string）：文档的唯一标识符（token），格式如 doxcnXXXXXXXXXXXXXXXXXXX
• `doc_url`（string）：文档的访问链接，可直接在浏览器中打开
• `message`（string）：操作结果消息，如"文档创建成功"

[!IMPORTANT]

当文档创建在 wiki_node 或 wiki_space 下时，返回的 doc_url 可能是 /wiki/... 形式的知识库链接，而不是 /docx/... 形式的文档链接。

如果后续要调用 `lark-doc-media-insert` 这类当前只支持 doc_id 或 /docx/... URL 自动提取的 skill，请优先使用返回值里的 doc_id，不要直接复用这个 doc_url。

[!IMPORTANT]

如果文档是以应用身份（bot）创建的，agent 在创建成功后应默认继续使用 bot 身份，为当前可用的 user 身份添加该文档的 full_access（管理员）权限。推荐流程：

1. 先用 lark-cli contact +get-user 获取当前用户信息，并从返回结果中读取该用户的 open_id

2. 再切回 bot 身份，使用这个 open_id 给该用户授权该文档的 full_access（管理员）权限

>

如果 lark-cli contact +get-user 无法执行，或者本地没有可用的 user 身份、拿不到当前用户的 open_id，则应视为“本地没有可用的 user 身份”，明确说明因此未完成授权。

>

回复创建结果时，除 doc_id / doc_url 外，还必须明确告知用户授权结果：

- 如果授权成功：直接说明当前 user 已获得该文档的管理员权限

- 如果本地没有可用的 user 身份：明确说明因此未完成授权

- 如果授权失败：明确说明文档已创建成功，但授权失败，并透出失败原因；同时提示用户可以稍后重试授权，或继续使用应用身份（bot）处理该文档

>

如果授权未完成，应继续给出后续引导：用户可以稍后重试授权，也可以继续使用应用身份（bot）处理该文档；如果希望后续改由自己管理，也可将文档 owner 转移给该用户。

>

仍然不要擅自执行 owner 转移。 如果用户需要把 owner 转给自己，必须单独确认。

参数

markdown（必填）

文档的 Markdown 内容，使用 Lark-flavored Markdown 格式。

调用本工具的 markdown 内容应当尽量结构清晰，样式丰富，有很高的可读性。合理地使用 callout 高亮块、分栏、表格、图片和空白画板等能力，做到图文并茂。

你需要遵循以下原则：

• 结构清晰：标题层级 ≤ 4 层，用 Callout 突出关键信息
• 视觉节奏：用分割线、分栏、表格打破大段纯文字
• 图文交融：流程、架构或草图需要可视化时，优先使用图片、表格或空白画板
• 克制留白：Callout 不过度、加粗只强调核心词

当用户有明确的样式、风格需求时，应当以用户的需求为准！

重要提示：

• 禁止重复标题：markdown 内容开头不要写与 title 相同的一级标题！title 参数已经是文档标题，markdown 应直接从正文内容开始
• 目录：飞书自动生成，无需手动添加
• Markdown 语法必须符合 Lark-flavored Markdown 规范，详见下方"内容格式"章节
• 创建较长的文档时，强烈建议配合 docs +update --mode append，进行分段的创建，提高成功率

folder-token（可选）

父文件夹的 token。如果不提供，文档将创建在用户的个人空间根目录。

folder_token 可以从飞书文件夹 URL 中获取，格式如：https://xxx.feishu.cn/drive/folder/fldcnXXXX，其中 fldcnXXXX 即为 folder_token。

wiki-node（可选）

知识库节点 token 或 URL（可选，传入则在该节点下创建文档，与 folder-token 和 wiki-space 互斥）

wiki_node 可以从飞书知识库页面 URL 中获取，格式如：https://xxx.feishu.cn/wiki/wikcnXXXX，其中 wikcnXXXX 即为 wiki_node token。

wiki-space（可选）

知识空间 ID（可选，传入则在该空间根目录下创建文档。特殊值 my_library 表示用户的个人知识库。与 wiki-node 和 folder-token 互斥）

wiki_space 可以从知识空间设置页面 URL 中获取，格式如：https://xxx.feishu.cn/wiki/settings/7000000000000000000，其中 7000000000000000000 即为 wiki_space ID。

参数优先级：wiki-node > wiki-space > folder-token

示例

示例 1：创建简单文档

lark-cli docs +create --title "项目计划" --markdown "## 项目概述\n\n这是一个新项目。\n\n## 目标\n\n- 目标 1\n- 目标 2"

示例 2：使用飞书扩展语法

lark-cli docs +create --title "产品需求" --markdown '<callout emoji="💡" background-color="light-blue">\n重要需求说明\n</callout>'

内容格式

文档内容使用 Lark-flavored Markdown 格式，这是标准 Markdown 的扩展版本，支持飞书文档的所有块类型和富文本格式。

通用规则

• 使用标准 Markdown 语法作为基础
• 使用自定义 XML 标签实现飞书特有功能（具体标签见各功能章节）
• 需要显示特殊字符时使用反斜杠转义：* ~ $ [ ] < > { } | ^`

---

基础块类型

文本（段落）

普通文本段落

段落中的**粗体文字**

多个段落之间用空行分隔。

居中文本 {align="center"}
右对齐文本 {align="right"}

段落对齐：支持 {align="left|center|right"} 语法。可与颜色组合：{color="blue" align="center"}

标题

飞书支持 9 级标题。H1-H6 使用标准 Markdown 语法，H7-H9 使用 HTML 标签：

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题
<h7>七级标题</h7>
<h8>八级标题</h8>
<h9>九级标题</h9>

# 带颜色的标题 {color="blue"}
## 红色标题 {color="red"}
# 居中标题 {align="center"}
## 蓝色居中标题 {color="blue" align="center"}

标题属性：支持 {color="颜色名"} 和 {align="left|center|right"} 语法，可组合使用。颜色值：red, orange, yellow, green, blue, purple, gray。请谨慎使用该能力。

列表

有序列表、无序列表嵌套使用 tab 或者 2 空格缩进：

- 无序项1
  - 无序项1.a
  - 无序项1.b

1. 有序项1
2. 有序项2

- [ ] 待办
- [x] 已完成

引用块

> 这是一段引用
> 可以跨多行

> 引用中支持**加粗**和*斜体*等格式

代码块

注意：只支持围栏代码块（ ` ），不支持缩进代码块。

````markdown

print("Hello")

````

支持语言：python, javascript, go, java, sql, json, yaml, shell 等。

分割线

---

---

富文本格式

文本样式

**粗体** *斜体* ~~删除线~~ ` 行内代码 <u>下划线</u>`

文字颜色

<text color="red">红色</text> <text background-color="yellow">黄色背景</text>

支持: red, orange, yellow, green, blue, purple, gray

链接

[链接文字](https://example.com) （不支持锚点链接）

行内公式（LaTeX）

$E = mc^2$（$前后需空格）或 <equation>E = mc^2</equation>（无限制，推荐）

---

高级块类型

高亮块（Callout）

<callout emoji="✅" background-color="light-green" border-color="green">
支持**格式化**的内容，可包含多个块
</callout>

属性: emoji (使用 emoji 字符如 ✅ ⚠️ 💡), background-color, border-color, text-color

背景色: light-red/red, light-blue/blue, light-green/green, light-yellow/yellow, light-orange/orange, light-purple/purple, pale-gray/light-gray/dark-gray

常用: 💡light-blue(提示) ⚠️light-yellow(警告) ❌light-red(危险) ✅light-green(成功)

限制: callout 子块仅支持文本、标题、列表、待办、引用。不支持代码块、表格、图片。

分栏（Grid）

适合对比、并列展示场景。支持 2-5 列：

两栏（等宽）

<grid cols="2">
<column>

左栏内容

</column>
<column>

右栏内容

</column>
</grid>

三栏自定义宽度

<grid cols="3">
<column width="20">左栏(20%)</column>
<column width="60">中栏(60%)</column>
<column width="20">右栏(20%)</column>
</grid>

属性: cols(列数 2-5), width(列宽百分比，总和为 100，等宽时可省略)

表格

标准 Markdown 表格

| 列 1 | 列 2 | 列 3 |
|------|------|------|
| 单元格 1 | 单元格 2 | 单元格 3 |
| 单元格 4 | 单元格 5 | 单元格 6 |

飞书增强表格

当单元格需要复杂内容（列表、代码块、高亮块等）时使用。

层级结构（必须严格遵守）：

<lark-table>                    <- 表格容器
  <lark-tr>                     <- 行（直接子元素只能是 lark-tr）
    <lark-td>内容</lark-td>     <- 单元格（直接子元素只能是 lark-td）
    <lark-td>内容</lark-td>     <- 每行的 lark-td 数量必须相同！
  </lark-tr>
</lark-table>

属性：

• column-widths：列宽，逗号分隔像素值，总宽约 730
• header-row：首行是否为表头（"true" 或 "false"）
• header-column：首列是否为表头（"true" 或 "false"）

单元格写法：内容前后必须空行

<lark-td>

这里写内容

</lark-td>

完整示例（2行3列）：

<lark-table column-widths="200,250,280" header-row="true">
<lark-tr>
<lark-td>

**表头1**

</lark-td>
<lark-td>

**表头2**

</lark-td>
<lark-td>

**表头3**

</lark-td>
</lark-tr>
<lark-tr>
<lark-td>

普通文本

</lark-td>
<lark-td>

- 列表项1
- 列表项2

</lark-td>
<lark-td>

代码内容

</lark-td>
</lark-tr>
</lark-table>

限制：单元格内不支持 Grid 和嵌套表格

合并单元格：读取时返回 rowspan/colspan 属性，创建暂不支持

禁止：

• 混用 Markdown 表格语法（|---|）
• 使用 <br/> 换行
• 遗漏 <lark-td> 标签

图片

<image url="https://example.com/image.png" width="800" height="600" align="center" caption="图片描述文字"/>

属性: url (必需，系统会自动下载并上传), width, height, align (left/center/right), caption

注意: 不支持直接使用 token 属性（如 <image token="xxx"/>），只支持 URL 方式。系统会自动下载图片并上传到飞书。

支持 PNG/JPG/GIF/WebP/BMP，最大 10MB

图片/文件插入方式选择：

• 有公开可访问的图片 URL → 直接在 docs +create / docs +update 的 markdown 中使用 <image url="..."/> 一步到位
• 本地图片或文件 → 先用 docs +create / docs +update 创建或更新文档文本内容，再用 lark-doc-media-insert（docs +media-insert）将本地图片或文件追加到文档末尾

文件

<file url="https://example.com/document.pdf" name="文档.pdf" view-type="1"/>

属性:

• url (文件 URL，必需，系统会自动下载并上传)
• name (文件名，必需)
• view-type (1=卡片视图, 2=预览视图，可选)

注意: 不支持直接使用 token 属性（如 <file token="xxx"/>）

画板

创建空白画板时，直接在 markdown 中写 <whiteboard type="blank"></whiteboard>。

自然语言请求示例：

• “帮我创建一个带单个空白画板的文档”
• “帮我创建一个文档，里面放两个空白画板”

# 创建带单个空白画板的文档
lark-cli docs +create --title "空白画板示例" --markdown '<whiteboard type="blank"></whiteboard>'

<whiteboard type="blank"></whiteboard>

一次创建多个空白画板时，在同一个 markdown 里重复多个标签：

<whiteboard type="blank"></whiteboard>
<whiteboard type="blank"></whiteboard>

读取画板

读取时返回 <whiteboard> 标签：

<whiteboard token="xxx" align="center" width="800" height="600"/>

重要说明：

• 创建空白画板时，直接使用 <whiteboard type="blank"></whiteboard>
• 读取时只能获取 token，可通过 media-download 查看内容，无法直接读出画板内部内容
• 画板编辑：详见 SKILL.md

多维表格（Bitable）

<bitable view="table"/>
<bitable view="kanban"/>

属性: view (table/kanban，默认 table)

注意: token 是只读属性，创建时不能指定。只能创建空的多维表格，创建后再手动添加数据。

会话卡片（ChatCard）

<chat-card id="oc_xxx" align="center"/>

属性: id (格式 oc_xxx, 必需), align (left/center/right)

内嵌网页（Iframe）

<iframe url="https://example.com/survey?id=123" type="12"/>

属性: url (必需), type (组件类型数字, 必需)

type 枚举: 1=Bilibili, 2=西瓜, 3=优酷, 4=Airtable, 5=百度地图, 6=高德地图, 8=Figma, 9=墨刀, 10=Canva, 11=CodePen, 12=飞书问卷, 13=金数据

重要提示: 仅支持上述列出的网页类型。对于普通网页链接，请使用 Markdown 链接格式 [链接文字](URL) 代替。

链接预览（LinkPreview）

<link-preview url="消息链接" type="message"/>

目前仅支持消息链接，只支持读取，不支持创建

引用容器（QuoteContainer）

<quote-container>
引用容器内容
</quote-container>

与 quote 引用块不同，引用容器是容器类型，可包含多个子块

---

高级功能块

电子表格（Sheet）

<sheet rows="5" cols="5"/>
<sheet/>

属性: rows (行数，默认 3，最大 9), cols (列数，默认 3)

注意: token 是只读属性，创建时不能指定。只能创建空的电子表格，创建后使用 Sheet API 操作数据。

只读块类型

以下块类型仅支持读取，不支持创建：

任务块

<task task-id="xxx" members="ou_123, ou_456" due="2025-01-01">任务标题</task>

同步块

<!-- 源同步块 -->
<source-synced align="1">子块内容...</source-synced>

<!-- 引用同步块 -->
<reference-synced source-block-id="xxx" source-document-id="yyy">源内容...</reference-synced>

文档小组件（AddOns）

<add-ons component-type-id="blk_xxx" record='{"key":"value"}'/>

Wiki 子页面列表（SubPageList）

<sub-page-list wiki="wiki_xxx"/>

仅支持知识库文档创建，需传入当前页面的 wiki token

议程（Agenda）

<agenda>
  <agenda-item>
    <agenda-title>议程标题</agenda-title>
    <agenda-content>议程内容</agenda-content>
  </agenda-item>
</agenda>

OKR 系列

<okr id="okr_xxx">
  <objective id="obj_1">
    <kr id="kr_1"/>
  </objective>
</okr>

仅支持 user_access_token 创建，需使用 OKR API 进行详细操作

---

提及和引用

提及用户

<mention-user id="ou_xxx"/>

属性: id (用户 open_id，格式 ou_xxx)

注意不要直接在文档中写 @张三 这类格式，应当使用 search-user 获取用户的 id，并使用 mention-user。

提及文档

<mention-doc token="doxcnXXX" type="docx">文档标题</mention-doc>

属性: token (文档 token), type (docx/sheet/bitable)

---

日期和时间

日期提醒（Reminder）

<reminder date="2025-12-31T18:00+08:00" notify="true" user-id="ou_xxx"/>

属性:

• date (必需): YYYY-MM-DDTHH:mm+HH:MM, ISO 8601 带时区偏移
• notify (true/false): 是否发送通知
• user-id (必需): 创建者用户 ID

---

数学表达式

块级公式（LaTeX）

```markdown $$ \int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2} $$ ```

行内公式

爱因斯坦方程：$E = mc^2$（注意 $ 前后需空格，紧邻位置不能有空格）

---

写作指南

场景速查

---

最佳实践

• 空行分隔：不同块类型之间用空行分隔
• 转义字符：特殊字符用 \ 转义：\* \~ \`
• 图片：使用 URL，系统自动下载上传
• 分栏：列宽总和必须为 100
• 表格选择：简单数据用 Markdown，复杂嵌套用 <lark-table>
• 提及：@用户用 <mention-user>，@文档用 <mention-doc>
• 目录：飞书自动生成，无需手动添加

参考

• lark-doc-fetch — 获取文档
• lark-doc-update — 更新文档
• lark-doc-media-insert — 插入图片/文件到文档
• lark-shared — 认证和全局参数

docs +fetch（获取飞书云文档）

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

命令

# 获取文档内容（默认输出 Markdown 文本）
lark-cli docs +fetch --doc "https://xxx.feishu.cn/docx/Z1FjxxxxxxxxxxxxxxxxxxxtnAc"

# 直接传 token
lark-cli docs +fetch --doc Z1FjxxxxxxxxxxxxxxxxxxxtnAc

# 知识库 URL 也支持
lark-cli docs +fetch --doc "https://xxx.feishu.cn/wiki/Z1FjxxxxxxxxxxxxxxxxxxxtnAc"

# 分页获取（大文档）
lark-cli docs +fetch --doc Z1FjxxxxxxxxxxxxxxxxxxxtnAc --offset 0 --limit 50

# 人类可读格式输出
lark-cli docs +fetch --doc Z1FjxxxxxxxxxxxxxxxxxxxtnAc --format pretty

参数

重要：图片、文件、画板的处理

文档中的图片、文件、画板需要通过 `lark-doc-media-download`（docs +media-download）单独获取！

识别格式

返回的 Markdown 中，媒体文件以 HTML 标签形式出现：

• 图片：

  <image token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc" width="1833" height="2491" align="center"/>

• 文件：

  <view type="1">
    <file token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc" name="skills.zip"/>
  </view>

• 画板：

  <whiteboard token="Z1FjxxxxxxxxxxxxxxxxxxxtnAc"/>

• 画板编辑：详见 SKILL.md

获取步骤

1. 从 HTML 标签中提取 token 属性值 2. 调用 lark-doc-media-download（docs +media-download）：

   lark-cli docs +media-download --token "提取的token" --output ./downloaded_media

Wiki URL 处理策略

知识库链接（/wiki/TOKEN）背后可能是云文档、电子表格、多维表格等不同类型的文档。当不确定类型时，不能直接假设是云文档，必须先查询实际类型。

处理流程

1. 先调用 lark-wiki 解析 wiki token 2. 从返回的 `node` 中获取 `obj_type`（实际文档类型）和 `obj_token`（实际文档 token） 3. 根据 `obj_type` 调用对应工具：

工具组合

参考

• lark-doc-create — 创建文档
• lark-doc-update — 更新文档
• lark-doc-media-download — 下载素材/画板缩略图
• lark-shared — 认证和全局参数

docs +media-download（下载文档素材/画板缩略图）

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

下载文档中的图片/文件素材（file_token），或下载画板缩略图（whiteboard_id）。当 --output 不带扩展名时，会根据响应的 Content-Type 自动补全扩展名。

命令

# 下载图片/文件素材（默认 type=media）
lark-cli docs +media-download --token "Z1Fjxxxxxxxx" --output ./asset

# 指定输出文件名（带扩展名则不会自动补全）
lark-cli docs +media-download --token "Z1Fjxxxxxxxx" --output ./asset.png

# 下载画板缩略图（whiteboard token）
lark-cli docs +media-download --type whiteboard --token "wbcnxxxxxxxx" --output ./whiteboard

参数

token 从哪里来

• 若你是从文档内容里提取：lark-doc-fetch 返回的 Markdown 里可能包含：
• 图片：<image token="..." .../>
• 文件：<file token="..." name="..."/>
• 画板：<whiteboard token="..."/>

参考

• lark-doc-fetch — 获取文档内容（用于提取 token）
• lark-shared — 认证和全局参数

docs +media-insert（文档末尾插入图片/文件）

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

把“创建空 block → 上传文件 → 设置 token”三步合并成一个命令，在文档末尾插入本地图片或文件。

命令

# 插入图片（默认）
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" --file ./image.png

# 如果上一步是 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 --file ./arch.png --align center --caption "架构图"

参数

[!IMPORTANT]

如果上一步是 `lark-doc-create`，并且它在知识库/知识空间场景下返回的是 /wiki/... 形式的 doc_url，后续调用 docs +media-insert 时应优先传 doc_id，不要直接传这个 doc_url。

输出

命令成功后会输出 JSON，包含：document_id、block_id、file_token、file_name、type。

[!CAUTION]

这是写入操作（会修改文档内容）—— 执行前必须确认用户意图。

参考

• lark-doc-fetch — 获取文档内容（可用于确认插入后的结果、以及提取媒体 token）
• lark-shared — 认证和全局参数

docs +search（云空间搜索：文档 / Wiki / 电子表格）

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

基于 Search v2 接口 POST /open-apis/search/v2/doc_wiki/search，以用户身份统一搜索云空间对象。

虽然接口名是 doc_wiki/search，但命中结果不只限于文档 / Wiki，也会返回 SHEET。因此它适合作为云空间对象的资源发现入口：先定位文档、知识库节点、电子表格，以及用户以“表格 / 报表”方式描述的相关对象，再切回对应业务 skill 做对象内部操作。

该 shortcut 会：

• 自动补齐 doc_filter / wiki_filter（API 必填）
• 支持在 filter.open_time / filter.create_time 中使用 ISO 8601 时间，并自动转换为 Unix 秒
• 在返回结果中为 *_time 字段补充 *_time_iso（便于阅读）
• title_highlighted / summary_highlighted 可能包含高亮标签（如 <h> / <hb>）

命令

# 关键词搜索
lark-cli docs +search --query "季度总结"

# 搜标题里带“评测结果”的电子表格 / 文档
lark-cli docs +search --query "评测结果"

# 标题包含关键词（默认按关键词检索，不做精确标题匹配）
lark-cli docs +search --query "方案"

# 按最近打开时间过滤
lark-cli docs +search \
  --query "方案" \
  --filter '{"open_time":{"start":"2025-09-24T00:00:00+08:00","end":"2025-12-24T23:59:59+08:00"}}'

# 空搜（不传 query 或传空字符串）：按最近浏览等默认规则返回
lark-cli docs +search

# 人类可读格式输出
lark-cli docs +search --query "OKR" --format pretty

# 返回原始 JSON，并用 page_token 翻页
lark-cli docs +search --query "方案" --format json
lark-cli docs +search --query "方案" --format json --page-token '<PAGE_TOKEN>'

参数

结果判别

• result_meta.doc_types == SHEET：电子表格，后续切到 lark-sheets
• 其他类型：继续按对应 skill 或 API 处理

决策规则

• 查询语义：默认按关键词搜索理解。用户说“标题为 X”“标题里有 X”“搜索 X 文档”时，先直接返回命中的 OpenAPI 结果；只有用户明确要求“标题精确等于 X”时，才做客户端二次筛选。做精确匹配前，先去掉 title_highlighted 里的高亮标签。
• 入口选择：用户说“找表格标题”“找名为 X 的电子表格”“搜某个报表”时，也默认走 docs +search。不要误用 sheets +find 做跨文件搜索。
• 分页策略：默认只返回第一页，并说明 has_more / page_token。只有当用户明确要求“全部结果”“继续翻页”“全量扫描”“所有结果”“完整列表”时，才继续翻页。
• 翻页上限：即使用户要求全量，单轮也最多先拉 5 页（按默认 page-size=20 约等于最多 100 条结果）。达到上限后，先回报当前进度和是否还有更多页，再让用户决定是否继续下一批。
• 总数口径：total 是 OpenAPI 的搜索结果总数，不一定等于客户端二次筛选后的精确数量。凡是依赖本地过滤、去重、精确标题匹配的场景，都不要默认承诺“精确总数”。
• 原始返回：如果用户要求“直接返回接口数据 / 原始返回”，优先使用 --format json，不要额外做精确标题过滤或摘要重写。
• 时间表达：用户如果说“3 到 6 个月前”“最近半年内”等相对时间，先转换成明确的绝对时间，再写入 filter.open_time / filter.create_time。
• 跨 skill handoff：如果搜索的目标是某个 spreadsheet，返回命中的标题、URL、token 等定位信息后，应切换到 lark-sheets 继续后续操作，不要把 docs +search 当成对象内部查询。

权限

docs +update（更新飞书云文档）

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

更新飞书云文档内容，支持 7 种更新模式。优先使用局部更新（replace_range/append/insert_before/insert_after），慎用 overwrite（会清空文档重写，可能丢失图片、评论等）。

命令

# 追加内容
lark-cli docs +update --doc "<doc_id_or_url>" --mode append --markdown "## 新章节\n\n追加内容"

# 定位替换（内容定位）
lark-cli docs +update --doc "<doc_id>" --mode replace_range --selection-with-ellipsis "旧标题...旧结尾" --markdown "## 新内容"

# 定位替换（标题定位）
lark-cli docs +update --doc "<doc_id>" --mode replace_range --selection-by-title "## 功能说明" --markdown "## 功能说明\n\n新内容"

# 全文替换
lark-cli docs +update --doc "<doc_id>" --mode replace_all --selection-with-ellipsis "张三" --markdown "李四"

# 前插入
lark-cli docs +update --doc "<doc_id>" --mode insert_before --selection-with-ellipsis "## 危险操作" --markdown "> 警告：以下需谨慎！"

# 后插入
lark-cli docs +update --doc "<doc_id>" --mode insert_after --selection-with-ellipsis "代码示例" --markdown "**输出示例**：result = 42"

# 删除内容
lark-cli docs +update --doc "<doc_id>" --mode delete_range --selection-by-title "## 废弃章节"

# 覆盖（慎用）
lark-cli docs +update --doc "<doc_id>" --mode overwrite --markdown "# 全新内容"

# 同时更新标题
lark-cli docs +update --doc "<doc_id>" --mode append --markdown "## 更新日志" --new-title "文档 v2.0"

# 在指定内容后新增两个空白画板
lark-cli docs +update --doc "<doc_id>" --mode insert_after --selection-with-ellipsis "有序列表" --markdown $'<whiteboard type="blank"></whiteboard>\n<whiteboard type="blank"></whiteboard>'

参数

定位方式

定位模式（replace_range/replace_all/insert_before/insert_after/delete_range）支持两种定位方式，二选一：

selection-with-ellipsis - 内容定位

支持两种格式：

1. 范围匹配：开头内容...结尾内容

• 匹配从开头到结尾的所有内容（包含中间内容）
• 建议 10-20 字符确保唯一性

2. 精确匹配：完整内容（不含 ...）

• 匹配完整的文本内容
• 适合替换短文本、关键词等

转义说明：如果要匹配的内容本身包含 ...，使用 \.\.\. 表示字面量的三个点。

示例：

• 你好...世界 → 匹配从"你好"到"世界"之间的任意内容
• 你好\.\.\.世界 → 匹配字面量 "你好...世界"

建议：如果文档中有多个 ...，建议使用更长的上下文来精确定位，避免歧义。

selection-by-title - 标题定位

格式：## 章节标题（可带或不带 # 前缀）

自动定位整个章节（从该标题到下一个同级或更高级标题之前）。

示例：

• ## 功能说明 → 定位二级标题"功能说明"及其下所有内容
• 功能说明 → 定位任意级别的"功能说明"标题及其内容

可选参数

new-title

更新文档标题。如果提供此参数，将在更新文档内容后同步更新文档标题。

特性：

• 仅支持纯文本，不支持富文本格式
• 长度限制：1-800 字符
• 可以与任何 mode 配合使用
• 标题更新在内容更新之后执行

返回值

成功

{
  "success": true,
  "doc_id": "文档ID",
  "mode": "使用的模式",
  "board_tokens": ["可选：新建画板 token 列表"],
  "message": "文档更新成功（xxx模式）",
  "warnings": ["可选警告列表"],
  "log_id": "请求日志ID"
}

如果本次 docs +update 创建了画板，响应会额外返回 board_tokens。在 CLI 的成功 JSON 输出里，后续编辑画板应读取 data.board_tokens。

异步模式（大文档超时）

{
  "task_id": "async_task_xxxx",
  "message": "文档更新已提交异步处理，请使用 task_id 查询状态",
  "log_id": "请求日志ID"
}

错误

{
  "error": "[错误码] 错误消息\n💡 Suggestion: 修复建议\n📍 Context: 上下文信息",
  "log_id": "请求日志ID"
}

---

使用示例

append - 追加到末尾

lark-cli docs +update --doc "文档ID或URL" --mode append --markdown "## 新章节\n\n追加的内容..."

replace_range - 定位替换

使用 --selection-with-ellipsis：

lark-cli docs +update --doc "文档ID" --mode replace_range --selection-with-ellipsis "## 旧标题...旧结尾。" --markdown "## 新标题\n\n新的内容..."

使用 --selection-by-title（替换整个章节）：

lark-cli docs +update --doc "文档ID" --mode replace_range --selection-by-title "## 功能说明" --markdown "## 功能说明\n\n更新后的内容..."

replace_all - 全文替换

lark-cli docs +update --doc "文档ID" --mode replace_all --selection-with-ellipsis "张三" --markdown "李四"

返回值包含 replace_count 字段，表示替换的次数。

注意：

• 与 replace_range 不同，replace_all 允许多个匹配
• 如果没有找到匹配内容，会返回错误
• --markdown 可以为空字符串，表示删除所有匹配内容

delete_range - 删除内容

lark-cli docs +update --doc "文档ID" --mode delete_range --selection-by-title "## 废弃章节"

注意：delete_range 模式不需要 --markdown 参数。

overwrite - 完全覆盖

⚠️ 会清空文档后重写，可能丢失图片、评论等，仅在需要完全重建文档时使用。

lark-cli docs +update --doc "文档ID" --mode overwrite --markdown "# 新文档\n\n全新的内容..."

创建空白画板

当用户要“新增空白画板”时，不要用 Mermaid 占位图；直接按 whiteboard 标签传 --markdown。

自然语言请求示例：

• “给我在这个文档末尾新增一个空白画板”

# 追加一个空白画板
lark-cli docs +update --doc "文档ID" --mode append --markdown '<whiteboard type="blank"></whiteboard>'

# 在指定内容后新增两个空白画板
lark-cli docs +update --doc "文档ID" --mode insert_after --selection-with-ellipsis "有序列表" --markdown $'<whiteboard type="blank"></whiteboard>\n<whiteboard type="blank"></whiteboard>'

成功后，响应里的 data.board_tokens 就是新建画板的 token 列表；如果后续要继续编辑这些画板，直接使用这些 token。

---

最佳实践

重要：画板编辑

⚠️ docs +update 不能编辑已有画板内容，但可以创建新的空白画板

画板编辑：详见 SKILL.md

小粒度精确替换

修改文档内容时，定位范围越小越安全。尤其是表格、分栏等嵌套块，应精确定位到需要修改的文本，避免影响其他内容。

保护不可重建的内容

图片、画板、电子表格、多维表格、任务等内容以 token 形式存储，无法读出后原样写入。

保护策略：

• 替换时避开包含这些内容的区域
• 精确定位到纯文本部分进行修改

分步更新优于整体覆盖

修改多处内容时：

• ✅ 多次小范围替换，逐步修改
• ⚠️ 谨慎使用 overwrite 重写整个文档，除非你认为风险完全可控

原因：局部更新保留原有媒体、评论、协作历史，更安全可靠。

insert 模式扩大定位范围时注意插入位置

使用 insert_before 或 insert_after 时，如果目标内容重复出现，需要扩大 --selection-with-ellipsis 范围来唯一定位。

关键：插入位置基于匹配范围的边界：

• insert_after → 插入在匹配范围的结尾之后
• insert_before → 插入在匹配范围的开头之前

修复画板语法错误

当 docs +create 或 docs +update 返回画板写入失败的 warning 时： 1. warning 中包含 whiteboard 标签（如 <whiteboard token="xxx"/>） 2. 分析错误信息，修正 Mermaid/PlantUML 语法 3. 用 --mode replace_range 替换：--selection-with-ellipsis 使用 warning 中的 whiteboard 标签，--markdown 提供修正后的代码块 4. 重新提交验证

---

注意事项

• Markdown 语法：支持飞书扩展语法，详见 lark-doc-create 工具文档

参考

• lark-doc-fetch — 获取文档
• lark-doc-create — 创建文档（含完整 Markdown 格式参考）
• lark-doc-media-insert — 插入图片/文件到文档
• lark-shared — 认证和全局参数

docs +whiteboard-update（更新飞书画板）

前置条件： 先阅读 `../lark-shared/SKILL.md` 了解认证、全局参数和安全规则。

更新飞书云文档中的画板内容。这个操作需要提供画板的 Token 和画板的 DSL 内容，并需要使用 whiteboard-cli 工具解析 DSL 内容，并通过管道传入这个命令。 关于如何设计画板内容，以及如何使用 whiteboard-cli，参考 `../lark-whiteboard/SKILL.md`。

参数

示例

此处不提供示例调用，请参考 `../lark-whiteboard/SKILL.md` 了解完整的使用流程。