lark-doc
larksuite/cli
Read and edit Lark/Feishu Docx & Wiki documents via CLI — fetch, create, update, and manage media attachments.
What is lark-doc?
lark-doc enables AI agents to interact with Lark (Feishu) cloud documents (Docx and Wiki format). It supports fetching document content, creating new documents, editing existing content with precise block-level operations, and managing media attachments and cover images. Routing is based on URL path patterns (/docx/ or /wiki/) and tokens, not domain names, so it also handles doubao.com document URLs. It does not handle document comments, spreadsheet data, or Base (multi-dimensional table) data operations.
- Fetch Lark Docx/Wiki document content in XML, Markdown, or im-markdown format with configurable scope and detail levels
- Create new Lark documents from XML or Markdown content
- Update existing documents using str_replace, block insert/replace/delete/move, append, or overwrite commands
- Insert local images or clipboard screenshots into documents with auto-rollback on failure
- Download or preview document media files and whiteboard thumbnails
- Download, update, or delete Docx cover image resources
How to install lark-doc
npx skills add null --skill lark-doc- lark-cli must be installed and available in PATH
- User must run `lark-cli auth login` before first use
- lark-shared SKILL.md must be readable for auth and global parameter handling
- Reference files (lark-doc-fetch.md, lark-doc-xml.md, lark-doc-update.md, etc.) must be accessible for the agent to read before executing operations
How to use lark-doc
- 1.Run `lark-cli auth login` to authenticate if not already done
- 2.To read a document: `lark-cli docs +fetch --doc "<URL or token>"`
- 3.To create a document: `lark-cli docs +create --content '<title>Title</title><p>Body</p>'`
- 4.To append content: `lark-cli docs +update --doc "<URL or token>" --command append --content '<p>Text</p>'`
- 5.To replace specific text: use `--command str_replace` with old and new text values
- 6.To insert an image from clipboard: `lark-cli docs +media-insert --from-clipboard --doc "<URL or token>"`
- 7.To download a cover image: `lark-cli docs +resource-download --type cover --doc "<URL or token>"`
- 8.For embedded spreadsheets or bitables found in fetched content, extract the token and switch to lark-sheets or lark-base skill
Use cases
- Read a Feishu or doubao.com document by URL or token and summarize its contents
- Create a structured Lark document with rich blocks (callouts, grids, checkboxes) from scratch
- Replace specific text or blocks in an existing document without rewriting the whole file
- Insert a screenshot or local image file into a Lark document
- Extract embedded spreadsheet or bitable tokens from a document and hand off to lark-sheets or lark-base
- Developers automating Lark document workflows via AI agents
- Teams using Claude Code or Cursor to draft, update, or summarize Feishu documents
- Users who need to programmatically manage Lark Docx/Wiki content including media attachments
- Agents routing document tasks that originate from doubao.com /docx/ or /wiki/ URLs
lark-doc FAQ
Yes. Routing is based on URL path pattern (/docx/ or /wiki/) and token, not domain name, so doubao.com /docx/ and /wiki/ URLs are handled by lark-doc.
Yes for create and full-section append/overwrite. XML is the default and supports richer blocks (callout, grid, checkbox). Use Markdown only when the user provides a .md file or explicitly requests it. For precise block-level edits, always use XML.
Use lark-doc to fetch the document and extract the token from the embedded <sheet> or <bitable> tag, then switch to lark-sheets or lark-base skill for data operations.
No. Comment management (add, view, reply, reactions) is handled by the lark-drive skill.
Use `lark-cli docs +media-insert --from-clipboard --doc "<URL or token>"`. Use --file only for images already saved to disk.
Full instructions (SKILL.md)
Source of truth, from larksuite/cli.
name: lark-doc version: 2.0.0 description: "飞书云文档（Docx / Wiki 文档）：读取和编辑飞书文档内容。当用户给出文档 URL 或 token，或需要查看、创建、编辑文档、插入或下载文档图片附件时使用。文档中嵌入的电子表格、多维表格、画板，先用本 skill 提取 token 再切到对应 skill。当用户给出 doubao.com 的 /docx/ 或 /wiki/ URL/token 时，也应直接使用本 skill；路由依据是 URL 路径模式和 token，而不是域名。不负责文档评论管理，也不负责表格或 Base 的数据操作。" metadata: requires: bins: ["lark-cli"] cliHelp: "lark-cli docs --help; lark-cli docs +create --help; lark-cli docs +fetch --help; lark-cli docs +update --help; lark-cli docs +resource-download --help; lark-cli docs +resource-update --help; lark-cli docs +resource-delete --help"
docs
身份：文档操作默认使用 --as user。首次使用前执行 lark-cli auth login。
# 常用示例
lark-cli docs +fetch --doc "文档URL或token"
lark-cli docs +create --content '<title>标题</title><p>内容</p>'
lark-cli docs +update --doc "文档URL或token" --command append --content '<p>内容</p>'
前置条件 — 执行操作前必读
CRITICAL — 执行对应操作前，MUST 先用 Read 工具读取以下文件，缺一不可：
../lark-shared/SKILL.md— 认证、权限处理、全局参数（所有操作通用）- 读取文档（
docs +fetch） → 必读lark-doc-fetch.md（--scope/--detail选择、局部读取策略、<fragment>/<excerpt>输出结构） - 创建或编辑文档内容 → 必读
lark-doc-xml.md（XML 语法规则，仅当用户明确要求 Markdown 时改读lark-doc-md.md）和lark-doc-style.md（元素选择、丰富度规则、颜色语义）；从零创建时加读lark-doc-create-workflow.md；编辑已有文档时加读lark-doc-update.md和lark-doc-update-workflow.md
未读完以上文件就执行相应操作会导致参数选择错误或格式错误。
格式选择规则（全局）：
- 创建 / 导入场景（
docs +create，或docs +update --command append/overwrite的整段写入）：XML 和 Markdown 都可以。用户提供.md本地文件、或明确说"导入 Markdown"时，直接用 Markdown；否则默认 XML（可用 callout、grid、checkbox 等富 block）。- 精准编辑场景（
docs +update的str_replace/block_insert_after/block_replace/block_delete/block_move_after等局部精修指令）：优先使用 XML（--doc-format xml，即默认值）。XML 能稳定表达 block 结构和样式，局部精修更可控；不要因为 Markdown 更简单就自行切换。
快速决策
- 先判定任务路径：找文档 / 导入导出走
lark-drive；只读 / 摘要用docs +fetch默认simple；明确旧文本 → 新文本直接str_replace；只有 block 链接、评论锚点、插入 / 替换 / 删除 / 移动才局部 fetchwith-ids；保真改写已有内容才读full - block 直达链接格式：
文档基础 URL#block_id；没有 block_id 时局部 fetchwith-ids - 连续执行多个文档写操作时，必须按
lark-doc-update.md的「Block ID 生命周期」判断旧 block ID 是否还能复用；overwrite/block_replace/block_delete后不要复用受影响的旧 ID，插入 / 复制后要重新 fetch 才能拿到新 block ID - 用户需要在文档内创建、复制或移动资源块（画板、电子表格、多维表格等）时，必须先读取
lark-doc-xml.md的「三、资源块」章节 - 写文档时，由内容和用户意图决定表达形式；流程、架构、路线图、关键指标等信息可以使用画板，但不要默认把重要信息都画板化
- 新增画板必须隔离到 SubAgent：简单图由 SubAgent 直接插入
<whiteboard type="svg">完整 SVG</whiteboard>，不读lark-whiteboard；复杂图才由主 Agent 先建<whiteboard type="blank"></whiteboard>，再启动 SubAgent 读取lark-whiteboard写入 - 用户说"看一下文档里的图片/附件/素材""预览素材" → 用
lark-cli docs +media-preview - 用户明确说"下载素材" → 用
lark-cli docs +media-download - 用户明确说"下载/更新/删除文档封面图" → 用
lark-cli docs +resource-download/+resource-update/+resource-delete --type cover resource-*目前仅支持 Docx 封面资源；其他图片、附件或素材请走+media-*- 如果目标是画板/whiteboard/画板缩略图 → 只能用
lark-cli docs +media-download --type whiteboard（不要用+media-preview） - 拿到 spreadsheet URL/token 后 → 切到
lark-sheets做对象内部操作 - 用户说"给文档加评论""查看评论""回复评论""给评论加/删除表情 reaction" → 切到
lark-drive处理 - 文档内容中出现嵌入的
<sheet>、<bitable>或<cite file-type="sheets|bitable">标签时 → 必须主动提取 token 并切到对应技能下钻读取内部数据，不能只呈现标签本身
| 标签 / 属性 | 提取字段 | 切到技能 |
|---|---|---|
<sheet token="..." sheet-id="..."> | token -> spreadsheet_token, sheet-id | lark-sheets |
<bitable token="..." table-id="..."> | token -> app_token, table-id | lark-base |
<cite type="doc" file-type="sheets" token="..." sheet-id="..."> | 同 <sheet> | lark-sheets |
<cite type="doc" file-type="bitable" token="..." table-id="..."> | 同 <bitable> | lark-base |
<vc-transcribe-tab vc-node-id="..."> | vc-node-id -> note_id | lark-note：先 note +detail --note-id <vc-node-id> |
<synced_reference src-token="..." src-block-id="..."> | src-token -> doc_token, src-block-id -> block_id | 用 docs +fetch 读取 src-token 文档，定位 block |
Shortcuts（推荐优先使用）
Shortcut 是对常用操作的高级封装（lark-cli docs +<verb> [flags]）。有 Shortcut 的操作优先使用。
| Shortcut | 说明 |
|---|---|
+create | Create a Lark document (XML / Markdown) |
+fetch | Fetch Lark document content (XML / Markdown / im-markdown; im-markdown only after fetch for lark-im) |
+update | Update a Lark document (str_replace / block_insert_after / block_replace / ...) |
+media-insert | Insert a local image or file at the end of a Lark document (4-step orchestration + auto-rollback). Prefer --from-clipboard when the image is already on the system clipboard (screenshots, copy from Feishu/browser); use --file only for on-disk sources. |
+media-download | Download document media or whiteboard thumbnail (auto-detects extension) |
+media-preview | Preview document media file (auto-detects extension) |
+resource-download / +resource-update / +resource-delete | Download, update, or delete a Docx cover image resource with --type cover |
+whiteboard-update | Alias of whiteboard +update. Update an existing whiteboard with DSL, Mermaid or PlantUML. Prefer whiteboard +update; refer to lark-whiteboard skill for details. |
不在本 Skill 范围
- 文档评论管理 →
lark-drive - 电子表格或 Base 的数据操作 →
lark-sheets/lark-base - 云空间文件上传、下载、权限管理 →
lark-drive
Related skills
More from larksuite/cli and the wider catalog.
lark-base
飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、workflow、角色权限；遇到 Base/多维表格/bitable 或 /base/ 链接时使用。文件导入转 lark-drive，认证/授权转 lark-shared。
lark-im
飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件（支持大文件分片下载）、管理表情回复、发送应用内/短信/电话加急、发送和处理交互卡片（Interactive Card）、监听卡片按钮回调（card.action.trigger）。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 Feed 置顶（添加/移除/查询置顶会话）、管理标签数据、处理卡片回调时使用。
lark-drive
飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、评论/权限/订阅、标题、版本和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。
lark-shared
Use for lark-cli setup/auth tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, or handling _notice JSON.
lark-calendar
飞书日历：管理日历日程和会议室。查看/搜索日程、创建/更新日程、管理参会人、查询忙闲和推荐时段、预定会议室。当用户需要查看日程安排、创建/修改会议、查询/预定会议室时使用。不负责：查询过去的视频会议记录（走 lark-vc）、待办任务（走 lark-task）。
lark-wiki
飞书知识库：管理知识空间、空间成员和文档节点。创建和查询知识空间、查看和管理空间成员、管理节点层级结构、在知识库中组织文档和快捷方式。当用户需要在知识库中查找或创建文档、浏览知识空间结构、查看或管理空间成员、移动或复制节点时使用。当用户给出 doubao.com 的 /wiki/ URL/token 时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是 URL 路径模式和 token，而不是域名。不负责：上传文件到知识库节点下（走 lark-drive）、编辑文档/表格/Base 内容（走 lark-doc / lark-sheets / lark-base）。