@deepseek-ai/dsh-token-stats

Readme

# dsh-token-stats

一个 **DeepSeek Harness 插件**（bundle），自动记录并统计 token 用量，支持按天 / 周 / 月
汇总，可按模型、日期区间过滤。这是 [`claude-token-stats`](../claude-token-stats)（Claude
Code / Codex 版）在 DeepSeek Harness 上的对应实现。

---

## 解决什么问题

DeepSeek Harness 的 `dsh-token-meter` 提供实时 token 计量，但没有跨会话的聚合报表。
用户想知道「本月用了多少 token」「哪个模型最费 token」时，需要手动翻日志或自行统计。

本插件从根上解决：监听 session 事件，在每次 `assistant/message` 带 provider usage 时
自动写入 `~/.dsh/token_usage.jsonl`，并提供 `token_report` 工具让模型查询聚合报表。

## 工作机制

```
assistant/message (带 usage)
      │
      ▼
token-stats 插件: 监听 session/event
      │  写入 {timestamp, sessionId, usage}
      ▼
~/.dsh/token_usage.jsonl
      │
      ▼
token_report 工具: 模型调用 → 聚合 → 文本表格
```

- **监听**：`session/event` 事件，每次 `assistant/message` 带 `usage` 字段时写入一条记录。
- **存储**：纯 JSONL 文件，每行一条记录；文件小（每会话一行），内存聚合。
- **工具**：`token_report`，模型侧 schema，返回文本表格。支持 `day`/`week`/`month`/`all`
  聚合，`model`/`since`/`until` 过滤，`local`/`utc` 时区。
- **系统提示段**：`tool:token-stats`，引导模型在用户询问 token 用量时调用 `token_report`。

## 安装

### 系统要求

| 项目 | 说明 |
|---|---|
| **操作系统** | Linux 或 macOS（Windows 未测试） |
| **DeepSeek Harness** | `dsh` CLI 与一个 profile（如 `headless` / `web`） |

### 一句话让 Agent 帮你装

把下面整段复制给你的 Agent（Claude Code / Cursor / Codex 均可）：

> 请先阅读 https://github.com/QEDQCD/dsh-token-stats 的 README.md「系统要求」，
> 确认本机满足（Linux/macOS、有 `dsh` CLI 与一个 profile 如 `headless`）。
> 满足后：克隆到任意目录，在该目录内运行 `pnpm install && pnpm build`，
> 再运行 `node scripts/install.mjs --profile headless`（profile 名按我实际用的改），
> 验证 `dsh --profile headless --dump-config | grep token-stats` 能输出。

### 构建并安装到 profile

```bash
cd dsh-token-stats
pnpm install          # 或 npm install（安装 devDeps 以构建）
pnpm build            # tsc 编译 src -> lib
node scripts/install.mjs --profile headless
```

安装脚本（幂等）把 bundle 拷入 `$DSH_HOME/profiles/<name>/node_modules/@deepseek-ai/dsh-token-stats`，
把 `SKILL.md` 装入用户级技能扫描根 `$DSH_HOME/skills/token-stats/`（目录式结构，被 dsh
skill-filesystem 扫描），并把 `@deepseek-ai/dsh-token-stats` 注册进 profile 的
`dsh.profile.bundles`。之后 `dsh --profile <name>` 启动即挂载 `token_report` 工具。

卸载：

```bash
node scripts/install.mjs --profile headless --uninstall
```

### 验证

```bash
# 1) 工具已挂载
dsh --profile headless --dump-config | grep token-stats

# 2) 跑一次会话后，检查日志文件
cat ~/.dsh/token_usage.jsonl
```

新开会话后，让模型「本月 token 用量」，应看到它调用 `token_report` 返回聚合表格。

### 从 GitHub 分发/安装（免 npm 发布）

本包是 dsh bundle（`package.json` 声明 `dsh.bundle`），`dsh plugin` 支持从 GitHub 直装，
仓库公开即可，无需发布 npm：

