1

2026-04-26 17:53:31 +08:00
parent 06d49c0ad2 a0d1cb86f0
commit 39f679d1ea
46 changed files with 1027 additions and 626 deletions
--- a/docs/audits/engineering/SERVER_NODE_FREEZE_AND_DEPRECATION_2026-04-24.md
+++ b/docs/audits/engineering/SERVER_NODE_FREEZE_AND_DEPRECATION_2026-04-24.md
@@ -28,7 +28,7 @@
 ## 4. 工程防线

 1. 第一批物理删除后，根目录 `package.json` 不再保留 `server-node:*`、`dev:node`、`check:server-node-freeze` 等旧入口。
-2. Vite、Caddy 与本地开发脚本默认只指向 Rust `api-server`，不再保留 Node/Rust 后端切换开关。
+2. Vite 与本地开发脚本默认只指向 Rust `api-server`，不再保留 Node/Rust 后端切换开关。
 3. 历史文档允许保留旧 `server-node` 字样，但新增工程入口、脚本、依赖、运行说明不得再指向旧 Node 后端。
 4. 若后续需要恢复旧能力，只能迁移到 `server-rs/` 对应 crate 或 Axum facade，不恢复 `server-node/` 工程目录。

@@ -60,7 +60,7 @@
 1. 删除 `server-node/` 目录本体，旧实现只允许通过历史提交、迁移文档和已迁移到 `server-rs/` 的代码追溯。
 2. 删除旧 Node 后端专用入口：`scripts/dev-node.mjs`、`scripts/server-node-frozen.mjs`、`scripts/check-server-node-freeze.mjs`、`scripts/server-node-freeze-baseline.json`、`scripts/smoke-server-node.ts`、`scripts/smoke-same-origin-stack.ts`、`scripts/m7-api-compare.ts`、`scripts/deploy.sh`、`scripts/update.sh`、`view-llm-logs.ps1`。
 3. 根目录 `package.json` 删除 `server-node:*`、`dev:node`、`m7:api-compare` 与 `check:server-node-freeze` 等旧入口，并移除 `express`、`@types/express` 依赖。
-4. `npm run dev` 改为启动 Rust 本地栈；Vite 和 Caddy 默认只代理到 Rust `api-server`，不再保留 `GENARRATIVE_BACKEND_STACK` 的 Node/Rust 双栈切换口。
+4. `npm run dev` 改为启动 Rust 本地栈；Vite 默认只代理到 Rust `api-server`，不再保留 `GENARRATIVE_BACKEND_STACK` 的 Node/Rust 双栈切换口。
 5. 清理 `.gitignore` 中只服务 `server-node/` 的忽略规则，并同步 `README.md`、`.env.example`、`server-rs/README.md` 与 `scripts/dev-server/README.md`。

 ### 7.2 暂不处理范围
@@ -93,3 +93,37 @@
 2. 保留审计、PRD、迁移基线中作为历史事实、旧实现来源、能力对照的 `server-node` 引用。
 3. 不大规模重写包含中文剧情、需求、审计结论的历史文档，避免把真实历史上下文抹平。
 4. 若发现某个历史文档仍指导新开发继续写 Node 后端，先把该文档改为“历史阶段口径”，再继续工程处理。
