Z.R.I.C（零界核心）
一句话定位：DM 在环的半自动文字冒险推演模拟器——AI 实时生成多分支剧情 + 自动管理 NPC 情绪 + 语义检索规则裁判 + 场景生图投屏；「人构造规则与世界观，AI 承接自由行动推演分支，触发器收束叙事」。 类型：AI TRPG 引擎（DM 在环演出台）· 开源 · 许可：GPL-3.0 · 仓库：zRICGao/ZRIC-AI-TRPG-Engine · 状态：早期 Demo
1. 项目概述
Z.R.I.C = Zero-boundary Roleplay Intelligence Core（零界核心）。作者的目标是摆脱传统电脑游戏的有限分支：人负责构造基本规则和主世界观（背景故事、主要人物、主线、地图），AI 承接玩家的自由行动推演剧情走向。它与纯聊天式 AI 跑团的本质区别在于「副作用引擎」——AI 生成的每个分支都携带结构化副作用（HP/SAN 变化、物品得失、地图移动、新 NPC、情绪位移、NPC 记忆），选择分支后由引擎自动结算。
2. 核心功能（12 项）
- 剧本加载：
campaign.json+knowledge/*.txt（RAG 知识库：世界观/规则/章节文本）；内置示例剧本《盘步山规则怪谈》《苏黎世恋曲》《利马特-禁忌之河》《光与夜》。 - AI 推演分支：玩家行动 → AI 生成分支（含 60 字场景骨架 + 副作用），支持流式 SSE；
json_repair容错。 - 世界实体：NPC/物品/组织档案，AI 自动提取与更新（
entity.py）。 - NPC 情绪状态机：信任/恐惧/烦躁三轴 + 断点反应；NPC 随剧情产生记忆、改变态度。
- NPC Persona：MBTI 性格 + 怪癖 + 独立记忆，模型扮演实时对话（
phone.html短信界面）。 - 三级记忆：L1 短期工作区（最近 8 次推演）→ L2 实体档案 → L3 向量长期记忆，自动折叠不丢失。
- RAG 规则裁判：推演时语义检索知识库（BGE-M3 embedding）注入 prompt。
- 空间地图：房间/通道拓扑、位置感知、自动生长新地点（
map.py）。 - 触发器系统：scene/item/stat/ai 四种条件；hard 强制跳转 + soft 提示——收束时间线的关键。
- 多时间线：分支平行推演、独立记忆、可合并（
timeline.py）。 - 演出层：深入调查（场景 AI 扩写）、场景生图（Kolors 免费/豆包付费）、BGM、WebSocket 投屏到玩家大屏。
- 存档：完整存档含向量索引，加载即用。
3. 技术架构
- 后端：FastAPI + SQLite（WAL）+ 8 个业务模块（main 编排 / agent 推演核心 / trigger 触发器 / rag 向量库 / entity 世界实体 / memory 三级记忆 / map 空间地图 / timeline 多时间线）。
- 前端：Vue 3 + Tailwind（CDN 零构建）——
index.html（GM 控制台 4250 行）+player.html（投屏端）+phone.html（NPC 短信）。 - AI：DeepSeek Chat / Claude Opus 4.6（OpenAI 兼容协议，一键切换 + 请求级回退）；Embedding 用硅基流动 BGE-M3；生图双源。
- 通信：REST + SSE 流式 + WebSocket 投屏。
- 关键端点：
/api/game/load（加载剧本）→/api/ai/dynamic-options[/stream]（推演分支）→/api/ai/expand-branch/stream（润色扩写）→/api/ai/apply-branch-effects（副作用结算）→/api/game/check-triggers（触发器判定）。
4. 本机实测记录（✅ 完整运行，本地 7B）
- 环境：Python 3.11 + uv；依赖 7 个包 + 补装
python-multipart（上游 requirements 遗漏，启动即崩）。 - 补丁（3 处，均标注 [PATCH]）：
main.py×2：DeepSeekbase_url改为读DEEPSEEK_BASE_URL环境变量（原版硬编码 api.deepseek.com）；main.py：端口 8000 → 8010（避开本机 SillyTavern）；agent.py：推演温度 0.8 → 0.3（本地小模型结构化输出可靠性）；_post_process_dynamic_result增加「单元素列表解包」兼容（本地模型爱输出[{...}]）。
- 实测链路（KoboldCpp + Qwen2.5-7B 全本地）：
- 加载《盘步山规则怪谈》→ 17 个场景节点 + 地图；
- 推演①「向售票亭工作人员打听失踪」→ 3.7 秒返回分支「询问售票员」：骨架『工作人员表情冷漠，低声回答：没有，这里一切正常』+ 思考过程 5 步（含 HP/SAN 检查、规则合规、信息可信度判断）+ NPC 情绪位移（fear+20）+ NPC 记忆；
- 推演②「翻围栏夜闯后山」→ 分支「后山密林」：『密林中沙沙作响，夜色中隐约可见树木移动』——规则怪谈氛围到位；
/api/game/check-triggers→ 触发器机制正常响应。
- 局限：RAG 需要硅基流动 key（本地未启用，向量库为空加载正常）；7B 偶发 JSON 尾部复读（json_repair + 低温已基本解决）；生图/投屏需浏览器交互。
- 使用：浏览器打开
http://127.0.0.1:8010（GM 控制台），选剧本 → 加载 → 右侧输入玩家行动 → 推演。
5. 如何运行（复现）
git clone https://github.com/zRICGao/ZRIC-AI-TRPG-Engine.git && cd ZRIC-AI-TRPG-Engine
python -m venv .venv && .venv\Scripts\pip install -r requirements.txt python-multipart
cp .env.example .env # DEEPSEEK_API_KEY 必填；本机接 KoboldCpp 需补丁 DEEPSEEK_BASE_URL
python main.py # http://127.0.0.1:8000（或 8010 补丁版）
6. 优劣势分析
| 优势 | 劣势 |
|---|---|
| 「分支+副作用」结构化推演，超越纯对话式 AI 跑团 | 早期 Demo：API 变动快、文档少 |
| 触发器 + 多时间线是开源侧稀缺设计 | 本地模型需 3 处补丁（已给出） |
| 演出层完整（投屏/生图/BGM/短信界面） | RAG 强依赖硅基流动（商业 API） |
| Vue CDN 零构建，前端开箱即用 | GPL-3.0；单人 DM 在环为主 |
7. 同类框架与对比
见 docs/projects/22-zric-similar-frameworks.md（功能矩阵：NarrativeEngine-P、NeverEndingQuest、Project_Infinity、aisandboxgame、loreweaver、ChatRPG、diceframe 等）。
8. 参考链接
- 仓库：https://github.com/zRICGao/ZRIC-AI-TRPG-Engine
- 同类开源：
docs/projects/21-engine-catalog.md（170 GM 类 + 124 引擎类全清单） - 商业对照：RPGGO（无代码 RPG 制作器）、AI Roguelite（Steam）、Wanderfolk