fix: delay wooden fish audio upload

2026-06-06 22:53:05 +08:00
parent d5b51a4242
commit ff7a2f6284
13 changed files with 1771 additions and 38 deletions
--- a/docs/test-cases/【测试用例】敲木鱼音频延迟上传与本地标准化-2026-06-06.md
+++ b/docs/test-cases/【测试用例】敲木鱼音频延迟上传与本地标准化-2026-06-06.md
@@ -0,0 +1,81 @@
+# 敲木鱼音频延迟上传与本地标准化测试用例
+
+## 覆盖目标
+
+- 选择上传或录音结束后只在浏览器本地处理，不请求 OSS 上传凭证。
+- 用户点击 `生成` 时才上传处理后的音频 Blob/File，并把确认后的 `WoodenFishAudioAsset` 放入创建 session payload。
+- 上传和录音统一执行前后声音过小片段裁切、最长 1 秒限制、近似 `-15 LKFS` 响度平衡和峰值保护。
+- 音频面板明确显示 `最长 1 秒`，并正确处理上传、录音、重置、禁用和错误状态。
+- OSS 上传 client 只接收 Blob/File，不接受 Data URL，并覆盖上传凭证、OSS POST、资产确认和错误分支。
+
+## 音频处理 helper
+
+- 空文件：`size=0`，报 `音频文件为空，请重新选择。`
+- 非音频 MIME：`text/plain`，报 `请选择音频文件。`
+- 浏览器没有 `AudioContext`：报 `当前浏览器不支持音频处理。`
+- `decodeAudioData` 失败：报 `音频解码失败，请重新选择。`
+- 全静音或声音全低于阈值：报 `音频声音过小，请重新录制或上传。`
+- 前后静音裁切：低于阈值的头尾帧被裁掉，`startFrame` 和 `frameCount` 正确。
+- 裁切后刚好 `1000ms`：允许通过。
+- 裁切后超过 `1000ms`：报 `音频最长 1 秒。`
+- 上传来源 `uploaded` 与录音来源 `recorded`：返回 pending asset 保留对应 source。
+- 原文件名有扩展名：输出 `.wav` 文件名；无扩展名补 `.wav`；空白文件名输出 `creative-audio.wav`。
+- `URL.createObjectURL` 存在：`audioSrc` / `previewUrl` 为 blob URL；不存在时返回空字符串且不阻断处理。
+- 近似响度平衡：低 RMS 样本被拉向 `-15 LKFS` 目标。
+- 峰值保护：高峰值样本增益后不超过 `peakCeiling`。
+- 零能量 section：归一化阶段报声音过小。
+- WAV 编码：写入 RIFF/WAVE/data header、PCM16 数据长度和采样值。
+
+## 音频输入面板
+
+- 传入 `limitLabel` 时显示 `最长 1 秒`；未传入时不显示限制标签。
+- 无资产时显示默认音效文案。
+- 有资产且 `audioSrc` 存在时渲染 `<audio controls>`。
+- 有资产但无 `audioSrc` 时显示 `音效已选择`。
+- 点击重置调用 `onAssetChange(null)`。
+- 上传取消选择时不读取音频、不写入资产。
+- 上传成功后调用 `readFileAsAsset(file, 'uploaded')`，清空错误并写入资产。
+- 上传失败时展示错误，不写入资产。
+- 浏览器不支持录音时提示 `当前浏览器不支持录音。`
+- 麦克风启动失败时透传启动错误。
+- 录音停止后把 Blob 包成 File，并以 `recorded` 来源读取。
+- 录音保存失败时展示错误。
+- disabled 状态不启动录音，文件输入禁用。
+
+## 木鱼工作台链路
+
+- 音频面板显示 `最长 1 秒`，并只保留上传和录音入口。
+- 选择上传音频后只调用本地处理 helper，不调用 `uploadWoodenFishHitSoundAsset`。
+- 点击 `生成` 且有 pending 音频时，先上传处理后的 WAV，再调用 `woodenFishClient.createSession`。
+- 上传给 OSS 的文件是处理后的 WAV，文件名和 MIME 为 `.wav` / `audio/wav`。
+- 提交 payload 使用 OSS confirmed asset，不包含 `data:audio`。
+- 未选择音频时不上传 OSS，payload 使用默认木鱼音。
+- 处理阶段报超过 1 秒时展示错误，不写入用户音频；继续生成时走默认木鱼音。
+- OSS 上传失败时停留工作台，展示错误，不创建 session。
+- `createSession` 失败时停留工作台，展示错误。
+- 提交中重复点击 `生成` 不重复上传、不重复创建 session。
+- 替换本地音频时回收旧 `previewUrl`。
+
+## 木鱼音频上传 client
+
+- 空 Blob/File、超过 20MB、非音频 MIME 均在本地拒绝，不创建上传凭证。
+- File 上传默认使用 `file.name` 和 `file.type`。
+- Blob 上传支持通过显式文件名扩展推断 `audio/wav` 等音频 MIME。
+- Blob 缺少 MIME 且扩展未知时拒绝上传。
+- direct upload ticket 请求包含 `legacyPrefix`、path segments、fileName、contentType、access、maxSizeBytes 和木鱼音频 metadata。
+- OSS POST 成功后调用 `/api/assets/objects/confirm`。
+- OSS POST 非 2xx 时提示 `上传敲击音效失败。`，不确认资产对象。
+- confirm 失败时透传确认错误。
+- confirm 请求包含 bucket、objectKey、contentType、contentLength、assetKind、accessPolicy 和 entityId。
+- 成功返回的 `WoodenFishAudioAsset` 包含 assetObjectId、audioObjectKey、audioSrc、source 和 prompt。
+
+## 验证命令
+
+```bash
+npm run test -- src/components/common/creativeAudioProcessing.test.ts
+npm run test -- src/components/common/CreativeAudioInputPanel.test.tsx
+npm run test -- src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.test.tsx
+npm run test -- src/services/wooden-fish/woodenFishAssetClient.test.ts
+npm run typecheck
+npm run check:encoding
+```
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -174,7 +174,7 @@ npm run check:server-rs-ddd
 - Match3D 1:1 容器 UI：VectorEngine `/v1/images/edits` multipart 参考图。该容器参考图是后端生图协议输入，必须通过 `include_bytes!` 随 `api-server` 编译进二进制，避免 API 单独发布或运行目录缺少 `public/` 时生成失败。
 - 敲木鱼敲击物和背景环境图：VectorEngine `/v1/images/edits`，模型固定 `gpt-image-2`。敲击物支持 multipart 多参考图，第一张固定为后端内嵌默认木鱼图，用户上传图只作为新主题参考；prompt 必须要求 `1:1` 真实透明 alpha PNG 并禁止黑底、白底、棋盘格和任何实底背景。当前敲击物上传 OSS 前不做服务端抠图后处理，避免误伤玉米等主体像素。背景环境图只使用第一步抠图完成后的透明敲击物图作为参考，prompt 必须要求中央主体预留区保持干净，中央 40% 区域禁止出现主题主体、主体局部特写、轮廓影子或重复元素，主题元素只能作为外围氛围，且必须显式声明不继承任何绿色底色、绿幕底色或纯绿色画布。
 - Hyper3D / Rodin：只保留后端安全代理和旧数据兼容；Rodin 提交、状态、下载和响应解析归属 `platform-hyper3d`，`api-server/src/hyper3d_generation.rs` 只做路由、配置和错误 envelope 映射；新 Match3D 草稿和批量新增不再生成 GLB。
- 音频：视觉小说专用音频路由保留；VectorEngine Suno/Vidu provider 协议、任务提交/查询、音频 URL 提取、下载、MIME/extension 归一和 OSS put 请求准备归属 `platform-audio`。`api-server/src/vector_engine_audio_generation.rs` 只做路由、配置、计费、asset object confirm、entity binding 和错误 envelope 映射；拼图、抓大鹅和敲木鱼提示词生成音效入口暂时关闭，通用 `/api/creation/audio/*` 对这些目标返回 `410 Gone`。敲木鱼创作只接收上传 / 录音音频资产；未提供时由 `api-server` 写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。
+- 音频：视觉小说专用音频路由保留；VectorEngine Suno/Vidu provider 协议、任务提交/查询、音频 URL 提取、下载、MIME/extension 归一和 OSS put 请求准备归属 `platform-audio`。`api-server/src/vector_engine_audio_generation.rs` 只做路由、配置、计费、asset object confirm、entity binding 和错误 envelope 映射；拼图、抓大鹅和敲木鱼提示词生成音效入口暂时关闭，通用 `/api/creation/audio/*` 对这些目标返回 `410 Gone`。敲木鱼创作只接收上传 / 录音音频资产；前端选择或录音阶段只在浏览器本地处理待提交音频，统一限制裁切后最长 1 秒、裁掉前后声音过小片段，并用浏览器端近似响度算法平衡到 `-15 LKFS` 后做峰值保护。点击生成时才直传 OSS 并确认 `asset_object`，创作 JSON 只提交轻量 `WoodenFishAudioAsset`，不得继续上传 Data URL 音频；未提供时由 `api-server` 写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。
 - OSS：私有 generated legacy path 进入浏览器前必须通过 `/api/assets/read-url` 换签；不要裸请求 `/generated-*`。OSS 签名、读签名、HEAD 和 PUT 的结构化日志由 `platform-oss` 输出，排查资产写入 / 确认失败时优先按 `operation`、`object_key` / `key_prefix`、`status_class`、`error_kind` 和 `elapsed_ms` 下钻。
 - 外部 API 失败审计：外部供应商调用未成功时，`api-server` 必须发送 OTLP 失败事件并写入 `tracking_event`。VectorEngine 图片 provider 在 `platform-image` 内输出结构化日志和 `PlatformImageFailureAudit`，覆盖 `request_send`、`response_body`、`upstream_status`、`response_parse`、`missing_image` 和 `image_download` 阶段；`api-server` 只把该 audit 映射成 `external_api_call_failure`，`scope_kind = module`、`scope_id = provider`、`module_key = external-api`。metadata 固定包含 provider、endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel、rawExcerpt，以及在调用方可获得上下文时补充的 `userId`（触发者）和 `profileId`（草稿 / 作品 / 场景作用域）。图片生成入口应优先把 owner user id 和 profile id 透传到失败审计，不要只保留 provider 级聚合，否则很难按“谁触发、哪个作品触发”定位问题。入库优先复用 tracking outbox，outbox 不可写或保护阈值拒绝时回退同步写 SpacetimeDB；不得新增前端兜底或在 SpacetimeDB reducer 内做外部 I/O。
 - 外部生成运行记录：所有外部生成编排的完成态统一写入 `tracking_event`，`event_key = external_generation_run`，`scope_kind = module`，`scope_id = provider`，`module_key = external-generation`。metadata 固定包含 `runId`、`provider`、`operation`、`requestLabel`、`requestPayload`、`status`、`success`、`failureReason`、`providerRequestId`、`resultPayload`、`startedAtMicros`、`completedAtMicros` 和 `durationMs`。这类记录只用于运行审计和排障，不再走 `ai_task` 旧表。
