NovelForge

NovelForge 是一款具备数百万字级长篇创作潜力的 AI 辅助写作工具。它不仅是编辑器，更是一套集世界观构建、结构化内容生成于一体的解决方案。

长篇创作中，维持一致性、保证可控性、激发持续灵感是最大的挑战。为此，NovelForge 围绕四大核心理念构建：模块化的 “卡片”、可自定义的 “动态输出模型”、灵活的 “上下文注入” 与保证一致性的 “知识图谱”。

📑 目录

快速导航

• ✨ 核心特性
• 📅 更新日志
• 🛠️ 技术栈
• 🚀 运行指南
• ✍️ 创作流程
• ⚙️ 高级功能与配置
• 📂 项目结构
• 🔭 展望

按功能跳转

• Schema-first：类型/实例结构与参数
• 提示词工坊（Prompt Workshop）
• 上下文注入（@DSL）详解
• 工作流系统（代码式工作流 + Workflow Agent）
  • 工作流工作室
  • 触发器配置
  • 工作流状态栏（全局后台运行）
  • 节点级进度与中断恢复（Beta）
  • 持久化工作流 vs 临时工作流
  • 内置工作流模板
  • 项目初始化工作流
  • 工作流 Agent（自然语言编写工作流）
  • 工作流使用示例（拆书工作流）

协作与规划

• 贡献指南
• 后续规划

✨ 核心特性

• 📚 Schema 驱动的卡片创作

  • 每种卡片都可定义结构（Schema），AI 生成会按结构校验，减少“看起来能用、落地却混乱”的输出。

• ⚡ 指令流式 AI 卡片生成

  • 不再是“一次性整段生成”。现在是“输入要求 → 字段粒度流式填充 → 你确认或反馈继续生成”，更可控、更容易修正。生成过程更加丝滑，避免长时间等待生成结果。
  • 该能力聚焦于“当前这张卡片”的生成与完善，关闭生成对话框后本次会话即结束。

• 📝 章节正文字数控制

  • 章节正文续写支持两种模式：提示词约束 与 控制模式。
  • 提示词约束 更自然、成本更低；控制模式 会按目标总字数切分多轮预算，控制更稳，但会消耗更多 token。

• ✅ 通用审核与审核结果卡片

  • 审核统一采用“草稿预览 → 确认保存为审核结果卡片”的流程。
  • 不同卡片类型可切换不同审核提示词，但结果卡片结构保持一致，便于统一查看与引用。

• 🧠 上下文注入 + 知识图谱一致性

  • 通过 @DSL 精准引用项目数据；结合 关系图谱与动态信息，让后续生成更贴近已写内容与角色关系。

• 🔮 灵感助手（Agent）

  • 可持续对话、引用卡片、调用工具修改内容。你可以像和搭档协作一样打磨设定，而不是反复整卡重生成。

• 🧩 代码式工作流系统

  • 已重构为代码式工作流主线（去掉旧 DAG 方案），支持可视化编辑、触发执行与复用，适合把常用创作流程自动化。

• 🤖 工作流 Agent

  • 你可以直接用自然语言描述需求，让 Agent 帮你写/改工作流代码、做校验并应用变更。

• 💡 灵感工作台 (Ideas Workbench)

  • 支持自由卡片、跨项目引用、移动/复制回正式项目，适合专门做脑暴和素材沉淀。

📅 更新日志

🛠️ 技术栈

• 前端 (Frontend): Electron, Vue 3, TypeScript, Pinia, Element Plus
• 后端 (Backend): FastAPI, SQLModel (Pydantic + SQLAlchemy), Uvicorn
• 数据库 (Database): SQLite (核心数据), Neo4j (知识图谱)

🚀 运行指南

无论你是想直接体验，还是参与开发，都可以轻松开始。

0. Neo4j Desktop（可选，非必须）

项目已默认使用sqlite代替实现关系图谱存储，但也可以切换为neo4j来存储，步骤如下

