GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions 5 Packages Projects Releases Wiki Activity
Files
fda996031f4ec1664947d1a942cfbbbaa3fd73ea
Genarrative/docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md
高物 192accd796 1
2026-05-10 22:20:54 +08:00

69 KiB
Raw Blame History

AI 原生视觉小说模板 PRD：TXT 玩法平台化接入

更新时间：2026-05-05

0. 文档目的

这份 PRD 用于把 E:\Repos\Interactive-fiction-backend 与 E:\Repos\Interactive-fiction-frontend 中已经跑通的 TXT / visual novel 玩法经验，整理成 Genarrative 平台内的 visual-novel 视觉小说模板落地口径。

本次不是迁移外部两个仓库的平台工程，也不是复刻其账号、商城、后台、公开市场、推广、回放或独立存档系统。外部仓库只作为“视觉小说模板玩法”的参考实现来源；所有入口、账号、作品、资产、钱包、存档、发布、广场、任务和运行时访问，都必须使用 Genarrative 当前平台接口与 server-rs + Axum + SpacetimeDB 后端基线。

若本文与历史 TXT 文档冲突，以本文为准：

  • docs/prd/TXT_MODE_CORE_GAMEPLAY_PRD_2026-04-20.md
  • docs/technical/TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md

1. 一句话定义

visual-novel 是一个 AI 原生视觉小说模板：创作者可以用想法、文档或空白底稿生成并编辑世界观、角色、场景、剧情阶段和视觉资产，发布后玩家在平台运行时中通过对话、旁白、选项、场景切换和历史重生成体验故事；它只提供视觉小说模板玩法，不新增外部仓库里的平台类能力，并且彻底删除回放功能。

2. 参考仓库提炼结论

2.1 可吸收的玩法经验

从外部仓库中保留这些“模板玩法”能力：

  1. idea / document / blank 三种创作起点。
  2. 世界观、玩家身份、角色、场景、剧情阶段、初始剧情和文风配置。
  3. 视觉小说运行时 step 协议：场景切换、旁白、角色对白、转场、选择项、标记与指标变化。
  4. 流式运行时：开始、模型文本片段、结构化 step、完成、错误、结束。
  5. 文本模式、背景图、角色立绘、场景音乐和移动端适配的视觉小说阅读界面。
  6. 历史记录查看和基于历史节点的重生成。
  7. 存档 / 继续体验能力，但只能接入平台统一存档，不保留 TXT 私有存档接口。
  8. 属性面板作为模板可选能力，只能由平台配置或白名单开启，不默认扩散为所有作品规则。

2.2 必须删除或禁止迁入的内容

这些内容不得进入本模板 PRD 和后续实现：

  1. 回放、分享回放、回放列表、回放编译、回放进度条、回放模式、回放存储目录和任何 /replay API。
  2. 外部仓库的 D1 / R2 平台表、平台账户体系、订单、会员、订阅、促销、banner、标签管理、后台管理、小游戏平台分发、公开游戏市场、活动配置和独立支付逻辑。
  3. 外部仓库的独立作品库、独立浏览历史、独立云存档页、独立分享页和独立平台详情页。
  4. 旧 server-node、Express、PostgreSQL 或 Cloudflare Worker 平台逻辑作为新实现目标。
  5. 把视觉小说玩法做成第二套平台壳层，绕过现有创作中心、作品架、广场、钱包、资产和存档接口。

2.3 参考文件映射

外部仓库文件只作为玩法语义参考，不能作为目录结构迁入依据：

外部参考 可参考内容 Genarrative 落点
interface/routes/visual.js 视觉小说创作和运行时路由语义 server-rs/crates/api-server/src/visual_novel.rs
interface/handlers/visual/sendActionStream.js 流式动作推进事件 Axum SSE handler + shared-contracts typed envelope
interface/handlers/visual/getHistory.js 历史记录读取 平台 runtime history API
interface/handlers/visual/saves.js 存档语义 平台统一 profile/save-archives
services/visual/gameLogic.js step 解析、会话状态推进 server-rs/crates/module-visual-novel
services/visual/storyGeneration.js 创作底稿生成语义 platform-agent / platform-llm + visual novel Tool
prompts/visual.gm.system/1.0.1/body.js 视觉小说 GM 输出结构经验 新 prompt 必须适配 Genarrative 契约，不原样照搬平台规则
src/page/Galgame.tsx 运行时界面结构 src/components/visual-novel-runtime/VisualNovelRuntimeShell.tsx
src/hooks/galgame/useGalgameController.ts 前端运行时状态组织 visual novel runtime hooks
src/page/GameSettingsEditor.tsx 创作编辑器模块划分 visual novel result / workspace 组件

3. 产品边界

3.1 必须完成的模板闭环

  1. 平台创作中心展示 视觉小说 入口，并在实现完成后从 open: false 改为 open: true。
  2. 创作者可选择 idea、document、blank 三种起点创建视觉小说底稿。
  3. Agent 或表单工作台生成 / 编辑同一份 VisualNovelResultDraft。
  4. 结果页可编辑世界观、角色、场景、剧情阶段、资产和运行时配置。
  5. 结果页可进入测试运行时。
  6. 作品可保存为平台 work profile，并通过现有发布链路进入平台作品体系。
  7. 玩家从平台作品入口启动视觉小说 run。
  8. 玩家可提交自由行动或选择项，后端流式返回结构化 step。
  9. 玩家可查看历史、从最近历史节点重生成、保存和继续体验。
  10. 全链路不出现回放入口、回放接口、回放表、回放字段或分享回放能力。

3.2 明确不做

  1. 不迁移外部平台首页、详情页、作品市场、浏览历史、账号、钱包、运营、后台和推广能力。
  2. 不新增第二套支付点数系统；如产生消耗，走平台钱包流水。
  3. 不新增第二套资产系统；图片、音乐、文档附件走平台资产接口。
  4. 不新增第二套存档系统；视觉小说存档走平台统一 save archive。
  5. 不新增第二套发布、广场、作品架或分享体系。
  6. 不为视觉小说模板设计排行榜、赛季、活动任务、抽卡、会员权益等非模板玩法功能。
  7. 不把外部仓库的回放功能改名为历史、录屏、分享片段或故事录像。
  8. 不在 UI 面板默认展示大段规则说明、字段解释或模板内部协议。

3.3 历史 TXT 文档口径修正

历史文档中“原样迁入”“完整复制外部 TXT 模式”“替换为 server-node 能力”等表述全部降级为历史背景。后续实现必须遵循本文：

  1. 保留视觉小说玩法经验，不保留外部平台工程。
  2. 使用 server-rs + Axum + SpacetimeDB。
  3. 使用 Genarrative shared contracts。
  4. 删除回放。
  5. 存档、发布、资产、钱包和作品入口完全接平台能力。

4. 用户主流程

4.1 创作者流程

平台创作中心
-> 选择视觉小说
-> 视觉小说入口页只展示一句话创作输入框和视觉画风选项
-> 点击生成草稿
-> 进入 visual-novel-generating
-> 生成或补齐底稿
-> 进入 visual-novel-result
-> 编辑世界观、角色、场景、剧情阶段、资产和运行时配置
-> 点击试玩
-> 进入 visual-novel-runtime 测试 run
-> 返回结果页继续调整
-> 保存 / 发布到平台作品体系

4.2 玩家流程

平台作品入口
-> 打开视觉小说作品
-> 创建 runtime run
-> 阅读背景、旁白、对白
-> 点击选项或输入行动
-> 后端流式生成下一段故事 step
-> 查看历史 / 重生成 / 存档 / 继续体验

4.3 恢复流程

平台草稿 / 作品架 / 统一存档
-> 读取 visual-novel work profile 或 save archive
-> 恢复 visual-novel-result 或 visual-novel-runtime
-> 继续编辑或游玩

恢复入口只负责读取平台统一状态，不引入 TXT 私有 saveId 路由。

5. 创作模式

5.1 一句话创建 idea

用户输入一段自然语言，Agent 生成完整底稿。首轮至少产出：

  1. 作品标题。
  2. 一句话简介。
  3. 视觉画风。
  4. 世界观摘要。
  5. 玩家身份。
  6. 3 到 6 个主要角色。
  7. 3 到 8 个可用场景。
  8. 3 到 6 个剧情阶段。
  9. 初始场景、初始旁白和第一轮可选行动。

5.2 文档创建 document

用户上传 .txt、.md、.docx 或平台已有文档资产后创建底稿。

要求：

  1. 文档必须先走平台资产上传。
  2. 后端只持久化资产引用、摘要和结构化提取结果，不把原文大段重复写入玩法表。
  3. Agent 从文档中提取人物、场景、核心冲突、章节节奏和文风。
  4. 文档中缺失的角色视觉描述、场景视觉描述可以由 Agent 补齐，但必须标记来源为 agent_inferred。
  5. 文档过长时先做摘要和分段索引，不把整篇文档塞入运行时 prompt。

5.3 空白创建 blank

用户直接进入结果页，用空白底稿手动编辑。

空白底稿默认值：

  1. 标题：空字符串。
  2. 世界观、角色、场景、剧情阶段均为空数组或空字段。
  3. 运行时配置使用模板默认值。
  4. 发布前必须通过完整校验。

