opencode-tokenwatch 0.2.0 → 0.3.1

package/README.en.md

@@ -8,17 +8,17 @@ Real-time token usage, cache analytics & performance dashboard plugin for OpenCo
 
 ## 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
+- **Sidebar panel** — Session-level and per-model real-time stats (requests, tokens, cache, cost)
+- **Cache hit rate** — Inline color progress bars with trend indicators (↑/↓) and global weighted hit rate
+- **Performance metrics** — TTFT / TPS / End-to-end latency + P50/P95/P99 latency percentiles
+- **Token distribution** — 5-bucket role breakdown (system / user / toolCall / toolResult / output + other fallback)
+- **Error rate tracking** — Detects failed requests (empty token response) and computes real-time error rate
+- **Cost display** — Per-model cost (requires provider billing data)
 - **`/usage` command** — HTML Report → JSON Export → Text Report → Settings
-- **HTML report** — Interactive ECharts dashboard, auto-opened in browser
+- **HTML report** — Interactive ECharts dashboard: token distribution, performance percentiles, TPS horizontal ranking, error rate analysis — auto-opened in browser
+- **Persistent stats** — Performance metrics (TPS/TTFT/latency) written to a dedicated JSON file that accumulates forever, unaffected by log rotation
 - **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
 
@@ -44,8 +44,8 @@ Add to `opencode.json` or `opencode.jsonc`:
     "opencode-tokenwatch": {
       "sidebar": {
         "showPerformance": true,
-        "showPricing": false,
-        "showTokenDistribution": false,
+        "showPricing": true,
+        "showTokenDistribution": true,
         "showTrend": true
       },
       "language": "auto"
@@ -57,7 +57,7 @@ Add to `opencode.json` or `opencode.jsonc`:
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `sidebar.showPerformance` | boolean | `true` | Show TTFT/TPS/latency |
-| `sidebar.showPricing` | boolean | `true` | Show model pricing |
+| `sidebar.showPricing` | boolean | `true` | Show request cost |
 | `sidebar.showTokenDistribution` | boolean | `true` | Show token distribution |
 | `sidebar.showTrend` | boolean | `true` | Show trend indicator |
 | `language` | `"auto"` / `"zh"` / `"en"` | `"auto"` | UI language |
@@ -73,6 +73,14 @@ In OpenCode TUI, run `/usage`:
 - **Text Report** — Exports Markdown report to `~/.opencode/reports/`
 - **Settings** — Toggle sidebar blocks, switch language
 
+## Data Files
+
+| File | Path | Description |
+|------|------|-------------|
+| JSONL log | `~/.opencode/tokenwatch.jsonl` | Raw per-request log, auto-rotated at 5 MB |
+| Aggregated stats | `~/.opencode/tokenwatch-stats.json` | Persistent performance stats, accumulates forever |
+| Report output | `~/.opencode/reports/` | HTML / JSON / Markdown reports |
+
 ## Requirements
 
 - OpenCode CLI (with `opencode db` command)

package/README.md

@@ -8,17 +8,17 @@ OpenCode CLI 的实时 Token 用量统计、缓存分析与性能指标插件。
 
 ## 功能
 
-- **侧边栏面板** — 会话级与按模型的实时统计（请求数、Token、缓存、耗时、成本）
-- **缓存命中率** — 模型行内彩色进度条，带趋势指示器（↑/↓）
-- **性能指标** — 首 Token 延迟（TTFT）、每秒吞吐（TPS）、端到端延迟
-- **Token 分布** — 按角色分解（系统、用户、Agent、Tool 等）
-- **模型定价** — 输入/缓存/输出单价
+- **侧边栏面板** — 会话级与按模型的实时统计（请求数、Token、缓存、成本）
+- **缓存命中率** — 模型行内彩色进度条，带趋势指示器（↑/↓），全局总计行显示**加权命中率**
+- **性能指标** — TTFT / TPS / 端到端延迟 + P50/P95/P99 延迟分位数
+- **Token 分布** — 5 桶角色分解（system / user / toolCall / toolResult / output + other 兜底）
+- **错误率统计** — 识别并统计失败请求（空 Token 响应），实时计算错误率
+- **成本展示** — 按模型显示 cost（需 provider 返回计费数据）
 - **`/usage` 命令** — HTML 报告 → JSON 导出 → 文本报告 → 设置
-- **HTML 报告** — 交互式 ECharts 仪表盘，自动在浏览器打开
+- **HTML 报告** — 交互式 ECharts 仪表盘：Token 分布、性能分位数、TPS 水平排名、错误率分析，自动在浏览器打开
+- **持久化统计** — 性能指标（TPS/TTFT/延迟）写入独立 JSON 文件，永久累积，不受日志轮转影响
 - **多级折叠** — 面板、模型、子区块均可折叠，状态持久化
-- **语言切换** — 中英双语，可跟随系统或手动切换
-- **性能追踪** — 每次请求的 TTFT/TPS/延迟写入 JSONL，用于报告分析
-- **自适应配色** — 从主题色自动衍生
+- **语言切换** — 中英双语，跟随系统或手动切换
 
 ## 安装
 
@@ -44,8 +44,8 @@ npm install opencode-tokenwatch
     "opencode-tokenwatch": {
       "sidebar": {
         "showPerformance": true,
-        "showPricing": false,
-        "showTokenDistribution": false,
+        "showPricing": true,
+        "showTokenDistribution": true,
         "showTrend": true
       },
       "language": "auto"
@@ -57,7 +57,7 @@ npm install opencode-tokenwatch
 | 配置项 | 类型 | 默认值 | 说明 |
 |--------|------|--------|------|
 | `sidebar.showPerformance` | boolean | `true` | 显示 TTFT/TPS/延迟 |
-| `sidebar.showPricing` | boolean | `true` | 显示模型定价 |
+| `sidebar.showPricing` | boolean | `true` | 显示请求成本 |
 | `sidebar.showTokenDistribution` | boolean | `true` | 显示 Token 分布 |
 | `sidebar.showTrend` | boolean | `true` | 显示趋势指示器 |
 | `language` | `"auto"` / `"zh"` / `"en"` | `"auto"` | 界面语言 |
@@ -73,6 +73,14 @@ npm install opencode-tokenwatch
 - **文本报告** — 导出 Markdown 格式至 `~/.opencode/reports/`
 - **设置** — 开关侧边栏显示项、切换语言
 
+## 数据文件
+
+| 文件 | 路径 | 说明 |
+|------|------|------|
+| JSONL 日志 | `~/.opencode/tokenwatch.jsonl` | 原始请求日志，超 5MB 自动轮转 |
+| 聚合统计 | `~/.opencode/tokenwatch-stats.json` | 持久化性能统计，永久累积 |
+| 报告输出 | `~/.opencode/reports/` | HTML / JSON / Markdown 报告 |
+
 ## 系统要求
 
 - OpenCode CLI（支持 `opencode db` 命令）

package/dist/commands.jsx

@@ -3,6 +3,7 @@ import { formatUsageReport } from "./formatter.js";
 import { generateUsageHtml } from "./generate-usage-html.js";
 import { t, setLanguage } from "./i18n.js";
 import { readLogs } from "./perf-tracker.js";
+import { readPersistedStats } from "./stats-store.js";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -44,6 +45,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 +68,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,28 +87,69 @@ 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);
-    const logs = readLogs(1000);
+    // perfLogs: 仅用于 JSON 导出参考，保持适当窗口即可
+    const logs = readLogs(200);
+    // perfSummary: 使用持久化聚合统计，包含自插件安装以来的全量历史数据
+    // 不再受 readLogs 窗口限制，即使 JSONL 被轮转，历史指标也不会丢失
+    const perfSummary = readPersistedStats();
     const now = new Date();
     const pad = (n) => String(n).padStart(2, '0');
     const meta = {
@@ -101,7 +162,7 @@ async function buildCombinedData(api, filters = {}) {
     return {
         ...report,
         perfLogs: logs,
-        perfSummary: aggregatePerfStats(logs),
+        perfSummary,
         meta,
     };
 }
@@ -152,6 +213,10 @@ function showHtmlReportRangeMenu(api, dialog) {
         ]} flat={true}/>));
 }
 function showUsageMenu(api, dialog) {
+    try {
+        setLanguage(loadConfigFromStore(api).language);
+    }
+    catch { }
     dialog.replace(() => (<api.ui.DialogSelect title={t("panelTitle")} placeholder="Select an action..." options={[
             {
                 title: `${t("cmdTitleHtml")} ▸`,

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;