DM20 Protocol

DM20协议

DM20 Protocol

全面 模型上下文协议 用于管理人工智能辅助的龙与地下城战役的服务器，由 FastMCP 2.9+.

• 对于团体 --一个帮助更有效地开展活动的工具包
• 对于单人玩家 --以AI为DM的完整虚拟D&D体验
• 对于Worldbuilders --创建丰富、互联的游戏世界的工具

状态： 正在积极发展中。看 路线图 接下来是什么。

特性

• 活动管理 --创建多个活动并在多个活动之间切换
• 角色生成器 --从加载的规则手册中自动填充字符（标准阵列、点购买、滚动4d6、手动）。根据规则手册数据自动填充启动法术和正确键入的装备。角色表上记录的创建骰子滚动
• 角色创建向导 --逐步指导或快速构建模式。询问玩家姓名、角色等级、种族、职业、能力得分、技能、装备和法术。创建后的完整性验证确保没有遗漏任何内容
• 升级和进步 --自动HP、类功能、法术槽、ASI/技能升级
• 角色表 --完整的D&D 5e统计数据、库存、施法、死亡拯救、创造历史
• 工作表同步 --双向Markdown↔JSON同步：在Obsidian或任何编辑器中编辑YAML frontmatter，DM批准更改
• D&D超越进口 --从D&D Beyond导入字符（URL或JSON文件）
• 休息与恢复 --长休息，短休息与命中骰子，法术槽管理，死亡拯救
• NPC和地点 --通过关系和联系建设富裕世界
• 任务跟踪 --目标、状态、奖励和分支路径
• 战斗系统 --主动性、回合、攻击/法术解析、主动效果、注意力跟踪、ASCII战术地图、AoE瞄准、遭遇构建器
• 简编包 --将活动内容导出/导入为具有冲突解决（跳过、覆盖、重命名）、选择性筛选和完整备份的便携式JSON包
• 战争的叙事迷雾 --渐进式位置发现（未发现→ 瞥见→ 探索→ 完全映射）、隐藏特征的感官提示、叙述者感知的描述
• 党的知识 --通过来源归因和双向NPC知识共享跟踪党对世界的了解
• 多用户权限 --基于角色的访问（DM、Player、Observer），具有输出过滤、会话协调和私有消息传递功能——单人无开销
• 聚会模式 --多玩家网络中继：玩家通过二维码从手机/平板电脑连接，每个人都有一个个人游戏界面，有叙事提要、角色表和动作输入——所有这些都经过权限系统的过滤。WebSocket实时推送、战斗回合协调、消息回放重连、JSONL队列持久化
• 规则版本选择 --创建活动时，在D&D 2024修订规则和2014经典规则之间进行选择。SRD和5etools数据源均自动加载
• 多源规则手册 --从SRD、Open5e、5etools或自定义JSON加载规则
• PDF规则手册库 --导入和查询您自己的PDF和自制内容
• 双语游戏 --意大利语/英语D&D术语解析（500多个术语）
• 会议笔记 --每场比赛总结、经验值、战利品、出勤率
• 冒险日志 --所有活动事件的可搜索时间线
• 上下文自动刷新 — /dm:refrill 保存会话并提供清除上下文的说明。两层保护：主动DM触发约65%+自动PreCompact挂钩约83.5%
• 骰子和实用程序 --Rolls、XP计算、规则查找
• 86 MCP工具 --完整列表在 用户指南

安装

玩D&D的三个步骤

你不需要事先安装任何东西。一个命令设置一切：

bash  **使用克劳德桌面？** 安装后只需重新启动它——MCP服务器已经配置好了。直接使用MCP工具，而不是斜线命令。

安装程序提供两种模式。 **大多数用户应该选择“用户”** --这是默认设置：

||用户（推荐）|开发人员|
|---|---|---|
| **给谁的** |想要玩D&D的玩家|想要修改代码的贡献者|
| **它安装了什么** |单身 `dm20-protocol` command |完整源代码库|
| **磁盘占用空间** |最小（约50 MB）|完整开发环境（约200+MB）|
| **先决条件** |无（自动安装）|无（自动已安装）|
| **如何更新** |使用以下命令重新运行install命令 `--upgrade` | `git pull && uv sync` |
| **添加语音旁白** |重新运行 `--voice` | `uv sync --extra voice` |

