hersaintel/stack-diagram

stack-diagram は何をしますか？

Hermes 統合

<skill> をこのSKILL.mdを含むディレクトリ（プロジェクトのワーキングディレクトリではない）に解決します。バンドルされたスクリプトは、引用符で囲まれた絶対パスを使用して、terminal でPythonを通じて実行します。テンプレートや参照には read_file を、成果物には write_file/patch を使用します。Playwrightには分離されたPython環境を推奨します。インポートだけではブラウザドライバが動作することを証明できません。

リポジトリベースのリクエストの場合、最初にノードとエッジの証拠を記録します。依存関係はランタイムトポロジを確立しません。推論された関係は仮定としてラベル付けし、曖昧さがアーキテクチャを変える場合は質問します。ユーザーが明示的に提供したトポロジは証拠です。スタックを発見するためにシークレットや無関係なファイルを決して読まないでください。

MEDIA:/absolute/path/to/out.html と MEDIA:/absolute/path/to/out.png（およびダークPNG）を使用してローカルファイルを配信します。vision_analyze を使用して、両方のレンダリングテーマを検査します。HTMLが唯一の視覚的なソースです。PNGはChromiumから生成され、独立したSVG/PILレンダラーからは生成されません。ファイルが存在する前に配信済みとしてマークしないでください。このスキルはbragを呼び出したり変更したりしません。ビデオが要求された場合にのみ stack-video を使用します。これは独立した兄弟スキルであり、必須のステップではありません。

アップストリームのスクリプト/リソースは caru-ini/stack-diagram から保持されています。このパックの UPSTREAM.md を参照してください。オプションのギャラリー手順は、それら自体の明示的な同意が必要です。このパックのインストールまたは公開はギャラリーの同意を意味しません。

エンジニアリング図面スタイルのアーキテクチャ図を生成します：白いタイル上の実際のロゴ、ラベル付きのグループボックス（クラウドベンダーのVPC図のように）、等幅フォントのラベルが付いた直交矢印、クールなグラフ用紙の背景。1つの自己完結型HTMLファイルがソースであり、PNG / TSX / 成果物はそれから派生します。

要件

• Python 3.9+（fetch_icons.py、build.py、share.py には標準ライブラリのみ）
• アイコンフェッチ時のアイコンソース（svgl.app、raw.githubusercontent.com、cdn.jsdelivr.net、aws.amazon.com および d1.awsstatic.com（AWSアイコン用）、services.google.com（Google Cloudアイコン用）、learn.microsoft.com および arch-center.azureedge.net（Azureアイコン用）、さらに name=URL のブランド自身のサイトまたはリポジトリ）へのネットワークアクセス
• render_png.py 用の Playwright + Chromium：pip install playwright && python3 -m playwright install --with-deps chromium

ワークフロー

1. コンテンツ（ノード、グループ、エッジ）を確定する
2. アイコンを取得する — scripts/fetch_icons.py
3. 座標を計画する — references/geometry.md を読む
4. assets/template.html からHTMLをビルドする — scripts/build.py
5. 配信前にPNGをレンダリングして確認する
6. 要求されたフォーマットで配信する
7. オプションで公開ギャラリーに共有する

ステップ1 — コンテンツ

ユーザーのテクノロジー/サービスのリストから、以下を決定します：

• ノード：各テクノロジー = 1つのノード（名前 + 「http server」「sqlite db」のような短い小文字のロール）
• グループ：同じランタイム、ベンダー、またはリポジトリを共有するものの周りにボックスを描画します（例：クラウドプロバイダーのボックス内のランタイムボックス、ツールのモノレポボックス）。1レベルのネストは問題ありませんが、それ以上はノイズになります。グループラベルはブランド自身の大文字小文字で記述します（GitHub、npm）。テンプレートはそのまま表示します。
• エッジ、3種類：
  • アクセント色の実線 = プライマリのリクエスト/データフロー（1つの連続したパスが最適）
  • ニュートラルな実線 = セカンダリの内部接続
  • ニュートラルな破線 = 開発時/デプロイ時の関係（CI、gitフック、IaCデプロイ）

ユーザーがツールのフラットなリストのみを提供した場合、ツールの性質から適切なグループとフローを推論します。ツールがあいまいで図がどちらにせよ間違ってしまう場合にのみ質問します。

ステップ2 — アイコン

