1. 项目缘起与整体交付思路1.1 一个真实到有点扎心的对比去年年底我接手了一个企业级内部管理系统的交付项目。合同上写的是 4 人团队、2 个月工期预算按人天算得清清楚楚。结果我带着 3 个 AI Agent硬生生在 3 周内把活干完了交付质量还过了甲方的验收。这不是标题党是我自己踩了无数坑之后跑通的一条路。先说清楚这个项目是什么一个面向企业内部运营团队的工单流转与知识检索系统前端是常规的管理后台后端要接工单状态机、权限体系、消息通知还要挂一个能查历史工单和内部文档的 RAG 知识库。听起来不复杂但企业项目的恶心之处在于——需求文档永远写不全甲方永远在验收前三天提新想法而你的团队永远在“这个功能到底谁负责”的扯皮里消耗掉一半时间。我当时的处境是手上只有 1 个后端、1 个前端、1 个测试加上我自己做架构和兜底。按传统排期2 个月是紧巴巴的。但我做了一个决定把 AI Agent 当成“虚拟团队成员”来用而不是当成一个“代码补全工具”。这个定位的差别直接决定了后面所有工作流的组织方式。1.2 为什么是 3 个 Agent而不是 1 个或 10 个很多人一上来就问你用的什么模型什么框架我的回答是先别管模型先想清楚你要几个“角色”。我最终定下来的是 3 个 Agent分别承担不同职责Agent A架构与后端主力负责接口设计、数据模型、核心业务逻辑、RAG 检索链路。Agent B前端与联调助手负责页面组件、状态管理、接口对接、表单校验。Agent C测试与代码审查负责生成测试用例、跑 CI、做 code review、抓边界条件。为什么不是 1 个因为单个 Agent 的上下文窗口再大也会在长任务里“失忆”。你让它同时管后端和前端它会在第 40 轮对话后把前面定的接口字段名改掉然后前端就炸了。为什么不是 10 个因为 Agent 之间的协调成本会指数级上升你需要写大量的编排逻辑最后你发现自己不是在写业务而是在写“Agent 调度器”。3 个是我实测下来最稳的平衡点职责边界清晰每个 Agent 的上下文压力可控而且刚好对应“开发—联调—验证”这条主线。1.3 整体交付思路把项目拆成“可并行的轨道”传统交付是串行的需求→设计→开发→测试→修 bug→验收。AI Agent 的优势在于它可以在你写需求的时候就开始生成脚手架在你 review 代码的时候就开始跑测试。所以我把整个项目拆成了三条并行轨道轨道负责角色核心产出并行策略轨道一契约先行我 Agent AOpenAPI 规范、数据模型、RAG 检索接口第一天冻结接口字段轨道二前端并行Agent B页面骨架、Mock 数据、组件库接口冻结后立即开工轨道三验证前置Agent C测试用例、CI 流水线、审查清单与开发同步推进这里最关键的一步是契约先行。我让 Agent A 在第一天就输出一份完整的 OpenAPI 规范包括每个接口的路径、方法、请求体、响应体、错误码。这份规范一旦冻结Agent B 就可以用 Mock 数据独立开发前端完全不用等后端写完。这就是为什么 3 周能做完 2 个月的活——不是写得快是等的时间被消灭了。提示契约冻结不是拍脑袋而是让 Agent A 基于需求文档生成初版我再人工过一遍字段命名和错误码规范。这一步花 2 小时能省后面 20 小时的联调扯皮。2. 核心技术点拆解与工具选型2.1 Git worktree让 3 个 Agent 同时干活不打架这是整个项目里我最想安利的一个点。很多人用 AI 写代码最头疼的就是“多个任务同时改同一个仓库分支切来切去最后 merge 冲突到怀疑人生”。我一开始也踩了这个坑Agent A 在改后端Agent B 在改前端两个人都往同一个分支提交结果 Agent B 的提交把 Agent A 还没写完的接口文件覆盖了。后来我改用git worktree。简单说worktree 允许你把同一个仓库的多个分支同时检出到不同的目录里。比如# 主仓库在 /project/main git worktree add ../project-backend feature/backend git worktree add ../project-frontend feature/frontend git worktree add ../project-test feature/test这样 Agent A 在../project-backend里干活Agent B 在../project-frontend里干活互不干扰。每个 Agent 有自己的工作目录、自己的分支、自己的上下文最后通过 PR 合并回主分支。这里必须区分一下git worktree 和 git branch 的区别因为很多人会混淆git branch只是创建一个分支指针你切换分支时工作目录里的文件会跟着变。git worktree是把分支“检出”到一个独立目录多个分支可以同时存在于不同目录互不影响。对于 AI Agent 协作来说worktree 的价值在于每个 Agent 有一个稳定的、不会被别人打断的工作环境。Agent 不需要理解“现在在哪个分支”它只需要在自己那个目录里持续工作。这大大降低了 Agent 的认知负担也降低了你的管理成本。注意worktree 用完记得git worktree remove清理否则目录会越堆越多。我一般是在 PR 合并后立即清理。2.2 CI/CD让 Agent C 的审查结果自动落地CI/CD 这个词大家都不陌生但在 AI Agent 项目里它的角色变了。传统 CI 是“人写完代码后跑一遍”而在我的流程里CI 是Agent C 的“执行手臂”。具体怎么做的Agent C 生成测试用例后直接推到feature/test分支触发 GitHub CI 或 GitLab CI 流水线。流水线里跑三件事单元测试和集成测试静态代码检查lint、类型检查构建产物并部署到预发环境如果流水线挂了Agent C 会自动读取日志定位失败原因然后生成修复建议。我只需要看它给的结论决定是让它自己修还是我介入。这里有个细节CI 的失败日志要结构化。我让 Agent C 在读取日志时先提取“失败用例名、失败断言、堆栈关键行”再喂给模型。如果直接把几千行日志丢进去模型会抓不住重点。这个预处理步骤是我踩坑后加的效果立竿见影。2.3 RAG企业知识库的检索增强别把它当搜索引擎这个项目里有一个核心功能工单知识检索。用户输入一个问题系统要从历史工单和内部文档里找到最相关的几条然后生成回答。这就是典型的RAG检索增强生成场景。我选的是LangChain4j 本地向量库的组合原因是企业内网不能随便调外部 API而且数据敏感。具体链路是文档切分把历史工单和文档按语义切块每块 300-500 字。向量化用本地 embedding 模型生成向量。存储写入向量库同时保留原文和元数据工单号、时间、分类。检索用户提问时先向量检索 Top-K再重排序。生成把检索结果拼进 prompt让模型生成回答。这里我踩过一个坑RAG 知识库能不能存图片答案是能但要看你的检索需求。如果图片里有文字比如截图里的报错信息你需要先做 OCR 提取文字再把文字向量化。如果图片是流程图那纯向量检索基本没用得靠多模态模型或者人工打标签。我的做法是图片单独存对象存储向量库里只存图片的描述文本和链接检索命中后把图片一起返回。还有一个热词是ontology RAG 和 KG 知识库。简单区分一下类型核心结构适合场景本项目是否采用向量 RAG向量相似度文档问答、语义检索是知识图谱 KG实体-关系-实体强逻辑推理、多跳查询否Ontology RAG本体向量需要领域建模的复杂检索部分借鉴我这个项目里工单之间的关联主要是“同一客户”“同一问题类型”用向量 RAG 加元数据过滤就够了。如果以后要做“这个工单的根因是不是三个月前那个变更引起的”那就得上 KG。2.4 工具选型对比为什么不用现成的 Agent 框架市面上有很多 AI Agent 搭建框架比如 Coze、LangGraph、Spring AI Agent 等。我评估过一圈最后选择半自研编排 成熟组件的路线。原因如下Coze 这类平台上手快但企业项目要私有化部署数据不能出内网而且深度定制受限。LangGraph适合复杂状态机但学习曲线陡我的项目流程相对线性用不上那么重的编排。Spring AI Agent如果团队是 Java 栈可以考虑但我这边后端是 Python前端是 TypeScript混用反而增加沟通成本。最终我的架构是Python 后端 FastAPI LangChain4j 思路 自研轻量编排层。编排层只做三件事任务分发、上下文管理、结果汇总。不搞花哨的图结构够用就行。实操心得不要为了用框架而用框架。Agent 项目的核心难点不在框架而在上下文管理和任务边界划分。框架解决不了你的业务问题只会增加你的调试成本。3. 实操过程与核心环节实现3.1 第一周契约冻结与脚手架生成第一周的目标只有一个把接口契约和数据模型定死。我让 Agent A 基于需求文档生成 OpenAPI 规范然后我人工 review 了三个东西字段命名规范统一用 snake_case避免前后端各写各的。错误码体系定义 400/401/403/404/500 的业务含义每个错误码对应一个明确的提示文案。分页和排序参数统一用page、page_size、sort_by、order。这份规范冻结后Agent B 立刻开始用 Mock 数据搭前端。Mock 数据的生成也是 Agent B 自己做的它根据 OpenAPI 规范自动生成 TypeScript 类型定义和 Mock 响应。这一步省掉了传统流程里“前端等后端接口”的至少一周时间。同时Agent C 开始搭建 CI 流水线。它生成的.github/workflows/ci.yml大概长这样name: CI on: push: branches: [feature/*] pull_request: branches: [main] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Python uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Install deps run: pip install -r requirements.txt - name: Run tests run: pytest --covapp --cov-reportxml - name: Lint run: ruff check .这个流水线在第一周就跑通了虽然当时测试用例还很少但“能跑”比“跑得全”更重要。因为一旦流水线跑起来后面每加一个功能Agent C 都会自动补测试用例并触发验证。3.2 第二周后端核心逻辑与 RAG 链路第二周是强度最高的一周。Agent A 负责后端核心逻辑我负责 review 和兜底。具体分工是工单状态机Agent A 生成状态流转代码我检查边界条件比如“已关闭”的工单能不能重新打开。权限体系Agent A 生成 RBAC 模型我补充企业特有的“部门隔离”规则。RAG 检索链路这是最花时间的部分我亲自参与了 prompt 设计和检索参数调优。RAG 链路的实现细节# 文档切分 from langchain.text_splitter import RecursiveCharacterTextSplitter splitter RecursiveCharacterTextSplitter( chunk_size400, chunk_overlap50, separators[\n\n, \n, 。, , , , ] ) # 向量化与存储 from langchain_community.embeddings import HuggingFaceEmbeddings embeddings HuggingFaceEmbeddings(model_nameBAAI/bge-small-zh-v1.5) # 检索 retriever vectorstore.as_retriever( search_typemmr, search_kwargs{k: 5, fetch_k: 20} )这里的关键参数是chunk_size和k。我试过 200、400、800 三种切分粒度最后发现 400 字左右最适合工单场景——太短会丢上下文太长会引入噪声。k5是检索返回条数配合 MMR最大边际相关性可以避免返回一堆相似内容。注意embedding 模型的选择很关键。中文场景下bge-small-zh性价比很高如果追求更高精度可以上bge-large-zh但推理速度会慢一倍。企业内网部署要考虑 GPU 资源。3.3 第三周联调、测试与交付第三周主要是联调和验收准备。这时候 worktree 的优势彻底体现出来Agent B 的前端分支和 Agent A 的后端分支各自独立联调时只需要把两个分支合并到一个integration分支跑一遍端到端测试。Agent C 在这一周干了三件大事生成端到端测试用例覆盖登录、工单创建、状态流转、知识检索四条主链路。跑 code review对每个 PR 生成审查意见重点抓空指针、越界、并发问题。生成验收文档包括接口文档、部署手册、测试报告。这里有个小技巧让 Agent C 的审查意见分级。我让它把问题分成 P0必须修、P1建议修、P2可选优化。这样我在 review 时可以先看 P0不会被一堆格式问题淹没。最终交付时甲方验收的重点是“功能是否完整、数据是否准确、性能是否达标”。前两项靠测试用例保证第三项我单独做了一轮压测确认工单创建接口在 100 并发下响应时间低于 200ms。3.4 关于“AI Agent 怎么扛并发”的实测这是热词里问得最多的一个问题。我的答案是Agent 本身不扛并发扛并发的是你的后端架构。Agent 是“开发时的助手”不是“运行时的服务”。你的系统上线后用户请求打过来处理请求的是你的 FastAPI 服务、你的数据库、你的向量库跟 Agent 没关系。Agent 只在开发和测试阶段帮你写代码、跑测试。但如果你要把 Agent 做成运行时服务比如智能客服那并发问题就来了。我的建议是Agent 服务无状态化每次请求带上完整上下文不要依赖内存里的会话状态。向量检索加缓存相同 query 的检索结果缓存 5 分钟能挡掉大量重复请求。限流和降级Agent 生成回答是慢操作必须限流超时后降级到“只返回检索结果不生成回答”。我实测下来单台 8 核 16G 的机器跑本地 embedding 向量检索QPS 大概在 20-30 左右。如果要更高得上 GPU 或者做检索结果缓存。4. 常见问题与排查技巧实录4.1 Agent 协作中的典型翻车现场问题一Agent A 改了接口字段Agent B 不知道。这是最常发生的。解决方案是契约冻结 变更通知。我在项目里加了一个规则任何接口字段变更必须先在 OpenAPI 规范里改然后重新生成前端类型定义。Agent B 每次开工前先拉最新规范确保类型对齐。问题二Agent C 的测试用例跑不过但代码看起来没问题。这种情况通常是测试用例本身写错了。我让 Agent C 在生成测试用例后先自己跑一遍确认用例能通过再提交。如果用例失败先检查是用例问题还是代码问题不要盲目改代码。问题三RAG 检索结果不相关。排查顺序是先看切分粒度是否合理再看 embedding 模型是否适合中文最后看 prompt 是否把检索结果用对了。我遇到过一次检索结果明明是对的但生成回答时模型忽略了检索内容自己编了一个答案。后来在 prompt 里加了“必须基于以下资料回答资料中没有的信息不要编造”问题就解决了。4.2 常见问题速查表问题现象可能原因排查方法解决方案Agent 输出格式不稳定prompt 约束不够检查 prompt 是否有明确格式要求加 few-shot 示例前端类型报错接口字段变更未同步对比 OpenAPI 和前端类型定义重新生成类型CI 流水线频繁失败测试用例不稳定查看失败用例是否依赖外部状态加 mock 和隔离RAG 检索慢向量库未建索引检查向量库配置建 IVF 或 HNSW 索引Agent 上下文溢出对话轮次过多统计 token 数定期摘要压缩上下文合并冲突频繁多 Agent 改同一文件检查 worktree 分支划分按模块拆分 worktree4.3 独家避坑技巧技巧一给每个 Agent 写一份“工作手册”。我在每个 worktree 目录下放了一个AGENT.md里面写清楚这个 Agent 的职责边界、代码规范、提交信息格式、遇到问题时的处理流程。这份手册是我在项目中期加的加了之后 Agent 的输出质量明显提升因为它有了明确的“行为准则”。技巧二用 git worktree 隔离但用 PR 合并。worktree 解决的是“同时干活”的问题PR 解决的是“质量把关”的问题。每个 Agent 的产出都必须通过 PR 合并PR 里附上 Agent C 的审查意见。这样即使 Agent 写错了也能在合并前被发现。技巧三RAG 的 chunk_overlap 不要省。很多人为了省存储把chunk_overlap设成 0。结果就是检索时经常丢上下文因为关键信息刚好被切在边界上。我实测chunk_overlap50是最低要求重要文档可以设到 100。技巧四CI 里加一个“Agent 输出检查”步骤。我在 CI 里加了一个脚本检查 Agent 生成的代码是否包含明显的“AI 味”——比如过度注释、无意义的变量名、重复代码。这个检查不阻断合并但会生成报告提醒我人工 review。5. 这套打法适合谁以及后续怎么扩展5.1 适合的团队和项目类型这套“3 Agent worktree CI RAG”的打法最适合以下场景中小型企业内部系统需求相对明确但工期紧、人手少。有私有化部署要求数据不能出内网必须用本地模型和本地向量库。团队有 1-2 个能兜底的人Agent 可以干活但关键决策和边界条件需要人来把关。不适合的场景也很明确需求极度模糊、需要大量创造性设计的项目Agent 帮不上太多忙反而会增加沟通成本。5.2 后续扩展方向如果要把这套打法复制到更大的项目我建议从三个方向扩展第一Agent 角色细化。3 个 Agent 可以扩展到 5 个比如加一个“数据库迁移 Agent”和一个“文档生成 Agent”。但每加一个编排复杂度就上升一档要谨慎。第二RAG 升级到混合检索。纯向量检索在关键词精确匹配上表现一般。可以加一路 BM25 关键词检索两路结果融合排序。这就是所谓的 hybrid search实测能提升 15%-20% 的召回准确率。第三CI 里加性能回归测试。每次合并前跑一遍基准测试确保新代码没有引入性能退化。这个对 RAG 链路尤其重要因为 embedding 和检索的参数调整很容易影响响应时间。5.3 我个人的几点体会踩了这么多坑我最深的体会是AI Agent 不是让你少干活而是让你把精力从“写代码”转移到“定规则”和“做决策”上。项目前期我花了两天时间写 Agent 工作手册、定接口契约、搭 CI 流水线当时觉得“怎么还没开始写业务”但正是这两天的投入让后面三周跑得飞快。另一个体会是不要追求全自动。我见过有人想搭一个“全自动开发流水线”需求进去代码出来人完全不参与。结果就是 Agent 在错误的路上越跑越远最后返工的成本比人工写还高。我的做法是Agent 负责 80% 的重复劳动我负责 20% 的关键决策。这个比例是我实测下来最舒服的。最后分享一个小技巧每天下班前让 Agent C 生成一份“今日变更摘要”包括改了哪些文件、跑了哪些测试、有哪些未解决的问题。第二天早上我花 10 分钟看完就能快速进入状态。这个习惯让我在 3 周里没有一天是“不知道昨天干了啥”的。