v0.2.3

May 12, 2026 · View on GitHub

主题

把本地用量从 v0.1.2 的"一次性 30 天估算"升级为持久化事实存储层：~/.config/usage-bar/data/<provider>/ 下按 UTC 年月分文件持久化 raw events，另维护按天/月/年三个聚合文件；增量采集（per-file 游标，挂 polling timer 但只读变动文件）；USD 不落盘、前端按当前价格表实时折算（价格表升级后历史自动重算）；popover 新增 GitHub 贡献图风格的消费热力图。supersede 2026-05-11-local-cost-scan。provider 抽象仅做目录结构预留，Codex 采集留后续 spec。

含隐私架构守护延续：parser schema 不读 message.content；含 sessionId 的文件 0600；错误日志只 log error type。

含 spec

  • 2026-05-12-usage-store-redesign — 按 provider 持久化 raw events + 聚合 + 消费热力图

验收（G6 checklist）

  • spec 的 spec_criteria SC1~SC14 全 done
  • swift build -c release Build complete! / swift test Executed 160 tests, with 0 failures（make release-artifacts 在发版 runbook G7 跑）
  • SC_AUTO_NO_PRINT_TOKENS / NO_REAL_TOKEN_PREFIX / NO_CONTENT_READ 全 0 匹配
  • SC_AUTO_LOCALCOSTSCANNER_GONE（LocalCostScanner.swift + 其测试已删）
  • 已用过 Claude CLI 的用户启动 .app 看到消费热力图 — 由用户在 popover 目视（开发会话无法启动菜单栏 app 验证渲染）
  • CHANGELOG.md 已 append v0.2.3 entry
  • 本文件 release_notes_zh 已填写

发版（G7 checklist）

  • docs/runbooks/release.md 全流程跑通
  • tag 已推送，Sparkle appcast 已更新
  • GitHub Release 已创建，资源（zip/dmg）已上传
  • 24h health 回访通过

参考 v0.1.x 用户偏好：v0.2.x 阶段累积，统一在合适节点考虑打 tag。

Release notes (zh)

从 frontmatter release_notes_zh 同步过来（发版 runbook 时复制到 CHANGELOG.md）。

v0.2.3 — 用量统计与存储重设计

改进（Changed）：

  • 本地用量从「一次性 30 天估算」升级为持久化存储：~/.config/usage-bar/data/claude/ 下按月份文件保存每次调用的 token 明细，另维护按天/月/年三个聚合文件
  • 后台采集改为递归增量：递归扫描 ~/.claude/projects/ 下任意层级 .jsonl（含 subagents 三层深），游标每轮批量 flush 一次；启动时一次性回填全部历史
  • 金额不落盘：明细与聚合只存 token 数，金额按当前价格表实时折算

新增（Added）：

  • popover 新增 GitHub 贡献图风格的消费热力图：从最早有数据那天铺到今天（不限一年），打开时默认滚到最右；悬停某格 → 网格下方一行显示「日期 · ≈ $X · N 次」
  • 估算卡跟随趋势图时间范围 picker（1h/6h/1d/7d/30d）；版块顺序：趋势图 → 估算卡 → 热力图
  • per-model 明细行新增 token 总数；金额/token 紧凑单位（K/M/B/T）；金额前缀简化为「$」；collapsed 头部 icon 展示金额/次数/token

内部（Internal）：

  • 新增 UsageEventStore / ScanCursorStore / ClaudeUsageCollector / UsageAggregator / UsageStatsService / UsageHeatmapView；退役 LocalCostScanner；清理 v0.1.2 旧 Caches
  • 损坏月明细 → 游标重置全量重读（避免 pre-cursor 事件丢失）；已统计数据不随源文件删除而清除
  • 隐私守护延续：parser 不读 message.content；含 sessionId/路径的文件 0600 目录 0700；错误日志只记录类型
  • 多账号：本机统计跨账号，切换账号不再清空/重算
  • 已知遗留：两处 Swift-6 严格并发警告（Swift 5.9 下无害，待统一处理）

引用