用途
本技能用于生成适配飞书画板的 PlantUML 图表，严格使用飞书画板的安全子集语法。当用户需要生成架构图、流程图或各类 UML 图时使用。
PlantUML 与 Mermaid 的选择
本项目同时支持 PlantUML 和 Mermaid，选择建议如下：
- 流程图、时序图、类图、ER 图、甘特图、饼图、思维导图、状态图：推荐 Mermaid，原因是飞书原生支持更好，成功率更高。
- 用例图、组件图、活动图（复杂分支）：推荐 PlantUML，原因是 Mermaid 不支持这些图类型。
- 需要精确控制图表布局：推荐 PlantUML，语法更灵活。
默认推荐 Mermaid，仅在 Mermaid 不支持的图类型时才使用 PlantUML。
图类型判断
根据用户描述自动选择图类型：
- 流程/步骤/审批/规则：活动图/流程图
- 调用链/接口交互/消息顺序：时序图
- 角色-功能：用例图
- 结构/类/关系：类图
- 组件/模块/技术路线图：组件图
- 架构图/分层架构：组件图（无 ArchiMate）
- 实体/字段/表关系：ER 图
- 思维导图/层级梳理：思维导图
安全子集规则
必须遵守：
- 使用 @startuml / @enduml 包裹（思维导图用 @startmindmap / @endmindmap）。
- 不要使用行首缩进——飞书画板将缩进的行视为独立行，导致解析失败。所有代码必须顶格书写（package/class 内部内容除外）。
- 避免 skinparam 样式指令。
- 避免 !define 预处理/宏指令。
- 避免颜色、字体、对齐控制。
- 避免方向控制指令（如 left to right direction）。
各图类型语法
活动图/流程图
@startuml
start
:步骤1;
if (条件?) then (是)
:步骤2;
else (否)
:步骤3;
endif
stop
@enduml
时序图
@startuml
participant 用户
participant 系统
用户 -> 系统: 请求
系统 --> 用户: 响应
@enduml
类图
@startuml
class 用户 {
id : int
name : string
login()
}
class 订单 {
id : int
amount : float
}
用户 --> 订单
@enduml
注意：避免可见性标记（+ - # ~）。
用例图
@startuml
actor 用户
(登录)
(注册)
用户 --> (登录)
用户 --> (注册)
@enduml
组件图
@startuml
package "前端" {
[Web App]
[Mobile App]
}
package "后端" {
[API Server]
[Database]
}
[Web App] --> [API Server]
[Mobile App] --> [API Server]
[API Server] --> [Database]
@enduml
ER 图
@startuml
entity 用户 {
*id : int
name : varchar
email : varchar
}
entity 订单 {
*id : int
user_id : int
amount : decimal
}
用户 ||--o{ 订单
@enduml
思维导图
@startmindmap
* 主题
** 分支1
*** 子分支1
*** 子分支2
** 分支2
@endmindmap
使用流程
- 分析用户需求：确定图类型。
- 生成 PlantUML：遵循安全子集。
- 输出代码块：仅输出一个代码块。
- 说明变更：如有降级或移除，简要说明。
导入到飞书文档
生成的 PlantUML 可以通过以下方式使用：
方式一：飞书画板直接粘贴
- 在飞书文档中插入画板。
- 点击“PlantUML”。
- 粘贴生成的代码。
方式二：通过 Markdown 导入
在 Markdown 中使用 plantuml 代码块：
@startuml
...
@enduml
然后使用 feishu-cli doc import 导入。
输出规范
- 只输出一个 PlantUML 代码块。
- 代码块外简短说明修改点（如有降级）。
- 不输出多余的伪代码。
- 输出时不要包含行首缩进。
常见问题
渲染失败：
- 检查是否有行首缩进。
- 检查是否使用了不支持的语法。
- 简化图表复杂度。
ArchiMate 不支持：
飞书画板 PlantUML 版本较旧，ArchiMate sprite 不完整。建议改用组件图。
权限要求
- board:board - 画板读写（PlantUML 通过画板 API 导入）。
- docx:document - 文档读写（通过 Markdown 导入时需要）。