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

nonebot_plugin_dnddicer-0.2.1/.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.1}/.gitignore

@@ -39,3 +39,6 @@ doc/
 .idea/
 .DS_Store
 Thumbs.db
+
+# ---- 发布流程临时产物（release workflow 提取的 Release 正文；本地试跑同名脚本时也会生成）----
+.release-notes.md

nonebot_plugin_dnddicer-0.2.1/CHANGELOG.md

@@ -0,0 +1,63 @@
+# 更新日志
+
+本文件按版本记录对外变化，分「新增 / 变更 / 修复 / 文档」四组，表述面向使用者（跑团玩家与 DM）。条目一律一条目一整行、不做软换行——本文件小节的正文会原样成为 GitHub Release 正文，而 Release 页面按「issue 式」渲染，单个换行会被渲染为真实换行。
+
+发布时 `.github/workflows/release.yml` 会把**与所推标签同名的版本小节**（下方 `## [x.y.z] - 日期` 标题）提取为 GitHub Release 的说明正文——因此**打 `v*` 标签前，请先在下方补好该版本的小节**，否则发布流程会在构建前直接失败。
+
+## [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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nonebot-plugin-dnddicer
-Version: 0.2.0
+Version: 0.2.1
 Summary: 专精 DND5e/5r 跑团的 NoneBot2 骰娘插件（屠龙骰）：掷骰表达式、角色卡与检定、属性生成、HP 管理、先攻列表、战斗轮等，命令手感对齐 nonebot-dicepp
 Project-URL: Homepage, https://github.com/H-Elden/nonebot-plugin-dnddicer
 Project-URL: Issues, https://github.com/H-Elden/nonebot-plugin-dnddicer/issues
