GenarrativeAI/Genarrative
6
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/codex/tiaoyitiao' into codex/tiaoyitiao

Browse Source 
# Conflicts:
#	docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md
#	server-rs/crates/spacetime-client/src/jump_hop.rs
#	server-rs/crates/spacetime-client/src/mapper/runtime.rs
#	server-rs/crates/spacetime-client/src/wooden_fish.rs
#	src/components/jump-hop-result/JumpHopResultView.test.tsx
#	src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx
#	src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
#	src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx
#	src/components/unified-creation/workspaces/JumpHopCreationWorkspace.tsx
#	src/components/unified-creation/workspaces/JumpHopWorkspace.test.tsx
This commit is contained in:
五香丸子
2026-06-04 11:34:31 +08:00
parent 2678954627 7d2d67a3f5
commit c442c3c3f0
52 changed files with 6752 additions and 2346 deletions
Download Patch File Download Diff File Expand all files Collapse all files

37
.hermes/shared-memory/decision-log.md
View File

@@ -1139,13 +1139,38 @@
- 验证方式：从平台推荐或公开详情进入跳一跳作品时，路由 source type 为 `jump-hop`、public code 为 `JH-*`，运行态启动消费后端返回的完整 profile / run 数据；后端 smoke 统一使用 `npm run dev:api-server` 启动并检查 `/healthz`。
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
## 2026-05-26 跳一跳地块图集改为专用 2x3 六格切分
## 2026-05-28 跳一跳重设计为 5x5 地块图集与弹弓拖拽
- 背景：跳一跳创作在地块生图阶段误用了通用系列素材图集 helper，`item_names.len() > grid_size` 的校验会让 6 个地块类型在 `grid_size = 3` 时直接失败；即使绕过校验，通用 helper 仍以“每物品多视图”语义切图，不符合跳一跳地块的一次性六格资产模型。
- 决策：跳一跳地块图集固定采用专用 `2行*3列` 六格布局，按 `start / normal / target / finish / bonus / accent` 顺序切分并分别持久化为独立 PNG 资产；图集 prompt 不再调用通用系列素材 `build_generated_asset_sheet_prompt`。
- 影响范围：`server-rs/crates/api-server/src/jump_hop.rs`、`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
- 验证方式：`cargo test -p api-server jump_hop_tile_atlas -- --nocapture` 通过；六张切片都应有独立 OSS 对象与 `JumpHopTileAsset` 记录，不再只有 atlas 预览路径。
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`。
- 背景：旧跳一跳模板仍保留角色生图、有限路径、score/combo 和 `2x3` 地块图集口径，和当前“俯视角平台跳跃 + 主题生成地块池 + 无限路径”的产品需求不一致。
- 决策：`jump-hop` v1 创作端只保留主题输入；image2 生成一张 `5x5`、共 25 个 2D 地块图标的图集，后端按均匀网格切出 25 个 `JumpHopTileAsset`。角色不再单独生图，运行态使用陶泥儿 logo 透明 PNG 角色；运行态输入为按住后拉蓄力、松手反向弹出，前端提交 `chargeMs + dragVectorX + dragVectorY`，后端裁决落点。草稿试玩必须使用 `runtimeMode=draft`，正式作品使用 `runtimeMode=published`；排行榜按作品维度每玩家只保留 1 条最佳记录，排序为成功跳跃次数降序、游戏时长升序、更新时间升序。
- 决策补充：跳一跳创作入口的事实源仍是 SpacetimeDB `creation_entry_type_config`。默认种子和旧默认行都必须同步迁移到 `subtitle=主题驱动平台跳跃`、`image_src=/creation-type-references/jump-hop.webp`；后端只在系统默认旧值命中时自动纠偏，避免覆盖后台手动配置。
- 影响范围：`jump-hop` PRD、`api-server` 生成编排、`module-jump-hop` 领域规则、`spacetime-module` / `spacetime-client` 跳一跳契约、前端工作台 / 结果页 / runtime / 平台壳调用链。
- 验证方式：`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`、`cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、跳一跳工作台和 runtime 定向前端测试。
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
## 2026-06-01 跳一跳运行态地块视觉尺寸和命中半径统一放大一倍
- 背景：当前跳一跳运行态里地块视觉尺寸偏小，玩家反馈“很难跳上去”，但仅放大前端展示会造成画面和后端裁决脱节。
- 决策：`jump-hop` 运行态的地块视觉尺寸、`width/height` 玩法世界尺寸以及 `landingRadius/perfectRadius` 同步乘以 2；前端平台渲染抽成统一尺寸 helper，保证单测可以直接校验放大结果。
- 影响范围：`server-rs/crates/module-jump-hop/src/application.rs`、`src/services/jump-hop/jumpHopRuntimeModel.ts`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、对应定向测试。
- 验证方式：`npm test -- src/services/jump-hop/jumpHopRuntimeModel.test.ts src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx`、`cargo test -p module-jump-hop --manifest-path server-rs/Cargo.toml -- --nocapture`。
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
## 2026-06-02 跳一跳起跳距离减半并加入飞行动画缓冲
- 背景：用户反馈当前跳跃到目标位置需要拖得太远，且松手后缺少角色翻腾到目标地块的过渡动画，导致跳跃手感偏硬。
- 决策：`jump-hop` 的 `chargeToDistanceRatio` 统一从 `0.004` 提升到 `0.008`，让同等跳跃距离所需拖动距离减半；前端 runtime 把“后端真实 run”和“当前屏幕显示态”拆开，松手瞬间先生成 `visualJump`，用当前角色位置作为起点、前端预测落点作为终点，播放约 `560ms` 的飞行动画；该路径不得等待后端新 run。角色弹到预测落点后若新 run 尚未返回，必须停在预测落点等待，再进入约 `1440ms` 的相机层推进过渡。推进期间地块 DOM 层和 DOM 角色层统一包在同一个 camera layer 下移动，旧当前地块自然离开视野，新预览地块从上方露出，避免 p1/p2 单独 top/left 过渡导致角色和地块不同步。相机推进必须同时使用 X/Y 偏移，从旧目标地块位置斜向滑到新当前地块聚焦位置，不能先横向瞬切居中再纵向推进。地块保留当前 / 目标 / 预览的深度尺寸差异，但该差异通过固定基准宽高上的 CSS transform scale 表达，并在相机推进期间同样使用 `1440ms` 缓动；当前态不再额外叠 CSS scale。
- 影响范围：`server-rs/crates/module-jump-hop/src/application.rs`、`src/services/jump-hop/jumpHopRuntimeModel.ts`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、跳一跳运行态定向测试。
- 验证方式：`npm test -- src/services/jump-hop/jumpHopRuntimeModel.test.ts src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx`、`cargo test -p module-jump-hop --manifest-path server-rs/Cargo.toml -- --nocapture`、`npm run check:encoding`。
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
## 2026-06-03 跳一跳角色形象改为陶泥儿 logo 透明 PNG
- 背景：跳一跳运行态此前仍使用旧内置 / CSS 角色形象，和用户要求的陶泥儿 logo 角色不一致，也容易和 DOM 地块层出现遮挡层级问题。
- 决策：`jump-hop` v1 不再渲染内置 3D 角色几何体；运行态和结果页统一使用 `public/branding/jump-hop-taonier-character.png`，该文件由陶泥儿 logo 处理为透明 PNG 后接入。蓄力时角色沿拖拽方向明显拉长，落地后向反方向回弹两次。`characterAsset` 继续仅作为历史兼容描述字段，不能重新打开角色生图槽或把角色图片作为创作者可配置输入。
- 影响范围：`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`src/components/jump-hop-result/JumpHopResultView.tsx`、跳一跳 PRD 和平台链路文档。
- 验证方式：跳一跳运行态 / 结果页测试需要断言角色图片 src 为 `/branding/jump-hop-taonier-character.png`，并确认旧默认角色 fallback 不再出现。
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
# 2026-05-20 陶泥儿主视觉配色回收为暖白/陶土橙

