2026-05-13 13:23:09 +08:00
32 changed files with 2244 additions and 18 deletions
--- a/.hermes/plans/2026-05-11_170028-bark-battle-three-phase-browser-ai-db-plan.md
+++ b/.hermes/plans/2026-05-11_170028-bark-battle-three-phase-browser-ai-db-plan.md
@@ -0,0 +1,709 @@
+# bark-battle 三阶段实施计划：浏览器原型 → AI 创作入口 → 数据库落地
+
+> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
+
+**Goal:** 按“三阶段”推进 `bark-battle / 汪汪声浪大作战`：第一阶段先做纯浏览器可运行游戏原型并验证玩法跑通；第二阶段接入 Genarrative 创作入口，用 AI 生成可试玩内容；第三阶段再打通后端数据库、发布、成绩和作品闭环。
+
+**Architecture:** 第一阶段只在前端 runtime 内闭环，优先落 `src/games/bark-battle/` 与直达路由，不依赖后端和 SpacetimeDB。第二阶段在已有创作入口、Agent flow controller、结果页和 runtime shell 上接入 `bark-battle`，AI 只生成配置化草稿，不承接正式业务真相。第三阶段按 `server-rs + Axum + SpacetimeDB` DDD 分层落库，前端只展示后端投影和调用后端 API。
+
+**Tech Stack:** React 19、TypeScript、Vite、Vitest、Testing Library；第一阶段优先 DOM/Canvas 原型，可在验证玩法后再引入 Phaser 3；后端阶段使用 `server-rs`、Axum、SpacetimeDB、shared-contracts。
+
+---
+
+## 0. 当前上下文 / 假设
+
+- 现有需求与技术文档：
+  - `docs/prd/BARK_BATTLE_BDD_2026-05-11.md`
+  - `docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md`
+  - `docs/technical/BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md`
+- 用户明确要求阶段顺序：
+  1. 第一阶段：先制作纯浏览器运行的游戏原型，需要测试游戏功能是否能跑通。
+  2. 第二阶段：打通创作入口，使用 AI 赋能游戏内容创作。
+  3. 第三阶段：最后打通数据库落地。
+- 因此本计划调整原技术方案中的落地优先级：
+  - 第一阶段不新增后端表、不接发布、不接作品架。
+  - 第一阶段可以用 mock / local draft 配置与直达路由 `/bark-battle` 完成 playable prototype。
+  - 第一阶段若 Phaser 依赖尚未安装，优先用 React DOM + Canvas/CSS 2D 原型跑通功能；待核心规则验证后再决定是否引入 Phaser，避免第一阶段被依赖安装和素材管线阻塞。
+- 当前仓库 `package.json` 还没有 `phaser` 依赖；如实现者选择 Phaser，需要单独评估依赖引入、包体和测试影响。
+- 本计划只写计划，不直接实现代码。
+
+## 1. 总体分阶段验收口径
+
+### Phase 1：纯浏览器游戏原型
+
+目标：打开本地前端路由即可玩到一局 `bark-battle`，并通过自动测试确认核心规则跑通。
+
+必须满足：
+- 可从 `/bark-battle` 进入独立原型页面。
+- 不登录、不请求后端、不依赖数据库。
+- 支持开发 mock input：点击/按键/按钮可模拟音量峰值；有真实麦克风时可走 Web Audio。
+- 能完成：权限/开始 → 校准或 mock 准备 → 倒计时 → 30 秒 playing → 结算 → 再来一局。
+- 低于阈值输入不计数；有效叫声计数；能量条向玩家或对手移动；结算胜/负/平。
+- 移动端至少能看到能量条、倒计时、双方狗狗、主要按钮和结算。
+
+### Phase 2：AI 创作入口
+
+目标：创作者能从创作中心选择 `bark-battle`，用 AI 生成玩法配置草稿，并进入结果页试玩。
+
+必须满足：
+- 后端入口配置中出现 `bark-battle`，按开关展示/可点击。
+- 前端类型分流、SelectionStage、工作台、结果页、runtime 入口齐全。
+- AI 生成内容仅限配置化草稿：标题、主题、狗狗外观描述、背景风格、难度、局长、AI 对手参数、提示文案 key 等。
+- 生成结果可在本地 runtime 中试玩。
+- 未落库前可先用 session/local state 保存草稿，但要清楚标识为“未发布草稿”。
+
+### Phase 3：数据库落地与正式作品闭环
+
+目标：`bark-battle` 草稿、发布态配置、runtime start/finish、成绩和作品级游玩埋点都进入后端 DDD / SpacetimeDB 链路。
+
+必须满足：
+- `shared-contracts`、`module-bark-battle`、`spacetime-module`、`spacetime-client`、`api-server` 分层清晰。
+- 发布为稳定作品 ID，runtime 从后端读取发布态 config。
+- start 成功写 `work_play_start`：`scope_kind=work`、`scope_id=稳定作品 ID`、metadata 包含 `playType/workId/sourceRoute/userId`。
+- finish 只上传派生指标，不保存原始麦克风音频、波形或可还原语音内容。
+- 作品架/广场/分享/排行榜如启用，均来自后端投影。
+
+---
+
+## 2. Phase 1：纯浏览器运行游戏原型
+
+### Task 1.1：补齐阶段边界文档
+
+**Objective:** 在现有技术方案中明确“先浏览器原型，后 AI 创作，最后数据库”的落地顺序，避免实现时过早接后端。
+
+**Files:**
+- Modify: `docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md`
+- Modify: `docs/prd/BARK_BATTLE_BDD_2026-05-11.md`
+
+**Steps:**
+1. 在 runtime 技术方案中新增“三阶段落地顺序”小节。
+2. 明确 Phase 1 不接后端、不接数据库、不接创作入口事实源。
+3. 在 BDD 中补充“浏览器原型 smoke”验收场景。
+4. 运行：
+   ```bash
+   npm run check:encoding -- docs/prd/BARK_BATTLE_BDD_2026-05-11.md docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md
+   git diff --check
+   ```
+
+**Expected:** 编码检查和 diff 空白检查通过。
+
+### Task 1.2：建立 Phase 1 目录骨架和类型
+
+**Objective:** 建立不依赖 React/DOM/Web Audio 的核心类型，后续所有测试和 UI 都围绕这些类型。
+
+**Files:**
+- Create: `src/games/bark-battle/domain/BarkBattleTypes.ts`
+- Create: `src/games/bark-battle/application/BarkBattleConfig.ts`
+
+**Key design:**
+- `BarkBattlePhase = 'permission' | 'calibration' | 'countdown' | 'playing' | 'finished' | 'unavailable'`
+- `MicrophoneFailureReason` 覆盖已有文档中的 9 类失败原因。
+- `BarkBattleSnapshot` 包含 `phase/uiState/errorReason/statusMessageKey/remainingMs/energy/player/opponent/winner/result/lastEvents`。
+- `BarkBattleConfig` 包含 `roundDurationMs/drawThreshold/minBarkGapMs/minBarkDurationMs/maxBarkDurationMs/balanceFactor/calibrationMaxWaitMs`。
+
+**Tests:**
+- 本任务可先不写运行时逻辑，但需要让 typecheck 能引用这些类型。
+
+**Validation:**
+```bash
+npm run typecheck
+npm run check:encoding -- src/games/bark-battle/domain/BarkBattleTypes.ts src/games/bark-battle/application/BarkBattleConfig.ts
+```
+
+### Task 1.3：TDD 实现叫声检测 BarkDetector
+
+**Objective:** 用纯函数/纯类把音频样本转换为有效叫声事件。
+
+**Files:**
+- Create: `src/games/bark-battle/domain/BarkDetector.ts`
+- Create: `src/games/bark-battle/domain/__tests__/BarkDetector.test.ts`
+
+**Test cases:**
+1. 超过阈值、持续时长合规、间隔足够时计为一次有效叫声。
+2. 持续噪音不在每个 tick 无限计数。
+3. 低于阈值的背景噪音不计数。
+4. `minBarkGapMs` 内连续峰值不重复计数。
+5. 过短脉冲不计数；过长持续声削弱为单段输入。
+
+**Validation:**
+```bash
+npm run test -- --run src/games/bark-battle/domain/__tests__/BarkDetector.test.ts
+npm run typecheck
+```
+
+### Task 1.4：TDD 实现能量条 EnergyTugOfWar
+
+**Objective:** 验证玩家/对手推动力能稳定改变 `energy`，并 clamp 到 `-100..100`。
+
+**Files:**
+- Create: `src/games/bark-battle/domain/EnergyTugOfWar.ts`
+- Create: `src/games/bark-battle/domain/__tests__/EnergyTugOfWar.test.ts`
+
+**Test cases:**
+1. 玩家 power 高于对手时 `energy` 增加。
+2. 对手 power 高于玩家时 `energy` 减少。
+3. energy 不超过 `100`。
+4. energy 不低于 `-100`。
+5. power 相等时变化不超过浮点误差。
+
+**Validation:**
+```bash
+npm run test -- --run src/games/bark-battle/domain/__tests__/EnergyTugOfWar.test.ts
+npm run typecheck
+```
+
+### Task 1.5：TDD 实现单局状态机 BarkBattleSession
+
+**Objective:** 跑通 permission/calibration/countdown/playing/finished/unavailable 状态流转和结算。
+
+**Files:**
+- Create: `src/games/bark-battle/domain/BarkBattleSession.ts`
+- Create: `src/games/bark-battle/domain/BarkBattleScoring.ts`
+- Create: `src/games/bark-battle/domain/OpponentStrategy.ts`
+- Create: `src/games/bark-battle/domain/__tests__/BarkBattleSession.test.ts`
+- Create: `src/games/bark-battle/domain/__tests__/BarkBattleScoring.test.ts`
+
+**Test cases:**
+1. 校准完成后进入 countdown。
+2. countdown 结束后进入 playing。
+3. playing 中 `remainingMs` 随 tick 递减。
+4. `remainingMs <= 0` 后进入 finished。
+5. `energy > drawThreshold` 判定玩家胜。
+6. `energy < -drawThreshold` 判定对手胜。
+7. `abs(energy) <= drawThreshold` 判定平局。
+8. finished 后新输入不再改变本局计数和能量。
+
+**Validation:**
+```bash
+npm run test -- --run src/games/bark-battle/domain/__tests__/BarkBattleSession.test.ts src/games/bark-battle/domain/__tests__/BarkBattleScoring.test.ts
+npm run typecheck
+```
+
+### Task 1.6：实现 mock-first Application Controller
+
+**Objective:** 不依赖真实麦克风，先用 mock audio sample 驱动完整 snapshot。
+
+**Files:**
+- Create: `src/games/bark-battle/application/BarkBattleController.ts`
+- Create: `src/games/bark-battle/application/BarkBattleSnapshotStore.ts`
+- Create: `src/games/bark-battle/application/__tests__/BarkBattleController.test.ts`
+
+**Behavior:**
+- `startWithMockInput()` 进入校准完成或直接 countdown。
+- `submitMockSample(sample)` 更新玩家输入。
+- `tick(deltaMs)` 推进对手、能量条、倒计时。
+- `restart()` 重置状态。
+- `failMicrophone(reason)` 进入 `phase: 'unavailable'`，并设置 `errorReason/statusMessageKey`。
+
+**Test cases:**
+1. mock start 后能进入 countdown/playing。
+2. 提交 mock 峰值后 bark count 增加。
+3. tick 后 energy 可变化。
+4. finish 后生成 result。
+5. `failMicrophone('permission-denied')` 不进入 playing。
+
+**Validation:**
+```bash
+npm run test -- --run src/games/bark-battle/application/__tests__/BarkBattleController.test.ts
+npm run typecheck
+```
+
+### Task 1.7：实现浏览器原型 UI Shell（不接平台）
+
+**Objective:** 提供 `/bark-battle` 可访问的 playable prototype。
+
+**Files:**
+- Create: `src/BarkBattlePlaygroundApp.tsx`
+- Create: `src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx`
+- Create: `src/games/bark-battle/ui/BarkBattleHud.tsx`
+- Create: `src/games/bark-battle/ui/BarkBattleResultPanel.tsx`
+- Create: `src/games/bark-battle/ui/BarkBattleHud.css`
+- Modify: `src/routing/appRoutes.tsx`
+
+**Behavior:**
+- 新增路由匹配：`/bark-battle`。
+- 首屏只有清爽开始面板，不常驻大段规则。
+- 提供开发原型按钮：开始、模拟叫声、模拟对手增强、再来一局。
+- playing 画面展示：顶部能量条、倒计时、玩家/对手狗狗、叫声次数、麦克风/mock 状态。
+- 结算面板独立居中，不追加在当前面板下方。
+
+**UI constraints:**
+- 移动端优先。
+- 正常 playing 阶段不在 playfield 常驻规则说明。
+- 大动效不遮挡顶部能量条和倒计时。
+
+**Validation:**
+```bash
+npm run test -- --run src/games/bark-battle/ui/**/*.test.tsx
+npm run typecheck
+npm run dev:web
+# 手动 smoke: 访问 /bark-battle → 开始 → 模拟叫声 → energy 变化 → 结算 → 再来一局
+```
+
+### Task 1.8：实现 HUD 组件测试
+
+**Objective:** 自动验证核心 UI 状态，不只依赖人工试玩。
+
+**Files:**
+- Create: `src/games/bark-battle/ui/__tests__/BarkBattleHud.test.tsx`
+- Create: `src/games/bark-battle/ui/__tests__/BarkBattleResultPanel.test.tsx`
+
+**Test cases:**
+1. playing 阶段展示倒计时和能量条。
+2. energy 正值时玩家侧占比更大。
+3. energy 负值时对手侧占比更大。
+4. permission-denied 展示重试授权入口。
+5. unsupported 不展示开始声控按钮。
+6. finished 展示胜负、叫声次数、再来一局。
+
+**Validation:**
+```bash
+npm run test -- --run src/games/bark-battle/ui/__tests__/BarkBattleHud.test.tsx src/games/bark-battle/ui/__tests__/BarkBattleResultPanel.test.tsx
+npm run typecheck
+```
+
+### Task 1.9：接入真实 Web Audio（可晚于 mock 原型）
+
+**Objective:** 在支持麦克风的浏览器中真实采样并驱动 controller，同时保留 mock fallback 便于测试。
+
+**Files:**
+- Create: `src/games/bark-battle/infrastructure/BrowserMicrophoneInput.ts`
+- Create: `src/games/bark-battle/infrastructure/AudioAnalyserSampler.ts`
+- Create: `src/games/bark-battle/infrastructure/MicrophonePermission.ts`
+- Create: `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`
+- Create: `src/games/bark-battle/infrastructure/__tests__/AudioAnalyserSampler.test.ts`
+
+**Behavior:**
+- 用户点击开始后才请求麦克风。
+- 用户手势后创建/resume `AudioContext`。
+- 输出归一化 `BarkAudioSample`。
+- 捕获并映射：unsupported、permission-denied、non-secure-context、not-found、not-readable、audio-context-blocked、unknown。
+- stop/restart/page unload 时停止 tracks。
+
+**Validation:**
+```bash
+npm run test -- --run src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts src/games/bark-battle/infrastructure/__tests__/AudioAnalyserSampler.test.ts
+npm run typecheck
+npm run dev:web
+# 手动 smoke: 真实麦克风授权 → 校准 → 发声 → 结算
+```
+
+### Task 1.10：Phase 1 收口验证
+
+**Objective:** 确认“纯浏览器原型”已经可以交给产品/测试试玩。
+
+**Commands:**
+```bash
+npm run test -- --run src/games/bark-battle/domain/**/*.test.ts src/games/bark-battle/application/**/*.test.ts src/games/bark-battle/infrastructure/**/*.test.ts src/games/bark-battle/ui/**/*.test.tsx
+npm run typecheck
+npm run lint:eslint
+npm run check:encoding
+npm run dev:web
+```
+
+**Manual smoke checklist:**
+- [ ] `/bark-battle` 能打开。
+- [ ] mock 模式可完整完成一局。
+- [ ] 真实麦克风模式可授权、校准、发声、结算。
+- [ ] 拒绝权限后不会进入 playing。
+- [ ] 移动端窄屏能看到核心信息并能点击主要按钮。
+- [ ] 再来一局不会继承上一局 energy/barkCount/result。
+
+---
+
+## 3. Phase 2：打通创作入口，用 AI 赋能内容创作
+
+### Task 2.1：定义 `bark-battle` 草稿契约（前端本地版）
+
+**Objective:** 在接后端前，先定义 AI 可生成的 runtime draft shape。
+
+**Files:**
+- Create: `packages/shared/src/contracts/barkBattle.ts`（临时前端共享类型，后端阶段再对齐 Rust shared-contracts）
+- Create: `src/services/bark-battle-creation/barkBattleDraftDefaults.ts`
+- Create: `src/services/bark-battle-creation/barkBattleDraftValidation.ts`
+
+**Draft fields:**
+- `title`
+- `description`
+- `themePrompt`
+- `playerDogName`
+- `opponentDogName`
+- `backgroundStyle`
+- `difficulty`
+- `roundDurationMs`
+- `drawThreshold`
+- `opponentConfig`
+- `audioSensitivityPreset`
+- `visualStyle`
+
+**Validation:**
+```bash
+npm run test -- --run src/services/bark-battle-creation/**/*.test.ts
+npm run typecheck
+```
+
+### Task 2.2：新增创作入口配置
+
+**Objective:** 让 `bark-battle` 出现在创作中心入口中，但可通过后端入口配置开关控制。
+
+**Files likely to change:**
+- `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs`
+- `server-rs/crates/module-runtime/src/domain.rs`
+- `server-rs/crates/module-runtime/src/application.rs`
+- `server-rs/crates/shared-contracts/src/creation_entry_config.rs`
+- `src/components/platform-entry/platformEntryCreationTypes.ts`
+- `src/components/platform-entry/platformEntryCreationTypes.test.ts`
+
+**Plan:**
+1. 在入口 seed 中新增 `bark-battle`，首轮可设：`visible: true`、`open: true`（若需要灰度则 `open: false`）。
+2. 前端展示派生只消费 API 返回，不恢复旧静态入口事实源。
+3. 更新排序和锁定态测试。
+
+**Validation:**
+```bash
+npm run test -- src/components/platform-entry/platformEntryCreationTypes.test.ts
+npm run typecheck
+cd server-rs && cargo check -p api-server -p spacetime-module --no-default-features
+```
+
+### Task 2.3：扩展 SelectionStage 与流程分流
+
+**Objective:** 点击 `bark-battle` 入口后进入对应创作工作台。
+
+**Files likely to change:**
+- `src/components/platform-entry/platformEntryTypes.ts`
+- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+- `src/components/platform-entry/usePlatformCreationAgentFlowController.ts`（如复用通用 agent flow）
+
+**Stages:**
+- `bark-battle-agent-workspace`
+- `bark-battle-generating`（可选）
+- `bark-battle-result`
+- `bark-battle-runtime`
+
+**Validation:**
+```bash
+npm run test -- src/components/platform-entry/**/*.test.tsx src/components/platform-entry/**/*.test.ts
+npm run typecheck
+```
+
+### Task 2.4：实现 AI 创作工作台
+
+**Objective:** 用对话式或表单式输入生成 `BarkBattleDraft`。
+
+**Files:**
+- Create: `src/components/bark-battle-creation/BarkBattleAgentWorkspace.tsx`
+- Create: `src/services/bark-battle-creation/barkBattleCreationClient.ts`
+- Create: `src/services/bark-battle-creation/barkBattlePromptBuilder.ts`
+- Create: `src/services/bark-battle-creation/__tests__/barkBattlePromptBuilder.test.ts`
+
+**Behavior:**
+- 用户输入一句主题，例如“柴犬在赛博公园比谁叫得响”。
+- AI 返回结构化草稿。
+- 前端校验并填默认值，不让非法 roundDuration/difficulty 进入 runtime。
+- 错误时保留用户输入和已生成草稿。
+
+**Validation:**
+```bash
+npm run test -- --run src/services/bark-battle-creation/**/*.test.ts
+npm run typecheck
+```
+
+### Task 2.5：实现结果页与试玩入口
+
+**Objective:** AI 草稿生成后可查看、返回编辑、进入 Phase 1 runtime 试玩。
+
+**Files:**
+- Create: `src/components/bark-battle-result/BarkBattleResultView.tsx`
+- Create: `src/components/bark-battle-result/BarkBattleResultView.test.tsx`
+- Modify: `src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx`（允许传入 draft config）
+
+**Behavior:**
+- 展示标题、主题、狗狗名、背景风格、难度、局长。
+- 提供“返回编辑”“试玩”按钮。
+- 暂不展示发布按钮，或发布按钮显示为后端阶段能力。
+
+**Validation:**
+```bash
+npm run test -- --run src/components/bark-battle-result/BarkBattleResultView.test.tsx
+npm run typecheck
+npm run dev:web
+# 手动 smoke: 创作入口 → AI 草稿 → 结果页 → 试玩 → 返回编辑
+```
+
+### Task 2.6：Phase 2 收口验证
+
+**Commands:**
+```bash
+npm run test -- src/components/platform-entry/platformEntryCreationTypes.test.ts src/components/bark-battle-result/BarkBattleResultView.test.tsx src/services/bark-battle-creation/**/*.test.ts src/games/bark-battle/**/*.test.ts src/games/bark-battle/**/*.test.tsx
+npm run typecheck
+npm run lint:eslint
+npm run check:encoding
+```
+
+**Manual smoke checklist:**
+- [ ] 创作中心展示 `bark-battle`。
+- [ ] 点击入口进入工作台。
+- [ ] AI 可生成草稿。
+- [ ] 草稿结果页可展示并返回编辑。
+- [ ] 试玩使用草稿配置影响 runtime 表现。
+- [ ] 未接数据库前不会假装发布成功。
+
+---
+
+## 4. Phase 3：数据库落地与正式作品闭环
+
+### Task 3.1：补齐 shared contracts
+
+**Objective:** 前后端共享 bark-battle DTO，避免前端手写正式契约漂移。
+
+**Files likely to change:**
+- `server-rs/crates/shared-contracts/src/bark_battle.rs`
+- `server-rs/crates/shared-contracts/src/lib.rs`
+- `packages/shared/src/contracts/barkBattle.ts`
+
+**DTO:**
+- `BarkBattleDraft`
+- `BarkBattlePublishedConfig`
+- `CreateBarkBattleSessionRequest/Response`
+- `BarkBattleRuntimeStartRequest/Response`
+- `BarkBattleRuntimeFinishRequest/Response`
+- `BarkBattleRunResult`
+- `BarkBattleScoreSummary`
+- `BarkBattleLeaderboardEntry`
+
+**Validation:**
+```bash
+npm run typecheck
+cd server-rs && cargo check -p shared-contracts --no-default-features
+```
+
+### Task 3.2：新增 `module-bark-battle` 纯领域模块
+
+**Objective:** 后端正式分数、配置校验、提交合法性不写在 api-server handler 里。
+
+**Files:**
+- Create: `server-rs/crates/module-bark-battle/`
+- Modify: `server-rs/Cargo.toml`
+
+**Responsibilities:**
+- 配置合法性校验。
+- run start/finish 状态约束。
+- 派生指标范围校验。
+- 分数与排行榜排序分计算。
+- 不接 Axum、不接 SpacetimeDB、不接 HTTP。
+
+**Validation:**
+```bash
+cd server-rs && cargo test -p module-bark-battle --no-default-features
+cd server-rs && cargo check -p module-bark-battle --no-default-features
+```
+
+### Task 3.3：SpacetimeDB 表、reducer、migration
+
+**Objective:** 保存草稿、发布态配置、run、result、leaderboard 投影。
+
+**Files likely to change:**
+- `server-rs/crates/spacetime-module/src/runtime/bark_battle.rs`（或按现有模块目录命名）
+- `server-rs/crates/spacetime-module/src/migration.rs`
+- `server-rs/crates/spacetime-module/src/lib.rs`
+- 生成绑定目录（通过命令生成，不手改生成物）
+
+**Tables draft:**
+- `bark_battle_draft`
+- `bark_battle_published_config`
+- `bark_battle_run`
+- `bark_battle_run_result`
+- `bark_battle_leaderboard_entry`
+
+**Reducers/procedures:**
+- `create_bark_battle_draft`
+- `publish_bark_battle_config`
+- `start_bark_battle_run`
+- `finish_bark_battle_run`
+- `list_bark_battle_leaderboard`
+
+**Validation:**
+```bash
+npm run spacetime:generate
+cd server-rs && cargo check -p spacetime-module --no-default-features
+npm run check:server-rs-ddd
+```
+
+### Task 3.4：spacetime-client facade
+
+**Objective:** api-server 通过 facade 调用 SpacetimeDB，不直接散落 reducer 细节。
+
+**Files likely to change:**
+- `server-rs/crates/spacetime-client/src/runtime.rs`
+- `server-rs/crates/spacetime-client/src/mapper.rs`
+- `server-rs/crates/spacetime-client/src/lib.rs`
+
+**Validation:**
+```bash
+cd server-rs && cargo check -p spacetime-client --no-default-features
+```
+
+### Task 3.5：api-server BFF 路由
+
+**Objective:** 提供创作、发布态 runtime start/finish、leaderboard API。
+
+**Files likely to change:**
+- `server-rs/crates/api-server/src/bark_battle.rs`
+- `server-rs/crates/api-server/src/main.rs` 或路由注册文件
+
+**Routes draft:**
+- `POST /api/bark-battle/sessions`
+- `GET /api/bark-battle/sessions/:sessionId`
+- `POST /api/bark-battle/runtime/start`
+- `POST /api/bark-battle/runtime/finish`
+- `GET /api/bark-battle/works/:workId/runtime-config`
+- `GET /api/bark-battle/works/:workId/leaderboard`
+
+**Tracking:**
+- runtime start 成功后主动写 `work_play_start`。
+- `scope_kind=work`。
+- `scope_id=稳定作品 ID`。
+- metadata 包含 `playType=bark-battle`、`workId`、`sourceRoute`、`userId`。
+
+**Validation:**
+```bash
+npm run api-server
+# 另一个终端检查 /healthz，并执行对应 API smoke
+cd server-rs && cargo check -p api-server --no-default-features
+```
+
+### Task 3.6：前端正式 client 与 runtime 切换
+
+**Objective:** runtime 从本地草稿模式升级为可读取后端发布态 config，并提交正式派生结果。
+
+**Files likely to change:**
+- Create: `src/services/bark-battle-runtime/barkBattleRuntimeClient.ts`
+- Create: `src/services/bark-battle-works/barkBattleWorksClient.ts`
+- Modify: `src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx`
+- Modify: `src/components/bark-battle-result/BarkBattleResultView.tsx`
+- Modify: `src/components/custom-world-home/creationWorkShelf.ts`
+- Modify: `src/components/custom-world-home/CustomWorldCreationHub.tsx`
+- Modify: `src/services/publicWorkCode.ts`
+
+**Behavior:**
+- 本地 preview 仍可使用 draft config。
+- 正式作品 runtime 必须先调用 start API，拿 run token/session。
+- finish 只提交派生 metrics。
+- 发布后刷新作品架/广场。
+
+**Validation:**
+```bash
+npm run test -- src/services/bark-battle-runtime/**/*.test.ts src/games/bark-battle/**/*.test.ts src/games/bark-battle/**/*.test.tsx
+npm run typecheck
+npm run check:encoding
+```
+
+### Task 3.7：Phase 3 收口验证
+
+**Commands:**
+```bash
+npm run test -- src/games/bark-battle/**/*.test.ts src/games/bark-battle/**/*.test.tsx src/services/bark-battle-runtime/**/*.test.ts src/services/bark-battle-creation/**/*.test.ts
+npm run typecheck
+npm run lint:eslint
+npm run check:encoding
+npm run check:server-rs-ddd
+cd server-rs && cargo test -p module-bark-battle --no-default-features
+cd server-rs && cargo check -p api-server -p spacetime-module -p spacetime-client -p shared-contracts --no-default-features
+npm run api-server
+```
+
+**Manual smoke checklist:**
+- [ ] 创作者生成并发布 bark-battle 作品。
+- [ ] 玩家从作品页进入 runtime。
+- [ ] start API 成功并写 `work_play_start`。
+- [ ] 浏览器本地完成一局。
+- [ ] finish API 只上传派生指标。
+- [ ] 成绩/排行榜/作品架刷新来自后端投影。
+- [ ] 拒绝麦克风权限时不会创建非法 finished result。
+
+---
+
+## 5. 文件清单总览
+
+### Phase 1 likely files
+
+- `src/routing/appRoutes.tsx`
+- `src/BarkBattlePlaygroundApp.tsx`
+- `src/games/bark-battle/domain/BarkBattleTypes.ts`
+- `src/games/bark-battle/domain/BarkDetector.ts`
+- `src/games/bark-battle/domain/EnergyTugOfWar.ts`
+- `src/games/bark-battle/domain/BarkBattleSession.ts`
+- `src/games/bark-battle/domain/BarkBattleScoring.ts`
+- `src/games/bark-battle/domain/OpponentStrategy.ts`
+- `src/games/bark-battle/application/BarkBattleConfig.ts`
+- `src/games/bark-battle/application/BarkBattleController.ts`
+- `src/games/bark-battle/application/BarkBattleSnapshotStore.ts`
+- `src/games/bark-battle/infrastructure/BrowserMicrophoneInput.ts`
+- `src/games/bark-battle/infrastructure/AudioAnalyserSampler.ts`
+- `src/games/bark-battle/infrastructure/MicrophonePermission.ts`
+- `src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx`
+- `src/games/bark-battle/ui/BarkBattleHud.tsx`
+- `src/games/bark-battle/ui/BarkBattleResultPanel.tsx`
+- `src/games/bark-battle/ui/BarkBattleHud.css`
+
+### Phase 2 likely files
+
+- `packages/shared/src/contracts/barkBattle.ts`
+- `src/components/platform-entry/platformEntryTypes.ts`
+- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+- `src/components/platform-entry/platformEntryCreationTypes.ts`
+- `src/components/bark-battle-creation/BarkBattleAgentWorkspace.tsx`
+- `src/components/bark-battle-result/BarkBattleResultView.tsx`
+- `src/services/bark-battle-creation/*`
+
+### Phase 3 likely files
+
+- `server-rs/crates/shared-contracts/src/bark_battle.rs`
+- `server-rs/crates/module-bark-battle/*`
+- `server-rs/crates/spacetime-module/src/runtime/bark_battle.rs`
+- `server-rs/crates/spacetime-module/src/migration.rs`
+- `server-rs/crates/spacetime-client/src/runtime.rs`
+- `server-rs/crates/spacetime-client/src/mapper.rs`
+- `server-rs/crates/api-server/src/bark_battle.rs`
+- `src/services/bark-battle-runtime/*`
+- `src/services/bark-battle-works/*`
+- `src/components/custom-world-home/creationWorkShelf.ts`
+- `src/services/publicWorkCode.ts`
+
+---
+
+## 6. 风险、取舍与开放问题
+
+### 风险
+
+1. **麦克风权限和移动端 AudioContext 差异大。** 需要 mock input 保底，否则自动化和本地开发会被真实设备阻塞。
+2. **第一阶段过早引入 Phaser 可能拖慢验证。** 当前仓库没有 `phaser` 依赖；建议先用 DOM/Canvas 跑通玩法，再决定是否引入 Phaser。
+3. **AI 草稿和正式发布配置容易漂移。** Phase 2 临时 TS 类型必须在 Phase 3 与 Rust shared-contracts 对齐。
+4. **不能保存原始音频。** 后端阶段只能保存派生指标，任何音频片段、波形、频谱明细都不应落库。
+5. **入口配置事实源在后端/SpacetimeDB。** Phase 2 接入口时不要恢复旧前端静态入口配置。
+
+### 取舍
+
+- Phase 1 先把“游戏是否好玩、功能是否跑通”作为第一目标，不追求正式作品闭环。
+- Phase 2 让 AI 生成内容配置，而不是让 AI 直接生成任意代码或不受控规则。
+- Phase 3 再把正式业务真相交给后端，避免前端 runtime 先背上发布、成绩、排行榜的复杂度。
+
+### 开放问题
+
+1. Phase 1 是否必须使用 Phaser？如果只是验证玩法，可先使用 DOM/CSS/Canvas 原型，后续再替换 renderer。
+2. `bark-battle` 的正式中文名是否固定为“汪汪声浪大作战”？如果名称要改，需先统一文档、入口配置和分享标题。
+3. AI 创作阶段是否需要生成图片/狗狗视觉资产，还是只生成风格描述和使用占位素材？
+4. 是否需要排行榜作为 Phase 3 必选，还是作为数据库落地后的增强项？
+5. 真实麦克风 smoke 需要哪些目标设备：Chrome 桌面、Android Chrome、iOS Safari 是否都纳入首批验收？
+
+---
+
+## 7. 建议执行方式
+
+1. 先按 Phase 1 执行，且每个 domain/application task 坚持 TDD：先失败测试，再实现。
+2. Phase 1 合并前不要接数据库，不要新增后端表，不要把入口配置切到 open。
+3. Phase 1 验证通过后，让产品/团队试玩 `/bark-battle`，确认玩法数值和 UI 方向。
+4. 再进入 Phase 2，把 AI 创作工作台接到同一个 runtime draft config。
+5. 最后进入 Phase 3，按后端 DDD 文档做数据库、发布、成绩和追踪闭环。
+
--- a/docs/prd/BARK_BATTLE_BDD_2026-05-11.md
+++ b/docs/prd/BARK_BATTLE_BDD_2026-05-11.md
@@ -383,17 +383,17 @@
 | 结算后点击再来一局重置本局状态 | application/component | `src/games/bark-battle/application/BarkBattleController.test.ts`, `src/games/bark-battle/ui/BarkBattleResultPanel.test.tsx` | planned |
 | 结算后返回玩法入口 | integration/smoke | `src/games/bark-battle/application/BarkBattleController.test.ts`, Playwright 或人工 smoke 清单 | planned |
 | 移动端进入对战页面时核心元素可见 | component/visual/smoke | `src/games/bark-battle/ui/BarkBattleHud.test.tsx`, Playwright 移动端视口 smoke | planned |
