feat(trace): add history filters and improve trace workspace - #10765

Refs #10748

内容由 AI 生成

追踪页是 AstrBot 运维人员和插件开发者排查“消息从接收、插件处理、Agent 调用到响应发送”全链路的主要入口。随着系统长时间运行，追踪历史会迅速累积到数千甚至数万条，而当前过滤器只提供“有错误”“有模型调用”“有插件调用”三个复选框，其余只能依赖关键词搜索。实际排障时，用户通常先按平台、消息类型或具体会话缩小范围，再按运行状态和时间窗口定位某一次异常，例如“最近一小时内某个 QQ 群的失败请求”或“某个私聊会话中带指令调用的追踪”。旧界面无法表达这些条件，只能反复翻页并人工比对；由于筛选条件有限，分页总数也失去了参考价值，定位一条异常链路往往需要多次搜索和翻页。

在多机器人实例共用同一追踪数据库的场景下，平台维度尤其关键：旧过滤器无法区分不同机器人实例的消息，用户只能查看所有实例混在一起的记录。消息类型（群聊/私聊）和会话 UMO 同样是最常用的定位条件，前者用于快速排除无关场景，后者用于从具体会话直接钻取到对应追踪。缺少这些条件时，搜索只能依赖消息文本或插件名命中，遇到内容相似但来源不同的记录很容易误判。

运行状态与时间范围是另一类高频需求。追踪可能处于运行中、已完成或错误状态，排障时通常只关心失败链路；历史数据按保留天数累积后，用户又往往只关心最近一小时、一天或一周。把这些条件下推到服务端执行，才能保证分页总数与当前筛选一致，也避免把整库数据拉到浏览器后再过滤。同时，实时事件流必须遵守同一套条件，否则用户已经筛选了平台或状态，新的不匹配记录仍会插入列表，造成前后数据不一致。

在窄屏和移动端，目前的宽表格只能横向滚动，列多、字号小，触控操作困难；打开详情后列表被挤占，关闭按钮和键盘焦点也不够明确。此次改动希望让追踪页在手机上同样可用：用卡片列表替代横向滚动，把详情改为全屏抽屉，并补齐触控尺寸、安全区与焦点管理，让桌面端和移动端共享同一套数据与筛选逻辑。

稳定性方面，目前实时连接在重试耗尽后仍停留在“连接中”文案，用户无法判断是网络断开还是服务异常，也没有手动恢复入口。新实现把重试次数收敛到 3 次、退避上限降到 4 秒，失败后显示明确的断线提示与重试按钮，同时保留当前列表和筛选条件，避免实时连接不可用影响历史排障。

实现上遵循最小改动原则：不新增数据库表或字段，继续基于既有追踪摘要 JSON 与 UMO 属性做 SQL 过滤，旧数据仍可读取；所有新查询参数都是可选的，省略时行为与之前一致，因此不构成破坏性变更。过滤器采用“同一分组内为或、不同分组与执行条件之间为与”的语义，既符合常见筛选习惯，也允许用户同时按平台、消息类型、状态、会话和时间窗口组合定位。最终效果是：定位异常链路所需的翻页与猜测明显减少，筛选结果、分页总数与实时列表保持一致，移动端也能完成完整的查看与排障流程。

Modifications / 改动点

本次改动由两个提交组成：feat: add trace history filters 提供后端查询能力与 OpenAPI 定义，feat(dashboard): improve trace workspace and filters 完成前端过滤器、响应式布局与断线恢复。

后端与 API

新增查询参数

前端

过滤器组合语义

测试与文档

兼容性说明

• 所有新增查询参数均为可选，未传入时查询行为与改动前一致，不构成破坏性变更。

• 未新增数据库表或字段，继续读取既有追踪摘要与 UMO 属性；旧追踪若摘要缺少 has_commands 或 astrbot.umo，按指令、平台或消息类型过滤时不会被命中，但列表展示与详情查看仍沿用既有逻辑，不受影响。

• 新增前端文案已同步四种语言，未引入新的运行时或构建依赖。

