前言¶

在 DSH（DeepSeek Harness）里跑多轮对话和工具调用时，token 会分散在各会话里；若只看模型侧账单或手工翻日志，很难在同一视图里对齐「用了多少、大概花多少钱、宿主是否吃紧」。DSH 本身会维护会话投影缓存，但默认界面未必覆盖预算水位和进程级 CPU 采样。下面介绍的插件从这份缓存读数，复刻官方「会话统计」工作台排版，把 KPI、图表和月度预算放在侧栏单页里。

这是什么¶

dsh-usage-stats 是社区维护的 DSH bundle 插件（维护者 Stopning，GitHub 仓库 Stopning/dsh-usage-stats，SkillHub 分类为 admin-security）。它不做原始日志解析，而是统计 token 消耗、估算成本、会话数、缓存命中率，并展示 月度预算（鲸鱼水位） 与 宿主进程运行状态（CPU / 内存 / 事件循环 / 运行时长）。界面单页滚动，无第三方运行时依赖；当前 package 版本为 0.1.0，许可证 MIT。

核心功能¶

KPI 与时间范围¶

顶部可选时间范围（24h / 7d / 14d / 30d / all），下列卡片随范围联动：

DSH 运行状态¶

每 5 秒采样（与官方一致，CPU_HISTORY = 60 点覆盖最近 5 分钟）：单核 CPU 百分比、整机负载与核数、内存 RSS、V8 堆、事件循环延迟 p99 与均值、进程运行时长 / PID / Node 版本，以及最近 5 分钟 CPU 柱状图。

图表与会话排行¶

• 每日消耗：按 token 类型堆叠柱状图，右上角显示范围总量与金额。
• 模型花费：按模型列出金额与占比条。
• 会话消耗排行：可切换「按 Token / 按花费 / 按耗时」。
• Token 构成：环形图与四项明细（缓存读取 / 未缓存输入 / 缓存写入 / 输出）。
• 对话性能：平均每轮耗时、平均首字延迟（TTFT）、输出速度（tok/s）、工具错误率（部分指标不随顶部范围变化，见下文限制）。

月度预算（鲸鱼水位）¶

统计 固定为当前自然月，不随顶部时间范围变化。点击金额可就地编辑上限，回车保存、Esc 取消；剩余比例 1 - 已用 / 上限 以「水位」展示，颜色从墨黑经绿、黄、橙到红随额度消耗变化。上限持久化在插件私有存储，而非仅 profile 配置。

安装与启用¶

插件通过 DSH 的 bundle 机制安装。对助手说「装这个插件」，并给出仓库来源（不要手改 profile 的 package.json 或 cordis.patch.yml，也不要手动拷进 node_modules，否则升级会丢）：

github:Stopning/dsh-usage-stats

本地开发时可指定路径：

/path/to/dsh-usage-stats

底层等价于：

plugin_manager{ action: "install_bundle", target: "github:Stopning/dsh-usage-stats" }

装好后侧栏出现 「会话与用量」，位于「插件」与「自动化任务」之间。助手会走 bundle 安装并自动排期重启。

生效规则：

• 改 client.js → 刷新页面（revision 由 mtime + size 计算）。
• 改 index.js → 重启宿主；可排队空闲重启：~/.dsh/bin/dsh-restart-idle。

典型用法¶

在面板里看数与改预算¶

1. 打开侧栏「会话与用量」，选择顶部时间范围查看 KPI 与图表。
2. 在「月度预算」区域点击金额，输入上限后回车保存；Esc 取消。

通过 HTTP 接口（需 DSH 认证 Cookie）¶

四条路由均为 POST，返回 { ok: true, value: ... }：

示例：设置月度预算上限为 100（将 <port> 换为实际端口，dsh-auth-... 换为有效 Cookie）：

curl -X POST http://127.0.0.1:<port>/api/dsh-usage-stats/budget \
  -H 'Content-Type: application/json' \
  -H 'Cookie: dsh-auth-...' \
  -d '{"amount": 100}'

预算文件位置（供了解；直接改文件不生效，须走路由或面板编辑以同步宿主内存）：

~/.dsh/storages/dsh-usage-stats/budget.json

可选 profile 配置¶

在 profile 的插件配置里可覆盖（全部可选）：

budgetAmount: 100        # 被 budget.json 覆盖
budgetPeriod: month      # 目前只支持 month
defaultRange: 30d
refreshIntervalMs: 5000
topSessions: 200
currency: CNY

数据来源与计价说明¶

插件读取 DSH 已维护的投影缓存：

按天成本由 contextActivity.days[date].cost 的四类 token 乘以价目表得到；价目表四级回退：模型定价 → 本渠道 provider → 跨渠道 proxied → 默认价（界面可能标「估算」）。成本换算在宿主完成，客户端使用 cost.display。

适用场景与注意¶

适合谁：需要在 DSH 内长期跑 agent、希望一眼看到 token / 估算成本、自然月预算水位，并同时观察宿主 CPU 与事件循环是否异常的开发者或运维。

权限与安全：插件以当前 DSH 宿主进程权限运行，会读会话投影缓存并注册 HTTP 路由；安装前请阅读 源码与 MIT 许可证，确认符合你的部署策略。社区目录 SkillHub 插件页 与 DeepSeek / 幻方无官方从属关系，DSH 生态理念是「一切皆插件」。

已知限制（README 原文）：

• 成本是估算，不是账单；与实际扣费可能有出入。
• 多数渠道不上报 cacheWriteTokens，「缓存写入」常为 0。
• TTFT 与输出速度只能取全会话累计值，不随顶部范围变化。
• 工具错误率粒度为命令执行失败 / 命令执行总数。
• 预算按自然月，无自定义起止日期。

结尾¶

dsh-usage-stats 把会话 token、估算成本、月度鲸鱼水位和宿主 CPU 监控收进侧栏单页，数据来自 DSH 自带的 session_projcache，安装走 bundle、一行来源即可。进一步细节见仓库 README 与 DESIGN.md。

• 目录页：https://www.skillhub.cn/plugins/Stopning/dsh-usage-stats
• GitHub：https://github.com/Stopning/dsh-usage-stats