review-anvil-improve-pr

review-anvil-improve-pr

review-anvil-pr 的高效搭档。review-anvil-pr 只读并发布审查评论，而此预设会实际修改代码：先在 PR 中发布公告，再以 commit_mode=per_fix 运行审查循环，在请求的轮次及任何自适应后续轮次中，将修复提交应用到本地分支，并推送结果以更新 PR，最后就地编辑起始评论，替换为综合报告（或失败摘要）——PR 时间线中只有一条评论，但有两个状态。

生成语言

对此预设应用 受 ASD-STE100 启发的语言规范。 内部步骤使用直接祈使句。PR 评论使用简短的主动陈述句。诊断内容直接呈现，不加标签；请求执行的工作放在 Suggestions: 下，每项单独列出一条可独立实施的修改。默认以动作动词开头描述必需的工作。将无需更改的限制写在正文中；对低优先级或细微问题使用建议句式；对确实尚未解决的选择提出问题。

此技能按顺序执行六个步骤：

1. scripts/pr-helper.sh verify-checkout [<locator>] — 解析定位符或自动检测，然后验证本地检出内容与 PR 的头部分支匹配，且工作区干净。记录 PR 的基分支、作者、标记 UUID 和报告路径。
2. scripts/pr-helper.sh post-start — 在 PR 中发布一条置顶的“开始处理”评论，并抄送原作者，说明即将进行的操作，以及稍后会编辑此评论以加入最终摘要。记录评论 ID（用于后续编辑）和开始时间戳。作者会收到 GitHub 通知。
3. 在分支与基分支的差异上运行 review-anvil 引擎，并设置 commit_mode=per_fix（不要使用 PR 定位符作为目标——引擎的“PR 目标与 per_fix 不兼容”规则禁止这种组合；此预设通过直接以本地分支为目标，刻意绕开该限制）。引擎会将最终综合报告写入 report_path，包括失败路径。
4. git push — 请求的轮次及任何自适应后续轮次完成（或提前收敛）后，仅推送一次；且只有在引擎报告没有失败，并且构建／测试门禁最终通过时，才将修复提交推送到 PR。
5. scripts/pr-helper.sh post-update — 通过 PATCH 编辑起始评论，将其正文替换为完整的最终报告（outcome=success）或失败摘要（outcome=failure）。GitHub 不会在编辑时发送通知，因此不会再次提醒作者——步骤 2 中原始的 cc @author 通知是唯一一次提醒。
6. 向用户展示最终报告和评论 URL。

输入

与 review-anvil-pr 相同的定位符格式，但你必须已切换到 PR 的分支：

• 省略 — 通过 gh pr view 自动检测；当你已检出 PR 分支时可用。
• 完整 GitHub URL — https://<host>/<owner>/<repo>/pull/<N>，适用于 github.com 或 GitHub Enterprise。
• Slug — <owner>/<repo>#<N>（默认主机为 github.com）。

如果当前检出内容与指定 PR 不匹配（分支错误、工作区有未提交更改、HEAD 分离或 SHA 不一致），辅助脚本会安全地中止。这可防止出现“我在 PR #42 的分支上，运行 improve”这种情况；否则，引擎可能会将修复提交到不相关的本地分支。

如何调用

0. 拒绝覆盖固定参数

此预设固定的参数：commit_mode、target、report_path、run_ordinal。必须通过机械方式强制执行——解析辅助脚本（步骤 1）后，运行：

bash <helper-path> check-pins review-anvil-improve-pr "commit_mode,target,report_path,run_ordinal" "$ARGUMENTS"

退出码非零表示某个固定参数被覆盖：原样显示错误并停止。

出于安全考虑，这些固定参数不可覆盖：commit_mode=per_fix 是此预设的核心（只读模式是 review-anvil-pr 的用途）；target=<base>...HEAD 与已验证的 PR 在机制上绑定；report_path 是引擎运行结束后摘要步骤需要读取的文件；run_ordinal 则将辅助脚本观察到的 PR 历史带入标识符生成过程。

