ブリッジハブ（bridge-hub.exe）— KASUGAI Canvas ドキュメント

1. 概要 — bridge-hub.exe とは

ローカルに常駐させるブリッジを 1本（127.0.0.1:8511）に集約するハブです。Rust 製の単一 exe（bridge-hub.exe）で、Node.js は不要です。アプリ版（kasugai_canvas.exe）と同じ server/src/bridge/ 実装を使い、Copilot / Devin / Antigravity の各プロバイダは実際に使われた時点で外部 CLI を子プロセスとして遅延起動します。

アプリ版・ブラウザ WebGIS 共通の1本で、アプリはハブを内蔵しません。起動時に :8511 のハブが未応答なら、インストール済みの本 exe を BRIDGE_HUB_PORT=8511 で自動起動します（旧ブラウザ WebGIS 用に 8512 で常駐していたハブは全て旧版のため、本ハブのインストール時・および新版アプリの起動時に自動で停止されます）。

エージェント連携は双方向

このハブは「ブラウザ → エージェント」方向だけを担います。逆方向は別経路です:

ブラウザ → エージェント（チャットから AI を使う）… 本ハブ（/agent・/models）
エージェント → ブラウザ（外から地図を操る）… アプリ本体（127.0.0.1:8510）の /api/command。Devin Desktop・Copilot CLI・任意スクリプトが {"name":"flyTo","args":{...}} を投入すると、ブラウザがロングポーリングで受信して executeChatTool で実行します

2. 導入・起動・解除

基本導入（自己インストール型 exe）

bridge-hub.exe を ダウンロードして実行するだけで、%LOCALAPPDATA%\kasugai\bridge-hub\ への自己コピー → ログイン時自動起動登録（タスク KasugaiCanvasBridgeHub・登録できない環境では HKCU Run キー）→ 127.0.0.1:8511 での起動 → ブリッジ用 CLI（copilot/devin）の未導入分の自動インストールまで一括で行われます（--no-cli-setup で CLI 導入を省略可。CLI DL に数分かかることがあります）。コンソールは表示されず、結果はメッセージボックスで通知されます。管理者権限は不要です。

Canvas の AI 設定画面でブリッジ系プロバイダを選んだ際にも、ハブ未検出ならこの exe のダウンロードが自動で始まり、実行後はブラウザ側が /health ポーリングで検出して接続まで完了します。

bridge-hub.exe              # 自己インストール（DL直後の実行）
                            #   ※ インストール先からの実行・BRIDGE_HUB_PORT 指定時は
                            #     その場でハブ起動（--serve と同じ）
bridge-hub.exe --install [--no-cli-setup]
                            # 自己インストールを明示実行（スクリプト向け。
                            #   --no-cli-setup で CLI 自動導入を省略）
bridge-hub.exe --serve      # インストールせずその場でハブ起動（既定 8511）
bridge-hub.exe --uninstall  # 自動起動解除＋停止＋インストール先の削除
bridge-hub.exe --setup status        # 全プロバイダの検出状況を表示
bridge-hub.exe --setup copilot       # copilot CLI を自動インストール
bridge-hub.exe --setup devin         # devin CLI を自動インストール
bridge-hub.exe --setup all           # 自動化可能な未導入CLIをまとめて導入

停止だけしたい場合は、実行中の bridge-hub.exe プロセスをタスクマネージャー等で終了してください（--uninstall は自動起動解除＋停止＋削除を行います）。

無人導入（PowerShell 一発）

ダウンロード → インストール → CLI 自動導入 → 疎通確認まで一括で行います。

