meticulous-simulate-and-diff

模拟会话并分析差异

本技能介绍如何运行单次模拟并解读结果。simulate 命令的完整选项说明，请参阅 meticulous-cli 技能中的 simulate 参考。

开始前，请运行 meticulous-cli-update 技能，确保 Meticulous CLI 和技能均为最新版本——如果本次对话中之前已经运行过，则跳过。

前提条件

• 要回放的 sessionId
• 一个 appUrl（本地开发服务器；也可以留空，以使用最初记录的 URL）
• 可选：baseReplayId——用于对比截图的先前回放 ID。若不提供，会保存截图，但不进行对比。

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

meticulous download test-run --testRunId=latest
# Then inspect ~/.meticulous/test-runs/<testRunId>/coverage.json
# or check the testCases[].replayId fields

步骤 1 — 运行模拟

使用基准回放（差异模式）

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

捕获完整的标准输出。重点关注以下内容：

# Per-screenshot diff outcomes (one line each):
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

# Final summary block:
=======
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 — 提取 head 回放 ID 并找到回放目录

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

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

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

最新创建的条目就是 head 回放的目录（目录名带有时间戳，例如 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 快照。这些文件已保存在磁盘上：

• Head 元数据：~/.meticulous/replays/<replayDir>/screenshots/<screenshotFilename>.metadata.json
• Base 元数据：~/.meticulous/replays/<baseReplayId>/screenshots/<screenshotFilename>.metadata.json

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

读取两个 .metadata.json 文件。相关字段如下：

• before.dom — 截图时页面的完整 HTML；对比这两个字符串，了解发生了哪些变化
• before.routeData.url — 截取该截图时所在的页面／路由

对比 HTML 时，重点关注标签的新增或移除、class 属性的变化，以及文本内容的变化。

每张截图对应的标准输出行还会报告 mismatchFraction（发生变化的像素占比）。如果存在像素差异，但 before.dom 字符串完全相同，则变化纯属视觉层面（例如颜色偏移），而非结构变化。

步骤 5 — 总结发现

此技能的主要输出是对视觉变化及其原因的高层次、易于理解的描述。使用上面收集的像素差异计数、路由 URL、变更的类名和 HTML 差异来回答：用户体验发生了什么变化，UI 的哪个部分导致了这种变化？

根据当前上下文选择合适的呈现形式（对话式回答、结构化报告、提供给调用工作流的输入等）。可参考以下有用信号：

• 受影响的路由
• 变更的 DOM 区域中出现了哪些 CSS 类（这些类通常可直接对应到组件）
• 变更是结构性的（DOM 添加或删除），还是纯视觉性的（像素位置发生变化，但 HTML 没有差异）
• 同一变更是否出现在多个截图中（表明共享组件发生了变化），还是只出现在一张截图中

记录到 stdout 的对比 URL 始终值得列出，方便他人快速直观地核查差异： https://app.meticulous.ai/.../simulations/<baseReplayId>/compare-to/<headReplayId>

备注

• 可直接打开 ~/.meticulous/replays/<replayDir>/diffs/<baseReplayId>/ 中的像素差异图进行目视检查。
• 如果省略 --baseReplayId，则无法分析差异。截图仍会保存在本地，之后可通过设置 --baseReplayId 为首次运行中的 head replay ID 再次运行，以便进行比较。
• 有关完整的迭代开发工作流（会话发现、逐步提交和最终云端运行），请参阅 meticulous-iterative-dev 技能。

步骤 6 — 向 Meticulous 反馈

最后，在总结发现后，向 Meticulous 团队提交一条简短反馈：模拟和差异是否有助于你验证变更、是否有令人困惑的地方，以及哪些信息能让任务更容易完成？

# CLI
meticulous agent submit-feedback --message="<one or two sentences>" --outcome=<helped|neutral|hindered> --skill=meticulous-simulate-and-diff

# MCP
submit_feedback(message="<one or two sentences>", outcome="<helped|neutral|hindered>", skill="meticulous-simulate-and-diff")