BOA — Build On Autopilot
強制你的程式碼正確無誤。(標誌:docs/assets/logo.png,一條盤繞的蛇,旁邊有文件與字標「BOA - Build on autopilot」。)
BOA 能讓你做的事
BOA 讓代理能端到端地執行一個專案:開始、工作、暫停、繼續及關閉。你透過以下方式實現:
- 以計劃為單一工作來源,搭配 worktree 上的並行工作線;
- 建構者 → 對抗式審查者 → 測試者 → 整合者,以及讓工作線著陸的合併列車;
- 內建混合搜尋記憶體,因此學習到的內容不會在會話之間遺失;
- 防止毀滅性意外的防護機制,你可為專案撰寫規則;
- 從每個需求到測試的完整可追溯性,並在關閉時確保無未結項目;
- 包含所有需要資訊的手冊與檔案地圖,以及保持長會話安全的上下文閘門;
- 人機協作:當你無法得知或決定時,向使用者提問,並提供替代方案與建議。
所有專案特定部分由你根據接線清單(references/project-wiring.md)自行連接。
請先閱讀已安裝的 AGENTS.md 頂部的運作模式(安裝前:<skill>/assets/templates/AGENTS.md);這是所有規則背後的精神。
你是主代理。此技能將 BOA 安裝到目前目錄的專案中,驗證安裝,然後移交給 run-project。<skill> 是此技能的基本目錄(執行時會告訴你從哪裡載入此檔案)。此處的每個命令都透過 BOA 的唯一進入點 boa <子命令> 執行:安裝前為 sh <skill>/core/bin/boa,安裝後為 sh .boa/bin/boa(在 Windows 上為 <skill>\core\bin\boa.cmd 與 .boa\bin\boa.cmd);boa help 會列出所有子命令。
引數:$ARGUMENTS = <模式> [idea-file]:包含構想的檔案(任意名稱或路徑)為選用(步驟2)。
| 模式 | 需要 | 安裝後的啟動(references/modes/<mode>.md) |
|---|---|---|
greenfield | 構想:要建置的內容(檔案或對話) | 構想 → 藍圖 → 規格 + 契約 → 計劃(先處理規格側任務) |
brownfield | 現有儲存庫 | 分析器全面讀取每一行 → 架構 + 程式碼遵守的契約 + 黃金測試 |
refactor | 現有儲存庫 + 構想:重構目標(檔案或對話) | brownfield + 黃金測試錨定今日行為;目標變成記錄為 ADR 的契約變更 |
先決條件(先檢查)
BOA 需要 git 2.31+(專案必須是或成為 git 儲存庫)與 Python 3.11+(BOA 的工具僅使用標準函式庫),以及你的代理執行環境;在 Windows 上則需要 Git for Windows。boa install 還會建立記憶體搜尋環境:在 .boa/embed/ 中的 BOA 自帶虛擬環境(使用 Python 的 venv 模組,並需要網路連線以存取套件索引與模型中心;約 480 MB 與半分鐘;若在代理後面,需設定 HTTPS_PROXY,包含憑證,因為下載會使用重新導向的家目錄,該目錄不會讀取 ~/.netrc);若此步驟失敗,會指出缺少什麼,其餘部分仍會安裝,然後你詢問使用者如何提供,再重新執行安裝。啟動器會在任何其他操作之前檢查兩者,無需 Python:若缺少或版本太舊,則不更改任何內容並以代碼 3 退出,指出缺少什麼以及找到的版本。然後:以使用者的語言告知他們缺少什麼、找到的版本以及如何在此作業系統上安裝(現在驗證目前的方式);若使用者同意並有權限,則自行為此作業系統撰寫步驟、顯示並執行;否則使用者執行你提供的步驟。再次檢查;只要缺少一項,就絕不繼續。
此流程的規則
- 僅在你自己評估、環境檢查與文件無法決定時才詢問使用者:一次只問一個問題,並先提供選項與你的建議。絕不猜測未知:停止該項目,提問,然後繼續處理其餘部分。
- 絕不重新發明輪子:對於每個專案特定部分,使用內建功能、擴充它或採用現有且維護成本低於收益的函式庫或工具;只在證明有缺口時才從頭開始撰寫。
- 區分兩種語言:產品語言(程式碼、註解、文件、提交;預設為英文)與使用者語言(與使用者的對話、記憶內容、報告、計劃與備註的自由文字);記憶語法一律為英文。
- 所有專案特定部分是規範,而非出貨的程式碼:安裝後,專案接線清單(
references/project-wiring.md)中的每個項目都會成為計劃行,由run-project在完整管線下處理。 - 未經使用者明確同意,絕不安裝系統套件、更改共用服務或寫入使用者層級設定;只要 BOA 的先決條件缺少一項,就絕不繼續。
- 絕不覆寫專案檔案:安裝程式會將衝突的渲染結果存放在
.boa/pending/中,你手動合併它們,並向使用者顯示變更。 - BOA 提供工具與鉤子;你將它們接入你的執行環境。安裝程式不會寫入任何執行環境目錄或設定。
- 若步驟失敗,請以明確的失敗報告停止;絕不將部分安裝報告為已完成。
步驟
- 能力自我評估(優先)。 在任何其他操作之前,評估你的執行環境提供了什麼,透過檢查它(其文件、
--help、設定架構、無害的測試),絕不依賴記憶:鉤子及其事件、子代理與並行能力、背景任務、worktree、每個子代理的模型選擇、權限模式、排程、網路存取、工具與限制。從中決定你如何實現規範的每個部分(管線角色、工作線、防護機制、時鐘、暫停/繼續、上下文閘門),宣告你使用的每個替代方案以及你無法提供的每個部分(絕不偽造)。對於無法自行確定的任何事項,你一次一個問題詢問使用者,並附上選項與建議:擁有者(人機協作)主題、突變測試(是否有敏感程式碼?使用哪個工具?)、持續整合、遠端執行器、模型、保護措施。將結果記錄為能力記錄,存放在memory-bank/04-ARCHITECTURE.md的「環境」中(隨專案版本化;在步驟6的安裝寫入該檔案之後;絕不放在.boa/下,該目錄被 git 忽略),並將決策記錄為決策條目。 - 引數、儲存庫與構想。 驗證模式。專案是目前目錄的 git 頂層。沒有儲存庫:在
greenfield模式下,提供git init並在使用者同意後執行;在brownfield/refactor模式下,停止並要求提供正確的目錄。然後是構想:- 當使用者命名一個檔案(任意名稱或路徑,不僅是
IDEA.md)時,完整讀取它;若命名的檔案不存在,則詢問,絕不猜測; - 在
greenfield/refactor模式下且沒有檔案時,從使用者已在對話中說明的內容取得構想(或重構目標),或要求使用者描述;將其寫入專案中的IDEA.md,以便版本化,顯示給使用者,並僅在使用者確認後才繼續; - 簡短的構想也可以:你仍能推導出所有規格,每個疑問都會變成給使用者的問題(
references/modes/greenfield.md,步驟1); - 在
brownfield模式下不需要構想檔案;使用者在對話中提供的額外方向(限制、優先順序)會記錄在專案的記憶或計劃中。
- 當使用者命名一個檔案(任意名稱或路徑,不僅是
- 檢查環境(不安裝任何東西):專案接線項目「能力記錄」(
references/project-wiring.md)說明要檢查什麼以及如何檢查。判斷是否預期會有長時間的測試波浪(大型測試套件、整合或瀏覽器測試、緩慢的建置)。然後:- 缺少某項:不更改其他任何內容;以使用者的語言告知他們缺少什麼、找到的版本以及如何在此作業系統上安裝(現在驗證的套件名稱)。若有權限則提供執行的選項:若同意,則自行為此作業系統撰寫步驟、顯示並執行。否則使用者執行你提供的步驟。然後再次檢查;只要缺少一項,就絕不繼續。
git config user.email(或user.name)為空:要求提供提交身份(專案本地git config,絕不全域設定)。
- 問題(僅限步驟1和3後仍未解決的問題),每個問題附上你的建議:
- 專案名稱(預設:目錄名稱)、使用者語言(根據使用者書寫方式偵測;不明確時提問)與產品語言(預設英文;僅能透過
boa language set後續更改);名稱包含無 ASCII 形式的字母(例如西里爾字母、中日韓文字,或拉丁字母如 sharp s、帶刪節線的 L、帶刪節線的 O)時,不會有預設的 slug:建議一個音譯,與使用者確認,並作為BOA_PROJECT_SLUG傳遞; - 技術棧,當構想或儲存庫未指定時:根據
references/stack-choice.md的目標選擇(最新穩定版本,現在線上驗證;將選擇記錄為安裝後的 ADR),僅在確實是分支時才與使用者確認; - 代理執行環境:你的自我評估(步驟1)找到的環境,作為
BOA_RUNTIME傳遞(references/runtimes.md); - 模型(無預設隨附):從執行環境目前的模型清單中挑選其前沿模型(建構者、審查者、分析者)與次一級模型(建構者中階、測試者、整合者),現在驗證,並與使用者確認;
- forge(
references/forge.md):檢查未找到時,選擇哪個 forge(github/gitlab/none)與儲存庫;若 CLI 缺失或未驗證,說明如何修復。然後是 forge 決策,一次一個問題,僅在使用者明確同意後才執行:使用 forge 遠端(建立一個,或使用現有的,在第一次推送或 PR/MR 前詢問);其可見性(根據專案性質建議私人或公開,並附上理由;使用者決定);伺服器端對 main 分支的保護;持續整合,僅在增加價值時(同意則計劃專案接線清單中的 CI 任務,references/project-wiring.md:由代理為此專案撰寫,觸發條件、映像與固定版本屆時決定並驗證;BOA 不安裝 CI 檔案)。若不同意則保持所有內容為本地; - 測試套件的執行位置、串行或並行,以及同時執行數量(專案接線項目「輕量與重量級套件」:根據測量負載建議,與使用者共同決定),包括在預期長時間測試波浪或機器較小時的遠端測試執行器:一個或一個池;在安裝後設定(專案接線項目「遠端執行器」),因此
BOA_RUNNER保持為off,直到有執行器回應。
- 專案名稱(預設:目錄名稱)、使用者語言(根據使用者書寫方式偵測;不明確時提問)與產品語言(預設英文;僅能透過
- 配置(專案接線項目「Config」):
sh <skill>/core/bin/boa install --target . --package <skill>會將帶有註解的範本寫入.boa/config.env(如果不存在),然後停止;填入每個答案(BOA_RUNTIME、BOA_STACK、BOA_MODE、BOA_PROJECT_NAME、BOA_REPLY_LANGUAGE、BOA_FORGE、BOA_FORGE_REPO、BOA_RUNNER、BOA_MODEL_FRONTIER、BOA_MODEL_MID、…;BOA_PYTHON:每個鉤子執行的 python)。暫存根目錄及其每個任務的佈局是你的執行環境的事實:從references/runtimes.md中你的執行環境設定檔取得它們(讀取你的執行環境提供的真實臨時目錄,絕不從記憶重建),並設定BOA_SCRATCH_ROOT。向使用者簡要顯示產生的.boa/config.env。 - 安裝: 再次執行
sh <skill>/core/bin/boa install --target . --package <skill>(對於 brownfield/refactor 專案,先嘗試--dry-run並顯示計劃)。BOA 的代理與命令僅部署在.boa/下(.boa/agents/、.boa/commands/);不附帶任何執行環境特定檔案。它在.boa/之外寫入的所有內容:AGENTS.md(現有檔案中的標記區塊)、memory-bank/、docs/agent-handbook.md、docs/parity/、主代理目錄、forge 的 PR/MR 範本(.github/pull_request_template.md或.gitlab/merge_request_templates/Default.md),以及.gitignore、.gitattributes(BOA 的檔案固定為 LF 換行符號)、.git/info/exclude和專案自己的memory-bank/04-ARCHITECTURE.md(殘留登記表)中的標記區塊。閱讀其報告:對於每個conflict或kept行,將.boa/pending/<path>中的渲染結果手動合併到專案檔案中(保留專案內容;添加 BOA 的),然後重新執行安裝程式,直到報告中沒有你尚未有意解決的衝突為止。空的 REQUIRED 或無效值會停止安裝並顯示金鑰名稱:在.boa/config.env中修復後重新執行。 - 將 BOA 接入你的執行環境(以你的執行環境自有格式自行接線)(專案接線清單項目;每個執行環境的作法,若無預設則以
references/runtimes.md為範例)。BOA 的代理與命令檔案帶有中性標頭(名稱、描述、模型層級、努力程度、工具)以及執行環境中性的內容:你轉換它們,BOA 不附帶轉接器。根據步驟1的發現完成所有操作,然後在你的執行環境中驗證:- (a) 將
.boa/agents/中的代理轉換為你的執行環境的子代理格式,並為每個層級設定配置好的模型; - (b) 將
.boa/commands/中的命令轉換為你的執行環境的命令或提示詞格式; - (c) 在你的執行環境設定中註冊 BOA 提供的鉤子(事件、匹配器、命令的清單在
references/runtimes.md中),將你的執行環境事件對應到 BOA 的中性事件,包括報告捕獲:子代理停止鉤子將每個代理的最終報告逐字儲存到工作線日誌,以及主代理停止和會話狀態鉤子; - (d) 當你的執行環境缺少其中一項(無子代理、無命令、無鉤子、無法拒絕的鉤子)時,你選擇的能力自我評估下最接近且忠實的等效項,宣告且絕不偽造;當你無法判斷時詢問使用者;
- (e) 指示:所有規則都存放在 AGENTS.md 中;只有原生不讀取它的執行環境才會獲得自己的指示檔案
- (a) 將
…
[為翻譯而截斷]