使用AI智能體自動化fork維護 | Cohere

如果你維護着一個軟件fork，上游代碼在不斷更新，你需要同步、修復問題、驗證、發佈。幾周後，上游再次更新，循環重複。

本文描述了一種使用AI編碼智能體自動化這一循環的通用方法。我們將其應用於Cohere的vLLM fork，通過一個具體案例展示了例行的上游版本發佈如何悄無聲息地破壞了Cohere的cohere-transcribe-03-2026 ASR模型，而修復方案最終回溯為vLLM的PR。

實踐中，這種方法將吸收新上游版本的時間從數週壓縮到數天，人類只需審查最終結果。支撐這一工作流的技能已在cohere-ai/vllm-skills開源。

問題

維護一個長期fork活躍開發的項目是一項持續性成本。但上游版本也帶來了新功能、性能改進和bug修復，你需要這些改進。保持同步不僅是維護，更是讓fork持續進步的方式。問題在於，每個上游版本都會引入干擾：合併衝突、API變更、函數刪除、新依賴或測試失敗。fork維護者的工作就是吸收這些干擾，恢復正常工作狀態。

這項工作始終遵循相同的結構：

1. 將新上游版本同步到fork。
2. 通過運行測試、基準測試、評估來衡量哪些部分出錯。
3. 修復衝突，適配API變更，更新測試。
4. 重複步驟2和3，直到全部通過。
5. 發佈更新後的fork。

這是一個反饋循環。每個維護fork的團隊都存在這個循環，只是它緩慢且手動。對於Cohere的vLLM fork，吸收一次典型的上游版本曾需要開發者數週的零散注意力，而本文所述的目標是將時間縮短到幾天，且大部分時間由智能體自主運行。

反饋系統

在控制理論中，閉環系統持續比較輸出與參考值，並調整以縮小差距。但真實系統也會面臨干擾：將系統推離期望狀態的外部輸入。

r(t)是參考值，系統應產生的期望值。 y(t)是輸出，系統實際產生的值。 e(t)是誤差，參考值與測量值的差距，計算為r(t) − measured_output。 d(t)是干擾，推動輸出偏離參考值的外部力。

控制器利用誤差調整系統；反饋使輸出趨近目標。精心設計的反饋循環不僅跟蹤參考值，還能通過檢測干擾對輸出的影響並將其驅回零，而無需人工干預。

定速巡航是經典例子。你設定期望速度（參考值），汽車維持速度（系統），但出現山坡或逆風（干擾）。好的控制器能注意到速度下降並自動調整油門。

Fork維護具有完全相同的結構。

Fork維護：

• r(t)：自定義更改在最新上游上正確工作
• d(t)：新上游版本（衝突、API變更、破壞性更改）
• 控制器：解決衝突、更新補丁、修復測試
• 系統：fork本身（代碼、測試、CI）
• y(t)：同步後fork的運行時行為
• 測量：測試套件、基準測試、評估
• 誤差：期望行為與實際同步後行為之間的差異

目標是自動化整個循環——同步、測量、修復、重複——從而以最少的人工干預吸收上游改進。

智能體之前的流程

同步fork有多種方式：合併、cherry-pick和變基是最常見的。合併保留兩個歷史，但產生混亂的提交圖，難以區分自定義更改與上游。Cherry-pick提供精確控制，但當上遊每次發佈移動數百個提交時無法擴展；你最終會維護一個不斷增長的pick列表，逐漸不同步。變基將自定義提交重播到新上游標籤之上，產生清晰線性的歷史，補丁明確位於頂部。代價是變基會重寫歷史並強制推送，但對於自定義提交數量較少且上游快速移動的fork，這種清晰性值得。

在Cohere，我們早期就採用了變基。在基於智能體的工作流之前，我們的流程已經結合了腳本自動化與手動工作。

• 變基：GitHub Actions工作流嘗試變基到目標上游標籤，利用共享git rerere緩存重播之前解決的衝突。
• 解決衝突：當工作流的自動變基失敗時，開發者本地接手，手動解決剩餘衝突（通常藉助LLM助手），驗證CI，並上傳更新後的rerere緩存。
• 驗證併發布：一旦變基分支CI通過，它就成為fork的新基礎。

這個流程已經結合了多種自動化：git rerere重播已知解決方案，GitHub Actions運行變基嘗試和CI，LLM輔助單個編碼和調試任務。但人類仍然是控制器的一部分，將各個部分拼接在一起，選擇應用哪些修復，並決定何時重新運行。反饋循環是工作的，只是速度較慢。下面描述的基於智能體的工作流保持相同結構，但讓智能體扮演控制器角色，使迭代以機器速度進行，人類僅在邊緣干預。

自動化每個組件

該方法將循環分解為三個可智能體自動化的組件，每個映射到控制圖的一部分。

1. 干擾注入

智能體技能檢測並應用新的上游版本。它變基fork到新標籤並自動解決合併衝突。這是干擾進入系統：一個有意的自動化動作，我們知道會暫時破壞東西，但我們希望儘快吸收。

該技能需要：

