Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 35 additions & 35 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,57 +8,57 @@ AstrBot 原生《断箭》(Broken Arrow)战绩查询插件。支持玩家概

## 快速开始

1. **安装插件**:在 AstrBot 插件管理中导入 `astrbot_plugin_ba_stats_v0.1.0.zip`(或将插件目录放入 `data/plugins/` 并使用 AstrBot 的 Python 环境安装 `requirements.txt`)。
1. **安装插件**:在 AstrBot 插件管理中导入 `astrbot_plugin_ba_stats_v0.1.1.zip`(或将插件目录放入 `data/plugins/` 并使用 AstrBot 的 Python 环境安装 `requirements.txt`)。
2. **配置接入**:打开插件设置中的「数据源接入」,填入获准客户端标识(若运营方要求则填写 Bearer 令牌),开启「启用在线查询」。
3. **保存重载**:保存配置并重载插件使其生效。
4. **绑定与查询**:
- 发送 `/ba search 昵称` 搜索玩家
- 发送 `/ba bind stb:玩家ID` 并按提示发送 `/ba select 请求码 序号` 确认绑定
- 发送 `/ba me` 或 `/ba recent` 查看战报
- 发送 `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 …`;私聊通常直接发送,若宿主要求唤醒词则加在命令前。英文子命令不区分大小写,开启中文别名后也可直接使用中文指令(如 `ba 帮助`、`ba 我`、`ba 战绩`、`ba 近期`、`ba 上一场`、`ba 单局`、`ba 搜索`、`ba 绑定`、`ba 当前绑定`、`ba 解绑`、`ba 选择`、`ba 取消`、`ba 额度`)。

