Feishu CLI → 云文档操作

Feishu CLI 云文档操作

通过命令行或 AI Agent 自动化，使用飞书风格的 Markdown 创建、读取、更新和搜索云文档。支持插入媒体、管理白板和下载资源。

概述

在终端中管理云文档

Feishu CLI 文档模块提供 6 个快捷命令，实现全面的云文档控制。每个快捷命令都直接映射到飞书开放平台文档 API 的 MCP 工具调用，让您拥有对飞书/Lark 文档的完整编程访问能力。

核心能力包括：

  • 基于 Markdown 的完整创建能力 — 使用飞书风格的 Markdown 创建富文档，支持高亮提示框、网格布局、表格、图片等
  • 7 种更新模式 — 追加、覆盖、替换范围、全部替换、前插、后插、删除范围
  • 媒体编排 — 4 步插入流水线，失败时自动回滚
  • 白板操作 — 通过 DSL 创建和更新白板，支持架构图、流程图和思维导图
  • 跨模块搜索 — 统一搜索文档、知识库和电子表格
创建文档

+create — 创建飞书文档

使用飞书风格的 Markdown 内容创建新的云文档。文档默认创建在用户的根文件夹中，也可以指定目标文件夹、知识库节点或知识空间。--folder-token、--wiki-node 和 --wiki-space 参数互斥。

# 在根文件夹创建简单文档 $ lark-cli docs +create --title "Weekly Report" --markdown "## Sprint 42\n### Highlights\n- Completed auth module\n- Deployed v2.1"
# 在指定文件夹中创建 $ lark-cli docs +create --title "Design Doc" --folder-token "fldcnXXXX" --markdown "## Architecture\n\n### Overview\nMicroservices-based design..."
# 在知识空间中创建 $ lark-cli docs +create --title "API Reference" --wiki-space "7000000000000000000" --markdown "## Endpoints\n\n### GET /users\nReturns a list of users."
# 在指定知识库节点下创建 $ lark-cli docs +create --title "Onboarding Guide" --wiki-node "wikcnXXXX" --markdown "## Welcome\n\nThis guide covers setup and configuration."
# 在个人知识库中创建 $ lark-cli docs +create --title "Study Notes" --wiki-space my_library --markdown "## Notes\n\n- Key takeaway 1\n- Key takeaway 2"

参数说明

参数必填说明
--markdown是文档正文的飞书风格 Markdown 内容
--title否文档标题（不要在 markdown 中重复作为 H1）
--folder-token否父文件夹 token（与 wiki 参数互斥）
--wiki-node否要创建到的知识库节点 token
--wiki-space否知识空间 ID；使用 my_library 表示个人知识库

返回值：doc_id（文档 token）、doc_url（浏览器链接）和 message（状态信息）。在知识库中创建时，URL 可能为 /wiki/... 格式 — 后续 API 调用请使用 doc_id。

权限范围：docx:document:create

身份：用户或机器人。使用机器人身份时，创建后需授予用户 full_access 权限。

读取文档

+fetch — 获取文档内容

通过 URL 或 token 获取飞书文档的内容。支持使用 --offset 和 --limit 对大文档进行分页。

# 获取整个文档 $ lark-cli docs +fetch --doc "docxXXXXXXXXXX"
# 分页获取（前 50 个块） $ lark-cli docs +fetch --doc "docxXXXXXXXXXX" --offset 0 --limit 50
# 通过文档 URL 获取 $ lark-cli docs +fetch --doc "https://example.feishu.cn/docx/docxXXXXXXXXXX"
参数必填说明
--doc是文档 URL 或 token
--offset否分页偏移量
--limit否分页限制（返回的块数量）

权限范围：docx:document:readonly

更新文档

+update — 更新飞书文档（7 种模式）

使用 7 种更新模式之一更新现有文档。每种模式服务于不同的编辑场景，从追加内容到精确文本替换。--selection-with-ellipsis 和 --selection-by-title 定位器互斥。

追加模式

# 在文档末尾追加新内容 $ lark-cli docs +update --doc "docxXXX" --mode append --markdown "## New Section\n\nAdditional content appended here."

覆盖模式

# 替换整个文档正文 $ lark-cli docs +update --doc "docxXXX" --mode overwrite --markdown "# Complete Replacement\n\nAll previous content is gone."

替换范围模式

