opencode-token-tracker 1.7.0 → 1.8.0

package/README.md

@@ -30,9 +30,14 @@ If you are building AI-assisted engineering workflows, we strongly recommend ado
 - **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.
+- **Per-model audits**: `pricing` and `models` show each built-in entry's review date. `doctor` flags used entries that are stale (more than 90 days since review) or expired (past a known validity date). A recent audit is not a guarantee that prices remain unchanged. User overrides are not assigned the unused built-in entry's audit status.
+- **DeepSeek estimates**: Flash/Pro use peak-hour USD rates; off-peak rates are 50% lower. Time-of-day and holiday selection are not automatic. Retired `deepseek-chat` / `deepseek-reasoner` retain legacy estimates marked expired. The October 2026 refresh covers DeepSeek Flash/Pro and Kimi K2.7 Code; other models retain their earlier review dates.
+- **Matching and history**: Newly audited DeepSeek/Kimi entries accept exact names and slash-prefixed names. Unverified variants such as `kimi-k2.7-code-highspeed` remain explicit fallbacks unless configured by the user. Updated prices apply to future records; stored historical costs are not recalculated.
 
 ## Installation
 
+### Plugin
+
 Add to your OpenCode config file (`~/.config/opencode/opencode.json`):
 
 ```json
@@ -44,6 +49,36 @@ 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).
@@ -54,11 +89,20 @@ Once installed, you'll see Toast notifications after each AI response:
 
 ```
 12.5K tokens
-$0.023 | Session: $0.156
+$0.023 | Session: 45.2K · $0.156
 ```
 
+> `Session:` rolls usage received by the current plugin process up to the top-level task, including its sub-agents. Parent links are restored from `sessions.jsonl` on startup and updated by session events; links learned later take effect on the next toast. Historical token totals are not replayed after a restart. Use `opencode-tokens --by session` for totals from persisted logs, or `--by raw-session` to inspect individual sessions.
+
 When budget limits are configured, you'll see warnings:
 
+```
+12.5K tokens
+$0.023 | Session: 45.2K · Daily: $4.20/$5.00 (84%)
+```
+
+When a budget is exceeded, the toast switches to an alert:
+
 ```
 ⚠️ Budget exceeded!
 Daily: $5.50/$5.00 (110%)
@@ -162,7 +206,8 @@ Breakdown options (`--by`):
 - `agent` - Group by agent (e.g., sisyphus, coder)
 - `provider` - Group by provider (e.g., anthropic, openai)
 - `daily` - Show day-by-day breakdown
