廣告位招商中 歡迎洽談
繁體中文
English简体中文繁體中文日本語EspañolPortuguês한국어DeutschFrançais
所有網站

軟體工程團隊如何設定 Sweep 將 GitHub Issue 描述轉化為自動化 Bug 修復 PR

觀察
365Finds Editorial
已收錄 11,430 篇 Wiki 文章

讓你的 AI 用上 365 Wiki

複製下方的提示詞，貼給你常用的 AI，然後直接提問。

下載完整版 Skill

先用提示詞體驗；經常使用時，安裝完整版 365Wiki Skill，以後無需重複複製。沒有常用 AI？Gemini、Microsoft Copilot 等網頁版也可以。

365Wiki Skill

下載完整版 Skill
在現代軟體研發流程中，處理積壓的日常缺陷與瑣碎維護往往會分散資深工程師的大量精力。空指標防禦、廢棄函式庫替換、邊界條件修復、補齊缺失單元測試等低風險但高頻繁出現的 Bug，經常在 Backlog 中擱置數週。


Sweep 正是為了解決這個瓶頸而設計的自主型 AI 初階工程師（AI Junior Developer）。作為 GitHub App 接入儲存庫後，Sweep 能即時監聽 Issue 動態，透過語意檢索與抽象語法樹（AST）解析程式碼上下文，自主編寫跨檔案補丁，並主動發起標準 Pull Request（PR）。更關鍵的是，它能與 CI/CD 測試流程深度整合，讀取失敗紀錄自動修復，並對工程師的程式碼審查（Code Review）意見進行即時迭代。


本文詳細說明研發團隊如何配置與導入 Sweep，包括核心運作流程、授權設定、sweep.yaml 生產環境設定、高品質 Issue 提示詞撰寫原則、CI 閉環自癒以及工程防護機制。




1. Sweep Issue 轉化 PR 的核心流程


在導入設定前，團隊需掌握 Sweep 處理任務的生命週期：


    

  1. 觸發事件：工程師建立帶有 Sweep: 前綴的 GitHub Issue（例如 Sweep: Fix KeyError when user metadata payload is missing）、為既有 Issue 加上 sweep 標籤，或在留言中提及 @sweepai。
    2. 

  2. 儲存庫語意檢索：Sweep 的 Webhook 入口函式（on_ticket）啟動，結合程式碼向量嵌入（Vector Embeddings）與 AST 程式碼分塊技術，快速定位與 Issue 關聯的目標檔案、函式定義與測試用例。
    3. 

  3. 制定執行方案：Sweep 會在 Issue 留言中發表執行計畫，列出預計修改的檔案清單與技術思路。
    4. 

  4. 產生程式碼與分支：Sweep 自動建立專屬分支（如 sweep/fix-...），依據專案規範完成修改並推送到遠端儲存庫。
    5. 

  5. 發起 Pull Request：Sweep 建立正式 PR，內容包含修復的 Issue 關聯（如 Fixes #<id>）、技術變更摘要與查核清單。
    6. 

  6. 雙向回饋閉環：

      

    • CI 自我修復循環：開啟 GitHub Actions 整合後，若測試失敗，Sweep 會自動讀取 CI 錯誤堆疊日誌並追加提交，直到測試通過。
      • 

    • 人工審查迭代：審查人在 PR Diff 中提出行級審查意見，Sweep 會讀取留言並自動修正程式碼。
      • 

    

    7. 





2. 安裝與 GitHub 授權設定


在組織或專案中啟用 Sweep，需完成以下步驟：


    

  1. 安裝 GitHub App：造訪 Sweep GitHub App 安裝頁面，選擇要授權的單一儲存庫或整個組織。
    2. 

  2. 指派必要權限：

      

    • Repository Contents（讀寫）：用於取得程式碼與推送修復分支。
      • 

    • Issues（讀寫）：用於讀取 Issue 描述、標記標籤並發布進度留言。
      • 

    • Pull Requests（讀寫）：用於發起 PR、檢視 Diff 變更並回應 Review 意見。
      • 

    • Actions / Checks（唯讀）：用於在測試流水線失敗時讀取建置記錄。
      • 

    

    3. 

  3. Draft 狀態策略：初期建議開啟草稿 PR 模式（draft: true），避免 Sweep 新開的 PR 在團隊通訊軟體中引發過多即時通知，待初步檢核無誤後再轉為 Ready for Review。
    4. 





3. 使用 sweep.yaml 規範工程標準


Sweep 的運作行為主要由專案根目錄下的 sweep.yaml（或 .sweep/config.yaml）定義。透過嚴謹的設定，可以避免幻覺引用、維持團隊程式風格、限定修改邊界並保護核心目錄。


生產環境 sweep.yaml 設定範例


# sweep.yaml - Sweep 自動化 Issue 處理設定檔

# 目標基準分支，Sweep 將基於此分支建立修復分支與發起 PR
branch: 'main'

# 是否以 Draft 形式發起 PR（剛導入建議設為 true，成熟後設為 false）
draft: false

# 是否讀取 GitHub Actions 的測試失敗日誌並自動修正
gha_enabled: true

# 專案技術架構與目錄概覽，協助 AI 迅速掌握專案脈絡
description: >
  後端 REST API 專案，技術堆疊為 Python 3.10 與 FastAPI。
  資料庫操作使用 SQLAlchemy 2.0，儲存體為 PostgreSQL。
  核心業務邏輯位於 services/，資料模型位於 models/，API 路由位於 api/v1/。
  所有 Python 模組引用必須採用全域絕對路徑（例如 `from services.auth import verify_token`）。

