视觉小说模板实现收口与交接说明 2026-05-07

1. 范围

本文记录 AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md 的 VN-13 收口结果，作为视觉小说模板后续维护的一页式入口。

本文只总结当前已经落地且需要长期遵守的实现边界，不再把视觉小说描述成外部 TXT 平台迁移，也不重复旧迁移方案里的临时讨论。

2. 当前正式入口

后续维护时优先看这些文档：

旧的 TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md 只保留历史参考意义，不再作为实现口径。

3. 已收口的实现边界

3.1 创作链路

创作链统一走 /api/creation/visual-novel/*。
入口、工作台、结果页和服务端 prompt 已围绕 visual-novel 模板闭环对齐。
VisualNovelResultDraft、VisualNovelCreationSessionSnapshot 等共享契约已经成型。

3.2 运行链路

运行链统一走 /api/runtime/visual-novel/*。
运行时只认 typed step 和快照，不让前端从 raw_text 猜业务真相。
visual_novel_runtime_history_entry 只用于继续体验和历史重生成边界，不是回放表。

3.3 数据链路

SpacetimeDB 首版只保留 6 张视觉小说表。
visual_novel_runtime_event 是 public event 审计事件表，不是 replay 数据源。
表结构变化必须同步 migration.rs、SPACETIMEDB_TABLE_CATALOG.md 和 Rust bindings。

3.4 作品与发布

作品架、广场和分享都复用平台现有链路。
公开作品码统一使用 VN- 前缀。
发布后要刷新作品架和公开聚合。

3.5 资产与登录态

文档、封面、背景、角色和音乐都只保留平台资产对象引用。
不保存大 Data URL、不走独立对象存储、不新增视觉小说私有存档系统。
退出登录时要清空视觉小说私有 session、work、run 和错误状态。

4. 长期维护规则

看到视觉小说相关改动，先确认是不是契约改动；如果是，先同步 TS / Rust shared contracts。
看到表结构改动，先同步 migration.rs 和表目录，再补 bindings。
看到资产链路改动，只改平台资产引用，不回退到本地路径或二进制直存。
看到运行时历史改动，只维护 typed history 和审计事件，不把它改成回放能力。
看到旧 TXT 文档时，只把它当历史来源，不把其中的平台工程目标重新带回实现。

5. 验证口径

收口后建议按下面顺序检查：

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

如果本轮没有改代码，只要编码检查和负向扫描通过，通常就说明 VN-13 的文档收口已经站稳。

3.3 KiB Raw Blame History