Merge branch 'master' of https://git.genarrative.world/GenarrativeAI/Genarrative

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

@@ -16,6 +16,22 @@
 
 ---
 
+## 2026-05-25 平台首页推荐按桌面与移动断点分流
+
+- 背景：平台首页的推荐页在桌面与移动端之间原先共用同一套推荐运行态逻辑，容易让桌面和移动两套内容同时启动，也让首页的推荐卡与桌面发现壳互相抢状态。
+- 决策：`RpgEntryHomeView` 只接受同一个 `isDesktopLayout` 断点判断；桌面端首页渲染桌面发现壳（`今日游戏`、`推荐`、`作品分类` 等），不挂移动推荐嵌入运行态；移动端 `home` 才渲染推荐卡与嵌入运行态。平台壳和首页视图都必须共用 `usePlatformDesktopLayout()`，不能在不同文件里各自判断断点。推荐嵌入运行态不是登录门禁：未登录可直达匿名运行态；已登录或已有 access token 时继续使用账号 Bearer，但必须用 local auth impact 防止推荐卡 401 清空全局登录态。
+- 影响范围：`src/components/platform-entry/platformEntryResponsive.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、首页推荐相关测试与 `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+- 验证方式：桌面宽度下首页应只看到桌面发现壳，窄屏下首页应只看到移动推荐流；`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "recommend"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "home recommendation"`、`npm run typecheck`、`npm run check:encoding` 通过。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-05-25 新增玩法接入必须使用统一 SOP skill
+
+- 背景：敲木鱼、跳一跳、汪汪声浪等玩法接入过程中，作品架曾经没有被作为强制闭环验收项，导致玩法可以先完成创作、发布、运行态或广场，但用户在草稿 / 已发布作品架中看不到自己的作品。
+- 决策：凡是新增、补齐、迁移或重构玩法入口、玩法类型、创作工作台、生成页、结果页、发布、运行态、作品架、广场或公开 read model 的任务，开始前必须显式读取并按 `.codex/skills/genarrative-play-type-integration/SKILL.md` 执行。需要发布或试玩的玩法，作品架不是可选项，必须补齐私有 `/works` 列表、作品摘要、pending shelf 兜底、统一作品架 adapter、打开详情 / 草稿恢复、已发布分享入口和草稿 / 已发布可见性测试。
+- 影响范围：`AGENTS.md`、`.codex/skills/genarrative-play-type-integration/SKILL.md`、玩法 PRD、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、新增玩法前后端接入流程。
+- 验证方式：玩法接入 PRD 和实现验收必须列出作品架链路；若一个玩法具备发布或试玩能力，但缺少 `/api/creation/<play>/works`、前端 client `listWorks`、`CustomWorldCreationHub` props、`creationWorkShelf` adapter 或草稿 / 已发布作品架测试，则接入不算完成。
+- 关联文档：`AGENTS.md`、`.codex/skills/genarrative-play-type-integration/SKILL.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 2026-05-24 创作 Tab banner 轮播只展示主题赛
 
 - 背景：创作 Tab banner 曾经把后端入口配置里的默认活动横幅和两个主题赛一起轮播，导致首屏出现 58000 奖池活动卡，和当前只强调拼图 / 抓大鹅主题赛的产品口径不一致。
@@ -121,6 +137,14 @@
 - 验证方式：执行 `cargo test -p api-server external_api_audit --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo test -p api-server openai_image_generation --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
