一次关于“为什么生产级Agent必须学会做减法”的实战复盘01. 缘起给内部开发者配一个“懂代码”的飞书助手我们团队内部维护着大量的自研工具和软件。其中核心的XXX项目涉及多个私有代码仓库总代码量数万行文档采用渐进式披露的方式嵌在代码仓库里。日常工作中内部开发人员在使用这些工具时遇到报错高频地截图丢到群里问。“这个报错什么意思”“这个工具怎么又挂了”重复性问题消耗了大量人工答疑时间。我们决定做一个飞书机器人——一个能看懂报错截图、能翻源码、能查文档的AI Agent。用多模态模型识别截图内容用Qwen开源的几十B多模态模型做基座模型配上Pi Agent做底层的任务理解任务拆解调度代码分析等——让它像一个高级工程师一样在代码库里“自由翱翔”找答案。听起来很完美对吧现实给了我们一记响亮的耳光。02. 大坑当“自由Agent”陷入“10分钟魔咒”理想中秒回的机器人在实际内测中变成了“加载中”的噩梦。我们原本的方案很纯粹纯靠Agent自主决策。用户丢来报错截图多模态模型识别文字Agent开始在代码仓库里“掘地三尺”。我们提供的就是自带文档的多个代码仓库当然文档的内容质量我们是可以保障的——就是让Agent自己决定翻哪里、怎么翻。通过Langfuse链路追踪我们看到了触目惊心的一幕解决一个稍微复杂的问题Agent竟然需要发起50到100次的工具调用。它在干什么不断地用Grep试探关键词用Bash查目录结构用Read读疑似文件。因为上下文不够还要启动Sub-Agent去子目录里继续翻更让我们崩溃的是对比实验。我们使用了完全相同的Prompt让业界公认的Coding Agent标杆——Claude Code——来执行同样的任务。结果呢也需要10到15分钟。15分钟在飞书这种即时通讯场景下等一个机器人回复要一刻钟这根本不可用。不仅如此由于有时遇到未知的问题Agent偶尔还会脱离代码实际情况仅凭问题表面的通用知识胡诌答案。更糟糕的是因为耗时过长直接触发了我们设定的超时限制——用户连结果都等不到只看到一句“请求超时”。我们意识到飞书问答机器人和我们平时用coding agent寻找bug不一样用户不会等待那么长时间获得回答因此在这种场景下完全的“自由意志”是致命的。仅凭AGENTS.md以及一些文档然后靠agent调用多次工具来查找答案纯粹是在浪费Token和时间。Agent再聪明没有方向感也是白搭。03. 破局不要纯RAG也不要纯Agent要“粗搜精搜”分层针对这种问题我们下一步探索的解法是摒弃非黑即白的方案采用“粗搜混合检索定位区域” “精搜Coding Agent校验事实”的两阶段策略。第一步粗搜混合检索——解决“去哪看”这里的核心洞察是文档和代码分开处理。纯RAG向量检索搜代码一些致命伤它是语义搜索不是关键词精准搜索且会破坏代码之间的结构性和关联性。在源码阅读中我们更依赖精确的符号和关键词——函数名、类名、错误码这些东西差一个字就完全不一样。且RAG的分块很有可能把代码的层级关系和关联关系破坏掉所以我们对代码的搜索不用RAG。所以我们粗搜层采用BM25关键词精确匹配 RAG语义向量的混合检索而且主要针对文档部分而非源码。文档采用递归分块512 token保证检索颗粒度精准既有语义理解又有精确匹配。当用户发来报错截图时多模态模型先提取关键报错码和核心名词。粗搜层迅速在文档库中定位出“可能涉及的模块、配置项或变更记录”。这个阶段的目标很明确不求甚解但求缩小包围圈。告诉精搜层“这个问题大概率跟‘权限配置模块’和‘最新提交的Feature-X’有关重点去这几个文件里看。”第二步精搜Coding Agent——解决“是什么”有了粗搜提供的“嫌疑人名单”——具体的文件路径、函数名、相关文档片段——我们才把这个结论作为先验知识注入给Coding Agent。此时Coding Agent不再是蒙眼狂奔。它带着地图进场知道该读哪个文件、该查哪个函数。工具调用不再需要那么多的试探直接瞄准目标定向验证。粗搜负责广度和效率精搜负责深度和准确——各司其职互不干扰。当然这只是我们提出的一个可能的解决方案我们会在下周实施且在下一篇中说一下效果。如果你也在做类似的企业级AI Agent项目欢迎交流。踩过的坑值得让更多人绕过去。