# 替换通过起止文本标识的特定区域 $ lark-cli docs +update --doc "docxXXX" --mode replace_range --selection-with-ellipsis "old paragraph text...surrounding context" --markdown "Updated paragraph content"

全部替换模式

# 替换所有匹配的文本 $ lark-cli docs +update --doc "docxXXX" --mode replace_all --selection-with-ellipsis "v1.0..." --markdown "v2.0"

前插 / 后插模式

# 在通过标题标识的章节前插入内容 $ lark-cli docs +update --doc "docxXXX" --mode insert_before --selection-by-title "## Section 3" --markdown "## Section 2.5\n\nInserted before Section 3."
# 在章节后插入内容 $ lark-cli docs +update --doc "docxXXX" --mode insert_after --selection-by-title "## Conclusion" --markdown "## Appendix\n\nSupplementary data."

删除范围模式

# 删除特定文本范围（不需要 --markdown） $ lark-cli docs +update --doc "docxXXX" --mode delete_range --selection-with-ellipsis "obsolete paragraph...end marker"

重命名文档

# 更新文档标题（可与任何模式组合使用） $ lark-cli docs +update --doc "docxXXX" --mode append --markdown " " --new-title "Updated Document Title"

全部更新参数

参数必填说明
--doc是文档 URL 或 token
--mode是append | overwrite | replace_range | replace_all | insert_before | insert_after | delete_range
--markdown是*飞书风格 Markdown 新内容（* delete_range 模式不需要）
--selection-with-ellipsis条件必填使用 start...end 模式的内容定位器（范围/替换/插入/删除模式需要）
--selection-by-title条件必填标题定位器，如 ## Section Name（与省略号选择器二选一）
--new-title否同时更新文档标题

权限范围：docx:document:write_only、docx:document:readonly

搜索内容

+search — 搜索文档、知识库与电子表格

使用搜索 v2 API（POST /open-apis/search/v2/doc_wiki/search）统一搜索云文档、知识库页面和电子表格。尽管端点名称只提到文档和知识库，搜索结果也包括电子表格（SHEET 类型）。可将此命令作为资源发现的入口，然后切换到特定领域的命令。

# 按关键词搜索文档 $ lark-cli docs +search --query "quarterly report"
# 带时间筛选的搜索 $ lark-cli docs +search --query "product roadmap" --filter '{"open_time":{"start":"2026-01-01T00:00:00+08:00","end":"2026-03-30T23:59:59+08:00"}}'
# 空搜索（返回最近浏览的文档） $ lark-cli docs +search
# 分页浏览结果 $ lark-cli docs +search --query "OKR" --page-token "next_page_token" --page-size 20
参数必填说明
--query否搜索关键词（为空时返回最近文档）
--filter否用于类型/所有者/时间条件的 JSON 筛选器
--page-size否每页结果数（默认 15，最大 20）
--page-token否下一页的分页 token

权限范围：search:docs:read。身份：仅限用户（机器人身份无法执行搜索）。

插入媒体

+media-insert — 插入图片与文件（4 步编排）

在文档末尾插入本地图片或文件。此命令执行 4 步流水线，失败时自动回滚：(1) 查询文档根块，(2) 创建占位块，(3) 上传文件，(4) 将上传的文件 token 绑定到块。对于知识库 URL，会先执行第 5 步将知识库节点解析为实际的 docx token。

最大文件大小：20 MB。支持 PNG、JPG、GIF、WebP、BMP 图片和通用文件附件。

# 插入居中对齐的带说明图片 $ lark-cli docs +media-insert --file ./diagram.png --doc "docxXXXXXX" --align center --caption "Architecture diagram"
# 插入文件附件 $ lark-cli docs +media-insert --file ./report.pdf --doc "docxXXXXXX" --type file
# 向知识库页面插入图片（自动解析知识库 token） $ lark-cli docs +media-insert --file ./screenshot.png --doc "https://example.feishu.cn/wiki/wikiXXXXXX"
参数必填说明
--file是本地文件路径（最大 20 MB）
--doc是文档 URL 或 document_id（仅 docx）
--type否image（默认）或 file
--align否left、center 或 right
--caption否图片说明文字

权限范围：docs:document.media:upload、docx:document:write_only、docx:document:readonly

下载媒体

+media-download — 下载文档媒体

