nonebot-plugin-dnddicer 0.2.2__tar.gz → 0.4.0__tar.gz

{nonebot_plugin_dnddicer-0.2.2 → nonebot_plugin_dnddicer-0.4.0}/.github/workflows/docs.yml

@@ -6,6 +6,12 @@
 #
 # 首次使用：仓库 Settings → Pages → Source 选「GitHub Actions」。
 # 未启用前本工作流会自动跳过（保持绿色），启用后无需再改任何配置。
+#
+# 注意（tag 部署被拒时查这里）：启用 Pages 后 GitHub 会自动建 `github-pages` 环境，
+# 其「Deployment branches and tags」默认只允许默认分支部署——tag 推送会在 deploy 步
+# 被拒（annotations 提示 not allowed due to environment protection rules）。
+# 解法：Settings → Environments → github-pages → 放行标签（选 Selected branches and
+# tags 加一条 Tag 规则 `v*`，并保留分支 main 供手动预览；或直接选 All branches and tags）。
 name: docs
 
 on:

{nonebot_plugin_dnddicer-0.2.2 → nonebot_plugin_dnddicer-0.4.0}/.gitignore

@@ -34,6 +34,9 @@ env/
 AGENTS.md
 doc/
 
+# ---- 项目记忆（随项目目录存放、不入库；根目录限定，避免误伤同名子目录）----
+/memory/
+
 # ---- 编辑器/系统 ----
 .vscode/
 .idea/

{nonebot_plugin_dnddicer-0.2.2 → nonebot_plugin_dnddicer-0.4.0}/CHANGELOG.md

@@ -8,6 +8,54 @@
 - 打 `v*` 标签前，请先在下方补好该版本的小节（标题格式 `## [x.y.z] - 日期`）：发布时 `.github/workflows/release.yml` 会提取与所推标签同名的小节作为 GitHub Release 的说明正文，缺小节即会在构建前直接失败。
 -->
 
+## [0.4.0] - 2026-09-26
+
+### 新增
+
+- **规则查询**（`.查询` / `.搜索`，别名 `.检索`；需骰主开启）：
+    - 两种检索：`.查询` 按词条名称匹配、`.搜索` 做全文检索；多关键词用空格分隔表示同时满足、`|` 表示任一满足。
+    - 命中多条时先列候选（回数字看词条、`+` / `-` 翻页，60 秒内只认发起者本人）。
+    - 内容来自《5e不全书》，只用于当次回复与短时内存缓存，不落盘、不随插件分发。
+- **规则查询图片模式**：骰主开启总开关并安装可选依赖（`[render]`）后，`.查询图片 on` 可让本处的词条正文以图片返回（仿《5e不全书》的卡片样式）；渲染失败或未装依赖时自动回退为文字。
+- **查询范围**：`.查询范围` 按群 / 私聊限定本处可查的书目（英文缩写，含 31 本书与 4 个整目录键，默认全部开放）；`.规则书` 列出中文书名与缩写对照（骰主开启图片模式时默认出图）。
+
+### 变更
+
+- **文档站按前置条件重排为四章**：第一章 · 基础操作、第二章 · 玩家进阶、第三章 · DM 进阶、第四章 · 最佳实践；HP 与代掷内容按「无需角色卡 / 已绑定角色卡 / DM」分层重排，旧的《HP 与长休》《DM 实战指南》地址失效，请从侧栏进入新页。
+- **大成功/大失败播报另起一行**：`.r` / `.rh` 的 `N#` 连掷按次汇总、检定点的单轮与连掷播报都单独成行，不再与结果末行相连。
+- **修饰符回显加括号**：带比较符的修饰符（`R` / `X` / `XO` / `CS`）在回复里以括号包裹（如 `2D6(R=1)+3`），与结果分隔的 `=` 区分开；`K` / `KL` / `M` / `P` / `F` 保持原样。
+- `.bot` 简介与插件描述补充「规则查询」表述。
+
+### 修复
+
+- 查询范围受限时未命中的提示分命令处理：`.查询` 会附一句建议改用 `.搜索` 做全文检索；`.搜索` 自身同受范围约束，只说明范围、不再建议改用自己。
+
+### 文档
+
+- 使用文档站新增《规则查询》《自建查询服务》两页；《命令总览》《快速开始》《群管理与 FAQ》同步规则查询的命令、配置与书目缩写表。
+
+## [0.3.0] - 2026-09-25
+
+### 新增
+
+- **自定义武器与攻击系统**：
+    - 角色卡新增 `$武器$` 段（`名称+命中加值,伤害表达式+类型`，多项用 `/` 分隔；名称尾加 `x` 表示不可攻击检定的纯伤害法术），并新增 `$种族$` / `$职业$` / `$子职$` 段（游荡者的偷袭骰按等级自动计算）。
+    - `.武器名攻击` / `.武器名命中`：用卡上该武器的命中加值掷攻击检定，支持 优势/劣势、`N#` 连掷、`±` 临时加值与 `@玩家` 代掷；天然 20 提示重击、天然 1 提示必失。
+    - `.武器名伤害`：掷该武器的伤害并报出伤害类型，`副手` / `重击` / `偷袭` 后缀可组合、可加 `±` 临时加值。
+    - `.设置武器` / `.删除武器`：便捷维护卡上武器（列表查看、同名覆盖、多名称删除）。
+- **`.hp` 伤害位置支持武器写法**：
+    - `.hp 骷髅a易伤 -战锤重击伤害+1d4` 一条命令完成掷伤与扣血；回复先报「谁用【哪件武器】造成了多少伤害」，再列出各目标的扣血读数（单目标报实际结算值、含抗性/易伤折算；一发多目标报掷出的原始值）。
+    - DM 代发不在场的玩家：尾部括号指定武器来源（`.hp 骷髅b -火焰箭伤害（洛恩）` 或 `（@玩家）`，角色名支持模糊匹配）。
+
+### 变更
+
+- **属性攻击命令退役（破坏性变更）**：`.力量攻击` 等六属性攻击命令整体移除，攻击检定统一走角色卡 `$武器$` 项；`$熟练$` 与 `$额外加值$` 不再接受攻击条目（含全局「攻击」键），攻击加值一律折算进武器项。**旧角色卡需重新登记**：新版本读取旧卡会报错，发送 `.角色卡清除` 后重录即可。
+- `.bot` 简介与插件描述补充「自定义武器与攻击」表述。
+
+### 文档
+
+- 使用文档站新增《武器与攻击》页，全站手册同步（检定与豁免、角色卡与属性、DM 实战指南、HP 与长休、命令总览与 FAQ 等）；示例团四张角色卡补齐武器与职业段，战斗示例统一到武器流程。
+
 ## [0.2.2] - 2026-09-24
 
 ### 变更

