feat: complete M6 custom world asset stage2

2026-04-22 18:06:08 +08:00
parent 2fe0a9083d
commit fc6519a7b7
8 changed files with 1888 additions and 140 deletions
--- a/backend-rewrite-tasklist/05_M6_ASSETS_OSS_EDITOR.md
+++ b/backend-rewrite-tasklist/05_M6_ASSETS_OSS_EDITOR.md
@@ -73,13 +73,13 @@
 - [x] 迁移动作模板查询（Stage 1 已接通 Rust 内置模板列表兼容接口）
 - [x] 迁移视频导入（Stage 1 已接通 Data URL 视频导入到 OSS 草稿区，不再写本地 `public/`）
 - [x] 迁移工作流缓存（Stage 1 已接通 Rust `GET/POST character-workflow-cache` 到 OSS JSON 草稿对象，不再写本地 `public/`）
- [x] 迁移场景图生成（Stage 1 已由 custom world `scene-image` 兼容路由写入 OSS 并确认/绑定；Stage 2 还需补真实 DashScope 图片生成，替换当前 Rust SVG 占位图）
- [x] 迁移封面图上传（Stage 1 已由 custom world `cover-image / cover-upload` 兼容路由写入 OSS 并确认/绑定；Stage 2 还需补 `cropRect + 16:9 + WebP 压缩`）
+- [x] 迁移场景图生成（已完成 Stage 2：custom world `scene-image` 走真实 DashScope 图片生成，并继续写入 `OSS + asset_object + asset_entity_binding`）
+- [x] 迁移封面图上传（已完成 Stage 2：custom world `cover-image / cover-upload` 已补齐真实 DashScope 生成与 `cropRect + 16:9 + WebP 压缩`）
 - [x] 首批收口 custom world `scene-image / cover-image / cover-upload` 到正式 `OSS + asset_object + asset_entity_binding` 主链（保持旧 `/generated-*` 返回 contract，不再写仓库 `public/`）

 补充说明：

-1. 本次收口只解决 custom world 兼容图片入口的正式资产真相链，不代表 DashScope 图片生成、任务状态、封面裁剪压缩能力已全量迁完。
+1. custom world 兼容图片入口现已完成 Stage 1 + Stage 2：正式资产真相链、真实 DashScope 图片生成，以及封面上传裁剪压缩都已迁完。
 2. 详细边界见：
   - [../docs/technical/M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md](../docs/technical/M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md)
 3. 角色动作模板与视频导入第一批已新增独立设计文档，当前只迁移：
@@ -93,10 +93,10 @@
 5. `2026-04-22` 复核确认：旧独立 `qwen-sprite-tool + qwenSpriteRoutes.ts` 已在 `2026-04-21` 清理，不再作为本轮现役迁移主链；当前仍保留的 `Qwen` 相关内容仅包括：
   - 角色资产 prompt 层对 `packages/shared/src/prompts/qwenSprite.ts` 的复用
   - 历史资源前缀 `/generated-qwen-sprites/*` 的读取兼容
-6. custom world 图片链已进入 Stage 2：
-   - `scene-image / cover-image` 需要把 Rust SVG 占位生成替换为真实 DashScope 图片生成
-   - `cover-upload` 需要补回 Node 旧链路中的 `cropRect + 16:9 + WebP 压缩`
-   - 详细口径见 [../docs/technical/M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md](../docs/technical/M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md)
+6. custom world 图片链 Stage 2 已完成：
+   - `scene-image / cover-image` 已替换为真实 DashScope 图片生成
+   - `cover-upload` 已补回 Node 旧链路中的 `cropRect + 16:9 + WebP 压缩`
+   - 详细口径与验证结果见 [../docs/technical/M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md](../docs/technical/M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md)

 ## 5. 路径兼容

