interactive-questions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Interactive Questions with the Question Tool

使用Question工具进行交互式提问

Use the

question

tool to ask users structured, interactive questions with selectable options instead of plain yes/no or free-text prompts. This produces a numbered option list the user navigates with arrow keys and confirms with Enter.

使用

question

工具向用户提出结构化的交互式问题，提供可选选项，而非单纯的是/否或自由文本提示。该工具会生成一个编号选项列表，用户可通过方向键导航并按Enter键确认选择。

Core Rule

核心规则

Never ask a yes/no question in plain text when the answer can be expressed as a set of options. Always use the

question

tool with explicit choices.

Wrong:

"Do you want to proceed? (yes/no)"

Right: use the

question

tool with options such as "Proceed" and "Cancel".

**当答案可以通过一组选项来表达时，绝对不要用纯文本提出是/否问题。**务必使用带有明确选项的

question

工具。

错误示例：

"你是否要继续？(是/否)"

正确做法：使用

question

工具提供“继续”和“取消”等选项。

When to Use the Question Tool

何时使用Question工具

Use it whenever you need the user to make a decision:

Confirmation — before destructive or irreversible actions (delete, overwrite, push, deploy)
Strategy selection — when multiple valid approaches exist and user preference matters
Clarification — when a request is ambiguous and each interpretation leads to meaningfully different work
Multi-step workflows — to let the user steer direction between phases

Do not use it for simple informational acknowledgement where no decision is required.

每当需要用户做出决策时，都可以使用该工具：

确认操作 — 在执行具有破坏性或不可逆的操作之前（如删除、覆盖、推送、部署）
选择策略 — 当存在多种有效方案且用户偏好至关重要时
澄清需求 — 当用户的请求模糊不清，不同的解读会导致截然不同的工作结果时
多步骤工作流 — 让用户在不同阶段之间掌控工作方向

无需将其用于无需决策的简单信息确认场景。

How to Call the Question Tool

如何调用Question工具

The tool accepts an array of

questions

. Each question has:

Field	Required	Notes
`question`	yes	The full question text shown to the user
`header`	yes	A very short label (max 30 chars) shown as the prompt title
`options`	yes	Array of `{ label, description }` objects
`multiple`	no	Set `true` to allow selecting more than one option

The tool automatically appends a "Type your own answer" option — do not add an "Other" catch-all yourself.

该工具接受一个

questions

数组。每个问题包含以下字段：

字段	是否必填	说明
`question`	是	展示给用户的完整问题文本
`header`	是	作为提示标题的极短标签（最多30个字符）
`options`	是	`{ label, description }` 对象组成的数组
`multiple`	否	设置为 `true` 时允许选择多个选项

该工具会自动添加“输入自定义答案”选项 —— 请勿自行添加“其他”类的兜底选项。

Option Design Rules

选项设计规则

Label: 1–5 words, concise action or noun phrase (e.g., "Proceed", "Cancel", "Edit message")
Description: one sentence explaining what that choice does (e.g., "Commit with the proposed message", "Abort the operation")
Order: put the recommended or most common option first; add
```
(Recommended)
```
at the end of its label when helpful
Coverage: include all meaningful paths — at minimum a "do it" option and a "cancel" option
No duplicates: each option must represent a distinct outcome

标签（Label）：1-5个词，简洁的动作或名词短语（例如：“继续”、“取消”、“编辑消息”）
描述（Description）：一句话解释该选项的作用（例如：“使用提议的消息提交”、“终止操作”）
排序：将推荐或最常用的选项放在首位；必要时在其标签末尾标注“(推荐)”
覆盖范围：涵盖所有有意义的选择路径 —— 至少包含一个“执行操作”选项和一个“取消”选项
无重复：每个选项必须代表不同的结果

Confirmation Pattern

确认操作模式

For any action that cannot easily be undone, use a three-option confirmation:

Proceed with <action>?
  1. Proceed (Recommended) — <short description of what happens>
  2. Cancel                 — Abort the operation
  3. Edit / Adjust          — <relevant alternative, e.g., "Provide a revised message">

对于任何难以撤销的操作，使用三选项确认模式：

