Decision ui

Decision UI for Codex

Goal

把真正需要用户判断的选择做成原生交互控件，同时保持 Agent 的执行自主性。不要把 Markdown 列表伪装成按钮，也不要为了展示 UI 而制造无意义的决策。

Decision Gate

先判断是否真的需要用户选择。仅在答案会实质改变以下至少一项时停下来询问：

• 用户可见的结果、范围或优先级
• 风险、成本、不可逆性或外部影响
• 缺失且无法从现有上下文发现的个人偏好
• 后续存在两个以上同样合理、但不能同时执行的方向

遇到以下情况时直接做出合理假设并继续：

• 低风险、可逆的实现细节
• 可以从仓库、文件、工具状态或既有约定中查明的事实
• 一个方案明显优于其他方案，且不会扩大用户授权范围
• 只是想在完成汇报末尾例行添加“下一步”菜单

Native Choice Workflow

1. 确认当前宿主是否提供结构化用户输入工具，例如 request_user_input。
2. 工具可用时直接调用，不要先输出编号菜单，也不要要求用户回复 1/2/3。
3. 默认一次只提出一个决策；只有问题彼此独立且合并能明显减少往返时，才在一次调用中提出多个问题。
4. 每个问题只提供 2-3 个互斥、可执行的选项。
5. 把有证据支持的推荐项放在第一位，并在标签后标记 (Recommended)。
6. 用一句话说明每个选项的影响或取舍；不要只换一种说法重复标签。
7. 依赖客户端提供自由输入的 Other 选项，不要手工再添加一个“其他”。
8. 收到选择后立即恢复原任务，把结构化答案当作用户明确输入，不要重复确认同一决定。

遵守宿主工具的字段限制。对于 Codex 当前的 request_user_input，保持：

• header 不超过 12 个字符
• question 为一个清晰句子
• 选项标签为 1-5 个词
• 选项描述为一个短句

Blocking And Non-Blocking Choices

对于会阻塞执行的决定，调用原生选择工具并等待用户回答，不设置自动继续超时。

对于仅能改善结果、但不值得阻塞的补充偏好，仅在工具明确支持自动解析时使用其非阻塞或超时机制；推荐项必须同时是超时后的安全默认值。工具不支持时，采用合理默认值继续，并在结果中简短说明假设。

完成答案后的可选后续动作不等同于阻塞性决策：

• 宿主提供专用的 clickable follow-up action 能力时，优先使用它。
• 只有 request_user_input 时，不要为了显示按钮而把已完成任务重新变成阻塞问答。
• 没有原生 follow-up 能力时，只说明一个最值得做的下一步；不要再输出让用户回复数字的菜单。

Choice Quality

• 让选项覆盖真实分叉，不要把“同意建议”拆成多个措辞相近的选项。
• 优先描述结果，而不是内部实现名词；用户需要知道选择后会发生什么。
• 推荐必须来自当前证据、约束和目标，不要机械地把第一项称为推荐。
• 能问“选择结果”时，不要退化成抽象的“是否继续”。
• 涉及外部写入、公开发布、费用、删除或不可逆操作时，保留明确确认，不使用自动解析。

Fallback

结构化选择工具不可用时：

1. 明确说明当前宿主无法渲染原生选择控件。
2. 用一个短问题加 2-3 个项目符号提供同样的互斥选项。
3. 让用户回复选项名称，不要求只回复数字。
4. 不输出自定义 fenced JSON、HTML 按钮或未经宿主支持的伪协议。

不要声称文本列表是可点击的，也不要为了逃避工具不可用而替用户做高影响决定。

Quality Bar

一次合格的 Decision UI 交互应满足：

• 只有真实、重要的分叉才打断用户
• 用户看到原生可点击选项，而不是编号文本替代品
• 推荐项及其代价清楚可见
• 选项互斥且选择后能直接继续执行
• 工具不可用时诚实回退，不伪造交互能力