Claude Code Command System 深度分析

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

// src/types/command.ts:175-203
export type CommandBase = {
  availability?: CommandAvailability[]  // 'claude-ai' | 'console'
  description: string
  hasUserSpecifiedDescription?: boolean
  isEnabled?: () => boolean             // 动态启用检查
  isHidden?: boolean                    // 从 typeahead/help 隐藏
  name: string
  aliases?: string[]
  argumentHint?: string                 // 参数提示文本
  whenToUse?: string                    // 使用场景描述 (来自 Skill spec)
  version?: string
  disableModelInvocation?: boolean      // 是否禁止模型调用
  userInvocable?: boolean               // 用户能否通过 /name 触发
  loadedFrom?: 'commands_DEPRECATED' | 'skills' | 'plugin' | 'managed' | 'bundled' | 'mcp'
  kind?: 'workflow'                     // workflow 类型标记
  immediate?: boolean                   // 是否绕过队列立即执行
  isSensitive?: boolean                 // 参数是否脱敏显示
  userFacingName?: () => string         // 用户可见名称覆盖
}

// src/types/command.ts:25-57
export type PromptCommand = {
  type: 'prompt'
  progressMessage: string
  contentLength: number               // 字符数 (token 估算用)
  argNames?: string[]
  allowedTools?: string[]             // 限定可用工具
  model?: string                      // 模型覆盖
  source: SettingSource | 'builtin' | 'mcp' | 'plugin' | 'bundled'
  pluginInfo?: { pluginManifest: PluginManifest; repository: string }
  disableNonInteractive?: boolean
  hooks?: HooksSettings                // 技能注册的 hooks
  skillRoot?: string                   // 技能资源根目录
  context?: 'inline' | 'fork'         // inline = 当前会话; fork = 子 agent
  agent?: string                       // fork 模式下的 agent 类型
  effort?: EffortValue                 // 执行力度
  paths?: string[]                     // glob 模式限定适用文件
  getPromptForCommand(
    args: string,
    context: ToolUseContext,
  ): Promise<ContentBlockParam[]>      // 返回 prompt 内容块
}

// src/types/command.ts:74-78
type LocalCommand = {
  type: 'local'
  supportsNonInteractive: boolean
  load: () => Promise<LocalCommandModule>  // 懒加载
}

// src/types/command.ts:62-66
export type LocalCommandCall = (
  args: string,
  context: LocalJSXCommandContext,
) => Promise<LocalCommandResult>

// src/types/command.ts:16-23
export type LocalCommandResult =
  | { type: 'text'; value: string }
  | { type: 'compact'; compactionResult: CompactionResult; displayText?: string }
  | { type: 'skip' }

// src/types/command.ts:144-152
type LocalJSXCommand = {
  type: 'local-jsx'
  load: () => Promise<LocalJSXCommandModule>  // 懒加载
}

// src/types/command.ts:131-135
export type LocalJSXCommandCall = (
  onDone: LocalJSXCommandOnDone,          // 完成回调
  context: ToolUseContext & LocalJSXCommandContext,
  args: string,
) => Promise<React.ReactNode>             // 返回 Ink UI 组件

const COMMANDS = memoize((): Command[] => [
  addDir, advisor, agents, branch, btw, chrome, clear, color,
  compact, config, copy, desktop, context, contextNonInteractive,
  cost, diff, doctor, effort, exit, fast, files, heapDump, help,
  ide, init, keybindings, installGitHubApp, installSlackApp, mcp,
  memory, mobile, model, outputStyle, remoteEnv, plugin,
  pr_comments, releaseNotes, reloadPlugins, rename, resume,
  session, skills, stats, status, statusline, stickers, tag,
  theme, feedback, review, ultrareview, rewind, securityReview,
  terminalSetup, upgrade, extraUsage, extraUsageNonInteractive,
  rateLimitOptions, usage, usageReport, vim,
  // 条件命令:
  ...(webCmd ? [webCmd] : []),
  ...(forkCmd ? [forkCmd] : []),
  ...(buddy ? [buddy] : []),
  // ... 更多 feature-gated 命令
  // 内部命令 (仅 ant/employee):
  ...(process.env.USER_TYPE === 'ant' ? INTERNAL_ONLY_COMMANDS : []),
])

