51.2 万行 TypeScript · 1,902 个文件 · 单系统深潜 · 不做任何对比
这一篇只讲 Claude Code 一个系统。不和任何其他项目对比，不讨论「别人怎么做」，只回答一个问题：这个系统是怎么造出来的？
从进程启动的第一行代码，到最后一条消息落盘，逐层拆开每一个子系统 —— 包括那些在对照式文章里通常被跳过的部分：终端界面层怎么渲染、会话怎么恢复、埋点体系怎么组织、单文件可执行程序怎么构建出来。
阅读门槛：不需要人工智能背景。所有概念在首次出现时都会解释。如果你完全没接触过大语言模型，建议先读《合刊》那一篇的第 1 章（零基础前置知识），大约 20 分钟，之后再回来。
Claude Code 是一个在终端里运行的编程助手。你在命令行里敲 claude，进入一个可以持续对话的界面，然后用自然语言让它帮你读代码、改代码、跑测试、提交 git。
它和普通聊天机器人的区别是：它会真的动手操作你的电脑 —— 读文件、写文件、执行 shell 命令。这个能力也正是它全部工程复杂度的来源。
| 属性 | 值 |
|---|---|
| 开发方 | Anthropic |
| 编程语言 | TypeScript |
| 运行环境 | Bun —— 一个比 Node.js 更快的 JavaScript 运行时，而且能把整个程序打包成单个可执行文件 |
| 界面框架 | React + Ink —— Ink 是「用 React 写终端界面」的框架，把 React 组件渲染成终端里的文字 |
| 代码规模 | 1,902 个 .ts / .tsx 文件，51.2 万行 |
| 源码来源 | 2026 年 3 月 31 日因 npm 包附带的 source map（源码映射文件）配置失误而泄露。它不是开源项目。 |
为什么文件后缀有 .ts 和 .tsx 两种？.tsx 是包含 JSX 语法（也就是在代码里直接写 HTML 式标签）的 TypeScript 文件，用于写界面组件。.ts 是纯逻辑文件。
下面是 src/ 目录下的全部内容。括号里是文件数量，可以直观看出各部分的体量分布：
| 核心逻辑（刻意保持很小） | 外围模块（放任臃肿） |
|---|---|
query.ts 主循环 —— 1,730 行Tool.ts 工具契约 —— 793 行toolOrchestration.ts —— 189 行tools.ts 注册表 —— 390 行
|
screens/REPL.tsx —— 875 KBmain.tsx —— 804 KBcomponents/PromptInput.tsx —— 347 KButils/messages.ts —— 189 KB
|
这不是疏忽，是有意识的取舍：核心抽象要小到能被一个人完整读懂并测试；边缘代码可以脏，因为它们改动频繁、逻辑分支多、而且出错的后果有限。
utils/ 有 331 个文件，说明什么utils（工具函数）目录通常是一个项目的「杂物间」。331 个文件是个惊人的数字 —— 但翻开看会发现它并不是真的杂乱，里面有清晰的二级分组：
utils/permissions/ —— 21 个文件，是完整的权限子系统utils/bash/ —— shell 命令的词法分析器和抽象语法树（bashParser.ts 128 KB + ast.ts 109 KB）utils/plugins/ —— 插件加载器 107 KB + 市场管理 91 KB这些本可以是独立的顶级目录。它们被塞进 utils/，更可能是历史原因（先写成小工具函数，后来长大了但没搬家）。这是一个真实项目的正常样貌 —— 值得注意的是它们内部依然是分组清晰的。
tools/ 和 commands/ 是最关键的一条切分线tools/（40 个） | commands/（约 100 个） | |
|---|---|---|
| 谁能触发 | 模型。模型输出一个「工具调用」请求，程序执行它 | 只有人。用户在终端敲 /compact、/resume 这样的命令 |
| 进不进上下文 | 进。每个工具的说明文字都要放进系统提示词，每一轮都要重新发给模型、重新付费 | 不进。模型完全不知道这些命令的存在 |
| 走不走权限判定 | 走。每次调用都要过一条 10 步的判定链 | 不走。用户自己敲的，视为已授权 |
| 典型例子 | Read（读文件）、Bash（执行命令）、Edit（改文件） | /model 换模型、/cost 看花费、/doctor 诊断 |
这条线解释了「技能」（Skill）这个功能存在的意义：技能是一座把命令变成工具的桥。
有些能力，用户希望模型能自己判断何时使用（所以应该是工具），但内容又像命令一样是「一段固定的操作流程」。技能系统让这类内容以工具的形式暴露给模型 —— 第 9 章会详细讲。
下面这条路径把 14 章串起来。建议先扫一遍，建立整体印象，再逐章深入。
| 章 | 标题 | 核心内容 |
|---|---|---|
| 1 | 入口层与启动流程 | 四种启动形态、60 多个命令行选项、启动时序、--bare 极简模式 |
| 2 | 会话层：QueryEngine | 一场对话的完整生命周期、状态所有权、消息落盘时机 |
| 3 | 智能体主循环 | ★ 状态机、7 条恢复路径、错误扣留、中断处理、模型降级 |
| 4 | 工具模型 | Tool 接口的七组能力、失败保守默认值、工具清单装配与缓存 |
| 5 | 工具执行 | 并发分区、流式执行器、两级中止作用域、单次执行的完整流程 |
| 6 | 上下文治理 | ★ 五级阶梯、缓存编辑、时间触发、摘要提示词工程 |
| 7 | 权限系统 | 10 步判定链、bypass 免疫层、自动模式分类器、权限规则语法、沙箱 |
| 8 | 子智能体 | 三种形态、分叉的字节级缓存复用、工具限制、后台任务 |
| 9 | 扩展体系 | 技能、插件、MCP 客户端、15 类钩子事件 |
| 10 | 终端界面层 | React Ink 架构、146 个组件、虚拟消息列表、输入框的复杂度 |
| 11 | 持久化与恢复 | JSONL 对话记录、写入队列、--resume、文件历史与回滚 |
| 12 | 可观测体系 | 埋点密度、事件命名、缓存断裂检测、性能剖析检查点 |
| 13 | 构建与分发 | Bun 单文件打包、编译期特性开关、死代码消除、版本管理 |