@dsh-external/dsh-skill-stats

Readme

# dsh-skill-stats

技能调用统计插件：统计每个技能被 `skill` 工具调用的次数（历史回放 + 实时订阅），帮助判断哪些技能值得保留。只读插件，不修改任何会话日志或技能文件。

## 功能

- **调用统计**：每个技能的累计调用次数、使用过的会话数、首次/最近调用时间、每次调用的具体时间
- **双通道数据**：
  - 历史回放：启动时扫描宿主环境的会话日志（`session.jsonl` / `session.jsonl.zstd`），解析 `tool/call` 事件中的技能调用
  - 实时订阅：监听进行中的工具调用事件，即时累加
- **会话视图**：单个会话用过的技能列表，可排序，每行带迷你趋势图，展开显示大图 + 每次调用时间；已删除的技能标记「已删除」
- **全局面板**：当前所有技能（含 0 次使用）的统计表，支持排序、SVG 趋势图、1/3/7/30 天范围筛选、每次调用明细
- **增量缓存**：按文件记录大小与修改时间，重启只重放发生变化的日志
- **已删除标记**：技能目录不再存在于任何工作区或全局技能根目录时标记为「已删除」
- **加载态**：重放未完成时显示加载提示，不会把统计中的空快照误报为「未使用」

## 仓库与反馈

- **主仓库**：github.com/chen-zz20/dsh-skill-stats（star / issue / PR 请到此处）
- **社区镜像**：github.com/omdsh-dev/dsh-skill-stats（只读镜像，同步主仓库）

## 安装（标准插件流程）

```sh
git clone git@github.com:chen-zz20/dsh-skill-stats.git
cd dsh-skill-stats && pnpm install && pnpm run build
dsh plugin --profile web add link:/path/to/dsh-skill-stats
```

bundle 型插件，自动加入 profile 的 `dsh.profile.bundles` 层，无需手动配置行。

依赖 `@deepseek-ai/*` 已发布至公共 npm registry，`pnpm install` 拉取声明依赖即可安装；若遇 pnpm 10.19+ 的 minimumReleaseAge 拦截，仓库已含 pnpm-workspace.yaml 豁免配置。开发环境的 typecheck/test 需本机 DSH 检出，见「开发」节。

## API

```
GET /skill-stats/api/stats                # 全局（含已删除技能）
GET /skill-stats/api/stats?scope=current  # 当前在磁盘上的技能（含 0 次使用，无已删除）
GET /skill-stats/api/stats?sessionId=...  # 单会话技能使用
```

响应：

```json
{
  "skills": [
    { "name": "file-dsh-issue", "invocations": 5, "sessions": 2,
      "firstUsedAt": 1786000000000, "lastUsedAt": 1786009000000,
      "deleted": false, "callTimes": [1786000000000, 1786009000000] }
  ],
  "archivedSessionCount": 0,
  "ready": true,
  "updatedAt": 1786010000000
}
```

- `ready`：启动重放是否已全部完成（未完成时前端显示加载态，避免把统计中的空快照误报为「未使用」）
- `callTimes`：每次调用的时间戳，升序排列（跨会话汇总按时间而非按会话排序）
- `sessionId` 参数：按会话查询；未就绪的会话会在查询时按需重放其日志

## 开发

```sh
pnpm install      # 拉取声明依赖（@deepseek-ai/dsh-home-paths 等）
pnpm run typecheck   # 类型检查（需本机 DSH 检出，见下）
pnpm test            # 测试
pnpm run build       # 构建 lib/
pnpm run check       # 全部
```

声明依赖：`@deepseek-ai/dsh-home-paths`（dependencies）；`cordis`/`schemastery`/`react`（peerDependencies）。其余运行时 `@deepseek-ai/*` 包由宿主环境注入，构建与安装不依赖它们。开发环境的 typecheck/test 通过 `tsconfig.json` 的 `paths` 与 `vitest.config.ts` 映射到本机 DSH 检出（`../../.dsh/source/current/...`）解析——**无本机检出的环境只能安装运行，typecheck/test 需先配置 paths**。

## 路线图

- [x] 插件骨架 + 标准安装（bundle 声明）
- [x] 服务端：回放已有会话日志 + 实时订阅
- [x] 统计 API
- [x] Web UI：会话 Tab + 设置面板（排序、SVG 趋势图、1/3/7/30 天筛选、已删除标记、加载态）
- [x] 增量缓存：文件级 watermark（size + mtime），重启只重放变化的日志

## 设计说明

- 数据源是宿主环境的持久化会话日志（`tool/call` 事件），与官方计量组件同源——不依赖任何特定插件
- 实时能力是插件形态的独特优势：技能形态的统计工具只能事后全量扫描，插件可以边发生边统计
- 技能删除判定扫描所有工作区与全局技能根目录，不限于当前工作目录