open-tabletop-gm 静态分析：模块设计与工作原理

对象：Bobby-Gray/open-tabletop-gm · 方法：纯静态分析

1. 总体架构

open-tabletop-gm 是一个「LLM 无关」的 TTRPG GM 框架：核心是一个提示词技能包（Markdown 驱动）加一套纯 Python 工具链。它的关键设计是把「叙述与判断」留给 LLM，把「一切机械计算」交给 Python，从而让小模型也能跑长线战役（README.md:7-25）。

┌────────────────────────────────────────────────────────────────┐
│  宿主 LLM 运行时（OpenCode / LM Studio / 任意 OpenAI 兼容端点）      │
│  README.md:7, 60-118；docs/LLM-GUIDE.md                         │
└──────────────────────────────┬─────────────────────────────────┘
                               │ 读指令 / 调 bash 工具 / 读写文件
┌──────────────────────────────▼─────────────────────────────────┐
│  SKILL 层（提示词，纯 Markdown，LLM 无关）                          │
│  SKILL.md         GM 人格与技艺（会话加载时读入，非启动常驻）          │
│  SKILL-branches.md 分支路由器（每个命令→步骤序列，常驻 ~2300 token）  │
│  SKILL-commands.md 命令签名参考；SKILL-scripts.md 脚本语法(已废弃)    │
└──────────────────────────────┬─────────────────────────────────┘
                               │ 命令 → 调用脚本
┌──────────────────────────────▼─────────────────────────────────┐
│  Python 工具链（确定性，零 LLM 依赖）                              │
│  scripts/    dice·combat·tracker·calendar·campaign_search·       │
│              paths·gm_graph·graph_extract_deterministic·         │
│              import_campaign·name_registry·migrate_system_version│
│  systems/<sys>/  系统模块：system.md + 可选脚本 + 数据               │
│  display/    Flask 电影化展示伴随程序（可选）                        │
└──────────────────────────────┬─────────────────────────────────┘
                               │ 读写
