opencode-cache-hit 0.1.0 → 0.2.1

package/docs/en/design.md

@@ -43,8 +43,8 @@ flowchart TB
 ## Cost model
 
 - OpenCode: `msg.cost` accumulates assistant messages using **USD** list prices from `opencode.json`.
-- Plugin: `createCostFormatter(loadPluginConfig().cost)`; default `costUnit: USD` → `currency: CNY`, `rate: 7.2`.
-- Config file: `cache-hit.config.json` at plugin root (`load-config.ts`); defaults in `plugin-config.ts`.
+- Plugin: `createCostFormatter(loadPluginConfig().cost)`; default `costUnit: USD` → `currency: CNY`, `rate: 6.77`.
+- Config file: `~/.config/opencode/cache-hit.json` (preferred) or `cache-hit.config.json` at plugin root (legacy). Defaults in `plugin-config.ts`.
 
 ## Runtime architecture
 
@@ -57,8 +57,8 @@ sequenceDiagram
 
   Slot->>Host: sessionId, display, api
   Host->>API: session.list → childIds
-  API-->>Host: message.updated
-  Host->>Host: refreshTick++
+  API-->>Host: message.updated { info: Message }
+  Host->>Host: refreshTick++, timeline.handleMessage(info)
   Host->>API: session.messages(sid / cid)
   Host->>W: main, messages, subAgents
   W->>W: aggregate / format / TuiPanel
@@ -77,6 +77,7 @@ sequenceDiagram
 | `stats.ts` | Pure aggregation (no UI) |
 | `session-list.ts` | Parse `session.list`, `childSessionIdsForParent` |
 | `format-cost.ts` / `format-tokens.ts` / `format-cache-ui.ts` | Display formatting (`computeHitBarWidth` lives in `tui-panel/layout.ts`) |
+| `format-model.ts` | Sub-agent row label (`formatSubAgentLabel`) and vendor brand colors (`modelRowColor`) |
 | `message-timing.ts` | SDK time fields |
 | `timeline/` | Per-call JSONL (`records` / `writer` / `collector`) |
 | `plugin-config.ts` / `load-config.ts` | Config normalization |
