# Claude Code 命令系统详解

## 概述

Claude Code 的命令系统是用户与 CLI 交互的核心方式。每个斜杠命令（slash command）都是一个独立的模块，支持懒加载以提高启动性能。命令定义遵循统一的 `Command` 接口，包含元数据和执行逻辑。

## 命令类型

### 1. prompt 类型命令
生成提示词发送给 AI 模型处理。

```typescript
type Command = {
  type: 'prompt'
  name: string
  description: string
  contentLength: number
  source: 'builtin'
  async getPromptForCommand(args): Promise<ContentBlockParam[]>
}
```

### 2. local-jsx 类型命令
渲染本地 React 组件的交互式命令。

```typescript
type Command = {
  type: 'local-jsx'
  name: string
  description: string
  load: () => import('./xxx.js')
}
```

### 3. local 类型命令
执行本地逻辑的命令，不涉及 AI 模型。

```typescript
type Command = {
  type: 'local'
  name: string
  description: string
  supportsNonInteractive: boolean
  load: () => import('./xxx.js')
}
```

---

## 命令详解

### /commit - 创建 Git 提交

**文件位置**: `src/commands/commit.ts`

**功能描述**: 分析当前 Git 状态，生成符合项目规范的提交信息，创建新的 Git 提交。

**触发条件**: 用户输入 `/commit`

**核心逻辑**:
1. 获取当前 Git 状态（`git status`、`git diff HEAD`、`git branch --show-current`）
2. 获取最近 10 条提交记录以了解项目提交风格
3. 根据变更内容生成提交信息
4. 使用 HEREDOC 语法执行 `git commit`

**安全协议**:
- 禁止更新 git config
- 禁止跳过 hooks（除非用户明确要求）
- 必须创建新提交，禁止使用 `--amend`
- 禁止提交包含密钥的文件（.env 等）
- 禁止使用需要交互输入的 git 命令（如 `git rebase -i`）

**相关文件**:
- `src/commands/commit.ts` - 命令入口
- `src/utils/attribution.js` - 获取归属文本

---

### /review - 代码审查

**文件位置**: `src/commands/review.ts`

**功能描述**: 审查 GitHub Pull Request 的代码变更。

**触发条件**: 用户输入 `/review [PR编号]`

**核心逻辑**:
1. 若未提供 PR 编号，执行 `gh pr list` 显示打开的 PR 列表
2. 若提供 PR 编号，执行 `gh pr view <number>` 获取详情
3. 执行 `gh pr diff <number>` 获取代码差异
4. 分析代码质量、风格、潜在问题、安全性等
5. 提供改进建议

**本地审查提示词** (`LOCAL_REVIEW_PROMPT`):
```
You are an expert code reviewer. Follow these steps:
1. If no PR number is provided, run `gh pr list`
2. Analyze the changes and provide a thorough code review
...
```

**ultrareview 命令**:
- 唯一入口：通过 `/ultrareview` 触发远程 Bug Hunter 路径
- 使用 `~10-20 min` 执行深度 bug 查找
- 需要在 Claude Code 网页版运行

**相关文件**:
- `src/commands/review.ts` - 包含本地 review 和 ultrareview 命令
- `src/commands/review/ultrareviewEnabled.ts` - ultrareview 功能开关

---

### /compact - 对话压缩

**文件位置**: `src/commands/compact/index.ts`, `src/commands/compact/compact.ts`

**功能描述**: 清除对话历史但保留摘要，保持在上下文中。

**触发条件**: 用户输入 `/compact [自定义摘要指令]`

**核心逻辑**:
1. 首先尝试会话内存压缩（无自定义指令时）
2. 若有自定义指令或会话内存压缩不适用，执行传统的压缩流程：
   - 执行 PreCompact hooks
   - 运行 microcompact 减少 token 数量
   - 调用 `compactConversation` 生成摘要
   - 执行 PostCompact hooks
3. 重置文件状态缓存
4. 生成压缩边界标记和摘要消息

**压缩类型**:
- **完整压缩**: 总结整个对话历史
- **部分压缩**: 围绕选定消息索引进行压缩
  - `from`: 总结索引之后的消息，保留早期消息
  - `up_to`: 总结索引之前的消息，保留后续消息

**相关服务**:
- `src/services/compact/compact.ts` - 核心压缩逻辑
- `src/services/compact/microCompact.ts` - 微压缩
- `src/services/compact/sessionMemoryCompact.ts` - 会话内存压缩
- `src/services/compact/postCompactCleanup.ts` - 压缩后清理

---

### /mcp - MCP 服务器管理

**文件位置**: `src/commands/mcp/index.ts`

**功能描述**: 管理 MCP（Model Context Protocol）服务器连接。

**触发条件**: 用户输入 `/mcp [enable|disable [服务器名称]]`

**核心逻辑**:
1. 懒加载 MCP 管理界面组件
2. 支持启用/禁用特定 MCP 服务器
3. 管理 MCP 服务器配置

