dsh-dungeon-master 0.5.2 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +7 -2
- package/CHANGELOG_EN.md +7 -2
- package/README.md +200 -198
- package/README_EN.md +200 -198
- package/cordis.patch.yml +32 -32
- package/cordis.yml +112 -112
- package/dist/commands/dnd.js +1 -1
- package/dist/commands/dnd.js.map +1 -1
- package/dist/config.d.ts +2 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +2 -0
- package/dist/config.js.map +1 -1
- package/dist/dnd/battle-image.d.ts +3 -0
- package/dist/dnd/battle-image.d.ts.map +1 -1
- package/dist/dnd/battle-image.js +3 -0
- package/dist/dnd/battle-image.js.map +1 -1
- package/dist/dnd/battlefield.d.ts +6 -0
- package/dist/dnd/battlefield.d.ts.map +1 -1
- package/dist/dnd/battlefield.js +75 -16
- package/dist/dnd/battlefield.js.map +1 -1
- package/dist/dnd/campaign.d.ts +131 -13
- package/dist/dnd/campaign.d.ts.map +1 -1
- package/dist/dnd/campaign.js +399 -71
- package/dist/dnd/campaign.js.map +1 -1
- package/dist/dnd/combat-agent.d.ts +26 -3
- package/dist/dnd/combat-agent.d.ts.map +1 -1
- package/dist/dnd/combat-agent.js +377 -59
- package/dist/dnd/combat-agent.js.map +1 -1
- package/dist/dnd/combat-context.d.ts +68 -2
- package/dist/dnd/combat-context.d.ts.map +1 -1
- package/dist/dnd/combat-context.js +58 -21
- package/dist/dnd/combat-context.js.map +1 -1
- package/dist/dnd/conditions.d.ts +157 -0
- package/dist/dnd/conditions.d.ts.map +1 -0
- package/dist/dnd/conditions.js +703 -0
- package/dist/dnd/conditions.js.map +1 -0
- package/dist/dnd/dice.d.ts +5 -1
- package/dist/dnd/dice.d.ts.map +1 -1
- package/dist/dnd/dice.js +4 -3
- package/dist/dnd/dice.js.map +1 -1
- package/dist/dnd/dnd-service.js +5 -5
- package/dist/dnd/dnd-service.js.map +1 -1
- package/dist/dnd/map-view.d.ts.map +1 -1
- package/dist/dnd/map-view.js +17 -6
- package/dist/dnd/map-view.js.map +1 -1
- package/dist/dnd/movement.d.ts.map +1 -1
- package/dist/dnd/movement.js +9 -4
- package/dist/dnd/movement.js.map +1 -1
- package/dist/dnd/pending-attack.d.ts +23 -13
- package/dist/dnd/pending-attack.d.ts.map +1 -1
- package/dist/dnd/pending-attack.js +198 -27
- package/dist/dnd/pending-attack.js.map +1 -1
- package/dist/dnd/save-effect.d.ts +4 -0
- package/dist/dnd/save-effect.d.ts.map +1 -1
- package/dist/dnd/save-effect.js +43 -6
- package/dist/dnd/save-effect.js.map +1 -1
- package/dist/dnd/spell-links.d.ts +32 -11
- package/dist/dnd/spell-links.d.ts.map +1 -1
- package/dist/dnd/spell-links.js +105 -20
- package/dist/dnd/spell-links.js.map +1 -1
- package/dist/dnd/tool-views.js +4 -4
- package/dist/dnd/tool-views.js.map +1 -1
- package/dist/dnd/tools/character.d.ts.map +1 -1
- package/dist/dnd/tools/character.js +167 -20
- package/dist/dnd/tools/character.js.map +1 -1
- package/dist/dnd/tools/combat.d.ts.map +1 -1
- package/dist/dnd/tools/combat.js +112 -16
- package/dist/dnd/tools/combat.js.map +1 -1
- package/dist/dnd/tools/dice.d.ts.map +1 -1
- package/dist/dnd/tools/dice.js +263 -44
- package/dist/dnd/tools/dice.js.map +1 -1
- package/dist/dnd/tools/saves.d.ts.map +1 -1
- package/dist/dnd/tools/saves.js +23 -6
- package/dist/dnd/tools/saves.js.map +1 -1
- package/dist/dnd/tools/shared.d.ts +2 -0
- package/dist/dnd/tools/shared.d.ts.map +1 -1
- package/dist/dnd/tools/shared.js +144 -34
- package/dist/dnd/tools/shared.js.map +1 -1
- package/dist/dnd/turn-buttons.d.ts +4 -0
- package/dist/dnd/turn-buttons.d.ts.map +1 -1
- package/dist/dnd/turn-buttons.js +47 -23
- package/dist/dnd/turn-buttons.js.map +1 -1
- package/dist/features/button-utils.d.ts +2 -1
- package/dist/features/button-utils.d.ts.map +1 -1
- package/dist/features/button-utils.js.map +1 -1
- package/dist/features/note-judge.d.ts +24 -7
- package/dist/features/note-judge.d.ts.map +1 -1
- package/dist/features/note-judge.js +112 -24
- package/dist/features/note-judge.js.map +1 -1
- package/dist/features/reply-judge.d.ts.map +1 -1
- package/dist/features/reply-judge.js +22 -4
- package/dist/features/reply-judge.js.map +1 -1
- package/dist/gateway/bootstrap.d.ts.map +1 -1
- package/dist/gateway/bootstrap.js +19 -1
- package/dist/gateway/bootstrap.js.map +1 -1
- package/dist/gateway/middleware-setup.d.ts +3 -1
- package/dist/gateway/middleware-setup.d.ts.map +1 -1
- package/dist/gateway/middleware-setup.js +24 -5
- package/dist/gateway/middleware-setup.js.map +1 -1
- package/dist/middleware/reply-decider.d.ts +8 -1
- package/dist/middleware/reply-decider.d.ts.map +1 -1
- package/dist/middleware/reply-decider.js +22 -8
- package/dist/middleware/reply-decider.js.map +1 -1
- package/dist/middleware/serial-merge.d.ts +7 -3
- package/dist/middleware/serial-merge.d.ts.map +1 -1
- package/dist/middleware/serial-merge.js +125 -9
- package/dist/middleware/serial-merge.js.map +1 -1
- package/dist/session/index.d.ts +1 -1
- package/dist/session/index.d.ts.map +1 -1
- package/dist/session/index.js.map +1 -1
- package/dist/session/session-manager.d.ts +11 -2
- package/dist/session/session-manager.d.ts.map +1 -1
- package/dist/session/session-manager.js +108 -11
- package/dist/session/session-manager.js.map +1 -1
- package/dist/session/types.d.ts +7 -0
- package/dist/session/types.d.ts.map +1 -1
- package/dist/setup/bind-routes.d.ts.map +1 -1
- package/dist/setup/bind-routes.js +2 -1
- package/dist/setup/bind-routes.js.map +1 -1
- package/dist/transport/agent-turn.d.ts +7 -3
- package/dist/transport/agent-turn.d.ts.map +1 -1
- package/dist/transport/agent-turn.js +20 -2
- package/dist/transport/agent-turn.js.map +1 -1
- package/dist/transport/events.d.ts +6 -1
- package/dist/transport/events.d.ts.map +1 -1
- package/dist/transport/events.js +1 -0
- package/dist/transport/events.js.map +1 -1
- package/dist/transport/inbound.d.ts +6 -0
- package/dist/transport/inbound.d.ts.map +1 -1
- package/dist/transport/inbound.js +62 -10
- package/dist/transport/inbound.js.map +1 -1
- package/dist/transport/outbound-buffer.d.ts +6 -0
- package/dist/transport/outbound-buffer.d.ts.map +1 -1
- package/dist/transport/outbound-buffer.js +13 -0
- package/dist/transport/outbound-buffer.js.map +1 -1
- package/dist/transport/outbound.d.ts.map +1 -1
- package/dist/transport/outbound.js +95 -21
- package/dist/transport/outbound.js.map +1 -1
- package/dist/transport/turn-steer.d.ts +70 -0
- package/dist/transport/turn-steer.d.ts.map +1 -0
- package/dist/transport/turn-steer.js +206 -0
- package/dist/transport/turn-steer.js.map +1 -0
- package/lib/client.js +10 -0
- package/lib/client.js.map +1 -1
- package/package.json +138 -137
- package/skills/dnd-module-authoring/SKILL.md +91 -0
- package/skills/dnd-module-authoring/guide.md +76 -47
package/CHANGELOG.md
CHANGED
|
@@ -2,14 +2,19 @@
|
|
|
2
2
|
|
|
3
3
|
> [English](./CHANGELOG_EN.md)
|
|
4
4
|
|
|
5
|
-
本文件从产品视角记录 dsh-
|
|
5
|
+
本文件从产品视角记录 `dsh-dungeon-master` 的重要更新,聚焦用户可感知的变化。
|
|
6
6
|
|
|
7
7
|
格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)。
|
|
8
8
|
|
|
9
|
-
## [
|
|
9
|
+
## [0.6.0] - 2026-11-16
|
|
10
10
|
|
|
11
11
|
### 新功能
|
|
12
12
|
|
|
13
|
+
- **D&D 5e 群聊跑团系统(`/dnd` 与 17 个 `dnd_*` 工具)**:支持模组加载(地城与城镇双模式)、角色卡与法术/职业能力表管理、SRD 查询、网格战场寻路与 AOE 覆盖计算、迷雾玩家地图与 Emoji/PNG 战棋地图渲染、剧情账本(Chronicle)与背景钩子、签到开团及快照回滚。
|
|
14
|
+
- **结构化状态引擎与回合账本**:完整支持 PHB 14 种状态、6 级力竭与常见战斗状态(祝福术、护盾信仰、加速术、狂暴、闪避、隐形、专注联动等)的自动优劣势、AC/豁免骰、速度归零、倒地半速自动起身与抗性结算;工具返回自动附带单行「当前回合账本」,所有自动规则均提供 `ignore_state_mods` 逃生阀。
|
|
15
|
+
- **分段反应窗口与精准回滚**:支持命中前(`foe_attacks` / `attacked`)、暴击确认(`enemy_crit`)、受伤后(`damaged`)分段反应询问与一次性服务端授权校验;`dnd_undo` 支持按步骤序号 `steps`、掷骰编号 `#R` 或角色开局站位精准撤销,不误伤开战先攻。
|
|
16
|
+
- **专用战斗子代理、自动备用通道回退与演练沙箱**:开战后可将战斗结算委派给独立子会话模型(主会话锁定为等待视图,战后自动汇总未播报账本与队伍净变化交回主 DM);当主通道遇到 429 配额或连接异常且已启用 `modelFailover` 时自动无缝切至备用通道续接,无备用通道或主备均失败时抑制原始 JSON 刷群并向主 DM 透出原因;`dnd_initiative(rehearsal=true)` 支持梦境/切磋沙箱战后自动还原。
|
|
17
|
+
- **模组制作 Skill(`dnd-module-authoring`)**:内置面向 AI Agent 的模组编写指南与隔离打包规范。
|
|
13
18
|
- **`qqbot_booru_fetch` 搜图工具**:按 tag(如 `shinosawa_hiro rating:general -ai-generated`)在 safebooru 上取一张 `latest`/`random` 的图,自动去重(`media/fanart/seen.json`,发出去的那张由 send-file 回调记为已发)、校验文件头与大小、落地到 `tmp/fanart/yuri-<id>.<ext>` 并返回路径,直接喂给 `qqbot_send_file`。角色新图推送这类定时任务不用再每轮手搓下载脚本。danbooru 本体对这台机器走 Cloudflare 质询(API/cdn 全 403),safebooru 是同一套 tag 语法的镜像且同图同字节,故统一走它。
|
|
14
19
|
- **纳入 DSH 插件管理**:可在 DSH Web 的「插件」页安装、启停 `dsh-dungeon-master`,并在组合包详情页直接调整配置,无需手改 profile 文件。
|
|
15
20
|
- **配置项扩展**:新增群聊未 @ 回复概率、群历史条数、会话闲置超时、主人 openid、文件访问白名单/敏感路径等可编辑项。
|
package/CHANGELOG_EN.md
CHANGED
|
@@ -2,14 +2,19 @@
|
|
|
2
2
|
|
|
3
3
|
> [简体中文](./CHANGELOG.md)
|
|
4
4
|
|
|
5
|
-
This file records significant dsh-
|
|
5
|
+
This file records significant `dsh-dungeon-master` updates from a product perspective, focusing on user-visible changes.
|
|
6
6
|
|
|
7
7
|
The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
|
|
8
8
|
|
|
9
|
-
## [
|
|
9
|
+
## [0.6.0] - 2026-11-16
|
|
10
10
|
|
|
11
11
|
### Added
|
|
12
12
|
|
|
13
|
+
- **D&D 5e AI Dungeon Master (`/dnd` and 17 `dnd_*` tools)**: adventure modules (dungeon & town hub modes), character sheets with unified spell/feature/item kit buttons, SRD lookup, grid battlefield pathfinding & AoE coverage, fog-of-war player maps and PNG/emoji battlemaps, chronicle ledger, backstory hooks, check-in roster, and snapshot undo.
|
|
14
|
+
- **Structured 5e condition engine & turn ledger**: automatic PHB condition, exhaustion (1–6), concentration, and combat state modifiers (advantage/disadvantage, AC/save dice, speed zeroing, prone half-speed stand-up, rage/petrified resistance) with single-line turn ledgers and `ignore_state_mods` escape hatches.
|
|
15
|
+
- **Staged reaction windows & targeted undo**: multi-stage reaction prompts (`foe_attacks`/`attacked`, `enemy_crit`, `damaged`) with one-time server authorization tokens; `dnd_undo` supports `steps`, `#R` roll IDs, and initial placement rollback without wiping combat initiative.
|
|
16
|
+
- **Dedicated combat subagent, automatic channel failover & rehearsal sandbox**: optional isolated combat subagent handoff with automatic post-combat delta/ledger summaries; automatically switches to the `modelFailover` backup route on 429 quota or upstream errors (or hands back cleanly to the main DM with failure reasons while suppressing raw error spam in chat), plus `rehearsal=true` dream/sparring fights that restore pre-combat state on completion.
|
|
17
|
+
- **Module authoring skill (`dnd-module-authoring`)**: bundled agent skill and guide for authoring adventure modules.
|
|
13
18
|
- **DSH plugin management**: install, enable/disable, and configure `dsh-dungeon-master` from the DSH Web Plugins page and the bundle detail form, without hand-editing profile files.
|
|
14
19
|
- **More editable settings**: group reply probability, group history size, session idle timeout, owner openid, and file-access allowlist / sensitive paths.
|
|
15
20
|
- **Automatic sticker collection**: the bot decides — based on how it feels about an image — whether to call `qqbot_save_sticker`; the tool deduplicates by content hash, updates `stickers/index.json`, and injects the new sticker into later turns' catalog, so the fixed persona table no longer needs manual edits.
|
package/README.md
CHANGED
|
@@ -1,198 +1,200 @@
|
|
|
1
|
-
# DSH Dungeon Master
|
|
2
|
-
|
|
3
|
-
**[English](./README_EN.md) | 简体中文**
|
|
4
|
-
|
|
5
|
-
**在 QQ 群里跑 D&D 5e 的 AI 地下城主。** 这是 [tencent-connect/dsh-qqbot](https://github.com/tencent-connect/dsh-qqbot) 的二次开发版本:群里发一句 `/dnd start`,bot 就成了这个群的 DM,骰子、检定、先攻、站位、血量全部由工具结算,模型只负责讲故事。
|
|
6
|
-
|
|
7
|
-
> 安装、扫码绑定、基础配置项、内置命令和整体架构都沿用上游,请看 **[上游 README](https://github.com/tencent-connect/dsh-qqbot#readme)**。本文主要讲跑团,其余新增功能在[文末](#其他功能)简要列出。
|
|
8
|
-
|
|
9
|
-
## 三步开团
|
|
10
|
-
|
|
11
|
-
1. 按[本地运行](#本地运行)装好插件,把 bot 拉进群。
|
|
12
|
-
2. 群里发 `/dnd start`。这条消息带签到按钮,人齐自动开场;有人来不了就点「开始」。
|
|
13
|
-
3. @bot 说清楚自己的角色做什么:「卡厄斯用巨剑砍地精 3」「恩佐潜行到门口听动静」。
|
|
14
|
-
|
|
15
|
-
不用换 preset,也不用开新会话:开团后每回合额外注入「DM 守则 + 精简团况」两段 system prompt,`/dnd end` 后恢复普通聊天。
|
|
16
|
-
|
|
17
|
-
---
|
|
18
|
-
|
|
19
|
-
## 🎲 跑团
|
|
20
|
-
|
|
21
|
-
### 设计原则
|
|
22
|
-
|
|
23
|
-
- **所有裁定都走工具**:骰点、检定、伤害、HP、状态、位置、资源只能通过 `dnd_*` 工具改动,模型不能自己编点数。
|
|
24
|
-
- **机密不给到嘴边**:DM 笔记、暗门只出现在工具结果里(`dnd_*` 的结果永远不在群里展示)。怪物的 AC、HP 和 DC 连例行的工具结果和团况里都不给,只给成败和伤势词(毫发无伤 / 受了点伤 / 伤得不轻 / 摇摇欲坠),要裁定时 DM 用 `dnd_character show` 专门查。
|
|
25
|
-
- **行动只认本人**:PC 绑定玩家 openid,只有本人宣告才能行动。工具还会核对这个人最近确实发过消息,模型照抄 openid 也冒充不了。
|
|
26
|
-
- **严格回合制**:战斗中只有当前回合的角色能主动行动,PC 的回合只有本人能结束。
|
|
27
|
-
- **状态存在档里,不靠模型记**:完整状态是一份 JSON,每回合只往 prompt 里放精简团况。站位、待结算的反应这类要跨压缩保留的东西都写在团况里,不依赖压缩摘要的转述。
|
|
28
|
-
- **判错了能回滚**:每次改动都留快照,可以按步数或按骰子编号撤销。
|
|
29
|
-
|
|
30
|
-
### 玩家命令
|
|
31
|
-
|
|
32
|
-
| 命令 | 说明 |
|
|
33
|
-
|------|------|
|
|
34
|
-
| `/dnd start [模组id]` | 开团(同一模组的旧团接着跑);消息带签到按钮,人齐自动开场 |
|
|
35
|
-
| `/dnd new [模组id] [blank]` | 存档旧团,从头开新团(默认带上旧角色卡,加 `blank` 从零建卡) |
|
|
36
|
-
| `/dnd status` | 玩家视角的团况:血量、资源、先攻顺序,战斗中附你到各人的距离 |
|
|
37
|
-
| `/dnd combat` | 最近一场战斗代理的模型与用量,新输入、缓存读取、缓存写入和输出分别统计 |
|
|
38
|
-
| `/dnd map [battle\|explore]` | 发地图:战斗中是站位图,平时是已探索部分的迷雾地图 |
|
|
39
|
-
| `/dnd checkin` | 再发一次签到按钮 |
|
|
40
|
-
| `/dnd end [摘要]` | 保存交接并暂停,战斗状态保留;也可以直接说「今天先到这」 |
|
|
41
|
-
| `/dnd dungeons` | 列出可用模组 |
|
|
42
|
-
| `/dnd search <词条>` | 查[灰机 D&D wiki](https://dnd.huijiwiki.com/wiki/)(法术、技能、职业、专长、怪物…) |
|
|
43
|
-
| `/dnd spells [职业]` | 职业法术列表 |
|
|
44
|
-
| `/dnd help` | 玩法说明 |
|
|
45
|
-
|
|
46
|
-
### 一场团怎么进行
|
|
47
|
-
|
|
48
|
-
- **说行动**:@bot 并说清楚角色做什么才算行动。闲聊、问规则、「查询状态」都不算,不掷骰也不消耗动作。只能控制自己的角色。
|
|
49
|
-
- **回合按钮**:轮到 PC 时,bot 在 DM 的回复后补一条带按钮的消息。
|
|
50
|
-
- 「结束回合」只有本人点击有效,点击后先攻由工具推进,DM 接着结算怪物回合。
|
|
51
|
-
- 「查看状态」由工具直接回复,不经过模型。
|
|
52
|
-
- 「我的法术」列出点击者自己的法术和法术位,每条带 wiki 链接。
|
|
53
|
-
- 「行动」往自己的输入框里预填角色名。
|
|
54
|
-
- 需要 QQ 开放平台的消息按钮权限;发送失败会在本次运行中自动关闭按钮,退回纯文字推进。
|
|
55
|
-
- **反应窗口**:有人能反应时,攻击只掷骰、先挂成待结算,等本人答复(护盾术、尖刻言语、时间变幻重掷);一直没人应,由 DM 替他跳过。
|
|
56
|
-
- **分头行动**:只有说了要走的人才会移动,其他人留在原地,地图上每个有人的房间各标人数。
|
|
57
|
-
- **回滚**:大家同意的话说「卷回到 xx 之前」,DM 用快照撤销,不会靠改数字硬凑。
|
|
58
|
-
- **收团与续团**:停团时写一份交接(位置、刚刚发生、已定行动、同行与留守、未结事项、下次接续),先攻、站位和待结算反应原样保留,下次 `start` 接着跑。停团后聊团不剧透,DM 先查账本再答。
|
|
59
|
-
|
|
60
|
-
### 独立战斗代理(可选)
|
|
61
|
-
|
|
62
|
-
设置页「跑团 → 独立战斗代理」可将战斗交给另一个模型,默认关闭。主 DM 负责掷先攻和叙述开场,回复结束后自动唤醒子 DM 准备场地图、摆位和当前回合;后续玩家消息及按钮直接交给同一个战斗子会话,主模型不逐条转述。默认路由为 `opencode-go/deepseek-v4.1-flash`、推理 `high`,交接最近 8000 字对话及角色状态与已记录约定,不复制整个主会话。战斗工具仍实时读写原团档;结束后交回最新状态、消耗与新增账本,主 DM 只接续战后剧情。
|
|
63
|
-
|
|
64
|
-
```yaml
|
|
65
|
-
dnd:
|
|
66
|
-
combatAgent:
|
|
67
|
-
enabled: true
|
|
68
|
-
provider: opencode-go
|
|
69
|
-
model: deepseek-v4.1-flash
|
|
70
|
-
reasoningEffort: high
|
|
71
|
-
contextChars: 8000
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
子级只开放战斗所需的 `dnd_*` 工具,没有终端、文件或任意子代理能力,因此无需给群增加终端白名单。插件重组可恢复活跃子会话;启动或运行失败交回主 DM,不重做已落账行动。`/new` 会释放子级。每场用量和交接记录保存在跑团目录的 `combat-runs/`,含 DM 私有资料,不要发给玩家。`/dnd combat` 只展示用量,包含战后主 DM 的一次交接回复,不包含开战前的主会话;金额按实际渠道账单计算。首次测试时同时观察规则错误与回滚次数,不能只比较单次请求价格。
|
|
75
|
-
|
|
76
|
-
启用独立代理时,主 DM 隐藏 `dnd_position`,只加载探索版 `dnd_check` / `dnd_apply` 和仅开战的 `dnd_initiative`;攻击、反应和回合循环参数及完整战斗守则由子 DM 加载。探索检定、陷阱群体豁免、治疗、改卡和资源工具仍保留。子级接管期间主级隐藏全部跑团工具;子级失败或关闭委派时自动恢复主 DM 的完整工具。旧宿主不支持同名工具覆盖时保留完整版本。
|
|
77
|
-
|
|
78
|
-
构建后还需保存一次设置触发 profile 重组,宿主才会加载新代码。
|
|
79
|
-
|
|
80
|
-
开战交接会附上角色的职业等级、属性、技能/专精、豁免、武器基础命中与伤害、法术、被动备注、反应和资源,并携带团档中所有 `ruling` 约定。备注里的能力不会自动成为程序规则:例如现世感知的智力先攻加值,核对后可用 `dnd_character update name=奇塔露 init_bonus=7` 保存**固定总先攻**;灵敏之赐的 `1d8` 仍在开战时通过 `bonus` 另加。修改固定先攻不重写当前先攻表;属性或能力变化时需同步更新。长期约定用 `dnd_chronicle add kind=ruling` 保存。
|
|
81
|
-
|
|
82
|
-
`dnd_check type=save targets=[…]` 一次掷公共伤害、逐人豁免并结算半伤、抗性和失败状态;每项可单独带 `bonus_dice="1d4"`,只给受到祝福的人加骰。普通 `dnd_apply targets=[{name,…}]` 可原子批量伤害、治疗、临时生命和状态;`damage_roll` / `heal_roll` 由工具统一掷一次,每人可覆盖数值或抗性,一次撤销整批回滚。`dnd_character update names=[…]` 可批量改卡。
|
|
83
|
-
|
|
84
|
-
玩家预先授权「最终命中就用至圣斩」时,可传 `dnd_check on_hit={name:"至圣斩",damage:"2d8",damage_type:"光耀",spend:"1环法术位"}`:所有防守反应结束后才扣一次资源,最终未命中不扣;重击翻倍追加骰,武器与追加分别过抗性,再作为同一击扣血。`critical_only=true` 仅用于玩家明确授权「重击才用」。这不是替玩家在掷骰后选资源;同回合多次攻击、跨轮持续伤害和看到命中后再询问选择仍逐次处理。普通 `spend` 仍在掷骰前扣除。
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
|
97
|
-
|
|
98
|
-
| | `
|
|
99
|
-
|
|
|
100
|
-
| | `
|
|
101
|
-
| | `
|
|
102
|
-
|
|
|
103
|
-
| | `
|
|
104
|
-
|
|
|
105
|
-
| | `
|
|
106
|
-
|
|
|
107
|
-
| | `
|
|
108
|
-
| | `
|
|
109
|
-
| | `
|
|
110
|
-
|
|
|
111
|
-
| | `
|
|
112
|
-
| | `
|
|
113
|
-
| | `
|
|
114
|
-
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
-
|
|
123
|
-
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
|
134
|
-
|
|
135
|
-
| `dnd.
|
|
136
|
-
| `dnd.
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
|
147
|
-
|
|
148
|
-
|
|
|
149
|
-
|
|
|
150
|
-
|
|
|
151
|
-
|
|
|
152
|
-
|
|
|
153
|
-
|
|
|
154
|
-
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
-
|
|
163
|
-
-
|
|
164
|
-
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
-
|
|
195
|
-
-
|
|
196
|
-
-
|
|
197
|
-
|
|
198
|
-
[
|
|
1
|
+
# DSH Dungeon Master
|
|
2
|
+
|
|
3
|
+
**[English](./README_EN.md) | 简体中文**
|
|
4
|
+
|
|
5
|
+
**在 QQ 群里跑 D&D 5e 的 AI 地下城主。** 这是 [tencent-connect/dsh-qqbot](https://github.com/tencent-connect/dsh-qqbot) 的二次开发版本:群里发一句 `/dnd start`,bot 就成了这个群的 DM,骰子、检定、先攻、站位、血量全部由工具结算,模型只负责讲故事。
|
|
6
|
+
|
|
7
|
+
> 安装、扫码绑定、基础配置项、内置命令和整体架构都沿用上游,请看 **[上游 README](https://github.com/tencent-connect/dsh-qqbot#readme)**。本文主要讲跑团,其余新增功能在[文末](#其他功能)简要列出。
|
|
8
|
+
|
|
9
|
+
## 三步开团
|
|
10
|
+
|
|
11
|
+
1. 按[本地运行](#本地运行)装好插件,把 bot 拉进群。
|
|
12
|
+
2. 群里发 `/dnd start`。这条消息带签到按钮,人齐自动开场;有人来不了就点「开始」。
|
|
13
|
+
3. @bot 说清楚自己的角色做什么:「卡厄斯用巨剑砍地精 3」「恩佐潜行到门口听动静」。
|
|
14
|
+
|
|
15
|
+
不用换 preset,也不用开新会话:开团后每回合额外注入「DM 守则 + 精简团况」两段 system prompt,`/dnd end` 后恢复普通聊天。
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 🎲 跑团
|
|
20
|
+
|
|
21
|
+
### 设计原则
|
|
22
|
+
|
|
23
|
+
- **所有裁定都走工具**:骰点、检定、伤害、HP、状态、位置、资源只能通过 `dnd_*` 工具改动,模型不能自己编点数。
|
|
24
|
+
- **机密不给到嘴边**:DM 笔记、暗门只出现在工具结果里(`dnd_*` 的结果永远不在群里展示)。怪物的 AC、HP 和 DC 连例行的工具结果和团况里都不给,只给成败和伤势词(毫发无伤 / 受了点伤 / 伤得不轻 / 摇摇欲坠),要裁定时 DM 用 `dnd_character show` 专门查。
|
|
25
|
+
- **行动只认本人**:PC 绑定玩家 openid,只有本人宣告才能行动。工具还会核对这个人最近确实发过消息,模型照抄 openid 也冒充不了。
|
|
26
|
+
- **严格回合制**:战斗中只有当前回合的角色能主动行动,PC 的回合只有本人能结束。
|
|
27
|
+
- **状态存在档里,不靠模型记**:完整状态是一份 JSON,每回合只往 prompt 里放精简团况。站位、待结算的反应这类要跨压缩保留的东西都写在团况里,不依赖压缩摘要的转述。
|
|
28
|
+
- **判错了能回滚**:每次改动都留快照,可以按步数或按骰子编号撤销。
|
|
29
|
+
|
|
30
|
+
### 玩家命令
|
|
31
|
+
|
|
32
|
+
| 命令 | 说明 |
|
|
33
|
+
|------|------|
|
|
34
|
+
| `/dnd start [模组id]` | 开团(同一模组的旧团接着跑);消息带签到按钮,人齐自动开场 |
|
|
35
|
+
| `/dnd new [模组id] [blank]` | 存档旧团,从头开新团(默认带上旧角色卡,加 `blank` 从零建卡) |
|
|
36
|
+
| `/dnd status` | 玩家视角的团况:血量、资源、先攻顺序,战斗中附你到各人的距离 |
|
|
37
|
+
| `/dnd combat` | 最近一场战斗代理的模型与用量,新输入、缓存读取、缓存写入和输出分别统计 |
|
|
38
|
+
| `/dnd map [battle\|explore]` | 发地图:战斗中是站位图,平时是已探索部分的迷雾地图 |
|
|
39
|
+
| `/dnd checkin` | 再发一次签到按钮 |
|
|
40
|
+
| `/dnd end [摘要]` | 保存交接并暂停,战斗状态保留;也可以直接说「今天先到这」 |
|
|
41
|
+
| `/dnd dungeons` | 列出可用模组 |
|
|
42
|
+
| `/dnd search <词条>` | 查[灰机 D&D wiki](https://dnd.huijiwiki.com/wiki/)(法术、技能、职业、专长、怪物…) |
|
|
43
|
+
| `/dnd spells [职业]` | 职业法术列表 |
|
|
44
|
+
| `/dnd help` | 玩法说明 |
|
|
45
|
+
|
|
46
|
+
### 一场团怎么进行
|
|
47
|
+
|
|
48
|
+
- **说行动**:@bot 并说清楚角色做什么才算行动。闲聊、问规则、「查询状态」都不算,不掷骰也不消耗动作。只能控制自己的角色。
|
|
49
|
+
- **回合按钮**:轮到 PC 时,bot 在 DM 的回复后补一条带按钮的消息。
|
|
50
|
+
- 「结束回合」只有本人点击有效,点击后先攻由工具推进,DM 接着结算怪物回合。
|
|
51
|
+
- 「查看状态」由工具直接回复,不经过模型。
|
|
52
|
+
- 「我的法术」列出点击者自己的法术和法术位,每条带 wiki 链接。
|
|
53
|
+
- 「行动」往自己的输入框里预填角色名。
|
|
54
|
+
- 需要 QQ 开放平台的消息按钮权限;发送失败会在本次运行中自动关闭按钮,退回纯文字推进。
|
|
55
|
+
- **反应窗口**:有人能反应时,攻击只掷骰、先挂成待结算,等本人答复(护盾术、尖刻言语、时间变幻重掷);一直没人应,由 DM 替他跳过。
|
|
56
|
+
- **分头行动**:只有说了要走的人才会移动,其他人留在原地,地图上每个有人的房间各标人数。
|
|
57
|
+
- **回滚**:大家同意的话说「卷回到 xx 之前」,DM 用快照撤销,不会靠改数字硬凑。
|
|
58
|
+
- **收团与续团**:停团时写一份交接(位置、刚刚发生、已定行动、同行与留守、未结事项、下次接续),先攻、站位和待结算反应原样保留,下次 `start` 接着跑。停团后聊团不剧透,DM 先查账本再答。
|
|
59
|
+
|
|
60
|
+
### 独立战斗代理(可选)
|
|
61
|
+
|
|
62
|
+
设置页「跑团 → 独立战斗代理」可将战斗交给另一个模型,默认关闭。主 DM 负责掷先攻和叙述开场,回复结束后自动唤醒子 DM 准备场地图、摆位和当前回合;后续玩家消息及按钮直接交给同一个战斗子会话,主模型不逐条转述。默认路由为 `opencode-go/deepseek-v4.1-flash`、推理 `high`,交接最近 8000 字对话及角色状态与已记录约定,不复制整个主会话。战斗工具仍实时读写原团档;结束后交回最新状态、消耗与新增账本,主 DM 只接续战后剧情。
|
|
63
|
+
|
|
64
|
+
```yaml
|
|
65
|
+
dnd:
|
|
66
|
+
combatAgent:
|
|
67
|
+
enabled: true
|
|
68
|
+
provider: opencode-go
|
|
69
|
+
model: deepseek-v4.1-flash
|
|
70
|
+
reasoningEffort: high
|
|
71
|
+
contextChars: 8000
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
子级只开放战斗所需的 `dnd_*` 工具,没有终端、文件或任意子代理能力,因此无需给群增加终端白名单。插件重组可恢复活跃子会话;启动或运行失败交回主 DM,不重做已落账行动。`/new` 会释放子级。每场用量和交接记录保存在跑团目录的 `combat-runs/`,含 DM 私有资料,不要发给玩家。`/dnd combat` 只展示用量,包含战后主 DM 的一次交接回复,不包含开战前的主会话;金额按实际渠道账单计算。首次测试时同时观察规则错误与回滚次数,不能只比较单次请求价格。
|
|
75
|
+
|
|
76
|
+
启用独立代理时,主 DM 隐藏 `dnd_position`,只加载探索版 `dnd_check` / `dnd_apply` 和仅开战的 `dnd_initiative`;攻击、反应和回合循环参数及完整战斗守则由子 DM 加载。探索检定、陷阱群体豁免、治疗、改卡和资源工具仍保留。子级接管期间主级隐藏全部跑团工具;子级失败或关闭委派时自动恢复主 DM 的完整工具。旧宿主不支持同名工具覆盖时保留完整版本。
|
|
77
|
+
|
|
78
|
+
构建后还需保存一次设置触发 profile 重组,宿主才会加载新代码。
|
|
79
|
+
|
|
80
|
+
开战交接会附上角色的职业等级、属性、技能/专精、豁免、武器基础命中与伤害、法术、被动备注、反应和资源,并携带团档中所有 `ruling` 约定。备注里的能力不会自动成为程序规则:例如现世感知的智力先攻加值,核对后可用 `dnd_character update name=奇塔露 init_bonus=7` 保存**固定总先攻**;灵敏之赐的 `1d8` 仍在开战时通过 `bonus` 另加。修改固定先攻不重写当前先攻表;属性或能力变化时需同步更新。长期约定用 `dnd_chronicle add kind=ruling` 保存。
|
|
81
|
+
|
|
82
|
+
`dnd_check type=save targets=[…]` 一次掷公共伤害、逐人豁免并结算半伤、抗性和失败状态;每项可单独带 `bonus_dice="1d4"`,只给受到祝福的人加骰。普通 `dnd_apply targets=[{name,…}]` 可原子批量伤害、治疗、临时生命和状态;`damage_roll` / `heal_roll` 由工具统一掷一次,每人可覆盖数值或抗性,一次撤销整批回滚。`dnd_character update names=[…]` 可批量改卡。
|
|
83
|
+
|
|
84
|
+
玩家预先授权「最终命中就用至圣斩」时,可传 `dnd_check on_hit={name:"至圣斩",damage:"2d8",damage_type:"光耀",spend:"1环法术位"}`:所有防守反应结束后才扣一次资源,最终未命中不扣;重击翻倍追加骰,武器与追加分别过抗性,再作为同一击扣血。`critical_only=true` 仅用于玩家明确授权「重击才用」。这不是替玩家在掷骰后选资源;同回合多次攻击、跨轮持续伤害和看到命中后再询问选择仍逐次处理。普通 `spend` 仍在掷骰前扣除。
|
|
85
|
+
|
|
86
|
+
PC 的待结算反应(包括借机)必须使用真实按钮或明确短宣告生成的一次性 `authorization`,原样填入 `dnd_apply reaction.authorization` / `dnd_check authorization`;`declared_by` 只核对归属,不能代替同意。授权绑定当前窗口、角色和技能;本人改选「不用」立即撤回,排队的旧调用不会掷骰或扣资源。规则提问、纠正规则及「没有/没/算了」等含混短答不授权;不明确时继续询问。掷骰前用 `hold_for` 询问手动 PC 技能;已有窗口漏了技能,用 `dnd_apply ask_reactions=[{by,name}]` 补询问并停手,不重掷、不自动授权,也不能覆盖拒绝。旧存档中没有凭证的确认需本人重新选择。
|
|
87
|
+
|
|
88
|
+
### 地图与战斗站位
|
|
89
|
+
|
|
90
|
+
- **战斗站位**:一格 5 尺,按房间画场地图(墙、门、门外走廊、障碍、难行地形)。移动按意图走,Dijkstra 寻路绕墙和敌人格,难行地形双倍,同距离优先少触发借机。逐步检查整条路线,在离开触及之前或长柄大师入圈处暂停;问清并结算借机后才继续剩余移动。反应按内置 `0/1` 记账,到本人下回合开始恢复,不另建 `dnd_resource`;护盾术持续到本人下回合开始。战斗中换房间要先走到对应出口;真正的强制位移/传送才用 `set` 或 `dnd_character forced_move=true`。
|
|
91
|
+
- **范围法术**:球、立方、线形先查罩到哪些敌我,再决定放不放。
|
|
92
|
+
- **图片地图**(需要可选依赖 `sharp`):战斗中发当前房间的战斗图,标出站位和坐标,模组有底图就用底图;平时发已探索部分的迷雾地图,有书里的玩家版地图就用它。没装 `sharp` 时退回聊天框里的字符地图。
|
|
93
|
+
|
|
94
|
+
### DM 工具
|
|
95
|
+
|
|
96
|
+
| 类别 | 工具 | 作用 |
|
|
97
|
+
|------|------|------|
|
|
98
|
+
| 掷骰 | `dnd_roll` | 任意骰子表达式(`2d6+3`、`4d6kh3`…) |
|
|
99
|
+
| | `dnd_check` | 检定、豁免、攻击、死亡豁免;逐目标加骰、`on_hit` 预授权命中追加;反应攻击自动扣反应,每一骰带 `#R` 编号 |
|
|
100
|
+
| | `dnd_apply` | 单人/`targets` 批量伤害、治疗、临时 HP、状态,公共伤害/治疗可直接掷骰;处理待结算骰子、反应及暂停移动 |
|
|
101
|
+
| 角色 | `dnd_character` | 建卡/改卡(玩家绑定、武器、法术清单、物品金币);展示、核对和改卡先 `show` 查当前卡,修改成功才确认保存;停团可建、改、查 PC 卡,不删卡或改位置;`names` 一次改多人(发东西、换房间、`max_hp_change` 加减生命上限);`srd=goblin count=3` 从 SRD 取真实数值加怪 |
|
|
102
|
+
| | `dnd_resource` | 法术位、圣疗池、诗人激励、职业特性次数;停团也可用 `set` 配置 PC 资源 |
|
|
103
|
+
| | `dnd_rest` | 短休(工具掷生命骰回血)/ 长休 |
|
|
104
|
+
| 战斗 | `dnd_initiative` | 先攻 start / next / goto / end / status;`surprised` 的人第 1 轮由工具跳过 |
|
|
105
|
+
| | `dnd_position` | 战斗内站位:画场地图、摆位、回合内移动、距离查询、`area` 查范围法术 |
|
|
106
|
+
| 探索 | `dnd_move` | 房间移动(`who` 分头行动、暗门发现),返回玩家视角描述 + DM 机密;出口检定已经用 `dnd_check` 投过时传 `check_done` 不再重掷 |
|
|
107
|
+
| | `dnd_map` | 发战斗图或迷雾地图到群里 |
|
|
108
|
+
| 剧情 | `dnd_story` | 按 id 改模组里写好的剧情状态:触发器、信息、任务、NPC 生死与同行 |
|
|
109
|
+
| | `dnd_lookup` | 查模组细节(房间、NPC、线索),只给 DM 看;`kind=character` 看队伍的角色卡,停团时也能查 |
|
|
110
|
+
| | `dnd_hook` | 背景钩子:玩家讲的角色来历里没了结的事挂在 PC 卡上,碰到触发词提醒 DM,分 5 档推进 |
|
|
111
|
+
| | `dnd_chronicle` | 长期剧情账本:临场事实、承诺、俘虏和未结线头,按关键词查询;停团后仍可查 |
|
|
112
|
+
| 存档 | `dnd_undo` | 列出最近改动 / 撤销 N 步 / 按骰子编号撤回那一骰和它之后的后果 |
|
|
113
|
+
| | `dnd_progress` | 保存进度但不暂停,按段增量修改 |
|
|
114
|
+
| | `dnd_prepare` | DM 私有备团:核对团况与交接,保存候选计划;不推进剧情、不向群里发送 |
|
|
115
|
+
| | `dnd_end` | 与 `/dnd end` 共用保存与暂停流程 |
|
|
116
|
+
| 查询 | `dnd_srd` | 查 5e SRD 怪物/法术(dnd5eapi.co) |
|
|
117
|
+
|
|
118
|
+
工具层还自动处理一部分规则:PC 0 HP 倒地与死亡豁免、溢出伤害即死、重击骰子翻倍、「不死坚韧」;手动解除「死亡」会被拒绝。
|
|
119
|
+
|
|
120
|
+
### 模组
|
|
121
|
+
|
|
122
|
+
- **内置「沉钟修道院」**:原创的 7 房间小地城,适合 1–3 级、3–5 人一晚打完,怪物数值取自 SRD 5.1(CC BY 4.0)。
|
|
123
|
+
- **自己写模组**:把 JSON 放进 `<dnd.root>/adventures/`,小模组一个文件,大模组按场景拆文件;文件改了自动重读,不用重启。模组可以写章节、场景、房间、NPC(含 `knows`:他知道什么、不知道什么)、线索、任务、触发器和战斗场地图。完整写法见 **[模组编写指南](./skills/dnd-module-authoring/guide.md)**。
|
|
124
|
+
- 旧的单地城格式(`dungeons/*.json`)仍然可用。
|
|
125
|
+
- **版权**:商业模组(如《凡达林的失落矿坑》)转出来的文本只放在本机自用,不要提交进仓库。
|
|
126
|
+
|
|
127
|
+
### 数据与配置
|
|
128
|
+
|
|
129
|
+
- 每个群一份团档 `<dnd.root>/campaigns/<会话>.json`,改动快照存在 `campaigns/history/`(最近 40 步)。团档只能经 `dnd_*` 工具修改,文件工具写不进去。
|
|
130
|
+
- `dnd_*` 工具只对有团的 QQ 会话可见:没开团的群和私聊不带这些工具(省下约一万 token 的工具说明),停团时只留查账本、备团和补写交接用的几个,`/dnd start` 后全部可用。
|
|
131
|
+
- 状态怎么跨压缩、跨停团保留,以及踩过的坑,见 **[跑团状态长期化的开发记录](./docs/dnd-long-lived-state.md)**。
|
|
132
|
+
|
|
133
|
+
| 配置 | 默认值 | 说明 |
|
|
134
|
+
|------|--------|------|
|
|
135
|
+
| `dnd.enabled` | `true` | 跑团开关(`/dnd` 命令 + `dnd_*` 工具) |
|
|
136
|
+
| `dnd.root` | `cwd/dnd` | 团档、模组的数据目录 |
|
|
137
|
+
| `dnd.turnButtons` | `true` | 轮到玩家时发回合按钮 |
|
|
138
|
+
| `dnd.interjections` | `true` | 开团期间也按插话概率随机吐槽(只吐槽、不结算);关掉后只回 @ |
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## 其他功能
|
|
143
|
+
|
|
144
|
+
除跑团外,本仓库在上游基础上还加了这些。配置项都在 DSH Web「插件」页的 QQ 机器人设置里,带说明。
|
|
145
|
+
|
|
146
|
+
| 方向 | 内容 |
|
|
147
|
+
|------|------|
|
|
148
|
+
| 💬 群聊 | 未 @ 时按概率或「回复欲望」打分接话;群消息落盘,重启后接得上;能看历史图片;合并消息保留各自发送者;上下文超限自动压缩;`/new` 时先压缩旧会话,把压缩摘要带进新会话(`/new blank` 完全从头) |
|
|
149
|
+
| 🎭 人设 | 群聊和私聊都支持 `/persona`(或 `/人设`)按钮切换,也可用 `/persona 名字`;主人和管理员可操作。每个聊天独立选择,各人设保留自己的历史;切换前生成跨人格共同交接,接手时只补未接收的版本;`/persona 默认` 恢复对应的 `groupPrompt` / `directPrompt` |
|
|
150
|
+
| 🧠 记忆 | `notes/` 下的 Markdown 笔记库,所有会话共用、按内容自动召回;`chat` 范围的笔记只在本群可见。主人私聊发 `/bot-notes` 查看注入情况 |
|
|
151
|
+
| 😺 表情 | 按情绪自动收藏(`qqbot_save_sticker`)、按哈希匹配(`qqbot_match_sticker`)、梗图识别 skill |
|
|
152
|
+
| 🖼 媒体 | 图文同发(`caption`)、`deepseek-native` 原生读图、语音识别、整段视频理解与关键帧复查、音频转写、合并转发里的图片 |
|
|
153
|
+
| 🔧 工具 | 以图搜图、B 站只读工具、同人图挑选、Playwright 浏览器(默认关闭,按群白名单授权)、Agent 临时目录与定期清理(`/bot-cleanup`) |
|
|
154
|
+
| ⏰ 定时 | `/new` 和人设切换时自动迁移定时任务;群聊主动消息失败后补发 |
|
|
155
|
+
| 🔁 模型 | 上游状态监测与主备模型自动切换(`modelFailover`,默认关闭) |
|
|
156
|
+
| 🧩 DSH 集成 | 在 DSH Web「插件」页安装、启停和改配置;桌宠余额兼容 `deepseek-native` |
|
|
157
|
+
|
|
158
|
+
人格交接保存在 `~/.dsh-qqbot/persona-handoffs/<聊天键哈希>.json`,按应用、群聊/私聊分别隔离。切换保留来源会话实际选用的模型,不随人格回落到默认模型;交接从已有压缩摘要、未覆盖的对话及工具证据生成,优先保留用户纠正和未完成事项。长记录逐段保存草稿,失败重试可继续处理未读部分。目标人格按「自身设定 → 自身历史 → 最新共同交接 → 新消息」接续,旧人格的身份与说话习惯不继承。版本、来源、时间、覆盖到的 session/事件位置及各人格接收记录均落盘,后台任务 ID 和定时任务迁移配置独立保留并要求先查状态;摘要失败时保留旧版、保存未覆盖原文并明确提示。切换需等待整理完成,期间新消息会等候;跑团期间仍禁止切换。更新宿主后可运行 `node scripts/check-persona-handoff-host.mjs [宿主包目录]`,用实际安装的 v4 编解码器离线检查消息持久化格式。
|
|
159
|
+
|
|
160
|
+
### 权限
|
|
161
|
+
|
|
162
|
+
- `allowlist` 为空时拒绝所有人(fail-closed);`/model`、`/preset` 和审批按钮只有 `ownerOpenid` / `adminOpenids` 能操作。
|
|
163
|
+
- **按会话限制工具**(`toolAccess`,默认开启):主人私聊和白名单会话不受限;其他 QQ 会话不给终端和子 agent,文件工具只能碰 media、表情库、临时目录和 `toolAccess.readRoots`。本机会话(Web/Desktop)不受影响。
|
|
164
|
+
- 主人在私聊里说「给 XX 群开终端」即可加白名单;在群里只能发起申请,由主人本人点按钮同意。
|
|
165
|
+
- `fileAccess.sensitivePaths` 里的路径对受限会话一律拦(即使在 `readRoots` 里);白名单会话有终端,不拦。关掉 `toolAccess` 后对所有 QQ 会话都拦。
|
|
166
|
+
- B 站登录和字幕仅限私聊主人/管理员;以图搜图会把图片上传到第三方服务,只在用户明确问出处时才调用。
|
|
167
|
+
|
|
168
|
+
> 共享笔记对所有会话可见,私聊内容也可能在群里被召回。不要让 bot 记隐私,主人应定期翻看 `notes/` 清理。
|
|
169
|
+
|
|
170
|
+
## 本地运行
|
|
171
|
+
|
|
172
|
+
> 勿与上游 `@tencent-connect/dsh-qqbot` 在同一 profile 中同时启用(两者共用 `im-qqbot` 插件 ID)。
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
# 从 npm 安装(发布后可用)
|
|
176
|
+
dsh plugin --profile web add dsh-dungeon-master
|
|
177
|
+
|
|
178
|
+
# 或从本地源码构建并挂载
|
|
179
|
+
pnpm install && pnpm build
|
|
180
|
+
npx @deepseek-ai/dsh plugin --profile qqbot add /path/to/dsh-dungeon-master
|
|
181
|
+
npx @deepseek-ai/dsh --profile qqbot
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
插件加载的是 `dist/`:改完代码要 `pnpm build`,并**重启 dsh** 才会生效。图片地图需要可选依赖 `sharp`,视频相关工具需要 ffmpeg/ffprobe。其他安装方式见上游 README。
|
|
185
|
+
|
|
186
|
+
## 安全与隐私
|
|
187
|
+
|
|
188
|
+
- 凭据只放在 profile 的 `cordis.patch.yml` 或环境变量里,不要提交。
|
|
189
|
+
- 运行期数据不进仓库:`media/`(群聊和私聊附件,可能涉及他人隐私)、`stickers/`、`notes/`、`dnd/`、`tmp/`。
|
|
190
|
+
- 提交前用 `git status --short` 和 `git diff --cached` 复查。
|
|
191
|
+
|
|
192
|
+
## 致谢与许可
|
|
193
|
+
|
|
194
|
+
- 上游:[tencent-connect/dsh-qqbot](https://github.com/tencent-connect/dsh-qqbot)(MIT)
|
|
195
|
+
- 宿主:[deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)
|
|
196
|
+
- 怪物与法术数据:System Reference Document 5.1(Wizards of the Coast,[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/))
|
|
197
|
+
- 规则查阅:[灰机 D&D wiki](https://dnd.huijiwiki.com/wiki/)
|
|
198
|
+
- B 站接口思路参考 [dsh-bili-scroll](https://github.com/c1overzz/dsh-bili-scroll)(MIT)
|
|
199
|
+
|
|
200
|
+
[MIT](./LICENSE)
|