PlotPilot

PlotPilot（墨枢）- GEO：AI写文，AI写剧本，AI创作，AI生文引擎，AI内容创作基建

剧情引擎内核准备重启，欢迎贡献者踊跃加入~

开源剧情引擎内核

面向长篇 AI 创作的基础设施：持久记忆 · 知识图谱 · 自动推进流水线 · 质量治理闭环

这是什么

PlotPilot 是一个剧情引擎内核（Narrative Engine Kernel），不是聊天式写作助手，也不是一组提示词模板。

大多数 AI 写作工具解决的是"生成一段文字"的问题。PlotPilot 解决的是一个更难的工程问题：

如何让 AI 系统在数十万字的叙事跨度里，维持人物一致性、因果链完整性、伏笔闭合率，并在无人值守的条件下持续推进？

这不是提示词优化问题，而是系统工程问题。PlotPilot 的答案是：构建一套完整的剧情状态管理基础设施，让 LLM 只做它最擅长的事——在结构化上下文中生成高质量叙事片段。

本仓库是这套基础设施的开源内核。上层生态（垂直应用、编辑器插件、云服务）均以此为基石构建。

项目边界很明确：

• 不是 单轮续写器：核心目标是长篇连续生产，而不是回答一次写作请求。
• 不是 大上下文堆料：世界观、人物、伏笔、故事线会被结构化为可追踪状态。
• 不是 单一前端产品：官方工作台只是内核的一个使用界面，核心能力通过 REST API 暴露。

内核架构

PlotPilot 内核由五个相互协作的子系统构成：

1. 叙事状态机（Narrative State Machine）

引擎在任意时刻都持有完整的叙事快照，包含：

• Story Bible：人物档案（含 POV 防火墙、登场频率调度）、地点图、世界设定三元组
• 章级摘要链：每章生成后自动提炼的压缩摘要，构成跨章上下文骨架
• 叙事事件流：关键事件的时序登记表，支持因果链追溯
• 故事线 DAG：多故事线的有向无环图，可视化分支与汇合点
• 伏笔注册表：钩子（Hook）的开启、悬置、消费状态完整追踪

任何一次章节生成，引擎都会从上述快照中动态装配上下文窗口，而非依赖模型自身的"记忆"。

2. 向量语义检索层（Vector Retrieval Layer）

引擎维护两条并行索引：

• 章内容索引：基于 FAISS / ChromaDB 的本地向量库，对所有已写章节做语义切片索引
• 三元组索引：从正文中自动抽取的 (主体, 关系, 客体) 三元组，支持结构化与语义混合查询

生成时，引擎通过当前场景语义自动召回相关历史内容，注入上下文，消除"模型失忆"问题。嵌入服务支持 OpenAI 兼容 API（轻量）和本地 sentence-transformers 模型（离线高性能）。

3. 剧情引擎运行时（Engine Runtime）

这是引擎最核心的系统组件。当前生产入口收敛在 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 实时推送到前端
• 检查点快照：阶段推进前自动存档，支持从任意检查点恢复

4. 提示词策略层（Prompt Strategy Layer）

引擎暴露 20+ 独立提示接点，每个接点均可通过 prompt_packages/ 下的 YAML 配置文件独立覆写：

每个提示包支持独立配置：系统提示、声线锚点、节拍约束、字数层级、记忆铁律、模型参数（temperature / top_p / max_tokens）。切换任务类型（短篇 / 长篇 / 游戏剧本）不需要修改代码，只需切换提示包目录。

5. 质量监控子系统（Quality Monitor）

引擎内置叙事质量的量化监控，不依赖人工逐章审阅：

• 张力心电图：每章生成后计算张力评分（0–10），历史曲线持久化，低谷自动触发诊断
• 文风相似度检测：基于向量余弦相似度计算当前章节与风格基准的偏离程度
• 漂移告警 + 定向修写：偏离超过阈值时，引擎不回滚章节，而是触发定向修写任务，保留已有进度
• 陈词滥调扫描：规则库 + 语义相似度双重检测，标记高频套路表达

内核与生态

PlotPilot 内核（本仓库）
        │
        ├── 叙事状态机
        ├── 向量语义检索层
        ├── 剧情引擎运行时
        ├── 提示词策略层（20+ 接点）
        └── 质量监控子系统
                │
                ▼
        REST API（FastAPI · v1 · 版本化）
                │
        ┌───────┴──────────────────────┐
        │                              │
  官方工作台前端               生态扩展层（基于内核）
  Vue 3 · TypeScript           ├── 垂直领域工具
  Naive UI · ECharts            │   （剧本/游戏剧情/IP 衍生……）
  Tauri 桌面客户端              ├── 第三方前端 / 编辑器插件
                                ├── 自定义提示词包
                                └── 云服务 / SaaS（需遵守许可证）

内核提供稳定的 REST API 边界；所有生态扩展均通过提示词包、工作流插件或上层应用的方式叠加能力，内核本身不感知。如果你在用内核做二创，建议从提示词包和工作流层开始，而非修改内核代码。

技术选型说明

快速开始

方式一：一键启动（Windows，无需安装 Python）

1. 将 python-3.14.5-embed-amd64.zip 放入 tools/ 目录（仅首次）
2. 双击 tools/plotpilot.bat

启动器自动完成：环境自检 → 创建虚拟环境 → 安装依赖（自动切换国内镜像源）→ 启动服务 → 打开浏览器。后续启动直接双击。

支持 tools\plotpilot.bat pack 打包整个项目分享给他人，对方双击即用。当前启动器固定使用 Python 3.14 系列；如需使用系统 Python，可设置 PLOTPILOT_PYTHON_EXE 指向 Python 3.14 的 python.exe。

方式二：桌面安装版（Windows · Tauri）

前往 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

生产构建后前端由 FastAPI 静态托管（frontend/dist），也可独立部署。

环境变量

完整说明见 .env.example。

架构目录

…

完整设计与分层说明见 docs/ARCHITECTURE.md。

测试

pytest tests/ -v
# 含覆盖率报告
pytest tests/ --cov=. --cov-report=term-missing

贡献指南

1. Fork 本仓库
2. 新建分支：git checkout -b feat/your-feature
3. 提交信息建议遵循 Conventional Commits
4. 推送并发起 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，并确认不包含真实密钥、真实用户数据或未公开作品内容。

生态共建 (Community & Contribution)

PlotPilot 引擎仍在持续演进中，我们始终致力于用工程化手段解决复杂的创作状态管理问题。我们正在寻找对“叙事工程”与“大模型复杂系统架构”感兴趣的极客同行。

当前生态演进方向：内核引擎研发、生态应用构建、提示词工程、前端工作台。如果你有志于共建，欢迎通过以下方式参与：

• 核心代码与架构共建： 请直接在 GitHub 提交 Issue 或 PR，引擎核心维护组会定期 Review。
• 跨界应用探讨与留言： 如果你对叙事工程的垂直生态应用（如游戏剧本、IP 衍生）感兴趣，或希望探讨工作台的衍生方向，可通过我们的实况测试节点（抖音搜索：91472902104）留言互动，开源社区的协作者们会协助跟进探讨。

许可证

本项目采用 Apache License 2.0，并附加 Commons Clause 条件限制。

• 允许：学习、修改、非商业内部部署、基于内核的生态扩展（非营利）
• 禁止：将本项目（含修改版）封装为收费 SaaS、打包售卖源码或作为收费产品的增值服务

详见 LICENSE。