Claude Code 核心架构分析与 Agent 公司借鉴路径

Claude Code 核心架构分析与 Agent 公司借鉴路径

一、 Claude Code 核心架构剖析

Claude Code 是一个纯本地运行、深度集成于终端的 AI 智能体应用。它的源码结构（特别是 src/ 目录下）清晰地展示了 Anthropic 在构建生产级 Agent 时的工程化思考。

1. 核心运行循环：QueryEngine

QueryEngine 是整个 Agent 的大脑和心脏（核心代码位于 QueryEngine.ts 和 query.ts）。

• 职责：维护单次或多次对话的生命周期（Agent Loop），包括状态管理、权限控制（Permission Mode）、API 调用及 Fallback（降级重试）机制。
• 特点：它并非简单的请求/响应模型，而是内置了一个微型的任务调度器。支持中途打断、等待用户授权（Hook 拦截）、自动重试等复杂交互。

2. 极致的上下文与记忆管理 (Context & Memory)

针对大语言模型（LLM）的 Context Window 和 Token 成本，Claude Code 设计了一套非常精细的管理机制：

• Prompt Caching：将 System Prompt 分为全局静态层和会话动态层（参见 prompts.ts 的 SYSTEM_PROMPT_DYNAMIC_BOUNDARY）。静态层可以跨会话被缓存（命中 Anthropic 的 Prompt Caching），极大降低了高频调用的延迟和成本。
• Auto Compaction (上下文压缩)：当对话历史接近 Token 上限时（核心代码位于 autoCompact.ts），它会触发后台总结任务，将漫长的历史步骤进行折叠（Context Collapse）或微压缩（Microcompact），只保留关键决策树和最终结论，防止 Token 爆炸。
• MemDir (记忆目录)：支持项目级别的记忆持久化（src/memdir/），Agent 可以把重要的项目背景、规范记录到特定的记忆目录中，避免每次启动都要重新探索。

3. 工具生态与标准扩展 (Tool & MCP)

• Native Tools：内置了细粒度的文件与系统操作工具（如 BashTool、FileReadTool、FileEditTool、GlobTool、GrepTool 等）。值得注意的是，它没有用一个笼统的“执行命令”工具包打天下，而是将不同意图拆分为高内聚的单一工具。
• MCP (Model Context Protocol)：原生集成 MCP 客户端（src/services/mcp/）。这使得 Claude Code 可以不修改核心代码，通过标准化协议直接挂载外部数据库、API 或者其他工具集。
• AgentTool (子智能体)：支持 Fork Sub-agent 机制。遇到耗时或者需要独立探索的复杂任务时，主 Agent 可以拉起一个独立的 exploreAgent，分治解决后再汇总结果。

4. 终端原生交互 (CLI UI/UX)

• 基于 React Ink 构建的 CLI 界面（src/ink/ 与 src/components/），让纯文本的终端具备了流式输出、进度条更新、组件级局部刷新的能力。极大地缓解了 Agent 执行长耗时任务时的“黑盒焦虑”。

二、 普通 Agent 公司最值得借鉴的地方

1. 不要再把所有历史记录“傻傻地”塞给大模型

   • 借鉴点：长文本的注意力衰减和成本是灾难性的。必须实现类似 autoCompact 的滑动窗口总结机制。不仅要总结用户的意图，还要把中间那些失败的 Tool Calls、冗长的报错堆栈“折叠”起来。

2. 全面拥抱 MCP 协议（放弃硬编码集成）

   • 借鉴点：传统的做法是为每个 SaaS 或本地能力写一套 API 集成代码，维护成本极高。未来属于 MCP，让你的 Agent 底层只实现一个 MCP Client，然后直接复用社区成百上千的 MCP Servers（如 GitHub、Notion、Postgres 等），这是建立生态护城河的最快方法。

