dsh-dungeon-master 0.5.2 → 0.7.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 +24 -2
- package/CHANGELOG_EN.md +24 -2
- package/README.md +203 -198
- package/README_EN.md +203 -198
- package/cordis.patch.yml +32 -32
- package/cordis.yml +112 -112
- package/dist/commands/dnd.d.ts.map +1 -1
- package/dist/commands/dnd.js +4 -3
- 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 +11 -4
- package/dist/dnd/battle-image.d.ts.map +1 -1
- package/dist/dnd/battle-image.js +86 -7
- package/dist/dnd/battle-image.js.map +1 -1
- package/dist/dnd/battlefield.d.ts +39 -3
- package/dist/dnd/battlefield.d.ts.map +1 -1
- package/dist/dnd/battlefield.js +378 -88
- package/dist/dnd/battlefield.js.map +1 -1
- package/dist/dnd/campaign.d.ts +192 -16
- package/dist/dnd/campaign.d.ts.map +1 -1
- package/dist/dnd/campaign.js +645 -92
- package/dist/dnd/campaign.js.map +1 -1
- package/dist/dnd/combat-agent.d.ts +53 -5
- package/dist/dnd/combat-agent.d.ts.map +1 -1
- package/dist/dnd/combat-agent.js +612 -62
- package/dist/dnd/combat-agent.js.map +1 -1
- package/dist/dnd/combat-context.d.ts +74 -2
- package/dist/dnd/combat-context.d.ts.map +1 -1
- package/dist/dnd/combat-context.js +62 -21
- package/dist/dnd/combat-context.js.map +1 -1
- package/dist/dnd/conditions.d.ts +217 -0
- package/dist/dnd/conditions.d.ts.map +1 -0
- package/dist/dnd/conditions.js +1216 -0
- package/dist/dnd/conditions.js.map +1 -0
- package/dist/dnd/custom-effects.d.ts +121 -0
- package/dist/dnd/custom-effects.d.ts.map +1 -0
- package/dist/dnd/custom-effects.js +446 -0
- package/dist/dnd/custom-effects.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.d.ts +8 -6
- package/dist/dnd/dnd-service.d.ts.map +1 -1
- package/dist/dnd/dnd-service.js +43 -7
- package/dist/dnd/dnd-service.js.map +1 -1
- package/dist/dnd/dnd-tools.d.ts.map +1 -1
- package/dist/dnd/dnd-tools.js +2 -0
- package/dist/dnd/dnd-tools.js.map +1 -1
- package/dist/dnd/formula.d.ts +40 -0
- package/dist/dnd/formula.d.ts.map +1 -0
- package/dist/dnd/formula.js +219 -0
- package/dist/dnd/formula.js.map +1 -0
- package/dist/dnd/map-view.d.ts +3 -1
- package/dist/dnd/map-view.d.ts.map +1 -1
- package/dist/dnd/map-view.js +33 -10
- package/dist/dnd/map-view.js.map +1 -1
- package/dist/dnd/movement.d.ts +3 -3
- package/dist/dnd/movement.d.ts.map +1 -1
- package/dist/dnd/movement.js +14 -8
- 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 +12 -0
- package/dist/dnd/save-effect.d.ts.map +1 -1
- package/dist/dnd/save-effect.js +72 -8
- 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/srd-lookup.d.ts.map +1 -1
- package/dist/dnd/srd-lookup.js +23 -0
- package/dist/dnd/srd-lookup.js.map +1 -1
- package/dist/dnd/terrain.d.ts +8 -2
- package/dist/dnd/terrain.d.ts.map +1 -1
- package/dist/dnd/terrain.js +13 -8
- package/dist/dnd/terrain.js.map +1 -1
- package/dist/dnd/tool-scope.d.ts.map +1 -1
- package/dist/dnd/tool-scope.js +1 -1
- package/dist/dnd/tool-scope.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 +223 -21
- 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 +222 -32
- 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 +406 -53
- package/dist/dnd/tools/dice.js.map +1 -1
- package/dist/dnd/tools/explore.d.ts.map +1 -1
- package/dist/dnd/tools/explore.js +3 -2
- package/dist/dnd/tools/explore.js.map +1 -1
- package/dist/dnd/tools/rules.d.ts +3 -0
- package/dist/dnd/tools/rules.d.ts.map +1 -0
- package/dist/dnd/tools/rules.js +190 -0
- package/dist/dnd/tools/rules.js.map +1 -0
- 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 +8 -2
- package/dist/dnd/tools/shared.d.ts.map +1 -1
- package/dist/dnd/tools/shared.js +239 -39
- 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 +49 -25
- package/dist/dnd/turn-buttons.js.map +1 -1
- package/dist/dnd/zones.d.ts +123 -0
- package/dist/dnd/zones.d.ts.map +1 -0
- package/dist/dnd/zones.js +545 -0
- package/dist/dnd/zones.js.map +1 -0
- 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 +28 -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/model/status-watch.d.ts +4 -0
- package/dist/model/status-watch.d.ts.map +1 -1
- package/dist/model/status-watch.js +6 -2
- package/dist/model/status-watch.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 +21 -5
- package/dist/session/session-manager.d.ts.map +1 -1
- package/dist/session/session-manager.js +141 -18
- package/dist/session/session-manager.js.map +1 -1
- package/dist/session/types.d.ts +8 -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 +66 -13
- 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 +143 -137
- package/skills/dnd-module-authoring/SKILL.md +91 -0
- package/skills/dnd-module-authoring/guide.md +76 -47
- package/skills/dnd-rule-extension/SKILL.md +126 -0
- package/skills/qqbot-sticker-maker/SKILL.md +87 -0
- package/skills/qqbot-sticker-maker/references/character-specs.md +94 -0
- package/skills/qqbot-sticker-maker/references/meme-adaptation-notes.md +46 -0
- package/skills/qqbot-sticker-maker/resources/zipzippipe/sources.json +105 -0
- package/skills/qqbot-sticker-maker/scripts/sticker-cli.cjs +1158 -0
- package/skills/qqbot-sticker-maker/scripts/sticker-export.cjs +147 -0
package/README_EN.md
CHANGED
|
@@ -1,198 +1,203 @@
|
|
|
1
|
-
# DSH Dungeon Master
|
|
2
|
-
|
|
3
|
-
**[简体中文](./README.md) | English**
|
|
4
|
-
|
|
5
|
-
**An AI dungeon master that runs D&D 5e in QQ groups.** This is a fork of [tencent-connect/dsh-qqbot](https://github.com/tencent-connect/dsh-qqbot): send `/dnd start` in a group and the bot becomes that group's DM. Dice, checks, initiative, positions and hit points are all resolved by tools; the model only tells the story.
|
|
6
|
-
|
|
7
|
-
> Installation, QR-code binding, the base config options, built-in commands and the overall architecture are unchanged from upstream: see the **[upstream README](https://github.com/tencent-connect/dsh-qqbot#readme)**. This document is mostly about campaigns; the other additions are listed briefly [at the end](#other-features).
|
|
8
|
-
|
|
9
|
-
## Start a game in three steps
|
|
10
|
-
|
|
11
|
-
1. Install the plugin as described in [Running locally](#running-locally) and add the bot to a group.
|
|
12
|
-
2. Send `/dnd start` in the group. The message carries check-in buttons and the game opens when everyone is in; if someone can't make it, click "Start".
|
|
13
|
-
3. @ the bot and say what your character does: "Kaes swings his greatsword at goblin 3", "Enzo sneaks to the door and listens".
|
|
14
|
-
|
|
15
|
-
There is no preset switch and no new session: while a campaign is active, every turn gets two extra system prompts (the DM rules and a compact campaign state), and `/dnd end` returns the bot to normal chat.
|
|
16
|
-
|
|
17
|
-
---
|
|
18
|
-
|
|
19
|
-
## 🎲 Campaigns
|
|
20
|
-
|
|
21
|
-
### Design principles
|
|
22
|
-
|
|
23
|
-
- **Every ruling goes through a tool.** Dice, checks, damage, HP, conditions, positions and resources only change through `dnd_*` tools; the model cannot make up a roll.
|
|
24
|
-
- **Secrets stay out of reach.** DM notes and secret doors only appear in tool results, and `dnd_*` results are never shown in the group. Monster AC, HP and DCs are kept out of routine tool results and the campaign state too: those give only success or failure and a wound word (unhurt / lightly hurt / badly hurt / barely standing). When a ruling needs the numbers, the DM looks them up with `dnd_character show`.
|
|
25
|
-
- **Only a PC's own player can act for it.** PCs are bound to their player's openid. The tool also checks that this person really sent a message recently, so the model can't impersonate someone by copying an openid.
|
|
26
|
-
- **Strict turn order.** In combat only the creature whose turn it is can act, and only a PC's own player can end that PC's turn.
|
|
27
|
-
- **State lives in the save file, not in the model's memory.** The full state is one JSON file and each turn gets only a compact summary. Anything that has to survive context compaction, such as positions and pending reactions, is in that summary instead of relying on a paraphrased recap.
|
|
28
|
-
- **Wrong rulings can be rolled back.** Every change leaves a snapshot, and you can undo by step count or by roll number.
|
|
29
|
-
|
|
30
|
-
### Player commands
|
|
31
|
-
|
|
32
|
-
| Command | What it does |
|
|
33
|
-
|---------|--------------|
|
|
34
|
-
| `/dnd start [module id]` | Start a campaign (an earlier campaign in the same module resumes); the message carries check-in buttons and the game opens when everyone is in |
|
|
35
|
-
| `/dnd new [module id] [blank]` | Archive the old campaign and start fresh (keeps the old character sheets unless you add `blank`) |
|
|
36
|
-
| `/dnd status` | Campaign state from the players' point of view: HP, resources and initiative order, plus your distance to everyone in combat |
|
|
37
|
-
| `/dnd combat` | Latest combat-agent route and usage, with uncached input, cache reads/writes and output counted separately |
|
|
38
|
-
| `/dnd map [battle\|explore]` | Send the map: the battle map in combat, otherwise the fog-of-war map of what has been explored |
|
|
39
|
-
| `/dnd checkin` | Re-send the check-in buttons |
|
|
40
|
-
| `/dnd end [recap]` | Save a handoff and pause, preserving combat; saying you're stopping for tonight also works |
|
|
41
|
-
| `/dnd dungeons` | List available modules |
|
|
42
|
-
| `/dnd search <term>` | Look up the [Huiji D&D wiki](https://dnd.huijiwiki.com/wiki/) (spells, skills, classes, feats, monsters…) |
|
|
43
|
-
| `/dnd spells [class]` | A class's spell list |
|
|
44
|
-
| `/dnd help` | How to play |
|
|
45
|
-
|
|
46
|
-
### How a session runs
|
|
47
|
-
|
|
48
|
-
- **Declaring actions.** Only @-ing the bot and saying what your character does counts as an action. Chatting, rules questions and "show me the status" don't roll dice or use up your action. You can only control your own character.
|
|
49
|
-
- **Turn buttons.** When it's a PC's turn, the bot sends a message with buttons after the DM's reply.
|
|
50
|
-
- **End turn** only works for the PC's own player; after the click the tool advances initiative and the DM resolves the monsters' turns.
|
|
51
|
-
- **Status** is answered directly by the tool, without the model.
|
|
52
|
-
- **My spells** lists the clicker's own spells and slots, each with a wiki link.
|
|
53
|
-
- **Act** fills the character's name into the clicker's own input box.
|
|
54
|
-
- The bot needs message-button permission on the QQ Open Platform. If sending buttons fails, they switch off for the rest of that run and the game continues in plain text.
|
|
55
|
-
- **Reaction windows.** When someone could react, an attack only rolls and is held as pending until that player answers (Shield, Vicious Mockery, a Chronal Shift reroll). If nobody answers, the DM skips them.
|
|
56
|
-
- **Splitting up.** Only the characters who said they're going move; everyone else stays put, and the map marks every occupied room with a head count.
|
|
57
|
-
- **Rollbacks.** If the table agrees something was resolved wrongly, say "roll back to before X". The DM restores a snapshot instead of patching numbers by hand.
|
|
58
|
-
- **Ending and resuming.** Pausing writes a handoff (location, what just happened, declared actions, who is with whom, loose ends, where to pick up). Initiative, positions and pending reactions are kept as they are, and the next `start` carries on. While paused, the bot doesn't spoil the module and checks the ledger before answering questions about the game.
|
|
59
|
-
|
|
60
|
-
### Dedicated combat agent (optional)
|
|
61
|
-
|
|
62
|
-
Enable **Settings → D&D → Dedicated combat agent** to hand combat to a separate model. It is off by default. The main DM rolls initiative and narrates the opening; after its reply, the child automatically prepares the map/positions and handles the current turn. Later player messages and buttons go directly to that persistent child. The default route is `opencode-go/deepseek-v4.1-flash`, reasoning `high`, with the latest 8,000 characters of dialogue plus party state and recorded table rulings. The full main conversation is not copied. Both DMs use the same campaign save.
|
|
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
|
-
The child has only combat-related `dnd_*` tools, without terminal, file or arbitrary delegation access; no terminal-whitelist grant is needed. Active child sessions resume after plugin reload.
|
|
75
|
-
|
|
76
|
-
With delegation enabled, the main DM hides `dnd_position` and loads exploration-only `dnd_check` / `dnd_apply`, plus a start-only `dnd_initiative`. The child receives full attack/reaction/turn schemas and combat instructions. Exploration checks, group trap saves, healing, sheets and resources remain available to the main DM. During child control, all main-DM D&D tools are hidden. Failure or disabling delegation restores the full main-DM tools; older hosts without scoped tool overrides retain full definitions.
|
|
77
|
-
|
|
78
|
-
After building, save settings once to recompose the profile and load the new server code.
|
|
79
|
-
|
|
80
|
-
The handoff includes class/level, abilities, proficiencies/expertise, saves, base weapon attack/damage, spells, passive notes, reactions, resources, and every recorded `ruling`. Notes do not automatically become engine rules. After checking a sheet, use `dnd_character update init_bonus=7` to persist the **total fixed initiative modifier**; temporary dice such as Gift of Alacrity still belong in initiative `bonus`. This does not rewrite the current order. Update the total when abilities change, and persist table agreements with `dnd_chronicle add kind=ruling`.
|
|
81
|
-
|
|
82
|
-
`dnd_check type=save targets=[…]` rolls shared damage and individual saves, applying reduction, defenses and failure conditions. Each target can specify `bonus_dice="1d4"` for Bless without affecting other creatures. `dnd_apply targets=[{name,…}]` atomically applies damage, healing, temporary HP and conditions; `damage_roll` / `heal_roll` roll once for the batch, with per-target overrides and defenses. One undo reverts the whole batch. Character updates support `names=[…]`.
|
|
83
|
-
|
|
84
|
-
For a player-authorized "use Divine Smite if the final hit lands", pass `dnd_check on_hit={name:"Divine Smite",damage:"2d8",damage_type:"radiant",spend:"1环法术位"}`. Resources are spent once after defensive reactions; a final miss spends nothing. Critical hits double rider dice; weapon and rider defenses are applied separately before one combined HP change. `critical_only=true` requires explicit permission to spend only on a crit. This does not choose resources for the player after rolling. Multiple attacks, damage across rounds and post-hit player choices still use separate calls and stopping points. Ordinary `spend` still happens before rolling.
|
|
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
|
-
|
|
136
|
-
|
|
|
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
|
+
**[简体中文](./README.md) | English**
|
|
4
|
+
|
|
5
|
+
**An AI dungeon master that runs D&D 5e in QQ groups.** This is a fork of [tencent-connect/dsh-qqbot](https://github.com/tencent-connect/dsh-qqbot): send `/dnd start` in a group and the bot becomes that group's DM. Dice, checks, initiative, positions and hit points are all resolved by tools; the model only tells the story.
|
|
6
|
+
|
|
7
|
+
> Installation, QR-code binding, the base config options, built-in commands and the overall architecture are unchanged from upstream: see the **[upstream README](https://github.com/tencent-connect/dsh-qqbot#readme)**. This document is mostly about campaigns; the other additions are listed briefly [at the end](#other-features).
|
|
8
|
+
|
|
9
|
+
## Start a game in three steps
|
|
10
|
+
|
|
11
|
+
1. Install the plugin as described in [Running locally](#running-locally) and add the bot to a group.
|
|
12
|
+
2. Send `/dnd start` in the group. The message carries check-in buttons and the game opens when everyone is in; if someone can't make it, click "Start".
|
|
13
|
+
3. @ the bot and say what your character does: "Kaes swings his greatsword at goblin 3", "Enzo sneaks to the door and listens".
|
|
14
|
+
|
|
15
|
+
There is no preset switch and no new session: while a campaign is active, every turn gets two extra system prompts (the DM rules and a compact campaign state), and `/dnd end` returns the bot to normal chat.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## 🎲 Campaigns
|
|
20
|
+
|
|
21
|
+
### Design principles
|
|
22
|
+
|
|
23
|
+
- **Every ruling goes through a tool.** Dice, checks, damage, HP, conditions, positions and resources only change through `dnd_*` tools; the model cannot make up a roll.
|
|
24
|
+
- **Secrets stay out of reach.** DM notes and secret doors only appear in tool results, and `dnd_*` results are never shown in the group. Monster AC, HP and DCs are kept out of routine tool results and the campaign state too: those give only success or failure and a wound word (unhurt / lightly hurt / badly hurt / barely standing). When a ruling needs the numbers, the DM looks them up with `dnd_character show`.
|
|
25
|
+
- **Only a PC's own player can act for it.** PCs are bound to their player's openid. The tool also checks that this person really sent a message recently, so the model can't impersonate someone by copying an openid.
|
|
26
|
+
- **Strict turn order.** In combat only the creature whose turn it is can act, and only a PC's own player can end that PC's turn.
|
|
27
|
+
- **State lives in the save file, not in the model's memory.** The full state is one JSON file and each turn gets only a compact summary. Anything that has to survive context compaction, such as positions and pending reactions, is in that summary instead of relying on a paraphrased recap.
|
|
28
|
+
- **Wrong rulings can be rolled back.** Every change leaves a snapshot, and you can undo by step count or by roll number.
|
|
29
|
+
|
|
30
|
+
### Player commands
|
|
31
|
+
|
|
32
|
+
| Command | What it does |
|
|
33
|
+
|---------|--------------|
|
|
34
|
+
| `/dnd start [module id]` | Start a campaign (an earlier campaign in the same module resumes); the message carries check-in buttons and the game opens when everyone is in |
|
|
35
|
+
| `/dnd new [module id] [blank]` | Archive the old campaign and start fresh (keeps the old character sheets unless you add `blank`) |
|
|
36
|
+
| `/dnd status` | Campaign state from the players' point of view: HP, resources and initiative order, plus your distance to everyone in combat |
|
|
37
|
+
| `/dnd combat` | Latest combat-agent route and usage, with uncached input, cache reads/writes and output counted separately |
|
|
38
|
+
| `/dnd map [battle\|explore]` | Send the map: the battle map in combat, otherwise the fog-of-war map of what has been explored |
|
|
39
|
+
| `/dnd checkin` | Re-send the check-in buttons |
|
|
40
|
+
| `/dnd end [recap]` | Save a handoff and pause, preserving combat; saying you're stopping for tonight also works |
|
|
41
|
+
| `/dnd dungeons` | List available modules |
|
|
42
|
+
| `/dnd search <term>` | Look up the [Huiji D&D wiki](https://dnd.huijiwiki.com/wiki/) (spells, skills, classes, feats, monsters…) |
|
|
43
|
+
| `/dnd spells [class]` | A class's spell list |
|
|
44
|
+
| `/dnd help` | How to play |
|
|
45
|
+
|
|
46
|
+
### How a session runs
|
|
47
|
+
|
|
48
|
+
- **Declaring actions.** Only @-ing the bot and saying what your character does counts as an action. Chatting, rules questions and "show me the status" don't roll dice or use up your action. You can only control your own character.
|
|
49
|
+
- **Turn buttons.** When it's a PC's turn, the bot sends a message with buttons after the DM's reply.
|
|
50
|
+
- **End turn** only works for the PC's own player; after the click the tool advances initiative and the DM resolves the monsters' turns.
|
|
51
|
+
- **Status** is answered directly by the tool, without the model.
|
|
52
|
+
- **My spells** lists the clicker's own spells and slots, each with a wiki link.
|
|
53
|
+
- **Act** fills the character's name into the clicker's own input box.
|
|
54
|
+
- The bot needs message-button permission on the QQ Open Platform. If sending buttons fails, they switch off for the rest of that run and the game continues in plain text.
|
|
55
|
+
- **Reaction windows.** When someone could react, an attack only rolls and is held as pending until that player answers (Shield, Vicious Mockery, a Chronal Shift reroll). If nobody answers, the DM skips them.
|
|
56
|
+
- **Splitting up.** Only the characters who said they're going move; everyone else stays put, and the map marks every occupied room with a head count.
|
|
57
|
+
- **Rollbacks.** If the table agrees something was resolved wrongly, say "roll back to before X". The DM restores a snapshot instead of patching numbers by hand.
|
|
58
|
+
- **Ending and resuming.** Pausing writes a handoff (location, what just happened, declared actions, who is with whom, loose ends, where to pick up). Initiative, positions and pending reactions are kept as they are, and the next `start` carries on. While paused, the bot doesn't spoil the module and checks the ledger before answering questions about the game.
|
|
59
|
+
|
|
60
|
+
### Dedicated combat agent (optional)
|
|
61
|
+
|
|
62
|
+
Enable **Settings → D&D → Dedicated combat agent** to hand combat to a separate model. It is off by default. The main DM rolls initiative and narrates the opening; after its reply, the child automatically prepares the map/positions and handles the current turn. Later player messages and buttons go directly to that persistent child. The default route is `opencode-go/deepseek-v4.1-flash`, reasoning `high`, with the latest 8,000 characters of dialogue plus party state and recorded table rulings. The full main conversation is not copied. Both DMs use the same campaign save. When combat ends, the child first narrates the final round's rolls, damage, and finishing blow to the group before returning updated state, spent resources, and new ledger facts to the main DM once.
|
|
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
|
+
The child has only combat-related `dnd_*` tools, without terminal, file or arbitrary delegation access; no terminal-whitelist grant is needed. Active child sessions resume after plugin reload. On startup/runtime failures, the router falls back through the `modelFailover` backup (if enabled) and then a lightweight combat subagent reusing the main DM's effective model route (without forcing incompatible reasoning settings) before returning control to the main DM without replaying settled actions; `/new` releases the child. Per-encounter usage and handoffs are saved under `combat-runs/` in the D&D data directory. These files contain private DM material. `/dnd combat` exposes usage only, including the main DM's closing handoff response but excluding its pre-combat work. Use provider invoices for actual charges and compare ruling errors and rollbacks alongside token usage.
|
|
75
|
+
|
|
76
|
+
With delegation enabled, the main DM hides `dnd_position` and loads exploration-only `dnd_check` / `dnd_apply`, plus a start-only `dnd_initiative`. The child receives full attack/reaction/turn schemas and combat instructions. Exploration checks, group trap saves, healing, sheets and resources remain available to the main DM. During child control, all main-DM D&D tools are hidden. Failure or disabling delegation restores the full main-DM tools; older hosts without scoped tool overrides retain full definitions.
|
|
77
|
+
|
|
78
|
+
After building, save settings once to recompose the profile and load the new server code.
|
|
79
|
+
|
|
80
|
+
The handoff includes class/level, abilities, proficiencies/expertise, saves, base weapon attack/damage, spells, passive notes, reactions, resources, and every recorded `ruling`. Notes do not automatically become engine rules. After checking a sheet, use `dnd_character update init_bonus=7` to persist the **total fixed initiative modifier**; temporary dice such as Gift of Alacrity still belong in initiative `bonus`. This does not rewrite the current order. Update the total when abilities change, and persist table agreements with `dnd_chronicle add kind=ruling`. Custom subclass features, signature weapon riders, auras, and destiny passives can be hot-registered into the deterministic engine via `dnd_rule` (with the bundled **[rule extension guide](./skills/dnd-rule-extension/SKILL.md)**) without code edits or restarts.
|
|
81
|
+
|
|
82
|
+
`dnd_check type=save targets=[…]` rolls shared damage and individual saves, applying reduction, defenses and failure conditions. Each target can specify `bonus_dice="1d4"` for Bless without affecting other creatures. `dnd_apply targets=[{name,…}]` atomically applies damage, healing, temporary HP and conditions; `damage_roll` / `heal_roll` roll once for the batch, with per-target overrides and defenses. One undo reverts the whole batch. Character updates support `names=[…]`.
|
|
83
|
+
|
|
84
|
+
For a player-authorized "use Divine Smite if the final hit lands", pass `dnd_check on_hit={name:"Divine Smite",damage:"2d8",damage_type:"radiant",spend:"1环法术位"}`. Resources are spent once after defensive reactions; a final miss spends nothing. Critical hits double rider dice; weapon and rider defenses are applied separately before one combined HP change. `critical_only=true` requires explicit permission to spend only on a crit. This does not choose resources for the player after rolling. Multiple attacks, damage across rounds and post-hit player choices still use separate calls and stopping points. Ordinary `spend` still happens before rolling.
|
|
85
|
+
|
|
86
|
+
Pending PC reactions, including opportunity attacks, require a one-use `authorization` generated by a real button click or explicit short declaration. Copy it into `dnd_apply reaction.authorization` / `dnd_check authorization`; `declared_by` checks ownership but does not grant consent. Tokens bind the window, character and skill. A later refusal revokes the token, so queued calls cannot roll or spend. Rules questions, corrections and ambiguous short replies do not authorize spending. Use `hold_for` before rolling for manual PC reactions. For a missed option on an existing roll, `dnd_apply ask_reactions=[{by,name}]` asks without rerolling, granting consent or overriding a refusal; stop and wait. Legacy confirmations without a token require reconfirmation.
|
|
87
|
+
|
|
88
|
+
### Maps and combat positions
|
|
89
|
+
|
|
90
|
+
- **Positions in combat.** One square is 5 feet. Dijkstra paths around walls and enemy cells, doubles difficult-terrain costs, and prefers fewer opportunity triggers among equally short routes. Every step is checked; movement pauses before leaving reach or on entering Polearm Master reach, then resumes only after reactions resolve. The built-in reaction resource is 0/1 and resets at the actor's next turn; do not create a duplicate with `dnd_resource`. Shield persists until that turn. Room changes in combat require reaching the mapped exit first. Only actual forced movement/teleportation uses `set` or `dnd_character forced_move=true`.
|
|
91
|
+
- **3D altitude & flight.** Characters and monsters support `fly_speed`, `hover`, `z` altitude, and room `ceiling`; 3D reach checks automatically govern melee attacks and opportunity triggers, and non-hovering flyers knocked prone, reduced to 0 speed, or incapacitated automatically fall and resolve `1d6 / 10 ft` bludgeoning damage plus prone.
|
|
92
|
+
- **Persistent battlefield zones.** `dnd_position action=zone / remove_zone` places Darkness, Fog Cloud, Poison Mist, Web, Cloud of Daggers, Moonbeam, Spike Growth, Wall of Fire, Silence, or custom hazard/obscurement zones. `/dnd status` and battle maps render zone overlays, remaining rounds, and coordinates automatically; moving through or starting/ending a turn inside triggers saves and damage automatically, heavy obscurement suppresses opportunity attacks, and zones linked to concentration clean up automatically on expiry or combat end.
|
|
93
|
+
- **Area spells.** Spheres, cubes and lines can be checked for which friends and foes they cover before casting.
|
|
94
|
+
- **Image maps** (need the optional dependency `sharp`). In combat the bot sends the current room's battle map with positions, altitudes, persistent zones and coordinates, on the module's own art if it has any. Otherwise it sends the fog-of-war map of what has been explored, using the book's player map when there is one. Without `sharp` it falls back to a character map in chat.
|
|
95
|
+
|
|
96
|
+
### DM tools
|
|
97
|
+
|
|
98
|
+
| Group | Tool | What it does |
|
|
99
|
+
|-------|------|--------------|
|
|
100
|
+
| Dice | `dnd_roll` | Any dice expression (`2d6+3`, `4d6kh3`…) |
|
|
101
|
+
| | `dnd_check` | Checks, saves, attacks and death saves; per-target bonus dice and pre-authorized `on_hit` riders; reaction attacks spend a reaction; each roll gets a `#R` number |
|
|
102
|
+
| | `dnd_apply` | Single/batch damage, healing, temp HP and conditions; rolls shared amounts; resolves held dice, reactions and paused movement |
|
|
103
|
+
| Characters | `dnd_character` | Create/edit sheets (player binding, weapons with multi-part `riders`, `fly_speed` / `hover`, spell list, items and gold); `show` the current sheet before displaying/checking/editing it, confirm saved only after a successful write; while paused, create/edit/read PC sheets without removing them or changing rooms; `names` changes several characters at once (handing out items, moving rooms, `max_hp_change` for max HP); `srd=goblin count=3` adds monsters with real SRD stats |
|
|
104
|
+
| | `dnd_resource` | Spell slots, Lay on Hands, Bardic Inspiration, class feature uses; `set` also configures PC resources while paused |
|
|
105
|
+
| | `dnd_rest` | Short rest (the tool rolls hit dice) / long rest |
|
|
106
|
+
| Rules | `dnd_rule` | Hot-register, inspect or remove `campaign`- or `global`-scoped custom combat rules (attack, on-hit rider, AC/resistance, save, aura and healing hooks) with safe formula evaluation |
|
|
107
|
+
| Combat | `dnd_initiative` | Initiative start / next / goto / end / status; `surprised` creatures are skipped in round 1 by the tool |
|
|
108
|
+
| | `dnd_position` | Positions & zones in combat: draw the battle map, place tokens, move within a turn with 3D altitude `z`, query distances, `area` for area spells, `zone` / `remove_zone` for persistent hazards and obscurement |
|
|
109
|
+
| Exploration | `dnd_move` | Room movement (`who` for splitting up, secret-door discovery); returns the player-facing description plus DM secrets; `check_done` skips the exit check when it was already rolled with `dnd_check` |
|
|
110
|
+
| | `dnd_map` | Send the battle map or the fog-of-war map to the group |
|
|
111
|
+
| Story | `dnd_story` | Change story state written into the module, by id: triggers, facts, quests, whether an NPC is alive or travelling with the party |
|
|
112
|
+
| | `dnd_lookup` | Read module details (rooms, NPCs, clues), for the DM only; `kind=character` shows the party's sheets, also while paused |
|
|
113
|
+
| | `dnd_hook` | Backstory hooks: unresolved threads from a character's past sit on the PC sheet, remind the DM when a trigger word comes up, and escalate through 5 tiers |
|
|
114
|
+
| | `dnd_chronicle` | Long-term story ledger: improvised facts, promises, prisoners and loose ends, searchable by keyword; still available while paused |
|
|
115
|
+
| Saves | `dnd_undo` | List recent changes / undo N steps / take back one roll by number along with everything after it |
|
|
116
|
+
| | `dnd_progress` | Save progress without pausing, edited section by section |
|
|
117
|
+
| | `dnd_prepare` | Private DM prep: check the state against the handoff and save candidate plans; doesn't advance the story or post to the group |
|
|
118
|
+
| | `dnd_end` | Shares the save-and-pause operation with `/dnd end` |
|
|
119
|
+
| Lookup | `dnd_srd` | Look up 5e SRD monsters/spells (dnd5eapi.co) |
|
|
120
|
+
|
|
121
|
+
The tool layer also handles some rules automatically: PCs dropping to 0 HP and death saves, instant death from overflow damage, doubled dice on a crit, Undead Fortitude, automatic on-hit riders (Hex, Hunter's Mark, Divine Favor, Enlarge, Rage, and weapon `riders`), concentration slot replacement and cleanup (`dnd_apply drop_concentration`), Protection from Poison, aura engine (Paladin Aura of Protection save bonuses, Spirit Guardians upcasting & enemy slow), Life Domain healing (Disciple of Life, Blessed Healer, Preserve Life), and non-hovering crash falls; manually removing "dead" is refused. The package bundles **[`dnd-module-authoring`](./skills/dnd-module-authoring/SKILL.md)** and **[`dnd-rule-extension`](./skills/dnd-rule-extension/SKILL.md)** skills for authoring adventures and extending combat rules.
|
|
122
|
+
|
|
123
|
+
### Modules
|
|
124
|
+
|
|
125
|
+
- **Built-in "The Sunken Bell Abbey".** An original 7-room dungeon for 3–5 characters of level 1–3, playable in one evening. Monster stats are from SRD 5.1 (CC BY 4.0).
|
|
126
|
+
- **Writing your own.** Put JSON in `<dnd.root>/adventures/`: one file for a small module, one file per site for a large one. Files are re-read when they change, with no restart. A module can define chapters, sites, rooms, NPCs (including `knows`: what they know and what they don't), clues, quests, triggers and battle maps. The full format is in the **[module authoring guide](./skills/dnd-module-authoring/guide.md)** (Chinese).
|
|
127
|
+
- The old single-dungeon format (`dungeons/*.json`) still works.
|
|
128
|
+
- **Copyright.** Text converted from commercial modules (such as *Lost Mine of Phandelver*) stays on your own machine. Don't commit it to the repo.
|
|
129
|
+
|
|
130
|
+
### Data and configuration
|
|
131
|
+
|
|
132
|
+
- Each group has one save file, `<dnd.root>/campaigns/<chat>.json`, with change snapshots in `campaigns/history/` (the last 40 steps). Saves can only be changed through `dnd_*` tools; file tools cannot write to them.
|
|
133
|
+
- `dnd_*` tools are only visible to QQ chats that have a campaign. Chats without one don't carry them (saving roughly ten thousand tokens of tool definitions), a paused campaign keeps only the ledger, prep and handoff tools, and `/dnd start` makes all of them available.
|
|
134
|
+
- How state survives compaction and pauses, and the incidents that shaped it, is written up in the **[long-lived campaign state notes](./docs/dnd-long-lived-state.md)** (Chinese).
|
|
135
|
+
|
|
136
|
+
| Option | Default | Description |
|
|
137
|
+
|--------|---------|-------------|
|
|
138
|
+
| `dnd.enabled` | `true` | Campaigns on/off (`/dnd` command + `dnd_*` tools) |
|
|
139
|
+
| `dnd.root` | `cwd/dnd` | Data directory for saves and modules |
|
|
140
|
+
| `dnd.turnButtons` | `true` | Send turn buttons when it's a player's turn |
|
|
141
|
+
| `dnd.interjections` | `true` | Keep making random remarks during a campaign (remarks only, nothing is resolved); off means the bot only answers @ |
|
|
142
|
+
|
|
143
|
+
---
|
|
144
|
+
|
|
145
|
+
## Other features
|
|
146
|
+
|
|
147
|
+
Besides campaigns, this fork adds the following on top of upstream. Every option is documented on the QQ bot settings page under "Plugins" in DSH Web.
|
|
148
|
+
|
|
149
|
+
| Area | Contents |
|
|
150
|
+
|------|----------|
|
|
151
|
+
| 💬 Group chat | Joins in without an @ by probability or a reply-desire score; group messages are persisted and survive restarts; sees earlier images; merged messages keep each sender; automatic compaction when context grows too large; `/new` compacts the old session first and carries the summary into the new one (`/new blank` starts from nothing) |
|
|
152
|
+
| 🎭 Personas | The owner and admins can switch personas in groups and private chats using `/persona` (or `/人设`) buttons or `/persona name`. Each chat has its own selection and each persona keeps its history. Switches generate a shared handoff; restored personas receive only an unseen version. `/persona default` restores the corresponding `groupPrompt` / `directPrompt` |
|
|
153
|
+
| 🧠 Memory | A Markdown notes library under `notes/`, shared by every session and recalled by content; `chat`-scoped notes are visible only in their own group. The owner can send `/bot-notes` in a private chat to see what gets injected |
|
|
154
|
+
| 😺 Stickers | Saves stickers based on the bot's mood (`qqbot_save_sticker`), matches by hash (`qqbot_match_sticker`), meme-recognition skill, plus bundled chibi sticker creation & registration skill ([`qqbot-sticker-maker`](./skills/qqbot-sticker-maker/SKILL.md) with alignment grids, overlay diffs, local patch splicing, white-bg matting / native-alpha 1:1 previews, and atomic `stickers/index.json` registration) |
|
|
155
|
+
| 🖼 Media | Text and media in one message (`caption`), native image input via `deepseek-native`, voice recognition, whole-video understanding with keyframe review, audio transcription, images inside forwarded chat records |
|
|
156
|
+
| 🔧 Tools | Reverse image search, read-only Bilibili tools, fanart picker, Playwright browser (off by default, granted per group), agent temp directory and scheduled cleanup (`/bot-cleanup`) |
|
|
157
|
+
| ⏰ Schedules | Scheduled tasks migrate on `/new` and persona switches; failed proactive group messages are resent later |
|
|
158
|
+
| 🔁 Models | Upstream status monitoring with automatic primary/backup model switching (`modelFailover`, off by default) |
|
|
159
|
+
| 🧩 DSH integration | Install, enable and configure from the "Plugins" page in DSH Web; pet balance works with `deepseek-native` |
|
|
160
|
+
|
|
161
|
+
Persona handoffs are stored in `~/.dsh-qqbot/persona-handoffs/<chat-key-hash>.json`, isolated by app and group/private chat. Switching preserves the source session's actual selected model instead of reverting to a default. Handoffs summarize compacted context, uncovered dialogue and tool evidence, prioritizing user corrections and unfinished work. Long inputs save progress after each chunk so retries can resume. The target receives its own persona prompt and history, then the latest shared handoff before the new message; the previous persona's identity and style are not inherited. Versions, source, time, session/event coverage and per-persona receipts persist across restarts. Background task IDs and schedule migration definitions are retained separately with a reminder to check their status first. Failed generation preserves the previous handoff and saves uncovered records with an explicit warning. Incoming messages wait for the switch to finish; switching during a campaign remains disabled. After host upgrades, run `node scripts/check-persona-handoff-host.mjs [host package directory]` to validate durable messages offline against the installed V4 codec.
|
|
162
|
+
|
|
163
|
+
### Permissions
|
|
164
|
+
|
|
165
|
+
- An empty `allowlist` rejects everyone (fail-closed). `/model`, `/preset` and approval buttons only work for `ownerOpenid` / `adminOpenids`.
|
|
166
|
+
- **Per-chat tool limits** (`toolAccess`, on by default). The owner's private chat and allowlisted chats are unrestricted. Other QQ chats get no terminal and no sub-agents, and file tools can only touch media, the sticker library, the temp directory and `toolAccess.readRoots`. Local sessions (Web/Desktop) are unaffected.
|
|
167
|
+
- The owner can say "give group XX a terminal" in a private chat to allowlist it. In a group the model can only file a request, which the owner approves by clicking a button.
|
|
168
|
+
- Paths in `fileAccess.sensitivePaths` are always blocked for restricted chats, even inside `readRoots`. Allowlisted chats have a terminal anyway, so they are not blocked. With `toolAccess` turned off, the paths are blocked for every QQ chat.
|
|
169
|
+
- Bilibili login and subtitles are limited to the owner/admins in private chat. Reverse image search uploads the image to third-party services, so it is only called when a user explicitly asks for a source.
|
|
170
|
+
|
|
171
|
+
> Shared notes are visible to every session, so something said in a private chat can be recalled in a group. Don't have the bot remember private information, and the owner should review `notes/` from time to time.
|
|
172
|
+
|
|
173
|
+
## Running locally
|
|
174
|
+
|
|
175
|
+
> Do not enable alongside upstream `@tencent-connect/dsh-qqbot` in the same profile (both register the `im-qqbot` plugin ID).
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
# Install from npm (once published)
|
|
179
|
+
dsh plugin --profile web add dsh-dungeon-master
|
|
180
|
+
|
|
181
|
+
# Or build and mount from local source
|
|
182
|
+
pnpm install && pnpm build
|
|
183
|
+
npx @deepseek-ai/dsh plugin --profile qqbot add /path/to/dsh-dungeon-master
|
|
184
|
+
npx @deepseek-ai/dsh --profile qqbot
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
The plugin loads from `dist/`: after changing code, run `pnpm build` and **restart dsh** for it to take effect. Image maps need the optional dependency `sharp`, and the video tools need ffmpeg/ffprobe. Other installation methods are in the upstream README.
|
|
188
|
+
|
|
189
|
+
## Security and privacy
|
|
190
|
+
|
|
191
|
+
- Keep credentials in the profile's `cordis.patch.yml` or in environment variables, never in the repo.
|
|
192
|
+
- Runtime data stays out of the repo: `media/` (attachments from group and private chats, which may involve other people's privacy), `stickers/`, `notes/`, `dnd/`, `tmp/`.
|
|
193
|
+
- Check `git status --short` and `git diff --cached` before committing.
|
|
194
|
+
|
|
195
|
+
## Credits and license
|
|
196
|
+
|
|
197
|
+
- Upstream: [tencent-connect/dsh-qqbot](https://github.com/tencent-connect/dsh-qqbot) (MIT)
|
|
198
|
+
- Host: [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)
|
|
199
|
+
- Monster and spell data: System Reference Document 5.1 (Wizards of the Coast, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/))
|
|
200
|
+
- Rules reference: [Huiji D&D wiki](https://dnd.huijiwiki.com/wiki/)
|
|
201
|
+
- Bilibili API approach based on [dsh-bili-scroll](https://github.com/c1overzz/dsh-bili-scroll) (MIT)
|
|
202
|
+
|
|
203
|
+
[MIT](./LICENSE)
|
package/cordis.patch.yml
CHANGED
|
@@ -1,32 +1,32 @@
|
|
|
1
|
-
# dsh-dungeon-master bundle patch
|
|
2
|
-
#
|
|
3
|
-
# 当本包通过 `dsh plugin --profile <name> add dsh-dungeon-master` 安装后,
|
|
4
|
-
# dsh 启动时自动加载此 patch。
|
|
5
|
-
#
|
|
6
|
-
# 环境变量:
|
|
7
|
-
# QQBOT_APPID - QQ Bot AppID(必填)
|
|
8
|
-
# QQBOT_SECRET - QQ Bot AppSecret(必填)
|
|
9
|
-
#
|
|
10
|
-
# 叠加顺序:dsh-base → 本 bundle patch → profile cordis.patch.yml → --patch
|
|
11
|
-
|
|
12
|
-
# ── 插入 im-qqbot 插件行 ──
|
|
13
|
-
- insert:
|
|
14
|
-
- id: im-qqbot
|
|
15
|
-
name: 'dsh-dungeon-master'
|
|
16
|
-
config:
|
|
17
|
-
appId: __FROM_ENV__
|
|
18
|
-
appSecret: __FROM_ENV__
|
|
19
|
-
# provider/model 留空:从宿主默认模型路由继承
|
|
20
|
-
# 用户可通过 /model 命令在聊天中切换
|
|
21
|
-
requireMention: true
|
|
22
|
-
textChunkLimit: 4500
|
|
23
|
-
sessionIdleTimeout: 1800000
|
|
24
|
-
maxQueue: 20
|
|
25
|
-
processingTimeoutMs: 1800000
|
|
26
|
-
historyLimit: 10
|
|
27
|
-
access:
|
|
28
|
-
c2cMode: open
|
|
29
|
-
c2cAllow: []
|
|
30
|
-
groupMode: open
|
|
31
|
-
groupAllow: []
|
|
32
|
-
debug: false
|
|
1
|
+
# dsh-dungeon-master bundle patch
|
|
2
|
+
#
|
|
3
|
+
# 当本包通过 `dsh plugin --profile <name> add dsh-dungeon-master` 安装后,
|
|
4
|
+
# dsh 启动时自动加载此 patch。
|
|
5
|
+
#
|
|
6
|
+
# 环境变量:
|
|
7
|
+
# QQBOT_APPID - QQ Bot AppID(必填)
|
|
8
|
+
# QQBOT_SECRET - QQ Bot AppSecret(必填)
|
|
9
|
+
#
|
|
10
|
+
# 叠加顺序:dsh-base → 本 bundle patch → profile cordis.patch.yml → --patch
|
|
11
|
+
|
|
12
|
+
# ── 插入 im-qqbot 插件行 ──
|
|
13
|
+
- insert:
|
|
14
|
+
- id: im-qqbot
|
|
15
|
+
name: 'dsh-dungeon-master'
|
|
16
|
+
config:
|
|
17
|
+
appId: __FROM_ENV__
|
|
18
|
+
appSecret: __FROM_ENV__
|
|
19
|
+
# provider/model 留空:从宿主默认模型路由继承
|
|
20
|
+
# 用户可通过 /model 命令在聊天中切换
|
|
21
|
+
requireMention: true
|
|
22
|
+
textChunkLimit: 4500
|
|
23
|
+
sessionIdleTimeout: 1800000
|
|
24
|
+
maxQueue: 20
|
|
25
|
+
processingTimeoutMs: 1800000
|
|
26
|
+
historyLimit: 10
|
|
27
|
+
access:
|
|
28
|
+
c2cMode: open
|
|
29
|
+
c2cAllow: []
|
|
30
|
+
groupMode: open
|
|
31
|
+
groupAllow: []
|
|
32
|
+
debug: false
|