agent-usage-all-in-one 0.8.1 → 0.10.0

package/CONTRIBUTING.md

@@ -6,7 +6,9 @@ accounting are release requirements rather than optional polish.
 
 ## Development
 
-Use macOS, Node.js 24+, and pnpm 10.33.3.
+Use macOS, Node.js 24+, and pnpm 10.33.3. That runtime is the product boundary
+(ADR 017); do not add Linux CI or a second install channel without superseding
+it.
 
 ```bash
 pnpm install

package/README.md

@@ -8,23 +8,36 @@
 [![npm](https://img.shields.io/npm/v/agent-usage-all-in-one.svg)](https://www.npmjs.com/package/agent-usage-all-in-one)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
+> **Local multi-agent usage center on macOS — one dashboard, no cloud, no auto-switch.**
+
 Agent Usage is a macOS-first, fully local usage center for Codex, Claude Code,
-OpenCode, Grok, dsh, and Antigravity. One command opens a dashboard for native quota windows,
+OpenCode, Grok, dsh, Antigravity, and Cursor. One command opens a dashboard for native quota windows,
 reset times, tokens, model rankings, equivalent API cost, history, and diagnostics.
 It offers advice but never switches agents automatically.
 
+## Compared
+
+Honest category axes and when to prefer Agent Usage vs provider UIs, exporters, or FinOps dashboards: [docs/comparison.md](docs/comparison.md).
+
+Sourced named competitors (ccusage, CodeBurn, Token Monitor, TokenTracker): [docs/named-competitors.md](docs/named-competitors.md).
+
+**Boundaries:** Cursor quota is experimental (no Tokens/history yet) · macOS only · multi-agent usage center for listed providers (don’t oversell “all-in-one”).
+
 ## Dashboard
 
 The dashboard has two primary tabs:
 
 - **Agent usage** preserves each provider's native five-hour, weekly, monthly,
   All models, and Fable-only quota labels and reset times.
-- **Tokens & model costs** supports 24-hour, 7-day, and 30-day ranges. It puts
-  totals first, then a GitHub-style last-year usage wall of headline-included
-  recorded Tokens, charts Provider share and the interactive daily trend, and
-  shows model rankings with visual share bars and the public API retail
-  equivalent of eligible token usage. The year wall is independent of the
-  selected 24-hour, 7-day, or 30-day window.
+- **Tokens & model costs** supports 24-hour, 7-day, and 30-day ranges. The
+  selected window, metric, and currency sit in the same sticky header as the
+  primary tabs. The summary board leads with the headline amount beside a
+  GitHub-style last-year usage wall of headline-included recorded Tokens, then
+  charts each known model separately by agent and billing domain on the share
+  pie and the interactive daily trend, and shows model
+  rankings with visual share bars and the public API retail equivalent of
+  eligible token usage. The year wall is independent of the selected 24-hour,
+  7-day, or 30-day window.
 - **Settings** provides a centered two-column modal organized into five dedicated
   categories: Connections, Custom model rates, Monitoring, Diagnostics, and
   Data & privacy.
@@ -44,11 +57,13 @@ Cached results are available immediately while discovery, provider usage, model
 pricing, and retention run as independent background modules. Each dashboard tab
 shows only its own update indicator and completed sections remain usable.
 
-Transcript scans use a persistent, path-redacted file index. Historical retail
-pricing is recalculated only when the pricing catalog version changes. SQLite
-time/provider/model indexes and retention compaction run in a worker after
-provider collection, while price backfill processes bounded pages. Settings
-includes an explicitly confirmed
+Transcript scans use a persistent, path-redacted file index. Refresh derives API
+retail equivalent only for new or changed Token observations. Historical retail
+pricing backfills remaining unpriced observations when the pricing catalog
+version changes. SQLite time/provider/model indexes and retention compaction run
+in a worker after provider collection only when those jobs have work. Price
+backfill processes bounded pages. Token and cost refresh bars follow price
+derivation, not connector collection or retention. Settings includes an explicitly confirmed
 **Hard rebuild all data** action for troubleshooting. It ignores these caches, can
 use substantial resources, and may take a long time without blocking the web UI.
 
@@ -67,7 +82,17 @@ browser closed.
 
 ## Install and run
 
-Agent Usage requires macOS and Node.js 24 or newer.
+Agent Usage requires macOS and Node.js 24 or newer. That floor is the supported
+runtime (built-in `node:sqlite`, Keychain, LaunchAgent), not a documentation
+oversight — see [ADR 017](docs/adr/017-macos-node24-npm-runtime.md) and the
+[platform roadmap](docs/platform-roadmap.md). Linux and Homebrew / DMG are not
+shipped.
+
+```bash
+npx agent-usage-all-in-one
+```
+
+Optional global install:
 
 ```bash
 npm install --global agent-usage-all-in-one
