解码 Agent Harness——Claude Code 架构深度剖析

从零到精通，深入理解 AI 编程助手的核心架构与最佳实践

背景

2026 年 3 月 31 日，安全研究员 Chaofan Shou (@Fried_rice) 发现 Anthropic 发布在 npm registry 中的 @anthropic-ai/claude-code 包存在构建配置失误：source map 文件引用了未设访问控制的 Cloudflare R2 存储桶。披露推文获得超 1700 万次浏览，引发了技术社区对 Agent 架构的空前讨论。Anthropic 随后修补了该配置。

本书写作的初衷正是受到这场讨论的启发——当 Agent 架构成为开发者社区的热门话题，我们意识到需要一本系统性的书来讲解 Agent Harness 的设计原理。

⚠️ 免责声明 / Disclaimer

本书基于对 Claude Code 公开文档和产品行为的架构分析编写，未引用、未使用任何未公开或未授权的源码。Claude Code 为 Anthropic PBC 产品，本书不隶属于、未获授权于、也不代表 Anthropic。

This book is based on analysis of Claude Code's public documentation and product behavior. No unpublished or unauthorized source code is referenced or used.

这本书讲什么

不做使用教程，不列 Prompt 技巧。 本书带你拆解 Claude Code 的架构——对话循环如何驱动、工具权限为何采用四阶段管线、上下文压缩怎样在 token 预算内运转。

读懂了 Claude Code 的设计，你就拥有了一套可迁移到任何 Agent 框架的心智模型。

为什么值得读

架构代表性 — 涵盖 Agent Harness 全部核心子系统：工具类型、权限管线、上下文压缩、MCP 集成、子智能体调度
工程决策可追溯 — 为什么用流式异步生成器而非回调？为什么权限是四阶段管线而非黑白名单？每个决策背后都是真实生产场景的洞察
可迁移的认知 — 每章提炼通用设计模式，无论你用 LangChain、AutoGen 还是从零构建

适合谁读

读者	收获
想构建 Agent Harness 的架构师	完整的设计空间地图与工程权衡
不满足于调 API 的高级工程师	工具调用、流式处理、权限管控的底层机制
对 Agent 工程感兴趣的研究者	从实现角度理解 Agent 系统的运作方式
希望最大化利用 Claude Code 的实践者	理解设计意图，用得更准、调得更深

章节	标题	核心内容
第 1 章	智能体编程的新范式	Agent 范式转移、Harness 定义、全景架构
第 2 章	对话循环 — Agent 的心跳	流式异步主循环、错误恢复、turn 状态机
第 3 章	工具系统 — Agent 的双手	23 种工具、Schema 定义、并发安全、注册表
第 4 章	权限管线 — Agent 的护栏	四阶段权限检查、权限模式、用户审批流

第二部分：核心系统篇

章节	标题	核心内容
第 5 章	设置与配置 — Agent 的基因	分层配置、settings.json 体系、远程托管设置
第 6 章	记忆系统 — Agent 的长期记忆	持久化记忆、索引机制、自动提取、跨会话保持
第 7 章	上下文管理 — Agent 的工作记忆	Token 预算、上下文压缩、优先级排序
第 8 章	钩子系统 — Agent 的生命周期扩展点	Hook 规范、pre/post 执行、阻断控制

第三部分：高级模式篇

章节	标题	核心内容
第 9 章	子智能体与 Fork 模式	worktree 隔离、上下文继承、并行调度
第 10 章	协调器模式 — 多智能体编排	Coordinator 架构、Team 机制、任务分配
第 11 章	技能系统与插件架构	Skill 协议、Plugin 加载、扩展点设计
第 12 章	MCP 集成与外部协议	Model Context Protocol、Server 管理、协议桥接

第四部分：工程实践篇

章节	标题	核心内容
第 13 章	流式架构与性能优化	并行预取、惰性加载、Token 估算、启动优化
第 14 章	Plan 模式与结构化工作流	Plan/Act 分离、结构化审批、定时触发
第 15 章	构建你自己的 Agent Harness	从零实现 Mini Harness，融会贯通全书

附录

附录	标题
A	架构导航地图
B	工具完整清单
C	功能标志速查表
D	术语表

阅读路径

┌─────────────────────────────────────────────────────────┐
│  时间有限？                                               │
│  第 1-2 章（心智模型）→ 第 3-4 章（核心机制）→ 收工        │
├─────────────────────────────────────────────────────────┤
│  有经验的工程师？                                         │
│  直接第二部分 → 遇到概念缺口回溯第一部分 → 按需跳第三部分   │
├─────────────────────────────────────────────────────────┤
│  完整学习？                                               │
│  按顺序阅读 → 完成每章实战练习 → 第 15 章动手构建          │
└─────────────────────────────────────────────────────────┘

约定

中文写作，技术术语保留英文原文
每章结构：学习目标 → 核心概念 → 架构图 → 实战练习 → 关键要点
代码示例为说明设计模式的示意代码，非产品源码

贡献

欢迎提交 Issue 和 Pull Request：

修正技术错误或表述不准确之处
补充实战练习和案例分析
改进章节结构和可读性

致谢

Linux.Do

Star History

License

本书内容采用 CC BY-NC-SA 4.0 协议发布——可自由分享和改编，但须署名、非商业使用、并以相同协议共享。

claude-code-book