feishu-cli-plantuml

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

飞书 PlantUML 生成技能

Feishu PlantUML Generation Skill

生成适配飞书画板的 PlantUML 图表，严格使用安全子集语法。

Generate PlantUML diagrams adapted for Feishu Board, strictly following the safe subset syntax.

PlantUML vs Mermaid 选择

PlantUML vs Mermaid Selection

本项目同时支持 PlantUML 和 Mermaid，选择建议：

场景	推荐	原因
流程图、时序图、类图、ER 图、甘特图、饼图、思维导图、状态图	Mermaid	飞书原生支持更好，成功率更高
用例图、组件图、活动图（复杂分支）	PlantUML	Mermaid 不支持这些图类型
需要精确控制图表布局	PlantUML	语法更灵活

默认推荐 Mermaid，仅在 Mermaid 不支持的图类型时才使用 PlantUML。

This project supports both PlantUML and Mermaid. Here's the selection recommendation:

Scenario	Recommendation	Reason
Flowcharts, sequence diagrams, class diagrams, ER diagrams, Gantt charts, pie charts, mind maps, state diagrams	Mermaid	Better native support in Feishu, 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	More flexible syntax

Default recommendation is Mermaid, only use PlantUML when the diagram type is not supported by Mermaid.

图类型判断

Diagram Type Determination

根据用户描述自动选择图类型：

用户描述关键词	图类型
流程/步骤/审批/规则	活动图/流程图
调用链/接口交互/消息顺序	时序图
角色-功能	用例图
结构/类/关系	类图
组件/模块/技术路线图	组件图
架构图/分层架构	组件图（无 ArchiMate）
实体/字段/表关系	ER 图
思维导图/层级梳理	思维导图

Automatically select the diagram type based on user description:

User Description Keywords	Diagram Type
Process/Step/Approval/Rules	Activity Diagram/Flowchart
Call Chain/Interface Interaction/Message Sequence	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 Follow

使用

@startuml

@enduml

包裹（思维导图用

@startmindmap

@endmindmap

）

不要使用行首缩进——飞书画板将缩进的行视为独立行，导致解析失败。所有代码必须顶格书写（package/class 内部内容除外）
避免
```
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, causing parsing failure. All code must be written flush left (except content inside package/class)
Avoid
```
skinparam
```
style directives
Avoid
```
!define
```
preprocessing/macro directives
Avoid color, font, alignment controls
Avoid direction control directives (e.g.,
```
left to right direction
```
)

各图类型语法

Syntax for Each Diagram Type

活动图/流程图

Activity Diagram/Flowchart

plantuml

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

plantuml

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

时序图

Sequence Diagram

plantuml

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

plantuml

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

类图

Class Diagram

plantuml

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

注意：避免可见性标记（

）

plantuml

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

Note: Avoid visibility markers (

)

用例图

Use Case Diagram

plantuml

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

plantuml

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

组件图

Component Diagram

plantuml

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

plantuml

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

ER 图

ER Diagram

plantuml

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

plantuml

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

思维导图

Mind Map

plantuml

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

plantuml

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

使用流程

Usage Process

分析用户需求：确定图类型
生成 PlantUML：遵循安全子集
输出代码块：仅输出一个代码块
说明变更：如有降级或移除，简要说明

Analyze User Requirements: Determine the diagram type
Generate PlantUML: Follow the safe subset
Output Code Block: Output only one code block
Explain Changes: Briefly explain if there are downgrades or removals

导入到飞书文档

Import to Feishu Document

生成的 PlantUML 可以通过以下方式使用：

The generated PlantUML can be used in the following ways:

方式一：飞书画板直接粘贴

Method 1: Direct Paste to Feishu Board

在飞书文档中插入画板
点击"PlantUML"
粘贴生成的代码

Insert a board in Feishu Document
Click "PlantUML"
Paste the generated code

方式二：通过 Markdown 导入

Method 2: Import via Markdown

在 Markdown 中使用 plantuml 代码块：

markdown

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

然后使用

feishu-cli doc import

导入。

Use plantuml code blocks in Markdown:

markdown

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

Then use

feishu-cli doc import

to import.

输出规范

Output Specifications

只输出一个 PlantUML 代码块
代码块外简短说明修改点（如有降级）
不输出多余的伪代码
输出时不要包含行首缩进

Output only one PlantUML code block
Briefly explain modifications outside the code block (if any downgrades)
Do not output redundant pseudo-code
Do not include leading indentation when outputting

常见问题

Frequently Asked Questions

渲染失败

Rendering Failure

检查是否有行首缩进
检查是否使用了不支持的语法
简化图表复杂度

Check for leading indentation
Check for unsupported syntax
Simplify diagram complexity

ArchiMate 不支持

ArchiMate Not Supported

飞书画板 PlantUML 版本较旧，ArchiMate sprite 不完整。建议改用组件图。

The PlantUML version in Feishu Board is relatively old, and ArchiMate sprites are incomplete. It is recommended to use component diagrams instead.

权限要求

Permission Requirements

```
board:board
```
- 画板读写（PlantUML 通过画板 API 导入）
```
docx:document
```
- 文档读写（通过 Markdown 导入时需要）

```
board:board
```
- Board read/write (PlantUML is imported via Board API)
```
docx:document
```
- Document read/write (required when importing via Markdown)