1

2026-05-08 11:44:42 +08:00
parent b08127031c
commit abf1f1ebea
249 changed files with 39411 additions and 887 deletions
@@ -13,7 +13,7 @@
  重点补充：RPG 创作与运行时脚本职责地图见 [RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md](./reference/RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md)。
 - [埋点查询](./tracking/README.md)：埋点原始事件与聚合投影的本地 SQL 查询。
 - [运营查询](./operations/README.md)：任务、领奖、钱包对账等后台核查查询。
- [PRD](./prd)：产品需求与阶段计划；后台管理独立前端工程见 [ADMIN_WEB_CONSOLE_PRD_2026-04-30.md](./prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)，新增 RPG 开场动画方案见 [AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md](./prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md)，新增抓大鹅 Match3D 玩法方案见 [AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md](./prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md)，方洞挑战创作、发布与试玩闭环见 [AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md](./prd/AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md)。
+- [PRD](./prd/README.md)：产品需求与阶段计划；参考 MOKU / 幕间类 AI 文游的百梦 `text-game` 模板口径见 [AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md](./prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md)，视觉小说模板 TXT 玩法平台化接入口径见 [AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md](./prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md)，创意互动内容 Agent Phase 1 的 LangChain-Rust PoC、拼图闭环和并行任务拆分见 [CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md](./prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md)，幸存者类模板闭环见 [AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md](./prd/AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md)，后台管理独立前端工程见 [ADMIN_WEB_CONSOLE_PRD_2026-04-30.md](./prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)，新增 RPG 开场动画方案见 [AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md](./prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md)，新增抓大鹅 Match3D 玩法方案见 [AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md](./prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md)，方洞挑战创作、发布与试玩闭环见 [AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md](./prd/AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md)。

 生产部署切换到 systemd + Nginx + SpacetimeDB 自托管的总方案见 [PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md](./technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md)，该文档也是当前生产 Jenkinsfile 的唯一入口。SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)；private 表迁移 JSON 导入导出、HTTP 413 分片导入和旧数据库迁移流水线经验见 [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md) 与 [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)；后台管理独立前端工程技术方案见 [ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md](./technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)。

@@ -23,6 +23,14 @@ SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段

 `maincloud` 相关脚本、环境变量、测试名和文档要求已统一判定为历史残留，后续禁止新增、运行或引用；当前后端 smoke 使用 `npm run api-server` 与 `/healthz`，详细规则见 [MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md](./technical/MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md)。

+基于 LangChain-Rust，以“感知—思考—记忆—行动—反思—协作”闭环完成图文创意理解、拼图模板选择、积分范围确认、拼图草稿字段填充、立即试玩和自然语言修订草稿字段的 Agent 方案见 [CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md](./technical/CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md)。
+
+创意互动内容 Agent Phase 1 的产品边界、实现细节、SpacetimeDB 落点、前端接入和可并行任务拆分见 [CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md](./prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md)。
+
+视觉小说模板接入以 [AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md](./prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md) 为最新口径：只吸收外部 TXT 玩法的模板创作与运行经验，禁止迁入外部平台功能，并删除回放。
+
+AI 文字游戏模板接入以 [AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md](./prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md) 为最新口径：只吸收 MOKU / 幕间类 AI 文游的剧本游乐场、自由行动、AI GM、记忆和模拟器强反馈经验，禁止迁入外部社区、支付、榜单、私有存档或回放。
+
 ## 推荐阅读顺序

 1. 先看 [经验沉淀](./experience/README.md)，快速建立这个项目的开发共识。
@@ -19,6 +19,8 @@
 - [CHARACTER_ASSET_PROMPT_CHAIN_AUDIT_2026-04-20.md](./CHARACTER_ASSET_PROMPT_CHAIN_AUDIT_2026-04-20.md)：角色资产默认描述文本、正式图像/动作 prompt、共享模板与保留接口的分层与冗余审计。
 - [RPG_RUNTIME_DIRECT_DRAFT_PROFILE_AUDIT_2026-04-25.md](./RPG_RUNTIME_DIRECT_DRAFT_PROFILE_AUDIT_2026-04-25.md)：RPG 运行时进入世界时改为直读 Agent session 草稿 profile 的链路检查。
 - [RPG_WORLD_DRAFT_EDIT_AUTOSAVE_OVERRIDE_AUDIT_2026-04-28.md](./RPG_WORLD_DRAFT_EDIT_AUTOSAVE_OVERRIDE_AUDIT_2026-04-28.md)：RPG 世界草稿结果页编辑后被旧设定覆盖的前端本地态、session 真相源与自动保存链路审计。
