1. 先搞清楚51 万行 TypeScript 到底在写什么Claude Code 的源码被逆向还原后公开1884 个 TypeScript 文件、src/ 目录约 9.8 万行核心代码、42 个工具模块、189 个斜杠命令加上测试与构建产物整体规模被讨论成“51 万行”。这个数字本身不关键关键是它把一个 CLI 工具做成了完整的 Agent 运行时CLI 入口负责启动与参数解析Agent 循环负责把模型输出翻译成工具调用MCP 协议层负责把外部服务接进来工具层负责真正碰文件系统和终端。如果你只把它当成“命令行版的聊天框”会看不懂它为什么需要这么多代码。它更像一个操作系统进程启动要抢时间权限要三级仲裁工具要统一接口上下文要自动压缩终端渲染要绕过重绘瓶颈。这篇就按架构层拆从 CLI 入口、Agent 循环、MCP 接入到工具调用链路逐层走一遍并给出可复制的目录梳理、调用链图和本地源码阅读配置。适合已经用过 Claude Code、想理解它内部怎么跑起来的开发者也适合正在设计自己 Agent 框架的人。我试过把它的模块按“启动 → 会话 → 工具 → 渲染”四层重新画图发现很多看似炫技的设计其实都在解决同一个问题让模型的不确定性不把整个进程拖垮。下面按这个思路展开。2. 前置准备用 TaoToken 把模型通道先跑通读源码之前建议先把模型调用通道跑通否则你只能静态看代码没法验证 Agent 循环里“模型返回工具调用 → 本地执行 → 结果回填”这条链路。TaoToken 提供统一的 API 入口兼容 Anthropic 风格调用适合用来做本地验证。官网地址https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址https://taotoken.net/api你需要先拿到 API Key再把它写进本地环境变量。注意不要把 Key 硬编码进源码仓库Claude Code 自己的 Keychain 预读逻辑就是围绕“凭据不落盘明文”设计的我们读源码时也应该保持同样的习惯。# 写入 shell 配置按需替换成你的实际 Key export TAOTOKEN_API_KEYsk-你的key export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY$TAOTOKEN_API_KEY如果你打算长期跑编码类 Agent 任务可以看 Coding Plan它更适合高频调用场景如果只是验证模型对话链路用模型对话页面即可。接入文档里有完整的请求示例排障时对照着看。注意环境变量名要和客户端实际读取的一致。Claude Code 源码里凭据读取走的是 Keychain 与配置合并逻辑本地验证时用环境变量覆盖是最省事的方式。3. 可复制配置目录结构梳理与本地阅读环境3.1 目录结构怎么拆拿到源码后不要从 main.tsx 一行行读先按职责分四层再逐层深入。下面是我整理的可复制结构字段名按常见命名习惯给出你对照实际仓库调整src/ ├── entry/ # CLI 入口参数解析、启动检查点、预读任务 │ ├── main.tsx │ └── profile.ts ├── agent/ # Agent 循环消息组装、模型调用、工具调度 │ ├── loop.ts │ └── compact.ts ├── tools/ # 42 个工具模块每个目录含 index/prompt/constants │ ├── BashTool/ │ ├── FileReadTool/ │ └── ... ├── mcp/ # MCP 客户端传输层、OAuth、工具融合 │ ├── client.ts │ └── transport/ ├── permissions/ # 权限系统Hook、Classifier、User 三路决策 │ ├── bashPermissions.ts │ └── resolveOnce.ts ├── ink/ # 终端渲染DECSTBM 滚动、CharPool、diff └── config/ # settings 加载、环境变量合并读的时候按“入口 → 循环 → 工具 → 渲染”顺序每层只抓一个核心问题入口层抓启动时序循环层抓消息与工具调用的边界工具层抓统一接口与权限渲染层抓 diff 与滚动。3.2 settings.json 骨架本地阅读时建议配一份最小 settings把模型通道和权限行为固定下来避免每次交互都弹确认{ model: claude-sonnet-4-5, apiKeyHelper: echo $TAOTOKEN_API_KEY, permissions: { allow: [ Read, Bash(git status), Bash(npm run lint) ], deny: [ Bash(rm -rf *), Bash(curl *) ], ask: [ Bash(git push *) ] }, mcpServers: { local-demo: { command: node, args: [./mcp-demo/server.js] } } }这份骨架对应源码里的几个关键点permissions.allow/deny/ask对应权限系统的前缀规则匹配mcpServers对应 MCP 客户端的 Stdio 传输配置apiKeyHelper对应凭据读取链路。把这份配置跑通你再去读bashPermissions.ts会顺很多。3.3 关键模块调用链把调用链画成文字版方便你对照源码打断点main.tsx → profileCheckpoint(main_tsx_entry) → startMdmRawRead() / startKeychainPrefetch() # 并行预读 → applySafeConfigEnvironmentVariables() # 合并配置 → runAgentLoop() → buildMessages() # 组装上下文 → callModel() # 模型请求 → parseToolCalls() # 解析工具调用 → for each toolCall: → checkPermissions() # 三路竞争 → tool.call() # 执行工具 → appendToolResult() # 结果回填 → maybeAutoCompact() # 上下文压缩 → render() # ink 渲染这条链里最值得反复看的是checkPermissions()和maybeAutoCompact()前者决定 Agent 能不能动手后者决定 Agent 能记多久。4. 验证请求按模块验证你的架构理解4.1 验证模型通道先用最小请求确认 API 通curl -s https://taotoken.net/api/v1/messages \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 128, messages: [{role: user, content: 只回复 ok}] }返回里能看到content数组即通道正常。这一步对应源码里callModel()的底层请求格式对上了后面读循环层就不会卡在协议细节上。4.2 验证工具调用链路写一个最小工具定义模拟源码里ToolInput, Output接口的形状type ToolResultT { data: T; isError?: boolean } type ToolInput, Output { name: string call(args: Input, context: unknown): PromiseToolResultOutput isConcurrencySafe(input: Input): boolean isReadOnly(input: Input): boolean checkPermissions(input: Input): Promise{ behavior: allow | deny | ask } } const echoTool: Tool{ text: string }, string { name: Echo, async call(args) { return { data: args.text } }, isConcurrencySafe: () true, isReadOnly: () true, async checkPermissions() { return { behavior: allow } }, } const result await echoTool.call({ text: hello }, {}) console.log(result.data) // hello跑通这个最小工具你就理解了 42 个工具模块为什么能共用一套调度逻辑接口统一权限和并发语义都在接口上声明调度器不需要知道具体工具在干什么。4.3 验证 MCP 工具融合启动一个本地 MCP server观察工具名如何被重写成mcp__server__tool# 假设本地有个 stdio MCP server node ./mcp-demo/server.js在 settings.json 里注册后Agent 看到的工具列表里会出现mcp__local-demo__xxx。这一步对应源码里buildMcpToolName()的拼接逻辑验证成功后你就明白为什么 MCP 工具和原生工具在模型视角里没有区别。4.4 验证上下文压缩阈值在长会话里观察 compact 触发点。源码里四级阈值大致是 Warning 20k、Error 20k、AutoCompact 13k、Blocking 3k以 buffer token 计。你可以手动构造一段长对话看日志里 compact 是否在接近阈值时触发。这一步验证的是maybeAutoCompact()的断路器逻辑连续失败 3 次就停止重试避免浪费调用。5. 本篇常见错排查报错一x-api-key无效或 401。先确认环境变量是否在当前 shell 生效echo $TAOTOKEN_API_KEY看有没有值。如果用了apiKeyHelper注意 helper 命令的输出不能带换行和多余空格源码里凭据读取对空白字符是敏感的。报错二工具调用一直卡在 ask。检查 settings.json 里permissions.allow的规则是否匹配。前缀规则是“拒绝 询问 允许”的优先级如果 deny 里有一条宽泛规则命中了allow 再具体也不会生效。读bashPermissions.ts时重点看matchingRulesForInput()的排序逻辑。报错三MCP 工具不出现。先确认 server 进程能独立启动再看传输层配置。Stdio 传输要求 command 和 args 正确路径用绝对路径更稳。如果 server 启动慢客户端可能有超时日志里会体现连接阶段失败。报错四compact 后上下文丢失关键信息。这是预期行为compact 是用 AI 重新摘要早期对话不是无损压缩。如果关键信息必须保留把它写进项目级记忆文件对应源码里agent-memory的三个作用域user、project、local。报错五终端渲染错乱。如果你在非标准终端里跑DECSTBM 滚动可能不生效源码里有decstbmSafe判断做降级。遇到错乱先换标准终端复现再去看ink/目录里的滚动补丁逻辑。6. 继续深入把源码当教科书用拆完这几层你会发现 Claude Code 的工程哲学很一致安全默认、性能敬畏、数据驱动、透明抽象。权限三路竞争用ResolveOnce做原子仲裁工具接口用buildTool()填安全默认值MCP 用统一接口抹平外部服务差异渲染用 CharPool 把字符比较降成整数比较。这些设计单看都不复杂难的是它们被一致地贯彻到 1884 个文件里。想继续验证模型行为可以去模型对话页面直接对比不同模型的工具调用表现想把这条链路接进日常编码API Keys 页面能拿到接入凭据接入文档里有完整的请求与排障说明如果你打算长期跑 Agent 类任务Coding Plan 更适合高频场景。源码阅读配置跑通之后建议从permissions/bashPermissions.ts和agent/compact.ts这两个文件开始精读它们分别代表了“安全”和“记忆”两条主线读懂了再回头看其他模块会快很多。