手動の Chrome 拡張機能シナリオ

手動記録は Desktop → Web Extension の Admin キャプチャージョブとして動作します。内部環境は WebExtension、キャプチャーメタデータと公開 MCP は web-extension を使います。エージェントは選択した Chrome Web Store の拡張機能をダウンロードし、その拡張機能と Reconstruct のキャプチャー拡張機能を入れた使い捨ての Chromium プロファイルを開きます。操作者が移動し、Reconstruct は画面と観測した遷移を reconstruct.scene.v1 として保存します。

ジョブを作成して実行する

1. Admin → Jobs → Create で Desktop → Web Extension を選びます。拡張機能だけが必要な場合は Web の選択を解除します。モバイル環境は引き続き Web、iOS、Android です。
2. Environment Settings → Web Extension に、選択した Chrome Web Store のリンクを貼り付けます。ローカルの拡張機能ディレクトリーや個人のブラウザープロファイルは入力に使用しません。
3. ジョブをキューに追加します。Desktop / Web Extension が割り当てられた有効な Capture Agent が取得します。Web と Web Extension のワーカーは互いのジョブを取得できません。
4. エージェントは Google の更新サービスから署名付き CRX3 をダウンロードし、選択した拡張機能 ID と公開者の署名を検証してから、非公開のジョブディレクトリーに展開します。展開して読み込んでもパッケージのストア ID は維持されます。キャプチャーバージョンのメタデータには、検証済み ID、ローカライズされた名前、パッケージバージョン、SHA-256 を持つ browserExtension が含まれ、カタログ表示名はそのパッケージから取得します。使用前にアーカイブのパス、ファイル数、展開後サイズを検査します。
5. Chromium は拡張機能自身の初期設定タブを開きます。なければ、宣言されたオプションページまたはアクションのポップアップを使います。UI の入口がない拡張機能は失敗します。
6. ブラウザーの拡張機能メニューから Reconstruct Agent Browser Bridge を開きます。ポップアップには実行中ジョブの ID と保存済み画面数が表示されます。各画面で Capture screen を使います。Pause、Resume、Finish recording もここから操作します。

個別に起動するレコーダー CLI や追加の記録用 MCP はありません。制御は実行中ジョブと非公開のローカルセッショントークンに結び付き、フィールド値、任意のラベル、参照元 URL は受け付けません。管理者は Admin → Jobs → job → Live browser からもジョブのブラウザーを監視・操作できます。ここでの入力はジョブが操作者待ちの間だけ受け付けます。別の拡張機能や別のジョブは拒否されます。拡張機能が別のタブを開いた場合は、キャプチャー前にそのタブをアクティブにします。対象を切り替える前に ID を確認します。パスワード、ウォレットの作成、同意、登録は手動の操作のままです。

サインインジョブと自動探索

初期設定が必要な拡張機能（MetaMask のウォレット作成など）は半自動で記録できます。Environment Settings → Web Extension の Sign-in を Operator registers（または Operator signs in）に設定します。

1. ジョブは操作者を待ちます。Admin → Jobs → job → Live browser、またはジョブのブラウザー自体で初期設定を完了します。Capture screen で画面を保存してください。パスワードと復元フレーズの画面は保存されません。
2. Finish sign-in（コンソール）、Continue（Admin）、または Finish sign-in and explore（Reconstruct のポップアップ）を選びます。
3. その後 Reconstruct は、拡張機能のポップアップ、オプション、サイドパネルと、そのナビゲーション操作の移動先を訪れ、ルートごとに 1 画面を保存します。送信、署名、確認、開示、エクスポート、ロック、削除、作成につながる可能性のある操作はクリックしません。
4. 拡張機能が自らロックした場合、操作者が解除して再び Finish sign-in を選ぶまで、ジョブは Signed out で待機します。ルートがなくなるかページ上限に達すると、記録が終了して審査用にアップロードされます。

Web ジョブにも同じ Sign-in 設定があります。サインイン画面はステージとして保存され、クロールはサインアウトリンクをスキップし、セッションが終了すると一時停止します。CAPTCHA、SMS コード、規約への同意は常に操作者が行います。詳細は backend/docs/operator-sign-in.md を参照してください。

エージェントの設定

backend/agent-browser-extensions で yarn nx run chrome:build を実行し、対応するブラウザーアダプターをビルドします。ホストには Node.js 24 以上、Python 3、拡張機能に対応した Chromium ビルドが必要です。gitignore 対象のローカル設定または環境変数を使って、既存の Capture Agent を設定します。

