puml-plantuml

PUML-PlantUML エキスパートスキル

PlantUML に関する深い知識（公式リファレンスの全 27 章）＋クロスプラットフォームの ローカルレンダリング＋画像から PUML へのリバースエンジニアリング。オフラインでレンダリングできます。 あらゆる OS に対応します。パスを前提としません。Python、Java、PlantUML を完全自動で検出し、インストールします。

---

クイック判断ツリー

User request
├── "Create/draw a diagram from description"   → § Generate PUML
├── "Convert image/screenshot to PUML"         → § Image → PUML
├── "Render/preview/generate image from code"  → § Render Locally
├── "Fix/debug my PUML"                        → § Diagnose & Fix
└── "Explain syntax / how do I..."             → references/syntax-quick-ref.md

---

§ 初回実行 — ゼロからのセットアップ

ブートストラップスクリプトの実行に、事前にインストールされたツールは不要です。Python → Java → PlantUML の順にインストールします。マシンごとに一度実行してください。

macOS / Linux

bash scripts/bootstrap.sh           # install everything
bash scripts/bootstrap.sh --verify  # install + test render

Windows（PowerShell — Windows 10/11 に組み込み済み）

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\bootstrap.ps1
.\scripts\bootstrap.ps1 -Verify

Python がすでに利用可能な場合

python3 scripts/render.py --detect      # show what's detected
python3 scripts/setup.py               # install Java + PlantUML
python3 scripts/setup.py --java        # ensure Java only
python3 scripts/setup.py --jar         # force JAR download
python3 scripts/setup.py --verify      # install + test render
python3 scripts/render.py --install-hint  # show manual steps

インストールされるもの：

コンポーネント	macOS	Linux	Windows
Python 3.9+	brew	apt/dnf/pacman/snap	winget/choco/scoop
Java JRE 11+	brew cask temurin	apt/dnf/pacman	winget Temurin/Zulu
PlantUML	brew	apt/dnf/pacman/snap	winget/choco/scoop
フォールバック	—	~/.plantuml/plantuml.jar	~/.plantuml/plantuml.jar

