Plantuml Renderer

PlantUML Renderer

将包含 PlantUML 代码的输入渲染为图表文件，支持文本输入与文件输入。

使用场景

• 用户明确要求“渲染 PlantUML / 生成 UML 图 / 导出 svg/png/txt/utxt”。
• 用户提供了任意包含有效 PlantUML 代码块（@startuml ... @enduml）的内容。
• 输入不一定是 .puml，也可以是 Markdown、Word 文档提取文本等。

前提条件（必须先检查）

1. 必须验证 Java 可用：

   java -version

2. 必须确认 JAR 存在：./assets/plantuml.jar 3. 如果缺少 Java 或 JAR，停止渲染并明确告知缺失项。

标准工作流

1. 接收输入

• 支持两类输入：
• 用户直接粘贴的文本。
• 用户提供的文件路径。

2. 提取 PlantUML 代码

• 从输入中提取完整 @startuml ... @enduml 代码块。
• 若没有任何有效代码块，返回明确错误并提示用户补充有效 PlantUML 代码。

3. 确认输出格式

• 询问用户输出格式（如 svg、png、txt、utxt）。
• 用户未指定时，默认使用 svg。

4. 构造渲染命令

• 命令参数需参考 ./references/cli_man.txt。
• 推荐使用 --format <name>，也可使用 --svg / --png / --txt / --utxt。

5. 执行渲染并生成文件

• 默认输出命名规则：
• 如果输入是文件：<input_filename>.<format>
• 如果输入是粘贴文本：output.<format>
• 若一个输入中有多个 @startuml 块，PlantUML 可能按 _001、_002 追加后缀输出，属于正常行为。

6. 清理中间文件

• 渲染完成后，删除过程中产生的所有中间文件，仅保留最终目标输出文件。
• 需清理的中间文件包括：
• 为粘贴文本输入临时创建的 .puml 文件。
• PlantUML 渲染过程中产生的临时文件或辅助文件（如 .cmapx 等）。
• 不得删除的文件：
• 用户原始输入文件（无论是 .puml、.md 还是其他格式）。
• 最终目标输出文件（如 .svg、.png、.atxt、.utxt）。
• 清理前应先确认目标输出文件已成功生成。

7. ASCII 文本格式特例

• 当输出格式是 txt 或 utxt（纯文本图）时，必须参考：
• ./references/ascii_guide.md
• 输出扩展名通常为 .atxt 或 .utxt，应在结果说明中明确实际生成文件名。

命令模板

以下命令均以技能目录为当前工作目录为前提。

文件输入

java -jar "./assets/plantuml.jar" --format svg "<input_file>"
java -jar "./assets/plantuml.jar" --format png "<input_file>"
java -jar "./assets/plantuml.jar" --format txt "<input_file>"
java -jar "./assets/plantuml.jar" --format utxt "<input_file>"

文本输入（通过 stdin）

java -jar "./assets/plantuml.jar" --svg -pipe > "output.svg"

如需 ASCII：

java -jar "./assets/plantuml.jar" --txt -pipe > "output.atxt"
java -jar "./assets/plantuml.jar" --utxt -pipe > "output.utxt"

关键规则

• 优先保证“提取代码块 + 正确格式 + 成功落盘”三件事。
• 不要假设输入是完整 .puml 文件；只要代码块有效就应处理。
• 若命令执行失败，返回原始错误并给出可操作修复建议（Java、JAR 路径、语法错误、Graphviz 依赖等）。
• 对语法检查可使用：

  java -jar "./assets/plantuml.jar" --check-syntax "<input_file_or_dir>"

快速检查清单

• [ ] java -version 成功
• [ ] ./assets/plantuml.jar 存在
• [ ] 已提取至少一个有效 @startuml ... @enduml
• [ ] 已确认输出格式（默认 svg）
• [ ] 已执行渲染命令并确认输出文件存在
• [ ] 若为 txt/utxt，已参考 ./references/ascii_guide.md
• [ ] 已清理所有中间文件，仅保留目标输出文件

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

Output Formats

Basic Workflow

1. 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

2. 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

Tips for Better ASCII Diagrams

1. Keep it simple: Complex diagrams don't render well in ASCII 2. Short labels: Long text breaks ASCII alignment 3. Use Unicode (`-utxt`): Better visual quality with box-drawing chars 4. Test before sharing: Verify in terminal with fixed-width font 5. 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