OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Get started

Canvas Plugin のリファクタリング

Canvas plugin のリファクタリング

Canvas は利用頻度が低く、実験的です。コア機能ではなく、同梱 Plugin として扱います。コアには汎用的な Gateway、Node、HTTP、認証、設定、ネイティブクライアントの基盤を残せますが、Canvas 固有の動作は extensions/canvas 配下に置く必要があります。

目標

現在のペアリング済み Node の動作を維持しながら、Canvas の所有権を extensions/canvas に移します。

  • エージェント向けの canvas ツールは Canvas Plugin が登録する
  • Canvas Node コマンドは、Canvas Plugin が登録した場合にのみ許可される
  • A2UI のホストおよびソースファイルは Canvas Plugin 配下に置く
  • Canvas ドキュメントの実体化は Canvas Plugin 配下に置く
  • CLI コマンドの実装は Canvas Plugin 配下に置くか、Plugin が所有するランタイムバレルを介して委譲する
  • ドキュメントと Plugin インベントリでは、Canvas を実験的かつ Plugin ベースとして説明する

対象外

  • このリファクタリングでは、ネイティブアプリの Canvas UI を再設計しない。
  • Canvas を削除するという別途の製品判断がない限り、iOS、Android、macOS から Canvas のプロトコル／クライアント対応を削除しない。
  • 同じ接続面を必要とする同梱 Plugin がほかに少なくとも 1 つない限り、Canvas のためだけに広範な Plugin サービスフレームワークを構築しない。

現在のブランチの状態

