devchristian1337/record-and-replay

Record & Replay（ブラウザ + デスクトップ）

Record & Replay を使用すると、エージェントはユーザーが実演するワークフローを学習し、再利用可能なスキルに変換できます。2つのモードがあります：

• ブラウザモード（デフォルト、最も豊富な証拠）：ヘッド付きPlaywrightブラウザ（システムのGoogle Chromeが利用可能な場合はそれを使用）が、複数のセレクタ候補を含むすべてのユーザーアクションを events.jsonl に記録し、さらにPlaywrightトレースチャンク（trace-NNN.zip）も記録します。macOS、Windows、Linuxで動作します。
• デスクトップモード（ネイティブアプリ）：軽量なシングルプロセスレコーダー（pynput）が、グローバルなマウス/キーボードイベント、アクティブウィンドウの変更、クリック時のスクリーンショット、各クリックのアクセシビリティターゲット（macOS AX、Windows UI Automation）を desktop-events.jsonl と screens/ にキャプチャします。パスワードフィールドはマスキングされます。Codexと同等の機能（Codexもビデオではなくイベント/コンテキストストリームを記録します）、CPU使用率は約1〜3％です。macOS、Windows、Linux（X11）で動作します。詳細は「デスクトップ記録」を参照してください。

ワークフローがブラウザのみの場合は、ブラウザモードを選択してください。そのセマンティックセレクタは、デスクトップの座標よりもはるかに優れたスキルを生成します。

セットアップ（初回のみ）

cd ~/.agents/skills/record-and-replay
node setup.mjs      # npm install + （Chromeがない場合のみChromiumをダウンロード）+ セルフテスト
node install.mjs    # エージェントスキルディレクトリにリンク（macOS/Linuxではシンボリックリンク、Windowsではジャンクション）

playwright npmパッケージをインストールします。Google Chromeがインストールされている場合、ブラウザはダウンロードされません（レコーダーは channel: 'chrome' を使用します）。それ以外の場合は、Chromiumがダウンロードされます。どちらのスクリプトもクロスプラットフォーム（Node.js）です。

記録ワークフロー

1. 開始する前に、ユーザーにキャプチャされたくないウィンドウ、ファイル、会話を閉じるよう伝え、保存されたくない秘密を入力しないように伝えてください。ユーザーが準備できた場合にのみ、レコーダーをバックグラウンドで切り離して起動してください。出力ディレクトリを事前に把握できるよう、常に --name <slug> を渡してください：

   cd ~/.agents/skills/record-and-replay
   # macOS / Linux:
   nohup node scripts/recorder.mjs --minutes 30 --name <slug> [--url <startUrl>] \
     > ~/.agents/recordings/recorder.log 2>&1 &
   # Windows (PowerShell):
   Start-Process node -WindowStyle Hidden -ArgumentList "scripts/recorder.mjs","--minutes","30","--name","<slug>"
   

   ネイティブのバックグラウンド実行機能を持つエージェント（例：Claude CodeのBash run_in_background）は、代わりにそれを使用しても構いません。出力は ~/.agents/recordings/<slug>/ に保存されます。

2. 起動を一度確認してください（起動後約2〜3秒後 — 単一チェック、ポーリングループではありません）：~/.agents/recordings/<slug>/session.json が存在し、"status": "recording" であることを確認してください（レコーダーは成功時にログに {"status":"recording",...} という行も出力します）。チェックが失敗した場合は、ログを読んでください。recording_already_active（終了コード2）は、別の録画がロックを保持していることを意味します。launch_failed またはモジュールが欠落しているエラーは、セットアップが必要であることを意味します。実際の問題を報告し、ユーザーに録画が開始されたとは伝えないでください。

3. 起動チェック後は、スリープ、ポーリング、またはループで待機しないでください。あなたのターンを終了します：ユーザーに録画が開始されたこと、時間制限、および小さなフローティングコントロールウィンドウ（右下、Codexの録画コントロールと同様）にタイマーと一時停止/再開、停止、破棄（2回タップして確認）ボタンがあることを伝えてください。一時停止中は何もキャプチャされません — イベントとトレースの両方が停止します。ユーザーが誤ってコントロールウィンドウを閉じると、自動的に再開します。メインブラウザウィンドウを閉じるとセッションも終了します（Cmd+Qでブラウザを完全に終了することは避けてください。最後の1分間のトレースが失われる可能性があります）。起動時に --badge を渡すと、コントロールウィンドウの代わりにページ内バッジが使用されます（特殊な環境向けのフォールバック）。

