Genarrative/docs/experience/VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md

视觉小说模板交接与维护经验 2026-05-07

1. 先读什么

新开发者接手视觉小说时，建议按这个顺序看：

1. AI 原生视觉小说模板 PRD
2. 视觉小说模板实现收口与交接说明
3. SpacetimeDB 表说明与查询目录
4. 视觉小说 VN-03 Prompt 与 LLM 工具实现说明
5. 视觉小说 VN-11 负向扫描报告

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. 常用检查

npm run check:encoding
npm run check:visual-novel-vn11
npm run typecheck

如果改了后端，再补：

cd server-rs
cargo test -p shared-contracts
cargo test -p module-visual-novel
cargo check -p api-server

5. 一句话结论

视觉小说模板已经是平台内的正式模板玩法，不是外部平台迁移；后续维护只需要沿着 PRD、表目录、prompt 文档和这份交接说明往下走。