深入拆解 Claude Code 源码（四）：77 个斜杠命令背后的三种设计模式与插件迁移之路

深入拆解 Claude Code 源码（四）：77 个斜杠命令背后的三种设计模式与插件迁移之路

系列：深入拆解 Claude Code 源码 | 第 4 篇 / 共 8 篇
关键词：Claude Code, 斜杠命令, Command 接口, prompt 命令, local 命令, 插件系统

开篇：一个命令，三种命运

在 Claude Code 里输入 /commit，AI 会帮你写一个 commit message 并提交代码。输入 /vim，终端会切换到 Vim 编辑模式。输入 /help，会弹出一个漂亮的 React 帮助面板。

这三个命令看起来都是"斜杠命令"，但它们的内部实现完全不同：

• /commit 是 prompt 类型 —— 它生成一段 AI 提示词，交给对话引擎处理
• /vim 是 local 类型 —— 它直接在本地执行 JavaScript 逻辑
• /help 是 local-jsx 类型 —— 它渲染一个 React/Ink 组件到终端

这三种类型，就是 Claude Code 命令系统的核心设计模式。今天我们就来拆解这 77 个命令背后的架构。

一、Command 接口：12 个字段的精密设计

所有命令都实现同一个接口，定义在 src/commands.ts 中。这个接口有 12 个字段，每一个都有其存在的理由：

// src/types/command.ts → src/commands.ts
interface Command {
  // ─── 身份标识 ───
  name: string              // 命令名称（不含 /），如 'commit', 'clear'
  type: 'prompt' | 'local' | 'local-jsx'  // 命令类型，决定执行路径
  description: string       // 命令描述，显示在 /help 面板中
  aliases: string[]         // 别名列表，如 /reset → /clear, /continue → /resume

  // ─── 生命周期控制 ───
  isEnabled: () => boolean  // 动态判断是否启用（运行时检查环境变量、Feature Flag 等）
  isHidden: boolean         // 是否在帮助面板中隐藏（如 /heapdump、/thinkback-play）
  immediate: boolean        // 是否立即执行，不等用户确认（如 /rename、/mcp、/status）

  // ─── 运行环境 ───
  supportsNonInteractive: boolean  // 是否支持 SDK/CLI 非交互模式（如 /compact、/advisor）
  availability: string[]    // 可用环境限制：'claude-ai'（订阅用户）、'console'（API 用户）
  source: 'builtin' | 'plugin'  // 来源：内置 or 插件

  // ─── 实现 ───
  argumentHint: string      // 参数提示，显示在命令名后面，如 '<model>|off'
  load: () => Promise       // 延迟加载工厂函数，返回命令的实际实现
}

关键设计：load() 是延迟加载的核心。每个命令的实际实现被封装在一个返回 Promise 的工厂函数中。只有当用户真正输入某个命令时，对应的代码才会被 import() 动态加载到内存中。/insights 命令的实现文件有 3201 行（113KB），如果没有延迟加载，它会在启动时白白占用内存。

availability 字段是一个精巧的访问控制机制。在 src/commands.ts 中，meetsAvailabilityRequirement() 函数会根据用户的认证状态过滤命令：

// src/commands.ts
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  // claude.ai 订阅用户
        break
      case 'console':
        // Console API 用户 = 第一方 API 客户端（排除 Bedrock/Vertex/Foundry）
        if (!isClaudeAISubscriber() && !isUsing3PServices()
            && isFirstPartyAnthropicBaseUrl())
          return true
        break
    }
  }
  return false
}

这就是为什么 /usage、/upgrade、/chrome 等命令在使用第三方 API 时不会出现 —— 它们的 availability 设置了 'claude-ai' 限制。

二、三种命令类型详解

类型一：prompt 命令 —— AI 的"剧本"

prompt 命令不直接执行任何操作，它只是生成一段精心构造的提示词，交给 AI 处理。这是 Claude Code 命令系统中最巧妙的设计 —— 把人类的意图转化为 AI 能理解的"剧本"。

