Workbuddy Usage Status

离线可视化 WorkBuddy 本机使用数据，以 token 消耗为主指标、credit 为本地估算，涵盖思考效率、模型分布与性价比、日期区间筛选、错误监控、用量高峰探查，生成本地使用信息看板。仅当用户**明确**想查看、生成或导出**自己 WorkBuddy 本机/本账号**的使用状态 / 使用统计 / 工作信...

clancy-feng@clancy-feng

Install

openclaw skills install @clancy-feng/workbuddy-usage-status

💖 支持这个项目

📊 已被 2000+ WorkBuddy 用户下载使用，覆盖 SkillHub & ClawHub 双平台。

如果这个工具帮到了你，欢迎：

⭐ 去 GitHub 点个 Star（这是对我最大的鼓励）
🐛 遇到问题提 Issue
📢 分享给你的 WorkBuddy 用户朋友

GitHub：https://github.com/clancy-feng/workbuddy-usage-status

界面预览

preview

技能简介

把 WorkBuddy 自己的本地使用数据，变成一份离线可查的 Dashboard。

可以看到：token 消耗、思考用时、思考效率、模型分布、错误数、credit 消耗。

✨ 核心功能特性

Token/Credit 全链路可视化：按模型、按日期、按会话统计，一眼定位"烧钱大户"
用量高峰探查：按 token 列出最高的几天，单行简介（token/credit/请求/会话/错误率）+「明细」展开当天会话表与模型 Top5，帮你快速定位消耗集中日
思考效率量化：输出 token ÷ 思考秒数（tok/s），横向对比模型性价比
错误集中监控：快速定位报错频繁的会话/模型，降低调试成本，可导出错误详情。
离线运行：Chart.js 随包附带，零外网依赖
缓存命中率面板：整体与按模型命中率趋势，看清"谁在帮你省钱"（口径 cached/input，自动判定并标注）
三级下钻（Top10 会话 →「查看」）：轮次表含时间 / 模型 / 状态 / Token / 输入 / 缓存命中 / 调用数 / 工具数 / 思考(分) / 错误；提问列默认隐藏，勾选「显示提问」展开（脱敏展示）；每轮再点「明细」= 事件摘要（生成段数与总时长、工具调用清单及耗时、错误类型与摘要）
全量 CSV 同步生成：每次运行自动产出 usage-full-<时间戳>.csv（每日汇总 / 按模型 / 会话清单 / 调用明细 / 错误六分区），表头与分区名语言自动跟随操作系统语言切换
自动归档合并：每次运行自动把逐笔数据并入本地归档（traceId 去重），WorkBuddy 30 天清理 trace 也不再丢历史——对用户完全透明，--no-archive 可关
只读无侵入：以只读模式访问 WorkBuddy 数据，不影响正在运行的程序
跨平台兼容：支持 Windows/macOS/Linux，Python 3.10+ 即可运行

WorkBuddy Usage Status —— Agent 执行指令

本文件是给 AI 的执行说明书，用户视角的安装、读图、故障排查见 README.md；指标算法口径见 DATA-GUIDE.md。

触发条件

当用户明确指向 WorkBuddy 自身、表达以下意图时调用本技能。description 已含触发词，此处强化判断与收紧边界：

想查看 / 生成 / 导出自己的 WorkBuddy 使用统计、工作量、成本看板；
关心 token 消耗、模型分布与性价比、思考效率、错误监控、用量高峰日等任一维度在 WorkBuddy 本机 trace 中的数据；
想对账某段时间 WorkBuddy 用了多少积分（credit）。

典型触发说法（示例，非穷举）：「看看我的 WorkBuddy 用了多少 token」「生成 WorkBuddy 用量看板」「WorkBuddy 积分消耗对账」「哪个模型最划算」「哪天用量最高」。命中任一具体说法即触发；只有泛指「做个统计图表」且未指向 WorkBuddy 本机用量时不易触发。

反向触发词：用户意图指向以下任一情况时，本技能不适用，应直接告知用户而非静默跳过：

想查看 / 统计其他产品（如 Cursor、VS Code、Trae、Claude 等任意第三方系统）的用量、数据、分析；
仅泛指"导出我的数据 / 做个统计图表 / 生成看板"，未明确指向 WorkBuddy 本机用量；
想为任意数据集生成通用可视化 / 报表；本技能只读取 ~/.workbuddy 下的数据文件，不具备通用图表能力。

遇到上述情况，回复要点：本技能只读取并可视化 WorkBuddy 本机（~/.workbuddy）的使用数据，不涉及其他产品或通用数据；请确认是否要分析 WorkBuddy 自身用量，或改用对应产品的工具。

执行步骤

抽取器仅依赖 Python 标准库，运行前无需 pip 安装任何包。在技能目录下运行：

text

python3 scripts/usage_extractor.py [--out <输出目录>] [--home <数据根>] [--credit-xlsx <路径>] [--billing-token-file <路径>] [--seed <旧快照>] [--no-archive]

