命令系统

职责概述

解决的问题：用户在 CC 中能做的不只是聊天——还要切换模型、压缩上下文、查看配置、审查代码等等。需要一个命令系统把这些操作统一为 /xxx 斜杠命令，让用户快速触发而不需要记住复杂的操作路径。

应用场景：① /model sonnet 快速切换模型 ② /compact 手动触发上下文压缩 ③ /review 对当前变更做代码审查 ④ /permissions 管理工具权限规则 ⑤ /buddy 孵化一只宠物 ⑥ 团队自定义的 /deploy、/test 等工作流命令。

一句话理解：就像微信的斜杠命令——输入 / 就弹出所有可用操作，选一个直接执行。

架构设计

核心数据流

命令注册与发现流程

命令类型分发

关键类型与接口

Command 联合类型

types/command.ts:175-206 — Command 是一个交叉类型，由 CommandBase 和三种命令变体之一组成：

// types/command.ts:175-206
export type CommandBase = {
  availability?: CommandAvailability[]    // 认证要求: 'claude-ai' | 'console'
  description: string
  hasUserSpecifiedDescription?: boolean
  isEnabled?: () => boolean               // 动态启用/禁用
  isHidden?: boolean                      // 从 typeahead 隐藏
  name: string
  aliases?: string[]
  argumentHint?: string                   // 参数提示（灰色显示）
  whenToUse?: string                      // 详细使用场景
  loadedFrom?: 'commands_DEPRECATED' | 'skills' | 'plugin'
             | 'managed' | 'bundled' | 'mcp'
  kind?: 'workflow'
  immediate?: boolean                     // 绕过队列立即执行
  isSensitive?: boolean                   // 参数从历史中脱敏
}

export type Command = CommandBase &
  (PromptCommand | LocalCommand | LocalJSXCommand)

PromptCommand — 提示类命令

// types/command.ts:25-57
export type PromptCommand = {
  type: 'prompt'
  progressMessage: string
  contentLength: number
  argNames?: string[]
  allowedTools?: string[]
  model?: string
  source: SettingSource | 'builtin' | 'mcp' | 'plugin' | 'bundled'
  context?: 'inline' | 'fork'            // inline=当前对话, fork=子代理
  agent?: string                          // fork 时的代理类型
  effort?: EffortValue
  paths?: string[]                        // 文件路径匹配 glob
  getPromptForCommand(args, context): Promise<ContentBlockParam[]>
}

典型命令定义示例

// commands/compact/index.ts — local 类型
const compact = {
  type: 'local',
  name: 'compact',
  description: 'Clear conversation history but keep a summary...',
  isEnabled: () => !isEnvTruthy(process.env.DISABLE_COMPACT),
  supportsNonInteractive: true,
  argumentHint: '<optional custom summarization instructions>',
  load: () => import('./compact.js'),      // 惰性加载
} satisfies Command

// commands/help/index.ts — local-jsx 类型
const help = {
  type: 'local-jsx',
  name: 'help',
  description: 'Show help and available commands',
  load: () => import('./help.js'),
} satisfies Command

// commands/review.ts — prompt 类型
const review: Command = {
  type: 'prompt',
  name: 'review',
  description: 'Review a pull request',
  progressMessage: 'reviewing pull request',
  contentLength: 0,
  source: 'builtin',
  async getPromptForCommand(args): Promise<ContentBlockParam[]> {
    return [{ type: 'text', text: LOCAL_REVIEW_PROMPT(args) }]
  },
}

命令过滤函数

// commands.ts:417-443 — 认证过滤
export function meetsAvailabilityRequirement(cmd: Command): boolean {
  if (!cmd.availability) return true
  for (const a of cmd.availability) {
    switch (a) {
      case 'claude-ai':
        if (isClaudeAISubscriber()) return true; break
      case 'console':
        if (!isClaudeAISubscriber() && !isUsing3PServices()
            && isFirstPartyAnthropicBaseUrl()) return true; break
    }
  }
  return false
}