@@ -113,10 +138,15 @@ agent-usage clear --yes
 | Grok · xAI API                   | No subscription quota                                                                                                                 | Official Management API aggregation                                                       | Actual USD amounts, balance, limit, and invoice when available                         |
 | dsh · DeepSeek API               | No subscription quota                                                                                                                 | Local dsh session logs across every profile, including front ends composed on dsh         | API retail equivalent at DeepSeek published peak/off-peak rates                        |
 | Antigravity · Gemini Code Assist | Official-client 5-hour sprint window and weekly baseline limit from live language server RPC, with local session observation fallback | Local conversation SQLite databases (~/.gemini/antigravity-cli and ~/.gemini/antigravity) | API retail equivalent at published Google Gemini and third-party model rates           |
+| Cursor                           | Experimental official Agent CLI `/usage` screen: Included percent and On-Demand spend-limit window; account-wide                      | Not collected in this version                                                             | On-Demand dollars are a quota window, not a bill                                       |
 
 Every value retains its authority and observation time. Account-wide and this-Mac
 evidence remain visibly distinct.
 
+## First launch / empty state
+
+Until connectors find local client data, the dashboard shows an honest empty state — connect or use an installed agent first.
+
 ## Credentials and privacy
 
 Official-client credentials stay in their owning clients and are neither copied
@@ -128,7 +158,7 @@ All usage data remains local. JSON and CSV exports omit account identifiers,
 session IDs, cookies, OAuth tokens, and secret values by default. Raw observations
 are retained for 90 days, then transactionally compacted into UTC daily aggregates.
 Clearing local usage never deletes credentials owned by Codex, Claude Code,
-OpenCode, Grok, dsh, or Antigravity.
+OpenCode, Grok, dsh, Antigravity, or Cursor.
 
 ## Verification
 