完了済み：

  • extensions/canvas に同梱 Plugin パッケージを追加。
  • extensions/canvas/openclaw.plugin.json を追加。
  • エージェントの canvas ツールを src/agents/tools/canvas-tool.ts から extensions/canvas/src/tool.ts に移動。
  • src/agents/openclaw-tools.ts から createCanvasTool のコア登録を削除。
  • Canvas ホスト実装を src/canvas-host から extensions/canvas/src/host に移動。
  • テスト、パッケージング、外部公開される Canvas ヘルパー向けに、Plugin が所有する互換性バレルとして extensions/canvas/runtime-api.ts を維持。
  • Canvas ドキュメントの実体化を src/gateway/canvas-documents.ts から extensions/canvas/src/documents.ts に移動。
  • Canvas CLI 実装と A2UI JSONL ヘルパーを extensions/canvas/src/cli.ts に移動。
  • Canvas ホスト URL とスコープ付きケイパビリティのヘルパーを extensions/canvas/src に移動。
  • Canvas Node コマンドのデフォルトを、ハードコードされたコアのリストから Plugin の nodeInvokePolicies に移動。
  • plugins.entries.canvas.config.host に Plugin 所有の Canvas ホスト設定を追加。
  • Canvas および A2UI の HTTP 配信を、Canvas Plugin の HTTP ルート登録の背後に移動。
  • Plugin 所有の HTTP ルート向けに、汎用的な Plugin WebSocket アップグレードディスパッチを追加。
  • Canvas 固有の Gateway ホスト URL と Node ケイパビリティ認証を、汎用的なホスト型 Plugin サーフェスおよび Node ケイパビリティヘルパーに置き換え。
  • Plugin 所有のホスト型メディアリゾルバーを追加し、コアが Canvas ドキュメント内部をインポートする代わりに、Canvas ドキュメント URL が Canvas Plugin を介して解決されるように変更。
  • api.registerNodeCliFeature(...) を追加し、親コマンドのパスを手動で記述せずに、Canvas が openclaw nodes canvas を Plugin 所有の Node 機能として宣言できるように変更。
  • 本番用 src/** からの extensions/canvas/runtime-api.js のインポートを削除。
  • A2UI バンドルのソースを apps/shared/OpenClawKit/Tools/CanvasA2UI から extensions/canvas/src/host/a2ui-app に移動。
  • A2UI のビルド／コピー実装を extensions/canvas/scripts 配下に移動し、ルートのビルド接続を汎用的な同梱 Plugin アセットフックに置き換え。
  • ランタイムのレガシーなトップレベル canvasHost 設定エイリアスを削除。
  • openclaw doctor --fix が古い canvasHost 設定を plugins.entries.canvas.config.host に書き換えるよう、Canvas の doctor マイグレーションを維持。
  • Gateway プロトコル v4 より前の旧エージェント向け Canvas プロトコル互換性を削除。ネイティブクライアントと Gateway は、pluginSurfaceUrls.canvas と node.pluginSurface.refresh のみを使用するようになりました。非推奨の canvasHostUrl、canvasCapability、node.canvas.capability.refresh の経路は、この実験的なリファクタリングでは意図的にサポートされません。
  • 生成された Plugin インベントリを更新し、Canvas を追加。
  • docs/plugins/reference/canvas.md に Plugin リファレンスドキュメントを追加。

コア所有のまま残っている既知の Canvas サーフェス：

  • apps/ 配下のネイティブアプリの Canvas ハンドラーは、引き続き意図的に Canvas Plugin サーフェスを利用する
  • apps/ 配下のネイティブアプリの Canvas プロトコル／クライアントハンドラー
  • 公開アーティファクトの出力は、後方互換性のあるランタイム検索のために引き続き dist/canvas-host/a2ui を使用するが、コピー手順は現在 Plugin が所有する

目標構成

extensions/canvas が所有するもの：

  • Plugin マニフェストとパッケージメタデータ
  • エージェントツールの登録
  • Node invoke コマンドポリシー
  • Canvas ホストと A2UI ランタイム
  • Canvas A2UI バンドルのソースとアセットのビルド／コピースクリプト
  • Canvas ドキュメントの作成とアセット解決
  • Canvas CLI の実装
  • Canvas ドキュメントページと Plugin インベントリエントリ

コアが所有するのは汎用的な接続面のみ：

  • Plugin の検出と登録
  • 汎用エージェントツールレジストリ
  • 汎用 Node invoke ポリシーレジストリ
  • 汎用 Gateway HTTP／認証と WebSocket アップグレードディスパッチ
  • 汎用ホスト型 Plugin サーフェス URL の解決
  • 汎用ホスト型メディアリゾルバーの登録
  • 汎用 Node ケイパビリティトランスポート
  • 汎用設定基盤
  • 汎用同梱 Plugin アセットフックの検出

ネイティブアプリは、プロトコルのクライアントとして Canvas コマンドハンドラーを保持できます。ネイティブアプリは Plugin ランタイムの所有者ではありません。

移行手順

  1. plugins.entries.canvas.config.host を Plugin 所有の設定サーフェスとして扱う。
  2. Canvas を実験的な同梱 Plugin として説明するようにドキュメントを更新する。
  3. Canvas に焦点を当てたテスト、Plugin インベントリチェック、Plugin SDK API チェック、およびランタイム境界の影響を受けるビルド／型ゲートを実行する。

監査チェックリスト

リファクタリングの完了を宣言する前に：

  • rg "src/canvas-host|../canvas-host" で使用中のソースインポートが検出されない。
  • rg "canvas-tool|createCanvasTool" src でコア所有の Canvas ツール実装が検出されない。
  • rg "canvas.present|canvas.snapshot|canvas.a2ui" src/gateway で、汎用 Plugin ポリシーテスト以外にハードコードされた許可リストのデフォルトが検出されない。
  • rg "extensions/canvas/runtime-api" src --glob '!**/*.test.ts' の結果が空である。
  • rg "canvas-documents" src の結果が空である。
  • rg "registerNodesCanvasCommands|nodes-canvas" src の結果が空である。Canvas Plugin は、ネストされた Plugin CLI メタデータを通じて openclaw nodes canvas を登録する。
  • rg "createCanvasHostHandler|handleA2uiHttpRequest" src/gateway で Gateway ランタイムの所有が検出されない。
  • rg "apps/shared/OpenClawKit/Tools/CanvasA2UI|canvas-a2ui-copy|extensions/canvas/src/host/a2ui" scripts .github package.json で、互換性ラッパーまたは Plugin 所有のパスのみが検出される。
  • pnpm plugins:inventory:check が成功する。
  • pnpm plugin-sdk:api:check が成功するか、生成された API ベースラインが意図的に更新され、レビューされている。
  • Canvas を対象としたテストが成功する。
  • Canvas ホスト／A2UI パスの変更レーンテストが成功する。
  • PR 本文に、Canvas が実験的かつ Plugin ベースであることが明記されている。

検証コマンド

反復作業中は、対象を絞ったローカルチェックを使用します：

sh
pnpm test extensions/canvas/src/host/server.test.ts extensions/canvas/src/host/server.state-dir.test.ts extensions/canvas/src/host/file-resolver.test.tspnpm test src/gateway/server.plugin-node-capability-auth.test.ts src/gateway/server-import-boundary.test.tspnpm test extensions/canvas/src/config-migration.test.ts src/commands/doctor-legacy-config.migrations.test.tspnpm test test/scripts/changed-lanes.test.ts test/scripts/build-all.test.ts extensions/canvas/scripts/bundle-a2ui.test.ts test/scripts/bundled-plugin-assets.test.ts extensions/canvas/scripts/copy-a2ui.test.ts src/infra/run-node.test.tspnpm tsgo:extensionspnpm plugins:inventory:checkpnpm plugin-sdk:api:check

ランタイムバレル、遅延インポート、パッケージング、または公開される Plugin サーフェスを変更した場合は、プッシュ前に pnpm build を実行します。

Was this useful?
On this page

On this page