6. 草稿契约

6.1 VisualNovelResultDraft

新增 TypeScript 契约建议：

export interface VisualNovelResultDraft {
  profileId: string | null;
  workTitle: string;
  workDescription: string;
  workTags: string[];
  coverImageSrc: string | null;
  sourceMode: 'idea' | 'document' | 'blank';
  sourceAssetIds: string[];
  world: VisualNovelWorldDraft;
  characters: VisualNovelCharacterDraft[];
  scenes: VisualNovelSceneDraft[];
  storyPhases: VisualNovelStoryPhaseDraft[];
  opening: VisualNovelOpeningDraft;
  runtimeConfig: VisualNovelRuntimeConfigDraft;
  publishReady: boolean;
  validationIssues: VisualNovelValidationIssue[];
  updatedAt: string;
}

6.2 世界观

export interface VisualNovelWorldDraft {
  title: string;
  summary: string;
  background: string;
  premise: string;
  literaryStyle: string;
  playerRole: string;
  defaultTone: string;
}

字段要求：

  1. summary 用于作品卡和运行时上下文摘要，建议 40 到 120 字。
  2. background 可长一些，用于 GM prompt，但发布前应控制在后端配置上限内。
  3. playerRole 必须说明玩家在故事中的身份，不允许为空。
  4. literaryStyle 只描述叙事风格，不写平台规则。

6.3 角色

export interface VisualNovelCharacterDraft {
  characterId: string;
  name: string;
  gender: string | null;
  role: 'protagonist' | 'main' | 'supporting' | 'antagonist' | 'background';
  appearance: string;
  personality: string;
  tone: string;
  background: string;
  relationshipToPlayer: string;
  imageAssets: VisualNovelCharacterImageAsset[];
  defaultExpression: string | null;
  isPlayerVisible: boolean;
}

校验：

  1. 至少 1 个非玩家主要角色。
  2. 角色 name 不能为空。
  3. 角色立绘可为空，但若填写图片引用，必须是平台资产或受控生成图 URL。
  4. role = protagonist 只能用于玩家或核心视角角色。

6.4 场景

export interface VisualNovelSceneDraft {
  sceneId: string;
  name: string;
  description: string;
  backgroundImageSrc: string | null;
  musicSrc: string | null;
  ambientSoundSrc: string | null;
  availability: 'opening' | 'always' | 'phase_locked';
  phaseIds: string[];
}

校验：

  1. 至少 1 个 opening 场景。
  2. 场景名不能为空。
  3. 背景图和音乐走平台资产引用。
  4. phase_locked 场景必须绑定至少一个 phaseId。

6.5 剧情阶段

export interface VisualNovelStoryPhaseDraft {
  phaseId: string;
  title: string;
  goal: string;
  summary: string;
  entryCondition: string;
  exitCondition: string;
  sceneIds: string[];
  characterIds: string[];
  suggestedChoices: string[];
}

校验：

  1. 至少 1 个剧情阶段。
  2. 第一阶段必须能从 opening 进入。
  3. 每个阶段至少绑定一个场景或角色。
  4. suggestedChoices 只作为 GM 候选，不强制每轮展示。

6.6 开场

export interface VisualNovelOpeningDraft {
  sceneId: string | null;
  narration: string;
  speakerCharacterId: string | null;
  firstDialogue: string | null;
  initialChoices: VisualNovelChoiceDraft[];
}

发布前要求：

  1. sceneId 必须指向有效场景。
  2. narration 不能为空。
  3. initialChoices 至少 2 个，至多 4 个。

6.7 运行配置

export interface VisualNovelRuntimeConfigDraft {
  textModeEnabled: boolean;
  defaultTextMode: boolean;
  maxHistoryEntries: number;
  maxAssistantStepCountPerTurn: number;
  allowFreeTextAction: boolean;
  allowHistoryRegeneration: boolean;
  attributePanelMode: 'off' | 'platform_whitelist' | 'template_config';
  saveArchiveEnabled: boolean;
}

默认值：

  1. textModeEnabled = true
  2. defaultTextMode = false
  3. maxHistoryEntries = 80
  4. maxAssistantStepCountPerTurn = 8
  5. allowFreeTextAction = true
  6. allowHistoryRegeneration = true
  7. attributePanelMode = 'off'
  8. saveArchiveEnabled = true

7. 创作 Agent 契约

视觉小说可以接入通用创意 Agent，但目标模板必须明确为 visual-novel。若复用 creative-agent，其模板选择阶段必须只把视觉小说作为当前入口目标，不自动扩展到外部平台功能。

7.1 Session Snapshot

export interface VisualNovelAgentSessionSnapshot {
  sessionId: string;
  ownerUserId: string;
  sourceMode: 'idea' | 'document' | 'blank';
  status: 'collecting' | 'drafting' | 'ready' | 'failed';
  messages: VisualNovelAgentMessage[];
  draft: VisualNovelResultDraft | null;
  pendingAction: VisualNovelAgentPendingAction | null;
  createdAt: string;
  updatedAt: string;
}

7.2 Action

export type VisualNovelAgentActionKind =
  | 'generate_draft'
  | 'patch_world'
  | 'patch_character'
  | 'patch_scene'
  | 'patch_story_phase'
  | 'generate_scene_image'
  | 'generate_character_image'
  | 'compile_work_profile';

约束：

  1. compile_work_profile 只能生成平台 work profile，不发布作品。
  2. 发布必须走平台 works publish 接口。
  3. 图片生成 action 必须写回平台资产引用。
  4. action 不允许创建回放或分享片段。

7.3 流式事件

export type VisualNovelAgentStreamEvent =
  | { type: 'start'; sessionId: string }
  | { type: 'phase'; phase: 'perception' | 'reasoning' | 'drafting' | 'reflection' | 'finalizing' }
  | { type: 'text_delta'; text: string }
  | { type: 'draft_patch'; patch: VisualNovelDraftPatch }
  | { type: 'action_required'; action: VisualNovelAgentPendingAction }
  | { type: 'complete'; session: VisualNovelAgentSessionSnapshot }
  | { type: 'error'; message: string; retryable: boolean }
  | { type: 'done' };

8. 运行时契约

8.1 Run Snapshot

export interface VisualNovelRunSnapshot {
  runId: string;
  ownerUserId: string;
  profileId: string;
  mode: 'test' | 'play';
  status: 'active' | 'completed' | 'failed';
  currentSceneId: string | null;
  currentPhaseId: string | null;
  visibleCharacterIds: string[];
  flags: Record<string, string | number | boolean>;
  metrics: Record<string, number>;
  history: VisualNovelHistoryEntry[];
  availableChoices: VisualNovelChoiceDraft[];
  textModeEnabled: boolean;
  createdAt: string;
  updatedAt: string;
}

8.2 Action Request

export interface VisualNovelRuntimeActionRequest {
  actionKind: 'choice' | 'free_text' | 'continue';
  choiceId?: string;
  text?: string;
  clientEventId: string;
}

校验：

  1. choice 必须传有效 choiceId。
  2. free_text 必须在作品配置允许时可用。
  3. continue 用于不需要玩家输入的下一段推进。
  4. clientEventId 用于幂等，重复请求不得重复扣费或重复写历史。

8.3 Runtime Step

export type VisualNovelRuntimeStep =
  | VisualNovelSceneChangeStep
  | VisualNovelNarrationStep
  | VisualNovelDialogueStep
  | VisualNovelTransitionStep
  | VisualNovelChoiceStep
  | VisualNovelFlagStep
  | VisualNovelMetricStep;

export interface VisualNovelSceneChangeStep {
  type: 'scene_change';
  sceneId: string;
  backgroundImageSrc: string | null;
  musicSrc: string | null;
}

export interface VisualNovelNarrationStep {
  type: 'narration';
  text: string;
}

export interface VisualNovelDialogueStep {
  type: 'dialogue';
  characterId: string;
  characterName: string;
  expression: string | null;
  text: string;
}

export interface VisualNovelTransitionStep {
  type: 'transition';
  transitionKind: 'fade' | 'cut' | 'flash' | 'none';
  text: string | null;
}

export interface VisualNovelChoiceStep {
  type: 'choice';
  choices: VisualNovelChoiceDraft[];
}

export interface VisualNovelFlagStep {
  type: 'flag';
  key: string;
  value: string | number | boolean;
}

export interface VisualNovelMetricStep {
  type: 'metric';
  key: string;
  delta: number;
}

8.4 History Entry

export interface VisualNovelHistoryEntry {
  entryId: string;
  runId: string;
  turnIndex: number;
  source: 'player' | 'assistant' | 'system';
  actionText: string | null;
  steps: VisualNovelRuntimeStep[];
  snapshotBeforeHash: string | null;
  snapshotAfterHash: string | null;
  createdAt: string;
}

历史用于查看和重生成，不是回放。历史不提供可分享播放页，不保存可独立播放的回放包。

8.5 SSE Envelope

运行时动作接口返回 SSE：

export type VisualNovelRuntimeStreamEvent =
  | { type: 'start'; runId: string }
  | { type: 'raw_text'; text: string }
  | { type: 'step'; step: VisualNovelRuntimeStep }
  | { type: 'snapshot'; run: VisualNovelRunSnapshot }
  | { type: 'complete'; run: VisualNovelRunSnapshot }
  | { type: 'error'; message: string; retryable: boolean }
  | { type: 'done' };

