Claude Code 源码架构全解析：Tool、Command、MCP 与权限系统

2026-03-31 约 15836 字预计阅读 40 分钟

Claude Code 源码架构全解析：Tool、Command、MCP 与权限系统

目标读者：希望系统理解 Claude Code 产品定位、源码快照价值、架构分层与扩展机制的开发者 核心问题：Claude Code 为什么不是普通聊天工具，而更像一个可扩展的软件工程代理平台？难度：⭐⭐⭐⭐（架构分析） 事实口径：官方产品能力以 Anthropic 官方资料为准；源码组织分析以 instructkr/claude-code 镜像说明为准 延伸阅读：Claude Code 最佳实践大全：22.9k Stars 的 AI 编程指南解读｜ Claude Code Skills & Plugins：AI 编程智能体技能库完全指南｜ Awesome Claude Code：从入门到精通 Claude Code 资源大全

如果你最近正好看到了 instructkr/claude-code 这个镜像仓库，最容易产生的两个误解是：第一，Claude Code 是不是已经“完全开源”；第二，这个项目的核心到底只是一个终端聊天器，还是一个真正的工程代理平台。本文会把这两个问题拆开讲清楚：哪些内容来自 Anthropic 官方公开资料，哪些内容来自公开快照镜像说明，以及 Tool、Command、MCP、Bridge、权限系统与多智能体机制是如何共同组成 Claude Code 的。

§0 先看结论

如果你时间有限，先记住下面 6 句话：

Claude Code 的官方定位是智能体式编程工具，不是普通聊天助手。
instructkr/claude-code 是公开快照镜像，不是 Anthropic 官方开源仓库。
真正决定 Claude Code 工程价值的，不是“回答效果”，而是工具系统 + 权限系统 + 工作流编排。
命令系统面向用户意图，工具系统面向执行动作，服务层负责隔离外部复杂性。
MCP、插件、技能、hooks 与 subagents 共同构成了 Claude Code 的扩展生态。
这份公开快照很适合学架构，但不应被误读为“今天线上版本的完整真相”。

§1 阅读说明与事实边界

这篇文章讨论的是两个相关但不能混为一谈的对象：

Claude Code 官方产品：Anthropic 官方发布的智能体式编程工具，官方 README 明确说明它可在终端、IDE 以及 GitHub 中使用。
instructkr/claude-code 镜像仓库：一个公开暴露快照的镜像与研究档案，不是 Anthropic 官方开发仓库。

为了严格尊重事实，本文采用以下写法原则：

官方文档能确认的内容，直接作为事实陈述。
镜像仓库 README 明确写出的内容，视为“镜像维护者公开声明”，不会写成 Anthropic 官方承诺。
无法从公开材料稳定核验的内容，不写成确定事实，不做脑补。
时间敏感数据（如 stars、forks、watchers）不作为核心结论。

如果你想把这篇文章当作学习材料，最稳妥的理解方式是：

产品能力、安装与使用方式，优先看 Anthropic 官方资料。
架构拆解与源码组织分析，把 instructkr/claude-code 当作公开快照研究材料。

§2 学习目标

完成本文档后，你将能够：

✅ 分清 Claude Code 官方产品与公开镜像快照的边界
✅ 理解这次公开事件的研究价值与伦理边界
✅ 从入门视角理解 Claude Code 的定位、基本使用方式与核心能力
✅ 从架构视角掌握 Tool System、Command System、Service Layer、Bridge System、Permission System 的职责划分
✅ 从开发者视角理解 Claude Code 的插件、技能、命令、MCP 与 hooks 扩展路径
✅ 从实践视角判断 Claude Code 适合什么场景，不适合什么场景
✅ 建立一条从“能用”到“能分析”再到“能扩展”的学习路径

§2.5 按你的目标选择阅读路径

如果你打开这篇文章，是带着不同任务来的，可以直接这样读：

想快速建立整体认识：优先阅读 §0、§3、§8、§21
想理解内部架构：重点阅读 §7、§8、§9、§10、§11、§12、§13、§14
想研究扩展开发：重点阅读 §16、§17、§18、§22
想判断是否适合自己团队：重点阅读 §5、§17、§19、§20

如果你读完本文后准备继续深入：

先去读 Claude Code 最佳实践大全：22.9k Stars 的 AI 编程指南解读
再去读 Claude Code Skills & Plugins：AI 编程智能体技能库完全指南
最后用 Awesome Claude Code：从入门到精通 Claude Code 资源大全做资源索引

§3 Claude Code 是什么

3.1 官方产品定位

Anthropic 官方 README 对 Claude Code 的描述很直接：它是一个运行在终端中的智能体式编程工具，能够理解代码库，通过自然语言帮助开发者：

执行常规开发任务
解释复杂代码
处理 Git 工作流
在终端、IDE 与 GitHub 场景中协作

这一定义很重要，因为它决定了 Claude Code 不是单纯的聊天助手，也不是只会“生成一段代码”的补全工具，而是一个带有上下文感知、工具调用、工作流编排能力的工程代理。

3.2 instructkr/claude-code 是什么

instructkr/claude-code 的仓库首页说明写得很清楚：它是一个公开暴露的 Claude Code 源码快照镜像，维护目的包括：

