Claude Code 的功能 — 以及使用时会发生什么
追踪从终端到 AI 驱动的代码改变的旅程
同样的 AI,但运行在你的终端中
你可能已经在浏览器中使用过 ChatGPT 或 Claude。Claude Code 是同样的 AI — 但它运行在你的 终端 中,可以真正操作你的文件,并运行命令。
真正的力量不在于 Claude 可以写代码 — 而在于 Claude Code 在 AI(理解语言)和你的计算机(只理解代码和命令)之间建立了一座桥梁。
让我们追踪当你输入 "修复 login.ts 中的 bug"时会发生什么。
理解你的意图
你用简单的英语输入 — 不需要特殊的语法或命令
采取行动
实际编辑文件、运行命令,并实现变更
学习你的代码库
读取你的文件以理解上下文并做出智能决策
旅程:从你的按键到代码变更
当你输入一个命令时,你的请求会经历一段相当长的旅程。让我们一步一步追踪它。
为什么要了解这些? 理解这个流程有助于你在 Claude 卡住时进行调试("是它误解了我,还是命令失败了?"),编写更好的提示词("我应该要求它使用编辑工具,而不是仅仅说'修改 X'"),并知道实际上在幕后发生了什么。
幕后:一切如何开始
一切都从 main.tsx 开始 — 这是 Claude Code 启动的入口点。让我们一起阅读前 20 行。
// These side-effects must run before all other imports:
// 1. profileCheckpoint marks entry before heavy module evaluation begins
// 2. startMdmRawRead fires MDM subprocesses (plutil/reg query) so they run in
// parallel with the remaining ~135ms of imports below
// 3. startKeychainPrefetch fires both macOS keychain reads (OAuth + legacy API
// key) in parallel — isRemoteManagedSettingsEligible() otherwise reads them
// sequentially via sync spawn inside applySafeConfigEnvironmentVariables()
// (~65ms on every macOS startup)
import { profileCheckpoint, profileReport } from './utils/startupProfiler.js';
// eslint-disable-next-line custom-rules/no-top-level-side-effects
profileCheckpoint('main_tsx_entry');
import { startMdmRawRead } from './utils/settings/mdm/rawRead.js';
// eslint-disable-next-line custom-rules/no-top-level-side-effects
startMdmRawRead();
这些注释解释了三个必须首先运行的启动任务 — 在任何其他代码加载之前。
1. 标记起点,这样我们可以测量启动需要多长时间...
2. 启动后台任务并行读取系统设置 (MDM)...
3. 提前开始读取 macOS 钥匙串 (API 密钥所在的地方)...
这通过并行读取而不是逐个读取,每次启动节省约 65 毫秒。
导入我们刚才提到的性能分析工具...
将这一时刻标记为 "main_tsx_entry" — 我们正式开始了!
导入 MDM (移动设备管理) 读取器...
现在就开始读取这些系统设置 — 不要等待!
这段代码都是为了速度。通过一次启动多个后台任务(而不是等待每个任务完成),Claude Code 启动得更快。工程师称之为"并行执行"。
群聊:组件之间如何对话
把 Claude Code 想象成一个群聊,不同的组件在其中协调完成你的工作。这就是那个对话的样子。
测试你的理解
让我们看看你是否掌握了 Claude Code 的工作原理。这些场景测试你是否能够追踪流程并理解架构。
当你在终端中输入 claude-code 时,首先发生的是什么?
你运行 /commit 来创建一个 git 提交。这个命令位于代码库的哪个部分?
Claude 想要读取一个文件来理解你的代码。它使用哪个"工具"?
下一步
现在你理解了大局:你的终端输入 → main.tsx → 查询引擎 → Anthropic API → 工具 → 文件系统 → 回到你。
Claude Code 是语言(你所说的)和代码(你的计算机所理解的)之间的桥梁。理解这个流程有助于你调试问题、编写更好的提示词,并更有效地引导 AI。
但是等等 — 我们一直在谈论的这些"参与者"都是谁?工具 vs. 命令 vs. 服务到底是什么?
Claude 可以采取的操作 — 比如读取文件、运行命令或编辑代码
你可以直接运行的快捷方式 — 比如 /commit 或 /clear
处理设置、会话和 API 通信等事情的后台系统
接下来: 我们将逐一认识每个参与者,了解他们的作用、他们在代码库中的位置,以及如何有效地与他们合作。
认识角色 —— 工具、命令和服务
把 Claude Code 想象成一个拥有不同类型技能的电子游戏角色
三种能力类型
在上一个模块中,我们看到 Claude Code 有不同的"角色"。现在让我们亲自认识它们。
工具
Claude 可以随时使用的基本能力 —— 比如读取文件或运行终端命令
命令
常见任务的必杀技 —— 将多个工具捆绑在一起的快捷方式
服务
来自盟友的力量 —— 与外部世界的连接,比如 GitHub 和身份验证
当 Claude 遇到困难时,知道哪个角色负责帮助你调试。"Bash 工具失败"与"Claude 感到困惑"是非常不同的情况。此外,你可以给出更好的指令 —— 比如"使用 Glob 工具查找所有 .ts 文件",而不仅仅是"查找所有 TypeScript 文件"。
工具 —— Claude 能做什么
工具是 Claude 的基本能力。它们是构建块 —— Claude 可以随时执行的独立操作。
Bash
运行终端命令(如 git status、npm install、ls)
Read
从你的电脑读取文件内容
Write
创建或完全替换文件
Edit
在文件中进行特定的文本替换
Glob
按模式查找文件(如 **/*.ts 查找所有 TypeScript 文件)
Grep
在文件中搜索文本(如搜索 "function")
总共有大约 40 个工具 —— 每个都擅长做一件事。把它们想象成遥控器上的独立按钮。
命令 —— 必杀技
斜杠命令是一个预先打包的配方。它将特定的工具与使用说明捆绑在一起。
例如,/commit 命令旨在安全地创建git 提交。以下是它在幕后的工作原理:
const ALLOWED_TOOLS = [
'Bash(git add:*)',
'Bash(git status:*)',
'Bash(git commit:*)',
]
const command = {
type: 'prompt',
name: 'commit',
description: 'Create a git commit',
allowedTools: ALLOWED_TOOLS,
prompt: getPromptContent(),
}
创建此命令允许的工具列表...
它可以运行 "git add" 来暂存文件...
它可以运行 "git status" 来查看更改内容...
它可以运行 "git commit" 来保存快照...
这是命令的定义 —— 它的 type "prompt" 意味着它给 Claude 提供指令...
名称是 "commit" —— 这就是你输入的内容(/commit)...
描述告诉 Claude 这个命令做什么...
allowedTools 限制通过只允许 git 命令来保持安全...
prompt 包含 Claude 应遵循的详细指令...
通过限制工具,/commit 命令不会意外删除文件或运行危险命令。这是一个安全网。
命令如何委托给工具
当你运行斜杠命令时,就像将任务分配给项目经理,然后由项目经理协调工人(工具)。观察 /commit 如何与团队沟通:
命令负责协调,但工具执行实际工作。这种分离保持一切井井有条且安全。
将工具与其用途匹配
让我们测试一下你的理解。将每个工具或命令拖到它的功能上:
运行终端命令
读取文件内容
在文件中进行文本替换
按模式查找文件(如 *.ts)
创建 git 提交
查看代码更改
测试你的理解
你想让 Claude 创建一个 git 提交。你应该说"使用 Commit 工具"还是"运行 /commit"?为什么?
Claude 想要读取一个 PDF 文件。它应该使用哪个工具?
/commit 命令需要运行 git 命令。它如何知道允许使用哪些 git 命令?
你正在构建一个类似的工具。你应该把新的"部署到生产环境"快捷方式放在哪里 —— tools/ 还是 commands/?
我们学到了什么
Claude 的基本能力 —— Read、Bash、Edit、Glob 和约 35 个其他工具。每个都擅长做一件事。
预先打包的配方,如 /commit,将工具与指令和安全限制捆绑在一起。
当你运行斜杠命令时,它协调工具 —— 就像项目经理将任务分配给工人一样。
当 Claude 遇到困难时,问问自己:"哪个角色遇到了问题?"如果 Bash 工具失败,检查命令。如果 Claude 看起来很困惑,尝试更具体地说明要使用哪个工具。
下一节:各部分如何对话 —— 查询引擎循环
现在你了解了角色,让我们看看当你要求 Claude 做某事时它们如何沟通。
组件如何对话——查询引擎循环
Claude 与你的代码库之间的对话
你输入"重构认证代码"
Claude 并不是神奇地自动完成这一切——它会通过一个结构化的循环:读取认证文件 → 理解结构 → 提出修改方案 → 编辑文件。这个循环就是查询引擎,它是 Claude Code 的核心。
查询引擎管理 Claude(AI)与你的代码库(文件/工具)之间的来回交互。每个工具调用都通过它进行。Claude 的每个响应也都通过它返回。它是协调一切的礼宾员。
接收你的请求
接收你输入的内容,并将可用工具一起发送给 Claude
执行工具调用
运行 Claude 请求的工具——读取文件、编辑代码、运行命令
重复直到完成
持续对话,直到任务完成
循环:这是对话,不是单行道
把查询引擎想象成你与一位能干的礼宾员之间的对话。循环的每次迭代都是一次来回交流。
你输入你想要的内容——"重构认证代码"——查询引擎将其发送给 API
API 根据你的请求响应工具调用——"读取 auth.ts,然后读取 config.ts"
查询引擎运行每个工具(如果需要,需要你的权限)并收集结果
结果返回给 Claude,Claude 决定下一步做什么——编辑文件?运行另一个工具?还是完成了?
循环持续——读取、编辑、再读取、再编辑——直到任务完成
当 Claude 陷入循环时("我尝试了 X,然后 Y,然后 Z..."),理解这个流程可以帮助你看出原因。Claude 是否调用了错误的工具?工具是否静默失败?Claude 是否误解了输出?这些知识帮助你有效地干预。
幕后:查询引擎需要什么
让我们看看 QueryEngine.ts 的导入语句。这些告诉我们引擎需要什么来完成工作。
import { feature } from 'bun:bundle'
import type { ContentBlockParam } from '@anthropic-ai/sdk/resources/messages.mjs'
import { randomUUID } from 'crypto'
import last from 'lodash-es/last.js'
import {
getSessionId,
isSessionPersistenceDisabled,
} from 'src/bootstrap/state.js'
import type {
PermissionMode,
SDKCompactBoundaryMessage,
SDKMessage,
SDKPermissionDenial,
SDKStatus,
SDKUserMessageReplay,
} from 'src/entrypoints/agentSdkTypes.js'
import { accumulateUsage, updateUsage }
from 'src/services/api/claude.js'
import type { NonNullableUsage }
from 'src/services/api/logging.js'
import { EMPTY_USAGE }
from 'src/services/api/logging.js'
import stripAnsi from 'strip-ansi'
import type { Command } from './commands.js'
import { getSlashCommandToolSkills }
from './commands.js'
import {
LOCAL_COMMAND_STDERR_TAG,
LOCAL_COMMAND_STDOUT_TAG,
} from './constants/xml.js'
import {
getModelUsage,
getTotalAPIDuration,
getTotalCost,
} from './cost-tracker.js'
import type { CanUseToolFn }
from './hooks/useCanUseTool.js'
打包: 需要打包代码以便分发(使用 Bun 的打包器)...
类型: 从 Anthropic 的 SDK 导入消息类型——定义 Claude 如何发送/接收数据...
UUID 生成: 创建唯一 ID 以跟踪请求和会话...
工具: 使用 lodash 的 'last' 函数获取数组的最后一项...
会话状态: 需要知道我们在哪个会话中以及是否保存历史记录...
权限类型: 定义工具何时需要批准——自动运行、始终询问或用户定义...
消息跟踪: 处理权限拒绝、状态更新和消息重放的类型...
使用跟踪: 监控 API 使用情况(token、成本、时间),以便向你展示会话花费...
日志类型: 用于跟踪 API 使用指标的标准化类型...
默认值: 用于初始化计数器的空使用对象...
文本格式化: 从终端输出中去除 ANSI 颜色代码(以便干净显示)...
命令处理: 处理像 /commit 或 /review 这样的斜杠命令...
命令工具: 获取可用的斜杠命令作为 Claude 可以调用的工具...
XML 标签: 用于解析命令输出(stdout/stderr)的常量...
成本跟踪: 计算总 token 使用量、API 时间和美元成本...
权限检查: 函数类型,用于检查 Claude 是否被允许使用特定工具...
看到规律了吗?查询引擎需要:与 API 通信、跟踪权限、处理命令、监控成本和格式化输出。它是确保所有部分协同工作的编排者。
观察循环的实际运行
让我们跟踪一个完整的请求在系统中的流动。点击"下一步"来跟踪数据在组件之间的流动。
这个循环会持续——每个工具调用都会导致另一个决策,而另一个决策又会导致另一个工具调用,直到 Claude 认为任务完成。这就是为什么它被称为"对话"——Claude 不断检查"我完成了吗?下一步是什么?"
调试循环:当 Claude 卡住时
有时 Claude 似乎会无限循环,一遍又一遍地做同样的事情。理解查询引擎可以帮助你找出问题所在。
错误的工具调用
Claude 一直在错误的文件路径上调用 FileRead——检查文件是否存在,以及 Claude 是否有正确的路径
静默失败
工具失败但 Claude 没有注意到——结果可能为空或格式错误,所以 Claude 继续尝试
误解输出
Claude 读取工具结果但误解了其含义——导致不相关的后续步骤
权限循环
Claude 请求权限,你拒绝,但它没有替代方案——所以它再次询问
如何干预
"文件在 src/lib/auth.ts 而不是 src/auth.ts"比"路径错了"更能指导 Claude
"不要读取整个文件,而是搜索'authenticate'函数"可以重定向循环
"先只读取文件并告诉我里面有什么"可以防止过早行动
测试你的知识:调试循环
这些场景测试你对查询引擎工作原理的理解。应用你学到的知识来诊断和修复问题。
Claude 试图编辑文件但一直说"找不到文件"。你应该首先检查查询引擎循环的哪个部分?
Claude 说"我需要权限来运行这个命令"。权限检查在循环的哪个位置进行?
你注意到 Claude 一直在同一文件上调用 FileRead 工具。你应该在循环的哪个位置添加缓存来解决这个问题?
用户报告他们的 Claude Code 会话"卡住了"——Claude 一直在尝试不同的事情但没有进展。你应该在查询引擎循环的哪个位置添加"放弃并请求帮助"的条件?
你学到了什么
查询引擎是管弦乐队的指挥——协调你、Claude、工具和代码库之间的关系。你的每个请求都通过这个循环流动,每个工具调用都是正在进行的对话的一部分。
理解循环可以帮助你在出现问题时进行调试。Claude 是否调用了错误的工具?工具是否静默失败?Claude 是否误解了输出?现在你知道在哪里查找——以及如何有效地干预。
接下来:终端 UI
我们已经介绍了后端循环——请求如何在系统中流动。但是你实际上如何看到发生了什么?在下一个模块中,我们将探索终端 UI,React 在命令行中运行以实时显示 Claude 的响应。
终端界面 —— 命令行中的 React
Claude Code 如何使用 Ink、React 和 ANSI 转义码渲染丰富的界面
终端里的 React?
你知道网站如何使用 React 来显示按钮、输入框和布局吗?Claude Code 也使用 React —— 但它不是渲染到浏览器,而是渲染到你的终端。
Ink 就像一场木偶戏,React 在幕后拉动着线。React 知道如何描述 UI 组件("这里显示一个按钮,那里显示文本"),而 Ink 将其翻译成终端所能理解的神秘控制代码。这就像有一个既懂 React 又懂终端的翻译官。
React 组件
使用熟悉的 React 模式描述 UI —— Box、Text、Button —— 就像网页开发一样
Ink 渲染器
将 React 的虚拟 DOM 转换为终端兼容的指令
终端显示
使用基于文本的转义序列显示颜色、布局和交互
Ink 如何工作:从组件到字符
让我们追踪当你在 Claude Code 中看到彩色按钮时发生的事情。
组件使用 JSX 和 props 说"显示一个红色的按钮,文本是'提交'"
布局引擎(Yoga)确定每个元素的位置 —— 就像文本的网格系统
颜色和位置被转换为终端理解的特殊转义序列
你的终端解释代码并显示彩色、定位的文本
当终端中的外观出现问题时(文本重叠、颜色不对、奇怪的字符),理解 Ink 可以帮助你知道从哪里查找。是 React 组件的问题?Ink 渲染的 bug?还是终端能力的问题?
代码 ↔ 中文:Text 组件
这是一个简单的 组件 如何从 React props 转换为终端转义码。
const Text: FC<TextProps> = function({ children, color, bold }) {
// 将 props 转换为 ANSI 转义码
// 例如,{ color: 'red', bold: true }
// 变成 '\x1b[31m\x1b[1m'
const styles = toANSI({ color, bold });
return <span style={{ color, fontWeight: bold ? 'bold' : 'normal' }}>
{children}
</span>;
};
这是一个名为 Text 的 React 组件,它接受三个输入:要显示的内容(children)、颜色和是否加粗...
我们将这些样式选项转换为 ANSI 转义码 —— 终端能理解的秘密语言。红色变成 \x1b[31m,加粗变成 \x1b[1m...
我们渲染一个应用了样式的 span 元素 —— React 不知道这是为终端用的,它只看到普通的 style props...
我们在内部显示内容。Ink 会在幕后处理到终端代码的转换...
变成 \x1b[31m —— "开始红色"
变成 \x1b[1m —— "开始加粗文本"
变成 \x1b[0m —— "清除所有样式"
架构:四层转换
Claude Code 的 UI 在到达你的屏幕之前要经过四个不同的层。
第 1 层:React 组件
第 2 层:Ink 渲染器
第 3 层:ANSI 转义码
第 4 层:终端显示
自己看看:React 层 vs 终端层
在两个视图之间切换,看看按钮是如何从代码转换为终端输出的。
React 层:带有 JSX 和 props 的组件代码
Ink 让这种转换变得不可见。你像为 Web 一样编写 React 组件,Ink 处理所有的 ANSI 代码生成。这种抽象使得构建终端 UI 感觉现代且易于上手。
测试你的理解
应用你学到的关于 Ink 架构的知识来调试和设计。
你在终端中看到红色加粗的文本。React 渲染了什么来创建这个?
一个组件应该居中但出现在左边缘。你会先调试哪一层?
Ink 需要在屏幕底部渲染一个按钮。它怎么知道"底部"在哪里?
你正在构建一个终端应用。为什么使用 Ink 而不是直接编写 ANSI 代码?
你学到了什么
Ink 弥合了现代 Web 开发和终端界面之间的差距 —— 给你 React 的力量和命令行工具的简单性。
你可以使用熟悉的 React 模式构建终端 UI
Ink 自动将 React 组件转换为 ANSI 转义码
当出现问题时,检查 React props → Ink 布局 → ANSI 代码 → 终端
既然你了解了 UI 的工作原理,让我们看看 Claude Code 如何让它快速响应。我们将探索缓存策略、流式响应以及保持流畅的聪明技巧。
巧妙技巧 —— 性能与功能
Claude Code 如何通过轻装打包和按需加载实现快速启动
性能挑战
但它拥有超过50 万行代码。如何做到的?它使用巧妙技巧,只在需要时加载需要的内容。
这就像旅行打包。你不会带整个衣柜 —— 你只带需要的物品,到了目的地再买其他东西。Claude Code 也是如此:启动时只加载必需品,然后懒加载其他所有内容。
并行预加载
尽早启动慢速操作并同时运行
无用代码消除
在构建时完全移除未使用的代码
懒加载
仅在首次需要时加载代码,延迟到使用时
这三个技巧协同工作,让 Claude Code 感觉瞬间启动。让我们看看每个技巧是如何工作的。
并行预加载:发射后不管
想象你在做早餐时准备咖啡和烤面包。你可以:
- 等咖啡机(5分钟),然后把面包放进烤面包机(2分钟) —— 总共 7 分钟
- 同时开始两者 —— 总共 5 分钟
第二个选项就是预加载:尽早启动慢速操作,这样当你需要它们时它们已经完成了。
Claude Code 在导入其余代码之前就启动读取配置文件等慢速操作。到应用完成加载时(约 135ms 后),这些操作已经在后台完成了。
这在每次 macOS 启动时节省了约65ms —— 这是总启动时间的 32%!
预加载在代码中的工作原理
这是来自 Claude Code 的 main.tsx 的实际代码,立即启动预加载:
// These side-effects must run before all other imports:
// 1. profileCheckpoint marks entry before heavy module evaluation begins
// 2. startMdmRawRead fires MDM subprocesses (plutil/reg query) so they run in
// parallel with the remaining ~135ms of imports below
// 3. startKeychainPrefetch fires both macOS keychain reads (OAuth + legacy API
// key) in parallel — isRemoteManagedSettingsEligible() otherwise reads them
// sequentially via sync spawn inside applySafeConfigEnvironmentVariables()
// (~65ms on every macOS startup)
import { profileCheckpoint, profileReport } from './utils/startupProfiler.js';
// eslint-disable-next-line custom-rules/no-top-level-side-effects
profileCheckpoint('main_tsx_entry');
import { startMdmRawRead } from './utils/settings/mdm/rawRead.js';
// eslint-disable-next-line custom-rules/no-top-level-side-effects
startMdmRawRead();
这些注释解释了正在发生的事情 —— 我们在导入其余代码之前就开始慢速操作...
我们需要读取 MDM(移动设备管理)设置和钥匙串凭证 —— 两者都很慢(总共约 65ms)...
导入启动分析器工具以跟踪性能...
标记这个时刻,以便我们可以测量启动需要多长时间...
导入读取 MDM 设置的函数...
现在就开始读取 MDM 设置 —— 这在后台运行,而其余代码加载...
注意到了 eslint-disable 注释吗?通常,在文件顶层运行代码是不被赞同的(这是一个"副作用")。但在这里,这是有意的 —— 我们希望这些操作立即开始,在其他任何东西之前。
无用代码消除:轻装打包
回到旅行的比喻:有些目的地需要冬装,有些需要泳装。你不会每次旅行都带两者 —— 你只带需要的,其他的留下。
Claude Code 使用功能开关来做到这一点。像"主动模式"或"语音模式"这样的功能对大多数用户来说完全被排除在外。
在构建时,Bun 检查功能开关。如果某个功能被禁用,该代码将从最终的打包文件中移除。它不仅仅在运行时被跳过 —— 它根本不会进入应用程序。
这意味着打包文件大小保持很小。需要特殊功能的用户可以启用它们,但其他人都获得更快、更轻的应用程序。
懒加载:到达时再买
最后一个技巧:延迟加载,直到你真正需要某些东西。这就像到达目的地时购买洗漱用品,而不是"以防万一"地打包它们。
Claude Code 对不需要立即使用的功能使用懒加载:
- 重型命令(如视频处理)仅在运行时加载
- UI 组件仅在显示时加载
- 语言模型仅在开始对话时加载
只有核心 UI 和必需功能加载 —— 约 200ms
该命令的代码按需加载 —— 第一次添加小延迟
后续运行是即时的,因为代码已经加载
并行预加载实际运行
看看 Claude Code 启动时会发生什么。多个操作同时运行:
关键见解:所有三个操作(MDM、钥匙串、模块加载)并行发生。如果它们按顺序运行,将需要 200ms + 65ms = 265ms。通过并行运行,总时间只有 200ms —— 最慢的操作胜出。
性能模式一览
这三种模式协同工作使 Claude Code 快速。每种模式解决不同的问题:
并行预加载
问题:某些操作很慢(65ms+)并阻塞启动
解决方案:尽早启动它们,与其他代码同时运行
影响:在 macOS 启动时节省约 65ms
无用代码消除
问题:加载未使用的代码浪费时间和带宽
解决方案:功能开关在构建时完全移除代码
影响:更小的打包文件,更快的下载
懒加载
问题:预先加载所有内容使启动变慢
解决方案:仅在首次使用时加载代码,然后缓存
影响:启动更快,后续加载接近即时
测试你的知识
让我们将你学到的知识应用到一些实际场景中。
你有两个操作:读取配置文件(10ms)和调用 API(200ms)。你应该并行还是顺序运行它们?
某个功能只有 1% 的用户使用。你应该懒加载它还是将其包含在主打包文件中?
Claude Code 使用功能开关为大多数用户排除"主动模式"代码。构建时该代码会发生什么?
你正在构建一个 CLI 工具。哪些操作应该在启动期间预加载?
我们学到了什么
性能不是魔法 —— 它是关于做出明智的权衡:
尽早启动慢速操作,以便在需要时完成
使用功能开关在构建时排除未使用的代码
延迟加载代码,直到真正需要它
在构建你自己的应用程序时,这些模式直接影响用户体验。启动时间影响第一印象。打包文件大小影响部署成本。理解这些技巧帮助你向 Claude 请求正确的优化:"对此路由使用懒加载",而不仅仅是"让它加载更快"。
接下来:我们将放大查看所有部分如何在大局架构中组合在一起。
宏观架构——大规模系统设计
所有组件如何协同工作,帮助你更好地驾驭 AI
拉远视角:城市地图
我们已经了解了各个部分——工具、命令、查询引擎、终端界面、性能优化技巧。现在让我们拉远视角,看看它们是如何组合在一起的。这就是 Claude Code 的地图,了解它有助于你更好地驾驭 AI、更快地调试,并在自己的项目中做出更明智的架构决策。
Claude Code 就像一个城市。它有行政区(如 commands/、tools/、services/ 等模块),有道路(组件之间的数据流),有服务机构(如 cost-tracker、context collection 等实用工具),还有一个中央广场(查询引擎),所有东西都在这里连接。了解布局有助于你导航,知道在需要什么时该去哪里。
自信地导航
在调试时知道该调查哪个"行政区"——工具用于操作,命令用于工作流,查询引擎用于流程问题
更好地驾驭 AI
当你让 Claude 重构代码时,你会知道哪些文件会改变,可能产生什么样的连锁反应
构建自己的工具
获得构建 AI 编程工具的模型——关注点分离、清晰的接口、模块化设计
城市布局:目录结构
让我们漫游 Claude Code 的各个行政区。每个文件夹都有特定的用途,知道什么文件放在哪里能帮助你快速找到所需内容。
这不仅仅是为了整洁——这是关注点分离。工具专注做好一件事。命令编排工具。服务处理外部连接。每个部分都有自己的工作,它们通过明确定义的接口进行通信。这使得代码库更易于理解、测试和扩展。
建筑材料:技术栈
每个城市都由建筑材料建造——混凝土、钢铁、玻璃。Claude Code 使用因其优势而选择的特定技术构建。让我们将技术栈翻译成通俗易懂的语言。
| 类别 | 技术 |
|---|---|
| 运行时 | Bun |
| 语言 | TypeScript (严格模式) |
| 终端 UI | React + Ink |
| CLI 解析 | Commander.js |
| 模式验证 | Zod v4 |
| 代码搜索 | ripgrep |
| 协议 | MCP SDK, LSP |
| API | Anthropic SDK |
| 遥测 | OpenTelemetry + gRPC |
| 功能开关 | GrowthBook |
| 认证 | OAuth 2.0, JWT, Keychain |
Bun:闪电般快速的 JavaScript 运行时——就像 Node.js 但快 3-4 倍。因启动速度而被选中...
TypeScript:具有类型安全的 JavaScript——在代码运行前捕获错误。严格模式意味着不能偷懒...
React + Ink:为终端改编的 Web 框架。React 构建 UI;Ink 将它们渲染为文本而不是像素...
Commander.js:用于解析命令行参数的库——将输入的命令转换为结构化数据...
Zod:模式验证器——确保数据符合预期的形状。就像在门口检查身份证的保安...
ripgrep:极快的代码搜索工具——在毫秒内搜索千兆字节。Grep 工具的引擎...
MCP SDK + LSP:连接外部工具的协议。MCP 用于 AI 服务器,LSP 用于编辑器集成...
Anthropic SDK:与 Claude API 对话的官方库——处理认证、请求、流式传输...
OpenTelemetry:跟踪性能的标准——监控 API 调用、延迟、跨系统的错误...
GrowthBook:功能开关系统——逐步推出功能,对新功能进行 A/B 测试...
OAuth + JWT:安全标准。OAuth 用于通过 GitHub/Google 登录。JWT 用于会话令牌...
每种技术的选择都有原因:Bun 为了启动速度,React 为了组件复用,ripgrep 为了搜索性能,TypeScript 为了安全。在构建自己的工具时,要考虑你需要的优势——而不是仅仅追求流行。
完整城市地图:架构概览
这是完整的系统——每个主要组件及其连接方式。点击或悬停在任何组件上以了解它的作用。
你(用户输入)
核心处理
外部服务
输出和显示
支持系统
城市的设计模式
伟大的城市都有设计模式——网格布局、分区法律、交通系统。Claude Code 也有。这些是使其快速、可扩展和可维护的工程模式。
并行预加载
启动时间通过同时加载多个内容来优化——设置、钥匙串、API 连接——在重型模块加载之前。就像在开始烹饪之前准备好所有食材。
延迟加载
重型模块(分析、遥测)仅在需要时加载。就像直到真的变冷才 unpack 冬装。保持快速启动。
智能体群
子智能体并行处理任务的不同部分。协调器处理团队。就像一个有不同专家同时工作的施工队。
技能系统
在 skills/ 中定义的可重用工作流可以由 Claude 执行或由用户自定义。就像任何人都可以遵循或改编的食谱卡。
插件架构
内置和第三方插件通过 plugins/ 子系统加载。无需修改核心代码即可扩展。就像带有应用商店的手机。
这些不仅仅是聪明的技巧——它们是构建 AI 工具的可重用模式。延迟加载保持快速。并行处理节省时间。插件架构使事物可扩展。在你自己的项目中使用这些模式。
三大支柱:关键要点
我们涵盖的所有内容归结为三个基本思想。这些概念将帮助你更好地驾驭 AI、更快地调试、构建更智能的工具。
工具 = 操作
工具是 Claude 能够做的事情。读取文件、编辑代码、运行命令、搜索、git 操作。每个工具都是一个专注的操作,有明确的目的。当你让 Claude 做某事时,它会为工作选择合适的工具。
命令 = 快捷方式
命令是编排多个工具的预构建工作流。/commit 运行 git status、git diff、git add、git commit。/review 用特定检查审查代码。它们是为了方便而打包的常见模式。
查询引擎 = 中心枢纽
查询引擎是所有东西连接的地方。它管理你和 Claude 之间的对话,执行工具调用,处理权限,跟踪成本,并重复直到任务完成。它是城市的中央广场。
测试你的知识:架构决策
这些场景测试你应用所学内容的能力。不需要死记硬背——只需要基于对架构的理解的实用决策。
你想添加一个新的斜杠命令 /deploy 来将应用部署到生产环境。你会把它放在哪个目录中,它需要什么才能工作?
Claude 似乎"困惑"了,不断尝试不同的方法但没有成功——"我尝试了 X,然后 Y,然后 Z..."从高层次来看,查询引擎循环中可能发生了什么?
你正在构建一个类似的 CLI 工具,并想要一个交互式终端界面。为什么你可能会选择 Ink (React + Ink) 而不是像 Commander.js 这样的传统 CLI 库?
用户报告"语音输入不起作用"——当他们说话时,什么也没有发生。你会首先调查哪个子系统,为什么?
你希望 Claude 能够在回答问题时搜索你公司的内部 API 文档。你将如何集成这个——作为工具、命令还是其他什么?
你现在可以做什么:实际应用
你已经学习了架构。以下是在 Claude Code 和其他 AI 工具的现实情况中使用这些知识的方法。
不要说"看看我的代码",而要说"使用 Grep 搜索数据库连接函数"——Claude 确切地知道使用哪个工具以及如何应用它。
当出现问题时,问:"这是工具问题(错误的操作)、命令问题(工作流问题)还是查询引擎问题(循环没有进展)?"在调查之前缩小范围。
在让 Claude 重构之前,考虑:"这会触及哪些文件?将使用哪些工具?什么可能中断?"了解架构帮助你预见后果。
使用你学到的模式:关注点分离(工具做一件事)、清晰的接口(明确定义的契约)、延迟加载(只加载你需要的东西)、插件架构(使其可扩展)。
正确使用技术词汇:"工具"用于操作,"命令"用于工作流,"查询引擎"用于中央循环。精确的语言产生精确的结果。
当你改变系统的一部分时,它会影响其他部分。在 Claude Code 中,修改工具会影响使用它的每个命令。更改查询引擎会影响所有工具执行。理解这些连锁反应帮助你做出更明智的决定并避免破坏事物。
恭喜!你完成了课程
你已经完整地了解了 Claude Code 的架构——从城市布局到单独的砖块。让我们回顾一下你学到了什么。
了解到工具是操作(Claude 能够做什么),命令是快捷方式(预构建的工作流)。发现了权限模式如何保护你。
探索了编排一切的中央循环——你的请求、Claude 的工具调用、权限和响应都流经这里。
看到了 React 如何在终端中运行,将组件渲染为文本而不是像素,随着查询引擎的处理实时更新。
学习了优化策略——并行预加载、延迟加载、缓存和其他保持 Claude Code 快速的聪明技巧。
拉远视角以了解所有部分如何组合在一起——完整的架构、设计模式以及如何应用这些知识。
你现在有能力:
- 更好地驾驭 AI——表达符合可用工具和工作流的请求
- 更快地调试——知道当出现问题时该调查哪个"行政区"
- 做出架构决策——理解权衡和连锁反应
- 构建更智能的工具——应用经过验证的模式,如关注点分离和延迟加载
- 精确沟通——在与 AI 合作时正确使用技术词汇
这门课程给了你地图。真正的学习发生在你使用 Claude Code 并注意到:"哦,这是查询引擎循环在运作!"或者"我应该使用 Grep 工具,而不是让 Claude 读取每个文件。"架构不是抽象的——它是每天帮助你实用知识。继续探索,继续提问,继续构建。
感谢你完成这门课程!
去用 AI 构建令人惊叹的东西吧。你现在拥有有效驾驭它的知识。