代码平台为 GitHub 仓库:AI Usage。开发、Issue、PR、同步和发布均以该仓库为准。
个人使用的 AI coding usage 观测工具,用来汇总多台设备、多 OS 用户、多 AI coding agent 的用量事实、采集健康状态和可验证的额度窗口状态。
当前项目已经从 Widget-first 原型重设为个人 HTTP 汇聚数据产品,并开始进入跨端客户端分层阶段。生产入口已经切到 Cloudflare Worker + D1,VPN2 旧后端不再承载 AI Usage 读写链路。
- Device push pipeline:每台设备在自己的账户上下文运行本机 Python pusher,读取本机 Codex / Claude /
ccusage结构化用量并主动 push。 - Usage Ledger:本机只上传去敏后的小时用量事实,不上传
.codex/.claude原始日志、prompt、response、tool output 或原始路径;服务端负责去重、入账和聚合。 - Canonical store:生产 canonical store 是 Cloudflare D1(SQLite-compatible serverless SQL)。#74 起服务端没有本地 SQLite;采集端唯一的本地库是 outbox 缓冲(
collector_store.py)。 - Client scope:产品只支持 macOS 菜单栏 popover 和 iPhone 端;网页看板已随 #199 整体废弃。CLI report 只读派生快照。
- Client direction(2026-09-27 决定):Apple Watch 不急,Android / Windows 方向搁置,不是当前工作目标。
- Optional limits source:quota/reset 只作为可插拔 limits 能力;没有可信来源时不展示为强结论。
- 模型周额度校准:每日 cron 按官方额度自动拟合系数(epic #180),菜单栏显示「≈x.x%」。
- 后续开发遵守 TDD:先写失败测试,再实现最小代码。
- 任务真值在 GitHub Issue,不在本文件维护第二份进度表。
用户可见客户端的目标目录:
clients/
ios/ # iPhone App + iOS Widget 目标落点
android/ # Android App + Android Widget 目标落点
macos/ # macOS 菜单栏 / 轻量桌面入口目标落点
windows/ # Windows 托盘 / 轻量桌面入口目标落点
packages/
client-contracts/ # 跨端展示数据合同
design-tokens/ # 跨端视觉 token 和状态语义
迁移期保留现有实现路径:
- iOS Swift Package / Xcode 工程暂时仍在
mobile/ios和mobile/ios-xcode。 - legacy macOS Widget 暂时仍在
widget/macos和widget/macos-xcode,只作历史兼容。
不要为了“目录好看”直接移动现有 iOS 文件;迁移必须单独开任务包,先补构建或路由验证。
目标 daily source:
| Source ID | 机器 | OS 用户 | 执行方式 |
|---|---|---|---|
mac-local |
Mac 终端 | 当前 macOS 用户 | 本机采集后 HTTP push |
linux-server-1 |
Linux 服务器 | 该服务器上的目标 OS 用户 | 本机采集后 HTTP push |
linux-server-2 |
Linux 服务器 | 该服务器上的目标 OS 用户 | 本机采集后 HTTP push |
windows-desktop |
Windows 台式机 | 当前 Windows 用户 | 本机采集后 HTTP push |
limits/quota source 仍是后续可插拔能力,见 docs/subscription-usage-source.md。
硬规则:
- 每个 OS 用户只在自己的账户上下文运行本机采集;
ccusage只作为日级对账和历史兜底,不应阻断 Codex / Claude Usage Ledger 明细上报。 wang不读取/home/ubuntu。- 不暴露 SSH 给汇聚端抓取 usage。
- 汇聚端不主动登录远端机器。
- 各终端不上传
.claude、.codex原始日志目录,只上传设计过的结构化 usage payload。 - Mac 不同步或解析远程
.claude、.codex原始日志目录。 config/sources.local.json、data/latest.json、data/usage.sqlite不提交。
三个 OS 同一条命令(uv 单文件自举、自管 Python 版本):
# 安装/升级到指定版本(发版即打 tag,tag 与 COLLECTOR_VERSION 同名,如 v0.3.0;
# tag 随发版才存在,可先用分支名或 commit 验证通道)
uv tool install "ai-usage-widget @ git+https://github.com/Moshuiwang/aiusage@<tag>"
# 没有 uv 时先装它(Linux/Mac;Windows 用 powershell 版安装脚本)
curl -LsSf https://astral.sh/uv/install.sh | sh- 版本单源:包版本动态取自
version_contract.COLLECTOR_VERSION(pyproject 不手写版本,tests/test_version_single_source.py守着)。发版流程 = 升COLLECTOR_VERSION→ 打同名 tag。 - 定时单元:
deploy_units.py渲染三个 OS 的定时任务(systemd / launchd / Windows Task Scheduler)。Windows 侧用render_windows_task_xml()生成任务 XML(UTF-16 写盘),schtasks /Create /TN <任务名> /XML <文件>导入;任务名见CollectorUnitSpec.windows_task_name。 - 体检:
ai-usage-widget doctor认得两种部署形态——版本化 release 目录,以及 uv tool install / pip 的已安装包(版本可追溯)。 - 自动升级暂不开启(#106/D7 决策):升级 = 重跑一条
uv tool install ...@新tag。
云端会话是临时容器,会话结束日志即被回收,所以在会话内由 Stop hook 增量推送(并由 SessionEnd hook 补推尾段)。你需要做两件事:
- 在云端环境设置里添加两个环境变量(值只填在那里,不进仓库/聊天):
AI_USAGE_INGEST_TOKEN(ingest Bearer token)、AI_USAGE_INGEST_URL(完整 ingest 地址,含/ingest)。 可选:AI_USAGE_CLOUD_PUSH_INTERVAL_MINUTES(节流分钟数,默认 15;0 = 不节流,每次 Stop 都推)、AI_USAGE_CLOUD_TIMEZONE(默认Asia/Shanghai)。 - 把下面这段粘进云端环境的 setup script(安装本包并把 Stop 与 SessionEnd hook 合并进
~/.claude/settings.json,可重复执行):
# 仓库已 checkout 在环境里时:
bash scripts/install_cloud_push.sh
# 其他仓库的会话(无 checkout):脚本直接从公开仓库 git+https://github.com/Moshuiwang/aiusage 安装,
# 默认 main,可用 AI_USAGE_PACKAGE_REF 指定 tag/分支;不需要任何 GitHub token。
# 需要自定义来源时设 AI_USAGE_PACKAGE_SPEC(优先级最高)。把脚本内容粘进 setup script 或
# curl 取自 raw 地址均可;容器需能 git 访问 github.com(codeload.github.com 被拦不影响 git 安装)。账户归属(#208):hook 会显式读取容器内 ~/.claude.json 的 oauthAccount.accountUuid 算账户指纹,
与本机同一 Claude 账户得到相同 ID;文件缺失或无该字段时降级为不上报账户观察,不猜。
行为:每个云端会话(容器)独立 source_id=claude-cloud-<云端会话号>(优先取 CLAUDE_CODE_REMOTE_SESSION_ID,缺失才用 stdin 的 session_id,hook 与手动运行因此同一 source),machine/os_user 固定为 claude-cloud;
默认 15 分钟节流(#213:Worker 每次 ingest 都会重建当天全部来源的汇总,每次推送约写 150-350 行 D1,逐轮推送会逼近 Cloudflare Free 每日 10 万行写入):距上次成功推送不足间隔的 Stop 直接跳过,可用环境变量覆盖。SessionEnd hook 执行 cloud-push --final,绕过节流补推一次尾段。回看窗口按上次成功时间收缩(最多 6 小时);缺 token 或 URL 时静默退出;
hook 永远返回 0,不阻断会话。手动入口:ai-usage-widget cloud-push(无 stdin 也能用,会话号取自环境变量)。
缺口:若会话被直接回收(未正常结束、SessionEnd 未触发),最后不足 15 分钟的用量可能丢失。
验证(唯一入口,会按改动面自动裁剪:不动 cloudflare/ 就不跑 Worker 测试):
scripts/verify.sh # 按改动面裁剪
scripts/verify.sh --full # 强制全量
scripts/verify.sh --explain-scope # 只看裁剪判定,不跑测试重新生成服务端合同 golden(value_golden / provider_slots_golden / api_contract_golden
/ macOS owner fixture)——只在 Worker 输出确实要变时才跑,跑完必须逐条复核 git diff:
npm run cf:golden:gen本地起服务端(Worker + 本地 D1,与生产同款实现):
scripts/dev_worker.sh --seed # 应用 migrations + 灌示例数据 + 起服务需要 Node >= 22。完全离线可用(首次 npm ci 之后)。
详见 docs/architecture/local-worker-development.md。
Python 服务端(
cli server及整条读模型路径)已按 #67 决策于 #74 删除, 服务端唯一实现是 Cloudflare Worker + D1。采集端仍是 Python,照常开发。
只跑 Python 测试:
PYTHONPATH=src python3 -m unittest discover -s tests -vlegacy 的
cli collect(本地采集写latest.json/ 本地 SQLite)已随 #74 删除; 采集主线是DevicePusher push -> /ingest。
HTTP push 终端侧命令:
PYTHONPATH=src python3 -m ai_usage_widget.cli push \
--config config/sources.local.json \
--ledger-mode incremental \
--ledger-lookback-hours 48 \
--lock-file /tmp/ai-usage-pusher.lock官方额度上报(给了 --config 才走本地 outbox:断网时观测先落盘、恢复后补推;不给就是直推):
PYTHONPATH=src python3 -m ai_usage_widget.cli push-limits \
--limits-config config/limits.local.json \
--url https://aiusage.chunbai.com/ingest-limits \
--config config/sources.local.json本地 outbox 的运维入口(关闭 outbox 回退直推前必须先排空,不允许静默丢弃):
PYTHONPATH=src python3 -m ai_usage_widget.cli outbox-status --config config/sources.local.json
PYTHONPATH=src python3 -m ai_usage_widget.cli outbox-export --config config/sources.local.json --dest /tmp/outbox-export.json
PYTHONPATH=src python3 -m ai_usage_widget.cli outbox-drain --config config/sources.local.json --export-to /tmp/outbox-export.json --yesoutbox-drain 会先导出再清空,且必须显式加 --yes;没有无条件清空的入口。
当前 macOS 本机生产上报由 LaunchAgent com.chunbai.aiusage.pusher 每 300 秒触发一次,实际运行 /usr/bin/python3 -m ai_usage_widget.cli push。它把最近窗口内有用量的 Codex / Claude 小时桶上报到 https://aiusage.chunbai.com/ingest,服务端按同一来源、账号、agent 和小时窗口 upsert;重复上报不会累加成假用量。
生产健康检查走 verify-cloud health(下方)或
curl -H "Authorization: Bearer <token>" https://aiusage.chunbai.com/api/health。
云端数据只读核对(无图形界面的环境用它自行判定数值对不对):
# 离线重放:无网络、无凭据,回放已落盘的读模型响应
PYTHONPATH=src python3 -m ai_usage_widget.cli verify-cloud summary \
--fixture-dir tests/fixtures/verify_cloud/healthy
# 在线只读:凭据只从环境变量读,只发只读请求
export AI_USAGE_READ_TOKEN=...
PYTHONPATH=src python3 -m ai_usage_widget.cli verify-cloud limits \
--base-url https://aiusage.chunbai.com --period today四个只读子命令:summary(周期用量关键口径)、limits(额度窗口逐条标注
official / confidence / status)、health(各来源最后上报时间、新鲜度、覆盖范围、
准确性)、parity(比对 /api/summary 与 /api/mobile/summary 的口径)。
加 --json 输出机器可判定结构。
退出码有语义,可直接进 CI:0 核对通过、3 数据异常(额度降级 / 来源掉线 /
用量归属不完整)、4 两端口径不一致、5 取数失败。
它证明的是数据正确,不证明用户看得到:Mac Popover / iPhone / Watch 的 界面验收不能用它替代。
离线 fixture 采集 official limits(只打印,不落任何本地库——PM-2,云端 D1 是唯一正本):
PYTHONPATH=src python3 -m ai_usage_widget.cli collect-limits \
--provider-fixture tests/fixtures/limits_runtime_fixture.json使用本地 limits config 采集 official limits:
PYTHONPATH=src python3 -m ai_usage_widget.cli collect-limits \
--limits-config config/limits.local.json只检查 limits config 并输出脱敏 provider plan:
PYTHONPATH=src python3 -m ai_usage_widget.cli collect-limits \
--limits-config config/limits.local.json \
--check-config真实 smoke 前做本机 readiness 诊断,不读取 auth 内容:
PYTHONPATH=src python3 -m ai_usage_widget.cli collect-limits \
--limits-config config/limits.local.json \
--doctorconfig/limits.local.json 支持同一 provider 的多个账号实例。为每个实例设置稳定的 source_id,云端 D1 会用它区分账号,避免两个 Claude 账号互相覆盖。Claude CLI provider 会先解析 /usage 文本;如果当前 Claude Code 只返回订阅说明,会回退读取同一配置目录下的 active_limits.json 当前额度 cache;如果 cache 也不存在,会执行一个极短 probe 来解析 session limit reset 文本,此时只生成 session window,不推断 weekly window。第二个 Claude Code 配置目录可以通过脱敏的 env map 表达,例如:
{
"provider": "claude",
"source_id": "claude-w",
"cli": true,
"env": {
"CLAUDE_CONFIG_DIR": "/Users/<user>/.claudew"
}
}env 只放运行环境变量,不放 token、secret、password 或 API key;--check-config / --doctor 只输出 env key,不输出 value。
显式指定 Codex auth 文件采集 WHAM usage:
PYTHONPATH=src python3 -m ai_usage_widget.cli collect-limits \
--provider codex \
--codex-auth-file /path/to/codex/auth.json显式指定 Codex app-server RPC 采集 rate limits:
PYTHONPATH=src python3 -m ai_usage_widget.cli collect-limits \
--provider codex \
--codex-rpc \
--codex-rpc-sock /path/to/codex-app-server.sock显式指定 Claude auth 文件和 Usage API URL 采集 OAuth usage:
PYTHONPATH=src python3 -m ai_usage_widget.cli collect-limits \
--provider claude \
--claude-auth-file /path/to/claude/auth.json \
--claude-usage-url https://example.invalid/claude/usage显式指定 Claude CLI /usage 采集 usage:
PYTHONPATH=src python3 -m ai_usage_widget.cli collect-limits \
--provider claude \
--claude-cli
sync-widget与collect --sync-widget已于 #72 移除。它们把latest.json同步进 macOS WidgetKit extension 容器,而 macOS Widget 已非产品目标(见docs/status.md)。 历史资料在docs/archive/legacy/widget-macos.md。
Legacy macOS SwiftUI 预览:
cd widget/macos
swift run ai-usage-widget-previewLegacy macOS Swift 测试:
cd widget/macos
swift testLegacy macOS WidgetKit App 构建:
cd widget/macos-xcode
xcodegen generate
xcodebuild -project AIUsageWidget.xcodeproj \
-scheme AIUsageWidgetApp \
-configuration Debug \
-destination 'platform=macOS' \
build- AGENTS.md:每次会话自动读取的最小硬规则和文档路由。
- project-map.md:项目地图、文档索引、客户端当前/目标目录映射。
- status.md:当前阶段、有效决策和下一步。
- architecture/architecture.md:当前真实架构、模块 owner 和禁止事项。
- architecture/database.md:当前 Cloudflare D1 / 本地 SQLite 边界和表结构索引。
- architecture/interfaces.md:当前 HTTP / summary / mobile 接口索引。
- product-brief.md:产品定位、能力域、阶段边界和关键技术决策。
- archive/INDEX.md:历史设计稿和 review 记录索引。
- operations-python-server.md:已删除的 Python Ingest 服务端历史运维文档(#74 归档)。
- schedulers.md:各平台终端定时任务配置文档。
- subscription-usage-source.md:limits/quota 数据源方向。
latest.json 是展示层读取入口。当前原型字段是:
{
"generated_at": "2026-05-24T12:30:00+08:00",
"timezone": "Asia/Shanghai",
"items": [],
"source_status": []
}latest.json 现在只属于 legacy/local compatibility。当前 Web、iPhone、Watch 和 macOS 菜单栏优先读取 Cloudflare API 或派生摘要,不再把本地快照文件作为生产事实源。
设备授权、Linux / Mac 签名发布与升级入口见 设备授权与签名升级。新机器通过配对码申请自己的设备凭据,无需 SSH 写共享 token;Mac App 已包含本机采集与推送。正式更新已固定发布公钥和公开清单地址;生产设备接入需 Ops 配置独立设备管理员凭据。