Dice!Next

主题

API 参考 ​

Dice!Next 后端提供 REST API，管理面板即基于此构建。本页按功能分组列出当前可用的接口；路由较多，只列路径与用途，具体请求 / 响应字段以实际版本为准（可在管理面板的网络请求中对照）。

基础信息 ​

项目说明
基础地址http://localhost:18088（端口见 server.port，可在网页设置中在线修改）
数据格式JSON，UTF-8
认证管理面板访问密钥（server.api_key）；另可启用 WebUI 登录密码（Cookie 会话，见「认证」一节）

统一响应格式 ​

除特别说明外，接口均返回统一信封：

json
{ "code": 0, "message": "ok", "data": {} }
  • code：0 成功，非 0 失败
  • message：提示信息
  • data：响应数据（失败时为 null 或缺省）

少数接口不走信封：/api/test/message 直接返回结果对象，/api/logs/{id}/export、/api/assets/{name}、图片类接口直接返回文件内容。

认证与运行控制 ​

方法路径说明
GET/api/auth/status是否启用登录密码 / 当前会话状态
POST/api/auth/login · /api/auth/logout登录 / 登出（Cookie 会话）
GET / PUT/api/system/webui-auth登录密码设置
GET / PUT/api/system/server-config运行 IP / 端口（改后需重启生效）
POST/api/system/restart重启后端
GET / PUT/api/system/autostart开机自启（Windows）

系统状态与设置 ​

方法路径说明
GET/api/system/status运行状态
GET/api/system/settings基础设置（host / port / 日志级别等）
GET/api/dashboard/stats仪表盘统计
GET / PUT/api/system/global原版全局设置（响应开关 / 外部请求等）
GET / PUT/api/system/events事件策略（审批 / 退群 / 自动清理等）
GET / PUT/api/system/prefixes指令前缀
GET / PUT/api/system/log-mode原始事件日志开关
GET / PUT/api/system/respond-self自控开关（响应骰娘账号自身消息）
GET / PUT/api/system/logsite日志站上传地址（logsite_url）
GET / PUT/api/system/save-log-images日志图片落地开关
GET / PUT/api/system/nick-wrap用户名包裹符号
GET / PUT/api/system/reply-segment分段发送
GET / PUT/api/system/quote-reply引用气泡回复
GET / PUT/api/system/forward-long长消息合并转发
GET / PUT/api/system/auto-card自动卡面（COC 自动算 HP/SAN/MP）
GET / PUT/api/system/image-host · /api/system/image-send图床 / 发图方式
GET / PUT/api/system/user-group用户群强制
GET / PUT/api/system/friend-clean好友自动清理
GET / PUT/api/system/chat-config聊天持久化（保留期等）
GET/api/roadmap开发计划数据（读 docs/roadmap.md）

通知与审计 ​

