meticulous-simulate-and-diff

模拟会话并分析差异

本技能涵盖运行单个模拟并解释结果。关于 simulate 命令的完整选项参考，请参阅 meticulous-cli 技能的 simulate 参考。

开始前，运行 meticulous-cli-update 技能以确保 Meticulous CLI 是最新版本——除非本次对话中已运行过，则跳过。

前提条件

• 一个 sessionId 用于回放
• 一个 appUrl（本地开发服务器，或留空以使用原始记录的 URL）
• 可选：一个 baseReplayId——用于比较截图的先前回放 ID。如果没有，截图会保存但不进行比较。

如果没有 baseReplayId，可以从下载的测试运行中找到：

meticulous download test-run
# 然后检查 ~/.meticulous/test-runs/<testRunId>/coverage.json
# 或查看 testCases[].replayId 字段

步骤 1 — 运行模拟

带基准回放（差异模式）

meticulous simulate \
  --sessionId=<sessionId> \
  --appUrl=<url> \
  --baseReplayId=<baseReplayId> \
  --headless

捕获完整的标准输出。需要关注的关键信息：

# 每张截图的差异结果（每行一个）：
0.412% pixel mismatch for screenshot screenshot-1234.png (threshold is 0.100%) => FAIL!
0.000% pixel mismatch for screenshot screenshot-5678.png (threshold is 0.100%) => PASS

# 最终摘要块：
=======
View simulation at: https://app.meticulous.ai/projects/<org>/<project>/simulations/<headReplayId>
View comparison with base: https://app.meticulous.ai/projects/<org>/<project>/simulations/<baseReplayId>/compare-to/<headReplayId>
=======

如果没有 FAIL! 行： 会话与基准视觉一致——报告无回归，然后继续步骤 6。

如果存在失败，继续步骤 2–6 定位并分析差异，然后提交反馈。

不带基准回放（快速检查模式）

如果没有 baseReplayId，则省略。截图仍会保存在本地，可直接进行视觉检查：

meticulous simulate \
  --sessionId=<sessionId> \
  --appUrl=<url> \
  --headless

然后定位回放目录（步骤 2），打开 <replayDir>/screenshots/ 中的截图以验证 UI 是否正确。此模式下没有差异图像——检查纯属视觉。步骤 3–5 不适用；检查后仍需完成步骤 6。

步骤 2 — 提取头部回放 ID 并定位回放目录

从 View simulation at: URL 中提取 <headReplayId>（最后一个路径段）。

要找到本次运行创建的本地回放目录：

ls -lt ~/.meticulous/replays/ | head -5

最近创建的条目即为头部回放的目录（以时间戳命名，例如 2024-01-15T12-30-45.123Z-abc123/）。记下此路径——下文称为 <replayDir>。

步骤 3 — 识别哪些截图存在差异

ls ~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/

此处的每个 .png 文件对应检测到视觉差异的截图。像素差异图像用颜色高亮显示变化的像素。还有以 thumb_ 为前缀的缩略图版本。

注意文件名——它们与截图标识符匹配（例如 screenshot-after-event-42.png）。

步骤 4 — 分析每个差异截图的 HTML 差异

每张截图都有一个对应的元数据文件，包含截图前页面的完整 HTML 快照。这些文件已在磁盘上：

• 头部元数据： ~/.meticulous/replays/<replayDir>/screenshots/<screenshotFilename>.metadata.json
• 基准元数据： ~/.meticulous/replays/<baseReplayId>/screenshots/<screenshotFilename>.metadata.json

基准元数据在模拟下载基准回放时永久缓存，因此无需额外下载。

读取两个 .metadata.json 文件。相关字段包括：

• before.dom — 截图时页面的完整 HTML；对这两个字符串进行差异比较以了解变化
• before.routeData.url — 截图所在的页面/路由

在比较 HTML 时，重点关注标签的添加/删除、class 属性的变化以及文本内容的变化。

标准输出中每张截图的行还报告 mismatchFraction（像素变化比例）。如果存在像素差异但 before.dom 字符串相同，则变化纯粹是视觉上的（例如颜色变化），而非结构性的。

步骤 5 — 总结发现

本技能的关键输出是对视觉变化及其原因的高层次、人类可读的描述。使用上面收集的像素差异计数、路由 URL、变化的类名和 HTML 差异来回答：用户体验发生了什么变化，哪个 UI 部分负责？

以适合当前上下文的任何格式呈现（对话式回答、结构化报告、输入到调用工作流等）。可参考的有用信号：

• 哪些路由受到影响
• 哪些 CSS 类出现在变化的 DOM 区域中（这些通常直接映射到组件）
• 变化是结构性的（DOM 添加/删除）还是纯视觉的（像素变化但 HTML 无差异）
• 相同的变化是否出现在多个截图中（表明共享组件发生了变化）还是仅出现在一个截图中

标准输出中记录的比较 URL 总是值得展示，因为它允许人类快速直观地验证差异：
https://app.meticulous.ai/.../simulations/<baseReplayId>/compare-to/<headReplayId>

步骤 6 — 向 Meticulous 报告反馈

作为最后一步，在报告结果（无回归或总结发现）后，向 Meticulous 团队提交一条简短的反馈：模拟和差异是否帮助您验证了更改，是否有任何令人困惑的地方，以及哪些信息会使任务更容易？

meticulous agent submit-feedback --message="<一两句话>" --outcome=<helped|neutral|hindered> --skill=meticulous-simulate-and-diff

MCP 工具：submit_feedback。

注意事项

• ~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/ 中的像素差异图像可以直接打开进行视觉检查。
• 如果省略 --baseReplayId，则无法进行差异分析。截图仍会保存在本地，可以通过使用第一次运行的头部回放 ID 重新运行 --baseReplayId 来稍后进行比较。
• 有关完整的迭代开发工作流（会话发现、逐步提交和最终云端运行），请参阅 meticulous-iterative-dev 技能。