opencode-cache-hit 0.2.0 → 0.2.1

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,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`。
+
 ## 聚合与刷新
 
 ### 何时重算
@@ -223,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

@@ -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.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",

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`):