meticulous-fix

要修复已审核并拒绝的差异，请按照以下工作流逐步操作，使用 CLI 或 MCP 命令，如下所述。

开始之前，请运行 meticulous-cli-update 技能，确保 Meticulous CLI 和技能均为最新版本——除非本次对话中已运行过该技能，此时请跳过。

此技能假定审核已完成——用户（或 meticulous-review 技能）已检查此次运行，并拒绝了确实存在问题的差异；他们可能留下了评论，说明问题所在或需要采取的措施，但不一定会有评论。此处的任务范围小于完整审核：不要重新审议未被拒绝的差异，也不要质疑拒绝本身——只需弄清楚需要更改什么并落实。

步骤 1 —— 获取被拒绝的差异和带有评论的差异

# CLI
meticulous agent test-run-diffs --onlyRejected --onlyWithComments --includeReviews

# MCP (git context is never inferred — pass a commit or test run explicitly)
get_test_run_diffs(testRunId="<id>", onlyRejected=true, onlyWithComments=true, includeReviews=true)

不带参数时，CLI 会根据本地 git HEAD 确定运行记录；若要明确指定，请传入 --testRunId <id>、--commitSha <sha> 或 --prNumber <n>（MCP 也支持用 prNumber 代替 testRunId）。

重要提示——这些 --only* 标志是累加的（逻辑 OR）： 同时传入 --onlyRejected 和 --onlyWithComments 时，会返回所有被拒绝、有未关闭评论或两者兼有的差异——而非仅返回两者兼有的差异，因为针对未被正式拒绝的差异所留的评论也可能包含值得执行的指示。命令会隐含启用 --includeAllDiffs，因此会涵盖整次运行，而不只是选中的子集；--includeReviews 会添加 decision/openComments 列，以便区分每一行属于哪种情况。

并非每条带评论的记录都是修复目标。 meticulous-review 技能的 ignore-diff 会发布说明该差异与此次更改无关的备注，而 approve-diff 可能会发布解释批准原因的评论——这两种都不是修复指示。查看步骤 1 的记录时，请跳过仅有这些未关闭评论的差异；不要处理这些评论串。

被拒绝的检查（仅当此次运行包含检查时）。 运行记录也可能包含非视觉检查，例如 accessibility 或 network-requests。使用 meticulous agent test-run-check --availableIds 列出这些检查（MCP：get_test_run_check_available_ids）。如果因项目未配置检查而被拒绝，或未列出任何检查，则没有此类检查：跳过本段其余内容。否则，请阅读每项检查记录的原因：

# CLI (--prNumber=<n> can stand in for --testRunId)
meticulous agent check-comments --testRunId=<id> --checkId=<checkId> [--checkType=custom]

# MCP
get_check_comments(testRunId="<id>", checkId="<checkId>", checkType="builtin|custom")

未关闭评论以 Verdict: reject 开头的检查，表示已被 Agent 拒绝；评论其余部分会说明原因：该检查是修复目标，原因就是给你的指示。以 Verdict: approve 或 Verdict: ignore 开头的评论不属于此类。人员的拒绝不会在此记录原因，因此，如果用户告诉你某项检查被拒绝，也应将其视为修复目标，并根据其报告处理。对于每项修复目标检查，请使用 meticulous agent test-run-check --checkId=<checkId> [--checkType=custom]（MCP：get_test_run_check）获取报告，以查看具体发现。

Agent swarm 修复提示词（仅当该提交有运行记录时）。 有些项目也会运行 Agent swarm，这是 Meticulous 托管的 Agent，可在浏览器中测试拉取请求的构建，并报告少量测试用例。其结果仅供参考，但带有修复提示词的 fail 用例除外：这类失败已获检查器确认，并附有现成的修复提示词。这些用例应作为修复目标考虑。查找该提交对应的运行记录，并列出其中失败的用例：

# CLI (same run selector as above; waits up to 10 minutes for a run still in progress)
meticulous agent agent-swarm-run --status=fail

# MCP (a run still in progress returns { status: 'processing' }: poll every 10s, for at most 10 minutes)
get_agent_swarm_run(commitSha="<sha>", status="fail")

如果未找到该提交的 Agent swarm 运行记录，或者只有仅含计划的运行记录，或者没有失败用例，则跳过本段其余内容。如果运行在 10 分钟后仍未完成，请在最终报告中说明。否则，请使用上方打印的 swarmRunId 指定运行记录，获取每个失败用例的完整内容，并保留包含 fixPrompt 的用例：

