decision-uilisted

# 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