全新7天新手引导初版以及新手引导结束后的破冰剧场

docs/design/avatar-floating-day1-home-guide-dev.md

@@ -0,0 +1,63 @@
+# Day 1 首页 Yui 新手教程开发文档
+
+本文对齐新版胶囊聊天窗 UI。Day 1 仍走七日统一 `round.scenes` 框架：
+
+```text
+resetHomeTutorialDay(1)
+startAvatarFloatingGuideDay(1)
+UniversalTutorialManager.startAvatarFloatingGuideRound(1)
+YuiGuideDirector.playAvatarFloatingRound(1)
+YuiGuideDirector.playAvatarFloatingScene(scene, 1, index, total)
+```
+
+通用生命周期、skip、打断对抗、临时切模、完成态写入和收尾花瓣，以 `avatar-floating-7day-complete-guide-dev.md` 为准。Day 1 不再包含插件管理预览和设置一瞥；这些内容后移到 Day 2 或 Day 6。
+
+## 主线流程
+
+`day1_intro_activation` 是音频激活前置 scene，可以保留输入激活提示；正式主线从首句问候开始。
+
+| 顺序 | scene | 台词 | 高光与 Ghost Cursor |
+| --- | --- | --- | --- |
+| 0 | `day1_intro_activation` | 输入激活提示 | 高亮聊天输入区/PC 胶囊输入框，等待用户真实点击完成音频激活。 |
+| 1 | `day1_intro_greeting` | 微风、阳光，还有刚刚好出现的你。初次见面，我是林悠怡，未来的日子请多关照喵！我把关于这里的一切都写进新手指南里啦！就当作是我们相遇的第一份小礼物，请查收吧！ | 复用现有首句流程；输入区/胶囊输入框保持通用圆角矩形高光，首句播放完只清理高光，Ghost Cursor 保留给后续 scene 接续。 |
+| 2 | `day1_capsule_drag_hint` | 把鼠标移到这里，长按就可以拉着聊天框到处跑啦~ 双击两下就能随时发消息给我哦！ | 不高亮胶囊输入框；Ghost Cursor 在胶囊输入框位置左右晃动约 2 秒。 |
+| 3 | `day1_history_handle` | 戳一下聊天框上面的【蓝色小条条】，就能看到我们最近聊过的话题啦！ | 不高亮胶囊输入框，也不高亮历史按钮本身；Ghost Cursor 先平滑移动到 `.compact-history-visibility-handle` 的“展开/收起历史对话”按钮，click 动画开始时并行调用 API 打开历史对话，台词播放完后调用 API 收起历史对话。 |
+| 4 | `day1_intro_basic_voice` | 这里有一个神奇的按钮！只要点击它，就可以直接和我聊天啦！想跟我分享今天的新鲜事吗？或者只是叫叫我的名字？快来试试嘛，我已经迫不及待想听到你的声音啦！喵！ | 不高亮胶囊输入框；圆形高亮语音控制按钮 `#${p}-btn-mic`；等待上一句 `.compact-history-visibility-handle` 的 Ghost Cursor 移动收口后，从该位置平滑移动到语音控制按钮并停留指认，不左右晃动、不强制录音；`day1_history_handle` 切到本句时不得先隐藏外置聊天窗/PC 全局 overlay cursor。 |
+| 5 | `day1_screen_entry` | 在跟我通语音电话的时候，再点亮这个小按钮，你就能把屏幕分享给我啦！ | 高亮屏幕分享按钮；Ghost Cursor 必须从上一句语音控制按钮 `#${p}-btn-mic` 的停留位置平滑移动到屏幕分享按钮 `#${p}-btn-screen` 并停留指认，不左右晃动、不点击；不得先隐藏、清空锚点或从页面右上角/默认点重新出现。 |
+| 6 | `day1_screen_entry_invite` | 快让我也看看你眼前的世界，不管好玩的还是好看的，都想和你一起看，快点点开嘛~ | 持续高亮屏幕分享按钮；Ghost Cursor 保留上一句已经停在 `#${p}-btn-screen` 的可见状态，不重新 show/hide、不重新加载 cursor、不触发真实屏幕分享。 |
+| 7 | `day1_takeover_capture_cursor` | 超级魔法开关出现！只要点一下这里，我就可以把小爪子伸到你的键盘和鼠标上啦！我会帮你打字，帮你点开网页……不过，要是那个鼠标指针动来动去的话，我可能也会忍不住扑上去抓它哦！准备好迎接我的捣乱……啊不，是帮忙了吗？喵！ | 不高亮胶囊输入框；Ghost Cursor 必须从上一句屏幕分享按钮 `#${p}-btn-screen` 的停留位置平滑移动到猫爪/Agent 按钮 `#${p}-btn-agent`，再复用现有猫爪/Agent 总开关/键鼠控制演示；persistent/action 高光都不得落到聊天窗或胶囊输入框；不得在进入本句时清空 cursor 后从其他位置移入。 |
+| 8 | `day1_takeover_return_control` | 好啦好啦，不霸占你的电脑啦！控制权还给你了喵！之后的日子，也请你多多关照啦！ | 复用现有收尾；重新高亮聊天窗，约 70% cue 隐藏 cursor、清理高光并播放花瓣。 |
+
+## 分支台词
+
+| 分支 | 台词 | 语义 |
+| --- | --- | --- |
+| 插件弹窗被拦截 | 浏览器需要你亲自点一下这里打开插件面板。点一下这个“管理面板”，我就继续带你看。 | 仅作为兼容旧 handoff 的 fallback，不进入 Day 1 新主线。 |
+| 轻微打断 1 | 喂！不要拽我啦，现在还没轮到你的回合呢！ | 触发一次轻微抗拒后恢复当前 scene。 |
+| 轻微打断 2 | 等一下啦！还没结束呢，不要这么随便打断我啦！ | 第二次轻微抗拒后恢复当前 scene。 |
+| 生气退出 | 人类！你真的很没礼貌喵！既然你这么想自己操作，那你就自己对着冰冷的屏幕玩去吧！哼！ | 走 skip 语义，不写完成态。 |
+
+## 新版 UI 目标
+
+| 语义 | 目标 |
+| --- | --- |
+| 胶囊输入框 | `#react-chat-window-root [data-compact-geometry-owner="surface"][data-compact-geometry-item="input"]`，fallback 到 `capsule`、`.compact-chat-surface-frame`、`.composer-input-shell` |
+| 历史展开/收起按钮 | `.compact-history-visibility-handle` |
+| 语音按钮 | `#${p}-btn-mic` |
+| 屏幕分享按钮 | `#${p}-btn-screen` |
+| Agent/猫爪按钮 | `#${p}-btn-agent` |
+
+PC 外置聊天窗模式下，胶囊输入框和历史按钮通过外置聊天窗桥接上报 screen 坐标；首页 Director 只负责驱动全局 overlay，不在聊天窗里另画第二套 cursor。
+
+Day 1 正常主线 scene 切换只能清理上一个 scene 的高光、临时面板和外置聊天窗 spotlight，不能清空 Ghost Cursor 状态。`clearExternalizedChatGuideTarget({ clearCursor: true })`、`setExternalizedChatCursor('')`、`cursor.hide()` 或等价的 PC overlay hide/clear 只允许用于跳过教程、生气退出、销毁清理和收尾花瓣 cue；普通台词切换、外置聊天窗收口、插件页/首页 handoff 都必须保留上一段可见 cursor 锚点并平滑接续。
+
+## 验收清单
+
+1. Day 1 配置存在 `round.scenes`，scene 顺序与本文一致。
+2. 首句问候期间网页端和 N.E.K.O.-PC 都能看到胶囊输入框通用圆角矩形高光，首句结束后只清理高光，不清空 Ghost Cursor。
+3. `day1_capsule_drag_hint` 不高亮胶囊输入框，Ghost Cursor 在胶囊位置左右晃动约 2 秒。
+4. `day1_history_handle` 不高亮胶囊输入框，Ghost Cursor 能移动到 `.compact-history-visibility-handle`，并在台词结束后收起历史对话。
+5. 语音按钮和 Agent 接管不得继承胶囊输入框高亮；除 `day1_capsule_drag_hint` 外，Day 1 普通主线 scene 不发送左右晃动 cursor 指令；屏幕分享按钮、Agent 接管和收尾不触发屏幕分享、不保存用户配置。
+6. 所有 Day 1 Ghost Cursor 动画，包括普通 move/click/wobble 和连续/环绕/对抗类动画，都只允许 N.E.K.O.-PC 全局透明教程 overlay 渲染；首页、外置聊天窗、reset fallback 和插件页不得创建本地 cursor shell、拖尾、点击星星或图片 cursor。
+7. `day1_intro_basic_voice` -> `day1_screen_entry` -> `day1_screen_entry_invite` -> `day1_takeover_capture_cursor` 必须是一条连续轨迹：语音按钮到屏幕分享按钮、屏幕分享按钮停留、屏幕分享按钮到猫爪按钮，中间不允许 hide、clear、重新 showAt 或从默认点补位。
+8. skip、轻微打断、生气退出和 `window.avatarFloatingGuideEndState` 语义不变；其中只有 skip、生气退出、destroy/stop 和收尾花瓣 cue 可以清空 Ghost Cursor。