教育用途
防御性安全研究
软件供应链分析

它同时强调：

不拥有原始代码
不代表官方
不应被解读为 Anthropic 官方仓库

因此，研究这个仓库时，最正确的态度不是“这是 Claude Code 正式开源了”，而是：

这是一次公开快照，为外界提供了观察一个真实世界 AI 工程代理系统内部结构的窗口。

3.3 为什么这个项目值得研究

即使不讨论事件本身，这个快照仍然有很高的工程学习价值，因为它同时覆盖了现代 AI 编程工具最重要的几个维度：

CLI 产品形态：如何在终端里做出可交互、可扩展的复杂产品
工具编排：如何把文件、搜索、网络、子智能体、MCP 等能力统一到一个框架里
权限治理：如何让高权限工具在真实用户环境里安全运行
多通道集成：如何同时支持终端、IDE、GitHub、远程控制
扩展能力：如何为命令、插件、技能、hooks、MCP 留出边界清晰的扩展点

§4 公开事件背景与研究边界

4.1 公开事件的已知事实

根据镜像仓库 README 的公开说明，以及对外传播的公开线索，可以确认以下信息：

公开时间点为 2026 年 3 月 31 日
对外传播线索指向 X 上的公开帖子
镜像说明称，npm 分发中的 source map 暴露了可追溯到未混淆 TypeScript 源码的路径
镜像仓库保存的是一个 src/ 快照，而不是完整、连续的官方开发历史

这意味着我们能研究到的是：

一次具体时刻的源码组织方式
当时的产品能力结构
工具、命令、服务、权限、扩展模型的大体设计

但我们不能自动推导出：

这是当前官方最新实现
所有细节都与今天上线版本完全一致
所有 README 中的摘要描述都已通过逐文件人工复核

4.2 这类研究的价值在哪里

这类材料的价值，不在于“八卦”，而在于它能帮助我们认真回答几个工程问题：

一个真实的 AI 编程代理，到底有哪些核心模块？
它如何把自然语言请求转成工具调用和结果回传？
为什么权限系统必须是架构核心，而不是附属能力？
为什么扩展体系通常要同时包含命令、插件、技能、MCP、hooks？
为什么终端产品最后会长成“CLI + UI + 服务层 + 协议层 + 权限层”的形态？

4.3 伦理边界

这类公开快照只能用于：

教学研究
防御性分析
软件供应链安全讨论
工程架构学习

不应该用于：

伪装为官方代码
商业性复制
绕过安全控制
构造恶意衍生工具

这一点不是礼貌问题，而是研究边界问题。

§5 从入门开始：Claude Code 怎么用

这一节先不谈源码，先回答最实际的问题：如果你只是想把 Claude Code 用起来，官方公开材料告诉了你什么？

5.1 官方定位的三种使用入口

官方 README 明确提到，Claude Code 可以在以下场景中使用：

终端
IDE
GitHub

这三种入口背后，对应的是三种截然不同的工作方式：

终端模式：最适合日常编码、调试、阅读代码、执行命令
IDE 模式：更适合在编辑器上下文中边看边改
GitHub 模式：更适合让代理参与 PR、Issue、代码评审、自动化协作

5.2 官方安装方式

官方 README 列出了多种安装方式，其中值得注意的一点是：

npm 安装已被标记为 Deprecated
官方更推荐使用安装脚本、Homebrew、PowerShell 或 WinGet

示例：

curl -fsSL https://claude.ai/install.sh | bash

brew install --cask claude-code

irm https://claude.ai/install.ps1 | iex

winget install Anthropic.ClaudeCode

npm install -g @anthropic-ai/claude-code

其中最后一条虽然还列在 README 中，但已经被官方标成“已弃用”。

5.3 最基本的使用体验

官方 README 对 Claude Code 的描述可以浓缩成一句话：

它不是“问答框”，而是“带工具能力的工程代理入口”。

这意味着，用户给 Claude Code 的指令通常不是泛泛地“讲讲这个技术”，而是更接近：

帮我解释这个仓库
帮我修复一个 bug
帮我检查改动
帮我处理 Git 工作流
帮我在项目中定位某个能力的实现位置

从学习角度说，理解 Claude Code 的关键不是“它会不会写代码”，而是“它如何把用户目标转成一串可控的工程动作”。

5.4 一个典型的入门流程

如果你是第一次接触 Claude Code，可以按下面的顺序理解它的使用方式：

安装 Claude Code
进入你的项目目录
启动 Claude Code
用自然语言描述任务
根据需要批准工具调用
观察输出、修改、验证与继续追问

这个流程看起来简单，但背后已经包含了 Claude Code 的核心产品哲学：

用户给的是目标
系统负责把目标拆成上下文理解 + 工具执行 + 结果回收
用户在关键副作用节点保留控制权

5.5 CLI 入口示例能说明什么

官方 CLI 参考页的公开摘要中，可以看到一些典型入口形式，例如：

claude

claude "explain this project"

claude -p "explain this function"

claude -c -p "Check for type errors"

这些例子至少说明了三件事：

Claude Code 支持交互式会话
也支持单次查询后退出
还支持继续已有上下文的工作方式

这正好对应真实工程中的三类需求：

临时问答
批处理式调用
长任务续跑

§6 技术栈全景

