perfect-web-clone

Perfect Web Clone

ピクセル単位で忠実にクローンを作成するスキルです。現在のエージェントはハーネスのランタイムです。 pwc は決定論的な手と目として機能し、キャプチャ、保存、ビルド、レンダリング、再生、計測を行います。別のモデルを呼び出すことはありません。エビデンスを理解し、コードを作成し、対象を絞った修正を選択します。

「复刻 https://example.com」のような自然言語によるリクエストひとつで、ローカルでの再現ワークフロー全体が許可されます。ハーネスが内部で多数のツール呼び出しや修正の反復を行っても、ひとつのユーザー操作として扱ってください。

リクエストに使用可能な URL が含まれている場合、通常の確認を求めてはいけません。 ページ全体のクローンがデフォルトだと判断してください。 進捗を知らせるだけ、または通常の実装上の選択を尋ねるだけのために制御を戻さず、各フェーズを続けてください。不足している情報によってスコープが大きく変わる場合、認証情報または新たな権限が必要な場合、あるいはユーザーによる外部の問題解決が必要な場合に限り、質問してください。

デプロイは暗黙に行いません。デフォルトではローカルビルドとレビュー用 URL を作成し、ユーザーが明示的に依頼した場合に限りデプロイします。

ページ全体の視覚的な文脈を各セクションにわたって維持できるよう、ページ全体を担当するエージェントはひとつにしてください。ユーザーが明示的に依頼した場合を除き、作業を委任しないでください。

譲れない実行契約

1. キャプチャ、計画、作成、ビルド、検証、修正、引き継ぎを、ひとつの継続的なタスクとして実行してください。
2. ok または success フラグと、そのエラーのエビデンスをすべて確認してください。ツールの結果を捏造してはいけません。
3. 不変の生のエビデンスと正規化済みのエビデンスを別々に保持してください。キャプチャが不完全な場合は、計画を作成しないでください。
4. 計画した最上位セクションと、個別に必須とされた重要領域をすべて再現してください。ビューポートや、視覚的に目立つ部分だけで終わらせないでください。
5. カルーセル、メニュー、タブ、アコーディオン／詳細表示など、キャプチャ中に確認された一般的な操作要件をすべて実装し、再生してください。見た目が似ていても操作できないコントロールは不合格です。
6. ゲートは依存関係の順序に従って実行してください。後続のスコアで、先行する構造上または動作上の不合格を覆すことはできません。
7. エビデンスによって特定された、対象を絞った最小のコンポーネントを修正し、再ビルドして、影響を受けるすべてのゲートを再実行してください。
8. 赤信号のゲートを隠したり、黙って免除したり、平均して消したりしてはいけません。 重要領域の欠落を、総合的な視覚的類似度で補うことはできません。
9. ready_for_user_review または failed_with_residuals のいずれかに到達した場合に限り、終了してください。 結果を承認できるのはユーザーだけです。

新しい実行を開始する前、または実行を再開する前に、references/harness-contract.md を読んでください。ここでは進捗台帳、終了状態、エビデンスの用語、正確な停止ルールを定義しています。

pwc が見つからない場合は、計測済みコアをインストールしてください。

pip install "git+https://github.com/ericshang98/Perfect-Web-Clone.git"
playwright install chromium

すべての pwc コマンドは JSON を出力します。ok: false は停止して修正する必要があることを示します。

継続的なワークフロー

1. 解決と再開

• リクエストから対象 URL を抽出してください。URL がなく、現在のブラウザー／タスクのコンテキストからも特定できない場合は、ユーザーに尋ねてください。
• アクティブなサンドボックスに .pwc/run.json があるか確認してください。URL が一致し、ステータスが終端状態でなければ、再開して新たに開始しないでください。URL が異なる場合は、新しい実行を開始してください。
• 各フェーズの成功後、および失敗のたびに、現在のフェーズとエビデンスを記録してください。台帳は監査証跡であり、ツール出力の代わりではありません。

2. 信頼できるソースの証拠を取得する

