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 使用互斥桶求和： ``text 未缓存输入 + 缓存读取 + 缓存写入 + 输出 ` 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 或更高版本，无第三方依赖： `bash npm run check npm run build ` 生成文件： `text 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。

项目结构

`text . ├── 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