DeepSeek Harness Token 用量统计插件

DeepSeek Harness（DSH）的设计理念是「一切皆插件」。在智能体开发与调试过程中，对会话中 input、output 以及 cache-read token 的统计需求很常见。dsh-token-usage 插件旨在解决这一需求，它通过读取本地会话日志，聚合 Token 用量数据，并提供 Web 侧边栏面板与 Agent 工具两种访问方式。

插件简介¶

这是一个由 joyiok 维护的 Token 用量统计插件。它的核心价值在于“权威计数”：不依赖估算，而是直接读取 DSH 的会话日志文件，对每个 (turn, step) 只计一次，并内置多帧 zstd 解码能力，无需外部依赖。

核心功能¶

该插件主要提供以下能力：

1. Web 侧边栏：在 Web 客户端底部新增 Tokens 按钮，点击可查看全部累计、今日以及每个会话的 input、output、cache-read token 详情。
2. Agent 工具：在 headless 或 Web 会话中，通过注册的 token_usage 工具获取统计数据，支持通过 scope 参数限定查询范围。
3. 权威计数：读取 $DSH_HOME/sessions/**/session.jsonl(.zstd)，利用内置解码器解析数据，确保统计口径准确。

安装与启用¶

安装插件需要将插件目录添加到 DSH 的 profile 中。请根据你的使用场景（Web 或 Headless）执行对应命令。

cd /home/joy/Documents
dsh plugin --profile web add /home/joy/Documents/token-usage-dsh-plugin
dsh plugin --profile headless add /home/joy/Documents/token-usage-dsh-plugin

安装完成后，重启 dsh web。客户端会扫描与 Typert 清单，重启后配置才会生效。你可以通过 dsh --profile web --dump-config 验证，输出中应出现 dsh-token-usage 配置段。

使用方法¶

Web 侧边栏¶

在任意活跃会话页面，左下角会出现 Tokens 图标。点击后，面板将展示以下内容：

• 汇总视图：全部累计 / 今日的输入、输出、输入+输出、缓存读取、含缓存总计以及 LLM steps。
• 会话明细表：列出各会话的标题、模型、输入/输出/缓存读取 Token 数以及最近活动时间。

Agent 工具¶

在对话中直接询问 Token 用量，Agent 会调用 token_usage 工具并返回结果。

示例：

用户：我一共用了多少 token？
Agent：调用 token_usage(scope: "all") 后回答

工具参数：

配置¶

插件支持在 profile 的 cordis.patch.yml 中进行覆盖配置。注意，这里需要覆盖整行 config。

- id: token-usage
  config:
    cacheTtlMs: 8000        # 聚合缓存毫秒数
    maxToolSessions: 20     # token_usage 工具最多返回的会话数

若需禁用插件，可在配置中添加：

- id: token-usage
  disabled: true

技术细节与说明¶

• 日志路径：插件读取 $DSH_HOME/sessions/**/session.l(.zstd)。
• 计算公式：totalTokens = inputTokens + outputTokens。含缓存的总计 totalWithCache 会额外计入 cacheReadTokens 和 cacheWriteTokens。
• 解码机制：插件内置多帧 zstd 解码。若内置解码失败且系统 PATH 中存在 zstd CLI，会自动回退调用该命令行工具。

参考资料¶

• 插件目录页
• GitHub 仓库