简介Claude Code v2.1.88 完整 TypeScript 源码包解包自 npm 包 anthropic-ai/claude-code并配有深度分析文档面向大模型应用开发者和终端代码助手架构研究者。整个压缩包共 1968 个文件、约 19.06MB其中 ts/tsx 源文件 1892 个、总代码量约 51 万行另有 md 文档、mjs/json 配置和 Git 元数据目录结构完整。已有 444 人浏览学习。源码中包含主代理循环、查询引擎、工具系统、命令处理与 React UI 模块可细读 query.ts、QueryEngine.ts、Tool.ts 以及 80 多条斜杠命令实现理解意图解析、上下文管理、工具调用等关键链路。配套分析文档深入拆解遥测与隐私、隐藏功能、卧底模式、KillSwitch 远程控制与未来路线图为自研 AI 编码助手提供一手参考。1. 拿到的“Claude Code源码”不是模型代码而是一个终端Agent的外壳工程“Claude Code源码”听起来像是能直接读懂的AI模型代码实际上它是一套跑在终端里的AI编程助手外壳src目录装的是TypeScript工程负责命令行解析、会话管理、工具调用和权限控制模型本身在远端不在这份源码里。随包附的分析文档就是帮你把这条链路提前画出来的一张地图。它能解决的问题很直接你想知道“让模型改代码”这个动作在工程上是怎么落地的、想仿写一个终端Agent、想找出官方工具的扩展点或者想把源码剖析能力沉淀成一份能送审的技术报告。适合三类人准备做Agent工程的开发者、要评估二次开发成本的架构师、以及想通过读一套高质量工程来提升源码阅读能力的团队。读这份源码最反直觉的一点是真正值得花时间的不是“怎么请求模型”而是“怎么在请求之后安全地让代码在用户机器上跑起来”。这个判断决定了你读源码的顺序和投入产出比后面所有章节都围绕这条主线展开。2. 读源码前先定地图从src顶层目录看懂一个终端AI工具的分层架构拿到一份不熟悉的TypeScript源码包最忌讳按文件名字典序从头读到尾。我一般会先花20分钟把src的目录结构建成一张分层图后面所有阅读都往这张图上挂。Claude Code这类终端AI助手无论具体实现差多少源码布局都逃不出三层骨架命令行入口、会话内核、工具注册表。把这三层找到了项目的地图就立住了之后读任何文件都知道它挂在哪一层。2.1 先找入口package.json的bin字段和src/main入口决定你从哪读起TypeScript CLI工程的入口往往不在src/index.ts而在package.json的bin字段。拿到源码的第一件事是在项目根目录跑一个查询命令把工程元数据捞出来cd claude-code-src # 进入解压后的源码根目录 node -e const prequire(./package.json);console.log(bin:,JSON.stringify(p.bin,null,2));console.log(main:,p.main);console.log(scripts:,JSON.stringify(p.scripts,null,2))bin字段告诉你用户在终端敲下claude这个命令时实际执行的是哪个JS文件main字段是模块化导入入口如果别人把这个工具当库调用走的是mainscripts里的build则告诉你src下的TypeScript是如何被编译成可执行JS的。我通常会先看scripts里的build命令确认编译目标CommonJS还是ESM再看bin指向的文件头几十行入口函数一般在这里做三件事解析参数、初始化日志、拉起会话内核。找到入口之后在src目录里沿着“入口→内核→工具”方向画箭头地图的骨干就出来了。2.2 终端Agent的三层骨架CLI解析、会话内核、工具注册表为什么是这三层因为职责边界必须分开CLI只负责把终端字符串翻译成结构化的用户意图会话内核负责维护多轮对话的完整状态工具注册表负责把模型请求映射到真实系统操作。三层混在一个文件里多轮对话和权限控制会变成一场灾难这几乎是所有同类工具的一致选型。读源码时对号入座的预期如下分层典型职责你在src里找什么CLI层参数解析、帮助、命令补全parse、commander、args相关文件会话内核上下文拼装、消息历史、模型往返session、conversation、context工具注册表工具声明、入参Schema、执行函数tools、tool、actions、permission这个表格不是让你照着同名目录硬找而是建立映射预期。如果某一层找不到对应目录通常说明它被合并进相邻层或抽成了独立npm包这时去分析文档的模块索引里找比自己在几千个文件里盲搜效率高。选型层面也值得记一句话工具注册表的设计决定了整套源码的扩展性。每个工具都实现了“名称入参校验执行函数结果格式化”这四个接口新增一个工具就是往注册表登记一件新武器没有这个抽象工具调用逻辑会散落在各个业务分支里二次开发的成本成倍上升。2.3 用一个静态统计脚本给源码体积建模光看目录名还不够我习惯先用行数给src做体积建模让复杂度重心自己浮现出来find src -type f -name *.ts | xargs wc -l | sort -rn | head -30find输出src下所有TypeScript文件wc -l统计行数sort -rn按行数从大到小排序head -30取前30个。行数最多的文件通常是核心业务逻辑所在地比如会话状态机、工具分发器同时也是阅读难度最高的黑匣子。想统计某个子目录的总行数把find路径换成对应目录即可例如find src/tools -type f -name *.ts。行数建模有个陷阱行数大不等于核心有些文件是常量表或测试夹具体积大但不值得细读。所以统计完行数之后要再跑一次依赖方向统计看谁被谁引用grep -rh from src --include*.ts \ | sed s/.*from //;s/.*// \ | sort | uniq -c | sort -rn | head -30grep -r递归搜索src下所有import语句-h只输出匹配内容不带文件名sed从每条import里提取被引用的模块路径sort和uniq -c统计每个模块被引用的次数sort -rn按引用次数排行。这份输出告诉你哪些文件是底层基础模块被依赖最多哪些文件是业务逻辑集中地行数多但被依赖少。把这两份榜单叠在一起就是你的阅读顺序表先读被依赖最多的基础类型再读行数最多的处理器最后回到工具注册表看装配方式。地图到这里已经能指导后续链路追踪了。3. 顺着一条命令追到工具调用把“让模型改代码”的全链路读成时序有了地图之后下一步是动态追一条真实命令的链路。静态看代码能看出结构但看不出顺序和状态流转。我常用做法是启动工具后随口问一句“当前目录有哪些文件”然后全程开调试日志让代码自己把时序讲出来。这一章追到的链路会贯穿后续所有分析。3.1 一条命令的旅程从终端参数到回调Shell先跑通工具本身确认拿到手的源码和实际行为一致。许多TypeScript CLI使用带命名空间的debug日志库开启方式通常是环境变量npm run build # 先按package.json的scripts完成构建得到可执行产物 DEBUG* node bin/cli.js 请列出当前目录的文件第一次跑建议不要加任何筛选条件直接让所有调试信息输出到文件信息量大没关系目的是拿到完整时序。执行完以后在日志里找几个标志性事件参数解析完成、模型请求发出、第一次工具调用、最后一次工具返回。这四个事件之间的日志就是完整链路。DEBUG命名空间值得单独说DEBUG是全部日志实际阅读时可以按模块过滤比如DEBUGsession,tools*只保留会话和工具模块日志量压缩比例通常在几十比一阅读效率高很多。日志里通常还有模块名和时间戳没有时间戳的日志要怀疑是不是走了普通console.log这类日志对时序分析帮助有限。3.2 工具调用的生命周期请求-审批-执行-回填模型侧的调用链路其实只有两段发请求、收结果。真正把终端Agent做成可用产品的是中间夹着的一个关键循环我把它拆成五步阶段发生了什么源码里对应的关注点1 请求模型返回结构化的工具调用意图而非直接执行响应解析、工具调用JSON校验2 审批会话内核检查这条调用是否被策略允许permission配置、自动放行名单、确认逻辑3 执行允许后调用注册表里的执行函数可能启动子进程子进程spawn、超时控制、工作目录4 回填执行结果被格式化为文本塞回消息历史结果截断策略、错误格式化5 续跑内核带着新上下文再次请求模型直到任务收敛循环终止条件、最大轮数这个五步循环是整套源码的题眼。初次接触容易误以为核心是大模型API调用可模型是远端黑匣子真正决定产品好坏的就是审批和执行这一段。权限策略放得太宽任何提示词注入都能让终端执行危险命令放得太窄每个操作都弹窗确认工具就没法用。源码里最值得反复读的就是审批阶段的判断顺序。顺带回答一个反复出现的问题有人问Claude Code的harness能否不登录就切换其他模型。这个问题的准确答案不在论坛讨论里而在源码里。你去看模型适配层是不是独立接口、请求是否携带厂商专属鉴权字段、harness初始化时校验了哪些配置项读完这三处你比争论十页的人都清楚。源码剖析的意义就在这里把争论变成查证。3.3 最小复刻用bash串起“请求→执行→回填”的往返为了验证上面读出的循环理解是对的我用一个不依赖任何框架的bash脚本把它复刻了一遍。这不替代源码但能把“五步循环”压缩成可读的几十行代码#!/usr/bin/env bash # 最小Agent循环请求模型、解析工具调用、执行、回填上下文 CONTEXT用户问题统计当前目录文件数 ROUND0 MAX_ROUND3 while [ $ROUND -lt $MAX_ROUND ]; do # 1) 把累积上下文发给模型要求只输出JSON工具调用 RESP$(curl -s $MODEL_API \ -H Content-Type: application/json \ -d $(jq -n --arg c $CONTEXT {messages:[{role:user,content:$c}]})) echo [round $ROUND] 模型响应: $RESP # 2) 从响应里解析工具名和参数 TOOL$(echo $RESP | jq -r .tool // empty) if [ -z $TOOL ]; then echo 模型认为任务已结束循环退出 break fi ARGS$(echo $RESP | jq -r .args // empty) # 3) 在白名单内才真正执行这就是权限审批的朴素实现 if [ $TOOL shell ]; then OUT$(eval $ARGS 21 | head -50) else OUT未知工具: $TOOL fi # 4) 结果回填进上下文下一次请求带着它走 CONTEXT$CONTEXT [工具$TOOL 返回]: $OUT ROUND$((ROUND1)) done这段脚本注释已经把五步循环落到了代码上。参数说明MODEL_API是环境变量填你实际能访问的模型服务地址MAX_ROUND3是循环终止上限防止模型陷入死循环源码里的最大轮数概念与它一致head -50对工具输出做截断对应真实实现里的结果长度限制eval执行很危险脚本里特意用白名单这与真实源码里权限审批的动机完全一致——不是阻止执行而是让每个执行都有决策点。跑通这段最小复刻之后回到源码里再看真实实现关注点会从“它怎么做的”变成“它在哪个环节比我这段脚本多做了什么”例如是否把终端输出按token截断、子进程是否带伪终端、结果回填是否区分标准输出和错误输出。带着这个差值去读代码效率远高于逐行平推。4. 读这套源码的五个常见误判错误入口、过时文档与黑匣子调试源码阅读的大量时间浪费在错误方向上不是读不懂而是读错了地方。下面五条踩坑记录是看同类全套源码包时反复遇到的类型按“现象→原因→解决”写清供你对照排查。4.1 现象把随包的分析文档当成官方架构图照着过时结论走分析文档是第三方根据某个时间点的代码写的如果源码包和文档不是同一次构建文档里的目录名、调用关系、参数解释都会对不上。有人照着文档找某个模块发现源码里根本没有第一反应是自己找错了而不是文档过期了。原因文档有版本锚定源码有更新两者不同步。解决动笔之前先做一致性检查打开文档首页或附录找它标注的版本信息或commit信息然后到源码目录执行git log -1 --format%H %cd查看HEAD提交如果源码没有git信息对比文档提到的文件名是否真实存在于src。不一致时一律以源码为准把文档当疑点索引而不是结论。4.2 现象在未构建的src上直接运行node报TS语法错后开始乱改源码在src下的入口文件上直接执行nodenode会抱怨遇到TypeScript语法于是有人为了让代码跑起来开始删类型标注、把import改成require一路把源码改得面目全非。原因TypeScript必须编译之后才能运行源码目录本来就不是直接执行的目标。解决回到package.json的scripts字段看build命令用什么编译器、产物输出到哪个目录常见是dist构建完成后再运行bin指向的JS文件。如果只是想快速试验可以用tsx这类TS解释器临时运行但别把临时运行方式固定下来。这是一个基本顺序问题先构建再运行跳过它后面全是坑。4.3 现象npm全局安装时遇到 no write permission to npm prefix 报错有开发者在全局安装完成后一启动就遇到auto-update failed: no write permission to npm prefix随后觉得工具坏了或者源码有问题转头去改源码里的自动更新逻辑。原因npm全局安装目录属于root当前普通用户没有写权限自动更新想在安装目录写文件失败。这与源码逻辑无关是环境权限问题。解决优先把Node安装在用户目录下用版本管理器装到home路径这样全局前缀天然可写已经处于错误状态的执行npm config get prefix查看当前全局路径再把前缀改到用户目录常见做法是npm config set prefix $HOME/.npm-global。改完重新安装自动更新就恢复正常。这类环境报错的排查顺序永远是先查权限和路径再怀疑源码。4.4 现象全程只搜“API”和“Key”把权限控制和Prompt拼装当成边角料调试时满屏搜索模型API调用找到请求函数就觉得源码读完了结果回答不了最核心的问题模型凭什么被允许执行shell命令。原因模型API在源码里通常只是一个网络请求封装业务复杂度集中在请求前后的两处——进入循环前的系统提示词拼装和执行前的权限审批。这两处决定产品行为反而不起眼。解决主动去src里找两段代码一是消息列表的构造位置看系统提示词如何注入规则二是权限判断的公共函数看审批顺序是先查白名单还是先问用户。如果找不到权限模块就看工具执行前有没有统一的闸门函数。这套源码的安全边界就在这两段代码里抓不住它们读完整套代码也说不清这个工具为什么安全或危险。4.5 现象调试时只加console.log把黑匣子越描越黑为了追踪一次工具调用失败在十几个文件里各加一行console.log跑完发现输出没有模块名、没有时间戳只有一堆无头无尾的字符串根本拼不出时序。原因console.log不携带上下文元数据在多模块并发场景下与其他日志混在一起无法过滤。解决优先使用源码里已有的日志设施。观察现有日志是否带模块名前缀和级别字段如果带直接在启动命令里用环境变量过滤对应模块如果源码没有日志设施临时加日志时也要带统一前缀比如console.error([MYTRACE], Date.now(), __filename)一屏输出就能按时间戳恢复先后顺序。调试信息要有身份信息才谈得上排错否则只是给黑匣子再加一层黑匣子。5. 把分析文档写成能送审的技术报告结论先行、证据链与参数表如果只有源码没有文档这份资源的价值少一半如果文档只是代码截图堆砌价值也少一半。一份能送审、能复用的分析文档和随手笔记之间的差别在三个方面结构上结论先行内容上每条结论都有代码坐标证据表格里记录的是可复用的参数而不是流水账。5.1 分析文档的三件套结论先行、模块索引、调用链证据技术评审场景下读者先看结论再看证据最后才会追细节。分析文档的骨架我固定成三件套结论先行、模块索引、调用链证据。结论先行是开头用两句话说明这套源码的核心机制是什么模块索引是一个表格列出每个目录的角色和关键文件调用链证据是每条关键结论后面附文件路径和行号。件作用常见败笔结论先行告诉读者这套源码值不值得看、核心机制是什么开头写“本报告分析了xxx”读三页还不知道结论模块索引一个表格列出每个目录的角色和关键文件只给目录树不给角色判断调用链证据每条关键结论后附文件路径和行号只画架构图不给证据坐标一个可参考的文档结构是一开始是核心机制的一句话概括然后放模块索引表再按照入口→会话→工具→权限的顺序展开最后附录放生成证据的脚本和原始输出。这套结构写过多份技术报告送审时被追问最多的是调用链证据那边做得丰富文档就站得住。5.2 用脚本生成调用链证据而不是手工画图手工画的架构图容易带入个人理解偏差而且画错很难发现。我一般用脚本把import关系提取出来用最原始的文本证据支撑结论# 提取src下所有文件各自import了谁输出“文件 - 依赖”列表 grep -rn from src --include*.ts \ | sed s/:.*from / - /;s/$// \ | sort deps.txt # 看谁被依赖最多取出边的终点统计次数 awk -F - {print $2} deps.txt | sort | uniq -c | sort -rn | head -20第一段命令把每个文件变成一行“源文件 - 目标模块”的边sort之后存成deps.txt它就是你调用链的原始证据集。第二段命令把边的终点提取出来统计次数输出被依赖最多的模块列表。文档里写“会话内核依赖工具注册表”这类结论时直接引用这段输出里的对应行再补一句“证据见deps.txt第xx行”比画一张精美架构图更经得起追问。参数说明grep -rn的-n给出行号是证据坐标的关键sed把行号替换成箭头让输出可读如果想只保留src目录内部依赖排除第三方包在管道里加grep -v node_modules即可。5.3 参数表和风险清单才是文档的复用价值分析文档最容易被人忽略、但复用价值最高的部分是参数表和风险清单。参数表把每个关键模块的可调项记录下来团队二次开发时直接查表就能决定怎么改风险清单把权限放行、外部命令依赖、路径写死这些点提前暴露避免使用者踩坑。模块关键参数/配置项默认行为与影响证据位置会话内核最大轮数、上下文窗口截断策略决定长任务能否收敛对应源码文件与行号工具注册表超时时间、输出截断阈值决定长时间命令是否卡死对应源码文件与行号权限审批自动放行名单、询问策略决定安全边界宽窄对应源码文件与行号CLI工作目录、日志级别决定调试信息的可获取性对应源码文件与行号这个表格里的证据位置一栏必须写实际的行号或函数名没有坐标的参数表无法验证。风险清单单独列一节类型包括哪些工具默认放行、哪些外部命令是硬依赖、哪些系统路径被写死、哪些错误被静默吞掉。吞错是最隐蔽的风险如果某个catch分支不打印错误继续走流程线上表现就是命令没执行但也没报错这类位置必须在风险清单里单独标注提醒后续维护者优先补日志。有这份清单文档才真正具备“拿来就能用”的价值。6. 验证你读懂了改一个触发条件看最小Agent循环的行为变化6.1 30分钟跑通基线再改掉权限匹配规则读源码的最终检验不是能复述结构而是能改。我会用最后一个技巧帮你验证把上一章的最小循环提炼成一个纯逻辑的权限审批验证器然后故意改一个触发条件观察行为变化。如果你预料得到变化的方向说明你是真的读懂了这套源码的机制而不是记住了概念。# 最小权限审批验证器同一组调用对比两种匹配策略 def approve(tool_args: str, mode: str) - str: cmd tool_args.split()[0] if mode exact: allowed {ls, pwd} # 精确匹配白名单 else: allowed {ls, pwd, curl} # 额外放行curl return 通过 if cmd in allowed else 拒绝 call1 ls call2 curl -s http://example.com print(f[exact] ls - {approve(call1, exact)}) print(f[exact] curl - {approve(call2, exact)}) print(f[loose] curl -s - {approve(call2, loose)})跑这个脚本你会看到同一条curl命令在exact策略下被拒绝在loose策略下被放行。改动只在allowed集合里加了一个命令行为就变了这背后就是源码里权限审批模块的决策逻辑。真实实现比我这个验证器复杂得多涉及通配符、路径匹配、超时策略但验证原则一致先跑基线再改条件最后对比输出。我读过不止一份几万行的工程源码最大的教训是不要用分析文档替代源码也不要从第一个文件平推到最后一个文件地图、链路、改行为三者各来一遍才算消化。源码阅读不是读完是验证完的希望你用这套方法读这份源码时能少走我走过的弯路希望帮到你。本文还有配套的精品资源点击获取