根据镜像仓库 README 中的技术栈说明，可以整理出 Claude Code 的公开技术画像。

类别	技术	作用
运行时	Bun	启动、打包、特性裁剪
语言	TypeScript（strict）	类型安全与大型工程维护
终端 UI	React + Ink	终端交互界面
CLI 解析	Commander.js	命令行参数与入口管理
模式验证	Zod v4	工具输入与配置校验
搜索	ripgrep	高性能代码搜索
协议	MCP SDK、LSP	外部工具与语言服务集成
API	Anthropic SDK	模型调用与相关能力接入
遥测	OpenTelemetry + gRPC	可观测性
特性开关	GrowthBook	功能开关与条件加载
认证	OAuth 2.0、JWT、macOS Keychain	身份与密钥管理

这个技术组合非常有代表性，因为它对应了现代 AI 工程代理的五类核心需求：

运行效率：Bun、动态加载、并行预取
复杂交互：React + Ink
工程可靠性：TypeScript strict + Zod
外部连接能力：MCP、LSP、OAuth、Keychain
产品化能力：命令、遥测、特性开关、权限控制

6.1 为什么是 Bun

镜像 README 提到，Claude Code 使用 Bun 不只是“换个运行时”，而是直接影响三个工程目标：

启动性能
构建时的 dead code elimination
原生 TypeScript 友好性

这很符合一个大型 CLI 产品的需求。因为对终端工具来说，用户对“打开即用”的敏感度通常比 Web 应用更高，启动阶段每一点额外成本都会放大体感延迟。

6.2 为什么是 Ink + React

如果你以前只把终端程序理解成“命令输入 + 文本输出”，那么 Claude Code 的一个关键信号是：

终端已经被当成一个真正的交互式 UI 容器来设计了。

Ink 的价值在于，它让 CLI UI 不必停留在字符串拼接层，而能使用组件化、状态驱动、增量更新的方式组织界面。这对以下场景很关键：

流式输出
状态切换
进度展示
键盘交互
多面板或全屏界面

也正因为如此，Claude Code 并不是“套了一层终端皮肤的脚本”，而是一个严肃的终端应用。

§7 目录结构深度解析

镜像 README 给出了一个非常有价值的目录树。即使不看每个文件实现，光看目录层次，也能读出系统架构。

7.1 入口与核心文件

src/
├── main.tsx
├── commands.ts
├── tools.ts
├── Tool.ts
├── QueryEngine.ts
├── context.ts
├── cost-tracker.ts

这组文件很像一个标准的“核心引擎层”：

main.tsx：入口编排
commands.ts：命令注册
tools.ts / Tool.ts：工具系统定义与注册
QueryEngine.ts：模型交互与主循环
context.ts：上下文收集
cost-tracker.ts：消耗统计

如果把 Claude Code 想成一台机器，这几项分别对应：

开机
接收用户意图
装配可调用能力
驱动主循环
收集环境信息
统计资源成本

7.2 功能目录的职责切分

commands/
tools/
components/
hooks/
services/
screens/
types/
utils/
bridge/
coordinator/
plugins/
skills/
remote/
server/
tasks/
state/
schemas/

从职责上看，它不是“一层塞到底”的设计，而是明显做了分层：

commands/：用户可见入口
tools/：代理可执行能力
components/、screens/：终端交互界面
services/：外部系统与通用服务
bridge/：IDE 与远程桥接
plugins/、skills/：扩展与复用
tasks/、state/：任务与状态
schemas/：约束与验证

这种组织方式的好处是，系统扩展时不会只有“继续往一个巨型文件里堆逻辑”这条路。

7.3 核心大文件透露了什么

镜像 README 特别标出了几个大文件：

文件	公开说明中的职责
`QueryEngine.ts`	LLM 调用、流式响应、工具循环、重试、Token 计数
`Tool.ts`	工具基类、输入模式、权限模型、进度状态
`commands.ts`	命令注册与执行
`main.tsx`	CLI 入口与 Ink 渲染初始化

这说明 Claude Code 的复杂度主要集中在三个方向：

模型回路
工具抽象
命令分发

这也正是大多数 AI 编程代理最终会变复杂的地方。

§8 总体架构：Claude Code 是怎么跑起来的

可以把 Claude Code 抽象成下面这条主链路：

用户输入
  ↓
CLI / IDE / GitHub 入口
  ↓
命令解析与上下文收集
  ↓
Query Engine 调用模型
  ↓
模型决定是否调用工具
  ↓
权限系统检查
  ↓
工具执行 / 服务访问 / 外部协议调用
  ↓
结果回流给 Query Engine
  ↓
格式化输出给用户

从工程角度看，这个链路至少说明了三件事：

Claude Code 的核心不是“回复文本”，而是“驱动工作流”
工具与权限必须深度耦合，因为每一步执行都可能有副作用
模型并不是单独工作的，它被包裹在一个完整的软件执行框架里

8.1 一个更贴近实际的理解方式

如果你熟悉传统软件架构，可以这样类比：

main.tsx 像应用入口与启动器
commands.ts 像控制器或命令路由层
QueryEngine.ts 像业务编排核心
tools/ 像能力适配器集合
services/ 像基础设施服务层
bridge/ 像外部接入层
hooks/toolPermission/ 像安全网关

