reverse-eng-site-skill

サイト API のリバースエンジニアリング

1 つの移行手順に従います。計測してから、再実行します。ログイン済みブラウザーを計測プローブとして使用し、状態を確認してリクエストを発生させます。対象のリクエストを取得したら、すぐに UI 操作を終了し、実行を直接 HTTP に移します。ブラウザーは、直接リクエストの認証済みトランスポートとして、または認証の更新に引き続き使用できますが、以降の手順でサイト内のクリック操作を再開することはありません。

1. 操作を定義する

観測可能な操作を、次の形式で 1 つ記述します。

Given <state>, perform <action>, obtain <exact result>.

読み取り専用か状態変更ありかを分類します。状態変更を伴う操作の場合は、元に戻せるテスト用オブジェクトを選び、検出作業中に一括実行しないようにします。

完了条件： 操作が読み取り専用か状態変更ありか分類され、対象の結果が明確であり、状態変更を伴う操作には元に戻せるテスト用アクションがあること。

2. リクエストを 1 つ取得する

ユーザーが既に認証済みのブラウザーセッションを使用します。アクションの前にネットワークキャプチャを開始し、ログを保持して無関係なトラフィックを消去してから、結果を 1 回だけ生成する最小限の UI アクションを実行します。リクエストボディを含み、ナビゲーション後も保持される DevTools Protocol または HAR によるキャプチャを優先します。

次の項目を記録します。

• メソッド、完全な URL、クエリパラメーター、ステータス、開始元
• リクエストヘッダーとボディの形式（秘密の値は伏せる）
• レスポンスのコンテンツタイプ、サイズ、トップレベルの構造、秘密情報を含まない UI カナリア 2 つ
• Cookie、認証ヘッダー、CSRF トークン、リクエスト署名が存在するかどうか

HAR を利用できる場合は、次を実行します。

python <skill-dir>/scripts/har_candidates.py capture.har

以下および以降で、<skill-dir> はこの SKILL.md を含むディレクトリを指します。

リポジトリ外のプライベートな一時ディレクトリに capture.har を保存します。機密情報を伏せていない Cookie やトークンが含まれる可能性があります。保存する前に秘密情報の境界を読んでください。

利用可能なブラウザーツールがボディを隠す、ナビゲーション時にイベントを失う、またはログイン済みセッションへのアクセス方法を複数公開している場合は、references/browser-capture.mdを読んでください。

完了条件： 対象の結果を説明できる可能性のあるリクエストを少なくとも 1 つキャプチャし、UI カナリアを少なくとも 1 つ保存していること。UI にカナリアが 2 つ表示される場合は、そのうち 1 つを忠実性確認用の保留項目として確保し、エンドポイントの選択には使用しないでください。カナリアが 1 つしかない場合は、その旨を記録してください。レンダリング済みページや DOM セレクターは、リクエストの証拠にはなりません。

3. UI の外部でリクエストを再実行する

推測したエンドポイントではなく、キャプチャしたリクエストを起点にします。curl、httpx、またはサイト固有のプロトコルを使って再現します。最初の再実行では、メソッド、エンコーディング、Cookie、ヘッダー、ボディを正確に保持してください。ブラウザーの Cookie ストアまたは認証済みリクエストコンテキストをプログラムから使用し、ユーザーに Cookie のコピーを求める前に、これらの方法をすべて試してください。

ユーザーに Cookie を求める前に、認証情報を取得する手順の優先順位についてreferences/browser-capture.mdを読んでください。

ステータス、バイト長、安定したキー、項目数、キャプチャしたカナリアを使って、キャプチャと再実行を比較します。ブラウザー限定のボット対策や署名付きリクエストによって単独の HTTP リクエストがブロックされる場合は、認証済みブラウザー内で fetch を使って再実行し、DOM 自動化で代用せず、その制約を記録します。

完了条件： 再現可能なコマンドで同じ対象データが返されること、またはリクエストの証拠によってブラウザーに依存する具体的な要件が実証されていること。

4. 最小化して対応付ける

重要でないヘッダーを一つずつ削除します。入力を一度に一つだけ変えて、次の項目を対応付けます。

