《AI 小说工坊》开发文档

交付对象：WorkBuddy（开发实施方）交付用途：作为该应用完整开发的唯一需求与实现依据产品名占位说明：以下统称「AI 小说工坊」，最终名称可在设置中自定义，文档内名称均可全局替换。

1. 项目概述

1.1 产品定位

一款本地化安装的 Windows 桌面应用（EXE 安装包，一键安装即用），面向小说作者与 AI 写作用户。用户只需选择生成模型并填写少量创作参数，应用即可自动完成从故事构思、大纲、角色、物品、地图、伏笔到逐章正文的全流程创作，产出一整套可查看、可编辑、可阅读、可导出 TXT 的「完整小说资产包」。

1.2 目标用户

网络小说作者（辅助创作、批量生成草稿）
AI 写作爱好者、内容工作室
需要长篇连载产出的内容团队

1.3 核心价值

#	价值点	说明
1	全流程自动化	输入 8 项基础参数 → 输出完整小说工程（介绍/大纲/章节大纲/正文/角色/物品/地图/伏笔/封面/阅读器）
2	全模型兼容	支持主流大模型 + 任意 OpenAI 兼容自定义接入（自配密钥）
3	长篇一致性	10–2000 章规模下，通过大纲约束 + 上下文包 + 伏笔台账 + 滚动一致性审查，保证故事贯通、不重复、不跑题
4	本地化可控	数据全部本地存储，联网仅用于调用用户所选模型的 API；所有产出均可人工编辑
5	断点续跑	章节生成过程随时暂停/中断/重启后继续，进度不丢失、不重复
6	完整体验	内置小说风格阅读器、角色关系图谱、黑白双主题带动画 UI

1.4 名词约定

小说资产：一部小说产生的全部结构化内容（介绍、大纲、章节大纲、章节正文、角色、物品、地图、伏笔、封面信息）。
设定包：世界观、主线、角色状态、物品规则、地图等"冻结设定"的合集，正文生成时注入以保证一致性。
上下文包：生成单章正文时注入模型的全部上下文（设定包 + 章节大纲 + 前文摘要 + 伏笔台账 + 前章结尾等）。

2. 总体架构

2.1 架构方案（推荐）

采用 Wails v2（Go 写桌面后端 + Vue3 写前端，可直接打包 Windows EXE 安装包），这是与"VUE + GO 技术栈 + 本地 EXE 安装包"要求最契合的官方成熟方案，无需额外运行时，体积小、资源占用低。

┌──────────────────────────────────────────────────────────────┐
│                    Windows 桌面（EXE 安装包）                   │
│  ┌────────────────────────┐  ┌────────────────────────────┐  │
│  │  Vue3 前端（本地 UI）    │  │  Go 本地后端                 │  │
│  │  · 小说风格主题/黑白双色  │  │  · Binding API / 事件推送    │  │
│  │  · 阅读器/角色图谱/表单  │◄─┤  · 生成流水线 + 任务队列      │  │
│  │  · 动画/页面路由         │  │  · 一致性审查 Agent          │  │
│  └────────────────────────┘  │  · LLM 适配层（多模型）        │  │
│                              │  · SQLite 持久化 / 文件存储    │  │
│                              └───────────────┬────────────┘  │
└──────────────────────────────────────────────┼──────────────┘
                                               ▼
                          ┌──────────────────────────────────┐
                          │  外部 LLM API（用户选择/自配密钥） │
                          │  OpenAI 兼容 / 厂商 SDK / 本地     │
                          │  Ollama（无需密钥）               │
                          └──────────────────────────────────┘

架构图补充说明：可视化附图见随文档交付的《AI小说工坊-架构与生成流水线.html》。

2.2 关键设计决策

决策点	选择	理由
桌面框架	Wails v2	Go + Vue 原生组合、EXE 打包、低内存
前端构建	Vue 3 + TypeScript + Vite + Pinia + Vue Router	生态成熟、开发效率高
数据存储	SQLite（GORM，纯 Go 驱动避免 CGO）	本地单文件、2000 章规模足够
密钥存储	Windows DPAPI 加密后入库	本地安全、防明文
LLM 协议	统一 OpenAI 兼容协议为主 + 厂商特适配 + Ollama 本地	覆盖绝大多数模型
前端 UI 组件	Naive UI 或 Element Plus（深/浅色适配）	双主题友好
图表	ECharts（角色关系图谱、伏笔时间线）	关系图能力强
阅读器	自研轻量阅读器（本地章节渲染）	无网络依赖、可控性强

2.3 备选方案（如开发方对 Wails 不熟）

方案 B：Go 后端内嵌 Vue 静态资源 + 本地 HTTP 服务 + 系统托盘 + 打开系统浏览器窗口。缺点：浏览器窗口 UI 风格受限、顶部标题栏难以自绘。
方案 C：Electron + Go sidecar 子进程。缺点：体积大、违背"VUE+GO 轻量"初衷。
默认采用方案 A（Wails v2），开发方如需更换必须说明理由并经确认。

3. 技术选型明细

3.1 前端

