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
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# 更新日志

## 0.1.3 · 2026-11-17

- 图片发送方式新增 Base64(默认)、本地文件(NapCat 直读)和图片链接(NapCat 下载);发送失败时记录 ERROR 并回复原文字战报,不自动切换方式。
- 修复损坏图片缓存被反复使用的问题,发现无效缓存后自动重新生成;新图片不可用时回复文字战报。

## 0.1.2 · 2026-11-17

- 近期战绩新增基于 ba-dragon 模型的逐局「评分」,按分数着色,不附称号。
Expand Down
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ AstrBot 原生《断箭》(Broken Arrow)战绩查询插件。以简洁排版

## 快速开始

1. **安装插件**:在 AstrBot 插件管理中导入 `astrbot_plugin_ba_stats_v0.1.2.zip`(或将插件目录放入 `data/plugins/` 并使用 AstrBot 的 Python 环境安装 `requirements.txt`)。
1. **安装插件**:在 AstrBot 的插件页面通过仓库链接在线安装:`https://github.com/timeance/astrbot_plugin_BA_stats`。
2. **开启查询**:进入插件详情 → 可视化视图 → 设置中心,在「常用设置」中开启「启用在线查询」(默认关闭);API 地址通常保持默认即可。常用设置也可在 AstrBot 原生插件配置中调整。
3. **保存重载**:保存设置后,在 AstrBot 插件页手动重载,使在线查询设置生效。
3. **保存重载**:自定义设置中心保存后,在 AstrBot 插件页手动重载;原生插件设置保存时自动重载。
4. **绑定与查询**:
- 发送 `ba search 昵称` 搜索玩家
- 发送 `ba bind stb:玩家ID` 并按提示发送 `ba select 请求码 序号` 确认绑定
Expand Down Expand Up @@ -65,7 +65,7 @@ ba stats @群友

## 主要配置

设置中心和 AstrBot 原生插件配置共用同一份设置。诊断开关保存后即时生效;其他设置保存后,请在插件页手动重载。
自定义设置中心和 AstrBot 原生插件配置共用同一份设置。自定义设置中心保存后,诊断开关即时生效,其他设置需在插件页手动重载;原生插件设置保存时自动重载。

- **数据源接入**:在线查询开关、API 地址,无需填写客户端标识或令牌。
- **查询与命令**:默认/最大近期场数(5 / 20)、用户冷却(3 秒)、中文子命令别名开关。
Expand All @@ -74,6 +74,8 @@ ba stats @群友
- **维护与缓存**:请求间隔、并发、超时、重试及缓存容量/旧缓存回退时间,设置中心中默认折叠。
- **诊断日志**:诊断开关、日志状态和 ZIP 下载集中显示,内容默认折叠;总容量上限 30 MB,旧日志自动轮换。

图片发送方式(`output.image_send_mode`)可选「Base64(默认)」「本地文件(NapCat 直读)」「图片链接(NapCat 下载)」。Windows 同机部署可选本地文件,NapCat 必须能访问 AstrBot 的图片路径;图片链接需要渲染器提供 NapCat 可访问的 HTTP(S) 链接,返回本地文件时不可用。图片生成或发送失败会在控制台记录 `ERROR` 并回复原文字战报,不自动切换 Base64 或重试其他发送方式。

排查问题时,在设置中心选择「诊断日志」并展开,开启诊断并保存后复现问题,再点击「下载诊断日志(ZIP)」。下载由宿主登录鉴权。

