opencode-tokenwatch 0.1.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

@@ -0,0 +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, 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,103 +1,97 @@
-# opencode-tokenwatch
-
-Token usage analytics plugin for OpenCode.
-
-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.
-
-## Features
-
-- 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
-
-Add the package to OpenCode's plugin list.
-
-Install the package first:
-
-```sh
-npm install opencode-tokenwatch
-```
-
-`opencode.json` or `opencode.jsonc`
-
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "plugin": ["opencode-tokenwatch"]
-}
-```
-
-`tui.json` or `tui.jsonc`
-
-```json
-{
-  "$schema": "https://opencode.ai/tui.json",
-  "plugin": ["opencode-tokenwatch"]
-}
-```
-
-If you are preparing for npm publishing, this package is already configured to
-publish public artifacts from `dist/`.
-
-## Usage
-
-In OpenCode TUI:
-
-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.
-
-Exports are written to the current working directory:
-
-- `tokenwatch-usage-report.json`
-- `tokenwatch-models.csv`
-- `tokenwatch-providers.csv`
-- `tokenwatch-daily.csv`
-- `tokenwatch-sessions.csv`
-
-## Report Dimensions
-
-- Model
-- Provider
-- Day
-- Session
-- Current session summary
-
-## Requirements
-
-- OpenCode CLI with `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.
-
-## License
-
-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.d.ts

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