尧图网页设计 
1. 一个人三周干完四个月的活这事到底怎么发生的先交代背景。我手上这个项目是一个企业内部的知识管理系统需求方是某制造业公司的运营部门核心诉求是把散落在各个业务系统里的文档、SOP、培训材料、历史工单整合起来让内部员工能通过自然语言问答的方式快速找到答案。合同签的是4人团队2个月的交付周期预算按人天算。实际执行下来我一个人带着3个AI Agent3周完成了全部交付。这不是标题党。但我也得把话说在前面AI Agent不是银弹它能帮你省掉的是重复劳动和模板化工作省不掉的是架构决策、需求对齐和最终质量把关。如果你指望搭个Agent就躺着收钱那这篇文章可能不适合你。我用的核心工具链是Claude/GPT作为推理主力Git worktree做多Agent并行隔离GitHub Actions做CI/CD流水线RAG检索增强生成做知识库问答Code Review环节用AI辅助但人工终审。这套组合拳打下来效率提升是实打实的但每一步都有坑下面我会把整个项目的设计思路、实操细节、踩坑记录全部摊开讲。这篇文章适合几类人看一是正在做或准备做AI Agent落地项目的开发者二是想了解RAG知识库实际交付中会遇到什么问题的人三是对多Agent协作、CI/CD自动化流程感兴趣的工程师。不管你是刚入门还是已经做过几个项目我相信里面的实操细节和避坑经验都能让你少走弯路。2. 项目整体设计与思路拆解2.1 为什么选AI Agent而不是传统开发模式这个项目的需求本质上是一个RAG知识库问答系统外加一些流程自动化。如果按传统方式做4个人2个月的分工大概是这样1个后端负责API和数据处理1个前端做管理界面和对话交互1个算法工程师调RAG检索和模型1个项目经理兼测试兼文档。听起来合理但实际执行中你会发现大量时间花在沟通、等待、返工上。我决定用AI Agent来重构这个流程核心逻辑是把可标准化的工作交给Agent把需要判断力的工作留给人。具体拆解一下文档解析与清洗这是最枯燥的活几百份PDF、Word、Excel要统一格式、提取文本、分块。传统方式一个人干两周Agent几个小时跑完。RAG检索链路搭建包括向量化、索引构建、检索策略调优。Agent可以快速生成基础代码框架但检索策略的取舍需要人来判断。API接口开发标准的CRUD和对话接口Agent生成代码的质量已经足够高人只需要做Code Review和边界处理。前端界面管理后台和对话窗口Agent能出可用的版本但交互细节需要人调。测试用例编写Agent批量生成测试用例人补充边界场景。CI/CD流水线GitHub Actions的配置文件Agent写得很标准人检查一下触发条件和环境变量就行。这样算下来我的角色从“写代码的人”变成了“定架构、做决策、审代码的人”。3个Agent分别负责不同的工作流通过Git worktree做代码隔离通过CI做质量门禁。2.2 三个Agent的分工与协作机制我给三个Agent起了名字方便区分Builder负责代码生成和文档处理Checker负责Code Review和测试Runner负责CI/CD和部署运维。这不是什么高级框架就是三个不同角色的Prompt加上不同的工具权限。Builder的职责最重根据我给出的接口定义和数据结构生成后端API代码、RAG检索逻辑、文档解析脚本。它的输出直接推到feature分支。Checker的职责是审查Builder的产出检查代码规范、潜在bug、安全问题、边界条件。它不直接改代码而是生成Review意见我来决定是否让Builder修改。Runner的职责是维护CI/CD流水线确保每次push都能触发构建、测试、部署。它还负责监控部署后的服务状态有问题及时告警。三个Agent之间的协作通过Git分支和CI流水线串联。Builder推代码到feature分支CI自动触发测试Checker的Review意见作为PR评论附上我合并到develop分支后Runner负责部署到测试环境。整个流程听起来像一个小型开发团队实际上只有我一个人在关键节点做决策。2.3 Git worktree为什么比branch更适合多Agent并行这里重点讲一下git worktree和git branch的区别因为这是多Agent并行开发的核心基础设施。普通branch的问题是同一时间一个工作目录只能检出一个分支。如果你想让Builder在feature-a上写代码同时Checker在feature-b上跑测试就得来回切换分支或者克隆多个仓库副本。切换分支会打断Agent的工作流克隆多个副本又浪费磁盘和同步成本。Git worktree解决了这个问题它允许你在同一个仓库下检出多个工作目录每个目录对应不同的分支。比如# 主工作目录在 develop 分支 git worktree add ../agent-builder feature/builder-api git worktree add ../agent-checker feature/checker-review git worktree add ../agent-runner feature/runner-ci这样三个Agent各自在自己的目录里工作互不干扰。Builder在../agent-builder里写代码Checker在../agent-checker里跑测试Runner在../agent-runner里改CI配置。它们共享同一个.git对象库所以提交历史是统一的合并的时候不会有冲突。实测下来worktree的磁盘占用比克隆三个仓库少了将近70%而且分支切换的时间从秒级降到了零。对于需要频繁切换上下文的Agent工作流来说这个提升非常明显。注意worktree的每个工作目录是独立的但.git目录是共享的。这意味着你在一个worktree里做的commit在其他worktree里也能看到。合并的时候要注意分支的基线是否一致否则会出现意外的冲突。3. 核心细节解析与实操要点3.1 RAG知识库的搭建从文档到可检索的向量RAG是这个项目的核心功能。简单说RAG就是让AI在回答问题之前先去知识库里检索相关内容然后基于检索结果生成答案。这样做的好处是AI不会瞎编答案有据可查。整个RAG链路的搭建分为四步文档解析、文本分块、向量化、检索策略。文档解析是最脏最累的活。客户给的资料包括PDF、Word、Excel、PPT、甚至扫描件。PDF里还有大量表格和图片。我的处理策略是纯文本PDF用pdfplumber提取保留段落结构。扫描件用OCR处理但准确率有限需要人工抽检。Word和PPT用python-docx和python-pptx提取。Excel表格单独处理转成结构化数据存入数据库不进入向量库。图片暂时不进入RAG链路因为RAG知识库对图片的存储和检索支持有限强行做多模态成本太高。文本分块是RAG效果的关键。分块太大检索精度下降分块太小上下文丢失。我试过几种策略分块策略块大小重叠适用场景实测效果固定长度512字符50字符通用文本一般容易切断句子按段落不定无结构化文档较好但长段落超标递归分割256-1024100字符混合文档最佳兼顾精度和上下文语义分块不定无高质量文档最好但计算成本高最终我选了递归分割块大小512字符重叠100字符。这个参数不是拍脑袋定的是根据实际检索测试调出来的。块太小256的时候检索到的片段经常缺少关键上下文块太大1024的时候检索精度明显下降因为一个块里混了太多不相关的信息。向量化用的是text-embedding-3-small维度1536。选这个模型的原因是性价比高而且对中文的支持不错。向量库用的ChromaDB轻量、易部署、支持元数据过滤。检索策略是RAG的灵魂。我用了混合检索向量相似度检索 关键词BM25检索然后用RRF倒数排名融合合并结果。纯向量检索的问题是对于专有名词和缩写向量模型经常抓不住纯关键词检索的问题是语义相近但用词不同的内容检索不到。混合检索能兼顾两者。# 混合检索的核心逻辑 def hybrid_search(query, top_k5): # 向量检索 vector_results vector_store.similarity_search(query, ktop_k*2) # 关键词检索 keyword_results bm25_index.search(query, ktop_k*2) # RRF融合 fused rrf_fusion(vector_results, keyword_results) return fused[:top_k]3.2 多Agent协作的Prompt设计与权限控制三个Agent的Prompt设计是项目成败的关键。我的原则是每个Agent的职责边界要清晰权限要最小化输出格式要标准化。Builder的Prompt核心要素角色定义你是一个资深后端工程师擅长Python/FastAPI和RAG系统开发。输入规范接收接口定义OpenAPI格式和数据结构JSON Schema。输出规范生成符合PEP8规范的代码附带单元测试提交到指定分支。禁止事项不得修改CI配置文件不得直接推送到main分支。Checker的Prompt核心要素角色定义你是一个严格的Code Reviewer擅长发现安全漏洞和边界问题。输入规范接收PR的diff和相关的测试结果。输出规范生成结构化的Review意见分为“必须修改”和“建议修改”两类。禁止事项不得直接修改代码只能生成评论。Runner的Prompt核心要素角色定义你是一个DevOps工程师擅长GitHub Actions和部署运维。输入规范接收CI日志和部署状态。输出规范生成CI配置修改建议和故障排查报告。禁止事项不得修改业务代码只能操作CI/CD相关文件。权限控制通过GitHub的branch protection rules实现main分支只允许我手动合并feature分支允许Agent推送CI配置文件的修改需要我审批。3.3 CI/CD流水线的设计从代码提交到自动部署CI/CD流水线用的是GitHub Actions。整个流程分为四个阶段lint检查、单元测试、集成测试、部署。lint阶段用ruff做代码风格检查mypy做类型检查。这两个工具速度快能在几秒内发现问题。单元测试阶段用pytest跑所有测试用例覆盖率要求80%以上。Agent生成的测试用例质量参差不齐我加了一个规则如果覆盖率低于80%CI直接失败不允许合并。集成测试阶段会启动一个完整的服务实例用真实的数据跑一遍RAG检索和对话流程。这个阶段最慢大概需要3-5分钟但能发现单元测试覆盖不到的问题。部署阶段分两步先部署到staging环境跑一轮冒烟测试通过后再部署到production。部署用的是Docker Compose简单直接不需要K8s那么重的编排。# .github/workflows/ci.yml 核心配置 name: CI Pipeline on: push: branches: [feature/*, develop] pull_request: branches: [main] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: pip install ruff mypy - run: ruff check . - run: mypy src/ test: needs: lint runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: pip install -r requirements.txt - run: pytest --covsrc --cov-fail-under80 deploy: needs: test if: github.ref refs/heads/develop runs-on: ubuntu-latest steps: - run: docker compose up -d --build提示GitHub Actions的免费额度对私有仓库有限制如果CI跑得太频繁额度很快会用完。我的做法是只在push到feature分支和PR到main时触发CI日常的小修改用本地pre-commit hook做检查。4. 实操过程与核心环节实现4.1 第一周环境搭建与RAG基础链路跑通第一周的目标是搭好基础设施让RAG链路能跑通。具体任务包括仓库初始化、worktree配置、向量库部署、文档解析脚本编写、基础检索测试。仓库初始化没什么好说的git init之后建了main、develop、feature三个分支。worktree的配置前面讲过了三个Agent各一个目录。向量库我选了ChromaDB用Docker部署docker run -d -p 8000:8000 -v ./chroma-data:/data chromadb/chroma文档解析脚本是Builder生成的我做了几处修改增加了异常处理因为客户给的PDF里有不少损坏文件增加了日志记录方便追踪每个文件的处理状态增加了去重逻辑因为有些文档重复上传了好几次。第一周结束时RAG链路能跑通但检索效果一般。我拿20个典型问题做了测试准确率大概60%。主要问题是分块策略不合理很多关键信息被切断了。4.2 第二周检索调优与API开发第二周的重点是调优检索效果和开发API接口。检索调优我做了三件事调整分块参数、引入混合检索、增加重排序。分块参数从固定512改成了递归分割块大小256-1024动态调整。混合检索前面讲过了向量BM25RRF。重排序用的是bge-reranker-base对检索结果做二次排序把最相关的排到前面。这三板斧下来准确率从60%提升到了85%。剩下的15%主要是文档本身质量太差比如扫描件OCR错误太多或者问题超出了知识库范围。API开发用的是FastAPIBuilder生成的代码框架很标准我主要改了错误处理和日志记录。接口包括文档上传、文档删除、对话问答、历史记录查询、健康检查。# 对话问答接口的核心逻辑 app.post(/api/chat) async def chat(request: ChatRequest): # 检索相关文档 docs hybrid_search(request.question, top_k5) # 构建Prompt context \n\n.join([doc.content for doc in docs]) prompt f基于以下资料回答问题\n{context}\n\n问题{request.question} # 调用LLM生成答案 answer llm.generate(prompt) # 返回答案和引用来源 return {answer: answer, sources: [doc.metadata for doc in docs]}4.3 第三周CI/CD完善、测试与交付第三周是收尾阶段。CI/CD流水线在前两周已经基本跑通这周主要是完善细节增加了部署后的健康检查增加了回滚机制增加了告警通知。测试方面Checker生成了200多个测试用例我补充了30多个边界场景。最终覆盖率达到了87%超过了80%的目标。交付前我做了一轮完整的验收测试用客户提供的50个真实问题做测试准确率88%响应时间平均1.2秒。客户对这个结果很满意因为他们的预期是准确率70%以上就行。整个项目从启动到交付实际用时3周零2天。如果按传统方式做4个人2个月是保守估计。效率提升主要来自三个方面Agent承担了80%的编码工作CI/CD自动化了测试和部署worktree让多Agent并行成为可能。5. 常见问题与排查技巧实录5.1 RAG检索效果差的排查思路RAG检索效果差是最常见的问题。我的排查顺序是先看分块再看向量模型最后看检索策略。分块问题最容易发现也最容易解决。如果检索到的片段经常缺少关键信息或者一个片段里混了多个主题那就是分块参数不对。调整方法是拿几个典型问题手动看检索结果如果发现关键信息被切断了就增大块大小或增加重叠如果发现检索结果太泛就减小块大小。向量模型的问题比较隐蔽。如果检索结果和问题语义相近但用词不同向量模型可能没抓好语义。解决方法是换一个更强的向量模型或者增加关键词检索作为补充。检索策略的问题需要看具体场景。如果专有名词检索不到加BM25如果语义相近但用词不同的检索不到加向量如果两者都有问题用混合检索重排序。问题现象可能原因排查方法解决方案检索结果缺少关键信息分块太小或重叠不足检查检索片段的完整性增大块大小或重叠检索结果太泛分块太大检查片段是否混了多个主题减小块大小专有名词检索不到向量模型对专有名词不敏感用关键词检索测试增加BM25检索语义相近检索不到向量模型语义理解不足用同义词测试换向量模型或增加关键词检索结果排序不合理缺少重排序检查Top-5结果的相关性增加重排序模型5.2 多Agent协作中的冲突处理多Agent协作最大的问题是代码冲突。三个Agent同时改代码合并的时候很容易冲突。我的处理策略是文件级隔离Builder只改src/目录Checker只改tests/目录Runner只改.github/目录。这样三个Agent改的文件不重叠合并的时候不会冲突。分支级隔离每个Agent在自己的feature分支上工作合并到develop之前先rebase确保基线一致。提交粒度控制要求Agent每次提交只做一件事提交信息要清晰。这样出问题的时候容易回滚。如果还是冲突了我的处理方式是先看冲突的文件属于哪个Agent的职责范围然后让那个Agent重新生成代码而不是手动解决冲突。因为Agent生成的代码通常比手动合并的更一致。5.3 CI流水线失败的常见原因CI流水线失败的原因很多我整理了一个速查表失败阶段常见原因排查方法解决方案lint代码风格不符合规范看ruff输出让Builder重新生成lint类型检查失败看mypy输出补充类型注解test单元测试失败看pytest输出修复逻辑或更新测试test覆盖率不足看覆盖率报告补充测试用例deployDocker构建失败看构建日志检查依赖和配置deploy健康检查失败看服务日志检查端口和环境变量注意CI流水线失败的时候不要急着手动修复。先看是哪个Agent的职责范围让对应的Agent重新生成。手动修复容易引入新的问题而且会破坏Agent的工作流。5.4 实操心得与避坑技巧心得一Agent的Prompt要迭代。我一开始给Builder的Prompt很粗糙生成的代码质量不稳定。后来我加了具体的代码示例、错误处理规范、日志格式要求生成质量明显提升。Prompt不是写一次就完事的要根据实际输出不断调整。心得二CI的反馈要快。如果CI跑一次要10分钟Agent的迭代速度会大打折扣。我的做法是把lint和单元测试拆开lint几秒就跑完单元测试控制在2分钟以内。集成测试可以慢一点但不要超过5分钟。心得三worktree的清理要及时。worktree用久了会积累很多不用的目录占用磁盘空间。我每周清理一次删除已经合并的分支对应的worktree。心得四RAG的评估要量化。不要凭感觉说“检索效果不错”要拿具体的问题集做测试算准确率、召回率、响应时间。有了量化指标调优才有方向。心得五人工终审不能省。Agent生成的代码再规范也可能有逻辑错误或安全漏洞。我每个PR都会看一遍重点看边界处理、错误处理、安全相关的地方。这个时间省不得。6. 关于这套方法论的一些个人体会这套方法论不是万能的。它适合需求明确、技术栈标准、文档齐全的项目。如果需求模糊、技术栈冷门、文档缺失Agent能帮的忙就有限了。另外AI Agent的产出质量高度依赖你的输入质量。你给的接口定义越清晰Agent生成的代码越准确你给的文档越规范RAG的检索效果越好。Agent不是替你思考的是替你执行的。你得先把事情想清楚Agent才能帮你做快。最后说一个实际感受用了这套流程之后我最大的变化不是写代码更快了而是有更多时间思考架构和业务逻辑。以前80%的时间花在写代码和调bug上现在80%的时间花在设计方案和审查代码上。这个转变对我来说是正向的因为架构决策的质量比代码写的快慢重要得多。如果你也在做类似的项目建议先从一个小模块开始试跑通了再推广到整个项目。不要一上来就搞三个Agent并行先把一个Agent的工作流跑顺再逐步增加。 一个人三周干完四个月活：AI Agent + RAG + Git worktree 实战全记录
1. 一个人三周干完四个月的活这事到底怎么发生的先交代背景。我手上这个项目是一个企业内部的知识管理系统需求方是某制造业公司的运营部门核心诉求是把散落在各个业务系统里的文档、SOP、培训材料、历史工单整合起来让内部员工能通过自然语言问答的方式快速找到答案。合同签的是4人团队2个月的交付周期预算按人天算。实际执行下来我一个人带着3个AI Agent3周完成了全部交付。这不是标题党。但我也得把话说在前面AI Agent不是银弹它能帮你省掉的是重复劳动和模板化工作省不掉的是架构决策、需求对齐和最终质量把关。如果你指望搭个Agent就躺着收钱那这篇文章可能不适合你。我用的核心工具链是Claude/GPT作为推理主力Git worktree做多Agent并行隔离GitHub Actions做CI/CD流水线RAG检索增强生成做知识库问答Code Review环节用AI辅助但人工终审。这套组合拳打下来效率提升是实打实的但每一步都有坑下面我会把整个项目的设计思路、实操细节、踩坑记录全部摊开讲。这篇文章适合几类人看一是正在做或准备做AI Agent落地项目的开发者二是想了解RAG知识库实际交付中会遇到什么问题的人三是对多Agent协作、CI/CD自动化流程感兴趣的工程师。不管你是刚入门还是已经做过几个项目我相信里面的实操细节和避坑经验都能让你少走弯路。2. 项目整体设计与思路拆解2.1 为什么选AI Agent而不是传统开发模式这个项目的需求本质上是一个RAG知识库问答系统外加一些流程自动化。如果按传统方式做4个人2个月的分工大概是这样1个后端负责API和数据处理1个前端做管理界面和对话交互1个算法工程师调RAG检索和模型1个项目经理兼测试兼文档。听起来合理但实际执行中你会发现大量时间花在沟通、等待、返工上。我决定用AI Agent来重构这个流程核心逻辑是把可标准化的工作交给Agent把需要判断力的工作留给人。具体拆解一下文档解析与清洗这是最枯燥的活几百份PDF、Word、Excel要统一格式、提取文本、分块。传统方式一个人干两周Agent几个小时跑完。RAG检索链路搭建包括向量化、索引构建、检索策略调优。Agent可以快速生成基础代码框架但检索策略的取舍需要人来判断。API接口开发标准的CRUD和对话接口Agent生成代码的质量已经足够高人只需要做Code Review和边界处理。前端界面管理后台和对话窗口Agent能出可用的版本但交互细节需要人调。测试用例编写Agent批量生成测试用例人补充边界场景。CI/CD流水线GitHub Actions的配置文件Agent写得很标准人检查一下触发条件和环境变量就行。这样算下来我的角色从“写代码的人”变成了“定架构、做决策、审代码的人”。3个Agent分别负责不同的工作流通过Git worktree做代码隔离通过CI做质量门禁。2.2 三个Agent的分工与协作机制我给三个Agent起了名字方便区分Builder负责代码生成和文档处理Checker负责Code Review和测试Runner负责CI/CD和部署运维。这不是什么高级框架就是三个不同角色的Prompt加上不同的工具权限。Builder的职责最重根据我给出的接口定义和数据结构生成后端API代码、RAG检索逻辑、文档解析脚本。它的输出直接推到feature分支。Checker的职责是审查Builder的产出检查代码规范、潜在bug、安全问题、边界条件。它不直接改代码而是生成Review意见我来决定是否让Builder修改。Runner的职责是维护CI/CD流水线确保每次push都能触发构建、测试、部署。它还负责监控部署后的服务状态有问题及时告警。三个Agent之间的协作通过Git分支和CI流水线串联。Builder推代码到feature分支CI自动触发测试Checker的Review意见作为PR评论附上我合并到develop分支后Runner负责部署到测试环境。整个流程听起来像一个小型开发团队实际上只有我一个人在关键节点做决策。2.3 Git worktree为什么比branch更适合多Agent并行这里重点讲一下git worktree和git branch的区别因为这是多Agent并行开发的核心基础设施。普通branch的问题是同一时间一个工作目录只能检出一个分支。如果你想让Builder在feature-a上写代码同时Checker在feature-b上跑测试就得来回切换分支或者克隆多个仓库副本。切换分支会打断Agent的工作流克隆多个副本又浪费磁盘和同步成本。Git worktree解决了这个问题它允许你在同一个仓库下检出多个工作目录每个目录对应不同的分支。比如# 主工作目录在 develop 分支 git worktree add ../agent-builder feature/builder-api git worktree add ../agent-checker feature/checker-review git worktree add ../agent-runner feature/runner-ci这样三个Agent各自在自己的目录里工作互不干扰。Builder在../agent-builder里写代码Checker在../agent-checker里跑测试Runner在../agent-runner里改CI配置。它们共享同一个.git对象库所以提交历史是统一的合并的时候不会有冲突。实测下来worktree的磁盘占用比克隆三个仓库少了将近70%而且分支切换的时间从秒级降到了零。对于需要频繁切换上下文的Agent工作流来说这个提升非常明显。注意worktree的每个工作目录是独立的但.git目录是共享的。这意味着你在一个worktree里做的commit在其他worktree里也能看到。合并的时候要注意分支的基线是否一致否则会出现意外的冲突。3. 核心细节解析与实操要点3.1 RAG知识库的搭建从文档到可检索的向量RAG是这个项目的核心功能。简单说RAG就是让AI在回答问题之前先去知识库里检索相关内容然后基于检索结果生成答案。这样做的好处是AI不会瞎编答案有据可查。整个RAG链路的搭建分为四步文档解析、文本分块、向量化、检索策略。文档解析是最脏最累的活。客户给的资料包括PDF、Word、Excel、PPT、甚至扫描件。PDF里还有大量表格和图片。我的处理策略是纯文本PDF用pdfplumber提取保留段落结构。扫描件用OCR处理但准确率有限需要人工抽检。Word和PPT用python-docx和python-pptx提取。Excel表格单独处理转成结构化数据存入数据库不进入向量库。图片暂时不进入RAG链路因为RAG知识库对图片的存储和检索支持有限强行做多模态成本太高。文本分块是RAG效果的关键。分块太大检索精度下降分块太小上下文丢失。我试过几种策略分块策略块大小重叠适用场景实测效果固定长度512字符50字符通用文本一般容易切断句子按段落不定无结构化文档较好但长段落超标递归分割256-1024100字符混合文档最佳兼顾精度和上下文语义分块不定无高质量文档最好但计算成本高最终我选了递归分割块大小512字符重叠100字符。这个参数不是拍脑袋定的是根据实际检索测试调出来的。块太小256的时候检索到的片段经常缺少关键上下文块太大1024的时候检索精度明显下降因为一个块里混了太多不相关的信息。向量化用的是text-embedding-3-small维度1536。选这个模型的原因是性价比高而且对中文的支持不错。向量库用的ChromaDB轻量、易部署、支持元数据过滤。检索策略是RAG的灵魂。我用了混合检索向量相似度检索 关键词BM25检索然后用RRF倒数排名融合合并结果。纯向量检索的问题是对于专有名词和缩写向量模型经常抓不住纯关键词检索的问题是语义相近但用词不同的内容检索不到。混合检索能兼顾两者。# 混合检索的核心逻辑 def hybrid_search(query, top_k5): # 向量检索 vector_results vector_store.similarity_search(query, ktop_k*2) # 关键词检索 keyword_results bm25_index.search(query, ktop_k*2) # RRF融合 fused rrf_fusion(vector_results, keyword_results) return fused[:top_k]3.2 多Agent协作的Prompt设计与权限控制三个Agent的Prompt设计是项目成败的关键。我的原则是每个Agent的职责边界要清晰权限要最小化输出格式要标准化。Builder的Prompt核心要素角色定义你是一个资深后端工程师擅长Python/FastAPI和RAG系统开发。输入规范接收接口定义OpenAPI格式和数据结构JSON Schema。输出规范生成符合PEP8规范的代码附带单元测试提交到指定分支。禁止事项不得修改CI配置文件不得直接推送到main分支。Checker的Prompt核心要素角色定义你是一个严格的Code Reviewer擅长发现安全漏洞和边界问题。输入规范接收PR的diff和相关的测试结果。输出规范生成结构化的Review意见分为“必须修改”和“建议修改”两类。禁止事项不得直接修改代码只能生成评论。Runner的Prompt核心要素角色定义你是一个DevOps工程师擅长GitHub Actions和部署运维。输入规范接收CI日志和部署状态。输出规范生成CI配置修改建议和故障排查报告。禁止事项不得修改业务代码只能操作CI/CD相关文件。权限控制通过GitHub的branch protection rules实现main分支只允许我手动合并feature分支允许Agent推送CI配置文件的修改需要我审批。3.3 CI/CD流水线的设计从代码提交到自动部署CI/CD流水线用的是GitHub Actions。整个流程分为四个阶段lint检查、单元测试、集成测试、部署。lint阶段用ruff做代码风格检查mypy做类型检查。这两个工具速度快能在几秒内发现问题。单元测试阶段用pytest跑所有测试用例覆盖率要求80%以上。Agent生成的测试用例质量参差不齐我加了一个规则如果覆盖率低于80%CI直接失败不允许合并。集成测试阶段会启动一个完整的服务实例用真实的数据跑一遍RAG检索和对话流程。这个阶段最慢大概需要3-5分钟但能发现单元测试覆盖不到的问题。部署阶段分两步先部署到staging环境跑一轮冒烟测试通过后再部署到production。部署用的是Docker Compose简单直接不需要K8s那么重的编排。# .github/workflows/ci.yml 核心配置 name: CI Pipeline on: push: branches: [feature/*, develop] pull_request: branches: [main] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: pip install ruff mypy - run: ruff check . - run: mypy src/ test: needs: lint runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - run: pip install -r requirements.txt - run: pytest --covsrc --cov-fail-under80 deploy: needs: test if: github.ref refs/heads/develop runs-on: ubuntu-latest steps: - run: docker compose up -d --build提示GitHub Actions的免费额度对私有仓库有限制如果CI跑得太频繁额度很快会用完。我的做法是只在push到feature分支和PR到main时触发CI日常的小修改用本地pre-commit hook做检查。4. 实操过程与核心环节实现4.1 第一周环境搭建与RAG基础链路跑通第一周的目标是搭好基础设施让RAG链路能跑通。具体任务包括仓库初始化、worktree配置、向量库部署、文档解析脚本编写、基础检索测试。仓库初始化没什么好说的git init之后建了main、develop、feature三个分支。worktree的配置前面讲过了三个Agent各一个目录。向量库我选了ChromaDB用Docker部署docker run -d -p 8000:8000 -v ./chroma-data:/data chromadb/chroma文档解析脚本是Builder生成的我做了几处修改增加了异常处理因为客户给的PDF里有不少损坏文件增加了日志记录方便追踪每个文件的处理状态增加了去重逻辑因为有些文档重复上传了好几次。第一周结束时RAG链路能跑通但检索效果一般。我拿20个典型问题做了测试准确率大概60%。主要问题是分块策略不合理很多关键信息被切断了。4.2 第二周检索调优与API开发第二周的重点是调优检索效果和开发API接口。检索调优我做了三件事调整分块参数、引入混合检索、增加重排序。分块参数从固定512改成了递归分割块大小256-1024动态调整。混合检索前面讲过了向量BM25RRF。重排序用的是bge-reranker-base对检索结果做二次排序把最相关的排到前面。这三板斧下来准确率从60%提升到了85%。剩下的15%主要是文档本身质量太差比如扫描件OCR错误太多或者问题超出了知识库范围。API开发用的是FastAPIBuilder生成的代码框架很标准我主要改了错误处理和日志记录。接口包括文档上传、文档删除、对话问答、历史记录查询、健康检查。# 对话问答接口的核心逻辑 app.post(/api/chat) async def chat(request: ChatRequest): # 检索相关文档 docs hybrid_search(request.question, top_k5) # 构建Prompt context \n\n.join([doc.content for doc in docs]) prompt f基于以下资料回答问题\n{context}\n\n问题{request.question} # 调用LLM生成答案 answer llm.generate(prompt) # 返回答案和引用来源 return {answer: answer, sources: [doc.metadata for doc in docs]}4.3 第三周CI/CD完善、测试与交付第三周是收尾阶段。CI/CD流水线在前两周已经基本跑通这周主要是完善细节增加了部署后的健康检查增加了回滚机制增加了告警通知。测试方面Checker生成了200多个测试用例我补充了30多个边界场景。最终覆盖率达到了87%超过了80%的目标。交付前我做了一轮完整的验收测试用客户提供的50个真实问题做测试准确率88%响应时间平均1.2秒。客户对这个结果很满意因为他们的预期是准确率70%以上就行。整个项目从启动到交付实际用时3周零2天。如果按传统方式做4个人2个月是保守估计。效率提升主要来自三个方面Agent承担了80%的编码工作CI/CD自动化了测试和部署worktree让多Agent并行成为可能。5. 常见问题与排查技巧实录5.1 RAG检索效果差的排查思路RAG检索效果差是最常见的问题。我的排查顺序是先看分块再看向量模型最后看检索策略。分块问题最容易发现也最容易解决。如果检索到的片段经常缺少关键信息或者一个片段里混了多个主题那就是分块参数不对。调整方法是拿几个典型问题手动看检索结果如果发现关键信息被切断了就增大块大小或增加重叠如果发现检索结果太泛就减小块大小。向量模型的问题比较隐蔽。如果检索结果和问题语义相近但用词不同向量模型可能没抓好语义。解决方法是换一个更强的向量模型或者增加关键词检索作为补充。检索策略的问题需要看具体场景。如果专有名词检索不到加BM25如果语义相近但用词不同的检索不到加向量如果两者都有问题用混合检索重排序。问题现象可能原因排查方法解决方案检索结果缺少关键信息分块太小或重叠不足检查检索片段的完整性增大块大小或重叠检索结果太泛分块太大检查片段是否混了多个主题减小块大小专有名词检索不到向量模型对专有名词不敏感用关键词检索测试增加BM25检索语义相近检索不到向量模型语义理解不足用同义词测试换向量模型或增加关键词检索结果排序不合理缺少重排序检查Top-5结果的相关性增加重排序模型5.2 多Agent协作中的冲突处理多Agent协作最大的问题是代码冲突。三个Agent同时改代码合并的时候很容易冲突。我的处理策略是文件级隔离Builder只改src/目录Checker只改tests/目录Runner只改.github/目录。这样三个Agent改的文件不重叠合并的时候不会冲突。分支级隔离每个Agent在自己的feature分支上工作合并到develop之前先rebase确保基线一致。提交粒度控制要求Agent每次提交只做一件事提交信息要清晰。这样出问题的时候容易回滚。如果还是冲突了我的处理方式是先看冲突的文件属于哪个Agent的职责范围然后让那个Agent重新生成代码而不是手动解决冲突。因为Agent生成的代码通常比手动合并的更一致。5.3 CI流水线失败的常见原因CI流水线失败的原因很多我整理了一个速查表失败阶段常见原因排查方法解决方案lint代码风格不符合规范看ruff输出让Builder重新生成lint类型检查失败看mypy输出补充类型注解test单元测试失败看pytest输出修复逻辑或更新测试test覆盖率不足看覆盖率报告补充测试用例deployDocker构建失败看构建日志检查依赖和配置deploy健康检查失败看服务日志检查端口和环境变量注意CI流水线失败的时候不要急着手动修复。先看是哪个Agent的职责范围让对应的Agent重新生成。手动修复容易引入新的问题而且会破坏Agent的工作流。5.4 实操心得与避坑技巧心得一Agent的Prompt要迭代。我一开始给Builder的Prompt很粗糙生成的代码质量不稳定。后来我加了具体的代码示例、错误处理规范、日志格式要求生成质量明显提升。Prompt不是写一次就完事的要根据实际输出不断调整。心得二CI的反馈要快。如果CI跑一次要10分钟Agent的迭代速度会大打折扣。我的做法是把lint和单元测试拆开lint几秒就跑完单元测试控制在2分钟以内。集成测试可以慢一点但不要超过5分钟。心得三worktree的清理要及时。worktree用久了会积累很多不用的目录占用磁盘空间。我每周清理一次删除已经合并的分支对应的worktree。心得四RAG的评估要量化。不要凭感觉说“检索效果不错”要拿具体的问题集做测试算准确率、召回率、响应时间。有了量化指标调优才有方向。心得五人工终审不能省。Agent生成的代码再规范也可能有逻辑错误或安全漏洞。我每个PR都会看一遍重点看边界处理、错误处理、安全相关的地方。这个时间省不得。6. 关于这套方法论的一些个人体会这套方法论不是万能的。它适合需求明确、技术栈标准、文档齐全的项目。如果需求模糊、技术栈冷门、文档缺失Agent能帮的忙就有限了。另外AI Agent的产出质量高度依赖你的输入质量。你给的接口定义越清晰Agent生成的代码越准确你给的文档越规范RAG的检索效果越好。Agent不是替你思考的是替你执行的。你得先把事情想清楚Agent才能帮你做快。最后说一个实际感受用了这套流程之后我最大的变化不是写代码更快了而是有更多时间思考架构和业务逻辑。以前80%的时间花在写代码和调bug上现在80%的时间花在设计方案和审查代码上。这个转变对我来说是正向的因为架构决策的质量比代码写的快慢重要得多。如果你也在做类似的项目建议先从一个小模块开始试跑通了再推广到整个项目。不要一上来就搞三个Agent并行先把一个Agent的工作流跑顺再逐步增加。