@@ -88,9 +89,9 @@ Reusable **page** skeleton aligned with visual-cache (layout, colors, foldable s
 | Module | Role |
 |--------|------|
 | `layout.ts` | Column widths, `justifyRow`, `computeHitBarWidth`, separators |
-| `palette.ts` | Theme → panel palette |
+| `palette.ts` | Theme → panel palette; `toneBrandHex` for vendor colors on dark panels |
 | `use-panel-layout.ts` | `createPanelLayout`, `createSectionFold` |
-| `components.tsx` | `TuiPanel`, `TuiHitRow`, `TuiMetricRow`, … (`@opentui/solid`) |
+| `components.tsx` | `TuiPanel`, `TuiHitRow`, `TuiMetricRow` (`labelFg` / `valueFg` split colors), … (`@opentui/solid`) |
 | `index.ts` | Barrel export |
 
 Import `layout.ts` / `palette.ts` directly from non-JSX code (e.g. `use-cache-hit-metrics`) so `bun test` smoke tests do not pull JSX.
@@ -130,6 +131,23 @@ flowchart TD
 
 The UI shows `agentsScopeHint` (“sub-sessions only”). This complements visual-cache’s main-session view—it is not a missing-aggregation bug.
 
+### Sub-agent row display
+
+When multiple child sessions run in parallel, each active sub-agent gets a metric row under **Agents** (see screenshot `docs/assets/cache-hit-panel.v3.png`).
+
+| Aspect | Behavior |
+|--------|----------|
+| **Purpose** | Distinguish which child session and which model in a narrow sidebar |
+| **Label text** | `{displayModelName} …{sessionIdTail}` — same naming rules as the main **Model** row (`shortModelName` + date-suffix strip); **no** semantic nicknames (`ds-flash`, etc.) |
+| **Truncation** | `gauge` ≈ measured panel width − border gutter; label budget subtracts right-side cost/tokens. Prefer keeping the **model prefix**; shrink ID tail (6 → 4 chars) before dropping the tail |
+| **Label color** | Approximate **vendor brand** hex (`MODEL_BRAND_HEX` in `format-model.ts`), passed through `toneBrandHex` for legibility on dark terminals |
+| **Value color** | `muted` — separate from label so row cost is not confused with Agents total **Cost** (`success` green) |
+| **Family match** | `MODEL_FAMILY_RULES` (claude, deepseek, openai, gemini, qwen, glm, kimi, minimax, grok, mimo, meta, mistral); matching is **case-insensitive** on model slug and `providerID` |
+| **Unknown models** | Stable hash → neutral fallback hues (never `success`) |
+| **Config** | No `cache-hit.json` keys in v1; extend `MODEL_FAMILY_RULES` / `MODEL_BRAND_HEX` in code |
+
+Implementation: `agents-view.tsx` calls `formatSubAgentLabel` + `modelRowColor`; `TuiMetricRow` uses `labelFg` / `valueFg`.
+
 ## Aggregation and refresh
 
 ### When values recompute
@@ -184,9 +202,13 @@ Sum input and cache.read over assistant messages
 - `computePerCallHitTrend`: one rate per assistant turn; skip `summary: true`.
 - Display the **last** non-summary turn; compare to previous for ↑ / ↓ / `-`.
 
-**Combined Hit**
+**Pricing & Saved**
 
-- Shown only when main block is visible, sub-agents exist, and combined vs session total differs by ≥ 0.05%.
+- Provider pricing is read from `api.state.provider` (SDK runtime data, not hardcoded).
+- `computePricing` looks up per-million rates by `providerID` + `modelID`; computes `saved = (inputRate - cacheReadRate) * cacheRead / 1M`.
+- Main session: **Saved** row in Detail section; per-million rates (`/M in`, `/M cache`, `/M out`) in Model section.
+- Agents section: **Saved** row sums savings across all child sessions (`computeSubsSaved`).
+- All pricing rows hidden when rates are unavailable or saved is zero.
 
 ## Time fields (OpenCode SDK v2)
 

package/docs/en/timeline-duplicate-writes.md

@@ -0,0 +1,125 @@
+# Timeline Duplicate Writes: Analysis and Fix
+
+## Overview
+
+Restarting OpenCode used to cause previously-written timeline records to be re-appended to JSONL log files, creating duplicates. **Impact**: 2,727 duplicate records found across 1,218 unique message keys in production logs.
+
+The fix eliminates polling entirely — using `message.updated` events as the data source instead of `api.state.session.messages()`.
+
+## Root Cause
+
+The OpenCode TUI plugin API has two data access patterns:
+
+| API | Behavior |
+|-----|----------|
+| `api.state.session.messages(sessionId)` | Returns **all** messages — no cursor, `since`, or limit |
+| `api.event.on("message.updated", handler)` | Fires per-message, carries the **full `Message` object** (cost, tokens, time, modelID, providerID) — see [`types.gen.ts` L1064](https://github.com/anomalyco/opencode/blob/dev/packages/sdk/js/src/v2/gen/types.gen.ts#L1064) |
+
+The original collector used the **polling path**: subscribe to `message.updated` → call `schedule()` (500ms debounce) → `collectNow()` → `getMessages()` (full history) → `buildCallRecords()` (all messages) → `shouldFlushToDisk()` (dedup filter). This required a `flushedKeys` Set to skip already-written records.
+
+On restart, `flushedKeys` was lost (it lived in memory only). Every message in the session would be re-flushed to JSONL. A startup scan of all JSONL files was proposed to rebuild the set, adding complexity without addressing the core issue: **polling is the wrong pattern for a write-only log**.
+
+## Solution: Event-Driven Collection
+
+The `message.updated` event fires once per message with the complete `Message` object. The collector subscribes to events directly — no polling, no dedup, no startup scan.
+
+```
+message.updated({ sessionID, info: Message })
+       ↓
+handleMessage(sessionID, info)
+       ↓
+if (assistant && complete) → assistantMessageToRecord → appendFile
+```
+
+### Implementation
+
+**`collector.ts`** — `handleMessage(sessionID, msg)`:
+
+- Determines scope (`main` / `child`) by comparing `sessionID` against root and child IDs
+- Skips non-assistant, incomplete (unless `flushIncomplete`), and summary messages (per config)
+- Converts to `LlmCallRecord` via `assistantMessageToRecord`
+- Writes immediately via `appendTimelineRecord` (fire-and-forget)
+- Maintains a bounded in-memory cache (`memoryRecords`)
+
+**`sidebar-host.tsx`** — event wiring:
+
+```typescript
+const timeline = createTimelineCollector({
+  config: props.timeline,
+  getRootSessionId: () => props.sessionId,
+  getChildIds: childIds,
+})
+
+props.api.event.on("message.updated", (event) => {
+  const sid = event.properties?.info?.sessionID
+  if (sid && event.properties?.info) {
+    timeline.handleMessage(sid, event.properties.info as AssistantMessage)
+  }
+})
+```
+
+### Key Properties
+
+- **No polling**: Zero calls to `getMessages()`. Events drive all writes.
+- **No dedup**: Each `message.updated` fires once per message. No `flushedKeys` Set, no JSONL scanning.
+- **No startup scan**: The collector is stateless between restarts. Messages written before startup were already logged.
+- **Concurrent-safe by design**: Each event is an independent append. `appendFile` uses `O_APPEND` — records (~300 bytes) are well under the 4KB `PIPE_BUF` atomic threshold.
+- **Purge unchanged**: `maxAgeDays` / `maxLogFiles` / `maxLinesPerFile` / `rotateMaxBytes` still run as before on collector construction and per-write.
+
+### What #27663 means (and doesn't mean)
+
+[Issue #27663](https://github.com/anomalyco/opencode/issues/27663) reports that `message.part.delta` (a **BusEvent**) is lost on the second `prompt_async` call. This does **not** affect the collector — `message.updated` is a **SyncEvent**, which the issue explicitly confirms is delivered correctly.
+
+## Performance
+
+No startup cost. No memory overhead beyond the in-memory record cache (`maxMemoryRows`, default 50). No per-message IO beyond the JSONL append itself.
+
+## Limitations
+
+Events are forward-only: messages existing before plugin load are not replayed. This is intentional — they were already written to JSONL during the previous session.
+
+When `flushIncomplete` is enabled, a record written before completion will not be updated later. This is the same behavior as before and is documented in the config schema.
+
+## Upstream Context (as of 2026-06-02)
+
+| Issue/PR | Relevance |
+|----------|-----------|
+| [PR #8535](https://github.com/anomalyco/opencode/pull/8535) — TUI paginated message loading | Open (conflicts). Adds cursor-based pagination to TUI internals. Does not expose pagination to plugin API. |
+| [Issue #6548](https://github.com/anomalyco/opencode/issues/6548) — Paginated message loading feature request | Open. Discussion spawned PR #8535. Plugin API not mentioned. |
+| [Issue #27663](https://github.com/anomalyco/opencode/issues/27663) — `message.part.delta` lost on second `prompt_async` | Open (v1.15.6). Affects BusEvents only; SyncEvents (`message.updated`) confirmed working. |
+| [Issue #26097](https://github.com/anomalyco/opencode/issues/26097) — Plugin API: session projection adapters | Open. Session-level extensions, not message-level. |
+
+No issue or PR proposes `messages(since)` for the plugin API. The `message.updated` event already carries full message data — this capability was underutilized by plugins.
+
+### Ecosystem Patterns
+
+| Plugin | Strategy | Dedup? |
+|--------|----------|--------|
+| [opencode-visual-cache](https://github.com/Hotakus/opencode-visual-cache) | SolidJS `createEffect` — reactive full recompute | None |
+| [opencode-usage](https://github.com/cosmiclasagnadev/opencode-usage) | Per-session reconciliation — clear and rebuild | None |
+| **opencode-cache-hit** (this plugin) | Memory stats: `createMemo` full recompute | None |
+| | Timeline writes: event-driven via `handleMessage` | None needed |
+
+### Reference Implementations
+
+| Project | Pattern |
+|---------|---------|
+| OpenCode TUI `sync.tsx` | `message.updated` → `reconcile(info)` → update store |
+| [DanWahlin/agent-sdk-core](https://github.com/DanWahlin/agent-sdk-core) | SSE `client.event.subscribe()` → per-event handler |
+| [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) | `client.event.subscribe()` + `client.session.messages()` hybrid |
+
+## Alternatives Considered
+
+| Approach | Verdict |
+|----------|---------|
+| **Poll + `flushedKeys` Set (memory only)** | Original approach. Restart loses state → duplicates. |
+| **Poll + JSONL startup scan** | Implemented on `fix/timeline-dedup-scan-jsonl`. Works correctly but adds scan logic for a problem that shouldn't exist. |
+| **Separate `.flushed-keys` file** | Extra state file, extra IO per write, must sync with purge. |
+| **Event-driven (current)** | `message.updated` carries full message. No polling, no dedup, no scan. ✅ |
+
+## References
+
+- Linux `open(2)` man page — `O_APPEND` semantics
+- Node.js `fs.appendFile` — uses `O_APPEND` internally
+- `PIPE_BUF` — POSIX guarantee for atomic writes (4096 bytes on Linux)
+- [OpenCode SDK types: `message.updated` event](https://github.com/anomalyco/opencode/blob/dev/packages/sdk/js/src/v2/gen/types.gen.ts#L1064)

package/docs/en/timeline.md

@@ -36,14 +36,14 @@ flowchart LR
 ```typescript
 export type LlmCallRecord = {
   schema: 1
-  recordedAt: number       // local write time (ms)
+  recordedAt: string       // ISO 8601 with local timezone offset
   sessionId: string
   rootSessionId: string    // main session; differs for child scope
   scope: "main" | "child"
   messageKey: string
   modelId: string
-  created: number
-  completedAt?: number
+  created: string
+  completedAt?: string
   durationMs?: number
   isComplete: boolean
   input: number
@@ -81,14 +81,14 @@ Module: `src/timeline/records.ts` — `buildCallRecords(sessionId, rootSessionId
 **Default layout**
 
 ```
-~/.config/opencode/plugins/opencode-cache-hit/logs/
+~/.local/share/opencode/logs/cache-hit/
   timeline-2026-05-31.jsonl       # one active file per local calendar day
   timeline-2026-05-31.jsonl.1     # size rotation backup for that day
 ```
 
 All main and child sessions for a day share one file; filter by `rootSessionId` / `sessionId` / `scope`. A new date gets a new filename at midnight.
 
-Optional `dir` (e.g. `~/.local/share/opencode/cache-hit/logs/`).
+Optional `dir` (e.g. `~/my-logs/`). Supports `~/` expansion to home directory.
 
 **Legacy**: older builds used `<rootSessionId>.jsonl` per main session; not migrated automatically.
 
@@ -116,7 +116,7 @@ Example values above; code defaults below (`enabled: false`, rotation `0` except
 | Field | Code default | Description |
 |-------|--------------|-------------|
 | `enabled` | `false` | No IO when off |
-| `dir` | `""` | Empty → plugin `logs/` |
+| `dir` | `""` | Empty → `~/.local/share/opencode/logs/cache-hit` |
 | `flushIncomplete` | `false` | Write only completed turns |
 | `logSummaryMessages` | `true` | Include summary rows (flagged) |
 | `maxMemoryRows` | `50` | In-memory rows for future UI |
@@ -131,7 +131,7 @@ Example values above; code defaults below (`enabled: false`, rotation `0` except
 1. Optional size roll **before** append.
 2. `appendFile` one JSON line.
 3. Optional line trim **after** append.
-4. Async flush in `queueMicrotask`; `flushedKeys` dedupe by `messageKey` (not cleared on session switch; cleared on date change).
+4. Event-driven: `message.updated` → `handleMessage()` → fire-and-forget `appendFile`. No polling, no dedup.
 
 ## Rotation and retention
 
@@ -169,11 +169,11 @@ Does **not** match legacy `ses_*.jsonl` names.
 
 New filename after midnight; previous days remain until cleanup runs.
 
-### Dedup and session switch
+### Collection
 
-- One append per `messageKey` per process (`flushedKeys`).
-- Switching main session: same day file; filter by `rootSessionId`.
-- **Restart** clears `flushedKeys`; completed messages may be written again (no persistent dedupe yet).
+- `message.updated` event carries the full `Message` object. The collector subscribes directly — no polling, no dedup.
+- Switching main session: `resetForRootChange()` clears in-memory cache; events for the new session arrive naturally.
+- Restarts are safe: messages before startup were already written to JSONL in the previous session. No replay, no scan.
 
 ## Runtime wiring
 
@@ -181,27 +181,27 @@ New filename after midnight; previous days remain until cleanup runs.
 sequenceDiagram
   participant E as message.updated
   participant H as sidebar-host
-  participant B as timeline/build
+  participant C as timeline/collector
   participant W as timeline/writer
 
-  E->>H: refreshTick++
-  H->>B: debounce 500ms buildCallRecords
-  alt enabled and complete and not flushed
-    B->>W: append JSONL
+  E->>H: { sessionID, info: Message }
+  H->>C: handleMessage(sessionID, info)
+  alt assistant and complete
+    C->>W: append JSONL (fire-and-forget)
   end
 ```
 
-- Child ids from `child-session-sync` / `session.list`; timeline only reads `messages()`.
-- Debounce 500ms when enabled.
-- Scope: current TUI root session + its children.
+- Child ids from `child-session-sync` / `session.list`; timeline writes main and child sessions from events.
+- No debounce, no polling. Scope: current TUI root session + its children.
 
 ## UI phases
 
 ### Phase 1 — disk only (current)
 
 ```bash
-LOG=~/.config/opencode/plugins/opencode-cache-hit/logs/timeline-$(date +%Y-%m-%d).jsonl
+LOG=~/.local/share/opencode/logs/cache-hit/timeline-$(date +%Y-%m-%d).jsonl
 tail -f "$LOG"
+# time fields are ISO 8601 strings with local timezone (e.g. "2024-05-30T08:00:00.000+08:00")
 jq -r 'select(.rootSessionId=="YOUR_ROOT") | [.created,.scope,.hitPercent,.cost]|@tsv' "$LOG"
 ```
 
@@ -213,8 +213,13 @@ python3 -c "import json,sys; r=[json.loads(x) for x in open(sys.argv[1]) if x.st
 
 bun scripts/plot-hit-rate.ts "$LOG" -o /tmp/hit.svg
 bun scripts/plot-hit-rate.ts "$LOG" --by-root -o /tmp/hit-multi.svg
+
+# interactive HTML dashboard (filters, Chart.js); add --open to launch browser
+bun scripts/timeline-dashboard.ts --open
 ```
 
+Default log dir matches `timeline.dir` in plugin config (`~/.local/share/opencode/logs/cache-hit/`).
+
 ### Phase 2 — sidebar Timeline section (planned)
 
 ### Phase 3 — metric window linkage (planned)
@@ -249,5 +254,5 @@ bun scripts/plot-hit-rate.ts "$LOG" --by-root -o /tmp/hit-multi.svg
 ## Example line
 
 ```json
-{"schema":1,"recordedAt":1717000000000,"sessionId":"sess_main","rootSessionId":"sess_main","scope":"main","messageKey":"sess_main:1716999990000:deepseek/v4","modelId":"deepseek/v4","created":1716999990000,"completedAt":1717000000000,"durationMs":10000,"isComplete":true,"input":1200,"output":80,"reasoning":0,"cacheRead":38000,"cacheWrite":0,"cost":0.012,"hitPercent":96.9,"skippedForHit":false}
+{"schema":1,"recordedAt":"2024-05-30T08:00:00.000+08:00","sessionId":"sess_main","rootSessionId":"sess_main","scope":"main","messageKey":"sess_main:1716999990000:deepseek/v4","modelId":"deepseek/v4","created":"2024-05-30T07:59:50.000+08:00","completedAt":"2024-05-30T08:00:00.000+08:00","durationMs":10000,"isComplete":true,"input":1200,"output":80,"reasoning":0,"cacheRead":38000,"cacheWrite":0,"cost":0.012,"hitPercent":96.9,"skippedForHit":false}
 ```

package/docs/zh-CN/design.md

@@ -43,8 +43,8 @@ flowchart TB
 ## 成本模型
 
 - OpenCode：`msg.cost` = 按 `opencode.json` 中**美元**单价对 assistant 消息累加。
-- 插件：`createCostFormatter(loadPluginConfig().cost)`；默认 `costUnit: USD` → `currency: CNY`，`rate: 7.2`。
-- 配置路径：插件根目录 `cache-hit.config.json`（`load-config.ts`）；缺省见 `plugin-config.ts` 的 `DEFAULT_PLUGIN_CONFIG`。
+- 插件：`createCostFormatter(loadPluginConfig().cost)`；默认 `costUnit: USD` → `currency: CNY`，`rate: 6.77`。
+- 配置路径：优先 `~/.config/opencode/cache-hit.json`，兜底插件根目录 `cache-hit.config.json`。缺省见 `plugin-config.ts` 的 `DEFAULT_PLUGIN_CONFIG`。
 
 ## 运行时架构
 
@@ -57,8 +57,8 @@ sequenceDiagram
 
   Slot->>Host: sessionId, display, api
   Host->>API: session.list → childIds
-  API-->>Host: message.updated
-  Host->>Host: refreshTick++
+  API-->>Host: message.updated { info: Message }
+  Host->>Host: refreshTick++, timeline.handleMessage(info)
   Host->>API: session.messages(sid / cid)
   Host->>W: main, messages, subAgents
   W->>W: aggregate / format / TuiPanel
@@ -77,6 +77,7 @@ sequenceDiagram
 | `stats.ts` | 纯函数聚合（无 UI） |
 | `session-list.ts` | `session.list` 响应解析、`childSessionIdsForParent` |
 | `format-cost.ts` / `format-tokens.ts` / `format-cache-ui.ts` | 展示格式化（**不含** `computeHitBarWidth`，其在 `tui-panel/layout.ts`） |
+| `format-model.ts` | 子 agent 行 label（`formatSubAgentLabel`）与厂商品牌色（`modelRowColor`） |
 | `message-timing.ts` | SDK 时间字段辅助 |
 | `timeline/` | 按次 JSONL（`records` / `writer` / `collector`） |
 | `plugin-config.ts` / `load-config.ts` | 配置归一化与默认值 |
@@ -88,9 +89,9 @@ sequenceDiagram
 | 模块 | 职责 |
 |------|------|
 | `layout.ts` | 视觉列宽、`justifyRow`、`computeHitBarWidth`、分隔线 |
-| `palette.ts` | 主题色 → 面板调色板 |
+| `palette.ts` | 主题色 → 面板调色板；`toneBrandHex` 用于深色面板上的厂商色 |
 | `use-panel-layout.ts` | `createPanelLayout`（测宽）、`createSectionFold` |
-| `components.tsx` | `TuiPanel`、`TuiHitRow`、`TuiMetricRow` 等（需 `@opentui/solid`） |
+| `components.tsx` | `TuiPanel`、`TuiHitRow`、`TuiMetricRow`（`labelFg` / `valueFg` 分段上色）等（需 `@opentui/solid`） |
 | `index.ts` | 对外 barrel |
 
 纯逻辑模块（如 `use-cache-hit-metrics`）应从 `layout.ts` / `palette.ts` 直接 import，避免经 `index.ts` 拉入 JSX（便于 `bun test` 冒烟）。
@@ -130,6 +131,23 @@ flowchart TD
 
 主 session 若仍有编排类调用，其 token/费用不会出现在 Agents 合计中；UI 通过 `agentsScopeHint`（「仅子会话 / sub-sessions」）标明。与 visual-cache 对主 session 的展示互补，不是漏算 bug。
 
+### 子 session 行展示
+
+多个子 session 并行时，**Agents** 段下每个有活动的子 session 一行（见截图 `docs/assets/cache-hit-panel.v3.png`）。
+
+| 方面 | 行为 |
+|------|------|
+| **目的** | 在窄侧栏中辨认「哪条子 session、用的什么模型」 |
+| **Label 文案** | `{displayModelName} …{sessionIdTail}` — 与主块 **Model** 行同源（`shortModelName` + 去日期尾）；**不做**语义缩写（如 `ds-flash`） |
+| **截断** | `gauge` ≈ 实测面板宽 − 边框 gutter；label 预算再减去右侧 cost/tok。优先保留**模型前缀**；先缩短 ID 尾（6 → 4 字符） |
+| **Label 颜色** | 厂商近似品牌色（`MODEL_BRAND_HEX`，经 `toneBrandHex` 压低饱和度以适配深色终端） |
+| **金额颜色** | `muted`，与 label 分开，避免与 Agents 合计 **Cost** 的 `success` 绿色混淆 |
+| **Family 匹配** | `MODEL_FAMILY_RULES`（claude、deepseek、openai、gemini、qwen、glm、kimi、minimax、grok、mimo、meta、mistral）；模型 slug 与 `providerID` **大小写不敏感** |
+| **未知模型** | 稳定 hash → 中性 fallback 色（不用 `success`） |
+| **配置** | v1 无 `cache-hit.json` 项；在代码中扩展 `MODEL_FAMILY_RULES` / `MODEL_BRAND_HEX` |
+
+实现：`agents-view.tsx` 调用 `formatSubAgentLabel`、`modelRowColor`；`TuiMetricRow` 使用 `labelFg` / `valueFg`。
+
 ## 聚合与刷新
 
 ### 何时重算
@@ -185,9 +203,13 @@ flowchart TD
 - `computePerCallHitTrend(messages)`：每条 assistant 一轮命中率；`summary: true` 跳过。
 - 展示**最后一条**非 summary 轮的命中率；与前一条比较得趋势（↑ / ↓ / `-`）。
 
-**Combined Hit**
+**单价与节省（Pricing & Saved）**
 
-- 存在子 agent 且与会话累计命中率差异 ≥ 0.05% 时显示（主+子合并口径）。
+- Provider 单价从 `api.state.provider`（SDK 运行时数据）读取，非硬编码。
+- `computePricing` 根据 `providerID` + `modelID` 查找百万 token 单价；计算 `saved = (inputRate - cacheReadRate) * cacheRead / 1M`。
+- 主 session：Detail 段展示 **Saved** 行；Model 段展示百万 token 单价（`/M 输入`、`/M 缓存`、`/M 输出`）。
+- Agents 段：**Saved** 行汇总所有子 session 的节省金额（`computeSubsSaved`）。
+- 单价不可用或节省为零时，所有 pricing 行隐藏。
 
 ## 时间字段（OpenCode SDK v2）
 
@@ -219,7 +241,7 @@ flowchart TD
 | 指标切换 | 累计 / 最近 N 轮 / 滑动窗口；与时间轴 Phase 3 联动 | timeline.md § Phase 3 |
 | 子 agent | 递归子 session、按 agent 类型过滤 | timeline.md § 风险；侧栏另议 |
 
-实现日志时继续复用 `message.updated` + `messages()`；落盘异步、勿阻塞 TUI（见 timeline.md）。
+实现日志时使用 `message.updated` 事件直接驱动的 `handleMessage()`；落盘异步、勿阻塞 TUI（见 timeline.md）。
 
 ## 插件缓存
 

package/docs/zh-CN/timeline.md

@@ -37,8 +37,8 @@ flowchart LR
 /** 单条记录；JSONL 一行一个 */
 export type LlmCallRecord = {
   schema: 1
-  /** 写入时间（本机 ms），非 LLM 时间 */
-  recordedAt: number
+  /** 写入时间（ISO 8601，含时区），非 LLM 时间 */
+  recordedAt: string
   /** 所属 session */
   sessionId: string
   /** 主 session id；子 session 时与 sessionId 不同 */
@@ -47,8 +47,8 @@ export type LlmCallRecord = {
   /** OpenCode message id；SDK 若无则用稳定合成键，见下文 */
   messageKey: string
   modelId: string
-  created: number
-  completedAt?: number
+  created: string
+  completedAt?: string
   durationMs?: number
   isComplete: boolean
   input: number
@@ -101,14 +101,14 @@ export function buildCallRecords(
 **默认路径（可配置）**
 
 ```
-~/.config/opencode/plugins/opencode-cache-hit/logs/
+~/.local/share/opencode/logs/cache-hit/
   timeline-2026-05-31.jsonl       # 按本地日历日一个活跃文件
   timeline-2026-05-31.jsonl.1     # 当日超过 rotateMaxBytes 时链式备份
 ```
 
 所有主/子 session 的调用写入**同一天**的同一文件；用行内 `rootSessionId` / `sessionId` / `scope` 筛某场对话。跨日自动切到新文件名。
 
-`dir` 非空时可改到例如 `~/.local/share/opencode/cache-hit/logs/`。
+`dir` 非空时可改到例如 `~/my-logs/`，支持 `~/` 展开为 home 目录。
 
 推荐 **JSONL** 第一期：实现简单、`tail -f` / `jq` 友好；SQLite 留给第二期索引查询。
 
@@ -138,7 +138,7 @@ export function buildCallRecords(
 | 字段 | 代码默认 | 说明 |
 |------|----------|------|
 | `enabled` | `false` | 关闭时零 IO，不影响侧栏 |
-| `dir` | `""` | 空则用插件目录下 `logs/` |
+| `dir` | `""` | 空则用 `~/.local/share/opencode/logs/cache-hit` |
 | `flushIncomplete` | `false` | 是否在未完成时写 JSONL |
 | `logSummaryMessages` | `true` | 是否记录 summary 行 |
 | `maxMemoryRows` | `50` | TUI 内存中保留条数（全量仍可从文件读） |
@@ -153,7 +153,7 @@ export function buildCallRecords(
 1. 可选 `rotateMaxBytes`：写**前**若当日活跃文件 ≥ 阈值 → 链式 rename（见 § 轮转与清理）。
 2. `appendFile` 一行 JSON。
 3. 可选 `maxLinesPerFile`：写**后**读回活跃文件，只保留最后 N 行（**删行**，不生成 `.1`）。
-4. 异步：`collector` 在 `queueMicrotask` 里写盘；`flushedKeys` 按 `messageKey` 去重（切换主 session **不**清空；跨日换文件名时清空）。
+4. 事件驱动：`message.updated` → `handleMessage()` → fire-and-forget `appendFile`。无轮询，无去重。
 
 ## 轮转与清理
 
@@ -193,11 +193,11 @@ export function buildCallRecords(
 
 午夜后自动写入新文件名；昨日文件保留，直至上述清理策略删除。
 
-### 去重与切换 session
+### 收集
 
-- 同一 `messageKey` 只 append 一次（进程内 `flushedKeys`）。
-- 切换 TUI 主 session：仍写**同日**文件，用 `rootSessionId` 过滤；**不**因切换而重复写同一 `messageKey`。
-- 插件重启后 `flushedKeys` 为空，可能对**同一批已完成消息**再写一遍（若需避免，需另做持久化去重，当前未做）。
+- `message.updated` 事件携带完整 `Message` 对象。collector 直接订阅事件——无轮询，无去重。
+- 切换主 session：`resetForRootChange()` 清空内存缓存；新 session 的事件自然到达。
+- 重启安全：启动前的消息已在上次 session 中写入 JSONL。无需回放，无需扫描。
 
 ## 运行时接入
 
@@ -205,20 +205,18 @@ export function buildCallRecords(
 sequenceDiagram
   participant E as message.updated
   participant H as sidebar-host
-  participant B as timeline/build
+  participant C as timeline/collector
   participant W as timeline/writer
 
-  E->>H: refreshTick++（现有）
-  H->>B: debounce 500ms buildCallRecords(main+children)
-  B->>H: 更新 memoryRecords（Signal）
-  alt enabled and isComplete and not flushed
-    B->>W: append JSONL
+  E->>H: { sessionID, info: Message }
+  H->>C: handleMessage(sessionID, info)
+  alt assistant and complete
+    C->>W: append JSONL（fire-and-forget）
   end
 ```
 
-- **与 `child-session-sync` 分工**：子 id 列表仍由 `session.list` 负责；时间轴只读 `messages()`，不额外 list。
-- **Debounce**：500ms（比 child list 的 200ms 略长，减少流式写盘）；仅 `timeline.enabled` 时注册。
-- **作用域**：只记录「当前 TUI 绑定的 `rootSessionId`」及其子 session；落盘路径按**当天**不变，切换主 session 仍写同一日文件。
+- **与 `child-session-sync` 分工**：子 id 列表仍由 `session.list` 负责；时间轴从事件中写 main 和 child session。
+- 无 debounce，无轮询。**作用域**：当前 TUI root session + 其子 session。
 
 ## UI（分阶段）
 
@@ -228,20 +226,26 @@ sequenceDiagram
 - 文档示例：
 
 ```bash
-LOG=~/.config/opencode/plugins/opencode-cache-hit/logs/timeline-$(date +%Y-%m-%d).jsonl
+LOG=~/.local/share/opencode/logs/cache-hit/timeline-$(date +%Y-%m-%d).jsonl
 tail -f $LOG
+# 时间字段为 ISO 8601 含本地时区（如 "2024-05-30T08:00:00.000+08:00"）
 jq -r 'select(.rootSessionId=="YOUR_ROOT") | [.created,.scope,.hitPercent,.cost]|@tsv' $LOG
 ```
 
-**画图（可选脚本）** — 见 [scripts/README.md](../../scripts/README.md)：
+**画图 / 分析（可选脚本）** — 见 [scripts/README.md](../../scripts/README.md)：
 
 ```bash
 python3 -c "import json,sys; r=[json.loads(x) for x in open(sys.argv[1]) if x.strip()]; h=[x['hitPercent'] for x in r if x.get('hitPercent') is not None]; print(f\"{len(r)} calls, avg hit {sum(h)/len(h):.1f}%\")" $LOG
 
 bun scripts/plot-hit-rate.ts $LOG -o /tmp/hit.svg
 bun scripts/plot-hit-rate.ts $LOG --by-root -o /tmp/hit-multi.svg
+
+# 交互式 HTML 仪表盘（筛选、Chart.js）；加 --open 才会打开浏览器
+bun scripts/timeline-dashboard.ts --open
 ```
 
+默认日志目录与插件 `timeline.dir` 一致（`~/.local/share/opencode/logs/cache-hit/`）。
+
 ### Phase 2 — 侧栏「Timeline」折叠段
 
 - 在 `widget.tsx` 增加 `TuiSection`，展示最近 `maxMemoryRows` 条（窄屏每行一条）：
@@ -293,7 +297,7 @@ bun scripts/plot-hit-rate.ts $LOG --by-root -o /tmp/hit-multi.svg
 ## 示例 JSONL 行
 
 ```json
-{"schema":1,"recordedAt":1717000000000,"sessionId":"sess_main","rootSessionId":"sess_main","scope":"main","messageKey":"sess_main:1716999990000:deepseek/v4","modelId":"deepseek/v4","created":1716999990000,"completedAt":1717000000000,"durationMs":10000,"isComplete":true,"input":1200,"output":80,"reasoning":0,"cacheRead":38000,"cacheWrite":0,"cost":0.012,"hitPercent":96.9,"skippedForHit":false}
+{"schema":1,"recordedAt":"2024-05-30T08:00:00.000+08:00","sessionId":"sess_main","rootSessionId":"sess_main","scope":"main","messageKey":"sess_main:1716999990000:deepseek/v4","modelId":"deepseek/v4","created":"2024-05-30T07:59:50.000+08:00","completedAt":"2024-05-30T08:00:00.000+08:00","durationMs":10000,"isComplete":true,"input":1200,"output":80,"reasoning":0,"cacheRead":38000,"cacheWrite":0,"cost":0.012,"hitPercent":96.9,"skippedForHit":false}
 ```
 
 ---

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "opencode-cache-hit",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "OpenCode TUI sidebar: prompt cache hit rate, tokens & cost with sub-agent rollup. Works with opencode-visual-cache; optional per-call JSONL timeline.",
   "type": "module",
   "license": "MIT",
-  "author": "zhumengzhu <mengzhu.loveyou@gmail.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/zhumengzhu/opencode-cache-hit.git"