项	选型	说明
框架	Vue 3（Composition API）+ TypeScript	—
构建	Vite	—
状态	Pinia	全局设置、当前小说、生成进度
路由	Vue Router	见 7.2 页面清单
UI 组件	Naive UI（推荐，主题化强）或 Element Plus	双主题切换需全部走 CSS 变量
图表	ECharts 5	关系图谱、伏笔时间线
动画	CSS 动画 + GSAP	页面转场、打字机、主题切换墨迹扩散
阅读器	自研分页阅读器	目录、字号、背景、翻页动画、伏笔高亮
字体	标题衬线（宋体/思源宋体）+ 正文黑体	小说风格

3.2 后端（Go）

项	选型	说明
桌面框架	Wails v2（含 window 配置、事件系统）	前端通过 Binding 直接调用 Go 方法
Web 框架	标准库 / Gin	若启用 HTTP 模式备用
ORM	GORM + SQLite 驱动（modernc.org/sqlite 纯 Go，避免 CGO）	本地单文件
LLM 客户端	① OpenAI 兼容：sashabaranov/go-openai（可自定义 BaseURL）② 特殊厂商：Claude（anthropic sdk）、Gemini（google-generativeai）等按需 ③ Ollama：本地 HTTP 调用	见第 5 章
加密	golang.org/x/sys/windows（DPAPI）+ AES-GCM 兜底	密钥加密
任务队列	自研状态机 + SQLite 事务	轻量、可控、断点续跑友好
打包	Wails 内置 NSIS 打包	一键生成安装包

3.3 开发环境要求

Go ≥ 1.22，Node.js ≥ 18，Wails CLI v2
构建命令：wails build（Windows 平台产出 EXE 与 NSIS 安装包）

4. 工程目录结构（建议）

novel-studio/
├── frontend/                    # Vue3 前端
│   ├── src/
│   │   ├── main.ts / App.vue
│   │   ├── router/index.ts
│   │   ├── stores/              # Pinia（app / novel / progress / settings）
│   │   ├── views/               # 页面（见 7.2）
│   │   ├── components/          # 阅读器 / 关系图谱 / 卡片组件等
│   │   ├── api/                 # Wails Binding 封装（统一 promise 化）
│   │   ├── styles/
│   │   │   ├── theme-dark.css   # 墨黑主题变量
│   │   │   ├── theme-light.css  # 素白主题变量
│   │   │   ├── base.css         # 动画 / 字体 / 纸张纹理
│   │   └── assets/
│   └── package.json
├── backend/                     # Go 后端
│   ├── cmd/novel-studio/main.go
│   ├── internal/
│   │   ├── app/                 # Wails app 装配、事件
│   │   ├── models/              # GORM 模型（见第 5 章）
│   │   ├── service/             # 业务：创作 / 章节 / 资产 CRUD
│   │   ├── pipeline/            # 生成流水线（见第 7 章）
│   │   ├── queue/               # 任务状态机、断点续跑
│   │   ├── llm/                 # Provider 接口 + 各厂商实现
│   │   ├── consistency/         # 一致性审查 Agent
│   │   ├── storage/             # SQLite 初始化、迁移、文件目录
│   │   └── export/              # TXT 导出
│   └── go.mod
├── build/                       # Wails 打包资源（图标、安装引导图）
└── docs/

5. 数据模型设计（SQLite / GORM）

5.1 ER 关系总览

novels(1) ──┬── (N) chapters             novels(1) ── (1) outlines
            ├── (N) chapter_outlines     novels(1) ── (N) characters
            ├── (N) items                characters(M) ── (N) character_relations
            ├── (N) maps                 novels(1) ── (N) foreshadows
            └── (1) cover_info           novels(N) ── (1) model_configs
generation_tasks(N) ── (1) novels        global_settings(KV)

删除小说时级联删除所有子表（ON DELETE CASCADE）。

5.2 表结构（核心字段）

novels 小说主表

字段	类型	说明
id	INTEGER PK
title	TEXT	书名（AI 生成 + 可改）
category	TEXT	分类（见 7.1 预设）
tags	TEXT(JSON)	标签数组
description	TEXT	用户输入的创作描述（核心输入）
style	TEXT	文风预设
perspective	TEXT	叙事视角预设
target_chapters	INTEGER	目标章节数（10–2000）
chapter_word_count	INTEGER	每章目标字数
intro	TEXT	小说介绍（AI 生成）
cover_path	TEXT	封面图片本地路径（可空）
cover_prompt	TEXT	封面 AI 生成描述词
status	TEXT	生成状态：planning / writing / paused / completed / failed
progress	INTEGER	已完成章节数
model_config_id	INTEGER FK	使用的模型配置
settings_json	TEXT(JSON)	生成参数快照（便于追溯）
created_at / updated_at	DATETIME

outlines 故事大纲

字段	类型	说明
id	INTEGER PK
novel_id	INTEGER FK
title	TEXT	大纲标题
structure_type	TEXT	卷结构类型（三幕式 / 卷宗式 / 单元剧等）
content	TEXT(JSON)	卷/部结构、主线、支线、主题、世界观设定、结局方向、关键转折点
notes	TEXT	备注

chapter_outlines 章节大纲

