D&D 5e AI 地下城主引擎 — 三层架构
基于 2024版 D&D 5e 规则 的 AI 地下城主系统。纯对话交互，不需要专用客户端，任何 IM 软件即可运行。
三层架构概览
┌─────────────────────────────────────────────┐
│ LLM 层：dnd-dm Skill (OpenClaw) │
│ 叙事生成、NPC 对话、场景描述、行为规则 │
│ ← prompt 驱动，保持 LLM 核心优势 │
├─────────────────────────────────────────────┤
│ API 层：dnd-api (FastAPI :8081) │
│ 22 个 HTTP 端点，标准化输入输出 │
│ ← 任何平台（Discord/Foundry/Web）均可调用 │
├─────────────────────────────────────────────┤
│ 引擎层：dnd-engine (pip install dnd-engine) │
│ 骰子、战斗、存档、世界状态、模组缓存、SRD 搜索 │
│ ← 纯 Python，零 LLM 依赖，90 项测试覆盖 │
└─────────────────────────────────────────────┘
核心原则：上层依赖下层，下层不依赖上层。LLM 层只管叙事 + 调用引擎函数，不自行计算或拼数据。
快速开始
1. 部署到工作目录
复制 DMskill/references/ + DMskill/code/ 到工作目录，另需部署 dnd-engine/ 目录：
your-workspace/
├── references/ ← 核心引用文件 (13个)
│ ├── DM_RULES.md ← 运行规则（6层分层架构，~43KB）
│ ├── DM_RULES_INDEX.md ← 层级索引（常驻参考）
│ ├── DM_TEMPLATES.md ← 信息展示模板（~19KB）
│ ├── DM_MAP_SYS.md ← 地图生成系统
│ ├── DM_DEV_GUIDE.md ← 开发规则（含三层架构规则9）
│ ├── CHAR_CREATION.md ← 角色创建流程（7阶段）
│ ├── MODULE_ARC.md ← 模组剧情框架
│ ├── MODULE_INDEX.md ← 模组关键信息索引
│ ├── ECHO_ARC.md ← 回声映射系统
│ ├── SOUL.md / IDENTITY.md ← DM 人格定义
│ ├── AGENTS.md ← Workspace 配置
│ └── USER.md / TOOLS.md ← 用户信息
├── code/ ← [已弃用] 旧代码模板库（兼容保留）
├── dnd-engine/ ← [新增] 三层架构引擎层
│ ├── src/dnd_engine/ ← Python 包源码
│ ├── api/server.py ← FastAPI 服务
│ └── tests/ ← pytest 测试
├── items/ ← [新增] 物品模板目录
├── srd/ ← SRD 5.2.1 参考文档
│ ├── scripts/ ← Python 搜索脚本
│ └── references/ ← 20 个 SRD 参考文件
├── rules/ ← [自行准备] 2024版三宝书
├── modules/ ← [自行准备] D&D 模组文件
├── saves/ ← [自动生成] 存档目录
├── live_party.json ← [自动生成] 实时角色状态
└── _scene_cache_*.json ← [自动生成] 场景缓存
2. 安装 dnd-engine
pip install dnd-engine
# 或本地开发安装
pip install -e dnd-engine/
3. 启动 dnd-api（可选）
python dnd-engine/api/server.py
# → http://127.0.0.1:8081/docs (Swagger UI)
4. 配置技能
# agents.yaml
agent:
name: dnd-dm
skills:
- dnd-dm
相关技能（Related Skills）
| 技能 | 作用 | 配合方式 |
|---|---|---|
dnd-dm（本技能） |
城主行为规则 + 三层架构调度 | 主技能，定义 DM 如何行动 |
dnd5e-srd |
SRD 5.2.1 RAG 检索 | 战时快速查规则，通过 Python 脚本搜索+展开引用 |
功能概览
🏗️ 三层架构（v1.1.0）
| 层级 | 名称 | 技术栈 | 核心职责 |
|---|---|---|---|
| LLM 层 | dnd-dm Skill | Markdown + prompt | 叙事、NPC、检定发起、行为红线——不可代码化 |
| API 层 | dnd-api | FastAPI :8081 | 22 个 HTTP 端点，包一引擎层供外部平台调用 |
| 引擎层 | 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不重投，公平透明
⚔️ 战斗系统
- 引擎层：命中/伤害/豁免检定/战斗状态 CRUD——代码化
- LLM 层：战斗叙事、旁白、态势表渲染
- 战斗状态持久化到
combat_state.json
📋 信息展示
- 渐进式探索引导（§9.2）：幕前自然语言暗示 + 幕后
_scene_cache_*.json追踪房间 - 检定结果直接输出
checks.py的detail_lines数组，格式由代码保证 - 任务清单、角色卡、法术展示——标准模板
🧙 角色创建
- 7阶段对话式创建，属性 roll_stat() 由引擎层执行
💾 存档系统（引擎层）
dnd_engine.save.io：write_save()/load_save()/list_saves()- 场景缓存自动嵌入存档（
scene_cache.py） - 模板工厂：
make_character_template()/make_save_template()/make_quest_template()
🌐 API 接口（dnd-api）
| 接口 | 功能 |
|---|---|
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/party/calc-combat-xp |
XP 计算 |
GET /api/saves/list |
存档列表 |
POST /api/saves/load |
读档 |
POST /api/saves/write |
存档 |
GET /api/srd/search?q= |
SRD 全文搜索 |
POST /api/srd/expand |
展开上下文 |
GET /api/state/world |
世界状态 |
🔒 行为红线（15条）
- 禁止偏离模组、禁止放水、禁止混用世界观
- 规则锁定（2024版 > 旧版）、自然1不重投
- 禁止 LLM 自行计算 AC/DC/检定格式——必须调引擎层
文件说明
| 文件 | 说明 |
|---|---|
references/ |
13 个核心引用文件（规则、模板、开发指南、人格） |
dnd-engine/ |
引擎层 + API 层全套源码 |
dnd-engine/src/dnd_engine/ |
引擎层 Python 包（dice/combat/party/save/state/module） |
dnd-engine/api/server.py |
FastAPI 服务（22 端点） |
dnd-engine/tests/ |
pytest 测试（90 项） |
items/ |
物品 MD 模板目录 |
srd/ |
SRD 5.2.1 参考文档 + 搜索脚本 |
saves/ |
自动生成的存档文件 |
live_party.json |
实时角色状态 |
_scene_cache_*.json |
场景缓存（自动生成/自动清理） |
版本 1.1.2 · 2026-06-06 · 沉浸修复, API+4, 战斗清理, 角色卡法术格式 · exec→import, 场景缓存按需, resolve-round, 规则重新编号, 上下文优化~10.4Kt · 三层架构（dnd-engine + dnd-api + dnd-dm Skill）· 基于2024版D&D 5e规则 · 90项测试全部通过