+
+## 8. 开发命令与脚本复核（2026-04-26）
+
+本轮按“`server-node/` 已完全移除”的状态复核当前开发入口、脚本和工程配置，确认不再保留旧 Node 后端或 Express 运行路径。
+
+### 8.1 已复核范围
+
+1. 根目录 `package.json` 与 `package-lock.json`。
+2. 根目录 `README.md`、`.env.example`、`.gitignore` 与 `vite.config.ts`。
+3. `scripts/`、`.github/`、`jenkins/` 与 `server-rs/` 下的已跟踪文本文件。
+
+### 8.2 复核结论
+
+1. `package.json` 中不存在 `server-node:*`、`dev:node`、`m7:api-compare`、`check:server-node-freeze` 等旧入口。
+2. `scripts/` 下不存在 `dev-node.mjs`、`smoke-server-node.ts`、`m7-api-compare.ts`、`smoke-same-origin-stack.ts` 等旧 Node 后端脚本。
+3. `package.json` 与 `package-lock.json` 中不存在 `express`、`@types/express`、`pg`、`postgres` 依赖。
+4. 当前开发入口继续固定为 `npm run dev`、`npm run dev:web`、`npm run api-server:maincloud` 与 Rust / SpacetimeDB 相关脚本，不恢复旧 Node 后端切换开关。
+
+## 9. Caddy 本地服务入口移除（2026-04-26）
+
+`serve:caddy` 仅服务旧的 dist 本地代理验证链路，不再属于当前 Rust / SpacetimeDB 主开发入口。本轮删除该入口和配套文件，避免开发命令继续暴露第二套本地服务方式。
+
+### 9.1 删除范围
+
+1. 根目录 `package.json` 删除 `serve:caddy`。
+2. 删除 `scripts/run-caddy-dev.mjs`。
+3. 删除 `tools/Caddyfile.dev`。
+4. `.env.example` 删除 `CADDY_API_UPSTREAM` 样例变量。
+
+### 9.2 后续口径
+
+1. 本地完整联调继续使用 `npm run dev`。
+2. 单独前端联调继续使用 `npm run dev:web` 并通过 Vite 代理到 Rust `api-server`。
+3. 生产包预览继续使用 Vite `preview`，不恢复 Caddy 专用开发入口。
--- a/docs/design/COMPANION_FIRST_CONTACT_RELATIONSHIP_AND_PRIVATE_CHAT_DESIGN_2026-04-04.md
+++ b/docs/design/COMPANION_FIRST_CONTACT_RELATIONSHIP_AND_PRIVATE_CHAT_DESIGN_2026-04-04.md
@@ -240,6 +240,7 @@ function buildNpcFirstContactOptionCatalog(
 - 不能再用“某人看着你，像是在等你把话接下去”这类第三人称占位旁白充当可见对话历史首句，也不能在聊天 state 里本地硬编码一条替代台词。
 - 当玩家在场景中第一次真正撞上角色型 NPC 并进入聊天时，应直接触发一轮由 NPC 主动开口的模型回复；这一轮只生成 NPC 自己的首句与后续可选回应，不得代替玩家补写未说过的话。
 - 负好感或敌对关系不应跳过主动开口；如果玩家从 NPC 交互面板点击 `npc_chat`，且该角色尚未完成 `firstMeaningfulContactResolved`，仍要走同一条 NPC 主动开场链路。负好感只影响语气、敌对聊天指令与后续可选功能，不影响“由角色先发言”的首遇行为。
+- 好感度小于 `0` 的角色在聊天终止时不进入 `story_continue_adventure` 收束态。无论是玩家主动退出聊天，还是模型通过敌对聊天指令主动结束聊天，底部选项都固定收束为 `npc_fight` 与 `battle_escape_breakout`：按钮文案分别为“战斗”“逃跑”。点击“战斗”进入 NPC 战斗结算链路；点击“逃跑”执行现有 `battle_escape_breakout` function，完成脱离演出与后续状态更新。

 4. 首遇状态下，不允许前两项直接变成：
   - 深背景追问
--- a/docs/experience/AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md
+++ b/docs/experience/AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md
@@ -0,0 +1,18 @@
+# Agent 空会话草稿可见性修正 2026-04-26
+
+用户从创作中心点进 RPG 或大鱼吃小鱼工作台时，后端会立即创建 Agent session，并写入一条助手欢迎消息。但在用户尚未发送任何消息、也没有传入种子文本时，这个 session 只是临时工作区，不应进入“我的创作”草稿列表。
+
+本次规则：
+
+1. 只有存在用户消息、非空 seedText、真实草稿数据或已发布状态时，Agent session 才算作品草稿。
+2. 助手欢迎消息、默认 anchorPack、空 `{}` draftProfile 不算用户创作内容。
+3. 过滤必须落在后端 works 聚合层，前端创作中心只消费结果，不负责隐藏空草稿。
+4. RPG 仍保留已发布 profile 和孤立持久草稿 profile 的展示；未发布且仍有活跃 Agent session 的编译 profile 继续去重。
+
+涉及入口：
+
+- `server-rs/crates/spacetime-module/src/lib.rs`
+- `server-rs/crates/spacetime-module/src/custom_world/mod.rs`
+- `server-rs/crates/spacetime-module/src/big_fish/session.rs`
+
+后续如果新增玩法创作 Agent，也必须复用同一判断：创建会话不等于创建草稿，作品列表只展示已经被用户实际开始编辑或已经生成结果的会话。
--- a/docs/experience/README.md
+++ b/docs/experience/README.md
@@ -29,3 +29,4 @@
 - [RPG_DRAFT_IMAGE_PARALLEL_GENERATION_2026-04-24.md](./RPG_DRAFT_IMAGE_PARALLEL_GENERATION_2026-04-24.md)：记录 RPG 底稿阶段角色主形象与场景背景图并行生成约束。
 - [PLATFORM_HOME_BANNER_IMAGE_SIZE_FIX_2026-04-25.md](./PLATFORM_HOME_BANNER_IMAGE_SIZE_FIX_2026-04-25.md)：记录首页 banner 背景图不能进入普通布局流的修复经验。
 - [RPG_PUBLISH_GALLERY_REFRESH_FIX_2026-04-25.md](./RPG_PUBLISH_GALLERY_REFRESH_FIX_2026-04-25.md)：记录 RPG 发布后首页 / 分类页公开作品列表刷新链路。
+- [AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md](./AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md)：记录 Agent 空会话不应进入作品草稿列表的后端判定规则。
--- a/docs/technical/FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md
+++ b/docs/technical/FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md
@@ -0,0 +1,56 @@
+# 前端首次加载慢修复记录
+
+日期：`2026-04-26`
+
+## 1. 背景
+
+网站启动后首次打开页面约需三分钟才出现可用界面。已确认 Vite dev server 本身可在数秒内 ready，浏览器 Network 面板中主要等待项集中在 `.tsx` 模块请求，因此本次不继续扩大 `api-server` 冷编译等待窗口，而是收口浏览器首屏 `.tsx` 冷转译与默认路由依赖图。
+
+## 2. 现象与根因
+
+本次排查发现三个会放大首屏等待的前端问题：
+
+1. 默认路由进入 `AuthenticatedApp -> App -> RpgRuntimeShell -> PlatformEntryFlowShellImpl`，首屏虽然只显示平台首页，但入口文件静态导入了创作中心、拼图 Agent、拼图结果页、拼图运行态等非首屏阶段组件。Vite dev 首次访问时需要逐个请求并转译这些 `.tsx`，表现为浏览器长时间卡在加载 `.tsx`。
+2. `RouteImageReadyGate` 会先挂载真实业务页面但把整页 `visibility: hidden`，扫描路由 DOM 中所有 `<img>` 和 CSS 图片，等全部图片 settled 后才显示页面。图片不是本轮确认到的主等待项，但会放大 `.tsx` 冷转译后的可见延迟。
+3. Vite dev server 监听范围过宽，日志中可见 `docs/`、`scripts/`、`server-rs/` 和测试文件变更都会触发 `page reload`。后端编译、文档更新或测试文件保存会让浏览器反复全量重载，叠加 `.tsx` 冷转译后表现为“首次加载一直等”。
+
+## 3. 修复口径
+
+### 3.1 首屏 `.tsx` 冷转译
+
+默认首页入口先做低风险依赖图收敛：
+
+- `App`、运行时阶段路由、面板路由避免从 barrel 文件导入，改为直连具体实现文件或类型文件。
+- `PlatformEntryFlowShellImpl` 将拼图 Agent、拼图结果页、拼图详情页、拼图运行态、创作货架等非默认首屏组件改为 `lazy`。
+- 平台首页 Tab 保留已访问页面的挂载状态，但首访只挂载当前 Tab，避免隐藏的创作页提前触发创作中心等懒加载模块。
+- RPG 运行态画布和 overlay host 只在已经进入 RPG 世界后挂载，平台首页不再同步拉取运行态画布链路。
+- 默认 `App` 不再首屏调用 `useRpgRuntimeSession`。平台首页先挂载轻量 `PlatformEntryFlowShell`，用户选择世界、恢复存档或进入 RPG 运行态深链后，才懒加载完整 `RpgRuntimeApp` 和故事/战斗/NPC 交互 hooks。
+- 平台入口 props 移除未使用的 `gameState`，避免轻量首页为了兼容旧签名初始化完整 RPG `GameState`。
+- 平台首页资料服务直连 `rpgProfileClient`，避免经过 `services/rpg-entry/index.ts` 把同域其它 client 一并纳入冷转译链路。
+
+### 3.2 首屏图片门控
+
+图片门控从“等待所有图片加载完成”改为“短暂稳态等待后放行”：
+
+- 页面仍先真实挂载，保留极短等待窗口，避免首帧布局剧烈闪动。
+- 达到最大阻塞时间后必须显示页面，慢图片由浏览器渐进加载，不再隐藏整页。
+- 页面已经显示后，不再因为新增图片或图片地址变化重新隐藏页面。
+- 图片预加载继续保留，用于提前触发浏览器缓存，但不得成为首屏可见的硬阻塞。
+
+### 3.3 Vite 监听范围
+
+Vite dev server 只对前端真实运行入口保持热更新敏感：
+
+- 忽略 `docs/`、`server-rs/`、`scripts/`、`backend-rewrite-tasklist/`、`media/` 等非前端首屏运行目录。
+- 忽略 `*.test.ts(x)` / `*.spec.ts(x)`，避免测试文件保存触发页面 reload。
+- 保留 `src/` 与 `packages/shared/` 的正常变更反馈，因为它们仍是前端运行时依赖。
+
+## 4. 验收标准
+
+1. Vite ready 后，默认站点首屏不再一次性转译明显非首屏的拼图/玩法结果/运行态组件。
+2. 默认首页冷加载 `.tsx` 请求数量下降，创作、拼图、运行态等阶段在用户进入时再加载对应 chunk。
+3. 默认首页不再同步加载 RPG story / combat / NPC interaction 运行态 hooks；进入自定义世界或恢复存档后再加载完整运行态。
+4. 慢图片、失败图片或生成资源代理慢时，页面主体仍能先显示并保持可操作。
+5. 修改 `docs/`、`server-rs/`、`scripts/` 或测试文件时，不再触发前端页面 reload。
+6. `RouteImageReadyGate` 工具测试覆盖慢图片仍会放行首屏的行为。
+7. 修改中文文件后运行编码检查，确保没有破坏 UTF-8 文本。
--- a/docs/technical/M6_LEGACY_GENERATED_PATH_OSS_READ_COMPAT_2026-04-22.md
+++ b/docs/technical/M6_LEGACY_GENERATED_PATH_OSS_READ_COMPAT_2026-04-22.md
@@ -51,6 +51,19 @@
 1. `content-type`：优先使用 OSS 响应头。
 2. `cache-control`：`private, max-age=60`。
 3. `x-genarrative-asset-object-key`：回写解析后的 OSS object key，方便调试。
+4. `content-length`：成功读取 OSS 对象后按二进制体长度显式回写，避免开发代理或浏览器把已成功读取的图片误判为空响应。
+
+## 3.1 成功对象响应稳定性补充
+
+日期：`2026-04-26`
+
+本次排查发现 `/generated-characters/storynpcs-0/visual/visual-storynpcs-0-aitask_65048e86d04f7/master.png` 在 OSS 签名 URL 下可正常返回 `200 image/png`，但 Rust 同源代理成功读取对象后曾对客户端返回空响应，Vite 开发代理进一步表现为 `500 Internal Server Error`。
+
+修复口径：
+
+1. 成功分支不再依赖隐式 `error_for_status()` 后继续用 builder 拼装响应，而是先判断上游状态，再用明确的 `(status, headers, bytes)` 二进制响应返回。
+2. 非 `2xx` 上游状态统一映射为 `404` 或 `502` JSON 错误，禁止把 OSS 上游异常表现成连接中断。
+3. 成功响应必须保留 `content-type`，并显式回写 `content-length`、`cache-control` 与 `x-genarrative-asset-object-key`。

 ## 4. 对象键约定

--- a/docs/technical/M7_TEST_DEPLOY_CUTOVER_EXECUTION_PLAN_2026-04-22.md
+++ b/docs/technical/M7_TEST_DEPLOY_CUTOVER_EXECUTION_PLAN_2026-04-22.md
@@ -2,6 +2,8 @@

 日期：`2026-04-22`

+归档说明：截至 `2026-04-26`，Rust 迁移已完成，旧 `server-node/` 已删除，M7 阶段性预检包装入口已移除。后续长期检查统一使用 `server-rs/scripts/check.ps1`、`server-rs/scripts/smoke.ps1`、`server-rs/scripts/oss-smoke.ps1` 与 `npm run api-server:maincloud`。
+
 ## 1. 文档目标

 这份文档把 `M7：联调、回归、部署与切流任务清单` 从高层勾选项细化为可直接执行的工程方案。
@@ -34,7 +36,7 @@ M7 固定四层测试入口：
 推荐本地顺序：

 ```powershell
-.\server-rs\scripts\m7-preflight.ps1
+.\server-rs\scripts\check.ps1
 .\server-rs\scripts\smoke.ps1
 ```

@@ -91,7 +93,7 @@ OSS / CDN / 域名方案：

 第一批删除后不再保留 Node/Rust 对比脚本，M7 回归改为 Rust 主线 contract 验证：

-1. `server-rs/scripts/m7-preflight.ps1` 覆盖 Rust 工作区构建、测试与关键脚本门禁。
+1. `server-rs/scripts/check.ps1` 覆盖 Rust 工作区格式、clippy、构建与测试门禁。
 2. `server-rs/scripts/smoke.ps1` 覆盖 `/healthz`、envelope 与 request id 基础 contract。
 3. `server-rs/scripts/oss-smoke.ps1` 覆盖真实 OSS 链路。
 4. 新增只读 contract 时优先补进 Rust 侧 smoke 或 handler 测试，不恢复 Node 对比脚本。
--- a/docs/technical/PUZZLE_BIG_FISH_INITIAL_CREATION_PROGRESS_ZERO_FIX_2026-04-26.md
+++ b/docs/technical/PUZZLE_BIG_FISH_INITIAL_CREATION_PROGRESS_ZERO_FIX_2026-04-26.md
@@ -0,0 +1,28 @@
+# 拼图与大鱼吃小鱼初始创作进度归零修复 2026-04-26
+
+## 背景
+
+拼图与大鱼吃小鱼 Agent 新建会话时，后端会先写入欢迎消息和初始锚点草稿。此前这两个模板把欢迎消息和种子推断视为创作推进，导致新会话一进入工作区就显示非 `0%` 的创作进度。
+
+这与创作工作区的统一约束冲突：新会话必须如实展示后端 session 的 `progressPercent`，初始值为 `0` 时前端数字与进度条都保持 `0%`，不能让用户误判已经完成了创作推进。
+
+## 设计约束
+
+1. 拼图与大鱼吃小鱼新建 Agent session 时，`progress_percent` 固定写入 `0`。
+2. 欢迎消息、种子文本和初始锚点推断只作为对话上下文与占位结构，不计入创作进度。
+3. 首次用户消息提交后，进度才允许由模型回包或后续 action 写回推进。
+4. 前端不为这两个模板额外兜底抬高初始进度，进度真相继续来自 `server-rs` 的 SpacetimeDB session。
+
+## 落地点
+
+1. `server-rs/crates/spacetime-module/src/big_fish/session.rs`
+   - `create_big_fish_session_tx` 初始化 `progress_percent = 0`。
+2. `server-rs/crates/spacetime-module/src/puzzle.rs`
+   - `create_puzzle_agent_session_tx` 初始化 `progress_percent = 0`。
+
+## 验收
+
+1. 新建大鱼吃小鱼创作工作区后，顶部创作进度显示 `0%`。
+2. 新建拼图创作工作区后，顶部创作进度显示 `0%`。
+3. 发送第一条用户消息后，进度按模型回包或后续操作正常推进。
+4. 生成草稿、生成资产、发布等后续阶段的进度值不受本次调整影响。
--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -7,6 +7,7 @@
 - [RPG_BATTLE_HEALTHBAR_AND_ACTION_PRESENTATION_FIX_2026-04-26.md](./RPG_BATTLE_HEALTHBAR_AND_ACTION_PRESENTATION_FIX_2026-04-26.md)：记录 RPG 战斗血条安全锚点、服务端战斗回包前端短表现，以及 `battle_use_skill` 指定技能兜底结算的修复口径。
 - [SPACETIMEDB_TABLE_CATALOG.md](./SPACETIMEDB_TABLE_CATALOG.md)：持续维护当前 SpacetimeDB 表目录，按领域说明每张表的作用、字段结构、索引和常用 `spacetime sql` 查询模板。
 - [RPG_OPENING_SCENE_ACT_IMAGE_PRESENTATION_SYNC_2026-04-26.md](./RPG_OPENING_SCENE_ACT_IMAGE_PRESENTATION_SYNC_2026-04-26.md)：记录开局场景与普通场景复用同一场景展示解析服务，修复列表幕缩略图和详情幕背景预览图片不一致的问题。
+- [FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md](./FRONTEND_FIRST_LOAD_PERFORMANCE_FIX_2026-04-26.md)：记录网站启动后首次加载约三分钟的前端根因，收口 `RouteImageReadyGate` 首屏图片门控和 Vite dev server 无关文件监听范围。
 - [RPG_WORK_DELETE_SPACETIMEDB_PROCEDURE_EXPORT_FIX_2026-04-25.md](./RPG_WORK_DELETE_SPACETIMEDB_PROCEDURE_EXPORT_FIX_2026-04-25.md)：记录 RPG 作品删除时报 `No such procedure` 的根因，补齐 `delete_custom_world_agent_session` 在有效 SpacetimeDB 模块入口中的导出，并要求发布后核验 Maincloud schema。
 - [CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md](./CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md)：冻结当前后端唯一落地口径，明确新功能以 `server-rs + Axum + SpacetimeDB` 为准，旧 `server-node` / Express / PostgreSQL 与 Go 方向只允许作为迁移参考。
 - [RPG_DRAFT_GENERATION_CONTINUE_AND_ETA_FIX_2026-04-25.md](./RPG_DRAFT_GENERATION_CONTINUE_AND_ETA_FIX_2026-04-25.md)：记录世界草稿生成失败/中断后进度不再误到 `100%`、主按钮改为“继续生成草稿”并复用已保存底稿续跑，以及按阶段耗时模型估算预计等待时间的修复口径。