DiceFrameOPEN-SOURCE AI TRPG
EN获取 DiceFrame

DICEFRAME · TRPG HELP CENTER

DiceFrame 使用与部署文档

从第一次启动 AI 跑团，到 DND / COC 规则设置、Docker / NAS 部署、版本更新与插件开发，都可以在这里找到说明。

SOURCE ONLINEGitHub / main
docs / README_zh-CN.md

项目总览

功能概览、快速开始、数据与项目结构

GitHub 原文 ↗
文档来源diceframe/diceframe@main
本页目录17

DiceFrame Logo

DiceFrame

English | 中文

GitHub Stars GitHub Release License

DiceFrame WebUI preview

官方网站

DiceFrame 是一个可以自己部署的 AI 跑团引擎，支持 D&D / CoC / 自定义规则与多人 WebUI。

它把 Web 桌面、角色卡、世界书、骰子、状态变动、剧情日志和群聊 Bot 接到同一个游戏状态里。玩家用自然语言说“我想做什么”，系统负责把这句话交给 GM 模型、处理骰子与状态变化，并把结果同步给网页或群聊里的其他玩家。

这个项目适合几种场景：

  • 一个人试跑世界观，看看一个设定能不能玩起来。
  • 小团在浏览器里联机，由一个人当 GM 管理入口和节奏。
  • 群聊里跑团，玩家用 @bot 提交行动、查状态；需要检定时系统自动判断并掷骰。
  • 自己改规则、世界书和角色模板，做一套私人跑团工具。

当前版本仍处于早期发布阶段。功能已经能跑，但接口、存档结构和文档还会继续整理。

交流与反馈

问题反馈和改进建议请优先通过 GitHub Issues 提交，代码贡献欢迎发起 PR。提交前请阅读 贡献指南。

QQ 交流群：1060613588

功能概览

  • WebUI：顶部以“总览 / 游玩 / 角色 / 内容 / 管理”组织主要工作区；内容区包含内容库、世界资料、内容包和规则，管理区包含记忆、日志、插件和设置。世界画廊、冒险工作台和剧本导入从内容库进入。
  • 官方维护英语和简体中文界面及文档；日语、德语、俄语为社区翻译，缺失内容回退英文。
  • 多人桌：邀请链接、玩家等待、暂离/回来、GM 强制推进、SSE 实时同步；实验性玩家直连可通过一次性链接码建立 WebRTC 对局。
  • 骰子与状态：D&D 5e 轻量规则、自定义 d20、CoC 7e 轻量 d100 与无骰叙事分层处理；支持规则声明的优势/劣势、CoC 奖惩骰，以及 HP、理智、金币、物品、经验、死亡/复活等状态标签。
  • 世界书：NPC、地点、物品、事件、谜题、势力等条目，按关键词注入上下文。
  • 记忆与摘要：长团会压缩历史，也可以启用 embedding 做语义召回。
  • AI 生成：世界、规则、角色、世界书条目都可以由模型辅助生成。
  • 语音朗读：系统音色零配置回退，也可连接在线或本地 OpenAI 兼容 TTS、GPT-SoVITS；服务已有的 voice ID 和个人参考 WAV 可直接使用，商店音色预设完全可选。
  • 系统生图：在模型路由中配置 OpenAI 兼容图像模型，为对话场景、角色头像、道具和地图背景生成图片；重大场景切换可在后台自动生成场景图。
  • QQ / NapCat 插件：群聊绑定网页对局，支持行动、桌外询问、状态、前情、地图、感知、支付；检定由系统自动判断并掷骰。
  • 应用更新：便携版和托管 Docker 支持旁路安装、健康检查和失败回滚；源码、Git 与基础镜像按安装方式给出安全更新流程。
  • Docker：提供 Linux/Docker 部署入口，运行数据挂载到 data/。
  • 内容库集中浏览世界、资料册和冒险，支持本局资料册选择、来源追踪及房主私密操作恢复。
  • 剧本/PDF/Foundry/Fantasy Grounds 导入先预览校验，再发布；可选 AI 整理有进度、取消和 token 提示。
  • 可复用角色卡、本局角色、AI 托管席位、检定策略、CoC 孤注一掷，以及已支持的 D&D 2024 法术和触发式至圣斩。
  • 房主 DF Agent 提供文档检索、草稿和经审核确认的应用操作。

快速开始

Windows 便携版

普通 Windows 用户建议直接下载便携版：

前往 Releases 下载最新版

