feat: 完善敲木鱼玩法模板链路
This commit is contained in:
@@ -39,6 +39,38 @@
|
||||
- 验证：`cargo test -p api-server puzzle_ui_spritesheet_postprocess_turns_green_screen_transparent --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server puzzle_level_scene_spritesheet_and_background_requests_use_references --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server match3d_derived_asset_prompts_match_three_sheet_pipeline --manifest-path server-rs\Cargo.toml`。
|
||||
- 关联：`server-rs/crates/api-server/src/puzzle/generation.rs`、`server-rs/crates/api-server/src/match3d/works.rs`、`server-rs/crates/api-server/src/generated_asset_sheets.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 敲木鱼 hit object 不要只相信透明底 prompt
|
||||
|
||||
- 现象：苹果等主题试玩时，中央敲击物图带明显黑底；背景图中央还可能出现苹果主体，或背景环境图偶发变成纯绿色底，和“中央只叠加 hitObjectAsset”的运行态设定冲突。
|
||||
- 原因：gpt-image-2 对“透明底”和“背景只做外围氛围”的遵循不稳定。若 hit object 直接入库，黑底会被当成真实像素展示；若背景 prompt 只有软描述，模型会把主题主体画进中央。第一步为了去背刻意要求绿幕图时，如果第二步参考图或 prompt 没有切断绿幕语义，背景图也可能继承纯绿色画布。
|
||||
- 处理：敲木鱼 hit object prompt 固定要求先输出 `1:1` 绿色背景主体图（纯绿色绿幕、单一 `#00FF00` 背景），再由 `api-server` 只对绿幕背景做去绿透明化；不要回到黑底 / 白底 / 透明底 prompt 后再做泛抠图。背景生成必须使用第一步抠图完成后的透明图作为参考图，并在 prompt 中显式禁止继承绿色底色、绿幕底色或纯绿色画布；背景 prompt 还要固定要求中央 40% 主体预留区干净，禁止主题主体、局部特写、轮廓影子、重复元素和主题碎片，只允许外围氛围。
|
||||
- 验证：`cargo test -p api-server wooden_fish --manifest-path server-rs\Cargo.toml`，并用花朵 / 苹果 / 玉米主题跑试玩图确认绿幕被去除、主体未被抠除、背景中央不出现主题主体，背景环境图不再出现纯绿色底。
|
||||
- 关联：`server-rs/crates/api-server/src/wooden_fish.rs`、`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 敲木鱼返回按钮不要让模型自由发挥外圈花纹
|
||||
|
||||
- 现象：返回按钮试玩图有时会被画成徽章、花盘、浮雕圆牌，甚至出现复杂外圈和装饰花纹，左箭头反而不够突出。
|
||||
- 原因：prompt 只说“主题化返回按钮”时，image2 会把参考图里的装饰语言一起学进去；如果没有把形状收束到“标准圆形 + 单个居中左箭头”，模型会优先补造型而不是补图标。
|
||||
- 处理：返回按钮生成 prompt 必须只允许参考图约束圆形底色与箭头配色，明确禁止复杂造型、花纹、浮雕边、异形外框和装饰图案，按钮本体固定为标准圆形。
|
||||
- 验证：`cargo test -p api-server wooden_fish --manifest-path server-rs\Cargo.toml`，并重新试玩确认返回按钮只剩圆形底色和中央左箭头。
|
||||
- 关联：`server-rs/crates/api-server/src/wooden_fish.rs`、`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`.
|
||||
|
||||
## 敲木鱼创作生成不要沿用 15 秒会话超时
|
||||
|
||||
- 现象：敲木鱼工作台点击“生成”后，前端直接提示 `请求超时：15000ms`，但后端和 VectorEngine 未必已经失败。
|
||||
- 原因：`createCreationAgentClient` 的 `createSessionTimeoutMs` 默认是 15 秒；敲木鱼创作链路会继续进入生成页并执行多次 image2 edits、去绿背景处理和 OSS 写入，单次请求窗口如果继承共享默认值，会早于业务生成完成被前端中断。
|
||||
- 处理：敲木鱼 client 必须单独配置长等待窗口，同时覆盖 `createSessionTimeoutMs` 与 `executeActionTimeoutMs`；不要修改共享默认值影响其它轻量创作 Agent。
|
||||
- 验证：`npm run test -- src/services/wooden-fish/woodenFishClient.test.ts`，并在本地触发一次木鱼创作确认不再出现 15 秒前端超时。
|
||||
- 关联：`src/services/wooden-fish/woodenFishClient.ts`、`src/services/creation-agent/creationAgentClientFactory.ts`、`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`。
|
||||
|
||||
## 敲木鱼点击生成出现 SpacetimeDB procedure 超时先查版本错配
|
||||
|
||||
- 现象：敲木鱼创作时点击“生成”，前端提示 `SpacetimeDB procedure 调用超时`，但服务端日志更早出现 `Failed to BSATN deserialize procedure return value` 或类似反序列化错误。
|
||||
- 原因：本机 `spacetime` CLI / standalone 版本与 `server-rs/Cargo.toml` 锁定的 `spacetimedb` 版本不一致时，procedure 返回值会在宿主侧反序列化失败，api-server 继续等待就表现成调用超时。若旧 standalone 进程还在复用，也会把这个错配继续带进新一轮创作。
|
||||
- 处理：先用 `spacetime --version` 确认 `spacetimedb tool version`，再和 `server-rs/Cargo.toml` 的 `spacetimedb = "..."` 对齐；必要时执行 `spacetime version install <version> && spacetime version use <version>`，然后重启 `npm run dev:spacetime`。当前 dev 脚本会在启动和复用本地 SpacetimeDB 前写入并校验 `dev-spacetime-tool-version`，避免继续复用旧宿主。
|
||||
- 验证：`spacetime --version` 输出与 `server-rs/Cargo.toml` 一致，`http://127.0.0.1:3101/v1/ping` 正常，`npm run test -- scripts/dev.test.ts` 通过，敲木鱼创作点击生成不再卡在 procedure timeout。
|
||||
- 关联：`scripts/dev.mjs`、`scripts/dev.test.ts`、`server-rs/Cargo.toml`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
|
||||
|
||||
## 拼图 UI spritesheet 运行态不要二次包圆底或拉伸比例
|
||||
|
||||
- 现象：拼图运行态左上返回和右上设置按钮外面出现白色圆圈；底部“提示 / 原图 / 冻结”三枚素材被压扁、拉宽或拉成正圆，和图集原始按钮比例不一致。
|
||||
@@ -1331,6 +1363,14 @@
|
||||
- 验证：`npm run test -- scripts/dev.test.ts`；重新运行 `npm run dev` 后 api-server 启动日志不再出现上述 subscribe 401，`/healthz` 返回 200。
|
||||
- 关联：`scripts/dev.mjs`、`scripts/dev.test.ts`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
|
||||
|
||||
## 创作作品架或公开列表异常先查本地 SpacetimeDB schema 漂移
|
||||
|
||||
- 现象：本地 `http://127.0.0.1:3000/` 启动后，`api-server` 日志反复出现 `Host returned error when processing subscription query: no such table: puzzle_gallery_card_view`；或创作中心草稿 / 已发布作品整块消失，`GET /api/creation-entry/config` 返回 `502` 且 details 为 `No such procedure`。
|
||||
- 原因：本地 `.env.local` 或 `spacetime.local.json` 指向的 SpacetimeDB 库没有发布当前 `spacetime-module`，或当前 CLI 身份无权发布该库；例如旧 `xushi-p4wfr` 库缺 `get_creation_entry_config` / `puzzle_gallery_card_view`，但当前代码的 `spacetime-client` 启动时会长期订阅这些公开 read model。
|
||||
- 处理：先用 `spacetime sql <database> "SELECT * FROM puzzle_gallery_card_view LIMIT 1" --server http://127.0.0.1:3101` 确认目标库是否有当前 view；若只是本地验证，可用 gitignored 的 `spacetime.local.json` 指向可发布且已包含当前 schema 的库，例如 `{"database":"genarrative-dev-codex"}`。该 JSON 必须无 UTF-8 BOM，否则 `scripts/dev.mjs` 会忽略它。修改后用 `npm run dev:api-server -- --database <database> --spacetime-port 3101 --api-port 8082 --no-interactive` 重启。
|
||||
- 验证：`curl.exe -i http://127.0.0.1:8082/healthz` 返回 `200`；`curl.exe -i http://127.0.0.1:8082/api/runtime/puzzle/gallery` 返回 `200`；浏览器打开 `http://127.0.0.1:3000/` 无 `puzzle_gallery_card_view` 控制台或后端日志错误。
|
||||
- 关联：`scripts/dev.mjs`、`server-rs/crates/spacetime-client/src/lib.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
|
||||
|
||||
## 创作作品架消失先查入口配置 procedure 与本地库权限
|
||||
|
||||
- 现象：寓教于乐或创作中心下草稿 / 已发布作品突然整块消失，`GET /api/creation-entry/config` 返回 `502`，details 中为 `No such procedure`。
|
||||
|
||||
Reference in New Issue
Block a user