深度拆解 Claude Code 源码

深度拆解 Claude Code 源码：51万行代码背后的 Agent 工程哲学，以及我们做的开源复刻版

大家好，我是 xcoder 的作者。

上个月 Claude Code 源码意外曝光的事，相信很多人都有所耳闻——一次部署失误把 source map 打进了 npm 包，51 万行 TypeScript、4700+ 个文件完整暴露在世人面前。

作为一个天天泡在终端里写代码的人，我花了整整一周啃完了核心源码。今天这篇文章，不聊八卦，只讲干货：Claude Code 真正强在哪？它的架构设计有哪些值得我们学习的地方？以及，基于这些思考，我做了一个什么样的开源项目？

一、先打破一个误区：Claude Code 不是"终端版 ChatGPT"

很多人第一次用 Claude Code，觉得这不就是个能跑命令的聊天机器人吗？

错。

如果你只把它当成"终端里的大模型"，你就彻底低估了它。Claude Code 的本质是一个面向软件工程的 Agent 运行时（Agent Runtime）——模型只是中间的一层，真正让它好用、可控、能落地的，是外围那套极其完善的工程化基础设施。

先看一组数字：

564 个工具函数文件
389 个 UI 组件
184 个内置工具
130 个服务模块
104 个自定义 Hook

这不是一个 demo，这是一个生产级的操作系统级别的工程。

二、核心引擎：一个 88 行的 while 循环，撑起了整个 Agent

最反直觉的一点：Claude Code 的核心执行引擎，简单到不可思议。

整个系统的心脏在 query.ts 里，就是一个 queryLoop 异步生成器：

调模型 → 模型返回工具调用？

├─ 否 → 输出文本给用户，结束

└─ 是 → 权限检查 → 执行工具 → 收集结果 → 回到开头

没有意图分类器，没有复杂的 DAG 编排，没有规划器与执行器的拆分。所有决策由模型自己做，代码只负责提供确定性的基础设施。

这是一种非常高明的设计哲学：

最小化决策脚手架，最大化工程基础设施。

把不确定性的事（意图理解、任务规划）交给模型，把确定性的事（权限检查、上下文管理、错误恢复、成本控制）用代码严格保证。

但这个循环绝不是玩具——它内置了 10 种终止条件和 7 条恢复路径：

最大输出 token 递增重试（每轮最多 3 次）
反应式上下文压缩（每轮最多触发一次）
上下文溢出时的三级降级策略
流式回退和后备模型自动切换

这才是生产级 Agent 和玩具 Demo 的核心区别。

三、工具系统：三层架构，解耦到极致

工具是 Agent 与世界交互的唯一通道。Claude Code 的工具系统采用了经典的三层架构：

层级职责核心设计

Tool Registry 声明 Schema 和默认权限 name, description, input_schema, permission_level

Dispatcher 将 LLM 调用路由到具体实现工具名 → 实现函数的映射表

Implementation 执行实际逻辑，返回结构化结果 execute(input): ToolResult

这个设计最精妙的地方在于：工具的 JSON Schema 直接透传给 LLM。

这意味着什么？

模型与具体实现完全解耦
工具接口是语言无关的
新增工具只需要写 Schema + 实现，不需要改提示词

180 多个工具，按职责划分为五大类：

文件操作：Read / Write / Edit / MultiEdit / Glob / Grep
Shell 执行：Bash / PowerShell / REPL
Agent 协作：Subagent / Task / Team
规划系统：EnterPlan / ExitPlan / VerifyPlan
网络与扩展：WebFetch / WebSearch / MCP

其中最值得一说的是 Subagent 子代理机制——主 Agent 可以生成一个拥有独立上下文和工具集的子 Agent 实例，本质上是递归调用 query.ts。理论上支持无限嵌套，复杂任务可以无限拆解。

四、上下文管理：五层压缩流水线

很多人好奇：Claude Code 跑长任务为什么不跑偏？上下文那么长为什么还很快？

答案是它有一套五层的上下文压缩流水线：

