opencode-token-tracker 1.6.5 → 1.7.1

package/README.md

@@ -23,8 +23,18 @@ This project uses the [AI Engineering Framework (AIEF)](https://github.com/tongs
 
 If you are building AI-assisted engineering workflows, we strongly recommend adopting AIEF in your own repositories for clearer context management and more consistent agent outputs.
 
+
+## Accuracy & Limitations
+
+- **Costs are estimates**, computed locally from your token logs and the built-in (or user-configured) pricing table. They may differ from your provider's official invoice — for example, when promotional credits, discounts, or enterprise pricing structures apply.
+- **Budgets are warnings, not enforcement.** This plugin does not block API calls, throttle requests, or interrupt active sessions. It is designed purely as an observability and tracking tool.
+- **Subscription or bundled providers** (such as GitHub Copilot, Cursor, etc.) or free local models should be configured with zero-cost overrides in your configuration file (see [Configuration](#configuration)).
+- **Pricing freshness**: The built-in pricing table is manually maintained. Please run `opencode-tokens models` to inspect which of your used models currently fall back to the default pricing, and configure overrides if necessary.
+
 ## Installation
 
+### Plugin
+
 Add to your OpenCode config file (`~/.config/opencode/opencode.json`):
 
 ```json
@@ -36,8 +46,40 @@ Add to your OpenCode config file (`~/.config/opencode/opencode.json`):
 
 Restart OpenCode and the plugin will be automatically installed.
 
+This installs the package for OpenCode's plugin runtime. It does not add the
+`opencode-tokens` CLI command to your shell `PATH`.
+
+### CLI
+
+If you only need to run the CLI occasionally, use it through npm without a
+persistent install:
+
+```bash
+npx -y --package opencode-token-tracker opencode-tokens today
+```
+
+Equivalent `npm exec` form:
+
+```bash
+npm exec --yes --package opencode-token-tracker -- opencode-tokens today
+```
+
+If you want `opencode-tokens` to be available as a normal shell command, install
+the package with npm's global bin linking:
+
+```bash
+npm install -g opencode-token-tracker
+opencode-tokens today
+```
+
+If `opencode-tokens: command not found` appears after configuring the plugin,
+the plugin is still installed for OpenCode, but the CLI command has not been
+installed into your shell `PATH`. Use one of the CLI options above.
+
 ## Usage
 
+For an end-to-end setup and verification path, see [walkthrough.md](./walkthrough.md).
+
 ### Toast Notifications
 
 Once installed, you'll see Toast notifications after each AI response:
@@ -228,6 +270,9 @@ Config changes are automatically backed up to `token-tracker.json.bak`.
 # Check budget status
 opencode-tokens budget
 
+# Diagnose plugin config, logs, and pricing fallbacks
+opencode-tokens doctor
+
 # Show built-in pricing table
 opencode-tokens pricing
 
@@ -237,8 +282,12 @@ opencode-tokens models
 # Show current config
 opencode-tokens config
 
-# Generate example config based on your usage
+# Print clean example JSON to stdout without writing a file
 opencode-tokens config init
+
+# Write example config to ~/.config/opencode/token-tracker.json
+# Existing config is backed up to token-tracker.json.bak
+opencode-tokens config generate
 ```
 
 Example `models` output:
@@ -255,6 +304,12 @@ This helps you understand:
 - Whether pricing is from built-in table, your config, or default fallback
 - What to add to your config file
 
+`config init` is safe for piping because stdout contains only valid JSON and no file is written. `config generate` is the file-writing path: stdout stays empty, guides and status messages go to stderr, the parent directory is created when needed, and an existing config is backed up before overwrite. Both commands inspect local logs and pre-fill likely zero-cost providers such as GitHub Copilot, Cursor, and Ollama.
+
+`doctor` is a read-only setup check. It reports whether the OpenCode plugin
+entry is present, whether the tracker config and token log exist, the latest log
+record, default-priced models, and the next command to run.
+
 ## Log Files
 
 Token usage is logged to:
@@ -359,29 +414,34 @@ All prices are in **USD per 1 million tokens**:
 
 | Scenario | Config |
 |----------|--------|
-| Subscription service (GitHub Copilot, Cursor) | `{ "input": 0, "output": 0 }` |
-| Free/local model | `{ "input": 0, "output": 0 }` |
+| Subscription service (GitHub Copilot, Cursor) | Provider override: `{ "input": 0, "output": 0 }` |
+| Free/local provider (Ollama, LM Studio, localhost) | Provider override: `{ "input": 0, "output": 0 }` |
+| Free/local model under a paid provider | Model override: `{ "input": 0, "output": 0 }` |
 | Custom API with known pricing | Look up provider's pricing page |
 
 ### Pricing Override
 
 Pricing is resolved in this order (first match wins):
 
-1. **Provider-level** - Override all models for a provider
-2. **Provider-specific model config** - Custom pricing for the same model under different providers
-3. **User model config** - Generic custom model pricing in config file
-4. **Built-in pricing** - Default pricing table
-5. **Fallback** - $1/M input, $4/M output
+1. **Provider-level override** - Override all models for a provider
+2. **Exact user model config** - Custom pricing for a specific model or provider-specific model entry
+3. **Built-in exact match** - Exact key in the built-in pricing table
+4. **Built-in partial match** - Longest matching built-in key for variant model names
+5. **User model partial match** - Longest matching user config key
+6. **Fallback** - $1/M input, $4/M output
+
+Exact user config is intentionally checked before built-ins, while broad partial user keys are checked after built-ins so a generic key like `"claude"` does not accidentally override a precise built-in model price.
 
 #### Example: Free providers
 
-If you're using GitHub Copilot or other subscription-based services, set their cost to $0:
+If you're using GitHub Copilot, Ollama, LM Studio, or other subscription/local providers, set their provider cost to $0:
 
 ```json
 {
   "providers": {
     "github-copilot": { "input": 0, "output": 0 },
-    "cursor": { "input": 0, "output": 0 }
+    "cursor": { "input": 0, "output": 0 },
+    "ollama": { "input": 0, "output": 0 }
   }
 }
 ```
@@ -437,12 +497,15 @@ npm install
 # Build
 npm run build
 
-# Link for local testing
-npm link
-cd ~/.config/opencode
-npm link opencode-token-tracker
+# Unit and CLI tests
+npm test
+
+# Real local OpenCode CLI dogfood
+node scripts/real-opencode-cli-smoke.mjs --use-temporary-link --model deepseek/deepseek-chat
 ```
 
+The dogfood script is repo-only and is not published as an npm command. It verifies the real local `opencode run` path, including OpenCode's cache package directory, and restores any temporary package links after the run.
+
 ## License
 
 MIT © [tongsh6](https://github.com/tongsh6)

package/README.zh-CN.md

@@ -23,8 +23,18 @@
 
 如果你在构建 AI-assisted engineering 工作流，推荐在你的仓库中采用 AIEF，以获得更清晰的上下文管理与更稳定的 agent 输出。
 
+
+## 准确性与限制
+
+- **成本均为估算值**，由本地 Token 日志及内置（或用户配置）的定价表计算得出。这可能与您的 Provider 官方账单存在差异 —— 例如，当您使用促销额度、企业折扣或特定定价优惠时。
+- **预算提醒仅为警告，非强制阻断**。本插件不会拦截 API 调用、节流请求或中断您的会话。其设计初衷纯粹是为了可观测性与用量追踪。
+- **订阅制或打包服务商**（如 GitHub Copilot、Cursor 等）或免费的本地模型，应在您的配置文件中将其价格覆写为 0（参见 [配置说明](#配置说明)）。
+- **定价数据时效性**：内置的定价表为手动维护。请运行 `opencode-tokens models` 来检查您当前使用的哪些模型退化（fallback）到了默认定价，并在需要时手动配置覆写。
+
 ## 安装
 
+### 插件
+
 在 OpenCode 配置文件 `~/.config/opencode/opencode.json` 中添加插件：
 
 ```json
@@ -36,8 +46,39 @@
 
 重启 OpenCode 后会自动安装插件。
 
+这一步只会让 OpenCode 的插件运行时安装并加载该包，不会把
+`opencode-tokens` CLI 命令加入你的 shell `PATH`。
+
+### CLI
+
+如果只是偶尔查看统计，可以不做持久安装，直接通过 npm 运行：
+
+```bash
+npx -y --package opencode-token-tracker opencode-tokens today
+```
+
+等价的 `npm exec` 写法：
+
+```bash
+npm exec --yes --package opencode-token-tracker -- opencode-tokens today
+```
+
+如果希望 `opencode-tokens` 成为普通 shell 命令，需要让 npm 建立全局
+bin 链接：
+
+```bash
+npm install -g opencode-token-tracker
+opencode-tokens today
+```
+
+如果你已经在 OpenCode 配置里添加了插件，但执行 `opencode-tokens today`
+提示 `opencode-tokens: command not found`，说明插件已供 OpenCode 加载，
+但 CLI 命令还没有安装到 shell `PATH`。请使用上面的任一 CLI 运行方式。
+
 ## 使用
 
+端到端安装、验证与 dogfood 路径见 [walkthrough.md](./walkthrough.md)。
+
 ### Toast 提示
 
 安装后，每次 AI 响应会看到类似提示：
@@ -152,12 +193,90 @@ opencode-tokens --by daily
   gpt-5.2               86.9K     $0.0000      18
 ```
 
+`--by` 可选：
+- `model`：按模型分组
+- `agent`：按 agent 分组
+- `provider`：按 provider 分组
+- `daily`：按天分组
+- `session`：按 session ID 分组
+- `all`：显示全部分组
+
+### 趋势图
+
+查看每日 token、成本或消息数趋势：
+
+```bash
+# 30 天成本趋势（默认）
+opencode-tokens trend
+
+# 7 天 token 趋势
+opencode-tokens trend --days 7 --metric tokens
+
+# 更紧凑的图表
+opencode-tokens trend --width 40
+```
+
+可选参数：
+- `--days N`：统计天数，默认 30
+- `--metric`：`cost`、`tokens` 或 `messages`，默认 `cost`
+- `--width W`：图表宽度，默认 60
+
+### 数据导出
+
+导出 JSONL 聚合后的用量数据：
+
+```bash
+# 导出全部数据为 CSV
+opencode-tokens export
+
+# 导出本月数据为 JSON
+opencode-tokens export --format json --period month
+
+# 写入文件
+opencode-tokens export --format csv --output usage.csv
+```
+
+可选参数：
+- `--format`：`csv` 或 `json`，默认 `csv`
+- `--period`：`today`、`week`、`month`、`all`，默认 `all`
+- `--output FILE`：写入文件，而不是 stdout
+
+### 配置管理
+
+可直接通过 CLI 管理预算与 Toast 配置：
+
+```bash
+# 查看当前配置
+opencode-tokens config
+
+# 设置每日预算为 $10
+opencode-tokens config set budget.daily 10
+
+# 关闭 Toast
+opencode-tokens config set toast.enabled false
+
+# 查看某个值
+opencode-tokens config get budget.warnAt
+
+# 恢复默认
+opencode-tokens config unset budget.daily
+```
+
+可设置字段：
+- `budget.daily`、`budget.weekly`、`budget.monthly`、`budget.warnAt`
+- `toast.enabled`、`toast.duration`、`toast.showOnIdle`
+
+配置变更会自动备份到 `token-tracker.json.bak`。
+
 ### 定价与配置命令
 
 ```bash
 # 查看预算状态
 opencode-tokens budget
 
+# 诊断插件配置、日志与默认定价回退
+opencode-tokens doctor
+
 # 查看内置定价表
 opencode-tokens pricing
 
@@ -167,8 +286,12 @@ opencode-tokens models
 # 查看当前配置
 opencode-tokens config
 
-# 基于当前使用情况生成示例配置
+# 输出干净 JSON 到 stdout，不写文件
 opencode-tokens config init
+
+# 写入 ~/.config/opencode/token-tracker.json
+# 已有配置会备份到 token-tracker.json.bak
+opencode-tokens config generate
 ```
 
 `models` 示例输出：
@@ -186,6 +309,11 @@ opencode-tokens config init
 - 定价来源是内置表、用户配置还是默认回退
 - 需要在配置文件中补充哪些模型定价
 
+`config init` 适合管道重定向，因为 stdout 只包含合法 JSON，且不会写文件。`config generate` 是写文件路径：stdout 保持为空，说明和状态信息输出到 stderr；父目录不存在时会自动创建，覆盖已有配置前会先备份。两个命令都会读取本地日志，并为 GitHub Copilot、Cursor、Ollama 这类疑似零成本 provider 预填覆盖配置。
+
+`doctor` 是只读诊断命令，会检查 OpenCode 插件入口、tracker 配置、token log、
+最新记录、默认定价回退模型，并给出下一步应该运行的命令。
+
 ## 日志文件
 
 token 记录保存在：
@@ -276,8 +404,9 @@ token 记录保存在：
 
 | 场景 | 配置 |
 | --- | --- |
-| 订阅制服务（GitHub Copilot、Cursor） | `{ "input": 0, "output": 0 }` |
-| 免费/本地模型 | `{ "input": 0, "output": 0 }` |
+| 订阅制服务（GitHub Copilot、Cursor） | Provider 覆盖：`{ "input": 0, "output": 0 }` |
+| 免费/本地 provider（Ollama、LM Studio、localhost） | Provider 覆盖：`{ "input": 0, "output": 0 }` |
+| 付费 provider 下的免费/本地模型 | Model 覆盖：`{ "input": 0, "output": 0 }` |
 | 自定义 API（已知定价） | 查看 provider 官方定价页 |
 
 ### 定价优先级
@@ -285,20 +414,24 @@ token 记录保存在：
 定价解析顺序（命中即止）：
 
 1. **Provider 覆盖** — 为某个 provider 的所有模型统一设置
-2. **按 provider 的 model 配置** — 同一模型在不同 provider 下使用不同定价
-3. **用户 model 配置** — 为特定模型自定义通用定价
-4. **内置定价** — 默认定价表
-5. **默认回退** — $1/M input，$4/M output
+2. **用户 model 精确匹配** — 为特定模型或 provider-specific model entry 自定义定价
+3. **内置定价精确匹配** — 命中内置定价表中的精确 key
+4. **内置定价部分匹配** — 对变体模型名使用最长的内置 key 匹配
+5. **用户 model 部分匹配** — 使用最长的用户配置 key 匹配
+6. **默认回退** — $1/M input，$4/M output
+
+精确用户配置会优先于内置定价；但宽泛的用户部分匹配会排在内置匹配之后，避免 `"claude"` 这类泛 key 意外覆盖精确的内置模型价格。
 
 #### 示例：免费 provider
 
-使用 GitHub Copilot 等订阅制服务时，将成本设为 $0：
+使用 GitHub Copilot、Ollama、LM Studio 等订阅制或本地 provider 时，将 provider 成本设为 $0：
 
 ```json
 {
   "providers": {
     "github-copilot": { "input": 0, "output": 0 },
-    "cursor": { "input": 0, "output": 0 }
+    "cursor": { "input": 0, "output": 0 },
+    "ollama": { "input": 0, "output": 0 }
   }
 }
 ```
@@ -368,12 +501,15 @@ npm install
 # 构建
 npm run build
 
-# 本地联调
-npm link
-cd ~/.config/opencode
-npm link opencode-token-tracker
+# 单元与 CLI 测试
+npm test
+
+# 真实本机 OpenCode CLI dogfood
+node scripts/real-opencode-cli-smoke.mjs --use-temporary-link --model deepseek/deepseek-chat
 ```
 
+dogfood 脚本只作为仓库内开发工具，不作为 npm 包命令发布。它验证真实本机 `opencode run` 路径，包括 OpenCode 的 cache package 目录；运行结束后会恢复临时 package link。
+
 ## License
 
 MIT © [tongsh6](https://github.com/tongsh6)