## 数据与常见问题
Expand Down
16 changes: 16 additions & 0 deletions _conf_schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,22 @@
"default": true,
"hint": "调用 AstrBot 图文渲染服务生成战报图;渲染或图片发送未成功时,使用同一查询结果回复文字,不重复查询。"
},
"image_send_mode": {
"description": "图片发送方式",
"type": "string",
"default": "base64",
"options": [
"base64",
"file",
"url"
],
"labels": [
"Base64(默认)",
"本地文件(NapCat 直读)",
"图片链接(NapCat 下载)"
],
"hint": "本地文件需 NapCat 可读取图片路径;图片链接需渲染器返回可访问的 HTTP(S) 地址。发送失败记录 ERROR 并回复文字战报。"
},
"theme": {
"description": "图片主题",
"type": "string",
Expand Down
34 changes: 30 additions & 4 deletions diagnostics.py
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
"lifecycle", "command", "query", "request", "cache", "render", "send", "fallback", "quota", "export",
"plugin_start", "plugin_stop", "command_start", "command_complete", "command_error",
"query_complete", "image_cache", "image_render_start", "image_render_complete", "image_render_error",
"image_send_start", "image_send_complete", "image_send_error", "text_report",
"image_send_start", "image_send_complete", "image_send_error", "image_validated", "image_cache_invalid", "text_report",
"text_send_start", "text_send_complete", "text_send_error", "http_start", "http_response", "http_error",
})
_ACTIONS = frozenset({"help", "stats", "recent", "last", "match", "search", "bind", "binding", "unbind", "select", "cancel", "status", "quota", "cache_clear", "unknown"})
Expand All @@ -43,7 +43,8 @@
"ReadTimeout", "WriteTimeout", "PoolTimeout", "HTTPError", "HTTPStatusError", "RequestError",
"ClientError", "NotConfiguredError", "AuthenticationError", "RateLimitError", "RequestTimeoutError",
"UpstreamError", "NoDataError", "SchemaError", "IdentityMismatchError", "QueueFullError", "ClientClosedError",
"QuotaExceededError",
"QuotaExceededError", "ImageTransportError", "UnidentifiedImageError", "DecompressionBombError",
"DecompressionBombWarning", "ClientConnectorError", "ClientPayloadError", "ClientResponseError", "ServerTimeoutError",
})
_ROUTES = frozenset({"/api/players/search", "/api/analysis/player", "/api/players/matches", "/api/match"})
_IMAGE_NAME = re.compile(r"(?:[0-9a-f]{64}|report|card|image)(?:-[0-9]{1,4})?\.(?:jpg|jpeg|png|webp|gif)\Z", re.IGNORECASE)
Expand All @@ -59,6 +60,14 @@
("failed", re.compile(r"\bfail\w*\b|失败", re.IGNORECASE)),
)
_ENUMS = {
"mode": frozenset({"base64", "file", "url"}),
"stage": frozenset({"generate", "download", "validate", "cache", "send"}),
"reason": frozenset({"generation_failed", "download_failed", "validation_failed", "cache_failed", "send_failed",
"timeout", "http_status", "invalid_content_type", "invalid_image_size", "invalid_image",
"unsupported_image", "url_unavailable", "local_path_unavailable", "unsupported_mode",
"onebot_required", "invalid_target", "onebot_rejected"}),
"content_type": frozenset({"image/jpeg", "image/png", "image/gif", "image/webp", "application/octet-stream",
"text/plain", "text/html", "application/json"}),
"phase": frozenset({"start", "finish", "error", "cancel", "initialize", "terminate", "enable", "disable"}),
"command": _ACTIONS,
"action": _ACTIONS,
Expand All @@ -70,7 +79,7 @@
"image_type": frozenset({"JPEG", "JPG", "PNG", "GIF", "WEBP", "UNKNOWN", "jpeg", "jpg", "png", "gif", "webp", "unknown", "未知"}),
"scope": frozenset({"global", "user", "group"}),
}
_COUNTERS = frozenset({"count", "inflight", "requests", "cache_hits", "stale_hits", "bytes", "retry", "limit", "used", "remaining", "page", "image_bytes", "attempt", "rows"})
_COUNTERS = frozenset({"count", "inflight", "requests", "cache_hits", "stale_hits", "bytes", "retry", "limit", "used", "remaining", "page", "image_bytes", "attempt", "rows", "width", "height"})
_BOOLEANS = frozenset({"configured", "closed", "force", "cached", "stale"})


Expand All @@ -94,7 +103,7 @@ def _safe_fields(fields: dict) -> dict:
value = fields.get("status")
if type(value) is int and 100 <= value <= 599:
result["status"] = value
elif type(value) is str and value in _ERROR_CODES | {"ok", "success", "error", "failed", "fallback", "0.1.2"}:
elif type(value) is str and value in _ERROR_CODES | {"ok", "success", "error", "failed", "fallback", "0.1.2", "0.1.3"}:
result["status"] = value
value = fields.get("retcode")
if type(value) is int and -1_000_000_000 <= value <= 1_000_000_000:
Expand All @@ -121,6 +130,23 @@ def _safe_fields(fields: dict) -> dict:
return result


