25.3 避免的陷阱
模型: gpt-5.4 (openai/gpt-5.4) 生成日期: 2026-04-01 书名: AI编码智能体 章节: 第25章 — 构建你自己的智能体 Token 消耗: ~4,350 输入 + ~1,420 输出
一旦你开始构建自己的智能体，真正的危险通常不是缺乏想象力，而是野心放错了方向。很多构建者看到 OpenCode、Oh-My-OpenCode、Claude Code 这类成熟系统，就误以为成熟来自功能数量。实际上，很多早期智能体项目恰恰是因为复杂性增长得比证据更快，最后把自己拖垮。
这里重点谈四类高频陷阱：工具膨胀、过度工程化、忽视安全，以及试图让一个智能体解决所有问题。
25.3.1 陷阱一：工具膨胀
所谓 tool bloat（工具膨胀），就是每观察到一次失败，就新增一个工具。没找到文件，就加仓库地图；改坏了文件，就加 patch tool、refactor tool、review tool；被长输出弄糊涂了，就再加 summarizer、compressor、smart context service。
结果往往不是更强，而是更差。因为每增加一个工具，模型就多了一层选择复杂度。它不只要决定“做什么”，还要决定“该调用哪个接口、它和相邻接口有什么差别、什么时候才安全”。工具功能重叠还会带来隐性不稳定：两个搜索工具、三个编辑工具、四种结构获取方式，语义却并不完全相同。
解决办法是纪律。不要因为单次失败就加工具。只有当某类失败反复出现，并且明确不能通过更清晰的提示词、更紧凑的输出、或更好的既有工具组合解决时，才值得新增工具。
25.3.2 陷阱二：第一版就过度工程化
第二类陷阱，是在版本一还没跑通之前，就开始设计版本三。
这种情况在架构图上通常非常壮观：provider 抽象、技能系统、权限中间层、多智能体路由、分层记忆、插件 SDK、后台任务、工作流图、评测面板、企业策略钩子。每个组件单独看都很合理，问题在于时机。
如果基础执行循环本身还不可靠，这些附加层并不会自动把产品变好。它们只会制造更多隐藏故障的位置。你可能花了几个月把扩展表面做得很漂亮，但系统仍然不能稳定地读文件、做边界清晰的修改、执行验证。
正确顺序很朴素：先证明一个小而稳的执行环真的能工作，再在真实需求推动下往上长结构。
25.3.3 陷阱三：因为本地或内部就忽视安全
智能体构建者经常把安全往后放，因为第一批用户是可信同事，或者系统只跑在本地机器上。这是很短视的。
即便是本地智能体，也可能执行破坏性 shell 命令、覆盖文件、在日志里泄漏凭据、跟随仓库里的恶意指令、调用不安全的外部工具。内部不是 threat model（威胁模型，即攻击面、风险来源、损害后果的系统性分析），它只是一个很容易失效的乐观假设。
智能体安全应该从 capability boundary（能力边界）开始想：哪些工具可以写文件？哪些工具可以执行命令？哪些工具能联网？允许操作哪些路径？哪些操作必须人工确认？输出里如何过滤密钥？第三方扩展如何隔离？
你当然不必第一天就做企业级策略系统，但第一天就应该有威胁模型。
25.3.4 陷阱四：试图覆盖所有用例
另一种高频失败模式，是普适主义冲动。构建者希望一个智能体同时充当程序员、研究员、运维助手、浏览器自动化工具、企业搜索层、文档写手、数据分析器和终端副驾驶。
这种广泛野心可以理解，但通用性不是免费的。不同任务需要不同工具、不同安全边界、不同评估标准，有时甚至需要完全不同的交互形态。一个针对代码修改优化的智能体，并不会自动对网页工作流或数据管道同样优秀。
更健康的方式，是先选择一个足够尖锐的工作负载。比如你先让智能体特别擅长仓库内工程任务；或者特别擅长测试修复；或者专注某一种语言的重构。聚焦不是弱点，而是质量出现的前提。
25.3.5 次级陷阱：把 Demo 成功误当成产品成熟
有些系统在精心准备的演示里很惊艳，因为仓库很干净、任务很窄、验证路径很清楚。但真实世界不是这样。真实仓库往往混乱、权限不一致、脚本会失败、依赖会漂移、需求还含糊不清。
如果构建者只为 demo 时刻优化，就会系统性低估错误处理、断点恢复和信任校准的重要性。这样的产品在台上看起来像魔法，进了日常工程环境后就会迅速暴露脆弱性。
25.3.6 次级陷阱：验证太弱
很多智能体构建者把主要精力放在生成上，却忽略验证。但对 coding agent 来说，只会产出、不做检查，并不等于可靠，只等于更有自信地猜。
验证在早期可以很简单：跑测试、看 diff、检查诊断、确认文件是否存在、验证 schema 是否有效。关键不是验证多复杂，而是验证必须是流程的一部分，而不是可有可无的收尾动作。一个会自信修改、却很少认真验证的智能体，迟早会积累隐藏缺陷。
25.3.7 次级陷阱：把所有保障都压给模型自己记住
语言模型很灵活，但不应该承担本来该由 scaffold（脚手架，即围绕模型构建的执行框架与约束层）保证的东西。如果安全路径能在工具层强制，就不要只在提示词里提醒；如果危险命令需要确认，就让执行层真的拦住；如果 Token 成本必须记录，就在外部做埋点；如果输出需要结构化解析，就定义 schema。
一个很好用的原则是：凡是软件可以强制保证的，不要只靠模型“记住”去保证。
25.3.8 更健康的默认哲学
为了避免这些陷阱，你可以采用一种更克制的默认哲学：初始工具集保持小、只有在反复证据出现后才加抽象、尽早建立真实威胁模型、先选窄场景再慢慢扩张、把验证做成强制环节。
真正强的智能体系统，不是第一天就试图做最多的系统，而是能一层层长大、同时不丢失整体一致性的系统。
如果要说一个元陷阱，那就是误以为成熟来自不断添加。很多时候，成熟恰恰来自在真正理解当前层之前，拒绝继续添加。