WorkBuddy Monitor — 自己动手打造 AI 编程助手的用量监控系统

当 AI 编程助手吃掉你的 API 额度时，你至少应该知道钱花在了哪里。

1. 前言

如果你和我一样，每天都在用 WorkBuddy（以及其他 AI 编程助手）写代码，你一定遇到过这个问题：每个月 API 账单来了，完全不知道这些 Token 用在了哪里。

某个模型花了多少钱？哪次会话消耗最大？某个 agent 调用了多少次？—— 一片空白。

这就是我写 WorkBuddy Monitor 的原因。它不是一个”计划中的功能”，而是一个已经跑起来的、能让你把 AI 使用情况看得一清二楚的监控系统。

2. 什么是 WorkBuddy Monitor？

它是一个双数据源互补的 AI 使用监控系统：

方案 A — Trace 文件扫描：自动读取 WorkBuddy 生成的 trace JSON 文件（每 5 秒扫描一次），提取 Token 用量、模型名称、调用次数等元数据
方案 B — MITM 代理拦截：拦截 WorkBuddy 与 LLM API 之间的 HTTPS 通信，捕获完整的 prompt 和 response 内容

两个方案的数据通过时间窗口自动关联，让你既能看统计数据，也能回溯具体的对话内容。

3. 核心功能一览

3.1 实时仪表盘

打开 http://localhost:5910，一个深色主题的全功能面板映入眼帘：

概览卡片：总输入/输出/缓存 Token、Trace 数量、今日用量
趋势图表：Token 累积趋势、小时级分布、模型用量占比、代理用量分布
会话列表：支持多列组合排序，一键切换显示条目数
代理控制：内置 MITM 代理的启动/停止控制面板

3.2 四级下钻分析

从会话 → Trace → Span（调用序列）→ 捕获记录，一路点下去，没有盲区：

会话详情 — 某次编码会话的整体统计
Trace 详情 — 单次 AI 调用的完整剖析，包括 Span 调用链
Span 分析 — agent/generation/function/custom 四类 Span 分类展示，可搜索过滤
捕获记录 — 通过时间关联的完整 prompt 和 response 内容

3.3 MITM 代理：白盒拦截，零入侵

这是我最自豪的部分。用纯 Python（asyncio + cryptography）实现了一个 HTTPS MITM 代理：

自动生成自签名 CA 证书
对每个目标主机动态生成 TLS 证书
只拦截 api.deepseek.com、api.minimaxi.com 等 LLM API，其他请求透明转发
支持 SSE 流式响应解析，能拼合 stream 中的 delta content
内置智能修复：自动修正 MiMo 模型的图片请求格式问题

不依赖 mitmproxy，不修改任何应用代码，真正做到 双击即用、零配置运行。

3.4 四种部署方式

方式	适合场景
独立 exe	双击运行，零依赖，谁都能用
Python 源码	跨平台，适合开发者二次开发
Docker	一键部署到服务器
Docker Compose	生产级容器编排

4. 技术栈一览

技术	用途
Python 3.9+、asyncio	主开发语言 + 异步 I/O 核心
Flask 3.x	Web 框架（REST API + 页面渲染）
SQLite3	本地持久化数据库
cryptography >=41.0	CA 证书生成 + TLS 证书签名
Chart.js 4.4.1	前端图表可视化
PyInstaller	打包为独立 Windows exe
Docker / Compose	容器化部署

5. 项目架构

