feishu-cli-doc-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

飞书文档创建规范指南

Feishu Document Creation Specification Guide

1. 概述

1. Overview

本技能是 其他飞书文档技能的参考规范，不可直接调用。整合了以下来源的验证经验：

feishu-cli

项目代码实现（

converter/

、

client/board.go

、

cmd/import_markdown.go

）

feishu-cli-write

、

feishu-cli-import

、

feishu-cli-plantuml

技能的实测数据

大规模导入测试：10,000+ 行 / 127 个图表 / 170+ 个表格的验证结果

适用场景：生成将要导入飞书的 Markdown 文档时，参考本规范确保兼容性。

This skill is a reference specification for other Feishu document skills and cannot be called directly. It integrates verification experience from the following sources:

feishu-cli

project code implementation (

converter/

client/board.go

cmd/import_markdown.go

)

Actual test data from

feishu-cli-write

feishu-cli-import

feishu-cli-plantuml

skills

Large-scale import test: verification results of 10,000+ lines / 127 charts / 170+ tables

Applicable Scenario: Refer to this specification to ensure compatibility when generating Markdown documents to be imported into Feishu.

2. Markdown 语法全量参考

2. Full Markdown Syntax Reference

支持的语法与 Block 类型映射

Supported Syntax and Block Type Mapping

Markdown 语法	Block Type	飞书块名称	说明
`# 标题` ~ `###### 标题`	3-8	Heading1-6	最多 6 级（7-9 级导出降级为粗体段落）
普通段落	2	Text	纯文本
`- 无序列表`	12	Bullet	支持无限深度嵌套
`1. 有序列表`	13	Ordered	支持无限深度嵌套
`- [x]` / `- [ ]`	17	Todo	任务列表
```lang	14	Code	代码块（支持语言标识）
`> 引用`	34	QuoteContainer	引用容器（导入使用 QuoteContainer）
`> [!NOTE]`	19	Callout	高亮块（6 种类型，见第 5 节）
`---`	22	Divider	分割线
Markdown 表格	31	Table	超过 9 行自动拆分（见第 6 节）
`![alt](url)`	27	Image	占位块（见第 7 节）
```mermaid	21→43	Diagram→Board	自动转飞书画板（见第 3 节）
```plantuml / ```puml	21→43	Diagram→Board	自动转飞书画板（见第 4 节）
`$$公式$$`	16	Equation	块级公式（降级为行内 Equation）
$公式$	—	InlineEquation	行内公式

Markdown Syntax	Block Type	Feishu Block Name	Description
`# Heading` ~ `###### Heading`	3-8	Heading1-6	Up to 6 levels (H7-H9 will be downgraded to bold paragraphs when exported)
Normal paragraph	2	Text	Plain text
`- Unordered list`	12	Bullet	Supports unlimited depth nesting
`1. Ordered list`	13	Ordered	Supports unlimited depth nesting
`- [x]` / `- [ ]`	17	Todo	Task list
```lang	14	Code	Code block (supports language identifiers)
`> Quote`	34	QuoteContainer	Quote container (uses QuoteContainer for import)
`> [!NOTE]`	19	Callout	Highlight block (6 types, see Section 5)
`---`	22	Divider	Divider line
Markdown table	31	Table	Automatically split when exceeding 9 rows (see Section 6)
`![alt](url)`	27	Image	Placeholder block (see Section 7)
```mermaid	21→43	Diagram→Board	Automatically converted to Feishu board (see Section 3)
```plantuml / ```puml	21→43	Diagram→Board	Automatically converted to Feishu board (see Section 4)
`$$Formula$$`	16	Equation	Block-level formula (downgraded to inline Equation)
$Formula$	—	InlineEquation	Inline formula

行内样式

Inline Styles

Markdown	效果	说明
`粗体`	粗体	Bold TextStyle
`斜体`	斜体	Italic TextStyle
`行内代码`	`代码`	InlineCode TextStyle
`~~删除线~~`	~~删除线~~	Strikethrough TextStyle
`<u>下划线</u>`	下划线	Underline TextStyle
`[文字](url)`	链接	Link TextElement
`==高亮==`	高亮	Highlight（需启用选项）

