feishu-cli-write

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

飞书文档写入技能

Feishu Docs Writing Skill

创建或更新飞书云文档，通过 Markdown 作为中间格式。支持 Mermaid/PlantUML 图表自动转飞书画板。

前置条件：使用前需先完成认证：
feishu-cli auth login
（OAuth 登录，建议包含
offline_access
scope 以获取 30 天有效的 Refresh Token）。

Create or update Feishu Cloud Docs using Markdown as the intermediate format. Supports automatic conversion of Mermaid/PlantUML diagrams to Feishu Boards.

Prerequisite: Complete authentication before use:
feishu-cli auth login
(OAuth login, it is recommended to include the
offline_access
scope to obtain a 30-day valid Refresh Token).

快速创建空白文档

Quick Creation of Blank Document

最简方式创建一个新的飞书云文档：

bash

feishu-cli doc create --title "文档标题" --output json

创建后必须立即：

授予

full_access

权限：

bash

feishu-cli perm add <document_id> --doc-type docx --member-type email --member-id user@example.com --perm full_access --notification

转移文档所有权：

bash

feishu-cli perm transfer-owner <document_id> --doc-type docx --member-type email --member-id user@example.com --notification

发送飞书消息通知用户文档已创建

The simplest way to create a new Feishu Cloud Document:

bash

feishu-cli doc create --title "Document Title" --output json

After creation, you must immediately:

Grant

full_access

permission:

bash

feishu-cli perm add <document_id> --doc-type docx --member-type email --member-id user@example.com --perm full_access --notification

Transfer document ownership:

bash

feishu-cli perm transfer-owner <document_id> --doc-type docx --member-type email --member-id user@example.com --notification

Send a Feishu message to notify the user that the document has been created

核心概念

Core Concepts

Markdown 作为中间态：本地文档与飞书云文档之间通过 Markdown 格式进行转换，中间文件存储在

/tmp

目录中。

CRITICAL: 禁止对已有文档全量覆盖
绝对禁止对已有文档使用
doc import --document-id <id>
全量覆盖！这会：
丢失所有划词评论（inline comments）

破坏画板/白板引用（变成空占位块）

丢失用户手动编辑的格式和内容
更新已有文档必须使用增量方式：
doc add
（追加）、
doc update
（修改块）、
doc delete
（删除块）。
doc import --document-id
仅允许在用户明确要求全量替换时使用。

Markdown as Intermediate Format: Conversion between local documents and Feishu Cloud Documents is done via Markdown format, with intermediate files stored in the

/tmp

directory.

CRITICAL: Full overwrite of existing documents is PROHIBITED
Absolutely forbidden to use
doc import --document-id <id>
to fully overwrite existing documents! This will:
Lose all inline comments

Break board/whiteboard references (become empty placeholder blocks)

Lose manually edited formats and content from users
Incremental updates must be used for updating existing documents:
doc add
(append),
doc update
(modify blocks),
doc delete
(delete blocks).
doc import --document-id
is only allowed when the user explicitly requests full replacement.

使用方法

Usage

bash

undefined

bash

undefined

创建新文档

Create new document

/feishu-write "文档标题"

/feishu-write "Document Title"

更新已有文档

Update existing document

/feishu-write <document_id>

undefined

/feishu-write <document_id>

undefined

执行流程

Execution Flow

创建新文档

Create New Document

收集内容
- 与用户确认文档标题
- 收集用户提供的内容或根据对话生成内容
生成 Markdown
- 在
```
/tmp/feishu_write_<timestamp>.md
```
  创建 Markdown 文件
- 使用标准 Markdown 语法

导入到飞书

bash

feishu-cli doc import /tmp/feishu_write_<timestamp>.md --title "文档标题"

添加权限（可选，给指定用户添加 full_access）
```
full_access
```
是最高权限，包含：管理协作者、编辑内容、管理文档设置（复制/移动/删除）、查看历史版本、导出等全部能力。
bash
```
feishu-cli perm add <document_id> --doc-type docx --member-type email --member-id user@example.com --perm full_access
```
通知用户
- 提供文档链接
- 发送飞书消息通知

Collect Content
- Confirm the document title with the user
- Collect content provided by the user or generate content based on the conversation
Generate Markdown
- Create a Markdown file at
```
/tmp/feishu_write_<timestamp>.md
```
- Use standard Markdown syntax

Import to Feishu

bash

feishu-cli doc import /tmp/feishu_write_<timestamp>.md --title "Document Title"