3. 工程化的细粒度工具链

   • 借鉴点：对于代码编辑，不要只给大模型一个简单的 replace 工具。Claude Code 的工具粒度非常细（精确到 Grep 搜索和 AST 级别的编辑）。工具的精细度和容错率，决定了 Agent 的落地能力上限。

4. 任务的分治与 Sub-Agent 模式

   • 借鉴点：单体 Agent 处理复杂链路极易产生幻觉或迷失。学习 AgentTool，在主循环中遇到“探索代码库”、“调试特定 bug”等子任务时，派发给一个隔离了上下文的子 Agent（甚至使用更便宜的模型），只把最终结果返回给主进程。

5. 交互即正义：透明的思考与执行过程

   • 借鉴点：用户往往不信任后台静默执行的 Agent。借鉴 React Ink 的做法，将大模型的“思考流”（Thinking）、“执行命令的实时输出”、“文件读取进度”实时呈现给用户，哪怕只是展示一个 Spinner，也能大幅提升信任感。

三、 最快落地解决方案与模仿路径 (Fast Landing Solution)

如果您是一家普通的 AI Agent 创业公司，希望最快复刻或借鉴这套架构，请遵循以下三步落地路径：

阶段 1：MVP 构建（1-2 周）—— 跑通核心循环与 MCP

• 技术选型：Node.js / TypeScript + Vercel AI SDK (或 LangChain)
• 核心动作：
  1. 不要从零写大模型接口和流式解析，直接使用 Vercel AI SDK 提供的 streamText 和原生的 tools 字段。
  2. 放弃手写业务工具。直接引入 @modelcontextprotocol/sdk。让你的系统只需要两步：连接用户的 MCP Server -> 将工具 Schema 注入给大模型。
  3. 如果做 CLI 客户端，直接使用 @clack/prompts 或 Ink；如果做 Web，使用 Next.js 的原生流式 UI。
• 里程碑：拥有一个能通过标准协议挂载工具、与大模型进行交互的基础 Agent 闭环。

阶段 2：体验与降本优化（2-3 周）—— 引入 Context 管理

• 核心动作：
  1. 实现 Prompt Caching：在调用 LLM 前对 Messages 数组进行预处理。将不会变动的 System Prompt 和 Tools Schema 加上 cache_control 标记。
  2. 实现 Auto Compaction：写一个 Middleware 拦截器。每次请求前计算 Token 数（使用 tiktoken 估算），一旦超过阈值（如 20k tokens），立刻开一个后台子线程，用一个小模型将最早的 N 轮对话和中间的废弃试错总结为一段简要记录，替换掉原始长文本。
  3. 实现细粒度文件工具：参考 Claude Code，至少提供四个核心工具：search_files (Glob), search_code (Grep), read_file (按行/分页读取), edit_file (基于块替换，坚决不要让 LLM 重写整个文件)。

阶段 3：复杂任务突围（1 个月）—— 引入多 Agent 分发与持久化

• 核心动作：
  1. Sub-Agent 分发机制：将主 Agent 包装为一个 Tool 给自己调用。当模型判断任务需要探索时，触发 Spawn_Sub_Agent 工具，传入目标和独立上下文，阻塞主进程等待结果返回。
  2. 工作区记忆 (MemDir)：在用户项目根目录创建一个隐藏文件夹（如 .agent_memory/）。每次长周期任务结束后，强制大模型总结“这个项目的架构特点或踩坑记录”并写入该目录。下次启动时，自动读取这些文件并注入 System Prompt。
  3. 安全审批流 (Approval Flow)：所有导致状态变更的工具（Bash 执行、FileEdit），在执行前必须在 UI 层挂起，等待用户点击 Approve 授权，保障生产环境安全。

总结：不要陷入重复造轮子（手写 API 对接、写死板的提示词）的泥潭。“基于 MCP 构建标准化扩展底座 + 精细的 Token 上下文压缩管理 + 流式透明的交互 UI”，这是普通公司通往工业级 Agent 的最快、最稳妥的路径。