// commands.ts:672-676 — 桥接安全判定
export function isBridgeSafeCommand(cmd: Command): boolean {
  if (cmd.type === 'local-jsx') return false    // JSX 命令有 UI 副作用
  if (cmd.type === 'prompt') return true         // prompt 类型天然安全
  return BRIDGE_SAFE_COMMANDS.has(cmd)           // local 需白名单
}

设计模式与亮点

1. 惰性加载（Lazy Loading）

每个命令的 load() 返回一个动态 import()。用户输入 /doctor 时才加载 doctor.tsx（含完整的诊断逻辑和 UI）。 这使得主入口 commands.ts 保持轻量——754 行管理 70+ 命令，每个命令的实现延迟到首次调用。

2. 条件编译与特性开关

命令系统大量使用 feature('XXX') 做 Dead Code Elimination。在构建时，未启用的特性分支被完全移除：

// commands.ts:62-122 — 条件导入示例
const bridge = feature('BRIDGE_MODE')
  ? require('./commands/bridge/index.js').default : null
const voiceCommand = feature('VOICE_MODE')
  ? require('./commands/voice/index.js').default : null
const workflowsCmd = feature('WORKFLOW_SCRIPTS')
  ? require('./commands/workflows/index.js').default : null

3. Memoize 缓存策略

命令列表通过 lodash memoize 按 cwd 缓存，避免每次按键触发 typeahead 时重新扫描文件系统。 clearCommandMemoizationCaches() 和 clearCommandsCache() 提供了精确和全局两种缓存失效机制。

4. 双重安全过滤

命令执行受两层安全机制保护：

• Remote Mode 过滤：REMOTE_SAFE_COMMANDS 白名单限制 --remote 模式下可用的命令（仅 session、exit、clear、help 等）
• Bridge 安全：isBridgeSafeCommand() 防止移动端/Web 客户端触发本地 JSX 渲染命令

5. 技能分层架构

命令系统实现了清晰的来源分层：

// commands.ts:449-469 — loadAllCommands 合并顺序
return [
  ...bundledSkills,          // 打包技能（内置）
  ...builtinPluginSkills,    // 内置插件技能
  ...skillDirCommands,       // .claude/commands/ 用户自定义
  ...workflowCommands,       // 工作流命令
  ...pluginCommands,         // 插件命令
  ...pluginSkills,           // 插件技能
  ...COMMANDS(),             // 70+ 内置命令
]

命令分类表

◈ 可视化处理拓扑图

⇉ 核心处理流程详解

命令系统是 Claude Code 用户交互的核心入口。当用户在 REPL 中输入 /command 时，系统需要从多个来源加载命令定义、执行可用性过滤、路由到正确的处理器，最终将结果返回给用户。整个流程涉及静态注册、动态发现、权限门控和类型分发四个关键阶段。

★ 设计精华

1. 三级命令类型系统的精妙分离

Command 联合类型（types/command.ts:205）将命令分为 prompt、local、local-jsx 三种执行模式。这种分类不是随意的——它精确对应了三种不同的用户交互需求：文本注入（不需要 UI）、同步执行（需要结果但不需要交互）、交互组件（需要完整的 React 渲染能力）。每种类型有独立的 call 签名和 load() 懒加载机制。

// types/command.ts:205-206
export type Command = CommandBase &
  (PromptCommand | LocalCommand | LocalJSXCommand)

// 每种类型有独立的 call 签名
type LocalCommandCall = (args, context) => Promise<LocalCommandResult>
type LocalJSXCommandCall = (args, context, onDone) => Promise<void>

2. Availability 门控的实时响应设计

meetsAvailabilityRequirement()（commands.ts:417）故意不做缓存。注释明确说明："auth state can change mid-session (e.g. after /login), so this must be re-evaluated on every getCommands() call"。这意味着每次 REPL 渲染命令列表时，都会重新检查认证状态。代价是每次调用遍历命令数组的 O(n) 开销，收益是 /login 后命令列表立即更新。