要求：

  1. 前端只能以 step 作为正式 UI 状态来源。
  2. raw_text 只用于流式观感和调试，不作为最终历史真相。
  3. complete 必须返回后端落库后的 run snapshot。
  4. 错误时保留已展示的可确认 step，并允许用户重试当前动作。

9. 平台 API 设计

路由必须遵循现有玩法接口风格：创作链走 /api/creation/visual-novel/*，运行链走 /api/runtime/visual-novel/*。不得新增 /visual/replay、/galgame/replay、/txt/replay 或任何同义回放路由。

9.1 创作 session

方法 路由 用途
POST /api/creation/visual-novel/sessions 创建视觉小说创作 session
GET /api/creation/visual-novel/sessions/{session_id} 读取 session snapshot
POST /api/creation/visual-novel/sessions/{session_id}/messages 非流式发送创作消息
POST /api/creation/visual-novel/sessions/{session_id}/messages/stream 流式发送创作消息
POST /api/creation/visual-novel/sessions/{session_id}/actions 执行结构化创作 action
POST /api/creation/visual-novel/sessions/{session_id}/compile 编译为 work profile 草稿

9.2 作品草稿与发布

方法 路由 用途
GET /api/creation/visual-novel/works 读取当前用户视觉小说作品草稿列表
GET /api/creation/visual-novel/works/{profile_id} 读取作品详情
PUT/PATCH /api/creation/visual-novel/works/{profile_id} 更新作品草稿
DELETE /api/creation/visual-novel/works/{profile_id} 删除未发布草稿或用户自有作品
POST /api/creation/visual-novel/works/{profile_id}/publish 发布到平台作品体系

9.3 运行时

方法 路由 用途
GET /api/runtime/visual-novel/gallery 读取平台聚合后的视觉小说公开作品列表
POST /api/runtime/visual-novel/works/{profile_id}/runs 创建测试或正式 run
GET /api/runtime/visual-novel/runs/{run_id} 读取 run snapshot
POST /api/runtime/visual-novel/runs/{run_id}/actions/stream 提交选择 / 自由行动并流式推进
GET /api/runtime/visual-novel/runs/{run_id}/history 读取当前 run 历史
POST /api/runtime/visual-novel/runs/{run_id}/regenerate 从历史节点重生成

9.4 存档

视觉小说不设计私有 save API。统一使用平台 save archive：

POST /api/runtime/profile/save-archives
POST /api/runtime/profile/save-archives/{world_key}
GET  /api/runtime/profile/save-archives

视觉小说写入 archiveState.runtimeKind = 'visual-novel'，并保存：

  1. profileId
  2. runId
  3. currentSceneId
  4. currentPhaseId
  5. historyCursor
  6. snapshotHash
  7. 必要的继续体验状态

9.5 明确禁止的接口

后续实现和测试必须确认不存在：

/api/creation/visual-novel/replay
/api/runtime/visual-novel/replay
/api/runtime/visual-novel/replays
/api/visual/replay
/api/galgame/replay
/api/txt/replay

10. 后端 DDD 落点

10.1 crate 职责

crate / 层 职责
server-rs/crates/module-visual-novel 纯领域规则：草稿校验、step 解析、run 状态推进、历史重生成边界
server-rs/crates/shared-contracts DTO、请求响应、SSE envelope、草稿和运行时契约
server-rs/crates/spacetime-module 表、reducer、procedure、migration 和事务编排
server-rs/crates/spacetime-client api-server 到 SpacetimeDB 的 typed facade
server-rs/crates/api-server Axum 路由、鉴权、SSE、LLM 编排、资产和钱包 facade 调用
server-rs/crates/platform-llm 视觉小说创作和运行时 GM 的模型调用
server-rs/crates/platform-oss 文档、图片、音乐等资产对象读写
server-rs/crates/platform-agent 如复用创意 Agent，负责 Agent 编排和工具注册

10.2 领域规则

module-visual-novel 至少提供：

  1. validate_visual_novel_draft(draft)：发布前校验。
  2. compile_visual_novel_profile(draft)：草稿转 work profile 领域结构。
  3. parse_runtime_steps(model_output)：把模型输出解析为 typed steps。
  4. apply_runtime_steps(snapshot, steps)：推进 run snapshot。
  5. build_runtime_prompt_context(profile, snapshot, action)：构造最小 GM 上下文。
  6. regenerate_from_history(snapshot, history_entry_id)：历史重生成状态回滚。
  7. build_save_archive_state(snapshot)：构造平台存档状态。

10.3 SpacetimeDB 表建议

新增表必须同步 migration.rs、表目录和 bindings：

表 用途
visual_novel_agent_session 创作 session 主表
visual_novel_agent_message 创作消息和模型回复
visual_novel_work_profile 视觉小说作品草稿 / 发布 profile
visual_novel_runtime_run 玩家或测试 run
visual_novel_runtime_history_entry 运行时历史
visual_novel_runtime_event 可审计事件，不用于回放

不得新增：

  1. visual_novel_replay
  2. visual_novel_replay_segment
  3. visual_replay
  4. galgame_replay
  5. 任意 *_private_save 私有存档表

10.4 LLM 与副作用

  1. 创作底稿生成和运行时 GM 输出由 api-server 编排 platform-llm，SpacetimeDB reducer 不直接调用 LLM。
  2. 图片和音乐生成 / 上传由 api-server 编排平台资产服务，不把二进制写入 SpacetimeDB。
  3. 消耗光点时走平台钱包流水；不得迁入外部仓库积分表。
  4. prompt 必须输出可解析 JSON step 或工具调用结果；解析失败时由后端 repair，不让前端猜测业务状态。

11. 前端接入

11.1 入口配置

当前 src/config/newWorkEntryConfig.ts 已存在：

{
  id: 'visual-novel',
  title: '视觉小说',
  subtitle: '敬请期待',
  badge: '敬请期待',
  visible: true,
  open: false,
}

实现完成后更新为：

{
  id: 'visual-novel',
  title: '视觉小说',
  subtitle: 'AI 生成可玩的视觉小说',
  badge: '新玩法',
  visible: true,
  open: true,
}

文案可在上线前按平台风格微调，但 UI 不展示大段说明。

11.2 SelectionStage

在 src/components/platform-entry/platformEntryTypes.ts 增加：

| 'visual-novel-agent-workspace'
| 'visual-novel-result'
| 'visual-novel-runtime'
| 'visual-novel-gallery-detail'

如创建过程需要独立生成页，可增加：

| 'visual-novel-generating'

11.3 流程分流

在 src/components/platform-entry/PlatformEntryFlowShellImpl.tsx：

  1. 删除或替换当前 visual-novel 的 early return。
  2. handleCreationHubCreateType('visual-novel') 进入 visual-novel-agent-workspace。
  3. 新增 openVisualNovelAgentWorkspace()。
  4. 新增 leaveVisualNovelFlow()。
  5. 新增 submitVisualNovelMessage()。
  6. 新增 executeVisualNovelAction()。
  7. 新增 result / runtime / gallery detail 渲染分支。
  8. 退出登录时清空视觉小说私有 session、draft、run 状态。

11.4 组件建议

src/components/visual-novel-creation/VisualNovelAgentWorkspace.tsx
src/components/visual-novel-result/VisualNovelResultView.tsx
src/components/visual-novel-runtime/VisualNovelRuntimeShell.tsx
src/components/visual-novel-runtime/useVisualNovelRuntimeController.ts
src/components/visual-novel-runtime/VisualNovelHistoryPanel.tsx
src/components/visual-novel-runtime/VisualNovelSavePanel.tsx
src/components/visual-novel-runtime/VisualNovelSettingsPanel.tsx
src/components/visual-novel-runtime/VisualNovelAttributePanel.tsx

11.5 service client

src/services/visual-novel-creation/index.ts
src/services/visual-novel-creation/visualNovelCreationClient.ts
src/services/visual-novel-works/index.ts
src/services/visual-novel-works/visualNovelWorksClient.ts
src/services/visual-novel-runtime/index.ts
src/services/visual-novel-runtime/visualNovelRuntimeClient.ts

service client 要复用现有请求封装、鉴权和错误提示风格，不引入外部仓库 API client。

12. UI 与交互要求

12.1 工作台

入口页只展示创作需要的输入和状态：

  1. 一句话创作输入框。
  2. 视觉画风选项，参考抓大鹅入口页的横向卡片选择结构。
  3. 生成草稿按钮。
  4. 错误、忙碌与禁用态。

点击生成草稿后进入 visual-novel-generating 过程页，过程页复用平台已有生成进度面板，展示一句话输入、画风和草稿生成阶段；完成后自动进入 visual-novel-result 草稿页。

不展示：

  1. 平台规则说明。
  2. 外部仓库平台功能介绍。
  3. 文档 / 空白创建入口。
  4. Agent 对话侧栏。
  5. 回放、分享回放、录像、复盘入口。
  6. 大段字段解释。

12.2 结果页

结果页按模块编辑：

  1. 基本信息：标题、简介、标签、封面。
  2. 世界观：摘要、背景、玩家身份、文风。
  3. 角色：名称、身份、性格、外貌、语气、立绘。
  4. 场景：名称、描述、背景图、音乐、可用阶段。
  5. 剧情阶段：目标、进入条件、退出条件、候选选项。
  6. 运行配置：文本模式、自由输入、历史重生成、属性面板模式。

按钮打开历史、设置、角色编辑、场景编辑等复杂内容时，必须使用独立弹层 / 抽屉 / 全屏面板，不在当前卡片下方展开长内容。

12.3 运行时

运行时首屏是视觉小说体验，不是说明页。

必须具备：

  1. 背景区域。
  2. 角色立绘区域。
  3. 文本框。
  4. 选择项区域。
  5. 自由输入区域。
  6. 历史按钮。
  7. 存档按钮。
  8. 设置按钮。
  9. 文本模式切换。

移动端要求：

  1. 文本框和选择项不遮挡关键按钮。
  2. 历史、存档、设置使用底部抽屉或全屏面板。
  3. 横屏和竖屏都可读。
  4. 长角色名、长选项文本必须换行或截断，不撑破按钮。
  5. 立绘缺失时用安静占位，不写说明文案。

12.4 回放删除验收

UI 中不得出现：

  1. 回放。
  2. 分享回放。
  3. 录制。
  4. 播放记录。
  5. 回放列表。
  6. 回放进度条。
  7. 复制回放链接。

历史记录只叫“历史”，用于当前 run 内查看和重生成，不生成可分享播放页面。

13. 平台能力复用

13.1 作品体系

视觉小说作品必须接入平台现有 work profile / works / gallery 聚合方式。PRD 不新增平台作品系统，只要求视觉小说 profile 提供平台聚合所需的最小摘要：

export interface VisualNovelWorkSummary {
  runtimeKind: 'visual-novel';
  profileId: string;
  ownerUserId: string;
  title: string;
  description: string;
  coverImageSrc: string | null;
  tags: string[];
  publishStatus: 'draft' | 'published';
  updatedAt: string;
}

13.2 资产

  1. 文档、封面、场景图、角色立绘、音乐都必须进入平台资产系统。
  2. 视觉小说表只保存 assetId、readUrl、用途和元数据。
  3. 前端不把大 Data URL 写入长期状态。

13.3 钱包

V1 消耗口径：

  1. 创作草稿生成可配置为免费或按平台统一创作 Agent 计费。
  2. 运行时每次 AI 推进如需扣费，走平台 profile_wallet_ledger。
  3. 幂等键使用 clientEventId 或后端 action id。
  4. 不迁入外部仓库积分、订单、会员或订阅表。

具体单价由运营配置决定，本文不新增视觉小说私有计费系统。

13.4 统一存档

视觉小说存档接入平台统一 save archive。作品内可展示“存档”按钮，但背后读写平台存档接口，不保留外部 TXT 五槽私有 save API。

V1 默认提供平台统一存档能力；如果平台存档 UI 当前按槽位展示，则视觉小说可在平台槽位中写入 runtimeKind = 'visual-novel' 的 archive state。

14. Prompt 与模型输出约束

14.1 创作 Prompt

创作 prompt 目标是生成 VisualNovelResultDraft，不能输出外部平台配置。

必须要求模型：

  1. 输出中文视觉小说内容。
  2. 补齐世界、角色、场景、剧情阶段和开场。
  3. 每个角色有可生成立绘的外貌描述。
  4. 每个场景有可生成背景图的视觉描述。
  5. 不输出回放、分享、商城、平台活动或运营字段。
  6. 不输出 UI 规则说明。

14.2 运行时 GM Prompt

运行时 prompt 目标是生成 VisualNovelRuntimeStep[]。

必须要求模型：

  1. 每轮最多输出 maxAssistantStepCountPerTurn 个 step。
  2. 关键剧情变化用 flag 或 metric 明确表达。
  3. 有选择时输出 choice step。
  4. 场景变化必须输出 scene_change。
  5. 不输出 Markdown 规则说明。
  6. 不输出回放元数据。

14.3 Repair

解析失败时：

  1. 后端先进行结构化 repair。
  2. repair 仍失败则返回可重试错误。
  3. 不让前端根据 raw text 自行生成业务 step。

15. 分阶段落地

Phase 0：文档和口径冻结

  1. 新增本文。
  2. 在旧 TXT 文档顶部标注冲突时以本文为准。
  3. 文档索引加入视觉小说模板 PRD。

Phase 1：创作入口和底稿

  1. 打开 visual-novel 入口。
  2. 增加 selection stage。
  3. 新增 shared contracts。
  4. 新增创作 session API。
  5. 支持 idea / document / blank 创建底稿。
  6. 新增 VisualNovelResultView。

Phase 2：作品与测试运行

  1. 草稿保存为 visual novel work profile。
  2. 接平台作品架。
  3. 支持测试 run。
  4. 支持场景、旁白、对白、选项 step 渲染。

Phase 3：正式运行闭环

  1. 正式 run。
  2. 动作流式推进。
  3. 历史记录。
  4. 历史重生成。
  5. 平台统一存档 / 继续体验。

Phase 4：发布收口

  1. 发布到平台作品体系。
  2. 接平台公开聚合。
  3. 移动端 UI 验收。
  4. 回放和外部平台功能负向扫描。

16. 可并行任务拆分

本节把视觉小说模板落地拆成可多人并行推进的任务包。每个任务包必须遵守同一条硬边界：只做 visual-novel 模板玩法，复用 Genarrative 平台接口，不迁入外部平台功能，不实现回放。

16.1 并行批次总览

批次 可并行任务 进入条件 汇合点
Batch 0 VN-00 PRD 已冻结 所有人以本文为唯一口径
Batch 1 VN-01、VN-02、VN-03、VN-04 VN-00 完成 契约、领域、UI 骨架、Prompt 口径可对齐
Batch 2 VN-05、VN-06、VN-07、VN-08 VN-01 产出契约初稿；VN-02 产出表草案 后端 API、前端创作、前端运行时可联调
Batch 3 VN-09、VN-10、VN-11 VN-05、VN-06、VN-07、VN-08 主链路可跑 发布、存档、广场、负向扫描收口
Batch 4 VN-12、VN-13 主链路完成 全链路验收和文档同步

并行规则：

  1. 同一批次任务可以同时开工。
  2. 不同任务必须尽量使用不重叠写入边界；确需改同一文件时，先约定编辑区域。
  3. VN-01 是所有工程任务的契约源头；若契约发生破坏性变更，需要通知 VN-02 到 VN-09。
  4. VN-11 负向扫描不是最后才做，Batch 1 开始后每个任务都要自查，但最终由 VN-11 统一验收。

16.2 并行任务具体要求速查表

任务 可并行窗口 输入依赖 必须完成 禁止事项 验收口径
VN-00 口径冻结 Batch 0 本 PRD、旧 TXT 文档、Hermes 决策记录 冻结 visual-novel 只做模板玩法、平台接口、删除回放；标注旧文档冲突口径 不再使用“原样迁入外部平台工程”作为实现目标 文档和 Hermes 记录明确三条硬边界；npm run check:encoding 通过
VN-01 契约与领域 Batch 1 PRD 第 6 到 8 章契约 TS contracts、Rust shared-contracts、module-visual-novel、领域单测 不写 HTTP、DB reducer、LLM、UI；不出现 replay 类型 TS/Rust 契约一致；草稿校验、step 解析、状态推进、重生成测试通过
VN-02 SpacetimeDB 与 facade Batch 1 VN-01 契约草案、SpacetimeDB 约束文档 表、reducer/procedure、migration、表目录、bindings、spacetime-client facade 不手改 bindings 绕过 schema；不建 replay 表或私有 save 表 schema 可生成；表目录写明 event 不是回放；cargo check -p spacetime-client 通过
VN-03 Prompt / LLM 工具 Batch 1 VN-01 draft 与 step 契约 创作 prompt、运行 GM prompt、repair prompt、工具参数 不照搬外部平台规则、扣费规则、回放规则；不让前端猜业务 step fixture 输出可解析；坏格式进入 repair 或可重试错误
VN-04 前端 UI 骨架 Batch 1 PRD 第 12 章 UI 要求 workspace、result、runtime mock 骨架；移动端优先布局；独立面板模式 不接真实 API；不写规则长文；不出现回放入口 桌面 / 移动基础布局可检查；长文本不撑破按钮
VN-05 API Server Batch 2 VN-01、VN-02，真实 LLM 依赖 VN-03 creation、works、runtime、history、regenerate 路由；SSE；平台 save archive 接入 不把领域规则塞 handler；不新增 replay 路由；不新增私有 save API /api/creation/visual-novel/* 和 /api/runtime/visual-novel/* 可 smoke；cargo check -p api-server 通过
VN-06 前端 service 与入口 Batch 2 VN-01 TS 契约草案；mock 可先行 service client、selection stage、入口分流、壳层挂载、登录态清理 不设计表单细节；不写 runtime UI 细节；不绕过平台入口 创作中心可进入 workspace；service 路由与 PRD 一致；npm run typecheck 通过
VN-07 创作工作台与结果页 Batch 2 VN-04、VN-06，真实生成依赖 VN-05 idea / document / blank、Agent 进度、结果页表单、保存草稿、测试 run 入口 不做正式玩家 runtime；不新增说明页；复杂内容不在卡片下展开 三种创建起点可用；草稿写入 VisualNovelResultDraft；发布校验 issue 可见
VN-08 前端运行时 Batch 2 VN-04、VN-06，真实运行依赖 VN-05 runtime shell、SSE 消费、step 渲染、历史、设置、存档、重生成 不做回放 UI；历史不生成分享播放页；raw_text 不作为业务真相 typed step 可渲染；历史与重生成可用；save archive 可继续体验
VN-09 作品架 / 广场 / 发布 Batch 3 VN-05 works/gallery API、VN-06 壳层 work summary 聚合、作品架、公开聚合、public work code、详情跳转 不新增独立视觉小说市场；不迁入外部平台详情页；不做分享回放 发布后作品架可见；公开作品可启动 run；聚合 key 不冲突
VN-10 资产与文档输入 Batch 3 VN-05 action/API、平台资产接口 文档资产读取、封面/场景/角色/音乐资产引用、可选图片生成 action 不迁入外部 R2；不存大 Data URL；不绕过资产鉴权 文档创建使用资产引用；SpacetimeDB 不保存二进制或大 base64
VN-11 负向扫描 Batch 1 到发布前 所有任务增量改动 扫描 replay 和外部平台功能；补负向测试或脚本清单 不把历史误判为回放；不做大范围重构 新工程代码无 replay；外部平台账号/订单/会员/后台等未误入
VN-12 全链路验收 Batch 4 VN-05 到 VN-10 主链路完成 创作、结果页、测试 run、发布、正式 run、历史、重生成、存档联调 不跳过移动端；不只测 mock；不忽略负向验收 全链路可跑；前端 typecheck、后端相关 cargo 检查、编码检查通过
VN-13 文档与交接 Batch 4 实际工程落地结果 PRD、技术方案、表目录、Hermes 决策 / 踩坑同步 不让旧 TXT 文档重新成为实现口径；不留下过期接口描述 新开发者可按最新文档维护；文档与代码一致

每个任务的交付回复必须包含：

  1. 任务编号和 owner。
  2. 改动文件清单。
  3. 已完成的“必须完成”项。
  4. 明确声明未触碰的“禁止事项”。
  5. 已执行验证命令和结果。
  6. 剩余风险或依赖其他任务的联调点。

16.3 任务详情

VN-00：任务准备与口径冻结

负责范围：

  1. 确认本文、旧 TXT PRD 顶部提示和 Hermes 决策记录都已同步。
  2. 确认 visual-novel 的产品边界是模板玩法，不是迁移外部平台。
  3. 确认回放删除是全链路强约束。

主要文件：

  1. docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md
  2. docs/prd/TXT_MODE_CORE_GAMEPLAY_PRD_2026-04-20.md
  3. docs/technical/TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md
  4. .hermes/shared-memory/decision-log.md

交付物：

  1. 本 PRD 保持最新。
  2. 旧文档冲突口径已经标注。
  3. 后续任务不再引用“原样迁入外部平台工程”。

验收：

  1. 文档中明确写出“不迁入外部平台功能”和“删除回放”。
  2. npm run check:encoding 通过。

VN-01：共享契约与领域模型

负责范围：

  1. 新增前端 TypeScript shared contracts。
  2. 新增 Rust shared-contracts DTO。
  3. 新增 module-visual-novel 纯领域 crate。
  4. 实现草稿校验、运行时 step 解析、run snapshot 推进、历史重生成边界和存档状态构造。

主要文件：

  1. packages/shared/src/contracts/visualNovel*.ts
  2. packages/shared/src/contracts/index.ts
  3. packages/shared/src/index.ts
  4. server-rs/crates/shared-contracts/src/visual_novel*.rs
  5. server-rs/crates/shared-contracts/src/lib.rs
  6. server-rs/crates/module-visual-novel/
  7. server-rs/Cargo.toml

不负责：

  1. 不写 HTTP handler。
  2. 不写 SpacetimeDB reducer。
  3. 不调用 LLM 或 OSS。
  4. 不做 UI。

交付物：

  1. VisualNovelResultDraft、VisualNovelAgentSessionSnapshot、VisualNovelRunSnapshot、VisualNovelRuntimeStep、VisualNovelRuntimeStreamEvent 等契约。
  2. Rust 与 TS 字段语义一致。
  3. 领域单测覆盖发布校验、step 解析失败、状态推进、历史重生成和 save archive state。

验收命令：

npm run typecheck

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

阻塞关系：

  1. 阻塞 VN-02、VN-05、VN-06、VN-07、VN-08 的正式联调。
  2. 可以先输出契约草案，让前后端用 mock 并行开发。

VN-01 实施收口记录（2026-05-05）：

  1. 已新增前端共享契约 packages/shared/src/contracts/visualNovel.ts，并从 packages/shared/src/contracts/index.ts 与 packages/shared/src/index.ts 导出。
  2. 已新增 Rust DTO server-rs/crates/shared-contracts/src/visual_novel.rs，字段命名与 TypeScript 契约保持 camelCase / snake_case / lowercase 语义一致。
  3. 已新增纯领域 crate server-rs/crates/module-visual-novel/，只覆盖草稿发布校验、runtime step 解析、run snapshot 推进、历史重生成边界、runtime prompt context 构造和平台 save archive state 构造。
  4. 本阶段未新增 HTTP handler、SpacetimeDB reducer / table / migration、LLM / OSS 调用、前端入口或 UI 能力；后续 VN-02 / VN-05 / VN-06 仍需基于本契约继续接入。
  5. 已补领域单测覆盖发布校验、step 解析失败、状态推进、历史重生成和 save archive state；验证命令以本节验收命令为准。

VN-02：SpacetimeDB 表、迁移与 facade

负责范围：

  1. 新增视觉小说创作 session、message、work profile、runtime run、history entry、runtime event 表。
  2. 新增 reducer / procedure。
  3. 同步 migration.rs 和表目录。
  4. 生成 bindings。
  5. 新增 spacetime-client facade。

主要文件：

  1. server-rs/crates/spacetime-module/src/visual_novel.rs
  2. server-rs/crates/spacetime-module/src/lib.rs
  3. server-rs/crates/spacetime-module/src/migration.rs
  4. docs/technical/SPACETIMEDB_TABLE_CATALOG.md
  5. server-rs/crates/spacetime-client/src/visual_novel.rs
  6. server-rs/crates/spacetime-client/src/lib.rs
  7. server-rs/crates/spacetime-client/src/module_bindings/

不负责：

  1. 不写 Axum 路由。
  2. 不写 LLM prompt。
  3. 不手改生成 bindings 来绕过 schema 问题。
  4. 不新增 replay 或私有 save 表。

交付物：

  1. 表和 procedure 能支撑创作、作品、运行、历史和审计事件。
  2. spacetime-client 暴露 typed facade 给 api-server。
  3. 表目录写明每张表用途，明确 runtime event 不是回放。

验收命令：

npm run spacetime:generate -- --rust-only

cd server-rs
cargo check -p spacetime-client

阻塞关系：

  1. 依赖 VN-01 的 Rust 契约。
  2. 阻塞 VN-05 的真实数据库联调。

VN-02 实施收口记录（2026-05-05）：

  1. 已新增 server-rs/crates/spacetime-module/src/visual_novel.rs，落地 visual_novel_agent_session、visual_novel_agent_message、visual_novel_work_profile、visual_novel_runtime_run、visual_novel_runtime_history_entry、visual_novel_runtime_event 六张表及对应 procedure。
  2. 已同步 server-rs/crates/spacetime-module/src/lib.rs、server-rs/crates/spacetime-module/src/migration.rs、docs/technical/SPACETIMEDB_TABLE_CATALOG.md 和 Rust bindings。
  3. 已新增 server-rs/crates/spacetime-client/src/visual_novel.rs typed facade，并从 server-rs/crates/spacetime-client/src/lib.rs 导出视觉小说 record / input 类型。
  4. visual_novel_runtime_event 只作为 public event 审计事件表使用；visual_novel_runtime_history_entry 只保存继续体验与历史重生成所需 step 和快照哈希，二者均不是 replay 数据源。
  5. 本阶段未新增 Axum 路由、LLM prompt、前端 UI、replay 表、replay 路由或私有 save 表；后续 VN-05 只应通过本阶段 facade 接入真实数据库。

VN-03：创作与运行 Prompt / LLM 工具

负责范围：

  1. 设计视觉小说底稿生成 prompt。
  2. 设计视觉小说运行时 GM prompt。
  3. 设计结构化 repair prompt。
  4. 定义创作 action 与图片生成 action 的工具参数。
  5. 接入 platform-llm 和可选 platform-agent 的 adapter 口径。

主要文件：

  1. server-rs/crates/api-server/src/prompt/visual_novel.rs
  2. server-rs/crates/platform-llm/src/
  3. server-rs/crates/platform-agent/src/，仅当复用 Agent 编排时修改
  4. server-rs/crates/module-visual-novel/src/，仅补 prompt 输入结构时修改

不负责：

  1. 不保存数据。
  2. 不写前端 UI。
  3. 不照搬外部 prompt 中的平台规则、扣费规则或回放规则。

交付物：

  1. 创作 prompt 输出 VisualNovelResultDraft。
  2. 运行 prompt 输出 VisualNovelRuntimeStep[]。
  3. repair 能把坏格式修成 typed step。
  4. prompt 明确禁止输出回放、商城、会员、后台、平台活动字段。

验收：

  1. prompt fixture 能解析为契约结构。
  2. 错误样例能进入 repair 或返回可重试错误。

阻塞关系：

  1. 依赖 VN-01 的 step 和 draft 契约。
  2. 与 VN-05 并行，但 VN-05 的真实 LLM 输出依赖本任务。

VN-04：前端视觉规范与组件骨架

负责范围：

  1. 定义视觉小说 workspace、result、runtime 的前端组件骨架。
  2. 先用 mock data 搭出移动端优先布局。
  3. 建立历史、存档、设置、属性面板的独立弹层 / 抽屉模式。
  4. 确认 UI 中不出现规则长文和回放入口。

主要文件：

  1. src/components/visual-novel-creation/
  2. src/components/visual-novel-result/
  3. src/components/visual-novel-runtime/
  4. src/index.css，仅在需要公共样式 token 时局部修改

不负责：

  1. 不接真实 API。
  2. 不修改平台入口分流。
  3. 不实现后端逻辑。

交付物：

  1. VisualNovelAgentWorkspace mock 版。
  2. VisualNovelResultView mock 版。
  3. VisualNovelRuntimeShell mock 版。
  4. 移动端和桌面端基础布局可检查。

验收：

  1. UI 无长说明文案。
  2. 按钮打开复杂内容时使用独立面板，不在当前面板下方展开。
  3. 长角色名、长选项文本不撑破按钮。

阻塞关系：

  1. 可与 VN-01 并行，用临时本地类型；合并前必须切回 shared contracts。
  2. 为 VN-07、VN-08 提供 UI 基础。

VN-05：API Server 创作、作品与运行路由

负责范围：

  1. 新增 api-server 视觉小说路由模块。
  2. 接创作 session、message、stream、action、compile。
  3. 接 works CRUD 和 publish。
  4. 接 runtime run、action stream、history、regenerate。
  5. 编排 spacetime-client、platform-llm、platform-oss、钱包和 save archive。

主要文件：

  1. server-rs/crates/api-server/src/visual_novel.rs
  2. server-rs/crates/api-server/src/app.rs
  3. server-rs/crates/api-server/src/main.rs
  4. server-rs/crates/api-server/src/prompt/visual_novel.rs，如 VN-03 已建则只接入
  5. server-rs/crates/api-server/tests/，按现有测试结构补 smoke

不负责：

  1. 不新增表结构。
  2. 不把领域规则写进 handler。
  3. 不新增 replay 路由。
  4. 不新增视觉小说私有 save API。

交付物：

  1. /api/creation/visual-novel/* 路由可用。
  2. /api/runtime/visual-novel/* 路由可用。
  3. SSE 事件使用 shared-contracts envelope。
  4. 存档调用平台统一 save archive。

验收命令：

cd server-rs
cargo check -p api-server
cargo test -p api-server visual_novel

实现状态（2026-05-05）：

  1. 已新增 server-rs/crates/api-server/src/visual_novel.rs，通过 spacetime-client facade 编排 creation、works、gallery、runtime、history、regenerate 路由。
  2. 已在 app.rs 挂载 /api/creation/visual-novel/* 与 /api/runtime/visual-novel/*；除公开 gallery 外均使用 bearer auth。
  3. SSE 输出使用 shared-contracts 中的视觉小说事件契约；LLM 不可用或输出不可解析时只生成最小可运行 fallback 草稿 / step。
  4. 本阶段未新增 SpacetimeDB schema、replay 路由或视觉小说私有 save API；平台统一 save archive 的正式 UI / 前端接入留给后续任务。

阻塞关系：

  1. 依赖 VN-01、VN-02。
  2. 真实 LLM 生成依赖 VN-03。
  3. 阻塞 VN-07、VN-08 的真实接口联调。

VN-06：前端 service client 与平台入口分流

负责范围：

  1. 新增视觉小说 creation、works、runtime service client。
  2. 增加 visual-novel selection stage。
  3. 打开平台创作入口分流。
  4. 在平台壳层挂载 workspace、result、runtime、gallery detail。
  5. 处理登录态清理、刷新恢复和错误回退。

主要文件：

  1. src/services/visual-novel-creation/
  2. src/services/visual-novel-works/
  3. src/services/visual-novel-runtime/
  4. src/components/platform-entry/platformEntryTypes.ts
  5. src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
  6. src/config/newWorkEntryConfig.ts

不负责：

  1. 不设计 result 表单细节。
  2. 不设计 runtime UI 细节。
  3. 不写后端 API。

交付物：

  1. 入口从创作中心能进入 visual-novel-agent-workspace。
  2. service client 方法与 PRD 路由一致。
  3. 平台壳层能在 mock 或真实 snapshot 下切换 workspace / result / runtime。
  4. 退出登录清空视觉小说私有状态。

验收命令：

npm run typecheck

阻塞关系：

  1. 依赖 VN-01 的 TS contracts。
  2. 可用 mock 与 VN-04 并行。
  3. 真实联调依赖 VN-05。

VN-06 实施收口记录（2026-05-05）：

  1. 已新增并对齐视觉小说 creation、works、runtime service client，覆盖 /api/creation/visual-novel/sessions、/api/creation/visual-novel/works、/api/runtime/visual-novel/gallery、run、history、regenerate 与 action stream 路由。
  2. 已在平台入口打开 visual-novel，新增 visual-novel-agent-workspace、visual-novel-result、visual-novel-gallery-detail、visual-novel-runtime 阶段和对应前端路由。
  3. 已在 PlatformEntryFlowShellImpl 挂载 VisualNovelAgentWorkspace、VisualNovelResultView、VisualNovelRuntimeShell，并接入创建 session、消息流、结构化 action、草稿编译、保存、发布和测试 run 的最小前端闭环。
  4. 退出登录或受保护数据不可读时会清空视觉小说 session、work、run、错误与 return stage；刷新或直达阶段缺少必要 snapshot 时会回退到 workspace、result 或平台首页。
  5. 本阶段未新增后端 handler、SpacetimeDB schema、平台作品聚合、公开号、分享回放或外部平台功能；gallery detail 仅做壳层最小挂载，完整作品架 / 广场聚合仍归 VN-09。
  6. 已执行 npm run typecheck、视觉小说相关组件单测、平台入口类型单测和 npm run check:encoding。

VN-07：前端创作工作台与结果页

负责范围：

  1. 实现 idea / document / blank 三种创作起点。
  2. 实现 Agent 对话、草稿生成进度和 action 执行。
  3. 实现 VisualNovelResultView 的编辑表单。
  4. 支持世界观、角色、场景、剧情阶段、开场和运行配置编辑。
  5. 支持保存草稿、编译 work profile、进入测试 runtime。

主要文件：

  1. src/components/visual-novel-creation/VisualNovelAgentWorkspace.tsx
  2. src/components/visual-novel-result/VisualNovelResultView.tsx
  3. src/components/visual-novel-result/ 下的编辑面板组件
  4. src/services/visual-novel-creation/
  5. src/services/visual-novel-works/

不负责：

  1. 不实现正式玩家 runtime。
  2. 不改平台作品聚合。
  3. 不新增平台说明页。

交付物：

  1. 一句话创建能生成草稿。
  2. 文档创建能使用平台资产引用生成草稿。
  3. 空白创建能进入可编辑结果页。
  4. 发布前校验 issue 能在结果页清晰呈现。
  5. 结果页可启动测试 run。

验收：

  1. 草稿字段写入 VisualNovelResultDraft。
  2. UI 不展示大段规则说明。
  3. 所有复杂编辑使用独立面板。

阻塞关系：

  1. 依赖 VN-04 骨架、VN-06 分流和 service client。
  2. 真实生成依赖 VN-05。

VN-07 实施收口记录（2026-05-05）：

  1. 已接通平台创作入口到 visual-novel-agent-workspace、visual-novel-result 和测试 visual-novel-runtime 的前端分流。
  2. VisualNovelAgentWorkspace 已支持 idea、document、blank 三种起点；blank 直接创建本地空白 VisualNovelResultDraft 并进入结果页，idea / document 继续调用 /api/creation/visual-novel/sessions。
  3. VisualNovelResultView 已支持作品信息、世界观、开场、角色、场景、剧情阶段和运行配置编辑；角色、场景、剧情阶段、运行配置均使用独立弹层编辑。
  4. 结果页已支持保存当前 session 草稿、显式编译 work profile、发布前结构校验展示和进入测试 run；真实 runtime 接口不可用时仅降级为本地 test run，不扩展正式玩家运行链路。
  5. 本阶段未实现正式玩家 runtime、作品架 / 广场聚合、独立说明页、回放能力或外部平台功能；真实生成、真实保存和正式运行仍以 VN-05 路由完成情况为准。

VN-08：前端运行时、历史、存档与重生成

负责范围：

  1. 实现 VisualNovelRuntimeShell。
  2. 实现 SSE action stream 消费。
  3. 渲染背景、角色立绘、旁白、对白、转场、选项、文本模式。
  4. 实现历史面板、设置面板、存档面板和可选属性面板。
  5. 实现历史重生成和平台 save archive 继续体验。

主要文件：

  1. src/components/visual-novel-runtime/VisualNovelRuntimeShell.tsx
  2. src/components/visual-novel-runtime/useVisualNovelRuntimeController.ts
  3. src/components/visual-novel-runtime/VisualNovelHistoryPanel.tsx
  4. src/components/visual-novel-runtime/VisualNovelSavePanel.tsx
  5. src/components/visual-novel-runtime/VisualNovelSettingsPanel.tsx
  6. src/services/visual-novel-runtime/

不负责：

  1. 不实现创作 result 表单。
  2. 不新增回放 UI。
  3. 不把历史做成可分享播放页。

交付物：

  1. 测试 run 和正式 run 都能渲染 typed step。
  2. 自由输入、选择项和继续推进可用。
  3. 历史查看和重生成可用。
  4. 存档按钮写入平台统一 save archive。
  5. 移动端竖屏可读、可操作。

验收：

  1. SSE step 是正式 UI 状态来源。
  2. raw_text 不写入最终业务状态。
  3. 历史面板不出现回放、分享、录制文案。

阻塞关系：

  1. 依赖 VN-04 骨架、VN-06 service client。
  2. 真实运行依赖 VN-05。

VN-08 实施收口记录（2026-05-05）：

  1. 已补齐 src/services/visual-novel-runtime/ 的运行时 client 与 SSE 消费：运行时 action stream 支持 raw_text、step、snapshot、complete，最终 run 只取 typed snapshot / complete。
  2. 已新增 useVisualNovelRuntimeController，收口 run 读取 / 启动、选择 / 自由输入 / 继续推进、历史重生成、平台 save archive 列表 / 恢复和 checkpoint 保存。
  3. 已升级 VisualNovelRuntimeShell：按 typed step 渲染背景、角色立绘 / 占位立绘、旁白、对白、转场、选项和文本模式；raw_text 仅作为临时流式文本展示，不写入 history 或文本模式最终内容。
  4. 已拆分历史、存档、设置、属性独立面板；历史面板只提供查看与重生成，存档面板只使用平台统一 archive 列表和 checkpoint 保存，不新增私有槽位语义。
  5. 本阶段未实现创作 result 表单、作品架 / 广场聚合、后端 VN-05 路由、回放 UI 或历史分享播放页；真实运行效果仍依赖 VN-05 API 可用性。

VN-09：作品架、广场与发布聚合

负责范围：

  1. 把视觉小说 work summary 接入平台作品架。
  2. 把视觉小说公开作品接入平台 gallery 聚合。
  3. 补 public work code 和详情跳转。
  4. 发布后刷新作品架和公开聚合。

主要文件：

  1. src/components/custom-world-home/creationWorkShelf.ts
  2. src/components/custom-world-home/CustomWorldCreationHub.tsx
  3. src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
  4. src/components/rpg-entry/rpgEntryWorldPresentation.ts
  5. src/services/publicWorkCode.ts
  6. src/services/visual-novel-works/

不负责：

  1. 不新增独立视觉小说市场。
  2. 不实现外部仓库平台详情页。
  3. 不新增回放分享。

交付物：

  1. 视觉小说草稿能出现在平台草稿 / 作品架。
  2. 发布后能进入平台公开聚合。
  3. 从公开作品能启动 visual novel run。

验收：

  1. 发布后刷新作品架能看到作品。
  2. 平台聚合 key 不与 RPG、Puzzle、Match3D、Square Hole 冲突。

阻塞关系：

  1. 依赖 VN-05 works / gallery API。
  2. 依赖 VN-06 平台壳层分流。

实施收口记录：

  1. 已把 VisualNovelWorkSummary 接入平台作品架聚合，视觉小说草稿和已发布作品会与 RPG、Puzzle、Match3D、Square Hole、Big Fish 一起按更新时间展示。
  2. 已新增 VN- public work code，并把视觉小说公开作品接入平台公开广场卡片、搜索、详情与分享路径；聚合 key 使用 visual-novel:{ownerUserId}:{profileId}，避免与现有玩法冲突。
  3. 已在平台壳层接入视觉小说 works/gallery 刷新、删除、发布后刷新和分享弹窗；发布完成后会刷新作品架和公开聚合。
  4. 已支持从平台公开详情启动 mode = 'play' 的 visual novel run；自有视觉小说作品可回到原 work detail / result 草稿继续编辑。
  5. 本阶段未新增独立视觉小说市场、外部平台详情页、分享回放、点赞接口或改造接口；点赞 / 改造按钮仅提示后续开放。

VN-10：资产、文档输入、图片与音乐生成接入

负责范围：

  1. 文档上传和读取走平台资产接口。
  2. 场景背景图、角色立绘、封面、音乐统一使用平台资产引用。
  3. 可选接入图片生成 action。
  4. 确保 SpacetimeDB 不保存大 Data URL 或二进制对象。

主要文件：

  1. src/components/visual-novel-creation/
  2. src/components/visual-novel-result/
  3. src/services/visual-novel-creation/
  4. server-rs/crates/api-server/src/visual_novel.rs
  5. server-rs/crates/platform-oss/src/
  6. server-rs/crates/platform-llm/src/，仅当图片生成 prompt 需要扩展时修改

不负责：

  1. 不新增独立对象存储。
  2. 不把外部 R2 路径迁入。
  3. 不绕过平台资产鉴权。

交付物：

  1. 文档创建可以读取平台资产。
  2. result 页可上传或生成场景 / 角色资产。
  3. work profile 只保存资产引用和 read URL。

验收：

  1. 长文档不会整篇重复写入玩法表。
  2. 大图不会写入长期前端状态或 SpacetimeDB。

阻塞关系：

  1. 可与 VN-07 并行，但最终需要在 result 页汇合。
  2. 后端资产 action 依赖 VN-05。

VN-10 实施收口记录（2026-05-07）：

  1. 已新增视觉小说资产客户端，统一通过 /api/assets/direct-upload-tickets、OSS 直传、/api/assets/objects/confirm 写入平台资产对象，不新增独立对象存储。
  2. 文档创建入口已改为上传平台文档资产后再解析文本，sourceAssetIds 写入平台 assetObjectId，seedText 仅保留截断后的摘要，避免长文档整篇进入玩法表。
  3. 结果页封面、场景背景、角色立绘、音乐均通过平台资产上传 / 历史素材选择写回 /generated-* 引用；角色立绘写入 imageAssets[].assetId / imageSrc / source = platform_asset。
  4. 运行时背景图与角色立绘改用 ResolvedAssetImage，私有 generated 路径通过 /api/assets/read-url 换签后渲染。
  5. 本阶段未接入可选图片生成 action，保留既有 action 契约；未改 SpacetimeDB schema，未保存 Data URL、二进制对象或外部 R2 路径。

VN-10 音频生成补充（2026-05-08）：

  1. 场景编辑器在既有 musicSrc / ambientSoundSrc 槽位上接入音频生成，不新增视觉小说专属音频表或第二套资产系统。
  2. 背景音乐走 VectorEngine Suno POST /suno/submit/music 与 GET /suno/fetch/{task_id}，完成后写入 visual_novel_music 平台资产并绑定到 visual_novel_scene / music。
  3. 场景音效走 VectorEngine Vidu POST /ent/v2/text2audio 与 GET /ent/v2/tasks/{id}/creations，完成后写入 visual_novel_ambient_sound 平台资产并绑定到 visual_novel_scene / ambient_sound。
  4. 前端只提交提示词、标题、标签、时长等生成参数；供应商 base URL 和 API key 只在 api-server 环境变量中读取。
  5. 生成参数使用独立弹层承载，不在场景面板下方展开规则说明。

VN-11：回放删除与外部平台功能负向扫描

负责范围：

  1. 扫描前端、后端、契约、表、文档和测试，确认无回放能力。
  2. 扫描外部平台功能是否被误迁入。
  3. 建立负向测试或脚本清单。

扫描范围：

  1. src/
  2. packages/shared/src/
  3. server-rs/crates/
  4. docs/
  5. .hermes/shared-memory/

禁止项：

  1. replay / Replay 类型、路由、组件、按钮、表、目录和文案。
  2. 分享回放、回放列表、回放编译、回放进度条。
  3. 外部平台账号、订单、会员、促销、banner、后台、公开市场、私有存档。
  4. 新增 server-node 或 Express 落点。

交付物：

  1. 负向扫描报告。
  2. 必要时补单元测试、路由测试或简单脚本。
  3. 发现误入范围时直接提修复任务，不在本任务中大范围重构。

验收命令：

rg -n "replay|Replay|回放|分享回放|录制|复盘" src packages server-rs docs .hermes

验收：

  1. 仅允许历史旧文档和本文“禁止回放”的语境命中。
  2. 新增工程代码不得命中 replay。

VN-11 实施收口记录（2026-05-07）：

  1. 已新增 scripts/check-visual-novel-vn11-negative-scan.mjs 与 npm run check:visual-novel-vn11，把工程代码回放类直出命中、文档 / 共享记忆历史命中、视觉小说实现路径外部平台能力误入分开扫描。
  2. 已生成 docs/audits/VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md，记录扫描范围、处理记录、门禁命令和当前结论。
  3. 已将 src/services/storyEngine/narrativeRegressionReplay.ts / .test.ts 收口为 narrativeRegressionRerun.ts / .test.ts，避免非视觉小说回归工具继续使用 replay 语义。
  4. 已将 src/components/SkillEffectPreview.tsx 的内部 replayTick 与“重播预览”文案收口为重新预览语义，保留原有预览重启动作，不新增回放能力。
  5. 已确认视觉小说实现路径未新增 replay 路由、DTO、表、按钮、文案，也未误入外部平台账号、订单、会员、促销、后台、公开市场或私有存档能力。

阻塞关系：

  1. 可以从 Batch 1 开始持续执行。
  2. 最终发布前必须完成。

VN-12：全链路联调与自动化验收

负责范围：

  1. 串起创作、结果页、测试运行、发布、正式运行、历史、重生成、存档和继续体验。
  2. 补前端 typecheck、后端 cargo test、API smoke 和必要的浏览器截图检查。
  3. 验证移动端和桌面端核心路径。

主要文件：

  1. tests/ 或现有前端测试目录，按项目实际结构补。
  2. server-rs/crates/api-server/tests/
  3. server-rs/crates/module-visual-novel/tests/
  4. src/components/visual-novel-*/，仅修复联调发现的问题。

