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

{nonebot_plugin_dnddicer-0.2.0 → nonebot_plugin_dnddicer-0.2.2}/.gitattributes

@@ -12,6 +12,13 @@
 *.lock text eol=lf
 *.gitignore text eol=lf
 *.gitattributes text eol=lf
+# 文档站（VitePress）前端文件
+*.mts text eol=lf
+*.ts text eol=lf
+*.js text eol=lf
+*.mjs text eol=lf
+*.css text eol=lf
+*.vue text eol=lf
 
 # 二进制文件不转换
 *.png binary

nonebot_plugin_dnddicer-0.2.2/.github/workflows/docs.yml

@@ -0,0 +1,75 @@
+# 文档站部署（GitHub Pages）
+#
+# 触发时机 = 发布时机：只有推 v* 标签（发版）或手动触发时才构建并部署。
+# 平时往 main 推送的文档改动只留在仓库里，不会改变线上页面——
+# 需要让某个改动上线时，要么随下一次发版，要么在 Actions 里手动运行本工作流。
+#
+# 首次使用：仓库 Settings → Pages → Source 选「GitHub Actions」。
+# 未启用前本工作流会自动跳过（保持绿色），启用后无需再改任何配置。
+name: docs
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    outputs:
+      enabled: ${{ steps.pages.outputs.enabled }}
+    steps:
+      - name: 检查 Pages 是否已启用
+        id: pages
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh api "repos/$GITHUB_REPOSITORY/pages" > /dev/null 2>&1; then
+            echo "enabled=true" >> "$GITHUB_OUTPUT"
+            echo "Pages 已启用，继续构建与部署。"
+          else
+            echo "enabled=false" >> "$GITHUB_OUTPUT"
+            echo "::notice title=文档站尚未启用::仓库 Settings → Pages 还没把 Source 选为 GitHub Actions，跳过本次部署；启用后手动运行本工作流、或等下一次发版即可。"
+          fi
+
+  build:
+    needs: check
+    if: needs.check.outputs.enabled == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: package-lock.json
+      - name: 安装文档站依赖
+        run: npm ci
+      # docs:build 自带「从 CHANGELOG.md 生成《更新日志》页」一步，站点更新日志随仓库同步
+      - name: 构建文档站
+        run: npm run docs:build
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: 部署到 GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

nonebot_plugin_dnddicer-0.2.2/.github/workflows/release.yml

@@ -0,0 +1,68 @@
+# 推 v* tag → 全量测试 → 构建并发布 PyPI（Trusted Publishing）+ 创建 GitHub Release
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: 全量测试
+        run: uv run pytest
+
+  release:
+    needs: test
+    runs-on: ubuntu-latest
+    permissions:
+      # 建 GitHub Release
+      contents: write
+      # PyPI Trusted Publishing（OIDC），无需存储 token
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      # 先于构建/发布校验并提取本版说明：缺小节时直接失败，不会出现「PyPI 已发、Release 没说明」的半成品
+      - name: 提取 CHANGELOG 本版说明
+        run: |
+          python3 - <<'PY'
+          import os, re, sys
+
+          version = os.environ["GITHUB_REF_NAME"].removeprefix("v")
+          lines = open("CHANGELOG.md", encoding="utf-8").read().splitlines()
+          body, capture = [], False
+          for line in lines:
+              if line.startswith("## "):
+                  if capture:
+                      break
+                  capture = re.match(rf"^##\s*\[?{re.escape(version)}\]?(?:\s|$)", line) is not None
+                  continue
+              if capture:
+                  body.append(line)
+          notes = "\n".join(body).strip()
+          if not notes:
+              sys.exit(f"CHANGELOG.md 中没有 {version} 的小节：请先补写该版本小节并提交，再重新打标签发布。")
+          with open(".release-notes.md", "w", encoding="utf-8") as f:
+              f.write(notes + "\n")
+          print(notes)
+          PY
+      - uses: astral-sh/setup-uv@v6
+      - name: 构建 sdist + wheel
+        run: uv build
+      - name: 发布到 PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+      - name: 创建 GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          # 正文取自 CHANGELOG 对应版本小节；generate_release_notes 再自动追加 Full Changelog 链接
+          body_path: .release-notes.md
+          generate_release_notes: true

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

