visio-skill

Visio スキル

ワークフロー

Visio がインストールされていて、ユーザーが実際の .vsdx ファイルを希望する場合は、ローカルの Microsoft Visio COM オートメーションを使用します。新しい図を作成する場合は、同梱のスクリプトを優先してください。

python "<skill>/scripts/New-VisioDiagram.py" "<diagram.json>" "<diagram.vsdx>"

まず JSON 仕様を作成し、その後スクリプトを実行します。出力ファイルは、ユーザーが指定したフォルダー、指定がない場合はアクティブなワークスペースに保存します。

RTL / Verilog ロジックブロック図

ユーザーが Verilog ソースを提供した場合、または FPGA / RTL のロジックブロック図を求めている場合は、JSON レイアウトを手作業で記述する代わりに、決定論的な RTL ジェネレーターを優先してください。

python "<skill>/scripts/verilog_to_visio.py" "<verilog-dir-or-top.v>" "<output.vsdx>" \
  --top top_module \
  --json "<output.json>" \
  --preview "<preview.png>"

サポートされる役割の推論とレイアウト規則については、references/rtl-verilog.md を参照してください。このジェネレーターでは、モジュールレベルの図を読みやすく保つため、グローバルクロックとリセットのファンアウトを意図的に要約します。生成された JSON は、特殊な設計向けにカスタマイズする場合のフォールバックとしてのみ使用してください。

画像から編集可能な Visio を再構築する

ユーザーが編集できない PNG、JPG、スクリーンショット、スキャンしたフローチャート、アーキテクチャ図、タイムライン、表、またはガントチャートを提供し、編集可能な Visio への再構築を希望する場合は、次を使用します。

python "<skill>/scripts/image_to_visio.py" "<input.png>" "<output.vsdx>" \
  --mode auto \
  --json "<output.json>" \
  --preview "<preview.png>"

ワークフローの全手順については、references/image-reconstruction.md を参照してください。ローカルパーサーは、図形、バー、サンプリングした色、線の形状を抽出します。OCR は任意です。テキストが多い図や視覚的に複雑な図では、ユーザーの画像を確認し、小さな --annotations JSON オーバーレイを渡して、ページ全体を手作業で作り直すことなくラベルや意味的な接続を修正してください。

JSON 仕様

このスキルは 2 種類の図に対応しています。

1. 標準図（フローチャート、アーキテクチャ図など）

フォーマットの詳細については、references/spec-format.md を参照してください。最小限の例：

{
  "title": "Example",
  "pages": [
    {
      "name": "Page-1",
      "nodes": [
        { "id": "start", "text": "Start", "x": 1, "y": 6, "w": 2, "h": 0.8 },
        { "id": "process", "text": "Process", "x": 4, "y": 6, "w": 2, "h": 0.8 }
      ],
      "connections": [
        { "from": "start", "to": "process", "text": "flow" }
      ]
    }
  ]
}

座標の単位は Visio のインチです。x と y はノードの左下隅、w と h は幅と高さを表します。

Visio ステンシルアイコンの使用：

専門的な Visio ステンシルアイコン（ネットワーク機器、サーバー、コンピューターなど）を使用するには、stencils 配列で宣言します。

{
  "stencils": [
    { "id": "network", "file": "NETSYM_M.VSSX" },
    { "id": "server", "file": "SERVER_M.VSSX" }
  ],
  "nodes": [
    { "id": "router1", "stencil": "network", "master": "路由器", "text": "Core Router", "x": 2, "y": 5 },
    { "id": "srv1", "stencil": "server", "master": "服务器", "text": "Web Server", "x": 5, "y": 5 }
  ]
}

ステンシルアイコンの検索：

• クイックリファレンス（推奨）：references/stencil-reference.md — 一般的なネットワーク／サーバー／コンピューターのステンシルと、確認済みのマスター名
• 完全なカタログ：references/visio-stencil-index.md — Visio に組み込まれている 362 個のステンシルすべて

最もよく使用されるステンシル：

• NETSYM_M.VSSX（マスター 24 個）- ネットワーク記号（ルーター、ワークグループスイッチ、ブリッジ、ゲートウェイ）
• SERVER_M.VSSX（マスター 17 個）- サーバー（Web サーバー、データベースサーバー、アプリケーションサーバー）
• COMPS_M.VSSX（マスター 10 個）- コンピューターとモニター（PC、ノートパソコン、タブレット）

2. シーケンス図（UML 相互作用図）

仕様の詳細については、references/sequence-format.md を参照してください。最小限の例：

{
  "type": "sequence",
  "title": "Login Flow",
  "actors": [
    { "id": "user", "name": "User", "type": "actor" },
    { "id": "api", "name": "API", "type": "system" },
    { "id": "db", "name": "Database", "type": "database" }
  ],
  "messages": [
    { "from": "user", "to": "api", "text": "POST /login", "type": "sync" },
    { "from": "api", "to": "db", "text": "Query user", "type": "sync" },
    { "from": "db", "to": "api", "text": "User record", "type": "return" },
    { "from": "api", "to": "user", "text": "JWT token", "type": "return" }
  ]
}

主な機能：

• "type": "sequence" を設定すると、シーケンス図モードが有効になります
• actors（参加者）を定義します。タイプ（actor、system、database、external）の指定は任意です
• from、to、text、type（sync、async、または return）を指定して messages を定義します
• アクターは左から右に配置され、メッセージは上から下へ流れます
• ライフラインと実行仕様は自動的に描画されます

作図のガイダンス

ステンシルアイコンと基本図形の使い分け

次の場合は基本図形のみを使用します（ステンシルは使用しません）：

• ✅ フローチャート
• ✅ プロセス図
• ✅ 決定木
• ✅ BPMN 図
• ✅ ステートマシン
• ✅ マインドマップ
• ✅ 組織図