字段	类型	说明
id	INTEGER PK
novel_id	INTEGER FK
chapter_index	INTEGER	第 N 章（与 novels 唯一约束）
title	TEXT	章节标题
purpose	TEXT	本章目标
events	TEXT(JSON)	事件列表
characters	TEXT(JSON)	出场角色及本章状态
foreshadow_set	TEXT(JSON)	本章设置的伏笔（标题/重要性/回收提示）
foreshadow_resolve	TEXT(JSON)	本章回收的伏笔
ending_hook	TEXT	本章结尾钩子（保证衔接）
continuity_from	TEXT	承接上一章结尾的衔接要点
status	TEXT	待生成 / 已生成 / 已修订

chapters 章节正文

字段	类型	说明
id	INTEGER PK
novel_id	INTEGER FK
index	INTEGER	章节序号（唯一）
title	TEXT	章节标题
word_count	INTEGER	实际字数
content	TEXT	正文
summary	TEXT	AI 生成的章节摘要（供后续上下文使用）
status	TEXT	pending / generating / done / edited / regenerating / failed
token_cost	INTEGER	本节约消耗 token（统计用）
revision	INTEGER	重写版本号
created_at / updated_at	DATETIME

characters 角色

字段	类型	说明
id	INTEGER PK
novel_id	INTEGER FK
name	TEXT	姓名
role_type	TEXT	主角 / 重要配角 / 反派 / 配角 / 关键NPC
identity / gender / age	TEXT	身份 / 性别 / 年龄
personality	TEXT	性格
appearance	TEXT	外貌
background	TEXT	背景
motivation	TEXT	动机
arc	TEXT	成长弧光
faction	TEXT	阵营
status	TEXT	存活 / 失踪 / 死亡 / 黑化等
avatar_path	TEXT	头像路径（可空）
card_json	TEXT(JSON)	角色卡片结构化信息（用于卡片展示）
detail	TEXT	角色详情长文
notes	TEXT	备注

character_relations 角色关系

字段	类型	说明
id	INTEGER PK
novel_id	INTEGER FK
from_char_id	INTEGER FK	源角色
to_char_id	INTEGER FK	目标角色
relation_type	TEXT	敌对 / 师徒 / 恋人 / 家人 / 盟友 / 宿敌 / 上下级等
strength	INTEGER	关系强度 1–10
description	TEXT	关系描述
evolution	TEXT	关系演变（随剧情变化）

items 物品卡

字段	类型	说明
id	INTEGER PK
novel_id	INTEGER FK
name	TEXT	名称
type	TEXT	武器 / 法宝 / 道具 / 科技 / 信物 / 功法等
rarity	TEXT	普通 / 稀有 / 史诗 / 传说 / 唯一
owner_char_id	INTEGER FK	当前持有角色（可空）
attributes	TEXT(JSON)	属性/规则
lore	TEXT	来历与设定
card_json	TEXT(JSON)	物品卡结构化信息
detail	TEXT	物品详情长文
notes	TEXT	备注

maps 地图卡

字段	类型	说明
id	INTEGER PK
novel_id	INTEGER FK
name	TEXT	地名
region_type	TEXT	主城 / 秘境 / 势力 / 野外 / 国家等
parent_map_id	INTEGER FK	上级地图（支持层级树）
description	TEXT	概述
key_locations	TEXT(JSON)	关键地点列表
card_json	TEXT(JSON)	地图卡结构化信息
detail	TEXT	地图详情长文
notes	TEXT	备注

foreshadows 伏笔管理

字段	类型	说明
id	INTEGER PK
novel_id	INTEGER FK
title	TEXT	伏笔名称
description	TEXT	伏笔内容
setup_chapter	INTEGER	埋设章节
resolve_chapter	INTEGER	回收章节（可空）
importance	TEXT	主线 / 支线 / 彩蛋
status	TEXT	planted（已埋设）/ pending_resolve（待回收）/ resolved（已回收）/ abandoned（放弃）
notes	TEXT	备注

cover_info 封面信息

字段	类型	说明
id	INTEGER PK
novel_id	INTEGER FK
prompt	TEXT	封面 AI 生成描述词（完整提示词）
style_tags	TEXT(JSON)	风格标签（国漫厚涂/水墨/写实等）
composition	TEXT	构图说明
aspect_ratio	TEXT	建议比例（如 3:4）
commercial_points	TEXT(JSON)	商业卖点词（视觉记忆点、市场风格）
negative_prompt	TEXT	负面提示词
image_path	TEXT	已应用的封面本地路径

model_configs 模型配置

字段	类型	说明
id	INTEGER PK
name	TEXT	配置名（如"DeepSeek"）
provider	TEXT	openai_compat / doubao / qianfan / claude / gemini / ollama / custom
base_url	TEXT	接口地址（custom 必填）
api_key_encrypted	TEXT	DPAPI 加密后的密钥
model	TEXT	模型名
endpoint_id	TEXT	火山方舟等需要的 endpoint（可空）
max_tokens	INTEGER	默认输出上限
temperature	REAL	默认温度
concurrency	INTEGER	该模型的并发数
timeout_sec	INTEGER	超时
extra	TEXT(JSON)	厂商特有参数（如 anthropic_version）
is_preset	BOOL	是否官方预设
is_default	BOOL	是否默认选中

