# 后续建议

> Qwen Code 可以预测你接下来想输入的内容，并在输入区域中以占位符文本的形式显示。该功能通过一次 LLM 调用分析对话上下文，生成自然的下一步操作建议。

- 网址：https://funcoding.ai/agents/qwen-code/users/features/followup-suggestions/
- 来源：Qwen Code 官方文档原文（中文），Apache-2.0 许可，同步于 2026-10-11
- 官方原文：https://qwenlm.github.io/qwen-code-docs/zh/users/features/followup-suggestions

---
Qwen Code 可以预测你接下来想输入的内容，并在输入区域中以占位符文本的形式显示。该功能通过一次 LLM 调用分析对话上下文，生成自然的下一步操作建议。

该功能在 CLI 和 Web Shell 中均端到端可用。建议生成是自动的，在服务端完成：每完成一个干净结束的轮次（daemon 的 `end_turn` 停止原因——`cancelled`、`refusal`、`max_tokens` 或 `max_turn_requests` 的轮次不会生成建议），daemon 会在会话流上发出建议（默认开启；将 `ui.enableFollowupSuggestions` 设为 `false` 可关闭），而 Web Shell 的 composer 已经接入了 `useDaemonFollowupSuggestion` hook，因此建议可以直接渲染和接受，无需宿主额外接线。

## 工作原理

Qwen Code 完成响应后，经过短暂的延迟（约 300ms），一条建议会以淡化的占位符文本出现在输入区域。例如，修复一个 bug 后，你可能会看到：

```
> run the tests
```

建议的生成过程是：将对话历史发送给模型，由模型预测你可能自然输入的下一个内容。如果响应中包含明确的提示（例如 `Tip: type post comments to publish findings`），则会自动提取建议的操作。

## 接受建议

| 按键         | 操作                   |
| ------------ | ---------------------- |
| `Tab`        | 接受建议并填入输入框   |
| `Enter`      | 接受建议并填入输入框   |
| `Right Arrow`| 接受建议并填入输入框   |
| 任意输入     | 取消建议，正常输入     |

按下 `Enter` 会将建议填入输入框而非提交，因此接受一个建议的斜杠命令（例如 `/clear`）不会自动执行——你需要再按一次 `Enter` 来提交。

## 建议出现时机

交互式 CLI 和 daemon 分别独立决定是否生成建议，且它们应用的条件并不相同：CLI 在其各个渲染器中自行控制生成，而 daemon 则在服务端为每个附加到该会话的客户端控制生成。

双方都要求满足以下所有条件：

- 对话中至少已进行了 2 轮模型交互
- 审批模式未设置为 `plan`
- 该功能已启用（默认开启——将 `ui.enableFollowupSuggestions` 设为 `false` 可关闭）

交互式 CLI 还额外要求：

- 会话是交互式的——CLI 在其自身的非交互模式或 SDK 模式下永远不会生成建议
- 模型已完成响应（不在流式输出过程中）
- 最近一次响应中没有错误
- 没有待处理的确认对话框（例如 shell 确认、权限确认）。一个渲染器直接读取该状态；另一个则依据自身的待处理工具调用来控制，无法看到轮次中途打开的 shell 对话框，因此仍可能在对话框背后生成建议。但此时不会显示任何内容——对话框弹出时 composer 会被卸载——所以代价只是该轮次的生成调用，而不是一条你可能误操作接受的建议。

daemon 还额外要求：

- 轮次干净结束，即其停止原因为 `end_turn`——被取消、拒绝或截断的轮次不会生成建议
- 自动轮次未被 todo stop guard 暂停，且没有排队等待运行的 prompt
- 对话历史中的最新条目是模型响应

由于 daemon 端的生成会为每个附加到会话的客户端执行，因此也会为无法渲染结果的客户端执行。这类客户端——daemon 会话的 headless 或 SDK 消费者（不是上面提到的 CLI 自身的非交互模式）——应将 `ui.enableFollowupSuggestions` 设为 `false`，以避免为其丢弃的输出支付每轮 LLM 成本。

建议在以下情况会自动取消：

- 你开始输入
- 新一轮模型交互开始
- 建议被接受

## 快速模型

默认情况下，建议使用与主对话相同的模型。为了获得更低的延迟，可以配置一个专用的快速模型：

### 通过命令

```
/model --fast qwen3-coder-flash
```

或者使用 `/model --fast`（不带模型名称）打开选择对话框。

### 通过 settings.json

```json
{
  "fastModel": "qwen3-coder-flash"
}
```

快速模型用于提示建议和推测执行。当未配置时，将回退使用主对话模型。

> **成本说明：** 快速模型能降低延迟，但并不总能降低成本。建议生成会复用对话的前缀缓存（通过 `ui.enableCacheSharing`，默认开启）——但前缀缓存是按模型独立的。将 `fastModel` 指向另一个模型会切换到独立的缓存，因此整个对话历史将在快速模型上按未缓存的输入重新计费。在长对话中，默认方案（主模型+共享缓存）可能比快速模型**更便宜**，因为大部分历史按折扣后的缓存费率计费。当延迟比单次开销更重要时，再设置 `fastModel`。

对于所有后台任务（建议生成和推测），思考和推理模式会自动禁用，无论主模型的思考配置如何。这样可以避免在这些不需要推理的任务上浪费 token。

## 配置

以下设置可以在 `settings.json` 中配置：

| 设置                              | 类型    | 默认值  | 描述                                                       |
| -------------------------------- | ------- | ------- | --------------------------------------------------------- |
| `ui.enableFollowupSuggestions`   | boolean | `true`  | 启用或禁用后续建议                                         |
| `ui.enableCacheSharing`          | boolean | `true`  | 使用缓存感知的分叉查询以降低成本（实验性）                 |
| `ui.enableSpeculation`           | boolean | `false` | 在提交前推测性执行建议（实验性）                           |
| `fastModel`                      | string  | `""`    | 用于提示建议和推测执行的模型                               |

### 示例

```json
{
  "fastModel": "qwen3-coder-flash",
  "ui": {
    "enableFollowupSuggestions": true,
    "enableCacheSharing": true
  }
}
```

## 监控

建议模型的用量会在 `/stats` 输出中显示，包括快速模型在建议生成中消耗的 token。

快速模型也会在 `/about` 输出的“Fast Model”字段中显示。

## 建议质量

建议会经过质量过滤，确保其有用性：

- 长度必须在 2-12 个单词（中文：2-30 个字符）之间，总字符不超过 100
- 不能是评价性内容（“看起来不错”、“谢谢”）
- 不能使用 AI 口吻（“让我来……”、“我将会……”）
- 不能包含多个句子或带有格式（markdown、换行）
- 不能是元评论（“没有建议”、“沉默”）
- 不能是错误消息或带前缀的标签（“建议：……”）
- 单个单词的建议只允许用于常见命令（yes, commit, push 等）
- 斜杠命令（例如 `/commit`）始终允许作为单个单词的建议