事件概述

通过对Claude Code（基于TypeScript/Bun运行时，约1900个源文件，51万+行代码）的深度源码分析，揭示了其如何将大模型能力封装为一套稳定的工程系统——Harness。该架构重点解决了Agent在真实场景中面临的工具并发、权限控制、记忆持久化及上下文压缩等核心工程问题，使AI从单纯的“对话生成”进化为能够“持续、安全地执行复杂任务”。

核心信息

1. 全链路处理流程

用户消息从终端输入到收到回复，需依次穿过UI层、编排层、核心层和服务层：

• 触发机制：核心组件REPL.tsx的onSubmit回调处理即时命令（如/clear直接执行，不经过模型）并恢复中断的上下文。
• 图片处理：独立管线处理剪贴板图片，优先调用原生API获取PNG字节，若失败则降级至系统脚本；随后执行多级压缩策略（尺寸缩放、调色板压缩、JPEG质量调整），确保符合API限制后转为Base64格式。
• 消息组装：文本与处理后的图片被封装为UserMessage进入查询循环。

2. 动态组装与成本优化（Prompt Caching）

系统提示词并非固定文本，而是由静态段落和动态段落并行组装而成，旨在最大化Anthropic API的Prompt Caching命中率（命中时可节省约90%成本）：

• 静态部分（缓存友好）：包括身份指令、编码哲学、工具使用指南等，标记为cache_control:ephemeral，服务端长期缓存。
• 动态部分（每轮刷新）：包含环境信息（当前目录、Git分支）、用户上下文（CLAUDE.md/MEMORY.md内容）、MCP指令及技能列表。
• 关键细节：工具列表按字母顺序排列，以确保缓存键的稳定性，避免因顺序变动导致缓存失效。

3. 核心引擎：查询循环与流式执行

查询循环（queryLoop）是一个while(true)结构，每轮迭代包含压缩检查、消息组装、API调用、响应处理及工具执行：

• 流式调度：StreamingToolExecutor是关键组件，根据工具的isConcurrencySafe标记进行智能调度。
  • 并行执行：Read、Grep等只读工具可立即并发启动。
  • 串行排队：Edit、Write等会修改文件系统的工具必须等待前序操作完成。
• 循环终止逻辑：不依赖不可靠的stop_reason字段，而是维护toolUseBlocks数组。只要检测到新的tool_use块，即追加工具结果并继续下一轮；否则循环结束。

4. 多层权限检查与风险判定

工具执行前需通过五步权限流水线，平衡自动化效率与安全性：

1. 否决规则：检查用户配置的显式禁止项。
2. 询问规则：检查需人工确认的配置。
3. 工具自身权限：如Bash命令结合shell-quote结构化解析与LLM语义分析，分为低、中、高风险。
4. 模式决策：根据权限模式（plan/default/auto/bypassPermissions）决定是直接拒绝、弹出确认框还是自动放行。
5. Hook一票否决：用户注册的PreToolUse钩子拥有最终否决权。

5. 四层记忆系统

为确保跨会话的持续性与上下文管理，系统构建了四层记忆机制：

• 第一层：CLAUDE.md：手动编写的项目规则，支持从根目录到当前工作目录的多级优先级加载，支持本地覆盖文件（.local.md）。
• 第二层：MEMORY.md：由后台子代理自动维护的跨会话记忆，记录架构决策和用户偏好，仅在特定Token阈值或对话阶段触发更新。
• 第三层：Session Memory：面向当前会话的运行摘要，记录进度状态，新会话启动时读取以延续上下文。
• 第四层：上下文压缩：当Token接近上限（如167,000）时触发。优先采用Session Memory摘要以避免额外API调用；其次采用Micro压缩（仅清空旧工具返回值）；最后才进行标准摘要替换。

值得关注

• 工程化价值：Claude Code的真正价值在于展示了Harness的核心理念，即通过子代理模式、流式执行、多层权限模型及缓存友好设计，将模型能力转化为可长期运行的系统。
• 局限性提示：由于项目代码量大且难以调试，文章结论指出其更适合外围赏析而非深度研究。对于希望系统性学习Harness架构的开发者，OpenClaw等更完整的项目可能提供更佳的体验。