-| 移动端授权和开始必须由用户手势触发 | application/e2e-smoke | `src/games/bark-battle/application/BrowserMicrophoneInput.test.ts`, Playwright 移动端 smoke | planned |
-| 移动端结算面板不遮挡主要操作 | component/visual/smoke | `src/games/bark-battle/ui/BarkBattleResultPanel.test.tsx`, Playwright 移动端视口 smoke | planned |
-| 当前浏览器不支持 getUserMedia | component/application | `src/games/bark-battle/application/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/ui/BarkBattlePermissionPanel.test.tsx` | planned |
-| getUserMedia 调用失败但浏览器 API 存在 | component/application | `src/games/bark-battle/application/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/ui/BarkBattlePermissionPanel.test.tsx` | planned |
-| 非安全上下文导致麦克风不可用 | component/application | `src/games/bark-battle/application/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/ui/BarkBattlePermissionPanel.test.tsx` | planned |
-| 对战中离开页面停止采集 | application/integration | `src/games/bark-battle/application/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/application/BarkBattleController.test.ts` | planned |
+| 移动端授权和开始必须由用户手势触发 | infrastructure/application/e2e-smoke | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/application/__tests__/BarkBattleController.test.ts`, Playwright 移动端 smoke | planned |
+| 移动端结算面板不遮挡主要操作 | component/visual/smoke | `src/games/bark-battle/ui/__tests__/BarkBattleResultPanel.test.tsx`, Playwright 移动端视口 smoke | planned |
+| 当前浏览器不支持 getUserMedia | infrastructure/component | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/ui/__tests__/BarkBattlePermissionPanel.test.tsx` | planned |
+| getUserMedia 调用失败但浏览器 API 存在 | infrastructure/application/component | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/application/__tests__/BarkBattleController.test.ts`, `src/games/bark-battle/ui/__tests__/BarkBattlePermissionPanel.test.tsx` | planned |
+| 非安全上下文导致麦克风不可用 | infrastructure/application/component | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/application/__tests__/BarkBattleController.test.ts`, `src/games/bark-battle/ui/__tests__/BarkBattlePermissionPanel.test.tsx` | planned |
+| 对战中离开页面停止采集 | infrastructure/application/integration | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/application/__tests__/BarkBattleController.test.ts` | planned |
 | 刷新页面后不沿用旧局临时状态 | integration/smoke | Playwright 或人工 smoke 清单 | planned |

 ## 验收清单

- [ ] 权限允许、拒绝、API 不支持、麦克风不可读均有明确状态，且不会误进入 playing。
+- [ ] 权限允许、拒绝、非安全上下文、API 不支持、麦克风未找到/不可读、AudioContext 被拦截、校准超时或样本不可读均有明确状态，且不会误进入 playing。
 - [ ] 校准阶段会影响有效叫声阈值，低噪音不会增加叫声计数。
 - [ ] 有效叫声计数具备阈值、峰值间隔、持续时长约束。
 - [ ] 能量条根据双方推动力差值双向移动，并限制在 `-100` 到 `100`。
--- a/docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md
+++ b/docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md
@@ -135,6 +135,7 @@ src/games/bark-battle/
    AudioAnalyserSampler.ts
    MicrophonePermission.ts
    __tests__/
+      BrowserMicrophoneInput.test.ts
      AudioAnalyserSampler.test.ts

  phaser/
@@ -183,14 +184,34 @@ export type BarkBattlePhase =
  | 'countdown'
  | 'playing'
  | 'finished'
-  | 'unsupported'
-  | 'permission-denied'
+  | 'unavailable'

 export type BarkBattleSide = 'player' | 'opponent'

 export type BarkBattleWinner = BarkBattleSide | 'draw' | null

 export type BarkBattleDifficulty = 'easy' | 'normal' | 'hard'
+
+export type BarkBattleUiState =
+  | 'idle'
+  | 'permission-ready'
+  | 'microphone-authorized'
+  | 'calibrating'
+  | 'ready-countdown'
+  | 'playing'
+  | 'finished'
+  | 'microphone-unavailable'
+
+export type MicrophoneFailureReason =
+  | 'unsupported'
+  | 'permission-denied'
+  | 'non-secure-context'
+  | 'not-found'
+  | 'not-readable'
+  | 'audio-context-blocked'
+  | 'calibration-timeout'
+  | 'calibration-sample-unreadable'
+  | 'unknown'
 ```

 关键数值：
