opencode-tokenwatch 0.4.0 → 0.6.0

package/README.en.md

@@ -4,29 +4,33 @@
 
 ![Sidebar](./assets/sidebar.png)
 
-Real-time token usage, cache analytics & performance dashboard plugin for OpenCode CLI.
+A terminal monitoring plugin for OpenCode CLI that displays real-time token usage, cache hit rate, and model throughput in the sidebar, with one-click interactive browser reports.
 
-## Features
+---
 
-- **Sidebar panel** — Session-level and per-model real-time stats (requests, tokens, cache, cost)
-- **Cache hit rate** — Per-model tracking with trend indicators (↑/↓) and global weighted total
-- **Performance metrics** — TTFT / TPS / End-to-end latency + P50/P95/P99 latency percentiles
-- **Token distribution** — Per-role breakdown (system / user / tool / output)
-- **Cost tracking** — Per-model cost display (requires provider billing data)
-- **Error rate tracking** — Detects failed requests and computes real-time error rate
-- **`/usage` command** — HTML Report → JSON Export → Text Report → Settings
-- **HTML report** — Interactive ECharts dashboard: token trends, performance comparison, TPS ranking, error rate analysis — auto-opened in browser
-- **Persistent stats** — Performance metrics accumulate forever in a dedicated file, unaffected by session resets
-- **Multi-level collapse** — Panel, models, and sub-blocks collapsible with persisted state
-- **Language switching** — Auto-detect or manually switch between Chinese and English
+## Key Features
 
-## Install
+- **Real-time Sidebar Dashboard**: Check input/output tokens, estimated cost, cache hit rate, and average TTFT & generation speed per model during sessions.
+- **Cache Hit Rate & Trends**: Track cache efficiency per model, with arrows showing whether the hit rate for recent requests is trending up or down.
+- **Token Breakdown**: Automatically breaks down tokens into system prompt, user input, tool execution, and assistant output to identify major context consumers.
+- **Interactive Usage Reports**: Type `/usage` in the terminal to launch an ECharts interactive dashboard in your browser with historical trends, cross-model comparisons, and failed request stats; export to JSON or Markdown with one click.
+- **Dual-Host Compatibility**: Seamlessly works with both OpenCode 1.x and OpenCode 2 (beta). Automatically detects the host environment with zero manual configuration.
+
+---
+
+## Installation & Setup
+
+### 1. Install
+
+Run in your project directory:
 
 ```sh
 npm install opencode-tokenwatch
 ```
 
-Add to `opencode.json` or `opencode.jsonc`:
+### 2. Enable Plugin
+
+Add the plugin entry to `opencode.json` (or `opencode.jsonc`):
 
 ```json
 {
@@ -35,45 +39,35 @@ Add to `opencode.json` or `opencode.jsonc`:
 }
 ```
 
-## Configuration
+Restart OpenCode and the TokenWatch panel will load in the sidebar automatically.
 
-In OpenCode TUI, run `/usage` → **Settings** to interactively toggle display items and switch language. Settings are persisted automatically — no need to edit config files manually.
+---
 
 ## Usage
 
-In OpenCode TUI, run `/usage`:
+Type `/usage` in the terminal input to open the action menu:
 
-- **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
+- **HTML Report**: Select a date range to generate and open an interactive chart in your default browser.
+- **Export Data**: Export structured JSON or Markdown reports, saved to `~/.opencode/reports/` by default.
+- **Settings**: Interactively toggle sidebar sections or switch language in the popup menu. Changes are saved automatically without editing configuration files.
 
-## Data Files
-
-| File | Path | Description |
-|------|------|-------------|
-| JSONL log | `~/.opencode/tokenwatch.jsonl` | Raw per-request log |
-| Aggregated stats | `~/.opencode/tokenwatch-stats.json` | Persistent performance stats |
-| Report output | `~/.opencode/reports/` | HTML / JSON / Markdown reports |
+---
 
 ## Requirements
 
-- OpenCode CLI (with `opencode db` command)
-- Node.js 18+
+- **OpenCode CLI**: 1.18+ or OpenCode 2 (`@opencode-ai/cli@beta`)
+- **Node.js**: ≥ 18.0.0
 