+- [VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md](./VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md)：视觉小说 VN-11 回放删除与外部平台功能误入负向扫描报告。
+- [VN12_FULL_CHAIN_ACCEPTANCE_REPORT_2026-05-07.md](./VN12_FULL_CHAIN_ACCEPTANCE_REPORT_2026-05-07.md)：视觉小说 VN-12 全链路联调与自动化验收报告。
 - [engineering/RPG_FRONTEND_SCRIPT_BACKEND_MIGRATION_AUDIT_2026-04-28.md](./engineering/RPG_FRONTEND_SCRIPT_BACKEND_MIGRATION_AUDIT_2026-04-28.md)：RPG 前端脚本中仍应迁到 `server-rs` / SpacetimeDB 的开局、快照、story engine、战斗、NPC/背包规则与创作残留后门审计。
 - [engineering/RPG_FRONTEND_SCRIPT_BACKEND_MIGRATION_COMPLETION_CHECK_2026-04-28.md](./engineering/RPG_FRONTEND_SCRIPT_BACKEND_MIGRATION_COMPLETION_CHECK_2026-04-28.md)：RPG 前端脚本后端迁移完成度复核，标明开局、快照、story engine / prompt context、`camp_travel_home_scene`、战斗、NPC、背包/锻造、结果页保存 normalize 与角色资产 prompt 主链均已收口。
 - [engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md](./engineering/ENGINEERING_CLEANUP_AND_BACKEND_BOUNDARY_AUDIT_2026-04-20.md)：对 `2026-04-19` 工程清理审计的当前仓库复核，区分已完成项、仍存边界问题和新的热点迁移。
