DSH 插件用量与能力看板

前言¶

在 DeepSeek Harness（DSH）里做智能体开发，常常会遇到一个问题：不知道自己用了哪些能力、调用频率有多高、哪些工具容易出错。本地跑完一通，只能靠日志回忆，没有统一的看板。DSH 的理念是「一切皆插件」，社区里有不少插件做特定功能，但缺乏一个统一的用量与能力看板。wjf1/dsh-plugin-usage-analytics 就是为此出现的一款本地插件：订阅会话事件，把工具调用、回合、错误、耗时与能力使用情况聚合成日表，在侧栏面板里展示，并对外提供一套本地 HTTP 查询接口。默认 local 模式、零出站，不采集任何消息正文。

核心功能¶

1. 本地采集与聚合¶

插件订阅 DSH 的会话事件，按工具名、能力类型（如 MCP / skill）进行聚合，生成以下维度：

工具调用次数、错误数、错误率、平均耗时
回合数、会话数
tokens 进出量

聚合结果按天落盘，存储结构包括：

meta：安装 ID、设置、游标、丢弃与采样计数
daily：按天的总量（toolCalls/toolErrors/turns/sessions/tokens/ms）
toolDaily：按天 + 工具维度的明细
capDaily：按天 + 能力键维度的明细（MCP / skill 等）
sessions：会话首见与累计（turns/toolCalls/errors/model）

2. 侧栏面板¶

插件加载后，在侧栏显示「用量分析」入口。主面板包含：

6 张 KPI 卡：窗口内工具调用、错误数、错误率、平均耗时、会话数、tokens 进出
14 日趋势柱状图（SVG 自绘，不引第三方图表库）
Top 工具表：调用数、错误数、平均耗时、占比
能力分布：MCP / skill 等非原生能力的调用占比条
设置区：collect 勾选、sampleRate 滑杆、retentionDays 数字框
操作区：刷新、立即落盘、清空本地数据（二次确认）、窗口天数切换（1/7/14/30/90）

配色使用宿主 --dsw-alias-* 主题 token，跟随浅色/深色主题。

3. 本地 HTTP 查询接口¶

前缀为 API_PREFIX = /dsh-plugin-usage-analytics/api。提供两类接口：

JSON-RPC 方法面：POST <prefix>/，请求体 { "method": "...", "params": { ... } }，响应 {ok:true,value} 或 {ok:false,error:{code,message,retryable?,detail?}}
REST 便捷端点：GET /、/overview?days=、/series?days=、/sessions?limit=、/tools?days=、/tool?name=&days=、/settings、/diagnostics、/export（NDJSON 下载）；POST /settings、/flush、/reset?confirm=RESET

支持的 JSON-RPC 方法包括：

overview：4 KPI + 窗口汇总 + Top 工具
plugins：工具/能力榜，每页 50
plugin：单工具逐日明细
capabilities：能力排行（mcp/skill）
env：宿主与插件版本、存储状态
series：逐日序列（calls/errors/sessions/turns）
events：最近会话摘要
settings.get / settings.set：读/改设置（白名单）
consent.get / consent.set：同意态（只支持 local/off）
report.preview / report.now / report.clear：上报预览/立即/清空（当前未启用上报）
data.delete：删除本地全部数据
export：内联导出（json/csv/ndjson）
diagnostics：运行态诊断
reset：清空并重扫

range 参数接受数字、"7d"、{days}、{from,to}，上限 366 天。

4. 隐私与安全¶

只记录事件元数据：工具名、能力分类、成败、耗时、会话短哈希、模型名、回合/步数、token 计数
不记录：消息正文、工具参数原文、工具输出、文件路径、用户名、环境变量
会话 ID 以 sha256(sessionId + ':' + installId) 截 16 位存储，卸载重装即换新 installId，历史无法互相拼接
默认 local 模式，代码里没有任何出站请求（可 grep -R "http" lib/ 自证：只有 http://localhost 的 URL 解析基线）

5. 隔离与限流¶

