使用场景

微光集首页除了文章入口,也希望保留一点“这个人最近在做什么”的信息。整体介绍见 关于本站:微光集。

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 分钟未更新,也会在读取时标记过期。缺少初始结果时才尝试建立第一份汇总。

最后活动时间按事件开始时间加持续时长计算,不能只取事件开始时间。否则一个持续了很久的窗口,会被误看成很早之前就没有活动。


星轨图