前言¶
在 DSH（DeepSeek Harness）里跑 Claude Code、OpenCode、Cursor 或 DSH 自身时，各工具往往各自记日志，token 与费用分散在不同目录。想回答「这周一共用了多少、缓存命中率如何、哪条会话最贵」通常要手动翻多个应用或脚本汇总，且源日志删掉后历史很难对齐。
下面介绍社区插件 dsh-agent-token-stats（维护者 skyzhao1223，分类：客户端）：它把本机多路 AI 工具的对话日志扫进一份持久化台账，在 DSH web 侧边栏提供统一分析面板。DeepSeek Harness 生态采用「一切皆插件」思路；插件目录在 SkillHub 等社区站点展示，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
dsh-agent-token-stats 是面向 DSH web profile 的跨 Agent 本地 LLM token 用量看板。Host 侧做增量扫描与台账合并，Client 侧在 web GUI 侧边栏（及主槽 dashboard）渲染图表与表格；数据留在本机 ~/.agent-token-stats/。
当前 npm 包版本为 1.2.0（见仓库 package.json），许可证 MIT，要求 DSH >= 0.1.5-rc。
核心功能¶
数据源与持久化¶
插件按签名做增量扫描，将对话日志聚合到 ~/.agent-token-stats/ledger.json：按「来源 × 模型 × 日」做 ratchet 合并，重扫不会重复计数；源日志删除后台账中的历史仍保留。
README 列出的主要来源包括：Claude Code、WPS Claude、OpenCode、DSH、OpenClaw、QClaw、CodeWhale、WorkBuddy、Cursor IDE、Hermes；另备 Codex CLI、Gemini CLI、Cline/Roo、Pi 等解析器，以及对 Trae / Lingma / CodeGeeX / Comate / Ollama / AionUi / Copilot 等的探测。
指标与视图¶
- 指标：输入 / 输出 / 推理 / 缓存读 / 缓存写拆分，缓存命中率，请求次数；上报费用与估算费用分列（内置参考价表，不混算）。
- 视图：概览卡片与环比、厂商与 prompt 构成环图（悬停、点击筛选）、堆叠趋势图（悬停、点击日下钻）、活动热力图、模型明细表（排序 / 搜索 / 日 sparkline / 合计行）、周期对比、Agent 对比、会话浏览器、来源状态与 schema 漂移提示。
- 导出：周报 / 月报 Markdown 下载；CSV 导出至
~/.agent-token-stats/export-*.csv。 - 体验：骨架首屏、扫描条提示当前为台账快照、「N 分钟前更新」相对时间；每 2 分钟自动刷新；冷启动优先从 Host 内存或磁盘台账毫秒级打开，后台再按来源冷却重扫。
- i18n：中文 / English 切换；部分键盘快捷键（如
/聚焦模型搜索、Esc逐级清除）与无障碍 tab 结构见 README。
可选配置¶
配置目录均为 ~/.agent-token-stats/，全部可选：
| 文件 | 用途 |
|---|---|
config.json |
预算告警，如 dailyTokens / monthlyTokens / dailyCost / monthlyCost；cost 阈值按 pricing.json 的 display 币种解读 |
pricing.json |
自定义单价规则与展示币种（display、unit、fx、rules 等，见 README「Pricing & currency」） |
quota.json |
DeepSeek / Kimi 等余额查询 API Key（亦可用环境变量 DEEPSEEK_API_KEY / MOONSHOT_API_KEY） |
价目匹配为小写子串、先命中先用；未命中规则时估算为 0，面板显示 0/—，不猜测。
架构概要¶
单 bundle 两行入口：Host（lib/index.js，注入 shell + webServer，提供 GET /agent-token-stats/{data,export,sessions,report,quota}，loopback 且校验 Origin）与 Client（lib/client.js，dsh.client web bundle，纯 React.createElement，改 UI 无需单独构建步骤）。
安装与启用¶
系统需已安装 sqlite3、jq、zstd（macOS 可用 brew install zstd）。在 DSH web profile 下执行官方安装命令：
dsh plugin --profile web add dsh-agent-token-stats # from npm
# or: dsh plugin --profile web add github:skyzhao1223/dsh-agent-token-stats
# then restart: dsh web
安装后重启 dsh web，在 web GUI 侧边栏打开 token 统计面板即可。维护升级时：改源码或拉新版本后执行 dsh plugin --profile web update dsh-agent-token-stats，再重启 dsh web。
典型用法¶
- 零配置浏览：安装并重启后，面板先展示已有台账快照，后台扫描各来源日志；在概览看总量与缓存命中，用时间范围、来源 chip、厂商与模型筛选缩小范围。
- 日级下钻：在趋势图或热力图上点击某一天，查看当日明细；会话浏览器可单独浏览会话（该页说明筛选器不适用，避免误用）。
- 费用对照：对比各模型「上报 cost」与按
pricing.json/ 内置表算的「估算 cost」；网关转售或非标模型可在pricing.json的rules里写细分pat行。 - 预算与余额：在
config.json设阈值；在quota.json或环境变量中配置 Key 后使用配额相关能力（见 Host 路由quota）。 - 导出归档：从面板下载周报 / 月报 Markdown，或导出 CSV 到配置目录。
开发自测可参考仓库内 node scripts/smoke.mjs、verify-instant-open.mjs 等脚本（README Development 一节）。
适用场景与注意¶
适合：在同一台开发机上并行使用多种 Agent IDE / CLI，希望在本机统一看 token、缓存与费用趋势，并保留删源日志后的历史台账的 DSH web 用户。
注意：
- 插件以当前 DSH 进程的用户与权限读取本机日志路径；安装前应在 GitHub 核对源码与 MIT 许可证，并确认可接受其扫描范围。
- 估算费用依赖价目规则与内置参考表，与厂商账单可能不一致；上报与估算永远分列。
- Host 要求 DSH >= 0.1.5-rc；依赖
sqlite3、jq、zstd必须在 PATH 中可用。 - 社区目录页星标等元数据会变动；功能与命令以 GitHub README 为准。
结尾¶
dsh-agent-token-stats 把 Claude Code、OpenCode、Cursor、DSH 等多路本地日志收成一份 ratchet 台账，在 DSH web 侧边栏提供缓存、费用与下钻分析，适合需要跨 Agent 用量可视化的开发者。