@@ -206,6 +227,9 @@ export type BarkBattleDifficulty = 'easy' | 'normal' | 'hard'
 ```ts
 export type BarkBattleSnapshot = {
  phase: BarkBattlePhase
+  uiState: BarkBattleUiState
+  errorReason: MicrophoneFailureReason | null
+  statusMessageKey: BarkBattleStatusMessageKey | null
  elapsedMs: number
  remainingMs: number
  countdownMs: number
@@ -237,6 +261,17 @@ export type BarkBattleResult = {
  playerAveragePower: number
  score: number
 }
+
+export type BarkBattleStatusMessageKey =
+  | 'microphone-unsupported'
+  | 'microphone-permission-denied'
+  | 'microphone-non-secure-context'
+  | 'microphone-not-found'
+  | 'microphone-not-readable'
+  | 'microphone-audio-context-blocked'
+  | 'microphone-calibration-timeout'
+  | 'microphone-calibration-sample-unreadable'
+  | 'microphone-unknown-error'
 ```

 ### 5.3 输入样本与叫声事件
@@ -341,10 +376,11 @@ energy = clamp(energy + energyDelta, -100, 100)

 ```text
 permission → calibration → countdown → playing → finished
-        ↘ permission-denied
-        ↘ unsupported
+        ↘ unavailable
 ```

+`phase` 只表达 runtime 是否可继续参与局内流程；所有麦克风不可用、权限失败、非安全上下文和校准失败都统一收敛到 `phase: 'unavailable'`，再通过 `uiState: 'microphone-unavailable'` 与 `errorReason` 区分 HUD 展示和重试策略，避免把基础设施错误枚举直接扩散成 domain 阶段。
+
 关键规则：

 - `countdown` 结束才进入 `playing`。