Add Permissions (optional, grant full_access to specified users)
```
full_access
```
is the highest permission, including: managing collaborators, editing content, managing document settings (copy/move/delete), viewing historical versions, exporting, and all other capabilities.
bash
```
feishu-cli perm add <document_id> --doc-type docx --member-type email --member-id user@example.com --perm full_access
```
Notify User
- Provide the document link
- Send a Feishu message notification

更新已有文档（增量更新）

Update Existing Document (Incremental Update)

原则：只修改需要变更的部分，保留其余内容不动。

Principle: Only modify the parts that need to be changed, leaving the rest of the content intact.

场景 A：在文档末尾追加内容

Scenario A: Append Content to the End of the Document

最常见的场景。直接用

doc add

以 Markdown 格式追加：

bash

undefined

The most common scenario. Directly use

doc add

to append in Markdown format:

bash

undefined

1. 准备要追加的内容（只写新增部分，不要包含已有内容）

1. Prepare the content to append (only write the new part, do not include existing content)

cat > /tmp/feishu_append.md << 'EOF'

新增章节标题

New Section Title

新增的内容... EOF

New content... EOF

2. 追加到文档末尾

2. Append to the end of the document

feishu-cli doc add <document_id> /tmp/feishu_append.md --content-type markdown

undefined

feishu-cli doc add <document_id> /tmp/feishu_append.md --content-type markdown

undefined

场景 B：在文档指定位置插入内容

Scenario B: Insert Content at a Specified Position in the Document

bash

undefined

bash

undefined

1. 获取文档块结构，找到插入点

1. Get the document block structure and find the insertion point

feishu-cli doc blocks <document_id>

2. 在指定父块的指定位置插入

2. Insert at the specified position under the parent block

feishu-cli doc add <document_id> /tmp/feishu_insert.md
--content-type markdown
--block-id <parent_block_id>
--index <position>

undefined

feishu-cli doc add <document_id> /tmp/feishu_insert.md
--content-type markdown
--block-id <parent_block_id>
--index <position>

undefined

场景 C：修改已有块的内容

Scenario C: Modify Content of an Existing Block

bash

undefined

bash

undefined

1. 获取文档块结构，找到要修改的 block_id

1. Get the document block structure and find the block_id to modify

feishu-cli doc blocks <document_id>

2. 更新指定块

2. Update the specified block

feishu-cli doc update <document_id> <block_id>
--content '{"update_text_elements":{"elements":[{"text_run":{"content":"更新后的文本"}}]}}'

undefined

feishu-cli doc update <document_id> <block_id>
--content '{"update_text_elements":{"elements":[{"text_run":{"content":"Updated text"}}]}}'

undefined

场景 D：删除指定范围的块

Scenario D: Delete Blocks in a Specified Range

bash

undefined

bash

undefined

删除父块下索引 2~4 的子块

Delete child blocks from index 2~4 under the parent block

feishu-cli doc delete <document_id> <parent_block_id> --start 2 --end 5

删除父块下所有子块

Delete all child blocks under the parent block

feishu-cli doc delete <document_id> <parent_block_id> --all

undefined

feishu-cli doc delete <document_id> <parent_block_id> --all

undefined

场景 E：替换某个章节

Scenario E: Replace a Section

先删除旧章节的块，再在同一位置插入新内容：

bash

undefined

First delete the blocks of the old section, then insert new content at the same position:

bash

undefined

1. 获取块结构，定位章节的块范围

1. Get the block structure and locate the block range of the section

feishu-cli doc blocks <document_id>

2. 删除旧章节（假设在父块下索引 5~8）

2. Delete the old section (assuming it is at indexes 5~8 under the parent block)

feishu-cli doc delete <document_id> <parent_block_id> --start 5 --end 9 -f

3. 在同一位置插入新内容

3. Insert new content at the same position

feishu-cli doc add <document_id> /tmp/feishu_new_section.md
--content-type markdown
--block-id <parent_block_id>
--index 5


> **何时允许全量覆盖**：仅当用户明确说"重写整个文档"、"全量替换"时，才可使用
> `feishu-cli doc import /tmp/file.md --document-id <id>`。默认必须增量更新。

feishu-cli doc add <document_id> /tmp/feishu_new_section.md
--content-type markdown
--block-id <parent_block_id>
--index 5


> **When is full overwrite allowed**: Only when the user explicitly says "rewrite the entire document" or "full replacement", can `feishu-cli doc import /tmp/file.md --document-id <id>` be used. Incremental updates are required by default.

支持的 Markdown 语法

Supported Markdown Syntax