交付物：

  1. 自动化验收清单。
  2. API smoke。
  3. 前端关键路径检查。
  4. 移动端和桌面端截图记录。

验收命令：

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

阻塞关系：

  1. 依赖 VN-05 到 VN-10 主链路完成。
  2. 发现问题后回流到对应任务 owner。

VN-12 实施收口记录（2026-05-07）：

  1. 已新增 scripts/check-visual-novel-vn12-acceptance.mjs 与 npm run check:visual-novel-vn12，固定检查 PRD、VN-11 报告、关键前端测试、运行时 service client、api-server 路由、shared-contracts 和 module-visual-novel 文件存在与命中。
  2. 已补 src/services/visual-novel-runtime/visualNovelRuntimeClient.test.ts，覆盖公开广场、run 启动、action SSE、历史重生成、平台 save archive 恢复、checkpoint 写入和 archive state 结构。
  3. 已将视觉小说公开广场读取设置为 skipAuth: true / skipRefresh: true，避免未登录公开列表先触发登录 refresh。
  4. 已生成 docs/audits/VN12_FULL_CHAIN_ACCEPTANCE_REPORT_2026-05-07.md，记录自动化验收清单、API smoke、前端关键路径、桌面 / 移动端检查说明、执行命令和未覆盖风险。
  5. 本阶段未新增玩法、未改 SpacetimeDB schema、未新增回放、外部平台功能或私有存档系统；若后续联调发现缺口，回流到对应 VN-05 到 VN-10 owner。

