volcengine/OpenViking v0.3.19

OpenViking v0.3.19

on GitHub

OpenViking v0.3.19 已发布。

这个版本是基于 v0.3.18 后当前 main 的一次小版本发布，重点收敛 Console / Web Studio 的多时区数据口径。核心变化是把 Usage/Audit BFF 的时间分桶语义前移到服务端：统计数据统一按 UTC 写入，查询时再按请求里的 viewer timezone 做读端重分桶，前端和外部调用方不再需要、也不应该再做客户端二次时区转换。

相比 v0.3.18 的广泛产品化推进，v0.3.19 更聚焦于一个会影响 BFF 消费方式的 breaking change：/api/v1/console/* 的 date / hour bucket 现在应被视为服务端已经按用户时区解释后的结果。这个改动修复了 Docker / Railway 等 UTC 容器环境下“今天”统计边界不符合用户本地时间的问题，也修复了 Web Studio heatmap 在 UTC+ 用户侧被二次平移到“明天”的问题。

重点变更

1. Console BFF 改为服务端 viewer timezone 分桶（Breaking Change）

/api/v1/console/dashboard/summary、/api/v1/console/tokens 和 /api/v1/console/context-commits 现在支持 IANA timezone 查询参数，例如 Asia/Shanghai。BFF 会以该时区解释用户的日期范围，并返回已经按 viewer timezone 聚合后的 date / hour bucket。

这意味着自定义 Console 客户端、生成 SDK 或外部仪表盘如果直接消费这些接口，需要停止把返回 bucket 当作 UTC 再做本地 shift。新的语义是：请求时声明用户时区，返回值就是该用户时区下的统计分桶。

2. Usage/Audit 统一按 UTC 写入，读端多时区重分桶

Usage/Audit 的 token、retrieval、context commit、agent activity 和 request audit 相关时间字段统一写入 UTC 口径，包括 date_utc、hour_utc 和 created_at。查询时，store 会把用户本地日期范围扩展到覆盖对应 UTC 小时窗口，再用 Python zoneinfo 进行重分桶。

这个设计避免了写入时被 server/container 本地时区固化的问题，也让同一份统计数据可以服务不同时区的用户。DST、UTC+8、America/New_York，以及 India / Nepal 这类半小时或 45 分钟偏移时区都按读端时区规则处理。

3. 本地 Usage/Audit SQLite schema v3 reset

本版本引入 Usage/Audit SQLite schema version v3。升级时，如果检测到不兼容的本地旧表结构，会重置并重建 usage_token_daily、usage_retrieval_daily、usage_token_hourly、usage_retrieval_hourly、usage_context_write_bucket、usage_agent_activity_daily 和 request_audit。

这会丢弃已有的本地 usage rollup 与 request audit 行；考虑到这部分数据当前属于短保留、pre-GA 的产品统计数据，这比保留混合 local/UTC 字段或半迁移 daily/hourly 表更安全。

4. Web Studio heatmap 对齐新的 BFF 语义

Web Studio 现在会通过 Intl.DateTimeFormat().resolvedOptions().timeZone 把浏览器时区传给 Console BFF。context commit heatmap 直接使用服务端返回的 item.date 聚合，不再运行旧的 shiftBucketToLocal 客户端平移逻辑。

这个修复解决了 #2178 的客户端平移逻辑与 #2190 服务端分桶同时存在时造成的 double-shift：UTC+ 用户的“今天”提交不再被显示到“明天”。

5. 其他补充更新

本版本还包含几项相邻更新：新增 session skill extraction 链路，可通过 memory.session_skill_extraction_enabled 控制；补充 Hermes-backed OpenViking LoCoMo benchmark scripts；修正 OAuth client OTP 文档，指向 Web Studio 侧边栏底部新的 OAuth setup 入口；同时刷新 LiteLLM 依赖范围。

Breaking Change / 升级说明

• 自定义 Console 客户端、生成 SDK 或仪表盘如果调用 /api/v1/console/*，应按需传入 timezone=<IANA name>，并移除客户端侧 UTC 到本地时区的二次分桶逻辑。
• tokens 和 context-commits 返回的 date / hour 已是 viewer timezone 下的 bucket；audit.created_at 仍为 UTC ISO 字符串，只需要在展示层格式化。
• 首次使用新的 Usage/Audit SQLite schema 启动时，不兼容的本地 usage/audit 表会被删除并重建；已有短保留 usage rollup 与 request audit 记录可能被丢弃。
• 如果自动化侧固定了 OpenAPI client、Console API 类型或静态 schema snapshot，需要重新生成，以包含新的 timezone 参数。
• 未传 timezone 时，Console BFF 会回退到 server.observability.usage_audit.timezone（默认 local）；服务端集成若需要稳定的用户日边界，应显式配置或传参。

按主题汇总的相关 PR

Console BFF / 多时区 / Web Studio

• #2190 持久化 Usage/Audit UTC 时间字段，并按请求时区重分桶
• #2194 移除 Web Studio heatmap 客户端二次时区平移，跟随服务端分桶

Session Skill / Benchmark

• #2182 新增从 session commit 流程提取可复用 skill 的链路
• #1985 新增 Hermes-backed OpenViking LoCoMo benchmark scripts

文档 / 依赖

• #2192 修正 OAuth client OTP 文档，指向新的 Web Studio OAuth setup 入口
• #2174 刷新 LiteLLM 依赖范围

完整变更

• Compare: v0.3.18...v0.3.19

What's Changed

• feat(benchmark): add Hermes OpenViking LoCoMo scripts by @ehz0ah in #1985
• docs(oauth): point OAuth client OTP to sidebar OAuth setup entry from #2178 by @r266-tech in #2192
• feat(skill): Add extracting skills from session commit processing by @yeshion23333 in #2182
• fix(observability): persist usage/audit in UTC and bucket per request tz by @ZaynJarvis in #2190
• chore(deps): update litellm requirement from <1.84.1,>=1.83.7 to >=1.83.7,<1.85.2 by @dependabot in #2174
• fix(web-studio): drop client-side heatmap tz rebucket by @ZaynJarvis in #2194

Full Changelog: v0.3.18...v0.3.19