meticulous-zero-diff-task

要完成一项无差异（或低差异）实现任务，请按照以下工作流逐步操作，使用 CLI 或 MCP 命令，如下所述。

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

此技能适用于成功标准是视觉稳定而非视觉变化的任务：依赖项／版本升级、重构、迁移（例如更换框架／库、变更构建工具），以及类似工作。在这些任务中，任何 Meticulous 差异都意味着出现了问题，而不是可以解释为新功能。它也适用于低差异任务（预期会出现少量已充分了解的视觉变化，而其他输出基本不变）：流程相同，只是最终需要解释而非修复的差异更少。

步骤 1 -- 实现任务

按照任务描述进行代码更改（升级、重构或迁移）。如果任务自然地分为多个步骤，可以边做边提交——这并非 Meticulous 特有的要求，只需完成实现工作即可。

步骤 2 -- 构建前端

1. 查看 CI 配置中对应的步骤，了解 Meticulous 需要哪种构建产物：
   • GitHub：在 .github/workflows/*.yml 中查找 uses: alwaysmeticulous/report-diffs-action/upload-assets@v1（构建资源）或 upload-container@v1（Docker 镜像）
   • GitLab：在 .gitlab-ci.yml（或其包含的 .gitlab/ci/*.yml）中查找 npx @alwaysmeticulous/cli ci upload-assets（构建资源）或 ci upload-container（Docker 镜像）
   • Bitbucket：在 bitbucket-pipelines.yml 中查找相同的 npx @alwaysmeticulous/cli ci upload-assets／ci upload-container 步骤
2. 按照 CI 配置中使用的相同说明构建前端。

步骤 3 -- 上传构建产物并触发测试运行

# CLI
meticulous agent upload-build --appDirectory <path-to-build>     # assets
meticulous agent upload-build --localImageTag <image-tag>        # container
meticulous agent trigger-test-run --deploymentId <deploymentId>

# MCP (upload is not 1:1 — request an upload URL, upload the artifact yourself, then register it)
request_asset_upload(size=<zipByteSize>)      # or request_container_upload() — no required args
# ... upload the zip/image to the returned URL/registry yourself ...
register_asset_build(uploadId="<id>", commitSha="<sha>")      # or register_container_build(uploadId="<id>", commitSha="<sha>")
trigger_test_run(deploymentId="<deploymentId>", baseSha="<sha>")

MCP 上的 trigger_test_run 不会推断 baseSha／gitDiffOutput（请在本地计算基准），并且总是立即返回，不会等待运行完成（与默认会阻塞的 CLI 不同）。

在仓库目录中运行 trigger-test-run，自动推断基准（与 origin 默认分支的 merge-base）和 git diff。完整选项列表请参阅 meticulous-cli 参考文档——特别是，工作树可以处于脏状态（会被捕获为临时提交），因此无需在下面的每次迭代前提交。

记下输出中的 testRunId。

步骤 4 —— 检查差异并持续迭代，直到没有问题

使用 meticulous-review 技能中的方法检查差异（其中的步骤 1-4：agent test-run-diffs、截图图像、DOM 差异、时间线），但使用以下判定规则，而不是 meticulous-review 技能的预期变化与回归判定框架：

对于无差异任务，在证明有其他原因之前，都将返回的差异视为 Bug。 此技能的前提是 UI 不应发生变化，因此：

1. 完全没有差异 —— 此步骤已完成；继续执行步骤 5。
2. 存在一个或多个差异 —— 对每个差异，查看截图图像和 DOM 差异（参照 meticulous-review 技能的步骤 2-3），准确了解发生了什么变化以及原因；如果仅凭 DOM/图像无法看出原因，则使用时间线（该技能的步骤 4）。然后对差异进行分类：
   • 回归（默认假设） —— 由你的更改造成的真实副作用。
   • 可接受 —— 你能够明确说明，这是任务本身带来的有意且不可避免的结果（例如，版本升级导致页脚中的版本字符串发生变化）。在此要谨慎：对于低差异任务，可能确实会有少量此类差异；而对于严格的无差异任务，通常不应有此类差异。暂时不要为这些差异提交记录——等到步骤 6 再提交备注，将其关联到 PR 自身由 CI 触发的运行，而不是临时的本地迭代。
   • 与更改无关 —— 按照 meticulous-review 技能步骤 5 中“哪些情况算作无关”一节的定义，你的更改不可能导致该差异；通常包括渲染噪声、动画处于不同帧、字体或图像延迟加载，或服务器渲染时间戳等环境噪声。不能将无法解释的差异归入此类：如果你的更改有可能导致该差异，就应归入其他类别之一。
   • 无法修复，也无法有把握地说明理由 —— 不要陷入反复循环。

对于回归，立即拒绝，以便留下完整的处理记录——即使你在这里既是审查者又是实现者：

# CLI
meticulous agent reject-diff --replayDiffId=<id> --screenshotName=<name> --reason="<what broke>" --x=<0..1> --y=<0..1>

# MCP
reject_diff(replayDiffId="<id>", screenshotName="<name>", reason="<what broke>", x=<0..1>, y=<0..1>)

然后修复代码，使行为/输出与更改前的基线一致，再返回步骤 3 重新构建并运行（使用新构建，基线不变）。后续运行确认该差异不再出现后，在评论串中回复“Fixed”以完成处理——将 reject-diff 返回的 id 作为 --commentId 传入：

# CLI
meticulous agent reply-to-diff-comment --commentId=<id> --text="Fixed."

# MCP
reply_to_diff_comment(commentId="<id>", text="Fixed.")

无法修复且无法有把握地说明理由的差异，也要以相同方式拒绝，并说明阻碍修复的原因，让评论串如实反映情况；但不要将其标记为已解决（不要回复“Fixed”），并在最终报告和 PR 描述（步骤 5）中清楚、具体地指出该问题，以便人工判断。

重复执行步骤 3-4，直到没有剩余差异，或所有剩余差异都已说明理由或明确标记为未解决。

步骤 5 -- 创建 PR

运行检查全部通过（或所有剩余差异都有合理说明）后，提交所有未提交的更改，推送分支并创建 PR。

**作者署名：**在提交消息末尾添加 Meticulous 的共同作者标记，因为 Meticulous 推动了整个实现流程，而不只是做了最终检查：

<summary of the change>

Co-authored-by: Meticulous <87660985+alwaysmeticulous[bot]@users.noreply.github.com>

标记应放在消息的最后一段，与正文之间空一行，每行一个。如果消息中已有标记，例如 Co-authored-by: Claude <[email protected]>，请将此标记放在它们上方，确保 Meticulous 列为第一位共同作者。在 GitHub 上，使用上方显示的地址：它属于 Meticulous 的 GitHub App，因此 GitHub 会将 Meticulous 显示为共同作者。在 GitLab 上，改用 Co-authored-by: Meticulous <[email protected]>。在 Bitbucket 上，省略此标记：Bitbucket 不支持共同作者标记。使用 git remote get-url origin 检查当前托管平台。

在 PR 描述中概述任务，并简要总结 Meticulous 的结果（包括任何未通过的非视觉检查，以及 PR 自身运行报告结果后的步骤 6 中的 Agent swarm 结果）：例如，“已通过 Meticulous 验证：黄金测试集没有视觉差异”；如果仍有差异，则简要列出差异及其预期产生或无法避免的原因，并为每项差异添加链接：https://app.meticulous.ai/test-runs/<testRunId>/replay-diff/<replayDiffId>?screenshot=<screenshotName>。

步骤 6 -- 确认 PR 自身的测试运行结果一致

CI 为推送的提交触发 Meticulous 测试运行后，确认结果与您已在本地验证的结果相同——这样可以发现本地构建与 CI 构建之间的差异（例如依赖锁定文件不一致，或某个环境变量只在 CI 中设置）。

# CLI (resolves from local git HEAD — already the pushed commit)
meticulous agent test-run-diffs

# MCP (git context is never inferred — resolve the testRunId from the local HEAD commit first)
get_test_run_for_commit(commitSha="<sha>")
get_test_run_diffs(testRunId="<id>")

除了从 HEAD 解析外，您也可以使用 --testRunId <id>、--commitSha <sha> 或 --prNumber <n> 指定运行（在 MCP 上，可直接调用 get_test_run_diffs(prNumber=<n>)）。

如果 CI 尚未触发测试运行，请等待并重试，而不要自行重新触发——PR 的测试运行应来自人工审核者也会看到的同一 CI 流水线。如果 PR 运行显示的差异与您本地迭代时不同，请将其视为新的信号：使用 PR 的 testRunId 返回步骤 4。

对于此处仍然存在且您已说明理由而非修复的每项差异（步骤 4 的 可接受 类别），请留下纯审核评论，记录您的理由——CI 和人工审核者实际会看到这次运行：

# CLI
meticulous agent create-diff-comment --replayDiffId=<id> --screenshotName=<name> --text="<why it's justified>" --x=<0..1> --y=<0..1>

# MCP
create_diff_comment(replayDiffId="<id>", screenshotName="<name>", text="<why it's justified>", x=<0..1>, y=<0..1>)

仅对步骤 4 中无关的差异使用 ignore-diff——也就是与您的更改毫无关系的差异：

# CLI
meticulous agent ignore-diff --replayDiffId=<id> --screenshotName=<name> --reason="<why it's unrelated>" --x=<0..1> --y=<0..1> [--reportFlake]

# MCP
ignore_diff(replayDiffId="<id>", screenshotName="<name>", reason="<why it's unrelated>", x=<0..1>, y=<0..1>, reportFlake=<true|false>)

如果重放本身出现了非确定性，而 Meticulous 本应让它变成确定性（参见 meticulous-review 技能步骤 5 中的“报告可能的引擎错误”），请添加 --reportFlake，以便 Meticulous 将其作为可能的重放引擎错误进行调查。每次运行中，每个随机失败只报告一次：如果同一个随机失败出现在多个差异中，只需在其中一个差异上报告。

评论不会决定任何结果——差异仍为 unreviewed，检查仍处于待处理状态——但您的理由会留存下来，供审核 PR 的人员查看。

非视觉检查（仅当 PR 运行包含此类检查时）。 使用 meticulous agent test-run-check --availableIds 查看。如果因项目未设置检查而被拒绝，或未列出任何检查，则跳过此项。否则，按 meticulous-review 技能步骤 8 的说明处理每项失败的检查，但按步骤 4 的规则进行分类：对于无差异任务，除非证明并非如此，否则失败的检查属于回归。

• 回归：修复并返回步骤 3。如果无法修复，则使用 reject-check 并说明理由。
• 与您的更改无关：使用 ignore-check 并说明理由。
• 可接受：使用 approve-check 并说明理由。

approve-check 和 ignore-check 需要启用项目的 Enable approve/ignore check actions 设置。如果这些操作被拒绝，请让检查保持未决定状态。检查理由会被保存，但不会显示给 Meticulous 应用中的用户，因此还要在 PR 描述中列出每项失败的检查及您的判定和理由。

Agent swarm（仅当 PR 的提交有测试运行时）。 一些项目还会运行 Agent swarm，这是 Meticulous 托管的 Agent，可在浏览器中测试拉取请求的构建，并报告若干测试用例。请按 meticulous-review 技能步骤 9 的说明查看其运行结果：这些结果仅供参考，唯一例外是带有修复提示的 fail 用例。对于无差异任务，请将这类用例视为回归：按 meticulous-fix 技能步骤 4 的说明进行修复（先对照提示中引用的代码检查您的分支），然后返回步骤 3；除非其检查发现失败与您的更改无关（check.linkedToChange 为 "no"）。在 PR 描述中添加一行，总结运行结果（例如“4 个用例：3 个通过，1 个受阻”），并说明您未处理的任何修复提示及其原因。

步骤 7 -- 向 Meticulous 提交反馈

最后一步是向 Meticulous 团队提交一条简短反馈：这种任务的“迭代直至干净”循环是否顺利，有没有令人困惑之处，以及哪些改进可以让流程更轻松？

# CLI
meticulous agent submit-feedback --message="<one or two sentences>" --outcome=<helped|neutral|hindered> --testRunId=<id> --skill=meticulous-zero-diff-task

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