核心概念

auto-maintainer 是一款自動化軟體庫維護工具，將大量重複性的倉庫維護工作交由人工智慧處理。當軟體庫一夜間湧入 147 個議題和 38 個 PR 時，這個工具能自動進行分類、程式審查、修復、合併和發行，讓維護者只在高風險或含糊不清的情況下才需介入。其核心特色是以純文字 Markdown 編寫規則，無需學習專有語言。

規則定義方式

使用者在 .github/repo-policy.md 檔案中用 Markdown 撰寫維護規則，不需任何 YAML 或 DSL 語法。規則涵蓋的範圍包括：

• 產品防護欄（如隱私優先、功能優先度）
• 風險分類（認證異動、資料庫遷移為高風險；文件更新、修正拼字為低風險）
• 決策規則（如何處理錯誤報告、功能請求、外部 PR）
• 軟體庫特定規則（特定模組的特殊處理方式）

設定過程中，npx auto-maintainer init 命令會分析現有程式庫自動生成初始規則檔，使用者可隨時編輯調整，改動會在下次執行時立即生效。

工作流程

auto-maintainer 透過四個 GitHub Actions 工作流程處理完整的軟體庫生命週期：

• 分類階段：讀取議題或 PR，進行分類、風險評估、重複檢查，並根據規則決定後續行動
• 實現階段：針對可處理的議題（低至中風險），自動撰寫修復程式、建立分支、開啟 PR，並根據審查回饋進行修訂
• 合併階段：當 PR 準備就緒（CI 通過、審查批准、標籤正確），自動合併，整合現有的分支保護規則，不繞過任何檢查
• 發行階段：根據標籤判斷版本號提升幅度，自動發行補丁版本和次版本，重大版本則需人工決策

何時請求協助

系統在下列情況會主動上報給維護者，標記為「awaiting-human」狀態：

• 涉及高風險變更
• 準備發行重大版本
• 議題或 PR 內容含糊，有多種有效詮釋
• 偵測到疑似提示詞注入、社交工程或規則繞過的可疑內容

成本與憑證

分類執行成本低廉（約 $0.01–0.05 美元），實現執行成本隨修復規模增加而提高。若使用者擁有 Claude Pro、Max 或 Team 訂閱，無需額外 API 費用；亦可帶入自己的 API 金鑰。

安全設計

系統採多層防護措施：

• 分類機器人只能讀取、標籤、留言，無法修改程式碼
• 實現機器人只在信任的觸發事件上運行（來自分類機器人或維護者的標籤事件），不接受原始使用者輸入
• 所有 Actions 固定於特定 commit SHA，避免上游標籤變更帶來的供應鏈風險
• 內建對抗性防禦機制，能偵測和上報提示詞注入與社交工程嘗試

使用者無須設定任何額外工作流程，auto-maintainer 會自動與現有 CI、測試、Lint 工具協作，確保所有檢查通過後再進行合併。