Claude Code 深度拆解：CLI 交互模块 2 — 斜杠命令系统：从 100+ 注册源到三岔分发

1. 为什么 CLI 里必须有一套斜杠命令系统终端里没有按钮、没有菜单、没有右键上下文用户敲下的每一个字符默认都会被当成发给模型的 prompt。那问题就来了用户想清屏、想切换模型、想查看当前会话花了多少钱这些操作怎么和我要发一段包含 /clear 字样的普通对话区分开答案就是斜杠前缀。/开头的输入走本地逻辑不调模型!开头的输入直接进子 shell剩下的才是普通 prompt。这套约定不是 Claude Code 发明的Vim 的:命令模式、Emacs 的M-x、bash 的 alias 都是同一个问题空间里的解法——在纯文本交互里用语法约定划出控制指令和内容的分界线。Claude Code 把这个范式搬进了 Agent 的 REPL 循环并且做到了 100 个斜杠命令零初始化成本敲/commit就能用不需要任何预热代码。支撑这件事的是三个东西——一个多路合一的命令注册表、一套编译时裁剪的 Feature Gate、一个独立于渲染循环的优先级消息队列。这篇文章聚焦注册与分发链路100 命令从哪几路汇入注册表、怎么经过两道过滤、最后怎么被三岔分发路由到执行层。我会给出可复制的命令注册表配置骨架和消息队列接入示例并附上验证分发路径的调试动作帮你在自己的 CLI 工具里复现同类命令系统。如果你正在做 Agent 工具、CLI 脚手架或者任何需要文本输入分流的交互层这套结构可以直接借鉴。下面从命令接口开始拆。2. TaoToken 前置给命令系统接一个可调用的模型后端命令注册表本身不依赖任何模型服务但 prompt 型命令比如/commit、/review最终要把生成的 prompt 文本送进 query 循环这一步需要一个能调用的 API 端点。我这边调试 Claude Code 类工具时用的是 TaoToken 做后端接入它兼容 Anthropic 风格的接口配置成本低适合在本地复现命令分发链路时快速验证。你需要先拿到一个 API Key。打开 https://taotoken.net/api-keys 创建密钥注意这个页面是控制台里的密钥管理入口创建后复制保存后面配置环境变量要用。拿到 Key 之后把接入地址和密钥写进环境变量。TaoToken 的 API 根地址是https://taotoken.net/api注意这个地址不带任何查询参数直接作为 base URL 使用export TAOTOKEN_API_KEYsk-你的密钥 export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY$TAOTOKEN_API_KEY如果你用的是 Claude Code 官方 CLI它默认读ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量所以上面这样设置之后CLI 发出的请求会走 TaoToken 的端点。这一步的意义在于命令系统里 prompt 型命令的执行结果你能在本地完整看到从命令名解析到模型返回的全链路方便对照调试。想先确认模型侧是否通可以直接在模型对话页发一条测试消息https://taotoken.net/models 。如果那边能正常返回说明 Key 和端点都没问题再回来调命令系统就不会把网络问题和分发逻辑问题混在一起排查。对于长期要跑编码任务或者 Agent 循环的场景可以考虑 Coding Plan它更适合高频调用https://taotoken.net/coding-plan 。接入文档在 https://taotoken.net/doc 里面有各语言 SDK 的调用示例配置细节可以对照着看。3. 命令注册表配置骨架七路来源与合并策略3.1 Command 接口的三种变体每个命令本质上是一张身份证字段决定了它的行为和归属。先定义接口// types/command.ts export type CommandType prompt | local | local-jsx export interface Command { type: CommandType name: string description: string argumentHint?: string aliases?: string[] availability?: AuthType[] isEnabled?: (config: Config) boolean source: builtin | plugin | skill | bundled | workflow getPromptForCommand?: (args: string[], ctx: Context) Promisestring render?: (props: RenderProps) JSX.Element }三种类型的区别很直接prompt型命令会生成一段 prompt 文本注入消息流最终调 APIlocal型命令在终端直接渲染 JSX 输出不调 APIlocal-jsx型命令渲染整个 React 组件做全屏交互 UI。判断走哪条路看command.type就够了。3.2 七路来源的合并骨架命令池不是单一来源而是七路汇流。按谁来定义、谁可以改分成三层产品层团队控制、生态层第三方扩展、用户层终端用户自定义。合并函数长这样// commands/registry.ts import { memoize } from ./utils export const loadAllCommands memoize(async (cwd: string): PromiseCommand[] { const [ { skillDirCommands, pluginSkills, bundledSkills, builtinPluginSkills }, pluginCommands, workflowCommands, ] await Promise.all([ getSkills(cwd), // 四合一skillDir pluginSkills bundled builtinPlugin getPluginCommands(), // 插件注册的完整命令 getWorkflowCommands(cwd), // 工作流脚本生成的命令 ]) return [ ...bundledSkills, // 优先级 1打包进 binary 的内置技能 ...builtinPluginSkills, // 优先级 2官方预装插件技能 ...skillDirCommands, // 优先级 3用户 .claude/skills/ 目录 ...workflowCommands, // 优先级 4用户工作流命令 ...pluginCommands, // 优先级 5插件命令 ...pluginSkills, // 优先级 6插件技能 ...COMMANDS(), // 优先级 7最低内置命令 ] })注意COMMANDS()放在数组最后意味着内置命令优先级最低——用户在.claude/skills/下放一个commit.md就能覆盖内置的/commit。这是扩展优于硬编码的开放封闭原则在命令系统里的直接落地。memoize按cwd缓存因为不同工作目录有各自的 skills 目录换目录要重新扫描。但缓存的是目录里有什么文件这个物理事实不缓存权限判断。3.3 两道过滤注册者不管权限调用者只看结果合并只解决命令存在不解决谁能看到、当前能不能用。过滤放在每次getCommands()调用时执行而不是注册阶段// commands/registry.ts export async function getCommands(cwd: string): PromiseCommand[] { const allCommands await loadAllCommands(cwd) return allCommands.filter( (cmd) meetsAvailabilityRequirement(cmd) // 商业策略订阅类型隔离 isCommandEnabled(cmd) // 工程策略Feature Gate 运行时检查 ) }两道过滤都不缓存。因为用户可能在会话中途/login订阅状态从 Console 跳到 claude.ai也可能通过/mcp开关改变了 Feature Gate 的结果。如果缓存了过滤结果用户换了登录方式后看到的命令列表还是旧的就会出现我已经登录了为什么还看不到某个命令这类 bug。3.4 懒加载重实现不进启动路径不是所有命令都轻量。像/insights这种实现文件有 3200 行、113KB如果在 REPL 启动时加载会拖慢初始化。解法是动态import()// commands/registry.ts const usageReport: Command { type: prompt, name: insights, description: Generate a report analyzing your sessions, async getPromptForCommand(args, context) { const real (await import(./commands/insights.js)).default if (real.type ! prompt) throw new Error(unreachable) return real.getPromptForCommand(args, context) }, }注册表里存的是指针而非实现。每个命令的注册对象只有几百字节name description alias真正的逻辑躲在getPromptForCommand里的import()后面。用户第一次敲/insights时才触发动态加载在此之前这 113KB 根本不进内存。注册表本身永远不会成为启动性能瓶颈。4. 三岔分发与消息队列接入示例4.1 processUserInput 的三岔路口入口函数把用户输入分成三类每条路径返回同一个结构{ messages, shouldQuery }// utils/processUserInput.ts export async function processUserInput({ input, mode, ...rest }: InputParams) { if (isBashCommand(input)) { return processBashCommand(input, rest) // shouldQuery false } const slashMatch parseSlashCommand(input) if (slashMatch) { return processSlashCommand(slashMatch, rest) // shouldQuery 取决于 command.type } return processTextPrompt(input, rest) // shouldQuery true }shouldQuery是整条链路的唯一控制信号。bash 固定false普通文本固定true斜杠命令由command.type决定——prompt型返回true模型介入local型返回false终端直接渲染。上游 REPL 主循环不需要知道下面跑的是子 shell、命令注册表还是模型 API它只看shouldQuery。4.2 斜杠命令的解析与查找parseSlashCommand用正则提取命令名和参数findCommand在合并后的命令池里按名匹配// utils/processUserInput/processSlashCommand.ts const SLASH_PATTERN /^\/([a-zA-Z0-9_-])\s*(.*)$/s export function parseSlashCommand(input: string) { const match input.match(SLASH_PATTERN) if (!match) return null return { commandName: match[1], args: match[2].trim() } } export async function findCommand(name: string, cwd: string): PromiseCommand | undefined { const commands await getCommands(cwd) return commands.find( (cmd) cmd.name name || cmd.aliases?.includes(name) ) }注意findCommand里调的是getCommands而不是loadAllCommands——过滤后的结果才是用户实际能用的命令集。4.3 消息队列接入示例REPL 的消息源不只用户输入还有远程控制消息、任务通知、孤儿权限恢复。这些消息可能在任何时候到达甚至在 query 循环进行中。用模块级队列独立于 React 渲染循环// utils/messageQueueManager.ts type Priority now | next | later interface QueuedCommand { prompt: string priority?: Priority uuid: string } const PRIORITY_ORDER: RecordPriority, number { now: 0, next: 1, later: 2, } const commandQueue: QueuedCommand[] [] let snapshot: readonly QueuedCommand[] Object.freeze([]) const queueChanged createSignal() export function enqueue(command: QueuedCommand): void { commandQueue.push(command) notifySubscribers() } export function dequeue( filter?: (cmd: QueuedCommand) boolean ): QueuedCommand | undefined { let bestIdx -1 let bestPriority Infinity for (let i 0; i commandQueue.length; i) { const cmd commandQueue[i]! if (filter !filter(cmd)) continue const priority PRIORITY_ORDER[cmd.priority ?? next] if (priority bestPriority) { bestIdx i bestPriority priority } } if (bestIdx -1) return undefined const [dequeued] commandQueue.splice(bestIdx, 1) notifySubscribers() return dequeued }dequeue不是简单的shift()——它遍历整个队列找最高优先级的命令。这意味着后来先到如果后来的是now优先级而先来的是later后来的先执行。React 组件通过useSyncExternalStore订阅队列非 React 代码比如流式打印循环直接调getCommandQueue()读取。两种方式共享同一个模块级队列不需要任何桥接代码。5. 验证分发路径调试动作与成功结果5.1 打印命令池确认七路合并结果在 REPL 里加一个临时调试命令或者直接在启动脚本里调用// debug/list-commands.ts import { getCommands } from ../commands/registry const commands await getCommands(process.cwd()) console.table( commands.map((c) ({ name: c.name, type: c.type, source: c.source, aliases: c.aliases?.join(,) ?? , })) ) console.log(total: ${commands.length})跑起来之后你会看到一张表source列能直接告诉你每个命令来自哪一路。如果某个插件命令没出现先检查getPluginCommands()是否返回了它再看meetsAvailabilityRequirement有没有把它过滤掉。5.2 追踪 shouldQuery 的取值在processUserInput的三个分支各打一条日志export async function processUserInput({ input, ...rest }: InputParams) { if (isBashCommand(input)) { const result await processBashCommand(input, rest) console.log([dispatch] bash, { input, shouldQuery: result.shouldQuery }) return result } const slashMatch parseSlashCommand(input) if (slashMatch) { const result await processSlashCommand(slashMatch, rest) console.log([dispatch] slash, { name: slashMatch.commandName, shouldQuery: result.shouldQuery, }) return result } const result await processTextPrompt(input, rest) console.log([dispatch] text, { shouldQuery: result.shouldQuery }) return result }分别敲!ls、/status、/commit fix bug、hello四条输入观察日志!ls→[dispatch] bash { shouldQuery: false }/status→[dispatch] slash { name: status, shouldQuery: false }local 型/commit fix bug→[dispatch] slash { name: commit, shouldQuery: true }prompt 型hello→[dispatch] text { shouldQuery: true }四条日志覆盖了三种分叉和两种 shouldQuery 取值说明分发路径正确。5.3 验证消息队列的优先级往队列里塞三条不同优先级的消息然后连续 dequeueimport { enqueue, dequeue } from ../utils/messageQueueManager enqueue({ prompt: later-task, priority: later, uuid: 1 }) enqueue({ prompt: now-task, priority: now, uuid: 2 }) enqueue({ prompt: next-task, priority: next, uuid: 3 }) console.log(dequeue()?.prompt) // now-task console.log(dequeue()?.prompt) // next-task console.log(dequeue()?.prompt) // later-task如果输出顺序是now-task → next-task → later-task说明优先级排序生效。如果输出的是入队顺序检查PRIORITY_ORDER的映射有没有写反。5.4 成功结果长什么样完整跑通之后一条/commit fix bug的走线应该是用户敲入 /commit fix bug ① processUserInput() → 识别为斜杠命令 ② parseSlashCommand() → { commandName: commit, args: fix bug } ③ findCommand(commit) → 在过滤后的命令池里命中 ④ command.type prompt → 走 prompt 型分支 ⑤ getPromptForCommand() → 生成 prompt 文本 ⑥ createUserMessage() → 包装成标准 user message ⑦ shouldQuery true → 进入 query 循环 模型回复 → notifyCommandLifecycle(uuid, completed)每一步都能在日志里对上就说明注册、过滤、分发、执行四段链路都通了。6. 常见错误排查6.1 命令敲了没反应也不报错最常见的原因是命令被meetsAvailabilityRequirement过滤掉了。比如某些命令只对特定订阅类型开放当前登录方式不满足条件时findCommand返回undefined分发层直接走兜底逻辑用户看到的就是没反应。排查方法在findCommand里加日志打印getCommands返回的完整命令名列表看目标命令在不在里面。如果不在再单独调loadAllCommands看它在不在合并池里——在合并池但不在过滤结果里就是权限问题两边都不在就是注册环节没接上。6.2 用户自定义命令覆盖不了内置命令检查loadAllCommands的 spread 顺序。COMMANDS()必须在数组最后用户来源skillDirCommands、workflowCommands必须在它前面。如果顺序写反了内置命令会覆盖用户命令表现为我明明放了 commit.md 但敲 /commit 还是走内置逻辑。6.3 会话中途登录后命令列表没更新这是过滤结果被缓存导致的。getCommands里的两道过滤必须每次重新跑不能把结果 memoize。loadAllCommands可以按 cwd 缓存目录内容不随登录状态变但meetsAvailabilityRequirement和isCommandEnabled的结果不能缓存。6.4 消息队列里的消息丢失或乱序如果队列直接放在 React state 里React 的批量更新可能导致消息丢失或乱序。正确做法是模块级队列 useSyncExternalStore订阅非 React 代码直接读模块级变量。检查你的enqueue和dequeue是不是操作同一个模块级数组而不是各自维护一份副本。6.5 大命令拖慢启动如果某个命令的实现文件很大几千行不要在注册对象里直接import用动态import()包在getPromptForCommand里。注册表里只放轻量壳重实现延迟到首次调用时加载。7. 继续往下走命令系统的核心就三件事七路来源合并成一张表、两道过滤决定谁能看到、三岔分发决定怎么执行。把这三段拆开之后每一段都可以独立测试和替换。如果你想在自己的 CLI 工具里复现这套结构建议先从最小版本开始一个Command接口、一个loadAllCommands合并函数、一个processUserInput三岔入口。跑通之后再逐步加插件来源、加 Feature Gate、加消息队列。调试过程中如果需要验证 prompt 型命令的实际输出可以用模型对话页快速确认后端是否正常https://taotoken.net/models 。接入细节和 SDK 示例在文档里https://taotoken.net/doc 。密钥管理在控制台https://taotoken.net/api-keys 。长期跑编码任务或 Agent 循环的话Coding Plan 更适合高频场景https://taotoken.net/coding-plan 。下一篇我会拆斜杠命令的参数解析和上下文组装也就是processSlashCommand里那 3600 行到底在干什么。