D&D 5e AI 地下城主引擎
基于 2024版 D&D 5e 规则 的 AI 地下城主系统。纯对话交互，不需要专用客户端，任何 IM 软件即可运行。
快速开始
1. 部署到工作目录
将本 skill 的 references/ 和 code/ 目录复制到你的 OpenClaw 工作目录根目录：
your-workspace/
├── DM_RULES.md ← DM 运行规则（核心，含规则18 代码优先策略）
├── DM_TEMPLATES.md ← 信息展示模板（9种场景模板）
├── DM_MAP_SYS.md ← 地图生成系统
├── CHAR_CREATION.md ← 角色创建流程（7阶段）
├── MODULE_ARC.md ← 模组剧情框架
├── MODULE_INDEX.md ← 模组关键信息索引
├── DM_DEV_GUIDE.md ← 城主开发规则（冲突处理/自动构建/代码模板库管理）
├── CHANGELOG_DM_v2.md ← 更新日志
├── SOUL.md / IDENTITY.md ← DM 人格定义文件
├── live_party.json ← 实时角色状态（运行中自动维护）
├── code/ ← 代码模板库（运行时优先调用，节省Token）
│ ├── CODE_LIBRARY.md ← 函数索引主目录
│ ├── dice/rolls.py ← 骰子操作
│ ├── combat/ ← 战斗：先攻表/命中/伤害/状态持久化/公式模板
│ ├── save/ ← 存档：读写/自动编号/预定义模板
│ ├── module/ ← 模组：扫描/章节解析/内容缓存
│ ├── party/ ← 角色：状态管理/经验计算
│ └── quickref.py ← 规则速查表
├── rules/ ← [自行准备] 2024版三宝书
│ ├── 玩家手册（2024）.md
│ ├── 城主指南 (2024).md
│ └── 怪物图鉴（2025）.md
├── modules/ ← [自行准备] D&D 模组文件
│ └── 博德之门_ 坠入阿弗纳斯 - Ch.*.md
└── saves/ ← [自动生成] 存档目录
注意：
rules/和modules/目录下的规则书和模组文件受版权保护，需要用户自行准备。
2. 配置技能
在 ~/.config/openclaw/agents.yaml 中配置此 skill：
agent:
name: dnd-dm
skills:
- dnd-dm
3. 首次运行
启动后，城主会自动：
- 检查
saves/中的存档 - 提供载入存档 / 新开一局 / 查看存档 选项
- 如新开一局，进入对话式角色创建
功能概览
🎲 规则裁决
- 严格按 2024版 规则结算（6步检定流程）
- 18种技能检定 + 战斗 + 法术 + 动作经济
- 自然1不重投，公平透明
⚔️ 战斗系统
- 先攻表（表格展示，排序+HP+AC+位置+状态）
- 每轮结束后自动展示更新后的战斗态势表
- 已死亡单位划掉、当前行动者标记
- 战斗状态持久化：
combat_state.json文件跟踪，替代LLM记忆
📋 信息展示
- 4种标准模板：剧情整理 / 房间布局 / 战斗态势 / 地形图
- 任务清单（主线+支线，含状态追踪）
- 实时角色卡查询（单角色 / 队伍总览 / 物品检索）
- 法术展示：含检定方式（🎯🛡️💀）+ 推荐理由
🧙 角色创建
- 7阶段对话式角色创建
- 属性分配、种族、职业、背景、技能、装备、法术选择
- 当前属性自动记录到
live_party.json
💾 存档系统
saves/存档*.json：自动递增编号，不覆盖已有- 每份存档记录时间戳、章节、位置
live_party.json：实时角色状态（每次变更后立即更新）- 存档触发：升级、长休、章节结束、玩家要求、重大决策前
🔒 行为红线（15条）
- 禁止偏离模组、禁止放水、禁止混用世界观
- 规则锁定（2024版 > 旧版）、自然1不重投
- 禁止提前加载后续章节、禁止跳过检定流程
⚡ Token优化体系
- 规则18：运行时强制使用预构建函数，禁止LLM生成代码
- 战斗状态文件
combat_state.json：持久化跟踪回合/HP/效果 - 模组缓存
module_cache.json：章节内容一次读取，按场景/NPC检索 - 公式模板：攻击/伤害/豁免等固定格式字符串，直接填值
- 规则速查
quickref.py：按关键词1行检索，不翻阅全文
🧩 代码模板自动积累
- 运行中任何首次生成的代码自动函数化入库
- 玩家新交互需求（如"把火把扔进油坑"）自动生成功能函数
- 代码库随每局游戏持续增长，响应速度越来越快
文件说明
| 文件 | 说明 |
|---|---|
DM_RULES.md |
核心规则，18条运行规则（含存档/升级/战斗展示/代码模板优先/Token优化） |
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 |
城主开发规则：规则冲突处理、填充内容追踪、模组自动构建、代码模板库管理 |
live_party.json |
实时角色状态 JSON（运行中自动维护） |
CHANGELOG_DM_v2.md |
版本更新日志 |
code/ |
代码模板库（详见下表） |
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/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() |
code/save/templates.py |
new_save_template() 预定义26字段存档 |
|
| 📦 模组 | code/module/scanner.py |
scan_modules() / read_chapter() |
code/module/cache.py |
load_chapter_cache() 章节预加载缓存 |
|
code/module/builder.py |
build_module_structure_files() 结构构建 |
|
| 👥 角色 | code/party/live.py |
get_character() / update_party() / find_item_in_party() |
code/party/xp.py |
calc_combat_xp() / calc_noncombat_xp() |
|
| 📋 速查 | code/quickref.py |
get_rule() / search_rules() / get_red_lines() |
完整函数索引见 code/CODE_LIBRARY.md。
场景描述格式标准
运行时城主使用以下标记格式描述场景：
[交互物]— 可互动的物体/位置【NPC】— 非玩家角色"对话"— 引号内为NPC对话
升级与存档要求
- 升级时：完整记录角色全部属性、技能、专长、戏法、法术、装备、职业特性
- 存档时：保存完整的角色状态 + 任务状态
- 后续升级基于前一次完整记录递增，不从零重建
版本 1.0.8 · 2026-05-22 · 基于2024版D&D 5e规则（老白干，你忠实的仆人）