URL: /built-in/ask_user

---
title: ask_user — 询问用户
description: 向用户提出一个带有选项的问题并获取回答
---

向用户提出一个带有选项的问题并获取回答。在需要用户做出决策、澄清需求、确认操作或选择偏好时使用。

**适用场景**：让 AI 询问用户选择哪个方案、确认是否执行某个操作、澄清模糊的需求、收集用户偏好等。

**注意**：一次只能问一个问题，不要在 `question` 中包含多个独立问题。

## 参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|:----:|------|
| `question` | string | 是 | 要向用户提出的问题，应清晰明确并以问号结尾 |
| `options` | object[] | 是 | 选项列表（1-6 个），每项包含 `label`（标签）和 `description`（说明）|
| `multi_select` | boolean | 否 | 是否允许多选，默认为 `false` |

## 交互界面

在交互式终端中，`ask_user` 会显示一个美观的选择界面：

```
? 你希望使用哪个方案？

  1. 方案 A   推荐，实现简单
> 2. 方案 B   性能更优但实现复杂
  3. 方案 C   第三方方案
  ───
  0. 自定义输入

数字选择 · j/k 或 ↑/↓ 导航 · Enter 确认 · Ctrl+C 取消
```

- **数字快捷键**：按 `1`-`9` 直接选择对应选项
- **导航**：`j`/`k` 或 `↑`/`↓` 移动光标
- **自定义输入**：最后一个选项支持用户自由输入文本
- **取消**：`Ctrl+C` 或 `Esc` 取消选择

## 约束与限制

| 限制项 | 值 |
|--------|:----:|
| 选项数量 | 1-6 个 |
| 运行环境 | 仅交互式终端（TTY），非 TTY 环境返回错误 |
| 多选模式 | 通过 `multi_select` 参数开启 |

## 错误场景

| 错误类型 | 说明 |
|----------|------|
| 缺少 `question` | 未提供必填参数 |
| 缺少 `options` | 未提供必填参数 |
| options 为空 | 选项列表不能为空数组 |
| 缺少 label | 选项中的 `label` 字段不能为空 |
| 非 TTY 环境 | 在管道、CI、重定向等非交互式环境中不可用 |
| 用户取消 | 用户按 `Ctrl+C` 取消选择 |

## 使用示例

```bash
zapmyco run '我想重构这个模块，请问你倾向哪种方案？'
```

## 相关文档

- [内置工具目录](/guide/built-in-tools) — 查看所有工具