feat: wire bark battle platform loop

docs/prd/BARK_BATTLE_BDD_2026-05-11.md

@@ -4,7 +4,7 @@
 
 - 需求来源：用户提供的视频 `C:\Users\DSK\Videos\一款双方比狗叫的游戏 - 1.一款双方比狗叫的游戏(Av116504192360177,P1).mp4`，并已在 `.hermes/plans/2026-05-11_144229-bark-battle-2d-game-bdd-ddd-tdd-plan.md` 中完成抽帧分析和玩法方案整理。
 - 玩法定位：浏览器 2D 声控狗叫对战小游戏，暂定中文名 `汪汪声浪大作战`，英文代号与 play type ID 建议为 `bark-battle`。
-- 核心玩法：双方狗狗在 30 秒限时内通过麦克风输入“狗叫声”进行声浪拔河；系统依据声音强度、有效叫声次数和叫声节奏计算推动力，实时推动顶部红蓝能量条；倒计时结束后按能量条位置判定胜负或平局。
+- 核心玩法：双方狗狗在 30 秒限时内通过麦克风输入“狗叫声”进行声浪拔河；系统依据声音强度、有效声浪触发次数和声浪节奏计算推动力，实时推动顶部红蓝能量条；倒计时结束后按能量条位置判定胜负或平局。
 - 文档目的：为产品、测试、前端、后端在编码前统一可验证验收口径；本文只定义 PRD/BDD 级行为与测试映射，不实现工程代码。
 
 ## 角色与目标
@@ -20,14 +20,14 @@
 ### 用户目标
 
 - 玩家可以在开局前完成麦克风授权和环境噪音校准。
-- 玩家发出有效狗叫时，能看到叫声计数、狗狗动画、拟声词/冲击波以及能量条变化。
-- 低于阈值的背景噪音不会被误计为有效叫声。
+- 玩家产生有效声浪触发时，能看到声浪计数、狗狗动画、拟声词/冲击波以及能量条变化。
+- 低于阈值的背景噪音不会被误计为有效声浪触发。
 - 单局在 30 秒后给出明确胜负、平局和关键数据。
 - 移动端和不支持麦克风的环境不会进入不可操作状态。
 
 ### 非目标
 
-- MVP 不要求识别“是否真实狗叫”，不引入机器学习声纹/物种分类；有效输入以音量阈值、峰值间隔、持续时间和校准结果为准。
+- MVP 不要求识别“是否真实狗叫”，不引入机器学习声纹/物种分类；有效输入以音量阈值、峰值冷却间隔和校准结果为准。
 - MVP 不要求实时联机对战；可先按“玩家 vs AI 对手”完成单机浏览器 runtime。
 - MVP 不要求成绩持久化、作品发布、作品架、广场和排行榜；若后续接入 Genarrative 作品闭环，需要另补玩法类型集成 PRD/技术文档。
 - MVP 不要求在 UI 中长期展示大段规则说明；游戏界面应保持倒计时、能量条、狗狗、麦克风状态和结算信息为主。
@@ -38,10 +38,10 @@
 - 单局时长：默认 30 秒，从正式进入 `playing` 阶段开始计时。
 - 能量条：使用 `-100` 到 `100` 的连续值表示，负数偏对手侧，正数偏玩家侧，`0` 为中线。
 - 平局阈值：倒计时结束时，若能量条绝对值小于或等于 `drawThreshold`，判定平局；具体数值由实现配置，但测试需可注入固定阈值。