**MCP 配置类型** (`Transport`):
- `stdio` - 标准 I/O 传输
- `sse` - Server-Sent Events
- `http` - HTTP 传输
- `ws` - WebSocket
- `sdk` - SDK 传输

**相关服务**:
- `src/services/mcp/useManageMCPConnections.ts` - MCP 连接管理 Hook
- `src/services/mcp/types.ts` - MCP 类型定义
- `src/services/mcp/client.ts` - MCP 客户端实现

---

### /config - 配置面板

**文件位置**: `src/commands/config/index.ts`

**功能描述**: 打开配置面板，管理 Claude Code 设置。

**别名**: `/settings`

**触发条件**: 用户输入 `/config`

**核心逻辑**:
- 懒加载配置面板 React 组件
- 支持用户偏好设置、项目设置等

---

### /doctor - 诊断检查

**文件位置**: `src/commands/doctor/index.ts`

**功能描述**: 诊断和验证 Claude Code 安装状态和设置。

**触发条件**: 用户输入 `/doctor`

**核心逻辑**:
1. 检查环境变量 `DISABLE_DOCTOR_COMMAND` 确认是否启用
2. 懒加载诊断组件
3. 执行多项检查：安装完整性、配置正确性、认证状态等

---

### /login - 登录

**文件位置**: `src/commands/login/index.ts`

**功能描述**: 使用 Anthropic 账户登录或切换账户。

**触发条件**: 用户输入 `/login`

**核心逻辑**:
1. 检测是否已有 API Key 认证（`hasAnthropicApiKeyAuth()`）
2. 根据认证状态显示不同描述
3. 检查环境变量 `DISABLE_LOGIN_COMMAND`
4. 懒加载登录组件

---

### /logout - 登出

**文件位置**: `src/commands/logout/index.ts`

**功能描述**: 从 Anthropic 账户登出。

**触发条件**: 用户输入 `/logout`

**核心逻辑**:
1. 检查环境变量 `DISABLE_LOGOUT_COMMAND`
2. 执行登出逻辑，清除认证信息

---

### /memory - 记忆文件编辑

**文件位置**: `src/commands/memory/index.ts`

**功能描述**: 编辑 Claude 记忆文件。

**触发条件**: 用户输入 `/memory`

**核心逻辑**:
- 懒加载记忆编辑器组件

---

### /skills - 技能列表

**文件位置**: `src/commands/skills/index.ts`

**功能描述**: 列出可用的技能（Skills）。

**触发条件**: 用户输入 `/skills`

**核心逻辑**:
- 懒加载技能列表组件
- 显示所有已安装和可用的技能

---

### /tasks - 后台任务管理

**文件位置**: `src/commands/tasks/index.ts`

**功能描述**: 列出和管理后台任务。

**别名**: `/bashes`

**触发条件**: 用户输入 `/tasks`

**核心逻辑**:
- 懒加载任务管理界面
- 显示正在运行、完成、失败的任务

---

### /vim - Vim 模式切换

**文件位置**: `src/commands/vim/index.ts`, `src/commands/vim/vim.ts`

**功能描述**: 在 Vim 和 Normal 编辑模式之间切换。

**触发条件**: 用户输入 `/vim`

**核心逻辑**:
- 切换 REPL 的编辑模式
- 仅在交互式会话中可用

---

### /diff - 变更查看

**文件位置**: `src/commands/diff/index.ts`

**功能描述**: 查看未提交的变更和每轮对话的差异。

**触发条件**: 用户输入 `/diff`

**核心逻辑**:
- 懒加载差异查看组件
- 显示工作区与上次提交的差异

---

### /cost - 成本显示

**文件位置**: `src/commands/cost/index.ts`, `src/commands/cost/cost.ts`

**功能描述**: 显示当前会话的总成本和持续时间。

**触发条件**: 用户输入 `/cost`

**隐藏条件**:
- Claude.ai 订阅用户（Ants 除外）默认隐藏
- 订阅用户可看到成本明细

---

### /theme - 主题切换

**文件位置**: `src/commands/theme/index.ts`

**功能描述**: 更改终端主题。

**触发条件**: 用户输入 `/theme`

**核心逻辑**:
- 懒加载主题选择组件

---

### /context - 上下文可视化

**文件位置**: `src/commands/context/index.ts`

**功能描述**: 将当前上下文使用情况可视化为彩色网格。

**触发条件**: 用户输入 `/context`

**交互模式变体**:
- `context` - 交互式彩色网格（仅交互式会话）
- `context` (非交互式) - 纯文本上下文使用情况

---

### /pr_comments - PR 评论获取

**文件位置**: `src/commands/pr_comments/index.ts`

**功能描述**: 获取 GitHub Pull Request 的评论。

**触发条件**: 用户输入 `/pr-comments [参数]`

**核心逻辑**:
1. 使用 `gh pr view` 获取 PR 信息
2. 使用 `gh api` 获取 PR 级评论
3. 使用 `gh api` 获取代码审查评论
4. 格式化显示评论列表

