PlantUML ASCII 图表生成器 - 命令行文本图表工具，支持序列图、类图、活动图

plantuml-ascii by github/awesome-copilot

7,600 周安装量

26,700 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/github/awesome-copilot --skill plantuml-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`

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

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

输出将保存为 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

<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 具有写入权限

🇺🇸English

PlantUML ASCII Art Diagram Generator

Overview

Create text-based ASCII art diagrams using PlantUML. Perfect for documentation in terminal environments, README files, emails, or any scenario where graphical diagrams aren't suitable.

What is PlantUML ASCII Art?

PlantUML can generate diagrams as plain text (ASCII art) instead of images. This is useful for:

Terminal-based workflows
Git commits/PRs without image support
Documentation that needs to be version-controlled
Environments where graphical tools aren't available

Installation

# macOS
brew install plantuml

# Linux (varies by distro)
sudo apt-get install plantuml  # Ubuntu/Debian
sudo yum install plantuml      # RHEL/CentOS

# Or download JAR directly
wget https://github.com/plantuml/plantuml/releases/download/v1.2024.0/plantuml-1.2024.0.jar

Output Formats

Flag	Format	Description
`-txt`	ASCII	Pure ASCII characters
`-utxt`	Unicode ASCII	Enhanced with box-drawing characters

Basic Workflow

1. Create PlantUML Diagram File

@startuml
participant Bob
actor Alice

Bob -> Alice : hello
Alice -> Bob : Is it ok?
@enduml

2. Generate ASCII Art

# Standard ASCII output
plantuml -txt diagram.puml

# Unicode-enhanced output (better looking)
plantuml -utxt diagram.puml

# Using JAR directly
java -jar plantuml.jar -txt diagram.puml
java -jar plantuml.jar -utxt diagram.puml

3. View Output

Output is saved as diagram.atxt (ASCII) or diagram.utxt (Unicode).

Diagram Types Supported

Sequence Diagram

@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

Class Diagram

@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

Activity Diagram

@startuml
start
:Initialize;
if (Is Valid?) then (yes)
  :Process Data;
  :Save Result;
else (no)
  :Log Error;
  stop
endif
:Complete;
stop
@enduml

State Diagram

@startuml
[*] --> Idle
Idle --> Processing : start
Processing --> Success : complete
Processing --> Error : fail
Success --> [*]
Error --> Idle : retry
@enduml

Component Diagram

@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

Use Case Diagram

@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

Deployment Diagram

@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

Command-Line Options

# Specify output directory
plantuml -txt -o ./output diagram.puml

# Process all files in directory
plantuml -txt ./diagrams/

# Include dot files (hidden files)
plantuml -txt -includeDot diagrams/

# Verbose output
plantuml -txt -v diagram.puml

# Specify charset
plantuml -txt -charset UTF-8 diagram.puml

Ant Task Integration

<target name="generate-ascii">
  <plantuml dir="./src" format="txt" />
</target>

<target name="generate-unicode-ascii">
  <plantuml dir="./src" format="utxt" />
</target>

Tips for Better ASCII Diagrams

Keep it simple : Complex diagrams don't render well in ASCII
Short labels : Long text breaks ASCII alignment
Use Unicode (-utxt): Better visual quality with box-drawing chars
Test before sharing : Verify in terminal with fixed-width font
Consider alternatives : For complex diagrams, use Mermaid.js or graphviz

Example Output Comparison

Standard ASCII (-txt):

     ,---.          ,---.
     |Bob|          |Alice|
     `---'          `---'
      |   hello      |
      |------------->|
      |              |
      |  Is it ok?   |
      |<-------------|
      |              |

Unicode ASCII (-utxt):

┌─────┐        ┌─────┐
│ Bob │        │Alice│
└─────┘        └─────┘
  │   hello      │
  │─────────────>│
  │              │
  │  Is it ok?   │
  │<─────────────│
  │              │

Quick Reference

# Create sequence diagram in ASCII
cat > seq.puml << 'EOF'
@startuml
Alice -> Bob: Request
Bob --> Alice: Response
@enduml
EOF

plantuml -txt seq.puml
cat seq.atxt

# Create with Unicode
plantuml -utxt seq.puml
cat seq.utxt

Troubleshooting

Problem : Garbled Unicode characters

Solution : Ensure terminal supports UTF-8 and has proper font

Problem : Diagram looks misaligned

Solution : Use fixed-width font (Courier, Monaco, Consolas)

Problem : Command not found

Solution : Install PlantUML or use Java JAR directly

Problem : Output file not created

Solution : Check file permissions, ensure PlantUML has write access

Weekly Installs

7.6K

Repository

github/awesome-copilot

GitHub Stars

26.7K

First Seen

Jan 23, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Installed on

gemini-cli7.5K

codex7.5K

opencode7.5K

github-copilot7.4K

cursor7.4K

amp7.4K