-- 有效叫声：一次有效叫声至少满足：音量超过校准后的有效阈值、与上一次有效峰值间隔不小于 `minBarkGapMs`、持续时长在 `minBarkDurationMs` 到 `maxBarkDurationMs` 之间。
-- 背景噪音：校准阶段采集到的环境声用于计算动态阈值；低于阈值的输入不得增加叫声次数，也不得让能量条出现可见推进。
-- 推动力：玩家推动力由音量分数、有效叫声频率和连击加成组成；能量条按玩家推动力与对手推动力差值移动，并被限制在 `-100` 到 `100`。
-- UI 反馈：有效叫声应触发可观察反馈，包括玩家侧狗狗张嘴/吠叫动画、拟声词或冲击波；反馈不应遮挡倒计时和顶部能量条。
+- 有效声浪触发：一次有效声浪触发满足：当前麦克风采样点的归一化响度达到或超过校准后的有效阈值，且与上一次有效声浪触发间隔不小于 `minBarkGapMs`；不再要求持续高响度时长达标，也不等待响度回落。
+- 背景噪音：校准阶段采集到的环境声用于计算动态阈值；低于阈值的输入不得增加声浪触发次数，也不得让能量条出现可见推进。
+- 推动力：玩家推动力由音量分数、有效声浪触发频率和连击加成组成；能量条按玩家推动力与对手推动力差值移动，并被限制在 `-100` 到 `100`。
+- UI 反馈：有效声浪触发应触发可观察反馈，包括玩家侧狗狗张嘴/吠叫动画、拟声词或冲击波；反馈不应遮挡倒计时和顶部能量条。
 
 ## 中文 Gherkin 场景
 
@@ -66,7 +66,7 @@
   场景: 校准完成后进入开局倒计时
     假如玩家已允许麦克风权限
     而且系统已采集足够的环境噪音样本
-    当校准计算出有效叫声阈值
+    当校准计算出有效声浪阈值
     那么系统应进入开局倒计时阶段
     而且倒计时结束后应进入 30 秒对战阶段
     而且初始能量条应位于中线
@@ -84,19 +84,19 @@
 功能: 环境噪音校准
   为了减少背景噪音误触发
   作为浏览器玩家
-  我希望游戏在开局前根据当前环境设置有效叫声阈值
+  我希望游戏在开局前根据当前环境设置有效声浪阈值
 
   场景: 安静环境生成低但非零的有效阈值
     假如校准阶段采集到的环境噪音 RMS 稳定低于默认噪音基线
     当系统完成校准
-    那么有效叫声阈值应高于环境噪音平均值
+    那么有效声浪阈值应高于环境噪音平均值
     而且阈值不应低于系统配置的最小阈值
 
   场景: 嘈杂环境生成更高的有效阈值
     假如校准阶段采集到的环境噪音 RMS 高于默认噪音基线
     当系统完成校准
-    那么有效叫声阈值应随环境噪音上调
-    而且低于该阈值的后续输入不应计为有效叫声
+    那么有效声浪阈值应随环境噪音上调
+    而且低于该阈值的后续输入不应计为有效声浪触发
 
   场景: 校准期间无法获得有效音频样本
     假如麦克风授权成功但音频样本持续为空或不可读
@@ -106,36 +106,36 @@
     而且不应直接开始对战
 ```
 
-### 功能: 有效叫声计数
+### 功能: 有效声浪触发计数
 
 ```gherkin
-功能: 有效叫声计数
-  为了把玩家的狗叫行为转换为可计分输入
+功能: 有效声浪触发计数
+  为了把玩家的声控行为转换为可计分输入
   作为玩家
-  我希望每次符合规则的短促叫声只被计数一次
+  我希望每次超过阈值且满足冷却的声浪触发只被计数一次
 
   背景:
     假如游戏处于 30 秒 playing 阶段
     而且系统已完成环境噪音校准
 
-  场景: 单次超过阈值且间隔足够的叫声计数加一
-    假如玩家当前叫声次数为 0
-    而且上一次有效叫声时间早于 minBarkGapMs
-    当麦克风输入出现一次超过有效阈值且持续时长合规的峰值
-    那么玩家叫声次数应变为 1
+  场景: 单次超过阈值且间隔足够的声浪触发计数加一
+    假如玩家当前声浪触发次数为 0
+    而且上一次有效声浪触发时间早于 minBarkGapMs
+    当某个麦克风采样点达到或超过有效阈值且满足声浪冷却
+    那么玩家声浪触发次数应变为 1
     而且玩家侧应出现一次吠叫动画反馈
     而且画面应出现一次拟声词或冲击波反馈
 