/commit：93 行代码的 Git 提交自动化

/commit 命令看起来简单，但它的 getPromptContent() 函数包含了一整套精心设计的"安全协议"：

// src/commands/commit.ts (93 行)
const ALLOWED_TOOLS = [
  'Bash(git add:*)',
  'Bash(git status:*)',
  'Bash(git commit:*)',
]

function getPromptContent(): string {
  const { commit: commitAttribution } = getAttributionTexts()

  // undercover 模式：Anthropic 内部使用的特殊指令前缀
  let prefix = ''
  if (process.env.USER_TYPE === 'ant' && isUndercover()) {
    prefix = getUndercoverInstructions() + '\n'
  }

  return `${prefix}## Context
- Current git status: !\`git status\`
- Current git diff (staged and unstaged changes): !\`git diff HEAD\`
- Current branch: !\`git branch --show-current\`
- Recent commits: !\`git log --oneline -10\`

## Git Safety Protocol
- NEVER update the git config
- NEVER skip hooks (--no-verify, --no-gpg-sign, etc)
- CRITICAL: ALWAYS create NEW commits. NEVER use git commit --amend
- Do not commit files that likely contain secrets (.env, credentials.json, etc)
- If there are no changes to commit, do not create an empty commit
- Never use git commands with the -i flag (interactive input not supported)

## Your task
Based on the above changes, create a single git commit:
1. Analyze all staged changes, draft a concise commit message (1-2 sentences, focus on "why")
2. Stage relevant files and create the commit using HEREDOC syntax
   (commitAttribution 自动附加到 commit message 末尾)
`
}

注意那个 !\``git status\`` 语法 —— 这是 Claude Code 的 内联 Shell 执行 机制。executeShellCommandsInPrompt() 函数会在发送给 AI 之前，先在本地执行这些命令，把结果替换到提示词中。AI 看到的不是 !\git status``，而是真实的 git 状态输出。

还有一个细节：getAttributionTexts() 会返回类似 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> 的归因文本，自动附加到 commit message 中。

/commit-push-pr：159 行的全流程自动化

如果说 /commit 是"一键提交"，那 /commit-push-pr 就是"一键发 PR"。它的工作量大得多：

// src/commands/commit-push-pr.ts (159 行)
const ALLOWED_TOOLS = [
  'Bash(git checkout --branch:*)',
  'Bash(git checkout -b:*)',
  'Bash(git add:*)',
  'Bash(git status:*)',
  'Bash(git push:*)',
  'Bash(git commit:*)',
  'Bash(gh pr create:*)',
  'Bash(gh pr edit:*)',
  'Bash(gh pr view:*)',
  'Bash(gh pr merge:*)',
  'ToolSearch',                              // 搜索可用工具
  'mcp__slack__send_message',               // Slack MCP 集成
  'mcp__claude_ai_Slack__slack_send_message', // claude.ai Slack 集成
]

getPromptContent() 函数的核心逻辑：

function getPromptContent(defaultBranch: string, prAttribution?: string): string {
  const safeUser = process.env.SAFEUSER || ''
  const username = process.env.USER || ''

  // undercover 模式下：移除 reviewer 和 Slack 步骤
  let reviewerArg = ' and `--reviewer anthropics/claude-code`'
  let slackStep = `5. After creating PR, check CLAUDE.md for Slack channels...`
  if (process.env.USER_TYPE === 'ant' && isUndercover()) {
    reviewerArg = ''; slackStep = ''
  }

  return `## Context
- SAFEUSER: ${safeUser}, whoami: ${username}
- git status/diff/branch: !\`git status\` !\`git diff HEAD\` !\`git branch --show-current\`
- diff from ${defaultBranch}: !\`git diff ${defaultBranch}...HEAD\`

## Your task
1. Create new branch if on ${defaultBranch} (use SAFEUSER for prefix, fallback to whoami)
2. Commit with heredoc syntax (include commitAttribution)
3. Push to origin
4. Create or update PR (title < 70 chars)${reviewerArg}
   ...${slackStep}`
}

