把网页、截图和录屏，转成可执行需求、可复用设计规范与可运行的还原项目。
项目网站 · 快速上手 · 案例库 · 架构与评测方案 · 执行与评测 · English
还原结果按案例与输入策略审阅；源码辅助展示不等于 clean-room 基准或完整 E2E 通过。
新增可选准备门禁、持久化分块规格、设计 token/区域框、状态与动效/声音 cue、灵活资产布局、匿名视觉比较及音频证据播放器。旧合同保持可读，运行端不新增依赖或服务。几何诊断与局部盲比不等于完整 E2E。
Interfaces · Asset layout · Upgrade scope · Acceptance
整体架构与模块复用说明四个优化项的接入、依赖与能力边界；统一工程检查提供可预览、可持久复核的本地校验入口。本地 ESM 接口可直接复用，目前没有独立发布的 SDK。
文档审阅入口同时保存 OpenBoard 实施流程与系统数据流图的 PNG/SVG、可编辑源数据和版本/哈希清单，便于离线沟通与后续迭代。
当前优先落地 Codex 开发评估闭环：显式绑定 run/主会话后，Restore CLI 与现有生命周期入口连接检查点、持久 Job、现有评估器、当前版本反馈和可选 Langfuse 交付。开发 E2E 与轨迹窗口可在 run 完成前评估；独立适配器/公开来源缺失时如实保留 unavailable，原生 hook 激活仍需单独验收。本版不包含 Claude 适配。
可选任务连续性将网站目标与单次 run 分开：持久断点、会话绑定、累计预算和 Stop/压缩/中断 hook 支持有界续跑；开发 E2E 的缺口可形成下一 run 的证据计划。Skill 改进只输出提案。项目 hook 须经宿主信任和真实回调验收；脚本通过不等于已自动运行，文件不会唤醒已停止的应用。
参考还原案例，展示从 v1 到 v28 的迭代效果。仅供学习，尊重源网站版权。
对标 Tiny Skies 原网站，用 生成 → 独立评估 → 差异修复 的循环推进 3D 网页游戏还原。88 秒横屏视频先对比原站与 v28，再展示版本变化、Agent 的观察/计划/修复，以及自动汇总的评测报告。
观看/下载中文横屏视频（88 秒，1080p） · English version · 展示媒体与校验信息
- 实现边界： 本案例为源码辅助还原（source-assisted），不是 clean-room 基准。前端样式与交互实现可参考公开代码；3D 场景和美术资产用代码重建，不镜像原站美术资产，未接入 3D 生成 MCP。
- 审阅方式： 视频尾帧展示最新独立评测摘要；本地完整报告用于审阅状态证据、核心迭代轨迹和未解决问题。展示片不是全流程测试录像，媒体 Release 不包含完整案例输出。
- 结果边界： 当前评测仍为
fail / provisional，存在交互差异与未验证的长链玩法，Judge 尚未校准。版本改善不等于完整 E2E 通过，也不是模型已完成 RL 训练的证明。
- 交付可继续开发： 从参考生成可运行、可修改的本地项目。
- 结果可对照： 记录参考状态、证据和已知缺口，帮助审阅还原差异。
- 迭代有记录： 保存版本和评测结果，方便回顾改动和未解决的问题。
在目标项目根目录运行对应命令。以下远程安装命令使用当前仓库根目录，尚未在干净环境验证；如果仓库为私有，账号需要访问权限。
Codex
npx --yes skills add https://github.com/PlevanTem/ui-reverse-engineer --skill ui-reverse-engineer --agent codex其他 Agent 的安装方式
Claude Code
npx --yes skills add https://github.com/PlevanTem/ui-reverse-engineer --skill ui-reverse-engineer --agent claude-codeGrok Build
npx --yes skills add https://github.com/PlevanTem/ui-reverse-engineer --skill ui-reverse-engineer --agent grokGemini CLI
npx --yes skills add https://github.com/PlevanTem/ui-reverse-engineer --skill ui-reverse-engineer --agent gemini-cliWorkBuddy
WorkBuddy 当前通过本地 Skill 包导入；vercel-labs/skills CLI 暂无 WorkBuddy 安装目标。在 WorkBuddy 选择「添加 Skill / 上传 Skill」→ 选择 ui-reverse-engineer 技能包。
上述
npx命令要求技能目录已提交到 GitHub 默认分支；如仓库为私有，账号还需有访问权限。若技能已在本地，先进入目标项目根目录运行npx --yes skills add <本地技能目录> --skill ui-reverse-engineer --agent <标识>，将<本地技能目录>替换为实际路径。
安装后直接用自然语言给任务和参考资料，例如：
把这张产品截图反推成需求 JSON，只做需求分析，不生成页面。
分析这个网站的视觉规范，生成可复用的 DESIGN.md。
参考这个截图的视觉风格，迁移到本地的 ./index.html，保留原有文案和交互。
还原这个网站，包括可取得的素材、响应式布局、滚动动效和主要交互；完成后给我可运行项目及对照结果。
也可以显式指定模式，如 --query、--design-md、--transfer、--restore；多个模式可组合。未指定时默认 --query --restore。
任务产物默认位于 reverse_output/{case_name}_{YYYYMMDD}/；Restore 的 restored/ 包含可运行项目，design_brief.md 记录范围和证据。
过程产物与清理约定见 输出目录规范；Restore 收尾检查见 执行流程，归档与临时文件只读清单见 接口说明。
关联运行的复盘与评分字段见 Restore 接口和 跨运行报告 Schema。
| 你的目标 | 交付结果 | 模式 |
|---|---|---|
| 还原参考页面 | 可运行项目、还原说明和对照结果 | --restore |
| 反推界面背后的产品需求 | 需求 JSON | --query |
| 提炼可复用的视觉规范 | DESIGN.md 和索引 |
--design-md |
| 将参考风格迁移到已有页面 | 保留内容和交互的页面 | --transfer |
可组合多个模式；未指定时默认 --query --restore。任务产物默认保存在 reverse_output/{case_name}_{YYYYMMDD}/，设计资产保存在 design_assets/。具体路径见 Skill 完整说明。
| 输入 | 能做什么 | 边界 |
|---|---|---|
| 网站 URL | 检查结构、布局、视觉状态、响应式和主要交互；主动检查页面公开加载的源码与运行时资源 | 需要可用浏览器/网页读取能力；跨域、登录或工具限制可能阻止部分源码核验，需记录缺口 |
| 截图 / Figma | 提取布局、颜色、字体、间距和组件风格 | 静态图看不到的交互需标为推断 |
| 视频 / 录屏 | 从关键帧整理操作顺序、状态变化和动效 | 需要客户端支持视频/视觉输入；快速变化的细节可能只能推测 |
| 源码 URL / HTML、CSS、JS | 从结构与实现推断信息架构、token 和状态逻辑 | 读到源码不等于核实了页面的实时外观 |
| 本地 HTML | 作为 --transfer 的迁移目标 |
--transfer 需要本地 HTML 目标 |
DESIGN.md |
作为 --transfer 的风格来源 |
使用文件内定义的设计 token |
普通网站 URL 即可启动技术栈分析的源码发现，不要求用户另提供代码托管链接；实际可检查范围取决于当前客户端的浏览器和网页读取能力。但 Restore 评测和 clean-room run 默认只使用冻结 fixture，不额外搜索公开资料或读取 case 源码证据；只有用户任务与冻结策略明确允许 source_assisted 时才可复用源码。安装 Skill 不会自动安装浏览器 MCP，也不会增加客户端原本没有的视频理解或本地文件访问能力。--transfer 会先给出迁移方案，确认后再改页面；--restore 会生成 brief 并直接完成还原，只有用户明确要求先审 brief 时才暂停。
Restore 支持汇总同一案例的多次运行；只有评测口径一致的结果才能直接比较。详见 Restore 接口。仅需本地采集脚本时，按以下说明配置浏览器。
浏览器采集环境
仓库自动采集脚本使用 Playwright 获取冻结截图、交互序列、运行时资源与控制台检查。默认 Python 入口为 scripts/restore/capture.py；宿主浏览器提供等价能力时也可用其取证。Node/Python 入口会在截图序列化期间冻结页面时钟，避免昂贵截图推进游戏或动画状态；该能力要求 requirements-dev.txt 固定的 Playwright/Chromium 或提供等价 Clock + CDP lifecycle 能力的宿主版本。需要本地脚本且尚无依赖时安装一次：
python -m pip install -r requirements-dev.txt
python -m playwright install chromium用下面的命令确认驱动和浏览器可启动：
python -c "from playwright.sync_api import sync_playwright; p=sync_playwright().start(); b=p.chromium.launch(headless=True); print(b.version); b.close(); p.stop()"scripts/restore/capture.mjs 是 Node 可选实现。只有需要运行该实现时才安装：
npm install --save-dev playwright
npx playwright install chromiumPlaywright 提供自动化浏览器，不能代替宿主提供的浏览器 MCP、视频理解或页面访问权限。遇到登录、反爬或网络限制时，继续记录可观察证据与失败原因，不把缺失状态标为已核实。
本地展示站包含首页、案例库、Tiny Skies 详情、快速上手和设计系统预览。 Firewood 的 fixture-only 本地还原尚未公开；最近一轮最终 E2E 为 incomplete；此前完整独立评测为 fail / provisional，案例页记录已知差异与未知项。先阅读 DESIGN.md 审计视觉与组件约定，再按 website/README.md 构建和预览。案例元数据由 evals/cases.yaml 生成，草稿状态与公开展示分开；网站由 GitHub Pages 工作流构建部署。Mosby’s Files 已在本地生成；落地页封面使用一张评测记录中的候选首页截图作预览。最新独立运行后评测为 fail / provisional，最终总分未计算、校准未测量；案例仍为 draft，完整报告与还原产物未发布。
首页 04 按能力与机制对比 Screenshot to Code、Open Lovable 与本项目；单元格附官方来源，未见说明不等于不支持，不作为同条件效果排名。
ui-reverse-engineer/
├── AGENTS.md # 项目级长期规则、维护约定与检查要求
├── SKILL.md # Agent 运行时入口与四种工作流
├── README.md # 中文使用说明与项目结构
├── README.en.md # 英文使用说明
├── CHANGE_LOG.md # 重要迭代、大量修改和推送记录
├── requirements-dev.txt # Restore Python 浏览器采集依赖
├── references/ # 按需加载的模板与详细指南
│ ├── design-md-template.md # DESIGN.md 设计资产模板
│ ├── transfer-guide.md # 风格迁移指南
│ ├── technology-stack-analysis.md # 网站技术栈分析 SOP
│ ├── restore.md # Restore 唯一执行 SOP
│ ├── restore-brief-template.md # 还原 brief 模板
│ └── restore/ # 精确接口、Schema 与局部视觉 Criteria
├── scripts/restore/ # v0.2 运行控制、采集适配器、报告和审批
├── assets/restore/ # v0.2 HTML 报告模板
└── evals/ # --restore 页面 E2E 还原质量评测
├── README.md # 评测目录、流程和自动化边界
├── cases.yaml # 11 个页面还原草稿案例；冻结素材后可用于评测
├── case-schema.json # Schema v1.2；区分 UI 类型和任务类型，难度保留三档
├── case-manager/ # 本地样本库；自动载入 cases.yaml，技术栈按高层模块拆分
├── restore.md # Restore 唯一最终 E2E 评测方案
├── templates/ # 跨 case 版本评测报告模板
├── fixtures/ # 授权、冻结的输入素材
├── pipeline/ # 独立五维 E2E grader
└── results/ # 按 run_id 保存结果摘要
当前评测入口、唯一方案和报告模板见 evals/README.md。案例输出与用户私人素材不作为仓库模板；只提交授权明确、去除个人信息且体量可控的 fixture。
Ctrl+S 保存的是浏览器当前加载的网页快照，具体包含哪些 HTML、资源和状态取决于浏览器的保存方式；动态数据、跨域资源和交互不一定能在离线环境正常工作。--restore 则根据参考页面的截图、状态、交互和资源证据，重新实现一个可运行、可修改的本地副本，并记录迭代与差异。前者适合存档，后者适合复现和继续开发。
Restore 模式里的 obligation（视觉义务）检查项是什么？
obligation 把“页面要还原得像”转化为可观察、可比较、可追溯的验收目标：明确参考页面的哪些表现必须还原，以及用什么证据判断修改是否改善了它。
例如，针对桌面首页，可以要求深色背景、居中大标题和四组彩色标签的相对位置与参考截图接近。这样评测者知道检查哪个画面和区域，实现者知道优先修复什么，也能在下一轮检查标题调整是否改善、是否破坏标签布局。证据不足时标记 unknown，不凭印象给分。
这属于测试预言机问题：先定义什么结果算对，以及用什么证据判断。
obligation 检查项在流程中如何触发？
- 生成前冻结： Restore 执行流程要求记录页面、视口、状态、关键区域、交互步骤和参考证据；obligation 写入本次运行的
contract.json。 - 定义判断标准： Loop Criteria要求每项指向状态和区域，写明预期表现、重要性、参考证据及判断方法，并归入 C1 构图、C2 外观或 C3 动态。
- 生成后测量与修复： 评测者记录 0–4 分，证据不足时标记
unknown；修复后再次对照，检查改善和其他必需项的退化。独立评测与实现者自查须明确区分；字段见 Restore 接口。 - 最后单独做 E2E： obligation 指导迭代；最终验收另按布局、样式、内容、交互、稳健性五维及红线评估，不能将局部分数直接换算为最终 E2E 分数。见 最终评测方案。
- 技能完整说明：模式、使用方式与输出。
- 网站技术栈分析 SOP：技术栈与资源取证。
- 技术栈审计脚本：本地采集与人工核验。
- Restore 执行流程：冻结、生成、迭代与停止。
- Loop Criteria：局部视觉评估与候选决策。
- Restore 接口：命令、采集、证据与报告。
- Restore 最终 E2E：最终验收、评分与红线。
- Firewood Langfuse 试点：真实控制事件导入、来源核验与轨迹/评分读回；缺失 Agent 轨迹不补造。
- Agent 轨迹与四维评估：主 Agent/子代理宿主记录、公开思考摘要、Skill 读取和工具反馈；Restore CLI 可选自动绑定、批量上报、外部 Codex Judge 与 Langfuse 原生评分回读。配置与恢复见接口，案例验收见 Firewood 协议。隐藏思维、缺失上下文和未校准指标不补造。
- v2 分步迭代：消息角色与去重、公开指令候选、事前委派规格、声明/证据配对和逐项 finding；新绑定使用 v2，旧批次保留，校准与数据覆盖分别报告。
- 交互场景还原：持续交互、3D 与动态场景。
- 还原 brief 模板：记录范围、实现与证据。
- DESIGN.md 资产模板：设计资产结构。
- 风格迁移指南：参考风格迁移。
中文 README 为默认入口；英文版见 README.en.md。