shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 其它无需 API Key

dnd5e-dm-general

AI地下城主引擎——基于2024版D&D 5e规则，三层架构（dnd‑engine、dnd‑api、dnd‑dm技能），支持模块化运行、战斗裁决、角色创建与存档管理

person作者: ackileshubclawhub
open_in_new仓库download下载资源包

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 (pip install)            │
│  骰子、战斗、存档、世界状态、模组缓存、SRD 搜索 │
│  ← 纯 Python，零 LLM 依赖，90 项测试覆盖       │
└─────────────────────────────────────────────┘

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

快速开始 — 安装指引

▸ 步骤 1：解压到工作目录

将 dnd-dm-skill-x.x.x.zip 解压到空目录。解压后结构如下：

your-workspace/
├── SKILL.md / _meta.json          ← Skill 元数据
├── CHANGELOG.md                  ← 版本历史
├── references/                   ← 14 个核心引用文件（供 LLM 读取）
│   ├── DM_RULES.md, DM_TEMPLATES.md, DM_MAP_SYS.md
│   ├── DM_DEV_GUIDE.md, CHAR_CREATION.md
│   ├── MODULE_ARC.md, MODULE_INDEX.md, ECHO_ARC.md
│   ├── SOUL.md, IDENTITY.md, AGENTS.md, TOOLS.md, USER.md
│   └── party-sheet.html          ← 角色卡网页（双击可看）
├── code/                         ← [已弃用] 旧代码模板库（兼容保留）
├── items/                        ← 物品模板（至恶护符、炼狱头巾、Blackrazor）
└── __pycache__/                  ← 自动生成

▸ 步骤 2：初始化工作目录

CLI 初始化（推荐）

pip install dnd-engine
dnd-engine init

自动创建：

  • saves/ — 存档目录
  • rules/ — 规则书目录（内含 README.txt 引导）
  • modules/ — 模组目录（内含 README.txt 引导）
  • live_party.json — 角色状态模板

▸ 步骤 3：放入规则书和模组

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

将以下文件放入对应目录：

  • rules/ — 2024版 D&D 三宝书（《玩家手册（2024）》.md、《城主指南（2024）》.md、《怪物图鉴（2025）》.md）
  • modules/ — 想玩的 D&D 模组文件（如《博德之门：坠入阿弗纳斯》.md 等）

▸ 步骤 4：启动 API 服务

dnd-engine server --port auto
# 或 python dnd-engine/api/server.py

--port auto 自动检测端口（优先 8080，被占用则从 8010-8020 选可用端口），端口号写入 _api_port.txt。

▸ 步骤 5：校验环境

在对话中回复 /verify，Agent 自动调用 GET /api/system/verify 校验所有依赖：

  • 引用文件是否完整（14/14）
  • 规则书和模组是否正确放入
  • dnd-engine 是否已安装
  • 工作目录是否有写入权限

校验通过后即可开始游戏。

相关技能

| 技能 | 作用 | 配合方式 | |:----|------|---------| | dnd-dm（本技能） | 城主行为规则 + 三层架构调度 | 主技能，定义 DM 如何行动 | | dnd5e-srd | SRD 5.2.1 RAG 检索 | 战时快速查规则，通过 Python 脚本搜索+展开引用 |

功能概览

🏗️ 三层架构

| 层级 | 名称 | 技术栈 | 核心职责 | |:----:|:-----|:-------|:---------| | LLM 层 | dnd-dm Skill | Markdown + prompt | 叙事、NPC、检定发起、行为红线——不可代码化 | | API 层 | dnd-api | FastAPI（端口自动检测） | 30 个 HTTP 端点 + CLI 命令行工具 | | 引擎层 | dnd-engine | pip 包, Python 3.10+ | 骰子/战斗/存档/世界状态/模组缓存/SRD搜索——纯函数 |

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

📐 规则裁决

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

⚔️ 战斗系统

  • 引擎层：命中/伤害/豁免检定/战斗状态 CRUD——代码化
  • LLM 层：战斗叙事、旁白、态势表渲染
  • 战斗状态持久化到 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 命令行

| 命令 | 功能 | |:-----|:------| | dnd-engine init | 初始化工作目录（创建 saves/ rules/ modules/ live_party.json） | | dnd-engine verify | 校验环境（需 API 运行中） | | dnd-engine server --port auto | 启动 API 服务（自动检测端口） |

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