generation_tasks 生成任务（断点续跑核心）

字段	类型	说明
id	INTEGER PK
novel_id	INTEGER FK
task_type	TEXT	plan / intro / outline / chapter_outlines / characters / items / maps / chapters / cover / finalize
step_order	TEXT(JSON)	完整步骤顺序（用于恢复）
current_step	INTEGER	当前执行到第几步
current_index	INTEGER	当前进度（如第 N 章）
total_steps	INTEGER	总步骤数
status	TEXT	queued / running / paused / failed / completed
error	TEXT	最近错误信息
retry_count	INTEGER	连续重试计数
checkpoint_json	TEXT(JSON)	阶段 checkpoint 数据
created_at / updated_at / finished_at	DATETIME

global_settings 全局设置

字段	类型	说明
key	TEXT PK	如 theme / default_export_path / default_model_id / ui_language / audit_interval
value	TEXT(JSON)	值

5.3 索引与约束

chapters(novel_id, index) 唯一；chapter_outlines(novel_id, chapter_index) 唯一
foreshadows(setup_chapter)、foreshadows(resolve_chapter) 索引
全部子表 novel_id 建索引；删除小说级联删除

6. LLM 适配层（核心模块）

6.1 统一 Provider 接口

type ChatMessage struct {
    Role    string `json:"role"`    // system / user / assistant
    Content string `json:"content"`
}

type ChatRequest struct {
    Model       string
    Messages    []ChatMessage
    Temperature float64
    MaxTokens   int
    JSONMode    bool            // 强制 JSON 输出
    Stop        []string
    Extra       map[string]any  // 厂商特有参数
}

type ChatResponse struct {
    Content string
    Usage   struct{ PromptTokens, CompletionTokens int }
}

type Provider interface {
    Name() string
    Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error)
}

6.2 预设提供商清单（至少内置 6+ 家 + 自定义）

预设	provider	默认模型示例	说明
DeepSeek	openai_compat	deepseek-chat	base_url: https://api.deepseek.com/v1
豆包 / 火山方舟	doubao	doubao-seed--	需 Endpoint ID
通义千问	openai_compat	qwen-plus	DashScope 兼容模式
Kimi（月之暗面）	openai_compat	moonshot-v1-8k
智谱 GLM	openai_compat	glm-4-plus
文心一言	qianfan	ernie-4.0	单独适配鉴权
OpenAI	openai_compat	gpt-4o-mini
Claude	claude	claude-sonnet-4	单独适配（非 OpenAI 协议）
Gemini	gemini	gemini-2.5-flash	单独适配
Ollama（本地）	ollama	qwen2.5:14b	本地模型，无需密钥
OpenRouter	openai_compat	任意	聚合接入
自定义	custom	用户填写	base_url + api_key + model，走 OpenAI 兼容协议；无法确认兼容性时给出提示

6.3 密钥安全

Windows 下使用 DPAPI（CryptProtectData）加密后写入 model_configs.api_key_encrypted
开发期其他平台用 AES-GCM 兜底，密钥由用户输入
前端只显示掩码（sk-****abcd），任何接口不回传明文；日志禁止记录密钥

6.4 结构化输出规范（所有"生成资产"统一走 JSON）

优先使用各模型 response_format: {type: "json_object"} / JSON Mode
不支持 JSON Mode 的模型：prompt 强制 + 解析 + 自动修复（去包裹、截断补全、转义修复），最多重试 3 次，指数退避
解析失败超过上限 → 该步骤标记 failed 并保留错误信息，可人工重试（断点续跑支持）

6.5 上下文包与 Token 预算（章节衔接的命脉）

单章正文生成的 Prompt 组装顺序（固定模板）：

system 提示词：写作规范、文风、视角、禁止重复/跑题/设定冲突的禁令
设定包：世界观设定、主线梗概、当前卷摘要（按 Token 预算截断）
章节大纲：当前章大纲 + 前后各 1 章大纲（保证衔接）
角色状态快照：存活角色清单 + 关键状态 + 所在地
伏笔台账：未回收伏笔列表 + 本章应回收伏笔
前文摘要：最近 5–10 章摘要 + 全文滚动摘要（Long Summary 压缩）
前章结尾：上一章正文最后 200–300 字（无缝衔接）
本章要求：事件清单、字数目标、结尾必须呼应 ending_hook

Token 预算策略：按模型上下文窗口分档（8k / 32k / 64k / 128k+），超出部分逐级丢弃（先丢次要设定，再压缩摘要）。每章正文若目标字数超出单次调用能力，则拆分为 1–3 次"续写"调用，续写上下文注入已写部分结尾 300 字。

6.6 一致性保障机制（10–2000 章不跑题、不重复）

