dsh-api-usage-monitor

Readme

# dsh-api-usage-monitor

> DeepSeek Harness (DSH) 永久插件（bundle）：实时读取当前正在使用的 LLM API（不限 DeepSeek），在设置页呈现**当前用量**、**分对话用量**，并可扫描会话日志读取**历史用量**。重启后依然生效。

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

## 功能特性

- 🔌 **实时读取当前 API**：通过 `llm/stream` 瀑布事件在适配器层之上观测每一次模型调用，与具体供应商无关——DeepSeek、Pi AI 或任何已注册的 API 路由都能被识别（provider + model）。
- ⚡ **当前用量**：插件启动以来的实时累计，按 API/模型分组，展示输入 / 输出 / 缓存读 / 缓存写 / 推理 token 明细与调用次数，每 2 秒自动刷新。
- 💬 **分对话用量**：按会话（sessionId）聚合的调用次数、token 用量与所用 API。
- 📜 **历史记录**：一键扫描持久化会话日志中的 `assistant/message` 用量记录，得到**插件启动之前**每个历史对话的用量、标题和用过的 API/模型。
- ⚙️ **设置页呈现**：在 DSH 设置面板注册独立页面「API 用量」（`settings.section`，id `api-usage`），四个卡片分区展示，配色使用 DSW 主题变量自动适配明暗主题。

## 架构

| 文件 | 平台 | 职责 |
| --- | --- | --- |
| [`lib/index.js`](./lib/index.js) | Host（Node 进程） | 拦截 `llm/stream` 记录每次调用的 provider/model/sessionId/token 用量；内存聚合实时总量与分会话量；经 `webServer` 注册 `/api/dsh-api-usage-monitor/status` 与 `/history` 两个 HTTP 路由 |
| [`lib/client.js`](./lib/client.js) | Client（浏览器） | `__ModuleLoader__` 单文件 bundle；注册 `settings.section`「API 用量」页；同源 `fetch` 每 2 秒轮询状态，「扫描历史日志」按钮按需拉取历史 |
| [`cordis.patch.yml`](./cordis.patch.yml) | 组合层 | bundle 补丁：向 profile 插入一行 Loader（id `api-usage-monitor`） |
| [`host.js`](./host.js) / [`client.js`](./client.js) | 存档 | v1 动态插件源码（`cordis_define` / `cordis_run` 形式），保留供临时挂载参考 |

Host ↔ Client 之间只走同源 HTTP JSON（webServer 路由 + fetch），不依赖 Typert RPC，也不注册任何公开远程服务。

## 安装到你的 DSH（永久，推荐）

本包是标准 DSH bundle（`dsh.bundle` + `dsh.client` web）。两种来源任选：

```powershell
# A. 从 GitHub 安装（有 git 时支持 update）
dsh plugin --profile web add github:DrFaithinT/dsh-api-usage-monitor

# B. 从本地目录安装（link 引用，改动即时生效）
dsh plugin --profile web add C:\path\to\dsh-api-usage-monitor
```

`dsh plugin` 会把包写进 profile 的 `dependencies`（底层转发给 pnpm）。然后**在 profile 配置里登记 bundle**：编辑 `$DSH_HOME/profiles/web/package.json`，把 `"dsh-api-usage-monitor"` 加进 `dsh.profile.bundles` 数组：

```jsonc
{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        // ... 你现有的包 ...
        "dsh-api-usage-monitor"   // ← 新增
      ]
    }
  }
}
```

最后重启 DSH 生效（bundle 补丁与客户端 bundle 都在启动时装配）：

```powershell
# 停掉当前 dsh web 进程，再运行：
dsh web
```

验证：`dsh --profile web --dump-config | findstr api-usage-monitor` 能看到插入的行；打开 **设置 → API 用量** 即正常展示。卸载：`dsh plugin --profile web remove dsh-api-usage-monitor` 并移除 bundles 条目。

### 动态挂载（v1 存档，临时场景）

`host.js` 与 `client.js` 是 v1 动态版源码（纯 JavaScript 函数体，返回一个 Cordis 插件）：把它们全文作为 `cordis_define` 的 `code.host` / `code.client` 提交，`cordis_run` 激活后打开 **设置 → API 用量** 即可。动态插件是进程本地的运行时扩展，**重启 DSH 后消失**，需要重新 define + run；实时数据同样从激活时刻起统计。

## 在对话中 @ 提及本插件（@话题）

DSH 的动态插件支持用 `@<pluginId>` 在对话中直接点名插件。当消息里出现 `@apiusg-1`（你实际分配到的 id）时，系统会注入该插件的身份、版本指针与运行状态，Agent 会按以下流程操作：

1. `cordis_inspect_self(pluginId, packageId)` 读取当前包的 Host/Client 源码与诊断；
2. `cordis_define` 以 `kind: 'existing'` 为同一插件追加一个**不可变**的新 Package（绝不覆盖旧版本）；
3. `cordis_run` 以 `update` 模式激活新版本；失败可回滚到 `currentPackageId`。

常用例句：

```
@apiusg-1 把设置页刷新间隔从 2 秒改成 5 秒
@apiusg-1 增加按天分组的用量统计
@apiusg-1 当前统计到多少 token 了？
@apiusg-1 回滚到上一个版本
```

其它维护操作（不必 @，直接说即可）：`cordis_stop` 临时停用、`cordis_run`（mode `run`）回滚/重启、`cordis_undefine` 永久移除。

> ⚠️ `apiusg-1` 是本机定义时分配到的 pluginId；你在自己环境里 define 后获得的 id 可能不同，请以实际返回为准。

## 数据说明

- **实时数据**：来自插件对 `llm/stream` 的观测，只统计插件运行期间经过的调用；重试失败的尝试记为 `ok: false` 且不计入 token 汇总。
- **历史数据**：来自持久化会话日志中的 `assistant/message` 事件（`data.usage`），覆盖插件安装前的用量；每个会话还会从 `request/header` 提取用过的 provider/model。
- **Token 字段**（与 `TokenUsage` 一致）：`inputTokens` / `outputTokens` / `cacheReadTokens` / `cacheWriteTokens` / `reasoningTokens`，各字段互不重叠。
- 所有数据仅存于插件内存，不落盘、不上传；扫描历史是显式按需操作。

## 文件结构

```
dsh-api-usage-monitor/
├── lib/index.js       # Host 半（永久版）：观测 + 聚合 + webServer 路由
├── lib/client.js      # Client 半（永久版）：__ModuleLoader__ bundle + 设置页
├── cordis.patch.yml   # bundle 补丁：插入 Loader 行
├── host.js            # v1 动态版 Host 源码（存档）
├── client.js          # v1 动态版 Client 源码（存档）
├── package.json       # dsh.bundle / dsh.client 清单 + 元数据
├── LICENSE            # MIT
└── README.md
```

## License

[MIT](./LICENSE)