NovelForge 是怎么做出来的?Electron + Vue 3 + FastAPI 的 AI 写作工具架构深度解析
NovelForge 是怎么做出来的?Electron + Vue 3 + FastAPI 的 AI 写作工具架构深度解析
NovelForge 是一款面向长篇小说的 AI 写作工具,采用 Electron + Vue 3 前端 + FastAPI 后端的本地架构:桌面端通过 electron-vite 打包,前端以 Vue 3 + TypeScript + Pinia 构建卡片式创作界面,后端由 FastAPI 提供 HTTP/SSE 接口,配合 SQLite 存储与 LangChain 接入各家大模型,实现 Schema 驱动的 AI 生成、上下文注入与代码式工作流。本文带你从源码角度拆解这套架构是如何搭起来的。
一、技术选型:为什么是这套组合?
先给出一张"技术栈速览表":
| 层级 | 技术选型 | 在 NovelForge 中的职责 |
|---|---|---|
| 桌面壳 | Electron 35 + electron-vite | 主进程、窗口管理、API Key 安全存储 |
| 前端 UI | Vue 3 + TypeScript + Pinia + Element Plus | 卡片库、章节编辑器、工作流工作室 |
| 代码编辑 | CodeMirror 6 | 工作流代码式 DSL 编辑 |
| 后端框架 | FastAPI + Uvicorn | REST + SSE 流式接口 |
| ORM/数据库 | SQLModel(Pydantic + SQLAlchemy)+ SQLite | 卡片、项目、配置等核心数据 |
| 知识图谱 | SQLite(默认)/ Neo4j(可选) | 角色关系、一致性校验 |
| AI 框架 | LangChain(OpenAI / Gemini / Anthropic 等) | 流式生成、结构化输出、工具调用 |
这套选型的核心思路是:前端负责"体验",后端负责"智能"。写作类应用对长会话流式输出、本地文件扫描、后台工作流有强需求,因此作者把 LLM 编排、工作流引擎等重逻辑全部放在独立的 Python 服务中,Electron 只承担界面与系统能力(如 keytar 安全存储 API Key)。
二、总体结构:一个主进程 + 一个本地服务
图:NovelForge 的主创作界面——三栏布局是理解整个前端的钥匙
2.1 Electron 三进程模型
前端源码位于 frontend/src/,严格遵循 Electron 的经典三层结构:
- 主进程:frontend/src/main/index.ts 中创建
BrowserWindow、注入 CSP 策略,并通过additionalArguments把后端端口传给渲染进程; - 预加载脚本:frontend/src/preload/index.ts 通过
contextBridge暴露setApiKey/getApiKey等方法,API Key 由主进程调用 keytar 写入系统凭据库,密钥不落渲染进程; - 渲染进程:
frontend/src/renderer/src/下按components/、views/、stores/(Pinia)、services/、api/分层组织。
一个巧妙的设计是端口协商:主进程启动时读取 backend/.env 的 APP_PORT,打包版与开发版各有一套查找路径(见 frontend/src/main/index.ts#L10-L18),桌面前端与后端服务因此共享同一份配置。
2.2 前后端通信:HTTP + SSE 流式
后端入口 backend/main.py 在 lifespan 钩子里完成数据库初始化、内置资源播种、工作流节点注册,然后统一挂载 backend/app/api/router.py 中的 15 组路由(projects / cards / ai / workflows / knowledge……)。
AI 类接口全部走 SSE 流式响应:前端封装在 frontend/src/renderer/src/api/streaming.ts#L35-L66,后端则通过 FastAPI 的异步生成器逐事件推送(字段填充、校验结果、完成/错误)。这套机制让"字段粒度流式生成"成为可能——用户不再需要盯着转圈等待整卡结果。
三、数据层:Schema-first 是一切的地基
3.1 SQLite + 安全增量迁移
核心数据全部落在 backend/novelforge.db(SQLite),引擎创建见 backend/app/db/session.py#L8-L12。值得一提的工程设计是启动时的"安全加列"机制:backend/app/core/startup.py#L54-L108 会对比模型与现网表结构差异,仅自动补齐可安全追加的普通列,主键/外键/唯一约束等复杂变更则交给 Alembic。对单机应用来说,这是一个成本极低又足够稳健的迁移策略。
3.2 JSON Schema 驱动的卡片结构
NovelForge 把"每张卡片长什么样"抽象为 JSON Schema:
- 类型级 Schema:在"设置 → 卡片类型"中用结构构建器定义,作为该类型的默认结构;
- 实例级覆写:单张卡片可在 Schema Studio 中二次覆写,或"应用到类型";
- AI 级校验:生成时由 Schema 动态构建 Pydantic 模型,对 LLM 输出做逐字段校验与自动修复。
图:AI 生成对话框——输入要求后按字段流式填充,可确认落库或反馈继续生成
图:Schema Studio 结构构建器——左侧可视化编辑字段,右侧实时预览 Schema JSON
这条"Schema → 动态模型 → 结构化生成 → 校验修复"的管线,源码主入口在 backend/app/services/ai/generation/instruction_generator.py#L46-L105。它把"AI 输出不可控"这个普遍痛点,转化为"输出必须满足某个结构"的确定性问题——这是 NovelForge 架构中最值得学习的一环。
四、AI 生成管线:上下文注入 @DSL 与记忆层
长篇小说最大的敌人是"前后不一致"。NovelForge 用两层机制应对:
第一层:@DSL 上下文注入。 提示词模板中可用 @ 引用项目内任意数据:按标题(@卡片标题)、按类型(@type:角色卡)、特殊引用(@self / @parent),并支持 previous、sibling、filter 等过滤器。前端提供可视化选择器来生成这些表达式:
图:@DSL 引用选择器——可视化生成"引用最近 3 章标题与正文"这类上下文表达式
第二层:知识图谱 + 记忆提取器。 章节写完后可提取角色关系存入图谱(默认 SQLite,可切 Neo4j),backend/app/services/kg_provider.py 以 Protocol 接口屏蔽两种存储差异;backend/app/services/memory_extractors/ 则把角色动态、场景状态、物品状态、组织状态等六类"记忆"统一为"提取 → 预览 → 确认写入"的流程。续写下一章时,backend/app/services/context_service.py 会按参与者自动组装事实子图注入上下文。
图:灵感助手——基于 LangChain 工具调用的对话 Agent,可直接创建/修改卡片
五、工作流系统:从 DAG 到代码式 DSL 的演进
工作流是 NovelForge 架构中最有探索性的部分。v0.9.0 起,项目放弃了传统的 DAG 节点连线,改用代码式工作流:用类 Python 语句 + 注释标记描述流程,例如内置的拆书工作流 backend/app/bootstrap/workflows/拆书工作流.wf#L8-L55:
# 选择当前执行的目标项目
#</node>
project = Logic.SelectProject(project_id=10)
这套设计的工程实现分为四层:
- 解析层:backend/app/services/workflow/parser/marker_parser.py#L22-L48 将
#@node(...)标记块解析为ExecutionPlan,并做依赖校验; - 执行层:
engine/下的async_executor按计划调度,支持async=true异步节点与Logic.Wait等待语义; - 运行时:backend/app/services/workflow/engine/runtime.py#L28-L59 用信号量实现全局并发槽位(默认 5 个),支持暂停/恢复/取消;
- 触发层:保存卡片、创建项目等事件触发工作流,触发的 run_id 通过 backend/app/core/workflow_context.py 的
ContextVar随请求流转,最终由WorkflowHeaderMiddleware写入响应头,前端据此感知后台运行状态。
对 AI 而言,代码式描述"几十行就能表达 DAG 几百行的节点与连线",这也为工作流 Agent(自然语言生成/修改工作流)铺平了道路。
图:工作流工作室——节点库 + 可视化块编辑 + 代码视图,右侧可实时查看执行结果
六、读码路线:如何深入 NovelForge 源码?
想自己动手或二次开发,建议按这条路线阅读:
git clone https://gitcode.com/gh_mirrors/no/NovelForge
cd NovelForge/backend && pip install -r requirements.txt && python main.py
cd ../frontend && npm install && npm run dev
推荐阅读顺序:
- 入口与启动:backend/main.py → backend/app/core/startup.py#L179-L201,理解 lifespan、初始化器注册(
@initializer)、事件与节点发现的"装饰器自注册"模式; - 内置资源播种:
backend/app/bootstrap/下的提示词、知识库、工作流模板(*.wf),它们就是产品的"预装大脑"; - AI 管线:backend/app/services/ai/core/chat_model_factory.py 看多模型适配,backend/app/services/ai/generation/instruction_generator.py 看指令流生成与校验修复;
- 工作流引擎:backend/app/services/workflow/ 的 parser → execution_plan → async_executor 三段式;
- 前端状态流:frontend/src/renderer/src/stores/ 的 Pinia store 与 frontend/src/renderer/src/api/ 的接口封装,对照 frontend/package.json 的依赖清单理解各库分工。
写在最后
NovelForge 的架构给出的启示可以浓缩为三点:用本地化后端承载 AI 编排(流式输出、工作流、文件扫描都不受浏览器限制);用 Schema 约束 AI 输出(把不确定性收敛为可校验的结构);用自注册机制保持扩展性(提示词、工作流节点、初始化器都是"加文件即生效")。无论是想写一个 AI 桌面应用,还是为写作流程做自动化,这套 Electron + Vue 3 + FastAPI 的骨架都值得拿来参考。