@@ -33,7 +33,7 @@ Description-Content-Type: text/markdown
 > 专精 **DND5e / DND5r** 跑团的 [NoneBot2](https://nonebot.dev/) 骰娘插件（OneBot V11 适配器），
 > 命令手感对齐 [nonebot-dicepp](https://github.com/pear-studio/nonebot-dicepp)（梨骰）。
 >
-> 当前版本：**v0.2.0** · 完整使用手册见 **📖 [使用文档](./docs/index.md)**
+> 当前版本：**v0.2.1** · 完整使用手册见 **📖 [使用文档](./docs/index.md)**
 
 ## ✨ 简介
 
@@ -96,6 +96,12 @@ plugins = ["nonebot_plugin_dnddicer"]
 > **群聊服务默认关闭（白名单）**：需群主/管理员发送 `.bot on` 开启本群服务；`.bot off`
 > 关闭后本群不再响应命令（`.bot` 本身不受影响）。群聊中使用 `.bot` 需先 @ 本机器人；
 > 私聊不受服务开关限制，可直接使用全部功能。
+>
+> **DM 代操作（@ 提及目标）**：多数带目标的命令支持用 **@群成员** 指定目标——直连该成员
+> 在本群的角色卡，不受同名 NPC/改名影响，且可与名称混写（`.hp @玩家 -4d6`、
+> `.hp @玩家;地精 -d4`、`.ri+3 @玩家`、`.init del @玩家`、`.回合 @玩家`、
+> `.角色卡 @玩家`、`.力量豁免 @玩家`、`.先攻检定 @玩家` 等）。详见
+> [使用文档](./docs/index.md#-提及目标dm-代操作)。
 
 ### 🎲 掷骰（群聊 / 私聊）
 
@@ -110,9 +116,11 @@ plugins = ["nonebot_plugin_dnddicer"]
 | --- | --- |
 | `.角色卡模板` / `.角色卡记录 <模板>` | 查看示例卡 / 记录或覆盖角色卡（`$…$` 分段模板） |
 | `.角色卡` / `.角色卡清除` / `.状态` | 查看 / 删除角色卡 / 查看 HP 与生命骰摘要 |
-| `.力量检定` / `.察觉检定+1` 等 | 属性/技能/先攻检定点命令，自动代入调整值/熟练/加值（`2#` 连掷、`+d4` 等可追加） |
-| `.体质豁免` / `.敏捷攻击优势` 等 | 豁免/攻击点命令（原名直配，优势/劣势后缀） |
-| `.先攻检定` | 掷先攻并自动写入本群先攻列表 |
+| `.角色卡 @玩家` / `.角色卡 角色名` | 查看**他人**整卡（任何人可查看；记录/清除仅限本人） |
+| `.状态 @玩家` | 查看他人的 HP 与生命骰摘要 |
+| `.力量检定` / `.察觉检定+1` 等 | 属性/技能/先攻检定点命令，自动代入调整值/熟练/加值（`2#` 连掷、`+d4` 等可追加；表达式右侧可加 `@玩家` 代掷） |
+| `.体质豁免` / `.敏捷攻击优势` 等 | 豁免/攻击点命令（原名直配，优势/劣势后缀；同样支持尾部 `@玩家`） |
+| `.先攻检定` / `.先攻检定 @玩家` | 掷先攻并自动写入本群先攻列表（@ 形式代不在场的玩家掷） |
 
 ### 🎯 属性生成（群聊 / 私聊）
 
@@ -127,18 +135,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` | 结束当前回合并自动推进（`.结束` 别名） |
 
 ### ⚙️ 群管理（群聊）
@@ -160,8 +173,13 @@ plugins = ["nonebot_plugin_dnddicer"]
 2. ✅ **v0.2.0**：HP 抗性/易伤与 AOE 掷骰完善、`.dnd 原因` 兼容修复、
    **NPC/怪物血量**（三层目标搜索、先攻列表与 `.hp list` 联动、`.ri` 入表自动回满、
    `.npc 持久/临时` 跨战斗保持）、`.dndx` 属性名绑定掷点；
-3. ⏳ **第二期 T2**：牌堆/随机表、规则查询；
-4. ⏳（可选）**T3 增强期**：法术位管理（`.ss/.cast`）、死亡豁免闭环（`.ds`）、BUFF/临时加值表（`.buff`）等。
+3. ✅ **v0.2.1**：**@ 提及目标**（DM 可代玩家操作 `.hp`/`.npc`/`.ri`/`.回合` 等、查看角色卡）、
+   玩家名称显示统一回退链、`.hp del/clr` 语义修订（仅作用 NPC 血量）、
+   优势/劣势别名粘连等真机反馈修复；
+4. ⏳ **第二期 T2**：牌堆/随机表、规则查询；
+5. ⏳（可选）**T3 增强期**：法术位管理（`.ss/.cast`）、死亡豁免闭环（`.ds`）、BUFF/临时加值表（`.buff`）等。
+
+每版完整变更（新增 / 变更 / 修复 / 文档）见 [CHANGELOG.md](./CHANGELOG.md)。
 
 ## 📦 本地开发
 

{nonebot_plugin_dnddicer-0.2.0 → nonebot_plugin_dnddicer-0.2.1}/README.md

@@ -3,7 +3,7 @@
 > 专精 **DND5e / DND5r** 跑团的 [NoneBot2](https://nonebot.dev/) 骰娘插件（OneBot V11 适配器），
 > 命令手感对齐 [nonebot-dicepp](https://github.com/pear-studio/nonebot-dicepp)（梨骰）。
 >
-> 当前版本：**v0.2.0** · 完整使用手册见 **📖 [使用文档](./docs/index.md)**
+> 当前版本：**v0.2.1** · 完整使用手册见 **📖 [使用文档](./docs/index.md)**
 
 ## ✨ 简介
 
@@ -66,6 +66,12 @@ plugins = ["nonebot_plugin_dnddicer"]
 > **群聊服务默认关闭（白名单）**：需群主/管理员发送 `.bot on` 开启本群服务；`.bot off`
 > 关闭后本群不再响应命令（`.bot` 本身不受影响）。群聊中使用 `.bot` 需先 @ 本机器人；
 > 私聊不受服务开关限制，可直接使用全部功能。
+>
+> **DM 代操作（@ 提及目标）**：多数带目标的命令支持用 **@群成员** 指定目标——直连该成员
+> 在本群的角色卡，不受同名 NPC/改名影响，且可与名称混写（`.hp @玩家 -4d6`、
+> `.hp @玩家;地精 -d4`、`.ri+3 @玩家`、`.init del @玩家`、`.回合 @玩家`、
+> `.角色卡 @玩家`、`.力量豁免 @玩家`、`.先攻检定 @玩家` 等）。详见
+> [使用文档](./docs/index.md#-提及目标dm-代操作)。
 
 ### 🎲 掷骰（群聊 / 私聊）
 
@@ -80,9 +86,11 @@ plugins = ["nonebot_plugin_dnddicer"]
 | --- | --- |
 | `.角色卡模板` / `.角色卡记录 <模板>` | 查看示例卡 / 记录或覆盖角色卡（`$…$` 分段模板） |
 | `.角色卡` / `.角色卡清除` / `.状态` | 查看 / 删除角色卡 / 查看 HP 与生命骰摘要 |
-| `.力量检定` / `.察觉检定+1` 等 | 属性/技能/先攻检定点命令，自动代入调整值/熟练/加值（`2#` 连掷、`+d4` 等可追加） |
-| `.体质豁免` / `.敏捷攻击优势` 等 | 豁免/攻击点命令（原名直配，优势/劣势后缀） |
-| `.先攻检定` | 掷先攻并自动写入本群先攻列表 |
+| `.角色卡 @玩家` / `.角色卡 角色名` | 查看**他人**整卡（任何人可查看；记录/清除仅限本人） |
+| `.状态 @玩家` | 查看他人的 HP 与生命骰摘要 |
+| `.力量检定` / `.察觉检定+1` 等 | 属性/技能/先攻检定点命令，自动代入调整值/熟练/加值（`2#` 连掷、`+d4` 等可追加；表达式右侧可加 `@玩家` 代掷） |
+| `.体质豁免` / `.敏捷攻击优势` 等 | 豁免/攻击点命令（原名直配，优势/劣势后缀；同样支持尾部 `@玩家`） |
+| `.先攻检定` / `.先攻检定 @玩家` | 掷先攻并自动写入本群先攻列表（@ 形式代不在场的玩家掷） |
 
 ### 🎯 属性生成（群聊 / 私聊）
 
@@ -97,18 +105,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` | 结束当前回合并自动推进（`.结束` 别名） |
 
 ### ⚙️ 群管理（群聊）
@@ -130,8 +143,13 @@ plugins = ["nonebot_plugin_dnddicer"]
 2. ✅ **v0.2.0**：HP 抗性/易伤与 AOE 掷骰完善、`.dnd 原因` 兼容修复、
    **NPC/怪物血量**（三层目标搜索、先攻列表与 `.hp list` 联动、`.ri` 入表自动回满、
    `.npc 持久/临时` 跨战斗保持）、`.dndx` 属性名绑定掷点；
-3. ⏳ **第二期 T2**：牌堆/随机表、规则查询；
-4. ⏳（可选）**T3 增强期**：法术位管理（`.ss/.cast`）、死亡豁免闭环（`.ds`）、BUFF/临时加值表（`.buff`）等。
+3. ✅ **v0.2.1**：**@ 提及目标**（DM 可代玩家操作 `.hp`/`.npc`/`.ri`/`.回合` 等、查看角色卡）、
+   玩家名称显示统一回退链、`.hp del/clr` 语义修订（仅作用 NPC 血量）、
+   优势/劣势别名粘连等真机反馈修复；
+4. ⏳ **第二期 T2**：牌堆/随机表、规则查询；
+5. ⏳（可选）**T3 增强期**：法术位管理（`.ss/.cast`）、死亡豁免闭环（`.ds`）、BUFF/临时加值表（`.buff`）等。
+
+每版完整变更（新增 / 变更 / 修复 / 文档）见 [CHANGELOG.md](./CHANGELOG.md)。
 
 ## 📦 本地开发
 

{nonebot_plugin_dnddicer-0.2.0 → nonebot_plugin_dnddicer-0.2.1}/docs/guide/battle.md

@@ -12,6 +12,7 @@
 | `.回合` / `.轮次` | 查看当前轮与回合 |
 | `.回合 +1 / -1 / =2 / 2` | 回合前进/后退/直接跳转（越界自动进位轮次） |
 | `.回合 名字` | 按名字跳转到该行动者的回合（支持模糊） |
+| `.回合 @玩家` | 按玩家归属跳转到其条目（不受改名/同名歧义影响） |
 | `.轮次 +1 / -1 / =3` | 调整轮次 |
 | `.ed` / `.结束` | 结束当前回合：播报 + 自动推进下一位；轮到玩家时输出 @ 提醒 |
 
@@ -86,6 +87,9 @@
 你发送：.回合 地精                  ← 按名字跳转（精确→模糊）
 骰娘回复：现在是地精的回合。
 
+你发送：.回合 @艾琳                 ← 按玩家归属跳转（不受改名/同名歧义影响）
+骰娘回复：现在是艾琳的回合。请玩家 @艾琳 开始行动。
+
 你发送：.回合+2                     ← 一次推进多位（地精是第 1 回合，+2 → 第 3 回合艾琳）
 骰娘回复：现在是艾琳的回合。请玩家 @艾琳 开始行动。
 
@@ -106,6 +110,7 @@
 | --- | --- |
 | 先攻表为空时操作战斗轮 | `目前先攻列表为空，故不存在回合与轮次。` |
 | `.回合 名字` 无匹配 / 多匹配 | `没有找到这个回合。` / `找到复数回合，请换一个关键词。` |
+| `.回合 @玩家` 而该玩家不在先攻表 | `@玩家 不在先攻列表中` |
 | `.回合=9`（超出总人数） / `.回合=0` | `这个数字太大了。` / `这个数字太小了。` |
 | `.回合+abc`（非数字） | `这不是数字。` |
 

{nonebot_plugin_dnddicer-0.2.0 → nonebot_plugin_dnddicer-0.2.1}/docs/guide/character-card.md

@@ -12,8 +12,9 @@
 | `.角色卡记录 <模板文本>` | 记录/覆盖自己的角色卡 |
 | `.角色卡模板` | 查看示例卡与段落填写说明 |
 | `.角色卡清除` | 删除自己的角色卡 |
-| `.状态` | 查看 HP 与生命骰摘要 |
-| `.xx检定` / `.xx豁免` / `.xx攻击` | 检定点命令（见下节） |
+| `.角色卡 @玩家` / `.角色卡 角色名` | 查看**他人**整卡（任何人可查看；记录/清除仅限本人） |
+| `.状态` / `.状态 @玩家` | 查看自己 / 他人的 HP 与生命骰摘要 |
+| `.xx检定` / `.xx豁免` / `.xx攻击` | 检定点命令（见下节，表达式右侧可加 `@玩家` 代掷） |
 
 ## 记录角色卡（.角色卡记录）
 
@@ -62,6 +63,28 @@ $熟练$ 力量/隐匿
 $额外加值$ 隐匿:优势
 ```
 
+### 查看他人角色卡（.角色卡 @玩家 / 名称）
+
+用 **@群成员** 或 **角色名** 可以查看他人的整卡（输出带标题行便于分辨）——
+@ 直连该成员的角色卡，名称则按「PC 角色卡 → NPC 血量 → 先攻表」三层搜索：
+
+```text
+你发送：.角色卡 @伊丽莎白          ← 或 .角色卡 伊丽莎白（两种写法等价）
+骰娘回复：伊丽莎白 的角色卡：
+$姓名$ 伊丽莎白
+$生命值$ 20/30 (5)
+$生命骰$ 3/4 D8
+$等级$ 5
+$属性$ 15/14/13/12/10/8
+$熟练$ 力量/隐匿
+$额外加值$ 隐匿:优势
+```
+
+> **查看开放、修改仅本人**：任何人可查看任何人的卡（群内信息共享），而
+> `.角色卡记录` / `.角色卡清除` 写入的目标**恒为发送者自己**——带 @ 也不会改动
+> 他人的卡。@ 到无卡成员会提示 `@玩家 还没有在本群建立角色卡（可用 .角色卡记录 建卡后再试）`；
+> 名称命中先攻表中的 NPC 条目时提示 `「名称」是NPC条目，没有角色卡`。
+
 ### 查看示例模板（.角色卡模板）
 
 ```text
@@ -88,6 +111,14 @@ $额外加值$ 敏捷攻击:+1d4/豁免:+2
 生命骰:3/4 D8
 ```
 
+`.状态 @玩家` 可查看他人的状态（输出加角色名前缀，仅 @ 形式）：
+
+```text
+你发送：.状态 @伊丽莎白
+骰娘回复：伊丽莎白: HP:20/30 (5)
+生命骰:3/4 D8
+```
+
 ## 检定点命令
 
 ### 语法
@@ -105,7 +136,9 @@ $额外加值$ 敏捷攻击:+1d4/豁免:+2
 - `N#` 前缀连掷 N 次（1~9，逐次独立掷骰并显示）；
 - 临时 `优势`/`劣势` 与卡上自带优劣势**叠加、可抵消**（同名两次优劣势抵消后提示「优劣抵消」）；
 - 检定只掷出裸数值（d20+加值），**不对 DC 做判定**——是否成功由玩家/DM 自行比较；
-- 无角色卡时提示「找不到角色卡」。
+- 无角色卡时提示「找不到角色卡」；
+- 表达式**右侧**可加 `@玩家`（DM 代不在场的玩家掷）：用**目标的角色卡**代入属性/
+  熟练/加值，落款取目标角色名，优劣势与 `±加值` 写在 @ 前后皆可（见下节示例）。
 
 ### 示例（伊丽莎白：5 级，力量 15 且力量熟练，体质 13，敏捷 14）
 
@@ -130,6 +163,31 @@ $额外加值$ 敏捷攻击:+1d4/豁免:+2
 1D20+2=[3]+2=5
 ```
 
+### 代不在场的玩家掷（@ 提及目标）
+
+把 `@玩家` 写在表达式右侧（含优劣势/加值之后），骰娘改用**该玩家角色卡**的数据代掷：
+
+```text
+你发送：.力量豁免 @伊丽莎白
+骰娘回复：伊丽莎白进行【力量豁免】：
+无熟练加值 力量调整值:2
+1D20+2=[9]+2=11
+
+你发送：.敏捷攻击优势 @伊丽莎白        ← 优劣势写在 @ 前后皆可
+骰娘回复：伊丽莎白进行【敏捷攻击】：
+无熟练加值 敏捷调整值:2
+2D20K1+2=MAX{[9], [7]}+2=11
+
+你发送：.2#敏捷攻击 @伊丽莎白          ← 连掷同样支持
+骰娘回复：伊丽莎白进行【2次敏捷攻击】：
+无熟练加值 敏捷调整值:2
+1D20+2=[3]+2=5
+1D20+2=[4]+2=6
+```
+
+> @ 的目标需已建卡，否则回复真 @ 提示引导建卡；检定点命令**不做**游离 @ 拦截
+> （误掷代价低）——`@玩家` 要写在表达式右侧才作为目标，写在命令前不生效。
+
 ### 大成功 / 大失败
 
 检定 / 豁免 / 攻击点命令与 `.r` 使用同一套判定：**被保留的 d20 出目 20 → 播报「好耶！大成功!」，出目 1 → 播报「哇哦！大失败!」**（攻击自然 1 同样播报——5e 规则中攻击出目 1 必定失误）。`N#` 连掷时按次汇总（`1次 大成功`）。
@@ -153,9 +211,19 @@ $额外加值$ 敏捷攻击:+1d4/豁免:+2
 伊丽莎白的先攻值是 1D20=[20]=20
 ```
 
+`.先攻检定 @玩家` 可代不在场的玩家掷：用其角色卡掷骰，并以**该玩家为归属**入先攻表
+（与 `.ri @玩家` 同源——重掷替换其旧条目、轮到该条目时 @ 提醒）：
+
+```text
+你发送：.先攻检定 @伊丽莎白
+骰娘回复：伊丽莎白进行【先攻检定】：
+无熟练加值 敏捷调整值:2
+伊丽莎白的先攻值是 1D20+2=[5]+2=7
+```
+
 再次投掷会替换旧条目并提示「你重复投掷了先攻」。先攻列表的查看与管理见[先攻列表](./initiative.md)。
 
 ## 相关
 
-- 检定反馈中的昵称回退链：角色名（`$姓名$`）→ 群名片 → QQ 昵称 →「未知玩家」。
+- 检定反馈中的昵称回退链与全插件一致：角色名（`$姓名$`）→ 群名片 → QQ 昵称 → 「未知玩家（QQ号）」（见[名称显示规则](../index.md#名称显示规则)）。
 - 属性生成（4D6K3 掷点）见 [属性生成](./attributes.md)。

{nonebot_plugin_dnddicer-0.2.0 → nonebot_plugin_dnddicer-0.2.1}/docs/guide/faq.md

@@ -83,6 +83,23 @@
 与 `.hp list` 都会展示）；同名 NPC 在新战斗中入表时自动回满，需要跨战斗延续
 血量用 `.npc 持久 名称`。详见 [HP 管理](./hp-rest.md) 的「NPC / 怪物血量」。
 
+**Q：玩家不在场，DM 怎么代操作他的角色卡？**
+把 **@该成员** 写在目标位置即可（@ 与名称可混写，分隔符 `;` 或空白）：
+
+| 场景 | 写法 |
+| --- | --- |
+| 结算 HP | `.hp @玩家 -4d6`、`.hp @玩家 20/30`、`.hp @玩家;地精 -d4`（AOE）、`.hp @玩家`（查看） |
+| 长休收尾 | `.长休 @玩家` |
+| 代掷先攻 | `.ri+3 @玩家`（条目名取角色卡名并与该玩家绑定，重掷替换、回合提醒同款） |
+| 定位先攻条目 | `.init del @玩家`、`.init first @玩家`、`.init swap @玩家/兽人`、`.回合 @玩家` |
+| 查看 | `.角色卡 @玩家`（整卡）、`.状态 @玩家` |
+| 代掷检定 | `.力量豁免 @玩家`、`.2#敏捷攻击优势 @玩家`、`.先攻检定 @玩家` |
+
+@ 的目标需已在本群建卡（否则真 @ 提示引导建卡）。注意 @ 要写在目标位置：
+`.hp -4d6 @玩家`、`@玩家 .hp -4d6` 这类游离写法**不执行**并回纠正示例——这是刻意
+设计（此前会静默按发送者自己结算，容易误伤）。查看他人卡对任何人开放，但
+`.角色卡记录`/`.角色卡清除` **仅本人**可执行。
+
 ## 更多
 
 - 各功能详细用法：见左侧各页面；

{nonebot_plugin_dnddicer-0.2.0 → nonebot_plugin_dnddicer-0.2.1}/docs/guide/hp-rest.md

@@ -82,9 +82,50 @@ HP:0/30 昏迷 -> HP:15/30
 | 情况 | 提示 |
 | --- | --- |
 | 多个目标匹配同一关键字 | `存在多个匹配目标：['爱丽丝a', '爱丽丝b']`（换更精确的关键字） |
-| 目标不存在 | `找不到XXX的生命值信息` |
+| 目标不存在 | `找不到XXX的生命值信息` + 新NPC提示（需先加入先攻表） |
 | 一次调整多个目标 | 目标用 `;` 分隔（如 `.hp 爱丽丝;小刚 -5`） |
 
+> 名称匹配为**精确优先的两级匹配**（与 `.init` 子指令一致）：先攻表/记录里同时
+> 有「地精」与「熊地精」时，`.hp 地精 ...` 直接命中地精、`.hp 熊 ...` 命中熊地精；
+> 没有完全匹配时才做子串匹配，命中多个则提示歧义。
+
+### @ 指定玩家（DM 代操作）
+
+用 **@群成员** 可直连该成员在本群的角色卡——不走名称搜索，因此不怕重名 NPC，
+角色卡改名也不影响；@ 与名称可用 `;`（半角/全角）或空白混写：
+
+```text
+你发送：.hp @布兰克 -4d6           ← 对 @ 的玩家角色卡造成伤害
+骰娘回复：布兰克: 当前HP减少[3+2+4]=9
+HP:20/30 -> HP:11/30
+
+你发送：.hp @布兰克 20/30 (5)      ← 设置 / 治疗（+10）/ 抗性·易伤后缀同理
+你发送：.hp @布兰克易伤 -d8        ← 易伤后缀紧贴标记照常生效
+你发送：.hp @布兰克;地精 -d8       ← 与 NPC 条目混写：AOE 一发结算
+你发送：.hp @布兰克                ← 查看该玩家的 HP（可多个：.hp @布兰克 @莎白）
+```
+
+- @ 的目标需**已在本群建立角色卡**，否则回复 `@玩家 还没有在本群建立角色卡（可用 .角色卡记录 建卡后再试）`；
+- **游离 @**（@ 没写在目标位置，如 `.hp -4d6 @布兰克`、`.hp 20/30 @布兰克`、`@布兰克 .hp -4d6`）
+  **不执行**并回纠正示例——这些写法此前会静默按发送者自己结算，属易误伤写法；
+- `@机器人自身` 不作为目标（`@骰娘 .hp -4d6` 仍按发送者自己结算）。
+
+**无角色卡的队友**只要已用 `.ri` 加入先攻表（条目绑定其 QQ），DM 也能直接用其
+名称结算；反馈落款走全插件统一的名称回退链（见[名称显示规则](../index.md#名称显示规则)）：
+
+```text
+你发送：.ri20            ← 队友在群里自己发（无卡：条目名取群名片）
+骰娘回复：陈莉莉的先攻值是 20
+
+你发送：.hp 陈莉莉-9     ← DM 结算
+骰娘回复：陈莉莉: 当前HP减少9
+损失HP:0 -> 损失HP:9
+```
+
+> 无最大 HP 的记录按「损失HP」累计受创（`损失HP:N` 表示已损失 N 点），
+> 治疗先以「损失」回补至 0。要让其拥有正常的 `HP:x/y` 记录，先 `.hp 名称 当前/最大`，
+> 或让该玩家用 `.角色卡记录` 建卡。
+
 ## DM 掷怪物伤害（推荐用法）
 
 DM 可以把"掷怪物攻击伤害 + 扣血"一步完成：**目标写在前面，伤害表达式跟在 `-`
@@ -125,6 +166,9 @@ HP:20/30 -> HP:10/30
 
 > `抗性`/`易伤` 后缀只对伤害（`-`）生效；用于设置/治疗会提示错误。
 > 结算顺序：临时 HP 先吸收，溢出再扣当前 HP；降至 0 昏迷。
+> **伤害与治疗的最低值为 0**：表达式算出负值时（如 `.hp 向导 -d12-2` 掷出 1）
+> 不会反向加血或掉血，按 0 计并在结果中标注「伤害最低为0」（`.r` 表达式里
+> 自带的 `抗性`/`易伤` 后缀同样受限）。
 
 ## NPC / 怪物血量
 
@@ -153,7 +197,10 @@ AOE 多目标）。
 你发送：.ri15 哥布林
 骰娘回复：哥布林的先攻值是 15
 注：哥布林 已自动回满 20/20（上次 16/20）
-如需沿用上次血量: .hp 哥布林 16/20；跨战斗保持血量: .npc 持久 哥布林
+如需沿用上次血量:
+.hp 哥布林 16/20
+如需跨战斗保持血量:
+.npc 持久 哥布林
 ```
 
 - 提示里的 `.hp 哥布林 16/20` 可直接复制发送，沿用上次战斗结束时的血量；
@@ -173,9 +220,16 @@ AOE 多目标）。
 
 ### 清空与清理
 
-`.init clr` / `.br` 清空先攻表时，会清理 NPC 的**临时血量**（未设上限、只记
-受损的条目）；设过上限的记录与 `.npc 持久` 标记的记录保留。`.init del 名称`
-删除先攻条目时一并删除其血量记录。
+三种清理各管一段，按需选用：
+
+| 方式 | 清理范围 |
+| --- | --- |
+| `.init clr` / `.br` | 清空先攻表，并清理 NPC 的**临时血量**（未设上限、只记受损的条目） |
+| `.init del 名称` | 删除单个先攻条目，一并删除其血量记录 |
+| `.hp del 名称` / `.hp clr` | 删除单个 / 清空全部 NPC 血量记录（不动先攻表，见下节） |
+
+设过上限的记录与 `.npc 持久` 标记的记录在前两者中保留；`.hp clr` 则包含它们
+（属显式清理）。
 
 ## 查看列表与删除
 
@@ -186,8 +240,26 @@ AOE 多目标）。
 ```
 
 - `.hp list` 列出**本群全部 PC 与 NPC** 的 HP（PC 在前、NPC 在后）；无记录时提示「本群没有任何生命值信息」；
-- 列表名称回退链：**角色卡名 → 群名片 → QQ 昵称 → 「未知玩家」**（API 查询失败也不显示 QQ 号）；
-- `.hp del` 删除自己的 HP 记录，`.hp del 名称` 删除指定目标（队友或 NPC）；`.hp` 无记录时提示 `找不到艾琳的生命值信息`。
+- 列表与目标结算反馈的名称回退链与全插件一致：**角色卡名 → 群名片 → QQ 昵称 → 「未知玩家（QQ号）」**（见[名称显示规则](../index.md#名称显示规则)）；
+- **删除只作用于 NPC 血量记录**（与 `.init` 的 `del`/`clr` 同形）：
+
+| 命令 | 作用 |
+| --- | --- |
+| `.hp del 名称` | 删除单个 NPC 血量记录（多个用 `/` 分隔，如 `.hp del 哥布林a/哥布林b`） |
+| `.hp clr` | 清空**本群全部** NPC 血量记录（含跨战斗保持的），回「已清空N条NPC血量记录」 |
+
+```text
+你发送：.hp del 哥布林
+骰娘回复：已删除哥布林的生命值信息
+
+你发送：.hp clr
+骰娘回复：已清空3条NPC血量记录
+```
+
+- `.hp del`（无对象）不会删除任何东西，只提示用法；
+- 目标解析为**玩家角色卡**时不会被删除，而是提示改用 `.角色卡清除`；用 `@玩家`
+  指定时会附带「移除玩家先攻条目请用 `.init del` 该玩家」的引导；
+- PC 的血量无需删除——直接 `.hp 20/30` 覆盖设置即可；`.hp` 无记录时提示 `找不到艾琳的生命值信息`。
 
 ## 长休（.长休）
 
@@ -198,6 +270,16 @@ AOE 多目标）。
 回复2个生命骰, 当前拥有4/4个D8生命骰
 ```
 
+DM 可代不在场的玩家收尾：`.长休 @玩家` 用该玩家的角色卡结算（回复落款取其角色名；
+无卡时给出真 @ 引导建卡）：
+
+```text
+你发送：.长休 @艾琳
+骰娘回复：艾琳进行了一次长休
+生命值回复至上限(30) 5点临时生命值失效
+回复2个生命骰, 当前拥有4/4个D8生命骰
+```
+
 规则：HP 回复至上限、临时 HP 清零、生命骰回复一半（不足 1 按 1）。需要角色卡上记录了 `$生命值$`（含当前值）与 `$生命骰$`（如 `2/4 D8`）。未记录生命骰时只结算 HP 与临时 HP；无角色卡提示 `找不到艾琳的角色卡信息`。
 
 ## 相关