diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c6a04a0..caa95fb 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -49,3 +49,7 @@ jobs:
PY
- name: Check Python syntax
run: python -m compileall -q .
+ - name: Run offline tests
+ run: python -m pytest -q
+ - name: Build and verify delivery archives
+ run: python tools/build_delivery.py --output dist
diff --git a/_conf_schema.json b/_conf_schema.json
new file mode 100644
index 0000000..dbf4eca
--- /dev/null
+++ b/_conf_schema.json
@@ -0,0 +1,165 @@
+{
+ "access": {
+ "type": "object",
+ "description": "数据源接入",
+ "items": {
+ "enabled": {
+ "description": "启用在线查询",
+ "type": "bool",
+ "default": false,
+ "hint": "请先取得 BATrace 对本插件的独立接入许可,填写获准客户端标识后再开启。",
+ "obvious_hint": true
+ },
+ "client_id": {
+ "description": "获准客户端标识",
+ "type": "string",
+ "default": "",
+ "hint": "由 BATrace 运营方为本插件单独分配,请勿借用其他项目的标识。",
+ "secret": true
+ },
+ "api_token": {
+ "description": "访问令牌(如需要)",
+ "type": "string",
+ "default": "",
+ "hint": "仅在运营方要求 Bearer 令牌时填写。",
+ "secret": true
+ },
+ "base_url": {
+ "description": "API 地址",
+ "type": "string",
+ "default": "https://bot.batrace.top",
+ "hint": "以运营方确认的 HTTPS 地址为准。"
+ }
+ }
+ },
+ "query": {
+ "type": "object",
+ "description": "查询与命令",
+ "items": {
+ "default_limit": {
+ "description": "默认近期场数",
+ "type": "int",
+ "default": 5,
+ "hint": "范围 1 到「最大近期场数」之间。"
+ },
+ "max_limit": {
+ "description": "最大近期场数",
+ "type": "int",
+ "default": 20,
+ "hint": "上限 20;仅展示当前接口返回的样本,不代表玩家完整生涯历史。"
+ },
+ "cooldown_seconds": {
+ "description": "同一用户查询间隔(秒)",
+ "type": "float",
+ "default": 3.0,
+ "hint": "限制查询命令的触发间隔,命中缓存也适用;帮助、查看绑定、解绑、额度查看及候选确认不受此冷却限制。"
+ },
+ "chinese_aliases": {
+ "description": "启用中文子命令别名",
+ "type": "bool",
+ "default": true,
+ "hint": "如 /ba 帮助;英文主命令始终可用。"
+ }
+ }
+ },
+ "limits": {
+ "type": "object",
+ "description": "每日请求额度",
+ "hint": "全插件每天最多 100 次上游请求,此总上限固定不可修改。所有额度北京时间每天 0 点重置;保存后重载插件生效,不清零已用次数。",
+ "items": {
+ "user_daily_limit": {
+ "description": "每用户每日请求额度",
+ "type": "int",
+ "default": 20,
+ "hint": "0–100;0 表示不单独限制,仍受全插件每日 100 次上限约束。同一平台用户跨群及私聊累计;按实际上游 HTTP 请求计数,重试及失败计入,命中缓存不计入。",
+ "obvious_hint": true
+ },
+ "group_daily_limit": {
+ "description": "每群每日请求额度",
+ "type": "int",
+ "default": 100,
+ "hint": "0–100;0 表示不单独限制,仍受全插件每日 100 次上限约束。群内所有用户共用,私聊不扣群额度。管理员查询同样计入。"
+ }
+ }
+ },
+ "output": {
+ "type": "object",
+ "description": "战报显示",
+ "items": {
+ "image_enabled": {
+ "description": "发送图片战报",
+ "type": "bool",
+ "default": true,
+ "hint": "调用 AstrBot 图文渲染服务生成战报图;渲染失败时自动回退为同内容文字。"
+ },
+ "theme": {
+ "description": "图片主题",
+ "type": "string",
+ "default": "dark",
+ "options": [
+ "dark",
+ "light"
+ ],
+ "labels": [
+ "深色",
+ "浅色"
+ ]
+ },
+ "timezone": {
+ "description": "显示时区",
+ "type": "string",
+ "default": "Asia/Shanghai",
+ "hint": "IANA 时区名,例如 Asia/Shanghai 或 Asia/Hong_Kong。仅改变战报显示,额度仍固定按北京时间 0 点重置。"
+ }
+ }
+ },
+ "maintenance": {
+ "type": "object",
+ "description": "维护与请求限制",
+ "items": {
+ "request_interval": {
+ "description": "上游请求最小间隔(秒)",
+ "type": "float",
+ "default": 1.0,
+ "hint": "根据获准接入频率调整,对所有在线查询全局生效。"
+ },
+ "concurrency": {
+ "description": "上游并发上限",
+ "type": "int",
+ "default": 2
+ },
+ "queue_size": {
+ "description": "待处理请求上限",
+ "type": "int",
+ "default": 20
+ },
+ "request_timeout": {
+ "description": "单次请求超时(秒)",
+ "type": "float",
+ "default": 20.0
+ },
+ "wait_timeout": {
+ "description": "总等待上限(秒)",
+ "type": "float",
+ "default": 45.0
+ },
+ "retries": {
+ "description": "临时故障重试次数",
+ "type": "int",
+ "default": 1,
+ "hint": "范围 0–2 次;鉴权失败、人机验证及数据结构错误不会重试。"
+ },
+ "cache_max_entries": {
+ "description": "API 缓存容量(条)",
+ "type": "int",
+ "default": 1000
+ },
+ "stale_hours": {
+ "description": "故障时旧缓存最长保留(小时)",
+ "type": "float",
+ "default": 24.0,
+ "hint": "0 表示禁用旧缓存回退;使用旧缓存时战报会明确标明抓取时间。"
+ }
+ }
+ }
+}
diff --git a/client.py b/client.py
new file mode 100644
index 0000000..ae57f40
--- /dev/null
+++ b/client.py
@@ -0,0 +1,546 @@
+"""Independent BATrace adapter with bounded scheduling and persistent caching.
+
+Creating a client never probes the source. All network methods require explicit
+access enablement and this plugin's own operator-approved client identity.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+import hashlib
+import json
+import math
+import time
+from typing import Any, Awaitable, Callable, Protocol, TypeVar
+from urllib.parse import urlsplit
+
+import httpx
+
+if __package__:
+ from .quota import AdmissionDeferred, GLOBAL_DAILY_LIMIT, QuotaActor, QuotaExceededError, quota_day
+ from .models import (
+ FetchResult, Match, Participant, Player, canonical_id, parse_match, parse_player,
+ parse_recent, parse_search, utc_datetime,
+ )
+else: # Direct module imports for framework-independent tests.
+ from quota import AdmissionDeferred, GLOBAL_DAILY_LIMIT, QuotaActor, QuotaExceededError, quota_day
+ from models import (
+ FetchResult, Match, Participant, Player, canonical_id, parse_match, parse_player,
+ parse_recent, parse_search, utc_datetime,
+ )
+
+T = TypeVar("T")
+
+
+class CacheStorage(Protocol):
+ async def get_cache(self, key: str) -> tuple[Any, Any, Any] | None: ...
+ async def put_cache(self, key: str, payload: Any, ttl: float) -> None: ...
+ async def clear_cache(self) -> None: ...
+ async def prune_cache(self, max_entries: int = 1000, max_age_seconds: float = 604800) -> Any: ...
+ async def cache_count(self) -> int: ...
+ async def consume_request(self, actor: QuotaActor | None = None, *, user_limit: int = 20,
+ group_limit: int = 100, ready: Callable[[], bool] | None = None) -> dict: ...
+ async def quota_usage(self, actor: QuotaActor | None = None) -> dict: ...
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+ enabled: bool = False
+ base_url: str = "https://bot.batrace.top"
+ client_id: str = ""
+ api_token: str = field(default="", repr=False)
+ request_interval: float = 1.0
+ concurrency: int = 2
+ queue_size: int = 20
+ request_timeout: float = 20.0
+ wait_timeout: float = 45.0
+ retries: int = 1
+ cache_max_entries: int = 1000
+ stale_hours: float = 24.0
+ user_daily_limit: int = 20
+ group_daily_limit: int = 100
+
+
+class ClientError(Exception):
+ code = "client_error"
+
+
+class NotConfiguredError(ClientError):
+ code = "not_configured"
+
+
+class AuthenticationError(ClientError):
+ code = "authentication"
+
+
+class RateLimitError(ClientError):
+ code = "rate_limited"
+
+ def __init__(self, message: str = "数据源请求受限,请稍后重试。", *, retry_after: float | None = None):
+ super().__init__(message)
+ self.retry_after = retry_after
+
+
+class RequestTimeoutError(ClientError):
+ code = "timeout"
+
+
+class UpstreamError(ClientError):
+ code = "upstream"
+
+
+class NoDataError(ClientError):
+ code = "no_data"
+
+
+class SchemaError(ClientError):
+ code = "schema"
+
+
+class IdentityMismatchError(ClientError):
+ code = "identity_mismatch"
+
+
+def participant_for(match: Match, player_id: str) -> Participant | None:
+ """Empty rosters are unknown; a nonempty roster must contain the target."""
+ person = next((p for p in match.players if p.player_id == player_id), None)
+ if match.players and person is None:
+ raise IdentityMismatchError("数据源返回了目标玩家未参与的对局,已中止本次查询。")
+ return person
+
+
+class QueueFullError(ClientError):
+ code = "queue_full"
+
+
+class ClientClosedError(ClientError):
+ code = "closed"
+
+
+@dataclass
+class _Flight:
+ task: asyncio.Task
+ waiters: int = 0
+ force: bool = False
+
+
+class BatraceClient:
+ """One shared instance per plugin; injected HTTP client remains caller-owned.
+
+ search(query), player(id), recent(id, limit), match(id) return FetchResult.
+ ``force=True`` bypasses fresh cache but keeps the same admission/rate limits.
+ close() cancels and awaits owned jobs; it closes only an internally-created
+ AsyncClient. The caller closes an injected AsyncClient and Storage itself.
+ """
+
+ def __init__(
+ self, config: ClientConfig | None = None, *,
+ storage: CacheStorage | None = None, http_client: httpx.AsyncClient | None = None,
+ ):
+ self.config = config or ClientConfig()
+ c = self.config
+ if any(not math.isfinite(x) or x < 0 for x in (c.request_interval, c.stale_hours)):
+ raise ValueError("interval and stale age must be finite and nonnegative")
+ if any(not math.isfinite(x) or x <= 0 for x in (c.request_timeout, c.wait_timeout)):
+ raise ValueError("timeouts must be finite and positive")
+ if any(isinstance(x, bool) or not isinstance(x, int) for x in (
+ c.concurrency, c.queue_size, c.retries, c.cache_max_entries,
+ )) or not (1 <= c.concurrency <= 8 and 0 <= c.queue_size <= 1000
+ and 0 <= c.retries <= 2 and c.cache_max_entries > 0):
+ raise ValueError("invalid scheduler/cache bounds")
+ if any(type(x) is not int or not 0 <= x <= GLOBAL_DAILY_LIMIT
+ for x in (c.user_daily_limit, c.group_daily_limit)):
+ raise ValueError("user and group daily limits must be integers between 0 and 100")
+ self._storage = storage
+ self._http = http_client
+ self._owns_http = http_client is None
+ self._closed = False
+ self._slots = asyncio.Semaphore(c.concurrency)
+ self._start_lock = asyncio.Lock()
+ self._cache_lock = asyncio.Lock()
+ self._last_start: float | None = None
+ self._not_before = 0.0
+ self._flights: dict[tuple[str, QuotaActor | None], _Flight] = {}
+ self._actor: ContextVar[QuotaActor | None] = ContextVar("ba_stats_actor", default=None)
+ # Standalone adapter tests may omit Storage. The plugin always supplies
+ # SQLite; identified requests require it so user/group limits persist.
+ self._local_quota_day = ""
+ self._local_quota_used = 0
+ self._generation = 0
+ self._requests = 0
+ self._cache_hits = 0
+ self._stale_hits = 0
+ self._last_error: str | None = None
+ # Includes origin AND identity, so a different deployment/credential can
+ # never accidentally read another source's cached identity response.
+ source = json.dumps([c.base_url.rstrip("/"), c.client_id, c.api_token])
+ self._namespace = "batrace:v1:" + hashlib.sha256(source.encode()).hexdigest()[:24]
+
+ @property
+ def namespace(self) -> str:
+ """Stable binding identity: credential rotation must not change it."""
+ origin = self.config.base_url.rstrip("/")
+ return "batrace:" + hashlib.sha256(origin.encode()).hexdigest()[:16]
+
+ @property
+ def configured(self) -> bool:
+ c = self.config
+ if not c.enabled or not c.client_id.strip() or "ba-dragon" in c.client_id.casefold():
+ return False
+ if any(ch in c.client_id + c.api_token for ch in "\r\n"):
+ return False
+ try:
+ u = urlsplit(c.base_url)
+ _ = u.port
+ return bool(u.scheme == "https" and u.hostname and not u.username and not u.password
+ and not u.query and not u.fragment and u.path in {"", "/"})
+ except ValueError:
+ return False
+
+ def _check_ready(self) -> None:
+ if self._closed:
+ raise ClientClosedError("数据源客户端已关闭,请稍后重试。")
+ if not self.configured:
+ raise NotConfiguredError("数据源接入未配置:需开启在线查询并填写本插件独立的获准客户端标识。")
+
+ def status(self) -> dict[str, Any]:
+ """Safe admin diagnostics: never return token, header, query or URL."""
+ return {
+ "configured": self.configured, "closed": self._closed,
+ "inflight": len(self._flights), "requests": self._requests,
+ "cache_hits": self._cache_hits, "stale_hits": self._stale_hits,
+ "last_error": self._last_error,
+ }
+
+ @contextmanager
+ def request_scope(self, actor: QuotaActor):
+ """Carry the trusted event identity into all child requests/retries."""
+ if self._storage is None:
+ raise RuntimeError("用户与群额度需要持久化存储。")
+ token = self._actor.set(actor)
+ try:
+ yield
+ finally:
+ self._actor.reset(token)
+
+ def _local_usage(self) -> int:
+ day = quota_day(time.time())
+ if self._local_quota_day != day:
+ self._local_quota_day, self._local_quota_used = day, 0
+ return self._local_quota_used
+
+ async def _check_daily_quota(self) -> None:
+ """Read-only preflight; reservation at send time remains authoritative."""
+ usage = (await self._storage.quota_usage(self._actor.get()) if self._storage is not None
+ else {"global": self._local_usage(), "user": None, "group": None})
+ for scope, limit in (("global", GLOBAL_DAILY_LIMIT), ("user", self.config.user_daily_limit),
+ ("group", self.config.group_daily_limit)):
+ if usage[scope] is not None and limit and usage[scope] >= limit:
+ raise QuotaExceededError(scope, limit, usage[scope])
+
+ async def _consume_request(self) -> None:
+ if self._storage is not None:
+ await self._storage.consume_request(
+ self._actor.get(), user_limit=self.config.user_daily_limit,
+ group_limit=self.config.group_daily_limit,
+ ready=self._send_ready,
+ )
+ return
+ if self._local_usage() >= GLOBAL_DAILY_LIMIT:
+ raise QuotaExceededError("global", GLOBAL_DAILY_LIMIT, self._local_quota_used)
+ self._local_quota_used += 1
+
+ async def search(self, query: str, *, force: bool = False) -> FetchResult[list[Player]]:
+ if not isinstance(query, str) or not query.strip() or len(query) > 200:
+ raise ValueError("query must contain 1–200 characters")
+ async def load() -> Any:
+ return await self._request("/api/players/search", {"q": query, "limit": 20})
+ return await self._get("search", [query, 20], load, parse_search, 600, force)
+
+ async def player(self, id: str, *, force: bool = False) -> FetchResult[Player]:
+ pid = canonical_id(id)
+ async def load() -> Any:
+ search = await self._request("/api/players/search", {"q": pid, "limit": 20})
+ try:
+ candidates = parse_search(search)
+ except (ValueError, TypeError, OverflowError) as exc:
+ raise SchemaError("玩家搜索返回的数据结构发生变化,暂无法解析。") from exc
+ if not any(p.id == pid for p in candidates):
+ raise IdentityMismatchError("数据源未返回对应的规范玩家 ID,无法核实身份。")
+ analysis = await self._request("/api/analysis/player", {"stbid": pid})
+ return {"search": search, "analysis": analysis}
+ return await self._get("player", [pid], load, lambda p: parse_player(p, pid), 900, force)
+
+ async def recent(self, id: str, limit: int = 5, *, force: bool = False) -> FetchResult[list[Match]]:
+ pid = canonical_id(id)
+ if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= 20:
+ raise ValueError("recent limit must be between 1 and 20")
+ async def load() -> Any:
+ return await self._request("/api/players/matches", {"stbid": pid, "limit": limit})
+ def decode(raw: Any) -> list[Match]:
+ matches = parse_recent(raw)
+ for match in matches:
+ participant_for(match, pid)
+ return matches[:limit]
+ return await self._get("recent", [pid, limit], load, decode, 600, force)
+
+ async def match(self, id: str, *, force: bool = False) -> FetchResult[Match]:
+ mid = canonical_id(id)
+ async def load() -> Any:
+ return await self._request("/api/match", {"matchid": mid})
+ return await self._get("match", [mid], load, lambda p: parse_match(p, mid), 86400, force)
+
+ async def _get(
+ self, operation: str, parameters: list[Any], loader: Callable[[], Awaitable[Any]],
+ decoder: Callable[[Any], T], ttl: float, force: bool,
+ ) -> FetchResult[T]:
+ self._check_ready()
+ digest = hashlib.sha256(json.dumps(parameters, ensure_ascii=False).encode()).hexdigest()
+ key = f"{self._namespace}:{operation}:{digest}"
+ # Keep cache shared, but only coalesce network jobs for the same sender
+ # and group. Another caller must not spend or bypass the owner's quota.
+ flight_key = (key, self._actor.get())
+ # force joins an already running refresh; no duplicate bypass lane.
+ flight = self._flights.get(flight_key)
+ if flight is not None and flight.task.done():
+ self._flights.pop(flight_key, None)
+ flight = None
+ if flight is None:
+ if len(self._flights) >= self.config.concurrency + self.config.queue_size:
+ self._last_error = QueueFullError.code
+ raise QueueFullError("当前请求排队已满,请稍后重试。")
+ task = asyncio.create_task(self._load(key, loader, decoder, ttl, lambda: flight.force))
+ flight = _Flight(task, force=force)
+ self._flights[flight_key] = flight
+ def finished(t: asyncio.Task) -> None:
+ if self._flights.get(flight_key) is flight:
+ self._flights.pop(flight_key, None)
+ if not t.cancelled():
+ t.exception() # retrieve errors even if every waiter was cancelled
+ task.add_done_callback(finished)
+ elif force:
+ # A bind revalidation joining a cache lookup must promote the shared
+ # job before it decides whether a fresh cache hit is acceptable.
+ flight.force = True
+ flight.waiters += 1
+ try:
+ return await asyncio.shield(flight.task)
+ except asyncio.CancelledError:
+ if self._closed:
+ raise ClientClosedError("数据源客户端已关闭,请稍后重试。") from None
+ raise
+ finally:
+ flight.waiters -= 1
+ if not flight.waiters and not flight.task.done():
+ flight.task.cancel()
+ await asyncio.gather(flight.task, return_exceptions=True)
+
+ @staticmethod
+ def _decode(decoder: Callable[[Any], T], payload: Any) -> T:
+ try:
+ return decoder(payload)
+ except ClientError:
+ raise
+ except (ValueError, TypeError, OverflowError, OSError, KeyError) as exc:
+ raise SchemaError("数据源返回的数据结构发生变化,暂无法解析。") from exc
+
+ async def _load(
+ self, key: str, loader: Callable[[], Awaitable[Any]], decoder: Callable[[Any], T],
+ ttl: float, force: Callable[[], bool],
+ ) -> FetchResult[T]:
+ cached: tuple[T, datetime, datetime] | None = None
+ generation = self._generation
+ try:
+ async with asyncio.timeout(self.config.wait_timeout):
+ if self._storage is not None:
+ hit = await self._storage.get_cache(key)
+ if hit is not None:
+ try:
+ payload, fetched, expires = hit
+ fetched, expires = utc_datetime(fetched), utc_datetime(expires)
+ if fetched is None or expires is None or fetched > expires:
+ raise ValueError("invalid cache timestamps")
+ cached = (self._decode(decoder, payload), fetched, expires)
+ except (ClientError, ValueError, TypeError, OverflowError, OSError):
+ cached = None # old/incompatible cache must be refetched
+ now = datetime.now(timezone.utc)
+ if cached and not force() and cached[2] > now and cached[1] <= now:
+ self._cache_hits += 1
+ return self._result(cached[0], cached[1])
+ await self._check_daily_quota()
+ async with self._slots:
+ self._check_ready()
+ raw = await loader()
+ data = self._decode(decoder, raw)
+ fetched_at = datetime.now(timezone.utc)
+ if isinstance(data, Match):
+ # A structural complete flag is insufficient for a just-ended
+ # match: keep it short until at least five minutes after end.
+ end = None
+ if data.started_at is not None and data.duration_seconds is not None:
+ end = data.started_at.timestamp() + data.duration_seconds
+ if not data.complete or end is None or time.time() - end < 300:
+ ttl = 60
+ if self._storage is not None:
+ async with self._cache_lock:
+ if generation == self._generation:
+ await self._storage.put_cache(key, raw, ttl)
+ # Enforce the configured bound at every insertion;
+ # rely on Storage's constructor bound as well.
+ await self._storage.prune_cache(
+ max_entries=self.config.cache_max_entries, max_age_seconds=604800,
+ )
+ self._last_error = None
+ return self._result(data, fetched_at)
+ except TimeoutError:
+ error: ClientError = RequestTimeoutError("本次查询超过总等待时间,请稍后重试。")
+ except (ClientError, QuotaExceededError) as exc:
+ error = exc
+ self._last_error = error.code
+ # No fallback for identity, authorization, not-found or schema failures.
+ if isinstance(error, (RequestTimeoutError, UpstreamError, RateLimitError)) and cached:
+ # Quota can become exhausted while this job waits/backoffs. Do not
+ # disguise that local limit as a temporary-source stale fallback.
+ try:
+ await self._check_daily_quota()
+ except QuotaExceededError as quota_error:
+ self._last_error = quota_error.code
+ raise
+ age = (datetime.now(timezone.utc) - cached[1]).total_seconds()
+ if 0 <= age <= self.config.stale_hours * 3600:
+ self._stale_hits += 1
+ return self._result(cached[0], cached[1], stale=True, reason=error.code)
+ raise error
+
+ @staticmethod
+ def _result(data: T, fetched_at: datetime, *, stale: bool = False, reason: str | None = None) -> FetchResult[T]:
+ records = data if isinstance(data, list) else [data]
+ times = [x.updated_at for x in records if getattr(x, "updated_at", None) is not None]
+ return FetchResult(data, fetched_at, stale, max(times) if times else None, reason)
+
+ def _send_ready(self) -> bool:
+ self._check_ready()
+ now = time.monotonic()
+ return now >= self._not_before and (self._last_start is None
+ or now >= self._last_start + self.config.request_interval)
+
+ async def _pace(self) -> None:
+ """Wait at the send gate; the caller holds _start_lock until dispatch."""
+ while True:
+ now = time.monotonic()
+ at = max(self._not_before, (self._last_start + self.config.request_interval)
+ if self._last_start is not None else now)
+ if at <= now:
+ break
+ await asyncio.sleep(at - now)
+ self._check_ready()
+
+ @staticmethod
+ def _retry_after(value: str | None) -> float | None:
+ if value is None:
+ return None
+ try:
+ seconds = float(value)
+ except ValueError:
+ try:
+ stamp = parsedate_to_datetime(value)
+ if stamp.tzinfo is None:
+ return None
+ seconds = stamp.timestamp() - time.time()
+ except (ValueError, TypeError, OverflowError):
+ return None
+ return max(0.0, seconds) if math.isfinite(seconds) else None
+
+ async def _request(self, path: str, params: dict[str, Any]) -> Any:
+ if self._http is None:
+ self._http = httpx.AsyncClient()
+ c = self.config
+ headers = {"Accept": "application/json", "User-Agent": "astrbot-plugin-ba-stats", "X-Client": c.client_id}
+ if c.api_token:
+ # Optional Bearer scheme is a deployment choice, NOT a verified
+ # BATrace requirement; configure only if operator-approved.
+ headers["Authorization"] = "Bearer " + c.api_token
+ for attempt in range(c.retries + 1):
+ await self._check_daily_quota()
+ async with self._start_lock:
+ while True:
+ await self._pace()
+ try:
+ await self._consume_request()
+ except AdmissionDeferred:
+ # Quota rolled back before commit: wait without holding
+ # SQLite and reserve against the final admission date.
+ continue
+ break
+ self._last_start = time.monotonic()
+ self._requests += 1
+ # No suspension between releasing the gate and handing off to HTTP;
+ # only request starts are serialized, never response processing.
+ delay = 30.0
+ try:
+ response = await self._http.get(
+ c.base_url.rstrip("/") + path, params=params, headers=headers,
+ timeout=c.request_timeout, follow_redirects=False,
+ )
+ except httpx.TimeoutException:
+ error: ClientError = RequestTimeoutError("连接或读取数据源超时,请稍后重试。")
+ except httpx.RequestError:
+ error = UpstreamError("暂时无法连接到数据源,请稍后重试。")
+ else:
+ status = response.status_code
+ if status in {401, 403}:
+ raise AuthenticationError("数据源鉴权失败或拒绝访问,请管理员检查客户端标识与令牌配置。")
+ content_type = response.headers.get("content-type", "").split(";")[0].lower()
+ is_json = content_type == "application/json" or content_type.endswith("+json")
+ if not is_json and any(mark in response.text for mark in (
+ "TencentEOCaptchaWidget", "EO-Bot-Captcha-Token", "Security Verification", "__tst_status",
+ )):
+ raise AuthenticationError("数据源触发了人机验证,当前接入暂不可用,请管理员联系运营方核实。")
+ if status == 429:
+ delay = self._retry_after(response.headers.get("Retry-After"))
+ delay = delay if delay is not None else 30.0
+ error = RateLimitError(retry_after=delay)
+ self._not_before = max(self._not_before, time.monotonic() + delay)
+ if delay >= c.wait_timeout:
+ raise error
+ elif status >= 500:
+ error = UpstreamError(f"""数据源服务暂时异常(HTTP {status}),请稍后重试。""")
+ else:
+ if not is_json:
+ raise SchemaError("数据源返回了非 JSON 格式的响应,暂无法解析。")
+ try:
+ payload = response.json()
+ except ValueError as exc:
+ raise SchemaError("数据源返回的 JSON 内容无效,暂无法解析。") from exc
+ if status == 404:
+ raise NoDataError("数据源暂未收录该记录,无法据此判断账号是否存在。")
+ if not 200 <= status < 300:
+ raise ClientError(f"""数据源拒绝了本次请求(HTTP {status})。""")
+ return payload
+ if attempt >= c.retries:
+ raise error
+ # Backoff belongs to the same bounded job/deadline and rate gate.
+ self._not_before = max(self._not_before, time.monotonic() + delay)
+ raise UpstreamError("数据源请求失败") # unreachable, keeps type checkers precise
+
+ async def clear_cache(self) -> None:
+ async with self._cache_lock:
+ self._generation += 1 # an older in-flight result must not refill cleared cache
+ if self._storage is not None:
+ await self._storage.clear_cache()
+
+ async def close(self) -> None:
+ self._closed = True
+ jobs = [f.task for f in self._flights.values()]
+ for job in jobs:
+ job.cancel()
+ if jobs:
+ await asyncio.gather(*jobs, return_exceptions=True)
+ self._flights.clear()
+ if self._owns_http and self._http is not None:
+ await self._http.aclose()
diff --git a/commands.py b/commands.py
new file mode 100644
index 0000000..1ecc8b0
--- /dev/null
+++ b/commands.py
@@ -0,0 +1,181 @@
+"""Parse arguments after the framework's registered ``ba`` command.
+
+Adapters replace actual At components with ``mention_token(index)`` and pass
+their IDs in ``mentions`` in component order. NUL is reserved for these tokens:
+adapters must reject NUL in Plain input. Typed ``@user:`` is always literal text.
+Names which look like reserved words or numeric IDs can use ``name:``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+import shlex
+
+
+@dataclass(frozen=True)
+class Target:
+ kind: str # me | mention | stb | steam | name
+ value: str
+
+
+@dataclass(frozen=True)
+class Request:
+ action: str
+ target: Target | None = None
+ limit: int = 5
+ code: str = "" # match ID for match; request code for select/cancel
+ index: int = 0 # one-based candidate index
+
+
+_ALIASES = {
+ "帮助": "help", "我": "me", "自己": "me", "战绩": "stats",
+ "近期": "recent", "最近": "recent", "上一场": "last",
+ "单局": "match", "搜索": "search", "绑定": "bind",
+ "当前绑定": "binding", "解绑": "unbind", "选择": "select",
+ "取消": "cancel", "状态": "status", "缓存": "cache", "清理": "clear", "额度": "quota",
+}
+_NUMBER = re.compile(r"[0-9]+\Z")
+
+
+def mention_token(index: int) -> str:
+ """Encode a trusted component position, not a user-typed account marker."""
+ return f"\x00at:{index}\x00"
+
+
+def _target(parts: list[str], mentions: dict[str, str], aliases: bool) -> Target:
+ if not parts:
+ raise ValueError("请指定玩家:me、@群友、stb:玩家ID、steam:SteamID64 或 name:昵称。")
+ value = " ".join(parts)
+ if not value.strip():
+ raise ValueError("玩家名称或 ID 不能为空。")
+ if "\x00" in value:
+ if len(parts) != 1 or value not in mentions:
+ raise ValueError("请单独使用聊天软件的 @ 提及功能选择群友;昵称请使用文字输入。")
+ return Target("mention", mentions[value])
+ prefix, separator, suffix = value.partition(":")
+ if separator and prefix.lower() in {"name", "stb", "steam"}:
+ kind = prefix.lower()
+ if not suffix.strip():
+ raise ValueError("玩家名称或 ID 不能为空。")
+ if kind != "name" and any(char.isspace() for char in suffix):
+ raise ValueError("玩家 ID 不能包含空格。")
+ if kind == "steam" and not _NUMBER.fullmatch(suffix):
+ raise ValueError("steam: 后请填写纯数字的 SteamID64。")
+ return Target(kind, suffix)
+ if value.lower() == "me" or (aliases and value in {"我", "自己"}):
+ return Target("me", "")
+ if any(part.startswith("@user:") for part in parts):
+ raise ValueError("请通过聊天软件的 @ 提及功能选择群友,不要手动输入 @user: 文本。")
+ if _NUMBER.fullmatch(value):
+ raise ValueError("纯数字可能有歧义,请补充前缀:stb:(STB ID)、steam:(SteamID64)或 name:(纯数字昵称)。")
+ if re.search(r"https?://|www\.|steamcommunity\.com/", value, re.IGNORECASE):
+ raise ValueError("暂不支持直接输入主页链接,请改用 stb:、steam: 或 name:昵称。")
+ if value.startswith("@"):
+ raise ValueError("请通过聊天软件的 @ 提及功能选择群友;如果玩家昵称本身以 @ 开头,请使用 name:昵称。")
+ return Target("name", value)
+
+
+def _count(value: str, maximum: int) -> int:
+ try:
+ count = int(value) if _NUMBER.fullmatch(value) else 0
+ except ValueError:
+ count = 0
+ if not 1 <= count <= maximum:
+ raise ValueError(f"对局数量须为 1 到 {maximum} 的整数。")
+ return count
+
+
+def parse_command(
+ text: str,
+ mentions: list[str] | None = None,
+ default_limit: int = 5,
+ max_limit: int = 20,
+ chinese_aliases: bool = True,
+) -> Request:
+ """Return one canonical request; all syntax errors are Chinese ValueErrors.
+
+ Actions: help/stats/recent/last/match/search/bind/binding/unbind/select/
+ cancel/status/quota/cache_clear. Match IDs are in ``code``; search queries in
+ ``target=Target('name', query)``. Empty arguments mean help.
+ """
+ if (type(default_limit) is not int or type(max_limit) is not int
+ or not 1 <= default_limit <= max_limit):
+ raise ValueError("默认数量和最大数量须为有效正整数,且默认数量不能超过上限。")
+ try:
+ parts = shlex.split(text)
+ except ValueError as exc:
+ raise ValueError("引号未配对,包含空格的昵称请用成对的英文双引号(\"\")括起来。") from exc
+ if not parts:
+ return Request("help", limit=default_limit)
+
+ def keyword(word: str) -> str:
+ return _ALIASES.get(word, word.lower()) if chinese_aliases else word.lower()
+
+ action = keyword(parts.pop(0))
+ if action not in {"stats", "bind", "recent", "last"} and any("\x00" in part for part in parts):
+ raise ValueError("此命令请使用文字参数;@ 提及仅用于指定查询或绑定的群友。")
+ compact = re.fullmatch(r"recent([0-9]+)", action)
+ if compact:
+ parts.insert(0, compact[1])
+ action = "recent"
+ if action == "me":
+ if not parts:
+ return Request("stats", Target("me", ""), default_limit)
+ subcommand = keyword(parts.pop(0))
+ compact = re.fullmatch(r"recent([0-9]+)", subcommand)
+ if compact:
+ parts.insert(0, compact[1])
+ subcommand = "recent"
+ if subcommand == "last" and not parts:
+ return Request("last", Target("me", ""), default_limit)
+ if subcommand != "recent" or len(parts) > 1:
+ raise ValueError("用法:me、me recent [数量] 或 me last。")
+ limit = _count(parts[0], max_limit) if parts else default_limit
+ return Request("recent", Target("me", ""), limit)
+ if action in {"help", "binding", "unbind", "status", "quota"}:
+ if parts:
+ raise ValueError(f"""{action} 命令不需要额外参数,请直接发送。""")
+ return Request(action, limit=default_limit)
+ if action == "cache":
+ if len(parts) != 1 or keyword(parts[0]) != "clear":
+ raise ValueError("用法:cache clear。")
+ return Request("cache_clear", limit=default_limit)
+ if action in {"match", "cancel", "select"}:
+ expected = 2 if action == "select" else 1
+ if len(parts) != expected or not parts[0] or any(c.isspace() for c in parts[0]):
+ raise ValueError({"match": "用法:match <对局ID>。", "cancel": "用法:cancel <请求码>。",
+ "select": "用法:select <请求码> <序号>。"}[action])
+ index = 0
+ if action == "select":
+ try:
+ index = int(parts[1]) if _NUMBER.fullmatch(parts[1]) else 0
+ except ValueError:
+ index = 0
+ if index < 1:
+ raise ValueError("候选序号须为从 1 开始的整数。")
+ return Request(action, limit=default_limit, code=parts[0], index=index)
+ if action == "search":
+ if not parts or not " ".join(parts).strip():
+ raise ValueError("用法:search <昵称>。")
+ return Request("search", Target("name", " ".join(parts)), default_limit)
+ trusted_mentions = {mention_token(index): user for index, user in enumerate(mentions or ())}
+ if action == "recent":
+ limit = default_limit
+ if "--limit" in parts:
+ position = parts.index("--limit")
+ if position == 0 or position != len(parts) - 2:
+ raise ValueError("用法:recent <玩家> --limit <数量>。")
+ limit = _count(parts[-1], max_limit)
+ parts = parts[:position]
+ elif len(parts) == 1 and _NUMBER.fullmatch(parts[0]):
+ return Request("recent", Target("me", ""), _count(parts[0], max_limit))
+ if any(part.startswith("--") for part in parts):
+ raise ValueError("近期查询仅支持末尾的 --limit <数量> 参数。")
+ target = _target(parts, trusted_mentions, chinese_aliases) if parts else Target("me", "")
+ return Request("recent", target, limit)
+ if action in {"stats", "bind", "last"}:
+ if action == "last" and not parts:
+ return Request("last", Target("me", ""), default_limit)
+ return Request(action, _target(parts, trusted_mentions, chinese_aliases), default_limit)
+ raise ValueError("未知命令,请使用 ba help 查看帮助。")
diff --git a/docs/API_NOTES.md b/docs/API_NOTES.md
index 3dfcacc..8af5164 100644
--- a/docs/API_NOTES.md
+++ b/docs/API_NOTES.md
@@ -131,7 +131,7 @@ storage 为 duck type:`get_cache(key) -> (JSON payload, fetched_at, expires_at
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`,其他层不增加。新鲜缓存判断后、网络退避前以及旧缓存回退前会只读检查额度,避免额度耗尽后因排队超时返回旧缓存。失败及重试计入;缓存命中、队列中取消、本地命令和图像渲染不计入。为防止断电或取消造成超额,已持久记账的尝试不退款;很小的记账后、发送前中断窗口可能保守多记一次。
+每次 `_request` 的每个 HTTP 尝试,在节流排队后、发送前调用 `Storage.consume_request`。SQLite 事务同时检查三层额度,再一起增加;不足则抛出 `QuotaExceededError`,其他层不增加。事务取得写锁后及提交前核对发送准入;退避发生变化或跨越北京时间日界时回滚,离开事务后重新排队,按最终准入日期记账。提交后直接交给 HTTP,不再进入退避等待。新鲜缓存判断后、网络退避前以及旧缓存回退前会只读检查额度,避免额度耗尽后因排队超时返回旧缓存。失败及重试计入;缓存命中、记账前取消、本地命令和图像渲染不计入。为防止断电或取消造成超额,已持久记账的尝试不退款;很小的提交与交给 HTTP 之间的中断窗口可能保守多记一次。
查询概览通常包含多个 HTTP,部分请求已发出后额度不足,会保留已用次数并中止剩余调用;绑定逻辑不会据不完整结果修改原绑定。额度不足时可读取新鲜缓存,但不会以 stale 回退隐藏该错误。网络合并仅限同一用户、同一群,防止其他调用者的强制刷新扣到原发起者。
diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md
index 2219b29..271c7af 100644
--- a/docs/VALIDATION.md
+++ b/docs/VALIDATION.md
@@ -7,7 +7,7 @@
| 项目 | 结果 |
| --- | --- |
| 首版代码与文档 | 已实现;按项目框架、插件实现两个 PR 审阅 |
-| 离线业务与契约测试 | **392 passed,19.49 秒**(含新增每日额度) |
+| 离线业务与契约测试 | **435 passed,24.70 秒**(含文案导入及 PR 审查回归) |
| 本地卡片渲染 | 18 组 HTML/文字、36 张 PNG;布局与外部请求检查全通过 |
| 成品目视检查 | 主代理查看 4 张代表图;渲染子代理另查看 9 张 |
| Python 语法检查 | 全部通过 |
@@ -26,6 +26,18 @@ Gemini 返回的 331 条文案全部匹配导出基线;回填 68 条变化,
项目 CI 使用 Python 3.11 / 3.12,执行依赖兼容性、元数据和语法检查;插件实现 PR 增加完整离线测试和安装包构建检查。CI 不调用真实战绩 API,也不发送 QQ 消息。
+PR 审查统一了以下行为,并增加对应回归验证:
+
+- 近期列表、单局详情和展示层共用目标玩家身份核对;有参与者但缺少目标时明确拒绝。
+- 真实 At 组件保留来源,显式昵称和搜索文本中的 `@user:` 不再被误判;手写标记仍不能借用真实提及。
+- 常用单位按来源 ID 聚合,名称仅用于展示;不同 ID 同名时在图片和文字中统一区分。
+- 所有 SQLite 业务写入共用事务边界;异常和重复取消时等待回滚完成后才释放连接锁。
+- HTTP 发送准入同时协调节流、共享退避和额度记账,响应处理保持并发。
+
+文案导入后重新生成 18 组 HTML/文字、36 张 PNG,布局与外部请求检查全部通过;复查手机概览,标题和常用单位区正常。预览仍全部为合成样本。
+
+最终全量运行:`python -m pytest -q`,435 passed(24.70 秒)。新增准入测试验证事务中跨日回滚、退避期间跨午夜后新日最多 100 次 HTTP;取消回滚与响应并发均有覆盖。旧间隔测试的 15ms 时间窗口在 Windows 全量运行中出现抖动,改为 80ms 间隔并保留 70ms 下界和并发断言后,全量通过。
+
## 核对基线
- 目标仓库初始 `main`:`c4272e87413734ec317fe937faa868bbbf70eb08`,原来仅有 Apache-2.0 LICENSE。
diff --git a/main.py b/main.py
new file mode 100644
index 0000000..b49d6b6
--- /dev/null
+++ b/main.py
@@ -0,0 +1,225 @@
+"""AstrBot v4.29.4 接口适配;命令只经宿主的唤醒及指令过滤器进入。"""
+from __future__ import annotations
+
+import asyncio
+from dataclasses import fields
+import hashlib
+from pathlib import Path
+import re
+import shutil
+import time
+
+from astrbot.api import AstrBotConfig
+from astrbot.api.event import AstrMessageEvent, filter
+from astrbot.api.message_components import At, Plain
+from astrbot.api.star import Context, Star, StarTools
+
+from .client import BatraceClient, ClientConfig, ClientError
+from .commands import mention_token, parse_command
+from .quota import GLOBAL_DAILY_LIMIT, QuotaActor
+from .render import Renderer
+from .service import Caller, StatsService
+from .settings import Settings
+from .storage import Storage
+
+
+def extract_arguments(event, prefixes):
+ """Rebuild Plain/At components; keep quoted nickname spacing and true IDs."""
+ parts, mentions = [], []
+ for component in event.get_messages():
+ if isinstance(component, Plain):
+ # NUL separates trusted components; ordinary @user: names stay literal.
+ if "\x00" in component.text:
+ raise ValueError("命令文本包含不支持的控制字符。")
+ parts.append(component.text)
+ elif isinstance(component, At):
+ user = str(component.qq)
+ if user == str(event.get_self_id()) and not "".join(parts).strip():
+ continue
+ if user == "all":
+ raise ValueError("不能使用 @全体成员 查询玩家。")
+ parts.append(f" {mention_token(len(mentions))} ")
+ mentions.append(user)
+ 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)
+ if match:
+ return raw[match.end():], mentions
+ # Some adapters expose normalized text with command prefixes already removed.
+ if not mentions:
+ match = re.match(r"^ba(?:\s+|$)", event.get_message_str().strip(), re.IGNORECASE)
+ if match:
+ return event.get_message_str().strip()[match.end():], []
+ raise ValueError("未能识别命令内容,请确认使用了当前配置的 AstrBot 命令前缀后重试。")
+
+
+def quota_actor(event):
+ """Account to the actual sender and group, never the queried/@ player."""
+ def identifier(value, required=True):
+ if value is None and not required:
+ return ""
+ if isinstance(value, bool) or not isinstance(value, (str, int)):
+ raise ValueError("无法确认消息的用户或群身份。")
+ result = str(value).strip()
+ if required and not result:
+ raise ValueError("无法确认消息的用户或群身份。")
+ return result
+ return QuotaActor(identifier(event.get_platform_id()), identifier(event.get_sender_id()),
+ identifier(event.get_group_id(), required=False))
+
+
+class BAStatsPlugin(Star):
+ def __init__(self, context: Context, config: AstrBotConfig):
+ super().__init__(context)
+ self.settings = Settings.from_config(config)
+ self.data_dir = StarTools.get_data_dir("astrbot_plugin_ba_stats")
+ self.storage = Storage(self.data_dir, max_entries=self.settings.cache_max_entries)
+ values = {f.name: getattr(self.settings, f.name) for f in fields(ClientConfig)}
+ self.client = BatraceClient(ClientConfig(**values), storage=self.storage)
+ self.service = StatsService(self.client, self.storage, self.settings)
+ self.renderer = Renderer(self.settings.theme, self.settings.timezone)
+ self._images = self.data_dir / "images"
+ self._image_lock = asyncio.Lock()
+ self._tasks = set()
+ self._closed = False
+
+ async def initialize(self):
+ await self.storage.open()
+ self._images.mkdir(parents=True, exist_ok=True)
+ self._prune_images()
+
+ async def _run(self, awaitable):
+ if self._closed:
+ awaitable.close()
+ raise asyncio.CancelledError
+ task = asyncio.create_task(awaitable)
+ self._tasks.add(task)
+ try:
+ return await asyncio.wait_for(task, self.settings.wait_timeout)
+ finally:
+ self._tasks.discard(task)
+
+ def _prune_images(self):
+ files = sorted(self._images.glob("*.jpg"), key=lambda p: p.stat().st_mtime, reverse=True)
+ for index, path in enumerate(files):
+ if index >= 48 or time.time() - path.stat().st_mtime > 86400:
+ path.unlink(missing_ok=True)
+
+ async def _image(self, view, umo):
+ html = self.renderer.template(view)
+ # Scope renderer endpoint/session too: different AstrBot sessions can use
+ # different render services. Content itself remains the same result.
+ digest = hashlib.sha256((umo + html).encode()).hexdigest()
+ destination = self._images / f"{digest}.jpg"
+ async with self._image_lock:
+ if destination.exists() and time.time() - destination.stat().st_mtime <= 86400:
+ return str(destination)
+ # Final HTML is DATA, never a second Jinja template. This preserves
+ # literal {{...}} in nicknames after the first HTML escaping pass.
+ source = await self.html_render(
+ "{{ body | safe }}", {"body": html}, return_url=False,
+ options={"type": "jpeg", "quality": 85, "full_page": True,
+ "viewport_width": 390, "device_scale_factor_level": "ultra"}, umo=umo)
+ if not Path(source).is_file():
+ raise ValueError("渲染服务未返回本地图片。")
+ shutil.copyfile(source, destination)
+ self._prune_images()
+ return str(destination)
+
+ async def _status(self):
+ status = self.client.status()
+ usage = await self.storage.quota_usage()
+ labels = {"authentication": "鉴权失败", "rate_limited": "限流", "timeout": "超时",
+ "schema": "响应结构变化", "identity_mismatch": "身份校验失败",
+ "no_data": "暂无收录", "upstream": "上游暂不可用", "queue_full": "队列已满",
+ "not_configured": "接入未配置", "closed": "客户端已关闭", "daily_quota": "每日额度已用完"}
+ return (f"断箭战报 v0.1.0\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"
+ f"图片缓存:{len(list(self._images.glob('*.jpg')))} 张\n"
+ f"最近错误:{labels.get(status['last_error'], '无' if not status['last_error'] else '请求失败')}\n"
+ "真实接口与 QQ 平台验收待完成。")
+
+ async def _quota(self, actor):
+ usage = await self.storage.quota_usage(actor)
+ def line(label, used, limit):
+ if limit == 0:
+ return f"{label}:已用 {used} 次,不单独限制"
+ return f"{label}:已用 {used}/{limit} 次,剩余 {max(0, limit - used)} 次"
+ lines = [f"今日请求额度 · {usage['day']}(北京时间)",
+ line("个人", usage['user'], self.settings.user_daily_limit)]
+ if actor.group:
+ lines.append(line("本群", usage['group'], self.settings.group_daily_limit))
+ lines.extend([line("全插件", usage['global'], GLOBAL_DAILY_LIMIT),
+ "北京时间每天 0 点重置;个人额度跨群及私聊累计。",
+ "按实际发出的上游 HTTP 请求计数(含重试与失败);命中缓存、本地命令及图片渲染不计入。"])
+ return "\n".join(lines)
+
+ @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 ""
+ 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")
+ if request.action == "quota":
+ yield event.plain_result(await self._quota(quota_actor(event)))
+ return
+ if request.action in {"status", "cache_clear"}:
+ self.service.pending.begin(caller.scope)
+ if not event.is_admin():
+ yield event.plain_result("此命令仅供 AstrBot 管理员使用。")
+ return
+ if request.action == "status":
+ yield event.plain_result(await self._status())
+ else:
+ await self.client.clear_cache()
+ async with self._image_lock:
+ for path in self._images.glob("*.jpg"):
+ path.unlink(missing_ok=True)
+ yield event.plain_result("已清理 API 缓存与图片缓存;账号绑定及今日已用额度不受影响。")
+ return
+ 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)
+ if response.view is not None:
+ for view in self.renderer.views(response.view):
+ if self.settings.image_enabled:
+ try:
+ path = await self._run(self._image(view, event.unified_msg_origin))
+ except (Exception,):
+ self.logger.warning("断箭战报图片渲染失败,已使用相同查询结果回复文字。")
+ else:
+ yield event.image_result(path)
+ continue
+ yield event.plain_result(self.renderer.text(view))
+ except (ClientError, ValueError) as exc:
+ yield event.plain_result(str(exc))
+ except asyncio.TimeoutError:
+ yield event.plain_result("查询等待超时,请稍后重试。")
+ except Exception as exc:
+ # Neither response bodies nor credential-bearing URLs enter logs.
+ self.logger.error("断箭战报请求失败(%s)。", type(exc).__name__)
+ yield event.plain_result("本次查询未完成,请稍后重试;如持续出现,请管理员使用 ba status 检查插件状态。")
+
+ async def terminate(self):
+ self._closed = True
+ tasks = list(self._tasks)
+ for task in tasks:
+ task.cancel()
+ if tasks:
+ await asyncio.gather(*tasks, return_exceptions=True)
+ self._tasks.clear()
+ self.service.close()
+ await self.client.close()
+ await self.storage.close()
diff --git a/models.py b/models.py
new file mode 100644
index 0000000..31e52e7
--- /dev/null
+++ b/models.py
@@ -0,0 +1,274 @@
+"""Plugin-owned normalized models; missing source values remain unknown.
+
+IDs are strings. All adapter-produced datetimes are aware UTC. Ratings and
+unit/value exchanges are distinct; these models claim no lifetime coverage.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+import math
+from typing import Any, Generic, Literal, TypeVar
+from urllib.parse import quote
+
+Outcome = Literal["win", "loss", "unknown"]
+Mode = Literal["ranked", "custom", "unknown"]
+T = TypeVar("T")
+
+
+@dataclass
+class Player:
+ id: str
+ name: str
+ steam_id: str | None = None
+ elo: float | None = None
+ source_url: str | None = None
+ updated_at: datetime | None = None
+ elo_observed_at: datetime | None = None
+
+
+@dataclass
+class Participant:
+ player_id: str
+ name: str
+ team: str | None = None
+ outcome: Outcome = "unknown"
+ elo: float | None = None
+ elo_delta: float | None = None
+ kills: int | None = None
+ losses: int | None = None
+ destroyed_value: float | None = None
+ lost_value: float | None = None
+ units: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class Match:
+ id: str
+ map_name: str | None = None
+ mode: Mode = "unknown"
+ started_at: datetime | None = None
+ duration_seconds: float | None = None
+ winner_team: str | None = None
+ players: list[Participant] = field(default_factory=list)
+ complete: bool = False
+ source_url: str | None = None
+ updated_at: datetime | None = None
+
+
+@dataclass
+class FetchResult(Generic[T]):
+ data: T
+ fetched_at: datetime
+ stale: bool = False
+ source_updated_at: datetime | None = None
+ stale_reason: str | None = None
+
+
+def utc_datetime(value: Any) -> datetime | None:
+ """Parse Unix seconds or ISO with an explicit zone; never guess local time."""
+ from datetime import timezone
+ import math
+
+ if value is None:
+ return None
+ if isinstance(value, bool):
+ raise ValueError("invalid timestamp")
+ if isinstance(value, (int, float)):
+ if not math.isfinite(value):
+ raise ValueError("invalid timestamp")
+ return datetime.fromtimestamp(value, timezone.utc)
+ if isinstance(value, datetime):
+ parsed = value
+ elif isinstance(value, str):
+ parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+ else:
+ raise ValueError("invalid timestamp")
+ if parsed.tzinfo is None or parsed.utcoffset() is None:
+ raise ValueError("timestamp needs an explicit timezone")
+ return parsed.astimezone(timezone.utc)
+
+
+SOURCE_URL = "https://dash.batrace.top/"
+
+
+def canonical_id(value: Any) -> str:
+ if isinstance(value, bool) or not isinstance(value, (str, int)):
+ raise ValueError("expected a string or integer ID")
+ result = str(value)
+ if not result or result != result.strip() or len(result) > 128:
+ raise ValueError("invalid ID")
+ return result
+
+
+def _object(value: Any) -> dict[str, Any]:
+ if not isinstance(value, dict):
+ raise ValueError("expected an object")
+ return value
+
+
+def _number(value: Any, *, count: bool = False) -> float | int | None:
+ if value is None:
+ return None
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
+ raise ValueError("expected a number")
+ if not math.isfinite(value):
+ raise ValueError("expected a finite number")
+ if count:
+ if value < 0 or int(value) != value:
+ raise ValueError("expected a nonnegative count")
+ return int(value)
+ return value
+
+
+def _name(value: Any) -> str:
+ if value is None:
+ return ""
+ if not isinstance(value, str):
+ raise ValueError("expected a name")
+ return value
+
+
+def parse_search(payload: Any) -> list[Player]:
+ """Search has an explicit players array; missing arrays are schema failures."""
+ rows = _object(payload).get("players")
+ if not isinstance(rows, list):
+ raise ValueError("missing players array")
+ result: dict[str, Player] = {}
+ for row in rows:
+ p = _object(row)
+ pid = canonical_id(p.get("id"))
+ candidate = Player(
+ id=pid, name=_name(p.get("name")), elo=_number(p.get("rating")),
+ updated_at=utc_datetime(p.get("updated_at")),
+ source_url=SOURCE_URL + "player/" + quote(pid, safe=""),
+ )
+ # Preserve first-seen ordering and identity; a duplicate ID may be renamed.
+ if pid not in result or (
+ candidate.updated_at is not None
+ and (result[pid].updated_at is None or candidate.updated_at > result[pid].updated_at)
+ ):
+ result[pid] = candidate
+ return list(result.values())
+
+
+def parse_player(payload: Any, requested_id: str) -> Player:
+ """Verify a canonical search echo, then use dated analysis rating observations.
+
+ The info endpoint's documented shape has no ID, so it cannot prove identity.
+ This private cache envelope contains responses from search and analysis.
+ """
+ envelope = _object(payload)
+ candidates = parse_search(envelope.get("search"))
+ player = next((p for p in candidates if p.id == requested_id), None)
+ if player is None:
+ raise ValueError("canonical player ID was not echoed")
+ analysis = _object(envelope.get("analysis"))
+ if "matchCount" not in analysis and "trend" not in analysis:
+ raise ValueError("missing player analysis")
+ if "matchCount" in analysis:
+ _number(analysis["matchCount"], count=True)
+ trend = _object(analysis.get("trend", {}))
+ points = trend.get("points", [])
+ if not isinstance(points, list):
+ raise ValueError("invalid trend points")
+ observations: list[tuple[datetime, float]] = []
+ for row in points:
+ point = _object(row)
+ rating = _number(point.get("ratingAfter"))
+ at = utc_datetime(point.get("endTime"))
+ if rating is not None and at is not None:
+ observations.append((at, rating))
+ if observations:
+ at, rating = max(observations, key=lambda item: item[0])
+ # Search rating is a profile snapshot; retain it if it is demonstrably newer.
+ if player.elo is None or player.updated_at is None or at >= player.updated_at:
+ player.elo = rating
+ player.elo_observed_at = at
+ return player
+
+
+def parse_match(payload: Any, requested_id: str, *, detail: bool = True) -> Match:
+ """Adapt the observed protobuf-shaped matchInfo, not arbitrary JSON objects.
+
+ Only the reference-confirmed protobuf defaults are applied (team and four
+ numeric counters). Ratings, times, names and mode never default to zero.
+ """
+ root = _object(payload)
+ info = _object(root.get("matchInfo"))
+ if "matchId" in root and canonical_id(root["matchId"]) != requested_id:
+ raise ValueError("match ID mismatch")
+ rows = info.get("Data")
+ if not isinstance(rows, dict):
+ raise ValueError("missing match participant data")
+ players: list[Participant] = []
+ seen: set[str] = set()
+ for raw in rows.values():
+ row = _object(raw)
+ pid = canonical_id(row.get("Id"))
+ if pid in seen:
+ raise ValueError("duplicate participant ID")
+ seen.add(pid)
+ team = row.get("TeamId", 0)
+ if isinstance(team, bool) or not isinstance(team, int):
+ raise ValueError("invalid team ID")
+ old, new = _number(row.get("OldRating")), _number(row.get("NewRating"))
+ units = row.get("UnitData", {})
+ if not isinstance(units, dict):
+ raise ValueError("invalid unit data")
+ normalized_units = []
+ for unit in units.values():
+ unit = _object(unit)
+ normalized_units.append({
+ "id": canonical_id(unit.get("Id")),
+ "name": _name(unit.get("Name")) or None,
+ "count": 1,
+ })
+ players.append(Participant(
+ player_id=pid, name=_name(row.get("Name")), team=str(team),
+ elo=new, elo_delta=(new - old if old is not None and new is not None else None),
+ kills=_number(row.get("Destruction", 0), count=True),
+ losses=_number(row.get("Losses", 0), count=True),
+ destroyed_value=_number(row.get("DestructionScore", 0)),
+ lost_value=_number(row.get("LossesScore", 0)), units=normalized_units,
+ ))
+ duration = _number(info.get("TotalPlayTimeInSec"))
+ if duration is not None and duration < 0:
+ raise ValueError("negative duration")
+ start = utc_datetime(info.get("StartTime"))
+ end = utc_datetime(info.get("EndTime"))
+ if start is None and end is not None and duration is not None:
+ from datetime import timedelta
+ start = end - timedelta(seconds=duration)
+ if end is not None and start is not None and end < start:
+ raise ValueError("match ends before it starts")
+ # The reference infers victory from rating changes. This is not an
+ # authoritative outcome field: retain unknown even for consistent deltas.
+ # Type enum meanings are not documented by the reference; zero ELO change
+ # alone cannot distinguish custom, incomplete and unrated matches.
+ complete = detail and bool(players) and end is not None and all(
+ isinstance(row, dict) and isinstance(row.get("UnitData"), dict) for row in rows.values()
+ )
+ return Match(
+ id=requested_id, map_name=(f"地图#{canonical_id(info['MapId'])}" if "MapId" in info else None),
+ started_at=start, duration_seconds=duration,
+ players=players, complete=complete,
+ source_url=SOURCE_URL + "match/" + quote(requested_id, safe=""),
+ )
+
+
+def parse_recent(payload: Any) -> list[Match]:
+ rows = _object(payload).get("matches")
+ if not isinstance(rows, list):
+ raise ValueError("missing matches array")
+ result: dict[str, Match] = {}
+ for raw in rows:
+ row = _object(raw)
+ mid = canonical_id(row.get("matchId"))
+ match = parse_match({"matchInfo": row.get("data")}, mid, detail=False)
+ if mid not in result or len(match.players) > len(result[mid].players):
+ result[mid] = match
+ from datetime import timezone
+ minimum = datetime.min.replace(tzinfo=timezone.utc)
+ return sorted(result.values(), key=lambda m: (m.started_at or minimum, m.id), reverse=True)
diff --git a/pending.py b/pending.py
new file mode 100644
index 0000000..7a4850f
--- /dev/null
+++ b/pending.py
@@ -0,0 +1,125 @@
+"""Single-use candidate selection, isolated by platform/session/user.
+
+Methods are synchronous and locked: call begin before awaiting the network,
+then publish with its generation. Requests and candidates stay opaque.
+"""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+from dataclasses import dataclass
+import itertools
+import math
+import secrets
+import threading
+import time
+from typing import Any, Callable, Iterable
+
+
+Scope = tuple[str, str, str]
+
+
+@dataclass(frozen=True)
+class Pending:
+ scope: Scope
+ generation: int
+ code: str
+ request: Any
+ candidates: tuple[Any, ...]
+ created_at: float
+ expires_at: float
+
+
+@dataclass
+class _Slot:
+ generation: int
+ expires_at: float
+ pending: Pending | None = None
+
+
+class PendingManager:
+ def __init__(
+ self,
+ ttl: float = 120,
+ max_entries: int = 1000,
+ clock: Callable[[], float] = time.monotonic,
+ ) -> None:
+ if not math.isfinite(ttl) or ttl <= 0 or type(max_entries) is not int or max_entries < 1:
+ raise ValueError("候选有效期和容量须大于零。")
+ self.ttl = ttl
+ self.max_entries = max_entries
+ self._clock = clock
+ self._generations = itertools.count(1)
+ self._slots: OrderedDict[Scope, _Slot] = OrderedDict()
+ self._lock = threading.Lock()
+
+ def _prune(self, now: float) -> None:
+ for scope in [scope for scope, slot in self._slots.items() if slot.expires_at <= now]:
+ del self._slots[scope]
+
+ def begin(self, scope: Scope) -> int:
+ """Invalidate the old request immediately, before network work starts."""
+ with self._lock:
+ now = self._clock()
+ self._prune(now)
+ self._slots.pop(scope, None)
+ while len(self._slots) >= self.max_entries:
+ self._slots.popitem(last=False)
+ generation = next(self._generations)
+ self._slots[scope] = _Slot(generation, now + self.ttl)
+ return generation
+
+ def is_current(self, scope: Scope, generation: int) -> bool:
+ """Check an unexpired generation without consuming or extending it."""
+ with self._lock:
+ self._prune(self._clock())
+ slot = self._slots.get(scope)
+ return slot is not None and slot.generation == generation
+
+ def clear(self) -> None:
+ """Invalidate all work on shutdown without recycling generations."""
+ with self._lock:
+ self._slots.clear()
+
+ def publish(
+ self, scope: Scope, generation: int, request: Any, candidates: Iterable[Any]
+ ) -> Pending | None:
+ """Return None if replaced, expired, consumed, or already published."""
+ values = tuple(candidates)
+ with self._lock:
+ now = self._clock()
+ self._prune(now)
+ slot = self._slots.get(scope)
+ if slot is None or slot.generation != generation or slot.pending is not None:
+ return None
+ if not values:
+ del self._slots[scope]
+ return None
+ pending = Pending(scope, generation, f"{generation:x}{secrets.token_hex(2)}",
+ request, values, now, now + self.ttl)
+ slot.pending = pending
+ slot.expires_at = pending.expires_at
+ return pending
+
+ def consume(self, scope: Scope, code: str, index: int) -> tuple[Any, Any]:
+ """Atomically consume a one-based choice; invalid choices preserve it."""
+ with self._lock:
+ self._prune(self._clock())
+ slot = self._slots.get(scope)
+ pending = slot.pending if slot is not None else None
+ if pending is None or pending.code != code:
+ raise ValueError("该选择请求不存在、已过期,或不属于当前会话,请重新发起查询。")
+ if type(index) is not int or not 1 <= index <= len(pending.candidates):
+ raise ValueError(f"候选序号须为 1 到 {len(pending.candidates)} 的整数。")
+ del self._slots[scope]
+ return pending.request, pending.candidates[index - 1]
+
+ def cancel(self, scope: Scope, code: str) -> bool:
+ """Cancel only the matching request; return False for any stale code."""
+ with self._lock:
+ self._prune(self._clock())
+ slot = self._slots.get(scope)
+ if slot is None or slot.pending is None or slot.pending.code != code:
+ return False
+ del self._slots[scope]
+ return True
diff --git a/quota.py b/quota.py
new file mode 100644
index 0000000..f9f001b
--- /dev/null
+++ b/quota.py
@@ -0,0 +1,42 @@
+"""Daily upstream request quotas, independent of credentials and caches."""
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+
+GLOBAL_DAILY_LIMIT = 100
+_BEIJING = timezone(timedelta(hours=8))
+
+
+@dataclass(frozen=True)
+class QuotaActor:
+ platform: str
+ user: str
+ group: str = ""
+
+ def __post_init__(self) -> None:
+ if any(not isinstance(value, str) or not value.strip()
+ for value in (self.platform, self.user)):
+ raise ValueError("配额的平台实例和用户 ID 必须为非空字符串。")
+ if not isinstance(self.group, str) or (self.group and not self.group.strip()):
+ raise ValueError("群 ID 必须为非空字符串;私聊请使用空字符串。")
+
+
+class QuotaExceededError(ValueError):
+ code = "daily_quota"
+
+ def __init__(self, scope: str, limit: int, used: int) -> None:
+ self.scope = scope
+ self.limit = limit
+ self.used = used
+ label = {"global": "全插件", "user": "本用户", "group": "本群"}[scope]
+ super().__init__(f"""{label}今日请求额度已用完(已用 {used}/{limit} 次),将于北京时间 0 点重置。""")
+
+
+class AdmissionDeferred(Exception):
+ """The send gate changed before quota commit; retry without spending."""
+
+
+def quota_day(timestamp: float) -> str:
+ """Return the UTC+08:00 calendar date, independent of the host timezone."""
+ return datetime.fromtimestamp(timestamp, _BEIJING).date().isoformat()
diff --git a/render.py b/render.py
new file mode 100644
index 0000000..2567093
--- /dev/null
+++ b/render.py
@@ -0,0 +1,346 @@
+"""One presentation contract for HTML cards and their plain-text fallback.
+
+Service -> Renderer view contract (independent of models.py):
+ kind: "overview" | "recent" | "match"; title: optional display title.
+ player: {id: str, name: str, source_url?: str}; required for player cards.
+ metrics: [{label: str, value: number | str | None, unit?: str,
+ format?: "integer" | "decimal" | "percent" | "signed", note?: str}].
+ Numbers default to two decimals; counts use integer. Percent values are
+ already on the 0..100 scale. Strings are display text, never HTML.
+ rows (recent): [{id, started_at, map_name, mode, outcome, duration_seconds,
+ elo_delta, kills, losses, destroyed_value, lost_value, unit_exchange,
+ value_exchange, source_url}]. Every field except id may be absent.
+ match (match): {id, map_name, mode, started_at, duration_seconds, winner}.
+ teams (match): [{name, outcome, players: [{id, name, elo, elo_delta, kills,
+ losses, destroyed_value, lost_value, unit_exchange, value_exchange}]}].
+ Team sizes are unrestricted; never pad absent players with dummy rows.
+ common_units (overview, optional): [{name: str, count?: int}].
+ scope: str describing actual sample / mode / coverage (never inferred).
+ fetched_at, source_updated_at: aware datetime or ISO 8601 with timezone.
+ stale: bool; source_url: optional public http(s) link; notes?: list[str].
+ synthetic?: bool marks previews explicitly as synthetic sample data.
+
+Outcome: win/loss/unknown; mode: ranked/custom/unknown (other labels preserved).
+Unit counts (kills/losses) and values (destroyed_value/lost_value) are displayed
+separately. Renderer does not derive statistics, coverage, ratios, or winners.
+None, blank, nonfinite, and absent values display as 暂无; real zero stays zero.
+Missing/naive timestamps display as 暂无, rather than guessing a timezone.
+
+Renderer(theme='dark', timezone='Asia/Shanghai').template(view) returns final
+escaped HTML. For AstrBot use the FIXED template '{{ body | safe }}' with
+data={'body': html}; never pass the generated HTML as another Jinja template.
+This preserves nicknames containing literal Jinja tags. text(view) uses exactly
+the same normalized presentation data. For recent cards, iterate
+views(view), which splits rows into pages of 5, before calling either method.
+Each page preserves scope, identity, timestamps and page/row coverage. These
+methods never query a service or load a remote avatar/font/resource.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from copy import deepcopy
+from datetime import datetime
+from decimal import Decimal, InvalidOperation
+from pathlib import Path
+from urllib.parse import urlsplit
+from zoneinfo import ZoneInfo
+
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+MISSING = "暂无"
+_TITLES = {"overview": "玩家概览", "recent": "近期战绩", "match": "单局战报"}
+_OUTCOMES = {"win": "胜利", "loss": "失利", "unknown": "胜负暂无"}
+_MODES = {"ranked": "排位", "custom": "自定义", "unknown": "暂无"}
+
+
+def _plain(value, default=MISSING) -> str:
+ # str() also strips a caller-supplied Markup object's HTML trust flag.
+ if value is None or isinstance(value, bool):
+ return default
+ result = str(value).strip()
+ return result if result else default
+
+
+def _number(value) -> Decimal | None:
+ if isinstance(value, bool) or not isinstance(value, (int, float, Decimal)):
+ return None
+ try:
+ parsed = Decimal(str(value))
+ return parsed if parsed.is_finite() else None
+ except (InvalidOperation, ValueError):
+ return None
+
+
+def _numeric(value, style="decimal") -> str:
+ parsed = _number(value)
+ if parsed is None:
+ return MISSING
+ if style == "integer":
+ return str(int(parsed)) if parsed == parsed.to_integral_value() else MISSING
+ return format(parsed, "+.2f" if style == "signed" else ".2f")
+
+
+def _safe_url(value) -> str:
+ if not isinstance(value, str) or not value:
+ return ""
+ # Links are shown, never fetched. Reject credentials and ambiguous spellings.
+ if any(character.isspace() or ord(character) < 32 for character in value) or "\\" in value:
+ return ""
+ try:
+ parts = urlsplit(value)
+ if (
+ parts.scheme.lower() not in {"http", "https"}
+ or not parts.hostname
+ or parts.username is not None
+ or parts.password is not None
+ ):
+ return ""
+ parts.port # Invalid/out-of-range ports raise ValueError.
+ except ValueError:
+ return ""
+ return str(value)
+
+
+def _mapping(value) -> Mapping:
+ return value if isinstance(value, Mapping) else {}
+
+
+def _records(value) -> list[Mapping]:
+ return [_mapping(item) for item in value] if isinstance(value, (list, tuple)) else []
+
+
+def _outcome(value) -> dict:
+ key = value if isinstance(value, str) and value in _OUTCOMES else "unknown"
+ return {"key": key, "label": _OUTCOMES[key]}
+
+
+class Renderer:
+ """Render self-contained cards without network access or model imports."""
+
+ def __init__(self, theme: str = "dark", timezone: str = "Asia/Shanghai"):
+ if theme not in {"dark", "light"}:
+ raise ValueError("theme must be dark or light")
+ self.theme = theme
+ self.timezone = ZoneInfo(timezone)
+ self._environment = Environment(
+ loader=FileSystemLoader(Path(__file__).with_name("templates")),
+ autoescape=select_autoescape(("html",)),
+ trim_blocks=True,
+ lstrip_blocks=True,
+ )
+
+ def views(self, view: dict, page_size: int = 5) -> list[dict]:
+ """Return independent recent pages; all other cards have one page."""
+ if isinstance(page_size, bool) or not isinstance(page_size, int) or not 1 <= page_size <= 5:
+ raise ValueError("page_size must be an integer from 1 to 5")
+ if view.get("kind", "overview") != "recent":
+ return [deepcopy(view)]
+ rows = view.get("rows") or []
+ if not isinstance(rows, (list, tuple)):
+ rows = []
+ count = max(1, (len(rows) + page_size - 1) // page_size)
+ result = []
+ for index in range(count):
+ page = deepcopy(view)
+ page.update(
+ rows=deepcopy(list(rows[index * page_size : (index + 1) * page_size])),
+ page=index + 1,
+ page_count=count,
+ row_start=index * page_size + 1 if rows else 0,
+ row_total=len(rows),
+ )
+ result.append(page)
+ return result
+
+ def _time(self, value) -> str:
+ try:
+ if isinstance(value, str):
+ value = datetime.fromisoformat(value.replace("Z", "+00:00"))
+ if not isinstance(value, datetime) or value.utcoffset() is None:
+ return MISSING
+ return value.astimezone(self.timezone).strftime("%Y-%m-%d %H:%M %Z")
+ except (ValueError, OverflowError):
+ return MISSING
+
+ @staticmethod
+ def _duration(value) -> str:
+ parsed = _number(value)
+ if parsed is None or parsed < 0:
+ return MISSING
+ seconds = int(parsed)
+ minutes, seconds = divmod(seconds, 60)
+ hours, minutes = divmod(minutes, 60)
+ return f"{hours}时{minutes:02d}分{seconds:02d}秒" if hours else f"{minutes}分{seconds:02d}秒"
+
+ @staticmethod
+ def _metric(metric: Mapping) -> dict:
+ value = metric.get("value")
+ style = metric.get("format", "decimal")
+ if style not in {"integer", "decimal", "percent", "signed"}:
+ style = "decimal"
+ formatted = _plain(value) if isinstance(value, str) else _numeric(value, style)
+ unit = _plain(metric.get("unit"), "")
+ if style == "percent" and not unit:
+ unit = "%"
+ if formatted == MISSING:
+ unit = ""
+ display = formatted + (unit if unit == "%" else " " + unit) if unit else formatted
+ return {
+ "label": _plain(metric.get("label")),
+ "value": formatted,
+ "unit": unit,
+ "display": display,
+ "note": _plain(metric.get("note"), ""),
+ }
+
+ def _exchange(self, item: Mapping, *, elo: bool = False) -> list[dict]:
+ fields = [
+ ("kills", "摧毁单位", "integer", "个"),
+ ("losses", "损失单位", "integer", "个"),
+ ("unit_exchange", "单位交换比", "decimal", ""),
+ ("destroyed_value", "摧毁价值", "decimal", ""),
+ ("lost_value", "损失价值", "decimal", ""),
+ ("value_exchange", "价值交换比", "decimal", ""),
+ ]
+ if elo:
+ fields = [("elo", "ELO", "decimal", ""), ("elo_delta", "ELO 变化", "signed", "")] + fields
+ return [
+ self._metric({"label": label, "value": item.get(key), "format": style, "unit": unit})
+ for key, label, style, unit in fields
+ ]
+
+ def _prepare(self, view: dict) -> dict:
+ kind = view.get("kind", "overview")
+ if kind not in _TITLES:
+ raise ValueError("unknown card kind")
+ player = _mapping(view.get("player"))
+ match = _mapping(view.get("match"))
+ prepared = {
+ "kind": kind,
+ "title": _plain(view.get("title"), _TITLES[kind]),
+ "theme": self.theme,
+ "player": {
+ "name": _plain(player.get("name")),
+ "id": _plain(player.get("id")),
+ "source_url": _safe_url(player.get("source_url")),
+ },
+ "metrics": [self._metric(item) for item in _records(view.get("metrics"))],
+ "scope": _plain(view.get("scope")),
+ "fetched_at": self._time(view.get("fetched_at")),
+ "source_updated_at": self._time(view.get("source_updated_at")),
+ "stale": view.get("stale") is True,
+ "source_url": _safe_url(view.get("source_url")) or _safe_url(player.get("source_url")),
+ "synthetic": view.get("synthetic") is True,
+ "notes": [_plain(note) for note in view.get("notes", [])] if isinstance(view.get("notes"), (list, tuple)) else [],
+ "common_units": [
+ {"name": _plain(item.get("name")), "count": _numeric(item.get("count"), "integer")}
+ for item in _records(view.get("common_units"))
+ ],
+ "rows": [],
+ "teams": [],
+ "pagination": "",
+ }
+ for item in _records(view.get("rows")):
+ prepared["rows"].append({
+ "id": _plain(item.get("id")),
+ "started_at": self._time(item.get("started_at")),
+ "map_name": _plain(item.get("map_name")),
+ "mode": _MODES.get(_plain(item.get("mode")), _plain(item.get("mode"))),
+ "outcome": _outcome(item.get("outcome")),
+ "duration": self._duration(item.get("duration_seconds")),
+ "elo_delta": _numeric(item.get("elo_delta"), "signed"),
+ "exchange": self._exchange(item),
+ "source_url": _safe_url(item.get("source_url")),
+ })
+ prepared["match"] = {
+ "id": _plain(match.get("id")),
+ "map_name": _plain(match.get("map_name")),
+ "mode": _MODES.get(_plain(match.get("mode")), _plain(match.get("mode"))),
+ "started_at": self._time(match.get("started_at")),
+ "duration": self._duration(match.get("duration_seconds")),
+ "winner": _plain(match.get("winner")),
+ }
+ for team in _records(view.get("teams")):
+ prepared["teams"].append({
+ "name": _plain(team.get("name")),
+ "outcome": _outcome(team.get("outcome")),
+ "players": [
+ {"id": _plain(item.get("id")), "name": _plain(item.get("name")), "metrics": self._exchange(item, elo=True)}
+ for item in _records(team.get("players"))
+ ],
+ })
+ page = _number(view.get("page"))
+ page_count = _number(view.get("page_count"))
+ row_total = _number(view.get("row_total"))
+ row_start = _number(view.get("row_start"))
+ if kind == "recent" and all(value is not None and value == value.to_integral_value() for value in (page, page_count, row_total, row_start)):
+ end = int(row_start) + len(prepared["rows"]) - 1 if prepared["rows"] else 0
+ prepared["pagination"] = f"第 {int(page)}/{int(page_count)} 页 · 本页 {int(row_start)}–{end} 场 / 共 {int(row_total)} 场"
+ return prepared
+
+ def template(self, view: dict) -> str:
+ prepared = self._prepare(view)
+ return self._environment.get_template(f"{prepared['kind']}.html").render(view=prepared)
+
+ def text(self, view: dict) -> str:
+ """Use the HTML presentation values verbatim in a readable fallback."""
+ data = self._prepare(view)
+ lines = [f"断箭战报 · {data['title']}"]
+ if data["synthetic"]:
+ lines.append("合成样本 · 非真实玩家战绩")
+ if data["kind"] != "match" or data["player"]["id"] != MISSING:
+ lines.extend([data["player"]["name"], f"玩家 ID:{data['player']['id']}"])
+ lines.append(f"统计范围:{data['scope']}")
+ if data["pagination"]:
+ lines.append(data["pagination"])
+ for metric in data["metrics"]:
+ lines.append(f"{metric['label']}:{metric['display']}" + (f"({metric['note']})" if metric["note"] else ""))
+ if data["kind"] == "overview":
+ if not data["metrics"]:
+ lines.append("统计指标:暂无")
+ lines.append("常用单位 / 兵种")
+ lines.extend(f"{unit['name']}:{unit['count']}" + (" 个" if unit["count"] != MISSING else "") for unit in data["common_units"])
+ if not data["common_units"]:
+ lines.append(MISSING)
+ elif data["kind"] == "recent":
+ for index, row in enumerate(data["rows"], 1):
+ lines.extend([
+ f"{index}. {row['map_name']} · {row['outcome']['label']}",
+ f"对局 ID:{row['id']}",
+ f"时间:{row['started_at']} · 模式:{row['mode']} · 时长:{row['duration']}",
+ f"ELO 变化:{row['elo_delta']}",
+ ";".join(f"{metric['label']}:{metric['display']}" for metric in row["exchange"]),
+ ])
+ if row["source_url"]:
+ lines.append(f"对局来源:{row['source_url']}")
+ if not data["rows"]:
+ lines.append("近期对局:暂无")
+ else:
+ match = data["match"]
+ lines.extend([
+ f"对局 ID:{match['id']}",
+ f"地图:{match['map_name']} · 模式:{match['mode']}",
+ f"时间:{match['started_at']} · 时长:{match['duration']}",
+ f"胜方:{match['winner']}",
+ ])
+ for team in data["teams"]:
+ lines.append(f"{team['name']} · {team['outcome']['label']} · {len(team['players'])} 人")
+ for player in team["players"]:
+ lines.append(f"{player['name']} · 玩家 ID:{player['id']}")
+ lines.append(";".join(f"{metric['label']}:{metric['display']}" for metric in player["metrics"]))
+ if not team["players"]:
+ lines.append("队员:暂无")
+ if not data["teams"]:
+ lines.append("分队与玩家:暂无")
+ lines.extend(data["notes"])
+ if data["stale"]:
+ lines.append("旧缓存 · 以抓取时间为准")
+ lines.extend([
+ f"抓取时间:{data['fetched_at']}",
+ f"来源更新:{data['source_updated_at']}",
+ f"数据来源:{data['source_url'] or MISSING}",
+ ])
+ if data["player"]["source_url"] and data["player"]["source_url"] != data["source_url"]:
+ lines.append(f"玩家来源:{data['player']['source_url']}")
+ return "\n".join(lines)
diff --git a/service.py b/service.py
new file mode 100644
index 0000000..0dde3de
--- /dev/null
+++ b/service.py
@@ -0,0 +1,314 @@
+"""平台无关的查询、身份选择和战报组装。生产路径从不读取演示数据。"""
+from __future__ import annotations
+
+import asyncio
+from collections import Counter, OrderedDict
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+import itertools
+import time
+
+from .client import participant_for
+from .commands import Request, Target
+from .models import FetchResult, Match, Participant, Player
+from .pending import PendingManager
+from .storage import Binding
+
+
+@dataclass(frozen=True)
+class Caller:
+ platform: str
+ session: str
+ user: str
+ prefix: str = "/ba"
+
+ @property
+ def scope(self):
+ return self.platform, self.session, self.user
+
+
+@dataclass
+class Response:
+ text: str = ""
+ view: dict | None = None
+
+
+def ratio(numerator, denominator):
+ if numerator is None or denominator is None:
+ return None
+ if denominator == 0:
+ return "无损失" if numerator > 0 else None
+ return numerator / denominator
+
+
+def freshness(*results):
+ return {
+ "fetched_at": min(r.fetched_at for r in results),
+ "stale": any(r.stale for r in results),
+ "source_updated_at": min((r.source_updated_at for r in results if r.source_updated_at), default=None),
+ }
+
+
+def participant_view(p: Participant):
+ return dict(id=p.player_id, name=p.name, elo=p.elo, elo_delta=p.elo_delta,
+ kills=p.kills, losses=p.losses, destroyed_value=p.destroyed_value,
+ lost_value=p.lost_value, unit_exchange=ratio(p.kills, p.losses),
+ value_exchange=ratio(p.destroyed_value, p.lost_value))
+
+
+def recent_rows(matches, player_id):
+ rows = []
+ for match in matches:
+ person = participant_for(match, player_id)
+ if person is None:
+ continue
+ row = participant_view(person)
+ row.update(id=match.id, started_at=match.started_at, map_name=match.map_name,
+ mode=match.mode, outcome=person.outcome,
+ duration_seconds=match.duration_seconds, source_url=match.source_url)
+ rows.append(row)
+ return rows
+
+
+def match_view(result, player=None):
+ match = result.data
+ if player is not None:
+ participant_for(match, player.id)
+ teams = OrderedDict()
+ for person in match.players:
+ key = person.team if person.team is not None else "未知"
+ if key not in teams:
+ teams[key] = {"name": f"分队 {key}", "outcome": "unknown", "players": []}
+ teams[key]["players"].append(participant_view(person))
+ if match.winner_team is not None and person.team is not None:
+ teams[key]["outcome"] = "win" if person.team == match.winner_team else "loss"
+ view = {"kind": "match", "match": {
+ "id": match.id, "map_name": match.map_name, "mode": match.mode,
+ "started_at": match.started_at, "duration_seconds": match.duration_seconds,
+ "winner": f"分队 {match.winner_team}" if match.winner_team is not None else None,
+ }, "teams": list(teams.values()), "scope": f"单局 · 实际收录 {len(match.players)} 名玩家",
+ "source_url": match.source_url, **freshness(result)}
+ if player:
+ view["player"] = asdict(player)
+ if not match.complete:
+ view["notes"] = ["本局数据可能尚未完整。"]
+ return view
+
+
+class StatsService:
+ def __init__(self, client, storage, settings):
+ self.client, self.storage, self.settings = client, storage, settings
+ self.pending = PendingManager()
+ self._cooldowns = OrderedDict()
+ self._mutations = OrderedDict()
+ self._serial = itertools.count(1)
+ self._binding_lock = asyncio.Lock()
+
+ def help(self, caller):
+ p = caller.prefix
+ return f"""【断箭战报】使用指南
+首次使用:{p} search 昵称 → 找到目标后发送 {p} bind stb:玩家ID → 按提示发送 {p} select <请求码> <序号> 确认一次即可。
+说明:绑定仅用于设定默认查询对象,不代表 Steam 账号所有权认证。
+
+常用命令:
+• {p} me:查看自己的玩家概览
+• {p} stats <玩家>:查看指定玩家概览(支持 me / @群友 / stb:ID / name:昵称)
+• {p} recent [数量] / {p} me recent [数量]:查看自己近期战绩(默认 {self.settings.default_limit} 场)
+• {p} recent <玩家> --limit <数量>:查看指定玩家近期战绩(如 {p} recent name:"Player 2" --limit 10)
+• {p} last [玩家] / {p} me last:查看最近一场可用单局战报
+• {p} match <对局ID>:查看指定单局战报
+• {p} search <昵称>:搜索玩家候选
+• {p} bind <玩家> / {p} binding / {p} unbind:绑定、查看或解除默认账号
+• {p} select <请求码> <序号> / {p} cancel <请求码>:确认或取消候选选择
+• {p} quota:查看个人、本群及全插件今日请求额度
+• {p} help:查看本帮助
+
+输入与额度提示:
+• 纯数字昵称请加前缀(如 name:12345);与关键词重名请写 name:me。
+• steam:SteamID64 需等待权威映射确认,当前请先用昵称搜索再选择 STB ID。
+• 管理员命令:{p} status(查看状态)、{p} cache clear(清理缓存)。
+• 全插件每日固定上限 100 次(个人默认 20 次、每群默认 100 次),北京时间 0 点重置;按实际发出的上游 HTTP 请求计数(含重试与失败),命中缓存不计入。
+• 命令前缀遵循 AstrBot 配置;图片渲染失败时会自动回复同内容的文字战报。"""
+
+ def _mutation(self, caller):
+ key = (caller.platform, caller.user)
+ token = next(self._serial)
+ self._mutations.pop(key, None)
+ self._mutations[key] = token
+ while len(self._mutations) > 1000:
+ self._mutations.popitem(last=False)
+ return token
+
+ def _cooldown(self, caller):
+ key = (caller.platform, caller.user)
+ now = time.monotonic()
+ previous = self._cooldowns.get(key, -float("inf"))
+ remaining = self.settings.cooldown_seconds - (now - previous)
+ if remaining > 0:
+ raise ValueError(f"""查询过于频繁,请 {remaining:.0f} 秒后再试。""")
+ self._cooldowns.pop(key, None)
+ self._cooldowns[key] = now
+ while len(self._cooldowns) > 1000:
+ self._cooldowns.popitem(last=False)
+
+ async def execute(self, request: Request, caller: Caller):
+ action = request.action
+ if action == "cancel":
+ ok = self.pending.cancel(caller.scope, request.code)
+ return Response("已取消本次操作。" if ok else "该请求已失效或不属于当前会话,无法取消。")
+ if action == "select":
+ original, candidate = self.pending.consume(caller.scope, request.code, request.index)
+ generation = self.pending.begin(caller.scope)
+ if original.action == "bind":
+ mutation = self._mutation(caller)
+ verified = await self.client.player(candidate.id, force=True)
+ if verified.data.id != candidate.id or verified.stale:
+ raise ValueError("未能重新核实该账号身份,原绑定保持不变,请稍后重试。")
+ async with self._binding_lock:
+ if (not self.pending.is_current(caller.scope, generation)
+ or self._mutations.get((caller.platform, caller.user)) != mutation):
+ return Response("本次选择已被后续操作覆盖,原绑定未作修改。")
+ player = verified.data
+ await self.storage.set_binding(caller.platform, caller.user, Binding(
+ self.client.namespace, player.id, player.name, player.source_url or ""))
+ return Response(f"""已绑定默认账号:{player.name or '未命名玩家'}
+STB ID:{player.id}
+{player.source_url or ''}
+现在可以发送 {caller.prefix} me 查看战报。""")
+ return await self._report(original, candidate.id)
+
+ generation = self.pending.begin(caller.scope)
+ if action == "help":
+ return Response(self.help(caller))
+ if action == "binding":
+ binding = await self.storage.get_binding(caller.platform, caller.user)
+ if binding is None:
+ return Response(f"""你还没有绑定默认账号,请发送 {caller.prefix} bind name:昵称 进行绑定。""")
+ return Response(f"""当前默认账号:{binding.display_name or '未命名玩家'}
+STB ID:{binding.player_id}
+{binding.source_url}
+注:昵称为绑定时记录,后续查询始终以该 STB ID 为准。""")
+ if action == "unbind":
+ self._mutation(caller)
+ async with self._binding_lock:
+ removed = await self.storage.unbind(caller.platform, caller.user)
+ return Response("已解除默认账号绑定。" if removed else "当前尚未绑定任何账号。")
+ self._cooldown(caller)
+ if action == "match":
+ return Response(view=match_view(await self.client.match(request.code)))
+ target = request.target or Target("me", "")
+ if target.kind == "steam":
+ raise ValueError("SteamID64 与 STB ID 的对应关系尚未验证,两种 ID 不能直接互换。请先用 search <昵称> 搜索,再选择对应的 STB ID。")
+ if target.kind in {"me", "mention"}:
+ user = caller.user if target.kind == "me" else target.value
+ binding = await self.storage.get_binding(caller.platform, user)
+ if binding is None:
+ raise ValueError("你尚未绑定默认账号,请先使用 bind name:昵称 进行绑定。" if target.kind == "me"
+ else "对方尚未绑定默认游戏账号。")
+ if binding.namespace != self.client.namespace:
+ raise ValueError("当前绑定的账号属于其他数据源环境,与当前接入不一致,请重新绑定。")
+ target = Target("stb", binding.player_id)
+ if target.kind == "stb":
+ if action != "bind":
+ return await self._report(request, target.value)
+ result = await self.client.player(target.value)
+ candidates = [result.data]
+ else:
+ result = await self.client.search(target.value)
+ candidates = list({p.id: p for p in result.data}.values())
+ candidates.sort(key=lambda p: p.name != target.value)
+ if not candidates:
+ return Response("未找到匹配的候选玩家,建议换用更准确的昵称重试(未搜到不代表该玩家不存在)。")
+ if action not in {"bind", "search"} and len(candidates) == 1 and candidates[0].name == target.value:
+ return await self._report(request, candidates[0].id)
+ if action == "bind" and result.stale:
+ raise ValueError("当前仅命中旧缓存,暂无法完成绑定核验,原绑定保持不变,请稍后重试。")
+ operation = Request("stats", limit=request.limit) if action == "search" else request
+ selected = candidates[:10]
+ pending = self.pending.publish(caller.scope, generation, operation, selected)
+ if pending is None:
+ return Response("本次查询已被新操作覆盖,请使用最新的候选列表。")
+ lines = ["选择后绑定此账号(只需确认一次):" if action == "bind" else "请选择要查询的账号:",
+ "以下为当前接口返回的候选(不代表全库完整结果);如需缩小范围,请提供更准确的昵称。"]
+ if len(candidates) == 1 and candidates[0].name != target.value and target.kind == "name":
+ lines.append("仅找到相似昵称结果,请仔细核对 STB ID 与来源链接后再确认。")
+ if result.stale:
+ lines.append(f"旧缓存 · 抓取于 {result.fetched_at.isoformat()}")
+ for index, player in enumerate(selected, 1):
+ lines.extend([f"{index}. {player.name or '未命名玩家'} · STB ID:{player.id}",
+ player.source_url or "来源链接暂无",
+ f"{caller.prefix} select {pending.code} {index}"])
+ lines.append(f"""请在 120 秒内发送上方对应指令确认;取消请发送:{caller.prefix} cancel {pending.code}""")
+ return Response("\n".join(lines))
+
+ async def _report(self, request, player_id):
+ player_result = await self.client.player(player_id)
+ player = player_result.data
+ if player.id != player_id:
+ raise ValueError("上游返回的玩家身份与请求不一致。")
+ limit = request.limit if request.action == "recent" else self.settings.max_limit
+ result = await self.client.recent(player.id, limit)
+ matches = result.data
+ if request.action == "last":
+ for match in matches:
+ if participant_for(match, player.id) is None:
+ continue
+ try:
+ detail = await self.client.match(match.id)
+ except Exception as exc:
+ if getattr(exc, "code", "") in {"not_found", "not_recorded", "no_data"}:
+ continue
+ raise
+ view = match_view(detail, player)
+ view.update(freshness(player_result, result, detail))
+ return Response(view=view)
+ return Response(f"{player.name} · STB ID:{player.id}\n当前返回样本中暂无可用单局战报。\n{player.source_url or ''}")
+ rows = recent_rows(matches, player.id)
+ times = [m.started_at for m in matches if m.started_at and any(p.player_id == player.id for p in m.players)]
+ scope = f"近期接口样本 · 实际 {len(rows)} 场(请求最多 {limit} 场);非完整历史,模式以单局标注为准"
+ view = {"kind": "recent" if request.action == "recent" else "overview",
+ "player": asdict(player), "rows": rows, "scope": scope,
+ "source_url": player.source_url, **freshness(player_result, result)}
+ if times:
+ from zoneinfo import ZoneInfo
+ zone = ZoneInfo(self.settings.timezone)
+ view["scope"] += f" · {min(times).astimezone(zone):%Y-%m-%d %H:%M} 至 {max(times).astimezone(zone):%Y-%m-%d %H:%M}"
+ if view["kind"] == "overview":
+ outcomes = Counter(row["outcome"] for row in rows)
+ known = outcomes["win"] + outcomes["loss"]
+ view["metrics"] = [
+ {"label": "ELO", "value": player.elo},
+ {"label": "样本场数", "value": len(rows), "format": "integer"},
+ {"label": "胜 / 负 / 未知", "value": f"{outcomes['win']} / {outcomes['loss']} / {outcomes['unknown']}"},
+ {"label": "已知结果胜率", "value": 100 * outcomes["win"] / known if known else None,
+ "format": "percent", "note": f"分母为 {known} 场已知胜负样本"},
+ ]
+ counts = Counter()
+ names = {}
+ for match in matches:
+ person = participant_for(match, player.id)
+ if person is not None:
+ for unit in person.units:
+ uid = unit["id"]
+ counts[uid] += unit["count"]
+ if unit.get("name"):
+ # Matches arrive newest first; names never define identity.
+ names.setdefault(uid, unit["name"])
+ labels = {uid: names.get(uid, f"单位#{uid}") for uid in counts}
+ duplicates = Counter(labels.values())
+ view["common_units"] = [
+ {"id": uid, "name": f"{labels[uid]}(ID:{uid})" if duplicates[labels[uid]] > 1 else labels[uid],
+ "count": count}
+ for uid, count in counts.most_common(5)
+ ]
+ view["notes"] = ["常用单位按当前样本中的出场记录数统计;未收录名称时显示来源单位 ID。"]
+ if player.elo_observed_at:
+ from zoneinfo import ZoneInfo
+ at = player.elo_observed_at.astimezone(ZoneInfo(self.settings.timezone))
+ view["notes"].append(f"ELO 对应时间:{at:%Y-%m-%d %H:%M %Z}")
+ return Response(view=view)
+
+ def close(self):
+ self.pending.clear()
+ self._cooldowns.clear()
+ self._mutations.clear()
diff --git a/settings.py b/settings.py
new file mode 100644
index 0000000..1758839
--- /dev/null
+++ b/settings.py
@@ -0,0 +1,84 @@
+"""单一配置来源:AstrBotConfig;启动时校验并快照。"""
+from dataclasses import dataclass
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+
+def bounded(data, key, default, lower, upper, cast=float):
+ try:
+ value = cast(data.get(key, default))
+ except (TypeError, ValueError):
+ raise ValueError(f"配置 {key} 必须为数值。") from None
+ if not lower <= value <= upper:
+ raise ValueError(f"配置 {key} 必须在 {lower}–{upper} 之间。")
+ return value
+
+
+def daily_limit(data, key, default):
+ value = data.get(key, default)
+ if type(value) is not int or not 0 <= value <= 100:
+ raise ValueError(f"配置 {key} 必须是 0–100 的整数;0 表示不单独限制。")
+ return value
+
+
+@dataclass(frozen=True)
+class Settings:
+ enabled: bool = False
+ base_url: str = "https://bot.batrace.top"
+ client_id: str = ""
+ api_token: str = ""
+ default_limit: int = 5
+ max_limit: int = 20
+ cooldown_seconds: float = 3
+ chinese_aliases: bool = True
+ image_enabled: bool = True
+ theme: str = "dark"
+ timezone: str = "Asia/Shanghai"
+ request_interval: float = 1
+ concurrency: int = 2
+ queue_size: int = 20
+ request_timeout: float = 20
+ wait_timeout: float = 45
+ retries: int = 1
+ cache_max_entries: int = 1000
+ stale_hours: float = 24
+ user_daily_limit: int = 20
+ group_daily_limit: int = 100
+
+ @classmethod
+ def from_config(cls, config):
+ access = config.get("access", {})
+ query = config.get("query", {})
+ output = config.get("output", {})
+ maintenance = config.get("maintenance", {})
+ limits = config.get("limits", {})
+ maximum = bounded(query, "max_limit", 20, 1, 20, int)
+ timezone = str(output.get("timezone", "Asia/Shanghai"))
+ try:
+ ZoneInfo(timezone)
+ except (ZoneInfoNotFoundError, ValueError):
+ raise ValueError("时区无效,请填写 Asia/Shanghai 等 IANA 时区名。") from None
+ theme = output.get("theme", "dark")
+ if theme not in {"dark", "light"}:
+ raise ValueError("主题必须为 dark 或 light。")
+ return cls(
+ enabled=bool(access.get("enabled", False)),
+ base_url=str(access.get("base_url", cls.base_url)).strip(),
+ client_id=str(access.get("client_id", "")).strip(),
+ api_token=str(access.get("api_token", "")).strip(),
+ default_limit=bounded(query, "default_limit", 5, 1, maximum, int),
+ max_limit=maximum,
+ cooldown_seconds=bounded(query, "cooldown_seconds", 3, 0, 60),
+ chinese_aliases=bool(query.get("chinese_aliases", True)),
+ image_enabled=bool(output.get("image_enabled", True)),
+ theme=theme, timezone=timezone,
+ request_interval=bounded(maintenance, "request_interval", 1, 0.1, 60),
+ concurrency=bounded(maintenance, "concurrency", 2, 1, 5, int),
+ queue_size=bounded(maintenance, "queue_size", 20, 1, 100, int),
+ request_timeout=bounded(maintenance, "request_timeout", 20, 1, 120),
+ wait_timeout=bounded(maintenance, "wait_timeout", 45, 1, 180),
+ retries=bounded(maintenance, "retries", 1, 0, 2, int),
+ cache_max_entries=bounded(maintenance, "cache_max_entries", 1000, 10, 10000, int),
+ stale_hours=bounded(maintenance, "stale_hours", 24, 0, 168),
+ user_daily_limit=daily_limit(limits, "user_daily_limit", 20),
+ group_daily_limit=daily_limit(limits, "group_daily_limit", 100),
+ )
diff --git a/storage.py b/storage.py
new file mode 100644
index 0000000..5a440dc
--- /dev/null
+++ b/storage.py
@@ -0,0 +1,266 @@
+"""SQLite bindings and persistent JSON cache in the plugin data directory."""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+import json
+import math
+from pathlib import Path
+import time
+from typing import AsyncIterator, Callable
+
+import aiosqlite
+
+if __package__:
+ from .quota import AdmissionDeferred, GLOBAL_DAILY_LIMIT, QuotaActor, QuotaExceededError, quota_day
+else: # The standalone storage tests import this module without AstrBot.
+ from quota import AdmissionDeferred, GLOBAL_DAILY_LIMIT, QuotaActor, QuotaExceededError, quota_day
+
+
+@dataclass(frozen=True)
+class Binding:
+ namespace: str
+ player_id: str
+ display_name: str
+ source_url: str = ""
+ updated_at: float = field(default_factory=time.time)
+
+ def __post_init__(self) -> None:
+ if not isinstance(self.player_id, str) or not self.player_id:
+ raise ValueError("玩家 ID 须为非空字符串。")
+ if not isinstance(self.namespace, str) or not self.namespace:
+ raise ValueError("数据源命名空间不能为空。")
+
+
+class Storage:
+ def __init__(
+ self,
+ data_dir: str | Path,
+ *,
+ max_entries: int = 1000,
+ max_age_seconds: float = 604800,
+ clock: Callable[[], float] | None = None,
+ ) -> None:
+ if (type(max_entries) is not int or max_entries < 0
+ or not math.isfinite(max_age_seconds) or max_age_seconds < 0):
+ raise ValueError("缓存容量和最长保留时间须为非负有限数值。")
+ self.path = Path(data_dir) / "ba_stats.sqlite3"
+ self.max_entries = max_entries
+ self.max_age_seconds = max_age_seconds
+ self._clock = clock if clock is not None else time.time
+ self._db: aiosqlite.Connection | None = None
+ self._lock = asyncio.Lock()
+
+ def _connection(self) -> aiosqlite.Connection:
+ if self._db is None:
+ raise RuntimeError("数据库尚未打开。")
+ return self._db
+
+ @asynccontextmanager
+ async def _transaction(self) -> AsyncIterator[aiosqlite.Connection]:
+ """Keep every write and its cancellation cleanup inside the connection lock."""
+ async with self._lock:
+ db = self._connection()
+ try:
+ async with db.execute("BEGIN IMMEDIATE"):
+ pass
+ yield db
+ await db.commit()
+ except BaseException:
+ # aiosqlite still runs queued SQL after its waiter is cancelled.
+ # Drain rollback, even on repeated cancellation, before reuse.
+ rollback = asyncio.create_task(db.rollback())
+ while not rollback.done():
+ try:
+ await asyncio.shield(rollback)
+ except asyncio.CancelledError:
+ continue
+ rollback.result()
+ raise
+
+ async def open(self) -> None:
+ async with self._lock:
+ if self._db is not None:
+ return
+ self.path.parent.mkdir(parents=True, exist_ok=True)
+ db = await aiosqlite.connect(self.path)
+ try:
+ await db.executescript("""
+ CREATE TABLE IF NOT EXISTS bindings (
+ platform TEXT NOT NULL, user_id TEXT NOT NULL,
+ namespace TEXT NOT NULL, player_id TEXT NOT NULL,
+ display_name TEXT NOT NULL, source_url TEXT NOT NULL,
+ updated_at REAL NOT NULL, PRIMARY KEY (platform, user_id)
+ );
+ CREATE TABLE IF NOT EXISTS cache (
+ cache_key TEXT PRIMARY KEY, payload TEXT NOT NULL,
+ fetched_at REAL NOT NULL, expires_at REAL NOT NULL
+ );
+ CREATE INDEX IF NOT EXISTS cache_fetched_at ON cache (fetched_at);
+ CREATE TABLE IF NOT EXISTS request_quotas (
+ day TEXT NOT NULL, scope TEXT NOT NULL,
+ platform TEXT NOT NULL, subject TEXT NOT NULL,
+ used INTEGER NOT NULL CHECK (used >= 0),
+ PRIMARY KEY (day, scope, platform, subject)
+ );
+ """)
+ await db.commit()
+ except BaseException:
+ await db.close()
+ raise
+ self._db = db
+
+ async def close(self) -> None:
+ async with self._lock:
+ if self._db is not None:
+ await self._db.close()
+ self._db = None
+
+ async def get_binding(self, platform: str, user: str) -> Binding | None:
+ async with self._lock:
+ async with self._connection().execute(
+ "SELECT namespace, player_id, display_name, source_url, updated_at "
+ "FROM bindings WHERE platform = ? AND user_id = ?", (platform, user)
+ ) as cursor:
+ row = await cursor.fetchone()
+ return Binding(*row) if row is not None else None
+
+ async def set_binding(self, platform: str, user: str, binding: Binding) -> None:
+ async with self._transaction() as db:
+ await db.execute(
+ "INSERT INTO bindings VALUES (?, ?, ?, ?, ?, ?, ?) "
+ "ON CONFLICT(platform, user_id) DO UPDATE SET namespace=excluded.namespace, "
+ "player_id=excluded.player_id, display_name=excluded.display_name, "
+ "source_url=excluded.source_url, updated_at=excluded.updated_at",
+ (platform, user, binding.namespace, binding.player_id, binding.display_name,
+ binding.source_url, binding.updated_at),
+ )
+
+ async def unbind(self, platform: str, user: str) -> bool:
+ async with self._transaction() as db:
+ async with db.execute(
+ "DELETE FROM bindings WHERE platform = ? AND user_id = ?", (platform, user)
+ ) as cursor:
+ removed = cursor.rowcount > 0
+ return removed
+
+ async def get_cache(self, key: str) -> tuple[dict | list, float, float] | None:
+ """Return retained entries, including expired ones, for labelled fallback."""
+ async with self._lock:
+ async with self._connection().execute(
+ "SELECT payload, fetched_at, expires_at FROM cache WHERE cache_key = ?", (key,)
+ ) as cursor:
+ row = await cursor.fetchone()
+ if row is None:
+ return None
+ return json.loads(row[0]), float(row[1]), float(row[2])
+
+ async def put_cache(self, key: str, payload: dict | list, ttl: float) -> None:
+ if not isinstance(payload, (dict, list)):
+ raise ValueError("缓存内容须为字典或列表。")
+ if not math.isfinite(ttl) or ttl < 0:
+ raise ValueError("缓存有效期须为非负有限秒数。")
+ serialized = json.dumps(payload, ensure_ascii=False, allow_nan=False)
+ async with self._transaction() as db:
+ now = self._clock()
+ await db.execute(
+ "INSERT INTO cache VALUES (?, ?, ?, ?) ON CONFLICT(cache_key) DO UPDATE SET "
+ "payload=excluded.payload, fetched_at=excluded.fetched_at, expires_at=excluded.expires_at",
+ (key, serialized, now, now + ttl),
+ )
+ await self._prune(db, self.max_entries, self.max_age_seconds)
+
+ async def clear_cache(self) -> None:
+ async with self._transaction() as db:
+ await db.execute("DELETE FROM cache")
+
+ async def _prune(self, db: aiosqlite.Connection, maximum: int, max_age: float) -> int:
+ async with db.execute("DELETE FROM cache WHERE fetched_at <= ?", (self._clock() - max_age,)) as cursor:
+ removed = cursor.rowcount
+ async with db.execute(
+ "DELETE FROM cache WHERE cache_key IN (SELECT cache_key FROM cache "
+ "ORDER BY fetched_at DESC, cache_key ASC LIMIT -1 OFFSET ?)", (maximum,)
+ ) as cursor:
+ return removed + cursor.rowcount
+
+ async def prune_cache(self, max_entries: int | None = None, max_age_seconds: float | None = None) -> int:
+ """Use constructor bounds unless overridden; never touch bindings."""
+ max_entries = self.max_entries if max_entries is None else max_entries
+ max_age_seconds = self.max_age_seconds if max_age_seconds is None else max_age_seconds
+ if (type(max_entries) is not int or max_entries < 0
+ or not math.isfinite(max_age_seconds) or max_age_seconds < 0):
+ raise ValueError("缓存容量和最长保留时间须为非负有限数值。")
+ async with self._transaction() as db:
+ removed = await self._prune(db, max_entries, max_age_seconds)
+ return removed
+
+ async def cache_count(self) -> int:
+ async with self._lock:
+ async with self._connection().execute("SELECT COUNT(*) FROM cache") as cursor:
+ row = await cursor.fetchone()
+ return int(row[0])
+
+ async def _quota_usage(self, db: aiosqlite.Connection, day: str, actor: QuotaActor | None) -> dict:
+ usage = {"day": day, "global": 0, "user": 0 if actor else None,
+ "group": 0 if actor and actor.group else None}
+ platform, user, group = (actor.platform, actor.user, actor.group) if actor else ("", "", "")
+ async with db.execute(
+ "SELECT scope, used FROM request_quotas WHERE day = ? AND ("
+ "(scope = 'global' AND platform = '' AND subject = '') OR "
+ "(scope = 'user' AND platform = ? AND subject = ?) OR "
+ "(scope = 'group' AND platform = ? AND subject = ?))",
+ (day, platform, user, platform, group),
+ ) as cursor:
+ for scope, used in await cursor.fetchall():
+ usage[scope] = int(used)
+ return usage
+
+ async def quota_usage(self, actor: QuotaActor | None = None) -> dict:
+ """Read today's committed usage in a single snapshot; never reset it."""
+ async with self._lock:
+ return await self._quota_usage(self._connection(), quota_day(self._clock()), actor)
+
+ async def consume_request(
+ self, actor: QuotaActor | None = None, *, user_limit: int = 20, group_limit: int = 100,
+ ready: Callable[[], bool] | None = None,
+ ) -> dict:
+ """Reserve one request atomically across all applicable daily buckets.
+
+ The global limit is fixed. Zero disables only the user/group limit,
+ never their accounting. No credentials or data-source namespace enter
+ these keys. Cancellation/errors before commit roll back every bucket.
+ """
+ if any(type(value) is not int or value < 0 for value in (user_limit, group_limit)):
+ raise ValueError("用户和群每日额度必须为非负整数,0 表示不限。")
+ async with self._transaction() as db:
+ if ready is not None and not ready():
+ raise AdmissionDeferred
+ # Evaluate the date AFTER obtaining the cross-connection write lock:
+ # a queued request can cross Beijing midnight.
+ day = quota_day(self._clock())
+ usage = await self._quota_usage(db, day, actor)
+ for scope, limit in (("global", GLOBAL_DAILY_LIMIT), ("user", user_limit),
+ ("group", group_limit)):
+ if usage[scope] is not None and limit and usage[scope] >= limit:
+ raise QuotaExceededError(scope, limit, usage[scope])
+ buckets = [(day, "global", "", "")]
+ if actor is not None:
+ buckets.append((day, "user", actor.platform, actor.user))
+ if actor.group:
+ buckets.append((day, "group", actor.platform, actor.group))
+ async with db.executemany(
+ "INSERT INTO request_quotas (day, scope, platform, subject, used) "
+ "VALUES (?, ?, ?, ?, 1) ON CONFLICT(day, scope, platform, subject) "
+ "DO UPDATE SET used = request_quotas.used + 1", buckets,
+ ):
+ pass
+ # Check again after SQLite awaits, while the write is uncommitted.
+ # Defer outside the transaction rather than waiting after charging.
+ if quota_day(self._clock()) != day or (ready is not None and not ready()):
+ raise AdmissionDeferred
+ for scope in ("global", "user", "group"):
+ if usage[scope] is not None:
+ usage[scope] += 1
+ return usage
diff --git a/templates/_macros.html b/templates/_macros.html
new file mode 100644
index 0000000..ec8827a
--- /dev/null
+++ b/templates/_macros.html
@@ -0,0 +1,9 @@
+{% macro exchange(metrics) %}
+
+ {% for metric in metrics %}
+
{{ metric.label }}
{{ metric.value }}{% if metric.unit %}{{ metric.unit }}{% endif %}
+ {% endfor %}
+
+{% endmacro %}
+
+{% macro outcome(value) %}{{ value.label }}{% endmacro %}
diff --git a/templates/base.html b/templates/base.html
new file mode 100644
index 0000000..1641a91
--- /dev/null
+++ b/templates/base.html
@@ -0,0 +1,135 @@
+
+
+
+
+
+
+ 断箭战报 · {{ view.title }}
+
+
+
+
+ 断箭战报{{ view.title }}
+ {% if view.synthetic %}合成样本 · 非真实玩家战绩
{% endif %}
+
+ {% if view.pagination %}{% endif %}
+ {% if view.metrics %}
+
+ {% for metric in view.metrics %}
+
+
{{ metric.label }}
+
{{ metric.value }}{% if metric.unit %}{{ metric.unit }}{% endif %}
+ {% if metric.note %}
{{ metric.note }}
{% endif %}
+
+ {% endfor %}
+
+ {% elif view.kind == 'overview' %}统计指标:暂无
{% endif %}
+ {% block content %}{% endblock %}
+ {% if view.notes %}{% for note in view.notes %}- {{ note }}
{% endfor %}
{% endif %}
+
+
+
+
diff --git a/templates/match.html b/templates/match.html
new file mode 100644
index 0000000..871a0e6
--- /dev/null
+++ b/templates/match.html
@@ -0,0 +1,30 @@
+{% extends "base.html" %}
+{% from "_macros.html" import exchange, outcome %}
+{% block identity %}
+ {{ view.match.map_name }}
+ 对局 ID:{{ view.match.id }}
+ {% if view.player.id != '暂无' %}{{ view.player.name }} · 玩家 ID:{{ view.player.id }}
{% endif %}
+{% endblock %}
+{% block content %}
+
+{% for team in view.teams %}
+
+ {{ team.name }}{{ team.players | length }} 人
{{ outcome(team.outcome) }}
+ {% if team.players %}
+
+ {% for player in team.players %}
+ -
+
{{ player.name }}
玩家 ID:{{ player.id }}
+ {{ exchange(player.metrics) }}
+
+ {% endfor %}
+
+ {% else %}队员:暂无
{% endif %}
+
+{% else %}分队与玩家:暂无
{% endfor %}
+{% endblock %}
diff --git a/templates/overview.html b/templates/overview.html
new file mode 100644
index 0000000..a5daa6b
--- /dev/null
+++ b/templates/overview.html
@@ -0,0 +1,13 @@
+{% extends "base.html" %}
+{% block content %}
+
+ 常用单位 / 兵种
+ {% if view.common_units %}
+
+ {% for unit in view.common_units %}
+ - {{ unit.name }}{{ unit.count }}{% if unit.count != '暂无' %} 个{% endif %}
+ {% endfor %}
+
+ {% else %}暂无
{% endif %}
+
+{% endblock %}
diff --git a/templates/recent.html b/templates/recent.html
new file mode 100644
index 0000000..7d4eab0
--- /dev/null
+++ b/templates/recent.html
@@ -0,0 +1,16 @@
+{% extends "base.html" %}
+{% from "_macros.html" import exchange, outcome %}
+{% block content %}
+{% if view.rows %}
+
+ {% for row in view.rows %}
+ -
+
{{ row.map_name }}
{{ outcome(row.outcome) }}
+ 时间:{{ row.started_at }}模式:{{ row.mode }}时长:{{ row.duration }}ELO 变化:{{ row.elo_delta }}
+ {{ exchange(row.exchange) }}
+ 对局 ID:{{ row.id }}{% if row.source_url %} · 对局来源:{{ row.source_url }}{% endif %}
+
+ {% endfor %}
+
+{% else %}近期对局:暂无
{% endif %}
+{% endblock %}
diff --git a/tests/test_client.py b/tests/test_client.py
new file mode 100644
index 0000000..e4054d7
--- /dev/null
+++ b/tests/test_client.py
@@ -0,0 +1,704 @@
+"""SYNTHETIC fixtures and httpx.MockTransport only; no live BATrace requests."""
+
+import asyncio
+from dataclasses import replace
+from datetime import datetime, timezone
+import time
+
+import httpx
+import pytest
+
+import client as client_module
+from client import (
+ AuthenticationError, BatraceClient, ClientClosedError, ClientConfig,
+ IdentityMismatchError, NoDataError, NotConfiguredError, QueueFullError,
+ RateLimitError, RequestTimeoutError, SchemaError, UpstreamError,
+)
+from storage import Storage
+from quota import GLOBAL_DAILY_LIMIT, QuotaActor, QuotaExceededError
+
+
+def config(**kwargs):
+ defaults = dict(enabled=True, base_url="https://synthetic.example.invalid",
+ client_id="synthetic-ba-stats", request_interval=0, retries=0,
+ request_timeout=0.2, wait_timeout=1)
+ defaults.update(kwargs)
+ return ClientConfig(**defaults)
+
+
+def search_payload(id="001", name="Synthetic Player"):
+ return {"players": [{"id": id, "name": name}]}
+
+
+def match_payload(*, complete=True, ended=None):
+ ended = time.time() - 1000 if ended is None else ended
+ player = {"Id": "001", "Name": "Synthetic", "OldRating": 1000, "NewRating": 1010}
+ if complete:
+ player["UnitData"] = {}
+ return {"matchInfo": {"StartTime": ended - 600, "EndTime": ended,
+ "TotalPlayTimeInSec": 600, "Data": {"a": player}}}
+
+
+class MemoryStorage:
+ """Small test double implementing the real retained-cache contract."""
+ def __init__(self):
+ self.entries = {}
+ self.ttls = []
+ self.requests = 0
+
+ async def consume_request(self, actor=None, *, user_limit=20, group_limit=100, ready=None):
+ assert actor is None # Identified quota tests use real temporary SQLite.
+ if ready is not None and not ready():
+ from quota import AdmissionDeferred
+ raise AdmissionDeferred
+ if self.requests >= GLOBAL_DAILY_LIMIT:
+ raise QuotaExceededError("global", GLOBAL_DAILY_LIMIT, self.requests)
+ self.requests += 1
+
+ async def quota_usage(self, actor=None):
+ assert actor is None
+ return {"global": self.requests, "user": None, "group": None}
+
+ async def get_cache(self, key):
+ return self.entries.get(key)
+
+ async def put_cache(self, key, payload, ttl):
+ now = time.time()
+ self.entries[key] = (payload, now, now + ttl)
+ self.ttls.append(ttl)
+
+ async def clear_cache(self):
+ self.entries.clear()
+
+ async def prune_cache(self, max_entries=1000, max_age_seconds=604800):
+ keys = sorted(self.entries, key=lambda k: self.entries[k][1], reverse=True)
+ for key in keys[max_entries:]:
+ self.entries.pop(key)
+ for key, (_, fetched, _) in list(self.entries.items()):
+ if time.time() - fetched >= max_age_seconds:
+ self.entries.pop(key)
+
+ async def cache_count(self):
+ return len(self.entries)
+
+ def expire(self, age=700):
+ now = time.time()
+ for key, (payload, _, _) in list(self.entries.items()):
+ self.entries[key] = (payload, now - age, now - 1)
+
+
+@pytest.mark.asyncio
+async def test_disabled_access_never_touches_http_or_cache():
+ calls = []
+ def handler(request):
+ calls.append(request)
+ raise AssertionError("disabled path reached transport")
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(http_client=http)
+ for operation in (lambda: client.search("Synthetic"), lambda: client.player("001"),
+ lambda: client.recent("001"), lambda: client.match("42")):
+ with pytest.raises(NotConfiguredError):
+ await operation()
+ await client.close()
+ assert calls == []
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("changes", [
+ {"client_id": ""}, {"client_id": "ba-dragon-app"}, {"client_id": "ba-dragon-collector"},
+ {"base_url": "http://synthetic.invalid"}, {"base_url": "https://name:secret@synthetic.invalid"},
+ {"base_url": "https://synthetic.invalid/?secret=1"}, {"client_id": "test\r\nX: bad"},
+])
+async def test_invalid_or_impersonated_access_fails_closed(changes):
+ client = BatraceClient(config(**changes))
+ with pytest.raises(NotConfiguredError):
+ await client.search("Synthetic")
+ assert client.status()["requests"] == 0
+ await client.close()
+
+
+def test_binding_namespace_survives_credentials_and_tracks_source():
+ a = BatraceClient(config(api_token="first"))
+ b = BatraceClient(config(client_id="rotated", api_token="second"))
+ c = BatraceClient(config(base_url="https://different.example.invalid"))
+ assert a.namespace == b.namespace != c.namespace
+ assert a._namespace != b._namespace
+ status = str(a.status())
+ assert "first" not in status and "synthetic.example" not in status
+ assert "first" not in repr(a.config)
+
+
+@pytest.mark.asyncio
+async def test_paths_query_encoding_and_plugin_identity():
+ requests = []
+ def handler(request):
+ requests.append(request)
+ return httpx.Response(200, json=search_payload())
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(api_token="synthetic-token"), http_client=http)
+ result = await client.search('Player 2 & "中文"')
+ assert result.data[0].id == "001"
+ assert result.fetched_at.tzinfo == timezone.utc
+ assert not result.stale
+ request = requests[0]
+ assert request.url.path == "/api/players/search"
+ assert dict(request.url.params) == {"q": 'Player 2 & "中文"', "limit": "20"}
+ assert request.headers["X-Client"] == "synthetic-ba-stats"
+ assert request.headers["User-Agent"] == "astrbot-plugin-ba-stats"
+ assert request.headers["Authorization"] == "Bearer synthetic-token"
+ assert request.extensions["timeout"]["read"] == 0.2
+ await client.close()
+ assert not http.is_closed
+
+
+@pytest.mark.asyncio
+async def test_player_echo_verification_and_latest_elo():
+ requests = []
+ pid = "00098765432109876543210987654321"
+ def handler(request):
+ requests.append(request)
+ if request.url.path.endswith("search"):
+ return httpx.Response(200, json=search_payload(pid))
+ assert request.url.path == "/api/analysis/player"
+ assert request.url.params["stbid"] == pid
+ return httpx.Response(200, json={"trend": {"points": [
+ {"ratingAfter": 1100, "endTime": 1700000600},
+ {"ratingAfter": 900, "endTime": 1700000000},
+ ]}})
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(), http_client=http)
+ result = await client.player(pid)
+ assert result.data.id == pid and result.data.elo == 1100
+ assert result.data.steam_id is None
+ assert len(requests) == 2
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_identity_mismatch_is_not_a_fallback_or_a_new_binding():
+ calls = []
+ def handler(request):
+ calls.append(request)
+ return httpx.Response(200, json=search_payload("somebody-else"))
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(), http_client=http)
+ with pytest.raises(IdentityMismatchError):
+ await client.player("001")
+ assert len(calls) == 1 # never continue analysis with the wrong identity
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_recent_identity_limit_and_actual_request_parameters():
+ seen = []
+ def handler(request):
+ seen.append(dict(request.url.params))
+ return httpx.Response(200, json={"matches": [
+ {"matchId": "42", "data": match_payload()["matchInfo"]},
+ ]})
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(), http_client=http)
+ assert (await client.recent("001", 7)).data[0].id == "42"
+ assert seen[0] == {"stbid": "001", "limit": "7"}
+ with pytest.raises(IdentityMismatchError):
+ await client.recent("002", 7)
+ for limit in (0, 21, True, 1.5):
+ with pytest.raises(ValueError):
+ await client.recent("001", limit)
+ await client.close()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("player_id", [None, "999"])
+async def test_recent_empty_roster_is_unknown_but_foreign_roster_cannot_use_old_cache(player_id):
+ store = MemoryStorage()
+ payload = {"matches": [{"matchId": "42", "data": match_payload()["matchInfo"]}]}
+ async with httpx.AsyncClient(transport=httpx.MockTransport(
+ lambda request: httpx.Response(200, json=payload)
+ )) as http:
+ client = BatraceClient(config(), storage=store, http_client=http)
+ try:
+ await client.recent("001")
+ store.expire()
+ payload = {"matches": [{"matchId": "42", "data": {
+ "Data": {} if player_id is None else {"a": {"Id": player_id}}
+ }}]}
+ if player_id is None:
+ result = await client.recent("001")
+ assert result.data[0].players == []
+ assert not result.stale
+ else:
+ with pytest.raises(IdentityMismatchError, match="未参与") as error:
+ await client.recent("001")
+ assert error.value.code == "identity_mismatch"
+ assert client.status()["stale_hits"] == 0
+ finally:
+ await client.close()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("status,error", [
+ (401, AuthenticationError), (403, AuthenticationError), (404, NoDataError),
+ (429, RateLimitError), (500, UpstreamError), (503, UpstreamError),
+])
+async def test_http_failures_remain_distinct_without_unlimited_retries(status, error):
+ calls = []
+ def handler(request):
+ calls.append(request)
+ return httpx.Response(status, json={"error": "SYNTHETIC secret, never display"})
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(), http_client=http)
+ with pytest.raises(error) as caught:
+ await client.search("Synthetic")
+ assert "secret" not in str(caught.value)
+ assert len(calls) == 1
+ assert client.status()["inflight"] == 0
+ await client.close()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("status,body,content_type,error", [
+ (200, "{}", "application/json", SchemaError),
+ (200, "not json", "application/json", SchemaError),
+ (404, "missing page
", "text/html", SchemaError),
+ (200, "Security Verification", "text/html", AuthenticationError),
+ (503, "EO-Bot-Captcha-Token", "text/html", AuthenticationError),
+ (200, "maintenance
", "text/html", SchemaError),
+])
+async def test_schema_changes_and_captcha_never_become_empty_results(status, body, content_type, error):
+ calls = []
+ def handler(request):
+ calls.append(request)
+ return httpx.Response(status, text=body, headers={"Content-Type": content_type})
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(retries=1), http_client=http)
+ with pytest.raises(error):
+ await client.search("Synthetic")
+ assert len(calls) == 1
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_retry_after_zero_retries_once_and_recovers():
+ calls = 0
+ def handler(request):
+ nonlocal calls
+ calls += 1
+ if calls == 1:
+ return httpx.Response(429, json={}, headers={"Retry-After": "0"})
+ return httpx.Response(200, json=search_payload())
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(retries=1), http_client=http)
+ assert (await client.search("Synthetic")).data[0].id == "001"
+ assert calls == 2
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_exhausted_retries_stop_after_configured_attempt_count():
+ calls = 0
+ def handler(request):
+ nonlocal calls
+ calls += 1
+ return httpx.Response(429, json={}, headers={"Retry-After": "0"})
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(retries=1), http_client=http)
+ with pytest.raises(RateLimitError):
+ await client.search("Synthetic")
+ assert calls == 2
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_long_retry_after_is_preserved_across_next_query():
+ calls = 0
+ def handler(request):
+ nonlocal calls
+ calls += 1
+ return httpx.Response(429, json={}, headers={"Retry-After": "120"})
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(retries=1, wait_timeout=0.03), http_client=http)
+ with pytest.raises(RateLimitError) as caught:
+ await client.search("Synthetic A")
+ assert caught.value.retry_after == 120
+ with pytest.raises(RequestTimeoutError):
+ await client.search("Synthetic B")
+ assert calls == 1
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_retry_wait_is_part_of_overall_deadline():
+ calls = 0
+ def handler(request):
+ nonlocal calls
+ calls += 1
+ return httpx.Response(503, json={})
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(retries=1, wait_timeout=0.03), http_client=http)
+ start = time.monotonic()
+ with pytest.raises(RequestTimeoutError):
+ await client.search("Synthetic")
+ assert time.monotonic() - start < 0.5 and calls == 1
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_cache_hit_force_refresh_and_new_client_persistence(tmp_path):
+ calls = 0
+ def handler(request):
+ nonlocal calls
+ calls += 1
+ return httpx.Response(200, json=search_payload(name=f"Synthetic {calls}"))
+ store = Storage(tmp_path / "data")
+ await store.open()
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ first = BatraceClient(config(), storage=store, http_client=http)
+ original = await first.search("Synthetic")
+ cached = await first.search("Synthetic")
+ assert calls == 1 and cached.data == original.data
+ assert not cached.stale
+ await first.close()
+ await store.close()
+ store = Storage(tmp_path / "data")
+ await store.open()
+ second = BatraceClient(config(), storage=store, http_client=http)
+ assert (await second.search("Synthetic")).data[0].name == "Synthetic 1"
+ assert calls == 1
+ assert (await second.search("Synthetic", force=True)).data[0].name == "Synthetic 2"
+ assert calls == 2
+ await second.close()
+ await store.close()
+
+
+@pytest.mark.asyncio
+async def test_stale_fallback_preserves_original_fetch_time_and_marks_reason():
+ fail = False
+ def handler(request):
+ return httpx.Response(503, json={}) if fail else httpx.Response(200, json=search_payload())
+ store = MemoryStorage()
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(), storage=store, http_client=http)
+ await client.search("Synthetic")
+ store.expire()
+ fetched = next(iter(store.entries.values()))[1]
+ fail = True
+ result = await client.search("Synthetic")
+ assert result.stale and result.stale_reason == "upstream"
+ assert result.fetched_at.timestamp() == pytest.approx(fetched, abs=0.000001, rel=0)
+ assert client.status()["stale_hits"] == 1
+ await client.close()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("status,payload,error", [
+ (401, {}, AuthenticationError), (404, {}, NoDataError), (200, {}, SchemaError),
+])
+async def test_nontransient_failures_never_hide_behind_stale_cache(status, payload, error):
+ fail = False
+ def handler(request):
+ return httpx.Response(status, json=payload) if fail else httpx.Response(200, json=search_payload())
+ store = MemoryStorage()
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(), storage=store, http_client=http)
+ await client.search("Synthetic")
+ store.expire()
+ fail = True
+ with pytest.raises(error):
+ await client.search("Synthetic")
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_stale_retention_limit_is_enforced():
+ fail = False
+ def handler(request):
+ if fail:
+ raise httpx.ConnectError("SYNTHETIC", request=request)
+ return httpx.Response(200, json=search_payload())
+ store = MemoryStorage()
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(stale_hours=1), storage=store, http_client=http)
+ await client.search("Synthetic")
+ store.expire(age=3601)
+ fail = True
+ with pytest.raises(UpstreamError):
+ await client.search("Synthetic")
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_identical_concurrent_misses_make_one_request():
+ entered, release = asyncio.Event(), asyncio.Event()
+ calls = 0
+ async def handler(request):
+ nonlocal calls
+ calls += 1
+ entered.set()
+ await release.wait()
+ return httpx.Response(200, json=search_payload())
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(queue_size=0, concurrency=1), http_client=http)
+ tasks = [asyncio.create_task(client.search("Synthetic")) for _ in range(20)]
+ await entered.wait()
+ assert client.status()["inflight"] == 1 and calls == 1
+ release.set()
+ results = await asyncio.gather(*tasks)
+ assert all(r.data[0].id == "001" for r in results)
+ assert client.status()["inflight"] == 0
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_queue_is_bounded_but_existing_request_can_join():
+ entered, release = asyncio.Event(), asyncio.Event()
+ calls = 0
+ async def handler(request):
+ nonlocal calls
+ calls += 1
+ entered.set()
+ await release.wait()
+ return httpx.Response(200, json=search_payload())
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(concurrency=1, queue_size=1), http_client=http)
+ a = asyncio.create_task(client.search("A"))
+ await entered.wait()
+ b = asyncio.create_task(client.search("B"))
+ await asyncio.sleep(0)
+ with pytest.raises(QueueFullError):
+ await client.search("C")
+ joined = asyncio.create_task(client.search("A"))
+ release.set()
+ await asyncio.gather(a, b, joined)
+ assert calls == 2
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_global_request_spacing_and_max_concurrency():
+ starts, active, peak = [], 0, 0
+ async def handler(request):
+ nonlocal active, peak
+ starts.append(time.monotonic())
+ active += 1
+ peak = max(active, peak)
+ await asyncio.sleep(0.2)
+ active -= 1
+ return httpx.Response(200, json=search_payload())
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(concurrency=2, request_interval=0.08), http_client=http)
+ await asyncio.gather(*(client.search(str(i)) for i in range(4)))
+ assert peak == 2
+ assert all(b - a >= 0.07 for a, b in zip(starts, starts[1:]))
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_queue_wait_and_transport_wait_share_one_deadline():
+ calls = 0
+ async def handler(request):
+ nonlocal calls
+ calls += 1
+ await asyncio.Event().wait()
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(concurrency=1, wait_timeout=0.03), http_client=http)
+ results = await asyncio.gather(client.search("A"), client.search("B"), return_exceptions=True)
+ assert all(isinstance(r, RequestTimeoutError) for r in results)
+ assert calls == 1
+ assert client.status()["inflight"] == 0
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_cancelled_waiter_does_not_cancel_another_joined_waiter():
+ entered, release = asyncio.Event(), asyncio.Event()
+ async def handler(request):
+ entered.set()
+ await release.wait()
+ return httpx.Response(200, json=search_payload())
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(), http_client=http)
+ a = asyncio.create_task(client.search("Synthetic"))
+ await entered.wait()
+ b = asyncio.create_task(client.search("Synthetic"))
+ await asyncio.sleep(0)
+ a.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await a
+ release.set()
+ assert (await b).data[0].id == "001"
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_last_waiter_cancel_releases_request_and_allows_recovery():
+ entered, stopped = asyncio.Event(), asyncio.Event()
+ calls = 0
+ async def handler(request):
+ nonlocal calls
+ calls += 1
+ if calls == 1:
+ entered.set()
+ try:
+ await asyncio.Event().wait()
+ finally:
+ stopped.set()
+ return httpx.Response(200, json=search_payload())
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(), http_client=http)
+ task = asyncio.create_task(client.search("Synthetic"))
+ await entered.wait()
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ assert stopped.is_set() and client.status()["inflight"] == 0
+ assert (await client.search("Synthetic")).data[0].id == "001"
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_close_cancels_and_awaits_active_and_queued_work():
+ entered, stopped = asyncio.Event(), asyncio.Event()
+ async def handler(request):
+ entered.set()
+ try:
+ await asyncio.Event().wait()
+ finally:
+ stopped.set()
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(concurrency=1), http_client=http)
+ a = asyncio.create_task(client.search("A"))
+ await entered.wait()
+ b = asyncio.create_task(client.search("B"))
+ await asyncio.sleep(0)
+ await client.close()
+ results = await asyncio.gather(a, b, return_exceptions=True)
+ assert all(isinstance(r, ClientClosedError) for r in results)
+ assert stopped.is_set() and client.status()["inflight"] == 0
+ with pytest.raises(ClientClosedError):
+ await client.search("C")
+ await client.close()
+ assert not http.is_closed
+
+
+@pytest.mark.asyncio
+async def test_owned_http_client_is_closed(monkeypatch):
+ http = httpx.AsyncClient(transport=httpx.MockTransport(lambda r: httpx.Response(200, json=search_payload())))
+ monkeypatch.setattr(client_module.httpx, "AsyncClient", lambda: http)
+ client = BatraceClient(config())
+ await client.search("Synthetic")
+ await client.close()
+ assert http.is_closed
+
+
+@pytest.mark.asyncio
+async def test_cache_capacity_and_clear_during_refresh():
+ entered, release = asyncio.Event(), asyncio.Event()
+ async def handler(request):
+ if request.url.params["q"] == "slow":
+ entered.set()
+ await release.wait()
+ return httpx.Response(200, json=search_payload())
+ store = MemoryStorage()
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(cache_max_entries=2), storage=store, http_client=http)
+ for q in ("A", "B", "C"):
+ await client.search(q)
+ assert await store.cache_count() == 2
+ task = asyncio.create_task(client.search("slow"))
+ await entered.wait()
+ await client.clear_cache()
+ release.set()
+ await task
+ assert await store.cache_count() == 0
+ await client.close()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("complete,ended,ttl", [
+ (True, None, 86400), (False, None, 60), (True, "now", 60),
+])
+async def test_complete_old_match_cache_is_long_but_fresh_or_partial_is_short(complete, ended, ttl):
+ payload = match_payload(complete=complete, ended=(time.time() if ended == "now" else ended))
+ def handler(request):
+ assert request.url.path == "/api/match" and request.url.params["matchid"] == "42"
+ return httpx.Response(200, json=payload)
+ store = MemoryStorage()
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(), storage=store, http_client=http)
+ assert (await client.match("42")).data.id == "42"
+ assert store.ttls[-1] == ttl
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_failed_request_does_not_leave_permanent_inflight_and_can_recover():
+ calls = 0
+ def handler(request):
+ nonlocal calls
+ calls += 1
+ if calls == 1:
+ raise httpx.ReadTimeout("SYNTHETIC", request=request)
+ return httpx.Response(200, json=search_payload())
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(), http_client=http)
+ with pytest.raises(RequestTimeoutError):
+ await client.search("Synthetic")
+ assert (await client.search("Synthetic")).data[0].id == "001"
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_force_joining_fresh_cache_lookup_promotes_it_to_real_revalidation():
+ class DelayedCache(MemoryStorage):
+ delay = False
+ entered = asyncio.Event()
+ release = asyncio.Event()
+
+ async def get_cache(self, key):
+ if self.delay:
+ self.entered.set()
+ await self.release.wait()
+ return await super().get_cache(key)
+
+ calls = 0
+ def handler(request):
+ nonlocal calls
+ calls += 1
+ return httpx.Response(200, json=search_payload(name=f"Synthetic {calls}"))
+ store = DelayedCache()
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(), storage=store, http_client=http)
+ await client.search("Synthetic")
+ store.delay = True
+ normal = asyncio.create_task(client.search("Synthetic"))
+ await store.entered.wait()
+ forced = asyncio.create_task(client.search("Synthetic", force=True))
+ await asyncio.sleep(0)
+ store.release.set()
+ results = await asyncio.gather(normal, forced)
+ assert calls == 2 # exactly one initial request plus one promoted refresh
+ assert all(r.data[0].name == "Synthetic 2" and not r.stale for r in results)
+ await client.close()
+
+
+@pytest.mark.asyncio
+async def test_force_joining_active_upstream_still_makes_one_request():
+ entered, release = asyncio.Event(), asyncio.Event()
+ calls = 0
+ async def handler(request):
+ nonlocal calls
+ calls += 1
+ entered.set()
+ await release.wait()
+ return httpx.Response(200, json=search_payload())
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(config(), http_client=http)
+ normal = asyncio.create_task(client.search("Synthetic"))
+ await entered.wait()
+ forced = asyncio.create_task(client.search("Synthetic", force=True))
+ await asyncio.sleep(0)
+ release.set()
+ await asyncio.gather(normal, forced)
+ assert calls == 1
+ await client.close()
diff --git a/tests/test_client_quota.py b/tests/test_client_quota.py
new file mode 100644
index 0000000..538ec8c
--- /dev/null
+++ b/tests/test_client_quota.py
@@ -0,0 +1,613 @@
+"""Client quota behavior using temporary SQLite and SYNTHETIC MockTransport data.
+
+No BATrace endpoint or real account is contacted. Storage atomicity and Beijing
+midnight rollover have their own storage tests and are not duplicated here.
+"""
+
+import asyncio
+from contextlib import asynccontextmanager
+from datetime import datetime
+
+import httpx
+import pytest
+
+import client as client_module
+
+from client import (
+ AuthenticationError, BatraceClient, ClientConfig, NoDataError,
+ RateLimitError, RequestTimeoutError, SchemaError, UpstreamError,
+)
+from quota import QuotaActor, QuotaExceededError
+from quota import quota_day
+from storage import Storage
+
+
+def configuration(**overrides):
+ values = dict(enabled=True, base_url="https://synthetic.example.invalid",
+ client_id="synthetic-quota-client", request_interval=0,
+ retries=0, wait_timeout=5, request_timeout=1)
+ values.update(overrides)
+ return ClientConfig(**values)
+
+
+def response():
+ return httpx.Response(200, json={"players": [{"id": "001", "name": "Synthetic"}]})
+
+
+@asynccontextmanager
+async def running_client(tmp_path, handler, **overrides):
+ storage = Storage(tmp_path / "plugin-data")
+ await storage.open()
+ try:
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = BatraceClient(configuration(**overrides), storage=storage, http_client=http)
+ try:
+ yield client, storage
+ finally:
+ await client.close()
+ finally:
+ await storage.close()
+
+
+async def search(client, actor, query, *, force=False):
+ with client.request_scope(actor):
+ return await client.search(query, force=force)
+
+
+async def counts(storage, actor):
+ usage = await storage.quota_usage(actor)
+ return usage["global"], usage["user"], usage["group"]
+
+
+def assert_quota(error, scope, limit, used):
+ assert isinstance(error, QuotaExceededError)
+ assert (error.code, error.scope, error.limit, error.used) == ("daily_quota", scope, limit, used)
+
+
+def expire_cache_reads(monkeypatch, storage):
+ """Expose retained data as one hour older, without changing daily quota time."""
+ original = storage.get_cache
+
+ async def expired(key):
+ hit = await original(key)
+ if hit is None:
+ return None
+ payload, fetched_at, expires_at = hit
+ return payload, fetched_at - 3600, expires_at - 3600
+
+ monkeypatch.setattr(storage, "get_cache", expired)
+
+
+@pytest.mark.asyncio
+async def test_100th_and_101st_http_attempts_race_at_fixed_global_limit(tmp_path):
+ calls = []
+ def handler(request):
+ calls.append(request)
+ return response()
+
+ async with running_client(tmp_path, handler) as (client, storage):
+ # Real adapter attempts establish 99; each sender stays below default 20.
+ for i in range(99):
+ actor = QuotaActor("onebot:a", f"sender-{i // 20}", "group-A")
+ await search(client, actor, f"Synthetic {i}", force=True)
+ actor = QuotaActor("onebot:a", "last-sender", "group-A")
+ results = await asyncio.gather(
+ search(client, actor, "Boundary A", force=True),
+ search(client, actor, "Boundary B", force=True),
+ return_exceptions=True,
+ )
+ errors = [r for r in results if isinstance(r, BaseException)]
+ assert len(errors) == 1
+ assert_quota(errors[0], "global", 100, 100)
+ assert len(calls) == client.status()["requests"] == 100
+ assert await counts(storage, actor) == (100, 1, 100)
+ # Even a different user/group cannot bypass the fixed plugin-wide cap.
+ other = QuotaActor("onebot:b", "another", "group-B")
+ with pytest.raises(QuotaExceededError) as denied:
+ await search(client, other, "Other source caller", force=True)
+ assert_quota(denied.value, "global", 100, 100)
+ assert await counts(storage, other) == (100, 0, 0)
+
+
+@pytest.mark.asyncio
+async def test_default_user_20_counts_across_groups_and_private_chat(tmp_path):
+ calls = []
+ def handler(request):
+ calls.append(request)
+ return response()
+
+ async with running_client(tmp_path, handler) as (client, storage):
+ actors = [QuotaActor("onebot:a", "same-user", group) for group in ("A", "B", "")]
+ for i in range(20):
+ await search(client, actors[i % 3], f"Synthetic {i}", force=True)
+ for actor in actors:
+ with pytest.raises(QuotaExceededError) as denied:
+ await search(client, actor, "Beyond personal limit", force=True)
+ assert_quota(denied.value, "user", 20, 20)
+ assert await counts(storage, actors[0]) == (20, 20, 7)
+ assert await counts(storage, actors[1]) == (20, 20, 7)
+ assert await counts(storage, actors[2]) == (20, 20, None)
+ other = QuotaActor("onebot:a", "other-user", "A")
+ await search(client, other, "Other user", force=True)
+ assert await counts(storage, other) == (21, 1, 8)
+ assert len(calls) == 21
+
+
+@pytest.mark.asyncio
+async def test_configured_group_limit_applies_to_all_senders_but_not_private_chat(tmp_path):
+ async with running_client(tmp_path, lambda r: response(), group_daily_limit=2) as (client, storage):
+ a = QuotaActor("onebot:a", "A", "limited-group")
+ b = QuotaActor("onebot:a", "B", "limited-group")
+ c = QuotaActor("onebot:a", "C", "limited-group")
+ await search(client, a, "First", force=True)
+ await search(client, b, "Second", force=True)
+ with pytest.raises(QuotaExceededError) as denied:
+ await search(client, c, "Third", force=True)
+ assert_quota(denied.value, "group", 2, 2)
+ assert await counts(storage, c) == (2, 0, 2)
+ private = QuotaActor("onebot:a", "C")
+ await search(client, private, "Private", force=True)
+ assert await counts(storage, private) == (3, 1, None)
+
+
+@pytest.mark.asyncio
+async def test_fresh_cache_costs_zero_at_limit_force_and_expired_cache_are_denied(tmp_path, monkeypatch):
+ calls = []
+ def handler(request):
+ calls.append(request)
+ return response()
+
+ async with running_client(tmp_path, handler, user_daily_limit=1) as (client, storage):
+ actor = QuotaActor("onebot:a", "A", "G")
+ await search(client, actor, "Synthetic")
+ assert not (await search(client, actor, "Synthetic")).stale
+ with pytest.raises(QuotaExceededError) as denied:
+ await search(client, actor, "Synthetic", force=True)
+ assert_quota(denied.value, "user", 1, 1)
+ expire_cache_reads(monkeypatch, storage)
+ with pytest.raises(QuotaExceededError):
+ await search(client, actor, "Synthetic")
+ assert await counts(storage, actor) == (1, 1, 1)
+ assert len(calls) == 1
+ assert client.status()["stale_hits"] == 0
+ assert client.status()["last_error"] == "daily_quota"
+
+
+@pytest.mark.asyncio
+async def test_each_submitted_failure_counts_and_is_not_refunded(tmp_path):
+ sequence = ["auth", "no_data", "server", "timeout", "network", "schema", "rate"]
+ errors = [AuthenticationError, NoDataError, UpstreamError, RequestTimeoutError,
+ UpstreamError, SchemaError, RateLimitError]
+ calls = []
+ def handler(request):
+ kind = sequence[len(calls)]
+ calls.append(kind)
+ if kind == "timeout":
+ raise httpx.ReadTimeout("SYNTHETIC", request=request)
+ if kind == "network":
+ raise httpx.ConnectError("SYNTHETIC", request=request)
+ status = {"auth": 403, "no_data": 404, "server": 503, "schema": 200, "rate": 429}[kind]
+ return httpx.Response(status, json={}, headers={"Retry-After": "0"})
+
+ async with running_client(tmp_path, handler) as (client, storage):
+ actor = QuotaActor("onebot:a", "A", "G")
+ for i, error in enumerate(errors):
+ with pytest.raises(error):
+ await search(client, actor, f"Failure {i}")
+ assert await counts(storage, actor) == (i + 1, i + 1, i + 1)
+ assert len(calls) == client.status()["requests"] == len(errors)
+ assert await storage.cache_count() == 0
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("user_limit", [1, 2])
+async def test_retry_consumes_another_attempt_or_is_blocked_before_submission(tmp_path, user_limit):
+ calls = []
+ def handler(request):
+ calls.append(request)
+ if len(calls) == 1:
+ return httpx.Response(429, json={}, headers={"Retry-After": "0"})
+ return response()
+
+ async with running_client(tmp_path, handler, retries=1, user_daily_limit=user_limit) as (client, storage):
+ actor = QuotaActor("onebot:a", "A", "G")
+ if user_limit == 1:
+ with pytest.raises(QuotaExceededError) as denied:
+ await search(client, actor, "Synthetic")
+ assert_quota(denied.value, "user", 1, 1)
+ else:
+ assert (await search(client, actor, "Synthetic")).data[0].id == "001"
+ assert len(calls) == user_limit
+ assert await counts(storage, actor) == (user_limit,) * 3
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("user_limit", [1, 2])
+async def test_player_two_http_calls_charge_twice_or_stop_between_endpoints(tmp_path, user_limit):
+ paths = []
+ def handler(request):
+ paths.append(request.url.path)
+ if request.url.path.endswith("search"):
+ return response()
+ return httpx.Response(200, json={"matchCount": 0})
+
+ async with running_client(tmp_path, handler, user_daily_limit=user_limit) as (client, storage):
+ actor = QuotaActor("onebot:a", "A", "G")
+ with client.request_scope(actor):
+ if user_limit == 1:
+ with pytest.raises(QuotaExceededError) as denied:
+ await client.player("001", force=True)
+ assert_quota(denied.value, "user", 1, 1)
+ assert await storage.cache_count() == 0
+ else:
+ assert (await client.player("001", force=True)).data.id == "001"
+ assert (await client.player("001")).data.id == "001"
+ assert paths == ["/api/players/search", "/api/analysis/player"][:user_limit]
+ assert await counts(storage, actor) == (user_limit,) * 3
+
+
+@pytest.mark.asyncio
+async def test_same_actor_coalesces_different_callers_charge_separately_and_share_cache(tmp_path):
+ first_entered, all_entered, release = asyncio.Event(), asyncio.Event(), asyncio.Event()
+ calls = []
+ async def handler(request):
+ calls.append(request)
+ first_entered.set()
+ if len(calls) == 3:
+ all_entered.set()
+ await release.wait()
+ return response()
+
+ async with running_client(tmp_path, handler, concurrency=3) as (client, storage):
+ a = QuotaActor("onebot:a", "A", "G1")
+ a_other_group = QuotaActor("onebot:a", "A", "G2")
+ b = QuotaActor("onebot:a", "B", "G1")
+ tasks = [asyncio.create_task(search(client, a, "Same"))]
+ try:
+ await asyncio.wait_for(first_entered.wait(), 2)
+ tasks.extend([
+ asyncio.create_task(search(client, a, "Same", force=True)),
+ asyncio.create_task(search(client, a_other_group, "Same", force=True)),
+ asyncio.create_task(search(client, b, "Same", force=True)),
+ ])
+ await asyncio.wait_for(all_entered.wait(), 2)
+ assert len(calls) == 3
+ release.set()
+ results = await asyncio.gather(*tasks)
+ assert all(r.data[0].id == "001" for r in results)
+ assert await counts(storage, a) == (3, 2, 2)
+ assert await counts(storage, a_other_group) == (3, 2, 1)
+ assert await counts(storage, b) == (3, 1, 2)
+ c = QuotaActor("onebot:a", "C", "G1")
+ assert not (await search(client, c, "Same")).stale
+ assert await counts(storage, c) == (3, 0, 2)
+ assert len(calls) == 3
+ finally:
+ release.set()
+ await asyncio.gather(*tasks, return_exceptions=True)
+
+
+@pytest.mark.asyncio
+async def test_other_actor_force_cannot_join_owner_or_spend_owners_quota(tmp_path):
+ entered, release = asyncio.Event(), asyncio.Event()
+ calls = []
+ async def handler(request):
+ calls.append(request)
+ if request.url.params["q"] == "Shared":
+ entered.set()
+ await release.wait()
+ return response()
+
+ async with running_client(tmp_path, handler, user_daily_limit=1) as (client, storage):
+ owner = QuotaActor("onebot:a", "owner", "G")
+ other = QuotaActor("onebot:a", "other", "G")
+ await search(client, other, "Spend own limit")
+ task = asyncio.create_task(search(client, owner, "Shared"))
+ try:
+ await asyncio.wait_for(entered.wait(), 2)
+ with pytest.raises(QuotaExceededError) as denied:
+ await search(client, other, "Shared", force=True)
+ assert_quota(denied.value, "user", 1, 1)
+ assert len(calls) == 2
+ finally:
+ release.set()
+ await task
+ assert await counts(storage, owner) == (2, 1, 2)
+ assert await counts(storage, other) == (2, 1, 2)
+
+
+@pytest.mark.asyncio
+async def test_cancelling_queued_costs_zero_submitted_attempt_remains_charged(tmp_path):
+ entered, stopped = asyncio.Event(), asyncio.Event()
+ calls = []
+ async def handler(request):
+ calls.append(request)
+ if len(calls) == 1:
+ entered.set()
+ try:
+ await asyncio.Event().wait()
+ finally:
+ stopped.set()
+ return response()
+
+ async with running_client(tmp_path, handler, concurrency=1) as (client, storage):
+ active_actor = QuotaActor("onebot:a", "active", "G")
+ queued_actor = QuotaActor("onebot:a", "queued", "G")
+ active = asyncio.create_task(search(client, active_actor, "Active"))
+ await asyncio.wait_for(entered.wait(), 2)
+ queued = asyncio.create_task(search(client, queued_actor, "Queued"))
+ async with asyncio.timeout(2):
+ while client.status()["inflight"] < 2:
+ await asyncio.sleep(0)
+ queued.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await queued
+ assert await counts(storage, queued_actor) == (1, 0, 1)
+ active.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await active
+ assert stopped.is_set()
+ assert await counts(storage, active_actor) == (1, 1, 1)
+ await search(client, active_actor, "After cancellation", force=True)
+ assert await counts(storage, active_actor) == (2, 2, 2)
+ assert len(calls) == 2
+
+
+@pytest.mark.asyncio
+async def test_cancellation_after_durable_reservation_conservatively_keeps_count(tmp_path, monkeypatch):
+ reserved = asyncio.Event()
+ calls = []
+ def handler(request):
+ calls.append(request)
+ return response()
+
+ async with running_client(tmp_path, handler) as (client, storage):
+ consume = storage.consume_request
+ async def pause_after_commit(*args, **kwargs):
+ await consume(*args, **kwargs)
+ reserved.set()
+ await asyncio.Event().wait()
+ monkeypatch.setattr(storage, "consume_request", pause_after_commit)
+ actor = QuotaActor("onebot:a", "A", "G")
+ task = asyncio.create_task(search(client, actor, "Synthetic"))
+ await asyncio.wait_for(reserved.wait(), 2)
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ assert await counts(storage, actor) == (1, 1, 1)
+ assert calls == []
+ assert client.status()["inflight"] == 0
+
+
+@pytest.mark.asyncio
+async def test_clear_rotation_and_reopen_never_reset_any_daily_bucket(tmp_path):
+ calls = []
+ def handler(request):
+ calls.append(request)
+ return response()
+
+ actor = QuotaActor("onebot:a", "A", "G")
+ async with running_client(tmp_path, handler, user_daily_limit=2) as (first, storage):
+ await search(first, actor, "Synthetic")
+ await first.clear_cache()
+ assert await counts(storage, actor) == (1, 1, 1)
+ async with running_client(
+ tmp_path, handler, user_daily_limit=2, client_id="rotated-synthetic", api_token="rotated-token",
+ ) as (second, storage):
+ await search(second, actor, "Synthetic", force=True)
+ assert await counts(storage, actor) == (2, 2, 2)
+ async with running_client(tmp_path, handler, user_daily_limit=2) as (third, storage):
+ with pytest.raises(QuotaExceededError) as denied:
+ await search(third, actor, "Synthetic", force=True)
+ assert_quota(denied.value, "user", 2, 2)
+ assert await counts(storage, actor) == (2, 2, 2)
+ assert len(calls) == 2
+
+
+@pytest.mark.asyncio
+async def test_exhausted_actor_during_global_backoff_cannot_receive_stale(tmp_path, monkeypatch):
+ calls = []
+ def handler(request):
+ calls.append(request)
+ if request.url.params["q"] == "Trigger backoff":
+ return httpx.Response(429, json={}, headers={"Retry-After": "120"})
+ return response()
+
+ async with running_client(tmp_path, handler, user_daily_limit=1, wait_timeout=0.1) as (client, storage):
+ exhausted = QuotaActor("onebot:a", "A", "G")
+ other = QuotaActor("onebot:a", "B", "G")
+ await search(client, exhausted, "Retained")
+ expire_cache_reads(monkeypatch, storage)
+ with pytest.raises(RateLimitError):
+ await search(client, other, "Trigger backoff")
+ with pytest.raises(QuotaExceededError) as denied:
+ await search(client, exhausted, "Retained")
+ assert_quota(denied.value, "user", 1, 1)
+ assert await counts(storage, exhausted) == (2, 1, 2)
+ assert len(calls) == 2
+ assert client.status()["stale_hits"] == 0
+
+
+def test_identified_requests_require_persistent_storage():
+ client = BatraceClient(configuration())
+ with pytest.raises(RuntimeError, match="持久化"):
+ with client.request_scope(QuotaActor("onebot:a", "A")):
+ pytest.fail("actor scope must not silently fall back to local counters")
+
+
+@pytest.mark.asyncio
+async def test_cache_write_deadline_rolls_back_and_next_request_recovers(tmp_path, monkeypatch):
+ calls = []
+
+ def handler(request):
+ calls.append(request)
+ return response()
+
+ async with running_client(tmp_path, handler, wait_timeout=0.1) as (client, storage):
+ actor = QuotaActor("p", "u", "g")
+
+ async def paused_prune(*args):
+ await asyncio.Event().wait()
+
+ with monkeypatch.context() as patch:
+ patch.setattr(storage, "_prune", paused_prune)
+ with pytest.raises(RequestTimeoutError):
+ await search(client, actor, "Interrupted cache write")
+ assert not storage._connection().in_transaction
+ assert await storage.cache_count() == 0
+ assert await counts(storage, actor) == (1, 1, 1)
+ assert (await search(client, actor, "Recovery")).data[0].id == "001"
+ assert await counts(storage, actor) == (2, 2, 2)
+ assert len(calls) == 2
+
+
+@pytest.mark.asyncio
+async def test_delayed_quota_keeps_send_spacing_without_serializing_responses(tmp_path, monkeypatch):
+ interval = 0.08
+ reserving, release_quota = asyncio.Event(), asyncio.Event()
+ both_started, release_responses = asyncio.Event(), asyncio.Event()
+ starts = []
+ loop = asyncio.get_running_loop()
+
+ async def handler(request):
+ starts.append(loop.time())
+ if len(starts) == 2:
+ both_started.set()
+ await release_responses.wait()
+ return response()
+
+ async with running_client(tmp_path, handler, request_interval=interval, concurrency=2) as (client, storage):
+ consume = storage.consume_request
+
+ async def delayed_consume(*args, **kwargs):
+ reserving.set()
+ await release_quota.wait()
+ return await consume(*args, **kwargs)
+
+ monkeypatch.setattr(storage, "consume_request", delayed_consume)
+ actor = QuotaActor("p", "u", "g")
+ tasks = [asyncio.create_task(search(client, actor, query)) for query in ("First", "Second")]
+ try:
+ await asyncio.wait_for(reserving.wait(), 2)
+ await asyncio.sleep(interval * 2)
+ release_quota.set()
+ # Both HTTP calls must start while the first response is still blocked.
+ await asyncio.wait_for(both_started.wait(), 2)
+ assert starts[1] - starts[0] >= interval - 0.005
+ assert await counts(storage, actor) == (2, 2, 2)
+ finally:
+ release_quota.set()
+ release_responses.set()
+ await asyncio.gather(*tasks, return_exceptions=True)
+
+
+@pytest.mark.asyncio
+async def test_backoff_received_during_quota_wait_is_checked_before_sending(tmp_path, monkeypatch):
+ first_started, reply_first = asyncio.Event(), asyncio.Event()
+ second_reserving, release_quota = asyncio.Event(), asyncio.Event()
+ starts = []
+ loop = asyncio.get_running_loop()
+ backoff_started = None
+
+ async def handler(request):
+ nonlocal backoff_started
+ starts.append(loop.time())
+ if request.url.params["q"] == "First":
+ first_started.set()
+ await reply_first.wait()
+ backoff_started = loop.time()
+ return httpx.Response(429, json={}, headers={"Retry-After": "0.15"})
+ return response()
+
+ async with running_client(tmp_path, handler, concurrency=2) as (client, storage):
+ consume = storage.consume_request
+ reservations = 0
+
+ async def delayed_second(*args, **kwargs):
+ nonlocal reservations
+ reservations += 1
+ if reservations == 2:
+ second_reserving.set()
+ await release_quota.wait()
+ return await consume(*args, **kwargs)
+
+ monkeypatch.setattr(storage, "consume_request", delayed_second)
+ actor = QuotaActor("p", "u", "g")
+ tasks = [asyncio.create_task(search(client, actor, "First"))]
+ try:
+ await asyncio.wait_for(first_started.wait(), 2)
+ tasks.append(asyncio.create_task(search(client, actor, "Second")))
+ await asyncio.wait_for(second_reserving.wait(), 2)
+ reply_first.set()
+ with pytest.raises(RateLimitError):
+ await tasks[0]
+ release_quota.set()
+ await asyncio.wait_for(tasks[1], 2)
+ assert len(starts) == 2
+ assert starts[1] - backoff_started >= 0.145
+ assert await counts(storage, actor) == (2, 2, 2)
+ finally:
+ reply_first.set()
+ release_quota.set()
+ await asyncio.gather(*tasks, return_exceptions=True)
+
+
+@pytest.mark.asyncio
+async def test_admission_backoff_crossing_midnight_cannot_send_101_new_day_attempts(tmp_path, monkeypatch):
+ clock = [datetime.fromisoformat("2026-11-17T15:59:59+00:00").timestamp()]
+ first_started, reply_first = asyncio.Event(), asyncio.Event()
+ second_reserved, release_reservation = asyncio.Event(), asyncio.Event()
+ days = []
+
+ async def handler(request):
+ days.append(quota_day(clock[0]))
+ if request.url.params["q"] == "First":
+ first_started.set()
+ await reply_first.wait()
+ return httpx.Response(429, json={}, headers={"Retry-After": "0.1"})
+ return response()
+
+ async with running_client(tmp_path, handler, user_daily_limit=0, group_daily_limit=0) as (client, storage):
+ monkeypatch.setattr(storage, "_clock", lambda: clock[0])
+ monkeypatch.setattr(client_module, "quota_day", lambda _: quota_day(clock[0]))
+ consume = storage.consume_request
+ reservations = 0
+
+ async def pause_second_before_commit(*args, **kwargs):
+ nonlocal reservations
+ reservations += 1
+ if reservations == 2:
+ second_reserved.set()
+ await release_reservation.wait()
+ return await consume(*args, **kwargs)
+
+ monkeypatch.setattr(storage, "consume_request", pause_second_before_commit)
+ actor = QuotaActor("p", "u", "g")
+ tasks = [asyncio.create_task(search(client, actor, "First", force=True))]
+ try:
+ await asyncio.wait_for(first_started.wait(), 2)
+ tasks.append(asyncio.create_task(search(client, actor, "Second", force=True)))
+ await asyncio.wait_for(second_reserved.wait(), 2)
+ assert await counts(storage, actor) == (1, 1, 1)
+ reply_first.set()
+ with pytest.raises(RateLimitError):
+ await tasks[0]
+ release_reservation.set()
+ await asyncio.sleep(0.02)
+ clock[0] += 1 # Midnight while the new Retry-After is still active.
+ await asyncio.wait_for(tasks[1], 2)
+ assert await counts(storage, actor) == (1, 1, 1)
+ clock[0] -= 1
+ assert await counts(storage, actor) == (1, 1, 1)
+ clock[0] += 1
+ for index in range(99):
+ await search(client, actor, f"New day {index}", force=True)
+ with pytest.raises(QuotaExceededError) as denied:
+ await search(client, actor, "New day 101st", force=True)
+ assert_quota(denied.value, "global", 100, 100)
+ assert days.count("2026-11-18") == 100
+ assert await counts(storage, actor) == (100, 100, 100)
+ finally:
+ reply_first.set()
+ release_reservation.set()
+ await asyncio.gather(*tasks, return_exceptions=True)
diff --git a/tests/test_commands.py b/tests/test_commands.py
new file mode 100644
index 0000000..f43f3b1
--- /dev/null
+++ b/tests/test_commands.py
@@ -0,0 +1,160 @@
+"""Command contract tests; no framework, network, or real account is used."""
+
+import pytest
+
+from commands import Request, Target, mention_token, parse_command
+
+
+@pytest.mark.parametrize(("text", "expected"), [
+ ("", Request("help")),
+ ("help", Request("help")),
+ ("me", Request("stats", Target("me", ""))),
+ ("stats me", Request("stats", Target("me", ""))),
+ ("stats stb:0012345678901234567890", Request("stats", Target("stb", "0012345678901234567890"))),
+ ("stats steam:76561198012345678", Request("stats", Target("steam", "76561198012345678"))),
+ ("recent", Request("recent", Target("me", ""))),
+ ("recent 10", Request("recent", Target("me", ""), 10)),
+ ("recent10", Request("recent", Target("me", ""), 10)),
+ ("me recent 10", Request("recent", Target("me", ""), 10)),
+ ("me recent10", Request("recent", Target("me", ""), 10)),
+ ("recent steam:76561198012345678 --limit 10",
+ Request("recent", Target("steam", "76561198012345678"), 10)),
+ ("last", Request("last", Target("me", ""))),
+ ("me last", Request("last", Target("me", ""))),
+ ("last stb:001", Request("last", Target("stb", "001"))),
+ ("match 00098765432109876543210", Request("match", code="00098765432109876543210")),
+ ("search Player 2", Request("search", Target("name", "Player 2"))),
+ ("search 12345", Request("search", Target("name", "12345"))),
+ ("search me", Request("search", Target("name", "me"))),
+ ("bind name:Player", Request("bind", Target("name", "Player"))),
+ ("binding", Request("binding")),
+ ("unbind", Request("unbind")),
+ ("select AbC123 2", Request("select", code="AbC123", index=2)),
+ ("cancel AbC123", Request("cancel", code="AbC123")),
+ ("status", Request("status")),
+ ("quota", Request("quota")),
+ ("cache clear", Request("cache_clear")),
+])
+def test_english_command_table(text, expected):
+ assert parse_command(text) == expected
+
+
+@pytest.mark.parametrize("action", ["stats", "bind", "recent", "last"])
+@pytest.mark.parametrize(("argument", "name"), [
+ ('"Player 2"', "Player 2"),
+ ('name:"Player 2"', "Player 2"),
+ ("name:Player 2", "Player 2"),
+ ("name:me", "me"),
+ ("name:recent", "recent"),
+ ("name:12345", "12345"),
+ ('name:" Player 2 "', " Player 2 "),
+ ('name:"欧阳 O\'Brien [x]&"', "欧阳 O'Brien [x]&"),
+ ("name:@user:123", "@user:123"),
+ ('name:"Player --limit 2"', "Player --limit 2"),
+])
+def test_names_preserve_content(action, argument, name):
+ request = parse_command(f"{action} {argument}")
+ assert request.target == Target("name", name)
+
+
+def test_trailing_number_belongs_to_target_unless_explicit_limit():
+ assert parse_command("recent Player 2").target == Target("name", "Player 2")
+ request = parse_command('recent name:"Player 2" --limit 10')
+ assert request == Request("recent", Target("name", "Player 2"), 10)
+ assert parse_command("recent name:10").target == Target("name", "10")
+
+
+def test_case_insensitive_keywords_do_not_change_names_or_ids():
+ assert parse_command("STATS NAME:MiXeD Player").target == Target("name", "MiXeD Player")
+ assert parse_command("ME ReCeNt 10") == parse_command("recent 10")
+ assert parse_command("STATS STB:AbC-001").target == Target("stb", "AbC-001")
+
+
+@pytest.mark.parametrize(("chinese", "english"), [
+ ("帮助", "help"), ("我", "me"), ("战绩 我", "stats me"),
+ ("最近 10", "recent 10"), ("自己 近期 10", "me recent 10"),
+ ("上一场", "last"), ("我 上一场", "me last"),
+ ("单局 123", "match 123"), ("搜索 me", "search me"),
+ ("绑定 name:me", "bind name:me"), ("当前绑定", "binding"),
+ ("解绑", "unbind"), ("选择 ABC 1", "select ABC 1"),
+ ("取消 ABC", "cancel ABC"), ("状态", "status"), ("缓存 清理", "cache clear"),
+ ("额度", "quota"),
+])
+def test_optional_chinese_aliases_share_requests(chinese, english):
+ assert parse_command(chinese) == parse_command(english)
+ with pytest.raises(ValueError, match="未知命令"):
+ parse_command(chinese, chinese_aliases=False)
+
+
+def test_alias_switch_does_not_translate_explicit_names():
+ assert parse_command("stats name:我").target == Target("name", "我")
+ assert parse_command("stats 我", chinese_aliases=False).target == Target("name", "我")
+
+
+def test_structured_mentions_require_trusted_component_position():
+ assert parse_command(f"stats {mention_token(0)}", mentions=["000123"]).target == Target("mention", "000123")
+ for text, mentions in [
+ ("stats @user:123", []), ("stats @user:123", ["123"]),
+ (f"stats @user:123 {mention_token(0)}", ["123"]),
+ (f"stats {mention_token(1)}", ["123"]),
+ (f"stats {mention_token(0)}", []),
+ ("stats @user:123 @user:321", ["123", "321"]),
+ ("stats @群名片", []), ("stats", ["123"]),
+ ]:
+ with pytest.raises(ValueError):
+ parse_command(text, mentions=mentions)
+
+
+@pytest.mark.parametrize("text", ["stats name:@user:123", "search @user:123"])
+def test_literal_marker_names_never_borrow_trusted_account_ids(text):
+ assert parse_command(text, mentions=["123"]).target == Target("name", "@user:123")
+
+
+@pytest.mark.parametrize("text", ["search {}", "stats name:{}", "stats name:Player {}"])
+def test_real_mentions_are_not_converted_into_nickname_queries(text):
+ with pytest.raises(ValueError, match="提及"):
+ parse_command(text.format(mention_token(0)), mentions=["123"])
+
+
+@pytest.mark.parametrize("text", [
+ "stats 12345", "bind 12345", "last 12345", "recent 123 --limit 5",
+])
+def test_bare_numeric_player_is_ambiguous(text):
+ with pytest.raises(ValueError, match="stb:.*steam:.*name:"):
+ parse_command(text)
+
+
+@pytest.mark.parametrize("text", [
+ "stats", "bind", 'stats ""', 'stats " "', "stats name:", 'stats name:" "', "stats stb:",
+ "stats steam:abc", 'stats stb:"12 34"', 'stats "Player',
+ "recent 0", "recent 21", "recent10 --limit 5", "me recent 0",
+ "me recent player", "me recent 5 6", "me stats", "me last player",
+ "recent Player --limit 0", "recent Player --limit", "recent --limit 5",
+ "recent Player --limit 5 ignored", "recent Player --limit 5 --limit 10",
+ "recent Player --unknown 10", "match", "match a b", "match 'a b'",
+ "select code 0", "select code -1", "select code 1.5", "select code",
+ "cancel", "cancel code extra", "cache", "cache clear extra", "cache delete",
+ "search", 'search ""', "help extra", "binding extra", "unbind extra", "status extra", "quota extra",
+ "stats https://steamcommunity.com/id/player", "stats steamcommunity.com/id/player",
+ "unknown", "/ba help",
+])
+def test_invalid_syntax_has_chinese_feedback(text):
+ with pytest.raises(ValueError) as error:
+ parse_command(text)
+ assert any("\u4e00" <= char <= "\u9fff" for char in str(error.value))
+
+
+def test_configured_limits_apply_to_defaults_and_both_self_spellings():
+ assert parse_command("recent", default_limit=3, max_limit=10).limit == 3
+ assert parse_command("recent 10", max_limit=10) == parse_command("me recent 10", max_limit=10)
+ with pytest.raises(ValueError):
+ parse_command("recent 11", max_limit=10)
+ for default, maximum in [(0, 20), (21, 20), (1, 0), (True, 20)]:
+ with pytest.raises(ValueError):
+ parse_command("help", default_limit=default, max_limit=maximum)
+
+
+def test_excessively_long_integer_arguments_still_have_chinese_errors():
+ for text in ["recent " + "9" * 5000, "select code " + "9" * 5000]:
+ with pytest.raises(ValueError, match="整数"):
+ parse_command(text)
diff --git a/tests/test_main.py b/tests/test_main.py
new file mode 100644
index 0000000..f62f040
--- /dev/null
+++ b/tests/test_main.py
@@ -0,0 +1,523 @@
+"""AstrBot adapter tests with test-local, fully restored module stubs.
+
+These exercise registered handler behavior, not a live QQ/AstrBot deployment.
+Plain/At and event methods follow the adapter's actual framework interfaces.
+"""
+
+import asyncio
+from contextlib import nullcontext
+from dataclasses import dataclass
+import importlib
+import inspect
+import json
+import logging
+from pathlib import Path
+import sys
+from types import ModuleType, SimpleNamespace
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock
+
+import pytest
+import httpx
+
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+@dataclass
+class Plain:
+ text: str
+
+
+@dataclass
+class At:
+ qq: str | int
+
+
+class Event:
+ def __init__(self, messages, *, admin=False, normalized=None, session="onebot:test:group:1",
+ user="10001", group="1", platform="onebot:test"):
+ self.message_obj = SimpleNamespace(message=messages, self_id="999", sender=SimpleNamespace(user_id="10001"))
+ self.unified_msg_origin = session
+ self.admin = admin
+ self.stopped = False
+ self.normalized = normalized
+ self.message_obj.sender.user_id = user
+ self.group, self.platform = group, platform
+
+ def get_messages(self):
+ return self.message_obj.message
+
+ def get_message_str(self):
+ if self.normalized is not None:
+ return self.normalized
+ text = "".join(part.text if isinstance(part, Plain) else f"@{part.qq}" for part in self.get_messages())
+ return " ".join(text.split())
+
+ def get_self_id(self):
+ return self.message_obj.self_id
+
+ def get_sender_id(self):
+ return self.message_obj.sender.user_id
+
+ def get_platform_id(self):
+ return self.platform
+
+ def get_group_id(self):
+ return self.group
+
+ def is_admin(self):
+ return self.admin
+
+ def stop_event(self):
+ self.stopped = True
+
+ def plain_result(self, text):
+ return "plain", text
+
+ def image_result(self, path):
+ return "image", path
+
+
+@pytest.fixture
+def app_modules(monkeypatch, tmp_path):
+ registered = []
+
+ class Filters:
+ def command(self, command, **options):
+ def decorate(function):
+ registered.append((command, options, function))
+ return function
+ return decorate
+
+ def __getattr__(self, name):
+ raise AssertionError(f"Unexpected message-wide or extra filter registration: {name}")
+
+ class Star:
+ def __init__(self, context):
+ self.context = context
+ self.logger = logging.getLogger("ba-stats-test")
+
+ async def html_render(self, *args, **kwargs):
+ raise AssertionError("A real renderer must never be contacted by these tests")
+
+ class StarTools:
+ @staticmethod
+ def get_data_dir(plugin_name):
+ assert plugin_name == "astrbot_plugin_ba_stats"
+ return tmp_path / "plugin-data"
+
+ stubs = {key: ModuleType(key) for key in (
+ "astrbot", "astrbot.api", "astrbot.api.event", "astrbot.api.message_components", "astrbot.api.star"
+ )}
+ stubs["astrbot"].__path__ = []
+ stubs["astrbot.api"].__path__ = []
+ stubs["astrbot"].api = stubs["astrbot.api"]
+ stubs["astrbot.api"].AstrBotConfig = dict
+ stubs["astrbot.api.event"].AstrMessageEvent = Event
+ stubs["astrbot.api.event"].filter = Filters()
+ stubs["astrbot.api.message_components"].Plain = Plain
+ stubs["astrbot.api.message_components"].At = At
+ stubs["astrbot.api.star"].Context = object
+ stubs["astrbot.api.star"].Star = Star
+ stubs["astrbot.api.star"].StarTools = StarTools
+ for key, module in stubs.items():
+ monkeypatch.setitem(sys.modules, key, module)
+ name = "_ba_stats_main_contract"
+ package = ModuleType(name)
+ package.__path__ = [str(ROOT)]
+ monkeypatch.setitem(sys.modules, name, package)
+ try:
+ main = importlib.import_module(name + ".main")
+ yield SimpleNamespace(
+ main=main, registered=registered,
+ models=importlib.import_module(name + ".models"),
+ storage=importlib.import_module(name + ".storage"),
+ package=name,
+ )
+ finally:
+ for key in tuple(sys.modules):
+ if key.startswith(name + "."):
+ sys.modules.pop(key, None)
+
+
+@pytest.fixture
+async def app(app_modules):
+ plugins = []
+
+ async def make(*, images=False, config=None, prefixes=None):
+ values = {"query": {"cooldown_seconds": 0}, "output": {"image_enabled": images}}
+ if config:
+ values.update(config)
+ context = SimpleNamespace(get_config=lambda umo: {"wake_prefix": prefixes or ["/"]})
+ plugin = app_modules.main.BAStatsPlugin(context, values)
+ plugins.append(plugin)
+ await plugin.initialize()
+ return plugin
+
+ try:
+ yield SimpleNamespace(make=make, **vars(app_modules))
+ finally:
+ for plugin in plugins:
+ await plugin.terminate()
+
+
+async def collect(plugin, event):
+ return [item async for item in plugin.ba(event)]
+
+
+def test_only_framework_ba_command_is_registered(app_modules):
+ assert len(app_modules.registered) == 1
+ command, options, function = app_modules.registered[0]
+ assert command == "ba"
+ assert options["alias"] == {"BA", "Ba", "bA"}
+ assert function is app_modules.main.BAStatsPlugin.ba
+
+
+@pytest.mark.parametrize("messages", [
+ [Plain('/ba recent name:"a b" --limit 10')],
+ [Plain('/ba recent name:"a '), Plain(' b" --limit 10')],
+ [At("999"), Plain(' /ba recent name:"a b" --limit 10')],
+ [Plain('!!BA recent name:"a b" --limit 10')],
+])
+def test_real_style_plain_components_preserve_quotes_and_repeated_spaces(app_modules, messages):
+ event = Event(messages, normalized='ba recent name:"a b" --limit 10')
+ text, mentions = app_modules.main.extract_arguments(event, ["/", "!!"])
+ assert 'name:"a b"' in text
+ request = app_modules.main.parse_command(text, mentions)
+ assert request.target.kind == "name"
+ assert request.target.value == "a b"
+ assert request.limit == 10
+
+
+def test_at_component_is_used_as_account_id_and_never_group_card(app_modules):
+ event = Event([At("999"), Plain(" /ba stats "), At(12345)])
+ text, mentions = app_modules.main.extract_arguments(event, ["/"])
+ assert mentions == ["12345"]
+ request = app_modules.main.parse_command(text, mentions)
+ assert (request.target.kind, request.target.value) == ("mention", "12345")
+
+
+@pytest.mark.parametrize("messages", [
+ [Plain("/ba stats @user:12345")],
+ [Plain("/ba stats @user:12345 "), At("12345")],
+ [Plain("/ba stats "), At("all")],
+])
+def test_typed_internal_mentions_and_at_all_are_rejected(app_modules, messages):
+ with pytest.raises(ValueError, match="提及|全体"):
+ text, mentions = app_modules.main.extract_arguments(Event(messages), ["/"])
+ app_modules.main.parse_command(text, mentions)
+
+
+def test_plain_text_cannot_forge_component_position(app_modules):
+ with pytest.raises(ValueError, match="控制字符"):
+ app_modules.main.extract_arguments(Event([
+ Plain("/ba stats \x00at:0\x00 "), At("12345")
+ ]), ["/"])
+
+
+@pytest.mark.parametrize("command", [
+ "stats name:@user:12345", "bind name:@user:12345",
+ "recent name:@user:12345 --limit 2", "last name:@user:12345",
+ "search @user:12345",
+])
+async def test_handler_preserves_marker_text_for_nickname_targets(app, monkeypatch, command):
+ plugin = await app.make()
+ execute = AsyncMock(return_value=SimpleNamespace(text="ok", view=None))
+ monkeypatch.setattr(plugin.service, "execute", execute)
+ assert await collect(plugin, Event([Plain("/ba " + command)])) == [("plain", "ok")]
+ request, _ = execute.await_args.args
+ assert (request.target.kind, request.target.value) == ("name", "@user:12345")
+
+
+@pytest.mark.parametrize("command", ["stats", "bind", "recent", "last"])
+def test_component_provenance_is_preserved_for_each_target_action(app_modules, command):
+ text, mentions = app_modules.main.extract_arguments(
+ Event([Plain(f"/ba {command} "), At("12345")]), ["/"])
+ target = app_modules.main.parse_command(text, mentions).target
+ assert (target.kind, target.value) == ("mention", "12345")
+
+
+async def test_unconfigured_plugin_help_works_and_online_command_explains_missing_access(app):
+ plugin = await app.make()
+ help_event = Event([Plain("/ba help")])
+ replies = await collect(plugin, help_event)
+ assert help_event.stopped
+ assert replies[0][0] == "plain"
+ assert "首次使用" in replies[0][1]
+ replies = await collect(plugin, Event([Plain("/ba search Synthetic")]))
+ assert "接入未配置" in replies[0][1]
+ assert plugin.client.status()["requests"] == 0
+
+
+async def test_handler_passes_component_preserved_name_to_service(app, monkeypatch):
+ plugin = await app.make(prefixes=["!!"])
+ execute = AsyncMock(return_value=SimpleNamespace(text="ok", view=None))
+ monkeypatch.setattr(plugin.service, "execute", execute)
+ replies = await collect(plugin, Event(
+ [Plain('!!ba stats name:"a '), Plain(' b"')], normalized='ba stats name:"a b"'
+ ))
+ assert replies == [("plain", "ok")]
+ request, caller = execute.await_args.args
+ assert request.target.value == "a b"
+ assert caller.prefix == "!!ba"
+
+
+@pytest.mark.parametrize("command", ["status", "状态", "cache clear", "缓存 清理"])
+async def test_admin_check_cannot_be_bypassed_by_english_or_chinese_commands(app, monkeypatch, command):
+ plugin = await app.make()
+ status = AsyncMock(wraps=plugin._status)
+ clear = AsyncMock(wraps=plugin.client.clear_cache)
+ execute = AsyncMock(wraps=plugin.service.execute)
+ monkeypatch.setattr(plugin, "_status", status)
+ monkeypatch.setattr(plugin.client, "clear_cache", clear)
+ monkeypatch.setattr(plugin.service, "execute", execute)
+ replies = await collect(plugin, Event([Plain("/ba " + command)], admin=False))
+ assert "仅供 AstrBot 管理员" in replies[0][1]
+ status.assert_not_awaited()
+ clear.assert_not_awaited()
+ execute.assert_not_awaited()
+
+
+async def test_admin_cache_clear_removes_api_and_images_but_preserves_binding(app):
+ plugin = await app.make()
+ old = app.storage.Binding(plugin.client.namespace, "001", "Synthetic")
+ await plugin.storage.set_binding("onebot:test", "10001", old)
+ await plugin.storage.put_cache("synthetic", {}, 60)
+ await plugin.storage.consume_request()
+ (plugin._images / "synthetic.jpg").write_bytes(b"synthetic image cache")
+ replies = await collect(plugin, Event([Plain("/ba cache clear")], admin=True))
+ assert "已清理" in replies[0][1]
+ assert await plugin.storage.cache_count() == 0
+ assert not list(plugin._images.glob("*.jpg"))
+ assert await plugin.storage.get_binding("onebot:test", "10001") == old
+ assert (await plugin.storage.quota_usage())["global"] == 1
+
+
+async def test_admin_status_does_not_expose_configured_credentials(app):
+ secret = "synthetic-token-never-display"
+ identity = "synthetic-private-client"
+ plugin = await app.make(config={"access": {
+ "enabled": True, "client_id": identity, "api_token": secret,
+ "base_url": "https://example.invalid",
+ }})
+ replies = await collect(plugin, Event([Plain("/ba status")], admin=True))
+ text = replies[0][1]
+ assert "已填写" in text
+ assert secret not in text and identity not in text and "example.invalid" not in text
+ assert plugin.client.status()["requests"] == 0
+ assert "今日总请求:0/100(固定上限)" in text
+
+
+async def test_image_failure_uses_same_result_as_text_without_second_fetch(app, monkeypatch):
+ plugin = await app.make(images=True)
+ m = app.models
+ at = datetime(2026, 11, 17, tzinfo=timezone.utc)
+ player = m.Player("001", "Synthetic a b", source_url="https://example.invalid/players/001")
+ client = SimpleNamespace(
+ namespace="batrace:synthetic", player=AsyncMock(return_value=m.FetchResult(player, at)),
+ recent=AsyncMock(return_value=m.FetchResult([], at)), close=AsyncMock(),
+ request_scope=lambda actor: nullcontext(),
+ )
+ await plugin.client.close()
+ plugin.client = plugin.service.client = client
+ image = AsyncMock(side_effect=RuntimeError("synthetic render failure"))
+ monkeypatch.setattr(plugin, "_image", image)
+ original_execute = plugin.service.execute
+ responses = []
+
+ async def execute(*args):
+ response = await original_execute(*args)
+ responses.append(response)
+ return response
+
+ monkeypatch.setattr(plugin.service, "execute", execute)
+ replies = await collect(plugin, Event([Plain("/ba stats stb:001")]))
+ assert len(responses) == 1
+ expected = plugin.renderer.text(plugin.renderer.views(responses[0].view)[0])
+ assert replies == [("plain", expected)]
+ assert "001" in expected and "Synthetic a b" in expected
+ image.assert_awaited_once()
+ client.player.assert_awaited_once_with("001")
+ client.recent.assert_awaited_once_with("001", plugin.settings.max_limit)
+
+
+async def test_image_render_uses_mobile_jpeg_contract_and_fixed_outer_template(app, monkeypatch, tmp_path):
+ plugin = await app.make(images=True)
+ # Only exercise local file handoff/caching, not image validity or appearance.
+ source = tmp_path / "synthetic-render.jpg"
+ source.write_bytes(b"synthetic jpeg handoff")
+ render = AsyncMock(return_value=str(source))
+ monkeypatch.setattr(plugin, "html_render", render)
+ view = {
+ "kind": "overview", "player": {"id": "001", "name": "Synthetic {{ 7 * 7 }} a b"},
+ "scope": "合成测试样本", "fetched_at": datetime(2026, 11, 17, tzinfo=timezone.utc),
+ }
+ first = await plugin._image(view, "onebot:test:group:one")
+ assert Path(first).suffix == ".jpg"
+ assert Path(first).read_bytes() == source.read_bytes()
+ assert await plugin._image(view, "onebot:test:group:one") == first
+ render.assert_awaited_once()
+ positional, options = render.await_args
+ assert positional[0] == "{{ body | safe }}"
+ assert "{{ 7 * 7 }} a b" in positional[1]["body"]
+ assert options["return_url"] is False
+ assert options["umo"] == "onebot:test:group:one"
+ assert options["options"] == {
+ "type": "jpeg", "quality": 85, "full_page": True,
+ "viewport_width": 390, "device_scale_factor_level": "ultra",
+ }
+ second = await plugin._image(view, "onebot:test:group:two")
+ assert second != first
+ assert render.await_count == 2
+
+
+async def test_run_after_terminate_closes_coroutine_and_creates_no_task(app):
+ plugin = await app.make()
+ await plugin.terminate()
+ entered = False
+
+ async def should_not_run():
+ nonlocal entered
+ entered = True
+
+ coroutine = should_not_run()
+ with pytest.raises(asyncio.CancelledError):
+ await plugin._run(coroutine)
+ assert inspect.getcoroutinestate(coroutine) == inspect.CORO_CLOSED
+ assert not entered
+ assert not plugin._tasks
+
+
+async def test_terminate_cancels_and_awaits_active_work_then_closes_resources(app, monkeypatch):
+ plugin = await app.make()
+ started, cancelled = asyncio.Event(), asyncio.Event()
+
+ async def blocked(*args):
+ started.set()
+ try:
+ await asyncio.Event().wait()
+ finally:
+ cancelled.set()
+
+ monkeypatch.setattr(plugin.service, "execute", blocked)
+ close_client = AsyncMock(wraps=plugin.client.close)
+ close_storage = AsyncMock(wraps=plugin.storage.close)
+ monkeypatch.setattr(plugin.client, "close", close_client)
+ monkeypatch.setattr(plugin.storage, "close", close_storage)
+ scope = ("p", "s", "u")
+ generation = plugin.service.pending.begin(scope)
+ plugin.service.pending.publish(scope, generation, object(), [object()])
+ task = asyncio.create_task(collect(plugin, Event([Plain("/ba search Synthetic")])))
+ try:
+ await asyncio.wait_for(started.wait(), 2)
+ await plugin.terminate()
+ results = await asyncio.gather(task, return_exceptions=True)
+ assert isinstance(results[0], asyncio.CancelledError)
+ assert cancelled.is_set()
+ assert not plugin._tasks
+ assert not plugin.service.pending.is_current(scope, generation)
+ close_client.assert_awaited_once()
+ close_storage.assert_awaited_once()
+ with pytest.raises(RuntimeError, match="尚未打开"):
+ await plugin.storage.get_binding("p", "u")
+ assert await collect(plugin, Event([Plain("/ba help")])) == []
+ finally:
+ if not task.done():
+ task.cancel()
+ await asyncio.gather(task, return_exceptions=True)
+
+
+@pytest.mark.parametrize("command,group", [("quota", "1"), ("额度", "")])
+async def test_quota_is_local_and_available_without_access_or_admin(app, command, group):
+ plugin = await app.make()
+ replies = await collect(plugin, Event([Plain("/ba " + command)], group=group))
+ text = replies[0][1]
+ assert "个人:已用 0/20 次" in text
+ assert "全插件:已用 0/100 次" in text
+ assert ("本群:已用 0/100 次" in text) == bool(group)
+ assert "北京时间每天 0 点重置" in text
+ assert plugin.client.status()["requests"] == 0
+
+
+async def test_handler_enforces_user_group_quota_and_preserves_cached_access(app):
+ plugin = await app.make(config={
+ "access": {"enabled": True, "client_id": "synthetic-test", "base_url": "https://synthetic.invalid"},
+ "query": {"cooldown_seconds": 0},
+ "maintenance": {"request_interval": 0.1, "retries": 0},
+ "limits": {"user_daily_limit": 2, "group_daily_limit": 3},
+ })
+ calls = []
+ def handler(request):
+ calls.append(request)
+ return httpx.Response(200, json={"players": [{"id": "001", "name": "Synthetic"}]})
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ plugin.client._http, plugin.client._owns_http = http, False
+ async def search(query, user, group, admin=False):
+ return await collect(plugin, Event([Plain("/ba search " + query)], user=user,
+ group=group, admin=admin))
+ await search("one", "u1", "g1")
+ await search("two", "u1", "g2")
+ blocked = await search("private", "u1", "")
+ assert "20" not in blocked[0][1] # Runtime override, not a hardcoded default.
+ assert "额度" in blocked[0][1] and "2" in blocked[0][1]
+ await search("three", "u2", "g1")
+ await search("four", "u3", "g1")
+ assert "额度" in (await search("five", "u4", "g1"))[0][1]
+ assert "额度" in (await search("six", "u1", "g2", admin=True))[0][1]
+ assert len(calls) == 4
+ # A fresh cached response consumes no upstream request, even at the cap.
+ cached = await search("one", "u1", "g1")
+ assert "请选择" in cached[0][1]
+ assert len(calls) == 4
+ actor = app.main.QuotaActor("onebot:test", "u1", "g1")
+ usage = await plugin.storage.quota_usage(actor)
+ assert (usage["global"], usage["user"], usage["group"]) == (4, 2, 3)
+ before = dict(usage)
+ for text in ["help", "binding", "unbind", "quota"]:
+ await collect(plugin, Event([Plain("/ba " + text)], user="u1", group="g1"))
+ assert await plugin.storage.quota_usage(actor) == before
+
+
+async def test_mentions_charge_request_sender_not_queried_user(app):
+ plugin = await app.make(config={
+ "access": {"enabled": True, "client_id": "synthetic-test", "base_url": "https://synthetic.invalid"},
+ "query": {"cooldown_seconds": 0}, "maintenance": {"request_interval": 0.1, "retries": 0},
+ })
+ await plugin.storage.set_binding("onebot:test", "target", app.storage.Binding(
+ plugin.client.namespace, "001", "Synthetic"))
+ def handler(request):
+ if request.url.path.endswith("search"):
+ payload = {"players": [{"id": "001", "name": "Synthetic"}]}
+ elif request.url.path.endswith("player"):
+ payload = {"trend": {"points": []}}
+ else:
+ payload = {"matches": []}
+ return httpx.Response(200, json=payload)
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ plugin.client._http, plugin.client._owns_http = http, False
+ replies = await collect(plugin, Event([Plain("/ba stats "), At("target")], user="sender", group="g"))
+ assert "Synthetic" in replies[0][1]
+ sender = await plugin.storage.quota_usage(app.main.QuotaActor("onebot:test", "sender", "g"))
+ target = await plugin.storage.quota_usage(app.main.QuotaActor("onebot:test", "target", "g"))
+ assert (sender["global"], sender["user"], sender["group"], target["user"]) == (3, 3, 3, 0)
+
+
+def test_quota_defaults_schema_and_fixed_total_are_consistent(app_modules):
+ settings = app_modules.main.Settings
+ schema = json.loads((ROOT / "_conf_schema.json").read_text(encoding="utf-8"))
+ limits = schema["limits"]["items"]
+ assert set(limits) == {"user_daily_limit", "group_daily_limit"}
+ defaults = settings.from_config({})
+ assert defaults.user_daily_limit == limits["user_daily_limit"]["default"] == 20
+ assert defaults.group_daily_limit == limits["group_daily_limit"]["default"] == 100
+ configured = settings.from_config({"limits": {
+ "user_daily_limit": 0, "group_daily_limit": 1, "global_daily_limit": 10000, "timezone": "UTC",
+ }, "output": {"timezone": "UTC"}})
+ assert configured.user_daily_limit == 0 and configured.group_daily_limit == 1
+ assert not hasattr(configured, "global_daily_limit")
+ assert app_modules.main.GLOBAL_DAILY_LIMIT == 100
+ for key in limits:
+ for invalid in [-1, 101, True, 2.5, "20", None]:
+ with pytest.raises(ValueError, match="0–100"):
+ settings.from_config({"limits": {key: invalid}})
diff --git a/tests/test_models.py b/tests/test_models.py
new file mode 100644
index 0000000..3591304
--- /dev/null
+++ b/tests/test_models.py
@@ -0,0 +1,176 @@
+"""All payloads below are SYNTHETIC contract fixtures, not captured BATrace data."""
+
+from datetime import datetime, timezone
+
+import pytest
+
+from models import (
+ FetchResult, Match, Participant, Player, canonical_id, parse_match,
+ parse_player, parse_recent, parse_search, utc_datetime,
+)
+
+
+def raw_match(*, start=1700000000, end=1700000600):
+ return {
+ "StartTime": start, "EndTime": end, "TotalPlayTimeInSec": 600,
+ "MapId": 20, "Type": 99,
+ "Data": {
+ "a": {"Id": "001", "Name": "Synthetic ", "OldRating": 1000,
+ "NewRating": 1012, "Destruction": 2, "Losses": 1,
+ "DestructionScore": 500, "LossesScore": 100, "UnitData": {}},
+ "b": {"Id": 2, "Name": "Synthetic B", "TeamId": 1,
+ "OldRating": 1000, "NewRating": 988, "UnitData": {}},
+ },
+ }
+
+
+def test_dataclasses_do_not_share_mutable_lists():
+ a, b = Match("a"), Match("b")
+ a.players.append(Participant("p", "Synthetic"))
+ assert b.players == []
+ a.players[0].units.append({"id": "u"})
+ assert Participant("q", "Another").units == []
+ assert Player("001", "Synthetic").steam_id is None
+ assert FetchResult([], datetime.now(timezone.utc)).stale is False
+
+
+@pytest.mark.parametrize("raw", [1.0, True, None, "", " 1", "1 "])
+def test_identity_does_not_guess_or_round(raw):
+ with pytest.raises(ValueError):
+ canonical_id(raw)
+
+
+def test_large_ids_are_strings_and_names_are_never_identity_keys():
+ payload = {"players": [
+ {"id": "000765611980123456789012345", "name": "Same"},
+ {"id": 98765432109876543210987654321, "name": "Same"},
+ {"id": "000765611980123456789012345", "name": "Same"},
+ ]}
+ players = parse_search(payload)
+ assert len(players) == 2
+ assert players[0].id == "000765611980123456789012345"
+ assert players[1].id == "98765432109876543210987654321"
+ assert all(p.elo is None and p.steam_id is None for p in players)
+
+
+def test_newer_search_duplicate_updates_name_without_moving_candidate():
+ players = parse_search({"players": [
+ {"id": "a", "name": "Old", "updated_at": "2023-01-01T00:00:00Z"},
+ {"id": "b", "name": "Other"},
+ {"id": "a", "name": "New", "updated_at": "2023-02-01T00:00:00Z"},
+ ]})
+ assert [(p.id, p.name) for p in players] == [("a", "New"), ("b", "Other")]
+
+
+def test_links_use_reference_confirmed_routes_and_escape_external_id():
+ player = parse_search({"players": [{"id": "x/#?", "name": "Synthetic"}]})[0]
+ assert player.source_url == "https://dash.batrace.top/player/x%2F%23%3F"
+ assert parse_match({"matchInfo": raw_match()}, "x/#?").source_url.endswith("/match/x%2F%23%3F")
+
+
+def test_time_is_aware_utc_and_recent_can_derive_start_from_end():
+ assert utc_datetime("2023-11-15T06:13:20+08:00") == utc_datetime(1700000000)
+ match = raw_match()
+ match.pop("StartTime")
+ normalized = parse_match({"matchInfo": match}, "a")
+ assert normalized.started_at == datetime.fromtimestamp(1700000000, timezone.utc)
+
+
+@pytest.mark.parametrize("raw", ["2023-01-01T00:00:00", True, float("nan"), float("inf")])
+def test_time_does_not_guess_timezone_or_accept_nonfinite_values(raw):
+ with pytest.raises(ValueError):
+ utc_datetime(raw)
+
+
+def test_player_uses_newest_dated_observation_not_array_order():
+ player = parse_player({
+ "search": {"players": [{"id": "001", "name": "Synthetic", "rating": 900}]},
+ "analysis": {"matchCount": 2, "trend": {"points": [
+ {"ratingAfter": 1200, "endTime": 1700000600},
+ {"ratingAfter": 1100, "endTime": 1700000000},
+ ]}},
+ }, "001")
+ assert player.elo == 1200
+ assert player.elo_observed_at == utc_datetime(1700000600)
+ assert player.updated_at is None # a match end is not a source update stamp
+
+
+def test_search_snapshot_newer_than_trend_keeps_its_rating():
+ player = parse_player({
+ "search": {"players": [{"id": "001", "name": "Synthetic", "rating": 1300,
+ "updated_at": "2023-11-15T00:00:00Z"}]},
+ "analysis": {"trend": {"points": [{"ratingAfter": 1200, "endTime": 1700000000}]}},
+ }, "001")
+ assert player.elo == 1300
+ assert player.elo_observed_at is None
+
+
+def test_player_does_not_replace_requested_identity_or_invent_steam_mapping():
+ with pytest.raises(ValueError, match="ID"):
+ parse_player({"search": {"players": [{"id": "other", "name": "Same"}]},
+ "analysis": {"matchCount": 0}}, "001")
+
+
+def test_protobuf_defaults_are_scoped_and_count_is_distinct_from_value():
+ match = parse_match({"matchInfo": raw_match()}, "42")
+ a, b = match.players
+ assert (a.kills, a.losses, a.destroyed_value, a.lost_value) == (2, 1, 500, 100)
+ assert a.team == "0"
+ assert (b.kills, b.losses, b.destroyed_value, b.lost_value) == (0, 0, 0, 0)
+ assert parse_match({"matchInfo": {"Data": {"a": {"Id": "001"}}}}, "empty").players[0].elo is None
+ assert Participant("001", "Synthetic").kills is None # no universal zero filling
+
+
+def test_rating_change_never_becomes_verified_outcome_or_mode():
+ match = parse_match({"matchInfo": raw_match()}, "42")
+ assert match.winner_team is None
+ assert match.mode == "unknown"
+ assert [p.outcome for p in match.players] == ["unknown", "unknown"]
+ assert [p.elo_delta for p in match.players] == [12, -12]
+
+
+def test_match_detail_and_recent_have_different_completeness():
+ match = raw_match()
+ assert parse_match({"matchInfo": match}, "42").complete
+ assert not parse_match({"matchInfo": match}, "42", detail=False).complete
+ match["Data"]["a"].pop("UnitData")
+ assert not parse_match({"matchInfo": match}, "42").complete
+
+
+def test_recent_deduplicates_ids_sorts_actual_start_and_retains_unknown_time():
+ rows = [
+ {"matchId": "old", "data": raw_match(start=1700000000)},
+ {"matchId": "new", "data": raw_match(start=1700000500)},
+ {"matchId": "new", "data": raw_match(start=1700000500)},
+ {"matchId": "unknown", "data": {"Data": {}}},
+ ]
+ assert [m.id for m in parse_recent({"matches": rows})] == ["new", "old", "unknown"]
+ assert parse_recent({"matches": []}) == []
+
+
+@pytest.mark.parametrize("payload", [{}, {"players": None}, {"players": {}}, {"error": "synthetic"}])
+def test_missing_response_array_is_not_a_successful_empty_search(payload):
+ with pytest.raises(ValueError):
+ parse_search(payload)
+
+
+@pytest.mark.parametrize("mutate", [
+ lambda m: m["Data"]["a"].update({"Id": 1.5}),
+ lambda m: m["Data"]["a"].update({"Destruction": -1}),
+ lambda m: m["Data"]["a"].update({"Losses": 1.5}),
+ lambda m: m["Data"]["a"].update({"NewRating": float("nan")}),
+ lambda m: m["Data"]["a"].update({"TeamId": None}),
+ lambda m: m["Data"]["a"].update({"UnitData": []}),
+ lambda m: m.update({"EndTime": 1600000000}),
+ lambda m: m.update({"TotalPlayTimeInSec": -1}),
+])
+def test_structural_changes_and_invalid_numbers_are_rejected(mutate):
+ payload = raw_match()
+ mutate(payload)
+ with pytest.raises(ValueError):
+ parse_match({"matchInfo": payload}, "42")
+
+
+def test_explicit_mismatching_match_id_is_rejected():
+ with pytest.raises(ValueError, match="ID mismatch"):
+ parse_match({"matchId": "other", "matchInfo": raw_match()}, "42")
diff --git a/tests/test_pending.py b/tests/test_pending.py
new file mode 100644
index 0000000..c604adf
--- /dev/null
+++ b/tests/test_pending.py
@@ -0,0 +1,219 @@
+"""Deterministic selection tests with opaque requests and fake time."""
+
+from concurrent.futures import ThreadPoolExecutor
+
+import pytest
+
+from pending import PendingManager
+
+
+SCOPE = ("onebot:instance-a", "group:one", "user:1")
+
+
+class Clock:
+ now = 100.0
+
+ def __call__(self):
+ return self.now
+
+
+def publish(manager, scope=SCOPE, request=None, candidates=None):
+ generation = manager.begin(scope)
+ pending = manager.publish(scope, generation, request if request is not None else object(),
+ candidates if candidates is not None else [object(), object()])
+ assert pending is not None
+ return pending
+
+
+def test_original_action_and_candidate_order_survive_one_time_choice():
+ manager = PendingManager()
+ request = {"action": "recent", "limit": 10, "query": "Player"}
+ candidates = [object(), object()]
+ pending = publish(manager, request=request, candidates=candidates)
+ candidates.reverse()
+ chosen_request, chosen_candidate = manager.consume(SCOPE, pending.code, 2)
+ assert chosen_request is request
+ assert chosen_request["action"] == "recent"
+ assert chosen_candidate is candidates[0]
+ with pytest.raises(ValueError):
+ manager.consume(SCOPE, pending.code, 2)
+ assert manager.publish(SCOPE, pending.generation, request, candidates) is None
+
+
+@pytest.mark.parametrize("scope", [
+ ("onebot:instance-a", "group:one", "user:2"),
+ ("onebot:instance-a", "group:two", "user:1"),
+ ("onebot:instance-b", "group:one", "user:1"),
+])
+def test_other_users_sessions_and_platforms_cannot_consume_or_cancel(scope):
+ manager = PendingManager()
+ first = publish(manager)
+ second = publish(manager, scope)
+ with pytest.raises(ValueError):
+ manager.consume(scope, first.code, 1)
+ assert not manager.cancel(scope, first.code)
+ assert manager.consume(SCOPE, first.code, 1)[0] is first.request
+ assert manager.consume(scope, second.code, 1)[0] is second.request
+
+
+def test_begin_immediately_invalidates_old_list_before_network_finishes():
+ manager = PendingManager()
+ old = publish(manager)
+ generation = manager.begin(SCOPE)
+ with pytest.raises(ValueError):
+ manager.consume(SCOPE, old.code, 1)
+ assert manager.publish(SCOPE, old.generation, old.request, old.candidates) is None
+ new = manager.publish(SCOPE, generation, {"action": "bind"}, ["new"])
+ assert new is not None
+ assert manager.consume(SCOPE, new.code, 1) == ({"action": "bind"}, "new")
+
+
+def test_old_network_result_cannot_replace_new_results():
+ manager = PendingManager()
+ old_generation = manager.begin(SCOPE)
+ new_generation = manager.begin(SCOPE)
+ new = manager.publish(SCOPE, new_generation, "read-only", ["right"])
+ assert manager.publish(SCOPE, old_generation, "bind", ["wrong"]) is None
+ assert manager.consume(SCOPE, new.code, 1) == ("read-only", "right")
+
+
+def test_generation_can_publish_only_once_and_empty_results_invalidate_it():
+ manager = PendingManager()
+ first = publish(manager)
+ assert manager.publish(SCOPE, first.generation, "bind", ["wrong"]) is None
+ assert manager.consume(SCOPE, first.code, 1)[0] is first.request
+ generation = manager.begin(SCOPE)
+ assert manager.publish(SCOPE, generation, "empty", []) is None
+ assert manager.publish(SCOPE, generation, "late", ["wrong"]) is None
+
+
+@pytest.mark.parametrize("index", [0, -1, 3, "1", True, 1.5])
+def test_out_of_range_or_invalid_index_preserves_valid_request(index):
+ manager = PendingManager()
+ pending = publish(manager)
+ with pytest.raises(ValueError, match="序号"):
+ manager.consume(SCOPE, pending.code, index)
+ assert manager.consume(SCOPE, pending.code, 1)[0] is pending.request
+
+
+def test_expiry_boundary_and_no_generation_reuse_after_cleanup():
+ clock = Clock()
+ manager = PendingManager(ttl=120, clock=clock)
+ pending = publish(manager)
+ clock.now += 120
+ with pytest.raises(ValueError):
+ manager.consume(SCOPE, pending.code, 1)
+ assert not manager.cancel(SCOPE, pending.code)
+ replacement = manager.begin(SCOPE)
+ assert replacement != pending.generation
+ assert manager.publish(SCOPE, pending.generation, "old", ["wrong"]) is None
+ assert manager.publish(SCOPE, replacement, "new", ["right"]) is not None
+
+
+def test_unpublished_network_request_expires_and_publication_starts_selection_ttl():
+ clock = Clock()
+ manager = PendingManager(ttl=120, clock=clock)
+ expired = manager.begin(SCOPE)
+ clock.now += 120
+ assert manager.publish(SCOPE, expired, "old", ["wrong"]) is None
+ generation = manager.begin(SCOPE)
+ clock.now += 90
+ pending = manager.publish(SCOPE, generation, "new", ["right"])
+ clock.now += 119
+ assert manager.consume(SCOPE, pending.code, 1) == ("new", "right")
+
+
+def test_cancel_is_scoped_single_use_and_does_not_cancel_replacement():
+ manager = PendingManager()
+ first = publish(manager)
+ second = publish(manager)
+ assert not manager.cancel(SCOPE, first.code)
+ assert manager.cancel(SCOPE, second.code)
+ assert not manager.cancel(SCOPE, second.code)
+ with pytest.raises(ValueError):
+ manager.consume(SCOPE, second.code, 1)
+ assert manager.publish(SCOPE, second.generation, "late", ["wrong"]) is None
+
+
+def test_capacity_evicts_oldest_without_resurrecting_its_network_generation():
+ manager = PendingManager(max_entries=2)
+ one = publish(manager)
+ two = publish(manager, ("p", "s", "2"))
+ three = publish(manager, ("p", "s", "3"))
+ with pytest.raises(ValueError):
+ manager.consume(SCOPE, one.code, 1)
+ assert manager.publish(SCOPE, one.generation, "late", ["wrong"]) is None
+ assert manager.consume(two.scope, two.code, 1)[0] is two.request
+ assert manager.consume(three.scope, three.code, 1)[0] is three.request
+
+
+def test_simultaneous_consume_only_succeeds_once():
+ manager = PendingManager()
+ pending = publish(manager)
+
+ def choose(_):
+ try:
+ return manager.consume(SCOPE, pending.code, 1)
+ except ValueError:
+ return None
+
+ with ThreadPoolExecutor(max_workers=4) as executor:
+ results = list(executor.map(choose, range(8)))
+ assert sum(result is not None for result in results) == 1
+
+
+def test_generation_check_does_not_consume_or_extend_and_expires_at_boundary():
+ clock = Clock()
+ manager = PendingManager(ttl=120, clock=clock)
+ generation = manager.begin(SCOPE)
+ assert manager.is_current(SCOPE, generation)
+ assert not manager.is_current(("other", "session", "user"), generation)
+ pending = manager.publish(SCOPE, generation, "bind", ["player"])
+ assert manager.is_current(SCOPE, generation)
+ assert manager.is_current(SCOPE, generation)
+ assert manager.consume(SCOPE, pending.code, 1) == ("bind", "player")
+ assert not manager.is_current(SCOPE, generation)
+ executing = manager.begin(SCOPE)
+ clock.now += 119
+ assert manager.is_current(SCOPE, executing)
+ clock.now += 1
+ assert not manager.is_current(SCOPE, executing)
+
+
+def test_new_operation_invalidates_selected_execution_generation():
+ manager = PendingManager()
+ pending = publish(manager, request="bind", candidates=["player"])
+ manager.consume(SCOPE, pending.code, 1)
+ execution = manager.begin(SCOPE)
+ assert manager.is_current(SCOPE, execution)
+ replacement = manager.begin(SCOPE)
+ assert not manager.is_current(SCOPE, execution)
+ assert manager.is_current(SCOPE, replacement)
+
+
+def test_clear_invalidates_all_scopes_and_prevents_late_publication():
+ manager = PendingManager()
+ published = publish(manager)
+ other_scope = ("p", "s", "another")
+ network_generation = manager.begin(other_scope)
+ manager.clear()
+ manager.clear()
+ assert not manager.is_current(SCOPE, published.generation)
+ assert not manager.is_current(other_scope, network_generation)
+ with pytest.raises(ValueError):
+ manager.consume(SCOPE, published.code, 1)
+ assert not manager.cancel(SCOPE, published.code)
+ new_generation = manager.begin(other_scope)
+ assert new_generation > network_generation
+ assert manager.publish(other_scope, network_generation, "old", ["wrong"]) is None
+ assert manager.publish(SCOPE, published.generation, "old", ["wrong"]) is None
+ assert manager.publish(other_scope, new_generation, "new", ["right"]) is not None
+
+
+def test_pending_configuration_requires_bounded_lifetime_and_capacity():
+ for ttl in [0, -1, float("nan"), float("inf")]:
+ with pytest.raises(ValueError):
+ PendingManager(ttl=ttl)
+ for maximum in [0, -1, 1.5, True]:
+ with pytest.raises(ValueError):
+ PendingManager(max_entries=maximum)
diff --git a/tests/test_quota_storage.py b/tests/test_quota_storage.py
new file mode 100644
index 0000000..a941072
--- /dev/null
+++ b/tests/test_quota_storage.py
@@ -0,0 +1,402 @@
+"""Persistent quota accounting with real temporary SQLite connections.
+
+No API requests: all dates, contention, cancellation and failures are local.
+"""
+
+import asyncio
+from dataclasses import FrozenInstanceError
+from datetime import datetime
+import sqlite3
+
+import pytest
+
+from quota import GLOBAL_DAILY_LIMIT, QuotaActor, QuotaExceededError, quota_day
+from storage import Binding, Storage
+
+
+class Clock:
+ def __init__(self, value="2026-11-17T15:59:59+00:00"):
+ self.now = datetime.fromisoformat(value).timestamp()
+
+ def __call__(self):
+ return self.now
+
+
+@pytest.fixture
+async def stores(tmp_path):
+ connections, tasks = [], []
+ clock = Clock()
+
+ async def connect():
+ store = Storage(tmp_path / "plugin-data", clock=clock)
+ await store.open()
+ connections.append(store)
+ return store
+
+ def spawn(coroutine):
+ task = asyncio.create_task(coroutine)
+ tasks.append(task)
+ return task
+
+ try:
+ yield connect, clock, spawn
+ finally:
+ for task in tasks:
+ if not task.done():
+ task.cancel()
+ await asyncio.gather(*tasks, return_exceptions=True)
+ for store in connections:
+ await store.close()
+
+
+def assert_exceeded(error, scope, limit, used):
+ assert isinstance(error, ValueError)
+ assert error.code == "daily_quota"
+ assert (error.scope, error.limit, error.used) == (scope, limit, used)
+ assert "北京时间 0 点重置" in str(error)
+ assert str(limit) in str(error) and str(used) in str(error)
+
+
+def test_actor_is_immutable_and_preserves_identity_strings():
+ actor = QuotaActor("onebot:001", "00012345678901234567890")
+ assert actor.group == ""
+ assert actor.user == "00012345678901234567890"
+ with pytest.raises(FrozenInstanceError):
+ actor.user = "another"
+
+
+@pytest.mark.parametrize("args", [
+ ("", "u"), ("p", ""), (" ", "u"), ("p", " \t"),
+ (None, "u"), ("p", 123), ("p", "u", None), ("p", "u", " "),
+])
+def test_actor_rejects_missing_platform_or_user_and_invalid_group(args):
+ with pytest.raises(ValueError):
+ QuotaActor(*args)
+
+
+@pytest.mark.parametrize(("iso", "expected"), [
+ ("2026-11-17T15:59:59.999999+00:00", "2026-11-17"),
+ ("2026-11-17T16:00:00+00:00", "2026-11-18"),
+ ("2026-12-31T16:00:00+00:00", "2027-01-01"),
+])
+def test_quota_day_uses_beijing_calendar_boundary(iso, expected):
+ assert quota_day(datetime.fromisoformat(iso).timestamp()) == expected
+
+
+async def test_usage_is_read_only_and_actor_none_counts_global_only(stores):
+ connect, _, _ = stores
+ store = await connect()
+ actor = QuotaActor("p", "u", "g")
+ before_changes = store._connection().total_changes
+ assert await store.quota_usage() == {"day": "2026-11-17", "global": 0, "user": None, "group": None}
+ assert await store.quota_usage(actor) == {"day": "2026-11-17", "global": 0, "user": 0, "group": 0}
+ assert store._connection().total_changes == before_changes
+ assert await store.consume_request() == {"day": "2026-11-17", "global": 1, "user": None, "group": None}
+ assert await store.quota_usage(actor) == {"day": "2026-11-17", "global": 1, "user": 0, "group": 0}
+
+
+async def test_default_user_twenty_boundary_does_not_charge_other_buckets(stores):
+ connect, _, _ = stores
+ store = await connect()
+ actor = QuotaActor("p", "u", "group-one")
+ for count in range(1, 21):
+ assert (await store.consume_request(actor))["user"] == count
+ another_group = QuotaActor("p", "u", "group-two")
+ with pytest.raises(QuotaExceededError) as error:
+ await store.consume_request(another_group)
+ assert_exceeded(error.value, "user", 20, 20)
+ assert await store.quota_usage(another_group) == {
+ "day": "2026-11-17", "global": 20, "user": 20, "group": 0,
+ }
+ assert (await store.quota_usage(actor))["group"] == 20
+ assert (await store.consume_request(QuotaActor("p", "other", "group-two")))["global"] == 21
+
+
+async def test_group_accumulates_across_users_and_rejection_does_not_charge_new_user(stores):
+ connect, _, _ = stores
+ store = await connect()
+ for index in range(3):
+ result = await store.consume_request(QuotaActor("p", str(index), "g"), group_limit=3)
+ assert result["user"] == 1
+ assert result["group"] == index + 1
+ actor = QuotaActor("p", "new-user", "g")
+ with pytest.raises(QuotaExceededError) as error:
+ await store.consume_request(actor, group_limit=3)
+ assert_exceeded(error.value, "group", 3, 3)
+ assert await store.quota_usage(actor) == {"day": "2026-11-17", "global": 3, "user": 0, "group": 3}
+ assert await store.consume_request(QuotaActor("p", actor.user, "other"), group_limit=3) == {
+ "day": "2026-11-17", "global": 4, "user": 1, "group": 1,
+ }
+
+
+async def test_user_shared_across_groups_and_private_but_platforms_are_isolated(stores):
+ connect, _, _ = stores
+ store = await connect()
+ for group in ("g1", "g2", ""):
+ await store.consume_request(QuotaActor("p1", "u", group), user_limit=3)
+ private = QuotaActor("p1", "u")
+ with pytest.raises(QuotaExceededError) as error:
+ await store.consume_request(private, user_limit=3)
+ assert_exceeded(error.value, "user", 3, 3)
+ assert await store.quota_usage(private) == {"day": "2026-11-17", "global": 3, "user": 3, "group": None}
+ assert (await store.quota_usage(QuotaActor("p1", "u", "g1")))["group"] == 1
+ assert await store.consume_request(QuotaActor("p2", "u", "g1"), user_limit=3) == {
+ "day": "2026-11-17", "global": 4, "user": 1, "group": 1,
+ }
+
+
+@pytest.mark.parametrize("unlimited", [False, True])
+async def test_fixed_global_hundred_and_default_group_hundred_boundaries(stores, unlimited):
+ connect, _, _ = stores
+ store = await connect()
+ assert GLOBAL_DAILY_LIMIT == 100
+ for index in range(100):
+ actor = QuotaActor("p", "one-user" if unlimited else str(index // 20), "g")
+ result = await store.consume_request(actor, user_limit=0 if unlimited else 20,
+ group_limit=0 if unlimited else 100)
+ assert result["global"] == 100 and result["group"] == 100
+ assert result["user"] == (100 if unlimited else 20)
+ rejected = QuotaActor("new-platform", "new-user", "new-group")
+ with pytest.raises(QuotaExceededError) as error:
+ await store.consume_request(rejected, user_limit=0, group_limit=0)
+ assert_exceeded(error.value, "global", 100, 100)
+ assert await store.quota_usage(rejected) == {"day": "2026-11-17", "global": 100, "user": 0, "group": 0}
+ with pytest.raises(QuotaExceededError) as error:
+ await store.consume_request()
+ assert_exceeded(error.value, "global", 100, 100)
+
+
+@pytest.mark.parametrize("scope", ["user", "group"])
+async def test_lowered_limits_apply_to_already_recorded_unlimited_usage(stores, scope):
+ connect, _, _ = stores
+ store = await connect()
+ actor = QuotaActor("p", "u", "g")
+ for _ in range(4):
+ await store.consume_request(actor, user_limit=0, group_limit=0)
+ limits = {"user_limit": 0, "group_limit": 0, f"{scope}_limit": 3}
+ with pytest.raises(QuotaExceededError) as error:
+ await store.consume_request(actor, **limits)
+ assert_exceeded(error.value, scope, 3, 4)
+ assert await store.quota_usage(actor) == {"day": "2026-11-17", "global": 4, "user": 4, "group": 4}
+ limits[f"{scope}_limit"] = 5
+ assert await store.consume_request(actor, **limits) == {
+ "day": "2026-11-17", "global": 5, "user": 5, "group": 5,
+ }
+
+
+@pytest.mark.parametrize(("scope", "limit", "kwargs"), [
+ ("global", 100, {"user_limit": 0, "group_limit": 0}),
+ ("user", 20, {"user_limit": 20, "group_limit": 0}),
+ ("group", 30, {"user_limit": 0, "group_limit": 30}),
+])
+async def test_multiple_connections_cannot_overdraw_any_bucket(stores, scope, limit, kwargs):
+ connect, _, spawn = stores
+ connections = [await connect() for _ in range(4)]
+ actor = QuotaActor("p", "u", "g")
+ tasks = [spawn(connections[index % 4].consume_request(actor, **kwargs))
+ for index in range(limit + 20)]
+ results = await asyncio.gather(*tasks, return_exceptions=True)
+ successes = [result for result in results if isinstance(result, dict)]
+ failures = [result for result in results if isinstance(result, BaseException)]
+ assert len(successes) == limit
+ assert len(failures) == 20
+ assert sorted(result["global"] for result in successes) == list(range(1, limit + 1))
+ for error in failures:
+ assert isinstance(error, QuotaExceededError)
+ assert_exceeded(error, scope, limit, limit)
+ for store in connections:
+ assert await store.quota_usage(actor) == {
+ "day": "2026-11-17", "global": limit, "user": limit, "group": limit,
+ }
+
+
+async def test_beijing_midnight_resets_all_daily_views_without_erasing_prior_day(stores):
+ connect, clock, _ = stores
+ store = await connect()
+ actor = QuotaActor("p", "u", "g")
+ await store.consume_request(actor, user_limit=1)
+ with pytest.raises(QuotaExceededError):
+ await store.consume_request(actor, user_limit=1)
+ clock.now += 1 # Beijing 23:59:59 -> 00:00:00
+ assert await store.quota_usage(actor) == {"day": "2026-11-18", "global": 0, "user": 0, "group": 0}
+ assert await store.consume_request(actor, user_limit=1) == {
+ "day": "2026-11-18", "global": 1, "user": 1, "group": 1,
+ }
+ clock.now -= 1
+ assert await store.quota_usage(actor) == {"day": "2026-11-17", "global": 1, "user": 1, "group": 1}
+
+
+async def test_date_is_evaluated_after_obtaining_cross_connection_write_lock(stores):
+ connect, clock, spawn = stores
+ locker, contender = await connect(), await connect()
+ actor = QuotaActor("p", "u", "g")
+ loop = asyncio.get_running_loop()
+ begin_started = asyncio.Event()
+
+ def trace(sql):
+ if sql == "BEGIN IMMEDIATE":
+ loop.call_soon_threadsafe(begin_started.set)
+
+ await contender._connection().set_trace_callback(trace)
+ async with locker._connection().execute("BEGIN IMMEDIATE"):
+ pass
+ try:
+ task = spawn(contender.consume_request(actor))
+ await asyncio.wait_for(begin_started.wait(), 2)
+ clock.now += 1
+ finally:
+ await locker._connection().rollback()
+ assert (await asyncio.wait_for(task, 2))["day"] == "2026-11-18"
+ clock.now -= 1
+ assert (await locker.quota_usage())["global"] == 0
+
+
+async def test_reload_cache_clear_prune_and_binding_namespace_changes_keep_usage(stores):
+ connect, _, _ = stores
+ store = await connect()
+ actor = QuotaActor("p", "u", "g")
+ expected = await store.consume_request(actor)
+ original = Binding("source:old-credentials", "001", "Synthetic")
+ await store.set_binding("p", "u", original)
+ await store.put_cache("source:old-credentials", {}, 10)
+ await store.clear_cache()
+ await store.prune_cache(max_entries=0, max_age_seconds=0)
+ assert await store.quota_usage(actor) == expected
+ assert await store.get_binding("p", "u") == original
+ await store.close()
+ reopened = await connect()
+ assert await reopened.quota_usage(actor) == expected
+ await reopened.set_binding("p", "u", Binding("source:new-credentials", "002", "Other"))
+ await reopened.put_cache("source:new-credentials", [], 10)
+ assert await reopened.quota_usage(actor) == expected
+ assert (await reopened.consume_request(actor))["global"] == 2
+
+
+async def test_sql_error_after_partial_bucket_updates_rolls_back_everything(stores):
+ connect, _, _ = stores
+ store, observer = await connect(), await connect()
+ actor = QuotaActor("p", "u", "g")
+ db = store._connection()
+ async with db.execute(
+ "CREATE TEMP TRIGGER reject_group BEFORE INSERT ON request_quotas "
+ "WHEN NEW.scope = 'group' BEGIN SELECT RAISE(ABORT, 'synthetic quota failure'); END"
+ ):
+ pass
+ with pytest.raises(sqlite3.IntegrityError, match="synthetic quota failure"):
+ await store.consume_request(actor)
+ assert not db.in_transaction
+ for connection in (store, observer):
+ assert await connection.quota_usage(actor) == {
+ "day": "2026-11-17", "global": 0, "user": 0, "group": 0,
+ }
+ async with db.execute("DROP TRIGGER reject_group"):
+ pass
+ assert (await store.consume_request(actor))["global"] == 1
+
+
+async def test_cancellation_before_commit_rolls_back_and_finishes_cleanup(stores, monkeypatch):
+ connect, _, spawn = stores
+ store, observer = await connect(), await connect()
+ actor = QuotaActor("p", "u", "g")
+ db = store._connection()
+ commit_started, rollback_started, allow_rollback = asyncio.Event(), asyncio.Event(), asyncio.Event()
+ original_rollback = db.rollback
+
+ async def paused_commit():
+ commit_started.set()
+ await asyncio.Event().wait()
+
+ async def paused_rollback():
+ rollback_started.set()
+ await allow_rollback.wait()
+ await original_rollback()
+
+ with monkeypatch.context() as patch:
+ patch.setattr(db, "commit", paused_commit)
+ patch.setattr(db, "rollback", paused_rollback)
+ task = spawn(store.consume_request(actor))
+ try:
+ await asyncio.wait_for(commit_started.wait(), 2)
+ task.cancel()
+ await asyncio.wait_for(rollback_started.wait(), 2)
+ task.cancel() # repeated cancellation must not abandon rollback
+ finally:
+ allow_rollback.set()
+ with pytest.raises(asyncio.CancelledError):
+ await asyncio.wait_for(task, 2)
+ assert not db.in_transaction
+ assert await observer.quota_usage(actor) == {"day": "2026-11-17", "global": 0, "user": 0, "group": 0}
+ assert (await store.consume_request(actor))["global"] == 1
+
+
+async def test_cancelled_queued_begin_cannot_leave_an_open_transaction(stores):
+ connect, _, spawn = stores
+ locker, contender = await connect(), await connect()
+ loop = asyncio.get_running_loop()
+ begin_started = asyncio.Event()
+
+ def trace(sql):
+ if sql == "BEGIN IMMEDIATE":
+ loop.call_soon_threadsafe(begin_started.set)
+
+ await contender._connection().set_trace_callback(trace)
+ async with locker._connection().execute("BEGIN IMMEDIATE"):
+ pass
+ try:
+ task = spawn(contender.consume_request(QuotaActor("p", "u", "g")))
+ await asyncio.wait_for(begin_started.wait(), 2)
+ task.cancel()
+ finally:
+ await locker._connection().rollback()
+ with pytest.raises(asyncio.CancelledError):
+ await asyncio.wait_for(task, 2)
+ assert not contender._connection().in_transaction
+ assert (await locker.quota_usage())["global"] == 0
+ assert (await contender.consume_request())["global"] == 1
+
+
+@pytest.mark.parametrize("invalid", [-1, 1.5, True, "20"])
+async def test_invalid_limits_are_rejected_without_charging(stores, invalid):
+ connect, _, _ = stores
+ store = await connect()
+ for field in ("user_limit", "group_limit"):
+ with pytest.raises(ValueError):
+ await store.consume_request(QuotaActor("p", "u", "g"), **{field: invalid})
+ assert (await store.quota_usage())["global"] == 0
+
+
+@pytest.mark.parametrize("reject_at", [1, 2])
+async def test_changed_admission_rolls_back_all_buckets(stores, reject_at):
+ from quota import AdmissionDeferred
+ connect, _, _ = stores
+ store, observer = await connect(), await connect()
+ actor = QuotaActor("p", "u", "g")
+ calls = 0
+ def ready():
+ nonlocal calls
+ calls += 1
+ return calls != reject_at
+ with pytest.raises(AdmissionDeferred):
+ await store.consume_request(actor, ready=ready)
+ assert not store._connection().in_transaction
+ assert (await observer.quota_usage(actor))["global"] == 0
+ assert (await store.consume_request(actor))["global"] == 1
+
+
+async def test_midnight_during_reservation_rolls_back_before_retry(stores):
+ from quota import AdmissionDeferred
+ connect, clock, _ = stores
+ store = await connect()
+ actor = QuotaActor("p", "u", "g")
+ original = store._quota_usage
+ async def cross_midnight(*args):
+ usage = await original(*args)
+ clock.now += 1
+ return usage
+ store._quota_usage = cross_midnight
+ with pytest.raises(AdmissionDeferred):
+ await store.consume_request(actor)
+ store._quota_usage = original
+ assert (await store.consume_request(actor))["day"] == "2026-11-18"
+ clock.now -= 1
+ assert (await store.quota_usage(actor))["global"] == 0
diff --git a/tests/test_render.py b/tests/test_render.py
new file mode 100644
index 0000000..453c538
--- /dev/null
+++ b/tests/test_render.py
@@ -0,0 +1,256 @@
+"""Presentation/security behavior; fixed synthetic values, no browser or API."""
+
+from copy import deepcopy
+from datetime import datetime, timezone
+from html.parser import HTMLParser
+import re
+
+from jinja2 import Environment
+from markupsafe import Markup
+import pytest
+
+from render import Renderer
+
+
+class VisibleHTML(HTMLParser):
+ def __init__(self, html):
+ super().__init__(convert_charrefs=True)
+ self.in_body = False
+ self.parts = []
+ self.tags = []
+ self.feed(html)
+
+ def handle_starttag(self, tag, attrs):
+ self.tags.append((tag, dict(attrs)))
+ if tag == "body":
+ self.in_body = True
+
+ def handle_endtag(self, tag):
+ if tag == "body":
+ self.in_body = False
+
+ def handle_data(self, data):
+ if self.in_body:
+ self.parts.append(data)
+
+ @property
+ def text(self):
+ return " ".join(self.parts)
+
+
+def compact(value):
+ return re.sub(r"\s+", "", value)
+
+
+@pytest.fixture
+def view():
+ return {
+ "kind": "overview",
+ "player": {"id": "00076561198012345678", "name": "合成样本玩家"},
+ "metrics": [
+ {"label": "近期胜率", "value": 62.5, "format": "percent"},
+ {"label": "实际样本", "value": 8, "format": "integer", "unit": "场"},
+ {"label": "单位交换比", "value": 1.234},
+ {"label": "价值交换比", "value": 2.789},
+ ],
+ "scope": "已取得的 8 场排位样本 · 非完整历史",
+ "fetched_at": "2026-11-17T02:30:00Z",
+ "source_updated_at": "2026-11-17T02:20:00+00:00",
+ "source_url": "https://example.invalid/player/preview?scope=recent&n=8",
+ "synthetic": True,
+ }
+
+
+@pytest.mark.parametrize("theme", ["dark", "light"])
+def test_identity_scope_precision_and_same_text_values(view, theme):
+ renderer = Renderer(theme=theme)
+ html = renderer.template(view)
+ visible = VisibleHTML(html).text
+ text = renderer.text(view)
+ for value in [
+ "00076561198012345678", "合成样本玩家", view["scope"],
+ "62.50%", "8场", "1.23", "2.79", "2026-11-17 10:30 CST",
+ "2026-11-17 10:20 CST", "合成样本", view["source_url"],
+ ]:
+ assert compact(value) in compact(visible)
+ assert compact(value) in compact(text)
+ assert f'data-theme="{theme}"' in html
+ assert visible.index("合成样本玩家") < visible.index(view["scope"]) < visible.index("近期胜率")
+
+
+@pytest.mark.parametrize("kind", ["overview", "recent", "match"])
+def test_external_text_is_escaped_in_every_card(view, kind):
+ attack = '
& "玩家"'
+ view.update(
+ kind=kind, title=attack, scope=attack, notes=[attack],
+ player={"id": attack, "name": Markup(attack)},
+ metrics=[{"label": attack, "value": attack, "unit": attack, "note": attack}],
+ rows=[{"id": attack, "map_name": attack, "mode": attack}],
+ match={"id": attack, "map_name": attack, "winner": attack},
+ teams=[{"name": attack, "players": [{"id": attack, "name": attack}]}],
+ common_units=[{"name": attack}],
+ )
+ renderer = Renderer()
+ html = renderer.template(view)
+ visible = VisibleHTML(html)
+ assert "<img" in html
+ assert not any(tag in {"img", "script", "iframe"} for tag, _ in visible.tags)
+ assert attack in visible.text
+ assert attack in renderer.text(view)
+
+
+def test_jinja_literal_nickname_survives_fixed_astrbot_wrapper(view):
+ nickname = '{{7*7}} {% if true %}字面昵称{% endif %} {#注释也保留#} <玩家>&'
+ view["player"]["name"] = nickname
+ renderer = Renderer()
+ html = renderer.template(view)
+ wrapped = Environment(autoescape=True).from_string("{{ body | safe }}").render(body=html)
+ assert nickname in VisibleHTML(wrapped).text
+ assert nickname in renderer.text(view)
+ assert "<玩家>" not in wrapped
+ assert "{{7*7}}" in wrapped
+
+
+@pytest.mark.parametrize("url", [
+ "javascript:alert(1)", "data:text/html,test", "file:///C:/secret", "//example.invalid",
+ "https://name:password@example.invalid/", "https://example.invalid\n/evil",
+ "https:\\example.invalid", "https://", "https://example.invalid:99999/", "https://[broken/",
+])
+def test_unsafe_source_urls_are_omitted_everywhere(view, url):
+ view.update(source_url=url, player={"id": "id", "name": "name", "source_url": url})
+ view["kind"] = "recent"
+ view["rows"] = [{"id": "match", "source_url": url}]
+ renderer = Renderer()
+ assert not any("href" in attrs for _, attrs in VisibleHTML(renderer.template(view)).tags)
+ assert url not in renderer.text(view)
+ assert "数据来源:暂无" in renderer.text(view)
+
+
+def test_safe_http_links_are_escaped_not_loaded(view):
+ renderer = Renderer()
+ html = renderer.template(view)
+ parsed = VisibleHTML(html)
+ assert ("a", {"href": view["source_url"], "rel": "noreferrer noopener"}) in parsed.tags
+ assert "&n=8" in html
+ assert not any(tag in {"img", "iframe", "script", "link"} for tag, _ in parsed.tags)
+ assert "@import" not in html and "url(" not in html
+
+
+@pytest.mark.parametrize("value", [None, "", " ", float("nan"), float("inf"), True])
+def test_missing_metric_is_unknown_without_fake_zero_or_unit(view, value):
+ view["metrics"] = [{"label": "ELO", "value": value, "unit": "分"}]
+ renderer = Renderer()
+ assert "ELO:暂无" in renderer.text(view)
+ assert "暂无分" not in compact(VisibleHTML(renderer.template(view)).text)
+ assert "0.00" not in renderer.text(view)
+
+
+def test_real_zero_and_unknown_stay_distinct(view):
+ view.update(kind="recent", rows=[{
+ "id": "zero", "kills": 0, "losses": None, "destroyed_value": 0,
+ "lost_value": None, "unit_exchange": None, "value_exchange": None,
+ "duration_seconds": 0, "elo_delta": 0,
+ }])
+ text = Renderer().text(view)
+ assert "摧毁单位:0 个" in text
+ assert "损失单位:暂无" in text
+ assert "摧毁价值:0.00" in text
+ assert "损失价值:暂无" in text
+ assert "价值交换比:暂无" in text
+ assert "胜负暂无" in text
+ assert "时长:0分00秒" in text
+ assert "ELO 变化:+0.00" in text
+
+
+def test_exchange_values_are_separate_and_not_recalculated(view):
+ view.update(kind="recent", rows=[{
+ "id": "ratios", "kills": 8, "losses": 2, "unit_exchange": 4,
+ "destroyed_value": 2500.5, "lost_value": 2000.75, "value_exchange": 1.249,
+ }])
+ renderer = Renderer()
+ html_text = compact(VisibleHTML(renderer.template(view)).text)
+ text = renderer.text(view)
+ for expected in ["摧毁单位:8 个", "损失单位:2 个", "单位交换比:4.00",
+ "摧毁价值:2500.50", "损失价值:2000.75", "价值交换比:1.25"]:
+ assert expected in text
+ assert compact(expected.replace(":", "")) in html_text
+
+
+def test_stale_and_absent_timestamps_are_visible(view):
+ view.update(stale=True, fetched_at=None, source_updated_at="2026-11-17T02:20:00")
+ renderer = Renderer()
+ for output in [renderer.text(view), VisibleHTML(renderer.template(view)).text]:
+ assert "旧缓存" in output
+ assert "抓取时间:暂无" in compact(output)
+ assert "来源更新:暂无" in compact(output)
+
+
+def test_timezone_aware_datetime_conversion(view):
+ view["fetched_at"] = datetime(2026, 11, 17, 2, 30, tzinfo=timezone.utc)
+ assert "2026-11-16 21:30 EST" in Renderer(timezone="America/New_York").text(view)
+
+
+def test_recent_pagination_preserves_every_row_scope_and_input(view):
+ view.update(kind="recent", rows=[{"id": f"match-{i:03}"} for i in range(20)])
+ before = deepcopy(view)
+ renderer = Renderer()
+ pages = renderer.views(view)
+ assert [len(page["rows"]) for page in pages] == [5, 5, 5, 5]
+ assert [row["id"] for page in pages for row in page["rows"]] == [row["id"] for row in view["rows"]]
+ assert "第 2/4 页 · 本页 6–10 场 / 共 20 场" in renderer.text(pages[1])
+ assert "match-005" in renderer.text(pages[1])
+ assert "match-000" not in renderer.text(pages[1])
+ assert all(page["scope"] == view["scope"] and page["player"] == view["player"] for page in pages)
+ pages[0]["rows"][0]["id"] = "changed"
+ assert view == before
+
+
+@pytest.mark.parametrize("kind,empty_label", [
+ ("overview", "统计指标:暂无"), ("recent", "近期对局:暂无"), ("match", "分队与玩家:暂无"),
+])
+def test_empty_card_has_explicit_unknown_state(kind, empty_label):
+ renderer = Renderer()
+ view = {"kind": kind}
+ assert empty_label in renderer.text(view)
+ assert compact(empty_label) in compact(VisibleHTML(renderer.template(view)).text)
+ assert len(renderer.views(view)) == 1
+
+
+def test_variable_team_sizes_keep_all_players_and_no_placeholder_opponents(view):
+ view.update(kind="match", match={"id": "000123", "map_name": "合成地图", "winner": "蓝队"}, teams=[
+ {"name": "蓝队", "outcome": "win", "players": [{"id": f"a{i}", "name": f"蓝方{i}"} for i in range(3)]},
+ {"name": "红队", "outcome": "loss", "players": [{"id": "b", "name": "红方0"}]},
+ {"name": "未分配", "players": []},
+ ])
+ renderer = Renderer()
+ html = renderer.template(view)
+ assert html.count('class="participant"') == 4
+ for expected in ["3 人", "1 人", "0 人", "队员:暂无", "蓝方2", "红方0", "000123"]:
+ assert compact(expected) in compact(VisibleHTML(html).text)
+ assert expected in renderer.text(view)
+
+
+def test_long_nickname_is_not_truncated(view):
+ name = "中文非常长的合成昵称MixedNickname_" * 20
+ view["player"]["name"] = name
+ renderer = Renderer()
+ assert name in VisibleHTML(renderer.template(view)).text
+ assert name in renderer.text(view)
+
+
+def test_invalid_count_does_not_silently_round(view):
+ view["metrics"] = [{"label": "实际样本", "value": 1.5, "format": "integer", "unit": "场"}]
+ assert "实际样本:暂无" in Renderer().text(view)
+
+
+@pytest.mark.parametrize("size", [0, 6, True, 2.5])
+def test_page_size_rejects_unbounded_cards(view, size):
+ with pytest.raises(ValueError):
+ Renderer().views(view, page_size=size)
+
+
+def test_unknown_theme_and_kind_are_configuration_errors():
+ with pytest.raises(ValueError):
+ Renderer(theme="other")
+ with pytest.raises(ValueError):
+ Renderer().template({"kind": "other"})
diff --git a/tests/test_service.py b/tests/test_service.py
new file mode 100644
index 0000000..6644ceb
--- /dev/null
+++ b/tests/test_service.py
@@ -0,0 +1,472 @@
+"""Synthetic integration scenarios against the real service and SQLite store.
+
+Network completions use explicit events, never timing-dependent sleeps. The
+isolated package permits relative imports without importing AstrBot globally.
+"""
+
+import asyncio
+import importlib
+from pathlib import Path
+import re
+import sys
+from types import ModuleType, SimpleNamespace
+from datetime import datetime, timezone
+from unittest.mock import AsyncMock, call
+
+import httpx
+import pytest
+
+
+ROOT = Path(__file__).resolve().parents[1]
+NOW = datetime(2026, 11, 17, tzinfo=timezone.utc)
+
+
+@pytest.fixture
+def modules(monkeypatch):
+ name = "_ba_stats_service_contract"
+ package = ModuleType(name)
+ package.__path__ = [str(ROOT)]
+ monkeypatch.setitem(sys.modules, name, package)
+ try:
+ yield SimpleNamespace(**{
+ part: importlib.import_module(f"{name}.{part}")
+ for part in ("service", "models", "commands", "storage", "settings", "client")
+ })
+ finally:
+ for key in tuple(sys.modules):
+ if key.startswith(name + "."):
+ sys.modules.pop(key, None)
+
+
+@pytest.fixture
+async def h(modules, tmp_path):
+ m = modules.models
+
+ def result(data, **kwargs):
+ return m.FetchResult(data, NOW, **kwargs)
+
+ player = m.Player("001", "Synthetic Player", source_url="https://example.invalid/players/001")
+ client = SimpleNamespace(
+ namespace="batrace:synthetic", player=AsyncMock(return_value=result(player)),
+ search=AsyncMock(return_value=result([player])), recent=AsyncMock(return_value=result([])),
+ match=AsyncMock(),
+ )
+ storage = modules.storage.Storage(tmp_path / "service-data")
+ await storage.open()
+ settings = modules.settings.Settings(cooldown_seconds=0)
+ service = modules.service.StatsService(client, storage, settings)
+ caller = modules.service.Caller("onebot:test", "group:one", "10001")
+ tasks = []
+
+ async def run(text, who=None):
+ return await service.execute(modules.commands.parse_command(text), who or caller)
+
+ def spawn(coro):
+ task = asyncio.create_task(coro)
+ tasks.append(task)
+ return task
+
+ try:
+ yield SimpleNamespace(
+ m=m, modules=modules, client=client, storage=storage, service=service,
+ caller=caller, run=run, result=result, player=player, spawn=spawn,
+ Binding=modules.storage.Binding,
+ )
+ finally:
+ for task in tasks:
+ if not task.done():
+ task.cancel()
+ await asyncio.gather(*tasks, return_exceptions=True)
+ service.close()
+ await storage.close()
+
+
+def select_command(response):
+ match = re.search(r"/ba select ([^\s]+) ([0-9]+)", response.text)
+ assert match, response.text
+ return f"select {match[1]} {match[2]}"
+
+
+async def seed(h, player_id="old", namespace=None):
+ binding = h.Binding(namespace or h.client.namespace, player_id, "Original", "https://example.invalid/original")
+ await h.storage.set_binding(h.caller.platform, h.caller.user, binding)
+ return binding
+
+
+async def binding(h):
+ return await h.storage.get_binding(h.caller.platform, h.caller.user)
+
+
+async def test_help_binding_unbind_work_with_real_unconfigured_client(h):
+ def forbidden_network(request):
+ raise AssertionError("Local commands must not contact the upstream")
+
+ c = h.modules.client
+ async with httpx.AsyncClient(transport=httpx.MockTransport(forbidden_network)) as http:
+ real_client = c.BatraceClient(c.ClientConfig(), storage=h.storage, http_client=http)
+ h.service.client = real_client
+ try:
+ await seed(h, namespace=real_client.namespace)
+ assert "/ba help" in (await h.run("help")).text
+ assert "old" in (await h.run("binding")).text
+ assert "解除" in (await h.run("unbind")).text
+ assert await binding(h) is None
+ with pytest.raises(c.NotConfiguredError, match="未配置"):
+ await h.run("search Synthetic")
+ assert real_client.status()["requests"] == 0
+ finally:
+ await real_client.close()
+
+
+async def test_single_bind_requires_one_choice_and_forces_identity_revalidation(h):
+ old = await seed(h)
+ renamed = h.m.Player("001", "Renamed", source_url=h.player.source_url)
+ h.client.player.side_effect = [h.result(h.player), h.result(renamed)]
+ offered = await h.run("bind stb:001")
+ assert "选择后绑定" in offered.text
+ assert h.player.source_url in offered.text
+ assert await binding(h) == old
+ command = select_command(offered)
+ response = await h.run(command)
+ assert "已绑定默认账号:Renamed" in response.text
+ assert (await binding(h)).player_id == "001"
+ assert (await binding(h)).display_name == "Renamed"
+ assert (await binding(h)).namespace == h.client.namespace
+ assert h.client.player.await_args_list == [call("001"), call("001", force=True)]
+ with pytest.raises(ValueError, match="过期"):
+ await h.run(command)
+ assert h.client.player.await_count == 2
+
+
+@pytest.mark.parametrize("failure", ["wrong_id", "stale", "upstream"])
+async def test_failed_final_identity_check_preserves_original_binding(h, failure):
+ old = await seed(h)
+ offered = await h.run("bind stb:001")
+ if failure == "upstream":
+ h.client.player.side_effect = h.modules.client.AuthenticationError("鉴权失败")
+ expected = h.modules.client.AuthenticationError
+ else:
+ player = h.m.Player("wrong" if failure == "wrong_id" else "001", "Synthetic")
+ h.client.player.return_value = h.result(player, stale=failure == "stale")
+ expected = ValueError
+ with pytest.raises(expected):
+ await h.run(select_command(offered))
+ assert await binding(h) == old
+ with pytest.raises(ValueError, match="过期"):
+ await h.run(select_command(offered))
+
+
+async def test_read_only_search_and_select_never_change_binding(h, monkeypatch):
+ old = await seed(h)
+ write = AsyncMock(wraps=h.storage.set_binding)
+ monkeypatch.setattr(h.storage, "set_binding", write)
+ offered = await h.run("search Synthetic Player")
+ assert "请选择要查询" in offered.text
+ assert await binding(h) == old
+ response = await h.run(select_command(offered))
+ assert response.view["kind"] == "overview"
+ assert response.view["player"]["id"] == "001"
+ assert await binding(h) == old
+ write.assert_not_awaited()
+ assert h.client.player.await_args_list == [call("001")]
+ h.client.recent.assert_awaited_once_with("001", h.service.settings.max_limit)
+
+
+async def test_late_search_cannot_publish_over_newer_candidates(h):
+ started, release = asyncio.Event(), asyncio.Event()
+ newer = h.m.Player("002", "New", source_url="https://example.invalid/players/002")
+
+ async def search(query):
+ if query == "Old":
+ started.set()
+ await release.wait()
+ return h.result([h.player])
+ return h.result([newer])
+
+ h.client.search.side_effect = search
+ old_task = h.spawn(h.run("search Old"))
+ await asyncio.wait_for(started.wait(), 2)
+ current = await h.run("search New")
+ release.set()
+ assert "覆盖" in (await old_task).text
+ h.client.player.return_value = h.result(newer)
+ response = await h.run(select_command(current))
+ assert response.view["player"]["id"] == "002"
+
+
+async def test_new_operation_during_selected_revalidation_prevents_binding(h):
+ old = await seed(h)
+ offered = await h.run("bind stb:001")
+ started, release = asyncio.Event(), asyncio.Event()
+
+ async def revalidate(player_id, *, force=False):
+ assert force
+ started.set()
+ await release.wait()
+ return h.result(h.player)
+
+ h.client.player.side_effect = revalidate
+ task = h.spawn(h.run(select_command(offered)))
+ await asyncio.wait_for(started.wait(), 2)
+ await h.run("help")
+ release.set()
+ assert "覆盖" in (await task).text
+ assert await binding(h) == old
+
+
+async def test_cross_group_unbind_wins_over_older_selected_revalidation(h):
+ await seed(h)
+ offered = await h.run("bind stb:001")
+ started, release = asyncio.Event(), asyncio.Event()
+
+ async def revalidate(player_id, *, force=False):
+ started.set()
+ await release.wait()
+ return h.result(h.player)
+
+ h.client.player.side_effect = revalidate
+ task = h.spawn(h.run(select_command(offered)))
+ await asyncio.wait_for(started.wait(), 2)
+ other_group = h.modules.service.Caller(h.caller.platform, "group:two", h.caller.user)
+ assert "解除" in (await h.run("unbind", other_group)).text
+ release.set()
+ assert "覆盖" in (await task).text
+ assert await binding(h) is None
+
+
+async def test_cross_group_unbind_serializes_with_already_started_binding_write(h, monkeypatch):
+ await seed(h)
+ offered = await h.run("bind stb:001")
+ entered, release = asyncio.Event(), asyncio.Event()
+ original_set = h.storage.set_binding
+
+ async def slow_set(*args):
+ entered.set()
+ await release.wait()
+ await original_set(*args)
+
+ monkeypatch.setattr(h.storage, "set_binding", slow_set)
+ selecting = h.spawn(h.run(select_command(offered)))
+ await asyncio.wait_for(entered.wait(), 2)
+ other_group = h.modules.service.Caller(h.caller.platform, "group:two", h.caller.user)
+ unbinding = h.spawn(h.run("unbind", other_group))
+ await asyncio.sleep(0) # let the unbind enter the service's mutation lock
+ assert not unbinding.done()
+ release.set()
+ await asyncio.gather(selecting, unbinding)
+ assert await binding(h) is None
+
+
+async def test_newer_cross_group_bind_cannot_be_overwritten_by_older_selection(h):
+ first = await h.run("bind stb:001")
+ second_player = h.m.Player("002", "Second", source_url="https://example.invalid/players/002")
+ h.client.player.return_value = h.result(second_player)
+ other_group = h.modules.service.Caller(h.caller.platform, "group:two", h.caller.user)
+ second = await h.run("bind stb:002", other_group)
+ started, release = asyncio.Event(), asyncio.Event()
+
+ async def revalidate(player_id, *, force=False):
+ if player_id == "001":
+ started.set()
+ await release.wait()
+ return h.result(h.player)
+ return h.result(second_player)
+
+ h.client.player.side_effect = revalidate
+ older = h.spawn(h.run(select_command(first)))
+ await asyncio.wait_for(started.wait(), 2)
+ assert "已绑定" in (await h.run(select_command(second), other_group)).text
+ release.set()
+ assert "覆盖" in (await older).text
+ assert (await binding(h)).player_id == "002"
+
+
+@pytest.mark.parametrize("target", ["me", "mention"])
+async def test_other_namespace_binding_is_rejected_before_upstream_query(h, target):
+ old = await seed(h, namespace="batrace:other-source")
+ request = h.modules.commands.Request("stats", h.modules.commands.Target(target, h.caller.user))
+ with pytest.raises(ValueError, match="数据源.*不一致"):
+ await h.service.execute(request, h.caller)
+ h.client.player.assert_not_awaited()
+ h.client.recent.assert_not_awaited()
+ assert await binding(h) == old
+
+
+async def test_last_skips_unrecorded_details_and_returns_next_available_match(h):
+ person = h.m.Participant("001", "Synthetic")
+ newest = h.m.Match("new", players=[person])
+ available = h.m.Match("old", players=[person], complete=True)
+ h.client.recent.return_value = h.result([newest, available])
+ h.client.match.side_effect = [h.modules.client.NoDataError("暂无收录"), h.result(available)]
+ response = await h.run("last stb:001")
+ assert response.view["match"]["id"] == "old"
+ assert h.client.match.await_args_list == [call("new"), call("old")]
+ assert response.view["player"]["id"] == "001"
+
+
+async def test_last_does_not_describe_authentication_failure_as_missing_match(h):
+ h.client.recent.return_value = h.result([
+ h.m.Match("new", players=[h.m.Participant("001", "Synthetic")])
+ ])
+ h.client.match.side_effect = h.modules.client.AuthenticationError("鉴权失败")
+ with pytest.raises(h.modules.client.AuthenticationError, match="鉴权失败"):
+ await h.run("last stb:001")
+ h.client.match.assert_awaited_once_with("new")
+
+
+@pytest.mark.parametrize("action", ["stats", "recent", "last"])
+async def test_player_reports_reject_nonempty_foreign_rosters(h, action):
+ h.client.recent.return_value = h.result([
+ h.m.Match("wrong", players=[h.m.Participant("999", "Other")]),
+ h.m.Match("valid", players=[h.m.Participant("001", "Synthetic")]),
+ ])
+ with pytest.raises(h.modules.client.IdentityMismatchError, match="未参与"):
+ await h.run(f"{action} stb:001")
+ h.client.match.assert_not_awaited()
+
+
+@pytest.mark.parametrize("detail_player_id", ["999", None, "001"])
+async def test_last_validates_real_client_detail_without_skipping_identity_errors(h, monkeypatch, detail_player_id):
+ c = h.modules.client
+ seen = []
+
+ def handler(request):
+ seen.append((request.url.path, dict(request.url.params)))
+ if request.url.path == "/api/players/matches":
+ return httpx.Response(200, json={"matches": [
+ {"matchId": mid, "data": {"StartTime": start, "Data": {"a": {"Id": "001"}}}}
+ for mid, start in [("new", 1700000100), ("old", 1700000000)]
+ ]})
+ assert request.url.path == "/api/match"
+ return httpx.Response(200, json={"matchInfo": {
+ "Data": {} if detail_player_id is None else {"a": {"Id": detail_player_id}}
+ }})
+
+ async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+ client = c.BatraceClient(c.ClientConfig(
+ enabled=True, client_id="synthetic-test-client", base_url="https://example.invalid",
+ request_interval=0, retries=0,
+ ), storage=h.storage, http_client=http)
+ monkeypatch.setattr(client, "player", AsyncMock(return_value=h.result(h.player)))
+ h.service.client = client
+ try:
+ if detail_player_id == "999":
+ with pytest.raises(c.IdentityMismatchError, match="未参与") as error:
+ await h.run("last stb:001")
+ assert error.value.code == "identity_mismatch"
+ else:
+ view = (await h.run("last stb:001")).view
+ assert view["match"]["id"] == "new"
+ assert view["player"]["id"] == "001"
+ if detail_player_id is None:
+ assert view["teams"] == []
+ assert view["match"]["winner"] is None
+ assert seen == [
+ ("/api/players/matches", {"stbid": "001", "limit": "20"}),
+ ("/api/match", {"matchid": "new"}),
+ ]
+ finally:
+ await client.close()
+
+
+async def test_empty_recent_rosters_remain_unavailable_without_identity_errors(h):
+ h.client.recent.return_value = h.result([h.m.Match("empty")])
+ assert (await h.run("recent stb:001")).view["rows"] == []
+ assert "暂无可用单局战报" in (await h.run("last stb:001")).text
+ h.client.match.assert_not_awaited()
+
+
+@pytest.mark.parametrize("theme", ["dark", "light"])
+async def test_units_use_stable_ids_and_distinct_labels_in_image_and_text(h, theme):
+ from html import escape
+ from render import Renderer
+
+ records = [
+ [{"Id": "u1"}, {"Id": "u2", "Name": "Tank "}, {"Id": "u3"}],
+ [{"Id": "u1", "Name": "Tank "}],
+ [{"Id": "u1", "Name": "Old Name"}],
+ ]
+ h.client.recent.return_value = h.result(h.m.parse_recent({"matches": [
+ {"matchId": str(index), "data": {"StartTime": 1700000200 - index * 100, "Data": {
+ "a": {"Id": "001", "UnitData": {str(i): unit for i, unit in enumerate(units)}},
+ "b": {"Id": "999", "UnitData": {"x": {"Id": "other", "Name": "Other player's unit"}}},
+ }}}
+ for index, units in enumerate(records)
+ ]}))
+ view = (await h.run("stats stb:001")).view
+ assert view["common_units"] == [
+ {"id": "u1", "name": "Tank (ID:u1)", "count": 3},
+ {"id": "u2", "name": "Tank (ID:u2)", "count": 1},
+ {"id": "u3", "name": "单位#u3", "count": 1},
+ ]
+ renderer = Renderer(theme=theme)
+ html, text = renderer.template(view), renderer.text(view)
+ for unit in view["common_units"]:
+ assert f"{unit['name']}:{unit['count']} 个" in text
+ assert (f'{escape(unit["name"])}'
+ f'{unit["count"]} 个') in html
+ assert "Old Name" not in html + text
+ assert "Other player's unit" not in html + text
+
+
+async def test_recent_view_distinguishes_zero_unknown_and_lossless_ratios(h):
+ people = [
+ h.m.Participant("001", "S", kills=0, losses=2, destroyed_value=0, lost_value=100),
+ h.m.Participant("001", "S", kills=2, losses=0, destroyed_value=500, lost_value=0),
+ h.m.Participant("001", "S", kills=None, losses=2, destroyed_value=None, lost_value=0),
+ h.m.Participant("001", "S", kills=0, losses=0, destroyed_value=0, lost_value=0),
+ h.m.Participant("001", "S", kills=2, losses=1, destroyed_value=1000, lost_value=100),
+ ]
+ h.client.recent.return_value = h.result([
+ h.m.Match(str(index), players=[person]) for index, person in enumerate(people)
+ ])
+ rows = (await h.run("recent stb:001 --limit 5")).view["rows"]
+ assert [row["unit_exchange"] for row in rows] == [0, "无损失", None, None, 2]
+ assert [row["value_exchange"] for row in rows] == [0, "无损失", None, None, 10]
+ assert rows[2]["kills"] is None
+ assert all(row["outcome"] == "unknown" for row in rows)
+
+
+async def test_overview_uses_actual_sample_and_known_outcomes_only(h):
+ h.client.recent.return_value = h.result([
+ h.m.Match(str(index), players=[h.m.Participant("001", "S", outcome=outcome)])
+ for index, outcome in enumerate(["win", "loss", "unknown"])
+ ], stale=True)
+ view = (await h.run("stats stb:001")).view
+ metrics = {item["label"]: item for item in view["metrics"]}
+ assert metrics["样本场数"]["value"] == 3
+ assert metrics["胜 / 负 / 未知"]["value"] == "1 / 1 / 1"
+ assert metrics["已知结果胜率"]["value"] == 50
+ assert "2 场" in metrics["已知结果胜率"]["note"]
+ assert "实际 3 场" in view["scope"]
+ assert "非完整历史" in view["scope"]
+ assert view["stale"] is True
+
+
+async def test_service_real_client_pipeline_sorts_and_deduplicates_recent_samples(h, monkeypatch):
+ c = h.modules.client
+ client = c.BatraceClient(c.ClientConfig(
+ enabled=True, client_id="synthetic-test-client", base_url="https://example.invalid",
+ request_interval=0, retries=0,
+ ), storage=h.storage)
+
+ def raw(start):
+ return {"StartTime": start, "EndTime": start + 60, "TotalPlayTimeInSec": 60,
+ "Data": {"a": {"Id": "001", "Name": "Synthetic", "UnitData": {}}}}
+
+ payload = {"matches": [
+ {"matchId": "old", "data": raw(1700000000)},
+ {"matchId": "new", "data": raw(1700000100)},
+ {"matchId": "new", "data": raw(1700000100)},
+ ]}
+ request = AsyncMock(return_value=payload)
+ monkeypatch.setattr(client, "_request", request)
+ monkeypatch.setattr(client, "player", AsyncMock(return_value=h.result(h.player)))
+ h.service.client = client
+ try:
+ view = (await h.run("recent stb:001 --limit 5")).view
+ assert [row["id"] for row in view["rows"]] == ["new", "old"]
+ assert "实际 2 场" in view["scope"]
+ request.assert_awaited_once_with("/api/players/matches", {"stbid": "001", "limit": 5})
+ finally:
+ await client.close()
diff --git a/tests/test_storage.py b/tests/test_storage.py
new file mode 100644
index 0000000..35e35a5
--- /dev/null
+++ b/tests/test_storage.py
@@ -0,0 +1,264 @@
+"""Use temporary SQLite databases, never production player data."""
+
+import asyncio
+
+import pytest
+
+from storage import Binding, Storage
+
+
+@pytest.mark.parametrize("operation", ["set_binding", "unbind", "put_cache", "clear_cache", "prune_cache"])
+@pytest.mark.parametrize("failure", ["error", "cancel"])
+async def test_failed_writes_roll_back_before_connection_reuse(tmp_path, monkeypatch, operation, failure):
+ store, observer = Storage(tmp_path), Storage(tmp_path)
+ await store.open()
+ await observer.open()
+ original = Binding("source", "001", "Original")
+ try:
+ await store.set_binding("p", "u", original)
+ await store.put_cache("existing", {"version": 1}, 60)
+ mutations = {
+ "set_binding": lambda: store.set_binding("p", "u", Binding("source", "002", "Replacement")),
+ "unbind": lambda: store.unbind("p", "u"),
+ "put_cache": lambda: store.put_cache("existing", {"version": 2}, 60),
+ "clear_cache": store.clear_cache,
+ "prune_cache": lambda: store.prune_cache(max_entries=0),
+ }
+ committing = asyncio.Event()
+
+ async def fail_commit():
+ committing.set()
+ if failure == "cancel":
+ await asyncio.Event().wait()
+ raise RuntimeError("synthetic commit failure")
+
+ with monkeypatch.context() as patch:
+ patch.setattr(store._connection(), "commit", fail_commit)
+ task = asyncio.create_task(mutations[operation]())
+ try:
+ await asyncio.wait_for(committing.wait(), 2)
+ if failure == "cancel":
+ task.cancel()
+ expected = asyncio.CancelledError if failure == "cancel" else RuntimeError
+ with pytest.raises(expected):
+ await asyncio.wait_for(task, 2)
+ finally:
+ if not task.done():
+ task.cancel()
+ await asyncio.gather(task, return_exceptions=True)
+
+ assert not store._connection().in_transaction
+ # A later successful write must neither commit the failed mutation nor
+ # encounter a transaction left open by it.
+ assert (await store.consume_request())["global"] == 1
+ await store.put_cache("recovery", {}, 60)
+ for connection in (store, observer):
+ assert await connection.get_binding("p", "u") == original
+ assert (await connection.get_cache("existing"))[0] == {"version": 1}
+ assert await connection.cache_count() == 2
+ finally:
+ await observer.close()
+ await store.close()
+
+
+class Clock:
+ now = 1000.0
+
+ def __call__(self):
+ return self.now
+
+
+def test_bindings_survive_restart_and_isolate_platform_and_user(tmp_path):
+ async def run():
+ first = Binding("batrace", "000765611980123456789012345", "Player 2", "https://example.invalid/player", 10.5)
+ other = Binding("batrace", "2", "Other", updated_at=11.0)
+ db = Storage(tmp_path / "plugin-data")
+ await db.open()
+ await db.open()
+ try:
+ await db.set_binding("onebot:a", "001", first)
+ await db.set_binding("onebot:b", "001", other)
+ await db.set_binding("onebot:a", "002", other)
+ assert await db.get_binding("onebot:a", "missing") is None
+ finally:
+ await db.close()
+ await db.close()
+ restarted = Storage(tmp_path / "plugin-data")
+ await restarted.open()
+ try:
+ assert await restarted.get_binding("onebot:a", "001") == first
+ assert isinstance((await restarted.get_binding("onebot:a", "001")).player_id, str)
+ assert await restarted.get_binding("onebot:b", "001") == other
+ assert await restarted.get_binding("onebot:a", "002") == other
+ renamed = Binding(first.namespace, first.player_id, "Renamed", first.source_url, 20.0)
+ await restarted.set_binding("onebot:a", "001", renamed)
+ assert await restarted.get_binding("onebot:a", "001") == renamed
+ assert await restarted.unbind("onebot:a", "001")
+ assert not await restarted.unbind("onebot:a", "001")
+ assert await restarted.get_binding("onebot:a", "001") is None
+ assert await restarted.get_binding("onebot:b", "001") == other
+ finally:
+ await restarted.close()
+ await restarted.open()
+ try:
+ assert await restarted.get_binding("onebot:a", "001") is None
+ finally:
+ await restarted.close()
+ asyncio.run(run())
+
+
+def test_json_cache_timing_expiry_stale_read_and_restart(tmp_path):
+ async def run():
+ clock = Clock()
+ db = Storage(tmp_path, clock=clock)
+ await db.open()
+ payload = {"id": "000765611980123456789012345", "name": "玩家", "unknown": None,
+ "nested": [{"win": False, "elo": 1234.5}]}
+ try:
+ assert await db.get_cache("missing") is None
+ await db.put_cache("batrace:player:001:recent:5", payload, 10)
+ clock.now = 1010.0
+ assert await db.get_cache("batrace:player:001:recent:5") == (payload, 1000.0, 1010.0)
+ await db.put_cache("batrace:player:001:recent:10", [], 0)
+ assert await db.cache_count() == 2
+ finally:
+ await db.close()
+ await db.open()
+ try:
+ assert await db.get_cache("batrace:player:001:recent:5") == (payload, 1000.0, 1010.0)
+ await db.put_cache("batrace:player:001:recent:5", [{"updated": True}], 60)
+ assert await db.get_cache("batrace:player:001:recent:5") == ([{"updated": True}], 1010.0, 1070.0)
+ assert await db.cache_count() == 2
+ finally:
+ await db.close()
+ asyncio.run(run())
+
+
+def test_cache_clear_and_age_capacity_pruning_preserve_binding(tmp_path):
+ async def run():
+ clock = Clock()
+ db = Storage(tmp_path, clock=clock)
+ await db.open()
+ binding = Binding("batrace", "001", "Player", updated_at=1.0)
+ try:
+ await db.set_binding("p", "u", binding)
+ for index in range(4):
+ clock.now = 1000.0 + index * 10
+ await db.put_cache(str(index), {"i": index}, 1)
+ assert await db.prune_cache(max_entries=2) == 2
+ assert await db.get_cache("0") is None
+ assert await db.get_cache("1") is None
+ assert await db.get_cache("2") is not None
+ clock.now = 1040
+ assert await db.prune_cache(max_age_seconds=15) == 1
+ assert await db.get_cache("2") is None
+ assert await db.get_cache("3") is not None
+ assert await db.get_binding("p", "u") == binding
+ await db.clear_cache()
+ assert await db.cache_count() == 0
+ assert await db.get_binding("p", "u") == binding
+ await db.put_cache("new", [], 30)
+ assert await db.prune_cache(max_entries=0) == 1
+ assert await db.get_binding("p", "u") == binding
+ finally:
+ await db.close()
+ asyncio.run(run())
+
+
+def test_default_retention_prunes_old_stale_entries_on_write(tmp_path):
+ async def run():
+ clock = Clock()
+ db = Storage(tmp_path, clock=clock)
+ await db.open()
+ try:
+ await db.put_cache("old", {}, 10)
+ clock.now += 604800
+ await db.put_cache("new", [], 10)
+ assert await db.get_cache("old") is None
+ assert await db.cache_count() == 1
+ finally:
+ await db.close()
+ asyncio.run(run())
+
+
+def test_configured_cache_bounds_apply_on_write_and_manual_prune(tmp_path):
+ async def run():
+ clock = Clock()
+ db = Storage(tmp_path, max_entries=2, max_age_seconds=10, clock=clock)
+ await db.open()
+ try:
+ for index in range(3):
+ clock.now += 1
+ await db.put_cache(str(index), {}, 1)
+ assert await db.get_cache("0") is None
+ assert await db.cache_count() == 2
+ assert await db.prune_cache() == 0
+ clock.now += 10
+ assert await db.prune_cache() == 2
+ finally:
+ await db.close()
+ asyncio.run(run())
+
+
+def test_configured_cache_capacity_can_exceed_one_thousand(tmp_path):
+ async def run():
+ db = Storage(tmp_path, max_entries=1002)
+ await db.open()
+ try:
+ for index in range(1001):
+ await db.put_cache(str(index), [], 60)
+ assert await db.cache_count() == 1001
+ assert await db.prune_cache() == 0
+ assert await db.cache_count() == 1001
+ finally:
+ await db.close()
+ asyncio.run(run())
+
+
+def test_concurrent_writes_and_cache_maintenance_do_not_affect_bindings(tmp_path):
+ async def run():
+ db = Storage(tmp_path)
+ await db.open()
+ try:
+ await asyncio.gather(*(
+ db.set_binding("p", str(index), Binding("ns", str(index), str(index)))
+ for index in range(20)
+ ), *(db.put_cache(str(index), {"i": index}, 30) for index in range(20)))
+ await asyncio.gather(db.clear_cache(), db.set_binding("p", "new", Binding("ns", "001", "New")))
+ assert await db.cache_count() == 0
+ for index in range(20):
+ assert (await db.get_binding("p", str(index))).player_id == str(index)
+ assert (await db.get_binding("p", "new")).player_id == "001"
+ finally:
+ await db.close()
+ asyncio.run(run())
+
+
+@pytest.mark.parametrize("player_id", [123, 123.5, None, ""])
+def test_bindings_never_convert_numeric_ids_to_float_or_integer(player_id):
+ with pytest.raises(ValueError):
+ Binding("batrace", player_id, "Player")
+
+
+def test_invalid_cache_parameters_and_closed_lifecycle(tmp_path):
+ async def run():
+ db = Storage(tmp_path)
+ with pytest.raises(RuntimeError, match="尚未打开"):
+ await db.get_binding("p", "u")
+ await db.open()
+ try:
+ for ttl in [-1, float("nan"), float("inf")]:
+ with pytest.raises(ValueError):
+ await db.put_cache("bad", {}, ttl)
+ with pytest.raises(ValueError):
+ await db.put_cache("bad", "text", 1)
+ for kwargs in [{"max_entries": -1}, {"max_entries": 1.5},
+ {"max_age_seconds": -1}, {"max_age_seconds": float("nan")}]:
+ with pytest.raises(ValueError):
+ await db.prune_cache(**kwargs)
+ assert await db.cache_count() == 0
+ finally:
+ await db.close()
+ with pytest.raises(RuntimeError):
+ await db.cache_count()
+ asyncio.run(run())
diff --git a/tools/build_delivery.py b/tools/build_delivery.py
new file mode 100644
index 0000000..2693ac0
--- /dev/null
+++ b/tools/build_delivery.py
@@ -0,0 +1,254 @@
+"""Build an install ZIP, Gemini copywriting ZIP, and one final delivery ZIP.
+
+Reads only repository sources and the session's reviewed previews. No runtime
+database, configuration, cache, credentials or virtual environment is included.
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import csv
+import hashlib
+import io
+import json
+from pathlib import Path
+import re
+import zipfile
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+VERSION = "0.1.0"
+CHINESE = re.compile(r"[\u3400-\u9fff]")
+
+
+def digest(data):
+ return hashlib.sha256(data).hexdigest()
+
+
+def repository_files():
+ root_names = {"README.md", "LICENSE", "metadata.yaml", "_conf_schema.json",
+ "requirements.txt", "requirements-dev.txt", "pytest.ini", ".gitignore", ".gitattributes", "logo.png"}
+ files = []
+ for p in ROOT.rglob("*"):
+ if not p.is_file():
+ continue
+ rel = p.relative_to(ROOT)
+ if "__pycache__" in rel.parts or ".pytest_cache" in rel.parts:
+ continue
+ if len(rel.parts) == 1 and (p.suffix == ".py" or p.name in root_names):
+ files.append(p)
+ elif rel.parts[0] in {"templates", "assets", "docs", "tests", "tools", ".github"} and p.suffix in {".py", ".html", ".md", ".json", ".png", ".txt", ".yml", ".yaml"}:
+ files.append(p)
+ return sorted(files)
+
+
+def archive(entries):
+ stream = io.BytesIO()
+ with zipfile.ZipFile(stream, "w", compression=zipfile.ZIP_DEFLATED) as z:
+ for name, data in sorted(entries.items()):
+ # Stable ZIP metadata keeps an unchanged export reproducible.
+ info = zipfile.ZipInfo(name, date_time=(2026, 11, 17, 0, 0, 0))
+ info.compress_type = zipfile.ZIP_DEFLATED
+ info.external_attr = 0o644 << 16
+ z.writestr(info, data)
+ data = stream.getvalue()
+ with zipfile.ZipFile(io.BytesIO(data)) as z:
+ assert z.testzip() is None
+ assert all(not name.startswith("/") and ".." not in Path(name).parts for name in z.namelist())
+ return data
+
+
+def text_catalog(files):
+ result = []
+ for path in files:
+ rel = path.relative_to(ROOT).as_posix()
+ if path.parent != ROOT or path.suffix != ".py":
+ continue
+ source = path.read_text(encoding="utf-8")
+ tree = ast.parse(source)
+ parents = {child: parent for parent in ast.walk(tree) for child in ast.iter_child_nodes(parent)}
+ docstrings = set()
+ for node in ast.walk(tree):
+ if isinstance(node, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)) and node.body:
+ first = node.body[0]
+ if isinstance(first, ast.Expr) and isinstance(first.value, ast.Constant) and isinstance(first.value.value, str):
+ docstrings.add(first.value)
+ for node in ast.walk(tree):
+ if isinstance(node, ast.JoinedStr):
+ text = "".join(v.value if isinstance(v, ast.Constant) else "{" + ast.unparse(v.value)
+ + ("!" + chr(v.conversion) if v.conversion != -1 else "")
+ + (":" + "".join(x.value if isinstance(x, ast.Constant) else "{" + ast.unparse(x.value) + "}"
+ for x in v.format_spec.values) if v.format_spec else "") + "}"
+ for v in node.values)
+ kind = "格式化提示(占位符必须原样保留)"
+ elif isinstance(node, ast.Constant) and isinstance(node.value, str) and node not in docstrings:
+ if isinstance(parents.get(node), ast.JoinedStr):
+ continue
+ text, kind = node.value, "文字常量(请结合上下文确认是否用户可见)"
+ else:
+ continue
+ ancestors, current = [], node
+ error_text = False
+ while current in parents:
+ current = parents[current]
+ if isinstance(current, ast.Raise):
+ error_text = True
+ if isinstance(current, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+ ancestors.append(current.name)
+ if not CHINESE.search(text) and not error_text:
+ continue
+ line = node.lineno
+ result.append(dict(id=f"{rel}:{line}:{len(result)+1}", file=rel, line=line,
+ context=" / ".join(reversed(ancestors)), kind=kind, original=text,
+ source_literal=ast.get_source_segment(source, node), suggestion=""))
+ schema = json.loads((ROOT / "_conf_schema.json").read_text(encoding="utf-8"))
+ def walk(value, pointer=""):
+ if isinstance(value, dict):
+ for key, child in value.items():
+ target = pointer + "/" + key
+ if key in {"description", "hint", "labels", "subtitles"}:
+ values = child if isinstance(child, list) else [child]
+ for i, text in enumerate(values):
+ result.append(dict(id="schema:" + target + (f"/{i}" if isinstance(child, list) else ""),
+ file="_conf_schema.json", line=None, context=pointer, kind="配置界面文案",
+ original=text, suggestion=""))
+ else:
+ walk(child, target)
+ walk(schema)
+ for number, line in enumerate((ROOT / "metadata.yaml").read_text(encoding="utf-8").splitlines(), 1):
+ if line.startswith(("display_name:", "desc:")):
+ key, text = line.split(":", 1)
+ result.append(dict(id="metadata:" + key, file="metadata.yaml", line=number,
+ context=key, kind="插件展示信息(名称需用户确认)", original=yaml.safe_load(text), suggestion=""))
+ # Keep complete Jinja/HTML lines so translators see tags and placeholders.
+ for path in sorted((ROOT / "templates").glob("*.html")):
+ for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+ if CHINESE.search(line):
+ result.append(dict(id=f"template:{path.name}:{number}", file=path.relative_to(ROOT).as_posix(),
+ line=number, context="保留 HTML 标签、Jinja 表达式和属性", kind="卡片模板行",
+ original=line, suggestion=""))
+ return result
+
+
+PROMPT = """# 交给 Gemini 的文案优化任务
+
+你将润色 AstrBot 插件「断箭战报」v0.1.0 的中文提示、配置说明、图片战报文字和 README。只提出文案修改,不执行代码、不调用服务、不改变功能或统计逻辑。
+
+## 先读这些材料
+1. `事实与约束.md`:哪些能力已实现、哪些尚未验证。
+2. `文案清单.json` 或 `文案清单.csv`:带文件/行号/上下文的原文和待填写建议。
+3. `原文件/README.md`:全文润色对象。
+4. `原文件/` 中代码、配置和模板:确认实际触发条件及动态占位符。自动清单可能收录内部日志或数据标签,请标注「保持原样」,不要擅改程序标识。
+5. `参考预览/`:只用来理解呈现位置,全部是合成样本。
+
+## 文风
+自然、准确、简洁的中文,像成熟工具的帮助信息;先告诉用户发生了什么及下一步。删重复说明和生硬技术用语,但保留影响操作的条件、范围、单位和后果。不要营销腔,不添加未经证实的能力、性能、兼容性或成功承诺。管理员诊断与普通玩家提示分别处理。
+
+## 不可改动
+- `/ba`、英文子命令、现有中文别名、`stb:`、`steam:`、`name:`、`--limit`、示例 ID 的类型和参数顺序。
+- Python f-string 的所有占位符及格式说明,如 `{caller.prefix}`、`{remaining:.0f}`;JSON 键、枚举值、路径、URL、版本、默认值与数字边界。
+- Jinja 的 `{{ ... }}`、`{% ... %}`、HTML 标签属性、CSS、自动转义及安全规则。
+- STB ID 与 Steam ID 的区分;绑定不是所有权认证;一次选择即确认;查询不修改绑定;原绑定在失败时保留。
+- 缺失与零、未知胜负、近期样本与生涯、数量与价值、抓取时间与来源时间的区分。
+- 每用户默认 20 次、每群默认 100 次可调,全插件每日 100 次固定不可调;北京时间 0 点重置;按 HTTP 请求计数,失败与重试计入、缓存不扣额。不要将请求次数润色为战报查询次数。
+- 不把测试或合成截图写成已上线成果;README 保持简洁,详细接口边界和验证记录放在 docs。
+- 许可证、来源致谢与原 Logo。不要改变设计、代码或配置结构。
+
+## 需要返回
+1. `README_润色建议.md`:完整 README,保留命令表、安装步骤、链接与必要限制。
+2. `文案修改建议.json`:数组,每条含 `id`、`original`、`suggestion`、`reason`;保持清单 id,不改键名。建议应为文案文本,不是自动执行补丁。
+3. `需确认事项.md`:仅列会改变含义、与代码不一致或无法确认的事项;不要自作假设。
+
+请按文件分组核对整份清单。可保持已清晰的文案;对多条原文相同但触发条件不同的提示,不盲目合并。先给可回填的完整结果,再简述少量关键取舍。最终建议由用户审阅并交回开发者,不自动覆盖源文件。
+"""
+
+FACTS = """# 事实与约束
+
+- 本包是文案审阅材料,非生产配置。源码、提示清单与 README 来自同一次交付快照;SHA256.json 用于核对回填基线。
+- 首版功能:英文主命令、可选中文子命令别名、玩家解析、候选请求码、默认绑定、玩家概览/近期/单局、图片失败文字回退、缓存/限流/管理员状态。
+- 接入默认关闭,客户端标识及令牌为空。需要本插件自己的 BATrace 许可;没有真实接口联调通过的结论,不借用其他项目身份。
+- SteamID64 权威映射尚未确认;语法识别后给出明确限制,不返回猜测映射。
+- API 字段来自固定参考源码研究及合成契约测试;未确认的胜负、模式、地图/单位名称保持未知或来源 ID。当前样本不代表全生涯。
+- 三类卡片已在本地 Chromium 用合成样本渲染并检查;实际 AstrBot 渲染服务与 QQ 收发仍待验收。
+- 配置保存后需重载。本地默认值不是上游许可额度。
+- 每用户默认 20 次、每群默认 100 次,均可在设置调整为 0–100;0 不单独限制。全插件每日 100 次为固定上限,不提供调整项或管理员豁免。所有额度北京时间每天 0 点重置,与显示时区无关。
+- 用户额度按同平台实例的实际发送者跨群及私聊累计,群额度由群内用户共享。按实际提交 HTTP 的尝试计数,重试、失败计入;一条战报命令可能耗多次。命中缓存、本地命令、图片渲染不计入。并发原子记账、重载/清缓存/改凭据不清零;发送前已记账的中断保守保留。
+- `/ba quota` 或 `/ba 额度` 可查看个人、本群、全插件用量;总额度固定 100,不得描述为可配置。达到额度仍可读取新鲜缓存,需要刷新则提示额度已用完,不使用旧缓存隐藏提示。
+- 用户偏好:界面简洁、主次清晰、必要解释靠近字段,普通小数两位、计数整数、精简冗余但保留口径和操作后果。
+- 交付源码保持 Apache-2.0;既有 Logo 原样保留。来源资料见原文件/docs。
+- 文案清单覆盖根目录 Python 中中文字符串及英文异常提示、配置展示字段、插件展示信息和含中文模板行;README 与文档全文随包。测试、工具、注释不作为用户文案润色目标。
+"""
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--output", type=Path, default=ROOT.parent / "delivery")
+ args = parser.parse_args()
+ args.output.mkdir(parents=True, exist_ok=True)
+ files = repository_files()
+ entries = {p.relative_to(ROOT).as_posix(): p.read_bytes() for p in files}
+ install = {"astrbot_plugin_ba_stats/" + name: data for name, data in entries.items()
+ if name.split("/")[0] not in {"tests", "tools", ".github"}
+ and name not in {"requirements-dev.txt", "pytest.ini", ".gitignore", ".gitattributes"}}
+ for required in ("main.py", "metadata.yaml", "_conf_schema.json", "README.md", "logo.png", "LICENSE"):
+ assert "astrbot_plugin_ba_stats/" + required in install
+ for name in install:
+ assert not any(p in name for p in (".env", ".sqlite", "__pycache__", ".git/"))
+ plugin_name = f"astrbot_plugin_ba_stats_v{VERSION}.zip"
+ plugin = archive(install)
+ (args.output / plugin_name).write_bytes(plugin)
+
+ catalog = text_catalog(files)
+ copy_entries = {"给Gemini的任务说明.md": PROMPT.encode(), "事实与约束.md": FACTS.encode(),
+ "文案清单.json": json.dumps(catalog, ensure_ascii=False, indent=2).encode()}
+ buffer = io.StringIO(newline="")
+ writer = csv.DictWriter(buffer, fieldnames=["id", "file", "line", "context", "kind", "original", "suggestion"], extrasaction="ignore")
+ writer.writeheader()
+ writer.writerows(catalog)
+ copy_entries["文案清单.csv"] = buffer.getvalue().encode("utf-8-sig")
+ for name, data in entries.items():
+ if name == "README.md" or name == "metadata.yaml" or name == "_conf_schema.json" or ("/" not in name and name.endswith(".py")) or name.startswith(("templates/", "docs/")):
+ copy_entries["原文件/" + name] = data
+ previews = ROOT.parent / "previews"
+ for name in ["overview-normal-dark-mobile.png", "recent-normal-light-mobile.png", "match-missing-light-mobile.png"]:
+ path = previews / name
+ if path.is_file():
+ copy_entries["参考预览/" + name] = path.read_bytes()
+ hashes = {name: digest(data) for name, data in entries.items()}
+ copy_entries["SHA256.json"] = json.dumps(hashes, indent=2).encode()
+ copy_name = f"断箭战报_Gemini文案优化包_v{VERSION}.zip"
+ copy_zip = archive(copy_entries)
+ (args.output / copy_name).write_bytes(copy_zip)
+
+ bundle = {"安装包/" + plugin_name: plugin, "文案优化/" + copy_name: copy_zip}
+ bundle.update({"源码/astrbot_plugin_ba_stats/" + name: data for name, data in entries.items()})
+ for p in previews.glob("*"):
+ if p.is_file() and p.suffix in {".png", ".html", ".txt", ".json"}:
+ bundle["验证/卡片预览/" + p.name] = p.read_bytes()
+ validation = ROOT / "docs" / "VALIDATION.md"
+ assert validation.is_file(), "Write final validation evidence before delivery."
+ bundle["验证/VALIDATION.md"] = validation.read_bytes()
+ log = ROOT.parent / "validation" / "pytest.txt"
+ if log.is_file():
+ bundle["验证/pytest.txt"] = log.read_bytes()
+ bundle["开始使用.md"] = f"""# 断箭战报 v{VERSION}
+
+1. 导入 AstrBot:使用「安装包/{plugin_name}」,不要直接导入本总 ZIP。
+2. 真实在线查询还需独立获准的 BATrace 接入;详见源码目录 README 和 docs/API_NOTES.md。
+3. 「文案优化/{copy_name}」可单独交给 Gemini。先让 Gemini 阅读「给Gemini的任务说明.md」,润色提示、配置文字、卡片和 README;回填前仍需核对占位符及功能语义。
+4. 「验证」包含真实执行记录及标注为合成样本的预览。离线通过不代表真实 API 或 QQ 平台验收。
+5. 完整源码、测试和重建工具位于「源码/astrbot_plugin_ba_stats」。仓库审阅状态以 GitHub PR 为准;此包不表示已发布市场或部署生产。
+6. 每日默认额度:个人 20 次、每群 100 次可调,全插件固定 100 次。北京时间 0 点重置;发送 `/ba quota` 查看用量。按上游 HTTP 请求计数,重试及失败计入,命中缓存不计入。
+""".encode()
+ bundle["SHA256.json"] = json.dumps({name: digest(data) for name, data in bundle.items()}, ensure_ascii=False, indent=2).encode()
+ final_name = f"断箭战报_v{VERSION}_交付包.zip"
+ final = archive(bundle)
+ (args.output / final_name).write_bytes(final)
+ print(json.dumps({"delivery": str(args.output / final_name), "bytes": len(final),
+ "sha256": digest(final), "source_files": len(entries), "copy_items": len(catalog),
+ "plugin_entries": len(install), "bundle_entries": len(bundle)}, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+ main()
diff --git a/tools/render_previews.py b/tools/render_previews.py
new file mode 100644
index 0000000..d0fd48b
--- /dev/null
+++ b/tools/render_previews.py
@@ -0,0 +1,198 @@
+"""Build labelled synthetic card previews, with optional local-only Chromium.
+
+Run from the repository using the session's .venv/Scripts/python.exe -B:
+ tools/render_previews.py # HTML + matching text only
+ tools/render_previews.py --screenshots # desktop + 390px mobile PNGs
+
+Chromium must already be installed under the session's .playwright directory.
+No installation, server, external page, account, or live API is used. Browser
+contexts are offline and all requests are aborted as an additional boundary.
+All outputs, browser temporary profiles and the manifest stay under the
+session root's previews/. Images show synthetic samples, never real players.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+from copy import deepcopy
+import json
+import os
+from pathlib import Path
+import sys
+import tempfile
+
+sys.dont_write_bytecode = True
+REPOSITORY = Path(__file__).resolve().parents[1]
+SESSION = REPOSITORY.parent
+OUTPUT = SESSION / "previews"
+sys.path.insert(0, str(REPOSITORY))
+
+from render import Renderer
+
+
+def sample_views() -> dict[str, dict]:
+ """Deterministic synthetic data; deliberately unequal 3v2 team sizes."""
+ base = {
+ "player": {"id": "sample-000001", "name": "蓝线观察员 · 合成样本"},
+ "scope": "最近取得 5 场 · 其中排位样本 4 场 · 非完整历史",
+ "fetched_at": "2026-11-17T04:10:00Z",
+ "source_updated_at": "2026-11-17T04:00:00Z",
+ "source_url": "https://example.invalid/synthetic-preview",
+ "synthetic": True,
+ }
+ overview = deepcopy(base)
+ overview.update(
+ kind="overview",
+ metrics=[
+ {"label": "ELO", "value": 1834.25, "note": "来源更新时点"},
+ {"label": "样本胜率", "value": 75, "format": "percent", "note": "排位样本 4 场"},
+ {"label": "单位交换比", "value": 150 / 96, "note": "摧毁单位 / 损失单位"},
+ {"label": "价值交换比", "value": 39602 / 26081, "note": "摧毁价值 / 损失价值"},
+ ],
+ common_units=[{"name": "合成装甲单位 A", "count": 12}, {"name": "合成支援兵种 B", "count": 8}],
+ )
+ recent = deepcopy(base)
+ recent.update(kind="recent", rows=[
+ {
+ "id": f"sample-match-{index + 1:03d}", "map_name": f"合成地图 {index + 1}",
+ "mode": "custom" if index == 4 else "ranked", "outcome": "loss" if index == 2 else "win",
+ "started_at": f"2026-11-{17 - index:02d}T02:20:00Z", "duration_seconds": 1327 + index * 53,
+ "elo_delta": -12.5 if index == 2 else 8.25, "kills": 36 + index, "losses": 24,
+ "unit_exchange": 1.5 + index / 24, "destroyed_value": 9750.5 + index * 100,
+ "lost_value": 6520.25, "value_exchange": (9750.5 + index * 100) / 6520.25,
+ }
+ for index in range(5)
+ ])
+ match = deepcopy(base)
+ match.update(
+ kind="match", scope="单场完整记录 · 自定义 · 实际 3 对 2 人",
+ match={"id": "sample-match-001", "map_name": "合成港区", "mode": "custom",
+ "started_at": "2026-11-17T02:20:00Z", "duration_seconds": 1327, "winner": "蓝队"},
+ teams=[
+ {"name": name, "outcome": "win" if side == 0 else "loss", "players": [
+ {"id": f"sample-{side}-{index}", "name": f"合成队员 {side + 1}-{index + 1}",
+ "elo": 1800 + index * 12.5, "elo_delta": 8.25 if side == 0 else -8.25,
+ "kills": 36, "losses": 24, "unit_exchange": 1.5,
+ "destroyed_value": 9750.5, "lost_value": 6520.25, "value_exchange": 9750.5 / 6520.25}
+ for index in range(size)
+ ]}
+ for side, (name, size) in enumerate([("蓝队", 3), ("红队", 2)])
+ ],
+ )
+ samples = {}
+ for kind, normal in [("overview", overview), ("recent", recent), ("match", match)]:
+ samples[f"{kind}-normal"] = normal
+ long = deepcopy(normal)
+ long["player"]["name"] = "合成长昵称_中文MixedPlayer_" * 7 + '{{7*7}} <昵称>&'
+ long["player"]["id"] = "sample-long-id-" + "0123456789" * 8
+ if kind == "overview":
+ long["common_units"][0]["name"] = "合成长单位名称_" * 8
+ elif kind == "recent":
+ long["rows"][0]["map_name"] = "合成长地图名称_" * 6
+ else:
+ long["teams"][0]["name"] = "合成长分队名称_" * 7
+ long["teams"][0]["players"][0]["name"] = long["player"]["name"]
+ samples[f"{kind}-long-name"] = long
+ missing = deepcopy(base)
+ missing.update(kind=kind, player={"id": "sample-missing", "name": None},
+ source_url=None, source_updated_at=None, stale=True, scope="已取得样本 · 覆盖范围暂无")
+ if kind == "overview":
+ missing["metrics"] = [
+ {"label": "ELO", "value": None}, {"label": "样本胜率", "value": None, "format": "percent"},
+ {"label": "实际样本", "value": 0, "format": "integer", "unit": "场"},
+ {"label": "价值交换比", "value": None},
+ ]
+ elif kind == "recent":
+ missing["rows"] = [{"id": "sample-partial", "kills": 0, "duration_seconds": 0}]
+ else:
+ missing["match"] = {"id": "sample-partial"}
+ missing["teams"] = [{"name": "合成未完整分队", "players": [{"id": "sample-player", "name": None}]},
+ {"name": "合成空分队", "players": []}]
+ samples[f"{kind}-missing"] = missing
+ return samples
+
+
+async def screenshots(artifacts: list[dict]) -> list[dict]:
+ from playwright.async_api import async_playwright
+
+ os.environ.setdefault("PLAYWRIGHT_BROWSERS_PATH", str(SESSION / ".playwright"))
+ temporary = OUTPUT / ".tmp"
+ temporary.mkdir(exist_ok=True)
+ os.environ["TMP"] = str(temporary)
+ os.environ["TEMP"] = str(temporary)
+ tempfile.tempdir = str(temporary)
+ checks = []
+ async with async_playwright() as playwright:
+ browser = await playwright.chromium.launch(headless=True)
+ try:
+ for label, width in [("desktop", 980), ("mobile", 390)]:
+ context = await browser.new_context(viewport={"width": width, "height": 900},
+ device_scale_factor=1, offline=True)
+ await context.route("**/*", lambda route: route.abort())
+ try:
+ page = await context.new_page()
+ requests = []
+ page.on("request", lambda request: requests.append(request.url))
+ for item in artifacts:
+ requests.clear()
+ await page.set_content((OUTPUT / item["html"]).read_text(encoding="utf-8"), wait_until="load")
+ await page.evaluate("document.fonts.ready")
+ dimensions = await page.evaluate("""() => ({
+ width: innerWidth,
+ documentWidth: document.documentElement.scrollWidth,
+ height: document.documentElement.scrollHeight,
+ reportHeight: document.querySelector('.report').getBoundingClientRect().height,
+ synthetic: document.querySelector('.synthetic')?.textContent,
+ font: getComputedStyle(document.body).fontFamily
+ })""")
+ name = f"{item['name']}-{label}.png"
+ await page.locator(".report").screenshot(path=str(OUTPUT / name), animations="disabled")
+ check = {"image": name, "viewport": label, **dimensions,
+ "external_requests": list(requests),
+ "passed": dimensions["documentWidth"] <= width and not requests
+ and bool(dimensions["synthetic"])}
+ checks.append(check)
+ finally:
+ await context.close()
+ finally:
+ await browser.close()
+ return checks
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--screenshots", action="store_true", help="use already installed local headless Chromium")
+ args = parser.parse_args()
+ OUTPUT.mkdir(parents=True, exist_ok=True)
+ artifacts = []
+ for sample_name, view in sample_views().items():
+ for theme in ("dark", "light"):
+ renderer = Renderer(theme=theme)
+ for page in renderer.views(view):
+ name = f"{sample_name}-{theme}"
+ if page.get("page_count", 1) > 1:
+ name += f"-page-{page['page']}"
+ html_name, text_name = name + ".html", name + ".txt"
+ (OUTPUT / html_name).write_text(renderer.template(page), encoding="utf-8")
+ (OUTPUT / text_name).write_text(renderer.text(page), encoding="utf-8")
+ artifacts.append({"name": name, "html": html_name, "text": text_name})
+ checks = asyncio.run(screenshots(artifacts)) if args.screenshots else []
+ manifest = {
+ "synthetic": True, "live_api_used": False,
+ "browser_mode": "local-only offline headless Chromium" if args.screenshots else "not launched",
+ "artifacts": artifacts, "screenshots": checks,
+ "visual_review": "Screenshots require manual image review; layout checks alone are not visual acceptance.",
+ }
+ (OUTPUT / "manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
+ failures = [check["image"] for check in checks if not check["passed"]]
+ print(f"Synthetic previews: {len(artifacts)} HTML/text pairs; {len(checks)} screenshots; {len(failures)} layout/network failures.")
+ print(f"Output: {OUTPUT}")
+ if failures:
+ print("Failed: " + ", ".join(failures))
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())