DiceFrame 用户手册

中文 | English

无论你是准备开团的 GM，还是刚加入游戏的玩家，都可以从这里开始。从创建冒险、行动和掷骰，到使用群聊 Bot、更新程序，常用操作都整理在下面；代码和开发相关内容请查看对应的技术文档。

页面和设置入口

在管理 → 设置中，侧栏顶部的搜索可直接定位设置项；手机上的分类目录可收起在搜索框下方。

具体配置行为见 AI 与界面设置。本文按当前主分支编写，旧版本的菜单可能不同。

第一次打开

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

http://localhost:18000

AI 服务商与模型配置（必填，WebUI 界面直接填）

模型 API 是生成冒险、检定判定和叙事的模型接口，直接在 WebUI 配置，不需要编辑任何配置文件：

1. 打开 管理 → 设置 → 模型接口，在“AI 服务商”中添加服务商名称、API 格式（OpenAI 兼容或 Anthropic）、Base URL 和 API Key。
2. 获取服务商的模型目录，或手动加入可用的模型 ID。
3. 打开 管理 → 设置 → 模型配置，从已保存的服务商与模型中选择主模型；需要时再配置两个备用模型，以及 Embedding、TTS、ASR 和生图模型。
4. 保存后使用相应的“测试连接”按钮确认服务可用。

同一服务商的地址和密钥只需配置一次，主模型、备用模型、向量、语音和生图等能力都可以复用。当前版本只使用已保存的服务商与能力引用；旧直填连接字段和 AI 环境变量不再生效，也不会自动转换，升级后需要手动添加服务商并分配能力。服务商缺失或被删除时，对应能力保持未配置，不会恢复旧密钥。浏览器/系统音色与 Edge TTS 无需服务商，本地服务商的密钥可以留空。

长期记忆（向量记忆）配置（可选）

DiceFrame 会把已确认的剧情要点沉淀为长期记忆，并在后续生成时按语义召回。默认仅做关键词匹配；配置向量记忆后改为语义召回，长团或信息量大的剧本命中更准。向量记忆不是必填项，不配置也能正常跑团。

分两步配置：先在管理 → 设置 → 模型接口保存 Embedding 服务的地址、密钥和模型目录；再到管理 → 设置 → 模型配置启用向量记忆，选择该服务商和模型，按需设置最大输入，测试向量连接后保存。

推荐一：本地部署（最省心，默认模型即为此方案）

用 Ollama 跑向量模型，数据不出本机，无需申请任何服务商密钥：

ollama pull nomic-embed-text

在管理 → 设置 → 模型接口添加服务商，Base URL 填 http://127.0.0.1:11434，API Key 留空，加入模型 nomic-embed-text，然后在模型配置的向量记忆卡片中选择它。Ollama 默认监听 11434 端口，DiceFrame 使用其原生接口。也可以执行 ollama pull bge-m3，再把该模型加入服务商目录。Docker 部署时，服务商地址使用 http://host.docker.internal:11434（或可达的宿主机地址），因为容器内的 127.0.0.1 指容器自身。

推荐二：在线服务（备选）

使用在线 Embedding 服务时，在“模型接口”保存地址与密钥，再在“模型配置”选择服务商支持的向量模型。例如硅基流动服务商可以使用 Base URL https://api.siliconflow.cn/v1、模型 BAAI/bge-m3，以该服务实际可用情况为准。这只是配置示例，不代表合作或赞助。

调用失败会在日志中提示，长期记忆会自动降级为关键词匹配，不影响正常游玩。

语音功能（可选）

语音朗读和语音输入都不是开团必需项。浏览器音色、在线或本地语音引擎、音色分配、语音输入和常见问题见《语音功能（可选）》。

开第一局

1. 打开“总览”，点击“创建新冒险”。
2. 选择游戏语言。
3. 选择模板世界、AI 生成世界，或自己填写世界设定。
4. 选择规则和难度。
5. 创建角色，或先让 AI 生成草稿再手动修改。
6. 进入“游玩”。
7. 输入角色行动，例如“我检查墙上的符文”。

DiceFrame 会把玩家行动交给 GM 模型，模型返回叙事和状态标签。系统会解析这些标签，更新 HP、物品、金币、经验、场景等状态。