方法路径说明
GET / PUT/api/system/notice通知设置（14 类事件逐项勾选、通知窗口、SMTP / Webhook）
POST/api/system/notice/test发送测试通知
GET/api/system/audit审计日志（data/audit/*.jsonl）

适配器 ​

方法路径说明
GET / POST/api/adapters列表 / 新建
PUT / DELETE / PATCH/api/adapters/{id}更新 / 删除 / 局部修改
POST/api/adapters/{id}/test测试连接
POST/api/adapters/{id}/reconnect手动重连（重置退避）

新建示例：

json
POST /api/adapters
{
  "name": "MyQQBot",
  "type": "onebot_v11",
  "connection_mode": "forward_ws",
  "endpoint": "ws://127.0.0.1:3001/",
  "access_token": "",
  "enabled": true
}

骰子规则与掷骰 ​

方法路径说明
GET / PUT/api/dice/rules规则开关与默认骰面
POST/api/dice/roll服务端掷骰（调试用）

指令、文案与 i18n ​

方法路径说明
GET/api/commands指令目录（分类 / 示例 / 回复键）
GET/api/i18n/locales可用语言列表（含自定义语言包）
GET/api/i18n/all全部文案键（含覆盖值与原版键）
PUT/api/templates设置某文案覆盖
DELETE/api/templates/{locale}/{key}重置某文案
GET/api/templates/export · POST /api/templates/import导出 / 导入文案覆盖

自定义回复与因果规则 ​

方法路径说明
GET / POST/api/replies关键词回复列表 / 新建
PUT / DELETE / PATCH/api/replies/{id}更新 / 删除 / 启停
GET / POST/api/causal/rules因果规则（条件 + 动作 + 计数器）列表 / 新建
PUT / DELETE/api/causal/rules/{id} · POST /api/causal/rules/{id}/toggle更新 / 删除 / 启停
POST/api/causal/rules/test因果规则试跑
GET/api/counters · PUT / DELETE /api/counters/{key}计数器查改删
POST/api/causal/cooldowns/clear清空因果冷却

骰娘人格 ​

方法路径说明
GET / POST/api/personas人格列表 / 新建
GET / PUT / DELETE/api/personas/{id}详情 / 更新 / 删除
POST/api/personas/{id}/copy · /api/personas/{id}/activate复制 / 激活
GET / PUT / DELETE/api/personas/{id}/entries人格回复文案条目
GET/api/personas/{id}/export · POST /api/personas/import导出 / 导入
GET/api/personas/active当前激活人格

牌堆 ​

方法路径说明
GET / POST/api/decks牌堆列表 / 操作
PUT / DELETE/api/decks/{id}更新 / 删除记录
GET / PUT/api/decks/file读取 / 写入牌堆文件
DELETE/api/decks/file/{name}删除牌堆文件
POST/api/decks/upload上传牌堆（.json）
POST/api/decks/reload重载牌堆目录

规则与规则包 ​

方法路径说明
GET/api/rules已加载规则系统列表
GET/api/rules/file读取规则文件
POST/api/rules/upload · /api/rules/delete · /api/rules/toggle规则文件上传 / 删除 / 启停
PUT/api/rules/save保存规则文件（规则编辑器）
POST/api/rules/test规则自定义指令试跑
GET/api/rulepacks规则包（bundle）列表
POST/api/rulepacks/upload · /api/rulepacks/toggle · /api/rulepacks/delete规则包 zip 上传 / 启停 / 删除

帮助文档 ​

方法路径说明
GET/api/help统一帮助注册表查询（内置 / 规则包 / 插件三源，分页）
GET/api/help/groups帮助分组
GET/api/help/files自定义帮助文档（helpdoc）文件列表
GET / POST/api/help/file读取 / 保存 helpdoc 文件
DELETE/api/help/file/{name}删除 helpdoc 文件

群组 ​

方法路径说明
GET / POST/api/groups群列表 / 操作
PUT / DELETE/api/groups/{platform}/{group}更新 / 移除群记录
POST/api/groups/{platform}/{group}/action群操作（退群 / 发消息 / 上传日志等）
GET/api/groups/{platform}/{group}/members成员列表
POST/api/groups/{platform}/{group}/member-action成员操作（禁言 / 踢 / 改名片等）
GET / POST/api/groups/{platform}/{group}/messages模拟聊天窗口（读记录 / 发消息）
POST/api/groups/{platform}/{group}/poke戳一戳
POST/api/groups/{platform}/{group}/fetch-history拉取历史消息（NapCat）
GET/api/groups/{platform}/{group}/files群文件列表
GET/api/groups/{platform}/{group}/file-url · /file-download群文件直链 / 代理下载
POST/api/groups/{platform}/{group}/file-upload上传群文件
GET/api/groups/plugins · POST /api/groups/plugins/toggle插件分群启停

玩家与好友 ​

方法路径说明
GET/api/players玩家档案列表
PUT / DELETE/api/players/{platform}/{user}更新 / 删除档案
GET/api/players/{platform}/{user}/detail玩家详情（人物卡 / 设置 / 插件变量全量）
POST…/card-attr · …/card-del人物卡属性改 / 删
POST…/setting玩家设置项
POST…/luavar · …/luacardLua 插件变量 / 卡片数据改删
POST…/delete-friend删除好友
GET/api/friends好友列表（各适配器汇总）

黑白名单与骰主 ​

方法路径说明
GET / POST/api/banlist黑白名单列表 / 添加
DELETE/api/banlist/{rowId}移除
GET / PUT/api/banlist/whitelist-only白名单模式开关
GET / POST/api/masters · DELETE /api/masters/{platform}/{id}骰主管理

定时任务与广播 ​

方法路径说明
GET / POST/api/schedules定时任务列表 / 新建（含 condition / action）
PUT / DELETE/api/schedules/{id}更新 / 删除
GET / POST / DELETE/api/broadcast触发式广播

跑团日志 ​

方法路径说明
GET / POST/api/logs记录列表 / 操作
DELETE/api/logs/{id}删除记录（同步清理缓存图片）
GET/api/logs/{id}/export?format=txt|csv|html导出（txt 与日志站上传内容一致；html 自包含带图）
POST/api/logs/{id}/upload上传日志站（SealDice V1 协议）
GET/api/logs/images/{file} · /api/chat/images/{file}日志 / 聊天缓存图片

扩展：Lua 模组 ​

方法路径说明
GET/api/mod/lua模组列表（含指令触发词）
POST/api/mod/lua/upload上传（zip 目录型 mod 或单文件 .lua）
POST/api/mod/lua/toggle · /api/mod/lua/delete · /api/mod/lua/reload启停 / 删除 / 重载
POST/api/mods/uploadLua mod 上传（另一入口，行为同上）

扩展：JS 插件 ​

方法路径说明
GET/api/plugins/js插件列表（元数据 / 启用状态 / 同名去重信息）
POST/api/plugins/js/upload · /toggle · /delete · /reload上传 / 启停 / 删除 / 重载
POST/api/plugins/js/config插件配置项表单读写
POST/api/plugins/js/check-update · /update按 @updateUrl 检测 / 执行更新
GET/api/plugins/js/storage · POST /storage/clear插件持久化存储查看 / 清空

AI ​

方法路径说明
GET / PUT/api/system/aiAI 全套设置（网关 / 模型 / 润色 / 翻译 / 对话 / 记忆 / 工具 / NPC / 视觉）
GET / POST / DELETE/api/system/ai/memoryAI 记忆（摘要 / 长期事实）查看与管理
POST/api/system/ai/test模型连通性测试

资源与数据迁移 ​

方法路径说明
POST/api/assets/upload · GET /api/assets/{name}图片资源
POST/api/legacy/import原版 V2 数据迁移（请求体 { "dir": "路径" }，导入前自动备份数据库）

测试接口 ​

POST /api/test/message
{ "text": ".r 3d6", "platform": "onebot_v11", "messageType": "group",
  "nickname": "希亚", "userId": "123", "groupId": "456", "locale": "zh-Hans" }

该接口是「测试台」页的后端，直接返回 { "reply": "...", "matched": true, "segments": [...] }（不走统一信封），走与真实消息一致的完整管线（内置指令 → JS 插件 → Lua 模组 → 因果规则 → 自定义回复 → AI），可不连接平台直接测试。可选字段：rawContent（带 CQ 码测识图）、selfId / atList（多骰娘定向）、role / card（群名片注入）。

TIP

以上为接口概览；字段细节以实际版本为准。所有 /api/* 请求都需要携带访问密钥（或已登录的 Cookie 会话）。

基于 AGPLv3 协议发布

Copyright © 2025-2026 Dice!Next