🎲 AI TRPG 引擎调研

仙途 XianTu 静态分析：模块设计与工作原理

对象：qianye60/XianTu · 方法：纯静态分析

1. 总体架构

XianTu 是纯前端的 AI 驱动修仙文字冒险游戏（Vue 3 + TypeScript + Pinia + Webpack），无内置后端也可运行；可选 Python/FastAPI 后端仅用于账号/存档云同步。核心思想：AI 作为「天道」GM 实时生成叙事，并以结构化 JSON 指令（tavern_commands）反向驱动游戏状态，前端负责状态机、判定、存档与渲染。

┌──────────────────────────── 浏览器 ─────────────────────────────┐
│  Vue 3 组件层 (dashboard/*.vue, character-creation/*.vue)        │
│        │ 渲染/事件                                               │
│  Pinia Store 层                                                  │
│   ├ gameStateStore.ts   (游戏状态 / toSaveData / loadFromSaveData)│
│   ├ characterStore.ts   (角色+多存档 / IndexedDB 持久化)          │
│   ├ actionQueueStore.ts (动作队列)  apiManagementStore.ts(多API)  │
│   └ uiStore.ts (UI/流式)  characterCreationStore.ts (创角)        │
│        │ 编排                                                     │
│  AIBidirectionalSystem.ts  (核心双向系统：拼Prompt→调AI→解析→执行) │
│        │ 组装                                                     │
│  promptAssembler.ts + prompts/definitions/* (规则/数据定义提示词)   │
│        │ 检索(可选)                                               │
│  vectorMemoryService.ts(长期记忆向量) narrativeRagService.ts(叙事) │
│        │ 调用                                                     │
│  aiService.ts (统一AI层：TavernHelper 或 自定义API axios)          │
│        ▼                                                          │
│  SillyTavern 内嵌 / OpenAI 兼容(OpenAI/Claude/Gemini/DeepSeek...) │
└──────────────────────────────────────────────────────────────────┘
        ▼ 持久化(IndexedDB via idb)            ▼ 可选云端
  indexedDBManager.ts (乾坤宝库)          services/api/* (FastAPI/JWT)

技术栈见 package.json:25-73（vue/pinia/idb/axios/pixi.js/chart.js 等）；入口 src/main.ts，路由 src/router/index.ts。

2. 核心工作流（最重要链路）

链路 A：玩家选择 → 剧情节点解析 → LLM 生成/检索 → 状态更新 → 渲染

  1. 玩家输入：MainGamePanel.vue:1433 sendMessage() 读取输入框 + 动作队列文本，包成 <行动趋向> 标签，调用 bidirectionalSystem.processPlayerAction()（MainGamePanel.vue:1571）。
  2. 取档与快照：AIBidirectionalSystem.ts:434 processPlayerAction 先 gameStateStore.toSaveData() 拿 V3 存档（gameStateStore.ts:469），并做「上次对话」快照用于回滚（AIBidirectionalSystem.ts:467-474）。
  3. 检索（可选）：向量检索长期记忆 vectorMemoryService（AIBidirectionalSystem.ts:509-538）与叙事 RAG narrativeRagService（:540-559），把 TopK 相关片段注入提示词，替代全量长期记忆以省 token。
  4. 前端判定数据：计算「幸运点/气运值/环境修正」等，写入 coreStatusSummary（AIBidirectionalSystem.ts:582-657），要求 AI 直接使用而不自行计算。
  5. 拼 Prompt：assembleSystemPrompt（promptAssembler.ts:17）按模块拼接核心规则/业务规则/数据结构定义/世界观等，再叠加完整存档 JSON（stateJsonString）。
  6. 调 LLM：aiService.generate()（aiService.ts:536），酒馆走 TavernHelper，网页走自定义 API；支持「分步生成」（先正文后指令，AIBidirectionalSystem.ts:944-1126）。
  7. 解析响应：parseAIResponse（AIBidirectionalSystem.ts:3447）把 AI 返回 JSON 解析为 GM_Response{ text, mid_term_memory, tavern_commands[], action_options[] }，含多层容错（:1154-1230）。
  8. 执行指令：processGmResponse（:1768）→ _preprocessCommands 纠错（:2541）→ 校验（commandValidator/commandValueValidator）→ executeCommand 执行 set/add/push/delete/pull（:3009）→ 事后 validateSaveDataV3 结构校验、必要时回滚（:2139-2187）。
  9. 回写与渲染：gameStateStore.loadFromSaveData() 刷新 Pinia（:2250-2253），saveAfterConversation() 落盘（gameStateStore.ts:740），UI 响应式重渲染；流式文本通过 onStreamChunk 实时显示。

链路 B：记忆三级沉降（短期→隐式中期→中期→长期）：processGmResponse 把 text 写入短期记忆并超限转移（AIBidirectionalSystem.ts:1836-1914）；中期达阈值时异步 triggerMemorySummary（:2276）调 AI 总结压入长期记忆，并同步向量索引。

3. 模块逐一分析

3.1 状态 Store

3.2 LLM 调用层

3.3 剧情/提示词组织

3.4 存档

3.5 记忆系统

3.6 世界/事件/地图

3.7 宗门 / 炼器 / 三千大道 / 联机

4. 数据模型（关键结构）

5. 修仙数值体系建模（重点）

境界为离散层级 × 子阶段的数值框架：境界.名称(9 级) + 境界.阶段(5 档) + 当前进度/下一级所需。突破进度由 AI 通过 add 角色.属性.境界.当前进度 指令推进（executeCommand 的 add 分支，AIBidirectionalSystem.ts:3176），前端不做硬性等级约束，主要靠提示词约束 + 事后校验。

修炼速度有纯前端公式：cultivationSpeedCalculator.ts:338 最终速度 = 基础速度 × 灵气系数 × 六司综合系数 × 状态系数 × (1+功法加成+环境加成)；六司系数=先天×0.7+(1+后天)×0.3（:176）；REALM_BREAKTHROUGH_STANDARDS（:68）给出各境界阶段最短/标准/最长突破月数，用于预估突破时间与进度合理性校验。

判定（战斗/修炼/探索）由前端算好「判定数据」交给 AI：AIBidirectionalSystem.ts:620-657 基于气运算幸运点、基于位置灵气浓度算环境修正，AI 只需按给定值写叙事结论；另有 diceRoller.ts（d20/多骰/calculateFinalValue）与 attributeCalculation.ts（装备/天赋加成合成后天六司）。

6. 与 Z.R.I.C 的功能对照表

维度 XianTu 实现情况 依据
剧本解析 无预设剧本树；用 parseAIResponse 解析 AI 结构化 JSON（正文+指令），视为「动态剧本」 AIBidirectionalSystem.ts:3447
推演分支 无固定分支树；分支=玩家输入+AI 自由叙事+随机事件+action_options 引导 AIBidirectionalSystem.ts:1180-1228
自动判定 ✅ 前端计算幸运点/环境修正等判定数据交 AI 使用；d20 骰子、修炼速度公式 AIBidirectionalSystem.ts:636-657、diceRoller.ts:10
世界状态 ✅ WorldInfo（大陆/势力/地点/经济/区域地图），AI 生成 + 存档持久 game.d.ts:793、enhancedWorldGenerator.ts:78
NPC情绪记忆 ✅ NPC 有 当前内心想法/当前外貌状态/记忆/好感度/人格底线；buildFocusedNpcPrompt 每回合更新「实时关注」NPC game.d.ts:986-1056、AIBidirectionalSystem.ts:143
地图 ✅ 世界坐标 + 区域地图(regionId/buildingId) + 境界地图集，gameMapManager gameStateStore.ts:957-1003
触发器 ✅ 事件系统按游戏时间触发随机事件/特殊 NPC；状态效果(StatusEffect) AIBidirectionalSystem.ts:170、game.d.ts:600
时间线 ✅ GameTime 年月日时分 + advanceGameTime + 事件按年推进 gameStateStore.ts:654、game.d.ts:1070
记忆系统 ✅ 短期/中期/长期三层 + 自动总结 + 向量检索 + 叙事 RAG game.d.ts:1061、vectorMemoryService.ts、narrativeRagService.ts
本地模型 ⚠️ 无显式 Ollama/LM Studio 支持；custom(OpenAI 兼容) provider 可指向本地端点；embedding 仍需云端 API aiService.ts:52、grep 未见 ollama/llama
许可 ⚠️ LICENSE 为自定义「个人/非商用免费，商用联系作者」，与 package.json 声明 Apache-2.0、文件头 CC BY-NC-SA 4.0 不一致 LICENSE:1-18、package.json:7、gameStateStore.ts:4

7. 设计评价

优点

  1. 「AI 出指令、前端执行+校验」的架构边界清晰：AI 只输出 JSON 指令，前端 executeCommand 有严格动作集、路径白名单、只读保护、事后结构校验与回滚，把 AI 的不可靠性隔离在可控沙箱内（AIBidirectionalSystem.ts:1945-2187）。
  2. 成熟的容错/纠错体系：指令预处理把旧格式/整体覆盖/数组 push 等 AI 常见错误自动改写（:2541-3007），响应解析多层降级（:1154-1230），数据修复（dataRepair.ts）+ 存档迁移（saveMigration.ts）保证旧档兼容。
  3. 可扩展的多 API + 可插拔提示词：按功能类型分配不同 API（apiManagementStore.ts:25），提示词模块化且支持用户自定义（promptAssembler.ts、promptStorage.ts），能针对不同任务（正文/指令/记忆/事件/embedding）用不同模型。
  4. 记忆分层 + 向量/RAG 检索：三层记忆沉降 + 长期记忆向量检索 + 叙事 RAG，缓解长上下文 token 压力（AIBidirectionalSystem.ts:509-559）。
  5. 数值体系相对自洽：境界/六司/修炼速度/突破时间/判定数据有明确公式与标准表（cultivationSpeedCalculator.ts、realms.ts）。

缺陷

  1. 大量 any 与中文 key 直接访问：核心状态大量 as any/(saveData as any)?.角色?.属性...（如 gameStateStore.ts:277-428、AIBidirectionalSystem.ts:565-690），类型安全形同虚设，重构/迁移易出错。
  2. 核心类职责过重：AIBidirectionalSystem.ts 达 3510 行，混合了 prompt 构建、世界事件调度、响应解析、指令执行、记忆总结、联机逻辑，可维护性差。
  3. 冗余/重复文件：如 services/ 与 services/prompts/、services/initialization/ 存在疑似重复（defaultPrompts.ts、promptConfig.ts、promptStorage.ts、characterInitialization.ts 各两份），存在死代码/迁移残留风险（见 glob 列表）。
  4. 本地模型支持缺失：embedding 仅支持 DashScope/SiliconFlow/OpenAI 兼容云端，未提供本地 embedding/推理的完整方案；对纯离线玩家门槛高。
  5. 许可与声明冲突：LICENSE（个人/非商用）、package.json（Apache-2.0）、文件头（CC BY-NC-SA 4.0）三处不一致，商用边界不清晰（LICENSE:5-18）。

8. 结论

XianTu 是一款架构思路较成熟的「AI 作为动态 GM」的修仙文字冒险：用提示词 + 完整 JSON 状态注入驱动 AI 生成叙事，再用受控的 tavern_commands 指令沙箱把 AI 输出回流为确定性状态变更，辅以三层记忆、向量/RAG 检索、世界事件、宗门/炼器/三千大道等丰富子系统，形成了「实时生成 + 预设数据」混合的剧情体系。其修仙数值（境界/六司/修炼速度/判定）以前端公式 + 标准表 + AI 叙事包装实现，而非硬性战斗引擎。主要短板在工程层面：类型安全弱、核心类过重、文件冗余、许可声明不一致，以及缺少显式本地模型方案（仅能经 OpenAI 兼容 custom 端点间接使用）。总体看，它是一个「玩法广度优先、AI 容错工程化程度高」的完整实现，适合作为 AI 文字游戏的状态管理与指令沙箱参考。

9. 附注：未读到项