这也是为什么研究 Claude Code，不能只盯着“模型 prompt 是怎么写的”。真正决定系统质量的，往往是模型之外的工程结构。

§9 工具系统：Claude Code 真正的执行内核

9.1 为什么说工具系统才是核心

镜像 README 把 Tool System 放在架构总结的第一位，这是合理的。

原因很简单：用户真正感受到“智能”的地方，不在模型说得多漂亮，而在它能不能把事做完。而“把事做完”依赖的正是工具。

Claude Code 公开材料中出现的工具类型，覆盖了工程代理最关键的能力面：

工具类别	代表工具	解决的问题
执行类	`BashTool`	执行系统命令
文件类	`FileReadTool`、`FileWriteTool`、`FileEditTool`	读写项目文件
搜索类	`GlobTool`、`GrepTool`	定位文件与内容
网络类	`WebFetchTool`、`WebSearchTool`	获取外部信息
智能体类	`AgentTool`	派生子智能体
协议类	`MCPTool`、`LSPTool`	调外部协议能力
任务类	`TaskCreateTool`、`TaskUpdateTool`	管理执行过程
团队类	`TeamCreateTool`、`TeamDeleteTool`	多智能体协作
模式类	`EnterPlanModeTool`、`ExitPlanModeTool`	切换工作模式
调度类	`CronCreateTool`、`RemoteTriggerTool`	触发自动化

换句话说，Claude Code 并没有把自己做成一个“只会改文件”的工具，而是做成了一个面向软件工程全链路的操作面板。

9.2 工具调用为什么必须标准化

镜像说明中给出了一个非常关键的执行框架：工具调用要经历：

权限检查
输入验证
执行
结果序列化

这四步意味着 Claude Code 不是直接让模型“想到什么就调用什么”，而是给所有工具套上统一外壳。

这个设计有四个直接收益：

安全：先判断能不能做
稳定：先判断输入是否合法
可观测：每种工具都能产出统一结果
可扩展：新工具接入时，不必重新发明一套调用协议

9.3 工具系统为什么适合大规模扩展

镜像 README 对工具系统的描述是“每个工具定义自己的输入模式、权限模型和执行逻辑”。这句话其实已经概括了一个成熟工具框架的核心抽象：

输入模式：这个工具需要什么参数
权限模型：什么情况下允许执行
执行逻辑：真正做什么事

只要这三件事稳定下来，整个系统就能持续增长工具数量，而不会立即失控。

9.4 对普通开发者的启发

如果你也想做一个自己的 AI 工具平台，Claude Code 的工具系统给出的最重要经验不是“工具越多越好”，而是：

先把工具抽象做对，再去扩展工具数量。

§10 命令系统：用户如何驱动系统

10.1 斜杠命令的角色

镜像 README 表明，Claude Code 暴露了大量 / 前缀命令，例如：

/commit
/review
/compact
/mcp
/config
/doctor
/login
/logout
/memory
/skills
/tasks
/diff
/theme
/resume
/share

这些命令的意义，不只是“给用户多几个快捷方式”，而是把复杂能力按任务意图拆成一组可发现的入口。

举例来说：

/review 对应“代码审查”意图
/compact 对应“上下文压缩”意图
/mcp 对应“外部工具接入管理”意图
/doctor 对应“环境诊断”意图
/tasks 对应“执行过程管理”意图

这说明命令系统本质上是一个面向用户心智模型的产品层。

10.2 命令系统与工具系统的关系

很多人第一次看这类系统时，会混淆“命令”和“工具”。实际上两者解决的是不同问题：

命令系统面向用户：用户怎么表达意图
工具系统面向代理：代理怎么执行动作

你可以把命令理解为“产品界面层”，把工具理解为“执行能力层”。

10.3 为什么命令注册会变成大文件

镜像说明提到 commands.ts 是一个很大的文件，并且支持按环境条件导入不同命令集。

这通常意味着命令系统承担了这些工作：

汇总命令定义
按环境启用或关闭某些命令
对接特性开关
延迟加载重型命令模块

命令越多，这一层越容易演变成“控制中心”。这既是能力强的表现，也是维护难点所在。

§11 服务层：把外部复杂性隔离出去

11.1 服务层的本质

镜像 README 列出的服务层非常典型：

服务	主要职责
`api/`	Anthropic API、文件 API、引导配置
`mcp/`	MCP 服务器连接与管理
`oauth/`	OAuth 2.0 登录流程
`lsp/`	语言服务器接入
`analytics/`	特性开关与分析
`plugins/`	插件加载
`compact/`	上下文压缩
`policyLimits/`	组织策略限制
`remoteManagedSettings/`	远程托管设置
`extractMemories/`	自动记忆提取
`tokenEstimation.ts`	Token 估算
`teamMemorySync/`	团队记忆同步

从架构上看，服务层做的是一件极其关键的事：

把“外部系统的复杂性”从 Query Engine 和 UI 层隔离出去。

11.2 为什么这层不能省

如果没有服务层，模型主循环很快就会被以下问题污染：

API 认证细节
Token 估算逻辑
上下文压缩策略
插件加载细节
LSP / MCP 协议处理
组织策略限制