1. 解析辅助脚本

辅助脚本相对于此 SKILL.md 位于 ../review-anvil-pr/scripts/pr-helper.sh——此预设会复用 review-anvil-pr 中的脚本，而不是重复创建。严格按照 review-anvil-pr SKILL.md 第 1 步（“解析辅助脚本”）进行解析：仅限宿主暴露的技能路径或用户级可信安装根目录，绝不可使用项目范围内／工作树本地的技能目录。如果无法解析出可信副本，则中止并报错：error: review-anvil-pr/scripts/pr-helper.sh not found in any trusted skill root; install via 'npx skills add mrshu/agent-skills --skill review-anvil-pr'（没错，依赖项是 review-anvil-pr，而不是 review-anvil-improve-pr 本身）。

2. 验证检出状态

bash <helper-path> verify-checkout "<locator>"   # explicit form
bash <helper-path> verify-checkout               # auto-detect from current branch

此脚本会运行 gh 预检（身份验证 + PR 可访问性），然后验证本地检出状态：当前分支与 PR 的头部分支匹配，HEAD 位于 PR 头部 SHA 之上或从其派生（允许有后续提交——未推送的本地提交会在最后推送），且工作树和索引均干净。脚本还会在本地获取 PR 的基分支，以便引擎使用差异目标。

成功时，脚本会在标准输出中打印以下 KEY=VALUE 行：

HOST=github.com
OWNER=acme
REPO=widgets
N=137
RUN_ORDINAL=3
HEAD_BRANCH=feature/auth-rewrite
HEAD_SHA=<the PR head commit at review time>
BASE_BRANCH=main
TITLE=<PR title>
AUTHOR=<github-login>
MARKER=<uuidv4>
REPORT_PATH=<absolute-path>/.review-anvil/final-report-<uuidv4>.md

如果定位信息是自动检测的，脚本还会在 KEY=VALUE 块之前向标准错误输出 auto-detected PR: <url>。如果 HEAD 超前于 PR 已发布的头部（存在未推送的本地提交），脚本会向标准错误输出一条 note:——请告知用户，让他们知道哪些内容会被推送。

捕获所有值，包括 RUN_ORDINAL。向用户回显：improving PR: $HOST/$OWNER/$REPO#$N — $TITLE ($HEAD_BRANCH → $BASE_BRANCH), author: @$AUTHOR。

退出码非零时，原样显示脚本的标准错误输出并停止。不要调度审查者。

然后获取 PR 完整的、包含状态的审查历史，供审查者提示词使用：

bash <helper-path> history "$HOST" "$OWNER" "$REPO" "$N"

捕获输出——一份逐项列出的开放／已解决／已过期／已报告／已抑制事项记录，或 None.——供步骤 4 使用。退出码非零时，中止：每次 PR 运行都必须处理此前已向作者展示的反馈。

辅助脚本会在此预检阶段解析 RUN_ORDINAL，早于步骤 3 发布开始评论。因此，当前尚未完成的开始评论不会被计为一次已完成的审查运行。

3. 发布“开始”评论

在开始任何审查工作之前：

bash <helper-path> post-start "$HOST" "$OWNER" "$REPO" "$N" "$MARKER" "$AUTHOR"

脚本会创建一条 PR 顶层评论，该评论：

• 嵌入标记 UUID（以便后续需要时查找）。
• 以 review-anvil-improve-pr started on this PR. cc @<author>. 开头。
• 说明即将进行的工作，并告知用户评论会在最终结果出来后编辑。
• 包含 Started: <ISO-8601 UTC> 时间戳。

然后脚本会通过标记查找评论（针对读后写入延迟重试一次），捕获评论 ID 和 URL，并打印以下 KEY=VALUE 行：

COMMENT_ID=12345678
COMMENT_URL=https://github.com/acme/widgets/pull/137#issuecomment-12345678
STARTED_AT=2026-06-07T10:00:00Z

