docs(agents): 完善 Cursor 确认问题与提示音可见性约定

明确工具先于正文时 notify-question 须为本轮最后一次调用，最终回复以「待你确认」打头，并区分 Queued 与确认入口，减少听音找不到题的情况。

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/agents/README.md

@@ -60,6 +60,13 @@ Agent 需要你做决定时，会在当前回复里直接写出「待你确认
 
 完整安装提供 `notify-question` 命令，由 Agent 在提问后调用，不是宿主自动弹窗钩子。当前支持用户 macOS 本机；其他系统或远程执行缺少本地播放条件时回退文字提醒，不代表你已听到。安装、更新、普通进度和结束答复不播放。细则见安装目录 `references/question-notification.md`。
 
+### 在 Cursor 里听到提示音却看不到题时
+
+- 提示音在整机播放，**不会自动跳到对应聊天**；请到正在跑 Agent 的会话里搜索「待你确认」。
+- 输入框上方的 **Queued / Start Multitasking** 是你排队的后续消息，**不是**确认清单。
+- Cursor 会先跑工具再刷出最终正文，声音可能比清单早响一两秒；清单应出现在该轮助手正文开头。多会话并行时，切换其他进行中会话再搜一次。
+- 工程内 Agent 适配约定见 [Cursor 确认可见性](cursor-question-visibility.md)。
+
 ## 日常开发怎么提需求
 
 | 场景 | 可以直接发送的示例 |

docs/agents/cursor-question-visibility.md

@@ -0,0 +1,33 @@
+# 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 下的展示与播音顺序。