下载最新的 DiceFrame-vX.Y.Z-windows-portable.zip，解压后运行 DiceFrame.exe。首次打开后，先进入“管理 → 设置 → 模型接口”，在“AI 服务商”中添加服务商名称、API 格式、Base URL、API Key 和可用模型，再进入“管理 → 设置 → 模型配置”为主模型、备用模型、向量记忆、TTS、ASR 和生图选择实际使用的服务商与模型。向量记忆的开关、输入上限和连接测试也集中在该页的向量模型卡片中。

Windows 便携版可以在“管理 → 设置 → 关于”的版本更新区检查并应用更新。

Docker 运行

已安装 Docker 的用户可以直接拉取镜像：

bash
docker pull ghcr.io/diceframe/diceframe:latest
docker run -d --name diceframe -p 9876:9876 -v ./data:/app/data ghcr.io/diceframe/diceframe:latest

打开：

text
http://localhost:9876

Docker 会把运行数据挂载到当前目录的 data/。详细说明见 DiceFrame 部署说明。

升级到支持托管更新的基线镜像后，普通应用版本可以直接在“管理 → 设置 → 关于”的版本更新区完成；Python 或系统运行时变化仍需拉取新镜像。程序不会挂载或控制 Docker socket。

NAS 用户可以在 Docker 管理界面搜索 diceframe 拉取镜像，或在 Docker Hub 查找。

latest 只跟随正式版。预览版也会发布 Docker 镜像，但不会覆盖 latest；需要体验时请从 GitHub Releases 复制完整预览版本号并显式拉取，例如：

bash
docker pull ghcr.io/diceframe/diceframe:2.3.0-beta.2
# Docker Hub：docker pull falconku/diceframe:2.3.0-beta.2

如果原先使用 Compose 部署，更新命令必须在存放 docker-compose.yml 的部署目录执行：

bash
cd /path/to/diceframe
docker compose pull
docker compose up -d

如果原先使用的是上面的 docker run 命令，则不能在任意目录改用 Compose 更新；请按部署说明拉取新镜像并用原端口、卷和环境变量重新创建容器。出现 no configuration file provided: not found，表示当前目录没有 Compose 配置文件。

从源码运行

源码运行适合开发、调试或自己改代码。需要：

  • Python 3.10 或更高版本
  • Node.js 20.19+，或 22.12+
  • 一个兼容 OpenAI Chat Completions API 的模型服务

可以使用 DeepSeek、硅基流动、OpenAI、Ollama 等服务。只要它提供 OpenAI 兼容接口，就可以在“管理 → 设置 → 模型接口”里配置。

第一次从 GitHub 克隆后，需要先构建前端：

bash
cd frontend-v2
npm ci
npm run build
cd ..

pip install -r requirements.txt
python web_server.py

直接运行时会自动读取项目根目录的 .env；已经在 PowerShell、服务管理器或 Docker 中设置的环境变量优先级更高。

启动后打开终端里显示的地址，默认是：

text
http://localhost:18000

第一次进入“管理 → 设置”，先在“模型接口”的“AI 服务商”中添加连接信息与模型目录，再到“模型配置”分配主模型、备用模型和各项 AI 能力；向量记忆的开关、输入上限和测试与向量模型配置放在一起。

AI 配置契约变更：应用仅支持 ai_providers 与各能力的 *_provider_ref，API Key 使用 ai_provider_key_<id> 保存到敏感配置。旧能力级直填地址、密钥、API 格式及 TRPG_LLM_*、TRPG_EMBEDDING_*、TRPG_TTS_*、TRPG_ASR_*、TRPG_IMAGEGEN_* 环境入口不再启用，也不会自动迁移或创建服务商；旧配置更新请求返回 HTTP 400 unsupported AI config fields。请在设置页手动添加服务商并分配用途。

主备模型、向量、生图及 OpenAI-compatible/GPT-SoVITS 语音只使用对应服务商引用；缺失或未知引用不会恢复旧地址和密钥，相关远程能力保持未配置。浏览器语音、edge-tts 和已禁用 ASR 无需服务商引用，本地服务商允许空 API Key。服务商连接测试可使用临时地址与密钥，但不会回退到旧能力级配置。

Windows 下也可以双击 web_ui.bat 启动；它会检查依赖，并在缺少前端构建产物时自动构建。

独立部署 Web 前端

如果希望让浏览器前端固定使用 HTTPS、而后端继续运行在 NAS、家用电脑或服务器上，可以把 WebUI 单独构建并部署到 Cloudflare Pages 等静态托管：

bash
cd frontend-v2
npm ci
npm run build:standalone