从文档中下载媒体文件或白板缩略图。扩展名根据内容类型自动检测（PNG、JPG、GIF、WebP、SVG、PDF、MP4、TXT）。

# 从文档下载媒体文件 $ lark-cli docs +media-download --token "boxXXXXXX" --output ./downloaded-image.png
# 将白板下载为图片 $ lark-cli docs +media-download --token "wbXXXXXX" --output ./whiteboard.png --type whiteboard
# 覆盖已有的输出文件 $ lark-cli docs +media-download --token "boxXXXXXX" --output ./image.png --overwrite
参数必填说明
--token是资源 token（file_token 或 whiteboard_id）
--output是本地保存路径
--type否media（默认）或 whiteboard
--overwrite否覆盖已有的输出文件（布尔值）

权限范围：docs:document.media:download

白板操作

创建与更新白板

飞书文档中的白板可以通过 +create 或 +update 命令使用特殊的 Markdown 语法内联创建。要更新白板内容，请使用 whiteboard-cli 工具解析 DSL 内容并通过管道传输到更新命令。

创建空白白板

# 创建带空白白板的文档 $ lark-cli docs +create --title "Whiteboard Doc" --markdown '<whiteboard type="blank"></whiteboard>'
# 创建带多个白板的文档 $ lark-cli docs +create --title "Design Boards" --markdown '## Board 1\n<whiteboard type="blank"></whiteboard>\n## Board 2\n<whiteboard type="blank"></whiteboard>'

更新白板内容

# 通过标准输入使用 DSL 更新白板 $ whiteboard-cli render architecture.dsl | lark-cli docs +whiteboard-update --whiteboard-token "wbXXXXXX"
# 覆盖已有白板内容 $ whiteboard-cli render flowchart.dsl | lark-cli docs +whiteboard-update --whiteboard-token "wbXXXXXX" --overwrite
参数必填说明
--whiteboard-token是白板 token（需要对父文档的编辑权限）
--idempotent-token否幂等性 token（最少 10 个字符）
--overwrite否更新前删除所有已有内容（默认 false）

支持的图表类型包括架构图、流程图、组织架构图、思维导图以及 Mermaid/PlantUML 图表（自动转换为飞书白板格式）。

知识库集成

处理知识库 URL

飞书中的知识库页面使用与普通文档不同的 URL 格式（feishu.cn/wiki/XXXXX）。在处理知识库内容时，需要先将知识库 token 解析为实际的文档 token。

+media-insert 命令会自动处理此过程（5 步编排）。对于其他命令，需要手动解析：

# 解析知识库 URL 以获取实际文档 token $ lark-cli wiki spaces get_node --token "wikiXXXXXX"
# 然后使用解析后的 docx token 进行操作 $ lark-cli docs +fetch --doc "docxYYYYYY"

+create 命令支持通过 --wiki-node 或 --wiki-space 直接在知识库中创建文档，因此仅在对已有知识库页面进行读取/更新操作时才需要解析。

权限

所需 OAuth 权限范围

操作权限范围
创建文档docx:document:create
读取文档docx:document:readonly
更新文档docx:document:write_only、docx:document:readonly
搜索文档search:docs:read
上传媒体docs:document.media:upload
下载媒体docs:document.media:download
命令参考

全部文档快捷命令

命令说明风险等级身份关键参数
+create使用 Markdown 创建飞书文档写入用户、机器人--title, --markdown, --folder-token, --wiki-space, --wiki-node
+fetch获取文档内容读取用户、机器人--doc, --offset, --limit
+update更新文档（7 种模式）写入用户、机器人--doc, --mode, --markdown, --selection-with-ellipsis, --selection-by-title, --new-title
+search搜索文档、知识库和电子表格读取仅限用户--query, --filter, --page-size, --page-token
+media-insert向文档插入本地图片/文件写入用户、机器人--file, --doc, --type, --align, --caption
+media-download下载文档媒体或白板读取用户、机器人--token, --output, --type, --overwrite
继续阅读

相关 Feishu CLI 指南

多维表格

60 个快捷命令，管理多维表格、记录、字段、视图、仪表盘和工作流。

消息命令

发送消息、管理群聊、搜索对话、回复话题和下载媒体。

邮件命令

通过命令行发送和管理飞书邮箱，支持完整的邮箱访问。

AI Agent 技能

19 个预置 AI 技能，使用自然语言自动化办公流程。