dsh-plugin-usage-analytics

dsh-plugin-usage-analytics

一款给 DeepSeek Harness（DSH）用的本地用量分析插件：订阅会话事件，把工具调用、回合、错误、耗时与能力使用情况聚合成日表，在侧栏面板里展示，并对外提供一套本地 HTTP 查询接口。默认 local 模式、零出站，不采集任何消息正文。

配图说明：上图是本插件随包发布的 icon.svg（32×32，侧栏与插件列表共用）。面板截图需要在宿主加载插件后由本机浏览器截取，见 docs/design-mapping.md 的「验证状态」一节。

特性

• 零依赖：纯 ESM JavaScript，只 import node: 内置模块（node:crypto），不需要 TS/打包工具链，装上即可跑。
• 三层幂等：游标（meta.cursors[sid]）+ fork 起点（inheritedEventCount）+ 回填去重，重启、重载、fork 都不会重复计数。
• 脏表才写：内存聚合 → 每 flushIntervalMs（默认 10s）只把脏表落盘，写放大可控。
• 可降级：取不到 storageDomain 时自动切内存档，面板与接口照常工作，只是重启即丢（diagnostics.storage.kind === 'memory'）。
• 可关：collect:false 停止采集，selfExclude 排除本插件的工具调用，retentionDays 控制保留天数（同时裁剪内存与落盘）。
• 围栏与限流：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/ 产物随仓库提交。

离线安装 / 手工等价（本机当前就是这种装法，等价于上面三步）：

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

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

配置

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

验证状态（真机）

面板

侧栏入口「用量分析」，主面板包含：

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

配色只用宿主 --dsw-alias-* 主题 token（带回退值），跟随浅色/深色主题。

HTTP 接口

前缀 API_PREFIX = /dsh-plugin-usage-analytics/api。

JSON-RPC 方法面（设计 §7.5）

POST <prefix>/，请求体 { "method": "...", "params": { ... } }，响应 {ok:true,value} 或 {ok:false,error:{code,message,retryable?,detail?}}。

range 接受数字、"7d"、{days}、{from,to}，上限 366 天；错误码 E_ORIGIN/E_RATE/E_RANGE/E_PAYLOAD/E_CONSENT/E_METHOD/E_INTERNAL 映射到设计 §7.5 的状态码表。

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 共用同一批聚合函数。

分页上限统一由 lib/shared.js 的 PAGE_SIZE / MAX_PAGE_SIZE 定义（REST 与 JSON-RPC 共用），/sessions 默认 20 条。

POST /reset 与 RPC 的 reset 都必须显式带确认（?confirm=RESET / params.confirm:"RESET"），否则回 E_CONFIRM。

存储

每个 profile 一个 domain：plugin_analytics_<profile 名>（storageDomain.open），默认 layout: 'single'，落盘位置由宿主的 DSH_HOME/storages 决定。表：

• meta：installId、settings、cursors、dropped、sampled
• daily：按天的总量（toolCalls/toolErrors/turns/sessions/tokens/ms）
• toolDaily：day + tool 维度
• capDaily：day + 能力键 维度（MCP / skill）
• sessions：会话首见与累计（turns/toolCalls/errors/model）

隐私

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

开发

无构建步骤，直接改 lib/*.js：

node --test test/store.test.mjs test/aggregate.test.mjs test/collector.test.mjs \
           test/routes.test.mjs test/rpc.test.mjs test/index.test.mjs

75 条测试全通过。node --test test/（只给目录）在 Windows 上会报 Cannot find module ...\test，必须显式列文件。

已知限制

见 docs/design-mapping.md：设计里的 plugins/env/events/report/SDK/上报通道在本实现中是明确降级（数据模型不含插件清单与逐事件行），逐条列了原因与替代方案。设计 v1.0 与评审报告不在本仓库内。

许可证

MIT。

---

dsh-plugin-usage-analytics (English)

A local-only usage analytics plugin for DeepSeek Harness. It subscribes to session events, aggregates tool calls, turns, errors, latencies and capability usage into daily rows, renders them in a sidebar panel, and exposes a fenced local HTTP API.

Highlights

• Zero runtime dependencies: plain ESM JavaScript, only node: builtins; no build step.
• Idempotent ingestion: per-session cursor + inheritedEventCount fork boundary + backfill dedupe.
• Write amplification control: in-memory aggregation, dirty tables flushed every flushIntervalMs (default 10s).
• Graceful degradation: falls back to an in-memory store when storageDomain is unavailable (diagnostics.storage.kind === 'memory').
• Switches: collect, selfExclude, sampleRate, retentionDays.
• Fence + rate limit: the Host header must be a loopback name (127.0.0.1/localhost/[::1] — this is what stops DNS rebinding), plus Sec-Fetch-Site/Origin checks, 10 writes per second, 64KB body cap.

Image note: icon.svg (32×32) ships with the package and is used by both the sidebar and the plugin list. Panel screenshots must be taken in a local browser after the host has loaded the plugin; see the "validation status" section of docs/design-mapping.md.

Install

Preferred: dsh plugin --profile <profile> add github:wjf1/dsh-plugin-usage-analytics — package.json declares a dsh.bundle manifest (plus dsh.client for the web UI), so it installs with no build step.

Offline / manual equivalent:

1. Put the package directory into the profile's node_modules (junction or plain copy): ~/.dsh/profiles/<profile>/node_modules/dsh-plugin-usage-analytics
2. Append "dsh-plugin-usage-analytics" to dsh.profile.bundles in the profile's package.json (not to dependencies — a bundle needs no npm resolution).
3. Restart DSH. A newly added bundle can activate through HMR; replacing an installed package requires a restart.

Once loaded, open "Usage Analytics" in the sidebar; GET /dsh-plugin-usage-analytics/api/ should return {"ok":true,"value":{"ready":true,...}}.

Configuration

Keys are written under config in cordis.patch.yml (whitelisted keys are also hot-editable at runtime via the settings method):

API

POST /dsh-plugin-usage-analytics/api/ with {method, params} — 18 design methods: overview, plugins, plugin, capabilities, env, series, events, settings.get/set, consent.get/set, report.preview/now/clear, data.delete, export, diagnostics, reset. Convenience REST GETs back the sidebar panel. Requests are gated by a loopback Host (blocks DNS rebinding) plus Sec-Fetch-Site and Origin/Host consistency, capped at 10 writes per second and 64KB per body. Both the REST /reset?confirm=RESET endpoint and the RPC reset method require an explicit confirmation.

Validation status (real host)

Development

No build step — edit lib/*.js directly and run:

node --test test/store.test.mjs test/aggregate.test.mjs test/collector.test.mjs \
           test/routes.test.mjs test/rpc.test.mjs test/index.test.mjs

75 tests, all passing. Passing only the test/ directory makes node --test fail on Windows (Cannot find module ...\test) — list the files explicitly.

Known limitations

See docs/design-mapping.md: the plugins/env/events/report methods, the SDK and the reporting channel are deliberately degraded in this implementation (the data model keeps no plugin list and no per-event rows); each case is listed with its reason and the substitute used instead. Design v1.0 and its review report live outside this repository.

Privacy

Metadata only: tool name, capability class, ok/error, latency, short session hash, model name, turn/step counts, token counters. No message bodies, arguments, outputs, paths, or usernames. Local mode performs zero outbound requests.

License

MIT.