feishu-cli-plantuml

Feishu PlantUML Generation Skill

Generate PlantUML diagrams adapted for Feishu Whiteboard, strictly using the safe subset syntax.

PlantUML vs Mermaid Selection

This project supports both PlantUML and Mermaid. Selection recommendations:

Scenario	Recommendation	Reason
Flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts, pie charts, mind maps, state diagrams	Mermaid	Feishu has better native support and a higher success rate
Use case diagrams, component diagrams, activity diagrams (complex branches)	PlantUML	Mermaid does not support these diagram types
Need precise control over diagram layout	PlantUML	The syntax is more flexible

Mermaid is recommended by default, and PlantUML is used only when Mermaid does not support the diagram type.

Diagram Type Determination

Automatically select the diagram type based on the user's description:

User description keywords	Diagram type
Process/steps/approval/rules	Activity diagram/flowchart
Call chain/interface interaction/message order	Sequence diagram
Role-function	Use case diagram
Structure/class/relationship	Class diagram
Component/module/technology roadmap	Component diagram
Architecture diagram/layered architecture	Component diagram (no ArchiMate)
Entity/field/table relationship	ER diagram
Mind map/hierarchy organization	Mind map

Safe Subset Rules

Must comply

• Use @startuml / @enduml wrapping (for mind maps use @startmindmap / @endmindmap）
• Do not use leading indentation—Feishu Whiteboard treats indented lines as independent lines, causing parsing failure. All code must be written flush left (except for content inside package/class)
• Avoid skinparam style directives
• Avoid !define preprocessing/macro directives
• Avoid color, font, and alignment controls
• Avoid direction control directives (such as left to right direction）

Syntax for Each Diagram Type

Activity Diagram/Flowchart

@startuml
start
:步骤1;
if (条件?) then (是)
:步骤2;
else (否)
:步骤3;
endif
stop
@enduml

Sequence Diagram

@startuml
participant 用户
participant 系统
用户 -> 系统: 请求
系统 --> 用户: 响应
@enduml

Class Diagram

@startuml
class 用户 {
id : int
name : string
login()
}
class 订单 {
id : int
amount : float
}
用户 --> 订单
@enduml

Note: avoid visibility markers (+ - # ~）

Use Case Diagram

@startuml
actor 用户
(登录)
(注册)
用户 --> (登录)
用户 --> (注册)
@enduml

Component Diagram

@startuml
package "前端" {
[Web App]
[Mobile App]
}
package "后端" {
[API Server]
[Database]
}
[Web App] --> [API Server]
[Mobile App] --> [API Server]
[API Server] --> [Database]
@enduml

ER Diagram

@startuml
entity 用户 {
*id : int
name : varchar
email : varchar
}
entity 订单 {
*id : int
user_id : int
amount : decimal
}
用户 ||--o{ 订单
@enduml

Mind Map

@startmindmap
* 主题
** 分支1
*** 子分支1
*** 子分支2
** 分支2
@endmindmap

Usage Flow

1. Analyze user requirements: determine the diagram type
2. Generate PlantUML: follow the safe subset
3. Output code block: output only one code block
4. Explain changes: if there are downgrades or removals, briefly explain

Import into Feishu Docs

The generated PlantUML can be used in the following ways:

Method 1: Paste directly into Feishu Whiteboard

1. Insert a whiteboard in a Feishu document
2. Click "PlantUML"
3. Paste the generated code

Method 2: Import via Markdown

Use a plantuml code block in Markdown:

```plantuml
@startuml
...
@enduml
```

Then use feishu-cli doc import to import.

Output Specification

• Output only one PlantUML code block
• Briefly explain the modification points outside the code block (if there is any degradation)
• Do not output extra pseudocode
• Do not include leading indentation in the output

Common Issues

Rendering Failure

1. Check whether there is leading indentation
2. Check whether unsupported syntax is used
3. Simplify the diagram complexity

ArchiMate Not Supported

The Feishu whiteboard PlantUML version is older, and ArchiMate sprites are incomplete. It is recommended to use a component diagram instead.

Permission Requirements

• board:board - Whiteboard read and write (PlantUML is imported via the whiteboard API)
• docx:document - Document read and write (required when importing via Markdown)