内容库与冒险包

在内容 → 内容库浏览世界、资料册与冒险。世界提供背景、默认规则和关联资料册，资料册提供人物、地点等详细参考。资料册卡片显示自己的标题，所属世界另行标明。搜索与内容语言筛选可以缩小范围，世界资料按所选世界/本局范围显示资料。

使用现成内容时，进入内容 → 内容包，预览安装影响，处理阻断提示后确认安装，查看完成状态或错误信息，再选择已安装的冒险开局。内容包可同时装载冒险与复用资源，不限于 D&D；冒险必须与已安装的规则运行时兼容，导入文字不会自动增加规则机制。

自备剧本可从内容库工具栏打开导入剧本：

1. 导入 UTF-8 Markdown/TXT、有文字层的 PDF、Foundry Adventure 导出 JSON，或未加密 Fantasy Grounds XML/.mod。扫描 PDF 需先 OCR。
2. 检查抽取的场景、章节、引用和 GM 备注。导入默认仅 GM 可见，需要公开的内容应明确设置。
3. 修正校验错误，或明确把不支持的引用仅保留为文字。“发布为冒险”不可用时，查看页面上的发布检查清单。
4. 校验并发布，再用该冒险创建游戏。

可选的 AI 整理会把草稿发送给已配置的主模型并消耗 Token；确认提示后才开始，支持进度显示与取消，已经完成的调用仍可能计费。检查并采纳结果后再发布。导入不会执行外部模组脚本，作者操作和兼容边界见内容、角色与游玩。

语言和内容

“设置”里的界面语言只影响 WebUI 文案；“创建”里的游戏语言会写入存档，用来约束 GM 叙事、开场、摘要、快捷行动和 AI 生成内容。

世界模板、世界书和内容包有自己的内容语言。创建页会优先列出同语言模板，也会标出其他模板或世界书的内容语言。选择中文世界书时，英文界面仍会显示这本世界书的中文内容；选择英文世界书时，中文界面也不会把原文自动改写成中文。

Content V2 规则使用单一 canonical core <rule_id>.json，语言内容放在 locales/<locale>/<rule_id>.json typed overlay 中。locale 只覆盖显示字段，不能改变机制；旧 <rule_id>_en.json/<rule_id>_ja.json 仅作为 V1 compatibility 输入，不要用于新内容。

回合和行动

单人模式里，提交一条行动后就会自动推进。

多人模式里，每轮每个活跃玩家都可以提交自己的行动。所有活跃玩家都提交后系统会自动推进；未提交的玩家会一直保留等待，不使用倒计时。GM 可以按桌面实际情况手动强制推进。

玩家可以修改本轮行动，但有次数上限。AI 只读取最后一次提交的行动。

多人玩法

GM 创建游戏后，在队伍成员列表底部点击邀请玩家复制邀请链接。玩家直接打开链接，不需要自己提取或填写房间/房主标识。

玩家打开链接后可以：

• 加入当前游戏。
• 创建角色。
• 认领已有角色。
• 在自己的玩家页面提交行动。

GM 从每张成员卡片右侧的⋯ 成员操作打开操作链接、编辑、暂离/回来、AI 托管或踢出，具体选项取决于成员状态。操作链接用于继续操作已有角色，邀请玩家用于新人加入；普通玩家看不到这些管理操作。暂离玩家不再阻塞回合，回来后恢复参与。

队伍操作位于成员列表和规则提示之间；支持休息的规则在这里提供队伍休息入口，GM 可发起投掷，玩家可继续待投掷请求或查看投掷记录。手机从游戏工具 → 队伍进入；左侧的角色状态边缘按钮可重新打开关闭的角色面板。

外网联机

如果玩家和 GM 不在同一个局域网，邀请链接还需要配合内网穿透、虚拟局域网或路由器端口映射工具使用。DiceFrame 不与下面提到的第三方服务存在合作关系，请根据价格、网络环境和隐私政策自行选择。

第三方工具需要连接到 DiceFrame 的本地网页地址：

Windows 便携版或源码运行：http://127.0.0.1:18000
默认 Docker 部署：http://127.0.0.1:9876