@@ -149,5 +149,5 @@
   - `generate` 直接写入 OSS `generated-character-drafts/*`。
   - `jobs/:taskId` 从 `AiTaskService` 派生旧任务状态 contract。
   - `publish` 会把动作帧与总 manifest 写入 OSS `generated-animations/*`，并确认 `asset_object + asset_entity_binding`。
-7. custom world 场景图、封面图、封面上传已在 `M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md` 范围内接入正式 `OSS + asset_object + asset_entity_binding` 主链。
+7. custom world 场景图、封面图、封面上传已在 `M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md` + `M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md` 范围内完成正式 `OSS + asset_object + asset_entity_binding` 主链、真实 DashScope 图片生成和封面上传裁剪压缩。
 8. `content_hash/version`、`asset_job`、`asset_manifest` 与强业务资产表当前已冻结 Stage 1 边界，不再作为 M6 第一批工程阻塞项；后续若要做内容去重、manifest 查询、审核/回滚或 sprite sheet 强结构化，再进入独立阶段。
--- a/docs/technical/M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md
+++ b/docs/technical/M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md
@@ -19,6 +19,31 @@

 本批目标就是把这两段缺失能力补齐，同时继续保持 `Stage 1` 已冻结的 OSS 真相链。

+## 1.1 当前落地结果
+
+`2026-04-22` 已按本文口径完成 Rust `api-server` Stage 2 落地：
+
+1. `POST /api/custom-world/scene-image` 已切到真实 DashScope 图片生成
+2. `POST /api/custom-world/cover-image` 已切到真实 DashScope 图片生成
+3. `POST /api/custom-world/cover-upload` 已补齐 `cropRect + 16:9 + 1600x900 + WebP + 1.5 MB`
+4. 三条链路继续统一写入 `OSS + asset_object + asset_entity_binding`
+5. `/generated-custom-world-scenes/*` 与 `/generated-custom-world-covers/*` 旧读取路径兼容口径保持不变
+
+本次同时补齐的兼容细节：
+
+1. `scene-image` 新增兼容读取 `negativePrompt / referenceImageSrc / userPrompt / profile / landmark`
+2. `cover-image` 新增兼容读取 `referenceImageSrc / characterRoleIds`
+3. `cover-upload` 新增兼容读取 `cropRect`
+4. 参考图输入在 Rust 端兼容两种来源：
+   - `data:image/*;base64,...`
+   - 现有 `/generated-*` 旧路径，通过 OSS 短签名回读后转为 Data URL
+
+本批验证结果：
+
+1. `cargo check -p api-server` 通过
+2. `cargo test -p api-server custom_world_ai` 通过
+3. `npm run check:encoding` 通过
+
 ## 2. 本批范围

 ### 2.1 要完成的内容
--- a/docs/technical/NODE_BACKEND_MODULE_AND_API_INDEX.md
+++ b/docs/technical/NODE_BACKEND_MODULE_AND_API_INDEX.md
@@ -3,6 +3,8 @@
 > 该文档由 `server-node/src/manifest/backendCapabilityManifest.ts` 自动生成。
 > 生成命令：`npm run server-node:manifest:backend`
 > 生成时间：`2026-04-20T14:26:38.663Z`
+>
+> 过期说明：该索引生成于 `2026-04-20`，其中 `createQwenSpriteRoutes` 与 `/api/assets/qwen-sprite/*` 相关描述已在 `2026-04-21` 后失效。当前 Node 现役资产挂载面仅保留 `createCharacterAssetRoutes`；`Qwen` 仅剩 prompt 模板复用与 `/generated-qwen-sprites/*` 历史路径兼容，不再存在独立路由主链。

 ## 总览

