藏山

主题

新建小说向导体验升级设计方案 ​

状态：草案，待评审排版 日期：2026-08-01 关联文档：08-章节生产流水线与前后审核体系设计.md

1. 背景与痛点定位 ​

1.1 一个重要事实：分步向导已经存在 ​

当前版本（v0.2.7 起，提交 b319836）的"新建小说"已经是五步向导，不是一次性大表单：

想法(idea) → 基调(tone) → 书名(title) → 篇幅(scale) → 点火(launch)
  • 入口：ProjectsPage.tsx「+ 新建小说」→ /new → OnboardingFlow.tsx（610 行）
  • 机制：进入即静默创建草稿项目，每步选择实时 PATCH 落库，中途退出可「继续创建」，顶部步骤条只可回退已完成步，右侧「本书档案」实时汇总
  • 后端：ProjectCreate 仅 title 必填，其余全部可后补；概念生成、题材推断、AI 起名、架构/蓝图生成均为独立异步接口——"确认一步再出下一步"的后端基础已完全具备

1.2 那痛点到底是什么 ​

用户体感"繁琐复杂、不炫酷"，对照现状可定位为三个真问题：

  1. 步内信息密度高：第 2 步"基调"同屏摆题材 chips + 三维倾向 chips；工作台「概念」面板多张卡片一次性全渲染。向导"分了步"，但每步还是"一屏全摆"。
  2. 无过渡动效：步骤条是自写 DOM（.wiz-steps），步间切换是硬切，无动画、无"AI 正在构思"的过渡体验，等待时只有静态 loading。
  3. AI 参与感弱：AI 产物（概念方案、书名候选、题材推断）以普通列表呈现，没有"AI 在为我想"的仪式感和"选卡确认"的爽感。

结论：方案目标不是"从零造向导"，而是"在现有骨架上做体验升级"——把五步向导从"功能正确的分步表单"升级为"一屏一焦点 + AI 抽卡 + 动效衔接"的沉浸式创作起步流。

2. 调研结论 ​

2.1 直接蓝本：MuMuAINovel（2.8k star，FastAPI+React） ​

它有两条新建路径，合并起来就是完整答案：

  • 灵感模式（一屏一问对话式向导）：步骤序列 idea → title → description → theme → genre → perspective → outline_mode → confirm → generating → complete。用户输入一句话灵感后，每一步 AI 生成 ≥3 个候选供点选，可"我自己输入"、"重新生成"，还能带一句话反馈 refine（"根据您的反馈，我重新生成了一些书名选项"）；确认步汇总全部设定后一键创建。
  • 生成流水线页：世界观 → 职业体系 → 角色 → 大纲四张步骤卡片（等待/进行/完成/失败四态 + 渐变色 + 总进度条 + SSE 实时进度文案"正在生成角色…"），断点续跑（wizard_step 持久化到服务端 + localStorage，刷新后从失败步继续，只重跑失败节点）。

2.2 补充借鉴 ​

  • 马良写作（850 star）："抽卡式多候选"——多模型并行生成多个方案，不满意的独立重生成；设定树快照可版本对比/恢复。适合移植到每一步的候选卡。
  • AI-Novel-Writer（279 star，Electron 桌面端）：阶段闸门状态机——每步有完成状态，未完成步可勾选补跑。与 MuMu 的 wizard_step 思路一致，佐证"状态驱动 + 可续跑"是桌面端标配。
  • AI Loading UX 业界共识：Skeleton 骨架屏优于 Spinner（主观快 ~20%）；流式输出填候选卡（3 秒流式比 1 秒一次性"感觉更快"）；轮换"思考"微文案（"正在构思世界观冲突…"）；有真实进度就推真实进度。
  • 表单心理学：一次一问把长表单拆成小决策，Typeform 式表单完成率显著高于单页长表单（~57% vs ~14% 的常被引用数据）。

2.3 如实说明 ​

MuMu 的"炫酷"主要靠状态卡片 + 流式文案，动画是 AntD 默认水平，视觉上有很大超越空间；中文圈之外没找到第三个成熟的"AI 分步创建向导"开源实现——MuMu 灵感模式 + 我们的动效升级 = 目标形态。

3. 设计目标 ​

  1. 一屏一焦点：每屏只做一个决策，把现在步内堆叠的内容再拆细（题材、倾向、自定义分屏）。
  2. AI 抽卡式候选：每个 AI 产物以候选卡呈现——选一个 / 自己写 / 换一批 / 带反馈 refine，确认即飞入进度条。
  3. 动效衔接：步间换页动画、卡片 FLIP 飞入、Skeleton + 流式填充、"AI 构思中"微文案，消灭硬切和等待真空。
  4. 可续跑、可回退：复用现有 PATCH + setup_state 续建机制；回退修改已确认步时，下游步骤标注"可能受影响"。
  5. 不动后端：本次升级纯前端体验层改造，后端接口零变更（现有 PATCH 分步落库、异步生成接口全部复用）。