+## 2026-05-25 VectorEngine 图片 provider 收到 platform-image
+
+- 背景：`api-server` 里原本同时混着 VectorEngine 创建 / 编辑协议、响应解析、远端图片下载、失败日志和审计落库逻辑，Puzzle / Match3D 还各自藏着一份近似实现，导致“provider 协议”和“业务编排”边界不清。
+- 决策：把 VectorEngine `gpt-image-2` 图片 provider 协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志统一收口到 `server-rs/crates/platform-image`。`api-server` 只保留配置校验、玩法 prompt 编排、OSS / asset object / binding 持久化、计费和外部 API 失败审计桥接；旧 `openai_image_generation.rs` 只作为兼容转接层，不再承担 provider 实现。
+- 影响范围：`server-rs/crates/platform-image`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`server-rs/crates/api-server/src/puzzle/vector_engine.rs`、`server-rs/crates/api-server/src/external_api_audit.rs`、后端架构与运维文档。
+- 验证方式：`cargo test -p platform-image --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server openai_image_generation --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo test -p api-server puzzle --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 2026-05-21 拼图参考图主链改为 OSS assetObjectId 与只读签名 URL
 
 - 背景：release 上拼图图生图生成草稿时，旧链路把上传图转成 Data URL/base64 放进创作 action JSON body，容易先触发 Nginx `413 Request Entity Too Large`，也让外部模型调用前的 HTTP body 过大。

.hermes/shared-memory/development-workflow.md

@@ -93,6 +93,8 @@ npm run dev:admin-web
 
 `npm run dev:api-server` 会保留终端实时输出，并把同一份输出持久化到 `logs/api-server/api-server-<timestamp>.log`。完整联调入口 `npm run dev` 启动的 Rust `api-server` 使用同一套日志规则。如需改写路径，可设置 `GENARRATIVE_API_SERVER_LOG_FILE`；如只改目录，可设置 `GENARRATIVE_API_SERVER_LOG_DIR`。
 
+开发态 `npm run dev` / `npm run dev:api-server` 默认打开 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=true`，密码入口可以直接注册未知手机号账号；生产默认仍关闭该开关。
+
 查看本地 Rust/SpacetimeDB 日志：
 
 ```bash

.hermes/shared-memory/pitfalls.md

@@ -23,6 +23,29 @@
 - 验证：点拼图 / 抓大鹅 / 汪汪声浪卡片后，应看到各自既有工作台内容，例如测试中的 `拼图工作区：missing-session`、`抓大鹅工作区：missing-session` 或 `汪汪声浪配置表单`，并且不再出现“X 创作入口”空白页。
 - 关联：`src/components/platform-entry/platformEntryTypes.ts`、`src/routing/appPageRoutes.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`。
 
+## 首页推荐分流参数不能条件性调用 hook
+
+- 现象：桌面首页或移动首页在 HMR、断点切换或重新渲染后直接报 React hook 顺序错误，页面停在“正在加载内容”。
+- 原因：`RpgEntryHomeView` 曾经写成 `const isDesktopLayout = isDesktopLayoutProp ?? usePlatformDesktopLayout();`，当 `isDesktopLayoutProp` 存在时会跳过 hook 调用，导致 hook 顺序在不同渲染之间变化。
+- 处理：先无条件调用 `usePlatformDesktopLayout()`，再用 `isDesktopLayoutProp ?? detectedDesktopLayout` 合并；不要把 hook 调用藏在条件表达式里。
+- 验证：桌面与窄屏各刷新一次首页，控制台不再出现 hook 顺序错误；`npm run typecheck` 和首页推荐相关测试通过。
+- 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/platform-entry/platformEntryResponsive.ts`。
+
+## 泥点不足提示不要把用户退回创作入口
+
+- 现象：拼图 / 抓大鹅 / 汪汪声浪等创作表单点击生成时，如果泥点不足，页面直接回到创作 Tab 玩法模板列表，刚填的表单内容随工作台卸载全部丢失。
+- 原因：`PlatformEntryFlowShellImpl.tsx` 的 `ensureEnoughDraftGenerationPointsFromServer(...)` 曾在余额不足或余额读取失败时调用 `enterCreateTab()` 并 `setSelectionStage('platform')`，把前置校验失败当作离开工作台处理。
+- 处理：泥点前置校验失败只更新独立 `UnifiedModal` 提示，不切换 stage，不清表单；余额读取失败也走同一弹窗口径。需要提示玩法内错误时可以保留局部错误位，但不得因此退出工作台。
+- 验证：`npm test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "puzzle form checks mud points before creating a draft|match3d form checks mud points before creating a draft|bark battle form checks mud points before creating image assets"` 应断言弹窗出现、对应工作台仍在、玩法模板分类不再出现。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 玩法入口分类字段缺失要前端兜底
+
+- 现象：平台创作入口初始化时，`platformEntryCreationTypes.ts` 直接对 `creationTypes[].categoryId` / `categoryLabel` 调 `trim()`，一旦后端旧数据、局部 mock 或异常返回里缺字段，整个创作页会在 `derivePlatformCreationTypes(...)` 里直接炸掉。
+- 处理：`normalizeCategoryId(...)` 和 `normalizeCategoryLabel(...)` 必须接收可空值，并分别回退到 `recent` / `最近创作`。前端这里是展示派生层，不能要求所有历史配置都先补齐字段。
+- 验证：`npm test -- src/components/platform-entry/platformEntryCreationTypes.test.ts`，再打开本地创作页确认能正常进入创作 Tab。
+- 关联：`src/components/platform-entry/platformEntryCreationTypes.ts`、`src/components/platform-entry/platformEntryCreationTypes.test.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 草稿页未读点不要继续用红色 literal
 
 - 现象：草稿页底部 Tab 和作品架的未读点视觉上仍像红点，或 glow 仍带红色阴影，和平台暖棕体系不一致。
@@ -234,6 +257,14 @@
 - 验证：`SELECT event_id, scope_id AS provider, metadata_json, occurred_at FROM tracking_event WHERE event_key = 'external_api_call_failure' ORDER BY occurred_at DESC LIMIT 50;`；如果查不到同时看 tracking outbox 目录权限和 sealed 文件是否堆积。
 - 关联：`server-rs/crates/api-server/src/external_api_audit.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