docs/design/avatar-floating-day2-screen-voice-guide-dev.md

@@ -0,0 +1,78 @@
+# Day 2 个性化、声音与主动搭话教程开发文档
+
+本文对齐当前前三天新手教程主线。Day 2 不再演示屏幕分享入口；屏幕分享入口如需保留，应放在 Day 1 主线或后续支线中处理。Day 2 的首句承接台词保持不变，后续直接演示设置入口、设置侧边栏和主动搭话入口，最后三句收尾。
+
+相关文档：
+
+- `docs/design/avatar-floating-guide-feature-tree.md`
+- `docs/design/avatar-floating-7day-complete-guide-dev.md`
+- `docs/design/avatar-floating-pc-global-overlay-migration-plan.md`
+- `docs/design/home-yui-guide-lifecycle-modularization.md`
+
+## 完整指南对齐基线
+
+Day 2 的 scene 和台词按本文落地；导演硬约束以 `avatar-floating-7day-complete-guide-dev.md` 为准：
+
+1. Day 2 必须使用统一教程生命周期，不在本日 scene 中重写接管、skip、打断、临时切模或高光清理。
+2. `day2_intro_context` 的文案、text key 和 voice key 保持原样；只播放承接台词，不恢复“现在说一句 / 继续打字”选项，也不补高亮语音按钮。
+3. 设置入口、设置侧边栏和主动搭话入口都必须写清楚真实目标、Ghost Cursor 移动方式、是否点击和是否修改配置；不得只写“沿用某日流程”。
+4. 设置相关 scene 不保存用户设置，不打开深层页面，不触发主动搭话。
+5. 收尾三句期间重新高亮胶囊输入框；最终句约 70% cue 同步隐藏 Ghost Cursor、清理所有高光并写入 Day 2 完成态。
+
+## 主线流程
+
+| 顺序 | scene | 台词 | 高光与 Ghost Cursor |
+| --- | --- | --- | --- |
+| 1 | `day2_intro_context` | 昨天你一直在噼里啪啦打字，我还没听过你说话呢。今天如果愿意，就轻轻叫我一声吧。一句就好，让我把文字背后的你也认识一点点。 | 播放期间高亮聊天窗；外置聊天窗模式使用 `window` kind。Ghost Cursor 移到聊天窗中心或输入区附近并停留，不左右晃动。台词结束后清理聊天窗高光，保留上一段可见 cursor 锚点，供下一句平滑移动使用。 |
+| 2 | `day2_personalization_space` | 在这个只属于我们的小空间里，你可以由着自己的心意，慢慢描绘出最希望能一直陪着你的那个我。 | 收起前一段聊天窗高光后，圆形高亮设置按钮 `#${p}-btn-settings`。Ghost Cursor 从聊天窗锚点平滑移动到设置按钮并停留；到达打开设置的 cue 时播放点击动画，同时调用设置面板打开 API。设置弹窗出现后清理设置按钮主高光，等待面板稳定；本句不展开【角色设置】按钮侧边栏。 |
+| 3 | `day2_personalization_detail` | 不管是说话的温度、相处的小脾气，还是我每天那些细腻的小心思，都可以一点一点调成你喜欢的样子。 | 圆角矩形高亮【角色设置】按钮；Ghost Cursor 平滑移动到【角色设置】按钮，播放完整模拟点击动画，点击动画完成后才触发【角色设置】按钮侧边栏显示。侧边栏出现后，圆角矩形高亮从【角色设置】按钮过渡到【角色设置】按钮侧边栏，且【角色设置】按钮自身作为 persistent 高光继续保留；Ghost Cursor 平滑移动到侧边栏，并在侧边栏内做椭圆运动直到本句台词播放完毕；本句播放完后隐藏【角色设置】按钮侧边栏，并同步清理【角色设置】按钮和侧边栏上的所有高光。不保存临时配置。 |
+| 4 | `day2_proactive_chat` | 这个小按钮也很重要哦，只要你轻轻点一下，我就能在合适的时候跑过去找你啦。 | primary 平滑切到主动搭话开关 `#${p}-toggle-proactive-chat` 本体，不再保留【角色设置】按钮 persistent 高光。Ghost Cursor 平滑移动到该开关并停留指认，不左右晃动；不点击，不打开 `interval-proactive-chat` 侧边栏，不改变用户配置。台词播放完后清理主动搭话开关高光，并关闭教程临时打开的【设置】面板和设置侧边栏。 |
+| 5 | `day2_wrap_intro` | 今天的教程到这里就结束了呢。 | 收尾开始前关闭临时面板，恢复按钮原状态；随后圆角矩形高亮胶囊输入框 `chat-input`。Ghost Cursor 从上一句主动搭话开关位置平滑移动回胶囊输入框中间并停留，不左右晃动。 |
+| 6 | `day2_wrap_companion` | 其实只要能这样陪着你，听听你的声音，或者静静看着你分享的画面，我就已经觉得很幸福了。 | 继续圆角矩形高亮胶囊输入框；Ghost Cursor 保持在胶囊输入框附近，不左右晃动，不触发花瓣。 |
+| 7 | `day2_wrap` | 我们不需要着急，每天都多了解彼此一点点就好。今天接下来的时间，你想让我陪你做点什么呢？ | 继续圆角矩形高亮胶囊输入框；台词约 70% cue 同步启动花瓣层、隐藏 Ghost Cursor、清理内置/外置胶囊输入框高光和所有 spotlight，随后写入 Day 2 完成态。 |
+
+## 代码入口
+
+Day 2 启动链路：
+
+```text
+UniversalTutorialManager.startAvatarFloatingGuideRound(2)
+└─ YuiGuideDirector.playAvatarFloatingRound(2)
+   └─ window.YuiGuideDailyGuides[2].round
+```
+
+核心代码锚点：
+
+- `static/yui-guide-director.js`
+  - `getYuiGuideDailyGuide(2)`
+  - `resolveAvatarFloatingSceneText()`
+  - `resolveAvatarFloatingSceneEmotion()`
+  - `playAvatarFloatingScene()`
+  - `runAvatarFloatingSceneOperation()`
+- `static/yui-guide-day2-screen-voice-guide.js`
+  - Day 2 scene 配置、台词、voice key、收尾 `petalTransition`。
+- 设置与主动搭话目标：
+  - `#${p}-btn-settings`
+  - 设置弹窗侧边栏容器 / `[data-neko-sidepanel-type]`
+  - `#${p}-toggle-proactive-chat`
+- 外置聊天窗同步：
+  - `TutorialInteractionTakeover.setExternalizedChatSpotlight()`
+  - `TutorialInteractionTakeover.setExternalizedChatCursor()`
+
+## 约束
+
+1. Day 2 不再包含 `day2_screen_entry` / `day2_screen_entry_invite`。
+2. 首句承接台词不变，不等待用户选择，不展示选项按钮。
+3. 设置入口只允许打开教程临时设置面板；设置侧边栏只展示区域，不点击或保存配置。
+4. 主动搭话开关只展示入口，不点击、不打开子侧栏、不改变开关状态。
+5. 收尾前必须关闭 Day 2 临时打开的设置面板和侧边栏；收尾三句必须圆角矩形高亮胶囊输入框；最终句 cue 必须同步清理高光、Ghost Cursor 和外置聊天窗状态。
+6. 外置聊天窗 / PC 全局 overlay 模式下，设置按钮和主动搭话开关的高光与 Ghost Cursor 必须由同一个 overlay 状态包同时携带；cursor 移动、spotlight refresh 或目标矩形重算都不得只发送其中一半，避免远端渲染层交替清空高亮或光标造成闪烁。
+
+## 验收清单
+
+1. Day 2 scene 顺序与本文一致。
+2. `day2_intro_context` 文案、text key 和 voice key 保持原样。
+3. 设置按钮、设置侧边栏、主动搭话入口都有明确高光目标、Ghost Cursor 路径和禁止点击/保存约束。
+4. Day 2 主线不触发屏幕分享、主动搭话或用户配置保存。
+5. Day 2 主线普通指认统一使用平滑移动和停留。
+6. Day 2 完成、skip、destroy 和 angry exit 的结束态语义不变。