如果你每天跟代码仓库打交道应该能明显感觉到现在的 AI 编码代理写代码早就不是新鲜事了真正难的是把“写完的代码”一路送到 PR 合并。无论是企业内部的评审规范还是开源仓库的分支保护都意味着你不能让模型生成完代码就撒手不管。我今天想聊的这套小系统就是一位“总导演”它接收一个 Issue自己拆任务、自己写代码、自己跑测试、自己建 PR甚至在满足条件时自己完成 PR 合并。整个过程只要在 Issue 上打一个标签剩下的大多数事情都由工作流自动接管。这套方案适合谁如果你正在用 AI 辅助编程但发现“生成代码挺好、一提 PR 就全卡住”如果你在运维一个小团队希望把重复性的例行需求自动化或者你只是好奇“从任务描述到 PR 合并”这条链路到底能自动化到什么程度这篇都值得往下看。我搭这套东西不是为了炫技而是真的在内部项目里跑了两个星期踩过不少坑最后沉淀出一套可以直接抄作业的方案。1. 先想清楚“总导演”到底执导什么很多 AI 编码工具解决的是“单个文件”的问题但真正到项目交付你面对的是“一条流程”。流程中有任务描述、代码结构、测试约束、分支规范、评审意见一个都不能少。标题里说的“总导演”指的就是把这套流程串起来的人——虽然执行者是 AI但真正让任务能走进 PR 合并靠的是流程编排。1.1 流程全貌从 Issue 到合并的一条龙链路我先画一下链路简单说就是开发者在 Issue 里写清楚需求打上一个约定好的标签工作流被触发后AI 代理先把 Issue 内容解析成结构化任务再根据仓库当前的代码生成补丁随后在隔离环境里跑测试和静态检查全部通过后创建新分支并提交 PR最后在满足分支保护条件的情况下完成合并。也就是说这条链路里的“输入”是自然语言任务“输出”是合并进主干分支的代码。整条链路由三块拼成任务理解、代码执行、质量校验。任务理解负责把模糊的中文或英文需求变成可执行的改动清单代码执行负责真正写代码和改文件质量校验负责把不达标的代码拦在门外。这个过程最核心的难点不在“让模型写代码”而在“让模型理解它正在参与一个真实项目”。真实项目有目录结构、有已有代码风格、有测试约定如果模型只是凭空生成代码而不考虑这些上下文最后的结果基本不能用。所以整个流程设计的第一原则就是把上下文喂够把校验做成硬门槛。1.2 单 Agent 会话 vs 项目级工作流以前我们用 AI 编码代理通常是开一个对话窗口把需求粘进去然后等它给出代码片段。这种“单 Agent 会话”模式对一次性提问够用但它天然缺三样东西一是没法访问仓库全貌二是没法在真实环境里验证生成结果三是没法把结果自动送进评审和合并流程。我这次想做的“项目级工作流”本质上就是把原来的“对话窗口”变成“后台执行器”。AI 代理不再只面对一段话而是面对一个完整任务。它需要自己决定改哪些文件、测试怎么跑、PR 怎么写甚至要自己处理 CI 报错后的重试。这对模型能力的要求高了不少但对使用者的要求反而降低了——你只需要会提需求。从实际效果看这两种模式带来的体感差别非常大。对话模式是“AI 给你答案”项目级工作流是“AI 给你交付”。前者把思考留给了人后者把执行流程也接了过去。当然代价就是搭建成本高后面我会逐步拆解。1.3 我对方案选型的关键判断市面上已经有不少成熟的一键 PR 工具和 AI 编程助手那我为什么还要自己拼一套关键原因是我需要可控性。AI 编码代理和 PR 合并是两套系统直接用成品工具有时候很难把组织内部的测试规范、分支保护规则、评审流程整套揉进去。自己拼装这套流程的好处首先是把“模型”这个环节设计成可替换的。今天我可能用某个模型明天如果评测下来另一个模型在特定任务上更稳我可以直接在配置里切换而不需要动整个流水线。其次整个流程的每一步都可以插桩、打日志、设权限。比如“哪些路径不允许 AI 改动”这类安全策略在成品工具里不一定能精细控制。所以我的结论是不要盲目追求“全自动”而是把自动化做成“有监督的可控流水线”。AI 负责干活人负责确认边界。这也是为什么我在设计里保留了人工闸门后面的实操部分会详细讲。2. 架构设计与工具选型项目级工作流不是写一个大脚本硬跑而是要有明确的层次划分。我最终采用的是三层结构任务解析层、编码执行层、质量校验层。每层只做自己该做的事层与层之间通过 JSON 传递结构化数据而不是靠粘贴复制文本这就避免了很多格式解析上的麻烦。2.1 三层架构解析、执行、校验任务解析层做的是“把 Issue 的自然语言变成机器可读的改动意图”。这一层我用的还是 AI 模型但输出不是代码而是 JSON 结构。结构里包含任务目标、涉及的技术栈、验收标准和待改动文件列表。这样做的目的是让后面两层有一个稳定的输入格式而不是每次都去啃一段长文本。编码执行层是最容易出现惊喜的地方。它负责根据解析结果生成具体的文件改动同样以 JSON 输出路径是什么、内容是新增还是修改、应该改成什么样。拿到这个 JSON 后脚本才真正往工作区写文件。这里有个关键点模型直接生成完整文件内容比生成 git diff 补丁要稳得多后面踩坑部分我会展开。质量校验层则是把 AI 生成的代码放进真实的测试环境里跑一遍。静态检查、单元测试、编译、构建该跑的都跑。只有这一层全绿了流程才会继续走向创建 PR。没有这层校验的 AI 编码代理基本就是裸奔。2.2 模型接入统一协议带来的灵活度模型接入方面我强烈建议只做“兼容 OpenAI 协议的 API”对接。理由很简单这类协议的生态最成熟SDK 稳定切换模型时基本不用改代码。我内部搭了一个统一的模型网关网关背后接的是公司合规允许使用的各类模型服务模型名字写进配置文件就行。你需要准备的核心参数只有四个模型名称、API Key、Base URL、超时时间。在 Python 代码里一套 Client 可以通吃。选用模型时我重点看三项能力长上下文理解力、代码生成正确率、对 JSON 结构化输出格式的遵循程度。长上下文能力尤其重要因为你要把仓库目录结构、关键文件内容、任务描述全部塞进提示词里上下文不够就会丢失关键信息。成本方面不用被“AI 跑流程很贵”吓到。从我实际账单看一个中等复杂度的任务大约消耗 100 万到 200 万 token按目前主流 API 的定价换算大概在几元到十几元之间。相比一个初级开发干半天才能真正交付一个 PR这个成本可以接受。2.3 仓库保护规则与 Token 权限边界这是整条链路设计里我最看重的一环。自动合并 PR 的前提是仓库本身有保护规则兜底。我建议在主干分支上强制开启两个规则一是禁止直接推送只能通过 PR 合入二是要求 PR 在合并前必须通过所有状态检查。这两条是避免 AI 代理把仓库搞乱的安全底牌。Token 权限要按最小化原则配置。我用的是仓库级 Personal Access Token只勾选跟 PR 和 Issue 相关的权限比如读取 Issue、创建分支、创建 PR、评论。绝不给它管理员权限也绝不让它具备直接修改主干分支保护规则的权限。这样即使模型生成的代码有问题或者 Agent 行为出现异常它也只能在划定的跑道里折腾翻不了天。实际操作中我见过很多团队为了方便把高权限 Token 直接写进 workflow这非常危险。一旦 Token 泄露等于整个仓库裸奔。正确做法是把 Token 存进仓库或组织的 Secrets 里在 workflow 中通过环境变量注入并且定期轮换。我会在实操流程里再强调一次。3. 实操把流程从零搭起来理论讲完直接进实操。我假设你用的是 GitHub 和 GitHub Actions因为这套组合完全不限制模型来源内部网关可以管住调用权限非常适合做 AI 编码代理工作流。下面五个步骤是我跑通后又简化过的版本每一步都保留了必要的验证节点。3.1 第一步定义任务流转的“入口单据”整个流程以 Issue 为入口所以第一步是给 Issue 定格式。一次理想的任务描述至少要有四个部分目标背景、需求明细、验收标准、技术约束。我把模板直接存成.github/ISSUE_TEMPLATE/agent_task.yml这样开发者新建 Issue 时会自动带出结构。模板示例name: Agent Task description: 给 AI 编码代理分配一个可自动执行的开发任务 title: [Agent] labels: [agent] body: - type: textarea id: background attributes: label: 任务背景 placeholder: 为什么需要这个改动 validations: required: true - type: textarea id: requirement attributes: label: 需求明细 placeholder: 具体要做什么尽量拆成条目。 validations: required: true - type: textarea id: acceptance attributes: label: 验收标准 placeholder: 什么样的结果算完成 validations: required: true - type: input id: tech_stack attributes: label: 技术栈约束 description: 例如后端 Python 3.12、前端 Vue、数据库 MySQL 等不要小看这个模板的作用。任务解析层能不能稳定输出 JSON很大程度上取决于源文本是否结构清晰。模板强制写作者把需求拆成条目AI 解析时就不容易遗漏关键点。我试过不限制格式的自由输入最后解析质量波动非常大。当 Issue 创建后开发者或维护者手动给它打上agent标签。这个标签就是启动信号。选择手动打标签而不是自动触发是为了避免任何 Issue 创建都让 AI 去跑一遍——那样既浪费成本也容易把无关讨论带入执行流程。3.2 第二步写 Agent 执行器Agent 执行器是整个工作流的大脑。我用 Python 来写核心依赖只有两个OpenAI 兼容客户端和 PyGithub。下面这段代码是执行器的骨架它会完成读取 Issue、调用模型解析任务、生成文件改动、写入分支这一整套动作。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 你是仓库 {REPO_NAME} 的 AI 开发总导演。 请根据 Issue 内容理解仓库结构输出 JSON {{ summary: 一句话总结, tech_stack: 技术栈, acceptance_criteria: [], files: [{{path: , action: create|modify|delete, description: }}] }} 仓库文件树{tree[:6000]} Issue 内容{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: 你只输出严格 JSON。}, {role: user, content: prompt}, ], ) return json.loads(resp.choices[0].message.content) # 2. 解析任务 plan call_model(build_task_prompt(issue.body), None) # 3. 生成代码用完整文件内容而不是 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, 模型在代码生成阶段重试次数用尽请人工介入。) raise SystemExit(1) # 4. 创建分支并写入文件 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))这里有三点值得说明。第一提示词里我塞入了仓库文件树但只截断 6000 字符避免上下文过长导致模型抓不住重点。第二模型生成文件的过程中加了MAX_RETRY循环如果校验不通过就让它自己重新输出最多重试三次三次不行就停止并通知人工。第三写分支时只用仓库级 Token 能操作的 API全程不碰本地 Git 命令避免因为权限问题在 CI 环境里卡住。3.3 第三步在不信任的代码上跑测试AI 生成的代码默认是不可信的。所以在把代码送到主干之前必须把它放进隔离环境里跑一遍完整校验。我这里说的隔离环境就是 GitHub Actions 的 runner 容器。每一步安装依赖和跑测试都不直接作用在你本机而是在一个全新的环境中完成天然具备隔离性。在 CI 里跑测试的核心 workflow 长这样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: 执行 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 }}下一步是在新分支上跑测试。测试阶段我会专门用一个独立 job确保只有测试通过后才会继续后续步骤。这一步用仓库自带的 Actions 就够了关键在于把if: success()条件加在后续创建 PR 的步骤上让测试失败时流程直接中断PR 永远不会被创建。再补充一个很容易忽略的点依赖安装阶段不要图省事直接pip install -r requirements.txtAI 生成的代码经常会新增第三方依赖所以要在 Agent 执行阶段先把requirements.txt里的改动写进去然后在测试 job 里重新安装。如果不这样做可能出现“本地测试过了、CI 里缺包”的尴尬情况。3.4 第四步PR 创建与自动合并测试全绿后就进入 PR 阶段。创建 PR 时我会让模型写一段 PR 描述但题目和描述框架由我们预先定义好避免模型自由发挥。PR 标题统一带上 Issue 编号描述里固定包含“任务来源”“改动摘要”“测试说明”三个区块这样评审人打开 PR 就能快速理解上下文。创建 PR 的代码很直接pr repo.create_pull( titlef Agent 自动 PR: #{issue.number} {plan[summary]}, bodybuild_pr_body(issue, plan, result), headfagent/issue-{issue.number}, baseTARGET_BRANCH, )真正需要小心的是“自动合并”这一步。GitHub 的 PR 对象有一个mergeable字段但它的状态有时候是None这表示 GitHub 还在后台计算冲突。你在自动合并前必须轮询等待这个字段变成明确的True或False不能直接判断。我见过一个很常见的 bug脚本看到mergeable是None就直接跳过了导致该合并的 PR 没合。自动合并的条件我设置成两个硬门槛仓库所有状态检查全部通过PR 基础分支是最新的。满足这两个条件后我会调用 GitHub 的合并接口使用 squash merge 策略把分支上所有提交压成一个干净提交合入主干。“总导演”到这里就完成了从任务到 PR 合并的闭环。3.5 第五步给团队留一道人工闸门看到这里你可能会问全自动合并风险是不是太大了我的做法是在自动合并前增加一个可跳过的人工确认步骤用“LGTM 评论触发合并”的方式给团队留一道闸门。具体机制AI 代理创建 PR 后在 PR 评论里写一句“测试全绿确认合并请回复 LGTM”。然后我再挂一个监听 issue_comment 的 workflow只有当评论作者在维护者白名单里且评论内容是 LGTM 时才真正调用自动合并接口。这个设计保留了标题里“一键搞定”的体验但把最终决定权留在人手里。对于完全信任的、低风险的任务可以通过仓库变量AUTO_MERGE_LEVEL把它设成两个模式semi需要人工 LGTMfull则只要测试全绿就自动合并。我的建议是默认永远用semi除非你跑完评测、对某个仓库的模型输出非常放心了再考虑放开。4. 踩坑记录与排查清单从理论到落地总有些坑只有真跑过才会遇到。在这两个星期里我把遇到的问题按照出现频率排了个序也整理了对应的解决方法和排查思路这部分的价值不亚于前面的搭建过程。4.1 补丁格式错乱导致的反复修复第一次设计时我让模型直接输出 git diff 文本然后由脚本调git apply去应用。想法是好的但实际操作中模型的 diff 输出经常出问题行号对不上、上下文行有缺失、文件路径写错导致补丁被拒绝。出错之后还得重新生成成本高、体验差。后来我换了一个思路不再让模型输出 diff而是直接输出每个文件的完整内容。在 JSON 结果里指定path和content由脚本直接把内容覆盖到对应文件上。这个改动一下就把“补丁失败”这类问题基本消灭了。代价是传输的内容变多了但换来的是稳定性和可控性非常划算。4.2 任务拆解不完整的问题AI 解析任务时最典型的问题是“只看表面不看全局”。比如你让它“加一个接口”它可能只改了接口文件却忘了在路由注册处加映射你让它“优化某个函数”它可能把这个函数涉及的外部调用方完全忽略。我的解决方式是在解析阶段增加“文件影响范围”约束。提示词里强制要求模型对每个改动文件给出“为什么改这个文件”的理由并输出一个 checklist说明这个改动可能影响哪些现有文件。脚本会拿着这个 checklist 和模型准备修改的文件列表做交叉验证不一致时直接让模型重新解析。这相当于给任务解析加了一层自检逻辑。4.3 存在感极强的“分支过期”另一个高频问题Agent 从创建分支到最终合并之间主干分支可能已经被其他 PR 推进了好几个提交。GitHub 会因此把 PR 标记为mergeablefalse自动合并直接失败。这个问题的排查思路很明确合并前检查 PR 基础分支是不是最新如果不是用 GitHub API 的 update branch 功能先把目标分支合进来再重新跑测试。但如果每次都是人工去点“Update branch”那自动化就不彻底了。所以我在 workflow 里加了一小段逻辑在轮询mergeable状态之前先检查 PR 的 head 分支是否落后于 base 分支落后就自动执行 update。不过要注意更新分支后需要重新等待一轮状态检查轮询时间要留足。4.4 安全与权限相关的坑最后是关于权限的坑。我的第一条血泪教训是GitHub Actions 自带的GITHUB_TOKEN虽然方便但它的默认权限是受限的而且如果仓库的 Actions 设置开了“read-only”你连创建 PR 都做不到。更安全可控的方式是用一个专门的机器人账号 PAT然后把 Token 放进 Secrets。第二条是路径过滤问题。AI 生成的代码里如果出现.github/workflows/这种路径我是直接拒绝的。因为工作流文件一旦被改等于把仓库的自动化防线也一起改了。我在脚本里维护了一个禁止 AI 触碰的路径列表包含工作流目录、安全相关配置、密钥文件等一旦校验发现模型要改这些路径立即终止流程并报警。顺带说一句抓日志非常重要。我给 Agent 执行器的每一步都加了详细日志输出包括模型返回的原始 JSON、重试次数、测试输出。因为模型生成是不可预测的没有日志就无从排查。下面给一个常见问题速查表方便你以后排查现象可能原因排查与解决流程停在上一步没有 PR 创建测试 job 失败或状态检查未通过查看 Actions 日志定位测试失败原因模型重试次数用尽任务描述太模糊或代码生成质量差检查 Issue 是否满足模板要求人工介入PR 显示 mergeablefalse基础分支过期或合并冲突在 workflow 里加自动 update branch自动合并未触发缺少 LGTM 评论或评论者不在白名单确认白名单配置补充 LGTM 评论模型试图修改敏感路径提示词约束不足检查路径过滤列表是否生效4.5 模型选的不好后续全是事最后补一个代码之外的坑模型选型直接决定整条链路的成功率。有些模型写点示例代码是没问题一旦面对仓库级任务、长上下文、多文件改动的场景输出质量立刻崩盘。我做过一次简短的横向对比把同一个 Issue 分别扔给三个主流模型成功率能从六成拉到九成差距很明显。我的建议是在正式接入流程前先准备一份“验收测试集”。从自己仓库里挑十来个典型需求让候选模型在低风险的分支上跑一轮以“一次通过率”和“重试次数”两个指标做筛选。能跑过这套测试集的模型再放进正式 workflow别拿正式任务当模型评测场。5. 最终效果与可以继续扩展的地方这套系统跑了两周我用一个中等规模的后端仓库做了试验总共产出约 30 个任务 PR。其中约 20 个是一次通过5 个经过模型自行重试后通过3 个需要人工小修后通过2 个因为任务需求本身过于模糊被退回。整体体验是它不能完全替代开发但能替团队接住大量重复性、样板式的工作。5.1 实际跑了两周后我的真实体感先说收益。团队里那些“加一个接口”“补一个单测”“重构某处重复代码”一类的低风险任务现在基本都是 AI 代理在处理。以前一个小任务从认领到提 PR至少要花半天工夫现在往往十几分钟就出一个可评审的 PR。这种把重复劳动从开发者的待办列表里拿掉的感觉是这套系统最值钱的地方。再说局限。模型在处理跨模块、涉及大量既有逻辑的任务时仍然经常翻车。尤其是那些需要“读懂整个业务背景”才能做对的需求AI 的完成质量很不稳定人工评审的成本自然就高。另外PR 合并后如果测试覆盖不全问题不会立刻暴露可能等到上线前才发现。这意味着自动化流程必须和测试覆盖率绑定覆盖率太低的任务不该放开自动合并。5.2 后续还可以扩展的四个方向这套框架后续还有几个我可以明确看到的方向。第一个方向是依赖图感知在任务解析阶段引入仓库的依赖关系让 AI 一眼看出改一个文件会影响哪些下游模块。第二个方向是多模型投票同一任务让两个不同模型各自生成方案由自动对比器选出更优版本适合高风险改动。第三个方向是自动回滚把 PR 合并后的线上监控接进来监控指标异常时自动 revert 对应 PR形成更完整的闭环。第四个方向是把流程从代码仓库延伸到文档和配置领域比如自动生成变更记录、更新接口文档、同步环境配置。这几个方向都不需要推翻现有架构只是在已有流水线上再叠加新的能力层。如果你也准备动手搭一个类似的 AI 编码代理工作流我的建议是不要贪多。先把“任务解析、代码生成、测试校验、PR 合并”这四段基础链路跑稳再考虑加花活。自动化流程最怕的不是功能少而是每个环节都不可靠。踏踏实实把每一段的校验和日志做扎实这个“总导演”才能真正成为团队里得力的帮手。 AI编码代理自动化工作流：从Issue到PR合并的全流程实践
如果你每天跟代码仓库打交道应该能明显感觉到现在的 AI 编码代理写代码早就不是新鲜事了真正难的是把“写完的代码”一路送到 PR 合并。无论是企业内部的评审规范还是开源仓库的分支保护都意味着你不能让模型生成完代码就撒手不管。我今天想聊的这套小系统就是一位“总导演”它接收一个 Issue自己拆任务、自己写代码、自己跑测试、自己建 PR甚至在满足条件时自己完成 PR 合并。整个过程只要在 Issue 上打一个标签剩下的大多数事情都由工作流自动接管。这套方案适合谁如果你正在用 AI 辅助编程但发现“生成代码挺好、一提 PR 就全卡住”如果你在运维一个小团队希望把重复性的例行需求自动化或者你只是好奇“从任务描述到 PR 合并”这条链路到底能自动化到什么程度这篇都值得往下看。我搭这套东西不是为了炫技而是真的在内部项目里跑了两个星期踩过不少坑最后沉淀出一套可以直接抄作业的方案。1. 先想清楚“总导演”到底执导什么很多 AI 编码工具解决的是“单个文件”的问题但真正到项目交付你面对的是“一条流程”。流程中有任务描述、代码结构、测试约束、分支规范、评审意见一个都不能少。标题里说的“总导演”指的就是把这套流程串起来的人——虽然执行者是 AI但真正让任务能走进 PR 合并靠的是流程编排。1.1 流程全貌从 Issue 到合并的一条龙链路我先画一下链路简单说就是开发者在 Issue 里写清楚需求打上一个约定好的标签工作流被触发后AI 代理先把 Issue 内容解析成结构化任务再根据仓库当前的代码生成补丁随后在隔离环境里跑测试和静态检查全部通过后创建新分支并提交 PR最后在满足分支保护条件的情况下完成合并。也就是说这条链路里的“输入”是自然语言任务“输出”是合并进主干分支的代码。整条链路由三块拼成任务理解、代码执行、质量校验。任务理解负责把模糊的中文或英文需求变成可执行的改动清单代码执行负责真正写代码和改文件质量校验负责把不达标的代码拦在门外。这个过程最核心的难点不在“让模型写代码”而在“让模型理解它正在参与一个真实项目”。真实项目有目录结构、有已有代码风格、有测试约定如果模型只是凭空生成代码而不考虑这些上下文最后的结果基本不能用。所以整个流程设计的第一原则就是把上下文喂够把校验做成硬门槛。1.2 单 Agent 会话 vs 项目级工作流以前我们用 AI 编码代理通常是开一个对话窗口把需求粘进去然后等它给出代码片段。这种“单 Agent 会话”模式对一次性提问够用但它天然缺三样东西一是没法访问仓库全貌二是没法在真实环境里验证生成结果三是没法把结果自动送进评审和合并流程。我这次想做的“项目级工作流”本质上就是把原来的“对话窗口”变成“后台执行器”。AI 代理不再只面对一段话而是面对一个完整任务。它需要自己决定改哪些文件、测试怎么跑、PR 怎么写甚至要自己处理 CI 报错后的重试。这对模型能力的要求高了不少但对使用者的要求反而降低了——你只需要会提需求。从实际效果看这两种模式带来的体感差别非常大。对话模式是“AI 给你答案”项目级工作流是“AI 给你交付”。前者把思考留给了人后者把执行流程也接了过去。当然代价就是搭建成本高后面我会逐步拆解。1.3 我对方案选型的关键判断市面上已经有不少成熟的一键 PR 工具和 AI 编程助手那我为什么还要自己拼一套关键原因是我需要可控性。AI 编码代理和 PR 合并是两套系统直接用成品工具有时候很难把组织内部的测试规范、分支保护规则、评审流程整套揉进去。自己拼装这套流程的好处首先是把“模型”这个环节设计成可替换的。今天我可能用某个模型明天如果评测下来另一个模型在特定任务上更稳我可以直接在配置里切换而不需要动整个流水线。其次整个流程的每一步都可以插桩、打日志、设权限。比如“哪些路径不允许 AI 改动”这类安全策略在成品工具里不一定能精细控制。所以我的结论是不要盲目追求“全自动”而是把自动化做成“有监督的可控流水线”。AI 负责干活人负责确认边界。这也是为什么我在设计里保留了人工闸门后面的实操部分会详细讲。2. 架构设计与工具选型项目级工作流不是写一个大脚本硬跑而是要有明确的层次划分。我最终采用的是三层结构任务解析层、编码执行层、质量校验层。每层只做自己该做的事层与层之间通过 JSON 传递结构化数据而不是靠粘贴复制文本这就避免了很多格式解析上的麻烦。2.1 三层架构解析、执行、校验任务解析层做的是“把 Issue 的自然语言变成机器可读的改动意图”。这一层我用的还是 AI 模型但输出不是代码而是 JSON 结构。结构里包含任务目标、涉及的技术栈、验收标准和待改动文件列表。这样做的目的是让后面两层有一个稳定的输入格式而不是每次都去啃一段长文本。编码执行层是最容易出现惊喜的地方。它负责根据解析结果生成具体的文件改动同样以 JSON 输出路径是什么、内容是新增还是修改、应该改成什么样。拿到这个 JSON 后脚本才真正往工作区写文件。这里有个关键点模型直接生成完整文件内容比生成 git diff 补丁要稳得多后面踩坑部分我会展开。质量校验层则是把 AI 生成的代码放进真实的测试环境里跑一遍。静态检查、单元测试、编译、构建该跑的都跑。只有这一层全绿了流程才会继续走向创建 PR。没有这层校验的 AI 编码代理基本就是裸奔。2.2 模型接入统一协议带来的灵活度模型接入方面我强烈建议只做“兼容 OpenAI 协议的 API”对接。理由很简单这类协议的生态最成熟SDK 稳定切换模型时基本不用改代码。我内部搭了一个统一的模型网关网关背后接的是公司合规允许使用的各类模型服务模型名字写进配置文件就行。你需要准备的核心参数只有四个模型名称、API Key、Base URL、超时时间。在 Python 代码里一套 Client 可以通吃。选用模型时我重点看三项能力长上下文理解力、代码生成正确率、对 JSON 结构化输出格式的遵循程度。长上下文能力尤其重要因为你要把仓库目录结构、关键文件内容、任务描述全部塞进提示词里上下文不够就会丢失关键信息。成本方面不用被“AI 跑流程很贵”吓到。从我实际账单看一个中等复杂度的任务大约消耗 100 万到 200 万 token按目前主流 API 的定价换算大概在几元到十几元之间。相比一个初级开发干半天才能真正交付一个 PR这个成本可以接受。2.3 仓库保护规则与 Token 权限边界这是整条链路设计里我最看重的一环。自动合并 PR 的前提是仓库本身有保护规则兜底。我建议在主干分支上强制开启两个规则一是禁止直接推送只能通过 PR 合入二是要求 PR 在合并前必须通过所有状态检查。这两条是避免 AI 代理把仓库搞乱的安全底牌。Token 权限要按最小化原则配置。我用的是仓库级 Personal Access Token只勾选跟 PR 和 Issue 相关的权限比如读取 Issue、创建分支、创建 PR、评论。绝不给它管理员权限也绝不让它具备直接修改主干分支保护规则的权限。这样即使模型生成的代码有问题或者 Agent 行为出现异常它也只能在划定的跑道里折腾翻不了天。实际操作中我见过很多团队为了方便把高权限 Token 直接写进 workflow这非常危险。一旦 Token 泄露等于整个仓库裸奔。正确做法是把 Token 存进仓库或组织的 Secrets 里在 workflow 中通过环境变量注入并且定期轮换。我会在实操流程里再强调一次。3. 实操把流程从零搭起来理论讲完直接进实操。我假设你用的是 GitHub 和 GitHub Actions因为这套组合完全不限制模型来源内部网关可以管住调用权限非常适合做 AI 编码代理工作流。下面五个步骤是我跑通后又简化过的版本每一步都保留了必要的验证节点。3.1 第一步定义任务流转的“入口单据”整个流程以 Issue 为入口所以第一步是给 Issue 定格式。一次理想的任务描述至少要有四个部分目标背景、需求明细、验收标准、技术约束。我把模板直接存成.github/ISSUE_TEMPLATE/agent_task.yml这样开发者新建 Issue 时会自动带出结构。模板示例name: Agent Task description: 给 AI 编码代理分配一个可自动执行的开发任务 title: [Agent] labels: [agent] body: - type: textarea id: background attributes: label: 任务背景 placeholder: 为什么需要这个改动 validations: required: true - type: textarea id: requirement attributes: label: 需求明细 placeholder: 具体要做什么尽量拆成条目。 validations: required: true - type: textarea id: acceptance attributes: label: 验收标准 placeholder: 什么样的结果算完成 validations: required: true - type: input id: tech_stack attributes: label: 技术栈约束 description: 例如后端 Python 3.12、前端 Vue、数据库 MySQL 等不要小看这个模板的作用。任务解析层能不能稳定输出 JSON很大程度上取决于源文本是否结构清晰。模板强制写作者把需求拆成条目AI 解析时就不容易遗漏关键点。我试过不限制格式的自由输入最后解析质量波动非常大。当 Issue 创建后开发者或维护者手动给它打上agent标签。这个标签就是启动信号。选择手动打标签而不是自动触发是为了避免任何 Issue 创建都让 AI 去跑一遍——那样既浪费成本也容易把无关讨论带入执行流程。3.2 第二步写 Agent 执行器Agent 执行器是整个工作流的大脑。我用 Python 来写核心依赖只有两个OpenAI 兼容客户端和 PyGithub。下面这段代码是执行器的骨架它会完成读取 Issue、调用模型解析任务、生成文件改动、写入分支这一整套动作。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 你是仓库 {REPO_NAME} 的 AI 开发总导演。 请根据 Issue 内容理解仓库结构输出 JSON {{ summary: 一句话总结, tech_stack: 技术栈, acceptance_criteria: [], files: [{{path: , action: create|modify|delete, description: }}] }} 仓库文件树{tree[:6000]} Issue 内容{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: 你只输出严格 JSON。}, {role: user, content: prompt}, ], ) return json.loads(resp.choices[0].message.content) # 2. 解析任务 plan call_model(build_task_prompt(issue.body), None) # 3. 生成代码用完整文件内容而不是 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, 模型在代码生成阶段重试次数用尽请人工介入。) raise SystemExit(1) # 4. 创建分支并写入文件 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))这里有三点值得说明。第一提示词里我塞入了仓库文件树但只截断 6000 字符避免上下文过长导致模型抓不住重点。第二模型生成文件的过程中加了MAX_RETRY循环如果校验不通过就让它自己重新输出最多重试三次三次不行就停止并通知人工。第三写分支时只用仓库级 Token 能操作的 API全程不碰本地 Git 命令避免因为权限问题在 CI 环境里卡住。3.3 第三步在不信任的代码上跑测试AI 生成的代码默认是不可信的。所以在把代码送到主干之前必须把它放进隔离环境里跑一遍完整校验。我这里说的隔离环境就是 GitHub Actions 的 runner 容器。每一步安装依赖和跑测试都不直接作用在你本机而是在一个全新的环境中完成天然具备隔离性。在 CI 里跑测试的核心 workflow 长这样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: 执行 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 }}下一步是在新分支上跑测试。测试阶段我会专门用一个独立 job确保只有测试通过后才会继续后续步骤。这一步用仓库自带的 Actions 就够了关键在于把if: success()条件加在后续创建 PR 的步骤上让测试失败时流程直接中断PR 永远不会被创建。再补充一个很容易忽略的点依赖安装阶段不要图省事直接pip install -r requirements.txtAI 生成的代码经常会新增第三方依赖所以要在 Agent 执行阶段先把requirements.txt里的改动写进去然后在测试 job 里重新安装。如果不这样做可能出现“本地测试过了、CI 里缺包”的尴尬情况。3.4 第四步PR 创建与自动合并测试全绿后就进入 PR 阶段。创建 PR 时我会让模型写一段 PR 描述但题目和描述框架由我们预先定义好避免模型自由发挥。PR 标题统一带上 Issue 编号描述里固定包含“任务来源”“改动摘要”“测试说明”三个区块这样评审人打开 PR 就能快速理解上下文。创建 PR 的代码很直接pr repo.create_pull( titlef Agent 自动 PR: #{issue.number} {plan[summary]}, bodybuild_pr_body(issue, plan, result), headfagent/issue-{issue.number}, baseTARGET_BRANCH, )真正需要小心的是“自动合并”这一步。GitHub 的 PR 对象有一个mergeable字段但它的状态有时候是None这表示 GitHub 还在后台计算冲突。你在自动合并前必须轮询等待这个字段变成明确的True或False不能直接判断。我见过一个很常见的 bug脚本看到mergeable是None就直接跳过了导致该合并的 PR 没合。自动合并的条件我设置成两个硬门槛仓库所有状态检查全部通过PR 基础分支是最新的。满足这两个条件后我会调用 GitHub 的合并接口使用 squash merge 策略把分支上所有提交压成一个干净提交合入主干。“总导演”到这里就完成了从任务到 PR 合并的闭环。3.5 第五步给团队留一道人工闸门看到这里你可能会问全自动合并风险是不是太大了我的做法是在自动合并前增加一个可跳过的人工确认步骤用“LGTM 评论触发合并”的方式给团队留一道闸门。具体机制AI 代理创建 PR 后在 PR 评论里写一句“测试全绿确认合并请回复 LGTM”。然后我再挂一个监听 issue_comment 的 workflow只有当评论作者在维护者白名单里且评论内容是 LGTM 时才真正调用自动合并接口。这个设计保留了标题里“一键搞定”的体验但把最终决定权留在人手里。对于完全信任的、低风险的任务可以通过仓库变量AUTO_MERGE_LEVEL把它设成两个模式semi需要人工 LGTMfull则只要测试全绿就自动合并。我的建议是默认永远用semi除非你跑完评测、对某个仓库的模型输出非常放心了再考虑放开。4. 踩坑记录与排查清单从理论到落地总有些坑只有真跑过才会遇到。在这两个星期里我把遇到的问题按照出现频率排了个序也整理了对应的解决方法和排查思路这部分的价值不亚于前面的搭建过程。4.1 补丁格式错乱导致的反复修复第一次设计时我让模型直接输出 git diff 文本然后由脚本调git apply去应用。想法是好的但实际操作中模型的 diff 输出经常出问题行号对不上、上下文行有缺失、文件路径写错导致补丁被拒绝。出错之后还得重新生成成本高、体验差。后来我换了一个思路不再让模型输出 diff而是直接输出每个文件的完整内容。在 JSON 结果里指定path和content由脚本直接把内容覆盖到对应文件上。这个改动一下就把“补丁失败”这类问题基本消灭了。代价是传输的内容变多了但换来的是稳定性和可控性非常划算。4.2 任务拆解不完整的问题AI 解析任务时最典型的问题是“只看表面不看全局”。比如你让它“加一个接口”它可能只改了接口文件却忘了在路由注册处加映射你让它“优化某个函数”它可能把这个函数涉及的外部调用方完全忽略。我的解决方式是在解析阶段增加“文件影响范围”约束。提示词里强制要求模型对每个改动文件给出“为什么改这个文件”的理由并输出一个 checklist说明这个改动可能影响哪些现有文件。脚本会拿着这个 checklist 和模型准备修改的文件列表做交叉验证不一致时直接让模型重新解析。这相当于给任务解析加了一层自检逻辑。4.3 存在感极强的“分支过期”另一个高频问题Agent 从创建分支到最终合并之间主干分支可能已经被其他 PR 推进了好几个提交。GitHub 会因此把 PR 标记为mergeablefalse自动合并直接失败。这个问题的排查思路很明确合并前检查 PR 基础分支是不是最新如果不是用 GitHub API 的 update branch 功能先把目标分支合进来再重新跑测试。但如果每次都是人工去点“Update branch”那自动化就不彻底了。所以我在 workflow 里加了一小段逻辑在轮询mergeable状态之前先检查 PR 的 head 分支是否落后于 base 分支落后就自动执行 update。不过要注意更新分支后需要重新等待一轮状态检查轮询时间要留足。4.4 安全与权限相关的坑最后是关于权限的坑。我的第一条血泪教训是GitHub Actions 自带的GITHUB_TOKEN虽然方便但它的默认权限是受限的而且如果仓库的 Actions 设置开了“read-only”你连创建 PR 都做不到。更安全可控的方式是用一个专门的机器人账号 PAT然后把 Token 放进 Secrets。第二条是路径过滤问题。AI 生成的代码里如果出现.github/workflows/这种路径我是直接拒绝的。因为工作流文件一旦被改等于把仓库的自动化防线也一起改了。我在脚本里维护了一个禁止 AI 触碰的路径列表包含工作流目录、安全相关配置、密钥文件等一旦校验发现模型要改这些路径立即终止流程并报警。顺带说一句抓日志非常重要。我给 Agent 执行器的每一步都加了详细日志输出包括模型返回的原始 JSON、重试次数、测试输出。因为模型生成是不可预测的没有日志就无从排查。下面给一个常见问题速查表方便你以后排查现象可能原因排查与解决流程停在上一步没有 PR 创建测试 job 失败或状态检查未通过查看 Actions 日志定位测试失败原因模型重试次数用尽任务描述太模糊或代码生成质量差检查 Issue 是否满足模板要求人工介入PR 显示 mergeablefalse基础分支过期或合并冲突在 workflow 里加自动 update branch自动合并未触发缺少 LGTM 评论或评论者不在白名单确认白名单配置补充 LGTM 评论模型试图修改敏感路径提示词约束不足检查路径过滤列表是否生效4.5 模型选的不好后续全是事最后补一个代码之外的坑模型选型直接决定整条链路的成功率。有些模型写点示例代码是没问题一旦面对仓库级任务、长上下文、多文件改动的场景输出质量立刻崩盘。我做过一次简短的横向对比把同一个 Issue 分别扔给三个主流模型成功率能从六成拉到九成差距很明显。我的建议是在正式接入流程前先准备一份“验收测试集”。从自己仓库里挑十来个典型需求让候选模型在低风险的分支上跑一轮以“一次通过率”和“重试次数”两个指标做筛选。能跑过这套测试集的模型再放进正式 workflow别拿正式任务当模型评测场。5. 最终效果与可以继续扩展的地方这套系统跑了两周我用一个中等规模的后端仓库做了试验总共产出约 30 个任务 PR。其中约 20 个是一次通过5 个经过模型自行重试后通过3 个需要人工小修后通过2 个因为任务需求本身过于模糊被退回。整体体验是它不能完全替代开发但能替团队接住大量重复性、样板式的工作。5.1 实际跑了两周后我的真实体感先说收益。团队里那些“加一个接口”“补一个单测”“重构某处重复代码”一类的低风险任务现在基本都是 AI 代理在处理。以前一个小任务从认领到提 PR至少要花半天工夫现在往往十几分钟就出一个可评审的 PR。这种把重复劳动从开发者的待办列表里拿掉的感觉是这套系统最值钱的地方。再说局限。模型在处理跨模块、涉及大量既有逻辑的任务时仍然经常翻车。尤其是那些需要“读懂整个业务背景”才能做对的需求AI 的完成质量很不稳定人工评审的成本自然就高。另外PR 合并后如果测试覆盖不全问题不会立刻暴露可能等到上线前才发现。这意味着自动化流程必须和测试覆盖率绑定覆盖率太低的任务不该放开自动合并。5.2 后续还可以扩展的四个方向这套框架后续还有几个我可以明确看到的方向。第一个方向是依赖图感知在任务解析阶段引入仓库的依赖关系让 AI 一眼看出改一个文件会影响哪些下游模块。第二个方向是多模型投票同一任务让两个不同模型各自生成方案由自动对比器选出更优版本适合高风险改动。第三个方向是自动回滚把 PR 合并后的线上监控接进来监控指标异常时自动 revert 对应 PR形成更完整的闭环。第四个方向是把流程从代码仓库延伸到文档和配置领域比如自动生成变更记录、更新接口文档、同步环境配置。这几个方向都不需要推翻现有架构只是在已有流水线上再叠加新的能力层。如果你也准备动手搭一个类似的 AI 编码代理工作流我的建议是不要贪多。先把“任务解析、代码生成、测试校验、PR 合并”这四段基础链路跑稳再考虑加花活。自动化流程最怕的不是功能少而是每个环节都不可靠。踏踏实实把每一段的校验和日志做扎实这个“总导演”才能真正成为团队里得力的帮手。