4. 总体设计 ​

4.1 新流程形态：三幕式 ​

第一幕【灵感采集】一屏一问（Typeform 式）
  灵感 → 概念方案 → 题材 → 基调倾向 → 书名 → 篇幅
第二幕【确认墙】
  全部设定汇总卡片墙 → "开始创建"
第三幕【点火流水线】
  架构生成 → 蓝图生成 步骤卡 + 流式进度 + 断点续跑 → 进工作台

对比现状五步向导的变化：步数从 5 细化为 6-7 屏（基调步拆分），每屏决策唯一；新增确认墙；点火步从"一个按钮"升级为流水线屏。

4.2 第一幕：逐屏设计 ​

每屏统一结构：

┌─────────────────────────────┐
│ 顶部：进度条（已确认项缩略卡） │
│                             │
│   大字问题："这本书的核心是什么？" │
│   AI 候选卡 ×3~4（流式填充）   │
│   [换一批] [带反馈重来] [自己写] │
│                             │
│   确认 ↓ 进入下一屏（动画）     │
└─────────────────────────────┘
屏内容AI 介入（全部复用现有接口）
1 灵感一句话输入框，Enter 提交；保留现有三入口卡的"选流派/对话捏概念"作为次级入口收进"没有灵感？"链接现有：inspire/async
2 概念方案AI 出 3~4 个概念卡（logline/hook/twist/主角/冲突/设定六字段），抽卡式呈现现有：inspire/async、inspire/refine-async（换一批/带反馈 refine）
3 题材独立一屏：AI 预填推断的题材 chips 点选 + 自定义现有：tendency/genre-infer
4 基调倾向独立一屏：pace/structure/tone 三维 chips（从现第 2 步拆出）规则预填，无新接口
5 书名AI 候选书名卡 + 手输 + 换一批现有：projects/title-suggestion
6 篇幅三预设卡（短/中/长篇）+ 两个数字输入（章数/每章字数），改为"先选卡、数字折叠进高级选项"无

候选卡交互（每屏通用组件）：

  • 四操作：选用（卡片 FLIP 飞入顶部进度条缩略位）/ 换一批 / 带一句话反馈重新生成（"太俗了，要冷峻一点"）/ 自己写
  • 流式填充：候选卡先出 skeleton 轮廓（shimmer），内容 token 级流入；预填充期显示轮换微文案（"正在揣摩题材气质…"）
  • 不选 AI 也能过：每屏永远有"跳过/自己写"，向导不绑架用户

4.3 第二幕：确认墙 ​

  • 全部已确认设定以卡片墙汇总（概念/题材/基调/书名/篇幅），每张卡可点"改"跳回对应屏
  • 回改某屏后，其下游已确认项标黄"可能受影响"，用户决定保留或重选
  • 「开始创建」→ 第三幕

4.4 第三幕：点火流水线屏 ​

复用 MuMu 流水线页设计，映射到我们的后端：

  • 两张步骤卡：生成架构（architecture-async）→ 生成蓝图（blueprint-async，后端已硬依赖架构，顺序天然成立）
  • 每卡四态（等待/生成中/完成/失败）+ 后端 job 进度文案（现有 useJob 轮询已支持，可升级 SSE）
  • 失败只重跑该步；页面刷新/中途退出后从 setup_state 续建（现有机制）进入对应幕
  • 全部完成 → "进入工作台"按钮点亮，配庆祝微动效
  • 保留现有"直接进工作台"逃生口（不生成架构，手动慢慢搭）

4.5 动效方案（炫酷的主要来源） ​

技术选型：Motion（原 framer-motion） 一个库全覆盖，与现有 React 18 + Vite + 纯 CSS 变量主题兼容，不引入组件库。

场景效果实现
步间切换当前屏上滑淡出 + 下一屏下滑淡入，问题文字逐行 stagger 出现AnimatePresence + variants
确认候选卡卡片缩小飞入顶部进度条缩略位（FLIP）Motion layoutId 共享元素过渡
AI 生成中候选位先 skeleton（shimmer）→ 流式文字填充 → 落定弹起CSS shimmer + 流式渲染
进度条完成步打勾动画 + 进度条流光推进Motion 路径动画
流水线屏步骤卡状态渐变背景 + 完成打勾弹跳 + 总进度条复用 MuMu 视觉模式
降级prefers-reduced-motion 时全部降为淡入淡出Motion 自带支持

可选加分项：View Transitions API（Tauri Webview2 是 Chromium，可用）做整屏过渡；不引入 AntD Steps 等组件库，步骤条继续自写但加动效。