语法	飞书块类型	说明
`# 标题`	Heading1-6
`普通文本`	Text
`- 列表项`	Bullet	支持缩进嵌套
`1. 有序项`	Ordered	支持缩进嵌套
`- [ ] 任务`	Todo
```code```	Code
```mermaid```	Board（画板）	推荐使用
```plantuml``` / ```puml```	Board（画板）	PlantUML 图表
`> 引用`	QuoteContainer	支持嵌套引用
`> [!NOTE]` 等	Callout（高亮块）	6 种类型
`---`	Divider
`粗体`	粗体样式
`斜体`	斜体样式
`~~删除线~~`	删除线样式
`<u>下划线</u>`	下划线样式
`行内代码`	行内代码样式
$公式$	行内公式	支持一段多个公式
`$$公式$$`	块级公式	独立公式行
`[链接](url)`	链接
`	表格	`

Syntax	Feishu Block Type	Description
`# Heading`	Heading1-6
`Plain text`	Text
`- List item`	Bullet	Supports indentation nesting
`1. Ordered item`	Ordered	Supports indentation nesting
`- [ ] Task`	Todo
```code```	Code
```mermaid```	Board	Recommended
```plantuml``` / ```puml```	Board	PlantUML diagrams
`> Quote`	QuoteContainer	Supports nested quotes
`> [!NOTE]` etc.	Callout	6 types
`---`	Divider
`Bold`	Bold style
`Italic`	Italic style
`~~Strikethrough~~`	Strikethrough style
`<u>Underline</u>`	Underline style
`Inline code`	Inline code style
$Formula$	Inline Formula	Supports multiple formulas in one paragraph
`$$Formula$$`	Block Formula	Independent formula line
`[Link](url)`	Link
`	Table	`

Recommendation: Use Mermaid / PlantUML for Diagramming

在文档中画图时，推荐使用 Mermaid（也支持 PlantUML），会自动转换为飞书画板。

支持的 Mermaid 图表类型：

✅ flowchart（流程图，支持 subgraph）
✅ sequenceDiagram（时序图）
✅ classDiagram（类图）
✅ stateDiagram-v2（状态图）
✅ erDiagram（ER 图）
✅ gantt（甘特图）
✅ pie（饼图）
✅ mindmap（思维导图）

Mermaid 限制（必须遵守，否则导入失败）：

❌ 禁止在 flowchart 节点标签中使用
```
{}
```
花括号（如
```
{version}
```
），会触发解析错误
❌ 禁止使用
```
par...and...end
```
语法，飞书解析器完全不支持
❌ 避免复杂度超限：10+ participant + 2+ alt 块 + 30+ 长消息标签会触发服务端 500
✅ 安全阈值：participant ≤ 8、alt ≤ 1、消息标签尽量简短
✅
```
par
```
替代方案：改用
```
Note over X: 并行执行...
```
✅ 导入失败的图表会自动降级为代码块展示，不会丢失内容

示例：

markdown

```mermaid
flowchart TD
    A[开始] --> B{判断}
    B -->|是| C[处理]
    B -->|否| D[结束]
```

markdown

```plantuml
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml
```

When creating diagrams in documents, it is recommended to use Mermaid (PlantUML is also supported), which will be automatically converted to Feishu Boards.

Supported Mermaid diagram types:

✅ flowchart (supports subgraph)
✅ sequenceDiagram
✅ classDiagram
✅ stateDiagram-v2
✅ erDiagram
✅ gantt
✅ pie
✅ mindmap

Mermaid Restrictions (Must Be Followed, Otherwise Import Will Fail):

❌ Do not use
```
{}
```
curly braces in flowchart node labels (e.g.,
```
{version}
```
), as this will trigger parsing errors
❌ Do not use
```
par...and...end
```
syntax, which is not supported by the Feishu parser at all
❌ Avoid excessive complexity: 10+ participants + 2+ alt blocks + 30+ long message labels will trigger a server 500 error
✅ Safety threshold: participants ≤ 8, alt ≤ 1, message labels as short as possible
✅ Alternative to
```
par
```
: Use
```
Note over X: Execute in parallel...
```
instead
✅ Diagrams that fail to import will be automatically downgraded to code blocks for display, and content will not be lost

Example:

markdown

```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[End]
```

markdown

```plantuml
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml
```

Callout 高亮块

Callout Highlight Blocks

在文档中使用 Callout 语法创建飞书高亮块：

markdown

> [!NOTE]
> 提示信息。

> [!WARNING]
> 警告信息。

> [!TIP]
> 技巧提示。

> [!CAUTION]
> 警示信息。

> [!IMPORTANT]
> 重要信息。

