合并 master 并保留外部生成 worker 模式

合入 master 的生产健康巡检、JumpHop 和 SpacetimeDB 更新
保留外部生成 worker、队列/内联模式与 lease guard 口径
合并 Server-Provision 工具复用、health patrol 和外部生成 worker systemd 配置
补齐 SpacetimeDB 生成绑定并通过本地检查

.hermes/shared-memory/pitfalls.md

@@ -47,6 +47,22 @@
 - 验证：`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server asset_operation_billing_does_not_refund_stale_worker_lease_errors --manifest-path server-rs/Cargo.toml`，并在 smoke 时确认 queued 任务被 worker 消费后 session 真实更新。
 - 关联：`server-rs/crates/api-server/src/puzzle/draft.rs`、`server-rs/crates/api-server/src/puzzle/generation.rs`、`server-rs/crates/api-server/src/external_generation_worker.rs`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`。
 
+## 生产冷备份后 API 不能只依赖 SpacetimeDB 自恢复
+
+- 现象：release 机器 `03:20` 冷备份后，`spacetimedb.service` 已恢复，但作品列表、创作入口配置或公开 gallery 继续超时 / 502 / 504，`genarrative-api.service` 保持 stopped。
+- 原因：`genarrative-api.service` 配置了 `Requires=spacetimedb.service`，冷备份停止 `spacetimedb.service` 时 API 会被 systemd 依赖关系一并停止；如果 `genarrative-database-backup.service` 只传 `--stop-service spacetimedb.service` 而漏掉 `--restart-service-after genarrative-api.service`，备份脚本只会恢复数据库，不会再拉起 API。
+- 处理：生产冷备份 unit 和发布脚本必须带 `--restart-service-after genarrative-api.service`；仓库用 `npm run check:production-ops` 检查 systemd 模板、API build/deploy 归档和健康巡检链路。现场修复后执行 `systemctl daemon-reload`，但不要为了验证而手动触发冷备份。
+- 验证：`systemctl cat genarrative-database-backup.service` 应包含该参数；`systemctl is-active spacetimedb.service genarrative-api.service nginx.service` 全为 `active`；`curl -fsS http://127.0.0.1:3101/v1/ping`、`/healthz`、`/readyz` 和代表性 `/api/runtime/puzzle/gallery` 均成功。
+- 关联：`deploy/systemd/genarrative-database-backup.service`、`scripts/database-backup-to-oss.mjs`、`scripts/ops/production-health-patrol.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## SpacetimeDB 45 秒超时要看 api-server 记录的阶段
+
+- 现象：release 上 Nginx 能立刻连到 `api-server`，但 `/api/runtime/*/gallery`、`/api/creation-entry/config` 等请求在约 `GENARRATIVE_SPACETIME_PROCEDURE_TIMEOUT_SECONDS` 后返回 `502` / `504`。
+- 原因：旧日志只能看到 HTTP 总耗时和最终状态，无法区分卡在连接池、SDK 建连、等待 `on_connect`、订阅 read model、等待 procedure / reducer 回调还是本地订阅 cache 读取。
+- 处理：`spacetime-client` 内置阶段化健康检查和失败日志；`/readyz` 用 `GENARRATIVE_SPACETIME_HEALTH_CHECK_TIMEOUT_SECONDS` 短窗口检查 SpacetimeDB 连接租约，业务失败日志包含 `operation_kind`、`operation_name`、`spacetime_stage`、`elapsed_ms`。
+- 验证：`/readyz` 失败时看 `details.spacetime.stage`；业务请求超时时查 `journalctl -u genarrative-api.service` 中同一时间窗口的 `SpacetimeDB client operation failed`，优先按 `pool_acquire`、`connect_build`、`connect_handshake`、`read_model_subscribe`、`procedure_result`、`reducer_result`、`read_cache` 分阶段处理。
+- 关联：`server-rs/crates/spacetime-client/src/lib.rs`、`server-rs/crates/api-server/src/health.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 新建草稿扣费不能和入口卡泥点配置分离
 
 - 现象：后台修改创作入口的 `mudPointCost` 后，入口卡和前置余额提示可能显示新数值，但用户真实钱包流水仍按代码常量扣除。
@@ -103,13 +119,13 @@
 - 验证：`CreationAgentWorkspace` 测试应断言进度标题、百分比和提示文本带专属 class；`src/index.test.ts` 应断言这些 class 在 remap surface 内有白色覆盖规则；移动端截图中暗色卡片文字应保持可读。
 - 关联：`src/components/creation-agent/CreationAgentWorkspace.tsx`、`src/components/creation-agent/CreationAgentWorkspace.test.tsx`、`src/index.css`、`src/index.test.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
-## VectorEngine 图片生成 SendRequest 超时要按传输失败排查
+## VectorEngine 图片生成 request_send 传输错误要按可重试网络抖动排查
 
-- 现象：`external_api_call_failure` 里看到 `failureStage=request_send`、`timeout=true`、`statusCode=null`，`errorSource` 可能是 `client error (SendRequest)` 或更完整的 reqwest 底层错误链，前端只知道图片生成失败。
-- 原因：`timeout=true` 来自 `reqwest::Error::is_timeout()`，不是业务代码固定写死；`SendRequest` 是 Hyper 发送请求阶段的错误来源标签，只说明请求未拿到可归类的 HTTP 响应，不会包含上游 JSON 错误体。
-- 处理：先按 `provider/failureStage/statusClass` 聚合，再用 `user_id` / `profile_id` 和 `metadata_json.userId/profileId/requestId` 定位触发者、草稿 / 作品和同一次 HTTP 请求；`request_send + timeout=true` 优先查 provider 日志的 `source_chain`、请求体大小、参考图数量、出口网络、代理/Nginx、VectorEngine 当时可用性和同一 request_id 日志。当前 `platform-image` 对 `request_send` 的 `timeout` / `connect` 错误最多重试 3 次，multipart `/v1/images/edits` 每次重试都必须重建 form；看到 `VectorEngine 图片请求发送失败，准备重试` 只是单次 attempt 失败，最终 `external_api_call_failure` 才代表该用户请求整体失败。若记录有 `502` 或 `429 moderation_blocked`，按上游网关或审核失败另行处理，不要归到传输超时。
+- 现象：`external_api_call_failure` 里看到 `failureStage=request_send`、`statusCode=null`，`errorSource` 可能是 `client error (SendRequest)`、`[35] SSL connect error (Recv failure: Connection reset by peer)`、`[56] Failure when receiving data from the peer (... unexpected eof while reading ...)`；也可能看到 `failureStage=upstream_status`、`statusCode=502`、错误体是 Nginx HTML `502 Bad Gateway`。前端只知道图片生成失败。
+- 原因：`request_send` 表示请求未拿到可归类的 HTTP 响应，不会包含上游 JSON 错误体；`upstream_status=502/5xx/429/408` 表示拿到了上游错误响应但仍属于可重试的过载 / 网关抖动。`timeout=true` 来自超时判定，`connect=true` 会同时覆盖 DNS / connect 失败以及 libcurl 35 SSL 握手、libcurl 56 收包提前 EOF、connection reset 这类临时传输错误。
+- 处理：先按 `provider/failureStage/statusClass` 聚合，再用 `user_id` / `profile_id` 和 `metadata_json.userId/profileId/requestId` 定位触发者、草稿 / 作品和同一次 HTTP 请求；`request_send + timeout/connect=true` 或 `upstream_status + statusCode=408/429/5xx` 优先查 provider 日志的 `source_chain`、请求体大小、参考图数量、出口网络、代理/Nginx、VectorEngine 当时可用性和同一 request_id 日志。当前 `platform-image` 对 request_send 的 timeout / connect / SSL connect reset / recv error / unexpected eof / send error，以及 upstream_status 的 408 / 429 / 5xx 最多发送 5 次，multipart `/v1/images/edits` 每次重试都会重新构造 form；看到 `VectorEngine 图片请求发送失败，准备重试` 或 `VectorEngine 图片上游状态可重试，准备重试` 只是单次 attempt 失败，最终 `external_api_call_failure` 才代表该用户请求整体失败。若记录有 `429 moderation_blocked` 或明确审核错误，按审核失败另行处理，不要归到网络抖动。
 - 拼图关卡资产生成按 `level_scene -> ui_spritesheet -> level_background` 顺序执行，每个资产会输出 `slot`、`asset_kind`、`elapsed_ms`；排查拼图草稿失败时优先看同一 request_id 下最后一个失败 slot。
-- 验证：`cargo test -p platform-image --manifest-path server-rs/Cargo.toml vector_engine_image_edit_retries_send_timeout_once_and_succeeds`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`；查询 `tracking_event` 时失败记录应能看到触发者 `user_id` 和可用的 `profile_id`。
+- 验证：`cargo test -p platform-image --manifest-path server-rs/Cargo.toml vector_engine_send_retry_policy -- --nocapture`、`cargo test -p platform-image --manifest-path server-rs/Cargo.toml vector_engine_image_edit_retries_send_timeout_once_and_succeeds`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`；查询 `tracking_event` 时失败记录应能看到触发者 `user_id` 和可用的 `profile_id`。
 - 关联：`server-rs/crates/platform-image/src/vector_engine/client.rs`、`server-rs/crates/api-server/src/external_api_audit.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
 ## “我的”页每日任务卡不要硬编码进度，也不要跨日保留旧状态
@@ -489,6 +505,14 @@
 - 验证：未登录推荐页可以直接进入跳一跳运行态，且 `work_play_start` 事件仍会落库或出现在 outbox 中，metadata 含匿名标记。
 - 关联：`server-rs/crates/api-server/src/jump_hop.rs`、`server-rs/crates/api-server/src/auth.rs`、`server-rs/crates/api-server/src/work_play_tracking.rs`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`。
 
+## 跳一跳直接打开空 runtime 路由不能停在加载态
+
+- 现象：直接访问 `/runtime/jump-hop` 时页面看起来一直停在“正在载入游戏 / 正在加载内容”，DOM 内部只有空的跳一跳运行态，没有平台、地块或 run 数据。
+- 原因：`appPageRoutes` 会把该路径解析为 `jump-hop-runtime`，但裸路径没有 `work=JH-*` 公开作品码，也没有从详情页启动后写入的 `jumpHopRun`，平台壳仍挂载 `JumpHopRuntimeShell`。
+- 处理：平台壳在 `jump-hop-runtime` 且缺少 run 时先看 `work` 参数；有 `JH-*` 则通过公开 gallery detail 回读 profile 并启动 published run，没有则回到平台首页。全局作品码恢复 effect 在跳一跳 runtime 阶段要跳过，避免和运行态恢复互相抢路由。
+- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "direct jump hop runtime route"`；浏览器 smoke 分别打开 `/`、`/runtime/jump-hop` 和 `/runtime/jump-hop?work=JH-*`。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/routing/appPageRoutes.ts`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`。
+
 ## release tracking outbox 权限错误先查 env 缺失
 
 - 现象：release 机器 `journalctl -u genarrative-api.service` 每秒刷 `tracking outbox 定时封存 active 文件失败 error=Permission denied (os error 13)` 和 `tracking outbox 批量写入 SpacetimeDB 失败`。
@@ -1143,6 +1167,8 @@
 - 现象：刷新网页后，用户明明有本地 access token，却回到未登录状态。
 - 原因：`AuthGate` hydrate 曾先强制调用 `refreshStoredAccessToken()`；当 refresh cookie 临时失效、代理错配或后端返回 `401` 时，该方法会先清空本地 access token，随后 `/api/auth/me` 只能恢复成未登录。
 - 处理：`refreshStoredAccessToken()` 增加 `clearOnFailure` 选项；`AuthGate` 在已有本地 access token 时先用 `/api/auth/me` 确认用户，确认成功后再后台 refresh 续期与写每日登录埋点，后台 refresh 失败不清 token。
+- 追加处理：`/api/auth/refresh` 只有明确返回 `401` / `403` 时才代表登录态权威失效，可以清本地 access token 并触发全局 auth 变化；服务器重启、Nginx 502/503/504、浏览器 `Failed to fetch` 或 refresh 响应契约异常都属于暂时不可用，不能把已有本地 token 清掉，否则重启窗口会把所有打开页面踢成未登录。
+- 契约：`/api/auth/refresh` 成功响应按共享契约 `RefreshSessionResponse { token }` 解析；测试 mock 不要额外塞 `{ ok: true, token }` 遮住真实恢复路径。
 - 验证：`npm run test -- src/services/apiClient.test.ts src/components/auth/AuthGate.test.tsx -t "explicit refresh opts out|auth gate keeps a valid local token login"`。
 - 关联：`src/services/apiClient.ts`、`src/components/auth/AuthGate.tsx`、`docs/technical/AUTH_RESTORE_AND_RECOMMEND_LOADING_FIX_2026-05-09.md`。
 
@@ -1338,6 +1364,14 @@
 - 验证：Jenkins 日志中 `Provision Target` 下的 `Prepare`、`Checkout Provision Files`、`Prepare Provision Tools` 和 `Provision Server` 都应运行在目标 dev / release agent；日志不应出现 `stash 'server-provision-tools'`、目标阶段 `unstash`、`Git 主地址拉取失败...改用备用地址` 或 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。
 - 关联：`jenkins/Jenkinsfile.production-server-provision`、`scripts/prepare-server-provision-tools.sh`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
+## Server-Provision 不要无条件下载工具包
+
+- 现象：目标 dev / release 机器已经安装正确版本的 SpacetimeDB 或 `otelcol-contrib`，但 `Prepare Provision Tools` 仍每次下载 release tarball，网络慢或 GitHub 不稳时会把服务器初始化卡在准备阶段。
+- 原因：工具准备阶段如果只按“生成交付包”理解，会忽略它已经运行在目标部署 agent 上这一事实；此时目标机本地的 `/usr/local/bin/otelcol-contrib` 与 `${SPACETIME_ROOT}/bin/current` 就是可信状态源。
+- 处理：`scripts/prepare-server-provision-tools.sh` 必须先检查目标机状态：`otelcol-contrib --version` 命中 `OTELCOL_VERSION` 时复制现有二进制；`spacetimedb-cli --version` 命中 `SPACETIME_EXPECTED_VERSION` 或 `SPACETIME_DOWNLOAD_ROOT` 推导出的版本且 standalone 同时存在时，复制 `${SPACETIME_ROOT}/bin` 并生成 wrapper。只有缺失、不可执行或版本不匹配时，才查 `PROVISION_DOWNLOADS_DIR` 或下载源。
+- 验证：运行 `bash scripts/check-server-provision-tools.sh`；Jenkins 日志应先出现“检查目标机 ...”，已有版本命中时出现“复用目标机已有 ...”，且不出现“下载 ...”。
+- 关联：`scripts/prepare-server-provision-tools.sh`、`jenkins/Jenkinsfile.production-server-provision`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## 个人任务 scope 不得扩成 work/site/module
 
 - 现象：个人任务配置为 `work` / `site` / `module` 后进度串桶或静默按 0 处理。
@@ -1772,18 +1806,18 @@
 - 验证：`npm run typecheck`，并跑 `npm test -- src/routing/appPageRoutes.test.ts` 覆盖 JumpHop 阶段路径。
 - 关联：`src/components/platform-entry/platformEntryTypes.ts`、`src/routing/appPageRoutes.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
-## 跳一跳地块图集固定走 5x5 地块池
+## 跳一跳地块图集固定走 18 个 UV 大单元
 
 - 现象：跳一跳初始草稿生成时报 `系列素材图集的物品行数不能超过 n。`，或者生成完成后只有 atlas 预览路径，地块切片没有真正落盘。
-- 原因：旧模板先后尝试过通用系列素材 helper 和 `2x3` 六格固定 tileType，但当前跳一跳已经重设计为“主题 -> 5x5 地块图集 -> 25 个等权地块池 -> 无限路径”，旧的物品行数 / 固定类型模型都会把创作链路带偏。
-- 处理：跳一跳地块固定生成一张 `5x5` 主题图集，后端按均匀网格切出 25 张 PNG，并对每张切片各自走 OSS 上传、asset_object 确认和 entity bind；不要再恢复 `2行*3列`、`start / normal / target / finish / bonus / accent` 六格口径。
-- 验证：`jump_hop.rs` 不应再调用通用物品行数模型处理地块图集；公开结果里应能拿到 25 个独立 `JumpHopTileAsset`，运行态无限路径从地块池随机取材。
+- 原因：旧模板先后尝试过通用系列素材 helper、`2x3` 六格固定 tileType 和 `5x5` 单贴图池，但当前跳一跳已经重设计为“主题 -> 一张 `1024x1536` 图集 -> 18 个 `3列*6行` UV 大单元 -> 每格 `4列*3行` 六面贴图 -> 无限路径”，旧的物品行数 / 固定类型模型都会把创作链路带偏。
+- 处理：跳一跳地块固定只生成一张 `1024x1536` 主题 UV 展开图集，后端先切出 18 个大单元，再从每格固定 UV 网切出 top/front/right/back/left/bottom 六张 `256x256` 不透明 PNG，并对 108 张面贴图各自走 OSS 上传、asset_object 确认和 entity bind；不要再恢复 `2行*3列`、`5x5` 单贴图、`start / normal / target / finish / bonus / accent` 六格口径。
+- 验证：`jump_hop.rs` 不应再调用通用物品行数模型处理地块图集；公开结果里应能拿到 18 个独立 `JumpHopTileAsset` 且每个新资产包含 `faceAssets` 六面贴图，运行态无限路径从地块池随机取材；旧资产没有 `faceAssets` 时仍能用 `imageSrc` 单贴图 fallback。
 - 关联：`server-rs/crates/api-server/src/jump_hop.rs`、`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
 ## 跳一跳宝可梦主题地块图集 safety rejection 只做专项改写
 
 - 现象：跳一跳草稿使用“宝可梦 / Pokemon / 皮卡丘 / 精灵球”等主题时，背景底图和返回按钮可能已生成成功，但地块图集的 VectorEngine 请求返回 `Your request was rejected by the safety system`，日志里 `failure_context="跳一跳地块图集生成失败"`、`status=429`、`code="invalid_prompt"`。
-- 原因：25 个落点图集 prompt 会把这些词放进“主题物体图集”语境，容易被上游理解为要求生成具体宝可梦角色或标志道具，触发安全拦截；这不是普通平台造型词、抠图或超时问题。
+- 原因：18 个立方体主题物体 UV 展开图集 prompt 会把这些词放进“主题物体图集”语境，容易被上游理解为要求生成具体宝可梦角色或标志道具，触发安全拦截；这不是普通平台造型词、抠图或超时问题。
 - 处理：仅在跳一跳图片生成 prompt 文本命中宝可梦相关词时做生成侧替换，把 `宝可梦 / 神奇宝贝 / 口袋妖怪 / Pokemon` 改为“原创幻想萌宠冒险道具”，把 `精灵球` 改为“彩色冒险能量球”，把 `皮卡丘 / Pikachu` 改为“黄色闪电萌宠符号”；不要把所有主题都加全局 IP 禁止约束，用户草稿标题和主题展示也不改。
 - 验证：`cargo test -p api-server jump_hop --manifest-path server-rs/Cargo.toml` 应覆盖宝可梦词专项替换；真实联调时同一草稿重试后，地块图集请求的 prompt 不再包含宝可梦相关词。
 - 关联：`server-rs/crates/api-server/src/jump_hop.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
@@ -1791,9 +1825,9 @@
 ## 跳一跳地块切片不要按 tileType 复用资产槽位
 
 - 现象：跳一跳生成完成后，运行态看起来仍像在显示默认几何地块，或者地块图片在加载时频闪；结果页地块池也可能只看到少量重复素材。
-- 原因：`tileType` 只是路径平台的玩法类型标签，25 个 atlas 切片里会重复出现 `normal / target / bonus / accent` 等类型。若后端持久化时用 `tileType` 生成 slot/path，同类型切片会写入同一个 `/generated-jump-hop-assets/<profile>/<slot>/image.png`，后上传的切片覆盖先上传的切片，前端换签缓存也会读到重复或旧对象。
-- 处理：后端切图后必须按 atlas 单元格写入 `tile-01` 到 `tile-25` 的唯一 slot/path；前端结果页和运行态展示生成图时用 `assetObjectId` 作为 `refreshKey`，避免重生成后复用旧签名或旧图片缓存。
-- 验证：`cargo test -p api-server jump_hop --manifest-path server-rs/Cargo.toml -- --nocapture` 应包含 `jump_hop_tile_asset_slots_are_unique_for_twenty_five_slices`；前端运行态测试应断言地块换签带 `assetObjectId` 刷新键。
+- 原因：`tileType` 只是路径平台的玩法类型标签，18 个 atlas 大单元里会重复出现 `normal / target / bonus / accent` 等类型。若后端持久化时用 `tileType` 生成 slot/path，同类型切片会写入同一个 `/generated-jump-hop-assets/<profile>/<slot>/image.png`，后上传的切片覆盖先上传的切片，前端换签缓存也会读到重复或旧对象。
+- 处理：后端切图后必须按 atlas 单元格写入 `tile-01` 到 `tile-18` 的唯一 tile slot，并把六面贴图写入 `tile-XX-top/front/right/back/left/bottom` 唯一 face slot；前端结果页和运行态展示生成图时用 `assetObjectId` 作为 `refreshKey`，避免重生成后复用旧签名或旧图片缓存。
+- 验证：`cargo test -p api-server jump_hop --manifest-path server-rs/Cargo.toml -- --nocapture` 应包含 `jump_hop_tile_asset_slots_are_unique_for_eighteen_slices`；前端运行态测试应断言地块换签带 `assetObjectId` 刷新键，并覆盖新 UV 资产会解析六张面贴图。
 - 关联：`server-rs/crates/api-server/src/jump_hop.rs`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`src/components/jump-hop-result/JumpHopResultView.tsx`。
 
 ## 跳一跳落点辅助标识不要再用舞台高度常量拍脑袋投影
@@ -1804,12 +1838,12 @@
 - 验证：拖拽半程时辅助点应落在当前地块和目标地块之间，完整拖拽时应逼近目标地块中心；运行态截图里辅助点必须始终压在地块与角色之上。
 - 关联：`src/services/jump-hop/jumpHopRuntimeModel.ts`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`。
 
-## 跳一跳落点辅助和后端裁决必须统一坐标换算
+## 跳一跳长按蓄力不能再消费拖拽方向
 
-- 现象：落点辅助标识已经压在目标地块图片上，松手后后端仍判定失败，玩家看到的是“明明瞄准了却没落上去”。
-- 原因：前端辅助标识使用屏幕像素坐标绘制，而后端裁决使用世界坐标。屏幕 y 轴向下为正、世界 y 轴向上为正；同时屏幕 x/y 每个世界单位对应的像素比例不同。若前端直接把屏幕像素拖拽向量发给后端，辅助点和后端落点方向会不一致。
-- 处理：前端运行态保留原始屏幕拖拽向量用于画弹弓和辅助点，但提交后端前必须按当前地块到目标地块的屏幕跨度 / 世界跨度把 x、y 分别换算成世界尺度一致的向量；后端继续只负责反向弹射和落点裁决。
-- 验证：前端回归测试要同时覆盖辅助点完整拖拽到目标地块，以及提交给后端的向量已完成世界尺度换算；后端领域测试覆盖屏幕向后下拉时应向世界 y 正方向跳出并命中。
+- 现象：跳一跳改成长按蓄力后，如果前端或后端仍消费 `dragVectorX/dragVectorY`，玩家手指轻微移动就会改变跳跃方向，和“始终朝下一块中心跳”的体验不一致。
+- 原因：历史弹弓拖拽版本把屏幕拖拽方向作为正式裁决输入，契约字段仍为兼容旧客户端保留，容易被误认为仍是当前玩法规则。
+- 处理：前端运行态只用长按时长提交 `dragDistance` 兼容字段，不再发送方向字段；落点预测按当前地块中心到下一块地块中心的方向投影。后端 `module-jump-hop` 即使收到旧客户端 `dragVectorX/dragVectorY` 也必须忽略，只按当前地块到下一块地块中心的单位向量裁决。
+- 验证：前端回归测试覆盖手指移动不改变提交方向、预测落点忽略旧方向字段；后端领域测试覆盖旧客户端传错误方向时仍按下一块中心命中。
 - 关联：`src/services/jump-hop/jumpHopRuntimeModel.ts`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`server-rs/crates/module-jump-hop/src/application.rs`。
 
 ## 跳一跳创作入口旧文案先查 SpacetimeDB 配置
@@ -2087,24 +2121,32 @@
 
 - 现象：跳一跳松手后如果后端很快返回下一帧 run，地块窗口会立刻前移，角色翻腾动画看起来像没播放；若同时刷新图片资产，还可能被误认为地块频闪。
 - 原因：后端 run 是规则真相，前端 runtime 又需要低延迟表现。如果 DOM 平台层直接用最新 `run.currentPlatformIndex` 渲染，后端回包会抢在动画前完成视觉切换。
-- 处理：前端保留独立 `displayRun`，松手后先进入 `isJumpAnimating=true`，角色在当前窗口内插值飞向目标地块；约 `300ms` 后再把 `displayRun` 切到最新后端 run，并进入约 `1440ms` 的 `platformAdvancing` 表现态。推进期间地块 DOM 层和 Three.js 角色层必须统一包在同一个 camera layer 下移动，旧当前地块用相机偏移自然离开视野，新预览地块从上方露出；不要再让 p1/p2 各自 top/left 过渡。相机层必须同时设置 `--jump-hop-camera-shift-x` 与 `--jump-hop-camera-shift-y`，从旧目标地块位置斜向滑到新当前地块聚焦位置，避免先横向瞬切居中再纵向推进。地块保留当前 / 目标 / 预览的深度尺寸差异，但深度差异必须用固定宽高 + CSS transform scale 缓动实现，不能直接改宽高瞬切；当前态不要额外叠 CSS scale。相机推进期间角色自身也不能保留 `left/top` transition，否则 `displayRun` 切换造成的角色局部坐标变更会和父级 camera layer 位移叠加，视觉上像落地后又从屏幕外飞回；角色推进期只允许 transform / opacity transition。正式胜负、成功跳跃次数、时长和排行榜仍以后端 run 为准，前端只延迟显示态。
-- 验证：`npm test -- src/services/jump-hop/jumpHopRuntimeModel.test.ts src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx` 应覆盖动画期间平台仍停在旧窗口，动画结束后进入 `data-platform-advancing=true`，Three 角色层与地块层同在 `jump-hop-camera-layer` 内，通过 `--jump-hop-camera-shift-x` 和 `--jump-hop-camera-shift-y` 完成相机斜向推进，并校验可见地块按深度保留不同视觉尺寸、运行态平台宽高使用固定基准值、推进态 transform transition 为 `1440ms`、推进态角色 transition 不包含 `left/top`。
+- 处理：前端保留独立 `displayRun`，松手后先进入 `isJumpAnimating=true`，角色在当前显示窗口内飞向前端预测真实落点；视觉预测必须用当前显示窗口的 current/next 地块作为方向来源，不能拿已经提前返回的后端新 run 目标配旧窗口角色，否则下一跳会朝实际目标反方向飞。飞行动画完成后再把 `displayRun` 切到最新后端 run，并进入约 `1440ms` 的 `platformAdvancing` 表现态。成功后的角色显示必须使用 `lastJump.landedX/landedY` 映射出的真实偏移，不要吸附到目标地块中心。推进期间地块 DOM 层和 DOM 角色层必须统一包在同一个 camera layer 下移动，旧当前地块先跟随相机偏移离开主视野，之后只保留在屏幕后方；不要给旧地块加独立向上 / 向下飞走 keyframes，也不要因为旧地块还在保留列表里阻塞下一跳。玩家继续向前跳时，已完成旧地块继续被新的相机推进自然带离屏幕，超过离屏阈值后销毁。相机层必须同时设置 `--jump-hop-camera-shift-x` 与 `--jump-hop-camera-shift-y`，并以旧窗口真实落点和新窗口真实落点为锚点，避免先横向瞬切居中再纵向推进；运行态相机层当前为约 `1.3x` 近距缩放。地块保留当前 / 目标 / 预览的深度尺寸差异，但深度差异必须用固定宽高 + CSS transform scale 缓动实现，不能直接改宽高瞬切；当前态不要额外叠 CSS scale。相机推进期间角色自身也不能保留 `left/top` transition，否则 `displayRun` 切换造成的角色局部坐标变更会和父级 camera layer 位移叠加，视觉上像落地后又从屏幕外飞回；角色推进期只允许 transform / opacity transition。正式胜负、成功跳跃次数、时长和排行榜仍以后端 run 为准，前端只延迟显示态。
+- 验证：`npm test -- src/services/jump-hop/jumpHopRuntimeModel.test.ts src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx` 应覆盖动画期间平台仍停在旧窗口，成功落地保留真实落点偏移，动画结束后进入 `data-platform-advancing=true`，DOM 角色层与地块层同在 `jump-hop-camera-layer` 内，通过 `--jump-hop-camera-shift-x` 和 `--jump-hop-camera-shift-y` 完成相机斜向推进，并校验可见地块按深度保留不同视觉尺寸、运行态平台宽高使用固定基准值、推进态 transform transition 为 `1440ms`、推进态角色 transition 不包含 `left/top`、旧地块没有独立 `jump-hop-platform-exit-drift` keyframes 且下一跳不会被旧地块保留态阻塞。
 - 关联：`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`src/services/jump-hop/jumpHopRuntimeModel.ts`、`server-rs/crates/module-jump-hop/src/application.rs`。
 
 ## 跳一跳相机推进不要让地块图片回退到原型方块
 
 - 现象：角色落到下一块后，相机推进时旧地块图片突然消失，或新预览地块先露出浅色原型方块，随后真实 image2 切片才出现。
-- 原因：旧地块进入 exiting 状态时如果 React key 从 `platformId` 变成 `platformId-exiting`，图片组件会重新挂载并丢失已加载状态；同时 `JumpHopTileImage` 曾在真实图片 URL 已存在但 `onLoad` 尚未触发时显示 fallback 原型地块。
-- 处理：exiting 地块继续使用稳定 `platformId` key，让旧图片组件在推进期复用；有真实 `resolvedUrl` 且未错误时直接保留真实 `<img>`，只在无 URL 或加载失败时显示 fallback；当前 3 块之外的后续地块通过隐藏预加载图片提前解析签名 URL 和浏览器缓存。
+- 原因：旧地块进入 exiting 状态时如果 React key 从 `platformId` 变成 `platformId-exiting`，图片组件会重新挂载并丢失已加载状态；同时 `JumpHopTileImage` 曾在真实图片 URL 已存在但 `onLoad` 尚未触发时显示 fallback 原型地块。Three.js 平台层接入后，如果隐藏预加载只让浏览器缓存 `<img>`，但没有把未来 `platformId` 的纹理 URL 写入 `platformTextureUrlsByRenderKey`，相机推进时新预览地块会短暂缺 Three 贴图；若旧 blob 贴图在空 URL 回调时先被 revoke，再继续保留在 state 中，也会留下一个看似 ready、实际已失效的贴图地址。
+- 处理：exiting 地块继续使用稳定 `platformId` key，让旧图片组件在推进期复用；有真实 `resolvedUrl` 且未错误时直接保留真实 `<img>`，只在无 URL 或加载失败时显示 fallback；当前 3 块之外的后续地块通过隐藏预加载图片提前解析签名 URL 和浏览器缓存，并同步按未来 `platformId` 发布 Three 纹理 URL。Three 平台层在当前 render items 全部有贴图 URL 后继续承接包含 exiting 地块在内的 3D 渲染；退出地块只随相机推进自然离屏，不播放独立飞走动画，避免退出期露出被放大的平面贴图或重复飞多次；贴图 URL 替换必须等新 URL 到达后再释放旧 parent-owned blob，空 URL 回调不得清空或 revoke 仍在活跃 / 预加载 key 上的旧贴图。
 - 验证：`npm run test -- src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx src/services/jump-hop/jumpHopRuntimeModel.test.ts` 应覆盖真实 tile URL 不露出 `.jump-hop-runtime__fallback-tile`，并存在 `jump-hop-tile-preload-image`。
 - 关联：`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx`。
 
-## 跳一跳地块抠图不要用绿幕或近白底识别
+## 跳一跳 Three.js 平台层不能左右镜像 DOM 坐标
 
-- 现象：跳一跳生成草地、花、雪地、白石或云朵地块时，透明化会把绿色 / 白色主体局部扣掉，运行态看到平台缺口、变薄或主体消失。
-- 原因：通用图集默认按绿幕和近白底做透明化，适合 UI / 普通物品，但跳一跳地块天然高频包含绿色和白色；如果继续用 `#00FF00` 绿幕或近白背景识别，素材本体会落入背景分数。旧逻辑还会清理非边缘连通的高置信 key 色块，遇到主体内部撞色时也可能误伤。
-- 处理：跳一跳地块图集 prompt 固定要求单一纯洋红 `#FF00FF` key 背景；切片前后透明化调用 `GeneratedAssetSheetAlphaOptions::jump_hop_magenta_screen()`，只扣洋红 key，关闭近白扣除，并且不清理非边缘连通 key 色像素。通用绿幕函数保持默认绿幕 / 近白兼容，避免影响拼图、抓大鹅和敲木鱼。
-- 验证：`cargo test -p platform-image --manifest-path server-rs/Cargo.toml generated_asset_sheet -- --nocapture` 覆盖洋红 key 保留绿色、白色和非边缘连通 key 色主体；`cargo test -p api-server jump_hop --manifest-path server-rs/Cargo.toml -- --nocapture` 覆盖跳一跳洋红 prompt 与绿 / 白地块切片。
+- 现象：视觉上下一块地块在角色右侧，但蓄力引导和角色飞行动画朝左侧；后端回包后地块窗口又闪现摆回正确位置，像是先按反方向飞、再由快照刷新纠正。
+- 原因：Three.js 平台层如果把相机 `up` 设置成反向，或在 Three 容器上做左右镜像，会让 WebGL 地块的屏幕 X 轴和 DOM 角色 / 落点预测的屏幕 X 轴相反。规则层仍沿当前地块中心到下一块中心裁决，所以后端快照会把状态纠正回来，表现为跳后刷新。
+- 处理：Three 相机保持 `up=(0, 1, 0)`，再用内部投影公式抵消 45° 下压导致的 Y 轴压缩；不要通过反向 `camera.up` 解决上下方向。DOM 角色、蓄力引导、落点预测和 Three 平台层必须共用同向屏幕坐标。
+- 验证：`npm run test -- src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx src/services/jump-hop/jumpHopRuntimeModel.test.ts` 应覆盖 `JUMP_HOP_THREE_CAMERA_UP_Y=1`，并断言 Three 投影与 DOM 屏幕坐标同向。
+- 关联：`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx`。
+
+## 跳一跳立方体贴图不要走透明主体切片
+
+- 现象：水果等主题生成成功后，运行态地块看起来像薄的纯水果 PNG、果切贴纸、透明 cutout；或者反过来六个面都是同一张平铺果皮 / 果肉材质，无法组合成方块苹果 / 方块香蕉这类完整主题对象表达。
+- 原因：跳一跳地板已经改为 Three.js 标准 `1x1x1` 等比极小倒角立方体复用几何体，运行态视角固定为近距相机和 45° 下压视角；image2 应生成 `1024x1536` 的 18 个 cube object UV unwrap，每个大单元内的 top/front/right/back/left/bottom 六面要共同包装同一个主题物体。只强调 full-bleed 容易让水果主题退化成果皮、果肉、叶脉等表面纹理；如果仍把一张图贴给六个面，模型也不需要理解正反和跨面连续特征。旧切图链路若把洋红 key 转 alpha、裁边、只保留最大 alpha 连通主体并补透明安全边，会把整格贴图重新抠成苹果 / 香蕉 / 果切等居中主体，贴到立方体上后四角和侧面都变透明。
+- 处理：跳一跳地板图集 prompt 固定要求 `cube object UV unwrap atlas / 立方体主题物体六面展开图集`，一张图只生成 18 个大单元，每个大单元固定 `4列*3行` UV 网：第 1 行第 2 列 top，第 2 行 left/front/right/back，第 3 行第 2 列 bottom；水果主题要明确生成能一眼说出名称的方块苹果、方块香蕉、方块橙子、方块西瓜等可识别对象，并要求果柄叶片、剥皮条带、放射切面、红瓤黑籽等身份特征跨面连续。禁止自然圆形水果、自然长条香蕉、非方块化完整水果、果切小贴纸、居中小物体、透明背景和留白，同时也禁止“单纯平铺材质 / 抽象纹理 / 只铺主题颜色 / 纯果皮材质 / 纯果肉纹理 / 纯叶脉纹理”。后端按 3x6 大单元和 4x3 UV 网切出 108 张 `256x256` 不透明面贴图，不再调用透明化、最大 alpha 连通主体保留或透明补边。洋红 `#FF00FF` 只作为图集安全缝 / UV 空位 / 外圈 key 色，裁切后若仍有极少残留则转成不透明材质底色；绿色、白色、雪地、云朵、草地、花朵、果肉粉色和浅黄色等主题颜色必须完整保留。
+- 验证：`cargo test -p api-server jump_hop --manifest-path server-rs/Cargo.toml -- --nocapture` 覆盖跳一跳 UV unwrap prompt、18 个大单元、108 张不透明面贴图、绿色 / 白色材质不被透明化、洋红 key 残留不作为透明洞；前端 `JumpHopRuntimeShell` 测试覆盖新 UV 资产会解析六张面贴图，旧单贴图资产仍可 fallback。
 - 关联：`server-rs/crates/platform-image/src/generated_asset_sheets/alpha.rs`、`server-rs/crates/platform-image/src/generated_asset_sheets/sheet.rs`、`server-rs/crates/api-server/src/jump_hop.rs`。
 
 ## 含中文 image2 live 验证不要用 PowerShell 管道喂 Node 源码
@@ -2170,3 +2212,12 @@
 - 处理：`api-server` 构造生成结果订阅消息时，`time4` 固定格式化为北京时间 `YYYY-MM-DD HH:mm`；不要复用 `shared_kernel::format_timestamp_micros`。
 - 验证：`cargo test --manifest-path server-rs\Cargo.toml -p api-server generation_result_template -- --nocapture`；dev 日志中不应再出现 `data.time4.value invalid`。
 - 关联：`server-rs/crates/api-server/src/wechat_subscribe_message.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## 待解决：跳一跳生成超时后可能后台继续成功
+
+- 风险程度：高。
+- 现象：跳一跳生成页可能在 `98% 写入正式草稿` 后报“请求超时，请稍后重试”，但后端仍在继续生成，稍后才把同一 session 写成 `DraftCompiled=100`。2026-06-08 排查 `jump-hop-session-6db8fa7af57c4fa2a71e6430cc808412` 时，背景底图 image2 成功但耗时约 `18分25秒`，返回按钮约 `2分44秒`，地板图集约 `1分46秒`，总耗时超过前端 20 分钟等待窗口，最终在前端超时后约 3 分钟写草稿成功。
+- 原因：跳一跳创作链路仍把背景、返回按钮、地板图集、切片和 OSS 写入串在一次 HTTP 请求里；VectorEngine image2 单步 timeout/connect 失败会在后端重试，单步耗时可能超过前端总等待窗口。中间资产和真实阶段没有落库，session 在完成前仍显示 `Collecting`、`progress_percent=0`，前端只能按时间显示假进度；超时后重试同一 session 时，后端还可能因为 session 没有中间素材而重新从背景开始生成。
+- 待处理：将跳一跳生成改为后端任务化 / 可轮询真实阶段进度，按背景、返回按钮、图集、切片、持久化、写草稿分阶段落库；统一后端全局生成 deadline、VectorEngine 重试预算、前端等待窗口和失败态回写。超时后再次进入同一 session 应优先恢复正在运行或已完成的任务，不应重复生图。
+- 验证：模拟首张 image2 超长耗时或超时重试时，生成页应显示真实阶段和可恢复状态；前端请求超时不应把最终成功草稿标记为失败；刷新 `/creation/jump-hop/generating?sessionId=<id>` 后应能恢复到后端真实状态；同一 session 重试不得重复生成已完成阶段。
+- 关联：`src/services/jump-hop/jumpHopClient.ts`、`src/services/miniGameDraftGenerationProgress.ts`、`server-rs/crates/api-server/src/jump_hop.rs`、`server-rs/crates/platform-image/src/vector_engine/client.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。