UsageMax public observability

UsageMax 将你电脑上已有的 AI 使用记录汇总为清晰的视图，展示令牌、模型构成、追踪费用、会话和活动。开源 CLI 会在本地执行范围受限的扫描，并将聚合快照上传到版本化的 UsageMax API。

**简而言之：**一次性采集器，默认保护隐私，只有你选择公开时才会公开。提示词和补全内容绝不会离开电脑。

你将获得

功能	用途
私有工作区	在一个租户范围的视图中比较电脑、提供方、模型、项目和成本中心。
公开个人资料	可选择公开个人资料、排行榜、活动、模型构成、费用估算和连续使用记录。
采集器 API	与安装实例绑定、仅写入的快照，以及不含内容的遥测数据。
usagemax CLI	适用于 bunx 的扫描器，支持归档恢复、安全诊断和可选的操作系统定时调度。
Agent 接口	范围受限的 OpenAPI、MCP、Markdown、WebMCP、A2A 和可安装技能界面。

实体 HUD/屏幕项目有意与此仓库分开。它可以使用 UsageMax 遥测数据，但使用该平台并不需要它。

连接电脑

1. 创建关联码

登录 usagemax.com/account，选择 关联电脑，为其命名，然后复制一次性命令。该代码有效期为十分钟，且只能使用一次。

2. 关联并同步

在保存使用记录的电脑或 WSL 发行版上运行命令：

bunx usagemax link UMX-XXXX-XXXX-XXXX-XXXX

# Optional explicit name; the account keeps this name for the installation.
bunx usagemax link UMX-XXXX-XXXX-XXXX-XXXX --name "Work laptop"

首次关联会执行一次完整同步。每次安装都会获得一个稳定的随机 ID，因此重新关联或重命名不会创建重复设备，只会轮换其密钥。

3. 按需汇总

bunx usagemax sync --dry-run --explain  # inspect the bounded plan
bunx usagemax sync                      # upload changed usage
bunx usagemax sync --full               # reconcile all retained history
bunx usagemax status --remote            # check the saved credential safely

CLI 更新与进度

CLI 每天最多检查两次 npm 的 latest dist-tag。运行 usagemax update，通过 Bun 或 npm 更新全局安装；使用 --check 进行只读检查。运行 usagemax update sync，无需输入 @latest， 即可将命令交给当前版本；也可以设置 USAGEMAX_AUTO_UPDATE=1，明确启用自动交接。在离线环境中，使用 --no-update-check 或设置 USAGEMAX_DISABLE_UPDATE_CHECK=1。交互式 终端会在 stderr 显示一条简短的进度信息；JSON、 静默、CI 和计划任务运行仍保持机器可读且不输出信息。

覆盖范围与准确性

UsageMax 固定使用 ccusage v20.0.24 并使用其 16 个适配器：Amp、Claude Code、Codebuff、Codex、GitHub Copilot CLI、Factory Droid、Gemini CLI、Goose、Grok Build、Hermes、Kilo Code、Kimi CLI、 OpenClaw、OpenCode、Pi 和 Qwen Code。系统也会发现以名称命名的 Pi 格式存储。

采集器可识别受支持的提供商覆盖设置、限定范围的主目录、Claude Desktop 会话、.cc-mirror、重命名的 Claude/Codex 备份文件夹，以及来自 WSL 的受支持 Windows 主目录。常规同步会检查已知位置和主目录中的直接子项；不会遍历整个磁盘。

bunx usagemax doctor                 # metadata-only coverage check
bunx usagemax doctor --deep --json   # retained-history audit
bunx usagemax sync --archives        # one-time compressed-history recovery
bunx usagemax report                 # local ccusage report
bunx usagemax status --json          # version, coverage, checkpoints, and link state
bunx usagemax update --json          # machine-readable npm release check

全盘扫描可以编目 2024 年以来保留的历史记录。可读取的文件清单并不能证明聚合解析器已处理所有文件和日期。UsageMax 会分别报告这两种状态；除非解析器明确确认其覆盖范围，否则会继续保护计数器减少和缺失行。未知模型仍标记为 unattributed；未知定价仍保持未知。

Cursor、Windsurf、Aider、Continue、Cline、Roo Code、托管 Agent、直接提供商 API 流量和企业计费系统，并非都能提供稳定的本地账本。请通过原生或 OTLP/HTTP JSON 合约接入这些数据；如果无法获取本地证据，也可以使用提供商的计费导出。

隐私与资源占用

保留在计算机上	可能上传
提示词和补全内容	汇总 Token 计数
源代码和文件内容	提供商、模型和来源名称
项目路径和工具负载	日期、成本和覆盖状态
提供商凭据和机密	不透明的 SHA-256 会话标识

CLI 是短时运行的。它会跳过未更改的清单，只解析必要的日期范围，使用本地锁防止并发，且绝不会在每次运行时下载软件包。可选的计划任务会调用同一个单次运行进程，并在失败后逐步延长重试间隔。

bun install -g usagemax
usagemax service install          # approximately every 15 minutes
usagemax service install --every 30
usagemax service status
usagemax service uninstall