围栏：Host 必须是回环名（127.0.0.1/localhost/[::1]），挡 DNS rebinding
一致性校验：Sec-Fetch-Site + Origin/Host 一致性校验
限流：写方法面每秒 10 次上限，请求体 64KB 上限

安装与启用¶

在线安装（推荐）¶

dsh plugin --profile <profile> add github:wjf1/dsh-plugin-usage-analytics

插件无需构建，package.json 声明了 dsh.bundle（patch: ./cordis.patch.yml）与 dsh.client（web UI），lib/ 产物随仓库提交。

装好后打开侧栏「用量分析」即可看到面板；GET /dsh-plugin-usage-analytics/api/ 应返回 {"ok":true,"value":{"ready":true,...}}。

离线安装 / 手工等价¶

把包目录放进 profile 的 node_modules（Junction 或直接拷贝）：
C:\Users\admin\.dsh\profiles\desktop\node_modules\dsh-plugin-usage-analytics
在 profile 的 package.json 的 dsh.profile.bundles 数组里追加 "dsh-plugin-usage-analytics"（不要加进 dependencies，bundle 不需要 npm 解析）
重启 DSH（新增 bundle 可以靠 HMR 加载，替换已装包必须重启；本仓库采用 Junction，改动即时可见但首次加载仍需宿主扫到 bundle 列表）

配置¶

配置写在 cordis.patch.yml 的 config 段（也可在运行时通过设置接口热改，仅白名单键）：

键	默认	说明
`mode`	`local`	`local` 只落本地；`remote`/`opt-in` 为未来上报预留，当前不产生任何出站流量
`collect`	`true`	总开关，`false` 时不再消费会话事件
`sampleRate`	`1`	采样率（0..1），按 `tool/call`+`tool/result` 成对抽稀，丢弃量记在 `meta.sampled`
`retentionDays`	`90`	保留天数（1..400），定时任务按此裁剪
`maxEventsPerDay`	`200000`	单日事件上限，超出记 `meta.dropped`
`flushIntervalMs`	`10000`	合并落盘间隔，最小 2000
`layout`	`single`	存储布局，`single` 整单元重写 / `per-record` 逐条写（小数据量更稳，大数据量注意小文件数量）
`selfExclude`	`false`	是否排除本插件自身产生的调用
`profileName`	`null`	存储 domain 的 profile 后缀。默认自动探测（`config` → `profile` 服务 → `app.profile` → `DSH_PROFILE`/`DSH_PROFILE_NAME`/`DSH_PROFILE_DIR` → `--profile=` → `ctx.baseDir` 的 `profiles/<name>` → `default`），显式指定可保证多 profile 隔离

使用示例¶

查询概览¶

curl http://localhost:<port>/dsh-plugin-usage-analytics/api/overview?days=7

查询工具排行¶

curl http://localhost:<port>/dsh-plugin-usage-analytics/api/plugins?days=14&q=&sort=toolCalls&cursor=

查询环境与存储状态¶

curl http://localhost:<port>/dsh-plugin-usage-analytics/api/env?days=1

导出数据¶

curl http://localhost:<port>/dsh-plugin-usage-analytics/api/export?range=30&format=json > analytics_30d.json

适用场景与注意¶

适合需要统一查看工具调用、错误率、平均耗时与能力分布的 DSH 智能体开发者
插件以当前 dsh 进程权限运行，安装前应检查源码与许可证（MIT）
当前版本不支持插件清单与逐事件行，设计 v1.0 与评审报告不在本仓库内

总结¶

wjf1/dsh-plugin-usage-analytics 是一款本地、零出站的 DSH 用量分析插件，通过侧栏面板与本地 HTTP 接口，提供工具调用、错误、耗时、能力分布等维度的聚合数据。默认 local 模式，只记录事件元数据，隐私可控。对于需要在本地梳理智能体使用情况、优化工具选择与性能的开发者，这是一个可以直接上手使用的工具。

参考链接¶

插件目录页：https://www.skillhub.cn/plugins/wjf1/dsh-plugin-usage-analytics
GitHub：https://github.com/wjf1/dsh-plugin-usage-analytics