zkxw/docs/agents/cursor-question-visibility.md

Cursor 宿主：确认问题可见性

个人开发体系要求：先在用户可见回复写出「待你确认」，再播放本机提示音。Cursor Agent 的执行顺序与此不完全同构，本文件是工程内的 Cursor 适配约定；与安装目录 references/planning.md、references/question-notification.md 并用，冲突时以「用户必须先看见清单」为准。

Cursor 执行顺序

1. 同轮内的工具调用先执行，最终助手正文后出现。
2. notify-question（afplay）若作为工具调用，提示音可能比「待你确认」正文早数秒响起。
3. 提示音在整机播放，不绑定当前聚焦的聊天标签；多会话并行时，声音来源会话可能不是眼前这个。
4. 输入框上方的 Queued / Start Multitasking 是用户排队的后续消息，不是 Agent 确认清单。

Agent 必须遵守

发问当轮：

1. 先写清单：该轮最终用户可见回复必须以「待你确认」开头（或紧接一句定位后立刻出现该标题），按问题展示规则写全题、推荐、理由与未回复处理。
2. 同轮停手：写出清单并（如需）播放提示音后，本轮不得再调用编辑、浏览器、继续实现等工具；依赖答复的工作等下一轮。允许的独立只读工作若与本题无关，应在发问之前做完，或放到用户答复之后。
3. 提示音时机：需要播放时，notify-question 必须是本轮最后一次工具调用，且本轮最终正文就是确认清单。禁止在仍计划继续工具批处理时提前播放。
4. 正文定位：清单首段或标题下用一句说明「请在本会话回复；提示音不念题目，底部 Queued 不是确认入口。」
5. 无清单不播放：最终正文没有「待你确认」时，不得调用 notify-question。
6. 原生卡片：若当前 Cursor 会话提供宿主提问/确认卡片，可与清单并用，卡片内容须与「待你确认」一致；不得只用卡片、省略正文清单。

用户侧核对

听到「有问题待确认」时：

1. 看正在或刚结束工具步骤的那个聊天（不必先看 Queued）。
2. 在该会话搜索或上翻 「待你确认」；清单在工具时间线收折块之外的助手正文里。
3. 若多聊天并行，切换到其他进行中会话再搜同一标题。

静音与一分钟策略

声音开关、一分钟默认选择仍按安装目录规则；本文件不改变其语义，只约束 Cursor 下的展示与播音顺序。