WorkBuddy 用量看板 + 桌面悬浮球
把 WorkBuddy 的消耗账本摆到眼前：Web 看板看趋势与分布，桌面悬浮球看当下。
它解决什么问题
WorkBuddy 官方账单只保留近 30 天、且看不到每次对话的花费明细。本 skill 直接解析本机
~/.workbuddy/projects/*/*.jsonl（WorkBuddy 自己逐轮写下的完整调用记录），还原出：
- 每天花了多少积分、多少 Token、缓存命中率
- 哪个模型最烧钱、哪个项目最耗
- 每一次对话、每一轮提问、每一次 LLM 调用的花费，可逐级下钻
- 此刻有几个对话正在跑、当前这轮已经花了多少（悬浮球实时显示）
全部本地计算，不联网、不上传、不需要 API Key。
前置条件
| 项目 | 要求 |
|---|---|
| WorkBuddy | 已安装并使用过（有 ~/.workbuddy/projects/*/*.jsonl） |
| Python | ≥ 3.8（看板零第三方依赖，标准库即可） |
| 看板 | 全平台可用（macOS / Linux / Windows） |
| 悬浮球 | 仅 macOS（依赖 Cocoa；非 macOS 自动跳过，不影响看板） |
安装（AI 执行）
一条命令完成全部部署——自动探测本机路径、安装 GUI 依赖、注册开机自启：
python3 scripts/install.py
脚本会依次完成：环境自检 → 写入本机路径配置 → 准备悬浮球依赖（独立 venv，不污染系统 Python）→ 生成并加载 launchd 常驻服务。
常用参数：
python3 scripts/install.py --check # 只自检，不改动任何东西
python3 scripts/install.py --no-gui # 只要看板，不要悬浮球
python3 scripts/install.py --port 8802 # 换端口（默认 8801）
python3 scripts/install.py --no-launchd # 不注册开机自启，只生成配置
> 悬浮球依赖 pyobjc（约 30–60MB），首次安装需 1–3 分钟，脚本会自动下载。
> 若你在受限环境执行导致 launchctl load 被拒，脚本不视为失败——配置已生成，
> 提示用户在自己的「终端 App」里执行 launchctl load ~/Library/LaunchAgents/com.user.wb-usage.plist 即可。
使用
安装成功后访问 http://127.0.0.1:8801，数据已在安装时自动完成首次全量采集。
悬浮球（macOS，桌面常驻）：
| 操作 | 行为 |
|---|---|
| 单击 | 展开面板：正在执行的对话、当前轮次的积分/Token/耗时 |
| 双击 | 浏览器打开完整看板 |
| 拖动 | 移到任意位置（位置自动记忆） |
| 右键 | 菜单：打开看板 / 退出 |
球上的数字是当前活跃对话数，绿点=看板服务正常，红点=服务未响应。
数据口径（重要）
这些规则来自对 WorkBuddy 记录格式的实测，改动会导致数字错误：
- 轮次 =
conversationRequestId，一轮提问可能触发多次 LLM 调用，需求和而非取最大值（否则低估约 3.2 倍） - 缓存命中 =
prompt_cache_hit_tokens（缺省回退prompt_tokens_details.cached_tokens） - 用户提问 =
<user_query>标签内的内容（其余 86% 是系统注入，须过滤） - 日期归属 = 轮次首次调用的本地时区日期（非 UTC）
隐私
- 所有数据停留在本机 SQLite（
scripts/wb_usage/data/wb_usage_dw.db），无任何外发 - 看板展示层默认脱敏：提问仅显示前 40 字，邮箱/手机号/绝对路径/长串密钥自动打码
- 需要看完整原文时，点右上角「显示原文」开关（仅本地生效）
- 服务只监听
127.0.0.1，局域网内其他机器访问不到
卸载
launchctl unload ~/Library/LaunchAgents/com.user.wb-usage.plist
launchctl unload ~/Library/LaunchAgents/com.user.wb-hover.plist
/bin/rm -f ~/Library/LaunchAgents/com.user.wb-usage.plist ~/Library/LaunchAgents/com.user.wb-hover.plist
/bin/rm -rf ~/.workbuddy/wb-usage-venv # 悬浮球虚拟环境
# 数据库在 scripts/wb_usage/data/wb_usage_dw.db，可自行决定是否保留
故障排查
| 现象 | 处理 |
|---|---|
| 页面打不开 | tail -f /tmp/wb-usage.log；确认 launchctl list \| grep wb-usage 有输出 |
| 悬浮球没出现 | tail -f /tmp/wb-hover.err.log；确认 pyobjc 装好：~/.workbuddy/wb-usage-venv/bin/python3 -c "import AppKit" |
| 数字为 0 | 跑 python3 scripts/install.py --check 确认数据源目录有 jsonl |
| 端口被占 | 换端口重装：python3 scripts/install.py --port 8802 |
| 改了代码不生效 | launchctl kickstart -k gui/$(id -u)/com.user.wb-usage |
文件结构
scripts/
install.py 一键安装（探测路径/装依赖/注册常驻）
b_hover.py macOS 悬浮球（原生 Cocoa NSPanel，真圆形置顶）
wb_usage/
wb_api.py 接口服务：静态 UI + JSON API + 1s 变更监听 + 30s 看门狗
wb_collect.py 增量采集（游标断点续采 + 覆盖/截断检测 + 幂等）
wb_dw.py SQLite VIEW 实时聚合层（ODS → 明细/汇总视图）
wb_common.py 公共口径（提问提取 / 字段兼容 / 时间换算 / 脱敏）
dashboard.html 前端 UI（Chart.js 本地副本，无需联网 CDN）
架构细节见 references/架构说明.md。