捕获这三项。向用户回显：starting comment posted: $COMMENT_URL。PR 作者会收到一条来自 @-mention 的 GitHub 通知。

如果 post-start 在发布前失败（网络短暂中断、gh 身份验证问题），则中止——无需清理。另有一种不同的失败情况：脚本在发布后退出，此时标记查找无法恢复评论 ID（“posted starting comment but could not recover its ID”）。这种情况下，PR 上确实存在一条开始评论——中止此次运行，并按照下方的恢复流程手动编辑该评论。

4. 激活引擎

使用以下参数字符串激活 review-anvil 技能（额外的用户参数放在固定参数之后；如果用户未传入，引擎会应用自身默认值 rounds: 3 和按差异规模调整的 max_rounds 上限）：

commit_mode: per_fix, target: <BASE_BRANCH>...HEAD, report_path: <REPORT_PATH>, run_ordinal: <RUN_ORDINAL>, <extra-user-args>

<BASE_BRANCH>、<REPORT_PATH> 和 <RUN_ORDINAL> 来自步骤 2。使用 <BASE_BRANCH>...HEAD（三点差异）可准确定位与 PR 基础分支不同的提交。固定 report_path 可确保引擎将最终汇总报告写入文件，以便步骤 6（post-update）读取。

用户无法覆盖观测到的 run_ordinal 值。当 RUN_ORDINAL 是正整数时，引擎会在新的来源 ID 中包含相应的 RUN 段。值为 unavailable 时，引擎会生成不带 RUN 段的 ID；历史记录不完整时不得臆造运行编号。

将步骤 2 中记录的账本作为引擎审查者提示词块中的 PR REVIEW HISTORY 提供——由于目标是分支，引擎不会自行获取该内容。审查者必须根据当前 HEAD 重新验证已报告的未解决、已解决和仅摘要事项；已解决只是对话状态，并不能证明问题已修复。

注意：不要将 PR 定位符固定为 target——引擎的“PR-target / per_fix 不兼容”规则会强制设置 commit_mode=none，从而违背此预设的目的。直接以分支为目标才是预期的规避方式。

用户可以覆盖 rounds: 或 max_rounds:（默认值为引擎的 rounds: 3 和按差异规模调整的 max_rounds 上限——即 rounds 加 1–3 轮自适应轮次，且不超过 max(6, rounds)）。用户无法覆盖 run_ordinal、commit_mode、target 或 report_path；为确保安全，这些参数均已固定，步骤 0 中的段落拒绝规则也会阻止覆盖尝试。

引擎会运行多轮循环，期间逐步提交修复组，并在完成后将最终汇总报告写入 <REPORT_PATH>。引擎默认会执行复现流程，在不确定的重要发现被提交为修复之前予以确认；构建／测试门禁（verify_cmd，除非用户传入命令，否则自动检测）会在每轮修复后运行。报告中的 Reproduction 和 Verification 行共同构成 PR 作者信任推送提交所需的证据——如果引擎记录了 Verification: none detected，这一限制说明也会随已发布的报告一并出现在 PR 中。如果必要候选项复现失败，这些候选项会被延后处理，循环仍可能以其他已验证的修复完成。如果任何一轮失败（审查者全部失败、git 提交出错、撤销路径后构建／测试门禁变为失败），引擎会停止循环并报告失败——跳过推送（步骤 5），并在步骤 6 中调用 post-update，将 outcome=failure，以便用失败摘要替换起始评论，避免评论悬而未决。

5. 推送

仅当引擎报告运行成功后，才进行推送：所有请求的轮次和任何自适应续跑均已完成（或循环提前收敛——这也算成功）；轮次摘要中没有 git commit failed 或 all reviewers failed 错误；并且每一轮的 Verification 状态都属于 passed、failed → round reverted、pre-existing failures (no new)、none detected 或 skipped——也就是说，绝不能出现新引入的失败（这些正是引擎的轮次摘要状态）。待后续处理的复现候选项本身不会阻止推送；同时，这些候选项也不得产生修复提交或可执行的 PR 评论。

