1

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

@@ -24,6 +24,14 @@
 - 验证方式：检查 `/child-motion-demo` 舞台是否在未生成资产时仍有可用草地绘本兜底；补齐 VectorEngine 私密配置后运行 `npm run assets:child-motion-demo -- --live` 应能写出默认背景文件。
 - 关联文档：`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`、`docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md`。
 
+## 2026-05-10 方洞挑战从创作页入口和作品架隐藏
+
+- 背景：运营节奏要求创作页完全隐藏方洞挑战，不能只隐藏新建入口后仍从创作页作品架暴露已有方洞草稿或已发布作品。
+- 决策：SpacetimeDB `creation_entry_type_config` 中 `square-hole.visible=false` 作为创作页统一开关；创作 Tab 模板入口、旧选择弹层、创作 Hub 卡带和创作页作品架都基于该开关隐藏方洞挑战。既有方洞详情、作品号、广场和运行态链路暂不删除，api-server 路由熔断只按 `open=false` 禁用玩法 API。
+- 影响范围：SpacetimeDB 入口配置默认种子、`platformEntryCreationTypes`、`CustomWorldCreationHub`、`PlatformEntryFlowShellImpl` 以及创作入口相关文档和回归测试。
+- 验证方式：执行入口配置、创作 Hub 和平台入口交互定向测试，确认看不到“方洞挑战” Tab、按钮和作品架条目。
+- 关联文档：`docs/technical/NEW_WORK_ENTRY_CONFIG_2026-05-01.md`、`docs/design/PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md`。
+
 ## 2026-05-10 运行态输入设备抽象层全项目通用化
 
 - 背景：拼图运行态接入 mocap 后，鼠标/触控和 mocap 各自维护输入逻辑会导致合并大块、拖拽语义和取消会话行为不一致；后续其他玩法也需要复用体感、摇杆、键盘等设备输入。
@@ -110,7 +118,7 @@
 
 - 背景：平台计划新增 2048 游戏玩法模板，需要同时适配前端 stage、HTTP 路由、Rust 模块、SpacetimeDB 表和公开作品号；裸 `2048` 不适合作为模块或文件命名前缀。
 - 决策：面向用户展示名保持 `2048`，工程玩法 ID 固定为 `twenty-forty-eight`，Rust 模块与表前缀使用 `twenty_forty_eight`，公开作品号前缀使用 `TF-`；玩法按完整闭环设计，包含 Agent 创作、结果页、试玩、发布、公开运行、后端棋盘裁决、排行榜和作品架 / 广场接入。
-- 影响范围：后续 `src/config/newWorkEntryConfig.ts`、平台 `SelectionStage`、前端 `twenty-forty-eight-*` 组件与 service、`module-twenty-forty-eight`、`shared-contracts`、`spacetime-module` 表、`spacetime-client` facade、`api-server` 路由、作品号和 PRD 索引。
+- 影响范围：后续 SpacetimeDB 创作入口配置、平台 `SelectionStage`、前端 `twenty-forty-eight-*` 组件与 service、`module-twenty-forty-eight`、`shared-contracts`、`spacetime-module` 表、`spacetime-client` facade、`api-server` 路由、作品号和 PRD 索引。
 - 验证方式：后续落地时确认用户可见标题为 `2048`，代码、路由和表统一使用 `twenty-forty-eight` / `twenty_forty_eight`；移动、合并、生成新方块、目标达成、失败和榜单成绩由后端正式裁决，前端不伪造分数或目标达成。
 - 关联文档：`docs/prd/AI_NATIVE_2048_GAMEPLAY_TEMPLATE_PRD_2026-05-05.md`。
 
@@ -213,10 +221,26 @@
 ## 2026-05-10 视觉小说入口收敛为单句创作 + 画风选择
 
 - 背景：视觉小说入口页要对齐抓大鹅式的线性创作入口，只保留最小可用输入，避免再暴露文档 / 空白 / 对话式工作台。
