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