git push origin "$HEAD_BRANCH"

如果引擎运行不完整或失败，请勿推送。直接转到步骤 6，并设置 outcome=failure。<REPORT_PATH> 处的报告文件包含引擎的最终状态和失败详情；post-update 将使用该文件填充评论。

如果引擎运行成功，但 git push 失败（权限被拒绝、冲突等），修复提交会保留在本地，但尚未推送到 PR。仍需调用步骤 6，并设置 outcome=failure，以便评论反映实际状态。告知用户本地提交仍保留在 <HEAD_BRANCH>，可供其调查。

6. 使用最终摘要更新评论

无论第 4/5 步结果如何，都必须执行此步骤。只有当引擎和推送都顺利完成时，才传入 outcome=success：

bash <helper-path> post-update "$HOST" "$OWNER" "$REPO" "$N" "$COMMENT_ID" "$MARKER" "$REPORT_PATH" "$AUTHOR" "$OUTCOME" "$STARTED_AT"

如果结果为 success，辅助脚本会先刷新完整的既往反馈记录，再编辑评论。如果查询失败，或刷新后的历史记录导致精简报告中的发现项有所变化，它会将更新改为 outcome=failure 并说明原因；它绝不会发布未经筛选或内部已过时的成功报告，也会避免留下未完成的“正在开始”评论。成功编辑后，只有当产物的 head_sha（引擎提交最后一个已接受的修复提交后本地的 HEAD）与实时推送的 PR head 相符，且实时打开的根评论带有匹配的 review-anvil 终态标记时，才会处理 <REPORT_PATH>.resolutions.json 中的条目。已修复或已过时的发现项可以标记为已解决；已接受的作者说明还要求存在来自 PR 作者的实时回复。它绝不会解决由人工撰写、非 anvil 的讨论串。

improve 工作流无法发布 GitHub 行内评审评论。成功更新时，在既往反馈刷新通过后，辅助脚本会将所有已处理的行内正文添加到一个折叠的 Finding details 部分下。可见报告仍为无标题的一行，包含一或两句中性的检测说明；折叠的完整详情表和发现详情则保留完整诊断及所需工作。失败更新绝不会添加跳过或未通过该刷新步骤的行内正文。除此之外，辅助脚本会原样发布报告正文，不会缩短内容。如果 GitHub 拒绝异常大的负载，更新会明确失败，并保留报告产物；运行中的 Agent 应以更清晰的组织方式重写报告，同时保留相同的发现项、理由和可执行详情，然后重试更新。

$OUTCOME 为 success 或 failure。脚本会通过 PATCH 编辑由 $COMMENT_ID 指定的起始评论。成功更新只包含隐藏标记和精简报告，因此默认视图仍是一行无标题的中性检测说明，且 review-anvil 页脚仍位于末尾。完成状态、作者提及、开始和完成时间以及结果都保留在折叠的 Review context 中。失败更新可以在失败报告前保留一句可见的 review-anvil-improve-pr failed 说明；其交付元数据仍会折叠。

GitHub 不会在编辑评论时发送通知，因此不会再次提醒作者——第 3 步中原先的 cc @author 通知是唯一一次提醒。

若结果为 success，在调用 post-update 之前，读取 <REPORT_PATH>.followups.json（如果存在），并将其中的条目告知用户——脚本之后会删除该文件。脚本会清理五个临时报告产物（<REPORT_PATH>、.inline.json、.resolutions.json、.approval.json、.followups.json）；如果没有其他报告产物，还会移除其自身忽略的 .review-anvil/ 目录。如果交付成功但讨论串解决失败，则会保留 .resolutions.json；使用 bash <helper-path> resolve "$HOST" "$OWNER" "$REPO" "$N" "<resolutions-path>" 重试。保留的证明包位于由主机创建、位于工作树之外的独立私有目录中，不会被修改。

