NovelForge 是怎么做出来的?Electron + Vue 3 + FastAPI 的 AI 写作工具架构深度解析

原创2026-10-13 21:27:141,402 阅读
文章标签:AI 应用AI 写作人工智能大模型AI AgentAgent 工作流知识图谱提示工程桌面应用后端

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 AI写作工具主编辑界面,左侧卡片库、中间章节编辑器、右侧上下文面板

图: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 输出做逐字段校验与自动修复。

NovelForge AI卡片生成对话框,按字段粒度流式生成并支持反馈迭代

图:AI 生成对话框——输入要求后按字段流式填充,可确认落库或反馈继续生成

NovelForge Schema结构构建器,可视化定义卡片JSON Schema字段

图: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 等过滤器。前端提供可视化选择器来生成这些表达式:

NovelForge上下文注入@DSL引用选择器,按类型引用最近章节卡片字段

图:@DSL 引用选择器——可视化生成"引用最近 3 章标题与正文"这类上下文表达式

第二层:知识图谱 + 记忆提取器。 章节写完后可提取角色关系存入图谱(默认 SQLite,可切 Neo4j),backend/app/services/kg_provider.py 以 Protocol 接口屏蔽两种存储差异;backend/app/services/memory_extractors/ 则把角色动态、场景状态、物品状态、组织状态等六类"记忆"统一为"提取 → 预览 → 确认写入"的流程。续写下一章时,backend/app/services/context_service.py 会按参与者自动组装事实子图注入上下文。

NovelForge灵感助手Agent面板,对话式修改卡片并调用工具

图:灵感助手——基于 LangChain 工具调用的对话 Agent,可直接创建/修改卡片

五、工作流系统:从 DAG 到代码式 DSL 的演进

工作流是 NovelForge 架构中最有探索性的部分。v0.9.0 起,项目放弃了传统的 DAG 节点连线,改用代码式工作流:用类 Python 语句 + 注释标记描述流程,例如内置的拆书工作流 backend/app/bootstrap/workflows/拆书工作流.wf#L8-L55:

# 选择当前执行的目标项目
#</node>
project = Logic.SelectProject(project_id=10)

这套设计的工程实现分为四层:

  1. 解析层:backend/app/services/workflow/parser/marker_parser.py#L22-L48 将 #@node(...) 标记块解析为 ExecutionPlan,并做依赖校验;
  2. 执行层:engine/ 下的 async_executor 按计划调度,支持 async=true 异步节点与 Logic.Wait 等待语义;
  3. 运行时:backend/app/services/workflow/engine/runtime.py#L28-L59 用信号量实现全局并发槽位(默认 5 个),支持暂停/恢复/取消;
  4. 触发层:保存卡片、创建项目等事件触发工作流,触发的 run_id 通过 backend/app/core/workflow_context.py 的 ContextVar 随请求流转,最终由 WorkflowHeaderMiddleware 写入响应头,前端据此感知后台运行状态。

对 AI 而言,代码式描述"几十行就能表达 DAG 几百行的节点与连线",这也为工作流 Agent(自然语言生成/修改工作流)铺平了道路。

NovelForge工作流工作室,可视化与代码双视图编辑工作流

图:工作流工作室——节点库 + 可视化块编辑 + 代码视图,右侧可实时查看执行结果

六、读码路线:如何深入 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

推荐阅读顺序:

  1. 入口与启动:backend/main.py → backend/app/core/startup.py#L179-L201,理解 lifespan、初始化器注册(@initializer)、事件与节点发现的"装饰器自注册"模式;
  2. 内置资源播种:backend/app/bootstrap/ 下的提示词、知识库、工作流模板(*.wf),它们就是产品的"预装大脑";
  3. AI 管线:backend/app/services/ai/core/chat_model_factory.py 看多模型适配,backend/app/services/ai/generation/instruction_generator.py 看指令流生成与校验修复;
  4. 工作流引擎:backend/app/services/workflow/ 的 parser → execution_plan → async_executor 三段式;
  5. 前端状态流:frontend/src/renderer/src/stores/ 的 Pinia store 与 frontend/src/renderer/src/api/ 的接口封装,对照 frontend/package.json 的依赖清单理解各库分工。

写在最后

NovelForge 的架构给出的启示可以浓缩为三点:用本地化后端承载 AI 编排(流式输出、工作流、文件扫描都不受浏览器限制);用 Schema 约束 AI 输出(把不确定性收敛为可校验的结构);用自注册机制保持扩展性(提示词、工作流节点、初始化器都是"加文件即生效")。无论是想写一个 AI 桌面应用,还是为写作流程做自动化,这套 Electron + Vue 3 + FastAPI 的骨架都值得拿来参考。

登录后查看全文
NovelForge