> [!SUCCESS]
> 成功信息。

Callout 内支持多行文本和子块（列表等）。

Create Feishu highlight blocks using Callout syntax in documents:

markdown

> [!NOTE]
> Tip information.

> [!WARNING]
> Warning information.

> [!TIP]
> Tip information.

> [!CAUTION]
> Warning information.

> [!IMPORTANT]
> Important information.

> [!SUCCESS]
> Success information.

Callouts support multi-line text and child blocks (such as lists).

公式

Formulas

markdown

行内公式：圆面积 $S = \pi r^2$，周长 $C = 2\pi r$。

块级公式：
$$\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$

markdown

Inline formula: Area of a circle $S = \pi r^2$, circumference $C = 2\pi r$.

Block formula:
$$\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$

高级操作

Advanced Operations

添加画板

Add Board

向文档添加空白画板：

bash

undefined

Add a blank board to the document:

bash

undefined

在文档末尾添加画板

Add a board to the end of the document

feishu-cli doc add-board <document_id>

在指定位置添加画板

Add a board at a specified position

feishu-cli doc add-board <document_id> --parent-id <block_id> --index 0

undefined

feishu-cli doc add-board <document_id> --parent-id <block_id> --index 0

undefined

添加 Callout

Add Callout

向文档添加高亮块：

bash

undefined

Add a highlight block to the document:

bash

undefined

添加信息类型 Callout

Add an info-type Callout

feishu-cli doc add-callout <document_id> "提示内容" --callout-type info

feishu-cli doc add-callout <document_id> "Tip content" --callout-type info

添加警告类型 Callout

Add a warning-type Callout

feishu-cli doc add-callout <document_id> "警告内容" --callout-type warning

feishu-cli doc add-callout <document_id> "Warning content" --callout-type warning

指定位置添加

Add at a specified position

feishu-cli doc add-callout <document_id> "内容" --callout-type error --parent-id <block_id> --index 0


**Callout 类型与颜色映射**：

飞书 Callout 共 6 种颜色。**Markdown 导入**（`doc import`）使用 `[!TYPE]` 语法支持全部 6 种，**CLI 命令**（`doc add-callout --callout-type`）支持其中 4 种：

| 颜色 | 背景色值 | Markdown 语法 | CLI `--callout-type` |
|------|---------|--------------|---------------------|
| 蓝色 | 6 | `[!NOTE]` | `info` |
| 红色 | 2 | `[!WARNING]` | `error` |
| 橙色 | 3 | `[!CAUTION]` | — |
| 黄色 | 4 | `[!TIP]` | `warning` |
| 绿色 | 5 | `[!SUCCESS]` | `success` |
| 紫色 | 7 | `[!IMPORTANT]` | — |

> 需要橙色（CAUTION）或紫色（IMPORTANT）时，请使用 Markdown 导入方式（`doc import` 或 `doc add --content-type markdown`）。

feishu-cli doc add-callout <document_id> "Content" --callout-type error --parent-id <block_id> --index 0


**Callout Type and Color Mapping**:

Feishu Callouts have 6 colors in total. **Markdown import** (`doc import`) supports all 6 types using the `[!TYPE]` syntax, while **CLI commands** (`doc add-callout --callout-type`) support 4 of them:

| Color | Background Color Value | Markdown Syntax | CLI `--callout-type` |
|------|---------|--------------|---------------------|
| Blue | 6 | `[!NOTE]` | `info` |
| Red | 2 | `[!WARNING]` | `error` |
| Orange | 3 | `[!CAUTION]` | — |
| Yellow | 4 | `[!TIP]` | `warning` |
| Green | 5 | `[!SUCCESS]` | `success` |
| Purple | 7 | `[!IMPORTANT]` | — |

> When orange (CAUTION) or purple (IMPORTANT) is needed, please use the Markdown import method (`doc import` or `doc add --content-type markdown`).

批量更新块

Batch Update Blocks

批量更新文档中的块内容：

bash

undefined

Batch update block content in the document:

bash

undefined

从 JSON 文件批量更新

Batch update from JSON file

feishu-cli doc batch-update <document_id> --source-type content --file updates.json


JSON 格式示例：
```json
[
  {
    "block_id": "block_xxx",
    "block_type": 2,
    "content": "更新后的文本内容"
  }
]

feishu-cli doc batch-update <document_id> --source-type content --file updates.json


JSON format example:
```json
[
  {
    "block_id": "block_xxx",
    "block_type": 2,
    "content": "Updated text content"
  }
]

输出格式

Output Format

创建/更新完成后报告：