关键设计点：

• 分支命名：使用 SAFEUSER 环境变量（而非直接用 USER），回退到 whoami。这是为了避免在共享环境中泄露用户名。
• 并行解析：getPromptForCommand() 中用 Promise.all() 并行获取 defaultBranch 和 prAttribution。
• Slack 集成：通过 ToolSearch 动态搜索 Slack 工具，而非硬编码依赖。找到后询问用户是否发送，找不到则静默跳过。
• PR 归因：getEnhancedPRAttribution() 会生成比 commit 更详细的 PR 归因文本，包含 PR body 的 footer 部分。

/security-review：196 行安全审查提示词

/security-review 是整个命令系统中提示词最长的 prompt 命令。它的核心是 SECURITY_REVIEW_MARKDOWN —— 一个 196 行的 Markdown 模板，定义了完整的安全审查流程。

// src/commands/security-review.ts (244 行)
const SECURITY_REVIEW_MARKDOWN = `---
allowed-tools: Bash(git diff:*), Bash(git status:*), Bash(git log:*),
  Bash(git show:*), Bash(git remote show:*), Read, Glob, Grep, LS, Task
---

You are a senior security engineer conducting a focused security review.
...（自动注入 git status、diff、commit 日志）

OBJECTIVE: Identify HIGH-CONFIDENCE security vulnerabilities.
CRITICAL: Only flag issues where you're >80% confident of actual exploitability.

ANALYSIS METHODOLOGY:
Phase 1 - Repository Context Research: 识别安全框架、编码模式、消毒/验证模式
Phase 2 - Comparative Analysis: 对比新代码与现有安全模式，识别偏差
Phase 3 - Vulnerability Assessment: 追踪数据流，检查注入点和不安全反序列化

START ANALYSIS (3 steps):
1. Use a sub-task to identify vulnerabilities
2. For each vulnerability, create a parallel sub-task to filter false-positives
3. Filter out any vulnerabilities where confidence < 8`

安全检查 5 大类：

误报过滤 17+ 条硬排除规则 + 12 条先例规则：这是安全审查中最实用的部分。Claude Code 的工程师们把常见的误报模式硬编码进了提示词。挑几条最有代表性的：

HARD EXCLUSIONS（自动排除）:
- DOS 漏洞、磁盘密钥存储、速率限制、内存安全（Rust 等内存安全语言不报告）
- 单元测试文件、日志欺骗、仅控制路径的 SSRF、正则注入/DOS
- GitHub Action 工作流中的输入消毒（除非明确可通过不可信输入触发）
- React/Angular 中的 XSS（除非使用了 dangerouslySetInnerHTML）
- 客户端 JS/TS 中缺少权限检查（服务端负责，不是漏洞）

PRECEDENTS（先例判定）:
- 记录高价值密钥明文是漏洞，记录 URL 不是
- UUID 可假定为不可猜测，无需验证
- 环境变量和 CLI 标志是可信值，依赖控制环境变量的攻击无效
- ipython notebook 中的漏洞通常不可实际利用，除非有明确攻击路径

注意最终的 3 步分析流程：子任务识别漏洞 → 并行子任务过滤误报 → 过滤置信度 < 8 的结果。这意味着每个发现的漏洞都会被一个独立的 AI 子任务重新审查一遍，大幅降低了误报率。

/init：NEW_INIT 的 8 阶段交互式设置

/init 命令有两个版本，由 feature('NEW_INIT') 控制。旧版本（OLD_INIT_PROMPT）只是一个简单的"帮我创建 CLAUDE.md"提示词。新版本（NEW_INIT_PROMPT，约 200 行）是一个完整的 8 阶段交互式流程。命令入口根据 USER_TYPE === 'ant' 和环境变量 CLAUDE_CODE_NEW_INIT 决定使用哪个版本，执行时调用 maybeMarkProjectOnboardingComplete() 标记 onboarding 完成。

