diagram-generator

ダイアグラムジェネレーター

ACTION REQUIRED（読了後すぐに実行）

1. NOW：現在のタスクがこの skill の適用範囲に該当するか確認する
2. NOW：../tool-index.md を読み、ツールの可用性と実際のパスを検証する
3. NEXT：ツールが不足している場合は bootstrap を呼び出す。パスを推測しない
4. ACT：「ワークフロー」の最初のステップに進んで実行する。確認状態で止まらない

Purpose

雑然とした入力や構造化された入力から、明確で編集可能なダイアグラムを作成します。結果をレビューし、バージョン管理し、洗練できるよう、まずテキストベースのダイアグラムソースを優先してください。画像や PDF をユーザーが求めた場合、またはダウンロード可能な成果物が実質的に役立つ場合にのみ、ファイルにレンダリングします。

デフォルトのワークフロー

1. ユーザーの意図、対象読者、ソース素材を特定します。
2. 以下の決定表を使用して、ダイアグラムの系統と言語を選択します。
3. ダイアグラムコードを書く前に、エンティティ、関係、ラベル、状態、分岐、時間・順序の情報を正規化します。
4. 簡潔で読みやすいダイアグラムソースを生成します。
5. 構文を頭の中で検証し、ファイルを作成する場合は scripts/render_diagram.py を実行します。
6. ダイアグラムソースと、前提に関する短い注記を返します。ファイルを生成した場合は、出力ファイルへのリンクを含めます。

明確化を求めすぎないでください。リクエストの指定が不十分な場合は、妥当な前提を置き、それらを簡潔に示してください。

ダイアグラム言語の決定表

別の言語の方が明らかに適している場合を除き、Mermaid を使用してください。

ユーザーの要望	推奨	理由
プロセスフロー、デシジョンツリー、シンプルなスイムレーン	Mermaid flowchart	読みやすく、Markdown に貼り付けやすい
システムとユーザーのインタラクションのシーケンス	Mermaid sequenceDiagram または PlantUML sequence	ドキュメントには Mermaid、UML の形式性には PlantUML
ライフサイクル、状態機械、遷移	Mermaid stateDiagram-v2 または PlantUML state	簡潔な遷移構文
データベーススキーマ、エンティティ、関係	Mermaid erDiagram	移植性の高い ER 記法
クラス・インターフェース・オブジェクトモデル	Mermaid classDiagram または PlantUML class	ドキュメントには Mermaid、詳細な UML には PlantUML
プロジェクトスケジュール	Mermaid gantt	簡潔なタイムライン構文
階層、アイデア、メモ	Mermaid mindmap	アイデアマップの有力なデフォルト
顧客・製品ジャーニー	Mermaid journey	組み込みのジャーニー記法
git 履歴	Mermaid gitGraph	組み込みの git 記法
依存関係グラフ、パッケージグラフ、大規模ネットワーク	Graphviz DOT	密なグラフに対する優れたレイアウトエンジン
レイヤー、クラスター、境界を持つアーキテクチャ	サブグラフ付き Mermaid flowchart、Graphviz クラスター、または PlantUML C4 スタイル	求められる忠実度に応じて選択
重み付きフロー・サンキー的な関係	サポートされていれば Mermaid sankey-beta、それ以外は SVG または Graphviz	Mermaid のサポートはレンダラーによって異なる場合がある
ソース言語が適合しにくいカスタムビジュアル	SVG	レイアウトとスタイリングを正確に制御

出力ポリシー

• ユーザーが画像のみを明示的に求めた場合を除き、常に編集可能なソースを提供してください。
• デフォルトでは、最適なダイアグラムを 1 つ提示してください。代替案は、本当に役立つ場合にのみ提示します。
• 古い Mermaid/PlantUML バージョンでレンダリングされない可能性がある凝った機能よりも、安定したシンプルな構文を優先してください。
• 短いラベルを使用してください。長いテキストは、必要に応じてダイアグラムの外の注記に分割します。
• 曖昧なノード ID は避けてください。ASCII の ID と人間が読めるラベルを使用します。
• ユーザーの用語を維持しつつ、1 つのダイアグラム内では大文字と小文字の使い方を統一してください。
• 技術的なダイアグラムでは、暗黙に存在する場合はクライアント、サービス、データベース、キュー、外部 API、オペレーター・ユーザーといった境界を含めてください。
• ビジネスプロセスのダイアグラムでは、存在する場合はハッピーパス、決定ポイント、失敗、リトライ、手動ステップを区別してください。
• 不確実なテキストから作成したダイアグラムでは、コードの後に Assumptions セクションを含めてください。

Mermaid 生成ルール

簡潔なテンプレートについては references/diagram-patterns.md を参照してください。

Mermaid の一般的なルール:

• 正しい図のディレクティブで始めてください。たとえば flowchart TD、sequenceDiagram、erDiagram、gantt、mindmap、journey などです。
• フローチャートでは、ユーザーが左から右を希望しない限り flowchart TD を使用してください。アーキテクチャやパイプラインには flowchart LR を使用してください。
• スイムレーンやアーキテクチャのレイヤーにはサブグラフを使用してください。サブグラフには読みやすいラベルを付けてください。
• ノード ID は安定した ASCII のみにしてください。たとえば ingest_service[Ingest Service] のようにします。
• パーサーを混乱させやすい句読点を含むラベルは引用符で囲んでください。
• 分岐には判断ひし形を使用してください: decision{Condition?}。
• 一貫したエッジラベルを使用してください: -- yes -->、-- no -->、-. async .->、または意味がある場合にのみ == critical ==>。
• シーケンス図では、メッセージの前に参加者を宣言してください。人間には actor を、システムには participant を使用してください。
• 条件分岐、オプション、繰り返し、並列フローには alt/else/end、opt/end、loop/end、par/and/end ブロックを使用してください。

