dsh-tokstat

<p align="center">读取 DeepSeek Harness (dsh) 会话日志的实时使用量与性能 TUI 统计面板 —— Tokens / TTFT / TPS / 成本一屏看全</p>

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a> <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/dsh-plugin-ecosystem-purple.svg" alt="dsh plugin"></a> </p>




Overview

dsh-tokstat 直接读取 dsh 的会话日志（~/.dsh/sessions//session.jsonl.zstd， zstd 帧级增量解析），把散落在多个会话文件里的每一次 LLM 请求还原成可分析的 指标：输入/输出/缓存 Tokens、TTFT（首 token 时延）、TPS、耗时、重试与失败、 估算成本**。

项目提供两种形态：

• dsh 设置面板插件：在 dsh Web 设置页增加「统计」section，实时展示概览 /

模型 / 会话 / 请求，2s 轮询；

• Python TUI：独立终端仪表盘（7 个视图，o t m p s r e 切换）。

适合谁：

• 想了解自己每天在 dsh 上花了多少 token / 钱的用户；
• 想评估模型与供应商性能（TTFT、TPS 分布）的用户；
• 想排查重试、失败步骤的 agent 重度用户。

7 个视图（o t m p s r e 切换）：

指标设计参考了 cc-switch 的用量统计、new-api 与 sub-api 的数据看板，指标口径与 dsh 官方 sessionStats 投影一致（见 [指标定义](#指标定义)）。

Compatibility

• 数据格式基于 dsh 0.1.0-rc.6 的会话日志结构验证（2026-08-15），并已与

服务器端 session_projcache.json 投影交叉验证（llmMs/decodeTokens 精确相等， TTFT 误差 <10%；历史验证 <2%，个别新日志批量 chunk 近似可达 ~9%）。

• 插件形态：Node half 需要 Node ≥ 23.6（dsh 运行时 Node 26 已验证）；client

面板运行在 dsh Web 设置页；peerDependencies 声明了 @deepseek-ai/* 版本范围。

• TUI 形态：Python 3.11+；依赖 textual ≥8.0、zstandard ≥0.23、PyYAML。
• 会话日志格式由 dsh 演进决定；若升级 dsh 后发现读取异常，请到仓库反馈。

Install / Uninstall

方式一：dsh 设置面板插件（推荐）

从 Git 仓库安装到指定 profile（例如 web-dev）：

dsh plugin --profile web-dev add https://github.com/kongjianguan/dsh-tokstat.git

# 启动 dsh Web
dsh --profile web-dev --port 3199

安装后打开 http://127.0.0.1:3199/，进入 设置 → 统计 即可看到面板。 插件数据通过 /tokstat/stats 由 dsh 进程内的 Node half 提供，无需额外服务。

本地开发安装：

dsh plugin --profile web-dev add /path/to/dsh-tokstat
# 或使用仓库内辅助脚本（自动写 package.json + 建 node_modules 链接）
node scripts/link-profile.mjs --profile web-dev

卸载：

dsh plugin --profile web-dev remove @kongjianguan/dsh-tokstat

方式二：Python TUI

git clone https://github.com/kongjianguan/dsh-tokstat.git
cd dsh-tokstat
./run.sh          # 自动创建虚拟环境并安装依赖（等价于下方手动步骤）

或手动：

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python main.py

TUI 升级：

git pull
.venv/bin/pip install -r requirements.txt   # 依赖有变更时

TUI 卸载：

rm -rf dsh-tokstat        # 工具无后台进程、无系统级安装、无写出的数据文件

Quick start

dsh 设置面板插件

dsh plugin --profile web-dev add https://github.com/kongjianguan/dsh-tokstat.git
dsh --profile web-dev --port 3199
# 浏览器打开 http://127.0.0.1:3199/ → 设置 → 统计

Python TUI

./run.sh                        # 默认范围：全部
./run.sh --range today          # 只看今日
./run.sh --refresh 5            # 降低刷新频率

示例输出（总览页核心指标）：

请求数 2,431   总 Tokens 384.33M   平均 TTFT 17.3s   平均 TPS 1889.9
成功率 99.6%   缓存命中率 98.8%    估算成本 ¥84.45     平均耗时 24.1s

快捷键：

Configuration

全部通过命令行参数与一个 YAML 文件配置，无环境变量依赖：

| 参数 / 文件 | 说明 | |---|---| | --home PATH | dsh 数据目录（默认 $DSH_HOME 或 ~/.dsh） | | --refresh SECONDS | 轮询刷新间隔（默认 2） | | --range all\|today\|7d\|30d | 初始时间范围（默认 all） | | --prices PATH | 价格表 YAML 路径（默认项目内 prices.yaml） |

prices.yaml 按每百万 token 定价（¥），内置 DeepSeek v4 官方价格，可增删：

deepseek-v4-flash:
  input: 1.00      # 每百万输入 token
  output: 2.00     # 每百万输出 token
  cacheRead: 0.20  # 每百万缓存命中 token

模型 ID 自动归一化（去 owner/ 前缀、去 :后缀、@→-、去日期后缀）， deepseek-v4-flash-0731 先精确匹配、再逐级缩短匹配。未定价模型成本显示 -。

Permissions & data

• 只读：TUI 仅读取 ~/.dsh/sessions/ 下的会话日志（session.jsonl.zstd）与

~/.dsh/settings.yaml（用于定位数据目录）；插件由 dsh 进程内的 Node half 通过 sessionPersistence 读取同一份会话日志；不修改任何 dsh 数据。

• 不联网：TUI 全程离线运行；插件 client 面板只访问本机 dsh Web 的

/tokstat/stats，无遥测、无上报。

• 价格表与自定义参数仅存于本地文件；不会读取或上传你的 API 密钥。
• 插件 client 面板运行在浏览器，不直接接触文件系统；所有数据由 Node half 聚合后

通过本机 HTTP 提供。

• 会话日志包含对话内容；请勿将包含敏感对话的 ~/.dsh 目录提交到任何仓库。

Troubleshooting

Development

> 本项目的插件开发规范、设置面板扩展机制（settings.section slot）与收录条件 > 对照，见 [docs/plugin-development/](docs/plugin-development/README.md)。

结构

dsh-tokstat/
├── index.mjs              # Node half：Cordis 插件入口（/tokstat/stats）
├── src/client/index.js    # client half 源码（设置面板 React）
├── lib/client.js          # client bundle 产物
├── src/host/              # Node half 聚合（fold/aggregate/pricing TS）
├── tui/                   # Python TUI（独立可用）
│   ├── main.py
│   └── dshstats/
├── scripts/               # build-client / gate / panel-harness / cdp-shot
└── docs/

TUI 内部结构：

tui/dshstats/
  store.py      zstd 帧扫描 + 增量 tail + 事件折叠（与 dsh 官方投影同口径）
  metrics.py    聚合：summary / 时间桶 / 分组 / 百分位
  pricing.py    价格表 + 模型名归一化
  ui/           textual 界面（7 个 tab + SortableTable/Bars/StatCard 组件）

插件构建与门禁

pnpm install                     # 首次安装依赖（已提交 lockfile）
pnpm run build:host              # Node half → dist/index.mjs（esbuild 打包 TS）
pnpm run build:client            # 同步 lib/client.js
pnpm gate                        # 结构门禁 + 三方对账 + 行为测试
pnpm gate --ci                   # CI/无真实 dsh 数据时：跳过三方对账，仍跑结构门禁 + 行为测试

不安装依赖也可直接跑（脚本只用 Node 内置能力/已提交 dist）：

node scripts/build-host.mjs     # Node half → dist/index.mjs（需要 esbuild，已装则可用）
node scripts/build-client.mjs   # 同步 lib/client.js
node scripts/gate.mjs           # 结构门禁 + 三方对账 + 行为测试

改 client 后建议跑无头 Chrome 回归：

node scripts/panel-harness.mjs --port 3320
# 另开 Chrome --headless=new --remote-debugging-port=9222
node scripts/cdp-shot.mjs "http://127.0.0.1:3320/" 8000 --click "请求"

测试与验证

• 插件数据正确性：node scripts/gate.mjs 会跑 TS/Python/官方 projcache 三方对账。
• TUI 无头功能测试：App.run_test() + Pilot 模拟按键/切 tab；app.save_screenshot()

导出 SVG 核对布局。

• 数据正确性：解析结果与 ~/.dsh/storages/session_projcache.json 中官方

sessionStats 投影交叉对比（llmMs/decodeTokens 应精确相等，TTFT <10%）。

• 贡献：fork + PR 即可；改动涉及事件折叠时请在 PR 中附交叉验证结果。

License & security

• 本项目以 MIT 许可发布（见 [LICENSE](LICENSE)）。
• 安全问题请通过 GitHub issue 私下说明（避免在公开 issue 中粘贴密钥或会话内容），

或直接邮件仓库维护者。

指标定义

与 dsh 官方 sessionStats 投影一致：

已知限制

• TTFT 定义与 dsh 官方一致，含排队/思考时间，长尾明显——请以 p50/p95 为准。
• 部分会话的持久化日志只有批量 chunk（*-chunks），TTFT 为近似值（历史误差 <2%，个别新日志可达 ~9%）。
• 成本为估算，中转渠道价格请自行配置。
• TUI 形态是独立 Python 程序；仓库根同时提供 dsh 设置面板插件（Node half +

client bundle），两者共享同一套指标口径。