570 lines
13 KiB
Markdown
570 lines
13 KiB
Markdown
# 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/` |
|