# 命令补全与智能候选

> **说明**
> 本页按 Pebrel 2.1.1 核对，智能补全从 2.1.0 起提供。1.9.x 的补全样式和接受键与这里不同；如果界面没有三个模式，先在设置中核对版本，不要照着新界面寻找旧版没有的选项。

## 打开命令补全

在 **设置 → 终端 → 补全** 开启 **启用命令补全**，再选择 **补齐模式**。回到普通 Shell 提示符，输入命令或路径的开头。切换模式会立即作用于已经打开的终端。

候选既可以来自已执行的历史命令，也可以来自当前环境，例如 Git 分支、项目脚本和文件路径。第一次输入命令也可能出现建议，不必先运行一遍；这些补齐不需要请求 AI 服务或安装 Shell 补齐插件。

## 选择模式与接受建议

| 模式 | 显示方式 | 如何填入 |
| --- | --- | --- |
| **行内补齐** | 建议以灰字接在光标后 | 按 Tab 接受灰字 |
| **列表补齐** | 随输入显示候选列表 | 上下方向键选择，Tab 填入；没有选中项时 Tab 接受第一项 |
| **混合补齐** | 默认显示灰字；Tab 展开列表 | 右方向键接受灰字；列表中用上下方向键选择、Enter 填入 |

列表打开时可按 Esc 关闭。混合模式的 Tab 用于打开列表或移动选择，不是直接执行命令。

**接受建议只填入文字，不执行命令。** 检查完整命令、路径和目标主机，再按 Enter 执行。尤其在混合模式里，第一次 Enter 可能只是接受选中的候选，不要连续按键而跳过检查。

当前界面由模式决定按键，不再单独提供“补全接受键”选择。需要完全使用 Shell 自己的补全时，关闭 Pebrel 的 **启用命令补全**。

## 试用不依赖历史的补齐

先进入已有的本地项目目录。在命令末尾保留表中的空格，再输入部分名称。下面是输入前缀，不是要求直接执行的完整命令：

| 输入前缀 | 预期候选 | 没有候选时先确认 |
| --- | --- | --- |
| `git switch ` | 当前仓库可用的分支 | 当前目录属于 Git 仓库，且确实有可切换分支 |
| `npm run ` | 项目 `package.json` 中的脚本名 | 最近的项目清单存在有效的 `scripts` |
| `ssh ` | SSH config 中可用的主机别名 | 本机 `~/.ssh/config` 中配置了具体的 Host 名称 |
| `wsl -d ` | 已注册的 WSL 发行版 | 在 Windows 本地 Shell 中输入，且已安装发行版 |
| `cat ` | 当前目录的文件 | 文件存在，当前 Shell 支持该命令；cmd 可使用 `type ` |

`ssh -F config ` 会使用指定配置文件中的别名；它与 Pebrel 主机库中保存的显示名称不是同一来源。相关设置见 [SSH config](/docs/ssh-config/)。

文件名含空格时，接受后检查引号是否覆盖完整路径。不要把候选中存在某个命令理解为已经安装了该程序；例如补齐 npm 脚本不会替你安装 Node.js，也不会运行脚本。

## 历史补齐与环境边界

运行一次无副作用的 `echo deployment finished`，等提示符返回后输入 `echo dep`，可以检查历史建议。历史补齐是复用已执行的命令；项目补齐则依据当前仍然存在的候选，已经删除的脚本或分支不会仅因出现过而重新成为有效项目候选。

本机 Git、项目脚本、SSH 别名和 WSL 发行版发现用于本地 Shell；不要期待它们读取 SSH 服务器或 WSL 项目中的同名文件。WSL、SSH 的路径建议取决于对应会话的目录查询能力，历史也按环境区分，不应拿宿主机路径来判断远端补齐。

Vim、全屏程序或正在运行的 AI CLI 有自己的按键行为。检查 Pebrel 补齐时，先回到普通 Shell 提示符。

## 排查没有建议或建议不对

1. 确认 **启用命令补全** 已打开，输入位置确实是 Shell 提示符。
2. 用 `pwd`（cmd 使用 `cd`）确认当前目录；Git 和脚本候选需要对应项目上下文。
3. 区分本地、WSL 和 SSH 窗格，按上面的环境边界检查候选来源。
4. 用 `echo` 示例区分历史补齐问题与项目候选问题。
5. 出现两套重复建议时，关闭 Pebrel 补齐或 Shell 插件中的一套再比较。

反复使用且不适合依赖历史的长命令，可以存入[保存命令](/docs/commands/)。

---
Source: Kuddev/pebrel PR #291, WilliamWang1721 and Pebrel contributors.
Adapted for pebrel.com. License: GPL-3.0.
