nonebot-plugin-dnddicer 0.1.0__tar.gz

nonebot_plugin_dnddicer-0.1.0/.gitattributes

@@ -0,0 +1,19 @@
+# 统一文本行尾为 LF（跨平台协作；ruff/uv 生态均按 LF 处理）
+* text=auto
+
+*.py  text eol=lf
+*.pyi text eol=lf
+*.md  text eol=lf
+*.toml text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.json text eol=lf
+*.txt text eol=lf
+*.lock text eol=lf
+*.gitignore text eol=lf
+*.gitattributes text eol=lf
+
+# 二进制文件不转换
+*.png binary
+*.jpg binary
+*.ico binary

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

@@ -0,0 +1,42 @@
+# 推 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
+      - 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:
+          generate_release_notes: true

nonebot_plugin_dnddicer-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,22 @@
+# push / PR 全量测试（NoneFlow 商店加载检查同思路的本地回归）
+name: test
+
+on:
+  push:
+  pull_request:
+
+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 }}
+      # uv sync 默认包含 [dependency-groups].dev，pytest/nonebug 随附
+      - name: 全量测试
+        run: uv run pytest

nonebot_plugin_dnddicer-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# ---- Python 通用 ----
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+junit.xml
+
+# ---- 虚拟环境 ----
+.venv/
+venv/
+env/
+
+# ---- localstore 数据目录（仅仓库根：开发/测试期由 tests/conftest 落于此；
+#      生产环境由宿主 LOCALSTORE_DATA_DIR 指定；不可用裸 data/ 以免误伤插件包内 data 目录）----
+/data/
+
+# ---- 环境与密钥 ----
+.env
+.env.*.local
+!.env.example
+
+# ---- 本地参考资料----
+.ref/
+
+# ---- 项目内部文档----
+AGENTS.md
+doc/
+
+# ---- 编辑器/系统 ----
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

nonebot_plugin_dnddicer-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

