Phase 3.A：srcIsloop 本地音频 + 3.B/3.C/3.D handler stub

3.A 本地音频完整落地（与 msext NewRootVC initJSdata 等价）：

  Source/Audio/AudioPlayer.swift（@MainActor 状态机）：
    - playOnce(url) 单次按钮音；buttonPlayers 数组保活池避免多次点击
      互相打断（duration + 0.5s 后清理）
    - loopBackground(url, type:) 循环背景音；numberOfLoops = -1 +
      backgroundType 记录用于同名停止
    - stopBackground(type:) 同名校验后才停止（msext 同款语义）

  Source/Bridge/Handlers/LocalAudioHandler.swift：
    - 注册 srcIsloop handler（@MainActor enum）
    - 入参 src + isloop，按 0/1/-1 分支调 AudioPlayer.shared 对应方法
    - audioFileURL 路径：{Caches}/{gamedir}/{gamestart}/assets/wav/{src}
      与 msext NewRootVC 路径约定 1:1（H5 zip 内 assets/wav 子目录）
    - audioFileURL 标 nonisolated 因 SandboxPaths 是 nonisolated 静态
    - cb 字面 "Response from srcIsloop" 严格保持

  Source/Bridge/Handlers/RemoteAudioHandler.swift（3.B/3.C/3.D stub）：
    - prepareaudio + mediaTypeAudio 仅 cb 维持契约，无真实业务
    - 待 Phase 3.B（opencore-amr .a 接入）+ 3.C（七牛 SPM + token）+
      3.D（远端播放）完整后升级
    - 按 CLAUDE.md 原则 A：H5 调啥就得有人接，即使是 stub

WebContainerViewController.registerBridgeHandlers 接入：
  - LocalAudioHandler.register（完整实现）
  - RemoteAudioHandler.register（stub）

Plan §5 Phase 3.1 勾选；3.2 真机验证留待 H5 提供音频文件后做。

Verification-Checklist.md 新增 Phase 3 章节：
  - H. 本地音频（E.14-E.16 srcIsloop 三个 isloop 值）
  - I. prepareaudio / mediaTypeAudio stub（E.17 E.18）

BuildProject 通过

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/Development-Plan.md

@@ -411,10 +411,14 @@ Contract       Design          Plan（本文档）
 
 ##### 3.A 本地音频
 
-- [ ] **3.1** `Source/Audio/AudioPlayer.swift`（@MainActor）
-  - `background` / `button` / `voice` 三类 AVAudioPlayer
-  - `srcIsloop` handler：`isloop=0` 单次 / `isloop=1` 循环背景 / `isloop=-1` 停同名背景
-- [ ] **3.2** 真机验证：放一个 `.wav` 进 Resources，H5 调 `srcIsloop({src:"test.wav", isloop:0})` 出声
+- [x] **3.1** `Source/Audio/AudioPlayer.swift`（@MainActor）
+  - `playOnce(url)` 单次按钮音（msext `buttunPlayer` 等价，多次点击不互打断 — 用 buttonPlayers 数组保活池）
+  - `loopBackground(url, type:)` 循环背景音（msext `backgroundPlayer numberOfLoops = -1`，记录 backgroundType）
+  - `stopBackground(type:)` 停同名背景音（type 与当前 backgroundType 匹配才停）
+  - `Source/Bridge/Handlers/LocalAudioHandler.swift` 注册 `srcIsloop` handler，按 isloop=0/1/-1 分支调用 AudioPlayer
+  - 音频文件路径：`{Caches}/{gamedir}/{gamestart}/assets/wav/{src}`（H5 zip 包内自带）
+  - `Source/Bridge/Handlers/RemoteAudioHandler.swift` 注册 `prepareaudio` / `mediaTypeAudio` stub（仅 cb 维持契约，等 Phase 3.B/3.C/3.D 升级）
+- [ ] **3.2** 真机验证：H5 调 `srcIsloop({src:"xxx.wav", isloop:0/1/-1})` 听到对应音效 — 等 H5 团队提供测试音频后做（Verification-Checklist Phase 3 E.14-E.16）
 
 ##### 3.B AMR 转码
 

docs/Verification-Checklist.md

@@ -149,12 +149,23 @@ H5 需先用 `bridge.registerHandler('callbackName', fn)` 注册：
 
 ---
 
-## Phase 3 — 音频体系（待实现）
+## Phase 3 — 音频体系（部分实现：3.A 完成；3.B/C/D 待外部资源）
 
-> Phase 3 实施后填充。预备验证项：
-> - srcIsloop 背景音循环 / 单次按钮音 / 停止
-> - mediaTypeAudio 远端语音回放 + gameui_play_voice / gameui_stop_voice
-> - prepareaudio 录音 + AMR 转码 + 七牛上传 + getaudiourl
+### H. 本地音频（srcIsloop，3.A 完成）
+
+- [ ] **E.14 srcIsloop({src:"xxx.wav", isloop:0})** → 听到单次按钮音；cb "Response from srcIsloop"
+- [ ] **E.15 srcIsloop({src:"bg.wav", isloop:1})** → 听到背景循环音 + 同时调 srcIsloop({src:"另一首.wav", isloop:1}) → 替换为新背景循环
+- [ ] **E.16 srcIsloop({src:"bg.wav", isloop:-1})** → 停止 bg.wav 背景；如果当前背景不是 bg.wav 则无效（与 msext 同名 type 校验）
+
+> **依赖**：测试需要 H5 zip 内 `assets/wav/` 目录有可用音频文件。
+> H5 团队 / 项目方提供后做。
+
+### I. prepareaudio / mediaTypeAudio stub（3.B/3.C/3.D 待实现）
+
+- [ ] **E.17 prepareaudio** → cb "Response from prepareaudio"（stub 仅 cb，无录音 / 无 getaudiourl 反向）
+- [ ] **E.18 mediaTypeAudio** → cb "Response from mediaTypeAudio"（stub 仅 cb，无下载 / 无播放 / 无 gameui_play_voice 反向）
+
+> 3.B AMR 转码 + 3.C 七牛上传 + 3.D 远端播放完整实现后升级。
 
 ---