opencode-tokenwatch 0.1.0 → 0.2.0

package/README.en.md

@@ -0,0 +1,96 @@
+# 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

package/README.md

@@ -1,31 +1,32 @@
 # opencode-tokenwatch
 
-Token usage analytics plugin for OpenCode.
+[English](./README.en.md) · **简体中文**
 
-It adds a live sidebar panel for the current session and a `/usage` slash command
-that reads your local OpenCode history from SQLite, aggregates token usage by
-model, provider, date, and session, and supports export to JSON or CSV.
+![Sidebar](./assets/sidebar.png)
 
-## Features
+OpenCode CLI 的实时 Token 用量统计、缓存分析与性能指标插件。
 
-- Live sidebar updates while the assistant replies
-- Current-session aggregation across every model used in the conversation
-- `/usage` report for local history with model, provider, date, and session views
-- Export full reports to `JSON`
-- Export grouped tables to `CSV`
-- Uses `opencode db ... --format json` directly, so it works from local records
+## 功能
 
-## Install
+- **侧边栏面板** — 会话级与按模型的实时统计（请求数、Token、缓存、耗时、成本）
+- **缓存命中率** — 模型行内彩色进度条，带趋势指示器（↑/↓）
+- **性能指标** — 首 Token 延迟（TTFT）、每秒吞吐（TPS）、端到端延迟
+- **Token 分布** — 按角色分解（系统、用户、Agent、Tool 等）
+- **模型定价** — 输入/缓存/输出单价
+- **`/usage` 命令** — HTML 报告 → JSON 导出 → 文本报告 → 设置
+- **HTML 报告** — 交互式 ECharts 仪表盘，自动在浏览器打开
+- **多级折叠** — 面板、模型、子区块均可折叠，状态持久化
+- **语言切换** — 中英双语，可跟随系统或手动切换
+- **性能追踪** — 每次请求的 TTFT/TPS/延迟写入 JSONL，用于报告分析
+- **自适应配色** — 从主题色自动衍生
 
-Add the package to OpenCode's plugin list.
-
-Install the package first:
+## 安装
 
 ```sh
 npm install opencode-tokenwatch
 ```
 
-`opencode.json` or `opencode.jsonc`
+在 `opencode.json` 或 `opencode.jsonc` 中添加：
 
 ```json
 {
@@ -34,70 +35,62 @@ npm install opencode-tokenwatch
 }
 ```
 
-`tui.json` or `tui.jsonc`
+## 配置
 