VN-13：实现文档、表目录和交接收口

负责范围：

  1. 根据实际落地更新 PRD、技术方案、表目录和经验文档。
  2. 记录视觉小说模板接入中的长期约定和排障经验。
  3. 确认旧 TXT 文档不会重新成为实现口径。

主要文件：

  1. docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md
  2. docs/technical/SPACETIMEDB_TABLE_CATALOG.md
  3. docs/technical/ 下新增或更新视觉小说实现方案，若工程落地出现新技术细节
  4. .hermes/shared-memory/decision-log.md
  5. .hermes/shared-memory/pitfalls.md

交付物：

  1. 实现后的文档差异已同步。
  2. 表结构、API、契约和验收命令与代码一致。
  3. 长期有效的坑和协作约定进入 Hermes 共享记忆。

验收：

  1. 新开发者只读本文和相关技术文档即可继续维护。
  2. 文档中没有把视觉小说描述成外部平台迁移。
  3. 编码检查通过。

VN-13 实施收口记录（2026-05-07）：

  1. 已新增 视觉小说模板实现收口与交接说明，把视觉小说当前正式入口、表目录、路由、作品 / 运行 / 资产和负向扫描口径收进一页式交接文档。
  2. 已新增 视觉小说模板交接与维护经验，沉淀新开发者最小阅读顺序、常见坑和验证命令。
  3. 已将 docs/technical/README.md、docs/experience/README.md、.hermes/shared-memory/decision-log.md 和 .hermes/shared-memory/pitfalls.md 同步到视觉小说最终收口口径。
  4. 旧 TXT 迁移方案继续只作为历史参考，不再作为视觉小说实现目标。
  5. 本次收口只做文档和共享记忆同步，没有新增回放能力、外部平台功能或新的 SpacetimeDB schema。