-- `session` - Group by session ID
+- `session` - Group by top-level session, rolling sub-agent sessions up into their parent (labelled by the parent's title)
+- `raw-session` - Group by each session id without rollup, so sub-agent sessions stay as separate rows labelled by their own title
 - `all` - Show all breakdowns
 
 ### Trend Chart
@@ -238,6 +283,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
 
@@ -269,7 +317,11 @@ 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.
+`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
 
@@ -375,8 +427,9 @@ 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
@@ -394,13 +447,14 @@ Exact user config is intentionally checked before built-ins, while broad partial
 
 #### 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 }
   }
 }
 ```

package/README.zh-CN.md

@@ -30,9 +30,14 @@
 - **预算提醒仅为警告，非强制阻断**。本插件不会拦截 API 调用、节流请求或中断您的会话。其设计初衷纯粹是为了可观测性与用量追踪。
 - **订阅制或打包服务商**（如 GitHub Copilot、Cursor 等）或免费的本地模型，应在您的配置文件中将其价格覆写为 0（参见 [配置说明](#配置说明)）。
 - **定价数据时效性**：内置的定价表为手动维护。请运行 `opencode-tokens models` 来检查您当前使用的哪些模型退化（fallback）到了默认定价，并在需要时手动配置覆写。
+- **逐型号核验**：`pricing` 和 `models` 显示各内置条目的核验日期；`doctor` 提示已使用条目中的 stale（距核验超过 90 天）与 expired（超过已知有效期）。近期核验不保证供应商未再次调价，用户自定义价格不沿用未使用的内置条目的时效标签。
+- **DeepSeek 估算口径**：Flash/Pro 使用 USD 峰时价格，谷时价格低 50%；不自动判断时段或节假日。已停用的 `deepseek-chat` / `deepseek-reasoner` 保留历史估算值并标记 expired。本次 2026-10 局部更新仅覆盖 DeepSeek Flash/Pro 与 Kimi K2.7 Code，其他型号保留原核验日期。
+- **匹配与历史**：本次核验的 DeepSeek/Kimi 条目接受精确名及以 `/` 分隔的 provider 前缀名；`kimi-k2.7-code-highspeed` 等未核价变体继续明确回退，用户可自行覆盖。更新价格只影响后续记录，不重算已保存的历史 cost。
 
 ## 安装
 
+### 插件
+
 在 OpenCode 配置文件 `~/.config/opencode/opencode.json` 中添加插件：
 
 ```json
@@ -44,6 +49,35 @@
 
 重启 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)。
@@ -54,11 +88,20 @@
 
 ```
 12.5K tokens
-$0.023 | Session: $0.156
+$0.023 | Session: 45.2K · $0.156
 ```
 
+> `Session:` 将当前插件进程收到的主、子 agent 消耗归并到顶层任务。启动时从 `sessions.jsonl` 恢复父子关系，并通过会话事件更新；晚到的关系在下一次提示中生效。重启后不会回放历史 token 累计；完整日志统计请用 `opencode-tokens --by session`，逐个会话明细请用 `--by raw-session`。
+
 配置预算后，超阈值会显示预警：
 
+```
+12.5K tokens
+$0.023 | Session: 45.2K · Daily: $4.20/$5.00 (84%)
+```
+
+预算超限时，toast 会切换为告警：
+
 ```
 ⚠️ Budget exceeded!
 Daily: $5.50/$5.00 (110%)
@@ -167,7 +210,8 @@ opencode-tokens --by daily
 - `agent`：按 agent 分组
 - `provider`：按 provider 分组
 - `daily`：按天分组
-- `session`：按 session ID 分组
+- `session`：按顶层会话分组，子 agent 会话归并到其父会话（用父会话标题标注）
+- `raw-session`：按每个 session id 分组、不做归并，子 agent 会话保留为独立行并用各自标题标注
 - `all`：显示全部分组
 
 ### 趋势图
@@ -243,6 +287,9 @@ opencode-tokens config unset budget.daily
 # 查看预算状态
 opencode-tokens budget
 
+# 诊断插件配置、日志与默认定价回退
+opencode-tokens doctor
+
 # 查看内置定价表
 opencode-tokens pricing
 
@@ -275,7 +322,10 @@ opencode-tokens config generate
 - 定价来源是内置表、用户配置还是默认回退
 - 需要在配置文件中补充哪些模型定价
 
-`config init` 适合管道重定向，因为 stdout 只包含合法 JSON，且不会写文件。`config generate` 是写文件路径：stdout 保持为空，说明和状态信息输出到 stderr；父目录不存在时会自动创建，覆盖已有配置前会先备份。
+`config init` 适合管道重定向，因为 stdout 只包含合法 JSON，且不会写文件。`config generate` 是写文件路径：stdout 保持为空，说明和状态信息输出到 stderr；父目录不存在时会自动创建，覆盖已有配置前会先备份。两个命令都会读取本地日志，并为 GitHub Copilot、Cursor、Ollama 这类疑似零成本 provider 预填覆盖配置。
+
+`doctor` 是只读诊断命令，会检查 OpenCode 插件入口、tracker 配置、token log、
+最新记录、默认定价回退模型，并给出下一步应该运行的命令。
 
 ## 日志文件
 
@@ -367,8 +417,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 官方定价页 |
 
 ### 定价优先级
@@ -386,13 +437,14 @@ token 记录保存在：
 
 #### 示例：免费 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 }
   }
 }
 ```