1

docs/design/PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md

@@ -34,9 +34,11 @@
 - 主视口占据顶部栏与作品信息区之间的主要空间，使用平台主题 token 控制运行容器背景、边框、阴影、加载态文字和错误态按钮；亮色主题不得残留纯黑底白字加载块。
 - 主视口下方展示当前作品的游玩、点赞、评论/改造等紧凑指标、作者头像、作者名与作品名，不写规则说明类文案。
 - 作品信息区不再提供详情箭头或点击详情入口；点击该区域无效，上滑切换下一个推荐作品，下滑切换上一个推荐作品。
+- 推荐页切换参考短视频上下滑交互：当前运行画布位于中间，上一个/下一个作品的封面预览提前挂载在画布上下屏幕外；拖动作品信息区时三屏轨道跟随位移，松手后完成切换或回弹。
 - 用户停留在推荐页时，底部当前 Tab 从“推荐”切换为“下一个”，图标使用向下的倒三角 / 双下箭头语义，点击后切换下一个推荐作品。
 - 推荐页不再展示额外的底部作品切换块；当前作品的完整操作继续收敛在详情页和作品自身运行态中。
 - 推荐页嵌入运行只调整平台外壳容器、主题注入和玩法壳层配色，不改写作品数据、关卡设定、道具设定或图片资产。
+- 屏幕外预览只允许使用公开封面、作品名和类型，不提前启动其它作品 run，不触发道具、计时、存档或作品数据变更。
 - 推荐页嵌入拼图玩法时隐藏拼图左上返回按钮，并在设置弹层中隐藏退出入口；作品切换前对当前拼图 run 执行既有“保存并退出”收口，正式 run 的交互状态以已写回后端的快照为准。
 - 点赞、改造、复制作品号等完整操作继续收敛在详情页，详情入口由作品自身运行态或其它广场列表承接，推荐页作品信息区只负责展示和上下滑切换。
 - 无数据、加载中、启动失败和暂不支持内嵌运行的作品沿用短状态文案。
@@ -90,6 +92,7 @@
 10. 推荐页作品信息区点击无效，上滑切下一个、下滑切上一个；点击底部“下一个”也切下一个作品。
 11. 仅推荐页嵌入拼图态隐藏返回与设置内退出入口；详情页、新手引导和普通拼图运行态继续保留原有退出能力。
 12. 推荐页切换作品前，如果当前作品是拼图，必须先执行当前拼图 run 的退出收口，再启动下一作品。
+13. 已登录推荐页的上/下滑切换必须展示相邻作品的屏幕外预览，并在拖动不足阈值时回弹；相邻预览不得提前启动玩法运行态。
 
 ## 8. 2026-05-07 未登录三栏补充
 

docs/technical/DEV_RUST_STACK_PORT_CONFLICT_PRECHECK_2026-05-09.md

@@ -0,0 +1,74 @@
+# 本地 Rust 栈端口冲突预检
+
+日期：`2026-05-09`
+
+## 问题
+
+执行完整本地栈启动命令时：
+
+```bash
+node scripts/run-bash-script.mjs scripts/dev-rust-stack.sh --spacetime-port 3101 --skip-spacetime
+```
+
+如果本机已有旧的 `api-server`、主站 Vite 或后台 Vite 进程仍在监听默认端口，脚本可能出现混合日志：
+
+```text
+Port 3000 is in use, trying another one...
+Error: Os { code: 10048, kind: AddrInUse }
+process didn't exit successfully: `server-rs\target\debug\api-server.exe`
+```
+
+其中 `wait_for_api_server` 只探测 `http://127.0.0.1:<api-port>/healthz`。当旧 `api-server` 仍监听 `8082` 时，健康检查会命中旧进程并误判新服务已就绪；随后新 `cargo run` 真正绑定 `8082` 时失败。与此同时，Vite 默认会在 `3000` 被占用时漂移到下一个端口，导致浏览器仍可能打开旧前端。
+
+## 处理
+
+`scripts/dev-rust-stack.sh` 在进入 SpacetimeDB publish 和 Rust 编译前，先检查三类端口是否可绑定：
+
+1. Rust `api-server`：默认 `127.0.0.1:8082`。
+2. 主站 Vite：默认 `0.0.0.0:3000`。
+3. 后台 Vite：默认 `127.0.0.1:3102`。
+
+端口被占用时，脚本会直接失败并打印监听进程。Windows 本地会通过 `Get-NetTCPConnection` 与 `Win32_Process` 输出 `pid / name / address / command`，方便精确停止旧进程。
+
+主站和后台 Vite 也追加 `--strictPort`，避免默认漂移到 `3001`、`3103` 等端口后让浏览器继续访问旧页面。
+
+## 排障步骤
+
+PowerShell 查看默认端口占用：
+
+```powershell
+Get-NetTCPConnection -State Listen -LocalPort 3000,3102,8082,3101 -ErrorAction SilentlyContinue |
+  Select-Object LocalAddress,LocalPort,OwningProcess |
+  Sort-Object LocalPort
+```
+
+查看进程命令行：
+
+```powershell
+Get-CimInstance Win32_Process |
+  Where-Object { $_.ProcessId -in @(3000端口PID, 8082端口PID) } |
+  Select-Object ProcessId,Name,CommandLine
+```
+
+停止确认可丢弃的旧本地开发进程：
+
+```powershell
+Stop-Process -Id <pid> -Force
+```
+
+如果确实需要保留旧栈，可显式换端口启动新栈：
+
+```bash
+node scripts/run-bash-script.mjs scripts/dev-rust-stack.sh \
+  --skip-spacetime \
+  --spacetime-port 3101 \
+  --api-port 8090 \
+  --web-port 3001 \
+  --admin-web-port 3103
+```
+
+## 验证
+
+1. `bash -n scripts/dev-rust-stack.sh` 通过。
+2. 默认端口被占用时重新运行完整栈，脚本应在 publish 前失败并打印占用进程。
+3. 清理占用进程或换端口后，重新启动时不再出现 Vite 端口漂移或 `api-server` `AddrInUse`。

docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md

@@ -20,7 +20,7 @@
 
 1. 玩家在创作页点击“拼图”入口时，前端必须立即创建一个新的拼图 Agent session，并同步生成一条 `publicationStatus = draft` 的拼图作品卡；此时不触发 `compile_puzzle_draft`，不生成图片，不进入生成进度页。
 2. 新 session 的 `seedText` 允许为空；SpacetimeDB 侧用空锚点和空表单草稿初始化，不得把默认题材文案写入玩家草稿字段。
-3. 初始表单输入自动保存到 session 的 `draft_json` 与 `puzzle_work_profile` 投影。保存字段只包含 `workTitle`、`workDescription`、`pictureDescription`、可推断标签和一个 `generationStatus = idle` 的默认关卡；草稿设置阶段默认关卡名称必须为空，不得写入“第一关”“第1关”或作品名称作为默认值。参考图只保存在当前前端会话内，不落入 SpacetimeDB。
+3. 初始表单输入自动保存到 session 的 `draft_json` 与 `puzzle_work_profile` 投影。保存字段只包含 `workTitle`、`workDescription`、`pictureDescription`、可推断标签和一个 `generationStatus = idle` 的默认关卡；草稿设置阶段默认关卡名称必须为空，不得写入“第一关”“第1关”或作品名称作为默认值。生成前的参考图只保存在当前前端会话内；一旦用于首图生成并成功返回，后端必须把该参考图写入首关 `pictureReference`，供结果页后续重新生成继续复用。
 4. 玩家在生成草稿前退出，再次从创作中心点击这条拼图草稿时，必须恢复到填表页，并回填之前自动保存的作品名称、作品描述和画面描述；只有执行 `compile_puzzle_draft` 且生成结果页草稿后，草稿入口才进入结果页。
 5. 表单自动保存走 `save_puzzle_form_draft` action，不消耗光点，不生成图片，不改变 `stage = collecting_anchors`；生成草稿按钮仍单独触发 `compile_puzzle_draft` 并进入进度页。
 6. 点击拼图入口始终创建新草稿，不复用上一次未完成 session；恢复旧草稿只通过“我的创作”中的草稿卡进入。

docs/technical/README.md