如果你修改过 Web 端口，请填写实际能在本机浏览器中打开的地址。隧道程序和 DiceFrame 不在同一台设备或同一个 Docker 容器时，127.0.0.1 通常要改为 DiceFrame 所在设备的局域网地址、容器名或 Docker 网关地址。

SakuraFrp

SakuraFrp 提供 Windows、macOS、Linux、OpenWrt 和 Docker 客户端，并有免费使用方案。具体安装、节点限制、域名和 HTTPS 配置以 SakuraFrp Web 应用穿透指南 为准。

用 TCP 隧道连接 Windows 上的 DiceFrame 时，关键配置是：

隧道类型：TCP
本地 IP：127.0.0.1
本地端口：18000

SakuraFrp 官方要求通过 TCP 隧道转发 HTTP 网页时选择非内地节点。分享前请确认最终地址能从手机流量或其他网络打开，并必须开启其 HTTPS、自动 HTTPS 或免费子域名能力。

最后一步：把外网地址填进 DiceFrame。 隧道跑起来后，在 SakuraFrp 启动器里找到它分配给你的外网访问地址（TCP 隧道是 域名:端口，形如 frp-xxx.natfrp.cloud:12345；开了免费子域名或 HTTPS 则是 https://你的子域名.natfrp.cloud）。复制这个地址，进 DiceFrame“管理 → 设置 → 分享地址 → 分享链接地址”粘进去保存。只有填了它，邀请链接才会指向外网地址，外面的人才能通过链接连进来；不填的话邀请链接默认是 127.0.0.1:18000，只有你自己这台电脑能打开。

Cloudflare Tunnel

Cloudflare Tunnel 可在免费套餐中使用，通过主动建立的隧道把域名指向本地服务，不要求公网 IP，也不需要在路由器上开放入站端口。它更适合已经有域名、希望长期保留固定 HTTPS 地址的 GM。创建正式隧道后，把 Public Hostname 的服务地址指向 http://127.0.0.1:18000；Docker 默认部署则指向实际可访问的 9876 端口。具体步骤见 Cloudflare Tunnel 官方文档。

Cloudflare 快速隧道插件（cloudflare-tunnel）

需 DiceFrame 1.9.12 及以上。

不想配置域名和 Cloudflare 账号时，可以在插件商店安装 Cloudflare 快速隧道 插件，一键生成一个免账号、免域名的 https://xxx.trycloudflare.com 公网地址，并自动写入分享链接。它适合几十分钟到几小时的临时小局；地址会变化，因此不适合需要长期保留同一入口的团。

1. 确认 DiceFrame 版本 ≥ 1.9.12（低于此版本无法安装/运行，商店卡会提示）。
2. 打开“管理 → 插件 → 插件商店”，安装 Cloudflare 快速隧道，并在“已安装插件”中启用。
3. 在“管理 → 插件”打开该插件的“工具”页，在外网接入卡片点击“一键启用”（或开启插件的“随宿主启动自动开隧道”）。
4. 等待约 30~60 秒，卡片会显示公网地址；该地址会自动同步到邀请链接，外部玩家/群聊 Bot 即可通过它访问。
5. 停止隧道后，访问地址恢复为发布前的状态。

注意：

• 快速隧道地址每次启动都会变化（随机域名），重启后链接会更新，旧链接失效。
• Cloudflare 官方当前把 Quick Tunnel 定位为测试/开发功能，不保证 SLA，并说明其不支持 SSE；实际使用中如果实时回合没有继续更新，先刷新页面，仍异常时改用 SakuraFrp、命名 Cloudflare Tunnel 或其他带 HTTPS 的入口。
• 使用前请先在“管理 → 设置 → 访问密码”设置访问密码，避免公网地址裸露。

可选 HTTPS 入口：Tailscale Funnel

Tailscale Funnel 不要求用户购买域名或拥有公网 IP，会提供 *.ts.net 公网 HTTPS 地址，并通过加密隧道访问本机服务。玩家不需要安装 Tailscale。Funnel 当前仍为 beta，存在带宽和端口限制；在中国大陆，不同运营商对 Tailscale 控制面、*.ts.net 和境外中继的可达性可能不同，不能保证所有玩家都能打开。配置方式与限制见 Tailscale Funnel 官方文档。