Graphviz DOT 生成ルール

大規模で密な、またはレイアウトに敏感な関係図には Graphviz を使用してください。

• 有向関係には digraph G を、無向ネットワークには graph G を優先してください。
• レイアウトに適したグラフ属性を先頭で設定してください: rankdir=LR、nodesep、ranksep、および役立つ場合は splines=true。
• 境界やサブシステムには subgraph cluster_name を使用してください。
• プレーンなラベルと控えめなスタイルを使用してください。
• エッジラベルは意味を追加する場合にのみ使用してください。
• ノードが多い場合は、クラスタでドメインごとにグループ化し、交差の多い全対全エッジを避けてください。

PlantUML 生成ルール

ユーザーが UML を求めたり、正式な UML 記法を必要とする場合は PlantUML を使用してください。

• 図を @startuml と @enduml で囲んでください。
• 役立つ場合は actor、participant、database、queue、collections、または component ステレオタイプを使用してください。
• アーキテクチャの境界には package、rectangle、または node を使用してください。
• クラス図では、ユーザーが網羅的な詳細を求めない限り、重要なフィールド/メソッドのみを含めてください。
• アクティビティ図では、明確な開始/終了マーカーと明示的な分岐ラベルを使用してください。

SVG 生成ルール

テキスト図言語では要求されたビジュアルを確実に表現できない場合にのみ、SVG を使用してください。

• SVG はシンプルで、アクセシブルで、編集可能に保ってください。
• <title> と意味のあるテキストラベルを含めてください。
• 複雑なパスよりも、長方形、線、矢印、グループを優先してください。
• 外部フォントやリモート画像を埋め込まないでください。

ファイルのレンダリング

ユーザーが PNG/SVG/PDF を求めた場合、ソースファイルを作成して次を実行してください:

python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.mmd --format svg --out output.svg
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.dot --format png --out output.png
python "<SKILL_ROOT>/diagram-generator/scripts/render_diagram.py" input.puml --format svg --out output.svg

<SKILL_ROOT> はこのパッケージの skills/ ディレクトリの実際のパスであり、AI が自動検出する必要があります。

レンダラーは意図的に依存関係を許容する設計です。一般的なローカルツールを試し、レンダラーが利用できない場合は実行可能なインストールのヒントを報告します。スクリプトが正常に完了し、出力ファイルが存在しない限り、画像がレンダリングされたと主張しないでください。

検証チェックリスト

最終化する前に:

• 図の種類がユーザーのタスクに一致している。
• ソースが選択した言語として構文的に妥当である。
• ラベルが収まる程度に短い。
• エッジとメッセージの順序が入力を正確に反映している。
• 入力が不完全だった場合は前提を明示している。
• 生成されたファイルについては、出力が存在し、開けるか、サイズがゼロでない。

一般的な応答テンプレート

ほとんどの図の回答にはこの構造を使用してください:

下面是可编辑的 [language] 版本：

```[language]
[source]

前提:

• [必要な場合のみ]

レンダリングされたファイル: [リンク] [生成された場合のみ]

For English user requests, respond in English. For Chinese user requests, respond in Chinese unless they ask otherwise.

---

## 按需自举（On-Demand Bootstrap）

### 自动化能力边界

| 工具 | 可自动安装 | 安装方式 | 说明 |
|------|-----------|---------|------|
| Mermaid CLI (mmdc) | ✓ | npm install -g @mermaid-js/mermaid-cli | 渲染 Mermaid 为 PNG/SVG |
| Graphviz (dot) | ✗ | 手动安装 | https://graphviz.org/download/ |
| PlantUML | ✗ | 需要 Java + plantuml.jar | https://plantuml.com/download |
| Python (render script) | ✓ | 已在 bootstrap 中 | `scripts/render_diagram.py` 依赖 |

### 说明

本 skill 主要输出文本格式的图表源码（Mermaid/DOT/PlantUML），不一定需要本地渲染工具。只有当用户明确要求生成 PNG/SVG/PDF 文件时才需要对应的渲染器。

如果渲染器不可用，`scripts/render_diagram.py` 会输出安装提示而不是报错。

---

## 路由上下文

**上游入口**: `skills/SKILL.md`（总控）、`routing.md`
**触发条件**: 用户说"画图"、"流程图"、"架构图"、"攻击路径图"、"时序图"、"Mermaid"、"Graphviz"、"PlantUML"
**下游出口**:
- 生成的图表可嵌入 `docs-generator/` 的报告中
- 攻击路径图可配合 `pentest-tools/` 的渗透报告

**同级关联模块**: `docs-generator/`（报告中嵌入图表）


## 任务完成自检（声称完成前 MUST 通过）

- [ ] 我是否执行了工作流中的每一步（而不是只阅读）？
- [ ] 我是否基于 `tool-index` 使用了真实工具路径？
- [ ] 我是否产出了可复现证据（命令/脚本/截图/报告）？
- [ ] 我是否完成并回写了 RULES 要求的 Checklist 项？