-- 决策：入口页只展示一句话创作输入框和横向视觉画风卡片；画风通过 `seedText` 追加 `视觉画风` 和 `画风要求` 两行透传给既有创作链路；点击生成后先进入 `visual-novel-generating` 过程页，再自动进入 `visual-novel-result`。
-- 影响范围：`VisualNovelAgentWorkspace`、`PlatformEntryFlowShellImpl`、`platformEntryTypes`、视觉小说 PRD；不新增后端字段或数据库结构。
-- 验证方式：视觉小说工作台单测通过，`npm run check:encoding` 通过；`npm run typecheck` 仍受仓库里 `src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx` 的既有类型错误影响。
-- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`。
+- 决策：入口页只展示一句话创作输入框和横向视觉画风卡片；画风通过 `seedText` 追加 `视觉画风` 和 `画风要求` 两行透传给既有创作链路；点击生成后先进入 `visual-novel-generating` 过程页，再自动进入 `visual-novel-result`。画风卡片主视觉固定消费 `public/visual-novel-style-references/` 下由 VectorEngine `gpt-image-2-all` 生成的静态参考图，不在前端运行时现场调用生图接口。
+- 影响范围：`VisualNovelAgentWorkspace`、`visualNovelEntryGeneration`、`PlatformEntryFlowShellImpl`、视觉小说 PRD 和创作 Tab 设计文档；不新增后端字段或数据库结构。
+- 验证方式：执行 `npm run test -- VisualNovelAgentWorkspace`、视觉小说工作台相关 ESLint、`npx prettier --check` 和 `npm run check:encoding`；`npm run typecheck` 若失败需先区分是否来自无关 Match3D / RPG 既有改动。
+- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/design/PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md`。
+
+## 2026-05-10 用户标签只做后端白名单投影
+
+- 背景：运营邀请码需要给账号打标签，但标签默认不能暴露到前端通用用户资料；拼图排行榜仅需展示特定标签。
+- 决策：`user_account.user_tags` 保存账号标签，数据库默认 `None`，业务按空数组读取；后台预置邀请码使用后授予的标签不再使用独立列，统一存放并解析自 `profile_invite_code.metadata_json.userTags`，兼容读取 `user_tags`。通用登录态和个人资料不返回原始标签。首版只在拼图排行榜 `visibleTags` 中白名单投影 `北科`。
+- 影响范围：用户认证表、邀请码后台、邀请兑换事务、拼图排行榜响应和 UI。
+- 验证方式：表结构变更需同步 `migration.rs`、`SPACETIMEDB_TABLE_CATALOG.md` 和 SpacetimeDB bindings；后端运行 `cargo check -p api-server`，后台运行 `npm run admin-web:typecheck`。
+- 关联文档：`docs/technical/USER_TAG_INVITE_AND_PUZZLE_LEADERBOARD_2026-05-10.md`。
+
+## 2026-05-10 抓大鹅草稿元信息由 gpt-4o 生成
+
+- 背景：抓大鹅草稿生成需要基于入口题材设定生成作品名称，结果页作品信息要对齐拼图草稿，不再把封面和作品名称拆成两个模块。
+- 决策：`match3d_compile_draft` 使用 `gpt-4o` 生成 `gameName` 与 3 到 6 个标签；`summary` 默认保持空字符串；标签可由结果页 `作品信息` Tab 手动编辑或再次 AI 生成。草稿生成会产出 3 个物品图片并立即调用 Rodin 生成 GLB，图片和模型一起写入 `generated_item_assets_json`，运行态必须优先消费 `generatedItemAssets[].modelSrc` / `modelObjectKey`，默认积木只做兜底。
+- 影响范围：`api-server` Match3D 编译、Match3D works 标签接口、结果页 `作品信息` 与 `3D素材` Tab、运行态 `Match3DRuntimeShell` / `Match3DPhysicsBoard`、生成进度和 Match3D 技术文档。
+- 验证方式：执行 `npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`、`npm run test -- src/services/miniGameDraftGenerationProgress.test.ts`、`cargo test -p api-server match3d --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`，并用 `npm run api-server` 检查 `/healthz`。
+- 关联文档：`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`、`docs/technical/MATCH3D_RODIN_ASSET_TAB_2026-05-10.md`。
 
 ## 2026-05-07 移动端整页缩放由入口统一锁定
 

.hermes/shared-memory/pitfalls.md

@@ -147,6 +147,14 @@
 - 验证：重新发布日志应显示创建新的数据库，而不是更新旧数据库；若仍显示更新或继续 `401`，继续检查 root-dir、库名和 CLI 身份。
 - 关联：`docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`、`docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md`。
 