16.4 推荐认领方式

最小并行组合：

  1. 后端领域开发认领 VN-01。
  2. SpacetimeDB 开发认领 VN-02。
  3. API 开发认领 VN-05。
  4. 前端平台开发认领 VN-06。
  5. 前端创作开发认领 VN-07。
  6. 前端运行时开发认领 VN-08。
  7. QA / 守门任务认领 VN-11 和 VN-12。

如果只有 2 名开发者：

  1. 开发者 A：VN-01、VN-02、VN-05、VN-10。
  2. 开发者 B：VN-04、VN-06、VN-07、VN-08、VN-09。
  3. 两人共同执行 VN-11、VN-12、VN-13。

如果有 3 名开发者：

  1. 开发者 A：契约、领域、SpacetimeDB、API，即 VN-01、VN-02、VN-05。
  2. 开发者 B：平台入口、创作工作台、结果页，即 VN-04、VN-06、VN-07、VN-09。
  3. 开发者 C：运行时、资产、负向扫描、验收，即 VN-08、VN-10、VN-11、VN-12。

16.5 阻塞关系明细

VN-00
  -> VN-01
      -> VN-02
          -> VN-05
              -> VN-07 / VN-08 / VN-09 / VN-10
                  -> VN-12
                      -> VN-13

VN-03 依赖 VN-01，可与 VN-02 / VN-04 并行。
VN-04 依赖 VN-00，可与 VN-01 / VN-02 / VN-03 并行。
VN-06 依赖 VN-01 契约草案，可与 VN-05 并行 mock。
VN-11 从 Batch 1 开始持续运行，最终阻塞发布。

