meticulous-review

要审查 Meticulous 测试运行，请按以下工作流程逐步操作，使用所述的 CLI 命令。

开始之前，运行 meticulous-cli-update 技能以确保 Meticulous CLI 是最新的——除非它已经在此对话中运行过，在这种情况下跳过它。

此工作流程中的每个 meticulous agent … 命令在托管的 Meticulous MCP 服务器 上都有对应的工具，命名为 get_…（例如 agent test-run-diffs → get_test_run_diffs）。每个工具返回与 CLI 命令的 --json 输出相同的数据。以下步骤使用 CLI 命令，并注明对应的 MCP 工具。

评估前端视觉变化

获取差异概览，然后逐一检查每个差异。默认情况下，摘要返回一个预选的代表性集合——每个独特的结构性 DOM 变化对应一个截图——因此每个返回的行都值得检查。行按优先级顺序返回（最具代表性/最重要的优先），因此请从上到下逐一处理。 对于每个差异，始终先查看截图图像（步骤 2）——差异图像是理解实际变化的最有信息量的方式。使用 DOM 差异（步骤 3）获取额外的结构细节，仅当差异出乎意料且无法通过 DOM 或图像解释时，才使用时间线（步骤 4）。

要得出 PR 良好的结论，必须检查并确认每个返回的差异——每个差异都被分类为预期或已解释（参见决策指南）。只有在没有未解释或非预期的变化时，PR 才安全地批准。最终报告应涵盖所有显著的视觉变化：每个变化都应有自己的解释。

步骤 1 -- 获取重放差异摘要

从本地检出运行，以从当前提交的 git HEAD 解析测试运行——这是在本地检出的拉取/合并请求上进行审查或监控时的常见情况。首先确保 HEAD 与 CI 运行的远程 HEAD 匹配（例如 git pull），否则您可能会审查到过时或缺失的运行：

meticulous agent test-run-diffs

MCP 工具：get_test_run_diffs。

所有非结果输出都发送到 stderr（stdout 仅携带差异表）；传递 --verbose 以查看已解析的提交和 testRunId。要显式定位一个运行，请传递以下之一：

• --testRunId <id> — 一个 20 个以上字符的字母数字字符串（例如 aB3xK9LmN7QrStUvWxYz12）。
• --commitSha <sha> — 使用该提交的最新测试运行。对于拉取/合并请求，解析其头部提交 SHA（例如通过托管平台的 CLI 或 API）并在此传递。

如果解析的运行仍在进行中，命令会阻塞直到完成，然后显示差异（等待是默认行为）；传递 --dontWaitForTestRunToComplete 以报告正在进行的运行并立即退出。如果未找到该提交的运行，则运行尚未触发——等待并重新运行，或询问用户。

输出格式： stdout 为 TSV，stderr 为元数据。

输出仅涵盖视觉差异——匹配的截图、已知的波动以及分歧下游的截图不包括在内。默认情况下，它进一步限制为选定的截图——每个独特的结构性 DOM 变化对应一个截图的代表性子集。行按优先级顺序返回（最具代表性/最重要的优先）——按此顺序检查它们。

stdout 列：

replayDiffId	screenshotName	index	outcome	mismatchFraction

index 是行的全局排名（上述优先级顺序）；使用 --orderByReplayDiffs 时，它改为按重放差异分组排名。

示例输出：

CqctwLpPC7	after-event-0	1	diff	0.00234
RRMGQft7PD	after-event-174	2	diff	0.01050
CLkCJ8WLrJ	after-event-8	4	diff	0.00100

每行代表一个在基础（之前）和头部（之后）重放之间比较的截图，并且是一个已确认的视觉差异——每行都有 outcome=diff。行按优先级顺序排列。

• outcome 始终是 diff——基础与头部之间的视觉像素差异。非差异截图（匹配、添加/删除的截图、分歧下游的截图）不在此摘要中；要查看某个截图，请将其 screenshotName 传递给 agent image-files / agent dom-diff（步骤 2-3），通过 agent timeline-diff 发现可用的名称。
• mismatchFraction（0-1，5 位小数）是像素不匹配分数——基础与头部截图之间不同像素的比例（0 = 相同，越高表示图像变化越大）。较大的 mismatchFraction 快速提示变化很大，但无论大小，始终检查差异图像，因为即使很小的分数也可能是有意义的变化。

stderr 显示：总数、唯一差异计数和时间分解。每个返回的行都必须在审查中说明——检查每个（步骤 2-3），并确认它是预期的或已解释的，然后才能得出 PR 良好的结论。

可选标志（以将输出扩大到默认选定子集之外）：

• --includeDomDiffIds — 添加一个 domDiffIds 列：一个分号分隔的有序差异 ID 列表，每个 ID 对应截图中的一个独立 DOM 变化。每个 ID 将结构相同的 DOM 变化分组到不同截图中（相同 ID = 相同结构变化）。示例：1;3 表示两个独立的 DOM 变化，ID 分别为 1 和 3。特殊值：none 表示未发现 DOM 变化（视觉差异纯粹是像素级别的，例如抗锯齿——检查截图图像以理解它）；error 表示尝试了 DOM 差异但失败（例如元数据不可用）。与 --includeAllDiffs 结合使用，以查看选定子集如何覆盖完整的一组唯一差异 ID。
• --includeAllDiffs — 返回所有差异，而不仅仅是选定的代表性子集。添加一个 isSelected 列（true/false），标记哪些行在选定子集中。
• --orderByReplayDiffs — 按重放差异分组排序行（每个会话的截图按流程阅读），而不是按全局优先级；index 然后在该分组内对行进行排名。输出仍然是扁平的行列表（每行一个截图），无论是 TSV 还是 --json——这仅改变排序和 index 值。