4. 一時停止/再開（ユーザーが一時停止を要求した場合、または機密性の高い部分をスキップする必要がある場合）：touch ~/.agents/recordings/<slug>/PAUSE を実行すると、2秒以内に一時停止します。ファイルを削除すると再開します。コントロールウィンドウのボタンと PAUSE ファイルは同期が保たれます。session.json には現在の paused 状態が記録されます。一時停止中の間隔は、events.jsonl に paused/resumed マーカーとして表示され、トレースには含まれません。

5. ユーザーが完了したと言った場合：

   • プロセスがまだ実行中の場合は、正常に停止します：touch ~/.agents/recordings/<slug>/STOP（レコーダーは2秒以内にそれを認識し、最終処理を行います）。
   • session.json を読み取ります — status: "recording" はまだライブであることを意味し、"completed" は出力が最終であることを意味し、"discarded" はユーザーが破棄ボタンを押したことを意味します — 証拠ファイルは削除されました。それを認め、決してスキルを作成しないでください。endReason は、user_stopped、user_discarded、browser_closed、stop_file、time_limit、signal、event_limit のいずれかです。
   • 応答する前にキャプチャされたイベントを検査します：node scripts/summarize.mjs <outDir> を実行してコンパクトなタイムラインを表示し、詳細が必要な手順については events.jsonl を直接読み取ります。

6. キャンセルは endReason ではなく内容によって定義されます：kind: "dom" イベントがほとんどまたはまったくない録画は — endReason に関係なく — キャンセルされたものとして扱います。それを認め、スキルを作成または更新しないでください。

7. 録画に再利用可能なワークフローを特定するのに十分な情報が含まれている場合は、デフォルトでそのためのスキルを作成または洗練してください — ユーザーが明示的に要求しなかった場合でも。概要やリプレイ計画のみを作成した後で停止しないでください。以下の「録画からのスキル作成」に従ってください — これは短い明確化ラウンドから始まります。

8. 録画がワークフローを特定するには薄すぎるか曖昧な場合は、推測しないでください。何が不明瞭かを説明し、ユーザーに不足している部分を尋ねてください。

同時録画

同時にアクティブにできる録画は1つだけです（ロックファイル ~/.agents/recordings/.lock）。レコーダーが recording_already_active で終了した場合、強制的に別の録画を開始しないでください。録画がすでに進行中であることをユーザーに伝え、それを使用するか、最初に停止するかを尋ねてください。同じ --name で再起動しても安全です。以前の events.jsonl はタイムスタンプ付きの .bak として保持され、追加されません。

イベントの解釈

events.jsonl が主要な証拠です。session.json はタイミング/パスのみを提供します。trace-NNN.zip チャンクはDOMレベルの真実です（npx playwright show-trace <outDir>/trace-*.zip、session.json の traceChunks が順にリストします）。トレースのデフォルトはライトモードです — アクションごとに完全なDOMスナップショットがありますが、連続的なスクリーンショットはありません（CPU使用率を低く抑えます）。ユーザーがピクセル単位の完全な視覚的証拠を望む場合は --trace full で開始し、最小限のフットプリントを望む場合は --trace off で開始します。

各行は1つのイベントです：{seq, t（開始からのミリ秒）, kind, type, url, ...}。