• 檢測fork當前基於的上游標籤
• 檢查是否存在更新的標籤
• 執行git rebase --onto並處理fork的自定義提交
• 解決衝突（利用上游差異上下文做出明智決策）

2. 測量收集

變基後，fork處於未知狀態。測量告訴你離目標有多遠：一個所有自定義行為完好的工作fork。沒有測量，智能體就會盲目飛行。

測量本身（測試、基準測試、評估）由項目定義，在自動化之前就已存在。智能體自動化的是收集它們：一個測試運行器技能，知道如何設置環境、執行驗證套件並報告結果。

• 測試：單元測試、集成測試、正確性測試
• 基準測試：性能檢查（吞吐量、延遲、資源使用）
• 評估：特定領域質量指標（準確率、困惑度、任務分數）

輸出是誤差信號：哪些測試失敗、哪些基準測試迴歸、哪些評估下降。測量越豐富可靠，控制器收斂越快。測試套件薄弱的fork信號弱；智能體不知道什麼壞了，也不知道離完成還有多遠。

3. 控制器

智能體技能閉合循環。變基完成且測量結果返回後，該技能：

• 讀取測試和基準測試結果
• 識別失敗和迴歸
• 應用修復（解決構建錯誤、更新破壞的測試、適配API變更）
• 重新運行測量
• 重複直到所有測量通過，或升級給人類

這是將誤差驅向零的控制器。關鍵洞察是智能體不需要第一次就變基正確，它只需要迭代——就像開發者一樣。

案例研究：vLLM

vLLM是一個開源LLM服務引擎。Cohere在整個推理棧中使用它，從模型開發期間的RL展開和評估，到生產環境中服務用户請求。我們維護一個fork來承載自定義提交——額外模型支持、自定義內核和優化、修改的入口點、額外測試——有些正在向上遊提交，其他則是我們的特定需求。挑戰是將這些提交重播到每個新上游版本而不破壞任何東西。上游大約每幾周發佈一次，每次都很龐大：標籤間的差異常涉及數百個文件。

技能棧

我們構建了五個技能，在cohere-ai/vllm-skills開源，實例化了通用模式。每個技能是一個markdown文檔，編碼智能體讀取並交互執行，可以訪問終端、文件系統和所需工具。

• install-vllm：環境設置。創建uv虛擬環境，以可編輯模式安裝vLLM並正確預編譯CUDA wheel。
• local-test-runner：測量。本地在NVIDIA GPU上運行Buildkite CI等效測試；解析.buildkite/test_areas/*.yaml，管理HuggingFace令牌，捕獲日誌。
• detect-upstream-base：干擾檢測。通過git merge-base + git describe找到fork當前基於的上游標籤。
• rebase-assistant：控制器。將自定義提交從v1變基到v2，利用上游差異上下文解決衝突，用test-runner驗證結果。
• Orchestrator：檢查新上游版本，端到端調用detect-upstream-base和rebase-assistant。

變基如何運行

本節中：v1/v2是舊的和新的上游標籤，b1/b2是變基前後的fork分支。

典型調用："/auto-rebase sync the current branch with the latest upstream release and make sure passes."

auto-rebase檢查先決條件（gh auth狀態），然後調用detect-upstream-base找到v1（例如v0.19.0）。 它獲取上游標籤並發現v2（v0.19.1）。向用户展示版本並等待確認。 它收集用户的驗證檢查（例如pytest tests/entrypoints/openai/correctness/test_transcription_api_correctness.py）。 它調用rebase-assistant，後者：

• 分析b1上的自定義提交（git log v1..HEAD）
• 首先驗證測試在b1上通過（使用local-test-runner和v1 wheel），這是確保已知良好基線的門控
• 備份b1，創建b2，可選擠壓自定義提交
• 運行git rebase --onto upstream/v0.19.1 HEAD
• 通過比較upstream/v1..upstream/v2差異解決衝突，瞭解變更
• 在b2上運行測試（使用local-test-runner和v2 wheel）
• 如果測試失敗：檢查失敗，與v1基線比較，應用修復，重新運行（內部反饋循環）
• 一旦所有檢查通過，auto-rebase展示摘要（重播的提交、解決的衝突、測試結果）並提供推送選項。

作為技能交互序列：

• 內部循環是控制器在b2上迭代：local-test-runner報告失敗，rebase-assistant應用修復並重新運行，直到測試通過。

工作示例：Cohere Transcribe on v0.19.1

這是該循環端到端的真實調用。

設置：我們的fork位於cohere-transcribe-v0.19.0，在上游v0.19.0上有一個自定義提交，為Cohere的cohere-transcribe-03-2026 ASR模型啓用了一個正確性測試。vLLM在v0.19.0中增加了對此模型架構的支持，但上游測試被註釋掉了，因為權重尚未發佈。我們的自定義提交只是取消了一行註釋。

測試在earnings-22驗證集的一個過濾切片上運行模型，並斷言WER ≤ 11.92。這個數字就是我們的測量信號y(t)。當fork健康時，數字接近11.92；當有東西被破壞時，它會飆升。

干擾：上游發佈了v0.19.1。

（原文因AI成本控制而被截斷）