@@ -0,0 +1,32 @@
+# VN-11 负向扫描报告
+
+生成日期：2026-05-07
+
+## 扫描范围
+
+- 工程代码：`src/`、`packages/shared/src/`、`server-rs/crates/`
+- 文档与共享记忆：`docs/`、`.hermes/shared-memory/`
+- 外部平台误入复核：视觉小说前端、service、shared contracts、Rust contracts、module、api-server、SpacetimeDB schema 与 facade 路径
+
+## 扫描结论
+
+- 工程代码回放类直出命中：0
+- 文档 / 共享记忆回放类命中：222
+- 视觉小说实现路径外部平台能力疑似误入命中：0
+
+## 处理记录
+
+- 已将 `storyEngine` 回归工具的命名从 replay 语义收口为 rerun / 复测语义。
+- 已将技能效果预览按钮的内部状态与文案从重播语义收口为重新预览语义。
+- 已确认视觉小说工程路径未新增回放路由、DTO、表、按钮、文案、外部平台账号 / 订单 / 会员 / 促销 / 后台 / 公开市场或私有存档能力。
+
+## 文档命中说明
+
+- 文档命中来自历史旧文档、设计复盘、禁止语境、负向验收或本报告记录。VN-11 工程门禁只阻断代码路径新增能力。
+
+## 门禁命令
+
+```bash
+npm run check:visual-novel-vn11
+```
+
@@ -0,0 +1,92 @@
+# VN-12 全链路联调与自动化验收报告
+
+生成日期：2026-05-07
+
+## 结论
+
+- 状态：通过
+- 失败项：0
+- 收口说明：VN-12 本次只补验收门禁、关键路径测试和报告记录，未扩展新玩法功能。
+
+## 自动化验收清单
+
+- docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md
+- docs/audits/VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md
+- src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx
+- src/components/visual-novel-result/VisualNovelResultView.test.tsx
+- src/components/visual-novel-runtime/VisualNovelRuntimeShell.test.tsx
+- src/services/visual-novel-runtime/visualNovelRuntimeClient.test.ts
+- src/services/visual-novel-runtime/visualNovelRuntimeSse.test.ts
+- server-rs/crates/api-server/src/visual_novel.rs
+- server-rs/crates/module-visual-novel/src/application.rs
+- server-rs/crates/shared-contracts/src/visual_novel.rs
+- package.json
+- server-rs/crates/api-server/src/app.rs
+- src/services/visual-novel-runtime/visualNovelRuntimeClient.ts
+- src/services/visual-novel-runtime/visualNovelRuntimeClient.test.ts
+- src/services/visual-novel-runtime/visualNovelRuntimeSse.test.ts
+- src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx
+- src/components/visual-novel-result/VisualNovelResultView.test.tsx
+- src/components/visual-novel-runtime/VisualNovelRuntimeShell.test.tsx
+
+## API smoke
+
+- `/api/creation/visual-novel/sessions`
+- `/api/creation/visual-novel/works`
+- `/api/runtime/visual-novel/gallery`
+- `/api/runtime/visual-novel/works/{profile_id}/runs`
+- `/api/runtime/visual-novel/runs/{run_id}/actions/stream`
+- `/api/runtime/visual-novel/runs/{run_id}/history`
+- `/api/runtime/visual-novel/runs/{run_id}/regenerate`
+- `/api/profile/save-archives`
+- `/api/profile/save-archives/{world_key}`
+- `/api/runtime/save/snapshot`
+
+本次实测：
+
+- `npm run api-server` 可启动 Rust `api-server`。
+- `GET http://127.0.0.1:3100/healthz` 返回 `200`，响应为 `{"ok":true,"service":"genarrative-api-server"}`。
+- `GET /api/runtime/visual-novel/gallery` 在当前本地环境返回超时 / `502`，日志显示 `api-server` 连接 `127.0.0.1:3101` SpacetimeDB 数据库 `xushi-p4wfr` 被拒绝；该项按本地 SpacetimeDB 未完整就绪记录为环境阻塞，不新增工程实现。
+
+## 前端关键路径
+
+- 创作工作台：`VisualNovelAgentWorkspace`
+- 结果页：`VisualNovelResultView`
+- 运行时：`VisualNovelRuntimeShell`
+- 运行时 SSE：`visualNovelRuntimeSse` / `visualNovelRuntimeClient`
+
+## 桌面 / 移动端检查
+
+- 桌面端：已用 Edge headless 截取 `/creation/visual-novel/agent`，文件为 `docs/audits/VN12_VISUAL_NOVEL_DESKTOP_2026-05-07.png`。
+- 移动端：已用 Edge headless 截取 `/creation/visual-novel/agent`，文件为 `docs/audits/VN12_VISUAL_NOVEL_MOBILE_2026-05-07.png`。
+- in-app browser 插件本次未发现可用 IAB backend，截图使用本机 Edge headless 兜底完成。
+
+## 校验摘要
+
+- package.json scripts: 通过
+- api-server visual novel routes: 通过
+- visual novel runtime client routes: 通过
+- visual novel runtime client tests: 通过
+- visual novel SSE tests: 通过
+- visual novel creation tests: 通过
+- visual novel result tests: 通过
+- visual novel runtime tests: 通过
+
+## 执行命令
+
+```bash
+npm run check:visual-novel-vn12 -- --write-report
+npm run test -- src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx src/components/visual-novel-runtime/VisualNovelRuntimeShell.test.tsx src/services/visual-novel-runtime/visualNovelRuntimeClient.test.ts src/services/visual-novel-runtime/visualNovelRuntimeSse.test.ts
+npm run check:encoding
+npm run typecheck
+cd server-rs
+cargo test -p shared-contracts
+cargo test -p module-visual-novel
+cargo check -p api-server
+```
+
+## 未覆盖风险
+
+- 当前本地 SpacetimeDB 连接未完整就绪，公开 gallery API 的真实数据返回未在本次环境完成；`/healthz` 与编译 / 单测已通过。
+- 若接口路由或测试名称后续调整，需要同步更新本门禁脚本与报告模板。
+
@@ -28,3 +28,12 @@
 - 锁定的模板卡统一以“敬请期待”作为状态标注，不再显示“锁定”。
 - RPG 入口展示为“角色扮演 / 剧情演绎，冒险成长”，拼图入口展示为“拼图 / 创意礼物，生活分享”。
 - 忙碌状态仅保留在模块标题行的轻量状态中，避免占用每张可用卡片的首要视觉层级。