python3 scripts/fetch_icons.py <icons-dir> tanstack hono drizzle "betterauth:better-auth" "orpc=https://orpc.unnoq.com/logo.webp"
python3 scripts/fetch_icons.py <icons-dir> "aws:aws/AWS-Cloud-logo" "vpc:aws/vpc" "fargate:aws/fargate" "s3:aws/s3"
python3 scripts/fetch_icons.py <icons-dir> "gcp:google-cloud" "run:gcp/cloud-run" "lb:gcp/load-balancing" "sql:gcp/cloud-sql"
python3 scripts/fetch_icons.py <icons-dir> "azure:azure/Azure-A" "app:azure/app-service" "vnet:azure/vnet" "sql:azure/sql-database"

指定形式：name（スラッグとして使用される名前）、name:slug（異なるスラッグ）、name=URL（明示的なURL）、name:aws/<Name>（公式AWSアイコン）、name:gcp/<Product>（公式Google Cloudアイコン）、name:azure/<Name>（公式Azureアイコン）。スクリプトは次の順序で試行します：svgl → devicon → gilbarbara/logos。ファイルと manifest.json を書き込み、塗りつぶしが白のアイコンにフラグを付けます。svgl（svgl.app）は、最新の公式マーク（TanStack、Better Auth、Hono...）を提供するため、最初に試行されます。ロゴにライト/ダークバージョンがある場合、ライトバージョンは <name>（両方のテーマでタイルは白）として保存され、ダークバージョンはグループラベル用に <name>_dark として保存されます。svglは完全なタイトルのみで一致するため、見つからなければ単にフォールスルーします。そのAPIは wordmark バリアントも公開していますが、幅広のグループラベルにはたまに便利ですが、タイルには決して使用しません。

メカニズムよりも重要なルール：

