diagram-generator

図表ジェネレーター

自然言語の説明から、プロフェッショナルなダークテーマの SVG アーキテクチャ図、フローチャート、シーケンス図などを生成します。

概要

ユーザーの説明に基づいて、レンダリング可能な SVG 図表ファイルを自動生成します。セマンティックカラー、フォント規則、間隔ルール、コンポーネントパターンを含む完全なデザインシステムを使用し、中国語に対応した単一の自己完結型 SVG ファイルを出力します。

使用する場合

• ユーザーがアーキテクチャ図、フローチャート、シーケンス図の作成を希望している
• ユーザーが図表、フローチャート、アーキテクチャ、ER 図、クラス図、組織図について言及している
• ユーザーがシステム設計、データフロー、API 呼び出しチェーンを可視化したい
• ユーザーが「图を描いて」／「アーキテクチャ図を描いて」／「draw diagram」と言っている
• ユーザーが /diagram-generator を入力している
• ユーザーがマインドマップやブレインストーミング図を描きたい
• ユーザーがステートマシンやライフサイクルを可視化したい
• ユーザーがプロジェクトのタイムラインやマイルストーンチャートを作成したい
• ユーザーがデータパイプラインや ETL フローを図示したい
• ユーザーがイベント駆動型アーキテクチャを文書化したい

使用しない場合：

• ユーザーがコード構造の確認のみを希望している（AST 分析を使用）
• ユーザーが UI プロトタイプ／ワイヤーフレームを希望している（Figma、Sketch、Adobe XD を使用）
• ユーザーが既存の図表を編集したい（元のファイルを提供）
• ユーザーがインタラクティブな図表を作成したい（D3.js または Mermaid を検討）
• ユーザーがデータから図表を生成したい（Chart.js などのチャートライブラリを使用）

基本パターン

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

ユーザーの説明に含まれるキーワード	図表の種類	参考ファイル
アーキテクチャ、コンポーネント、デプロイ、システム	Architecture	references/architecture.md
フロー、ステップ、判定、意思決定	Flowchart	references/flowchart.md
呼び出し、リクエスト、レスポンス、インタラクション	Sequence	references/sequence.md
クラス、継承、実装、ER、関係	Structural	references/structural.md
思考、ブレインストーミング、テーマ	Mind Map	—
タイムライン、履歴、スケジュール	Timeline	—
状態、ライフサイクル、遷移	State Machine	—

ステップ 2：情報を収集する

# 如果是项目架构图，先扫描项目结构
ls -la
find . -name "*.ts" -o -name "*.go" -o -name "*.py" | head -20
cat package.json 2>/dev/null | python3 -c "import sys,json; d=json.load(sys.stdin); print(list(d.get('dependencies',{}).keys())[:10])" 2>/dev/null

抽出する情報：

• プロジェクトの種類と技術スタック
• モジュール／サービスの区分
• データの流れ
• 外部依存関係

ステップ 3：参考ファイルを読む

描画を始める前に、該当する図表の種類に対応する参考ファイルを読みます。

# 确定 skill 目录路径
SKILL_DIR="<skill-install-path>/diagram-generator"

# 读取对应类型的参考文件
cat $SKILL_DIR/references/architecture.md   # 架构图
cat $SKILL_DIR/references/flowchart.md      # 流程图
cat $SKILL_DIR/references/sequence.md       # 时序图
cat $SKILL_DIR/references/structural.md     # 结构图

ステップ 4：レイアウトを計画する

描画する前に、すべてのコンポーネントを列挙し、配置を計算します。

1. すべてのコンポーネントを列挙する — 名前、種類、分類
2. グループを決める — 同じ階層／領域に属するコンポーネント
3. 位置を計算する — 参考ファイルのレイアウトアルゴリズムに従って座標を割り当てる
4. 流れる方向を決める — LTR または TTB

Step 5: 生成 SVG

⚠️ 关键顺序：先写所有内容，最后算 viewBox。

执行步骤：

1. 先写 <svg> 标签，viewBox 暂时留空：<svg xmlns="..." viewBox="0 0 0 0">
2. 按分层顺序写所有内容（背景→边界→箭头→遮罩→组件→文字→图例→标题）
3. 全部写完后，扫描所有元素的坐标，计算实际 viewBox
4. 回去修改 <svg> 标签的 viewBox 值

SVG 分层顺序（从底到顶）：