// src/commands.ts:449-469
const loadAllCommands = memoize(async (cwd: string): Promise<Command[]> => {
  const [
    { skillDirCommands, pluginSkills, bundledSkills, builtinPluginSkills },
    pluginCommands,
    workflowCommands,
  ] = await Promise.all([
    getSkills(cwd),           // .claude/skills/ + plugin skills
    getPluginCommands(),      // plugin manifest 命令
    getWorkflowCommands(cwd), // workflow 脚本
  ])

  return [
    ...bundledSkills,         // 1. 内置 bundled skills
    ...builtinPluginSkills,   // 2. 内置 plugin skills
    ...skillDirCommands,      // 3. .claude/skills/ 目录
    ...workflowCommands,      // 4. workflow 脚本
    ...pluginCommands,        // 5. plugin 命令
    ...pluginSkills,          //    plugin skills
    ...COMMANDS(),            // 6. 内置命令 (最后，优先级最低)
  ]
})

// src/commands.ts:476-517
export async function getCommands(cwd: string): Promise<Command[]> {
  const allCommands = await loadAllCommands(cwd)
  const baseCommands = allCommands.filter(
    _ => meetsAvailabilityRequirement(_) && isCommandEnabled(_),
  )
  // 动态 skills 插入...
}

// src/utils/slashCommandParsing.ts:25-59
export function parseSlashCommand(input: string): ParsedSlashCommand | null {
  const withoutSlash = input.trim().slice(1)
  const words = withoutSlash.split(' ')
  let commandName = words[0]
  let isMcp = false
  let argsStartIndex = 1

  // MCP 命令检测: "/mcp:tool (MCP) arg1"
  if (words.length > 1 && words[1] === '(MCP)') {
    commandName = commandName + ' (MCP)'
    isMcp = true
    argsStartIndex = 2
  }

  return { commandName, args: words.slice(argsStartIndex).join(' '), isMcp }
}

// src/utils/processUserInput/processSlashCommand.tsx:549-748
switch (command.type) {
  case 'local-jsx':
    return new Promise<SlashCommandResult>(resolve => {
      const onDone = (result?, options?) => {
        // 处理 display: 'skip'|'system'|'user'
        // 处理 shouldQuery, metaMessages, nextInput
      }
      command.load().then(mod =>
        mod.call(onDone, { ...context, canUseTool }, args)
      ).then(jsx => {
        // 渲染 Ink UI 组件
        setToolJSX({ jsx, shouldHidePromptInput: true, ... })
      })
    })

  case 'local':
    const mod = await command.load()
    const result = await mod.call(args, context)
    // result.type === 'text' → createCommandInputMessage(...)
    // result.type === 'compact' → buildPostCompactMessages(...)
    // result.type === 'skip' → return empty messages

  case 'prompt':
    if (command.context === 'fork') {
      return await executeForkedSlashCommand(...)  // 子 agent 执行
    }
    return await getMessagesForPromptSlashCommand(...)  // inline 注入
}

async function executeForkedSlashCommand(command, args, context, ...) {
  const agentId = createAgentId()
  const { skillContent, modifiedGetAppState, baseAgent, promptMessages } =
    await prepareForkedCommandContext(command, args, context)

  // KAIROS 模式: 后台执行，不阻塞用户输入
  if (feature('KAIROS') && kairosEnabled) {
    void runAgent(...)  // fire-and-forget
    return { messages: [], shouldQuery: false, ... }
  }

  // 普通模式: 同步执行，显示进度
  const result = await runAgent(agentDefinition, ...)
  return { messages: resultMessages, shouldQuery: true, ... }
}

const ALLOWED_TOOLS = [
  'Bash(git add:*)',
  'Bash(git status:*)',
  'Bash(git commit:*)',
]

const command = {
  type: 'prompt',
  name: 'commit',
  description: 'Create a git commit',
  allowedTools: ALLOWED_TOOLS,
  contentLength: 0,
  progressMessage: 'creating commit',
  source: 'builtin',
  async getPromptForCommand(_args, context) {
    const promptContent = getPromptContent()
    // executeShellCommandsInPrompt 处理 !`cmd` 语法
    const finalContent = await executeShellCommandsInPrompt(
      promptContent,
      {
        ...context,
        getAppState() {
          const appState = context.getAppState()
          return {
            ...appState,
            toolPermissionContext: {
              ...appState.toolPermissionContext,
              alwaysAllowRules: {
                ...appState.toolPermissionContext.alwaysAllowRules,
                command: ALLOWED_TOOLS,  // 自动允许 git 操作
              },
            },
          }
        },
      },
      '/commit',
    )
    return [{ type: 'text', text: finalContent }]
  },
}

const LOCAL_REVIEW_PROMPT = (args: string) => `
  You are an expert code reviewer. Follow these steps:
  1. If no PR number is provided, run \`gh pr list\`
  2. If a PR number is provided, run \`gh pr view <number>\`
  3. Run \`gh pr diff <number>\` to get the diff
  4. Analyze and provide thorough code review...
  PR number: ${args}
`