• ロゴの色を決して変更しないでください。 ユーザーは気づきます。ロゴが白または白いタイルに明るすぎる場合は、塗りつぶしに触れる代わりに、暗いタイル（tile dark クラス）に配置します。マニフェストの white_fill フラグはヒューリスティックです。白い塗りつぶしは色付きのマーク（tRPC、Ubuntu）の内部詳細である可能性があるため、暗いタイルに手を伸ばす前にSVGを一目確認してください。
• 公式マークのみを使用してください。 simple-iconsは意図的にソースから除外されています。そのグリフはモノクロの再描画であり、ユーザーは一目で間違いだと指摘します。すべてのソースが見つからない場合（FAIL）、公式ファイルを見つけて name=URL として渡します。プロジェクトのリポジトリ（ルート logo*.svg、docs/、assets/、public/）とそのサイト（/logo.svg、/favicon.svg、/images/logo.svg）を確認してください。一部のマークはリポジトリにのみ存在します（Lefthookのマークは evilmartians/lefthook のルートにある logo_sign.svg です）。
• 抽象的な概念にはピクトグラムを使用し、テキストは使用しないでください。 「dev environment」「cron」「queue」「cache」「webhook receiver」などのノードにはブランドがありません。name:lucide/<icon> を介してLucideラインアイコンを使用します（例：devenv:lucide/terminal、cron:lucide/clock。lucide.dev/icons を参照）。タイル内にテキストや絵文字は使用しないでください。
• ベンダーサブプロダクト（Cloudflare D1/R2/KV...）には通常、個別のロゴがありません。タイルにベンダーロゴを再利用し、ノード名で区別を付けます（「Cloudflare D1」/「sqlite db」）。
• AWSはAWS独自のアイコンを使用します。 各サービスには1つあります。name:aws/<Name> で取得し、実行時にAWSの公式アイコンパッケージから読み取ります（例：lambda:aws/lambda、aws:aws/AWS-Cloud-logo、s3:aws/s3）。AWS- / Amazon- プレフィックスはオプションで、一般的な略語は機能します（s3、sqs、sns、ses、ecs、eks、ecr、elb、alb、nlb、iam、kms、msk、vpc）。見つからない場合はすべての名前が出力されます。スラッグ aws、amazonwebservices、aws-* は同じパッケージに送られ、パッケージにないものはサードパーティのコピーにフォールバックする代わりに FAIL します。サービスの場合は常に aws/ プレフィックスを記述します。ベアの dynamodb は依然としてサードパーティのチェーンを経由します。パッケージとルーズなアイコンファイルはリポジトリの外に保管してください。AWSは図内でのアイコン使用を許可しており、再配布は未確認です。
• AWSエリアはAWS独自の描画ルールに従います。 サービスアイコンは独自の正方形を持ち、明るい背景と暗い背景の両方で機能するため、tile bare を使用します。白いタイルはフレームを二重にするだけです。その内部の人物と汎用ノードは、AWSの汎用アイコン（user:aws/General-User、General-Users、General-Client、General-Internet、General-Server）を tile bare res とテンプレートの lt/dk ペアで使用します。グループは、AWS Cloud用にテンプレートの group aws（ラベルに aws:aws/AWS-Cloud-logo）、さらに region、az、vpc、private、public を使用します。角は正方形、輪郭のみ、ラベルはインク色、ベンダーの色合いはなし、コーナーに14pxの代わりに30pxのアイコンがあります。VPC内では、分割がわかっているか安全に推論できる場合（インターネットに面したロードバランサーはパブリック、アプリサーバーとデータベースはプライベート）、パブリックサブネットとプライベートサブネットを表示します。フラットなVPCがAWS関係者が最初に気づく点です。内部のエッジは1色と開いた矢印を使用します：<path class="aws" ... marker-end="url(#open)"/>、開発/デプロイには aws dash、プレーンな .el ラベル、凡例は不要です。ノードには Amazon S3 / AWS Fargate のように名前を付け、ベアの S3 / Fargate は使用しません。ALB のような短縮形は、完全名（Elastic Load Balancing）の下のロール行に入れます。名前は2行になる可能性がありますが、Amazon / AWS は最初の単語の行に残す必要があります。プレフィックスの直後に折り返される場合は、そのノードの幅を広げます（left:<centerX-76>px; width:152px）。
• Google CloudはGoogle独自のアイコンを使用します。 name:gcp/<Product> で取得し、実行時にGoogleの公式パッケージから読み取ります（例：run:gcp/cloud-run、lb:gcp/load-balancing、memorystore:gcp/memorystore）。コアプロダクトのみが独自のアイコンを持ちます（Cloud Run、Cloud SQL、Cloud Storage、BigQuery、GKE、Compute Engine、Vertex AI...）。その他のプロダクトは、Googleのガイドに従い、カテゴリのアイコンを使用します。Cloud Load BalancingとCloud CDNはどちらもNetworkingを取得し、MemorystoreとFirestoreはどちらもDatabasesを取得します。プロダクトの名前を記述すると、スクリプトがアイコンを選択します。Cloud / Google プレフィックスはオプションで、一部の短縮形は機能します（vpc、iam、kms、iap、gce、gcs）。見つからない場合はすべての名前が出力されます。gcp/storage はStorageカテゴリで、Cloud Storageは gcp/cloud-storage です。スラッグ gcp-* と google-cloud-* は同じパッケージに送られ、パッケージにないものはサードパーティのコピーにフォールバックする代わりに FAIL します。これらのコピーは廃止された六角形アイコンであり、Googleは使用しないよう指示しています。プロダクトの場合は常に gcp/ プレフィックスを記述します。ベアの bigquery は依然としてサードパーティのチェーンを経由します。gcp:google-cloud はグループラベル用のGoogle Cloudマークです。GeminiとFirebaseはパッケージに含まれていません。ベアの gemini と firebase を使用します。パッケージとルーズなアイコンファイルはリポジトリの外に保管してください。Googleは図とドキュメント用にアイコンを提供しており、再配布は未確認です。
• Google Cloud図は通常のスタイルを維持し、Googleのグループを使用します。 Google自身の図（単色の青いパネル、水平カード）は意図的にコピーしません。アイコンは通常の白いタイルに配置され、エッジと凡例は通常通りです。グループは、Google Cloud用にテンプレートの group gcp（ラベルに gcp:google-cloud）、さらに vpc、region、subnet、zone を使用します。VPCはグローバル、サブネットはリージョナルであるため、リージョンをVPC内に配置し、VPCをリージョン内に配置することは決してしません。グローバルおよびサーバーレスサービス（外部ロードバランサー、Cloud Storage、Cloud Run）はVPCの外側に留まります。アイコンは共有されるため、常にプロダクトの完全名（Cloud Load Balancing、LBではない）を記述し、名前が折り返されるノードの幅を広げます（left:<centerX-76>px; width:152px）。
• AzureはMicrosoft独自のアイコンを使用します。 各サービスには1つあります。name:azure/<Name> で取得し、実行時にMicrosoftの公式パッケージから読み取ります（例：app:azure/app-service、azure:azure/Azure-A、vault:azure/key-vault）。Azure- / Microsoft- プレフィックスと複数形の s はオプションで、一般的な短縮形は機能します（aks、vm、vnet、nsg、waf、blob、cosmos、redis、postgres、functions、front-door、apim、ai-search）。見つからない場合はすべての名前が出力されます。スラッグ azure、microsoft-azure、azure-* は同じパッケージに送られ、パッケージにないものはサードパーティのコピーにフォールバックする代わりに FAIL します。サービスの場合は常に azure/ プレフィックスを記述します。ベアの cosmos は依然としてサードパーティのチェーンを経由します。Microsoft Entra IDには個別のアイコンセットがあります。公式ファイルを name=URL として渡します。Microsoftはこれらのアイコンをアーキテクチャ図、トレーニング資料、ドキュメントでのみ使用することを許可しています。アイコンをトリミング、反転、回転、変形したり、それが表すMicrosoftサービス以外に使用したりせず、パッケージとルーズなアイコンファイルはリポジトリの外に保管してください。
• Azure図は通常のスタイルを維持し、Microsoftのグループ色を使用します。 Microsoft自身の図は意図的にコピーしません。アイコンは通常の白いタイルに配置され、エッジと凡例は通常通りです。グループは、Azure用にテンプレートの group azure（ラベルに azure:azure/Azure-A）、さらに rg、region、vnet、subnet、zone を使用し、vnet または subnet ラベルはそのアイコン（vnet:azure/vnet、subnet:azure/subnet）を持ちます。VNetは1つのリージョンに属するため、リージョン内に配置されます。Front Doorのようなグローバルサービスはリージョンの外側に留まります。App Serviceは、App Service Environmentで実行されている場合を除き、VNetの外側に配置され、プライベートエンドポイントを介して到達されるPaaSサービスは、ロールとして「private endpoint」を付けて内部に配置できます。Microsoftは各アイコンの横にサービスの完全名（Azure SQL Database、SQLではない）を要求するため、名前が折り返されるノードの幅を広げます（left:<centerX-76>px; width:152px）。
• ベンダーのルールはそのベンダー自身のエリアにのみ適用されます。 AWS、Google Cloud、Azureのルールは、図に他のものがなくても、そのベンダーのグループ内でのみ適用されます。グループ外のすべて（たとえば隣のユーザーやグループに入るエッジ）は、通常のタイル、グループ、エッジ、凡例を維持します。
• 非ブランドノード（user、browser、internet、devices、bare-metal server）：assets/generic/ からグリフをアイコンディレクトリにノード名でコピーするか、name:lucide/<icon> を使用します。絵文字は使用しないでください。これらはブランドロゴではないため、図のインク色に着色しても問題ありません（取得スクリプトはLucideに対して自動的に行います）。
• グループラベルのアイコンは14pxでレンダリングされます — 正方形のグリフマークが必要です。ワードマークやワイドロックアップはそのサイズでつぶれます。メインのアイコンがワードマークの場合は、ラベル用にブランドの正方形アイコンを別途取得します（svglは通常持っています。持っていない場合はプロジェクト自身のアイコンまたはファビコンファイル）。
• グループラベルはグループの色合いの上に配置され、白いタイルの上には配置されません。そのため、ダークテーマでは黒い部分があるマークがそこで消えてしまいます。fetch_icons.py が <name>_dark を保存した場合は、ラベルでテンプレートの lt/dk ペアを使用します。ダークバリアントがなく、マークに黒い部分がある場合は、ラベルの <img> にクラス plate を追加します（白い背景、ダークテーマのみ）。
• ラスターロゴ（png/webp）でも問題ありませんが、build.py はそれらを処理します。
• 名前にはスラッグまたは明示的なURLのみを使用します：ノード名は name 部分から自動的に取得されるため、name はアイコンのIDのみを目的とします。

ステップ3 — 座標

references/geometry.md を読み、ノードとエッジのピクセル位置を計画します。主なグリッドは columnWidth: 210、rowHeight: 120、edgeStagger: 30 です。

ステップ4 — HTMLのビルド

python3 scripts/build.py <html-out-path> <icons-dir> <topology-file>

topology-file は、assets/topology-template.json で定義された構造を持つJSONです。build.py に渡す前に、テンプレートを使用して検証します。read_file でテンプレートを読み込み、write_file で出力HTMLを書き込みます。

ステップ5 — PNGのレンダリング

python3 scripts/render_png.py <html-in-path> <png-out-path>
python3 scripts/render_png.py <html-in-path> <png-dk-out-path> --dark

ステップ6 — 配信

要求された出力フォーマットに応じて、ファイルとして、または MEDIA: 経由で配信します。

ステップ7 — 共有（オプション）

python3 scripts/share.py <html-in-path>