构建 AI Coding Agent 的 5 条血泪教训
如果你以为 AI coding agent 的核心竞争力是「选了一个好模型」，那你第一个月就会撞墙。真正决定 agent 好不好用的是上下文管理、错误恢复、工具设计和安全边界——全是工程问题。
经验 1：上下文是氧气，不是燃料
刚起步时我们的直觉是：「上下文窗口越大越好，把所有信息都塞进去」。但实践告诉我们：上下文不是越多越好，多出来的全是噪音。
一个 200K tokens 的上下文里，如果 150K 是冗余的工具调用历史、格式化日志和无用的文件内容，模型的有效注意力会被稀释。PieBox 现在的做法是：
- AGENTS.md 指令固定在 prompt 最前端——永远不被压缩掉
- 工具调用历史做增量压缩——保留前因后果，去掉纯日志输出
- 只加载与当前任务真正相关的文件片段，不全文导入
教训：token 预算是 agent 最稀缺的资源，只给模型它真正需要的东西。
经验 2：工具设计决定 agent 的能力上限
agent 能做什么取决于它有什么工具。但工具的粒度是个陷阱：太粗（一个「写代码」工具包揽所有）让模型需要自己判断太多事情，准确率暴跌；太细（readFile、writeFile、appendFile 分三个工具）增加调用次数和延迟。
PieBox 的策略是工具分层：
- 粗粒度工具（explore、deploy）给规划层用——让模型做宏观决策
- 细粒度工具（bash、edit、read）给执行层用——精确操作文件系统
教训：好工具不是功能多，是让模型在两步之内就能把一件事做完。
经验 3：失败恢复比成功执行更重要
一个 agent 跑 10 分钟，中间任何一个环节崩了——文件写一半、测试挂了、命令权限不够——都会导致整个任务报废。
我们经历过最惨痛的一次：agent 重构了 17 个文件，在最后一个文件上因为类型错误改坏了接口签名，然后它「自信地」继续推进到下一步。等到发现时，前面 16 个文件的改动已经和新的接口签名不一致了。
PieBox 现在的做法：
- 每次文件操作后立即跑类型检查
- 失败最多自动修复 2 轮，超过就停止并要求人工介入
- 关键步骤（修改公共接口、删除文件）加确认检查点
教训：宁可 agent 停下来问你，也不能让它带着错误继续跑。
经验 4：不要迷信单一模型
早期我们全链路用 GPT-4，效果不错但成本太高。后来全切 DeepSeek，成本降了但稳定性下降。最终发现最优解是「联邦模型」——不同阶段用不同模型。
当前 PieBox 的默认路由：
- 规划阶段 → DeepSeek-R1（推理强）
- 代码生成 → GPT-4o 或 Claude（精准）
- 探索文件 → 轻量模型（快、便宜）
教训：没有一个模型在所有环节都是最优解。agent 的能力不应该被单一模型的天花板锁死。
经验 5：用户觉得「聪明」不等于工程做得好
最反直觉的经验：用户对 agent 的评价标准和它的工程复杂度几乎没有关系。用户觉得 agent 「聪明」的时刻往往是：它猜对了用户没说出来的意图、它在你打断前就做对了、它失败后能清晰告诉你为什么。
而这些体验背后全是工程细节：快速失败反馈、清晰的错误信息、可恢复的操作、不需要用户猜的状态展示。agent 的「聪明」不是模型能力，是工程体验的副产品。
这五条经验里没有一条是关于「如何训一个更好的模型」。做了一年多我们才真正理解：AI coding agent 本质上是一个分布式系统问题——模型的推理能力只是其中一环，更重要的是如何让这个系统和用户、文件系统、工具链安全高效地协作。
PieBox 正是基于这些经验构建的。如果你也在做 agent 或者想找一个真正工程驱动的 AI 编码工具，欢迎试试 PieBox。