opencode-tokenwatch 0.2.0 → 0.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 TTWK
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 TTWK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -1,96 +1,97 @@
-# opencode-tokenwatch
-
-**English** · [简体中文](./README.md)
-
-![Sidebar](./assets/sidebar.png)
-
-Real-time token usage, cache analytics & performance dashboard plugin for OpenCode CLI.
-
-## Features
-
-- **Sidebar panel** — Session-level and per-model real-time stats (requests, tokens, cache, latency, cost)
-- **Cache hit rate** — Inline progress bars with color thresholds and trend indicators (↑/↓)
-- **Performance metrics** — Time to first token (TTFT), tokens per second (TPS), end-to-end latency
-- **Token distribution** — Breakdown by role (system, user, Agent, Tool, etc.)
-- **Model pricing** — Input/cache/output unit prices
-- **`/usage` command** — HTML Report → JSON Export → Text Report → Settings
-- **HTML report** — Interactive ECharts dashboard, auto-opened in browser
-- **Multi-level collapse** — Panel, models, and sub-blocks collapsible with persisted state
-- **Language switching** — Auto-detect or manually switch between Chinese and English
-- **Per-request tracking** — TTFT/TPS/latency logged to JSONL for report analysis
-- **Adaptive coloring** — Colors auto-derived from theme
-
-## Install
-
-```sh
-npm install opencode-tokenwatch
-```
-
-Add to `opencode.json` or `opencode.jsonc`:
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-tokenwatch"]
-}
-```
-
-## Configuration
-
-```jsonc
-{
-  "plugin": ["opencode-tokenwatch"],
-  "pluginConfig": {
-    "opencode-tokenwatch": {
-      "sidebar": {
-        "showPerformance": true,
-        "showPricing": false,
-        "showTokenDistribution": false,
-        "showTrend": true
-      },
-      "language": "auto"
-    }
-  }
-}
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `sidebar.showPerformance` | boolean | `true` | Show TTFT/TPS/latency |
-| `sidebar.showPricing` | boolean | `true` | Show model pricing |
-| `sidebar.showTokenDistribution` | boolean | `true` | Show token distribution |
-| `sidebar.showTrend` | boolean | `true` | Show trend indicator |
-| `language` | `"auto"` / `"zh"` / `"en"` | `"auto"` | UI language |
-
-Settings can also be toggled via `/usage` → Settings, taking precedence over `pluginConfig`.
-
-## Usage
-
-In OpenCode TUI, run `/usage`:
-
-- **HTML Report** — Pick a date range, generates a dashboard and opens it in browser
-- **JSON Export** — Exports full usage data to `~/.opencode/reports/`
-- **Text Report** — Exports Markdown report to `~/.opencode/reports/`
-- **Settings** — Toggle sidebar blocks, switch language
-
-## Requirements
-
-- OpenCode CLI (with `opencode db` command)
-- Node.js 18+
-
-## Build
-
-```sh
-npm install
-npm run build
-```
-
-## Related
-
-- [opencode-throughput](https://github.com/Howardzhangdqs/opencode-throughput) — Real-time LLM performance monitoring (TTFT/TPS/latency/cost)
-- [opencode-visual-cache](https://github.com/Hotakus/opencode-visual-cache) — TUI sidebar cache hit rate visualization, token distribution analysis
-- [magic-context](https://github.com/cortexkit/magic-context/) — Cache-aware infinite context + cross-session memory system
-
-## License
-
-MIT
+# opencode-tokenwatch
+
+**English** · [简体中文](./README.md)
+
+![Sidebar](./assets/sidebar.png)
+
+Real-time token usage, cache analytics & performance dashboard plugin for OpenCode CLI.
+
+## Features
+
+- **Sidebar panel** — Session-level and per-model real-time stats (requests, tokens, cache, latency, cost)
+- **Cache hit rate** — Inline progress bars with color thresholds, trend indicators (↑/↓), and global weighted cache hit rate in the summary row
+- **Performance metrics** — TTFT / TPS / End-to-end latency + P50/P95/P99 latency percentiles
+- **Token distribution** — 5-bucket role breakdown (system, user, Agent, Tool and other with fallback and adaptive scaling)
+- **Error rate statistics** — Detects and tracks failed requests (empty token response) and real-time error rate
+- **Model pricing** — Input/cache/output unit prices
+- **`/usage` command** — HTML Report → JSON Export → Text Report → Settings
+- **HTML report** — Interactive ECharts dashboard: Token distribution, performance percentiles, error rate analysis, model speed rankings (redesigned from overlapping scatter plots to horizontal bar charts), auto-opened in browser
+- **Multi-level collapse** — Panel, models, and sub-blocks collapsible with persisted state
+- **Language switching** — Auto-detect or manually switch between Chinese and English
+- **Per-request tracking** — TTFT/TPS/latency logged to JSONL for report analysis
+- **Adaptive coloring** — Colors auto-derived from theme
+
+## Install
+
+```sh
+npm install opencode-tokenwatch
+```
+
+Add to `opencode.json` or `opencode.jsonc`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-tokenwatch"]
+}
+```
+
+## Configuration
+
+```jsonc
+{
+  "plugin": ["opencode-tokenwatch"],
+  "pluginConfig": {
+    "opencode-tokenwatch": {
+      "sidebar": {
+        "showPerformance": true,
+        "showPricing": false,
+        "showTokenDistribution": false,
+        "showTrend": true
+      },
+      "language": "auto"
+    }
+  }
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `sidebar.showPerformance` | boolean | `true` | Show TTFT/TPS/latency |
+| `sidebar.showPricing` | boolean | `true` | Show model pricing |
+| `sidebar.showTokenDistribution` | boolean | `true` | Show token distribution |
+| `sidebar.showTrend` | boolean | `true` | Show trend indicator |
+| `language` | `"auto"` / `"zh"` / `"en"` | `"auto"` | UI language |
+
+Settings can also be toggled via `/usage` → Settings, taking precedence over `pluginConfig`.
+
+## Usage
+
+In OpenCode TUI, run `/usage`:
+
+- **HTML Report** — Pick a date range, generates a dashboard and opens it in browser
+- **JSON Export** — Exports full usage data to `~/.opencode/reports/`
+- **Text Report** — Exports Markdown report to `~/.opencode/reports/`
+- **Settings** — Toggle sidebar blocks, switch language
+
+## Requirements
+
+- OpenCode CLI (with `opencode db` command)
+- Node.js 18+
+
+## Build
+
+```sh
+npm install
+npm run build
+```
+
+## Related
+
+- [opencode-throughput](https://github.com/Howardzhangdqs/opencode-throughput) — Real-time LLM performance monitoring (TTFT/TPS/latency/cost)
+- [opencode-visual-cache](https://github.com/Hotakus/opencode-visual-cache) — TUI sidebar cache hit rate visualization, token distribution analysis
+- [magic-context](https://github.com/cortexkit/magic-context/) — Cache-aware infinite context + cross-session memory system
+
+## License
+
+MIT

package/README.md

@@ -1,96 +1,97 @@
-# opencode-tokenwatch
-
-[English](./README.en.md) · **简体中文**
-
-![Sidebar](./assets/sidebar.png)
-
-OpenCode CLI 的实时 Token 用量统计、缓存分析与性能指标插件。
-
-## 功能
-
-- **侧边栏面板** — 会话级与按模型的实时统计（请求数、Token、缓存、耗时、成本）
-- **缓存命中率** — 模型行内彩色进度条，带趋势指示器（↑/↓）
-- **性能指标** — 首 Token 延迟（TTFT）、每秒吞吐（TPS）、端到端延迟
-- **Token 分布** — 按角色分解（系统、用户、Agent、Tool 等）
-- **模型定价** — 输入/缓存/输出单价
-- **`/usage` 命令** — HTML 报告 → JSON 导出 → 文本报告 → 设置
-- **HTML 报告** — 交互式 ECharts 仪表盘，自动在浏览器打开
-- **多级折叠** — 面板、模型、子区块均可折叠，状态持久化
-- **语言切换** — 中英双语，可跟随系统或手动切换
-- **性能追踪** — 每次请求的 TTFT/TPS/延迟写入 JSONL，用于报告分析
-- **自适应配色** — 从主题色自动衍生
-
-## 安装
-
-```sh
-npm install opencode-tokenwatch
-```
-
-在 `opencode.json` 或 `opencode.jsonc` 中添加：
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-tokenwatch"]
-}
-```
-
-## 配置
-
-```jsonc
-{
-  "plugin": ["opencode-tokenwatch"],
-  "pluginConfig": {
-    "opencode-tokenwatch": {
-      "sidebar": {
-        "showPerformance": true,
-        "showPricing": false,
-        "showTokenDistribution": false,
-        "showTrend": true
-      },
-      "language": "auto"
-    }
-  }
-}
-```
-
-| 配置项 | 类型 | 默认值 | 说明 |
-|--------|------|--------|------|
-| `sidebar.showPerformance` | boolean | `true` | 显示 TTFT/TPS/延迟 |
-| `sidebar.showPricing` | boolean | `true` | 显示模型定价 |
-| `sidebar.showTokenDistribution` | boolean | `true` | 显示 Token 分布 |
-| `sidebar.showTrend` | boolean | `true` | 显示趋势指示器 |
-| `language` | `"auto"` / `"zh"` / `"en"` | `"auto"` | 界面语言 |
-
-运行时也可通过 `/usage` → 设置 调整，优先级高于 `pluginConfig`。
-
-## 用法
-
-在 OpenCode TUI 中输入 `/usage`，选择：
-
-- **HTML 报告** — 选择日期范围，生成仪表盘并在浏览器打开
-- **JSON 导出** — 导出完整用量数据至 `~/.opencode/reports/`
-- **文本报告** — 导出 Markdown 格式至 `~/.opencode/reports/`
-- **设置** — 开关侧边栏显示项、切换语言
-
-## 系统要求
-
-- OpenCode CLI（支持 `opencode db` 命令）
-- Node.js 18+
-
-## 构建
-
-```sh
-npm install
-npm run build
-```
-
-## 相关项目
-
-- [opencode-throughput](https://github.com/Howardzhangdqs/opencode-throughput) — 实时 LLM 性能监控，采集 TTFT/TPS/延迟和成本
-- [opencode-visual-cache](https://github.com/Hotakus/opencode-visual-cache) — TUI 侧边栏缓存命中率可视化，Token 分布分析
-- [magic-context](https://github.com/cortexkit/magic-context/) — 缓存感知的无限上下文 + 跨会话记忆系统
-
-## 许可
-
-MIT
+# opencode-tokenwatch
+
+[English](./README.en.md) · **简体中文**
+
+![Sidebar](./assets/sidebar.png)
+
+OpenCode CLI 的实时 Token 用量统计、缓存分析与性能指标插件。
+
+## 功能
+
+- **侧边栏面板** — 会话级与按模型的实时统计（请求数、Token、缓存、耗时、成本）
+- **缓存命中率** — 模型行内彩色进度条，带趋势指示器（↑/↓），全局总计行显示**全局加权命中率**
+- **性能指标** — TTFT / TPS / 端到端延迟 + P50/P95/P99 延迟分位数
+- **Token 分布** — 5 桶角色分解（系统、用户、Agent、Tool 以及 other 兜底，支持自适应缩放）
+- **错误率统计** — 识别并统计失败请求（空 Token 响应），实时计算错误率
+- **模型定价** — 输入/缓存/输出单价
+- **`/usage` 命令** — HTML 报告 → JSON 导出 → 文本报告 → 设置
+- **HTML 报告** — 交互式 ECharts 仪表盘：Token 分布、性能分位数、错误率分析、模型效率水平排名（已重构重叠散点图为水平条形对比图），自动在浏览器打开
+- **多级折叠** — 面板、模型、子区块均可折叠，状态持久化
+- **语言切换** — 中英双语，可跟随系统或手动切换
+- **性能追踪** — 每次请求的 TTFT/TPS/延迟写入 JSONL，用于报告分析
+- **自适应配色** — 从主题色自动衍生
+
+## 安装
+
+```sh
+npm install opencode-tokenwatch
+```
+
+在 `opencode.json` 或 `opencode.jsonc` 中添加：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-tokenwatch"]
+}
+```
+
+## 配置
+
+```jsonc
+{
+  "plugin": ["opencode-tokenwatch"],
+  "pluginConfig": {
+    "opencode-tokenwatch": {
+      "sidebar": {
+        "showPerformance": true,
+        "showPricing": false,
+        "showTokenDistribution": false,
+        "showTrend": true
+      },
+      "language": "auto"
+    }
+  }
+}
+```
+
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `sidebar.showPerformance` | boolean | `true` | 显示 TTFT/TPS/延迟 |
+| `sidebar.showPricing` | boolean | `true` | 显示模型定价 |
+| `sidebar.showTokenDistribution` | boolean | `true` | 显示 Token 分布 |
+| `sidebar.showTrend` | boolean | `true` | 显示趋势指示器 |
+| `language` | `"auto"` / `"zh"` / `"en"` | `"auto"` | 界面语言 |
+
+运行时也可通过 `/usage` → 设置 调整，优先级高于 `pluginConfig`。
+
+## 用法
+
+在 OpenCode TUI 中输入 `/usage`，选择：
+
+- **HTML 报告** — 选择日期范围，生成仪表盘并在浏览器打开
+- **JSON 导出** — 导出完整用量数据至 `~/.opencode/reports/`
+- **文本报告** — 导出 Markdown 格式至 `~/.opencode/reports/`
+- **设置** — 开关侧边栏显示项、切换语言
+
+## 系统要求
+
+- OpenCode CLI（支持 `opencode db` 命令）
+- Node.js 18+
+
+## 构建
+
+```sh
+npm install
+npm run build
+```
+
+## 相关项目
+
+- [opencode-throughput](https://github.com/Howardzhangdqs/opencode-throughput) — 实时 LLM 性能监控，采集 TTFT/TPS/延迟和成本
+- [opencode-visual-cache](https://github.com/Hotakus/opencode-visual-cache) — TUI 侧边栏缓存命中率可视化，Token 分布分析
+- [magic-context](https://github.com/cortexkit/magic-context/) — 缓存感知的无限上下文 + 跨会话记忆系统
+
+## 许可
+
+MIT

package/dist/commands.jsx

@@ -44,6 +44,19 @@ function openInBrowser(filePath) {
     }
     catch { /* silently fail */ }
 }
+/** 线性插值百分位数，输入须为有序数组 */
+function computePercentile(sortedArr, p) {
+    if (sortedArr.length === 0)
+        return null;
+    if (sortedArr.length === 1)
+        return sortedArr[0];
+    const idx = (p / 100) * (sortedArr.length - 1);
+    const lo = Math.floor(idx);
+    const hi = Math.ceil(idx);
+    if (lo === hi)
+        return sortedArr[lo];
+    return sortedArr[lo] + (sortedArr[hi] - sortedArr[lo]) * (idx - lo);
+}
 function aggregatePerfStats(logs) {
     const map = new Map();
     for (const entry of logs) {
@@ -54,10 +67,16 @@ function aggregatePerfStats(logs) {
                 model: key,
                 providerID: entry.providerID,
                 requestCount: 0,
+                ttftCount: 0, // Bug fix: 独立维护有效样本计数
+                tpsCount: 0,
+                latencyCount: 0,
                 totalInput: 0, totalOutput: 0, totalCacheRead: 0, totalCacheWrite: 0, totalCost: 0,
                 avgTTFT: null, maxTTFT: null, minTTFT: null,
+                p50TTFT: null, p95TTFT: null, p99TTFT: null,
                 avgTPS: null, maxTPS: null, minTPS: null,
                 avgLatency: null, maxLatency: null, minLatency: null,
+                p50Latency: null, p95Latency: null, p99Latency: null,
+                cacheHitRate: null,
             };
             map.set(key, s);
         }
@@ -67,24 +86,61 @@ function aggregatePerfStats(logs) {
         s.totalCacheRead += entry.cacheReadTokens;
         s.totalCacheWrite += entry.cacheWriteTokens;
         s.totalCost += entry.cost;
-        const c = s.requestCount;
         if (entry.ttft_ms != null) {
+            // Bug fix: 分母使用 ttftCount（有效样本数），而非 requestCount（总请求数）
+            s.ttftCount++;
+            const c = s.ttftCount;
             s.avgTTFT = s.avgTTFT != null ? s.avgTTFT + (entry.ttft_ms - s.avgTTFT) / c : entry.ttft_ms;
             s.maxTTFT = s.maxTTFT != null ? Math.max(s.maxTTFT, entry.ttft_ms) : entry.ttft_ms;
             s.minTTFT = s.minTTFT != null ? Math.min(s.minTTFT, entry.ttft_ms) : entry.ttft_ms;
         }
         if (entry.tps != null) {
+            // Bug fix: 分母使用 tpsCount（有效样本数）
+            s.tpsCount++;
+            const c = s.tpsCount;
             s.avgTPS = s.avgTPS != null ? s.avgTPS + (entry.tps - s.avgTPS) / c : entry.tps;
             s.maxTPS = s.maxTPS != null ? Math.max(s.maxTPS, entry.tps) : entry.tps;
             s.minTPS = s.minTPS != null ? Math.min(s.minTPS, entry.tps) : entry.tps;
         }
         if (entry.latency_ms != null) {
+            s.latencyCount++;
+            const c = s.latencyCount;
             s.avgLatency = s.avgLatency != null ? s.avgLatency + (entry.latency_ms - s.avgLatency) / c : entry.latency_ms;
             s.maxLatency = s.maxLatency != null ? Math.max(s.maxLatency, entry.latency_ms) : entry.latency_ms;
             s.minLatency = s.minLatency != null ? Math.min(s.minLatency, entry.latency_ms) : entry.latency_ms;
         }
     }
-    return Array.from(map.values());
+    // 分位数后处理：需要收集每个模型的所有样本然后计算
+    // 注： 此处采用单次遍历日志重新收集分数据，需要两次遍历
+    const ttftBuckets = new Map();
+    const latBuckets = new Map();
+    for (const entry of logs) {
+        const key = entry.model;
+        if (entry.ttft_ms != null) {
+            const arr = ttftBuckets.get(key) ?? [];
+            arr.push(entry.ttft_ms);
+            ttftBuckets.set(key, arr);
+        }
+        if (entry.latency_ms != null) {
+            const arr = latBuckets.get(key) ?? [];
+            arr.push(entry.latency_ms);
+            latBuckets.set(key, arr);
+        }
+    }
+    const result = Array.from(map.values());
+    for (const s of result) {
+        const ttftArr = [...(ttftBuckets.get(s.model) ?? [])].sort((a, b) => a - b);
+        s.p50TTFT = computePercentile(ttftArr, 50);
+        s.p95TTFT = computePercentile(ttftArr, 95);
+        s.p99TTFT = computePercentile(ttftArr, 99);
+        const latArr = [...(latBuckets.get(s.model) ?? [])].sort((a, b) => a - b);
+        s.p50Latency = computePercentile(latArr, 50);
+        s.p95Latency = computePercentile(latArr, 95);
+        s.p99Latency = computePercentile(latArr, 99);
+        const denom = s.totalInput + s.totalCacheRead;
+        s.cacheHitRate = denom > 0 ? (s.totalCacheRead / denom) * 100 : null;
+    }
+    return result;
 }
 async function buildCombinedData(api, filters = {}) {
     const report = await getUsageReport(filters);

package/dist/formatter.d.ts

@@ -67,6 +67,22 @@ export interface SessionBreakdownItem {
     totalCost: number;
     day: string;
 }
+/** 失败请求统计 */
+export interface ErrorStats {
+    /** 过滤内总请求数（tokens.total > 0 的 assistant） */
+    successCount: number;
+    /** 失败请求数（tokens.total == 0 的 assistant） */
+    failedCount: number;
+    /** 失败率：failedCount / (successCount + failedCount) */
+    errorRate: number;
+    /** 按模型细化的失败数 */
+    byModel: Array<{
+        provider: string;
+        model: string;
+        failed: number;
+        total: number;
+    }>;
+}
 export interface UsageReport {
     filters: UsageFilters;
     summary: SessionTokenData;
@@ -74,6 +90,7 @@ export interface UsageReport {
     providers: ProviderBreakdownItem[];
     daily: DailyBreakdownItem[];
     sessions: SessionBreakdownItem[];
+    errors?: ErrorStats;
 }
 export declare function formatTokens(n: number): string;
 export declare function formatCost(n: number): string;
@@ -95,12 +112,17 @@ export interface SessionPerfStats {
         totalCacheWrite: number;
         totalRequests: number;
         totalCost: number;
+        /** 全局加权缓存命中率（按请求数加权平均） */
+        weightedCacheHitRate: number | null;
     };
 }
 export interface ModelPerfStats {
     model: string;
     providerID: string;
     requestCount: number;
+    ttftCount: number;
+    tpsCount: number;
+    latencyCount: number;
     totalInput: number;
     totalOutput: number;
     totalCacheRead: number;
@@ -109,12 +131,20 @@ export interface ModelPerfStats {
     avgTTFT: number | null;
     maxTTFT: number | null;
     minTTFT: number | null;
+    p50TTFT: number | null;
+    p95TTFT: number | null;
+    p99TTFT: number | null;
     avgTPS: number | null;
     maxTPS: number | null;
     minTPS: number | null;
     avgLatency: number | null;
     maxLatency: number | null;
     minLatency: number | null;
+    p50Latency: number | null;
+    p95Latency: number | null;
+    p99Latency: number | null;
+    /** 该模型加权缓存命中率：cacheRead / (cacheRead + input) */
+    cacheHitRate: number | null;
 }
 export interface TokenDistribution {
     system: number;