const review: Command = {
  type: 'prompt',
  name: 'review',
  description: 'Review a pull request',
  progressMessage: 'reviewing pull request',
  source: 'builtin',
  async getPromptForCommand(args) {
    return [{ type: 'text', text: LOCAL_REVIEW_PROMPT(args) }]
  },
}

const ultrareview: Command = {
  type: 'local-jsx',
  name: 'ultrareview',
  description: '~10–20 min · Finds and verifies bugs...',
  isEnabled: () => isUltrareviewEnabled(),
  load: () => import('./review/ultrareviewCommand.js'),
}

// index.ts
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'),
}

// compact.ts — call 函数核心逻辑
export const call: LocalCommandCall = async (args, context) => {
  const customInstructions = args.trim()

  // 1. 尝试 session memory compaction (无自定义指令时)
  if (!customInstructions) {
    const sessionMemoryResult = await trySessionMemoryCompaction(messages, agentId)
    if (sessionMemoryResult) {
      return { type: 'compact', compactionResult: sessionMemoryResult }
    }
  }

  // 2. 尝试 microcompact (短上下文)
  if (shouldMicrocompact) {
    const result = await microcompactMessages(...)
    if (result) return { type: 'compact', compactionResult: result }
  }

  // 3. 完整 compaction (调用模型总结)
  const result = await compactConversation(messages, customInstructions, ...)
  return { type: 'compact', compactionResult: result }
}

const config = {
  aliases: ['settings'],
  type: 'local-jsx',
  name: 'config',
  description: 'Open config panel',
  load: () => import('./config.js'),
} satisfies Command

const mcp = {
  type: 'local-jsx',
  name: 'mcp',
  description: 'Manage MCP servers',
  immediate: true,                    // 立即执行，不排队
  argumentHint: '[enable|disable [server-name]]',
  load: () => import('./mcp.js'),
} satisfies Command

const command = {
  type: 'prompt',
  name: 'init',
  get description() {
    return feature('NEW_INIT') && isAntOrFlag
      ? 'Initialize new CLAUDE.md file(s) and optional skills/hooks...'
      : 'Initialize a new CLAUDE.md file with codebase documentation'
  },
  contentLength: 0,
  progressMessage: 'analyzing your codebase',
  source: 'builtin',
  async getPromptForCommand() {
    maybeMarkProjectOnboardingComplete()
    return [{
      type: 'text',
      text: feature('NEW_INIT') && isAntOrFlag
        ? NEW_INIT_PROMPT     // 8 阶段完整流程 (~200 行 prompt)
        : OLD_INIT_PROMPT,    // 简单 prompt
    }]
  },
}

const resume: Command = {
  type: 'local-jsx',
  name: 'resume',
  description: 'Resume a previous conversation',
  aliases: ['continue'],
  argumentHint: '[conversation id or search term]',
  load: () => import('./resume.js'),
}

const doctor: Command = {
  name: 'doctor',
  description: 'Diagnose and verify your Claude Code installation and settings',
  isEnabled: () => !isEnvTruthy(process.env.DISABLE_DOCTOR_COMMAND),
  type: 'local-jsx',
  load: () => import('./doctor.js'),
}

// SkillTool.ts 中获取可用技能
const allCommands = await getCommands(cwd)
return allCommands.filter(cmd =>
  cmd.type === 'prompt' &&
  !cmd.disableModelInvocation &&
  cmd.source !== 'builtin' &&
  (cmd.loadedFrom === 'skills' || cmd.loadedFrom === 'bundled' || ...)
)

// src/commands.ts:619-637
export const REMOTE_SAFE_COMMANDS: Set<Command> = new Set([
  session, exit, clear, help, theme, color, vim, cost,
  usage, copy, btw, feedback, plan, keybindings, statusline,
  stickers, mobile,
])

// src/commands.ts:651-660
export const BRIDGE_SAFE_COMMANDS: Set<Command> = new Set([
  compact, clear, cost, summary, releaseNotes, files,
])

argumentHint: '[conversation id or search term]'  // /resume
argumentHint: '[enable|disable [server-name]]'     // /mcp
argumentHint: '<optional custom summarization instructions>'  // /compact

// src/commands.ts:523-539
export function clearCommandMemoizationCaches(): void {
  loadAllCommands.cache?.clear?.()
  getSkillToolCommands.cache?.clear?.()
  getSlashCommandToolSkills.cache?.clear?.()
  clearSkillIndexCache?.()
}

// src/commands.ts:728-753
export function formatDescriptionWithSource(cmd: Command): string {
  if (cmd.source === 'plugin') {
    const pluginName = cmd.pluginInfo?.pluginManifest.name
    if (pluginName) return `(${pluginName}) ${cmd.description}`
  }
  if (cmd.source === 'bundled') return `${cmd.description} (bundled)`
  // ...
}