• This is NOT a breaking change. / 这不是一个破坏性变更。

Screenshots or Test Results / 运行截图或测试结果

运行截图

更改后的界面如下：

过滤器菜单：

选择会话来源（单选）：

过滤展示结果：

详细信息：

移动端展示：

连接断开：

重新连接：

验证步骤

1. 运行追踪存储单元测试，覆盖新增过滤条件、状态枚举与查询结果数量。
2. 运行 Dashboard API 路由测试，携带全部新增查询参数请求 /api/v1/trace/history，并验证非法时间范围返回 422。
3. 执行前端 TypeScript 类型检查与四种语言的 i18n key 一致性检查。
4. 对 Python 代码执行 ruff check。

测试结果

本次以自动化测试日志与静态检查结果作为验证证据。

单元测试新增断言覆盖：

• commands=True 仅命中带指令处理器的追踪，结果为 1 条。
• status=running/completed/error 分别命中 1/2/1 条，覆盖运行中、已完成和无错误结束、错误结束三种状态。
• platforms=["qq"] 命中 4 条，platforms=["telegram"] 命中 0 条。
• message_types=["Group"] 命中 4 条，message_types=["FriendMessage"] 命中 0 条。
• umo="qq:Group:123" 精确命中 4 条。

API 测试同时传入 status=completed、platforms=qq,telegram、message_types=FriendMessage、umo=qq:FriendMessage:session:user、commands=true、start_time/end_time，返回 200 且 total=1；新增的倒置时间范围请求返回 422。

说明：ruff format --check 对 tests/test_fastapi_v1_dashboard.py、tests/unit/test_trace_store.py 提示的格式差异在 master 上同样存在，属于既有问题；本分支新增的测试代码未引入新的格式差异，ruff check 全部通过。

Checklist / 检查清单

• 😊 If there are new features added in the PR, I have discussed it with the authors through issues/emails, etc.
  / 如果 PR 中有新加入的功能，已经通过 Issue / 邮件等方式和作者讨论过。

• 👀 My changes have been well-tested, and "Verification Steps" and "Screenshots" have been provided above.
  / 我的更改经过了良好的测试，并已在上方提供了“验证步骤”和“运行截图”。

• 📚 I checked the affected WebUI instructions and screenshots in docs/zh and docs/en against the changed navigation, page structure, and labels, and updated them in this PR (or explained why no documentation update is needed). For renamed, moved, or merged entry points, I included an old entry → new entry mapping in the documentation and changelog.
  / 我已对照变化后的 WebUI 入口、页面结构和术语，核对并在本 PR 中更新 docs/zh 和 docs/en 的相关操作说明与截图（或说明无需更新文档的原因）。入口改名、移动或合并时，已在文档和 changelog 中补充 旧入口 → 新入口 对照。

• 🤓 I have ensured that no new dependencies are introduced, OR if new dependencies are introduced, they have been added to the appropriate locations in requirements.txt and pyproject.toml.
  / 我确保没有引入新依赖库，或者引入了新依赖库的同时将其添加到 requirements.txt 和 pyproject.toml 文件相应位置。

• 😮 My changes do not introduce malicious code.
  / 我的更改没有引入恶意代码。

Summary by Sourcery

Improve trace history investigation with richer filtering, responsive workspace behavior, and reliable live-connection recovery.

New Features:

• Add server-side trace history filters for command handling, status, platform, message type, session UMO, and time range.
• Expand the trace workspace with grouped filters, responsive mobile cards, adaptive detail and filter panels, and improved accessibility interactions.

Bug Fixes:

• Keep filtered history, pagination, and live trace updates consistent when search or server-side filters are active.
• Provide clear connection-loss feedback and manual SSE recovery after retry exhaustion.

Enhancements:

• Improve trace workspace presentation with compact status badges, responsive layouts, touch-friendly controls, safe-area support, and focus management.
• Align the trace API client and OpenAPI definitions with the expanded history query parameters.
• Add localized labels for the new filters and connection states across supported languages.

Tests:

• Extend trace storage and Dashboard API tests to cover the new filters and invalid time ranges.