完整的 Cloudflare Pages 参数、后端 HTTPS、跨域白名单、安全建议与排错步骤见官网的独立部署 WebUI 指南。Windows 便携版、Docker 和服务器自带 WebUI 继续使用默认同源模式，不需要单独配置。

新手玩法、多人流程、群聊命令和状态变动说明见 DiceFrame 用户手册。

移动端 App

DiceFrame 提供独立的 Android 客户端，源码在 diceframe-mobile 仓库，安装包在 Releases 页下载；使用问题、需求与贡献也请前往该仓库。

第一局怎么玩

  1. 打开 WebUI。
  2. 进入“管理 → 设置 → 模型接口”添加连接与模型目录，再到“模型配置”选择主模型。
  3. 回到“总览”，点击“创建新冒险”并选择游戏语言。
  4. 选择模板世界、AI 生成世界，或自己填写世界设定。
  5. 选择规则和难度。
  6. 创建角色，或用 AI 生成一个角色草稿后再手动改。
  7. 进入“游玩”，输入角色行动。
  8. 行动需要检定时，系统会自动判断并只掷一次骰，随后 GM 继续叙事。

多人模式下，GM 创建游戏后复制邀请链接给其他玩家。玩家加入并认领角色后，每轮提交自己的行动；所有活跃玩家都提交后，或 GM 强制推进后，进入下一段叙事。

QQ / NapCat

推荐的群聊方式是内置 QQ / NapCat 插件。

基本流程：

  1. 进入“管理 → 插件”，打开 QQ / NapCat 的插件配置。
  2. 配置 NapCat 的 WebSocket 地址、端口和 token。
  3. 启用 QQ / NapCat 插件。
  4. 在游戏页复制 Bot 绑定命令。
  5. 到群里发送绑定命令，把网页游戏和群聊关联起来。

DiceFrame Bot API Token 由宿主自动生成并注入，内置 QQ / NapCat 无需填写。外部 MaiBot Bridge 等适配器可在“管理 → 设置 → Bot API”复制服务地址和 Token。

Bot 图片卡片需要系统提供中文字体：Windows 与 Docker 镜像（已内置 fonts-noto-cjk）开箱可用；直接在 Linux 主机上运行 python web_server.py 时请自行安装 CJK 字体（如 Debian/Ubuntu 的 fonts-noto-cjk），否则卡片渲染会失败并自动降级为纯文本消息。

Bot 会跟随绑定对局的语言显示帮助和主要操作提示；中文与英文对局都可直接使用对应语言的命令。

群聊里常用命令：

  • @bot 帮助：查看当前群可用指令。
  • @bot 绑定 <game_key> <凭证>：GM 将网页游戏绑定到群聊。
  • @bot 邀请：发送网页加入链接和新玩家教程卡。
  • @bot 新建角色 / @bot 车卡：在群里发送建卡入口。
  • @bot AI车卡：AI 辅助生成角色草稿，私聊确认后发到群里公示。
  • @bot 加入 角色名：认领已有角色。
  • @bot 询问 <问题>：向 KP 进行桌外询问；只使用公开剧情、规则和该角色已知信息，不提交行动、不推进剧情、不触发检定，也不消耗本轮行动。英文对局使用 @bot ask kp <question> 或 @bot ask: <question>；普通 ask the guard ... 仍是角色行动。
  • @bot 前情：查看前情提要和最近回合。
  • @bot 地图：查看当前场景和地点连接。
  • @bot 状态：查看 HP、金币、背包等摘要。
  • @bot 感知：私聊查看角色专属感知。
  • @bot 支付：查看待确认支付列表。
  • @bot 确认支付 / @bot 拒绝支付：处理付款。
  • @bot 推进：GM 强制推进当前回合。
  • @bot 暂离 / @bot 回来：临时下线不阻塞回合。
  • @bot <自然语言行动>：提交角色行动。

DiceFrame 插件商店可以浏览和安装社区插件。插件由作者通过 GitHub Release 发布；安装和更新都需要用户确认，插件申请运行外部进程或扩大权限时会额外提示风险。本地或私下分享的插件也可以通过 .dfplugin 文件安装。

DiceFrame Hub 为插件商店提供审核信息、版本状态和详情。Hub 暂时不可用时，已安装插件和本地游戏不受影响。匿名使用统计默认关闭，可以在“管理 → 设置 → 安全 → DiceFrame Hub 与隐私”中管理。

如果你想开发或发布插件，请阅读插件开发指南和插件索引与审核规则。

文档

