back
loading skill details...
通用Dungeon Master AI城主系统。基于2024版D&D 5e规则的智能AI地牢城主程序。支持场景级懒加载、世界状态追踪、剧情摘要、模块化运行。
---
name: dnd-dm
description: "通用Dungeon Master AI城主系统。基于2024版D&D 5e规则的智能AI地牢城主程序。支持场景级懒加载、世界状态追踪、剧情摘要、模块化运行。"
version: 1.0.12
author: 老白干一杯
tags: [dnd, dm, rpg, ttrpg, dungeon-master, dnd5e]
---
# D&D 5e AI 地下城主引擎
基于 **2024版 D&D 5e 规则** 的 AI 地下城主系统。纯对话交互，不需要专用客户端，任何 IM 软件即可运行。
## 快速开始
### 已通过 OpenClaw 插件安装
如果你已经通过插件安装了本技能 (`dnd-dm`)，请执行以下部署步骤：
#### 1. 将引用文件复制到工作目录
将插件 `skill/references/` 目录中的文件复制到工作目录根：
```
your-workspace/
├── DM_RULES.md ← 运行规则（6层分层架构）
├── DM_RULES_INDEX.md ← 层级索引（含关键词速查列）
├── DM_TEMPLATES.md ← 信息展示模板（9种场景模板）
├── DM_MAP_SYS.md ← 地图生成系统
├── CHAR_CREATION.md ← 角色创建流程（7阶段）
├── MODULE_ARC.md ← 模组运行结构（通用模板）
├── MODULE_INDEX.md ← 模组章节索引（指针格式）
├── DM_DEV_GUIDE.md ← 城主开发规则
├── SOUL.md / IDENTITY.md ← DM 人格定义文件
├── srd/ ← SRD 5.2.1 参考文档（含Python搜索脚本）
├── code/ ← 代码模板库
├── rules/ ← [自行准备] 2024版三宝书
├── modules/ ← [自行准备] D&D 模组文件
├── saves/ ← [自动生成] 存档目录
├── world_state.json ← [自动生成] 世界状态
├── plot_summary.json ← [自动生成] 剧情摘要
└── live_party.json ← [自动生成] 实时角色状态
```
#### 2. 配置技能
在 `~/.config/openclaw/agents.yaml` 中配置此 skill：
```yaml
agent:
name: dnd-dm
skills:
- dnd-dm
```
#### 3. 首次运行
启动后，城主会自动：
1. 检查 `modules/` 目录扫描可用模组
2. 提供载入存档 / 新开一局 / 查看存档 选项
3. 如新开一局，输入模组名→`init_module()` 自动生成模板→进入对话式角色创建
## 相关技能（Related Skills）
本技能与 **`dnd5e-srd`** skill 配合使用：
| 技能 | 作用 | 配合方式 |
|:----|------|---------|
| **`dnd-dm`（本技能）** | 城主行为规则 + 裁决流程 + 展示模板 | 主技能，定义DM如何行动 |
| **`dnd5e-srd`** | SRD 5.2.1 RAG 检索——法术、职业、装备、怪物、状态 | **战时快速查规则** — 通过 Python 脚本搜索+展开引用 |
| **`rules/` 目录** | 2024版三宝书全文（玩家手册+城主指南+怪物图鉴） | **备份查阅** — SRD 搜索不到时降级使用 |
**分工原则**：
1. 凡在 SRD 中可搜索到的内容，优先使用 `srd/` Python 脚本检索
2. 引用格式：`[DND5eSRD_XXX-YYY.md, chars N-M]`
3. 搜索无结果时降级至 `rules/` 规则书全文
> 本技能不包含 SRD 文件；需用户同时安装 `dnd5e-srd` skill 或将 SRD 文件部署到工作目录的 `srd/` 子目录。
> 详细分工参见 `DM_RULES.md` →「规则参考来源分工」。
## 规则分层架构（v1.0.12）
19条运行规则按场景分为 **6层**，含 5 级上下文加载优先级体系（P0-P5）：
| 层 | 名称 | 规则 | Token 策略 |
|:---:|------|------|:----------:|
| **0** | 全局基石 | 规则10(红线15条), 规则18(代码模板) | **P0 常驻** |
| **1** | 运行时交互 | 规则0-1.5,2,2b,3,4,7,8,17（共12条） | **P1 场景推进时**加载 |
| **2** | 展示模板 | 规则5(经验结算), 规则9(模板), 规则15(战斗展示) | **P1 展示时**加载 |
| **3** | 战斗系统 | 规则15b(装备加成) | **P3 进入战斗**检索 |
| **4** | 进度与状态 | 规则13(升级), 规则14(存档+剧情摘要), 规则16(实时状态) | **P4 升级/存档时**加载 |
| **5** | 模组控制 | 规则12(通用构建+存档恢复核查) | **P5 开新局**加载 |
**5级上下文加载优先级（P0-P5）**：
| 级别 | 内容 | Token预算 |
|:----:|------|:---------:|
| **P0** 常驻 | SOUL + 世界状态摘要(50-100t) + 剧情摘要(100-300t) | ~2.3K |
| **P1** 当前场景 | 场景原文(场景索引行范围加载) + NPC条目 | ~3.5-6.5K |
| **P2** 对话 | 最近5-10轮 | ~2K |
| **P3** 规则检索 | 关键词 → `rule/retriever.py` 按需加载 | 0~2K |
| **P4** SRD检索 | 法术/怪物/装备 → `srd/scripts/` 按需搜索 | 0~1K |
| **总计** | | **~5.8K~12K** |
日常探索仅需 P0+P1+P2（~8-10K tokens），较旧版全量加载（~50-75K）节省 **70-85%**。
## v1.0.12 新功能
### 场景级懒加载
按 `##` 识别场景边界，每次只加载当前场景（~2.5K tokens），替代整章文件（~27-55K tokens）。场景切换时通过 `scene_index.py` 自动更新行范围。
### 结构化世界状态
6种数据结构追踪派系关系、任务进度、NPC状态、地点发现、游戏天数、当前场景。增量更新 API：`update_faction()`、`update_quest()`、`update_npc_status()` 等。
### 剧情摘要系统（P0）
每次存档自动生成100-300 token摘要（队伍状态+位置+NPC关系+关键事件+任务进度）。会话启动优先加载摘要替代完整聊天历史。仅当玩家要求详细回溯时才加载原始历史。
### 规则关键词检索
`retriever.py` 提供19组关键词→规则ID映射。`load_rules_by_keywords()` 按需提取匹配规则文本，替代加载整层（5K→0.5-2K tokens）。
### 通用模组架构
`init_module(module_name)` 接受任意模组名，自动生成通用模板（索引/运行结构/世界状态/场景索引）。所有文件通过 `scan_modules()` 自动发现，零硬编码。
### 检定展示函数
`checks.py` 提供 `resolve_skill_check()`、`check_hit_v2()`、`resolve_save_check()`，显示完整加值构成明细（熟练+属性+装备+临时），替代纯数字总览。
## 功能概览
### 📐 规则裁决
- 严格按 **2024版** 规则结算（6步检定流程）
- 18种技能检定 + 战斗 + 法术 + 动作经济
- 自然1不重投，公平透明
- 6层规则按场景按需细读，关键词快速检索
### ⚔️ 战斗系统
- 先攻表（表格展示，排序+HP+AC+位置+状态）
- 每轮结束后自动展示更新后的战斗态势表
- 已死亡单位划掉、当前行动者标记
- **战斗状态持久化**：`combat_state.json` 文件跟踪，替代LLM记忆
### 📋 信息展示
- 4种标准模板：剧情整理 / 房间布局 / 战斗态势 / 地形图
- 任务清单（主线+支线，含状态追踪）
- 实时角色卡查询（单角色 / 队伍总览 / 物品检索）
- 法术展示：含检定方式 + 推荐理由
### 🧙 角色创建
- 7阶段对话式角色创建
- 属性分配、种族、职业、背景、技能、装备、法术选择
- 当前属性自动记录到 `live_party.json`
### 💾 存档系统
- `saves/存档*.json`：自动递增编号，不覆盖已有
- 每份存档记录时间戳、章节、位置
- 存档时自动生成剧情摘要（`plot_summary.json`）
- `live_party.json`：实时角色状态（每次变更后立即更新）
- 存档触发：升级、长休、章节结束、玩家要求、重大决策前
### 🌍 世界状态
- 派系关系（焰拳/范萨姆普尔/死亡三神等，通用模板）
- 任务进度追踪（主/支线，初始化为"待触发"）
- NPC状态记录（存活/死亡/友好/敌对）
- 地点发现记录（新地点自动登记）
- 游戏天数自动推进
### 🔒 行为红线（15条）
- 禁止偏离模组、禁止放水、禁止混用世界观
- 规则锁定（2024版 > 旧版）、自然1不重投
- 禁止提前加载后续章节、禁止跳过检定流程
### ⚡ Token优化体系
- **P0-P5 5级上下文优先级**：按场景按需加载，日常操作仅8-10K tokens
- **场景级懒加载**：只加载当前场景原文，切换场景更新行范围
- **剧情摘要替代历史**：100-300 tokens 替代数万 tokens 聊天历史
- **规则关键词检索**：19组关键词按需提取规则文本
- **战斗状态文件** `combat_state.json`：持久化跟踪回合/HP/效果
- **模组缓存** `module_cache.json`：章节内容一次读取，按场景/NPC检索
- **公式模板**：攻击/伤害/豁免等固定格式字符串，直接填值
- **规则速查** `quickref.py`：按关键词1行检索，不翻阅全文
- **代码模板库**：预构建函数代替 LLM 逐行生成代码
### 🧩 代码模板自动积累
- 运行中任何首次生成的代码自动函数化入库
- 玩家新交互需求（如"把火把扔进油坑"）自动生成功能函数
- 代码库随每局游戏持续增长，响应速度越来越快
## 文件说明
### 核心运行文件
| 文件 | 说明 |
|------|------|
| `DM_RULES.md` | 核心规则，19条规则按6层组织 + P0-P5优先级 |
| `DM_RULES_INDEX.md` | 层级索引，含关键词速查列和规则检索提示 |
| `DM_TEMPLATES.md` | 展示模板：剧情整理、房间布局、战斗态势表、角色卡、任务清单、法术展示 |
| `DM_MAP_SYS.md` | 地图生成系统：Excel地图 + emoji标记 + 坐标查询 |
| `CHAR_CREATION.md` | 对话式角色创建的7阶段流程 |
| `MODULE_ARC.md` | 模组剧情框架通用模板 |
| `MODULE_INDEX.md` | 模组章节索引（指针格式，引用场景索引） |
| `SOUL.md` / `IDENTITY.md` | DM 人格定义文件 |
| `DM_DEV_GUIDE.md` | 城主开发规则（8条开发规则，包含版本发布约束） |
### code/ 代码模板库
运行时所有计算、格式化、文件操作**强制优先调用**以下预构建函数：
| 分类 | 目录 | 核心函数 |
|------|------|---------|
| 🎲 骰子 | `code/dice/rolls.py` | `roll_d20()` / `rolling("3d6+2")` / `roll_stat()` |
| ⚔️ 战斗 | `code/combat/display.py` | `build_combat_table()` 先攻表 |
| | `code/combat/resolve.py` | `check_hit()` 命中 / `calc_damage()` 伤害 |
| | `code/combat/checks.py` | `resolve_skill_check()` / `check_hit_v2()` / `resolve_save_check()` 检定展示 |
| | `code/combat/state.py` | `new_combat()`→`advance_turn()`→`get_combat_table()` 战斗持久化 |
| | `code/combat/formulas.py` | `full_attack_sequence()` / `save_check_text()` 公式模板 |
| 💾 存档 | `code/save/io.py` | `list_saves()` / `load_save()` / `write_save()` / `write_save_with_summary()` |
| | `code/save/templates.py` | `new_save_template()` 预定义存档结构（含 plotSummary 字段） |
| 📦 模组 | `code/module/scanner.py` | `scan_modules()` / `read_chapter()` 自动发现章节文件 |
| | `code/module/init.py` | `init_module(module_name)` 通用模组初始化（零硬编码） |
| | `code/module/scene_index.py` | `build_scene_index()` / `load_scene_by_index()` / `set_current_scene()` 场景懒加载 |
| | `code/module/cache.py` | `load_chapter_cache()` 章节预加载缓存 |
| | `code/module/builder.py` | `build_chapter_content()` 通用章节内容构建 |
| 👥 角色 | `code/party/live.py` | `get_character()` / `update_party()` / `find_item_in_party()` |
| | `code/party/xp.py` | `calc_combat_xp()` / `calc_noncombat_xp()` |
| 📋 状态 | `code/state/world.py` | `load_world_state()` / `update_faction()` / `update_quest()` / `update_npc_status()` / `get_world_summary()` |
| 📝 摘要 | `code/summary/generate.py` | `generate_plot_summary()` / `save_summary()` / `load_summary()` / `update_summary()` |
| 🔍 规则 | `code/rule/retriever.py` | `retrieve_by_keyword(keyword)` / `load_rules_by_keywords()` 关键词→规则文本 |
| 📋 速查 | `code/quickref.py` | `get_rule()` / `search_rules()` / `get_red_lines()` |
完整函数索引见 `code/CODE_LIBRARY.md`。
## 场景描述格式标准
运行时城主使用以下标记格式描述场景：
- `[交互物]` — 可互动的物体/位置
- `【NPC】` — 非玩家角色
- `"对话"` — 引号内为NPC对话
## 升级与存档要求
- **升级时**：完整记录角色全部属性、技能、专长、戏法、法术、装备、职业特性
- **存档时**：保存完整的角色状态 + 任务状态，同时自动生成剧情摘要
- **会话启动**：优先加载 `plot_summary.json`（100-300 tokens）替代完整聊天历史
- 后续升级基于前一次完整记录递增，不从零重建
## 规则分层维护约束
**所有新增规则必须归入层0-5之一**（`DM_DEV_GUIDE.md` 开发规则6）。违反视为结构污染，会被回退。
---
*版本 1.0.12 · 2026-05-23 · 基于2024版D&D 5e规则 · 集成 dnd5e-srd skill · 通用模组架构 · 场景级懒加载*
don't have the plugin yet? install it then click "run inline in claude" again.
by @clawhub