• 请下载并安装 Neo4j Desktop，推荐版本 5.16 或更高。
• 下载地址: Neo4j Desktop
• 安装后，创建一个本地数据库实例，并确保其处于运行状态。默认连接信息可在 .env 文件中配置。

方式一：从源码运行 (开发者/最新功能)（非开发者建议用方式二）

1. 后端 (Python / FastAPI)

# 克隆仓库
git clone https://github.com/RhythmicWave/NovelForge.git
cd NovelForge/backend

conda create -n NovelForge python=3.11
conda activate NovelForge

# 安装依赖
pip install -r requirements.txt

将backend/.env.example文件修改为.env

# 如默认端口被占用，可在 backend/.env 中修改（范围 1-65535）
APP_PORT=53210

# 运行后端服务
python main.py

2. 前端 (Node.js / Electron)

# 进入前端目录
cd ../frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
# 也可以用下面命令启动web页面
// npm run dev:web

3. 一行命令同时启动前后端（npm）

npm run dev

重要：.env 的 BOOTSTRAP_OVERWRITE

启动后端时，系统会按需初始化/更新内置资源（知识库、提示词、工作流等）。是否覆盖更新由 .env 中的 BOOTSTRAP_OVERWRITE 控制。

• 建议设置：

  • 如果你没有直接修改过内置资源，建议设置为：

    BOOTSTRAP_OVERWRITE=true
    

    这样可以在升级版本或重启时自动同步最新的内置知识库/提示词/工作流。
  • 如果你曾直接修改过“内置”资源，建议设置为 false，以避免被覆盖。

• 建议（避免被覆盖）：

  • 不要直接编辑“内置”资源。
  • 如需定制，请新建一个副本（复制知识库/提示词/工作流后重命名），在副本上修改。这样即使将来设置 BOOTSTRAP_OVERWRITE=true，你的自定义副本也不会被更新逻辑覆盖。

方式二：使用发行版 (快速上手)

不定期打包发布版本，无需配置开发环境，开箱即用。

1. 前往项目的 Releases 页面下载最新的便携版压缩包 (.zip 或 .7z)。
2. 解压到任意位置。
3. 进入解压后的文件夹，找到 backend 目录，按需编辑 .env 文件以配置数据库连接。 如默认的 54321 端口被占用，可修改 APP_PORT；后端与桌面前端会读取同一配置。
4. 运行 backend/NovelForgeBackend.exe 启动后端服务。
5. 返回上一级，运行 NovelForge.exe 启动主程序。

大部分数据都存储在backend/novelforge.db数据库中，当版本更新/迁移时，将该数据库文件复制到对应位置即可。

✍️ 创作流程

1. 配置大语言模型 (LLM)

   • 首次启动后，在设置中添加你的 AI 模型配置，如 API Key、Base URL 等。 推荐使用Gemini 2.5Pro级别以上的LLM进行创作

2. 创建项目与初始化工作流

   • 新建项目时，可以选择一个初始化工作流（通常是 onprojectcreate 类型）来自动创建预设卡片。系统内置了"项目创建·雪花创作法"工作流，会按照雪花创作法自动创建一套完整的卡片树。

3. 自顶向下，填充核心设定

   • 从最高层卡片开始逐步推进（一句话梗概 → 故事大纲 → 世界观 → 核心蓝图）。
   • 每张卡片都可以打开 AI 生成对话框，输入本次要求，系统会按字段粒度流式生成。
   • 你可以在生成后选择“确认”直接落库，或提交反馈意见继续迭代，不满意不必整卡重来。 完成核心蓝图卡片创作后，点击保存，会自动根据分卷数量创建对应分卷卡片。 继续完成分卷大纲创作即可，从第1卷开始。 完成之后，会自动根据阶段数创建阶段大纲子卡片、写作指南卡片。建议先生成写作指南卡片，生成写作指导信息，再进行阶段大纲卡片创作。 AI生成卡片示例流程： 生成完成后点击完成，再保存卡片即可。或者对某些字段不满意，则输入指导意见进行反馈。