当前可以先用 Tailscale CLI 把本地 DiceFrame 端口作为 HTTPS Funnel 公开，分享前建议用手机流量测试一次。DiceFrame 后续即使提供一键 Funnel 插件，也不会覆盖你已经填写的 SakuraFrp 或其他外部 HTTPS 地址。

有公网 IP、没有域名

Let’s Encrypt 已支持 IPv4/IPv6 地址证书。有真实公网 IP 且能映射 80/443 时，可以使用支持 IP 地址证书的 ACME 客户端签发受信任证书，再用 Caddy 等本地反向代理把 HTTPS 请求转到 DiceFrame。IP 地址证书只有 160 小时有效期，必须配置全自动续期；不熟悉端口映射和 ACME 时，继续使用提供 HTTPS 的内网穿透会更省事。

无论选择哪一种方式，最后都把外部 HTTPS 地址填入“管理 → 设置 → 分享地址 → 分享链接地址”。DiceFrame 不会因为检测到公网 IP 而自动替换 SakuraFrp、Cloudflare 或其他穿透地址。

对外分享前

• 先在“管理 → 设置 → 访问密码”设置一个不容易猜到的密码。
• 优先分享 HTTPS 地址，避免通过明文 HTTP 传输访问密码和游戏内容。
• 只映射 DiceFrame 的网页端口，不要同时暴露 NAS 管理页、数据库或 data/ 目录。
• 游戏结束后可以关闭隧道；第三方服务的账号、实名、流量和费用由该服务商负责。
• DiceFrame 有基础访问限流，但不能替代专业的抗 DDoS 服务。

掷骰流程

有些行动会直接叙事，有些行动需要检定。

玩家只需自然地描述行动，不需要写“鉴定”或点击掷骰。行动收齐后，GM 的独立裁判阶段会一次读取本轮全部行动，通过 dice_checks 决定谁需要检定、使用哪个现有属性/技能以及目标值。服务端随后只掷一次骰并固定结果，叙事阶段只能遵循该结果。

常见流程是：

1. 玩家提交行动。
2. 单人立即、多人在所有活跃玩家提交后自动推进；GM 也可手动推进。
3. GM 裁判阶段整批决定是否需要检定。
4. 服务端一次性掷骰，页面按行动顺序显示判定卡片。
5. GM 拿固定结果生成后续叙事。

新游戏默认自动揭示骰子。GM 可在GM 工作台 → 规则 → 检定流程 → 骰子揭示调整；已有存档保留记录的选择。CoC 中可消耗幸运的失败仍会暂停，等待对应玩家或 GM 决定；这不会重掷骰。

管理 → 设置 → 游戏位于通用下方，设置新对局的骰子揭示、已支持的孤注一掷、行动建议和叙事偏好等默认值，不会改写已有存档。运行中的对局由 GM 在工作台调整。

角色有可用技能时，技能选择器位于输入框内部右侧、行动按钮上方；提交成功后自动回到自动判断，失败草稿保留选择以便重试。每个玩家可在行动面板标题旁通过建议隐藏或显示本设备的行动建议，自由输入不受影响。

DF Agent

房主的 DF Agent 可读取当前状态、搜索内置帮助并准备改动；写操作需要在应用中审核确认。Agent 使用主模型，可能消耗 Token；普通玩家页面没有房主 Agent。

手机上可折叠任务工作区，给对话留出空间。管理 → 设置 → 通用 → DF Agent可调整显示、找回移位的悬浮球，并设置输出预算（默认每次模型请求 4096 Token）。这不是整项任务的总费用上限，生成工具另有各自的预算。

状态变动怎么看

GM 叙事后，系统会显示“状态变动”。这里记录的是这轮真正写入存档的变化。

常见状态包括：

• HP：受到伤害或治疗。
• 物品：获得、失去或消耗道具。
• 金币：获得、支付或扣除。
• 经验：获得经验、升级。
• 场景：当前位置或当前局势变化。
• 私密感知：只给某个角色看的信息。

如果状态变动和叙事文字不一致，以状态变动为准；叙事文字是描述，状态变动是系统实际记录。