@@ -39,3 +39,11 @@ doc/
 .idea/
 .DS_Store
 Thumbs.db
+
+# ---- 发布流程临时产物（release workflow 提取的 Release 正文；本地试跑同名脚本时也会生成）----
+.release-notes.md
+
+# ---- 文档站（VitePress，仅构建文档用，不进发布产物）----
+node_modules/
+docs/.vitepress/dist/
+docs/.vitepress/cache/

nonebot_plugin_dnddicer-0.2.2/CHANGELOG.md

@@ -0,0 +1,84 @@
+# 更新日志
+
+本文件按版本记录对外变化，分「新增 / 变更 / 修复 / 文档」四组，表述面向使用者（跑团玩家与 DM）。
+
+<!-- 维护说明（渲染时不可见）：
+
+- 条目一律一条目一整行、不做软换行：本文件小节的正文会原样成为 GitHub Release 正文，而 Release 页面按「issue 式」渲染，单个换行会被渲染为真实换行。
+- 打 `v*` 标签前，请先在下方补好该版本的小节（标题格式 `## [x.y.z] - 日期`）：发布时 `.github/workflows/release.yml` 会提取与所推标签同名的小节作为 GitHub Release 的说明正文，缺小节即会在构建前直接失败。
+-->
+
+## [0.2.2] - 2026-09-24
+
+### 变更
+
+- **定位表述统一**：`.bot` 插件简介与插件元数据描述更新为「功能最全面、体验最好的 DND 骰娘」口径，清理旧的对齐式表述（掷骰引擎上游来源的致谢仅保留在许可位置）。
+
+### 修复
+
+- **掷骰说明文字按四则运算还原**：修复算式说明里常量复合子表达式与一元负号的错位——如 `.rd6+2*2` 旧显示为 `1D6+2*2=[4]*2+4=8`（乘号挪用了骰块）、`-1d6+3` 丢负号、`12/(1+2)`、`3*d6` 同类错显；说明文字现与表达式结构一一对应，骰子结果与取骰规则不变。
+- **私聊下的群聊限定命令不再静默**：角色卡、检定/豁免/攻击点、HP、先攻与战斗轮等按群归属的命令在私聊中发送时，会如常收到「该指令仅在群聊中可用。」提示（此前部分命令族没有回应）。
+- **`.bot` 私聊回应文案修正**：不再写「私聊可直接使用本插件的全部功能」，改为如实说明私聊可用范围（掷骰、属性生成、`.帮助` 等可用；角色卡、检定、HP、先攻与战斗轮、群配置等仅限群聊）。
+
+### 文档
+
+- **使用文档站上线**：手册式 15 页（快速开始、三章教程、参考组、更新日志），配固定示例团的真实取证示例；推 `v*` 标签时自动构建并部署到 GitHub Pages。
+- README 改为手册式目录并挂文档站入口；全站正文统一骰记法（D20 等）与命令示例的最简写法。
+
+## [0.2.1] - 2026-09-22
+
+### 新增
+
+- **@ 提及目标（DM 代操作）**：`.hp`、`.npc`、`.ri`、`.init del|first|swap`、`.回合`、`.角色卡`（可查看他人整卡，记录/清除仍仅限本人）、`.状态`、`.长休` 以及各检定点命令（含 `.先攻检定`）均可直接 @ 某位玩家，作用于其角色卡或先攻条目；游离的 @ 会被拦截并提示，不再静默按自己处理（此前 `.hp @玩家 -d4` 会误扣自己血量）。
+- **玩家名称显示统一**：凡是需要显示玩家名的场景（`.r`/`.rh`、`.dnd`/`.dndx`、检定反馈、`.hp`、`.ri` 入表名等）统一按「角色卡名 → 群名片 → QQ 昵称 → 未知玩家（QQ号）」回退，末端兜底附带 QQ 号，便于 DM 定位是谁。
+
+### 变更
+
+- `.hp del` / `.hp clr` 语义修订为**仅作用于 NPC 血量**：`del` 删除指定 NPC（支持 `/` 分隔多名称）、`clr` 清空本群全部 NPC 血量（含跨战斗保持的）；无对象时只提示用法，目标解析到玩家角色卡时改为引导使用 `.角色卡清除`，不再直接删除整张角色卡。
+
+### 修复
+
+- 优势/劣势别名粘连：`.rd劣势20+6` 这类面数错序写法不再被静默改写成错误骰式，改为报错引导；`K`/`KL` 取点超量时给出报错而非错误结果。
+- `.hp` 目标匹配改为完全匹配优先（与 `.init` 一致）：修复「地精」与「熊精」并存时 `.hp 地精` 命中错对象、`.hp del 地精` 删不掉的问题。
+- 伤害/治疗结算最低为 0：修复伤害掷出负值后经抗性/易伤计算反而变成回血的问题；治疗为 0 时不再触发昏迷唤醒。
+- `.hp` 目标未命中时补充引导提示（新建 NPC 需先加入先攻表才能设置 HP）；回满提示中的命令独立成行，便于直接复制。
+
+### 文档
+
+- README 命令表与使用文档（角色卡 / HP 管理 / 先攻列表 / 战斗轮 / 快速开始）补充 @ 用法与示例。
+
+## [0.2.0] - 2026-09-21
+
+### 新增
+
+- **NPC / 怪物血量**：`.hp` 目标搜索扩展为三层（玩家角色卡 → NPC 血量 → 先攻表，NPC 经先攻表按需建立记录）；先攻列表与 `.hp list` 显示 NPC 血量，`.hp del` 支持指定对象；`.init clr` / `.br` 清理未设最大值的临时血量，`.init del` 连带删除对应记录。
+- **NPC 血量自动回满与跨战斗保持**：同名 NPC 以新条目加入先攻表时自动回满并给出提示（同一场战斗内重掷不触发）；`.npc 持久` / `.npc 临时` 控制血量是否跨战斗保持。
+- **`.dndx` 属性名绑定掷点**：4D6K3 掷点后将六项数值按固定顺序绑定力量/敏捷/体质/智力/感知/魅力（不降序排列，掷出即定配对，可直接抄入角色卡），与 `.dnd` 并存。
+
+### 修复
+
+- `.dnd` 原因参数不再被静默丢弃：首词不是数字时整段视为原因（如 `.dnd 开卡`），分隔符放宽为任意空白。
+
+### 文档
+
+- HP 管理新增「NPC / 怪物血量」章节；先攻列表、战斗轮、FAQ、命令总表与 README 同步。
+
+## [0.1.1] - 2026-09-10
+
+### 修复
+
+- 依赖下限放宽至 NoneBot2 ≥ 2.4.0：兼容仍运行 2.4.x 的宿主（已在 2.4.0 环境实测全量测试通过）。
+
+## [0.1.0] - 2026-09-10
+
+首个公开版本：第一期功能全部落地。
+
+### 新增
+
+- **掷骰**：`.r` / `.rh`——优势/劣势、保留最高、重掷、爆炸骰、连掷、暗骰、原因后缀、群默认骰面；仅 D20 出目 20/1 播报大成功/大失败。
+- **角色卡与检定**：`.角色卡` / `.状态`（`$…$` 模板建卡，`.角色卡模板` 输出模板）；检定/豁免/攻击点命令自动代入调整值、熟练与额外加值。
+- **属性生成**：`.dnd`（4D6K3 掷点）。
+- **HP 管理与长休**：`.hp`（查看 / 结算 / 列表 / 删除）、抗性/易伤与 AOE 伤害掷骰、`.长休`。
+- **先攻列表**：`.init`（子指令）、`.ri`、`.先攻`，`.先攻检定` 与角色卡联动。
+- **战斗轮**：`.br` / `.ed` / `.回合` / `.轮次`。
+- **群配置与帮助**：`.dset` 群默认骰面、`.帮助` / `.help`、`.bot` 插件信息与群聊服务开关（群聊默认关闭，需 @ 机器人触发）。

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: nonebot-plugin-dnddicer
-Version: 0.2.0
-Summary: 专精 DND5e/5r 跑团的 NoneBot2 骰娘插件（屠龙骰）：掷骰表达式、角色卡与检定、属性生成、HP 管理、先攻列表、战斗轮等，命令手感对齐 nonebot-dicepp
+Version: 0.2.2
+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
@@ -30,32 +30,28 @@ Description-Content-Type: text/markdown
 
 # 屠龙骰（DNDDicer / nonebot-plugin-dnddicer）
 