> 跑步 `bash install.sh` 从现有的克隆中？安装程序会自动检测到它并切换到开发人员模式。

**支持的平台：** macOS（苹果硅和英特尔）、Linux（x86_64/arm64）、Windows通过WSL。看 [安装程序详细信息](docs/INSTALLER.md) 为了彻底崩溃。

**想知道引擎盖下发生了什么吗？** 这 [安装指南](docs/INSTALLER.md) 涵盖了整个架构、我们处理的每个边缘案例，以及我们为什么这样构建它。

### 兼容性

此服务器实现了开放 [模型上下文协议](https://modelcontextprotocol.io/) 标准。它与 **任何兼容MCP的客户端** --不仅仅是克劳德。

|平台/客户端|状态|
|---|---|
|macOS+克劳德代码| **已测试** （英特尔和苹果硅）|
|macOS+克劳德桌面| **已测试** （英特尔和苹果硅）|
|Linux+Claude代码|支持，欢迎社区测试|
|Linux+Claude桌面|支持，欢迎社区测试|
|Windows（通过WSL）|受支持，欢迎社区测试|
|Cursor、Windsurf、Cline、VS Code Copilot |支持，欢迎社区测试|
|OpenAI Codex、Gemini CLI、Amazon Q |支持，欢迎社区测试|

> 我们对跨平台支持充满信心（安装程序和服务器都是为此而设计的），但只有在贡献者确认后，我们才能将组合标记为“已测试”。如果你尝试了一种未经测试的组合，并且它有效（或无效），请 [打开一个问题](https://github.com/Polloinfilzato/dm20-protocol/issues) --它对每个人都有帮助。

有关每个客户端的详细设置说明、配置文件位置和特定于平台的注意事项，请参阅 **[MCP客户端设置指南](docs/MCP_CLIENTS.md)**.

### 手动安装

Option A: Install as a tool (simplest — no git clone needed)

需要 [紫外线](https://docs.astral.sh/uv/getting-started/installation/).

uv tool install "dm20-protocol @ git+https://github.com/Polloinfilzato/dm20-protocol.git"

然后添加到MCP客户端的配置文件中（请参阅 [MCP客户端设置指南](docs/MCP_CLIENTS.md) 对于客户端的配置路径）：

{ "mcpServers": { "dm20-protocol": { "command": "dm20-protocol", "env": { "DM20_STORAGE_DIR": "/path/to/your/data" } } } }

> **注：** 有些客户端（如Claude Desktop）不继承您的shell PATH。请改用绝对路径： `"command": "/Users/you/.local/bin/dm20-protocol"` （找到它 `which dm20-protocol`).

在Linux上，如果 `dm20-protocol` 安装后找不到，请运行 `uv tool update-shell` 或添加 `~/.local/bin` 手动添加到PATH。

Option B: Clone the repository (for development)

git clone https://github.com/Polloinfilzato/dm20-protocol.git cd dm20-protocol uv sync

然后添加到MCP客户端的配置文件中（请参阅 [MCP客户端设置指南](docs/MCP_CLIENTS.md) 对于客户端的配置路径）：

{ "mcpServers": { "dm20-protocol": { "command": "uv", "args": ["run", "python", "-m", "dm20_protocol"], "cwd": "/absolute/path/to/dm20-protocol", "env": { "DM20_STORAGE_DIR": "/path/to/your/data" } } } }

> **注：** Claude Desktop不继承您的shell PATH。对两者都使用绝对路径 `command` 和 `cwd`.查找 `uv` 随着 `which uv`.

## 快速开始

配置完MCP客户端后，尝试以下自然语言命令即可开始：

Create a new campaign called "The Lost Kingdom"

Load the D&D 5e rules: load_rulebook source=srd

Create a level 3 High Elf Wizard named Lyra with Standard Array

Create a location called "Silverdale", a peaceful village surrounded by ancient forests

Create an NPC named Marta, an elderly herbalist who lives in Silverdale

Create a quest called "The Missing Amulet" given by Marta

AI将自动使用DM20的工具，不需要特殊的语法。用简单的英语描述你想要什么。加载规则手册后，角色生成器会自动从官方规则中填充HP、熟练度、功能、装备和拼写槽。

有关86个工具和高级用法的完整列表，请参阅 [用户指南](docs/GUIDE.md)。有关完整的示例活动，请参阅 [示例/dnd/](example/dnd/example.md).

## 玩游戏

### Claude Code（推荐——有完整的AI DM经验）

克劳德代码包括斜线命令，可以将克劳德变成一个完整的地牢大师。每个命令都会注入一个详细的DM角色，其中包含特定情况的指令和双代理架构（旁白+仲裁员并行运行）。

/dm:start Curse of Strahd ← start session (once) /dm:action I explore the tavern ← exploration, social, any non-combat action /dm:action I talk to the innkeeper

/dm:combat Wolves burst from the woods! ← starts combat /dm:combat I attack with my longsword ← each combat turn needs /dm:combat /dm:combat I cast Shield as a reaction ← still in combat ← combat ends automatically when enemies fall

/dm:action I search the wolf den ← back to exploration after combat /dm:save ← save and stop

**重要提示：** 使用 `/dm:combat` 为了 **战斗中的每一个动作**，而不仅仅是开始。 `/dm:action` 无法推进战斗回合——它仅用于探索和社交。

### 其他MCP客户端（克劳德桌面、光标等）

没有Claude Code，通过自然语言使用DM20的工具。添加 [推荐系统提示](docs/GUIDE.md#system-prompt-recommendation) 为了获得最佳体验，请访问客户端的系统提示字段——它包括完整的游戏循环、战斗协议和DM行为指南。

AI将根据您的请求自动链接工具。体验很好，但斜线命令提供了更一致的结果，因为它们在每条消息上注入了特定于上下文的指令。

## 可选：更智能的规则手册搜索

默认情况下，当您使用以下内容搜索PDF规则手册时 `ask_books`，系统使用 **关键词匹配** --它会找到包含您键入的确切单词的结果。这对于“火球”或“战斗机”等特定查找非常有效。

启用RAG（检索增强生成）后，系统能够理解 **意义**不仅仅是言语。例如：

|您询问|关键字搜索找到|RAG搜索也找到|
|---|---|---|
|“坦克近战类”|无（没有规则手册包含“坦克”）|战斗机、圣骑士、野蛮人子类|
|“没有魔法的治愈”|同时提到“治愈”和“魔法”的页面|治疗师壮举、草药工具包、命中骰子恢复|
|“偷偷摸摸的远程构建”|最多只能进行部分比赛|盗贼/游侠多类选择，Skulker壮举|

要启用它，请从Claude Code内部运行以下命令：

/dm:install-rag

这将安装ChromaDB（约200 MB），一个完全在您的机器上运行的本地矢量数据库-没有云服务，没有API密钥。命令自动检测您的设置并自动处理平台怪癖。

Manual installation (developer mode only)

uv sync --extra rag

> **注：** RAG在上不可用 **macOS英特尔（x86_64）** 由于缺少ML库支持。没有它，其他一切都能完美运行——关键字搜索可以很好地覆盖大多数用例。

## 可选：语音叙述

默认情况下，DM20仅通过文本叙述。启用语音后，DM使用以下命令实时大声朗读旁白和NPC对话 **文本转语音（TTS）** -不需要云订阅或API密钥。

开 **苹果芯片**，DM20使用一个3层引擎系统，为每个上下文选择最佳引擎。其他平台对所有层都使用Edge TTS：

|级别|使用时| Apple Silicon |其他平台|
|---|---|---|---|
| **速度** |战斗，快速行动| Kokoro-离线| Piper-离线|
| **质量** |DM旁白、NPC对话|Qwen3-TTS--线下|Edge TTS--互联网|
| **后备方案** |如果上述层失败|Edge TTS--互联网|Edge TTS-互联网|

> **首次使用说明（Apple Silicon）：** Qwen3-TTS模型在第一个解说环节从Hugging Face下载了约1.2 GB。这 `--voice` 安装步骤本身只有大约50 MB（软件包）。然后，模型被缓存，永远不会重新下载。

要将语音旁白添加到现有安装中，请执行以下操作：

bash 音频在浏览器中播放，而不是在终端中播放。 跑 /dm:party-mode，打开显示的URL，并让该选项卡继续播放。对于 局域网会话 （所有人坐在同一张桌子上），只有一台设备应该打开音频——将播放器设备上的浏览器选项卡静音，以避免多个扬声器同时播放相同的旁白。

完整的语音设置演练——交互模式、三层引擎细节以及局域网与远程场景——在 用户指南.

Manual installation (developer mode only)

uv sync --extra voice

发展

git clone https://github.com/Polloinfilzato/dm20-protocol.git
cd dm20-protocol
uv sync --group dev

运行测试：

uv run pytest tests/

在本地运行服务器：

uv run python -m dm20_protocol

单人游戏——AI地牢大师

DM20协议包括一个完整的 AI地牢大师 独唱D&D游戏系统。克劳德成为你的DM——讲述世界、角色扮演NPC、运行战斗，并自动跟踪所有游戏状态。

游戏命令

运作原理

该系统使用 双代理架构 其中两个专门的LLM代理在每个玩家动作上并行运行：

• 叙述者 --丰富的场景描述、NPC对话、大气文本
• 仲裁者 --机械决议、掷骰子、规则裁决

A. DM人物 (.claude/dm-persona.md)协调游戏循环：收集上下文，决定发生什么，通过工具执行，更新状态，讲述结果。Python方面 档案管理员 代理在不消耗LLM令牌的情况下处理数据检索和游戏状态跟踪。

模型配置文件 只需一个命令，您就可以交易质量与代币成本。所有配置文件都使用不同努力水平的Opus——中等努力与Sonnet质量相匹配，输出令牌减少约76%：

在会话中期切换 /dm:profile economy 或通过 configure_claudmaster(model_profile="quality")配置文件同时更新Python端配置和Claude Code代理文件。

交互模式 控制DM如何与玩家通信。它们与模型轮廓正交——模式×轮廓的任何组合都是有效的（3×3=9个组合）：

在创建活动时使用 create_campaign(interaction_mode="narrated") 或在会话中期通过以下方式切换 configure_claudmaster(interaction_mode="immersive")默认值为 classic （仅限文本，无额外依赖关系）。非经典模式需要 pip install dm20-protocol[voice].

注： 模型配置文件和努力水平是 克劳德特色.努力参数仅通过Claude API在Anthropic的Opus模型上受支持。如果你使用dm20协议和不同的MCP客户端或LLM后端，那么努力设置将没有效果——系统仍然可以工作，但你不会得到努力提供的质量/成本扩展。CC代理文件更新(.claude/agents/*.md)是克劳德代码特有的。

基于 学术研究 表明多智能体GM优于单智能体方法。基于Claudmaster架构，具有会话持久性、难度扩展性和可配置的叙事风格。

请参阅 玩家指南 如何玩，或者 路线图 接下来是什么。

文档

• 玩家指南 --如何用AI DM玩独奏D&D
• 聚会模式 --多玩家网络中继架构和设置
• 用户指南 --系统提示、工具参考、数据结构、PDF库
• 存储结构 --如何在磁盘上组织活动数据
• 开发指南 -架构、贡献、API详细信息
• 路线图 --实施了什么，下一步是什么
• 更新日志 --版本历史

学分

这个项目始于 游戏大师mcp 通过 乔尔·卡齐米尔，通过MCP为D&D活动管理奠定了初步基础。

此后，该项目已被广泛重写和扩展，使用了66个MCP工具、多源规则手册系统、PDF库、Claudmaster双代理AI DM和全面的测试覆盖率。

许可证

MIT许可证