企业官网建设流程全解析

1. 先把这个项目的底牌摊开讲

“3 个 AI Agent 交付一个企业项目：4 人团队 2 个月，我 3 周做完”——这句话我第一次看到的时候，第一反应不是兴奋，而是警惕。因为但凡在企业里真正交付过项目的人都知道，工期压缩一半靠工具，另一半靠的是把不确定性提前掐死。AI Agent 能帮你写代码、查资料、跑测试，但它不会替你背锅，也不会在需求评审会上帮你跟业务方扯皮。所以这个标题真正值得拆的，不是“3 周做完”这个结果，而是为什么 3 个 Agent 能顶住一个 4 人团队 2 个月的活，以及这套东西到底怎么搭、怎么用、哪里会翻车。

我先把结论放在前面：这套方案的核心不是“让 AI 写代码”，而是把交付流程拆成可并行、可验证、可回滚的单元，然后让 Agent 去填那些重复度高、上下文明确、验收标准清晰的环节。人负责的是判断、取舍和兜底，Agent 负责的是执行、检索和初筛。这个分工一旦错位，比如让 Agent 去做需求决策，或者让人去干重复的 CRUD，效率立刻崩盘。

这篇文章适合三类人看：一是手里有企业项目、想试试 AI Agent 但不知道从哪下手的开发者；二是团队小、工期紧、想用工具把人力杠杆撬起来的 Tech Lead；三是已经在用 RAG、CI、code review 这些工具，但还没把它们串成一条流水线的人。我会把整个项目的设计思路、Agent 分工、worktree 并行策略、CI 卡点、RAG 知识库搭建、以及我踩过的坑，全部摊开讲。你看完不一定能 3 周做完，但至少知道哪些地方能省、哪些地方不能省。

2. 整体设计与思路拆解：为什么是 3 个 Agent，而不是 1 个或 5 个

2.1 从“4 人 2 个月”倒推工作量结构

一个典型的企业项目，4 人 2 个月，按每人每天有效产出 5 小时算，大约是 4 × 40 天 × 5 小时 = 800 人时。这 800 小时里，真正写核心业务逻辑的可能只占 30%，剩下 70% 是：需求理解与澄清、接口联调、数据迁移脚本、测试用例、code review、文档、环境配置、修 bug、以及各种“等别人回复”的阻塞时间。

AI Agent 最擅长吃掉的，恰恰是那 70% 里上下文明确、验收标准可量化的部分。比如：

• 根据 OpenAPI 文档生成接口调用代码和 mock 数据
• 根据数据库 schema 生成 CRUD 和迁移脚本
• 根据历史 code review 记录，对 diff 做第一轮静态检查
• 根据 RAG 知识库回答“这个字段的业务含义是什么”
• 根据 CI 失败日志，定位是依赖问题还是逻辑问题

这些活人做不是不行，而是切换成本高、重复度高、容易漏。Agent 做这些，速度是人的 5 到 10 倍，而且不会因为下午开了个会就忘了上午的上下文。

2.2 为什么是 3 个 Agent，而不是 1 个全能 Agent

我试过用一个“全能 Agent”包打天下，结果很惨。它一会儿要查业务文档，一会儿要写代码，一会儿要跑测试，上下文窗口被塞得乱七八糟，最后连“当前在改哪个模块”都搞混了。Agent 的数量不是越多越好，而是按职责边界切分，每个 Agent 的输入输出尽量正交。

我最终定下来的 3 个 Agent 是：

这三个 Agent 的边界很清楚：ArchAgent 不写代码，CodeAgent 不做需求决策，GateAgent 不直接改代码只给意见。这样每个 Agent 的 prompt 可以写得很窄，准确率反而高。你如果非要用一个 Agent 干三件事，那就得接受它每件事都干到 70 分，而企业项目里 70 分往往等于返工。

2.3 人在这套体系里到底干什么

很多人以为上了 Agent 人就可以躺了，恰恰相反。人的角色变成了定义验收标准、处理 Agent 之间的冲突、以及兜底那些 Agent 不敢碰的模糊地带。具体来说：