机制	实现
大纲约束	正文必须严格按章节大纲事件生成；章节大纲由故事大纲派生；故事大纲由描述+参数派生（层层约束）
设定冻结	世界观/角色/物品/地图在 P4–P5 阶段生成后"冻结"，正文生成强制注入
伏笔台账	章节大纲阶段登记伏笔；正文只允许设置已登记的伏笔，回收必须登记对应关系
章节摘要	每章完成后调用模型生成结构化摘要（新事件/角色状态变化/新增伏笔）写入 `chapters.summary`
滚动一致性审查	每 N 章（默认 20，可配置）运行一致性审查 Agent：对照设定包与近 N 章摘要，输出冲突清单 → 自动修正设定（需用户确认）或生成"修订建议"人工处理
防重复防跑题	生成前注入"本卷主线 + 最近事件"，明确禁令；可选对已写章节摘要做相似度检测（关键词/向量），相似度过高自动要求重写
结尾钩子	每章大纲预设 ending_hook，正文结尾强制呼应，下章开篇承接

6.7 限流与成本

每模型并发数可配置（默认 1–2）
失败重试 + 指数退避（30s/60s/120s）；连续失败 5 次 → 任务自动暂停并提示用户
每章记录 token 消耗；进度页展示估算成本

7. 生成流水线（业务核心）

7.1 用户输入（生成表单，全部带预设）

参数	预设	说明
生成模型	6.2 预设列表 + 自定义	必选
分类	玄幻 / 仙侠 / 都市 / 科幻 / 悬疑 / 言情 / 历史 / 游戏 / 军事 / 轻小说 / 其他	单选
标签	穿越、系统、无敌流、重生、克苏鲁、电竞、星际、校园、商战、末世…	多选，可自增
描述	自由文本	核心输入，一句话/一段话故事构思
章节数量	10–2000（输入整数，越界提示）	必填
每章字数	1000 / 2000 / 3000 / 4000 / 5000 / 8000（可自定义）	必填
文风	网文爽文 / 文青细腻 / 悬疑冷峻 / 幽默吐槽 / 古典文言 / 科幻硬核 / 温暖治愈 / 史诗厚重 / 自定义	单选
叙事视角	第一人称 / 第三人称限知 / 第三人称全知 / 多视角	单选

高级选项（默认合理值，可展开）：世界观基调、是否自动生成角色/物品/地图、一致性审查间隔（章）、并发数、摘要用小模型（省钱）。

7.2 流水线步骤（状态机，全步骤可断点续跑）

P1 任务初始化
  └ 校验参数、创建 novel 记录、生成任务落库
P2 生成小说介绍（简介 + 卖点）
P3 生成故事大纲（含卷结构；章节数 > 100 自动按卷分块，每卷约 30–60 章）
P4 生成章节大纲（批量并行，每批 10–20 章；依赖 P3）
P5 生成角色体系（角色清单 → 角色卡片 → 角色详情 → 关系图谱）
P6 生成物品卡 / 地图卡（依赖世界观设定）
P7 逐章正文生成（核心循环，见 7.3）
P8 封面工坊（生成商业封面描述词；可选调用图像模型生成本地封面）
P9 收尾（一致性总检、状态置 completed、输出生成报告）

每一步完成即事务提交；已完成步骤在续跑时自动跳过
任一步失败：记录 error + 步骤上下文，任务置 failed/paused，可手动从该步骤继续

7.3 逐章正文生成循环（P7）

for i = 当前进度 → target_chapters:
  1. 读取 chapter_outlines[i]，组装上下文包（6.5 模板）
  2. 调用 LLM 生成正文（超长则续写拼接）
  3. 调用 LLM 生成章节摘要（写入 chapters.summary）
  4. 同步伏笔台账（比对正文实际出现/回收）
  5. 写入 chapters（事务提交），进度 +1，checkpoint 更新
  6. 失败 → 按 6.7 重试策略处理
  7. 每 N 章触发一致性审查（6.6）

7.4 断点续跑设计（重点需求）

任务表：generation_tasks 记录步骤顺序、当前步骤、当前索引、checkpoint；每章/每步骤事务提交
应用重启：启动时扫描未完成任务 → 弹窗"检测到未完成创作《XX》，是否继续？"
续跑：跳过硬完成步骤，从 current_step/current_index 继续；幂等保证（(novel_id, index) 唯一，重跑不产生脏数据）
手动控制：生成页提供暂停 / 继续 / 取消按钮；取消后进度保留，可随时重新启动
单章重写：以"上一章摘要 + 本章大纲 + 原章节前 N 字"为上下文重写，覆盖时 revision+1（保留旧内容到历史记录，可选）

7.5 人工编辑（所有信息可改）

大纲、章节大纲、章节正文、角色卡片/详情、物品、地图、伏笔、封面词、小说介绍、书名标签——全部支持编辑保存
编辑章节大纲后：该章标记"已修订"，可选"重新生成本章正文"
编辑角色/物品/地图后：设定包更新，后续章节生成自动采用新设定

8. 前端设计与页面（小说风格 UI）

8.1 主题系统（黑白双风格 + 顶部标题栏）

双主题：墨黑（暗色，星空/水墨意境）/ 素白（亮色，羊皮纸/宣纸质感）
全部视觉走 CSS 变量（--bg-primary / --bg-paper / --ink / --accent / --border 等），一处切换全应用生效
窗口顶部标题栏随主题切换：采用 Wails 无边框窗口 + Vue 自绘标题栏（最小化/最大化/关闭按钮同样换肤）
主题切换动画：墨迹扩散 / 纸张翻页过渡（可配置开关，默认开启）
小说风格元素：衬线标题、纸张纹理、毛边阴影、印章式 Logo、书脊元素
动效清单：页面转场（翻页/淡入）、生成时"打字机 + 研墨"光标、章节解锁动画、水墨流动进度条、卡片 hover 微交互（浮起 + 墨晕）、阅读器翻页动画

