前言¶
在本地运行 DeepSeek Harness 时，常常需要了解每日的 Token 消耗与模型分布。没有集中化的用量面板，查看历史消耗往往只能依赖日志或外部服务，过程繁琐且容易引入隐私顾虑。下面介绍一个本地、仅本地的 Token 用量统计插件。
是什么¶
这是一个面向 macOS Desktop 0.2.0-rc.2 的独立插件，由 zhongyichang1998 维护。它通过读取宿主的会话持久化服务，统计并展示今日/本月总量、模型用量，以及最近 12 个自然周的 7×12 热力图。界面采用中文磨砂卡片，跟随宿主明暗主题。
安装与启用¶
先完全退出桌面客户端，再通过官方 CLI 安装发行包：
dsh plugin --profile desktop add /完整路径/dsh-mini-usage-1.1.0.tgz
安装完成后重新打开客户端，即可在设置中的插件管理里启用或禁用此插件。卸载时使用：
dsh plugin --profile desktop remove dsh-mini-usage
核心功能¶
- 侧栏入口：提供 32px 侧栏入口，支持窄侧栏图标模式与窗口边缘避让。
- 数据展示：显示今日总量/输入/输出、本月累计，支持今天/本月切换。
- 模型统计：优先使用结算消息中的
message.source.provider/model，否则回退到request/header.header.config路由信息。相同模型的不同来源分开统计，跨会话合并同一路由。 - 热力图：最近 12 周，从 11 周前周一到本周日，未来单元格不展示用量。
- 主题与交互：中文界面配合半透明磨砂卡片，跟随宿主明暗主题；支持手动与每 5 分钟刷新、键盘操作。
- 隐私与安全：不注入 credentials/settings/llm 服务，不读 API Key，不修改 Session 或宿主程序；前端仅访问同源
/api/dsh-mini-usage，并限制回环地址、Host、Origin 与专用请求头。
统计口径¶
数据源为宿主的 sessionPersistence.list() / open(id, 'read') / read(offset, length)，覆盖当前 DSH_HOME 中持久化服务可枚举的 Session（含子会话），不只统计当前聊天。
- Input = inputTokens + cacheReadTokens + cacheWriteTokens；Output = outputTokens；Total = Input + Output；reasoningTokens 不额外相加。
- 按 rc.2 官方 token-meter 结算语义读取
assistant/message.data.usage，否则读取 message/attempt 内嵌 stream 最后一条 usage。 - 同一 turn/step 的结算替换前值；
llm/retry-started关闭替换位置，使重试单独累计。seq 游标防止重复事件。fork 的inheritedEventCount前缀不重复计入全局总量。 - 采用系统本地时区、结算事件的自然日。跨日的更正归到更正事件日期；相同值重复结算保留原日期。时区变更后重建索引。
- “—” 表示没有记录或统计不可用，不等于 0；有明确零 Usage 才显示 0。当天存在缺失/异常 Usage 或不提供 Usage 的 LLM compaction 时，该日及所属月显示未知；热力图工具提示解释原因。
- 热力图从 11 周前周一到本周日，未来单元格不展示用量；空心虚线为无记录/不可用，实心最低色阶为已报告的真实零。色阶是当前窗口每日总量的相对强度。
- 只覆盖公开日志中可获取的调用。没有持久化 Usage 的后台模型调用、已删除的会话、其他 DSH_HOME 和账号服务端账单不在统计范围。
派生缓存与性能¶
派生缓存保存在 ${DSH_HOME:-~/.dsh}/storages/dsh-mini-usage/index-v3.json，仅保存每日数值、模型与来源标识、游标和最后结算位置，不存聊天内容或认证数据。缓存采用临时文件 + rename；损坏可从官方记录重建。每次刷新需枚举 Session 元数据，成本随会话数增长。首次建立索引读取可用历史；以后通过 backend revision 跳过未变化日志，变化日志分批读取（每批最多 512 事件）。
适用场景与注意¶
适合需要在本地追踪 Token 消耗、关注模型分布与历史趋势的用户。插件以当前 DSH 进程权限运行，安装前应检查源码与许可证。它不是 API 账户全量账单，不能替代服务端账单或第三方分析服务。
结尾¶
该插件在本地完成 Token 用量统计，不依赖外部服务，不收集聊天内容或认证信息。如需进一步了解或下载，可访问插件目录页与 GitHub 仓库。