计划任务为可选项。macOS 使用用户 LaunchAgent，Linux/WSL 使用用户 systemd 计时器，Windows 使用任务计划程序。不会为了运行任务而不必要地唤醒休眠或使用电池供电的计算机。

凭据与安全诊断

UsageMax 使用独立的凭据进行网站登录、一次性关联和收集器写入。收集器密钥的格式严格为 umx_ 后跟 64 个小写十六进制字符。它由服务器端生成，仅显示一次，以仅限用户访问的权限存储在本地；UsageMax 仅以 SHA-256 哈希的形式存储该密钥。

对于 高级版 · 自定义遥测收集器 密钥，请通过标准输入传递密钥。切勿将其放入命令行参数、URL、请求正文、代码仓库或日志中：

set +x
set -o pipefail
printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
  | bunx usagemax token status \
      --json \
  | jq -r '[.httpStatus, (if .ingestAuthorized then 1 else 0 end)] | @tsv'

token status 和 telemetry test 已包含在 CLI 0.3.11 中。如果全新环境仍使用较旧的 npm 标签，请运行 usagemax update token status，或在新软件包发布前，在此代码仓库中使用 node packages/cli/src/cli.js token status。

要验证经过身份验证的写入路径，请发送一个不含内容的 agent_state 事件，并将所有令牌和费用值设为零：

set +x
set -o pipefail
printf '%s' "$USAGEMAX_COLLECTOR_TOKEN" \
  | bunx usagemax telemetry test \
      --token-stdin \
      --json

这会写入一个可观测性事件，不会更改令牌或支出总额。未绑定的高级密钥会在首次成功写入时绑定到此 CLI 安装。若凭据无法写入数据，或 API 拒绝该事件，CLI 会返回非零退出代码。

数值投影刻意保持简洁：

结果	含义
200 1	已识别、处于激活状态，且获准写入数据。
200 0	已识别但遭到阻止；请检查已删减敏感信息的 JSON 状态。
409 0	安装 UUID 与密钥绑定不匹配。
401 0	格式或密钥未通过验证；服务器不会透露具体原因。

只读诊断会报告凭据类型、权限范围、激活状态、个人资料/名称、绑定状态以及最近一次成功/被拒绝的写入。它绝不会返回令牌、令牌哈希或已授权 UUID。高级密钥会立即激活，并在首次有效写入时绑定。关联的 CLI 密钥会在关联交换期间绑定。

Agent 与开发者入口

入口	URL
OpenAPI	openapi.json
Agent 能力视图	/?mode=agent
公共 MCP	server-card.json
文档 MCP	/docs-mcp
A2A 卡片	agent-card.json
Skills 索引	agent-skills/index.json
MCP Registry 元数据	server.json
Skill 源码与安装文档	skills/ · skills.sh
身份验证指南	/auth.md

公共读取接口受到限制且无需身份验证。公共 MCP 服务采用无状态、只读设计，不会暴露私有工作区数据或收集器凭据。收集器数据接收是一个独立的、需要身份验证的 API 边界。

代码仓库结构

src/             Next.js web app, public routes, docs, and UI
convex/          Convex schema, authorization, ingestion, and projections
packages/cli/    Distributable `usagemax` package
docs/            Architecture, contracts, coverage, operations, and releases
skills/          Direct-installable agent skills and source notes
server.json      MCP Registry submission metadata for the public remote server

如需了解文档结构，请从 docs/README.md 开始。该文档将面向公众的产品与集成指南，与贡献者、运营人员、发布及历史记录文档区分开来。

MCP 注册表和 skills.sh 状态

公共 MCP 服务已发布在官方注册表中，名称为 io.github.SYMBaiEX/[email protected]。 server.json 文件是该条目的版本化源元数据；其中不包含软件包或凭据声明。三个 skills/ 卡片均含有效的 name 和 description frontmatter，并已在 skills.sh 上建立索引：

npx skills add SYMBaiEX/usagemax --skill usage-observability
npx skills add SYMBaiEX/usagemax --skill enterprise-reporting
npx skills add SYMBaiEX/usagemax --skill collector-diagnostics

固定摘要的 Agent Skills 索引 是已部署的清单；原始 GitHub 文件则是安装源。此目录的自动化安全审计状态独立于本仓库，可能会随着这些文件之外的因素而变化。

开发

要求：Bun 1.4.2 和 Node.js 20 或更高版本。Web 应用还需要配置好的 Convex 开发部署。

bun install
bun run check       # lint, typecheck, tests, and production build
bun run cli:pack    # verify the publishable CLI archive

要进行本地 Web 开发，请配置一个被忽略的 .env.local，然后运行 bunx convex dev 和 bun run dev。有关贡献范围，请参阅 CONTRIBUTING.md；有关发布门槛，请参阅 docs/RELEASE.md。

开源

UsageMax 采用 MIT License 发布。第三方依赖项声明见 NOTICE.md。如需报告疑似漏洞，请通过 SECURITY.md 私下联系，不要提交公开议题。