核心用法
agent-usage-stats（token-stats）是一款专注于本地 Token 消耗监控的 Python 命令行工具。其核心设计遵循"每次运行都弹菜单"的交互哲学——用户启动后通过 TUI 菜单选择目标 Agent，而非预设固定目标。支持 Hermes、Claude Code、CodeX、OpenClaw、Reasonix、DeepSeek TUI 六大主流 AI 编程助手。
典型工作流：
- 默认交互模式：
token-stats弹出菜单 → 选择 Agent → 展示消耗统计 - 定向查询：
token-stats -a <agent>跳过菜单直接输出指定 Agent 数据 - 实时监控：
--watch模式持续刷新，适合长会话观察 - 后端探测：
--list-backends查看本机已安装的 Agent
技术实现：纯 Python 标准库编写，零第三方依赖，直接读取各 Agent 的本地数据文件（SQLite、JSONL 等），全程离线运行。
显著优点
1. 隐私优先：数据完全本地处理，不上传任何云端，满足敏感环境审计要求
2. 零摩擦部署：单文件/标准库依赖，Python 3.11+ 环境即装即用
3. 多 Agent 统一：打破各平台数据孤岛，一站式对比不同助手消耗
4. 灵活集成：可通过 -a <agent> 参数嵌入 Hermes SKILL.md，实现任务结束自动报表
潜在局限
- 覆盖范围有限：仅支持 6 款 CLI 工具，不含 API 直连或 Web 端使用场景
- 数据只读：无法修正或合并历史记录，各 Agent 数据格式变更可能导致解析失效
- 无趋势分析：缺少长期可视化、成本预估、团队级聚合等进阶功能
- Python 版本门槛：3.11+ 要求排除了部分旧系统环境
适合人群
- 高频使用多款 AI 编程助手的开发者，需要横向对比 Token 效率
- 企业内网环境、对数据出境敏感的技术团队
- 希望低成本快速了解消耗情况，无需复杂 BI 系统的个人用户
- Hermes 生态用户，追求工作流自动化集成
常规风险
| 风险类型 | 说明 |
|---------|------|
| 数据误读 | 各 Agent 版本升级可能改变本地存储格式，导致统计偏差 |
| 权限问题 | 需读取 `~/.<agent>/` 下的隐藏目录，多用户系统需注意文件权限 |
| 误操作风险 | `--watch` 模式长期运行可能忽略终端占用，建议配合 `timeout` 使用 |
| 供应链安全 | 源码 MIT 开源，建议审计后使用；ClawHub 分发渠道需校验签名 |
> 安全认证备注：提供的认证报告为系统自动生成的占位文本，未执行实际安全扫描，建议结合静态分析工具（如 Bandit）自行审计。