NEW_INIT 的 8 个阶段：

NEW_INIT 的设计哲学是"只写 Claude 会犯错的东西"。Phase 4 的 CLAUDE.md 写入规则非常严格：

• 包含：非标准的构建/测试/lint 命令、与语言默认不同的代码风格、测试怪癖、环境变量要求
• 排除：文件结构列表（Claude 可以自己读）、标准语言惯例、通用建议、频繁变化的信息（用 @path 引用代替）

prompt 命令的代表清单：

类型二：local 命令 —— 本地的"快速反应"

local 命令直接执行 JavaScript 逻辑，不经过 AI。适合不需要 AI 参与的纯操作。

// 示例：/version 命令
{
  name: 'version',
  type: 'local',
  async load() {
    return () => {
      console.log(MACRO.VERSION)
      if (MACRO.BUILD_TIME) {
        console.log(`Build: ${MACRO.BUILD_TIME}`)
      }
    }
  }
}

/compact：对话压缩的核心机制

/compact 是 local 命令中最复杂的一个。它不只是"清除历史"，而是一套精心设计的对话压缩系统。命令定义很简单：isEnabled 受 DISABLE_COMPACT 环境变量门控，支持非交互模式，支持自定义摘要指令作为参数。

compact.ts 的实现（约 100+ 行）包含多层压缩策略：

1. 会话记忆压缩（trySessionMemoryCompaction）：优先尝试，不支持自定义指令
2. 标准压缩（compactConversation）：调用 AI 生成对话摘要
3. 微压缩（microcompactMessages）：对消息进行细粒度裁剪
4. 响应式压缩（reactiveCompact）：Feature Flag REACTIVE_COMPACT 门控的实验性方案

压缩完成后还会执行一系列清理操作：清除用户上下文缓存、运行后压缩 hooks（runPostCompactCleanup）、通知缓存断裂检测（notifyCompaction）、标记压缩状态（markPostCompaction）、抑制压缩警告（suppressCompactWarning）。

/rewind：回到过去

/rewind（别名 checkpoint）支持恢复代码和/或对话到之前的状态。checkpoint 别名暗示了它的用途 —— 在关键时刻创建检查点，方便回溯。supportsNonInteractive: false，不支持 SDK 模式。

/clear：一键清空

/clear 有三个入口：/clear、/reset、/new。实现分为两层：clearSessionCaches（清除会话缓存）和 clearConversation（清除对话）。注意 supportsNonInteractive: false —— 在 SDK 非交互模式下，/clear 不会清除当前会话，而是应该创建一个全新的会话。

/advisor：模型顾问的三层验证

// src/commands/advisor.ts (110 行)
const advisor = {
  type: 'local',
  name: 'advisor',
  description: 'Configure the advisor model',
  argumentHint: '[<model>|off]',
  isEnabled: () => canUserConfigureAdvisor(),  // GrowthBook 配置门控
  get isHidden() {
    return !canUserConfigureAdvisor()  // 未启用时隐藏
  },
  supportsNonInteractive: true,
  load: () => Promise.resolve({ call }),  // 直接返回，无需动态导入
}

/advisor 支持三种操作：show（显示当前配置）、set <model>（设置模型）、unset/off（关闭）。设置模型时有三层验证：parseUserSpecifiedModel() 解析名称 → validateModel() 验证 API 有效性 → isValidAdvisorModel() 验证业务适配性。通过后持久化到用户设置，并检查当前主模型是否兼容 advisor 角色。

local 命令的代表清单：

类型三：local-jsx 命令 —— 终端里的"UI 组件"

local-jsx 命令渲染 React/Ink 组件，提供丰富的交互式界面。