内容中文English
内容与游玩内容与游玩Content and play
AI 设置AI 与界面设置AI and interface settings
冒险作者示例灯火港湾Lantern Harbor
翻译维护翻译维护Translation policy
用户手册用户手册User guide
Docker 部署Docker 部署Docker deployment
独立 WebUI独立部署 WebUIStandalone WebUI
应用更新应用更新Application updates
规则与骰子规则与骰子Rules and dice
玩家直连（实验性）玩家直连Player Direct Connect
插件开发插件开发Plugin development
插件索引与审核插件索引与审核Plugin registry
Bot Bridge 核心Bot Bridge 核心Bot Bridge Core

语言维护

官方维护英语和简体中文界面及文档。日语、德语和俄语保留为社区翻译，后续译文由对应语言的志愿维护者负责，贡献一个语言不会让项目负责人承担长期翻译义务。

集中式界面缺失或尚未核对新版英文的译文会回退英文；社区语言可以暂停，同时保留语言 ID、存档和机制。维护状态及贡献流程见翻译维护。

已有数据升级

支持的存档和资料册数据库在载入或启动时自动迁移，沿用 main 拆分后的模块契约，并识别已知的未发布本地存储分支；未知或未来格式明确拒绝。当前存档 schema 47、资料册 schema 12，beta.2 及更早程序不能读取升级后的存档。托管 Docker 保留程序与数据配对，可以恢复上一配对；源码和便携版只回退程序不会还原数据。升级前请停服并备份完整 data/，包含 updater 内的数据副本。

旧直填 AI 地址、密钥等配置不自动转换，需要在设置中添加服务商并分配能力引用。部分旧玩家链接需要重新发席位邀请。已有托管 Docker 在 Python/系统运行时兼容时可直接点更新；候选程序在独立副本迁移，失败时旧启动器能恢复旧程序和可读数据，runtime API 保持 1。真正的基础运行时变化仍需更新镜像。完整步骤见应用更新。

世界、资料册、导入模组、邀请、法术和 DF Agent 的使用方法见内容、角色与游玩。

数据与隐私

运行数据默认放在：

text
data/

这里会包含配置、访问口令、插件运行数据、存档、世界书数据库和记忆数据库。简单说，这里放的是“你的桌子”和“你的记录”。

常见数据位置：

  • data/config.json：普通配置
  • data/secrets.json：API key、token 等敏感配置
  • data/access_token.txt：首次启动时生成的 WebUI 初始口令；忘记密码时可新建 data/reset_access_password.txt 写入新密码并重启
  • data/saves/：游戏存档
  • data/templates/：运行时规则和世界模板；用户自定义内容会保存在这里，升级时不会被内置模板覆盖
  • data/plugins/：插件运行数据
  • data/plugin-packages/：用户安装的插件源码（跨版本保留）
  • data/bot/cards/：群聊图片卡片缓存

请妥善保管这些文件。备份、迁移服务器或发给别人排查问题时，先确认里面没有 API Key、访问口令、真实群号、私人聊天记录或不想公开的存档。

项目结构

text
.
├── web_server.py          # WebUI 服务入口
├── scripts/               # 维护检查和开发调试脚本
├── frontend-v2/           # Vue 3 + TypeScript 前端源码
├── static-v2/             # 前端构建输出入口
├── src/
│   ├── engine/            # 游戏状态、骰子、战斗、剧情追踪
│   ├── commands/          # 回合处理、标签解析、状态应用
│   ├── generation/        # 世界、规则、角色生成
│   ├── lorebook/          # 世界书存储与匹配
│   ├── memory/            # 长期记忆、摘要、embedding
│   ├── rules/             # JSON 规则系统
│   ├── webui/             # HTTP API、routes、services
│   └── bots/bridge_core/  # 通用聊天底座（各平台适配器复用）
├── plugins/               # 内置/示例插件（随版本分发；用户安装的插件在 data/plugin-packages/）
├── prompts/               # GM 系统提示词
├── templates/             # 内置规则和世界模板
└── docs/                  # 双语文档：更新、规则与骰子、玩家直连；插件开发等见 diceframe-content

贡献者

感谢所有提交代码、文档、测试、问题反馈和内容改进的朋友。贡献者由 GitHub 根据提交记录自动统计，详见 Contributors。其中可能包含 CI、发布流程和代码助手等机器人账号；它们保留在自动统计中，但不代表人工开发者名单。

贡献规则和本地验证方式见 CONTRIBUTING.md。

License

本项目采用 GNU Affero General Public License v3.0 授权。

你可以在 AGPL-3.0 的条款下使用、修改和分发本项目。若你分发修改后的版本，或将修改后的版本作为网络服务提供给他人使用，应按 AGPL-3.0 的要求公开相应源码。