# CLI
meticulous agent agent-swarm-run-case --swarmRunId=<id> --caseIndex=<n> --json

# MCP
get_agent_swarm_run_case(swarmRunId="<id>", caseIndex=<n>)

如果用例的 check.linkedToChange 为 "no"，说明检查器发现此次 PR 并未导致该失败，例如这是一个已存在的 bug：请报告该问题而不要修复，除非用户要求你修复。

第 2 步——阅读有评论的差异的审核意见

对于每个 openComments > 0 的差异：

# CLI
meticulous agent diff-comments --replayDiffId <replayDiffId> --screenshotName <screenshotName>

# MCP
get_diff_comments(replayDiffId="<replayDiffId>", screenshotName="<screenshotName>")

这是你的主要指引来源——评论通常会指出问题所在，而且往往会说明该怎么做。开始处理某个差异前，先阅读该差异的每条评论及其回复（按嵌套顺序从早到晚）；回复可能会缩小或改变较早评论提出的要求。

对于没有评论的已拒绝差异，这里没有内容可读——接下来要依赖的是视觉和结构上下文。

第 3 步——了解视觉和结构上下文

对每个差异，复用 meticulous-review 技能中的检查方法：

# CLI
meticulous agent image-files --replayDiffId <replayDiffId> --screenshotName <screenshotName>
meticulous agent dom-diff --replayDiffId <replayDiffId> --screenshotName <screenshotName>

# MCP
get_image_urls(replayDiffId="<replayDiffId>", screenshotName="<screenshotName>")
get_dom_diff(replayDiffId="<replayDiffId>", screenshotName="<screenshotName>")

有关输出格式，请参阅 meticulous-review 技能的第 2–3 步；如果仍不清楚原因，也可以使用时间线（agent timeline-diff）。

**没有评论的已拒绝差异的后备方案：**此时，上下文就是你的主要指引来源，而非额外背景——请像遵循 meticulous-review 技能的 Decision guide 一样对待它，并自行判断拒绝所指向的回归问题。

第 4 步——修复底层代码

对于每个修复目标——被拒绝的差异，或评论要求具体修复的未被拒绝差异——修改代码，以解决评论中的要求（如果没有评论，则修复你识别出的回归问题）。跳过第 1 步中仅要求忽略的讨论串；不要为它们修改代码，也不要回复。一次代码修改可能同时解决多个修复目标差异（例如，一个组件缺陷导致多个截图差异）——不要重复修复同一个根本原因。

对每个修复目标差异，无论是否修复，都要通过回复其评论讨论串（若没有则创建一个）来完成闭环：

# CLI
meticulous agent reply-to-diff-comment --commentId=<id> --text="<message>"
meticulous agent create-diff-comment --replayDiffId=<id> --screenshotName=<name> --text="<message>" --x=<0..1> --y=<0..1>

# MCP
reply_to_diff_comment(commentId="<id>", text="<message>")
create_diff_comment(replayDiffId="<id>", screenshotName="<name>", text="<message>", x=<0..1>, y=<0..1>)

如果该差异已有评论讨论串，请使用 reply-to-diff-comment——传入第 2 步中讨论串的根 id（即 replyToCommentId 为空的行），而不是某条回复的 id。只有当差异被拒绝且没有现有评论时，才使用 create-diff-comment（即没有评论的后备方案），因为此时没有可回复的讨论串。

• 已修复——回复/评论“Fixed。”
• 无法修复（评论要求的内容实际上无法实现——与其他要求矛盾、描述了不存在的行为、引用了你找不到的内容等）——不要猜测；请说明原因，让审核者无需再次询问就能了解情况。

无论哪种情况，都要继续处理下一个修复目标差异；最后在报告中列出（见下文的最终报告）。

第 1 步中的检查修复目标也按同样方式修复，依据拒绝原因和报告中的发现进行处理。它们没有可回复的评论讨论串：Meticulous 应用不会向用户显示检查原因。因此，请在最终报告和 PR 评论（第 6 步）中记录对每项检查所做的处理，无论是否修复，并说明原因。

如果是带有修复提示的 Agent swarm 案例，请从 fixPrompt 开始（这是案例输出中的一个字段；CLI 的 agent-swarm-run-case --fixPrompt 只会打印该字段）。它只是起点，并非经过验证的补丁：检查器读取的是运行所测试的提交，因此请先对照你的分支检查它引用的每个文件和每一行，并修复根本原因，而不是 Agent 遇到的问题表象。与检查一样，案例没有评论讨论串，因此请在最终报告和 PR 评论中记录对每个案例所做的处理。

