使用场景
微光集首页除了文章入口,也希望保留一点“这个人最近在做什么”的信息。整体介绍见 关于本站:微光集。
ActivityWatch 负责记录应用窗口和离开状态。把这些数据接进网站后,可以展示最近七天的活动时长、分类分布,以及当前活跃、暂离或离线状态。
这里实际上有两条不同的数据链路:七日统计直接查 ActivityWatch,实时状态通过 AstrBot 的 ActivityWatch 场景插件读取。 页面看起来在一起,来源和统计口径却不同。
实现内容与对接入口
| 页面内容 | 数据来源 |
|---|---|
| 首页罗盘的七日总活动时长 | ActivityWatch 查询结果 |
| 每日时长、分类时长与分类内应用 | 本站 Go 汇总 |
| 活跃/暂离/离线、当前场景 | AstrBot 场景插件 |
| 当前应用、窗口标题、近期活动和场景详情 | 场景插件的详情响应,由本站筛选字段 |
服务地址和分类集在 星枢 → 服务 → ActivityWatch 配置;实时场景另外依赖 AstrBot 的地址和 API Key。统计刷新周期由 星枢 → 任务 维护。
统计:ActivityWatch → Go 查询和汇总 → MySQL 保存结果 → /api/activitywatch
状态:ActivityWatch 场景插件 → AstrBot API → Go 整理 → /api/activity-status前端不直接读取本地 ActivityWatch,也不取得 AstrBot API Key。网页面对的是本站公开展示接口。
最近七天到底统计什么
时间范围是北京时间的今天及前六天。前六天从零点到下一天零点,今天从零点到当前时刻,不是简单地取“现在往前 168 小时”。请求 ActivityWatch 时再转换成 UTC 时间区间。
数据使用窗口 bucket,与同一台设备的 AFK bucket 取交集:
窗口活动记录 ∩ not-afk 时间段 → 按应用合并 → 分类与每日汇总当前实现要求能唯一确定一个 aw-watcher-window_… bucket,并存在名称对应的 aw-watcher-afk_… bucket。多台设备混在一起时不会随便选一个,需要先整理数据源或扩展选择逻辑。
核心查询如下,具体 bucket 名称由后端读取后填入:
w = query_bucket("aw-watcher-window_设备名");
a = query_bucket("aw-watcher-afk_设备名");
a = filter_keyvals(a, "status", ["not-afk"]);
w = filter_period_intersect(w, a);
RETURN = merge_events_by_keys(w, ["app"]);这里会排除 LockApp.exe。因此,页面上的总活动时长是满足这套规则的窗口活动时长,并不是开机时长,也不应直接拿 AW 任意一个页面的总数来比较。
分类规则怎么复用
后端先读取 AW 设置,优先使用服务接入里指定的分类集;没有指定时,尝试当前启用的分类集,再兼容旧的 classes 配置。
当前支持正则类型的分类规则,匹配的是应用路径。规则按层级深度优先处理,命中后汇总到分类名称的第一层。没有命中规则的应用仍归入“未分类”。
应用展示名会从路径中取文件名,分类内再按应用合并和排序。最终输出每日时长、分类时长、百分比和应用明细。
AW 里的分类树可以很细,本站目前展示的是一级分类汇总。正则由 Go 处理,也不能假定所有其他正则引擎的写法都兼容。
使用的 API
| ActivityWatch 原生接口 | 用途 |
|---|---|
GET /api/0/settings | 分类集、启用分类与旧版分类配置 |
GET /api/0/buckets/ | 找到窗口及对应 AFK bucket |
POST /api/0/query/ | 同一查询提交七个 timeperiods,取得每日活动 |
GET /api/0/buckets/{windowBucket}/events?limit=1 | 读取最后一条窗口事件,计算最后活动时间 |
实时状态使用的上游接口是:
GET /api/v1/plugins/extensions/astrbot_plugin_scene_aw/dashboard/state
X-API-Key: <在服务接入配置的 AstrBot API Key>这是当前场景插件提供的接口,不是 ActivityWatch 原生 API。插件如何判断场景属于上游实现,本站负责读取和整理它返回的状态。
| 本站公开接口 | 输出 |
|---|---|
GET /api/activitywatch | 七日总量、每日分布、分类、更新时间、最后活动时间与 stale |
GET /api/activity-status | 状态、展示文字和当前场景 |
GET /api/activity-status/details | 当前焦点、场景线程、分类画像与近期活动等详情 |
实时状态的交互
上游的 ACTIVE、AFK、OFFLINE 分别映射为活跃、暂离、离线。只有活跃时,才继续展示当前场景和焦点等实时信息;状态接口与详情接口分开,请求详情时才取完整展示字段。
首页定时更新状态,也会在需要时打开详情。后端把同一份场景响应短暂缓存,避免一次界面交互产生多次相同的上游请求。
场景服务不可用时,当前逻辑退回离线展示。
缓存、时间与数据边界
七日统计由后台任务刷新,保存到数据库。前台读取已保存的结果,不会每次打开首页都重新扫描一周的窗口事件。
刷新失败时保留上一份可用结果并标记 stale;已保存的统计超过 20 分钟未更新,也会在读取时标记过期。缺少初始结果时才尝试建立第一份汇总。
最后活动时间按事件开始时间加持续时长计算,不能只取事件开始时间。否则一个持续了很久的窗口,会被误看成很早之前就没有活动。