# 嚴格禁止 Sweep 讀取或修改的目錄與檔案（安全防護牆）
blocked_dirs:
  - "deploy/"
  - "terraform/"
  - ".github/workflows/"
  - "migrations/"
  - "*.env*"
  - "security/"

# 在發起 PR 前，Sweep 在獨立沙盒中執行的檢驗指令
sandbox:
  install:
    - "poetry install --no-root"
  check:
    - "poetry run ruff check {file_path}"
    - "poetry run pytest tests/unit"

# 注入給 AI Agent 的強制性編程準則
rules:
  - "所有 Bug 修復必須在 tests/ 目錄下新增或更新相應的 pytest 單元測試。"
  - "嚴禁使用萬用字元引用（例如 `from module import *`）。"
  - "所有 API 介面的請求與回應驗證統一採用 Pydantic v2 Schema。"
  - "日誌記錄統一使用 loguru；例外處理區塊內必須使用 logger.exception() 保留完整 Traceback。"
  - "未獲明確指示前，嚴禁變更資料庫 Schema 或產生 alembic 遷移腳本。"
  - "所有新增或修改的函式簽名必須包含完整的型別標註（Type Annotations）。"



核心欄位解析





4. 撰寫高品質 Issue：獲得精準修復的關鍵


Sweep 的產出品質高度仰賴 GitHub Issue 描述的完整度。人類工程師可透過 Slack 與會議即時溝通確認細節，而 AI Agent 完全根據儲存庫程式碼與 Issue Prompt 進行推論。


推薦 Bug Issue 格式


建議在工程團隊內推行結構化範本：


標題: Sweep: Fix 400 Bad Request on empty user metadata payload in /api/v1/profile

### Bug 描述
在透過 `PUT /api/v1/profile` 更新使用者個人資料時，若請求主體傳入空的 `metadata` 字典 `{}`，系統會丟出 ValidationError，而非自動帶入預設空值。

### 重現步驟
1. 發送 HTTP PUT 請求至 `/api/v1/profile`，Body 為 `{"metadata": {}}`。
2. 觀察到 API 回應 HTTP 400，錯誤訊息為 `Value error, metadata must contain required fields`。

### 預期行為
API 應允許空的 `metadata` 字典，自動帶入預設欄位值 (`{"theme": "light", "notifications": true}`) 並正常儲存入庫。

### 相關程式碼與檔案路徑
- `api/v1/profile.py`: `update_profile` 路由處理器。
- `schemas/profile.py`: `UserProfileUpdate` Pydantic 資料模型。
- `services/profile_service.py`: `save_profile_metadata` 業務輔助函式。

### 驗收條件
- 修改 `schemas/profile.py` 驗證規則，使空字典能夠通過並套用預設值。
- 在 `tests/unit/test_profile_api.py` 中新增針對空字典 payload 的測試用例。
- 確保 `tests/unit/` 下既有測試全數通過。



標題修飾指令與運作模式


Sweep 的標題解析函式（strip_sweep）支援多種專屬前綴以調整執行策略：





5. 程式碼審查與即時迭代機制


PR 發起後，工程師與 AI 的合作在 GitHub 原生介面中進行：


[GitHub Issue] ──> Sweep 啟動 ──> 建立 PR ──> CI (GitHub Actions)
                                                    │
                      ┌─────────────────────────────┴─────┐
                      ▼                                   ▼
                CI 失敗 (gha_enabled)                 CI 成功
                      │                                   │
                      ▼                                   ▼
             Sweep 自動提交補丁                    工程師 Code Review
                      │                                   │
                      └─────────► PR 持續更新 ◄───────────┘
                                       │
                            (工程師在 Diff 留言:
                           "@sweepai 請改用共通模組的
                               時間轉換輔助函式")



行內審查反饋


工程師無需在本地切換分支修改。只要在 GitHub PR 的 Diff 頁面標記該行並留言：




@sweepai 這裡請直接使用 DateUtils.formatIso() 工具函式，不需要重新自訂日期格式化邏輯。




Sweep 的 Webhook 會捕捉評論，分析上下文後產生修正，並在同一 PR 上追加 Commit。


重新產生 PR


若原始 Issue 需求描述有誤或實作方向偏差，不需要手動關閉 PR，只需直接編輯原 GitHub Issue 的標題或內文，Sweep 就會自動重置分支並重新發起符合最新說明的 PR。




6. 團隊安全落地準則與邊界


將自主 AI 代理導入正式開發流程時，應建立明確的防護規範：


    

  1. 堅持人工最終審批：嚴禁對 Sweep 建立的 PR 啟用自動合併（Auto-merge）。主分支必須設置保護規則，規定至少一名資深工程師 Review 同意且 CI 測試全綠方可合併。
    2. 

  2. 明確隔離關鍵路徑：務必在 blocked_dirs 中封鎖雲端架構代碼（terraform/、k8s/）、CI 流程腳本（.github/）、資料庫遷移檔以及各類敏感環境變數檔案。
    3. 

  3. 精確限定任務規模：Sweep 最適合處理定義明確的邊界 Bug、補充單元測試與局部相依性更新，不建議直接指派架構重構或需求模糊的大型業務模組開發。
    4. 

  4. 健全自動化測試基底：Sweep 的自我修正能力完全仰賴 CI 報錯輸出。高覆蓋率的單元測試與整合測試，是確保 AI 不引入回歸問題（Regression）的最重要基石。
    5. 





參考資料


涉及產品
Sweep