{
  "Agent": {
    "Id": "extension-worker",
    "ApiUrl": "https://internal-admin-api.example",
    "ChromiumPath": "/Applications/Chromium.app/Contents/MacOS/Chromium",
    "ExtensionDir": "/checkout/backend/agent-browser-extensions/chrome"
  },
  "WebExtension": {
    "RecorderDirectory": "/checkout/backend/tools/manual-recorder",
    "NodePath": "node",
    "PythonPath": "python3"
  }
}

既存の ApiTokens:Agent 認証情報はシークレット設定で渡します。既存の Kestrel Web リスナーはループバックでなければなりません。Capture Agent のバイナリーを extension serve で起動し、Admin でエージェントレコードに Desktop / Web Extension を割り当てます。各ホストモードは自身のリスナーと作業ロックを所有するため、同じエンドポイントで 2 つのワーカーを起動しないでください。拡張機能は独自のネットワーク処理とバックグラウンドコードを実行するため、リモートワーカーには管理された隔離ブラウザーホストと明示的な WebExtension:ManagedBrowserIsolated 宣言が必要です。このフラグ自体は隔離を作りません。既存の明示的な Agent:AllowHttpApi 設定は、ループバックの開発用 API に適用されます。

ワーカーは、ジョブ取得、ハートビート、キャンセル、アップロード再試行を管理します。内部の Node 子プロセスは非公開のプロセス間パイプを使い、デバッグ用 TCP ポートは使いません。終了時にジョブのブラウザーを閉じ、一時プロファイルを削除します。空のテスト用ウォレットを使ってください。シナリオに認証情報や利用可能なウォレットは保持されません。

シークレットと画像の審査

パスワード、復元フレーズ、キー、コードを入力する前に一時停止します。機密画面から移動した後に再開します。保護対象のテキスト画面は安全側に失敗し、観測の欠落を作ります。スクリーンショット前に編集可能なコントロールとその子孫をマスクし、フィールド値は Scene に読み込みません。キャプチャー中に保護状態、マスク、ナビゲーション、ドキュメント内容が変わった場合は、前後の検査でキャプチャーを拒否します。

Canvas などの不透明なピクセルは、非公開の審査用メディアに表示されたままです。DOM 検査ではシークレットが含まれないと断定できません。検査とマスクは単一の隔離ワールド評価内で同期実行します。ネイティブ Canvas の内容を描画できるよう、スクリーンショット中も JavaScript は有効です。

Finish recording は結果を自動的にパッケージ化し、非公開キャプチャーとしてアップロードします。各チェックポイントはページ、Scene、スクリーンショットを所有します。シナリオ索引はテキストをコピーせずページを参照します。Admin の Hide personal data ですべてのスクリーンショットを確認し、機密部分をぼかすか危険なメディアを削除し、審査後に公開します。マスキングは該当する Scene テキスト、アクセシビリティー名、繰り返し値、メディア参照も消去します。別に保存された元メディアには個別の審査が必要です。記録の制御から公開や生画像の返却はできません。

MCP による再構築

審査・公開後、エージェントは通常の Capture MCP カタログからバージョンを見つけます。get_scenario_scene を使い、Admin のマスキングを含む現在のページ所有データから構成したフレーム、プロファイル、遷移を読み込みます。承認済み画像には通常の公開ページツールを使います。必要なすべてのキャプチャー画面とプロファイルに対して再構築を検証してください。ツールの成功だけでは視覚的な忠実度は証明されません。

根拠と制限

チェックポイントは静的な観測です。移動、メニュー、モーダルなどの展開後と、必要な各ビューポートでキャプチャーします。隣接する観測は変化あり／なしの結果を測定しますが、自動クリックの実行を証明しません。一時停止とブロックの区間は明示的な欠落になります。このモードはすべてのクリックを黙って記録したり、登録を再生したり、OS ネイティブの許可ダイアログを取得したり、静止画像からアニメーションを推論したりしません。シークレットを含む手順は手動のままで、公開シナリオに含まれません。ジョブのページ上限がチェックポイント数を制限します（自動選択の既定値は 200）。Scene ノードの上限はジョブごとに 100,000 です。ジョブ時間と要素数の上限も適用されます。

リクエストの利用可否

Admin → Requests → Job defaults → Request submissions で、許可する製品種類／環境のペアを設定します。既定値は Desktop/Web、Desktop/Web Extension、Mobile/Web です。Allow new requests ですべての新規送信を停止・再開します。停止中に保存しても選択したペアは維持されます。既存のリクエストと公開済みキャプチャーは引き続き利用できます。同じ保存済みポリシーが Platform API と認証済み MCP の両方に適用され、古いフォームの選択肢を持つクライアントも対象です。停止中、request-options エンドポイントはプラットフォームを返しません。カタログの製品種類／環境の選択欄には、その製品で取得済みの環境だけが表示されます。リクエストの利用可否によって公開済みカタログの根拠が隠れることはありません。