nonebot_plugin_dnddicer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DNDDicer contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nonebot_plugin_dnddicer-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: nonebot-plugin-dnddicer
+Version: 0.1.0
+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
+Project-URL: Repository, https://github.com/H-Elden/nonebot-plugin-dnddicer.git
+Author: Elden
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dice,dnd,dnd5e,nonebot,nonebot2,trpg,跑团,骰娘
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Role-Playing
+Requires-Python: >=3.11
+Requires-Dist: lark<2.0.0,>=1.1.0
+Requires-Dist: nonebot-adapter-onebot<3.0.0,>=2.4.6
+Requires-Dist: nonebot-plugin-localstore<1.0.0,>=0.7.4
+Requires-Dist: nonebot2<3.0.0,>=2.5.0
+Provides-Extra: dev
+Requires-Dist: nonebot2[fastapi]<3.0.0,>=2.5.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'
+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)（梨骰）。
+>
+> 当前版本：**v0.1.0**（第一期功能完整可用）· 完整使用手册见 **📖 [使用文档](./docs/index.md)**
+
+## ✨ 简介
+
+DNDDicer 的目标是填补「NoneBot 商店中缺少 **DND5e/5r 专业 + 现代维护 + 插件形态** 骰娘」的空位：
+以 DicePP 掷骰引擎与命令手感为基准，做独立的、零配置可加载的 NoneBot 插件，供任何已有
+机器人从商店安装即用。
+
+- **掷骰引擎**：移植 nonebot-dicepp 的 AST 表达式引擎（Lark 文法），支持 `2d20kh1`、
+  优势/劣势、爆炸骰、连掷、暗骰等 DicePP 完整语法面；
+- **跑团全流程**：掷骰 → `.dnd` 属性生成 → 角色卡与检定/豁免/攻击点命令 → HP 管理
+  （伤害掷骰、抗性/易伤、AOE 多目标结算、长休）→ 先攻列表与战斗轮；
+- **规则范围**：仅 DND5e/5r——专精 DND 定位，不做 COC/d100 体系与 `.mode` 模式切换；
+- **商店合规**：零配置可加载、本地存储走 `nonebot-plugin-localstore`、元数据完整、全程异步。
+
+## 📖 使用文档
+
+详细用法、输入/输出示例与常见问题见仓库 `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)
+
+## 📦 安装
+
+通过 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.5.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` 等常见单词命令与其他插件同时命中（冲突） |
+
+## 🎲 用法
+
+> 命令以 `.`（或全角 `。`）开头，中英文别名对齐 DicePP；命令起始符默认仅 `.` / `。`，
+> 如需用宿主斜杠 `/` 等起始符触发（如 `/.help`），请设置配置项 `dnddicer_use_host_command_starts=true`。
+> **群聊服务默认关闭（白名单）**：需群主/管理员发送 `.bot on` 开启本群服务；`.bot off`
+> 关闭后本群不再响应命令（`.bot` 本身不受影响）。群聊中使用 `.bot` 需先 @ 本机器人；
+> 私聊不受服务开关限制，可直接使用全部功能。
+
+### 🎲 掷骰（群聊 / 私聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.r [N#][hs][表达式] [原因]` | 掷骰表达式（`#` 连掷 1~10、`h` 暗骰、`s` 只显数值；仅 d20 有大成功/大失败播报） |
+| `.rh [表达式] [原因]` | 暗骰（群内提示、结果私聊） |
+
+### 📋 角色卡与检定（群聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.角色卡模板` / `.角色卡记录 <模板>` | 查看示例卡 / 记录或覆盖角色卡（`$…$` 分段模板） |
+| `.角色卡` / `.角色卡清除` / `.状态` | 查看 / 删除角色卡 / 查看 HP 与生命骰摘要 |
+| `.力量检定` / `.察觉检定+1` 等 | 属性/技能/先攻检定点命令，自动代入调整值/熟练/加值（`2#` 连掷、`+d4` 等可追加） |
+| `.体质豁免` / `.敏捷攻击优势` 等 | 豁免/攻击点命令（原名直配，优势/劣势后缀） |
+| `.先攻检定` | 掷先攻并自动写入本群先攻列表 |
+
+### 🎯 属性生成（群聊 / 私聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.dnd [次数] [原因]` | 4D6K3 掷点生成六项属性（附合计与降序，自行分配给六属性） |
+
+### ❤️ HP 与长休（群聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.hp [对象] 20/30 (5)` | 设置自己/队友 HP（含临时 HP） |
+| `.hp [对象] -2d6+3` 等 | 伤害/治疗（支持掷骰表达式；目标后加 `抗性`/`易伤` 后缀可减半/加倍，分号分隔多目标同发结算） |
+| `.hp` / `.hp list` / `.hp del` | 查看自己 / 本群列表 / 删除 |
+| `.长休` | 长休结算（回满 HP、清临时 HP、回复一半生命骰） |
+
+### ⚔️ 先攻与战斗轮（群聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.ri[修正] [名称/…]` | 掷先攻入表（`.ri20 地精` 固定值、`3#` 批量、`.先攻` 别名） |
+| `.init` | 查看先攻列表（`del`/`clr`/`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. ⏳ **第二期 T2**：牌堆/随机表、规则查询；
+3. ⏳（可选）**T3 增强期**：法术位管理（`.ss/.cast`）、死亡豁免闭环（`.ds`）、BUFF/临时加值表（`.buff`）等。
+
+## 📦 本地开发
+
+```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 许可全文，来源按 MIT 要求在 LICENSE 中注明。
+- 规则查询类资料内容**不随插件分发**（版权归原权利方/译者），需要时由使用者自行提供。
+- 本项目与 nonebot-dicepp 无隶属关系，为独立命名的衍生/移植作品。

nonebot_plugin_dnddicer-0.1.0/README.md

