shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 数据与分析无需 API Key

智能体Token用量统计看板

用于统计智能体调用大模型（LLM）的 Token 消耗量，支持按日期和模型维度查看输入（Prompt）、输出（Completion）及总计用量，便于进行成本核算与用量监控。

person作者: user_6e944abahubcommunity
download下载资源包

Token Usage Analyzer（智能体 Token 用量统计看板）

解析 AI 智能体的 trace / 日志，生成一份自包含 HTML 仪表盘： 按天 × 模型的输入/输出/缓存用量、调用次数、对话轮数，以及 GitHub 风格的每日用量热力图。

特性

  • 多智能体开箱即用：内置 WorkBuddy 与 DSH 两个真实适配器；5 个 stub（qoder / trae / qclaw / codybuddy / minimax-code）等你补样本即可激活；通用 JSONL schema 可覆盖未列出的工具
  • 自动发现：scripts/adapters/*.js 全部自动注册，--adapter <name> 即用
  • 报表完整：统计卡、按天柱状图、模型占比环形图、明细表、7 行热力图
    • 热力图日期轴以打开页面的当天为终点（浏览器时钟），最后格永远是今天
    • 页面每 10 分钟自动重新加载（<meta http-equiv="refresh" content="600">）
  • 零 npm 依赖：仅用 Node 内置模块（fs / path / os / child_process / node:zlib）
  • path-agnostic：HTML 默认写到 skill 自己的目录，装哪就在哪
  • 三层防御：adapter 自带默认路径、路径 sentinel 校验、文件名白名单，避免误读数据

支持的智能体

| 适配器 | 数据源 | 状态 | |---|---|---| | workbuddy（默认） | ~/.workbuddy/traces/<pid>/trace_*.json | ✅ 实装 | | dsh | ~/.dsh/sessions/<ws>/<sess>/session.jsonl.zstd | ✅ 实装 | | generic | 任意 JSONL + --schema 描述字段映射 | ✅ 实装 | | qoder | Qoder IDE LLM trace | 🟡 stub（需样本激活） | | trae | Trae / Trae CN LLM trace | 🟡 stub（需样本激活） | | qclaw | qclaw trace | 🟡 stub（需样本激活） | | codybuddy | CodyBuddy trace | 🟡 stub（需样本激活） | | minimax-code | MiniMax Code trace | 🟡 stub（需样本激活） |

查看本机已安装的全部适配器：

node analyzer.js --list

用法

cd scripts
node analyzer.js [options]

参数：

| 参数 | 说明 | |---|---| | --adapter <name> | 选适配器（默认 workbuddy） | | --list | 列出所有已发现的适配器并退出 | | --dir <path> | 覆盖适配器默认路径 | | --adapter-dir <path> | 从外部目录加载额外适配器 | | --days N | 报表窗口天数（默认 30） | | --from / --to YYYY-MM-DD | 显式日期区间（替代 --days） | | --out file.html | 输出 HTML 路径（默认生成到本 skill 目录的 token-usage.html） | | --schema schema.json | 仅 generic 适配器使用，描述 JSONL 字段映射 | | --force-path | 跳过 adapter 路径 sentinel 校验 | | --no-open | 生成后不自动在浏览器打开 |

生成后自动打开：报表写好后会用系统默认浏览器自动打开（Windows start / macOS open / Linux xdg-open），加 --no-open 可禁用。

示例：

cd scripts

# 查看本机可用适配器
node analyzer.js --list

# WorkBuddy（默认），近 7 天
node analyzer.js --days 7

# DSH（DeepSeek Harness）
node analyzer.js --adapter dsh --days 7

# generic 适配器 + 自定义 schema
node analyzer.js --adapter generic --dir /var/log/agent --schema ./my-schema.json

# 指定 traces 目录 + 显式日期区间
node analyzer.js --dir /data/wb-traces --from 2026-08-01 --to 2026-08-14

# 只生成不打开（适合计划任务）
node analyzer.js --adapter dsh --days 30 --no-open

# 路径不含 sentinel 时强跳过
node analyzer.js --adapter workbuddy --dir /tmp/wb-traces --force-path

路径无关：skill 装在哪里，HTML 就生成在哪里（默认输出在本目录下）， 不依赖任何硬编码路径。

输出

生成的 HTML 完全自包含（内嵌数据与图表脚本），直接双击打开即可，无需服务器。 打开后：热力图最后格=当天；页面每 10 分钟自动重新加载以显示最新数据。

各适配器说明

workbuddy

WorkBuddy 的 trace 日志位于 ~/.workbuddy/traces/<pid>/trace_*.json， 每个文件的 spans 里 type === "generation" 的 span 在其 toolInput 字符串中内嵌了 请求 JSON（可能截断），parseToolInput 用正则扫描所有 usage 对象并配对最近的前置 model 字段，cache 取自 inputTokensDetails[].cached_tokens 之和。

dsh

DSH（DeepSeek Harness）日志位于 ~/.dsh/sessions/<workspace>/<session>/session.jsonl.zstd， 多帧 zstd 压缩 JSONL。识别 3 类事件：

  • request/header → ev.data.header.config.{provider,model} 设定当前模型
  • request/context → ev.data.{provider,model} 覆盖当前模型
  • assistant/message → ev.data.usage.{inputTokens|uncachedInputTokens, outputTokens, cacheReadTokens} 是一次 usage

要求 Node ≥ 22（用 node:zlib.zstdDecompressSync）。

generic

把任意 JSONL 日志按用户提供的 schema 映射成统一事件流。Schema 文件示例：

{
  "fileGlob":    "*.jsonl",
  "timeField":   "timestamp",
  "modelField":  "model",
  "usageField":  "usage",
  "inputTokens": "input_tokens || prompt_tokens",
  "outputTokens":"output_tokens || completion_tokens",
  "cacheTokens": "cache_read_tokens || cache_read_input_tokens"
}

路径支持点号下钻；多种字段名用 || 列出，回退到第一个非空。

stub 适配器（qoder / trae / qclaw / codybuddy / minimax-code）

已经注册到 --list，调用时抛"需样本激活"错误并打印路径候选清单。只需把 trace 样本贴给我，即可补完。

适配新智能体

每个适配器是 scripts/adapters/<name>.js，只需这一个文件，被 analyzer.js 自动发现。

Adapter 契约

// scripts/adapters/<name>.js
module.exports = {
  name:        "<id>",             // 必填，--adapter 用
  displayName: "<人类可读名>",      // 用于 --list
  defaultRoot: () => "<path>",     // 可选，不填则必须 --dir
  SENTINEL:    "<路径子串>",        // 可选，--dir 必须含此子串（除非 --force-path）
  filePattern: /<文件名正则>/,      // 可选，仅作提示
  readUsageEvents: function(root, opts) {
    // 必填：返回 [{time, model, input, output, cache}, ...]
  }
};

示例：5 分钟加一个新工具

# 1) 新建文件
$EDITOR scripts/adapters/my-agent.js

# 2) 实现 readUsageEvents(root) 返回事件数组

# 3) 验证
node analyzer.js --list                       # 应出现 my-agent
node analyzer.js --adapter my-agent --days 7  # 跑通

外部 adapter（不污染主分支）

# 把 adapter 放在任意目录
mkdir -p ~/.token-usage-adapters
cp my-agent.js ~/.token-usage-adapters/

# 加载时指定
node analyzer.js --adapter-dir ~/.token-usage-adapters --adapter my-agent

适合"先试用、不入主干"的开发流程，或第三方分发。

故障排查

| 现象 | 处理 | |---|---| | Unknown adapter: X | 拼写错，或 --adapter-dir 没指定；先跑 --list 看可用列表 | | Path not found | 默认路径不存在，用 --dir <path> 指向真实 trace 目录 | | path must contain "SENTINEL" | 路径与 adapter 不匹配；要么换 --adapter，要么 --force-path | | No token usage events found | 日志里没有 usage 数据；调整 --days / --from / --to 或检查源 | | stub 适配器抛"需样本激活" | 正常；提供一份脱敏 trace 后即可补完 | | HTML 打开了但图表是空的 | 检查浏览器控制台，模板占位符未替换时会抛错（见 report.js） | | node:zlib.zstdDecompressSync is not a function | Node < 22，DSH 适配器需要 Node ≥ 22 |

🤝 反馈：新适配器、bug 报告、改进建议 → 仓库 Issue。