+
+## 2026-05-07 玩法参考图
+
+1. 每个玩法入口都必须配置一张 `public/creation-type-references/` 下的参考图。
+2. 当前创作 Tab 顶部玩法卡带、旧创作中心卡带和玩法类型弹层都消费同一份 `PLATFORM_CREATION_TYPES.imageSrc`，避免多入口视觉漂移。
+3. 图片只承担玩法识别和氛围锚定，不在卡片上叠加规则说明文案。
+4. 移动端卡片仍以紧凑横滑为主，参考图使用暗色遮罩承接标题，文本不得溢出卡片。
+5. 当前创作 Tab 的可见玩法卡必须真实渲染 `img`，不能只在隐藏弹窗或旧入口中配置图片。
+6. 参考图卡片上的标题和副标题必须显式使用白色文字，并配合底部加深渐变与文字阴影；禁止依赖 `text-inherit`，避免黑字叠在暗蒙版上。
@@ -6,8 +6,8 @@

 - 新增“分类” Tab，用作品标签聚合所有公开发布作品。
 - 强化“创作” Tab 的导航视觉权重，让它在底部导航中居中并更醒目。
- 登录态底部导航顺序为：首页、分类、创作、存档、我的。
- 未登录态底部导航只保留：首页、创作、分类，其中创作保持居中。
+- 登录态底部导航顺序为：推荐、发现、创作、草稿、我的。
+- 未登录态底部导航只保留：推荐、创作、发现，其中创作保持居中。

 ## 2. 数据边界

@@ -24,10 +24,10 @@

 底部导航展示 5 个入口：

-1. 首页
-2. 分类
+1. 推荐
+2. 发现
 3. 创作
-4. 存档
+4. 草稿
 5. 我的

 创作入口位于第三位，视觉上使用更大的图标壳、轻微上浮、渐变高亮和阴影，保证它是主行动入口。
@@ -36,11 +36,11 @@

 底部导航展示 3 个入口：

-1. 首页
+1. 推荐
 2. 创作
-3. 分类
+3. 发现

-不展示“存档”和“我的”，避免未登录用户在底部导航看到必须登录后才有价值的入口。创作入口位于第二位，保持几何居中。
+不展示“草稿”和“我的”，避免未登录用户在底部导航看到必须登录后才有价值的入口。创作入口位于第二位，保持几何居中，并沿用原推荐 Tab 的星光图标；推荐 Tab 改用游戏手柄图标。

 ### 3.3 桌面端

@@ -59,6 +59,6 @@

 - 登录态移动端底部导航顺序准确，创作在 5 个 Tab 中居中。
 - 未登录态移动端底部导航只显示 3 个 Tab，创作在中间。
- 分类 Tab 能按标签切换并展示公开作品。
+- 发现 Tab 能按标签切换并展示公开作品。
 - 创作 Tab 在移动端和桌面端都比普通 Tab 更醒目。
 - 不修改 server-node，不新增后端逻辑。
