AI agent skill · by @JasonxzWen

Decision Ui

Load when Codex 即将要求用户在 2-3 个互斥方案中做真实决定、准备询问阻塞性澄清问题或需要确认高影响取舍；将选择转换为宿主原生可点击 UI，并在工具不可用时诚实文本回退。不要用于低风险实现细节、只有一个合理答案的问题、普通信息采集或不需要用户决策的完成汇报。

Archived 2026-10-23 · Source updated 2026-07-23. Check the original repository for the latest version.

SKILL.md instructions

# 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 交互应满足：

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