4. 借助灵感助手完善内容

   • 在写作过程中，如果你想进一步打磨或优化卡片内容，可以随时使用右侧的灵感助手。
   • 选中任意卡片后，灵感助手会自动读取该卡片的内容，方便你参考和思考。
   • 你可以直接向助手提出具体问题，比如“这个角色的动机是否合理？”、“怎样让这个场景更有张力？”等。
   • 灵感助手会结合当前卡片内容，给出针对性的建议，你可以与助手反复交流，逐步完善想法。
   • 通过“添加引用”按钮，还能把当前项目或其他项目的相关卡片内容加入对话，激发更多创意火花。
   • 灵感助手具备感知上下文、调用工具修改/创建卡片内容的能力（实验性）

AI 生成对话框 vs 灵感助手（如何选择）

• AI 生成对话框：聚焦当前单张卡片，用于快速生成与迭代该卡片内容；会话仅持续到本次生成流程结束，关闭对话框后会话清空。
• 灵感助手：用于跨卡片、跨项目的持续对话与创作；可引用多个卡片进行分析与联动创作，并且对话历史可持久保存。
• 建议用法：
  • 目标是“把这张卡片写好” → 用 AI 生成对话框。
  • 目标是“跨设定联动思考/长期讨论/多卡片协作” → 用灵感助手。

5. 完成阶段大纲创作后，自动生成章节大纲、章节正文卡片，并自动注入每章需要参与的实体。

6. 进入章节创作

   • 完成上述步骤后，点击对应的章节正文卡片，打开章节编辑器，进入核心的写作界面。右侧的上下文面板会自动为你准备好当前章节所需的全部背景资料。

   • 可点击续写进行AI生成（如果没有任何内容，则自动从头开始写）。

   • 续写时可选择两种字数控制模式：

     • 提示词约束：只做提示词层面的字数约束，文本更自然，也更省 token。
     • 控制模式：按目标总字数切分为多轮预算，适合对章节总字数要求更严格的情况，但会消耗更多 token。

   • 若对生成内容不满意，可选中内容点击右键进行快速编辑，然后输入要求，点击润色/扩写，可以重写这部分内容。

   • 章节正文也支持直接审核：

     • 点击顶部 审核 按钮即可运行审核
     • 可通过按钮右侧下拉切换审核提示词
     • 审核会先返回草稿，确认后再保存为审核结果卡片
     • 保存后的结果会自动放入根级 审核结果 文件夹，并可在右侧面板中查看

   • 内容创作完成后，点击入图关系，解析出角色之间的关系存入知识图谱，供后续写作时参考。 提取完成后，点击确认即可存入neo4j数据库。

   • 建议再提取角色动态信息，可用成本更低的模型进行提取。

   • 以上步骤完成后，进行下一章创作时，自动注入相关参与实体的信息

7. 灵感工作台：捕捉创意火花

   • 有了新点子却一时不知道归属哪个项目？点击页面顶部的“灵感”按钮，即可打开独立的灵感工作台窗口。
   • 在这里，你可以随手记录各种想法，自由创建不同类型的卡片，无需考虑项目结构，专注于把灵感落到实处。
   • 右侧的灵感助手支持引用任意项目的卡片内容，方便你跨项目查阅、对比和组合，激发更多创意。
   • 当某个想法逐渐成型，只需用顶部的“移动/复制到项目”功能，就能把自由卡片一键归入正式项目，创意自然衔接到后续创作中。

⚙️ 高级功能与配置

虽然 NovelForge 提供了一套推荐的创作流程，但其真正的强大之处在于高度的灵活性。你可以完全抛开预设，利用以下工具，组合出专属于你自己的创作体系。

Schema-first：类型/实例结构与参数

• 在 设置 -> 卡片类型 中，使用结构构建器为类型定义 json_schema（支持基础类型、relation(embed)、tuple 等）。类型 Schema 将作为该类型卡片的默认结构。