• kind: "page" — ナビゲーション、ダウンロード、ダイアログ、タブの開閉。ナビゲーションはワークフローを段階に分割します。
• kind: "dom" — ユーザーアクション。target.selectors は複数のセレクタ候補を保持します：testId、role（{role, name}）、id、nameAttr、text、css。リプレイコードを生成する際は、その順序で優先的に使用してください。css は最後の手段です。
• type: "input" イベントはデバウンスされます — フィールドごとに1つのイベントで最終値が保持されます（blur、Enter、change、フォーム送信時にフラッシュされます）。パスワード/クレジットカード/OTPのようなフィールド（英語とトルコ語の名前：password、parola、şifre、kart、kimlik…）は、事前にマスクされて到着します（***MASKED***、masked: true）。
• selection と copy イベントは、ユーザーがどのコンテンツを操作していたかを明らかにします — ユーザーが「これ」や「私が選択したもの」に言及した場合の最良の手がかりとなることがよくあります。シークレットのように見える選択（OTP、APIキー、トークン）はマスクされます。paste イベントは長さ/単語数のみを保持し、内容は保持しません。
• 機密データ：マスキングはヒューリスティックであり、保証ではありません — そして、それは events.jsonl にのみ適用されます。トレースチャンクはマスクされません：DOMスナップショットには生の入力値（JSONLでマスクされた値を含む）が含まれ、スクリーンショットは画面上に表示されるすべて（公開されたトークン、2FAコード、残高）をキャプチャします。~/.agents/recordings/<name>/ ディレクトリ全体を機密として扱ってください：ローカルでのみ検査し、アップロードやコミットを決して行わず、要約や生成されたスキルにリテラルの秘密を引用しないでください — プレースホルダーまたは一般的な説明を使用してください。

録画からのスキル作成

スキルを作成する前に references/skill-authoring.md を読んでください：そこには質問バンク、フロントマターの制限、SKILL.mdの骨子、バンドルスクリプトのルール、品質チェックリストが含まれています。skill-creator スキルが環境で利用可能な場合、そのガイダンスも適用されます。単なるMarkdownのランブックではなく、実際に検出可能なスキル（SKILL.md フォルダ）を作成してください。

このチェックリストをコピーしてチェックを入れてください：

- [ ] 1. 録画を要約する。すべてのギャップ（決定、マスクされた部分、盲点）を書き留める
- [ ] 2. 明確化：1つのメッセージで、最大6つの質問、ギャップについてのみ
- [ ] 3. このワークフローをカバーする既存のスキルがないか確認する → 重複する代わりにそれを更新する
- [ ] 4. スキル + evals/evals.json を書く（録画はテストケース1）
- [ ] 5. 検証：node scripts/export-skill.mjs <skillDir> --check → エラーを修正し、再実行
- [ ] 6. トリガーチェックとドライランを提供する。修正を反映させ、metadata.version を更新する
- [ ] 7. claude.ai ZIPエクスポートを提供する

ステップ2 — 書く前に明確化する。 録画には音声はありません。録画は何が起こったかを示しますが、理由は示しません。録画から表示されるものについては回答し、次にユーザーに質問します — 一度だけ、1つのメッセージで、最大6つの質問 — 録画が表示できないことについて：結果とそれが機能したかどうかを確認する方法、実行ごとに異なる値、ある時点でなぜXを選択したか、どのアクションが回り道だったか、スキルをトリガーするために何と言うか（そして何を言うべきでないか）、確認が必要なアクション。該当する瞬間を引用します（「02:14に日付フィルターをクリアしました — なぜですか？」）。構造化質問ツールがあればそれを使用します。それ以外の場合はプレーンチャットを使用します。録画とユーザーのリクエストですべてがすでに回答されている場合にのみ、このラウンドをスキップし、そのように伝えます。

作成ルール：