一旦这些都直接进到核心引擎层，系统会迅速失去清晰边界。

11.3 compact 服务为什么重要

镜像说明中特别点出了上下文压缩服务。这个能力在 AI 编程代理里非常关键，因为它不是“锦上添花”，而是长会话的生存条件。

Claude Code 面临的不是普通聊天，而是：

长时间迭代
多轮工具调用
大量项目上下文
任务状态延续

如果没有 compact 之类的服务，系统上下文会很快膨胀到不可控。

11.4 policyLimits 的信号意义

policyLimits/ 这个目录非常值得注意。它意味着 Claude Code 不只是服务单个开发者，还考虑到了：

团队约束
组织级策略
企业环境中的权限与边界

这也是很多“个人玩具级 AI 工具”与“企业可落地产品”之间的分水岭。

§12 Bridge System：为什么 Claude Code 不只属于终端

12.1 Bridge 的定位

镜像 README 将 Bridge System 定义为连接 IDE 扩展 与 Claude Code CLI 的双向通信层，明确提到了：

VS Code
JetBrains

这说明 Claude Code 从产品设计上就不是“纯 CLI 工具”，而是把 CLI 当成了一个统一执行核心，再通过 Bridge 把能力延伸到其他宿主环境。

12.2 为什么要单独做桥接层

因为 IDE 与 CLI 的运行约束完全不同：

CLI 更接近本地直接控制
IDE 更强调编辑器上下文、会话同步与 UI 集成
远程控制还涉及认证、消息协议、权限回调与会话管理

如果不单独抽出桥接层，这些差异会直接把主应用搞乱。

12.3 从文件名可以读出哪些职责

镜像说明中列出的文件名已经很能说明问题：

文件	透露出的职责
`bridgeMain.ts`	桥接主循环
`bridgeMessaging.ts`	消息协议
`bridgePermissionCallbacks.ts`	权限回调
`replBridge.ts`	REPL 会话桥接
`jwtUtils.ts`	认证
`sessionRunner.ts`	会话执行管理

从这里可以看出，Bridge 不是“转发几条消息”的薄层，而是一个真正的接入子系统。

§13 权限系统：AI 工具真正的护城河

13.1 为什么权限系统必须是架构核心

Claude Code 这类产品最危险的地方，不是回答错一个概念，而是：

执行了不该执行的命令
改了不该改的文件
把敏感信息暴露给外部服务
在错误上下文中做了破坏性操作

因此，权限系统不是“锦上添花的安全功能”，而是 Claude Code 能否成为真实生产力工具的前提。

13.2 公开材料中能确认的权限模型

镜像 README 给出了几种权限模式：

模式	含义
`default`	每次提示用户批准或拒绝
`plan`	在特定模式下进行额外控制
`bypassPermissions`	自动批准所有操作
`auto`	按规则自动决定

同时，镜像说明明确写到：权限检查发生在每一次工具调用时。

这一点非常关键，因为它说明 Claude Code 不是“先判断一次身份，后面随便跑”，而是把权限控制放在动作级别。

13.3 这对系统设计意味着什么

动作级权限检查有三个直接优势：

粒度细
更安全
更适合混合模式执行

例如，同一个会话中：

读取文件可能可以自动通过
写文件可能需要确认
执行 shell 命令可能需要更严格控制

这种精细化控制，是 AI 工程代理能进入真实工程环境的必要条件。

§14 特性开关、惰性加载与性能设计

14.1 Feature Flags 不只是“开关”

镜像 README 提到 Claude Code 使用 Bun 的 bun:bundle 配合特性开关做 dead code elimination，并列出了一组标志，例如：

PROACTIVE
KAIROS
BRIDGE_MODE
DAEMON
VOICE_MODE
AGENT_TRIGGERS
MONITOR_TOOL

这说明 Feature Flags 在 Claude Code 中至少承担三种任务：

产品分层：不同用户或环境可见不同能力
构建裁剪：未启用能力可直接在构建时剥离
风险隔离：实验特性不会强行进入所有运行路径

14.2 并行预取说明了什么

镜像说明还提到了启动阶段的并行预取，例如 MDM、Keychain、API 预连接、GrowthBook 初始化。

这释放出一个清晰信号：

Claude Code 已经在做“产品级启动优化”，而不是停留在脚本级实现。

这类优化通常只会出现在启动路径已经足够复杂、且团队开始认真关注冷启动体验时。

14.3 惰性加载为什么必要

镜像说明中提到重型模块通过动态 import() 延迟加载。这个策略在 Claude Code 中非常合理，因为它天然存在很多“并不是每次都会用到”的能力：

遥测
语音
桥接
某些特定命令
某些环境专属集成

惰性加载的收益非常直接：

减少冷启动成本
缩小默认路径复杂度
避免所有用户承担所有功能的代价

§15 多智能体、技能与任务系统

15.1 子智能体不是“锦上添花”

镜像 README 明确提到了：

AgentTool
coordinator/
TeamCreateTool
TeamDeleteTool
多智能体团队协作示例

这说明 Claude Code 的“代理”设计，不只支持一个单体代理，还支持将任务拆给多个角色。

15.2 多智能体的工程意义

多智能体设计的重点不在于“更酷”，而在于解决不同角色的偏置问题。例如：

