★ FEATURED ARTICLE 简介Claude Code是Anthropic官方推出的AI编程助手命令行工具其源代码包聚焦于底层实现适合对Agent化CLI架构、TypeScript大型项目组织方式感兴趣的开发者学习研究。包体共1903个文件以TypeScript为主包含1332个ts与552个tsx另有少量js及md文档压缩包大小约9.43MB。目录结构按业务模块清晰拆分commands存放斜杠命令实现components/design-system提供终端UI组件services下包含API、MCP协议与设置同步等核心服务tools则封装了BashTool、FileEditTool、GrepTool等具体工具。通过阅读源码可理解Claude Code如何组织命令解析、任务代理、文件读写与代码搜索等能力也能参考其基于Ink构建交互式终端界面的设计思路对想深入掌握AI编程工具原理或进行二次开发的读者很有价值。目前已有707人学习下载。1. 拿到这份“Claude Code源码”压缩包先别急着解压先说结论我是在一次内部技术交流时拿到的这份标注为 Claude Code 源码的压缩包日期写着 26年4月1日。最初我也以为解压就能得到一份完整的客户端源码拆开才发现里面是一个工程骨架的集合harness 主循环、核心 SDK、第三方依赖快照外加一堆构建脚本。这类源码包对想改模型路由、解决插件报错、做 CLI 二次开发的人来说价值很高对只想拿它当作正式安装包的用户反而容易踩坑。它能帮你搞明白三件事模型请求从哪发出、参数在哪个文件里生效、自动升级失败时到底是谁在拦截。如果你正卡在“装上了不会配、配了不生效、日志看不懂”的状态这份源码值得跟到底。2. 拆包看实现从目录结构还原 Claude Code 的运行骨架拿到源码包之后我习惯先不看 README直接看目录树。因为泄露包与官方发行版的最大区别不是“有没有代码”而是“代码的组织方式”。发行版是编译压缩过的产物几乎所有变量名都被混淆模块边界只能靠行为猜测源码包则保留了模块拆分、注释和测试用例能直接看到 agent 的决策循环和工具注册逻辑。2.1 先看包里的文件清单源码包和发行版差在哪我一般会先做一次顶层扫描看看包里装的是什么。以下命令可以直接在你解压后的目录里跑# 在包根目录执行只显示两层目录结构 find . -maxdepth 2 -type d | sort | head -60 # 统计关键文件类型 find . -type f | sed s/.*\.// | sort | uniq -c | sort -rn | head -15 # 看看有没有 .map 和测试文件 find . -type f \( -name *.map -o -name *.test.* -o -name *.spec.* \) | head -30逻辑说明第一段命令是看目录层级判断这个包是“源码仓完整导出”还是“单包发布前的临时拼装”。第二段命令统计文件类型能快速识别包的主体是 TypeScript、JavaScript还是掺了大量二进制资源。第三段命令检查的是 source map 和测试文件这两类文件在正式发布包里几乎不会出现但在源码包里有很高出现概率。参数说明-maxdepth 2控制在两层以内避免输出爆炸sed s/.*\.//提取扩展名uniq -c | sort -rn按数量倒序排列一眼能看出语言占比。如果.test.ts文件数量很少甚至为零说明这个包可能被人为清理过也可能是从某次构建中间态里捞出来的。在源码包里常见的目录布局和我见到的多数 CLI 项目一致表 1 列出的是我拆包时的预期角色分配。目录/文件预期角色泄露包里常见变化src/核心源码含 agent 循环、工具调用、上下文管理可能被压缩成单文件harness/与终端交互的输入输出层管 stdin/stdout常被误命名为shell/vendor/或third_party/第三方依赖快照可能缺部分许可证文件scripts/构建、打包、版本更新脚本容易被删只剩 build 脚本package.json入口、依赖、bin 映射依赖版本可能被篡改这里要提醒一个事源码包和发行版的依赖处理方式完全不同。发行版通常把依赖直接打进产物你在node_modules里看不到完整依赖树源码包则依赖package.json里的声明安装时还需要拉取外部依赖。这意味着源码包的复现成本比发行版高如果网络环境受限第一步就会卡住。2.2 harness 是核心谁在跑 agent谁在管模型请求很多使用者对 Claude Code 的印象是“一个终端里能聊天的命令”但源码拆开后会看到真正的核心是 harness 层。它负责读取终端输入、维护会话上下文、调用模型 API、接收工具执行结果并决定下一步动作。这个循环在源码里通常体现为一个runAgentLoop或executeTurn之类的方法。我最关心的不是这个循环本身而是它读取配置的位置。几乎所有模型路由参数都集中在同一个配置读取函数里找到它就能改模型、改温度、改流式开关。常见做法是通过环境变量覆盖默认值源码里的读取逻辑类似// 这是一个简化后的配置读取示意实际源码变量名可能不同 function loadConfig(env process.env) { return { model: env.CLAUDE_MODEL || env.ANTHROPIC_MODEL || default-model, baseUrl: env.CLAUDE_BASE_URL || https://default.endpoint.example.com, apiKey: env.CLAUDE_API_KEY || , maxTokens: parsePositiveInt(env.CLAUDE_MAX_TOKENS, 4096), temperature: parseFloat(env.CLAUDE_TEMPERATURE ?? 0.7), stream: env.CLAUDE_STREAM ! false }; }逻辑说明这四行配置决定了整个 CLI 的行为边界。baseUrl决定请求发到哪个服务model决定模型标识maxTokens和temperature影响生成长度和随机性stream控制是否流式输出。源码包的实用价值就在这里你不需要黑盒试参数直接看读取逻辑就能确定环境变量名。参数说明parsePositiveInt和parseFloat这类表达式常见于健壮的配置解析目的是避免空字符串或非法值把进程打崩。实际源码里可能还会对baseUrl做尾部斜杠处理判断是否以/v1结尾这也解释了为什么很多人配置完地址后请求 404——地址拼接规则藏在源码里不拆包根本看不到。2.3 双入口问题CLI 入口和 SDK 入口同时存在另一个在源码包里必须确认的点是 package.json 中的bin字段。很多泄露包会把入口写错导致你安装了却执行不了。{ name: claude-code-local, version: 4.6.1, bin: { claude: ./bin/cli.js }, exports: { .: ./src/index.js, ./harness: ./src/harness/index.js }, engines: { node: 18.12.0 } }逻辑说明bin字段决定命令行调用名exports字段决定 SDK 导入路径engines字段决定 Node 版本下限。我见过一个翻车案例有人把bin指向了./build/index.js但该文件在包内根本不存在导致claude命令永远提示“找不到模块”。参数说明exports里的./harness子路径是调试的好帮手它允许你在自己的 Node 脚本里直接引入内部模块而不必绕整个 CLI。engines里的18.12.0说明这个版本依赖 Node 的完整特性如果你的 Node 版本低于它启动时会报语法错误或模块加载失败这是排查问题的第一道关卡。2.4 版本指纹日期和版本号谁在撒谎最后一个我必查的文件是package.json里的version字段以及/src/version.js这类单独存放版本变量的模块。泄露包经常被二次打包二次打包的人会顺手改日期、改版本号以混淆来源。# 查看版本相关内容 grep -rn version package.json src/version* 2/dev/null | head -20 # 检查 Git 信息如果包内残留 .git ls -la .git 2/dev/null git log --oneline -5 2/dev/null逻辑说明第一段命令把 package.json 和独立版本文件中的版本声明全部捞出来对比是否一致。如果两处版本号对不上说明包被人动过手脚。第二段命令是查看残留的 Git 历史很多源码包是从服务器直接打包的.git目录会被打进去这是判断来源可信度的重要指标。参数说明2/dev/null丢弃无权限读取的错误head -20限制输出量。如果.git目录存在且能查到提交记录优先看最后一条提交的时间和 message正常工程最后一次提交不会写在“4 月 1 日”这种日期上。某次我拆过一个包版本号显示 4.6.x但 Git 提交时间却在半年前基本可以断定是旧版本改了号重新发的。这一章拆完你应该能回答三个问题包里有什么、主循环在哪个模块、配置在哪读。接下来就可以真刀真枪地把源码跑起来了。3. 从源码构建把静态文件变成可运行的命令行工具拆包看清结构只是第一步真正让源码“活”起来的是构建。这一步的坑比想象中多尤其是 Node 版本和依赖安装方式稍有偏差就会得到一堆莫名其妙的报错。我会按环境准备、依赖安装、构建启动、版本校验四步走。3.1 环境准备先确认 Node 版本和包管理器源码包里的engines字段只写了 Node 版本下限但没有写上限。实际测试中我在新版 Node 环境下跑构建遇到过两次失败一次是某个依赖用了旧的 C 插件编译接口一次是内置fetch行为差异导致测试断言失败。所以我的习惯是先把版本固化下来再继续操作。# 检查当前 Node 版本 node --version # 检查 npm 版本 npm --version # 如果你用的是 corepack 管理包管理器 corepack --version 2/dev/null || echo corepack not active逻辑说明Node 版本会影响依赖解析和原生模块编译。node --version告诉你能不能达到engines的下限npm --version决定锁文件是否能被正确解析corepack的作用是固定包管理器版本避免不同机器上锁文件语义不一致。参数说明这里我没有直接给出版本号因为不同包的依赖策略差异很大。如果你拆的包依赖较老常见做法是用 Node 20 系列或 22 系列的 LTS 版本而不是最新版如果依赖较新则需要至少 Node 22。判断方法很简单先看engines再试跑构建报错就换版本。3.2 安装依赖npm ci 优先npm install 其次源码包通常自带锁文件可能是package-lock.json、yarn.lock或pnpm-lock.yaml。锁文件的价值在于锁死依赖版本避免传递依赖偏移导致行为不一致。# 首选方式使用锁文件安装全部依赖 npm ci # 如果锁文件缺失退回 npm install # npm install逻辑说明npm ci会严格按照锁文件安装速度快且不会改动锁文件内容。npm install会重新解析依赖哪怕有锁文件也可能因版本范围产生变化。源码包的这个区别尤其明显如果包在制作过程中修改过package.json但锁文件没有同步更新npm ci会直接报错反而能提醒你“这个包被改过”。参数说明npm ci要求锁文件与package.json完全匹配不匹配时抛出EUSAGE错误。这其实是好事它帮你提前发现包是否被篡改。若遇到这个报错我一般会手动对比package.json中的依赖列表和锁文件中的packages字段找出被加进去的额外依赖再决定要不要继续。3.3 构建与启动区分一次构建和增量构建源码包内常见的构建命令是npm run build但不同包的含义完全不同。有的包 build 只是语法转译几秒结束有的包会做打包、压缩、混淆耗时几分钟。启动时也不是直接node某个入口而是要看bin指向。# 执行构建 npm run build # 查看构建产物 ls -la dist/ build/ out/ 2/dev/null # 直接用入口启动调试模式 node ./bin/cli.js --verbose --model your-model-name 写一句测试话逻辑说明npm run build执行的是scripts.build中定义的完整命令链常见的是tsc加打包器。最后一行命令绕过 npm 直接以 Node 启动--verbose打开详细日志--model指定模型名后面跟的字符串是本次 request 的提示词。参数说明--verbose在大多数 CLI 中会输出完整的请求和响应体包括 base URL、请求头、状态码和 raw body这是排查“接入第三方模型后无响应”的最直接手段。--model有时可用环境变量替代优先级通常是命令行参数高于环境变量高于默认配置。启动后如果看到正常的欢迎信息说明构建链路是通的。如果卡住或直接退出优先看下面两种现象。3.4 构建产物与源码不一致改代码不生效怎么办源码跑起来之后你会发现改了src/里的代码重启命令却没变化。这不是玄学而是入口文件指向的是dist/或build/产物并没有走源码。处理方法有两种。# 方法一使用源码注册的调试入口 node src/index.js --verbose # 方法二重新构建后再跑 npm run build node bin/cli.js --verbose逻辑说明大多数工程会区分“开发模式”和“生产模式”。开发模式用 ts-node、tsx 之类直接执行 TypeScript生产模式先编译到dist/再执行。泄露包往往缺省前者所以你只能在“改源码”和“跑产物”之间二选一除非你手动注入调试脚本。参数说明如果你看到src/index.js运行时提示找不到某些模块是因为那些依赖只在构建后被抹平源码里还没有被引用的路径。这时不要强行跑直接改编译产物调试缩短反馈循环。版本校验这一关我一般会跑npm run test的轻量版本只跑带smoke标签的用例避免重测试拖时间。如果源码包里没有测试用例就直接跳过不在这上面浪费时间。4. 配置与联动VSCode 插件、PyCharm 插件和第三方模型接入源码能跑通之后下一步就是把它接到自己的日常环境里。这一章解决三个高频诉求把模型请求切到第三方兼容模型、在 IDE 里用插件唤起 CLI、把终端模式切到 WSL 或远程环境。每一条我都给出了典型的配置路径和参数解读。4.1 模型路由从默认端点切到兼容网关很多人拿到源码包后最想做的事是让它跑在第三方兼容模型上。源码里的模型路由逻辑通常支持两类端点一类是默认的官方原生 API 格式另一类是 OpenAI 兼容格式。常见做法是设置一个网关服务把官方格式转换成 OpenAI 兼容格式再让 Claude Code 客户端指向这个网关。# 环境变量配置示例当前终端临时生效 export CLAUDE_API_KEYsk-your-key-here export CLAUDE_BASE_URLhttp://127.0.0.1:8080/v1 export CLAUDE_MODELyour-third-party-model export CLAUDE_MAX_TOKENS8192 export CLAUDE_TEMPERATURE0.7 # 然后启动 claude逻辑说明这套环境变量的优先级高于配置文件且不会污染用户目录适合快速验证。CLAUDE_BASE_URL指向本地网关的/v1路径网关会把请求转换成第三方模型的格式。CLAUDE_MODEL的值需要与网关侧配置的模型名完全一致大小写敏感。参数说明CLAUDE_MAX_TOKENS如果设得太高第三方兼容层的上下文窗口可能会截断请求设得太低长对话体验会明显下降。我一般先设 4096 左右跑通链路再根据模型实际窗口加量。CLAUDE_TEMPERATURE在代码生成类任务里建议保持 0.2 至 0.4不要直接抄默认的 0.7。接入后验证是否生效最快的方法是开启详细日志观察请求头和请求体。验证方式我会在第 6 章展开这里先保留一个结论如果日志里 base URL 还是默认端点说明环境变量没有生效大概率是变量名拼错了或者旧 config 文件优先级更高。4.2 VSCode 配置插件方式唤起 CLI最常见的 IDE 联动方式是装一个支持自定义命令的终端插件然后在插件配置里把命令指向本地源码入口。下面是一份基于settings.json的配置示例。{ terminal.integrated.env.linux: { CLAUDE_API_KEY: sk-your-key-here, CLAUDE_BASE_URL: http://127.0.0.1:8080/v1, CLAUDE_MODEL: your-third-party-model, CLAUDE_MAX_TOKENS: 8192 }, terminal.integrated.profiles.linux: { Claude Dev: { path: /usr/bin/bash, args: [-c, claude --verbose] } } }逻辑说明terminal.integrated.env.linux对当前项目终端注入环境变量避免全局污染。terminal.integrated.profiles.linux新增名为“Claude Dev”的终端配置打开即执行claude --verbose省去每次手敲命令。参数说明args里的-c表示通过 bash 执行一条命令如果 Claude Code 安装路径不在 PATH 中要改成绝对路径例如/home/user/build/bin/cli.js --verbose。VSCode 插件市场里那些带“smart”或“super”字样的第三方插件本质都是起一个终端进程配置逻辑与这里完全一致不需要被花哨界面迷惑。4.3 PyCharm 插件与远程环境的注意点PyCharm 这类 IDE 里联动的思路类似但它自带运行配置概念比 VSCode 更容易出现环境变量不传递的问题。我见过一个翻车案例在运行配置里设置了环境变量插件终端里却读不到原因是 PyCharm 的终端会话不会自动继承运行配置的环境变量必须写到系统环境变量或 IDE 的全局环境配置里。# 在 WSL 或远程调试时先确认本机入口位置 which claude readlink -f $(which claude) # 确认 Node 路径 which node逻辑说明which claude只是展示 PATH 中找到的第一个入口readlink -f会把符号链接解析到真实路径。在 WSL 里Windows 侧的 npm 全局目录和 Linux 侧的 npm 全局目录互不相通经常出现“Windows 能跑、WSL 里找不到命令”的局面这两条命令能快速暴露问题。参数说明WSL 环境下推荐直接在 Linux 子系统中安装一套完整 Node 环境不要复用 Windows 侧 Node。因为源码包启动时会创建伪终端对进程组和信号处理有要求Windows 版 Node 跑在 WSL 里容易报 IO 错误。4.4 自动升级与权限npm prefix 为什么老报错源码包二次分发后最刺眼的一个报错是auto-update failed: no write permission to npm prefix。这行字看起来是更新失败背后的根源是包的自动更新机制试图升级自身但安装目录的写权限受限。源码里通常会有一个updateCheck模块它执行的命令类似npm install -g claude-code-locallatest这条命令要求对 npm 全局目录有写权限。在用户态安装的场景下全局目录往往属于 root于是更新失败。常见的修法是调整 npm 前缀到用户目录。# 查看当前位置 npm config get prefix # 将全局目录改到用户目录 npm config set prefix $HOME/.local/npm # 重新设置 PATH export PATH$HOME/.local/npm/bin:$PATH逻辑说明npm config get prefix显示全局安装目录默认可能是/usr/local普通用户没权限写入。把前缀改到$HOME/.local/npm后全局安装不再需要 root 权限自动更新也能正常执行。这是治本的做法比每次报错手动授权更省心。参数说明set prefix只影响后续的npm install -g已经安装的存量包需要重装一次才能迁移到新目录。改 PATH 时一定要把用户目录放在系统目录之前否则还是会命中旧的全局入口。5. 踩坑排查从 auto-update failed 到 start in cowork五个必踩的坑源码包与官方安装包的差别在排错时最明显。官方安装包自带校验和回滚机制泄露包则常常把问题暴露在最底层。这一章整理成“现象 → 原因 → 解决”三段式都是我在实际拆包复现中遇到的真实问题。5.1 现象 1auto-update failed: no write permission to npm prefix现象每次启动都打印一行红色错误提示自动更新失败无写入权限但命令本身还能继续工作。原因自动更新模块尝试执行npm install -g把自己升级到最新版但 npm 全局目录当前是系统级路径当前用户不可写。源码包里如果环境变量DISABLE_AUTO_UPDATE没有被设置更新检查就会默认开启。解决两步走。第一设置环境变量DISABLE_AUTO_UPDATE1临时关闭自更新第二按 4.4 节把 npm 全局目录改到用户目录。如果不想改全局配置也可以在源码包的配置读取处直接注释掉更新检查代码重新构建后替换启动入口。注意关闭自更新后后续不会收到任何修复补丁安全性由你自己负责。5.2 现象 2start in cowork on 3 p是个谜现象在终端输入一条看起来像指令的文本后命令没有任何可预期的响应或者报出start in cowork on 3 p这样的提示无法继续。原因这句话实际上是源码包中某个状态机的内部提示被误暴露到终端的结果。cowork在工程语境里往往指协作模式on 3 p可能是一个格式化占位符泄露包在二次打包时没有正确替换模板变量导致内部状态被当作用户提示输出。我最初也以为是端侧指令查了源码才发现它是运行时状态展示。解决不需要特别处理。检查当前输入是否触发了特定模式切换最简单的方法是退出当前会话重新进入并把输入文本包在引号里传入避免被解析成 toggle 指令。如果频繁出现直接查看源码中该提示出现的分支条件定位是哪一轮状态异常。5.3 现象 3Ubuntu/WSL 下启动秒退没有任何报错现象在 WSL 或纯净 Ubuntu 环境里执行启动命令后进程直接退出终端没有任何错误输出。原因常见有三类。第一缺少终端交互依赖库CLI 启动时创建伪终端失败。第二Node 版本太低部分 ES2024 语法无法解析报错被静默吞掉。第三locale 未设置某些文本编码模块在locale异常时直接退出。解决先跑一次二进制入口不要跑 npm 包装层node ./bin/cli.js --verbose 21 | head -5021把 stderr 合并到 stdouthead -50防止输出过长。如果看到Cannot find module检查依赖是否装全如果没有输出直接退出重点检查伪终端依赖常见做法是安装libstdc6和build-essential基础包后重试。5.4 现象 4接入第三方模型后输出被截断现象模型能响应短问题但长上下文的回答明显变短甚至首字输出后立即结束代码块中间断裂。原因三个参数在打架。一是CLAUDE_MAX_TOKENS设置值超过了第三方模型的最大输出限制网关侧直接截断二是stream模式下兼容层对流式 chunk 处理有误提前终止生成三是接口返回的usage结构不兼容源码里的终止条件拿到了空值。解决观察详细日志里的stop_reason字段。如果值是length说明确实触发了 token 截断把CLAUDE_MAX_TOKENS降到网关允许的范围内例如从 8192 降到 4096。如果值是stop但文本仍然断裂问题在流式合流逻辑这里只能调整网关的参数映射将断流时的结束标记统一为[DONE]格式。5.5 现象 5源码包 md5 对不上二次打包痕迹明显现象从多渠道下载的同一个“泄露包”用md5sum计算出来的哈希值完全不一致部分文件在包内出现两次路径大小写不同。原因这类包往往是多手转发的产物转发的人会重新压缩、删除注释、替换版本号导致哈希变化。这不是你操作错误而是包本身已经不具备唯一指纹。更危险的是某些包会把可执行文件藏在vendor/资源目录中文件名伪装成字体或数据文件。解决下载之后先看包内是否夹杂意外扩展名find . -type f -exec file {} \; | grep -v -E script|text|json|wasm|node | head -20file命令会读取文件头判断真实类型。如果发现某个.png文件被识别为 ELF 可执行文件立即停止使用。这一步是必要的不是玄学。五个坑走完你已经具备了自己排障的基本能力。最后一章给一个具体技巧如何用源码里的日志系统验证第三方模型接入是否真正成功。6. 用源码日志验证模型接入一次完整的请求追踪我不信任“看起来能聊”就算接成功因为很多第三方兼容模型返回的格式不标准聊两句就断。验证是否真正打通要打开详细日志从请求 URL、响应头和 token 统计三个维度核对。先在源码里找到日志级别开关。常见做法是设置一个--verbose标志把 logger 级别提到debug然后在终端里启动并执行一段固定输入。node ./bin/cli.js --verbose --model your-third-party-model 请只回复两个字正常观察日志时重点看三处第一request url指向的地址是否与你设置的CLAUDE_BASE_URL一致第二响应体里的model字段是否与请求时传入的模型名一致第三usage字段里有没有input_tokens和output_tokens如果这两个值是 0 或缺失说明兼容层并没有按预期协议返回元数据后续计费和截断都会出问题。如果源码里日志模块是封装过的可能看不到原始请求。这时我一般直接在 HTTP 客户端封装处加一行临时输出把 payload 打印出来改完重新构建产物再跑。示例是在请求发送前插入// 临时调试代码发送前打印请求体 debugRequest console.log(JSON.stringify(payload, null, 2));这段代码的关键是debugRequest开关避免每次请求都刷屏。用完之后立即删除否则下次构建会把无关输出带到生产环境。这是我从一次事故里学会的有一次我在源码里留了一处调试输出结果把完整会话上下文打印到了日志文件里从那以后我每次改完还是会强制走一遍“改源码 → 构建 → 查看产物 diff → 跑单轮验证”的闭环确认没有残留再继续下一步。希望这一整套拆包、构建、配置、排错的路径能帮到你。如果你手里也有一份来源存疑的 Claude Code 源码包照着第 2 章的目录扫描和第 5.5 节的类型嗅探先做一轮体检再决定要不要投入时间复现。很多时候问题不在源码本身而在我们是否愿意花十分钟先看看包里到底装了什么。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