+## SpacetimeDB 模块 publish 报 `wasm-bindgen detected`
+
+- 现象：`spacetime publish` 已经完成 Rust 编译，但随后报 `wasm-bindgen detected`，提示依赖树里有面向 Web 平台的 wasm-bindgen。
+- 原因：SpacetimeDB 模块是数据库内 WASM，不允许拉入 Web/HTTP client 链路；常见误因是 `spacetime-module -> module-* -> shared-contracts -> platform-* -> reqwest -> wasm-bindgen` 这类反向依赖。
+- 处理：执行 `cargo tree -i wasm-bindgen --manifest-path server-rs/Cargo.toml -p spacetime-module --target wasm32-unknown-unknown` 找到链路；把平台实现类型从 `shared-contracts` 或 `module-*` 中移除，只保留公开 DTO，平台响应到 DTO 的转换放回 `api-server` 等 adapter 层。
+- 验证：上述 `cargo tree` 输出 `warning: nothing to print`；`cargo check -p shared-contracts`、`cargo check -p api-server` 通过；重新 `spacetime publish ... --module-path server-rs/crates/spacetime-module` 不再报 wasm-bindgen。
+- 关联：`docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md`、`server-rs/crates/shared-contracts/src/assets.rs`、`server-rs/crates/api-server/src/assets.rs`。
+
 ## Vite SPA fallback 吞掉 API 请求
 
 - 现象：本地请求 `/api/profile/*` 等接口时返回 HTML，被前端当 JSON 解析报错。
@@ -429,13 +437,21 @@
 - 验证：`cargo test -p api-server accepts_opaque_subscription_key_without_length_cap --manifest-path server-rs/Cargo.toml`。
 - 关联：`server-rs/crates/api-server/src/hyper3d_generation.rs`、`docs/technical/HYPER3D_RODIN_GEN2_MODEL_GENERATION_2026-05-08.md`。
 
-## 抓大鹅草稿生成不要阻塞在 Rodin 模型下载
+## 抓大鹅草稿生成恢复 Rodin 后要并行生成模型、同步长超时和 GLB 私有读取
 