Planner 更擅长拆解任务
Coder 更擅长实现
Reviewer 更擅长挑错与校验

把这些角色拆开后，系统可以在一个总任务下形成更强的内部分工。

15.3 Skill System 的价值

镜像 README 将 skills/ 描述为“可复用工作流定义目录”，官方插件文档也明确把 skills/ 作为插件目录结构的一部分。

这意味着 Skill 的核心价值不是“多一个 prompt 文件”，而是：

把高频工作流沉淀为可重用资产
让团队形成标准化做事方式
让复杂任务拥有稳定执行框架

如果说命令是面向用户的入口，那么技能更像是面向团队与流程的“工作模板”。

15.4 任务系统的重要性

镜像 README 中同时存在 tasks/ 目录，以及 TaskCreateTool / TaskUpdateTool。这说明 Claude Code 并没有把执行过程完全埋在“黑箱对话”里，而是尝试让任务状态显式化。

这一点很重要，因为复杂工程任务通常都需要：

任务拆分
状态追踪
阶段反馈
结果回收

没有任务系统，代理就很容易变成“看上去很忙，实际上难以审计”的黑盒。

§16 开发扩展：Claude Code 如何被二次开发

这一节是本文最适合开发者实践的部分。即使你完全不关心镜像快照，只想知道 Claude Code 官方提供了哪些扩展面，这一节也值得看。

16.1 官方插件目录结构

官方插件文档给出的标准结构大致如下：

plugin-name/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── agents/
├── skills/
├── hooks/
├── .mcp.json
└── README.md

这个结构本身就说明 Claude Code 的扩展体系不是单点扩展，而是多通道扩展：

commands/：扩展斜杠命令
agents/：扩展专业子智能体
skills/：扩展工作流能力
hooks/：扩展事件驱动逻辑
.mcp.json：接外部 MCP 工具

16.2 plugin.json 说明了什么

官方插件资料中的 plugin.json 主要用于定义：

插件名称
版本
描述
作者信息

这意味着 Claude Code 的插件体系不是“把文件随手丢进某个目录”，而是有明确元数据边界的正式扩展机制。

16.3 自定义命令如何定义

官方插件开发示例显示，命令可以用 Markdown 文件定义，并使用 frontmatter 描述命令接口。例如：

---
description: Generate documentation for file
argument-hint: [source-file]
---

Generate comprehensive documentation for @$1

这里至少释放出三个重要信号：

命令是声明式定义的
命令支持参数提示
命令本质上是在给代理下结构化任务说明

16.4 `allowed-tools` 的价值

官方插件开发资料里还出现了 allowed-tools 这样的 frontmatter 字段。例如某个命令只允许使用特定 MCP 工具。

这说明扩展系统不是“写了命令就能随便调用所有能力”，而是支持：

明确授权边界
控制命令可用工具集合
降低扩展失控风险

这是一种非常成熟的扩展治理思路。

16.5 MCP 是怎么接进来的

官方教程搜索结果显示，Claude Code 支持类似下面的 MCP 接入方式：

claude mcp add <name> <command> [args...]

这说明 Claude Code 并没有把外部工具接入做成“内置耦合”，而是通过 MCP 把它协议化。这样做的好处非常明显：

外部工具可以独立演进
Claude Code 不必内置所有能力
团队可以按需接自己的数据源和自动化系统

16.6 hooks 适合做什么

官方 hooks 参考页的公开摘要至少能看到一些事件名，例如：

UserPromptSubmit
Notification
Stop
SubagentStop

这已经足够说明，hooks 的目标是让 Claude Code 支持事件驱动型自动化。典型用途包括：

用户提交请求前做预处理
任务结束后做通知
子智能体结束后补充记录
在关键节点执行统一团队规则

16.7 自定义 subagents 的方向

官方 CLI 参考页的公开摘要提到，CLI 支持 --agents 标志，通过 JSON 动态定义自定义 subagents。

这意味着 Claude Code 的可扩展性并不局限于“扩工具”或“扩命令”，还包括“扩角色”。这对团队化使用非常关键，因为不同团队常常需要：

审查型代理
文档型代理
测试型代理
基础设施型代理
安全型代理

把角色扩展做成一等能力，是智能体系统比传统 CLI 更先进的地方。

§17 使用场景：Claude Code 适合拿来做什么

17.1 适合的场景

基于官方产品定位与镜像快照体现出的能力边界，Claude Code 特别适合以下场景：

大型代码库理解：搜索、上下文、命令、解释联动
多步骤工程任务：定位问题、编辑代码、执行命令、检查结果
代码评审与修复建议：尤其是 /review 这类命令式入口
环境诊断与维护性工作：如配置检查、依赖分析、工作流整理
团队标准化工作流：借助技能、命令、插件、hooks、MCP 沉淀规范
IDE / CLI / GitHub 贯通协作：适合需要跨环境一致体验的团队

17.2 不适合或需要谨慎的场景

同时，它并不是所有任务的最佳选择：

高风险生产操作：必须有清晰权限边界与人工确认
极强确定性要求的任务：仍然需要传统自动化与测试兜底
对数据流转极度敏感的环境：需要先明确组织策略和合规边界
仅需要单一命令的小工具场景：Claude Code 可能显得过重

17.3 最能发挥价值的组织类型