@@ -0,0 +1,46 @@
+# 平台创作 Tab 模板入口设计
+
+更新时间：`2026-05-07`
+
+## 1. 目标
+
+创作 Tab 恢复为模板选择入口，但不回到旧的大卡片选择面板：
+
+1. 首屏保留现有创作页布局骨架，顶部标题固定为“10分钟创作一个精品互动玩法”。
+2. 选择模板入口改为横向 Tab，数据来自 `src/config/newWorkEntryConfig.ts` 的可见玩法配置。
+3. 默认选中“拼图”模板，并在创作 Tab 内直接展示拼图创作表单。
+4. 智能创作入口从可见模板中隐藏，保留既有 `creative-agent` 运行链路用于后续内部恢复或草稿目标打开。
+5. 草稿、发现、我的等一级 Tab 职责不变，作品管理仍在草稿 Tab。
+
+## 2. 页面结构
+
+移动端和桌面端共用同一信息结构：
+
+```text
+标题：10分钟创作一个精品互动玩法
+模板 Tab：拼图 / 方洞挑战 / 视觉小说 / AIRP
+默认内容：拼图创作表单
+```
+
+拼图表单嵌入创作 Tab 时：
+
+- 不展示工作台返回按钮。
+- 不重复展示“创建拼图”标题。
+- 保留表单内的拼图模板、参考图上传、画面描述和生图模型选择。
+- 生成草稿仍走登录保护，未登录时先触发登录流程。
+
+## 3. 交互
+
+1. 打开“创作”一级 Tab 时默认停留在拼图 Tab，不主动创建拼图 session。
+2. 点击拼图表单“生成草稿”后，才创建拼图 session 并执行 `compile_puzzle_draft`。
+3. 拼图表单内的模板按钮使用 `tablist / tab` 语义，点击后只填充画面描述。
+4. 点击非拼图且已开放的模板 Tab 时，进入该玩法既有工作台；未开放模板保持禁用。
+5. `creative-agent` 不出现在模板 Tab 和选择弹层中，不再作为创作 Tab 首屏入口。
+
+## 4. 验收
+
+1. 点击“创作”后首屏出现“10分钟创作一个精品互动玩法”。
+2. 顶部选择模板入口为 Tab，拼图 Tab 默认 `aria-selected=true`。
+3. 创作 Tab 默认显示拼图创作表单内容，且不显示旧“Hi, 朋友”、输入框或智能创作快捷按钮。
+4. 隐藏的智能创作类型不出现在模板 Tab、旧选择弹层和创作 Hub 卡片中。
+5. 草稿页返回创作页后仍回到同一模板入口，并可保留拼图表单草稿内容。
@@ -0,0 +1,90 @@
+# 平台移动端推荐、发现与草稿 Tab 改版设计
+
+更新时间：`2026-05-05`
+
+## 1. 目标
+
+本次只调整平台入口的信息架构与移动端视觉，不新增后端接口：
+
+1. 原“首页”一级 Tab 对用户改名为“推荐”，进入后直接展示原首页推荐榜单启动后的公开游戏内容流。
+2. 原“首页”中的搜索、今日游戏、游戏分类等探索内容移动到第二个一级 Tab；第二个 Tab 对用户命名为“发现”。
+3. 原“排行”页内容并入“发现”页的子 Tab 中，不再作为一级主 Tab 独立展示。
+4. 创作页只保留新建创作入口；原创作页作品列表拆到一级“草稿” Tab，替换原“存档” Tab。
+5. 原“存档”列表结构并入“我的”页面的“玩过”列表弹层，作为每个已玩作品的可继续存档入口。
+6. 移动端推荐页与底部 Tab 栏参考用户给定样式，使用大画面推荐流、顶部品牌/通知、悬浮胶囊底部导航；保留当前平台已有明暗两套主题色 token。
+
+## 2. 状态映射
+
+为降低迁移风险，前端内部 `PlatformHomeTab` 仍复用既有状态值：
+
+- `home`：用户看到“推荐”。
+- `category`：用户看到“发现”，内容包含搜索、今日游戏、分类和排行子 Tab。
+- `create`：用户看到“创作”，只承担新建入口。
+- `saves`：用户看到“草稿”，承载原创作页作品列表。
+- `profile`：用户看到“我的”，其中“玩过”弹层合并存档入口。
+
+旧 `category` 状态此前承载“排行”，本次不改状态名，只改用户文案和页面内容，避免详情页返回目标、测试辅助和历史路由状态大范围迁移。
+
+## 3. 推荐页
+
+移动端推荐页默认不展示搜索和频道横滑条，进入一级“推荐”后直接渲染公开作品流：
+
+- 数据来源沿用 `featuredEntries + latestEntries` 去重后的公开作品列表。
+- 卡片保留现有作品读模型字段：封面、作者、游玩、改造、点赞、标签。
+- 移动端推荐卡使用近全屏大画面比例，底部展示互动指标、作者和主操作，不写规则说明类文案。
+- 无数据、加载中和错误态沿用短状态文案。
+
+桌面端仍保持现有首页布局，只把一级导航文案从“首页”改为“推荐”。
+
+## 4. 发现页
+
+发现页承接原首页探索能力和原排行能力，子 Tab 为：
+
+1. 推荐：原首页推荐内容流，可作为发现页内的快速回看。
+2. 今日：原首页“今日游戏”。
+3. 分类：原首页“游戏分类”。
+4. 排行：原一级“排行”页四榜切换。
+
+移动端发现页顶部保留搜索框和子 Tab；分类内容继续使用纵向应用商店式列表；排行内容继续使用榜单行。
+
+## 5. 创作与草稿
+
+创作页只保留新建创作入口：
+
+- 继续复用 `CustomWorldCreationStartCard` 和现有创作类型弹窗。
+- 不在创作页下方展示作品列表，避免“创作入口”和“作品管理”挤在同一首屏。
+
+草稿页复用创作中心作品架：
+
+- 默认显示全部作品列表，保留草稿/已发布筛选。
+- 入口、删除、分享、领取拼图激励等行为全部复用现有 `CustomWorldCreationHub` 的作品卡逻辑。
+- 一级底部 Tab 文案为“草稿”，内部仍可按草稿与已发布筛选。
+
+## 6. 我的页玩过列表
+
+“我的”页面的“玩过”列表弹层合并存档结构：
+
+- 顶部仍展示总游戏时长。
+- 列表先展示可恢复存档，使用原 `SaveArchiveCard` 的字段结构和恢复行为。
+- 再展示已玩作品统计列表，保持作品号、最近时间和时长。
+- 若某个存档被点击，必须继续走既有后端恢复接口，不在前端拼接运行态。
+
+## 7. 验收
+
+1. 移动端底部导航显示“推荐 / 发现 / 创作 / 草稿 / 我的”，未登录时显示“推荐 / 创作 / 发现”。
+2. 点击“推荐”直接看到公开作品推荐流，不再先看到搜索框和频道 Tab。
+3. 点击“发现”可看到搜索、推荐、今日、分类、排行子 Tab。
+4. 点击“草稿”看到原创作页作品列表。
+5. 点击“创作”只看到新建创作入口。
+6. “我的”里的“玩过”弹层包含原存档列表入口，点击存档能继续恢复。
+7. 移动端底部导航为悬浮胶囊样式，保留当前明暗主题色变量，不新增第三套主题。
+
+## 8. 2026-05-07 未登录三栏补充
+
+未登录状态下底部导航只显示 3 个入口，顺序调整为：
+
+1. 推荐
+2. 创作
+3. 发现
+
+创作 Tab 必须位于中间，并使用原推荐 Tab 的星光图标，保持几何和视觉上的主行动入口。推荐 Tab 改用游戏手柄图标，避免与创作图标重复。
@@ -12,6 +12,8 @@
 - [MOBILE_CREATION_NEW_WORK_COMPACT_LAYOUT_2026-04-24.md](./MOBILE_CREATION_NEW_WORK_COMPACT_LAYOUT_2026-04-24.md)：移动端创作页新建作品模块最多占用首屏约 1/3 高度的紧凑布局设计。
 - [MOBILE_CREATION_WORK_LIST_TWO_COLUMN_LAYOUT_2026-04-29.md](./MOBILE_CREATION_WORK_LIST_TWO_COLUMN_LAYOUT_2026-04-29.md)：移动端创作页作品列表至少 2 列的紧凑布局设计。
 - [PLATFORM_HOME_MOBILE_FEED_CARD_REDESIGN_2026-04-28.md](./PLATFORM_HOME_MOBILE_FEED_CARD_REDESIGN_2026-04-28.md)：平台首页移动端参考图式信息流、双端公开作品卡 16:9 封面结构与点赞数读模型设计。