**备用方案**: 若市场不可用，使用内置提示词直接调用 GitHub CLI

---

### /resume - 恢复对话

**文件位置**: `src/commands/resume/index.ts`

**功能描述**: 恢复之前的对话。

**别名**: `/continue`

**触发条件**: 用户输入 `/resume [对话ID或搜索词]`

**核心逻辑**:
- 懒加载恢复界面
- 支持按 ID 或关键词搜索历史对话

---

### /share - 分享会话

**文件位置**: `src/commands/share/index.ts`

**功能描述**: 分享当前会话。

**触发条件**: 用户输入 `/share`

**核心逻辑**:
- 生成分享链接或会话导出

---

### /desktop - 桌面客户端

**文件位置**: `src/commands/desktop/index.ts`

**功能描述**: 在 Claude Desktop 中继续当前会话。

**别名**: `/app`

**触发条件**: 用户输入 `/desktop`

**平台限制**:
- macOS: 完全支持
- Windows (x64): 支持
- 其他平台: 隐藏

---

### /mobile - 移动应用

**文件位置**: `src/commands/mobile/index.ts`

**功能描述**: 显示下载 Claude 移动应用的二维码。

**别名**: `/ios`, `/android`

**触发条件**: 用户输入 `/mobile`

**核心逻辑**:
- 懒加载移动应用下载界面组件
- 显示 iOS 和 Android 的下载选项

---

### /permissions - 权限管理

**文件位置**: `src/commands/permissions/index.ts`

**功能描述**: 管理允许和拒绝的工具权限规则。

**别名**: `/allowed-tools`

**触发条件**: 用户输入 `/permissions`

**核心逻辑**:
- 懒加载权限管理界面
- 配置 `alwaysAllowRules` 等权限规则

---

### /agents - Agent 配置管理

**文件位置**: `src/commands/agents/index.ts`

**功能描述**: 管理 Agent 配置。

**触发条件**: 用户输入 `/agents`

**核心逻辑**:
- 懒加载 Agent 管理界面
- 支持多 Agent 配置

---

### /exit - 退出 REPL

**文件位置**: `src/commands/exit/index.ts`

**功能描述**: 退出 REPL 会话。

**别名**: `/quit`

**触发条件**: 用户输入 `/exit`

**特性**:
- `immediate: true` - 立即执行，不等待 AI 响应

---

### /bridge - 远程控制

**文件位置**: `src/commands/bridge/index.ts`

**功能描述**: 连接此终端进行远程控制会话。

**别名**: `/rc`

**触发条件**: 用户输入 `/remote-control [名称]`

**条件限制**:
- 需要启用 `BRIDGE_MODE` 功能
- 需要 `isBridgeEnabled()` 返回 true

**核心逻辑**:
- 建立与 Claude Code 网页版的桥接连接
- 支持远程会话控制

---

## 命令注册机制

命令通过 `src/commands.js` 统一注册和管理：

```typescript
export interface Command {
  type: 'prompt' | 'local-jsx' | 'local'
  name: string
  description: string
  aliases?: string[]
  load?: () => Promise<any>
  getPromptForCommand?: (args: string, context: CommandContext) => Promise<ContentBlockParam[]>
  allowedTools?: string[]
  contentLength?: number
  progressMessage?: string
  source?: 'builtin'
  isEnabled?: () => boolean
  isHidden?: boolean
  supportsNonInteractive?: boolean
  argumentHint?: string
}
```

## 懒加载机制

大多数命令使用懒加载模式：

```typescript
const command = {
  type: 'local-jsx',
  name: 'example',
  load: () => import('./example.js'),
}
```

这确保只有实际使用的命令才会加载其代码，优化启动性能。

## 权限控制

某些命令支持 `isEnabled()` 方法动态控制可用性：

```typescript
const command = {
  type: 'local',
  name: 'doctor',
  isEnabled: () => !isEnvTruthy(process.env.DISABLE_DOCTOR_COMMAND),
  load: () => import('./doctor.js'),
}
```

---

## 相关源码文件

| 命令 | 源码路径 |
|------|---------|
| commit | `src/commands/commit.ts` |
| review | `src/commands/review.ts` |
| compact | `src/commands/compact/` |
| mcp | `src/commands/mcp/` |
| config | `src/commands/config/` |
| doctor | `src/commands/doctor/` |
| login | `src/commands/login/` |
| logout | `src/commands/logout/` |
| memory | `src/commands/memory/` |
| skills | `src/commands/skills/` |
| tasks | `src/commands/tasks/` |
| vim | `src/commands/vim/` |
| diff | `src/commands/diff/` |
| cost | `src/commands/cost/` |
| theme | `src/commands/theme/` |
| context | `src/commands/context/` |
| resume | `src/commands/resume/` |
| share | `src/commands/share/` |
| desktop | `src/commands/desktop/` |
| mobile | `src/commands/mobile/` |
| permissions | `src/commands/permissions/` |
| agents | `src/commands/agents/` |
| exit | `src/commands/exit/` |
| bridge | `src/commands/bridge/` |