```bash
dsh plugin --profile headless add github:QEDQCD/dsh-token-stats
# 或指定分支/标签：github:QEDQCD/dsh-token-stats#main
```

> 将来发布到 npm 后，可改用 `dsh plugin --profile <name> add @deepseek-ai/dsh-token-stats`。
> `package.json` 已带 `keywords`/`repository`/`publishConfig.access`，便于 registry 检索与公开发布。

## 使用

### 命令行（一键查看，无需 DSH 运行时）

```bash
dsh-token-report                  # 今日 + 本月 + 全部汇总
dsh-token-report --by day         # 按天明细
dsh-token-report --by month       # 按月明细
dsh-token-report --model deepseek # 按模型过滤
dsh-token-report --since 2026-08-01
dsh-token-report --json           # 机器可读 JSON
```

安装时自动在 `~/.local/bin/` 创建 `dsh-token-report` 符号链接。也可直接用：

```bash
node scripts/token-report.mjs --by day
```

### 模型侧（在 DSH 会话中）

```text
token_report()
token_report(period: "day")
token_report(period: "month", model: "deepseek-chat")
token_report(period: "week", since: "2026-08-01")
```

预期输出（工具返回的文本表格）：

```text
Token Usage Report  ·  2026-08-17 10:30:00
Period: month  ·  Timezone: local

Period         Sessions        Input    CacheRead     Hit%       Output        Total
--------------------------------------------------------------------------------
2026-08              12      456,789      234,567    33.9%       56,789      748,145
--------------------------------------------------------------------------------
TOTAL                12      456,789      234,567    33.9%       56,789      748,145
```

## 配置

`token-stats` 插件可通过 cordis 配置调整：

| 字段 | 默认 | 含义 |
|---|---|---|
| `logPath` | `~/.dsh/token_usage.jsonl` | token 用量日志文件路径 |
| `maxRecords` | `0`（无限制） | 最大保留记录数；超出时最旧记录被驱逐（待实现） |

## 目录结构

```
dsh-token-stats/
├── package.json          # @deepseek-ai/dsh-token-stats, bundle 声明(dsh.bundle.patch)
├── cordis.patch.yml      # bundle 补丁:把 token-stats 插件插入 profile
├── src/
│   ├── index.ts          # token_report 工具 + session 事件监听 + 系统提示段
│   ├── types.ts          # 类型定义(TokenRecord, TokenReport, Config)
│   ├── storage.ts        # JSONL 读写
│   ├── report.ts         # 聚合引擎 + 文本渲染
│   └── invariant.ts      # 包级 invariant 伴生
├── SKILL.md              # token 用量统计技能
├── scripts/
│   ├── install.mjs        # 安装/卸载到指定 profile
│   └── token-report.mjs   # 命令行工具（直接查看用量，无需 DSH 运行时）
├── tsconfig.json
├── README.md
└── LICENSE
```

## 隐私与安全

- **日志不含提示词**：`token_usage.jsonl` 只含 token 计数、session id、UTC 时间戳，
  不含提示词内容或 API key。
- **本地存储**：日志文件在 `~/.dsh/` 下，不出本机。
- **仓库洁净**：仓库不含任何密钥、token、个人数据或真实日志。

## 已知限制与后续

- **模型名未记录**：当前 `TokenUsage` 类型不携带模型名，报告中无法按模型过滤。
  后续可从 `request/header` 事件提取模型名关联到记录。
- **maxRecords 未实现**：配置字段已声明，但驱逐逻辑待实现。
- **无 Codex 支持**：与 claude-token-stats 不同，本插件不读取 Codex 会话日志。
  后续可扩展为多源采集。

## 开发与测试

插件源码可独立构建和测试。确定性测试注入 fixture 记录文件：

```ts
ctx.plugin(TokenStats, { logPath: '/tmp/test_usage.jsonl' })
```

测试后清理：

```bash
rm -f /tmp/test_usage.jsonl
```