@@ -146,6 +176,13 @@ See the [official pricing evidence](docs/research/official-pricing-sources-2026-
 [connector receipts](docs/release/connector-receipts-2026-08-28.md), and
 [open-source notices](docs/open-source.md).
 
+## Roadmap vision (not shipped)
+
+Linux, Homebrew, and DMG stay off the product until the conditions in
+[docs/platform-roadmap.md](docs/platform-roadmap.md) are met.
+
+> **VISION only — not shipped.** Menu bar / always-available glance is tracked in [issue #19](https://github.com/Blackman99/agent-usage-all-in-one/issues/19). Do not treat the mock as a current feature.
+
 ## License and community
 
 MIT — see [LICENSE](LICENSE). Also see [CONTRIBUTING.md](CONTRIBUTING.md),

package/README.zh-CN.md

@@ -8,16 +8,26 @@
 [![npm](https://img.shields.io/npm/v/agent-usage-all-in-one.svg)](https://www.npmjs.com/package/agent-usage-all-in-one)
 [![许可证：MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
+> **macOS 上的本地多 Agent 用量中心——一个仪表盘，无云端，不自动切换。**
+
 Agent Usage 是一个 macOS 优先、完全在本地运行的用量中心。一次启动即可统一查看
-Codex、Claude Code、OpenCode、Grok、dsh 与 Antigravity 的原生额度窗口、刷新时间、Token、模型排行、
+Codex、Claude Code、OpenCode、Grok、dsh、Antigravity 与 Cursor 的原生额度窗口、刷新时间、Token、模型排行、
 API 对等费用、历史与诊断。它只提供建议，不会自动切换 Agent。
 
+## 对比说明
+
+按类别对比何时更适合用 Agent Usage，而非各平台官网、导出工具或通用 FinOps 看板：[docs/comparison.md](docs/comparison.md)。
+
+具名竞品对照（ccusage、CodeBurn、Token Monitor、TokenTracker）：[docs/named-competitors.md](docs/named-competitors.md)。
+
+**边界：** Cursor 额度为实验性（尚无 Token/历史）· 仅 macOS · 对已列出的 Provider 做多 Agent 用量中心（不夸大 “all-in-one”）。
+
 ## 核心页面
 
 页面只有两个主要标签页：
 
 - **Agent 用量**：保留各平台原生的 5 小时、周、月、All models 和 Fable only 等额度标签与刷新时间。
-- **Token 与模型费用**：支持 24 小时、7 天和 30 天范围。顶部优先展示汇总信息，接着是过去一年的 GitHub 风格用量墙（只统计计入摘要的已记录 Token），随后用图表展示 Provider 占比和可交互的每日趋势，再以占比条呈现模型排行及符合条件的 Token 按公开 API 价格计算出的对等费用。用量墙与所选的 24 小时 / 7 天 / 30 天窗口相互独立。
+- **Token 与模型费用**：支持 24 小时、7 天和 30 天范围。所选窗口、指标与币种和主标签页共用同一条吸顶导航。汇总卡片左侧是金额或 Token 头条，右侧是过去一年的 GitHub 风格用量墙（只统计计入摘要的已记录 Token），随后用图表按 agent、计费域和模型分开展示占比与可交互的每日趋势，再以占比条呈现模型排行及符合条件的 Token 按公开 API 价格计算出的对等费用。用量墙与所选的 24 小时 / 7 天 / 30 天窗口相互独立。
 - **设置面板**：采用居中双栏结构，将连接管理、自定义模型费率、运行监控、系统诊断与数据隐私划分为 5 个独立分类，方便高效维护各项配置。
 
 实际账单、平台报告估算、固定订阅费和 API 对等零售价是四类互不混合的证据。
@@ -31,9 +41,9 @@ Grok Build/SuperGrok 与 xAI API 是两个独立计费域，其额度、Token
 本地 Web 服务会先启动，再在后台运行连接发现、平台用量、模型定价和保留整理四个独立模块。
 已有缓存会立即展示；每个标签页只在自己的数据区域显示更新状态，已经完成的内容始终可用。
 
-本地会话记录扫描使用跨进程持久化且不保存原始个人路径的文件索引。历史费用只在价格目录版本变化时
-重新计算，并按有限批次处理；时间、平台、模型和计费域索引及保留期整理会在平台采集完成后交给后台
-工作线程执行。设置里提供需要明确确认的
+本地会话记录扫描使用跨进程持久化且不保存原始个人路径的文件索引。刷新只为新增或定价输入已变化的
+Token 观测计算 API 对等零售价；历史费用只在价格目录版本变化时补算仍未定价的观测，并按有限批次处理。
+时间、平台、模型和计费域索引及保留期整理会在平台采集完成后交给后台工作线程，且仅在确有工作（索引尚未建立、或存在超过 90 天的原始观测）时执行。Token 与费用区域的刷新条只在价格推导实际运行时显示，不等待连接器采集或保留整理。设置里提供需要明确确认的
 **硬重算全部数据**：它会忽略缓存、消耗较多资源，并且可能等待很久，但不会阻塞页面。
 
 ## 开发调试
@@ -49,7 +59,13 @@ pnpm dev
 
 ## 安装与启动
 
-要求 macOS 和 Node.js 24 或更高版本。
+要求 macOS 和 Node.js 24 或更高版本。这是受支持的运行时（内置 `node:sqlite`、钥匙串、LaunchAgent），不是文档疏漏——见 [ADR 017](docs/adr/017-macos-node24-npm-runtime.md) 和 [平台路线图](docs/platform-roadmap.md)。尚未提供 Linux，也没有 Homebrew / DMG。
+
+```bash
+npx agent-usage-all-in-one
+```
+
+可选全局安装：
 
 ```bash
 npm install --global agent-usage-all-in-one
@@ -95,6 +111,7 @@ agent-usage clear --yes
 | Grok · xAI API                   | 没有订阅额度                                                                                  | 官方 Management API 聚合                                                     | 可用时展示实际美元金额、余额、上限与账单                       |
 | dsh · DeepSeek API               | 没有订阅额度                                                                                  | 本机 dsh 全部 profile 的会话日志，含基于 dsh 的终端前端                      | 按 DeepSeek 公布的峰谷价计算 API 对等零售价                    |
 | Antigravity · Gemini Code Assist | 通过官方 Language Server 本地 RPC 获取 5 小时冲刺窗口与周度基准额度，支持本地会话分析平滑降级 | 本地会话 SQLite 数据库（~/.gemini/antigravity-cli 与 ~/.gemini/antigravity） | 按公布的 Google Gemini 及第三方模型公开价格计算 API 对等零售价 |
+| Cursor                           | 实验性官方 Agent CLI `/usage` 屏幕：Included 百分比与 On-Demand 花费上限；账户全局            | 本版不采集                                                                   | On-Demand 美元是额度窗口，不是账单                             |
 
 每个数字都会保留来源权威等级和观测时间；账户全局与仅此 Mac 的证据始终明确区分。
 
@@ -106,7 +123,7 @@ Agent Usage 管理的凭据，存储在 macOS 钥匙串。本地页面使用一
 
 所有用量数据都留在本机。JSON/CSV 导出默认排除账户标识、会话 ID、Cookie、OAuth Token
 和密钥值。原始观测保留 90 天，之后在事务中压缩为 UTC 日汇总。清理本地用量永远不会删除
-Codex、Claude Code、OpenCode、Grok、dsh 或 Antigravity 官方客户端拥有的凭据。
+Codex、Claude Code、OpenCode、Grok、dsh、Antigravity 或 Cursor 官方客户端拥有的凭据。
 
 ## 验证
 
@@ -124,6 +141,12 @@ pnpm test:e2e
 [连接验证收据](docs/release/connector-receipts-2026-08-28.md)与
 [开源说明](docs/open-source.md)。
 
+## 路线图愿景（未交付）
+
+Linux、Homebrew 和 DMG 在满足 [docs/platform-roadmap.md](docs/platform-roadmap.md)
+中的条件之前不会进入产品。菜单栏一览见 [issue #19](https://github.com/Blackman99/agent-usage-all-in-one/issues/19)，
+仓库中的示意图只是愿景，不是现有功能。
+
 ## 许可证与社区
 
 MIT，详见 [LICENSE](LICENSE)。另请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)、