Markdown	Effect	Description
`Bold`	Bold	Bold TextStyle
`Italic`	Italic	Italic TextStyle
`Inline code`	`Code`	InlineCode TextStyle
`~~Strikethrough~~`	~~Strikethrough~~	Strikethrough TextStyle
`<u>Underline</u>`	Underline	Underline TextStyle
`[Text](url)`	Link	Link TextElement
`==Highlight==`	Highlight	Highlight (requires option enabled)

嵌套列表示例

Nested List Example

markdown

- 一级无序
  - 二级无序
    - 三级无序
      1. 四级有序
      2. 四级有序
    - 三级无序
  - 二级无序

无序/有序列表支持 无限深度嵌套 和 混合嵌套，导入时自动保留缩进层级。

markdown

- Level 1 unordered
  - Level 2 unordered
    - Level 3 unordered
      1. Level 4 ordered
      2. Level 4 ordered
    - Level 3 unordered
  - Level 2 unordered

Unordered/ordered lists support unlimited depth nesting and mixed nesting, and indentation levels are automatically preserved during import.

3. Mermaid 飞书语法规范

3. Feishu Mermaid Syntax Specification

这是最重要的章节。Mermaid 图表导入飞书有严格的语法限制，不遵守会导致渲染失败。

This is the most important section. Mermaid chart import into Feishu has strict syntax restrictions; non-compliance will cause rendering failure.

支持的 8 种图表类型

8 Supported Chart Types

类型	声明	飞书 diagram_type	说明
流程图	`flowchart TD` / `flowchart LR`	6 (flowchart)	支持 subgraph
时序图	`sequenceDiagram`	2 (sequence)	复杂度限制最严格
类图	`classDiagram`	4 (class)
状态图	`stateDiagram-v2`	0 (auto)	必须用 v2
ER 图	`erDiagram`	5 (er)
甘特图	`gantt`	0 (auto)
饼图	`pie`	0 (auto)
思维导图	`mindmap`	1 (mindmap)

Type	Declaration	Feishu diagram_type	Description
Flowchart	`flowchart TD` / `flowchart LR`	6 (flowchart)	Supports subgraph
Sequence Diagram	`sequenceDiagram`	2 (sequence)	Strictest complexity restrictions
Class Diagram	`classDiagram`	4 (class)
State Diagram	`stateDiagram-v2`	0 (auto)	Must use v2
ER Diagram	`erDiagram`	5 (er)
Gantt Chart	`gantt`	0 (auto)
Pie Chart	`pie`	0 (auto)
Mind Map	`mindmap`	1 (mindmap)

6 条强制性规则

6 Mandatory Rules

规则 1：禁止在标签中使用花括号

{}

Rule 1: Forbid using curly braces

{}

in labels

花括号会被 Mermaid 解析器识别为菱形（decision）节点，导致语法错误。此规则针对 flowchart 节点标签，erDiagram/classDiagram 语法结构中的

{}

不受此限制。

markdown

<!-- ❌ 错误 -->
flowchart TD
    A["{name: value}"]

<!-- ✅ 正确 -->
flowchart TD
    A["name: value"]

替代方案：移除花括号，或用圆括号/方括号替代。

Curly braces will be recognized as diamond (decision) nodes by the Mermaid parser, causing syntax errors. This rule applies to flowchart node labels;

{}

in the syntax structure of erDiagram/classDiagram is not restricted.

markdown

<!-- ❌ Error -->
flowchart TD
    A["{name: value}"]

<!-- ✅ Correct -->
flowchart TD
    A["name: value"]

Alternative: Remove curly braces, or replace with parentheses/square brackets.

规则 2：禁止使用

par...and...end

并行语法

Rule 2: Forbid using

par...and...end

parallel syntax