第 5 步 —— 提交、推送，并让 CI 确认

1. 提交修复。在提交信息中说明这次修复是针对 Meticulous 审查反馈的，描述要足够具体，以便日后仅查看 git log 就能了解情况：

   Fix layout shift in checkout header
   
   Addresses Meticulous review feedback on test run <testRunId>:
   - <replayDiffId>/<screenshotName>: <brief on what was wrong and the fix>
   - Agent swarm case "<title>": <brief on what was wrong and the fix>
   
   Co-authored-by: Meticulous <87660985+alwaysmeticulous[bot]@users.noreply.github.com>
   

   作者署名： 在提交信息末尾添加上方所示的 Co-authored-by: Meticulous 署名行，因为这次修复是由 Meticulous 的审查反馈推动的。署名行应放在提交信息的最后一段，中间空一行，每行一条。如果信息中已有署名行，例如 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 检查你所使用的托管平台。

2. 推送分支（git push origin <branch>——请参阅你的 git 推送规则）。

3. 等待 CI 为推送的提交触发新的 Meticulous 测试运行，然后确认先前标记的差异确实已解决：

   # CLI (resolves from local git HEAD — already the pushed commit)
   meticulous agent test-run-for-commit
   meticulous agent test-run-diffs --onlyRejected --onlyWithComments --includeReviews
   
   # 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>", onlyRejected=true, onlyWithComments=true, includeReviews=true)
   

如果你认为已修复的差异仍然出现（决策/评论会从对比的运行中延续），说明你的修复没有解决根本原因；针对该项返回第 3/4 步，然后重复本步骤。

请检查审查结果是否会延续：新运行中的检查初始状态均为未判定。若要确认某项检查已修复，请获取新运行中该检查的报告（meticulous agent test-run-check --checkId=<checkId> [--checkType=custom]），并确认已修复的问题不再出现。

如果项目会在每次提交时运行 Agent swarm，那么推送提交对应的运行（meticulous agent agent-swarm-run，如第 1 步所示）会显示你修复的案例现在是否通过；请按标题匹配，因为其 caseIndex 可能会变化。如果再次失败并给出新的修复提示，请针对该项返回第 4 步。

第 6 步 —— 最终报告

总结结果，涵盖第 1 步中的每个修复目标差异、检查和 Agent swarm 修复提示（省略你跳过的仅忽略项）。为提及的每项差异添加链接：https://app.meticulous.ai/test-runs/<testRunId>/replay-diff/<replayDiffId>?screenshot=<screenshotName>，并在有 Agent swarm 结果时添加链接：https://app.meticulous.ai/test-runs/<testRunId>?tab=agent-swarm。

1. 已修复：说明解决了哪些差异、检查和案例，底层代码做了哪些更改，以及修复针对的评论、拒绝原因或修复提示（如有）。
2. 未修复（如有）：说明哪些差异、检查或案例无法处理，以及原因——例如，评论中的要求无法实现、含义模糊，或与其他内容冲突。对于差异，请注明你已在该差异下以回复/评论的形式留下说明（第 4 步）；不要只把说明写在只有本次对话能看到的报告里。对于检查或 Agent swarm 案例，报告和 PR 评论是其他人能看到的唯一记录。请提供足够具体的信息，让人工审查者无需重新推导你已查明的情况，也能继续跟进。

除了在此处提交报告，还要将其作为评论发布到 PR 本身（例如，在 GitHub 上使用 gh pr comment <number> --body "..."，在 GitLab 上使用 glab mr note <id> --message "..."；在 Bitbucket 上，如果 Teamwork Graph CLI 可用，可使用 twg bitbucket pull-requests comment create --pull-request <id> --text "..."——如果已安装，请遵循其 twg-engineering-work 技能；如果提示输入 Bitbucket 令牌，请运行一次 twg setup bitbucket——否则，调用 POST /2.0/repositories/{workspace}/{repo_slug}/pullrequests/{id}/comments，并使用请求体 {"content": {"raw": "..."}}）。

第 7 步 —— 向 Meticulous 反馈

最后一步，向 Meticulous 团队提交一条简短的反馈：拒绝意见/评论是否提供了足够的信息供你处理，是否有含糊之处，以及怎样的交接能让工作更顺利？

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

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