买东西时如何确认

剧情中需要花钱购买物品时，系统会先请付款的玩家确认。确认前不会扣钱，物品也不会放进背包。

多人游戏里，由实际付款的那名玩家确认，其他玩家不需要替他操作。确认时余额足够才会成交；余额不足或选择拒绝，都不会扣钱或获得物品。

群聊 Bot

DiceFrame 可以通过 QQ / NapCat 插件把网页对局接到群聊里。Bot 只通过 Web 服务的 HTTP API 工作，不直接读写存档。

基本流程：

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

绑定成功后，群聊就和当前网页游戏关联起来了。

内置 QQ / NapCat 不需要填写 DiceFrame Bot API Token，宿主会自动生成并注入。使用 MaiBot 等外部桥接时，到“管理 → 设置 → Bot API”复制 DiceFrame 服务地址和 Token，再填写到外部插件；重新生成 Token 后需要同步更新外部插件。

Bot 会跟随当前对局的语言显示帮助、状态、前情、地图、支付和错误提示。中文对局使用下面的中文命令；英文对局可以直接发送 help、join、status、recap、map、pay、advance、away、back 等英文命令。兼容命令 roll 只会说明自动判定流程，不会再次掷骰。

插件商店怎么用

进入“管理 → 插件 → 插件商店”即可查看社区收录的插件。这里是索引，不是源码仓库：插件作者继续维护自己的 GitHub 仓库，DiceFrame 在安装时把最新正式 Release 固定到精确提交。

商店优先从 DiceFrame Hub 读取目录、审核状态、下载统计、点赞、评分和经过清理的 README。Hub 离线时会使用本地缓存或公开索引镜像，不影响本地游玩；插件包始终从作者仓库下载，Hub 不代理包体。浏览公开目录不会创建安装身份；只有安装事件、点赞或评分需要时才创建本机令牌。首次启动需主动确认用户协议与隐私政策；匿名使用统计独立且默认关闭，只有用户主动开启并确认后才发送心跳。之后可在“管理 → 设置 → 安全”中的“DiceFrame Hub 与隐私”中随时关闭或清除身份。心跳只包含 DiceFrame 版本、粗粒度操作系统和时间桶，不包含游戏、角色、插件列表、模型配置、日志或正文。

• “已支持”表示当前版本确实能接入 DiceFrame；“部分支持”表示只有页面写明的那部分功能；“预留”类型现在不能从商店安装。
• “来源已固定”表示安装时会把最新正式 GitHub Release 解析到精确提交，并再次核对插件 ID、版本和权限；它不代表插件代码绝对安全。
• official、verified、community 是来源等级，不是安全保证。尤其是需要启动进程的插件，只安装你信任的作者发布的版本。
• 安装按钮变灰时，查看条目下方的原因。内置插件随 DiceFrame 更新，不从商店单独安装；缺少公开仓库或正式 Release 的条目也不能安装。
• 安装后仍需在“已安装插件”中查看权限、填写插件自身配置并启用。QQ / NapCat 的 DiceFrame Bot Token 仍由宿主自动注入，不需要手填。
• 商店会检测插件新版本并提示，安装或更新都需要用户手动确认；进程型插件只提示更新并要求确认；新增权限或变为进程型时也必须确认。
• 私下分享的插件应使用作者通过打包脚本生成的 .dfplugin 文件，在“本地安装”中选择。手动复制插件目录后可点击“重新扫描本地插件”。
• 聊天展示扩展可以增加群聊命令，或把状态、地图等回复换成新的文字、图片和卡片。扩展临时出错时会继续使用 DiceFrame 自带的展示，不会因此改坏角色状态、骰点或支付结果。

群聊常用命令

下面用 @bot 表示艾特你的 Bot。

@bot 帮助
@bot 加入 角色名
@bot 新建角色
@bot 车卡
@bot AI车卡
@bot 邀请
@bot 前情
@bot 地图
@bot 状态
@bot 感知
@bot 支付
@bot 我检查墙上的符文
@bot 推进
@bot 下一轮
@bot 暂离
@bot 回来

常用说明：