@@ -0,0 +1,147 @@
+# 屠龙骰（DNDDicer / nonebot-plugin-dnddicer）
+
+> 专精 **DND5e / DND5r** 跑团的 [NoneBot2](https://nonebot.dev/) 骰娘插件（OneBot V11 适配器），
+> 命令手感对齐 [nonebot-dicepp](https://github.com/pear-studio/nonebot-dicepp)（梨骰）。
+>
+> 当前版本：**v0.1.0**（第一期功能完整可用）· 完整使用手册见 **📖 [使用文档](./docs/index.md)**
+
+## ✨ 简介
+
+DNDDicer 的目标是填补「NoneBot 商店中缺少 **DND5e/5r 专业 + 现代维护 + 插件形态** 骰娘」的空位：
+以 DicePP 掷骰引擎与命令手感为基准，做独立的、零配置可加载的 NoneBot 插件，供任何已有
+机器人从商店安装即用。
+
+- **掷骰引擎**：移植 nonebot-dicepp 的 AST 表达式引擎（Lark 文法），支持 `2d20kh1`、
+  优势/劣势、爆炸骰、连掷、暗骰等 DicePP 完整语法面；
+- **跑团全流程**：掷骰 → `.dnd` 属性生成 → 角色卡与检定/豁免/攻击点命令 → HP 管理
+  （伤害掷骰、抗性/易伤、AOE 多目标结算、长休）→ 先攻列表与战斗轮；
+- **规则范围**：仅 DND5e/5r——专精 DND 定位，不做 COC/d100 体系与 `.mode` 模式切换；
+- **商店合规**：零配置可加载、本地存储走 `nonebot-plugin-localstore`、元数据完整、全程异步。
+
+## 📖 使用文档
+
+详细用法、输入/输出示例与常见问题见仓库 `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)
+
+## 📦 安装
+
+通过 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.5.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` 等常见单词命令与其他插件同时命中（冲突） |
+
+## 🎲 用法
+
+> 命令以 `.`（或全角 `。`）开头，中英文别名对齐 DicePP；命令起始符默认仅 `.` / `。`，
+> 如需用宿主斜杠 `/` 等起始符触发（如 `/.help`），请设置配置项 `dnddicer_use_host_command_starts=true`。
+> **群聊服务默认关闭（白名单）**：需群主/管理员发送 `.bot on` 开启本群服务；`.bot off`
+> 关闭后本群不再响应命令（`.bot` 本身不受影响）。群聊中使用 `.bot` 需先 @ 本机器人；
+> 私聊不受服务开关限制，可直接使用全部功能。
+
+### 🎲 掷骰（群聊 / 私聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.r [N#][hs][表达式] [原因]` | 掷骰表达式（`#` 连掷 1~10、`h` 暗骰、`s` 只显数值；仅 d20 有大成功/大失败播报） |
+| `.rh [表达式] [原因]` | 暗骰（群内提示、结果私聊） |
+
+### 📋 角色卡与检定（群聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.角色卡模板` / `.角色卡记录 <模板>` | 查看示例卡 / 记录或覆盖角色卡（`$…$` 分段模板） |
+| `.角色卡` / `.角色卡清除` / `.状态` | 查看 / 删除角色卡 / 查看 HP 与生命骰摘要 |
+| `.力量检定` / `.察觉检定+1` 等 | 属性/技能/先攻检定点命令，自动代入调整值/熟练/加值（`2#` 连掷、`+d4` 等可追加） |
+| `.体质豁免` / `.敏捷攻击优势` 等 | 豁免/攻击点命令（原名直配，优势/劣势后缀） |
+| `.先攻检定` | 掷先攻并自动写入本群先攻列表 |
+
+### 🎯 属性生成（群聊 / 私聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.dnd [次数] [原因]` | 4D6K3 掷点生成六项属性（附合计与降序，自行分配给六属性） |
+
+### ❤️ HP 与长休（群聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.hp [对象] 20/30 (5)` | 设置自己/队友 HP（含临时 HP） |
+| `.hp [对象] -2d6+3` 等 | 伤害/治疗（支持掷骰表达式；目标后加 `抗性`/`易伤` 后缀可减半/加倍，分号分隔多目标同发结算） |
+| `.hp` / `.hp list` / `.hp del` | 查看自己 / 本群列表 / 删除 |
+| `.长休` | 长休结算（回满 HP、清临时 HP、回复一半生命骰） |
+
+### ⚔️ 先攻与战斗轮（群聊）
+
+| 命令 | 说明 |
+| --- | --- |
+| `.ri[修正] [名称/…]` | 掷先攻入表（`.ri20 地精` 固定值、`3#` 批量、`.先攻` 别名） |
+| `.init` | 查看先攻列表（`del`/`clr`/`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. ⏳ **第二期 T2**：牌堆/随机表、规则查询；
+3. ⏳（可选）**T3 增强期**：法术位管理（`.ss/.cast`）、死亡豁免闭环（`.ds`）、BUFF/临时加值表（`.buff`）等。
+
+## 📦 本地开发
+
+```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 许可全文，来源按 MIT 要求在 LICENSE 中注明。
+- 规则查询类资料内容**不随插件分发**（版权归原权利方/译者），需要时由使用者自行提供。
+- 本项目与 nonebot-dicepp 无隶属关系，为独立命名的衍生/移植作品。

nonebot_plugin_dnddicer-0.1.0/docs/guide/attributes.md

@@ -0,0 +1,52 @@
+# 属性生成（.dnd）
+
+`.dnd` 按 DND5e 标准掷点法 **4D6K3** 生成一套六项属性：每项掷 4 个 D6、去掉最低的一个、剩余 3 个求和。**掷出的 6 个数值不绑定属性名**——由你自行分配给力量/敏捷/体质/智力/感知/魅力后，用 `.角色卡记录` 建卡。
+
+## 用法
+
+```
+.dnd [次数] [原因]
+```
+
+| 参数 | 说明 |
+| --- | --- |
+| 次数 | 可选，默认 1、上限 10（越界/非数字回退 1）。`.` 与命令名后可直接接数字（`.dnd2` 与 `.dnd 2` 等价） |
+| 原因 | 可选，跟在次数之后（截断 50 字符），显示在结果标题中 |
+
+群聊与私聊均可使用。
+
+## 示例
+
+```text
+你发送：.dnd
+骰娘回复：艾琳 DND人物作成:
+83 : [18, 17, 14, 13, 12, 9]
+```
+
+输出读法：`83` 是六项合计；`[18, 17, …]` 是六项数值的**降序**列表。
+示例中第一项 18 来自掷出 `6,6,6,1`（去掉 1 后 6+6+6）；每项属性都是这样独立掷出。
+
+多组与原因：
+
+```text
+你发送：.dnd 2 为了勇者
+骰娘回复：艾琳 DND人物作成——为了勇者:
+108 : [18, 18, 18, 18, 18, 18]
+108 : [18, 18, 18, 18, 18, 18]
+```
+
+> 注：标准购点（27 点）暂无先例（DicePP/海豹骰均无），本期未提供；
+> 如需购点建卡，可直接用 `.角色卡记录` 填写你购点得到的数值。
+
+## 建卡衔接
+
+拿到数值后，按顺序分配给六属性并建卡：
+
+```text
+你发送：.角色卡记录 $姓名$ 艾琳
+$等级$ 1
+$属性$ 18/14/13/12/9/17    ← 依次为 力量/敏捷/体质/智力/感知/魅力
+骰娘回复：角色卡已设置
+```
+
+角色卡与检定点命令见 [角色卡与检定](./character-card.md)。

nonebot_plugin_dnddicer-0.1.0/docs/guide/battle.md

@@ -0,0 +1,113 @@
+# 战斗轮（.br / .ed / .回合 / .轮次）
+
+战斗轮不是独立系统，而是**先攻表的"进行中状态机"**：`.br` 开局后，先攻列表
+变成回合队列，`.ed`（结束回合）自动推进到下一行动者，一轮走完自动进位。
+所有命令**仅限群聊**、作用于**本群**先攻表。
+
+## 命令一览
+
+| 命令 | 作用 |
+| --- | --- |
+| `.br` / `.战斗轮` | 新建战斗轮：清空本群先攻表与轮次指针，重新开局 |
+| `.回合` / `.轮次` | 查看当前轮与回合 |
+| `.回合 +1 / -1 / =2 / 2` | 回合前进/后退/直接跳转（越界自动进位轮次） |
+| `.回合 名字` | 按名字跳转到该行动者的回合（支持模糊） |
+| `.轮次 +1 / -1 / =3` | 调整轮次 |
+| `.ed` / `.结束` | 结束当前回合：播报 + 自动推进下一位；轮到玩家时输出 @ 提醒 |
+
+> 回合流转只需记住三条：玩家结束自己的回合用 `.ed`；DM 想连续推进多位直接发
+> `.回合+2`；想直接到某人的回合发 `.回合 名字`——没有也不需要额外的推进命令。
+
+## 开局顺序（重要）
+
+**先 `.br` 开局，再掷先攻入表**——`.br` 会**清空**本群先攻表（无论旧的还是刚掷的），若先掷先攻再 `.br`，先攻会被清掉。
+
+> `.br` 与 `.init clr` 的作用**完全等价**（都清空先攻表与轮次指针），区别只在播报文案：
+> `.br` 播「已创建新战斗轮。清除先攻表、当前回合。」（面向开局），
+> `.init clr` 播「已清除先攻列表」（面向清表）。
+> 战斗开局用 `.br`，战斗中清表用 `.init clr` 即可。
+
+## 完整时序示例
+
+**① 开局**——DM 发 `.br`，然后全员掷先攻（详见 [先攻列表](./initiative.md)）：
+
+```text
+你发送：.br
+骰娘回复：已创建新战斗轮。清除先攻表、当前回合。
+
+你发送：.ri            ← 掷先攻入表（也可以用 .先攻检定 联动）
+骰娘回复：艾琳的先攻值是 1D20=[15]=15
+
+你发送：.ri20 地精
+骰娘回复：地精的先攻值是 20
+
+你发送：.ri 兽人
+骰娘回复：兽人的先攻值是 1D20=[18]=18
+```
+
+**② 查看列表**（自动进入第 1 轮第 1 回合，先攻最高者行动）：
+
+```text
+你发送：.init
+骰娘回复：先攻列表如下: 
+当前是第1轮,地精的回合
+1.地精 先攻:20 
+2.兽人 先攻:18 
+3.艾琳 先攻:15
+```
+
+**③ 查看当前回合**：
+
+```text
+你发送：.回合
+骰娘回复：现在是第1轮第1回合，地精的回合。
+```
+
+**④ 结束回合自动推进**（`.ed`）：走完一轮自动进入下一轮并播报：
+
+```text
+你发送：.ed
+骰娘回复：地精的回合结束了。
+现在是兽人的回合。
+
+你发送：.ed
+骰娘回复：兽人的回合结束了。
+现在是艾琳的回合。请玩家 @艾琳 开始行动。   ← 轮到绑定 QQ 的玩家时输出 @ 提醒
+```
+
+**⑤ 手动调整回合/轮次**（DM 修正与连续推进）：
+
+```text
+你发送：.回合-1                     ← 回到上一行动者（艾琳 → 兽人）
+骰娘回复：现在是兽人的回合。
+
+你发送：.回合 地精                  ← 按名字跳转（精确→模糊）
+骰娘回复：现在是地精的回合。
+
+你发送：.回合+2                     ← 一次推进多位（地精是第 1 回合，+2 → 第 3 回合艾琳）
+骰娘回复：现在是艾琳的回合。请玩家 @艾琳 开始行动。
+
+你发送：.回合+1                     ← 艾琳是第 3 回合（本轮最后一位），+1 溢出自动进位轮次
+骰娘回复：新的一轮，现在是第2轮。
+现在是地精的回合。
+
+你发送：.轮次+1                     ← 轮次从第 2 轮前进到第 3 轮
+骰娘回复：现在变成第3轮了。
+现在是地精的回合。
+```
+
+**⑥ 结束战斗**（无需专门命令）：不再推进即可；下次 `.br` 重新开局。
+
+## 常见提示
+
+| 场景 | 回复 |
+| --- | --- |
+| 先攻表为空时操作战斗轮 | `目前先攻列表为空，故不存在回合与轮次。` |
+| `.回合 名字` 无匹配 / 多匹配 | `没有找到这个回合。` / `找到复数回合，请换一个关键词。` |
+| `.回合=9`（超出总人数） / `.回合=0` | `这个数字太大了。` / `这个数字太小了。` |
+| `.回合+abc`（非数字） | `这不是数字。` |
+
+## 一期范围说明
+
+- **BUFF 计时表不做**（本轮中自动到期的 BUFF 由 DM 手动管理）；
+- NPC 先攻条目不关联临时 HP；实体显示入表时快照的名称（离线可用）。