// 示例：/help 命令
{
  name: 'help',
  type: 'local-jsx',
  async load() {
    return ({ onExit }) => (
      <Dialog title="Help" onCancel={onExit}>
        <Box flexDirection="column">
          <Text bold>Available Commands:</Text>
          {commands.map(cmd => (
            <ListItem key={cmd.name}>
              <Text color="blue">/{cmd.name}</Text>
              <Text dimColor>{cmd.description}</Text>
            </ListItem>
          ))}
        </Box>
      </Dialog>
    )
  }
}

/resume：恢复对话

/resume（别名 continue）渲染一个对话选择器 UI，让用户从历史会话列表中选择要恢复的会话。continue 别名的设计很贴心 —— 用户可以自然地说"继续上次的对话"。支持通过参数 [conversation id or search term] 直接指定会话。

/branch：对话分叉

/branch 在当前对话点创建一个分支。它的别名设计很有趣：当 FORK_SUBAGENT Feature Flag 开启时，fork 别名会被移除（aliases: feature('FORK_SUBAGENT') ? [] : ['fork']），因为此时存在一个独立的 /fork 命令（用于创建子 Agent）。这是一个别名冲突避免的典型案例。

/export：导出对话

/export 支持两种导出目标：文件（指定文件名参数）或剪贴板（不指定文件名）。

/brief：Kairos 的简要模式

// src/commands/brief.ts (131 行)
const brief = {
  type: 'local-jsx',
  name: 'brief',
  description: 'Toggle brief-only mode',
  isEnabled: () => {
    if (feature('KAIROS') || feature('KAIROS_BRIEF')) {
      return getBriefConfig().enable_slash_command  // GrowthBook 配置
    }
    return false
  },
  immediate: true,
  // load 直接返回 Promise.resolve，无需动态导入
}

/brief 是 Kairos 系统的一部分，它切换"简要模式"—— 在这个模式下，AI 只能通过特定的 Brief 工具输出内容，普通文本输出会被隐藏。它的实现有 131 行，包含几个精妙的设计：

• Zod schema 验证：GrowthBook 推送的配置通过 z.object({ enable_slack_command: z.boolean() }) 验证，防止错误配置
• 权益检查只在开启时生效：关闭 brief 模式总是允许的 —— 如果 GrowthBook 门控中途翻转，已开启 brief 模式的用户不会被卡住
• userMsgOptIn 双向同步：确保 Brief 工具可用性与 brief 模式状态一致，但这会导致 prompt cache 失效
• 系统提醒注入：工具列表变化不足以让模型"改习惯"，所以显式注入 <system-reminder> 告诉模型行为切换
• Kairos 活跃时跳过提醒：getKairosActive() 时 Kairos 系统提示词已经强制使用 SendUserMessage，无需额外提醒

local-jsx 命令的代表清单：

三、命令注册表：754 行的中央调度

src/commands.ts 是命令的集中注册表，754 行代码，管理着所有命令的生命周期。

注册结构