骰子： | 接口 | 功能 | |:-----|:------| | POST /api/roll | 骰子表达式求值 |

战斗： | 接口 | 功能 | |:-----|:------| | POST /api/combat/check-hit | 命中判定 | | POST /api/combat/calc-damage | 伤害结算 | | POST /api/combat/skill-check | 技能检定（完整公式） | | POST /api/combat/state/* | 战斗状态 CRUD（6 端点） | | POST /api/combat/resolve-round | 一键命中+伤害+状态更新 | | POST /api/combat/roll-initiative | 一键掷先攻+排序 |

队伍： | 接口 | 功能 | |:-----|:------| | POST /api/party/calc-combat-xp | XP 计算 | | POST /api/party/rest | 短休/长休结算 | | GET /api/party/character/{name} | 角色属性查询 | | POST /api/party/level-up | 升级自动结算 | | GET /api/party/live | 实时角色状态 | | POST /api/party/live/rebuild | 从存档重建实时状态 |

存档： | 接口 | 功能 | |:-----|:------| | GET /api/saves/list | 存档列表 | | POST /api/saves/load | 读档 | | POST /api/saves/write | 存档 |

SRD： | 接口 | 功能 | |:-----|:------| | GET /api/srd/search?q= | SRD 全文搜索 | | POST /api/srd/expand | 展开上下文 | | GET /api/srd/files | 查询 SRD 文件列表 | | GET /api/srd/search-in-file | 在指定文件中搜索 |

系统： | 接口 | 功能 | |:-----|:------| | GET /api/system/verify | 预飞校验：引用文件、引擎、权限 | | POST /api/system/init | 自动创建工作目录 | | GET /api/system/port | 查询当前 API 端口 |

世界状态： | 接口 | 功能 | |:-----|:------| | GET /api/state/world | 世界状态 |

🔒 行为红线（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 --> 标记。加载时按层优先级常驻：

| 层 | 名称 | 包含规则 | 常驻时段 | |:--:|:-----|:---------|:---------| | 0 | 全局基石 | 0(会话启动), 0a(模组选择), 0.5(微互动), 10(红线), 18(代码), 19(Token), 21(安装) | 整个会话 | | 1 | 运行时交互 | 1(检定), 1.5(叙事匹配), 2(场景空间), 3(推进), 4(支线), 17(不泄题), 20(回声) | 每次场景 | | 2 | 展示模板 | 2b(地图), 9(信息展示) | 展示信息时 | | 3 | 战斗系统 | 15(回合), 15b(装备) | 战斗回合 | | 4 | 进度与状态 | 5(经验), 7(锚点), 8(章节), 13(存档), 14(存档), 16(实时状态) | 存档/升级 | | 5 | 模组控制 | 12(构建), X(特殊) | 开新局/跨章 |

文件说明

| 文件/目录 | 说明 | |:----------|:------| | references/ | 14 个核心引用文件（规则、模板、开发指南、人格定义、角色卡模板） | | code/ | [已弃用] 旧代码模板库（25 个 .py，兼容保留） | | items/ | 物品模板目录（3 个 .md） | | dnd-engine/ | 引擎层 + API 层全套源码 | | dnd-engine/src/dnd_engine/ | 引擎层 Python 包（dice/combat/party/save/state/module/cli） | | dnd-engine/api/server.py | FastAPI 服务（30 端点，端口自动检测） | | dnd-engine/tests/ | pytest 测试（90 项） | | saves/ | [自动生成] 存档文件 | | rules/ | [自行准备] 2024版三宝书 | | modules/ | [自行准备] D&D 模组文件 | | party-sheet.html | 角色卡网页（双击即看，从 live_party.json 读取） | | live_party.json | [自动生成] 实时角色状态 | | _api_port.txt | [自动生成] API 运行端口 | | _scene_cache_*.json | [自动生成] 场景缓存 |

*版本 1.1.4 · 2026-06-08 · SKILL.md标准化(AgentSkills格式+metadata/os/install), 规则6层重排+layer标记修复, DM_RULES_INDEX.md移除, 安装引导流程完整化(verify+init+CLI) · 三层架构（dnd-engine + dnd-api + dnd-dm Skill）· 基于2024版D&D 5e规则 · 90项测试全部通过 · 支持 Windows / macOS / Linux