• ID、公開情報、ワークスペース、アカウント、またはリソースの ID
• ページネーションまたはカーソル、並べ替え、フィルター、検索、上限
• リスト、詳細、ダウンロード、変更のエンドポイント
• REST、GraphQL の操作、永続化クエリ、RPC バッチ、またはストリーミングフレーム
• 認証の有効期間、CSRF との連動、更新動作

認証ありと認証なしのリプレイを比較します。公開リストへのリクエストが成功しても、リストが公開されていることしか証明されません。詳細全体、有料コンテンツ、非公開フィールド、変更操作については何も分かりません。

リクエストが GraphQL、フレームワーク RPC、Server Action、バッチ、またはストリームの場合は、references/protocols.md を読んでください。

完了条件： 判明している最小のリクエストが文書化され、ユーザーの操作に必要な各入力の取得元が分かっています。

5. 忠実性を検証する

サンプルを比較したり書き込みをテストしたりする前に、references/security-and-validation.md を読んでください。

直接取得したレスポンスを、ステップ 2 で保存した UI のカナリアと比較します。カナリアが 2 つある場合は、予備のホールドアウトを使用してください。この比較は、以降の UI 操作を行わずに実施します。レスポンスのフィールドを正確に報告します。詳細レスポンスで確認できるまでは、プレビュー、要約、検索スニペット、リストのペイロードを不完全なものとして扱ってください。ソースデータを保持し、欠落したテキストを再構成するのではなく、書式を整えてください。

書き込みでは、元に戻せるサンプルを 1 つ使い、レスポンスを調べてから、独立したエンドポイント経由で読み戻します。

完了条件： 2 つの制御されたサンプルで想定される結果が再現され、認証あり／なしの差が測定されています。書き込みの場合は、読み戻しによる検証も完了しています。

6. 長期利用できるクライアントを構築する

実証済みのリクエストを、次の要件を満たす形で実装します。

• ソースファイルではなく、環境変数またはブラウザーセッションからシークレットを取得する
• テスト済みの停止条件を備えたページネーション
• タイムアウト、上限付きリトライ、レート制限
• 生の ID とフィールドを保持する明示的な出力形式
• 低コストの認証チェックと、検証リファレンスに記載された失敗の分類
• 状態を変更する操作や一括操作に対するドライランまたは確認ゲート

キャプチャした成果物は、サニタイズするまでバージョン管理から除外します。リクエストを永続化する前、書き込みエンドポイントを扱う前、またはクライアントの完成を宣言する前に、references/security-and-validation.md を読んでください。

完了条件： クライアントが新しいプロセスから実行でき、シークレットが追跡対象ファイルやログに含まれず、ページネーションが正しく終了し、失敗時に再調査すべき箇所が特定されます。状態を変更する操作と一括操作には、ドライランまたは確認ゲートがあります。

7. サイト固有のスキルをパッケージ化する

assets/site-skill-template をコピーし、すべてのプレースホルダーを置き換えます。検証済みの操作、認証情報の取得方法、実行可能な例、証拠の日付、トラフィックの再キャプチャから始める修復手順を含めます。サイト固有の情報はそのサイトのスキルに記載し、このメタスキルは汎用のままにします。

完了条件： テンプレート内のすべてのプレースホルダーが置き換えられ、新しいエージェントが UI をクリックせずに読み取り専用の操作を 1 つ実行でき、サイトが変更された場合の再キャプチャ方法を正確に特定できます。

引き継ぎ

次の内容を報告します。

証拠	必須内容
キャプチャしたリクエスト	アクション、メソッド、マスキング済み URL、ステータス
リプレイ	コマンドまたはスクリプトのパスと一致するカナリア
認証	方式、プログラムからの取得元、測定した認証あり／なしの差
サーフェス	エンドポイントまたは操作、パラメーター、ページネーション
検証	2 つのサンプル。該当する場合は書き込みの読み戻し
成果物	クライアントのパス、サイトスキルのパス、シークレットのスキャン結果
制約	ボット対策、レート、アカウント、法的制約、またはブラウザー依存の制約

キャプチャ後に結果を discovered、直接リプレイと忠実性チェックの完了後に proven、パッケージ化したクライアントが新しいプロセスからの実行に成功した後にのみ durable と宣言します。