// src/commands.ts — 命令注册表（简化版）
const COMMANDS = memoize((): Command[] => [
  // ─── 会话管理 ───
  clear, compact, resume, session, exportCommand,
  rename, branch, rewind,

  // ─── 配置 ───
  config, color, theme, vim, keybindings, permissions,
  outputStyle, sandboxToggle, terminalSetup,

  // ─── 认证 ───
  login(), logout, usage, upgrade, extraUsage, passes, privacySettings,

  // ─── MCP 与集成 ───
  mcp, ide, chrome, desktop, mobile, installGitHubApp, installSlackApp,

  // ─── 代码审查与 Git ───
  review, ultrareview, securityReview, pr_comments, diff,

  // ─── 任务/Agent ───
  tasks, agents, plan, skills, memory,

  // ─── 信息 ───
  help, status, cost, stats, context, doctor, files, releaseNotes,

  // ─── AI 功能 ───
  usageReport, thinkback, thinkbackPlay, btw,

  // ─── 开发工具 ───
  hooks, heapDump, copy, reloadPlugins,

  // ─── 其他 ───
  exit, feedback, stickers, tag, statusline,

  // ─── 条件命令（Feature Flag 门控）───
  ...(webCmd ? [webCmd] : []),
  ...(forkCmd ? [forkCmd] : []),
  ...(buddy ? [buddy] : []),
  ...(proactive ? [proactive] : []),
  ...(briefCommand ? [briefCommand] : []),
  ...(assistantCommand ? [assistantCommand] : []),
  ...(bridge ? [bridge] : []),
  ...(remoteControlServerCommand ? [remoteControlServerCommand] : []),
  ...(voiceCommand ? [voiceCommand] : []),
  ...(peersCmd ? [peersCmd] : []),
  ...(workflowsCmd ? [workflowsCmd] : []),
  ...(torch ? [torch] : []),

  // ─── 内部命令（ant-only）───
  ...(process.env.USER_TYPE === 'ant' && !process.env.IS_DEMO
    ? INTERNAL_ONLY_COMMANDS : []),
])

动态命令加载

COMMANDS() 只是基础命令列表。完整的命令列表还需要合并来自四个来源的动态命令：

// src/commands.ts
const loadAllCommands = memoize(async (cwd: string): Promise<Command[]> => {
  const [
    { skillDirCommands, pluginSkills, bundledSkills, builtinPluginSkills },
    pluginCommands,
    workflowCommands,
  ] = await Promise.all([
    getSkills(cwd),           // .claude/skills/ 目录下的技能命令
    getPluginCommands(),      // 插件提供的命令
    getWorkflowCommands(cwd), // 工作流脚本命令
  ])

  return [
    ...bundledSkills,         // 内置技能
    ...builtinPluginSkills,   // 内置插件技能
    ...skillDirCommands,      // 用户自定义技能
    ...workflowCommands,      // 工作流命令
    ...pluginCommands,        // 插件命令
    ...pluginSkills,          // 插件技能
    ...COMMANDS(),            // 基础命令（最后，优先级最低）
  ]
})

最终的 getCommands() 函数会过滤掉不满足 availability 要求和 isEnabled() 返回 false 的命令，并合并运行时动态发现的技能。

四、条件加载与 Feature Flag

Claude Code 大量使用 bun:bundle 的 feature() 宏进行编译时死代码消除。以下是所有受 Feature Flag 控制的命令：

// src/commands.ts — 条件导入（编译时消除），共 15 个 Flag 门控命令
// 模式：feature('FLAG') ? require('./commands/xxx.js').default : null

// 单 Flag 门控
const voiceCommand = feature('VOICE_MODE')
  ? require('./commands/voice/index.js').default : null
const bridge = feature('BRIDGE_MODE')
  ? require('./commands/bridge/index.js').default : null

// OR 组合（任一 Flag 开启即可）
const proactive = feature('PROACTIVE') || feature('KAIROS')
  ? require('./commands/proactive.js').default : null
const briefCommand = feature('KAIROS') || feature('KAIROS_BRIEF')
  ? require('./commands/brief.js').default : null

// AND 组合（两个 Flag 都需开启）
const remoteControlServerCommand =
  feature('DAEMON') && feature('BRIDGE_MODE')
    ? require('./commands/remoteControlServer/index.js').default : null

// 其他 Flag：FORK_SUBAGENT, BUDDY, WORKFLOW_SCRIPTS, CCR_REMOTE_SETUP,
// KAIROS_GITHUB_WEBHOOKS, ULTRAPLAN, TORCH, UDS_INBOX, HISTORY_SNIP ...

完整的 Feature Flag 命令对照表：

注意 remoteControlServerCommand 需要两个 Flag 同时开启（DAEMON AND BRIDGE_MODE），这体现了它对运行环境的严格要求。