飞书画板完全不支持

par

语法（错误码 2891001）。

markdown

<!-- ❌ 错误 -->
sequenceDiagram
    par
        A->>B: 请求1
    and
        A->>C: 请求2
    end

<!-- ✅ 正确：用 Note 替代 -->
sequenceDiagram
    Note over A,C: 并行处理
    A->>B: 请求1
    A->>C: 请求2

Feishu board does not support

par

syntax at all (error code 2891001).

markdown

<!-- ❌ Error -->
sequenceDiagram
    par
        A->>B: Request 1
    and
        A->>C: Request 2
    end

<!-- ✅ Correct: Replace with Note -->
sequenceDiagram
    Note over A,C: Parallel processing
    A->>B: Request 1
    A->>C: Request 2

规则 3：方括号中避免冒号

Rule 3: Avoid colons in square brackets

方括号

[text:xxx]

中的冒号可能导致解析歧义。

markdown

<!-- ❌ 可能出错 -->
flowchart TD
    A[类型:string]

<!-- ✅ 正确 -->
flowchart TD
    A["类型: string"]

修复方法：给含冒号的标签加双引号。

Colons in square brackets

[text:xxx]

may cause parsing ambiguity.

markdown

<!-- ❌ May cause error -->
flowchart TD
    A[Type:string]

<!-- ✅ Correct -->
flowchart TD
    A["Type: string"]

Fix: Add double quotes to labels containing colons.

规则 4：Note 作用域限制

Rule 4: Note scope restriction

Note over

最多跨 2 个相邻 participant。

markdown

<!-- ❌ 错误：跨太多参与者 -->
sequenceDiagram
    Note over A,D: 说明

<!-- ✅ 正确 -->
sequenceDiagram
    Note over A,B: 说明

Note over

can span at most 2 adjacent participants.

markdown

<!-- ❌ Error: Too many participants spanned -->
sequenceDiagram
    Note over A,D: Description

<!-- ✅ Correct -->
sequenceDiagram
    Note over A,B: Description

规则 5：sequenceDiagram 复杂度阈值

Rule 5: SequenceDiagram Complexity Threshold

维度	安全阈值	超限风险
participant 数量	≤ 8	超过 10 + 其他因素 → 失败
alt/opt 嵌套	≤ 1 层	超过 2 层 → 失败风险增大
消息标签长度	简短（≤ 30 字符）	长标签 + 多参与者 → 失败
总消息数	≤ 30	需结合其他因素评估

超限组合（实测必定失败）：10+ participant + 2+ alt + 30+ 长消息标签

建议：超过安全阈值时，拆分为多个小图。

Dimension	Safe Threshold	Risk of Exceeding
Number of participants	≤ 8	Exceeding 10 + other factors → Failure
alt/opt nesting	≤ 1 layer	Exceeding 2 layers → Increased failure risk
Message label length	Short (≤ 30 characters)	Long labels + multiple participants → Failure
Total number of messages	≤ 30	Need to evaluate with other factors

Exceeding Combination (guaranteed to fail in tests): 10+ participants + 2+ alt layers + 30+ long message labels

Recommendation: Split into multiple small diagrams when exceeding the safe threshold.

规则 6：避免过于复杂的嵌套结构

Rule 6: Avoid overly complex nested structures

多层 subgraph 嵌套、大量条件分支等复杂结构会增加渲染失败概率。保持图表简洁。

Complex structures such as multi-layer subgraph nesting and a large number of conditional branches will increase the probability of rendering failure. Keep diagrams concise.

生成前检查清单

Pre-Generation Checklist

在生成 Mermaid 代码块前，逐项检查：

图表类型是否在支持的 8 种之内？
标签中是否存在花括号
```
{}
```
？→ 移除或替换
是否使用了
```
par...and...end
```
？→ 改用
```
Note over
```
方括号标签中是否有冒号？→ 加双引号
sequenceDiagram 参与者是否 ≤ 8？
sequenceDiagram alt 嵌套是否 ≤ 1 层？
整体复杂度是否可控？→ 考虑拆分

