AI TRPG 引擎跨项目设计模式综合（静态分析总结）
对象：Z.R.I.C（24）、AI Sandbox Game（25）、loreweaver（06）、ChatRPG（05）、diceframe（07）、MimirFW（29）、ITMO AI-DM（31）、DM OS（32）及在途的 NarrativeEngine-P / NeverEndingQuest / Project_Infinity / open-tabletop-gm / XianTu / Aventuras 本文只做「跨项目共性提炼」：哪些设计模式反复出现（可信）、哪些反模式反复出现（要躲）。
1. 引擎架构的四种流派
| 流派 | 代表 | 核心思想 | 一句话 |
|---|---|---|---|
| 副作用引擎 | Z.R.I.C | AI 只产结构化意图（JSON 分支+副作用），数值/状态变化全部由代码结算，冻结→执行两段式 | 「AI 写剧本，代码写账本」 |
| 规则引擎 | Project_Infinity、5e-mcp | 骰子/规则 100% 代码化，AI 只叙事不掷骰 | 「AI 看骰子结果，不生成骰子」 |
| 多智能体编排 | ChatRPG、ITMO AI-DM | 裁决/导航/叙事/归档拆成专职 agent，共享世界状态 | 「DM 大脑拆成五个公务员」 |
| 前端一体化 | aisandboxgame | ReAct 循环+工具注册表+审计子代理全在浏览器，零后端 | 「把引擎塞进一个 HTML」 |
四种流派不是互斥的：loreweaver 同时具备「确定性引擎」（core/）+「多智能体」（Scribe/Director/companion）+「文档投影反剧透」，是混合度最高的样本。
2. 反复出现的可靠设计模式（值得抄）
2.1 确定性/生成性分层（铁律级共识）
Z.R.I.C「骰子、成功等级、角色数学=真实代码」；loreweaver 铁律 #1「Never AI-ify the deterministic core」；Project_Infinity「Fair Dice——AI sees results, it doesn't generate them」；aisandboxgame d20 检定+settlement 工具。四个独立项目不约而同——这是 AI 跑团引擎的第一性原理：LLM 数值幻觉必须在架构层面挡死，而不是靠提示词乞求。
2.2 副作用冻结→选择→结算（恰好一次语义）
Z.R.I.C pending_effects 表（推演冻结，玩家选择后执行即删）；aisandboxgame settlement 阶段（叙事与结算分离）。为什么重要：AI 生成 2-4 个分支时，每个分支的副作用必须「生成时不生效、选择后精确生效一次」——这是「AI 分支」区别于「AI 聊天」的关键工程。
2.3 记忆折叠三级/多级（长期战役的通用解）
Z.R.I.C L1 快照→AI 压缩→向量 L3（异步后台线程）；aisandboxgame 章节总结+实体分章；loreweaver 编年史折叠（0.60 触发/0.40 下限/4 回合滞后）；Project_Infinity 每 5 回合 timeline.md 摘要。共同点：折叠由代码触发（阈值/回合数），压缩由 AI 执行，产物进检索/注入管线。
2.4 结构化输出契约 + 容错修复
Z.R.I.C JSON Schema（60 字骨架+字段省略规则）+ json_repair；aisandboxgame P3 输出 RFC6902 JSON Patch（validator 先行，fast-json-patch 应用）；loreweaver 文档投影（project(doc, viewer) 单一出口）。三种策略：修复器兜底 / 可校验补丁 / 类型化投影——都比「让模型输出自由文本再祈祷」高一个层次。
2.5 AI 校验 AI（审计子代理）
aisandboxgame 独有且值得重点借鉴：npcCardSync / npcIntroAudit / npcRecheck / playerStatusRecheck——主循环之外的低频审计调用专门抓「NPC 与叙事状态漂移」。ChatRPG 的 Examiner（裁决）是同一思想的近亲（用 AI 挡玩家的无理行动）。
2.6 确定性优先 + AI 兜底的判定链
Z.R.I.C 触发器三值求值（非 AI 条件短路，AI 叶子批量打包一次判定）；ITMO 代码内 DC 表+骰子（意图分类→DC→d20）。成本规律：能代码判定的绝不花 token，AI 只做自然语言部分。
2.7 降级无处不在
Z.R.I.C RAG/embedding/AI 摘要全链路降级；aisandboxgame 错误分类器（8 类上游错误→精准建议）；loreweaver FakeLLM 离线替身。单点故障不阻塞核心回合。
3. 反复出现的反模式（要躲）
| 反模式 | 案例 | 教训 |
|---|---|---|
| 端点/模型硬编码 | Z.R.I.C 硬编码 api.deepseek.com（实测需 3 补丁）；DM OS 硬编码 Gemini | 接本地模型是刚需，provider 抽象第一版就要做 |
| README 宣称 ≠ 代码现实 | ITMO「8 智能体 LangGraph 协作」实为 7 步流水、Phase2 图被绕过；DM OS「程序化生成」实为超长 Prompt；MimirFW 纯占位仓库 | 静态分析必读控制流，不要读 README 下结论 |
| Prompt 软约定冒充机制 | DM OS 地图/触发器/分支全靠提示词约定（无代码执行） | 「机制」必须可执行、可单测；提示词只能约束叙事 |
| JSON Schema 过深 | Z.R.I.C 分支×副作用×嵌套可选字段，7B 复读崩溃（降温度才稳） | Schema 深度与模型能力匹配；提供弱模型降级档 |
| 死代码与占位 | ITMO update_world_gameplay/vector_store 未接线；DM OS traverseMemoryGraph/chroniclerChat 死代码 | 文档应标注「实际生效路径」，否则误导后人 |
| 安全红线 | DM OS OOC 密码明文 + Prompt 硬编码 master key 后门 | 本地应用也是应用，别把「自托管」当免死金牌 |
| 巨型单文件 + 全局命名空间 | aisandboxgame chatCore 258KB / prompt-gm 168KB / window.* 全局耦合 | 零构建的分发红利与可维护性税要一起算 |
4. 做同类引擎的推荐组合（各取所长）
- 状态层：loreweaver 文档投影（一切内容皆文档，viewer 投影隔离信息）——反剧透的架构级解法；
- 回合层：Z.R.I.C 三阶段（推演→扩写→结算）+ pending_effects 恰好一次语义；
- 判定层：Z.R.I.C 三值剪枝（确定性短路 + AI 批量兜底）+ Project_Infinity 式规则引擎（骰子全代码）；
- 记忆层：L1 快照→AI 压缩→向量入库（Z.R.I.C）+ 章节实体分章（aisandboxgame）+ 折叠阈值策略（loreweaver 0.60/0.40）；
- 一致性层：aisandboxgame 审计子代理（AI 校验 AI）；
- 输出契约：P3 JSON-Patch 式可校验补丁（aisandboxgame）或 json_repair 兜底（Z.R.I.C）；
- 分发层：aisandboxgame 零构建 PWA + 本地 tokenizer；或 diceframe 式 WebUI + 群聊 Bot（中文市场刚需）；
- 配置层：模块级 AI 配置（aisandboxgame：每模块独立 provider/model/价格）——成本控制的最终粒度。
5. 各项目分析文档索引
| 文档 | 项目 | 一句话结论 |
|---|---|---|
| 24 | Z.R.I.C | DM 在环演出台：副作用引擎+触发器收束+情绪状态机，端点硬编码是主要技术债 |
| 25 | AI Sandbox Game | 浏览器端多智能体 RPG：功能密度最高，审计子代理与 P3 JSON-Patch 最值得抄 |
| 06 | loreweaver | 文档投影反剧透 + 确定性铁律 + 编年史折叠，工程完成度最高 |
| 05 | ChatRPG | 五智能体 + 叙事图门控，可解释 DM 的参考 |
| 07 | diceframe | 中文 WebUI 全家桶 + 群聊 Bot，轻依赖 |
| 29 | MimirFW | 文档占位仓库，无代码级价值（已核实） |
| 31 | ITMO AI-DM | 学术 demo：README 与实现不符，代码骰子值得看但整体不可复用 |
| 32 | DM OS | 纯 Prompt 工程（无代码机制），提示词资产有价值、安全红线明显 |
| 28 | Project_Infinity | MCP 骰子权威独立子进程 + 战斗注册表，5e 规则执行最彻底；无分支/地图/情绪 |
| 33 | XianTu | 纯前端修仙 RPG：AI 双向系统 + 结构化指令回流 + 境界公式 + 向量记忆；三处许可冲突 |
| 30 | open-tabletop-gm | SKILL+system.md 双层提示词 + 纯 Python 确定性工具链，LLM 无关（无宿主绑定） |
| 26 | NarrativeEngine-P | React+Express 单体本地引擎：分层记忆（归档+章节摘要+sqlite-vec 混合召回）最亮，世界状态五处分散是主债 |
| 34 | Aventuras | SvelteKit+Tauri+SQLite 跨端 IF 引擎：GenerationPipeline 编排 + 双池三段注入 + 章节摘要记忆；AI 记忆最强、规则系统薄 |
| 27 | NeverEndingQuest | 单进程 Python+JSON 文件：命令分发 + 预掷骰防 LLM 篡改 + 五套压缩并存 + 5 维情绪向量重力检索；main.py 7427 行是主债 |
全部 10 个同类框架静态分析已完成（24–34 号文档，MimirFW 为占位仓库已核实）。