剧情引擎内核仍在高速演进中。欢迎提交 Issue / PR；涉及商业化封装、私有素材、未公开设定稿的内容请先脱敏。
开源剧情引擎内核
面向长篇 AI 创作的基础设施：持久记忆 · 知识图谱 · 自动推进流水线 · 质量治理闭环
PlotPilot 是一个剧情引擎内核（Narrative Engine Kernel），不是聊天式写作助手，也不是一组提示词模板。
大多数 AI 写作工具解决的是"生成一段文字"的问题。PlotPilot 解决的是一个更难的工程问题：
如何让 AI 系统在数十万字的叙事跨度里，维持人物一致性、因果链完整性、伏笔闭合率，并在无人值守的条件下持续推进？
这不是提示词优化问题，而是系统工程问题。PlotPilot 的答案是：构建一套完整的剧情状态管理基础设施，让 LLM 只做它最擅长的事——在结构化上下文中生成高质量叙事片段。
本仓库是这套基础设施的开源内核。上层生态（垂直应用、编辑器插件、云服务）均以此为基石构建。
项目边界很明确：
- 不是 单轮续写器：核心目标是长篇连续生产，而不是回答一次写作请求。
- 不是 大上下文堆料：世界观、人物、伏笔、故事线会被结构化为可追踪状态。
- 不是 单一前端产品：官方工作台只是内核的一个使用界面，核心能力通过 REST API 暴露。
PlotPilot 内核由五个相互协作的子系统构成：
引擎在任意时刻都持有完整的叙事快照，包含：
- Story Bible：人物档案（含 POV 防火墙、登场频率调度）、地点图、世界设定三元组
- 章级摘要链：每章生成后自动提炼的压缩摘要，构成跨章上下文骨架
- 叙事事件流：关键事件的时序登记表，支持因果链追溯
- 故事线 DAG：多故事线的有向无环图，可视化分支与汇合点
- 伏笔注册表：钩子（Hook）的开启、悬置、消费状态完整追踪
任何一次章节生成，引擎都会从上述快照中动态装配上下文窗口，而非依赖模型自身的"记忆"。
引擎维护两条并行索引：
- 章内容索引：基于 FAISS / ChromaDB 的本地向量库，对所有已写章节做语义切片索引
- 三元组索引：从正文中自动抽取的
(主体, 关系, 客体)三元组，支持结构化与语义混合查询
生成时，引擎通过当前场景语义自动召回相关历史内容，注入上下文，消除"模型失忆"问题。嵌入服务支持 OpenAI 兼容 API（轻量）和本地 sentence-transformers 模型（离线高性能）。
这是引擎最核心的系统组件。当前生产入口收敛在 engine/runtime/engine_daemon.py：由 EngineDaemon 承接守护进程生命周期，委托 StoryPipelineRunner 运行章节规划、写作、审计与状态推进；章节写作默认走 BaseStoryPipeline 十步管线。
宏观规划（部 / 卷 / 幕结构）
└─▶ 幕级节拍规划（Beat Sheet 生成）
└─▶ 章节生成循环
├─▶ 叙事治理预算
├─▶ 章节执行剧本准备
├─▶ 上下文装配（人物 / 世界观 / 记忆 / 伏笔）
├─▶ LLM 调用
├─▶ 内容策略验证
├─▶ 文风漂移检测
├─▶ 章末管线（摘要 / 事件 / 三元组 / 伏笔）
├─▶ 向量索引更新
├─▶ 张力评分
└─▶ 状态落库 → 继续 / 重写 / 暂停
关键工程特性：
- 单一生产入口：
scripts/start_daemon.py构造依赖并启动EngineDaemon - 可回退写作路径：默认
StoryPipeline写作，PLOTPILOT_USE_STORY_PIPELINE=off/legacy可临时回退 - 熔断保护：连续失败超过阈值自动暂停，附带诊断信息
- 单写者路由（Write Dispatch）：所有 SQLite 写操作经由统一调度器串行执行，消除并发写冲突
- SSE 实时推流：生成进度、Token 消耗、当前阶段、错误信息全部通过 Server-Sent Events 实时推送到前端
- 检查点快照：阶段推进前自动存档，支持从任意检查点恢复
引擎暴露 20+ 独立提示接点，每个接点均可通过 prompt_packages/ 下的 YAML 配置文件独立覆写：
| 接点类型 | 包含接点 |
|---|---|
| 规划类 | planning-main-plot-suggest · planning-quick-macro |
| 生成类 | scene-director · chapter-narrative-sync |
| 知识类 | bible-all · bible-characters · bible-locations · bible-worldbuilding |
| 分析类 | style-analysis · tension-analysis-diagnosis |
每个提示包支持独立配置：系统提示、声线锚点、节拍约束、字数层级、记忆铁律、模型参数（temperature / top_p / max_tokens）。切换任务类型（短篇 / 长篇 / 游戏剧本）不需要修改代码，只需切换提示包目录。
引擎内置叙事质量的量化监控，不依赖人工逐章审阅：
- 张力心电图：每章生成后计算张力评分（0–10），历史曲线持久化，低谷自动触发诊断
- 文风相似度检测：基于向量余弦相似度计算当前章节与风格基准的偏离程度
- 漂移告警 + 定向修写：偏离超过阈值时，引擎不回滚章节，而是触发定向修写任务，保留已有进度
- 陈词滥调扫描：规则库 + 语义相似度双重检测，标记高频套路表达
PlotPilot 内核（本仓库）
│
├── 叙事状态机
├── 向量语义检索层
├── 剧情引擎运行时
├── 提示词策略层（20+ 接点）
└── 质量监控子系统
│
▼
REST API（FastAPI · v1 · 版本化）
│
┌───────┴──────────────────────┐
│ │
官方工作台前端 生态扩展层（基于内核）
Vue 3 · TypeScript ├── 垂直领域工具
Naive UI · ECharts │ （剧本/游戏剧情/IP 衍生……）
Tauri 桌面客户端 ├── 第三方前端 / 编辑器插件
├── 自定义提示词包
└── 云服务 / SaaS（需遵守许可证）
内核提供稳定的 REST API 边界；所有生态扩展均通过提示词包、工作流插件或上层应用的方式叠加能力，内核本身不感知。如果你在用内核做二创，建议从提示词包和工作流层开始，而非修改内核代码。
| 层 | 技术 | 选型理由 |
|---|---|---|
| 后端框架 | FastAPI + uvicorn | 原生异步 + 自动 OpenAPI 文档，SSE 支持开箱即用 |
| 架构范式 | DDD 分层 + 独立 engine/ 运行内核 |
领域逻辑、用例编排、生产写作管线与技术实现分离，生态扩展不污染内核 |
| AI 接入 | OpenAI 兼容协议 / Anthropic Claude / 火山方舟 Doubao | 统一接口抽象，模型切换不改业务代码 |
| 向量存储 | ChromaDB（默认）/ FAISS | 本地部署，零外部依赖，冷启动快 |
| 嵌入模型 | OpenAI 兼容 API / 本地 bge-small-zh-v1.5 |
在线轻量与离线高性能双模式 |
| 主数据库 | SQLite + Write Dispatch 单写者路由 | 嵌入式零依赖，并发写冲突由调度层解决 |
| 前端 | Vue 3 + TypeScript + Vite + Naive UI + ECharts | 组件类型安全，知识图谱与 DAG 可视化由 ECharts 驱动 |
| 桌面客户端 | Tauri（Rust） | 比 Electron 内存占用低 80%+，原生系统集成 |
- 将
python-3.14.5-embed-amd64.zip放入tools/目录（仅首次） - 双击
tools/plotpilot.bat
启动器自动完成：环境自检 → 创建虚拟环境 → 安装依赖（自动切换国内镜像源）→ 启动服务 → 打开浏览器。后续启动直接双击。
支持
tools\plotpilot.bat pack打包整个项目分享给他人，对方双击即用。当前启动器固定使用 Python 3.14 系列；如需使用系统 Python，可设置PLOTPILOT_PYTHON_EXE指向 Python 3.14 的python.exe。
前往 GitHub Releases 下载最新安装包，内含冻结后端，无需单独安装 Python。
构建流程见 docs/BUILD_INSTALLER.md。
环境要求：Python 3.14.x、Node.js 18+
# 后端 — Windows
py -3.14 -m venv .venv && .venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env # 填写 LLM 凭证
uvicorn interfaces.main:app --host 127.0.0.1 --port 8005 --reload# 后端 — Linux / macOS
python3.14 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn interfaces.main:app --host 127.0.0.1 --port 8005 --reload# 前端（另开终端）
cd frontend && npm install && npm run dev| 地址 | 说明 |
|---|---|
http://127.0.0.1:8005 |
后端 API |
http://127.0.0.1:8005/docs |
OpenAPI 交互文档 |
http://localhost:3000 |
前端开发服务器 |
生产构建后前端由 FastAPI 静态托管（frontend/dist），也可独立部署。
| 变量 | 说明 |
|---|---|
LLM_PROVIDER |
可选；指定默认 LLM 提供方 |
ANTHROPIC_API_KEY / ARK_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY |
至少配置一个 LLM 凭证 |
ARK_BASE_URL / ARK_MODEL、ANTHROPIC_BASE_URL / ANTHROPIC_MODEL、OPENAI_BASE_URL / OPENAI_MODEL、GEMINI_BASE_URL / GEMINI_MODEL |
对应提供方的接口地址与模型名 |
EMBEDDING_SERVICE |
openai（.env.example 默认）或 local（需额外安装模型，见 requirements-local.txt） |
EMBEDDING_API_KEY / EMBEDDING_BASE_URL / EMBEDDING_MODEL |
云端嵌入服务配置；EMBEDDING_API_KEY 为空时可回退读取 OPENAI_API_KEY |
EMBEDDING_MODEL_PATH / EMBEDDING_USE_GPU |
本地嵌入模型路径与 GPU 开关 |
VECTOR_STORE_ENABLED / VECTOR_STORE_TYPE / VECTOR_STORE_PATH |
向量索引开关、类型与持久化目录 |
CORS_ORIGINS |
生产环境前端域名，逗号分隔 |
DISABLE_AUTO_DAEMON |
设为 1 禁止启动时自动拉起守护进程 |
LOG_LEVEL / LOG_FILE |
日志级别与路径 |
完整说明见 .env.example。
（项目根目录）/
├── domain/ # 领域层 — 纯业务模型和值对象
│ ├── novel/ # 小说、章节、故事线、伏笔、因果、张力
│ ├── bible/ # 设定库、人物档案、地点、时间线
│ ├── character/ # 人物实体、人物状态、关系能力
│ ├── cast/ # 卡司与人物关系图
│ ├── knowledge/ # 知识三元组、故事知识图
│ ├── memory/ # 长期记忆与上下文状态
│ ├── prop/ # 道具生命周期与道具事件
│ ├── worldbuilding/ # 世界观领域模型
│ ├── structure/ # 故事结构节点
│ ├── evolution/ # 世界线 / 演化相关模型
│ ├── ai/ # AI 领域契约与值对象
│ └── shared/ # 共享基类、异常、事件、ID
│
├── application/ # 应用层 — 用例编排，协调领域、引擎与基础设施
│ ├── core/ # 小说 / 章节 / 导出等基础用例
│ ├── onboarding/ # 新书向导、前置设定生成
│ ├── blueprint/ # 宏观规划、连续规划、Beat Sheet、故事结构
│ ├── engine/ # 上下文构建、章后管线、治理预算、AI 调用编排
│ ├── governance/ # 叙事治理、质量约束、章节预算
│ ├── audit/ # 章节审阅、宏观重构、章节元素分析
│ ├── analyst/ # 文风、张力、伏笔账本、叙事状态分析
│ ├── world/ # Bible、知识图谱、世界观与人物关系服务
│ ├── ai/ # LLM / embedding 应用服务
│ ├── ai_invocation/ # AI 调用记录与审阅
│ ├── checkpoint/ # 检查点与快照用例
│ ├── memory/ # 记忆编排用例
│ ├── narrative/ # 叙事投影与状态同步
│ ├── narrative_engine/ # 叙事引擎应用服务
│ ├── manuscript/ # 正文实体索引与手稿服务
│ ├── prop/ # 道具应用服务
│ ├── reader/ # 读者模拟 / 阅读侧能力
│ ├── snapshot/ # 快照应用服务
│ ├── workbench/ # 工作台编排
│ └── workflows/ # 自动生成工作流、兼容编排与后台任务
│
├── engine/ # 剧情引擎内核 — 生产运行时、章节写作管线与题材扩展
│ ├── runtime/ # EngineDaemon、StoryPipelineRunner、守护进程委托、质量守门
│ ├── pipeline/ # BaseStoryPipeline 十步章节生成管线
│ ├── pipelines/ # 题材 Pipeline 注册与扩展（如武侠、通用题材桥接）
│ ├── core/ # 引擎侧实体、端口、服务契约
│ └── infrastructure/ # 引擎事件、记忆编排、checkpoint 适配
│
├── infrastructure/ # 基础设施层 — 技术实现，可替换
│ ├── ai/ # LLM Provider、Prompt Packages、向量存储、嵌入服务
│ ├── persistence/ # SQLite 仓储、迁移、Write Dispatch 单写者调度器
│ ├── export/ # DOCX / EPUB / PDF 导出
│ └── runtime/ # 数据目录、日志环境与进程级运行配置
│
├── interfaces/ # 接口层 — FastAPI、依赖注入、运行状态与外部边界
│ ├── main.py # FastAPI 应用入口
│ ├── daemon_manager.py # 后端内自动驾驶进程管理
│ └── api/v1/ # REST API（core / world / blueprint / engine / audit / analyst 等）
│
├── frontend/ # 官方工作台 — Vue 3 + TypeScript + Tauri 桌面壳
│ ├── src/ # 工作台、自动驾驶、知识图谱、设置、API client
│ └── src-tauri/ # Tauri 桌面客户端与后端 sidecar
│
├── shared/ # 跨端共享配置与分类体系资源
├── config/ # 本地配置与默认配置
├── scripts/ # 启动、安装、迁移、评估与维护脚本
├── tests/ # 单元、集成、E2E 与 DAG 测试
└── tools/ # Windows 启动器与内嵌 Python 包
完整设计与分层说明见 docs/ARCHITECTURE.md。
pytest tests/ -v
# 含覆盖率报告
pytest tests/ --cov=. --cov-report=term-missing- Fork 本仓库
- 新建分支：
git checkout -b feat/your-feature - 提交信息建议遵循 Conventional Commits
- 推送并发起 Pull Request
架构与分层说明见 docs/ARCHITECTURE.md；其余文档索引见 docs/README.md。
请不要提交以下内容：
.env、API Key、模型网关地址中的私有凭证data/、logs/、SQLite 数据库、向量库、运行时缓存- Word / PPT / Excel 等办公文档（如
.docx、.pptx、.xlsx），尤其是未公开设定、商业计划、合同、客户资料 - 打包产物、安装包、Tauri / PyInstaller 输出目录
如果必须提交示例资料，请放入脱敏后的 Markdown / JSON / YAML，并确认不包含真实密钥、真实用户数据或未公开作品内容。
引擎在持续演进，我们也在寻找对叙事工程感兴趣的同行。
当前关注方向：内核引擎研发、生态应用构建、提示词工程、前端工作台
如果你对"用工程化手段解决创作问题"这件事感兴趣，欢迎来直播间转一圈，大概就能判断这个项目的调性：
- 抖音：搜索直播间 91472902104（每晚约 21:00 随缘开播）
- 联系方式：直播间私信附简历即可
本项目采用 Apache License 2.0，并附加 Commons Clause 条件限制。
- 允许：学习、修改、非商业内部部署、基于内核的生态扩展（非营利）
- 禁止：将本项目（含修改版）封装为收费 SaaS、打包售卖源码或作为收费产品的增值服务
详见 LICENSE。