# 快捷键指南

本文档列出了 SNOW AI CLI 中所有可用的快捷键和功能。

## 目录

- [基本编辑](#基本编辑)
- [光标移动](#光标移动)
- [文本删除](#文本删除)
- [模式切换](#模式切换)
- [导航和选择](#导航和选择)
- [剪贴板操作](#剪贴板操作)
- [命令执行控制](#命令执行控制)
- [历史记录和回滚](#历史记录和回滚)
- [面板和选择器](#面板和选择器)

## 基本编辑

| 快捷键                 | 功能     | 说明                                    |
| ---------------------- | -------- | --------------------------------------- |
| `Enter`                | 提交消息 | 发送当前输入的消息给 AI                 |
| `Ctrl+Enter`           | 插入换行 | 在输入框中插入新行，不提交消息          |
| `Ctrl+G`               | 外部编辑 | 在 Notepad 中编辑当前输入（仅 Windows） |
| `Backspace` / `Delete` | 删除字符 | 删除光标前的字符                        |

## 光标移动

### Readline 兼容快捷键

| 快捷键               | 功能           | 说明                                 |
| -------------------- | -------------- | ------------------------------------ |
| `Ctrl+A`             | 行首           | 移动光标到当前行开头                 |
| `Ctrl+E`             | 行尾           | 移动光标到当前行末尾                 |
| `Alt+F` / `Option+F` | 向前一个词     | 跳转到下一个词的开头（支持中文标点） |
| `Alt+B` / `Option+B` | 向后一个词     | 跳转到上一个词的开头（支持中文标点） |
| `↑`                  | 历史记录上一条 | 在终端风格历史导航中浏览上一条消息   |
| `↓`                  | 历史记录下一条 | 在终端风格历史导航中浏览下一条消息   |

注意：macOS 上 Option 键的三种检测方式：

1. `key.meta` 属性
2. 转义序列 `\x1bf` / `\x1bb`
3. Terminal.app 默认特殊字符 `ƒ` / `∫`

## 文本删除

### Readline 兼容快捷键

| 快捷键   | 功能         | 说明                                 |
| -------- | ------------ | ------------------------------------ |
| `Ctrl+K` | 删除到行尾   | 删除从光标位置到当前行末尾的所有内容 |
| `Ctrl+U` | 删除到行首   | 删除从当前行开头到光标位置的所有内容 |
| `Ctrl+W` | 删除前一个词 | 删除光标前的一个单词                 |
| `Ctrl+D` | 删除当前字符 | 删除光标位置的字符                   |

### 旧版兼容快捷键（保留）

| 快捷键   | 功能       | 说明                               |
| -------- | ---------- | ---------------------------------- |
| `Ctrl+L` | 清除到开头 | 删除从开头到光标的内容（旧版兼容） |
| `Ctrl+R` | 清除到末尾 | 删除从光标到末尾的内容（旧版兼容） |

## 模式切换

### YOLO 和 Plan 模式

| 快捷键      | 功能         | 说明                                           |
| ----------- | ------------ | ---------------------------------------------- |
| `Shift+Tab` | 循环切换模式 | 按顺序切换：YOLO → YOLO+Plan → Plan → 全部关闭 |
| `Ctrl+Y`    | 循环切换模式 | 同 `Shift+Tab`，按顺序切换模式                 |

模式切换顺序：

1. YOLO 模式
2. YOLO + Plan 模式（启用 Plan 时自动禁用漏洞搜寻模式）
3. Plan 模式
4. 全部关闭

### Profile 配置切换

| 快捷键   | 功能                 | 平台            |
| -------- | -------------------- | --------------- |
| `Ctrl+P` | 切换到下一个 Profile | macOS           |
| `Alt+P`  | 切换到下一个 Profile | Windows / Linux |

## 导航和选择

### 通用导航（所有选择器）

| 快捷键  | 功能     | 适用范围                                  |
| ------- | -------- | ----------------------------------------- |
| `↑`     | 上一项   | 所有选择器（循环导航：第一项 → 最后一项） |
| `↓`     | 下一项   | 所有选择器（循环导航：最后一项 → 第一项） |
| `Enter` | 确认选择 | 所有选择器                                |
| `ESC`   | 关闭     | 所有选择器和面板                          |

### 文件选择器特定快捷键

| 快捷键         | 功能           | 说明                                                   |
| -------------- | -------------- | ------------------------------------------------------ |
| `@`            | 触发文件选择器 | 输入 `@` 符号后自动显示文件列表                        |
| `@@`           | 内容搜索       | 搜索文件内容而非文件名                                 |
| `@:` / `@@:`   | 工作区过滤     | 选择一个工作目录来限定搜索范围，输入框中显示 `@[标签]` |
| `@??` / `@@??` | AI 智能搜索    | 使用 AI 代理根据自然语言智能搜索文件                   |
| `Tab`          | 选择文件       | 在文件选择器中选择当前高亮的文件                       |
| `Space`        | 切换多选       | 勾选/取消勾选当前文件以批量插入                        |
| `Ctrl+T`       | 切换显示模式   | 在树形和扁平显示模式之间切换                           |
| 输入文本       | 过滤文件       | 支持文件名和内容搜索                                   |

文件选择器搜索模式：

- `@` — 跨所有工作目录的文件名模糊搜索
- `@@` — 内容搜索：按文件内容查找文件（支持行号）
- `@:` / `@@:` — 工作区过滤：在 `@` 或 `@@` 后输入 `:` 可从列表中选择一个工作目录。选择后，输入框中会插入 `@[标签]` 标签，后续搜索仅限该目录范围
- `@??` / `@@??` — AI 智能搜索：在 `@` 或 `@@` 后输入 `??` 可触发 AI 驱动的文件搜索。代理理解自然语言查询，跨工作目录搜索并实时流式预览结果

### 命令面板快捷键

| 快捷键   | 功能         | 说明                            |
| -------- | ------------ | ------------------------------- |
| `/`      | 触发命令面板 | 输入 `/` 符号后显示可用命令列表 |
| `Tab`    | 自动完成     | 用选中的命令名替换输入框内容    |
| 输入文本 | 过滤命令     | 根据命令名和描述进行模糊搜索    |

### Agent 选择器

| 快捷键                 | 功能              | 说明                          |
| ---------------------- | ----------------- | ----------------------------- |
| `/agent-` 后按 `Enter` | 打开 Agent 选择器 | 从命令面板选择 `agent-` 命令  |
| 输入文本               | 自动过滤          | 输入会自动更新 Agent 过滤状态 |

### TODO 选择器

| 快捷键                | 功能             | 说明                           |
| --------------------- | ---------------- | ------------------------------ |
| `/todo-` 后按 `Enter` | 打开 TODO 选择器 | 从命令面板选择 `todo-` 命令    |
| `Space`               | 切换选择         | 选择/取消选择当前 TODO 项      |
| `Backspace`           | 删除搜索字符     | 删除搜索查询的最后一个字符     |
| 输入文本              | 搜索过滤         | 支持中文等多字节字符的模糊搜索 |

### Profile 选择器

| 快捷键      | 功能         | 说明                                  |
| ----------- | ------------ | ------------------------------------- |
| `Backspace` | 删除搜索字符 | 删除搜索查询的最后一个字符            |
| 输入文本    | 模糊搜索     | 支持中文等多字节字符过滤 Profile 列表 |

## 剪贴板操作

| 快捷键   | 功能 | 平台                              |
| -------- | ---- | --------------------------------- |
| `Ctrl+V` | 粘贴 | macOS（支持文本和图片）           |
| `Alt+V`  | 粘贴 | Windows / Linux（支持文本和图片） |

注意：粘贴功能支持：

- 纯文本
- 图片（自动检测并插入图片占位符）

## 命令执行控制

### 后台运行

| 快捷键     | 功能                 | 说明                         |
| ---------- | -------------------- | ---------------------------- |
| `Ctrl+B`   | 将命令移入后台       | 仅在命令执行过程中可用       |
| `/backend` | 打开后台进程管理面板 | 查看和管理所有后台运行的命令 |

后台运行功能说明：

- 当长时间运行的命令占用前台时，可以使用 `Ctrl+B` 将其移入后台
- 命令会继续在后台执行，不影响你继续操作
- 使用 `/backend` 指令查看所有后台进程
- 在后台进程面板中：
  - `↑/↓` - 选择进程
  - `Enter` - 终止选中的运行中进程
  - `ESC` - 关闭面板

## 历史记录和回滚

### 双击 ESC 回滚菜单

| 快捷键      | 功能         | 说明                                           |
| ----------- | ------------ | ---------------------------------------------- |
| `ESC` `ESC` | 打开回滚菜单 | 在 500ms 内按两次 ESC 键                       |
| `↑` / `↓`   | 选择回滚点   | 在历史消息中导航,选择要回滚到的位置            |
| `Enter`     | 确认回滚     | 回滚到选中的消息点(如有文件变更会弹出二次确认) |
| `ESC`       | 关闭回滚菜单 | 退出回滚模式                                   |

回滚功能说明:

- 如果选中的回滚点有文件变更,系统会显示文件回滚确认对话框
- 支持选择性回滚部分文件或全部回滚
- 支持跨会话回滚(从压缩后的会话回滚到原始会话)
- 回滚后会将选中的历史消息内容恢复到输入框

### 文件回滚确认对话框

当回滚点包含文件变更时,会显示确认对话框支持精细控制:

| 快捷键    | 功能         | 说明                                                     |
| --------- | ------------ | -------------------------------------------------------- |
| `Tab`     | 切换视图模式 | 在简洁模式和完整文件列表模式之间切换                     |
| `↑` / `↓` | 导航         | 简洁模式: 选择回滚选项; 完整模式: 导航文件列表           |
| `Space`   | 切换文件选择 | 仅在完整模式下: 选择/取消选择当前高亮的文件              |
| `Enter`   | 确认操作     | 简洁模式: 确认选中选项; 完整模式: 确认文件选择并执行回滚 |
| `ESC`     | 返回/取消    | 完整模式: 返回简洁模式; 简洁模式: 取消整个回滚操作       |

文件选择模式:

- 默认所有文件都被选中
- 使用 `Space` 可以取消选择不想回滚的文件
- 如果取消选择所有文件,相当于"仅回滚对话"
- 部分选择时,只会回滚选中的文件
- 完整模式下显示文件的选择状态: `[x]` 已选择, `[ ]` 未选择

### 终端风格历史导航

| 快捷键 | 功能       | 说明                         |
| ------ | ---------- | ---------------------------- |
| `↑`    | 上一条历史 | 输入框为空或未打开任何面板时 |
| `↓`    | 下一条历史 | 浏览历史记录                 |

## 面板和选择器

### 关闭顺序（按 ESC 键）

当按下 `ESC` 键时，系统按以下优先级关闭面板：

1. Profile 选择器
2. TODO 选择器
3. Agent 选择器
4. 文件选择器
5. 命令面板
6. 历史菜单

### 特殊命令

| 命令      | 功能              | 说明                       |
| --------- | ----------------- | -------------------------- |
| `/todo-`  | 打开 TODO 选择器  | 选择和管理项目中的 TODO 项 |
| `/agent-` | 打开 Agent 选择器 | 选择子代理执行任务         |

## 中文输入支持

系统完整支持中文输入法：

- 所有搜索和过滤功能都支持多字节字符（中文、日文、韩文等）
- 词边界检测支持中文标点符号（`\p{P}` Unicode 属性）
- 输入法组合状态得到正确处理，避免每个字母都触发搜索

## 焦点事件过滤

系统自动过滤终端焦点事件，防止产生干扰字符：

- 组件挂载后 500ms 内过滤所有可能的焦点事件
- 自动识别并过滤 `ESC[I` (焦点进入) 和 `ESC[O` (焦点退出) 序列
- 支持拖放操作时产生的焦点事件

## 提示

- 大多数导航都支持循环模式（到达列表末尾后返回开头）
- 快捷键设计遵循 Readline 标准，熟悉 bash/zsh 的用户会感到熟悉
- macOS 和 Windows/Linux 在某些快捷键上有差异（主要是 Ctrl vs Alt/Meta）
- 所有文本输入都支持粘贴检测，可以安全处理大量文本粘贴