pr-improver

PR 改进器

运行 /code-improver:improve，改进当前分支——这是一个动态工作流，会循环调用 PR 审查器和修复子 Agent，针对分支更改反复处理，直到审查报告中不存在严重或主要问题。循环、记录账本和保护措施都由工作流负责；此技能会根据分支差异确定范围并传达结果。

开始循环

用户提供了：$ARGUMENTS（如果为空，则从对话中获取基准分支和偏好）。

1. 确定分支及其更改范围

1. 仓库根目录：git rev-parse --show-toplevel。如果当前目录不在仓库中，则明确报错。
2. 基准分支：如果提供了参数，则使用该参数；否则使用仓库的默认分支（git symbolic-ref refs/remotes/origin/HEAD → 其短名称，若失败则回退到 main）。如果当前分支就是基准分支，则拒绝运行——没有可改进的差异。
3. 更改的文件：git diff --name-only <base>...HEAD。如果结果为空，则说明情况并停止。
4. 范围：扩大到更改文件所在的目录——按文件匹配的 glob 范围太窄（PR 修复通常会在更改代码旁添加测试）。将每个更改文件映射为仓库相对目录 glob <dir>/**（只有根目录中的文件发生更改时，才使用根目录下的 **），然后去重并移除被其他 glob 覆盖的 glob。

2. 确定循环脚本

循环是此插件中的动态工作流 workflows/improve.js。按路径启动：scriptPath 接受解析后的绝对路径，而 Workflow 工具的 name 会解析内置工作流和项目工作流，因此通过市场安装的插件可能无法响应 code-improver:improve。按顺序尝试，命中第一个即停止——主目录排在 . 之前，因此已安装的副本优先于此市场项目的检出副本：

1. Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"
2. Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js"（如果设置了该变量）
3. Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

请原样使用打印出的路径。其插件目录——即移除 /workflows/improve.js 后的路径——就是 pluginRoot。如果三种方式都没有返回结果，则尝试一次 {name: "code-improver:improve"}；如果仍不可用，则停止并说明无法定位循环。不要手动拼接路径，也不要自行设计循环。

3. 调用工作流

使用 Workflow 工具运行，{scriptPath: "<the path from step 2>", args: {...}}：

{
  "target": "<repo root>",
  "reviewer": {
    "kind": "skill",
    "name": "pr-review-toolkit:review-pr",
    "notes": "Review the working tree's changes against <base> as a pull request: correctness, tests, error handling, and the review dimensions the skill prescribes."
  },
  "scope": ["<derived-dir-glob>/**"],
  "pluginRoot": "<the plugin directory from step 2>",
  "maxRounds": 5
}

• reviewer — 上述默认设置要求使用 pr-review-toolkit 插件。当用户指定了其他 PR 审查者（技能或 Agent）时，使用该审查者，并相应设置 kind。
• 仅当用户要求设置不同的上限时，才使用 maxRounds。
• pluginRoot 用于帮助运行查找其指标收集器；只有当步骤 2 回退到工作流名称时，才省略该键——此时工作流会自行查找。
• finalize 的默认值适用于 PR：除非分支位于插件内，否则不升级版本；开启旁白剥离和文档检查。
• 仅在继续运行时（见下文）使用 decision。

循环的基线快照是循环开始时的工作树——其作用域保护机制会保护分支中尚未提交的工作；审查者审查的是 PR 自身的提交。

工作流在后台运行，无需看管：它会进行审查、修复、重新审查，在每轮修复后检查作用域，并且只有审查通过后才能完成。它不会提交；所有更改都会留在工作树中。

如果 Workflow 工具不可用或访问遭拒，请停止并说明原因。 不要在行内通过直接编辑来模拟这个循环——工作流包含变更记录、作用域保护和升级处理保障，行内模拟不具备这些保障。

如果结果是 halted: "reviewer-unavailable"，请转达此结果并停止。 当前会话未安装审查者；请告知用户提供该审查者的插件（默认设置需要 pr-review-toolkit），并在安装后重新运行。不要自行审查该分支。

循环运行期间，不要结束本轮回复。 Workflow 工具会立即返回一个任务 ID；结果稍后才会返回。在交互式会话中，完成通知会重新调用你——请等待通知。在非交互式运行中（脚本、CI、评测），不会有后续轮次：停止会导致循环在本轮中途被放弃，因此启动后请轮询任务（使用返回的任务 ID 调用 TaskOutput，或等待后重新检查），直到任务完成，然后转达结果。如果回复“循环正在运行，我稍后会报告”，就等于放弃了此次运行。

转达结果

工作流会返回结构化结果。请如实报告——不同结果之间的区别很重要：

• converged: true — 最后一步是审查，且没有严重或重大问题。报告使用的轮数、剩余的轻微问题数（open_minor_count）以及产物路径（ledger_path、metrics）。
• capped: true — 修复预算已用尽，且最终审查仍发现阻塞问题。请明确说明：已达上限，尚未收敛，并列出 open_blocking。不要将其描述为成功。
• escalation — 循环检测到无法收敛（问题反复出现、数量未减少，或修复导致问题转移）。请将升级处理消息和问题 ID 转达给用户：这需要设计决策，而不是继续增加轮数。
• halted — 某项保护机制已触发（作用域违规、新文件未登记、审查者已失效或不可用，或 finalize 检查通过后自身的编辑未能通过后续检查）。请转达 violations/new_untracked_files 中的路径、finalize_regressions 中的位置，以及备注。
• notes 始终会随结果返回——请一并告知用户；其中可能包含重要警告，例如“已初始化 git 仓库”。

升级处理后的继续运行

循环按设计会在升级处理时停止。用户决定后，使用相同参数启动一次新运行，并添加：

{ "decision": "<the user's ruling, verbatim>" }

新运行会重新加载磁盘上的变更记录，因此每个问题、驳回和判定都会保留——轮数会重新计数，但不会重新推导。

要停止正在运行的循环，请停止工作流任务（TaskStop）；磁盘上的变更记录会更新至最后一轮，重新运行时会从该处继续。

不适用场景

• 一次性审查：直接运行 PR-review 技能；循环的价值在于迭代
• 技能：使用 skill-improver 入口——它会配置合适的审查器
• 尚未推送的探索性工作：审查并修复循环会完善差异；在工作方向 尚未稳定时，手动迭代能提供更多控制