Commands

Commands 模块实现了 Claude Code 的斜杠命令生态系统，包含 80+ 个子命令目录（从 /compact、/config 到 /teleport、/voice），每个命令是一个独立目录。模块提供统一的命令注册表（commands.ts）、命令发现（getCommands）、命令路由（findCommand）和权限过滤（filterCommandsForRemoteMode）。命令类型涵盖 prompt 型（注入提示词）、action 型（执行操作）和 UI 型（渲染界面），支持从内置命令、Skills、MCP 工具和插件四个来源聚合。

职责与设计理念

职责说明

斜杠命令系统，管理 80+ 个子命令的注册、发现与执行

设计理念

命令即目录——每个命令是独立的文件夹，自包含其逻辑、类型和测试。命令注册表是声明式的，命令发现是动态的，命令执行是多态的。

架构决策

为什么每个命令是一个独立目录而不是一个函数？

命令即目录（command-as-directory）模式

复杂命令（如 /review）需要多个文件（类型定义、子命令、测试）。目录模式让每个命令自包含，新增命令只需新建目录，不修改任何已有代码。这是开放-封闭原则的文件系统级实践。

⚖️ 简单命令（如 /clear）也需要一个目录，略显冗余，但一致性比简洁性更重要。

为什么命令有三种类型（prompt/action/ui）？

按执行方式分为 prompt 型、action 型和 UI 型

prompt 型命令（如 Skills）只注入提示词，不执行代码；action 型命令（如 /clear）直接执行操作；UI 型命令（如 /config）渲染交互界面。三种类型的执行路径完全不同，统一接口但分离实现。

文件清单

文件名 用途
compact/ 上下文压缩命令，智能摘要对话历史以释放 Token 窗口
config/ 配置管理命令，读写用户/项目级设置
model/ 模型切换命令，运行时更换 AI 模型
resume/ 会话恢复命令，从历史中恢复中断的对话
teleport/ 会话传送命令，跨设备迁移对话状态
mcp/ MCP 服务器管理命令，配置外部工具服务器
voice/ 语音交互命令，启用语音输入模式
review/ 代码审查命令，对 PR/diff 进行 AI 审查

使用场景

输入 / 触发命令补全

getCommands() 聚合四个来源的命令列表，Autocomplete 组件展示匹配结果

用户输入 "/" → getCommands() → Autocomplete 过滤 → 用户选择

/compact 压缩上下文

智能摘要对话历史，释放 Token 窗口空间，保留关键上下文

/compact → 生成摘要 → 替换历史消息 → 释放 Token

/teleport 跨设备传送

将当前会话状态序列化并传输到另一台设备

/teleport → 序列化会话 → Bridge 传输 → 目标设备恢复

依赖关系

  • Context — 9 个 React Context Provider，管理 UI 层的全局状态分发
  • Plugins — 内置插件注册表，管理可启用/禁用的内置插件生态
  • Bootstrap — 全局状态容器与会话生命周期管理，维护运行时的单一真相源

关键代码片段

命令注册与发现

export type Command = {
  type: 'prompt' | 'action' | 'ui'
  name: string
  description: string
  source: 'builtin' | 'bundled' | 'mcp' | 'plugin'
  userInvocable: boolean
  isEnabled: () => boolean
  getPromptForCommand: (args: string) => Promise<string>
}

async function getCommands(cwd: string): Promise<Command[]> {
  const [builtins, skills, mcpTools, plugins] = await Promise.all([
    getBuiltinCommands(),
    getSkills(cwd),
    getMcpSkillCommands(),
    getBuiltinPluginSkillCommands(),
  ])
  return [...builtins, ...skills, ...mcpTools, ...plugins]
}

四源聚合：内置命令 + Skills + MCP 工具 + 插件，统一为 Command 接口

远程模式权限过滤

function filterCommandsForRemoteMode(
  commands: Command[]
): Command[] {
  // 远程模式下禁用危险命令
  const blocked = new Set([
    'config', 'login', 'logout', 'doctor'
  ])
  return commands.filter(c => !blocked.has(c.name))
}

远程会话中过滤掉可能修改本地配置的危险命令，安全边界前移

技术笔记

performance

命令发现并行化

getCommands() 使用 Promise.all 并行加载四个来源，避免串行等待。Skills 和 MCP 工具的发现可能涉及文件系统扫描和网络请求。

security

远程模式命令过滤

远程会话（Bridge 模式）中，config/login/logout 等可能修改本地状态的命令被自动禁用，防止远程用户篡改本地配置。