┌──────────────────────────────▼─────────────────────────────────┐
│  持久化（纯文本 Markdown + JSON，游戏无关）                          │
│  <campaigns-dir>/<name>/  state.md·world.md·npcs.md·npcs-full.md·│
│      session-log.md·session-log-archive.md·characters/*.md·      │
│      tracker.json·calendar.json·graph.json·session_tail.json     │
│  <root>/  .name_registry.json·characters/（全局角色名册）           │
└────────────────────────────────────────────────────────────────┘

架构分两层（README.md:29-46、SYSTEM-PORTING.md:7-16）：SKILL.md 永不随游戏变化（GM 技艺），systems//system.md 随游戏变化（具体规则）。二者在 /gm load 时一起读入。

2. 核心工作流

链路一：会话加载 /gm load（最重要的链路）

由 SKILL-branches.md:7-106 定义，七步顺序执行，是「路由架构」的典型体现：

1. 检查 display 状态（SKILL-branches.md:11-15）：读 display/app.pid 判断展示程序是否在跑。
2. 同步战役 + 重放上一会话尾巴（:17-34）：send.py --set-campaign 注册战役，读 session_tail.json 逐条回放。
3. 系统版本迁移检查（:36-52）：跑 migrate_system_version.py --check（exit 0/1/2），旧战役提示补盖 **System Version:**。
4. 读三文件（:54-63）：state.md、world.md、npcs.md，并检查 roll_mode、读 ## Pinned Facts。
5. 拉取场景子图（:65-102）：gm_graph.py scene-context --place ... --present ... 用 BFS 取 2 跳子图；未初始化则强制走 graph init。
6. 输出开场叙述（:104）：纯文本，不调任何命令。
7. 进入 GM 模式（:106）：此后玩家输入不需 /gm 前缀。

对应 SKILL.md:373-380 给出高层步骤。这一链路的目的是用最小 tool-call 深度完成加载——README.md:428 明确 70B 以下模型在 4-5 次连续 tool-call 后会漂移。

链路二：战斗回合（每回合确定性判定）

SKILL.md:287-297 给出「每回合战斗序列」，SKILL-branches.md:156-178 定义状态机（COMBAT 开始/回合/结束）：

a. send.py --player          ← 玩家动作
b. combat.py / dice.py 掷骰  ← 所有判定
c. send.py --dice            ← 带上下文回传结果
d. tracker.py effect tick    ← 扣减计时效果，打印过期告警
e. 写完整叙述
f. send.py [--stat-*]        ← 叙述 + 全部状态变更（HP/条件/资源）
g. push_stats.py --turn-current ← 推进回合指针

combat.py init 掷先攻并输出 STATE_JSON 存入 state.md → ## Active Combat（combat.py:126-137、SKILL-branches.md:160）。判定本身由 dice.py（d20+mod、优劣势、暴击/大失败标记，dice.py:64-112）与 combat.py attack（命中判定，combat.py:70-97）完成，全程不经过 LLM。

3. 模块逐一分析

3.1 SKILL.md（265 行）— GM 核心人格

工作原理：这是写给 LLM 的行为约束，本身无代码逻辑；它对「何时读哪个脚本、何时停止、何时读哪一节文件」做了极细的编排，把 GM 的隐性知识显式化成可执行的提示词。

3.2 SKILL-branches.md（293 行）— 分支路由器

常驻上下文（~2,300 token，README.md:97,428）。把每个命令映射到「先读哪个脚本文件 → 执行哪个终态动作」的线性步骤。覆盖 /gm load、/gm display、/gm path、/gm update、ACTIVE 叙述回合、/gm combat、/gm rest、/gm roll、/gm character new、/gm save、/gm end、/gm list、过去事件查找。这是项目对抗「小模型工具调用漂移」的核心手段（docs/LLM-GUIDE.md:36-42）。

3.3 SKILL-commands.md（261 行）— 命令参考

命令签名表 + 详细流程：/gm new 世界生成（:46-74）、/gm save 会话保存与归档（:78-99）、/gm pin（:102-112）、/gm import（:115-159）、/gm arc（:162-200）、/gm graph（:204-261）。

3.4 SYSTEM-PORTING.md（194 行）+ systems/ — 系统移植层

systems/TEMPLATE.md（244 行）是脚手架；systems/brp/system.md（254 行）是纯 system.md 即够用的最小移植范例（BRP 百分位系统，无系统脚本，见其 :254）。5e 是完整参考实现。核心机制：system.md 声明 ## System Versions（如 2014/2024），paths.campaign_system_version()/campaign_system() 从 state.md 头部正则解析 **System Version:**/**System Module:**（paths.py:98-151），数据文件按版本落到 systems/<sys>/data/（paths.py:154-168）。

3.5 scripts/ — 通用确定性工具链

tracker.py 与 calendar.py 都通过 subprocess 把状态推给 display，且display 未运行时静默失败（tracker.py:162-184、calendar.py:162-172）——这是「展示层可插拔」的体现。

3.6 systems/dnd5e/ — 5e 参考实现（规则数据组织）

5e 规则数据以代码内硬编码表 + 外部 JSON 数据集两种方式组织：表格型规则（熟练加值、XP、生命骰、CR）直接写在 character.py/xp.py 字典里；开放授权内容（SRD）经 build_srd.py 打包成 dnd5e_srd.json，由 lookup.py 提供模糊匹配与格式化输出。

3.7 templates/ — 战役数据模型（文件模板）

3.8 display/ — 电影化展示伴随程序（可选 Flask）

