diff --git a/README.en.md b/README.en.md index bb183b7..9d68257 100644 --- a/README.en.md +++ b/README.en.md @@ -2,9 +2,9 @@ # codex-usage -**Which machine used your Codex tokens?** +**Which machine, model, project, or session used your Codex tokens?** -*同一个 Codex 账号跑在多台电脑：哪台机器用掉了 Token？* +*本地优先的 Codex 使用分析：从逐电脑归属，到模型、项目、会话与 API 等价成本。* [Live Demo](https://zjay26.github.io/codex-usage/?lang=en) · [Windows x64](https://github.com/zJay26/codex-usage/releases/latest/download/codex-usage-windows-amd64.exe) · [Linux x64](https://github.com/zJay26/codex-usage/releases/latest/download/codex-usage-linux-amd64) · English / [简体中文](README.md) @@ -23,13 +23,28 @@ Run one single-file binary on each Windows, WSL, or Linux host. It scans that machine's historical Codex JSONL and receives future usage over loopback OTel. Coverage-aware merge rules deduplicate the two sources, and the result stays in that machine's SQLite database. The Dashboard therefore answers **how much this computer used**, not how much the whole account used. -The differentiators are deliberately narrow: per-machine scope, historical JSONL + live OTel, deduplication, single-file deployment, local-first operation, and **no access to `auth.json`**. +Per-machine attribution is codex-usage's most distinctive entry point, but it is not the endpoint. It breaks the local total down by model and token category, project, Thread, Session, Agent, and local calendar day, then adds Standard API-equivalent cost, pricing coverage, and data-quality records. + +Codex's official [`/usage`](https://learn.chatgpt.com/docs/developer-commands.md?surface=cli) is useful for daily, weekly, and cumulative account token activity. codex-usage complements that account view with an explainable local attribution layer: **where these machine-local tokens came from and what drove them**. + +The analysis stays local-first: one binary, loopback-only services, local SQLite, and **no access to `auth.json` or conversation content**. + +## From totals to explainable usage analytics + +| Question | What codex-usage shows | +|---|---| +| Which machine used the tokens? | An independent ledger for each Windows, WSL, or Linux host | +| Which models and token categories drove usage? | Model plus Input, Cached, Cache Write, Output, and Reasoning composition | +| Which work drove it? | Project, Thread, Session, and main task / Subagent / Guardian / Memory attribution | +| When did it happen? | Today, 7 days, 30 days, all time, local calendar days, and single-day drill-down | +| What would it roughly cost at API rates? | Standard API-equivalent cost with explicit token pricing coverage | +| Can the number be audited? | JSONL / OTel provenance, coverage-aware deduplication, unattributed deltas, and data-quality records | ## What it counts / what it does not count | Counts | Does not count or read | |---|---| -| Tokens, models, sources, projects, Threads, Agents, and local calendar days on this machine | Usage from other machines on the account | +| Tokens, models, sources, projects, Threads, Sessions, Agents, and local calendar days on this machine | Usage from other machines on the account | | Historical session JSONL and future `turn.token_usage` OTel metrics | Account quota, subscription balance, or real bills | | Standard API text-token equivalent cost and pricing coverage | Prompts, replies, reasoning, tool output, or `auth.json` | | Dedup records, coverage gaps, and historical deltas without dates | Cloud sync, remote telemetry, or third-party analytics | @@ -63,12 +78,13 @@ On a headless Linux server, Codex Usage prints an SSH tunnel command. Run it fro | Capability | What you get | |---|---| -| Per-machine accounting | A separate `machine_id` and SQLite database on every host | +| Signature per-machine attribution | A separate `machine_id` and SQLite database on every host | | Historical + live | Scan existing JSONL first, then receive official OTel metrics | | Deduplication | Merge OTel, JSONL, and state data by explicit coverage rules instead of summing them | | Daily drill-down | Continuous daily pulse, calendar, zero-usage days, and per-day model mix | -| Useful attribution | Filter by model, source, project, Thread, main task, Subagent, Guardian, or Memory | -| Equivalent cost | Query-time estimate with visible token pricing coverage; unknown usage never looks free | +| Multi-dimensional usage analytics | Understand usage by model, token category, source, project, Thread, Session, main task, Subagent, Guardian, or Memory | +| Cost insight | Query-time Standard API-equivalent estimate with visible token pricing coverage; unknown usage never looks free | +| Auditable quality | Visible provenance, dedup records, coverage gaps, and historical deltas without dates | | Local-first | Loopback-only at `127.0.0.1`, embedded assets, and no runtime external requests | | Single binary | Windows/Linux, amd64/arm64, no CGO or external database service | | Bilingual | Dashboard and CLI support `zh-CN` / `en` through URL, button, flag, and environment | diff --git a/README.md b/README.md index db8872d..f0e2029 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ # codex-usage -**同一个 Codex 账号跑在多台电脑：哪台机器用掉了 Token？** +**同一个 Codex 账号：哪台电脑、哪个模型、哪个项目和会话用掉了 Token？** -*Which machine used your Codex tokens?* +*Local-first Codex usage analytics—from machine attribution to models, projects, sessions, and API-equivalent cost.* [在线体验](https://zjay26.github.io/codex-usage/?lang=zh-CN) · [Windows x64 下载](https://github.com/zJay26/codex-usage/releases/latest/download/codex-usage-windows-amd64.exe) · [Linux x64 下载](https://github.com/zJay26/codex-usage/releases/latest/download/codex-usage-linux-amd64) · [English](README.en.md) / 简体中文 @@ -23,13 +23,28 @@ 在每台 Windows、WSL 或 Linux 主机分别运行一个单文件程序。它扫描该机的历史 Codex JSONL，并通过 loopback OTel 接收之后的新用量；两种来源按覆盖时间合并和去重，结果只写入该机的 SQLite。Dashboard 因而回答的是**这台电脑用了多少**，不是整个账号用了多少。 -核心差异只有六点：逐电脑口径、历史 JSONL + 实时 OTel、防重复计算、单文件部署、本地优先，以及**从不读取 `auth.json`**。 +逐电脑归属是 codex-usage 最鲜明的入口，但不是终点。它把本机总量继续拆到模型与 Token 类型、项目、Thread、Session、Agent 和本地自然日，并给出 Standard API 等价成本、定价覆盖率与数据质量记录。 + +Codex 官方 [`/usage`](https://learn.chatgpt.com/docs/developer-commands.md?surface=cli) 适合查看账号级 daily / weekly / cumulative Token 活动；codex-usage 不替代官方视图，而是补上**这些本机 Token 在哪里产生、由什么构成**的可解释归属层。 + +分析全程保持本地优先：单文件部署、loopback 服务、本机 SQLite，**从不读取 `auth.json` 或对话内容**。 + +## 从总量到可解释的使用分析 + +| 你想知道 | codex-usage 给出的视图 | +|---|---| +| 哪台电脑用了 Token？ | 每台 Windows、WSL 或 Linux 主机独立统计，保留清晰机器边界 | +| 用在了什么模型与 Token 类型？ | 模型及 Input、Cached、Cache Write、Output、Reasoning 构成 | +| 哪项工作驱动了用量？ | 项目、Thread、Session，以及主任务 / Subagent / Guardian / Memory 归属 | +| 什么时候发生？ | 今天、7 日、30 日、全部历史、本地自然日与单日下钻 | +| 如果按 API 价格折算大约是多少？ | Standard API 等价成本与明确的 Token 定价覆盖率 | +| 这些数字能否被复核？ | JSONL / OTel 来源、防重覆盖区间、未归属差额与数据质量记录 | ## 它统计什么 / 不统计什么 | 统计 | 不统计 | |---|---| -| 当前电脑的 Token、模型、来源、项目、Thread、Agent 和本地自然日 | 账号在其他电脑上的用量 | +| 当前电脑的 Token、模型、来源、项目、Thread、Session、Agent 和本地自然日 | 账号在其他电脑上的用量 | | 历史 session JSONL 与未来 `turn.token_usage` OTel 指标 | 账号配额、订阅余额或真实账单 | | Standard API 文本 Token 的等价成本与定价覆盖率 | prompt、回复、reasoning、工具输出或 `auth.json` | | 去重记录、覆盖缺口和无法按日期归属的历史差额 | 云同步、远程遥测或第三方分析 | @@ -67,12 +82,13 @@ Linux 服务器没有桌面环境时，程序会打印 SSH 隧道命令。在自 | 功能 | 你得到什么 | |---|---| -| 逐电脑统计 | 每台机器生成独立 `machine_id` 和 SQLite 数据库，不把账号其他电脑混进来 | +| 标志性的逐电脑归属 | 每台机器生成独立 `machine_id` 和 SQLite 数据库，不把账号其他电脑混进来 | | 历史 + 实时 | 首次扫描已有 JSONL，之后接收官方 OTel 指标 | | 防重 | OTel、JSONL 与状态库按明确覆盖规则合并，不直接相加 | | 每日下钻 | 连续自然日脉冲带、月历、零用量日与单日模型构成 | -| 清晰归属 | 按模型、来源、项目、Thread、主任务/Subagent/Guardian/Memory 筛选 | -| 等价成本 | 查询时估算并显示 Token 定价覆盖率，未知部分不伪装成零费用 | +| 多维使用分析 | 按模型、Token 类型、来源、项目、Thread、Session、主任务/Subagent/Guardian/Memory 理解用量 | +| 成本洞察 | 查询时估算 Standard API 等价成本并显示定价覆盖率，未知部分不伪装成零费用 | +| 可审计质量 | 明示来源、防重记录、覆盖缺口和未按日期归属的历史差额 | | 本地优先 | 只监听 `127.0.0.1`，资源嵌入二进制，无运行时外部请求 | | 单文件部署 | Windows/Linux、amd64/arm64、无 CGO、无需外部数据库服务 | | 双语 | Dashboard 与 CLI 支持 `zh-CN` / `en`，URL、按钮、环境变量均可切换 | diff --git a/docs/media/social-preview.png b/docs/media/social-preview.png index 4159381..824b935 100644 Binary files a/docs/media/social-preview.png and b/docs/media/social-preview.png differ diff --git a/docs/releases/v1.0.0.md b/docs/releases/v1.0.0.md index eff602f..234a458 100644 --- a/docs/releases/v1.0.0.md +++ b/docs/releases/v1.0.0.md @@ -1,10 +1,11 @@ # codex-usage v1.0.0 -`v1.0.0` is the first stable-interface release of the local-first, per-machine accounting workflow. It adds complete Chinese/English localization and a safe interactive demo built entirely from synthetic data without changing the existing accounting or automation interfaces. +`v1.0.0` is the first stable-interface release of local-first Codex usage analytics. Per-machine attribution is its signature entry point; model, token-category, project, Thread, Session, Agent, local-day, and Standard API-equivalent-cost views turn a total into explainable local usage. This release also adds complete Chinese/English localization and a safe interactive demo built entirely from synthetic data without changing the existing accounting or automation interfaces. ## Highlights - Complete `zh-CN` / `en` Dashboard localization, including dates, numbers, ARIA labels, empty states, Toasts, filters, pricing, and data-quality labels. +- Multi-dimensional local attribution across machines, models, token categories, projects, Threads, Sessions, Agents, and calendar days, with pricing coverage and an auditable source-merging trail. - Dashboard locale precedence: `?lang=en|zh-CN`, saved header-button choice, browser locale, then Chinese fallback. - Global CLI language selection with `codex-usage --lang en install` or `CODEX_USAGE_LANG=en`; Windows UI locale and Linux locale variables are used when neither is set. - GitHub Pages Live Demo that reuses the production frontend and intercepts every `/api/v1/*` call with a session-only synthetic adapter. @@ -27,4 +28,4 @@ Release assets include Windows and Linux binaries for amd64 and arm64 plus `SHA2 --- -`v1.0.0` 是本地优先、逐电脑 Codex Token 统计工具的首个稳定接口版本。它为 Dashboard 与 CLI 增加完整中英双语，并上线完全使用合成数据的交互 Demo；统计口径、JSONL / OTel 合并、SQLite、JSON/CSV 字段和 `/api/v1/*` 均保持兼容。在线 Demo 不读取本机文件、不设 Cookie、无埋点、无外部请求，刷新后重置。 +`v1.0.0` 是本地优先 Codex 使用分析工具的首个稳定接口版本。逐电脑归属是最鲜明的入口；模型与 Token 类型、项目、Thread、Session、Agent、本地自然日和 Standard API 等价成本共同把总量变成可解释的本机使用分析。该版本同时为 Dashboard 与 CLI 增加完整中英双语，并上线完全使用合成数据的交互 Demo；统计口径、JSONL / OTel 合并、SQLite、JSON/CSV 字段和 `/api/v1/*` 均保持兼容。在线 Demo 不读取本机文件、不设 Cookie、无埋点、无外部请求，刷新后重置。 diff --git a/internal/web/static/i18n.js b/internal/web/static/i18n.js index 80a8005..13d4ab8 100644 --- a/internal/web/static/i18n.js +++ b/internal/web/static/i18n.js @@ -4,8 +4,8 @@ const STORAGE_KEY = "codex-usage-locale"; const catalogs = { "zh-CN": { - "app.title": "Codex Usage · 本机用量", - "app.description": "当前电脑的 Codex Token 用量与 Standard API 等价成本估算", + "app.title": "Codex Usage · 本地使用分析", + "app.description": "本地优先的 Codex 使用分析：逐电脑归属、模型/项目/会话明细与 Standard API 等价成本", "skip.main": "跳到主要内容", "brand.home": "返回概览", "nav.label": "主要视图", @@ -227,8 +227,8 @@ "scan.complete": "扫描完成：新增 {inserted} 个事件，忽略 {duplicates} 个重复" }, en: { - "app.title": "Codex Usage · Per-machine usage", - "app.description": "Per-machine Codex token usage and Standard API-equivalent cost estimates", + "app.title": "Codex Usage · Local usage analytics", + "app.description": "Local-first Codex usage analytics by machine, model, project, and session, with Standard API-equivalent cost", "skip.main": "Skip to main content", "brand.home": "Return to overview", "nav.label": "Primary views", diff --git a/internal/web/static/index.html b/internal/web/static/index.html index 6fe8883..8e5fb8b 100644 --- a/internal/web/static/index.html +++ b/internal/web/static/index.html @@ -4,8 +4,8 @@ - - Codex Usage · 本机用量 + + Codex Usage · 本地使用分析 @@ -15,7 +15,7 @@