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