// commands.ts:417-443
export function meetsAvailabilityRequirement(cmd: Command): boolean {
  if (!cmd.availability) return true  // 无声明 = 全局可用
  for (const a of cmd.availability) {
    switch (a) {
      case 'claude-ai':
        if (isClaudeAISubscriber()) return true
        break
      case 'console':
        // 直接 API 用户（排除 3P 和 claude.ai）
        if (!isClaudeAISubscriber() &&
            !isUsing3PServices() &&
            isFirstPartyAnthropicBaseUrl()) return true
        break
      // ... exhaustive check
    }
  }
  return false
}

3. 动态技能的优先级插入算法

在 getCommands()（commands.ts:504-516）中，动态发现的技能需要插入到已有命令列表中。插入位置不是随意选择的——动态技能被插入到"插件技能之后、内置命令之前"。这确保了：内置命令优先级最高（同名冲突时内置胜出），插件技能次之，动态技能最低。

// commands.ts:504-516
const builtInNames = new Set(COMMANDS().map(c => c.name))
const insertIndex = baseCommands.findIndex(c => builtInNames.has(c.name))
return [
  ...baseCommands.slice(0, insertIndex),  // 技能 + 插件命令
  ...uniqueDynamicSkills,                  // 动态技能
  ...baseCommands.slice(insertIndex),      // 内置命令（最高优先级）
]

4. 三层缓存与精确失效

clearCommandMemoizationCaches()（commands.ts:523）需要清除三个独立的 memoize 缓存：loadAllCommands、getSkillToolCommands、getSlashCommandToolSkills。但更深层的问题是 getSkillIndex（skillSearch/localSearch.ts）是一个独立的外层缓存，它缓存了内层函数的结果。L527-531 的注释详细解释了 lodash memoize 的穿透陷阱：清除内层缓存后，外层仍返回旧结果。

5. 内部命令的编译时过滤

INTERNAL_ONLY_COMMANDS（commands.ts:225）数组收集所有仅限内部使用的命令。在 COMMANDS() 的末尾（L343-345），通过 process.env.USER_TYPE === 'ant' && !process.env.IS_DEMO 条件展开。这意味着外部构建完全不含这些命令——它们在编译时就被 tree-shaking 移除了，而非运行时隐藏。

// commands.ts:225-254
export const INTERNAL_ONLY_COMMANDS = [
  backfillSessions, breakCache, bughunter, commit,
  commitPushPr, ctx_viz, goodClaude, // ...
].filter(Boolean)

// commands.ts:343-345 — 条件展开
...(process.env.USER_TYPE === 'ant' && !process.env.IS_DEMO
  ? INTERNAL_ONLY_COMMANDS
  : [])

◈ Agent 实践借鉴 — 客服 Agent 命令交互设计

1. 场景映射：客服坐席的 "/" 命令

想象一个客服坐席的日常工作面板。坐席不想点菜单、不想记快捷键，最自然的操作是输入 "/" 触发命令：

// 客服命令的真实分级
/问候   → 自动插入"您好，请问有什么可以帮您？"
         纯文本注入，无 UI，无副作用 → 模板级

/查订单 ORDER-12345 → 调用订单系统，直接返回结果
         同步查询，有网络 IO，不需要表单 → 查询级

/退单   → 弹出退单表单：选择原因 + 填写金额 + 上传凭证
         需要交互式 UI，多步操作 → 表单级

/查物流 WAYBILL-67890 → 调用物流 API，返回时间线
         同步查询 → 查询级

/记录   → 将本次服务摘要写入客户档案
         同步操作 → 查询级

// Claude Code              →  客服 Agent
// ──────────────────────────────────────────
type: "prompt"     文本注入  →  模板级：/问候、/结束语
type: "local"      同步执行  →  查询级：/查订单、/查物流
type: "local-jsx"  交互 UI   →  表单级：/退单、/发券

