diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..31318e2
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,9 @@
+* text=auto
+*.py text eol=lf
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.json text eol=lf
+*.html text eol=lf
+*.txt text eol=lf
+*.png binary
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000..b6f5eb7
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,7 @@
+## 改动
+
+说明解决的问题和改动后的行为。
+
+## 验证
+
+列出已执行的检查及结果;涉及真实 API 或 AstrBot 收发时注明验证环境。
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..c6a04a0
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,51 @@
+name: CI
+
+on:
+ pull_request:
+ push:
+ branches: [main]
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ checks:
+ name: Python ${{ matrix.python-version }}
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ strategy:
+ fail-fast: false
+ matrix:
+ python-version: ['3.11', '3.12']
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+ - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+ with:
+ python-version: ${{ matrix.python-version }}
+ cache: pip
+ - name: Install development dependencies
+ run: python -m pip install -r requirements-dev.txt
+ - name: Check dependency compatibility
+ run: python -m pip check
+ - name: Check plugin metadata
+ run: |
+ python - <<'PY'
+ from pathlib import Path
+ import yaml
+
+ metadata = yaml.safe_load(Path('metadata.yaml').read_text(encoding='utf-8'))
+ for key in ('name', 'display_name', 'desc', 'version', 'author', 'repo'):
+ assert isinstance(metadata[key], str) and metadata[key].strip(), key
+ assert Path('README.md').is_file()
+ assert Path('logo.png').is_file()
+ assert Path('assets/readme-logo.png').is_file()
+ PY
+ - name: Check Python syntax
+ run: python -m compileall -q .
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..4b0b63c
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,9 @@
+__pycache__/
+.pytest_cache/
+*.py[cod]
+.venv/
+*.sqlite*
+*.db
+.env
+previews/
+dist/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..35f03b3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,92 @@
+

