feat: refine wooden fish runtime generation

.hermes/shared-memory/decision-log.md

@@ -16,6 +16,14 @@
 
 ---
 
+## 2026-05-22 敲木鱼图片创作采用双图 image2 链路
+
+- 背景：敲木鱼自定义题材只生成中央敲击物时，运行态缺少与新主题匹配的竖屏背景；若直接让背景 prompt 自由发挥，又容易把敲击物或木槌画进背景里。
+- 决策：敲木鱼 `compile-draft` / `regenerate-hit-object` 图片链路固定为两步 image2 edits。第一步调用 VectorEngine `/v1/images/edits` + `gpt-image-2`，以默认木鱼图作为结构和画风参考，用户上传参考图只作为同次请求的新主题参考，结合用户题材关键词或参考图主题生成 `1:1` 透明底新敲击物并写回 `hitObjectAsset`；第二步以新敲击物图作为主题和画风参考，结合用户原始题材生成 `9:16` 背景环境图并写回 `backgroundAsset`。两步 prompt 使用 PRD 中固定隐藏关键词，不追加额外 negative prompt；背景图不得包含敲击物本体或木槌互动物品。
+- 影响范围：`api-server` 木鱼图片生成编排、`wooden_fish_work_profile.background_asset_json`、shared contracts、前端结果页 / 运行态背景展示、敲木鱼 PRD 和平台链路文档。
+- 验证方式：执行 `cargo test -p api-server wooden_fish --manifest-path server-rs/Cargo.toml`、`cargo test -p spacetime-client wooden_fish --manifest-path server-rs/Cargo.toml`、`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run typecheck`。
+- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 2026-05-21 外部 API 失败必须 OTLP 上报并落库
 
 - 背景：图片生成等外部供应商调用失败时，仅返回 502/504 或普通日志无法支持后续按 provider、阶段和重试属性聚合排障。

.hermes/shared-memory/pitfalls.md

@@ -478,6 +478,14 @@
 - 验证：`spacetime server list` 默认目标为 local；重新登录后发布不再返回 `401` / `403`；`npm run dev` 可以完成 SpacetimeDB publish 并继续启动 `api-server`。
 - 关联：`docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md`、`scripts/dev.mjs`。
 
+## 本地 api-server 启动订阅 401 先查 Web identity token 注入
+
+- 现象：`npm run dev` 启动到 api-server 恢复认证快照时，日志出现 `Failed to initiate WebSocket connection ... /v1/database/<db>/subscribe?compression=Brotli: HTTP error: 401 Unauthorized`。
+- 原因：SpacetimeDB SDK 订阅需要 Web API identity token；本地 `.env.local` 常把 `GENARRATIVE_SPACETIME_TOKEN` 留空，只靠 CLI 登录态 publish 成功并不能让 api-server 的 WebSocket subscribe 获得权限。
+- 处理：`scripts/dev.mjs` 在 SpacetimeDB 就绪后调用 `/v1/identity` 创建当前进程专用 Web API identity token，并只注入本次 `api-server` 环境；不要把临时 token 写进 `.env.local` 或日志。若仍报 401，先确认是否使用了项目脚本启动、日志是否出现 `已创建本地 Web identity`，以及 `GENARRATIVE_SPACETIME_SERVER_URL` / 数据库名是否指向本次启动的实例。
+- 验证：`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 联调可按阶段跳过宿主或发布
 
 - 现象：本地 `npm run dev` 因 `3101` 已占用、重复发布 SpacetimeDB wasm 编译太慢，或只想检查 `spacetime-module` 语法而被完整联调链路拖慢。