8.2 页面清单（路由）

路由	页面	功能
`/generate`	新建创作	参数表单（7.1）+ 高级选项折叠
`/progress/:novelId`	生成进度	实时进度、流水线步骤状态、日志、暂停/继续/取消、断点提示
`/library`	我的书架	小说列表（封面/进度/状态徽标）、搜索、排序、历史
`/novel/:id`	小说详情	介绍、封面、元数据、全部资产入口
`/novel/:id/outline`	故事大纲	大纲查看/编辑（卷结构树）
`/novel/:id/chapters`	章节列表	分页列表、状态、字数、单章重写/编辑
`/novel/:id/reader`	阅读器	分页阅读、目录抽屉、字号/行距/背景/字体、翻页动画、伏笔高亮
`/novel/:id/characters`	角色图谱	ECharts 关系网（可拖拽、筛选、点击看卡片）
`/novel/:id/characters/:cid`	角色详情	角色卡片 + 详情长文编辑
`/novel/:id/items`	物品库	物品卡网格 + 详情 + 编辑
`/novel/:id/maps`	地图集	地图卡 + 层级地图树 + 详情 + 编辑
`/novel/:id/foreshadows`	伏笔管理	时间线视图（埋设章→回收章连线）、状态筛选、编辑
`/novel/:id/cover`	封面工坊	封面描述词展示/重新生成、上传本地封面图
`/settings/models`	模型设置	预设列表、自定义接入、密钥掩码、测试连通
`/settings/general`	通用设置	主题切换、默认导出路径、一致性审查间隔
`/settings/about`	关于	版本、数据目录、日志、备份入口、合规提示

8.3 阅读器设计

数据源为本地章节，无网络依赖
分页模式：按字数/屏宽自动分页；上下章滑动/淡入翻页动画
目录抽屉：章节树 + 当前进度 + 跳转
阅读设置：字号、行距、字体（衬线/黑体）、背景（宣纸/墨绿护眼/纯黑/纯白）、翻页方式
伏笔高亮：正文中伏笔关键词高亮（可开关），点击弹出伏笔详情卡

8.4 角色图谱

ECharts 力导向图：节点 = 角色（头像/阵营配色），边 = 关系（类型标签 + 强度）
支持：按阵营/类型筛选、拖拽布局、点击节点打开角色卡片、编辑关系（新增/修改/删除）、布局保存
数据来源：characters + character_relations

9. API / Binding 设计

采用 Wails v2 Binding：前端直接调用 Go 方法（JSON 序列化），并配合 Wails Events 做进度推送。接口分组如下（方法名示意，可微调）：

9.1 模型配置

ListModelConfigs() []ModelConfig
SaveModelConfig(cfg ModelConfig) (id int64, err error)
TestModelConnection(cfg ModelConfig) TestResult
DeleteModelConfig(id int64) error
SetDefaultModel(id int64) error

9.2 创作（生成控制）

CreateNovel(req CreateNovelReq) (novelID int64, err error)
StartGeneration(novelID int64, opts GenOptions) error
PauseGeneration(novelID int64) error
ResumeGeneration(novelID int64) error
CancelGeneration(novelID int64) error
GetGenerationStatus(novelID int64) GenStatus（含 current_step / progress / logs）
GetPendingTasks() []GenTask（启动时断点扫描）

9.3 小说与资产查询/编辑

ListNovels(page, size, filter) Page[NovelSummary]
GetNovel(id) Novel / UpdateNovelMeta(id, patch) error / DeleteNovel(id) error
GetOutline(novelID) Outline / SaveOutline(novelID, content) error
ListChapterOutlines(novelID, start, end) []ChapterOutline / SaveChapterOutline(id, patch) error
ListChapters(novelID, page, size, filter) Page[ChapterSummary]
GetChapter(id) Chapter / SaveChapter(id, patch) error / RegenerateChapter(id) error / RegenerateFromChapter(id) error
ListCharacters(novelID) []Character / GetCharacter(id) Character / SaveCharacter(id, patch) error / CreateCharacter(...) / DeleteCharacter(id) error
ListRelations(novelID) []Relation / SaveRelation(...) / DeleteRelation(id) error
ListItems(novelID) / GetItem / SaveItem / DeleteItem
ListMaps(novelID) / GetMap / SaveMap / DeleteMap
ListForeshadows(novelID, status?) []Foreshadow / SaveForeshadow(...) / ResolveForeshadow(id, chapterIndex) error
GetCoverInfo(novelID) CoverInfo / RegenerateCover(novelID) error / SetCoverImage(novelID, path) error

9.4 导出与阅读

ExportTXT(novelID int64, opts ExportOptions) (filePath string, err error)（opts：是否含简介/大纲、编码 UTF-8/GBK、输出目录）
GetChapterContent(id) string（阅读器按章拉取）
OpenDataDir() error

9.5 通用

GetSettings(key)/SetSettings(key, value) / GetTheme()/SetTheme(name)
GetAppVersion() / GetDataDir()

