使い方・セットアップ

使い方(A): Driver単体で使う

QGISをAIツールや自作アプリから遠隔操作したい人向け。リポジトリもNodeも不要。

1. QGISプラグインリポジトリから QGIS Live Driver をインストール (または qgis_live_driver/ フォルダを python/plugins/ へコピー)
2. プラグイン > QGIS Live Driver > リモート制御 (localhostのみ) をON (初回は警告ダイアログ→Yes。QSettingsに保存され次回起動から自動有効)
3. 接続は4系統のどれでもよい(Driver詳細):
   • MCP stdio — AIクライアントのMCP設定に python <profile>/python/plugins/qgis_live_driver/mcp_stdio.py を登録するだけ
   • MCP/REST HTTP — ~/.qgis-live/<pid>-qgis_live_driver.json から mcp_url/http_port と token を読み Bearer 認証で接続
   • ファイルJSONL — commands.jsonl に {"type":...,"token":...} を追記 → results.jsonl で結果受取

できること: pyeval(任意Python実行・iface/QgsProjectに直接アクセス)/ screenshot/status/open_plugin/reload_plugin/ bridge_call + plugin_id 転送(hub)。

セキュリティの境界: localhost限定・全チャネルでセッショントークン必須で、 他のOSユーザ・ブラウザ発のページ・外部ネットワークからは遮断される。 ただし同一ユーザ権限のプロセスはトークンを読めるため防げない (信頼境界=ローカルユーザアカウント)。詳細は セキュリティモデル を参照。

使い方(B): Harnessでプラグインを開発する

WebEngineベースのQGISプラグインをAIと一緒に作りたい人向け。リポジトリをクローンして使う。

セットアップ(初回のみ)

クローン直後は scripts\setup.ps1 が前提ツール (QGIS 4.x / Node.js 24+ / Python 3.13+)の確認・不足分のインストール(winget経由)から npm install・プラグイン配置までを一括で行う:

git clone <repo> && cd qgis_live_harness
powershell -ExecutionPolicy Bypass -File scripts\setup.ps1
#   -Yes / -CheckOnly / -SkipPlaywright / -SkipDeploy オプションあり

手動でセットアップする場合(スクリプトと等価):

npm install
npm run deploy                 # 管理プラグインをQGISプラグインディレクトリへjunction配置+有効化(開発モード)
npx playwright install         # L1テスト(npm test)を回す場合のみ
pip install pytest             # ユニットテスト(test:unit)を回す場合のみ

開発対象プラグインは qgis-plugin/<id>/ に配置する。 開発対象の切替は plugin.config.json の id を書き換える。

開発ループ

npm run live:ensure     # 常駐QGISを用意(起動済みならアタッチ、未起動なら起動)
                        # ※deployはしない — 未配置なら先に npm run deploy を手動で
# → bridge.py / logic.py / ui/* を編集
npm run live:devreload  # repo側コードを即反映(deploy不要)
npm run test:live       # 実QGIS内で検証(pyevalで内部状態assert含む)

器側(main_plugin.py/live_driver.py等)を変更した時だけ:

npm run live:reload     # 実行中QGISでホットリロード(deployはしない)

deployモード(開発/利用の明示切替)

同じQGISプロファイル内で「開発」と「利用(通常使用)」を 配置形態で明示切替する。モード宣言は profiles/<profile>/qgis_live_mode.json に記録される (宣言は意図の記録であり、現在モードの判定は配置実態 (junction/dir)が優先。乖離時は宣言も併記される)。 現在モードは npm run deploy:status、Driverメニューの 配置モード ダイアログ(現在モード+各プラグインの実配置形態+退避状態)、 および GeoSuiteツールバー先頭のモードバッジ (開発=「開発モード」の赤背景白文字、利用=歯車アイコンのみで非侵襲。 クリックでダイアログを開く)で確認できる。 GeoSuiteは管理対象プラグインのツールバー項目を集約した共有ツールバー。

利用モード ── npm run deploy ──→  利用版を qgis_live_parked/ へ退避 → junction張付 = 開発モード
開発モード ── npm run deploy:use  → junction解除 → parked利用版を復元   = 利用モード
任意      ── npm run deploy:install → repo現状を利用版として配置(旧parked破棄) = 利用モード
(「開発を終えて戻る」=「保存した利用版に戻る」。開発往復で利用版は上書きされない)