步骤 2 -- 获取截图图像

对于每个代表性截图：

meticulous agent image-files --replayDiffId <replayDiffId> --screenshotName <screenshotName>

这将截图图像下载到 ~/.meticulous/agent-images/ 并打印本地文件路径。

MCP 工具：get_image_urls 返回相同的结果和签名的图像 URL，获取 URL 以查看图像。

输出格式：

outcome:	<outcome>
before:	<path>              # 基础图像；当 outcome 为 missing-base 时省略
after:	<path>               # 头部图像；当 outcome 为 missing-head 时省略
diffImage:	<path>           # 仅当 outcome 为 diff 时存在

打开 before、after 和 diffImage 文件以视觉检查变化。diffImage 通常信息量最大——它精确高亮显示了哪些像素发生了变化。即使 DOM 差异清晰，也始终检查图像以了解变化的实际视觉影响。

替代方案：使用 image-urls 而不是 image-files 获取图像的 URL，而不是本地下载。

步骤 3 -- 检查 DOM 差异（用于结构细节）

meticulous agent dom-diff --replayDiffId <replayDiffId> --screenshotName <screenshotName>

MCP 工具：get_dom_diff。

可选：传递 --context <N|full> 以控制每个块周围的上下文行数（默认 3）。使用 --context 0 表示无上下文，或 --context full 表示包含完整文件上下文的单个统一差异。

输出格式： 统一差异（+/- 格式），前导缩进已去除。所有差异块由 [diff 0]、[diff 1] 等标题分隔。示例：

[diff 0]
 <span class="text-zinc-400">#7687</span>
-<span class="min-w-0 flex-1 truncate transition-colors">Use divergence-aware comparison</span>
+<span class="min-w-0 flex-1 truncate transition-colors" data-tooltip-id=":r1h:">Use divergence-aware comparison</span>
[diff 1]
 <span class="inline-flex items-center rounded-lg bg-zinc-800">Temporal Workflow</span></a>
+<a href="/projects/Foo/Bar/test-runs/abc123"><span class="inline-flex items-center rounded-lg bg-zinc-800">Original: abc123</span></a>

步骤 4 -- 获取重放时间线（可选，用于诊断意外差异）

如果差异出乎意料，并且图像/DOM 无法明确解释原因：

meticulous agent timeline-diff --replayDiffId <replayDiffId>

MCP 工具：get_timeline_diff。

输出格式： stdout 为 TSV。

stdout 列：

diff	timeMs	event	description

• diff 列： （相同）、-（移除）、+（添加）、!（更改）
• event 类型：user、screenshot、network、console、debug、urlChange、error、fatalError 等。
• description：事件的简洁单行摘要

查找异常，例如失败的网络请求、意外的重定向或可能解释视觉变化的时间相关差异。

决策指南

对于每个代表性截图，根据差异图像和 DOM 差异将视觉变化分类为预期或非预期：

• 预期：视觉变化是您正在处理的任务的期望结果。确认并继续。
• 非预期：变化不是任务的目标。这包括明显与您的代码无关的变化，以及——通常更重要的是——您的代码更改产生的意外副作用。变化可以被您的代码_解释_并不意味着它是_预期的_；如果任务不需要该视觉变化，它就是非预期的。

对于非预期变化：

1. 如果变化是您的代码的副作用，尝试修复它，使代码在不产生不需要的视觉变化的情况下达到预期结果，然后重新运行测试。
2. 使用时间线（步骤 4）检查失败的网络请求、重定向或其他可能解释与您的代码无关的差异的异常。
3. 如果您能自信地解释原因（例如，波动的时间戳、非确定性元素），请记录解释。
4. 如果您无法解释或修复，请向用户标记。

最终报告

在调查所有差异并尝试修复任何可修复的问题后，生成一份涵盖所有显著视觉变化的摘要。解释点的数量应至少与您检查的代表性差异数量相同——每个视觉变化都应有自己的解释。

1. 预期变化：对于每个作为任务期望结果的独特视觉变化，描述视觉上发生了什么变化（基于差异图像）以及为什么是预期的。
2. 非预期变化（如果有）：对于每个变化，包括：
   • 一个代表性的 replayDiffId / screenshotName
   • 视觉变化的样子（例如“添加了新徽章元素”、“标题中的布局偏移”）
   • 它是您的代码的副作用还是无关的，以及您对原因的最佳评估

只有当每个返回的差异都已被检查并说明——每个要么确认为预期，要么已解释——时，PR 才是良好的。如果任何差异仍然是非预期的或未解释的，PR 尚未良好：修复它，或向用户清晰地呈现。

向 Meticulous 报告反馈

作为最后一步，在提交最终报告后，向 Meticulous 团队提交一条简短的反馈：Meticulous 是否捕获了真正的问题，是否有任何令人困惑或误导的地方，以及哪些信息会使审查更容易？

meticulous agent submit-feedback --message="<一两句话>" --outcome=<helped|neutral|hindered> --testRunId=<id> --skill=meticulous-review

MCP 工具：submit_feedback。