9.6 事件推送（进度实时性）

Wails Events:Emit("generation_progress", payload)：每完成一章、每切换步骤时推送 {novelID, step, currentIndex, totalSteps, chapterIndex, status}
前端订阅后实时刷新进度页与书架状态

10. TXT 导出规范

默认结构：书名 + 简介 + 目录 + 正文（卷标题 → 章标题 → 正文）
选项：是否包含简介/大纲、编码（UTF-8 默认 / GBK 可选）、单文件或按卷分文件
文件命名：书名.txt 或 书名_第X卷.txt
大文件处理：2000 章 × 3000 字 ≈ 600 万字符，必须流式写入，避免内存峰值；导出显示进度
默认导出目录：文档/AI小说工坊/导出/（可配置）
导出后弹窗提示路径 + "打开所在文件夹"

11. 打包与发布（EXE 安装包）

Wails v2 打包：wails build -nsis 产出安装包（NSIS）
安装默认目录：%LOCALAPPDATA%\Programs\AI小说工坊（免管理员权限）；创建桌面快捷方式
数据目录：%USERPROFILE%\Documents\AI小说工坊\（novels.db + media/ 封面图等），迁移 = 拷贝整个目录
应用图标：书本 + 墨水瓶元素；安装引导图与产品名一致
兼容性：Windows 10/11 x64；无 GPU 依赖
提供 --version 与日志目录：%LOCALAPPDATA%\AI小说工坊\logs\（滚动保留 7 天）

12. 非功能需求

12.1 性能

2000 章规模：书架/章节列表查询 < 1s（分页 + 索引）；阅读器章节拉取 < 200ms
生成并发 1–3；单章 3000 字生成时间取决于模型（预计 10–60s），生成全程不卡 UI（异步 + 事件推送）
常驻内存 < 300MB

12.2 可靠性

每章写入事务；生成中途崩溃不丢已完成章节
统一错误码与中文提示（如"API 密钥无效，请到设置页检查"）
备份入口：一键导出 zip（novels.db + media/）

12.3 安全与隐私

除用户主动调用所选模型 API 外，应用不联网、不上传任何数据
API 密钥 DPAPI 加密存储；日志不记录密钥与正文
关于页提供合规提示："AI 生成内容请遵守平台规则，商用前请自查版权与内容合规"

12.4 易用性

首次启动引导：选择模型 → 测试连通 → 示例生成（预置演示参数）
书架空状态：引导创建第一部小说
所有生成类操作均有进度反馈与可取消按钮

13. 验收标准（开发方交付自查）

#	验收项	标准
1	安装包	双击安装包完成安装，启动即用，无需安装额外环境（Node/Go/Python 均不需要）
2	模型接入	预设模型 ≥ 6 家可用；自定义 base_url 可连通；密钥不回显、日志无密钥
3	参数生成	8 项参数均有预设可选；章节数 10 与 2000 边界可用
4	产出完整	一部 10 章小说生成后：介绍/大纲/章节大纲/正文/角色+图谱/物品/地图/伏笔/封面词全部存在且可查看
5	一致性	生成 30 章以上抽查：无明显跑题、重复情节、人名/设定前后矛盾；伏笔可正常回收
6	断点续跑	生成至第 8 章强制退出，重启后提示继续，从第 9 章续写且不重复不丢章
7	人工编辑	所有资产生成后可在对应页面修改并保存生效
8	TXT 导出	导出成功、编码正确、章节数抽样核对一致、大文件不卡死
9	阅读器	目录/翻页/字号设置可用；伏笔高亮可用
10	主题	黑白切换覆盖全部页面（含顶部自绘标题栏），动画流畅可关闭
11	性能	2000 章规模列表与阅读流畅；生成过程 UI 不卡顿
12	历史	已生成小说列表历史完整，可再次打开查看/编辑/续生成

14. 开发计划（建议里程碑）

里程碑	内容	验收
M1 骨架	Wails 初始化、Vue 工程、主题系统、路由、自绘标题栏	应用可启动，黑白主题切换生效
M2 数据层	GORM 模型、迁移、全量 CRUD service	数据结构与 5.2 一致
M3 LLM 层	Provider 接口、预设模型、密钥加密、结构化输出	6 家以上可连通测试
M4 生成流水线	介绍→大纲→章节大纲→正文→摘要→伏笔；任务队列 + 断点续跑	验收项 4/5/6 通过
M5 资产页面	角色/图谱/物品/地图/伏笔/封面页 + 编辑	验收项 7 通过
M6 阅读器与导出	分页阅读器、TXT 导出	验收项 8/9 通过
M7 打磨	动画、空状态、错误提示、日志、备份、首次引导	验收项 10/11/12 通过
M8 打包发布	NSIS 安装包、图标、引导图	验收项 1 通过

15. 风险与对策

风险	对策
长文一致性不足	摘要滚动窗口、设定注入、伏笔台账、滚动一致性审查 Agent（见 6.6）
模型限流/失败	队列重试 + 指数退避 + 自动暂停人工续跑
Token 成本高	上下文预算分级、摘要压缩、可选小模型生成摘要
SQLite 并发写	生成流水线串行写入（单写连接），读走独立连接
Wails 打包/环境坑	M1 提前验证打包链路；SQLite 用纯 Go 驱动避免 CGO
2000 章数据量	分页索引齐全、正文按需拉取、导出流式写入

