Token 用量日历Fiennes4590/dsh-token-usage-calendar

DSH Token 用量日历

一个为 DeepSeek Harness（DSH） 编写的动态 Cordis 插件。它直接读取 DSH 持久化会话日志中的真实模型 usage，按日、周、月展示 Token 用量，并提供模型维度明细、热力颜色自定义和深色模式适配。

本项目不是通用浏览器统计脚本，也不会生成模拟数据；数据来源是当前 DSH 实例的真实会话事件。

功能

- 按日查看：标准月历，日期格为正方形；使用越多颜色越深。
- 按周查看：按周聚合，并用 7 天迷你柱状图展示分布。
- 按月查看：展示全年 12 个月汇总和相对用量。
- 悬停明细：显示未缓存输入、缓存读取、缓存写入、输出、调用次数和总量。
- 模型明细：按提供方与模型汇总当前时间范围的数据。
- 自定义热力颜色：提供 6 种预设色和原生取色器。
- 中文界面：插件中的可见文案均为中文。
- 深色模式：使用 DSH 官方 --dsw-alias-* 主题 Token，自动跟随系统主题。
- 自绘设置图标：16×16 日历与热力格 SVG，不使用 Emoji。

数据口径

插件读取 sessionQuery 提供的持久化会话事件：

- assistant/message.data.usage：优先采用模型调用的最终用量；
- assistant/chunk 中的 usage：作为流式阶段样本；同一 turn:step 的最终消息会替换它，避免重复计算；
- compaction/summary.data.usage：计入上下文压缩产生的模型调用；
- 分叉会话中 SessionHeader.seedLength 之前的继承事件会跳过，避免父会话前缀被重复统计。

总 Token 使用互斥桶求和：

未缓存输入 + 缓存读取 + 缓存写入 + 输出

reasoningTokens 已包含在提供方的输出统计中，因此只展示或留存，不再次加进总量。

DSH 要求

运行时需要以下 DSH 能力：

- Host Service：sessionQuery
- Client Service：slots
- Client Slot：settings.section
- 可选 Client Slot：settings.section.icon
- Dynamic Cordis Builtins：harness、host、React、styles

如果当前 DSH 尚未提供 settings.section.icon，统计页面仍可运行，但导航会使用设置外壳的默认图标。当前版本的 DeepSeek Harness 可通过 keyed settings.section.icon Slot 显示仓库内的自绘图标。

使用方法

1. 校验与生成 Package

只需要 Node.js 20 或更高版本，无第三方依赖：

npm run check
npm run build

生成文件：

dist/cordis-package.json

它的结构与 DSH cordis_define 参数一致，包含完整的 Host/Client JavaScript function body。

2. 在 DSH 中定义并运行

1. 在支持动态 Cordis Plugin 的 DSH 会话中读取 dist/cordis-package.json。
2. 将该对象提交给 cordis_define。
3. 使用返回的 pluginId 和 packageId 调用 cordis_run，首次激活使用 mode: "run"。
4. 按 DSH 页面提示批准 Client Package。
5. 打开 设置 → Token 用量。

动态 Cordis Plugin 属于当前 DSH 进程；进程重启后定义不会保留。如果需要随 DSH 启动永久挂载，应将本仓库源码集成为正式 DSH Cordis 包或加入部署 composition。

项目结构

.
├── src/
│   ├── host.js              # 读取会话日志、去重并聚合真实 usage
│   └── client.js            # 中文日历 UI、模型明细、主题和设置图标
├── scripts/
│   ├── check.mjs            # 校验两个动态 function body 的语法
│   └── build-package.mjs    # 生成 cordis_define 参数 JSON
├── dist/
│   └── cordis-package.json
└── README.md

隐私与权限

- 插件只在当前 DSH 实例中读取会话用量并在设置页展示。
- 不向第三方服务上传会话内容或 Token 数据。
- Client 与 Host 之间只传递聚合后的日期、模型名称和数字统计。
- 插件不会序列化整个 Session、Event 或其他 DSH 内部活对象。

开发说明

src/host.js 和 src/client.js 是 DSH 动态 Cordis evaluator 使用的普通 JavaScript 函数体，不是 ESM 模块：

- 不使用 TypeScript、JSX、import 或 require；
- Client React 使用 React.createElement(...)；
- UI 通过 DSH Slot 注册，所有副作用归属当前 Cordis Fiber；
- Host/Client 通过 Package-private harness.handle 与 host.call 通信。

License

MIT