Agent Harness 与 Claude Code

更新: 4/25/2026 字数: 0 字 时长: 0 分钟

全面解析Claude Code

Agent Harness，或者说是驾驭工程，是25年末提出的新的Agent开发的概念，是一个完整的对于Agent系统开发架构的总结

Harness的直译是马具，也就是驾驶马用的工具，这里是将大模型比作一个奔驰的野马，而我们的Agent系统就是驾驶这批马的马具，程序员是制造马具的人，为的是让骑马的人更好的骑马

当社区还在尝试Agent Harness的最佳实践时，最具戏剧性的事情发生了，Claude Code的npm仓库被爆出有安全隐患，导致Claude Code的核心代码泄露，大家纷纷fork代码进行学习，Agent Harness在全球顶尖厂商的实践也被我们得知了

Agent Harness 设计的哲学

异步流式优先

Claude Code 的对话建立在AsynGenerator上，让Agent可以在一个用户请求中执行多轮工具调用，每一轮都可以产生需要实时在线给用户的中间状态（思考过程，工具调用计划，执行进度）

成功的实现了：

• 增量输出：通过 yield 逐步产出流式事件，上层代码可以实时渲染。
• 可中断性：调用者可以随时通过 generator.return() 或 generator.throw() 终止生成器。
• 背压控制：如果消费者处理速度跟不上生产速度，生成器会自动暂停，避免内存溢出。

安全内嵌边界

LLM调用工具实际上是经过了多个安全检查点：

1. 工具可见性过滤：在将工具列表发送给 LLM 之前，根据权限规则过滤掉被禁止的工具。模型甚至无法"看到"它不应该使用的工具。
2. 输入校验：工具的 validateInput 方法在权限检查之前执行，拒绝格式不合法的参数。
3. 权限决策：canUseTool 回调综合考量权限模式（默认/Auto/Bypass）、工具的危险等级、用户的历史决策等因素，做出允许/拒绝/询问的决策。
4. 运行时防护：即使通过了上述检查，工具执行过程中仍有沙箱限制、超时控制、输出大小限制等防护措施。

只有多层的工具调用才保证了LLM调用工具的安全性

缓存感知设计

Claude Code的设计针对Anthropic的缓存设计做了专门的优化

• 系统 Prompt 稳定性：系统 Prompt 的构建方式被精心设计，确保在工具列表不变的情况下，Prompt 的字节内容保持一致，从而命中 API 侧的 Prompt 缓存。
• 子智能体的缓存共享：Fork 模式下的子智能体会继承父智能体的 renderedSystemPrompt，避免重新生成可能因配置变化而不同的 Prompt，保证缓存命中率。
• 消息历史的不可变性：已发送给 API 的消息不会被修改，只有追加新消息的操作，这保证了缓存键的稳定性。

渐进式能力扩展

Claude Code 提供了四级扩展模型，从内建到外部、从简单到复杂：

扩展级别	机制	适用场景	扩展者角色
工具（Tool）	实现 Tool 类型接口	添加新的原子操作能力	核心开发者
技能（Skill）	Markdown + 脚本的声明式工具	封装可复用的任务模板	高级用户
插件（Plugin）	带生命周期的工具包	组织相关工具和配置	生态开发者
MCP 服务器	标准化协议的外部工具集成	第三方工具生态	第三方开发者

不可变状态流转

Cluade Code的核心状态存储由一个极简的 store 实现完成。这个实现虽然简洁，但蕴含了重要的设计决策：

• Updater 函数模式：状态更新接收一个 (prev: T) => T 函数，而非新状态值本身。这确保了状态的每次更新都基于前一个状态，避免了竞态条件。
• 引用相等性检查：通过引用比较确保只有真正发生变化时才触发通知，避免不必要的重渲染
• 订阅/取消订阅模式：监听器通过集合管理，返回清理函数，防止内存泄漏。