fazhu4 / dsh-usage-insights

dsh-usage-insights

DeepSeek Harness 的本地只读用量面板。它从 DSH 会话事件中统计 Token、请求、Agent 活动、工具调用和性能，在“设置 > 工作活动”中提供可核对的卡片、趋势和分页明细。

当前版本为 alpha。插件不显示金额，不调用模型或服务商接口，也不修改、归档或删除会话。

界面预览

功能

• 按已验证的 IANA 时区自然日查看今天、近 7 天、近 30 天或全部数据。
• 同时按工作区、服务商和模型筛选。
• 分开展示未缓存输入、缓存读取、缓存写入、输出和输出中的推理 Token。
• 展示已计量请求、活跃工作区、活跃会话、Agent Usage、模型耗时、工具耗时、TTFT 覆盖率和缓存复用率。
• 日趋势可在 Token 与请求数之间切换；服务商和模型明细区分 Agent 与 Compaction 请求来源。
• 提供工作区、服务商、模型、会话和工具五种分页明细，可搜索和排序。
• 工具事件没有精确的服务商/模型归因，因此工具维度会禁用这两项筛选，API 对该组合返回 HTTP 400。
• 统计平均首 Token 时间、输出速度、模型耗时、工具耗时、工具失败日趋势和轮次结果。
• 导出与当前筛选及分析维度一致的 UTF-8 CSV。
• 会话行通过 DSH 客户端会话服务打开，不构造私有 URL。
• 中英文界面、键盘可操作标签页、可聚焦的图表日桶和窄屏布局。

安装

dsh plugin --profile web add dsh-usage-insights@0.2.0-alpha.0

v0.2.0 命名空间改版：dsh-activity-report 已更名为 dsh-usage-insights（插件 ID、HTTP 路由、storage domain、CSS 前缀与本地化命名空间全部更新）。安装旧包的 profile 请先 dsh plugin --profile web remove dsh-activity-report，再安装新包并重启 dsh web；派生聚合会从会话事件自动重建。

添加后重启 dsh web，再打开“设置 > 工作活动”。host 插件需要重启加载，client bundle 随页面刷新加载。

指标口径

总输入 Token：

未缓存输入 + 缓存读取 + 缓存写入

总处理 Token：

总输入 Token + 输出

推理 Token 是输出的子集，不会再次加入总量。缓存复用率为缓存读取除以总输入 Token。Agent Usage 覆盖率为带 provider usage 的闭合步骤数除以全部闭合步骤数；模型耗时覆盖率和工具耗时覆盖率分别使用同一自然日 cohort 的已测样本数与闭合步骤/工具调用数。没有分母时显示“未报告”。工具失败率以已经返回结果的工具调用为分母。

today、7d 和 30d 使用配置的 IANA 时区自然日。API 返回实际 timezone、startDay 和排他的 endDayExclusive。卡片、趋势和明细从同一批日期桶聚合。时区或聚合算法版本改变时，插件会在打开兼容的 storage domain 后丢弃旧派生缓存并从会话事件重建，绝不混合不同统计口径。

数据准确性

• 使用类型化 SessionEvent，不接受历史原型的任意对象格式。
• 同一步的早期 usage chunk 会被最终 assistant message usage 替换，不重复计数。
• 最终消息缺失时保留已经报告的 usage，避免失败请求消失。
• compaction 用量单列为 compaction 请求来源，不混入 Agent 覆盖率分母。
• provider 与 model 使用联合路由事实，组合筛选取精确交集。
• 工具调用和结果用 callId 配对并持久去重；重复事件不会增加调用数或覆盖原始起始时间。配对结果、失败和耗时归入调用自然日，使调用数与耗时覆盖率使用同一 cohort。负耗时归零，未闭合区间不进入耗时。
• 每个会话的 watermark、增量状态和日期事实作为一个完整记录原子写入。
• 启动回填期间先缓冲实时事件，再按 seq 合并；重复 replay 由 watermark 忽略。读取失败的会话保持隔离，其实时事件不会越过未读历史推进 watermark，并在下次完整回填后恢复。
• 写入失败会保留 dirty 记录并显示降级状态；刷新会先重试固化，再重新读取页面数据。

本地存储与隐私

插件只读取 DSH 已有的本地会话语料，并通过 DSH storageDomain 的 usage_insights domain 固化每会话聚合记录。实际介质由 DSH profile 的 storage backend 决定。界面和导出不包含提示词、回复正文、工具参数或工具输出。

当源会话从 DSH 逻辑语料中移除时，插件只清理自己对应的派生聚合记录，不修改或删除 DSH 会话数据。

配置

cordis.patch.yml 暴露以下部署参数：

字段	默认值	说明
persistDebounceMs	1000	实时事件合并写入的等待毫秒数；可设为 0
backfillConcurrency	4	历史会话回填并发数，范围 1..32
defaultPageSize	25	明细默认页大小，范围 1..200
timezone	系统 IANA 时区	自然日分桶时区，例如 Asia/Shanghai；非法值会在加载时失败

HTTP API

路由	说明
GET /dsh-usage-insights/summary	卡片、日期趋势、服务商/模型/来源汇总和数据状态
GET /dsh-usage-insights/breakdown	指定维度、排序、方向、搜索、limit 和 cursor 的一页明细；实时投影变化会使旧 cursor 失效
GET /dsh-usage-insights/filters	当前范围及筛选条件下可用的工作区、服务商和模型
GET /dsh-usage-insights/export.csv	当前筛选和维度的完整 CSV
POST /dsh-usage-insights/retry	重试尚未固化的派生记录并返回最新状态

三个 JSON 读取接口都返回 timezone、startDay、endDayExclusive、status 和样本覆盖率。所有读取接口接受 range=today|7d|30d|all，以及可重复的 workspace、provider 和 model 参数。工具维度不接受 provider 或 model。无效筛选组合、枚举、排序、游标或页大小返回 HTTP 400；意外的内部异常返回不泄漏细节的 HTTP 500。

CSV 按维度使用固定列。服务商和模型导出包含 agent_requests、compaction_requests、steps、message_samples 和 ttft_samples，工作区与会话也包含 message_samples，可据此独立核对来源与覆盖率；工作区导出不会重复输出 workspace 列。

开发与验证

需要 Node.js ^22.19.0 或 >=24.0.0 与 pnpm。

pnpm install
pnpm run typecheck
pnpm test
pnpm run build
pnpm run verify:package

pnpm run build 生成 host/client bundle、source map、manifest 和声明文件。pnpm run verify:package 会检查导出、JavaScript 语法和 npm pack --dry-run 文件清单。

License

MIT