文档 ID
文档 URL：
```
https://feishu.cn/docx/<document_id>
```
操作状态

After creation/update is completed, report:

Document ID
Document URL:
```
https://feishu.cn/docx/<document_id>
```
Operation status

示例

Examples

bash

undefined

bash

undefined

创建新的会议纪要

Create new meeting minutes

/feishu-write "2024-01-21 周会纪要"

/feishu-write "2024-01-21 Weekly Meeting Minutes"

更新现有文档

Update existing document

/feishu-write <document_id>

undefined

/feishu-write <document_id>

undefined

常见问题

Frequently Asked Questions

问题	原因与解决方案
Mermaid 图表导入失败	图表会自动降级为代码块展示，不会丢失内容。检查是否使用了 `{}` 花括号、 `par...and...end` 等不支持的语法
权限添加失败	检查飞书开放平台中 App 是否已配置 `docs:permission.member:create` 权限，且应用已发布
认证过期（401 错误）	重新执行 `feishu-cli auth login` ，建议包含 `offline_access` scope 以获取 30 天 Refresh Token
文档创建成功但无法访问	确认已执行 `perm add` 授予 `full_access` 权限并 `perm transfer-owner` 转移所有权
表格内容显示不全	飞书 API 单个表格限制 9 行 9 列，超出部分会自动拆分为多个表格，属于正常行为

Problem	Cause and Solution
Mermaid diagram import failed	The diagram will be automatically downgraded to a code block for display, and content will not be lost. Check if unsupported syntax such as `{}` curly braces or `par...and...end` is used
Permission addition failed	Check if the App in the Feishu Open Platform has been configured with the `docs:permission.member:create` permission and the application has been published
Authentication expired (401 error)	Re-execute `feishu-cli auth login` , it is recommended to include the `offline_access` scope to obtain a 30-day Refresh Token
Document created successfully but cannot be accessed	Confirm that `perm add` has been executed to grant `full_access` permission and `perm transfer-owner` has been executed to transfer ownership
Table content is not fully displayed	The Feishu API limits a single table to 9 rows and 9 columns, and excess parts will be automatically split into multiple tables, which is normal behavior

feishu-cli-write

Original

Translation

飞书文档写入技能

Feishu Docs Writing Skill

快速创建空白文档

Quick Creation of Blank Document

核心概念

Core Concepts

使用方法

Usage

创建新文档

Create new document

更新已有文档

Update existing document

执行流程

Execution Flow

创建新文档

Create New Document

更新已有文档（增量更新）

Update Existing Document (Incremental Update)

场景 A：在文档末尾追加内容

Scenario A: Append Content to the End of the Document

1. 准备要追加的内容（只写新增部分，不要包含已有内容）

1. Prepare the content to append (only write the new part, do not include existing content)

新增章节标题

New Section Title

2. 追加到文档末尾

2. Append to the end of the document

场景 B：在文档指定位置插入内容

Scenario B: Insert Content at a Specified Position in the Document

1. 获取文档块结构，找到插入点

1. Get the document block structure and find the insertion point

2. 在指定父块的指定位置插入

2. Insert at the specified position under the parent block

场景 C：修改已有块的内容

Scenario C: Modify Content of an Existing Block

1. 获取文档块结构，找到要修改的 block_id

1. Get the document block structure and find the block_id to modify

2. 更新指定块

2. Update the specified block

场景 D：删除指定范围的块

Scenario D: Delete Blocks in a Specified Range

删除父块下索引 2~4 的子块

Delete child blocks from index 2~4 under the parent block

删除父块下所有子块

Delete all child blocks under the parent block

场景 E：替换某个章节

Scenario E: Replace a Section

1. 获取块结构，定位章节的块范围

1. Get the block structure and locate the block range of the section

2. 删除旧章节（假设在父块下索引 5~8）

2. Delete the old section (assuming it is at indexes 5~8 under the parent block)

3. 在同一位置插入新内容

3. Insert new content at the same position

支持的 Markdown 语法

Supported Markdown Syntax

推荐：使用 Mermaid / PlantUML 画图

Recommendation: Use Mermaid / PlantUML for Diagramming

Callout 高亮块

Callout Highlight Blocks

公式

Formulas

高级操作

Advanced Operations

添加画板

Add Board

在文档末尾添加画板

Add a board to the end of the document

在指定位置添加画板

Add a board at a specified position

添加 Callout

Add Callout

添加信息类型 Callout

Add an info-type Callout

添加警告类型 Callout

Add a warning-type Callout

指定位置添加

Add at a specified position

批量更新块