如果从团队视角看，Claude Code 特别适合：

代码库较大、上下文复杂的团队
希望把工程知识沉淀为技能与命令的团队
需要在终端、IDE 与代码托管平台之间统一体验的团队
对工具治理、权限治理、流程标准化有要求的团队

§18 从入门到精通的学习路径

如果你想真正学透 Claude Code，建议按下面的顺序走，而不是一上来就钻到大文件里。

18.1 第一阶段：先会用

目标：

理解官方定位
理解安装方式
理解终端、IDE、GitHub 三种使用入口
理解“命令”“工具”“权限”的基本概念

建议问题：

Claude Code 与普通聊天助手有什么本质差异？
为什么工程代理必须拥有工具系统？
为什么 npm 安装被官方标记为已弃用？

18.2 第二阶段：再看架构

目标：

搞清 main.tsx、commands.ts、Tool.ts、QueryEngine.ts 的角色分工
理解服务层、桥接层、权限层的边界
理解为什么长会话必须有 compact 之类的能力

建议问题：

命令系统与工具系统如何协作？
为什么权限控制必须发生在每次工具调用时？
为什么 CLI 产品会需要 React + Ink？

18.3 第三阶段：进入扩展开发

目标：

读懂插件目录结构
学会定义命令、技能、代理、hooks
理解 MCP 为什么是高扩展性的关键

建议问题：

自定义命令适合做什么？
Skill 与 Command 的边界是什么？
什么样的能力应该做成 MCP，而不是内置工具？

18.4 第四阶段：站在产品与平台视角复盘

目标：

从“功能列表”上升到“平台架构”
理解 Claude Code 为什么能同时支持终端、IDE、GitHub
理解它为什么要做团队协作、权限治理、策略限制与遥测

这一阶段真正要回答的问题是：

Claude Code 为什么看起来像一个 CLI，内部却更像一个软件工程操作系统？

§19 自测与练习

19.1 基础理解题

请尝试不用看原文，直接回答下面 3 个问题：

Claude Code 与普通聊天助手最大的差异是什么？
为什么工具系统比“回答文本”更能决定 Claude Code 的实际价值？
为什么本文必须把官方产品与镜像快照区分开来？

19.2 架构分析题

如果你已经具备一些工程经验，可以继续思考：

如果拿掉权限系统，Claude Code 会在哪些地方立即变得危险？
如果拿掉服务层，QueryEngine.ts 最容易被哪些外部复杂性污染？
如果没有 Bridge 与 MCP，Claude Code 的扩展上限会卡在哪里？

19.3 迁移实践题

假设你要为自己的团队做一个内部 AI 工程代理，请先写出你的最小架构草图，并至少回答：

你的工具抽象怎么设计？
你的权限模型放在哪一层？
你的命令、技能、插件、MCP 是否都需要，为什么？
你如何处理长会话中的上下文压缩与任务状态？

如果这 4 个问题还回答不清，说明你还处在“会用”阶段，尚未真正进入“会设计”阶段。

§20 常见问题

20.1 这是不是 Claude Code 官方开源？

不是。公开镜像仓库明确强调它是镜像快照与研究档案，不应被视为 Anthropic 官方仓库。

20.2 这份快照能代表今天的官方实现吗？

不能直接这么理解。它更像某个时间点的公开快照，适合做架构研究，不适合被当成“当前官方实现的逐行真相”。

20.3 为什么这篇文章既讲官方产品，又讲镜像快照？

因为两者回答的是不同问题：

官方资料回答“它怎么安装、怎么用、有哪些正式扩展面”
镜像快照回答“它内部大概是怎么组织起来的”

只讲一边，结论都会失真。

20.4 我能直接照着这份快照去做自己的产品吗？

你可以学习其中的架构思想，但不要把一次公开快照等同于最佳实践模板。真正值得迁移的，是这些原则：

工具抽象要统一
权限控制要动作级
服务层要隔离外部复杂性
扩展机制要有清晰边界
长会话系统必须考虑上下文压缩与任务状态

§21 架构总结

如果把本文内容压缩成几个最重要的结论，那就是：

Claude Code 的本质不是聊天工具，而是工程代理平台
工具系统是执行核心，命令系统是产品入口，服务层是外部复杂性的隔离带
权限系统不是附属能力，而是架构级核心
Bridge、MCP、插件、技能、hooks 共同构成了它的扩展生态
公开镜像快照适合做研究材料，但不能替代官方文档与官方实现

如果你从这篇文章只带走一句话，我希望是：

Claude Code 值得研究的地方，不只是“它用了什么模型”，而是它如何把模型、工具、权限、协议、UI 与扩展机制组合成一个真正可用的工程系统。

§22 下一步行动建议

如果你准备把“看懂”转成“真正用起来”，建议直接选一条路径继续：

想把 Claude Code 用顺手：下一篇去读最佳实践文章，把命令、工作流与常见使用误区补齐。
想自己做扩展：下一篇去读 Skills & Plugins 文章，把命令、技能、插件与跨平台转换链路搞明白。
想系统追踪生态：下一篇去读 Awesome 资源大全，把常用扩展、社区项目与资料入口收集完整。
想做自家 AI 工程代理：回看本文 §9、§11、§13、§16，再把工具抽象、权限模型与扩展边界画成你自己的架构图。