• 在具体卡片中，可打开 结构（Schema Studio）对该卡片实例的结构进行覆写，或一键"应用到类型"。

  

  应用到类型之后，后续再创建该类型卡片将使用新的结构。

• 卡片 AI 参数：通过编辑器工具栏设置模型、提示词与温度等参数（llm_config_id、prompt_name、temperature、max_tokens、timeout）。

• 完成以上设置后，即可在项目中创建该类型卡片并进行 AI 生成。系统会将该卡片的"有效 Schema"一并用于结构化校验与输出。 新建卡片时也可以直接从已有卡片中拖动到下方，自动创建

  

• Schema 支持嵌入（$ref 到类型 $defs），可以组合复用已有结构，便于复合能力搭建。

  

注意，尽量新增模型而不是修改已存在模型结构，避免和已有数据冲突。

章节审核与通用审核

除章节正文外，其它卡片（例如阶段大纲、通用文本等）也可以直接使用顶部的 审核 按钮。

• 审核入口统一为一个按钮，按钮右侧可切换审核提示词
• 阶段大纲默认使用 阶段审核 提示词
• 普通卡片默认使用 通用审核 提示词
• 审核结果统一保存为 内容审核卡片

这样你既可以为不同卡片类型配置不同审核标准，又能保持统一的审核结果结构和查看方式。

提示词工坊 (Prompt Workshop)

• 所有 AI 功能的背后都是可编辑的提示词模板。你可以在这里修改预设模板，或创建全新的模板。
• 知识库注入: 支持通过 @KB{name=知识库名称} 语法，在提示词中动态引用"知识库"内容，为 AI 提供更丰富的背景信息。

上下文注入 (@DSL) 详解

这是 NovelForge 的特色。它允许你在提示词模板中，用 @ 符号精确地引用项目中的任何数据注入为上下文。

• 按标题引用: @卡片标题 或 @卡片标题.content.某个字段
• 按类型引用: @type:角色卡 (所有角色卡)
• 特殊引用: @self (当前卡片), @parent (父卡片)
• 强大的过滤器:
  • [previous]: 获取同级的前一个卡片。
  • [previous:global:n]: 获取全局顺序（树状先序）中最近的n个同类型卡片。
  • [sibling]: 获取所有同级兄弟卡片。
  • [index=...]: 按序号获取，支持表达式，如 $self.content.volume_number - 1。
  • [filter:...]: 按条件过滤，如 [filter:content.level > 5] 或 [filter:content.name in $self.content.entity_list]。
• 字段级别选中: 可选中整个卡片数据，也可以单独选中卡片的字段。

例如，引用最近3章的章节标题及原文:

工作流系统（代码式工作流 + Workflow Agent）

工作流系统用于把常见创作动作（初始化项目、保存后自动生成子卡、批量处理内容等）编排成可复用流程，并在合适时机自动执行。

当前已完成代码式主线重构，旧 DAG 式工作流方案已移除。

工作流系统

• 访问“工作流”页面，可在可视化与代码视图中编辑工作流。
• 可通过节点库快速搭建流程，也可以直接编写/修改代码。
• 参数面板支持实时编辑与校验，修改后可安全应用到工作流代码。
• 支持查看运行记录、执行结果与错误信息，便于迭代调试。

触发器配置

每个工作流可以配置一个或多个触发器，定义何时自动执行：

• 保存时触发：当指定类型卡片保存时自动执行
• 创建项目时触发：新建项目后自动执行（常用于项目初始化）

工作流状态栏（全局后台运行）

• 工作流运行后，状态会显示在全局工作流状态栏中（不局限于工作流页面）。
• 你可以切换到其它页面继续创作，工作流在后台执行。
• 状态栏会显示运行中数量、当前节点、总体进度与完成状态。

节点级进度与中断恢复（Beta）

• 系统支持节点级进度上报，可看到“当前执行到哪个节点”。
• 支持暂停/恢复执行，并保留运行状态用于续跑。
• 支持运行记录持久化与查看。
• 说明：这部分能力已可用，复杂流程下可能存在少量边界问题（如个别恢复场景）。

