dsh-token-stats

一个 DeepSeek Harness 插件（bundle），自动记录并统计 token 用量，支持按天 / 周 / 月 汇总，可按模型、日期区间过滤。这是 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

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 拷入 profile 的 skills/，并把 @deepseek-ai/dsh-token-stats 注册进 profile 的 dsh.profile.bundles。之后 dsh --profile <name> 启动即挂载 token_report 工具。

卸载：

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

验证

# 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：

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 运行时）

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 符号链接。也可直接用：

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

模型侧（在 DSH 会话中）

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

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

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 记录文件：

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

测试后清理：

rm -f /tmp/test_usage.jsonl