// CC 的懒加载                       →  客服也按需加载
// CC 的统一 Command 联合类型        →  客服统一注册调度
// CC 的命令自动补全                →  坐席输入 "/" 弹候选

2. 借鉴 CC + 客服改造：伪代码实现

以下是客服命令系统的核心实现，借鉴 CC 的三级命令分离、懒加载和统一调度，但去掉终端相关的 React Reconciler：

// 客服命令的三级类型 — 借鉴 CC 的 PromptCommand/LocalCommand/LocalJSXCommand
type CSCommand = TemplateCommand | QueryCommand | FormCommand

// 模板级：纯文本注入，无 UI，无副作用
interface TemplateCommand {
  type: "template"
  name: string                          // "/问候"
  description: string                   // 自动补全的说明
  transformInput: (args: string) => string  // 模板渲染
}

// 查询级：同步调用后端，直接返回结果
interface QueryCommand {
  type: "query"
  name: string                          // "/查订单"
  description: string
  handler: (args: string) => Promise<QueryResult>
  loadingText: string                   // "正在查询订单..."
}

// 表单级：需要弹表单收集参数
interface FormCommand {
  type: "form"
  name: string                          // "/退单"
  description: string
  schema: FormSchema                    // 表单字段定义
  onSubmit: (formData: Record<string,any>) => Promise<FormResult>
}

// 表单 Schema 示例 — /退单
const refundFormSchema: FormSchema = {
  fields: [
    { key: "reason", label: "退款原因", type: "select",
      options: ["质量问题","七天无理由","发错货","其他"] },
    { key: "amount", label: "退款金额", type: "number", required: true },
    { key: "evidence", label: "凭证图片", type: "fileUpload", required: false },
  ]
}

// 统一调度器 — 借鉴 CC 的 switch(cmd.type) 模式
async function dispatchCSCommand(
  cmd: CSCommand, args: string, ctx: CSCommandContext
) {
  switch (cmd.type) {
    case "template":
      // 模板注入：直接插入到坐席的输入框或消息区
      const text = cmd.transformInput(args)
      ctx.insertToMessageArea(text)      // 不需要弹 UI
      break

    case "query":
      // 同步查询：显示 loading，调用后端，直接展示结果
      ctx.showLoading(cmd.loadingText)
      try {
        const result = await cmd.handler(args)
        ctx.displayResult(result)        // 查订单→卡片，查物流→时间线
      } finally {
        ctx.hideLoading()
      }
      break

    case "form":
      // 弹表单：Web 框架渲染表单，收集参数后提交
      ctx.openFormDialog({
        title: cmd.name,
        schema: cmd.schema,
        onSubmit: async (formData) => {
          const result = await cmd.onSubmit(formData)
          ctx.displayResult(result)
        }
      })
      break
  }
}

// 懒加载注册表 — 借鉴 CC 的 CommandDescriptor
const csCommandRegistry = new Map<string, CSCommandDescriptor>()

function registerCSCommand(name: string, loader: () => Promise<CSCommand>) {
  csCommandRegistry.set(name, {
    loaded: false,
    loader,                // 工厂函数，首次调用时执行
    instance: null,
    // 自动补全信息在注册时就提供，不需要加载实现
    autoComplete: { name, description: loader.description }
  })
}

// 首次调用时才加载实现
async function getCSCommand(name: string): Promise<CSCommand> {
  const desc = csCommandRegistry.get(name)
  if (!desc.loaded) {
    desc.instance = await desc.loader()
    desc.loaded = true
  }
  return desc.instance
}

// 自动补全 — 坐席输入 "/" 时触发
function getAutoCompleteList(): AutoCompleteItem[] {
  return Array.from(csCommandRegistry.values())
    .map(desc => desc.autoComplete)     // 只取 name + description
    .filter(cmd => isAvailable(cmd.name))  // 权限过滤
}

3. 落地清单：必须抄 vs 不需要抄

4. 常见坑

代码索引