CLI 参考

仓库根目录运维 CLI（cli.py，"AI Token Usage CLI"）的参考文档。它与共享脚本（scripts/shared/）读写同一个用量数据库，适合日常查询和定时维护——但其中三个命令会修改计量数据，见下方专门章节。

运行方式

所有命令都在仓库根目录以 cli.py 的子命令形式执行：

python3 cli.py <command> [options]
python3 cli.py --help
python3 cli.py <command> --help

共同行为：

• 执行任何命令前都会先初始化用量数据库（db.init_database()），因此 CLI 也可以引导全新环境。
• 数据来源：~/.open-ace/config.json 中 database 段配置的用量数据库。默认为 SQLite（~/.open-ace/ace.db）；配置 postgresql:// URL 则切换到 PostgreSQL（需要 psycopg2）。
• 应用配置读取自 ~/.open-ace/config.json（可用 OPENACE_CONFIG_DIR 覆盖目录）；其中 email 段供 report 命令使用。
• Token 数量同时以可读形式（如 1.2M）和原始数值打印。

查询命令

today — 今日用量

按工具展示当天的用量：总 token、输入/输出/缓存拆分、请求数和使用的模型。

选项	说明
--tool TOOL	按工具名过滤（如 claude、qwen）
--host HOST	按主机名过滤

python3 cli.py today
python3 cli.py today --tool claude
python3 cli.py today --host dev-machine

query — 指定日期用量

输出结构与 today 相同，日期任意指定。

参数 / 选项	必需	说明
date（位置参数）	是	YYYY-MM-DD 格式日期（非法格式会被拒绝）
--tool TOOL	否	按工具名过滤
--host HOST	否	按主机名过滤

python3 cli.py query 2026-09-01
python3 cli.py query 2026-09-01 --tool qwen

top — 最近 N 天用量排行

统计截至今天的窗口期内各工具总用量，按总 token 排序，并显示请求数。

选项	说明
--tool TOOL	只统计某个工具
--days N	窗口天数（默认 7）
--host HOST	按主机名过滤

python3 cli.py top
python3 cli.py top --days 30

summary — 全量汇总

全历史按工具汇总：跟踪天数、总 token、日均、总请求数、日均请求数和统计区间。

选项	说明
--host HOST	按主机名过滤

python3 cli.py summary

report — 邮件报告

组装 HTML 用量报告并通过 SMTP 发送。基准日为今天；本地时间 08:00 之前执行时自动改用昨天——清晨的 cron 也能拿到完整的前一天数据。

参数	说明
type（位置参数，可选）	报告类型；目前只有 email（默认）

python3 cli.py report

注意事项：

• 需要 ~/.open-ace/config.json 中的 email 段（smtp_server、smtp_port、smtp_username、smtp_password、from_email、to_email、use_tls）；缺失时命令会明确报错退出。
• 发送前会先测试 SMTP 连接；邮件主题为 AI Token Usage Report - <date>。
• 邮件中的汇总表为全历史数据；每日数据表只覆盖基准日。

config — 配置管理

动作	说明
show	打印当前配置 JSON（含路径）
init	从 config/settings.json.sample 创建 ~/.open-ace/config.json，无样例时创建内置默认值；覆盖前会交互确认
edit	用 $EDITOR（默认 nano）打开配置；配置不存在时先执行 init

python3 cli.py config show
python3 cli.py config init
python3 cli.py config edit

计量维护命令

以下三个命令会修改计费/计量数据。执行前先备份数据库，优先限定日期范围或单个 --tenant-id，且不要并发执行——aggregate-quota 有 300 秒聚合锁和幂等历史记录，但 reset-tenant-period 与 repair-consistency 是直接写入。

aggregate-quota — 重建配额与租户用量聚合

两步流水线：

1. daily_messages → quota_usage：把用户消息（role='user'）计为请求，累加通过 parent_id 链关联的助手回复的 token。sender_name 按用户名匹配用户——导入数据中无法匹配用户名的发送者不会生成记录。
2. quota_usage → tenant_usage / tenants：重置已过期的计费周期，执行数据质量检查，然后在聚合锁下汇总各租户用量并更新租户总计。已聚合过的日期范围会被识别并跳过（幂等历史）。

选项	说明
--start DATE	起始日期 YYYY-MM-DD（默认：全部数据）
--end DATE	结束日期 YYYY-MM-DD（默认：全部数据）

python3 cli.py aggregate-quota
python3 cli.py aggregate-quota --start 2026-09-01 --end 2026-09-30

使用场景：

• 导入历史消息后回填，或修复因任务失败丢失的 quota_usage 记录。
• 重跑中途失败的定时聚合（安全：聚合锁 + 幂等保护）。

风险：

• 它重建的是配额检查与账单报表所依赖的聚合：日期范围错误或 daily_messages 脏数据会直接变成计费用量。质量分数低于 90% 时仅记录警告——先排查再信任结果。
• 不带 --start/--end 时会重新处理全部数据；修复场景优先限定范围。

reset-tenant-period — 手动重置租户计费周期

重置指定租户的计费计数器并开始新周期（按租户的 billing_day 与 billing_cycle_type 重新计算 billing_cycle_start / billing_cycle_end）。

选项	必需	说明
--tenant-id ID	是	数字租户 ID（整数）

python3 cli.py reset-tenant-period --tenant-id 3

使用场景：

• 租户变更计费日或套餐，运维需要立即切换周期。
• 周期数据损坏（例如聚合用错日期），周期计数器需要干净重启。

风险：

• 这是计费边界变更：旧周期内累计的用量不再计入该周期。用量行不会被删除，但按新周期评估的配额与报表看不到旧周期消耗。执行前确认租户 ID——没有确认提示，且重置无法自动回滚。

repair-consistency — 从 tenant_usage 重算租户总计

把 tenants.total_tokens_used 和 tenants.total_requests_made 重建为对 tenant_usage 的 SUM(...)——可限定单个租户，省略 --tenant-id 时修复全部租户。

选项	必需	说明
--tenant-id ID	否	只修复指定租户；省略则修复全部

python3 cli.py repair-consistency --tenant-id 3
python3 cli.py repair-consistency

使用场景：

• consistency_violations 表记录检测到的租户总计与聚合用量不一致（violation_type、expected_value 与 actual_value、difference、状态 detected / repaired / ignored）。当表中存在 detected 记录时，本命令执行这些记录所描述的修复；修复后应更新对应行的 status/repaired_at，保持审计轨迹准确。
• 聚合任务更新了 tenant_usage 但在更新 tenants 前中断之后。

风险：

• 它无条件用 tenant_usage 覆盖租户总计：如果底层聚合本身是错的，修复会把错误固化。先用 aggregate-quota 修正数据，再执行修复。
• 它只对齐两个聚合层；不会从 quota_usage 重新推导 tenant_usage（那是 aggregate-quota 的职责）。

退出码

查询命令即使没有匹配数据也返回 0（打印 "no usage data" 提示）。维护命令失败时以非零码退出：aggregate-quota 在租户聚合出错时、reset-tenant-period 与 repair-consistency 在任何异常时，因此可以用于脚本化健康检查。