• 需求评审时，人要把“用户能快速看到数据”翻译成“列表接口 P95 小于 200ms，首屏渲染小于 1s”，Agent 才能据此生成可验证的任务。
• CodeAgent 和 GateAgent 意见冲突时，人要做最终裁决，并把裁决结果写回 RAG 知识库，让下次不再吵。
• 涉及权限、资金、合规的逻辑，人必须逐行 review，不能交给 Agent 初筛就过。

我个人的体会是：Agent 把人的时间从“做”转移到了“判”。判比做累，但判的杠杆率高得多。你判一次，Agent 能执行一百次。

3. 核心细节解析与实操要点：worktree、CI、RAG 怎么串起来

3.1 git worktree 与 git branch 的区别，以及为什么并行开发必须用 worktree

这是整个项目里最容易被忽略、但收益最大的一个点。很多人分不清git worktree和git branch，我用人话解释一下：

• git branch是逻辑上的分支指针，你切换分支时，工作区文件会被替换。同一时间你只能在一个分支上干活。
• git worktree是把同一个仓库的不同分支，检出到不同的物理目录。你可以同时开着三个终端，一个目录在改 feature A，一个目录在改 feature B，互不干扰。

为什么这对 AI Agent 至关重要？因为 CodeAgent 并行跑多个任务时，如果共用一个工作区，就会出现“Agent A 改了文件，Agent B 读到的却是改了一半的版本”，这种脏读会导致生成的代码完全错乱。用 worktree 之后，每个 Agent 任务分配一个独立目录，物理隔离，谁也别碰谁。

实操命令大概是这样：

# 主仓库在 /repo/main cd /repo/main git worktree add ../wt-task-101 -b task-101 git worktree add ../wt-task-102 -b task-102 git worktree add ../wt-task-103 -b task-103 # 每个 Agent 在自己的目录里干活 cd ../wt-task-101 && codeagent run --task task-101

注意：worktree 不是免费的。每个 worktree 都会占一份磁盘空间，而且 node_modules、venv 这类依赖目录不会自动共享。我的做法是把依赖目录做成软链接，或者用 pnpm 的全局 store 来省空间。

3.2 CI 卡点怎么设计，才能让 GateAgent 真正拦住问题

CI 不是“跑个测试就完事”。在这个项目里，CI 承担的是GateAgent 的物理执行层。GateAgent 的审查意见再漂亮，如果 CI 不执行，等于没有。我把 CI 分成四道门：

1. 静态检查门：lint、类型检查、格式检查。这一层最快，30 秒内出结果，不过直接打回。
2. 单测门：CodeAgent 生成的单测必须跑过，覆盖率低于阈值直接失败。
3. 集成门：起一个轻量环境，跑接口契约测试，确认 ArchAgent 定义的契约没被破坏。
4. 安全门：依赖漏洞扫描、敏感信息扫描。这一层最慢，但必须卡。

