模块: commands | Claude Code 源码分析

本章总览

src/commands/ 是 Claude Code 的「斜杠命令实现层」：每个 /clear、/model、/mcp 等用户输入对应一个 Command 对象，由根目录 commands.ts 聚合注册，经 processSlashCommand 分派到 local / local-jsx / prompt 三种执行路径（213 个文件，约 26692 行）。务必区分：commands.ts（注册表与 getCommands）≠ commands/ 目录（各命令实现）。

总览图

渲染图表中…

学完本章你应该能

建立 command-registry → model / mcp / compact-memory 的阅读顺序
理解 Command 三种 type 与 lazy load 模式
能在源码树中从本页跳转到子章节与高亮文件
区分内置命令、plugin/skill 命令与 MCP prompt 命令的来源

建议学习步骤

浏览下方子章节导航表，选择入口主题
点击 SourceTree 中的 commands.ts 或 commands/ 子目录跳转到对应讲解
建议顺序：command-registry → model-command → mcp-commands → compact-memory-commands

模块在架构中的位置

commands 是 src/ 下的一级目录，共 213 个文件、26,692 行。一句话概括：87 个 /command：/model、/compact、/mcp、/memory、/doctor 等，用户可直接操控 Agent 行为。

概览

指标	数值
行数	26,692
文件	213

子章节导航

子章节	主题	核心路径
command-registry	commands.ts 注册、getCommands、分派	`commands.ts`、`types/command.ts`
model-command	/model 模型选择与校验	`commands/model/`
mcp-commands	/mcp 服务器管理	`commands/mcp/`
compact-memory-commands	/compact /memory 上下文与记忆	`commands/compact/`、`commands/memory/`

Command 三种类型

Claude Code 斜杠命令在 types/command.ts 中分为三类：

type	执行形态	典型命令	load 返回
`local`	同步函数，直接改 messages 或返回 compact 结果	/compact、/clear	`{ call(args, context) }`
`local-jsx`	Ink React 组件，弹窗或 picker	/model、/mcp、/memory	`{ call(onDone, context, args) }`
`prompt`	展开为 prompt 块发给模型（skills）	/commit（skill）、plugin 命令	`getPromptForCommand`

lazy load：index.ts 只导出元数据（name、description、type），load: () => import('./xxx.js') 推迟重模块（如 insights 113KB）直到用户真正输入命令。REPL typeahead 调用 getCommands(cwd) 时只读 description，不触发 load。

immediate 命令（如 /mcp、/model 在部分配置下）绕过输入队列，在 stop point 之外立即执行——见 shouldInferenceConfigCommandBeImmediate。

命令来源与优先级

loadAllCommands(cwd) 合并顺序（后者覆盖同名前者需 dedupe）：

bundledSkills → builtinPluginSkills → skillDirCommands
  → workflowCommands → pluginCommands → pluginSkills
  → COMMANDS() 内置数组

getCommands 在此基础上过滤 meetsAvailabilityRequirement（claude-ai / console）与 isCommandEnabled()（GrowthBook、env）。动态 skill（文件操作中发现）插入在内置命令之前。

INTERNAL_ONLY_COMMANDS 仅 USER_TYPE === 'ant' 且非 demo 时加入 COMMANDS，外部构建通过 dead code elimination 剥离。REMOTE_SAFE_COMMANDS 与 BRIDGE_SAFE_COMMANDS 限制 remote / mobile bridge 可执行的命令子集。

目录树展示 src/commands/ 下全部子目录（clear、compact、config、doctor 等）。根目录 commands.ts 不在树中但 command-registry 子章节通过 highlightFiles 与高亮锚点跳转。

与其他模块的边界

协作方	关系
processSlashCommand.tsx	解析 `/name args`，findCommand，按 type 分派
skills/loadSkillsDir.js	从 ~/.claude/skills 加载 prompt 命令
utils/plugins/loadPluginCommands.js	插件 manifest 中的 commands
services/compact/*	/compact 命令调用 compactConversation
services/mcp/*	/mcp 与 MCPSettings 组件、ConnectionManager
components/ModelPicker	/model 菜单 UI
state/AppState	mainLoopModel、fastMode、mcp.clients

调试「命令找不到」：先 getCommands(cwd) 列表是否含该名，再查 alias、availability、isEnabled；调试「命令无反应」：查 processSlashCommand 的 type 分支与 load() 是否抛错。

本章小结与延伸

commands 模块 = 用户斜杠输入的产品化入口。先懂 commands.ts 如何组装命令池，再按主题读 model / mcp / compact / memory 四条高频路径。 继续学习：

command-registry