Invoke-WebRequest "https://yamamoto-ryuzo.github.io/kasugai-canvas-web/stable/download/bridge-hub.exe" -OutFile "$env:TEMP\bridge-hub.exe"
Unblock-File "$env:TEMP\bridge-hub.exe"
& "$env:TEMP\bridge-hub.exe" --install     # 自動起動登録(8511)+即時起動
& "$env:TEMP\bridge-hub.exe" --setup all   # copilot/devin CLI を自動導入
# 疎通確認（起動反映まで数秒かかることがあるためリトライ）
1..15 | % { try { Invoke-RestMethod http://127.0.0.1:8511/health -TimeoutSec 2; break } catch { Start-Sleep 1 } }

download/bridge-hub.zip には bridge-hub/bridge-hub.exe と README のみが入っています（スクリプト同梱は廃止。exe は GUI subsystem ビルドでコンソールを持たないため、非表示起動用の vbs/ps1 は不要です）。展開して実行すれば同じ自己インストールが行われ、--install / --serve / --uninstall / --setup もそのまま使えます。

3. HTTP API 一覧（127.0.0.1:8511）

エンドポイント	説明
`GET /`	ハブ状態確認ページ（ブラウザで開ける。表示側 JS が `/health`・`/setup` を取って描画）
`GET /health`	ハブ自身の状態（`hub:true`・`providers.<名>.available/running`・`active`）
`GET /models?provider=<copilot\|devin\|antigravity>`	対象プロバイダの `/models`
`POST /agent`	ボディの `provider` フィールドでプロバイダを選択・起動。ブラウザから設定するエンドポイントは `http://127.0.0.1:<port>/agent`
`POST\|DELETE /mcp[/<project>]`	地図ツールの MCP 公開（devin/agy から呼ばれる。`/mcp` は処理中プロジェクト、`/mcp/<project>` は明示指定）
`GET /setup`	各プロバイダ用 CLI の検出状況と自動化可否（`cli_found`/`cli_path`/`auto_install`/`methods`）
`POST /setup`	`{provider, action:"install", confirm:true}` で公式手順の自動インストールをジョブ開始（`{"job": "<id>"}` を返す）
`GET /setup/job/<id>`	ジョブの状態（`running`/`done`/`failed`）・ログ・結果

POST /setup はブラウザ経由の踏み台を防ぐため、Origin が loopback または Canvas の既知デプロイホスト（*.github.io/*.run.app/*.pages.dev、BRIDGE_SETUP_ORIGINS で追加可）の場合のみ受け付けます。

4. /setup による CLI 自動導入

「copilot/devin CLI が見つかりません」系の導入エラーを減らすため、ハブは各プロバイダ公式の導入手順を実行できます（ホワイトリスト化済み・任意コマンドは実行しません）:

プロバイダ	自動導入手順（順にフォールバック）
copilot	`winget install GitHub.Copilot` → `npm i -g @github/copilot` → GitHub Releases から `copilot-win32-*.zip` を直接DL（ハブ管理ディレクトリ `%LOCALAPPDATA%\kasugai\bridge-cli\copilot\` へ配置）
devin	公式 `irm https://static.devin.ai/cli/setup.ps1 \| iex`（unix は `install.sh`）
antigravity	自動化不可（IDE インストーラ＋対話 Google ログインのため案内のみ）

導入直後の CLI はプロセス環境の古い PATH では見えないことがあるため、検出・起動の両方で レジストリの最新 User/Machine PATH も参照します（ハブ再起動なしで検出できます）
Canvas の AI 設定画面の各プロバイダ欄にある「CLI を自動インストール」ボタンと、チャットツール bridgeSetup（Gemini 等の内蔵AIからも「copilot をインストールして」と指示できる）がこの API を使います

5. プロバイダ別の前提と利用条件（必読）

いずれのブリッジも公式連携ではなく、公開インターフェースを使ったサードパーティ製クライアントです。各サービスの利用規約に沿うため、ローカル・本人利用限定で使ってください（127.0.0.1 にのみバインド。自分のアカウントで他者のチャットを処理する形態は禁止）。

プロバイダ	必要なもの	認証
GitHub Copilot	`copilot` CLI（npm 版は Node.js も必要）＋Copilot 契約（Free〜Enterprise いずれのプランでも可）	`copilot` CLI で対話ログイン済み、または `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`
Devin	`devin` CLI（Devin Desktop 同梱の `devin.exe` または単体インストール。`DEVIN_CLI_PATH` で指定可）＋本人の Devin プラン	サービスユーザー APIキー（`cog_`、app.devin.ai → Settings → Devin API → Service users・ロール Member。`DEVIN_API_KEY` またはアプリ設定画面。PAT は拒否）または初回接続時のブラウザ PKCE ログイン
Antigravity	`agy` CLI（Antigravity のインストールに含まれる `agy.exe`。`AGY_CLI_PATH` で指定可）	利用者自身の Google アカウントでの `agy` ログイン（一度対話起動してサインイン）

Copilot: プレミアムリクエストの quota（AI クレジット）を消費。Free プランはモデル自動選択のみ
Devin: 消費されるのは利用者自身の quota。ローカル CLI のログイン資格は ACP モードでは使われない
Antigravity: ブリッジが agy mcp add kasugai で地図ツールを MCP 登録し、~/.gemini/antigravity-cli/settings.json の permissions.allow に mcp(kasugai/*) を追加（headless では未許可ツールが自動拒否されるため必須）。ファイル書込み・シェル実行等の内蔵ツールは利用者が自分で許可ルールを足さない限り拒否され、作業ディレクトリも空の %TEMP%/kasugai-antigravity-bridge に限定される

6. 環境変数

変数	既定	説明
`BRIDGE_HUB_PORT`	`8511`	ハブの待受ポート（127.0.0.1 のみバインド）。アプリ版・ブラウザ WebGIS 共通の統一ポート。変更するとブラウザがハブを検出できなくなるため通常は変更不要
`BRIDGE_SETUP_ORIGINS`	なし	`POST /setup` を受け付ける Origin の追加許可リスト（loopback・既知デプロイホスト以外を許可する場合）
`KASUGAI_NO_COPILOT_BRIDGE`	なし	copilot プロバイダを無効化
`KASUGAI_NO_DEVIN_BRIDGE`	なし	devin プロバイダを無効化
`KASUGAI_NO_ANTIGRAVITY_BRIDGE`	なし	antigravity プロバイダを無効化

各プロバイダ固有の環境変数（DEVIN_API_KEY・COPILOT_CLI_PATH・DEVIN_CLI_PATH・AGY_CLI_PATH・*_BRIDGE_TOKEN 等）はアプリ版と同じものがそのまま使えます。

7. 関連リンク

【ブリッジ】外部エージェント連携 — 利用者向けの導入・接続手順と規約判断
AI ツール仕様 — 内蔵AIが制御できるツールの定義（bridgeSetup 等）
V3: 設計判断 — ブリッジハブ — ハブ集約の設計判断（3ポート分離との比較）
【アプリ】ローカルアプリ — ハブ未応答時に自動起動するアプリ本体
← ドキュメントトップへ