oh-my-pi 的 ask 工具:面向交互式编码 Agent 的澄清提问工具设计指南

原创2026-09-11 19:23:532,277 阅读
文章标签:代码智能体AI Agent人工智能大模型CLI开发工具工具调用

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 行):

  1. 富 ask 对话框:当 context.ui 提供 askDialog API 时,一次打开一个多问题表单。header、description、preview 都会在富形态中呈现;用户可以为答案附加 note,或选择对话框的 "Chat about this" 重定向。富形态对返回值有强校验:结果数量、id、顺序任一不匹配都会抛 Error(第 1028-1037 行)。
  2. 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 行):

  1. 从设置读取秒数,0 视为禁用;plan 模式(session.getPlanModeState()?.enabled)下强制禁用超时,避免规划阶段因等待而自动替用户做选择;
  2. 超时触发时:若存在合法 recommended 下标则自动选中该项,否则选第一个选项;
  3. 回退模式下,自动选择的结果文本带 (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 行),避免与用户真实选择混淆;
  4. 超时检测带 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(...) 中,确保中止信号能打断挂起的对话框。
  • 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 的完整使用纪律可以归纳为:

  1. 先穷尽已有来源(代码、配置、文档、历史),默认行动;
  2. 仅在方案取舍差异显著、必须用户权衡时才提问;
  3. 一次打包多个相关问题,选项 2-5 个、标签简短、取舍放 description;
  4. 用 recommended 标记默认项、用 multi 开启多选,不要手写 "Other";
  5. 理解超时语义:ask.timeout 是"超时自动选推荐项"的安全网,plan 模式下自动关闭。

遵循以上纪律,ask 就能在"不打断 Agent 流畅度"与"关键决策不越权"之间取得平衡——这正是 ask.ts 与 ask.test.ts 这套实现所承载的设计意图。

登录后查看全文
oh-my-pi