962d8f1215
- 修复 4 个 heatmap 提交的编译错误与对抗审查问题：浮层锚定与跨年日期、 Crossfade 快照、时区口径统一（useUtc8）、万级格式化溢出、周视图周日对齐 - 新增年份选择器：自然年语义、默认今年、三种视图跟随、下拉菜单、 图例固定不随热力图滚动、打开默认滚到最右、0 token 天可点击查看 - 每周视图改为离散柱状图：列=自然周，高度按 token 排名比例映射 2~7 格 （不同量级周高度可区分），0 用量周显示 Level 0 空白格（整列 7 格全绘制） - 选中周整列主题色描边强调，浮层日期跨年带年份前缀 - 文档 docs/heatmap-plan.md 补充年份选择器/图例与滚动/柱状图章节
124 lines
5.9 KiB
Markdown
124 lines
5.9 KiB
Markdown
# Token 活动热力图 — 设计方案
|
||
|
||
> 参考实现：`reference/react-activity-calendar`（grubersjoe/react-activity-calendar，MIT）
|
||
> 该库为 React/SVG Web 组件，本项目用 Jetpack Compose Canvas 重新实现，仅参考其布局逻辑和数据结构。
|
||
|
||
---
|
||
|
||
## 一、入口与数据源
|
||
|
||
- 主页新增一个入口，点击进入独立的 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 级
|
||
|
||
## 七、格子交互
|
||
|
||
- 点击格子显示浮层，内容为日期和当天使用的 Token 数
|
||
- 浮层格式示例：
|
||
```
|
||
7月9日 使用了1.9亿token
|
||
7月10日 使用了1124.5万token
|
||
7月11日 使用了11.2万token
|
||
7月12日 使用了16783token
|
||
```
|
||
（Token 数按数量级自然中文读法显示）
|
||
- 再次点击或点击外部关闭浮层
|
||
- 不需要"查看详情"按钮
|
||
- 热力格支持键盘聚焦，提供日期与 Token 数的无障碍描述
|
||
|
||
## 八、视图切换动画
|
||
|
||
- 切换视图使用约 150ms 的淡入淡出
|
||
- 不要明显的滑动或弹跳动画
|
||
|
||
## 九、Token 定义
|
||
|
||
- 热力图中的「使用 token」= `inputTokens + cacheReadTokens + reasoningTokens + outputTokens`
|
||
- `inputTokens`：未命中缓存的输入 token
|
||
- `cacheReadTokens`：命中缓存的输入 token
|
||
- `reasoningTokens`：推理 token（思维链 CoT）
|
||
- `outputTokens`：输出 token
|
||
- 不包含 `cacheWrite5mTokens` 和 `cacheWrite1hTokens`（缓存写入 token）
|
||
|
||
## 十、Token 数显示格式
|
||
|
||
- 按数量级自然转换为中文读法：
|
||
- 亿级：1.9亿
|
||
- 千万级：1124.5万
|
||
- 万级：11.2万
|
||
- 万以下：原始数字（如 16783）
|
||
|
||
## 十一、年份选择器（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 浅色格、同样可点击（柱状图语义，见「五、每周视图」） |