-```json
+```jsonc
 {
-  "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["opencode-tokenwatch"]
+  "plugin": ["opencode-tokenwatch"],
+  "pluginConfig": {
+    "opencode-tokenwatch": {
+      "sidebar": {
+        "showPerformance": true,
+        "showPricing": false,
+        "showTokenDistribution": false,
+        "showTrend": true
+      },
+      "language": "auto"
+    }
+  }
 }
 ```
 
-If you are preparing for npm publishing, this package is already configured to
-publish public artifacts from `dist/`.
-
-## Usage
-
-In OpenCode TUI:
+| 配置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `sidebar.showPerformance` | boolean | `true` | 显示 TTFT/TPS/延迟 |
+| `sidebar.showPricing` | boolean | `true` | 显示模型定价 |
+| `sidebar.showTokenDistribution` | boolean | `true` | 显示 Token 分布 |
+| `sidebar.showTrend` | boolean | `true` | 显示趋势指示器 |
+| `language` | `"auto"` / `"zh"` / `"en"` | `"auto"` | 界面语言 |
 
-1. Open the right sidebar to see live token totals for the current session.
-2. Run `/usage`.
-3. Choose:
-   - `View report`
-   - `Export JSON`
-   - `Export CSV`
-4. Pick a time range and optional provider/model filters.
+运行时也可通过 `/usage` → 设置 调整，优先级高于 `pluginConfig`。
 
-Exports are written to the current working directory:
+## 用法
 
-- `tokenwatch-usage-report.json`
-- `tokenwatch-models.csv`
-- `tokenwatch-providers.csv`
-- `tokenwatch-daily.csv`
-- `tokenwatch-sessions.csv`
+在 OpenCode TUI 中输入 `/usage`，选择：
 
-## Report Dimensions
+- **HTML 报告** — 选择日期范围，生成仪表盘并在浏览器打开
+- **JSON 导出** — 导出完整用量数据至 `~/.opencode/reports/`
+- **文本报告** — 导出 Markdown 格式至 `~/.opencode/reports/`
+- **设置** — 开关侧边栏显示项、切换语言
 
-- Model
-- Provider
-- Day
-- Session
-- Current session summary
+## 系统要求
 
-## Requirements
-
-- OpenCode CLI with `opencode db`
+- OpenCode CLI（支持 `opencode db` 命令）
 - Node.js 18+
 
-## Build
+## 构建
 
 ```sh
 npm install
 npm run build
 ```
 
-## Publish Prep
-
-Before publishing to npm, run:
-
-```sh
-npm run release:check
-```
+## 相关项目
 
-This builds the package and runs `npm pack --dry-run` with an isolated temp npm
-cache, which is especially helpful on Windows when the default cache directory is
-locked by another process.
+- [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/) — 缓存感知的无限上下文 + 跨会话记忆系统
 
-## License
+## 许可
 
 MIT

package/dist/commands.d.ts

@@ -0,0 +1,2 @@
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+export declare function registerCommands(api: TuiPluginApi): Promise<void>;

package/dist/commands.js

@@ -0,0 +1,208 @@
+import { getUsageReport } from "./queries.js";
+import { formatUsageReport } from "./formatter.js";
+import { generateUsageHtml } from "./generate-usage-html.js";
+import { t } from "./i18n.js";
+import { readLogs } from "./perf-tracker.js";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { execSync } from "node:child_process";
+const DEFAULT_CONFIG = {
+    sidebar: { showPerformance: true, showPricing: true, showTokenDistribution: true, showTrend: true },
+    language: "auto",
+};
+export async function registerCommands(api) {
+    api.command?.register(() => [
+        {
+            value: "tokenwatch-html-report",
+            title: "Generate HTML report",
+            description: "Generate an HTML dashboard with token usage, cache efficiency, and performance charts",
+            category: "Stats",
+            slash: { name: "usage-html", aliases: ["usage"] },
+            onSelect: async () => {
+                await showHtmlReport(api);
+            },
+        },
+        {
+            value: "tokenwatch-json-export",
+            title: "Export as JSON",
+            description: "Export usage data as JSON file",
+            category: "Stats",
+            slash: { name: "usage-json" },
+            onSelect: async () => {
+                await showJsonExport(api);
+            },
+        },
+        {
+            value: "tokenwatch-text-report",
+            title: "Text report (legacy)",
+            description: "View plain text usage report in terminal",
+            category: "Stats",
+            slash: { name: "usage-text" },
+            onSelect: async () => {
+                await showTextReport(api);
+            },
+        },
+        {
+            value: "tokenwatch-settings",
+            title: "TokenWatch Settings",
+            description: "Configure sidebar display options",
+            category: "Stats",
+            slash: { name: "usage-settings", aliases: ["tokenwatch-settings"] },
+            onSelect: async () => {
+                await showSettingsDialog(api);
+            },
+        },
+    ]);
+}
+function ensureReportDir() {
+    const dir = join(homedir(), ".opencode", "reports");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function openInBrowser(filePath) {
+    try {
+        const platform = process.platform;
+        if (platform === "win32")
+            execSync(`start "" "${filePath}"`, { windowsHide: true, timeout: 5000 });
+        else if (platform === "darwin")
+            execSync(`open "${filePath}"`, { timeout: 5000 });
+        else
+            execSync(`xdg-open "${filePath}"`, { timeout: 5000 });
+    }
+    catch { /* silently fail */ }
+}
+function aggregatePerfStats(logs) {
+    const map = new Map();
+    for (const entry of logs) {
+        const key = entry.model;
+        let s = map.get(key);
+        if (!s) {
+            s = {
+                model: key,
+                providerID: entry.providerID,
+                requestCount: 0,
+                totalInput: 0, totalOutput: 0, totalCacheRead: 0, totalCacheWrite: 0, totalCost: 0,
+                avgTTFT: null, maxTTFT: null, minTTFT: null,
+                avgTPS: null, maxTPS: null, minTPS: null,
+                avgLatency: null, maxLatency: null, minLatency: null,
+            };
+            map.set(key, s);
+        }
+        s.requestCount++;
+        s.totalInput += entry.inputTokens;
+        s.totalOutput += entry.outputTokens;
+        s.totalCacheRead += entry.cacheReadTokens;
+        s.totalCacheWrite += entry.cacheWriteTokens;
+        s.totalCost += entry.cost;
+        const c = s.requestCount;
+        if (entry.ttft_ms != null) {
+            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) {
+            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.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());
+}
+async function buildCombinedData(api) {
+    const report = await getUsageReport({});
+    const logs = readLogs(1000);
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    const meta = {
+        generatedAt: `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}`,
+        dateRange: {
+            start: report.daily.length > 0 ? report.daily[report.daily.length - 1].day : "—",
+            end: report.daily.length > 0 ? report.daily[0].day : "—",
+        },
+    };
+    return {
+        ...report,
+        perfLogs: logs,
+        perfSummary: aggregatePerfStats(logs),
+        meta,
+    };
+}
+async function showHtmlReport(api) {
+    try {
+        const data = await buildCombinedData(api);
+        const html = generateUsageHtml(data);
+        const dir = ensureReportDir();
+        const dateStr = new Date().toISOString().slice(0, 10);
+        const filePath = join(dir, `tokenwatch-${dateStr}.html`);
+        writeFileSync(filePath, html, "utf-8");
+        api.ui.toast?.({ message: `Report: ${filePath}`, variant: "info" });
+        openInBrowser(filePath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        api.ui.toast?.({ message: `Error: ${msg}`, variant: "error" });
+    }
+}
+async function showJsonExport(api) {
+    try {
+        const report = await getUsageReport({});
+        const dir = ensureReportDir();
+        const dateStr = new Date().toISOString().slice(0, 10);
+        const filePath = join(dir, `tokenwatch-${dateStr}.json`);
+        writeFileSync(filePath, JSON.stringify(report, null, 2), "utf-8");
+        api.ui.toast?.({ message: `JSON: ${filePath}`, variant: "info" });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        api.ui.toast?.({ message: `Error: ${msg}`, variant: "error" });
+    }
+}
+async function showTextReport(api) {
+    try {
+        const report = await getUsageReport({});
+        const formatted = formatUsageReport(report);
+        const dir = ensureReportDir();
+        const dateStr = new Date().toISOString().slice(0, 10);
+        const filePath = join(dir, `tokenwatch-${dateStr}.md`);
+        writeFileSync(filePath, formatted, "utf-8");
+        api.ui.toast?.({ message: `Report saved to ${filePath}`, variant: "info" });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        api.ui.toast?.({ message: `Error: ${msg}`, variant: "error" });
+    }
+}
+async function showSettingsDialog(api) {
+    const currentConfig = loadConfigFromStore(api);
+    const cfg = currentConfig.sidebar;
+    const options = [
+        `[${cfg.showPerformance ? "x" : " "}] ${t("showPerformance")}`,
+        `[${cfg.showPricing ? "x" : " "}] ${t("showPricing")}`,
+        `[${cfg.showTokenDistribution ? "x" : " "}] ${t("showTokenDistribution")}`,
+        `[${cfg.showTrend ? "x" : " "}] ${t("showTrend")}`,
+        `---`,
+        `${t("language")}: ${currentConfig.language}`,
+    ].join("\n");
+    api.ui.toast?.({ message: `TokenWatch settings:\n${options}`, variant: "info" });
+}
+function loadConfigFromStore(api) {
+    const base = { sidebar: { ...DEFAULT_CONFIG.sidebar }, language: DEFAULT_CONFIG.language };
+    try {
+        const stored = api.kv?.get?.("tokenwatch-config");
+        if (stored) {
+            if (stored.sidebar)
+                Object.assign(base.sidebar, stored.sidebar);
+            if (stored.language)
+                base.language = stored.language;
+        }
+    }
+    catch { /* defaults */ }
+    return base;
+}