-  场景: 持续噪音不会被无限计数
-    假如玩家当前叫声次数为 1
-    当麦克风输入持续超过阈值但没有新的峰值间隔
-    那么玩家叫声次数不应在每个 tick 中持续增加
-    而且系统最多只应记录当前连续声音段内的一次有效叫声
+  场景: 持续高响度输入只按冷却节奏计数
+    假如玩家当前声浪触发次数为 1
+    当麦克风输入持续超过阈值但仍处于声浪冷却内
+    那么玩家声浪触发次数不应在每个 tick 中持续增加
+    而且系统只应在冷却结束后的采样点再次达阈值时记录下一次有效声浪触发
 
   场景: 间隔过短的连续峰值不重复计数
-    假如玩家刚刚产生一次有效叫声
-    当麦克风输入在 minBarkGapMs 内再次出现峰值
-    那么玩家叫声次数不应增加
+    假如玩家刚刚产生一次有效声浪触发
+    当麦克风输入在 minBarkGapMs 内再次达到有效阈值
+    那么玩家声浪触发次数不应增加
     而且连击或推动力不应因该峰值重复加成
 ```
 
@@ -145,23 +145,23 @@
 功能: 声浪推动能量条
   为了复刻双方比狗叫的核心体验
   作为玩家
-  我希望更响、更连续的有效叫声能把顶部能量条推向自己一侧
+  我希望更响、更高频的有效声浪触发能把顶部能量条推向自己一侧
 
   背景:
     假如游戏处于 30 秒 playing 阶段
     而且能量条当前位于中线
 
   场景: 玩家推动力高于对手时能量条向玩家侧移动
-    假如玩家在短时间窗口内产生多次有效叫声
+    假如玩家在短时间窗口内产生多次有效声浪触发
     而且玩家推动力高于对手推动力
     当系统推进一个 simulation tick
     那么能量条数值应向玩家侧增加
     而且顶部红蓝能量条的玩家侧占比应变大
 
-  场景: 连续大声叫声触发更强反馈
-    假如玩家连续产生多次高于强叫声阈值的有效叫声
+  场景: 连续强声浪触发触发更强反馈
+    假如玩家连续产生多次高于强声浪阈值的有效声浪触发
     当系统计算玩家连击加成
-    那么玩家侧推动力应高于单次普通叫声推动力
+    那么玩家侧推动力应高于单次普通声浪触发推动力
     而且玩家侧声浪或冲击波反馈应比普通叫声更明显
     但是反馈不应遮挡倒计时和能量条
 
@@ -185,31 +185,30 @@
 功能: 背景噪音过滤
   为了避免环境声替玩家自动得分
   作为玩家
-  我希望低于阈值或不合规的声音不会被当作有效狗叫
+  我希望低于阈值或处于冷却内的声音不会被当作有效声浪触发
 
   背景:
     假如游戏处于 30 秒 playing 阶段
     而且系统已完成环境噪音校准
 
   场景: 低于阈值的背景噪音不计数
-    当麦克风只接收到低于有效叫声阈值的背景噪音
-    那么玩家叫声次数不应增加
+    当麦克风只接收到低于有效声浪阈值的背景噪音
+    那么玩家声浪触发次数不应增加
     而且玩家侧不应播放吠叫动画
     而且能量条不应因为该背景噪音出现可见推进
 
-  场景: 过短脉冲不计为有效叫声
-    假如麦克风输入峰值超过有效阈值
-    但是持续时长短于 minBarkDurationMs
-    当系统完成该声音段判定
-    那么玩家叫声次数不应增加
+  场景: 冷却内重复达阈值不计数
+    假如玩家刚刚产生一次有效声浪触发
+    当麦克风输入在 minBarkGapMs 内再次达到有效声浪阈值
+    那么玩家声浪触发次数不应增加
     而且不应触发连击加成
 
-  场景: 过长持续声被削弱为单段输入
-    假如麦克风输入持续超过有效阈值
-    但是持续时长长于 maxBarkDurationMs
-    当系统完成该声音段判定
-    那么系统不应按多个叫声重复计数
-    而且该声音段的推动力应按持续噪音削弱规则处理
+  场景: 持续高响度输入只按冷却节奏产生触发
+    假如麦克风输入持续达到或超过有效声浪阈值
+    当声浪冷却尚未结束
+    那么系统不应在每个 tick 中重复计数
+    当声浪冷却结束且当前采样仍达到有效声浪阈值
+    那么系统可以记录下一次有效声浪触发
 ```
 
 ### 功能: 倒计时与胜负结算