如果 post-update 本身失败（少见情况：gh 暂时出现问题，或运行过程中评论被手动删除），请告知错误，但不要撤销推送——修复提交已经在 PR 上，缺失的评论编辑可以补救。用户可以使用评论 ID 手动编辑起始评论。报告文件会保留在磁盘上，以便用于此目的（post-update 失败时会跳过清理）。

7. 汇报结果

直接展示引擎的最终报告。回显两行摘要：

• pushed N commits to $HOST/$OWNER/$REPO#$N ($HEAD_BRANCH)，其中 N 来自已推送的修复提交，或最终报告中合并后的 Changes made 列表。如果跳过了步骤 5（失败路径），则写 did not push (engine/run failure)。
• comment $COMMENT_URL updated with outcome=$OUTCOME（如果步骤 6 出错，则写 comment update failed: ...）。

示例

• “改进我当前所在的 PR。” — 用户当前检出的是 PR 分支；Agent 调用 verify-checkout，不提供定位参数；辅助程序会自动检测。
• “在 acme/widgets#137 上运行 5 轮。” — 用户传入标识并要求进行更多轮次；通过末尾的 rounds: 5 参数覆盖引擎默认值。
• “审查并改进这个 PR，重点关注生产环境安全。” — 用户要求采用非默认的关注重点；此要求会作为 focus: production blast-radius（或类似内容）传递给引擎。

限制

• 需要 gh、uuidgen、jq（真实的二进制程序——gh 内置的 --jq 使用 gojq，不算）以及 uv（首选；不可用时回退到 python3），用于处理 PR 反馈历史记录。verify-checkout 会预先检查这些依赖，因此缺少依赖时会在耗时的审查开始前失败。此辅助程序遵循与 review-anvil-pr 相同的环境开关（REVIEW_ANVIL_NO_APPROVE、旧名称为 REVIEW_ANVIL_SKIP_DISMISSED 的开关、REVIEW_ANVIL_DISMISSALS）。
• 会修改本地工作树并推送到 PR。 如果只想获取反馈而不应用修复，请使用 review-anvil-pr（只读并发表评论）。
• 用户必须已位于 PR 分支，且工作树干净。verify-checkout 步骤会强制执行此要求，并在失败时提供明确的恢复说明（例如 gh pr checkout <N>）。
• 你必须拥有该 PR 的推送权限。否则 git push 会报出普通的 git 错误；脚本不会预先检查推送权限。
• 支持 github.com 和 GitHub Enterprise，处理方式与 review-anvil-pr 相同。

恢复：悬空的“starting”评论

如果编排器崩溃（或 Agent 主机丢失上下文，或用户中断），且发生在步骤 3 和步骤 6 之间，PR 上会留下一个承诺会编辑、但最终没有编辑的“starting”评论。根据崩溃发生的位置，修复提交可能已经推送，也可能尚未推送。

这种情况很少见，但可以恢复。如果发现悬空的 starting 评论：

1. 在 PR 上找到评论 URL。评论正文以 `` 和 review-anvil-improve-pr started on this PR. 开头。数字评论 ID 位于 URL 末尾（...#issuecomment-<ID>）。
2. 使用 gh api 手动编辑评论：

   gh api repos/<owner>/<repo>/issues/comments/<COMMENT_ID> -X PATCH \
     -F body="review-anvil-improve-pr failed: orchestrator did not complete. No reliable summary available."
   

   或者使用 GitHub 网页界面中该评论的“Edit”菜单。

如果编排器仍在运行，且引擎已完成，只是步骤 6 因某种原因被跳过，报告仍保存在步骤 4 打印的路径中；你可以将报告原样粘贴到编辑内容中。

如果引擎从未运行（在步骤 3 和步骤 4 之间崩溃），就没有内容被推送；只需按照上述说明将评论编辑为“未完成”说明即可。

配套组件

依赖 review-anvil 引擎和 review-anvil-pr 预设（此技能会复用其 scripts/pr-helper.sh）。三者都包含在同一插件中，应一起安装（npx skills add mrshu/agent-skills --skill review-anvil --skill review-anvil-pr --skill review-anvil-improve-pr，或直接使用 --all）。