企业官网建设流程全解析

如果你每天跟代码仓库打交道，应该能明显感觉到：现在的 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_key=os.environ["MODEL_API_KEY"], base_url=os.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, recursive=True )) 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( model=os.environ["MODEL_NAME"], temperature=0.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 = f"agent/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_ascii=False))

这里有三点值得说明。第一，提示词里我塞入了仓库文件树，但只截断 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/checkout@v4 - uses: actions/setup-python@v5 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.txt，AI 生成的代码经常会新增第三方依赖，所以要在 Agent 执行阶段先把requirements.txt里的改动写进去，然后在测试 job 里重新安装。如果不这样做，可能出现“本地测试过了、CI 里缺包”的尴尬情况。

3.4 第四步：PR 创建与自动合并

测试全绿后，就进入 PR 阶段。创建 PR 时，我会让模型写一段 PR 描述，但题目和描述框架由我们预先定义好，避免模型自由发挥。PR 标题统一带上 Issue 编号，描述里固定包含“任务来源”“改动摘要”“测试说明”三个区块，这样评审人打开 PR 就能快速理解上下文。

创建 PR 的代码很直接：

pr = repo.create_pull( title=f"🤖 Agent 自动 PR: #{issue.number} {plan['summary']}", body=build_pr_body(issue, plan, result), head=f"agent/issue-{issue.number}", base=TARGET_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需要人工 LGTM，full则只要测试全绿就自动合并。我的建议是，默认永远用semi，除非你跑完评测、对某个仓库的模型输出非常放心了，再考虑放开。

4. 踩坑记录与排查清单

从理论到落地，总有些坑只有真跑过才会遇到。在这两个星期里，我把遇到的问题按照出现频率排了个序，也整理了对应的解决方法和排查思路，这部分的价值不亚于前面的搭建过程。

4.1 补丁格式错乱导致的反复修复

第一次设计时，我让模型直接输出 git diff 文本，然后由脚本调git apply去应用。想法是好的，但实际操作中模型的 diff 输出经常出问题：行号对不上、上下文行有缺失、文件路径写错，导致补丁被拒绝。出错之后还得重新生成，成本高、体验差。

后来我换了一个思路：不再让模型输出 diff，而是直接输出每个文件的完整内容。在 JSON 结果里指定path和content，由脚本直接把内容覆盖到对应文件上。这个改动一下就把“补丁失败”这类问题基本消灭了。代价是传输的内容变多了，但换来的是稳定性和可控性，非常划算。

4.2 任务拆解不完整的问题

AI 解析任务时，最典型的问题是“只看表面，不看全局”。比如你让它“加一个接口”，它可能只改了接口文件，却忘了在路由注册处加映射；你让它“优化某个函数”，它可能把这个函数涉及的外部调用方完全忽略。

我的解决方式是在解析阶段增加“文件影响范围”约束。提示词里强制要求模型对每个改动文件给出“为什么改这个文件”的理由，并输出一个 checklist，说明这个改动可能影响哪些现有文件。脚本会拿着这个 checklist 和模型准备修改的文件列表做交叉验证，不一致时直接让模型重新解析。这相当于给任务解析加了一层自检逻辑。

4.3 存在感极强的“分支过期”

另一个高频问题：Agent 从创建分支到最终合并之间，主干分支可能已经被其他 PR 推进了好几个提交。GitHub 会因此把 PR 标记为mergeable=false，自动合并直接失败。这个问题的排查思路很明确：合并前检查 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、重试次数、测试输出。因为模型生成是不可预测的，没有日志就无从排查。

下面给一个常见问题速查表，方便你以后排查：

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 合并”这四段基础链路跑稳，再考虑加花活。自动化流程最怕的不是功能少，而是每个环节都不可靠。踏踏实实把每一段的校验和日志做扎实，这个“总导演”才能真正成为团队里得力的帮手。