rhwp GUI Agent
このスキルを使用して、人間向けのWebエディタとしても、エージェントが制御可能なGUIとしても動作する rhwp-studio を操作します。機能確認には実際のGUI操作を優先し、?agent=1 ブリッジは準備状態の確認、状態検査、サンプル読み込み、エクスポート検証にのみ使用してください。
クイックスタート
rhwpリポジトリのルートから:
cp .env.docker.example .env.docker
docker compose --env-file .env.docker run --rm wasm
cd rhwp-studio
npm ci
npm run build
python3 -m http.server 8765 --bind 0.0.0.0 -d dist
http://127.0.0.1:8765/?agent=1 を開きます。?agent=1 がない場合、エディタはユーザー向けに動作しますが、自動化ブリッジは公開されません。
コアワークフロー
- Studioを起動する前に
pkg/rhwp.jsとpkg/rhwp_bg.wasmをビルドします。npm run buildがCannot find module '@wasm/rhwp.js'を報告する場合、WASMパッケージがビルドされていません。 - ビルドされたアプリを配信するか、Viteを実行します。Viteがサンドボックス内でポートにバインドできない場合は、
python3 -m http.server ... -d distを使用します。 /?agent=1に対してブラウザ自動化セッションを開始します。- アクションにはGUIセレクタを使用します:
- メニュー:
#menu-bar .menu-item[data-menu="<menu>"] .menu-title - メニューコマンド:
[data-cmd="<command-id>"] - ツールバーボタン:
.tb-btn[data-cmd="<command-id>"] - スタイルバーコントロール:
#style-name、#font-lang、#font-name、#font-size、#btn-bold、#btn-italic、#btn-underline、#btn-strike、#btn-text-color、#btn-highlight、配置ボタン、#linespacing-select - ファイル入力:
#file-input - キャンバスエディタ:
#scroll-container canvas
- メニュー:
- 観察には
window.__rhwpAgentを使用します:ready()context()commands()pageCount()fileName()loadSample(path)loadBytes(bytes, fileName)createNewDocument()exportHwp()、exportHwpx()
- 各機能クラスターの後にスクリーンショットとエクスポートファイルをキャプチャします。クリック失敗、無効なコマンド、コンソールエラー、空白のキャンバスはテスト失敗として扱います。
機能カバレッジ
すべてのGUI機能を列挙またはテストする場合は、references/feature-map.md を参照してください。このファイルには、トップレベルメニュー、コマンドID、ダイアログ、ツールバーコントロール、および hwpctl アクションがマッピングされています。
自動スモーク実行には、以下を使用:
cd rhwp-studio
node e2e/agent-gui-full-smoke.mjs
環境によってブラウザ起動がブロックされる場合でも、以下を実行:
npm run build
その後、e2e/agent-gui-full-smoke.mjs を確認し、ブラウザが利用可能な環境で実行します。
テスト戦略
3つのレイヤーを使用:
- ビルド検証:
docker compose --env-file .env.docker run --rm wasm、続けてnpm run build。 - GUIスモーク: 新しいドキュメントを作成し、テキストを入力し、文字/段落の書式を切り替え、表を作成し、図形ピッカーを開き、記号ダイアログを開き、
.hwpと.hwpxサンプルを読み込み、.hwpを保存/ダウンロードし、スクリーンショットをキャプチャします。 - 詳細チェック: 実際のブラウザが利用可能な場合、既存の
rhwp-studio/e2e/*.mjsテストと hwpctl シナリオを実行します。
最初に組み込みサンプルを優先:
public/samples/basic/KTX.hwp
public/samples/form-002.hwpx
public/samples/BlogForm_BookReview.hwp
public/samples/biz_plan.hwp
public/samples/field-01.hwp
public/samples/footnote-01.hwp
public/samples/number-bullet.hwp
公開HWP/HWPXサンプルをダウンロードする場合は、rhwp-studio/public/samples/external/ に保存し、読み込む前にファイルシグネチャを確認し、ソースURL、ファイル名、バイトサイズ、読み込み結果を記録します。
エージェントブリッジルール
ブリッジは、GUIカバレッジを迂回するためではなく、状態の観察と再現可能なテストフィクスチャの読み込みに使用します。「表作成が機能する」という機能の主張には、ツールバー/メニューとダイアログをクリックします。「ドキュメントが読み込まれた」という主張には、window.__rhwpAgent.pageCount() が適切です。
コマンドがHTMLに表示されているからといって、実装されていると想定しないでください。src/command/commands/*.ts で相互確認してください。一部のメニュー項目はプレースホルダーであるか、コンテキストに応じて無効になっています。
一般的な失敗
listen EPERM: 承認されたポートで静的サーバを使用するか、サンドボックス外で実行します。- ブラウザ起動失敗: Chrome/Chromiumの実行が許可されている場所でスクリプトを実行し、必要に応じて
CHROME_PATHを設定します。 - HWPX保存が無効: 現在のベータパスでは、HWPXソースドキュメントで予期される動作です。
@wasm/rhwp.jsが見つからない: DockerでWASMを再ビルドします。- ヘッドレスChromeでFile System Access APIが利用不可: フォールバックダウンロードフローを期待します。