Java は次の場所から検出されます：$JAVA_HOME、PATH、macOS の /usr/libexec/java_home、 Azul/Zulu（zulu*）、Temurin、Homebrew OpenJDK、SDKMAN、/usr/lib/jvm/*。

---

§ 説明から PUML を生成する

ステップ 1 — 図の種類を特定する：

リクエスト内のキーワード	種類	タグ
呼び出しのシーケンス、API フロー、メッセージ	シーケンス	@startuml
クラス、OOP、継承、メソッド	クラス	@startuml
プロセス、ワークフロー、フローチャート、ステップ	アクティビティ（新）	@startuml
アーキテクチャ、サービス、コンポーネント	コンポーネント	@startuml
データベース、スキーマ、テーブル、エンティティ	ER	@startuml
状態、ライフサイクル、ステータス遷移	状態	@startuml
ユースケース、アクター、ユーザーストーリー	ユースケース	@startuml
オブジェクト、インスタンス、実行時スナップショット	オブジェクト	@startuml
タイミング、シグナル、波形	タイミング	@startuml
ブレインストーミング、概念マップ、トピック	マインドマップ	@startmindmap
プロジェクトのタイムライン、スケジュール、マイルストーン	ガント	@startgantt
作業分解、プロジェクトのフェーズ	WBS	@startwbs
UI フォーム、ワイヤーフレーム、モックアップ	Salt	@startsalt
JSON データ構造	JSON	@startjson
YAML データ構造	YAML	@startyaml
ネットワークトポロジー、サーバー、サブネット	nwdiag	@startuml + nwdiag {}
エンタープライズアーキテクチャ、ArchiMate	Archimate	@startuml + archimate kw
数式、方程式、LaTeX	数式	@startmath / @startlatex
ASCII アート図	Ditaa	@startditaa

ステップ 2 — 生成する： references/syntax-quick-ref.md に記載された完全な構文を使用します。 必ず次を含めてください：title 行、skinparam shadowing false、すべての矢印のラベル。

ステップ 3 — 記述、検証、レンダリング：

cat > /tmp/diagram.puml << 'PUML'
@startuml
title My Diagram
... generated code ...
@enduml
PUML

python3 scripts/render.py /tmp/diagram.puml --check   # validate
python3 scripts/render.py /tmp/diagram.puml -f svg -o /tmp/  # render

---

§ 画像 → PUML（リバースエンジニアリング）

1. 画像を確認する — view ツールを使用するか、アップロードされた画像を調べます
2. 図の種類を特定する — references/image-to-puml.md
3. 要素を抽出する — 名前、ラベル、矢印、関係、カーディナリティ
4. PUML を生成する — 正確に再現し、適切な矢印の種類を使用します
5. 検証してレンダリングする — 元の画像と比較し、必要に応じて調整します

視覚分析ガイド：references/image-to-puml.md

---

§ ローカルでレンダリングする

scripts/render.py を使用します。バイナリと JAR+Java のいずれにも対応し、あらゆる OS で自動検出します。

# macOS / Linux
python3 scripts/render.py diagram.puml                        # PNG
python3 scripts/render.py diagram.puml -f svg -o ./output/   # SVG
python3 scripts/render.py diagram.puml -f pdf -o ./output/   # PDF
cat diagram.puml | python3 scripts/render.py --stdin -f svg -n "name" -o /tmp/

# Windows
py scripts\render.py diagram.puml
py scripts\render.py diagram.puml -f svg -o .\output\

直接 CLI を使用する場合（plantuml が PATH にある場合）：

plantuml -tsvg diagram.puml
plantuml -tpng -o ./output/ *.puml
plantuml -checkonly diagram.puml

レンダリング後、present_files を使用して出力ファイルをユーザーに提示します。

オプション、環境変数、形式、トラブルシューティングの詳細：references/local-rendering.md

---

§ PUML の診断と修正

python3 scripts/render.py diagram.puml --check

エラー	原因	修正方法
No @startuml found	ラッパーの不足	@startuml / @enduml を追加します
Unknown command	タイプミスまたは誤った図の種類	syntax-quick-ref.md を確認します
矢印 →（Unicode）	ASCII が必要です	→ ではなく -> を使います
Cannot find class	前方参照	使用する前に宣言します
Graphviz エラー	dot がインストールされていません	brew/apt install graphviz を実行するか、!pragma layout smetana を追加します
PlantUML が見つかりません	インストールされていません	bash scripts/bootstrap.sh を実行します
Java が検出されません	標準以外の JDK	JAVA_HOME 環境変数を設定します
Python が見つかりません	Python がありません	bash scripts/bootstrap.sh を実行します
Unicode が正しく表示されません	文字セットの問題	plantuml -charset UTF-8 file.puml を実行します

---

§ 構文早見表（超クイック）

全リファレンス（全 27 章、2700 行以上）：references/syntax-quick-ref.md

シーケンス図の矢印：

->   sync          -->  response/dashed
->>  thin           -->> thin dashed
->x  lost           ->o  open arrowhead
<->  bidirectional  ->+  activate   -->-  deactivate
[->  incoming      ->]   outgoing

クラスの関係：

<|--  inheritance    <|..  realization
o--   aggregation    *--   composition
-->   dependency     ..>   usage
--    association    --()  lollipop (provided interface)
"1" *-- "0..*"  : label  (with cardinality and label)

ER 図の多重度（クロウズフット）：

||   exactly one    o|   zero or one
o{   zero or more   |{   one or more

すべての @start タグ：

@startuml          most diagrams
@startmindmap      mind maps
@startgantt        gantt charts
@startwbs          work breakdown
@startsalt         wireframes
@startjson         JSON display
@startyaml         YAML display
@startmath         AsciiMath
@startlatex        LaTeX formula
@startditaa        Ditaa ASCII art

共通の書式設定：

title My Title
skinparam shadowing false
skinparam monochrome true
!theme cerulean
left to right direction
!pragma layout smetana    ' no Graphviz needed

---

完全な図の網羅（PDF の全 27 章）

Ch	種類	備考
1	シーケンス	完全対応：矢印、グループ、アクティベーション、ノート、自動番号付け、メインフレーム、並列処理、ステレオタイプ／スポット、アンカー、包囲、フットボックスの非表示
2	ユースケース	完全対応：アクター、extends/include、ノート、パッケージ、ビジネス UC、JSON オーバーレイ
3	クラス	完全対応：可視性、ステレオタイプ、スポット、ジェネリクス、ロリポップ、extends/implements キーワード、hide/show/remove、$tags、名前空間
4	オブジェクト	インスタンス、関係、マップ、関連オブジェクト
5	アクティビティ（旧形式）	旧 (*) --> 構文、分岐、同期バー、パーティション
6	アクティビティ（新形式）	start/stop、if/else/elseif、switch/case、while、repeat、fork、split、スイムレーン、SDL 形状、goto/label、コネクター、条件スタイル
7	コンポーネント	コンポーネント、インターフェース、ボール・ソケット、グループ化、ポート、未接続要素の非表示
8	配置	すべての要素タイプ、ネスト、ポート、角丸、向き
9	状態	ネスト、並行状態、fork/join、履歴、選択、ピン、展開、リンク上のノート、インラインカラー
10	タイミング	robust、concise、binary、clock、analog、相対時間、アンカー、ハイライト
11	JSON	表示、ハイライト、スタイル、最小限の例
12	YAML	表示、ハイライト、エイリアス、Creole
13	ネットワーク（nwdiag）	ネットワーク、ノード、アドレス、グループ化、スプライト、ピアネットワーク
14	ワイヤーフレーム（Salt）	すべてのウィジェット：ボタン、入力、ドロップダウン、ラジオボタン、チェックボックス、グリッド、ツリー、タブ、グループボックス、スクロールボックス
15	Archimate	archimate キーワード、ジャンクション、マクロ、StdLib との統合
16	ガント	タスク、制約、マイルストーン、色、完了率、ハイパーリンク、休業日、ズーム、スケール
17	マインドマップ	OrgMode および Markdown 構文、左向きのブランチ、複数ルート、色、方向
18	WBS	OrgMode 構文、方向、色、矢印、ワードラップ
19	数式	AsciiMath（@startmath）、LaTeX/JLaTeXMath（@startlatex）、インライン <math> タグ
20	ER（情報工学）	エンティティ、属性、PK/FK マーカー、カラスの足記法による関係
21	共通コマンド	コメント、scale/zoom、title、caption、header、footer、legend、newpage、mainframe、appendix、pragma
22	Creole	太字、斜体、等幅、取り消し線、下線、波線、リスト、見出し、表、リンク、絵文字、HTML タグ、Unicode
23	スプライト	16 進スプライトの定義、インライン SVG スプライト、StdLib からのインポート、OpenIconic、Font Awesome
24	Skinparam	要素ごとの完全な skinparam + CSS 風の最新 <style> 代替 + すべてのテーマ
25	プリプロセッサ	変数、条件、while/loop、プロシージャ、関数、デフォルト引数、引用符なし、キーワード引数、include、サブパート、テーマ、define、組み込み関数（%string、%strlen、%date、%random、%hsl_color など）
26	Unicode	ネイティブ UTF-8、&#XXXX; および <U+XXXX> 参照、絵文字 <:name:>、文字セットフラグ
27	StdLib	ArchiMate、AWS、Azure、C4、Kubernetes、Elastic、GCP、CloudOgu、Tupadr3/FontAwesome、EDGY
—	Ditaa	@startditaa の ASCII アートから図への変換

---

参照ファイル

ファイル	内容
references/syntax-quick-ref.md	2700 行以上 — 全 27 章の完全な構文
references/image-to-puml.md	画像から PUML へのリバースエンジニアリングのための視覚分析ガイド
references/local-rendering.md	セットアップ、CLI フラグ、形式、環境変数、トラブルシューティング

スクリプト

スクリプト	目的
scripts/bootstrap.sh	ここから開始 — macOS/Linux — Python→Java→PlantUML をインストール（依存関係なし）
scripts/bootstrap.ps1	ここから開始 — Windows — PowerShell 5 以降、依存関係は不要
scripts/setup.py	Python セットアップ：Java と PlantUML を検出／インストールし、Python も報告
scripts/render.py	クロスプラットフォームのレンダリング：Python／バイナリ／JAR／Java を自動検出