@@ -5,6 +5,7 @@
 ## 文档列表
 
 - [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 差异。
+- [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 通信异常阻断时的根因、`dev-rust-stack` 自动降级策略和手动排障命令。
 - [AUTH_RESTORE_AND_RECOMMEND_LOADING_FIX_2026-05-09.md](./AUTH_RESTORE_AND_RECOMMEND_LOADING_FIX_2026-05-09.md)：记录刷新网页后登录态失效和推荐页作品卡卡在加载中的联合修复，覆盖 `AuthGate` 本地 token 优先恢复、refresh 失败不清 token、推荐页启动请求版本保护和错误态收口。

docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md

@@ -80,6 +80,7 @@ VectorEngine 文档要求使用像素尺寸，不再使用 APIMart 的比例写
    - 拼图默认 `gpt-image-2` 前端值继续兼容，但上游请求模型统一映射到 `gpt-image-2-all`。
    - `nanobanana2` / `gemini-3.1-flash-image-preview` 不再走 APIMart；当前阶段统一回落到 VectorEngine GPT-image-2-all，避免保留旧图片网关。
    - 错误 `details.provider` 改为 `vector-engine`。
+   - 入口页上传图若用于首图生成，后端必须在生成成功后同步写入首关 `pictureReference`，保证结果页重新生成默认继续带同一张参考图。
 3. `.codex/skills/gpt-image-2-apimart/`
    - 目录名暂不强制迁移，避免本地插件索引漂移；Skill 文案与脚本行为改为 VectorEngine。
 
@@ -110,7 +111,18 @@ VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=180000
 2. 请求体 `model = gpt-image-2-all`，尺寸为 VectorEngine 支持的像素尺寸。
 3. 请求体不再包含 `official_fallback`。
 4. 参考图字段使用 `image`，不再使用 APIMart 的 `image_urls`。
-5. 缺少 `VECTOR_ENGINE_BASE_URL` 或 `VECTOR_ENGINE_API_KEY` 时返回 `503 SERVICE_UNAVAILABLE`，`details.provider = "vector-engine"`。
-6. 上游错误映射为 `502 UPSTREAM_ERROR`，保留 `upstreamStatus`、业务 message 和截断后的 raw excerpt。
-7. 运行 `npm run check:encoding`、`cargo test -p api-server openai_image --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server puzzle --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server custom_world_ai --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server character_visual --manifest-path server-rs/Cargo.toml`。
-8. 后端改动后使用 `npm run api-server` 重启，并确认 `/healthz`。
+5. 拼图入口页上传图生成首图后，返回的首关 `pictureReference` 保留该 Data URL；结果页重新生成在用户未重新上传参考图时会继续把 `pictureReference` 作为 `referenceImageSrc` 传给后端。
+6. 缺少 `VECTOR_ENGINE_BASE_URL` 或 `VECTOR_ENGINE_API_KEY` 时返回 `503 SERVICE_UNAVAILABLE`，`details.provider = "vector-engine"`。
+7. 上游错误映射为 `502 UPSTREAM_ERROR`，保留 `upstreamStatus`、业务 message 和截断后的 raw excerpt。
+8. 运行 `npm run check:encoding`、`cargo test -p api-server openai_image --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server puzzle --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server custom_world_ai --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server character_visual --manifest-path server-rs/Cargo.toml`。
+9. 后端改动后使用 `npm run api-server` 重启，并确认 `/healthz`。
+
+## 拼图链路排障日志
+
+拼图 `compile_puzzle_draft` 与 `generate_puzzle_images` 进入图片生成时，api-server 会输出分阶段耗时日志。排查“是谁慢”时按同一 `session_id` 串联：
+
+1. `拼图参考图解析完成` / `拼图参考图解析跳过`：确认前端是否传入参考图，以及 Data URL 解析或旧 `/generated-*` OSS 读取耗时；日志只记录 `reference_mime` 与 `reference_bytes`，不记录图片内容。
+2. `拼图 VectorEngine 图片生成 HTTP 返回`：VectorEngine `POST /v1/images/generations` 的同步上游耗时，若这一段长，慢点在 VectorEngine 生图接口。
+3. `拼图 VectorEngine 图片下载完成`：从 VectorEngine 返回的 `data[].url` 下载正式图耗时。
+4. `拼图生成图片已写入 OSS 与资产索引`：正式图上传 OSS、确认资产对象与实体绑定耗时。
+5. `拼图图片候选生成完成`：整段候选图生成总耗时。

docs/technical/VOLCENGINE_SPEECH_STREAMING_INTEGRATION_2026-05-08.md

@@ -35,7 +35,7 @@ VOLCENGINE_SPEECH_TTS_SSE_URL=https://openspeech.bytedance.com/api/v3/tts/unidir
 配置规则：
 
 1. 优先使用新版控制台 `VOLCENGINE_SPEECH_API_KEY`，上游请求头写 `X-Api-Key`。
-2. 若只配置旧版控制台信息，则使用 `VOLCENGINE_SPEECH_APP_ID` 和 `VOLCENGINE_SPEECH_ACCESS_KEY`。
+2. 若只配置旧版控制台信息，则使用 `VOLCENGINE_SPEECH_APP_ID` 和 `VOLCENGINE_SPEECH_ACCESS_KEY`，上游请求头写 `X-Api-App-Key` 与 `X-Api-Access-Key`。
 3. ASR 默认资源 ID 选 ASR 2.0 并发版；如账号是小时版，部署时改成 `volc.seedasr.sauc.duration`。
 4. TTS 默认资源 ID 选 `seed-tts-2.0`；旧音色或 1.0 计费资源由部署环境覆盖。