16.6 拆分验收口径

每个任务完成时必须留下：

  1. 变更文件清单。
  2. 已执行的验证命令。
  3. 未覆盖风险。
  4. 是否触碰 SpacetimeDB schema。
  5. 是否确认无 replay / 外部平台功能误入。

任何任务如果需要修改 VisualNovelResultDraft、VisualNovelRuntimeStep 或 API 路由，必须先更新 VN-01 契约并通知所有依赖任务。

17. 验收标准

17.1 正向验收

  1. visual-novel 入口可见并可点击创建。
  2. 一句话创建能生成可编辑底稿。
  3. 文档创建能读取平台文档资产并生成底稿。
  4. 空白创建能进入结果页。
  5. 结果页能编辑世界观、角色、场景、剧情阶段和运行时配置。
  6. 发布前校验能阻止缺少 opening 场景、角色或初始选项的作品。
  7. 测试 run 能渲染背景、角色、旁白、对白和选项。
  8. 正式 run 能通过 SSE 返回 typed step。
  9. 文本模式可切换。
  10. 历史面板可查看当前 run 历史。
  11. 历史重生成能从指定节点继续，且不会污染旧历史。
  12. 存档和继续体验走平台统一 save archive。
  13. 发布后作品可被平台作品体系读取。
  14. 移动端和桌面端无文本溢出、按钮遮挡和面板错位。

