@aiwayds/dsh-llm-stats

English | 中文

DeepSeek Harness 的持久化 LLM 用量账本插件，提供 /llm-stats 斜杠命令，以 markdown 报告（GFM 表格 + emoji）呈现用量。插件把每个结束的 agent step 折叠成一行持久化记录——token 四桶（provider 报告）、模型耗时、首 token 延迟、解码吞吐、工具耗时——追加写入 $DSH_HOME/llm-stats/ 下本进程私有的分片文件。本机所有挂载了本插件的 dsh 进程共用这份整机账本，/llm-stats 在任意 surface 上按滚动日历窗口渲染：

要求 dsh >= 0.2.0-rc.2 — 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。不再支持 alpha 线。

📊 LLM stats · last 30 days (Aug 3 – Sep 1)

| ⚡ Sessions | 💬 Turns | 📡 Requests | 👣 Steps | | --- | --- | --- | --- | | 132 | 196 | 2710 | 2742 |

| 📥 In | 🔥 Cache hit | 📤 Out | 🧮 Total | | --- | --- | --- | --- | | 141M | 93% | 2.5M | 144M |

⏱ Model 13h15m · 🔧 Tools 18h35m · 🚀 TTFT 4.5s · ⚡ 69.2 tok/s

🤖 By model

| Model | 📥 In | 📤 Out | 🔥 Cache | 📡 Req | | --- | --- | --- | --- | --- | | glm-5.3-flash | 46.8M | 930K | 90% | 1053 | | deepseek-flash | 78.1M | 1.1M | 94% | 1304 | | glm-5.3 | 14.6M | 369K | 93% | 301 | | MiniMax-M3 | 186K | 15.3K | 45% | 7 | | kimi | 393K | 6.8K | 79% | 10 | | minimax/minimax-m3:free | 1.2M | 14.2K | 96% | 35 |

📈 Activity

| 📅 Date | 📊 Tokens | 📈 | | --- | --- | --- | | Aug 28 | 168K | ▇ | | Aug 31 | 4.6M | ▇▇▇▇▇▇▇▇▇▇▇▇▇▇ | | Sep 1 | 8M | ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇ |

dsh-tui-pi 会识别表格分隔行，把报告经 markdown 组件渲染成框线表格；其他 surface（如 headless）显示原始 markdown。

安装

dsh plugin add @aiwayds/dsh-llm-stats

然后重启 dsh。想让哪些 profile 的用量计入，就把插件装进哪些 profile（账本整机一份，但只有挂载了插件的进程才会记账）。

卸载

dsh plugin --profile <name> remove @aiwayds/dsh-llm-stats

宿主会自动收敛（bundles 条目移除、patch 层随包消失）。~/.dsh/llm-stats/ 的账本（baseline.jsonl、records.*.jsonl 分片、回填文件）有意保留 —— 这是用量历史，重装后继续累计。0.5.1 起插件启动时会清扫遗留的 compact.lock.stale-* 接管目录和已死进程的 .baseline.jsonl.tmp-* 暂存文件。彻底清除：先备份，再 rm -rf ~/.dsh/llm-stats。

用法

| 命令 | 含义 | | --- | --- | | /llm-stats | 帮助：用法、当前配置、账本覆盖情况 | | /llm-stats day\|week\|month\|3m\|6m\|12m | 以现在为终点的滚动日历窗口 | | /llm-stats d\|w\|m | day / week / month 的短别名 | | /llm-stats backfill | 从落盘会话日志回填历史用量 |

范围是滚动语义：week = 最近 7 个本地日历日（含今天），输出标注的实际日期区间与口语「最近七天」一致。3 个月及以上的长档，逐日条形自动折叠为周一取齐的逐周条形。

配置

- id: dsh-llm-stats
  config:
    mode: on              # off 停止记账；/llm-stats 与清理照常工作
    retentionDays: 365    # 超过该天数的记录在 compaction 时清除（最小 7）

工作原理

• 一个 step 一条记录。 折叠以 step/end 为锚点（step 生命周期的权威事件：完成、失败、取消、max-tokens 的步都恰好落一个），语义对齐上游 @deepseek-ai/dsh-session-stats projection——即 dsh web 聊天统计条背后的那份折叠。token 字段可空：没有 provider usage 的步照样计入 Steps 与 Turns，只是不计入 Requests。
• 分片 append-only 账本。 每个 dsh 进程只追加自己的 records.<boot-id>.jsonl 分片，活着的进程绝不重写共享文件——TUI + headless + bot 并发互不践踏。死进程的分片在锁保护下于 compaction 时并入 baseline.jsonl，retentionDays 的过期清理也在同一时机执行。记录是计费旁路事实而非会话真相：写入尽力而为，失败的行直接丢弃，绝不影响会话。
• 重叠安全的聚合。 聚合按 (sid, turn, step) 去重（last-wins），日志重放或（将来的）历史回填都不会重复计数。
• 不记内容。 账本里只有数字、模型 id 和会话 id——没有 prompt、没有工具名、没有结果。

回填

账本从插件启动才开始记；之前的历史跑一次：

/llm-stats backfill

它会扫描 $DSH_HOME/sessions/（全部项目），解码每个落盘日志（拼接 zstd 帧的生产格式，含打包 chunk 行），用与实时记账完全相同的 step 语义折叠，然后把记录并入账本。全程遵守 retentionDays（最后写入早于窗口的会话整体跳过）；fork/subagent 的种子历史按 header seedLength 跳过，父会话的用量绝不会被重复计入；已处理的会话记入 done-ledger，重复执行很快；中途被打断也可以续跑。

已知局限

• 进程在 step/end 前崩溃的步实时记账不会记录；下一次 backfill 会从会话日志补回。
• 子代理子会话只有在其事件冒泡到 host 监听时才被实时计入；漏掉的由 backfill 兜底。

开发

npm install                          # devDependencies 解析 @deepseek-ai/* 类型闭包
node scripts/link-dsh-closure.mjs    # 把本地 @deepseek-ai/* 重新指向全局闭包（每次 install 后重跑）
npm run check                        # tsc --noEmit
npm test                             # 构建 + node --test（fold / aggregate / render / store / 插件接线）

@deepseek-ai/* 只进 peerDependencies（devDependencies 仅供本地构建）；把第二份闭包打进 dsh profile 会破坏 cordis 服务同一性。仓库以 link 挂进 live profile 时，正是上面这步 link 保证插件与 profile 解析到同一份闭包——不要跳过。

许可

MIT