opencode-cache-hit 0.2.0 → 0.2.2

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 up to 100 messages (capped by TUI sync); no cursor, `since`, or limit parameter on the plugin side |
+| `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()` (TUI-synced window, up to 100 messages) → `buildCallRecords()` (all returned 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

@@ -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,19 +181,18 @@ 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
 
@@ -214,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)

package/docs/zh-CN/design.md

@@ -57,9 +57,10 @@ sequenceDiagram
 
   Slot->>Host: sessionId, display, api
   Host->>API: session.list → childIds
-  API-->>Host: message.updated
-  Host->>Host: refreshTick++
-  Host->>API: session.messages(sid / cid)
+  API-->>Host: message.updated { info: Message }
+  Host->>Host: refreshTick++, timeline.handleMessage(info)
+  Host->>API: session.get(sid / cid) → 聚合值
+  Host->>API: session.messages(sid / cid) → fallback / 趋势
   Host->>W: main, messages, subAgents
   W->>W: aggregate / format / TuiPanel
 ```
@@ -77,6 +78,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 +90,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` 冒烟）。
@@ -112,14 +114,14 @@ flowchart TD
   F -->|否| R
   C --> H[childSessionIdsForParent]
   C2 --> H
-  H --> I[messages 重读 + 聚合]
+  H --> I["session.get 聚合 + messages 兜底"]
 ```
 
 - **唯一来源**：`childIds` 始终由 `session.list` 结果**覆盖**写入，不再 `session.get` + 追加（避免漏发现、僵尸 id）。
 - **竞态**：`listGen` 在 parent 切换时递增；回调校验 generation 与 `parentId` 未变。
 - **流式**：外国 session 的 `message.updated` 很密，用 `CHILD_LIST_DEBOUNCE_MS`（200ms）合并 list 请求。
 - **一层子 session**：`parentID === sid` 的直接子节点；嵌套子 agent 见「未来方向」。
-- **子 session 数据**：对每个 `cid` 调用 `messages(cid)` → `aggregateSessionFromMessages`；无统计的条目过滤掉。
+- **子 session 数据**：`session.get(cid)` → `aggregateFromSessionObject`（主路径）；不可用时降级到 `messages(cid)` → `aggregateSessionFromMessages`。若 session 聚合缺少 model/provider 元数据，从 messages 末尾补齐（`withModelFallback`）。
 
 ### Agents 合计语义（实现正确，勿与「全场总账」混淆）
 
@@ -130,18 +132,35 @@ 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`。
+
 ## 聚合与刷新
 
 ### 何时重算
 
 | 数据 | 触发方式 |
 |------|----------|
-| 主 session snapshot | `createMemo` 内读 `refreshTick` + `api.state.session.messages(sid)` |
-| 主 session 消息列表（Hit 趋势） | 同上 |
-| 子 agent 列表内容 | `childIds` 变化或 `refreshTick` 后各 `messages(cid)` 重读 |
+| 主 session snapshot | `createMemo` 内读 `refreshTick` + `session.get(sid)`（聚合）；fallback `messages(sid)` |
+| 主 session 消息列表（Hit 趋势） | `createMemo` 内读 `refreshTick` + `messages(sid)` |
+| 子 agent 列表内容 | `refreshTick` + `childIds` → 每个 child 的 `session.get(cid)`；fallback `messages(cid)` |
 | 子 agent id 集合 | `session.list` 完成回调 / `message.updated` 发现新 child |
 
-主 session **显式**订阅 `message.updated`（在 `sidebar-host`）：每次事件 `refreshTick++`，保证流式过程中 `tokens` 更新会重算（不仅依赖 store 是否自动触发 Solid memo）。
+主 session **显式**订阅 `message.updated`（在 `sidebar-host`）：每次事件 `refreshTick++`，触发相关 memo 重算；会话总量以 `session.get()` 聚合为准，逐轮趋势使用最近 messages。
 
 ### 累加规则
 
@@ -223,7 +242,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/frontend-migration-plan.md