GitHub CI 和 GitLab CI 我都用过，核心逻辑一样，区别在配置语法。GitHub 用.github/workflows/*.yml，GitLab 用.gitlab-ci.yml。我的建议是：把 CI 配置也纳入 RAG 知识库，这样 GateAgent 在给审查意见时，能引用“根据 CI 第 3 条规则，你这个改动会导致集成门失败”，而不是干巴巴地说“我觉得有问题”。

3.3 RAG 知识库到底存什么，不存什么

RAG 是这套体系里最容易做成“玩具”的部分。我见过太多人搭了个 RAG，往里塞了一堆 PDF，然后问它“我们项目的登录逻辑在哪”，它给你编一段。问题不在 RAG，在于你塞进去的东西本身就没有结构。

我的 RAG 知识库只存四类内容：

• 接口契约：OpenAPI 文档、字段业务含义、错误码表。这类内容结构化程度高，检索准确率最高。
• 历史 code review 记录：把“这个写法为什么被拒”沉淀下来，GateAgent 直接复用。
• CI 失败归因：每次 CI 挂了，人工写一句归因，比如“依赖版本冲突，需锁版本”。下次同类失败，Agent 直接给建议。
• 架构决策记录（ADR）：为什么选 A 不选 B，这类内容对 ArchAgent 拆任务极其重要。

至于图片，RAG 知识库能不能存图片？技术上可以，用多模态 embedding，但我的经验是企业项目里图片检索的准确率远低于文本，除非你有大量架构图需要按图搜图，否则别折腾。把图里的关键信息用文字描述一遍存进去，效果更好。

3.4 ontology rag 和普通 RAG 的区别，什么时候值得上

普通 RAG 是“文本块 + 向量检索”，ontology rag 是“实体 + 关系 + 向量检索”。区别在于，普通 RAG 检索出来的是“相似的段落”，ontology rag 检索出来的是“相关的实体及其关系”。

举个例子：你问“订单模块依赖哪些服务”。普通 RAG 可能返回一段提到订单和支付的文档，但未必完整。ontology rag 里，订单是一个实体，它和支付、库存、用户之间有明确的依赖关系边，检索时能沿着边把整条链路拉出来。

什么时候值得上 ontology rag？我的判断标准是：如果你的项目里实体关系复杂、且跨模块查询频繁，就值得。比如微服务架构、有几十个表和上百个接口的项目。如果只是个单体应用，普通 RAG 加好的元数据过滤就够了。上 ontology 的成本不低，要建本体、要维护关系，别为了时髦硬上。

4. 实操过程与核心环节实现：从需求到交付的完整流水线

4.1 第一步：ArchAgent 把需求拆成可执行任务卡

需求文档进来，ArchAgent 的第一件事不是写代码，而是输出任务卡。一张合格的任务卡包含：

• 任务 ID 和标题
• 输入：依赖哪些接口、哪些数据表、哪些配置
• 输出：改哪些文件、新增哪些文件、对外暴露什么
• 验收标准：可量化的测试点，比如“输入 X 返回 Y”“并发 100 时无超时”
• 风险标记：是否涉及权限、资金、外部依赖

我让 ArchAgent 用固定模板输出，模板本身存在 RAG 里。这样每张任务卡格式一致，CodeAgent 消费起来不需要额外解析。实测下来，任务卡拆得越细，CodeAgent 的首次通过率越高。一张卡如果超过 200 行代码量，就该拆。

4.2 第二步：CodeAgent 在 worktree 里并行执行

CodeAgent 拿到任务卡后，流程是这样的：

1. 从主仓库拉一个 worktree，创建独立分支。
2. 读任务卡，读相关代码文件，读 RAG 里的接口契约。
3. 生成代码和单测。
4. 本地跑单测和 lint。
5. 通过后，提交 diff，交给 GateAgent。

这里有个关键参数：并行度。我一开始开了 6 个 worktree 并行跑，结果机器 CPU 打满，单测跑得比串行还慢。后来压到 3 个并行，配合 16 核 32G 的机器，吞吐最高。你可以用这个公式估算：并行度 ≈ CPU 核数 / 每个任务平均核数占用。一般编译型语言每个任务吃 2 到 4 核，解释型语言吃 1 到 2 核。

4.3 第三步：GateAgent 做第一轮 code review

GateAgent 的审查不是“看一眼说不错”，而是按规则逐条过。规则来自三处：CI 配置、历史 review 记录、以及团队约定的编码规范。它的输出是一份结构化报告：

人只需要看“失败”和“警告”这两栏，通过的不用管。这一下就把 review 时间从每人 30 分钟压到 5 分钟。

4.4 第四步：CI 跑门禁，失败自动归因

CI 挂了不可怕，可怕的是不知道为啥挂。我在 CI 脚本里加了一段逻辑：失败时，把日志尾部 200 行喂给 GateAgent，让它输出归因。归因分三类：

• 环境问题：依赖下载失败、端口占用。这类直接重试。
• 代码问题：编译错误、测试断言失败。这类打回 CodeAgent。
• 契约问题：接口不匹配、字段缺失。这类打回 ArchAgent 重新对齐。

实测下来，80% 的 CI 失败是环境问题，重试就好。剩下 20% 里，代码问题和契约问题各占一半。这个归因机制让平均修复时间从 40 分钟降到 12 分钟。

4.5 第五步：人做最终验收与知识沉淀

Agent 跑完，人做三件事：

1. 抽查：随机抽 20% 的 diff 逐行看，重点看权限和资金相关。
2. 验收：按任务卡的验收标准跑一遍，确认达标。
3. 沉淀：把这次的新决策、新坑、新规范写回 RAG。

第三步最容易被跳过，但它是让下一周比这一周快的关键。我坚持每次迭代结束花 30 分钟做沉淀，三周下来，RAG 里的有效条目从 40 条涨到 180 条，CodeAgent 的首次通过率从 55% 涨到 78%。

5. 常见问题与排查技巧实录

5.1 Agent 之间上下文不一致怎么办

这是最常见的问题。ArchAgent 说接口返回userId，CodeAgent 写成了user_id，GateAgent 又按userId检查，三方打架。根因是契约没有单一事实来源。

我的解法是：所有接口契约统一存在 RAG 的一个命名空间下，任何 Agent 引用契约必须带版本号。契约变更必须走一次人工确认，确认后版本号加一，旧版本标记废弃。这样谁引用旧版本，GateAgent 直接报错。

5.2 RAG 检索不准，Agent 答非所问

先别怪模型，先查三件事：

• 分块是否合理：把 50 页的文档切成 500 字一块，检索时经常切在句子中间。我的做法是按标题层级切，每块带上级标题作为上下文。
• 元数据是否齐全：每块内容要带来源、版本、生效日期。检索时先按元数据过滤，再按向量排序。
• 是否有重复内容：同一份文档存了三个版本，检索出来互相矛盾。定期去重，只留最新版。

5.3 CI 太慢，拖垮整体节奏

CI 慢通常慢在依赖安装和全量测试。我的优化顺序是：

1. 依赖缓存，命中缓存后安装时间从 3 分钟降到 20 秒。
2. 测试分片，把单测按模块拆成 4 片并行跑。
3. 增量测试，只跑受影响的模块，用 git diff 算出影响范围。

这三招下来，CI 从 12 分钟压到 3 分半。别小看这几分钟，一天跑 20 次就是 3 小时的差距。

5.4 Agent 生成的代码能直接上生产吗

不能。我的底线是：Agent 生成的代码必须经过人 review 才能合并到主分支。GateAgent 只是初筛，它拦得住语法错误和契约问题，拦不住业务逻辑错误。尤其是涉及金额计算、权限判断、状态机流转的地方，人必须逐行看。我踩过一次坑：CodeAgent 把“退款金额不能超过订单金额”写成了“不能超过订单金额的 1.1 倍”，GateAgent 没查出来，因为这条规则不在 RAG 里。后来我把所有业务规则都补进 RAG，这类问题才绝迹。

5.5 常见问题速查表

6. 这套方案能复制到什么程度

我把这套东西跑通之后，最大的感受是：AI Agent 不是魔法，它是一面镜子，照出你流程里本来就不清晰的地方。你需求拆得越细，它干得越好；你契约定得越死，它错得越少；你 CI 卡得越严，它越不敢乱来。反过来，如果你自己都不知道要做什么，Agent 只会把混乱放大十倍。

至于“3 周做完 4 人 2 个月的活”，我的真实数据是：核心功能 3 周交付，但后续的联调、压测、上线准备又花了 1 周半。所以严格说是 4 周半，不是 3 周。标题嘛，总要有点冲击力。但即便 4 周半，相比 2 个月也是实打实的压缩。

最后分享一个我一直在用的小技巧：每次 Agent 犯错，不要只修代码，要把错误原因写成一条 RAG 规则。比如“CodeAgent 把分页参数默认值写成 10，但业务要求是 20”，就把“分页默认值 20”写进契约。这样下次它就不会再错。三周下来，我的 RAG 规则库从 40 条涨到 180 条，Agent 的首次通过率从 55% 涨到 78%。这个数字还会涨，因为规则在积累，而人的时间被省下来了。