pwc extract <url>

• ok: true と summary.capture_integrity.status == "passed" を必須とします。
• source_id を記録し、以降のすべてのコマンドで同じ値を使用します。
• capture_residuals と site_classification の上限を提示します。ページが WebGL、実行時のキャンバス描画、または忠実にキャプチャできないスクロール演出に依存している場合は、測定された上限の範囲内でのみ続行し、それを残存事項として記録します。
• エクストラクターの再試行回数を使い切ってもソースの整合性が赤のままの場合は、failed_with_residuals で停止します。推測したコンテンツや不完全なコンテンツを基に生成してはいけません。
• コード生成の前に、ソースディレクトリでキャプチャのインベントリ（スクリーンショット、ブレークポイント、検出されたインタラクション）をただちに確認し、ブレークポイント、状態、インタラクションに関する要件を明確にします。それらを .pwc/run.json に記録します。

3. ページ全体を計画する

pwc plan <source_id>

• 実際の #main の子要素を、順序どおりにセクションおよび修正単位として使用します。
• required_structure の各項目は、大きな親セクションの内側にネストされていても、必須のアンカーとして扱います。
• 作成に取りかかる前に、ページのジオメトリとソースのスクリーンショットを確認します。計画がキャプチャしたドキュメントの高さ全体を網羅し、生の証拠で確認できる目立つ領域を含んでいることを確認します。
• 計画したすべてのセクション ID を .pwc/run.json に記録します。

4. シェルを作成し、すべてのセクションを作成する

pwc assemble <source_id>

初回の呼び出しでは、セクションファイルが存在しないのが想定どおりです。Assembly は .pwc/run.json を初期化します。エージェントの進行に合わせて、その台帳を読み取り、更新し、書き戻してください。

計画した各セクションについて、順番に以下を行います。

1. pwc section <source_id> <section_name>
2. セクションの証拠に基づいて、クリーンでセマンティックな JSX とスコープを限定したローカルスタイルを作成します。
3. 名前空間付きのコンポーネントファイルのみを src/components/sections/<namespace>/ に書き込みます。
4. .pwc/run.json でセクションを完了としてマークします。

セクション間でページ全体のレイアウトトークンを維持します。キャプチャから得たローカライズ済みアセットを再利用します。ソースのフレームワーク由来のマークアップ、ソース固有のクラスの指紋、外部リンクされたメディア、または実際のコンテンツの代わりとなる画像スナップショットを含めてはいけません。実際のテキスト、画像、リンク、動画、コントロールを使用します。

以下の作成要件を適用します。

• スティッキー動作を保持し、スティッキー要素の祖先によるクリッピングを避けます。
• ソースのレイアウトジオメトリに基づいてフッターの列を再構築します。
• キャプチャしたレビューのデータを使ってレビューウィジェットを描画します。
• ローカライズ済みの動画要素を機能する状態で出力します。
• 誤って空の状態でキャプチャされたコンテンツをそのまま保持せず、復元可能な遅延読み込みコンテンツを表示します。
• 必須の構造領域ごとに data-pwc-critical="<anchor>" を付与します。
• すべてのセクションで、Assembly が所有する data-pwc-section ラッパーを維持します。

各インタラクションの契約について、以下を行います。

• 状態遷移と、表示を制御するサーフェスを実装します。
• コントロールに data-pwc-interaction="<contract id>" を付与します。
• 該当する場合は、制御されるサーフェスに data-pwc-controlled="<contract id>" を付与します。
• 次／前のカルーセル操作やメニュー／アコーディオンの開閉動作など、ソースと同様に繰り返し操作できるようにします。

解決されていないアセット、領域、または動作は、明示的な残存事項とします。

5. 忠実度を評価する前にビルドする

pwc assemble <source_id>
pwc build

• missing_section_files がないことを必須とします。
• success: true であり、dist/ が生成されていることを必須とします。
• 失敗した場合は、ビルド JSON を読み取り、該当コンポーネントを修正してから再ビルドします。

