D&D 5e AI 地下城主引擎 — 三层架构

基于 2024版 D&D 5e 规则 的 AI 地下城主系统。纯对话交互，无需专用客户端，任何 IM 软件即可运行。本 Skill 将 DM（地下城主）角色交给 AI，严格按照模组剧本和规则书推进游戏。

城主人格：明萨拉·班瑞（Minthara Baenre）——守序邪恶卓尔圣武士，前魔索布莱城贵族。语气霸道、果断、直接，但绝不放水作弊。详见 SOUL.md 和 IDENTITY.md。

三层架构概览

┌─────────────────────────────────────────────┐
│  LLM 层：dnd-dm Skill (OpenClaw)             │
│  叙事生成、NPC 对话、场景描述、行为红线       │
│  ← prompt 驱动，保持 LLM 核心优势             │
├─────────────────────────────────────────────┤
│  API 层：dnd-api (FastAPI，端口自动检测)     │
│  30 个 HTTP 端点 + CLI 命令行工具            │
│  ← 任何平台（Discord/Foundry/Web）均可调用    │
├─────────────────────────────────────────────┤
│  引擎层：dnd-engine（已内置）                 │
│  骰子、战斗、存档、世界状态、模组缓存、SRD 搜索 │
│  ← 纯 Python，零 LLM 依赖，220 项测试覆盖     │
└─────────────────────────────────────────────┘

核心原则：上层依赖下层，下层不依赖上层。LLM 层只管叙事 + 调用引擎函数，不自行计算或拼数据。

模式与手动骰

• 模式（mode）：系统支持两种运行模式：adventurer（默认）和 gm_assist。
  • adventurer：引擎按规则自动执行掷骰与结算，玩家不干预骰面结果。
  • gm_assist：城主辅助模式，允许通过 MCP 工具预设「手动骰」，用于演示、复现或争议裁定。
• 选择时机：在新游戏启动时选择（例：start_new_game(mode="gm_assist")）。
• MCP 工具：start_new_game(mode)、get_mode()、set_manual_roll(name, value)、list_manual_rolls()、clear_manual_rolls()。
• 行为：gm_assist 且存在手动骰时，掷骰函数优先使用手动骰并记录使用历史；否则正常随机掷骰。
• 透明性要求：所有手动骰操作必须在会话内记录并可查询，避免秘密修改。

快速开始 — 安装指引

步骤 1：解压到工作目录

将 dnd-dm-skill-x.x.x.zip 解压到空目录即可使用。

your-workspace/
├── SKILL.md / _meta.json
├── references/             ← 核心规则文件（供 LLM 读取）
│   └── party-sheet.html    ← 角色卡网页（双击打开）
├── dnd-engine/             ← 引擎源码（已内置，无需安装）
├── items/                  ← 物品模板
└── DND Lens（可选子技能）
    ├── data/               ← 知识资产（世界卡 / 模组范式 / 映射字典）
    ├── scripts/            ← lens_rag.py（BM25 中文检索）+ lens_pipeline.py
    ├── world-lore/         ← 功能一：世界观 / 编年史检索
    ├── module-forge/       ← 功能二：按需求生成模组
    └── echo-map/           ← 功能三：真实经历 → DND 映射

步骤 2：放入规则书和模组

⚠️ 需用户自行准备：规则书和模组因版权原因无法随 Skill 分发。

将 2024版三宝书放入 rules/ 目录，模组文件放入 modules/ 目录。

步骤 3：校验并开玩

在对话中回复 /verify，Agent 自动校验环境。通过后即可开始游戏。

首次使用时 LLM 会自动加载引擎：import sys; sys.path.insert(0, "dnd-engine")

一条命令完成检定（推荐）

dnd-check --actor 老白 --skill 潜行 --dc 15       # Windows 用 dnd-check.cmd
dnd-check --actor 老白 --ac 16                   # 攻击检定（走 AC）

自动读 live_party.json、组装加值、投骰，输出即为可直接贴给玩家的明细。 实测 ≈0.13 秒/次（含 Python 启动）。不要为了调引擎去写临时 Python 脚本。 参数与“角色卡缺技能信息怎么办”见 references/DM_RULES.md 规则 1.2.1。

相关技能

子技能 · DND Lens（世界观 / 模组 / 经历映射）

宿主于本技能下的三件套，共享 scripts/lens_rag.py（BM25 中文检索）与 data/ 知识资产。三者可独立调用，也可串联：真实经历 → echo-map 映射 → module-forge 做 CR 平衡 → world-lore 检索设定锚点。

一键串联：经历 → 映射 → 平衡 → 背景，运行 python scripts/lens_pipeline.py --story 经历.txt --names "张三" --places "上海" --players 4 --level 5 --duration medium（详见脚本头部说明）。

调用方式（相对本技能目录，用当前环境的 Python 运行）：

# 功能一：世界观 / 编年史检索
python scripts/lens_rag.py "深水城 历史" --top-k 6
# 功能二：按需求生成模组（带 CR 平衡）
python module-forge/scripts/module_forge.py --players 4 --level 5 --duration medium --type 都市寻宝
# 功能三：真实经历脱敏 + 映射
python echo-map/scripts/echo_map.py anonymize --names "张三" --places "上海"

数据流：各子技能脚本通过 sys.path 复用 scripts/lens_rag.py；数据目录默认 data/，可用环境变量 DND_LENS_DATA 覆盖。

功能概览

三层架构

新增/修改功能时按 DM_DEV_GUIDE.md 开发规则9 做三层分析。

判定层（1.2.1 新增）