@@ -227,20 +226,20 @@
     当系统时间从 30 秒推进到 0 秒
     那么界面应显示倒计时归零
     而且系统应进入 finished 结算阶段
-    而且归零后的麦克风输入不应再改变本局能量条和叫声次数
+    而且归零后的麦克风输入不应再改变本局能量条和声浪触发次数
 
   场景: 玩家侧占优时判定玩家胜利
     假如倒计时归零时能量条数值大于 drawThreshold
     当系统进入结算阶段
     那么系统应判定玩家胜利
-    而且结算面板应展示玩家叫声次数、最大音量和声浪评分
+    而且结算面板应展示玩家声浪触发次数、最大音量和声浪评分
     而且应提供再来一局入口
 
   场景: 对手侧占优时判定玩家失败
     假如倒计时归零时能量条数值小于 -drawThreshold
     当系统进入结算阶段
     那么系统应判定对手胜利
-    而且结算面板应展示玩家叫声次数、最大音量和声浪评分
+    而且结算面板应展示玩家声浪触发次数、最大音量和声浪评分
     而且应提供再来一局入口
 
   场景: 能量条接近平衡时判定平局
@@ -265,7 +264,7 @@
     当玩家选择再来一局
     那么系统应重置剩余时间为 30 秒
     而且能量条应回到中线
-    而且玩家叫声次数、最大音量、连击和胜负结果应清零
+    而且玩家声浪触发次数、最大音量、连击和胜负结果应清零
     而且系统应重新进入校准或开局倒计时流程
 
   场景: 结算后返回玩法入口
@@ -353,7 +352,7 @@
     假如玩家在 playing 阶段刷新页面
     当页面重新加载 bark-battle
     那么系统应重新进入权限检查或授权准备状态
