arch-diagrams

arch-diagrams

目的

このスキルを使うと、OpenClaw は C4 モデル、PlantUML、Mermaid、シーケンス図、ERD、インフラストラクチャ図などのツールを使用して、アーキテクチャ図を生成、編集、レンダリングできます。システム設計を視覚化するため、図の作成をコーディングワークフローに統合します。

使用するタイミング

ソフトウェアアーキテクチャのドキュメント作成、システム間のやり取りの計画、ERD やシーケンスフローの視覚資料の作成には、このスキルを使用してください。設計段階、コードレビュー、インフラストラクチャのセットアップでの共同作業時に適用すると、テキストの説明からすばやく図のプロトタイプを作成できます。

主な機能

• 高レベルの説明から C4 図を生成します。
• PlantUML コードを SVG または PNG にレンダリングします。
• フローチャート、シーケンス図、ERD 用の Mermaid 図を作成します。
• AWS などのツールや汎用クラウドアイコンを使ったインフラストラクチャ図に対応します。
• ソースコード（PlantUML 構文など）を解析して変更し、既存の図を編集します。
• ドキュメントに含めるため、図をコードスニペットまたは画像ファイルとしてエクスポートします。

使用パターン

タスクを実行するには、明確なテキストの説明または図のコードの一部を OpenClaw に渡し、図の種類を指定します。たとえば、JSON 設定などの入力を使って、CLI または API 経由でスキルを呼び出します。「データベースを備えたウェブアプリの C4 コンテナ図を生成する」のように、常にコンテキストを含めてください。生成、確認、改良などのコマンドを連結して、反復作業を行います。操作の前に $OPENCLAW_API_KEY を設定するなど、認証には環境変数を使用してください。

一般的なコマンド／API

直接実行するには OpenClaw CLI を、プログラムからアクセスするには API を使用してください。環境内の $OPENCLAW_API_KEY で認証します。

• CLI コマンド：openclaw arch-diagrams generate --type mermaid --input "sequenceDiagram: A->B: Request" --output diagram.md 入力文字列から Mermaid シーケンス図を生成し、ファイルに保存します。

• API エンドポイント：JSON 本文 {"type": "plantuml", "description": "@startuml\nAlice -> Bob: Hello\n@enduml", "format": "svg"} を指定して /api/v1/arch-diagrams/generate に POST します。 レスポンスにはレンダリング済みの SVG が含まれます。認証には HTTP ヘッダーを使用してください。

• 設定形式：入力には YAML を使用します。例：

  type: c4
  elements:
    - name: System
      type: container
  

  CLI フラグ --config path/to/config.yaml でこれを渡します。

• コードスニペット（Python）：

  import requests
  response = requests.post('https://api.openclaw.ai/api/v1/arch-diagrams/generate', json={"type": "erd", "input": "User has many Posts"}, headers={'Authorization': f'Bearer {os.environ["OPENCLAW_API_KEY"]}'})
  print(response.json()['output'])
  

統合に関する注意

IDE 拡張機能（OpenClaw 用の VS Code プラグインなど）や CI/CD パイプラインにこのスキルを追加して、ワークフローに統合します。たとえば、GitHub Action では次のように使用します：run: openclaw arch-diagrams generate --type sequence --input ./specs.md && echo '::set-output name=diagram::$(cat diagram.md)'。環境内のシークレットとして $OPENCLAW_API_KEY を設定してください。他のスキルと組み合わせる場合は、出力をパイプで渡します。たとえば、コード分析の結果から図を生成します。OpenClaw CLI v2.5+ のように、バージョンを指定して互換性を確保してください。

エラー処理

レスポンスコードまたは CLI の終了ステータスを解析して、必ずエラーを確認してください。入力が無効な場合、OpenClaw は「Invalid PlantUML syntax: missing @enduml」のような詳細とともに HTTP 400 を返します。ネットワークの問題には、コード内で if response.status_code == 503: time.sleep(5); retry() のように、指数バックオフを使って再試行してください。送信前に、図の種類が ["c4", "mermaid", "plantuml", "sequence", "erd"] のいずれかであることを確認するなど、入力を検証してください。API 呼び出しには、たとえば次のように try-except ブロックを使用してください。

try:
    result = requests.post(url, json=data)
    result.raise_for_status()
except requests.exceptions.HTTPError as e:
    print(f"Error: {e.response.text} - Fix input and retry")

具体的な使用例

1. C4 システム図を生成する： シンプルなウェブアプリケーションを視覚化するには、次を実行します：openclaw arch-diagrams generate --type c4 --input "System: WebApp with Database and API" --output c4_diagram.puml。これにより、C4 システムコンテキスト図の PlantUML ファイルが生成されます。確認して、次を追加して調整します：openclaw arch-diagrams edit --file c4_diagram.puml --add "Container: Frontend"。

2. データベーススキーマの ERD を作成する： リレーションシップをモデル化するには、次を使用します：openclaw arch-diagrams generate --type erd --input '{"entities": [{"name": "User", "attributes": ["id", "name"]}, {"name": "Post", "attributes": ["id", "content"]}]}' --output erd.mmd。これにより Mermaid の ERD コードが出力され、Markdown ファイルでレンダリングできます。

グラフのリレーションシップ

• C4 図：「システムが外部システムに依存する」、「コンテナーがコンポーネントを使用する」。
• シーケンス図：「アクターがオブジェクトにメッセージを送信する」、「オブジェクトがアクターに応答を返す」。
• ERD：「エンティティが別のエンティティと一対多のリレーションシップを持つ」、「属性がエンティティに属する」。
• インフラストラクチャ図：「サーバーがデータベースに接続する」、「ロードバランサーがサービスにルーティングする」。