73
.hermes/shared-memory/pitfalls.md
View File

@@ -1643,14 +1643,45 @@
- 验证：`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`。
## 跳一跳地块图集不要套通用系列素材 n 行模型
## 跳一跳地块图集固定走 5x5 地块池
- 现象：跳一跳初始草稿生成时报 `系列素材图集的物品行数不能超过 n。`，或者即使绕过报错也只生成了 atlas 预览路径，地块切片没有真正落盘。
- 原因：跳一跳地块只有 6 个固定 tileType，但旧实现把它塞进通用系列素材 helper，并使用 `grid_size = 3` / `item_names = 6` 的语义冲突模型；随后又只保留 atlas 资产与模拟路径，没把六个切片逐一上传并确认到 `JumpHopTileAsset`。
- 处理：跳一跳地块改用专用 `2行*3列` 图集 prompt，按 `start / normal / target / finish / bonus / accent` 顺序切 6 张 PNG，并对每张切片各自走 OSS 上传、asset_object 确认和 entity bind。
- 验证：`cargo test -p api-server jump_hop_tile_atlas -- --nocapture` 通过后，再看 `jump_hop.rs` 不应再调用 `build_generated_asset_sheet_prompt` 处理地块图集；公开结果里应能拿到 6 个独立 `JumpHopTileAsset`。
- 现象：跳一跳初始草稿生成时报 `系列素材图集的物品行数不能超过 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`，运行态无限路径从地块池随机取材。
- 关联：`server-rs/crates/api-server/src/jump_hop.rs`、`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
## 跳一跳地块切片不要按 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` 刷新键。
- 关联：`server-rs/crates/api-server/src/jump_hop.rs`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`src/components/jump-hop-result/JumpHopResultView.tsx`。
## 跳一跳落点辅助标识不要再用舞台高度常量拍脑袋投影
- 现象：拖拽时落点辅助标识虽然会动，但看起来像静态点位漂移，和真实可落地的位置对不上。
- 原因：辅助标识如果只按 `stageSize.height` 和一个固定比例估算投影距离，再去跟拖拽向量合成，就会和当前地块到目标地块的真实屏幕跨度脱节；三维场景层级过高时还会把辅助点直接盖住。
- 处理：辅助标识必须使用当前地块与目标地块之间的真实屏幕距离和后端 `chargeToDistanceRatio` 做投影，再映射到屏幕坐标；同时把辅助层 z-index 放到三维角色层之上，避免被场景层遮挡。
- 验证：拖拽半程时辅助点应落在当前地块和目标地块之间，完整拖拽时应逼近目标地块中心；运行态截图里辅助点必须始终压在地块与角色之上。
- 关联：`src/services/jump-hop/jumpHopRuntimeModel.ts`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`。
## 跳一跳落点辅助和后端裁决必须统一坐标换算
- 现象：落点辅助标识已经压在目标地块图片上，松手后后端仍判定失败，玩家看到的是“明明瞄准了却没落上去”。
- 原因：前端辅助标识使用屏幕像素坐标绘制，而后端裁决使用世界坐标。屏幕 y 轴向下为正、世界 y 轴向上为正；同时屏幕 x/y 每个世界单位对应的像素比例不同。若前端直接把屏幕像素拖拽向量发给后端，辅助点和后端落点方向会不一致。
- 处理：前端运行态保留原始屏幕拖拽向量用于画弹弓和辅助点，但提交后端前必须按当前地块到目标地块的屏幕跨度 / 世界跨度把 x、y 分别换算成世界尺度一致的向量；后端继续只负责反向弹射和落点裁决。
- 验证：前端回归测试要同时覆盖辅助点完整拖拽到目标地块，以及提交给后端的向量已完成世界尺度换算；后端领域测试覆盖屏幕向后下拉时应向世界 y 正方向跳出并命中。
- 关联：`src/services/jump-hop/jumpHopRuntimeModel.ts`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`server-rs/crates/module-jump-hop/src/application.rs`。
## 跳一跳创作入口旧文案先查 SpacetimeDB 配置
- 现象：`JumpHopWorkspace` 已只剩主题输入，但创作 Tab 的跳一跳模板卡仍显示旧的“俯视角跳跃闯关”或拼图参考图。
- 原因：创作入口卡片事实源是 SpacetimeDB `creation_entry_type_config` 和 `/api/creation-entry/config`，前端只做展示派生；如果只改工作台、PRD 或前端组件，已有库里的旧入口行不会自动变化。当前 `api-server` 读取入口配置时优先订阅缓存，缓存命中后不会再走 procedure 播种，所以只把迁移写在 `get_creation_entry_config` 里不够。
- 处理：同步更新 `module-runtime` 默认入口种子，并在 `spacetime-module/src/runtime/creation_entry_config.rs` 加只命中旧系统默认值的迁移；同时在 `spacetime-client` 的入口配置读模型里做同一条旧系统默认行的读路径纠偏。跳一跳当前默认值为 `subtitle=主题驱动平台跳跃`、`image_src=/creation-type-references/jump-hop.webp`。
- 验证：本地 `GET /api/creation-entry/config` 的 `jump-hop` 项应返回新 subtitle 和新 imageSrc；若仍旧，检查本地 SpacetimeDB 是否已发布当前 `spacetime-module`，以及后台是否手动覆盖过入口配置。若缓存路径和 procedure 路径返回不一致，优先怀疑读模型映射没做纠偏，而不是前端展示层。
## image2 dry-run 带参考图时不要直接打印 data URL
- 现象：使用 VectorEngine `gpt-image-2-all` 生成带参考图的概念图时，如果 dry-run 直接打印完整请求体，参考图会被转成超长 `data:image/png;base64,...`，终端日志会被数百万字符淹没。
@@ -1737,6 +1768,22 @@
- 验证：`npm test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "mobile profile page matches the reference layout sections|profile scan action opens camera scanner instead of recharge panel"`。
- 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
## 旧创作入口先确认是不是旧 worktree 在响应
- 现象：浏览器里明明还看到跳一跳旧入口，比如 `俯视角跳跃闯关` 和 `puzzle.webp`，但当前 worktree 里已经改成了 `主题驱动平台跳跃` 和 `jump-hop.webp`。
- 原因：本机常同时存在两个开发栈，旧 worktree 可能还在占用 `3000/8082/3101/3102`，而当前 worktree 可能跑在另一组端口。只看页面文案就下结论，容易把旧进程误认成当前改动没生效。
- 处理：先用 `Get-NetTCPConnection` / `Get-CimInstance Win32_Process` 确认端口对应的可执行文件和命令行，再分别请求 `/api/creation-entry/config` 比对旧端口与当前 worktree 端口。必要时以当前 worktree 的实际端口为准重新打开页面。
- 验证：旧端口返回旧跳一跳入口，当前 worktree 端口返回新跳一跳入口；两边的 `api-server` / `vite-cli` 命令行应指向不同仓库路径。
- 关联：`scripts/dev.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
## 3001 无法访问先查旧 worktree 占端口和 SpacetimeDB 版本
- 现象：`http://127.0.0.1:3001/` 打不开，但 `3000 / 3101 / 8082` 仍有进程；`npm run dev` 直接退出，没有把新栈拉起来。
- 原因：旧 worktree 的 `api-server`、`spacetime-standalone` 和 Vite 还活着，或者当前 worktree 的本机 SpacetimeDB CLI 默认版本低于仓库锁定版本，`scripts/dev.mjs` 会先校验版本再启动并直接报错退出。
- 处理：先停掉占用端口的旧进程，再执行 `spacetime version list` 和 `spacetime version use 2.3.0`，确认本机 CLI/standalone 与仓库一致后重新启动 `npm run dev -- --no-interactive --web-port 3001 --api-port 8083 --spacetime-port 3103 --admin-web-port 3104`。
- 验证：`http://127.0.0.1:3001/`、`http://127.0.0.1:8083/healthz`、`http://127.0.0.1:3103/v1/ping` 都返回 200，且进程命令行指向当前 worktree 路径而不是别的仓库。
- 关联：`scripts/dev.mjs`、`.hermes/shared-memory/pitfalls.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
## 微信历史孤儿作品不要让新注册账号顶替
- 现象：清空用户数据或迁移历史数据后，旧作品的 `owner_user_id` 为空或失效，新注册用户会因为顺序号复用或旧 ID 残留顶替作品归属，导致刚注册就看到别人的草稿或已发布作品。
@@ -1752,3 +1799,19 @@
- 处理：推荐页拖拽只校验当前是否有作品、多作品可切换以及是否正在提交动画，不再要求登录；登录态相关操作仍由点赞、改造等按钮自身权限控制。
- 验证：`npx vitest run src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx` 覆盖访客态纵向滑动不弹登录且触发下一条推荐。
- 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`。
## 跳一跳飞行动画不要直接用最新 run 重绘地块窗口
- 现象：跳一跳松手后如果后端很快返回下一帧 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。正式胜负、成功跳跃次数、时长和排行榜仍以后端 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`。
- 关联：`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`src/services/jump-hop/jumpHopRuntimeModel.ts`、`server-rs/crates/module-jump-hop/src/application.rs`。
## 含中文 image2 live 验证不要用 PowerShell 管道喂 Node 源码
- 现象：本地用 `@'...'@ | node -` 跑 VectorEngine / gpt-image-2 live 验证时，`request.json` 里的中文 prompt 可能全部变成 `????`，生成图会变成完全不相关的 UI、建筑海报或其它随机内容，容易误判为模型不服从提示词。
- 原因：Windows PowerShell 管道到 Node stdin 时可能按本机非 UTF-8 编码传输脚本文本，JS 源码里的中文字符串在进入 Node 前已经损坏；Rust 后端真实请求不会走这条编码路径。
- 处理：含中文提示词的 live 验证优先写成 UTF-8 `.mjs` 文件再执行，或使用能确认 UTF-8 的运行入口；执行后先检查本次 `request.json` 是否保留真实中文，再判断生图质量。不要基于 `????` prompt 生成的图片调整项目提示词。
- 验证：生成前后检查 `request.json`，其中 `prompt` 字段应显示中文而不是问号；同一提示词在 UTF-8 文件脚本下应能得到符合主题的图。
- 关联：`.codex/skills/gpt-image-2-apimart/SKILL.md`、`server-rs/crates/api-server/src/jump_hop.rs`。