问题：LLM 直接决定「要不要检定 / 投什么技能 / DC 多少」时，同一条输入会给出不同答案，且无法审计。

做法：把判定拆成「批量原子提问 → 类型化回答 → 代码组合成 DecisionPacket → 引擎结算」。

• 三原语：Choice（选一个）、Score（打 0–1 分）、Noul（是/否）。
• 优先级链（经 106 条探针实测标定）：
  1. 要不要检定：模型有把握就听模型；低置信时用规则表强命中补位。
  2. 投什么技能：模组关键词 > 规则表强命中 > 模型高置信 > 模型低置信。
  3. DC：模组原文 > 规则表 > 模型档位 > 默认档。
• 置信度门控：门限 0.60；低于门限的字段回退本地依据并记入 low_confidence_fields。
• 契约保护：模型输出非法 → 先尝试一次修复 → 仍失败则回退纯规则路径（contract_error:...），不会让游戏卡住。
• 确定性兜底：本地规则表 + check_rules.json 映射始终可用，不依赖任何外部模型。

叙事层（1.2.1 新增）

问题：长模组（40 万 token 级）每轮整份注入，导致成本高、首字慢、且剧情状态无处落地。

做法：四级注入 + 确定性节点图 + 一轮一次调用。

• 四级注入预算：L0 骨架 ≈ 300 tok / L1 当前场景 2–4k / L2 邻域摘要 ≈ 600 / L3 按需全文。实测每轮注入 52.9k → 6.1k tok。
• 确定性剧情图：module_plot.json（节点+边）+ plot_state.json（当前节点/已访问/事件）。推进由代码裁决，不由模型自由发挥。
• 一轮一次调用：叙事文本与类型化 delta 一次返回，实测 3 次 → 1 次。
• 前缀分层（prefix cache）：system（契约）/ user-stable（队伍+本章索引）/ user-volatile（本轮变化）。实测 88% 输入命中缓存。
• 流式输出：边收边增量解析 narration 字段，实测首字 ≈2.6 s 出现。
• 预取：后继场景切片先做批量相关性筛选并缓存（按前缀签名失效）；可选预热稳定前缀。
• 防出戏守卫：叙事若出现内部字段名/节点编号/内部术语 → 触发一次修复 → 仍泄漏则 fail closed，宁可不输出。

规则裁决

• 严格按 2024版 规则结算（6步检定流程）
• 检定公式由 dnd_engine.combat.checks 结构化返回，LLM 仅展示结果
• 数据模板由 dnd_engine.save.templates 工厂生成，LLM 不自拼 JSON
• 自然1不重投，公平透明
• 26 条运行规则按 6层架构 组织（每条规则有 <!-- layer: N --> 标记）

战斗系统

• 引擎层：命中/伤害/豁免检定/战斗状态 CRUD——代码化
• 多重攻击：敌人按 multiattack 真打 N 次（上限 4 次）
• 抗性/免疫/易伤参与结算（免疫×0、抗性×0.5、易伤×2，双向生效）；伤害类型用中文关键词匹配
• 敌人 AI：每敌 4 问（action / target_policy / attack / morale），引擎把策略解成具体目标；HP≤33% 且士气不足时强制撤退
• 战斗状态持久化到 combat_state.json
• 一键决议：POST /api/combat/resolve-round 合并命中+伤害+状态更新

信息展示

• 渐进式探索引导（§9.2）：幕前自然语言暗示 + 幕后 _scene_cache_*.json 追踪房间
• 检定结果直接输出 checks.py 的 detail_lines 数组，格式由代码保证
• 任务清单、角色卡、法术展示——标准模板
• 角色卡网页：party-sheet.html 双击即可查看队伍状态

角色创建

• 7阶段对话式创建，属性 roll_stat() 由引擎层执行
• 自动生成 live_party.json 和角色卡

存档系统（引擎层）

• dnd_engine.save.io：write_save() / load_save() / list_saves()
• 场景缓存自动嵌入存档（scene_cache.py）
• 模板工厂：make_character_template() / make_save_template() / make_quest_template()

CLI 命令行

API 接口（dnd-api，共30个端点）

骰子：

战斗：

队伍：

存档：

SRD：

系统：

世界状态：

行为红线（15条，不可越界）

1. NO 偏离模组：禁止自创与模组无关的大段剧情
2. NO 无底线乱搞：严禁任何 R18G 交互描述
3. NO 放水求爱：严禁修改怪物数据以迎合剧情
4. NO 打断真骰：自然 1 不重投，包括关键剧情检定
5. NO 反刍世界观：不混用博德之门3游戏设定与模组设定
6. NO 规则混淆：不使用 2014 版旧规则覆盖 2024 版新规则
7. NO 成年人黑暗内容：涉未成年人零容忍
8. NO 全知推理：DM 不替 NPC 知晓玩家未公开的战术
9. 禁止 LLM 自行计算 AC/DC/检定格式——必须调引擎层
10. 禁止 LLM 自行生成 Python 脚本执行——必须用 import 或 API 调用

6层规则架构

DM_RULES.md 中 26 条运行规则按 6 层组织，每条规则开头有 <!-- layer: N --> 标记。加载时按层优先级常驻：

文件说明

版本 1.2.1 · 2026-09-25 · 合并发布：线上 1.2.0 的 DND Lens 三子技能（world-lore / module-forge / echo-map）+ 本地新一代引擎（类型化判定层 judge、叙事层 narrative：四级注入 52.9k→6.1k tok、一轮一次调用、prefix cache 命中 88%、流式首字 2.6s、防出戏守卫）· 严格按 2024版 D&D 5e 规则 · 220 项测试通过 · 支持 Windows / macOS / Linux