@@ -419,13 +455,29 @@ barkThreshold = clamp(ambientNoiseFloor + 0.12, 0.18, 0.55)
 export type MicrophoneFailureReason =
  | 'unsupported'
  | 'permission-denied'
+  | 'non-secure-context'
  | 'not-found'
  | 'not-readable'
  | 'audio-context-blocked'
+  | 'calibration-timeout'
+  | 'calibration-sample-unreadable'
  | 'unknown'
 ```

-前端只根据错误分类展示可操作状态：重试授权、返回、或使用调试备用输入。不要把浏览器原始错误堆栈展示给玩家。
+错误来源与分层归属：
+
+| 失败原因 | 主要检测位置 | controller snapshot 表达 | HUD 可区分状态 |
+| --- | --- | --- | --- |
+| 浏览器无 `mediaDevices.getUserMedia` | `BrowserMicrophoneInput.isSupported()` | `phase: 'unavailable'`, `uiState: 'microphone-unavailable'`, `errorReason: 'unsupported'` | 设备或浏览器不支持麦克风输入，只提供返回入口，不展示可开始声控按钮 |
+| 非安全上下文 | `BrowserMicrophoneInput.isSupported()` 或 `MicrophonePermission` 预检 `window.isSecureContext` | `phase: 'unavailable'`, `errorReason: 'non-secure-context'` | 当前环境无法使用麦克风，提示使用受支持的安全环境或返回 |
+| 用户拒绝授权 | `BrowserMicrophoneInput.requestPermission()` 捕获 `NotAllowedError` / `SecurityError` | `phase: 'unavailable'`, `errorReason: 'permission-denied'` | 提供重新授权或返回入口，不进入 calibration/countdown/playing |
+| 未检测到设备 | `getUserMedia` 捕获 `NotFoundError` / `DevicesNotFoundError` | `phase: 'unavailable'`, `errorReason: 'not-found'` | 展示麦克风不可用，可重试授权或返回 |
+| 设备被占用或不可读 | `getUserMedia` 捕获 `NotReadableError` / `TrackStartError` | `phase: 'unavailable'`, `errorReason: 'not-readable'` | 展示麦克风不可用，可重试授权或返回 |
+| AudioContext 被移动端策略拦截 | 用户手势后创建 / resume `AudioContext` 失败 | `phase: 'unavailable'`, `errorReason: 'audio-context-blocked'` | 提示点击重试，不自动循环请求 |
+| 校准超时 | `BarkBattleController` 在 calibration 阶段等待样本超出 `calibrationMaxWaitMs` | `phase: 'unavailable'`, `errorReason: 'calibration-timeout'` | 展示麦克风输入不可用，提供重试校准入口 |
+| 校准样本不可读 | `AudioAnalyserSampler.sample()` 持续返回空样本、NaN 或无法读取 buffer | `phase: 'unavailable'`, `errorReason: 'calibration-sample-unreadable'` | 展示麦克风输入不可用，提供重试校准入口 |
+
+前端只根据错误分类展示可操作状态：重试授权、重试校准、返回、或使用调试备用输入。不要把浏览器原始错误堆栈展示给玩家。

 ## 8. Phaser Scene 切分

@@ -544,10 +596,13 @@ HUD 分区：

 权限失败时：

- `unsupported`：展示“当前浏览器不支持麦克风输入”，提供返回入口。
+- `unsupported`：展示“当前浏览器不支持麦克风输入”，提供返回入口，不展示开始声控按钮。
+- `non-secure-context`：展示“当前环境无法使用麦克风”，提示切换到受支持的安全环境或返回。
 - `permission-denied`：展示简短说明和“重新授权”入口。
- `not-found`：提示未检测到麦克风，提供返回入口。
+- `not-found`：提示未检测到麦克风，提供重试授权或返回入口。
+- `not-readable`：提示麦克风被占用或暂时不可读，提供重试授权或返回入口。
 - `audio-context-blocked`：提示点击重试。
+- `calibration-timeout` / `calibration-sample-unreadable`：提示麦克风输入不可用，提供“重新校准”和返回入口。

 可选开发调试降级：

@@ -578,7 +633,9 @@ HUD 分区：
 建议测试：

 - 权限允许后进入校准，再进入倒计时。
- 权限拒绝后 phase 为 `permission-denied`，不进入 playing。
+- 权限拒绝后 `phase` 为 `unavailable`、`errorReason` 为 `permission-denied`，不进入 playing。
+- 非安全上下文、设备未找到、设备不可读、AudioContext 被拦截时，controller snapshot 都进入 `phase: 'unavailable'`，并保留可供 HUD 区分的 `errorReason`。
+- 校准超时或样本持续不可读时，controller snapshot 使用 `errorReason: 'calibration-timeout'` 或 `calibration-sample-unreadable`，并提供重试校准动作。
 - 提交 mock audio sample 后 snapshot 中玩家状态更新。
 - AI 对手 power 参与能量条拉锯。
 - `lastEvents` 只发布新增视觉事件。
@@ -591,7 +648,9 @@ HUD 分区：

 - playing 阶段展示倒计时和能量条。
 - energy 正负值映射到玩家 / 对手侧比例。
- permission-denied 展示重试入口。
+- `errorReason: 'permission-denied'` 展示重试授权入口。
+- `errorReason: 'unsupported'` 展示返回入口且不展示开始声控按钮。
+- `not-found`、`not-readable`、`non-secure-context`、`audio-context-blocked`、`calibration-timeout`、`calibration-sample-unreadable` 分别映射到可区分的简短状态文案和对应操作。
 - finished 展示胜负、叫声次数和再来一局。
 - 移动端 class / 结构不依赖 Phaser Canvas 才能渲染。

@@ -609,7 +668,7 @@ HUD 分区：

 ```bash
 npm run check:encoding
-git diff -- docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md
+git diff -- docs/prd/BARK_BATTLE_BDD_2026-05-11.md docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md
 ```

 后续实现 domain 后建议：
@@ -620,6 +679,14 @@ npm run typecheck
 npm run check:encoding
 ```