17.2 负向验收

  1. 前端不存在回放按钮、回放列表、分享回放弹窗和回放进度条。
  2. 后端不存在 replay 路由、replay DTO、replay 表和 replay 存储目录。
  3. shared contracts 不出现 Replay / replay 类型。
  4. 视觉小说不新增外部平台账号、订单、会员、促销、banner、后台、公开市场或浏览历史能力。
  5. 视觉小说不新增私有存档系统。
  6. 视觉小说不绕过平台资产系统保存图片、音乐或文档。
  7. 视觉小说不使用 server-node 或 Express 作为新功能落点。

17.3 建议验证命令

按实际改动范围执行：

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 schema、reducer、procedure 或 bindings 时，必须按项目当前 SpacetimeDB 文档执行生成和迁移验证。

18. 后续实现前必须确认的问题

这些问题不阻塞本文冻结边界，但进入编码前需要产品确认默认值：

  1. 视觉小说运行时 AI 推进是否首版收费，以及单次推进默认光点数。
  2. 文档上传首版支持的最大大小和格式。
  3. 角色立绘、场景图是否首版自动生成，还是仅提供手动上传和后续生成按钮。
  4. 属性面板是否首版关闭，还是只对内部白名单开启。
  5. 平台统一存档 UI 是否按槽位展示视觉小说 archive state。

无论上述默认值如何选择，都不能改变三个硬边界：只做视觉小说模板、完全使用平台接口、删除回放。

Reference in New Issue View Git Blame Copy Permalink