{nonebot_plugin_dnddicer-0.2.2 → nonebot_plugin_dnddicer-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: nonebot-plugin-dnddicer
-Version: 0.2.2
-Summary: 专精 DND5e/5r 跑团的 NoneBot2 骰娘插件（屠龙骰）：掷骰表达式、角色卡与检定、属性生成、HP 管理、先攻列表、战斗轮等
+Version: 0.4.0
+Summary: 专精 DND5e/5r 跑团的 NoneBot2 骰娘插件（屠龙骰）：掷骰表达式、角色卡与检定、自定义武器与攻击、属性生成、HP 管理、先攻列表、战斗轮、规则查询等
 Project-URL: Homepage, https://github.com/H-Elden/nonebot-plugin-dnddicer
 Project-URL: Issues, https://github.com/H-Elden/nonebot-plugin-dnddicer/issues
 Project-URL: Repository, https://github.com/H-Elden/nonebot-plugin-dnddicer.git
@@ -26,21 +26,23 @@ Requires-Dist: nonebot2[fastapi]<3.0.0,>=2.4.0; extra == 'dev'
 Requires-Dist: nonebug<1.0.0,>=0.4.4; extra == 'dev'
 Requires-Dist: pytest-asyncio<1.0.0,>=0.25.0; extra == 'dev'
 Requires-Dist: pytest<9.0.0,>=8.3.0; extra == 'dev'
+Provides-Extra: render
+Requires-Dist: nonebot-plugin-htmlkit>=0.1.0rc5; extra == 'render'
 Description-Content-Type: text/markdown
 
 # 屠龙骰（DNDDicer / nonebot-plugin-dnddicer）
 
 > 专精 **DND5e / DND5r** 跑团的 [NoneBot2](https://nonebot.dev/) 骰娘插件（OneBot V11 适配器），致力于做功能最全面、体验最好的 DND 骰娘。
 >
-> 当前版本：**v0.2.2** · 完整使用手册见 **📖 [使用文档](https://h-elden.github.io/nonebot-plugin-dnddicer/)**
+> 当前版本：**v0.4.0** · 完整使用手册见 **📖 [使用文档](https://h-elden.github.io/nonebot-plugin-dnddicer/)**
 
 ## ✨ 简介
 
 DNDDicer 的目标是填补「NoneBot 商店中缺少 **DND5e/5r 专业 + 现代维护 + 插件形态** 骰娘」的空位：围绕 DND 跑团全流程持续做深做全，致力于提供功能最全面、体验最好的 DND 骰娘，零配置可加载，供任何已有机器人从商店安装即用。
 
 - **掷骰引擎**：内置 AST 表达式引擎（Lark 文法），支持 `2d20kh1`、优势/劣势、爆炸骰、连掷、暗骰等完整掷骰语法；
-- **跑团全流程**：掷骰 → `.dnd` 属性生成 → 角色卡与检定/豁免/攻击点命令 → HP 管理（伤害掷骰、抗性/易伤、AOE 多目标结算、长休）→ 先攻列表与战斗轮；
-- **规则范围**：仅 DND5e/5r——专精 DND 定位，不做 COC/D100 体系与 `.mode` 模式切换；
+- **跑团全流程**：掷骰 → `.dnd` 属性生成 → 角色卡与检定/豁免点命令 → 自定义武器与攻击（`.X攻击`/`.X伤害`）/ HP 管理（伤害掷骰、抗性/易伤、AOE 多目标结算、长休）→ 先攻列表与战斗轮 → 规则查询（`.查询`/`.搜索`，可限定书目、可出图）；
+- **规则范围**：仅 DND5e/5r：专精 DND 定位，不做 COC/D100 体系与 `.mode` 模式切换；
 - **商店合规**：零配置可加载、本地存储走 `nonebot-plugin-localstore`、元数据完整、全程异步。
 
 ## 📖 使用文档
@@ -48,10 +50,11 @@ DNDDicer 的目标是填补「NoneBot 商店中缺少 **DND5e/5r 专业 + 现代
 详细用法、输入/输出示例与常见问题见使用文档（手册式分章，含跑团示例；**在线版**：<https://h-elden.github.io/nonebot-plugin-dnddicer/>，源文件在仓库 `docs/`）：
 
 - 开始：[快速开始](./docs/guide/quickstart.md) · [示例团与人物](./docs/guide/cast.md)
-- 第一章 · 基础操作：[掷骰基础](./docs/guide/roll-basics.md) · [掷骰进阶](./docs/guide/roll-advanced.md) · [先攻列表](./docs/guide/initiative.md)
-- 第二章 · 进阶操作：[角色卡与属性](./docs/guide/character-card.md) · [检定与豁免](./docs/guide/checks.md) · [HP 与长休](./docs/guide/hp-rest.md) · [战斗轮](./docs/guide/battle.md)
-- 第三章 · DM 操作：[DM 实战指南](./docs/guide/dm-guide.md)
-- 参考 · [命令总览](./docs/guide/overview.md) · [群管理与 FAQ](./docs/guide/faq.md)
+- 第一章 · 基础操作：[掷骰基础](./docs/guide/roll-basics.md) · [掷骰进阶](./docs/guide/roll-advanced.md) · [生命值管理](./docs/guide/hp.md) · [先攻列表](./docs/guide/initiative.md) · [战斗轮](./docs/guide/battle.md) · [规则查询](./docs/guide/query.md)
+- 第二章 · 玩家进阶：[角色卡与属性](./docs/guide/character-card.md) · [检定与豁免](./docs/guide/checks.md) · [武器与攻击](./docs/guide/weapons.md) · [HP 进阶与长休](./docs/guide/hp-advanced.md)
+- 第三章 · DM 进阶：[代掷与代操作](./docs/guide/dm-proxy.md) · [血量与伤害结算](./docs/guide/dm-settlement.md) · [查询范围](./docs/guide/query-scope.md)
+- 第四章 · 最佳实践：[最佳实践](./docs/guide/best-practices.md)
+- 参考：[命令总览](./docs/guide/overview.md) · [群管理与 FAQ](./docs/guide/faq.md) · [自建查询服务](./docs/guide/self-host.md)
 
 ## 📦 安装
 
@@ -87,9 +90,9 @@ plugins = ["nonebot_plugin_dnddicer"]
 
 ## 🎲 用法
 
-> 命令以 `.`（或全角 `。`）开头；命令起始符默认仅 `.` / `。`，如需用宿主斜杠 `/` 等起始符触发（如 `/.help`），请设置配置项 `dnddicer_use_host_command_starts=true`。**群聊服务默认关闭（白名单）**：需群主/管理员发送 `.bot on` 开启本群服务；`.bot off` 关闭后本群不再响应命令（`.bot` 本身不受影响）。群聊中使用 `.bot` 需先 @ 本机器人；私聊不受服务开关限制，但可用命令更少——角色卡、检定、HP、先攻等仅限群聊（差异见[快速开始](./docs/guide/quickstart.md)）。
+> 命令以 `.`（或全角 `。`）开头；命令起始符默认仅 `.` / `。`，如需用宿主斜杠 `/` 等起始符触发（如 `/.help`），请设置配置项 `dnddicer_use_host_command_starts=true`。**群聊服务默认关闭（白名单）**：需群主/管理员发送 `.bot on` 开启本群服务；`.bot off` 关闭后本群不再响应命令（`.bot` 本身不受影响）。群聊中使用 `.bot` 需先 @ 本机器人；私聊不受服务开关限制，但可用命令更少：角色卡、检定、HP、先攻等仅限群聊（差异见[快速开始](./docs/guide/quickstart.md)）。
 >
-> **DM 代操作（@ 提及目标）**：多数带目标的命令支持用 **@群成员** 指定目标——直连该成员在本群的角色卡，不受同名 NPC/改名影响，且可与名称混写（`.hp @玩家 -4d6`、`.hp @玩家;地精 -d4`、`.ri+3 @玩家`、`.init del @玩家`、`.回合 @玩家`、`.角色卡 @玩家`、`.力量豁免 @玩家`、`.先攻检定 @玩家` 等）。详见 [命令总览 - @ 提及目标](./docs/guide/overview.md#-提及目标dm-代操作)。
+> **DM 代操作（@ 提及目标）**：多数带目标的命令支持用 **@群成员** 指定目标：直连该成员在本群的角色卡，不受同名 NPC/改名影响，且可与名称混写（`.hp @玩家 -4d6`、`.hp @玩家;地精 -d4`、`.ri+3 @玩家`、`.init del @玩家`、`.回合 @玩家`、`.角色卡 @玩家`、`.力量豁免 @玩家`、`.先攻检定 @玩家` 等）。完整机制见[代掷与代操作](./docs/guide/dm-proxy.md)，命令清单见[命令总览 - @ 提及目标](./docs/guide/overview.md#提及目标-dm-代操作)。
 
 ### 🎲 掷骰（群聊 / 私聊）
 
@@ -107,9 +110,23 @@ plugins = ["nonebot_plugin_dnddicer"]
 | `.角色卡 @玩家` / `.角色卡 角色名` | 查看**他人**整卡（任何人可查看；记录/清除仅限本人） |
 | `.状态 @玩家` | 查看他人的 HP 与生命骰摘要 |
 | `.力量检定` / `.察觉检定+1` 等 | 属性/技能/先攻检定点命令，自动代入调整值/熟练/加值（`2#` 连掷、`+d4` 等可追加；表达式右侧可加 `@玩家` 代掷） |
-| `.体质豁免` / `.敏捷攻击优势` 等 | 豁免/攻击点命令（原名直配，优势/劣势后缀；同样支持尾部 `@玩家`） |
+| `.体质豁免` / `.感知豁免优势` 等 | 豁免点命令（原名直配，优势/劣势后缀；同样支持尾部 `@玩家`） |
 | `.先攻检定` / `.先攻检定 @玩家` | 掷先攻并自动写入本群先攻列表（@ 形式代不在场的玩家掷） |
 
+### 🗡️ 武器与攻击（群聊）
+
+角色卡通过 `$武器$` 段自定义武器/法术项：`名称+命中加值,伤害表达式+类型`，如 `长剑+8,1d8+5挥砍`；名称尾加 `x` 表示不可攻击检定，如 `火球术x,8d6火焰`。
+
+骰娘只忠实执行、不判 AC、不自动补属性：
+
+| 命令 | 说明 |
+| --- | --- |
+| `.刺剑攻击` / `.刺剑命中` | 用卡上该武器的命中加值掷攻击检定（`优势`/`劣势`、`N#` 连掷、`±` 临时加值、`@玩家` 代掷；天然 20 提示重击） |
+| `.刺剑伤害` | 掷该武器伤害并报出类型；后缀 `副手`（不加任何加值）/ `重击`（骰数翻倍）/ `偷袭`（游荡者按等级自动附加偷袭骰）可组合，尾部可加 `±` 临时加值（如升环 `.火球术伤害+1d6`） |
+| `.设置武器` / `.删除武器` | 维护卡上武器（同名覆盖 / 删除，多个用 `/` 分隔；`.设置武器` 无参数列出当前武器） |
+
+详见 [武器与攻击](./docs/guide/weapons.md)。
+
 ### 🎯 属性生成（群聊 / 私聊）
 
 | 命令 | 说明 |
@@ -117,18 +134,20 @@ plugins = ["nonebot_plugin_dnddicer"]
 | `.dnd [次数] [原因]` | 4D6K3 掷点生成六项属性（附合计与降序，自行分配给六属性） |
 | `.dndx [次数] [原因]` | 4D6K3 掷点并绑定属性名（不排序，掷出即定、可直接抄入角色卡） |
 
-### ❤️ HP 与长休（群聊）
+### ❤️ 生命值管理（群聊）
 
 | 命令 | 说明 |
 | --- | --- |
 | `.hp [对象] 20/30 (5)` | 设置自己/队友/NPC HP（含临时 HP；先 `.ri 名称` 入先攻表后即可记录 NPC 血量） |
-| `.hp [对象] -2d6+3` 等 | 伤害/治疗（支持掷骰表达式；目标后加 `抗性`/`易伤` 后缀可减半/加倍，分号分隔多目标同发结算） |
+| `.hp [对象] -2d6+3` 等 | 伤害/治疗（支持掷骰表达式；伤害位置可直接写 `-武器名伤害`，如 `-战锤重击伤害+1d4`，对应发送者卡上武器项、尾部括号可指定来源代发；目标后加 `抗性`/`易伤` 后缀可减半/加倍，分号分隔多目标同发结算） |
 | `.hp @玩家 …` / `.hp @玩家` | 对 @ 的玩家角色卡结算 / 查看（`.hp @玩家 -4d6`、`.hp @玩家;地精 -d4` 与名称混写；需该玩家已建卡） |
 | `.hp` / `.hp list` | 查看自己 / 本群列表（PC + NPC） |
 | `.hp del 名称` / `.hp clr` | 删除单个 / 清空全部 NPC 血量记录（玩家角色卡请用 `.角色卡清除`，玩家先攻条目用 `.init del`） |
 | `.npc 持久/临时 名称` | NPC 血量跨战斗保持 / 恢复默认（同名 NPC 新入先攻表默认自动回满并提示） |
 | `.长休` / `.长休 @玩家` | 长休结算（回满 HP、清临时 HP、回复一半生命骰）；@ 形式代不在场的玩家收尾 |
 
+> 基础用法见[生命值管理](./docs/guide/hp.md)，武器伤害写法与长休进阶见 [HP 进阶与长休](./docs/guide/hp-advanced.md)，DM 的结算打法见[血量与伤害结算](./docs/guide/dm-settlement.md)。
+
 ### ⚔️ 先攻与战斗轮（群聊）
 
 | 命令 | 说明 |
@@ -142,6 +161,17 @@ plugins = ["nonebot_plugin_dnddicer"]
 | `.回合 @玩家` | 跳转到该玩家的条目（不受改名/同名歧义影响） |
 | `.ed` | 结束当前回合并自动推进（`.结束` 别名） |
 
+### 🔍 规则查询（群聊 / 私聊，需骰主开启）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.查询 <关键词>` / `.搜索 <关键词>` | 按名称 / 全文检索《5e不全书》；多关键词用空格分隔表示同时满足、`\|` 表示或；返回候选后回数字看词条、`+` / `-` 翻页（60 秒内有效、只认发起者本人） |
+| `.查询图片 [on/off]` | 查看 / 切换本处的词条图片显示（群聊按群、私聊按本人；需骰主先开启图片模式，否则报错并回退文字） |
+| `.查询范围 [缩写…]` | 查看 / 收窄本处可查询的书目范围（如 `.查询范围 PHB24,MM25`；`.查询范围 全部` 恢复；不设置即全部开放） |
+| `.规则书` | 列出可设置的书目缩写与中文名对照（骰主开启图片模式时默认出图） |
+
+> 规则查询默认关闭（`dnddicer_query_enabled`）：开启后群聊仍受本群服务开关管辖，私聊可用；查询内容来自《5e不全书》，只用于当次回复与短时内存缓存、不落盘、不随插件分发。详见[规则查询](./docs/guide/query.md)。
+
 ### ⚙️ 群管理（群聊）
 
 | 命令 | 说明 |
@@ -150,16 +180,18 @@ plugins = ["nonebot_plugin_dnddicer"]
 | `.bot [on/off]` | 插件信息查询 / 本群服务开关（群主/管理员，需 @） |
 | `.帮助` / `.help [命令]` | 命令总览 / 指定命令详细用法（如 `.help r`） |
 
-> 一期范围外功能会**显式提示而非静默**：`.r exp` 期望值采样、`.r a/n` 特殊判定；牌堆/随机表与规则查询（T2）、法术位/死亡豁免/BUFF 表（T3 候选）见下方路线。
+> 一期范围外功能会**显式提示而非静默**：`.r exp` 期望值采样、`.r a/n` 特殊判定；牌堆/随机表（T2）与法术位/死亡豁免/BUFF 表（T3 候选）见下方路线。
 
 ## 📄 版本与路线
 
-1. ✅ **v0.1.0**（第一期 = T0 + T1 + 战斗轮简化版 + `.bot` 服务开关）：掷骰引擎移植、`.r/.rh`、帮助、群配置（`.dset`）、角色卡与检定/豁免/攻击、`.dnd` 属性生成、HP 管理与长休（含抗性/易伤与 AOE 伤害掷骰）、先攻列表、战斗轮——全部落地，全量测试通过；
+1. ✅ **v0.1.0**（第一期 = T0 + T1 + 战斗轮简化版 + `.bot` 服务开关）：掷骰引擎移植、`.r/.rh`、帮助、群配置（`.dset`）、角色卡与检定/豁免/攻击、`.dnd` 属性生成、HP 管理与长休（含抗性/易伤与 AOE 伤害掷骰）、先攻列表、战斗轮，全部落地、全量测试通过；
 2. ✅ **v0.2.0**：HP 抗性/易伤与 AOE 掷骰完善、`.dnd 原因` 兼容修复、**NPC/怪物血量**（三层目标搜索、先攻列表与 `.hp list` 联动、`.ri` 入表自动回满、`.npc 持久/临时` 跨战斗保持）、`.dndx` 属性名绑定掷点；
 3. ✅ **v0.2.1**：**@ 提及目标**（DM 可代玩家操作 `.hp`/`.npc`/`.ri`/`.回合` 等、查看角色卡）、玩家名称显示统一回退链、`.hp del/clr` 语义修订（仅作用 NPC 血量）、优势/劣势别名粘连等真机反馈修复；
 4. ✅ **v0.2.2**：掷骰说明文字按四则运算还原（常量复合子表达式与一元负号）、私聊下的群聊限定命令不再静默与 `.bot` 私聊文案修正；**使用文档站上线**（手册式 15 页，随发版自动部署）；
-5. ⏳ **第二期 T2**：牌堆/随机表、规则查询；
-6. ⏳（可选）**T3 增强期**：法术位管理（`.ss/.cast`）、死亡豁免闭环（`.ds`）、BUFF/临时加值表（`.buff`）等。
+5. ✅ **v0.3.0**：**自定义武器与攻击系统**（`$武器$` 段、`.武器名攻击` / `.武器名伤害`、`.设置武器` / `.删除武器`）、`.hp` 伤害位置武器写法（含来源括号代发）；**属性攻击命令退役**（破坏性变更，旧卡需重录）、文档站新增《武器与攻击》页与全站同步；
+6. ✅ **v0.4.0**：**规则查询**（`.查询` / `.搜索` 两种检索、候选选择与翻页、`.查询图片` 图片模式、`.查询范围` 书目限定与 `.规则书`）；**文档站按前置条件重排为四章**（基础操作 / 玩家进阶 / DM 进阶 / 最佳实践）；大成功/大失败播报另起一行、修饰符回显加括号；
+7. ⏳ **第二期余下**：牌堆/随机表；
+8. ⏳（可选）**T3 增强期**：法术位管理（`.ss/.cast`）、死亡豁免闭环（`.ds`）、BUFF/临时加值表（`.buff`）等。
 
 每版完整变更（新增 / 变更 / 修复 / 文档）见 [CHANGELOG.md](./CHANGELOG.md)。
 

{nonebot_plugin_dnddicer-0.2.2 → nonebot_plugin_dnddicer-0.4.0}/README.md

@@ -2,15 +2,15 @@
 
 > 专精 **DND5e / DND5r** 跑团的 [NoneBot2](https://nonebot.dev/) 骰娘插件（OneBot V11 适配器），致力于做功能最全面、体验最好的 DND 骰娘。
 >
-> 当前版本：**v0.2.2** · 完整使用手册见 **📖 [使用文档](https://h-elden.github.io/nonebot-plugin-dnddicer/)**
+> 当前版本：**v0.4.0** · 完整使用手册见 **📖 [使用文档](https://h-elden.github.io/nonebot-plugin-dnddicer/)**
 
 ## ✨ 简介
 
 DNDDicer 的目标是填补「NoneBot 商店中缺少 **DND5e/5r 专业 + 现代维护 + 插件形态** 骰娘」的空位：围绕 DND 跑团全流程持续做深做全，致力于提供功能最全面、体验最好的 DND 骰娘，零配置可加载，供任何已有机器人从商店安装即用。
 
 - **掷骰引擎**：内置 AST 表达式引擎（Lark 文法），支持 `2d20kh1`、优势/劣势、爆炸骰、连掷、暗骰等完整掷骰语法；
-- **跑团全流程**：掷骰 → `.dnd` 属性生成 → 角色卡与检定/豁免/攻击点命令 → HP 管理（伤害掷骰、抗性/易伤、AOE 多目标结算、长休）→ 先攻列表与战斗轮；
-- **规则范围**：仅 DND5e/5r——专精 DND 定位，不做 COC/D100 体系与 `.mode` 模式切换；
+- **跑团全流程**：掷骰 → `.dnd` 属性生成 → 角色卡与检定/豁免点命令 → 自定义武器与攻击（`.X攻击`/`.X伤害`）/ HP 管理（伤害掷骰、抗性/易伤、AOE 多目标结算、长休）→ 先攻列表与战斗轮 → 规则查询（`.查询`/`.搜索`，可限定书目、可出图）；
+- **规则范围**：仅 DND5e/5r：专精 DND 定位，不做 COC/D100 体系与 `.mode` 模式切换；
 - **商店合规**：零配置可加载、本地存储走 `nonebot-plugin-localstore`、元数据完整、全程异步。
 
 ## 📖 使用文档
@@ -18,10 +18,11 @@ DNDDicer 的目标是填补「NoneBot 商店中缺少 **DND5e/5r 专业 + 现代
 详细用法、输入/输出示例与常见问题见使用文档（手册式分章，含跑团示例；**在线版**：<https://h-elden.github.io/nonebot-plugin-dnddicer/>，源文件在仓库 `docs/`）：
 
 - 开始：[快速开始](./docs/guide/quickstart.md) · [示例团与人物](./docs/guide/cast.md)
-- 第一章 · 基础操作：[掷骰基础](./docs/guide/roll-basics.md) · [掷骰进阶](./docs/guide/roll-advanced.md) · [先攻列表](./docs/guide/initiative.md)
-- 第二章 · 进阶操作：[角色卡与属性](./docs/guide/character-card.md) · [检定与豁免](./docs/guide/checks.md) · [HP 与长休](./docs/guide/hp-rest.md) · [战斗轮](./docs/guide/battle.md)
-- 第三章 · DM 操作：[DM 实战指南](./docs/guide/dm-guide.md)
-- 参考 · [命令总览](./docs/guide/overview.md) · [群管理与 FAQ](./docs/guide/faq.md)
+- 第一章 · 基础操作：[掷骰基础](./docs/guide/roll-basics.md) · [掷骰进阶](./docs/guide/roll-advanced.md) · [生命值管理](./docs/guide/hp.md) · [先攻列表](./docs/guide/initiative.md) · [战斗轮](./docs/guide/battle.md) · [规则查询](./docs/guide/query.md)
+- 第二章 · 玩家进阶：[角色卡与属性](./docs/guide/character-card.md) · [检定与豁免](./docs/guide/checks.md) · [武器与攻击](./docs/guide/weapons.md) · [HP 进阶与长休](./docs/guide/hp-advanced.md)
+- 第三章 · DM 进阶：[代掷与代操作](./docs/guide/dm-proxy.md) · [血量与伤害结算](./docs/guide/dm-settlement.md) · [查询范围](./docs/guide/query-scope.md)
+- 第四章 · 最佳实践：[最佳实践](./docs/guide/best-practices.md)
+- 参考：[命令总览](./docs/guide/overview.md) · [群管理与 FAQ](./docs/guide/faq.md) · [自建查询服务](./docs/guide/self-host.md)
 
 ## 📦 安装
 
@@ -57,9 +58,9 @@ plugins = ["nonebot_plugin_dnddicer"]
 
 ## 🎲 用法
 
-> 命令以 `.`（或全角 `。`）开头；命令起始符默认仅 `.` / `。`，如需用宿主斜杠 `/` 等起始符触发（如 `/.help`），请设置配置项 `dnddicer_use_host_command_starts=true`。**群聊服务默认关闭（白名单）**：需群主/管理员发送 `.bot on` 开启本群服务；`.bot off` 关闭后本群不再响应命令（`.bot` 本身不受影响）。群聊中使用 `.bot` 需先 @ 本机器人；私聊不受服务开关限制，但可用命令更少——角色卡、检定、HP、先攻等仅限群聊（差异见[快速开始](./docs/guide/quickstart.md)）。
+> 命令以 `.`（或全角 `。`）开头；命令起始符默认仅 `.` / `。`，如需用宿主斜杠 `/` 等起始符触发（如 `/.help`），请设置配置项 `dnddicer_use_host_command_starts=true`。**群聊服务默认关闭（白名单）**：需群主/管理员发送 `.bot on` 开启本群服务；`.bot off` 关闭后本群不再响应命令（`.bot` 本身不受影响）。群聊中使用 `.bot` 需先 @ 本机器人；私聊不受服务开关限制，但可用命令更少：角色卡、检定、HP、先攻等仅限群聊（差异见[快速开始](./docs/guide/quickstart.md)）。
 >
-> **DM 代操作（@ 提及目标）**：多数带目标的命令支持用 **@群成员** 指定目标——直连该成员在本群的角色卡，不受同名 NPC/改名影响，且可与名称混写（`.hp @玩家 -4d6`、`.hp @玩家;地精 -d4`、`.ri+3 @玩家`、`.init del @玩家`、`.回合 @玩家`、`.角色卡 @玩家`、`.力量豁免 @玩家`、`.先攻检定 @玩家` 等）。详见 [命令总览 - @ 提及目标](./docs/guide/overview.md#-提及目标dm-代操作)。
+> **DM 代操作（@ 提及目标）**：多数带目标的命令支持用 **@群成员** 指定目标：直连该成员在本群的角色卡，不受同名 NPC/改名影响，且可与名称混写（`.hp @玩家 -4d6`、`.hp @玩家;地精 -d4`、`.ri+3 @玩家`、`.init del @玩家`、`.回合 @玩家`、`.角色卡 @玩家`、`.力量豁免 @玩家`、`.先攻检定 @玩家` 等）。完整机制见[代掷与代操作](./docs/guide/dm-proxy.md)，命令清单见[命令总览 - @ 提及目标](./docs/guide/overview.md#提及目标-dm-代操作)。
 
 ### 🎲 掷骰（群聊 / 私聊）
 
@@ -77,9 +78,23 @@ plugins = ["nonebot_plugin_dnddicer"]
 | `.角色卡 @玩家` / `.角色卡 角色名` | 查看**他人**整卡（任何人可查看；记录/清除仅限本人） |
 | `.状态 @玩家` | 查看他人的 HP 与生命骰摘要 |
 | `.力量检定` / `.察觉检定+1` 等 | 属性/技能/先攻检定点命令，自动代入调整值/熟练/加值（`2#` 连掷、`+d4` 等可追加；表达式右侧可加 `@玩家` 代掷） |
-| `.体质豁免` / `.敏捷攻击优势` 等 | 豁免/攻击点命令（原名直配，优势/劣势后缀；同样支持尾部 `@玩家`） |
+| `.体质豁免` / `.感知豁免优势` 等 | 豁免点命令（原名直配，优势/劣势后缀；同样支持尾部 `@玩家`） |
 | `.先攻检定` / `.先攻检定 @玩家` | 掷先攻并自动写入本群先攻列表（@ 形式代不在场的玩家掷） |
 
+### 🗡️ 武器与攻击（群聊）
+
+角色卡通过 `$武器$` 段自定义武器/法术项：`名称+命中加值,伤害表达式+类型`，如 `长剑+8,1d8+5挥砍`；名称尾加 `x` 表示不可攻击检定，如 `火球术x,8d6火焰`。
+
+骰娘只忠实执行、不判 AC、不自动补属性：
+
+| 命令 | 说明 |
+| --- | --- |
+| `.刺剑攻击` / `.刺剑命中` | 用卡上该武器的命中加值掷攻击检定（`优势`/`劣势`、`N#` 连掷、`±` 临时加值、`@玩家` 代掷；天然 20 提示重击） |
+| `.刺剑伤害` | 掷该武器伤害并报出类型；后缀 `副手`（不加任何加值）/ `重击`（骰数翻倍）/ `偷袭`（游荡者按等级自动附加偷袭骰）可组合，尾部可加 `±` 临时加值（如升环 `.火球术伤害+1d6`） |
+| `.设置武器` / `.删除武器` | 维护卡上武器（同名覆盖 / 删除，多个用 `/` 分隔；`.设置武器` 无参数列出当前武器） |
+
+详见 [武器与攻击](./docs/guide/weapons.md)。
+
 ### 🎯 属性生成（群聊 / 私聊）
 
 | 命令 | 说明 |
@@ -87,18 +102,20 @@ plugins = ["nonebot_plugin_dnddicer"]
 | `.dnd [次数] [原因]` | 4D6K3 掷点生成六项属性（附合计与降序，自行分配给六属性） |
 | `.dndx [次数] [原因]` | 4D6K3 掷点并绑定属性名（不排序，掷出即定、可直接抄入角色卡） |
 
-### ❤️ HP 与长休（群聊）
+### ❤️ 生命值管理（群聊）
 
 | 命令 | 说明 |
 | --- | --- |
 | `.hp [对象] 20/30 (5)` | 设置自己/队友/NPC HP（含临时 HP；先 `.ri 名称` 入先攻表后即可记录 NPC 血量） |
-| `.hp [对象] -2d6+3` 等 | 伤害/治疗（支持掷骰表达式；目标后加 `抗性`/`易伤` 后缀可减半/加倍，分号分隔多目标同发结算） |
+| `.hp [对象] -2d6+3` 等 | 伤害/治疗（支持掷骰表达式；伤害位置可直接写 `-武器名伤害`，如 `-战锤重击伤害+1d4`，对应发送者卡上武器项、尾部括号可指定来源代发；目标后加 `抗性`/`易伤` 后缀可减半/加倍，分号分隔多目标同发结算） |
 | `.hp @玩家 …` / `.hp @玩家` | 对 @ 的玩家角色卡结算 / 查看（`.hp @玩家 -4d6`、`.hp @玩家;地精 -d4` 与名称混写；需该玩家已建卡） |
 | `.hp` / `.hp list` | 查看自己 / 本群列表（PC + NPC） |
 | `.hp del 名称` / `.hp clr` | 删除单个 / 清空全部 NPC 血量记录（玩家角色卡请用 `.角色卡清除`，玩家先攻条目用 `.init del`） |
 | `.npc 持久/临时 名称` | NPC 血量跨战斗保持 / 恢复默认（同名 NPC 新入先攻表默认自动回满并提示） |
 | `.长休` / `.长休 @玩家` | 长休结算（回满 HP、清临时 HP、回复一半生命骰）；@ 形式代不在场的玩家收尾 |
 
+> 基础用法见[生命值管理](./docs/guide/hp.md)，武器伤害写法与长休进阶见 [HP 进阶与长休](./docs/guide/hp-advanced.md)，DM 的结算打法见[血量与伤害结算](./docs/guide/dm-settlement.md)。
+
 ### ⚔️ 先攻与战斗轮（群聊）
 
 | 命令 | 说明 |
@@ -112,6 +129,17 @@ plugins = ["nonebot_plugin_dnddicer"]
 | `.回合 @玩家` | 跳转到该玩家的条目（不受改名/同名歧义影响） |
 | `.ed` | 结束当前回合并自动推进（`.结束` 别名） |
 
+### 🔍 规则查询（群聊 / 私聊，需骰主开启）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.查询 <关键词>` / `.搜索 <关键词>` | 按名称 / 全文检索《5e不全书》；多关键词用空格分隔表示同时满足、`\|` 表示或；返回候选后回数字看词条、`+` / `-` 翻页（60 秒内有效、只认发起者本人） |
+| `.查询图片 [on/off]` | 查看 / 切换本处的词条图片显示（群聊按群、私聊按本人；需骰主先开启图片模式，否则报错并回退文字） |
+| `.查询范围 [缩写…]` | 查看 / 收窄本处可查询的书目范围（如 `.查询范围 PHB24,MM25`；`.查询范围 全部` 恢复；不设置即全部开放） |
+| `.规则书` | 列出可设置的书目缩写与中文名对照（骰主开启图片模式时默认出图） |
+
+> 规则查询默认关闭（`dnddicer_query_enabled`）：开启后群聊仍受本群服务开关管辖，私聊可用；查询内容来自《5e不全书》，只用于当次回复与短时内存缓存、不落盘、不随插件分发。详见[规则查询](./docs/guide/query.md)。
+
 ### ⚙️ 群管理（群聊）
 
 | 命令 | 说明 |
@@ -120,16 +148,18 @@ plugins = ["nonebot_plugin_dnddicer"]
 | `.bot [on/off]` | 插件信息查询 / 本群服务开关（群主/管理员，需 @） |
 | `.帮助` / `.help [命令]` | 命令总览 / 指定命令详细用法（如 `.help r`） |
 
-> 一期范围外功能会**显式提示而非静默**：`.r exp` 期望值采样、`.r a/n` 特殊判定；牌堆/随机表与规则查询（T2）、法术位/死亡豁免/BUFF 表（T3 候选）见下方路线。
+> 一期范围外功能会**显式提示而非静默**：`.r exp` 期望值采样、`.r a/n` 特殊判定；牌堆/随机表（T2）与法术位/死亡豁免/BUFF 表（T3 候选）见下方路线。
 
 ## 📄 版本与路线
 
-1. ✅ **v0.1.0**（第一期 = T0 + T1 + 战斗轮简化版 + `.bot` 服务开关）：掷骰引擎移植、`.r/.rh`、帮助、群配置（`.dset`）、角色卡与检定/豁免/攻击、`.dnd` 属性生成、HP 管理与长休（含抗性/易伤与 AOE 伤害掷骰）、先攻列表、战斗轮——全部落地，全量测试通过；
+1. ✅ **v0.1.0**（第一期 = T0 + T1 + 战斗轮简化版 + `.bot` 服务开关）：掷骰引擎移植、`.r/.rh`、帮助、群配置（`.dset`）、角色卡与检定/豁免/攻击、`.dnd` 属性生成、HP 管理与长休（含抗性/易伤与 AOE 伤害掷骰）、先攻列表、战斗轮，全部落地、全量测试通过；
 2. ✅ **v0.2.0**：HP 抗性/易伤与 AOE 掷骰完善、`.dnd 原因` 兼容修复、**NPC/怪物血量**（三层目标搜索、先攻列表与 `.hp list` 联动、`.ri` 入表自动回满、`.npc 持久/临时` 跨战斗保持）、`.dndx` 属性名绑定掷点；
 3. ✅ **v0.2.1**：**@ 提及目标**（DM 可代玩家操作 `.hp`/`.npc`/`.ri`/`.回合` 等、查看角色卡）、玩家名称显示统一回退链、`.hp del/clr` 语义修订（仅作用 NPC 血量）、优势/劣势别名粘连等真机反馈修复；
 4. ✅ **v0.2.2**：掷骰说明文字按四则运算还原（常量复合子表达式与一元负号）、私聊下的群聊限定命令不再静默与 `.bot` 私聊文案修正；**使用文档站上线**（手册式 15 页，随发版自动部署）；
-5. ⏳ **第二期 T2**：牌堆/随机表、规则查询；
-6. ⏳（可选）**T3 增强期**：法术位管理（`.ss/.cast`）、死亡豁免闭环（`.ds`）、BUFF/临时加值表（`.buff`）等。
+5. ✅ **v0.3.0**：**自定义武器与攻击系统**（`$武器$` 段、`.武器名攻击` / `.武器名伤害`、`.设置武器` / `.删除武器`）、`.hp` 伤害位置武器写法（含来源括号代发）；**属性攻击命令退役**（破坏性变更，旧卡需重录）、文档站新增《武器与攻击》页与全站同步；
+6. ✅ **v0.4.0**：**规则查询**（`.查询` / `.搜索` 两种检索、候选选择与翻页、`.查询图片` 图片模式、`.查询范围` 书目限定与 `.规则书`）；**文档站按前置条件重排为四章**（基础操作 / 玩家进阶 / DM 进阶 / 最佳实践）；大成功/大失败播报另起一行、修饰符回显加括号；
+7. ⏳ **第二期余下**：牌堆/随机表；
+8. ⏳（可选）**T3 增强期**：法术位管理（`.ss/.cast`）、死亡豁免闭环（`.ds`）、BUFF/临时加值表（`.buff`）等。
 
 每版完整变更（新增 / 变更 / 修复 / 文档）见 [CHANGELOG.md](./CHANGELOG.md)。
 

{nonebot_plugin_dnddicer-0.2.2 → nonebot_plugin_dnddicer-0.4.0}/docs/.vitepress/config.mts

@@ -8,7 +8,7 @@ export default defineConfig({
   lang: 'zh-CN',
   title: '屠龙骰 DNDDicer',
   description:
-    '专精 DND5e/5r 的 QQ 跑团骰娘插件使用文档：掷骰表达式、角色卡与属性、检定与豁免、HP 管理、先攻列表与战斗轮',
+    '专精 DND5e/5r 的 QQ 跑团骰娘插件使用文档：掷骰表达式、角色卡与属性、检定与豁免、生命值管理、先攻列表与战斗轮、规则查询、DM 进阶与最佳实践',
   base: '/nonebot-plugin-dnddicer/',
   cleanUrls: true,
   lastUpdated: true,
@@ -41,27 +41,39 @@ export default defineConfig({
         items: [
           { text: '掷骰基础', link: '/guide/roll-basics' },
           { text: '掷骰进阶', link: '/guide/roll-advanced' },
+          { text: '生命值管理', link: '/guide/hp' },
           { text: '先攻列表', link: '/guide/initiative' },
+          { text: '战斗轮', link: '/guide/battle' },
+          { text: '规则查询', link: '/guide/query' },
         ],
       },
       {
-        text: '第二章 · 进阶操作',
+        text: '第二章 · 玩家进阶',
         items: [
           { text: '角色卡与属性', link: '/guide/character-card' },
           { text: '检定与豁免', link: '/guide/checks' },
-          { text: 'HP 与长休', link: '/guide/hp-rest' },
-          { text: '战斗轮', link: '/guide/battle' },
+          { text: '武器与攻击', link: '/guide/weapons' },
+          { text: 'HP 进阶与长休', link: '/guide/hp-advanced' },
+        ],
+      },
+      {
+        text: '第三章 · DM 进阶',
+        items: [
+          { text: '代掷与代操作', link: '/guide/dm-proxy' },
+          { text: '血量与伤害结算', link: '/guide/dm-settlement' },
+          { text: '查询范围', link: '/guide/query-scope' },
         ],
       },
       {
-        text: '第三章 · DM 操作',
-        items: [{ text: 'DM 实战指南', link: '/guide/dm-guide' }],
+        text: '第四章 · 最佳实践',
+        items: [{ text: '最佳实践', link: '/guide/best-practices' }],
       },
       {
         text: '参考',
         items: [
           { text: '命令总览', link: '/guide/overview' },
           { text: '群管理与 FAQ', link: '/guide/faq' },
+          { text: '自建查询服务（可选）', link: '/guide/self-host' },
           { text: '更新日志', link: '/guide/changelog' },
         ],
       },

{nonebot_plugin_dnddicer-0.2.2 → nonebot_plugin_dnddicer-0.4.0}/docs/guide/battle.md

@@ -25,7 +25,7 @@
 > 
 > `.br` 播「已创建新战斗轮」面向开局，`.init clr` 播「已清除先攻列表」面向清表。
 > 
-> 战斗结束后不必专门收尾命令——不再推进即可，下次 `.br` 重新开局。
+> 战斗结束后不必专门收尾命令，不再推进即可，下次 `.br` 重新开局。
 
 开局后全员掷先攻（`.ri` / `.先攻检定`），就绪的列表形如：
 
@@ -75,7 +75,7 @@
 新的一轮，现在是第2轮。
 现在是塔莉的回合。请玩家@老猫开始行动。
 
-注：一轮走完自动进位——先播「新的一轮」，再播下一位行动者。
+注：一轮走完自动进位：先播「新的一轮」，再播下一位行动者。
 :::
 
 > 回合流转只需记住三条：
@@ -108,7 +108,7 @@
 | `.回合+2` / `.回合-1` | 前进 / 后退若干位（越界自动进位、退位轮次） |
 | `.回合=3` | 直接跳到本轮第 3 位（越界报错） |
 | `.回合 名字` | 按名称跳转（精确优先、其次部分匹配） |
-| `.回合 @玩家` | 按归属跳转——不受改名与同名歧义影响 |
+| `.回合 @玩家` | 按归属跳转，不受改名与同名歧义影响 |
 | `.轮次+1` / `.轮次=3` | 调整轮次（只动轮次，回合指针按越界规则修正） |
 
 ## 常见提示
@@ -149,7 +149,7 @@
 
 - **没有 BUFF 计时表**：本轮中自动到期的效果（祝福术、持续时间…）由 DM 手动记、手动撤；
 - 条目显示的是**入表时快照的名称**；玩家改名不影响已入表的条目（`.回合 @玩家` 按归属定位，改名照常生效）；
-- `.init clr` / `.br` 会一并清理 NPC 的临时血量（详见[HP 与长休](./hp-rest.md#查看与清理)）。
+- `.init clr` / `.br` 会一并清理 NPC 的临时血量（详见[生命值管理](./hp.md#查看与清理)）。
 
 ## 相关命令
 
@@ -160,4 +160,4 @@
 | `.轮次` | `.轮次`、`.轮次+1`、`.轮次=3` | 查看 / 调整轮次 |
 | `.ed` / `.结束` | `.ed` | 结束当前回合并自动推进；一处清表用 `.init clr` |
 
-上一站：[HP 与长休](./hp-rest.md)；战场之外（群管理、帮助、默认骰面）见[群管理与 FAQ](./faq.md)。
+上一站：[先攻列表](./initiative.md)；接下来：[规则查询](./query.md)：把规则原文查到手。战场之外（群管理、帮助、默认骰面）见[群管理与 FAQ](./faq.md)。