--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -48,6 +48,7 @@
 - [SPACETIMEDB_CUSTOM_WORLD_LIBRARY_DETAIL_STAGE5_EXTENSION_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_LIBRARY_DETAIL_STAGE5_EXTENSION_DESIGN_2026-04-22.md)：补齐 `M5` Stage 5 遗漏的 owner-only `GET /api/runtime/custom-world-library/:profileId` 设计，冻结单条 profile detail 的 SpacetimeDB procedure、client facade、404 语义与 Axum 路由扩展方式。
 - [SPACETIMEDB_CUSTOM_WORLD_WORKS_AND_AGENT_EXTENSION_STAGE9_DESIGN_2026-04-22.md](./SPACETIMEDB_CUSTOM_WORLD_WORKS_AND_AGENT_EXTENSION_STAGE9_DESIGN_2026-04-22.md)：冻结 `M5` 剩余主链的 works、card detail、publish gate、supportedActions、action registry 与 AI/OSS 兼容路由边界，作为 Stage 9 到收口阶段的统一落地依据。
 - [M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md](./M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md)：冻结 `M6` 第一批 custom world 场景图、封面图、封面上传从本地 `public/` 临时落地切到 `OSS + asset_object + asset_entity_binding` 正式真相链的边界与槽位约定。
+- [M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md](./M6_CUSTOM_WORLD_ASSET_OSS_INTEGRATION_STAGE2_2026-04-22.md)：冻结 `M6` 第二批 custom world 图片链迁移口径，明确把 `scene-image / cover-image` 从 Rust SVG 占位切到真实 DashScope 图片生成，并补回 `cover-upload` 的 `cropRect + 16:9 + WebP 压缩`。
 - [M6_CHARACTER_ANIMATION_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md](./M6_CHARACTER_ANIMATION_ASSET_OSS_INTEGRATION_STAGE1_2026-04-22.md)：冻结 `M6` 第一批角色动作 `generate / jobs / publish` 接口从旧本地 `public/generated-*` 真相切到 `OSS + asset_object + asset_entity_binding + AI task` 的最小闭环与兼容 contract。
 - [M6_CHARACTER_ANIMATION_IMPORT_AND_TEMPLATE_STAGE1_2026-04-22.md](./M6_CHARACTER_ANIMATION_IMPORT_AND_TEMPLATE_STAGE1_2026-04-22.md)：冻结 `M6` 第一批角色动作模板查询与参考视频导入从旧 Node 本地草稿写盘切到 Rust `OSS` 草稿对象的接口 contract、对象键规划与暂不确认 `asset_object` 的边界。
 - [M6_CHARACTER_WORKFLOW_CACHE_OSS_STAGE1_2026-04-22.md](./M6_CHARACTER_WORKFLOW_CACHE_OSS_STAGE1_2026-04-22.md)：冻结 `M6` 第一批角色资产工作流缓存从旧 Node 本地 `workflow-cache.json` 切到 Rust `OSS` JSON 草稿对象的读写 contract、字段归一化与暂不落正式资产表的边界。
