简介Claude Code v2.1.88 完整 TypeScript 源码包面向大模型应用开发、终端代码助手架构方向的开发者与研究人员可帮助读者从源码层理解 AI 编程助手的工作原理。内含从 npm 包 anthropic-ai/claude-code 解包的原始 src 目录37 个子目录、1884 个 TypeScript/TSX 源文件代码总量约 51 万行覆盖 query.ts 主代理循环、main.tsx REPL 引导、QueryEngine 无头查询生命周期引擎、Tool/tools 工具接口与注册系统、commands.ts 中 80 斜杠命令定义、context.ts 用户输入上下文处理及 interactiveHelpers 交互式助手组件等核心实现。随包附带的深度分析文档逐项拆解遥测与隐私的数据收集机制、隐藏功能与模型代号背后的 Feature Flag 体系、卧底模式中 AI 身份隐藏原理、远程控制与紧急开关的 KillSwitch 机制以及 Numbat、KAIROS、语音模式等未来路线图同时可从源码中一窥 40 内置工具文件操作、代码执行、Git 命令、MCP 协议支持与工作流脚本系统的落地方式。包体共 1968 个文件以 ts/tsx 源码为主体1340 个 ts、552 个 tsx另有 js、md、json、sample 等辅助文件压缩包 19.06MB已有 429 人学习下载。无论是想复用 Claude Code 的架构设计还是研究 Agent 工具编排与终端交互这份源码包都能提供第一手参考资料。 最近我花了两天把 Claude Code 的完整 src 目录翻了一遍还对照着一份分析文档做笔记。越看越觉得这工具被大多数人用浅了。很多人只在终端里敲几个斜杠命令、让它改改代码却从来没想过它的会话为什么能跨天恢复、工具权限系统为什么设计成那样、第三方模型又是怎么被“接”进去的。这篇文章是我基于这套源码和分析文档整理出来的实战笔记不聊虚的直接讲清楚 Claude Code 是什么、源码里能挖到哪些东西、怎么改配置、怎么接入 DeepSeek 这类第三方模型以及我自己踩过的坑。适合刚接触 Claude Code 的小白也适合想基于它做二次开发或者团队内部集成的同学。1. 项目定位与源码价值为什么值得扒一遍1.1 Claude Code 到底是干什么的Claude Code 是 Anthropic 推出的命令行 AI 编程助手但它不是简单的聊天机器人。它的核心逻辑是“理解整个项目”能读文件、写文件、执行命令、调用 MCP 工具甚至可以在你授权之后自动跑测试、批量改代码。本质上它是一个跑在终端里的 Agent而不是一个问答窗口。这一点很关键因为它决定了源码的设计方向。如果你只是跟它聊聊天那对上下文的要求不高但如果你要它在一个大型仓库里找出问题并修复就需要一套完整的状态管理、工具调度、权限确认机制。这些机制正是我读源码时最感兴趣的部分。1.2 src 目录里能挖到什么我拿到的这版源码不算特别大但目录分层非常清楚。入口文件很轻大部分逻辑都拆到了独立模块里。按照分析文档里的模块图最值得看的是四块命令系统负责解析/clear、/resume、/compact这类斜杠命令。会话存储负责把历史消息序列化到本地文件支持断点续聊。工具调用链负责把模型输出的工具请求翻译成真实的文件读写、命令执行。权限控制负责在每次工具调用前判断是放行、拒绝还是弹确认。这四块不是互相独立的而是从上到下串成一条完整链路用户输入 - 命令解析 - 拼装提示词 - 请求模型 - 返回工具调用 - 权限校验 - 执行工具 - 写回上下文。看懂这条链路你就能理解 Claude Code 的很多行为比如为什么要/compact、为什么第一次跑命令会问你“是否允许”以及模型到底是怎么“看到”你的 CLAUDE.md 的。2. 安装与首次运行从源码到能跑起来2.1 官方安装方式与版本验证大多数人刚开始没必要折腾源码直接用 npm 安装最省事。官方推荐的方式是npm install -g anthropic-ai/claude-code装完先验证一下版本claude --version然后直接在终端里敲claude就能进入交互界面。如果你的终端里能正常弹出欢迎语说明基础环境没问题。之后所有配置文件的修改、模型切换都能在这个基础上展开。这里提醒一句Claude Code 的更新频率不低如果你发现某个新功能没有先执行claude update不要急着怀疑源码。2.2 用源码直接运行如果你手上已经有完整 src想从源码跑起来其实也不复杂。先进入项目目录安装依赖npm install然后查看package.json里的 scripts 配置一般会有build或dev脚本。如果你想在本地改完代码立即生效最简单的方式是npm link这样会把当前目录下的命令行工具软链到全局之后你改一行源码终端里再次运行claude时用的就是新代码。我建议第一次跑源码就直接用npm link调试效率比反复打包高很多。如果你只是看代码不打算全局替换也可以直接执行入口 JS 文件比如node cli.js。但要特别注意源码里的依赖版本和 Node 版本有对应关系Node 太老或太新都可能跑不起来。分析文档里的环境要求是 Node 18 以上我实测用 Node 20 是最稳的。2.3 配置自定义模型以 DeepSeek 为例很多同学拿到 CLI 之后第一件想做的事就是接第三方模型因为相比之下成本更低。Claude Code 本身是 Anthropic 生态的东西但它兼容 Anthropic 协议的接口所以只要第三方服务支持这个格式理论上都能接。我实际测过 DeepSeek 的兼容接口步骤很简单。先设置环境变量export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的APIKey export ANTHROPIC_MODELdeepseek-chat然后直接运行claude。只要接口路径正确模型名在服务端存在就能正常对话。不过用环境变量有一个麻烦每次开新终端都要重新设置。更推荐的做法是写进配置文件。在~/.claude/settings.json里加一段{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: 你的APIKey, ANTHROPIC_MODEL: deepseek-chat }, model: deepseek-chat }这样之后每次启动claude都会自动读这个配置。但这里有个非常容易踩的坑Claude Code 的部分版本会做模型名单校验。如果你在一个旧版本里直接指定了一个它不认识的名字终端就会报类似deepseek-v4-pro is not a model this version of claude code recognizes这样的错误。这时候不要慌先确认你用的是最新版本然后检查ANTHROPIC_MODEL这个名字是否和第三方服务暴露给用户的一致。如果你确实要用某个特殊模型名可以通过claude config set --global model your-model-name来覆盖默认配置或者升级版本新版对自定义模型的宽容度会高很多。3. 源码核心机制拆解四个必看模块3.1 会话Session管理历史上下文怎么存Claude Code 有个很实用的能力关掉终端之后下次还能恢复之前的对话。这个能力不是凭空来的源码里有一块独立的 session 存储模块。从代码路径看会话数据会以 JSON 格式落到本地文件通常位于~/.claude/projects/下面按项目路径的哈希值分目录存放。每个会话文件里保存了消息列表、工具调用记录、时间戳等元数据。所以你执行claude --continue或者/resume的时候它才能把上一次的工作现场还原出来。理解了这一点你就能解释两个现象为什么换了一个目录--continue可能找不到之前的对话因为会话是和项目路径绑定的。为什么对话太长之后会变慢因为每次请求都要把完整历史重新发送给模型。针对后者源码里提供了/compact命令它会自动压缩早先的上下文把前面的对话总结成一段摘要再继续后续工作。我建议每次对话明显变卡、开始丢失早期信息时就执行一次/compact比手动开新会话更有连续性。3.2 工具调用Tool Calling与权限系统Claude Code 能做的事很大程度取决于它给你暴露了多少工具。源码里可以看到读文件、写文件、执行 Bash 命令、调用 MCP 服务等工具定义。但工具越强风险越大。所以源码在工具调用前有一层权限校验逻辑。它不是默认放行所有操作而是有一套 allowlist 和 denylist 机制。你可以把它理解为“门禁”名单里允许的直接放行名单里禁止的直接拒绝剩下的一律弹窗问你。这套机制在配置文件里对应permissions字段{ permissions: { allow: [ Bash(git status), Read ], deny: [ Write ] } }上面这个配置的意思是允许执行git status和所有读文件操作拒绝所有写文件操作。实际使用中我建议把高频、安全的命令比如git status、npm test加入allow把危险命令比如rm -rf、sudo加入deny这样既减少频繁确认的打扰又能守住底线。这个设计最大的价值是让工具调用变得可审计。你不需要信任模型只需要信任配置。模型再聪明也跨不过权限边界。3.3 Prompt 构建与 CLAUDE.md 的记忆注入Claude Code 每次发起模型请求前都会构建一份“组合提示词”。源码里有一段逻辑会扫描当前项目的根目录寻找CLAUDE.md文件并把它的内容注入到系统提示词里。这个文件非常重要它相当于项目的“长期记忆”。你可以在里面写项目结构说明、代码风格规范、禁止使用的命令、常见任务的操作步骤。模型每次启动时都会读它所以它能有效提升输出的稳定性。举个例子如果你在CLAUDE.md里写清楚“本项目统一使用 pnpm不使用 npm”那模型在帮你安装依赖、执行脚本时就会优先选择 pnpm。如果没有这个约束它可能会按自己的习惯用 npm最后导致锁文件混乱。我用这个文件的方式是这样的第一段是我的要求第二段是项目技术栈和目录结构第三段是常见的开发流程和注意事项。写完这个文件之后Claude Code 的行为会明显“贴题”很多。3.4 Skill 机制源码里的扩展点在哪Skill技能是 Claude Code 比较新的一套扩展机制。它的本质不是插件而是“预置的提示词片段”。你可以在项目下建一个.claude/skills/目录里面放 Markdown 文件每个文件就是一条技能。从源码的加载逻辑看Claude Code 会扫描这个目录读取每个 skill 文件里的 name 和 description然后在模型认为当前任务匹配某个技能时自动把对应内容注入上下文。举个例子我想让它每次代码审查都按同一套标准来就写了一个.claude/skills/code-review.md--- name: code-review description: 对最近改动做一次代码审查 --- 执行以下步骤 1. 先运行 git diff HEAD 查看改动文件 2. 按文件逐项检查是否有逻辑错误、安全隐患、风格问题 3. 输出问题时给出具体行号和修复建议之后我只要说“帮我 review 一下代码”Claude Code 就会按这个流程走。这比每次手动描述要求要稳定得多。如果你要扩展复杂能力比如接入公司内部接口那建议优先考虑 MCP。Skill 适合做“流程模板”MCP 适合做“数据接入”两者不冲突可以配合使用。4. 实操让源码为我所用4.1 用 settings.json 做全局和项目级配置读源码的过程中我最大的收获是把三个配置文件的边界弄清楚了。它们各自的优先级和适用场景完全不同配置路径作用范围典型用途~/.claude/settings.json当前用户全局个人模型接入、全局权限.claude/settings.json当前项目团队统一规则、项目级权限.claude/settings.local.json当前项目本地个人密钥、本地调试参数可被 git 忽略实际使用时我会把团队共同需要的东西放在.claude/settings.json比如代码风格规范、统一的 deny 规则把只有我自己用的 API Key、模型地址放在.claude/settings.local.json避免提交到仓库。一个综合示例的.claude/settings.local.json长这样{ env: { ANTHROPIC_BASE_URL: https://你的接口地址, ANTHROPIC_AUTH_TOKEN: sk-本地key }, permissions: { allow: [Bash(npm run lint)] } }注意.claude/settings.json和.claude/settings.local.json如果同时存在本地文件的配置会覆盖项目文件的同名配置这一点在源码里是有明确合并顺序的。所以如果你发现团队配置不生效优先检查本地文件里是不是有同名覆盖项。4.2 通过 MCP 接入外部工具MCP 的全称是 Model Context Protocol简单理解就是“AI 工具的统一接口协议”。Claude Code 源码里内置了 MCP 客户端可以连接外部服务让模型读取数据库、调用公司内部接口、查文档等。配置 MCP 有两种常见方式。一种是命令行claude mcp add my-server --transport http --url http://localhost:8080另一种是直接在项目根目录写.mcp.json{ mcpServers: { my-helper: { command: node, args: [server.js] } } }启动claude后它会自动加载这个文件里配置的 MCP 服务。如果服务启动失败会在工具调用时报类似“MCP server not found”的错误。我的排查思路是先把服务单独拉起来确认接口能通再让 Claude Code 去连这样能避免两边问题混在一起。需要提醒的是MCP 不是“免维护”的。服务端的数据格式、鉴权方式、超时设置都会影响稳定性。如果你发现 Claude Code 调用 MCP 工具经常失败多半不是协议问题而是你的服务端没处理边界情况。4.3 调试与日志源码里留下的定位手段源码里留了不少调试入口最常用的就是环境变量DEBUG。在终端里启动时加上DEBUG1 claude它会打印出请求、响应、工具调用等详细日志非常适合排查“模型明明输出了工具调用但代码没执行”这种问题。另外日志文件一般会落在~/.claude/logs/目录下。如果你遇到崩溃或者异常退出先去翻最新的日志通常能找到具体报错堆栈。分析文档里也提到GitHub issue 里常见的“Claude Code 没有响应”问题很多都能在日志里找到真正的报错原因而不是界面上的风火轮。我自己的习惯是遇到问题先不开界面直接DEBUG1 claude跑一遍把前几十行日志看明白往往比瞎猜高效得多。5. 常见问题与避坑实录很多问题是我在实际使用和分析源码时反复遇到的。这里整理成一张速查表方便你直接对照现象可能原因解决办法提示xxx is not a model this version of claude code recognizes模型名不在内置名单或者配置未生效检查ANTHROPIC_MODEL确认接口文档里的模型名升级到最新版本用claude config set --global model覆盖执行命令时每次都弹确认permissions.allow没配置把常用安全命令加入allow列表对话稍长就丢失信息上下文长度超限执行/compact压缩历史或/clear重新开始中文路径或中文输出乱码终端编码问题终端设置为 UTF-8尽量不用 Windows 默认编码MCP 工具调用失败服务端未启动或数据格式不对单独启动并测试服务端确认接口返回符合协议格式修改源码后不生效构建流程没重新执行检查是用npm link还是打包产物确认当前运行的入口文件是预期的那份第一行的模型名报错最典型。我在接 DeepSeek 和其他兼容服务时都遇到过原因不外乎两个一是版本太旧模型名单里没有你填的名字二是填写的模型名和第三方接口实际提供的名字不一致。解决办法就是先升级版本再核对名字。实在不行把ANTHROPIC_MODEL这个环境变量彻底去掉让服务端默认给你选一个模型有时候反而更省事。还有一个容易被忽略的问题如果你同时配了全局settings.json和项目settings.json里面有同名配置项项目级会覆盖全局级。源码里合并配置的时候采用后写覆盖先写的方式。所以当某个配置“改了没反应”先顺着这条覆盖链查一遍。6. 写在最后几个我在源码里学到的小技巧代码读完之后我最大的感受是Claude Code 没有把 Agent 设计成黑盒而是把控制权一点一点交还给用户。权限、记忆、技能、协议全部都能在配置层面干预。它真正的上限不在于模型本身而在于你把项目信息和工具链喂给它多少。如果你要开始认真使用它我建议按这个顺序推进先写好CLAUDE.md让模型懂项目再花几分钟整理permissions把安全边界划清楚然后把你反复要做的事情沉淀成 Skill最后才是上 MCP 接外部系统。这套组合拳打下来工具会一次比一次好用。最后再分享一个小技巧如果你改过源码务必用 git 管理你的本地修改每次官方版本更新前先diff一下看看有没有冲突。别问我为什么知道我已经经历过两次“升级一时爽补丁全丢光”的场面了。希望这篇笔记能帮你少走几步弯路。本文还有配套的精品资源点击获取