+## VectorEngine 图片协议先看 platform-image，不要先翻 puzzle.rs
+
+- 现象：排查拼图或其它玩法的生图失败时，如果直接在 `api-server` 的大文件里找 `images/generations`、`images/edits`、base64 解码或下载逻辑，会看到很多历史 helper 和测试桥，看起来像每个玩法都自带一份 provider 实现。
+- 原因：旧实现把 VectorEngine 图片 provider 协议、响应解析、下载和日志混在 `api-server` 里，后来虽然迁出到 `platform-image`，但兼容层和测试 helper 仍会让人误判真相源位置。
+- 处理：先看 `server-rs/crates/platform-image/src/lib.rs` 的 provider 协议和结构化日志，再看 `server-rs/crates/api-server/src/openai_image_generation.rs` 的兼容桥和 `external_api_audit.rs` 的落库映射；`puzzle/vector_engine.rs` 只保留玩法编排，不再作为 provider 协议真相源。
+- 验证：`cargo test -p platform-image --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server openai_image_generation --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo test -p api-server puzzle --manifest-path server-rs/Cargo.toml -- --nocapture` 通过时，排障先按 `platform-image` 的日志字段查 provider / endpoint / failure_stage。
+- 关联：`server-rs/crates/platform-image/src/lib.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`server-rs/crates/api-server/src/external_api_audit.rs`、`server-rs/crates/api-server/src/puzzle/vector_engine.rs`。
+
 ## release 创作接口 413 先查是否还在提交 Data URL
 
 - 现象：release 上 `POST /api/runtime/puzzle/agent/sessions/{session_id}/actions` 携带参考图 Data URL 时返回 `413 Request Entity Too Large`，access log 显示 `request_time=0.000`、`upstream_status=-`。
@@ -825,6 +856,7 @@
 - 现象：前端登录成功后进入推荐页，推荐页自动加载出一个作品，随后瞬间回到未登录；停留在其他页面或推荐页没加载出作品时不复现。
 - 原因：推荐页 embedded 运行态会自动发起受保护写请求。若这些卡片级后台请求遇到 `401` 或 refresh 失败，默认请求层曾清空 access token 并广播全局 auth 事件，导致 `AuthGate` 重新 hydrate 成未登录态。更隐蔽的是，`refreshAccessToken()` 自身曾在 refresh 失败时静默清 token，即便调用方关闭了 `clearAuthOnUnauthorized`，也可能让后续 hydrate 变成未登录。
 - 处理：请求层统一使用 `authImpact: 'global' | 'local'` 区分账号权威请求与局部后台请求；推荐页自动运行态、图片换签、公开拼图运行态和平台 bootstrap 私有投影刷新统一使用 `BACKGROUND_AUTH_REQUEST_OPTIONS` / `RUNTIME_BACKGROUND_AUTH_OPTIONS`，并等 `canReadProtectedData` 为 true 后再启动；用户主动点击的账号动作仍保留默认全局鉴权失败处理。
+- 追加处理：推荐页嵌入运行态要按真实身份分流，已登录或已有 access token 时继续走账号 Bearer + local auth impact，不能误带 runtime guest token；只有匿名访客才申请并透传 runtime guest token。
 - 追加处理：generated 私有图片换签 `/api/assets/read-url` 也属于展示层后台请求；推荐页拼图运行态挂载后会立即解析封面图，若换签 401 触发全局鉴权事件，也会表现成“进入拼图作品后瞬间未登录”。资源换签失败只应让当前图片为空，不应清 token、广播 auth 事件或主动 refresh。
 - 追加处理：从推荐页点进公开拼图作品并启动完整运行态后，`startPuzzleRun`、通关自动 `submitPuzzleLeaderboard`、下一关 `advancePuzzleNextLevel` 和重开同样属于当前玩法局部同步；这些请求失败时只应留在拼图错误态，不应清 token 或广播 auth 事件。
 - 追加处理：通关后 `refreshSaveArchives()`、首屏 bootstrap 的个人看板/作品架/浏览历史读写也只是平台投影刷新，失败应显示局部错误，不能充当全局登录态判定。
@@ -841,9 +873,9 @@
 
 ## 推荐页未登录入口误打开公开详情
 
-- 现象：新用户默认在发现页，但点击推荐页或推荐封面后，如果复用公开作品详情入口，可能绕过推荐页“登录后游玩”的产品门禁。
+- 现象：新用户默认在发现页，但点击推荐页或推荐封面后，如果复用公开作品详情入口，可能绕过推荐页沉浸运行态，打开普通公开详情页。
 - 原因：`RpgEntryHomeView` 曾只有 `onOpenGalleryDetail` 一个回调，同时服务发现页公开详情和推荐页作品入口；一旦为发现页保留公开浏览能力，推荐页也会跟着打开详情。
-- 处理：公开详情与推荐页入口分离为 `onOpenGalleryDetail` 和 `onOpenRecommendGalleryDetail`。发现页、搜索和排行榜保留公开详情；推荐 Tab、推荐封面、推荐运行态错误重试和桌面推荐模块统一走登录门禁。未登录推荐页只显示封面，点击封面只弹登录窗，不携带登录后自动打开详情的回调。
+- 处理：公开详情与推荐页入口分离为 `onOpenGalleryDetail` 和 `onOpenRecommendGalleryDetail`。发现页、搜索和排行榜保留公开详情；推荐 Tab、推荐封面、推荐运行态错误重试和桌面推荐模块走推荐运行态入口，不再主动弹登录窗。登录门禁只保留给创作、个人作品、删除、发布、Remix 等账号或所有权动作。
 - 验证：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "logged out recommend"`。
 - 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/technical/AUTH_RESTORE_AND_RECOMMEND_LOADING_FIX_2026-05-09.md`。
 
@@ -982,7 +1014,7 @@
 
 - 现象：生产发布、数据库导入导出、服务器配置、构建或 `Genarrative-Full-Build-And-Deploy` 流水线执行 `GitSCM checkout` 时，如果 Jenkins 生成的 fetch 是 `+refs/heads/*:refs/remotes/origin/*`，公网 Git 链路可能在收包阶段以 `git-remote-https died of signal 15`、`curl 56 GnuTLS recv error (-9)`、`early EOF`、`invalid index-pack output` 失败；发布类流水线还可能先遇到 `http://127.0.0.1:3000/GenarrativeAI/Genarrative.git` 不可达。
 - 原因：`127.0.0.1` 只代表当前执行阶段的 agent 自身；当 release agent 与 Git 服务不在同一台机器，或本机 Git/Web 服务临时不可用时，固定写死 localhost 会阻断 Jenkinsfile 内部源码/脚本 checkout。即使只使用域名 Git，如果 `GitSCM` 没有显式 refspec 并开启 `CloneOption honorRefspec=true`，Jenkins Git 插件也会拉取所有分支。
-- 处理：Jenkins Job 的 `Pipeline script from SCM` 由 Windows controller 执行，SCM URL 使用公网域名 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。运行于 Linux agent 的 Jenkinsfile 首次 `checkout([$class: 'GitSCM', ...])` 层先尝试 `GIT_REMOTE_URL=http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后直接尝试 `GIT_REMOTE_FALLBACK_URL=https://git.genarrative.world/GenarrativeAI/Genarrative.git`，不再配置内网 IP fallback；所有生产 Jenkinsfile 的首次 checkout 都必须使用目标分支 refspec、`CloneOption shallow=true depth=1 noTags=true honorRefspec=true`。后续统一走 `scripts/jenkins-checkout-source.sh`，该脚本也按主地址、域名备用地址顺序重新 fetch 并把 `origin` 切到实际可用地址；`COMMIT_HASH` 为空时继续 `--depth=1 --no-tags`，只有指定 commit 时才允许加深历史做分支归属校验。
+- 处理：Jenkins Job 的 `Pipeline script from SCM` 由 Windows controller 执行，SCM URL 使用公网域名 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。运行于 `linux && genarrative-build` 的 `Genarrative-Full-Build-And-Deploy` 源码解析阶段、`Genarrative-Web-Build` checkout 阶段，以及部署/发布类 Linux agent 的 Jenkinsfile 首次 `checkout([$class: 'GitSCM', ...])` 层先尝试 `GIT_REMOTE_URL=http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后直接尝试 `GIT_REMOTE_FALLBACK_URL=https://git.genarrative.world/GenarrativeAI/Genarrative.git`，不再配置内网 IP fallback；这些首次 checkout 都必须使用目标分支 refspec、`CloneOption shallow=true depth=1 noTags=true honorRefspec=true`。后续统一走 `scripts/jenkins-checkout-source.sh`，该脚本也按主地址、域名备用地址顺序重新 fetch 并把 `origin` 切到实际可用地址；`COMMIT_HASH` 为空时继续 `--depth=1 --no-tags`，只有指定 commit 时才允许加深历史做分支归属校验。
 - 验证：扫描本地 Jenkins live job `config.xml`，确认 SCM `<url>` 都是 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；扫描所有生产 Jenkinsfile 的首次 `GitSCM checkout`，确认 `userRemoteConfigs` 带 `+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}`，`CloneOption` 带 `honorRefspec: true`；运行 `bash -n scripts/jenkins-checkout-source.sh`。
 - 关联：`jenkins/Jenkinsfile.production-full-build-and-deploy`、`jenkins/Jenkinsfile.production-web-build`、`jenkins/Jenkinsfile.production-api-build`、`jenkins/Jenkinsfile.production-stdb-module-build`、`jenkins/Jenkinsfile.production-web-deploy`、`jenkins/Jenkinsfile.production-api-deploy`、`jenkins/Jenkinsfile.production-stdb-module-publish`、`jenkins/Jenkinsfile.production-server-provision`、`jenkins/Jenkinsfile.production-database-export`、`jenkins/Jenkinsfile.production-database-import`、`scripts/jenkins-checkout-source.sh`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。