16. 附录：提示词模板与 JSON Schema 示例（开发可直接复用）

16.1 章节大纲输出 Schema

{
  "chapter_index": 12,
  "title": "初入宗门",
  "purpose": "主角通过入门考核并结识第一位同伴",
  "summary": "本章一句话概括",
  "events": ["主角通过入门考核", "与林小婉相识", "发现藏书阁密道"],
  "characters": [
    {"name": "沈夜", "role": "主角", "state": "通过考核"},
    {"name": "林小婉", "role": "重要配角", "state": "首次登场"}
  ],
  "foreshadow_set": [
    {"title": "藏书阁密道", "importance": "支线", "resolve_hint": "第三卷揭晓"}
  ],
  "foreshadow_resolve": [
    {"title": "入门考核的神秘考官", "resolve_chapter": 12}
  ],
  "ending_hook": "密道深处传来低语声",
  "continuity_from": "承接第 11 章结尾的考核结果揭晓"
}

16.2 角色卡片 Schema

{
  "name": "沈夜",
  "role_type": "主角",
  "gender": "男",
  "age": 17,
  "identity": "青云宗杂役弟子",
  "personality": "冷静、坚韧、轻微社恐",
  "appearance": "黑发、左眼下方泪痣、常年洗白的灰袍",
  "background": "孤儿，被守门人收养",
  "motivation": "寻找父母失踪的真相",
  "arc": "自卑逃避 → 承担责任 → 守护所爱",
  "faction": "青云宗",
  "status": "存活",
  "key_relations": [{"name": "林小婉", "relation": "同伴/暧昧"}]
}

16.3 正文生成 System Prompt 模板

你是资深网络小说作家。请严格按以下要求创作：

【文风】{{style}}　【视角】{{perspective}}
【硬性禁令】
1. 不得重复前文情节，不得偏离本章大纲事件；
2. 不得改变已冻结的角色/物品/地图设定；
3. 只允许设置大纲中已登记的伏笔，必须回收大纲要求回收的伏笔；
4. 本章结尾必须呼应 ending_hook；开篇必须承接上一章结尾。

【世界观设定】
{{world_setting}}

【本章大纲】{{current_outline}}
【上一章大纲】{{prev_outline}}　【下一章大纲】{{next_outline}}

【角色状态快照】{{character_snapshot}}
【伏笔台账（未回收）】{{foreshadow_open}}
【本章应回收】{{foreshadow_resolve_now}}

【前文摘要】{{recent_summaries}}
【上一章结尾】{{last_chapter_tail}}

【本章要求】事件：{{events}}；目标字数：{{word_count}}；结尾钩子：{{ending_hook}}
只输出正文，不要输出标题、大纲或解释。

16.4 章节摘要 Schema

{
  "chapter_index": 12,
  "summary": "2-3 句话概括本章剧情",
  "new_events": ["事件A", "事件B"],
  "character_state_changes": [{"name": "沈夜", "from": "杂役弟子", "to": "外门弟子"}],
  "foreshadow_planted": ["藏书阁密道"],
  "foreshadow_resolved": ["神秘考官"],
  "location_changes": {"沈夜": "青云宗 → 藏书阁"}
}

16.5 一致性审查输出 Schema

{
  "conflicts": [
    {
      "type": "设定冲突",
      "chapter": 45,
      "issue": "林小婉第 12 章已离宗，第 45 章又出现在宗门内",
      "suggestion": "改为两人在宗外小镇相遇"
    }
  ],
  "continuity_ok": true,
  "recommendations": ["第 50 章建议回收伏笔「藏书阁密道」"]
}

16.6 封面描述词输出 Schema（商业性质）

{
  "prompt": "完整的英文/中文文生图提示词：主角半身像、国漫厚涂、高饱和、强光影、泪痣灰袍少年、宗门剪影背景、动态光效、3:4 竖版……",
  "style_tags": ["国漫厚涂", "高饱和", "光影对比"],
  "composition": "主角半身像居中偏右，身后宗门剪影，视觉焦点在眼睛",
  "aspect_ratio": "3:4",
  "commercial_points": ["主角视觉记忆点：泪痣 + 灰袍", "市场风格：起点/番茄热血少年向封面"],
  "negative_prompt": "低质量、模糊、多余手指、文字、水印"
}

17. 给开发方（WorkBuddy）的实施要点清单

[ ] 确认桌面框架选型（默认 Wails v2，如需变更先说明）
[ ] 确认 UI 组件库（默认 Naive UI）与产品名
[ ] 实现优先级：生成流水线 + 断点续跑 + 一致性机制 为最高优先级
[ ] 所有"生成资产"一律走 JSON 结构化输出 + 解析修复
[ ] 密钥加密、日志脱敏、数据本地化三项安全基线不可妥协
[ ] 交付时附：安装包、源码、数据库初始化脚本、M1–M8 里程碑自测记录

本文档为 AI 小说工坊的完整开发依据；可视化附图见同目录 HTML 文件。