14-命令架构与注册机制

14. 命令架构与注册机制所属分组命令系统概述Claude Code 的斜杠命令slash command系统是 REPL 交互体验的核心骨架。用户在终端中输入/clear、/help、/commit等指令时背后是一条层次清晰、可扩展、可懒加载的命令流水线从内置命令数组到插件命令、Skill 目录命令、Bundled Skill、MCP 命令再到动态发现的 workflow 命令最终通过统一的getCommands(cwd)入口对外暴露。整条流水线的设计目标可以概括为三点第一启动快——绝大多数命令实现都被设计成懒加载index.ts只暴露极小的元数据对象第二可扩展——通过loadedFrom、source、availability、isEnabled等字段支持插件、MCP、feature flag、auth 状态等多维度裁剪第三安全可控——通过REMOTE_SAFE_COMMANDS、BRIDGE_SAFE_COMMANDS两道白名单将命令暴露面收敛到远程/移动端场景下安全的子集。本文从commands.ts、types/command.ts以及代表性命令目录commands/clear/、commands/help/入手剖析命令的注册流程、类型定义、过滤策略与目录组织模式。源码位置[commands.ts](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/commands.ts)[types/command.ts](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/types/command.ts)[commands/clear/index.ts](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/commands/clear/index.ts)[commands/help/index.ts](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/commands/help/index.ts)[commands/clear/clear.ts](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/commands/clear/clear.ts)[commands/help/help.tsx](file:///e:/2026plan/AI_Lab/claude-code-sourcemap-main/restored-src/src/commands/help/help.tsx)核心实现分析1. Command 类型定义三种命令形态types/command.ts把所有命令统一抽象为Command CommandBase (PromptCommand | LocalCommand | LocalJSXCommand)即基础信息 三选一的执行体。CommandBase携带所有命令共有的元数据exporttypeCommandBase{availability?:CommandAvailability[]description:stringhasUserSpecifiedDescription?:booleanisEnabled?:()booleanisHidden?:booleanname:stringaliases?:string[]argumentHint?:stringwhenToUse?:stringloadedFrom?:commands_DEPRECATED|skills|plugin|managed|bundled|mcpkind?:workflowimmediate?:booleanisSensitive?:booleanuserFacingName?:()string}三种执行体对应三种命令形态PromptCommandtype: prompt命令本质是一段会被注入到模型上下文中的 prompt。它通过getPromptForCommand(args, context)返回ContentBlockParam[]常用于 skill如/commit会展开成帮我生成 commit message 并执行 git的指令。它还携带allowedTools、model、hooks、context: inline | fork、paths等字段决定 prompt 如何被模型消费。LocalCommandtype: local纯本地副作用命令例如/clear清空对话、/cost查看花费。它通过load()懒加载一个LocalCommandModule其call(args, context)返回{ type: text | compact | skip }。LocalJSXCommandtype: local-jsx需要渲染 Ink UI 的命令例如/help、/config。它的call(onDone, context, args)返回React.ReactNode由 REPL 渲染。local-jsx命令天然不能在非交互模式下运行也默认被 bridge 屏蔽。getCommandName与isCommandEnabled是两个工具函数前者优先取userFacingName()否则回落到name用于插件前缀剥离等场景后者把isEnabled缺省视为true。2. 命令注册commands.ts的中央清单commands.ts顶部一口气import了几乎所有内置命令模块并对一些依赖 feature flag 的命令使用require() 条件判断包裹constultraplanfeature(ULTRAPLAN)?require(./commands/ultraplan.js).default:nullconstvoiceCommandfeature(VOICE_MODE)?require(./commands/voice/index.js).default:null这种feature flag 守卫的 require配合 Bun 的 dead code elimination让外部发布版本能直接把内部功能从产物里抹掉而无需在运行时做软开关。随后是一个被memoize包裹的COMMANDS()函数返回内置命令数组。注意它不是模块级常量而是函数——注释明确说明“underlying functions read from config, which can’t be read at module initialization time”。这是为了避免在模块加载阶段就读取配置导致的状态泄漏constCOMMANDSmemoize(():Command[][addDir,advisor,agents,branch,btw,chrome,clear,/* ... */vim,...(webCmd?[webCmd]:[]),...(proactive?[proactive]:[]),...(process.env.USER_TYPEant!process.env.IS_DEMO?INTERNAL_ONLY_COMMANDS:[]),])INTERNAL_ONLY_COMMANDS是一个独立数组列出仅在 Anthropic 内部 (USER_TYPE ant) 构建中可见的命令commit、commitPushPr、bughunter、version、ultraplan、antTrace等普通用户构建会通过process.env.IS_DEMO等条件过滤掉。3. 多源命令汇聚loadAllCommands与getCommands内置命令只是冰山一角。getSkills(cwd)异步并行加载四类Skill 形态命令getSkillDirCommands(cwd)从.claude/skills/等目录扫描出的命令getPluginSkills()从已启用插件中提取的 skill 命令getBundledSkills()随包内置的 skillskills/bundled/如batch、debug、loop、verifygetBuiltinPluginSkillCommands()内置插件提供的 skill 命令。任何一个加载失败都被catch兜底为[]避免单个 skill 故障拖垮整个命令系统。loadAllCommands(cwd)用Promise.all同时拉取 skills、getPluginCommands()、getWorkflowCommands(cwd)再按固定顺序拼接bundled → builtinPlugin → skillDir → workflow → pluginCommands → pluginSkills → COMMANDS()。这个顺序决定了 typeahead 中命令的展示优先级——内置命令总在最后方便用户优先看到自定义 skill。最终的对外入口getCommands(cwd)在loadAllCommands结果之上做三件事调用getDynamicSkills()取文件操作过程中动态发现的 skill用meetsAvailabilityRequirementisCommandEnabled双重过滤对动态 skill 做去重并插入到内置命令之前、其他命令之后的位置。注释特别强调meetsAvailabilityRequirement不做 memoize因为 auth 状态可能在会话中变化比如用户刚执行了/login必须每次调用都重新评估。4.filterCommandsForRemoteMode远程模式白名单--remote模式下REPL 渲染前会调用filterCommandsForRemoteMode(commands)只保留REMOTE_SAFE_COMMANDS集合中的命令exportconstREMOTE_SAFE_COMMANDS:SetCommandnewSet([session,exit,clear,help,theme,color,vim,cost,usage,copy,btw,feedback,plan,keybindings,statusline,stickers,mobile,])注释点明这套白名单的判定标准“only affect local TUI state and don’t depend on local filesystem, git, shell, IDE, MCP”。它在两处被使用main.tsx在 REPL 渲染前预过滤避免和 CCR 初始化消息竞态以及 REPL 的handleRemoteInit在 CCR 过滤后保留本地命令。与之并列的还有BRIDGE_SAFE_COMMANDS与isBridgeSafeCommand用于从移动端/Web 客户端通过 Remote Control bridge 进来的命令。isBridgeSafeCommand的策略是local-jsx一律屏蔽会弹 Ink UIprompt一律允许本质是文本展开local命令必须在BRIDGE_SAFE_COMMANDS显式 opt-in。注释里提到 PR #19134 曾因/model从 iOS 触发本地 Ink picker 而 blanket-block 所有斜杠命令现在改为显式 allowlist。5.index.ts模式元数据与实现分离每个命令目录都遵循同一套index.ts暴露元数据、同名.ts/.tsx暴露实现的模式。以clear为例// commands/clear/index.tsconstclear{type:local,name:clear,description:Clear conversation history and free up context,aliases:[reset,new],supportsNonInteractive:false,load:()import(./clear.js),}satisfies Commandload返回一个动态import()只有用户真正输入/clear时才会加载clear.ts。clear.ts本身只是call函数的薄封装// commands/clear/clear.tsexportconstcall:LocalCommandCallasync(_,context){awaitclearConversation(context)return{type:text,value:}}help命令则是local-jsx形态的典型// commands/help/index.tsconsthelp{type:local-jsx,name:help,description:Show help and available commands,load:()import(./help.js),}satisfies Command// commands/help/help.tsx export const call: LocalJSXCommandCall async (onDone, { options: { commands } }) { return HelpV2 commands{commands} onClose{onDone} / }这种index.ts极简 实现懒加载的模式是整个commands/目录的一致约定让启动时只需评估几百个轻量元数据对象而无需把所有命令的依赖git、Ink 组件、LSP 客户端等全部拉进启动图。6. 辅助工具findCommand/getCommand/formatDescriptionWithSourcecommands.ts还提供了一系列查找与展示工具findCommand(name, commands)按name、getCommandName()、aliases三种方式匹配getCommand在找不到时抛出ReferenceError并把所有可用命令名含 alias拼接进错误信息方便用户排查formatDescriptionWithSource(cmd)给 prompt 类型命令的描述加上来源标注plugin 名、bundled、workflow等用于 typeahead 和帮助屏但模型侧仍直接使用cmd.description以避免污染语义。clearCommandsCache与clearCommandMemoizationCaches提供缓存失效能力前者连 skill 缓存一起清后者只清loadAllCommands、getSkillToolCommands、getSlashCommandToolSkills三层 memoize用于动态 skill 增量添加时刷新命令列表而不重建整个 skill 索引。关键设计要点懒加载优先index.ts只暴露satisfies Command的元数据对象实现通过load: () import(./xxx.js)在调用时才加载把启动开销压到最低。配置延后求值COMMANDS被定义为memoize的函数而非顶层常量因为部分命令的isEnabled依赖运行时配置只有getCommands真正被调用时才触发求值。多维度过滤availabilityauth 静态属性isEnabledfeature flag/环境动态属性REMOTE_SAFE_COMMANDS/BRIDGE_SAFE_COMMANDS场景白名单三层过滤分别承担谁能用“现在能不能用”在哪个通道能用三个正交维度。dead code elimination 友好内部命令通过feature(...)守卫的require写法让 Bun 在打包外部发行版时直接删除整段代码比运行时 if 判断更彻底。失败隔离getSkills中每一类 skill 加载都单独catch避免一个损坏的插件或 skill 目录让整个getCommands抛错。与其他模块的关系skills/loadSkillsDir.ts、bundledSkills.ts、builtinPlugins.ts提供命令的skill 形态来源被getSkills聚合。utils/plugins/loadPluginCommands.ts插件命令与插件 skill 的加载入口对应getPluginCommands/getPluginSkills。utils/auth.ts、utils/model/providers.tsmeetsAvailabilityRequirement依赖它们判断claude-ai/console/3P 服务身份。screens/REPL.tsx与main.tsxgetCommands的主要消费者REPL 渲染、typeahead、命令分发都基于它返回的列表。tools/SkillToolgetSkillToolCommands与getSlashCommandToolSkills为 SkillTool 提供模型可调用的 prompt 命令集合把命令系统和工具系统打通。services/mcp/MCP 加载的命令通过getMcpSkillCommands单独过滤绕开getCommands的主清单由调用方按需注入。小结Claude Code 的命令系统把丰富和快这对矛盾拆到了三个层次解决类型层用Command联合类型把 prompt/local/local-jsx 三种执行体统一到一个接口下注册层用COMMANDS()loadAllCommands把内置、插件、skill、workflow 等多源命令汇聚到一条流水线过滤层用availability/isEnabled/REMOTE_SAFE_COMMANDS三道闸门按场景裁剪。配合index.ts懒加载约定与feature()dead code elimination整个系统在拥有上百条命令的同时仍能保持亚秒级启动是后续每一条具体命令commit、review、config、plan 等能被简洁实现的基础。