Community寫作與編輯github.com

vouchdev/vouch

一個基於 Git、經審查閘門控管的 AI 代理人知識庫:代理人提出寫入請求,由您核准。每項主張皆附來源,每次變更都是儲存庫中的差異。支援 MCP + CLI。

vouch 是什麼?

auto-pr 技能將 `vouch auto-pr` CLI 封裝成 AI 代理人的指令,其核心目標是針對任意 GitHub 儲存庫產生「可合併」的 Pull Request,而非單純的 N 個 PR。代理人的工作流程包含:自動探索並合成貢獻規範(若無現有規範則從已合併的 PR 中學習)、從開放的 Issue 或自行發現的改進點中篩選工作項目、並以雙引擎交替驗證模式(一個代理人負責修復,另一個負責審查)確保每個 PR 在送出前均通過儲存庫原生的測試閘門。此技能目前支援 Claude Code 與 Codex 兩種引擎,並提供 `--claude-effort` 與 `--codex-effort` 參數以獨立調整各引擎的運算強度。其安全設計包含自動衝突與重複檢查、預設使用編輯權限(`edit`)而非完整執行權限(`full`)、以及在單一項目失敗時仍繼續處理其餘項目的部分成功行為,確保不會因部分錯誤而導致整個批次中斷。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add vouchdev/vouch

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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;部分成功是預期的行為,而非錯誤。

前置需求

  • gh CLI 需已針對目標儲存庫完成驗證(gh auth status 回傳 session)。用於分支、複製、Issue 列表、重複搜尋及 PR 建立。
  • claude(Claude Code)和 codex 需在 PATH 中——兩個引擎都會用到;一個負責修復,另一個負責審查,每個 PR 交替進行。
  • vouch CLI 需在 PATH 中(pip install vouch-kb)。

若 claude 或 codex 缺失,請停止並告知使用者——交叉驗證是核心重點;不要默默降級回單一引擎。

運作方式(管線)

  1. 解析工作空間 —— 若 --workspace 已經是複製的儲存庫,直接使用;否則執行 gh repo fork --clone(若您有推入權限則進行一般複製)。同步預設分支。
  2. 偵測或建立引導標記 —— 掃描儲存庫中是否存在 CONTRIBUTING.md、AGENTS.md、CLAUDE.md、.claude/skills/**/SKILL.md、.codex/、.github/PULL_REQUEST_TEMPLATE.md。若存在,則成為修復者/審查者的上下文。若不存在,則擷取儲存庫的已合併 PR 並合成一個貢獻 SKILL.md,寫入複本中的 .claude/skills/(以及 .codex/ 鏡像),以便下次執行時重複使用。
  3. 尋找 N 個工作項目 —— 優先尋找開放的未指派 Issue(可透過 --issue-label 篩選);若在去重後少於 N 個,則讓引擎自行發現真正的錯誤/改進來補足。每個候選項目都會與儲存庫中既有的 PR 進行重複檢查。
  4. 逐項處理(隔離的 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 推理強度
lowhaikulow
mediumsonnetmedium
highopushigh
maxopushigh (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 錯誤)⇒ 該項目被跳過並附帶原因;批次繼續執行。
  • 缺少引擎二進位檔案 ⇒ 快速失敗並指出缺少的二進位檔名。

相關技能