-- 现象：抓大鹅草稿生成时 Hyper3D 状态已完成，但下载列表为空或没有可用模型文件，`/api/creation/match3d/sessions/{sessionId}/actions` 返回 `502 Bad Gateway`，前端提示 `Hyper3D 已完成但未返回可下载模型文件`。
-- 原因：草稿生成链路曾在切割图片后立即并行调用 Rodin 图生模型，并把模型下载成功作为草稿完成前置条件；上游完成态和可下载文件列表不是强一致，容易把本来可用的图片草稿卡死。
-- 处理：草稿阶段只生成物品名、素材图、切割独立图片并上传 OSS，返回 `status = image_ready`；Rodin 3D 模型生成留到结果页 `3D素材` Tab 手动触发。
-- 验证：草稿响应中的 `generatedItemAssets[].imageSrc` 有值、`modelSrc` 为空、状态为 `image_ready`；结果页显示 `图片已就绪` 和 `0 文件`，不会自动请求 Hyper3D 下载。
-- 关联：`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-result/Match3DResultView.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
+- 现象：抓大鹅草稿生成重新接回 Rodin 后，前端可能在模型轮询和 GLB 转存完成前超时；或结果页把 `/generated-match3d-assets/.../model.glb` 直接当浏览器 URL 加载导致私有 OSS/CORS 读取失败。
+- 原因：`match3d_compile_draft` 会完成作品元信息、素材图、切图上传、3 件 Rodin 图生模型、GLB 下载和 OSS 转存，耗时远长于普通 Agent action；如果 3 件 Rodin 模型逐个提交和轮询，等待时间会线性叠加；同时 generated 私有资产不能被 Three.js 直接 `fetch`。
+- 处理：切图和图片入库后，所有 Rodin 图生模型任务必须并行提交、并行轮询、并行下载转存；Match3D creation client 的 `executeAction` 必须给长超时，当前为 20 分钟；生成进度页要包含 `生成3D模型` 阶段；结果页模型预览、场内运行态和备选栏预览都必须通过 `/api/assets/read-bytes` 读取 GLB 字节后交给 Three.js GLTFLoader，不要直接请求裸 generated 路径。
+- 验证：`npm run test -- src\services\miniGameDraftGenerationProgress.test.ts src\components\match3d-result\Match3DResultView.test.tsx src\components\match3d-runtime\Match3DRuntimeShell.test.tsx`、`npm run typecheck`；真实联调需配置 `VECTOR_ENGINE_API_KEY`、`HYPER3D_API_KEY` 和 OSS 变量。
+- 关联：`src/services/match3d-creation/match3dCreationClient.ts`、`src/services/creation-agent/creationAgentClientFactory.ts`、`src/components/match3d-result/Match3DModelPreview.tsx`、`src/components/match3d-runtime/Match3DPhysicsBoard.tsx`、`server-rs/crates/api-server/src/match3d.rs`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
+
+## Rodin 完成态后下载列表可能延迟或字段漂移
+
+- 现象：抓大鹅草稿生成时 Rodin 状态已完成，但 `/api/creation/match3d/sessions/{sessionId}/actions` 返回 502，提示 `{物品名} 3D 模型已完成但未返回可下载模型文件：{taskUuid}`。
+- 原因：Hyper3D Rodin 官方示例要求看 `jobs` 列表，只有所有 job 都 `Done` 才能进入下载；旧聚合若只看 root status 或第一个 job，可能在 preview job 完成但模型 job 仍在生成时提前下载。另外任务完成和下载列表文件发布不是强同步的；上游下载结果还可能使用 `fileUrl`、`signedUrl`、`presignedUrl`、`fileName` 等字段别名，旧解析器只识别 `url/downloadUrl/name/file_name/filename` 时会得到空列表。
+- 处理：`query_task_status` 聚合状态必须以 `jobs` 为准：任一 failed 即 failed，全部 done 才 done；`match3d_compile_draft` 在状态完成后对 `query_downloads` 继续轮询；下载解析兼容常见 URL 和文件名字段别名；模型选择优先 `.glb`，可兜底到非图片下载文件，但只有 preview/png/jpg/webp 这类预览图时必须继续失败，不能伪装成 GLB。
+- 验证：`cargo test -p api-server match3d_model_download --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server extracts_download_files --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server match3d --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server hyper3d --manifest-path server-rs/Cargo.toml`。
+- 关联：`server-rs/crates/api-server/src/match3d.rs`、`server-rs/crates/api-server/src/hyper3d_generation.rs`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
 
 ## 抓大鹅切图路径不能只用中文物品名
 
@@ -452,3 +468,19 @@
 - 处理：compile 成功时把独立物品图片列表序列化写入 `match3d_work_profile.generated_item_assets_json`；`update_match3d_work` / `publish_match3d_work` 保留该字段；API work summary/detail 映射反序列化为 `generatedItemAssets`。前端保持“本次 draft 优先，重进 profile 兜底”的读取顺序。
 - 验证：`cargo test -p spacetime-client match3d --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server match3d --manifest-path server-rs/Cargo.toml`、`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`。
 - 关联：`server-rs/crates/spacetime-module/src/match3d/*`、`server-rs/crates/spacetime-client/src/mapper.rs`、`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-result/Match3DResultView.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
+
+## 抓大鹅标签清洗不要把 `3D素材` 当编号剥掉
+
+- 现象：AI 或兜底生成的 `3D素材` 标签在后端规范化后变成 `D素材`。
+- 原因：标签清洗在去掉编号列表前缀后，又无条件剥离开头数字和标点，把合法标签中的 `3D` 当成列表编号处理。
+- 处理：只移除明确的编号列表前缀，例如 `1. 标签`、`1、标签`、`1) 标签`；不要对普通标签开头数字做二次剥离。
+- 验证：`cargo test -p api-server match3d_tag_normalization --manifest-path server-rs/Cargo.toml`，并保留 `normalize_match3d_tag("3D素材") == "3D素材"` 的单测。
+- 关联：`server-rs/crates/api-server/src/match3d.rs`。
+
+## 用户标签不要直接外显，SpacetimeDB Vec 字段不要写 default 宏
+
+- 现象：给 `user_account.user_tags` 或邀请码独立标签列写 `#[default(Vec::<String>::new())]` 时，SpacetimeDB WASM 构建报 `destructor of Vec<String> cannot be evaluated at compile-time`。
+- 原因：SpacetimeDB 的 table default 宏会走编译期常量求值，不能直接使用有析构逻辑的堆分配类型默认值。
+- 处理：`user_account.user_tags` 使用 `Option<Vec<String>>` + `#[default(None::<Vec<String>>)]` 表达数据库默认空，业务层统一把 `None` 归一化为空数组；邀请码授予标签复用 `metadata_json.userTags` 存储和解析，不再新增独立 Vec 列。用户标签原始值不得进入登录态、个人资料等通用响应，只能在明确业务白名单里投影，例如拼图排行榜 `visibleTags` 首版仅允许 `北科`。
+- 验证：`npm run spacetime:generate -- --rust-only` 能通过；`user_account` 旧迁移 JSON 缺字段时能导入，`profile_invite_code` 缺 `metadata_json` 时按 `{}` 兼容。
+- 关联：`docs/technical/USER_TAG_INVITE_AND_PUZZLE_LEADERBOARD_2026-05-10.md`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`。