+- [PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md](./PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md)：平台移动端推荐、发现、创作、草稿、我的 Tab 重新分工与推荐页/底部导航改版设计。
+- [PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md](./PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md)：平台创作 Tab 恢复模板 Tab 入口、默认选中拼图并内嵌拼图创作表单的布局设计。
 - [PLATFORM_CATEGORY_AND_CREATE_TAB_DESIGN_2026-04-24.md](./PLATFORM_CATEGORY_AND_CREATE_TAB_DESIGN_2026-04-24.md)：平台入口新增分类 Tab、登录态导航裁剪与创作 Tab 视觉强化设计。
 - [PLATFORM_BIG_FISH_ENTRY_HIDE_2026-04-28.md](./PLATFORM_BIG_FISH_ENTRY_HIDE_2026-04-28.md)：平台入口暂时隐藏大鱼吃小鱼创作卡片，但保留现有玩法链路。
 - [UNIFIED_MODAL_WINDOW_DESIGN_2026-04-25.md](./UNIFIED_MODAL_WINDOW_DESIGN_2026-04-25.md)：统一平台风与 RPG 像素风模态窗口外壳、交互边界和迁移顺序。
@@ -221,3 +221,8 @@
 - 后续新增怪物资源时，先检查红圈标注的实际落点，再调整锚点分档或单怪物偏移，避免出现“悬在地面上方”的状态。
 - 自定义世界里敌对角色已经先作为场景 NPC 存在，即使它同时携带 `characterId` 和 `monsterPresetId`，画布也不能直接沿用模板角色的 `groundOffsetY`；只要 encounter 自身有 `imageSrc` 或 `visual`，就按场景 NPC 自定义形象锚点处理。
 - 幕预览运行时还会构造“无 `characterId`、但有 `visual` 的场景 NPC”，这类和平相遇分支同样必须套用场景 NPC 自定义形象锚点，否则会停在画面中上部。