-> 专精 **DND5e / DND5r** 跑团的 [NoneBot2](https://nonebot.dev/) 骰娘插件（OneBot V11 适配器），
-> 命令手感对齐 [nonebot-dicepp](https://github.com/pear-studio/nonebot-dicepp)（梨骰）。
+> 专精 **DND5e / DND5r** 跑团的 [NoneBot2](https://nonebot.dev/) 骰娘插件（OneBot V11 适配器），致力于做功能最全面、体验最好的 DND 骰娘。
 >
-> 当前版本：**v0.2.0** · 完整使用手册见 **📖 [使用文档](./docs/index.md)**
+> 当前版本：**v0.2.2** · 完整使用手册见 **📖 [使用文档](https://h-elden.github.io/nonebot-plugin-dnddicer/)**
 
 ## ✨ 简介
 
-DNDDicer 的目标是填补「NoneBot 商店中缺少 **DND5e/5r 专业 + 现代维护 + 插件形态** 骰娘」的空位：
-以 DicePP 掷骰引擎与命令手感为基准，做独立的、零配置可加载的 NoneBot 插件，供任何已有
-机器人从商店安装即用。
+DNDDicer 的目标是填补「NoneBot 商店中缺少 **DND5e/5r 专业 + 现代维护 + 插件形态** 骰娘」的空位：围绕 DND 跑团全流程持续做深做全，致力于提供功能最全面、体验最好的 DND 骰娘，零配置可加载，供任何已有机器人从商店安装即用。
 
-- **掷骰引擎**：移植 nonebot-dicepp 的 AST 表达式引擎（Lark 文法），支持 `2d20kh1`、
-  优势/劣势、爆炸骰、连掷、暗骰等 DicePP 完整语法面；
-- **跑团全流程**：掷骰 → `.dnd` 属性生成 → 角色卡与检定/豁免/攻击点命令 → HP 管理
-  （伤害掷骰、抗性/易伤、AOE 多目标结算、长休）→ 先攻列表与战斗轮；
-- **规则范围**：仅 DND5e/5r——专精 DND 定位，不做 COC/d100 体系与 `.mode` 模式切换；
+- **掷骰引擎**：内置 AST 表达式引擎（Lark 文法），支持 `2d20kh1`、优势/劣势、爆炸骰、连掷、暗骰等完整掷骰语法；
+- **跑团全流程**：掷骰 → `.dnd` 属性生成 → 角色卡与检定/豁免/攻击点命令 → HP 管理（伤害掷骰、抗性/易伤、AOE 多目标结算、长休）→ 先攻列表与战斗轮；
+- **规则范围**：仅 DND5e/5r——专精 DND 定位，不做 COC/D100 体系与 `.mode` 模式切换；
 - **商店合规**：零配置可加载、本地存储走 `nonebot-plugin-localstore`、元数据完整、全程异步。
 
 ## 📖 使用文档
 
-详细用法、输入/输出示例与常见问题见仓库 `docs/` 使用文档：
+详细用法、输入/输出示例与常见问题见使用文档（手册式分章，含跑团示例；**在线版**：<https://h-elden.github.io/nonebot-plugin-dnddicer/>，源文件在仓库 `docs/`）：
 
-- [命令总表与快速开始](./docs/index.md) · [群管理与 FAQ](./docs/guide/faq.md)
-- [掷骰语法](./docs/guide/roll-syntax.md) · [角色卡与检定](./docs/guide/character-card.md)
-- [属性生成](./docs/guide/attributes.md) · [HP 管理](./docs/guide/hp-rest.md)
-- [先攻列表](./docs/guide/initiative.md) · [战斗轮](./docs/guide/battle.md)
+- 开始：[快速开始](./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)
 
 ## 📦 安装
 
@@ -85,23 +81,21 @@ plugins = ["nonebot_plugin_dnddicer"]
 | 配置项 | 类型 | 默认值 | 说明 |
 | --- | --- | --- | --- |
 | `dnddicer_command_priority` | `int` | `10` | 命令事件响应器基础优先级（越小越优先），与其他插件冲突时按需调整 |
-| `dnddicer_default_face` | `int` | `20` | 全局默认骰面（DND 惯例 d20；已配置 `.dset` 的群以群配置为准，此项作兜底） |
+| `dnddicer_default_face` | `int` | `20` | 全局默认骰面（DND 惯例 D20；已配置 `.dset` 的群以群配置为准，此项作兜底） |
 | `dnddicer_enabled` | `bool` | `true` | 功能总开关，`false` 时只加载骨架、不注册命令 |
 | `dnddicer_use_host_command_starts` | `bool` | `false` | 是否兼容宿主 `COMMAND_START` 起始符（NoneBot 默认 `/`，开启后 `/.help` 等亦可触发）。默认只匹配 `.` / `。`，避免 `/help`、`/bot` 等常见单词命令与其他插件同时命中（冲突） |
 
 ## 🎲 用法
 
-> 命令以 `.`（或全角 `。`）开头，中英文别名对齐 DicePP；命令起始符默认仅 `.` / `。`，
-> 如需用宿主斜杠 `/` 等起始符触发（如 `/.help`），请设置配置项 `dnddicer_use_host_command_starts=true`。
-> **群聊服务默认关闭（白名单）**：需群主/管理员发送 `.bot on` 开启本群服务；`.bot off`
-> 关闭后本群不再响应命令（`.bot` 本身不受影响）。群聊中使用 `.bot` 需先 @ 本机器人；
-> 私聊不受服务开关限制，可直接使用全部功能。
+> 命令以 `.`（或全角 `。`）开头；命令起始符默认仅 `.` / `。`，如需用宿主斜杠 `/` 等起始符触发（如 `/.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-代操作)。
 
 ### 🎲 掷骰（群聊 / 私聊）
 
 | 命令 | 说明 |
 | --- | --- |
-| `.r [N#][hs][表达式] [原因]` | 掷骰表达式（`#` 连掷 1~10、`h` 暗骰、`s` 只显数值；仅 d20 有大成功/大失败播报） |
+| `.r [N#][hs][表达式] [原因]` | 掷骰表达式（`#` 连掷 1~10、`h` 暗骰、`s` 只显数值；仅 D20 有大成功/大失败播报） |
 | `.rh [表达式] [原因]` | 暗骰（群内提示、结果私聊） |
 
 ### 📋 角色卡与检定（群聊）
@@ -110,9 +104,11 @@ plugins = ["nonebot_plugin_dnddicer"]
 | --- | --- |
 | `.角色卡模板` / `.角色卡记录 <模板>` | 查看示例卡 / 记录或覆盖角色卡（`$…$` 分段模板） |
 | `.角色卡` / `.角色卡清除` / `.状态` | 查看 / 删除角色卡 / 查看 HP 与生命骰摘要 |
-| `.力量检定` / `.察觉检定+1` 等 | 属性/技能/先攻检定点命令，自动代入调整值/熟练/加值（`2#` 连掷、`+d4` 等可追加） |
-| `.体质豁免` / `.敏捷攻击优势` 等 | 豁免/攻击点命令（原名直配，优势/劣势后缀） |
-| `.先攻检定` | 掷先攻并自动写入本群先攻列表 |
+| `.角色卡 @玩家` / `.角色卡 角色名` | 查看**他人**整卡（任何人可查看；记录/清除仅限本人） |
+| `.状态 @玩家` | 查看他人的 HP 与生命骰摘要 |
+| `.力量检定` / `.察觉检定+1` 等 | 属性/技能/先攻检定点命令，自动代入调整值/熟练/加值（`2#` 连掷、`+d4` 等可追加；表达式右侧可加 `@玩家` 代掷） |
+| `.体质豁免` / `.敏捷攻击优势` 等 | 豁免/攻击点命令（原名直配，优势/劣势后缀；同样支持尾部 `@玩家`） |
+| `.先攻检定` / `.先攻检定 @玩家` | 掷先攻并自动写入本群先攻列表（@ 形式代不在场的玩家掷） |
 
 ### 🎯 属性生成（群聊 / 私聊）
 
@@ -127,18 +123,23 @@ plugins = ["nonebot_plugin_dnddicer"]
 | --- | --- |
 | `.hp [对象] 20/30 (5)` | 设置自己/队友/NPC HP（含临时 HP；先 `.ri 名称` 入先攻表后即可记录 NPC 血量） |
 | `.hp [对象] -2d6+3` 等 | 伤害/治疗（支持掷骰表达式；目标后加 `抗性`/`易伤` 后缀可减半/加倍，分号分隔多目标同发结算） |
-| `.hp` / `.hp list` / `.hp del [对象]` | 查看自己 / 本群列表（PC + NPC）/ 删除 |
+| `.hp @玩家 …` / `.hp @玩家` | 对 @ 的玩家角色卡结算 / 查看（`.hp @玩家 -4d6`、`.hp @玩家;地精 -d4` 与名称混写；需该玩家已建卡） |
+| `.hp` / `.hp list` | 查看自己 / 本群列表（PC + NPC） |
+| `.hp del 名称` / `.hp clr` | 删除单个 / 清空全部 NPC 血量记录（玩家角色卡请用 `.角色卡清除`，玩家先攻条目用 `.init del`） |
 | `.npc 持久/临时 名称` | NPC 血量跨战斗保持 / 恢复默认（同名 NPC 新入先攻表默认自动回满并提示） |
-| `.长休` | 长休结算（回满 HP、清临时 HP、回复一半生命骰） |
+| `.长休` / `.长休 @玩家` | 长休结算（回满 HP、清临时 HP、回复一半生命骰）；@ 形式代不在场的玩家收尾 |
 
 ### ⚔️ 先攻与战斗轮（群聊）
 
 | 命令 | 说明 |
 | --- | --- |
 | `.ri[修正] [名称/…]` | 掷先攻入表（`.ri20 地精` 固定值、`3#` 批量、`.先攻` 别名） |
+| `.ri+3 @玩家` | 代不在场的玩家掷先攻：条目名取角色卡名并与该玩家绑定（重掷替换、回合提醒与 `.hp` 解析同步生效） |
 | `.init` | 查看先攻列表（`del`/`clr`/`first`/`swap` 子指令） |
+| `.init del/first/swap @玩家` | 子指令按玩家归属定位条目（角色卡改名后仍有效；未入表会给出提示） |
 | `.br` | 新建战斗轮（清空先攻表） |
 | `.回合` / `.轮次` | 查看/跳转当前回合与轮次（`.回合+2` 连续推进，轮到玩家自动 @ 提醒） |
+| `.回合 @玩家` | 跳转到该玩家的条目（不受改名/同名歧义影响） |
 | `.ed` | 结束当前回合并自动推进（`.结束` 别名） |
 
 ### ⚙️ 群管理（群聊）
@@ -149,19 +150,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 伤害掷骰）、先攻列表、战斗轮——全部落地，全量测试通过；
-2. ✅ **v0.2.0**：HP 抗性/易伤与 AOE 掷骰完善、`.dnd 原因` 兼容修复、
-   **NPC/怪物血量**（三层目标搜索、先攻列表与 `.hp list` 联动、`.ri` 入表自动回满、
-   `.npc 持久/临时` 跨战斗保持）、`.dndx` 属性名绑定掷点；
-3. ⏳ **第二期 T2**：牌堆/随机表、规则查询；
-4. ⏳（可选）**T3 增强期**：法术位管理（`.ss/.cast`）、死亡豁免闭环（`.ds`）、BUFF/临时加值表（`.buff`）等。
+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`）等。
+
+每版完整变更（新增 / 变更 / 修复 / 文档）见 [CHANGELOG.md](./CHANGELOG.md)。
 
 ## 📦 本地开发
 
@@ -176,7 +176,6 @@ uv run pytest
 ## 🤝 许可与致谢
 
 - 本项目（业务层与工程骨架）以 **MIT License** 发布，见 [LICENSE](./LICENSE)。
-- **掷骰引擎与命令语法移植自 [nonebot-dicepp](https://github.com/pear-studio/nonebot-dicepp)**
-  （Copyright (c) 2022 pear-studio，MIT License）：相关文件头保留上游版权声明与 MIT 许可全文，来源按 MIT 要求在 LICENSE 中注明。
+- **掷骰引擎移植自 [nonebot-dicepp](https://github.com/pear-studio/nonebot-dicepp)**（Copyright (c) 2022 pear-studio，MIT License）：引擎文件头保留上游版权声明，MIT 许可全文见 [LICENSE](./LICENSE)。
 - 规则查询类资料内容**不随插件分发**（版权归原权利方/译者），需要时由使用者自行提供。
 - 本项目与 nonebot-dicepp 无隶属关系，为独立命名的衍生/移植作品。

nonebot_plugin_dnddicer-0.2.2/README.md

@@ -0,0 +1,151 @@
+# 屠龙骰（DNDDicer / nonebot-plugin-dnddicer）
+
+> 专精 **DND5e / DND5r** 跑团的 [NoneBot2](https://nonebot.dev/) 骰娘插件（OneBot V11 适配器），致力于做功能最全面、体验最好的 DND 骰娘。
+>
+> 当前版本：**v0.2.2** · 完整使用手册见 **📖 [使用文档](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` 模式切换；
+- **商店合规**：零配置可加载、本地存储走 `nonebot-plugin-localstore`、元数据完整、全程异步。
+
+## 📖 使用文档
+
+详细用法、输入/输出示例与常见问题见使用文档（手册式分章，含跑团示例；**在线版**：<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)
+
+## 📦 安装
+
+通过 NB-CLI（推荐，与商店安装方式一致）：
+
+```bash
+nb plugin install nonebot-plugin-dnddicer
+```
+
+或通过包管理器安装后，在 `pyproject.toml` 的 `[tool.nonebot]` 中声明加载：
+
+```bash
+pip install nonebot-plugin-dnddicer
+```
+
+```toml
+[tool.nonebot]
+plugins = ["nonebot_plugin_dnddicer"]
+```
+
+> 依赖：Python ≥ 3.11，NoneBot2 ≥ 2.4.0，OneBot V11 适配器（`nb plugin install` 会自动安装依赖）。
+
+## ⚙️ 配置
+
+插件**零配置即可加载运行**，以下配置项全部可选（在 `.env` / 环境变量中设置）：
+
+| 配置项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `dnddicer_command_priority` | `int` | `10` | 命令事件响应器基础优先级（越小越优先），与其他插件冲突时按需调整 |
+| `dnddicer_default_face` | `int` | `20` | 全局默认骰面（DND 惯例 D20；已配置 `.dset` 的群以群配置为准，此项作兜底） |
+| `dnddicer_enabled` | `bool` | `true` | 功能总开关，`false` 时只加载骨架、不注册命令 |
+| `dnddicer_use_host_command_starts` | `bool` | `false` | 是否兼容宿主 `COMMAND_START` 起始符（NoneBot 默认 `/`，开启后 `/.help` 等亦可触发）。默认只匹配 `.` / `。`，避免 `/help`、`/bot` 等常见单词命令与其他插件同时命中（冲突） |
+
+## 🎲 用法
+
+> 命令以 `.`（或全角 `。`）开头；命令起始符默认仅 `.` / `。`，如需用宿主斜杠 `/` 等起始符触发（如 `/.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-代操作)。
+
+### 🎲 掷骰（群聊 / 私聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.r [N#][hs][表达式] [原因]` | 掷骰表达式（`#` 连掷 1~10、`h` 暗骰、`s` 只显数值；仅 D20 有大成功/大失败播报） |
+| `.rh [表达式] [原因]` | 暗骰（群内提示、结果私聊） |
+
+### 📋 角色卡与检定（群聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.角色卡模板` / `.角色卡记录 <模板>` | 查看示例卡 / 记录或覆盖角色卡（`$…$` 分段模板） |
+| `.角色卡` / `.角色卡清除` / `.状态` | 查看 / 删除角色卡 / 查看 HP 与生命骰摘要 |
+| `.角色卡 @玩家` / `.角色卡 角色名` | 查看**他人**整卡（任何人可查看；记录/清除仅限本人） |
+| `.状态 @玩家` | 查看他人的 HP 与生命骰摘要 |
+| `.力量检定` / `.察觉检定+1` 等 | 属性/技能/先攻检定点命令，自动代入调整值/熟练/加值（`2#` 连掷、`+d4` 等可追加；表达式右侧可加 `@玩家` 代掷） |
+| `.体质豁免` / `.敏捷攻击优势` 等 | 豁免/攻击点命令（原名直配，优势/劣势后缀；同样支持尾部 `@玩家`） |
+| `.先攻检定` / `.先攻检定 @玩家` | 掷先攻并自动写入本群先攻列表（@ 形式代不在场的玩家掷） |
+
+### 🎯 属性生成（群聊 / 私聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.dnd [次数] [原因]` | 4D6K3 掷点生成六项属性（附合计与降序，自行分配给六属性） |
+| `.dndx [次数] [原因]` | 4D6K3 掷点并绑定属性名（不排序，掷出即定、可直接抄入角色卡） |
+
+### ❤️ HP 与长休（群聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.hp [对象] 20/30 (5)` | 设置自己/队友/NPC HP（含临时 HP；先 `.ri 名称` 入先攻表后即可记录 NPC 血量） |
+| `.hp [对象] -2d6+3` 等 | 伤害/治疗（支持掷骰表达式；目标后加 `抗性`/`易伤` 后缀可减半/加倍，分号分隔多目标同发结算） |
+| `.hp @玩家 …` / `.hp @玩家` | 对 @ 的玩家角色卡结算 / 查看（`.hp @玩家 -4d6`、`.hp @玩家;地精 -d4` 与名称混写；需该玩家已建卡） |
+| `.hp` / `.hp list` | 查看自己 / 本群列表（PC + NPC） |
+| `.hp del 名称` / `.hp clr` | 删除单个 / 清空全部 NPC 血量记录（玩家角色卡请用 `.角色卡清除`，玩家先攻条目用 `.init del`） |
+| `.npc 持久/临时 名称` | NPC 血量跨战斗保持 / 恢复默认（同名 NPC 新入先攻表默认自动回满并提示） |
+| `.长休` / `.长休 @玩家` | 长休结算（回满 HP、清临时 HP、回复一半生命骰）；@ 形式代不在场的玩家收尾 |
+
+### ⚔️ 先攻与战斗轮（群聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.ri[修正] [名称/…]` | 掷先攻入表（`.ri20 地精` 固定值、`3#` 批量、`.先攻` 别名） |
+| `.ri+3 @玩家` | 代不在场的玩家掷先攻：条目名取角色卡名并与该玩家绑定（重掷替换、回合提醒与 `.hp` 解析同步生效） |
+| `.init` | 查看先攻列表（`del`/`clr`/`first`/`swap` 子指令） |
+| `.init del/first/swap @玩家` | 子指令按玩家归属定位条目（角色卡改名后仍有效；未入表会给出提示） |
+| `.br` | 新建战斗轮（清空先攻表） |
+| `.回合` / `.轮次` | 查看/跳转当前回合与轮次（`.回合+2` 连续推进，轮到玩家自动 @ 提醒） |
+| `.回合 @玩家` | 跳转到该玩家的条目（不受改名/同名歧义影响） |
+| `.ed` | 结束当前回合并自动推进（`.结束` 别名） |
+
+### ⚙️ 群管理（群聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.dset [表达式]` | 设置/查看群默认骰面（群主/管理员） |
+| `.bot [on/off]` | 插件信息查询 / 本群服务开关（群主/管理员，需 @） |
+| `.帮助` / `.help [命令]` | 命令总览 / 指定命令详细用法（如 `.help r`） |
+
+> 一期范围外功能会**显式提示而非静默**：`.r exp` 期望值采样、`.r a/n` 特殊判定；牌堆/随机表与规则查询（T2）、法术位/死亡豁免/BUFF 表（T3 候选）见下方路线。
+
+## 📄 版本与路线
+
+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`）等。
+
+每版完整变更（新增 / 变更 / 修复 / 文档）见 [CHANGELOG.md](./CHANGELOG.md)。
+
+## 📦 本地开发
+
+```bash
+# uv 方式（推荐；或使用 pip 安装 .[dev]）
+uv sync --group dev
+uv run pytest
+```
+
+测试基于 [nonebug](https://github.com/nonebot/nonebug) 做 NoneBot 加载冒烟与全命令行为回归（与 NoneFlow 商店自动加载检查同思路）。
+
+## 🤝 许可与致谢
+
+- 本项目（业务层与工程骨架）以 **MIT License** 发布，见 [LICENSE](./LICENSE)。
+- **掷骰引擎移植自 [nonebot-dicepp](https://github.com/pear-studio/nonebot-dicepp)**（Copyright (c) 2022 pear-studio，MIT License）：引擎文件头保留上游版权声明，MIT 许可全文见 [LICENSE](./LICENSE)。
+- 规则查询类资料内容**不随插件分发**（版权归原权利方/译者），需要时由使用者自行提供。
+- 本项目与 nonebot-dicepp 无隶属关系，为独立命名的衍生/移植作品。