# 14 · 向导交互层设计裁定（v1 基线）

> 依据：research/02-methodology/methodology.md §3（L3 状态层 / L4 引导层）→
> research/03-schemes/schemes.md §1/§2（实施蓝图，唯一事实源）。
> 本文存档 v1 已落地的裁定与新增语音资产台词表，供后续轮次回溯。
> 实现载体：`web/engine/guide.js`（引擎向导模块）+ 各游戏 game.js 接线。

## 1. 裁定摘要

| # | 裁定 | 内容 |
|---|---|---|
| 1 | 分期 | v1 只做「全局基线」= 引擎向导层 + 逐游戏接线；场景参数包（A 通勤/B 摸鱼/C 睡前/D 下班）与人设旋钮在试玩验证后分期（schemes §3）。 |
| 2 | 等级 | `settings.guide`：`'full'`（默认，earcon+语音+震动）/ `'standard'`（earcon+震动，无语音）/ `'off'`（全静 no-op，**不挂任何定时器**）。大厅设置面板「向导帮助：详细/只听提示音/关闭」。 |
| 3 | earcon | 8 个签名（6 状态 menu/explore/battle/choice/settle/danger + 2 功能 turn/nudge）**全项目统一**，全部运行时 WebAudio 合成（零资产、可复现）；总长 0.25~0.4s、单音 ≥0.08s、125Hz~5kHz、总增益 ≈0.12；家族=波形音色、子类=节奏轮廓（schemes §1.4）。 |
| 4 | 语音纪律 | 向导插播语音一律 `queue:true`（等当前对白播完），**绝不顶掉正在播的内容**；抉择提示（storyline p*）播完即可选的等待点不插任何语音。 |
| 5 | 看门狗 | 统一模板：静默 N 秒 → nudge 轻 earcon（+ full 档语音）→ 二次升级播上下文提示 → 级数用尽自动停止；任何手势/向导动作复位。escape 的三级卡关骨架保留，仅加「连续撞墙 ≥2 次 → full 档阈值提前一级」。 |
| 6 | 引擎配套 | `audio.isVoicePlaying()` 公开只读 API（收编 5 处私有 `_voice` 读）；`audio.setRateBoostEnabled(bool)` 长按快进 per-game 开关（rhythm/space 对局期豁免）；`settings.speed` 增加 2.2 档（视障档，250+ WPM）。 |
| 7 | 语义分工铁律 | 语音说「你要做什么」、earcon 说「哪类事/哪个状态」、BGM 说「宏观状态」、震动说「刚才那下对不对」——向导层不越界（L2 铁律：earcon 只做粗标记，语义靠语音）。 |

## 2. 逐游戏接线裁定（v1 落地范围）

| 游戏 | 接线 |
|---|---|
| storyline | W1/W3 静默看门狗 [8s]=nudge+`gd_continue`、[20s]=复用 `playHelpAndResume`；选择节点外左右滑的静默 return 处加 error 震+`gd_invalid`；抉择态（p* 播完）不插语音不挂看门狗；状态签名 explore/menu 与状态 BGM 同点。 |
| simon | input 看门狗 [10s]=nudge+`gd_relisten`、[25s]=免扣机会自动重听（每局 2 次）；`your_turn` 泛化为 turn earcon（每轮，第 1 轮保留原语音）；状态签名 settle/menu。 |
| escape | REOPEN 提示播完与引导步解锁给 turn cue；连续撞墙 ≥2 次 → full 档卡关三级阈值提前一级；其余（wrong/blunt/stuck/nav）保持既有完备体系。 |
| rhythm | 每曲首次领奏→应答切换推 `gd_answer`（谱面排程处入 `_timed`）；连续 2 Miss 播 `gd_miss`（queue 插播，同曲一次）；结算链换 `_speakGuarded`；main 演奏期 `setRateBoostEnabled(false)`；状态签名 menu/battle/settle。 |
| space | 对局第 1 次受击（保护期外）追加 `gd_hit_hint`；结算链换 `_speakGuarded`；对局期 `setRateBoostEnabled(false)`；状态签名 battle/menu/settle。 |
| rpg | 格挡窗口内做错手势 → error 震+`gd_parry_miss`（每局一次）；PLAYER_SELECT 挂看门狗 [60s]=nudge+`gd_stall`；状态签名 explore/battle/menu/settle 与四状态 BGM 同点补齐。 |

## 3. 新增语音资产台词表（8 句 ×2 性别 = 16 文件）

定稿依据 schemes.md §1.5，台词全文一字不改；speaker/instruct 沿用各游戏旁白常量
（见 `tools/gen_voice_dual.py` SPEAKERS 与各 `_XXX` pair）：

| 游戏 | id | 全文 | 触发 | female speaker / instruct | male speaker / instruct |
|---|---|---|---|---|---|
| storyline | `gd_continue` | 轻触屏幕，继续。 | W1/W3 叙事节点播完静默 8s（看门狗第 1 级） | Vivian / _SL_NARR[1] | Uncle_Fu / _SL_NARR[0] |
| storyline | `gd_invalid` | 这个操作在这里用不上。 | 无效手势（选择节点外左右滑静默 return，同局限次） | Vivian / _SL_NARR[1] | Uncle_Fu / _SL_NARR[0] |
| simon | `gd_relisten` | 需要的话，双击可以重新听一遍序列。 | input 阶段 10s 无输入（不改变重听扣机会规则） | Serena / _SIMON | Uncle_Fu / _SIMON |
| rhythm | `gd_answer` | 现在跟着我打。 | 每曲首次领奏→应答切换 | Vivian / _RHY | Uncle_Fu / _RHY |
| rhythm | `gd_miss` | 慢了半拍，下一小节跟上我就行。 | 连续 2 次 Miss（同曲限 1 次，queue 插播） | Vivian / _RHY | Uncle_Fu / _RHY |
| space | `gd_hit_hint` | 被撞了。听方位，同向滑动就能拨开。 | 对局第 1 次受击（保护期外，同局 1 次） | Serena / _SPC | Uncle_Fu / _SPC |
| rpg | `gd_parry_miss` | 前摇声起的时候双击，才能格挡。 | 格挡窗口内做错手势（每局限次） | Serena / _RPG | Uncle_Fu / _RPG |
| rpg | `gd_stall` | 想好了吗？左右滑动选择，单击出手。 | PLAYER_SELECT 60s 无输入 | Serena / _RPG | Uncle_Fu / _RPG |

资产落位：`web/<game>/audio/voice/{female,male}/gd_*.{ogg,m4a}`（管线
`tools/gen_voice_dual.py --game <g> --only gd_xxx` 生成 + `--convert` 落盘，
双格式配对由 `tools/check_all_assets.py` 终检保证）。

## 4. 已知边界与后续候选

- `onceKey` 语义为「同局（游戏会话）一次」；schemes §1.5 中 storyline `gd_invalid`
  「同局限 2 次」、rpg `gd_parry_miss`「每场战斗 1 次」为更细粒度限次，v1 统一收敛到
  onceKey（一次教学提示足矣），如试玩反馈不足再引入 per-run 限次 API。
- 教学义务（schemes §1.4「full 档开场教学带教签名 earcon」）：v1 未在各游戏教学链中
  逐个口播签名音，列为 v2 候选（需逐游戏改教学台词，涉及台词表返工）。
- 向导插播语音目前挂在引擎 voice 队列；若游戏层 `stopVoice()` 会顺带丢弃排队中的
  向导句（作废语义，可接受）。