--- a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
+++ b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
@@ -188,7 +188,7 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
 创作输入固定为：

 1. `敲什么`：敲击物单图资产槽位。默认模板使用内置透明 PNG `/wooden-fish/default-hit-object.png` 作为 `bundled-default` 敲击物资产，避免默认关键词被重新语义化改形；用户输入自定义关键词或上传参考图时，后端必须以默认木鱼图作为基础结构和画风参考，使用 image2 生成最终敲击物图案，上传图只作为新主题参考，不直接进入运行态。自定义 `compile-draft` / `regenerate-hit-object` 必须完成 image2 -> OSS 私有对象 -> asset object 登记和绑定后，再由 `api-server` 注入真实 `hitObjectAsset.imageSrc`，不能只写 `/generated-wooden-fish-assets/...` 占位路径，也不能接受前端请求自带的 `hitObjectAsset` 短路生成。
-2. `敲击音效`：音频资产槽位，当前创作阶段只支持用户上传或麦克风录制；麦克风录制结束后，前端会自动裁掉音频开头连续静音段，再把裁剪后的录音作为 `recorded` 音频资产写入表单。上传音频不做裁剪；浏览器音频解码或裁剪失败时保留原始录音继续保存，不能让用户录音丢失。未提供音频时统一写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。提示词生成音效入口临时关闭，通用 `/api/creation/audio/sound-effect` 对木鱼 `hit_sound` 目标也返回 `410 Gone`；`hitSoundPrompt` 只作为历史兼容字段保留，不参与当前创作流程，也不得由 `spacetime-client` 合成假音频路径。
+2. `敲击音效`：音频资产槽位，当前创作阶段只支持用户上传或麦克风录制；音频面板必须在前端明确显示 `最长 1 秒`。选择文件或录音结束后，前端只在浏览器本地解码并生成待提交音频对象，不在选择阶段请求 `/api/assets/direct-upload-tickets`。上传和录音统一裁掉前后声音过小片段，裁切后仍超过 1 秒时提示错误且不写入表单状态；有效音频按浏览器端近似算法做响度平衡，目标为 GY/T 377-2023 口径下的 `-15 LKFS`，并做峰值保护后重新编码为可上传 Blob。用户点击 `生成` 时才把处理后的音频直传 OSS、确认 `asset_object`，创作 session/action 只提交 `hitSoundAsset.assetObjectId`、`audioSrc` 和对象 key 等轻量字段；未提供音频时统一写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。提示词生成音效入口临时关闭，通用 `/api/creation/audio/sound-effect` 对木鱼 `hit_sound` 目标也返回 `410 Gone`；`hitSoundPrompt` 只作为历史兼容字段保留，不参与当前创作流程，也不得由 `spacetime-client` 合成假音频路径。后端对敲木鱼创作 JSON 的放宽 body limit 仅用于兼容旧小程序 Data URL 请求，不作为新链路输入方式。
 3. `功德有什么`：最多 8 条飘字，创作态首屏只保留一个默认词条 `幸运`，其下提供加号格继续追加词条；创作态只保存词条名，运行态飘字展示时再追加 `+1`。运行态顶部总数卡采用品牌化徽标样式，子项计数器预置展示在可展开面板中，未出现词条初始值为 0。
 4. `作品标题 / 作品简介 / 主题标签`：不再放在创作工作台首屏，改为生成草稿后的结果页补录区，提交试玩或发布前必须先写回当前作品信息。主题标签编辑样式对齐拼图结果页的胶囊标签编辑器。

--- a/server-rs/crates/api-server/src/app.rs
+++ b/server-rs/crates/api-server/src/app.rs
@@ -1504,6 +1504,88 @@ mod tests {
        assert!(!body_text.contains("length limit exceeded"));
    }

+    #[tokio::test]
+    async fn wooden_fish_session_creation_accepts_legacy_audio_body_above_default_limit() {
+        let state = AppState::new(AppConfig::default()).expect("state should build");
+        let seed_user =
+            seed_phone_user_with_password(&state, "13800138026", TEST_PASSWORD).await;
+        let token = sign_test_user_token(&state, &seed_user, "sess_wooden_fish_audio_body");
+        let app = build_router(state);
+        let request_body = format!(
+            "{{\"templateId\":\"wooden-fish\",\"hitSoundAsset\":{{\"audioSrc\":\"data:audio/webm;base64,{}\"}}",
+            "A".repeat(3 * 1024 * 1024)
+        );
+        assert!(request_body.len() > 2 * 1024 * 1024);
+
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/creation/wooden-fish/sessions")
+                    .header("authorization", format!("Bearer {token}"))
+                    .header("content-type", "application/json")
+                    .body(Body::from(request_body))
+                    .expect("request should build"),
+            )
+            .await
+            .expect("request should succeed");
+
+        assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+        let body = response
+            .into_body()
+            .collect()
+            .await
+            .expect("response body should collect")
+            .to_bytes();
+        let body_text = String::from_utf8_lossy(&body);
+        assert!(
+            body_text.contains("hitSoundAsset") || body_text.contains("missing field"),
+            "handler should parse the oversized wooden fish payload before rejecting invalid JSON fields: {body_text}"
+        );
+        assert!(!body_text.contains("length limit exceeded"));
+    }
+
+    #[tokio::test]
+    async fn wooden_fish_actions_accept_legacy_audio_body_above_default_limit() {
+        let state = AppState::new(AppConfig::default()).expect("state should build");
+        let seed_user =
+            seed_phone_user_with_password(&state, "13800138027", TEST_PASSWORD).await;
+        let token = sign_test_user_token(&state, &seed_user, "sess_wooden_fish_action_body");
+        let app = build_router(state);
+        let request_body = format!(
+            "{{\"actionType\":\"replace-hit-sound\",\"hitSoundAsset\":{{\"audioSrc\":\"data:audio/webm;base64,{}\"}}",
+            "A".repeat(3 * 1024 * 1024)
+        );
+        assert!(request_body.len() > 2 * 1024 * 1024);
+
+        let response = app
+            .oneshot(
+                Request::builder()
+                    .method("POST")
+                    .uri("/api/creation/wooden-fish/sessions/wooden-fish-session-large/actions")
+                    .header("authorization", format!("Bearer {token}"))
+                    .header("content-type", "application/json")
+                    .body(Body::from(request_body))
+                    .expect("request should build"),
+            )
+            .await
+            .expect("request should succeed");
+
+        assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+        let body = response
+            .into_body()
+            .collect()
+            .await
+            .expect("response body should collect")
+            .to_bytes();
+        let body_text = String::from_utf8_lossy(&body);
+        assert!(
+            body_text.contains("hitSoundAsset") || body_text.contains("missing field"),
+            "handler should parse the oversized wooden fish action payload before rejecting invalid JSON fields: {body_text}"
+        );
+        assert!(!body_text.contains("length limit exceeded"));
+    }
+
    #[tokio::test]
    async fn password_entry_rejects_unknown_phone_without_registration() {
        let app = build_router(AppState::new(AppConfig::default()).expect("state should build"));
--- a/server-rs/crates/api-server/src/modules/wooden_fish.rs
+++ b/server-rs/crates/api-server/src/modules/wooden_fish.rs
@@ -1,27 +1,36 @@
 use axum::{
-    Router, middleware,
-    routing::{delete, get, post},
+    Router,
+    extract::DefaultBodyLimit,
+    middleware,
+    routing::{get, post},
 };

 use crate::{
    auth::{require_bearer_auth, require_runtime_principal_auth},
    state::AppState,
    wooden_fish::{
-        checkpoint_wooden_fish_run, create_wooden_fish_session, delete_wooden_fish_work,
-        execute_wooden_fish_action, finish_wooden_fish_run, get_wooden_fish_gallery_detail,
-        get_wooden_fish_runtime_work, get_wooden_fish_session, list_wooden_fish_gallery,
-        list_wooden_fish_works, publish_wooden_fish_work, start_wooden_fish_run,
+        checkpoint_wooden_fish_run, create_wooden_fish_session, execute_wooden_fish_action,
+        finish_wooden_fish_run, get_wooden_fish_gallery_detail, get_wooden_fish_runtime_work,
+        get_wooden_fish_session, list_wooden_fish_gallery, list_wooden_fish_works,
+        publish_wooden_fish_work, start_wooden_fish_run,
    },
 };

+const WOODEN_FISH_CREATION_BODY_LIMIT_BYTES: usize = 32 * 1024 * 1024;
+
 pub fn router(state: AppState) -> Router<AppState> {
    Router::new()
        .route(
            "/api/creation/wooden-fish/sessions",
-            post(create_wooden_fish_session).route_layer(middleware::from_fn_with_state(
-                state.clone(),
-                require_bearer_auth,
-            )),
+            post(create_wooden_fish_session)
+                // 中文注释：兼容旧小程序把参考图或录音 Data URL 放进创作 JSON 的请求；新前端音频会先直传 OSS。
+                .layer(DefaultBodyLimit::max(
+                    WOODEN_FISH_CREATION_BODY_LIMIT_BYTES,
+                ))
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_bearer_auth,
+                )),
        )
        .route(
            "/api/creation/wooden-fish/sessions/{session_id}",
@@ -32,10 +41,15 @@ pub fn router(state: AppState) -> Router<AppState> {
        )
        .route(
            "/api/creation/wooden-fish/sessions/{session_id}/actions",
-            post(execute_wooden_fish_action).route_layer(middleware::from_fn_with_state(
-                state.clone(),
-                require_bearer_auth,
-            )),
+            post(execute_wooden_fish_action)
+                // 中文注释：compile/regenerate 会携带参考图旧兼容输入，避免 Axum 默认 2MB 先于 handler 拦截。
+                .layer(DefaultBodyLimit::max(
+                    WOODEN_FISH_CREATION_BODY_LIMIT_BYTES,
+                ))
+                .route_layer(middleware::from_fn_with_state(
+                    state.clone(),
+                    require_bearer_auth,
+                )),
        )
        .route(
            "/api/creation/wooden-fish/works",
@@ -44,13 +58,6 @@ pub fn router(state: AppState) -> Router<AppState> {
                require_bearer_auth,
            )),
        )
