如果你每天跟代碼倉(cāng)庫(kù)打交道應(yīng)該能明顯感覺到現(xiàn)在的 AI 編碼代理寫代碼早就不是新鮮事了真正難的是把“寫完的代碼”一路送到 PR 合并。無論是企業(yè)內(nèi)部的評(píng)審規(guī)范還是開源倉(cāng)庫(kù)的分支保護(hù)都意味著你不能讓模型生成完代碼就撒手不管。我今天想聊的這套小系統(tǒng)就是一位“總導(dǎo)演”它接收一個(gè) Issue自己拆任務(wù)、自己寫代碼、自己跑測(cè)試、自己建 PR甚至在滿足條件時(shí)自己完成 PR 合并。整個(gè)過程只要在 Issue 上打一個(gè)標(biāo)簽剩下的大多數(shù)事情都由工作流自動(dòng)接管。這套方案適合誰如果你正在用 AI 輔助編程但發(fā)現(xiàn)“生成代碼挺好、一提 PR 就全卡住”如果你在運(yùn)維一個(gè)小團(tuán)隊(duì)希望把重復(fù)性的例行需求自動(dòng)化或者你只是好奇“從任務(wù)描述到 PR 合并”這條鏈路到底能自動(dòng)化到什么程度這篇都值得往下看。我搭這套東西不是為了炫技而是真的在內(nèi)部項(xiàng)目里跑了兩個(gè)星期踩過不少坑最后沉淀出一套可以直接抄作業(yè)的方案。1. 先想清楚“總導(dǎo)演”到底執(zhí)導(dǎo)什么很多 AI 編碼工具解決的是“單個(gè)文件”的問題但真正到項(xiàng)目交付你面對(duì)的是“一條流程”。流程中有任務(wù)描述、代碼結(jié)構(gòu)、測(cè)試約束、分支規(guī)范、評(píng)審意見一個(gè)都不能少。標(biāo)題里說的“總導(dǎo)演”指的就是把這套流程串起來的人——雖然執(zhí)行者是 AI但真正讓任務(wù)能走進(jìn) PR 合并靠的是流程編排。1.1 流程全貌從 Issue 到合并的一條龍鏈路我先畫一下鏈路簡(jiǎn)單說就是開發(fā)者在 Issue 里寫清楚需求打上一個(gè)約定好的標(biāo)簽工作流被觸發(fā)后AI 代理先把 Issue 內(nèi)容解析成結(jié)構(gòu)化任務(wù)再根據(jù)倉(cāng)庫(kù)當(dāng)前的代碼生成補(bǔ)丁隨后在隔離環(huán)境里跑測(cè)試和靜態(tài)檢查全部通過后創(chuàng)建新分支并提交 PR最后在滿足分支保護(hù)條件的情況下完成合并。也就是說這條鏈路里的“輸入”是自然語言任務(wù)“輸出”是合并進(jìn)主干分支的代碼。整條鏈路由三塊拼成任務(wù)理解、代碼執(zhí)行、質(zhì)量校驗(yàn)。任務(wù)理解負(fù)責(zé)把模糊的中文或英文需求變成可執(zhí)行的改動(dòng)清單代碼執(zhí)行負(fù)責(zé)真正寫代碼和改文件質(zhì)量校驗(yàn)負(fù)責(zé)把不達(dá)標(biāo)的代碼攔在門外。這個(gè)過程最核心的難點(diǎn)不在“讓模型寫代碼”而在“讓模型理解它正在參與一個(gè)真實(shí)項(xiàng)目”。真實(shí)項(xiàng)目有目錄結(jié)構(gòu)、有已有代碼風(fēng)格、有測(cè)試約定如果模型只是憑空生成代碼而不考慮這些上下文最后的結(jié)果基本不能用。所以整個(gè)流程設(shè)計(jì)的第一原則就是把上下文喂夠把校驗(yàn)做成硬門檻。1.2 單 Agent 會(huì)話 vs 項(xiàng)目級(jí)工作流以前我們用 AI 編碼代理通常是開一個(gè)對(duì)話窗口把需求粘進(jìn)去然后等它給出代碼片段。這種“單 Agent 會(huì)話”模式對(duì)一次性提問夠用但它天然缺三樣?xùn)|西一是沒法訪問倉(cāng)庫(kù)全貌二是沒法在真實(shí)環(huán)境里驗(yàn)證生成結(jié)果三是沒法把結(jié)果自動(dòng)送進(jìn)評(píng)審和合并流程。我這次想做的“項(xiàng)目級(jí)工作流”本質(zhì)上就是把原來的“對(duì)話窗口”變成“后臺(tái)執(zhí)行器”。AI 代理不再只面對(duì)一段話而是面對(duì)一個(gè)完整任務(wù)。它需要自己決定改哪些文件、測(cè)試怎么跑、PR 怎么寫甚至要自己處理 CI 報(bào)錯(cuò)后的重試。這對(duì)模型能力的要求高了不少但對(duì)使用者的要求反而降低了——你只需要會(huì)提需求。從實(shí)際效果看這兩種模式帶來的體感差別非常大。對(duì)話模式是“AI 給你答案”項(xiàng)目級(jí)工作流是“AI 給你交付”。前者把思考留給了人后者把執(zhí)行流程也接了過去。當(dāng)然代價(jià)就是搭建成本高后面我會(huì)逐步拆解。1.3 我對(duì)方案選型的關(guān)鍵判斷市面上已經(jīng)有不少成熟的一鍵 PR 工具和 AI 編程助手那我為什么還要自己拼一套關(guān)鍵原因是我需要可控性。AI 編碼代理和 PR 合并是兩套系統(tǒng)直接用成品工具有時(shí)候很難把組織內(nèi)部的測(cè)試規(guī)范、分支保護(hù)規(guī)則、評(píng)審流程整套揉進(jìn)去。自己拼裝這套流程的好處首先是把“模型”這個(gè)環(huán)節(jié)設(shè)計(jì)成可替換的。今天我可能用某個(gè)模型明天如果評(píng)測(cè)下來另一個(gè)模型在特定任務(wù)上更穩(wěn)我可以直接在配置里切換而不需要?jiǎng)诱麄€(gè)流水線。其次整個(gè)流程的每一步都可以插樁、打日志、設(shè)權(quán)限。比如“哪些路徑不允許 AI 改動(dòng)”這類安全策略在成品工具里不一定能精細(xì)控制。所以我的結(jié)論是不要盲目追求“全自動(dòng)”而是把自動(dòng)化做成“有監(jiān)督的可控流水線”。AI 負(fù)責(zé)干活人負(fù)責(zé)確認(rèn)邊界。這也是為什么我在設(shè)計(jì)里保留了人工閘門后面的實(shí)操部分會(huì)詳細(xì)講。2. 架構(gòu)設(shè)計(jì)與工具選型項(xiàng)目級(jí)工作流不是寫一個(gè)大腳本硬跑而是要有明確的層次劃分。我最終采用的是三層結(jié)構(gòu)任務(wù)解析層、編碼執(zhí)行層、質(zhì)量校驗(yàn)層。每層只做自己該做的事層與層之間通過 JSON 傳遞結(jié)構(gòu)化數(shù)據(jù)而不是靠粘貼復(fù)制文本這就避免了很多格式解析上的麻煩。2.1 三層架構(gòu)解析、執(zhí)行、校驗(yàn)任務(wù)解析層做的是“把 Issue 的自然語言變成機(jī)器可讀的改動(dòng)意圖”。這一層我用的還是 AI 模型但輸出不是代碼而是 JSON 結(jié)構(gòu)。結(jié)構(gòu)里包含任務(wù)目標(biāo)、涉及的技術(shù)棧、驗(yàn)收標(biāo)準(zhǔn)和待改動(dòng)文件列表。這樣做的目的是讓后面兩層有一個(gè)穩(wěn)定的輸入格式而不是每次都去啃一段長(zhǎng)文本。編碼執(zhí)行層是最容易出現(xiàn)驚喜的地方。它負(fù)責(zé)根據(jù)解析結(jié)果生成具體的文件改動(dòng)同樣以 JSON 輸出路徑是什么、內(nèi)容是新增還是修改、應(yīng)該改成什么樣。拿到這個(gè) JSON 后腳本才真正往工作區(qū)寫文件。這里有個(gè)關(guān)鍵點(diǎn)模型直接生成完整文件內(nèi)容比生成 git diff 補(bǔ)丁要穩(wěn)得多后面踩坑部分我會(huì)展開。質(zhì)量校驗(yàn)層則是把 AI 生成的代碼放進(jìn)真實(shí)的測(cè)試環(huán)境里跑一遍。靜態(tài)檢查、單元測(cè)試、編譯、構(gòu)建該跑的都跑。只有這一層全綠了流程才會(huì)繼續(xù)走向創(chuàng)建 PR。沒有這層校驗(yàn)的 AI 編碼代理基本就是裸奔。2.2 模型接入統(tǒng)一協(xié)議帶來的靈活度模型接入方面我強(qiáng)烈建議只做“兼容 OpenAI 協(xié)議的 API”對(duì)接。理由很簡(jiǎn)單這類協(xié)議的生態(tài)最成熟SDK 穩(wěn)定切換模型時(shí)基本不用改代碼。我內(nèi)部搭了一個(gè)統(tǒng)一的模型網(wǎng)關(guān)網(wǎng)關(guān)背后接的是公司合規(guī)允許使用的各類模型服務(wù)模型名字寫進(jìn)配置文件就行。你需要準(zhǔn)備的核心參數(shù)只有四個(gè)模型名稱、API Key、Base URL、超時(shí)時(shí)間。在 Python 代碼里一套 Client 可以通吃。選用模型時(shí)我重點(diǎn)看三項(xiàng)能力長(zhǎng)上下文理解力、代碼生成正確率、對(duì) JSON 結(jié)構(gòu)化輸出格式的遵循程度。長(zhǎng)上下文能力尤其重要因?yàn)槟阋褌}(cāng)庫(kù)目錄結(jié)構(gòu)、關(guān)鍵文件內(nèi)容、任務(wù)描述全部塞進(jìn)提示詞里上下文不夠就會(huì)丟失關(guān)鍵信息。成本方面不用被“AI 跑流程很貴”嚇到。從我實(shí)際賬單看一個(gè)中等復(fù)雜度的任務(wù)大約消耗 100 萬到 200 萬 token按目前主流 API 的定價(jià)換算大概在幾元到十幾元之間。相比一個(gè)初級(jí)開發(fā)干半天才能真正交付一個(gè) PR這個(gè)成本可以接受。2.3 倉(cāng)庫(kù)保護(hù)規(guī)則與 Token 權(quán)限邊界這是整條鏈路設(shè)計(jì)里我最看重的一環(huán)。自動(dòng)合并 PR 的前提是倉(cāng)庫(kù)本身有保護(hù)規(guī)則兜底。我建議在主干分支上強(qiáng)制開啟兩個(gè)規(guī)則一是禁止直接推送只能通過 PR 合入二是要求 PR 在合并前必須通過所有狀態(tài)檢查。這兩條是避免 AI 代理把倉(cāng)庫(kù)搞亂的安全底牌。Token 權(quán)限要按最小化原則配置。我用的是倉(cāng)庫(kù)級(jí) Personal Access Token只勾選跟 PR 和 Issue 相關(guān)的權(quán)限比如讀取 Issue、創(chuàng)建分支、創(chuàng)建 PR、評(píng)論。絕不給它管理員權(quán)限也絕不讓它具備直接修改主干分支保護(hù)規(guī)則的權(quán)限。這樣即使模型生成的代碼有問題或者 Agent 行為出現(xiàn)異常它也只能在劃定的跑道里折騰翻不了天。實(shí)際操作中我見過很多團(tuán)隊(duì)為了方便把高權(quán)限 Token 直接寫進(jìn) workflow這非常危險(xiǎn)。一旦 Token 泄露等于整個(gè)倉(cāng)庫(kù)裸奔。正確做法是把 Token 存進(jìn)倉(cāng)庫(kù)或組織的 Secrets 里在 workflow 中通過環(huán)境變量注入并且定期輪換。我會(huì)在實(shí)操流程里再?gòu)?qiáng)調(diào)一次。3. 實(shí)操把流程從零搭起來理論講完直接進(jìn)實(shí)操。我假設(shè)你用的是 GitHub 和 GitHub Actions因?yàn)檫@套組合完全不限制模型來源內(nèi)部網(wǎng)關(guān)可以管住調(diào)用權(quán)限非常適合做 AI 編碼代理工作流。下面五個(gè)步驟是我跑通后又簡(jiǎn)化過的版本每一步都保留了必要的驗(yàn)證節(jié)點(diǎn)。3.1 第一步定義任務(wù)流轉(zhuǎn)的“入口單據(jù)”整個(gè)流程以 Issue 為入口所以第一步是給 Issue 定格式。一次理想的任務(wù)描述至少要有四個(gè)部分目標(biāo)背景、需求明細(xì)、驗(yàn)收標(biāo)準(zhǔn)、技術(shù)約束。我把模板直接存成.github/ISSUE_TEMPLATE/agent_task.yml這樣開發(fā)者新建 Issue 時(shí)會(huì)自動(dòng)帶出結(jié)構(gòu)。模板示例name: Agent Task description: 給 AI 編碼代理分配一個(gè)可自動(dòng)執(zhí)行的開發(fā)任務(wù) title: [Agent] labels: [agent] body: - type: textarea id: background attributes: label: 任務(wù)背景 placeholder: 為什么需要這個(gè)改動(dòng) validations: required: true - type: textarea id: requirement attributes: label: 需求明細(xì) placeholder: 具體要做什么盡量拆成條目。 validations: required: true - type: textarea id: acceptance attributes: label: 驗(yàn)收標(biāo)準(zhǔn) placeholder: 什么樣的結(jié)果算完成 validations: required: true - type: input id: tech_stack attributes: label: 技術(shù)棧約束 description: 例如后端 Python 3.12、前端 Vue、數(shù)據(jù)庫(kù) MySQL 等不要小看這個(gè)模板的作用。任務(wù)解析層能不能穩(wěn)定輸出 JSON很大程度上取決于源文本是否結(jié)構(gòu)清晰。模板強(qiáng)制寫作者把需求拆成條目AI 解析時(shí)就不容易遺漏關(guān)鍵點(diǎn)。我試過不限制格式的自由輸入最后解析質(zhì)量波動(dòng)非常大。當(dāng) Issue 創(chuàng)建后開發(fā)者或維護(hù)者手動(dòng)給它打上agent標(biāo)簽。這個(gè)標(biāo)簽就是啟動(dòng)信號(hào)。選擇手動(dòng)打標(biāo)簽而不是自動(dòng)觸發(fā)是為了避免任何 Issue 創(chuàng)建都讓 AI 去跑一遍——那樣既浪費(fèi)成本也容易把無關(guān)討論帶入執(zhí)行流程。3.2 第二步寫 Agent 執(zhí)行器Agent 執(zhí)行器是整個(gè)工作流的大腦。我用 Python 來寫核心依賴只有兩個(gè)OpenAI 兼容客戶端和 PyGithub。下面這段代碼是執(zhí)行器的骨架它會(huì)完成讀取 Issue、調(diào)用模型解析任務(wù)、生成文件改動(dòng)、寫入分支這一整套動(dòng)作。import os import json import base64 from openai import OpenAI from github import Github REPO_NAME os.environ[REPO_NAME] ISSUE_NUMBER int(os.environ[ISSUE_NUMBER]) TARGET_BRANCH os.environ.get(TARGET_BRANCH, main) MAX_RETRY int(os.environ.get(MAX_RETRY, 3)) client OpenAI( api_keyos.environ[MODEL_API_KEY], base_urlos.environ[MODEL_BASE_URL], ) gh Github(os.environ[REPO_AGENT_TOKEN]) repo gh.get_repo(REPO_NAME) issue repo.get_issue(ISSUE_NUMBER) # 1. 讀取 Issue 并拼接上下文 def build_task_prompt(issue_body: str) - str: tree get_repo_tree(repo.get_git_tree( repo.get_branch(TARGET_BRANCH).commit.sha, recursiveTrue )) return f 你是倉(cāng)庫(kù) {REPO_NAME} 的 AI 開發(fā)總導(dǎo)演。 請(qǐng)根據(jù) Issue 內(nèi)容理解倉(cāng)庫(kù)結(jié)構(gòu)輸出 JSON {{ summary: 一句話總結(jié), tech_stack: 技術(shù)棧, acceptance_criteria: [], files: [{{path: , action: create|modify|delete, description: }}] }} 倉(cāng)庫(kù)文件樹{tree[:6000]} Issue 內(nèi)容{issue_body} def call_model(prompt: str, schema: dict) - dict: resp client.chat.completions.create( modelos.environ[MODEL_NAME], temperature0.2, response_format{type: json_object}, messages[ {role: system, content: 你只輸出嚴(yán)格 JSON。}, {role: user, content: prompt}, ], ) return json.loads(resp.choices[0].message.content) # 2. 解析任務(wù) plan call_model(build_task_prompt(issue.body), None) # 3. 生成代碼用完整文件內(nèi)容而不是 diff code_prompt build_code_prompt(plan, get_code_snippets(repo, plan[files])) for attempt in range(MAX_RETRY): result call_model(code_prompt, None) if validate_files(result[files]): break else: post_issue_comment(issue, 模型在代碼生成階段重試次數(shù)用盡請(qǐng)人工介入。) raise SystemExit(1) # 4. 創(chuàng)建分支并寫入文件 branch_name fagent/issue-{ISSUE_NUMBER} create_branch_from_main(repo, branch_name) write_files_to_branch(repo, branch_name, result[files]) print(json.dumps({branch: branch_name, plan: plan}, ensure_asciiFalse))這里有三點(diǎn)值得說明。第一提示詞里我塞入了倉(cāng)庫(kù)文件樹但只截?cái)?6000 字符避免上下文過長(zhǎng)導(dǎo)致模型抓不住重點(diǎn)。第二模型生成文件的過程中加了MAX_RETRY循環(huán)如果校驗(yàn)不通過就讓它自己重新輸出最多重試三次三次不行就停止并通知人工。第三寫分支時(shí)只用倉(cāng)庫(kù)級(jí) Token 能操作的 API全程不碰本地 Git 命令避免因?yàn)闄?quán)限問題在 CI 環(huán)境里卡住。3.3 第三步在不信任的代碼上跑測(cè)試AI 生成的代碼默認(rèn)是不可信的。所以在把代碼送到主干之前必須把它放進(jìn)隔離環(huán)境里跑一遍完整校驗(yàn)。我這里說的隔離環(huán)境就是 GitHub Actions 的 runner 容器。每一步安裝依賴和跑測(cè)試都不直接作用在你本機(jī)而是在一個(gè)全新的環(huán)境中完成天然具備隔離性。在 CI 里跑測(cè)試的核心 workflow 長(zhǎng)這樣name: agent-run on: issues: types: [labeled] jobs: agent: if: github.event.label.name agent runs-on: ubuntu-latest permissions: contents: write issues: write pull-requests: write steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.12 - name: 安裝依賴 run: pip install -r requirements-dev.txt openai PyGithub - name: 執(zhí)行 AI Agent run: python agent_director.py env: REPO_NAME: ${{ github.repository }} ISSUE_NUMBER: ${{ github.event.issue.number }} REPO_AGENT_TOKEN: ${{ secrets.REPO_AGENT_TOKEN }} MODEL_API_KEY: ${{ secrets.MODEL_API_KEY }} MODEL_BASE_URL: ${{ secrets.MODEL_BASE_URL }} MODEL_NAME: ${{ vars.MODEL_NAME }}下一步是在新分支上跑測(cè)試。測(cè)試階段我會(huì)專門用一個(gè)獨(dú)立 job確保只有測(cè)試通過后才會(huì)繼續(xù)后續(xù)步驟。這一步用倉(cāng)庫(kù)自帶的 Actions 就夠了關(guān)鍵在于把if: success()條件加在后續(xù)創(chuàng)建 PR 的步驟上讓測(cè)試失敗時(shí)流程直接中斷PR 永遠(yuǎn)不會(huì)被創(chuàng)建。再補(bǔ)充一個(gè)很容易忽略的點(diǎn)依賴安裝階段不要圖省事直接pip install -r requirements.txtAI 生成的代碼經(jīng)常會(huì)新增第三方依賴所以要在 Agent 執(zhí)行階段先把requirements.txt里的改動(dòng)寫進(jìn)去然后在測(cè)試 job 里重新安裝。如果不這樣做可能出現(xiàn)“本地測(cè)試過了、CI 里缺包”的尷尬情況。3.4 第四步PR 創(chuàng)建與自動(dòng)合并測(cè)試全綠后就進(jìn)入 PR 階段。創(chuàng)建 PR 時(shí)我會(huì)讓模型寫一段 PR 描述但題目和描述框架由我們預(yù)先定義好避免模型自由發(fā)揮。PR 標(biāo)題統(tǒng)一帶上 Issue 編號(hào)描述里固定包含“任務(wù)來源”“改動(dòng)摘要”“測(cè)試說明”三個(gè)區(qū)塊這樣評(píng)審人打開 PR 就能快速理解上下文。創(chuàng)建 PR 的代碼很直接pr repo.create_pull( titlef Agent 自動(dòng) PR: #{issue.number} {plan[summary]}, bodybuild_pr_body(issue, plan, result), headfagent/issue-{issue.number}, baseTARGET_BRANCH, )真正需要小心的是“自動(dòng)合并”這一步。GitHub 的 PR 對(duì)象有一個(gè)mergeable字段但它的狀態(tài)有時(shí)候是None這表示 GitHub 還在后臺(tái)計(jì)算沖突。你在自動(dòng)合并前必須輪詢等待這個(gè)字段變成明確的True或False不能直接判斷。我見過一個(gè)很常見的 bug腳本看到mergeable是None就直接跳過了導(dǎo)致該合并的 PR 沒合。自動(dòng)合并的條件我設(shè)置成兩個(gè)硬門檻倉(cāng)庫(kù)所有狀態(tài)檢查全部通過PR 基礎(chǔ)分支是最新的。滿足這兩個(gè)條件后我會(huì)調(diào)用 GitHub 的合并接口使用 squash merge 策略把分支上所有提交壓成一個(gè)干凈提交合入主干?！翱倢?dǎo)演”到這里就完成了從任務(wù)到 PR 合并的閉環(huán)。3.5 第五步給團(tuán)隊(duì)留一道人工閘門看到這里你可能會(huì)問全自動(dòng)合并風(fēng)險(xiǎn)是不是太大了我的做法是在自動(dòng)合并前增加一個(gè)可跳過的人工確認(rèn)步驟用“LGTM 評(píng)論觸發(fā)合并”的方式給團(tuán)隊(duì)留一道閘門。具體機(jī)制AI 代理創(chuàng)建 PR 后在 PR 評(píng)論里寫一句“測(cè)試全綠確認(rèn)合并請(qǐng)回復(fù) LGTM”。然后我再掛一個(gè)監(jiān)聽 issue_comment 的 workflow只有當(dāng)評(píng)論作者在維護(hù)者白名單里且評(píng)論內(nèi)容是 LGTM 時(shí)才真正調(diào)用自動(dòng)合并接口。這個(gè)設(shè)計(jì)保留了標(biāo)題里“一鍵搞定”的體驗(yàn)但把最終決定權(quán)留在人手里。對(duì)于完全信任的、低風(fēng)險(xiǎn)的任務(wù)可以通過倉(cāng)庫(kù)變量AUTO_MERGE_LEVEL把它設(shè)成兩個(gè)模式semi需要人工 LGTMfull則只要測(cè)試全綠就自動(dòng)合并。我的建議是默認(rèn)永遠(yuǎn)用semi除非你跑完評(píng)測(cè)、對(duì)某個(gè)倉(cāng)庫(kù)的模型輸出非常放心了再考慮放開。4. 踩坑記錄與排查清單從理論到落地總有些坑只有真跑過才會(huì)遇到。在這兩個(gè)星期里我把遇到的問題按照出現(xiàn)頻率排了個(gè)序也整理了對(duì)應(yīng)的解決方法和排查思路這部分的價(jià)值不亞于前面的搭建過程。4.1 補(bǔ)丁格式錯(cuò)亂導(dǎo)致的反復(fù)修復(fù)第一次設(shè)計(jì)時(shí)我讓模型直接輸出 git diff 文本然后由腳本調(diào)git apply去應(yīng)用。想法是好的但實(shí)際操作中模型的 diff 輸出經(jīng)常出問題行號(hào)對(duì)不上、上下文行有缺失、文件路徑寫錯(cuò)導(dǎo)致補(bǔ)丁被拒絕。出錯(cuò)之后還得重新生成成本高、體驗(yàn)差。后來我換了一個(gè)思路不再讓模型輸出 diff而是直接輸出每個(gè)文件的完整內(nèi)容。在 JSON 結(jié)果里指定path和content由腳本直接把內(nèi)容覆蓋到對(duì)應(yīng)文件上。這個(gè)改動(dòng)一下就把“補(bǔ)丁失敗”這類問題基本消滅了。代價(jià)是傳輸?shù)膬?nèi)容變多了但換來的是穩(wěn)定性和可控性非常劃算。4.2 任務(wù)拆解不完整的問題AI 解析任務(wù)時(shí)最典型的問題是“只看表面不看全局”。比如你讓它“加一個(gè)接口”它可能只改了接口文件卻忘了在路由注冊(cè)處加映射你讓它“優(yōu)化某個(gè)函數(shù)”它可能把這個(gè)函數(shù)涉及的外部調(diào)用方完全忽略。我的解決方式是在解析階段增加“文件影響范圍”約束。提示詞里強(qiáng)制要求模型對(duì)每個(gè)改動(dòng)文件給出“為什么改這個(gè)文件”的理由并輸出一個(gè) checklist說明這個(gè)改動(dòng)可能影響哪些現(xiàn)有文件。腳本會(huì)拿著這個(gè) checklist 和模型準(zhǔn)備修改的文件列表做交叉驗(yàn)證不一致時(shí)直接讓模型重新解析。這相當(dāng)于給任務(wù)解析加了一層自檢邏輯。4.3 存在感極強(qiáng)的“分支過期”另一個(gè)高頻問題Agent 從創(chuàng)建分支到最終合并之間主干分支可能已經(jīng)被其他 PR 推進(jìn)了好幾個(gè)提交。GitHub 會(huì)因此把 PR 標(biāo)記為mergeablefalse自動(dòng)合并直接失敗。這個(gè)問題的排查思路很明確合并前檢查 PR 基礎(chǔ)分支是不是最新如果不是用 GitHub API 的 update branch 功能先把目標(biāo)分支合進(jìn)來再重新跑測(cè)試。但如果每次都是人工去點(diǎn)“Update branch”那自動(dòng)化就不徹底了。所以我在 workflow 里加了一小段邏輯在輪詢mergeable狀態(tài)之前先檢查 PR 的 head 分支是否落后于 base 分支落后就自動(dòng)執(zhí)行 update。不過要注意更新分支后需要重新等待一輪狀態(tài)檢查輪詢時(shí)間要留足。4.4 安全與權(quán)限相關(guān)的坑最后是關(guān)于權(quán)限的坑。我的第一條血淚教訓(xùn)是GitHub Actions 自帶的GITHUB_TOKEN雖然方便但它的默認(rèn)權(quán)限是受限的而且如果倉(cāng)庫(kù)的 Actions 設(shè)置開了“read-only”你連創(chuàng)建 PR 都做不到。更安全可控的方式是用一個(gè)專門的機(jī)器人賬號(hào) PAT然后把 Token 放進(jìn) Secrets。第二條是路徑過濾問題。AI 生成的代碼里如果出現(xiàn).github/workflows/這種路徑我是直接拒絕的。因?yàn)楣ぷ髁魑募坏┍桓牡扔诎褌}(cāng)庫(kù)的自動(dòng)化防線也一起改了。我在腳本里維護(hù)了一個(gè)禁止 AI 觸碰的路徑列表包含工作流目錄、安全相關(guān)配置、密鑰文件等一旦校驗(yàn)發(fā)現(xiàn)模型要改這些路徑立即終止流程并報(bào)警。順帶說一句抓日志非常重要。我給 Agent 執(zhí)行器的每一步都加了詳細(xì)日志輸出包括模型返回的原始 JSON、重試次數(shù)、測(cè)試輸出。因?yàn)槟Ｐ蜕墒遣豢深A(yù)測(cè)的沒有日志就無從排查。下面給一個(gè)常見問題速查表方便你以后排查現(xiàn)象可能原因排查與解決流程停在上一步?jīng)]有 PR 創(chuàng)建測(cè)試 job 失敗或狀態(tài)檢查未通過查看 Actions 日志定位測(cè)試失敗原因模型重試次數(shù)用盡任務(wù)描述太模糊或代碼生成質(zhì)量差檢查 Issue 是否滿足模板要求人工介入PR 顯示 mergeablefalse基礎(chǔ)分支過期或合并沖突在 workflow 里加自動(dòng) update branch自動(dòng)合并未觸發(fā)缺少 LGTM 評(píng)論或評(píng)論者不在白名單確認(rèn)白名單配置補(bǔ)充 LGTM 評(píng)論模型試圖修改敏感路徑提示詞約束不足檢查路徑過濾列表是否生效4.5 模型選的不好后續(xù)全是事最后補(bǔ)一個(gè)代碼之外的坑模型選型直接決定整條鏈路的成功率。有些模型寫點(diǎn)示例代碼是沒問題一旦面對(duì)倉(cāng)庫(kù)級(jí)任務(wù)、長(zhǎng)上下文、多文件改動(dòng)的場(chǎng)景輸出質(zhì)量立刻崩盤。我做過一次簡(jiǎn)短的橫向?qū)Ρ劝淹粋€(gè) Issue 分別扔給三個(gè)主流模型成功率能從六成拉到九成差距很明顯。我的建議是在正式接入流程前先準(zhǔn)備一份“驗(yàn)收測(cè)試集”。從自己倉(cāng)庫(kù)里挑十來個(gè)典型需求讓候選模型在低風(fēng)險(xiǎn)的分支上跑一輪以“一次通過率”和“重試次數(shù)”兩個(gè)指標(biāo)做篩選。能跑過這套測(cè)試集的模型再放進(jìn)正式 workflow別拿正式任務(wù)當(dāng)模型評(píng)測(cè)場(chǎng)。5. 最終效果與可以繼續(xù)擴(kuò)展的地方這套系統(tǒng)跑了兩周我用一個(gè)中等規(guī)模的后端倉(cāng)庫(kù)做了試驗(yàn)總共產(chǎn)出約 30 個(gè)任務(wù) PR。其中約 20 個(gè)是一次通過5 個(gè)經(jīng)過模型自行重試后通過3 個(gè)需要人工小修后通過2 個(gè)因?yàn)槿蝿?wù)需求本身過于模糊被退回。整體體驗(yàn)是它不能完全替代開發(fā)但能替團(tuán)隊(duì)接住大量重復(fù)性、樣板式的工作。5.1 實(shí)際跑了兩周后我的真實(shí)體感先說收益。團(tuán)隊(duì)里那些“加一個(gè)接口”“補(bǔ)一個(gè)單測(cè)”“重構(gòu)某處重復(fù)代碼”一類的低風(fēng)險(xiǎn)任務(wù)現(xiàn)在基本都是 AI 代理在處理。以前一個(gè)小任務(wù)從認(rèn)領(lǐng)到提 PR至少要花半天工夫現(xiàn)在往往十幾分鐘就出一個(gè)可評(píng)審的 PR。這種把重復(fù)勞動(dòng)從開發(fā)者的待辦列表里拿掉的感覺是這套系統(tǒng)最值錢的地方。再說局限。模型在處理跨模塊、涉及大量既有邏輯的任務(wù)時(shí)仍然經(jīng)常翻車。尤其是那些需要“讀懂整個(gè)業(yè)務(wù)背景”才能做對(duì)的需求AI 的完成質(zhì)量很不穩(wěn)定人工評(píng)審的成本自然就高。另外PR 合并后如果測(cè)試覆蓋不全問題不會(huì)立刻暴露可能等到上線前才發(fā)現(xiàn)。這意味著自動(dòng)化流程必須和測(cè)試覆蓋率綁定覆蓋率太低的任務(wù)不該放開自動(dòng)合并。5.2 后續(xù)還可以擴(kuò)展的四個(gè)方向這套框架后續(xù)還有幾個(gè)我可以明確看到的方向。第一個(gè)方向是依賴圖感知在任務(wù)解析階段引入倉(cāng)庫(kù)的依賴關(guān)系讓 AI 一眼看出改一個(gè)文件會(huì)影響哪些下游模塊。第二個(gè)方向是多模型投票同一任務(wù)讓兩個(gè)不同模型各自生成方案由自動(dòng)對(duì)比器選出更優(yōu)版本適合高風(fēng)險(xiǎn)改動(dòng)。第三個(gè)方向是自動(dòng)回滾把 PR 合并后的線上監(jiān)控接進(jìn)來監(jiān)控指標(biāo)異常時(shí)自動(dòng) revert 對(duì)應(yīng) PR形成更完整的閉環(huán)。第四個(gè)方向是把流程從代碼倉(cāng)庫(kù)延伸到文檔和配置領(lǐng)域比如自動(dòng)生成變更記錄、更新接口文檔、同步環(huán)境配置。這幾個(gè)方向都不需要推翻現(xiàn)有架構(gòu)只是在已有流水線上再疊加新的能力層。如果你也準(zhǔn)備動(dòng)手搭一個(gè)類似的 AI 編碼代理工作流我的建議是不要貪多。先把“任務(wù)解析、代碼生成、測(cè)試校驗(yàn)、PR 合并”這四段基礎(chǔ)鏈路跑穩(wěn)再考慮加花活。自動(dòng)化流程最怕的不是功能少而是每個(gè)環(huán)節(jié)都不可靠。踏踏實(shí)實(shí)把每一段的校驗(yàn)和日志做扎實(shí)這個(gè)“總導(dǎo)演”才能真正成為團(tuán)隊(duì)里得力的幫手。