AI Sandbox Game 静态分析：模块设计与工作原理

对象：hayowei/aisandboxgame（70★，JavaScript 零构建浏览器应用，2026-06 活跃）· 方法：纯静态分析（不运行）一句话：本地优先的浏览器文字 RPG——ReAct 推理循环 + 工具注册表 + 审计子代理 + 结构化世界卡创作（P3 JSON-Patch）+ 六边形地图 + 章节记忆，全 AI 多厂商直连。

1. 总体架构

浏览器（零构建、零后端；React18+本地 vendor+ServiceRegistry+EventBus）
┌───────────────────────────────────────────────────────────────┐
│ UI 层    ui/* (settingsUI/debugUI/npcPanelUI/saveManagerUI…)    │
│           renderers/* (gameOutputRenderer/streamVisualizer…)    │
├───────────────────────────────────────────────────────────────┤
│ 应用层   stores/* (npcStore/entityStore/inventoryStore/timeline…│
│          )  ·  core/* (sessionManager/ServiceRegistry/EventBus) │
├───────────────────────────────────────────────────────────────┤
│ 游戏引擎 services/                                             │
│   pzgmStoryController（GM 引擎）· paceEngine（节奏）            │
│   summaryService（章节记忆）· timelineService · triggerScanner  │
│   map/*（Hex 地图）· smsService（短信）· skillDispatcher（技能）│
├───────────────────────────────────────────────────────────────┤
│ AI 层  services/ai/                                            │
│   react.js —— ReAct 主循环（narrative/settlement/closing 三阶段）│
│   prompt-gm.js —— GM 提示词构建（168KB）                        │
│   provider.js —— 多厂商 Adapter 工厂（mixin 注入 AIService）    │
│   subagents（npcCardSync/npcIntroAudit/npcRecheck/             │
│              playerStatusRecheck/starter）—— 审计型子代理      │
│   toolRegistry + tools/* —— 带框架元数据的工具注册表            │
├───────────────────────────────────────────────────────────────┤
│ 设计层 services/design/ + p3/                                  │
│   世界卡面试式创作（P1 锚定→P2 展开→P3 JSON-Patch 精修）        │
├───────────────────────────────────────────────────────────────┤
│ 持久化  localStorage（配置/AI设置）+ 存档槽位 + migrations      │
│         (v1ToV2/v2ToV3) + snapshotRing + PWA(sw.js/offline)    │
└───────────────────────────────────────────────────────────────┘
        │ 浏览器直连（CORS）
  Gemini / Anthropic / OpenAI兼容(openai/deepseek/grok/siliconflow/自定义 baseUrl)

组织模式：无打包器、无模块系统——通过「mixin 类 + 文件末尾合并到 AIService.prototype」模式（react.js:12-14）切分巨型服务；全局挂 window.*（toolRegistry/promptRegistry/worldCardManager）做服务定位；ServiceRegistry + EventBus（core/）做正式的解耦通道。

2. 核心工作流一：游戏回合（ReAct 主循环，ai/react.js）

_runAgentWorkflow（react.js:97，文件共 2673 行）是一个策略模式 + 三阶段编排的 function-calling 循环：

回合入口：turn 级唯一 ID（telemetry）、中止信号挂实例、迭代计数重置；
能力预检：模型不支持 function calling 时早抛（memo 记住「provider::model」，避免用户白等一轮，react.js:117-120 注释）；
iter1 叙事脊柱：按模块配置（iter1_narrative 有独立 provider/model/温度/thinking 档）生成叙事主线；
工具循环：模型可调用 toolRegistry.getReactLoopDeclarations() 返回的工具（排除 dispatcherManaged 工具，那些由 SkillDispatcher 管理，toolRegistry.js:235-243）；
三阶段收束：narrative → settlement（结算：状态/物品/地图变更落 store）→ closing（收尾）；
全程流式：onChunk 高频回调 + segment tracking + 每 iter 独立遥测（stepMetrics，RECOMMENDED_PHASE_MAP 支持不同 iter 不同模型）。

错误分类器（react.js:21-80，生产级容错的代表）：把上游失败分成 8 类——safety_filtered（Gemini 内容过滤）/ balance（402、余额关键词、billing_hard_limit_reached、OpenAI insufficient_quota）/ payload_too_large（413）/ provider_5xx / rate_or_quota（429，但 insufficient_quota 归余额）/ auth（401/403，但先查 message 关键词防中转站误报）/ network / forced_tool_thinking_incompat（推理模型不支持强制工具调用）——每类给出精准的用户修复建议。

3. 核心工作流二：世界卡创作（设计模式，services/design + p3/）

面试式创作（README 宣称「自然语言 pitch → 可玩世界卡」）的三阶段：

Phase 1（P1）：AI 抽取 frozen_moment（世界「此刻」：datetime + label + world_tense 张力态）、player_anchor（玩家锚点）、world_terms（世界观术语）、narrative_core_characters（核心角色），每个字段带 source 标记（explicit=作者改过/inferred=AI 抽取/defaulted=兜底，worldCardFieldSchema.js:73-78）；
Phase 2：按已确认的锚点展开完整设定；
P3 精修：JSON-Patch 引擎——AI 输出 RFC6902 patch（p3Service/p3CallAPI/p3Dispatcher/p3JsonValidator/p3PatchEngine，vendor/fast-json-patch.min.js），校验通过才应用，可反复精修；
世界卡 Schema（config/worldCardFieldSchema.js，646 行）：V2 卡约 40 个高频字段的 JSON Pointer 路径 schema（/{id} 动态 key、/{idx} 数组索引占位符），供 P3 lookup_schema 工具查询；designService 的 snapshotInfra 保存每次设计调用的完整快照（_pushDesignTrace，provider.js:517-545，上限 500 条防内存堆积）。

4. 工具系统（toolRegistry + tools/*）——比裸 function calling 高一级的编排

工具注册表（toolRegistry.js）每工具带框架元数据，而不仅是 schema：

元数据	用途
`phase` / `required`	工具属于哪个阶段、该阶段结束前必须被调用（`getRequiredToolsForPhase`）
`trigger` / `triggerHint`	谓词触发 + 默认提示文案（triggerScanner 扫描）
`signal`	工具专属事件名（EventBus 信号）
`dispatcherManaged`	由 SkillDispatcher 管理的工具，从 ReAct 循环声明中隐藏（防主循环乱调）
五段描述	`description / when_to_call / avoid_when / input_focus / expected_output` 由 promptRegistry 统一渲染（工具 schema 与提示词描述分治）

工具集（tools/*）：archiveTools（归档）/ commTools（通讯）/ computeTools（计算）/ expandTools（扩写）/ itemTools（物品）/ narrativeTools（叙事）/ npcTools（NPC）/ readTools（读取）/ stateTools（状态）。

5. NPC 智能体系统（stores/npcStore + analyzers + 审计子代理）

三分析器（analyzers/）：CognitiveAnalyzer（认知状态：优先级链玩家存档覆盖 > timeline 规则推算 > 默认值，且每次更新带 UID 溯源，CognitiveAnalyzer.js:28-54）、RelationshipAnalyzer（关系）、StatusAnalyzer（状态）；另有 SexHistoryAnalyzer（成人向关系史——合规敏感）。
审计子代理（services/ai/subagents）：npcCardSyncSubagent（同步 NPC 卡与叙事）、npcIntroAuditSubagent（NPC 登场审计）、npcRecheckSubagent（NPC 复查）、playerStatusRecheckSubagent（玩家状态复查）、starterSubagent——用 AI 校验 AI 的一致性，这是该项目区别于其他引擎的标志性设计。
NPC 交互面：短信（smsService + phoneUI + summary-sms.js 独立总结通道）、OOC 对话（npc-ooc.js）、NPC 卡渲染（npcCardRenderer）。

6. 记忆/叙事连续性

章节总结（summaryService 71KB + entityChapterSchema）：按章折叠对话为摘要，实体（角色）分章归档——「AI that remembers」的落点；
timelineService + archiveService + searchScorer：时间线记录 + 归档 + 检索打分；
paceEngine：叙事节奏控制；directorTagSentinels（导演标签哨兵）：剧情指示标记；
本地 token 估算（tokenEstimateService + assets/tokenizers/deepseek-v3/tokenizer.json + vendor/transformers.min.js）：浏览器内真实 tokenizer，无需服务端。

7. 地图与位置（map/*）

HexGrid + MapGenerator（生成）+ MapData + MapRenderer + MapInteraction + mapMovementHandler + TerrainTypes；locationTracker + locationTriad（三元位置：地点/区域/方位）供 prompt 注入。

8. 持久化与存档

sessionManager（1845 行）：新游戏/读档/存档统一管理，session origin（manual/unsaved）绑定 + 自动存档 + 过渡锁（_transitionLockState）；
存档槽位（saveManager + saveStore + snapshotRing 环形快照）+ 版本迁移（migrations/v1ToV2、v2ToV3——存档格式演进有正式通道）；
配置/AI 设置走 localStorage（含自定义 provider、每模块价格 priceIn/priceOut——成本面板数据源）。

9. 与 Z.R.I.C 功能对照

能力	aisandboxgame	Z.R.I.C
剧本解析	✅ 世界卡（结构化 schema + 面试式 P1→P3 生成）	✅ campaign.json + knowledge RAG
推演分支	⚠️ ReAct 单循环（无多分支选择）	✅ 2-4 分支 + 副作用冻结
自动判定	✅ d20 检定 + 工具结算（三阶段 settlement）	✅ 触发器 + stat 判定
世界状态	✅ stores 全家桶 + 实体分章	✅ SQLite 表
NPC 情绪记忆	✅ 认知/关系/状态三分析器 + 审计子代理	✅ 三轴情绪状态机
地图	✅ 六边形生成地图	✅ 房间/通道拓扑
触发器	⚠️ triggerScanner + director tags（轻量）	✅ 条件树 + 11 种动作
时间线	✅ timelineService	✅ 多时间线可合并
记忆系统	✅ 章节总结 + 归档 + 检索	✅ L1/L3 + RAG
本地模型	✅ 自定义 provider baseUrl（浏览器直连）	✅ 需补丁（已实测）
多人/投屏	❌ 单人（无服务端）	✅ WebSocket 投屏
许可	双许可（README：Framework Code 开源 + 其余条款，详见 LICENSE）	GPL-3.0

10. 设计评价

优点

模块化 AI 配置：每个 AI 模块（react/sms/summary/chapter/design/iter1_narrative/step3…）独立 provider/model/温度/thinking 档/价格——旗舰模型跑叙事、小模型跑总结的成本控制粒度在开源侧罕见（provider.js:17-46）。
审计子代理（npcCardSync/npcIntroAudit/npcRecheck/playerStatusRecheck）：用独立 AI 调用校验主循环输出的一致性，把「多智能体」用在质量门禁而非仅生成。
P3 JSON-Patch 设计引擎：AI 修改世界卡走可校验、可回滚的结构化 patch，而非自由文本重写——创作模式的工程上限。
工具元数据框架（phase/required/trigger/dispatcherManaged + 五段描述分治）：把工具从「函数列表」升级为「阶段编排单元」。
生产级容错：错误分类器（8 类上游错误 → 精准建议）、无 function-calling 模型 memo 预检、遥测 finish_reason 归一化且成本面板防双计。
真本地优先：PWA + 离线页 + 本地 tokenizer + 零构建——分发给非技术用户的成本趋近于零。

缺陷

巨型单文件 + 全局命名空间：chatCore.js 258KB、debugUI.js 165KB、prompt-gm.js 168KB，window.* 全局耦合贯穿全库——无模块边界，维护与二次开发成本高。
成人向功能（SexHistoryAnalyzer、NSFW 内容）：合规与分发（应用商店/托管）风险。
浏览器直连 API：key 存在用户浏览器 localStorage，无法做服务端鉴权/配额——「本地优先」的代价，也意味着无多人、无账号体系。
依赖强模型：ReAct + function calling + 三阶段 + 审计子代理的多轮调用链，小模型（本地 7B 级）难以跑完整链路（作者预检只挡「不支持工具」的模型，不挡「工具用得差」的模型）。
复杂度天花板：AI 模块配置矩阵 × 五段工具描述 × phase 体系 × 设计模式 P1/P2/P3——功能密度极高但学习曲线陡峭。

11. 结论

是：本地优先的浏览器单人文字 RPG 完整实现——「AI 多智能体协作 + 工具编排 + 世界卡创作工具」功能密度在开源侧最高，尤其适合做「零部署、双击即玩」的分发形态参考。
不是：传统意义的引擎（无后端/无 API 网关/无多人）、规则系统（d20 只是骰子，无 5e/CoC 规则深度）、DM 在环演出台（无 GM 控制台/投屏分离——虽然它有 debugUI 和设计模式）。

同类静态分析：24（Z.R.I.C）、26-34（其余九个框架）；功能矩阵总览见 22-zric-similar-frameworks.md。