构建 AI Coding Agent：5 个关键设计决策

为什么要做 AI Coding Agent？

开发者工具的格局正在转变。GitHub Copilot 证明了 AI 可以自动补全代码。但我们问了一个不同的问题：如果 AI 能掌控整个开发工作流呢？

不仅仅是写代码，而是理解项目结构、运行测试、修复 bug、部署——同时在整个会话中保持上下文。

决策 1：工具优先架构

我们没有构建一个「无所不知」的单体模型，而是围绕工具调用架构来设计 PieBox。AI 代理可以访问一组定义明确的工具：

• 文件系统操作（读、写、搜索）
• Shell 命令执行
• 浏览器自动化
• 知识检索

interface Tool {
  name: string
  description: string
  parameters: z.ZodSchema
  execute: (params: unknown) => Promise<ToolResult>
}

这意味着模型不需要凭空「幻觉」出文件内容——它直接读取。不需要猜测命令输出——它直接执行。

决策 2：流式优先的执行模型

PieBox 中的每个操作都以流式方式实时返回结果给用户。这不仅是用户体验的选择——更是架构决策：

• 用户可以中断长时间运行的操作
• 上下文增量构建
• 错误即时暴露，而非累积到最后

决策 3：结构化上下文管理

AI 编码中最大的挑战不是生成代码——而是维护上下文。一个真实项目有数百个文件、复杂的依赖图和隐含的编码规范。

我们的解决方案：

1. AGENTS.md — 项目级指令，跨会话持久化
2. Explore 工具 — 智能代码库搜索，找到相关文件
3. 对话压缩 — 保留窗口中最相关的上下文

决策 4：快速失败，快速修复

我们的代理遵循严格的循环：

1. 写代码
2. 立即运行测试 / 类型检查
3. 如果失败 → 修复（最多 2 轮）
4. 如果仍然失败 → 停止并报告

这避免了 AI 代理的常见失败模式：悄悄生成有问题的代码然后继续往前走。

决策 5：委托给专家

不是每个问题都应该由通用模型来解决。PieBox 将特定任务路由到专业化的子代理：

• UI 工作 → UI 工程师（具备设计意识，了解组件库）
• 架构决策 → 顾问（看到完整上下文，给出果断答案）
• 代码库探索 → 探索器（快速、低成本、只读）

这反映了人类团队的工作方式——专家处理他们最擅长的事情。

下一步

我们正在继续推动 AI 编码代理自主能力的边界。目标不是取代开发者——而是让每位开发者拥有 10 人团队的杠杆。

敬请关注更多架构深度分析。