-## Build
+---
 
-```sh
-npm install
-npm run build
-```
-
-## Related
+## Related Projects
 
 - [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

@@ -4,29 +4,33 @@
 
 ![Sidebar](./assets/sidebar.png)
 
-OpenCode CLI 的实时 Token 用量统计、缓存分析与性能指标插件。
+OpenCode CLI的终端监控插件，在侧边栏实时显示Token用量、缓存命中率与模型响应速度，并支持一键生成网页版可视化用量报表。
 
-## 功能
+---
 
-- **侧边栏面板** — 会话级与按模型的实时统计（请求数、Token、缓存、成本）
-- **缓存命中率** — 按模型实时追踪，带趋势指示器（↑/↓）与全局加权总计
-- **性能指标** — TTFT / TPS / 端到端延迟，含 P50/P95/P99 延迟分位数
-- **Token 分布** — 按角色（system / user / tool / output）分解用量占比
-- **成本追踪** — 按模型实时显示请求成本（需 provider 返回计费数据）
-- **错误率统计** — 识别并统计失败请求，实时计算错误率
-- **`/usage` 命令** — HTML 报告 → JSON 导出 → 文本报告 → 设置
-- **HTML 报告** — 交互式 ECharts 仪表盘：Token 趋势、性能对比、TPS 排名、错误率分析，自动在浏览器打开
-- **持久化统计** — 性能指标永久累积写入独立文件，历史数据不受会话重置影响
-- **多级折叠** — 面板、模型、子区块均可折叠，状态持久化
-- **语言切换** — 中英双语，跟随系统或手动切换
+## 主要特性
 
-## 安装
+- **侧边栏实时看板**：会话中随时查看各模型的输入输出Token、预估花费、缓存命中率，以及当前会话的平均首字延迟与生成速率。
+- **缓存命中率与趋势**：按模型追踪缓存利用效率，用箭头标注近几次请求的命中率是在上升还是下降。
+- **Token构成归类**：自动将Token按系统提示词、用户输入、工具调用和模型输出分别统计，清楚定位上下文占用大头。
+- **交互式用量报告**：在终端输入 `/usage` 即可在浏览器中打开ECharts 交互仪表盘，查看历史用量趋势、模型横向对比与失败请求统计；也可一键导出为JSON或Markdown文件。
+- **双版本无缝适配**：同时兼容 OpenCode 1.x 与 OpenCode 2（beta），自动识别宿主环境，无需手动切换或调整配置。
+
+---
+
+## 安装与配置
+
+### 1. 安装
+
+在项目中运行：
 
 ```sh
 npm install opencode-tokenwatch
 ```
 
-在 `opencode.json` 或 `opencode.jsonc` 中添加：
+### 2. 启用插件
+
+在配置文件 `opencode.json`（或 `opencode.jsonc`）中添加插件项：
 
 ```json
 {
@@ -35,38 +39,26 @@ npm install opencode-tokenwatch
 }
 ```
 
-## 配置
+重新打开 OpenCode，侧边栏便会自动载入 TokenWatch 面板。
 
-在 OpenCode TUI 中输入 `/usage` → **设置**，可交互式开关各显示项和切换界面语言，配置自动持久化，无需手动编辑配置文件。
+---
 
-## 用法
+## 常用操作
 
-在 OpenCode TUI 中输入 `/usage`，选择：
+在终端对话框中输入 `/usage` 即可唤出操作菜单：
 
-- **HTML 报告** — 选择日期范围，生成仪表盘并在浏览器打开
-- **JSON 导出** — 导出完整用量数据至 `~/.opencode/reports/`
-- **文本报告** — 导出 Markdown 格式至 `~/.opencode/reports/`
-- **设置** — 开关侧边栏显示项、切换语言
+- **HTML 报告**：选择统计日期范围，在默认浏览器中打开交互式图表。
+- **导出数据**：导出结构化 JSON 或 Markdown 报告，默认保存在 `~/.opencode/reports/` 目录下。
+- **设置**：在弹出的交互菜单中开关各个显示区块或切换中英文显示。改动会自动保存，不需要手动修改配置文件。
 
-## 数据文件
-
-| 文件 | 路径 | 说明 |
-|------|------|------|
-| JSONL 日志 | `~/.opencode/tokenwatch.jsonl` | 原始请求日志 |
-| 聚合统计 | `~/.opencode/tokenwatch-stats.json` | 持久化性能统计 |
-| 报告输出 | `~/.opencode/reports/` | HTML / JSON / Markdown 报告 |
+---
 
 ## 系统要求
 
-- OpenCode CLI（支持 `opencode db` 命令）
-- Node.js 18+
+- **OpenCode CLI**：1.18+ 或 OpenCode 2（`@opencode-ai/cli@beta`）
+- **Node.js**：≥ 18.0.0
 
-## 构建
-
-```sh
-npm install
-npm run build
-```
+---
 
 ## 相关项目
 
@@ -74,6 +66,8 @@ npm run build
 - [opencode-visual-cache](https://github.com/Hotakus/opencode-visual-cache) — TUI 侧边栏缓存命中率可视化，Token 分布分析
 - [magic-context](https://github.com/cortexkit/magic-context/) — 缓存感知的无限上下文 + 跨会话记忆系统
 
-## 许可
+---
+
+## 协议
 
 MIT

package/dist/host/command-actions.d.ts

@@ -0,0 +1,20 @@
+import type { HostAdapter } from "./types.js";
+import type { SidebarConfig, SidebarToggleKey } from "../kernel/config.js";
+import type { UsageFilters } from "../kernel/format.js";
+export interface CommandActions {
+    htmlReport(filters?: UsageFilters, presetTag?: string): Promise<void>;
+    jsonExport(): Promise<void>;
+    textReport(): Promise<void>;
+    config(): SidebarConfig;
+    toggle(key: SidebarToggleKey): SidebarConfig;
+    setLanguage(language: SidebarConfig["language"]): SidebarConfig;
+}
+export declare function createCommandActions(host: HostAdapter): CommandActions;
+/** 报告时间范围预设，供两代宿主菜单共用 */
+export interface RangePreset {
+    readonly id: string;
+    readonly label: string;
+    readonly tag: string;
+    readonly filters: UsageFilters;
+}
+export declare function rangePresets(): RangePreset[];

package/dist/host/runtime.d.ts

@@ -0,0 +1,7 @@
+import type { HostAdapter } from "./types.js";
+/**
+ * 启动 TokenWatch 共享核心，返回卸载函数。
+ *
+ * 事件 → 聚合/持久化/性能追踪 → 侧边栏渲染 的整条链路在此装配。
+ */
+export declare function startTokenWatch(host: HostAdapter): () => void;

package/dist/host/types.d.ts

@@ -0,0 +1,148 @@
+/**
+ * 宿主无关的能力契约。
+ *
+ * v1（opencode 1.x，TuiPluginApi）与 v2（opencode2，Plugin Context）在
+ * 事件模型、插槽命名、主题结构、命令注册、存储 API 上全都不同。
+ * 本文件定义两者共同能力的交集，由各自的 adapter 负责映射。
+ *
+ * 上层 UI / 命令逻辑只依赖本接口，因此可以在两代宿主间完全复用。
+ */
+import type { RGBA } from "@opentui/core";
+import type { JSX } from "@opentui/solid";
+import type { UsageFilters, UsageReport } from "../kernel/format.js";
+export type HostKind = "v1" | "v2";
+/** 归一化主题色。v1 扁平、v2 嵌套，由 adapter 各自映射。 */
+export interface ThemeColors {
+    readonly primary: RGBA;
+    readonly text: RGBA;
+    readonly textMuted: RGBA;
+    readonly background: RGBA;
+    readonly border: RGBA;
+    readonly success: RGBA;
+    readonly warning: RGBA;
+    readonly error: RGBA;
+}
+/** 归一化消息事件（由两代各自的事件形状折叠而来） */
+export interface NormalizedMessageEvent {
+    readonly messageID: string;
+    readonly sessionID: string;
+    readonly role: string;
+    readonly providerID: string;
+    readonly modelID: string;
+    readonly input: number;
+    readonly output: number;
+    readonly reasoning: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly total: number;
+    readonly cost: number;
+    /** 请求开始时间（epoch ms），供性能追踪计算延迟/TPS */
+    readonly timeCreated?: number;
+    /** 请求完成时间（epoch ms），缺失时性能追踪跳过该样本 */
+    readonly timeCompleted?: number;
+    /** 原始事件对象，供性能追踪器读取时间戳等宿主专属字段 */
+    readonly raw: any;
+}
+/** 归一化 part 事件（用于 TTFT 计时） */
+export interface NormalizedPartEvent {
+    readonly messageID?: string;
+    readonly type?: string;
+    readonly text?: string;
+    readonly timeStart?: number;
+    readonly raw: any;
+}
+export interface HostEventHandlers {
+    onMessageUpdated(event: NormalizedMessageEvent): void;
+    onPartUpdated(event: NormalizedPartEvent): void;
+    /** 消息被删除 / 会话数据失效，UI 应重算 */
+    onInvalidate(): void;
+}
+/** 侧边栏渲染入参（归一化：两代宿主都提供 sessionID） */
+export interface SidebarInput {
+    readonly sessionID: string;
+}
+/** 键值存储（配置与折叠状态） */
+export interface KeyValueStore {
+    get<T>(key: string, fallback: T): T;
+    set<T>(key: string, value: T): void;
+    /** 删除条目；v1 宿主可能不提供（调用方需判空），用于会话消息 KV 的淘汰 */
+    delete?(key: string): void;
+}
+export interface CommandSpec {
+    readonly id: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly category?: string;
+    /** 斜杠命令名（不含前导斜杠） */
+    readonly slash?: string;
+    readonly run: () => void | Promise<void>;
+}
+export interface SelectOption<Value> {
+    readonly title: string;
+    readonly value: Value;
+    readonly description?: string;
+}
+export type NotifyVariant = "info" | "success" | "warning" | "error";
+/**
+ * 历史用量数据源。
+ *
+ * v1 通过 `opencode db` 执行 SQL（快、功能完整）；
+ * v2 移除了 db 子命令，只能在客户端遍历会话消息重算（慢、需要缓存与进度提示）。
+ */
+export interface UsageDataSource {
+    readonly kind: "sql" | "client-scan";
+    /**
+     * 首次取数是否需要显著耗时。
+     * v2 为 true —— 宿主应在调用前提示用户。
+     */
+    readonly needsFirstRunNotice: boolean;
+    /**
+     * 本次取数是否会触发冷启动全量扫描。
+     * SQL 数据源恒为 false；client-scan 在缓存为空时返回 true。
+     */
+    readonly isCold: () => boolean;
+    getUsageReport(filters: UsageFilters): Promise<UsageReport>;
+}
+/** 宿主能力统一抽象 */
+export interface HostAdapter {
+    readonly kind: HostKind;
+    /** 宿主版本号，用于诊断与报告元信息 */
+    readonly hostVersion: string;
+    theme(): ThemeColors;
+    store: KeyValueStore;
+    /** 订阅事件，返回取消订阅函数 */
+    subscribe(handlers: HostEventHandlers): () => void;
+    /** 挂载侧边栏 UI，返回卸载函数 */
+    registerSidebar(render: (input: SidebarInput) => JSX.Element): () => void;
+    /**
+     * 注册命令，返回注销函数。
+     * v1 经由 host/v1/commands.tsx 用原生 DialogSelect 实现菜单，不走此方法。
+     */
+    registerCommands?(specs: readonly CommandSpec[]): () => void;
+    notify(message: string, variant?: NotifyVariant): void;
+    alert(input: {
+        title: string;
+        message: string;
+    }): Promise<void>;
+    select<Value>(input: {
+        title: string;
+        options: readonly SelectOption<Value>[];
+    }): Promise<Value | undefined>;
+    /** 宿主退出 / 插件卸载时调用 */
+    onDispose(fn: () => void): void;
+    /** 当前会话消息列表（用于侧边栏 token 分布估算与历史重建） */
+    sessionMessages(sessionID: string): readonly any[];
+    /**
+     * 指定消息的 part 列表，归一化到 v1 part 形状。
+     *
+     * v1 需要二次查询 `api.state.part(id)`（会话无关，sessionID 忽略）；
+     * v2 传入 sessionID 时走 O(1) 的 `message.get(sessionID, id)`，
+     * 避免跨全部会话线性扫描。
+     */
+    messageParts(messageID: string, sessionID?: string): readonly any[];
+    /** 宿主应用配置（读取 agent prompt 用于 system token 估算） */
+    appConfig(): Record<string, unknown>;
+    /** 订阅 part 级更新（用于 token 分布重算），返回取消订阅函数 */
+    onPartUpdated(handler: () => void): () => void;
+    readonly dataSource: UsageDataSource;
+}

package/dist/host/v1/adapter.d.ts

@@ -0,0 +1,9 @@
+/** @jsxImportSource @opentui/solid */
+/**
+ * v1 宿主适配层：把 opencode 1.x 的 `TuiPluginApi` 折叠为统一 `HostAdapter`。
+ */
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+import type { HostAdapter, KeyValueStore } from "../types.js";
+/** v1 kv 的 KeyValueStore 折叠（v1/commands.tsx 复用同一份，避免两套实现漂移） */
+export declare function makeStore(api: TuiPluginApi): KeyValueStore;
+export declare function createV1Adapter(api: TuiPluginApi): HostAdapter;

package/dist/host/v1/commands.d.ts

@@ -0,0 +1,9 @@
+/** @jsxImportSource @opentui/solid */
+/**
+ * v1 命令注册 —— /usage 菜单（HTML 报告 / JSON 导出 / 文本报告 / 设置）。
+ *
+ * v1 拥有原生 DialogSelect 对话栈，UX 优于通用 select，因此菜单在此原生实现；
+ * 实际动作（取数、装配、落盘、打开）全部委托内核层，与 v2 行为一致。
+ */
+import type { TuiPluginApi } from "@opencode-ai/plugin/tui";
+export declare function registerCommands(api: TuiPluginApi): Promise<void>;

package/dist/{queries.d.ts → host/v1/data-source.d.ts}

@@ -1,14 +1,9 @@
-import type { DailyBreakdownItem, ErrorStats, ModelBreakdownItem, ProviderBreakdownItem, SessionBreakdownItem, SessionTokenData, UsageFilters, UsageReport } from "./formatter.js";
+import type { DailyBreakdownItem, ErrorStats, ModelBreakdownItem, ProviderBreakdownItem, SessionBreakdownItem, SessionTokenData, UsageFilters, UsageReport } from "../../kernel/format.js";
 export declare function getPresetRange(preset: "all" | "7d" | "30d" | "month"): Pick<UsageFilters, "startDate" | "endDate">;
-export declare function getCurrentSessionStats(sessionId?: string): Promise<SessionTokenData>;
 export declare function getSummary(filters?: UsageFilters): Promise<SessionTokenData>;
 export declare function getModelBreakdown(filters?: UsageFilters): Promise<ModelBreakdownItem[]>;
 export declare function getProviderBreakdown(filters?: UsageFilters): Promise<ProviderBreakdownItem[]>;
 export declare function getDailyBreakdown(filters?: UsageFilters): Promise<DailyBreakdownItem[]>;
 export declare function getSessionBreakdown(filters?: UsageFilters): Promise<SessionBreakdownItem[]>;
-export declare function getAvailableModels(): Promise<string[]>;
-export declare function getAvailableProviders(): Promise<string[]>;
-/** 失败请求计数 SQL。1次运行获取成功数＋失败数＋按模型细分 */
 export declare function getErrorStats(filters?: UsageFilters): Promise<ErrorStats>;
 export declare function getUsageReport(filters?: UsageFilters): Promise<UsageReport>;
-export declare function exportReportAsCsv(report: UsageReport, section: "models" | "providers" | "daily" | "sessions"): string;

package/dist/host/v2/adapter.d.ts

@@ -0,0 +1,63 @@
+import type { HostAdapter } from "../types.js";
+/** v2 插件 Context 的最小结构约束（避免对 beta SDK 的硬类型依赖） */
+export interface V2Context {
+    readonly app: {
+        readonly version: string;
+        readonly channel: string;
+    };
+    readonly theme: any;
+    readonly themeMode: "dark" | "light";
+    readonly data: {
+        readonly on: (type: string, handler: (event: any) => void) => () => void;
+        readonly session: {
+            list(): any[];
+            get(sessionID: string): any | undefined;
+            readonly message: {
+                list(sessionID: string): any[];
+                get(sessionID: string, messageID: string): any | undefined;
+                sync(sessionID: string): Promise<void>;
+                invalidate(sessionID: string): void;
+            };
+            sync(sessionID: string): Promise<void>;
+        };
+        readonly location: {
+            readonly agent: {
+                list(location?: any): any[] | undefined;
+            };
+        };
+    };
+    readonly ui: {
+        readonly slot: (claim: any) => () => void;
+        readonly toast: {
+            show(options: {
+                message: string;
+                variant?: string;
+                title?: string;
+            }): void;
+        };
+        readonly dialog: {
+            alert(options: {
+                title: string;
+                message: string;
+            }): Promise<void>;
+            select<Value>(options: {
+                title: string;
+                options: readonly {
+                    title: string;
+                    value: Value;
+                    description?: string;
+                }[];
+            }): Promise<Value | undefined>;
+        };
+    };
+    readonly keymap: {
+        layer(input: () => any): void;
+    };
+    readonly storage: {
+        store<Value extends object>(key: string, options: {
+            readonly initial: Value;
+        }): readonly [any, (m: (draft: Value) => void) => Promise<void>];
+    };
+    readonly client: any;
+}
+export declare function createV2Adapter(ctx: V2Context, dispose: Set<() => void>): HostAdapter;

package/dist/host/v2/commands.d.ts

@@ -0,0 +1,8 @@
+/**
+ * v2 命令注册 —— 通过 keymap.layer 暴露 /usage 斜杠命令与面板命令。
+ *
+ * 菜单用宿主通用 `dialog.select` 实现（v2 无 DialogSelect 对话栈），
+ * 动作复用两代共享的 command-actions，行为与 v1 菜单一致。
+ */
+import type { HostAdapter } from "../types.js";
+export declare function registerV2Commands(host: HostAdapter): void;

package/dist/host/v2/data-source.d.ts

@@ -0,0 +1,26 @@
+/**
+ * v2 历史用量数据源 —— 客户端遍历重算。
+ *
+ * v2 移除了 `opencode db` 子命令，无法再用 SQL 聚合。这里改为：
+ * 1. `session.list()` 拿到全部会话（自带 tokens/cost，可快速出总数）
+ * 2. 逐会话 `message.list()` 遍历 assistant 消息，按模型 / 供应商 / 日期分解
+ *
+ * 第 2 步是 O(会话数 × 消息数) 的冷启动开销，因此：
+ * - 首次执行前由调用方提示用户（见 `UsageDataSource.needsFirstRunNotice`）
+ * - 结果缓存在内存中，同一 TUI 会话内不重复扫描
+ * - 每个会话只同步一次，并把让步交给事件循环，避免长时间阻塞渲染
+ */
+import type { UsageFilters, UsageReport } from "../../kernel/format.js";
+/**
+ * 取用量报告（stale-while-revalidate）。
+ *
+ * - 冷启动（无缓存）：等待全量扫描完成（调用方已先提示用户）。
+ * - 缓存可用且数据有更新（markUsageCacheDirty）：立即返回旧快照，
+ *   同时后台重建 —— 本次报告不卡顿，下次打开即为新数据。
+ * - 缓存可用且无更新：直接返回。
+ */
+export declare function getUsageReport(ctx: any, filters?: UsageFilters): Promise<UsageReport>;
+/** 有新数据落库（如 session.idle）时由适配层调用：下次取数触发后台重建 */
+export declare function markUsageCacheDirty(): void;
+/** 供命令层判断本次调用是否会触发冷启动扫描 */
+export declare function isUsageCacheCold(): boolean;

package/dist/kernel/config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 侧边栏配置 —— 宿主无关的持久化设置。
+ *
+ * 读写只依赖 `KeyValueStore`（v1 的 kv / v2 的 storage.store 在各自 adapter 中折叠），
+ * 因此设置项在两代宿主间行为完全一致。
+ */
+import type { KeyValueStore } from "../host/types.js";
+export interface SidebarConfig {
+    sidebar: {
+        showPerformance: boolean;
+        showPricing: boolean;
+        showTokenDistribution: boolean;
+        showTrend: boolean;
+    };
+    language: "zh" | "en" | "auto";
+}
+export type SidebarToggleKey = keyof SidebarConfig["sidebar"];
+export declare const DEFAULT_CONFIG: SidebarConfig;
+/**
+ * 读取配置：默认值 ← 插件配置（opencode.json）← 运行时覆盖（设置菜单）。
+ * `pluginConfig` 为宿主声明式配置，v1 读 `state.config`，v2 暂无等价物。
+ */
+export declare function loadConfig(store: KeyValueStore, pluginConfig?: Record<string, any>): SidebarConfig;
+export declare function saveConfig(store: KeyValueStore, cfg: SidebarConfig): void;
+/**
+ * 递增配置版本号。
+ *
+ * 侧边栏用轮询版本号的方式感知"设置在别处被改了"，
+ * 因为 v1 的 kv 不是响应式的。
+ */
+export declare function bumpVersion(store: KeyValueStore): void;
+export declare function toggleSidebarSetting(store: KeyValueStore, key: SidebarToggleKey): SidebarConfig;
+export declare function setLanguageSetting(store: KeyValueStore, language: SidebarConfig["language"]): SidebarConfig;

package/dist/{formatter.d.ts → kernel/format.d.ts}

@@ -73,7 +73,7 @@ export interface ErrorStats {
     successCount: number;
     /** 失败请求数（tokens.total == 0 的 assistant） */
     failedCount: number;
-    /** 失败率：failedCount / (successCount + failedCount) */
+    /** 失败率：failedCount / (successCount + failedCount)，小数口径（0~1），两代宿主一致 */
     errorRate: number;
     /** 按模型细化的失败数 */
     byModel: Array<{
@@ -91,6 +91,8 @@ export interface UsageReport {
     daily: DailyBreakdownItem[];
     sessions: SessionBreakdownItem[];
     errors?: ErrorStats;
+    /** daily 明细被数据源截断（未覆盖全部日期）时为 true，报告 UI 据此提示 */
+    dailyTruncated?: boolean;
 }
 export declare function formatTokens(n: number): string;
 export declare function formatCost(n: number): string;
@@ -145,15 +147,10 @@ export interface ModelPerfStats {
     p99Latency: number | null;
     /** 该模型加权缓存命中率：cacheRead / (cacheRead + input) */
     cacheHitRate: number | null;
-}
-export interface TokenDistribution {
-    system: number;
-    user: number;
-    agent: number;
-    toolCall: number;
-    toolResult: number;
-    output: number;
-    total: number;
+    /** 最近一次请求的 TTFT / TPS / 端到端延迟（与宿主单次口径可直接对照） */
+    lastTTFT: number | null;
+    lastTPS: number | null;
+    lastLatency: number | null;
 }
 export interface LogEntry {
     ts: string;
@@ -187,4 +184,6 @@ export interface CombinedReportData {
     perfLogs: LogEntry[];
     perfSummary: ModelPerfStats[];
     meta: HtmlReportMeta;
+    /** daily 明细被数据源截断时为 true（来自 UsageReport），报告时间线区据此提示 */
+    dailyTruncated?: boolean;
 }

package/dist/kernel/model.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 会话内单条 assistant 消息的归一化内存模型。
+ *
+ * v1 来自 `message.updated` 事件（`info.tokens.{input,output,reasoning,cache}`）；
+ * v2 来自 `SessionMessageAssistant.tokens`（`{input,output,reasoning,cache:{read,write}}`）。
+ * 两者在各自的 adapter 中折叠为本类型，后续所有聚合逻辑只认这一份结构。
+ */
+export interface TokenMessage {
+    id: string;
+    sessionID: string;
+    providerID: string;
+    modelID: string;
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+}