持久化工作流 vs 临时工作流

• 临时工作流（默认）：运行记录用于当前查看与调试，后续会被自动清理。
• 持久化工作流：开启“持久化保存”后，运行记录会长期保留（受系统保留策略影响）。

内置工作流模板

系统预置了多个常用工作流，可直接使用或作为参考：

• 项目创建·雪花创作法: 新建项目时按照雪花创作法自动创建初始卡片结构
• 世界观·转组织: 从世界观设定的势力列表自动生成组织卡
• 核心蓝图·落子卡: 根据蓝图内容自动创建角色卡、场景卡和分卷卡片
• 分卷大纲·落子卡: 根据分卷大纲自动创建阶段大纲和写作指南
• 阶段大纲·落章节卡: 根据阶段大纲的章节列表自动创建章节大纲和正文卡片
• 拆书工作流: 用于拆解既有文本结构并落地到卡片体系

项目初始化工作流

新建项目时，可以选择一个 onprojectcreate 触发器的工作流作为项目模板：

• 默认选择"项目创建·雪花创作法"，自动创建作品标签、金手指、一句话梗概、故事大纲、世界观设定、核心蓝图等卡片
• 也可以在工作流工作室中创建自己的项目初始化工作流，完全自定义项目起始结构
• 支持复杂的初始化逻辑，如根据条件创建不同的卡片结构

工作流 Agent（自然语言编写工作流）

• 在工作流页面打开工作流 Agent，对它说出你的目标，例如“创建一个多 AI 辩论流程并输出到指定项目”。
• Agent 会自动读取当前工作流、生成修改方案、校验后给出可应用结果。
• 使用这种方式，无需自己搭建工作流，可以快速实现复杂流程。
• 目前可能还存在一些bug

（右边执行界面是详细进度显示，工作流状态栏是简单的进度展示） 一些长时间任务执行可以切换到其它界面，无需一直在工作流界面等待。执行完成后工作流状态栏会闪烁提示。

工作流使用示例

拆书工作流 先建一个空项目

进入工作流界面，选择拆书工作流

设置目标项目、模型名、小说章节目录

注意，小说文件存放需按满足预设的格式要求，例如按每章节进行分割存储为txt文件

点击执行即可

拆书结果：

提取章节大纲→划分阶段故事线→根据所有阶段故事性进行全局分析

许可证协议

本项目采用双许可证授权模式：

• 默认情况下，本项目基于 GNU Affero General Public License v3.0 (AGPLv3) 授权协议
• 提供服务型商用：将本项目（或其修改版本）作为后端以 SaaS、托管或其他形式向第三方提供服务，须通过作者获取商业授权许可。

请遵守开源协议条款，并在适用场景下取得相应授权。

📂 项目结构

NovelForge/
  ├── backend/        # FastAPI 后端
  │   ├── app/
  │   │   ├── api/        # API 路由
  │   │   ├── db/         # 数据库模型与会话
  │   │   ├── schemas/    # Pydantic 数据模型
  │   │   └── services/   # 核心业务逻辑
  │   └── main.py       # 入口
  │
  └── frontend/       # Electron + Vue3 前端
      └── src/
          ├── main/       # Electron 主进程
          ├── preload/    # 预加载脚本
          └── renderer/   # Vue 渲染进程
              └── src/
                  ├── components/ # Vue 组件
                  ├── services/   # 前端服务
                  ├── stores/     # Pinia 状态管理
                  └── views/      # 页面视图

展望

NovelForge 目前仍处于迭代的早期阶段，作者深知该项目在创作流程、一致性维持、 UI 设计、交互体验等方面还有巨大的改进空间。

最好的工具源于社区的智慧。无论你是创作者还是开发者，都真诚地欢迎你：

• 在 Issues 中提出宝贵的功能建议或反馈问题。
• 分享你对创作流程的独到见解。

交流群