WorkBuddy (AI助手)
  ├─ traces/*.json (Token用量元数据)
  └─ HTTPS 请求 → MITM Proxy (5911端口)
                    └─ 拦截 DeepSeek/MiniMax 等 API
                       └─ 保存完整 prompt/response

WorkBuddy Monitor
  ├─ TraceWatcher (5秒轮询) → SQLite
  ├─ MITM Proxy (asyncio)  → SQLite
  └─ Flask Web (5910端口)
       ├─ REST API
       └─ 深色主题面板 (Chart.js)

6. 开发中的挑战与取舍

6.1 双数据源设计

为什么不用单一方案？因为 trace 文件只有元数据（Token 数、模型名），没有具体的对话内容。MITM 代理能捕获对话内容，但需要用户手动配置。两个方案互补，让用户按需选择——Trace 监控零配置开箱即用，需要看具体内容时再开启代理。

6.2 自建 CA vs mitmproxy

用成熟的 mitmproxy 不是更简单吗？是的，但依赖一个 50MB+ 的外部工具不符合”零配置”的理念。用 cryptography 库自建 CA，整个核心逻辑不到 200 行代码，生成证书、签名、TLS 握手全搞定。

6.3 SSE 流式解析

LLM 的响应大多是流式的 Server-Sent Events。代理层不能简单等完整响应，必须一边转发一边拼合 chunk。我实现了一个状态机式的解析器，能正确处理换行、JSON 碎片、多个 data 事件——这在调试时是最容易出 bug 的地方。

6.4 时间关联匹配

Trace 文件和代理捕获的数据没有共同的 ID。解决方案：用时间窗口匹配——以 trace 的时间戳为中心，前后各取 10 秒缓冲，查找在该窗口内的捕获记录。实测效果不错，误匹配率很低。

从项目的 artifacts/dist/web/ 目录获取 wb-monitor-web.exe，双击运行，打开 http://localhost:5910 即可。

pip install -r config/requirements.txt
python run.py

四种部署方式覆盖了从零门槛到生产集群的全场景，可按需选择：

方式	适用场景	难度	依赖
① 独立 exe	其他 Windows 设备（无需环境）	⭐	无
② Python 源码	有 Python 环境的任何设备	⭐⭐	Python 3.9+
③ Docker	服务器 / Linux / macOS / Windows	⭐⭐	Docker
④ Docker Compose	需要集群管理的设备	⭐⭐⭐	Docker Compose

7. 如何开始使用

7.1 方式一：独立 exe（Windows，最推荐）

无需安装 Python，一个 exe 直接运行。

在本机运行 scripts/build_exe.bat 打包（或直接使用已编译的 exe），完成后得到：

artifacts/dist/web/wb-monitor-web.exe — 完整面板（~15MB），包含 MITM 代理功能
artifacts/dist/proxy/wb-monitor-proxy.exe — 仅 MITM 代理（可选）

部署到其他 Windows 设备：将 exe 复制到目标设备，双击运行，浏览器访问 http://127.0.0.1:5910 即可。目标设备需要有 WorkBuddy 的 trace 文件（位于 ~/.workbuddy/traces/）才能看到数据。

命令行选项：

wb-monitor-web.exe                       # 默认启动面板
wb-monitor-web.exe --proxy               # 同时启动 MITM 代理
wb-monitor-web.exe --port 8080           # 自定义端口
wb-monitor-web.exe --no-browser          # 不自动打开浏览器
wb-monitor-web.exe --help                # 查看全部选项

7.2 方式二：Python 源码（跨平台）

任何安装了 Python 3.9+ 的设备均可使用。

安装依赖并启动：

cd wb_monitor
pip install -r config/requirements.txt
python run.py

可选：安装为系统命令，全局可用：

pip install .
wb-monitor

配合 MITM 代理启动：python run.py --proxy，然后在应用中将 HTTPS 代理设为 http://127.0.0.1:5911，首次使用需将 ~/.workbuddy-monitor/proxy-ca/ca.crt 安装为受信任根证书。

7.3 方式三：Docker（推荐服务器）

一键部署到任何支持 Docker 的设备。

docker build -t wb-monitor -f docker/Dockerfile .
docker run -d \
  --name wb-monitor \
  -p 5910:5910 \
  -v ~/.workbuddy/traces:/root/.workbuddy/traces:ro \
  -v wb-monitor-data:/root/.workbuddy-monitor \
  wb-monitor

~/.workbuddy/traces 只读挂载 trace 数据，wb-monitor-data 卷持久化 SQLite 数据库。

7.4 方式四：Docker Compose（推荐生产）

export TRACES_DIR=/path/to/your/traces
docker compose -f docker/docker-compose.yml up -d

如需对外暴露 MITM 代理端口，取消 docker-compose.yml 中 5911:5911 的注释。

部署检查清单

目标设备能访问 WorkBuddy trace 文件（~/.workbuddy/traces/）
端口 5910（Web 面板）未被占用
如需 MITM 代理，端口 5911 也需可用
如需 MITM 代理，需安装 CA 证书到系统证书库

项目目录结构

wb_monitor/
  run.py              - 统一入口（推荐使用）
  monitor.py          - Web 面板主程序（~3000行）
  llm_proxy.py        - MITM 代理模块（~800行）
  setup.py            - pip install 安装配置
  config/             - 配置文件
  docker/             - Docker 部署
  scripts/            - 启动/打包脚本
  docs/               - 部署文档
  artifacts/          - 生成物与缓存

8. 最后

WorkBuddy Monitor 不仅是一个工具，也是我对”如何监控 AI 使用”这个问题的完整解答。它涵盖了文件监控、网络代理、数据持久化、可视化面板、跨平台部署等完整技术栈——全部用一个 Python 项目实现。

如果你也在用 WorkBuddy 或其他 AI 编程助手，并且想知道自己的 API 额度花在了哪里，不妨试试它。

开源地址：wb_monitor 📂 在线预览 wb_monitor.zip —— 查看项目完整目录结构。

透明，是高效使用 AI 的第一步。