auto-pr
目標: 指向任意 GitHub 儲存庫並開啟 N 個可合併的 PR —— 而非 N 個 PR。 每一個 PR 解決一個真實的 Issue(或一個確實的改進),在本地通過儲存庫自身的測試閘門,並在送達維護者之前由第二個引擎簽核。
這是一個輕量的協調層,位於 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 的網址(每行一個,使用 --json 則為 JSON 陣列)。驗證失敗的嘗試會以 skipped 的方式報告至 stderr,並附帶原因——這些 PR 絕不會被開啟。M 個真正的 PR 勝過 N 個不穩定的 PR;部分成功是預期的行為,而非錯誤。
前置需求
ghCLI 需已針對目標儲存庫完成驗證(gh auth status回傳 session)。用於分支、複製、Issue 列表、重複搜尋及 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 個,則讓引擎自行發現真正的錯誤/改進來補足。每個候選項目都會與儲存庫中既有的 PR 進行重複檢查。 - 逐項處理(隔離的
auto-pr/<slug>分支):修復引擎編輯並提交;執行儲存庫自身的測試閘門(make check/pytest/npm test/cargo test/go test);另一個引擎審查差異。測試閘門失敗或被拒絕將回饋給修復引擎,最多進行--max-revise輪。仍然失敗 ⇒ 跳過該項目並附帶原因。成功 ⇒ 推入分支並執行gh pr create。
它強制執行的內部規則
- 採用 conventional-commit 風格標題;內文使用小寫。
- 產生的提交中不包含
Co-Authored-By/ AI 標記尾綴。 - 開啟前先去重——不產生已嘗試/被拒絕修復的第 N 次重複。
- 在開啟 PR 前,必須在本地通過儲存庫自身等同於 CI 的閘門。
- 每個 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(預設)—— claude 使用acceptEdits(自動接受檔案編輯,不允許任意指令執行),codex 使用--sandbox workspace-write(寫入操作限於複本內,不允許網路連線)。對於大多數修復來說已足夠,因為測試閘門是透過 vouch 自己的執行器執行,而非透過引擎。--autonomy full—— 將 claude 提升至bypassPermissions(引擎可在無權限提示下執行任意指令)。僅在修復確實需要執行指令時使用,且僅用於您足夠信任可以執行的儲存庫。這是一個明確、每次執行皆需操作者選擇的選項——絕非預設值。
審查始終為唯讀(claude 使用 plan / codex 使用 read-only)。
失敗語意
- 工作空間解析失敗 ⇒ 整個執行中止;沒有開啟任何內容。
- 沒有工作項目 ⇒ 乾淨地退出,顯示「nothing to do」。
- 單一項目失敗(無差異、測試閘門失敗、超過上限被拒絕、push/
gh錯誤)⇒ 該項目被跳過並附帶原因;批次繼續執行。 - 缺少引擎二進位檔案 ⇒ 快速失敗並指出缺少的二進位檔名。