+
+### 10.3 移动端固定整页画布缩放
+- 主站移动端以固定游戏画布体验为准，入口 `viewport` 需要锁定 `minimum-scale=1.0`、`maximum-scale=1.0` 和 `user-scalable=no`，同时保留 `viewport-fit=cover` 适配安全区。
+- 浏览器仍可能通过 iOS `gesture*` 或多指 `touchmove` 触发整页缩放，因此主站启动入口应统一调用 `lockMobileViewportZoom()` 拦截页面级捏合与快速双击缩放。
+- 不要在每个画布组件里重复注册缩放拦截；单指滚动、点击、拖拽应继续留给具体页面和玩法处理。
@@ -29,6 +29,7 @@
 - [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 发布后首页 / 分类页公开作品列表刷新链路。
+- [VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md](./VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md)：记录视觉小说模板交接时的阅读顺序、常见坑和维护检查口径。
 - [AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md](./AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md)：记录 Agent 空会话不应进入作品草稿列表的后端判定规则。
 - [BIG_FISH_PUBLISH_FEEDBACK_FIX_2026-04-26.md](./BIG_FISH_PUBLISH_FEEDBACK_FIX_2026-04-26.md)：记录大鱼吃小鱼发布成功后结果页反馈与作品列表刷新的修复口径。
 - [BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md](./BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md)：记录大鱼作品列表 `items_json` 字段升级后的向后兼容修复口径，避免旧 JSON 直接打崩 works 接口。
@@ -0,0 +1,48 @@
+# 视觉小说模板交接与维护经验 2026-05-07
+
+## 1. 先读什么
+
+新开发者接手视觉小说时，建议按这个顺序看：
+
+1. [AI 原生视觉小说模板 PRD](../prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md)
+2. [视觉小说模板实现收口与交接说明](../technical/VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md)
+3. [SpacetimeDB 表说明与查询目录](../technical/SPACETIMEDB_TABLE_CATALOG.md)
+4. [视觉小说 VN-03 Prompt 与 LLM 工具实现说明](../technical/VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md)
+5. [视觉小说 VN-11 负向扫描报告](../audits/VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md)
+
+## 2. 最容易踩的坑
+
+1. 不要把 `visual_novel_runtime_history_entry` 当回放表来扩。
+2. 不要把 `visual_novel_runtime_event` 当业务回放数据源来用。
+3. 不要绕过平台资产对象去保存图片、音乐或文档。
+4. 不要让旧 TXT 迁移文档重新变成实现口径。
+5. 不要忘记发布后刷新作品架和公开聚合。
+6. 不要忘记退出登录时清理视觉小说私有状态。
+
+## 3. 维护时的判断顺序
+
+1. 先看是不是共享契约变化。
+2. 再看是不是 SpacetimeDB 表或 facade 变化。
+3. 然后看是不是作品架、广场或 runtime 的前端分流变化。
+4. 最后才看文档措辞和历史说明。
+
+## 4. 常用检查
+
+```bash
+npm run check:encoding
+npm run check:visual-novel-vn11
+npm run typecheck
+```
+
+如果改了后端，再补：
+
+```bash
+cd server-rs
+cargo test -p shared-contracts
+cargo test -p module-visual-novel
+cargo check -p api-server
+```
+
+## 5. 一句话结论
+
+视觉小说模板已经是平台内的正式模板玩法，不是外部平台迁移；后续维护只需要沿着 PRD、表目录、prompt 文档和这份交接说明往下走。
@@ -0,0 +1,20 @@
+# PRD 总览
+
+本目录用于存放产品需求、玩法闭环、阶段计划和可直接指导编码的需求拆分文档。
+
+## 重点入口
+
+- [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 创作、结果页、资产、试玩、发布到后端权威配置与前端高频运行表现的完整闭环。
+- [创意互动内容生成 Agent Phase 1 PRD：LangChain-Rust PoC + 拼图闭环](./CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md)：首版只支持拼图模板，Agent 使用 APIMart Responses `gpt-5` 支持文本和图像多模态输入，明确模板选择、积分范围、草稿字段填充、单关卡/多关卡图片生成、立即试玩、自然语言修改和可并行任务拆分。
+- [AI 原生 2048 游戏玩法模板 PRD](./AI_NATIVE_2048_GAMEPLAY_TEMPLATE_PRD_2026-05-05.md)：新增 `twenty-forty-eight` 玩法模板，定义主题化合成链创作、结果页、发布、公开运行、后端棋盘裁决、排行榜和并行落地任务。
+- [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)：后台管理端产品边界。
+
+## 使用规则
+
+- 新玩法、新 Agent 阶段、新创作闭环或较大功能落地前，优先补 PRD。
+- PRD 必须写到可以编码的程度，包含字段、接口、状态、验收和并行任务拆分。
+- 若 PRD 与最新代码或技术方案冲突，以代码和最新技术方案为准，并同步修正 PRD。
@@ -2,6 +2,8 @@

 更新时间：`2026-04-20`

+> 2026-05-05 更新口径：本文保留为历史参考。视觉小说模板后续落地以 [`AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`](./AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md) 为准；冲突时不再按“外部 TXT 模式原样迁入”执行，必须只保留模板玩法能力、完全使用 Genarrative 平台接口，并删除回放功能。
+
 ## 0. 文档目的

 这份 PRD 只定义 `Interactive-fiction-frontend` + `Interactive-fiction-backend` 中 TXT 模式在 `Genarrative` 落地时的**核心玩法闭环**。
@@ -115,3 +115,24 @@
 2. 该失败只代表登录方式配置探测失败，不代表登录功能不可用，因此不把 `读取登录方式失败` 写入登录弹窗错误条。
 3. 登录弹窗仍展示密码登录表单，玩家可继续登录后进入创作链路。
 4. 本地仍需要启动 `api-server`，否则后续 `POST /api/auth/entry` 等真实登录请求无法完成。
+
+## 9. 2026-05-07 本地短信入口恢复记录
+
+如果登录弹窗里短信登录页签“像是被删了”，先不要改前端表单，优先检查本地登录方式探测结果：
+
+1. 仓库根目录 `.env.local` 里必须显式保留 `SMS_AUTH_ENABLED=true`。
+2. 本地启动请优先使用 `npm run api-server`、`npm run dev:rust` 或 `npm run dev`，这些脚本会按“shell 环境优先、`.env.local` 覆盖 `.env`”合并配置。
+3. 若 `GET /api/auth/login-options` 只返回 `["password"]`，说明短信入口没有被服务端配置打开，前端只是按 contract 正常降级。
+4. 当 `SMS_AUTH_ENABLED=true` 生效时，`GET /api/auth/login-options` 至少应返回 `["phone", "password"]`，短信登录页签才会重新出现。
+
+## 10. 2026-05-07 前端代理端口错配修复记录
+
+如果 Rust API 直连返回 `["phone", "password"]`，但从前端域名请求 `GET /api/auth/login-options` 返回 `500`，短信页签同样会消失。此时不是登录 UI 被删除，而是 `AuthGate` 按第 5.3 节降级成 `["password"]`。
+
+本地排查顺序固定为：
+
+1. 先请求 `http://127.0.0.1:3000/api/auth/login-options`，确认前端代理是否成功返回 JSON。
+2. 再请求当前 Rust API 目标，例如 `http://127.0.0.1:3100/api/auth/login-options` 或 `http://127.0.0.1:8082/api/auth/login-options`。
+3. 若直连 API 成功而 3000 返回 `500`，检查 `RUST_SERVER_TARGET`、`GENARRATIVE_API_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET` 是否指向仍在监听的 API 端口。
+4. `npm run dev` / `npm run dev:rust` 完整栈默认由脚本计算 API 端口；加载 `.env.local` 给后端使用后，脚本必须重新固定 `RUST_SERVER_TARGET`，避免 `.env.local` 中的旧代理目标覆盖本次启动的实际 API 端口。
+5. `npm run dev:web` 只启动前端，不会自动拉起 Rust API；如果单独使用它，必须同时确认其打印的 backend target 已有 `api-server` 正在监听。
--- a/Show More
+++ b/Show More