你不一定要一次看完所有内容，但最好立即选一条路径继续，否则这篇文章带来的理解很容易停留在“知道有这些概念”。

§23 延伸阅读

如果你接下来想继续把 Claude Code 学深，建议按下面的顺序延伸：

Claude Code 最佳实践大全：22.9k Stars 的 AI 编程指南解读：适合从“会用”走向“用得更稳、更快”。
Claude Code Skills & Plugins：AI 编程智能体技能库完全指南：适合理解 Skills、Plugins 与跨平台复用。
Awesome Claude Code：从入门到精通 Claude Code 资源大全：适合系统收集生态资源、扩展项目与工作流资料。

如果你的目标是：

学产品与架构：优先读本文
学最佳实践与工作流：优先读最佳实践那篇
学扩展与技能生态：优先读 Skills & Plugins 那篇
找更多资料入口：优先读 Awesome 资源大全

§24 参考来源

24.1 官方来源

Anthropic 官方 README：https://github.com/anthropics/claude-code/blob/main/README.md
Anthropic 官方文档站：https://docs.anthropic.com/en/docs/claude-code/
官方插件目录与示例：https://github.com/anthropics/claude-code/tree/main/plugins

24.2 镜像与公开线索

镜像仓库：https://github.com/instructkr/claude-code
公开传播线索：https://x.com/Fried_rice/status/2038894956459290963

24.3 本文的取材说明

本文优先依据以下几类公开材料进行整理：

镜像仓库 README 中明确写出的目录、技术栈与架构摘要
Anthropic 官方 README 中明确写出的产品定位与安装方式
官方插件与文档资料中可确认的扩展方式，例如命令、技能、hooks、MCP、插件目录结构

凡是缺乏稳定公开来源支撑的内容，本文一律不写成确定事实。

文档版本 2.0 | 撰写日期：2026-03-31 | 基于公开镜像说明与 Anthropic 官方资料整理 | 仅供教育研究用途

目录

Claude Code 源码架构全解析：Tool、Command、MCP 与权限系统

Claude Code 源码架构全解析：Tool、Command、MCP 与权限系统

§0 先看结论

§1 阅读说明与事实边界

§2 学习目标

§2.5 按你的目标选择阅读路径

§3 Claude Code 是什么

3.1 官方产品定位

3.2 instructkr/claude-code 是什么

3.3 为什么这个项目值得研究

§4 公开事件背景与研究边界

4.1 公开事件的已知事实

4.2 这类研究的价值在哪里

4.3 伦理边界

§5 从入门开始：Claude Code 怎么用

5.1 官方定位的三种使用入口

5.2 官方安装方式

5.3 最基本的使用体验

5.4 一个典型的入门流程

5.5 CLI 入口示例能说明什么

§6 技术栈全景

6.1 为什么是 Bun

6.2 为什么是 Ink + React

§7 目录结构深度解析

7.1 入口与核心文件

7.2 功能目录的职责切分

7.3 核心大文件透露了什么

§8 总体架构：Claude Code 是怎么跑起来的

8.1 一个更贴近实际的理解方式

§9 工具系统：Claude Code 真正的执行内核

9.1 为什么说工具系统才是核心

9.2 工具调用为什么必须标准化

9.3 工具系统为什么适合大规模扩展

9.4 对普通开发者的启发

§10 命令系统：用户如何驱动系统

10.1 斜杠命令的角色

10.2 命令系统与工具系统的关系

10.3 为什么命令注册会变成大文件

§11 服务层：把外部复杂性隔离出去

11.1 服务层的本质

11.2 为什么这层不能省

11.3 compact 服务为什么重要

11.4 policyLimits 的信号意义

§12 Bridge System：为什么 Claude Code 不只属于终端

12.1 Bridge 的定位

12.2 为什么要单独做桥接层

12.3 从文件名可以读出哪些职责

§13 权限系统：AI 工具真正的护城河

13.1 为什么权限系统必须是架构核心

13.2 公开材料中能确认的权限模型

13.3 这对系统设计意味着什么

§14 特性开关、惰性加载与性能设计

14.1 Feature Flags 不只是“开关”

14.2 并行预取说明了什么

14.3 惰性加载为什么必要

§15 多智能体、技能与任务系统

15.1 子智能体不是“锦上添花”

15.2 多智能体的工程意义

15.3 Skill System 的价值

15.4 任务系统的重要性

§16 开发扩展：Claude Code 如何被二次开发

16.1 官方插件目录结构

16.2 plugin.json 说明了什么

16.3 自定义命令如何定义

16.4 allowed-tools 的价值

16.5 MCP 是怎么接进来的

16.6 hooks 适合做什么

16.7 自定义 subagents 的方向

§17 使用场景：Claude Code 适合拿来做什么

17.1 适合的场景

17.2 不适合或需要谨慎的场景

17.3 最能发挥价值的组织类型

§18 从入门到精通的学习路径

18.1 第一阶段：先会用

18.2 第二阶段：再看架构

18.3 第三阶段：进入扩展开发

18.4 第四阶段：站在产品与平台视角复盘

§19 自测与练习

19.1 基础理解题

16.4 `allowed-tools` 的价值