详细的 8 种图表模板和更多正反示例见
references/mermaid-spec.md
。

Before generating Mermaid code blocks, check each item:

Is the chart type among the 8 supported types?
Are there curly braces
```
{}
```
in the labels? → Remove or replace
Is
```
par...and...end
```
used? → Replace with
```
Note over
```
Are there colons in square bracket labels? → Add double quotes
Does sequenceDiagram have ≤ 8 participants?
Does sequenceDiagram have ≤ 1 layer of alt nesting?
Is the overall complexity controllable? → Consider splitting

Detailed templates for 8 chart types and more positive/negative examples can be found in
references/mermaid-spec.md
.

4. PlantUML 安全子集

4. PlantUML Safe Subset

全局规则

Global Rules

使用

@startuml

@enduml

包裹（思维导图用

@startmindmap

@endmindmap

）

不要使用行首缩进（飞书画板将缩进行视为独立行）
避免
```
skinparam
```
、
```
!define
```
、颜色、字体、对齐控制等样式指令
避免方向控制指令（
```
left to right direction
```
等在部分场景不可靠）

Wrap with

@startuml

@enduml

(use

@startmindmap

@endmindmap

for mind maps)

Do not use leading indentation (Feishu board treats indented lines as independent lines)
Avoid style directives such as
```
skinparam
```
,
```
!define
```
, color, font, alignment control
Avoid direction control directives (e.g.,
```
left to right direction
```
is unreliable in some scenarios)

各图类型注意事项

Notes by Chart Type

图类型	安全语法	禁忌
活动图	`start/stop` 、 `:动作;` 、 `if/then/else/endif` 、 `repeat` 、 `fork`	避免过深嵌套
时序图	`participant` 、 `->` / `-->` 、 `activate/deactivate` 、 `note` 、 `alt/opt/loop`	避免样式指令
类图	`class` 、 `interface` 、 `package` 、关系箭头	避免可见性标记（+ - # ~）
用例图	`actor` 、 `(用例)` 、 `<<include>>` / `<<extend>>`	避免复杂布局
组件图	`[Component]` 、 `package/node/cloud/database`	避免 ArchiMate sprite
ER 图	`entity` 、关系箭头	与 Mermaid ER 语法不同
思维导图	`@startmindmap` 、 `* / +` 层级标记	必须用专用包裹标记