五、环境变量控制：企业级的命令禁用机制

除了 Feature Flag，Claude Code 还支持通过环境变量在运行时禁用特定命令。这主要用于企业部署场景 —— 企业管理员不希望员工使用某些命令（如登录、反馈、升级）。每个被禁用的命令都有一个对应的 isEnabled 检查：isEnabled: () => !isEnvTruthy(process.env.DISABLE_XXX)。

完整的环境变量控制表：

注意 /feedback 命令的禁用逻辑最复杂 —— 它同时被 6 个环境变量控制。这是因为第三方服务提供商（Bedrock/Vertex/Foundry）不支持 Anthropic 的反馈通道，所以需要自动禁用。

六、insights.ts：3201 行的巨型命令

/insights 是整个命令系统中最大的单文件（3201 行，113KB），它生成一个完整的 HTML 使用分析报告。正因为它太大，commands.ts 中专门用了一个延迟加载 shim：

// src/commands.ts — 延迟加载 shim
const usageReport: Command = {
  type: 'prompt',
  name: 'insights',
  description: 'Generate a report analyzing your Claude Code sessions',
  contentLength: 0,
  progressMessage: 'analyzing your sessions',
  source: 'builtin',
  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)
  },
}

6 阶段报告生成流程

Phase 1: Lite Scan
  → scanAllSessions() 扫描文件系统元数据（无 JSONL 解析）
  → 仅读取目录结构和文件大小，快速估算工作量

Phase 2: SessionMeta 加载
  → loadCachedSessionMeta() 尝试从缓存加载
  → logToSessionMeta() 解析未缓存的 JSONL 会话日志
  → deduplicateSessionBranches() 去重会话分支（同一会话的不同分支）

Phase 3: 特征提取
  → loadCachedFacets() 尝试从缓存加载
  → extractFacetsFromAPI() 对未缓存会话调用 API 提取特征
  → formatTranscriptForFacets() 格式化转录用于特征提取
  → saveFacets() 缓存提取结果

Phase 4: 聚合
  → aggregateData() 聚合所有会话数据
  → detectMultiClauding() 检测并行会话使用（多开 Claude Code）

Phase 5: 洞察生成
  → generateParallelInsights() 并行调用 Claude 生成 6+ 个洞察部分
  → 每个洞察部分独立生成，互不依赖

Phase 6: HTML 生成
  → generateHtmlReport() 生成完整 HTML 报告（~800 行 HTML）
  → generateBarChart() 生成柱状图
  → generateResponseTimeHistogram() 生成响应时间分布图
  → generateTimeOfDayChart() 生成时段使用图
  → buildExportData() 构建导出数据结构

核心数据结构

// 会话元数据 —— 从 JSONL 日志中提取
type SessionMeta = {
  session_id: string
  start_time: string
  end_time: string
  user_message_count: number
  assistant_message_count: number
  duration_minutes: number
  lines_added: number
  lines_removed: number
  files_modified: string[]
  git_commits: number
  language_counts: Record<string, number>  // 如 {"TypeScript": 42, "Python": 10}
  tool_counts: Record<string, number>      // 如 {"Bash": 15, "Read": 30}
}

// 会话特征 —— 通过 API 从转录中提取
type SessionFacets = {
  underlying_goal: string           // 用户的根本目标
  outcome: string                   // 会话结果
  brief_summary: string             // 简要摘要
  goal_categories: string[]         // 目标分类
  user_satisfaction_counts: Record<string, number>  // 满意度统计
  friction_counts: Record<string, number>           // 摩擦点统计
}

// 聚合数据 —— 所有会话的汇总
type AggregatedData = {
  total_messages: number
  total_sessions: number
  date_range: { start: string, end: string }
  languages: Record<string, number>
  tool_counts: Record<string, number>
  goal_categories: Record<string, number>
  outcomes: Record<string, number>
  satisfaction: Record<string, number>
  friction: Record<string, number>
  message_hours: Record<string, number>       // 按小时分布
  tool_error_categories: Record<string, number>
  multi_clauding: { sessions: number, peak: number }
}

