perfect-web-clone

完美网页克隆

像素级精准克隆就是这项技能。当前 Agent 是运行时框架。 pwc 是确定性的手和眼：它负责捕获、持久化、构建、渲染、回放和测量。它绝不会调用其他模型。你负责理解证据、编写代码并选择针对性的修复方案。

像“复刻 https://example.com”这样的一条自然语言请求，即授权执行完整的本地复现工作流。即使运行时框架会执行许多内部工具调用和修复迭代，也应将其视为一次用户操作。

当请求中包含可用的 URL 时，不要要求用户进行常规确认。 默认推断用户需要完整页面克隆。 跨阶段持续执行，不要仅为通报进度或征求一般实现方案而交还控制权。只有当缺失的信息会实质性改变范围、需要凭据或新的授权，或必须由用户解决外部阻碍时，才提出问题。

部署绝非默认操作。默认生成本地构建和审查 URL；只有用户明确要求时才部署。

由一个负责整个页面的 Agent 统一执行，以便在不同区块间保留全局视觉上下文。除非用户明确要求，否则不要委派任务。

不可妥协的执行约定

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；随着 Agent 推进，应读取、更新并重写该记录文件。

按顺序处理每个计划中的区段：

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 中更新尝试次数、测量变化和证据路径。

每个断点 × 状态最多尝试修复五次。如果一次重试未能改善指标，随后第二次尝试仍未改善同一指标，则提前停止。保留测量结果最佳的候选版本；不要让回归成为最终产物。

8. 诚实交接

只有在以下条件全部满足时，才设置 ready_for_user_review：

• 捕获完整性已通过；
• 所有规划的版块和关键锚点均实际存在；
• 所有必需的常见交互均能成功重放；
• 生产构建已通过；
• 指纹和必需的预算均已通过；
• 必需的视觉断点／状态关卡均已通过；且
• 每项声称的结果都有证据路径或工具输出。

否则，设置 failed_with_residuals，并列出每项遗留问题及其关卡、版块／状态、预期值、测量值、证据、尝试次数和停止原因。

返回本地审阅 URL、源项目路径、dist/ 路径、证据／报告路径、关卡摘要和遗留问题。请说“已准备好供您审阅”，不要说“已验收”或“像素级完美”。最终决定由用户的视觉和功能审阅作出。

工具映射

用途	pwc 命令
捕获	pwc extract <url>
规划	pwc plan <source_id>
单个版块的证据	pwc section <source_id> <name>
Shell	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）只是起点，并非面向客户端质量工作的默认路径。