WorkBuddy 用量看板
一条链路：采集日志 → 文字摘要 → 交互面板。全部在本机完成，不联网、不上传。
何时使用
- 用户想知道「我这周 / 这个月用了多少」「哪个模型最费」「哪些项目烧 token」。
- 需要按模型、项目、会话排查消耗结构。
- 想定期（automation）生成用量报告。
不触发：问其他 CLI 的用量、讨论 token 计费原理、写文章时提到「词元」。
前置检查
只依赖 Python 3.9+ 与标准库，无需 pip 安装。先确认日志目录存在：
python -c "import os;print(os.path.isdir(os.path.expanduser('~/.workbuddy/projects')))"
返回 False 说明本机还没有会话记录，直接告知用户即可，不要伪造数据。
执行
python scripts/collect.py # 扫描 + 计价（增量：首次全量，之后只解析变更文件）
python scripts/brief.py # 输出文字摘要（Markdown）
python scripts/render.py # 生成面板，stdout 打印 HTML 绝对路径
再用 present_files 打开 render.py 打印的路径（会自动弹出预览）。
常用参数：
| 参数 | 作用 |
|---|---|
collect.py --days 30 |
只统计最近 30 天 |
collect.py --no-cache |
忽略缓存全量重扫（怀疑数据不准时用） |
collect.py --out DIR |
自定义输出目录（默认 ~/.workbuddy/usage-reports） |
brief.py --top 8 |
排行榜条数 |
render.py --open |
生成后直接调系统浏览器打开 |
回复用户的方式
- 先给结论：把
brief.py的输出压缩成一句总量 + 一张小表（今天 / 近 7 天 / 近 30 天 / 全部），不要整段粘贴。 - 再给结构：模型 Top 3–5、项目 Top 3、最贵会话 1–2 条，挑有信息量的说，例如某个模型单价高但调用少。
- 最后给面板：
present_files打开 HTML，一句话说明可筛选的维度。 - 必须交代口径（照抄下面这段，按实际值替换）：
> 人民币是按厂商公开刊例价逐条折算的等效金额，不等于实际扣费；credit才是平台计费单位。未计价模型（…）的 token 计入总量但金额不计入合计，因此总额是下限。
口径速查
| 单位 | 含义 | 公式 / 判据 |
|---|---|---|
| token | 模型处理量（命中 + 未命中 + 输出） | 逐事件累加；去重键 (sessionId, messageId) |
| 积分（Credit） | 平台计费单位 | 取 rawUsage.credit；覆盖率随报告给出，缺失不当 0 |
| 人民币 | 按官方刊例价折算的等效金额 | (hit×命中价 + miss×未命中价 + out×输出价) / 1e6 |
三条硬规则：
- 人民币 ≠ 账单。它是「若直连官方 API 需要多少钱」，不是平台扣费；实际扣费看 credit。两个数并列才有意义，比值反映平台定价水平。
- 未计价模型只计 token、不计金额，所以总额是下限，必须在回复里点明。
- DeepSeek 峰谷按每条事件的北京时间逐条判定（工作日 9–12、14–18 为高峰，其余半价），不要按天近似。
完整推导、算例、偏差清单与自查命令见 references/methodology.md；价格出处见 references/pricing.md。
口径与坑（务必遵守）
- credit 覆盖率：部分早期请求没有
rawUsage.credit，报告里要标覆盖率，不能把缺失当 0。覆盖率 = 带 credit 的事件数 / 总事件数。 - 去重键：
(sessionId, providerData.messageId)。不要用conversationRequestId去重——一个请求里可能包含多次模型调用，会把真实用量砍掉一大半。 - 缓存字段：命中量在
prompt_cache_hit_tokens/prompt_cache_miss_tokens；cache_read_input_tokens在多数日志里恒为 0，别用它。 - 峰谷价：DeepSeek 按北京时间工作日 9–12、14–18 计高峰，其余时段半价。脚本已按每条事件时间判断，不要用「按天」近似。
- 未定价模型：日志里会出现平台内部代号（如
space-bunny、hy3），公开价目表查不到。标为“未计价”并单列，不要猜价格。 - 会话标题：优先读
~/.workbuddy/workbuddy.db的sessions.title/custom_title（真实标题）；DB 缺失或无标题时，回退到首条用户消息，并清洗<system-reminder>包装与@skill:"…"附件引用。
详细字段说明见 references/schema.md，价格来源与抓取日期见 references/pricing.md。
安全与边界
- 只 读
~/.workbuddy/projects，不修改、不删除任何日志；输出只写到~/.workbuddy/usage-reports。 - 面板是生成时刻的快照；用户要最新数据就重跑三条命令。
- 不把用量数据发到外部服务；
--days之外不做任何上传。 - 面板底部自带「数据说明」区块（来源 / 换算 / 限制），回复里不必重复粘贴，指一下即可。