// AI 生成的洞察结果
type InsightResults = {
  at_a_glance: string          // 一目了然的总结
  project_areas: string        // 项目区域分析
  interaction_style: string    // 交互风格分析
  what_works: string           // 什么有效
  friction_analysis: string    // 摩擦点分析
  suggestions: string          // 改进建议
  on_the_horizon: string       // 展望
}

关键函数一览

远程主机数据采集（ant-only）

对于 Anthropic 内部用户，/insights 还支持从远程开发主机收集数据：

// 远程主机数据采集
getRunningRemoteHosts()              // 获取运行中的远程主机列表
getRemoteHostSessionCount(host)      // 获取单个主机的会话数
collectFromRemoteHost(host, destDir) // 从单个主机收集数据到本地目录
collectAllRemoteHostData(destDir)    // 从所有主机批量收集

这些远程主机通常是 Anthropic 内部的云开发环境，工程师可能同时在多个环境中使用 Claude Code。

七、插件迁移模式：从内置到插件的无缝过渡

这是命令系统中最有趣的设计之一。部分内置命令正在从"编译进二进制"迁移到"插件安装"。

createMovedToPluginCommand 工厂（66 行）

// src/commands/createMovedToPluginCommand.ts (66 行)
export function createMovedToPluginCommand({
  name, description, progressMessage,
  pluginName, pluginCommand,
  getPromptWhileMarketplaceIsPrivate,  // 市场未公开时的回退逻辑
}: Options): Command {
  return {
    type: 'prompt',
    name,
    description,
    progressMessage,
    contentLength: 0,
    source: 'builtin',
    async getPromptForCommand(args, context): Promise<ContentBlockParam[]> {
      // ─── Ant 用户：显示插件安装指引 ───
      if (process.env.USER_TYPE === 'ant') {
        return [{
          type: 'text',
          text: `This command has been moved to a plugin. Tell the user:
1. Install: claude plugin install ${pluginName}@claude-code-marketplace
2. Use: /${pluginName}:${pluginCommand}
3. Docs: https://github.com/anthropics/claude-code-marketplace/blob/main/${pluginName}/README.md`,
        }]
      }
      // ─── 其他用户：保留原始 prompt 逻辑 ───
      return getPromptWhileMarketplaceIsPrivate(args, context)
    },
  }
}

这个工厂函数的核心是一个两阶段迁移策略：

1. Ant 用户（Anthropic 内部员工）：获得插件安装指引，告诉他们去 marketplace 安装
2. 其他用户（外部用户）：获得原始的 prompt 逻辑，体验完全不变

使用此模式的命令

这个模式的巧妙之处在于：对用户完全透明。无论命令是内置还是插件，用户输入 /security-review 的体验是一样的。内部员工提前体验插件版本，外部用户继续使用内置版本，直到 marketplace 公开后统一切换。

迁移状态在代码中的体现是 getPromptWhileMarketplaceIsPrivate 这个参数名 —— 它明确告诉未来的维护者：“这个回退逻辑只在 marketplace 是私有的时候需要，公开后可以删除。”

八、设计亮点总结

下篇预告

第五篇：35 个内置工具的瑞士军刀

命令是面向用户的入口，工具才是 AI 真正的"手脚"。Claude Code 内置了 35+ 工具，从文件读写到 Shell 执行，从网页搜索到 Agent 调度。所有工具都通过一个统一的 buildTool() 工厂函数构建，支持输入验证、权限检查、并发安全标记和 UI 渲染。

下一篇，我们将深入工具系统的架构，看看 AI 是如何通过这些"瑞士军刀"操作你的电脑的。

标签: Claude Code 斜杠命令 Command接口 prompt命令 插件系统 TypeScript 源码分析 Feature Flag 安全审查 insights