前言¶
在本地运行 DeepSeek Harness、Codex 或 OpenCode 时，追踪 token 消耗是控制成本的关键。通常这些数据散落在本地日志中，难以进行跨会话的汇总分析。本文介绍的工具通过读取本地日志，聚合三个来源的 token 数据，并提供可视化的看板与命令行工具，用于估算费用与监控缓存命中率。
什么是 dsh-token-usage-observer¶
这是一个 DeepSeek Harness 插件，由维护者 RyzenWang 提供，遵循 MIT 许可证。它的核心作用是收集、汇总并展示本机 DeepSeek Harness、Codex (ChatGPT) 和 OpenCode 的 token 使用情况，包括缓存命中情况与预计费用，同时不修改任何原始数据。
核心功能¶
- 数据聚合与计算：插件会聚合三个来源的 token 用量（输入、缓存命中、缓存写入、输出），并计算缓存命中率与预计费用。
- WebUI 侧边栏看板：安装后，WebUI 侧边栏会出现「Token 统计」入口。看板支持按来源、时间段、分类与分组维度筛选，提供总量分布图表（堆叠条形图）与逐会话明细列表。
- Agent 工具：提供
usage_stats工具，支持通过命令行显式调用，并返回分组统计与明细表。 - 会话名称解析：自动解析会话名称（Harness 取
session/title，Codex 取thread_name，OpenCode 取session.title），缺失时使用会话 ID。 - 费用单价配置：支持配置每百万 token 的费用单价，默认按 DeepSeek 公开价设置。
安装与启用¶
通过 dsh 插件命令安装：
dsh plugin --profile web add "github:ZhengDaoWang/dsh-token-usage-observer"
安装或更新后，需要重启 dsh web，侧边栏「Token 统计」入口与看板才会加载。
典型用法¶
安装完成后，可以在对话中直接询问：
- “统计我本机的 token 用量”
- “看看 codex 这周花了多少 token”
- “8 月 deepseek 模型的用量按天分组，并按公开价估算费用”
也可以通过工具名 usage_stats 显式调用，支持的参数包括：
* source：数据来源（all, deepseek-harness, codex, opencode）
* from / to：起止日期（YYYY-MM-DD）
* category：分类筛选（模型 ID 或 preset 子串）
* groupBy：分组维度（source, category, day, none）
* prices：单价覆盖对象
数据来源与配置¶
插件读取本地日志文件。费用单价默认值如下（每百万 token）：
* 输入：\(0.14
* 缓存命中：\)0.014
* 输出：$0.28
数据来源位置包括：
* DeepSeek Harness：~/.dsh/sessions/<encoded-cwd>/session-<uuid>/session.jsonl[.zstd]
* Codex：~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
* OpenCode：~/.local/share/opencode/opencode.db
可以通过环境变量 DSH_HOME 或 CODEX_HOME 覆盖 Harness 与 Codex 的日志根目录。插件对损坏或无法读取的文件会静默跳过。
注意事项¶
- 插件以只读方式访问本地日志，不会修改任何数据。
- 安装前建议检查源码与许可证。
总结¶
该工具通过读取本地日志，为开发者提供了一个统一的视角来监控 DeepSeek Harness、Codex 和 OpenCode 的 token 消耗。结合 WebUI 看板与 Agent 工具，可以方便地进行成本估算与用量分析。
GitHub: https://github.com/RyzenWang/dsh-token-usage-observer