--- a/server-rs/Cargo.lock
+++ b/server-rs/Cargo.lock
@@ -76,6 +76,7 @@ dependencies = [
 "hmac",
 "http-body-util",
 "httpdate",
+ "image",
 "module-ai",
 "module-assets",
 "module-auth",
@@ -106,6 +107,7 @@ dependencies = [
 "url",
 "urlencoding",
 "uuid",
+ "webp",
 ]

 [[package]]
@@ -294,6 +296,12 @@ version = "1.25.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c8efb64bd706a16a1bdde310ae86b351e4d21550d98d056f22f8a7f7a2183fec"

+[[package]]
+name = "byteorder-lite"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f1fe948ff07f4bd06c30984e69f5b4899c516a3ef74f34df92a2df2ab535495"
+
 [[package]]
 name = "bytes"
 version = "1.11.1"
@@ -326,6 +334,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "43c5703da9466b66a946814e1adf53ea2c90f10063b86290cc9eb67ce3478a20"
 dependencies = [
 "find-msvc-tools",
+ "jobserver",
+ "libc",
 "shlex",
 ]

@@ -654,6 +664,15 @@ version = "2.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f1f227452a390804cdb637b74a86990f2a7d7ba4b7d5693aac9b4dd6defd8d6"

+[[package]]
+name = "fdeflate"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e6853b52649d4ac5c0bd02320cddc5ba956bdb407c4b75a2c6b75bf51500f8c"
+dependencies = [
+ "simd-adler32",
+]
+
 [[package]]
 name = "find-msvc-tools"
 version = "0.1.9"
@@ -850,6 +869,12 @@ dependencies = [
 "wasip3",
 ]

+[[package]]
+name = "glob"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
+
 [[package]]
 name = "hashbrown"
 version = "0.12.3"
@@ -1169,6 +1194,32 @@ dependencies = [
 "icu_properties",
 ]

+[[package]]
+name = "image"
+version = "0.25.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85ab80394333c02fe689eaf900ab500fbd0c2213da414687ebf995a65d5a6104"
+dependencies = [
+ "bytemuck",
+ "byteorder-lite",
+ "image-webp",
+ "moxcms",
+ "num-traits",
+ "png",
+ "zune-core",
+ "zune-jpeg",
+]
+
+[[package]]
+name = "image-webp"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "525e9ff3e1a4be2fbea1fdf0e98686a6d98b4d8f937e1bf7402245af1909e8c3"
+dependencies = [
+ "byteorder-lite",
+ "quick-error",
+]
+
 [[package]]
 name = "indexmap"
 version = "1.9.3"
@@ -1239,6 +1290,16 @@ version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"

+[[package]]
+name = "jobserver"
+version = "0.1.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9afb3de4395d6b3e67a780b6de64b51c978ecf11cb9a462c66be7d4ca9039d33"
+dependencies = [
+ "getrandom 0.3.4",
+ "libc",
+]
+
 [[package]]
 name = "js-sys"
 version = "0.3.95"
@@ -1304,6 +1365,16 @@ version = "0.2.185"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "52ff2c0fe9bc6cb6b14a0592c2ff4fa9ceb83eea9db979b0487cd054946a2b8f"

+[[package]]
+name = "libwebp-sys"
+version = "0.9.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "54cd30df7c7165ce74a456e4ca9732c603e8dc5e60784558c1c6dc047f876733"
+dependencies = [
+ "cc",
+ "glob",
+]
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
@@ -1512,6 +1583,16 @@ dependencies = [
 "spacetimedb",
 ]

+[[package]]
+name = "moxcms"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bb85c154ba489f01b25c0d36ae69a87e4a1c73a72631fc6c0eb6dde34a73e44b"
+dependencies = [
+ "num-traits",
+ "pxfm",
+]
+
 [[package]]
 name = "native-tls"
 version = "0.2.14"
@@ -1748,6 +1829,19 @@ dependencies = [
 "tokio",
 ]

+[[package]]
+name = "png"
+version = "0.18.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60769b8b31b2a9f263dae2776c37b1b28ae246943cf719eb6946a1db05128a61"
+dependencies = [
+ "bitflags",
+ "crc32fast",
+ "fdeflate",
+ "flate2",
+ "miniz_oxide",
+]
+
 [[package]]
 name = "potential_utf"
 version = "0.1.5"
@@ -1826,6 +1920,18 @@ dependencies = [
 "thiserror 1.0.69",
 ]

+[[package]]
+name = "pxfm"
+version = "0.1.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e0c5ccf5294c6ccd63a74f1565028353830a9c2f5eb0c682c355c471726a6e3f"
+
+[[package]]
+name = "quick-error"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a993555f31e5a609f617c12db6250dedcac1b0a85076912c436e6fc9b2c8e6a3"
+
 [[package]]
 name = "quinn"
 version = "0.11.9"
@@ -3508,6 +3614,16 @@ dependencies = [
 "wasm-bindgen",
 ]

+[[package]]
+name = "webp"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c071456adef4aca59bf6a583c46b90ff5eb0b4f758fc347cea81290288f37ce1"
+dependencies = [
+ "image",
+ "libwebp-sys",
+]
+
 [[package]]
 name = "webpki-roots"
 version = "1.0.7"
@@ -3884,3 +4000,18 @@ name = "zmij"
 version = "1.0.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
+
+[[package]]
+name = "zune-core"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb8a0807f7c01457d0379ba880ba6322660448ddebc890ce29bb64da71fb40f9"
+
+[[package]]
+name = "zune-jpeg"
+version = "0.5.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27bc9d5b815bc103f142aa054f561d9187d191692ec7c2d1e2b4737f8dbd7296"
+dependencies = [
+ "zune-core",
+]
--- a/server-rs/crates/api-server/Cargo.toml
+++ b/server-rs/crates/api-server/Cargo.toml
@@ -6,9 +6,12 @@ license.workspace = true

 [dependencies]
 axum = "0.8"
+base64 = "0.22"
 bytes = "1"
 dotenvy = "0.15"
+image = { version = "0.25", default-features = false, features = ["jpeg", "png", "webp"] }
 reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+webp = "0.3"
 module-ai = { path = "../module-ai" }
 module-assets = { path = "../module-assets" }
 module-auth = { path = "../module-auth" }
@@ -28,7 +31,7 @@ shared-contracts = { path = "../shared-contracts" }
 shared-kernel = { path = "../shared-kernel" }
 shared-logging = { path = "../shared-logging" }
 spacetime-client = { path = "../spacetime-client" }
-tokio = { version = "1", features = ["macros", "rt-multi-thread", "net"] }
+tokio = { version = "1", features = ["macros", "rt-multi-thread", "net", "time"] }
 tokio-stream = "0.1"
 time = { version = "0.3", features = ["formatting"] }
 tower-http = { version = "0.6", features = ["trace"] }
--- a/server-rs/crates/api-server/src/config.rs
+++ b/server-rs/crates/api-server/src/config.rs
@@ -54,6 +54,9 @@ pub struct AppConfig {
    pub llm_request_timeout_ms: u64,
    pub llm_max_retries: u32,
    pub llm_retry_backoff_ms: u64,
+    pub dashscope_base_url: String,
+    pub dashscope_api_key: Option<String>,
+    pub dashscope_image_request_timeout_ms: u64,
    pub slow_request_threshold_ms: u64,
 }

@@ -105,6 +108,9 @@ impl Default for AppConfig {
            llm_request_timeout_ms: DEFAULT_REQUEST_TIMEOUT_MS,
            llm_max_retries: DEFAULT_MAX_RETRIES,
            llm_retry_backoff_ms: DEFAULT_RETRY_BACKOFF_MS,
+            dashscope_base_url: "https://dashscope.aliyuncs.com/api/v1".to_string(),
+            dashscope_api_key: None,
+            dashscope_image_request_timeout_ms: 150_000,
            slow_request_threshold_ms: 1_000,
        }
    }
@@ -307,6 +313,18 @@ impl AppConfig {
            config.llm_retry_backoff_ms = llm_retry_backoff_ms;
        }

+        if let Some(dashscope_base_url) = read_first_non_empty_env(&["DASHSCOPE_BASE_URL"]) {
+            config.dashscope_base_url = dashscope_base_url;
+        }
+
+        config.dashscope_api_key = read_first_non_empty_env(&["DASHSCOPE_API_KEY"]);
+
+        if let Some(dashscope_image_request_timeout_ms) =
+            read_first_positive_u64_env(&["DASHSCOPE_IMAGE_REQUEST_TIMEOUT_MS"])
+        {
+            config.dashscope_image_request_timeout_ms = dashscope_image_request_timeout_ms;
+        }
+
        if let Some(slow_request_threshold_ms) =
            read_first_positive_u64_env(&["GENARRATIVE_SLOW_REQUEST_THRESHOLD_MS"])
        {
--- a/server-rs/crates/api-server/src/custom_world_ai.rs
+++ b/server-rs/crates/api-server/src/custom_world_ai.rs