安全性の最強ルール: deploy-plugin.ps1(プラグインフォルダへの あらゆる書込み)はAIエージェント・自動スクリプトから一切呼ばれない。 qgis-session.mjs はdeployのコード経路自体を持たないため、 非devモードではAIからプラグイン内容を変える手段が存在しない。 AIが書き換えるのはrepoの作業ツリーのみである。

利用版の新規インストール/更新(リリース)は別コマンド: npm run deploy:install がrepoの現状を利用版として配置する (junction解除・旧parked破棄・repo copy)。確定 → git commit/tag → deploy:install の順で実行すれば、利用版=正式リリース版として追跡できる。

テスト

npm test               # L1: UI単体E2E(ブラウザ+mock。WebEngineプラグインのみ)
npm run test:unit      # Pythonロジックのpytest
npm run test:live      # L2: 実QGIS内検証(QGIS未起動でも自動起動)

Qt Widgets製プラグインもL2の検証対象になる(WebEngineへの作り替えは不要)。 pyevalでQtウィジェットを直接検査・操作し、live dirを持たないプラグインも plugin.config.jsonに列挙すればhub経由でtest:liveが検証する。 詳しくは QGIS Live Harness を参照。

ディレクトリ構成

qgis-plugin/          プラグイン群のルート(複数プラグインをここに並べる)
  <plugin_id>/       プラグイン1つ分。フォルダ名=QGISのプラグインID
    metadata.txt      プラグイン定義(name=はQGIS上の表示名)
    __init__.py       エントリポイント(classFactory)
    main_plugin.py    ダイアログ/view/channel/ドライバ起動 + dev source loader
    live_driver.py    view用ファイルドライバ
                      (eval/pyeval/screenshot/devreload + 共通コマンド)
    bridge.py         ★開発対象: WebChannel経由でJSに公開するAPI
    logic.py          ★開発対象: QGIS非依存の純粋ロジック(pytest対象)
    ui/               ★開発対象: HTML/CSS/JS (mockでブラウザ単体動作も可)
  qgis_live_driver/   QGIS Live Driver。制御専用プラグイン(UIなし・汎用部品)
    live_driver.py    pyeval/screenshot + status/open_plugin/reload_plugin/
                      bridge_call + plugin_id転送の実行体
                      (ファイル+メモリキューdispatch)
    mcp_http.py       内蔵HTTPサーバ(/mcp=MCP Streamable HTTP, /api/*=REST)
    mcp_stdio.py      stdio↔ファイルJSONLブリッジ(同梱・stdlibのみ)
                      詳細: docs/driver.html
plugin.config.json    開発対象のプラグインID(qgis-plugin/下のフォルダ名)
scripts/
  live-drive.mjs      LivePage: クライアント側API(evaluate/pyeval/devreload等)
  qgis-session.mjs    ensure/reload/devreloadのオーケストレーション
  qgis-live-check.mjs L2検証ランナー(npm run test:live)
  qgis-mcp.mjs        MCPサーバ(stdio)。tools: pyeval/eval/screenshot/...
  scan-ini.js         QGIS4.iniの肥大化/破損診断
  repair-ini.js       QGIS4.iniの破損エントリ修復(backup付き)
tests/e2e/            Playwright (L1 = mock使用)
tests/unit/           pytest
docs/                 GitHub Pages用HTML(直接編集)

プラグインの追加・複数開発

qgis-plugin/ の下に プラグインIDと同じ名前のフォルダ で管理する。 複数フォルダを並べると 1つのQGISインスタンスで全プラグインを同時起動 でき、live dirは qgis-<pid>/<plugin_id>/ で分離されるため各プラグインを 独立にeval/pyeval/testできる。deployはqgis-plugin/直下の全プラグインを 一括配置し、test:live は検出した全プラグインに対してチェックを回す。

plugin.config.json の id はserve-uiやMCPのデフォルト対象を指す (metadata.txt の name= は表示名)。

外部API(接続面まとめ)

MCPツール(Harness側)

qgis_ensure / qgis_pyeval / qgis_eval / qgis_bridge_call / qgis_screenshot / qgis_status / qgis_open_plugin / qgis_devreload / qgis_reload

どのツールも内部でensureするため、QGIS未起動でも自動で立ち上がる。

npm run mcp:qgis       # 手動でMCPサーバ(stdio)を起動する場合