142 lines
8.8 KiB
Markdown
142 lines
8.8 KiB
Markdown
# Token 活动热力图 — 设计方案
|
||
|
||
> 参考实现：`reference/react-activity-calendar`（grubersjoe/react-activity-calendar，MIT）
|
||
> 该库为 React/SVG Web 组件，本项目用 Jetpack Compose Canvas 重新实现，仅参考其布局逻辑和数据结构。
|
||
|
||
---
|
||
|
||
## 一、入口与数据源
|
||
|
||
- 主页 OCGO 用量卡片「查看详情」右侧新增「Token 活动」快捷入口，点击进入独立的 Token 活动热力图页面（另有独立入口卡片）
|
||
- 首页入口卡片标题「OCGO Token 活动」、副标题「OCGO 每日 Token 使用热力图」（数据来源更准确）
|
||
- **只统计 OCGO 服务的数据**，不涉及 CCGO / Codex / Ollama
|
||
|
||
## 二、页面布局
|
||
|
||
- 标题左对齐：「Token 活动」
|
||
- 标题右侧视图切换：每日 / 每周 / 累计
|
||
- 选中项：主要文字颜色 + 中等字重
|
||
- 未选中项：弱文字颜色
|
||
- 不使用大号按钮背景或明显的 Tab 胶囊样式
|
||
|
||
## 三、每日视图（默认）
|
||
|
||
- GitHub Contribution Calendar 结构：
|
||
- 53 列 × 7 行
|
||
- 每列代表一周，每行代表星期中的一天
|
||
- 越靠右越接近当前日期
|
||
- 按所选自然年显示：今年 = 1月1日 ～ 今天；往年 = 1月1日 ～ 12月31日（完整自然年，取代早期「最近滚动 365 天」窗口，详见「十一、年份选择器」）
|
||
- 格子参数：
|
||
- 尺寸 10～12dp
|
||
- 间距 3dp
|
||
- 圆角 3dp
|
||
- 月份标签：12sp，底部显示
|
||
- 不显示左侧星期标签
|
||
|
||
> 注：2026-08 起已改为**年份选择器（自然年）**取代固定滚动 365 天窗口，详见「十一、年份选择器」。
|
||
|
||
## 四、颜色等级
|
||
|
||
- 6 级：Level 0（空白）+ Level 1～5（逐渐加深的粉色）
|
||
- 使用项目现有配色（Color.kt 中的粉色系）
|
||
- **映射方案：分位数法**
|
||
- 收集所有非零日 Token 数，排序，计算分位阈值
|
||
- Level 0：token = 0（空白）
|
||
- Level 1：0 ～ 25% 分位
|
||
- Level 2：25% ～ 50% 分位
|
||
- Level 3：50% ～ 75% 分位
|
||
- Level 4：75% ～ 95% 分位
|
||
- Level 5：95% 以上
|
||
- 颜色会随数据变化是预期行为（与 GitHub 热力图一致）
|
||
|
||
## 五、每周视图
|
||
|
||
- 与每日视图**共用同一 7 行 × 约 53 列网格尺寸**（列数按所选自然年浮动 52~54），切换视图时布局保持一致
|
||
- 语义为**离散柱状图**：横轴 = 自然周，每一列 = 一周，纵向高度 = 该周 Token 用量
|
||
- 每列从底部向上填充格子，用量越多填充越高；**整列 7 格全部绘制**：底部 barHeight 格 = 该周等级颜色（柱），其余格 = Level 0 浅色（空白格不隐藏，网格完整），最大高度 = 7 格满柱
|
||
- **高度映射**：非零周按 token 去重排序的排名比例映射 2~7 格（height = 2 + rankIndex×5/(uniqueCount-1)，排名不同高度必不同，如 3.7亿 → 2 格、10.7亿 → 7 格；唯一非零值时满柱 7 格）
|
||
- 填充格使用该周的等级颜色（6 级粉色分位，与图例"少→多"一致）
|
||
- 列内格子**不表示周日~周六**（与每日视图的日期语义解耦）
|
||
- 周列与日视图一致按周日对齐；第一列 = 该年 1月1日 所在周（可能含去年 12 月空位），最后一列 = 结束日所在周（今年 = 今天所在周，往年可能跨到次年 1 月初）
|
||
- 点击：每周视图列内任意格子可点击查看该周浮层（"X月X日-X月X日 使用了X token"），含 0 用量周（显示"使用了0token"）；**选中周整列加主题色描边强调**（再次点击或点击其他周取消）
|
||
|
||
## 六、累计视图
|
||
|
||
- 和每日视图同样的小格子风格
|
||
- 53 列 × 7 行
|
||
- 每个格子的颜色代表从起始日到该日的累计 Token 总量
|
||
- 同样用分位数法映射到 6 级
|
||
|
||
## 七、格子交互
|
||
|
||
- **滑动查看（三种视图，OCGO 风格）**：在图表上手指拖动或长按，按速度/时长仲裁两种模式：
|
||
- **长按（按住不动 ≥ 系统长按时长）→ 查看模式**：手指所在格子直接高亮预览（所见即所得），底部读数条显示该格数据；按住期间拖动可切换预览格子，抬起后保留
|
||
- **慢速横向拖动（< 约150dp/s）→ 查看模式**：图表锁定不滚动（保证稳定），**所见即所得**——手指所在格子加主题色边框高亮预览，底部读数条实时显示该格数据（抬起后保留，切换视图/年份清除）
|
||
- **快速横向拖动（≥ 约150dp/s）→ 滚动模式**：放行给图表正常左右滚动浏览（含惯性）
|
||
- 读数条语义与视图一致：**每日/累计**=该天"X月X日 使用了X token"（累计视图 tokens 为累计值）；**每周**=该周范围"X月X日-X月X日 使用了X token"（与周浮层同口径，末周夹取到数据最后一天、跨年带年份前缀）
|
||
- 点击格子显示浮层，内容为日期和当天使用的 Token 数
|
||
- 浮层格式示例：
|
||
```
|
||
7月9日 使用了1.9亿token
|
||
7月10日 使用了1124.5万token
|
||
7月11日 使用了11.2万token
|
||
7月12日 使用了16783token
|
||
```
|
||
（Token 数按数量级自然中文读法显示）
|
||
- **浮层保留卡片外观，但不拦截图表交互**（Popup focusable=false）：点击/滑动直接作用于图表——点其他格子即切换浮层，再次点击同一格子关闭，手指滑动查看图表不受浮层影响
|
||
- 图表支持手指横向滑动查看（配合年份选择器浏览任意年份），页面纵向滚动
|
||
- 不需要"查看详情"按钮
|
||
- 热力格支持键盘聚焦，提供日期与 Token 数的无障碍描述
|
||
|
||
## 八、视图切换动画
|
||
|
||
- 切换视图使用约 150ms 的淡入淡出
|
||
- 不要明显的滑动或弹跳动画
|
||
|
||
## 九、Token 定义
|
||
|
||
- 热力图中的「使用 token」= `inputTokens + cacheReadTokens + reasoningTokens + outputTokens`
|
||
- `inputTokens`：未命中缓存的输入 token
|
||
- `cacheReadTokens`：命中缓存的输入 token
|
||
- `reasoningTokens`：推理 token（思维链 CoT）
|
||
- `outputTokens`：输出 token
|
||
- 不包含 `cacheWrite5mTokens` 和 `cacheWrite1hTokens`（缓存写入 token）
|
||
|
||
## 十、Token 数显示格式
|
||
|
||
- 按数量级自然转换为中文读法（locale-aware）：
|
||
- 中文：亿级 1.9亿 / 千万级 1124.5万 / 万级 11.2万 / 万以下原始数字（繁体用 萬/億）
|
||
- 非中文：≥1e9 → 1.9B / ≥1e6 → 11.2M / ≥1e3 → 16.8K / 否则原数字
|
||
- 日期格式同理：中文 "7月9日"（跨年 "2024年7月9日"）；非中文 "Jul 9"（跨年 "Jul 9, 2024"）
|
||
- 浮层/读数条句子（"X月X日 使用了X token"）走 stringResource（heatmap_day_used/heatmap_week_used），按语言拼接
|
||
|
||
## 十一、年份选择器（2026-08 新增）
|
||
|
||
- 标题「Token 活动」右侧为年份下拉选择器（「2026 ▾」），点击弹出年份列表
|
||
- 语义：按**自然年**查看
|
||
- 今年：1月1日 ～ 今天（默认选中年份）
|
||
- 往年：1月1日 ～ 12月31日（完整自然年）
|
||
- 取代原先固定「最近滚动 365 天」窗口
|
||
- 可选年份范围：最早有数据的年份 ～ 今年
|
||
- 三种视图（每日/每周/累计）均跟随所选年份，分位数按所选年份独立计算（颜色随年份数据变化是预期行为）
|
||
- 周视图按自然年时列数浮动（52~54 列，闰年且 1月1日 为周六时可达 54 列）：
|
||
- 第一列为该年 1月1日 所在周（可能含去年 12 月空位）
|
||
- 最后一列为结束日所在周（今年=今天所在周；往年可能跨到次年 1 月初）
|
||
- 浮层日期：日期所在年份与今年不同时前缀加年份（如「2024年7月9日 使用了1.9亿token」）
|
||
|
||
## 十二、图例与滚动（2026-08 新增）
|
||
|
||
- 底部「少 → 多」颜色图例固定显示，不随热力图横向滚动
|
||
- 页面打开 / 切换视图 / 切换年份时，热力图横向滚动自动定位到最右（最新数据）
|
||
- 0 token 的天可以点击查看浮层（显示「7月9日 使用了0token」）；每周视图 0 用量周显示 1 格 Level 0 浅色格、同样可点击（柱状图语义，见「五、每周视图」）
|
||
|
||
## 十三、年度统计（2026-08 新增）
|
||
|
||
- 视图切换器下方 **2×2 网格** 4 个统计卡片（每行 2 个，窄屏友好），**按所选年份**计算（切换年份跟随变化），与图表口径一致
|
||
- **累计 token**：当年全部天之和（= 累计视图最后一天的累计值）
|
||
- **峰值 token**：当年单日最大 token（无数据=0）
|
||
- **当前连续**：从数据最后一天往前数连续 >0 的天数（最后一天为 0 则=0）
|
||
- **最长连续**：当年内连续 >0 的最大天数
|
||
- 实现：HeatmapViewModel 的 `computeStats(dailyData)`（companion 内，internal），结果存于 `HeatmapUiState.stats`；加载与切换年份时随 dailyData 一起更新
|
||
- 连续天数的"有 token"判定：当日 token > 0（0 token 的天视为断档）；数据为 1月1日～结束日的完整日序列，含 0 token 的天
|
||
- Token 数值显示沿用「十、Token 数显示格式」（亿/万中文读法）；天数显示为「N 天」 |