@@ -0,0 +1,100 @@
+# 前端迁移方案：session.get() 聚合数据
+
+## 概述
+
+cache-hit 插件此前通过遍历 `api.state.session.messages()` 逐条累加 per-message 字段来统计 cost/token。这个路径受 OpenCode TUI sync 的 **100 条消息上限** 限制（[issue #31513]），超过 100 条消息的会话数据被静默截断。
+
+**影响**：对于超过 100 条消息的会话，截断导致大量数据丢失。在一个实际的长会话中，插件仅显示了约 43% 的缓存读 token 和约 39% 的实际费用。
+
+| 指标 | 旧（messages，100 条截断） | 新（session.get，无截断） |
+|------|--------------------------|-------------------------|
+| 缓存读 | 59.6M tok | **139.0M tok** |
+| 缓存写 | 89.8K tok | **1.4M tok** |
+| 未命中 | 118 tok | **329 tok** |
+| 输出 | 32.7K tok | **91.9K tok** |
+| 可见子 Agent | 3 | **10** |
+
+修复方案是将数据来源从逐条消息累加切换为 `api.state.session.get()`，该接口返回 **数据库层聚合值**，由 session projector 从全部消息累加得出 —— 不受 100 条上限影响。
+
+## 根因
+
+OpenCode TUI sync（`packages/opencode/src/cli/cmd/tui/context/sync.tsx`）在获取会话消息时硬编码了 `limit: 100`：
+
+```typescript
+// 第 559 行 — 最多获取 100 条消息
+sdk.client.session.messages({ sessionID, limit: 100 }),
+
+// 第 580-581 行 — TUI store 也只保留最后 100 条
+const visible = infos.slice(-100)
+```
+
+`api.state.session.messages(sid)` 读取的是 `sync.data.message[sid]`，最多 100 条。超过的会话，插件看到的是不完整数据，且没有任何截断提示。
+
+与此同时，OpenCode SQLite 数据库的 `session` 表存储了**预聚合**列（`cost`、`tokens_input`、`tokens_output`、`tokens_cache_read`、`tokens_cache_write`），由 session projector 通过 SQL 增量更新 —— 每条消息都会被计入，无上限。
+
+`api.state.session.get(sid)` 返回完整 `Session` 对象（SDK 类型 `Session`），包含来自数据库聚合的 `cost` 和 `tokens` 字段。
+
+## 方案
+
+### 设计
+
+```
+之前：
+  api.state.session.messages(sid) → 遍历 100 条消息 → 累加           ❌ 截断
+
+现在：
+  api.state.session.get(sid)      → 直接读 cost/tokens → 完成       ✅ 全量
+  └─ session 不可用时              → fallback 到消息累加             （兼容）
+```
+
+### 改动
+
+| 文件 | 内容 |
+|------|------|
+| `src/types.ts` | 新增 `SessionObject` 类型（`model`、`cost`、`tokens`、`parentID`）；更新 `session.get` 返回类型 |
+| `src/stats.ts` | 新增 `aggregateFromSessionObject()` — O(1) 从 `SessionObject` 提取 `SessionSnapshot` |
+| `src/sidebar-host.tsx` | `mainSnap` 和 `subAgentList` 优先使用 `session.get()`，不可用时 fallback 到消息累加 |
+| `tests/stats.test.ts` | 3 个测试用例覆盖空对象、完整对象、部分字段对象 |
+
+### 数据流
+
+1. **`mainSnap`**：调用 `api.state.session.get(sid)` → `aggregateFromSessionObject()` → 有数据则返回。若 session 不可用或为空，fallback 到 `aggregateSessionFromMessages()`。
+
+2. **`subAgentList`**：每个子会话同上。
+
+3. **逐轮趋势**（`computePerCallHitTrend`）：仍使用 `api.state.session.messages()` —— 趋势只看最近几轮，100 条足够。
+
+### 为什么 resume 会话立即可见
+
+resume 会话时，OpenCode TUI `sync()` 立即调用 `sdk.client.session.get({ sessionID })` 获取完整 `Session` 对象（含数据库级聚合值）。该对象存入 TUI state store，`api.state.session.get(sid)` 读取之。插件从会话加载的瞬间就能看到准确总数。
+
+### Fallback 策略
+
+`session.get()` 对从未被 sync 到 TUI state 的会话返回 `undefined`（极少见，多见于特殊上下文中加载的子会话）。fallback 到 `api.state.session.messages()` 作为安全网保留原有行为。
+
+## 性能
+
+| 维度 | 旧（消息遍历） | 新（session.get） |
+|------|---------------|-------------------|
+| 时间复杂度 | O(n)，n ≤ 100 | O(1) |
+| 内存 | 读取整个消息数组 | 读取一个小对象 |
+| 响应式触发 | `message.updated` → 重算 | 同一事件，同一时机 |
+| 数据完整性 | ≤ 100 条消息 | 全部消息（数据库聚合） |
+
+## 上线
+
+1. **无需配置变更** —— 插件自动优先使用 `session.get()`。
+2. **存量用户无需迁移** —— 旧配置文件和 timeline 日志不受影响。
+3. **重启 OpenCode** 加载更新后的插件代码。
+4. **验证**：打开一个超过 100 条消息的会话，侧边栏数据应与数据库聚合值一致。
+
+## 相关链接
+
+- [anomalyco/opencode#31513] — v1 TUI sync 硬编码 limit:100
+- [anomalyco/opencode#26861] — 基于游标的分页 PR（待合入）
+- [anomalyco/opencode#6548] — 分页消息加载功能请求
+
+[issue #31513]: https://github.com/anomalyco/opencode/issues/31513
+[anomalyco/opencode#31513]: https://github.com/anomalyco/opencode/issues/31513
+[anomalyco/opencode#26861]: https://github.com/anomalyco/opencode/pull/26861
+[anomalyco/opencode#6548]: https://github.com/anomalyco/opencode/issues/6548

package/docs/zh-CN/timeline.md

@@ -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（分阶段）
 
@@ -234,15 +232,20 @@ tail -f $LOG
 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` 条（窄屏每行一条）：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-cache-hit",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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",

package/scripts/README.md

@@ -20,6 +20,69 @@ Export TSV for spreadsheets (time fields are ISO 8601 strings):
 jq -r 'select(.hitPercent!=null) | [.completedAt,.scope,.hitPercent,.cost]|@tsv' logs/timeline-2026-05-31.jsonl
 ```
 
+## `timeline-dashboard.ts` (Bun, no install)
+
+Interactive HTML dashboard with charts, filters, and data tables:
+
+```bash
+bun scripts/timeline-dashboard.ts                                                  # auto-detect logs/ (no browser)
+bun scripts/timeline-dashboard.ts --open                                           # write HTML, then open browser
+bun scripts/timeline-dashboard.ts -o /tmp/report.html                              # custom output path
+bun scripts/timeline-dashboard.ts ~/logs/timeline-*.jsonl                          # globs expanded by script
+bun scripts/timeline-dashboard.ts --output /tmp/report.html --open                 # combined
+```
+
+Default output: `/tmp/timeline-dashboard-YYYY-MM-DD-HHmmss.html` (timestamp suffix to avoid overwrites).
+
+**Browser:** not opened by default; pass `--open` (macOS `open`, Linux `xdg-open`, Windows `start`).
+
+**Features:**
+- Summary cards follow active filters (records, tokens, cost, avg hit rate)
+- Time / session / scope / model / text search filters
+- 3 Chart.js charts: token volume (stacked bar), hit rate + cost (dual axis), duration (bar)
+- Session summary table (mixed main+child scope shown as `main+child`)
+- Per-call detail table with expandable rows (all JSONL fields)
+- Embedded data — no server needed, just open the HTML file
+
+**How it works:**
+
+1. Reads `timeline-*.jsonl` and rotation backups `timeline-*.jsonl.N` from the default log dir (`~/.local/share/opencode/logs/cache-hit/`) or user-supplied paths/globs
+2. Parses each JSONL line (`schema: 1` validation), sorts by `completedAt` / `created`
+3. Aggregates per-session statistics in the browser when filters change
+4. Generates a self-contained HTML file with:
+   - All data embedded as JSON in a `<script>` tag (`<` escaped for safety)
+   - Chart.js 4.4.7 from CDN (`cdn.jsdelivr.net`)
+   - Vanilla JS for interactivity (no framework dependency)
+5. Optional `--open` opens the output file in the default browser
+
+**Avg hit rate:** excludes `skippedForHit` rows (same rule as `plot-hit-rate.ts`); null `hitPercent` still appear in tables/charts.
+
+**Cost display:** reads `currency` / `costUnit` / `rate` from `~/.config/opencode/cache-hit.json` when present (same as the TUI sidebar). **No config file** → defaults (`CNY` display, `USD` JSONL unit, rate `6.77`). Invalid or partial cost fields are normalized; corrupt config falls back without failing the script. JSONL always stores raw `cost` in `costUnit` (usually USD).
+
+**Note:** The generated HTML is self-contained except Chart.js CDN. Re-run the script to refresh data (static snapshot).
+
+### Design approaches
+
+**Option A (current — static HTML):**
+Data is embedded into the HTML at build time by Bun. The browser just renders.
+
+```
+bun scripts/timeline-dashboard.ts  →  /tmp/timeline-dashboard-YYYY-MM-DD-HHmmss.html (self-contained)
+```
+
+- Pros: No server needed, zero runtime deps, can email/share the file
+- Cons: Snapshot only — re-run to refresh data
+
+**Option B (live server):**
+Starts an HTTP server; the browser fetches JSONL via `fetch("/api/logs")`.
+
+```
+bun scripts/timeline-dashboard.ts serve  →  http://localhost:PORT
+```
+
+- Pros: Live reload — refresh the page to see new logs
+- Cons: Must keep a process running, cannot send the page as a file
+
 ## `plot-hit-rate.ts` (Bun, no install)
 
 Terminal ASCII chart; optional SVG (`open /tmp/hit.svg`):