1. 背景填充 + 网格
2. 区域/组边界（虚线）— 边界也是元素，有自己的 x/y/width/height
3. 连接箭头和线
4. 不透明遮罩矩形（与组件框同位置）
5. 组件框（半透明填充 + 描边）
6. 文字标签
7. 图例 — 在所有内容下方
8. 标题块

设计系统：

类别	填充 (rgba)	描边	用途
Primary	rgba(8, 51, 68, 0.4)	#22d3ee (cyan)	前端、用户界面、输入
Secondary	rgba(6, 78, 59, 0.4)	#34d399 (emerald)	后端、服务、处理
Tertiary	rgba(76, 29, 149, 0.4)	#a78bfa (violet)	数据库、存储、持久化
Accent	rgba(120, 53, 15, 0.3)	#fbbf24 (amber)	云、基础设施、区域
Alert	rgba(136, 19, 55, 0.4)	#fb7185 (rose)	安全、错误、警告
Connector	rgba(251, 146, 60, 0.3)	#fb923c (orange)	总线、队列、中间件
Neutral	rgba(30, 41, 59, 0.5)	#94a3b8 (slate)	外部、通用、未知
Highlight	rgba(59, 130, 246, 0.3)	#60a5fa (blue)	活动状态、焦点

字体规范：

• 标题：16px, weight 700
• 组件名：11-12px, weight 600
• 描述/子标签：9px, weight 400, color #94a3b8
• 注释：8px, weight 400
• 箭头标签：7-8px

中文支持： 当标签包含中文时，使用 font-family: 'JetBrains Mono', 'Noto Sans SC', 'PingFang SC', sans-serif' 并增加组件框宽度。

间距规则：

• 组件框高度：50-70px（标准），80-120px（大/复杂）
• 组件间最小间距：40px 垂直，30px 水平
• 箭头标签距组件边：10px
• 区域边界内边距：20px（边界内所有组件必须完全包含在内）
• 区域内组件居中： 同一区域内的组件组必须水平居中。计算：start_x = region_x + (region_w - total_content_w) / 2
• 区域标签位置： 必须放在边界顶部上方（y=边界y-4），避免被组件框的不透明遮罩覆盖
• 图例位置：最低元素下方至少 20px
• 标题块：距左上角 20px
• viewBox：所有内容 + 四周 30px padding

溢出预防（必须遵守）：

1. 先计算所有组件位置，再画区域边界 — 列出每个组件的 y+height，区域边界高度 = 最低组件 y+height + 20px 内边距
2. viewBox 最后确定 — 写完所有 SVG 元素后，扫描全部元素（包括区域边界）的坐标，viewBox = 所有内容 + 四周 30px padding。计算完后回去修改 <svg> 标签
3. 区域边界也是元素 — 它们有自己的 x/width/y/height，必须纳入 viewBox 计算
4. 检查清单 — 画完后逐项验证：
   • 每个区域边界完全包含其所有子组件
   • 没有元素（包括边界框）超出 viewBox
   • 区域标签在组件框遮罩层之上（标签 y < 区域边界 y）

布局计算方法：

1. 列出所有组件的坐标（x, y, width, height）
2. 画区域边界（边界本身也是元素，有自己的坐标）
3. 画图例和标题
4. 扫描全部元素，找到最大 x+width 和最大 y+height
5. viewBox = "0 0 (max_x+60) (max_y+60)"（四周各 30px padding）

基础 SVG 模板：

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 WIDTH HEIGHT">
  <style>
    @import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&amp;display=swap');
    text { font-family: 'JetBrains Mono', 'Noto Sans SC', 'PingFang SC', monospace; }
  </style>
  <defs>
    <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
      <path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
    </pattern>
    <marker id="arrow" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
      <polygon points="0 0, 10 3.5, 0 7" fill="#64748b"/>
    </marker>
  </defs>
  
  <rect width="100%" height="100%" fill="#0f172a"/>
  <rect width="100%" height="100%" fill="url(#grid)"/>
  
  ...
  
  <text x="30" y="35" fill="white" font-size="16" font-weight="700">Diagram Title</text>
</svg>

标准组件框：

<rect x="X" y="Y" width="160" height="60" rx="6" fill="#0f172a"/>

<rect x="X" y="Y" width="160" height="60" rx="6" fill="FILL_COLOR" stroke="STROKE_COLOR" stroke-width="1.5"/>