+后续实现 infrastructure/application 错误状态后建议：
+
+```bash
+npm run test -- --run src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts src/games/bark-battle/application/__tests__/BarkBattleController.test.ts
+npm run typecheck
+npm run check:encoding
+```
+
 后续实现 HUD 后建议：

 ```bash
--- a/public/bark-battle-assets/bark-battle-image-prompts.json
+++ b/public/bark-battle-assets/bark-battle-image-prompts.json
@@ -0,0 +1,17 @@
+[
+  {
+    "id": "bark-battle-player-back",
+    "title": "玩家背对屏幕狗狗",
+    "prompt": "竖屏手机游戏素材，背对屏幕的可爱小狗，站在下半屏中央，耳朵竖起，身体朝向远处对手，夸张卡通 2D 手游风，轮廓清晰，暖橙色毛发，适合做 sprite，透明背景或纯色背景，无文字、水印、UI、边框"
+  },
+  {
+    "id": "bark-battle-opponent-front",
+    "title": "对手面向屏幕狗狗",
+    "prompt": "竖屏手机游戏素材，面向屏幕的可爱小狗，站在上半屏中央，张嘴准备汪汪叫，夸张卡通 2D 手游风，轮廓清晰，紫蓝色竞技光效，适合做 sprite，透明背景或纯色背景，无文字、水印、UI、边框"
+  },
+  {
+    "id": "bark-battle-bark-particles",
+    "title": "汪字粒子声浪",
+    "prompt": "竖屏手机游戏特效素材，画面中心必须是完整清晰的中文汉字“汪”，包含左侧三点水偏旁“氵”和右侧“王”，字体由金黄色发光粒子组成，字形周围向外扩散圆形声浪冲击波与粉色火花，深色纯背景便于叠加，适合做游戏粒子特效贴图，无其他文字、水印、按钮、UI，不要只生成“王”字"
+  }
+]
--- a/public/bark-battle-assets/generated/bark-battle-bark-particles.png
+++ b/public/bark-battle-assets/generated/bark-battle-bark-particles.png
--- a/public/bark-battle-assets/generated/bark-battle-opponent-front.png
+++ b/public/bark-battle-assets/generated/bark-battle-opponent-front.png
--- a/public/bark-battle-assets/generated/bark-battle-player-back.png
+++ b/public/bark-battle-assets/generated/bark-battle-player-back.png
--- a/scripts/generate-bark-battle-assets.mjs
+++ b/scripts/generate-bark-battle-assets.mjs
@@ -0,0 +1,145 @@
+import { Buffer } from 'node:buffer';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+const repoRoot = process.cwd();
+const promptsPath = path.join(repoRoot, 'public', 'bark-battle-assets', 'bark-battle-image-prompts.json');
+const outDir = path.join(repoRoot, 'public', 'bark-battle-assets', 'generated');
+const args = new Set(process.argv.slice(2));
+
+function readDotenv(fileName) {
+  const filePath = path.join(repoRoot, fileName);
+  if (!existsSync(filePath)) return {};
+  const values = {};
+  for (const line of readFileSync(filePath, 'utf8').split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/u.exec(trimmed);
+    if (!match) continue;
+    let value = match[2].trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    values[match[1]] = value;
+  }
+  return values;
+}
+
+function resolveEnv() {
+  const loaded = {
+    ...readDotenv('.env.example'),
+    ...readDotenv('.env.local'),
+    ...readDotenv('.env.secrets.local'),
+    ...process.env,
+  };
+  return {
+    baseUrl: String(loaded.VECTOR_ENGINE_BASE_URL || '').trim().replace(/\/+$/u, ''),
+    apiKey: String(loaded.VECTOR_ENGINE_API_KEY || '').trim(),
+    timeoutMs: Number.parseInt(String(loaded.VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS || 180000), 10),
+  };
+}
+
+function generationUrl(baseUrl) {
+  return baseUrl.endsWith('/v1') ? `${baseUrl}/images/generations` : `${baseUrl}/v1/images/generations`;
+}
+
+function collectStringsByKey(value, targetKey, output) {
+  if (Array.isArray(value)) {
+    value.forEach((entry) => collectStringsByKey(entry, targetKey, output));
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+  for (const [key, nested] of Object.entries(value)) {
+    if (key === targetKey) {
+      if (typeof nested === 'string' && nested.trim()) output.push(nested.trim());
+      if (Array.isArray(nested)) nested.forEach((entry) => typeof entry === 'string' && entry.trim() && output.push(entry.trim()));
+    }
+    collectStringsByKey(nested, targetKey, output);
+  }
+}
+
+function inferExtensionFromBytes(bytes) {
+  if (bytes.subarray(0, 8).equals(Buffer.from('\x89PNG\r\n\x1A\n', 'binary'))) return 'png';
+  if (bytes.subarray(0, 3).equals(Buffer.from([0xff, 0xd8, 0xff]))) return 'jpg';
+  if (bytes.subarray(0, 4).toString('ascii') === 'RIFF' && bytes.subarray(8, 12).toString('ascii') === 'WEBP') return 'webp';
+  return 'png';
+}
+
+async function fetchJson(url, options, timeoutMs) {
+  const abortController = new AbortController();
+  const timer = setTimeout(() => abortController.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { ...options, signal: abortController.signal });
+    const text = await response.text();
+    if (!response.ok) throw new Error(`VectorEngine ${response.status}: ${text.slice(0, 300)}`);
+    return JSON.parse(text);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function downloadUrl(url, timeoutMs) {
+  const abortController = new AbortController();
+  const timer = setTimeout(() => abortController.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { signal: abortController.signal });
+    if (!response.ok) throw new Error(`download ${response.status}`);
+    const bytes = Buffer.from(await response.arrayBuffer());
+    const type = response.headers.get('content-type') || '';
+    const extension = type.includes('webp') ? 'webp' : type.includes('jpeg') ? 'jpg' : 'png';
+    return { bytes, extension };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const rawTemplates = JSON.parse(readFileSync(promptsPath, 'utf8'));
+const onlyIds = process.argv
+  .slice(2)
+  .flatMap((arg, index, values) => (arg === '--only' ? String(values[index + 1] || '').split(',') : []))
+  .map((value) => value.trim())
+  .filter(Boolean);
+const templates = rawTemplates.filter((template) => !onlyIds.length || onlyIds.includes(template.id));
+const dryRun = args.has('--dry-run') || !args.has('--live');
+const requests = templates.map((template) => ({ id: template.id, title: template.title, body: { model: 'gpt-image-2-all', prompt: template.prompt, n: 1, size: '1024x1024' } }));
+if (dryRun) {
+  console.log(JSON.stringify({ mode: 'dry-run', outDir, count: requests.length, requests }, null, 2));
+  process.exit(0);
+}
+
+const env = resolveEnv();
+if (!env.baseUrl || !env.apiKey) {
+  console.error(JSON.stringify({ ok: false, error: 'Missing VECTOR_ENGINE_BASE_URL or VECTOR_ENGINE_API_KEY', hasBaseUrl: Boolean(env.baseUrl), hasApiKey: Boolean(env.apiKey) }));
+  process.exit(1);
+}
+
+mkdirSync(outDir, { recursive: true });
+const files = [];
+for (const request of requests) {
+  console.log(`Generating ${request.id}...`);
+  const payload = await fetchJson(generationUrl(env.baseUrl), {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${env.apiKey}`, Accept: 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify(request.body),
+  }, env.timeoutMs);
+  const urls = [];
+  const b64 = [];
+  collectStringsByKey(payload, 'url', urls);
+  collectStringsByKey(payload, 'image', urls);
+  collectStringsByKey(payload, 'image_url', urls);
+  collectStringsByKey(payload, 'b64_json', b64);
+  let image;
+  const url = [...new Set(urls)].find((item) => /^https?:\/\//u.test(item));
+  if (url) {
+    image = await downloadUrl(url, env.timeoutMs);
+  } else if (b64[0]) {
+    const bytes = Buffer.from(b64[0], 'base64');
+    image = { bytes, extension: inferExtensionFromBytes(bytes) };
+  } else {
+    throw new Error(`VectorEngine returned no image for ${request.id}`);
+  }
+  const outputPath = path.join(outDir, `${request.id}.${image.extension}`);
+  writeFileSync(outputPath, image.bytes);
+  files.push(outputPath);
+}
+console.log(JSON.stringify({ ok: true, count: files.length, files }, null, 2));
--- a/scripts/vite-cli.mjs
+++ b/scripts/vite-cli.mjs
@@ -1,4 +1,7 @@
 import crypto from 'node:crypto';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';

 if (crypto.webcrypto) {
  if (typeof crypto.getRandomValues !== 'function') {
@@ -13,4 +16,7 @@ if (crypto.webcrypto) {
  }
 }

-await import('../node_modules/vite/bin/vite.js');
+const require = createRequire(import.meta.url);
+const vitePackageJsonPath = require.resolve('vite/package.json');
+const viteBinPath = join(dirname(vitePackageJsonPath), 'bin', 'vite.js');
+await import(pathToFileURL(viteBinPath).href);
--- a/src/BarkBattlePlaygroundApp.tsx
+++ b/src/BarkBattlePlaygroundApp.tsx
@@ -0,0 +1,5 @@
+import { BarkBattleRuntimeShell } from './games/bark-battle/ui/BarkBattleRuntimeShell';
+
+export default function BarkBattlePlaygroundApp() {
+  return <BarkBattleRuntimeShell />;
+}
--- a/src/games/bark-battle/application/BarkBattleConfig.ts
+++ b/src/games/bark-battle/application/BarkBattleConfig.ts
@@ -0,0 +1,25 @@
+export type BarkBattleConfig = {
+  roundDurationMs: number;
+  countdownMs: number;
+  drawThreshold: number;
+  barkThreshold: number;
+  minBarkGapMs: number;
+  minBarkDurationMs: number;
+  maxBarkDurationMs: number;
+  balanceFactor: number;
+  calibrationMaxWaitMs: number;
+  opponentBasePower: number;
+};
+
+export const DEFAULT_BARK_BATTLE_CONFIG: BarkBattleConfig = {
+  roundDurationMs: 30_000,
+  countdownMs: 3_000,
+  drawThreshold: 12,
+  barkThreshold: 0.5,
+  minBarkGapMs: 300,
+  minBarkDurationMs: 90,
+  maxBarkDurationMs: 900,
+  balanceFactor: 32,
+  calibrationMaxWaitMs: 4_000,
+  opponentBasePower: 0.22,
+};
--- a/src/games/bark-battle/application/BarkBattleController.ts
+++ b/src/games/bark-battle/application/BarkBattleController.ts
@@ -0,0 +1,71 @@
+import { type BarkBattleSession,createBarkBattleSession } from '../domain/BarkBattleSession';
+import type { MicrophoneFailureReason } from '../domain/BarkBattleTypes';
+import { BarkDetector } from '../domain/BarkDetector';
+import type { BarkBattleConfig } from './BarkBattleConfig';
+
+export class BarkBattleController {
+  private session: BarkBattleSession;
+  private detector: BarkDetector;
+  private sampleClockMs = 0;
+
+  constructor(private config: BarkBattleConfig) {
+    this.session = createBarkBattleSession(config);
+    this.detector = this.createDetector();
+  }
+
+  getSnapshot() {
+    return this.session.snapshot;
+  }
+
+  updateConfig(config: BarkBattleConfig) {
+    this.config = config;
+    this.restart();
+  }
+
+  finishNow() {
+    if (this.session.snapshot.phase !== 'playing') {
+      this.session = this.session.startMockRound();
+    }
+    if (this.session.snapshot.phase === 'countdown') {
+      this.session = this.session.tick(this.session.snapshot.countdownMs);
+    }
+    this.session = this.session.tick(this.session.snapshot.remainingMs + 1);
+  }
+
+  startWithMockInput() {
+    this.session = createBarkBattleSession(this.config).startMockRound();
+    this.detector = this.createDetector();
+    this.sampleClockMs = 0;
+  }
+
+  submitMockSample(volume: number) {
+    const events = this.detector.acceptSample({ atMs: this.sampleClockMs, volume });
+    for (const event of events) {
+      this.session = this.session.applyPlayerBark(event);
+    }
+  }
+
+  tick(deltaMs: number) {
+    this.sampleClockMs += deltaMs;
+    this.session = this.session.tick(deltaMs);
+  }
+
+  restart() {
+    this.session = createBarkBattleSession(this.config);
+    this.detector = this.createDetector();
+    this.sampleClockMs = 0;
+  }
+
+  failMicrophone(reason: MicrophoneFailureReason) {
+    this.session = this.session.failMicrophone(reason);
+  }
+
+  private createDetector() {
+    return new BarkDetector({
+      threshold: this.config.barkThreshold,
+      minBarkGapMs: this.config.minBarkGapMs,
+      minBarkDurationMs: this.config.minBarkDurationMs,
+      maxBarkDurationMs: this.config.maxBarkDurationMs,
+    });
+  }
+}
--- a/src/games/bark-battle/application/tests/BarkBattleController.test.ts
+++ b/src/games/bark-battle/application/tests/BarkBattleController.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+
+import { DEFAULT_BARK_BATTLE_CONFIG } from '../BarkBattleConfig';
+import { BarkBattleController } from '../BarkBattleController';
+
+describe('BarkBattleController', () => {
+  it('mock 模式可跑通完整一局并生成结算', () => {
+    const controller = new BarkBattleController({ ...DEFAULT_BARK_BATTLE_CONFIG, roundDurationMs: 1200, countdownMs: 300 });
+
+    controller.startWithMockInput();
+    controller.tick(300);
+    expect(controller.getSnapshot().phase).toBe('playing');
+
+    controller.submitMockSample(0.92);
+    controller.tick(160);
+    controller.submitMockSample(0.12);
+
+    expect(controller.getSnapshot().player.barkCount).toBe(1);
+    expect(controller.getSnapshot().energy).toBeGreaterThan(0);
+
+    controller.tick(1200);
+    expect(controller.getSnapshot().phase).toBe('finished');
+    expect(controller.getSnapshot().result?.winner).toBe('player');
+  });
+
+  it('麦克风失败时进入 unavailable 且不会进入 playing', () => {
+    const controller = new BarkBattleController(DEFAULT_BARK_BATTLE_CONFIG);
+
+    controller.failMicrophone('permission-denied');
+    controller.tick(5000);
+
+    expect(controller.getSnapshot()).toMatchObject({
+      phase: 'unavailable',
+      uiState: 'microphone-unavailable',
+      errorReason: 'permission-denied',
+      statusMessageKey: 'microphone-permission-denied',
+    });
+  });
+
+  it('restart 会重置上一局计数、能量和结果', () => {
+    const controller = new BarkBattleController({ ...DEFAULT_BARK_BATTLE_CONFIG, roundDurationMs: 1, countdownMs: 0 });
+
+    controller.startWithMockInput();
+    controller.tick(1);
+    controller.submitMockSample(1);
+    controller.tick(120);
+    controller.submitMockSample(0.1);
+    controller.tick(2);
+    expect(controller.getSnapshot().result).not.toBeNull();
+
+    controller.restart();
+    expect(controller.getSnapshot().phase).toBe('permission');
+    expect(controller.getSnapshot().player.barkCount).toBe(0);
+    expect(controller.getSnapshot().energy).toBe(0);
+    expect(controller.getSnapshot().result).toBeNull();
+  });
+});
--- a/src/games/bark-battle/domain/BarkBattleScoring.ts
+++ b/src/games/bark-battle/domain/BarkBattleScoring.ts
@@ -0,0 +1,30 @@
+import type { BarkBattleResult, BarkBattleWinner } from './BarkBattleTypes';
+
+export function decideBarkBattleWinner(
+  energy: number,
+  drawThreshold: number,
+): BarkBattleWinner {
+  if (energy > drawThreshold) {
+    return 'player';
+  }
+  if (energy < -drawThreshold) {
+    return 'opponent';
+  }
+  return 'draw';
+}
+
+export function buildBarkBattleResult(input: {
+  energy: number;
+  drawThreshold: number;
+  playerBarkCount: number;
+  opponentBarkCount: number;
+}): BarkBattleResult {
+  const winner = decideBarkBattleWinner(input.energy, input.drawThreshold);
+  return {
+    winner,
+    playerBarkCount: input.playerBarkCount,
+    opponentBarkCount: input.opponentBarkCount,
+    finalEnergy: input.energy,
+    score: Math.max(0, Math.round(input.energy + input.playerBarkCount * 120)),
+  };
+}
--- a/src/games/bark-battle/domain/BarkBattleSession.ts
+++ b/src/games/bark-battle/domain/BarkBattleSession.ts
@@ -0,0 +1,154 @@
+import type { BarkBattleConfig } from '../application/BarkBattleConfig';
+import { buildBarkBattleResult } from './BarkBattleScoring';
+import type { BarkBattleEvent, BarkBattleSnapshot } from './BarkBattleTypes';
+import { advanceEnergy, clampEnergy } from './EnergyTugOfWar';
+import { computeOpponentPower } from './OpponentStrategy';
+
+export class BarkBattleSession {
+  constructor(
+    private readonly config: BarkBattleConfig,
+    readonly snapshot: BarkBattleSnapshot,
+  ) {}
+
+  startMockRound() {
+    return new BarkBattleSession(this.config, {
+      ...this.snapshot,
+      phase: this.config.countdownMs > 0 ? 'countdown' : 'playing',
+      uiState: this.config.countdownMs > 0 ? 'ready-countdown' : 'playing',
+      countdownMs: this.config.countdownMs,
+      remainingMs: this.config.roundDurationMs,
+      lastEvents: [],
+    });
+  }
+
+  tick(deltaMs: number) {
+    if (this.snapshot.phase === 'finished' || this.snapshot.phase === 'unavailable') {
+      return this.withEvents([]);
+    }
+
+    if (this.snapshot.phase === 'countdown') {
+      const countdownMs = Math.max(0, this.snapshot.countdownMs - deltaMs);
+      return new BarkBattleSession(this.config, {
+        ...this.snapshot,
+        phase: countdownMs <= 0 ? 'playing' : 'countdown',
+        uiState: countdownMs <= 0 ? 'playing' : 'ready-countdown',
+        countdownMs,
+        remainingMs: this.config.roundDurationMs,
+        lastEvents: [],
+      });
+    }
+
+    if (this.snapshot.phase !== 'playing') {
+      return this.withEvents([]);
+    }
+
+    const elapsedMs = this.snapshot.elapsedMs + deltaMs;
+    const remainingMs = Math.max(0, this.snapshot.remainingMs - deltaMs);
+    const opponentPower = computeOpponentPower(this.config, elapsedMs);
+    const energy = advanceEnergy({
+      energy: this.snapshot.energy,
+      playerPower: this.snapshot.player.power,
+      opponentPower,
+      deltaMs,
+      balanceFactor: this.config.balanceFactor,
+    });
+    const nextSnapshot: BarkBattleSnapshot = {
+      ...this.snapshot,
+      elapsedMs,
+      remainingMs,
+      energy,
+      opponent: {
+        ...this.snapshot.opponent,
+        power: opponentPower,
+      },
+      player: {
+        ...this.snapshot.player,
+        power: Math.max(0, this.snapshot.player.power * 0.78),
+      },
+      lastEvents: [],
+    };
+
+    if (remainingMs > 0) {
+      return new BarkBattleSession(this.config, nextSnapshot);
+    }
+
+    const result = buildBarkBattleResult({
+      energy,
+      drawThreshold: this.config.drawThreshold,
+      playerBarkCount: nextSnapshot.player.barkCount,
+      opponentBarkCount: nextSnapshot.opponent.barkCount,
+    });
+    return new BarkBattleSession(this.config, {
+      ...nextSnapshot,
+      phase: 'finished',
+      uiState: 'finished',
+      winner: result.winner,
+      result,
+    });
+  }
+
+  applyPlayerBark(event: BarkBattleEvent) {
+    if (this.snapshot.phase !== 'playing') {
+      return this.withEvents([]);
+    }
+
+    const playerPower = Math.min(1, Math.max(this.snapshot.player.power, event.peakVolume));
+    return new BarkBattleSession(this.config, {
+      ...this.snapshot,
+      energy: clampEnergy(this.snapshot.energy + event.peakVolume * 12),
+      player: {
+        barkCount: this.snapshot.player.barkCount + 1,
+        power: playerPower,
+      },
+      lastEvents: [event],
+    });
+  }
+
+  failMicrophone(reason: BarkBattleSnapshot['errorReason']) {
+    return new BarkBattleSession(this.config, {
+      ...this.snapshot,
+      phase: 'unavailable',
+      uiState: 'microphone-unavailable',
+      errorReason: reason,
+      statusMessageKey: reason ? MICROPHONE_STATUS_KEYS[reason] : null,
+      lastEvents: [],
+    });
+  }
+
+  private withEvents(lastEvents: BarkBattleEvent[]) {
+    return new BarkBattleSession(this.config, {
+      ...this.snapshot,
+      lastEvents,
+    });
+  }
+}
+
+const MICROPHONE_STATUS_KEYS = {
+  unsupported: 'microphone-unsupported',
+  'permission-denied': 'microphone-permission-denied',
+  'non-secure-context': 'microphone-non-secure-context',
+  'not-found': 'microphone-not-found',
+  'not-readable': 'microphone-not-readable',
+  'audio-context-blocked': 'microphone-audio-context-blocked',
+  'calibration-timeout': 'microphone-calibration-timeout',
+  'calibration-sample-unreadable': 'microphone-calibration-sample-unreadable',
+  unknown: 'microphone-unknown-error',
+} as const;
+
+export function createBarkBattleSession(config: BarkBattleConfig) {
+  return new BarkBattleSession(config, {
+    phase: 'permission',
+    uiState: 'permission-ready',
+    errorReason: null,
+    statusMessageKey: null,
+    elapsedMs: 0,
+    remainingMs: config.roundDurationMs,
+    countdownMs: config.countdownMs,
+    energy: 0,
+    player: { barkCount: 0, power: 0 },
+    opponent: { barkCount: 0, power: config.opponentBasePower },
+    winner: null,
+    result: null,
+    lastEvents: [],
+  });
+}
--- a/src/games/bark-battle/domain/BarkBattleTypes.ts
+++ b/src/games/bark-battle/domain/BarkBattleTypes.ts
@@ -0,0 +1,84 @@
+export type BarkBattlePhase =
+  | 'permission'
+  | 'calibration'
+  | 'countdown'
+  | 'playing'
+  | 'finished'
+  | 'unavailable';
+
+export type BarkBattleSide = 'player' | 'opponent';
+export type BarkBattleWinner = BarkBattleSide | 'draw' | null;
+export type BarkBattleDifficulty = 'easy' | 'normal' | 'hard';
+
+export type BarkBattleUiState =
+  | 'idle'
+  | 'permission-ready'
+  | 'microphone-authorized'
+  | 'calibrating'
+  | 'ready-countdown'
+  | 'playing'
+  | 'finished'
+  | 'microphone-unavailable';
+
+export type MicrophoneFailureReason =
+  | 'unsupported'
+  | 'permission-denied'
+  | 'non-secure-context'
+  | 'not-found'
+  | 'not-readable'
+  | 'audio-context-blocked'
+  | 'calibration-timeout'
+  | 'calibration-sample-unreadable'
+  | 'unknown';
+
+export type BarkBattleStatusMessageKey =
+  | 'microphone-unsupported'
+  | 'microphone-permission-denied'
+  | 'microphone-non-secure-context'
+  | 'microphone-not-found'
+  | 'microphone-not-readable'
+  | 'microphone-audio-context-blocked'
+  | 'microphone-calibration-timeout'
+  | 'microphone-calibration-sample-unreadable'
+  | 'microphone-unknown-error';
+
+export type BarkAudioSample = {
+  atMs: number;
+  volume: number;
+};
+
+export type BarkBattleEvent = {
+  side: BarkBattleSide;
+  atMs: number;
+  peakVolume: number;
+  durationMs: number;
+};
+
+export type BarkBattleParticipantState = {
+  barkCount: number;
+  power: number;
+};
+
+export type BarkBattleResult = {
+  winner: BarkBattleWinner;
+  playerBarkCount: number;
+  opponentBarkCount: number;
+  finalEnergy: number;
+  score: number;
+};
+
+export type BarkBattleSnapshot = {
+  phase: BarkBattlePhase;
+  uiState: BarkBattleUiState;
+  errorReason: MicrophoneFailureReason | null;
+  statusMessageKey: BarkBattleStatusMessageKey | null;
+  elapsedMs: number;
+  remainingMs: number;
+  countdownMs: number;
+  energy: number;
+  player: BarkBattleParticipantState;
+  opponent: BarkBattleParticipantState;
+  winner: BarkBattleWinner;
+  result: BarkBattleResult | null;
+  lastEvents: BarkBattleEvent[];
+};
--- a/src/games/bark-battle/domain/BarkDetector.ts
+++ b/src/games/bark-battle/domain/BarkDetector.ts
@@ -0,0 +1,69 @@
+import type { BarkAudioSample, BarkBattleEvent } from './BarkBattleTypes';
+
+export type BarkDetectorConfig = {
+  threshold: number;
+  minBarkGapMs: number;
+  minBarkDurationMs: number;
+  maxBarkDurationMs: number;
+};
+
+type ActiveBark = {
+  startMs: number;
+  peakVolume: number;
+};
+
+export class BarkDetector {
+  private activeBark: ActiveBark | null = null;
+  private lastAcceptedAtMs = Number.NEGATIVE_INFINITY;
+
+  constructor(private readonly config: BarkDetectorConfig) {}
+
+  acceptSample(sample: BarkAudioSample): BarkBattleEvent[] {
+    const volume = clamp01(sample.volume);
+    if (volume >= this.config.threshold) {
+      this.activeBark = this.activeBark
+        ? {
+            startMs: this.activeBark.startMs,
+            peakVolume: Math.max(this.activeBark.peakVolume, volume),
+          }
+        : {
+            startMs: sample.atMs,
+            peakVolume: volume,
+          };
+      return [];
+    }
+
+    if (!this.activeBark) {
+      return [];
+    }
+
+    const activeBark = this.activeBark;
+    this.activeBark = null;
+    const durationMs = sample.atMs - activeBark.startMs;
+    const accepted =
+      durationMs >= this.config.minBarkDurationMs &&
+      durationMs <= this.config.maxBarkDurationMs &&
+      activeBark.startMs - this.lastAcceptedAtMs >= this.config.minBarkGapMs;
+
+    if (!accepted) {
+      return [];
+    }
+
+    this.lastAcceptedAtMs = activeBark.startMs;
+    return [
+      {
+        side: 'player',
+        atMs: activeBark.startMs,
+        peakVolume: activeBark.peakVolume,
+        durationMs,
+      },
+    ];
+  }
+}
+
+function clamp01(value: number) {
+  if (!Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.min(1, Math.max(0, value));
+}
--- a/src/games/bark-battle/domain/EnergyTugOfWar.ts
+++ b/src/games/bark-battle/domain/EnergyTugOfWar.ts
@@ -0,0 +1,20 @@
+export type AdvanceEnergyInput = {
+  energy: number;
+  playerPower: number;
+  opponentPower: number;
+  deltaMs: number;
+  balanceFactor: number;
+};
+
+export function advanceEnergy(input: AdvanceEnergyInput) {
+  const deltaSeconds = Math.max(0, input.deltaMs) / 1000;
+  const powerDelta = input.playerPower - input.opponentPower;
+  return clampEnergy(input.energy + powerDelta * input.balanceFactor * deltaSeconds);
+}
+
+export function clampEnergy(value: number) {
+  if (!Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.min(100, Math.max(-100, value));
+}
--- a/src/games/bark-battle/domain/OpponentStrategy.ts
+++ b/src/games/bark-battle/domain/OpponentStrategy.ts
@@ -0,0 +1,6 @@
+import type { BarkBattleConfig } from '../application/BarkBattleConfig';
+
+export function computeOpponentPower(config: BarkBattleConfig, elapsedMs: number) {
+  const pulse = 0.05 * Math.sin(elapsedMs / 480);
+  return Math.min(1, Math.max(0, config.opponentBasePower + pulse));
+}
--- a/src/games/bark-battle/domain/tests/BarkBattleSession.test.ts
+++ b/src/games/bark-battle/domain/tests/BarkBattleSession.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import { DEFAULT_BARK_BATTLE_CONFIG } from '../../application/BarkBattleConfig';
+import { decideBarkBattleWinner } from '../BarkBattleScoring';
+import { createBarkBattleSession } from '../BarkBattleSession';
+
+describe('BarkBattleSession', () => {
+  it('能从校准完成进入倒计时、playing 并在归零后结算', () => {
+    let session = createBarkBattleSession({ ...DEFAULT_BARK_BATTLE_CONFIG, roundDurationMs: 1000, countdownMs: 600 });
+
+    expect(session.snapshot.phase).toBe('permission');
+    session = session.startMockRound();
+    expect(session.snapshot.phase).toBe('countdown');
+
+    session = session.tick(600);
+    expect(session.snapshot.phase).toBe('playing');
+    expect(session.snapshot.remainingMs).toBe(1000);
+
+    session = session.tick(400);
+    expect(session.snapshot.remainingMs).toBe(600);
+
+    session = session.applyPlayerBark({ atMs: 700, peakVolume: 0.9, durationMs: 140, side: 'player' });
+    expect(session.snapshot.player.barkCount).toBe(1);
+    expect(session.snapshot.energy).toBeGreaterThan(0);
+
+    session = session.tick(600);
+    expect(session.snapshot.phase).toBe('finished');
+    expect(session.snapshot.result?.winner).toBe('player');
+  });
+
+  it('finished 后输入不再改变本局叫声计数和能量', () => {
+    let session = createBarkBattleSession({ ...DEFAULT_BARK_BATTLE_CONFIG, roundDurationMs: 1, countdownMs: 0 }).startMockRound().tick(1);
+    session = session.tick(1);
+    const before = session.snapshot;
+
+    session = session.applyPlayerBark({ atMs: 200, peakVolume: 1, durationMs: 120, side: 'player' });
+
+    expect(session.snapshot.player.barkCount).toBe(before.player.barkCount);
+    expect(session.snapshot.energy).toBe(before.energy);
+  });
+});
+
+describe('decideBarkBattleWinner', () => {
+  it('按 drawThreshold 判定玩家胜、对手胜和平局', () => {
+    expect(decideBarkBattleWinner(16, 12)).toBe('player');
+    expect(decideBarkBattleWinner(-16, 12)).toBe('opponent');
+    expect(decideBarkBattleWinner(8, 12)).toBe('draw');
+  });
+});
--- a/src/games/bark-battle/domain/tests/BarkDetector.test.ts
+++ b/src/games/bark-battle/domain/tests/BarkDetector.test.ts
@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+
+import { DEFAULT_BARK_BATTLE_CONFIG } from '../../application/BarkBattleConfig';
+import { BarkDetector } from '../BarkDetector';
+
+describe('BarkDetector', () => {
+  it('超过阈值且持续时长合规时只计为一次有效叫声', () => {
+    const detector = new BarkDetector({
+      threshold: 0.45,
+      minBarkGapMs: DEFAULT_BARK_BATTLE_CONFIG.minBarkGapMs,
+      minBarkDurationMs: 90,
+      maxBarkDurationMs: 900,
+    });
+
+    expect(detector.acceptSample({ atMs: 0, volume: 0.2 })).toEqual([]);
+    expect(detector.acceptSample({ atMs: 40, volume: 0.72 })).toEqual([]);
+    expect(detector.acceptSample({ atMs: 150, volume: 0.76 })).toEqual([]);
+    const events = detector.acceptSample({ atMs: 180, volume: 0.2 });
+
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ side: 'player', peakVolume: 0.76 });
+    expect(events[0]?.durationMs).toBe(140);
+  });
+
+  it('持续噪音不会在每个 tick 无限计数', () => {
+    const detector = new BarkDetector({
+      threshold: 0.4,
+      minBarkGapMs: 250,
+      minBarkDurationMs: 80,
+      maxBarkDurationMs: 600,
+    });
+
+    const allEvents = [
+      ...detector.acceptSample({ atMs: 0, volume: 0.7 }),
+      ...detector.acceptSample({ atMs: 100, volume: 0.72 }),
+      ...detector.acceptSample({ atMs: 200, volume: 0.73 }),
+      ...detector.acceptSample({ atMs: 300, volume: 0.75 }),
+      ...detector.acceptSample({ atMs: 500, volume: 0.2 }),
+    ];
+
+    expect(allEvents).toHaveLength(1);
+  });
+
+  it('低于阈值的背景噪音、过短脉冲和冷却内峰值不计数', () => {
+    const detector = new BarkDetector({
+      threshold: 0.5,
+      minBarkGapMs: 300,
+      minBarkDurationMs: 80,
+      maxBarkDurationMs: 800,
+    });
+
+    expect(detector.acceptSample({ atMs: 0, volume: 0.48 })).toEqual([]);
+    detector.acceptSample({ atMs: 20, volume: 0.9 });
+    expect(detector.acceptSample({ atMs: 60, volume: 0.2 })).toEqual([]);
+
+    detector.acceptSample({ atMs: 500, volume: 0.88 });
+    expect(detector.acceptSample({ atMs: 620, volume: 0.2 })).toHaveLength(1);
+
+    detector.acceptSample({ atMs: 700, volume: 0.9 });
+    expect(detector.acceptSample({ atMs: 820, volume: 0.2 })).toEqual([]);
+  });
+});
--- a/src/games/bark-battle/domain/tests/EnergyTugOfWar.test.ts
+++ b/src/games/bark-battle/domain/tests/EnergyTugOfWar.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+
+import { advanceEnergy } from '../EnergyTugOfWar';
+
+describe('advanceEnergy', () => {
+  it('玩家推动力高于对手时能量增加', () => {
+    expect(advanceEnergy({ energy: 0, playerPower: 0.8, opponentPower: 0.2, deltaMs: 1000, balanceFactor: 40 })).toBeGreaterThan(0);
+  });
+
+  it('对手推动力高于玩家时能量减少', () => {
+    expect(advanceEnergy({ energy: 0, playerPower: 0.1, opponentPower: 0.7, deltaMs: 1000, balanceFactor: 40 })).toBeLessThan(0);
+  });
+
+  it('能量被限制在 -100 到 100 且双方相等时保持稳定', () => {
+    expect(advanceEnergy({ energy: 98, playerPower: 1, opponentPower: 0, deltaMs: 2000, balanceFactor: 40 })).toBe(100);
+    expect(advanceEnergy({ energy: -98, playerPower: 0, opponentPower: 1, deltaMs: 2000, balanceFactor: 40 })).toBe(-100);
+    expect(advanceEnergy({ energy: 12, playerPower: 0.5, opponentPower: 0.5, deltaMs: 1000, balanceFactor: 40 })).toBeCloseTo(12);
+  });
+});
--- a/src/games/bark-battle/infrastructure/BrowserMicrophoneInput.ts
+++ b/src/games/bark-battle/infrastructure/BrowserMicrophoneInput.ts
@@ -0,0 +1,24 @@
+import type { MicrophoneFailureReason } from '../domain/BarkBattleTypes';
+
+export function mapGetUserMediaError(error: unknown): MicrophoneFailureReason {
+  const name = error && typeof error === 'object' && 'name' in error ? String((error as { name?: unknown }).name) : '';
+  if (name === 'NotAllowedError' || name === 'SecurityError') return 'permission-denied';
+  if (name === 'NotFoundError' || name === 'DevicesNotFoundError') return 'not-found';
+  if (name === 'NotReadableError' || name === 'TrackStartError') return 'not-readable';
+  return 'unknown';
+}
+
+export function isMicrophoneApiSupported(windowLike: { isSecureContext?: boolean; navigator?: Navigator | { mediaDevices?: { getUserMedia?: unknown } } }) {
+  if (windowLike.isSecureContext === false) {
+    return { ok: false as const, reason: 'non-secure-context' as const };
+  }
+  const getUserMedia = windowLike.navigator?.mediaDevices?.getUserMedia;
+  if (typeof getUserMedia !== 'function') {
+    return { ok: false as const, reason: 'unsupported' as const };
+  }
+  return { ok: true as const, reason: null };
+}
+
+export function stopMediaStreamTracks(stream: MediaStream) {
+  stream.getTracks().forEach((track) => track.stop());
+}
--- a/src/games/bark-battle/infrastructure/tests/BrowserMicrophoneInput.test.ts
+++ b/src/games/bark-battle/infrastructure/tests/BrowserMicrophoneInput.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { isMicrophoneApiSupported, mapGetUserMediaError, stopMediaStreamTracks } from '../BrowserMicrophoneInput';
+
+describe('BrowserMicrophoneInput', () => {
+  it('区分非安全上下文和不支持 getUserMedia', () => {
+    expect(isMicrophoneApiSupported({ isSecureContext: false })).toEqual({ ok: false, reason: 'non-secure-context' });
+    expect(isMicrophoneApiSupported({ isSecureContext: true, navigator: {} })).toEqual({ ok: false, reason: 'unsupported' });
+  });
+
+  it('映射常见 getUserMedia 错误', () => {
+    expect(mapGetUserMediaError({ name: 'NotAllowedError' })).toBe('permission-denied');
+    expect(mapGetUserMediaError({ name: 'NotFoundError' })).toBe('not-found');
+    expect(mapGetUserMediaError({ name: 'NotReadableError' })).toBe('not-readable');
+    expect(mapGetUserMediaError({ name: 'OtherError' })).toBe('unknown');
+  });
+
+  it('停止 MediaStream 的所有音轨', () => {
+    const stopA = vi.fn();
+    const stopB = vi.fn();
+    stopMediaStreamTracks({ getTracks: () => [{ stop: stopA }, { stop: stopB }] } as unknown as MediaStream);
+    expect(stopA).toHaveBeenCalledTimes(1);
+    expect(stopB).toHaveBeenCalledTimes(1);
+  });
+});
--- a/src/games/bark-battle/ui/BarkBattleHud.css
+++ b/src/games/bark-battle/ui/BarkBattleHud.css
@@ -0,0 +1,193 @@
+.bark-battle-hud {
+  min-height: 100svh;
+  color: #fff7ed;
+  background: radial-gradient(circle at 50% 15%, rgba(251, 191, 36, 0.35), transparent 28%), linear-gradient(180deg, #1f1147 0%, #521b4f 48%, #130a28 100%);
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+  padding: max(18px, env(safe-area-inset-top)) 16px max(18px, env(safe-area-inset-bottom));
+  box-sizing: border-box;
+  overflow: hidden;
+}
+
+.bark-battle-hud__topline {
+  display: grid;
+  gap: 10px;
+}
+
+.bark-battle-hud__timer {
+  justify-self: center;
+  border-radius: 999px;
+  padding: 8px 16px;
+  background: rgba(15, 23, 42, 0.56);
+  font-weight: 900;
+  letter-spacing: 0.04em;
+}
+
+.bark-battle-energy {
+  position: relative;
+  display: flex;
+  height: 18px;
+  border: 2px solid rgba(255, 247, 237, 0.78);
+  border-radius: 999px;
+  overflow: hidden;
+  background: rgba(15, 23, 42, 0.48);
+}
+
+.bark-battle-energy__side--player { background: linear-gradient(90deg, #f97316, #facc15); }
+.bark-battle-energy__side--opponent { background: linear-gradient(90deg, #60a5fa, #a78bfa); }
+
+.bark-battle-arena {
+  flex: 1;
+  min-height: 0;
+  display: grid;
+  grid-template-rows: 1fr auto 1fr;
+  place-items: center;
+}
+
+.bark-battle-dog {
+  display: grid;
+  place-items: center;
+  gap: 8px;
+}
+
+.bark-battle-dog__body {
+  font-size: clamp(92px, 30vw, 150px);
+  filter: drop-shadow(0 18px 22px rgba(0, 0, 0, 0.42));
+}
+
+.bark-battle-dog--player .bark-battle-dog__body {
+  transform: rotateY(180deg) translateY(4px);
+}
+
+.bark-battle-dog__label,
+.bark-battle-vs {
+  font-weight: 900;
+  text-shadow: 0 2px 10px rgba(0, 0, 0, 0.35);
+}
+
+.bark-battle-vs {
+  border-radius: 999px;
+  padding: 10px 18px;
+  background: rgba(255, 255, 255, 0.16);
+}
+
+.bark-battle-controls,
+.bark-battle-result__stats {
+  display: flex;
+  gap: 10px;
+  justify-content: center;
+  flex-wrap: wrap;
+}
+
+.bark-battle-controls button,
+.bark-battle-primary-button {
+  border: 0;
+  border-radius: 999px;
+  padding: 12px 18px;
+  color: #1f1147;
+  background: #fff7ed;
+  font-weight: 900;
+}
+
+.bark-battle-primary-button {
+  background: linear-gradient(135deg, #facc15, #fb7185);
+}
+
+.bark-battle-status-card,
+.bark-battle-result {
+  margin: auto;
+  width: min(92vw, 420px);
+  border: 1px solid rgba(255, 255, 255, 0.18);
+  border-radius: 28px;
+  padding: 24px;
+  text-align: center;
+  background: rgba(15, 23, 42, 0.68);
+  box-shadow: 0 26px 60px rgba(0, 0, 0, 0.3);
+  backdrop-filter: blur(18px);
+}
+
+.bark-battle-result__stats span {
+  min-width: 84px;
+  display: grid;
+  gap: 4px;
+}
+
+.bark-battle-result__stats strong {
+  font-size: 28px;
+}
+
+.bark-battle-particles {
+  position: absolute;
+  inset: 18% 0 auto;
+  pointer-events: none;
+  text-align: center;
+  font-size: clamp(30px, 10vw, 70px);
+  font-weight: 950;
+  letter-spacing: 0.08em;
+  color: rgba(255, 247, 237, 0.88);
+  text-shadow: 0 0 18px rgba(250, 204, 21, 0.75);
+  animation: barkBattleParticlePop 820ms ease-out both;
+}
+
+.bark-battle-debug-panel {
+  position: fixed;
+  right: 12px;
+  bottom: max(12px, env(safe-area-inset-bottom));
+  z-index: 8;
+  width: min(92vw, 340px);
+  max-height: 42svh;
+  overflow: auto;
+  border: 1px solid rgba(255, 255, 255, 0.18);
+  border-radius: 22px;
+  padding: 12px;
+  color: #fff7ed;
+  background: rgba(15, 23, 42, 0.72);
+  box-shadow: 0 18px 46px rgba(0, 0, 0, 0.28);
+  backdrop-filter: blur(18px);
+}
+
+.bark-battle-debug-panel header,
+.bark-battle-debug-panel label {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+}
+
+.bark-battle-debug-panel label {
+  margin-top: 8px;
+  font-size: 12px;
+}
+
+.bark-battle-debug-panel input {
+  flex: 1;
+}
+
+.bark-battle-debug-panel output {
+  min-width: 44px;
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+}
+
+.bark-battle-debug-panel__controls {
+  display: flex;
+  gap: 8px;
+  margin-top: 10px;
+}
+
+.bark-battle-debug-panel__controls button {
+  flex: 1;
+  border: 0;
+  border-radius: 999px;
+  padding: 8px 10px;
+  color: #1f1147;
+  background: #fff7ed;
+  font-weight: 800;
+}
+
+@keyframes barkBattleParticlePop {
+  from { transform: translateY(28px) scale(0.7); opacity: 0; }
+  42% { opacity: 1; }
+  to { transform: translateY(-80px) scale(1.14); opacity: 0; }
+}
--- a/src/games/bark-battle/ui/BarkBattleHud.tsx
+++ b/src/games/bark-battle/ui/BarkBattleHud.tsx
@@ -0,0 +1,91 @@
+import './BarkBattleHud.css';
+
+import type { BarkBattleSnapshot } from '../domain/BarkBattleTypes';
+
+type BarkBattleHudProps = {
+  snapshot: BarkBattleSnapshot;
+  onStartMicrophone?: () => void;
+  onMockBark?: () => void;
+  onMockQuiet?: () => void;
+  onRestart?: () => void;
+};
+
+const failureText = {
+  unsupported: '当前浏览器不支持麦克风输入',
+  'permission-denied': '麦克风授权被拒绝',
+  'non-secure-context': '当前环境无法使用麦克风',
+  'not-found': '未检测到麦克风',
+  'not-readable': '麦克风暂时不可读',
+  'audio-context-blocked': '音频上下文被拦截',
+  'calibration-timeout': '校准超时',
+  'calibration-sample-unreadable': '校准样本不可读',
+  unknown: '麦克风暂时不可用',
+};
+
+export function BarkBattleHud({
+  snapshot,
+  onStartMicrophone,
+  onMockBark,
+  onMockQuiet,
+  onRestart,
+}: BarkBattleHudProps) {
+  const playerWidth = `${Math.round(((snapshot.energy + 100) / 200) * 100)}%`;
+  const opponentWidth = `${Math.round(((100 - snapshot.energy) / 200) * 100)}%`;
+  const isUnavailable = snapshot.phase === 'unavailable';
+
+  return (
+    <section className="bark-battle-hud" aria-label="汪汪声浪大作战">
+      <header className="bark-battle-hud__topline">
+        <div className="bark-battle-hud__timer">{(snapshot.remainingMs / 1000).toFixed(1)}s</div>
+        <div
+          className="bark-battle-energy"
+          role="meter"
+          aria-label="声浪能量条"
+          aria-valuemin={-100}
+          aria-valuemax={100}
+          aria-valuenow={Math.round(snapshot.energy)}
+        >
+          <div className="bark-battle-energy__side bark-battle-energy__side--player" data-testid="player-energy-fill" style={{ width: playerWidth }} />
+          <div className="bark-battle-energy__side bark-battle-energy__side--opponent" data-testid="opponent-energy-fill" style={{ width: opponentWidth }} />
+        </div>
+      </header>
+
+      {isUnavailable ? (
+        <div className="bark-battle-status-card">
+          <h1>{snapshot.errorReason ? failureText[snapshot.errorReason] : '麦克风暂时不可用'}</h1>
+          {snapshot.errorReason !== 'unsupported' ? (
+            <button type="button" className="bark-battle-primary-button" onClick={onStartMicrophone}>
+              {snapshot.errorReason === 'permission-denied' ? '重新授权' : '重试'}
+            </button>
+          ) : null}
+        </div>
+      ) : (
+        <div className="bark-battle-arena" aria-label="竖屏声浪竞技场">
+          <div className="bark-battle-dog bark-battle-dog--player" aria-label="玩家狗狗背对屏幕">
+            <span className="bark-battle-dog__body">🐕</span>
+            <span className="bark-battle-dog__label">你 · {snapshot.player.barkCount}</span>
+          </div>
+          <div className="bark-battle-vs">VS</div>
+          <div className="bark-battle-dog bark-battle-dog--opponent" aria-label="对手狗狗面向屏幕">
+            <span className="bark-battle-dog__body">🐶</span>
+            <span className="bark-battle-dog__label">对手 · {snapshot.opponent.barkCount}</span>
+          </div>
+        </div>
+      )}
+
+      <footer className="bark-battle-controls">
+        {snapshot.phase === 'permission' ? (
+          <button className="bark-battle-primary-button" type="button" onClick={onStartMicrophone}>
+            开始声控
+          </button>
+        ) : null}
+        <button type="button" onPointerDown={onMockBark} onPointerUp={onMockQuiet} onClick={onMockBark}>
+          模拟叫声
+        </button>
+        {snapshot.phase === 'finished' ? (
+          <button type="button" onClick={onRestart}>再来一局</button>
+        ) : null}
+      </footer>
+    </section>
+  );
+}
--- a/src/games/bark-battle/ui/BarkBattleResultPanel.tsx
+++ b/src/games/bark-battle/ui/BarkBattleResultPanel.tsx
@@ -0,0 +1,34 @@
+import type { BarkBattleResult } from '../domain/BarkBattleTypes';
+
+type BarkBattleResultPanelProps = {
+  result: BarkBattleResult;
+  onRestart: () => void;
+};
+
+export function BarkBattleResultPanel({ result, onRestart }: BarkBattleResultPanelProps) {
+  const title = result.winner === 'player' ? '汪力压制成功' : result.winner === 'opponent' ? '对手声浪更强' : '势均力敌';
+
+  return (
+    <section className="bark-battle-result" role="dialog" aria-label="对战结算">
+      <p className="bark-battle-result__eyebrow">本局结束</p>
+      <h2>{title}</h2>
+      <div className="bark-battle-result__stats">
+        <span>
+          <strong>{result.playerBarkCount}</strong>
+          玩家叫声
+        </span>
+        <span>
+          <strong>{result.opponentBarkCount}</strong>
+          对手压制
+        </span>
+        <span>
+          <strong>{result.score}</strong>
+          声浪分
+        </span>
+      </div>
+      <button className="bark-battle-primary-button" type="button" onClick={onRestart}>
+        再来一局
+      </button>
+    </section>
+  );
+}
--- a/src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx
+++ b/src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx
@@ -0,0 +1,137 @@
+import { useEffect, useRef, useState } from 'react';
+
+import {
+  type BarkBattleConfig,
+  DEFAULT_BARK_BATTLE_CONFIG,
+} from '../application/BarkBattleConfig';
+import { BarkBattleController } from '../application/BarkBattleController';
+import { BarkBattleHud } from './BarkBattleHud';
+import { BarkBattleResultPanel } from './BarkBattleResultPanel';
+
+type BarkBattleRuntimeShellProps = {
+  title?: string;
+};
+
+const DEBUG_CONFIG_FIELDS: Array<{
+  key: keyof Pick<
+    BarkBattleConfig,
+    | 'roundDurationMs'
+    | 'countdownMs'
+    | 'drawThreshold'
+    | 'barkThreshold'
+    | 'minBarkGapMs'
+    | 'balanceFactor'
+    | 'opponentBasePower'
+  >;
+  label: string;
+  min: number;
+  max: number;
+  step: number;
+}> = [
+  { key: 'roundDurationMs', label: '局长(ms)', min: 1000, max: 60000, step: 1000 },
+  { key: 'countdownMs', label: '倒计时(ms)', min: 0, max: 5000, step: 500 },
+  { key: 'drawThreshold', label: '平局阈值', min: 0, max: 40, step: 1 },
+  { key: 'barkThreshold', label: '叫声阈值', min: 0.1, max: 1, step: 0.05 },
+  { key: 'minBarkGapMs', label: '叫声间隔(ms)', min: 100, max: 1200, step: 50 },
+  { key: 'balanceFactor', label: '拉锯速度', min: 5, max: 80, step: 1 },
+  { key: 'opponentBasePower', label: '对手基础力', min: 0, max: 1, step: 0.05 },
+];
+
+export function BarkBattleRuntimeShell({ title = '汪汪声浪大作战' }: BarkBattleRuntimeShellProps) {
+  const [config, setConfig] = useState(DEFAULT_BARK_BATTLE_CONFIG);
+  const controllerRef = useRef<BarkBattleController | null>(null);
+  if (!controllerRef.current) {
+    controllerRef.current = new BarkBattleController(config);
+  }
+  const controller = controllerRef.current;
+  const [snapshot, setSnapshot] = useState(() => controller.getSnapshot());
+  const [particleText, setParticleText] = useState('');
+  const heldRef = useRef(false);
+
+  useEffect(() => {
+    controller.updateConfig(config);
+    setSnapshot(controller.getSnapshot());
+  }, [config, controller]);
+
+  useEffect(() => {
+    const timer = window.setInterval(() => {
+      controller.tick(100);
+      if (heldRef.current) {
+        controller.submitMockSample(0.88);
+      } else {
+        controller.submitMockSample(0.12);
+      }
+      setSnapshot(controller.getSnapshot());
+    }, 100);
+    return () => window.clearInterval(timer);
+  }, [controller]);
+
+  const restart = () => {
+    heldRef.current = false;
+    controller.restart();
+    setParticleText('');
+    setSnapshot(controller.getSnapshot());
+  };
+
+  const startMock = () => {
+    controller.startWithMockInput();
+    setSnapshot(controller.getSnapshot());
+  };
+
+  const finishNow = () => {
+    heldRef.current = false;
+    controller.finishNow();
+    setSnapshot(controller.getSnapshot());
+  };
+
+  const bark = () => {
+    heldRef.current = true;
+    setParticleText('汪！');
+    window.setTimeout(() => setParticleText(''), 680);
+  };
+
+  return (
+    <main className="bark-battle-runtime" aria-label={title}>
+      <BarkBattleHud
+        snapshot={snapshot}
+        onStartMicrophone={startMock}
+        onMockBark={bark}
+        onMockQuiet={() => {
+          heldRef.current = false;
+        }}
+        onRestart={restart}
+      />
+      <aside className="bark-battle-debug-panel" aria-label="调试面板">
+        <header>
+          <strong>调试面板</strong>
+          <span>{snapshot.phase}</span>
+        </header>
+        <div className="bark-battle-debug-panel__controls">
+          <button type="button" onClick={startMock}>开始</button>
+          <button type="button" onClick={finishNow}>结束</button>
+          <button type="button" onClick={restart}>重置</button>
+        </div>
+        {DEBUG_CONFIG_FIELDS.map((field) => (
+          <label key={field.key}>
+            <span>{field.label}</span>
+            <input
+              aria-label={field.label}
+              type="range"
+              min={field.min}
+              max={field.max}
+              step={field.step}
+              value={config[field.key]}
+              onChange={(event) => {
+                const value = Number(event.currentTarget.value);
+                setConfig((current) => ({ ...current, [field.key]: value }));
+              }}
+            />
+            <output>{config[field.key]}</output>
+          </label>
+        ))}
+      </aside>
+      {particleText ? <div className="bark-battle-particles">{particleText}</div> : null}
+      {snapshot.result ? <BarkBattleResultPanel result={snapshot.result} onRestart={restart} /> : null}
+    </main>
+  );
+}
--- a/src/games/bark-battle/ui/tests/BarkBattleHud.test.tsx
+++ b/src/games/bark-battle/ui/tests/BarkBattleHud.test.tsx
@@ -0,0 +1,57 @@
+/* @vitest-environment jsdom */
+
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import type { BarkBattleSnapshot } from '../../domain/BarkBattleTypes';
+import { BarkBattleHud } from '../BarkBattleHud';
+
+function buildSnapshot(overrides: Partial<BarkBattleSnapshot> = {}): BarkBattleSnapshot {
+  return {
+    phase: 'playing',
+    uiState: 'playing',
+    errorReason: null,
+    statusMessageKey: null,
+    elapsedMs: 0,
+    remainingMs: 12_000,
+    countdownMs: 0,
+    energy: 40,
+    player: { barkCount: 3, power: 0.8 },
+    opponent: { barkCount: 1, power: 0.25 },
+    winner: null,
+    result: null,
+    lastEvents: [],
+    ...overrides,
+  };
+}
+
+describe('BarkBattleHud', () => {
+  it('playing 阶段展示竖屏核心元素、倒计时和双方狗狗朝向', () => {
+    render(<BarkBattleHud snapshot={buildSnapshot()} onMockBark={() => {}} onMockQuiet={() => {}} />);
+
+    expect(screen.getByText('12.0s')).toBeTruthy();
+    expect(screen.getByLabelText('玩家狗狗背对屏幕')).toBeTruthy();
+    expect(screen.getByLabelText('对手狗狗面向屏幕')).toBeTruthy();
+    expect(screen.getByLabelText('声浪能量条').getAttribute('aria-valuenow')).toBe('40');
+  });
+
+  it('energy 正负值会改变玩家侧和对手侧占比', () => {
+    const { rerender } = render(<BarkBattleHud snapshot={buildSnapshot({ energy: 60 })} />);
+    expect(screen.getByTestId('player-energy-fill').getAttribute('style')).toContain('width: 80%');
+
+    rerender(<BarkBattleHud snapshot={buildSnapshot({ energy: -60 })} />);
+    expect(screen.getByTestId('opponent-energy-fill').getAttribute('style')).toContain('width: 80%');
+  });
+
+  it('unsupported 不展示开始声控按钮，permission-denied 展示重试授权入口', () => {
+    const { rerender } = render(
+      <BarkBattleHud snapshot={buildSnapshot({ phase: 'unavailable', errorReason: 'unsupported' })} onStartMicrophone={() => {}} />,
+    );
+    expect(screen.queryByRole('button', { name: '开始声控' })).toBeNull();
+
+    rerender(
+      <BarkBattleHud snapshot={buildSnapshot({ phase: 'unavailable', errorReason: 'permission-denied' })} onStartMicrophone={() => {}} />,
+    );
+    expect(screen.getByRole('button', { name: '重新授权' })).toBeTruthy();
+  });
+});
--- a/src/games/bark-battle/ui/tests/BarkBattleResultPanel.test.tsx
+++ b/src/games/bark-battle/ui/tests/BarkBattleResultPanel.test.tsx
@@ -0,0 +1,26 @@
+/* @vitest-environment jsdom */
+
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi } from 'vitest';
+
+import { BarkBattleResultPanel } from '../BarkBattleResultPanel';
+
+describe('BarkBattleResultPanel', () => {
+  it('展示胜负、叫声次数并支持再来一局', async () => {
+    const onRestart = vi.fn();
+    render(
+      <BarkBattleResultPanel
+        result={{ winner: 'player', playerBarkCount: 6, opponentBarkCount: 2, finalEnergy: 72, score: 792 }}
+        onRestart={onRestart}
+      />,
+    );
+
+    expect(screen.getByRole('dialog', { name: '对战结算' })).toBeTruthy();
+    expect(screen.getByText('汪力压制成功')).toBeTruthy();
+    expect(screen.getByText('6')).toBeTruthy();
+
+    await userEvent.click(screen.getByRole('button', { name: '再来一局' }));
+    expect(onRestart).toHaveBeenCalledTimes(1);
+  });
+});
--- a/src/games/bark-battle/ui/tests/BarkBattleRuntimeShell.test.tsx
+++ b/src/games/bark-battle/ui/tests/BarkBattleRuntimeShell.test.tsx
@@ -0,0 +1,25 @@
+/* @vitest-environment jsdom */
+
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it } from 'vitest';
+
+import { BarkBattleRuntimeShell } from '../BarkBattleRuntimeShell';
+
+describe('BarkBattleRuntimeShell 调试面板', () => {
+  it('提供开始、结束、重置流程控制按钮和参数滑杆', async () => {
+    render(<BarkBattleRuntimeShell />);
+
+    expect(screen.getByLabelText('调试面板')).toBeTruthy();
+    expect(screen.getByRole('button', { name: '开始' })).toBeTruthy();
+    expect(screen.getByRole('button', { name: '结束' })).toBeTruthy();
+    expect(screen.getByRole('button', { name: '重置' })).toBeTruthy();
+    expect(screen.getByLabelText('叫声阈值')).toBeTruthy();
+
+    await userEvent.click(screen.getByRole('button', { name: '开始' }));
+    expect(screen.getByText(/countdown|playing/u)).toBeTruthy();
+
+    await userEvent.click(screen.getByRole('button', { name: '结束' }));
+    expect(screen.getByRole('dialog', { name: '对战结算' })).toBeTruthy();
+  });
+});
--- a/src/routing/appRoutes.tsx
+++ b/src/routing/appRoutes.tsx
@@ -19,6 +19,9 @@ export type AppRouteMatch =
  | {
      kind: 'match3d-playground';
    }
+  | {
+      kind: 'bark-battle-playground';
+    }
  | {
      kind: 'child-motion-demo';
    }
@@ -37,6 +40,7 @@ export type ResolvedAppRoute = {
 const GameApp = lazy(() => import('../AuthenticatedApp')) as AppRouteComponent;
 const BigFishPlaygroundApp = lazy(() => import('../BigFishPlaygroundApp')) as AppRouteComponent;
 const Match3DPlaygroundApp = lazy(() => import('../Match3DPlaygroundApp')) as AppRouteComponent;
+const BarkBattlePlaygroundApp = lazy(() => import('../BarkBattlePlaygroundApp')) as AppRouteComponent;
 const PuzzlePlaygroundApp = lazy(() => import('../PuzzlePlaygroundApp')) as AppRouteComponent;
 const ChildMotionDemoApp = lazy(() => import('../ChildMotionDemoApp')) as AppRouteComponent;

@@ -65,6 +69,12 @@ export function matchAppRoute(pathname: string): AppRouteMatch {
    };
  }

+  if (normalizedPath === '/bark-battle') {
+    return {
+      kind: 'bark-battle-playground',
+    };
+  }
+
  if (
    normalizedPath === '/child-motion-demo' &&
    isEdutainmentEntryEnabled()
@@ -109,6 +119,15 @@ export function resolveAppRoute(pathname: string): ResolvedAppRoute {
    };
  }

+  if (matchedRoute.kind === 'bark-battle-playground') {
+    return {
+      kind: 'bark-battle-playground',
+      loadingEyebrow: '正在载入汪汪声浪',
+      loadingText: '正在进入竖屏声浪竞技场...',
+      Component: BarkBattlePlaygroundApp,
+    };
+  }
+
  if (matchedRoute.kind === 'child-motion-demo') {
    return {
      kind: 'child-motion-demo',