dsh-skill-mcp-stats

Readme

# dsh-skill-mcp-stats

> 想知道每一轮对话里 agent 到底动了哪些 skill 和 MCP？把每一轮翻成一张清单，按钮一点就知道。

Per-turn skill & MCP usage stats for DeepSeek Harness (dsh) — see what the agent actually called, per turn, without digging through transcripts.

原生 DSH 插件：宿主监听 `session/event` 事件流聚合统计，浏览器端在每条 assistant 消息的操作栏加一个 📊 按钮展开查看。

## 功能

- 📊 消息栏统计按钮：不弹窗、不遮屏，面板直接在按钮所在消息下方展开，随对话流滚动
- 🏷 重点概览：skill（绿）与 MCP（橙）彩色标签 + 调用次数，本轮/本会话用了什么一眼可见
- 📚 轮次明细折叠：每轮一行摘要，点击展开 skill / MCP / 其他工具的明细；默认展开最新一轮
- 🧠 按会话隔离：面板只统计你当前所在的会话，不会被其他会话的记录干扰
- 💾 自动落盘：每轮结束实时追加 JSONL 日志，进程重启不丢历史
- 🛠 对话内可查：注册 `skill_mcp_stats_summary` 工具，你直接问 agent"这轮用了哪些 skill 和 MCP"也能答
- 🌗 主题自适应：全部使用 DSH 官方主题令牌，深浅色自动适配
- 📡 HTTP API：`GET /skill-mcp-stats/api/overview`（可带 `?session=` / `?scope=latest`）供二次开发取数

## 安装（原生 DSH 装配）

这个插件是标准的 DSH npm 插件包：宿主侧是 cordis 插件（`lib/index.js`），浏览器侧通过 package.json 的 `dsh.client` 字段声明（`lib/client.js`），走 profile bundle 装配，不需要任何特殊注入工具。

### 0. 构建

```bash
npm install          # 安装 typescript / tsdown 等构建依赖
npm run build        # → lib/index.js + lib/client.js + 类型声明
```

### 1. 加进 web profile

编辑 `~/.dsh/profiles/web/package.json`：

```json
{
  "dependencies": {
    "dsh-skill-mcp-stats": "link:D:/dshcahjian/dsh-skill-mcp-stats"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-skill-mcp-stats"
      ]
    }
  }
}
```

> 用 `link:`（pnpm 本地链接）而非 `file:`：链接模式让插件的 `lib/` 改动即时生效，与 profile 里其他本地插件（如 dsh-message-finder）一致。`bundles` 是 cordis 装配列表，宿主插件在这里被装载。

### 2. 安装并重启

```bash
cd ~/.dsh/profiles/web
pnpm install
```

然后重启 `dsh web`。重启后：
- 宿主开始监听事件流统计，日志写到 `~/.dsh/skill-mcp-stats/turns.jsonl`
- 每条 assistant 消息操作栏出现 📊 按钮，点击展开本会话统计

> **依赖实例约定**：插件运行时的 `@deepseek-ai/*` 依赖必须与 dsh 宿主共享同一实例（否则 cordis Service 注入会因双实例失效）。构建后请确认插件目录 `node_modules/@deepseek-ai/*` 是指向 `D:\DSH\npm-global\node_modules\@deepseek-ai\dsh\node_modules\@deepseek-ai\*` 的 junction（本项目 `scripts/link-host-deps.mjs` 可一键重建），**不要在插件目录直接 `npm install`**（会覆盖 junction 为 registry 副本）。日常改动后只需 `npm run build`。

### 卸载

从 `~/.dsh/profiles/web/package.json` 移除依赖和 bundles 条目，`pnpm install` 后重启即可。

## 它怎么工作的

- 数据：宿主监听 `session/event` 事件流，只消费三个事件——`turn/start`（一轮开始）、`tool/call`（每次工具调用，含工具名与参数）、`turn/end`（一轮结算）
- 分类：工具名 `skill` 记入 skill（取参数里的技能名）；以 `mcp__` 开头的记入 MCP；其余归为其他工具
- 界面：`conversation.chat.assistant-actions` Slot（官方给消息反馈类插件预留的按钮席位）注入 📊 按钮，点按后直接在按钮行下方插入内联面板
- 持久化：`turn/end` 时把整轮（轮号、时间、分类计数、调用明细）追加到 JSONL；进程内按 session+turn 内存聚合
- 生命周期：宿主 `ctx.on` / `ctx.effect` 注册，client 卸载即净，无残留

## 开发

```bash
npm run typecheck   # host + client 双端类型检查
npm run build       # 构建 lib/
npm run watch       # client 增量打包（tsdown --watch）
```

结构：
- `src/index.ts` — 宿主侧：事件监听、聚合、JSONL 落盘、`skill_mcp_stats_summary` 工具、HTTP API
- `src/client/index.ts` — 浏览器侧：📊 按钮 + 内联面板
- `tsconfig.json` / `tsconfig.client.json` — host / client 编译配置
- `tsdown.config.ts` — client 打包（`window.__ModuleLoader__.load` 格式，与官方插件一致）

## 已知限制

- 插件注入**之后**产生的轮次才计入实时统计；历史轮次只能在注入时刻按已加载的会话事件回填一次（时间戳为注入时刻，不影响统计正确性）
- 极个别历史事件里 skill 参数为不可解析格式时记为 `(unknown)`，新产生的轮次不受影响
- 目前聚焦"用了什么"，暂不做耗时/成败/参数明细的深挖

## 兼容性

- DeepSeek Harness Web GUI（`dsh web`），`@deepseek-ai/dsh-*` 0.1.0-rc.x
- 依赖官方 Slot：`conversation.chat.assistant-actions` / 宿主 `session/event` 事件流（若未来官方调整这些接口需适配）
- Node.js 任意现代版本（宿主侧仅用 `node:fs` / `node:path` / `node:os` / `node:http`）

## License

BSD-3-Clause