From db74cd64fe3592ce08dcbd4a9c687cd4aa4d18fa Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Wed, 11 Nov 2026 10:38:20 +0800 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E5=AE=8C=E5=96=84=20Cursor=20?= =?UTF-8?q?=E7=A1=AE=E8=AE=A4=E9=97=AE=E9=A2=98=E4=B8=8E=E6=8F=90=E7=A4=BA?= =?UTF-8?q?=E9=9F=B3=E5=8F=AF=E8=A7=81=E6=80=A7=E7=BA=A6=E5=AE=9A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 明确工具先于正文时 notify-question 须为本轮最后一次调用，最终回复以「待你确认」打头，并区分 Queued 与确认入口，减少听音找不到题的情况。 Co-authored-by: Cursor --- .agents/skills/personal-dev/SKILL.md | 2 +- .../personal-dev/references/planning.md | 8 +++++ .../references/question-notification.md | 3 +- .cursor/rules/personal-dev.mdc | 12 +++++-- docs/agents/README.md | 7 ++++ docs/agents/cursor-question-visibility.md | 33 +++++++++++++++++++ 6 files changed, 60 insertions(+), 5 deletions(-) create mode 100644 docs/agents/cursor-question-visibility.md diff --git a/.agents/skills/personal-dev/SKILL.md b/.agents/skills/personal-dev/SKILL.md index ea9ad2f5..aee0ec25 100644 --- a/.agents/skills/personal-dev/SKILL.md +++ b/.agents/skills/personal-dev/SKILL.md @@ -19,7 +19,7 @@ description: Use when starting a project, designing or prototyping project UI, i | 任务 | 读取 | | --- | --- | | 工单领取、并行会话、流程标签、转交、共享环境或合并排队 | [工单占用与隔离](references/issue-claims.md) | -| 发送确认问题、请求用户操作、补发缺推荐或缺超时说明的旧题 | 先按[问题展示](references/planning.md#问题展示)在当前回复写出「待你确认」，完成[发问前检查](references/planning.md#发问前检查)后，再按[本地确认语音](references/question-notification.md)提醒 | +| 发送确认问题、请求用户操作、补发缺推荐或缺超时说明的旧题 | 先按[问题展示](references/planning.md#问题展示)与 Cursor 宿主节在当前回复写出「待你确认」，完成[发问前检查](references/planning.md#发问前检查)后，再按[本地确认语音](references/question-notification.md)提醒；Cursor 下 `notify-question` 须为本轮最后一次工具且发问后停手 | | 关闭/恢复声音提醒 | [本地确认语音](references/question-notification.md) | | 空白工程、大需求、技术栈或架构变化 | [建设与规格](references/planning.md) | | 拉取工单、理解评论和截图、续接工单或交付前核对补充 | [工单全文、评论与图片](references/issue-context.md) | diff --git a/.agents/skills/personal-dev/references/planning.md b/.agents/skills/personal-dev/references/planning.md index 06c51a71..96cfee43 100644 --- a/.agents/skills/personal-dev/references/planning.md +++ b/.agents/skills/personal-dev/references/planning.md @@ -43,6 +43,14 @@ 必须等待的题，最后一行写「未回复时：本题保持等待。」宿主问题卡片可以同时使用，卡片内容与这份清单一致。回复正文里没有「待你确认」时，不播放提示音，也不开始 60 秒计时。 +### Cursor / 工具先于正文的宿主 + +Cursor Agent 等同轮「先跑工具、再出最终回复」的宿主上： + +1. 需要播音时，`notify-question` 只能作为本轮**最后一次**工具调用；最终可见回复必须以「待你确认」开头写全清单，本轮随后不得再编辑代码、开浏览器或继续依赖答复的实现。 +2. 承认提示音可能早于正文渲染数秒；用清单内一句「请在本会话回复；Queued 不是确认入口」消除错位。提示音整机可听，不保证当前聚焦会话就是发问会话。 +3. 工程若提供宿主适配说明（如 `docs/agents/cursor-question-visibility.md`），发问前按该说明执行；与本节冲突时以「用户必须看见清单」为准。 + ## 发问前检查 每次发送确认问题（含调用宿主提问工具）前，逐题完成以下检查；缺项先改题，再按[问题展示](#问题展示)写入当前回复。这里是 Agent 的执行步骤，尚无自动拦截宿主问题卡片的校验器。 diff --git a/.agents/skills/personal-dev/references/question-notification.md b/.agents/skills/personal-dev/references/question-notification.md index 44cc65bc..0fec4114 100644 --- a/.agents/skills/personal-dev/references/question-notification.md +++ b/.agents/skills/personal-dev/references/question-notification.md @@ -6,7 +6,8 @@ 1. 先核对用户/工程的静音选择。当前回复已经写上「待你确认」清单后，记录该批问题的发送时间、推荐及范围，再播放。回复里还没有这份清单时不播放，也不把这一轮当作已经发问。 2. 每批问题只播放一次，多题合并发送共用一次提醒。将“已尝试提醒/结果”记在现有任务记录；同一批等待、轮询、重试和会话恢复不重复播放。真正重新提出的新问题或用户要求再提醒时才播放下一次。 -3. 执行以下已安装入口。它只读取随包预生成的本地 WAV，并调用播放器；不联网、不调用语音生成服务、不在提问时临时生成语音。命令最多等待播放器 12 秒，不另开后台常驻进程。 +3. **Cursor 等「工具先于最终正文」的宿主**：不得在仍要继续工具批处理时播放。需要播放时，将 `notify-question` 放在本轮最后一次工具调用，并保证同轮最终正文以「待你确认」清单为主体且本轮停手。提示音在整机播放、不绑定聊天标签；Queued/Multitasking 队列不是确认入口。工程适配见 `docs/agents/cursor-question-visibility.md`（若存在）。 +4. 执行以下已安装入口。它只读取随包预生成的本地 WAV，并调用播放器；不联网、不调用语音生成服务、不在提问时临时生成语音。命令最多等待播放器 12 秒，不另开后台常驻进程。 ```sh python3 .agents/skills/personal-dev/scripts/pda.py notify-question --project . diff --git a/.cursor/rules/personal-dev.mdc b/.cursor/rules/personal-dev.mdc index aa92af02..b9165dec 100644 --- a/.cursor/rules/personal-dev.mdc +++ b/.cursor/rules/personal-dev.mdc @@ -1,8 +1,14 @@ --- -description: 个人开发体系的工程任务入口 +description: 个人开发体系的工程任务入口（含 Cursor 确认可见性） alwaysApply: true --- -工程建设、界面设计或原型、需求开发、Bug 修复、验收反馈或提交/push/合并续聊时，先读根 AGENTS.md，再读取工程根目录的 .agents/skills/personal-dev/SKILL.md 进行任务分级。仅咨询概念时直接回答。业务约束仍按目标目录的 AGENTS.md 查阅。 +工程建设、界面设计或原型、需求开发、Bug 修复、验收反馈或提交/push/合并续聊时，先读根 `AGENTS.md`，再读取工程根目录的 `.agents/skills/personal-dev/SKILL.md` 进行任务分级。仅咨询概念时直接回答。业务约束仍按目标目录的 `AGENTS.md` 查阅。 -需要用户确认时，先在当前回复写出「待你确认」清单，再播放提示音。清单的写法以该 Skill 的问题展示规则为准。回复里没有这份清单时，不播放提示音。 +需要用户确认时： + +1. 先读 [Cursor 确认可见性](../../docs/agents/cursor-question-visibility.md)，再按 Skill 的问题展示规则发问。 +2. 本轮最终用户可见回复必须以「待你确认」清单为主体（含推荐与未回复处理）；写完清单前不播放提示音。 +3. 若播放提示音：`notify-question` 必须是本轮最后一次工具调用，且本轮随后不再继续编辑/浏览器/实现类工具。 +4. 清单中写明请在本会话回复；底部 Queued / Multitasking 不是确认入口。 +5. 回复正文没有「待你确认」时，不播放提示音。 diff --git a/docs/agents/README.md b/docs/agents/README.md index a1247764..ba9a2da5 100644 --- a/docs/agents/README.md +++ b/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)。 + ## 日常开发怎么提需求 | 场景 | 可以直接发送的示例 | diff --git a/docs/agents/cursor-question-visibility.md b/docs/agents/cursor-question-visibility.md new file mode 100644 index 00000000..c494e96f --- /dev/null +++ b/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 下的展示与播音顺序。