是否继续执行<操作>？
  1. 继续（推荐） — <操作内容的简短描述>
  2. 取消                 — 终止操作
  3. 编辑/调整          — <相关替代选项，例如：“提供修改后的消息”>

Strategy Selection Pattern

策略选择模式

When multiple valid approaches exist:

How should I handle <situation>?
  1. <Approach A> (Recommended) — <one sentence tradeoff>
  2. <Approach B>               — <one sentence tradeoff>
  3. <Approach C>               — <one sentence tradeoff>

Always explain the tradeoff in the description so the user can decide without needing additional context.

当存在多种有效方案时：

应如何处理<场景>？
  1. <方案A>（推荐） — <一句话说明权衡利弊>
  2. <方案B>               — <一句话说明权衡利弊>
  3. <方案C>               — <一句话说明权衡利弊>

务必在描述中解释利弊，以便用户无需额外上下文即可做出决策。

Clarification Pattern

需求澄清模式

When a request is ambiguous, clarify before starting work rather than assuming:

What should <term / feature> include?
  1. <Interpretation A> — <what this means concretely>
  2. <Interpretation B> — <what this means concretely>

Limit clarification questions to genuine ambiguities. Do not ask about details you can decide using reasonable defaults.

当用户请求模糊不清时，在开始工作前先澄清，而非自行假设：

<术语/功能>应包含哪些内容？
  1. <解读A> — <该解读的具体含义>
  2. <解读B> — <该解读的具体含义>

仅针对真正模糊的点提出澄清问题。对于可通过合理默认值自行决定的细节，无需询问。

Multiple Selection

多选模式

Set

multiple: true

only when the user genuinely needs to pick more than one item — for example, selecting which files to include, which environments to target, or which checks to run. Keep the option list short (2–7 items) to avoid overwhelming the user.

仅当用户确实需要选择多个项目时，才设置

multiple: true

—— 例如选择要包含的文件、目标环境或要运行的检查项。选项列表应保持简短（2-7个），避免使用户感到负担。

Avoid These Anti-Patterns

需避免的反模式

Anti-pattern	Problem	Fix
Asking yes/no in text	Requires typing; no structured response	Use `question` tool with Proceed / Cancel options
Too many options (8+)	Overwhelming; hard to scan	Group related options or split into sequential questions
Vague labels ("Option 1")	User cannot decide without reading description	Use action-oriented labels ("Deploy to staging")
Catch-all "Other" option	Redundant — tool adds "Type your own answer" automatically	Remove it
Asking every minor detail	Slows workflow; irritates user	Reserve questions for decisions that genuinely affect the outcome
Multiple questions at once	Harder to process	Ask one question per tool call unless questions are tightly coupled

反模式	问题	解决方法
用纯文本提出是/否问题	需要用户手动输入，无结构化响应	使用 `question` 工具提供“继续”/“取消”选项
选项过多（8个及以上）	使用户不知所措，难以快速浏览	将相关选项分组，或拆分为多个连续的问题
模糊的标签（如“选项1”）	用户不阅读描述就无法做出决策	使用面向动作的标签（如“部署到预发布环境”）
兜底的“其他”选项	多余 —— 工具会自动添加“输入自定义答案”选项	删除该选项
询问每一个细节	拖慢工作流，惹恼用户	仅针对会真正影响结果的决策提出问题
一次性提出多个问题	增加用户的处理难度	除非问题紧密关联，否则每次工具调用仅提出一个问题

Quick Reference

快速参考

question tool fields:
  questions[].question     — full question text
  questions[].header       — short label (≤30 chars)
  questions[].options[]
    .label                 — 1–5 words
    .description           — one sentence
  questions[].multiple     — true | false (default false)

Do NOT add "Other" — tool appends "Type your own answer" automatically.
Put recommended option first, label it "(Recommended)".

question工具字段：
  questions[].question     — 完整问题文本
  questions[].header       — 短标签（≤30字符）
  questions[].options[]
    .label                 — 1-5个词
    .description           — 一句话
  questions[].multiple     — true | false（默认false）

请勿添加“其他”选项 —— 工具会自动添加“输入自定义答案”。
将推荐选项放在首位，并标注“(推荐)”。