-        .route(
-            "/api/creation/wooden-fish/works/{profile_id}",
-            delete(delete_wooden_fish_work).route_layer(middleware::from_fn_with_state(
-                state.clone(),
-                require_bearer_auth,
-            )),
-        )
        .route(
            "/api/creation/wooden-fish/works/{profile_id}/publish",
            post(publish_wooden_fish_work).route_layer(middleware::from_fn_with_state(
--- a/src/components/common/CreativeAudioInputPanel.test.tsx
+++ b/src/components/common/CreativeAudioInputPanel.test.tsx
@@ -0,0 +1,300 @@
+/* @vitest-environment jsdom */
+
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import type { ComponentProps } from 'react';
+import { afterEach, expect, test, vi } from 'vitest';
+
+import {
+  CreativeAudioInputPanel,
+} from './CreativeAudioInputPanel';
+import type { CreativeAudioAsset } from './creativeAudioFileAsset';
+
+type TestAudioAsset = CreativeAudioAsset;
+
+const originalMediaRecorder = globalThis.MediaRecorder;
+const originalMediaDevices = navigator.mediaDevices;
+
+afterEach(() => {
+  globalThis.MediaRecorder = originalMediaRecorder;
+  Object.defineProperty(navigator, 'mediaDevices', {
+    configurable: true,
+    value: originalMediaDevices,
+  });
+  vi.restoreAllMocks();
+});
+
+function buildAsset(overrides: Partial<TestAudioAsset> = {}): TestAudioAsset {
+  return {
+    assetId: 'asset-test',
+    audioSrc: 'blob:audio-preview',
+    audioObjectKey: '',
+    assetObjectId: '',
+    source: 'uploaded',
+    prompt: 'hit.wav',
+    durationMs: 800,
+    ...overrides,
+  };
+}
+
+function renderPanel(
+  overrides: Partial<ComponentProps<typeof CreativeAudioInputPanel<TestAudioAsset>>> = {},
+) {
+  const onAssetChange = vi.fn();
+  const onError = vi.fn();
+  const readFileAsAsset = vi.fn(async (file: File, source: 'uploaded' | 'recorded') =>
+    buildAsset({
+      audioSrc: `blob:${source}`,
+      source,
+      prompt: file.name,
+    }),
+  );
+
+  const rendered = render(
+    <CreativeAudioInputPanel<TestAudioAsset>
+      title="敲击音效"
+      defaultLabel="默认木鱼音"
+      asset={null}
+      buildRecordedFileName={() => 'recorded-hit.webm'}
+      onAssetChange={onAssetChange}
+      onError={onError}
+      readFileAsAsset={readFileAsAsset}
+      {...overrides}
+    />,
+  );
+
+  return { ...rendered, onAssetChange, onError, readFileAsAsset };
+}
+
+function getUploadInput() {
+  const input = screen
+    .getByText('上传')
+    .closest('label')
+    ?.querySelector('input[type="file"]') as HTMLInputElement | null;
+  expect(input).not.toBeNull();
+  return input!;
+}
+
+test('音频面板按需显示最长限制标签', () => {
+  renderPanel({ limitLabel: '最长 1 秒' });
+
+  expect(screen.getByText('最长 1 秒')).toBeTruthy();
+});
+
+test('音频面板未传限制标签时不渲染限制提示', () => {
+  renderPanel();
+
+  expect(screen.queryByText('最长 1 秒')).toBeNull();
+});
+
+test('音频面板无资产时显示默认音效文案', () => {
+  renderPanel();
+
+  expect(screen.getByText('默认木鱼音')).toBeTruthy();
+});
+
+test('音频面板有预览地址时渲染 audio 控件', () => {
+  const { container } = render(
+    <CreativeAudioInputPanel<TestAudioAsset>
+      title="敲击音效"
+      defaultLabel="默认木鱼音"
+      asset={buildAsset({ audioSrc: 'blob:preview' })}
+      buildRecordedFileName={() => 'recorded-hit.webm'}
+      onAssetChange={() => {}}
+      onError={() => {}}
+    />,
+  );
+
+  expect(container.querySelector('audio')?.getAttribute('src')).toBe(
+    'blob:preview',
+  );
+});
+
+test('音频面板有资产但无预览地址时显示已选择状态', () => {
+  renderPanel({ asset: buildAsset({ audioSrc: '' }) });
+
+  expect(screen.getByText('音效已选择')).toBeTruthy();
+});
+
+test('点击重置清空当前音频资产', () => {
+  const onAssetChange = vi.fn();
+  renderPanel({
+    asset: buildAsset(),
+    onAssetChange,
+  });
+
+  fireEvent.click(screen.getByRole('button', { name: '重置' }));
+
+  expect(onAssetChange).toHaveBeenCalledWith(null);
+});
+
+test('取消上传选择时不读取音频', () => {
+  const { readFileAsAsset, onAssetChange } = renderPanel();
+
+  fireEvent.change(getUploadInput(), { target: { files: [] } });
+
+  expect(readFileAsAsset).not.toHaveBeenCalled();
+  expect(onAssetChange).not.toHaveBeenCalled();
+});
+
+test('上传音频成功后清空错误并写入资产', async () => {
+  const audioFile = new File(['audio'], 'hit.webm', { type: 'audio/webm' });
+  const { readFileAsAsset, onAssetChange, onError } = renderPanel();
+
+  fireEvent.change(getUploadInput(), { target: { files: [audioFile] } });
+
+  await waitFor(() =>
+    expect(readFileAsAsset).toHaveBeenCalledWith(audioFile, 'uploaded'),
+  );
+  await waitFor(() => expect(onAssetChange).toHaveBeenCalledTimes(1));
+  expect(onError).toHaveBeenCalledWith(null);
+});
+
+test('上传音频失败时提示错误且不写入资产', async () => {
+  const readFileAsAsset = vi.fn(async () => {
+    throw new Error('音频最长 1 秒。');
+  });
+  const onAssetChange = vi.fn();
+  const onError = vi.fn();
+  renderPanel({ readFileAsAsset, onAssetChange, onError });
+
+  fireEvent.change(getUploadInput(), {
+    target: {
+      files: [new File(['audio'], 'hit.webm', { type: 'audio/webm' })],
+    },
+  });
+
+  await waitFor(() => expect(onError).toHaveBeenCalledWith('音频最长 1 秒。'));
+  expect(onAssetChange).not.toHaveBeenCalled();
+});
+
+test('浏览器不支持录音时提示错误', async () => {
+  Object.defineProperty(navigator, 'mediaDevices', {
+    configurable: true,
+    value: undefined,
+  });
+  globalThis.MediaRecorder = undefined as unknown as typeof MediaRecorder;
+  const { onError } = renderPanel();
+
+  fireEvent.click(screen.getByRole('button', { name: '录音' }));
+
+  await waitFor(() =>
+    expect(onError).toHaveBeenCalledWith('当前浏览器不支持录音。'),
+  );
+});
+
+test('录音启动失败时透传启动错误', async () => {
+  Object.defineProperty(navigator, 'mediaDevices', {
+    configurable: true,
+    value: {
+      getUserMedia: vi.fn(async () => {
+        throw new Error('麦克风拒绝授权。');
+      }),
+    },
+  });
+  globalThis.MediaRecorder = class {
+    start = vi.fn();
+    stop = vi.fn();
+  } as unknown as typeof MediaRecorder;
+  const { onError } = renderPanel();
+
+  fireEvent.click(screen.getByRole('button', { name: '录音' }));
+
+  await waitFor(() => expect(onError).toHaveBeenCalledWith('麦克风拒绝授权。'));
+});
+
+test('录音停止后按 recorded 来源读取音频', async () => {
+  const stopTrack = vi.fn();
+  const recorderInstances: Array<{
+    ondataavailable: ((event: BlobEvent) => void) | null;
+    onstop: (() => void) | null;
+  }> = [];
+
+  Object.defineProperty(navigator, 'mediaDevices', {
+    configurable: true,
+    value: {
+      getUserMedia: vi.fn(async () => ({
+        getTracks: () => [{ stop: stopTrack }],
+      })),
+    },
+  });
+  globalThis.MediaRecorder = class {
+    mimeType = 'audio/webm';
+    ondataavailable: ((event: BlobEvent) => void) | null = null;
+    onstop: (() => void) | null = null;
+
+    constructor() {
+      recorderInstances.push(this);
+    }
+
+    start = vi.fn();
+
+    stop = vi.fn(() => {
+      this.ondataavailable?.({
+        data: new Blob(['recorded-audio'], { type: 'audio/webm' }),
+      } as BlobEvent);
+      this.onstop?.();
+    });
+  } as unknown as typeof MediaRecorder;
+
+  const { readFileAsAsset, onAssetChange } = renderPanel();
+
+  fireEvent.click(screen.getByRole('button', { name: '录音' }));
+  await waitFor(() => expect(screen.getByRole('button', { name: '停止' })).toBeTruthy());
+  fireEvent.click(screen.getByRole('button', { name: '停止' }));
+
+  await waitFor(() => expect(readFileAsAsset).toHaveBeenCalledTimes(1));
+  const [recordedFile, source] = readFileAsAsset.mock.calls[0]!;
+  expect(recordedFile).toBeInstanceOf(File);
+  expect((recordedFile as File).name).toBe('recorded-hit.webm');
+  expect(source).toBe('recorded');
+  expect(stopTrack).toHaveBeenCalledTimes(1);
+  await waitFor(() => expect(onAssetChange).toHaveBeenCalledTimes(1));
+  expect(recorderInstances).toHaveLength(1);
+});
+
+test('录音保存失败时提示错误', async () => {
+  Object.defineProperty(navigator, 'mediaDevices', {
+    configurable: true,
+    value: {
+      getUserMedia: vi.fn(async () => ({
+        getTracks: () => [],
+      })),
+    },
+  });
+  globalThis.MediaRecorder = class {
+    mimeType = 'audio/webm';
+    ondataavailable: ((event: BlobEvent) => void) | null = null;
+    onstop: (() => void) | null = null;
+    start = vi.fn();
+    stop = vi.fn(() => this.onstop?.());
+  } as unknown as typeof MediaRecorder;
+  const readFileAsAsset = vi.fn(async () => {
+    throw new Error('音频声音过小，请重新录制或上传。');
+  });
+  const onError = vi.fn();
+  renderPanel({ readFileAsAsset, onError });
+
+  fireEvent.click(screen.getByRole('button', { name: '录音' }));
+  await waitFor(() => expect(screen.getByRole('button', { name: '停止' })).toBeTruthy());
+  fireEvent.click(screen.getByRole('button', { name: '停止' }));
+
+  await waitFor(() =>
+    expect(onError).toHaveBeenCalledWith('音频声音过小，请重新录制或上传。'),
+  );
+});
+
+test('禁用状态不启动录音也不允许上传', () => {
+  const getUserMedia = vi.fn();
+  Object.defineProperty(navigator, 'mediaDevices', {
+    configurable: true,
+    value: { getUserMedia },
+  });
+  const { container } = renderPanel({ disabled: true });
+
+  fireEvent.click(screen.getByRole('button', { name: '录音' }));
+
+  expect(getUserMedia).not.toHaveBeenCalled();
+  const input = container.querySelector('input[type="file"]');
+  expect(input).not.toBeNull();
+  expect((input as HTMLInputElement).disabled).toBe(true);
+});
--- a/src/components/common/CreativeAudioInputPanel.tsx
+++ b/src/components/common/CreativeAudioInputPanel.tsx
@@ -5,12 +5,12 @@ import {
  type CreativeAudioAsset,
  readCreativeAudioFileAsAsset,
 } from './creativeAudioFileAsset';
-import { trimLeadingSilenceFromRecordedAudioFile } from './creativeAudioSilenceTrim';

 type CreativeAudioInputPanelProps<TAsset extends CreativeAudioAsset> = {
  disabled?: boolean;
  title: string;
  defaultLabel: string;
+  limitLabel?: string;
  asset: TAsset | null;
  buildRecordedFileName: () => string;
  onAssetChange: (asset: TAsset | null) => void;
@@ -25,6 +25,7 @@ export function CreativeAudioInputPanel<TAsset extends CreativeAudioAsset>({
  disabled = false,
  title,
  defaultLabel,
+  limitLabel,
  asset,
  buildRecordedFileName,
  onAssetChange,
@@ -64,8 +65,7 @@ export function CreativeAudioInputPanel<TAsset extends CreativeAudioAsset>({
        const file = new File([blob], buildRecordedFileName(), {
          type: blob.type,
        });
-        void trimLeadingSilenceFromRecordedAudioFile(file)
-          .then((trimmedFile) => readFileAsAsset(trimmedFile, 'recorded'))
+        void readFileAsAsset(file, 'recorded')
          .then(onAssetChange)
          .catch((caughtError) => {
            onError(
@@ -95,8 +95,15 @@ export function CreativeAudioInputPanel<TAsset extends CreativeAudioAsset>({
  return (
    <section className="platform-subpanel rounded-[1.25rem] p-4">
      <div className="mb-3 flex items-center justify-between gap-3">
-        <div className="text-sm font-black text-[var(--platform-text-strong)]">
-          {title}
+        <div className="flex min-w-0 items-center gap-2">
+          <div className="text-sm font-black text-[var(--platform-text-strong)]">
+            {title}
+          </div>
+          {limitLabel ? (
+            <div className="rounded-full bg-white/70 px-2 py-1 text-[11px] font-black text-[var(--platform-text-soft)]">
+              {limitLabel}
+            </div>
+          ) : null}
        </div>
        {asset ? (
          <button
--- a/src/components/common/creativeAudioProcessing.test.ts
+++ b/src/components/common/creativeAudioProcessing.test.ts
@@ -0,0 +1,241 @@
+import { afterEach, expect, test, vi } from 'vitest';
+
+import {
+  encodePcmChannelsToWavBlob,
+  findAudibleFrameRange,
+  normalizeAudioBufferSection,
+  prepareCreativeAudioFileForLocalUse,
+} from './creativeAudioProcessing';
+
+const originalAudioContext = globalThis.AudioContext;
+const originalCreateObjectUrl = URL.createObjectURL;
+
+afterEach(() => {
+  globalThis.AudioContext = originalAudioContext;
+  URL.createObjectURL = originalCreateObjectUrl;
+  vi.restoreAllMocks();
+});
+
+function createAudioBufferStub(
+  channels: number[][],
+  sampleRate = 1000,
+): AudioBuffer {
+  return {
+    length: channels[0]?.length ?? 0,
+    numberOfChannels: channels.length,
+    sampleRate,
+    duration: (channels[0]?.length ?? 0) / sampleRate,
+    getChannelData: (channel: number) =>
+      new Float32Array(channels[channel] ?? []),
+  } as AudioBuffer;
+}
+
+function installAudioContextMock(
+  decodeAudioData: (bytes: ArrayBuffer) => Promise<AudioBuffer>,
+) {
+  globalThis.AudioContext = class {
+    decodeAudioData = decodeAudioData;
+    close = vi.fn();
+  } as unknown as typeof AudioContext;
+}
+
+test('prepareCreativeAudioFileForLocalUse rejects empty audio files', async () => {
+  await expect(
+    prepareCreativeAudioFileForLocalUse(
+      new File([], 'empty.webm', { type: 'audio/webm' }),
+      'uploaded',
+    ),
+  ).rejects.toThrow('音频文件为空，请重新选择。');
+});
+
+test('prepareCreativeAudioFileForLocalUse rejects non-audio files', async () => {
+  await expect(
+    prepareCreativeAudioFileForLocalUse(
+      new File(['not-audio'], 'note.txt', { type: 'text/plain' }),
+      'uploaded',
+    ),
+  ).rejects.toThrow('请选择音频文件。');
+});
+
+test('prepareCreativeAudioFileForLocalUse reports decode failures', async () => {
+  installAudioContextMock(async () => {
+    throw new Error('decode failed');
+  });
+
+  await expect(
+    prepareCreativeAudioFileForLocalUse(
+      new File(['audio-bytes'], 'broken.webm', { type: 'audio/webm' }),
+      'uploaded',
+    ),
+  ).rejects.toThrow('音频解码失败，请重新选择。');
+});
+
+test('prepareCreativeAudioFileForLocalUse rejects when AudioContext is unavailable', async () => {
+  globalThis.AudioContext = undefined as unknown as typeof AudioContext;
+
+  await expect(
+    prepareCreativeAudioFileForLocalUse(
+      new File(['audio-bytes'], 'hit.webm', { type: 'audio/webm' }),
+      'uploaded',
+    ),
+  ).rejects.toThrow('当前浏览器不支持音频处理。');
+});
+
+test('prepareCreativeAudioFileForLocalUse rejects all-silent audio', async () => {
+  installAudioContextMock(async () => createAudioBufferStub([[0, 0.001, 0]], 1000));
+
+  await expect(
+    prepareCreativeAudioFileForLocalUse(
+      new File(['audio-bytes'], 'silent.webm', { type: 'audio/webm' }),
+      'recorded',
+    ),
+  ).rejects.toThrow('音频声音过小，请重新录制或上传。');
+});
+
+test('prepareCreativeAudioFileForLocalUse allows audio exactly at the visible limit', async () => {
+  URL.createObjectURL = vi.fn(() => 'blob:one-second-audio');
+  installAudioContextMock(async () =>
+    createAudioBufferStub([Array.from({ length: 1000 }, () => 0.2)], 1000),
+  );
+
+  const asset = await prepareCreativeAudioFileForLocalUse(
+    new File(['audio-bytes'], 'one-second.webm', { type: 'audio/webm' }),
+    'uploaded',
+  );
+
+  expect(asset.durationMs).toBe(1000);
+  expect(asset.audioSrc).toBe('blob:one-second-audio');
+});
+
+test('prepareCreativeAudioFileForLocalUse rejects audio longer than the visible limit after trimming', async () => {
+  installAudioContextMock(async () =>
+    createAudioBufferStub([[0, ...Array.from({ length: 1001 }, () => 0.2), 0]], 1000),
+  );
+
+  await expect(
+    prepareCreativeAudioFileForLocalUse(
+      new File(['audio-bytes'], 'long.webm', { type: 'audio/webm' }),
+      'uploaded',
+    ),
+  ).rejects.toThrow('音频最长 1 秒。');
+});
+
+test('findAudibleFrameRange trims quiet leading and trailing frames', () => {
+  const buffer = createAudioBufferStub([
+    [0, 0.003, 0.02, 0.2, -0.03, 0.004],
+    [0, 0, 0, 0.05, 0, 0],
+  ]);
+
+  expect(findAudibleFrameRange(buffer, 0.01)).toEqual({
+    startFrame: 2,
+    frameCount: 3,
+  });
+});
+
+test('normalizeAudioBufferSection pulls samples toward -15 LKFS approximation', () => {
+  const buffer = createAudioBufferStub([[0.02, -0.02, 0.02, -0.02]], 1000);
+  const normalized = normalizeAudioBufferSection(
+    buffer,
+    { startFrame: 0, frameCount: 4 },
+    { targetLkfs: -15, peakCeiling: 0.98 },
+  );
+  const channel = normalized[0];
+  expect(channel).toBeDefined();
+  const rms = Math.sqrt(
+    channel!.reduce((sum, sample) => sum + sample * sample, 0) /
+      channel!.length,
+  );
+
+  expect(rms).toBeCloseTo(Math.pow(10, -15 / 20), 3);
+});
+
+test('normalizeAudioBufferSection avoids clipping when target gain is too high', () => {
+  const buffer = createAudioBufferStub([[0.8, -0.8, 0.4, -0.4]], 1000);
+  const normalized = normalizeAudioBufferSection(
+    buffer,
+    { startFrame: 0, frameCount: 4 },
+    { targetLkfs: 0, peakCeiling: 0.5 },
+  );
+  const channel = normalized[0];
+  expect(channel).toBeDefined();
+  const peak = Math.max(...channel!.map((sample) => Math.abs(sample)));
+
+  expect(peak).toBeLessThanOrEqual(0.5);
+});
+
+test('normalizeAudioBufferSection rejects zero-energy sections', () => {
+  const buffer = createAudioBufferStub([[0, 0, 0]], 1000);
+
+  expect(() =>
+    normalizeAudioBufferSection(buffer, { startFrame: 0, frameCount: 3 }),
+  ).toThrow('音频声音过小，请重新录制或上传。');
+});
+
+test('prepareCreativeAudioFileForLocalUse writes trimmed normalized wav blob', async () => {
+  URL.createObjectURL = vi.fn(() => 'blob:processed-audio');
+  installAudioContextMock(async () =>
+    createAudioBufferStub([[0, 0, 0.12, -0.12, 0]], 1000),
+  );
+
+  const asset = await prepareCreativeAudioFileForLocalUse(
+    new File(['audio-bytes'], 'hit.webm', { type: 'audio/webm' }),
+    'uploaded',
+  );
+  const bytes = await asset.blob.arrayBuffer();
+
+  expect(asset.fileName).toBe('hit.wav');
+  expect(asset.mimeType).toBe('audio/wav');
+  expect(asset.audioSrc).toBe('blob:processed-audio');
+  expect(asset.durationMs).toBe(2);
+  expect(String.fromCharCode(...new Uint8Array(bytes, 0, 4))).toBe('RIFF');
+  expect(String.fromCharCode(...new Uint8Array(bytes, 8, 4))).toBe('WAVE');
+});
+
+test('prepareCreativeAudioFileForLocalUse still succeeds without object URL support', async () => {
+  URL.createObjectURL = undefined as unknown as typeof URL.createObjectURL;
+  installAudioContextMock(async () =>
+    createAudioBufferStub([[0.12, -0.12]], 1000),
+  );
+
+  const asset = await prepareCreativeAudioFileForLocalUse(
+    new File(['audio-bytes'], 'hit.webm', { type: 'audio/webm' }),
+    'recorded',
+  );
+
+  expect(asset.audioSrc).toBe('');
+  expect(asset.previewUrl).toBe('');
+});
+
+test('prepareCreativeAudioFileForLocalUse normalizes processed wav file names', async () => {
+  URL.createObjectURL = vi.fn(() => 'blob:processed-audio');
+  installAudioContextMock(async () =>
+    createAudioBufferStub([[0.12, -0.12]], 1000),
+  );
+
+  await expect(
+    prepareCreativeAudioFileForLocalUse(
+      new File(['audio-bytes'], 'hit-sound', { type: 'audio/webm' }),
+      'uploaded',
+    ),
+  ).resolves.toMatchObject({ fileName: 'hit-sound.wav' });
+  await expect(
+    prepareCreativeAudioFileForLocalUse(
+      new File(['audio-bytes'], '   ', { type: 'audio/webm' }),
+      'uploaded',
+    ),
+  ).resolves.toMatchObject({ fileName: 'creative-audio.wav' });
+});
+
+test('encodePcmChannelsToWavBlob writes pcm16 wav bytes', async () => {
+  const blob = encodePcmChannelsToWavBlob(
+    [new Float32Array([0.25, -0.5])],
+    1000,
+  );
+  const bytes = await blob.arrayBuffer();
+  const view = new DataView(bytes);
+
+  expect(blob.type).toBe('audio/wav');
+  expect(view.getUint32(40, true)).toBe(4);
+  expect(view.getInt16(44, true)).toBeCloseTo(8191, -1);
+  expect(view.getInt16(46, true)).toBeCloseTo(-16384, -1);
+});
--- a/src/components/common/creativeAudioProcessing.ts
+++ b/src/components/common/creativeAudioProcessing.ts
@@ -0,0 +1,308 @@
+import {
+  type CreativeAudioAsset,
+} from './creativeAudioFileAsset';
+
+type BrowserAudioGlobal = typeof globalThis & {
+  webkitAudioContext?: typeof AudioContext;
+};
+
+export type CreativeAudioSource = 'uploaded' | 'recorded';
+
+export type PendingCreativeAudioAsset = CreativeAudioAsset & {
+  fileName: string;
+  mimeType: string;
+  blob: Blob;
+  source: CreativeAudioSource;
+  previewUrl: string;
+  durationMs: number;
+};
+
+export type CreativeAudioProcessingOptions = {
+  maxDurationMs?: number;
+  silenceThreshold?: number;
+  targetLkfs?: number;
+  peakCeiling?: number;
+};
+
+export type AudibleFrameRange = {
+  startFrame: number;
+  frameCount: number;
+};
+
+const DEFAULT_MAX_DURATION_MS = 1000;
+const DEFAULT_SILENCE_THRESHOLD = 0.01;
+const DEFAULT_TARGET_LKFS = -15;
+const DEFAULT_PEAK_CEILING = 0.98;
+const WAV_HEADER_BYTE_LENGTH = 44;
+const WAV_BITS_PER_SAMPLE = 16;
+const WAV_BYTES_PER_SAMPLE = WAV_BITS_PER_SAMPLE / 8;
+
+export async function prepareCreativeAudioFileForLocalUse(
+  file: File,
+  source: CreativeAudioSource,
+  options: CreativeAudioProcessingOptions = {},
+): Promise<PendingCreativeAudioAsset> {
+  validateCreativeAudioFile(file);
+
+  const decodedBuffer = await decodeCreativeAudioFile(file);
+  const range = findAudibleFrameRange(
+    decodedBuffer,
+    options.silenceThreshold ?? DEFAULT_SILENCE_THRESHOLD,
+  );
+  if (!range) {
+    throw new Error('音频声音过小，请重新录制或上传。');
+  }
+
+  const durationMs = Math.round(
+    (range.frameCount / decodedBuffer.sampleRate) * 1000,
+  );
+  const maxDurationMs = options.maxDurationMs ?? DEFAULT_MAX_DURATION_MS;
+  if (durationMs > maxDurationMs) {
+    throw new Error(`音频最长 ${formatDurationSeconds(maxDurationMs)} 秒。`);
+  }
+
+  const normalized = normalizeAudioBufferSection(decodedBuffer, range, {
+    targetLkfs: options.targetLkfs ?? DEFAULT_TARGET_LKFS,
+    peakCeiling: options.peakCeiling ?? DEFAULT_PEAK_CEILING,
+  });
+  const blob = encodePcmChannelsToWavBlob(normalized, decodedBuffer.sampleRate);
+  const fileName = buildProcessedAudioFileName(file.name);
+  const previewUrl =
+    typeof URL !== 'undefined' && typeof URL.createObjectURL === 'function'
+      ? URL.createObjectURL(blob)
+      : '';
+
+  return {
+    assetId: `local-${source}-${Date.now()}`,
+    audioSrc: previewUrl,
+    audioObjectKey: '',
+    assetObjectId: '',
+    source,
+    prompt: file.name,
+    durationMs,
+    fileName,
+    mimeType: blob.type,
+    blob,
+    previewUrl,
+  };
+}
+
+export function findAudibleFrameRange(
+  buffer: AudioBuffer,
+  silenceThreshold = DEFAULT_SILENCE_THRESHOLD,
+): AudibleFrameRange | null {
+  const threshold = Math.max(0, silenceThreshold);
+  let startFrame: number | null = null;
+  let endFrame: number | null = null;
+
+  for (let frameIndex = 0; frameIndex < buffer.length; frameIndex += 1) {
+    if (isFrameAudible(buffer, frameIndex, threshold)) {
+      startFrame = frameIndex;
+      break;
+    }
+  }
+
+  if (startFrame === null) {
+    return null;
+  }
+
+  for (let frameIndex = buffer.length - 1; frameIndex >= startFrame; frameIndex -= 1) {
+    if (isFrameAudible(buffer, frameIndex, threshold)) {
+      endFrame = frameIndex;
+      break;
+    }
+  }
+
+  if (endFrame === null) {
+    return null;
+  }
+
+  return {
+    startFrame,
+    frameCount: endFrame - startFrame + 1,
+  };
+}
+
+export function normalizeAudioBufferSection(
+  buffer: AudioBuffer,
+  range: AudibleFrameRange,
+  options: Pick<CreativeAudioProcessingOptions, 'targetLkfs' | 'peakCeiling'> = {},
+) {
+  const channelCount = Math.max(1, buffer.numberOfChannels);
+  const targetLkfs = options.targetLkfs ?? DEFAULT_TARGET_LKFS;
+  const peakCeiling = Math.max(0.01, options.peakCeiling ?? DEFAULT_PEAK_CEILING);
+  const channels = Array.from({ length: channelCount }, (_value, channelIndex) =>
+    copyChannelSection(buffer, channelIndex, range),
+  );
+  const stats = measurePcmStats(channels);
+  if (stats.rms <= 0 || stats.peak <= 0) {
+    throw new Error('音频声音过小，请重新录制或上传。');
+  }
+
+  // 浏览器端近似：用全通道 RMS 估算 LKFS，再按 GY/T 377-2023 目标值拉到 -15 LKFS。
+  const targetLinear = Math.pow(10, targetLkfs / 20);
+  const loudnessGain = targetLinear / stats.rms;
+  const protectedGain = Math.min(loudnessGain, peakCeiling / stats.peak);
+
+  return channels.map((channel) =>
+    Float32Array.from(channel, (sample) => clampSample(sample * protectedGain)),
+  );
+}
+
+export function encodePcmChannelsToWavBlob(
+  channels: Float32Array[],
+  sampleRate: number,
+) {
+  const channelCount = Math.max(1, channels.length);
+  const frameCount = channels[0]?.length ?? 0;
+  const dataByteLength = frameCount * channelCount * WAV_BYTES_PER_SAMPLE;
+  const output = new ArrayBuffer(WAV_HEADER_BYTE_LENGTH + dataByteLength);
+  const view = new DataView(output);
+
+  writeAscii(view, 0, 'RIFF');
+  view.setUint32(4, 36 + dataByteLength, true);
+  writeAscii(view, 8, 'WAVE');
+  writeAscii(view, 12, 'fmt ');
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true);
+  view.setUint16(22, channelCount, true);
+  view.setUint32(24, sampleRate, true);
+  view.setUint32(28, sampleRate * channelCount * WAV_BYTES_PER_SAMPLE, true);
+  view.setUint16(32, channelCount * WAV_BYTES_PER_SAMPLE, true);
+  view.setUint16(34, WAV_BITS_PER_SAMPLE, true);
+  writeAscii(view, 36, 'data');
+  view.setUint32(40, dataByteLength, true);
+
+  let outputOffset = WAV_HEADER_BYTE_LENGTH;
+  for (let frameIndex = 0; frameIndex < frameCount; frameIndex += 1) {
+    for (let channelIndex = 0; channelIndex < channelCount; channelIndex += 1) {
+      const sample = channels[channelIndex]?.[frameIndex] ?? 0;
+      view.setInt16(outputOffset, toSignedPcm16(sample), true);
+      outputOffset += WAV_BYTES_PER_SAMPLE;
+    }
+  }
+
+  return new Blob([output], { type: 'audio/wav' });
+}
+
+function validateCreativeAudioFile(file: File) {
+  if (file.size <= 0) {
+    throw new Error('音频文件为空，请重新选择。');
+  }
+  if (!resolveFileMimeType(file).startsWith('audio/')) {
+    throw new Error('请选择音频文件。');
+  }
+}
+
+async function decodeCreativeAudioFile(file: File) {
+  const AudioContextConstructor = getAudioContextConstructor();
+  if (!AudioContextConstructor) {
+    throw new Error('当前浏览器不支持音频处理。');
+  }
+
+  const context = new AudioContextConstructor();
+  try {
+    const bytes = await file.arrayBuffer();
+    return await context.decodeAudioData(bytes.slice(0));
+  } catch {
+    throw new Error('音频解码失败，请重新选择。');
+  } finally {
+    void context.close();
+  }
+}
+
+function getAudioContextConstructor() {
+  const audioGlobal = globalThis as BrowserAudioGlobal;
+  return audioGlobal.AudioContext ?? audioGlobal.webkitAudioContext ?? null;
+}
+
+function resolveFileMimeType(file: File) {
+  if (file.type.trim()) {
+    return file.type.trim();
+  }
+  return '';
+}
+
+function isFrameAudible(
+  buffer: AudioBuffer,
+  frameIndex: number,
+  threshold: number,
+) {
+  for (
+    let channelIndex = 0;
+    channelIndex < buffer.numberOfChannels;
+    channelIndex += 1
+  ) {
+    const channelData = buffer.getChannelData(channelIndex);
+    if (Math.abs(channelData[frameIndex] ?? 0) > threshold) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function copyChannelSection(
+  buffer: AudioBuffer,
+  channelIndex: number,
+  range: AudibleFrameRange,
+) {
+  const source =
+    channelIndex < buffer.numberOfChannels
+      ? buffer.getChannelData(channelIndex)
+      : new Float32Array(buffer.length);
+  const output = new Float32Array(range.frameCount);
+  for (let frameOffset = 0; frameOffset < range.frameCount; frameOffset += 1) {
+    output[frameOffset] = source[range.startFrame + frameOffset] ?? 0;
+  }
+  return output;
+}
+
+function measurePcmStats(channels: Float32Array[]) {
+  let sumSquares = 0;
+  let peak = 0;
+  let sampleCount = 0;
+  for (const channel of channels) {
+    for (const sample of channel) {
+      sumSquares += sample * sample;
+      peak = Math.max(peak, Math.abs(sample));
+      sampleCount += 1;
+    }
+  }
+  return {
+    rms: sampleCount > 0 ? Math.sqrt(sumSquares / sampleCount) : 0,
+    peak,
+  };
+}
+
+function clampSample(sample: number) {
+  return Math.max(-1, Math.min(1, sample));
+}
+
+function toSignedPcm16(sample: number) {
+  const clamped = clampSample(sample);
+  return clamped < 0
+    ? Math.round(clamped * 0x8000)
+    : Math.round(clamped * 0x7fff);
+}
+
+function writeAscii(view: DataView, offset: number, value: string) {
+  for (let index = 0; index < value.length; index += 1) {
+    view.setUint8(offset + index, value.charCodeAt(index));
+  }
+}
+
+function buildProcessedAudioFileName(fileName: string) {
+  const normalizedName = fileName.trim();
+  if (!normalizedName) {
+    return 'creative-audio.wav';
+  }
+  return /\.[^.]+$/u.test(normalizedName)
+    ? normalizedName.replace(/\.[^.]+$/u, '.wav')
+    : `${normalizedName}.wav`;
+}
+
+function formatDurationSeconds(durationMs: number) {
+  return Number.isInteger(durationMs / 1000)
+    ? String(durationMs / 1000)
+    : (durationMs / 1000).toFixed(1);
+}
--- a/src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.test.tsx
+++ b/src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.test.tsx
@@ -4,7 +4,12 @@ import { fireEvent, render, screen, waitFor, within } from '@testing-library/rea
 import { beforeEach, expect, test, vi } from 'vitest';

 import { woodenFishClient } from '../../../services/wooden-fish/woodenFishClient';
-import { WOODEN_FISH_DEFAULT_HIT_OBJECT_PROMPT } from '../../../services/wooden-fish/woodenFishDefaults';
+import { uploadWoodenFishHitSoundAsset } from '../../../services/wooden-fish/woodenFishAssetClient';
+import {
+  WOODEN_FISH_DEFAULT_HIT_OBJECT_PROMPT,
+  WOODEN_FISH_DEFAULT_HIT_SOUND_ASSET,
+} from '../../../services/wooden-fish/woodenFishDefaults';
+import { prepareCreativeAudioFileForLocalUse } from '../../common/creativeAudioProcessing';
 import { WoodenFishCreationWorkspace } from './WoodenFishCreationWorkspace';

 vi.mock('../../../services/wooden-fish/woodenFishClient', () => ({
@@ -13,8 +18,18 @@ vi.mock('../../../services/wooden-fish/woodenFishClient', () => ({
  },
 }));

+vi.mock('../../../services/wooden-fish/woodenFishAssetClient', () => ({
+  uploadWoodenFishHitSoundAsset: vi.fn(),
+}));
+
+vi.mock('../../common/creativeAudioProcessing', () => ({
+  prepareCreativeAudioFileForLocalUse: vi.fn(),
+}));
+
 beforeEach(() => {
  vi.mocked(woodenFishClient.createSession).mockReset();
+  vi.mocked(uploadWoodenFishHitSoundAsset).mockReset();
+  vi.mocked(prepareCreativeAudioFileForLocalUse).mockReset();
  vi.mocked(woodenFishClient.createSession).mockResolvedValue({
    session: {
      sessionId: 'wooden-fish-session-test',
@@ -25,6 +40,30 @@ beforeEach(() => {
      updatedAt: '2026-05-24T00:00:00Z',
    },
  });
+  vi.mocked(uploadWoodenFishHitSoundAsset).mockResolvedValue({
+    assetId: 'uploaded-hit-sound-asset',
+    audioSrc: '/generated-wooden-fish-assets/draft/hit-sound.webm',
+    audioObjectKey: 'generated-wooden-fish-assets/draft/hit-sound.webm',
+    assetObjectId: 'asset-object-hit-sound',
+    source: 'uploaded',
+    prompt: 'hit-sound.webm',
+    durationMs: null,
+  });
+  vi.mocked(prepareCreativeAudioFileForLocalUse).mockImplementation(
+    async (file, source) => ({
+      assetId: 'local-hit-sound-asset',
+      audioSrc: 'blob:local-hit-sound',
+      audioObjectKey: '',
+      assetObjectId: '',
+      source,
+      prompt: file.name,
+      durationMs: 800,
+      fileName: 'hit-sound.wav',
+      mimeType: 'audio/wav',
+      blob: new Blob(['processed-audio-bytes'], { type: 'audio/wav' }),
+      previewUrl: 'blob:local-hit-sound',
+    }),
+  );
 });

 test('敲什么输入栏初始置空但提交时仍使用默认生成提示词', async () => {
@@ -103,10 +142,303 @@ test('敲击音效临时关闭提示词生成入口，仅保留上传和录音',

  expect(section).not.toBeNull();
  expect(within(section as HTMLElement).queryByText('音效描述')).toBeNull();
+  expect(within(section as HTMLElement).getByText('最长 1 秒')).toBeTruthy();
  expect(within(section as HTMLElement).getByText('上传')).toBeTruthy();
  expect(within(section as HTMLElement).getByText('录音')).toBeTruthy();
 });

+test('敲击音效上传后只生成本地待提交音频，点击生成时才上传 OSS', async () => {
+  const onSubmitted = vi.fn();
+  const audioFile = new File(['audio-bytes'], 'hit-sound.webm', {
+    type: 'audio/webm',
+  });
+
+  render(
+    <WoodenFishCreationWorkspace
+      onBack={() => {}}
+      onSubmitted={onSubmitted}
+    />,
+  );
+
+  const input = screen
+    .getByText('上传')
+    .closest('label')
+    ?.querySelector('input[type="file"]') as HTMLInputElement | null;
+  expect(input).not.toBeNull();
+
+  fireEvent.change(input as HTMLInputElement, {
+    target: { files: [audioFile] },
+  });
+
+  await waitFor(() =>
+    expect(prepareCreativeAudioFileForLocalUse).toHaveBeenCalledWith(
+      audioFile,
+      'uploaded',
+    ),
+  );
+  expect(uploadWoodenFishHitSoundAsset).not.toHaveBeenCalled();
+
+  fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+  await waitFor(() => expect(onSubmitted).toHaveBeenCalledTimes(1));
+  expect(uploadWoodenFishHitSoundAsset).toHaveBeenCalledTimes(1);
+  const uploadCall = vi.mocked(uploadWoodenFishHitSoundAsset).mock.calls[0];
+  expect(uploadCall).toBeDefined();
+  const [uploadedFile, source] = uploadCall!;
+  expect(uploadedFile).toBeInstanceOf(File);
+  const uploadedAudioFile = uploadedFile as File;
+  expect(uploadedAudioFile.name).toBe('hit-sound.wav');
+  expect(uploadedFile.type).toBe('audio/wav');
+  expect(source).toBe('uploaded');
+
+  const payload = onSubmitted.mock.calls[0]?.[1];
+  expect(payload.hitSoundAsset).toMatchObject({
+    assetObjectId: 'asset-object-hit-sound',
+    audioSrc: '/generated-wooden-fish-assets/draft/hit-sound.webm',
+  });
+  expect(payload.hitSoundAsset.audioSrc).not.toContain('data:audio');
+});
+
+test('未选择敲击音效时生成不上传 OSS 且使用默认木鱼音', async () => {
+  const onSubmitted = vi.fn();
+
+  render(
+    <WoodenFishCreationWorkspace
+      onBack={() => {}}
+      onSubmitted={onSubmitted}
+    />,
+  );
+
+  fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+  await waitFor(() => expect(onSubmitted).toHaveBeenCalledTimes(1));
+  expect(uploadWoodenFishHitSoundAsset).not.toHaveBeenCalled();
+  expect(onSubmitted.mock.calls[0]?.[1].hitSoundAsset).toEqual(
+    WOODEN_FISH_DEFAULT_HIT_SOUND_ASSET,
+  );
+});
+
+test('敲击音效超过 1 秒时展示错误且不提交音频', async () => {
+  const onSubmitted = vi.fn();
+  vi.mocked(prepareCreativeAudioFileForLocalUse).mockRejectedValueOnce(
+    new Error('音频最长 1 秒。'),
+  );
+
+  render(
+    <WoodenFishCreationWorkspace
+      onBack={() => {}}
+      onSubmitted={onSubmitted}
+    />,
+  );
+
+  const input = screen
+    .getByText('上传')
+    .closest('label')
+    ?.querySelector('input[type="file"]') as HTMLInputElement | null;
+  expect(input).not.toBeNull();
+
+  fireEvent.change(input as HTMLInputElement, {
+    target: {
+      files: [
+        new File(['too-long-audio'], 'too-long.webm', {
+          type: 'audio/webm',
+        }),
+      ],
+    },
+  });
+
+  expect(await screen.findByText('音频最长 1 秒。')).toBeTruthy();
+  fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+  await waitFor(() => expect(onSubmitted).toHaveBeenCalledTimes(1));
+  expect(uploadWoodenFishHitSoundAsset).not.toHaveBeenCalled();
+  expect(onSubmitted.mock.calls[0]?.[1].hitSoundAsset.audioSrc).not.toContain(
+    'data:audio',
+  );
+});
+
+test('敲击音效上传失败时停留在工作台且不创建 session', async () => {
+  vi.mocked(uploadWoodenFishHitSoundAsset).mockRejectedValueOnce(
+    new Error('上传敲击音效失败。'),
+  );
+
+  render(
+    <WoodenFishCreationWorkspace
+      onBack={() => {}}
+      onSubmitted={() => {}}
+    />,
+  );
+
+  const input = screen
+    .getByText('上传')
+    .closest('label')
+    ?.querySelector('input[type="file"]') as HTMLInputElement | null;
+  expect(input).not.toBeNull();
+
+  fireEvent.change(input as HTMLInputElement, {
+    target: {
+      files: [
+        new File(['audio-bytes'], 'hit-sound.webm', {
+          type: 'audio/webm',
+        }),
+      ],
+    },
+  });
+  await waitFor(() =>
+    expect(prepareCreativeAudioFileForLocalUse).toHaveBeenCalledTimes(1),
+  );
+
+  fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+  expect(await screen.findByText('上传敲击音效失败。')).toBeTruthy();
+  expect(woodenFishClient.createSession).not.toHaveBeenCalled();
+});
+
+test('创建木鱼草稿失败时停留工作台并展示错误', async () => {
+  vi.mocked(woodenFishClient.createSession).mockRejectedValueOnce(
+    new Error('创建敲木鱼共创会话失败'),
+  );
+
+  render(
+    <WoodenFishCreationWorkspace
+      onBack={() => {}}
+      onSubmitted={() => {}}
+    />,
+  );
+
+  fireEvent.click(screen.getByRole('button', { name: '生成' }));
+
+  expect(await screen.findByText('创建敲木鱼共创会话失败')).toBeTruthy();
+  expect(uploadWoodenFishHitSoundAsset).not.toHaveBeenCalled();
+});
+
+test('提交中重复点击生成不会重复上传或创建 session', async () => {
+  let resolveUpload: (
+    value: Awaited<ReturnType<typeof uploadWoodenFishHitSoundAsset>>,
+  ) => void = () => {};
+  vi.mocked(uploadWoodenFishHitSoundAsset).mockImplementationOnce(
+    () =>
+      new Promise<Awaited<ReturnType<typeof uploadWoodenFishHitSoundAsset>>>((resolve) => {
+        resolveUpload = resolve;
+      }),
+  );
+
+  render(
+    <WoodenFishCreationWorkspace
+      onBack={() => {}}
+      onSubmitted={() => {}}
+    />,
+  );
+
+  const input = screen
+    .getByText('上传')
+    .closest('label')
+    ?.querySelector('input[type="file"]') as HTMLInputElement | null;
+  expect(input).not.toBeNull();
+
+  fireEvent.change(input as HTMLInputElement, {
+    target: {
+      files: [
+        new File(['audio-bytes'], 'hit-sound.webm', {
+          type: 'audio/webm',
+        }),
+      ],
+    },
+  });
+  await waitFor(() =>
+    expect(prepareCreativeAudioFileForLocalUse).toHaveBeenCalledTimes(1),
+  );
+
+  const submitButton = screen.getByRole('button', { name: '生成' });
+  fireEvent.click(submitButton);
+  fireEvent.click(submitButton);
+
+  expect(uploadWoodenFishHitSoundAsset).toHaveBeenCalledTimes(1);
+  expect(woodenFishClient.createSession).not.toHaveBeenCalled();
+
+  resolveUpload({
+    assetId: 'uploaded-hit-sound-asset',
+    audioSrc: '/generated-wooden-fish-assets/draft/hit-sound.webm',
+    audioObjectKey: 'generated-wooden-fish-assets/draft/hit-sound.webm',
+    assetObjectId: 'asset-object-hit-sound',
+    source: 'uploaded',
+    prompt: 'hit-sound.webm',
+    durationMs: null,
+  });
+
+  await waitFor(() => expect(woodenFishClient.createSession).toHaveBeenCalledTimes(1));
+});
+
+test('替换本地敲击音效时回收旧预览地址', async () => {
+  const revokeObjectURL = vi.fn();
+  URL.revokeObjectURL = revokeObjectURL;
+  vi.mocked(prepareCreativeAudioFileForLocalUse)
+    .mockResolvedValueOnce({
+      assetId: 'local-hit-sound-old',
+      audioSrc: 'blob:old-hit-sound',
+      audioObjectKey: '',
+      assetObjectId: '',
+      source: 'uploaded',
+      prompt: 'old.webm',
+      durationMs: 800,
+      fileName: 'old.wav',
+      mimeType: 'audio/wav',
+      blob: new Blob(['old-audio'], { type: 'audio/wav' }),
+      previewUrl: 'blob:old-hit-sound',
+    })
+    .mockResolvedValueOnce({
+      assetId: 'local-hit-sound-new',
+      audioSrc: 'blob:new-hit-sound',
+      audioObjectKey: '',
+      assetObjectId: '',
+      source: 'uploaded',
+      prompt: 'new.webm',
+      durationMs: 700,
+      fileName: 'new.wav',
+      mimeType: 'audio/wav',
+      blob: new Blob(['new-audio'], { type: 'audio/wav' }),
+      previewUrl: 'blob:new-hit-sound',
+    });
+
+  render(
+    <WoodenFishCreationWorkspace
+      onBack={() => {}}
+      onSubmitted={() => {}}
+    />,
+  );
+
+  const input = screen
+    .getByText('上传')
+    .closest('label')
+    ?.querySelector('input[type="file"]') as HTMLInputElement | null;
+  expect(input).not.toBeNull();
+
+  fireEvent.change(input as HTMLInputElement, {
+    target: {
+      files: [
+        new File(['old'], 'old.webm', {
+          type: 'audio/webm',
+        }),
+      ],
+    },
+  });
+  await waitFor(() => expect(screen.getByText('重置')).toBeTruthy());
+
+  fireEvent.change(input as HTMLInputElement, {
+    target: {
+      files: [
+        new File(['new'], 'new.webm', {
+          type: 'audio/webm',
+        }),
+      ],
+    },
+  });
+
+  await waitFor(() =>
+    expect(revokeObjectURL).toHaveBeenCalledWith('blob:old-hit-sound'),
+  );
+});
+
 test('敲击音效和功德词条不放进独立滚动窗', () => {
  const { container } = render(
    <WoodenFishCreationWorkspace
--- a/src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.tsx
+++ b/src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.tsx
@@ -13,12 +13,17 @@ import type {
  WoodenFishWorkspaceCreateRequest,
 } from '../../../../packages/shared/src/contracts/woodenFish';
 import { readPuzzleReferenceImageAsDataUrl } from '../../../services/puzzleReferenceImage';
+import { uploadWoodenFishHitSoundAsset } from '../../../services/wooden-fish/woodenFishAssetClient';
 import { woodenFishClient } from '../../../services/wooden-fish/woodenFishClient';
 import {
  WOODEN_FISH_DEFAULT_HIT_OBJECT_PROMPT,
  WOODEN_FISH_DEFAULT_HIT_SOUND_ASSET,
 } from '../../../services/wooden-fish/woodenFishDefaults';
 import { CreativeAudioInputPanel } from '../../common/CreativeAudioInputPanel';
+import {
+  type PendingCreativeAudioAsset,
+  prepareCreativeAudioFileForLocalUse,
+} from '../../common/creativeAudioProcessing';
 import { CreativeImageInputPanel } from '../../common/CreativeImageInputPanel';

 type WoodenFishCreationWorkspaceProps = {
@@ -36,7 +41,7 @@ type WoodenFishCreationWorkspaceProps = {
 type WoodenFishWorkspaceFormState = {
  hitObjectPrompt: string;
  hitObjectReferenceImageSrc: string;
-  hitSoundAsset: WoodenFishAudioAsset | null;
+  hitSoundAsset: PendingCreativeAudioAsset | null;
  floatingWords: string[];
 };

@@ -132,6 +137,14 @@ export function WoodenFishCreationWorkspace({
    setLocalError(null);

    try {
+      const hitSoundAsset: WoodenFishAudioAsset = formState.hitSoundAsset
+        ? await uploadWoodenFishHitSoundAsset(
+            new File([formState.hitSoundAsset.blob], formState.hitSoundAsset.fileName, {
+              type: formState.hitSoundAsset.mimeType,
+            }),
+            formState.hitSoundAsset.source,
+          )
+        : WOODEN_FISH_DEFAULT_HIT_SOUND_ASSET;
      const payload: WoodenFishWorkspaceCreateRequest = {
        templateId: 'wooden-fish',
        workTitle: '',
@@ -143,8 +156,7 @@ export function WoodenFishCreationWorkspace({
        hitObjectReferenceImageSrc:
          formState.hitObjectReferenceImageSrc.trim() || null,
        hitSoundPrompt: null,
-        hitSoundAsset:
-          formState.hitSoundAsset ?? WOODEN_FISH_DEFAULT_HIT_SOUND_ASSET,
+        hitSoundAsset,
        floatingWords: normalizedFloatingWords,
      };
      const response = await woodenFishClient.createSession(payload);
@@ -246,18 +258,28 @@ export function WoodenFishCreationWorkspace({
        </div>

        <div className="flex flex-col gap-3 pr-0 lg:pr-1">
-          <CreativeAudioInputPanel<WoodenFishAudioAsset>
+          <CreativeAudioInputPanel<PendingCreativeAudioAsset>
            disabled={isBusy || isSubmitting}
            title="敲击音效"
            defaultLabel="默认木鱼音"
+            limitLabel="最长 1 秒"
            asset={formState.hitSoundAsset}
            buildRecordedFileName={() => `wooden-fish-hit-${Date.now()}.webm`}
-            onAssetChange={(asset) =>
+            readFileAsAsset={prepareCreativeAudioFileForLocalUse}
+            onAssetChange={(asset) => {
+              if (
+                formState.hitSoundAsset?.previewUrl &&
+                formState.hitSoundAsset.previewUrl !== asset?.previewUrl &&
+                typeof URL !== 'undefined' &&
+                typeof URL.revokeObjectURL === 'function'
+              ) {
+                URL.revokeObjectURL(formState.hitSoundAsset.previewUrl);
+              }
              setFormState((current) => ({
                ...current,
                hitSoundAsset: asset,
-              }))
-            }
+              }));
+            }}
            onError={setLocalError}
          />

--- a/src/services/wooden-fish/woodenFishAssetClient.test.ts
+++ b/src/services/wooden-fish/woodenFishAssetClient.test.ts
@@ -0,0 +1,212 @@
+/* @vitest-environment jsdom */
+
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+
+const requestJsonMock = vi.hoisted(() => vi.fn());
+
+vi.mock('../apiClient', () => ({
+  requestJson: requestJsonMock,
+}));
+
+import { uploadWoodenFishHitSoundAsset } from './woodenFishAssetClient';
+
+const uploadTicket = {
+  upload: {
+    bucket: 'private-bucket',
+    host: 'https://oss.example.test/upload',
+    objectKey: 'generated-wooden-fish-assets/draft/hit-sound/uploaded/1/hit.wav',
+    legacyPublicPath: '/generated-wooden-fish-assets/draft/hit-sound.wav',
+    formFields: {
+      key: 'object-key',
+      policy: 'policy-value',
+      empty: null,
+    },
+  },
+};
+
+const confirmedAsset = {
+  assetObject: {
+    assetObjectId: 'asset-object-hit-sound',
+    objectKey: uploadTicket.upload.objectKey,
+    assetKind: 'wooden_fish_hit_sound',
+  },
+};
+
+beforeEach(() => {
+  requestJsonMock.mockReset();
+  requestJsonMock
+    .mockResolvedValueOnce(uploadTicket)
+    .mockResolvedValueOnce(confirmedAsset);
+  globalThis.fetch = vi.fn(async () => new Response(null, { status: 204 }));
+  vi.useFakeTimers();
+  vi.setSystemTime(new Date('2026-06-06T12:00:00.000Z'));
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+test('空音频 Blob 不创建上传凭证', async () => {
+  await expect(
+    uploadWoodenFishHitSoundAsset(
+      new Blob([], { type: 'audio/wav' }),
+      'uploaded',
+      'empty.wav',
+    ),
+  ).rejects.toThrow('音频文件为空，请重新选择。');
+
+  expect(requestJsonMock).not.toHaveBeenCalled();
+});
+
+test('超过 20MB 的音频不创建上传凭证', async () => {
+  await expect(
+    uploadWoodenFishHitSoundAsset(
+      new Blob([new Uint8Array(20 * 1024 * 1024 + 1)], {
+        type: 'audio/wav',
+      }),
+      'uploaded',
+      'large.wav',
+    ),
+  ).rejects.toThrow('音频文件过大，请压缩后再上传。');
+
+  expect(requestJsonMock).not.toHaveBeenCalled();
+});
+
+test('非音频 MIME 不创建上传凭证', async () => {
+  await expect(
+    uploadWoodenFishHitSoundAsset(
+      new Blob(['text'], { type: 'text/plain' }),
+      'uploaded',
+      'note.txt',
+    ),
+  ).rejects.toThrow('请选择音频文件。');
+
+  expect(requestJsonMock).not.toHaveBeenCalled();
+});
+
+test('File 上传使用自身 MIME 和文件名创建上传凭证', async () => {
+  const file = new File(['audio'], 'hit.webm', { type: 'audio/webm' });
+
+  const asset = await uploadWoodenFishHitSoundAsset(file, 'uploaded');
+
+  expect(requestJsonMock).toHaveBeenNthCalledWith(
+    1,
+    '/api/assets/direct-upload-tickets',
+    expect.objectContaining({
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+    }),
+    '创建敲击音效上传凭证失败',
+  );
+  const ticketBody = JSON.parse(requestJsonMock.mock.calls[0]![1].body);
+  expect(ticketBody).toMatchObject({
+    legacyPrefix: 'generated-wooden-fish-assets',
+    fileName: 'hit.webm',
+    contentType: 'audio/webm',
+    access: 'private',
+    maxSizeBytes: 20 * 1024 * 1024,
+    metadata: {
+      asset_kind: 'wooden_fish_hit_sound',
+      wooden_fish_slot: 'hit_sound',
+      wooden_fish_audio_source: 'uploaded',
+    },
+  });
+  expect(ticketBody.pathSegments).toEqual([
+    'wooden-fish',
+    'draft',
+    'hit-sound',
+    'uploaded',
+    String(Date.now()),
+  ]);
+  expect(fetch).toHaveBeenCalledWith(uploadTicket.upload.host, {
+    method: 'POST',
+    body: expect.any(FormData),
+  });
+  expect(asset).toMatchObject({
+    assetId: 'asset-object-hit-sound',
+    audioSrc: uploadTicket.upload.legacyPublicPath,
+    audioObjectKey: uploadTicket.upload.objectKey,
+    assetObjectId: 'asset-object-hit-sound',
+    source: 'uploaded',
+    prompt: 'hit.webm',
+  });
+});
+
+test('Blob 上传可通过文件名扩展推断音频 MIME', async () => {
+  const blob = new Blob(['audio']);
+
+  await uploadWoodenFishHitSoundAsset(blob, 'recorded', 'recorded.wav');
+
+  const ticketBody = JSON.parse(requestJsonMock.mock.calls[0]![1].body);
+  expect(ticketBody).toMatchObject({
+    fileName: 'recorded.wav',
+    contentType: 'audio/wav',
+    metadata: {
+      wooden_fish_audio_source: 'recorded',
+    },
+  });
+});
+
+test('Blob 缺少 MIME 且文件扩展未知时拒绝上传', async () => {
+  await expect(
+    uploadWoodenFishHitSoundAsset(new Blob(['audio']), 'uploaded', 'hit.bin'),
+  ).rejects.toThrow('请选择音频文件。');
+
+  expect(requestJsonMock).not.toHaveBeenCalled();
+});
+
+test('OSS POST 失败时不确认资产对象', async () => {
+  globalThis.fetch = vi.fn(async () => new Response(null, { status: 500 }));
+
+  await expect(
+    uploadWoodenFishHitSoundAsset(
+      new File(['audio'], 'hit.webm', { type: 'audio/webm' }),
+      'uploaded',
+    ),
+  ).rejects.toThrow('上传敲击音效失败。');
+
+  expect(requestJsonMock).toHaveBeenCalledTimes(1);
+});
+
+test('确认资产对象失败时透传确认错误', async () => {
+  requestJsonMock.mockReset();
+  requestJsonMock
+    .mockResolvedValueOnce(uploadTicket)
+    .mockRejectedValueOnce(new Error('确认敲击音效资产失败'));
+
+  await expect(
+    uploadWoodenFishHitSoundAsset(
+      new File(['audio'], 'hit.webm', { type: 'audio/webm' }),
+      'uploaded',
+    ),
+  ).rejects.toThrow('确认敲击音效资产失败');
+
+  expect(fetch).toHaveBeenCalledTimes(1);
+});
+
+test('确认资产对象时提交 OSS 对象和内容长度', async () => {
+  const file = new File(['audio'], 'hit.webm', { type: 'audio/webm' });
+
+  await uploadWoodenFishHitSoundAsset(file, 'uploaded');
+
+  expect(requestJsonMock).toHaveBeenNthCalledWith(
+    2,
+    '/api/assets/objects/confirm',
+    expect.objectContaining({
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+    }),
+    '确认敲击音效资产失败',
+  );
+  const confirmBody = JSON.parse(requestJsonMock.mock.calls[1]![1].body);
+  expect(confirmBody).toMatchObject({
+    bucket: uploadTicket.upload.bucket,
+    objectKey: uploadTicket.upload.objectKey,
+    contentType: 'audio/webm',
+    contentLength: file.size,
+    assetKind: 'wooden_fish_hit_sound',
+    accessPolicy: 'private',
+    entityId: 'hit_sound',
+  });
+});
--- a/src/services/wooden-fish/woodenFishAssetClient.ts
+++ b/src/services/wooden-fish/woodenFishAssetClient.ts
@@ -0,0 +1,141 @@
+import type { WoodenFishAudioAsset } from '../../../packages/shared/src/contracts/woodenFish';
+import { requestJson } from '../apiClient';
+
+const WOODEN_FISH_AUDIO_UPLOAD_MAX_BYTES = 20 * 1024 * 1024;
+
+type DirectUploadTicketResponse = {
+  upload: {
+    bucket: string;
+    host: string;
+    objectKey: string;
+    legacyPublicPath: string;
+    formFields: Record<string, string | null | undefined>;
+  };
+};
+
+type ConfirmAssetObjectResponse = {
+  assetObject: {
+    assetObjectId: string;
+    objectKey: string;
+    assetKind: string;
+  };
+};
+
+const MIME_BY_EXTENSION: Record<string, string> = {
+  m4a: 'audio/mp4',
+  mp3: 'audio/mpeg',
+  ogg: 'audio/ogg',
+  wav: 'audio/wav',
+  webm: 'audio/webm',
+};
+
+function resolveAudioContentType(file: Blob, fileName: string) {
+  if (file.type.trim()) {
+    return file.type.trim();
+  }
+  const extension = fileName.split('.').pop()?.trim().toLowerCase() ?? '';
+  return MIME_BY_EXTENSION[extension] ?? 'application/octet-stream';
+}
+
+function validateWoodenFishAudioFile(file: Blob, fileName: string) {
+  const contentType = resolveAudioContentType(file, fileName);
+  if (file.size <= 0) {
+    throw new Error('音频文件为空，请重新选择。');
+  }
+  if (file.size > WOODEN_FISH_AUDIO_UPLOAD_MAX_BYTES) {
+    throw new Error('音频文件过大，请压缩后再上传。');
+  }
+  if (!contentType.startsWith('audio/')) {
+    throw new Error('请选择音频文件。');
+  }
+  return contentType;
+}
+
+function buildWoodenFishAudioPathSegments(source: 'uploaded' | 'recorded') {
+  return ['wooden-fish', 'draft', 'hit-sound', source, `${Date.now()}`];
+}
+
+async function postDirectUploadFile(
+  upload: DirectUploadTicketResponse['upload'],
+  file: Blob,
+  fileName: string,
+) {
+  const formData = new FormData();
+  Object.entries(upload.formFields).forEach(([key, value]) => {
+    if (value !== null && value !== undefined) {
+      formData.append(key, value);
+    }
+  });
+  formData.append('file', file, fileName);
+
+  const response = await fetch(upload.host, {
+    method: 'POST',
+    body: formData,
+  });
+
+  if (!response.ok) {
+    throw new Error('上传敲击音效失败。');
+  }
+}
+
+export async function uploadWoodenFishHitSoundAsset(
+  file: Blob,
+  source: 'uploaded' | 'recorded',
+  fileName =
+    typeof File !== 'undefined' && file instanceof File
+      ? file.name
+      : 'wooden-fish-hit-sound.wav',
+): Promise<WoodenFishAudioAsset> {
+  const contentType = validateWoodenFishAudioFile(file, fileName);
+  const ticket = await requestJson<DirectUploadTicketResponse>(
+    '/api/assets/direct-upload-tickets',
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        legacyPrefix: 'generated-wooden-fish-assets',
+        pathSegments: buildWoodenFishAudioPathSegments(source),
+        fileName,
+        contentType,
+        access: 'private',
+        maxSizeBytes: WOODEN_FISH_AUDIO_UPLOAD_MAX_BYTES,
+        metadata: {
+          asset_kind: 'wooden_fish_hit_sound',
+          wooden_fish_slot: 'hit_sound',
+          wooden_fish_audio_source: source,
+        },
+      }),
+    },
+    '创建敲击音效上传凭证失败',
+  );
+
+  await postDirectUploadFile(ticket.upload, file, fileName);
+
+  const confirmed = await requestJson<ConfirmAssetObjectResponse>(
+    '/api/assets/objects/confirm',
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        bucket: ticket.upload.bucket,
+        objectKey: ticket.upload.objectKey,
+        contentType,
+        contentLength: file.size,
+        assetKind: 'wooden_fish_hit_sound',
+        accessPolicy: 'private',
+        entityId: 'hit_sound',
+      }),
+    },
+    '确认敲击音效资产失败',
+  );
+
+  return {
+    assetId: confirmed.assetObject.assetObjectId,
+    audioSrc: ticket.upload.legacyPublicPath,
+    audioObjectKey: confirmed.assetObject.objectKey,
+    assetObjectId: confirmed.assetObject.assetObjectId,
+    source,
+    prompt: fileName,
+    durationMs: null,
+  };
+}