| 命令 | 用途 |
| --- | --- |
| `/ba help` | 查看使用帮助与示例 |
| `/ba me` | 查看自己默认绑定账号的玩家概览 |
| `/ba stats <target>` | 查看指定玩家概览 |
| `/ba recent [count]` | 查看自己近期战绩(默认 5 场,上限 20 场) |
| `/ba me recent [count]` | 与 `/ba recent [count]` 等价 |
| `/ba recent <target> --limit N` | 查看指定玩家近期最多 `N` 场战绩 |
| `/ba last [target]` | 查看自己或指定玩家最近一场可用单局战报 |
| `/ba me last` | 与 `/ba last` 等价 |
| `/ba match <match-id>` | 查看指定对局 ID 的单局战报 |
| `/ba search <query>` | 搜索玩家候选,选择后查看概览 |
| `/ba bind <target>` | 设置默认查询账号(不验证账号归属) |
| `/ba binding` | 查看当前绑定(纯本地,不耗额度) |
| `/ba unbind` | 解除当前绑定(纯本地,不耗额度) |
| `/ba select <request-code> <index>` | 确认候选编号(120 秒内有效,单次有效) |
| `/ba cancel <request-code>` | 取消当前待确认选择 |
| `/ba quota` | 查看个人、本群与全插件今日已用和剩余额度 |
| `/ba status` | 管理员查看接入配置、请求与缓存状态 |
| `/ba cache clear` | 管理员清理 API 与图片缓存(不影响绑定与额度) |
| `ba help` | 查看使用帮助与示例 |
| `ba me` | 查看自己默认绑定账号的玩家概览 |
| `ba stats <target>` | 查看指定玩家概览 |
| `ba recent [count]` | 查看自己近期战绩(默认 5 场,上限 20 场) |
| `ba me recent [count]` | 与 `ba recent [count]` 等价 |
| `ba recent <target> --limit N` | 查看指定玩家近期最多 `N` 场战绩 |
| `ba last [target]` | 查看自己或指定玩家最近一场可用单局战报 |
| `ba me last` | 与 `ba last` 等价 |
| `ba match <match-id>` | 查看指定对局 ID 的单局战报 |
| `ba search <query>` | 搜索玩家候选,选择后查看概览 |
| `ba bind <target>` | 设置默认查询账号(不验证账号归属) |
| `ba binding` | 查看当前绑定(纯本地,不耗额度) |
| `ba unbind` | 解除当前绑定(纯本地,不耗额度) |
| `ba select <request-code> <index>` | 确认候选编号(120 秒内有效,单次有效) |
| `ba cancel <request-code>` | 取消当前待确认选择 |
| `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 @群友
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 场)。
- 纯数字请加 `stb:`、`steam:` 或 `name:` 前缀(`ba recent 10` 除外,该写法专指查询自己近期 10 场)。
- `steam:SteamID64` 当前因映射尚未确认暂不可直接查询,请改用昵称搜索后选择 STB ID。

## 主要配置
Expand All @@ -68,21 +68,21 @@ AstrBot 原生《断箭》(Broken Arrow)战绩查询插件。支持玩家概
- **数据源接入**:在线查询开关、获准客户端标识、访问令牌(可选)、API 地址。
- **查询与命令**:默认/最大近期场数(5 / 20)、用户冷却(3 秒)、中文子命令别名开关。
- **每日请求额度**:每用户默认 20 次、每群默认 100 次(可在 `0–100` 间调整,`0` 表示不单独限制);**全插件每日总上限固定为 100 次不可调整**。所有额度于北京时间每天 0 点重置,按上游 HTTP 请求计数,失败与重试也计入;命中缓存及本地命令不扣额。
- **战报显示**:图片战报开关(渲染失败自动回退为同内容文字)、深浅主题(默认深色)、显示时区(默认 `Asia/Shanghai`)。
- **战报显示**:图片战报开关(渲染或发送未成功时回复同内容文字)、深浅主题(默认深色)、显示时区(默认 `Asia/Shanghai`)。
- **维护与缓存**:请求间隔、并发、超时、重试及缓存容量/旧缓存回退时间。

## 数据与常见问题

- **为什么有字段显示「暂无」?**:当数据源未提供、未收录地图/单位名称,或胜负/模式语义尚未确认时,插件会显示「暂无」或来源 ID,不以猜测数据替代。
- **为什么没查满 20 次就提示额度用完?**:额度按上游 HTTP 请求次数计算,单条战报命令可能触发多次接口请求(如未命中缓存的概览需请求搜索、分析与近期列表),个人额度跨群及私聊累计,可用 `/ba quota` 查看用量;重载或清缓存不会重置额度。
- **为什么没查满 20 次就提示额度用完?**:额度按上游 HTTP 请求次数计算,单条战报命令可能触发多次接口请求(如未命中缓存的概览需请求搜索、分析与近期列表),个人额度跨群及私聊累计,可用 `ba quota` 查看用量;重载或清缓存不会重置额度。
- **只收到文字没有图片?**:请检查「发送图片战报」是否开启及 AstrBot HTML 渲染服务是否正常。
- **同名玩家怎么区分?**:请核对候选列表中的规范 STB ID 与来源链接后再发送 `/ba select` 确认。
- **同名玩家怎么区分?**:绑定候选不超过 3 人时,核对 STB ID 与来源链接后按提示确认;超过 3 人请前往 [BATrace](https://dash.batrace.top/) 搜索,在玩家主页链接末尾取得 ID,再发送 `ba bind stb:玩家ID`。

## 开发与许可

- 运行要求:AstrBot **4.29.4 及以上**,QQ(OneBot v11);详细测试与验证记录见 [验证记录](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))。
- 致谢与参考:[BATrace](https://dash.batrace.top/)(战绩数据源)、[AlexanderHYuba-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
Expand Down
4 changes: 2 additions & 2 deletions _conf_schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@
"description": "启用中文子命令别名",
"type": "bool",
"default": true,
"hint": "如 /ba 帮助;英文主命令始终可用。"
"hint": "如 ba 帮助;群聊先 @ 机器人,英文主命令始终可用。"
}
}
},
Expand Down Expand Up @@ -90,7 +90,7 @@
"description": "发送图片战报",
"type": "bool",
"default": true,
"hint": "调用 AstrBot 图文渲染服务生成战报图;渲染失败时自动回退为同内容文字。"
"hint": "调用 AstrBot 图文渲染服务生成战报图;渲染或图片发送未成功时,使用同一查询结果回复文字,不重复查询。"
},
"theme": {
"description": "图片主题",
Expand Down
21 changes: 16 additions & 5 deletions docs/VALIDATION.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,32 @@
# 首版验证记录
# 验证记录

验证日期:2026-11-17(Asia/Hong_Kong)。版本:v0.1.0。
验证日期:2026-11-17(Asia/Hong_Kong)。版本:v0.1.1。

## v0.1.1 命令提示与发送修复

用户提供的实际群聊记录复现了 `wake_prefix=zar` 被直接拼成 `zarba` 的帮助和候选提示,同时提供了 QQ/OneBot 图片发送阶段 `retcode=1200`、`sendMsg` 确认超时日志。该日志不能单独确定 QQ 发送超时的底层原因。

- 命令正文统一为 `ba …`,唤醒信息只由平台适配层添加;群聊确认、取消和后续操作使用真实 At 组件,显示名由 QQ 解析。帮助与候选提示保留为可复制文字,不再自动转图。
- 私聊通常显示裸命令;宿主要求唤醒词时,在操作示例中单独加上唤醒词和空格。输入解析同时支持 `zar ba …`、既有符号前缀和真实 @。
- 昵称绑定按去重后的规范 ID 计数,超过 3 人时不发布可确认的绑定候选,提示去 BATrace 网站搜索并使用 `ba bind stb:玩家ID`。1–3 人和明确 ID 仍只需确认一次,既有绑定不受未确认操作影响。
- 图片通过 `await event.send(...)` 发送并等待平台返回;渲染或发送异常时,本次剩余分页改用相同数据的文字,关闭文字自动转图,不重发图片或重新查询。发送超时表述为“未获成功确认”,不宣称远端一定未送达;取消继续传播。
- 完整离线测试 **453 passed,25.95 秒**。新增测试覆盖 1/3/4/20 人、重复 ID、旧候选失效、真实 At 确认往返、私聊唤醒词、首张/中途图片发送失败及取消。
- 核对 AstrBot v4.29.4 的 `chain_result`、`use_t2i(False)`、OneBot `send` 与唤醒流程;这些测试使用事件桩和合成数据,修复后的真实 QQ 收发仍待部署验收。三类战报模板未修改,复用已有卡片渲染结果。

## 结果边界

| 项目 | 结果 |
| --- | --- |
| 首版代码与文档 | 已实现;按项目框架、插件实现两个 PR 审阅 |
| 离线业务与契约测试 | **435 passed,24.70 秒**(含文案导入及 PR 审查回归) |
| 离线业务与契约测试 | **453 passed,25.95 秒**(含 v0.1.1 回归) |
| 本地卡片渲染 | 18 组 HTML/文字、36 张 PNG;布局与外部请求检查全通过 |
| 成品目视检查 | 主代理查看 4 张代表图;渲染子代理另查看 9 张 |
| Python 语法检查 | 全部通过 |
| 两张 Logo 原样核对 | SHA-256 与交接包一致 |
| AstrBot API 兼容性研究 | 核对 v4.29.4 固定源码,插件适配器用本地桩测试 |
| 完整 AstrBot 服务启动/真实 html_render | **尚未执行** |
| BATrace 真实接口联调 | **尚未执行,缺本插件独立获准接入** |
| QQ OneBot v11 群聊与私聊 | **尚未执行,未发送真实消息** |
| BATrace 真实接口联调 | 用户已提供玩家候选结果;开发环境未执行完整真实接口联调 |
| QQ OneBot v11 群聊与私聊 | 用户提供群聊提示和图片发送超时日志;v0.1.1 修复后的实际收发待验收 |
| GitHub PR / 发布 / 部署 | 远端检查以对应 PR 为准;本记录不代表发布或部署验收 |

API 与模型 fixture、渲染预览均为合成数据。HTTP 测试使用 `httpx.MockTransport`,不调用 BATrace。`tests/test_main.py` 在测试作用域注入 AstrBot 桩并恢复,不代表真实框架启动成功。
Expand Down
54 changes: 42 additions & 12 deletions main.py
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ def extract_arguments(event, prefixes):
raw = "".join(parts).strip()
choices = sorted({str(p) for p in prefixes if p}, key=len, reverse=True)
for prefix in choices + [""]:
match = re.match(r"^" + re.escape(prefix) + r"ba(?:\s+|$)", raw, re.IGNORECASE)
match = re.match(r"^" + re.escape(prefix) + r"\s*ba(?:\s+|$)", raw, re.IGNORECASE)
if match:
return raw[match.end():], mentions
# Some adapters expose normalized text with command prefixes already removed.
Expand Down Expand Up @@ -134,7 +134,7 @@ async def _status(self):
"schema": "响应结构变化", "identity_mismatch": "身份校验失败",
"no_data": "暂无收录", "upstream": "上游暂不可用", "queue_full": "队列已满",
"not_configured": "接入未配置", "closed": "客户端已关闭", "daily_quota": "每日额度已用完"}
return (f"断箭战报 v0.1.0\n接入配置:{'已填写(不代表联调通过)' if status['configured'] else '未配置'}\n"
return (f"断箭战报 v0.1.1\n接入配置:{'已填写(不代表联调通过)' if status['configured'] else '未配置'}\n"
f"今日总请求:{usage['global']}/{GLOBAL_DAILY_LIMIT}(固定上限);北京时间 0 点重置\n"
f"本次运行请求:{status['requests']};进行中:{status['inflight']}\n"
f"API 缓存:{await self.storage.cache_count()} 条;命中:{status['cache_hits']};旧缓存:{status['stale_hits']}\n"
Expand All @@ -157,20 +157,35 @@ def line(label, used, limit):
"按实际发出的上游 HTTP 请求计数(含重试与失败);命中缓存、本地命令及图片渲染不计入。"])
return "\n".join(lines)

def _response_result(self, event, response, config):
parts = [Plain(response.text)] if response.text else []
private_prefix = ""
if not event.get_group_id() and config.get("platform_settings", {}).get("friend_message_needs_wake_prefix", False):
prefixes = config.get("wake_prefix", [])
private_prefix = str(prefixes[0]) if prefixes else ""
for label, command in response.instructions:
parts.append(Plain("\n" + label))
if event.get_group_id():
# QQ resolves this real mention to the bot's current group card/name.
parts.extend([At(qq=event.get_self_id()), Plain(" " + command)])
else:
parts.append(Plain((private_prefix + " " if private_prefix else "") + command))
# Instructions must remain copyable, and At components must stay interactive.
return event.chain_result(parts).use_t2i(False)

@filter.command("ba", alias={"BA", "Ba", "bA"})
async def ba(self, event: AstrMessageEvent):
if self._closed:
return
event.stop_event()
config = self.context.get_config(event.unified_msg_origin)
prefixes = config.get("wake_prefix", ["/"]) if config is not None else ["/"]
prefix = str(prefixes[0]) if prefixes else ""
config = self.context.get_config(event.unified_msg_origin) or {}
prefixes = config.get("wake_prefix", ["/"])
try:
text, mentions = extract_arguments(event, prefixes)
request = parse_command(text, mentions, self.settings.default_limit,
self.settings.max_limit, self.settings.chinese_aliases)
caller = Caller(str(event.get_platform_id()), event.unified_msg_origin,
str(event.get_sender_id()), prefix + "ba")
str(event.get_sender_id()))
if request.action == "quota":
yield event.plain_result(await self._quota(quota_actor(event)))
return
Expand All @@ -191,18 +206,33 @@ async def ba(self, event: AstrMessageEvent):
with self.client.request_scope(quota_actor(event)):
response = await self._run(self.service.execute(request, caller))
if response.text:
yield event.plain_result(response.text)
yield self._response_result(event, response, config)
if response.view is not None:
send_images = self.settings.image_enabled
for view in self.renderer.views(response.view):
if self.settings.image_enabled:
send_uncertain = False
if send_images:
try:
path = await self._run(self._image(view, event.unified_msg_origin))
except (Exception,):
except Exception:
self.logger.warning("断箭战报图片渲染失败,已使用相同查询结果回复文字。")
else:
yield event.image_result(path)
continue
yield event.plain_result(self.renderer.text(view))
try:
# Await the transport here: errors from yielded results
# are otherwise swallowed later by AstrBot's pipeline.
await self._run(event.send(event.image_result(path)))
except Exception as exc:
self.logger.warning("断箭战报图片发送未获成功确认(%s),改发文字。", type(exc).__name__)
send_uncertain = True
else:
continue
send_images = False
text = self.renderer.text(view)
if send_uncertain:
text = "图片发送未获成功确认,以下为文字战报:\n" + text
# Prevent the host's global T2I setting from turning fallback
# text into another image sent through the same failing path.
yield event.plain_result(text).use_t2i(False)
except (ClientError, ValueError) as exc:
yield event.plain_result(str(exc))
except asyncio.TimeoutError:
Expand Down
2 changes: 1 addition & 1 deletion metadata.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ name: astrbot_plugin_ba_stats
display_name: 断箭战报
short_desc: "《断箭》玩家战绩查询,支持账号绑定与图片战报。"
desc: "查询《断箭》(Broken Arrow)玩家概览、近期战绩和单局战报,支持账号绑定、群友查询及图片或文字展示。使用前需配置 BATrace 接入。"
version: "0.1.0"
version: "0.1.1"
author: timeance
repo: https://github.com/timeance/astrbot_plugin_BA_stats
astrbot_version: ">=4.29.4"
Expand Down
Loading
Loading