Chart Type	Safe Syntax	Forbidden
Activity Diagram	`start/stop` , `:Action;` , `if/then/else/endif` , `repeat` , `fork`	Avoid deep nesting
Sequence Diagram	`participant` , `->` / `-->` 、 `activate/deactivate` , `note` , `alt/opt/loop`	Avoid style directives
Class Diagram	`class` , `interface` , `package` , relationship arrows	Avoid visibility markers (+ - # ~)
Use Case Diagram	`actor` , `(Use Case)` , `<<include>>` / `<<extend>>`	Avoid complex layouts
Component Diagram	`[Component]` , `package/node/cloud/database`	Avoid ArchiMate sprite
ER Diagram	`entity` , relationship arrows	Different from Mermaid ER syntax
Mind Map	`@startmindmap` , `* / +` level markers	Must use dedicated wrapping tags

Mermaid vs PlantUML 选择策略

Mermaid vs PlantUML Selection Strategy

场景	推荐	原因
流程图	Mermaid	飞书原生支持更好，成功率高
时序图（简单）	Mermaid	语法简洁
时序图（复杂）	PlantUML	Mermaid 复杂度限制严格
类图	Mermaid	两者都可，Mermaid 更简洁
ER 图	Mermaid	语法更直观
状态图	Mermaid	stateDiagram-v2 支持好
甘特图	Mermaid	PlantUML 甘特图飞书支持差
饼图	Mermaid	简洁
思维导图	两者均可	PlantUML 层级标记更灵活
用例图	PlantUML	Mermaid 不支持
组件图	PlantUML	Mermaid 不支持
活动图（复杂分支）	PlantUML	支持更丰富的分支语法

默认推荐 Mermaid，仅在 Mermaid 不支持的图类型或复杂场景下使用 PlantUML。

Scenario	Recommendation	Reason
Flowchart	Mermaid	Better native Feishu support, high success rate
Simple Sequence Diagram	Mermaid	Concise syntax
Complex Sequence Diagram	PlantUML	Mermaid has strict complexity restrictions
Class Diagram	Mermaid	Both are available, Mermaid is more concise
ER Diagram	Mermaid	More intuitive syntax
State Diagram	Mermaid	Good support for stateDiagram-v2
Gantt Chart	Mermaid	Poor Feishu support for PlantUML Gantt charts
Pie Chart	Mermaid	Concise
Mind Map	Either	PlantUML has more flexible level markers
Use Case Diagram	PlantUML	Not supported by Mermaid
Component Diagram	PlantUML	Not supported by Mermaid
Activity Diagram with Complex Branches	PlantUML	Supports richer branch syntax

Default recommendation is Mermaid, use PlantUML only when Mermaid does not support the chart type or in complex scenarios.

5. Callout 高亮块

5. Callout Highlight Blocks

6 种类型与背景色映射

6 Types and Background Color Mapping

类型	bgColor	颜色	Markdown 语法	适用场景
NOTE / INFO	6	蓝色	`> [!NOTE]`	补充说明、提示信息
WARNING	2	红色	`> [!WARNING]`	警告、危险提醒
TIP	4	黄色	`> [!TIP]`	技巧、建议
CAUTION	3	橙色	`> [!CAUTION]`	注意事项
IMPORTANT	7	紫色	`> [!IMPORTANT]`	重要信息
SUCCESS	5	绿色	`> [!SUCCESS]`	成功、通过

Type	bgColor	Color	Markdown Syntax	Applicable Scenario
NOTE / INFO	6	Blue	`> [!NOTE]`	Supplementary explanations, prompt information
WARNING	2	Red	`> [!WARNING]`	Warnings, danger reminders
TIP	4	Yellow	`> [!TIP]`	Tips, suggestions
CAUTION	3	Orange	`> [!CAUTION]`	Notes
IMPORTANT	7	Purple	`> [!IMPORTANT]`	Important information
SUCCESS	5	Green	`> [!SUCCESS]`	Success, pass status

使用示例

Usage Example

markdown

> [!NOTE]
> 这是一条补充说明信息。

> [!WARNING]
> 此操作不可逆，请谨慎执行。

> [!TIP]
> 使用 `--verbose` 参数可以查看详细进度。

> [!CAUTION]
> 注意：API 有频率限制。

> [!IMPORTANT]
> 必须在执行前配置环境变量。

> [!SUCCESS]
> 所有测试用例已通过。

markdown

> [!NOTE]
> This is supplementary explanatory information.

> [!WARNING]
> This operation is irreversible, please proceed with caution.

> [!TIP]
> Use the `--verbose` parameter to view detailed progress.

> [!CAUTION]
> Note: The API has frequency limits.

> [!IMPORTANT]
> Environment variables must be configured before execution.

> [!SUCCESS]
> All test cases have passed.

注意事项

Notes

Callout 块不能同时设置
```
EmojiId
```
，仅通过
```
BackgroundColor
```
区分类型
支持 Callout 内包含子块（段落、列表等）
```
INFO
```
和
```
NOTE
```
等效，都映射为蓝色 (bgColor=6)

Callout blocks cannot set
```
EmojiId
```
at the same time; types are distinguished only by
```
BackgroundColor
```
Callouts can contain child blocks (paragraphs, lists, etc.)
```
INFO
```
and
```
NOTE
```
are equivalent, both mapped to blue (bgColor=6)

6. 表格规范

6. Table Specification

9 行限制与自动拆分

9-Row Limit and Automatic Splitting

飞书 API 限制单个表格最多 9 行（包括表头）。超出时 feishu-cli 自动拆分为多个表格，每个子表格复制表头。

拆分逻辑（

converter/markdown_to_block.go

）：

表格行数	处理方式
≤ 9 行（含表头）	直接创建单个表格
> 9 行	拆分为多个表格，每个最多 8 行数据 + 1 行表头

Feishu API limits a single table to a maximum of 9 rows (including header). When exceeded, feishu-cli automatically splits it into multiple tables, with each sub-table copying the header.

Splitting logic (

converter/markdown_to_block.go

Number of Table Rows	Processing Method
≤ 9 rows (including header)	Directly create a single table
> 9 rows	Split into multiple tables, each with up to 8 data rows + 1 header row

列宽自动计算

Automatic Column Width Calculation

列宽根据单元格内容自动计算（

converter/markdown_to_block.go:25-103

）：

参数	值	说明
中文字符宽度	14px	非 ASCII 字符
英文字符宽度	8px	ASCII 字符
列内边距	16px	每列额外边距
最小列宽	80px	不能更窄
最大列宽	400px	不能更宽
文档默认宽度	700px	总宽度不足时按比例扩展

Column width is automatically calculated based on cell content (

converter/markdown_to_block.go:25-103

Parameter	Value	Description
Chinese character width	14px	Non-ASCII characters
English character width	8px	ASCII characters
Column padding	16px	Extra padding per column
Minimum column width	80px	Cannot be narrower
Maximum column width	400px	Cannot be wider
Default document width	700px	Expand proportionally when total width is insufficient

单元格多块支持

Multi-Block Support in Cells

表格单元格内可以包含多种块类型：

Text（普通文本）
Bullet（无序列表）
Heading（标题）

注意：飞书 API 创建表格时会自动在每个单元格内创建空的 Text 块。填充内容时应 更新现有块 而非创建新块。

Table cells can contain multiple block types:

Text (plain text)
Bullet (unordered list)
Heading (heading)

Note: Feishu API automatically creates an empty Text block in each cell when creating a table. When filling content, you should update existing blocks instead of creating new ones.

表格编写建议

Table Writing Recommendations

markdown

| 列1 | 列2 | 列3 |
|-----|-----|-----|
| 数据 | 数据 | 数据 |

确保每行列数一致
大表格（超过 8 行数据）会自动拆分，无需手动处理
列宽由内容自动决定，无需手动控制

markdown

| Column 1 | Column 2 | Column 3 |
|-----|-----|-----|
| Data | Data | Data |

Ensure consistent number of columns per row
Large tables (more than 8 data rows) will be automatically split, no manual processing required
Column width is automatically determined by content, no manual control needed

7. 图片处理

7. Image Processing

当前限制

Current Restrictions

飞书 DocX Open API 不支持通过 API 插入实际图片内容。

feishu-cli

的处理方式：

遇到
```
![alt](url)
```
时，创建一个空的 Image 占位块（BlockType=27）
导入完成后，报告中显示 跳过的图片数量
用户需要在飞书文档中手动替换图片

Feishu DocX Open API does not support inserting actual image content via API. The processing method of

feishu-cli

When encountering
```
![alt](url)
```
, create an empty Image placeholder block (BlockType=27)
After import completion, the number of skipped images is displayed in the report
Users need to manually replace images in Feishu documents

建议

Recommendations

如果文档中有大量图片，考虑在导入后手动上传
可以使用
```
feishu-cli media upload
```
上传素材到飞书，获取文件 token
图片相关的 alt 文字会作为占位信息保留

If there are a large number of images in the document, consider manual upload after import
You can use
```
feishu-cli media upload
```
to upload materials to Feishu and obtain file tokens
The alt text related to images will be retained as placeholder information

8. 公式

8. Formulas

行内公式

Inline Formulas

使用单美元符号包裹：

$E = mc^2$

支持一个段落内包含多个行内公式：

markdown

已知 $a^2 + b^2 = c^2$，当 $a = 3, b = 4$ 时，$c = 5$。

Wrap with single dollar signs:

$E = mc^2$

Supports multiple inline formulas in one paragraph:

markdown

Given $a^2 + b^2 = c^2$, when $a = 3, b = 4$, $c = 5$.

块级公式

Block-Level Formulas

使用双美元符号包裹：

markdown

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Wrap with double dollar signs:

markdown

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

注意事项

Notes

飞书 API 不支持直接创建块级 Equation（BlockType=16），实际导入时 降级为行内 Equation
LaTeX 语法兼容飞书 KaTeX 渲染器
公式中的特殊字符无需额外转义

Feishu API does not support direct creation of block-level Equation (BlockType=16); it is actually downgraded to inline Equation during import
LaTeX syntax is compatible with Feishu KaTeX renderer
Special characters in formulas do not need additional escaping

9. API 限制与容错

9. API Restrictions and Fault Tolerance

三阶段并发管道

Three-Stage Concurrent Pipeline

feishu-cli doc import

采用三阶段管道架构（

cmd/import_markdown.go

）：

阶段	方式	处理内容
阶段一	顺序	按文档顺序创建所有块，为图表创建空画板占位块，收集表格任务
阶段二	并发	图表 worker 池（默认 5 并发）+ 表格 worker 池（默认 3 并发）同时处理
阶段三	逆序	处理失败的图表：删除空画板块，在原位置插入代码块（逆序避免索引偏移）

feishu-cli doc import

adopts a three-stage pipeline architecture (

cmd/import_markdown.go

Stage	Method	Processing Content
Stage 1	Sequential	Create all blocks in document order, create empty board placeholder blocks for charts, collect table tasks
Stage 2	Concurrent	Chart worker pool (default 5 concurrency) + table worker pool (default 3 concurrency) process simultaneously
Stage 3	Reverse Order	Process failed charts: delete empty board blocks, insert code blocks at original positions (reverse order avoids index offset)

批量操作限制

Batch Operation Restrictions

限制	值	处理方式
单次创建块数	最多 50 个	自动分批（ `batchSize = 50` ）
单个表格行数	最多 9 行	自动拆分并复制表头
文件大小	最大 100MB	超出直接报错
API 频率	429 Too Many Requests	自动重试 + 线性退避

Restriction	Value	Processing Method
Maximum number of blocks created per request	50	Automatic batching ( `batchSize = 50` )
Maximum rows per table	9	Automatic splitting with header copying
File size	Maximum 100MB	Direct error reporting when exceeded
API frequency	429 Too Many Requests	Automatic retry + linear backoff

图表重试与降级策略

Chart Retry and Downgrade Strategy

错误类型	判断条件	处理方式
语法错误	`Parse error` 、 `Invalid request parameter`	不重试，直接降级为代码块
服务端错误	500/502/503、 `internal error`	重试（最多 10 次，1s 间隔）
频率限制	429、 `rate limit` 、 `frequency limit`	重试（归为可重试错误）
重试耗尽	超过最大重试次数	降级为代码块

降级处理流程：

获取文档所有顶层子块
按索引逆序处理失败图表（避免删除导致索引偏移）
删除空画板块
在原位置插入代码块（保留原始图表代码）

Error Type	Judgment Condition	Processing Method
Syntax Error	`Parse error` , `Invalid request parameter`	No retry, directly downgrade to code block
Server Error	500/502/503, `internal error`	Retry (up to 10 times, 1s interval)
Rate Limit	429, `rate limit` , `frequency limit`	Retry (classified as retryable error)
Retry Exhausted	Exceed maximum retry times	Downgrade to code block

Downgrade Processing Flow:

Get all top-level child blocks of the document
Process failed charts in reverse order by index (avoid index offset caused by deletion)
Delete empty board blocks
Insert code blocks at original positions (retain original chart code)

CLI 并发控制参数

CLI Concurrency Control Parameters

参数	默认值	说明
`--diagram-workers`	5	图表（Mermaid/PlantUML）并发导入数
`--table-workers`	3	表格并发填充数
`--diagram-retries`	10	图表最大重试次数
`--verbose`	false	显示详细进度

Parameter	Default Value	Description
`--diagram-workers`	5	Number of concurrent imports for charts (Mermaid/PlantUML)
`--table-workers`	3	Number of concurrent table fill operations
`--diagram-retries`	10	Maximum number of retries for charts
`--verbose`	false	Display detailed progress

画板 API 技术细节

Board API Technical Details

API 端点：

/open-apis/board/v1/whiteboards/{id}/nodes/plantuml

```
syntax_type
```
：1 = PlantUML，2 = Mermaid
```
diagram_type
```
映射：0=auto, 1=mindmap, 2=sequence, 3=activity, 4=class, 5=er, 6=flowchart, 7=state, 8=component

API Endpoint:

/open-apis/board/v1/whiteboards/{id}/nodes/plantuml

```
syntax_type
```
: 1 = PlantUML, 2 = Mermaid
```
diagram_type
```
Mapping: 0=auto, 1=mindmap, 2=sequence, 3=activity, 4=class, 5=er, 6=flowchart, 7=state, 8=component

10. 最佳实践检查清单

10. Best Practices Checklist

创建将导入飞书的 Markdown 文档前，完成以下检查：

Before creating a Markdown document to be imported into Feishu, complete the following checks:

文档结构

Document Structure

标题层级不超过 6 级（H7-H9 会降级为粗体段落）
嵌套列表使用 2 或 4 空格缩进
表格数据行控制在 8 行以内（避免不必要拆分）
文件总大小不超过 100MB

Heading levels do not exceed 6 (H7-H9 will be downgraded to bold paragraphs)
Nested lists use 2 or 4 spaces for indentation
Table data rows are controlled within 8 rows (avoid unnecessary splitting)
Total file size does not exceed 100MB

Mermaid 图表

Mermaid Charts

图表类型在支持的 8 种之内
标签无花括号
```
{}
```
未使用
```
par...and...end
```
方括号标签内含冒号时已加双引号
sequenceDiagram：participant ≤ 8，alt ≤ 1 层
复杂图表已拆分为多个小图

Chart type is among the 8 supported types
No curly braces
```
{}
```
in labels
```
par...and...end
```
is not used
Double quotes are added to square bracket labels containing colons
SequenceDiagram: participants ≤ 8, alt layers ≤ 1
Complex charts have been split into multiple small diagrams

PlantUML 图表

PlantUML Charts

使用正确的包裹标记（
```
@startuml
```
/
```
@enduml
```
）
无行首缩进
无
```
skinparam
```
等样式指令
类图未使用可见性标记（
```
+ - # ~
```
）

Correct wrapping tags are used (
```
@startuml
```
/
```
@enduml
```
)
No leading indentation
No style directives such as
```
skinparam
```
Class diagrams do not use visibility markers (
```
+ - # ~
```
)

特殊内容

Special Content

图片已标注（导入后需手动替换）
公式语法正确（
```
$...$
```
行内 /
```
$$...$$
```
块级）
Callout 类型在 6 种之内（NOTE/WARNING/TIP/CAUTION/IMPORTANT/SUCCESS）

Images are labeled (need manual replacement after import)
Formula syntax is correct (
```
$...$
```
for inline /
```
$$...$$
```
for block-level)
Callout types are among the 6 types (NOTE/WARNING/TIP/CAUTION/IMPORTANT/SUCCESS)

性能考虑

Performance Considerations

大量图表时考虑增加
```
--diagram-workers
```
大量表格时考虑增加
```
--table-workers
```
首次导入建议加
```
--verbose
```
观察进度

Consider increasing
```
--diagram-workers
```
when there are a large number of charts
Consider increasing
```
--table-workers
```
when there are a large number of tables
It is recommended to add
```
--verbose
```
for the first import to observe progress