ユーザーが「アイコン」または特定の機器を明示した場合は、ステンシルアイコンを使用します：

• 🔧 ネットワークトポロジ図（ルーター、スイッチ、ファイアウォール）
• 🔧 インフラストラクチャ図（サーバー、ストレージ、デバイス）
• 🔧 クラウドアーキテクチャ図（Azure、AWS サービス）
• 🔧 データセンターのレイアウト図

デフォルトの動作：ユーザーが「アイコン」、「専門的なアイコン」、「ネットワーク機器」、または「クラウドサービス」を明示的に求めない限り、基本図形のみを使用してください。

標準的な図

• 予測可能なレイアウトにするため、明示的な座標を使用します。
• 図を読みやすく保つため、ノードを行や列に揃え、図形の間隔を少なくとも 0.6～1.0 インチ空けます。また、ユーザーから別の指定がない限り、左から右、または上から下へ線を引きます。
• ⚠️ キャンバスサイズの動的調整ルール：大きな図を標準的なページサイズ（例：11x8.5インチ）に収めるためだけに、ノードを詰めたり、フォントを小さくしたり、間隔を狭めたりしないでください。代わりに、座標とノード数に応じて1ページのキャンバスサイズ（pageWidth／pageHeight）を動的に大きくします（例：A3サイズ、または15x11インチや18x12インチなどのカスタムサイズ）。これにより、すべてのノードと接続線の間に十分な余白を確保できます。各図は必ず1ページに収めますが、ページのキャンバスサイズはコンテンツが美しく収まるように拡大してください。
• ⚠️ フローチャートの「结束」（終了）ノードのルール：フローチャートやプロセスフロー図（特に上から下への垂直フロー）では、最後の「结束」（終了）ノードを必ず図の一番下（つまり、y座標が最も大きい位置）に配置します。途中のステップと並べたり、横に配置したりせず、ページの最下部で視覚的なフローが明確に終わるようにしてください。
• デフォルトの図形は roundrect（角丸長方形）です。デフォルトの塗りつぶし色は上質なライトブルーの #EFF6FF、境界線の色は #3B82F6 です。デフォルトのノードテキストは Microsoft YaHei の 11 pt です。
• デフォルトのコネクタ線の色はスレートグレーの #475569、テキストは 10 pt です。重なりを避けるため、自動的に "textPinX": 0.35 と "textOffsetY": 0.18 を使用します。
• レイヤーや役割ごとに、上質で彩度を抑えたパステルカラーを使用します（例：メインロジックには #EFF6FF／#3B82F6、開始／成功には #ECFDF5／#10B981、ストレージには #FEF3C7／#D97706、外部 API には #F5F3FF／#8B5CF6）。
• ラベル付きコネクタで横並びのボックスを配置する場合は、矢印の分の余裕も含め、水平方向に少なくとも max(1.4 in, label characters * 0.12 in) の間隔を空けます。
• 図形内のラベルは短くします。長い説明はコールアウトまたは外部注記に記載します。
• アーキテクチャ図では、クライアント、エッジ／API、サービス、データ、外部システムのレイヤーごとにグループ化します。
• プロセス図では、ステップが多い場合を除き、左から右へのフローにします。ステップが多い場合は行に分けます。
• スイムレーン形式の図では、ノードの背後に薄く塗りつぶした大きな長方形でレーンを表すか、レーンラベル付きの行を個別に作成します。
• ステンシルのサイズ設定：ステンシルマスターを使用する場合、w と h は省略可能で、省略するとマスターのデフォルトサイズが使用されます。ステンシルアイコンの一般的なサイズは 1.0～1.5 インチです。

シーケンス図

• アクターは論理的な順序（左から右）で定義します。通常は、ユーザー → フロントエンド → バックエンド → データベース → 外部サービスの順です。
• 各参加者を明確に示す説明的なアクター名を使用します（例：「User」、「Web App」、「Auth Service」、「PostgreSQL」）。
• 自動的な色分けに適したアクタータイプを選択します。
  • ユーザー／人物には "actor"（青）
  • 内部サービスには "system"（紫）
  • データストアには "database"（琥珀色）
  • サードパーティ API には "external"（緑）
• 実際の実行フローを表すため、メッセージは上から下へ時系列順に並べます。
• メソッド呼び出し／リクエストには "type": "sync"、レスポンス（破線の矢印で表示）には "type": "return" を使用します。
• メッセージラベルは簡潔でありながら意味が明確になるようにします（例：「POST /login」、「Query user」、「JWT token」）。
• ⚠️ シーケンス図のページサイズ：メッセージやアクターが多いシーケンス図では、actorSpacing や messageSpacing を小さくしてアクターやメッセージを詰め込まないでください。代わりに、すべての要素が十分な余白を保って収まるよう、1ページの寸法（pageWidth／pageHeight）を大きくします。
• 複雑なフローでは、アクターを最大4～6人に制限します。必要に応じて複数の図に分割します。
• デフォルトの間隔は適切です。図が詰まりすぎている、または間隔が空きすぎている場合に限り、layout.actorSpacing または layout.messageSpacing を上書きします。

検証

.vsdx を生成した後、ファイルが存在し、サイズが 0 でないことを確認してください。ユーザーが視覚的な QA を必要としている場合は、Visio COM で開き、必要に応じて PNG/PDF プレビューをエクスポートしてください。

COM の作成に失敗した場合は、Visio がインストールされ、登録されているか確認してください。

import win32com.client
win32com.client.Dispatch("Visio.Application")

Visio を利用できない場合は、.vsdx が作成されたかのように装わず、代わりに Mermaid、SVG、draw.io、または別のインポート可能な形式を提案してください。