前言¶
在 DeepSeek Harness（DSH）里跑 Agent 或批量调用 API 时，费用往往按月汇总出现在官方控制台，很难一眼看出是哪个 API Key、哪类模型、或哪一天把用量拉上去的。把官方导出的 ZIP 或自家整理的 CSV / JSON 留在本机做统计，又不希望账单字节流到第三方服务，就需要一套和会话界面绑定的本地分析能力。下面介绍社区插件 dsh-token-usage（维护者 Jimmy-20100728），它在 DSH 内完成导入、归一化、分析与展示，分类属于 admin-security，当前 npm 包版本为 1.1.0。
这是什么¶
dsh-token-usage 是 DeepSeek Harness 插件：导入 DeepSeek 官方导出 ZIP（amount-*.csv + cost-*.csv）、通用 CSV 或 JSON，在会话界面新增「Token 用量」标签页，查看费用趋势、按模型 / API Key / 自定义分组对比、缓存命中与节省、输入输出构成、异常用量检测；也可在对话里让 Agent 调用 token_analysis 工具。解析、统计、落盘均在 DSH 本机进程内完成，浏览器只访问本机 /api/token-usage/*。
同一套 analyze() 逻辑同时供 Web UI 与对话工具使用，两边数字一致。
它解决什么问题¶
官方控制台侧重「当月花了多少」，本插件针对以下缺口做本地补充（README 中列出的能力）：
- 哪个 API Key / 项目 在消耗更多：账单本身不按 Key 拆分时，按 token 与单价权重把月账单分摊到 Key。
- 缓存命中率 与命中节省的费用。
- 输入 / 输出 Token 构成。
- 哪天 用量突增：采用中位数 + MAD 判定，相对均值更抗离群点。
核心功能¶
数据导入与存储¶
支持拖拽或「导入文件」上传；同一数据集可多次追加（例如先 amount-*.csv 再 cost-*.csv，或 ZIP 内两份一起）。默认数据目录为 $DSH_HOME/token-usage（一般为 ~/.dsh/token-usage），可通过插件配置项 dataDir 覆盖。目录下保存数据集元信息、归一化 rows.json、原始文件及 groups.json（自定义分组）。
界面仪表盘（1.1.0）¶
会话顶部视图标签出现「Token 用量」。可切换按日 / 按周 / 按月、Token / 费用、模型 / API Key / 分组；底部「自定义分组」可为 Key 起业务名并按组聚合。
仪表盘包含：KPI 条（总 Token、总费用、缓存命中率、缓存节省、请求数、日均 Token）；趋势区（堆叠柱状或折线）；三栏分析（模型排行、Token 构成图、统计参数）；异常用量检测与中文解读。图表为自绘 SVG，无 ECharts、无远程字体。
对话工具 token_analysis¶
Agent 可调用 token_analysis，例如分析已导入的最新数据集、直接分析本机路径（不落库）、或 persist: true 分析并入库。返回结构化数据并渲染为中文 markdown。
HTTP API¶
路由经 Host 连接鉴权（connection.requestRejection），与 DSH 自身 /api 同一策略；无该能力时退回仅信任 loopback。主要路径包括：GET /api/token-usage/state、POST /api/token-usage/import、POST /api/token-usage/import-path、GET /api/token-usage/analysis、GET /api/token-usage/export、POST /api/token-usage/groups、POST /api/token-usage/rename、POST /api/token-usage/delete。
费用口径¶
优先级为：billed（cost-*.csv）→ reported（通用数据自带 cost）→ price（amount 的 price × amount）→ estimated（内置价目表）。缺 cost-*.csv 的月份会在界面标明费用为推算，不冒充精确账单。
安装与启用¶
插件为纯 JavaScript（ESM），无需构建，无第三方依赖，仅依赖 Node 自带的 zlib。package.json 要求 Node ^22.19.0 || >=24.0.0。许可证为 MIT。
README 给出的安装方式如下，请按你本机 DSH 的插件管理习惯选择其一：
# 方式 A：在本机 DSH 里用插件管理器安装包目录
# plugin_manager install_bundle target = <本仓库绝对路径>
# 方式 B：打包成 tgz / 目录后放进 profile 的 node_modules 再启用
npm pack # 生成 dsh-token-usage-1.1.0.tgz
安装后由 cordis.patch.yml（dsh.bundle.patch）向 bundle 注入 dsh-token-usage，并注册 Web 客户端（lib/client.js 注入会话视图标签）。
典型用法¶
在界面里导入并查看¶
- 打开 DSH 会话，切换到「Token 用量」标签。
- 拖入 DeepSeek 导出的 ZIP，或 CSV / JSON；需要时可对同一数据集多次追加文件。
- 切换时间桶与维度，按需配置「自定义分组」后保存，查看排行与趋势。
在对话里让 Agent 分析¶
// 分析已导入的最新数据集
{ "name": "token_analysis", "arguments": { "bucket": "week", "group_by": "key", "top": 10 } }
// 直接分析本机文件（不落库）
{ "name": "token_analysis", "arguments": { "path": "D:/账单/export.zip", "bucket": "day" } }
// 分析并入库，之后可在界面里继续看
{ "name": "token_analysis", "arguments": { "path": "D:/账单/amount-2026-08.csv", "persist": true } }
脚本调用分析接口¶
对已入库的数据集，可带鉴权请求：
GET /api/token-usage/analysis?datasetId=&bucket=&from=&to=&top=
参数与 UI 侧分析一致，便于与自有报表串联。
适用场景与注意¶
适合谁：需要在 DSH 工作台内做 Token / 费用复盘、按 Key 或项目分组对比、观察缓存节省与突增日的团队或个人；希望账单文件不出本机的环境。
权限与安全：插件以当前 DSH 进程权限运行，可读写 dataDir、通过 import-path 读取服务器本机路径。安装前应自行审阅 GitHub 仓库 源码与 MIT 许可证。README 说明不写遥测、不向外部服务发送账单数据。
已知边界（来自 README）：ZIP 仅支持 store / deflate，ZIP64 会报错；Key 级费用为权重分摊，不是账单原始拆分；界面文案目前为中文，未做 i18n。
生态说明：DSH 社区插件目录由独立站点维护（SkillHub 目录页），与 DeepSeek / 幻方无官方从属关系；「一切皆插件」是 DSH 的使用方式，本文介绍的是社区维护的 admin-security 类插件。
结尾¶
dsh-token-usage 把官方导出与通用账单文件留在本机，用同一分析内核驱动「Token 用量」页与 token_analysis 工具，补齐 Key 维度、缓存与突增等控制台不易展开的细节。若要安装细节与适配器扩展，以仓库 README 为准。
