Appearance
Claude Code Harness工程化解析：Agent架构设计的真正难点
Claude Code源码泄露展示了生产级AI Agent的完整设计：1900个文件、512000行TypeScript、Bun运行时、React+Ink终端UI——真正的难点在模型之外的Harness。
真正的难点：模型之外的Harness
Claude Code的架构核心是一个「Harness」本地运行时外壳。根据公开镜像仓库nirholas/claude-code，Claude Code的TypeScript源代码跨越约1900个文件，超过512000行严格类型的TypeScript，基于Bun运行时构建，用React和Ink驱动终端UI。
更像一个用于软件工作的操作系统：围绕模型堆叠了权限管理、记忆层、后台任务、IDE桥接、MCP管道和多代理编排。
Agent架构的三代演进
| 代际 | 特征 | 代表 |
|---|---|---|
| 第一代 | Chatbot，无状态问答 | — |
| 第二代 | Workflow，代码驱动的DAG流 | n8n、LangChain |
| 第三代 | Autonomous Agent，模型控制循环 | Claude Code |
Claude Code属于第三代：模型控制循环，运行时只是执行器。
TAOR Loop设计：Orchestrator越笨越稳定
Claude Code的执行引擎是TAOR循环：Think-Act-Observe-Repeat。
设计哲学：Orchestrator本身被设计得极其「愚蠢」，只负责驱动循环、执行工具调用、感知结果。所有推理、决策、何时停止，全部交给模型。
运行时越笨，架构越稳定。把智能下沉到模型，把确定性留给框架。
工具层遵循「笨」的哲学
Claude Code没有给模型配备100个专项工具，而是只提供四种能力原语：
| 原语 | 能力 |
|---|---|
| Read | 读取文件 |
| Write | 写入文件 |
| Execute | 执行命令 |
| Connect | 连接外部服务 |
Bash是通用适配器：允许模型使用任何人类开发者会用的工具——git、npm、docker，全部通过shell组合完成。
不要构建100个工具，给模型一个shell，让它自己组合。
脚手架随模型变强而变薄
随着模型变得更强，脚手架应该变薄，而不是变厚。硬编码的脚手架应该随着模型能力提升而被主动删除。
如果你每次模型升级都要往框架里加更多脚手架，说明你在对抗模型，而不是利用模型。
Context Window：稀缺资源，不是越大越好
Context不是越大越好，而是越干净越好。
Context Collapse：Agent系统最普遍的失败模式
随着对话进行，上下文窗口被填满，记忆退化，幻觉出现，Agent开始在自己积累的噪音里迷失方向。
Claude Code的三层防御
第一层：Auto-Compaction
当Context使用量达到约50%时自动触发，用LLM摘要替换原始对话轮次，释放空间的同时保留关键决策。
第二层：Sub-Agent隔离
把重型探索、研究任务卸载给独立的子Agent。子Agent运行自己独立的TAOR循环，有自己的Context预算，任务完成后只把摘要返回给主Agent。
第三层：Prompt Cache经济学
promptCacheBreakDetection.ts里追踪了14个cache-break向量。代码里还有一个函数叫DANGEROUS_uncachedSystemPromptSection()——命名本身就是文档：这里加东西要小心，会破坏缓存。
当你为每个token付费的时候，缓存失效不再是计算机科学笑话，更多的是一个财务问题。
Session Continuity
会话像git branch一样运作，可以checkpoint、rollback，或者把某个探索方向fork成新路径。Context的管理不只是在单次会话内，而是跨会话的。
记忆系统：核心是索引，不是存储
设计原则
能从代码库中重新推导出的信息，绝不应该被存储。
六层记忆架构
| 层级 | 内容 | 加载时机 |
|---|---|---|
| Managed Policy | 组织级策略 | 每次会话启动 |
| Project CLAUDE.md | 项目配置 | 每次会话启动 |
| User Preferences | 用户偏好 | 每次会话启动 |
| Auto-Memory | 自动学习模式 | 每次会话启动 |
| Session | 会话上下文 | 每次会话启动 |
| Sub-Agent Memory | 子Agent记忆 | 子Agent运行时 |
Auto-Memory循环：Agent从历史交互中学习用户模式，写入MEMORY.md供未来会话使用。
主动自我编辑能力：不仅会记录，还会重写、去重、甚至剪除互相矛盾的信息。过期且无效的记忆被视为「负债」而非资产。
权限系统：UX设计，信任是可组合的
五档信任光谱
| 级别 | 权限 | 信任程度 |
|---|---|---|
| plan | 只读，完全不能写入 | 最低 |
| default | 编辑和shell操作前都需要询问 | 标准模式 |
| acceptEdits | 自动批准文件编辑，shell操作仍需询问 | 中等信任 |
| dontAsk | 自动批准白名单内所有操作 | 高信任 |
| bypassPermissions | 跳过所有检查，仅限托管组织使用 | 最高信任 |
安全检查
bashSecurity.ts里有23项编号的安全检查：
- 18个被阻止的Zsh内置命令
- 防御Zsh equals expansion
- unicode零宽字符注入
- IFS null-byte注入
- HackerOne审查期间发现的恶意token绕过
底层认证机制
API请求在JS层之下做了身份验证。system.ts文件里，每个API请求都包含一个cch=00000占位符。在请求真正离开进程之前，Bun的原生HTTP栈会把这五个零替换成计算出的哈希值。
整个计算过程发生在JS层之下，对运行在JS里的任何代码都完全不可见。本质上是在HTTP传输层实现的API调用DRM。
多Agent编排：从Sub-Agent到Agent Teams
第一层：Sub-Agent
子Agent以独立进程方式运行，有自己的TAOR循环、Context预算、maxTurns上限、记忆。
三种预设子Agent：
| 类型 | 模型 | 工具 | 用途 |
|---|---|---|---|
| Explore | Haiku（快、低成本） | 只读工具 | 文件发现、代码库探索 |
| Plan | 继承主Agent模型 | 只读工具 | 代码库研究、规划信息收集 |
| General-purpose | 继承主Agent模型 | 全套工具 | 复杂多步骤操作 |
执行模式：
- 前台：阻塞主对话，权限询问透传用户
- 后台：并发运行，权限在启动前预收集
第二层：Agent Teams
完全独立的Claude Code实例通过共享文件系统协调任务。
协调机制：
- Shared Task List：所有Agent可见任务状态
- 单播Message：发给特定Teammate
- Broadcast：发给所有Teammate
- Automatic Idle Notification：Teammate完成停止时自动通知Lead
质量门控Hook：
- TeammateIdle：Teammate即将空闲时触发
- TaskCompleted：任务即将标记完成时触发
注：Agent Teams目前是实验性功能，需通过环境变量启用。
KAIROS：Always-On Agent
在泄露的源码中，有一个未发布的功能KAIROS——后台持续运行的Agent。
特征
- /dream技能：夜间记忆蒸馏
- 每日append-only日志
- GitHub Webhook订阅
- 后台Daemon工作进程
- 每5分钟的Cron调度刷新
产品形态
现有Claude Code：召唤式Agent——你打开终端，它来帮你；你关掉终端，它就停了。
KAIROS：常驻后台、持续学习、主动感知代码库变化的Autonomous Agent。不是你召唤它，它来帮你；而是它一直在，主动为你工作。
彩蛋：Anti-Distillation与Undercover Mode
Anti-Distillation机制
claude.ts第301-313行有一个ANTI_DISTILLATION_CC标志。开启时，Claude Code会在API请求里携带anti_distillation: ['fake_tools']参数，服务端会向系统提示中静默注入虚假的工具定义。
逻辑：如果有人在录制Claude Code的API流量来训练竞品模型，这些假工具会污染训练数据。
Undercover Mode
undercover.ts文件约90行，实现了一个单向门：当Claude Code在非Anthropic内部仓库里使用时，它会指示模型永远不提及内部代号、内部Slack频道、仓库名称，甚至不提及Claude Code这个名字本身。
There is NO force-OFF. This guards against model codename leaks.
你可以用CLAUDE_CODE_UNDERCOVER=1强制开启，但没有办法强制关闭。
总结
| 维度 | 设计原则 |
|---|---|
| Harness | 模型控制循环，运行时只是执行器 |
| TAOR | Orchestrator越笨，架构越稳定 |
| Context | 稀缺资源，Auto-Compaction + Sub-Agent隔离 |
| 记忆 | 索引不是存储，六层架构按需加载 |
| 权限 | UX设计，信任是可组合的 |
| 多Agent | Sub-Agent隔离Context，Agent Teams共享文件系统 |
Claude Code的产品野心已经远超「LLM + 命令行包装」，朝着「终端操作系统级Agent」方向前进。
关键词：Claude Code Harness, Agent架构, TAOR循环, Context管理, 记忆系统, 权限设计, 多Agent编排
