SKILL.md
readonly只读
name
plantuml-ascii
description
使用PlantUML文本模式生成ASCII艺术图。当用户要求创建ASCII图、基于文本的图、终端友好图，或提到plantuml ascii、text diagram、ascii art diagram时使用。支持：将PlantUML图转换为ASCII艺术，创建序列图、类图、ASCII格式的流程图，使用-utxt标志生成Unicode增强的ASCII艺术。
PlantUML ASCII艺术图生成器
概述
使用PlantUML创建基于文本的ASCII艺术图。非常适合终端环境、README文件、电子邮件或任何不适合使用图形图的场景中的文档。
什么是PlantUML ASCII艺术？
PlantUML可以生成纯文本（ASCII艺术）图而不是图像。这在以下场景中非常有用：
- 基于终端的工作流
- 不支持图像的Git提交/PR
- 需要进行版本控制的文档
- 没有图形工具的环境
安装
# macOS
brew install plantuml
# Linux（因发行版而异）
sudo apt-get install plantuml # Ubuntu/Debian
sudo yum install plantuml # RHEL/CentOS
# 或直接下载JAR
wget https://github.com/plantuml/plantuml/releases/download/v1.2024.0/plantuml-1.2024.0.jar
输出格式
| 标志 | 格式 | 描述 |
|---|---|---|
-txt |
ASCII | 纯ASCII字符 |
-utxt |
Unicode ASCII | 使用制表符增强 |
基本工作流
1. 创建PlantUML图文件
@startuml
participant Bob
actor Alice
Bob -> Alice : hello
Alice -> Bob : Is it ok?
@enduml
2. 生成ASCII艺术
# 标准ASCII输出
plantuml -txt diagram.puml
# Unicode增强输出（更好看）
plantuml -utxt diagram.puml
# 直接使用JAR
java -jar plantuml.jar -txt diagram.puml
java -jar plantuml.jar -utxt diagram.puml
3. 查看输出
输出保存为 diagram.atxt（ASCII）或 diagram.utxt（Unicode）。
支持的图类型
序列图
@startuml
actor User
participant "Web App" as App
database "Database" as DB
User -> App : Login Request
App -> DB : Validate Credentials
DB --> App : User Data
App --> User : Auth Token
@enduml
类图
@startuml
class User {
+id: int
+name: string
+email: string
+login(): bool
}
class Order {
+id: int
+total: float
+items: List
+calculateTotal(): float
}
User "1" -- "*" Order : places
@enduml
活动图
@startuml
start
:Initialize;
if (Is Valid?) then (yes)
:Process Data;
:Save Result;
else (no)
:Log Error;
stop
endif
:Complete;
stop
@enduml
状态图
@startuml
[*] --> Idle
Idle --> Processing : start
Processing --> Success : complete
Processing --> Error : fail
Success --> [*]
Error --> Idle : retry
@enduml
组件图
@startuml
[Client] as client
[API Gateway] as gateway
[Service A] as svcA
[Service B] as svcB
[Database] as db
client --> gateway
gateway --> svcA
gateway --> svcB
svcA --> db
svcB --> db
@enduml
用例图
@startuml
actor "User" as user
actor "Admin" as admin
rectangle "System" {
user -- (Login)
user -- (View Profile)
user -- (Update Settings)
admin -- (Manage Users)
admin -- (Configure System)
}
@enduml
部署图
@startuml
actor "User" as user
node "Load Balancer" as lb
node "Web Server 1" as ws1
node "Web Server 2" as ws2
database "Primary DB" as db1
database "Replica DB" as db2
user --> lb
lb --> ws1
lb --> ws2
ws1 --> db1
ws2 --> db1
db1 --> db2 : replicate
@enduml
命令行选项
# 指定输出目录
plantuml -txt -o ./output diagram.puml
# 处理目录中的所有文件
plantuml -txt ./diagrams/
# 包含点文件（隐藏文件）
plantuml -txt -includeDot diagrams/
# 详细输出
plantuml -txt -v diagram.puml
# 指定字符集
plantuml -txt -charset UTF-8 diagram.puml
Ant任务集成
<target name="generate-ascii">
<plantuml dir="./src" format="txt" />
</target>
<target name="generate-unicode-ascii">
<plantuml dir="./src" format="utxt" />
</target>
更好的ASCII图技巧
- 保持简单：复杂的图在ASCII中渲染效果不佳
- 短标签：长文本会破坏ASCII对齐
- 使用Unicode（
-utxt）：使用制表符获得更好的视觉质量 - 分享前测试：在等宽字体的终端中验证
- 考虑替代方案：对于复杂图，使用Mermaid.js或graphviz
示例输出对比
标准ASCII（-txt）：
,---. ,---.
|Bob| |Alice|
`---' `---'
| hello |
|------------->|
| |
| Is it ok? |
|<-------------|
| |
Unicode ASCII（-utxt）：
┌─────┐ ┌─────┐
│ Bob │ │Alice│
└─────┘ └─────┘
│ hello │
│─────────────>│
│ │
│ Is it ok? │
│<─────────────│
│ │
快速参考
# 创建ASCII序列图
cat > seq.puml << 'EOF'
@startuml
Alice -> Bob: Request
Bob --> Alice: Response
@enduml
EOF
plantuml -txt seq.puml
cat seq.atxt
# 使用Unicode创建
plantuml -utxt seq.puml
cat seq.utxt
故障排除
问题：乱码的Unicode字符
- 解决方案：确保终端支持UTF-8并具有合适的字体
问题：图看起来不对齐
- 解决方案：使用等宽字体（Courier、Monaco、Consolas）
问题：找不到命令
- 解决方案：安装PlantUML或直接使用Java JAR
问题：未创建输出文件
- 解决方案：检查文件权限，确保PlantUML有写权限
