overwatch_bot/docs/archive-2026-09-29.md

对话归档：OWCX 插件评估、重构与 v2.3.0 更新

• 归档日期：2026-09-29
• 仓库：https://github.com/TZYCeng/astrbot_plugin_owcx.git
• 分支：main
• 版本跨度：v2.1.0 → v2.2.0 → v2.3.0

初评发现

• main.py 约 1904 行，常量、工具与绑定逻辑混杂。
• 图片与头像下载为每次请求单独创建 aiohttp session；临时图片没有清理。
• API 请求缺少缓存与 429/503 重试，默认超时 30 秒。
• 玩家 ID 缺少校验及 URL 编码；重复定义竞技图标；日志实现不统一。
• 图片开关默认值与配置 schema 不一致；README 仓库地址有误，存在重复 logo 文件。

v2.2.0：重构与健壮性（9f3deca）

• 将映射拆至 constants.py，纯逻辑拆至 utils.py，绑定存储与迁移拆至 bindings.py；main.py 缩减至约 700 行，并保留旧导入路径兼容。
• API 超时改为 15 秒；增加进程级 GET 缓存（玩家 120 秒、榜单 600 秒、英雄 3600 秒）及 429/503 的 retry_after 重试（最多 2 次）；对 URL 参数进行 quote。
• 图片/头像下载复用 session，并限制同时下载数为 6。
• 新增旧临时图片清理逻辑及英雄统计卡片渲染；补充玩家 ID 校验；统一使用 AstrBot logger。
• 图片渲染默认值与 schema 统一为开启；修正 README 仓库地址并删除重复 logo 文件。

v2.3.0：新段位与 API 地址配置化（c1c813e）

依据用户提供的 OverFast API 4.13.0 openapi.json：

• 段位枚举新增 emerald（翡翠）及 ultimate（王者）。
• champion 保留兼容旧数据并显示为王者；top500 保留。
• 54 个 HeroKey 与现有英雄映射一致，无需改动。
• _conf_schema.json 增加 api_base_url，默认 https://overfast-api.tekrop.fr，可填自建 OverFast 服务地址。
• normalize_api_base_url() 去除首尾空白和尾斜杠；空值或非 HTTP(S) 地址回退官方地址。
• 全部 API 客户端由插件的 _api_client() 按配置地址创建，启动日志显示当前 API 地址。
• metadata.yaml 版本更新至 v2.3.0。

历史提交

提交	日期	内容
9f3deca	2026-09-29	v2.2.0 结构重构、缓存重试、下载复用与健壮性修正
c1c813e	2026-09-29	v2.3.0 新段位与 API 地址配置化
fa5d65e	2026-09-29	开发辅助文件与渲染检查（本次已移除相关文件）

后续关注

• 在真实 AstrBot 环境验证 /owsummary、/owstats、/owcareer、/owherostats 及绑定指令。
• 使用真实翡翠/王者账号确认文字与卡片显示。
• 配置自建 OverFast 服务地址后确认请求走向；上游尚未支持 ultimate 榜单筛选时不传该筛选值。
• 如上游公布不同正式中文译名，可再调整 champion 对应显示。
• 核对新增英雄中文名是否与官方最新译名完全一致。

关键文件

文件	说明
main.py	OverwatchStatsPlugin 主类与指令入口
api_client.py	OverFastAPIClient / OverFastAPIError、缓存、重试与基础 URL
constants.py	段位、角色、模式、平台、地区与英雄映射
utils.py	纯逻辑及 API 地址归一化
bindings.py	KV 绑定存储与旧数据迁移
image_renderer.py	卡片渲染与临时图片清理
_conf_schema.json	插件配置 schema
CHANGELOG.md	版本变更记录