def image_error_metadata(exc, mode, stage):
"""Share the same allowlist between always-on console errors and diagnostics."""
result = getattr(exc, "result", None)
result = result if isinstance(result, dict) else {}
cause = exc.__cause__ or exc
defaults = {"generate": "generation_failed", "download": "download_failed", "validate": "validation_failed",
"cache": "cache_failed", "send": "send_failed"}
return _safe_fields({
"mode": mode, "stage": stage if stage == "cache" else getattr(exc, "stage", stage),
"error": type(cause).__name__, "retcode": result.get("retcode"),
"reason": getattr(exc, "reason", "timeout" if isinstance(exc, TimeoutError) else defaults.get(stage)),
"message": result.get("message") or result.get("wording"),
"status_code": getattr(exc, "status_code", None), "content_type": getattr(exc, "content_type", None),
"image_bytes": getattr(exc, "image_bytes", None),
})


class DiagnosticLog:
"""Thread-safe bounded recorder with atomic ZIP snapshots.

Expand Down
36 changes: 23 additions & 13 deletions docs/VALIDATION.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,16 @@
# 验证记录

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

## 本次结果

| 项目 | 结果 |
| --- | --- |
| 完整离线测试 | **635 passed,25.90 秒** |
| 完整离线测试 | **695 passed,33.35 秒** |
| 评分与固定上游 TypeScript 对照 | **320 个合成样本一致**;中间值误差小于 1e-12 |
| 三类战报本地渲染 | 18 组 HTML/文字、36 张 PNG;无横向溢出或外部请求 |
| 设置中心本地交互 | 深色 390px、浅色 1100px 两组通过;4 张预览 |
| 依赖兼容性 | `uv pip check`:21 个已安装包兼容 |
| 三类战报本地渲染 | 沿用 v0.1.2 的 18 组 HTML/文字、36 张 PNG;本轮未修改战报版式 |
| 设置中心本地交互 | 深色 390px、浅色 1100px 两组通过;4 张预览;新增发送方式保存检查 |
| 依赖兼容性 | `uv pip check`:30 个已安装包兼容 |
| 完整 AstrBot 服务、真实渲染服务 | 未启动;按 v4.29.4 固定源码核对 API,使用事件与桥接桩验证 |
| BATrace / QQ 实际联调 | 开发环境未调用;用户已提供候选结果和图片超时日志 |
| 远端 PR / CI | 以对应 PR 的实时结果为准;本记录不表示已合并或部署 |
Expand All @@ -31,26 +31,36 @@

- 独立视图 `views/settings/`,与原生配置共用 AstrBotConfig;常用、额度、维护、诊断分组。跟随宿主深浅主题,维护和诊断内容默认折叠。
- 按 schema 描述与白名单校验字段,API origin 与客户端复用同一 HTTPS 校验规则;不返回或接受旧客户端标识、令牌、全局额度字段。
- 保存检查磁盘配置版本,冲突返回 409 并保留页面草稿。普通设置等待手动重载,页面显示待生效项;诊断开关保存后即时应用,保存不重启业务对象或中断在途请求。
- 自定义设置中心保存检查磁盘配置版本,冲突返回 409 并保留页面草稿。普通设置等待手动重载,页面显示待生效项;诊断开关保存后即时应用,保存不重启业务对象或中断在途请求。AstrBot 原生插件设置保存时由宿主自动重载。
- API 使用 AstrBot 登录鉴权,插件额外检查用户名。未登录、已关闭、无效 JSON、非法类型/范围、保存失败及旧实例卸载有回归测试。下载不通过公开静态目录。
- 诊断仅记录允许的事件与字段:请求耗时/状态、渲染及图片发送阶段、文件类型/大小、受控错误分类等。日志上限为 `30 * 1024 * 1024` 字节,旧段自动淘汰;关闭后可下载既有日志。
- 记录器覆盖轮换、并发导出、关闭、磁盘失败及脱敏;不记录令牌、请求头、完整响应、聊天正文或图片内容。导出为 ZIP,不清空原日志。
- 本地浏览器验证保存开关、下载路由、409 草稿保留、重新读取后保留草稿、待重载提示及固定总额度。合成桥接不替代真实宿主收发;常用设置全页预览将悬浮保存栏放到文档末尾,交互测试使用原样 CSS。
- 本地浏览器验证保存开关、下载路由、409 草稿保留、重新读取后保留草稿、待重载提示及固定总额度;新增验证 Base64 默认值,以及 file/url 保存后等待重载。合成桥接不替代真实宿主收发;常用设置全页预览将悬浮保存栏放到文档末尾,交互测试使用原样 CSS。

## 图片超时的已知边界
## 图片发送与损坏缓存

用户环境为 AstrBot 4.29.4、NapCat.Core 4.18.18;其他插件能发图片。用户日志显示 OneBot `retcode=1200`、QQ `sendMsg` 确认超时。

v0.1.1 已改为等待图片发送结果,并在未获成功确认时使用同一次查询回复文字、关闭文字自动转图。v0.1.2 增加受控诊断信息,**未证明 QQ 超时根因已修复**。本地卡片可渲染不等于实际 QQ 可接收;需在用户实例打开诊断并复现后检查日志。
用户提供的诊断 ZIP 显示,玩家概览和单局图片缓存仅有 20 字节,随后发送超时。没有取得该缓存文件原始正文,因此不能断言具体错误响应内容。固定版本 AstrBot 的远程渲染下载路径未验证响应状态和图片内容,插件原先也只检查文件是否存在。

v0.1.3 共用图片下载与验证流程:检查 HTTP 状态,限制下载大小与重定向,通过 Pillow 验证并完整解码图片。缓存命中也重新验证;当前摘要的损坏图片会删除并重新生成,新产生的无效文件不会进入缓存或发送。只处理图片缓存,保留查询缓存、绑定和额度记录。

- Base64 为默认方式,使用 AstrBot 标准图片组件并等待发送结果;本地文件和链接方式直接调用 OneBot,分别传入 file URI 和实际 HTTP(S) URL,群聊和私聊均保留当前机器人 self_id。
- 链接方式每次获取新地址。渲染器只返回本地路径或平台不支持对应方式时,明确报错,不伪造链接、不自动切换方式重发。
- 生成、下载、校验或发送失败均在控制台记录 ERROR,包含方式、阶段和受控原因;诊断关闭也不会隐藏这些错误。不记录原始异常正文、签名 URL、Base64 或凭据。
- 回归覆盖 20 字节无效文件、损坏及截断图片、旧缓存重建、错误响应不落盘、三种发送方式、群聊/私聊路由及不自动切换重发。文字回退复用同一次查询并关闭自动转图。

这些结果证明离线流程与坏缓存处理通过测试,**不代表已完成真实 QQ 收发验收**。仍需在用户实例安装后验证;不能将旧日志中的所有 QQ 超时都归因为相同原因。

## 执行与证据

```powershell
& ../.venv/Scripts/python.exe -X utf8 -m pytest -q --basetemp=../tmp/pytest-v012-final --junitxml=../validation/pytest-v0.1.2.xml
# 635 passed in 25.90s
& ../.venv/Scripts/python.exe -X utf8 -m pytest -q --basetemp=../tmp/pytest-v013-portable --junitxml=../validation/pytest-v0.1.3.xml
# 695 passed in 33.35s

& ../.venv/Scripts/python.exe -X utf8 -B tools/render_previews.py --screenshots
# 18 HTML/text pairs; 36 screenshots; 0 layout/network failures
# v0.1.2 记录:18 HTML/text pairs; 36 screenshots; 0 layout/network failures
# 本轮未修改战报版式,沿用对应预览,未重复运行此命令。

& ../.venv/Scripts/python.exe -X utf8 -B tools/check_settings_view.py
# 2 local browser scenarios passed; 4 screenshots; no external requests
Expand All @@ -70,7 +80,7 @@ uv --cache-dir ../tmp/uv-cache pip check --python ../.venv/Scripts/python.exe
- AstrBot T2I:`bcc08e47274c69e5ace19bbf738b95260ce17ca7`。
- 设置中心仅参考 `anka-afk/astrbot_plugin_meme_manager` 的分组、折叠与共享配置交互,代码独立实现。

`tools/build_delivery.py --output ../delivery/v0.1.2` 生成安装 ZIP、Gemini 文案优化 ZIP 及总交付 ZIP。安装包包含原生入口、元数据、配置、模板、设置视图、标题翻译、模型和许可;不含测试环境、个人数据库、缓存、真实凭据或参考项目源码。文案包覆盖提示、配置、HTML/JS、README、CHANGELOG,保留占位符、固定文字与许可约束。各 ZIP 用 `testzip()` 校验并附 SHA-256。
本次通过 GitHub PR 交付,使用 AstrBot 仓库链接在线安装;不将安装 ZIP 或文案优化包作为交付物。仓库包含原生入口、元数据、配置、模板、设置视图、标题翻译、模型和许可,不提交测试环境、个人数据库、缓存、真实凭据或参考项目源码。

原 Logo 保持不变:

Expand Down
Loading
Loading