Snip（裁剪）：截断过长的工具输出，只保留首尾
Compact（压缩）：用模型对历史消息做摘要重写
Collapse（折叠）：将多轮工具调用合并为单条总结
Memory Extract（记忆提取）：从对话中抽取持久化记忆
System Prompt（系统提示）：CLAUDE.md + 模式配置 + 规则文件

并且这套压缩是反应式的——不是定时触发，而是在每轮循环前检查上下文余量，按需触发。这也是为什么它能在 200k 上下文的模型上跑几千行代码的重构任务。

五、然后呢？我们做了 Xcoder

看懂了这些设计之后，我开始思考：这么好的架构，能不能开源出来？能不能加上我们想要的功能？

于是有了 Xcoder——基于 Claude Code Best（CCB）逆向还原项目进行的大规模二次开发。

坦诚地说，核心引擎的架构我们继承自上游。但在这之上，我们注入了大量原创的思考和设计：

✨ 6 种人格模式系统，一键切换

这是 Xcoder 最有辨识度的原创功能。不只是换个主题色，每种模式是一整套完整配置：性格 + 工具集 + 权限 + UI 风格。

模式性格适用场景

默认专业平衡日常编码

温柔耐心鼓励学习新技术

Dr. Sharp 心理手术刀思路卡壳时

苦力高效零废话批量搬砖

省 Token 简洁精准预算有限时

超级 AI 全能主动复杂重构

输入 /mode sharp 或者直接 /sharp，瞬间切换人格。写代码写累了，切到温柔模式让 AI 鼓励鼓励你；思路混乱了，切到 Dr. Sharp 帮你做三阶段认知手术。

🔍 代码问责面板

AI 改完代码就完事了？不行。

Xcoder 强制展示 diff 并追问修改理由，每一次改动都有决策日志。不让 AI 成为黑盒，每一行代码的修改都要有迹可循。

🌐 7 家模型供应商，自由切换

原版只支持 Anthropic。我们在原生架构上扩展了统一抽象层，现在支持：

Anthropic 原生
OpenAI 兼容（Ollama / DeepSeek / vLLM）
Google Gemini
xAI Grok
AWS Bedrock
Google Vertex
Azure Foundry

想用哪家用哪家，本地模型也能跑完整 Agent 能力。

🎤 语音输入 + 🌐 浏览器自动化 + 📱 远程控制

这些都是原版没有的能力：

对着麦克风说话就能写代码（豆包 ASR）
内置 Chrome Use，自动操作浏览器、填表单、抓数据
Docker 部署远程界面，手机上也能看 Xcoder 干活

💰 穷鬼模式

输入 /poor 一键开启。跳过记忆提取、提示建议和验证代理，Token 消耗直接砍半。学生党和个人开发者友好。

六、一键安装，开箱即用

macOS / Linux

bash <(curl -fsSL https://raw.githubusercontent.com/YuanyuanMa03/xcoder/main/scripts/install.sh)

Windows

irm https://raw.githubusercontent.com/YuanyuanMa03/xcoder/main/scripts/install.ps1 | iex

npm 安装（需 Node.js >= 18）

npm install -g @yuanyuan20031001/xcoder

安装完成后输入 xcoder 启动，首次使用输入 /login 配置你的 API 即可。

七、写在最后

做这个项目的初衷很简单：好的架构不应该被闭源锁死。

Claude Code 证明了终端原生的 Code Agent 这条路是走得通的，而且体验远超 IDE 插件。但它闭源、只支持自家模型、没有个性化、价格也不便宜。

Xcoder 想做的，就是把这套优秀的架构开源出来，加上更多接地气的功能，让每个人都能用得上、改得了。

项目完全开源，地址在这里：

👉 https://github.com/YuanyuanMa03/xcoder

如果你觉得这个项目不错，欢迎给个 Star。有任何想法或者想贡献代码，也欢迎提 Issue 和 PR。

人机协作的边界在哪？我不知道。但我知道，这件事需要更多人一起探索。

互动时间

你平时用什么 AI 编程工具？最在意哪个功能？评论区聊聊～

觉得文章有帮助的话，欢迎点赞 + 在看 + 转发三连，后续会带来更多 Claude Code 源码深度拆解系列。