<text x="CX" y="Y+24" fill="white" font-size="11" font-weight="600" text-anchor="middle">Component Name</text>

<text x="CX" y="Y+40" fill="#94a3b8" font-size="9" text-anchor="middle">description</text>

数据库圆柱：

<g transform="translate(X, Y)">
  <rect x="0" y="10" width="120" height="50" rx="2" fill="#0f172a"/>
  <ellipse cx="60" cy="10" rx="60" ry="12" fill="#0f172a"/>
  <ellipse cx="60" cy="60" rx="60" ry="12" fill="#0f172a"/>
  <rect x="0" y="10" width="120" height="50" fill="rgba(76,29,149,0.4)"/>
  <ellipse cx="60" cy="10" rx="60" ry="12" fill="rgba(76,29,149,0.4)" stroke="#a78bfa" stroke-width="1.5"/>
  <ellipse cx="60" cy="60" rx="60" ry="12" fill="rgba(76,29,149,0.4)" stroke="#a78bfa" stroke-width="1.5"/>
  <line x1="0" y1="10" x2="0" y2="60" stroke="#a78bfa" stroke-width="1.5"/>
  <line x1="120" y1="10" x2="120" y2="60" stroke="#a78bfa" stroke-width="1.5"/>
  <text x="60" y="40" fill="white" font-size="11" font-weight="600" text-anchor="middle">PostgreSQL</text>
</g>

区域边界：

<rect x="X" y="Y" width="W" height="H" rx="12" fill="none" stroke="#fbbf24" stroke-width="1" stroke-dasharray="8,4"/>
<text x="X+12" y="Y+16" fill="#fbbf24" font-size="9" font-weight="600">Region Name</text>

XML 转义规则（重要）：

SVG 是 XML 格式，以下字符必须转义：

字符	转义	使用场景
&	&	标签文字中的 "A & B"
<	&lt;	比较符号
>	&gt;	比较符号
"	&quot;	属性值中的双引号

<style> 标签必须用 CDATA 包裹：

<style><![CDATA[
  @import url('https://fonts.googleapis.com/css2?family=...');
  text { font-family: 'JetBrains Mono', monospace; }
]]></style>

Step 6: QA 质量检查

生成完成后，读取 references/qa-checklist.md 逐项检查：

# 读取 QA 检查清单
cat $SKILL_DIR/references/qa-checklist.md

必须通过的检查项：

• 视觉一致性（颜色、大小、间距统一）
• 布局合理性（无重叠、流向清晰）
• SVG 规范（viewBox、转义、图层顺序）
• 边界处理（区域包含子组件）

Step 7: 保存文件

• 保存为 .svg 文件
• 如果输入是文件，保存到 {inputFileDir}/diagram/
• 否则保存到 {projectDir}/diagram/{topic-slug}/
• 创建目录（如不存在）

Quick Reference

/diagram-generator                         # 交互式询问图表类型
/diagram-generator 架构图                   # 生成架构图
/diagram-generator 流程图                   # 生成流程图
/diagram-generator 时序图                   # 生成时序图

提示	说明	默认值
类型	图表类型（architecture/flowchart/sequence/structural/mindmap/timeline/state）	自动检测
方向	布局方向（ltr/ttb）	自动选择

Common Mistakes

错误	正确做法	原因
跳过参考文件直接画	先读取对应类型的参考文件	布局算法和组件模式在参考文件中
不用遮罩层	每个组件框前加不透明遮罩	半透明组件会透出底下的箭头
不分层	严格按 8 层顺序绘制	SVG 按绘制顺序渲染，顺序错误会导致遮挡
不加区域边界	用虚线框分组相关组件	读者无法理解组件的组织关系
中文不加宽	CJK 字符比拉丁字符宽	组件框宽度需要增加以容纳中文
viewBox 太小	预留 30px padding	内容可能超出预期边界
组件间距不一致	统一使用参考文件的间距规则	间距混乱影响专业感
箭头标签位置随意	标签放在箭头中间偏上	遮挡箭头或脱离箭头导致混淆
区域内组件未居中	计算 start_x = region_x + (region_w - total_w) / 2	未居中看起来不对称
忘记 XML 转义	& 必须转义为 & 等	SVG 是 XML，未转义会导致渲染失败
viewBox 不包含区域边界	区域边界也是元素，必须纳入计算	边界超出 viewBox 被裁切