auto-pr
目标: 指向任意 GitHub 仓库,并打开 N 个可合并的 PR(而非 N 个普通 PR)。 每个 PR 解决一个实际问题(或一个真正发现的改进),在本地通过仓库自身的测试门控,并在到达维护者之前由第二个引擎签署。
这是一个构建在 vouch auto-pr CLI 之上的轻量级编排层。它与知识库是同辈工具:永远不会写入存储/提案/审计日志,审查门控保持不变。
调用方式
vouch auto-pr <repo-url> \
--workspace <dir> --count <N> \
--claude-effort <low|medium|high|max> \
--codex-effort <low|medium|high|max> \
[--issue-label good-first-issue] \
[--fork-owner <login>] \
[--max-revise 2] [--autonomy edit|full] \
[--dry-run] [--json]
<repo-url> 可以是 https://github.com/<owner>/<name>、
[email protected]:<owner>/<name>.git 或 <owner>/<name> 简写形式。
输出:实际打开的 PR 的 URL(每行一个,或使用 --json 时为一个 JSON 数组)。验证失败的尝试会在 stderr 上报告为已跳过并附带原因 — 这些 PR 永远不会被打开。M 个真正的 PR 胜过 N 个不可靠的 PR;部分成功是预期行为,而非错误。
前置条件
ghCLI 已针对目标仓库进行身份验证(gh auth status返回一个会话)。用于复刻/克隆、问题列表、去重搜索和 PR 创建。claude(Claude Code)和codex位于PATH中 — 两个引擎都会被使用;一个负责修复,另一个负责审查,每个 PR 轮流进行。vouchCLI 位于PATH中(pip install vouch-kb)。
如果 claude 或 codex 缺失,则停止并告知用户 — 交叉验证是核心要点;不要静默地回退到单个引擎。
工作原理(流水线)
- 解析工作区 — 如果
--workspace已经是一个克隆,则使用它;否则执行gh repo fork --clone(或当你具有推送权限时直接克隆)。同步默认分支。 - 检测或引导指南 — 扫描仓库中的
CONTRIBUTING.md、AGENTS.md、CLAUDE.md、.claude/skills/**/SKILL.md、.codex/、.github/PULL_REQUEST_TEMPLATE.md。如果存在任何这些文件,它们将作为修复者/审查者的上下文。如果不存在任何文件,则获取仓库已合并的 PR 并合成一个贡献SKILL.md,写入克隆的.claude/skills/目录(以及.codex/镜像),以便下次运行时重用。 - 获取 N 个工作项 — 首先打开未分配的 issue(可通过
--issue-label过滤);如果去重后少于 N 个,则让引擎发现真正的错误/改进来填补剩余数量。每个候选 will 都会根据仓库现有 PR 进行去重检查。 - 逐项处理(隔离的
auto-pr/<slug>分支):修复引擎编辑并提交;仓库自身的门控运行(make check/pytest/npm test/cargo test/go test);另一个引擎审查差异。门控失败或拒绝会反馈给修复引擎,最多进行--max-revise轮修正。仍然失败 ⇒ 跳过并附带原因。通过 ⇒ 推送到复刻分支并执行gh pr create。
执行的规则
- 使用约定式提交标题;正文使用小写。
- 生成的提交中不包含
Co-Authored-By/ AI 署名尾注。 - 打开前进行去重 — 不创建已尝试/已拒绝修复的第 N 个副本。
- 仓库自身的等效 CI 门控必须在 PR 打开前在本地通过。
- 每个 PR 包含一个逻辑更改;链接/关闭其解决的 issue。
努力级别
--claude-effort / --codex-effort 独立调整每个引擎:
| 级别 | claude 模型 | codex 推理 |
|---|---|---|
| low | haiku | low |
| medium | sonnet | medium |
| high | opus | high |
| max | opus | high(codex 上限) |
(claude 模型作为别名传递 — opus/sonnet/haiku — 因此工具追踪每个层级的最新模型。high 和 max 都选择 opus;codex 将推理努力上限设为 high。)
对于真实贡献使用 high;仅在不重要的探索性运行时降级到 low/medium。先使用 --dry-run 针对新仓库运行,以查看其会打开哪些 PR,然后再在真实运行上花费引擎资源。
自主性与安全性
修复引擎会无头驱动对不可信第三方仓库的克隆,因此默认行为是受限的:
--autonomy edit(默认)— claudeacceptEdits(自动接受文件编辑,不允许任意命令执行)和 codex--sandbox workspace-write(写入限制在克隆目录内,无网络访问)。适用于大多数修复,因为测试门控通过 vouch 自己的运行器运行,而非引擎。--autonomy full— 将 claude 提升至bypassPermissions(引擎可以运行任意命令,无需权限提示)。仅用于修复确实需要执行命令的仓库,且仅在你足够信任的仓库上使用。这是一个明确的、每次运行的运算符选择 — 永远不是默认值。
审查始终是只读的(claude plan / codex read-only)。
失败语义
- 工作区解析失败 ⇒ 整个运行中止;未打开任何内容。
- 没有工作项 ⇒ 以“无操作”状态干净退出。
- 单个项失败(无差异、门控失败、超过上限被拒绝、推送/
gh错误)⇒ 该项被跳过并附带原因;批次继续执行。 - 缺少引擎二进制文件 ⇒ 快速失败并指明缺失的二进制文件名称。