albertirgi/replica

replica 是做什么的？

重建用户指向的内容，然后证明它。capture 将参考转化为包含测量数据的蓝图。你根据蓝图进行构建。compare 在四个维度（布局、样式、像素、动效）上对你的构建打分，并告诉你哪个修复能带来最高分。当 compare 返回退出码 0 时才算完成，而不是当你觉得构建看起来对的时候。

本文件所在目录即为 <skill>。

规则

1. 测量，而非猜测。 所有尺寸、颜色、字体、间距、持续时间和缓动函数都必须取自 blueprint.md、blueprint.json 或报告。不要依赖你对同类网站通常样式的记忆。
2. 绝不钻评分空子。 不要嵌入参考的截图或视频帧，不要 iframe 或代理参考页面，不要直接粘贴其渲染后的 HTML，不要编辑 .replica/ 下的任何文件，也不要降低 --level 来通过测试。在用户的技术栈中构建真实的 UI。
3. 使用项目当前的技术栈。 先读取 package.json 和最近的已有组件。匹配项目已在使用的框架、样式方法和动效库。仅当参考需要项目无法实现的功能时才添加依赖。
4. 按报告顺序修复，每次少量修改。 报告顶部的问题常常是底部问题的根源：一次级联修复可以移动数十个元素。每批次修复后重新运行 compare。绝不要一次堆叠十个推测性的改动。
5. 尊重所有权。 参考中的字体、图片、图标和文案归其所有者所有。尽量使用用户自己的资源和文案。否则，请询问或使用相同尺寸的占位元素，并标记 data-replica="placeholder"：compare 仍会检查其盒模型，但不会将其计入像素评分。在最终消息中说明你复用了哪些参考资源。

0. 范围

在第一条消息中确定以下内容并说明：

• 目标：URL 或文件，以及具体部分：用于区域或组件的 CSS 选择器，或用于视频的时间范围。

• 目标位置：用户项目中的文件或路由，以及技术栈。

• 等级，它设定 compare 对你的要求：

  等级	用户说	通过条件（全部必须满足）
  structure	“布局/感觉一致但使用我们的品牌”、“像 X 但用我们的内容”	布局 ≥ 90，动效 ≥ 85
  faithful（默认）	“克隆这个”、“重新创建”、“让它看起来像”	布局 ≥ 95，样式 ≥ 95，像素 ≥ 85，动效 ≥ 90
  exact	“像素级完美”、“1:1”、“完全一致”	布局 ≥ 98，样式 ≥ 98，像素 ≥ 97，动效 ≥ 95

• 触发器：动效的触发方式（页面加载、悬停、点击、滚动进入视口、随滚动擦除）。这将作为 --action 参数。

根据请求和仓库情况尽可能推断。仅当两种解读会导致不同的工作内容时才提问。

1. 环境准备（每台机器只需一次）

npm install --prefix <skill>/scripts
node <skill>/scripts/replica.mjs doctor

如果 doctor 报告没有浏览器，则运行它打印的安装命令。如果已安装 Google Chrome，Replica 会将其作为备用浏览器。视频和 GIF 参考还需要将 ffmpeg 添加到 PATH。

2. 捕获参考

将所有内容保存在用户项目内的 .replica/<name>/ 目录下，并将 .replica/ 添加到 .gitignore。

node <skill>/scripts/replica.mjs capture <url|file.html|image|video> --out .replica/<name>/ref \
  --selector "<所需部分的CSS选择器>" --viewports 1440x900,390x844 --action load --motion 1500

• --selector：将捕获范围限定在你要克隆的部分。整个页面会产生庞大的蓝图。
• --viewports：你将交付的视口宽度。第一个为主视口；动效将在主视口中录制。
• --action 和 --motion <毫秒>：仅当存在要克隆的动效时使用。录制时长应足够覆盖所有动效；capture 会在末尾有动画仍在进行时打印提示。
• --hide "<CSS选择器>"：隐藏 Cookie 横幅、聊天控件和开发覆盖层。这同样适用于你构建的克隆。

针对图片、视频、需要登录的页面、iframe、Canvas 和暗色模式的更多用法请参考 references/sources.md。

然后完整阅读 ref/blueprint.md。使用图像查看器查看 ref/<viewport>/shot.png 和 ref/motion/filmstrip.png。蓝图语法在 references/blueprint.md 中有说明。图片和视频参考没有蓝图，因此基于截图和帧进行构建。

3. 构建

按以下顺序工作：令牌 → 布局骨架 → 排版 → 盒模型与油漆 → 媒体 → 响应式 → 动效。

• 令牌：将蓝图中的颜色、字号比例、圆角、阴影和 CSS 变量以其精确值放入项目的令牌系统（CSS 变量或 Tailwind 主题）。
• 布局：逐条复现 flex … / grid cols[…]、gap 和 pad 值，以及容器的宽度。
• 排版：精确匹配字体系列、字重、字号/行高和字间距。如果某种字体不可用或受版权保护，则使用最接近的可用字体，并将其记录为已知差异。
• 动效：当蓝图中包含“声明动画”时，精确复制其持续时间、延迟、缓动函数和关键帧。否则使用时间线的开始时间、持续时间和缓动，或其弹簧参数。
• 提供服务：将克隆部署到可访问的 URL 或 HTML 文件，使其渲染出相同的状态（开发服务器路由、Storybook 故事或静态文件）。如果其根元素需要使用与参考不同的选择器，请向 compare 传递 --selector。

针对不同技术栈（CSS、Tailwind、Framer Motion、GSAP）的说明请参考 references/building.md。

4. 比较、修复、重复

node <skill>/scripts/replica.mjs compare .replica/<name>/ref <克隆URL|文件> [--selector "<克隆根元素的CSS选择器>"]

它会创建 round-N/ 目录，内含 report.md、issues.json、score.json 和 sheets/。退出码 0 表示通过，1 表示还未通过，2 表示发生错误。

1. 阅读 round-N/report.md：查看评分表，然后找到下一个要修复的问题。每个问题都显示了修复它能获得多少分。
2. 查看 round-N/sheets/*.png：参考 | 你的版本 | 差异总览、放大的热点区域以及动效时间线。
3. 修复前 3–5 个问题，务必包括任何标记为**“可能原因”**的问题。然后再次运行 compare。

• 如果报告显示 ▼（分数下降了），在尝试其他操作之前先撤销你上一次的更改。
• 如果连续两轮评分提升不足 1 分，停止修补。重新阅读出问题区域的蓝图，并检查字体是否加载、比较的选择器、状态和视口是否正确。
• 如果经过 8 轮仍未通过，汇报遗留问题及其原因。

references/fixing.md 涵盖了每种发现结果的含义以及通常能解决该问题的更改。

5. 交付

最后以如下格式总结：

Replica · <目标> → <修改过的文件列表>
等级 <等级> · 第 <N> 轮 · 评分 <总分> — 通过 | 未通过
布局 <n> · 样式 <n> · 像素 <n> · 动效 <n>
已知差异：<逐条说明及其原因（受版权保护的字体、用户自己的文案等）>
已复用的参考资源：<列表，或“无”> · 占位符：<列表，或“无”>
证据：.replica/<name>/round-<N>/report.md 及 sheets/ 目录下的图片

如果未通过测试，应明确说明并列出剩余的顶层待修复问题。