ClawHub

dnd5e-dm-general

Other

通用Dungeon Master AI城主系统。基于2024版D&D 5e规则的智能AI地牢城主程序。支持场景级懒加载、世界状态追踪、剧情摘要、模块化运行。

Install

openclaw skills install dnd-dm-skill

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：

agent:
  name: dnd-dm
  skills:
    - dnd-dm

3. 首次运行

启动后，城主会自动：

  1. 检查 modules/ 目录扫描可用模组
  2. 提供载入存档 / 新开一局 / 查看存档 选项
  3. 如新开一局，输入模组名→init_module() 自动生成模板→进入对话式角色创建

相关技能（Related Skills）

本技能与 dnd5e-srd skill 配合使用：

技能作用配合方式
dnd-dm（本技能）城主行为规则 + 裁决流程 + 展示模板主技能，定义DM如何行动
dnd5e-srdSRD 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.8K12K

日常探索仅需 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.mdDM 人格定义文件
DM_DEV_GUIDE.md城主开发规则（8条开发规则，包含版本发布约束）

code/ 代码模板库

运行时所有计算、格式化、文件操作强制优先调用以下预构建函数：

分类目录核心函数
🎲 骰子code/dice/rolls.pyroll_d20() / rolling("3d6+2") / roll_stat()
⚔️ 战斗code/combat/display.pybuild_combat_table() 先攻表
code/combat/resolve.pycheck_hit() 命中 / calc_damage() 伤害
code/combat/checks.pyresolve_skill_check() / check_hit_v2() / resolve_save_check() 检定展示
code/combat/state.pynew_combat()→advance_turn()→get_combat_table() 战斗持久化
code/combat/formulas.pyfull_attack_sequence() / save_check_text() 公式模板
💾 存档code/save/io.pylist_saves() / load_save() / write_save() / write_save_with_summary()
code/save/templates.pynew_save_template() 预定义存档结构（含 plotSummary 字段）
📦 模组code/module/scanner.pyscan_modules() / read_chapter() 自动发现章节文件
code/module/init.pyinit_module(module_name) 通用模组初始化（零硬编码）
code/module/scene_index.pybuild_scene_index() / load_scene_by_index() / set_current_scene() 场景懒加载
code/module/cache.pyload_chapter_cache() 章节预加载缓存
code/module/builder.pybuild_chapter_content() 通用章节内容构建
👥 角色code/party/live.pyget_character() / update_party() / find_item_in_party()
code/party/xp.pycalc_combat_xp() / calc_noncombat_xp()
📋 状态code/state/world.pyload_world_state() / update_faction() / update_quest() / update_npc_status() / get_world_summary()
📝 摘要code/summary/generate.pygenerate_plot_summary() / save_summary() / load_summary() / update_summary()
🔍 规则code/rule/retriever.pyretrieve_by_keyword(keyword) / load_rules_by_keywords() 关键词→规则文本
📋 速查code/quickref.pyget_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 · 通用模组架构 · 场景级懒加载