• 加入 角色名：把你的群聊账号和网页里的角色绑定。
• 新建角色 / 车卡：获取建卡入口或建卡提示。
• AI车卡：让 AI 生成角色草稿，确认后再使用。
• 邀请：发送玩家加入链接。
• 前情：查看公开剧情提要和最近回合。
• 地图：查看当前地点和已知地点关系。
• 状态：查看自己的角色摘要。
• 感知：查看只属于自己的私密信息，通常会私聊发送。
• 支付：查看待确认付款，并可确认或拒绝。
• 推进 / 下一轮：GM 或授权账号推进剧情。
• 暂离 / 回来：临时离开或恢复参与。

群聊行动

玩家可以直接在群里艾特 Bot 发送自然语言行动：

@bot 我绕到守卫背后，观察他腰间钥匙的位置

群聊与网页走同一套裁判和自动推进流程。需要检定时由服务端自动掷骰，Bot 直接发送 🎲 角色 · 属性检定 d20=… vs DC … → 成功/失败，随后发送 GM 叙事和状态变动。

私密信息

有些信息只给特定角色看，例如暗门、幻觉、梦境、内心低语、角色独有线索等。

网页左侧会显示角色感知。群聊里可以发送：

@bot 感知

Bot 会尽量私聊发送；如果私聊失败，会提示检查临时会话或好友设置。

更新 DiceFrame

在“管理 → 设置 → 关于”的版本更新区可以检查新版本。不同安装方式的更新方法不同：

• Windows 便携版可以在页面中下载并应用；新版启动失败时会自动回到旧版本。
• 解压运行的源码发布包可以应用更新，成功后按提示手动重启。
• Git 开发目录请使用 git pull。
• 已支持托管更新、且 Python/系统运行时兼容的 Docker，可在管理 → 设置 → 关于应用普通程序更新；候选版本验证失败时恢复旧程序和可读数据。
• 旧 Docker 镜像或基础运行时变化，需要拉取镜像并按原有数据挂载、端口和环境重建容器。Compose 部署在原部署目录依次执行 docker compose pull、docker compose up -d；原先用 docker run 的，继续使用原来的启动参数重建。

升级前备份完整 data/，包括更新器管理的数据与绑定记录。latest 跟随正式版，预览镜像需显式指定版本标签。首次迁入托管更新可能需更换一次镜像；各安装方式、数据保留与回滚行为见应用更新说明。

常见问题

AI 没回复

先检查“管理 → 设置”中的模型接口、模型配置和测试连接。常见原因是 API Key 错误、模型名错误、接口地址不兼容，或网络无法访问模型服务。

检查更新出现 HTTP 403

这表示版本检查使用的匿名请求额度暂时用完，只会影响更新提醒，不影响游戏、存档或模型调用。稍后再检查，或直接到项目 Releases 页面查看即可。

玩家不能行动

可能是角色已死亡、还没有加入本局、当前回合正在推进，或者玩家只是 GM 预览身份。刷新页面前先看页面提示。

Bot 没反应

先确认 WebUI 里的 QQ / NapCat 插件已启用，再确认 NapCat WebSocket 地址、端口和 token 正确。群聊还需要先完成绑定。

群聊里没有推进

多人局可能还在等待其他活跃玩家提交行动。GM 可以发送 @bot 推进 或在网页里强制推进。

状态看起来不对

先刷新游戏详情。如果叙事文字和状态变动冲突，以状态变动为准。仍然异常时，优先保留当前存档，不要删除 data/，方便排查。

升级后自定义世界或规则会丢吗

不会。内置模板随程序发布，运行时会同步到 data/templates/；你创建或由 AI 生成的世界和规则也保存在这里，升级只刷新内置模板，不覆盖用户内容。迁移电脑时请复制整个 data/ 目录。

如果 data/config.json 或 data/secrets.json 损坏，DiceFrame 会把原文件保留为 *.corrupt-时间.json，然后使用安全的空配置启动。请不要公开这些损坏副本，其中仍可能包含 API Key 或访问口令。

可以公开存档或群聊记录吗

不建议。data/ 里可能包含 API Key、访问口令、真实群号、私密消息和完整跑团记录。发布到 GitHub 前不要提交 data/、.env、日志和缓存。