ビルドが壊れている場合や古い場合は、受け入れスコアリングを実行してはいけません。

6. ゲートの順序に沿って検証する

dist/ のローカルプレビューを起動し、ユーザー確認用にその URL を保持します。取得したブレークポイントと観測可能な状態で検証します。

次を実行します。

1. 抽出元とのソース整合性。
2. 重要な構造：計画したすべてのセクションと data-pwc-critical アンカーが存在すること。
3. プレビューで必須のインタラクションを再生する（カルーセル、メニュー、タブ、アコーディオン）。 見た目だけ似せたものは不合格です。
4. pwc fingerprints <dist_dir>
5. pwc weight <dist_dir>
6. クローンのスクリーンショットを撮影し、 pwc score --ref <source.png> --cand <clone.png> を実行します。 高さが異なる場合は、セクションごとの境界を指定して --sections を使用します。
7. 同じソースのベースラインがある場合は比較します。

全体の SSIM 値ひとつだけを合格判定に使用しないでください。構造、インタラクション、必須の各ブレークポイント／状態を、結果で個別に確認できるようにします。

7. 自動で修正する

必須ゲートが不合格で、まだ予算が残っている間は、次の手順に従います。

1. 最初に失敗したハードゲートを選び、その中で測定値が最も悪いセクションまたは状態を選びます。
2. セクションの境界、インタラクション ID、スクリーンショットの差分、診断出力を使い、証拠を担当コンポーネントに対応付けます。
3. 現在のコンポーネントと pwc section <source_id> <name> を確認します。
4. 証拠に基づいて、そのコンポーネントまたは共有トークンをひとつ修正します。証拠により誤りが全体に及ぶと確認できる場合は、共有トークンを修正します。
5. 再ビルドし、影響を受ける構造、動作、ビジュアルの各ゲートをすべて再実行します。
6. 試行内容、測定値の差分、証拠のパスを .pwc/run.json に記録します。

ブレークポイント × 状態ごとの修正は最大 5 回までです。同じ指標が改善しない再試行が 1 回あり、続く 2 回目の試行でも改善しない場合は、早めに中止します。測定結果が最良の候補を保持し、最終成果物に劣化を残さないでください。

8. 正確に引き継ぐ

次の条件を満たした場合にのみ、ready_for_user_review を設定します。

• キャプチャの整合性に合格している。
• 計画したすべてのセクションと重要なアンカーが実質的に存在する。
• 必須の一般的なインタラクションがすべて正常に再生される。
• 本番ビルドに合格している。
• フィンガープリントと必須の予算に合格している。
• 必須のビジュアルに関するブレークポイント／状態のゲートに合格している。
• 主張するすべての結果に、証拠のパスまたはツール出力がある。

それ以外の場合は failed_with_residuals を設定し、残存項目をすべて、ゲート、セクション／状態、期待値、測定値、証拠、試行回数、中止理由とともに列挙します。

ローカルの確認用 URL、ソースプロジェクトのパス、dist/ のパス、証拠／レポートのパス、ゲートの概要、残存項目を返します。「レビューの準備ができました」と伝え、「承認済み」や「ピクセルパーフェクト」とは言わないでください。ビジュアルと機能の最終判断はユーザーが行います。

ツール一覧

目的	pwc コマンド
キャプチャ	pwc extract <url>
計画	pwc plan <source_id>
1 セクション分の証拠	pwc section <source_id> <name>
シェル	pwc assemble <source_id>
ビルド	pwc build
フィンガープリント	pwc fingerprints <dist>
重量	pwc weight <dist>
ビジュアルスコア	pwc score --ref <png> --cand <png>

作成したコードは、アセンブル済みプロジェクトの src/components/sections/<namespace>/ に書き込まれます。プレビューは dist/ 上のローカルサーバーです。インタラクションの再生はそのプレビューで行います。見た目が似ていても、操作できないコントロールは不合格です。

決定論的なコード生成（html_to_jsx）は出発点であり、クライアント品質の作業におけるデフォルトの手段ではありません。