Add release web artifact rsync fallback

Reviewed-on: #18

.codex/skills/behavior-driven-development

@@ -1 +0,0 @@
-C:/proj/Genarrative/.hermes/skills/behavior-driven-development

.codex/skills/behavior-driven-development

@@ -0,0 +1 @@
+C:/proj/Genarrative/.hermes/skills/behavior-driven-development

.env

@@ -0,0 +1,5 @@
+# 微信小程序 web-view 登录配置。
+# 留空时不覆盖已有微信网页 OAuth 配置；正式联调时再填小程序 AppID / AppSecret。
+WECHAT_MINI_PROGRAM_APP_ID=""
+WECHAT_MINI_PROGRAM_APP_SECRET=""
+WECHAT_JS_CODE_SESSION_ENDPOINT=""

.env.example

@@ -103,6 +103,9 @@ WECHAT_REDIRECT_PATH="/"
 WECHAT_AUTHORIZE_ENDPOINT="https://open.weixin.qq.com/connect/qrconnect"
 WECHAT_ACCESS_TOKEN_ENDPOINT="https://api.weixin.qq.com/sns/oauth2/access_token"
 WECHAT_USER_INFO_ENDPOINT="https://api.weixin.qq.com/sns/userinfo"
+WECHAT_JS_CODE_SESSION_ENDPOINT="https://api.weixin.qq.com/sns/jscode2session"
+WECHAT_STABLE_ACCESS_TOKEN_ENDPOINT="https://api.weixin.qq.com/cgi-bin/stable_token"
+WECHAT_PHONE_NUMBER_ENDPOINT="https://api.weixin.qq.com/wxa/business/getuserphonenumber"
 WECHAT_STATE_TTL_MINUTES="15"
 WECHAT_MOCK_USER_ID="wx-mock-user"
 WECHAT_MOCK_UNION_ID="wx-mock-union"

.env.local

@@ -56,8 +56,6 @@ LLM_DEBUG_LOG="true"
 ALIYUN_OSS_BUCKET="xushi-dev"
 ALIYUN_OSS_REGION="oss-cn-beijing"
 ALIYUN_OSS_ENDPOINT="oss-cn-beijing.aliyuncs.com"
-ALIYUN_OSS_ACCESS_KEY_ID="LTAI5t7aiyw6uDFW4miJvU8f"
-ALIYUN_OSS_ACCESS_KEY_SECRET="XblWGE6CO1WLnSBdMRVpL6lut4GSoS"
 
 # Local Rust backend target for Vite dev proxy.
 RUST_SERVER_TARGET="http://127.0.0.1:8082"

.eslintrc.cjs

@@ -37,6 +37,12 @@ module.exports = {
         'simple-import-sort/exports': 'off',
       },
     },
+    {
+      files: ['src/components/match3d-runtime/Match3DPhysicsBoard.tsx'],
+      rules: {
+        'react-refresh/only-export-components': 'off',
+      },
+    },
   ],
   plugins: [
     '@typescript-eslint',

.github/workflows/ci.yml

@@ -1,44 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-      - master
-
-jobs:
-  verify:
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20.19.0
-          cache: npm
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Check encoding
-        run: npm run check:encoding
-
-      - name: Lint
-        run: npm run lint:eslint
-
-      - name: Typecheck
-        run: npm run typecheck
-
-      - name: Test
-        run: npm run test
-
-      - name: Build
-        run: npm run build
-
-      - name: Validate content
-        run: npm run check:content

.gitignore

@@ -32,3 +32,11 @@ temp*build*/
 /logs
 .worktrees/
 .env.secrets.local
+
+# Local load-test data extracted from private migration files
+scripts/loadtest/data/*.local.json
+
+# Local load-test run artifacts
+scripts/loadtest/data/k6-*.log
+scripts/loadtest/data/k6-*summary*.md
+scripts/loadtest/data/latest-*-prefix.txt

.hermes/plans/2026-05-11_144229-bark-battle-2d-game-bdd-ddd-tdd-plan.md

@@ -0,0 +1,561 @@
+# 声控狗叫对战 2D 浏览器游戏设计与实现计划
+
+## 目标
+
+基于用户提供的视频：
+
+`C:\Users\DSK\Videos\一款双方比狗叫的游戏 - 1.一款双方比狗叫的游戏(Av116504192360177,P1).mp4`
+
+提取其中“双方比狗叫”的核心玩法，并按照 BDD / TDD / DDD 的方法，为 Genarrative 中可运行于浏览器的 2D 游戏方案生成一份可落地设计与实现思路。实现方向遵循仓库内 `game-studio` 插件工作流，默认采用 2D Phaser + TypeScript + Vite + DOM HUD 的浏览器游戏架构。
+
+本计划仅做方案设计，不直接编码。
+
+## 当前上下文与输入分析
+
+### 已识别视频核心画面
+
+通过抽帧观察，视频中的游戏呈现出以下稳定特征：
+
+- 画面是横版 2D 手绘舞台，场景包括公园、海边等固定关卡背景。
+- 双方各有一只狗作为对战角色，站在左右两侧。
+- 中央有明显倒计时，例如 `30`、`28`。
+- 顶部有红蓝双方拉锯式能量条 / 进度条。
+- 中央提示出现：`对着麦克风汪一声`、`用声音大小 + 叫声次数推动能量条！`
+- 玩家输入不是传统键鼠，而是麦克风声音。
+- 玩家需要模仿狗叫，系统根据声音大小与叫声次数推动能量条。
+- 屏幕会根据叫声出现 `BARK`、`WOOF`、`WAN`、`WANGOOF` 等拟声词与冲击波视觉反馈。
+- 回合结束时，根据能量条偏向或推进结果判定胜负。
+
+### 提炼出的核心玩法
+
+这是一个“声控拔河式狗叫对战”小游戏：
+
+- 两名玩家 / 一名玩家对 AI 分别代表左右两只狗。
+- 每局限时 30 秒。
+- 玩家通过麦克风持续发出狗叫声。
+- 游戏实时分析音量峰值、叫声次数、叫声节奏。
+- 声音越大、叫声越密集，己方推动力越强。
+- 顶部能量条在双方推动力差值下左右移动。
+- 时间结束后，能量条偏向哪一方，哪一方获胜。
+
+### 需要合理抽象的地方
+
+视频中存在直播弹幕、贴图、表情包、遮挡层，这些不是游戏本体机制。本方案只吸收游戏本体核心：
+
+- 双方狗狗对叫
+- 麦克风输入
+- 声音强度 + 次数判定
+- 红蓝拉锯能量条
+- 限时回合
+- 夸张拟声词与冲击波反馈
+
+## game-studio 插件路线
+
+根据仓库内 `.hermes/plugins/game-studio` 技能：
+
+- 早期游戏工作先走 `game-studio` 总入口。
+- 2D 浏览器游戏默认选择 Phaser。
+- 架构上需要分离 simulation 与 renderer。
+- HUD / 菜单 / 设置优先使用 DOM overlay，不把密集文字塞进 canvas。
+- 玩法状态不应由 Phaser Scene 直接持有，Scene 只负责渲染、动画、相机、输入适配。
+
+因此本方案采用：
+
+- Runtime：Phaser 3
+- Language：TypeScript
+- Build：Vite
+- UI：React/DOM HUD overlay 或项目现有 DOM UI 层
+- Audio input：Web Audio API + MediaDevices.getUserMedia
+- Simulation：纯 TS domain/service 层
+- Renderer：Phaser Scene 读取 simulation snapshot 并播放动画/特效
+
+## 游戏概念设计
+
+### 游戏名建议
+
+- 中文：`汪汪声浪大作战`
+- 英文代号：`bark-battle`
+- Play type ID 建议：`bark-battle`
+
+### 玩家幻想
+
+玩家不是通过按键战斗，而是真的对着麦克风“汪汪叫”，把自己的狗狗声浪推向对手。游戏目标是在倒计时结束前用更响、更密集、更有节奏的叫声赢得声浪拔河。
+
+### 核心动词
+
+- 叫：对麦克风发出狗叫声。
+- 推：通过叫声推动能量条。
+- 压制：让能量条持续向对手方向倾斜。
+- 爆发：短时间内连续高质量叫声触发冲击波。
+- 防守：对手强势时通过持续叫声把能量条拉回。
+
+### 单局流程
+
+1. 准备阶段
+   - 展示双方狗狗、地图、麦克风权限提示。
+   - 用户授权麦克风。
+   - 系统检测环境噪音并校准阈值。
+
+2. 倒计时阶段
+   - 3、2、1 或中央 `30` 倒计时开始。
+   - 玩家看到提示：`对着麦克风汪一声`。
+
+3. 对战阶段
+   - 每帧或固定 tick 采集麦克风音量。
+   - 根据音量峰值与短促叫声次数计算本方 barkPower。
+   - AI 或远端对手产生 opponentPower。
+   - 能量条根据 `playerPower - opponentPower` 拉锯。
+   - 狗狗张嘴动画、拟声词、冲击波按声音强度生成。
+
+4. 结算阶段
+   - 30 秒结束。
+   - 能量条偏玩家侧则胜利，偏对手侧则失败，接近中线则平局。
+   - 展示叫声次数、最大音量、平均节奏、声浪评分。
+
+5. 重开 / 返回
+   - 支持再来一局。
+   - 支持返回玩法入口或结果页。
+
+## 规则设计
+
+### 关键状态
+
+```ts
+type BarkBattlePhase = 'permission' | 'calibration' | 'countdown' | 'playing' | 'finished'
+
+type BarkBattleSnapshot = {
+  phase: BarkBattlePhase
+  remainingMs: number
+  energy: number // -100 到 100，负数偏对手，正数偏玩家
+  player: BarkSideState
+  opponent: BarkSideState
+  winner: 'player' | 'opponent' | 'draw' | null
+}
+
+type BarkSideState = {
+  barkCount: number
+  currentVolume: number
+  recentPeak: number
+  combo: number
+  power: number
+  isBarking: boolean
+}
+```
+
+### 输入判定
+
+#### 音量采样
+
+- 使用 Web Audio API 创建 `AnalyserNode`。
+- 每个 simulation tick 读取频域或时域数据。
+- 计算 RMS 或 peak volume。
+- 根据校准后的环境噪音设置动态阈值。
+
+#### 一次“叫声”的判定
+
+一次有效叫声建议满足：
+
+- 音量超过 `barkThreshold`。
+- 与上一次叫声峰值至少间隔 `minBarkGapMs`，避免持续噪音被无限计数。
+- 持续时长在合理范围，例如 80ms 到 1200ms。
+- 可选：频谱能量集中在中高频，不强制做复杂语音识别，MVP 先用音量 + 峰值节奏。
+
+#### 推动力计算
+
+```text
+playerPower = volumeScore * 0.65 + barkRateScore * 0.35 + comboBonus
+opponentPower = aiPower 或远端玩家 power
+energyDelta = (playerPower - opponentPower) * deltaTime * balanceFactor
+energy = clamp(energy + energyDelta, -100, 100)
+```
+
+### AI 对手 MVP
+
+若先做单机浏览器版，右侧对手可由 AI 模拟：
+
+- 简单难度：周期性小叫，power 低。
+- 普通难度：有节奏地爆发，power 中等。
+- 困难难度：根据玩家领先程度自适应追赶，但不得作弊到不可赢。
+
+后续可扩展为多人实时对战。
+
+## BDD 行为场景
+
+### 功能: 麦克风授权与准备
+
+```gherkin
+功能: 狗叫对战麦克风准备
+  为了让玩家能用声音参与对战
+  作为浏览器玩家
+  我希望游戏在开局前明确请求麦克风权限并完成环境校准
+
+  场景: 玩家允许麦克风权限后进入准备倒计时
+    假如玩家打开狗叫对战页面
+    当玩家同意浏览器麦克风授权
+    那么系统应进入环境噪音校准阶段
+    而且校准完成后应显示开局倒计时
+
+  场景: 玩家拒绝麦克风权限
+    假如玩家打开狗叫对战页面
+    当玩家拒绝浏览器麦克风授权
+    那么系统应显示无法声控游玩的提示
+    而且应提供重试授权入口
+    而且不应直接开始对战
+```
+
+### 功能: 声音推动能量条
+
+```gherkin
+功能: 声音大小和叫声次数推动能量条
+  为了复刻双方比狗叫的核心体验
+  作为玩家
+  我希望自己的叫声能实时推动顶部能量条
+
+  场景: 玩家发出一次有效狗叫
+    假如游戏处于 playing 阶段
+    而且麦克风输入音量超过有效叫声阈值
+    当系统检测到一次新的叫声峰值
+    那么玩家叫声次数应增加 1
+    而且玩家狗狗应播放张嘴吠叫动画
+    而且画面应出现拟声词反馈
+
+  场景: 玩家连续大声狗叫压制对手
+    假如游戏处于 playing 阶段
+    而且玩家在短时间内产生多次有效叫声
+    当玩家推动力高于对手推动力
+    那么顶部能量条应向玩家侧移动
+    而且玩家侧声浪特效应增强
+
+  场景: 环境噪音低于阈值不计入叫声
+    假如游戏处于 playing 阶段
+    当麦克风只有低于阈值的背景噪音
+    那么玩家叫声次数不应增加
+    而且能量条不应因为背景噪音明显移动
+```
+
+### 功能: 限时胜负结算
+
+```gherkin
+功能: 狗叫对战胜负结算
+  为了让单局对抗有明确目标
+  作为玩家
+  我希望倒计时结束后根据能量条位置判定胜负
+
+  场景: 倒计时结束时玩家侧占优
+    假如游戏剩余时间归零
+    而且能量条位于玩家侧
+    当系统进入结算阶段
+    那么系统应判定玩家胜利
+    而且展示玩家叫声次数、最大音量和声浪评分
+
+  场景: 倒计时结束时双方接近平衡
+    假如游戏剩余时间归零
+    而且能量条处于平局阈值范围内
+    当系统进入结算阶段
+    那么系统应判定为平局
+    而且展示再来一局入口
+```
+
+### 功能: 移动端与无麦克风降级
+
+```gherkin
+功能: 声控游戏移动端与无麦克风降级
+  为了让不同设备玩家都能理解当前状态
+  作为移动端或无麦克风环境玩家
+  我希望系统给出清晰、可操作的降级路径
+
+  场景: 当前浏览器不支持麦克风 API
+    假如玩家设备不支持 getUserMedia
+    当玩家进入狗叫对战页面
+    那么系统应显示设备不支持麦克风输入
+    而且提供返回入口
+
+  场景: 移动端进入对战页面
+    假如玩家使用移动端浏览器
+    当玩家进入狗叫对战页面
+    那么主要能量条、倒计时和狗狗角色应保持可见
+    而且非关键设置应收起到菜单中
+```
+
+## DDD 领域划分
+
+### 领域层：bark-battle domain
+
+职责：只处理玩法规则，不依赖 Phaser、DOM、Web Audio、后端。
+
+建议模块：
+
+- `BarkBattleSession`
+  - 管理 phase、remainingMs、energy、winner。
+- `BarkDetector`
+  - 根据音量样本判断是否形成一次有效叫声。
+- `EnergyTugOfWar`
+  - 根据双方 power 更新能量条。
+- `BarkBattleScoring`
+  - 计算最大音量、叫声次数、combo、评分。
+- `OpponentStrategy`
+  - 单机 AI 对手策略接口。
+
+领域规则必须可用纯单元测试验证。
+
+### 应用层：use case / controller
+
+职责：编排麦克风输入、simulation tick、AI 对手、结果输出。
+
+建议用例：
+
+- `requestMicrophonePermission()`
+- `calibrateAmbientNoise()`
+- `startBarkBattleSession()`
+- `submitAudioSample(sample)`
+- `tickBarkBattle(deltaMs)`
+- `finishBarkBattle()`
+
+### 基础设施层
+
+职责：浏览器 API 与引擎适配。
+
+- `BrowserMicrophoneInput`
+  - 封装 `navigator.mediaDevices.getUserMedia`。
+  - 输出 normalized volume samples。
+- `PhaserBarkBattleScene`
+  - 渲染狗狗、背景、拟声词、冲击波。
+  - 不持有核心玩法规则。
+- `DomBarkBattleHud`
+  - 展示倒计时、能量条、权限提示、结算面板。
+
+### 表现层
+
+- Phaser Canvas：地图、狗狗、声浪、粒子、拟声词。
+- DOM HUD：顶部能量条、倒计时、权限/结算/设置面板。
+
+## TDD 落地顺序
+
+### 第一轮：领域规则 RED-GREEN-REFACTOR
+
+先写纯 TS 单元测试，不接 Phaser，不接麦克风。
+
+目标测试：
+
+- `BarkDetector`：超过阈值且间隔足够时计为一次叫声。
+- `BarkDetector`：持续噪音不会无限增加叫声次数。
+- `EnergyTugOfWar`：玩家 power 高于对手时 energy 向玩家侧移动。
+- `EnergyTugOfWar`：energy 被 clamp 在 -100 到 100。
+- `BarkBattleSession`：倒计时归零后进入 finished。
+- `BarkBattleSession`：根据 energy 判定 player/opponent/draw。
+
+### 第二轮：应用层测试
+
+- 模拟音频 sample 输入，验证 session snapshot 更新。
+- 模拟 AI 对手 power，验证能量条拉锯。
+- 模拟权限失败，验证 phase 不进入 playing。
+
+### 第三轮：组件 / 集成测试
+
+- HUD 根据 snapshot 显示倒计时。
+- HUD 根据 energy 渲染红蓝能量条比例。
+- 权限拒绝时显示重试入口。
+- 结算阶段显示胜负与再来一局。
+
+### 第四轮：浏览器 smoke / playtest
+
+- 本地启动页面。
+- 授权麦克风。
+- 对麦克风发声后看到拟声词与能量条变化。
+- 移动端宽度下主游戏画面不被 HUD 遮挡。
+
+## 建议文件结构
+
+如果作为独立前端玩法原型，可采用：
+
+```text
+src/games/bark-battle/
+  domain/
+    BarkBattleSession.ts
+    BarkDetector.ts
+    EnergyTugOfWar.ts
+    BarkBattleScoring.ts
+    OpponentStrategy.ts
+  application/
+    BarkBattleController.ts
+    BrowserMicrophoneInput.ts
+  phaser/
+    BarkBattleScene.ts
+    BarkBattlePreloadScene.ts
+    barkBattleAssets.ts
+  ui/
+    BarkBattleHud.tsx
+    BarkBattleResultPanel.tsx
+    BarkBattlePermissionPanel.tsx
+  tests/
+    BarkDetector.test.ts
+    EnergyTugOfWar.test.ts
+    BarkBattleSession.test.ts
+```
+
+如果接入 Genarrative 玩法类型闭环，后续还需要按 `genarrative-play-type-integration` 扩展：
+
+```text
+src/components/bark-battle-runtime/BarkBattleRuntimeShell.tsx
+src/components/bark-battle-result/BarkBattleResultView.tsx
+src/services/barkBattleRuntimeClient.ts
+packages/shared/src/contracts/barkBattle.ts
+server-rs/crates/shared-contracts/src/bark_battle.rs
+```
+
+MVP 阶段建议先做浏览器单机 runtime 原型，再决定是否进入创作入口、作品发布、广场和后端持久化。
+
+## UI / 视觉方向
+
+### 画面
+
+- 横版固定舞台。
+- 左右两只狗对峙。
+- 背景可先做公园一张图，后续扩展海边、街区等地图。
+- 狗狗用 2D sprite 或简单骨架帧动画。
+
+### HUD
+
+- 顶部：红蓝声浪能量条。
+- 中央：大号倒计时，只在开局和关键时间突出显示。
+- 左右：双方狗狗状态，不堆叠复杂面板。
+- 底部或角落：麦克风状态、小型重试按钮。
+- 结算：居中弹出简洁面板，显示胜负和关键数据。
+
+### 动效
+
+- 叫声触发狗狗张嘴。
+- 声音越大，拟声词越大，冲击波越宽。
+- combo 时触发短暂屏幕震动，但不能遮挡能量条。
+- 尊重 reduced motion，非必要动画可降级。
+
+## 测试映射
+
+| BDD 场景 | 测试层级 | 目标文件 | 状态 |
+| --- | --- | --- | --- |
+| 玩家允许麦克风权限后进入准备倒计时 | application/component | `BarkBattleController.test.ts`, `BarkBattlePermissionPanel.test.tsx` | planned |
+| 玩家拒绝麦克风权限 | application/component | `BarkBattleController.test.ts`, `BarkBattlePermissionPanel.test.tsx` | planned |
+| 玩家发出一次有效狗叫 | unit | `BarkDetector.test.ts` | planned |
+| 玩家连续大声狗叫压制对手 | unit/integration | `EnergyTugOfWar.test.ts`, `BarkBattleController.test.ts` | planned |
+| 环境噪音低于阈值不计入叫声 | unit | `BarkDetector.test.ts` | planned |
+| 倒计时结束时玩家侧占优 | unit | `BarkBattleSession.test.ts` | planned |
+| 倒计时结束时双方接近平衡 | unit | `BarkBattleSession.test.ts` | planned |
+| 当前浏览器不支持麦克风 API | component | `BarkBattlePermissionPanel.test.tsx` | planned |
+| 移动端进入对战页面 | visual/smoke | Playwright 或人工 playtest 清单 | planned |
+
+## 验证命令建议
+
+具体命令以后续实际落地位置为准，建议包括：
+
+```bash
+npm run test -- --run src/games/bark-battle/**/*.test.ts
+npm run test -- --run src/games/bark-battle/**/*.test.tsx
+npm run typecheck
+npm run check:encoding
+```
+
+若接入 Genarrative 后端或玩法配置，还需要追加：
+
+```bash
+cd server-rs && cargo check -p api-server -p shared-contracts --no-default-features
+npm run test -- src/components/platform-entry/platformEntryCreationTypes.test.ts
+```
+
+## 实施阶段拆分
+
+### Phase 0：产品与技术定稿
+
+- 确认玩法 ID：`bark-battle`。
+- 确认 MVP 只做单机玩家 vs AI，不做实时多人。
+- 确认是否只做 runtime 原型，还是接入 Genarrative 创作入口。
+- 确认是否允许浏览器麦克风权限作为核心输入。
+
+### Phase 1：纯领域模型
+
+- 建立 bark-battle domain。
+- 按 TDD 写 `BarkDetector`、`EnergyTugOfWar`、`BarkBattleSession` 测试。
+- 实现最小规则让测试通过。
+
+### Phase 2：麦克风输入适配
+
+- 封装 Web Audio API。
+- 支持权限请求、权限失败、环境噪音校准。
+- 使用 mock input 完成自动化测试，真实麦克风做 smoke。
+
+### Phase 3：Phaser 2D runtime
+
+- 新建 Phaser Scene。
+- 绘制或占位加载公园背景、左右狗狗、声浪特效。
+- Scene 只消费 snapshot，不写规则。
+- 接入 DOM HUD。
+
+### Phase 4：反馈与结算
+
+- 加入拟声词、冲击波、狗狗张嘴动画。
+- 加入结算面板。
+- 加入再来一局与返回入口。
+
+### Phase 5：Genarrative 集成可选项
+
+若要正式接入玩法类型：
+
+- 补 `shared-contracts` 中 bark-battle runtime/result DTO。
+- 补前端 service 与 runtime shell。
+- 补入口配置数据库 seed。
+- 补作品架 / 发布 / 广场链路，若需要持久化成绩或作品。
+- 按 `genarrative-play-type-integration` 执行完整闭环验证。
+
+## 风险与权衡
+
+### 麦克风权限风险
+
+浏览器麦克风权限受 HTTPS、浏览器策略、用户设置影响。MVP 需要明确：
+
+- 本地开发可在 localhost 使用。
+- 线上必须 HTTPS。
+- 权限拒绝需要可恢复。
+
+### 声音识别准确性风险
+
+MVP 不建议做复杂“是否真的是狗叫”的 AI 识别，否则实现成本高、误判多。建议先用：
+
+- 音量阈值
+- 峰值次数
+- 节奏间隔
+- 环境噪音校准
+
+后续再考虑加入频谱特征或 ML 分类。
+
+### 噪音作弊风险
+
+玩家可以喊叫、拍桌子或播放音频。若是娱乐派对玩法可以接受；若要竞技公平，需要后续加入：
+
+- 频谱特征
+- 输入冷却
+- 异常持续噪音削弱
+- 本地/服务端反作弊策略
+
+### 移动端兼容风险
+
+移动端 Web Audio 可能需要用户手势激活 AudioContext。计划中需把“开始”按钮作为显式用户手势，避免自动启动失败。
+
+### UI 遮挡风险
+
+视频原型中的核心可读信息非常少：倒计时、能量条、狗狗、拟声词。实现时应避免把说明文案、复杂面板长期铺在画面上。
+
+## 开放问题
+
+1. MVP 是“玩家 vs AI”，还是需要从第一版开始支持双人同屏 / 联机？
+2. 是否要作为 Genarrative 新玩法入口完整接入，还是先做独立 runtime 原型？
+3. 是否需要记录成绩、发布作品、进入作品架和广场？
+4. 狗狗与背景素材是使用临时占位、AI 生成，还是需要复用项目既有素材系统？
+5. 是否允许游戏强依赖麦克风权限，还是必须提供键盘备用输入？
+
+## 推荐下一步
+
+建议下一步先执行 Phase 0 + Phase 1：
+
+1. 明确 MVP 边界：单机玩家 vs AI。
+2. 写 `BarkDetector` / `EnergyTugOfWar` / `BarkBattleSession` 的 BDD 对应单元测试。
+3. 不接 Phaser、不接麦克风，先把核心规则用 TDD 跑通。
+4. 规则稳定后再接 Web Audio 与 Phaser runtime。

.hermes/plans/2026-05-11_170028-bark-battle-three-phase-browser-ai-db-plan.md

@@ -0,0 +1,709 @@
+# bark-battle 三阶段实施计划：浏览器原型 → AI 创作入口 → 数据库落地
+
+> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
+
+**Goal:** 按“三阶段”推进 `bark-battle / 汪汪声浪大作战`：第一阶段先做纯浏览器可运行游戏原型并验证玩法跑通；第二阶段接入 Genarrative 创作入口，用 AI 生成可试玩内容；第三阶段再打通后端数据库、发布、成绩和作品闭环。
+
+**Architecture:** 第一阶段只在前端 runtime 内闭环，优先落 `src/games/bark-battle/` 与直达路由，不依赖后端和 SpacetimeDB。第二阶段在已有创作入口、Agent flow controller、结果页和 runtime shell 上接入 `bark-battle`，AI 只生成配置化草稿，不承接正式业务真相。第三阶段按 `server-rs + Axum + SpacetimeDB` DDD 分层落库，前端只展示后端投影和调用后端 API。
+
+**Tech Stack:** React 19、TypeScript、Vite、Vitest、Testing Library；第一阶段优先 DOM/Canvas 原型，可在验证玩法后再引入 Phaser 3；后端阶段使用 `server-rs`、Axum、SpacetimeDB、shared-contracts。
+
+---
+
+## 0. 当前上下文 / 假设
+
+- 现有需求与技术文档：
+  - `docs/prd/BARK_BATTLE_BDD_2026-05-11.md`
+  - `docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md`
+  - `docs/technical/BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md`
+- 用户明确要求阶段顺序：
+  1. 第一阶段：先制作纯浏览器运行的游戏原型，需要测试游戏功能是否能跑通。
+  2. 第二阶段：打通创作入口，使用 AI 赋能游戏内容创作。
+  3. 第三阶段：最后打通数据库落地。
+- 因此本计划调整原技术方案中的落地优先级：
+  - 第一阶段不新增后端表、不接发布、不接作品架。
+  - 第一阶段可以用 mock / local draft 配置与直达路由 `/bark-battle` 完成 playable prototype。
+  - 第一阶段若 Phaser 依赖尚未安装，优先用 React DOM + Canvas/CSS 2D 原型跑通功能；待核心规则验证后再决定是否引入 Phaser，避免第一阶段被依赖安装和素材管线阻塞。
+- 当前仓库 `package.json` 还没有 `phaser` 依赖；如实现者选择 Phaser，需要单独评估依赖引入、包体和测试影响。
+- 本计划只写计划，不直接实现代码。
+
+## 1. 总体分阶段验收口径
+
+### Phase 1：纯浏览器游戏原型
+
+目标：打开本地前端路由即可玩到一局 `bark-battle`，并通过自动测试确认核心规则跑通。
+
+必须满足：
+- 可从 `/bark-battle` 进入独立原型页面。
+- 不登录、不请求后端、不依赖数据库。
+- 支持开发 mock input：点击/按键/按钮可模拟音量峰值；有真实麦克风时可走 Web Audio。
+- 能完成：权限/开始 → 校准或 mock 准备 → 倒计时 → 30 秒 playing → 结算 → 再来一局。
+- 低于阈值输入不计数；有效叫声计数；能量条向玩家或对手移动；结算胜/负/平。
+- 移动端至少能看到能量条、倒计时、双方狗狗、主要按钮和结算。
+
+### Phase 2：AI 创作入口
+
+目标：创作者能从创作中心选择 `bark-battle`，用 AI 生成玩法配置草稿，并进入结果页试玩。
+
+必须满足：
+- 后端入口配置中出现 `bark-battle`，按开关展示/可点击。
+- 前端类型分流、SelectionStage、工作台、结果页、runtime 入口齐全。
+- AI 生成内容仅限配置化草稿：标题、主题、狗狗外观描述、背景风格、难度、局长、AI 对手参数、提示文案 key 等。
+- 生成结果可在本地 runtime 中试玩。
+- 未落库前可先用 session/local state 保存草稿，但要清楚标识为“未发布草稿”。
+
+### Phase 3：数据库落地与正式作品闭环
+
+目标：`bark-battle` 草稿、发布态配置、runtime start/finish、成绩和作品级游玩埋点都进入后端 DDD / SpacetimeDB 链路。
+
+必须满足：
+- `shared-contracts`、`module-bark-battle`、`spacetime-module`、`spacetime-client`、`api-server` 分层清晰。
+- 发布为稳定作品 ID，runtime 从后端读取发布态 config。
+- start 成功写 `work_play_start`：`scope_kind=work`、`scope_id=稳定作品 ID`、metadata 包含 `playType/workId/sourceRoute/userId`。
+- finish 只上传派生指标，不保存原始麦克风音频、波形或可还原语音内容。
+- 作品架/广场/分享/排行榜如启用，均来自后端投影。
+
+---
+
+## 2. Phase 1：纯浏览器运行游戏原型
+
+### Task 1.1：补齐阶段边界文档
+
+**Objective:** 在现有技术方案中明确“先浏览器原型，后 AI 创作，最后数据库”的落地顺序，避免实现时过早接后端。
+
+**Files:**
+- Modify: `docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md`
+- Modify: `docs/prd/BARK_BATTLE_BDD_2026-05-11.md`
+
+**Steps:**
+1. 在 runtime 技术方案中新增“三阶段落地顺序”小节。
+2. 明确 Phase 1 不接后端、不接数据库、不接创作入口事实源。
+3. 在 BDD 中补充“浏览器原型 smoke”验收场景。
+4. 运行：
+   ```bash
+   npm run check:encoding -- docs/prd/BARK_BATTLE_BDD_2026-05-11.md docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md
+   git diff --check
+   ```
+
+**Expected:** 编码检查和 diff 空白检查通过。
+
+### Task 1.2：建立 Phase 1 目录骨架和类型
+
+**Objective:** 建立不依赖 React/DOM/Web Audio 的核心类型，后续所有测试和 UI 都围绕这些类型。
+
+**Files:**
+- Create: `src/games/bark-battle/domain/BarkBattleTypes.ts`
+- Create: `src/games/bark-battle/application/BarkBattleConfig.ts`
+
+**Key design:**
+- `BarkBattlePhase = 'permission' | 'calibration' | 'countdown' | 'playing' | 'finished' | 'unavailable'`
+- `MicrophoneFailureReason` 覆盖已有文档中的 9 类失败原因。
+- `BarkBattleSnapshot` 包含 `phase/uiState/errorReason/statusMessageKey/remainingMs/energy/player/opponent/winner/result/lastEvents`。
+- `BarkBattleConfig` 包含 `roundDurationMs/drawThreshold/minBarkGapMs/minBarkDurationMs/maxBarkDurationMs/balanceFactor/calibrationMaxWaitMs`。
+
+**Tests:**
+- 本任务可先不写运行时逻辑，但需要让 typecheck 能引用这些类型。
+
+**Validation:**
+```bash
+npm run typecheck
+npm run check:encoding -- src/games/bark-battle/domain/BarkBattleTypes.ts src/games/bark-battle/application/BarkBattleConfig.ts
+```
+
+### Task 1.3：TDD 实现叫声检测 BarkDetector
+
+**Objective:** 用纯函数/纯类把音频样本转换为有效叫声事件。
+
+**Files:**
+- Create: `src/games/bark-battle/domain/BarkDetector.ts`
+- Create: `src/games/bark-battle/domain/__tests__/BarkDetector.test.ts`
+
+**Test cases:**
+1. 超过阈值、持续时长合规、间隔足够时计为一次有效叫声。
+2. 持续噪音不在每个 tick 无限计数。
+3. 低于阈值的背景噪音不计数。
+4. `minBarkGapMs` 内连续峰值不重复计数。
+5. 过短脉冲不计数；过长持续声削弱为单段输入。
+
+**Validation:**
+```bash
+npm run test -- --run src/games/bark-battle/domain/__tests__/BarkDetector.test.ts
+npm run typecheck
+```
+
+### Task 1.4：TDD 实现能量条 EnergyTugOfWar
+
+**Objective:** 验证玩家/对手推动力能稳定改变 `energy`，并 clamp 到 `-100..100`。
+
+**Files:**
+- Create: `src/games/bark-battle/domain/EnergyTugOfWar.ts`
+- Create: `src/games/bark-battle/domain/__tests__/EnergyTugOfWar.test.ts`
+
+**Test cases:**
+1. 玩家 power 高于对手时 `energy` 增加。
+2. 对手 power 高于玩家时 `energy` 减少。
+3. energy 不超过 `100`。
+4. energy 不低于 `-100`。
+5. power 相等时变化不超过浮点误差。
+
+**Validation:**
+```bash
+npm run test -- --run src/games/bark-battle/domain/__tests__/EnergyTugOfWar.test.ts
+npm run typecheck
+```
+
+### Task 1.5：TDD 实现单局状态机 BarkBattleSession
+
+**Objective:** 跑通 permission/calibration/countdown/playing/finished/unavailable 状态流转和结算。
+
+**Files:**
+- Create: `src/games/bark-battle/domain/BarkBattleSession.ts`
+- Create: `src/games/bark-battle/domain/BarkBattleScoring.ts`
+- Create: `src/games/bark-battle/domain/OpponentStrategy.ts`
+- Create: `src/games/bark-battle/domain/__tests__/BarkBattleSession.test.ts`
+- Create: `src/games/bark-battle/domain/__tests__/BarkBattleScoring.test.ts`
+
+**Test cases:**
+1. 校准完成后进入 countdown。
+2. countdown 结束后进入 playing。
+3. playing 中 `remainingMs` 随 tick 递减。
+4. `remainingMs <= 0` 后进入 finished。
+5. `energy > drawThreshold` 判定玩家胜。
+6. `energy < -drawThreshold` 判定对手胜。
+7. `abs(energy) <= drawThreshold` 判定平局。
+8. finished 后新输入不再改变本局计数和能量。
+
+**Validation:**
+```bash
+npm run test -- --run src/games/bark-battle/domain/__tests__/BarkBattleSession.test.ts src/games/bark-battle/domain/__tests__/BarkBattleScoring.test.ts
+npm run typecheck
+```
+
+### Task 1.6：实现 mock-first Application Controller
+
+**Objective:** 不依赖真实麦克风，先用 mock audio sample 驱动完整 snapshot。
+
+**Files:**
+- Create: `src/games/bark-battle/application/BarkBattleController.ts`
+- Create: `src/games/bark-battle/application/BarkBattleSnapshotStore.ts`
+- Create: `src/games/bark-battle/application/__tests__/BarkBattleController.test.ts`
+
+**Behavior:**
+- `startWithMockInput()` 进入校准完成或直接 countdown。
+- `submitMockSample(sample)` 更新玩家输入。
+- `tick(deltaMs)` 推进对手、能量条、倒计时。
+- `restart()` 重置状态。
+- `failMicrophone(reason)` 进入 `phase: 'unavailable'`，并设置 `errorReason/statusMessageKey`。
+
+**Test cases:**
+1. mock start 后能进入 countdown/playing。
+2. 提交 mock 峰值后 bark count 增加。
+3. tick 后 energy 可变化。
+4. finish 后生成 result。
+5. `failMicrophone('permission-denied')` 不进入 playing。
+
+**Validation:**
+```bash
+npm run test -- --run src/games/bark-battle/application/__tests__/BarkBattleController.test.ts
+npm run typecheck
+```
+
+### Task 1.7：实现浏览器原型 UI Shell（不接平台）
+
+**Objective:** 提供 `/bark-battle` 可访问的 playable prototype。
+
+**Files:**
+- Create: `src/BarkBattlePlaygroundApp.tsx`
+- Create: `src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx`
+- Create: `src/games/bark-battle/ui/BarkBattleHud.tsx`
+- Create: `src/games/bark-battle/ui/BarkBattleResultPanel.tsx`
+- Create: `src/games/bark-battle/ui/BarkBattleHud.css`
+- Modify: `src/routing/appRoutes.tsx`
+
+**Behavior:**
+- 新增路由匹配：`/bark-battle`。
+- 首屏只有清爽开始面板，不常驻大段规则。
+- 提供开发原型按钮：开始、模拟叫声、模拟对手增强、再来一局。
+- playing 画面展示：顶部能量条、倒计时、玩家/对手狗狗、叫声次数、麦克风/mock 状态。
+- 结算面板独立居中，不追加在当前面板下方。
+
+**UI constraints:**
+- 移动端优先。
+- 正常 playing 阶段不在 playfield 常驻规则说明。
+- 大动效不遮挡顶部能量条和倒计时。
+
+**Validation:**
+```bash
+npm run test -- --run src/games/bark-battle/ui/**/*.test.tsx
+npm run typecheck
+npm run dev:web
+# 手动 smoke: 访问 /bark-battle → 开始 → 模拟叫声 → energy 变化 → 结算 → 再来一局
+```
+
+### Task 1.8：实现 HUD 组件测试
+
+**Objective:** 自动验证核心 UI 状态，不只依赖人工试玩。
+
+**Files:**
+- Create: `src/games/bark-battle/ui/__tests__/BarkBattleHud.test.tsx`
+- Create: `src/games/bark-battle/ui/__tests__/BarkBattleResultPanel.test.tsx`
+
+**Test cases:**
+1. playing 阶段展示倒计时和能量条。
+2. energy 正值时玩家侧占比更大。
+3. energy 负值时对手侧占比更大。
+4. permission-denied 展示重试授权入口。
+5. unsupported 不展示开始声控按钮。
+6. finished 展示胜负、叫声次数、再来一局。
+
+**Validation:**
+```bash
+npm run test -- --run src/games/bark-battle/ui/__tests__/BarkBattleHud.test.tsx src/games/bark-battle/ui/__tests__/BarkBattleResultPanel.test.tsx
+npm run typecheck
+```
+
+### Task 1.9：接入真实 Web Audio（可晚于 mock 原型）
+
+**Objective:** 在支持麦克风的浏览器中真实采样并驱动 controller，同时保留 mock fallback 便于测试。
+
+**Files:**
+- Create: `src/games/bark-battle/infrastructure/BrowserMicrophoneInput.ts`
+- Create: `src/games/bark-battle/infrastructure/AudioAnalyserSampler.ts`
+- Create: `src/games/bark-battle/infrastructure/MicrophonePermission.ts`
+- Create: `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`
+- Create: `src/games/bark-battle/infrastructure/__tests__/AudioAnalyserSampler.test.ts`
+
+**Behavior:**
+- 用户点击开始后才请求麦克风。
+- 用户手势后创建/resume `AudioContext`。
+- 输出归一化 `BarkAudioSample`。
+- 捕获并映射：unsupported、permission-denied、non-secure-context、not-found、not-readable、audio-context-blocked、unknown。
+- stop/restart/page unload 时停止 tracks。
+
+**Validation:**
+```bash
+npm run test -- --run src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts src/games/bark-battle/infrastructure/__tests__/AudioAnalyserSampler.test.ts
+npm run typecheck
+npm run dev:web
+# 手动 smoke: 真实麦克风授权 → 校准 → 发声 → 结算
+```
+
+### Task 1.10：Phase 1 收口验证
+
+**Objective:** 确认“纯浏览器原型”已经可以交给产品/测试试玩。
+
+**Commands:**
+```bash
+npm run test -- --run src/games/bark-battle/domain/**/*.test.ts src/games/bark-battle/application/**/*.test.ts src/games/bark-battle/infrastructure/**/*.test.ts src/games/bark-battle/ui/**/*.test.tsx
+npm run typecheck
+npm run lint:eslint
+npm run check:encoding
+npm run dev:web
+```
+
+**Manual smoke checklist:**
+- [ ] `/bark-battle` 能打开。
+- [ ] mock 模式可完整完成一局。
+- [ ] 真实麦克风模式可授权、校准、发声、结算。
+- [ ] 拒绝权限后不会进入 playing。
+- [ ] 移动端窄屏能看到核心信息并能点击主要按钮。
+- [ ] 再来一局不会继承上一局 energy/barkCount/result。
+
+---
+
+## 3. Phase 2：打通创作入口，用 AI 赋能内容创作
+
+### Task 2.1：定义 `bark-battle` 草稿契约（前端本地版）
+
+**Objective:** 在接后端前，先定义 AI 可生成的 runtime draft shape。
+
+**Files:**
+- Create: `packages/shared/src/contracts/barkBattle.ts`（临时前端共享类型，后端阶段再对齐 Rust shared-contracts）
+- Create: `src/services/bark-battle-creation/barkBattleDraftDefaults.ts`
+- Create: `src/services/bark-battle-creation/barkBattleDraftValidation.ts`
+
+**Draft fields:**
+- `title`
+- `description`
+- `themePrompt`
+- `playerDogName`
+- `opponentDogName`
+- `backgroundStyle`
+- `difficulty`
+- `roundDurationMs`
+- `drawThreshold`
+- `opponentConfig`
+- `audioSensitivityPreset`
+- `visualStyle`
+
+**Validation:**
+```bash
+npm run test -- --run src/services/bark-battle-creation/**/*.test.ts
+npm run typecheck
+```
+
+### Task 2.2：新增创作入口配置
+
+**Objective:** 让 `bark-battle` 出现在创作中心入口中，但可通过后端入口配置开关控制。
+
+**Files likely to change:**
+- `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs`
+- `server-rs/crates/module-runtime/src/domain.rs`
+- `server-rs/crates/module-runtime/src/application.rs`
+- `server-rs/crates/shared-contracts/src/creation_entry_config.rs`
+- `src/components/platform-entry/platformEntryCreationTypes.ts`
+- `src/components/platform-entry/platformEntryCreationTypes.test.ts`
+
+**Plan:**
+1. 在入口 seed 中新增 `bark-battle`，首轮可设：`visible: true`、`open: true`（若需要灰度则 `open: false`）。
+2. 前端展示派生只消费 API 返回，不恢复旧静态入口事实源。
+3. 更新排序和锁定态测试。
+
+**Validation:**
+```bash
+npm run test -- src/components/platform-entry/platformEntryCreationTypes.test.ts
+npm run typecheck
+cd server-rs && cargo check -p api-server -p spacetime-module --no-default-features
+```
+
+### Task 2.3：扩展 SelectionStage 与流程分流
+
+**Objective:** 点击 `bark-battle` 入口后进入对应创作工作台。
+
+**Files likely to change:**
+- `src/components/platform-entry/platformEntryTypes.ts`
+- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+- `src/components/platform-entry/usePlatformCreationAgentFlowController.ts`（如复用通用 agent flow）
+
+**Stages:**
+- `bark-battle-agent-workspace`
+- `bark-battle-generating`（可选）
+- `bark-battle-result`
+- `bark-battle-runtime`
+
+**Validation:**
+```bash
+npm run test -- src/components/platform-entry/**/*.test.tsx src/components/platform-entry/**/*.test.ts
+npm run typecheck
+```
+
+### Task 2.4：实现 AI 创作工作台
+
+**Objective:** 用对话式或表单式输入生成 `BarkBattleDraft`。
+
+**Files:**
+- Create: `src/components/bark-battle-creation/BarkBattleAgentWorkspace.tsx`
+- Create: `src/services/bark-battle-creation/barkBattleCreationClient.ts`
+- Create: `src/services/bark-battle-creation/barkBattlePromptBuilder.ts`
+- Create: `src/services/bark-battle-creation/__tests__/barkBattlePromptBuilder.test.ts`
+
+**Behavior:**
+- 用户输入一句主题，例如“柴犬在赛博公园比谁叫得响”。
+- AI 返回结构化草稿。
+- 前端校验并填默认值，不让非法 roundDuration/difficulty 进入 runtime。
+- 错误时保留用户输入和已生成草稿。
+
+**Validation:**
+```bash
+npm run test -- --run src/services/bark-battle-creation/**/*.test.ts
+npm run typecheck
+```
+
+### Task 2.5：实现结果页与试玩入口
+
+**Objective:** AI 草稿生成后可查看、返回编辑、进入 Phase 1 runtime 试玩。
+
+**Files:**
+- Create: `src/components/bark-battle-result/BarkBattleResultView.tsx`
+- Create: `src/components/bark-battle-result/BarkBattleResultView.test.tsx`
+- Modify: `src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx`（允许传入 draft config）
+
+**Behavior:**
+- 展示标题、主题、狗狗名、背景风格、难度、局长。
+- 提供“返回编辑”“试玩”按钮。
+- 暂不展示发布按钮，或发布按钮显示为后端阶段能力。
+
+**Validation:**
+```bash
+npm run test -- --run src/components/bark-battle-result/BarkBattleResultView.test.tsx
+npm run typecheck
+npm run dev:web
+# 手动 smoke: 创作入口 → AI 草稿 → 结果页 → 试玩 → 返回编辑
+```
+
+### Task 2.6：Phase 2 收口验证
+
+**Commands:**
+```bash
+npm run test -- src/components/platform-entry/platformEntryCreationTypes.test.ts src/components/bark-battle-result/BarkBattleResultView.test.tsx src/services/bark-battle-creation/**/*.test.ts src/games/bark-battle/**/*.test.ts src/games/bark-battle/**/*.test.tsx
+npm run typecheck
+npm run lint:eslint
+npm run check:encoding
+```
+
+**Manual smoke checklist:**
+- [ ] 创作中心展示 `bark-battle`。
+- [ ] 点击入口进入工作台。
+- [ ] AI 可生成草稿。
+- [ ] 草稿结果页可展示并返回编辑。
+- [ ] 试玩使用草稿配置影响 runtime 表现。
+- [ ] 未接数据库前不会假装发布成功。
+
+---
+
+## 4. Phase 3：数据库落地与正式作品闭环
+
+### Task 3.1：补齐 shared contracts
+
+**Objective:** 前后端共享 bark-battle DTO，避免前端手写正式契约漂移。
+
+**Files likely to change:**
+- `server-rs/crates/shared-contracts/src/bark_battle.rs`
+- `server-rs/crates/shared-contracts/src/lib.rs`
+- `packages/shared/src/contracts/barkBattle.ts`
+
+**DTO:**
+- `BarkBattleDraft`
+- `BarkBattlePublishedConfig`
+- `CreateBarkBattleSessionRequest/Response`
+- `BarkBattleRuntimeStartRequest/Response`
+- `BarkBattleRuntimeFinishRequest/Response`
+- `BarkBattleRunResult`
+- `BarkBattleScoreSummary`
+- `BarkBattleLeaderboardEntry`
+
+**Validation:**
+```bash
+npm run typecheck
+cd server-rs && cargo check -p shared-contracts --no-default-features
+```
+
+### Task 3.2：新增 `module-bark-battle` 纯领域模块
+
+**Objective:** 后端正式分数、配置校验、提交合法性不写在 api-server handler 里。
+
+**Files:**
+- Create: `server-rs/crates/module-bark-battle/`
+- Modify: `server-rs/Cargo.toml`
+
+**Responsibilities:**
+- 配置合法性校验。
+- run start/finish 状态约束。
+- 派生指标范围校验。
+- 分数与排行榜排序分计算。
+- 不接 Axum、不接 SpacetimeDB、不接 HTTP。
+
+**Validation:**
+```bash
+cd server-rs && cargo test -p module-bark-battle --no-default-features
+cd server-rs && cargo check -p module-bark-battle --no-default-features
+```
+
+### Task 3.3：SpacetimeDB 表、reducer、migration
+
+**Objective:** 保存草稿、发布态配置、run、result、leaderboard 投影。
+
+**Files likely to change:**
+- `server-rs/crates/spacetime-module/src/runtime/bark_battle.rs`（或按现有模块目录命名）
+- `server-rs/crates/spacetime-module/src/migration.rs`
+- `server-rs/crates/spacetime-module/src/lib.rs`
+- 生成绑定目录（通过命令生成，不手改生成物）
+
+**Tables draft:**
+- `bark_battle_draft`
+- `bark_battle_published_config`
+- `bark_battle_run`
+- `bark_battle_run_result`
+- `bark_battle_leaderboard_entry`
+
+**Reducers/procedures:**
+- `create_bark_battle_draft`
+- `publish_bark_battle_config`
+- `start_bark_battle_run`
+- `finish_bark_battle_run`
+- `list_bark_battle_leaderboard`
+
+**Validation:**
+```bash
+npm run spacetime:generate
+cd server-rs && cargo check -p spacetime-module --no-default-features
+npm run check:server-rs-ddd
+```
+
+### Task 3.4：spacetime-client facade
+
+**Objective:** api-server 通过 facade 调用 SpacetimeDB，不直接散落 reducer 细节。
+
+**Files likely to change:**
+- `server-rs/crates/spacetime-client/src/runtime.rs`
+- `server-rs/crates/spacetime-client/src/mapper.rs`
+- `server-rs/crates/spacetime-client/src/lib.rs`
+
+**Validation:**
+```bash
+cd server-rs && cargo check -p spacetime-client --no-default-features
+```
+
+### Task 3.5：api-server BFF 路由
+
+**Objective:** 提供创作、发布态 runtime start/finish、leaderboard API。
+
+**Files likely to change:**
+- `server-rs/crates/api-server/src/bark_battle.rs`
+- `server-rs/crates/api-server/src/main.rs` 或路由注册文件
+
+**Routes draft:**
+- `POST /api/bark-battle/sessions`
+- `GET /api/bark-battle/sessions/:sessionId`
+- `POST /api/bark-battle/runtime/start`
+- `POST /api/bark-battle/runtime/finish`
+- `GET /api/bark-battle/works/:workId/runtime-config`
+- `GET /api/bark-battle/works/:workId/leaderboard`
+
+**Tracking:**
+- runtime start 成功后主动写 `work_play_start`。
+- `scope_kind=work`。
+- `scope_id=稳定作品 ID`。
+- metadata 包含 `playType=bark-battle`、`workId`、`sourceRoute`、`userId`。
+
+**Validation:**
+```bash
+npm run api-server
+# 另一个终端检查 /healthz，并执行对应 API smoke
+cd server-rs && cargo check -p api-server --no-default-features
+```
+
+### Task 3.6：前端正式 client 与 runtime 切换
+
+**Objective:** runtime 从本地草稿模式升级为可读取后端发布态 config，并提交正式派生结果。
+
+**Files likely to change:**
+- Create: `src/services/bark-battle-runtime/barkBattleRuntimeClient.ts`
+- Create: `src/services/bark-battle-works/barkBattleWorksClient.ts`
+- Modify: `src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx`
+- Modify: `src/components/bark-battle-result/BarkBattleResultView.tsx`
+- Modify: `src/components/custom-world-home/creationWorkShelf.ts`
+- Modify: `src/components/custom-world-home/CustomWorldCreationHub.tsx`
+- Modify: `src/services/publicWorkCode.ts`
+
+**Behavior:**
+- 本地 preview 仍可使用 draft config。
+- 正式作品 runtime 必须先调用 start API，拿 run token/session。
+- finish 只提交派生 metrics。
+- 发布后刷新作品架/广场。
+
+**Validation:**
+```bash
+npm run test -- src/services/bark-battle-runtime/**/*.test.ts src/games/bark-battle/**/*.test.ts src/games/bark-battle/**/*.test.tsx
+npm run typecheck
+npm run check:encoding
+```
+
+### Task 3.7：Phase 3 收口验证
+
+**Commands:**
+```bash
+npm run test -- src/games/bark-battle/**/*.test.ts src/games/bark-battle/**/*.test.tsx src/services/bark-battle-runtime/**/*.test.ts src/services/bark-battle-creation/**/*.test.ts
+npm run typecheck
+npm run lint:eslint
+npm run check:encoding
+npm run check:server-rs-ddd
+cd server-rs && cargo test -p module-bark-battle --no-default-features
+cd server-rs && cargo check -p api-server -p spacetime-module -p spacetime-client -p shared-contracts --no-default-features
+npm run api-server
+```
+
+**Manual smoke checklist:**
+- [ ] 创作者生成并发布 bark-battle 作品。
+- [ ] 玩家从作品页进入 runtime。
+- [ ] start API 成功并写 `work_play_start`。
+- [ ] 浏览器本地完成一局。
+- [ ] finish API 只上传派生指标。
+- [ ] 成绩/排行榜/作品架刷新来自后端投影。
+- [ ] 拒绝麦克风权限时不会创建非法 finished result。
+
+---
+
+## 5. 文件清单总览
+
+### Phase 1 likely files
+
+- `src/routing/appRoutes.tsx`
+- `src/BarkBattlePlaygroundApp.tsx`
+- `src/games/bark-battle/domain/BarkBattleTypes.ts`
+- `src/games/bark-battle/domain/BarkDetector.ts`
+- `src/games/bark-battle/domain/EnergyTugOfWar.ts`
+- `src/games/bark-battle/domain/BarkBattleSession.ts`
+- `src/games/bark-battle/domain/BarkBattleScoring.ts`
+- `src/games/bark-battle/domain/OpponentStrategy.ts`
+- `src/games/bark-battle/application/BarkBattleConfig.ts`
+- `src/games/bark-battle/application/BarkBattleController.ts`
+- `src/games/bark-battle/application/BarkBattleSnapshotStore.ts`
+- `src/games/bark-battle/infrastructure/BrowserMicrophoneInput.ts`
+- `src/games/bark-battle/infrastructure/AudioAnalyserSampler.ts`
+- `src/games/bark-battle/infrastructure/MicrophonePermission.ts`
+- `src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx`
+- `src/games/bark-battle/ui/BarkBattleHud.tsx`
+- `src/games/bark-battle/ui/BarkBattleResultPanel.tsx`
+- `src/games/bark-battle/ui/BarkBattleHud.css`
+
+### Phase 2 likely files
+
+- `packages/shared/src/contracts/barkBattle.ts`
+- `src/components/platform-entry/platformEntryTypes.ts`
+- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+- `src/components/platform-entry/platformEntryCreationTypes.ts`
+- `src/components/bark-battle-creation/BarkBattleAgentWorkspace.tsx`
+- `src/components/bark-battle-result/BarkBattleResultView.tsx`
+- `src/services/bark-battle-creation/*`
+
+### Phase 3 likely files
+
+- `server-rs/crates/shared-contracts/src/bark_battle.rs`
+- `server-rs/crates/module-bark-battle/*`
+- `server-rs/crates/spacetime-module/src/runtime/bark_battle.rs`
+- `server-rs/crates/spacetime-module/src/migration.rs`
+- `server-rs/crates/spacetime-client/src/runtime.rs`
+- `server-rs/crates/spacetime-client/src/mapper.rs`
+- `server-rs/crates/api-server/src/bark_battle.rs`
+- `src/services/bark-battle-runtime/*`
+- `src/services/bark-battle-works/*`
+- `src/components/custom-world-home/creationWorkShelf.ts`
+- `src/services/publicWorkCode.ts`
+
+---
+
+## 6. 风险、取舍与开放问题
+
+### 风险
+
+1. **麦克风权限和移动端 AudioContext 差异大。** 需要 mock input 保底，否则自动化和本地开发会被真实设备阻塞。
+2. **第一阶段过早引入 Phaser 可能拖慢验证。** 当前仓库没有 `phaser` 依赖；建议先用 DOM/Canvas 跑通玩法，再决定是否引入 Phaser。
+3. **AI 草稿和正式发布配置容易漂移。** Phase 2 临时 TS 类型必须在 Phase 3 与 Rust shared-contracts 对齐。
+4. **不能保存原始音频。** 后端阶段只能保存派生指标，任何音频片段、波形、频谱明细都不应落库。
+5. **入口配置事实源在后端/SpacetimeDB。** Phase 2 接入口时不要恢复旧前端静态入口配置。
+
+### 取舍
+
+- Phase 1 先把“游戏是否好玩、功能是否跑通”作为第一目标，不追求正式作品闭环。
+- Phase 2 让 AI 生成内容配置，而不是让 AI 直接生成任意代码或不受控规则。
+- Phase 3 再把正式业务真相交给后端，避免前端 runtime 先背上发布、成绩、排行榜的复杂度。
+
+### 开放问题
+
+1. Phase 1 是否必须使用 Phaser？如果只是验证玩法，可先使用 DOM/CSS/Canvas 原型，后续再替换 renderer。
+2. `bark-battle` 的正式中文名是否固定为“汪汪声浪大作战”？如果名称要改，需先统一文档、入口配置和分享标题。
+3. AI 创作阶段是否需要生成图片/狗狗视觉资产，还是只生成风格描述和使用占位素材？
+4. 是否需要排行榜作为 Phase 3 必选，还是作为数据库落地后的增强项？
+5. 真实麦克风 smoke 需要哪些目标设备：Chrome 桌面、Android Chrome、iOS Safari 是否都纳入首批验收？
+
+---
+
+## 7. 建议执行方式
+
+1. 先按 Phase 1 执行，且每个 domain/application task 坚持 TDD：先失败测试，再实现。
+2. Phase 1 合并前不要接数据库，不要新增后端表，不要把入口配置切到 open。
+3. Phase 1 验证通过后，让产品/团队试玩 `/bark-battle`，确认玩法数值和 UI 方向。
+4. 再进入 Phase 2，把 AI 创作工作台接到同一个 runtime draft config。
+5. 最后进入 Phase 3，按后端 DDD 文档做数据库、发布、成绩和追踪闭环。
+

.hermes/plans/2026-05-11_195214-k6-works-list-load-test-plan.md

@@ -0,0 +1,310 @@
+# K6 作品列表压测计划（使用 spacetime-migration-7.json 作为数据源）
+
+## 目标
+
+使用 K6 对 Genarrative 的“作品列表”相关接口进行压测，并将用户提供的 `spacetime-migration-7.json` 作为压测数据源；数据处理时**只导入作品列表相关数据**，不导入用户、会话、钱包、埋点、运行存档等非作品表，避免把敏感或无关数据带入压测环境。
+
+## 当前上下文
+
+- 工作区：`/c/proj/Genarrative`
+- 原始迁移文件：`C:\Users\DSK\AppData\Local\hermes\cache\documents\doc_150e84029b2d_spacetime-migration-7.json`
+- 已确认原始迁移文件结构：
+  - `schema_version = 1`
+  - `tables = 53`
+  - 作品相关表中当前有数据的重点表：
+    - `puzzle_work_profile`：80 行
+    - `custom_world_profile`：1 行
+    - `match3d_work_profile`：0 行
+    - `big_fish_*`：当前样本中相关表为 0 行
+  - 原始文件还包含 `user_account`、`auth_identity`、`refresh_session`、`profile_wallet_ledger`、`asset_object`、运行记录等数据，压测导入时必须过滤。
+- 当前仓库未发现现成 K6 脚本或 `k6` 相关文件，需要新增压测脚本与数据提取脚本。
+- `package.json` 当前有 `dev/dev:rust/test/check` 等脚本，未发现 K6 npm script。
+
+## 范围约束
+
+### 本次只导入/使用
+
+1. 作品列表表：
+   - `puzzle_work_profile`
+   - `custom_world_profile`
+   - 后续若接口覆盖其他玩法，可扩展：
+     - `match3d_work_profile`
+     - `square_hole_work_profile`（以实际 SpacetimeDB 表名为准）
+     - `big_fish_work_profile`（以实际 SpacetimeDB 表名为准）
+     - `visual_novel_work_profile`（以实际 SpacetimeDB 表名为准）
+2. 为作品列表卡片展示所需的最小字段：
+   - 稳定 ID：`profile_id`、`work_id` 或 `public_work_code`
+   - 标题：`work_title` / `level_name` / `world_name`
+   - 描述：`work_description` / `summary` / `summary_text` / `subtitle`
+   - 作者：`owner_user_id`、`author_display_name`、`author_public_user_code`
+   - 封面：`cover_image_src`、`cover_asset_id`（如果接口只返回 asset id，则压测阶段不额外导入二进制 asset）
+   - 状态与计数：`publication_status`、`published_at`、`play_count`、`like_count`、`remix_count`
+   - 作品内容摘要：`levels_json`、`profile_payload_json`、`theme_tags_json` 等列表渲染或进入作品详情可能需要的 JSON 字段
+
+### 本次不导入/不使用
+
+- 认证与账号：`user_account`、`auth_identity`、`refresh_session`、`auth_store_snapshot`
+- 用户资产与钱包：`profile_wallet_ledger`、`profile_dashboard_state`、`profile_redeem_*`、`profile_invite_*`
+- 游玩历史/存档/运行态：`profile_played_world`、`public_work_play_daily_stat`、`puzzle_runtime_run`、`profile_save_archive`、`runtime_snapshot` 等
+- AI 任务过程：`ai_task`、`ai_task_stage`、`ai_text_chunk`
+- asset 二进制与绑定：`asset_object`、`asset_entity_binding`，除非后续确认作品列表接口强依赖它们；即便需要，也只导入作品列表封面所需的最小 metadata，不导入原始大对象。
+
+## 推荐目录与文件
+
+建议新增：
+
+```text
+.hermes/plans/2026-05-11_195214-k6-works-list-load-test-plan.md  # 本计划
+scripts/loadtest/extract-works-list-data.mjs                     # 从迁移文件提取作品列表数据
+scripts/loadtest/k6-works-list.js                                # K6 压测脚本
+scripts/loadtest/data/works-list.sample.json                     # 过滤后的样例数据（不要提交敏感原始迁移全量）
+scripts/loadtest/README.md                                       # 执行说明与指标阈值
+```
+
+可选新增 npm scripts：
+
+```json
+{
+  "loadtest:extract-works": "node scripts/loadtest/extract-works-list-data.mjs",
+  "loadtest:k6:works": "k6 run scripts/loadtest/k6-works-list.js"
+}
+```
+
+## 数据提取方案
+
+### 输入
+
+默认读取：
+
+```bash
+node scripts/loadtest/extract-works-list-data.mjs \
+  --input "C:/Users/DSK/AppData/Local/hermes/cache/documents/doc_150e84029b2d_spacetime-migration-7.json" \
+  --output scripts/loadtest/data/works-list.local.json
+```
+
+### 输出结构
+
+建议输出为 K6 直接可读的 JSON：
+
+```json
+{
+  "source": "spacetime-migration-7.json",
+  "generatedAt": "<iso datetime>",
+  "tables": {
+    "puzzle_work_profile": [
+      {
+        "profile_id": "...",
+        "work_id": "...",
+        "owner_user_id": "...",
+        "work_title": "...",
+        "work_description": "...",
+        "publication_status": "Published",
+        "published_at": { "__timestamp_micros_since_unix_epoch__": 0 },
+        "play_count": 0,
+        "like_count": 0,
+        "levels_json": "..."
+      }
+    ],
+    "custom_world_profile": []
+  },
+  "workIds": {
+    "puzzle": ["<profile_id>"],
+    "customWorld": ["<profile_id>"]
+  }
+}
+```
+
+### 过滤原则
+
+1. 按 `tables[].name` 白名单过滤，只保留作品 profile 表。
+2. 对每个 row 再按字段白名单过滤，避免误带账号、手机号、token、钱包流水等字段。
+3. 对特别大的字段进行处理：
+   - `cover_image_src` 如果是 `data:image/...base64`，默认替换为占位符或截断，避免压测数据文件过大。
+   - `levels_json`、`profile_payload_json` 保留原文，但可以记录大小；如果过大，再提供 `--compact` 选项只保留摘要。
+4. 输出 `.local.json` 默认加入 `.gitignore`；如果要提交样例数据，只提交脱敏/裁剪后的 `works-list.sample.json`。
+
+## K6 压测接口矩阵
+
+需要先确认本地 api-server 实际端口。默认以 `http://127.0.0.1:8787` 为例，实际运行时通过环境变量覆盖：
+
+```bash
+BASE_URL=http://127.0.0.1:<actual-api-port> k6 run scripts/loadtest/k6-works-list.js
+```
+
+初版建议覆盖以下“作品列表”读接口，具体路径以仓库服务端路由为准，实施时需要通过搜索 api-server 路由确认：
+
+| 场景 | 目的 | 候选路径 |
+| --- | --- | --- |
+| 拼图作品列表 | 作品列表主场景之一，当前数据量最多 | `/api/creation/puzzle/works` 或实际 puzzle works list route |
+| RPG/自定义世界作品列表 | 使用 `custom_world_profile` 数据 | `/api/creation/custom-world/works` 或实际 custom world works route |
+| 作品详情/启动前读取 | 模拟用户从列表点进作品 | `/api/creation/*/works/:profileId` 或 `/api/runtime/*/works/:profileId` |
+| 公开作品库 | 如果首页/发现页依赖 | `/api/runtime/*/works` 或 gallery/list route |
+
+> 注意：不要凭空固定 endpoint。实施阶段先用 `search_files` / 路由源码确认真实路径，再写入 K6 脚本。
+
+## K6 场景设计
+
+### 阶段 1：基线 smoke
+
+目的：确认脚本、数据和目标服务可用。
+
+```js
+export const options = {
+  scenarios: {
+    smoke: {
+      executor: 'constant-vus',
+      vus: 1,
+      duration: '30s'
+    }
+  },
+  thresholds: {
+    http_req_failed: ['rate<0.01'],
+    http_req_duration: ['p(95)<800']
+  }
+};
+```
+
+### 阶段 2：常规读压
+
+目的：模拟日常列表浏览。
+
+- `constant-vus`: 10/25/50 三档
+- 每个 VU 随机选择作品类型和列表分页参数
+- `sleep(0.5~2s)` 模拟用户停留
+- 阈值建议：
+  - `http_req_failed < 1%`
+  - `p95 < 800ms`
+  - `p99 < 1500ms`
+
+### 阶段 3：峰值/突刺
+
+目的：模拟首页入口或活动导致的作品列表突增。
+
+- `ramping-arrival-rate`
+- 从 5 RPS 增长到 100 RPS，维持 2~5 分钟，再降回
+- 单独输出 `checks`：列表接口状态码、响应 JSON shape、items 数量
+
+### 阶段 4：容量探索
+
+目的：找瓶颈，不作为每次回归必跑。
+
+- 每轮提升 RPS 或 VU
+- 观察：api-server CPU/内存、SpacetimeDB 日志、错误率、p95/p99
+- 一旦 `http_req_failed >= 5%` 或 p95 持续超过 2s，停止继续加压并记录容量点。
+
+## K6 脚本设计要点
+
+1. 使用 `SharedArray` 加载 `works-list.local.json`，避免每个 VU 重复解析大 JSON。
+2. 基于数据源里的 `profile_id` / `work_id` 随机抽样，保证请求覆盖真实作品 ID。
+3. 对列表接口添加分页/排序 query，例如：
+   - `?limit=20&offset=0`
+   - `?pageSize=20&cursor=...`（以真实 API 为准）
+4. 使用 `check()` 验证：
+   - HTTP 200
+   - 响应体是 JSON
+   - `items` 或 `works` 是数组
+   - 列表项包含 `profileId/profile_id`、标题字段、状态字段
+5. 使用 `Trend` / `Rate` 细分指标：
+   - `works_list_duration`
+   - `works_detail_duration`
+   - `works_list_shape_error_rate`
+6. 支持环境变量：
+
+```bash
+BASE_URL=http://127.0.0.1:8787 \
+WORKS_DATA=scripts/loadtest/data/works-list.local.json \
+SCENARIO=baseline \
+k6 run scripts/loadtest/k6-works-list.js
+```
+
+## 实施步骤
+
+1. **确认路由**
+   - 搜索 api-server / BFF 的作品列表路由。
+   - 明确各玩法对应 endpoint、鉴权要求、分页参数、返回字段。
+2. **实现数据提取脚本**
+   - 新增 `scripts/loadtest/extract-works-list-data.mjs`。
+   - 只按表白名单读取作品列表 profile 表。
+   - 对字段做白名单与脱敏/截断。
+   - 输出 `works-list.local.json`。
+3. **生成本地压测数据**
+   - 用用户提供的迁移文件生成 `scripts/loadtest/data/works-list.local.json`。
+   - 验证输出只包含作品表和作品字段。
+4. **实现 K6 脚本**
+   - 新增 `scripts/loadtest/k6-works-list.js`。
+   - 支持 `BASE_URL`、`WORKS_DATA`、`SCENARIO`。
+   - 覆盖列表接口，必要时增加详情/启动前读取接口。
+5. **新增执行说明**
+   - 在 `scripts/loadtest/README.md` 写明：安装 K6、启动本地 dev 栈、提取数据、运行 smoke/baseline/spike、查看结果。
+6. **本地验证**
+   - 启动 Genarrative dev 栈；注意端口可能漂移，使用实际 api-server 端口。
+   - 跑 smoke：`SCENARIO=smoke`。
+   - 确认失败率、p95、响应 shape。
+7. **可选集成 npm scripts**
+   - 如果团队希望标准化入口，再加入 `package.json` scripts。
+8. **记录结果**
+   - 将 smoke/baseline/spike 的结果摘要追加到 `scripts/loadtest/README.md` 或单独保存到 `.hermes/plans/` 的结果文档中。
+
+## 启动与运行建议
+
+本地服务启动按当前 Genarrative dev 栈约定：
+
+```bash
+npm run dev
+```
+
+如果 SpacetimeDB/API/Vite 端口被占用，项目脚本会寻找可用端口；压测时必须从启动日志中读取实际 api-server 地址，并传给 K6：
+
+```bash
+BASE_URL=http://127.0.0.1:<actual-api-port> \
+WORKS_DATA=scripts/loadtest/data/works-list.local.json \
+SCENARIO=smoke \
+k6 run scripts/loadtest/k6-works-list.js
+```
+
+## 验证标准
+
+### 数据源验证
+
+- `works-list.local.json` 中只出现作品 profile 表。
+- 不出现以下字段或内容：
+  - `password_hash`
+  - `refresh_token_hash`
+  - `phone_number_e164`
+  - `phone_number_masked`
+  - `wallet_ledger_id`
+  - `auth_identity`
+  - `user_account`
+- `puzzle_work_profile` 行数应接近原始文件中的 80 行。
+- `custom_world_profile` 行数应接近原始文件中的 1 行。
+
+### K6 smoke 验证
+
+- 所有目标接口返回 2xx。
+- `http_req_failed < 1%`。
+- 响应 JSON shape 与 shared contracts 对齐：`items` 或 `works` 数组。
+- K6 输出中能区分不同 endpoint 的耗时。
+
+### 性能阈值初稿
+
+- Smoke：`p95 < 800ms`，失败率 `< 1%`
+- Baseline：`p95 < 1000ms`，`p99 < 2000ms`，失败率 `< 1%`
+- Spike：允许短暂 p95 抖动，但 1 分钟内应恢复；失败率 `< 5%`
+
+阈值后续需要结合本地机器性能、SpacetimeDB 本地模式和正式部署规格调整。
+
+## 风险与注意事项
+
+1. **原始迁移文件包含敏感数据。** 必须只提取作品列表白名单字段，禁止把原始 JSON 全量提交到仓库。
+2. **base64 封面可能导致压测数据膨胀。** 默认截断或替换为占位符，除非本次明确要测封面 payload 对响应体积的影响。
+3. **本地 SpacetimeDB 与 api-server 端口会漂移。** 不要硬编码端口，运行时通过 `BASE_URL` 注入。
+4. **列表接口可能需要鉴权。** 若实际接口要求登录，不要导入真实 refresh session；应使用本地测试账号或专门的压测 token 生成流程。
+5. **作品表名/接口路径可能与候选名称不完全一致。** 实施前必须以源码路由为准。
+6. **本计划仅保存压测方案，不执行实际压测。** 后续执行时再创建/修改脚本、导出过滤数据、跑 K6 并记录结果。
+
+## 开放问题
+
+1. 压测目标是本地 dev 栈、测试环境，还是预发/生产只读接口？不同环境阈值和安全边界不同。
+2. “作品列表”是否只包含拼图和自定义世界，还是要覆盖 match3d、square-hole、big-fish、visual-novel 的统一列表入口？
+3. 是否允许使用专门压测账号/token？如果接口无鉴权则无需处理。
+4. 是否需要测封面/asset 加载，还是只测作品列表 JSON API？

.hermes/plans/2026-05-11_205645-genarrative-disaster-recovery.md

@@ -0,0 +1,447 @@
+# Genarrative 容灾方案设计计划
+
+> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
+
+**Goal:** 基于当前 Genarrative 单机生产部署、Jenkins 流水线、SpacetimeDB 与 Rust `api-server` 架构，补齐一套可落地、可演练、可审计的容灾方案。
+
+**Architecture:** 首版容灾不引入复杂多活系统，优先围绕现有 `systemd + Nginx + SpacetimeDB + api-server + Jenkins` 单机生产推荐方案做“备份可恢复、版本可回滚、故障可切换、演练可复盘”。方案采用分层容灾：入口层、静态资源层、API 服务层、SpacetimeDB 数据层、外部服务与密钥层、Jenkins/发布链路层。
+
+**Tech Stack:** Nginx、systemd、SpacetimeDB self-hosting、Rust `api-server` / Axum、Jenkins Pipeline、Shell/Node.js 运维脚本、仓库 `deploy/` 与 `docs/technical/` 文档体系。
+
+---
+
+## 1. 当前上下文与已确认事实
+
+### 1.1 当前生产部署口径
+
+来自 `docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md` 的现状：
+
+- 生产为单机推荐方案，不使用 Docker。
+- 公网入口为 Nginx，负责 HTTPS、静态站点、后台静态页面、维护页、`/admin/api/` 与临时 `/api/*` 反向代理。
+- SpacetimeDB 作为 systemd 服务运行：
+  - `spacetimedb.service`
+  - 监听：`127.0.0.1:3101`
+  - 数据根目录：`/stdb`
+- Rust `api-server` 作为 systemd 服务运行：
+  - `genarrative-api.service`
+  - 监听：`127.0.0.1:8082`
+  - 环境文件：`/etc/genarrative/api-server.env`
+- 静态站点发布到 release/current 目录：
+  - `/opt/genarrative/releases/<version>/`
+  - `/opt/genarrative/current`
+  - `/srv/genarrative/web`
+- 已有维护模式：
+  - 开关文件：`/var/lib/genarrative/maintenance/enabled`
+  - API 发布、SpacetimeDB 模块发布、数据库导入、服务器配置变更必须进入维护模式。
+- 已有数据库导入导出 Jenkins Job：
+  - `Genarrative-Database-Export`
+  - `Genarrative-Database-Import`
+  - 对应文件：`jenkins/Jenkinsfile.production-database-export`、`jenkins/Jenkinsfile.production-database-import`
+- 已有回滚基本口径：
+  - Web 回滚：切 `/srv/genarrative/web` 或 `/opt/genarrative/current` 到上一版本并 reload Nginx。
+  - API 回滚：切 `/opt/genarrative/current` 到上一版本并重启 `genarrative-api.service`。
+  - SpacetimeDB 模块回滚：发布上一版本 `spacetime_module.wasm`。
+  - 数据回滚：使用导入流水线恢复指定备份，必须进入维护模式。
+
+### 1.2 关键风险
+
+- 当前是单机生产拓扑，单机磁盘、系统盘、`/stdb`、Nginx 或公网 IP 故障会造成整体不可用。
+- SpacetimeDB 是核心业务真相，容灾重点必须围绕 `/stdb`、数据库导出产物、schema 迁移与导入验证。
+- `/etc/genarrative/api-server.env` 持有生产密钥，不能进入 Git，也不能写进普通备份明文归档。
+- Jenkins controller/agent 同时承担构建、发布、备份、导入导出编排；Jenkins 不可用时仍需要有最小人工恢复路径。
+- 外部 LLM、图片、语音、3D 网关不是本仓库可控系统，容灾只能做到配置降级、超时隔离、能力熔断与可观测告警。
+
+---
+
+## 2. 容灾目标
+
+### 2.1 恢复目标建议
+
+| 灾难类型 | 目标 RTO | 目标 RPO | 首版策略 |
+| --- | ---: | ---: | --- |
+| Web 静态资源发布失败 | 5 分钟 | 0 | release/current 原子切换回滚 |
+| API 发布失败 | 10 分钟 | 0 | 维护模式 + 上一版二进制回滚 |
+| SpacetimeDB wasm 发布失败 | 15 分钟 | 0 或按迁移前备份 | 发布前导出 + 上一版 wasm 回滚 |
+| 数据误写 / 迁移失败 | 30-60 分钟 | 最近一次导出点 | 导入流水线从备份恢复 |
+| 生产机磁盘损坏 | 2-4 小时 | 最近一次异地备份 | 新机器 provision + 拉取 release 包 + 恢复数据库 |
+| Jenkins controller 不可用 | 1-2 小时 | 不影响线上数据 | 手工脚本恢复 + Jenkins 备份恢复 |
+| 第三方模型网关不可用 | 5-15 分钟内降级 | 不丢核心数据 | 配置切换 / 功能熔断 / 队列失败可重试 |
+
+### 2.2 首版不做
+
+- 不做跨地域双活写入。
+- 不做 SpacetimeDB 在线主从复制，除非后续官方能力与项目压测验证支持。
+- 不让前端绕过 `api-server` 直接承担正式业务真相。
+- 不把生产密钥、Token、数据库 dump、Jenkins secret 写入 Git。
+- 不恢复旧 `server-node`、Express、PostgreSQL 或 Docker 一体化部署方案。
+
+---
+
+## 3. 总体容灾设计
+
+### 3.1 分层策略
+
+1. **入口层：Nginx / DNS / HTTPS**
+   - 保留 Nginx 配置模板在 Git：`deploy/nginx/genarrative.conf`、`deploy/nginx/genarrative-dev-http.conf`。
+   - 为 release 环境建立 Nginx 配置备份与证书恢复流程。
+   - 明确 DNS 切换预案：生产机不可恢复时，将域名指向灾备机公网 IP。
+
+2. **静态资源层：Web / Admin Web**
+   - 依赖 `web.tar.gz`、`web.tar.gz.sha256`、`release-manifest.json`。
+   - 保留最近 N 个 release 目录与构建产物指针。
+   - 回滚只切软链，不重新构建。
+
+3. **API 服务层：Rust `api-server`**
+   - 依赖归档的 `api-server` 二进制、checksum、`release-manifest.json`。
+   - `/etc/genarrative/api-server.env` 通过加密备份或密钥管理恢复，不进入 release 包。
+   - systemd unit 由 `deploy/systemd/genarrative-api.service` 重新安装。
+
+4. **数据层：SpacetimeDB**
+   - 每次高风险发布前强制导出数据库。
+   - 定时导出：建议每天至少 1 次；高活跃期可每 4 小时 1 次。
+   - 导出产物同时保存在：Jenkins 归档 + 生产机 `SERVER_BACKUP_DIRECTORY` + 异地对象存储/备份机。
+   - 导入前自动生成安全备份，保留当前实现口径。
+
+5. **发布编排层：Jenkins**
+   - Jenkins Job、Jenkinsfile 在 Git 中可恢复。
+   - Jenkins controller 配置、凭据、插件清单需要额外备份。
+   - 发布 agent 使用 inbound + systemd 自恢复，agent secret 仅存在目标机或 Jenkins 凭据。
+
+6. **密钥与外部服务层**
+   - `/etc/genarrative/api-server.env`、Jenkins Secret Text、SSH PEM、agent secret 不进 Git。
+   - 制定密钥清单和恢复责任人，但不在仓库记录明文。
+   - 外部服务配置按 `docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md` 维护必配项。
+
+---
+
+## 4. 建议新增/更新的文档
+
+### Task 1: 新增生产容灾技术方案文档
+
+**Objective:** 形成团队可共享、可执行的容灾总纲。
+
+**Files:**
+- Create: `docs/technical/PRODUCTION_DISASTER_RECOVERY_PLAN_2026-05-11.md`
+- Modify: `docs/technical/README.md`（若已有技术索引，应加入该文档入口）
+- Optional Modify: `.hermes/shared-memory/project-overview.md`（只加稳定索引，不写敏感信息）
+
+**文档必须覆盖：**
+
+1. 容灾目标：RTO/RPO 表。
+2. 生产资产清单：Nginx、systemd、release/current、`/stdb`、`/etc/genarrative/api-server.env`、Jenkins、构建产物。
+3. 备份策略：
+   - 数据库导出。
+   - release 产物保留。
+   - Nginx/systemd/env 配置备份。
+   - Jenkins 配置备份。
+4. 恢复流程：
+   - Web 回滚。
+   - API 回滚。
+   - Stdb module 回滚。
+   - 数据恢复。
+   - 整机重建。
+5. 演练计划：每月一次数据库恢复演练，每季度一次整机重建演练。
+6. 安全边界：密钥不进 Git，备份加密，最小权限。
+7. 验收命令与人工检查清单。
+
+**Verification:**
+
+```bash
+npm run check:encoding
+```
+
+Expected: PASS，无中文乱码、无 BOM/CRLF 问题。
+
+---
+
+## 5. 建议新增/更新的脚本与流水线
+
+### Task 2: 增强数据库定时备份流水线
+
+**Objective:** 把现有人工导出扩展为可定时执行、可异地保存、可审计的备份流程。
+
+**Files:**
+- Modify: `jenkins/Jenkinsfile.production-database-export`
+- Modify: `docs/technical/PRODUCTION_DISASTER_RECOVERY_PLAN_2026-05-11.md`
+- Optional Create: `scripts/deploy/production-backup-sync.sh`
+
+**Implementation notes:**
+
+- 在 Jenkins Job 中保留人工触发能力，同时建议配置 cron：
+  - development：每天凌晨。
+  - release：每天凌晨或业务低峰。
+- 增加备份命名规范：
+  - `spacetime-migration-<database>-<yyyyMMdd-HHmmss>-<source_commit>.json`
+- 增加 `SERVER_BACKUP_DIRECTORY` 默认建议：
+  - `/var/backups/genarrative/spacetimedb/<database>/`
+- 增加备份保留策略：
+  - 本机保留 7-14 天。
+  - 异地保留 30-90 天。
+- 如实现 `production-backup-sync.sh`，只做同步框架，不硬编码真实 bucket、账号、endpoint 或密钥。
+
+**Verification:**
+
+```bash
+bash -n scripts/deploy/production-backup-sync.sh
+npm run check:encoding
+```
+
+Expected: shell 语法通过；文档编码检查通过。
+
+---
+
+### Task 3: 增加灾备恢复 Runbook
+
+**Objective:** 在真正故障时不依赖临场推理，按清单执行恢复。
+
+**Files:**
+- Create: `docs/operations/PRODUCTION_DR_RUNBOOK_2026-05-11.md`
+- Modify: `docs/operations/README.md`（如果存在）
+
+**Runbook sections:**
+
+1. 故障分级：P0/P1/P2。
+2. 第一响应：
+   - 判断 Nginx 是否在线。
+   - 判断 `genarrative-api.service` 是否在线。
+   - 判断 `spacetimedb.service` 是否在线。
+   - 判断磁盘是否满。
+   - 判断 Jenkins agent 是否在线。
+3. 快速止血：
+   - 开维护模式。
+   - 禁止继续发布。
+   - 保留现场日志。
+4. 回滚流程：
+   - Web 回滚命令。
+   - API 回滚命令。
+   - Stdb wasm 回滚命令。
+5. 数据恢复流程：
+   - 选择备份。
+   - dry-run 导入。
+   - 确认导入。
+   - smoke test。
+6. 整机重建流程：
+   - 新机器 provision。
+   - 恢复 `/etc/genarrative/api-server.env`。
+   - 恢复 SpacetimeDB 数据。
+   - 发布最近稳定 release。
+   - DNS 切换。
+7. 复盘模板。
+
+**Verification:**
+
+```bash
+npm run check:encoding
+```
+
+Expected: PASS。
+
+---
+
+### Task 4: 增加备份健康检查与恢复演练记录模板
+
+**Objective:** 防止“有备份但不可恢复”。
+
+**Files:**
+- Create: `docs/operations/DR_DRILL_REPORT_TEMPLATE.md`
+- Optional Create: `scripts/deploy/verify-database-backup.sh`
+- Modify: `docs/technical/PRODUCTION_DISASTER_RECOVERY_PLAN_2026-05-11.md`
+
+**建议检查项：**
+
+- 备份文件存在且大小非 0。
+- 备份文件 checksum 可验证。
+- 备份文件可被 `Genarrative-Database-Import` dry-run 解析。
+- 最近一次备份时间未超过 RPO 阈值。
+- 导入后 `/healthz` 可用。
+- 首页、后台登录页、关键 API smoke 可用。
+
+**Verification:**
+
+```bash
+bash -n scripts/deploy/verify-database-backup.sh
+npm run check:encoding
+```
+
+Expected: PASS。
+
+---
+
+## 6. 具体恢复流程草案
+
+### 6.1 Web 静态资源回滚
+
+1. 进入目标机。
+2. 查看 release 目录：`/opt/genarrative/releases/`。
+3. 选择上一个稳定版本。
+4. 切换 `/srv/genarrative/web` 或 `/opt/genarrative/current` 软链。
+5. 执行 Nginx 配置检查与 reload。
+6. 访问首页与后台静态入口。
+
+验收：
+
+- `/` 返回最新稳定页面。
+- `/admin/` 返回后台页面。
+- 静态资源无 404。
+
+### 6.2 API 回滚
+
+1. 开维护模式。
+2. 切 `/opt/genarrative/current` 到上一版包含稳定 `api-server` 的 release。
+3. 重启 `genarrative-api.service`。
+4. 本机检查 `http://127.0.0.1:8082/healthz`。
+5. 检查 Nginx 反代路径。
+6. 解除维护模式。
+
+验收：
+
+- `systemctl status genarrative-api.service` 正常。
+- `/healthz` 正常。
+- 后台 `/admin/api/*` 基础接口正常。
+
+### 6.3 SpacetimeDB 模块回滚
+
+1. 开维护模式。
+2. 确认目标数据库名与当前 API 环境一致：`GENARRATIVE_SPACETIME_DATABASE`。
+3. 选择上一版 `spacetime_module.wasm`。
+4. 使用 `spacetimedb` 服务用户发布上一版 wasm。
+5. 重启或检查 `spacetimedb.service`。
+6. 检查 `api-server` 对目标数据库访问。
+7. 解除维护模式。
+
+注意：如果 schema 已迁移且旧 wasm 不兼容当前数据，需要走数据恢复，不应直接盲目发布旧 wasm。
+
+### 6.4 数据恢复
+
+1. 开维护模式。
+2. 从 Jenkins 归档或 `SERVER_BACKUP_DIRECTORY` 选择备份。
+3. 先执行导入 dry-run。
+4. 真正导入前生成当前数据库安全备份。
+5. 执行导入。
+6. 执行 smoke test。
+7. 解除维护模式。
+
+必须记录：
+
+- 备份文件名。
+- 来源 Job/build number。
+- 恢复目标 database。
+- 恢复开始/结束时间。
+- 恢复后验证结果。
+
+### 6.5 整机重建
+
+1. 准备新 Linux 机器。
+2. 接入 Jenkins release deploy agent，或准备人工 SSH 运维路径。
+3. 运行 `Genarrative-Server-Provision`：
+   - 创建用户和目录。
+   - 安装 SpacetimeDB。
+   - 安装 systemd unit。
+   - 安装 Nginx 配置。
+4. 恢复 `/etc/genarrative/api-server.env`。
+5. 发布最近稳定 Web/API/Stdb 产物。
+6. 导入最近一次有效数据库备份。
+7. smoke test。
+8. 切 DNS。
+9. 观察 30-60 分钟。
+
+---
+
+## 7. 文件可能变更清单
+
+首版落地建议按以下文件收口：
+
+- Create: `docs/technical/PRODUCTION_DISASTER_RECOVERY_PLAN_2026-05-11.md`
+- Create: `docs/operations/PRODUCTION_DR_RUNBOOK_2026-05-11.md`
+- Create: `docs/operations/DR_DRILL_REPORT_TEMPLATE.md`
+- Modify: `docs/technical/README.md`
+- Modify: `docs/operations/README.md`（若存在）
+- Modify: `.hermes/shared-memory/project-overview.md`（仅增加文档索引）
+- Optional Modify: `jenkins/Jenkinsfile.production-database-export`
+- Optional Modify: `jenkins/Jenkinsfile.production-database-import`
+- Optional Create: `scripts/deploy/production-backup-sync.sh`
+- Optional Create: `scripts/deploy/verify-database-backup.sh`
+
+---
+
+## 8. 测试与验收
+
+### 8.1 文档与编码
+
+```bash
+npm run check:encoding
+```
+
+Expected: PASS。
+
+### 8.2 Shell 脚本语法
+
+如新增 shell 脚本：
+
+```bash
+bash -n scripts/deploy/production-backup-sync.sh
+bash -n scripts/deploy/verify-database-backup.sh
+```
+
+Expected: PASS。
+
+### 8.3 Jenkinsfile 静态检查
+
+建议在 Jenkins UI 或本地 Jenkins Pipeline Linter 中检查：
+
+- `jenkins/Jenkinsfile.production-database-export`
+- `jenkins/Jenkinsfile.production-database-import`
+
+Expected: Pipeline syntax valid。
+
+### 8.4 演练验收
+
+至少完成一次 development 目标演练：
+
+1. 触发 `Genarrative-Database-Export`。
+2. 确认备份产物存在并归档。
+3. 使用 `Genarrative-Database-Import` dry-run 验证备份可解析。
+4. 不覆盖生产数据的前提下，记录演练报告。
+
+release 目标演练应在业务低峰进行，并先确认通知渠道可用。
+
+---
+
+## 9. 风险、取舍与开放问题
+
+### 9.1 风险
+
+- 单机生产仍存在物理机级单点故障，首版只能通过“快速重建 + 异地备份”降低恢复时间。
+- SpacetimeDB schema 回滚不一定可逆，必须把发布前备份作为强约束。
+- Jenkins controller 若在本地 Windows，controller 自身备份和恢复需要单独制定，不应只依赖 agent 自恢复。
+- 外部模型网关失败可能影响创作能力，但不应影响已发布作品浏览和后台基础能力。
+
+### 9.2 取舍
+
+- 选择先做可执行 runbook 和备份恢复演练，而不是直接引入复杂多活。
+- 选择继续复用现有 Jenkins 导入导出流水线，降低工程改造风险。
+- 选择不把密钥恢复细节写死到 Git 文档，避免泄露。
+
+### 9.3 开放问题
+
+1. release 环境是否已经有独立备份机或对象存储？如果有，需要补充备份同步目标，但不能提交密钥。
+2. Jenkins controller 的 `JENKINS_HOME` 当前实际部署在哪里？是否已有周期备份？
+3. 生产域名 DNS TTL 当前是多少？是否可降低到适合故障切换的值？
+4. `/stdb` 所在磁盘是否独立于系统盘？是否已有磁盘水位告警？
+5. release 环境的通知渠道除邮件外是否需要接入企业微信/飞书/Telegram？
+
+---
+
+## 10. 推荐实施顺序
+
+1. 先只落文档：技术方案 + runbook + 演练模板。
+2. 在 development 目标做一次数据库导出 + dry-run 导入演练。
+3. 根据演练结果补脚本：备份同步、备份健康检查。
+4. 再把 release 备份设置为定时任务。
+5. 最后规划整机重建演练与 DNS 切换演练。
+
+首版完成标准：
+
+- 团队任一成员打开 runbook，即可在 30 分钟内完成 Web/API 回滚或数据库备份 dry-run 恢复。
+- 最近一次数据库备份时间、备份位置、checksum、恢复演练结果可追溯。
+- 生产密钥仍只存在于服务器/Jenkins 凭据/加密备份中，不进入 Git。

.hermes/plans/2026-05-12_0616-remote-works-list-loadtest-diagnosis.md

@@ -0,0 +1,206 @@
+# 远端作品列表压测排查报告
+
+时间：2026-05-12 06:16 CST
+目标：`http://82.157.175.59`
+SSH：远端生产机 root 账号（具体私钥路径仅保留在本机环境，不写入仓库）
+
+## 背景
+
+远端 `k6-works-list.js` 压测中：
+
+- smoke 通过。
+- baseline 10 VU：无 HTTP 错误，但 p95/p99 超阈值。
+- 50 RPS spike：`http_req_failed` / `works_list_shape_error_rate` 约 21.99%。
+- 100 RPS spike：`http_req_failed` / `works_list_shape_error_rate` 约 25.47%。
+- 从 k6 check 看，失败主要集中在 `puzzle_gallery_list`，`custom_world_gallery_list` 基本正常。
+
+## 已完成排查
+
+### 1. 服务器进程与资源
+
+远端服务监听：
+
+- Rust api-server：`127.0.0.1:8082`，systemd 服务 `genarrative-api.service`。
+- SpacetimeDB：`127.0.0.1:3101`，systemd 服务 `spacetimedb.service`。
+- Nginx：公网 80 反代 `/api/*` 到 `127.0.0.1:8082`。
+
+服务器规格/状态：
+
+- 2 vCPU。
+- 内存约 1.9GiB。
+- Swap 约 1.9GiB，已有约 600MiB 使用。
+- `/` 磁盘约 69%。
+- Rust api-server 当前 CPU 不高。
+- SpacetimeDB 当前 CPU 不高。
+
+发现一个独立异常：
+
+- PM2 下旧 `server-node` 进程 `genarrative` 正在重启风暴。
+- cwd：`/work/Genarrative/server-node`
+- 错误：连接 `127.0.0.1:5432` PostgreSQL 被拒绝。
+- PM2 restart 次数已超过 33 万。
+- 该进程不是当前公网 `/api/*` 使用的 Rust api-server，但会制造额外 CPU/内存/日志抖动。
+
+### 2. 压测窗口服务端日志
+
+子任务聚合了 2026-05-12 04:50-05:05 的 nginx 与 api-server 日志。
+
+nginx access：
+
+- `/api/runtime/puzzle/gallery`：4661 次，全部 200。
+- `/api/runtime/custom-world-gallery`：4659 次，全部 200。
+
+api-server journal：
+
+`/api/runtime/puzzle/gallery`：
+
+- completed：4661
+- status：200 全部
+- slow_request：0
+- latency_ms：min 13 / p50 30 / p90 43 / p95 50 / p99 62 / max 88
+
+`/api/runtime/custom-world-gallery`：
+
+- completed：4659
+- status：200 全部
+- slow_request：0
+- latency_ms：min 0 / p50 1 / p90 5 / p95 7 / p99 13 / max 49
+
+结论：
+
+- 在服务端视角，两个接口在该窗口都没有 5xx，也没有慢请求。
+- 这与 k6 客户端侧 30s timeout / failed check 存在明显不一致。
+- 需要进一步区分：客户端侧网络/连接耗尽/本机 k6 执行环境问题，还是 k6 统计混合/响应解析问题。
+
+### 3. k6 脚本行为
+
+文件：`scripts/loadtest/k6-works-list.js`
+
+无 `AUTH_TOKEN` 时，每轮 iteration 顺序请求两个接口：
+
+1. `GET /api/runtime/puzzle/gallery`
+2. `GET /api/runtime/custom-world-gallery`
+
+`DETAIL_RATIO=0` 时不会请求详情。
+
+`works_list_shape_error_rate` 不只代表字段结构错误，只要下面任意 check 失败都会计入：
+
+- status is 200
+- returns json object
+- has collection
+- list item shape
+
+因此 timeout、非 JSON、非 200、响应结构不符合都会表现为 shape error。
+
+数据文件实际路径：
+
+- `scripts/loadtest/data/works-list.local.json`
+
+脚本里 `data/works-list.local.json` 是相对 k6 脚本文件解析的，因此本身合理。
+
+### 4. 代码层疑似瓶颈
+
+虽然这次远端服务端日志没有复现慢请求，但代码层仍发现一个真实性能隐患。
+
+`/api/runtime/puzzle/gallery` 调用链：
+
+- `server-rs/crates/api-server/src/app.rs:1192`
+- `server-rs/crates/api-server/src/puzzle.rs:1385-1409`
+- `server-rs/crates/spacetime-client/src/puzzle.rs:367-381`
+- `server-rs/crates/spacetime-module/src/puzzle.rs:430-443`
+- `server-rs/crates/spacetime-module/src/puzzle.rs:1393-1404`
+
+关键实现：
+
+- `list_puzzle_gallery_tx` 对 `puzzle_work_profile().iter()` 全表扫描。
+- 再过滤 `publication_status == Published`。
+- 对每个公开作品调用 `build_puzzle_work_profile_from_row_with_recent_count`。
+- 该函数调用 `count_recent_public_work_plays(ctx, "puzzle", &row.profile_id, now_micros)`。
+
+`count_recent_public_work_plays`：
+
+- 文件：`server-rs/crates/spacetime-module/src/runtime/profile.rs:1296-1321`
+- 当前实现对 `public_work_play_daily_stat().iter()` 全表扫描过滤。
+- 但表定义已有复合索引：
+  - `server-rs/crates/spacetime-module/src/runtime/profile.rs:242-248`
+  - `by_public_work_play_daily_stat_work_day(source_type, profile_id, played_day)`
+- 当前统计函数未使用该索引。
+
+复杂度风险：
+
+```text
+puzzle gallery ~= O(puzzle_work_profile 全表扫描 + Published作品数 * public_work_play_daily_stat 全表扫描)
+```
+
+`custom-world-gallery` 与 puzzle 的差异：
+
+- custom-world 使用 `CustomWorldGalleryEntry` 公开读模型表。
+- puzzle 直接从 `puzzle_work_profile` 即席拼装。
+- 两者都调用 recent count，但 puzzle 更容易受作品表规模和统计表规模影响。
+
+## 当前判断
+
+本次排查有两个层面的结论：
+
+1. 生产服务端日志没有证明 `puzzle/gallery` 在 04:50-05:05 窗口真的 30s 慢或 5xx。
+   - api-server 记录的 p95 只有 50ms。
+   - nginx 看到两个接口都是 200。
+   - 所以 k6 侧的 30s timeout 需要进一步从客户端网络、连接池、Windows/k6 执行环境、summary 混合统计角度验证。
+
+2. 代码层确实存在可修的性能隐患。
+   - `count_recent_public_work_plays` 未使用已有索引。
+   - puzzle gallery 对每个作品重复做 recent count。
+   - puzzle gallery 未使用 `publication_status` 索引或读模型。
+
+## 建议下一步
+
+### A. 先处理服务器 PM2 重启风暴
+
+建议确认旧 Node 服务是否仍需要。
+
+如果不需要，应停止并禁用 PM2 中的旧 `server-node`：
+
+```bash
+PM2_HOME=/home/ubuntu/.pm2 pm2 stop genarrative
+PM2_HOME=/home/ubuntu/.pm2 pm2 delete genarrative
+PM2_HOME=/home/ubuntu/.pm2 pm2 save
+```
+
+这是生产侧操作，执行前需要确认。
+
+### B. 单接口短压验证客户端/服务端不一致
+
+不要继续用混合脚本大压。
+
+建议新增或临时使用单接口 k6 脚本，分别只测：
+
+- `/api/runtime/puzzle/gallery`
+- `/api/runtime/custom-world-gallery`
+
+并在同一时间窗口并行采集：
+
+- k6 客户端 summary
+- nginx access 请求数/状态码
+- api-server journal latency
+- 本机到服务器网络错误/timeout
+
+目标是确认 timeout 是不是发生在客户端侧连接/网络，而不是服务端处理慢。
+
+### C. 修复代码性能隐患
+
+优先级建议：
+
+1. `count_recent_public_work_plays` 改为使用 `by_public_work_play_daily_stat_work_day` 复合索引，或至少改成批量统计，避免 N 次全表扫描。
+2. `list_puzzle_gallery_tx` 使用 `by_puzzle_work_publication_status` 索引查询 Published，或参考 custom-world 建立 `puzzle_gallery_entry` 公开读模型。
+3. gallery 列表页不要实时逐条扫描统计表，可维护读模型或批量聚合 `recent_play_count_7d`。
+
+### D. 调整 k6 脚本输出
+
+建议 k6 summary 按 endpoint tag 输出或新增单接口模式，否则 overall 指标会把 puzzle/custom-world 混在一起。
+
+建议增加：
+
+- `ENDPOINT=puzzle_gallery_list`
+- `ENDPOINT=custom_world_gallery_list`
+
+让脚本只跑一个 endpoint，避免诊断时混淆。

.hermes/plans/2026-05-13_112225-visual-novel-one-line-genarrative-plan.md

@@ -0,0 +1,343 @@
+# Genarrative 视觉小说“一句话生成”最小闭环落地计划
+
+生成时间：2026-05-13 11:22
+工作区：`C:/proj/Genarrative/.worktrees/hermes-visual-novel`
+参考文档：`C:/Users/DSK/Documents/Interactive-fiction/一句话生成视觉小说整体流程总结.md`
+
+## 1. 目标
+
+把 Interactive-fiction 总结文档中的“一句话生成视觉小说”流程，映射并落地到 Genarrative 现有视觉小说能力中，优先做成一个可端到端验证的最小闭环：
+
+1. 用户在视觉小说入口输入一句话并选择画风。
+2. 前端进入生成过程页，展示分阶段进度。
+3. 后端创建视觉小说创作会话，并基于 seedText 生成 `VisualNovelResultDraft`。
+4. 生成完成后进入草稿结果页，可看到世界观、角色、场景、剧情阶段、开场选择。
+5. 草稿可编译/保存为作品 profile，并进入视觉小说运行态测试/正式游玩。
+
+本计划只覆盖 Genarrative 内部最小闭环，不引入 Interactive-fiction 原项目的独立 TXT 播放记录、分享播放包、外部活动运营、独立账号/交易/资产系统。
+
+## 2. 当前上下文与已发现实现
+
+### 2.1 Interactive-fiction 总结文档提炼
+
+参考文档将整体流程分为：
+
+- 输入侧：一句话创意、主题/风格、可选文档或素材。
+- 生成侧：理解意图、扩展世界观、角色、场景、剧情阶段、开场与选择。
+- 编辑侧：草稿页可查看和调整生成结果。
+- 运行侧：从草稿进入视觉小说游玩，支持剧情推进、玩家选择、历史与状态。
+- 资产侧：角色立绘、背景、音乐/音效可作为后续增强，最小闭环可先使用文字描述与空资产占位。
+
+### 2.2 Genarrative 已有实现基础
+
+已确认项目中视觉小说相关能力并非从零开始：
+
+- 前端入口表单：
+  - `src/components/visual-novel-creation/VisualNovelAgentWorkspace.tsx`
+  - 已有“一句话创作” textarea、6 个视觉画风选项、提交按钮“生成视觉小说草稿”。
+- 前端入口 payload/progress：
+  - `src/components/visual-novel-creation/visualNovelEntryGeneration.ts`
+  - 已有 `VisualNovelEntryFormPayload`、锚点展示、一句话/画风生成进度步骤。
+- 前端平台主流程：
+  - `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+  - 已接入 `createVisualNovelDraftFromForm`，会创建 session、stream message、进入 `visual-novel-generating`，完成后进入 `visual-novel-result`。
+- 前端 API client：
+  - `src/services/visual-novel-creation/visualNovelCreationClient.ts`
+  - 已封装 session/message/action/compile 接口。
+- 共享契约：
+  - `packages/shared/src/contracts/visualNovel.ts`
+  - 已定义 `VisualNovelResultDraft`、world/characters/scenes/storyPhases/opening/runtimeConfig/work/run/history 等结构。
+- 后端 API：
+  - `server-rs/crates/api-server/src/visual_novel.rs`
+  - 已有创建 session、发消息、流式消息、执行 action、compile、work、runtime run 等接口。
+- 后端 prompt：
+  - `server-rs/crates/api-server/src/prompt/visual_novel.rs`
+  - 已有 `VISUAL_NOVEL_CREATION_SYSTEM_PROMPT`、结构化输出契约、runtime GM prompt、repair prompt。
+- SpacetimeDB 模块：
+  - `server-rs/crates/spacetime-module/src/visual_novel.rs`
+  - 已有 session/message/work/run/history/event 表与 procedure。
+- 文档参考：
+  - `docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`
+  - `docs/technical/VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md`
+  - `docs/technical/VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md`
+
+### 2.3 关键实现判断
+
+当前项目已经实现了视觉小说的主要骨架，本次不应大规模重写。更合理的落地方式是补齐“一句话生成”闭环中最容易断裂的点：
+
+- 入口输入与画风信息是否被稳定传给后端 prompt。
+- 后端生成 draft 后是否自动保存/关联可编辑 work profile。
+- 生成过程页是否能清晰展示 Interactive-fiction 文档中提到的阶段。
+- 结果页是否有足够的字段展示与继续游玩入口。
+- 运行态是否能基于 opening/choices 正常启动，而不依赖尚未生成的图片/音乐资产。
+
+## 3. 拟采用方案
+
+### 3.1 最小闭环范围
+
+本次优先实现：
+
+1. “一句话 + 视觉画风”作为 `sourceMode: 'idea'` 的 seedText。
+2. 后端生成完整 `VisualNovelResultDraft`，包括：
+   - world
+   - 3-6 个角色
+   - 3-8 个场景
+   - 3-6 个剧情阶段
+   - opening narration/firstDialogue/2-4 个 choices
+   - runtimeConfig
+3. 若 LLM 输出失败，使用 repair 或确定性 fallback，保证可回到草稿页并显示错误/警告。
+4. 结果页支持保存/编译为 work profile。
+5. work profile 支持启动 runtime run，opening 能展示初始场景、旁白、对话和选择。
+
+暂不做或仅预留：
+
+- 真实图片/音乐生成队列。
+- 多文档解析导入的完整链路。
+- 复杂分镜/节点图编辑器。
+- 外部 Interactive-fiction 项目的播放器、TXT 记录包、分享活动、独立账号系统。
+
+### 3.2 与 Genarrative 架构的映射
+
+| Interactive-fiction 概念 | Genarrative 落点 |
+| --- | --- |
+| 一句话创意 | `VisualNovelEntryFormPayload.ideaText` / `seedText` |
+| 画风/主题 | `seedText` 中的“视觉画风/画风要求”，后续可结构化为 metadata |
+| 世界观设定 | `VisualNovelResultDraft.world` |
+| 角色设定 | `VisualNovelResultDraft.characters` |
+| 场景设定 | `VisualNovelResultDraft.scenes` |
+| 剧情阶段/章节 | `VisualNovelResultDraft.storyPhases` |
+| 开场文本与选项 | `VisualNovelResultDraft.opening` |
+| 运行时剧情推进 | `VisualNovelRuntimeStep[]` + run snapshot/history |
+| 发布/作品库 | `VisualNovelWorkProfileRecord` / works API |
+
+## 4. 分步计划
+
+### Step 1：补齐入口 payload 与生成过程语义
+
+涉及文件：
+
+- `src/components/visual-novel-creation/VisualNovelAgentWorkspace.tsx`
+- `src/components/visual-novel-creation/visualNovelEntryGeneration.ts`
+- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+
+任务：
+
+1. 保持现有 6 个画风选项，但确认每个 option 的 prompt 会进入 `seedText`。
+2. 将生成过程阶段从当前 3 步细化为更贴合参考文档的 4-5 步，例如：
+   - 理解一句话创意
+   - 扩展世界观与玩家身份
+   - 设计角色/场景/剧情阶段
+   - 生成开场与选择
+   - 准备可编辑草稿
+3. 生成过程页的 anchor 保留“一句话”和“视觉画风”，必要时增加“生成目标：视觉小说草稿”。
+4. 确认 `createVisualNovelDraftFromForm` 对失败状态会保留返回入口/重试能力。
+
+验收点：提交一句话后能进入 `visual-novel-generating`，看到阶段进度；完成后进入 `visual-novel-result`。
+
+### Step 2：增强后端 creation prompt 与 fallback 约束
+
+涉及文件：
+
+- `server-rs/crates/api-server/src/prompt/visual_novel.rs`
+- `server-rs/crates/api-server/src/visual_novel.rs`
+- 如已有 domain crate：`server-rs/crates/module-visual-novel/**` 或相关 normalize/validate 文件
+
+任务：
+
+1. 在 creation prompt 中显式吸收 Interactive-fiction 的“一句话生成”目标：
+   - 从 seedText 提取核心创意、视觉风格、故事类型。
+   - 生成可直接运行的 opening 和 choices。
+   - 图片/音乐资产先置 null，但必须有可生成图像的描述。
+2. 强化输出约束：
+   - `opening.sceneId` 必须指向存在且 availability 为 `opening` 的 scene。
+   - `opening.initialChoices` 必须 2-4 个。
+   - `storyPhases[0]` 必须包含 opening scene 和主要角色。
+   - `publishReady` 的判定与 validationIssues 一致。
+3. 检查 `submit_visual_novel_message_turn` / `resolve_action_draft` / compile 相关代码：
+   - 如果 LLM 失败，是否已有 fallback；没有则补确定性 fallback draft。
+   - 如果 draft 不完整，是否会 normalize/repair 并写入 session。
+4. 保留现有“不要输出旧 TXT 播放记录、分享播放包、外部商业字段”的约束，避免把参考项目的外部概念误并入 Genarrative。
+
+验收点：后端给定 seedText 时，返回 session.draft 不为空且满足共享契约。
+
+### Step 3：确认草稿结果页、保存/编译与作品库链路
+
+涉及文件：
+
+- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+- `src/components/visual-novel-creation/**`
+- `src/services/visual-novel-works*` 或相关 visual novel works client
+- `server-rs/crates/api-server/src/visual_novel.rs`
+- `packages/shared/src/contracts/visualNovel.ts`
+
+任务：
+
+1. 查找并确认 `visual-novel-result` 页面组件：
+   - 是否显示 workTitle/workDescription/world/characters/scenes/storyPhases/opening。
+   - 是否有保存/发布/开始试玩按钮。
+2. 确认 `compileVisualNovelWorkProfile` 或 `executeVisualNovelAction({kind:'compile_work_profile'})` 会生成/更新 work profile。
+3. 确认作品架上使用 `profileId` 而不是 sessionId 作为稳定作品 ID。
+4. 如果结果页缺少“一句话来源/画风”的可视化提示，可在结果页或 summary 中补轻量展示，避免用户以为画风丢失。
+
+验收点：生成完成后能保存为作品；作品出现在“我的作品/创作架”；再次打开能读取同一 draft。
+
+### Step 4：确认运行态 opening 闭环
+
+涉及文件：
+
+- `src/components/visual-novel-runtime/**`
+- `src/services/visual-novel-runtime*`
+- `server-rs/crates/api-server/src/visual_novel.rs`
+- `server-rs/crates/api-server/src/prompt/visual_novel.rs`
+- `packages/shared/src/contracts/visualNovel.ts`
+
+任务：
+
+1. 启动 visual novel work run 时，优先使用 `draft.opening` 生成第一轮 runtime snapshot/history。
+2. 如果没有图片/音乐，前端 runtime shell 必须可用文字 fallback，不应白屏或阻断游玩。
+3. 玩家选择 `choice` 后，后端 runtime GM prompt 生成下一轮 `VisualNovelRuntimeStep[]`。
+4. 确认正式游玩入口调用 `work_play_start`，并满足已有埋点约定：
+   - `scope_kind=work`
+   - `scope_id=稳定作品 ID`
+   - metadata 包含 `playType/workId/sourceRoute/userId` 等。
+
+验收点：从生成出的作品进入运行态，能看到 opening 并点击至少一个选择推进一轮。
+
+### Step 5：补测试与文档
+
+涉及文件：
+
+- 前端测试：按仓库现有测试布局查找 `*.test.ts` / `*.test.tsx`
+- Rust 测试：`server-rs/crates/api-server/src/**` 或 domain crate tests
+- 文档：可追加到 `docs/technical/` 或 `.hermes/shared-memory/decision-log.md`（如团队约定需要）
+
+建议测试：
+
+1. TypeScript 单元测试：
+   - `buildVisualNovelEntryGenerationProgress` 阶段输出。
+   - `buildVisualNovelEntryGenerationAnchorEntries` 能展示一句话和画风。
+2. Rust 单元测试：
+   - creation prompt 包含 seedText、sourceMode、输出契约。
+   - draft normalize/fallback 能生成合法 opening/choices。
+   - runtime opening 或 first-step 构造不依赖图片/音乐。
+3. 集成/手工测试文档：
+   - 访问平台视觉小说入口。
+   - 输入一句话。
+   - 选择画风。
+   - 点击生成。
+   - 查看结果页。
+   - 保存作品。
+   - 启动试玩并点击选择。
+
+## 5. 可能改动文件清单
+
+高概率改动：
+
+- `src/components/visual-novel-creation/VisualNovelAgentWorkspace.tsx`
+- `src/components/visual-novel-creation/visualNovelEntryGeneration.ts`
+- `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+- `server-rs/crates/api-server/src/prompt/visual_novel.rs`
+- `server-rs/crates/api-server/src/visual_novel.rs`
+- `packages/shared/src/contracts/visualNovel.ts`
+
+中概率改动：
+
+- `src/components/visual-novel-runtime/**`
+- `src/services/visual-novel-creation/**`
+- `src/services/visual-novel-runtime/**`
+- `src/services/visual-novel-works/**`
+- `server-rs/crates/spacetime-module/src/visual_novel.rs`
+- `server-rs/crates/spacetime-client/**` 生成/绑定文件，若 SpacetimeDB contract 需要更新
+
+低概率/仅文档：
+
+- `docs/technical/VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md`
+- `docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`
+- `.hermes/shared-memory/decision-log.md`
+
+## 6. 验证计划
+
+### 6.1 静态检查
+
+在 worktree 根目录执行：
+
+```bash
+npm run typecheck
+```
+
+如仓库无统一 typecheck，则按 package scripts 选择最接近的前端类型检查命令。
+
+### 6.2 前端定向测试
+
+优先运行与 visual novel / platform entry 相关测试，如存在：
+
+```bash
+npm test -- visual-novel
+npm test -- platform-entry
+```
+
+若仓库使用 vitest：
+
+```bash
+npm run test -- visual-novel
+```
+
+### 6.3 Rust 定向测试
+
+在 `server-rs` 下运行 visual novel 相关测试：
+
+```bash
+cargo test -p api-server visual_novel
+cargo test -p shared-contracts visual_novel
+```
+
+如改动 SpacetimeDB module：
+
+```bash
+cargo test -p spacetime-module visual_novel
+```
+
+### 6.4 人工验收步骤
+
+1. 启动本地 dev 栈。
+2. 访问 Genarrative 主站。
+3. 进入创作/视觉小说入口。
+4. 输入：`一个雨夜，失忆的高中生在旧图书馆发现一本会回应她心声的日记。`
+5. 选择任一画风，例如“映画动画”。
+6. 点击“生成视觉小说草稿”。
+7. 预期：进入生成过程页，能看到分阶段进度。
+8. 预期：完成后进入草稿结果页，包含标题、简介、世界观、角色、场景、剧情阶段和 opening choices。
+9. 点击保存/编译作品。
+10. 从作品入口进入试玩。
+11. 预期：opening 文本出现，至少 2 个选择可点击；点击后剧情继续推进一轮。
+
+## 7. 风险、权衡与开放问题
+
+### 7.1 风险
+
+- 现有视觉小说代码已较完整，贸然新增一套 parallel pipeline 会制造重复逻辑；应复用当前 `VisualNovelResultDraft` 与 creation agent flow。
+- LLM 输出不稳定可能导致草稿结构不完整；需要 normalize/repair/fallback 确保最小闭环。
+- 视觉/音乐资产生成未接入时，UI 必须接受 null asset，否则运行态可能白屏。
+- `PlatformEntryFlowShellImpl.tsx` 文件很大，改动需局部、谨慎，避免影响其他玩法入口。
+- 若改动 SpacetimeDB 表结构，可能牵涉 publish、client binding、清库/迁移；最小闭环阶段应尽量避免 schema 变更。
+
+### 7.2 权衡
+
+- 先让文字版视觉小说完整跑通，再补角色立绘/背景图生成。
+- 先用 `seedText` 承载画风，再考虑把 `visualStyleId/Label/Prompt` 结构化进 draft metadata。
+- 先用现有 result/work/runtime 页面闭环，不引入新编辑器。
+
+### 7.3 开放问题
+
+1. 用户是否要求把 Interactive-fiction 原项目中的具体 UI 样式/页面布局迁移到 Genarrative？当前计划只迁移流程语义，不迁移独立 UI。
+2. 画风是否需要成为作品可编辑字段？当前以 seedText/prompt 影响生成内容，后续可在 draft 中增加 metadata。
+3. 文档导入模式是否本期要做？当前计划聚焦一句话模式，document 模式只保留契约能力。
+4. 是否需要真实图片/音乐生成？当前计划作为后续增强，不纳入最小闭环。
+
+## 8. 建议实施顺序
+
+1. 先做只改 prompt/progress/少量前端展示的轻量闭环修补。
+2. 运行前后端定向测试，确认现有能力是否已足够。
+3. 如果后端没有 fallback 或 normalize，再补 Rust 层确定性兜底。
+4. 手工跑通“一句话 -> 生成 -> 结果页 -> 保存 -> 试玩”。
+5. 最后再考虑是否需要资产生成、文档导入、结构化画风 metadata。

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

@@ -16,14 +16,102 @@
 
 ---
 
+## 2026-05-13 修改密码后全设备强制下线
+
+- 背景：修改密码原本只递增 `token_version`，旧 access token 会失效，但旧 refresh cookie 仍可通过 `/api/auth/refresh` 重新签发新 token，不符合“改密后全设备强制下线”的账号安全预期。
+- 决策：`POST /api/auth/password/change` 成功后必须在同一认证真相更新中撤销该用户全部 active `refresh_session`，继续递增 `token_version`，响应清除当前 refresh cookie；前端 `changePassword` 成功后清空本地 access token 并回到未登录态。用户需要使用新密码重新登录。
+- 影响范围：`module-auth` 修改密码用例、`api-server` password management route、`AuthGate`、`authService`、密码登录/重置技术文档。
+- 验证方式：执行 `cargo test -p api-server --manifest-path server-rs/Cargo.toml password_change_allows_login_with_new_password_only -- --nocapture`、`npm run test -- AuthGate.test.tsx authService.test.ts`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/technical/PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md`、`docs/technical/AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md`。
+
+## 2026-05-13 refresh_session 会话组后端聚合与远端踢下线
+
+- 背景：账号安全页中同设备同 IP 的多条 active `refresh_session` 会重复展示；退出登录没有稳定撤销当前 refresh session；前端“踢下线”只做本地状态变化，未真正让远端设备失效。
+- 决策：`GET /api/auth/sessions` 由后端按“同设备 + 同 IP”聚合 active refresh sessions，响应保留代表 `sessionId` 并新增 `sessionIds/sessionCount`；组内包含当前 refresh hash 或 Bearer `sid` 时整组视为当前设备组，前端不展示踢下线。新增 `POST /api/auth/sessions/{session_id}/revoke`，只允许撤销当前用户自己的非当前会话，不递增 `token_version`，但认证中间件会校验 access token `sid` 对应 active refresh session，使被踢设备立即失效。`/api/auth/logout` 在 refresh cookie 缺失时回退用 Bearer `sid` 撤销当前 session，并继续递增 `token_version`。
+- 影响范围：`module-auth` refresh session service、`api-server` auth middleware/logout/sessions route、`shared-contracts`/TS auth contract、`AuthGate`、`AccountModal`、认证会话技术文档和路由/埋点索引。
+- 验证方式：执行 `cargo test -p module-auth --manifest-path server-rs/Cargo.toml refresh_session`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml auth_sessions -- --nocapture`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml revoke_auth_session -- --nocapture`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml logout_succeeds_without_refresh_cookie_when_bearer_token_is_valid -- --nocapture`、`npm run test -- AuthGate.test.tsx AccountModal.test.tsx authService.test.ts`、`npm run check:encoding`、`git diff --check`，并用 `npm run api-server` 检查 `/healthz`。
+- 关联文档：`docs/technical/AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md`、`docs/technical/SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md`、`docs/technical/SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md`。
+
+## 2026-05-12 抓大鹅入口素材风格改为 2D 常见素材风格
+
+- 背景：抓大鹅草稿素材生成已经收敛为多视角 2D 图片素材，但入口页和旧参考图仍沿用黏土、低多边形、塑料、木雕、体素、金属等偏 3D 素材语言，容易让后续生成链路和用户预期继续漂移。
+- 决策：抓大鹅创作入口 `2D素材风格` 固定为 `扁平图标 / 赛璐璐卡通 / 像素复古 / 手绘水彩 / 贴纸描边 / 厚涂图标 / 自定义`；默认风格为 `flat-icon`。入口参考图统一由 `npm run assets:match3d-style-references -- --live` 调用 VectorEngine `gpt-image-2-all` 生成，输出到 `public/match3d-style-references/`。旧 3D 风格参考图不再保留为入口资产。
+- 影响范围：`Match3DAgentWorkspace`、抓大鹅入口交互测试、Match3D PRD、素材生成流水线技术文档、F1 入口文档和 `public/match3d-style-references/` 静态资产。
+- 验证方式：执行 `npm run test -- src\components\match3d-creation\Match3DAgentWorkspace.interaction.test.tsx`、`cargo test -p shared-contracts match3d --manifest-path server-rs\Cargo.toml`、`npm run typecheck`、`npm run check:encoding`，并人工抽查 `.tmp/match3d-style-preview.png`。
+- 关联文档：`docs/prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`、`docs/technical/MATCH3D_F1_CREATION_ENTRY_AND_AGENT_UI_2026-04-30.md`。
+
+## 2026-05-12 拼图与抓大鹅草稿背景音乐按纯音乐自动生成
+
+- 背景：拼图和抓大鹅需要在草稿生成阶段直接产出可试听、可重生成、可进入运行态循环播放的背景音乐。
+- 决策：复用通用 VectorEngine Suno 创作音频链路，不新增 SpacetimeDB 表；拼图音乐保存到首关 `PuzzleDraftLevel.backgroundMusic`，运行态通过 `PuzzleRuntimeLevelSnapshot.backgroundMusic` 下发；抓大鹅音乐保存到首个 `generatedItemAssets[].backgroundMusic`。两者草稿生成都使用 `title` 驱动、`prompt = ""`、`make_instrumental = true`，失败只降级记录 warning，结果页允许重新生成。
+- 影响范围：`api-server` 音频生成、拼图草稿编译、抓大鹅草稿编译、Puzzle/Match3D 结果页和运行态音频播放。
+- 验证方式：检查草稿 response / work detail 中的 `backgroundMusic.audioSrc`，运行态开局后隐藏 audio 循环播放；执行音频相关后端 check、前端 typecheck 和编码检查。
+- 关联文档：`docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
+
+## 2026-05-12 拼图 UI 背景图复用 levels_json 持久化
+
+- 背景：拼图草稿结果页需要像抓大鹅一样支持 UI 背景生成，但首版只需要作品级/首关背景，不应为图片生成结果新增 SpacetimeDB 表结构。
+- 决策：拼图 UI 背景字段存入首关 `levels_json`，字段为 `uiBackgroundPrompt`、`uiBackgroundImageSrc`、`uiBackgroundImageObjectKey`；`compile_puzzle_draft` 草稿编译阶段在首图和背景音乐后自动生成首关 UI 背景，失败只记录 warning 并允许结果页重试；结果页新增 `UI` Tab，可编辑提示词并触发 `generate_puzzle_ui_background`。`api-server` 读取 `public/ui-previews/puzzle-image-compact-ui-2026-05-08.png` 作为非拼图 UI 参考图，调用 VectorEngine `gpt-image-2-all` 生成 9:16 背景并要求中央正方形拼图区与外部 UI 背景边界清晰。SpacetimeDB 只保存结果，不做外部 I/O。
+- 影响范围：拼图结果页、拼图运行态背景渲染、拼图 agent action、`module-puzzle` / `spacetime-module` / `spacetime-client` 的拼图关卡 JSON 映射、拼图流程技术文档。
+- 验证方式：执行 `npm run test -- src/components/puzzle-result/PuzzleResultView.test.tsx`、`cargo test -p api-server puzzle_ui_background --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run typecheck`、`npm run check:encoding`。
+- 关联文档：`docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md`。
+
+## 2026-05-12 抓大鹅结果页素材编辑统一走作品级资产面板
+
+- 背景：抓大鹅结果页需要支持碰面图上传 / AI 重绘、物品素材独立预览、单项删除和批量新增，且不能把素材编辑继续做成列表内联展开或前端临时状态。
+- 决策：结果页 `作品信息` 的碰面图点击打开独立面板，参考图可来自本地上传、物品素材和 UI 素材；AI 重绘统一调用 `POST /api/creation/match3d/works/{profileId}/cover-image` 并转存到 `generated-match3d-assets`。`素材配置 > 物品` 列表项点击打开独立预览面板，不再提供单项重新生成按钮；单项删除和批量新增都写回同一份 `generated_item_assets_json`。批量新增调用 `POST /api/creation/match3d/works/{profileId}/item-assets`，复用草稿生成的 2D 素材图、5x5 切图、OSS 上传和可选点击音效链路，仅作用于新增物品，不新增 SpacetimeDB 表。
+- 影响范围：Match3D 结果页、Match3D works shared contracts、`api-server` Match3D 作品路由、生成资产历史类型和草稿恢复路径。
+- 验证方式：执行 `npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`、`npm run typecheck`、`cargo test -p api-server match3d --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`。
+- 关联文档：`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
+
+## 2026-05-12 平台法律文档入口与登录协议确认
+
+- 背景：生产发布需要在个人页展示用户协议、隐私政策、免责声明和备案号；登录页首次登录需要显式确认法律协议。
+- 决策：法律文档内容读取 `media/files/*.md`，统一通过 `LegalDocumentModal` 独立弹窗展示；“我的”页常用功能区固定 3 列，设置入口下方展示法律信息和 `京ICP备2026025677号` 外链。登录弹窗用 `genarrative.auth.legal-consent.v1` 记录本机确认，首次未勾选时短信 / 密码登录按钮禁用，法律链接不自动勾选。
+- 影响范围：平台个人页、登录弹窗、法律 Markdown 渲染和前端认证交互测试。
+- 验证方式：执行 `npm run test -- src/components/auth/AuthGate.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、触碰文件 ESLint、`npm run check:encoding`。
+- 关联文档：`docs/prd/PROFILE_LEGAL_INFO_AND_AUTH_AGREEMENT_PRD_2026-05-12.md`。
+## 2026-05-12 微信小程序待绑定手机号优先走原生手机号授权
+
+- 背景：微信小程序 `web-view` 壳登录后若返回 `pending_bind_phone`，H5 仍会展示手输手机号和短信验证码绑定页，体验上多了一步。
+- 决策：小程序壳在 `pending_bind_phone` 时暂不打开 H5，先展示原生 `button open-type="getPhoneNumber"`；用户同意后把 `bindgetphonenumber` 返回的 `code` 作为 `wechatPhoneCode` 调用 `/api/auth/wechat/bind-phone`。后端通过微信 `stable_token` 与 `getuserphonenumber` 换取平台验证后的手机号，再复用现有微信待绑定账号合并逻辑并重新签发 active 系统 token。H5 旧短信验证码绑定流程继续作为非小程序环境兜底。
+- 影响范围：`miniprogram/pages/web-view/index.*`、`server-rs/crates/platform-auth`、`server-rs/crates/api-server/src/wechat_auth.rs`、认证共享契约、微信小程序 web-view 壳技术文档。
+- 验证方式：执行 `npm run check:encoding`、`node scripts/check-wechat-miniprogram-auth-smoke.mjs`、`cargo test -p shared-contracts wechat_bind_phone_request_accepts_mini_program_phone_code --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server wechat_miniprogram_bind_phone_code_activates_pending_user --manifest-path server-rs/Cargo.toml -- --nocapture`。
+- 关联文档：`docs/technical/WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md`。
+
+## 2026-05-11 拼图与抓大鹅结果页音频资产复用通用创作音频链路
+
+- 背景：拼图和抓大鹅结果页需要接入 Suno 背景音乐，抓大鹅还需要物体点击音效，但当前两类作品没有独立的作品级音频表或 metadata 字段。
+- 决策：新增 `/api/creation/audio/*` 通用创作音频路由，后端统一负责 VectorEngine 音频任务、OSS 转存、`asset_object` 与 `asset_entity_binding` 写入；视觉小说旧路由保留并复用同一持久化逻辑。拼图背景音乐暂存到首关 `levels_json[0].backgroundMusic/background_music`；抓大鹅背景音乐暂存到 `generated_item_assets_json[0].backgroundMusic/background_music`，单物体点击音效存到对应 item 的 `clickSound/click_sound`。本轮不新增 SpacetimeDB 表和字段。
+- 2026-05-12 补充：抓大鹅入口页新增 `generateClickSound` 开关，默认关闭；开启时 `match3d_compile_draft` 在生成首批 2D 物品素材后并行生成各物品点击音效，并继续复用通用创作音频路由的 OSS、资产绑定和扣费口径。
+- 影响范围：拼图结果页、抓大鹅结果页、抓大鹅运行态音频播放、通用创作音频 shared contracts、`api-server` 音频路由和资产绑定。
+- 验证方式：执行拼图/抓大鹅结果页定向测试、`npm run typecheck`、`cargo test -p api-server vector_engine_audio_generation`、`cargo test -p shared-contracts creation_audio`、`cargo check -p api-server`，真实生成需配置 VectorEngine 与 OSS 私密环境。
+- 关联文档：`docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md`。
+
+## 2026-05-11 寓教于乐公开作品使用独立 `edutainment` 来源接入
+
+- 背景：`宝贝识物` 首关需要通过创作模板发布后进入寓教于乐板块，同时关闭入口时必须从发现页、搜索、详情深链、作品号和历史入口完全不可见；若继续落入 RPG 默认公共作品链路，容易出现误启动、误改造或近似标签误归类。
+- 决策：寓教于乐公开作品在前端公共作品模型中使用 `sourceType = edutainment`，当前只承接 `templateId = baby-object-match`、`templateName = 宝贝识物`；进入“发现 / 寓教于乐”频道仍必须携带精确等于 `寓教于乐` 的公开标签，不因模板名或近似标签自动归类。公开详情、推荐运行态、改造、编辑、点赞和分享链路都必须显式识别 `edutainment`，不得回落到 RPG 默认处理。
+- 影响范围：公开作品卡、发现页频道、作品号搜索、公开详情深链、分享、作品架聚合、后续儿童动作 Demo 模板的发布结果展示。
+- 验证方式：执行第4线程定向单测、前端类型检查、ESLint 与编码检查；关闭 `VITE_ENABLE_EDUTAINMENT_ENTRY` 时确认精确 `寓教于乐` 作品不可通过任何公开入口访问。
+- 关联文档：`docs/design/CHILD_MOTION_EDUTAINMENT_DISCOVER_ENTRY_2026-05-09.md`、`docs/prd/BABY_OBJECT_MATCH_EDUTAINMENT_TEMPLATE_PRD_2026-05-11.md`、`docs/technical/BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md`。
+
 ## 2026-05-10 儿童动作 Demo 视觉资产统一为绘本草地舞台
 
-- 背景：儿童动作 Demo 需要从暗色科技风切换到更适合儿童互动的卡通绘本草地风格，并且要预留 image-2 真实背景图的固定接入位。
+- 背景：儿童动作 Demo 需要从暗色科技风切换到更适合儿童互动的卡通绘本草地风格，并且要让背景、地面、UI、地面指示环和用户轮廓使用同一套 image-2 资源口径。
-- 决策：热身舞台统一采用绘本草地视觉语言，真实背景图默认输出到 `public/child-motion-demo/picture-book-grass-stage.webp`，生成脚本固定为 `scripts/generate-child-motion-demo-assets.mjs`，并通过 `npm run assets:child-motion-demo` 调用 VectorEngine `gpt-image-2-all`。在缺少 `VECTOR_ENGINE_BASE_URL` 或 `VECTOR_ENGINE_API_KEY` 时，只允许 dry-run 和 CSS 兜底，不伪造 live 生图结果。
+- 决策：热身舞台及后续儿童动作 Demo 场景、物品、UI 资源统一采用明亮卡通绘本草地视觉语言。真实资源默认输出到 `public/child-motion-demo/`。背景沿用 `picture-book-grass-stage.png`；地面、指示环、角色轮廓和 UI 已拆分为 v2 用途专属资源：`picture-book-foreground-grass-v2.png`、`picture-book-ground-ring-v2.png`、`picture-book-character-outline-v2.png`、`picture-book-hud-strip-v2.png`、`picture-book-calibration-strip-v2.png`、`picture-book-start-panel-v2.png` 和 `picture-book-ui-button-v2.png`。生成脚本固定为 `scripts/generate-child-motion-demo-assets.mjs`，并通过 `npm run assets:child-motion-demo` 调用 VectorEngine `gpt-image-2-all`；透明资源使用品红底生成后本地去背，中间源图仅保存在 `tmp/child-motion-demo-assets/`。在缺少 `VECTOR_ENGINE_BASE_URL` 或 `VECTOR_ENGINE_API_KEY` 时，只允许 dry-run 和 CSS 兜底，不伪造 live 生图结果。
 - 影响范围：`src/index.css`、`src/components/child-motion-demo/ChildMotionWarmupDemo.tsx` 的舞台视觉层、儿童动作 Demo 技术文档、后续 image-2 资产生成流程。
-- 验证方式：检查 `/child-motion-demo` 舞台是否在未生成资产时仍有可用草地绘本兜底；补齐 VectorEngine 私密配置后运行 `npm run assets:child-motion-demo -- --live` 应能写出默认背景文件。
+- 验证方式：检查 `/child-motion-demo` 舞台是否在未生成资产时仍有可用草地绘本兜底；补齐 VectorEngine 私密配置后运行 `npm run assets:child-motion-demo -- --live` 或 `--live --only <asset-id>` 应能写出对应 PNG，并确认页面静态资源返回 `image/png`。若只调整透明去背、裁切或品红边缘，可运行 `npm run assets:child-motion-demo -- --live --postprocess-only --force --only <asset-id>` 复用源图后处理。页面接入时必须按资源原始比例等比使用，不得把方形软纸面板拉伸成 HUD、状态条或底部草坪。
 - 关联文档：`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 各自维护输入逻辑会导致合并大块、拖拽语义和取消会话行为不一致；后续其他玩法也需要复用体感、摇杆、键盘等设备输入。
@@ -118,7 +206,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`。
 
@@ -221,10 +309,34 @@
 ## 2026-05-10 视觉小说入口收敛为单句创作 + 画风选择
 
 - 背景：视觉小说入口页要对齐抓大鹅式的线性创作入口，只保留最小可用输入，避免再暴露文档 / 空白 / 对话式工作台。
-- 决策：入口页只展示一句话创作输入框和横向视觉画风卡片；画风通过 `seedText` 追加 `视觉画风` 和 `画风要求` 两行透传给既有创作链路；点击生成后先进入 `visual-novel-generating` 过程页，再自动进入 `visual-novel-result`。
+- 决策：入口页只展示一句话创作输入框和横向视觉画风卡片；画风通过 `seedText` 追加 `视觉画风` 和 `画风要求` 两行透传给既有创作链路；点击生成后先进入 `visual-novel-generating` 过程页，再自动进入 `visual-novel-result`。画风卡片主视觉固定消费 `public/visual-novel-style-references/` 下由 VectorEngine `gpt-image-2-all` 生成的静态参考图，不在前端运行时现场调用生图接口。
-- 影响范围：`VisualNovelAgentWorkspace`、`PlatformEntryFlowShellImpl`、`platformEntryTypes`、视觉小说 PRD；不新增后端字段或数据库结构。
+- 影响范围：`VisualNovelAgentWorkspace`、`visualNovelEntryGeneration`、`PlatformEntryFlowShellImpl`、视觉小说 PRD 和创作 Tab 设计文档；不新增后端字段或数据库结构。
-- 验证方式：视觉小说工作台单测通过，`npm run check:encoding` 通过；`npm run typecheck` 仍受仓库里 `src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx` 的既有类型错误影响。
+- 验证方式：执行 `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/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 生成。草稿生成会按难度产出多视角 2D 物品图片并写入 `generated_item_assets_json`，运行态必须优先消费 `generatedItemAssets[].imageViews[]`，默认积木只做兜底。
+- 影响范围：`api-server` Match3D 编译、Match3D works 标签接口、结果页 `作品信息` 与 `素材配置` 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-12 抓大鹅物品种类从消除次数中拆出并改为 2D 五视角素材
+
+- 背景：结果页草稿素材已经能生成和预览，但标准 / 硬核难度仍可能按 `clearCount` 误判需要 12 / 20 种素材，且继续生产 GLB 会拉长草稿生成耗时。
+- 决策：难度配置统一使用 `物品种类`：轻松 3、标准 9、进阶 15、硬核 21；历史硬核 `clearCount=20` 在运行态升为 21 组三消。新草稿和批量新增不再调用 Rodin、不再生成 GLB。每个物品生成 5 个不同 2D 视角，单张 1K 素材图固定按 5x5 切割，最多承载 5 个物品；超过 5 个物品时由 `api-server` 自动分批并行生图。发布必须校验已生成 `image_ready` 且有 `imageViews[]` 或首图引用的素材数量满足当前难度；试玩通过 `itemTypeCountOverride` 自动降到可用 2D 素材数量。历史模型字段只作为旧数据兼容，不再进入新生产链路。
+- 影响范围：Match3D 结果页、运行态启动契约、`module-match3d` 初始 run 生成、SpacetimeDB start input / restart、发布校验和 Match3D 技术文档。
+- 验证方式：`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`、`cargo test -p module-match3d --manifest-path server-rs\Cargo.toml`、相关后端 check / tests。
+- 关联文档：`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
 
 ## 2026-05-07 移动端整页缩放由入口统一锁定
 

.hermes/shared-memory/pitfalls.md

@@ -22,6 +22,14 @@
 - 验证：运行 `cd server-rs && cargo test -p platform-oss -- --nocapture`，并用 bucket=`xushi-dev`、object_key=`generated-square-hole-assets/square-hole-session-546d881972684be2980a2a882cd0cc71/square-hole-profile-134411276ce1469cbe398f946a25d7f8/square-hole-shape-image/rabbit-option/asset-1777979289912039/image.png` 覆盖签名生成。
 - 关联：`server-rs/crates/platform-oss/src/lib.rs`、`server-rs/crates/platform-oss/README.md`。
 
+## generated 音频路径进运行态前要先换签
+
+- 现象：草稿页 audio 控件能播放背景音乐，但拼图或抓大鹅运行态开局后背景音乐不响，Network 可能出现裸 `/generated-*-assets/...mp3` 私有路径 403。
+- 原因：生成音乐转存到 OSS 私有对象后，`audioSrc` 是 generated legacy path；浏览器 `<audio>` 不能像公开静态资源一样直接请求裸路径。
+- 处理：运行态隐藏 `<audio>` 设置 `src` 前，先通过 `useResolvedAssetReadUrl` 或 `resolveAssetReadUrl` 换签；播放失败只静默兜底，不阻断局内交互。拼图读取 `currentLevel.backgroundMusic.audioSrc`，抓大鹅读取 `generatedItemAssets[].backgroundMusic.audioSrc`。
+- 验证：运行态开局后 `<audio loop>` 的 `src` 为签名 URL 或公开 URL；`npm run typecheck` 不报契约字段缺失，后端 run response 带 `backgroundMusic`。
+- 关联：`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`、`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md`。
+
 ## 中文乱码与编码风险
 
 - 现象：中文文案、注释、剧情或文档显示为乱码，或被改写成英文。
@@ -35,6 +43,14 @@
 - 验证：运行仓库已有编码检查；人工抽查修改文件中的中文内容。
 - 关联：`AGENTS.md`、`npm run check:encoding`。
 
+## 忘记密码后仍提示手机号或密码错误先查认证快照同步
+
+- 现象：用户通过“忘记密码”重设密码后，接口返回成功或页面进入登录态，但再次使用新密码登录仍提示“手机号或密码错误”；重启后还可能出现 `Bearer JWT 版本已失效`，日志里的 token version 与本地快照不一致。
+- 原因：重置/修改密码会更新 `password_hash`、`password_login_enabled` 和 `token_version`，如果 API 层只更新本地 `InMemoryAuthStore`，没有调用 `sync_auth_store_snapshot_to_spacetime()`，`api-server` 重启时可能从旧的 SpacetimeDB 表或旧快照恢复账号状态。
+- 处理：`POST /api/auth/password/change` 与 `POST /api/auth/password/reset` 成功后必须同步认证快照；启动恢复时从 SpacetimeDB 表、SpacetimeDB 快照记录和本地 `GENARRATIVE_AUTH_STORE_PATH` 文件中选择可判断的最新快照，本地文件更新时尝试回写 SpacetimeDB。
+- 验证：执行 `cargo test -p module-auth password --manifest-path server-rs/Cargo.toml` 与 `cargo test -p api-server password --manifest-path server-rs/Cargo.toml`；手测时重设密码后旧密码应失败，新密码应成功，重启后仍应保持。
+- 关联：`server-rs/crates/api-server/src/password_management.rs`、`server-rs/crates/api-server/src/state.rs`、`docs/technical/PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md`。
+
 ## `.hermes` 只放共享内容，不放个人 Hermes 配置
 
 - 现象：团队成员误把个人 Hermes 配置、会话或密钥复制进仓库。
@@ -51,14 +67,31 @@
 - 验证：运行 `npx vitest run src\services\useMocapInput.test.ts src\components\child-motion-demo\ChildMotionWarmupDemo.test.tsx`，并在本地硬件服务启动后进入 `/child-motion-demo` 实测站位、招手、左右手挥动和跳跃阶段。
 - 关联：`src/services/useMocapInput.ts`、`src/components/child-motion-demo/ChildMotionWarmupDemo.tsx`、`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`。
 
-## 儿童动作 Demo 真实绘本背景图未生成先查 VectorEngine 配置
+## 宝贝识物选篮误触发先查多套判定和残余轨迹
 
-- 现象：`/child-motion-demo` 已经呈现绘本草地风格，但 `public/child-motion-demo/picture-book-grass-stage.webp` 不存在，Network 里该图返回 404，或运行 `npm run assets:child-motion-demo -- --live` 返回缺少 VectorEngine 配置。
+- 现象：`宝贝识物` 运行态打开礼物盒或反馈结束后，当前物品被连续送入左侧或右侧篮子，或硬件动作名偶发命中导致未做明确横移动作也触发选篮。
-- 原因：儿童动作 Demo 的真实背景图使用 VectorEngine `gpt-image-2-all` 生成，脚本只读取 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和可选 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；仓库内不能提交真实 key，缺配置时页面只能使用 CSS 草地绘本兜底。
+- 原因：选篮如果同时消费 `wave_left_hand` / `wave_right_hand` / `wave` 动作名和手部轨迹，或在 `correct` / `wrong` 反馈阶段继续累计手部路径，会把抓握、反馈期间残留移动或未知侧别手部误算成下一次选篮。
-- 处理：在本地私密环境补齐 `VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai` 与 `VECTOR_ENGINE_API_KEY`，不要把 key 写入 Git；先运行 `npm run assets:child-motion-demo -- --dry-run` 核对 prompt，再运行 `npm run assets:child-motion-demo -- --live` 生成默认背景图。
+- 处理：宝贝识物选篮只使用明确 `leftHand` / `rightHand` 的连续横向轨迹阈值；侧别为 `unknown` 的手部轨迹不参与选篮；礼物盒打开和反馈阶段清空轨迹，不在非 `active` 阶段累计路径。礼物盒激活仍使用 `open_palm -> grab` 抓握序列。
-- 验证：生成后确认 `public/child-motion-demo/picture-book-grass-stage.webp` 存在，重新打开 `/child-motion-demo` 可看到真实绘本草地背景；`npm run check:encoding` 仍通过。
+- 补充：当前本地 mocap 的 handedness 是摄像头视角，宝贝识物选篮前需要换算为用户身体视角；`rightHand` 轨迹代表玩家左手并进入左篮，`leftHand` 轨迹代表玩家右手并进入右篮。键鼠调试不走该换算，仍保持鼠标左键=左篮、右键=右篮。
+- 验证：运行 `npm run test -- src/components/edutainment-runtime/BabyObjectMatchRuntimeShell.test.tsx src/services/useMocapInput.test.ts`，确认动作名负向测试、未知侧别负向测试和左右手横向轨迹测试通过。
+- 关联：`src/components/edutainment-runtime/BabyObjectMatchRuntimeShell.tsx`、`docs/technical/BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md`。
+
+## 儿童动作 Demo 绘本风资源未生成先查 VectorEngine 配置
+
+- 现象：`/child-motion-demo` 已经呈现绘本草地风格，但 `public/child-motion-demo/picture-book-grass-stage.png`、`picture-book-grass-floor.png`、`picture-book-ground-ring.png`、`picture-book-character-outline.png`、`picture-book-ui-panel.png` 或 `picture-book-ui-button.png` 不存在，Network 里对应图片返回 404，或运行 `npm run assets:child-motion-demo -- --live` 返回缺少 VectorEngine 配置。
+- 原因：儿童动作 Demo 的真实背景、地面、UI、地面指示环和角色轮廓资源都使用 VectorEngine `gpt-image-2-all` 生成，脚本只读取 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和可选 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；仓库内不能提交真实 key，缺配置时页面只能使用 CSS 草地绘本兜底。
+- 处理：在本地私密环境补齐 `VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai` 与 `VECTOR_ENGINE_API_KEY`，不要把 key 写入 Git；先运行 `npm run assets:child-motion-demo -- --dry-run` 核对 prompt，再运行 `npm run assets:child-motion-demo -- --live` 或 `npm run assets:child-motion-demo -- --live --only ui-panel` 等小批量命令生成资源。透明资源的品红底源图写入 `tmp/child-motion-demo-assets/`，不要把源图或预览图放入 `public/child-motion-demo/` 作为正式资产。
+- 验证：生成后确认 `public/child-motion-demo/` 只保留页面引用的最终 PNG，重新打开 `/child-motion-demo` 可看到真实绘本草地背景、地面、圆环、角色轮廓和 UI 资源；`npm run check:encoding` 仍通过。
 - 关联：`scripts/generate-child-motion-demo-assets.mjs`、`src/index.css`、`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`。
 
+## 儿童动作 Demo 绘本资源变形先查用途拆分和透明后处理
+
+- 现象：`/child-motion-demo` 背景风格正确，但底部草坪被拉成厚色块、顶部 HUD 或右下状态条像方形面板被横向拉伸，或旧 `picture-book-ui-panel.png` 与新资源叠在一起。
+- 原因：早期资源中 `picture-book-ui-panel.png` 是接近方形画布，`picture-book-grass-floor.png` 也含大量透明边界；若 CSS 用 `background-size: 100% 100%` 把同一资源强行铺成 HUD、状态条、开始面板或底部地板，就会出现变形和层叠观感。
+- 处理：使用 v2 用途专属资源：`picture-book-foreground-grass-v2.png`、`picture-book-ground-ring-v2.png`、`picture-book-character-outline-v2.png`、`picture-book-hud-strip-v2.png`、`picture-book-calibration-strip-v2.png`、`picture-book-start-panel-v2.png`、`picture-book-ui-button-v2.png`；CSS 按资源比例等比缩放，底部草坪只覆盖下沿，HUD / 状态条 / 开始托盘分别引用各自资源。若只需修透明裁切或品红边，运行 `npm run assets:child-motion-demo -- --live --postprocess-only --force --only <asset-id>`，不重新请求 image-2。
+- 验证：用横屏截图检查没有新旧资源叠加、没有方形面板拉成长条、角色和地面指示环不被前景草坪埋住；同时运行 `npm run check:encoding`。
+- 关联：`scripts/generate-child-motion-demo-assets.mjs`、`src/index.css`、`public/child-motion-demo/`、`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`。
+
 ## GPT-image-2 不再读 APIMart 图片配置
 
 - 现象：配置了 `APIMART_BASE_URL` / `APIMART_API_KEY` 后，RPG、拼图或方洞的 GPT-image-2 生图仍返回缺配置，或请求体里还出现 `official_fallback` / `image_urls`。
@@ -155,6 +188,14 @@
 - 验证：重新发布日志应显示创建新的数据库，而不是更新旧数据库；若仍显示更新或继续 `401`，继续检查数据目录、库名和 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 解析报错。
@@ -397,6 +438,22 @@
 - 验证：发布链路使用当前 `deploy/systemd`、`deploy/nginx`、`scripts/deploy` 和 `jenkins/Jenkinsfile.production-*`。
 - 关联：`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
 
+## Release Web 产物通过内网 rsync 拉取
+
+- 现象：`Genarrative-Web-Deploy` 发布到 `release` 目标时，release agent 本地没有 `/var/cache/genarrative-build/web-artifacts/<job>/<build>/<version>/web.tar.gz`，但 Jenkins controller 又只归档轻量元数据，导致发布阶段找不到 Web 大包。
+- 原因：Web 大包为了避免从 Linux 构建机拉回 Jenkins controller，默认留在构建机稳定缓存目录；development 目标与构建机同机可直接读取，release 目标是独立机器，需要内网同步。
+- 处理：release 服务器的 Jenkins 运行用户配置 SSH Host `genarrative-build-internal` 指向构建机内网地址，`Genarrative-Web-Deploy` 在 `DEPLOY_TARGET=release` 且本地缺少大包时默认执行 `rsync` 拉取同一路径内容；真实内网 IP、用户和私钥路径只放在服务器本机 SSH config，不写入 Jenkinsfile。
+- 验证：在 release 服务器上先手工跑通 `rsync -av --progress "genarrative-build-internal:${SRC}/" "${DST}/"`，再运行 Web Deploy；流水线会继续执行 `web.tar.gz.sha256` 校验。
+- 关联：`jenkins/Jenkinsfile.production-web-deploy`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
+
+## Jenkins 生产流水线拉 Git 先本机再域名备用
+
+- 现象：生产发布、数据库导入导出或服务器配置流水线在目标 Linux agent 上执行 `GitSCM checkout` 时，`http://127.0.0.1:3000/GenarrativeAI/Genarrative.git` 不可达，导致脚本还没拉下来就失败；若 fallback 到公网 Git 时没有限制 refspec、浅克隆和 tags，还可能在约 10 分钟后出现 `git-remote-https died of signal 15`、`early EOF`、`invalid index-pack output`。
+- 原因：`127.0.0.1` 只代表当前执行阶段的 agent 自身；当 release agent 与 Git 服务不在同一台机器，或本机 Git/Web 服务临时不可用时，固定写死 localhost 会阻断 Jenkinsfile 内部源码/脚本 checkout。
+- 处理：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；首次 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`；扫描所有以 `127.0.0.1:3000` 拉 Git 且运行在 Linux agent 的生产 Jenkinsfile，确认存在 `GIT_REMOTE_FALLBACK_URL`、`EFFECTIVE_GIT_REMOTE_URL` 和脚本层 `GIT_REMOTE_FALLBACK_URL` 透传；运行 `bash -n scripts/jenkins-checkout-source.sh`。
+- 关联：`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`。
+
 ## Jenkins 可选参数在 set -u 下不能裸读
 
 - 现象：数据库导入或导出流水线报 `INCLUDE_TABLES: unbound variable`，或其它可选参数在 Bash 中未定义即退出。
@@ -437,30 +494,85 @@
 - 验证：`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/GLB 方案，导致新草稿生成耗时变长、进度停在模型阶段，或运行态等待不存在的 GLB。
-- 原因：草稿生成链路曾在切割图片后立即并行调用 Rodin 图生模型，并把模型下载成功作为草稿完成前置条件；上游完成态和可下载文件列表不是强一致，容易把本来可用的图片草稿卡死。
+- 原因：仓库里保留了 Hyper3D 通用代理和历史模型字段，旧文档也曾要求草稿阶段同步生成 GLB。当前产品口径已经改为 2D 多视角素材。
-- 处理：草稿阶段只生成物品名、素材图、切割独立图片并上传 OSS，返回 `status = image_ready`；Rodin 3D 模型生成留到结果页 `3D素材` Tab 手动触发。
+- 处理：新 `match3d_compile_draft` 与批量新增只生成 2D 图片：每个物品 5 个视角，单张 1K 素材图固定 5x5 切割，一行对应一个物品，超过 5 个物品自动分批并行生图。`generatedItemAssets[].status` 使用 `image_ready`，发布校验看 `imageViews[]` 或首图引用。`generated-models` 仅用于历史外部模型链接转存，不能作为新生产链路。
-- 验证：草稿响应中的 `generatedItemAssets[].imageSrc` 有值、`modelSrc` 为空、状态为 `image_ready`；结果页显示 `图片已就绪` 和 `0 文件`，不会自动请求 Hyper3D 下载。
+- 验证：`cargo test -p api-server match3d --manifest-path server-rs/Cargo.toml`、`npm run test -- src\services\miniGameDraftGenerationProgress.test.ts src\components\match3d-result\Match3DResultView.test.tsx src\components\match3d-runtime\Match3DRuntimeShell.test.tsx`。
-- 关联：`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`。
+- 关联：`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
 
 ## 抓大鹅切图路径不能只用中文物品名
 
-- 现象：草稿页 `3D素材` Tab 中多个素材名称不同，但预览图片完全一样；点击图生模型生成时还可能提示 `参考图必须是 data URL`。
+- 现象：草稿页 `素材配置 > 物品` 中多个素材名称不同，但预览图片完全一样。
-- 原因：中文物品名经过 OSS 路径段清洗后都可能退化成 `item`，多张切割图片写到同一个 `items/item/image.png` object key，后写入覆盖先写入；结果页手动 Rodin 图生模型还曾把 `/generated-match3d-assets/...` 私有路径直接作为 `imageDataUrls` 提交。
+- 原因：中文物品名经过 OSS 路径段清洗后都可能退化成 `item`，多张切割图片写到同一个 object key，后写入覆盖先写入。
-- 处理：切割图上传路径必须带稳定唯一 `itemId` 前缀，例如 `items/match3d-item-1-item/image.png`；结果页提交图生模型前，generated 私有路径先经同源 `/api/assets/read-bytes` 由后端换签并读取字节，前端再转成 `data:image/...;base64,...`，不要在浏览器里直接 `fetch` OSS 签名 URL，否则会被 bucket CORS 拦截。
+- 处理：切割图上传路径必须带稳定唯一 `itemId` 前缀，例如 `items/match3d-item-1-item/views/view-01.png`；运行态读取 generated 私有图片时通过同源 `/api/assets/read-url` 换签，不直接请求裸 OSS 路径。
-- 验证：后端单测覆盖中文名路径唯一；前端单测覆盖 generated 参考图会换签、fetch 并以 Data URL 调用 `submitHyper3dImageToModel`。
+- 验证：后端单测覆盖中文名路径唯一，前端运行态测试覆盖 generated 图片源解析。
 - 关联：`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`。
 
 ## 抓大鹅生成素材不能只挂在 compile response
 
-- 现象：抓大鹅草稿生成完成后停留在结果页能看到切割好的 `3D素材` 图片；退出后从草稿 Tab 重新进入同一草稿，素材列表变回默认占位或为空，已生成的物品名称和图片丢失。
+- 现象：抓大鹅草稿生成完成后停留在结果页能看到切割好的物品图片；退出后从草稿 Tab 重新进入同一草稿，素材列表变回默认占位或为空，已生成的物品名称和图片丢失。
 - 原因：`generatedItemAssets` 如果只附加在 `match3d_compile_draft` 的 HTTP response draft 上，刷新或重进时 `getMatch3DWorkDetail` 只能读取 SpacetimeDB 中的 `match3d_work_profile`；旧 mapper 返回空数组，自然无法恢复素材。拼图链路已经通过 `save_puzzle_generated_images` 把候选图和 levels 写回 work profile，抓大鹅也必须同样写持久字段。
 - 处理：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`。
 
+## 抓大鹅试玩和正式运行态不要只读草稿页本地素材预览
+
+- 现象：结果页能看到生成的物品图片，但点击试玩或从推荐 / 公开作品进入正式抓大鹅时，局内仍显示默认积木素材。
+- 原因：结果页本地 `assetDrafts` 和作品 profile 的 `generatedItemAssets` 可能不同步；推荐流内嵌运行态若只读卡片摘要，卡片缺素材时会把已持久化 profile 素材丢掉；点击试玩时 React state 异步更新也可能让运行态第一帧读取旧 `match3dProfile`。
+- 处理：删除、批量新增、音效生成或封面引用物品素材后，都把当前 `generatedItemAssets` 写回作品 profile；`Match3DResultView` 合并同 `itemId` 的 draft/profile 素材，用 profile 已有 `imageViews[]` 或首图引用补齐旧 draft；点击试玩前把试玩可用物品种类通过 `itemTypeCountOverride` 降到已生成 2D 素材数量；推荐流内嵌运行态启动前若卡片摘要没有生成素材，补读 `getMatch3DWorkDetail(profileId)` 并把详情资产传给 `Match3DRuntimeShell`。`PlatformEntryFlowShellImpl` 需要维护 `match3dRuntimeProfile`，在 `startMatch3DRunFromProfile` 创建 run 后立即锁定本次完整 profile，runtime 渲染时优先按 `run.profileId` 使用这份 profile，而不是等待普通 `match3dProfile` state 下一轮刷新。
+- 验证：执行 `npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`、`npm run test -- src/components/match3d-runtime/Match3DRuntimeShell.test.tsx`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`，并检查历史草稿和公开 M3 作品的 Network 响应里 `generatedItemAssets[].imageViews/imageSrc/imageObjectKey`。
+- 关联：`src/components/match3d-result/Match3DResultView.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/match3d-runtime/Match3DPhysicsBoard.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
+
+## 法律文档弹窗通过 portal 挂载时要显式带平台主题
+
+- 现象：登录弹窗内点击协议链接打开法律文档时，弹窗可能继承不到 `platform-theme--light/dark` 变量，或者层级低于登录遮罩导致不可见。
+- 原因：`UnifiedModal` 默认通过 portal 挂到 `document.body`，不再处于原页面的主题容器内；登录弹窗自身又使用较高 z-index。
+- 处理：法律文档弹窗组件应支持传入 `platformTheme`，overlay 上显式挂 `platform-theme platform-theme--*`，并使用高于登录遮罩的层级。法律内容必须作为独立面板打开，不要在当前个人页或登录面板下方内联展开。
+- 验证：登录页协议链接、个人页法律入口均能打开可滚动 `LegalDocumentModal`，亮色 / 暗色主题文本和按钮可读。
+
+## 生成页完成回调不能只依赖异步 React state
+
+- 现象：抓大鹅或拼图点击生成后，进度页已经显示 100% / 生成完成，但没有自动进入试玩或结果页。
+- 原因：完成回调用 `selectionStageRef.current` 判断用户是否仍在生成页；如果执行 compile 前只调用 `setSelectionStage('*-generating')`，action 很快返回时 ref 仍可能是旧 stage。
+- 处理：进入各玩法生成页时同步写 `selectionStageRef.current = '*-generating'`，再调用 `setSelectionStage('*-generating')`。这不是为渲染服务，而是给同一异步链路里的完成回调提供即时事实。
+- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx` 覆盖抓大鹅和拼图生成后自动试玩 / 返回结果页。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
+
+## 抓大鹅历史草稿外部 Rodin GLB 链接必须转存后再试玩或发布
+
+- 现象：草稿页预览模型失败并报 `GL_INVALID_ENUM: Invalid cap.`，或结果页能看到历史生成记录但试玩、发布和正式运行态仍显示默认积木。
+- 原因：历史结果页手动 `重新生成` 会把 Hyper3D/Rodin 的外部 CDN 下载链接直接保存到 `generatedItemAssets[].modelSrc`，同时 `modelObjectKey` 为空。外部链接可能过期、跨域、返回 HTML 错误页或非 GLB 内容；前端预览和运行态不能把它当作稳定私有资产。
+- 处理：该问题只适用于旧数据。结果页发现 `status = model_ready`、`modelSrc = https://...` 且无 `modelObjectKey` 时，可调用 `POST /api/creation/match3d/works/{profileId}/generated-models` 做一次性转存；新草稿和批量新增不得继续生成或依赖 GLB。若历史半修复数据同时保留外部 `modelSrc` 和平台 `modelObjectKey`，旧模型预览读取层优先用 `modelObjectKey`。
+- 验证：`npm run test -- src\components\match3d-result\Match3DResultView.test.tsx`、`npm run test -- src\components\match3d-runtime\Match3DRuntimeShell.test.tsx`、`npm run test -- src\components\rpg-entry\RpgEntryFlowShell.agent.interaction.test.tsx`、`cargo test -p api-server match3d_model_download --manifest-path server-rs\Cargo.toml`，并检查修复后响应中的 `generatedItemAssets[].modelObjectKey` 不为空。
+- 关联：`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-result/Match3DResultView.tsx`、`src/components/match3d-result/Match3DModelPreview.tsx`、`src/components/match3d-runtime/Match3DPhysicsBoard.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。
+
+## 抓大鹅难度配置的物品种类和消除次数必须分离
+
+- 现象：历史草稿选择标准 / 硬核难度后，系统可能把 `clearCount` 当成局内物品种类数量，导致标准需要 12 种、硬核需要 20/21 种；素材不足时发布或试玩行为不一致。
+- 原因：旧运行态把消除次数和类型数量绑在一起，结果页文案又同时展示“素材图片 / 局内类型”，导致前端、发布校验和 run start 口径不一致。
+- 处理：统一使用 `物品种类` 口径：轻松 3、标准 9、进阶 15、硬核 21；历史 `clearCount=20` 且难度为硬核的运行态按新硬核升为 21 组三消，避免 20 组却要求 21 种素材。发布前按 `image_ready` 且有 `imageViews[]` 或 `imageSrc/imageObjectKey` 的生成素材数量阻断不足难度；试玩不阻断，但通过 `itemTypeCountOverride` 自动降到已生成 2D 素材数量。重启从已有 run 快照反推实际物品种类，保持同一局重开不变。
+- 验证：`npm run test -- src\components\match3d-result\Match3DResultView.test.tsx`、`cargo test -p module-match3d --manifest-path server-rs\Cargo.toml`，涉及发布 reducer 时补跑 `cargo test -p spacetime-module match3d --manifest-path server-rs\Cargo.toml`。
+- 关联：`src/components/match3d-result/Match3DResultView.tsx`、`src/services/match3d-runtime/match3dRuntimeClient.ts`、`server-rs/crates/module-match3d/src/application.rs`、`server-rs/crates/spacetime-module/src/match3d/mod.rs`、`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`。
+
 ## 公开作品详情深链找不到作品不能停在空详情页
 
 - 现象：直接访问 `/works/detail?work=PZ-...`，作品不存在或已下架时会弹出“作品不存在或已下架，将返回首页。”；关闭提示后仍可能停在大白屏。

AGENTS.md

@@ -12,6 +12,20 @@
 - 仓库 `.hermes/` 只保存可进入 Git 的团队共享内容；禁止提交个人 `~/.hermes` 配置、`.env`、API Key、Token、会话记录、认证文件和本地私密路径。
 - 若 `.hermes/shared-memory/` 与当前代码或 `docs/` 最新文档冲突，以代码和最新 `docs/` 为准，并同步修正过期共享记忆。
 
+## Agent skills
+
+### Issue tracker
+
+Issues are tracked in the self-hosted Gitea remote for this repo. Use Gitea Issues via the configured Gitea UI/API or `tea` CLI when available; do not use GitHub `gh` or GitLab `glab` unless the repo is migrated. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Use the default canonical triage labels: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context layout: read root `CONTEXT.md` when present and architecture decisions from `docs/adr/`. See `docs/agents/domain.md`.
+
 ## 项目约束
 - 代码需要有完善的中文注释
 - 在落地工程修改前检查是否有详细指导本次落地的文档，若没有文档或文档的完善程度仍有落地过程中编码级别的歧义优先优化文档后落地工程迭代。

apps/admin-web/src/api/adminApiTypes.ts

@@ -182,7 +182,6 @@ export interface AdminUpsertProfileRedeemCodeRequest {
 export interface AdminUpsertProfileInviteCodeRequest {
   inviteCode: string;
   metadata?: Record<string, unknown>;
-  grantedUserTags: string[];
   startsAt?: string | null;
   expiresAt?: string | null;
 }
@@ -229,7 +228,6 @@ export interface ProfileInviteCodeAdminResponse {
   userId: string;
   inviteCode: string;
   metadata: Record<string, unknown>;
-  grantedUserTags: string[];
   startsAt?: string | null;
   expiresAt?: string | null;
   status: 'pending' | 'active' | 'expired';

apps/admin-web/src/pages/AdminInviteCodePage.tsx

@@ -78,10 +78,13 @@ export function AdminInviteCodePage({
 
     setIsSaving(true);
     try {
+      const metadata = withMetadataUserTags(
+        parseMetadata(metadataText),
+        parseUserTags(grantedTagsText),
+      );
       const payload: AdminUpsertProfileInviteCodeRequest = {
         inviteCode: inviteCode.trim(),
-        metadata: parseMetadata(metadataText),
+        metadata,
-        grantedUserTags: parseUserTags(grantedTagsText),
         startsAt: startsAt ? toIsoDateTime(startsAt) : null,
         expiresAt: expiresAt ? toIsoDateTime(expiresAt) : null,
       };
@@ -117,7 +120,7 @@ export function AdminInviteCodePage({
     setInviteCode(entry.inviteCode);
     setStartsAt(toDateTimeLocalValue(entry.startsAt));
     setExpiresAt(toDateTimeLocalValue(entry.expiresAt));
-    setGrantedTagsText(entry.grantedUserTags.join('、'));
+    setGrantedTagsText(metadataUserTags(entry.metadata).join('、'));
     setMetadataText(JSON.stringify(entry.metadata, null, 2));
   }
 
@@ -252,7 +255,7 @@ export function AdminInviteCodePage({
                           </button>
                         </td>
                         <td>
-                          <TagList tags={entry.grantedUserTags} />
+                          <TagList tags={metadataUserTags(entry.metadata)} />
                         </td>
                         <td>
                           <span className={`admin-status ${inviteValidityClass(entry)}`}>
@@ -291,7 +294,7 @@ export function AdminInviteCodePage({
                 <div>
                   <dt>标签</dt>
                   <dd>
-                    <TagList tags={result.grantedUserTags} />
+                    <TagList tags={metadataUserTags(result.metadata)} />
                   </dd>
                 </div>
                 <div>
@@ -338,6 +341,29 @@ function TagList({tags}: {tags: string[]}) {
   );
 }
 
+function metadataUserTags(metadata: Record<string, unknown>) {
+  const raw = metadata.userTags ?? metadata.user_tags;
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+
+  return parseUserTags(raw.filter((value): value is string => typeof value === 'string').join('、'));
+}
+
+function withMetadataUserTags(
+  metadata: Record<string, unknown>,
+  tags: string[],
+): Record<string, unknown> {
+  const next = {...metadata};
+  delete next.user_tags;
+  if (tags.length) {
+    next.userTags = tags;
+  } else {
+    delete next.userTags;
+  }
+  return next;
+}
+
 function parseUserTags(value: string) {
   const tags: string[] = [];
   for (const raw of value.split(/[\n,，;；、]+/)) {

deploy/nginx/README.md

@@ -0,0 +1,34 @@
+# Genarrative Nginx compression policy
+
+本配置片段由 `scripts/jenkins-server-provision.sh` 在安装 Nginx 站点配置时展开。
+
+## gzip
+
+- `deploy/nginx/genarrative.conf` 与 `deploy/nginx/genarrative-dev-http.conf` 默认开启 gzip。
+- 覆盖 `application/json`，用于降低 `/api/runtime/*/gallery` 这类 JSON 列表接口的公网带宽占用。
+- 当前推荐等级为 `gzip_comp_level 5`，兼顾 2C/2G 服务器 CPU 与压缩收益。
+
+## Brotli
+
+- Brotli 只在目标服务器 Nginx 接受 brotli 指令时开启。
+- Provision 脚本通过临时配置执行 `nginx -t` 做能力探测；探测配置会先 `include /etc/nginx/modules-enabled/*.conf`，避免 Ubuntu 动态模块已安装但测试配置未加载模块导致误判。可用时把模板中的 `# __GENARRATIVE_BROTLI_DIRECTIVES__` 替换为 brotli 指令，不可用时保留注释说明。
+- 不要直接在静态模板里无条件写 `brotli on;`，否则没有 brotli 模块的服务器会 `nginx -t` 失败并回滚。
+- 不要用 `nginx -V | grep brotli` 判断 brotli 是否可用；Ubuntu apt 安装的 brotli 是动态模块，可能只出现在 `nginx -T` 的 `load_module` 配置里。
+
+## 验证
+
+```bash
+curl -sSI -H 'Accept-Encoding: gzip' \
+  http://<host>/api/runtime/puzzle/gallery \
+  | grep -iE 'content-encoding|vary|content-type|content-length'
+
+curl -sSI -H 'Accept-Encoding: br' \
+  http://<host>/api/runtime/puzzle/gallery \
+  | grep -iE 'content-encoding|vary|content-type|content-length'
+```
+
+预期：
+
+- gzip 可用时返回 `Content-Encoding: gzip`。
+- br 可用时返回 `Content-Encoding: br`。
+- 响应头应包含 `Vary: Accept-Encoding`。

deploy/nginx/genarrative-dev-http.conf

@@ -5,6 +5,23 @@ server {
     listen 80;
     server_name genarrative.example.com;
 
+    gzip on;
+    gzip_vary on;
+    gzip_proxied any;
+    gzip_comp_level 5;
+    gzip_min_length 1024;
+    gzip_types
+        text/plain
+        text/css
+        text/javascript
+        application/javascript
+        application/json
+        application/xml
+        application/xml+rss
+        image/svg+xml;
+
+    # __GENARRATIVE_BROTLI_DIRECTIVES__
+
     root /srv/genarrative/web;
     index index.html;
 

deploy/nginx/genarrative.conf

@@ -16,6 +16,23 @@ server {
     listen 443 ssl http2;
     server_name genarrative.example.com;
 
+    gzip on;
+    gzip_vary on;
+    gzip_proxied any;
+    gzip_comp_level 5;
+    gzip_min_length 1024;
+    gzip_types
+        text/plain
+        text/css
+        text/javascript
+        application/javascript
+        application/json
+        application/xml
+        application/xml+rss
+        image/svg+xml;
+
+    # __GENARRATIVE_BROTLI_DIRECTIVES__
+
     ssl_certificate /etc/letsencrypt/live/genarrative.example.com/fullchain.pem;
     ssl_certificate_key /etc/letsencrypt/live/genarrative.example.com/privkey.pem;
 

docs/agents/domain.md

@@ -0,0 +1,36 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Layout
+
+This repo uses a **single-context** layout for Matt Pocock engineering skills:
+
+- `CONTEXT.md` at the repo root, when present, is the primary domain glossary/context file.
+- `docs/adr/`, when present, contains architecture decision records.
+- If either path does not exist, proceed silently; do not block the task just to create it.
+
+## Before exploring, read these
+
+1. Root `CONTEXT.md`, if present.
+2. Relevant ADRs under `docs/adr/`, if present.
+3. Existing project context that predates this setup:
+   - `.hermes/README.md`
+   - `.hermes/shared-memory/project-overview.md`
+   - `.hermes/shared-memory/team-conventions.md`
+   - `.hermes/shared-memory/development-workflow.md`
+   - `.hermes/shared-memory/decision-log.md`
+   - `.hermes/shared-memory/pitfalls.md`
+   - Relevant files under `docs/technical/`, `docs/prd/`, `docs/design/`, and `docs/experience/`
+
+Follow `AGENTS.md` when it is more specific than this file. If older docs conflict with current code or newer technical docs, treat current code and newer docs as authoritative and update stale docs when the task requires it.
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept in an issue title, refactor proposal, diagnosis, test name, or implementation plan, use the term as defined in `CONTEXT.md` when available. Do not drift to synonyms the glossary explicitly avoids.
+
+If the concept you need is not in the glossary yet, either use the established vocabulary from `.hermes/shared-memory/` and `docs/`, or note the gap for a future documentation pass.
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding it.

docs/agents/issue-tracker.md

@@ -0,0 +1,35 @@
+# Issue tracker: Gitea
+
+Issues and PRDs for this repo live as issues in the self-hosted Gitea remote:
+
+- Remote: `https://git.genarrative.world/GenarrativeAI/Genarrative.git`
+- Tracker type: Gitea Issues
+
+## Conventions
+
+- Prefer the Gitea `tea` CLI when it is installed and configured for this host.
+- Do not use GitHub `gh` or GitLab `glab` for this repo unless the repository is explicitly migrated to those platforms.
+- If `tea` is unavailable, use the Gitea Web UI or Gitea REST API for the same operations.
+
+## Common operations with `tea`
+
+Exact flags can vary by `tea` version. Run `tea issues --help` or `tea issue --help` before using a command in a new environment.
+
+- Create an issue: `tea issues create --title "..." --body "..."`
+- Read an issue: `tea issues view <number>`
+- List issues: `tea issues list`
+- Comment on an issue: use the installed `tea` issue comment command shown by `tea issues --help`; if unavailable, use the Gitea Web UI or REST API.
+- Apply labels: use the installed `tea` issue update/edit command shown by `tea issues --help`; if unavailable, use the Gitea Web UI or REST API.
+- Close an issue: use the installed `tea` issue close/update command shown by `tea issues --help`; if unavailable, use the Gitea Web UI or REST API.
+
+## When a skill says "publish to the issue tracker"
+
+Create a Gitea issue in `GenarrativeAI/Genarrative` with the requested title, body, labels, and links back to any relevant docs or branch.
+
+## When a skill says "fetch the relevant ticket"
+
+Read the Gitea issue body and comments/notes for the referenced issue number. Include labels and current open/closed state in the working context.
+
+## Authentication
+
+Use the locally configured Gitea credentials for the current developer. Do not commit tokens, cookies, `.env`, or local credential files.

docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's Gitea issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role, use the corresponding Gitea label string from this table.
+
+If the Gitea repository later adopts Chinese labels or a different naming scheme, edit the right-hand column here rather than letting skills create duplicate labels.

docs/design/BAIMENG_EXPO_ROLLUP_BANNER_DESIGN_2026-05-07.md

@@ -108,3 +108,42 @@ output/imagegen/baimeng-expo-rollup/baimeng-rollup-final-cn-preview.png
 2. 若需要放二维码，应放在底部独立留白区，不遮挡产品心智和关键技术段。
 3. 若展会现场观众偏投资人或B端合作方，可以把“产品心智”段压缩，放大“关键技术”与平台愿景。
 4. 若观众偏玩家或普通创作者，可以把“关键技术”段压缩，放大“10分钟创作、玩过就改、发布分享”的闭环。
+
+## 6. 公司招聘版 2026-05-11
+
+2026-05-11 根据线下招聘场景，将海报方向从“纯产品宣传”调整为“公司 + 产品 + 岗位”的整体宣传。
+
+新版定位：
+
+```text
+北京亓盒网络科技有限公司
+岗位名称：AI 原生游戏产品/内容实习生
+行业方向：AI 原生游戏 × UGC 内容创作 × 互动叙事
+产品：百梦 AI互动内容创作平台
+```
+
+新版保留百梦气泡色彩、轻盈白底和创作流动感，但新增校园实验室、AI 游戏创作、作品卡、产品测试与内容设计氛围。版面结构调整为：
+
+1. 顶部：公司名、岗位名、行业方向与招聘主标题。
+2. 中上：百梦产品主张与三枚产品能力标签。
+3. 中部：按 `游玩 -> 改造 -> 创作` 顺序展示产品体验闭环。
+4. 中下：介绍“我们正在做的事「百梦」”。
+5. 下部：实习生参与内容、加分项、团队背景和联系方式。
+6. 底部：预留两个方形二维码占位，收尾文案为 `百梦 | 让每个人都能做自己的游戏`。
+
+新版使用当前仓库 `VectorEngine gpt-image-2-all` 路径生成底图：
+
+```text
+model: gpt-image-2-all
+size: 1536x3840
+reference image 1: 用户提供的上一版海报截图
+reference image 2: 百梦气泡共创logo方向图
+output: output/imagegen/baimeng-recruitment-rollup/baimeng-recruitment-rollup-background-gpt-image-2-all.png
+```
+
+最终输出：
+
+```text
+output/imagegen/baimeng-recruitment-rollup/baimeng-recruitment-rollup-final-cn.png
+output/imagegen/baimeng-recruitment-rollup/baimeng-recruitment-rollup-final-cn-preview.png
+```

docs/design/CHILD_MOTION_EDUTAINMENT_DISCOVER_ENTRY_2026-05-09.md

@@ -48,7 +48,7 @@
 1. 发现页隐藏“寓教于乐”标签；
 2. 隐藏“寓教于乐”标签下内容；
 3. 该内容线内容不进入推荐、今日、分类、排行和搜索结果；
-4. 该内容线内容完全不可见，公开作品搜索、作品号搜索直达、公开详情深链、浏览历史入口等平台公开入口都不能打开该内容。
+4. 该内容线内容完全不可见，公开作品搜索、作品号搜索直达、公开详情深链、浏览历史入口、创作入口和创作页作品架等平台入口都不能打开或展示该内容。
 
 ## 4. 内容识别规则
 
@@ -114,4 +114,23 @@ no
 4. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx` 已复用同一过滤 helper，避免推荐运行态自动启动寓教于乐作品，并在公开详情、作品号直达和公开详情深链等公开入口保留不可见保护。
 5. 浏览历史入口会优先按当前公开作品集合匹配作品标签；匹配到“寓教于乐”作品且开关关闭时不再展示历史入口。
 6. `/child-motion-demo` 本地动作 Demo 直达路由也复用同一开关；开关关闭时不匹配独立 Demo 应用，回落到主站入口。
-7. 定向回归覆盖在 `src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`src/components/platform-entry/platformEdutainmentVisibility.test.ts` 和 `src/routing/appRoutes.test.ts`，包含频道顺序、开关关闭、普通列表过滤、搜索过滤、作品号直达拦截、Demo 直达路由拦截和精确标签识别。
+7. `宝贝识物` 创作入口和创作页作品架也复用同一开关；开关关闭时不展示模板入口，也不展示本地宝贝识物草稿或已发布卡片。
+8. 定向回归覆盖在 `src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`src/components/platform-entry/platformEdutainmentVisibility.test.ts`、`src/components/platform-entry/platformEntryCreationTypes.test.ts` 和 `src/routing/appRoutes.test.ts`，包含频道顺序、开关关闭、普通列表过滤、搜索过滤、作品号直达拦截、Demo 直达路由拦截、创作入口隐藏和精确标签识别。
+
+## 9. 第 4 项作品架 / 广场接入边界
+
+`宝贝识物` 首关的公开作品展示接入按以下口径收口：
+
+1. 平台公共作品模型新增 `sourceType = edutainment`，当前只承接 `templateId = baby-object-match`、`templateName = 宝贝识物`。
+2. `宝贝识物` 作品仍必须携带精确等于“寓教于乐”的公开标签，才会进入“发现 / 寓教于乐”频道。
+3. `宝贝识物` 不因为模板名自动归入寓教于乐，也不因为近似标签归入寓教于乐。
+4. 第 4 项只负责公开作品卡片、发现页专属频道、公开详情、分享作品号和开关隐藏保护。
+5. 创作模板、image-2 资产生成、发布接口、运行时开始游戏和关卡状态由对应线程接入；当前公共作品卡直接透传后续数据源提供的 `publicWorkCode`，不在前端新增最终作品号前缀规则。
+6. 在创作和运行时链路真正接入前，公开详情内的启动、改造、编辑和点赞只做保护性占位，不新增玩法规则。
+
+当前工程落点：
+
+1. `src/components/rpg-entry/rpgEntryWorldPresentation.ts` 定义 `PlatformEdutainmentGalleryCard` 与 `isEdutainmentGalleryEntry`。
+2. `src/components/rpg-entry/RpgEntryHomeView.tsx` 将 `宝贝识物` 卡片识别为寓教于乐公开作品，并继续从推荐、今日、分类、排行和搜索结果中过滤。
+3. `src/components/platform-entry/PlatformWorkDetailView.tsx` 在公开详情中显示 `宝贝识物` 类型标签，并继续复用作品号复制和分享链路。
+4. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx` 已识别 `edutainment` 公共作品，避免落入 RPG 默认详情、推荐运行态或错误的改造链路。

docs/design/PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md

@@ -7,7 +7,7 @@
 创作 Tab 恢复为模板选择入口，但不回到旧的大卡片选择面板：
 
 1. 首屏保留现有创作页布局骨架，顶部标题固定为“10分钟创作一个精品互动玩法”。
-2. 选择模板入口改为横向 Tab，数据来自 `src/config/newWorkEntryConfig.ts` 的可见玩法配置。
+2. 选择模板入口改为横向 Tab，数据来自 `GET /api/creation-entry/config` 返回的可见玩法配置。
 3. 默认选中“拼图”模板，并在创作 Tab 内直接展示拼图创作表单。
 4. 智能创作入口从可见模板中隐藏，保留既有 `creative-agent` 运行链路用于后续内部恢复或草稿目标打开。
 5. 草稿、发现、我的等一级 Tab 职责不变，作品管理仍在草稿 Tab。
@@ -18,7 +18,7 @@
 
 ```text
 标题：10分钟创作一个精品互动玩法
-模板 Tab：拼图 / 方洞挑战 / 视觉小说 / AIRP
+模板 Tab：拼图 / 抓大鹅 / 视觉小说（敬请期待）/ AIRP
 默认内容：拼图创作表单
 ```
 
@@ -34,21 +34,24 @@
 1. 打开“创作”一级 Tab 时默认停留在拼图 Tab，不主动创建拼图 session。
 2. 点击拼图表单“生成草稿”后，才创建拼图 session 并执行 `compile_puzzle_draft`。
 3. 拼图表单内的模板按钮使用 `tablist / tab` 语义，点击后只填充画面描述。
-4. 点击非拼图且已开放的模板 Tab 时，进入该玩法既有工作台；未开放模板保持禁用。
+4. 点击非拼图且已开放的模板 Tab 时，进入该玩法既有工作台；视觉小说与 AIRP 当前保持敬请期待禁用态。
 5. `creative-agent` 不出现在模板 Tab 和选择弹层中，不再作为创作 Tab 首屏入口。
+6. 方洞挑战暂时从创作页完全隐藏，不出现在模板 Tab、旧选择弹层和创作 Hub 卡片中；既有作品链路继续保留。
 
 ## 4. 验收
 
 1. 点击“创作”后首屏出现“10分钟创作一个精品互动玩法”。
 2. 顶部选择模板入口为 Tab，拼图 Tab 默认 `aria-selected=true`。
 3. 创作 Tab 默认显示拼图创作表单内容，且不显示旧“Hi, 朋友”、输入框或智能创作快捷按钮。
-4. 隐藏的智能创作类型不出现在模板 Tab、旧选择弹层和创作 Hub 卡片中。
+4. 隐藏的智能创作类型与方洞挑战不出现在模板 Tab、旧选择弹层和创作 Hub 卡片中。
 5. 草稿页返回创作页后仍回到同一模板入口，并可保留拼图表单草稿内容。
 
 ## 5. 嵌入式表单 UI 细节
 
 2026-05-10 补充：抓大鹅与视觉小说作为创作 Tab 内嵌表单时，风格类横滑选择器应统一使用浅底卡片、柔和玫瑰色选中态和小圆点确认标记。不要使用大面积黑色渐变、黑底胶囊标签或高饱和红色外框，以免在输入框下方误读为错误提示。
 
+2026-05-10 追加：视觉小说画风选项已改为使用 `public/visual-novel-style-references/` 下由 VectorEngine `gpt-image-2-all` 生成的参考图，作为横向卡片主视觉。
+
 嵌入式表单控件保持以下口径：
 
 1. 大文本输入框使用白底、低饱和边框和轻量 focus ring。

docs/design/PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md

@@ -11,7 +11,7 @@
 3. 原“排行”页内容并入“发现”页的子 Tab 中，不再作为一级主 Tab 独立展示。
 4. 创作页只保留新建创作入口；原创作页作品列表拆到一级“草稿” Tab，替换原“存档” Tab。
 5. 原“存档”列表结构并入“我的”页面的“玩过”列表弹层，作为每个已玩作品的可继续存档入口。
-6. 移动端推荐页与底部 Tab 栏参考用户给定样式，使用大画面推荐流、顶部品牌/通知、悬浮胶囊底部导航；保留当前平台已有明暗两套主题色 token。
+6. 移动端推荐页与底部 Tab 栏参考用户给定样式，使用大画面推荐流、顶部品牌与悬浮胶囊底部导航；右上角不保留通知按钮，账号相关入口统一进入“我的”和账号面板；保留当前平台已有明暗两套主题色 token。
 
 ## 2. 状态映射
 
@@ -114,3 +114,13 @@
 - 未登录用户点击推荐页封面时，再次打开同一个登录弹窗；登录成功后由既有受保护动作继续进入作品详情或玩法入口。
 - 未登录状态下点击“下一个”只切换下一张推荐封面，不触发登录弹窗，也不启动玩法。
 - 已登录用户继续沿用推荐页内嵌运行态、上下滑切换和底部“下一个”行为。
+
+## 10. 2026-05-11 草稿生成中与新完成标记
+
+草稿生成过程页允许用户直接返回创作中心并自由使用平台其它功能：
+
+- 点击生成过程页的返回按钮时，当前生成任务继续在后台执行，页面回到创作中心，不清空生成状态。
+- 用户再进入草稿 Tab 并点击同一草稿时，若生成仍未完成，进入对应生成过程页查看最新进度；若已完成，直接进入对应结果页。
+- 草稿作品卡在生成中展示“生成中”状态标记；新生成完成且用户尚未查看的草稿在卡片右上角展示红点。
+- 底部一级“草稿”Tab 在存在未查看新完成草稿时展示红点；用户点击查看带红点的作品后，该作品红点消失。若草稿页已无任何带红点作品，底部“草稿”Tab 红点同步消失。
+- 生成完成时如果用户仍停留在对应生成过程页，可自动进入结果页；如果用户已经回到创作中心或其它功能页，不打断当前操作。

docs/experience/AGENT_UI_CHANGELOG.md

@@ -122,6 +122,7 @@
 ## 9. 2026-05-08 创作首页通知入口下线
 
 - `CreativeAgentHome` 顶栏右上角不再展示“通知与账户”按钮，避免创作首页把通知入口放在首屏高频区域。
+- 2026-05-12 平台入口页同步移除移动端和桌面端右上角通知铃铛；移动端顶栏只保留品牌，未登录时保留登录按钮，桌面端只保留账号入口。
 - 账号入口仍保留在侧边栏底部，创作首页顶栏维持左侧菜单、居中品牌的轻量结构。
 - 当前账号相关入口统一保留在平台首页受保护动作、个人页、存档页与账号弹窗，不再占用全局悬浮层。
 
@@ -220,4 +221,12 @@
 
 ---
 
+## 19. 2026-05-12 登录协议与个人页法律入口
+
+- 登录弹窗的法律协议确认应挂在短信 / 密码登录提交按钮上方，法律链接只打开独立 `LegalDocumentModal`，不能顺手勾选同意。
+- 法律弹窗通过 portal 挂到 `body` 时必须显式带 `platform-theme--*` 和高于登录遮罩的层级，否则容易丢主题变量或被登录弹窗遮住。
+- “我的”页常用功能区固定为 3 列，法律信息区放在设置入口下方；备案号作为外链进入工信部备案站，入口保持轻量，不在页面内展开长文。
+
+---
+
 _文档目的：交接给下一个 Agent 时，优先读本文件 + `UI_CODING_STANDARD.md`，再改 `uiAssets.ts` / `App.tsx` / `index.css`。_

docs/prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md

@@ -96,7 +96,7 @@ Match3D 必须形成独立玩法域，后续技术方案至少需要覆盖：
 2. 创建流程采用入口表单收集关键配置。
 3. 表单必须在进入结果页前确认：
    - 题材主题
-   - 3D 素材风格
+   - 2D 素材风格
    - 难度选项
 4. `需要消除次数` 与难度 `1~10` 数值不再作为独立输入框展示，由难度选项派生。
 5. 生成抓大鹅草稿消耗 `20` 光点，生成按钮必须显式展示。
@@ -110,7 +110,7 @@ Match3D 必须形成独立玩法域，后续技术方案至少需要覆盖：
 13. 清空圆形空间中全部物品即胜利。
 14. 倒计时结束或备选栏满即失败。
 15. 胜利 / 失败后展示结算界面。
-16. 入口页的 3D 素材风格选择会进入素材图提示词，并作为结果页手动 Rodin 3D 模型生成的默认提示词依据。
+16. 入口页的 2D 素材风格选择会进入素材图提示词，并作为后续物品素材新增和重绘的默认提示词依据。
 17. 点击、入槽、消除、失败、胜利的即时反馈效果由前端先行呈现，后端负责权威确认、状态落库和成绩可信性。
 
 ---
@@ -124,7 +124,7 @@ Match3D 必须形成独立玩法域，后续技术方案至少需要覆盖：
 3. 不做排行榜正式展示。
 4. 不做道具，但需要预留功能口。
 5. 不做洗牌、重置、旋转、放大等局内操作。
-6. 不做真实 3D 模型。
+6. 不做首屏真实 3D 模型生成；当前草稿生成以多视角 2D 物品素材为主，并写入 OSS。
 7. 不做真实 3D 物理遮挡。
 8. 不做真实物理碰撞结算。
 9. 不做必须试玩通关才能发布的门槛。
@@ -143,7 +143,7 @@ Match3D 首版参考拼图后期的入口表单收集方式，而不是早期的
 表单的职责是帮助用户确认可以直接编译 demo 的最小配置：
 
 1. 题材主题。
-2. 3D 素材风格。
+2. 2D 素材风格。
 3. 游戏难度选项。
 
 `需要消除次数` 与游戏难度数值仍属于后端会话配置，但不再要求用户手填。当前入口页固定采用以下映射：
@@ -152,7 +152,7 @@ Match3D 首版参考拼图后期的入口表单收集方式，而不是早期的
 轻松 -> 需要消除 8 次，难度 2
 标准 -> 需要消除 12 次，难度 4
 进阶 -> 需要消除 16 次，难度 6
-硬核 -> 需要消除 20 次，难度 8
+硬核 -> 需要消除 21 次，难度 8
 ```
 
 ## 6.2 必填配置
@@ -161,7 +161,7 @@ Match3D 首版参考拼图后期的入口表单收集方式，而不是早期的
 
 题材决定后续生成或选择物品素材的方向。用户可以自定义主题，例如水果、玩具、食物、符号等。
 
-首版 demo 不接入真实图片生成。当前运行态可消除物统一使用题材方向的 25 个积木件类型表现，不使用透明气泡，也不在图案上放文字标识。前端首版用差异化颜色、积木造型和 3D 程序化模型表现可消除物，避免玩家在堆叠状态下难以辨认。
+当前抓大鹅草稿会按难度生成题材物品：素材图切割出的多视角 2D 图片必须转存 OSS，并随作品 profile 的 `generatedItemAssets` 持久化。运行态优先使用这些生成图片；只有图片缺失、读取失败或未进入生成素材模式时，才回退到默认积木件视觉键。默认素材不使用透明气泡，也不在图案上放文字标识。
 
 可消除物尺寸使用五档相对体积规则：XL 型相对体积为 `1.60~2.30`，L 型为 `1.25~1.60`，M 型为 `1.00`，XS 型为 `0.65~0.85`，S 型为 `0.35~0.50`。单局中 XL / L / M / XS / S 按本局使用的消除物类型数的 `20% / 30% / 30% / 15% / 5%` 分配；非整数配额按最大余数补齐，确保总数等于本局使用类型数量。同一关卡内同一个颜色和造型的物品只能对应一个尺寸档位；可存在同尺寸但不同颜色和造型的物品。后端运行态通过 `radius` 下发权威尺寸，前端只按快照表现。
 
@@ -183,19 +183,25 @@ Match3D 首版参考拼图后期的入口表单收集方式，而不是早期的
 
 首版 demo 中，用户只需凭感觉选择难度；具体难度规则由系统内部解释。后续优化阶段再细化难度曲线、生成算法和遮挡策略。
 
-### 3D 素材风格
+### 2D 素材风格
 
-入口页在题材主题与难度之间展示 `3D素材风格` 横向滑动选择。首批固定选项为：
+入口页在题材主题与难度之间展示 `2D素材风格` 横向滑动选择。首批固定选项为：
 
 ```text
-黏土手作 / 低多边形 / 玩具塑料 / 木质雕刻 / 体素积木 / 金属机甲 / 自定义
+扁平图标 / 赛璐璐卡通 / 像素复古 / 手绘水彩 / 贴纸描边 / 厚涂图标 / 自定义
 ```
 
 每个内置选项使用 VectorEngine `gpt-image-2-all` 生成的画风参考图展示；参考图保存在 `public/match3d-style-references/`，只作为入口选择的视觉提示，不作为用户上传参考图。选择内置风格时，前端提交 `assetStyleId`、`assetStyleLabel` 与对应 `assetStylePrompt`。选择 `自定义` 时必须弹出独立面板，用户填写描述后才允许应用；自定义描述作为 `assetStylePrompt` 进入后端生成链路。
 
 ## 6.3 参考图片
 
-抓大鹅入口页不展示参考图片上传。题材表现先由题材文本和草稿切割图片链路承接；后续需要 3D 模型时，在结果页 `3D素材` Tab 以切割图片作为图生模型参考图手动触发。
+抓大鹅入口页不展示参考图片上传。题材表现由题材文本和草稿切割图片链路承接；草稿生成阶段会生成多视角 2D 物品素材并写入作品 profile。结果页 `素材配置 > 物品` 继续承接物品素材预览、删除、批量新增和音效配置。
+
+## 6.4 生成音效开关
+
+抓大鹅入口页在生成按钮前提供 `生成音效` Toggle，默认关闭。关闭时，草稿生成只保存 `generatedItemAssets[].soundPrompt`，不调用 Vidu 生成点击音效。
+
+用户打开 Toggle 后，前端在创建会话和执行 `match3d_compile_draft` 时提交 `generateClickSound=true`。后端完成物品名称与 `soundPrompt` 生成后，在图片素材生成阶段为每个生成物品调用 Vidu 生成点击音效，并把结果写入对应 `generatedItemAssets[].clickSound`。音效生成复用通用创作音频接口和资产落点；结果页仍保留单个物品音效的手动补生成入口。
 
 ---
 
@@ -222,9 +228,9 @@ Match3D 首版参考拼图后期的入口表单收集方式，而不是早期的
 
 ## 7.3 素材生成边界
 
-抓大鹅草稿生成链路会生成首批 `3` 个题材物品素材：文本模型生成物品名，VectorEngine 生成 `2*2` 素材图并切割独立图片。入口页选择的 `assetStylePrompt` 必须写入素材图提示词；结果页手动 Rodin 图生模型时，继续以该物品图片和默认提示词作为起点。
+抓大鹅草稿生成链路会根据难度生成题材物品素材：文本模型生成物品名，VectorEngine 分批生成 `1:1` 素材图并切割为每个物品 `5` 张不同视角图片，再转存 OSS。入口页选择的 `assetStylePrompt` 必须写入素材图提示词；结果页批量新增物品时继续以该风格作为默认提示词起点。
 
-生成出的独立图片先作为草稿页 `3D素材` Tab 的预览资产返回，状态为 `image_ready`，模型文件为空。正式平台资产绑定、Rodin 生成模型转存和二次编辑流程以后续技术方案为准。
+生成出的独立图片必须作为结果页 `素材配置 > 物品` 的预览资产返回。图片素材生成成功时 `generatedItemAssets[].status = image_ready`，并携带 `imageViews[]`，兼容字段 `imageSrc` / `imageObjectKey` 指向首张视角图；正式平台资产绑定和更完整的二次编辑流程以后续技术方案为准。
 
 ## 7.4 发布前试玩
 
@@ -277,13 +283,16 @@ totalItemCount = clearCount * 3
 
 每种物品数量必须是 `3` 的倍数，避免生成无法通关的局。
 
-生成的消除物类型数由用户填写的需要消除次数决定：
+生成的消除物类型数由难度档位决定：
 
 ```text
-itemTypeCount = clearCount <= 25 ? clearCount : 25
+轻松 = 3
+标准 = 9
+进阶 = 15
+硬核 = 21
 ```
 
-当 `clearCount <= 25` 时，本局生成的 `itemTypeId` 数量等于 `clearCount`，每种类型默认生成 `3` 件；当 `clearCount > 25` 时，本局最多生成 `25` 种 `itemTypeId`，后续消除组按这 `25` 种类型轮转补齐，且每种类型最终数量仍必须保持 `3` 的倍数。
+当前四档难度分别生成 `3 / 9 / 15 / 21` 种 `itemTypeId`。历史草稿若仍保留 `clearCount = 20` 的硬核配置，运行时和素材生成都必须兼容映射为 `21` 种物品，不得回退成 `20` 种。
 
 同一局内这些类型必须分别使用不同的形状和颜色组合，不能出现两个组看起来像同一种物体的情况。
 
@@ -297,12 +306,14 @@ itemTypeCount = clearCount <= 25 ? clearCount : 25
 
 ## 8.5 物品资产
 
-首版 demo 使用 2D 图案素材。
+当前 demo 使用生成 2D 图片优先、默认积木兜底的物品资产策略。
 
-1. demo 至少提供 `25` 种彼此不同的颜色与几何造型组合素材，支撑 `clearCount > 25` 时的类型上限。
+1. demo 至少提供 `25` 种彼此不同的颜色与几何造型组合默认素材，支撑 `clearCount > 25` 时的类型上限和图片缺失兜底。
-2. 当前 demo 使用 25 个积木件视觉键作为默认素材池；前端首版必须把这些视觉键映射为无文字的纯色 2D 图标和程序化 3D 积木模型，不能显示为透明气泡或文字标记。
+2. 有 `generatedItemAssets[].imageViews`、`imageSrc` 或 `imageObjectKey` 时，运行态与备选栏必须优先读取该 2D 图片素材；默认积木件只作为加载失败或图片缺失时的兜底素材池。
-3. 后续可以尝试替换为伪 3D 或 3D 模型。
+3. 前端读取 generated legacy 图片必须通过 `/api/assets/read-url` 换签后加载；不得直接把 `/generated-match3d-assets/...` 当裸 URL 请求。
-4. 用户题材主题后续会映射为符合常识预期的物品集合。
+4. 运行态 `match3d-type-01/02/03` 等类型按类型编号顺序映射到生成出的图片素材列表；后续更大生成数量时，素材列表顺序必须继续与类型编号稳定对应。
+5. 默认积木视觉键仍需映射为无文字的纯色 2D 图标，不能显示为透明气泡或文字标记。
+6. 用户题材主题后续会映射为符合常识预期的物品集合。
 
 示例：水果题材可以对应红色苹果、黄色香蕉、紫色葡萄等。
 
@@ -332,7 +343,7 @@ itemTypeCount = clearCount <= 25 ? clearCount : 25
 
 飞行动画过程中，物品不再与其他物品产生碰撞。
 
-当前 3D 实验模式下，物品进入备选栏后必须从圆形空间的物理世界移除；备选栏只展示该物品同款 3D 模型的独立预览，固定为斜 `45` 度便于识别，不再参与场内碰撞、重力或堆叠。
+物品进入备选栏后必须从圆形空间的可点击列表移除；备选栏展示该物品同款 2D 素材图，不再参与场内点击、遮挡或堆叠。
 
 前端播放即时反馈的同时，必须向后端提交点击意图。后端确认后固化入槽结果；后端拒绝时，前端恢复物品位置和备选栏表现。
 
@@ -342,7 +353,7 @@ itemTypeCount = clearCount <= 25 ? clearCount : 25
 
 1. 每次点击进入即时反馈流程后，前端先把物品表现为进入备选栏。
 2. 备选栏中每出现 `3` 个相同物品 id，前端立即播放自动消除效果并腾出格子。
-3. 3D 模式下，备选栏格子展示从场内取出的同款 3D 模型预览，视角固定斜 `45` 度，不使用另一套不一致的 UI 图标；托盘预览必须共享一个 WebGL renderer，并按 `7` 格容器实际宽高把模型居中摆放到对应格子，不能因多个预览上下文导致中心场地模型不可见；WebGL 回退或 `2D` 模式下才使用保留的 2D 图标。
+3. 备选栏格子展示从场内取出的同款 2D 素材图，不使用另一套不一致的 UI 图标；图片缺失或读取失败时才使用保留的默认图标。
 4. 后端确认后固化真实备选栏和消除结果；若后端返回状态不一致，前端必须以最新后端快照校正。
 5. 如果备选栏满且无法消除，前端可以立即展示失败过渡，最终失败状态以后端确认为准。
 
@@ -669,11 +680,12 @@ GET /api/runtime/match3d/runs/:runId
 
 ## 14.2 入口表单
 
-入口表单只展示三个输入块：
+入口表单只展示四个输入块：
 
 1. `想做一个什么题材的抓大鹅？` 大文本输入框。
-2. `3D素材风格` 横向滑动风格卡，最后一个为 `自定义`。
+2. `2D素材风格` 横向滑动风格卡，最后一个为 `自定义`。
 3. `难度` 选项按钮。
+4. `生成音效` Toggle，默认关闭。
 
 入口页不展示参考图、`需要消除次数` 数值输入、`难度数值` 滑杆，也不展示 `题材 / 物品 / 难度` 三个摘要框。`需要消除次数` 和 `difficulty` 由难度选项派生后提交给后端。
 
@@ -702,24 +714,25 @@ GET /api/runtime/match3d/runs/:runId
 首版 PRD 对应 demo 验收标准：
 
 1. 用户可从平台创作入口进入“抓大鹅”模板。
-2. 入口表单能确认题材主题、3D 素材风格和难度选项，并提交派生后的消除次数与难度数值。
+2. 入口表单能确认题材主题、2D 素材风格和难度选项，并提交派生后的消除次数与难度数值。
 3. 入口页不展示参考图上传。
 4. 内置风格显示画风参考图，自定义风格通过独立面板填写并进入提交 payload。
 5. 移动端入口页所有内容一屏展示，不产生纵向滚动。
-6. 系统可生成待发布结果页，并在草稿中返回首批切割图片素材预览。
+6. `生成音效` 关闭时草稿生成不产生 `clickSound`；打开时首批生成物品随图片素材生成并持久化点击音效。
-7. 用户可编辑游戏名称、标签、封面图等基础信息。
+7. 系统可生成待发布结果页，并在草稿中返回首批多视角 2D 切割图片素材预览。
-8. 用户可发布前试玩，且试玩失败不阻断发布。
+8. 用户可编辑游戏名称、标签、封面图等基础信息。
-9. 运行态能展示圆形空间、倒计时、物品和 `7` 格备选栏。
+9. 用户可发布前试玩，且试玩失败不阻断发布。
-10. 物品可重叠、遮挡、堆叠。
+10. 运行态能展示圆形空间、倒计时、物品和 `7` 格备选栏；存在 `generatedItemAssets` 图片素材时必须优先展示生成 2D 素材，而不是默认积木素材。
-11. 被完全遮挡物品不可点击，露出可点击区域的物品可点击。
+11. 物品可重叠、遮挡、堆叠。
-12. 点击通过后物品飞入备选栏。
+12. 被完全遮挡物品不可点击，露出可点击区域的物品可点击。
-13. 备选栏中 `3` 个相同物品 id 自动消除。
+13. 点击通过后物品飞入备选栏。
-14. 清空空间中全部物品后胜利。
+14. 备选栏中 `3` 个相同物品 id 自动消除。
-15. 倒计时结束或备选栏满后失败。
+15. 清空空间中全部物品后胜利。
-16. 胜利结算展示使用时间。
+16. 倒计时结束或备选栏满后失败。
-17. 失败结算展示完成进度和重新开始按钮。
+17. 胜利结算展示使用时间。
-18. 局内即时反馈由前端先行呈现，关键状态以后端确认快照校正。
+18. 失败结算展示完成进度和重新开始按钮。
-19. 相关中文文档通过编码检查。
+19. 局内即时反馈由前端先行呈现，关键状态以后端确认快照校正。
+20. 相关中文文档通过编码检查。
 
 ---
 

docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md

@@ -51,7 +51,7 @@
 外部仓库文件只作为玩法语义参考，不能作为目录结构迁入依据：
 
 | 外部参考                                        | 可参考内容                   | Genarrative 落点                                                  |
-| --- | --- | --- |
+| ----------------------------------------------- | ---------------------------- | ----------------------------------------------------------------- |
 | `interface/routes/visual.js`                    | 视觉小说创作和运行时路由语义 | `server-rs/crates/api-server/src/visual_novel.rs`                 |
 | `interface/handlers/visual/sendActionStream.js` | 流式动作推进事件             | Axum SSE handler + `shared-contracts` typed envelope              |
 | `interface/handlers/visual/getHistory.js`       | 历史记录读取                 | 平台 runtime history API                                          |
@@ -69,7 +69,7 @@
 
 ### 3.1 必须完成的模板闭环
 
-1. 平台创作中心展示 `视觉小说` 入口，并在实现完成后从 `open: false` 改为 `open: true`。
+1. 平台创作中心展示 `视觉小说` 入口；2026-05-11 起当前运营状态回退为 `open: false`，入口显示敬请期待，不允许创建新视觉小说草稿。
 2. 创作者可选择 `idea`、`document`、`blank` 三种起点创建视觉小说底稿。
 3. Agent 或表单工作台生成 / 编辑同一份 `VisualNovelResultDraft`。
 4. 结果页可编辑世界观、角色、场景、剧情阶段、资产和运行时配置。
@@ -160,8 +160,8 @@
 5. 玩家身份。
 6. 3 到 6 个主要角色。
 7. 3 到 8 个可用场景。
-7. 3 到 6 个剧情阶段。
+8. 3 到 6 个剧情阶段。
-8. 初始场景、初始旁白和第一轮可选行动。
+9. 初始场景、初始旁白和第一轮可选行动。
 
 ### 5.2 文档创建 `document`
 
@@ -399,7 +399,15 @@ export type VisualNovelAgentActionKind =
 ```ts
 export type VisualNovelAgentStreamEvent =
   | { type: 'start'; sessionId: string }
-  | { type: 'phase'; phase: 'perception' | 'reasoning' | 'drafting' | 'reflection' | 'finalizing' }
+  | {
+      type: 'phase';
+      phase:
+        | 'perception'
+        | 'reasoning'
+        | 'drafting'
+        | 'reflection'
+        | 'finalizing';
+    }
   | { type: 'text_delta'; text: string }
   | { type: 'draft_patch'; patch: VisualNovelDraftPatch }
   | { type: 'action_required'; action: VisualNovelAgentPendingAction }
@@ -559,7 +567,7 @@ export type VisualNovelRuntimeStreamEvent =
 ### 9.1 创作 session
 
 | 方法   | 路由                                                               | 用途                     |
-| --- | --- | --- |
+| ------ | ------------------------------------------------------------------ | ------------------------ |
 | `POST` | `/api/creation/visual-novel/sessions`                              | 创建视觉小说创作 session |
 | `GET`  | `/api/creation/visual-novel/sessions/{session_id}`                 | 读取 session snapshot    |
 | `POST` | `/api/creation/visual-novel/sessions/{session_id}/messages`        | 非流式发送创作消息       |
@@ -570,7 +578,7 @@ export type VisualNovelRuntimeStreamEvent =
 ### 9.2 作品草稿与发布
 
 | 方法        | 路由                                                    | 用途                             |
-| --- | --- | --- |
+| ----------- | ------------------------------------------------------- | -------------------------------- |
 | `GET`       | `/api/creation/visual-novel/works`                      | 读取当前用户视觉小说作品草稿列表 |
 | `GET`       | `/api/creation/visual-novel/works/{profile_id}`         | 读取作品详情                     |
 | `PUT/PATCH` | `/api/creation/visual-novel/works/{profile_id}`         | 更新作品草稿                     |
@@ -580,7 +588,7 @@ export type VisualNovelRuntimeStreamEvent =
 ### 9.3 运行时
 
 | 方法   | 路由                                                     | 用途                                 |
-| --- | --- | --- |
+| ------ | -------------------------------------------------------- | ------------------------------------ |
 | `GET`  | `/api/runtime/visual-novel/gallery`                      | 读取平台聚合后的视觉小说公开作品列表 |
 | `POST` | `/api/runtime/visual-novel/works/{profile_id}/runs`      | 创建测试或正式 run                   |
 | `GET`  | `/api/runtime/visual-novel/runs/{run_id}`                | 读取 run snapshot                    |
@@ -628,7 +636,7 @@ GET  /api/runtime/profile/save-archives
 ### 10.1 crate 职责
 
 | crate / 层                             | 职责                                                          |
-| --- | --- |
+| -------------------------------------- | ------------------------------------------------------------- |
 | `server-rs/crates/module-visual-novel` | 纯领域规则：草稿校验、step 解析、run 状态推进、历史重生成边界 |
 | `server-rs/crates/shared-contracts`    | DTO、请求响应、SSE envelope、草稿和运行时契约                 |
 | `server-rs/crates/spacetime-module`    | 表、reducer、procedure、migration 和事务编排                  |
@@ -655,7 +663,7 @@ GET  /api/runtime/profile/save-archives
 新增表必须同步 `migration.rs`、表目录和 bindings：
 
 | 表                                   | 用途                            |
-| --- | --- |
+| ------------------------------------ | ------------------------------- |
 | `visual_novel_agent_session`         | 创作 session 主表               |
 | `visual_novel_agent_message`         | 创作消息和模型回复              |
 | `visual_novel_work_profile`          | 视觉小说作品草稿 / 发布 profile |
@@ -684,27 +692,27 @@ GET  /api/runtime/profile/save-archives
 
 ### 11.1 入口配置
 
-当前 `src/config/newWorkEntryConfig.ts` 已存在：
+入口配置事实源已经迁移到 SpacetimeDB 的 `creation_entry_type_config` 表，默认种子位于 `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs`。2026-05-11 起视觉小说当前默认状态为：
 
 ```ts
 {
   id: 'visual-novel',
   title: '视觉小说',
-  subtitle: '敬请期待',
+  subtitle: '分支叙事体验',
   badge: '敬请期待',
   visible: true,
   open: false,
 }
 ```
 
-实现完成后更新为：
+重新开放创建时再通过后台入口开关或默认种子更新为：
 
 ```ts
 {
   id: 'visual-novel',
   title: '视觉小说',
-  subtitle: 'AI 生成可玩的视觉小说',
+  subtitle: '分支叙事体验',
-  badge: '新玩法',
+  badge: '可创建',
   visible: true,
   open: true,
 }
@@ -781,6 +789,8 @@ service client 要复用现有请求封装、鉴权和错误提示风格，不
 3. 生成草稿按钮。
 4. 错误、忙碌与禁用态。
 
+视觉画风卡片使用 `public/visual-novel-style-references/` 下的 `gpt-image-2-all` 参考图，分别对应映画动画、水彩绘本、像素霓虹、水墨幻想、柔彩校园和暗色哥特。卡片只承载图像和标签，不额外展示说明文案。
+
 点击生成草稿后进入 `visual-novel-generating` 过程页，过程页复用平台已有生成进度面板，展示一句话输入、画风和草稿生成阶段；完成后自动进入 `visual-novel-result` 草稿页。
 
 不展示：
@@ -976,7 +986,7 @@ V1 默认提供平台统一存档能力；如果平台存档 UI 当前按槽位
 ### 16.1 并行批次总览
 
 | 批次    | 可并行任务                         | 进入条件                                      | 汇合点                                 |
-| --- | --- | --- | --- |
+| ------- | ---------------------------------- | --------------------------------------------- | -------------------------------------- |
 | Batch 0 | `VN-00`                            | PRD 已冻结                                    | 所有人以本文为唯一口径                 |
 | Batch 1 | `VN-01`、`VN-02`、`VN-03`、`VN-04` | `VN-00` 完成                                  | 契约、领域、UI 骨架、Prompt 口径可对齐 |
 | Batch 2 | `VN-05`、`VN-06`、`VN-07`、`VN-08` | `VN-01` 产出契约初稿；`VN-02` 产出表草案      | 后端 API、前端创作、前端运行时可联调   |
@@ -993,7 +1003,7 @@ V1 默认提供平台统一存档能力；如果平台存档 UI 当前按槽位
 ### 16.2 并行任务具体要求速查表
 
 | 任务                          | 可并行窗口       | 输入依赖                                | 必须完成                                                                        | 禁止事项                                                        | 验收口径                                                                                                   |
-| --- | --- | --- | --- | --- | --- |
+| ----------------------------- | ---------------- | --------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
 | `VN-00` 口径冻结              | Batch 0          | 本 PRD、旧 TXT 文档、Hermes 决策记录    | 冻结 `visual-novel` 只做模板玩法、平台接口、删除回放；标注旧文档冲突口径        | 不再使用“原样迁入外部平台工程”作为实现目标                      | 文档和 Hermes 记录明确三条硬边界；`npm run check:encoding` 通过                                            |
 | `VN-01` 契约与领域            | Batch 1          | PRD 第 6 到 8 章契约                    | TS contracts、Rust shared-contracts、`module-visual-novel`、领域单测            | 不写 HTTP、DB reducer、LLM、UI；不出现 replay 类型              | TS/Rust 契约一致；草稿校验、step 解析、状态推进、重生成测试通过                                            |
 | `VN-02` SpacetimeDB 与 facade | Batch 1          | `VN-01` 契约草案、SpacetimeDB 约束文档  | 表、reducer/procedure、migration、表目录、bindings、`spacetime-client` facade   | 不手改 bindings 绕过 schema；不建 replay 表或私有 save 表       | schema 可生成；表目录写明 event 不是回放；`cargo check -p spacetime-client` 通过                           |
@@ -1744,7 +1754,7 @@ VN-11 从 Batch 1 开始持续运行，最终阻塞发布。
 
 ### 17.1 正向验收
 
-1. `visual-novel` 入口可见并可点击创建。
+1. `visual-novel` 入口当前可见但处于敬请期待禁用态；重新开放 `open=true` 后，再验收点击创建闭环。
 2. 一句话创建能生成可编辑底稿。
 3. 文档创建能读取平台文档资产并生成底稿。
 4. 空白创建能进入结果页。

docs/prd/BABY_OBJECT_MATCH_EDUTAINMENT_TEMPLATE_PRD_2026-05-11.md

@@ -0,0 +1,99 @@
+# 宝贝识物寓教于乐模板 PRD 2026-05-11
+
+## 1. 目标
+
+新增寓教于乐内容线的创作模板：
+
+```text
+宝贝识物
+```
+
+创作者必须通过该模板创作并发布作品后，用户才能在寓教于乐板块体验对应关卡。
+
+本模板只服务儿童动作 Demo 内容线，不把普通教育题材作品自动归入寓教于乐。
+
+## 2. 创作输入
+
+创作者必须填写两个物品名称：
+
+1. 物品 A 名称；
+2. 物品 B 名称。
+
+两个名称都必须去除首尾空白后非空。当前阶段不新增题材、难度、计时、失败次数、分数、体力或递增规则。
+
+## 3. 生成规则
+
+提交后生成一份宝贝识物草稿，草稿包含：
+
+1. 模板 ID：`baby-object-match`；
+2. 模板名称：`宝贝识物`；
+3. 两个物品；
+4. 两个物品图；
+5. 作品标签。
+
+物品图使用 VectorEngine `gpt-image-2-all` / image-2 生成。图片生成只能走后端或后续后端预留接口，前端不得泄露 `VECTOR_ENGINE_API_KEY`。
+
+本地 Demo 阶段若真实生图接口未接入完成，允许前端 service 返回明确标记为 `placeholder` 的占位图形，用于打通创作到结果页的交互链路；该占位结果不得伪装成正式 image-2 资产。
+
+## 4. 标签规则
+
+发布作品必须携带精确标签：
+
+```text
+寓教于乐
+```
+
+标签识别只接受精确等于 `寓教于乐`。不接受 `儿童教育`、`动作教育`、`寓教于乐 ` 等近似标签。
+
+宝贝识物草稿与发布 payload 中都必须保留该标签。发布后的公开展示、搜索、深链和入口开关继续遵循 `CHILD_MOTION_EDUTAINMENT_DISCOVER_ENTRY_2026-05-09.md`。
+
+## 5. 结果页能力
+
+结果页展示：
+
+1. 作品名称；
+2. 两个物品名称；
+3. 两个物品图；
+4. 标签；
+5. 保存草稿；
+6. 发布；
+7. 试玩。
+
+结果页不展示长规则说明文案。试玩按钮直接进入宝贝识物首关本地运行态。
+
+试玩按钮进入宝贝识物首关运行态，运行态消费当前草稿中的两个物品名称和两张物品图，不重新生成或改写物品内容。
+
+## 6. 发布后体验
+
+发布完成后作品应进入寓教于乐内容线，并在寓教于乐入口开启时可被板块消费。
+
+入口关闭时，发布作品完全不可见，不能通过推荐、发现普通频道、搜索、作品号、公开详情深链或浏览历史访问。
+
+## 7. 与运行时线程的边界
+
+本 PRD 同步约束首关运行态，已确认规则包括：
+
+1. 礼物盒打开在本地调试绑定 `F` 键；
+2. 每轮仅中间礼物盒跳出的物品随机；左右两侧篮子固定为当前草稿两个物品的顺序；
+3. 下一关按钮当前占位；
+4. 不新增用户未确认的计时、失败次数、分数、体力或难度递增。
+5. 屏幕中上方字幕固定为“将物品放入对应的篮子里”。
+6. 礼物盒位于屏幕中下方，任意手抬起后打开并跳出下一个随机物品。
+7. 屏幕下方左侧和右侧分别展示两个固定篮子，左侧固定使用草稿第一个物品图，右侧固定使用草稿第二个物品图。
+8. 明确左手连续横向移动达到阈值时将当前物品送入左侧篮子，明确右手连续横向移动达到阈值时将当前物品送入右侧篮子；选篮不使用动作名判定，侧别未知的手部轨迹不参与选篮。
+9. 正确时展示“真棒”字幕和正确特效；错误时展示“再想一想吧”字幕和错误特效，物品回到中央。
+10. 成功 20 次后展示“恭喜你！小朋友！”字幕和特效，并展示“再来一次”和“下一关”按钮。
+11. 当前本地 Demo 阶段音效与语音播报接口只预留调用点，不在前端写死外部硬件或服务接口。
+
+## 8. 验收
+
+1. 创作入口显示 `宝贝识物` 并可进入模板表单。
+2. 未填写任一物品名称时不能生成草稿。
+3. 生成草稿后进入结果页，展示两个物品名称和物品图。
+4. 草稿标签中始终包含精确 `寓教于乐`。
+5. 发布 payload 始终包含精确 `寓教于乐`。
+6. 发布完成后出现分享弹窗或发布完成状态。
+7. 前端不读取或暴露 VectorEngine 密钥。
+8. 结果页试玩进入宝贝识物运行态，不再显示“试玩关卡正在接入中”。
+9. 运行态可通过 `F` 打开礼物盒，通过鼠标左键拖动映射左手横向移动，通过鼠标右键拖动映射右手横向移动。
+10. 成功 20 次后出现“再来一次”和“下一关”按钮。

docs/prd/BARK_BATTLE_BDD_2026-05-11.md

@@ -0,0 +1,412 @@
+# 汪汪声浪大作战 / bark-battle BDD 验收场景
+
+## 背景
+
+- 需求来源：用户提供的视频 `C:\Users\DSK\Videos\一款双方比狗叫的游戏 - 1.一款双方比狗叫的游戏(Av116504192360177,P1).mp4`，并已在 `.hermes/plans/2026-05-11_144229-bark-battle-2d-game-bdd-ddd-tdd-plan.md` 中完成抽帧分析和玩法方案整理。
+- 玩法定位：浏览器 2D 声控狗叫对战小游戏，暂定中文名 `汪汪声浪大作战`，英文代号与 play type ID 建议为 `bark-battle`。
+- 核心玩法：双方狗狗在 30 秒限时内通过麦克风输入“狗叫声”进行声浪拔河；系统依据声音强度、有效叫声次数和叫声节奏计算推动力，实时推动顶部红蓝能量条；倒计时结束后按能量条位置判定胜负或平局。
+- 文档目的：为产品、测试、前端、后端在编码前统一可验证验收口径；本文只定义 PRD/BDD 级行为与测试映射，不实现工程代码。
+
+## 角色与目标
+
+### 主要角色
+
+- 浏览器玩家：进入 `bark-battle` 玩法，用麦克风发声参与对战。
+- 移动端玩家：在手机浏览器中进入玩法，需要看到核心游戏信息并完成授权、对战、结算。
+- 无麦克风或无 API 支持玩家：设备或浏览器不支持声控输入时，需要得到明确降级反馈并可返回。
+- 测试人员：依据本文场景验证权限、校准、叫声识别、能量条、胜负结算和布局兼容。
+- 前端实现人员：依据本文拆分 Web Audio 输入、领域规则、Phaser/DOM HUD 表现和自动化测试。
+
+### 用户目标
+
+- 玩家可以在开局前完成麦克风授权和环境噪音校准。
+- 玩家发出有效狗叫时，能看到叫声计数、狗狗动画、拟声词/冲击波以及能量条变化。
+- 低于阈值的背景噪音不会被误计为有效叫声。
+- 单局在 30 秒后给出明确胜负、平局和关键数据。
+- 移动端和不支持麦克风的环境不会进入不可操作状态。
+
+### 非目标
+
+- MVP 不要求识别“是否真实狗叫”，不引入机器学习声纹/物种分类；有效输入以音量阈值、峰值间隔、持续时间和校准结果为准。
+- MVP 不要求实时联机对战；可先按“玩家 vs AI 对手”完成单机浏览器 runtime。
+- MVP 不要求成绩持久化、作品发布、作品架、广场和排行榜；若后续接入 Genarrative 作品闭环，需要另补玩法类型集成 PRD/技术文档。
+- MVP 不要求在 UI 中长期展示大段规则说明；游戏界面应保持倒计时、能量条、狗狗、麦克风状态和结算信息为主。
+- MVP 不处理竞技级反作弊；播放录音、拍桌、喊叫等非狗叫输入只作为后续公平性风险记录。
+
+## 业务规则口径
+
+- 单局时长：默认 30 秒，从正式进入 `playing` 阶段开始计时。
+- 能量条：使用 `-100` 到 `100` 的连续值表示，负数偏对手侧，正数偏玩家侧，`0` 为中线。
+- 平局阈值：倒计时结束时，若能量条绝对值小于或等于 `drawThreshold`，判定平局；具体数值由实现配置，但测试需可注入固定阈值。
+- 有效叫声：一次有效叫声至少满足：音量超过校准后的有效阈值、与上一次有效峰值间隔不小于 `minBarkGapMs`、持续时长在 `minBarkDurationMs` 到 `maxBarkDurationMs` 之间。
+- 背景噪音：校准阶段采集到的环境声用于计算动态阈值；低于阈值的输入不得增加叫声次数，也不得让能量条出现可见推进。
+- 推动力：玩家推动力由音量分数、有效叫声频率和连击加成组成；能量条按玩家推动力与对手推动力差值移动，并被限制在 `-100` 到 `100`。
+- UI 反馈：有效叫声应触发可观察反馈，包括玩家侧狗狗张嘴/吠叫动画、拟声词或冲击波；反馈不应遮挡倒计时和顶部能量条。
+
+## 中文 Gherkin 场景
+
+### 功能: 麦克风授权与开局准备
+
+```gherkin
+功能: 狗叫对战麦克风准备
+  为了让玩家能用声音参与对战
+  作为浏览器玩家
+  我希望游戏在正式开局前请求麦克风权限并完成环境校准
+
+  背景:
+    假如玩家进入 bark-battle 玩法页面
+    而且浏览器支持 navigator.mediaDevices.getUserMedia
+
+  场景: 玩家允许麦克风权限后进入环境噪音校准
+    当玩家同意浏览器麦克风授权
+    那么系统应进入环境噪音校准阶段
+    而且游戏不应在校准完成前进入 playing 阶段
+    而且界面应显示麦克风已授权的可观察状态
+
+  场景: 校准完成后进入开局倒计时
+    假如玩家已允许麦克风权限
+    而且系统已采集足够的环境噪音样本
+    当校准计算出有效叫声阈值
+    那么系统应进入开局倒计时阶段
+    而且倒计时结束后应进入 30 秒对战阶段
+    而且初始能量条应位于中线
+
+  场景: 玩家拒绝麦克风权限后不能开始声控对战
+    当玩家拒绝浏览器麦克风授权
+    那么系统应停留在无法声控游玩的状态
+    而且应提供重新授权或返回入口
+    而且不应进入校准、倒计时或 playing 阶段
+```
+
+### 功能: 环境噪音校准
+
+```gherkin
+功能: 环境噪音校准
+  为了减少背景噪音误触发
+  作为浏览器玩家
+  我希望游戏在开局前根据当前环境设置有效叫声阈值
+
+  场景: 安静环境生成低但非零的有效阈值
+    假如校准阶段采集到的环境噪音 RMS 稳定低于默认噪音基线
+    当系统完成校准
+    那么有效叫声阈值应高于环境噪音平均值
+    而且阈值不应低于系统配置的最小阈值
+
+  场景: 嘈杂环境生成更高的有效阈值
+    假如校准阶段采集到的环境噪音 RMS 高于默认噪音基线
+    当系统完成校准
+    那么有效叫声阈值应随环境噪音上调
+    而且低于该阈值的后续输入不应计为有效叫声
+
+  场景: 校准期间无法获得有效音频样本
+    假如麦克风授权成功但音频样本持续为空或不可读
+    当校准超过系统配置的最长等待时间
+    那么系统应展示麦克风输入不可用状态
+    而且应提供重试校准入口
+    而且不应直接开始对战
+```
+
+### 功能: 有效叫声计数
+
+```gherkin
+功能: 有效叫声计数
+  为了把玩家的狗叫行为转换为可计分输入
+  作为玩家
+  我希望每次符合规则的短促叫声只被计数一次
+
+  背景:
+    假如游戏处于 30 秒 playing 阶段
+    而且系统已完成环境噪音校准
+
+  场景: 单次超过阈值且间隔足够的叫声计数加一
+    假如玩家当前叫声次数为 0
+    而且上一次有效叫声时间早于 minBarkGapMs
+    当麦克风输入出现一次超过有效阈值且持续时长合规的峰值
+    那么玩家叫声次数应变为 1
+    而且玩家侧应出现一次吠叫动画反馈
+    而且画面应出现一次拟声词或冲击波反馈
+
+  场景: 持续噪音不会被无限计数
+    假如玩家当前叫声次数为 1
+    当麦克风输入持续超过阈值但没有新的峰值间隔
+    那么玩家叫声次数不应在每个 tick 中持续增加
+    而且系统最多只应记录当前连续声音段内的一次有效叫声
+
+  场景: 间隔过短的连续峰值不重复计数
+    假如玩家刚刚产生一次有效叫声
+    当麦克风输入在 minBarkGapMs 内再次出现峰值
+    那么玩家叫声次数不应增加
+    而且连击或推动力不应因该峰值重复加成
+```
+
+### 功能: 声音大小和连续叫声推动能量条
+
+```gherkin
+功能: 声浪推动能量条
+  为了复刻双方比狗叫的核心体验
+  作为玩家
+  我希望更响、更连续的有效叫声能把顶部能量条推向自己一侧
+
+  背景:
+    假如游戏处于 30 秒 playing 阶段
+    而且能量条当前位于中线
+
+  场景: 玩家推动力高于对手时能量条向玩家侧移动
+    假如玩家在短时间窗口内产生多次有效叫声
+    而且玩家推动力高于对手推动力
+    当系统推进一个 simulation tick
+    那么能量条数值应向玩家侧增加
+    而且顶部红蓝能量条的玩家侧占比应变大
+
+  场景: 连续大声叫声触发更强反馈
+    假如玩家连续产生多次高于强叫声阈值的有效叫声
+    当系统计算玩家连击加成
+    那么玩家侧推动力应高于单次普通叫声推动力
+    而且玩家侧声浪或冲击波反馈应比普通叫声更明显
+    但是反馈不应遮挡倒计时和能量条
+
+  场景: 能量条到达边界后不会越界
+    假如能量条已经接近玩家侧最大值
+    而且玩家推动力仍高于对手推动力
+    当系统推进多个 simulation tick
+    那么能量条数值不应超过 100
+    而且界面不应显示超出容器范围的能量条
+
+  场景: 对手推动力高于玩家时能量条向对手侧移动
+    假如对手推动力高于玩家推动力
+    当系统推进一个 simulation tick
+    那么能量条数值应向对手侧减少
+    而且顶部红蓝能量条的对手侧占比应变大
+```
+
+### 功能: 低噪音和无效输入过滤
+
+```gherkin
+功能: 背景噪音过滤
+  为了避免环境声替玩家自动得分
+  作为玩家
+  我希望低于阈值或不合规的声音不会被当作有效狗叫
+
+  背景:
+    假如游戏处于 30 秒 playing 阶段
+    而且系统已完成环境噪音校准
+
+  场景: 低于阈值的背景噪音不计数
+    当麦克风只接收到低于有效叫声阈值的背景噪音
+    那么玩家叫声次数不应增加
+    而且玩家侧不应播放吠叫动画
+    而且能量条不应因为该背景噪音出现可见推进
+
+  场景: 过短脉冲不计为有效叫声
+    假如麦克风输入峰值超过有效阈值
+    但是持续时长短于 minBarkDurationMs
+    当系统完成该声音段判定
+    那么玩家叫声次数不应增加
+    而且不应触发连击加成
+
+  场景: 过长持续声被削弱为单段输入
+    假如麦克风输入持续超过有效阈值
+    但是持续时长长于 maxBarkDurationMs
+    当系统完成该声音段判定
+    那么系统不应按多个叫声重复计数
+    而且该声音段的推动力应按持续噪音削弱规则处理
+```
+
+### 功能: 倒计时与胜负结算
+
+```gherkin
+功能: 狗叫对战胜负结算
+  为了让单局对抗有明确目标
+  作为玩家
+  我希望 30 秒倒计时结束后根据能量条位置得到胜负或平局
+
+  背景:
+    假如游戏已经进入 30 秒 playing 阶段
+
+  场景: 倒计时每秒递减并在归零时停止对战输入
+    当系统时间从 30 秒推进到 0 秒
+    那么界面应显示倒计时归零
+    而且系统应进入 finished 结算阶段
+    而且归零后的麦克风输入不应再改变本局能量条和叫声次数
+
+  场景: 玩家侧占优时判定玩家胜利
+    假如倒计时归零时能量条数值大于 drawThreshold
+    当系统进入结算阶段
+    那么系统应判定玩家胜利
+    而且结算面板应展示玩家叫声次数、最大音量和声浪评分
+    而且应提供再来一局入口
+
+  场景: 对手侧占优时判定玩家失败
+    假如倒计时归零时能量条数值小于 -drawThreshold
+    当系统进入结算阶段
+    那么系统应判定对手胜利
+    而且结算面板应展示玩家叫声次数、最大音量和声浪评分
+    而且应提供再来一局入口
+
+  场景: 能量条接近平衡时判定平局
+    假如倒计时归零时能量条数值位于 -drawThreshold 到 drawThreshold 之间
+    当系统进入结算阶段
+    那么系统应判定为平局
+    而且结算面板应展示双方接近平衡的结果
+    而且应提供再来一局入口
+```
+
+### 功能: 再来一局与状态重置
+
+```gherkin
+功能: 对战重开
+  为了让玩家快速再次挑战
+  作为玩家
+  我希望结算后可以开始新的一局且旧状态不会污染新局
+
+  场景: 结算后点击再来一局重置本局状态
+    假如系统处于 finished 结算阶段
+    而且结算面板展示上一局结果
+    当玩家选择再来一局
+    那么系统应重置剩余时间为 30 秒
+    而且能量条应回到中线
+    而且玩家叫声次数、最大音量、连击和胜负结果应清零
+    而且系统应重新进入校准或开局倒计时流程
+
+  场景: 结算后返回玩法入口
+    假如系统处于 finished 结算阶段
+    当玩家选择返回入口
+    那么系统应离开当前对战运行态
+    而且不应继续采集麦克风输入
+```
+
+### 功能: 移动端布局
+
+```gherkin
+功能: 移动端 bark-battle 布局
+  为了让手机浏览器玩家可以完成声控对战
+  作为移动端玩家
+  我希望核心信息在窄屏中保持可见且可操作
+
+  场景: 移动端进入对战页面时核心元素可见
+    假如玩家使用宽度不超过 430px 的移动端视口
+    当玩家进入 bark-battle 页面
+    那么顶部能量条应完整显示在首屏可见区域内
+    而且倒计时应可见
+    而且双方狗狗主体不应被权限、设置或说明面板长期遮挡
+    而且非关键设置应收起到菜单或次级入口中
+
+  场景: 移动端授权和开始必须由用户手势触发
+    假如玩家使用移动端浏览器
+    当玩家点击开始或授权入口
+    那么系统才应请求麦克风权限并激活音频上下文
+    而且不应在页面自动加载时直接启动 AudioContext
+
+  场景: 移动端结算面板不遮挡主要操作
+    假如玩家在移动端完成一局对战
+    当系统展示结算面板
+    那么胜负结果、再来一局和返回入口应在不横向滚动的情况下可见
+    而且结算面板不应要求玩家阅读大段规则说明才能继续
+```
+
+### 功能: 无 getUserMedia 或不可用环境降级
+
+```gherkin
+功能: 无麦克风 API 降级
+  为了避免不支持设备进入卡死状态
+  作为无麦克风或无 API 支持玩家
+  我希望系统明确告知无法声控游玩并提供退出路径
+
+  场景: 当前浏览器不支持 getUserMedia
+    假如玩家设备不支持 navigator.mediaDevices.getUserMedia
+    当玩家进入 bark-battle 页面
+    那么系统应显示设备或浏览器不支持麦克风输入的状态
+    而且应提供返回入口
+    而且不应展示可开始声控对战的按钮
+
+  场景: getUserMedia 调用失败但浏览器 API 存在
+    假如浏览器支持 getUserMedia
+    但是请求麦克风时返回 NotFoundError 或 NotReadableError
+    当系统接收到失败结果
+    那么系统应展示麦克风不可用状态
+    而且应提供重试授权或返回入口
+    而且不应进入 playing 阶段
+
+  场景: 非安全上下文导致麦克风不可用
+    假如页面运行在浏览器不允许麦克风的非安全上下文
+    当玩家进入 bark-battle 页面
+    那么系统应展示当前环境无法使用麦克风的状态
+    而且应提示使用受支持的安全环境或返回
+    而且不应开始对战倒计时
+```
+
+### 功能: 刷新与退出时释放麦克风资源
+
+```gherkin
+功能: 麦克风资源释放
+  为了保护用户隐私并避免浏览器资源泄漏
+  作为浏览器玩家
+  我希望离开对战时麦克风采集被停止
+
+  场景: 对战中离开页面停止采集
+    假如玩家已经授权麦克风并处于 playing 阶段
+    当玩家离开 bark-battle 页面或运行态卸载
+    那么系统应停止当前 MediaStream 的所有音轨
+    而且不应继续推进本局 simulation tick
+
+  场景: 刷新页面后不沿用旧局临时状态
+    假如玩家在 playing 阶段刷新页面
+    当页面重新加载 bark-battle
+    那么系统应重新进入权限检查或授权准备状态
+    而且不应沿用刷新前的剩余时间、能量条和叫声次数作为新局结果
+```
+
+## 测试映射
+
+| 场景 | 测试层级 | 建议目标文件 | 自动化状态 |
+| --- | --- | --- | --- |
+| 玩家允许麦克风权限后进入环境噪音校准 | application/component | `src/games/bark-battle/application/BarkBattleController.test.ts`, `src/games/bark-battle/ui/BarkBattlePermissionPanel.test.tsx` | planned |
+| 校准完成后进入开局倒计时 | application/unit | `src/games/bark-battle/application/BarkBattleController.test.ts`, `src/games/bark-battle/domain/BarkBattleSession.test.ts` | planned |
+| 玩家拒绝麦克风权限后不能开始声控对战 | application/component | `src/games/bark-battle/application/BarkBattleController.test.ts`, `src/games/bark-battle/ui/BarkBattlePermissionPanel.test.tsx` | planned |
+| 安静环境生成低但非零的有效阈值 | unit | `src/games/bark-battle/domain/BarkNoiseCalibration.test.ts` | planned |
+| 嘈杂环境生成更高的有效阈值 | unit | `src/games/bark-battle/domain/BarkNoiseCalibration.test.ts` | planned |
+| 校准期间无法获得有效音频样本 | application/component | `src/games/bark-battle/application/BarkBattleController.test.ts`, `src/games/bark-battle/ui/BarkBattlePermissionPanel.test.tsx` | planned |
+| 单次超过阈值且间隔足够的叫声计数加一 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
+| 持续噪音不会被无限计数 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
+| 间隔过短的连续峰值不重复计数 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
+| 玩家推动力高于对手时能量条向玩家侧移动 | unit | `src/games/bark-battle/domain/EnergyTugOfWar.test.ts` | planned |
+| 连续大声叫声触发更强反馈 | unit/integration/component | `src/games/bark-battle/domain/BarkBattleScoring.test.ts`, `src/games/bark-battle/ui/BarkBattleHud.test.tsx` | planned |
+| 能量条到达边界后不会越界 | unit | `src/games/bark-battle/domain/EnergyTugOfWar.test.ts` | planned |
+| 对手推动力高于玩家时能量条向对手侧移动 | unit | `src/games/bark-battle/domain/EnergyTugOfWar.test.ts` | planned |
+| 低于阈值的背景噪音不计数 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
+| 过短脉冲不计为有效叫声 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
+| 过长持续声被削弱为单段输入 | unit | `src/games/bark-battle/domain/BarkDetector.test.ts` | planned |
+| 倒计时每秒递减并在归零时停止对战输入 | unit/application | `src/games/bark-battle/domain/BarkBattleSession.test.ts`, `src/games/bark-battle/application/BarkBattleController.test.ts` | planned |
+| 玩家侧占优时判定玩家胜利 | unit/component | `src/games/bark-battle/domain/BarkBattleSession.test.ts`, `src/games/bark-battle/ui/BarkBattleResultPanel.test.tsx` | planned |
+| 对手侧占优时判定玩家失败 | unit/component | `src/games/bark-battle/domain/BarkBattleSession.test.ts`, `src/games/bark-battle/ui/BarkBattleResultPanel.test.tsx` | planned |
+| 能量条接近平衡时判定平局 | unit/component | `src/games/bark-battle/domain/BarkBattleSession.test.ts`, `src/games/bark-battle/ui/BarkBattleResultPanel.test.tsx` | planned |
+| 结算后点击再来一局重置本局状态 | application/component | `src/games/bark-battle/application/BarkBattleController.test.ts`, `src/games/bark-battle/ui/BarkBattleResultPanel.test.tsx` | planned |
+| 结算后返回玩法入口 | integration/smoke | `src/games/bark-battle/application/BarkBattleController.test.ts`, Playwright 或人工 smoke 清单 | planned |
+| 移动端进入对战页面时核心元素可见 | component/visual/smoke | `src/games/bark-battle/ui/BarkBattleHud.test.tsx`, Playwright 移动端视口 smoke | planned |
+| 移动端授权和开始必须由用户手势触发 | infrastructure/application/e2e-smoke | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/application/__tests__/BarkBattleController.test.ts`, Playwright 移动端 smoke | planned |
+| 移动端结算面板不遮挡主要操作 | component/visual/smoke | `src/games/bark-battle/ui/__tests__/BarkBattleResultPanel.test.tsx`, Playwright 移动端视口 smoke | planned |
+| 当前浏览器不支持 getUserMedia | infrastructure/component | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/ui/__tests__/BarkBattlePermissionPanel.test.tsx` | planned |
+| getUserMedia 调用失败但浏览器 API 存在 | infrastructure/application/component | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/application/__tests__/BarkBattleController.test.ts`, `src/games/bark-battle/ui/__tests__/BarkBattlePermissionPanel.test.tsx` | planned |
+| 非安全上下文导致麦克风不可用 | infrastructure/application/component | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/application/__tests__/BarkBattleController.test.ts`, `src/games/bark-battle/ui/__tests__/BarkBattlePermissionPanel.test.tsx` | planned |
+| 对战中离开页面停止采集 | infrastructure/application/integration | `src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts`, `src/games/bark-battle/application/__tests__/BarkBattleController.test.ts` | planned |
+| 刷新页面后不沿用旧局临时状态 | integration/smoke | Playwright 或人工 smoke 清单 | planned |
+
+## 验收清单
+
+- [ ] 权限允许、拒绝、非安全上下文、API 不支持、麦克风未找到/不可读、AudioContext 被拦截、校准超时或样本不可读均有明确状态，且不会误进入 playing。
+- [ ] 校准阶段会影响有效叫声阈值，低噪音不会增加叫声计数。
+- [ ] 有效叫声计数具备阈值、峰值间隔、持续时长约束。
+- [ ] 能量条根据双方推动力差值双向移动，并限制在 `-100` 到 `100`。
+- [ ] 30 秒归零后停止本局输入影响，并按玩家胜利、对手胜利、平局三类结果结算。
+- [ ] 移动端核心元素可见，非关键设置收起，不在主画面堆叠长规则说明。
+- [ ] 离开页面或返回入口时停止麦克风采集。
+- [ ] 每个编码依据场景已在测试映射中标注测试层级和建议文件。
+
+## 开放问题
+
+1. MVP 是否确认只做“玩家 vs AI”，还是第一版需要双人同屏或联机对战？
+2. `drawThreshold`、`minBarkGapMs`、`minBarkDurationMs`、`maxBarkDurationMs` 的首版默认值由产品/调参阶段确认，还是先采用开发可配置默认值？
+3. 是否允许无麦克风设备提供键盘/点击备用输入？若允许，需要另补非声控模式场景；若不允许，当前降级只提供返回入口。
+4. 是否需要在结算中记录或上报成绩、最高音量、叫声次数和声浪评分？若需要，需补埋点/后端持久化场景。
+5. bark-battle 是否作为 Genarrative 正式 play type 接入创作入口、作品发布和广场，还是先作为独立 runtime 原型验证？
+6. 狗狗、背景、拟声词和冲击波素材来源是临时占位、AI 生成，还是复用项目现有素材管线？

docs/prd/PROFILE_LEGAL_INFO_AND_AUTH_AGREEMENT_PRD_2026-05-12.md

@@ -0,0 +1,90 @@
+# “我的”页签法律信息与登录协议确认 PRD
+
+## 1. 目标
+
+在平台“我的”页签底部补齐法律信息入口和备案信息；同时在登录弹窗中增加协议确认，用户首次登录必须手动勾选同意后才能继续登录。
+
+## 2. 入口与布局
+
+### 2.1 “我的”页签常用功能
+
+- 已登录用户在“我的”页签看到常用功能区。
+- 常用功能区移动端和网页端都使用 3 列网格。
+- 每个功能入口保持图标、主标题、短副标题结构。
+- 不新增独立“我的”页面，只扩展现有个人页签。
+
+### 2.2 法律信息区
+
+法律信息区放在“我的”页签底部、设置入口之后。
+
+区块内容：
+
+- 区块标题：`法律信息`。
+- 三个列表入口：
+  - `用户协议`
+  - `隐私政策`
+  - `免责声明`
+- 每个入口点击后打开独立模态面板，不在当前页签下方展开内容。
+- 备案信息固定显示在法律入口下方：
+  - 文案：`京ICP备2026025677号`
+  - 点击跳转到 `https://beian.miit.gov.cn/`
+  - 外链在新窗口打开，并使用 `rel="noreferrer"`。
+
+## 3. 法律内容面板
+
+### 3.1 内容来源
+
+三份法律内容读取仓库现有 Markdown 文件：
+
+- `media/files/user_agreement.md`
+- `media/files/privacy_policy.md`
+- `media/files/disclaimer.md`
+
+### 3.2 展示规则
+
+- 使用平台主题变量渲染，暗色和亮色主题都必须可读。
+- 面板最大高度不超过视口，正文区域内部滚动。
+- 标题固定在面板顶部，底部保留确认按钮 `我知道了`。
+- Markdown 首版只需要支持标题、段落、列表和加粗文本。
+- 不把 Markdown 原文作为纯文本整段堆叠，必须保留基本阅读层级。
+
+## 4. 登录协议确认
+
+### 4.1 展示位置
+
+登录弹窗的短信登录和密码登录表单都在提交按钮上方展示协议确认行：
+
+`我已阅读并同意《用户协议》《隐私政策》和《免责声明》`
+
+其中三段蓝色链接分别打开对应法律内容面板。
+
+### 4.2 勾选规则
+
+- 使用本地存储 key `genarrative.auth.legal-consent.v1` 记录是否已经确认。
+- 首次打开登录弹窗时，如果没有本地确认记录，勾选框默认为未选中。
+- 后续打开登录弹窗时，如果本地已有确认记录，勾选框默认为选中。
+- 用户未勾选时：
+  - 登录按钮禁用。
+  - 点击法律链接只打开内容面板，不自动勾选。
+- 用户勾选后：
+  - 立即写入本地确认记录。
+  - 短信登录和密码登录都可继续使用。
+
+## 5. 验收
+
+- 已登录“我的”页签常用功能区为 3 列。
+- “我的”页签底部出现 `法律信息`、三个入口和 `京ICP备2026025677号`。
+- 三个法律入口都能打开独立可滚动面板。
+- 备案号点击打开 `https://beian.miit.gov.cn/`。
+- 首次登录弹窗协议勾选为空，登录按钮禁用。
+- 勾选协议后登录按钮恢复可用，并持久化本地确认状态。
+- 再次打开登录弹窗时协议勾选默认选中。
+
+## 6. 2026-05-12 落地记录
+
+- 法律文档解析与弹窗复用 `src/components/common/legalDocuments.ts` 和 `src/components/common/LegalDocumentModal.tsx`。
+- “我的”页签在 `src/components/rpg-entry/RpgEntryHomeView.tsx` 中接入 3 列常用功能、法律入口和备案链接。
+- 登录协议确认在 `src/components/auth/LoginScreen.tsx` 中接入，短信登录和密码登录共用同一确认行。
+- 定向验证：
+  - `npm run test -- src/components/auth/AuthGate.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`
+  - `npx eslint src/components/auth/LoginScreen.tsx src/components/auth/AuthGate.test.tsx src/components/common/LegalDocumentModal.tsx src/components/common/legalDocuments.ts src/components/rpg-entry/RpgEntryHomeView.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx --max-warnings 0`

docs/prd/README.md

@@ -4,6 +4,7 @@
 
 ## 重点入口
 
+- [宝贝识物寓教于乐模板 PRD](./BABY_OBJECT_MATCH_EDUTAINMENT_TEMPLATE_PRD_2026-05-11.md)：定义寓教于乐内容线的 `宝贝识物` 创作模板，覆盖两个物品名称输入、image-2 物品图生成、精确 `寓教于乐` 标签、结果页和发布边界。
 - [AI 原生幕间文字游戏模板 PRD：参考 MOKU 的剧本模拟器闭环](./AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md)：参考 MOKU / 幕间类 AI 文游的剧本游乐场、自由行动、AI GM、记忆和模拟器强反馈经验，但只落为百梦 `text-game` 模板，复用平台接口，不迁入外部社区、支付、私有存档或回放。
 - [AI 原生视觉小说模板 PRD：TXT 玩法平台化接入](./AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md)：参考 `Interactive-fiction-backend` / `Interactive-fiction-frontend` 的 TXT 玩法经验，但只保留视觉小说模板创作与运行闭环，完全使用 Genarrative 平台接口，并明确删除回放和外部平台功能。
 - [AI 原生幸存者类游戏模板 PRD](./AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md)：定义 `survivor` 幸存者挑战模板，从 Agent 创作、结果页、资产、试玩、发布到后端权威配置与前端高频运行表现的完整闭环。
@@ -12,6 +13,7 @@
 - [AI 原生拼图玩法创作工具与玩法系统 PRD](./AI_NATIVE_PUZZLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-22.md)：拼图玩法创作、结果页、发布、广场和运行时主链路。
 - [AI 原生方洞挑战玩法创作工具与玩法系统 PRD](./AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md)：方洞挑战创作、发布与试玩闭环。
 - [后台管理独立前端工程 PRD](./ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)：后台管理端产品边界。
+- [“我的”页签法律信息与登录协议确认 PRD](./PROFILE_LEGAL_INFO_AND_AUTH_AGREEMENT_PRD_2026-05-12.md)：定义个人页法律入口、备案链接、法律内容弹窗和首次登录协议勾选规则。
 
 ## 使用规则
 

docs/technical/ADMIN_CREATION_ENTRY_SWITCH_CONFIG_2026-05-11.md

@@ -65,7 +65,7 @@ Admin Web
   -> spacetime-module creation_entry_type_config 表
 ```
 
-`visible=false` 会让创作中心不展示对应入口；`open=false` 会让前端展示锁定态；api-server 的运行态熔断继续以 `visible && open` 判断路由是否可用。
+`visible=false` 会让创作中心不展示对应入口；`open=false` 会让前端展示锁定态，并让 api-server 熔断对应玩法创作 / 运行态 API。隐藏入口但仍保留既有作品号、广场详情或试玩链路时，应只关闭 `visible`，不要关闭 `open`。
 
 ## 注意
 

docs/technical/AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md

@@ -10,6 +10,7 @@
 2. 当前设备识别方式与 `isCurrent` 语义
 3. 多端登录识别字段如何从 `refresh_session` 派生到 DTO
 4. Rust 首版在 Axum + 进程内 `module-auth` 下的最小实现边界
+5. `2026-05-13` 会话组合并展示与远端踢下线闭环修复口径
 
 ## 2. 当前基线
 
@@ -46,11 +47,16 @@
 3. 登录创建 session 时落库结构化客户端身份字段
 4. 会话列表返回多端识别所需字段，并兼容旧 `clientLabel`
 
-本阶段明确不包含：
+`2026-05-13` 起，本接口同时承担账号安全页的会话组读模型：
 
-1. `/api/auth/sessions/:sessionId/revoke`
+1. 后端按“同设备 + 同 IP”聚合活跃 `refresh_session`
-2. 前端完整消费全部新增字段
+2. 前端只消费后端聚合结果，不自行推断合并
-3. SpacetimeDB reducer / view 正式读表
+3. `POST /api/auth/sessions/{sessionId}/revoke` 已纳入 Rust 实现，用于踢下线非当前会话
+
+本阶段仍明确不包含：
+
+1. SpacetimeDB reducer / view 正式读表
+2. 登录方式、refresh token 轮换策略或账号安全页整体重设计
 
 ## 5. 请求与响应 contract
 
@@ -70,6 +76,8 @@
   "sessions": [
     {
       "sessionId": "usess_xxx",
+      "sessionIds": ["usess_xxx", "usess_yyy"],
+      "sessionCount": 2,
       "clientType": "web_browser",
       "clientRuntime": "chrome",
       "clientPlatform": "windows",
@@ -90,9 +98,12 @@
 
 字段说明：
 
-1. `clientLabel` 当前阶段继续兼容旧前端字段，值固定与 `deviceDisplayName` 保持一致
+1. `sessionId` 是聚合组代表会话 ID；若组内包含当前 `sid`，代表 ID 必须使用当前会话 ID
-2. `clientRuntime`、`clientPlatform`、`deviceDisplayName` 是多端识别首版最小新增字段
+2. `sessionIds` 是该聚合组内全部活跃 session ID，前端批量踢下线时逐个调用 revoke
-3. 小程序来源额外暴露 `miniProgramAppId`、`miniProgramEnv`
+3. `sessionCount` 是聚合组内 session 数量
+4. `clientLabel` 当前阶段继续兼容旧前端字段，值固定与 `deviceDisplayName` 保持一致
+5. `clientRuntime`、`clientPlatform`、`deviceDisplayName` 是多端识别首版最小新增字段
+6. 小程序来源额外暴露 `miniProgramAppId`、`miniProgramEnv`
 
 ### 5.3 失败响应
 
@@ -110,12 +121,25 @@
 1. 从 refresh cookie 读取当前原始 refresh token
 2. 在 Axum 侧计算 `sha256(refresh_token)`
 3. 与会话列表中的 `refresh_token_hash` 比较
-4. 命中则 `isCurrent = true`
+4. 同时读取 Bearer access token claims 中的 `sid`
+5. 聚合组内任意 session 命中当前 refresh hash 或当前 `sid`，则整组 `isCurrent = true`
 
 说明：
 
 1. 如果请求没有携带 refresh cookie，本接口仍可返回会话列表
-2. 此时全部会话的 `isCurrent` 都为 `false`
+2. 此时仍可通过 Bearer `sid` 标记当前组
+3. 当前组不允许在前端显示“踢下线”，当前设备退出必须走 `/api/auth/logout`
+
+## 6.1 会话组合并规则
+
+同设备同 IP 的 active refresh sessions 在后端合并为一条 DTO：
+
+1. 优先使用 `device_fingerprint + ip` 作为聚合 key
+2. 无 `device_fingerprint` 时退化为 `client_type + client_runtime + client_platform + device_display_name + user_agent + ip`
+3. `createdAt` 取组内最早 `created_at`
+4. `lastSeenAt` 取组内最新 `last_seen_at`
+5. `expiresAt` 取组内最新 `expires_at`
+6. `ipMasked` 仍只返回脱敏 IP
 
 ## 7. 多端标识派生规则
 
@@ -161,8 +185,21 @@
 负责：
 
 1. 读取 Bearer JWT 与 refresh cookie
-2. 把活跃会话映射成旧接口兼容 DTO
+2. 按同设备同 IP 聚合活跃会话
-3. 派生 `ipMasked` 与 `isCurrent`
+3. 把活跃会话组映射成旧接口兼容 DTO
+4. 派生 `ipMasked` 与 `isCurrent`
+5. 暴露 `POST /api/auth/sessions/{sessionId}/revoke`
+
+## 8.3 指定会话吊销接口
+
+`POST /api/auth/sessions/{sessionId}/revoke` 固定规则：
+
+1. Bearer JWT 必填
+2. 仅允许吊销当前用户自己的非当前会话
+3. 当前会话自吊销返回业务错误，提示使用退出登录
+4. 只撤销目标 `refresh_session`，不递增 `token_version`
+5. 撤销后同步 auth store 到 SpacetimeDB
+6. 认证中间件会校验 access token `sid` 对应 active `refresh_session`，因此被踢设备已有 access token 会立即失效
 
 ## 9. 测试策略
 
@@ -172,6 +209,9 @@
 2. 微信内 H5 登录后，会话列表返回 `wechat_h5 + wechat_embedded_browser`
 3. 显式小程序头优先于 `User-Agent` 判断
 4. 请求携带当前 refresh cookie 时，只有当前会话 `isCurrent = true`
+5. 同设备同 IP 会话会合并，并返回 `sessionIds/sessionCount`
+6. 合并组包含当前 `sid` 或当前 refresh hash 时，整组 `isCurrent = true`
+7. 指定远端会话吊销后，被踢设备 access token 立即无法通过认证
 
 ## 10. 完成定义
 
@@ -181,4 +221,6 @@
 2. 会话列表可区分普通浏览器、微信内 H5、小程序来源
 3. 同设备不同浏览器可在会话列表中清晰区分
 4. `clientLabel` 与新增多端字段都已稳定返回
-5. 文档、任务清单与测试已同步更新
+5. 同设备同 IP 的重复 active refresh sessions 已合并展示
+6. 非当前会话可通过真实 revoke 接口踢下线
+7. 文档、任务清单与测试已同步更新

docs/technical/BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md

@@ -0,0 +1,164 @@
+# 宝贝识物创作发布实现方案 2026-05-11
+
+## 1. 范围
+
+本方案对应第 2 线程：创作发布线程。
+
+本线程落地：
+
+1. 创作入口配置；
+2. 模板表单；
+3. 本地草稿生成 service；
+4. 结果页；
+5. 发布 payload 约束；
+6. 本地 Demo 运行态；
+7. 后端 image-2 / 作品持久化 / 运行态接口预留形状。
+
+本阶段运行态先做浏览器本地 Demo，并消费现有本地 mocap 动作数据源；正式硬件接口和摄像头调教在后续接口稳定后继续接入。
+
+## 2. 前端接入点
+
+新增玩法 ID：
+
+```text
+baby-object-match
+```
+
+用户展示名：
+
+```text
+宝贝识物
+```
+
+入口文件：
+
+1. `src/config/newWorkEntryConfig.ts`
+2. `src/components/platform-entry/platformEntryCreationTypes.ts`
+3. `src/components/platform-entry/PlatformEntryCreationTypeModal.tsx`
+4. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+
+`baby-object-match` 必须复用 `VITE_ENABLE_EDUTAINMENT_ENTRY` 开关；开关关闭时，创作类型弹层不展示 `宝贝识物`，创作页作品架不展示本地宝贝识物草稿或已发布作品卡，公开发现、搜索、详情、作品号和浏览历史也继续完全不可见。
+
+新增阶段：
+
+```text
+baby-object-match-workspace
+baby-object-match-generating
+baby-object-match-result
+baby-object-match-runtime
+```
+
+## 3. 契约
+
+前端共享契约放在：
+
+```text
+packages/shared/src/contracts/edutainmentBabyObject.ts
+```
+
+核心字段：
+
+1. `BabyObjectMatchDraft.templateId = "baby-object-match"`；
+2. `BabyObjectMatchDraft.templateName = "宝贝识物"`；
+3. `BabyObjectMatchDraft.themeTags` 必须包含精确 `寓教于乐`；
+4. `BabyObjectMatchItemAsset.generationProvider` 首版允许为 `vector-engine-gpt-image-2` 或 `placeholder`；
+5. `BabyObjectMatchPublishRequest.draft.themeTags` 发布前必须归一化补齐 `寓教于乐`。
+
+## 4. Service 边界
+
+前端 service 放在：
+
+```text
+src/services/edutainment-baby-object/babyObjectMatchClient.ts
+```
+
+首版提供：
+
+1. `createBabyObjectMatchDraft(payload)`；
+2. `saveBabyObjectMatchDraft(draft)`；
+3. `publishBabyObjectMatchWork(payload)`。
+
+当前后端正式接口未在本线程扩表落地，因此 service 先走本地 Demo 存储，并把 asset 结果标记为 `placeholder`。后续后端接入时，应替换为：
+
+```text
+POST /api/creation/edutainment/baby-object-match/drafts
+PUT  /api/creation/edutainment/baby-object-match/drafts/{draftId}
+POST /api/creation/edutainment/baby-object-match/drafts/{draftId}/publish
+```
+
+图片生成必须在后端调用 VectorEngine `gpt-image-2-all`，不得从前端直接调用外部图片接口。
+
+## 5. UI 边界
+
+工作台只展示两个必填输入和生成按钮。
+
+结果页只展示草稿核心信息、两个物品、保存草稿、发布、试玩。不在 UI 内写玩法说明长文案。
+
+移动端优先：表单和结果页使用单列布局，桌面端自然扩展为双列。
+
+## 6. 运行态边界
+
+前端运行态放在：
+
+```text
+src/components/edutainment-runtime/BabyObjectMatchRuntimeShell.tsx
+```
+
+运行态直接消费 `BabyObjectMatchDraft`，必须使用草稿中的两个物品名称和物品图。
+每轮只随机当前从礼物盒跳出的物品；左右篮子不随机交换，左侧固定为草稿 `itemAssets[0]`，右侧固定为草稿 `itemAssets[1]`。
+
+首关状态机：
+
+1. `waiting`：礼物盒关闭，等待任意手抬起；
+2. `active`：当前物品停留在屏幕中央；
+3. `correct`：展示“真棒”反馈，成功次数加 1；
+4. `wrong`：展示“再想一想吧”反馈，当前物品回到中央；
+5. `complete`：成功次数达到 20，展示“恭喜你！小朋友！”和按钮。
+
+动作输入：
+
+1. 任意手完成一次 `open_palm -> grab` 抓握序列：打开礼物盒并生成当前物品；
+2. 左手连续横向移动达到阈值：将当前物品送入左侧篮子；
+3. 右手连续横向移动达到阈值：将当前物品送入右侧篮子。
+
+运行态直接通过 `useMocapInput` 消费本地 mocap WebSocket `/stream`。选篮只使用明确 `leftHand` 或 `rightHand` 的连续横向轨迹阈值，不再通过 `wave_left_hand`、`wave_right_hand`、`wave` 等动作名触发；侧别为 `unknown` 的手部轨迹也不参与选篮，以避免多套判定误命中和连续误触发。当前本地 mocap 输出的 handedness 按摄像头视角标记，宝贝识物运行态必须先换算为用户身体视角：`rightHand` 轨迹映射玩家左手并进入左侧篮子，`leftHand` 轨迹映射玩家右手并进入右侧篮子。草稿试玩、发布后正式体验和热身关后的本地 Demo 都复用同一个运行态，因此三条入口都必须具备同一套动作控制能力。
+
+开发者调试输入：
+
+1. `F`：映射任意手抬起，打开礼物盒并生成当前物品；
+2. 鼠标左键按下并拖动：映射左手轨迹，抬起后将当前物品送入左侧篮子；
+3. 鼠标右键按下并拖动：映射右手轨迹，抬起后将当前物品送入右侧篮子。
+
+运行态不得新增计时、失败次数、分数、体力或难度递增规则。
+
+音效和语音播报当前只保留接口预留边界，正式语音接口后续接入。
+
+## 7. 发布约束
+
+发布前必须执行：
+
+1. 两个物品名非空；
+2. 两个物品名对应的 asset 存在；
+3. 标签补齐精确 `寓教于乐`；
+4. `publicationStatus` 从 `draft` 变为 `published`。
+
+发布后首版本地响应返回 `publicWorkCode`，用于分享弹窗；正式后端接入时 public code 生成规则需要纳入统一作品号服务。
+
+## 8. 热身关衔接
+
+`/child-motion-demo` 热身完成后的“开始游戏”按钮进入同一个 `BabyObjectMatchRuntimeShell`。
+
+热身关独立 Demo 没有创作者草稿上下文，因此使用固定本地 Demo 草稿承载两个物品，仅用于热身关后验证首关体验；正式平台体验仍必须从 `宝贝识物` 模板创作发布后进入寓教于乐板块。
+
+## 9. 验收命令
+
+```bash
+npm run test -- src/components/platform-entry/platformEntryCreationTypes.test.ts src/components/edutainment-creation/BabyObjectMatchWorkspace.test.tsx src/components/edutainment-result/BabyObjectMatchResultView.test.tsx src/components/edutainment-runtime/BabyObjectMatchRuntimeShell.test.tsx src/components/child-motion-demo/ChildMotionWarmupDemo.test.tsx src/services/edutainment-baby-object/babyObjectMatchClient.test.ts
+npx vitest run src/components/platform-entry/platformEdutainmentVisibility.test.ts src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/custom-world-home/creationWorkShelf.test.ts src/services/useMocapInput.test.ts src/services/child-motion-demo/childMotionDebugInput.test.ts src/routing/appRoutes.test.ts
+npx eslint src/components/platform-entry/platformEntryCreationTypes.ts src/components/platform-entry/platformEntryCreationTypes.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --ext .ts,.tsx --max-warnings 0
+npm run check:encoding
+npm run typecheck
+npm run build:raw
+```
+
+若后续接入真实 Rust API 和 SpacetimeDB 表，再补充 `npm run api-server`、`/healthz`、Rust contract / api-server / spacetime-client 定向测试和 migration 表目录更新。

docs/technical/BACKEND_TRACKING_EVENT_COVERAGE_2026-05-09.md

@@ -94,6 +94,7 @@ API Server 新增统一 helper：
 | `auth_phone_login_success` | `POST /api/auth/phone/login` |
 | `auth_me_view` | `GET /api/auth/me` |
 | `auth_sessions_view` | `GET /api/auth/sessions` |
+| `auth_revoke_session` | `POST /api/auth/sessions/{session_id}/revoke` |
 | `auth_refresh_success` | `POST /api/auth/refresh` |
 | `auth_logout` | `POST /api/auth/logout` |
 | `auth_logout_all` | `POST /api/auth/logout-all` |

docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md

@@ -0,0 +1,729 @@
+# bark-battle 2D Runtime 前端技术方案（2026-05-11）
+
+## 1. 背景与目标
+
+本方案基于 `.hermes/plans/2026-05-11_144229-bark-battle-2d-game-bdd-ddd-tdd-plan.md`，为“汪汪声浪大作战 / bark-battle”细化前端与浏览器游戏 runtime 的技术实现路线。
+
+本任务只产出技术方案，不直接实现代码。后续编码应以本文作为 runtime 层设计约束，再按 TDD 小步落地。
+
+### 1.1 玩法定位
+
+`bark-battle` 是一个声控拔河式 2D 浏览器小游戏：玩家对麦克风发出狗叫声，系统根据音量峰值、有效叫声次数和节奏计算本方声浪推动力，在限时 30 秒内推动顶部红蓝能量条，时间结束后按能量条偏向判定胜负。
+
+### 1.2 本文范围
+
+本文覆盖：
+
+- Phaser + TypeScript + Vite 栈选择
+- simulation / render / HUD 边界
+- 建议目录结构
+- 核心 domain 类型
+- Web Audio 输入适配
+- Phaser Scene 切分
+- DOM HUD 设计
+- 移动端与权限降级
+- 测试与验证命令
+
+本文不覆盖：
+
+- 后端表结构、持久化成绩、作品发布、广场接入
+- 实时多人对战协议
+- 复杂 AI 狗叫识别模型
+- 美术素材正式生产流程
+
+## 2. 技术栈选择
+
+### 2.1 推荐栈
+
+```text
+Runtime Renderer: Phaser 3
+Language: TypeScript
+Build: Vite
+Host UI: React / DOM overlay
+Audio Input: Web Audio API + MediaDevices.getUserMedia
+Test: Vitest + Testing Library + 浏览器 smoke / Playwright 可选
+```
+
+### 2.2 选择理由
+
+1. 玩法是横版 2D 舞台，核心表现是狗狗 sprite、声浪、拟声词、粒子、屏幕震动与能量条反馈，Phaser 对 2D 渲染、时间循环、sprite animation、camera、粒子和 Scene 生命周期支持成熟。
+2. 当前项目主前端已使用 TypeScript + Vite，继续复用现有构建和测试体系，避免引入独立构建链。
+3. 文字密集、权限提示、结算、设置和移动端响应式布局适合 DOM HUD；Canvas 保持负责 playfield 和动态特效。
+4. Web Audio API 可以在浏览器端完成 MVP 所需音量采样、RMS/peak 计算、环境噪音校准和输入归一化，不需要首版接入后端音频处理。
+
+### 2.3 不选择其它路线的原因
+
+- 不使用 Three.js / 3D：当前玩法画面是 2D 横版舞台，不需要 3D 相机、模型和材质管线。
+- 不把 HUD 全部塞入 Phaser Canvas：权限说明、重试、结算、移动端布局和可访问性更适合 DOM。
+- 不在前端实现正式业务真相：浏览器 runtime 可承载单局即时 simulation，但若后续涉及成绩、作品、排行榜、发布和奖励，必须交给后端投影/API 裁决。
+
+## 3. 总体架构
+
+### 3.1 分层总览
+
+```text
+React Runtime Shell
+  ├─ DOM HUD / Panels
+  │   ├─ PermissionPanel
+  │   ├─ TopEnergyBar
+  │   ├─ TimerChip
+  │   └─ ResultPanel
+  │
+  ├─ Application Controller
+  │   ├─ permission / calibration orchestration
+  │   ├─ simulation tick
+  │   ├─ audio sample submission
+  │   └─ snapshot publish
+  │
+  ├─ Pure Domain / Simulation
+  │   ├─ BarkBattleSession
+  │   ├─ BarkDetector
+  │   ├─ EnergyTugOfWar
+  │   ├─ BarkBattleScoring
+  │   └─ OpponentStrategy
+  │
+  ├─ Infrastructure Adapters
+  │   ├─ BrowserMicrophoneInput
+  │   ├─ AudioAnalyserSampler
+  │   └─ PhaserGameHost
+  │
+  └─ Phaser Renderer
+      ├─ BootScene
+      ├─ PreloadScene
+      ├─ BattleScene
+      ├─ FxScene / DebugScene（可选）
+      └─ Asset manifest
+```
+
+### 3.2 强制边界
+
+1. `domain/` 不依赖 Phaser、Web Audio、DOM、React、浏览器全局对象或后端 API。
+2. `domain/` 只接收 plain data，例如时间增量、归一化音量样本、对手 power、配置参数。
+3. `application/` 负责编排权限、校准、音频输入、AI 对手、tick 和 snapshot 分发。
+4. Phaser Scene 只消费 `BarkBattleSnapshot`，把 snapshot 映射成 sprite、动画、粒子、camera 和 sound effect；不得持有核心胜负、计数和能量条规则。
+5. DOM HUD 只消费 snapshot 和少量 runtime UI 状态，负责展示、按钮和弹层；不得重复实现核心胜负规则。
+6. 若后续接入平台作品/成绩/排行榜，前端只调用后端 API 和展示投影，不在本地绕过后端生成正式结论。
+
+## 4. 建议目录结构
+
+首版建议以独立 runtime 原型落在 `src/games/bark-battle/`，避免提前侵入平台创作链路。
+
+```text
+src/games/bark-battle/
+  domain/
+    BarkBattleTypes.ts
+    BarkBattleSession.ts
+    BarkDetector.ts
+    EnergyTugOfWar.ts
+    BarkBattleScoring.ts
+    OpponentStrategy.ts
+    __tests__/
+      BarkDetector.test.ts
+      EnergyTugOfWar.test.ts
+      BarkBattleSession.test.ts
+      BarkBattleScoring.test.ts
+
+  application/
+    BarkBattleController.ts
+    BarkBattleConfig.ts
+    BarkBattleSnapshotStore.ts
+    __tests__/
+      BarkBattleController.test.ts
+
+  infrastructure/
+    BrowserMicrophoneInput.ts
+    AudioAnalyserSampler.ts
+    MicrophonePermission.ts
+    __tests__/
+      BrowserMicrophoneInput.test.ts
+      AudioAnalyserSampler.test.ts
+
+  phaser/
+    BarkBattleGameHost.ts
+    scenes/
+      BarkBattleBootScene.ts
+      BarkBattlePreloadScene.ts
+      BarkBattleScene.ts
+      BarkBattleFxScene.ts
+    assets/
+      barkBattleAssetManifest.ts
+
+  ui/
+    BarkBattleRuntimeShell.tsx
+    BarkBattleHud.tsx
+    BarkBattlePermissionPanel.tsx
+    BarkBattleResultPanel.tsx
+    BarkBattleMobileControls.tsx
+    BarkBattleHud.css
+    __tests__/
+      BarkBattleHud.test.tsx
+      BarkBattlePermissionPanel.test.tsx
+      BarkBattleResultPanel.test.tsx
+```
+
+若后续进入 Genarrative 正式玩法类型闭环，再按 `genarrative-play-type-integration` 扩展到：
+
+```text
+src/components/bark-battle-runtime/BarkBattleRuntimeShell.tsx
+src/components/bark-battle-result/BarkBattleResultView.tsx
+src/services/barkBattleRuntimeClient.ts
+packages/shared/src/contracts/barkBattle.ts
+server-rs/crates/shared-contracts/src/bark_battle.rs
+```
+
+首版不建议直接新增后端表或正式作品链路，除非产品明确要求成绩、发布和广场能力。
+
+## 5. 核心 Domain 类型
+
+### 5.1 基础枚举与数值约定
+
+```ts
+export type BarkBattlePhase =
+  | 'permission'
+  | 'calibration'
+  | 'countdown'
+  | 'playing'
+  | 'finished'
+  | 'unavailable'
+
+export type BarkBattleSide = 'player' | 'opponent'
+
+export type BarkBattleWinner = BarkBattleSide | 'draw' | null
+
+export type BarkBattleDifficulty = 'easy' | 'normal' | 'hard'
+
+export type BarkBattleUiState =
+  | 'idle'
+  | 'permission-ready'
+  | 'microphone-authorized'
+  | 'calibrating'
+  | 'ready-countdown'
+  | 'playing'
+  | 'finished'
+  | 'microphone-unavailable'
+
+export type MicrophoneFailureReason =
+  | 'unsupported'
+  | 'permission-denied'
+  | 'non-secure-context'
+  | 'not-found'
+  | 'not-readable'
+  | 'audio-context-blocked'
+  | 'calibration-timeout'
+  | 'calibration-sample-unreadable'
+  | 'unknown'
+```
+
+关键数值：
+
+- `energy`: `-100..100`，正数偏玩家侧，负数偏对手侧。
+- `currentVolume`: `0..1`，音频采样归一化后的瞬时音量。
+- `recentPeak`: `0..1`，短窗口内峰值。
+- `power`: `0..1` 或 `0..100` 二选一，建议 domain 内统一 `0..1`，HUD 显示再转百分比。
+- `remainingMs`: 单局剩余毫秒。
+
+### 5.2 Snapshot
+
+```ts
+export type BarkBattleSnapshot = {
+  phase: BarkBattlePhase
+  uiState: BarkBattleUiState
+  errorReason: MicrophoneFailureReason | null
+  statusMessageKey: BarkBattleStatusMessageKey | null
+  elapsedMs: number
+  remainingMs: number
+  countdownMs: number
+  energy: number
+  player: BarkSideState
+  opponent: BarkSideState
+  winner: BarkBattleWinner
+  result: BarkBattleResult | null
+  lastEvents: BarkBattleVisualEvent[]
+}
+
+export type BarkSideState = {
+  side: BarkBattleSide
+  barkCount: number
+  currentVolume: number
+  recentPeak: number
+  combo: number
+  power: number
+  isBarking: boolean
+  lastBarkAtMs: number | null
+  maxVolume: number
+}
+
+export type BarkBattleResult = {
+  winner: BarkBattleWinner
+  finalEnergy: number
+  playerBarkCount: number
+  playerMaxVolume: number
+  playerAveragePower: number
+  score: number
+}
+
+export type BarkBattleStatusMessageKey =
+  | 'microphone-unsupported'
+  | 'microphone-permission-denied'
+  | 'microphone-non-secure-context'
+  | 'microphone-not-found'
+  | 'microphone-not-readable'
+  | 'microphone-audio-context-blocked'
+  | 'microphone-calibration-timeout'
+  | 'microphone-calibration-sample-unreadable'
+  | 'microphone-unknown-error'
+```
+
+### 5.3 输入样本与叫声事件
+
+```ts
+export type BarkAudioSample = {
+  atMs: number
+  volume: number
+  peak: number
+  rms: number
+}
+
+export type BarkDetectedEvent = {
+  id: string
+  atMs: number
+  side: BarkBattleSide
+  volume: number
+  strength: number
+  combo: number
+}
+```
+
+### 5.4 视觉事件
+
+视觉事件由 domain 或 application 生成，但只包含 plain data，不包含 Phaser 对象：
+
+```ts
+export type BarkBattleVisualEvent =
+  | {
+      type: 'bark-word'
+      id: string
+      side: BarkBattleSide
+      atMs: number
+      strength: number
+      text: 'BARK' | 'WOOF' | 'WAN' | 'WANGOOF'
+    }
+  | {
+      type: 'shockwave'
+      id: string
+      side: BarkBattleSide
+      atMs: number
+      strength: number
+    }
+  | {
+      type: 'combo-burst'
+      id: string
+      side: BarkBattleSide
+      atMs: number
+      combo: number
+    }
+```
+
+Phaser 只根据这些事件播放一次性特效，并维护已消费事件 ID，避免重复播放。
+
+## 6. Domain 模块职责
+
+### 6.1 BarkDetector
+
+职责：把连续音频样本转换为有效叫声事件。
+
+输入：
+
+- `BarkAudioSample`
+- 校准后的 `ambientNoiseFloor`
+- `barkThreshold`
+- `minBarkGapMs`
+- `minBarkDurationMs`
+- `maxBarkDurationMs`
+
+规则建议：
+
+1. 音量超过动态阈值进入 candidate 状态。
+2. 峰值回落到阈值以下或持续时长达到上限时结束 candidate。
+3. candidate 持续时间在 `80ms..1200ms` 且与上一次有效叫声间隔足够时，记为一次叫声。
+4. 长时间持续噪音不应无限计数，只能按冷却和峰值回落形成新事件。
+5. MVP 不要求识别“是否真狗叫”，先基于音量峰值、时长和间隔判断。
+
+### 6.2 EnergyTugOfWar
+
+职责：更新红蓝拉锯条。
+
+建议公式：
+
+```text
+playerPower = volumeScore * 0.65 + barkRateScore * 0.35 + comboBonus
+opponentPower = opponentStrategy.tick(...)
+energyDelta = (playerPower - opponentPower) * deltaSeconds * balanceFactor
+energy = clamp(energy + energyDelta, -100, 100)
+```
+
+约束：
+
+- `EnergyTugOfWar` 不知道玩家来自麦克风还是 mock input。
+- `EnergyTugOfWar` 不知道 Phaser 能量条宽度。
+- 平衡参数集中在 `BarkBattleConfig`，不要散落在 Scene 或 HUD 中。
+
+### 6.3 BarkBattleSession
+
+职责：管理局内 phase、计时、胜负和 snapshot。
+
+状态机建议：
+
+```text
+permission → calibration → countdown → playing → finished
+        ↘ unavailable
+```
+
+`phase` 只表达 runtime 是否可继续参与局内流程；所有麦克风不可用、权限失败、非安全上下文和校准失败都统一收敛到 `phase: 'unavailable'`，再通过 `uiState: 'microphone-unavailable'` 与 `errorReason` 区分 HUD 展示和重试策略，避免把基础设施错误枚举直接扩散成 domain 阶段。
+
+关键规则：
+
+- `countdown` 结束才进入 `playing`。
+- `playing` 时 `remainingMs` 随 tick 递减。
+- `remainingMs <= 0` 后进入 `finished`。
+- `energy > drawThreshold` 判定玩家胜利。
+- `energy < -drawThreshold` 判定对手胜利。
+- `abs(energy) <= drawThreshold` 判定平局。
+
+### 6.4 OpponentStrategy
+
+职责：为单机 MVP 提供对手推动力。
+
+```ts
+export interface OpponentStrategy {
+  tick(input: OpponentTickInput): OpponentTickOutput
+}
+```
+
+普通难度建议：
+
+- 周期性小叫声提供基础压力。
+- 每 3~6 秒一次短爆发。
+- 玩家大幅领先时可轻微增强，但不能追到不可赢。
+
+## 7. Web Audio 输入适配
+
+### 7.1 BrowserMicrophoneInput
+
+职责：封装浏览器麦克风权限与音频流生命周期。
+
+建议 API：
+
+```ts
+export interface MicrophoneInputPort {
+  isSupported(): boolean
+  requestPermission(): Promise<MicrophoneSession>
+  stop(): void
+}
+
+export interface MicrophoneSession {
+  sample(atMs: number): BarkAudioSample
+  stop(): void
+}
+```
+
+实现要点：
+
+1. 使用 `navigator.mediaDevices?.getUserMedia({ audio: true })`。
+2. 在用户点击“开始”后创建或 resume `AudioContext`，避免移动端自动播放策略拦截。
+3. 使用 `AnalyserNode` 读取时域数据，计算 RMS 与 peak。
+4. 输出归一化样本，不把 `MediaStream`、`AudioContext`、`AnalyserNode` 泄漏到 domain。
+5. 退出、重开、页面卸载时停止 track，避免麦克风占用残留。
+
+### 7.2 校准流程
+
+`calibration` 阶段建议持续 `800ms..1500ms`：
+
+1. 收集静默环境样本。
+2. 计算 `ambientNoiseFloor`，例如 `p75` 或均值 + 标准差。
+3. 设置动态阈值：
+
+```text
+barkThreshold = clamp(ambientNoiseFloor + 0.12, 0.18, 0.55)
+```
+
+4. 若环境噪音过高，HUD 给出简短提示和“继续 / 重新校准”入口，但不要把长说明常驻在画面上。
+
+### 7.3 权限与错误分类
+
+```ts
+export type MicrophoneFailureReason =
+  | 'unsupported'
+  | 'permission-denied'
+  | 'non-secure-context'
+  | 'not-found'
+  | 'not-readable'
+  | 'audio-context-blocked'
+  | 'calibration-timeout'
+  | 'calibration-sample-unreadable'
+  | 'unknown'
+```
+
+错误来源与分层归属：
+
+| 失败原因 | 主要检测位置 | controller snapshot 表达 | HUD 可区分状态 |
+| --- | --- | --- | --- |
+| 浏览器无 `mediaDevices.getUserMedia` | `BrowserMicrophoneInput.isSupported()` | `phase: 'unavailable'`, `uiState: 'microphone-unavailable'`, `errorReason: 'unsupported'` | 设备或浏览器不支持麦克风输入，只提供返回入口，不展示可开始声控按钮 |
+| 非安全上下文 | `BrowserMicrophoneInput.isSupported()` 或 `MicrophonePermission` 预检 `window.isSecureContext` | `phase: 'unavailable'`, `errorReason: 'non-secure-context'` | 当前环境无法使用麦克风，提示使用受支持的安全环境或返回 |
+| 用户拒绝授权 | `BrowserMicrophoneInput.requestPermission()` 捕获 `NotAllowedError` / `SecurityError` | `phase: 'unavailable'`, `errorReason: 'permission-denied'` | 提供重新授权或返回入口，不进入 calibration/countdown/playing |
+| 未检测到设备 | `getUserMedia` 捕获 `NotFoundError` / `DevicesNotFoundError` | `phase: 'unavailable'`, `errorReason: 'not-found'` | 展示麦克风不可用，可重试授权或返回 |
+| 设备被占用或不可读 | `getUserMedia` 捕获 `NotReadableError` / `TrackStartError` | `phase: 'unavailable'`, `errorReason: 'not-readable'` | 展示麦克风不可用，可重试授权或返回 |
+| AudioContext 被移动端策略拦截 | 用户手势后创建 / resume `AudioContext` 失败 | `phase: 'unavailable'`, `errorReason: 'audio-context-blocked'` | 提示点击重试，不自动循环请求 |
+| 校准超时 | `BarkBattleController` 在 calibration 阶段等待样本超出 `calibrationMaxWaitMs` | `phase: 'unavailable'`, `errorReason: 'calibration-timeout'` | 展示麦克风输入不可用，提供重试校准入口 |
+| 校准样本不可读 | `AudioAnalyserSampler.sample()` 持续返回空样本、NaN 或无法读取 buffer | `phase: 'unavailable'`, `errorReason: 'calibration-sample-unreadable'` | 展示麦克风输入不可用，提供重试校准入口 |
+
+前端只根据错误分类展示可操作状态：重试授权、重试校准、返回、或使用调试备用输入。不要把浏览器原始错误堆栈展示给玩家。
+
+## 8. Phaser Scene 切分
+
+### 8.1 BarkBattleBootScene
+
+职责：
+
+- 初始化 Phaser 全局配置。
+- 注册 scale、background color、全局事件桥。
+- 不加载重资源，不处理玩法规则。
+
+### 8.2 BarkBattlePreloadScene
+
+职责：
+
+- 根据 `barkBattleAssetManifest` 加载背景、狗狗 sprite、声浪 FX、拟声词 bitmap / atlas、轻量音效。
+- 使用稳定 manifest key，不在 gameplay 代码中散写文件路径。
+- 加载完成后进入 `BarkBattleScene`。
+
+### 8.3 BarkBattleScene
+
+职责：
+
+- 创建横版舞台、左右狗狗、背景层、声浪层、拟声词层。
+- 每帧读取最新 `BarkBattleSnapshot`。
+- 根据 snapshot 更新：
+  - 狗狗 idle / bark / win / lose 动画
+  - 声浪强度
+  - camera shake
+  - transient bark words
+  - shockwave
+- 把可选的调试输入 action 传给 controller，但不处理麦克风和规则。
+
+不得在 Scene 中实现：
+
+- 叫声计数
+- 胜负判定
+- 能量条规则
+- 权限流程
+- 结算数据计算
+
+### 8.4 BarkBattleFxScene（可选）
+
+如果特效复杂，可拆出叠加 Scene：
+
+- 专门处理拟声词、粒子、冲击波和 camera shake。
+- 通过视觉事件 ID 去重。
+- 对 `prefers-reduced-motion` 或低端设备降级。
+
+首版也可以先把 FX 保持在 `BarkBattleScene` 内，但必须仍然只消费 snapshot / visual events。
+
+## 9. DOM HUD 设计
+
+### 9.1 HUD 层级
+
+DOM HUD 建议覆盖在 Phaser Canvas 上方：
+
+```text
+BarkBattleRuntimeShell
+  ├─ <div className="bark-battle-canvas-host" />
+  └─ <BarkBattleHud snapshot={snapshot} uiState={uiState} />
+```
+
+HUD 分区：
+
+- 顶部：红蓝声浪能量条 + 小型剩余时间。
+- 中央：仅在倒计时、关键提示或结算时短暂展示大号状态。
+- 左右边缘：双方简洁状态，例如叫声次数 / combo chip。
+- 底部角落：麦克风状态、重试、小菜单。
+- 结算：独立居中面板，显示胜负、叫声次数、最大音量、评分、再来一局、返回。
+
+### 9.2 Playfield 保护
+
+遵循 game UI 约束：
+
+1. 正常 playing 阶段保持中心和下中部 playfield 清爽，不常驻长文案。
+2. 不把规则说明、长控制说明、多段提示默认铺在画面上。
+3. 权限、设置、结算使用独立面板或弹层，不在当前面板下面展开一大块内容。
+4. 移动端优先保证顶部能量条、倒计时、狗狗和重试入口可见可点。
+5. 大动效不能遮挡顶部能量条和倒计时。
+
+### 9.3 CSS 设计建议
+
+- 使用局部 CSS class 或 CSS module，避免污染全站。
+- 使用 CSS 变量定义主题：
+  - `--bark-player-color`
+  - `--bark-opponent-color`
+  - `--bark-panel-bg`
+  - `--bark-safe-bottom`
+- 使用 `dvh` / `svh` 和 safe-area inset 处理移动端地址栏与刘海。
+- `pointer-events` 分层：HUD 容器默认 `pointer-events: none`，按钮和面板恢复 `pointer-events: auto`。
+
+## 10. 移动端与权限降级
+
+### 10.1 移动端输入约束
+
+移动端浏览器通常要求用户手势才能启动 AudioContext。开局流程必须是：
+
+```text
+玩家点击“开始” → requestPermission → 创建/恢复 AudioContext → calibration → countdown → playing
+```
+
+不要在页面加载时自动请求或自动启动 AudioContext。
+
+### 10.2 响应式布局
+
+移动端建议：
+
+- 横屏优先呈现完整舞台；竖屏可保持舞台居中并缩小 HUD。
+- 顶部能量条高度保持可读，但不要占满大面积。
+- 结算面板宽度使用 `min(92vw, 420px)`。
+- 底部按钮避开 `env(safe-area-inset-bottom)`。
+- 非关键设置折叠进小菜单。
+
+### 10.3 权限失败降级
+
+权限失败时：
+
+- `unsupported`：展示“当前浏览器不支持麦克风输入”，提供返回入口，不展示开始声控按钮。
+- `non-secure-context`：展示“当前环境无法使用麦克风”，提示切换到受支持的安全环境或返回。
+- `permission-denied`：展示简短说明和“重新授权”入口。
+- `not-found`：提示未检测到麦克风，提供重试授权或返回入口。
+- `not-readable`：提示麦克风被占用或暂时不可读，提供重试授权或返回入口。
+- `audio-context-blocked`：提示点击重试。
+- `calibration-timeout` / `calibration-sample-unreadable`：提示麦克风输入不可用，提供“重新校准”和返回入口。
+
+可选开发调试降级：
+
+- 本地 dev 可启用键盘 mock input，例如按住空格模拟音量峰值。
+- mock input 必须标记为开发/调试能力，不作为正式竞技能力。
+
+## 11. 测试策略
+
+### 11.1 Domain 单元测试（优先）
+
+目标：不接 Phaser、不接 DOM、不接 Web Audio。
+
+建议测试：
+
+- `BarkDetector`：超过阈值且间隔足够时计为一次有效叫声。
+- `BarkDetector`：持续噪音不会无限计数。
+- `BarkDetector`：低于环境噪音阈值不计入叫声。
+- `EnergyTugOfWar`：玩家 power 高于对手时 energy 向玩家侧移动。
+- `EnergyTugOfWar`：energy clamp 在 `-100..100`。
+- `BarkBattleSession`：倒计时结束进入 playing。
+- `BarkBattleSession`：剩余时间归零进入 finished。
+- `BarkBattleSession`：按 energy 和 drawThreshold 判定胜 / 负 / 平。
+
+### 11.2 Application 测试
+
+目标：验证输入样本、AI、tick 和 snapshot 编排。
+
+建议测试：
+
+- 权限允许后进入校准，再进入倒计时。
+- 权限拒绝后 `phase` 为 `unavailable`、`errorReason` 为 `permission-denied`，不进入 playing。
+- 非安全上下文、设备未找到、设备不可读、AudioContext 被拦截时，controller snapshot 都进入 `phase: 'unavailable'`，并保留可供 HUD 区分的 `errorReason`。
+- 校准超时或样本持续不可读时，controller snapshot 使用 `errorReason: 'calibration-timeout'` 或 `calibration-sample-unreadable`，并提供重试校准动作。
+- 提交 mock audio sample 后 snapshot 中玩家状态更新。
+- AI 对手 power 参与能量条拉锯。
+- `lastEvents` 只发布新增视觉事件。
+
+### 11.3 HUD 组件测试
+
+目标：验证 snapshot 到 DOM 的展示映射。
+
+建议测试：
+
+- playing 阶段展示倒计时和能量条。
+- energy 正负值映射到玩家 / 对手侧比例。
+- `errorReason: 'permission-denied'` 展示重试授权入口。
+- `errorReason: 'unsupported'` 展示返回入口且不展示开始声控按钮。
+- `not-found`、`not-readable`、`non-secure-context`、`audio-context-blocked`、`calibration-timeout`、`calibration-sample-unreadable` 分别映射到可区分的简短状态文案和对应操作。
+- finished 展示胜负、叫声次数和再来一局。
+- 移动端 class / 结构不依赖 Phaser Canvas 才能渲染。
+
+### 11.4 Phaser 集成与 smoke
+
+自动化层面不强行在 Vitest 中完整启动 Phaser。建议：
+
+- 用 adapter mock 测试 Scene 消费 snapshot 的纯映射函数。
+- 浏览器 smoke 验证真实 Canvas、Web Audio 和动画。
+- 若后续引入 Playwright，再做最小视觉和交互 smoke。
+
+## 12. 验证命令建议
+
+文档阶段只需要编码检查和 diff 检查：
+
+```bash
+npm run check:encoding
+git diff -- docs/prd/BARK_BATTLE_BDD_2026-05-11.md docs/technical/BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md
+```
+
+后续实现 domain 后建议：
+
+```bash
+npm run test -- --run src/games/bark-battle/domain/**/*.test.ts
+npm run typecheck
+npm run check:encoding
+```
+
+后续实现 infrastructure/application 错误状态后建议：
+
+```bash
+npm run test -- --run src/games/bark-battle/infrastructure/__tests__/BrowserMicrophoneInput.test.ts src/games/bark-battle/application/__tests__/BarkBattleController.test.ts
+npm run typecheck
+npm run check:encoding
+```
+
+后续实现 HUD 后建议：
+
+```bash
+npm run test -- --run src/games/bark-battle/ui/**/*.test.tsx
+npm run lint:eslint
+npm run typecheck
+npm run check:encoding
+```
+
+后续接入浏览器 runtime 后建议：
+
+```bash
+npm run dev:web
+# 人工 smoke：授权麦克风 → 校准 → 发声 → 能量条变化 → 结算 → 再来一局
+```
+
+若未来接入 Genarrative 正式玩法类型、后端持久化或发布链路，再追加对应契约、api-server 和 SpacetimeDB 验证；首版 runtime 原型不应提前新增这些命令作为门槛。
+
+## 13. 后续落地顺序
+
+建议后续实现按以下顺序推进：
+
+1. 先建 `domain/` 和纯单元测试。
+2. 实现 `BarkDetector`、`EnergyTugOfWar`、`BarkBattleSession` 的最小规则。
+3. 建 `application/` controller，用 mock audio sample 跑通 snapshot。
+4. 实现 DOM HUD 的 permission / energy / timer / result 展示。
+5. 接入 `BrowserMicrophoneInput` 和校准流程。
+6. 接入 Phaser host、Scene 和 asset manifest，占位素材先跑通视觉反馈。
+7. 做移动端视口和权限失败 smoke。
+8. 产品确认后再决定是否进入正式玩法类型、作品发布和后端真相链。
+
+## 14. 关键技术决策
+
+1. 默认采用 Phaser 3 + TypeScript + Vite，符合 2D 浏览器游戏默认路线。
+2. 核心 simulation 放在纯 TypeScript domain，严格不依赖 Phaser / Web Audio / DOM。
+3. Web Audio 只作为输入 adapter，输出归一化 `BarkAudioSample`。
+4. Phaser Scene 是 renderer，只消费 snapshot 和 visual events，不承载规则真相。
+5. HUD 使用 DOM overlay，承载权限、能量条、倒计时、结算和移动端响应式布局。
+6. MVP 不做复杂狗叫语义识别，先用音量峰值、持续时长、冷却和环境噪音校准。
+7. MVP 建议玩家 vs AI 单机 runtime，正式成绩、排行榜、发布和奖励后续再交给后端链路。

docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md

@@ -47,7 +47,7 @@
 
 用户完成热身关所有步骤后，进入关卡选择。
 
-当前后续游戏仍在设计中。热身结束后可先展示“开始游戏”按钮作为关卡选择占位，用户点击后进入下一关占位界面。
+热身结束后展示“开始游戏”按钮，用户点击后进入宝贝识物首关本地 Demo。该入口只用于热身关后的本地体验验证；正式平台体验仍必须通过“宝贝识物”创作模板发布后，在寓教于乐板块进入。
 
 ### 3.3 固定流程顺序
 
@@ -642,7 +642,7 @@
 
 1. `src/ChildMotionDemoApp.tsx` 挂载独立 Demo 应用壳。
 2. `src/components/child-motion-demo/childMotionWarmupModel.ts` 维护热身步骤、圆环目标、2 秒保持判定、热身校准记录和当前运行时会话完成标记。
-3. `src/components/child-motion-demo/ChildMotionWarmupDemo.tsx` 实现横屏舞台、背景虚化占位层、角色剪影、绿色圆环、手势引导、热身记录面板、热身完成后的“开始游戏”按钮和下一关占位界面。
+3. `src/components/child-motion-demo/ChildMotionWarmupDemo.tsx` 实现横屏舞台、背景虚化占位层、角色剪影、绿色圆环、手势引导、热身记录面板、热身完成后的“开始游戏”按钮，并复用宝贝识物运行态进入首关本地 Demo。
 4. `src/services/child-motion-demo/childMotionDebugInput.ts` 保留开发者调试输入适配层，后续可被正式动作识别 SDK 适配层替换或并行接入。
 5. `src/routing/appRoutes.tsx` 新增 `/child-motion-demo` 独立路由，并复用 `VITE_ENABLE_EDUTAINMENT_ENTRY` 开关；开关关闭时不允许通过该直达路径进入 Demo。
 
@@ -669,19 +669,27 @@
 当前未接入但已保留边界：
 
 1. 正式语音播报接口暂不接入，当前先展示热身文案。
-2. 正式 gpt-image-2 视觉资源暂不接入，当前使用 CSS 占位表达相同位置和状态。
+2. 后续关卡安全边界暂停逻辑暂未落地，当前只完成热身记录和宝贝识物首关本地 Demo 衔接。
-3. 后续关卡安全边界暂停逻辑暂未落地，当前只完成热身记录和下一关按钮占位。
 
 ## 16. 当前视觉资产与生图口径补充
 
 儿童动作 Demo 的视觉口径已经统一收敛到绘本风格草地舞台：
 
 1. 舞台主环境采用卡通绘本风格、明亮草地、天空、小山坡和树木的组合，默认背景环境需要保证中心与下方前景留空，便于角色轮廓和地面指示环叠加。
-2. `src/index.css` 中的热身舞台、摄像头背景层、地面、角色轮廓、地面圆环、开始按钮和横屏提示均按绘本草地风格重做，未生成真实背景图时由 CSS 兜底。
+2. 该卡通绘本草地风格是儿童动作 Demo 后续场景、物品、UI 资源的全局风格要求；新增资源不得切回暗色科技风、真实照片风或后台面板风。
-3. 真实背景图的默认输出路径固定为 `public/child-motion-demo/picture-book-grass-stage.webp`。
+3. `src/index.css` 中的热身舞台、摄像头背景层、地面、角色轮廓、地面圆环、开始按钮和横屏提示均按绘本草地风格接入真实资源；资源加载失败时保留 CSS 兜底。
-4. 生成脚本固定为 `scripts/generate-child-motion-demo-assets.mjs`，并通过 `npm run assets:child-motion-demo` 触发；脚本使用 `gpt-image-2-all` 调用 VectorEngine `POST /v1/images/generations`。
+4. 生成脚本固定为 `scripts/generate-child-motion-demo-assets.mjs`，并通过 `npm run assets:child-motion-demo` 触发；脚本使用 `gpt-image-2-all` 调用 VectorEngine `POST /v1/images/generations`，透明资源先生成品红底源图，再在本地移除色键，源图写入 `tmp/child-motion-demo-assets/`。
-5. 当前本机工作区未检测到 `VECTOR_ENGINE_BASE_URL` 与 `VECTOR_ENGINE_API_KEY`，因此暂时只能完成 dry-run 或代码层接入，不能直接产出真实 image-2 资产。
+5. 当前已生成并接入以下正式 Demo 资源：
-6. 若后续补齐 VectorEngine 私密配置，再运行 live 生成即可把真实绘本背景写入上述固定路径，页面会自动读取。
+   - `public/child-motion-demo/picture-book-grass-stage.png`：默认草地舞台背景。
+   - `public/child-motion-demo/picture-book-foreground-grass-v2.png`：底部前景草坪条，只覆盖舞台下沿，不作为整块地板拉伸。
+   - `public/child-motion-demo/picture-book-ground-ring-v2.png`：已按透视绘制的地面椭圆指示环，CSS 只等比缩放。
+   - `public/child-motion-demo/picture-book-character-outline-v2.png`：半透明用户角色轮廓，使用独立去背后处理避免内部填充被误删。
+   - `public/child-motion-demo/picture-book-hud-strip-v2.png`：顶部 HUD 细长软纸条。
+   - `public/child-motion-demo/picture-book-calibration-strip-v2.png`：右下角五格热身状态条。
+   - `public/child-motion-demo/picture-book-start-panel-v2.png`：开始按钮背后的轻盈托盘。
+   - `public/child-motion-demo/picture-book-ui-button-v2.png`：开始按钮绘本风按钮底图。
+6. v2 资源按最终用途拆分，CSS 必须按资源原始比例、`aspect-ratio` 或 `background-size: contain / auto` 等方式等比使用；禁止把方形面板强行拉伸为 HUD、状态条或地板，也禁止把底部草坪扩展成覆盖角色脚下的大色块。
+7. 若后续补充或重绘资源，应先运行 `npm run assets:child-motion-demo -- --dry-run` 核对 prompt 和输出路径，再使用 `--live --only <asset-id>` 小批量生成；仅调整透明去背、裁切、画布归一或品红边缘时，可用 `npm run assets:child-motion-demo -- --live --postprocess-only --force --only <asset-id>` 复用 `tmp/child-motion-demo-assets/` 中的源图，不额外请求 image-2；不得把 `VECTOR_ENGINE_API_KEY`、源图或中间预览图提交到仓库。
 
 已执行的定向验证命令：
 

docs/technical/CREATION_ENTRY_CONFIG_AND_RUNTIME_NOT_FOUND_RECOVERY_2026-05-10.md

@@ -36,7 +36,7 @@ SpacetimeDB 新增两张表：
 其中：
 
 - `visible=false`：前端隐藏入口。
-- `open=false`：前端展示为锁定/暂不可创建，api-server 也可据此熔断运行时入口。
+- `open=false`：前端展示为锁定/暂不可创建，api-server 据此熔断对应玩法 API；只隐藏创作页入口但保留既有作品链路时不要关闭 `open`。
 - `sort_order`：数据库排序字段，前端只做可见/锁定分组派生。
 
 ## API

docs/technical/HYPER3D_RODIN_GEN2_MODEL_GENERATION_2026-05-08.md

@@ -13,6 +13,8 @@
 - `https://developer.hyper3d.ai/api-specification/rodin-generation-gen2`
 - `https://developer.hyper3d.ai/api-specification/check-status`
 - `https://developer.hyper3d.ai/api-specification/download-results`
+- `https://developer.hyper3d.ai/api-specification/check-status_reset_v`
+- `https://developer.hyper3d.ai/api-specification/download-results_reset_v`
 
 上游接口：
 
@@ -24,6 +26,11 @@ POST https://api.hyper3d.com/api/v2/download
 
 Rodin Gen-2 提交接口必须使用 `multipart/form-data`。文本生成时提交 `prompt`；图片生成时提交一个或多个 `images` 文件，可选 `prompt` 作为辅助描述。两种模式均固定提交 `tier=Gen-2`。
 
+官方 `*_reset_v` 文档对状态和下载有两个关键约束：
+
+1. 生成接口返回的顶层 `uuid` 是后续下载接口的 `task_uuid`，不要使用 `jobs.uuids` 中的子任务 uuid 作为下载参数。
+2. 状态接口使用 `subscription_key` 查询，并返回 `jobs[]`；只有所有 job 的 `status` 都为 `Done` 才能进入下载，任一 job `Failed` 都应视为任务失败。
+
 ## 3. 环境变量
 
 ```text
@@ -111,7 +118,7 @@ RODIN_MODEL_REQUEST_TIMEOUT_MS
 }
 ```
 
-状态查询会把上游 `Waiting / Generating / Done / Failed` 归一化为 `waiting / generating / done / failed / unknown`。下载接口只返回上游 `list.name` 与 `list.url`，不在后端转存文件。
+状态查询会把上游 `Waiting / Generating / Done / Failed` 归一化为 `waiting / generating / done / failed / unknown`，整体状态必须以 `jobs[]` 聚合结果为准。下载接口只返回上游 `list.name` 与 `list.url`，不在 Hyper3D 代理路由中转存文件；具体玩法若需要持久化模型，应在玩法编排层等待 `Done` 后再下载并转存。
 
 ## 7. 验收
 

docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md

@@ -2,47 +2,54 @@
 
 ## 1. 范围
 
-本方案用于改造 `生成抓大鹅草稿` 的首版生成链路：点击按钮后先进入独立生成过程页，生成结束后自动进入抓大鹅草稿页，并在草稿页 `3D素材` Tab 预览本次生成的 3D 模型。
+本方案用于改造 `生成抓大鹅草稿` 的首版生成链路：点击按钮后先进入独立生成过程页，生成结束后自动进入抓大鹅结果页，并在结果页 `素材配置 > 物品` 预览本次生成的 2D 多视角物品素材。
 
-本次只把任意难度都收敛为 `3` 件物品。后续难度曲线恢复时，再把物品数、网格数和手动 3D 任务数量从配置中放开。
+草稿生成不再调用 Hyper3D Rodin，也不再生成 GLB 模型。物品素材继续沿用原来的“生成图片 -> 网格拆分 -> 上传 OSS -> 写回草稿”机制，但每个物品必须生成 `5` 个不同视角的 2D 视图。试玩和正式运行态的消除次数、总物品数和物品种类数以结果页 `难度配置` 保存的难度为准。难度对应物品种类固定为：轻松 `3` 种、标准 `9` 种、进阶 `15` 种、硬核 `21` 种。历史硬核草稿若仍保存 `clearCount = 20`，运行态按新硬核升为 `21` 次消除、`63` 件总物品。正式发布前如果已生成 `image_ready` 且具备至少 `5` 张有效 `imageViews[]` 的物品种类不足当前难度要求，必须阻断发布；试玩不阻断，但启动时把物品种类自动降到当前可用 2D 素材数量。
 
 ## 2. 前端流程
 
 入口仍复用 `Match3DAgentWorkspace` 表单。点击 `生成抓大鹅草稿` 后：
 
 1. 创建 Match3D session。
-2. 进入 `match3d-generating` 生成过程页。
+2. 后端先用当前题材和本地兜底元信息创建同一个 Match3D 草稿 profile，草稿 Tab 必须立即能看到这份存档。
-3. 过程页复用拼图生成页的 `CustomWorldGenerationView` 结构。
+3. 进入 `match3d-generating` 生成过程页。
-4. 生成成功后自动进入 `match3d-result`。
+4. 过程页复用拼图生成页的 `CustomWorldGenerationView` 结构。
-5. 生成失败时停留在生成过程页，允许重新生成或返回创作中心。
+5. 生成成功后自动进入 `match3d-result`。
+6. 生成失败时停留在生成过程页，允许重新生成或返回创作中心；重新生成必须复用同一个 session / profile，并从缺失的素材阶段继续，不新建第二份草稿。
 
 生成页步骤固定为：
 
 ```text
-生成游戏名称 -> 生成物品名称 -> 生成素材图 -> 切割独立图片 -> 上传图片资产 -> 写入草稿页
+生成游戏名称 -> 生成物品名称与背景音乐名称 -> 生成背景提示词 -> 分批生成1K素材图 -> 切割五视角图片 -> 上传图片资产 -> 生成背景音乐 -> 生成背景图 -> 写入草稿页
 ```
 
 生成页只展示题材和物品数量，不展示玩法规则说明。
 
+当前 `match3d-generating` 进度页不是后端 task 状态订阅页，而是一个覆盖 `match3d_compile_draft` 长 action 的本地时间进度页：前端每 500ms 以本地时间刷新阶段展示，真正的生成完成仍以 action 返回为准。为避免长 action 未返回时页面完全无感，生成页在 `match3d_compile_draft` 执行期间每 3 秒旁路读取一次 session 和 work detail，并用 profile 中已写回的 `generatedItemAssets` 更新图片素材完成数量。若 `generatedItemAssets` 已出现 `image_ready` 且带 `imageViews`，前端应逐步显示完成数量。
+
 ## 3. 后端编排边界
 
-外部模型和 OSS 上传全部由 `api-server` 编排，不进入 SpacetimeDB reducer。SpacetimeDB 继续只负责 Match3D 会话、草稿和作品 profile 的确定性写入。
+外部生图、音频生成和 OSS 上传全部由 `api-server` 编排，不进入 SpacetimeDB reducer。SpacetimeDB 继续只负责 Match3D 会话、草稿和作品 profile 的确定性写入。
 
 `match3d_compile_draft` action 的后端顺序为：
 
 1. 读取 session config。
-2. 将本次 MVP 的 `clearCount` 固定为 `3`，并同步用于草稿编译。
+2. 草稿编译先创建可恢复 profile；素材生成数量由入口页难度派生的物品种类决定：轻松 `3` 种、标准 `9` 种、进阶 `15` 种、硬核 `21` 种。
-3. 基于入口页题材设定文本调用文本模型生成作品元信息。模型固定请求 `gpt-4o`，只返回 JSON，其中 `gameName` 为 4 到 12 个中文字符的游戏名称，`tags` 为 3 到 6 个中文短标签；`summary` 首版必须保持空字符串，结果页 `作品描述` 默认留给用户填写。
+3. 先调用 SpacetimeDB compile procedure 写入草稿。首次执行使用新 `profileId`；重试时复用 session draft / work profile 中已有 `profileId`。这一步不能等待 LLM、图片、音频或 OSS 成功后才执行。
-4. 调用文本模型生成 `3` 个题材下的短物品名称。
+4. 基于入口页题材设定文本调用文本模型生成作品生成计划。模型固定请求 `gpt-4o`，只返回 JSON，其中 `gameName` 为 4 到 12 个中文字符的游戏名称，`tags` 为 3 到 6 个中文短标签；`summary` 首版必须保持空字符串，结果页 `作品描述` 默认留给用户填写。生成计划还必须包含 `backgroundMusic.title`、`backgroundMusic.style`、`backgroundMusic.prompt`、`backgroundPrompt`，以及 `items[]` 中每个物品的 `name` 与 `soundPrompt`。`backgroundMusic.title` 是背景音乐名称，`backgroundMusic.prompt` 固定为空字符串，用于后续 Suno 纯音乐生成；`backgroundPrompt` 用于生成局内竖屏背景图，必须描述绿色纵向背景与居中浅锅/圆盘状竞技区融合为一张完整背景图，且不包含 UI、文字、按钮、倒计时或物品。文本模型不可用时保留第 3 步的本地兜底，不阻断草稿。
-5. 调用项目当前图片链路 VectorEngine `gpt-image-2-all` 生成一张 `1:1` 素材图，提示词必须合入入口页选择的 `assetStylePrompt`。历史 `nanobanana2` 图片选项当前按项目统一决策回落到 VectorEngine，不重新接入 APIMart 图片网关。
+5. 后端从同一份作品生成计划读取当前难度所需数量的短物品名称和音效提示词；不得再只生成物品名称而丢失后续音效生成上下文。
-6. 将素材图按 `n*n` 网格切割成独立图片。当前 `3` 件物品使用 `2*2` 网格，取前 `3` 格。
+6. 调用项目当前图片链路 VectorEngine `gpt-image-2-all` 生成 `1:1`、`1024x1024` 素材图，提示词必须合入入口页选择的 `assetStylePrompt`。历史 `nanobanana2` 图片选项当前按项目统一决策回落到 VectorEngine，不重新接入 APIMart 图片网关。
-7. 将素材图和每张独立图片上传到 OSS，其中独立图片作为草稿页素材预览和后续 Rodin 图生模型参考图。
+7. 每个物品固定需要 `5` 个不同视角。单张素材图最多切成 `5*5 = 25` 格；因此单张图最多承载 `5` 个物品。若草稿物品数超过 `5`，后端按每批最多 `5` 个物品自动分批，多张素材图并行生成。
-8. 调用现有 SpacetimeDB compile procedure 写入草稿，并把本次生成的独立物品图片列表序列化写入 `match3d_work_profile.generated_item_assets_json`。这一步对标拼图的 `save_puzzle_generated_images`：生成资产不能只挂在本次 HTTP response 上，否则退出结果页后从草稿架读取 `getMatch3DWorkDetail` 会丢失素材列表。
+8. 将每张素材图按 `n*n` 网格切割成独立图片，并按物品顺序连续分配 `5` 张视角图。每个物品 JSON 写入 `imageViews[]`，同时把第一个视角兼容写入 `imageSrc/imageObjectKey`。
-9. 在 HTTP 返回的 draft/profile DTO 中附带本次生成的素材资产预览信息，独立图片状态为 `image_ready`，模型字段保持为空；后续重进草稿页时从 work profile 的持久化 `generatedItemAssets` 恢复同一批素材。
+9. 将素材图和每张独立视角图片上传到 OSS。每次获得可恢复的图片资产后，都要回写 `match3d_work_profile.generated_item_assets_json`。成功素材状态为 `image_ready`；失败素材保留已成功图片引用并记录 `error`。每个素材 JSON 同步保存 `soundPrompt`，首个素材 JSON 同步保存 `backgroundMusicTitle` 与 `backgroundMusicStyle`，`backgroundMusicPrompt` 保存为空字符串作为兼容字段。
+10. 后端在图片素材生成后使用 `backgroundMusic.title` 提交 Suno 背景音乐任务，`prompt` 为空，`tags` 来自 `backgroundMusic.style`，并固定走纯音乐生成。轮询完成后通过通用创作音频资产链路转存 OSS、确认 `asset_object`、绑定到 `match3d_work/background_music`，再写回首个素材的 `backgroundMusic`。音乐生成失败只记录 warning，不阻断草稿页进入，用户可在结果页 `素材配置 > 背景音乐` 重试。
+11. 若入口页 `generateClickSound=true`，后端在图片素材生成后继续为缺少 `clickSound` 的已生成物品并行提交 Vidu 点击音效任务，轮询完成后通过通用创作音频资产链路转存 OSS、确认 `asset_object`、绑定实体并写回对应素材的 `clickSound`；若开关关闭则只保存 `soundPrompt`，不调用音频生成。
+12. 背景图生成同样由 `api-server` 调用 VectorEngine `gpt-image-2-all`，尺寸固定为 `9:16`，并固定传入 `public/match3d-background-references/pot-fused-reference.png` 作为参考图。参考图只表达抓大鹅绿色页面背景和锅状圆形竞技区的融合构图，不包含 HUD、物品、文字或按钮。生成后的背景图上传到 `generated-match3d-assets/{sessionId}/{profileId}/background/{taskId}/background.png`，并作为 `backgroundAsset` 挂在首个 `generatedItemAssets[]` JSON 上；HTTP DTO 同时顶层输出 `backgroundPrompt`、`backgroundImageSrc`、`backgroundImageObjectKey` 与 `generatedBackgroundAsset`。
+13. 在 HTTP 返回的 draft/profile DTO 中附带本次生成的素材资产预览信息、背景音乐资产信息和背景资产信息；后续重进草稿页时从 work profile 的持久化 `generatedItemAssets` 恢复同一批素材、音乐与背景。
 
 若文本模型不可用或返回无法解析，后端必须降级为 `{themeText}抓大鹅` 与本地标签兜底，不阻断素材生成；但描述仍保持空字符串。
 
-草稿生成阶段不调用 Hyper3D Rodin，不等待 `subscriptionKey`，也不下载模型文件；Rodin 生成只在结果页 `3D素材` Tab 由用户手动触发。手动生成得到的上游下载 URL 仍不得直接写入 Match3D profile，后续正式资产绑定以独立技术方案为准。
+草稿生成阶段不再调用 Hyper3D Rodin，不生成 GLB，也不等待任何模型轮询。前端 `match3d_compile_draft` action 的长耗时主要来自文本生成、分批 1K 生图、切图、OSS 上传、背景图和可选音频生成。批量新增物品由 `POST /api/creation/match3d/works/{profileId}/item-assets` 复用同一套 2D 素材图生成、5x5 切图、OSS 上传和可选点击音效链路，只补齐本次新增物品并把 `imageViews[]` 写回 `generatedItemAssets`。
 
 ## 4. 图片提示词
 
@@ -50,27 +57,35 @@
 
 ```text
 生成一张1:1图片
-生成2*2网格素材图
+生成不超过5*5网格素材图
 整体画风遵循：...
 只绘制这些物品：...
 不要出现文字、水印、UI、边框
 ```
 
-`包含若干个物品名称` 在落地中解释为“按生成出的物品名称绘制对应主体”，不要求图片上写出物品名称。这样可以避免文字渲染污染切图和后续手动 3D 模型参考。
+`包含若干个物品名称` 在落地中解释为“按生成出的物品名称绘制对应主体”，不要求图片上写出物品名称。这样可以避免文字渲染污染切图和局内 2D 素材表现。
 
-入口页内置风格参考图通过同一 VectorEngine `gpt-image-2-all` 能力生成，保存路径固定为：
+入口页内置 2D 风格参考图通过同一 VectorEngine `gpt-image-2-all` 能力生成，执行命令为 `npm run assets:match3d-style-references -- --live`，保存路径固定为：
 
 ```text
-public/match3d-style-references/clay-toy.png
+public/match3d-style-references/flat-icon.png
-public/match3d-style-references/low-poly.png
+public/match3d-style-references/cel-cartoon.png
-public/match3d-style-references/toy-plastic.png
+public/match3d-style-references/pixel-retro.png
-public/match3d-style-references/wood-carved.png
+public/match3d-style-references/watercolor.png
-public/match3d-style-references/voxel-block.png
+public/match3d-style-references/sticker-outline.png
-public/match3d-style-references/metal-mecha.png
+public/match3d-style-references/painterly-icon.png
 ```
 
 这些图片只作为入口页风格选择的视觉参考，不进入用户草稿资产，不替代生成时的物品素材图。
 
+局内背景生成固定参考图路径为：
+
+```text
+public/match3d-background-references/pot-fused-reference.png
+```
+
+这张图作为 VectorEngine `image` 参考输入使用，用来锁定“绿色竖屏背景 + 居中锅状竞技区”的构图。每次草稿生成仍会根据 `backgroundPrompt` 生成新的题材化背景图；参考图本身不作为运行态最终背景。
+
 ## 5. OSS 路径
 
 新增 generated legacy prefix：
@@ -83,16 +98,56 @@ generated-match3d-assets
 
 ```text
 generated-match3d-assets/{sessionId}/{profileId}/material-sheet/{taskId}/sheet.png
-generated-match3d-assets/{sessionId}/{profileId}/items/{itemSlug}/image.png
+generated-match3d-assets/{sessionId}/{profileId}/items/{itemSlug}/views/view-01.png
+generated-match3d-assets/{sessionId}/{profileId}/items/{itemSlug}/views/view-02.png
+generated-match3d-assets/{sessionId}/{profileId}/items/{itemSlug}/views/view-03.png
+generated-match3d-assets/{sessionId}/{profileId}/items/{itemSlug}/views/view-04.png
+generated-match3d-assets/{sessionId}/{profileId}/items/{itemSlug}/views/view-05.png
+generated-match3d-assets/{sessionId}/{profileId}/background/{taskId}/background.png
 ```
 
 `itemSlug` 必须带 `itemId` 前缀，例如 `match3d-item-1-item`。中文物品名清洗后可能都退回 `item`，不能只用物品名做路径，否则多张切割图会写到同一个 object key，导致草稿页预览图全部一致。
 
-HTTP DTO 同时返回 `imageSrc`、`imageObjectKey`、空的 `modelSrc`、空的 `modelObjectKey` 和 `status = image_ready`。前端预览图片继续走 `ResolvedAssetImage` 换签；后续手动生成的模型文件也必须通过 `useResolvedAssetReadUrl` / `/api/assets/read-url` 换签后打开，不直接请求裸 `/generated-match3d-assets/...` 路径。
+HTTP DTO 同时返回兼容字段 `imageSrc`、`imageObjectKey`，以及正式 2D 字段 `imageViews[]`、`backgroundAsset` 和 `status`。图片素材生成成功后 `status = image_ready`；背景生成成功后首个素材的 `backgroundAsset.status = image_ready`。前端通过 `/api/assets/read-url` 将 generated legacy path 换签后加载私有图片，不直接请求裸 `/generated-match3d-assets/...` 路径。运行态背景图同样通过 `/api/assets/read-url` 换签后作为全屏 `object-cover` 背景加载。
+
+## 5.1 运行态 2D 素材消费
+
+生成的 2D 五视角素材不仅用于结果页预览，也必须进入游戏运行态。运行态入口的传递链路为：
+
+```text
+Match3DWorkProfile / PlatformMatch3DGalleryCard
+-> Match3DRuntimeShell(generatedItemAssets, backgroundImageSrc)
+-> Match3DPhysicsBoard / Match3DTrayPreviewBoard
+```
+
+运行态按运行快照中的 `itemTypeId` 稳定排序后，把 `generatedItemAssets` 顺序映射到对应类型。加载某个物品实例时，从该类型素材的 `imageViews[]` 中按实例 id 稳定随机选择一个视角；若历史数据没有 `imageViews[]`，则回退到 `imageSrc/imageObjectKey`。没有生成图片或图片加载失败时，继续使用默认积木图标兜底。
+
+运行态背景优先读取 `backgroundImageSrc` / `generatedBackgroundAsset.imageSrc`，为空时从 `generatedItemAssets[].backgroundAsset.imageSrc/imageObjectKey` 兜底。`Match3DRuntimeShell` 只保留顶部返回、倒计时、重开三个控件；进度、组数、版本等状态信息不得再作为顶部常驻 UI 出现，避免遮挡生成背景和锅状竞技区。
+
+前端加载规则：
+
+1. 优先读取 `imageViews[]` 中的 `imageSrc/imageObjectKey`，为空时使用兼容字段 `imageSrc/imageObjectKey`。
+2. 对 generated legacy path 通过同源 `/api/assets/read-url` 换签后交给浏览器图片加载。
+3. 场内物品、点击命中和备选栏继续使用后端快照中的 `itemInstanceId/itemTypeId/x/y/radius/layer`；生成 2D 图片只替换视觉表现，不承接规则真相。
+4. 同一物品类型的多个实例可以展示不同视角，但同一实例在本局中应稳定使用同一个视角，避免移动或入槽时闪图。
+5. 图片缺失、读取失败或解码失败时，继续使用默认积木素材，不能阻断开局、点击、入槽或结算。
+
+结果页点击 `试玩` 时，前端必须把当前结果页可见的 `generatedItemAssets` 带入运行态启动入参。`PUT /api/runtime/match3d/works/{profileId}` 若因为并发或旧快照返回了缺少素材的 profile，`Match3DResultView` 需要把当前 draft / profile 的素材重新合并到运行态 profile，并在启动试玩前调用生成素材保存接口把当前可见的 `generatedItemAssets` 写回作品 profile；不能只在内存里把素材补到 `onStartTestRun(profile)`。发布同理必须先落库当前素材，再调用 `publish_match3d_work`，否则公开推荐流和正式运行态只能读到旧 profile 快照。若历史草稿同时存在旧 `draft.generatedItemAssets` 和较新的 `profile.generatedItemAssets`，同 `itemId` 下以 profile 中已有的 `imageViews[]`、`imageSrc` 或 `imageObjectKey` 补齐 draft，不能让旧 draft 把素材覆盖成空列表。`PlatformEntryFlowShellImpl` 在渲染 `match3d-runtime` 时按 `run.profileId` 优先使用当前 `match3dProfile.generatedItemAssets`，只有 profileId 不匹配时才读取 `selectedPublicWorkDetail.generatedItemAssets`。推荐流内嵌正式运行态也必须走同一解析器；当推荐卡片摘要缺少素材时，启动前补读 `getMatch3DWorkDetail(profileId)`，把详情里的生成图片素材写入 `match3dProfile` 后再传给运行态。这样可以避免从公开详情页残留状态或推荐卡片旧摘要进入试玩 / 正式游戏时，把已生成草稿的 2D 素材覆盖成空列表。
+
+历史草稿若仍保存 `status = model_ready`、`modelSrc` 或 `modelObjectKey`，仅作为旧版本兼容读取，不再参与新素材生产。历史外部模型链接转存接口只用于清理旧数据，不能被新草稿生成、批量新增或结果页普通编辑入口调用。
+
+生成完成后自动进入试玩依赖 `selectionStageRef.current === 'match3d-generating'` 的同步判断。执行 `match3d_compile_draft` 前切到生成页时，必须同时写 `selectionStageRef.current = 'match3d-generating'` 和 `setSelectionStage('match3d-generating')`；只调用 React state 会让 action 很快返回时读到旧 stage，表现为生成页已经 100% 但不进入试玩或结果页。拼图、大鱼吃小鱼、方洞挑战等同类生成页也遵循同一规则。
 
 ## 6. 自动保存与草稿恢复
 
-抓大鹅结果页的基础信息自动保存继续调用 `PUT /api/runtime/match3d/works/{profileId}` 更新名称、题材、描述、标签、封面、消除数和难度；该保存不得清空 `generated_item_assets_json`。SpacetimeDB `update_match3d_work` / `publish_match3d_work` 必须保留当前行的生成素材 JSON。
+点击 `生成抓大鹅草稿` 后，草稿存档创建与素材生成解耦：
+
+1. 首次 compile 必须先写 `match3d_work_profile` 草稿行，即使后续卡在文本模型、图片生成、音频生成或 OSS 上传任意阶段。
+2. 失败态前端要重新读取 session / work detail，并刷新草稿作品架，保证用户离开生成页后仍能在草稿 Tab 找到这份作品。
+3. 重新生成时优先使用当前 session 的 `draft.profileId` 或 `publishedProfileId`，不得重新创建 session；后端读取同一 profile 的 `generated_item_assets_json` 后，只补齐缺失图片或缺失音频的阶段。
+4. 已有 `status = image_ready` 且带 `imageViews[]` 或 `imageSrc/imageObjectKey` 的素材视为完成，不再重复生成图片。
+
+抓大鹅结果页的基础信息自动保存继续调用 `PUT /api/runtime/match3d/works/{profileId}` 更新名称、题材、描述、标签、封面、消除数和难度；该保存不得清空 `generated_item_assets_json`。结果页 `素材配置 > 物品` 只在独立面板中预览和编辑当前素材，不再提供单项重新生成入口；删除单项或批量新增成功后，都必须把当前素材列表重新序列化成 `generatedItemAssets` 并写回作品 profile，否则试玩、发布和重进草稿会读取旧素材快照。SpacetimeDB `update_match3d_work` / `publish_match3d_work` 必须保留当前行的生成素材 JSON。
 
 草稿架重进路径为：
 
@@ -100,22 +155,56 @@ HTTP DTO 同时返回 `imageSrc`、`imageObjectKey`、空的 `modelSrc`、空的
 草稿 Tab -> getMatch3DWorkDetail(profileId) -> Match3DResultView(profile.generatedItemAssets)
 ```
 
-因此 `map_match3d_work_summary_response` / `map_match3d_work_profile_response` 需要从 work profile snapshot 反序列化 `generated_item_assets_json` 并输出 `generatedItemAssets`。前端 `Match3DResultView` 仍保持现有优先级：本次生成流程内有 `draft.generatedItemAssets` 时用 draft；从草稿架重进没有 draft 时，用 `profile.generatedItemAssets`；两者都没有才回退到默认 3D 素材占位。
+因此 `map_match3d_work_summary_response` / `map_match3d_work_profile_response` 需要从 work profile snapshot 反序列化 `generated_item_assets_json` 并输出 `generatedItemAssets` 与顶层背景字段。前端 `Match3DResultView` 的读取顺序为：有 `draft.generatedItemAssets` 时先用 draft 保留本次生成顺序和图片；同 `itemId` 在 `profile.generatedItemAssets` 中已有 `imageViews[]` 或 `imageSrc/imageObjectKey` 时，用 profile 图片字段补齐 draft；背景资产同样必须从 profile 或 draft 的首个 `backgroundAsset` 保留到保存 payload；从草稿架重进没有 draft 时，用 `profile.generatedItemAssets`；两者都没有才回退到默认素材占位。
 
 结果页 `作品信息` Tab 字段命名对齐拼图草稿：
 
 1. `作品名称` 对应 Match3D `gameName`。
 2. `作品描述` 对应 Match3D `summary`，草稿生成默认空。
 3. `作品标签` 对应 Match3D `tags`，可由 AI 首次生成并允许用户继续编辑。
-4. 封面图与作品名称不再拆成左右两个大模块；封面只作为同一 Tab 内的可选上传入口，避免和作品基础信息割裂。
+4. 封面图与作品名称不再拆成左右两个大模块；封面只作为同一 Tab 内的可选入口，避免和作品基础信息割裂。点击封面图必须弹出独立编辑面板，不允许在当前作品信息面板下方展开。封面面板布局参考拼图创作页上传卡：移动端优先、左侧/上方为方形预览，右侧/下方为提示词与操作区。面板支持三类输入：本地上传图片、上传后开启 AI 重绘、直接引用 `物品素材` 或 `UI素材` 中已有图片作为封面或 AI 重绘参考图。AI 重绘通过 `api-server` 的 Match3D 作品封面生成接口调用 VectorEngine `gpt-image-2-all`，生成结果转存到 `generated-match3d-assets/{sessionId}/{profileId}/cover/{taskId}/cover.png` 后再写回 `coverImageSrc`；关闭 AI 重绘时只把选中的 Data URL 或 generated legacy path 写入封面字段。
 
-`3D素材` 详情页只保留：
+结果页 `难度配置` Tab 取代旧 `玩法配置`，不再展示旧的分散输入项。该 Tab 必须与创作入口页使用同一组难度选项，并统一把原“类型素材图片 / 局内类型”等口径归一为 `物品种类`：
 
-1. 模型预览区：优先加载 `modelSrc` 对应 GLB，支持拖动旋转；没有模型时展示空预览。
+| 难度 | clearCount | difficulty | 总物品数 | 物品种类 |
+| ---- | ---------: | ---------: | -------: | -------: |
+| 轻松 |          8 |          2 |       24 |        3 |
+| 标准 |         12 |          4 |       36 |        9 |
+| 进阶 |         16 |          6 |       48 |       15 |
+| 硬核 |         21 |          8 |       63 |       21 |
+
+预览区展示 `需要消除`、`总物品数`、`物品种类` 和 `已生成物品种类`。历史草稿如果保存的是旧 `clearCount/difficulty`，前端按 `clearCount` 精确命中优先、否则按 `difficulty` 就近归一到上述选项，并把归一后的数值保存回 profile。发布校验以 `generatedItemAssets[]` 中 `image_ready` 且至少有 `5` 张有效 `imageViews[]` 的素材数量为准；试玩启动时用同一数量计算 `itemTypeCountOverride`，不足时自动降低，不修改草稿难度配置本身。历史单图 `imageSrc/imageObjectKey` 只作为运行态和预览兜底，不计入新发布素材完成数。
+
+结果页 `素材配置` Tab 取代旧一级素材入口，并包含三个子 Tab：
+
+1. `物品`：显示 2D 物品素材列表、五视角预览、素材名称、点击音效提示词和点击音效生成入口。
+2. `UI`：预览生成的竖屏游戏背景图，读取顺序为 draft 顶层背景、draft `generatedBackgroundAsset`、profile 顶层背景、profile `generatedBackgroundAsset`、`generatedItemAssets[].backgroundAsset`、本地参考图兜底。该页必须展示默认画面描述提示词，默认值来自草稿生成计划的 `backgroundPrompt` 或持久化 `backgroundAsset.prompt`；用户修改后点击重新生成，后端继续固定使用 `public/match3d-background-references/pot-fused-reference.png` 作为 VectorEngine `image` 参考图，并把新的 `backgroundAsset` 写回同一份 `generated_item_assets_json`。UI 子 Tab 还必须提供独立的运行态 UI 预览面板，直接用当前背景图模拟抓大鹅竖屏页面的顶部返回、倒计时、重开控件、锅状竞技区和底部托盘，不在 Tab 下方内联展开。
+3. `背景音乐`：承载原一级音乐 Tab 的背景音乐曲名、风格、生成进度和试听控件；背景音乐始终按纯音乐生成，前端不提供提示词输入。
+
+旧一级 `音乐` Tab 删除；抓大鹅背景音乐入口只保留在 `素材配置 > 背景音乐`。
+
+`素材配置 > 物品` 详情页只保留：
+
+1. 五视角预览区：优先展示 `imageViews[]`，缺失时展示兼容字段 `imageSrc/imageObjectKey`。
 2. 素材名称输入。
-3. `重新生成` 按钮。
+3. 可编辑的点击音效提示词输入。
+4. 点击音效生成入口。
 
-详情页不再展示参考图、用途、提示词、文生/图生切换、状态查询、下载列表、taskUuid 或 subscriptionKey。
+详情页不再展示参考图、用途、模型提示词、文生/图生切换、状态查询、下载列表、taskUuid 或 subscriptionKey。
+
+`物品素材` 列表项点击必须弹出独立预览面板，不允许在列表右侧或列表下方内联展示。预览面板只承担查看五视角图片、编辑素材名称、编辑点击音效提示词和生成点击音效；不再展示 `重新生成` 按钮。列表项自身支持单项删除，删除后立即把剩余 `generatedItemAssets` 写回作品 profile。批量新增通过列表顶部按钮打开独立面板，面板内每个输入框只输入一个物品名称，`新增物品名称` 按钮追加一个输入框；提交后按输入框顺序清洗、去重并调用 Match3D 作品批量生图接口。生成进度同时显示在批量新增面板和 `素材配置 > 物品` 列表顶部，面板可关闭，后台生成继续推进，不阻塞封面、音频等其他生成操作。后端复用草稿生成的素材图、切图、OSS 上传和可选点击音效流程，但仅作用于本次新增名称，不重新生成已有物品，不新增 SpacetimeDB 表，最终仍写回同一份 `generated_item_assets_json`。
+
+## 6.1 音频生成与扣费
+
+抓大鹅结果页音频生成复用通用创作音频路由：
+
+1. `素材配置 > 背景音乐` 默认读取首个 `generatedItemAssets[0].backgroundMusicTitle/backgroundMusicStyle`，用户可继续编辑曲名和风格；`backgroundMusicPrompt` 保留为空字符串兼容旧 JSON，生成请求固定传空 `prompt`。
+2. 物品点击音效默认读取对应 `generatedItemAssets[].soundPrompt`，用户可在 `素材配置 > 物品` 详情面板内编辑。
+3. 背景音乐与物品音效生成过程必须显示进度条；提交任务、等待生成、转存资产和完成分别推进到不同进度，不再只展示旋转图标。
+4. 音频生成完成后立即展示浏览器原生 audio 控件，支持试听。
+5. `POST /api/creation/audio/background-music/{task_id}/asset` 和 `POST /api/creation/audio/sound-effect/{task_id}/asset` 在真正拿到音频并转存资产前，由后端按 `taskId + 资产槽位` 幂等预扣 `10` 光点；任务仍在处理中时不扣费。资产下载、OSS 转存或资产绑定失败时后端自动退款。前端只展示生成按钮和进度，不自行计算或写入钱包。
+
+入口页 `生成音效` Toggle 复用同一扣费与资产绑定规则。默认关闭，关闭时草稿生成阶段不产生音频任务也不扣除音频光点；开启时每个首批物品的点击音效按单独任务和单独 `match3d_click_sound` 资产槽位扣费。音效生成失败不阻断草稿结果页进入，失败素材保留 `soundPrompt`，用户可在结果页物品详情面板手动重试。
 
 ## 7. 验收
 
@@ -125,6 +214,8 @@ HTTP DTO 同时返回 `imageSrc`、`imageObjectKey`、空的 `modelSrc`、空的
 npm run check:encoding
 npm run test -- src\services\miniGameDraftGenerationProgress.test.ts
 npm run test -- src\components\match3d-result\Match3DResultView.test.tsx
+npm run test -- src\components\match3d-runtime\Match3DRuntimeShell.test.tsx
+npm run test -- src\components\rpg-entry\RpgEntryFlowShell.agent.interaction.test.tsx
 npm run typecheck
 cargo test -p shared-contracts match3d --manifest-path server-rs\Cargo.toml
 cargo test -p spacetime-client match3d --manifest-path server-rs\Cargo.toml
@@ -135,4 +226,4 @@ cargo check -p spacetime-client --manifest-path server-rs\Cargo.toml
 cargo check -p spacetime-module --manifest-path server-rs\Cargo.toml
 ```
 
-真实草稿生成需要本地私密环境配置 `VECTOR_ENGINE_API_KEY` 和 OSS 访问变量；`HYPER3D_API_KEY` 只在结果页手动生成 3D 模型时需要。后端改动后使用 `npm run api-server` 启动，并检查 `/healthz`。
+真实草稿生成需要本地私密环境配置 `VECTOR_ENGINE_API_KEY` 和 OSS 访问变量；开启音频生成还需要对应音频上游配置。后端改动后使用 `npm run api-server` 启动，并检查 `/healthz`。

docs/technical/MATCH3D_F1_CREATION_ENTRY_AND_AGENT_UI_2026-04-30.md

@@ -4,7 +4,7 @@
 >
 > 2026-05-10 更新：抓大鹅入口页对齐拼图入口页，直接嵌入创作页模板 Tab。入口表单不再展示参考图、消除次数输入、难度数值滑杆和题材/物品/难度摘要框，仅保留题材主题大输入框和难度选项。难度选项负责派生 `clearCount` 与 `difficulty`，生成按钮必须展示 `消耗20光点`。
 >
-> 2026-05-10 补充：入口页新增 `3D素材风格` 横向滑动选择，首批风格参考图通过 VectorEngine `gpt-image-2-all` 生成并保存到 `public/match3d-style-references/`。最后一个选项为 `自定义`，点击后弹出独立面板填写画风描述。
+> 2026-05-12 补充：入口页风格选择收敛为 `2D素材风格`，首批常见 2D 素材风格参考图通过 `npm run assets:match3d-style-references -- --live` 调用 VectorEngine `gpt-image-2-all` 生成并保存到 `public/match3d-style-references/`。最后一个选项为 `自定义`，点击后弹出独立面板填写画风描述。
 
 ## 1. 阶段边界
 
@@ -40,11 +40,12 @@ badge: 可创建
 
 创作页 `选择模板` Tab 中切换到 `抓大鹅` 时，直接渲染该表单，不创建会话，也不跳到独立工作台。点击生成后才创建 Match3D 会话并执行 `match3d_compile_draft`。
 
-表单只展示三个输入块：
+表单只展示四个输入块：
 
 1. `想做一个什么题材的抓大鹅？`：大文本输入框，收集 `themeText`。
-2. `3D素材风格`：横向滑动风格卡，选择会写入 `assetStyleId`、`assetStyleLabel` 与 `assetStylePrompt`。
+2. `2D素材风格`：横向滑动风格卡，选择会写入 `assetStyleId`、`assetStyleLabel` 与 `assetStylePrompt`。
 3. `难度`：四个选项按钮，选项内部派生消除次数和难度数值。
+4. `生成音效`：Toggle，默认关闭，开启后提交 `generateClickSound=true`。
 
 当前难度映射固定为：
 
@@ -52,7 +53,7 @@ badge: 可创建
 轻松 -> clearCount 8,  difficulty 2
 标准 -> clearCount 12, difficulty 4
 进阶 -> clearCount 16, difficulty 6
-硬核 -> clearCount 20, difficulty 8
+硬核 -> clearCount 21, difficulty 8
 ```
 
 入口页不再上传参考图，提交 payload 中 `referenceImageSrc` 固定为 `null`。如果从旧会话或旧草稿恢复，前端只根据已有 `difficulty` 选择最接近的难度选项，并按当前选项重新派生 `clearCount` 与 `difficulty`。
@@ -60,7 +61,7 @@ badge: 可创建
 内置风格选项为：
 
 ```text
-黏土手作 / 低多边形 / 玩具塑料 / 木质雕刻 / 体素积木 / 金属机甲 / 自定义
+扁平图标 / 赛璐璐卡通 / 像素复古 / 手绘水彩 / 贴纸描边 / 厚涂图标 / 自定义
 ```
 
 自定义风格必须在弹出面板中填写描述后才能应用。入口表单必须在移动端创作页可视区内完成题材、风格、难度和生成按钮的展示，页面自身不产生纵向滚动；风格卡只允许横向滑动。

docs/technical/MATCH3D_F2_RESULT_AND_PUBLISH_2026-04-30.md

@@ -275,6 +275,12 @@ type Match3DAutoSaveState = 'idle' | 'saving' | 'saved' | 'error';
 
 F2 不实现运行态本身；只冻结结果页如何发起试玩。
 
+### 12.1 生成完成自动试玩补充（2026-05-12）
+
+抓大鹅表单生成草稿完成后，如果用户仍停留在 `match3d-generating` 进度页，前端应立即用刚生成的 `Match3DWorkProfile` 启动试玩，并把运行态返回目标设置为 `match3d-result`。试玩过程中点击左上角返回时，进入同一份抓大鹅草稿结果页查看与编辑。
+
+该自动试玩只响应当前等待中的生成页；如果用户已经返回草稿 Tab 或切到其它页面，后台生成完成只更新草稿可见状态，不主动切屏。自动启动失败时，仍保留结果页草稿作为兜底入口。
+
 ---
 
 ## 13. 发布接口

docs/technical/MATCH3D_RODIN_ASSET_TAB_2026-05-10.md

@@ -18,13 +18,13 @@
 
 ## 3. Rodin 任务边界
 
-前端只维护当前页面内的临时重新生成任务状态：
+前端只维护当前页面内的临时重新生成任务状态；草稿生成得到的正式模型资产从 `generatedItemAssets.modelSrc` 恢复：
 
 1. 素材槽位名称。
 2. 模型预览。草稿生成的 `/generated-match3d-assets/...` GLB 必须通过同源 `/api/assets/read-bytes` 由后端换签并读取字节，前端再转成 Blob URL 后交给 Three.js GLTFLoader，避免浏览器直接 `fetch` OSS 签名 URL 时被 CORS 拦截。
 3. 图生模型参考图只作为重新生成的隐藏输入来源，不在详情页展示。上传图片在前端直接读成 Data URL；草稿生成的 `/generated-match3d-assets/...` 图片必须通过 `/api/assets/read-bytes` 转成 Data URL 后提交给 Hyper3D。
-4. Hyper3D `taskUuid` 与 `subscriptionKey`。
+4. Hyper3D `taskUuid` 与 `subscriptionKey` 仅用于重新生成过程，不在详情页展示。
-5. 查询到的状态、进度与下载文件列表。
+5. 查询到的状态、进度与下载文件列表仅作为内部状态，不在详情页展示。
 
 正式资产链后续再接：
 

docs/technical/NEW_WORK_ENTRY_CONFIG_2026-05-01.md

@@ -2,18 +2,19 @@
 
 ## 背景
 
-创作中心的模板 Tab、平台创作类型弹层和旧“新建作品”卡片配置都依赖同一组玩法模板。此前入口开放状态、隐藏状态和中文文案集中写在 `src/components/platform-entry/platformEntryCreationTypes.ts` 与入口组件中，后续切换玩法开放节奏时容易出现多个入口不一致。
+创作中心的模板 Tab、平台创作类型弹层和旧“新建作品”卡片配置都依赖同一组玩法模板。此前入口开放状态、隐藏状态和中文文案集中写在前端配置与入口组件中，后续切换玩法开放节奏时容易出现多个入口不一致。当前入口配置事实源已经迁移到 SpacetimeDB，由 `api-server` 通过 `GET /api/creation-entry/config` 下发。
 
 ## 落地规则
 
-1. 新建作品入口配置统一放在 `src/config/newWorkEntryConfig.ts`。
+1. 新建作品入口配置统一存放在 SpacetimeDB 的 `creation_entry_config` / `creation_entry_type_config` 表；默认种子位于 `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs`。
 2. `visible` 控制玩法是否展示在创作 Tab 模板入口、新建作品入口和创作类型弹层中。
-3. `open` 控制玩法是否允许点击创建；`open: false` 时入口保持展示但禁用。
+3. `open` 控制玩法是否允许点击创建以及对应创作 / runtime API 路由是否放行；`open: false` 时入口保持展示但禁用，并由 `api-server` 熔断对应玩法 API。
 4. `title`、`subtitle`、`badge` 控制玩法卡片文案。
 5. `startCard` 控制旧创作中心顶部新建作品模块的标题、辅助文案和移动端角标文案；当前创作 Tab 首屏标题固定在 `PlatformEntryFlowShellImpl.tsx`，不再由 `startCard` 控制。
 6. `typeModal` 控制平台创作类型弹层标题和描述。
 7. 入口排序仍遵循“可创建玩法在前，未开放玩法在后”；同组内部沿用配置顺序。
 8. `creative-agent` 可以继续保留运行链路，但默认 `visible: false`，不出现在创作 Tab 模板入口。
+9. 前端 `src/components/platform-entry/platformEntryCreationTypes.ts` 只做展示派生，不再承载默认入口配置。
 
 ## 当前状态
 
@@ -23,17 +24,17 @@
 | 大鱼吃小鱼 | 否 | 是 | 功能仍保留，不在新建作品入口展示 |
 | 拼图 | 是 | 是 | 创作 Tab 默认选中并内嵌展示拼图创作表单，提交后进入拼图草稿生成 |
 | 抓大鹅 | 是 | 是 | 点击后进入抓大鹅 Match3D Agent 共创工作台 |
-| 方洞挑战 | 是 | 是 | 点击后进入方洞挑战 Agent 共创工作台，支持草稿、结果页、发布、试玩、作品架与广场 |
+| 方洞挑战 | 否 | 是 | 创作页入口暂时完全隐藏，既有草稿、结果页、发布、试玩、作品架与广场链路保留 |
 | AIRP | 是 | 否 | 保留入口，显示敬请期待 |
-| 视觉小说 | 是 | 是 | 点击后进入视觉小说创作工作台 |
+| 视觉小说 | 是 | 否 | 保留入口，显示敬请期待，暂不允许创建视觉小说草稿 |
 | 智能创作 | 否 | 是 | 入口隐藏，既有 `creative-agent` 链路保留 |
 
 ## 验收
 
-1. 修改 `src/config/newWorkEntryConfig.ts` 后，创作 Tab 模板入口、创作中心顶部卡带和平台创作类型弹层应同步变化。
+1. 修改 SpacetimeDB 入口配置后，创作 Tab 模板入口、创作中心顶部卡带和平台创作类型弹层应同步变化。
 2. 隐藏玩法不触发入口预加载，也不出现在新建作品入口中。
 3. 未开放玩法点击态保持禁用，不应进入鉴权或创建会话链路。
 4. 已开放玩法点击后必须进入对应创建链路；若用户未登录，先走登录保护。
 5. 创作 Tab 首屏应显示“10分钟创作一个精品互动玩法”，并默认展示拼图创作表单。
 6. 智能创作入口隐藏后，不应出现“Hi, 朋友”“问一问百梦”或“一句话生成闪应用”等旧首页入口。
-7. 方洞挑战作品发布后应生成 `SH-` 作品号，并能从作品架、广场详情和试玩 runtime 回到同一作品详情。
+7. 方洞挑战入口隐藏后，不应出现在创作 Tab 模板入口、创作中心顶部卡带、平台创作类型弹层和创作页作品架中；既有 `SH-` 作品号、广场详情和试玩 runtime 链路不因此删除。

docs/technical/PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md

@@ -32,7 +32,8 @@
 2. 请求字段：`currentPassword`、`newPassword`。
 3. 若账号未设置过密码，允许 `currentPassword` 为空并设置首个密码。
 4. 若账号已有密码，必须校验 `currentPassword` 后才能写入 `newPassword`。
-5. 修改成功后递增用户 `token_version`，使旧 access token 失效；前端沿用当前 refresh 会话刷新登录态。
+5. 修改成功后递增用户 `token_version`，使旧 access token 失效。
+6. `2026-05-13` 起，修改密码成功后必须撤销该用户全部 active `refresh_session`，并在响应中清除当前 refresh cookie；前端清空本地 access token 并回到未登录态。用户需要使用新密码重新登录。
 
 ### 2.3 重置密码
 
@@ -76,3 +77,16 @@
 3. 只有用户显式修改或重置密码后，才允许密码登录。
 
 后续迁移到 SpacetimeDB 表时，保持同一语义：密码哈希字段允许为空，密码登录 reducer 不承担注册能力，验证码登录 reducer 承担“无账号则自动注册”的唯一注册入口。
+
+## 5. 2026-05-12 快照同步修复
+
+重置密码和修改密码都会改变认证真相：`password_hash`、`password_login_enabled`、`token_version`，重置密码还会立即创建新的 refresh session，修改密码还会撤销全部旧 refresh session。因此 API 层在 `POST /api/auth/password/change` 与 `POST /api/auth/password/reset` 成功后，必须和密码登录、手机号登录、刷新、退出一样调用 `sync_auth_store_snapshot_to_spacetime()`。
+
+若只更新本地 `InMemoryAuthStore` 而不同步 SpacetimeDB 认证快照，`api-server` 重启时可能从旧的 SpacetimeDB 表或旧快照恢复账号状态，表现为用户已通过忘记密码重设成功，但再次密码登录仍返回“手机号或密码错误”。启动恢复时应从 SpacetimeDB 表、SpacetimeDB 快照记录和本地 `GENARRATIVE_AUTH_STORE_PATH` 文件中选择可判断的最新快照；当本地文件更新且远端表无更新时间戳时，优先使用本地文件并尝试回写 SpacetimeDB，避免旧远端状态覆盖刚重设的密码。
+
+验证命令：
+
+```bash
+cargo test -p module-auth password --manifest-path server-rs/Cargo.toml
+cargo test -p api-server password --manifest-path server-rs/Cargo.toml
+```

docs/technical/PLATFORM_MOBILE_RECOMMEND_CARD_SAFE_SWIPE_LAYOUT_2026-05-12.md

@@ -0,0 +1,21 @@
+# 平台移动端推荐页卡片与滑动热区布局 2026-05-12
+
+## 背景
+
+移动端推荐页承载嵌入式作品运行态，顶部品牌栏和底部导航上方留白会压缩首屏可玩区域。推荐页同时需要纵向切换作品，但不能让切换手势覆盖作品运行态内部的点击、拖拽、滑动热区。
+
+## 落地口径
+
+1. 仅推荐页隐藏移动端顶部品牌栏，发现、创作、草稿、我的页继续保留原顶部结构。
+2. 推荐页外层使用独立 shell class，把原顶部区域和底部导航上方额外留白让给推荐卡片。
+3. 推荐页运行态画面保持独立可交互区域，不挂平台切换作品的 pointer 手势。
+4. 切换作品的纵向手势只绑定在卡片底部作品信息区；底部信息区可以扩大触控高度，但不得绝对定位覆盖运行态画面。
+5. 点赞、分享、改造按钮继续阻止 pointer 事件冒泡，避免按钮点击误触发切换作品。
+
+## 验收
+
+1. 手机竖屏进入推荐页时，首屏不显示顶部品牌标题。
+2. 推荐卡片上沿贴近可视区域顶部，下沿贴近底部导航上方。
+3. 在作品运行态画面内点击、拖拽或滑动，只触发作品自身交互。
+4. 在底部作品信息区上下滑动，可以切换推荐作品。
+5. 点赞、分享、改造按钮可正常点击，不触发作品切换。

docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md

@@ -132,8 +132,8 @@ SpacetimeDB 公网路由默认保持收敛，只按实际前端 SDK 需要暴露
 
 Nginx 配置文件分为两类：
 
-- `deploy/nginx/genarrative.conf`：生产正式域名 HTTPS 配置，`genarrative.example.com` 只是占位域名，安装时必须替换为真实 `SERVER_NAME`，并要求 `/etc/letsencrypt/live/<SERVER_NAME>/fullchain.pem` 与 `privkey.pem` 已存在。
+- `deploy/nginx/genarrative.conf`：生产正式域名 HTTPS 配置，`genarrative.example.com` 只是占位域名，安装时必须替换为真实 `SERVER_NAME`，并要求 `/etc/letsencrypt/live/<SERVER_NAME>/fullchain.pem` 与 `privkey.pem` 已存在。`SERVER_NAME` 只填证书主目录名对应的单个域名；`www` 等额外域名通过 `SERVER_ALIASES` 写入 Nginx `server_name`，不参与证书目录拼接。
-- `deploy/nginx/genarrative-dev-http.conf`：开发服无域名时的 HTTP-only 配置，只允许 `DEPLOY_TARGET=development` 使用。没有域名时，`SERVER_NAME` 填开发机 IP 或临时主机名。它仍复用同一套静态目录、后台 API 反代、临时主站 `/api/*` 反代和 SpacetimeDB SDK 最小公网路由，不恢复旧 `/generated-*` 或公网 `/healthz`。
+- `deploy/nginx/genarrative-dev-http.conf`：开发服无域名时的 HTTP-only 配置，只允许 `DEPLOY_TARGET=development` 使用。没有域名时，`SERVER_NAME` 填开发机 IP 或临时主机名；如有多个入口，额外域名或 IP 填 `SERVER_ALIASES`。它仍复用同一套静态目录、后台 API 反代、临时主站 `/api/*` 反代和 SpacetimeDB SDK 最小公网路由，不恢复旧 `/generated-*` 或公网 `/healthz`。
 
 ## 维护模式
 
@@ -272,13 +272,14 @@ journalctl -u 'jenkins-agent@*.service' -f
 
 Jenkins controller 与 Linux agent 看到的 Git 服务地址不同，必须拆成两层配置：
 
-- Jenkins Job 的 `Pipeline script from SCM` 由 controller 执行，SCM URL 使用 controller 可访问的公网地址：`http://82.157.175.59:3000/GenarrativeAI/Genarrative.git`。
+- Jenkins Job 的 `Pipeline script from SCM` 由 controller 执行，SCM URL 使用 controller 可访问的公网域名：`https://git.genarrative.world/GenarrativeAI/Genarrative.git`。
-- Jenkinsfile 内部的源码、脚本 checkout 在 Linux agent 上执行，`GIT_REMOTE_URL` 使用 agent 本机可访问地址：`http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`。
+- Jenkinsfile 内部的源码、脚本 checkout 在 Linux agent 上执行，`GIT_REMOTE_URL` 优先使用 agent 本机可访问地址：`http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`。
+- 若 `127.0.0.1` Git 服务在当前 Linux agent 上不可达，发布、数据库和服务器配置类 Jenkinsfile 会用 `GIT_REMOTE_FALLBACK_URL=https://git.genarrative.world/GenarrativeAI/Genarrative.git` 重新 checkout。该首次 checkout 只拉 `SOURCE_BRANCH` 单分支、`depth=1` 且不拉 tags，避免 release agent 通过公网备用地址拉取全仓库历史时被 Jenkins Git checkout timeout 杀掉；`scripts/jenkins-checkout-source.sh` 后续 fetch 也会按主地址、域名备用地址顺序重试，并在日志中输出最终使用的远端。
 - 这里的 `3000` 是 Git/Web 服务端口，不是 SpacetimeDB 端口；生产 SpacetimeDB 固定使用 `http://127.0.0.1:3101`，避免流水线部署时与本机 Git 服务抢端口。
 
-因此生产 Jenkinsfile 不使用 `checkout scm` 作为构建源码入口，而是显式 `checkout([$class: 'GitSCM', userRemoteConfigs: [[url: "${GIT_REMOTE_URL}"]], ...])`。后续 `scripts/jenkins-checkout-source.sh` 会继续把 `origin` 设置为 `GIT_REMOTE_URL`，并按 `SOURCE_BRANCH` / `COMMIT_HASH` 拉取和校验目标提交。
+因此生产 Jenkinsfile 不使用 `checkout scm` 作为构建源码入口，而是显式 `checkout([$class: 'GitSCM', userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/<SOURCE_BRANCH>:refs/remotes/origin/<SOURCE_BRANCH>"]], ...])`。首次 checkout 先尝试 `GIT_REMOTE_URL`，失败后尝试 `GIT_REMOTE_FALLBACK_URL`，两次都必须保持单分支浅克隆和 `noTags=true`；后续 `scripts/jenkins-checkout-source.sh` 会继续把 `origin` 设置为实际可用远端，并按 `SOURCE_BRANCH` / `COMMIT_HASH` 拉取和校验目标提交。
 
-`127.0.0.1` 只代表当前执行该阶段的 Linux agent 自身；如果 release agent 与 Git 服务不在同一台机器，必须把对应 Jenkinsfile 的 `GIT_REMOTE_URL` 改成 release agent 可访问的内网地址，不能让 release 发布阶段回退到 controller 公网拉取。
+`127.0.0.1` 只代表当前执行该阶段的 Linux agent 自身；如果 release agent 与 Git 服务不在同一台机器，`GIT_REMOTE_FALLBACK_URL` 统一使用 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`，不要再配置内网 IP 备用地址。
 
 ### SSH PEM 凭证
 
@@ -323,7 +324,7 @@ Jenkins controller 与 Linux agent 看到的 Git 服务地址不同，必须拆
 
 构建流水线运行在当前 Linux agent 的脱敏 label expression `linux && genarrative-build`。发布、导入导出和服务器配置流水线通过 `DEPLOY_TARGET` 映射到 Linux-only 脱敏部署表达式；其中 `development` 映射到当前 Linux 开发/构建/开发部署 agent 的 `linux && genarrative-build`，`release` 映射到独立 Linux 生产部署 agent 的 `linux && genarrative-release-deploy`，不能复用当前开发/构建/开发部署 agent。真实机器名、IP 和带 IP 的 Jenkins label 只允许留在 Jenkins 节点连接配置中，不能暴露为 Job 参数默认值、调度标签或文档推荐值。
 
-发布流水线通过 Jenkins `copyArtifacts(...)` 从对应构建 Job 获取归档产物，因此 Jenkins 需要安装并启用 Copy Artifact 插件。Web 大包例外：`Genarrative-Web-Build` 只把轻量元数据归档到 Jenkins controller，`web.tar.gz` 保留在 Linux 构建机稳定目录 `/var/cache/genarrative-build/web-artifacts/`，`Genarrative-Web-Deploy` 在部署目标机器上按构建 Job、构建号和版本号读取该目录。development 目标天然共享当前 Linux 开发/构建/开发部署机；release 目标若不是同一台机器，必须先把该目录通过共享存储、rsync 或其它内网同步方式提供给 release 部署 agent。数据库导入流水线的手动上传模式使用 `stashedFile` 文件参数，因此 Jenkins 还需要安装并启用 File Parameter 插件。所有生产 Pipeline 日志必须带时间戳以便审计，Jenkins 需要安装 Timestamper 插件，并在全局配置中启用 `Enabled for all Pipeline builds`。邮件通知流水线使用 Jenkins Pipeline `mail` step，Jenkins 需要安装/启用 Mailer 能力，并在系统配置中配置 SMTP。生产发布不能退回到读取构建 workspace 本地目录的旧模式。
+发布流水线通过 Jenkins `copyArtifacts(...)` 从对应构建 Job 获取归档产物，因此 Jenkins 需要安装并启用 Copy Artifact 插件。Web 大包例外：`Genarrative-Web-Build` 只把轻量元数据归档到 Jenkins controller，`web.tar.gz` 保留在 Linux 构建机稳定目录 `/var/cache/genarrative-build/web-artifacts/`，`Genarrative-Web-Deploy` 在部署目标机器上按构建 Job、构建号和版本号读取该目录。development 目标天然共享当前 Linux 开发/构建/开发部署机；release 目标若不是同一台机器，发布流水线默认在本地缓存缺少 `web.tar.gz` 时通过 `rsync` 从 SSH Host `genarrative-build-internal` 拉取同一路径内容。该 Host 必须配置在 release 服务器上 Jenkins 运行用户的 SSH config 中，真实内网 IP、用户和私钥路径只保存在服务器本机；如需改名或指定 config，可通过 `WEB_ARTIFACT_SYNC_HOST` / `WEB_ARTIFACT_SYNC_SSH_CONFIG` 参数覆盖。也可以提前通过共享存储或其它内网同步方式提供该目录。数据库导入流水线的手动上传模式使用 `stashedFile` 文件参数，因此 Jenkins 还需要安装并启用 File Parameter 插件。所有生产 Pipeline 日志必须带时间戳以便审计，Jenkins 需要安装 Timestamper 插件，并在全局配置中启用 `Enabled for all Pipeline builds`。邮件通知流水线使用 Jenkins Pipeline `mail` step，Jenkins 需要安装/启用 Mailer 能力，并在系统配置中配置 SMTP。生产发布不能退回到读取构建 workspace 本地目录的旧模式。
 
 邮件通知的持久收件人不写入 Git，由 Jenkins `Secret text` 凭据 `genarrative-notification-emails` 保存，凭据内容为逗号分隔邮箱。所有生产流水线仍提供 `NOTIFICATION_EMAILS` 参数作为本次运行的追加收件人；通知 Job 会把持久收件人凭据与本次 `NOTIFICATION_EMAILS` 合并去重后发送，参数留空时只发送给持久收件人。流水线结束时在 `post { always { ... } }` 中异步触发 `Genarrative-Notify-Email`，把来源 Job、构建号、构建 URL、结果、源码分支、源码 commit、发布版本、部署目标和数据库名传给通知 Job。通知 Job 失败不能反向改变业务流水线结果，只在来源流水线日志中记录触发失败。
 
@@ -424,8 +425,8 @@ WASM_SOURCE="${CARGO_TARGET_DIR}/wasm32-unknown-unknown/release/spacetime_module
 
 执行规则：
 
-- 流水线先按 Jenkins SCM 配置 checkout 仓库，再执行 `git fetch --tags --prune origin "+refs/heads/<SOURCE_BRANCH>:refs/remotes/origin/<SOURCE_BRANCH>"`。
+- 流水线先按 Jenkins SCM 配置 checkout 仓库，再执行单分支 `git fetch --no-tags --prune origin "+refs/heads/<SOURCE_BRANCH>:refs/remotes/origin/<SOURCE_BRANCH>"`；`COMMIT_HASH` 为空时追加 `--depth=1`。
-- 如果工作区是浅克隆，流水线必须尝试 `git fetch --unshallow --tags`，确保能验证目标 commit 与分支关系。
+- 如果工作区是浅克隆，只有在 `COMMIT_HASH` 非空、需要验证指定提交属于目标分支时，流水线才尝试 `git fetch --unshallow --no-tags`。`COMMIT_HASH` 为空时只需要目标分支 HEAD，必须保持 `--depth=1 --no-tags`，避免普通发布或服务器配置任务拉取全仓库历史。
 - `COMMIT_HASH` 为空时，detached checkout 到 `refs/remotes/origin/<SOURCE_BRANCH>` 当前最新 commit。
 - `COMMIT_HASH` 非空时，先解析到完整 commit，再用 `git merge-base --is-ancestor <commit> refs/remotes/origin/<SOURCE_BRANCH>` 校验该提交属于指定分支，校验通过后 detached checkout。
 - 流水线日志必须输出最终 `SOURCE_BRANCH` 与实际 `SOURCE_COMMIT`。
@@ -462,7 +463,7 @@ WASM_SOURCE="${CARGO_TARGET_DIR}/wasm32-unknown-unknown/release/spacetime_module
 该流水线属于高风险操作，默认要求人工确认后执行。
 已落地的 Jenkinsfile 为 `jenkins/Jenkinsfile.production-server-provision`。该流水线默认 `DRY_RUN=true`，只打印将执行的初始化动作；真正写入系统用户、目录、systemd、环境文件并启动服务时，必须设置 `DRY_RUN=false` 且勾选 `CONFIRM_PROVISION`。当 `DEPLOY_TARGET=release` 时，还必须勾选 `CONFIRM_RELEASE_DEPLOY_AGENT`，并通过 `linux && genarrative-release-deploy` 调度到独立 release 部署 agent。
 
-首次真实初始化默认保持 `NGINX_CONFIG_MODE=none`，先完成系统用户、目录、SpacetimeDB、systemd unit 与 `/etc/genarrative/api-server.env` 落盘。开发服没有域名时，使用 `DEPLOY_TARGET=development` + `NGINX_CONFIG_MODE=development-http` 安装 `deploy/nginx/genarrative-dev-http.conf`，并把 `SERVER_NAME` 填为开发机 IP 或临时主机名。等正式域名确定，并且目标机已经存在 `/etc/letsencrypt/live/<SERVER_NAME>/fullchain.pem` 与 `/etc/letsencrypt/live/<SERVER_NAME>/privkey.pem` 后，再把 `SERVER_NAME` 改成真实域名，并设置 `NGINX_CONFIG_MODE=production-https` 安装 Nginx HTTPS 配置。流水线会拒绝 release 目标安装 `development-http`，也会拒绝用占位域名或缺失证书安装 `production-https`。Nginx 配置写入后必须先 `nginx -t`，再 `nginx -s reload`，不能只验证配置而不重载当前进程。
+首次真实初始化默认保持 `NGINX_CONFIG_MODE=none`，先完成系统用户、目录、SpacetimeDB、systemd unit 与 `/etc/genarrative/api-server.env` 落盘。开发服没有域名时，使用 `DEPLOY_TARGET=development` + `NGINX_CONFIG_MODE=development-http` 安装 `deploy/nginx/genarrative-dev-http.conf`，并把 `SERVER_NAME` 填为开发机 IP 或临时主机名。等正式域名确定，并且目标机已经存在 `/etc/letsencrypt/live/<SERVER_NAME>/fullchain.pem` 与 `/etc/letsencrypt/live/<SERVER_NAME>/privkey.pem` 后，再把 `SERVER_NAME` 改成证书主域名，并设置 `NGINX_CONFIG_MODE=production-https` 安装 Nginx HTTPS 配置。如果同一张证书同时覆盖根域名和 `www` 域名，`SERVER_NAME` 仍只填证书目录名，例如 `genarrative.world`，`SERVER_ALIASES` 填 `www.genarrative.world`。流水线会拒绝 release 目标安装 `development-http`，也会拒绝用占位域名或缺失证书安装 `production-https`。Nginx 配置写入后必须先 `nginx -t`，再 `nginx -s reload`，不能只验证配置而不重载当前进程。
 
 若误用占位域名执行过真实初始化，失败通常发生在 `nginx -t`，错误表现为找不到 `/etc/letsencrypt/live/genarrative.example.com/fullchain.pem` 或 `privkey.pem`。新版初始化在 `NGINX_CONFIG_MODE=none` 时会检测并禁用上一轮留下的占位域名 Nginx 配置，避免它继续影响后续 `nginx -t`。
 
@@ -482,6 +483,7 @@ WASM_SOURCE="${CARGO_TARGET_DIR}/wasm32-unknown-unknown/release/spacetime_module
 
 - 先按 `SOURCE_BRANCH` / `COMMIT_HASH` 解析并 checkout 部署脚本源码，默认使用 `origin/master` 最新 commit；上游构建触发时使用上游传入的实际构建 commit。
 - 通过 Jenkins 归档获取 `web.tar.gz.sha256`、`release-manifest.json` 和 `web-artifact-pointer.txt`，再从 `/var/cache/genarrative-build/web-artifacts/<job>/<build>/<version>/` 读取 `web.tar.gz`；先校验 checksum，再解压到 `/opt/genarrative/releases/<version>/web`。
+- 当 `DEPLOY_TARGET=release` 且 release 服务器本地缓存缺少 `web.tar.gz` 时，默认先执行 `rsync -av --progress <WEB_ARTIFACT_SYNC_HOST>:/var/cache/genarrative-build/web-artifacts/<job>/<build>/<version>/ /var/cache/genarrative-build/web-artifacts/<job>/<build>/<version>/`，再继续校验 checksum；默认 Host 为 `genarrative-build-internal`，由 release 服务器本机 SSH config 解析。
 - 更新 `/opt/genarrative/current` 与 `/srv/genarrative/web` 指向。
 - 执行 Nginx 配置测试和静态页面 smoke test。
 - 不进入维护模式。

docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md

@@ -6,6 +6,12 @@
 
 2026-05-03 后入口进一步收口为画面描述直创：入口表单只保留画面描述、参考图和图片模型选择；作品名称、作品描述、作品标签全部进入结果页补全。若本文件早期段落仍提到入口必填作品名称或作品描述，以 `PUZZLE_PICTURE_ONLY_CREATION_AND_AI_TAGS_2026-05-03.md` 为准。
 
+## 首访新手引导隐藏
+
+2026-05-12 起，平台首访不再自动进入 `puzzle-onboarding` 新手引导步骤。前端应直接停留在平台入口；旧新手引导面板、生成接口和保存接口暂时保留为休眠代码，后续只有在产品明确恢复时才重新打开分流开关。
+
+首访隐藏不写入 `genarrative.puzzle-onboarding.first-visit.v1`，避免把“引导未展示”误记录成玩家已主动完成或跳过。
+
 ## 入口表单
 
 ### 2026-05-03 画面描述直创补充
@@ -87,10 +93,28 @@
 
 ## 结果页
 
-拼图草稿结果页分为两个 Tab：
+拼图草稿结果页分为四个 Tab：
 
 1. 拼图关卡列表：默认展示草稿生成出的第一关。列表项参考 RPG 草稿卡片样式，显示画面图、关卡名称和轻量状态。支持新增关卡、删除关卡。点击列表项进入独立关卡详情页，不在列表项下方展开。关卡详情页可编辑关卡名称、画面描述、生成或重新生成画面，并在已有正式图后支持关卡测试。
 2. 作品信息：展示并编辑作品名称、作品描述、作品标签。
+3. UI：展示并编辑拼图运行态 UI 背景提示词。`compile_puzzle_draft` 草稿编译完成首图和背景音乐后，`api-server` 会基于作品名称、作品描述、标签和首关信息自动生成首关 9:16 UI 背景图；结果页继续支持用户修改提示词并通过 `generate_puzzle_ui_background` 重新生成。图片生成在 `api-server` 中读取 `public/ui-previews/puzzle-image-compact-ui-2026-05-08.png` 作为非拼图 UI 背景参考图，并调用 VectorEngine `gpt-image-2-all` 的 `9:16` 图片生成链路。生成结果写入首关 `levels_json` 的 `uiBackgroundPrompt`、`uiBackgroundImageSrc`、`uiBackgroundImageObjectKey`，不新增 SpacetimeDB 表字段。
+4. 音乐：编辑并生成背景音乐，音乐资产暂存到首关 `levels_json[0].backgroundMusic`。
+
+### 2026-05-12 UI 背景生成补充
+
+1. UI 背景图只生成拼图棋盘以外的运行态背景与 UI 容器层次，提示词必须要求中央正方形拼图区和外部 UI 背景之间有明确描边、容器或留白边界。
+2. UI 背景图不得生成文字、水印、按钮文字、数字、拼图碎片、完整拼图图像或教程浮层，避免与真实拼图图块和运行态 HUD 混淆。
+3. 结果页 UI Tab 支持直接修改提示词并重新生成；点击生成前会把本地首关 `uiBackgroundPrompt` 同步进 `levelsJson`，使自动保存尚未完成时后端仍能拿到最新提示词。
+4. 草稿编译阶段自动生成 UI 背景失败时只记录 warning，并保留草稿进入结果页；用户可在 UI Tab 重新生成，不因背景图上游波动阻断首图草稿主流程。
+5. `api-server` 负责读取参考图、拼接生成 prompt、调用 VectorEngine、下载并转存 OSS；SpacetimeDB 只通过 `save_puzzle_ui_background` procedure 保存结果，不做外部 I/O。
+6. 拼图运行态读取 `currentLevel.uiBackgroundImageSrc` 渲染为全屏背景；无 UI 背景图时继续使用原封面模糊背景兜底。棋盘本身仍由正式拼图图生成，不能把 UI 背景当作拼图切块来源。
+
+### 2026-05-12 草稿生成完成自动试玩补充
+
+1. 玩家停留在拼图草稿生成进度页等待 `compile_puzzle_draft` 完成时，前端必须先把最新 session / profile 记为草稿结果页状态，再自动启动本地拼图试玩。
+2. 自动试玩的返回目标固定为 `puzzle-result`。玩家在试玩过程中点击左上角返回后，应进入同一份拼图草稿结果页继续查看和编辑。
+3. 自动试玩只在当前仍处于 `puzzle-generating` 时触发；若玩家已返回草稿 Tab 或切到其它页面，后台生成完成只标记草稿已生成，不得强行抢屏进入试玩。
+4. 若自动启动试玩失败，前端保留草稿结果页作为兜底查看入口，并展示已有错误态，不应丢失已生成草稿。
 
 ### 2026-04-30 关卡列表卡片交互补充
 
@@ -107,7 +131,7 @@
 6. api-server 处理 `generate_puzzle_images` 时，若 action 带有 `levelsJson`，必须用这份关卡快照覆盖本次生成的草稿关卡视图后再定位 `levelId`。若请求明确传入 `levelId` 但关卡列表中不存在该关卡，必须返回错误，不得静默回退第一关。
 7. 历史拼图素材入口和本地上传参考图入口统一收口到 `画面图` 图卡右下角，避免 `画面描述` 输入区同时承载文本编辑和素材入口；无正式图时也展示空图态图卡。
 8. 历史拼图素材列表必须由服务端按当前登录账号过滤，只返回 `asset_kind = puzzle_cover_image` 且 `owner_user_id = 当前账号` 的资产；不得依赖前端过滤，也不得展示其他账号素材。
-9. `画面图` 图卡本身就是上传热区，详情页不再保留右下角独立“上传参考图”按钮；历史入口统一使用带 `History` 图标和 `历史` 小字的按钮。入口页空图态的“点击上传拼图图片”只作为图卡内轻量提示，不使用胶囊按钮、边框或背景样式。
+9. `画面图` 图卡本身就是上传热区，详情页不再保留右下角独立“上传参考图”按钮；历史入口统一使用带 `History` 图标和 `历史` 小字的按钮。入口页历史按钮固定在图片上传区域右上角；空图态只展示“上传图片/填写画面描述”轻量提示，不再展示额外规则说明文案。
 
 ### 2026-05-10 关卡生图交互补充
 
@@ -126,8 +150,9 @@
 ## 验收
 
 1. 从拼图创作入口只能看到作品名称、作品描述、画面描述和参考图上传，不出现 Agent 聊天输入、补齐设定、锚点问答。
-2. 点击确认后进入拼图草稿生成进度页，并自动完成草稿编译、首图生成、正式图选择。
+2. 点击确认后进入拼图草稿生成进度页，并自动完成草稿编译、首图生成、正式图选择、背景音乐生成和首关 UI 背景图生成。
 3. 首图生成请求使用玩家画面描述作为 prompt；上传参考图时走图生图；作品详情页展示玩家作品描述。
-4. 结果页包含“拼图关卡”和“作品信息”两个 Tab；关卡列表默认至少一关，支持新增、删除和进入关卡详情。
+4. 结果页包含“拼图关卡”“作品信息”“UI”“音乐”四个 Tab；关卡列表默认至少一关，支持新增、删除和进入关卡详情。
 5. 关卡详情页支持生成或重新生成画面；已有正式图后显示吸底“关卡测试”入口。
 6. 发布、作品测试、自动保存作品名称、作品描述、作品标签和关卡列表仍可用。
+7. 草稿初次生成后首关默认带 `uiBackgroundImageSrc`；UI Tab 可修改提示词并重新生成背景图；生成后运行态应显示 `uiBackgroundImageSrc`，且拼图棋盘区域和 UI 背景区域有明确边界。

docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md

@@ -0,0 +1,105 @@
+# 拼图与抓大鹅结果页音乐入口 2026-05-11
+
+## 1. 范围
+
+本方案把 VectorEngine 音频生成能力从视觉小说结果页扩展到拼图与抓大鹅结果页：
+
+1. 拼图结果页新增 `音乐` Tab，支持通过 Suno 生成作品背景音乐。
+2. 抓大鹅结果页在 `素材配置 > 背景音乐` 中支持通过 Suno 生成作品背景音乐；旧一级 `音乐` Tab 已删除。
+3. 抓大鹅 `素材配置 > 物品` 支持为每个生成物体通过 Vidu 生成点击音效。
+4. 拼图运行态与抓大鹅运行态内置默认关卡音频配置：通用点击音效 `/audio/ui-click-soft.wav`、过关音效 `/audio/ui-level-clear.wav`、倒计时临界音效 `/audio/ui-countdown-warning.wav`。
+5. 拼图和抓大鹅草稿生成阶段会自动生成背景音乐并转存 OSS，结果页继续支持试听和重新生成。
+
+本轮不新增 SpacetimeDB 表，不修改表字段，不把供应商密钥下发到前端。
+
+## 2. 通用音频接口
+
+后端在既有视觉小说音频路由外新增通用创作音频路由：
+
+| 方法 | 路由 | 用途 |
+| --- | --- | --- |
+| `POST` | `/api/creation/audio/background-music` | 提交 Suno 背景音乐任务 |
+| `POST` | `/api/creation/audio/background-music/{task_id}/asset` | 查询并转存 Suno 音频资产 |
+| `POST` | `/api/creation/audio/sound-effect` | 提交 Vidu 音效任务 |
+| `POST` | `/api/creation/audio/sound-effect/{task_id}/asset` | 查询并转存 Vidu 音效资产 |
+
+通用转存请求由前端传入 `entityKind`、`entityId`、`slot`、`assetKind`、`profileId`。后端仍负责：
+
+1. 校验 VectorEngine 与 OSS 环境变量。
+2. 轮询供应商任务结果。
+3. 下载音频字节。
+4. 写入 OSS 私有对象。
+5. 确认 `asset_object` 并绑定 `asset_entity_binding`。
+6. 音频真正可下载并准备转存时，按 `taskId + assetKind + entityId + slot` 幂等扣除 `10` 光点；任务仍在处理中不扣费，转存或资产绑定失败自动退款。
+
+通用背景音乐提交允许 `prompt = ""`。拼图和抓大鹅草稿生成都按纯音乐处理：后端提交 Suno 时固定带 `make_instrumental = true`，只用 `title` 和 `tags` 约束作品气质，不把歌词或规则描述写入 prompt。视觉小说原路由保持兼容，内部继续复用同一套提交、轮询、转存逻辑。
+
+## 3. 数据落点
+
+### 3.1 拼图
+
+拼图作品没有独立作品级 metadata 字段。背景音乐随 `levels_json` 保存到首个 `PuzzleDraftLevel.backgroundMusic`：
+
+```json
+{
+  "levelId": "puzzle-level-1",
+  "backgroundMusic": {
+    "taskId": "suno-task",
+    "provider": "vector-engine-suno",
+    "assetObjectId": "assetobj_1",
+    "assetKind": "puzzle_background_music",
+    "audioSrc": "/generated-puzzle-assets/..."
+  }
+}
+```
+
+草稿生成阶段在生成首关作品题目后，使用作品题目作为 Suno `title`，`prompt` 为空，`tags` 使用轻快、拼图、循环、instrumental。生成失败只记录 warning，不阻断草稿进入结果页。运行态从 `PuzzleRuntimeLevelSnapshot.backgroundMusic.audioSrc` 读取该字段作为背景音乐源，游戏开始后自动循环播放；若字段为空，保持静默背景音乐兜底。
+
+### 3.2 抓大鹅
+
+抓大鹅作品级音频与物体点击音效复用 `generated_item_assets_json` 数组保存，不新增表字段：
+
+1. 作品背景音乐暂存到第一个 `Match3DGeneratedItemAsset.backgroundMusic`，表示当前 work profile 的作品级背景音乐。
+2. 单个物体点击音效保存到对应 `Match3DGeneratedItemAsset.clickSound`。
+
+这是一个兼容性折中：当前 Match3D work profile 没有 work-level metadata 字段，而 `generated_item_assets_json` 已经随作品详情、草稿架、运行态入口稳定传递。草稿生成阶段的文本计划在生成物品名称时同步生成 `backgroundMusic.title` 作为背景音乐名称，`backgroundMusic.prompt` 固定为空字符串，后端用该名称作为 Suno `title` 并生成纯音乐。后续若新增正式作品 metadata 表达，应迁移 `backgroundMusic` 到作品级字段。
+
+## 4. 前端交互
+
+结果页 UI 保持轻量：
+
+1. `音乐` Tab 只展示必要输入、生成按钮、状态与音频预览，不展示供应商规则说明。
+2. 生成完成后立即写回本地草稿状态，并触发既有保存链路或专用保存接口。
+3. 抓大鹅每个物体音效生成入口放在对应素材详情面板内，不在列表下方展开大段配置。
+4. 抓大鹅物体音效提示词允许在素材详情面板内编辑；背景音乐只允许在 `素材配置 > 背景音乐` 编辑曲名和风格，生成请求固定使用空 `prompt`。
+5. 背景音乐和物体音效生成期间都显示进度条，生成完成后展示 audio 控件试听。
+6. 背景音乐重新生成只要求曲名非空；重新生成继续按纯音乐提交，`prompt = ""`。
+
+### 4.1 运行态默认点击音效
+
+1. `src/services/runtimeAudioFeedback.ts` 提供通用关卡音频配置 `DEFAULT_RUNTIME_LEVEL_AUDIO_CONFIG`，内部缓存 `HTMLAudioElement`，失败时静默兜底，不阻塞玩法交互。
+2. 拼图点击、按压或拖拽拼块时播放默认通用点击音效，并继续保留既有触觉反馈。
+3. 抓大鹅点击物体时优先播放该物体绑定的 `clickSound.audioSrc`；若作品没有生成物体点击音效，则回退播放 `/audio/ui-click-soft.wav`。
+4. 拼图关卡 `currentLevel.status` 首次进入 `cleared` 时播放默认过关音效；抓大鹅 run `status` 首次进入 `won` 时播放默认过关音效。
+5. 拼图使用 `displayRemainingMs`，抓大鹅使用 `timeLeftMs`。当剩余时间进入默认阈值 `5_000ms` 后，每个自然秒桶最多播放一次倒计时音效，归零后停止。
+6. 默认关卡音效跟随现有 `musicVolume` 设置，不新增独立音量 UI，不在运行态界面增加说明文案。
+7. 拼图和抓大鹅运行态背景音乐同样跟随 `musicVolume`，读取 generated legacy path 时先换签，再交给隐藏 `<audio loop preload="auto">` 自动播放；浏览器拒绝自动播放时静默失败，不阻断游戏交互。
+
+## 5. 验收
+
+建议执行：
+
+```powershell
+npm run check:encoding
+npm run test -- src\components\puzzle-result\PuzzleResultView.test.tsx
+npm run test -- src\components\match3d-result\Match3DResultView.test.tsx
+npm run typecheck
+cargo test -p shared-contracts creation_audio --manifest-path server-rs\Cargo.toml
+cargo test -p shared-contracts puzzle --manifest-path server-rs\Cargo.toml
+cargo test -p shared-contracts match3d --manifest-path server-rs\Cargo.toml
+cargo test -p api-server vector_engine_audio_generation --manifest-path server-rs\Cargo.toml
+cargo test -p api-server match3d --manifest-path server-rs\Cargo.toml
+cargo check -p api-server --manifest-path server-rs\Cargo.toml
+```
+
+真实生成 smoke 需要本地私密环境配置 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 与 OSS 变量。后端改动后使用 `npm run api-server` 启动，并确认 `/healthz`。

docs/technical/PUZZLE_TEMPLATE_FORM_AND_GPT_IMAGE_SKILL_2026-05-03.md

@@ -33,11 +33,11 @@
    - 亮色主题下上传卡片必须使用白色或暖浅色卡面，不得显示整块黑色底。
    - 上传卡片固定为 1:1 正方形，避免拼图主画面在首屏出现非正方形预期。
    - 移动端表单主体不可依赖纵向拖动查看核心控件；玩法卡带、描述输入框和底部生成按钮占位固定后，上传卡片必须按剩余高度等比例缩放，仍保持 1:1。
-   - 上传卡片底部不再叠加文件名 bar；`点击上传拼图图片` 入口必须显示在拼图画面卡片内部。
+   - 上传卡片底部不再叠加文件名 bar；`上传图片/填写画面描述` 入口必须显示在拼图画面卡片内部。
    - 上传卡片上方固定展示 `拼图画面` 标题。
-   - 无图状态下，上传卡片内部、`点击上传拼图图片` 按钮上方展示 11px 级辅助提示 `若没有合适的图片可以通过填写画面描述生成画面`，提示用户可不上传图片、直接填写画面描述生成画面。
+   - 无图状态下，上传卡片内部只保留 `上传图片/填写画面描述` 轻量提示，不再展示额外规则说明文案。
-   - 上传成功后，`AI重绘` 开关显示在卡片左下角，右上角显示移除拼图图片图标按钮；移除必须先弹出二次确认。
+   - 历史素材按钮固定在上传卡片右上角；上传成功后，`AI重绘` 开关显示在卡片左下角，移除拼图图片图标按钮显示在卡片左上角；移除必须先弹出二次确认。
-   - 叠在上传卡片上的 `AI重绘`、移除图标和上传入口必须和卡面保持足够对比，避免浅色主题重映射后不可读。
+   - 叠在上传卡片上的历史按钮、`AI重绘`、移除图标和上传入口必须和卡面保持足够对比，避免浅色主题重映射后不可读。
 3. 画面描述输入框高度固定，移动端保持约 `6rem`，不随剩余屏幕高度变大或变小，避免把上传参考图和提交区挤出首屏。
 4. 创作 Tab 顶部玩法卡带的选中态只使用卡内暗色蒙版、细描边或内描边，不使用粉色外发光、外扩阴影或会从卡片边缘突出的高饱和边。
 5. 输入区保留：
@@ -93,7 +93,7 @@ size = 1024x1024
 拼图入口上传区左下角展示 `AI重绘` 开关，默认打开；未上传拼图图片前不显示开关，上传成功后才显示。上传成功后右上角展示移除图标按钮，点击后必须二次确认。
 
 1. `AI重绘=true`
-   - 上传区文案为 `点击上传拼图图片`，上传图作为生图参考图。
+   - 上传区文案为 `上传图片/填写画面描述`，上传图作为生图参考图。
    - 未上传图片时，输入框标题为 `画面描述`。
    - 已上传图片时，输入框标题为 `画面AI重绘要求（提示词）`。
    - 展示图片模型切换。

docs/technical/README.md

@@ -4,10 +4,15 @@
 
 ## 文档列表
 
+- [WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md](./WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md)：记录微信小程序 `web-view` 壳的最小接入范围、需要填写的 H5 业务域名、微信后台配置、`npm run check:wechat-miniprogram-auth` 可重复登录链路 smoke 和后续原生化边界。
+- [BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md](./BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md)：冻结“汪汪声浪大作战 / bark-battle”后端 DDD 技术方案，明确 `server-rs + Axum + SpacetimeDB` 分层边界、shared contracts、作品配置、runtime run、派生成绩、排行榜、`work_play_start` 埋点、migration/绑定生成策略，以及不保存原始麦克风音频的隐私与反作弊约束。
+- [BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md](./BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md)：冻结“汪汪声浪大作战 / bark-battle”2D 浏览器 runtime 技术方案，明确 Phaser + TypeScript + Vite 选型、纯 TS simulation 与 Phaser renderer/DOM HUD 边界、Web Audio 输入适配、移动端权限降级和后续测试验证命令。
 - [PUBLIC_WORK_DETAIL_NOT_FOUND_RECOVERY_2026-05-11.md](./PUBLIC_WORK_DETAIL_NOT_FOUND_RECOVERY_2026-05-11.md)：记录直接访问公开作品详情深链时作品不存在或已下架的回首页修复，避免关闭提示后停在 `work-detail` 空状态白屏。
+- [PLATFORM_MOBILE_RECOMMEND_CARD_SAFE_SWIPE_LAYOUT_2026-05-12.md](./PLATFORM_MOBILE_RECOMMEND_CARD_SAFE_SWIPE_LAYOUT_2026-05-12.md)：冻结移动端推荐页隐藏顶部品牌栏、扩大推荐卡片可用高度，以及只在底部作品信息区承接切换作品手势的布局口径。
+- [BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md](./BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md)：冻结寓教于乐 `宝贝识物` 模板创作发布线程的前端入口、契约、service、结果页、发布标签和后端 image-2 接口预留边界。
 - [CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md](./CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md)：冻结儿童动作识别互动玩法 Demo 固定热身关的开发落地规格，覆盖横屏展示、摄像头背景虚化、角色剪影、绿色圆环 2 秒保持、动作教学、当前会话内空间边界记录和后续关卡安全暂停规则。
 - [RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md](./RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md)：记录运行态输入设备抽象层，明确鼠标、触控、mocap 等设备统一归一为通用拖拽语义，玩法组件只负责解释目标和落点。
-- [RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md](./RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md)：记录 `server-rs` Cargo 依赖集中配置口径，第三方版本和 workspace 内部 crate path 统一维护在根 `server-rs/Cargo.toml`，成员 crate 只保留 feature/optional 差异。
+- [RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md](./RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md)：记录 `server-rs` Cargo 依赖集中配置口径，第三方版本和 workspace 内部 crate path 统一维护在根 `server-rs/Cargo.toml`，成员 crate 只保留 feature/optional 差异；同时冻结 `shared-contracts` 不得反向依赖 `platform-*`，避免 SpacetimeDB 模块发布时拉入 `wasm-bindgen`。
 - [DEV_RUST_STACK_PORT_CONFLICT_PRECHECK_2026-05-09.md](./DEV_RUST_STACK_PORT_CONFLICT_PRECHECK_2026-05-09.md)：记录本地完整 Rust 栈启动时 `api-server`、主站 Vite 和后台 Vite 端口占用的误判根因、脚本预检策略和 Windows 排障命令。
 - [VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md](./VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md)：记录 GPT-image-2 图片生成从 APIMart 迁移到 VectorEngine `gpt-image-2-all` 的接口、环境变量、尺寸映射、错误口径和验收命令。
 - [SPACETIMEDB_PUBLISH_SCCACHE_FALLBACK_2026-05-09.md](./SPACETIMEDB_PUBLISH_SCCACHE_FALLBACK_2026-05-09.md)：记录本地 `spacetime publish` 被 sccache wrapper 通信异常阻断时的根因、debug 构建参数口径和手动排障命令。
@@ -16,8 +21,8 @@
 - [RECOMMEND_RUNTIME_AUTH_FAILURE_ISOLATION_FIX_2026-05-09.md](./RECOMMEND_RUNTIME_AUTH_FAILURE_ISOLATION_FIX_2026-05-09.md)：记录平台推荐页自动加载作品、公开拼图作品完整运行态、平台 bootstrap 私有投影刷新和展示层图片换签的局部请求 `401` 不应扩散成全局登出的修复，覆盖 `authImpact: local` 请求策略、推荐页 embedded 运行态启动、拼图开局/排行榜/下一关和回归测试。
 - [AUTH_GATE_LOGIN_RACE_GUARD_FIX_2026-05-09.md](./AUTH_GATE_LOGIN_RACE_GUARD_FIX_2026-05-09.md)：记录 `AuthGate` 登录成功后又被旧 hydrate 覆盖回未登录态的竞态根因、版本号保护修复与回归测试。
 - [HYPER3D_RODIN_GEN2_MODEL_GENERATION_2026-05-08.md](./HYPER3D_RODIN_GEN2_MODEL_GENERATION_2026-05-08.md)：记录 Hyper3D Rodin Gen-2 文生 3D 模型、图生 3D 模型、状态查询和下载列表的后端代理、环境变量、请求约束与验收边界。
-- [MATCH3D_RODIN_ASSET_TAB_2026-05-10.md](./MATCH3D_RODIN_ASSET_TAB_2026-05-10.md)：记录抓大鹅结果页多 Tab 改造与 Rodin 3D 素材列表/详情页的前端接入边界，明确首版只复用 Hyper3D 后端代理，不新增表或正式资产写入。
+- [MATCH3D_RODIN_ASSET_TAB_2026-05-10.md](./MATCH3D_RODIN_ASSET_TAB_2026-05-10.md)：历史记录抓大鹅 Rodin 3D 素材列表/详情页的早期接入边界；当前新草稿不再调用 Rodin 或生成 GLB。
-- [MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md](./MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md)：冻结抓大鹅草稿生成过程页、3 件物品名称生成、VectorEngine 1:1 素材图、n*n 切图、并行 Rodin 图生 3D 与 OSS 回填草稿页的端到端边界。
+- [MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md](./MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md)：冻结抓大鹅草稿生成过程页、按题材生成 UI 背景提示词、VectorEngine 2D 五视角素材、UI 背景图、背景音乐和 OSS 回填草稿页的端到端边界。
 - [VOLCENGINE_SPEECH_STREAMING_INTEGRATION_2026-05-08.md](./VOLCENGINE_SPEECH_STREAMING_INTEGRATION_2026-05-08.md)：记录火山引擎大模型 ASR 双向流式、TTS WebSocket 双向流式和 TTS HTTP SSE 单向流式的后端代理、环境变量、协议帧和验收边界。
 - [VECTOR_ENGINE_AUDIO_GENERATION_SUNO_VIDU_2026-05-08.md](./VECTOR_ENGINE_AUDIO_GENERATION_SUNO_VIDU_2026-05-08.md)：记录视觉小说结果页接入 VectorEngine Suno 文生背景音乐与 Vidu 文生音效的接口、环境变量、后端路由、OSS 资产回写和前端弹层交互边界。
 - [PROFILE_FEEDBACK_BACKEND_INTEGRATION_2026-05-08.md](./PROFILE_FEEDBACK_BACKEND_INTEGRATION_2026-05-08.md)：冻结“我的”页签帮助与反馈入口的后端接入方案，覆盖 `POST /api/profile/feedback`、`profile_feedback_submission`、凭证图片 Data URL 校验和前端预览/提交边界。
@@ -170,7 +175,7 @@
 - [AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md](./AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md)：`/api/auth/login-options` 首版设计，冻结登录方式列表 contract、配置开关来源与返回顺序。
 - [AUTH_ME_QUERY_DESIGN_2026-04-21.md](./AUTH_ME_QUERY_DESIGN_2026-04-21.md)：`/api/auth/me` 首版查询设计，冻结 Bearer JWT 衔接、`user + availableLoginMethods` 返回 contract，以及用户不存在时的 `401` 语义。
 - [AUTH_LOGOUT_ALL_DESIGN_2026-04-21.md](./AUTH_LOGOUT_ALL_DESIGN_2026-04-21.md)：`/api/auth/logout-all` 全端登出设计，冻结全部 refresh session 吊销、`token_version` 递增、清 cookie 语义与 Rust 首版接口边界。
-- [AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md](./AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md)：`/api/auth/sessions` 会话列表设计，冻结当前设备识别、多端登录字段映射、`clientLabel` 兼容策略与 Rust 首版接口边界。
+- [AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md](./AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md)：`/api/auth/sessions` 会话列表设计，冻结当前设备识别、多端登录字段映射、同设备同 IP 会话组合并、`clientLabel` 兼容策略与 Rust 接口边界。
 - [PHONE_AUTH_AXUM_MINIMAL_FLOW_DESIGN_2026-04-21.md](./PHONE_AUTH_AXUM_MINIMAL_FLOW_DESIGN_2026-04-21.md)：手机号验证码登录最小闭环设计，冻结 mock 验证码规则、`send-code` / `phone/login` contract 与 crate 边界。
 - [PHONE_AUTH_AXUM_RATE_LIMIT_AND_FAILURE_DESIGN_2026-04-21.md](./PHONE_AUTH_AXUM_RATE_LIMIT_AND_FAILURE_DESIGN_2026-04-21.md)：手机号验证码冷却与失败次数限制设计，冻结同手机号同场景发送冷却、错误次数耗尽、`429` 与 `Retry-After` contract。
 - [PHONE_AUTH_AXUM_REAL_SMS_PROVIDER_DESIGN_2026-04-22.md](./PHONE_AUTH_AXUM_REAL_SMS_PROVIDER_DESIGN_2026-04-22.md)：冻结 Rust `api-server + module-auth + platform-auth` 接入真实阿里云短信 provider 的 crate 边界、发送与校验职责、配置项和错误语义。
@@ -202,7 +207,7 @@
 - [SPACETIMEDB_SMS_AUTH_EVENT_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_SMS_AUTH_EVENT_TABLE_DESIGN_2026-04-21.md)：`M2` 第六张短信鉴权统计表 `sms_auth_event` 的事件范围、统计口径、索引与和风控/审计表的协作边界。
 - [SPACETIMEDB_AUTH_RISK_BLOCK_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_RISK_BLOCK_TABLE_DESIGN_2026-04-21.md)：`M2` 第五张风控状态表 `auth_risk_block` 的作用域、活跃态、刷新/解除规则与读取派生约束。
 - [SPACETIMEDB_AUTH_AUDIT_LOG_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_AUDIT_LOG_TABLE_DESIGN_2026-04-21.md)：`M2` 第四张鉴权审计表 `auth_audit_log` 的事件范围、追加写规则、索引与对外 DTO 派生约束。
-- [SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md)：`M2` 第三张会话表 `refresh_session` 的 cookie/hash 边界、轮换与吊销语义、索引与迁移规则。
+- [SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md)：`M2` 第三张会话表 `refresh_session` 的 cookie/hash 边界、轮换、logout fallback、指定会话吊销语义、索引与迁移规则。
 - [SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md)：`M2` 第二张身份表 `auth_identity` 的 provider 范围、唯一约束、手机号/微信身份写入规则与迁移策略。
 - [SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md)：`M2` 第一张身份主表 `user_account` 的职责边界、字段、唯一约束、状态迁移、旧 `users` 映射与落地约束。
 - [SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](./SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)：基于旧 Node 后端能力清单，设计用 `SpacetimeDB + Axum + 阿里云 OSS` 重写后端的目标架构、模块映射、数据分层、迁移顺序与验收标准。

docs/technical/RUST_API_SERVER_ROUTE_INDEX_2026-04-22.md

@@ -1,6 +1,6 @@
 # Rust API Server 路由索引（2026-04-23）
 
-更新时间：`2026-05-01`
+更新时间：`2026-05-13`
 
 > 2026-04-29 补充：本文件保留为迁移期路由快照。DDD G1 后续并行工作的契约冻结口径以 [`SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md`](./SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md) 为准，尤其是新增的 Big Fish、Puzzle、profile、runtime chat、story facade 和兼容路由删除计划。
 >
@@ -20,7 +20,7 @@
 2. 内部鉴权调试接口：`2` 条。
 3. AI task 接口：`9` 条。
 4. assets / OSS 接口：`15` 条。
-5. auth 接口：`12` 条。
+5. auth 接口：`13` 条。
 6. custom world / agent 接口：`23` 条。
 7. match3d creation / runtime 接口：`14` 条。
 8. llm proxy 接口：`1` 条。
@@ -84,13 +84,14 @@
 3. `POST /api/auth/logout`
 4. `POST /api/auth/logout-all`
 5. `GET /api/auth/sessions`
-6. `POST /api/auth/refresh`
+6. `POST /api/auth/sessions/{session_id}/revoke`
-7. `POST /api/auth/phone/send-code`
+7. `POST /api/auth/refresh`
-8. `POST /api/auth/phone/login`
+8. `POST /api/auth/phone/send-code`
-9. `GET /api/auth/wechat/start`
+9. `POST /api/auth/phone/login`
-10. `GET /api/auth/wechat/callback`
+10. `GET /api/auth/wechat/start`
-11. `POST /api/auth/wechat/bind-phone`
+11. `GET /api/auth/wechat/callback`
-12. `POST /api/auth/entry`
+12. `POST /api/auth/wechat/bind-phone`
+13. `POST /api/auth/entry`
 
 ### 3.6 Custom World / Agent
 

docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md

@@ -16,7 +16,9 @@
 4. 成员 crate 只保留自身需要表达的差异，例如 `features`、`optional = true` 或 target-specific dependency。
 5. 需要关闭 default features 的依赖，应优先在 workspace 根依赖中声明；成员 crate 不再重复覆盖同一项。
 6. `module-assets` 这类有默认服务端 feature 的领域 crate，在 workspace 根内按 `default-features = false` 维护；需要服务端 OSS/HTTP 能力的 adapter crate 显式启用 `features = ["server-service"]`。
-7. 面向 SpacetimeDB WASM 的依赖链不得隐式启用原生 HTTP / OSS / Web 平台依赖；例如 `shared-contracts` 的 `assets` 模块通过 `oss-contracts` feature 暴露给 `api-server`，`spacetime-module` 路径只消费关闭默认 feature 后的纯 DTO 子集。
+7. `shared-contracts` 只能承载前后端公开 DTO 和轻量枚举，禁止直接依赖 `platform-*` 服务实现 crate；需要把平台实现响应转换为公开 DTO 时，转换函数放在 `api-server` 等 adapter 层。
+8. 面向 SpacetimeDB WASM 的依赖链不得隐式启用原生 HTTP / OSS / Web 平台依赖；例如 `shared-contracts` 的 `assets` 模块通过不依赖 `platform-oss` 的 `oss-contracts` feature 暴露给 `api-server`，`spacetime-module` 路径只消费关闭默认 feature 后的纯 DTO 子集。
+9. `spacetime-module` 的传递依赖不能包含 `reqwest`、`web-sys`、`js-sys`、`wasm-bindgen` 等 Web/HTTP 客户端链路；发布前可用 `cargo tree -i wasm-bindgen --manifest-path server-rs/Cargo.toml -p spacetime-module --target wasm32-unknown-unknown` 排查。
 
 ## 3. 本次收敛范围
 
@@ -57,14 +59,33 @@ npm.cmd run check:encoding -- docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDA
 
 ## 6. SpacetimeDB WASM 依赖边界
 
+2026-05-11 本地重置 SpacetimeDB 并重新发布 `xushi-p4wfr` 时，`spacetime publish` 在 Rust 编译成功后报 `wasm-bindgen detected`。排查命令显示链路为：
+
+```text
+spacetime-module -> module-runtime -> shared-contracts -> platform-oss -> reqwest -> wasm-bindgen
+```
+
+根因是 `shared-contracts` 为了复用 OSS 直传/读签名返回类型，直接依赖了 `platform-oss`。这违反 DDD 分层边界：契约 crate 不能依赖平台副作用实现，否则所有引用契约的纯领域和 SpacetimeDB 模块都会被迫拉入 HTTP client。
+
 `spacetime publish` 会构建 `spacetime-module` 的 `wasm32-unknown-unknown` 目标。这个目标不能包含 `wasm-bindgen`，也不应通过 DTO crate 间接拉入 `reqwest`、`web-sys` 或浏览器 WebAssembly 平台依赖。
 
+修正口径：
+
+1. `shared-contracts::assets` 定义独立的公开 DTO 和 `DirectUploadObjectAccess` 轻量枚举。
+2. `platform-oss` 保持 OSS 签名、读写请求和错误分类实现，不被契约层引用。
+3. `api-server::assets` 负责把 `platform_oss::OssPostObjectResponse` / `OssSignedGetObjectUrlResponse` 转成 `shared-contracts` DTO。
+4. 后续新增外部平台能力时，重复使用这个边界：平台 crate 不得被 `shared-contracts`、`module-*` 或 `spacetime-module` 反向依赖。
+
 已验证的排查命令：
 
 ```powershell
+cargo tree -i wasm-bindgen --manifest-path server-rs\Cargo.toml -p spacetime-module --target wasm32-unknown-unknown
 cargo tree -i wasm-bindgen --manifest-path server-rs\crates\spacetime-module\Cargo.toml --target wasm32-unknown-unknown
 cargo tree --manifest-path server-rs\crates\spacetime-module\Cargo.toml --target wasm32-unknown-unknown | Select-String -Pattern 'wasm-bindgen|platform-oss|reqwest'
 cargo check -p spacetime-module --manifest-path server-rs\Cargo.toml --target wasm32-unknown-unknown
+cargo check -p shared-contracts --manifest-path server-rs\Cargo.toml
+cargo check -p api-server --manifest-path server-rs\Cargo.toml
+spacetime publish xushi-p4wfr --server local --module-path server-rs\crates\spacetime-module --build-options="--debug" -c=on-conflict --yes
 ```
 
-若反向树显示 `reqwest -> platform-oss -> shared-contracts -> module-* -> spacetime-module`，优先检查新增的 `shared-contracts` 或领域 crate 依赖是否忘记关闭默认 feature。原生 `api-server` 需要资产上传契约时，应在自身 `Cargo.toml` 显式启用 `shared-contracts` 的 `oss-contracts` feature，而不是让 workspace 根依赖默认启用。
+若反向树显示 `reqwest -> platform-oss -> shared-contracts -> module-* -> spacetime-module`，优先检查新增的 `shared-contracts` 或领域 crate 依赖是否忘记关闭默认 feature，或 `shared-contracts` feature 是否错误依赖了平台实现 crate。原生 `api-server` 需要资产上传契约时，应在自身 `Cargo.toml` 显式启用 `shared-contracts` 的 `oss-contracts` feature，而不是让 workspace 根依赖默认启用。

docs/technical/SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md

@@ -31,7 +31,7 @@ G1 单 owner 文件范围：
 | 管理兑换码 | `POST /admin/api/profile/redeem-codes`、`POST /admin/api/profile/redeem-codes/disable` | 收敛 | 继续走 admin 路由，DTO 归入 profile/runtime 管理命令组 | WP-RT、WP-API |
 | 内部鉴权调试 | `GET /_internal/auth/claims`、`GET /_internal/auth/refresh-cookie` | 删除 | 只允许本地诊断脚本或 admin debug 能力使用，不作为前端契约 | WP-DEL |
 | 鉴权公开查询 | `GET /api/auth/login-options`、`GET /api/auth/public-users/by-code/{code}`、`GET /api/auth/public-users/by-id/{user_id}` | 保留 | `AuthLoginOptionsResponse`、`PublicUserSearchResponse` | WP-A |
-| 鉴权会话 | `GET /api/auth/me`、`GET /api/auth/sessions`、`POST /api/auth/refresh`、`POST /api/auth/logout`、`POST /api/auth/logout-all` | 保留 | `AuthMeResponse`、`AuthSessionsResponse`、`RefreshSessionResponse`、`LogoutResponse`、`LogoutAllResponse` | WP-A |
+| 鉴权会话 | `GET /api/auth/me`、`GET /api/auth/sessions`、`POST /api/auth/sessions/{session_id}/revoke`、`POST /api/auth/refresh`、`POST /api/auth/logout`、`POST /api/auth/logout-all` | 保留 | `AuthMeResponse`、`AuthSessionsResponse`、`RevokeAuthSessionResponse`、`RefreshSessionResponse`、`LogoutResponse`、`LogoutAllResponse` | WP-A |
 | 鉴权登录 | `POST /api/auth/phone/send-code`、`POST /api/auth/phone/login`、`GET /api/auth/wechat/start`、`GET /api/auth/wechat/callback`、`POST /api/auth/wechat/bind-phone`、`POST /api/auth/entry`、`POST /api/auth/password/change`、`POST /api/auth/password/reset` | 保留 | TS 命名统一使用 `Auth*` 前缀，Rust 命名维持领域语义 | WP-A |
 | 旧本地生成资产代理 | `GET /generated-character-drafts/{*path}`、`/generated-characters/{*path}`、`/generated-animations/{*path}`、`/generated-big-fish-assets/{*path}`、`/generated-puzzle-assets/{*path}`、`/generated-custom-world-scenes/{*path}`、`/generated-custom-world-covers/{*path}`、`/generated-qwen-sprites/{*path}` | 已删除 | 正式读取统一走 `GET /api/assets/read-url` 或 asset object projection；`/generated-*` 仅允许作为 legacyPublicPath/object key 标识，不再作为可裸读路由 | WP-AS、WP-FE、WP-DEL |
 | LLM 代理 | `POST /api/llm/chat/completions` | 收敛 | 仅作为平台能力代理；玩法 prompt 不允许由前端直接传入 | WP-PF、WP-API |
@@ -59,7 +59,7 @@ G1 单 owner 文件范围：
 | --- | --- |
 | `shared-contracts/src/api.rs` | `ApiResponseMeta`、`ApiErrorPayload`、`ApiSuccessEnvelope<T>`、`ApiErrorEnvelope` |
 | `shared-contracts/src/admin.rs` | `AdminLoginRequest/Response`、`AdminSessionPayload`、`AdminMeResponse`、`AdminOverviewResponse`、`AdminDebugHttpRequest/Response` |
-| `shared-contracts/src/auth.rs` | `AuthLoginOptionsResponse`、`AuthUserPayload`、`PublicUserSummaryPayload`、`PublicUserSearchResponse`、`PasswordEntry*`、`PasswordChange*`、`PasswordReset*`、`AuthMeResponse`、`AuthSessionsResponse`、`RefreshSessionResponse`、`Logout*`、`Phone*`、`Wechat*` |
+| `shared-contracts/src/auth.rs` | `AuthLoginOptionsResponse`、`AuthUserPayload`、`PublicUserSummaryPayload`、`PublicUserSearchResponse`、`PasswordEntry*`、`PasswordChange*`、`PasswordReset*`、`AuthMeResponse`、`AuthSessionsResponse`、`RevokeAuthSessionResponse`、`RefreshSessionResponse`、`Logout*`、`Phone*`、`Wechat*` |
 | `shared-contracts/src/ai.rs` | `CreateAiTaskRequest`、`AppendAiTextChunkRequest`、`CompleteAiStageRequest`、`AttachAiResultReferenceRequest`、`FailAiTaskRequest`、`AiTask*Payload`、`AiTaskMutationResponse`、`AiTaskAcceptedResponse` |
 | `shared-contracts/src/assets.rs` | Direct upload、read url、asset object、asset binding、asset history、character visual/animation、workflow cache、role asset workflow 相关 DTO |
 | `shared-contracts/src/creation_agent_document_input.rs` | `ParseCreationAgentDocumentInputRequest/Response`、`CreationAgentDocumentInputPayload` |

docs/technical/SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md

@@ -115,6 +115,8 @@
 1. 从 cookie 读出原始 refresh token
 2. 计算 hash
 3. 与 `refresh_session.refresh_token_hash` 比较
+4. 若 refresh cookie 缺失或不可用，再使用 Bearer access token claims 中的 `sid` 与 `refresh_session.session_id` 比较
+5. 会话列表按“同设备 + 同 IP”聚合时，组内任一 session 命中当前 hash 或当前 `sid`，整组都视为当前设备组
 
 ## 5. 表访问级别
 
@@ -228,9 +230,10 @@
 写入规则：
 
 1. 按当前 cookie 找 session
-2. 写 `revoked_at = now`
+2. 如果 refresh cookie 缺失，则回退用 Bearer access token claims 中的 `sid` 找当前 session
-3. 写 `revoked_reason_code = logout`
+3. 写 `revoked_at = now`
-4. 同时提升 `user_account.token_version`
+4. 写 `revoked_reason_code = logout`
+5. 同时提升 `user_account.token_version`
 
 ### 8.4 吊销全部会话
 
@@ -248,7 +251,7 @@
 
 触发点：
 
-1. `POST /api/auth/sessions/:sessionId/revoke`
+1. `POST /api/auth/sessions/{sessionId}/revoke`
 
 写入规则：
 
@@ -257,6 +260,13 @@
 3. 只改目标 `refresh_session`
 4. `revoked_reason_code = session_revoke`
 5. 不提升 `token_version`
+6. 撤销后必须同步 auth store 到 SpacetimeDB
+
+读取约束：
+
+1. Bearer JWT 中的 `sid` 必须对应 active `refresh_session`
+2. 被该接口撤销的设备即使 access token 未过期，后续请求也必须立刻返回未授权
+3. 该接口不承担当前设备退出语义；当前设备退出固定走 `/api/auth/logout`
 
 ### 8.6 账号被禁用或并入
 
@@ -315,13 +325,18 @@
 
 1. `clientLabel` 当前阶段继续兼容保留，但固定与 `deviceDisplayName` 对齐。
 2. `ipMasked`、`isCurrent` 继续在 Axum 侧派生。
+3. 同设备同 IP 的 active sessions 由 Axum 聚合后返回一条记录。
+4. `sessionId` 是代表 ID；当前组代表 ID 使用当前 `sid` 对应 session。
+5. `sessionIds` 返回组内全部 active session ID，`sessionCount` 返回组内数量。
+6. 聚合组时间语义：`createdAt` 取最早创建时间，`lastSeenAt` 与 `expiresAt` 取最新值。
 
 ### 10.3 `POST /api/auth/logout`
 
 依赖：
 
 1. 当前 cookie 命中的 `refresh_session`
-2. `user_account.token_version`
+2. cookie 缺失时 Bearer `sid` 命中的 `refresh_session`
+3. `user_account.token_version`
 
 ### 10.4 `POST /api/auth/logout-all`
 
@@ -330,6 +345,22 @@
 1. 当前 `user_id` 下全部活跃 `refresh_session`
 2. `user_account.token_version`
 
+### 10.5 `POST /api/auth/sessions/{sessionId}/revoke`
+
+依赖：
+
+1. 当前 Bearer JWT 的 `user_id`
+2. 当前 Bearer JWT 的 `sid`
+3. 目标 `refresh_session.session_id`
+4. `refresh_session.revoked_at`
+5. `refresh_session.expires_at`
+
+固定行为：
+
+1. 目标 session 必须属于当前用户
+2. 目标 session 不能是当前 `sid`
+3. 成功只撤销目标 session，不递增 `token_version`
+
 ## 11. 与当前 Node `user_sessions` 的映射关系
 
 | Node `user_sessions` 列 | 新 `refresh_session` 字段 | 迁移规则 |

docs/technical/SPACETIMEDB_TABLE_CATALOG.md

@@ -72,8 +72,8 @@ SELECT * FROM auth_store_snapshot WHERE snapshot_id = 'default';
 ### `user_account`
 
 - 作用：用户账号主表，保存用户名、公开百梦号、手机号掩码、登录方式、密码登录开关、token 版本和默认不前端展示的运营标签。
-- 结构：`user_id PK: String`, `public_user_code: String`, `username: String`, `display_name: String`, `avatar_url: Option<String>`, `phone_number_masked: Option<String>`, `phone_number_e164: Option<String>`, `login_method: String`, `binding_status: String`, `wechat_bound: bool`, `password_hash: String`, `password_login_enabled: bool`, `token_version: u64`, `user_tags: Vec<String>`。
+- 结构：`user_id PK: String`, `public_user_code: String`, `username: String`, `display_name: String`, `avatar_url: Option<String>`, `phone_number_masked: Option<String>`, `phone_number_e164: Option<String>`, `login_method: String`, `binding_status: String`, `wechat_bound: bool`, `password_hash: String`, `password_login_enabled: bool`, `token_version: u64`, `user_tags: Option<Vec<String>>`。
-- 说明：`user_tags` 默认空数组，只允许后端白名单投影到特定业务接口；不得在登录态、个人资料等通用前端响应中直接暴露。
+- 说明：`user_tags` 数据库默认 `None`，业务读取时按空数组归一化；只允许后端白名单投影到特定业务接口，不得在登录态、个人资料等通用前端响应中直接暴露。
 - 索引：`username`, `public_user_code`。
 
 ```sql
@@ -256,11 +256,11 @@ SELECT * FROM profile_redeem_code_usage WHERE user_id = '<user_id>';
 
 ### `profile_invite_code`
 
-- 作用：用户邀请中心的邀请码主表，也承载后台运营预置邀请码和使用后授予账号的运营标签。
+- 作用：用户邀请中心的邀请码主表，也承载后台运营预置邀请码和使用后授予账号的运营标签配置。
-- 结构：`user_id PK: String`, `invite_code: String`, `metadata_json: String`, `created_at: Timestamp`, `updated_at: Timestamp`, `starts_at: Option<Timestamp>`, `expires_at: Option<Timestamp>`, `granted_user_tags: Vec<String>`。
+- 结构：`user_id PK: String`, `invite_code: String`, `metadata_json: String`, `created_at: Timestamp`, `updated_at: Timestamp`, `starts_at: Option<Timestamp>`, `expires_at: Option<Timestamp>`。
 - 索引：主键 `user_id`，唯一索引 `invite_code`。
 - 后台读取：`GET /admin/api/profile/invite-codes` 只返回 `user_id` 以 `admin:` 开头的后台预置码；普通用户自己的邀请码不得进入后台运营列表。
-- 说明：`granted_user_tags` 默认空数组；用户注册填写该邀请码后合并进 `user_account.user_tags`，不回改历史用户。
+- 说明：使用该邀请码后授予的标签存放在 `metadata_json.userTags`，服务端兼容读取 `metadata_json.user_tags`；用户注册填写该邀请码后合并进 `user_account.user_tags`，不回改历史用户。
 
 ```sql
 SELECT * FROM profile_invite_code WHERE user_id = '<user_id>';
@@ -665,7 +665,7 @@ SELECT * FROM match3d_agent_message WHERE session_id = '<session_id>' ORDER BY c
 
 - 作用：抓大鹅 Match3D 作品主表，保存作品基础信息、配置、发布状态、游玩次数和草稿生成出的独立物品素材引用。
 - 结构：`profile_id PK: String`, `owner_user_id: String`, `source_session_id: String`, `author_display_name: String`, `game_name: String`, `theme_text: String`, `summary_text: String`, `tags_json: String`, `cover_image_src: String`, `cover_asset_id: String`, `clear_count: u32`, `difficulty: u32`, `config_json: String`, `publication_status: String`, `play_count: u32`, `updated_at: Timestamp`, `published_at: Option<Timestamp>`, `generated_item_assets_json: Option<String>`。
-- 说明：`generated_item_assets_json` 保存 `Match3DGeneratedItemAsset` 数组 JSON，用于草稿页退出后从作品架重进时恢复 `3D素材` Tab 中的切割图片预览；基础信息自动保存和发布必须保留该字段。
+- 说明：`generated_item_assets_json` 保存 `Match3DGeneratedItemAsset` 数组 JSON，用于草稿页退出后从作品架重进时恢复 `3D素材` Tab 中的切割图片和 GLB 模型预览；运行态也通过该字段拿到 `modelSrc` / `modelObjectKey` 并优先渲染生成模型。基础信息自动保存和发布必须保留该字段。
 - 索引：`owner_user_id`, `publication_status`。
 
 ```sql

docs/technical/USER_TAG_INVITE_AND_PUZZLE_LEADERBOARD_2026-05-10.md

@@ -1,13 +1,13 @@
 # 用户标签、邀请码授予与拼图榜单展示方案
 
-更新时间：`2026-05-10`
+更新时间：`2026-05-11`
 
 ## 1. 目标
 
 本次新增用户标签系统的最小闭环：
 
-1. `user_account` 增加账号标签字段，默认空。
+1. `user_account` 增加账号标签字段，数据库默认空，业务读取时按空数组处理。
-2. 后台预置邀请码可配置授予标签。
+2. 后台预置邀请码可通过原有 `metadata` 字段配置授予标签。
 3. 用户填写带标签的邀请码后，把标签合并到自己的账号。
 4. 标签默认不在前端资料页、邀请中心或通用接口展示。
 5. 拼图排行榜仅对白名单标签做展示，首版只展示 `北科`。
@@ -16,19 +16,21 @@
 
 ### `user_account.user_tags`
 
-- 类型：`Vec<String>`。
+- 类型：`Option<Vec<String>>`。
-- 默认：空数组。
+- 默认：`None`，业务层读取时统一按空数组处理。
 - 语义：账号级运营标签，属于后台与服务端投影数据，不作为普通前端个人资料字段。
 - 写入：首版只由邀请码兑换链路合并写入。
-- 迁移：旧迁移包和旧数据库按空数组兼容。
+- 迁移：旧迁移包和旧数据库按 `null` 兼容，再由业务层归一化为空数组。
 
-### `profile_invite_code.granted_user_tags`
+### `profile_invite_code.metadata_json.userTags`
 
-- 类型：`Vec<String>`。
+- 类型：`metadata_json` 对象里的 `userTags: string[]`。
-- 默认：空数组。
+- 默认：字段缺失或空数组时不授予标签。
 - 语义：使用该邀请码后授予被邀请账号的标签列表。
 - 范围：后台运营预置码和普通用户个人邀请码都可存字段，但后台表单首版只允许管理员配置预置码。
-- 迁移：旧邀请码按空数组兼容。
+- 存储：不再新增或使用独立的邀请码标签列；后台保存时把用户标签写回 `metadata.userTags`。
+- 解析：服务端优先读取 `metadata_json.userTags`，并兼容解析 `metadata_json.user_tags`。
+- 迁移：旧邀请码缺少 `metadata_json` 时按 `{}` 兼容；旧迁移包里已废弃的独立字段会在导入时丢弃。
 
 ## 3. 标签归一化
 
@@ -45,35 +47,38 @@
 
 1. 写入 `profile_referral_relation`。
 2. 发放原有双方奖励。
-3. 读取 `profile_invite_code.granted_user_tags`。
+3. 从 `profile_invite_code.metadata_json` 解析 `userTags` / `user_tags`。
 4. 将这些标签合并进 `user_account.user_tags`。
 
-管理员更新邀请码时，`grantedUserTags` 代表覆盖该邀请码之后授予的标签集合；空数组代表不授予标签。更新邀请码不会回溯修改已经使用过该邀请码的账号。
+管理员更新邀请码时，后台表单里的用户标签会覆盖写入 `metadata.userTags`；空数组代表不授予标签。更新邀请码不会回溯修改已经使用过该邀请码的账号。
 
 ## 5. API 契约
 
-后台邀请码 upsert 请求增加：
+后台邀请码 upsert 请求继续只提交 `metadata`，标签写在 `metadata.userTags` 中：
 
 ```json
 {
   "inviteCode": "BEIKE2026",
-  "grantedUserTags": ["北科"],
+  "metadata": {
-  "metadata": {},
+    "userTags": ["北科"]
+  },
   "startsAt": null,
   "expiresAt": null
 }
 ```
 
-后台邀请码列表和 upsert 返回增加同名字段：
+后台邀请码列表和 upsert 返回继续回传 `metadata`：
 
 ```json
 {
   "inviteCode": "BEIKE2026",
-  "grantedUserTags": ["北科"]
+  "metadata": {
+    "userTags": ["北科"]
+  }
 }
 ```
 
-用户侧邀请中心、账号资料、登录返回和普通 profile 接口不返回 `userTags`。
+后台表单展示时从 `metadata.userTags` 回显用户标签；用户侧邀请中心、账号资料、登录返回和普通 profile 接口不返回 `userTags`。
 
 ## 6. 拼图排行榜展示
 
@@ -94,9 +99,10 @@
 
 ## 7. 验收
 
-1. 新账号 `user_account.user_tags` 默认为空。
+1. 新账号 `user_account.user_tags` 数据库默认为 `None`，业务读取为空数组。
-2. 后台创建邀请码时可填写 `北科`，列表和结果面板可回显。
+2. 后台创建邀请码时可填写 `北科`，请求和返回的 `metadata.userTags` 可回显。
 3. 用户填写该邀请码后，账号表 `user_tags` 包含 `北科`。
 4. 不带标签的邀请码不改变账号标签。
 5. 拼图排行榜中带 `北科` 的用户昵称下方显示 `北科`，其它标签不显示。
-6. 执行 `npm run check:encoding`、`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`，并按影响范围执行后台 typecheck / 拼图前端测试。
+6. 生成 SpacetimeDB bindings 后，不再出现独立的邀请码标签字段。
+7. 执行 `npm run check:encoding`、`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`，并按影响范围执行后台 typecheck / 拼图前端测试。

docs/technical/WECHAT_LOGIN_AXUM_IMPLEMENTATION_DESIGN_2026-04-21.md

@@ -92,6 +92,25 @@
 2. 若是并入已有手机号正式账号，则返回目标正式账号快照，当前实现会保持其账号主登录方式，例如 `loginMethod = phone`。
 3. 但 access token 中的 `provider` 仍按**本次登录来源**签发，不依赖账号主登录方式推断，因此微信绑定后的当前会话仍会签发 `provider = wechat`。
 
+### 3.4 `POST /api/auth/wechat/miniprogram-login`
+
+职责固定为：
+
+1. 接收微信小程序原生壳通过 `wx.login` 拿到的 `code`。
+2. 在 `Axum` 内调用微信 `jscode2session`，兑换 `openid/unionid`。
+3. 复用 `resolve_login` 处理 `unionid/openid -> user_id` 的查找、补写和待绑定账号创建。
+4. 签发本系统 access token，并创建 refresh session。
+5. 返回：
+   - `token`
+   - `bindingStatus`
+   - `user`
+
+关键约束：
+
+1. 小程序壳不能把裸 `openid` 直接拼给 H5 做登录。
+2. H5 仍只消费本系统 `auth_token`，小程序壳只是把这枚 token 放入既有 hash 回调格式。
+3. 小程序请求必须补传 `x-client-type=mini_program` 与 `x-client-runtime=wechat_mini_program`，用于 refresh session 记录来源。
+
 ## 4. 当前最小实现策略
 
 当前阶段为了先打通 Rust 后端闭环，采用以下最小实现：
@@ -125,6 +144,7 @@
 4. `GET /api/auth/wechat/start`
 5. `GET /api/auth/wechat/callback`
 6. `POST /api/auth/wechat/bind-phone`
+7. `POST /api/auth/wechat/miniprogram-login`
 
 ## 6. 环境变量
 
@@ -139,11 +159,14 @@
 7. `WECHAT_AUTHORIZE_ENDPOINT`
 8. `WECHAT_ACCESS_TOKEN_ENDPOINT`
 9. `WECHAT_USER_INFO_ENDPOINT`
-10. `WECHAT_STATE_TTL_MINUTES`
+10. `WECHAT_JS_CODE_SESSION_ENDPOINT`
-11. `WECHAT_MOCK_USER_ID`
+11. `WECHAT_MINI_PROGRAM_APP_ID`
-12. `WECHAT_MOCK_UNION_ID`
+12. `WECHAT_MINI_PROGRAM_APP_SECRET`
-13. `WECHAT_MOCK_DISPLAY_NAME`
+13. `WECHAT_STATE_TTL_MINUTES`
-14. `WECHAT_MOCK_AVATAR_URL`
+14. `WECHAT_MOCK_USER_ID`
+15. `WECHAT_MOCK_UNION_ID`
+16. `WECHAT_MOCK_DISPLAY_NAME`
+17. `WECHAT_MOCK_AVATAR_URL`
 
 ## 7. 与后续 SpacetimeDB 的衔接要求
 

docs/technical/WECHAT_LOGIN_REAL_INTEGRATION_RUNBOOK_2026-04-21.md

@@ -100,6 +100,9 @@ real 模式行为固定为：
 | `WECHAT_AUTHORIZE_ENDPOINT` | 否 | 默认桌面二维码授权地址 |
 | `WECHAT_ACCESS_TOKEN_ENDPOINT` | 否 | 默认 access_token 接口 |
 | `WECHAT_USER_INFO_ENDPOINT` | 否 | 默认用户信息接口 |
+| `WECHAT_JS_CODE_SESSION_ENDPOINT` | 否 | 默认小程序 `jscode2session` 接口 |
+| `WECHAT_MINI_PROGRAM_APP_ID` | 小程序 `real` 模式必填 | 微信小程序 AppID；不填时回退 `WECHAT_APP_ID` |
+| `WECHAT_MINI_PROGRAM_APP_SECRET` | 小程序 `real` 模式必填 | 微信小程序 AppSecret；不填时回退 `WECHAT_APP_SECRET` |
 | `WECHAT_STATE_TTL_MINUTES` | 否 | state 有效期，默认 `15` 分钟 |
 
 补充说明：
@@ -225,7 +228,46 @@ https://game.example.com
    - `wechatBound = true`
    - `bindingStatus` 已更新为目标状态
 
-## 8. 账号命中规则
+## 8. 小程序 web-view 登录联调步骤
+
+小程序壳走原生 `wx.login`，不走网页 OAuth callback。联调前需要额外确认：
+
+```bash
+WECHAT_AUTH_ENABLED=true
+WECHAT_AUTH_PROVIDER=real
+WECHAT_MINI_PROGRAM_APP_ID="你的微信小程序 AppID"
+WECHAT_MINI_PROGRAM_APP_SECRET="你的微信小程序 AppSecret"
+```
+
+在 `miniprogram/config.js` 中确认：
+
+```js
+const WEB_VIEW_ENTRY_URL = 'https://你的H5业务域名/';
+const API_BASE_URL = 'https://你的服务器域名/';
+const MINI_PROGRAM_APP_ID = '你的微信小程序 AppID';
+```
+
+联调流程：
+
+1. 微信开发者工具打开项目根目录。
+2. 小程序启动后调用 `wx.login`。
+3. 小程序壳请求：
+
+```http
+POST /api/auth/wechat/miniprogram-login
+```
+
+4. 后端通过 `jscode2session` 兑换 `openid/unionid`。
+5. 后端返回系统 `token`、`bindingStatus` 与 `user`。
+6. 小程序壳打开 H5，并在 hash 中附加：
+   - `auth_provider=wechat`
+   - `auth_token=...`
+   - `auth_binding_status=active|pending_bind_phone`
+7. H5 消费 hash 后通过 `/api/auth/me` 恢复登录态。
+
+这里不能把裸 `openid` 作为 web-view query 登录凭证；`openid` 只能留在后端身份绑定层，H5 只消费本系统 JWT。
+
+## 9. 账号命中规则
 
 当前实现固定按以下顺序命中已有账号：
 
@@ -238,7 +280,7 @@ https://game.example.com
 1. 若按 `unionid` 命中了已有微信身份，但本次微信回调带来了新的 `openid`，后端会把新的 `openid -> user_id` 映射补齐
 2. 若后续绑定手机号时发现该手机号已经属于正式账号，则会把微信身份并入这个正式账号
 
-## 9. 前端验收点
+## 10. 前端验收点
 
 前端联调时至少检查以下行为：
 
@@ -248,6 +290,8 @@ https://game.example.com
 4. 若 `auth_binding_status=pending_bind_phone`，页面必须进入绑定手机号界面
 5. 绑定成功后，应切回正常已登录状态
 
+小程序原生手机号授权链路中，请求体应携带 `wechatPhoneCode`。后端调用微信 `getuserphonenumber` 后，需要按微信原始响应字段 `phoneNumber` / `purePhoneNumber` / `countryCode` 解析手机号；如果误按 Rust 字段名 `phone_number` / `pure_phone_number` / `country_code` 解析，会出现已传 `wechatPhoneCode` 但返回“微信手机号授权失败：缺少手机号”的假失败。
+
 ## 10. 后端验收点
 
 当前后端至少应满足以下检查：

docs/technical/WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md

@@ -0,0 +1,187 @@
+# 微信小程序 web-view 壳接入记录
+
+日期：`2026-05-03`
+
+## 1. 目标
+
+本次先用微信小程序 `web-view` 承载现有 H5，不重写 React/Vite 主前端，也不把 SpacetimeDB SDK 或业务规则搬进小程序端。
+
+当前小程序壳只承担五件事：
+
+1. 提供微信开发者工具可识别的 `miniprogram/` 工程根目录。
+2. 在原生小程序壳中调用 `wx.login` 获取小程序 `code`。
+3. 调用服务器域名下的 `/api/auth/wechat/miniprogram-login`，由 Rust `api-server` 兑换微信身份并签发系统登录态。
+4. 若后端返回 `pending_bind_phone`，先在小程序原生层通过 `button open-type="getPhoneNumber"` 取得用户同意后的手机号动态令牌，再调用 `/api/auth/wechat/bind-phone` 完成绑定。
+5. 用一个全屏 `web-view` 打开现有 H5 入口，并把系统 `auth_token` 放入 H5 现有登录回调 hash。
+
+重要边界：
+
+1. `openid` 只作为后端微信身份绑定依据，不直接暴露给 H5 当登录凭证。
+2. H5 继续消费本系统 JWT，也就是 `#auth_provider=wechat&auth_token=...&auth_binding_status=...`。
+3. 这与 [`WECHAT_LOGIN_AXUM_IMPLEMENTATION_DESIGN_2026-04-21.md`](./WECHAT_LOGIN_AXUM_IMPLEMENTATION_DESIGN_2026-04-21.md) 中“微信只提供三方身份，Axum 签发系统 JWT”的边界一致。
+
+## 2. 文件入口
+
+| 文件 | 说明 |
+| --- | --- |
+| `project.config.json` | 指定 `miniprogramRoot: "miniprogram/"`。 |
+| `miniprogram/app.json` | 小程序全局配置，注册 `pages/web-view/index`。 |
+| `miniprogram/config.js` | 业务域名入口配置，需要部署时填写。 |
+| `miniprogram/pages/web-view/index.*` | 最小 web-view 页面。 |
+| `server-rs/crates/api-server/src/wechat_auth.rs` | 新增小程序登录接口 `/api/auth/wechat/miniprogram-login`。 |
+| `server-rs/crates/platform-auth/src/lib.rs` | 新增 `jscode2session` 兑换能力。 |
+
+## 3. 需要手工填写的配置
+
+在 `miniprogram/config.js` 中填写：
+
+```js
+const WEB_VIEW_ENTRY_URL = 'https://你的H5业务域名/';
+const API_BASE_URL = 'https://你的服务器域名/';
+const MINI_PROGRAM_APP_ID = '你的微信小程序 AppID';
+const MINI_PROGRAM_ENV = 'develop';
+```
+
+约束：
+
+1. 必须是 `https`。
+2. 不能是 `localhost` 或 IP。
+3. `WEB_VIEW_ENTRY_URL` 域名需要在微信小程序后台配置为业务域名。
+4. `API_BASE_URL` 域名需要在微信小程序后台配置为 request 合法域名。
+5. H5 页面里的 API、图片、音视频、iframe 等外链也要满足微信侧域名与证书要求。
+
+在 `api-server` 环境变量中填写：
+
+```bash
+WECHAT_AUTH_ENABLED=true
+WECHAT_AUTH_PROVIDER=real
+WECHAT_MINI_PROGRAM_APP_ID="你的微信小程序 AppID"
+WECHAT_MINI_PROGRAM_APP_SECRET="你的微信小程序 AppSecret"
+WECHAT_JS_CODE_SESSION_ENDPOINT="https://api.weixin.qq.com/sns/jscode2session"
+WECHAT_STABLE_ACCESS_TOKEN_ENDPOINT="https://api.weixin.qq.com/cgi-bin/stable_token"
+WECHAT_PHONE_NUMBER_ENDPOINT="https://api.weixin.qq.com/wxa/business/getuserphonenumber"
+```
+
+如果开放平台网页 OAuth 与小程序使用同一个 AppID/Secret，也可以继续使用已有：
+
+```bash
+WECHAT_APP_ID="你的微信 AppID"
+WECHAT_APP_SECRET="你的微信 AppSecret"
+```
+
+但正式部署建议把小程序配置写到 `WECHAT_MINI_PROGRAM_APP_ID` 与 `WECHAT_MINI_PROGRAM_APP_SECRET`，避免和网页 OAuth 配置混淆。
+
+`WEB_VIEW_SOURCE_QUERY` 默认附加：
+
+```text
+clientType=mini_program
+clientRuntime=wechat_mini_program
+```
+
+小程序壳调用登录接口时会补传：
+
+```text
+x-client-type=mini_program
+x-client-runtime=wechat_mini_program
+x-client-platform=ios|android|unknown
+x-client-instance-id=<小程序本地持久化随机值>
+x-mini-program-app-id=<MINI_PROGRAM_APP_ID>
+x-mini-program-env=<MINI_PROGRAM_ENV>
+```
+
+这些字段会进入 refresh session 的客户端身份快照；URL query 只作为 H5 识别宿主来源的轻量标记，不作为鉴权依据。
+
+## 4. 登录链路
+
+当前登录链路固定为：
+
+1. 小程序页面启动。
+2. 调用 `wx.login` 获取一次性 `code`。
+3. 小程序壳请求：
+
+```http
+POST /api/auth/wechat/miniprogram-login
+Content-Type: application/json
+
+{
+  "code": "wx.login 返回的 code"
+}
+```
+
+4. `api-server` 调用微信 `jscode2session` 兑换 `openid/unionid`。
+5. `api-server` 复用现有微信身份逻辑：
+   - 先按 `unionid` 命中已有身份
+   - 再按 `openid` 命中已有身份
+   - 都没有命中时创建 `pending_bind_phone` 的微信壳账号
+6. `api-server` 签发系统 access token，并写入 refresh session。
+7. 如果返回 `bindingStatus=active`，小程序壳打开：
+
+```text
+https://你的H5业务域名/#auth_provider=wechat&auth_token=<系统JWT>&auth_binding_status=active
+```
+
+8. 如果返回 `bindingStatus=pending_bind_phone`，小程序壳暂不打开 H5，而是展示原生 `getPhoneNumber` 按钮。用户点击并同意后，小程序把 `bindgetphonenumber` 事件里的 `detail.code` 作为 `wechatPhoneCode` 传给：
+
+```http
+POST /api/auth/wechat/bind-phone
+Authorization: Bearer <小程序登录返回的系统JWT>
+Content-Type: application/json
+
+{
+  "wechatPhoneCode": "getPhoneNumber 返回的 code"
+}
+```
+
+9. `api-server` 通过微信 `stable_token` 获取小程序 `access_token`，再调用 `getuserphonenumber` 换取平台验证后的手机号，并复用现有微信待绑定账号合并逻辑。微信返回的手机号字段使用 `phoneNumber` / `purePhoneNumber` / `countryCode`，后端解析时必须兼容这些原始 camelCase 字段；否则会在已收到 `wechatPhoneCode` 的情况下误报“微信手机号授权失败：缺少手机号”。成功后重新签发 `active` 系统 token。
+10. H5 复用 `consumeAuthCallbackResult()` 消费 `auth_token` 并进入现有登录态恢复流程。
+
+补充：H5 里的旧短信验证码绑定页继续保留为非小程序环境兜底；小程序原生手机号授权只替代“手动输入手机号 + 短信验证码”这一步，不代表后台静默读取本机号码。
+
+## 5. 微信后台配置
+
+至少需要在小程序后台配置：
+
+1. `业务域名`：承载 H5 的域名。
+2. `request 合法域名`：`API_BASE_URL` 对应的服务器域名。
+3. `socket 合法域名`：若后续小程序原生层直连 WebSocket 才需要；当前不启用。
+
+当前仓库的 H5 仍建议通过同域 `/api/*` 访问 Rust `api-server`，避免在小程序和 H5 中分别维护跨域白名单。
+
+## 6. 当前不做的事
+
+本次不做原生小程序页面迁移，原因是当前主前端依赖：
+
+1. React DOM 挂载、浏览器 history 和 `window.location`。
+2. `localStorage` / `sessionStorage`。
+3. 浏览器 `fetch` 与 `ReadableStream` SSE。
+4. DOM、Canvas、Three.js 等浏览器渲染能力。
+
+这些能力不能稳定原样运行在原生小程序宿主中。后续如要原生化，应新建小程序端宿主，复用 `packages/shared` 契约和 `api-server` BFF，而不是把 `src/` 整体搬过去。
+
+本次也不做 `openid` query 直登。原因是 `openid` 不是本系统签发的登录凭证，不能表达 token 版本、会话 ID、绑定状态、角色与过期时间，也不能被 H5 直接信任。
+
+## 7. 验收口径
+
+可重复自动化 smoke：
+
+```bash
+npm run check:wechat-miniprogram-auth
+```
+
+该命令固定覆盖三段链路：
+
+1. 静态确认 `miniprogram/pages/web-view/index.js` 会请求 `/api/auth/wechat/miniprogram-login`，携带 `mini_program / wechat_mini_program` 客户端来源头，并把 `auth_provider/auth_token/auth_binding_status` 拼入 H5 hash。
+2. 运行 `api-server` 定向测试 `wechat_miniprogram_login_returns_system_token_and_marks_session_source`，断言小程序登录返回 `token/bindingStatus/user`、写入 refresh cookie，并且 `/api/auth/sessions` 能看到 `clientType=mini_program`、`clientRuntime=wechat_mini_program`、`miniProgramAppId`。
+3. 静态确认小程序壳在 `pending_bind_phone` 时使用 `getPhoneNumber` 和 `wechatPhoneCode` 调用 `/api/auth/wechat/bind-phone`，而不是打开 H5 后再要求手输手机号。
+4. 运行前端 `authService` 定向测试，断言 `consumeAuthCallbackResult()` 会消费 `#auth_provider=wechat&auth_token=...&auth_binding_status=...`、保存 access token，并清理地址栏 hash。
+
+手工联调仍按以下口径确认真实微信与域名配置：
+
+1. 微信开发者工具打开项目根目录后，识别 `miniprogram/` 为小程序源码目录。
+2. 未填写 `WEB_VIEW_ENTRY_URL` 或 `API_BASE_URL` 时，页面显示配置提示，不出现空白页。
+3. 填写已配置业务域名后，小程序先请求 `/api/auth/wechat/miniprogram-login`。
+4. 后端返回 `token/bindingStatus/user`，并写入 refresh cookie。
+5. 若返回 `pending_bind_phone`，先看到小程序原生授权手机号按钮；用户同意后，小程序请求 `/api/auth/wechat/bind-phone` 且请求体包含 `wechatPhoneCode`。
+6. 绑定成功后首页全屏打开 H5，URL hash 中包含 `auth_provider=wechat`、`auth_token`、`auth_binding_status=active`。
+7. H5 内 `consumeAuthCallbackResult()` 消费 hash 后，`/api/auth/me` 能返回当前用户。
+8. `/api/auth/sessions` 能看到来源为 `mini_program / wechat_mini_program` 的会话记录。

jenkins/Jenkinsfile.production-api-build

@@ -10,7 +10,7 @@ pipeline {
   }
 
   environment {
-    GIT_REMOTE_URL = 'http://82.157.175.59:3000/GenarrativeAI/Genarrative.git'
+    GIT_REMOTE_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
     CARGO_HOME = '/home/dsk/.cache/genarrative-jenkins/api-server/cargo-home'
     CARGO_TARGET_DIR = '/home/dsk/.cache/genarrative-jenkins/api-server/cargo-target/prod-release'
     CARGO_INCREMENTAL = '0'

jenkins/Jenkinsfile.production-api-deploy

@@ -9,6 +9,7 @@ pipeline {
 
   environment {
     GIT_REMOTE_URL = 'http://127.0.0.1:3000/GenarrativeAI/Genarrative.git'
+    GIT_REMOTE_FALLBACK_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
   }
 
   parameters {
@@ -66,13 +67,28 @@ pipeline {
         label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-build' : 'linux && genarrative-release-deploy'}"
       }
       steps {
+        script {
+          def checkoutFromRemote = { String remoteUrl ->
             checkout([
               $class: 'GitSCM',
               branches: [[name: "*/${params.SOURCE_BRANCH}"]],
               doGenerateSubmoduleConfigurations: false,
-          extensions: [[$class: 'CleanBeforeCheckout']],
+              extensions: [
-          userRemoteConfigs: [[url: "${GIT_REMOTE_URL}"]],
+                [$class: 'CleanBeforeCheckout'],
+                [$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
+              ],
+              userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
             ])
+          }
+          try {
+            checkoutFromRemote(env.GIT_REMOTE_URL)
+            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_URL
+          } catch (error) {
+            echo "Git 主地址拉取失败: ${env.GIT_REMOTE_URL}，改用备用地址: ${env.GIT_REMOTE_FALLBACK_URL}"
+            checkoutFromRemote(env.GIT_REMOTE_FALLBACK_URL)
+            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
+          }
+        }
         script {
           if (params.COMMIT_HASH?.trim()) {
             echo "API 发布脚本 checkout 将忽略上游构建 commit=${params.COMMIT_HASH}，改用 ${params.SOURCE_BRANCH ?: 'master'} 最新提交，避免发布阶段回退到旧部署脚本。构建产物仍由 BUILD_NUMBER_TO_DEPLOY 决定。"
@@ -84,7 +100,8 @@ pipeline {
             chmod +x scripts/jenkins-checkout-source.sh
             SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
             COMMIT_HASH="" \
-            GIT_REMOTE_URL="${GIT_REMOTE_URL}" \
+            GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
+            GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
             SOURCE_COMMIT_FILE=".jenkins-source-commit" \
             scripts/jenkins-checkout-source.sh
           '

jenkins/Jenkinsfile.production-database-export

@@ -9,6 +9,7 @@ pipeline {
 
   environment {
     GIT_REMOTE_URL = 'http://127.0.0.1:3000/GenarrativeAI/Genarrative.git'
+    GIT_REMOTE_FALLBACK_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
   }
 
   parameters {
@@ -82,20 +83,36 @@ pipeline {
         label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-build' : 'linux && genarrative-release-deploy'}"
       }
       steps {
+        script {
+          def checkoutFromRemote = { String remoteUrl ->
             checkout([
               $class: 'GitSCM',
               branches: [[name: "*/${params.SOURCE_BRANCH}"]],
               doGenerateSubmoduleConfigurations: false,
-          extensions: [[$class: 'CleanBeforeCheckout']],
+              extensions: [
-          userRemoteConfigs: [[url: "${GIT_REMOTE_URL}"]],
+                [$class: 'CleanBeforeCheckout'],
+                [$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
+              ],
+              userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
             ])
+          }
+          try {
+            checkoutFromRemote(env.GIT_REMOTE_URL)
+            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_URL
+          } catch (error) {
+            echo "Git 主地址拉取失败: ${env.GIT_REMOTE_URL}，改用备用地址: ${env.GIT_REMOTE_FALLBACK_URL}"
+            checkoutFromRemote(env.GIT_REMOTE_FALLBACK_URL)
+            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
+          }
+        }
         sh '''
           bash -lc '
             set -euo pipefail
             chmod +x scripts/jenkins-checkout-source.sh
             SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
             COMMIT_HASH="${COMMIT_HASH:-}" \
-            GIT_REMOTE_URL="${GIT_REMOTE_URL}" \
+            GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
+            GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
             SOURCE_COMMIT_FILE=".jenkins-source-commit" \
             scripts/jenkins-checkout-source.sh
           '

jenkins/Jenkinsfile.production-database-import

@@ -9,6 +9,7 @@ pipeline {
 
   environment {
     GIT_REMOTE_URL = 'http://127.0.0.1:3000/GenarrativeAI/Genarrative.git'
+    GIT_REMOTE_FALLBACK_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
   }
 
   parameters {
@@ -140,20 +141,36 @@ pipeline {
         label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-build' : 'linux && genarrative-release-deploy'}"
       }
       steps {
+        script {
+          def checkoutFromRemote = { String remoteUrl ->
             checkout([
               $class: 'GitSCM',
               branches: [[name: "*/${params.SOURCE_BRANCH}"]],
               doGenerateSubmoduleConfigurations: false,
-          extensions: [[$class: 'CleanBeforeCheckout']],
+              extensions: [
-          userRemoteConfigs: [[url: "${GIT_REMOTE_URL}"]],
+                [$class: 'CleanBeforeCheckout'],
+                [$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
+              ],
+              userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
             ])
+          }
+          try {
+            checkoutFromRemote(env.GIT_REMOTE_URL)
+            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_URL
+          } catch (error) {
+            echo "Git 主地址拉取失败: ${env.GIT_REMOTE_URL}，改用备用地址: ${env.GIT_REMOTE_FALLBACK_URL}"
+            checkoutFromRemote(env.GIT_REMOTE_FALLBACK_URL)
+            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
+          }
+        }
         sh '''
           bash -lc '
             set -euo pipefail
             chmod +x scripts/jenkins-checkout-source.sh
             SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
             COMMIT_HASH="${COMMIT_HASH:-}" \
-            GIT_REMOTE_URL="${GIT_REMOTE_URL}" \
+            GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
+            GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
             SOURCE_COMMIT_FILE=".jenkins-source-commit" \
             scripts/jenkins-checkout-source.sh
           '

jenkins/Jenkinsfile.production-full-build-and-deploy

@@ -12,7 +12,7 @@ pipeline {
   }
 
   environment {
-    GIT_REMOTE_URL = 'http://82.157.175.59:3000/GenarrativeAI/Genarrative.git'
+    GIT_REMOTE_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
   }
 
   parameters {

jenkins/Jenkinsfile.production-server-provision

@@ -9,6 +9,7 @@ pipeline {
 
   environment {
     GIT_REMOTE_URL = 'http://127.0.0.1:3000/GenarrativeAI/Genarrative.git'
+    GIT_REMOTE_FALLBACK_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
   }
 
   parameters {
@@ -19,7 +20,8 @@ pipeline {
     booleanParam(name: 'DRY_RUN', defaultValue: true, description: '只打印将执行的服务器初始化命令，不写入系统配置')
     string(name: 'SOURCE_BRANCH', defaultValue: 'master', description: '部署脚本来源分支')
     string(name: 'COMMIT_HASH', defaultValue: '', description: '部署脚本来源 commit')
-    string(name: 'SERVER_NAME', defaultValue: 'genarrative.example.com', description: 'Nginx server_name 与证书域名')
+    string(name: 'SERVER_NAME', defaultValue: 'genarrative.example.com', description: '证书主域名；也作为 Nginx server_name 的第一个域名')
+    string(name: 'SERVER_ALIASES', defaultValue: '', description: '可选，额外 Nginx server_name，多个用空格或逗号分隔，例如 www.genarrative.world')
     string(name: 'SPACETIME_BIN_SOURCE', defaultValue: '/usr/local/bin/spacetime', description: '服务器上已有 spacetime CLI 路径')
     string(name: 'SPACETIME_ROOT', defaultValue: '/stdb', description: 'SpacetimeDB root-dir')
     string(name: 'RELEASE_ROOT', defaultValue: '/opt/genarrative/releases', description: 'release 根目录')
@@ -47,6 +49,17 @@ pipeline {
           if (!params.SERVER_NAME?.trim()) {
             error('SERVER_NAME 不能为空。')
           }
+          if (!(params.SERVER_NAME.trim() ==~ /^[A-Za-z0-9][A-Za-z0-9.-]*$/)) {
+            error("SERVER_NAME 只能填写单个域名或 IP，不能包含空格、路径或协议: ${params.SERVER_NAME}")
+          }
+          def serverAliases = params.SERVER_ALIASES?.trim()
+          if (serverAliases) {
+            serverAliases.split(/[,\s]+/).findAll { it }.each { aliasName ->
+              if (!(aliasName ==~ /^[A-Za-z0-9][A-Za-z0-9.-]*$/)) {
+                error("SERVER_ALIASES 只能填写域名或 IP，多个用空格或逗号分隔: ${aliasName}")
+              }
+            }
+          }
           if (!params.SPACETIME_BIN_SOURCE?.trim()) {
             error('SPACETIME_BIN_SOURCE 不能为空。')
           }
@@ -69,20 +82,36 @@ pipeline {
         label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-build' : 'linux && genarrative-release-deploy'}"
       }
       steps {
+        script {
+          def checkoutFromRemote = { String remoteUrl ->
             checkout([
               $class: 'GitSCM',
               branches: [[name: "*/${params.SOURCE_BRANCH}"]],
               doGenerateSubmoduleConfigurations: false,
-          extensions: [[$class: 'CleanBeforeCheckout']],
+              extensions: [
-          userRemoteConfigs: [[url: "${GIT_REMOTE_URL}"]],
+                [$class: 'CleanBeforeCheckout'],
+                [$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
+              ],
+              userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
             ])
+          }
+          try {
+            checkoutFromRemote(env.GIT_REMOTE_URL)
+            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_URL
+          } catch (error) {
+            echo "Git 主地址拉取失败: ${env.GIT_REMOTE_URL}，改用备用地址: ${env.GIT_REMOTE_FALLBACK_URL}"
+            checkoutFromRemote(env.GIT_REMOTE_FALLBACK_URL)
+            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
+          }
+        }
         sh '''
           bash <<'BASH'
             set -euo pipefail
             chmod +x scripts/jenkins-checkout-source.sh
             SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
             COMMIT_HASH="${COMMIT_HASH:-}" \
-            GIT_REMOTE_URL="${GIT_REMOTE_URL}" \
+            GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
+            GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
             SOURCE_COMMIT_FILE=".jenkins-source-commit" \
             scripts/jenkins-checkout-source.sh
 BASH

jenkins/Jenkinsfile.production-stdb-module-build

@@ -10,7 +10,7 @@ pipeline {
   }
 
   environment {
-    GIT_REMOTE_URL = 'http://82.157.175.59:3000/GenarrativeAI/Genarrative.git'
+    GIT_REMOTE_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
     CARGO_HOME = '${env.WORKSPACE_TMP}/cargo-home'
     CARGO_TARGET_DIR = '${env.WORKSPACE_TMP}/cargo-target/prod-release'
     CARGO_INCREMENTAL = '0'
@@ -49,7 +49,7 @@ pipeline {
           $ErrorActionPreference = 'Stop'
           $sourceBranch = if ($env:SOURCE_BRANCH) { $env:SOURCE_BRANCH } else { 'master' }
           $commitHash = if ($env:COMMIT_HASH) { $env:COMMIT_HASH } else { '' }
-          $gitRemoteUrl = if ($env:GIT_REMOTE_URL) { $env:GIT_REMOTE_URL } else { 'http://82.157.175.59:3000/GenarrativeAI/Genarrative.git' }
+          $gitRemoteUrl = if ($env:GIT_REMOTE_URL) { $env:GIT_REMOTE_URL } else { 'https://git.genarrative.world/GenarrativeAI/Genarrative.git' }
           git fetch --no-tags --prune --depth=1 $gitRemoteUrl "+refs/heads/${sourceBranch}:refs/remotes/origin/${sourceBranch}"
           if ($commitHash) {
             git checkout --force $commitHash

jenkins/Jenkinsfile.production-stdb-module-publish

@@ -9,6 +9,7 @@ pipeline {
 
   environment {
     GIT_REMOTE_URL = 'http://127.0.0.1:3000/GenarrativeAI/Genarrative.git'
+    GIT_REMOTE_FALLBACK_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
   }
 
   parameters {
@@ -78,20 +79,36 @@ pipeline {
         label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-build' : 'linux && genarrative-release-deploy'}"
       }
       steps {
+        script {
+          def checkoutFromRemote = { String remoteUrl ->
             checkout([
               $class: 'GitSCM',
               branches: [[name: "*/${params.SOURCE_BRANCH}"]],
               doGenerateSubmoduleConfigurations: false,
-          extensions: [[$class: 'CleanBeforeCheckout']],
+              extensions: [
-          userRemoteConfigs: [[url: "${GIT_REMOTE_URL}"]],
+                [$class: 'CleanBeforeCheckout'],
+                [$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
+              ],
+              userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
             ])
+          }
+          try {
+            checkoutFromRemote(env.GIT_REMOTE_URL)
+            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_URL
+          } catch (error) {
+            echo "Git 主地址拉取失败: ${env.GIT_REMOTE_URL}，改用备用地址: ${env.GIT_REMOTE_FALLBACK_URL}"
+            checkoutFromRemote(env.GIT_REMOTE_FALLBACK_URL)
+            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
+          }
+        }
         sh '''
           bash -lc '
             set -euo pipefail
             chmod +x scripts/jenkins-checkout-source.sh
             SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
             COMMIT_HASH="${COMMIT_HASH:-}" \
-            GIT_REMOTE_URL="${GIT_REMOTE_URL}" \
+            GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
+            GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
             SOURCE_COMMIT_FILE=".jenkins-source-commit" \
             scripts/jenkins-checkout-source.sh
           '

jenkins/Jenkinsfile.production-web-build

@@ -10,7 +10,7 @@ pipeline {
   }
 
   environment {
-    GIT_REMOTE_URL = 'http://82.157.175.59:3000/GenarrativeAI/Genarrative.git'
+    GIT_REMOTE_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
     WEB_ARTIFACT_ROOT = '/var/cache/genarrative-build/web-artifacts'
   }
 

jenkins/Jenkinsfile.production-web-deploy

@@ -9,6 +9,7 @@ pipeline {
 
   environment {
     GIT_REMOTE_URL = 'http://127.0.0.1:3000/GenarrativeAI/Genarrative.git'
+    GIT_REMOTE_FALLBACK_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
     WEB_ARTIFACT_ROOT = '/var/cache/genarrative-build/web-artifacts'
   }
 
@@ -24,6 +25,9 @@ pipeline {
     string(name: 'RELEASE_ROOT', defaultValue: '/opt/genarrative/releases', description: '生产 release 根目录')
     string(name: 'CURRENT_LINK', defaultValue: '/opt/genarrative/current', description: '当前版本软链接')
     string(name: 'WEB_LINK', defaultValue: '/srv/genarrative/web', description: 'Nginx 静态站点软链接')
+    booleanParam(name: 'SYNC_WEB_ARTIFACT_FROM_BUILD_HOST', defaultValue: true, description: 'release 目标本地缺少 Web 大包时，是否通过 rsync 从构建机内网拉取')
+    string(name: 'WEB_ARTIFACT_SYNC_HOST', defaultValue: 'genarrative-build-internal', description: 'rsync 源 SSH Host，通常来自 release 服务器上 Jenkins 运行用户的 ~/.ssh/config')
+    string(name: 'WEB_ARTIFACT_SYNC_SSH_CONFIG', defaultValue: '', description: '可选，rsync 使用的 ssh config 绝对路径；留空使用当前用户默认 ~/.ssh/config')
   }
 
   stages {
@@ -54,20 +58,36 @@ pipeline {
         label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-build' : 'linux && genarrative-release-deploy'}"
       }
       steps {
+        script {
+          def checkoutFromRemote = { String remoteUrl ->
             checkout([
               $class: 'GitSCM',
               branches: [[name: "*/${params.SOURCE_BRANCH}"]],
               doGenerateSubmoduleConfigurations: false,
-          extensions: [[$class: 'CleanBeforeCheckout']],
+              extensions: [
-          userRemoteConfigs: [[url: "${GIT_REMOTE_URL}"]],
+                [$class: 'CleanBeforeCheckout'],
+                [$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
+              ],
+              userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
             ])
+          }
+          try {
+            checkoutFromRemote(env.GIT_REMOTE_URL)
+            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_URL
+          } catch (error) {
+            echo "Git 主地址拉取失败: ${env.GIT_REMOTE_URL}，改用备用地址: ${env.GIT_REMOTE_FALLBACK_URL}"
+            checkoutFromRemote(env.GIT_REMOTE_FALLBACK_URL)
+            env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
+          }
+        }
         sh '''
           bash -lc '
             set -euo pipefail
             chmod +x scripts/jenkins-checkout-source.sh
             SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
             COMMIT_HASH="${COMMIT_HASH:-}" \
-            GIT_REMOTE_URL="${GIT_REMOTE_URL}" \
+            GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
+            GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
             SOURCE_COMMIT_FILE=".jenkins-source-commit" \
             scripts/jenkins-checkout-source.sh
           '
@@ -92,9 +112,36 @@ pipeline {
             set -euo pipefail
 
             artifact_dir="${WEB_ARTIFACT_ROOT}/${BUILD_JOB_NAME}/${BUILD_NUMBER_TO_DEPLOY}/${BUILD_VERSION}"
+            if [[ ! -f "${artifact_dir}/web.tar.gz" ]]; then
+              sync_enabled="${SYNC_WEB_ARTIFACT_FROM_BUILD_HOST:-true}"
+              sync_host="${WEB_ARTIFACT_SYNC_HOST:-genarrative-build-internal}"
+              sync_ssh_config="${WEB_ARTIFACT_SYNC_SSH_CONFIG:-}"
+
+              if [[ "${DEPLOY_TARGET:-development}" == "release" && "${sync_enabled}" == "true" ]]; then
+                if [[ -z "${sync_host}" ]]; then
+                  echo "[web-deploy] release 目标需要同步 Web 大包，但 WEB_ARTIFACT_SYNC_HOST 为空。" >&2
+                  exit 1
+                fi
+
+                echo "[web-deploy] release 目标本地缓存缺少 Web 大包，尝试从 ${sync_host} 同步: ${artifact_dir}"
+                if ! command -v rsync >/dev/null 2>&1; then
+                  echo "[web-deploy] 当前 release agent 缺少 rsync，请先安装 rsync 或预先挂载 Web 产物目录。" >&2
+                  exit 1
+                fi
+                mkdir -p "${artifact_dir}"
+
+                rsync_args=(-av --progress)
+                if [[ -n "${sync_ssh_config}" ]]; then
+                  rsync_args+=(-e "ssh -F ${sync_ssh_config}")
+                fi
+
+                rsync "${rsync_args[@]}" "${sync_host}:${artifact_dir}/" "${artifact_dir}/"
+              fi
+            fi
+
             if [[ ! -f "${artifact_dir}/web.tar.gz" ]]; then
               echo "[web-deploy] 未找到构建机本地 Web 大包: ${artifact_dir}/web.tar.gz" >&2
-              echo "[web-deploy] development 目标要求 Web 构建与发布共享同一 Linux 构建/开发部署机；release 目标需要预先同步或挂载 ${WEB_ARTIFACT_ROOT}。" >&2
+              echo "[web-deploy] development 目标要求 Web 构建与发布共享同一 Linux 构建/开发部署机；release 目标会默认通过 rsync 从 WEB_ARTIFACT_SYNC_HOST 拉取，也可预先同步或挂载 ${WEB_ARTIFACT_ROOT}。" >&2
               exit 1
             fi
 

media/files/disclaimer.md

@@ -0,0 +1,42 @@
+## 免责声明
+在使用百梦（Genarrative）平台前，请仔细阅读以下声明。
+
+### 一、AI 内容免责
+1. 本平台基于第三方 AI 大语言模型提供文字游戏体验，所有 AI 生成内容均为算法自动产出，不代表本平台的观点、立场或价值取向。
+2. AI 具有内容生成的不确定性，可能产出不准确、不完整或不当的内容。平台已部署安全过滤机制，但无法做到百分之百的内容审查。
+3. AI 生成内容仅供娱乐体验，不构成任何形式的事实陈述或专业建议。用户不应将其作为决策依据。
+
+### 二、用户行为免责
+1. 用户在平台上发布的所有内容（包括自定义剧本、论坛帖子、评论等）均由用户自行负责。
+2. 用户主动诱导 AI 生成违法违规内容的，由用户自行承担全部法律责任，平台不承担任何连带责任。
+3. 用户利用平台进行任何违法活动所导致的后果，由用户自行承担。
+   本平台论坛功能允许用户自由发布文字、图片等内容。对此，特别声明如下：
+    - 版权声明：用户在论坛发布的所有内容（文字、图片、截图等）应为用户原创或已获得合法授权。平台不对用户发布内容进行事先版权审查，不对用户内容的合法性承担审核义务。
+    - 侵权责任：如用户发布的内容侵犯了任何第三方的知识产权（包括但不限于著作权、肖像权、商标权等），一切法律责任由发布该内容的用户独自承担，与本平台无关。
+    - 平台角色：本平台仅作为用户内容的技术展示平台，提供信息存储与展示服务，不对任何用户内容进行编辑、推荐背书或商业利用。平台不对用户内容的真实性、准确性、完整性或合法性作任何形式的保证。
+    - 内容处置：平台有权根据法律法规、监管要求或平台规则，对涉嫌侵权或违规的用户内容进行删除、屏蔽等处理，且无需事先通知发布者。
+    - 追偿权利：如因用户发布的内容导致平台被第三方索赔或遭受任何损失，平台保留向该用户追偿全部损失的权利。
+    - 图片特别说明：用户上传的图片应确保拥有合法使用权。对于AI生成的图片，用户应确认其所使用的AI工具允许将生成内容进行公开发布，并自行承担由此产生的任何法律责任。
+
+### 三、第三方服务免责
+1. 用户自行配置的第三方 API 密钥产生的费用和数据安全问题，由用户自行负责。
+2. 因第三方 AI 服务商的服务中断、数据泄露等问题导致的损失，本平台不承担责任。
+3. 平台内的外部链接仅供便利，不代表平台对链接内容的认可或担保。
+
+### 四、服务可用性
+1. 本平台按"现状"提供服务，不作任何明示或暗示的保证。
+2. 平台可能因维护升级、技术故障、不可抗力等原因发生服务中断，平台将尽合理努力恢复服务，但不对此承担赔偿责任。
+3. 平台有权根据运营情况调整服务内容、功能或收费标准。
+
+### 五、数据安全
+1. 平台将尽合理努力保障用户数据安全，但无法提供绝对安全保证。
+2. 因用户自身原因（如密码泄露、浏览器使用不当、未使用推荐浏览器、浏览器或者手机自身崩溃导致数据丢失、浏览器无痕模式、设备丢失）导致的数据损失，平台不承担责任。
+3. 用户应自行做好重要数据的备份。
+
+### 六、违规处理与执法配合
+1. 平台有权对违反用户协议的账号采取包括但不限于警告、限制功能、封禁账号等措施，且不予退还任何已消费的费用。
+2. 对于涉嫌违法犯罪的行为，平台将保留相关证据并依法向有关部门报告。
+3. 平台依法配合国家有关部门的监管和调查工作，并根据法律要求提供必要的用户信息和操作记录。
+
+### 七、责任限制
+在法律允许的最大范围内，平台就任何间接、附带、特殊、惩罚性损害不承担责任。平台对用户因使用本平台而产生的任何损失所承担的最大责任，不超过用户实际向平台支付的费用金额。

media/files/privacy_policy.md

@@ -0,0 +1,61 @@
+## 隐私政策
+百梦（Genarrative）平台深知个人信息安全的重要性。本政策说明我们如何收集、使用、存储和保护您的个人信息。
+
+### 一、我们收集的信息
+1. 您主动提供的信息
+   - 注册信息：邮箱地址、密码（加密存储）、昵称
+   - 论坛内容：您发布的帖子、评论等
+
+2. 自动收集的信息
+   - 设备信息：浏览器类型、操作系统
+   - 使用记录：操作日志、访问时间、功能使用频率
+   - 网络信息：IP 地址（用于安全防护和合规要求）
+
+3. 我们不会收集的信息
+   - 我们不会收集您的身份证号、手机号、银行账号等敏感个人信息
+   - 我们不会读取您设备上的通讯录、相册、定位等信息
+
+### 二、信息使用目的
+我们仅在以下场景使用您的个人信息：
+1. 提供和维护平台核心功能（账号管理、内容服务、云端存档）
+2. 保障账号和平台安全（登录验证、异常检测、防止滥用）
+3. 改进服务质量（使用统计分析，均以匿名、聚合方式进行）
+4. 履行法律义务（依法配合有权机关的调查请求）
+5. 发送与服务直接相关的通知（账号安全提醒等）
+   
+**我们不会将您的个人信息用于任何未经您同意的营销推广目的。**
+
+### 三、信息存储与安全
+1. 您的数据存储在具备安全保障的云服务器上。
+2. 密码采用单向加密存储，任何人（包括平台管理员）均无法查看明文密码。
+3. 用户操作日志保存期限不少于六个月，以满足法律合规要求。
+4. 我们采取合理的技术和管理措施防止数据泄露、篡改和丢失，但无法保证绝对安全。
+   
+### 四、信息共享
+我们**不会**主动向第三方出售或分享您的个人信息，但以下情况除外：
+1. 获得您的明确同意；
+2. 根据法律法规的要求或有权机关的强制性要求；
+3. 为保护平台、其他用户或公众的合法权益所必需；
+4. 与平台核心功能直接相关的第三方服务（如邮件发送服务），且该第三方受到严格的数据保护约束。
+   
+### 五、用户自行配置 API 的说明
+如您选择使用自定义 API 密钥，您的游戏对话内容将直接发送至您指定的第三方 AI 服务提供商。该部分数据的处理受该第三方的隐私政策约束，平台对此不承担责任。
+
+### 六、您的权利
+1. 访问权：您可以随时查看和修改您的个人信息。
+2. 删除权：您可以申请删除您的账号和相关数据。
+3. 导出权：您可以导出您的游戏存档数据。
+   如需行使以上权利或有隐私相关疑问，请通过平台提供的联系方式与我们沟通。
+
+### 七、未成年人保护
+本平台不向未满 18 周岁的未成年人提供服务。如我们发现在未获得家长或监护人同意的情况下收集了未成年人的个人信息，将尽快删除相关信息。
+
+### 八、论坛用户生成内容
+当您在论坛发布内容时，我们会收集并存储以下信息：
+- 您发布的文字、图片等内容本身
+- 发布时间、编辑记录等操作信息
+- 与内容关联的互动信息（点赞、评论等）
+请注意：您在论坛公开发布的内容对所有平台用户可见。请勿在公开内容中包含个人敏感信息。您上传的图片可能包含元数据（如拍摄时间、地理位置），建议您在上传前自行清除此类信息。
+
+### 九、政策更新
+本政策可能根据法律法规变化或平台运营需要进行更新。更新后将在平台公布，继续使用即视为同意更新后的政策。

media/files/user_agreement.md

@@ -0,0 +1,103 @@
+## 百梦用户协议
+欢迎使用百梦（Genarrative）平台。请您在注册或使用本平台服务前，仔细阅读并充分理解本协议的全部内容。注册、登录或继续使用本平台即表示您已阅读、理解并同意接受本协议的约束。
+
+### 一、服务说明
+百梦是一个基于人工智能技术的交互内容创作与体验平台，为用户提供优质的内容体验和方便快捷的创作工具。平台所生成的内容由AI模型自动产出，不代表本平台的立场或观点。
+
+### 二、用户资格
+1. 您必须年满**18周岁**方可注册和使用本平台。
+2. 如您为未成年人，请立即停止使用本平台服务，本平台不对未成年人提供服务。
+3. 若您的监护人发现您未满18周岁已注册使用本平台，可联系平台协助注销相关账号。
+4. 您应当提供真实、准确的注册信息，并对账号下的一切行为承担法律责任。
+
+### 三、用户行为规范
+使用本平台时，您承诺**不得**从事以下行为：
+
+1. **发布、传播或诱导生成**涉及以下内容的信息：
+   - 违反宪法所确定的基本原则的内容；
+   - 危害国家安全、泄露国家秘密、颠覆国家政权、破坏国家统一的内容；
+   - 损害国家荣誉和利益的内容；
+   - 煽动民族仇恨、民族歧视，破坏民族团结的内容；
+   - 破坏国家宗教政策，宣扬邪教和封建迷信的内容；
+   - 散布谣言，扰乱社会秩序，破坏社会稳定的内容；
+   - 涉及淫秽、色情、赌博、暴力、凶杀、恐怖的内容；
+   - **涉及未成年人色情、性暗示或任何形式的未成年人侵害内容（零容忍）；**
+   - 侮辱或者诽谤他人，侵害他人名誉、隐私和其他合法权益的内容；
+   - 其他违反法律法规、社会公德或公序良俗的内容。
+2. 不得利用平台从事任何违法犯罪活动。
+3. 不得利用技术手段攻击、干扰平台正常运营。
+4. 不得将平台生成内容用于欺诈、造谣或侵犯他人权益的用途。
+
+违反以上规定的，平台有权立即停止服务、封禁账号，且用户已使用的体验额度不予恢复。情节严重的，平台将依法向有关部门举报并配合调查。
+
+### 四、AI 生成内容
+1. 本平台基于第三方 AI 大语言模型提供服务，AI 生成的内容具有不可预测性。
+2. AI 生成的内容不构成任何形式的专业建议，包括但不限于法律、医疗、财务建议。
+3. 平台已尽合理努力对 AI 输出进行安全过滤，但无法保证所有输出内容完全合规。如您在使用过程中遇到不当内容，请及时向平台反馈。
+4. 用户不得主动诱导 AI 生成违反法律法规或本协议第三条所列的禁止性内容。
+
+### 五、用户生成内容与知识产权
+1. 平台的界面设计、代码、商标、标识等知识产权归平台所有。
+2. 用户创建的自定义剧本内容，知识产权归用户所有，但用户授予平台在运营范围内使用的许可。
+3. 用户在论坛发布的内容，视为授权平台在平台范围内展示和传播。
+4. 内容归属与授权
+
+用户在本平台论坛发布的所有内容（包括但不限于文字、图片、截图、评论等，以下统称"用户内容"），其知识产权归原始权利人所有。用户发布内容即表示：
+    - 用户保证其发布的内容为原创，或已获得合法权利人的明确授权
+    - 用户保证其发布的内容不侵犯任何第三方的著作权、商标权、肖像权、隐私权及其他合法权益
+    - 用户授予本平台在平台范围内展示、传播、存储该内容的非排他性、免费许可，该许可仅用于平台正常运营展示，不作商业转售或二次商业开发用途
+    - 用户可随时删除其发布的内容，删除后平台将在合理时间内停止展示（但因技术原因产生的缓存或备份除外）
+
+5. 用户侵权责任
+用户对其在本平台发布的全部内容承担独立且完整的法律责任：
+   - 如用户上传、发布的图片或文字侵犯了第三方的著作权、肖像权或其他合法权益，由用户自行承担全部法律责任及赔偿义务
+   - 本平台仅提供信息发布与展示的技术服务，不对用户发布内容进行事先版权审核，不对用户发布内容的合法性、真实性、准确性作任何保证
+   - 严禁用户发布以下侵权内容：
+     - 未经授权使用他人原创作品（包括但不限于绘画、摄影、文学作品、音乐等）
+     - 未经本人同意使用他人肖像、照片
+     - 未经授权使用受商标权保护的标识、品牌元素
+     - 其他任何侵犯第三方知识产权的行为
+
+6. 侵权投诉与处理
+本平台尊重知识产权，建立了以下侵权处理机制：
+   - 任何权利人如认为平台上的用户内容侵犯了其合法权益，可通过平台提供的联系方式进行投诉举报
+   - 平台在收到符合法律规定的有效侵权通知后，将及时审核并依法采取删除、屏蔽、断开链接等必要措施
+   - 被投诉用户如认为其内容不构成侵权，可提交书面反通知说明理由
+   - 对于多次侵权的用户，平台有权采取限制发布、封禁账号等措施
+7. 平台免责
+   - 平台不对用户发布的任何内容的知识产权状态作出保证或承诺
+   - 因用户发布内容引发的任何知识产权纠纷，由发布用户自行负责解决并承担一切法律后果
+   - 如因用户侵权行为导致平台遭受损失（包括但不限于赔偿金、诉讼费、律师费、商誉损失等），平台有权向该用户追偿
+
+### 六、虚拟额度说明
+1. 光点是本平台的游戏体验额度凭证，用户通过兑换码在平台兑换获得。
+2. 光点仅限在本平台内用于消耗 AI 交互次数（包括游戏行动和 NPC 对话），不具有货币属性。
+3. 光点不可转让、不可提现、不可兑换为法定货币或其他虚拟货币。
+4. 兑换码的获取方式以平台公告或官方授权渠道为准，本平台不对非官方渠道获取的兑换码承担任何责任。
+5. 因用户违反本协议被封禁账号的，账号内剩余的光点额度不予恢复。
+
+### 七、内容分级声明
+1. 本平台部分游戏剧本可能包含虚构的悬疑、惊悚、推理等文学创作元素，所有内容均为虚构，与现实无关。
+2. 平台将对含有特殊题材的剧本进行标签标注提示，用户可根据个人偏好自行选择是否体验。
+3. 本平台严禁任何涉及未成年人不当内容的剧本创作与传播，违者将被永久封禁并依法追究责任。
+
+### 八、账号安全
+1. 您有义务妥善保管账号和密码，因保管不善造成的损失由您自行承担。
+2. 平台有权对涉嫌异常操作的账号采取限制措施。
+3. 每个用户仅可注册一个账号，禁止批量注册或交易账号。
+
+### 九、服务变更与终止
+1. 平台有权根据运营需要调整、中断或终止部分或全部服务，并尽合理努力提前通知用户。
+2. 因不可抗力（包括但不限于自然灾害、政策法规变化、技术故障）导致的服务中断，平台不承担责任。
+
+### 十、免责条款
+1. 用户因自身行为导致的任何法律后果，由用户自行承担全部责任。
+2. 因 AI 模型自身特性产生的内容偏差或错误，平台不承担责任。
+3. 因第三方 API 服务商的原因导致的服务异常，平台不承担责任。
+4. 平台不对用户使用自定义API密钥产生的任何后果负责。
+
+### 十一、协议修改
+平台有权根据需要修改本协议。修改后的协议将在平台上公布，继续使用平台服务即视为接受修改后的协议。
+
+### 十二、适用法律与争议解决
+本协议适用中华人民共和国法律。因本协议引起的争议，双方应友好协商解决；协商不成的，任一方均有权向平台所在地有管辖权的人民法院提起诉讼。

miniprogram/app.js

@@ -0,0 +1,10 @@
+App({
+  globalData: {
+    launchOptions: null,
+  },
+
+  onLaunch(options) {
+    // 中文注释：保留启动参数，后续如果要把分享路径映射到 H5 深链，可以从这里统一读取。
+    this.globalData.launchOptions = options;
+  },
+});

miniprogram/app.json

@@ -0,0 +1,21 @@
+{
+  "pages": [
+    "pages/web-view/index"
+  ],
+  "window": {
+    "navigationBarTitleText": "百梦",
+    "navigationBarBackgroundColor": "#0b0f14",
+    "navigationBarTextStyle": "white",
+    "backgroundColor": "#0b0f14",
+    "backgroundTextStyle": "light"
+  },
+  "networkTimeout": {
+    "request": 60000,
+    "connectSocket": 60000,
+    "uploadFile": 60000,
+    "downloadFile": 60000
+  },
+  "permission": {},
+  "style": "v2",
+  "sitemapLocation": "sitemap.json"
+}

miniprogram/app.wxss

@@ -0,0 +1,5 @@
+page {
+  min-height: 100vh;
+  background: #0b0f14;
+  color: #f5f7fb;
+}

miniprogram/config.js

@@ -0,0 +1,28 @@
+// 中文注释：这里填写已经在“小程序后台-开发-开发设置-业务域名”配置过的 H5 入口。
+// 示例：https://game.example.com/
+// 注意：必须是 https 域名，不能是 localhost、IP 地址或未备案域名。
+const WEB_VIEW_ENTRY_URL = 'https://dev.genarrative.world/';
+
+// 中文注释：这里填写 Rust api-server 的公网 HTTPS 域名，必须在“小程序后台-开发设置-request 合法域名”中配置。
+// 如果 H5 和 API 同域，可保持和 WEB_VIEW_ENTRY_URL 同一个域名；请求路径会固定走 /api/auth/wechat/miniprogram-login。
+const API_BASE_URL = 'https://dev.genarrative.world/';
+
+// 中文注释：这里填写微信小程序 AppID，用于后端记录会话来源；project.config.json 里的 appid 也要保持一致。
+const MINI_PROGRAM_APP_ID = 'wx3da23ea14ca66b65';
+
+// 中文注释：按当前上传版本填写 develop / trial / release，后端会写入会话来源快照。
+const MINI_PROGRAM_ENV = 'develop';
+
+// 中文注释：给 H5 加一个来源标记，便于后续前端或后端识别这是微信小程序 web-view 宿主。
+const WEB_VIEW_SOURCE_QUERY = {
+  clientType: 'mini_program',
+  clientRuntime: 'wechat_mini_program',
+};
+
+module.exports = {
+  API_BASE_URL,
+  MINI_PROGRAM_APP_ID,
+  MINI_PROGRAM_ENV,
+  WEB_VIEW_ENTRY_URL,
+  WEB_VIEW_SOURCE_QUERY,
+};

miniprogram/pages/web-view/index.js

@@ -0,0 +1,349 @@
+const {
+  API_BASE_URL,
+  MINI_PROGRAM_APP_ID,
+  MINI_PROGRAM_ENV,
+  WEB_VIEW_ENTRY_URL,
+  WEB_VIEW_SOURCE_QUERY,
+} = require('../../config');
+
+const MINI_PROGRAM_CLIENT_TYPE = 'mini_program';
+const MINI_PROGRAM_CLIENT_RUNTIME = 'wechat_mini_program';
+const CLIENT_INSTANCE_STORAGE_KEY = 'genarrative:mini-program-client-instance-id';
+
+function isConfiguredEntryUrl(value) {
+  const trimmed = String(value || '').trim();
+  return /^https:\/\/[^/]+/i.test(trimmed);
+}
+
+function trimTrailingSlash(value) {
+  return String(value || '').trim().replace(/\/+$/u, '');
+}
+
+function isConfiguredApiBaseUrl(value) {
+  return /^https:\/\/[^/]+/i.test(String(value || '').trim());
+}
+
+function appendQuery(url, query) {
+  const pairs = Object.keys(query)
+    .filter((key) => query[key])
+    .map(
+      (key) =>
+        `${encodeURIComponent(key)}=${encodeURIComponent(String(query[key]))}`,
+    );
+
+  if (pairs.length === 0) {
+    return url;
+  }
+
+  return `${url}${url.includes('?') ? '&' : '?'}${pairs.join('&')}`;
+}
+
+function appendHashParams(url, params) {
+  const pairs = Object.keys(params)
+    .filter((key) => params[key])
+    .map(
+      (key) =>
+        `${encodeURIComponent(key)}=${encodeURIComponent(String(params[key]))}`,
+    );
+  if (pairs.length === 0) {
+    return url;
+  }
+
+  const hashIndex = url.indexOf('#');
+  const baseUrl = hashIndex >= 0 ? url.slice(0, hashIndex) : url;
+  const rawHash = hashIndex >= 0 ? url.slice(hashIndex + 1) : '';
+  const separator = rawHash ? '&' : '';
+  return `${baseUrl}#${rawHash}${separator}${pairs.join('&')}`;
+}
+
+function resolveWebViewUrl(authResult) {
+  const entryUrl = String(WEB_VIEW_ENTRY_URL || '').trim();
+  if (!isConfiguredEntryUrl(entryUrl)) {
+    return '';
+  }
+
+  const sourcedUrl = appendQuery(entryUrl, WEB_VIEW_SOURCE_QUERY);
+  if (!authResult || !authResult.token) {
+    return sourcedUrl;
+  }
+
+  return appendHashParams(sourcedUrl, {
+    auth_provider: 'wechat',
+    auth_token: authResult.token,
+    auth_binding_status: authResult.bindingStatus,
+  });
+}
+
+function getClientInstanceId() {
+  const stored = wx.getStorageSync(CLIENT_INSTANCE_STORAGE_KEY);
+  if (stored) {
+    return String(stored);
+  }
+
+  const nextId = `wxmp_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+  wx.setStorageSync(CLIENT_INSTANCE_STORAGE_KEY, nextId);
+  return nextId;
+}
+
+function resolveClientPlatform() {
+  const info = wx.getSystemInfoSync();
+  const platform = String(info.platform || '').toLowerCase();
+  if (platform === 'ios') {
+    return 'ios';
+  }
+  if (platform === 'android') {
+    return 'android';
+  }
+  return 'unknown';
+}
+
+function wxLogin() {
+  return new Promise((resolve, reject) => {
+    wx.login({
+      success(result) {
+        if (result.code) {
+          resolve(result.code);
+          return;
+        }
+        reject(new Error('微信登录未返回 code'));
+      },
+      fail(error) {
+        reject(new Error(error.errMsg || '微信登录失败'));
+      },
+    });
+  });
+}
+
+function requestMiniProgramLogin(code) {
+  return new Promise((resolve, reject) => {
+    const apiBaseUrl = trimTrailingSlash(API_BASE_URL);
+    if (!isConfiguredApiBaseUrl(apiBaseUrl)) {
+      reject(new Error('请先配置 API_BASE_URL'));
+      return;
+    }
+
+    wx.request({
+      url: `${apiBaseUrl}/api/auth/wechat/miniprogram-login`,
+      method: 'POST',
+      data: { code },
+      header: {
+        'content-type': 'application/json',
+        'x-client-type': MINI_PROGRAM_CLIENT_TYPE,
+        'x-client-runtime': MINI_PROGRAM_CLIENT_RUNTIME,
+        'x-client-platform': resolveClientPlatform(),
+        'x-client-instance-id': getClientInstanceId(),
+        'x-mini-program-app-id': MINI_PROGRAM_APP_ID,
+        'x-mini-program-env': MINI_PROGRAM_ENV,
+      },
+      success(response) {
+        if (response.statusCode >= 200 && response.statusCode < 300) {
+          resolve(response.data);
+          return;
+        }
+        const message =
+          response.data &&
+          response.data.error &&
+          response.data.error.message
+            ? response.data.error.message
+            : `微信登录失败：${response.statusCode}`;
+        reject(new Error(message));
+      },
+      fail(error) {
+        reject(new Error(error.errMsg || '微信登录请求失败'));
+      },
+    });
+  });
+}
+
+function requestMiniProgramBindPhone(authToken, wechatPhoneCode) {
+  return new Promise((resolve, reject) => {
+    const apiBaseUrl = trimTrailingSlash(API_BASE_URL);
+    if (!isConfiguredApiBaseUrl(apiBaseUrl)) {
+      reject(new Error('请先配置 API_BASE_URL'));
+      return;
+    }
+
+    wx.request({
+      url: `${apiBaseUrl}/api/auth/wechat/bind-phone`,
+      method: 'POST',
+      data: { wechatPhoneCode },
+      header: {
+        authorization: `Bearer ${authToken}`,
+        'content-type': 'application/json',
+        'x-client-type': MINI_PROGRAM_CLIENT_TYPE,
+        'x-client-runtime': MINI_PROGRAM_CLIENT_RUNTIME,
+        'x-client-platform': resolveClientPlatform(),
+        'x-client-instance-id': getClientInstanceId(),
+        'x-mini-program-app-id': MINI_PROGRAM_APP_ID,
+        'x-mini-program-env': MINI_PROGRAM_ENV,
+      },
+      success(response) {
+        if (response.statusCode >= 200 && response.statusCode < 300) {
+          resolve(response.data);
+          return;
+        }
+        const message =
+          response.data &&
+          response.data.error &&
+          response.data.error.message
+            ? response.data.error.message
+            : `绑定手机号失败：${response.statusCode}`;
+        reject(new Error(message));
+      },
+      fail(error) {
+        reject(new Error(error.errMsg || '绑定手机号请求失败'));
+      },
+    });
+  });
+}
+
+async function resolveAuthResult() {
+  const code = await wxLogin();
+  const response = await requestMiniProgramLogin(code);
+  if (!response || !response.token) {
+    throw new Error('服务器未返回登录态');
+  }
+  return {
+    token: response.token,
+    bindingStatus: response.bindingStatus || 'pending_bind_phone',
+  };
+}
+
+Page({
+  data: {
+    authResult: null,
+    bindingPhone: false,
+    errorMessage: '',
+    loading: true,
+    phoneBindingRequired: false,
+    webViewUrl: '',
+  },
+
+  async onLoad() {
+    // 中文注释：web-view 只能打开已配置业务域名；未配置时展示本地提示，避免空白页误判。
+    if (!isConfiguredEntryUrl(WEB_VIEW_ENTRY_URL)) {
+      this.setData({
+        errorMessage: '请先在 miniprogram/config.js 填写 WEB_VIEW_ENTRY_URL。',
+        loading: false,
+        webViewUrl: '',
+      });
+      return;
+    }
+
+    if (!isConfiguredApiBaseUrl(API_BASE_URL)) {
+      this.setData({
+        errorMessage: '请先在 miniprogram/config.js 填写 API_BASE_URL。',
+        loading: false,
+        webViewUrl: '',
+      });
+      return;
+    }
+
+    try {
+      const authResult = await resolveAuthResult();
+      if (authResult.bindingStatus === 'pending_bind_phone') {
+        this.setData({
+          authResult,
+          errorMessage: '',
+          loading: false,
+          phoneBindingRequired: true,
+          webViewUrl: '',
+        });
+        return;
+      }
+
+      this.setData({
+        authResult,
+        errorMessage: '',
+        loading: false,
+        phoneBindingRequired: false,
+        webViewUrl: resolveWebViewUrl(authResult),
+      });
+    } catch (error) {
+      this.setData({
+        authResult: null,
+        errorMessage:
+          error && error.message
+            ? error.message
+            : '微信登录失败，请稍后重试。',
+        loading: false,
+        phoneBindingRequired: false,
+        webViewUrl: '',
+      });
+    }
+  },
+
+  async handleGetPhoneNumber(event) {
+    if (!this.data.authResult || !this.data.authResult.token) {
+      this.handleRetryLogin();
+      return;
+    }
+
+    const detail = event.detail || {};
+    if (!detail.code) {
+      this.setData({
+        errorMessage: detail.errMsg || '需要授权手机号后才能完成绑定。',
+      });
+      return;
+    }
+
+    this.setData({
+      bindingPhone: true,
+      errorMessage: '',
+    });
+    try {
+      const response = await requestMiniProgramBindPhone(
+        this.data.authResult.token,
+        detail.code,
+      );
+      if (!response || !response.token) {
+        throw new Error('服务器未返回绑定后的登录态');
+      }
+      const nextAuthResult = {
+        token: response.token,
+        bindingStatus: 'active',
+      };
+      this.setData({
+        authResult: nextAuthResult,
+        bindingPhone: false,
+        errorMessage: '',
+        loading: false,
+        phoneBindingRequired: false,
+        webViewUrl: resolveWebViewUrl(nextAuthResult),
+      });
+    } catch (error) {
+      this.setData({
+        bindingPhone: false,
+        errorMessage:
+          error && error.message
+            ? error.message
+            : '绑定手机号失败，请稍后重试。',
+      });
+    }
+  },
+
+  handleRetryLogin() {
+    this.setData({
+      authResult: null,
+      bindingPhone: false,
+      errorMessage: '',
+      loading: true,
+      phoneBindingRequired: false,
+      webViewUrl: '',
+    });
+    this.onLoad();
+  },
+
+  handleWebViewLoad(event) {
+    console.info('[web-view] loaded', event.detail);
+  },
+
+  handleWebViewError(event) {
+    console.error('[web-view] load failed', event.detail);
+  },
+
+  handleWebViewMessage(event) {
+    // 中文注释：H5 如需和小程序壳通信，可通过 wx.miniProgram.postMessage 发送轻量消息。
+    console.info('[web-view] message', event.detail);
+  },
+});

miniprogram/pages/web-view/index.json

@@ -0,0 +1,3 @@
+{
+  "usingComponents": {}
+}

miniprogram/pages/web-view/index.wxml

@@ -0,0 +1,47 @@
+<block wx:if="{{webViewUrl}}">
+  <web-view
+    src="{{webViewUrl}}"
+    bindload="handleWebViewLoad"
+    binderror="handleWebViewError"
+    bindmessage="handleWebViewMessage"
+  />
+</block>
+
+<view wx:elif="{{loading}}" class="setup-screen">
+  <view class="setup-card">
+    <view class="setup-title">正在登录</view>
+  </view>
+</view>
+
+<view wx:elif="{{phoneBindingRequired}}" class="setup-screen">
+  <view class="setup-card">
+    <view class="setup-title">绑定手机号</view>
+    <view wx:if="{{errorMessage}}" class="setup-text setup-text--danger">
+      {{errorMessage}}
+    </view>
+    <button
+      class="retry-button"
+      open-type="getPhoneNumber"
+      bindgetphonenumber="handleGetPhoneNumber"
+      loading="{{bindingPhone}}"
+      disabled="{{bindingPhone}}"
+    >
+      {{bindingPhone ? '正在绑定' : '微信授权手机号'}}
+    </button>
+    <button
+      class="ghost-button"
+      disabled="{{bindingPhone}}"
+      bindtap="handleRetryLogin"
+    >
+      重新登录
+    </button>
+  </view>
+</view>
+
+<view wx:else class="setup-screen">
+  <view class="setup-card">
+    <view class="setup-title">无法进入</view>
+    <view class="setup-text">{{errorMessage}}</view>
+    <button class="retry-button" bindtap="handleRetryLogin">重试</button>
+  </view>
+</view>

miniprogram/pages/web-view/index.wxss

@@ -0,0 +1,58 @@
+.setup-screen {
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 48rpx;
+  background: #0b0f14;
+  box-sizing: border-box;
+}
+
+.setup-card {
+  width: 100%;
+  max-width: 560rpx;
+  padding: 36rpx;
+  border: 1rpx solid rgba(255, 255, 255, 0.14);
+  border-radius: 12rpx;
+  background: rgba(255, 255, 255, 0.06);
+  box-sizing: border-box;
+}
+
+.setup-title {
+  font-size: 34rpx;
+  font-weight: 600;
+  line-height: 1.35;
+  color: #f5f7fb;
+}
+
+.setup-text {
+  margin-top: 16rpx;
+  font-size: 26rpx;
+  line-height: 1.55;
+  color: rgba(245, 247, 251, 0.72);
+}
+
+.setup-text--danger {
+  color: #ffb4a9;
+}
+
+.retry-button {
+  margin-top: 28rpx;
+  width: 100%;
+  border-radius: 8rpx;
+  background: #f5f7fb;
+  color: #0b0f14;
+  font-size: 28rpx;
+  line-height: 2.6;
+}
+
+.ghost-button {
+  margin-top: 18rpx;
+  width: 100%;
+  border-radius: 8rpx;
+  border: 1rpx solid rgba(255, 255, 255, 0.24);
+  background: transparent;
+  color: rgba(245, 247, 251, 0.86);
+  font-size: 26rpx;
+  line-height: 2.6;
+}

miniprogram/sitemap.json

@@ -0,0 +1,8 @@
+{
+  "rules": [
+    {
+      "action": "allow",
+      "page": "*"
+    }
+  ]
+}

package.json

@@ -23,8 +23,10 @@
     "clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
     "check:encoding": "node scripts/check-encoding.mjs",
     "assets:child-motion-demo": "node scripts/generate-child-motion-demo-assets.mjs",
+    "assets:match3d-style-references": "node scripts/generate-match3d-style-references.mjs",
     "check:visual-novel-vn11": "node scripts/check-visual-novel-vn11-negative-scan.mjs",
     "check:visual-novel-vn12": "node scripts/check-visual-novel-vn12-acceptance.mjs",
+    "check:wechat-miniprogram-auth": "node scripts/check-wechat-miniprogram-auth-smoke.mjs",
     "check:server-rs-ddd": "node scripts/check-server-rs-ddd-boundaries.mjs",
     "lint:eslint": "eslint . --ext .ts,.tsx,.js,.mjs,.cjs --max-warnings 0",
     "lint:guardrails": "npm run lint:eslint",
@@ -36,6 +38,8 @@
     "format:check": "prettier --check .",
     "test": "vitest run",
     "test:watch": "vitest",
+    "loadtest:extract-works": "node scripts/loadtest/extract-works-list-data.mjs",
+    "loadtest:k6:works": "k6 run scripts/loadtest/k6-works-list.js",
     "check": "npm run lint && npm run test && npm run build && npm run check:content",
     "check:data": "node scripts/run-tsx.cjs scripts/validate-content.ts",
     "check:overrides": "node scripts/run-tsx.cjs scripts/validate-overrides.ts",

packages/shared/src/contracts/auth.ts

@@ -114,8 +114,9 @@ export type AuthWechatStartResponse = {
 };
 
 export type AuthWechatBindPhoneRequest = {
-  phone: string;
+  phone?: string;
-  code: string;
+  code?: string;
+  wechatPhoneCode?: string;
 };
 
 export type AuthWechatBindPhoneResponse = {
@@ -123,6 +124,16 @@ export type AuthWechatBindPhoneResponse = {
   user: AuthUser;
 };
 
+export type AuthWechatMiniProgramLoginRequest = {
+  code: string;
+};
+
+export type AuthWechatMiniProgramLoginResponse = {
+  token: string;
+  bindingStatus: AuthBindingStatus;
+  user: AuthUser;
+};
+
 export type AuthPhoneChangeRequest = {
   phone: string;
   code: string;
@@ -139,6 +150,8 @@ export type AuthRefreshResponse = {
 
 export type AuthSessionSummary = {
   sessionId: string;
+  sessionIds: string[];
+  sessionCount: number;
   clientType: string;
   clientRuntime: string;
   clientPlatform: string;

packages/shared/src/contracts/creationAudio.ts

@@ -0,0 +1,53 @@
+export type CreationAudioGenerationKind =
+  | 'background_music'
+  | 'sound_effect';
+
+export interface CreationAudioAsset {
+  taskId: string;
+  provider: string;
+  assetObjectId?: string | null;
+  assetKind?: string | null;
+  audioSrc: string;
+  prompt?: string | null;
+  title?: string | null;
+  updatedAt?: string | null;
+}
+
+export interface CreateBackgroundMusicRequest {
+  prompt: string;
+  title: string;
+  tags?: string | null;
+  model?: string | null;
+}
+
+export interface CreateSoundEffectRequest {
+  prompt: string;
+  duration?: number | null;
+  seed?: number | null;
+}
+
+export interface AudioGenerationTaskResponse {
+  kind: CreationAudioGenerationKind;
+  taskId: string;
+  provider: string;
+  status: string;
+}
+
+export interface PublishGeneratedAudioAssetRequest {
+  entityKind: string;
+  entityId: string;
+  slot: string;
+  assetKind: string;
+  profileId?: string | null;
+  storagePrefix?: 'puzzle_assets' | 'match3d_assets' | 'custom_world_scenes' | null;
+}
+
+export interface GeneratedAudioAssetResponse {
+  kind: CreationAudioGenerationKind;
+  taskId: string;
+  provider: string;
+  status: string;
+  assetObjectId?: string | null;
+  assetKind?: string | null;
+  audioSrc?: string | null;
+}

packages/shared/src/contracts/edutainmentBabyObject.ts

@@ -0,0 +1,89 @@
+export const BABY_OBJECT_MATCH_TEMPLATE_ID = 'baby-object-match';
+export const BABY_OBJECT_MATCH_TEMPLATE_NAME = '宝贝识物';
+export const BABY_OBJECT_MATCH_EDUTAINMENT_TAG = '寓教于乐';
+
+export type BabyObjectMatchTemplateId =
+  typeof BABY_OBJECT_MATCH_TEMPLATE_ID;
+
+export type BabyObjectMatchAssetProvider =
+  | 'vector-engine-gpt-image-2'
+  | 'placeholder';
+
+export type BabyObjectMatchPublicationStatus = 'draft' | 'published';
+
+export type BabyObjectMatchItemAsset = {
+  itemId: string;
+  itemName: string;
+  imageSrc: string;
+  assetObjectId: string | null;
+  generationProvider: BabyObjectMatchAssetProvider;
+  prompt: string;
+};
+
+export type BabyObjectMatchDraft = {
+  draftId: string;
+  profileId: string;
+  templateId: BabyObjectMatchTemplateId;
+  templateName: typeof BABY_OBJECT_MATCH_TEMPLATE_NAME;
+  workTitle: string;
+  workDescription: string;
+  itemNames: [string, string];
+  itemAssets: [BabyObjectMatchItemAsset, BabyObjectMatchItemAsset];
+  themeTags: string[];
+  publicationStatus: BabyObjectMatchPublicationStatus;
+  createdAt: string;
+  updatedAt: string;
+  publishedAt: string | null;
+};
+
+export type CreateBabyObjectMatchDraftRequest = {
+  itemAName: string;
+  itemBName: string;
+};
+
+export type BabyObjectMatchDraftResponse = {
+  draft: BabyObjectMatchDraft;
+};
+
+export type SaveBabyObjectMatchDraftRequest = {
+  draft: BabyObjectMatchDraft;
+};
+
+export type BabyObjectMatchPublishRequest = {
+  draft: BabyObjectMatchDraft;
+};
+
+export type BabyObjectMatchPublishResponse = {
+  draft: BabyObjectMatchDraft;
+  publicWorkCode: string;
+};
+
+export function normalizeBabyObjectMatchItemName(value: string) {
+  return value.trim();
+}
+
+export function normalizeBabyObjectMatchTags(tags: string[]) {
+  return [
+    ...new Set([
+      BABY_OBJECT_MATCH_EDUTAINMENT_TAG,
+      ...tags.map((tag) => tag.trim()).filter(Boolean),
+    ]),
+  ];
+}
+
+export function hasBabyObjectMatchRequiredTag(tags: string[]) {
+  return tags.some((tag) => tag === BABY_OBJECT_MATCH_EDUTAINMENT_TAG);
+}
+
+export function validateBabyObjectMatchItemNames(
+  payload: CreateBabyObjectMatchDraftRequest,
+) {
+  const itemAName = normalizeBabyObjectMatchItemName(payload.itemAName);
+  const itemBName = normalizeBabyObjectMatchItemName(payload.itemBName);
+
+  return {
+    itemAName,
+    itemBName,
+    valid: Boolean(itemAName && itemBName),
+  };
+}

packages/shared/src/contracts/index.ts

@@ -1,4 +1,5 @@
 export type * from './creativeAgent';
+export type * from './creationAudio';
 export type * from './hyper3d';
 export type * from './puzzleCreativeTemplate';
 export type * from './visualNovel';

packages/shared/src/contracts/match3dAgent.ts

@@ -2,7 +2,10 @@
  * 抓大鹅 Match3D 创作 Agent 共享契约。
  * 字段按 HTTP facade 的 camelCase DTO 命名，后端领域层 snake_case 字段由 facade 映射。
  */
-import type { Match3DGeneratedItemAsset } from './match3dWorks';
+import type {
+  Match3DGeneratedBackgroundAsset,
+  Match3DGeneratedItemAsset,
+} from './match3dWorks';
 
 export type Match3DCreationStage =
   | 'collecting'
@@ -34,6 +37,7 @@ export interface CreateMatch3DAgentSessionRequest {
   assetStyleId?: string | null;
   assetStyleLabel?: string | null;
   assetStylePrompt?: string | null;
+  generateClickSound?: boolean;
 }
 
 export type CreateMatch3DSessionRequest = CreateMatch3DAgentSessionRequest;
@@ -55,6 +59,7 @@ export interface ExecuteMatch3DAgentActionRequest {
   coverImageSrc?: string | null;
   clearCount?: number;
   difficulty?: number;
+  generateClickSound?: boolean;
 }
 
 export type ExecuteMatch3DActionRequest = ExecuteMatch3DAgentActionRequest;
@@ -80,6 +85,7 @@ export interface Match3DCreatorConfig {
   assetStyleId?: string | null;
   assetStyleLabel?: string | null;
   assetStylePrompt?: string | null;
+  generateClickSound?: boolean;
 }
 
 export interface Match3DResultDraft {
@@ -96,6 +102,10 @@ export interface Match3DResultDraft {
   totalItemCount?: number;
   publishReady?: boolean;
   blockers?: string[];
+  backgroundPrompt?: string | null;
+  backgroundImageSrc?: string | null;
+  backgroundImageObjectKey?: string | null;
+  generatedBackgroundAsset?: Match3DGeneratedBackgroundAsset | null;
   generatedItemAssets?: Match3DGeneratedItemAsset[];
 }
 

packages/shared/src/contracts/match3dRuntime.ts

@@ -46,6 +46,7 @@ export type Match3DClickConfirmStatus =
 
 export interface StartMatch3DRunRequest {
   profileId: string;
+  itemTypeCountOverride?: number | null;
 }
 
 export interface Match3DClickItemRequest {

packages/shared/src/contracts/match3dWorks.ts

@@ -2,6 +2,8 @@
  * 抓大鹅 Match3D 作品读写共享契约。
  * 首版作品发布必须补齐游戏名称、标签、封面、题材、消除次数和难度。
  */
+import type { CreationAudioAsset } from './creationAudio';
+
 export type Match3DWorkPublicationStatus = 'draft' | 'published' | string;
 
 export type Match3DGeneratedItemAssetStatus =
@@ -12,20 +14,93 @@ export type Match3DGeneratedItemAssetStatus =
   | 'failed'
   | string;
 
+export interface Match3DGeneratedBackgroundAsset {
+  prompt: string;
+  imageSrc?: string | null;
+  imageObjectKey?: string | null;
+  status: string;
+  error?: string | null;
+}
+
+export interface Match3DGeneratedItemImageView {
+  viewId: string;
+  viewIndex: number;
+  imageSrc?: string | null;
+  imageObjectKey?: string | null;
+}
+
 export interface Match3DGeneratedItemAsset {
   itemId: string;
   itemName: string;
   imageSrc?: string | null;
   imageObjectKey?: string | null;
+  imageViews?: Match3DGeneratedItemImageView[];
   modelSrc?: string | null;
   modelObjectKey?: string | null;
   modelFileName?: string | null;
   taskUuid?: string | null;
   subscriptionKey?: string | null;
+  soundPrompt?: string | null;
+  backgroundMusicTitle?: string | null;
+  backgroundMusicStyle?: string | null;
+  backgroundMusicPrompt?: string | null;
+  backgroundMusic?: CreationAudioAsset | null;
+  clickSound?: CreationAudioAsset | null;
+  backgroundAsset?: Match3DGeneratedBackgroundAsset | null;
   status: Match3DGeneratedItemAssetStatus;
   error?: string | null;
 }
 
+export interface PutMatch3DAudioAssetsRequest {
+  generatedItemAssets: Match3DGeneratedItemAsset[];
+}
+
+export interface PersistMatch3DGeneratedModelRequest {
+  itemId: string;
+  itemName: string;
+  sourceUrl: string;
+  fileName?: string | null;
+  taskUuid?: string | null;
+  subscriptionKey?: string | null;
+}
+
+export interface PersistMatch3DGeneratedModelResponse {
+  asset: Match3DGeneratedItemAsset;
+}
+
+export interface GenerateMatch3DCoverImageRequest {
+  prompt: string;
+  referenceImageSrc?: string | null;
+}
+
+export interface GenerateMatch3DCoverImageResponse {
+  item: Match3DWorkProfile;
+  coverImageSrc: string;
+  coverImageObjectKey: string;
+  prompt: string;
+}
+
+export interface GenerateMatch3DBackgroundImageRequest {
+  prompt: string;
+}
+
+export interface GenerateMatch3DBackgroundImageResponse {
+  item: Match3DWorkProfile;
+  backgroundImageSrc: string;
+  backgroundImageObjectKey: string;
+  generatedBackgroundAsset: Match3DGeneratedBackgroundAsset;
+  prompt: string;
+}
+
+export interface GenerateMatch3DItemAssetsRequest {
+  itemNames: string[];
+}
+
+export interface GenerateMatch3DItemAssetsResponse {
+  item: Match3DWorkProfile;
+  generatedItemAssets: Match3DGeneratedItemAsset[];
+}
+
 export interface PutMatch3DWorkRequest {
   gameName: string;
   themeText?: string;
@@ -37,6 +112,15 @@ export interface PutMatch3DWorkRequest {
   difficulty: number;
 }
 
+export interface GenerateMatch3DWorkTagsRequest {
+  gameName: string;
+  themeText: string;
+}
+
+export interface GenerateMatch3DWorkTagsResponse {
+  tags: string[];
+}
+
 export interface Match3DWorkSummary {
   workId: string;
   profileId: string;
@@ -55,6 +139,10 @@ export interface Match3DWorkSummary {
   updatedAt: string;
   publishedAt?: string | null;
   publishReady: boolean;
+  backgroundPrompt?: string | null;
+  backgroundImageSrc?: string | null;
+  backgroundImageObjectKey?: string | null;
+  generatedBackgroundAsset?: Match3DGeneratedBackgroundAsset | null;
   generatedItemAssets?: Match3DGeneratedItemAsset[];
 }