.hermes/plans/2026-05-11_144229-bark-battle-2d-game-bdd-ddd-tdd-plan.md

@@ -0,0 +1,561 @@
+# 声控狗叫对战 2D 浏览器游戏设计与实现计划
+
+## 目标
+
+基于用户提供的视频：
+
+`C:\Users\DSK\Videos\一款双方比狗叫的游戏 - 1.一款双方比狗叫的游戏(Av116504192360177,P1).mp4`
+
+提取其中“双方比狗叫”的核心玩法，并按照 BDD / TDD / DDD 的方法，为 Genarrative 中可运行于浏览器的 2D 游戏方案生成一份可落地设计与实现思路。实现方向遵循仓库内 `game-studio` 插件工作流，默认采用 2D Phaser + TypeScript + Vite + DOM HUD 的浏览器游戏架构。
+
+本计划仅做方案设计，不直接编码。
+
+## 当前上下文与输入分析
+
+### 已识别视频核心画面
+
+通过抽帧观察，视频中的游戏呈现出以下稳定特征：
+
+- 画面是横版 2D 手绘舞台，场景包括公园、海边等固定关卡背景。
+- 双方各有一只狗作为对战角色，站在左右两侧。
+- 中央有明显倒计时，例如 `30`、`28`。
+- 顶部有红蓝双方拉锯式能量条 / 进度条。
+- 中央提示出现：`对着麦克风汪一声`、`用声音大小 + 叫声次数推动能量条！`
+- 玩家输入不是传统键鼠，而是麦克风声音。
+- 玩家需要模仿狗叫，系统根据声音大小与叫声次数推动能量条。
+- 屏幕会根据叫声出现 `BARK`、`WOOF`、`WAN`、`WANGOOF` 等拟声词与冲击波视觉反馈。
+- 回合结束时，根据能量条偏向或推进结果判定胜负。
+
+### 提炼出的核心玩法
+
+这是一个“声控拔河式狗叫对战”小游戏：
+
+- 两名玩家 / 一名玩家对 AI 分别代表左右两只狗。
+- 每局限时 30 秒。
+- 玩家通过麦克风持续发出狗叫声。
+- 游戏实时分析音量峰值、叫声次数、叫声节奏。
+- 声音越大、叫声越密集，己方推动力越强。
+- 顶部能量条在双方推动力差值下左右移动。
+- 时间结束后，能量条偏向哪一方，哪一方获胜。
+
+### 需要合理抽象的地方
+
+视频中存在直播弹幕、贴图、表情包、遮挡层，这些不是游戏本体机制。本方案只吸收游戏本体核心：
+
+- 双方狗狗对叫
+- 麦克风输入
+- 声音强度 + 次数判定
+- 红蓝拉锯能量条
+- 限时回合
+- 夸张拟声词与冲击波反馈
+
+## game-studio 插件路线
+
+根据仓库内 `.hermes/plugins/game-studio` 技能：
+
+- 早期游戏工作先走 `game-studio` 总入口。
+- 2D 浏览器游戏默认选择 Phaser。
+- 架构上需要分离 simulation 与 renderer。
+- HUD / 菜单 / 设置优先使用 DOM overlay，不把密集文字塞进 canvas。
+- 玩法状态不应由 Phaser Scene 直接持有，Scene 只负责渲染、动画、相机、输入适配。
+
+因此本方案采用：
+
+- Runtime：Phaser 3
+- Language：TypeScript
+- Build：Vite
+- UI：React/DOM HUD overlay 或项目现有 DOM UI 层
+- Audio input：Web Audio API + MediaDevices.getUserMedia
+- Simulation：纯 TS domain/service 层
+- Renderer：Phaser Scene 读取 simulation snapshot 并播放动画/特效
+
+## 游戏概念设计
+
+### 游戏名建议
+
+- 中文：`汪汪声浪大作战`
+- 英文代号：`bark-battle`
+- Play type ID 建议：`bark-battle`
+
+### 玩家幻想
+
+玩家不是通过按键战斗，而是真的对着麦克风“汪汪叫”，把自己的狗狗声浪推向对手。游戏目标是在倒计时结束前用更响、更密集、更有节奏的叫声赢得声浪拔河。
+
+### 核心动词
+
+- 叫：对麦克风发出狗叫声。
+- 推：通过叫声推动能量条。
+- 压制：让能量条持续向对手方向倾斜。
+- 爆发：短时间内连续高质量叫声触发冲击波。
+- 防守：对手强势时通过持续叫声把能量条拉回。
+
+### 单局流程
+
+1. 准备阶段
+   - 展示双方狗狗、地图、麦克风权限提示。
+   - 用户授权麦克风。
+   - 系统检测环境噪音并校准阈值。
+
+2. 倒计时阶段
+   - 3、2、1 或中央 `30` 倒计时开始。
+   - 玩家看到提示：`对着麦克风汪一声`。
+
+3. 对战阶段
+   - 每帧或固定 tick 采集麦克风音量。
+   - 根据音量峰值与短促叫声次数计算本方 barkPower。
+   - AI 或远端对手产生 opponentPower。
+   - 能量条根据 `playerPower - opponentPower` 拉锯。
+   - 狗狗张嘴动画、拟声词、冲击波按声音强度生成。
+
+4. 结算阶段
+   - 30 秒结束。
+   - 能量条偏玩家侧则胜利，偏对手侧则失败，接近中线则平局。
+   - 展示叫声次数、最大音量、平均节奏、声浪评分。
+
+5. 重开 / 返回
+   - 支持再来一局。
+   - 支持返回玩法入口或结果页。
+
+## 规则设计
+
+### 关键状态
+
+```ts
+type BarkBattlePhase = 'permission' | 'calibration' | 'countdown' | 'playing' | 'finished'
+
+type BarkBattleSnapshot = {
+  phase: BarkBattlePhase
+  remainingMs: number
+  energy: number // -100 到 100，负数偏对手，正数偏玩家
+  player: BarkSideState
+  opponent: BarkSideState
+  winner: 'player' | 'opponent' | 'draw' | null
+}
+
+type BarkSideState = {
+  barkCount: number
+  currentVolume: number
+  recentPeak: number
+  combo: number
+  power: number
+  isBarking: boolean
+}
+```
+
+### 输入判定
+
+#### 音量采样
+
+- 使用 Web Audio API 创建 `AnalyserNode`。
+- 每个 simulation tick 读取频域或时域数据。
+- 计算 RMS 或 peak volume。
+- 根据校准后的环境噪音设置动态阈值。
+
+#### 一次“叫声”的判定
+
+一次有效叫声建议满足：
+
+- 音量超过 `barkThreshold`。
+- 与上一次叫声峰值至少间隔 `minBarkGapMs`，避免持续噪音被无限计数。
+- 持续时长在合理范围，例如 80ms 到 1200ms。
+- 可选：频谱能量集中在中高频，不强制做复杂语音识别，MVP 先用音量 + 峰值节奏。
+
+#### 推动力计算
+
+```text
+playerPower = volumeScore * 0.65 + barkRateScore * 0.35 + comboBonus
+opponentPower = aiPower 或远端玩家 power
+energyDelta = (playerPower - opponentPower) * deltaTime * balanceFactor
+energy = clamp(energy + energyDelta, -100, 100)
+```
+
+### AI 对手 MVP
+
+若先做单机浏览器版，右侧对手可由 AI 模拟：
+
+- 简单难度：周期性小叫，power 低。
+- 普通难度：有节奏地爆发，power 中等。
+- 困难难度：根据玩家领先程度自适应追赶，但不得作弊到不可赢。
+
+后续可扩展为多人实时对战。
+
+## BDD 行为场景
+
+### 功能: 麦克风授权与准备
+
+```gherkin
+功能: 狗叫对战麦克风准备
+  为了让玩家能用声音参与对战
+  作为浏览器玩家
+  我希望游戏在开局前明确请求麦克风权限并完成环境校准
+
+  场景: 玩家允许麦克风权限后进入准备倒计时
+    假如玩家打开狗叫对战页面
+    当玩家同意浏览器麦克风授权
+    那么系统应进入环境噪音校准阶段
+    而且校准完成后应显示开局倒计时
+
+  场景: 玩家拒绝麦克风权限
+    假如玩家打开狗叫对战页面
+    当玩家拒绝浏览器麦克风授权
+    那么系统应显示无法声控游玩的提示
+    而且应提供重试授权入口
+    而且不应直接开始对战
+```
+
+### 功能: 声音推动能量条
+
+```gherkin
+功能: 声音大小和叫声次数推动能量条
+  为了复刻双方比狗叫的核心体验
+  作为玩家
+  我希望自己的叫声能实时推动顶部能量条
+
+  场景: 玩家发出一次有效狗叫
+    假如游戏处于 playing 阶段
+    而且麦克风输入音量超过有效叫声阈值
+    当系统检测到一次新的叫声峰值
+    那么玩家叫声次数应增加 1
+    而且玩家狗狗应播放张嘴吠叫动画
+    而且画面应出现拟声词反馈
+
+  场景: 玩家连续大声狗叫压制对手
+    假如游戏处于 playing 阶段
+    而且玩家在短时间内产生多次有效叫声
+    当玩家推动力高于对手推动力
+    那么顶部能量条应向玩家侧移动
+    而且玩家侧声浪特效应增强
+
+  场景: 环境噪音低于阈值不计入叫声
+    假如游戏处于 playing 阶段
+    当麦克风只有低于阈值的背景噪音
+    那么玩家叫声次数不应增加
+    而且能量条不应因为背景噪音明显移动
+```
+
+### 功能: 限时胜负结算
+
+```gherkin
+功能: 狗叫对战胜负结算
+  为了让单局对抗有明确目标
+  作为玩家
+  我希望倒计时结束后根据能量条位置判定胜负
+
+  场景: 倒计时结束时玩家侧占优
+    假如游戏剩余时间归零
+    而且能量条位于玩家侧
+    当系统进入结算阶段
+    那么系统应判定玩家胜利
+    而且展示玩家叫声次数、最大音量和声浪评分
+
+  场景: 倒计时结束时双方接近平衡
+    假如游戏剩余时间归零
+    而且能量条处于平局阈值范围内
+    当系统进入结算阶段
+    那么系统应判定为平局
+    而且展示再来一局入口
+```
+
+### 功能: 移动端与无麦克风降级
+
+```gherkin
+功能: 声控游戏移动端与无麦克风降级
+  为了让不同设备玩家都能理解当前状态
+  作为移动端或无麦克风环境玩家
+  我希望系统给出清晰、可操作的降级路径
+
+  场景: 当前浏览器不支持麦克风 API
+    假如玩家设备不支持 getUserMedia
+    当玩家进入狗叫对战页面
+    那么系统应显示设备不支持麦克风输入
+    而且提供返回入口
+
+  场景: 移动端进入对战页面
+    假如玩家使用移动端浏览器
+    当玩家进入狗叫对战页面
+    那么主要能量条、倒计时和狗狗角色应保持可见
+    而且非关键设置应收起到菜单中
+```
+
+## DDD 领域划分
+
+### 领域层：bark-battle domain
+
+职责：只处理玩法规则，不依赖 Phaser、DOM、Web Audio、后端。
+
+建议模块：
+
+- `BarkBattleSession`
+  - 管理 phase、remainingMs、energy、winner。
+- `BarkDetector`
+  - 根据音量样本判断是否形成一次有效叫声。
+- `EnergyTugOfWar`
+  - 根据双方 power 更新能量条。
+- `BarkBattleScoring`
+  - 计算最大音量、叫声次数、combo、评分。
+- `OpponentStrategy`
+  - 单机 AI 对手策略接口。
+
+领域规则必须可用纯单元测试验证。
+
+### 应用层：use case / controller
+
+职责：编排麦克风输入、simulation tick、AI 对手、结果输出。
+
+建议用例：
+
+- `requestMicrophonePermission()`
+- `calibrateAmbientNoise()`
+- `startBarkBattleSession()`
+- `submitAudioSample(sample)`
+- `tickBarkBattle(deltaMs)`
+- `finishBarkBattle()`
+
+### 基础设施层
+
+职责：浏览器 API 与引擎适配。
+
+- `BrowserMicrophoneInput`
+  - 封装 `navigator.mediaDevices.getUserMedia`。
+  - 输出 normalized volume samples。
+- `PhaserBarkBattleScene`
+  - 渲染狗狗、背景、拟声词、冲击波。
+  - 不持有核心玩法规则。
+- `DomBarkBattleHud`
+  - 展示倒计时、能量条、权限提示、结算面板。
+
+### 表现层
+
+- Phaser Canvas：地图、狗狗、声浪、粒子、拟声词。
+- DOM HUD：顶部能量条、倒计时、权限/结算/设置面板。
+
+## TDD 落地顺序
+
+### 第一轮：领域规则 RED-GREEN-REFACTOR
+
+先写纯 TS 单元测试，不接 Phaser，不接麦克风。
+
+目标测试：
+
+- `BarkDetector`：超过阈值且间隔足够时计为一次叫声。
+- `BarkDetector`：持续噪音不会无限增加叫声次数。
+- `EnergyTugOfWar`：玩家 power 高于对手时 energy 向玩家侧移动。
+- `EnergyTugOfWar`：energy 被 clamp 在 -100 到 100。
+- `BarkBattleSession`：倒计时归零后进入 finished。
+- `BarkBattleSession`：根据 energy 判定 player/opponent/draw。
+
+### 第二轮：应用层测试
+
+- 模拟音频 sample 输入，验证 session snapshot 更新。
+- 模拟 AI 对手 power，验证能量条拉锯。
+- 模拟权限失败，验证 phase 不进入 playing。
+
+### 第三轮：组件 / 集成测试
+
+- HUD 根据 snapshot 显示倒计时。
+- HUD 根据 energy 渲染红蓝能量条比例。
+- 权限拒绝时显示重试入口。
+- 结算阶段显示胜负与再来一局。
+
+### 第四轮：浏览器 smoke / playtest
+
+- 本地启动页面。
+- 授权麦克风。
+- 对麦克风发声后看到拟声词与能量条变化。
+- 移动端宽度下主游戏画面不被 HUD 遮挡。
+
+## 建议文件结构
+
+如果作为独立前端玩法原型，可采用：
+
+```text
+src/games/bark-battle/
+  domain/
+    BarkBattleSession.ts
+    BarkDetector.ts
+    EnergyTugOfWar.ts
+    BarkBattleScoring.ts
+    OpponentStrategy.ts
+  application/
+    BarkBattleController.ts
+    BrowserMicrophoneInput.ts
+  phaser/
+    BarkBattleScene.ts
+    BarkBattlePreloadScene.ts
+    barkBattleAssets.ts
+  ui/
+    BarkBattleHud.tsx
+    BarkBattleResultPanel.tsx
+    BarkBattlePermissionPanel.tsx
+  tests/
+    BarkDetector.test.ts
+    EnergyTugOfWar.test.ts
+    BarkBattleSession.test.ts
+```
+
+如果接入 Genarrative 玩法类型闭环，后续还需要按 `genarrative-play-type-integration` 扩展：
+
+```text
+src/components/bark-battle-runtime/BarkBattleRuntimeShell.tsx
+src/components/bark-battle-result/BarkBattleResultView.tsx
+src/services/barkBattleRuntimeClient.ts
+packages/shared/src/contracts/barkBattle.ts
+server-rs/crates/shared-contracts/src/bark_battle.rs
+```
+
+MVP 阶段建议先做浏览器单机 runtime 原型，再决定是否进入创作入口、作品发布、广场和后端持久化。
+
+## UI / 视觉方向
+
+### 画面
+
+- 横版固定舞台。
+- 左右两只狗对峙。
+- 背景可先做公园一张图，后续扩展海边、街区等地图。
+- 狗狗用 2D sprite 或简单骨架帧动画。
+
+### HUD
+
+- 顶部：红蓝声浪能量条。
+- 中央：大号倒计时，只在开局和关键时间突出显示。
+- 左右：双方狗狗状态，不堆叠复杂面板。
+- 底部或角落：麦克风状态、小型重试按钮。
+- 结算：居中弹出简洁面板，显示胜负和关键数据。
+
+### 动效
+
+- 叫声触发狗狗张嘴。
+- 声音越大，拟声词越大，冲击波越宽。
+- combo 时触发短暂屏幕震动，但不能遮挡能量条。
+- 尊重 reduced motion，非必要动画可降级。
+
+## 测试映射
+
+| BDD 场景 | 测试层级 | 目标文件 | 状态 |
+| --- | --- | --- | --- |
+| 玩家允许麦克风权限后进入准备倒计时 | application/component | `BarkBattleController.test.ts`, `BarkBattlePermissionPanel.test.tsx` | planned |
+| 玩家拒绝麦克风权限 | application/component | `BarkBattleController.test.ts`, `BarkBattlePermissionPanel.test.tsx` | planned |
+| 玩家发出一次有效狗叫 | unit | `BarkDetector.test.ts` | planned |
+| 玩家连续大声狗叫压制对手 | unit/integration | `EnergyTugOfWar.test.ts`, `BarkBattleController.test.ts` | planned |
+| 环境噪音低于阈值不计入叫声 | unit | `BarkDetector.test.ts` | planned |
+| 倒计时结束时玩家侧占优 | unit | `BarkBattleSession.test.ts` | planned |
+| 倒计时结束时双方接近平衡 | unit | `BarkBattleSession.test.ts` | planned |
+| 当前浏览器不支持麦克风 API | component | `BarkBattlePermissionPanel.test.tsx` | planned |
+| 移动端进入对战页面 | visual/smoke | Playwright 或人工 playtest 清单 | planned |
+
+## 验证命令建议
+
+具体命令以后续实际落地位置为准，建议包括：
+
+```bash
+npm run test -- --run src/games/bark-battle/**/*.test.ts
+npm run test -- --run src/games/bark-battle/**/*.test.tsx
+npm run typecheck
+npm run check:encoding
+```
+
+若接入 Genarrative 后端或玩法配置，还需要追加：
+
+```bash
+cd server-rs && cargo check -p api-server -p shared-contracts --no-default-features
+npm run test -- src/components/platform-entry/platformEntryCreationTypes.test.ts
+```
+
+## 实施阶段拆分
+
+### Phase 0：产品与技术定稿
+
+- 确认玩法 ID：`bark-battle`。
+- 确认 MVP 只做单机玩家 vs AI，不做实时多人。
+- 确认是否只做 runtime 原型，还是接入 Genarrative 创作入口。
+- 确认是否允许浏览器麦克风权限作为核心输入。
+
+### Phase 1：纯领域模型
+
+- 建立 bark-battle domain。
+- 按 TDD 写 `BarkDetector`、`EnergyTugOfWar`、`BarkBattleSession` 测试。
+- 实现最小规则让测试通过。
+
+### Phase 2：麦克风输入适配
+
+- 封装 Web Audio API。
+- 支持权限请求、权限失败、环境噪音校准。
+- 使用 mock input 完成自动化测试，真实麦克风做 smoke。
+
+### Phase 3：Phaser 2D runtime
+
+- 新建 Phaser Scene。
+- 绘制或占位加载公园背景、左右狗狗、声浪特效。
+- Scene 只消费 snapshot，不写规则。
+- 接入 DOM HUD。
+
+### Phase 4：反馈与结算
+
+- 加入拟声词、冲击波、狗狗张嘴动画。
+- 加入结算面板。
+- 加入再来一局与返回入口。
+
+### Phase 5：Genarrative 集成可选项
+
+若要正式接入玩法类型：
+
+- 补 `shared-contracts` 中 bark-battle runtime/result DTO。
+- 补前端 service 与 runtime shell。
+- 补入口配置数据库 seed。
+- 补作品架 / 发布 / 广场链路，若需要持久化成绩或作品。
+- 按 `genarrative-play-type-integration` 执行完整闭环验证。
+
+## 风险与权衡
+
+### 麦克风权限风险
+
+浏览器麦克风权限受 HTTPS、浏览器策略、用户设置影响。MVP 需要明确：
+
+- 本地开发可在 localhost 使用。
+- 线上必须 HTTPS。
+- 权限拒绝需要可恢复。
+
+### 声音识别准确性风险
+
+MVP 不建议做复杂“是否真的是狗叫”的 AI 识别，否则实现成本高、误判多。建议先用：
+
+- 音量阈值
+- 峰值次数
+- 节奏间隔
+- 环境噪音校准
+
+后续再考虑加入频谱特征或 ML 分类。
+
+### 噪音作弊风险
+
+玩家可以喊叫、拍桌子或播放音频。若是娱乐派对玩法可以接受；若要竞技公平，需要后续加入：
+
+- 频谱特征
+- 输入冷却
+- 异常持续噪音削弱
+- 本地/服务端反作弊策略
+
+### 移动端兼容风险
+
+移动端 Web Audio 可能需要用户手势激活 AudioContext。计划中需把“开始”按钮作为显式用户手势，避免自动启动失败。
+
+### UI 遮挡风险
+
+视频原型中的核心可读信息非常少：倒计时、能量条、狗狗、拟声词。实现时应避免把说明文案、复杂面板长期铺在画面上。
+
+## 开放问题
+
+1. MVP 是“玩家 vs AI”，还是需要从第一版开始支持双人同屏 / 联机？
+2. 是否要作为 Genarrative 新玩法入口完整接入，还是先做独立 runtime 原型？
+3. 是否需要记录成绩、发布作品、进入作品架和广场？
+4. 狗狗与背景素材是使用临时占位、AI 生成，还是需要复用项目既有素材系统？
+5. 是否允许游戏强依赖麦克风权限，还是必须提供键盘备用输入？
+
+## 推荐下一步
+
+建议下一步先执行 Phase 0 + Phase 1：
+
+1. 明确 MVP 边界：单机玩家 vs AI。
+2. 写 `BarkDetector` / `EnergyTugOfWar` / `BarkBattleSession` 的 BDD 对应单元测试。
+3. 不接 Phaser、不接麦克风，先把核心规则用 TDD 跑通。
+4. 规则稳定后再接 Web Audio 与 Phaser runtime。

docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md

@@ -0,0 +1,662 @@
+# bark-battle 2D Runtime 前端技术方案（2026-05-11）
+
+## 1. 背景与目标
+
+本方案基于 `.hermes/plans/2026-05-11_144229-bark-battle-2d-game-bdd-ddd-tdd-plan.md`，为“汪汪声浪大作战 / bark-battle”细化前端与浏览器游戏 runtime 的技术实现路线。
+
+本任务只产出技术方案，不直接实现代码。后续编码应以本文作为 runtime 层设计约束，再按 TDD 小步落地。
+
+### 1.1 玩法定位
+
+`bark-battle` 是一个声控拔河式 2D 浏览器小游戏：玩家对麦克风发出狗叫声，系统根据音量峰值、有效叫声次数和节奏计算本方声浪推动力，在限时 30 秒内推动顶部红蓝能量条，时间结束后按能量条偏向判定胜负。
+
+### 1.2 本文范围
+
+本文覆盖：
+
+- Phaser + TypeScript + Vite 栈选择
+- simulation / render / HUD 边界
+- 建议目录结构
+- 核心 domain 类型
+- Web Audio 输入适配
+- Phaser Scene 切分
+- DOM HUD 设计
+- 移动端与权限降级
+- 测试与验证命令
+
+本文不覆盖：
+
+- 后端表结构、持久化成绩、作品发布、广场接入
+- 实时多人对战协议
+- 复杂 AI 狗叫识别模型
+- 美术素材正式生产流程
+
+## 2. 技术栈选择
+
+### 2.1 推荐栈
+
+```text
+Runtime Renderer: Phaser 3
+Language: TypeScript
+Build: Vite
+Host UI: React / DOM overlay
+Audio Input: Web Audio API + MediaDevices.getUserMedia
+Test: Vitest + Testing Library + 浏览器 smoke / Playwright 可选
+```
+
+### 2.2 选择理由
+
+1. 玩法是横版 2D 舞台，核心表现是狗狗 sprite、声浪、拟声词、粒子、屏幕震动与能量条反馈，Phaser 对 2D 渲染、时间循环、sprite animation、camera、粒子和 Scene 生命周期支持成熟。
+2. 当前项目主前端已使用 TypeScript + Vite，继续复用现有构建和测试体系，避免引入独立构建链。
+3. 文字密集、权限提示、结算、设置和移动端响应式布局适合 DOM HUD；Canvas 保持负责 playfield 和动态特效。
+4. Web Audio API 可以在浏览器端完成 MVP 所需音量采样、RMS/peak 计算、环境噪音校准和输入归一化，不需要首版接入后端音频处理。
+
+### 2.3 不选择其它路线的原因
+
+- 不使用 Three.js / 3D：当前玩法画面是 2D 横版舞台，不需要 3D 相机、模型和材质管线。
+- 不把 HUD 全部塞入 Phaser Canvas：权限说明、重试、结算、移动端布局和可访问性更适合 DOM。
+- 不在前端实现正式业务真相：浏览器 runtime 可承载单局即时 simulation，但若后续涉及成绩、作品、排行榜、发布和奖励，必须交给后端投影/API 裁决。
+
+## 3. 总体架构
+
+### 3.1 分层总览
+
+```text
+React Runtime Shell
+  ├─ DOM HUD / Panels
+  │   ├─ PermissionPanel
+  │   ├─ TopEnergyBar
+  │   ├─ TimerChip
+  │   └─ ResultPanel
+  │
+  ├─ Application Controller
+  │   ├─ permission / calibration orchestration
+  │   ├─ simulation tick
+  │   ├─ audio sample submission
+  │   └─ snapshot publish
+  │
+  ├─ Pure Domain / Simulation
+  │   ├─ BarkBattleSession
+  │   ├─ BarkDetector
+  │   ├─ EnergyTugOfWar
+  │   ├─ BarkBattleScoring
+  │   └─ OpponentStrategy
+  │
+  ├─ Infrastructure Adapters
+  │   ├─ BrowserMicrophoneInput
+  │   ├─ AudioAnalyserSampler
+  │   └─ PhaserGameHost
+  │
+  └─ Phaser Renderer
+      ├─ BootScene
+      ├─ PreloadScene
+      ├─ BattleScene
+      ├─ FxScene / DebugScene（可选）
+      └─ Asset manifest
+```
+
+### 3.2 强制边界
+
+1. `domain/` 不依赖 Phaser、Web Audio、DOM、React、浏览器全局对象或后端 API。
+2. `domain/` 只接收 plain data，例如时间增量、归一化音量样本、对手 power、配置参数。
+3. `application/` 负责编排权限、校准、音频输入、AI 对手、tick 和 snapshot 分发。
+4. Phaser Scene 只消费 `BarkBattleSnapshot`，把 snapshot 映射成 sprite、动画、粒子、camera 和 sound effect；不得持有核心胜负、计数和能量条规则。
+5. DOM HUD 只消费 snapshot 和少量 runtime UI 状态，负责展示、按钮和弹层；不得重复实现核心胜负规则。
+6. 若后续接入平台作品/成绩/排行榜，前端只调用后端 API 和展示投影，不在本地绕过后端生成正式结论。
+
+## 4. 建议目录结构
+
+首版建议以独立 runtime 原型落在 `src/games/bark-battle/`，避免提前侵入平台创作链路。
+
+```text
+src/games/bark-battle/
+  domain/
+    BarkBattleTypes.ts
+    BarkBattleSession.ts
+    BarkDetector.ts
+    EnergyTugOfWar.ts
+    BarkBattleScoring.ts
+    OpponentStrategy.ts
+    __tests__/
+      BarkDetector.test.ts
+      EnergyTugOfWar.test.ts
+      BarkBattleSession.test.ts
+      BarkBattleScoring.test.ts
+
+  application/
+    BarkBattleController.ts
+    BarkBattleConfig.ts
+    BarkBattleSnapshotStore.ts
+    __tests__/
+      BarkBattleController.test.ts
+
+  infrastructure/
+    BrowserMicrophoneInput.ts
+    AudioAnalyserSampler.ts
+    MicrophonePermission.ts
+    __tests__/
+      AudioAnalyserSampler.test.ts
+
+  phaser/
+    BarkBattleGameHost.ts
+    scenes/
+      BarkBattleBootScene.ts
+      BarkBattlePreloadScene.ts
+      BarkBattleScene.ts
+      BarkBattleFxScene.ts
+    assets/
+      barkBattleAssetManifest.ts
+
+  ui/
+    BarkBattleRuntimeShell.tsx
+    BarkBattleHud.tsx
+    BarkBattlePermissionPanel.tsx
+    BarkBattleResultPanel.tsx
+    BarkBattleMobileControls.tsx
+    BarkBattleHud.css
+    __tests__/
+      BarkBattleHud.test.tsx
+      BarkBattlePermissionPanel.test.tsx
+      BarkBattleResultPanel.test.tsx
+```
+
+若后续进入 Genarrative 正式玩法类型闭环，再按 `genarrative-play-type-integration` 扩展到：
+
+```text
+src/components/bark-battle-runtime/BarkBattleRuntimeShell.tsx
+src/components/bark-battle-result/BarkBattleResultView.tsx
+src/services/barkBattleRuntimeClient.ts
+packages/shared/src/contracts/barkBattle.ts
+server-rs/crates/shared-contracts/src/bark_battle.rs
+```
+
+首版不建议直接新增后端表或正式作品链路，除非产品明确要求成绩、发布和广场能力。
+
+## 5. 核心 Domain 类型
+
+### 5.1 基础枚举与数值约定
+
+```ts
+export type BarkBattlePhase =
+  | 'permission'
+  | 'calibration'
+  | 'countdown'
+  | 'playing'
+  | 'finished'
+  | 'unsupported'
+  | 'permission-denied'
+
+export type BarkBattleSide = 'player' | 'opponent'
+
+export type BarkBattleWinner = BarkBattleSide | 'draw' | null
+
+export type BarkBattleDifficulty = 'easy' | 'normal' | 'hard'
+```
+
+关键数值：
+
+- `energy`: `-100..100`，正数偏玩家侧，负数偏对手侧。
+- `currentVolume`: `0..1`，音频采样归一化后的瞬时音量。
+- `recentPeak`: `0..1`，短窗口内峰值。
+- `power`: `0..1` 或 `0..100` 二选一，建议 domain 内统一 `0..1`，HUD 显示再转百分比。
+- `remainingMs`: 单局剩余毫秒。
+
+### 5.2 Snapshot
+
+```ts
+export type BarkBattleSnapshot = {
+  phase: BarkBattlePhase
+  elapsedMs: number
+  remainingMs: number
+  countdownMs: number
+  energy: number
+  player: BarkSideState
+  opponent: BarkSideState
+  winner: BarkBattleWinner
+  result: BarkBattleResult | null
+  lastEvents: BarkBattleVisualEvent[]
+}
+
+export type BarkSideState = {
+  side: BarkBattleSide
+  barkCount: number
+  currentVolume: number
+  recentPeak: number
+  combo: number
+  power: number
+  isBarking: boolean
+  lastBarkAtMs: number | null
+  maxVolume: number
+}
+
+export type BarkBattleResult = {
+  winner: BarkBattleWinner
+  finalEnergy: number
+  playerBarkCount: number
+  playerMaxVolume: number
+  playerAveragePower: number
+  score: number
+}
+```
+
+### 5.3 输入样本与叫声事件
+
+```ts
+export type BarkAudioSample = {
+  atMs: number
+  volume: number
+  peak: number
+  rms: number
+}
+
+export type BarkDetectedEvent = {
+  id: string
+  atMs: number
+  side: BarkBattleSide
+  volume: number
+  strength: number
+  combo: number
+}
+```
+
+### 5.4 视觉事件
+
+视觉事件由 domain 或 application 生成，但只包含 plain data，不包含 Phaser 对象：
+
+```ts
+export type BarkBattleVisualEvent =
+  | {
+      type: 'bark-word'
+      id: string
+      side: BarkBattleSide
+      atMs: number
+      strength: number
+      text: 'BARK' | 'WOOF' | 'WAN' | 'WANGOOF'
+    }
+  | {
+      type: 'shockwave'
+      id: string
+      side: BarkBattleSide
+      atMs: number
+      strength: number
+    }
+  | {
+      type: 'combo-burst'
+      id: string
+      side: BarkBattleSide
+      atMs: number
+      combo: number
+    }
+```
+
+Phaser 只根据这些事件播放一次性特效，并维护已消费事件 ID，避免重复播放。
+
+## 6. Domain 模块职责
+
+### 6.1 BarkDetector
+
+职责：把连续音频样本转换为有效叫声事件。
+
+输入：
+
+- `BarkAudioSample`
+- 校准后的 `ambientNoiseFloor`
+- `barkThreshold`
+- `minBarkGapMs`
+- `minBarkDurationMs`
+- `maxBarkDurationMs`
+
+规则建议：
+
+1. 音量超过动态阈值进入 candidate 状态。
+2. 峰值回落到阈值以下或持续时长达到上限时结束 candidate。
+3. candidate 持续时间在 `80ms..1200ms` 且与上一次有效叫声间隔足够时，记为一次叫声。
+4. 长时间持续噪音不应无限计数，只能按冷却和峰值回落形成新事件。
+5. MVP 不要求识别“是否真狗叫”，先基于音量峰值、时长和间隔判断。
+
+### 6.2 EnergyTugOfWar
+
+职责：更新红蓝拉锯条。
+
+建议公式：
+
+```text
+playerPower = volumeScore * 0.65 + barkRateScore * 0.35 + comboBonus
+opponentPower = opponentStrategy.tick(...)
+energyDelta = (playerPower - opponentPower) * deltaSeconds * balanceFactor
+energy = clamp(energy + energyDelta, -100, 100)
+```
+
+约束：
+
+- `EnergyTugOfWar` 不知道玩家来自麦克风还是 mock input。
+- `EnergyTugOfWar` 不知道 Phaser 能量条宽度。
+- 平衡参数集中在 `BarkBattleConfig`，不要散落在 Scene 或 HUD 中。
+
+### 6.3 BarkBattleSession
+
+职责：管理局内 phase、计时、胜负和 snapshot。
+
+状态机建议：
+
+```text
+permission → calibration → countdown → playing → finished
+        ↘ permission-denied
+        ↘ unsupported
+```
+
+关键规则：
+
+- `countdown` 结束才进入 `playing`。
+- `playing` 时 `remainingMs` 随 tick 递减。
+- `remainingMs <= 0` 后进入 `finished`。
+- `energy > drawThreshold` 判定玩家胜利。
+- `energy < -drawThreshold` 判定对手胜利。
+- `abs(energy) <= drawThreshold` 判定平局。
+
+### 6.4 OpponentStrategy
+
+职责：为单机 MVP 提供对手推动力。
+
+```ts
+export interface OpponentStrategy {
+  tick(input: OpponentTickInput): OpponentTickOutput
+}
+```
+
+普通难度建议：
+
+- 周期性小叫声提供基础压力。
+- 每 3~6 秒一次短爆发。
+- 玩家大幅领先时可轻微增强，但不能追到不可赢。
+
+## 7. Web Audio 输入适配
+
+### 7.1 BrowserMicrophoneInput
+
+职责：封装浏览器麦克风权限与音频流生命周期。
+
+建议 API：
+
+```ts
+export interface MicrophoneInputPort {
+  isSupported(): boolean
+  requestPermission(): Promise<MicrophoneSession>
+  stop(): void
+}
+
+export interface MicrophoneSession {
+  sample(atMs: number): BarkAudioSample
+  stop(): void
+}
+```
+
+实现要点：
+
+1. 使用 `navigator.mediaDevices?.getUserMedia({ audio: true })`。
+2. 在用户点击“开始”后创建或 resume `AudioContext`，避免移动端自动播放策略拦截。
+3. 使用 `AnalyserNode` 读取时域数据，计算 RMS 与 peak。
+4. 输出归一化样本，不把 `MediaStream`、`AudioContext`、`AnalyserNode` 泄漏到 domain。
+5. 退出、重开、页面卸载时停止 track，避免麦克风占用残留。
+
+### 7.2 校准流程
+
+`calibration` 阶段建议持续 `800ms..1500ms`：
+
+1. 收集静默环境样本。
+2. 计算 `ambientNoiseFloor`，例如 `p75` 或均值 + 标准差。
+3. 设置动态阈值：
+
+```text
+barkThreshold = clamp(ambientNoiseFloor + 0.12, 0.18, 0.55)
+```
+
+4. 若环境噪音过高，HUD 给出简短提示和“继续 / 重新校准”入口，但不要把长说明常驻在画面上。
+
+### 7.3 权限与错误分类
+
+```ts
+export type MicrophoneFailureReason =
+  | 'unsupported'
+  | 'permission-denied'
+  | 'not-found'
+  | 'not-readable'
+  | 'audio-context-blocked'
+  | 'unknown'
+```
+
+前端只根据错误分类展示可操作状态：重试授权、返回、或使用调试备用输入。不要把浏览器原始错误堆栈展示给玩家。
+
+## 8. Phaser Scene 切分
+
+### 8.1 BarkBattleBootScene
+
+职责：
+
+- 初始化 Phaser 全局配置。
+- 注册 scale、background color、全局事件桥。
+- 不加载重资源，不处理玩法规则。
+
+### 8.2 BarkBattlePreloadScene
+
+职责：
+
+- 根据 `barkBattleAssetManifest` 加载背景、狗狗 sprite、声浪 FX、拟声词 bitmap / atlas、轻量音效。
+- 使用稳定 manifest key，不在 gameplay 代码中散写文件路径。
+- 加载完成后进入 `BarkBattleScene`。
+
+### 8.3 BarkBattleScene
+
+职责：
+
+- 创建横版舞台、左右狗狗、背景层、声浪层、拟声词层。
+- 每帧读取最新 `BarkBattleSnapshot`。
+- 根据 snapshot 更新：
+  - 狗狗 idle / bark / win / lose 动画
+  - 声浪强度
+  - camera shake
+  - transient bark words
+  - shockwave
+- 把可选的调试输入 action 传给 controller，但不处理麦克风和规则。
+
+不得在 Scene 中实现：
+
+- 叫声计数
+- 胜负判定
+- 能量条规则
+- 权限流程
+- 结算数据计算
+
+### 8.4 BarkBattleFxScene（可选）
+
+如果特效复杂，可拆出叠加 Scene：
+
+- 专门处理拟声词、粒子、冲击波和 camera shake。
+- 通过视觉事件 ID 去重。
+- 对 `prefers-reduced-motion` 或低端设备降级。
+
+首版也可以先把 FX 保持在 `BarkBattleScene` 内，但必须仍然只消费 snapshot / visual events。
+
+## 9. DOM HUD 设计
+
+### 9.1 HUD 层级
+
+DOM HUD 建议覆盖在 Phaser Canvas 上方：
+
+```text
+BarkBattleRuntimeShell
+  ├─ <div className="bark-battle-canvas-host" />
+  └─ <BarkBattleHud snapshot={snapshot} uiState={uiState} />
+```
+
+HUD 分区：
+
+- 顶部：红蓝声浪能量条 + 小型剩余时间。
+- 中央：仅在倒计时、关键提示或结算时短暂展示大号状态。
+- 左右边缘：双方简洁状态，例如叫声次数 / combo chip。
+- 底部角落：麦克风状态、重试、小菜单。
+- 结算：独立居中面板，显示胜负、叫声次数、最大音量、评分、再来一局、返回。
+
+### 9.2 Playfield 保护
+
+遵循 game UI 约束：
+
+1. 正常 playing 阶段保持中心和下中部 playfield 清爽，不常驻长文案。
+2. 不把规则说明、长控制说明、多段提示默认铺在画面上。
+3. 权限、设置、结算使用独立面板或弹层，不在当前面板下面展开一大块内容。
+4. 移动端优先保证顶部能量条、倒计时、狗狗和重试入口可见可点。
+5. 大动效不能遮挡顶部能量条和倒计时。
+
+### 9.3 CSS 设计建议
+
+- 使用局部 CSS class 或 CSS module，避免污染全站。
+- 使用 CSS 变量定义主题：
+  - `--bark-player-color`
+  - `--bark-opponent-color`
+  - `--bark-panel-bg`
+  - `--bark-safe-bottom`
+- 使用 `dvh` / `svh` 和 safe-area inset 处理移动端地址栏与刘海。
+- `pointer-events` 分层：HUD 容器默认 `pointer-events: none`，按钮和面板恢复 `pointer-events: auto`。
+
+## 10. 移动端与权限降级
+
+### 10.1 移动端输入约束
+
+移动端浏览器通常要求用户手势才能启动 AudioContext。开局流程必须是：
+
+```text
+玩家点击“开始” → requestPermission → 创建/恢复 AudioContext → calibration → countdown → playing
+```
+
+不要在页面加载时自动请求或自动启动 AudioContext。
+
+### 10.2 响应式布局
+
+移动端建议：
+
+- 横屏优先呈现完整舞台；竖屏可保持舞台居中并缩小 HUD。
+- 顶部能量条高度保持可读，但不要占满大面积。
+- 结算面板宽度使用 `min(92vw, 420px)`。
+- 底部按钮避开 `env(safe-area-inset-bottom)`。
+- 非关键设置折叠进小菜单。
+
+### 10.3 权限失败降级
+
+权限失败时：
+
+- `unsupported`：展示“当前浏览器不支持麦克风输入”，提供返回入口。
+- `permission-denied`：展示简短说明和“重新授权”入口。
+- `not-found`：提示未检测到麦克风，提供返回入口。
+- `audio-context-blocked`：提示点击重试。
+
+可选开发调试降级：
+
+- 本地 dev 可启用键盘 mock input，例如按住空格模拟音量峰值。
+- mock input 必须标记为开发/调试能力，不作为正式竞技能力。
+
+## 11. 测试策略
+
+### 11.1 Domain 单元测试（优先）
+
+目标：不接 Phaser、不接 DOM、不接 Web Audio。
+
+建议测试：
+
+- `BarkDetector`：超过阈值且间隔足够时计为一次有效叫声。
+- `BarkDetector`：持续噪音不会无限计数。
+- `BarkDetector`：低于环境噪音阈值不计入叫声。
+- `EnergyTugOfWar`：玩家 power 高于对手时 energy 向玩家侧移动。
+- `EnergyTugOfWar`：energy clamp 在 `-100..100`。
+- `BarkBattleSession`：倒计时结束进入 playing。
+- `BarkBattleSession`：剩余时间归零进入 finished。
+- `BarkBattleSession`：按 energy 和 drawThreshold 判定胜 / 负 / 平。
+
+### 11.2 Application 测试
+
+目标：验证输入样本、AI、tick 和 snapshot 编排。
+
+建议测试：
+
+- 权限允许后进入校准，再进入倒计时。
+- 权限拒绝后 phase 为 `permission-denied`，不进入 playing。
+- 提交 mock audio sample 后 snapshot 中玩家状态更新。
+- AI 对手 power 参与能量条拉锯。
+- `lastEvents` 只发布新增视觉事件。
+
+### 11.3 HUD 组件测试
+
+目标：验证 snapshot 到 DOM 的展示映射。
+
+建议测试：
+
+- playing 阶段展示倒计时和能量条。
+- energy 正负值映射到玩家 / 对手侧比例。
+- permission-denied 展示重试入口。
+- finished 展示胜负、叫声次数和再来一局。
+- 移动端 class / 结构不依赖 Phaser Canvas 才能渲染。
+
+### 11.4 Phaser 集成与 smoke
+
+自动化层面不强行在 Vitest 中完整启动 Phaser。建议：
+
+- 用 adapter mock 测试 Scene 消费 snapshot 的纯映射函数。
+- 浏览器 smoke 验证真实 Canvas、Web Audio 和动画。
+- 若后续引入 Playwright，再做最小视觉和交互 smoke。
+
+## 12. 验证命令建议
+
+文档阶段只需要编码检查和 diff 检查：
+
+```bash
+npm run check:encoding
+git diff -- docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md
+```
+
+后续实现 domain 后建议：
+
+```bash
+npm run test -- --run src/games/bark-battle/domain/**/*.test.ts
+npm run typecheck
+npm run check:encoding
+```
+
+后续实现 HUD 后建议：
+
+```bash
+npm run test -- --run src/games/bark-battle/ui/**/*.test.tsx
+npm run lint:eslint
+npm run typecheck
+npm run check:encoding
+```
+
+后续接入浏览器 runtime 后建议：
+
+```bash
+npm run dev:web
+# 人工 smoke：授权麦克风 → 校准 → 发声 → 能量条变化 → 结算 → 再来一局
+```
+
+若未来接入 Genarrative 正式玩法类型、后端持久化或发布链路，再追加对应契约、api-server 和 SpacetimeDB 验证；首版 runtime 原型不应提前新增这些命令作为门槛。
+
+## 13. 后续落地顺序
+
+建议后续实现按以下顺序推进：
+
+1. 先建 `domain/` 和纯单元测试。
+2. 实现 `BarkDetector`、`EnergyTugOfWar`、`BarkBattleSession` 的最小规则。
+3. 建 `application/` controller，用 mock audio sample 跑通 snapshot。
+4. 实现 DOM HUD 的 permission / energy / timer / result 展示。
+5. 接入 `BrowserMicrophoneInput` 和校准流程。
+6. 接入 Phaser host、Scene 和 asset manifest，占位素材先跑通视觉反馈。
+7. 做移动端视口和权限失败 smoke。
+8. 产品确认后再决定是否进入正式玩法类型、作品发布和后端真相链。
+
+## 14. 关键技术决策
+
+1. 默认采用 Phaser 3 + TypeScript + Vite，符合 2D 浏览器游戏默认路线。
+2. 核心 simulation 放在纯 TypeScript domain，严格不依赖 Phaser / Web Audio / DOM。
+3. Web Audio 只作为输入 adapter，输出归一化 `BarkAudioSample`。
+4. Phaser Scene 是 renderer，只消费 snapshot 和 visual events，不承载规则真相。
+5. HUD 使用 DOM overlay，承载权限、能量条、倒计时、结算和移动端响应式布局。
+6. MVP 不做复杂狗叫语义识别，先用音量峰值、持续时长、冷却和环境噪音校准。
+7. MVP 建议玩家 vs AI 单机 runtime，正式成绩、排行榜、发布和奖励后续再交给后端链路。

docs/technical/README.md

@@ -4,6 +4,7 @@
 
 ## 文档列表
 
+- [BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md](./BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md)：冻结“汪汪声浪大作战 / bark-battle”2D 浏览器 runtime 技术方案，明确 Phaser + TypeScript + Vite 选型、纯 TS simulation 与 Phaser renderer/DOM HUD 边界、Web Audio 输入适配、移动端权限降级和后续测试验证命令。
 - [CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md](./CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md)：冻结儿童动作识别互动玩法 Demo 固定热身关的开发落地规格，覆盖横屏展示、摄像头背景虚化、角色剪影、绿色圆环 2 秒保持、动作教学、当前会话内空间边界记录和后续关卡安全暂停规则。
 - [RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md](./RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md)：记录运行态输入设备抽象层，明确鼠标、触控、mocap 等设备统一归一为通用拖拽语义，玩法组件只负责解释目标和落点。
 - [RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md](./RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md)：记录 `server-rs` Cargo 依赖集中配置口径，第三方版本和 workspace 内部 crate path 统一维护在根 `server-rs/Cargo.toml`，成员 crate 只保留 feature/optional 差异。