前言¶
在 DeepSeek Harness（DSH）里跑多个 API 通道、多个工作区会话时，Token 和成本往往分散在台账文件、会话持久化与通道配置里。宿主本身不一定提供按通道、按项目、按会话汇总的只读视图。若你只想在本机看清「用了多少、花在哪、余额还剩多少」，又不想为看数单独写脚本或依赖额外 SaaS，就需要一个挂在侧边栏、数据来自本机、默认少联网的客户端插件。
下面介绍社区插件 dsh-key-usage（维护者 xyl886，分类：客户端）：在 DSH 侧边栏提供「使用情况」面板，按通道查看用量明细、活跃热力图、项目与会话聚合，并在总览中查看余额与配额快照（实时查询优先，失败回落本机快照）。
这是什么¶
dsh-key-usage 是 DeepSeek Harness 的侧边栏用量面板插件。npm 包名 dsh-key-usage，当前版本 0.1.8，许可证 MIT，要求 Node.js >= 22，支持 web 与 desktop profile。
一句话定位：读你机器上的用量台账与会话投影，在侧边栏展示总览、使用明细、项目用量、按模型、会话用量；成本按官方账单与内置价目规则展示，定不下来显示 — 而不猜测。界面中英双语跟随宿主「通用 → 语言」，字号跟随宿主通用字号设置。
目录页：skillhub.cn/plugins/xyl886/dsh-key-usage
源码与说明：github.com/xyl886/dsh-key-usage
核心功能¶
总览¶
- 通道清单：每通道一行，含类型、今日与近 30 天调用量、余额或订阅窗口占用、30 天成本（带来源角标）。
- 通道详情弹窗（点击通道行）：官方余额（总余额 / 赠送 / 充值）或订阅窗口占用（5 小时 / 本周 / 本月及重置时间）、查询时间；失败时界面提示「实时查询未成功 · 查看系统日志」。弹窗内可切换 ¥ / $、刷新汇率与价目，并展示该通道近 30 天模型单价表（含「官方价 / 聚合 / 模型官方价」来源与「· 部分」提示）。
- 活跃热力图：近 9 个月按日 Tokens，五档深浅；横向滚动时星期列固定在左侧。
使用明细¶
- 时间范围：今日 / 周 / 月 / 总计 / 自定义（日历弹层选起止）+ 通道下拉，全页联动。
- 十张统计卡：调用次数、Tokens、输入、输出、缓存读、缓存命中率、日均 Tokens、通道数、使用天数、成本；每张带上期值与环比角标（「总计」范围整组不显示环比）。
- 通道占比条、按天 / 按小时图表（单日自动切 24 小时视图）；悬停时浮层固定在图表右上角并高亮对应列。
项目用量、按模型、会话用量¶
- 分别按工作目录、通道 + 模型、单个会话聚合；支持搜索、通道筛选与排序。
- 会话按日期分组，可显示已归档会话；没有人类提问的会话不显示。会话名与工作区对齐宿主会话投影；子代理判定以投影中的
subagent字段为准。 - 会话详情抽屉：首条真实提问、工作区、通道、四类 tokens 与命中率、成本与来源角标、逐模型占比；有样本时提供 24 小时迷你图。
- 列表首屏 50 条，可「加载更多」；可从会话行跳转到对应项目的「项目用量」视图。
导出与系统日志¶
- 总览、使用明细、项目、模型、会话四处均可将当前筛选结果导出为 CSV（UTF-8 BOM）或 JSON。
- 页头日志图标：查看
$DSH_HOME/dsh-key-usage/plugin.log（JSONL）中的刷新价目、汇率、余额查询失败原因等；可刷新、复制、导出、清空。页面上的失败结论可一键打开日志窗。
成本与价目（摘要）¶
取值优先级：官方账单（台账记录）→ 通道内价目（插件内置厂商官方价目；未收录时按 LiteLLM 聚合价经通道别名命中）→ 同模型官方价目（聚合价全库唯一命中等规则）。2026-10-16 起已移除「估算」层，无法定价则显示 —。内置价目随包发布于 data/pricing-catalog.yml，升级会覆盖，文档要求不要手动改该文件。点「刷新价目」可从 GitHub / jsDelivr 拉取 LiteLLM 聚合价目副本到 $DSH_HOME/dsh-key-usage/model-prices.json（校验失败不覆盖旧文件）。
数据、权限与联网¶
插件以当前 DSH 进程权限运行；安装前建议自行查看源码与 MIT 许可证，确认读写范围可接受。
主要只读来源
| 读取对象 | 用途 |
|---|---|
$DSH_HOME/dsh-usage/usage-ledger.json |
用量台账 |
$DSH_HOME/dsh-usage/provider-snapshots.json |
余额 / 窗口回落值 |
$DSH_HOME/profiles/<profile>/cordis.yml |
通道清单（文本提取，不执行 !!js） |
宿主 sessionPersistence |
项目 / 会话 / 详情 / 按小时（只读句柄） |
宿主 credentials / 环境变量 |
查余额时拼 Authorization（不读凭据文件） |
写入位置（均在 $DSH_HOME/dsh-key-usage/）：snapshot.json（五 Tab 统一快照，定时与打开页时重算）、model-prices.json、fx-rate.json、plugin.log。上述文件不含密钥；宿主配置与 provider-snapshots.json 只读；端点仅接受回环请求。
默认不联网。以下三类动作会联网，且需你打开页面或点击触发：
- 打开插件页 / 总览通道详情弹窗：按通道查官方余额或窗口（打开页时缓存超过 60 秒则后台补查；点「刷新」强制重查；失败回落本机快照）。
- 点「刷新价目」：
POST /dsh-key-usage/pricing/refresh。 - 打开页 / 切换显示币种 / 点「刷新汇率」：
GET /dsh-key-usage/fx（12 小时 TTL 内可复用缓存；再失败可用默认汇率并在界面明示）。
不做开机拉取、不做定时轮询、不在其它端点隐式联网。
安装与启用¶
在对应 profile 下执行官方安装命令（包名 dsh-key-usage）：
dsh plugin --profile web add dsh-key-usage
dsh plugin --profile desktop add dsh-key-usage
安装完成后，在 DSH 侧边栏打开「使用情况」即可。首次打开会基于本地台账与会话重建快照；若需最新聚合价目或汇率，在界面内使用「刷新价目」「刷新汇率」；查余额需通道已配置可用 API Key（未配置时原因写入系统日志）。
典型用法¶
- 日常核对：打开侧边栏「使用情况 → 总览」，看各通道今日 / 30 天用量与成本角标；需要余额时点通道行打开详情弹窗。
- 排查某段时间：进入「使用明细」，选周 / 月或自定义日历范围，必要时用通道下拉过滤，结合十张卡片环比与按天图表定位异常峰值。
- 按项目或会话归因：在「项目用量」按工作目录排序筛选；在「会话用量」按成本或命中率排序，点开会话详情看首问与模型构成。
- 离线归档：在当前筛选下导出 CSV 或 JSON，便于 spreadsheet 或自有分析脚本使用。
- 失败排查：界面出现「查看系统日志」时打开日志窗，查看余额 / 价目 / 汇率请求的上游 URL 与 HTTP 状态，必要时对单项点「重试」。
以上步骤均来自插件 README 描述的操作路径，无需额外配置文件即可使用。
适用场景与注意¶
适合
- 已在 DSH 中启用
dsh-usage台账、并希望在本机统一查看多通道 Token、缓存命中率与成本的开发者。 - 需要按工作目录、模型、会话维度做用量归因，且希望会话命名与侧边栏一致的用户。
- 希望在少联网前提下偶尔刷新官方余额与价目表，并接受失败时回落本地快照的场景。
注意
- 插件分类为客户端，依赖宿主 Node >= 22 与 DSH 的 sessionPersistence、credentials 等服务；web / desktop 需分别对 profile 安装。
- 成本展示严格按文档优先级；无账单且无价目命中时为
—，不要与厂商控制台账单混为一谈。 - 错峰、节假日等价目规则以 README 为准（例如 DeepSeek 高峰时段按北京时间工作日定义，插件无法定节假日日历时节假日按高峰价算，偏保守）。
- 社区目录 skillhub.cn 与 dsh-plugin.org 为生态索引站点，与 DeepSeek / 幻方无官方从属关系；星标与 fork 数以各页面当时显示为准（GitHub 当前为 0 star、1 fork）。
结尾¶
dsh-key-usage 把 DSH 本机已有的用量台账、会话投影与通道配置收成侧边栏里的只读面板：总览加热力图、明细十卡与图表、项目 / 模型 / 会话多层聚合，以及可选的余额与价目刷新。若你的痛点是「多通道、多会话，数在本机却不好一眼看清」，可先按上文命令安装，再从总览通道行与使用明细时间范围用起来。
- 目录页：https://www.skillhub.cn/plugins/xyl886/dsh-key-usage
- GitHub：https://github.com/xyl886/dsh-key-usage
