小爱丽丝官网

Appearance

2026-08-23
1691
6m

AI 对话完成后的标题与浏览器通知设计 ​

1. 目标 ​

在 VitePress 文档站的单一 AI 聊天框中，当一轮 AI 回复自然完成后立即提醒用户：标题切换为完成提示；当用户没有聚焦当前页面时，在用户已授权的前提下发送浏览器系统通知。用户返回页面或点击通知后，标题恢复为当前页面标题。

本次仅覆盖 MVP 的单一聊天会话，不设计多会话计数、并行对话、Service Worker 或移动端系统通知。

2. 已确认的用户体验 ​

2.1 完成判定 ​

只有 AI 流式响应自然成功结束，并产生本轮助手消息时，才算完成。

以下情况不算完成：

  • 用户主动停止请求；
  • 请求失败或进入错误状态；
  • 没有产生新的助手回复。

2.2 标题行为 ​

  • 完成后立即将浏览器标题切换为 AI 回复已完成｜小爱丽丝官网。
  • 当前 MVP 只有一个聊天会话，不维护超过 1 的未读数字。
  • 用户重新聚焦页面、页面重新可见或点击系统通知后，恢复 VitePress 当前页面的原始标题。
  • 页面标题切换必须使用 VueUse useTitle。

2.3 系统通知行为 ​

  • 聊天面板提供“开启回复通知”入口，权限申请只能由用户点击触发。
  • 仅在 Notification.permission === "granted"，且页面不可见或窗口未聚焦时发送系统通知。
  • 通知标题为 小爱丽丝官网，正文为 AI 已完成回复，点击返回继续查看。。
  • 通知图标使用站点现有 favicon，通过 VitePress 客户端等价的 import.meta.env.BASE_URL 路径解析（主题层若注入 withBase("/favicon.svg") 也必须保持同一结果），以支持非根路径部署。
  • 用户点击通知时，尝试聚焦当前页面并清除标题提醒；浏览器不支持聚焦时静默降级。
  • 用户拒绝授权后不循环申请权限，入口改为说明需在浏览器站点设置中手动开启；标题提醒仍然有效。
  • 不支持 Notifications API、非安全上下文或不适合直接构造通知的运行环境时，保持无通知的静默降级，不阻断聊天。

3. 技术设计 ​

3.1 模块边界 ​

在 packages/ai-vitepress-plugins 中新增客户端注意力提醒组合式函数，负责：

  • VueUse useTitle 的标题状态切换与恢复；
  • 通知能力检测、权限状态读取与用户手势授权；
  • 页面可见性与窗口焦点判断；
  • favicon 地址解析；
  • 通知点击后的聚焦与提醒清理。

AiChatVitePressShell.vue 负责将聊天完成事件连接到该组合式函数，并展示授权入口。useKnowledgeChat 负责识别自然完成，不把通知逻辑放入通用 ai-vue 组件。

3.2 SSR 与生命周期 ​

useTitle、document、window 和 Notification 只在客户端使用。组合式函数必须在 VitePress 客户端挂载边界内初始化，并在卸载时移除 visibilitychange、focus、blur 等监听器。服务端渲染不能读取浏览器对象。

3.3 完成事件 ​

useKnowledgeChat 增加可测试的自然完成通知边界。完成事件必须具备本轮请求隔离，不能把上一轮助手消息或停止请求误判为本轮完成。错误和停止路径应保留现有聊天内容与状态，不触发完成提醒。

3.4 现有组件的接入约束 ​

当前 AiChatFloatingButton 和 AiChat 没有通知控制入口或插槽，因此不能只修改 VitePress 壳组件就完成“聊天面板内授权”。实施时需要给通用聊天 UI 增加最小的展示扩展（优先使用可选插槽或等价的无业务耦合入口），由 VitePress 壳注入授权按钮和拒绝说明；通知权限、标题和完成判定仍不得下沉到通用 ai-vue 组件。

完成事件不能仅通过 isResponding 从 true 变为 false 推断，因为停止请求也会产生相同状态变化。必须在发送边界记录本轮请求、停止标记和新助手消息，并在自然成功结束后只触发一次回调。

标题恢复不能永久依赖首次挂载时捕获的字符串。VitePress 客户端路由可能在提醒期间改变页面标题；恢复逻辑需要使用当前路由标题或 VueUse useTitle 的原始标题恢复机制，并覆盖“提醒期间发生页面导航”的测试。

4. 测试与验收 ​

4.1 自动化测试 ​

使用 Vitest 的 describe 与 test，测试文件放在 packages/ai-vitepress-plugins/src/tests/，覆盖：

  • 自然完成触发一次完成事件；
  • 用户停止不触发完成事件；
  • 请求错误不触发完成事件；
  • 完成后标题立即切换；
  • 页面重新可见或获得焦点后标题恢复；
  • 未聚焦且已授权时发送通知；
  • 页面聚焦时不发送系统通知；
  • 拒绝权限时不重复申请；
  • 通知点击尝试聚焦并清除提醒；
  • SSR 或不支持通知时安全降级。

4.2 构建与浏览器验收 ​

  • @ruan-cat-drill-doc/ai-vitepress-plugins 测试和类型检查通过；
  • VitePress 文档站构建通过；
  • 浏览器自测统一使用 agent-browser CLI，并先读取其 core skill；通过受控本地 data-stream 响应驱动真实页面交互，确认授权入口、标题切换、页面聚焦规则、favicon 通知图标和通知点击行为；不把真实 embeddings、Neon、模型或生产 /v1/chat 作为本次前端验收前置条件。
  • 使用 agent-browser snapshot、get title、click、wait 等命令记录可复现证据；测试结束执行 agent-browser close，不遗留浏览器会话或 CLI 进程。
  • 页面验收必须覆盖聊天面板打开后的真实授权入口；只验证悬浮按钮或只读取构建产物，不足以证明权限入口已接入。

5. 风险与明确不做事项 ​

  • 浏览器和操作系统可能限制 SVG 通知图标的显示，代码使用站点 favicon，但最终图标外观以浏览器实际行为为准。
  • 本次不保证移动浏览器直接构造 Notification 的体验，不引入 Service Worker 作为补偿方案。
  • 本次不改变后端 API，不改通用 AI 聊天组件的完成渲染协议，不实现多窗口或多聊天会话的未读计数。
  • 本次受控浏览器验收不能替代 OpenSpec ai-rag-phase2 的真实 embedding、检索、模型装配或生产浏览器回归任务。

贡献者

The avatar of contributor named as ruan-cat ruan-cat

页面历史

最近更新