4.6 状态与续跑 ​

  • 每屏选择实时 PATCH 落库（现有机制保留）——服务端是真相源
  • 新增 localStorage 缓存当前屏位 + 候选卡内容：刷新后恢复到"正在选第几屏"，而非粗暴回到第一步
  • setup_state 细化为 idea/concept/genre/tone/title/scale/confirm/generating/done（现 setup_state 是字符串字段，直接扩展取值即可，无需迁移）；退出后列表页「继续创建」直达对应屏
  • 生成中中断：流水线屏重新进入时按 job 状态恢复进度展示（现有 /api/jobs/:id 轮询）

4.7 同步治理的高密度残留面 ​

向导升级后，工作台侧的两处"一屏全摆"顺手治理（同一套"一屏一焦点 + 抽卡候选"组件复用）：

  • InspirePanel.tsx：概念六字段卡 + TendencySelector + 三张 AI 卡全渲染 → 改为向导同款分屏或手风琴
  • 工作台 8 步左侧导航（ProjectPage.tsx:224-238）：保留全列导航（工作台需要全局跳转），但当前步高亮强化

5. 与现有代码的对接点 ​

改造项落点
屏拆分与换页动画frontend/src/pages/OnboardingFlow.tsx 重构：step 数组细化（idea/concept/genre/tone/title/scale/confirm/launch），包 AnimatePresence
通用候选卡组件新增 ui/CandidateCards.tsx：skeleton/流式/四操作/FLIP 飞入，六个屏复用
顶部进度条缩略卡现 .wiz-steps 升级：已确认项缩略卡 + layoutId 接收飞入
确认墙新增步 confirm，数据源 = 已 PATCH 的项目字段，无需新接口
流水线屏现 launch 步（OnboardingFlow.tsx:516-530）扩展为双步骤卡，复用 useJob + architecture-async/blueprint-async
微文案轮换新增 ui/ThinkingText.tsx，纯前端
依赖package.json 新增 motion（约 30KB gzip）；不引入组件库
续跑ProjectsPage.tsx:96-103「继续创建」已存在，setup_state 取值细化即可
InspirePanel 治理复用 CandidateCards 重构 InspirePanel.tsx:183-369

后端零变更：所有 AI 能力（inspire/refine/genre-infer/title-suggestion/architecture/blueprint）均已有异步接口，向导只做编排。

6. 分阶段实施路线 ​

P0 — 动效骨架（炫酷感的 80%）

  1. 引入 Motion，AnimatePresence 步间换页 + 进度条动效
  2. 候选卡组件（skeleton + 四操作），接入现有 5 步
  3. "AI 构思中"微文案

P1 — 一屏一焦点

  1. 基调步拆分为题材屏 + 倾向屏；篇幅屏折叠高级选项
  2. 确认卡 FLIP 飞入进度条
  3. setup_state 细化 + localStorage 屏位恢复

P2 — 确认墙与流水线

  1. 确认墙步 + 下游"可能受影响"标注
  2. 点火流水线双步骤卡 + 失败重跑 + 完成庆祝动效
  3. （可选）候选卡流式化：若后端支持 SSE 则接，否则保持 job 轮询 + skeleton

P3 — 工作台残留面治理

  1. InspirePanel 复用组件重构

7. 风险与取舍 ​

  • 屏数变多，步骤疲劳：6-7 屏每屏点一下，可能比 5 步更显长。对策：进度条永远可见 + 每屏平均决策时间 < 15 秒 + "跳过/自己写"永在。
  • 流式依赖后端：候选卡流式填充体验最好，但现有生成接口是 job 轮询。P0/P1 用 skeleton + 轮询即可达标，SSE 流式列为可选升级，不阻塞。
  • 动画性能：桌面端 Webview2 无压力；提供 prefers-reduced-motion 降级，动画全部可关（设置项）。
  • 回退修改的一致性：回改灵感后书名/概念是否作废？方案采用"标黄提示，用户决定"，不做强制清空（强制清空是向导类产品的最大差评来源）。

附：调研索引 ​

参考地址借鉴点
MuMuAINovel 灵感模式github.com/xiamuceer-j/MuMuAINovel (frontend/src/pages/Inspiration.tsx)一屏一问步骤序列、AI 候选 + 带反馈 refine、确认墙
MuMuAINovel 生成流水线同上 (AIProjectGenerator.tsx)步骤卡四态、进度文案、wizard_step 断点续跑
马良写作github.com/Deng-m1/MaliangAINovalWriter抽卡式多候选、局部重生成、快照
AI-Novel-Writergithub.com/EthanYoQ/AI-Novel-Writer阶段闸门状态机、未完成步补跑
Motion 多步向导教程buildui.com/courses/framer-motion-recipes/multistep-wizardAnimatePresence 换页配方
AI Loading UXuxpatterns.dev/patterns/ai-intelligence/ai-loading-statesskeleton > spinner、流式、微文案

基于 Apache License 2.0 开源

Copyright © 2026 ynnyh