• 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

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

• 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

.

1. Wrap with

   @startuml

   /

   @enduml

   (use

   @startmindmap

   /

   @endmindmap

   for mind maps)
2. Do not use leading indentation (Feishu board treats indented lines as independent lines)
3. Avoid style directives such as

   skinparam

   ,

   !define

   , color, font, alignment control
4. Avoid direction control directives (e.g.,

   left to right direction

   is unreliable in some scenarios)

• 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)

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

| 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

feishu-cli

1. When encountering

   ![alt](url)

   , create an empty Image placeholder block (BlockType=27)
2. After import completion, the number of skipped images is displayed in the report
3. Users need to manually replace images in Feishu documents

• 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

• 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

Parse error

Invalid request parameter

internal error

rate limit

frequency limit

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

• 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

• 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

• 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

• Correct wrapping tags are used (

  @startuml

  /

  @enduml

  )
• No leading indentation
• No style directives such as

  skinparam

• Class diagrams do not use visibility markers (

  + - # ~

  )

• 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)

• 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