• 録画をユーザーの意図した結果の証拠として扱い、ピクセル単位でリプレイするスクリプトとしては扱わないでください。コネクタ/API/CLI/MCPツールが同じ結果を意味的に達成できる場合（カレンダーイベントを作成する、PRを開く、メッセージを投稿する）、UI自動化よりもそれを優先してください。
• UIリプレイが本当に必要な場合は、scripts/replay-template.mjs からPlaywrightスクリプトを生成します：セマンティックロケータ（getByTestId > getByRole > getByLabel > getByText）、各重要なアクションの後の検証ステップ、環境変数からのシークレット。イベントストリームがより良いターゲットを提供しない限り、生の座標を使用しないでください。
• デスクトップステップは、キャプチャされたターゲット（役割 + 名前 + ウィンドウ、例：ボタン「保存」 in 「請求書 — Acme」）に名前を付けて、アクセシビリティツリーがそれを見つけられるようにします。ターゲットがキャプチャされなかった場合にのみ座標を使用します。
• レコーダーの永続的なプロファイル（~/.agents/recordings/.browser-profile）は、セッション間でログイン状態を保持するため、生成されたスキルは通常ログイン手順を必要としません。セキュリティ：そのディレクトリには、ライブの認証済みセッション素材（クッキー/localStorage。PlaywrightはモックキーチェーンでChromeを起動するため、プレーンテキストの資格情報として扱います）が含まれています。暗号化せずにコミット、共有、バックアップしないでください。また、それを再利用するリプレイスキルはすべて、ユーザーのログインで実行されることに注意してください。信頼できない、または機密性の高いサイトでの録画には、使い捨てプロファイル（--out と一時プロファイル）を優先するか、その後プロファイルをクリアしてください。
• 新しいスキルは ~/.agents/skills/<skill-name>/ に保存してください（フォルダ名 = name、ケバブケース）。そして、それらをエージェントスキルディレクトリにシンボリックリンクしてください（パターンについては install.mjs を参照）。これにより、このマシン上のすべてのエージェントがそれらを使用できます。
• 変わるもの（日付、金額、名前）はパラメータ化し、変わらないものはハードコードします。生成されたSKILL.mdにワークフローの目的と検証基準を記載してください。シークレットやマスクされた値をスキルにコピーしないでください。

claude.ai用のエクスポート（提供する。要求に応じて実行）：node scripts/export-skill.mjs ~/.agents/skills/<name> は ~/.agents/exports/<name>.zip を書き込みます（ZIPルートにフォルダ。README、evals、キャッシュ、録画証拠は除外され、成功前にアーカイブが読み戻されます）。スキルがClaude Code専用のフロントマター（disable-model-invocation など）を使用する場合は、--strip-cc-keys を追加してください。ファイルの場所をユーザーに伝え、カスタマイズ › スキル › + › スキルをアップロード（コード実行が有効になっている必要があります）でアップロードされることを伝えます。

デスクトップ記録（macOS、Windows、Linux/X11）

セットアップ：node setup.mjs（requirements-desktop.txt から最小限の .venv-desktop Python環境を作成します — pynput + mss + pillow、Windowsではcomtypesも、約50 MB。 uv が必要です）。

権限（macOS）：レコーダーはそれらを事前チェックし、機械可読な状態を報告するため、決して推測しないでください。start は permissions: {inputMonitoring, screenRecording, grantTo} と、何かが欠落している場合の warning を出力し、自動的にシステムダイアログを表示して適切な設定ペインを開きます（--no-permission-prompt で無効化。node scripts/desktop-record.mjs permissions でオンデマンド実行）。grantTo はユーザーが許可する必要があるアプリの名前です — TCC許可はPythonではなく、エージェントをホストする .app バンドルにバインドされ、その後そのアプリを再起動する必要があります。grantTo をそのまま伝えてください。ユーザーに「ターミナルに許可を与えてください」と伝えるのは通常間違いです。Windowsは許可も管理者権限も必要としません。

エンジンはシングルプロセスレコーダーです（CPU使用率約0〜3％）：入力イベントストリーム + アクティブウィンドウ/タイトルの変更 + 各クリック時の半解像度JPEG（最大1/700ms）→ desktop-events.jsonl + screens/。各クリックには、カーソル下の要素のアクセシビリティ記述も含まれます（kind: "target" 行、forSeq でクリックに結合）：role、name、automationId、window、ancestors — 生の座標ではなく、Button "Save" のようなセマンティックターゲットです（macOS AX、Windows UI Automation、Linuxではなし）。入力は type: "text" イベントとして到着し、各バーストの最終値を保持します（バックスペースによる修正が適用されます）。ショートカットと特殊キーは press イベント（ctrl+c、enter）として到着します。スクリーンショット、ターゲットクエリ、フォーカスチェックはワーカースレッドで実行され、入力コールバックでは決して実行されません：遅いコールバックはmacOSのイベントタップを無効にし、Windowsのフックをサイレントに削除します（レコーダーは後者も監視し、フックを再インストールします）。

これはCodexと同等の機能です：CodexのRecord & Replayも記録します...