+
+# 断箭战报
+
+AstrBot 原生《断箭》(Broken Arrow)战绩查询插件。支持玩家概览、近期战绩、单局战报图片生成与默认账号绑定,不依赖大模型。
+
+> 首次使用需配置获准的 BATrace 客户端标识,并开启在线查询。
+
+## 快速开始
+
+1. **安装插件**:在 AstrBot 插件管理中导入 `astrbot_plugin_ba_stats_v0.1.0.zip`(或将插件目录放入 `data/plugins/` 并使用 AstrBot 的 Python 环境安装 `requirements.txt`)。
+2. **配置接入**:打开插件设置中的「数据源接入」,填入获准客户端标识(若运营方要求则填写 Bearer 令牌),开启「启用在线查询」。
+3. **保存重载**:保存配置并重载插件使其生效。
+4. **绑定与查询**:
+ - 发送 `/ba search 昵称` 搜索玩家
+ - 发送 `/ba bind stb:玩家ID` 并按提示发送 `/ba select 请求码 序号` 确认绑定
+ - 发送 `/ba me` 或 `/ba recent` 查看战报
+
+接入说明见 [API 说明](docs/API_NOTES.md)。
+
+## 命令列表
+
+默认前缀为 `/`(以实际 AstrBot 配置为准),英文子命令不区分大小写,开启中文别名后也可直接使用中文指令(如 `/ba 帮助`、`/ba 我`、`/ba 战绩`、`/ba 近期`、`/ba 上一场`、`/ba 单局`、`/ba 搜索`、`/ba 绑定`、`/ba 当前绑定`、`/ba 解绑`、`/ba 选择`、`/ba 取消`、`/ba 额度`)。
+
+| 命令 | 用途 |
+| --- | --- |
+| `/ba help` | 查看使用帮助与示例 |
+| `/ba me` | 查看自己默认绑定账号的玩家概览 |
+| `/ba stats ` | 查看指定玩家概览 |
+| `/ba recent [count]` | 查看自己近期战绩(默认 5 场,上限 20 场) |
+| `/ba me recent [count]` | 与 `/ba recent [count]` 等价 |
+| `/ba recent --limit N` | 查看指定玩家近期最多 `N` 场战绩 |
+| `/ba last [target]` | 查看自己或指定玩家最近一场可用单局战报 |
+| `/ba me last` | 与 `/ba last` 等价 |
+| `/ba match ` | 查看指定对局 ID 的单局战报 |
+| `/ba search ` | 搜索玩家候选,选择后查看概览 |
+| `/ba bind ` | 设置默认查询账号(不验证账号归属) |
+| `/ba binding` | 查看当前绑定(纯本地,不耗额度) |
+| `/ba unbind` | 解除当前绑定(纯本地,不耗额度) |
+| `/ba select ` | 确认候选编号(120 秒内有效,单次有效) |
+| `/ba cancel ` | 取消当前待确认选择 |
+| `/ba quota` | 查看个人、本群与全插件今日已用和剩余额度 |
+| `/ba status` | 管理员查看接入配置、请求与缓存状态 |
+| `/ba cache clear` | 管理员清理 API 与图片缓存(不影响绑定与额度) |
+
+### 目标玩家(`target`)写法
+
+支持 `me`、`@群友`、`stb:规范ID`、`name:完整昵称` 或普通非数字昵称:
+
+```text
+/ba stats "Player 2"
+/ba bind name:"Player 2"
+/ba recent name:"Player 2" --limit 10
+/ba recent 10
+/ba stats name:12345
+/ba stats name:me
+/ba stats @群友
+```
+
+- `@群友` 需使用聊天软件的真实提及功能,查询对方已绑定的账号。
+- 纯数字请加 `stb:`、`steam:` 或 `name:` 前缀(`/ba recent 10` 除外,该写法专指查询自己近期 10 场)。
+- `steam:SteamID64` 当前因映射尚未确认暂不可直接查询,请改用昵称搜索后选择 STB ID。
+
+## 主要配置
+
+可在 AstrBot 插件管理页直接调整,修改后需重载插件:
+
+- **数据源接入**:在线查询开关、获准客户端标识、访问令牌(可选)、API 地址。
+- **查询与命令**:默认/最大近期场数(5 / 20)、用户冷却(3 秒)、中文子命令别名开关。
+- **每日请求额度**:每用户默认 20 次、每群默认 100 次(可在 `0–100` 间调整,`0` 表示不单独限制);**全插件每日总上限固定为 100 次不可调整**。所有额度于北京时间每天 0 点重置,按上游 HTTP 请求计数,失败与重试也计入;命中缓存及本地命令不扣额。
+- **战报显示**:图片战报开关(渲染失败自动回退为同内容文字)、深浅主题(默认深色)、显示时区(默认 `Asia/Shanghai`)。
+- **维护与缓存**:请求间隔、并发、超时、重试及缓存容量/旧缓存回退时间。
+
+## 数据与常见问题
+
+- **为什么有字段显示「暂无」?**:当数据源未提供、未收录地图/单位名称,或胜负/模式语义尚未确认时,插件会显示「暂无」或来源 ID,不以猜测数据替代。
+- **为什么没查满 20 次就提示额度用完?**:额度按上游 HTTP 请求次数计算,单条战报命令可能触发多次接口请求(如未命中缓存的概览需请求搜索、分析与近期列表),个人额度跨群及私聊累计,可用 `/ba quota` 查看用量;重载或清缓存不会重置额度。
+- **只收到文字没有图片?**:请检查「发送图片战报」是否开启及 AstrBot HTML 渲染服务是否正常。
+- **同名玩家怎么区分?**:请核对候选列表中的规范 STB ID 与来源链接后再发送 `/ba select` 确认。
+
+## 开发与许可
+
+- 宿主基线:AstrBot **v4.29.4**(详细测试与验证记录见 [验证记录](docs/VALIDATION.md))。
+- 开源协议:**Apache-2.0**。
+- 致谢与参考:[BATrace](https://dash.batrace.top/)(战绩数据源)、[AlexanderHYu/ba-dragon](https://github.com/AlexanderHYu/ba-dragon)、[benx1n/wows-stats-bot](https://github.com/benx1n/wows-stats-bot)、[timeance/astrbot_plugin_openai_native](https://github.com/timeance/astrbot_plugin_openai_native)、AstrBot(第三方边界说明见 [第三方说明](docs/THIRD_PARTY.md))。
+
+```sh
+python -m pip install -r requirements-dev.txt
+python -m pytest -q
+python -m playwright install chromium
+python tools/render_previews.py --help
+```
diff --git a/__init__.py b/__init__.py
new file mode 100644
index 0000000..6552b6d
--- /dev/null
+++ b/__init__.py
@@ -0,0 +1 @@
+"""断箭战报:AstrBot 原生插件。"""
diff --git a/assets/readme-logo.png b/assets/readme-logo.png
new file mode 100644
index 0000000..7b4a7d4
Binary files /dev/null and b/assets/readme-logo.png differ
diff --git a/docs/API_NOTES.md b/docs/API_NOTES.md
new file mode 100644
index 0000000..3dfcacc
--- /dev/null
+++ b/docs/API_NOTES.md
@@ -0,0 +1,181 @@
+# BATrace 接口核对与本地适配契约
+
+核对日期:2026-11-17。**本地客户端与合成响应测试已实现;真实接口联调未完成。**
+本次只读取公开 GitHub 源码,没有请求 BATrace 数据接口,没有复用其他项目身份、联系第三方或进行浏览器验证。
+
+## 证据与版本
+
+- 参考仓库:`AlexanderHYu/ba-dragon`,默认分支 `main`。
+- 执行时 GitHub connector 查询的分支提交:`072dc9bc2d73ffc87000c1d3db4c0f9b4dcab549`,提交时间 `2026-11-13T02:22:27Z`;`package.json` 版本 `2.0.1`。
+- 客户端实现:[src/main/services/batrace.ts](https://github.com/AlexanderHYu/ba-dragon/blob/072dc9bc2d73ffc87000c1d3db4c0f9b4dcab549/src/main/services/batrace.ts)。
+- 字段定义:[src/shared/types/batrace.ts](https://github.com/AlexanderHYu/ba-dragon/blob/072dc9bc2d73ffc87000c1d3db4c0f9b4dcab549/src/shared/types/batrace.ts)。
+- 玩家与评分来源:[src/main/services/players.ts](https://github.com/AlexanderHYu/ba-dragon/blob/072dc9bc2d73ffc87000c1d3db4c0f9b4dcab549/src/main/services/players.ts)。
+- 列表时间语义:[src/main/services/matchSync.ts](https://github.com/AlexanderHYu/ba-dragon/blob/072dc9bc2d73ffc87000c1d3db4c0f9b4dcab549/src/main/services/matchSync.ts)。
+- 公开页面路径:[PlayerDetail.tsx 第 203、403 行](https://github.com/AlexanderHYu/ba-dragon/blob/072dc9bc2d73ffc87000c1d3db4c0f9b4dcab549/src/renderer/src/features/players/PlayerDetail.tsx)。
+- 使用许可说明:[README](https://github.com/AlexanderHYu/ba-dragon/blob/072dc9bc2d73ffc87000c1d3db4c0f9b4dcab549/README.md);源码许可证:[LICENSE](https://github.com/AlexanderHYu/ba-dragon/blob/072dc9bc2d73ffc87000c1d3db4c0f9b4dcab549/LICENSE)。
+- 主代理选定的 AstrBot 稳定基线:`v4.29.4`,`61335414433db721b3f7ecc93f90deafe0a59d78`;框架适配与总验收由主代理记录。
+
+研究快照位于本次会话根目录 `references/ba-dragon-072dc9bc/`,不进入插件 ZIP。
+这是参考客户端的实际使用契约,**不是 BATrace 运营方发布的完整 API 规范,也不证明本插件获准访问**。
+
+## 接入与鉴权边界
+
+参考源码的 API origin 是 `https://bot.batrace.top`,公开页面 origin 是 `https://dash.batrace.top`。
+源码使用 `X-Client` 标识,取值属于该项目自己的放行身份;README 的使用同意针对该工具,不延伸为其他插件的许可。
+本插件不会预置或发送该项目的标识,并拒绝包含 `ba-dragon` 的客户端标识。
+
+配置由主代理统一读取:`access.enabled=false`、`base_url=https://bot.batrace.top`、`client_id=''`、`api_token=''`。
+`enabled=true`、合法 HTTPS origin 和本插件自己的获准 `client_id` 缺一不可;未配置时在缓存与网络操作之前抛出 `NotConfiguredError`。
+构造、状态查看、关闭均不探活。没有凭据时不发匿名探测,也不回退到网页抓取或验证码绕行。
+
+本插件发送自己的 `User-Agent: astrbot-plugin-ba-stats` 和配置的 `X-Client`。
+`api_token` 非空时支持 `Authorization: Bearer `,**这只是配置支持,不是已核实的 BATrace 鉴权要求**;只能在运营方明确认可该方案后配置。
+若对方要求不同机制,应先核实并调整适配,不能尝试猜测凭据或身份。
+token 不出现在 `ClientConfig` 的 repr、status、异常消息或缓存明文 key 中。
+
+参考客户端文件头还保留“不发自定义 UA”的旧注释,但该提交的 `CLIENT_HEADERS()` 实际发送自定义 UA 和 `X-Client`;本说明以现行代码为准,未据旧注释模拟浏览器。
+参考工具采用串行、约 1.2 秒间隔,网络/5xx 约 30 秒后重试一次。这些是该工具的本地策略,**不能宣传为本插件获准的上游限额或通用放行办法**。
+
+## 观察到的 GET 路径
+
+| 路径 | 参数 | 观察到的响应形状 | 本插件用途与边界 |
+| --- | --- | --- | --- |
+| `/api/players/search` | `q`、`limit` | `{players:[{id,name,level?,rating?,rating_games?,updated_at?}]}` | 候选按字符串 ID 去重,返回前 20 项;不假装已搜遍全库 |
+| `/api/analysis/player` | `stbid` | `{matchCount?,trend?:{points?},highlightUnits?,categoryPreferences?,mapPerformance?,playStyle?}` | 玩家身份核对后读取有时间的评分观察;不输出生涯胜率 |
+| `/api/players/info` | `stbid` | `{info?:{name?},statInfo?:{...}}` | 已研究但未调用;已知 shape 不含规范 ID,不能单独完成身份校验 |
+| `/api/players/matches` | `stbid`、`limit` | `{matches:[{matchId,data:MatchInfo}]}` | 最近样本;reference 说明单次最多 20,未独立验证;不实现历史分页 |
+| `/api/match` | `matchid` | `{matchInfo:MatchInfo}` | 单局;若额外返回根级 `matchId`,必须与请求一致 |
+
+公开页面路径在参考 UI 中明确出现:`/player/<规范ID>`、`/match/<对局ID>`。
+模型据此生成 URL 并对 ID 做路径编码;**只确认源码中的使用方式,没有确认当前页面在线可达、是否需要登录或是否完整展示身份资料**。
+绑定应同时显示最终名称、规范 ID 和该玩家链接,不声称完成 Steam 所有权认证。
+
+`q=<规范ID>` 是否必定返回该规范 ID,缺少运营方文档及本插件真实响应验证。
+`player(id)` 当前先调用该搜索,再要求候选中出现完全相同的 `id`,之后才请求分析;没有回显则抛 `IdentityMismatchError`,不能接受第一条或同名结果。
+这是一条明确的上线依赖:若合法实测证明搜索不支持 ID,应取得有 ID 回显的权威接口后修改适配,不能绕过校验。
+SteamID64 与 STB ID 均保持字符串;**未找到可靠的 Steam→STB 映射,不实现自动映射或同名猜测**。
+
+## 字段归一化
+
+`models.py` 为插件独立的 dataclass:
+
+| 模型 | 字段 |
+| --- | --- |
+| `Player` | `id, name, steam_id?, elo?, source_url?, updated_at?, elo_observed_at?` |
+| `Participant` | `player_id, name, team?, outcome, elo?, elo_delta?, kills?, losses?, destroyed_value?, lost_value?, units` |
+| `Match` | `id, map_name?, mode, started_at?, duration_seconds?, winner_team?, players, complete, source_url?, updated_at?` |
+| `FetchResult[T]` | `data, fetched_at, stale=False, source_updated_at?, stale_reason?` |
+
+- 外部 ID 只接收字符串或整数,不接收布尔、浮点或按位数猜测的身份;转换不会丢掉字符串前导零。
+- 搜索 `rating` 是档案快照;`updated_at` 保留源时间。分析 `trend.points` 中显式 `ratingAfter` 配合 `endTime`,按实际时间选最新,不依赖数组顺序。已知更新时间更新的搜索评分优先。
+- `elo_observed_at` 表示评分观察对应的对局结束时间;它不是源记录更新时间。`source_updated_at` 不会用抓取时间或对局结束时间冒充。
+- 只解析 Unix **秒**或带明确时区的 ISO 时间,内部为 aware UTC;不猜毫秒、不按机器本地时区解释无时区字符串。真实源若使用其他格式,须先核实其时区及单位再适配。
+- `MatchInfo` 已观察到 `MapId, Type, StartTime, EndTime, TotalPlayTimeInSec, Data`。列表可能只有结束时间,结束时间和时长都在时倒推开始时间;没有时间则保持未知。
+- `Data` 为参与者对象字典,条目的 `Id` 为玩家规范 ID;不把对象键当 ID。重复参与者 ID、无 ID 或变更为其他集合结构均报结构错误。
+- `OldRating/NewRating` 仅用于 `elo/elo_delta`;**本版不将评分涨跌转换成胜负**。参考项目的推断没有权威胜负语义证据,故 `winner_team=None`、`outcome='unknown'`。
+- `Type` 枚举未得到可靠释义,故 `mode='unknown'`。缺评分或评分不变不能证明是自定义局;参考工具的“未计分”筛选也不能替代源模式。
+- `Destruction/Losses` 对应单位数量,`DestructionScore/LossesScore` 对应摧毁/损失价值;两者不可混算。只在已识别的 protobuf 参与者 shape 中,对这四个省略字段和 `TeamId` 应用参考源码明确记载的零默认值;四个计数显式 null 保持未知,`TeamId` 显式 null 报结构错误。其他来源与 dataclass 默认不填零。
+- 名字缺失为空字符串;地图表未核实,已有 `MapId` 显示 `地图#`。不下载单位表或游戏资产。
+- `UnitData` 对象的每条记录只归一化为 `{id, name?, count:1}`;名称通常缺失。这里是**出场记录数**,飞机重复出动可能多条,不是独立单位数、击杀数、费用或兵种偏好。不会估算配装价或单位摧毁价值。
+- `complete` 是保守的**本地缓存完整度标记**:单局详情有结束时间、参与者且每人显式含 `UnitData` 对象才为真;不代表源端声明“数据最终完成”。列表始终为 false。结束不足五分钟的详情仍仅缓存 60 秒。
+- 最近对局按稳定 ID 去重、按实际开始时间降序,未知时间放最后;相同 ID 优先保留参与者更多的记录。返回实际样本数,不冒称完整历史或完整排位样本。
+- `players/matches` 必须显式返回数组。缺数组、错误对象、非 JSON/验证码响应不能当成“零搜索结果/零场对局”。
+
+## client 与 storage 契约
+
+```python
+client = BatraceClient(
+ config=ClientConfig(
+ enabled=False, base_url="https://bot.batrace.top", client_id="", api_token="",
+ request_interval=1, concurrency=2, queue_size=20,
+ request_timeout=20, wait_timeout=45, retries=1,
+ cache_max_entries=1000, stale_hours=24,
+ user_daily_limit=20, group_daily_limit=100,
+ ),
+ storage=storage, # 已 open 的 Storage(data_dir)
+ http_client=async_client, # 可省略,首次获准请求时才内部创建
+)
+```
+
+方法:`search(query, *, force=False) -> FetchResult[list[Player]]`、
+`player(id, *, force=False) -> FetchResult[Player]`、
+`recent(id, limit=5, *, force=False) -> FetchResult[list[Match]]`、
+`match(id, *, force=False) -> FetchResult[Match]`、`clear_cache()`、`close()`。
+`status()` 是同步安全摘要,返回 configured/closed/inflight/requests/cache_hits/stale_hits/last_error。
+其中 `requests` 为本次运行的 HTTP 尝试数;每日持久用量由 `await storage.quota_usage(actor)` 提供。
+`namespace` 只由数据源 `base_url` 生成,供持久绑定使用;内部缓存命名空间另外包含客户端身份/token 的摘要,凭据轮换不改变绑定身份。
+
+storage 为 duck type:`get_cache(key) -> (JSON payload, fetched_at, expires_at) | None`,过期但保留的记录也应返回;
+`put_cache(key,payload,ttl)`、`clear_cache()`、`prune_cache(max_entries=...,max_age_seconds=...)`、`cache_count()`。
+另需 `consume_request(actor=None, *, user_limit=20, group_limit=100)` 在每次 HTTP 尝试前原子检查并持久增加额度;`quota_usage(actor=None)` 只读返回 `day/global/user/group`。无 actor 时只有全局计数,user/group 为 None。
+生产使用 SQLite Storage;client 不另建数据库,不触碰绑定。时间戳可用 Unix 秒或 aware datetime。
+缓存存的是已校验的**原始 JSON**(player 为 search+analysis 的私有组合),读取后重新适配,不持久化 dataclass。
+每次写入后按 client 上限清理,保留期限 604800 秒;创建 Storage 时也应传相同 `max_entries`,避免其内部提前按更小上限裁剪。
+
+调度由一个插件实例共享一个 client:
+
+- 所有真实请求统一经过全局起始间隔;并发上限和有界等待分别生效。最多接受 `concurrency + queue_size` 个不同查询任务,同一 `QuotaActor` 的同查询等待者共享同一个任务。不同用户或群不合并网络任务,已完成的缓存仍共享。
+- 整体 `wait_timeout` 包括缓存读取、排队、节流、网络、退避和缓存写入;`request_timeout` 另限制单次 HTTP。未启用时不存在后台探活任务。
+- `force=True` 绕过新鲜缓存。加入尚在读缓存的非 force 任务时会将共享任务提升为刷新;加入已经发送的上游任务仍只请求一次。它仍受同一队列、间隔和上游退避限制。
+- 网络异常、超时、5xx 最多按配置重试,默认退避 30 秒;429 解析 `Retry-After` 秒数或 HTTP date,缺失时退避 30 秒。长于整体预算时不会突破预算;下一查询也保留已知退避窗口。
+- 鉴权、404、参数错误、结构变化不重试。429 或临时服务故障可能返回旧缓存,但必须带原抓取时间和 `stale=True/stale_reason`;默认只允许抓取后 24 小时内的记录。**绑定端应拒绝 stale**。
+- 清缓存有代次隔离:清理前发起、之后才完成的任务不会重新写入旧缓存;不删除绑定或额度记录。
+- 一个等待者取消不影响其他合并等待者;最后一个等待者取消会取消并等待共享任务。`close()` 取消并等待所有运行中与排队任务,之后新调用抛 `ClientClosedError`。
+- 内部创建的 HTTP client 由 `close()` 关闭;注入的 HTTP client 与 Storage 仍由调用者关闭。没有永久 worker/周期任务。
+
+这些缓存与调度数值全部是**本地默认值**,上线应服从本插件实际获准的配额,不能据参考软件的使用策略推断许可或额度。
+
+## 每日请求限额
+
+全局 `GLOBAL_DAILY_LIMIT=100` 固定,不在 `ClientConfig`、`Settings` 或配置 Schema 中提供可调字段。用户默认 20、群默认 100,在 `limits.user_daily_limit` 和 `limits.group_daily_limit` 调整,范围 0–100,0 只取消该层限制。全部固定北京时间(UTC+8)0 点切换日期,不依赖显示时区或宿主机器时区;不提供管理员豁免。
+
+AstrBot 适配器从事件的 `get_platform_id()/get_sender_id()/get_group_id()` 生成 `QuotaActor`,通过 `with client.request_scope(actor)` 覆盖整个业务调用;`ContextVar` 传播到子任务、后续接口及重试。身份不来自命令里的查询对象或 @ 目标。用户按平台实例跨群及私聊累计,群按平台实例和群 ID 汇总,全局覆盖本插件数据库内全部平台。
+
+每次 `_request` 的每个 HTTP 尝试,在节流排队后、发送前调用 `Storage.consume_request`。SQLite 事务同时检查三层额度,再一起增加;不足则抛出 `QuotaExceededError`,其他层不增加。新鲜缓存判断后、网络退避前以及旧缓存回退前会只读检查额度,避免额度耗尽后因排队超时返回旧缓存。失败及重试计入;缓存命中、队列中取消、本地命令和图像渲染不计入。为防止断电或取消造成超额,已持久记账的尝试不退款;很小的记账后、发送前中断窗口可能保守多记一次。
+
+查询概览通常包含多个 HTTP,部分请求已发出后额度不足,会保留已用次数并中止剩余调用;绑定逻辑不会据不完整结果修改原绑定。额度不足时可读取新鲜缓存,但不会以 stale 回退隐藏该错误。网络合并仅限同一用户、同一群,防止其他调用者的强制刷新扣到原发起者。
+
+额度表独立于缓存及凭据命名空间;重开数据库、清缓存、改凭据、调整限制不清零。无 Storage 的独立适配器只有进程内全局计数,`request_scope` 拒绝该模式;生产插件始终使用持久 Storage。`/ba quota` 为无需接入许可的本地只读查询。
+
+## 失败语义
+
+| 异常/code | 含义 | 可用 stale |
+| --- | --- | --- |
+| `NotConfiguredError / not_configured` | 缺自身接入配置,未发请求 | 否 |
+| `AuthenticationError / authentication` | 401/403 或明确验证码页 | 否 |
+| `NoDataError / no_data` | 404 + JSON,暂无收录;不证明账号不存在 | 否 |
+| `IdentityMismatchError / identity_mismatch` | 规范 ID 未回显,或近期列表包含其他玩家对局 | 否 |
+| `SchemaError / schema` | 字段结构、类型、时间、数值或内容格式不符合适配契约 | 否 |
+| `RateLimitError / rate_limited` | 429,可读取 retry_after | 是 |
+| `RequestTimeoutError / timeout` | 单次超时或整体等待用尽 | 是 |
+| `UpstreamError / upstream` | 连接故障或 5xx | 是 |
+| `QueueFullError / queue_full` | 本地并发与等待名额用尽 | 否 |
+| `QuotaExceededError / daily_quota` | 本地用户、群或全插件今日额度不足;scope/limit/used 表示触发范围 | 否 |
+| `ClientClosedError / closed` | 关闭中或已关闭 | 否 |
+
+搜索成功返回空数组才表示“当前查询没有候选”;其他非成功状态不改写成玩家不存在,不清绑定。
+其他 JSON 4xx 抛 `ClientError / client_error` 并只保留 HTTP 状态,不输出上游任意错误正文或请求凭据。
+
+## 测试与上线前核对
+
+`tests/test_client.py`、`tests/test_models.py` 的 fixture 全部为**明确标识的合成数据**,HTTP 使用 `httpx.MockTransport`,SQLite 使用临时目录。
+它们验证契约、缓存持久化、同请求合并、有界队列、节流/并发、超时、限流/重试、取消/关闭、force 竞争、规范身份和未知值行为;不证明 BATrace 当前真实响应吻合。
+
+离线运行:`python -m pytest -q`。新增每日限额测试覆盖持久计数、北京时间日界、并发边界、失败/重试计数、缓存免费与身份传播;当前完整结果见 [验证记录](VALIDATION.md)。所有真实 SQLite 重开测试也使用临时目录,没有访问真实账号或 BATrace。
+真实联调与实际平台验证均未执行。框架、service、render、平台与总验证详见主代理交付记录。
+
+最少还需补齐:本插件可使用的 API origin、自身获准身份/鉴权方式、允许接口与查询范围、实际并发/请求间隔/退避与缓存政策。
+随后在明确授权的最小调用量内依次核对:
+
+1. 以已知玩家名搜索,确认规范 ID、updated_at 格式/时区和截断规则。
+2. 核实 `q=<规范ID>` 是否可靠回显;确认有 ID 的权威详情能力后再验收绑定 revalidation。
+3. 核对分析评分时序、最新评分语义、列表实际上限,以及列表/详情的字段大小写、秒单位和 protobuf 省略默认值。
+4. 获取权威模式枚举与真实胜负字段;没有证据则继续显示未知,不以 ELO 涨跌替代。
+5. 在授权测试账号上检查玩家/单局页面链接和真实无收录、鉴权、限流响应;不得故意压测上游来测限流。
+6. 再由主代理在明确授权的 AstrBot 测试会话验收查询与绑定;未完成前保持“真实接口联调待完成”。
+
+## 许可与独立实现
+
+该提交的 ba-dragon 主源码为 MIT,LICENSE 载明 AlexanderHYu 与沿用部分的 Zola 版权;其 README 另外说明可选录像使用 GPL FFmpeg。
+本插件只依据公开的路径、参数与字段事实独立编写 Python 调度、数据模型和测试,没有复制其评分模型、录像、游戏数据、FFmpeg 或其他 GPL 实质代码。
+本仓库原有 Apache-2.0 LICENSE 保持不变;来源致谢和全项目第三方说明由主代理统一维护。
diff --git a/docs/THIRD_PARTY.md b/docs/THIRD_PARTY.md
new file mode 100644
index 0000000..447c834
--- /dev/null
+++ b/docs/THIRD_PARTY.md
@@ -0,0 +1,18 @@
+# 来源与许可
+
+本项目既有许可证为 Apache-2.0,原始仓库基线为 `c4272e87413734ec317fe937faa868bbbf70eb08`。新增代码按该许可证提供;第三方服务数据、产品名称和交接图像不因本项目代码许可证而获得额外授权。
+
+| 来源 | 本次用途 | 固定版本 |
+| --- | --- | --- |
+| [AstrBot](https://github.com/astrbotdevs/astrbot) | 原生插件 API、ZIP 格式与配置 Schema 核对 | v4.29.4,`61335414433db721b3f7ecc93f90deafe0a59d78` |
+| [AstrBot T2I](https://github.com/AstrBotDevs/astrbot-t2i-service) | 核对 `viewport_width`、像素比及 JPEG 质量参数 | `bcc08e47274c69e5ace19bbf738b95260ce17ca7` |
+| [ba-dragon](https://github.com/AlexanderHYu/ba-dragon) | BATrace 请求形态、ID 与字段语义研究 | 见 API_NOTES.md |
+| [wows-stats-bot](https://github.com/benx1n/wows-stats-bot) | README 中绑定与 @ 查询的交互研究,未移植 HoshinoBot 实现 | master,`80c86970685887578054e61e1a76d1589ea1dc31` |
+| [BATrace](https://dash.batrace.top/) | 预期战绩数据来源 | 自身接入许可、配额及真实字段待确认 |
+| [astrbot_plugin_openai_native](https://github.com/timeance/astrbot_plugin_openai_native) | 参考用户跨群累计、群共享额度、配置提示与额度查询;按本任务要求统一私聊用户计数和北京时间日界 | main,`98bd76784bb2a35df0aea968138f87fd4d9ee207`;核对 README、配置 Schema、事件身份提取 |
+
+研究不等于获得服务调用许可。插件不内置参考项目的获准标识或密钥。测试负载与卡片预览为明确标识的合成样本。
+
+未复制参考项目的非琐碎源码、图片、字体或样式到插件。依赖由宿主环境安装,安装 ZIP 不附带第三方库;各依赖许可证以其发布包为准。预览工具使用本地 Playwright/Chromium,仅用于开发验收,运行插件不需要安装它们。
+
+`logo.png` 与 `assets/readme-logo.png` 原样来自用户交接包,交付时核对 SHA-256 一致。它们的授权与来源由交接提供方负责说明,本项目没有代替权利人作版权声明。
diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md
new file mode 100644
index 0000000..2219b29
--- /dev/null
+++ b/docs/VALIDATION.md
@@ -0,0 +1,111 @@
+# 首版验证记录
+
+验证日期:2026-11-17(Asia/Hong_Kong)。版本:v0.1.0。
+
+## 结果边界
+
+| 项目 | 结果 |
+| --- | --- |
+| 首版代码与文档 | 已实现;按项目框架、插件实现两个 PR 审阅 |
+| 离线业务与契约测试 | **392 passed,19.49 秒**(含新增每日额度) |
+| 本地卡片渲染 | 18 组 HTML/文字、36 张 PNG;布局与外部请求检查全通过 |
+| 成品目视检查 | 主代理查看 4 张代表图;渲染子代理另查看 9 张 |
+| Python 语法检查 | 全部通过 |
+| 两张 Logo 原样核对 | SHA-256 与交接包一致 |
+| AstrBot API 兼容性研究 | 核对 v4.29.4 固定源码,插件适配器用本地桩测试 |
+| 完整 AstrBot 服务启动/真实 html_render | **尚未执行** |
+| BATrace 真实接口联调 | **尚未执行,缺本插件独立获准接入** |
+| QQ OneBot v11 群聊与私聊 | **尚未执行,未发送真实消息** |
+| GitHub PR / 发布 / 部署 | 远端检查以对应 PR 为准;本记录不代表发布或部署验收 |
+
+API 与模型 fixture、渲染预览均为合成数据。HTTP 测试使用 `httpx.MockTransport`,不调用 BATrace。`tests/test_main.py` 在测试作用域注入 AstrBot 桩并恢复,不代表真实框架启动成功。
+
+## 文案导入与 CI
+
+Gemini 返回的 331 条文案全部匹配导出基线;回填 68 条变化,并校正其中 4 处语义。README 沿用用户要求的简版,详细说明保留在 `docs`。同步旧文案断言后,推荐候选的 392 项离线测试全部通过;正式导入逐文件核对与候选一致。
+
+项目 CI 使用 Python 3.11 / 3.12,执行依赖兼容性、元数据和语法检查;插件实现 PR 增加完整离线测试和安装包构建检查。CI 不调用真实战绩 API,也不发送 QQ 消息。
+
+## 核对基线
+
+- 目标仓库初始 `main`:`c4272e87413734ec317fe937faa868bbbf70eb08`,原来仅有 Apache-2.0 LICENSE。
+- AstrBot:v4.29.4,`61335414433db721b3f7ecc93f90deafe0a59d78`。
+- 发布列表中有更新的 v4.30.0-alpha.1;虽然 GitHub `prerelease` 字段为 false,版本名仍为 alpha,本次没有作为稳定目标。
+- ba-dragon:`072dc9bc2d73ffc87000c1d3db4c0f9b4dcab549`,接口研究细节见 API_NOTES.md。
+- wows-stats-bot:`80c86970685887578054e61e1a76d1589ea1dc31`,只参考 README 中绑定/@ 查询的交互方式。
+- OpenAI Native 插件:`98bd76784bb2a35df0aea968138f87fd4d9ee207`,按用户指定参考额度交互和配置设计;本次采用用户默认 20、群默认 100、总额固定 100 及北京时间 0 点重置。
+- AstrBot T2I:`bcc08e47274c69e5ace19bbf738b95260ce17ca7`,核对视口、像素比、截图类型参数。运行插件使用 390 CSS 像素视口与 ultra 像素比;JPEG 质量 85。实际用户部署的渲染服务版本仍需联调。
+
+## 环境和执行命令
+
+Windows,Python 3.11.4;httpx 0.28.1、aiosqlite 0.22.1、Jinja2 3.1.6、pytest 9.2.0、pytest-asyncio 1.5.0、Playwright 1.65.2、tzdata 2026.6。
+本地 Chromium 为 159.0.8154.6(Playwright build 1255)。这是测试环境记录,不是对所有环境的兼容承诺。
+
+会话工作目录:`H:\Codex\01a1e923-f766-7562-b804-35854a994fc4`;以下命令在其中的 `astrbot_plugin_ba_stats` 仓库执行。
+
+```powershell
+& ../.venv/Scripts/python.exe -m pytest -q --basetemp=../tmp/pytest-quota-final
+# 392 passed in 19.49s
+
+$env:PLAYWRIGHT_BROWSERS_PATH = '../.playwright'
+& ../.venv/Scripts/python.exe -B tools/render_previews.py --screenshots
+# Synthetic previews: 18 HTML/text pairs; 36 screenshots; 0 layout/network failures.
+
+& ../.venv/Scripts/python.exe -m compileall -q .
+# exit 0
+```
+
+最初依赖安装遇到 Windows 临时目录写入限制,改用会话内临时目录后安装成功。Chromium 下载的一次连接重置由下载器切换官方镜像后恢复;最终安装成功。未更改共享环境、系统 ACL、SSH 配置或用户密钥。
+
+## 测试覆盖的风险
+
+- 命令别名一致、`recent 10` 和 `me recent 10`、带目标 `--limit`、空格昵称、数字/关键词昵称、真实结构化 @ 与手写标记拒绝。
+- STB/Steam 分离、未验证映射明确失败、规范 ID 回显核对、同名去重及候选截断提示。
+- 平台/用户/会话隔离、旧异步结果晚到、过期和越界、单次选择、选择期间新操作与跨群解绑竞争。
+- 只读选择不改绑定、绑定重启持久、失败保留原绑定、清缓存不删绑定。
+- 已确认字段的归一化、未知胜负/模式、数量和价值分离、缺失/零损失、重复与乱序对局。
+- 新鲜/旧缓存、同请求合并、force 刷新竞争、有界队列、限流/超时/鉴权/结构错误、取消和关闭恢复。
+- 管理员权限、未配置时本地命令、同一结果渲染失败回退、模板转义与 `{{7*7}}` 作为文字保留、卸载关闭资源。
+- 每用户默认 20、每群默认 100 可调,总上限 100 固定;并发及多 SQLite 连接同时扣额不超限,任一桶不足时其他桶不扣额。
+- 用户跨群及私聊累计、群跨用户累计、不同平台身份隔离、查询 @ 群友扣发送者;管理员查询无豁免,缓存与本地命令不扣额。
+- 北京时间 23:59:59/00:00 日期切换、跨午夜排队、重开数据库/清缓存/改凭据保留计数、提交前取消及异常回滚。
+- 每次 HTTP 尝试在发送前记账,失败及重试计入;设置项没有总额度或日界时区的可调入口。
+- 子代理复现的「额度耗尽后受退避阻塞,先超时再回退旧缓存」已修复:增加只读预检及回退前复核,新增回归测试通过。
+
+## 图像验证
+
+预览矩阵:overview/recent/match × normal/long-name/missing × dark/light;每组检查 980px 和 390px。
+浏览器 context 使用离线模式并拦截外部请求,未打开外部网页、账号或登录态。
+
+主代理实际打开并检查:
+
+- `overview-normal-dark-desktop.png`:主要数字、单位、样本范围与来源层级。
+- `recent-normal-light-mobile.png`:手机尺寸的逐局阅读、明确胜负样本标签、数量/价值指标区分。
+- `match-missing-light-mobile.png`:缺失字段、不完整队伍、零人队伍与旧缓存说明。
+- `overview-long-name-light-mobile.png`:长中文/英文、长 ID、Jinja 字面文本、折行不裁切。
+
+预览明确标注「合成样本 · 非真实玩家战绩」。其中用于展示胜负、排位等状态的合成字段,不表示当前 BATrace 适配器已获得这些字段的权威语义。生产适配器对此保持未知。
+截图与 `manifest.json` 随总交付 ZIP 提供;布局自动检查与目视检查分别记录,不替代真实 QQ 图片显示验收。
+
+新增额度功能的可见界面变化为命令文字和原生设置;三类卡片模板和样式未修改,复用上述已经通过的本地渲染检查。
+
+## 安装包与文案交付
+
+构建工具:`python tools/build_delivery.py`。
+
+- 插件 ZIP 有单一 `astrbot_plugin_ba_stats/` 根目录及原生入口、元数据、配置、依赖、模板和文档。
+- 完整源码另含测试和开发工具;安装 ZIP 不包含测试环境、真实凭据、个人数据库、缓存、Git 目录或参考项目源码。
+- 文案优化 ZIP 包含 Gemini 任务说明、事实约束、带位置的 JSON/CSV 清单、README、原始提示与模板,以及合成预览。占位符、命令、配置键和数据口径标为不可随意修改。
+- 总 ZIP 与嵌套 ZIP 使用 `testzip()` 检查,保存源码 SHA-256,原始 Logo 哈希如下。
+
+```text
+logo.png
+7b93b4513cc84535155e4e4edf63b7a36b17321823e05ce0b494369d03b6e616
+
+assets/readme-logo.png
+2acb2855440c8ec609370789866857ca80e9c4c73a1cd1379f9b23d5c15e65a7
+```
+
+## 下一步真实验收
+
+先取得本插件可用的 API origin、获准身份/鉴权方式、接口范围、请求额度与缓存政策。按 API_NOTES.md 的最小调用步骤验证 ID 回显、时间单位、胜负/模式与字段结构,再在明确授权的 AstrBot/QQ 测试会话验收绑定、搜索和三类战报。没有这些条件时保持在线开关关闭。
diff --git a/logo.png b/logo.png
new file mode 100644
index 0000000..66ea26e
Binary files /dev/null and b/logo.png differ
diff --git a/metadata.yaml b/metadata.yaml
new file mode 100644
index 0000000..f09c5ac
--- /dev/null
+++ b/metadata.yaml
@@ -0,0 +1,6 @@
+name: astrbot_plugin_ba_stats
+display_name: 断箭战报
+desc: "《断箭》(Broken Arrow)玩家查询、账号绑定、近期战绩与单局战报插件(需独立获准的 BATrace 接入)。"
+version: v0.1.0
+author: timeance
+repo: https://github.com/timeance/astrbot_plugin_BA_stats
diff --git a/pytest.ini b/pytest.ini
new file mode 100644
index 0000000..64baef7
--- /dev/null
+++ b/pytest.ini
@@ -0,0 +1,4 @@
+[pytest]
+asyncio_mode = auto
+asyncio_default_fixture_loop_scope = function
+testpaths = tests
diff --git a/requirements-dev.txt b/requirements-dev.txt
new file mode 100644
index 0000000..5ed5380
--- /dev/null
+++ b/requirements-dev.txt
@@ -0,0 +1,5 @@
+-r requirements.txt
+pytest>=8,<10
+pytest-asyncio>=0.24,<2
+PyYAML>=6,<7
+playwright>=1.48,<2
diff --git a/requirements.txt b/requirements.txt
new file mode 100644
index 0000000..a1575e1
--- /dev/null
+++ b/requirements.txt
@@ -0,0 +1,4 @@
+httpx>=0.27,<1
+aiosqlite>=0.20,<1
+Jinja2>=3.1,<4
+tzdata>=2024.1