-    而且不应沿用刷新前的剩余时间、能量条和叫声次数作为新局结果
+    而且不应沿用刷新前的剩余时间、能量条和声浪触发次数作为新局结果
 ```
 
 ## 测试映射
@@ -367,15 +366,15 @@
 | 嘈杂环境生成更高的有效阈值 | unit | `src/games/bark-battle/domain/BarkNoiseCalibration.test.ts` | planned |
 | 校准期间无法获得有效音频样本 | application/component | `src/games/bark-battle/application/BarkBattleController.test.ts`, `src/games/bark-battle/ui/BarkBattlePermissionPanel.test.tsx` | planned |
 | 单次超过阈值且间隔足够的叫声计数加一 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
-| 持续噪音不会被无限计数 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
+| 持续高响度输入只按冷却节奏计数 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
 | 间隔过短的连续峰值不重复计数 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
 | 玩家推动力高于对手时能量条向玩家侧移动 | unit | `src/games/bark-battle/domain/EnergyTugOfWar.test.ts` | planned |
-| 连续大声叫声触发更强反馈 | unit/integration/component | `src/games/bark-battle/domain/BarkBattleScoring.test.ts`, `src/games/bark-battle/ui/BarkBattleHud.test.tsx` | planned |
+| 连续强声浪触发触发更强反馈 | unit/integration/component | `src/games/bark-battle/domain/BarkBattleScoring.test.ts`, `src/games/bark-battle/ui/BarkBattleHud.test.tsx` | planned |
 | 能量条到达边界后不会越界 | unit | `src/games/bark-battle/domain/EnergyTugOfWar.test.ts` | planned |
 | 对手推动力高于玩家时能量条向对手侧移动 | unit | `src/games/bark-battle/domain/EnergyTugOfWar.test.ts` | planned |
 | 低于阈值的背景噪音不计数 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
-| 过短脉冲不计为有效叫声 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
-| 过长持续声被削弱为单段输入 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
+| 冷却内重复达阈值不计数 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
+| 持续高响度输入只按冷却节奏产生触发 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
 | 倒计时每秒递减并在归零时停止对战输入 | unit/application | `src/games/bark-battle/domain/BarkBattleSession.test.ts`, `src/games/bark-battle/application/BarkBattleController.test.ts` | planned |
 | 玩家侧占优时判定玩家胜利 | unit/component | `src/games/bark-battle/domain/BarkBattleSession.test.ts`, `src/games/bark-battle/ui/BarkBattleResultPanel.test.tsx` | planned |
 | 对手侧占优时判定玩家失败 | unit/component | `src/games/bark-battle/domain/BarkBattleSession.test.ts`, `src/games/bark-battle/ui/BarkBattleResultPanel.test.tsx` | planned |
@@ -394,8 +393,8 @@
 ## 验收清单
 
 - [ ] 权限允许、拒绝、非安全上下文、API 不支持、麦克风未找到/不可读、AudioContext 被拦截、校准超时或样本不可读均有明确状态，且不会误进入 playing。
-- [ ] 校准阶段会影响有效叫声阈值，低噪音不会增加叫声计数。
-- [ ] 有效叫声计数具备阈值、峰值间隔、持续时长约束。
+- [ ] 校准阶段会影响有效声浪阈值，低噪音不会增加叫声计数。
+- [ ] 有效声浪触发计数具备阈值与声浪冷却约束。
 - [ ] 能量条根据双方推动力差值双向移动，并限制在 `-100` 到 `100`。
 - [ ] 30 秒归零后停止本局输入影响，并按玩家胜利、对手胜利、平局三类结果结算。
 - [ ] 移动端核心元素可见，非关键设置收起，不在主画面堆叠长规则说明。
@@ -405,8 +404,8 @@
 ## 开放问题
 
 1. MVP 是否确认只做“玩家 vs AI”，还是第一版需要双人同屏或联机对战？
-2. `drawThreshold`、`minBarkGapMs`、`minBarkDurationMs`、`maxBarkDurationMs` 的首版默认值由产品/调参阶段确认，还是先采用开发可配置默认值？
+2. `drawThreshold`、`minBarkGapMs`、有效声浪阈值 的首版默认值由产品/调参阶段确认，还是先采用开发可配置默认值？
 3. 是否允许无麦克风设备提供键盘/点击备用输入？若允许，需要另补非声控模式场景；若不允许，当前降级只提供返回入口。
-4. 是否需要在结算中记录或上报成绩、最高音量、叫声次数和声浪评分？若需要，需补埋点/后端持久化场景。
+4. 是否需要在结算中记录或上报成绩、最高音量、声浪触发次数和声浪评分？若需要，需补埋点/后端持久化场景。
 5. bark-battle 是否作为 Genarrative 正式 play type 接入创作入口、作品发布和广场，还是先作为独立 runtime 原型验证？
 6. 狗狗、背景、拟声词和冲击波素材来源是临时占位、AI 生成，还是复用项目现有素材管线？