oh-my-pi 的 ask 工具:面向交互式编码 Agent 的澄清提问工具设计指南
oh-my-pi 的 ask 工具:面向交互式编码 Agent 的澄清提问工具设计指南
导读
ask 是 oh-my-pi(编码 Agent + IDE 深度集成的开源项目)内置的交互式提问工具:当任务存在多个权衡差异显著的方案、必须由用户拍板时,Agent 通过它向用户抛出单选、多选或自由文本问题,并把答案结构化回传。本指南以模型侧提示词 packages/coding-agent/src/prompts/tools/ask.md 为骨架,结合 ask.ts 的实现与 ask.test.ts 的测试用例,完整讲解 ask 的触发条件、参数契约、交互形态、超时回退与错误处理,读完即可掌握如何在 Agent 工具调用中正确使用 ask,以及其底层原理。
何时应该使用 ask:一个条件的判定
ask 的模型侧提示词 packages/coding-agent/src/prompts/tools/ask.md 对使用条件给出唯一约束:
Multiple approaches with significantly different tradeoffs user should weigh.
即只有当存在多条路径、且其取舍差异显著到用户必须亲自权衡时,才应提问。该文件同时给出两条硬性纪律:
- 优先行动(Default to action):先用代码、配置、文档与历史记录等一切已有来源消解歧义,只有选项的取舍确实存在实质差异且必须由用户决策时才提问;
- 多个选择均可接受时:选取最保守/最标准的方案直接执行,并在过程中说明该选择。
这与实现中 AskTool 的注册逻辑相互印证:AskTool.createIf() 仅当 session.hasUI 为真时才会注册(ask.ts 第 851-853 行),headless 会话根本拿不到这个工具——也就是说,ask 本身就是"有人可问"时的最后手段,而不是默认手段。
参数契约:question、options、multi、recommended
ask 的输入由一个必填字段 questions(Question[])组成,其 schema 由 ask.ts 中的 QuestionItem / askSchema 定义(第 70-87 行),关键字段如下:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
id |
string |
是 | 稳定标识符,用于多问题结果的关联 |
question |
string |
是 | 展示给用户的提问文本 |
options |
{ label, description?, preview? }[] |
是 | 选项列表;description 为解释性说明文字,preview 为富文本对话框提供的可选预览内容。运行时自带控件,调用方不得使用保留标签 Other (type your own)、Chat about this、Next → |
header |
string |
否 | 富 ask 对话框使用的简短展示标签;selector 回退模式忽略 |
multi |
boolean |
否 | 启用多选,默认 false |
recommended |
number |
否 | 从 0 开始的推荐/默认选项下标;无效下标会被忽略,回退 selector 会给有效的单选选项追加 (Recommended) |
模型侧提示词对格式做了三点补充约束(<instruction> 段):
recommended: <index>从 0 开始计数," (Recommended)" 后缀由运行时自动追加,无需模型手动书写;- 多个相关的问题应该用
questions一次性打包,而不是逐个串行提问; - 需要多选时给问题设置
multi: true; - 选项标签保持简短,详细的取舍说明放在
description中,不要写进标签。
<caution> 段则要求提供 2-5 个简洁、互异的选项;注意这是提示词层面的引导——如 docs/tools/ask.md 所述,代码只要求 options 数组存在,并不强制数量上下限。
<critical> 段还明确:不要提供 "Other" 选项,因为运行时 UI 会自动为每个问题追加 "Other (type your own)"。这在实现中体现为 RESERVED_OPTION_LABELS(ask.ts 第 55-62 行),一旦模型传入的标签与保留标签碰撞,schema 的 narrow 校验会直接拒绝该参数(第 77-83 行),execute() 中还会在 \r 清洗后二次检测碰撞并返回错误文本(第 889-923 行)。
一个可直接使用的调用示例
以下是 AskTool.examples 中内置的示例(ask.ts 第 800-838 行),展示了单问题与多问题两种形态:
{
"questions": [
{
"id": "auth_method",
"question": "Which authentication method should this API use?",
"options": [
{ "label": "JWT", "description": "Bearer tokens for stateless API clients." },
{ "label": "OAuth2", "description": "Delegated authorization with external identity providers." },
{ "label": "Session cookies", "description": "Browser-first authentication backed by server-side sessions." }
],
"recommended": 0
}
]
}
{
"questions": [
{ "id": "storage_type", "question": "Which storage backend?", "options": [{ "label": "SQLite" }, { "label": "PostgreSQL" }] },
{ "id": "auth_method", "question": "Which auth method?", "options": [{ "label": "JWT" }, { "label": "Session cookies" }] }
]
}
交互形态:富对话框与 selector/editor 回退
execute() 根据 UI 能力分两条路径(ask.ts 第 992-1085 行):
- 富 ask 对话框:当
context.ui提供askDialogAPI 时,一次打开一个多问题表单。header、description、preview都会在富形态中呈现;用户可以为答案附加 note,或选择对话框的 "Chat about this" 重定向。富形态对返回值有强校验:结果数量、id、顺序任一不匹配都会抛Error(第 1028-1037 行)。 - selector/editor 回退:否则对每个问题走选择器:
- 单选:列表 + "Other (type your own)"(ask.ts 第 644-718 行);
- 多选:复选框循环 + "Done selecting"(仅当非前向导航且至少选中一项时出现)+ "Other"(第 567-642 行);
- 多问题模式下,左右方向键在问题间前进/后退并保留之前的答案,最后一题选中后自动推进(第 1148-1191 行)。
单选/多选在终端里的区分由主题提供:单选渲染圆形 radio 字形,多选渲染矩形 checkbox 字形,见 theme.ts 的 theme.radio.* 与 theme.checkbox.*,TUI 侧的 askToolRenderer(ask.ts 第 1468 行起)与富对话框 ask-dialog.ts 均基于这两个主题标记渲染。
自定义输入(Other)与多行文本
选择 "Other" 后,promptForCustomInput 会通过 ui.editor 打开一个 promptStyle 编辑器(ask.ts 第 554-564 行)。编辑器标题由 formatCustomInputTitle 构造,对超长选项列表有硬性上限:选项行最多保留 8 行(MAX_CUSTOM_INPUT_OPTION_ROWS)、标题总行数最多 16 行(MAX_CUSTOM_INPUT_TITLE_ROWS),多出的选项用 "… N more options …" 折叠摘要,确保小终端上输入行不被挤出屏幕(第 202-217 行、第 248-390 行)。自定义输入支持多行文本——测试 ask.test.ts 中 "preserves raw multiline strings" 用例验证了 first line\nsecond line 会原样保存在 details.customInput 中。
结果结构:content 文本与结构化 details
ask 是单次(single-shot)工具,不流式更新,返回值由 content[0].text 与 details 两部分组成(docs/tools/ask.md):
- 单问题:
content形如User selected: JWT;details为扁平结构{ question, options, multi, selectedOptions, customInput?, note?, timedOut? }。格式化逻辑见formatSingleQuestionResponse(ask.ts 第 741-777 行),多行自定义输入与多行 note 会按行缩进输出。 - 多问题:
content以User answers:开头,每行对应一个id,如storage_type: SQLite、auth_method: JWT;details.results[]逐项包含id、question、options、multi、selectedOptions与可选的customInput、note、timedOut。格式化见formatQuestionResult(第 727-739 行)。 - Chat 重定向:
content为 "User chose to chat about this instead of answering.",details为{ chatRedirect: true, questions: string[] }(第 1016-1026 行)。
details 不仅供 Agent 读取,TUI 渲染器也依赖它做富展示:renderResult 会按 results 逐节渲染并填充 radio/checkbox 标记(第 1535-1670 行)。
超时与推荐选项:ask.timeout / ask.notify
ask 的行为受两个设置项控制,定义在 settings-schema.ts:
ask.timeout(第 2396-2412 行):number,默认0(禁用)。单位是秒,运行时换算为毫秒(timeoutSeconds * 1000),预设档位 15/30/60/120 秒。语义是"超时后自动选中推荐选项"。ask.notify(第 2414-2424 行):"on" | "off",默认"on"。为on时,工具等待输入期间发送终端通知 "Waiting for input"(#sendAskNotification,ask.ts 第 856-867 行)。
超时处理的关键逻辑(ask.ts 第 968-973 行、第 183-189 行):
- 从设置读取秒数,
0视为禁用;plan 模式(session.getPlanModeState()?.enabled)下强制禁用超时,避免规划阶段因等待而自动替用户做选择; - 超时触发时:若存在合法
recommended下标则自动选中该项,否则选第一个选项; - 回退模式下,自动选择的结果文本带
(auto-selected after timeout)后缀,且details.timedOut置真——测试 "auto-selects the recommended option on ask timeout"(ask.test.ts 第 185-234 行)验证了这一点,timedOut也会在 TUI 中显示 "auto-selected after timeout — not a user choice" 的注释(第 1657-1660 行),避免与用户真实选择混淆; - 超时检测带 1 秒容差(
TIMEOUT_DETECTION_TOLERANCE_MS),用于区分"UI 在截止点自动关闭"与"用户超时后按 Esc 取消"(第 160-163 行、第 535-542 行)。
如果用户没有在超时前作答,且没有有效推荐项,代码会用第一项兜底(getAutoSelectionOnTimeout,第 183-189 行),即"宁可给一个默认答案,也不让 Agent 卡死"。
约束、错误与安全边界
ask 在并发、输入校验与取消语义上有明确的实现约束:
- 并发独占(exclusive):
AskTool.concurrency = "exclusive",工具批次内只能有它一个。因为 selector/editor 是共享的单一 UI 表面,两个并发 ask 会互相抢占焦点、导致其中一个永久挂起(ask.ts 第 839-844 行的注释对此有详细解释)。 - 权限等级:
approval = "read",loadMode = "discoverable",strict = true——schema 之外的未知字段会被拒绝。 - 运行时校验:
questions为空返回文本错误Error: questions must not be empty(第 978-983 行);id重复、问题内选项标签重复都会返回错误文本(第 929-958 行)。此外模型注入的\r换行会被sanitizeAskParams清洗,清洗后若标签坍缩成保留标签同样 fail-closed(第 884-902 行)。 - 错误路径(docs/tools/ask.md 的 Errors 一节):
- 无交互 UI(headless):
ToolAbortError("Ask tool requires interactive mode"),且会先context.abort()(第 876-880 行); - 用户取消选择:
ToolAbortError("Ask tool was cancelled by the user")(第 1123-1126 行); - 输入期间收到 abort 信号:
ToolAbortError("Ask input was cancelled")(第 1080-1082 行)。所有 UI 等待都包裹在untilAborted(...)中,确保中止信号能打断挂起的对话框。
- 无交互 UI(headless):
- headless 会话:
AskTool.createIf只在有 UI 时注册(第 851-853 行),所以 headless 会话根本不会发现这个工具;若强行执行,会走上面的无 UI 错误路径。这就是提示词要求"能不问就不问"的根本原因。
回放与可追溯:/tree 重新回答
值得一提的细节是 recoverAskQuestions(ask.ts 第 100-104 行):它从持久化的 ask toolCall 参数中恢复 schema 校验过的原始 questions,使 /tree 命令选中历史中的 ask 结果后能重新打开选择器并生成兄弟分支答案(issue #5642),而不是篡改旧记录;畸形或损坏的历史参数会 fail-closed 返回 undefined。这保证了 ask 交互可回放、可追溯,让提问记录成为会话树中的一等公民。
总结:ask 的正确用法
回到模型侧提示词 packages/coding-agent/src/prompts/tools/ask.md 的初衷,ask 的完整使用纪律可以归纳为:
- 先穷尽已有来源(代码、配置、文档、历史),默认行动;
- 仅在方案取舍差异显著、必须用户权衡时才提问;
- 一次打包多个相关问题,选项 2-5 个、标签简短、取舍放
description; - 用
recommended标记默认项、用multi开启多选,不要手写 "Other"; - 理解超时语义:
ask.timeout是"超时自动选推荐项"的安全网,plan 模式下自动关闭。
遵循以上纪律,ask 就能在"不打断 Agent 流畅度"与"关键决策不越权"之间取得平衡——这正是 ask.ts 与 ask.test.ts 这套实现所承载的设计意图。