--out <dir>：输出目录，默认当前工作目录。
--home <dir>：指定数据根目录，默认 ~/.workbuddy；此参数仅用于迁移或测试，会改变实际读取路径，日常使用不要加。
--credit-xlsx <path>：传入从 workbuddy.cn 用量页导出的 xlsx，用服务端精确 credit 覆盖对应日期窗口；用于"查清某月精确花费/对账"。默认不主动使用，仅当用户明确要求精确 credit 时再加。
--billing-token-file <path>：Path A（opt-in，默认关闭）。用户从自己浏览器 DevTools 手动复制用量 API 的鉴权头（如 Cookie: ... 整行，或 Authorization: Bearer ...）存入本地文件后传入，skill 以该 token 调用官方用量 API（/billing/meter/get-user-request-usage）拉取逐请求精确 credit，效果同 --credit-xlsx 但无需先导出 xlsx。token 必须由用户显式提供，skill 绝不自动读取宿主 App 凭据存储；不传此参数时零网络。详见 README「精确化 credit（可选）」与 CHANGELOG.md 安全等级评估。该参数只传本地文件路径；凭证本体保存在该文件内，不会出现在命令行参数中。
--seed <path>：旧快照种子（usage-status.json 或历史 dashboard HTML）。一次性导入其每日总量进入持久覆盖层，恢复已被 WorkBuddy 30 天清理的日期（逐笔明细不可追溯）。导入后持久生效，无需重复传入。
--no-archive：禁用自动归档合并（默认开启，不建议）。

⚠️ 用户侧 token 安全提醒：该 token 文件等同于你的 WorkBuddy 会话凭证，请当作密码保管——① 不要提交到任何 Git 仓库 / 云盘 / 聊天工具；② 限制文件权限（如 chmod 600），用完即删或在 workbuddy.cn 退出登录使其失效；③ 不要分享给他人，也不要长期留存明文。skill 只在使用该参数时联网一次，且绝不自动读取宿主 App 的凭据存储。

执行后在该目录生成 5 个文件：

workbuddy-usage-status-dashboard-<时间戳>.html —— 数据内联、Chart.js 外链，双击/预览即可看，零外网依赖；文件名带生成时间戳，每次生成独立文件，不覆盖旧报告；
usage-status.json —— 原始聚合数据，供二次处理；
usage-status.js —— window.USAGE_STATUS = {...}，供 HTML 通过 <script> 直接引入，以此避开 file:// 的 fetch 跨域限制。
chart.umd.min.js —— 图表引擎，由抽取器从 skill 包复制到输出目录，需与 HTML 同目录存放。
usage-full-<时间戳>.csv —— 全量数据 CSV（每日汇总 / 按模型 / 会话清单 / 调用明细 / 错误分区），与看板同源；内置浏览器无法下载 CSV 时直接取用此文件。

⚠ 产物敏感性提醒：usage-status.json / usage-status.js / dashboard HTML / 全量 CSV 中均含会话标题与用户提问原文摘要（提问最长 300 字；看板内展示默认脱敏，数据文件内为原文截断），分享或提交到仓库前请先检查敏感性。

⚠ 30 天缓存期（重要）：WorkBuddy 现对本机 traces 只保留 30 天，本 skill 每次运行会自动把数据归档到 ~/.workbuddy/usage-archive/，之后无论 trace 是否被清理，看板始终是全量视图——但归档只在运行时发生，所以需至少每 30 天运行一次，建议设置自动任务，断档超 30 天期间的 trace 无法追溯；首次运行只能看到最近 30 天。可用 --seed <旧快照> 导入历史快照恢复更早的每日总量。

交付方式

生成完成后，在输出目录找到最新生成的 workbuddy-usage-status-dashboard-*.html，按文件名时间戳取最大者，用 present_files 打开预览交回给用户。

约束与口径

读写与网络边界：① 读——仅以只读模式读 ~/.workbuddy 下的 workbuddy.db、traces/、projects/*/*.jsonl（仅提取 <user_query> 提问摘要供下钻显示），不修改 WorkBuddy 自身数据、不上传任何数据、不读取任何 API key/密码；② 写——仅在输出目录生成 5 个产物文件，并在 ~/.workbuddy/usage-archive/ 维护本地归档以对抗 30 天 trace 清理（--no-archive 可关闭）；③ 网络——默认零外部请求，仅当用户显式传入 --billing-token-file 时才向官方用量 API（workbuddy.cn）发起一次出站 HTTPS 请求，且鉴权凭据由用户提供（绝不自动读取宿主 App 凭据存储）；不传该参数时完全离线。
指标口径：token 为权威主指标，本地 trace 带精确时间戳，按请求本地时区归日，精确；credit 为会话级估算，本地无逐日时间戳，按归首日近似，非精确值，精确值只能由 --credit-xlsx 给出。各指标的具体算法、聚合口径与已知限制见 DATA-GUIDE.md，不要凭空编造数字。
数据完整性：抽取器顶部警告条已列出被跳过/解析失败的 trace 与会话，报告可能不完整属正常现象，如实告知用户即可。
产物确定：每次运行仅生成上述 5 个固定文件（dashboard HTML / usage-status.json / usage-status.js / chart.umd.min.js / usage-full-<时间戳>.csv），规模由本地 ~/.workbuddy 数据量天然限定，不存在无界输出。