前言¶
在 DeepSeek Harness（DSH）里跑智能体，会话一多，很难从服务商账单或粗略的 input/output 数字还原「本机实际花了多少 token」。缓存读写在真实日志里往往远大于新鲜输入；seed、fork、子智能体还会让同一条 message.id 出现在多个日志文件里，简单相加会重复计数。下面介绍社区插件 花费（xiaobaga281/dsh-token-spend）：在本机设置页增加一页「花费」，直接读已提交的会话日志做日汇总与可视化，不联网、不读账单、不另建业务数据库。
这是什么¶
花费 是 DSH 的 admin-security 类设置页插件，维护者为 xiaobaga281。npm 包名为 @local/dsh-token-spend，当前发布版本 1.0.0（MIT © 2026）。它在宿主侧注册聚合接口，在 Web 客户端注入设置页 UI，解决的是：按服务商意义上的全部 token（输入 + 缓存读 + 缓存写 + 输出）统计用量，按消息 ID 去重，并在会话被永久删除后仍保留已记录的花费。
核心功能¶
插件读本机已提交的会话日志，在设置页展示以下内容（均来自本地派生，无外部请求）：
- 全部用量：四类 token 合计，对齐服务商
totalTokens，而非仅 input + output。 - 今日 / 昨日：顶部展示今日用量及与昨日环比。
- 用量构成：输入、缓存读、缓存写、输出四类占比条。
- 14 天趋势与每日热力图：按本地日历日分桶；点色块可查看当天明细。
- 当天明细：按会话、按模型列出花费，并展示缓存命中率。
- 预算条：日预算参照。未配置
budgetTokens时，按历史最忙一天的用量 ×1.25 取整推算。 - 已删除会话：永久删除会移除会话目录，纯日志总量会「改写历史」；插件用日账本保留已见过的用量，并在页面上单列这部分占比。
两条计数规则¶
- 一次调用只记一次。 同一
message.id可能因 seed / fork / 子智能体继承事件前缀而出现在多个文件；用量按该 id 只计一次。 - 缓存读不算输入。 服务商的
inputTokens不含缓存读取；若只用 input + output，相对真实全部用量可能严重低估。本插件按日志中的完整字段统计。
折叠结果按会话的 snapshot.revision 缓存，刷新时只重读有变化的日志。内存侧默认缓存约 30 秒（见配置 cacheTtlMs）。
已删除会话的账本¶
账本仅保存计数器，不含标题、路径或消息正文，默认路径为：
<DSH_HOME>/storages/token-spend/ledger.json
写入采用「临时文件 + rename」的原子替换，避免写坏时抹掉已有记录。若不需要保留已删会话的花费，可将 retainDeleted 设为 false。
HTTP 接口¶
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/token-spend/summary |
返回聚合结果；查询参数 ?refresh=1 可跳过约 30 秒的内存缓存 |
返回字段包括 totals、days、sessions、models、today、budget、cacheHitRate、retainedDeleted 等（以仓库 README 为准）。
安装与启用¶
DSH 生态里插件通常通过 Plugin Manager 的 install_bundle 安装包目录或发布包，或将其加入 profile 的 bundle 列表。不要凭插件名自行拼接未在文档中出现的 CLI 安装命令。
发布包可在插件仓库根目录打包：
npm pack
产物示例为 dsh-token-spend-1.0.0.tgz（以 package/ 为包根）。包内包含 index.js、client.js、cordis.patch.yml、locale、icon.svg 等（见 package.json 的 files 字段）。
说明：宿主侧（index.js）改动后需重启 DSH 应用；客户端（client.js）随设置页重新加载即可。运行环境要求 Node.js >= 20。
cordis.patch.yml 会向 Loader 插入 token-spend 相关行，由 bundle 机制挂载到现有 DSH 宿主。
配置项¶
在插件配置中可调整以下键（默认值以 README 为准）：
| 键 | 默认 | 说明 |
|---|---|---|
budgetTokens |
0 |
日预算 token 数；0 表示按历史峰值自动推算 |
cacheTtlMs |
30000 |
聚合结果的内存缓存时长（毫秒） |
retainDeleted |
true |
是否在账本中保留已删除会话的用量 |
ledgerPath |
<DSH_HOME>/storages/token-spend/ledger.json |
日账本文件路径 |
典型用法¶
- 按上文方式通过 Plugin Manager 或 profile bundle 安装并启用插件，必要时重启宿主。
- 打开 DSH 设置，进入插件提供的 「花费」 页（显示名来自
displayName与 locale）。 - 查看今日用量、构成、14 天热力图与当天明细；需要强制重算时，可调用
GET /token-spend/summary?refresh=1（例如自行脚本或调试工具，需具备访问本机 DSH 宿主的权限）。 - 若需固定日预算参照线，将
budgetTokens设为大于 0 的整数；若不希望保留已删会话历史，设retainDeleted: false。
插件不替代服务商账单，只反映本机日志与账本中的统计结果。
适用场景与注意¶
适合：在本机 DSH 中长期开发、调试智能体，需要看清缓存读写占比、避免重复计数、并在删会话后仍能对齐历史花费的开发者。
注意：
- 插件以当前 DSH 进程权限读取会话日志并写入
ledgerPath；安装前应阅读 GitHub 源码 与 MIT 许可证，确认符合你的安全策略。 - 社区目录 SkillHub 插件页 与 GitHub 仓库由维护者发布，与 DeepSeek / 幻方无官方从属关系；DSH 理念是「一切皆插件」，本文介绍的是社区插件而非内置功能。
- 统计依赖本地已提交日志的完整性与字段；若日志格式或 DSH 版本与插件假设不一致，展示结果可能不完整，应以仓库 Issue 与版本说明为准。
结尾¶
花费 把「全部 token、按 message.id 去重、删会话不丢账」三件事收进一页设置 UI 和一个可选的 ledger.json，适合作为 admin-security 类本地用量面板。进一步了解可访问目录页与仓库：
- 目录页：https://www.skillhub.cn/plugins/xiaobaga281/dsh-token-spend
- GitHub：https://github.com/xiaobaga281/dsh-token-spend
