DiceFrame

一句话定位：中文可自部署 AI 跑团引擎——COC/DND 多规则、WebUI + 多人 + 群聊 Bot、世界书、骰子检定、状态追踪；TRPG_LLM_BASE_URL 直指本地或任意 OpenAI 兼容端点。 类型：自托管 AI 跑团引擎 · 开源 · 许可：AGPL-3.0 · 仓库：diceframe/diceframe

1. 项目概述

DiceFrame 是中文社区「自部署 AI 跑团」方向的最新尝试（15★，2026-08 仍活跃）。目标是做一个像「骰娘 + AI 主持人」一体化的自托管引擎：跑团桌/玩家页/世界书/角色卡/规则模板全在 WebUI 里，LLM 可接云端或本地，还能挂 QQ/NapCat Bot 把 AI 主持人带进群聊。规则内容与引擎分离——规则模板、世界模板作为数据包同步分发。

2. 核心功能

• 多规则支持：COC / DND / 自由酒馆等，规则模板可扩展（启动即同步 22 套规则模板）。
• WebUI 全家桶：跑团桌（games）、玩家页（player）、世界书（lorebook，内置 74 条初始条目）、角色卡、场景图、地图、生成（generation）、SSE 流式、记忆系统（memory）。
• 多人 + Bot：多人游戏房间；全局 Bot API Token（外部桥接用）+ QQ/NapCat 插件配置。
• LLM 灵活接入：TRPG_LLM_API_KEY / TRPG_LLM_BASE_URL / TRPG_LLM_MODEL 三键即可接 KoboldCpp/Ollama/云端；未配时留待 WebUI 设置页。
• TTS：浏览器语音或 OpenAI 兼容 TTS（如 Kokoro-FastAPI 本地）。
• 安全：访问密码（自动生成或固定 Token）、防滥用中间件、插件包大小限制、登录审计。

3. 技术架构

• 后端：Python（aiohttp），依赖极轻——aiohttp + Pillow 两个包（Python 3.10+）。
• 模块化 src/：common_factory（子系统装配）、llm.client（ProviderConfig）、hub_client、plugin_host（插件宿主）、webui（路由/API/SSE/认证）、tts。
• 前端：Vue 3（frontend-v2，Vite 构建 → static-v2/ 由后端直接服务）；后端同时服务 v2 资产与 API。
• 数据：SQLite（lorebook.db 等，data/ 目录）。

4. 本机实测记录（✅ 后端完整运行）

• 依赖安装 2 个包秒装；web_server.py 启动即打印 WebUI 地址与初始访问密码。
• 实测初始化：22 套规则模板 + 14 个世界模板 + 74 条内置世界书 + 全局 Bot API Token 自动生成。
• 配置 TRPG_LLM_BASE_URL=http://127.0.0.1:5002/v1（本地 KoboldCpp）后启动正常（:18000）。
• 卡点：Vue 前端需 npm ci && npm run build，Vite 的 realpath 优化调用 child_process.exec 撞沙箱 spawn 边界——后端与 API 全部验证通过，前端在普通机器上可正常构建（Windows 下双击 web_ui.bat 会检查并自动构建）。

5. 如何运行（复现）

git clone https://github.com/diceframe/diceframe && cd diceframe
# 构建前端（一次）：
cd frontend-v2 && npm ci && npm run build && cd ..
# 后端：
python -m venv .venv && .venv\Scripts\pip install -r requirements.txt
# .env 配置 TRPG_LLM_*（可省略，留待 WebUI 填写）
.venv\Scripts\python web_server.py     # 或 Windows 双击 web_ui.bat
# 打开打印的地址，输入访问密码（data/access_token.txt）

6. 优劣势分析

7. 参考链接

• 仓库：https://github.com/diceframe/diceframe
• 同类中文项目：ZRIC-AI-TRPG-Engine（世界书/NPC 情绪自动更新）、Qiuerjun/storyforge-ai（跑团辅助创作平台）、GA10d/AI-TRPG-Demo（DeepSeek 驱动 COC/VHS）