gm-display-app.py（2609 行）是核心：SSE 流式推送到浏览器，端点见其 :7-21（/chunk、/stats、/stream、/player-input/*、/srd-lookup）。场景检测按关键词切背景（README.md:304-322）、动态天空画布按 world_time 渲染（README.md:324-340）、SFX 需 numpy 否则静默降级（README.md:350）。它完全独立于 LLM，未运行时所有脚本静默失败（README.md:253）。子模块拆解：

玩家输入走「stage→ready→skip」队列（gm-display-app.py:16-19），设备首次出现需 GM 批准（README.md:294-302）；会话缓冲把最近 60 块叙述落盘到 text_log.json，断线重连自动重放（README.md:374-376）。

3.9 probe/ — 模型评测工具

probe.py（421 行）对任意 OpenAI 兼容端点跑 5 个测试用例；narrative_probe.py（890 行）做叙事质量评测；model_sweep.py（302 行）批量扫模型；results/narrative/ 存几十个模型的评测 JSON。docs/LLM-GUIDE.md 汇总结论（如 24B 在 4-5 次 tool-call 后漂移、gguf 需 eval_batch_size:4096，:36-88）。

4. 数据模型与持久化

• 战役数据（游戏无关，纯 Markdown + JSON）：state.md（世界状态/阵营移动/活跃任务/Live State Flags/战役弧/会话旗标/GM 风格笔记）、world.md、npcs.md（一行索引）+ npcs-full.md（完整 NPC：性格轴/关系/隐藏目标/说话怪癖，SKILL.md:163-164）、session-log.md + session-log-archive.md（>3 次会话后归档，SKILL-commands.md:93）、characters/<name>.md、tracker.json、calendar.json、graph.json、session_tail.json。
• NPC 结构化档案（templates/npcs.md）：表面索引表（Name/Role/Faction/Location/Attitude/Notes）:3-5 + 深度字段（Demeanor/Motivation/Secret/Speech quirk/Attitude 五级刻度/Current goal/Schedule）:9-17 + 四组人格轴（Trustworthy↔Deceptive、Ambitious↔Content、Loyal↔Opportunistic、Brave↔Cowardly）:19-23 + 关系清单（Knows/Owes/Hates/Fears/Allied with，每 NPC 至少 2 条）:25-31。这是本项目最接近「NPC 情绪记忆」的结构——但存的是倾向与关系，非逐回合情绪状态。
• 角色卡（templates/character-sheet.md）：身份/人物支柱（玩家一句话 + 派生 Bond/Flaw/Ideal/Goal + 活跃钩子）:8-13、属性/战斗/豁免/技能表:19-59、攻击/法术位/装备/背景:61-96。XP 字段由 xp.py 正则读写 **XP:** 行（xp.py:186-209）。
• 系统移植层：system.md（规则上下文）+ system_data_path() 定位 systems/<sys>/data/ 下的版本化数据；核心对版本值「不透明」，由系统模块自解释（paths.py:84-94）。
• 全局名册：<root>/.name_registry.json（跨战役角色名去重，含 slug/首次出现/活跃战役/退役记录）+ characters/ 全局角色镜像（SKILL.md:110-112、name_registry.py:15-28）。
• 路径可迁移：GM_CAMPAIGN_ROOT 环境变量重定位，find_campaign() 带旧路径回退 + 按访问复制（paths.py:48-81）。

4.1 工程与安全实践

• 测试（tests/，7 个文件）：test_gm_graph.py（368 行）、test_deterministic_extract.py（313 行）、test_display_robustness.py、test_lookup_suggest.py、test_milestone_counter.py、test_verb_table.py 覆盖图、确定性抽取、display 鲁棒性、lookup 纠错等核心路径。
• 安全：wrapper.py:27-37 对注入的玩家输入做多层防御（会话门、[角色]: 文本 结构校验、角色白名单、仅可打印 ASCII、shell 元字符剥离、行长/总量上限、审计日志、拒绝时静默丢弃）；display 用 token + 自签 TLS 认证（send.py:69-89）。
• 版本与迁移：语义化版本 + VERSION + CHANGELOG.md；/gm update --check 只做 fast-forward、拒绝脏工作树（SKILL-branches.md:131-138、update_skill.py）；migrate_system_version.py 幂等补字段并先备份（migrate_system_version.py:95-99）。

5. 与 Z.R.I.C 功能对照表

6. 三个重点问题的答案

1. SKILL.md 如何驱动 GM：SKILL.md 是「GM 技艺的行为约束提示词」，不参与启动常驻（README.md:97）。它用「Script-First 规则」（:118-127）+「每回合 Display 同步序列」（:287-297）+「压缩后重读最小源节」（:166-174）等显式约束，把 GM 经验写成 LLM 可执行的编排步骤；SKILL-branches.md 再把命令映射成最短 tool-call 序列。

2. SYSTEM-PORTING.md 的移植机制：两层分离——SKILL.md 恒定、system.md 承载规则。移植 = 复制 TEMPLATE.md 填 system.md，最小可用集只需「骰子判定/属性/HP/资源/条件」（SYSTEM-PORTING.md:149-156）。通用脚本不依赖具体系统；系统特定数据经 paths.py 版本化落到 systems/<sys>/data/；brp/system.md 证明「纯文档即可跑」的底线。

3. LLM 无关性如何实现：三层——(a) 宿主层无绑定，README 给 OpenCode 与 LM Studio 两份配置（README.md:84-118）；(b) 所有机械操作移出模型，LLM 只做叙述与判断（docs/LLM-GUIDE.md:7-20）；(c) 上游 claude-dnd-skill 中依赖 Claude API/Haiku 的部分，此 fork 用确定性等价物替代或暂缓——关系图是「manual + query-only」，抽取用 graph_extract_deterministic.py 动词表模式匹配（gm_graph.py:8-13、graph_extract_deterministic.py:1-16）。

7. 设计评价

优点

1. 机械/叙述严格分离：所有算术（骰子、HP、先攻、计时效果、XP 表）都在 Python 里确定性完成，模型不碰数字——直接降低对小模型的能力门槛（docs/LLM-GUIDE.md:7-20、README.md:424-426）。
2. 提示词工程精良：SKILL-branches.md 把系统提示从 ~18,000 压到 ~2,300 token，并逐命令定义线性步骤以对抗小模型工具调用漂移（README.md:97,428；docs/LLM-GUIDE.md:36-42）。
3. 持久化选型务实：战役数据全用可读可改的 Markdown + JSON，配合「最小源节重读」「Live State Flags」等抗压缩策略，明确针对长线战役的上下文压缩问题（templates/state.md:37-47、SKILL.md:166-174）。
4. 系统可移植性设计干净：SKILL/system 两层分离 + TEMPLATE.md 脚手架 + 通用脚本不耦合具体系统，brp 模块证明最小移植成本极低（SYSTEM-PORTING.md:149-156）。
5. 防御性降级做得好：display 未运行、numpy 缺失、PyYAML 缺失、SRD 未构建时均静默降级不中断会话（tracker.py:162-184、build_srd.py:27-32、gm-display-app.py:44-76）。

缺陷

1. 对 LLM 上下文窗口高度依赖：核心状态（state.md/world.md/npcs.md + 全部角色卡 + system.md）每次 /gm load 全量读入（SKILL.md:378），战役变长后上下文压力线性上升，虽有用归档/图缓解但仍靠模型自己按提示词「只读最小节」，无硬约束。
2. 触发器/事件是「人肉」而非引擎：威胁升级弧、world_pressure、Faction Moves 都是「提示词让 GM 记着做」的约定，没有代码自动触发（templates/world.md:71-82、SKILL.md:63-64）；tracker.py 计时效果需手动 tick（tracker.py:243）。
3. 图是「手工+查询」而非自动维护：graph 边靠 GM 在会话中手动 add-edge，save 时的关系变化扫描也靠 LLM 事后提出、GM 审批（SKILL-branches.md:254-268）；确定性抽取器明确标 recall ~50%（graph_extract_deterministic.py:12）。
4. 规则数据硬编码在代码里：XP/CR/生命骰/豁免熟练等 5e 表直接写死在 character.py/xp.py 字典，改版本（2014/2024）或换系统时需改代码而非数据（character.py:25-68、xp.py:38-92），与「system.md 即规则」的移植理念部分冲突。
5. display 状态与战役状态双写易失同步：tracker.json/calendar.json/display 侧 stats.json 与 state.md 里的人工字段（HP/资源/条件）多处并存，靠 GM 逐回合同步（SKILL.md:268-297），无单一权威源，存在漂移风险。

8. 结论

open-tabletop-gm 是一个**「提示词技能包 + 确定性 Python 工具链」的 GM 框架，其真正价值不在某个模型能力，而在工程化的职责分离**：把 TTRPG GM 工作拆成「叙述判断（LLM）」「机械判定（脚本）」「世界记忆（Markdown/JSON 分层）」「展示（可选 Flask）」四层，并针对小模型/本地模型的工具调用深度做专门优化。它已是一个成熟可运行的开源项目（非文档占位），5e 全支持、BRP 作移植范例，LLM 无关性落实到位。其短板集中在「剧情/世界自动推演仍是提示词约定而非代码引擎」——推演分支、触发器、NPC 情绪等 Z.R.I.C 维度目前靠 GM 模型的自觉与 SKILL 编排维持，而非确定性状态机。对后续 Z.R.I.C 设计的直接借鉴点：**分层记忆（Pinned Facts / Live State Flags / Continuity Archive）与「把可计算部分移出模型」**这两条路线，是本地小模型跑长线战役最可复用的两个经验。

9. 关键代码位置速查