opencode-cache-hit 0.1.0

package/docs/zh-CN/design.md

@@ -0,0 +1,229 @@
+# 设计说明
+
+面向**维护本插件的开发者**：说明数据从哪来、何时重算、与 visual-cache 的边界。使用与配置见 [README.zh-CN.md](../../README.zh-CN.md)。
+
+## 与 opencode-visual-cache 的关系
+
+本插件是**独立项目**，并非 visual-cache 官方维护。实现上**大量借鉴**了 [opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache) 的思路，包括但不限于：
+
+- **侧栏面板布局**（`src/tui-panel/`）：边框、命中率条、折叠段、主题色映射等页面骨架
+- **布局**：主 session 块始终显示；有子 agent 时增加可折叠的 **Agents** 段
+- **命中率口径**：会话累计与 visual-cache 的 `cache.read / (cache.read + input)` 约定对齐
+
+**分工**：visual-cache 侧重主 session **上下文 / token 分布预估**；cache-hit 侧重**按轮次指标、成本与子 agent 汇总**。推荐两个插件一起装。
+
+用法见 [文档索引](../README.md)。
+
+## 产品边界
+
+```mermaid
+flowchart TB
+  subgraph ours [opencode-cache-hit]
+    DISC[子 session 发现]
+    AGG[消息级 token/cost 聚合]
+    UI[Cache Hit 侧边栏]
+  end
+  subgraph ref [opencode-visual-cache 参考]
+    EST[上下文 token 预估]
+    VCUI[Token Cache 侧边栏]
+  end
+  OC[OpenCode session / messages API] --> DISC
+  OC --> AGG
+  AGG --> UI
+  OC -.->|只读参考 UI 语言| EST
+  EST -.-> VCUI
+```
+
+| 角色 | 职责 |
+|------|------|
+| **cache-hit** | 子 agent 发现与汇总；主/子 session 的 cache、token、成本；可独立演进 |
+| **visual-cache** | 主 session 上下文与预估；非本仓库维护 |
+| **默认** | 主 session + 可折叠 **Agents**（子 session 合计） |
+
+## 成本模型
+
+- 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`。
+
+## 运行时架构
+
+```mermaid
+sequenceDiagram
+  participant Slot as sidebar_content slot
+  participant Host as sidebar-host
+  participant API as OpenCode API
+  participant W as widget + metrics
+
+  Slot->>Host: sessionId, display, api
+  Host->>API: session.list → childIds
+  API-->>Host: message.updated
+  Host->>Host: refreshTick++
+  Host->>API: session.messages(sid / cid)
+  Host->>W: main, messages, subAgents
+  W->>W: aggregate / format / TuiPanel
+```
+
+### 模块职责
+
+| 文件 | 职责 |
+|------|------|
+| `plugin.tsx` | `api.slots.register`（`order: 56`，紧邻 visual-cache）；加载配置与 `formatCost` |
+| `sidebar-host.tsx` | 绑定 `sessionId`；`mainSnap` / `mainMessages` / `subAgentList`；`refreshTick` + `message.updated` |
+| `widget.tsx` | `sessionId` 非空则渲染面板；`hasData` 否则 noData |
+| `use-cache-hit-metrics.ts` | Hit 条、趋势、Combined Hit、hasData |
+| `main-session-view.tsx` / `agents-view.tsx` | 业务区块 |
+| `cache-hit-rows.tsx` | Detail 区共用 token 行 |
+| `stats.ts` | 纯函数聚合（无 UI） |
+| `session-list.ts` | `session.list` 响应解析、`childSessionIdsForParent` |
+| `format-cost.ts` / `format-tokens.ts` / `format-cache-ui.ts` | 展示格式化（**不含** `computeHitBarWidth`，其在 `tui-panel/layout.ts`） |
+| `message-timing.ts` | SDK 时间字段辅助 |
+| `timeline/` | 按次 JSONL（`records` / `writer` / `collector`） |
+| `plugin-config.ts` / `load-config.ts` | 配置归一化与默认值 |
+
+### TUI 面板框架（`src/tui-panel/`）
+
+可复用的 visual-cache **页面**骨架（布局、配色、折叠段），**不含** skills 预估、slash、kv 等业务。
+
+| 模块 | 职责 |
+|------|------|
+| `layout.ts` | 视觉列宽、`justifyRow`、`computeHitBarWidth`、分隔线 |
+| `palette.ts` | 主题色 → 面板调色板 |
+| `use-panel-layout.ts` | `createPanelLayout`（测宽）、`createSectionFold` |
+| `components.tsx` | `TuiPanel`、`TuiHitRow`、`TuiMetricRow` 等（需 `@opentui/solid`） |
+| `index.ts` | 对外 barrel |
+
+纯逻辑模块（如 `use-cache-hit-metrics`）应从 `layout.ts` / `palette.ts` 直接 import，避免经 `index.ts` 拉入 JSX（便于 `bun test` 冒烟）。
+
+用法见 [src/tui-panel/README.zh-CN.md](../../src/tui-panel/README.zh-CN.md)。
+
+## 子 agent 发现
+
+实现：`src/child-session-sync.ts`（`sidebar-host` 调用）。
+
+```mermaid
+flowchart TD
+  A[sessionId 变化] --> B[resetForParentChange]
+  B --> C[loadChildren 立即 session.list]
+  E[message.updated 任意会话] --> R[refreshTick++]
+  E --> F{sessionID !== parent?}
+  F -->|是| G[debounce 200ms]
+  G --> C2[loadChildren 覆盖 childIds]
+  F -->|否| R
+  C --> H[childSessionIdsForParent]
+  C2 --> H
+  H --> I[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`；无统计的条目过滤掉。
+
+### Agents 合计语义（实现正确，勿与「全场总账」混淆）
+
+| 范围 | 是否计入 Agents 段 |
+|------|-------------------|
+| 各子 session 的 assistant 消息 | 是（`aggregateSubAgents`） |
+| 主 session 的 assistant 消息 | **否**（即使在 auto 下仍会计入 `mainSnap`，仅 UI 隐藏主块） |
+
+主 session 若仍有编排类调用，其 token/费用不会出现在 Agents 合计中；UI 通过 `agentsScopeHint`（「仅子会话 / sub-sessions」）标明。与 visual-cache 对主 session 的展示互补，不是漏算 bug。
+
+## 聚合与刷新
+
+### 何时重算
+
+| 数据 | 触发方式 |
+|------|----------|
+| 主 session snapshot | `createMemo` 内读 `refreshTick` + `api.state.session.messages(sid)` |
+| 主 session 消息列表（Hit 趋势） | 同上 |
+| 子 agent 列表内容 | `childIds` 变化或 `refreshTick` 后各 `messages(cid)` 重读 |
+| 子 agent id 集合 | `session.list` 完成回调 / `message.updated` 发现新 child |
+
+主 session **显式**订阅 `message.updated`（在 `sidebar-host`）：每次事件 `refreshTick++`，保证流式过程中 `tokens` 更新会重算（不仅依赖 store 是否自动触发 Solid memo）。
+
+### 累加规则
+
+- **不是**只在「最后一轮」算一次；session 内**每条** `role === assistant` 的消息都进入累加。
+- **流式中**：同一条 message 的 `tokens` 可能多次变化；每次 `message.updated` 后重算。
+- `reasoning` token **不参与**命中率分母。
+- `summary: true` 的 assistant：在 `computePerCallHitTrend` 中**跳过**；会话累计器 `aggregateSessionFromMessages` **暂未**排除。
+
+### 侧边栏可见性（避免与 README 混淆）
+
+```mermaid
+flowchart TD
+  S{sessionId 非空?}
+  S -->|否| H[不渲染面板]
+  S -->|是| P[渲染 TuiPanel]
+  P --> D{hasData?<br/>主或子有统计}
+  D -->|否| ND[noData]
+  D -->|是| MAIN[Main / Detail / Model]
+  D -->|有子 agent| AG[Agents 段（可折叠）]
+```
+
+| 概念 | 实现 |
+|------|------|
+| 整个面板 | `widget.tsx`：`Show when={sessionId().length > 0}` |
+| 有无可显示数据 | `hasData` = `mainSessionHasStats(main) \|\| subs.length > 0` |
+| 主 session **区块** | 始终渲染（Hit / Detail / Model） |
+| **Agents 段** | `subs.length > 0` 时显示，各段可独立折叠 |
+| `sidebarShouldShow` | `mainSessionHasStats(main) \|\| subs.length > 0`（测试用） |
+
+## 命中率（当前实现）
+
+**会话累计（Total Hit 口径，对齐 visual-cache）**
+
+```
+对所有 assistant 消息累加 input、cache.read
+→ cacheRead / (cacheRead + input)
+```
+
+**顶栏 Hit（单轮 + 趋势）**
+
+- `computePerCallHitTrend(messages)`：每条 assistant 一轮命中率；`summary: true` 跳过。
+- 展示**最后一条**非 summary 轮的命中率；与前一条比较得趋势（↑ / ↓ / `-`）。
+
+**Combined Hit**
+
+- 存在子 agent 且与会话累计命中率差异 ≥ 0.05% 时显示（主+子合并口径）。
+
+## 时间字段（OpenCode SDK v2）
+
+| 来源 | 字段 | 说明 |
+|------|------|------|
+| `AssistantMessage` | `time.created` | ms epoch，消息创建 |
+| `AssistantMessage` | `time.completed?` | ms epoch，本轮 LLM 结束；流式中常缺失 |
+| `ReasoningPart` | `time.start` / `time.end?` | thought 片段 |
+| `ToolStateCompleted` | `time.start` / `time.end` | 工具执行 |
+| `StepFinishPart` | （无 time） | 有 tokens/cost，时间回退到 message |
+
+按次日志（**Phase 1 已实现**，默认关闭）：以 `AssistantMessage` 为一行，用 `created` + `completed` 排序；按**本地日历日**单文件 JSONL 落盘。实现：`src/timeline/`、`src/message-timing.ts`。路径、轮转与清理见 **[timeline.md](./timeline.md)**（本文档同目录）§ 存储、§ 轮转与清理。
+
+## 测试策略
+
+| 层级 | 文件 | 作用 |
+|------|------|------|
+| 单元 | `tests/*.test.ts` | `stats`、`format-*`、`tui-panel/layout` 等纯函数 |
+| 冒烟 | `tests/module-load.test.ts` | `import` 消费者模块，捕获「符号已迁移但 import 路径未改」 |
+| 运行时 | OpenCode 日志 | JSX / peer（`@opentui/solid`）加载错误；本地 `bun test` 不覆盖 |
+
+重构移动 `export` 后：`rg` 旧符号名 + `bun test`。
+
+## 未来方向（未实现）
+
+| 方向 | 说明 | 设计文档 |
+|------|------|----------|
+| 按次 LLM + 时间轴 / JSONL | **Phase 1 已实现**（`src/timeline/`，默认关闭） | [timeline.md](./timeline.md) |
+| 指标切换 | 累计 / 最近 N 轮 / 滑动窗口；与时间轴 Phase 3 联动 | timeline.md § Phase 3 |
+| 子 agent | 递归子 session、按 agent 类型过滤 | timeline.md § 风险；侧栏另议 |
+
+实现日志时继续复用 `message.updated` + `messages()`；落盘异步、勿阻塞 TUI（见 timeline.md）。
+
+## 插件缓存
+
+| 安装 | 更新 |
+|------|------|
+| 本地路径 | 重启 OpenCode |
+| npm 包 | 重启；必要时删除 `~/.cache/opencode/packages/opencode-cache-hit@latest` |

package/docs/zh-CN/timeline.md

@@ -0,0 +1,301 @@
+# 时间轴 / 按次日志 — 设计方案
+
+面向开发者。侧栏聚合见 [design.md](./design.md)。用户指南见 [README.zh-CN.md](../../README.zh-CN.md)。
+
+**Phase 1（JSONL 落盘）已实现**，默认 `timeline.enabled: false`。Phase 2 侧栏 Timeline 段、Phase 3 指标切换仍未做。
+
+## 目标与非目标
+
+| 目标 | 非目标 |
+|------|--------|
+| 按时间查看每次 assistant 调用的 token / cache / cost / 命中率 | 替代 OpenCode 平台日志（`~/.local/share/opencode/log`） |
+| 区分主 session 与子 session 的调用 | 在 TUI 里实时 `console.log` 刷屏 |
+| 本地落盘，便于事后用 jq / 脚本分析 | 上传云端、团队共享 |
+| 与现有 `stats.ts` 口径一致（含 `summary` 跳过规则） | 第一期就做 SQLite、图表、递归子 agent |
+
+## 核心概念
+
+**一条时间轴事件 = 一次「可计费的 assistant 轮次」**，与侧栏顶栏 **Hit** 行同源，不是 tool part、不是 user 消息。
+
+```mermaid
+flowchart LR
+  MSG[AssistantMessage] --> REC[LlmCallRecord]
+  REC --> MEM[内存 ring 最近 N 条]
+  REC --> JSONL[JSONL 追加写]
+  MEM --> UI[侧栏 Timeline 段 可选]
+```
+
+| 字段 | 来源 |
+|------|------|
+| 时间排序键 | `time.completed ?? time.created`（已有 `timingFromAssistantMessage`） |
+| 是否计入 Hit 趋势 | `summary !== true` 且 `input + cache.read > 0`（对齐 `computePerCallHitTrend`） |
+| 会话累计 | 仍用 `aggregateSessionFromMessages`（可后续让累计也跳过 `summary`） |
+
+## 数据模型
+
+```typescript
+/** 单条记录；JSONL 一行一个 */
+export type LlmCallRecord = {
+  schema: 1
+  /** 写入时间（本机 ms），非 LLM 时间 */
+  recordedAt: number
+  /** 所属 session */
+  sessionId: string
+  /** 主 session id；子 session 时与 sessionId 不同 */
+  rootSessionId: string
+  scope: "main" | "child"
+  /** OpenCode message id；SDK 若无则用稳定合成键，见下文 */
+  messageKey: string
+  modelId: string
+  created: number
+  completedAt?: number
+  durationMs?: number
+  isComplete: boolean
+  input: number
+  output: number
+  reasoning: number
+  cacheRead: number
+  cacheWrite: number
+  cost: number
+  /** 单轮 cache 命中率 0–100；无分母时为 null */
+  hitPercent: number | null
+  /** compaction / summary 消息 */
+  skippedForHit: boolean
+}
+```
+
+**`messageKey`（去重键）**
+
+1. 优先：`message.id` / `messageID`（实现前用真实 SDK 样本确认字段名，扩展 `AssistantMessage` 类型）。
+2. 回退：`${sessionId}:${created}:${modelID ?? ""}`（同一 created 极罕见碰撞；流式更新时 created 不变，可覆盖同键）。
+
+**流式更新策略**
+
+- `message.updated` 频繁触发时，**内存 Map<messageKey, LlmCallRecord>** 覆盖更新同一键。
+- **落盘**：仅在 `isComplete === true` 时 append 一行；或配置 `flushIncomplete: true` 时也写，行带 `isComplete`，便于分析 in-flight（默认 `false`，减少 JSONL 噪音）。
+- 未完成行在 TUI 时间轴里可显示为 `…` 后缀（可选）。
+
+## 从消息构建记录
+
+新建纯函数模块 `src/timeline/records.ts`（不依赖 JSX）：
+
+```typescript
+export function buildCallRecords(
+  sessionId: string,
+  rootSessionId: string,
+  scope: "main" | "child",
+  messages: readonly AssistantMessage[],
+): LlmCallRecord[]
+```
+
+逻辑要点：
+
+- 只处理 `role === assistant`。
+- `skippedForHit = msg.summary === true`。
+- `hitPercent`：与 `computePerCallHitTrend` 单条算法一致；`skippedForHit` 时可为 `null` 仍保留 token/cost 行（配置项 `logSummaryMessages`，默认 `true` 但标记 `skippedForHit`）。
+
+子 session：在 `sidebar-host` 已有 `childIds` 与 `refreshTick` 上，对每个 `cid` 调用 `buildCallRecords(cid, rootSid, "child", messages)`，与主 session 记录合并后按 `sortKey = completedAt ?? created` 排序。
+
+## 存储
+
+**默认路径（可配置）**
+
+```
+~/.config/opencode/plugins/opencode-cache-hit/logs/
+  timeline-2026-05-31.jsonl       # 按本地日历日一个活跃文件
+  timeline-2026-05-31.jsonl.1     # 当日超过 rotateMaxBytes 时链式备份
+```
+
+所有主/子 session 的调用写入**同一天**的同一文件；用行内 `rootSessionId` / `sessionId` / `scope` 筛某场对话。跨日自动切到新文件名。
+
+`dir` 非空时可改到例如 `~/.local/share/opencode/cache-hit/logs/`。
+
+推荐 **JSONL** 第一期：实现简单、`tail -f` / `jq` 友好；SQLite 留给第二期索引查询。
+
+**与旧版**：曾用 `<rootSessionId>.jsonl` 按主会话分文件；现改为按天。旧文件不会被自动迁移，可手动删除或保留。
+
+**配置**（并入 `cache-hit.config.json` 的 `timeline` 段）：
+
+```json
+{
+  "timeline": {
+    "enabled": false,
+    "dir": "",
+    "flushIncomplete": false,
+    "logSummaryMessages": true,
+    "maxMemoryRows": 50,
+    "maxLinesPerFile": 100000,
+    "rotateMaxBytes": 16777216,
+    "retainRotated": 5,
+    "maxAgeDays": 30,
+    "maxLogFiles": 20
+  }
+}
+```
+
+上表为 **example 推荐值**；代码默认见下表（`enabled: false`，轮转项为 `0`）。
+
+| 字段 | 代码默认 | 说明 |
+|------|----------|------|
+| `enabled` | `false` | 关闭时零 IO，不影响侧栏 |
+| `dir` | `""` | 空则用插件目录下 `logs/` |
+| `flushIncomplete` | `false` | 是否在未完成时写 JSONL |
+| `logSummaryMessages` | `true` | 是否记录 summary 行 |
+| `maxMemoryRows` | `50` | TUI 内存中保留条数（全量仍可从文件读） |
+| `maxLinesPerFile` | `0` | 活跃文件只保留最后 N 行（`0` = 不限） |
+| `rotateMaxBytes` | `0` | 活跃文件 ≥ 该字节数时滚到 `.jsonl.1`（`0` = 关闭） |
+| `retainRotated` | `5` | 同日大小轮转保留的**备份**个数（不含正在写的活跃文件） |
+| `maxAgeDays` | `0` | collector **启动时**删除超 N 天的 `timeline-*.jsonl*` |
+| `maxLogFiles` | `0` | 日志目录内 `timeline-*.jsonl*` 总数上限（每个 `.1` 单独计数） |
+
+**写入流程**（`src/timeline/writer.ts` + `rotation.ts`）
+
+1. 可选 `rotateMaxBytes`：写**前**若当日活跃文件 ≥ 阈值 → 链式 rename（见 § 轮转与清理）。
+2. `appendFile` 一行 JSON。
+3. 可选 `maxLinesPerFile`：写**后**读回活跃文件，只保留最后 N 行（**删行**，不生成 `.1`）。
+4. 异步：`collector` 在 `queueMicrotask` 里写盘；`flushedKeys` 按 `messageKey` 去重（切换主 session **不**清空；跨日换文件名时清空）。
+
+## 轮转与清理
+
+### 同日大小轮转（`rotateMaxBytes` + `retainRotated`）
+
+仅作用于**当天**活跃文件 `timeline-YYYY-MM-DD.jsonl`。写下一条记录**之前**检查大小。
+
+```
+活跃 (将满)  →  rename →  .1
+原 .1        →  rename →  .2
+原 .N        →  删除（当备份数已达 retainRotated 且再次轮转时）
+然后新建空的 活跃 文件，继续 append
+```
+
+| `retainRotated` | 当日最多占用（约） |
+|-----------------|-------------------|
+| `5`（默认 / example） | 活跃 + `.1`…`.5` ≈ 6× `rotateMaxBytes` |
+| `1` | 活跃 + `.1` ≈ 2× `rotateMaxBytes` |
+| `0` | 满则**删掉**活跃文件，不保留备份 |
+
+再满时最老备份**整文件删除**，更早的调用不可恢复。同时注意 `maxLogFiles`（每个备份各占 1 个文件槽）；繁忙日 + `retainRotated: 5` 时更易触达目录文件数上限。
+
+### 行数截断（`maxLinesPerFile`）
+
+写**后**对**当日活跃文件**原地重写，只留最后 N 行；**不会**把删掉的行挪到 `.1`。
+
+与 `rotateMaxBytes` 同时开启时，通常**先碰到字节上限**（当前记录约 500B/行，16MB ≈ 3.4 万行，远小于 example 的 10 万行）。
+
+### 目录清理（collector 启动时一次）
+
+1. `maxAgeDays`：删除 mtime 超过 N 天的所有 `timeline-*.jsonl*`。
+2. `maxLogFiles`：若仍多于 N 个文件，按**日志时间先后**删到剩 N 个：先删文件名里**最早日期**的；同一天先删 `.5`、`.4`…再删活跃文件（与 mtime 无关，避免 `touch` 误留旧日文件）。
+
+**不匹配**旧版 `<rootSessionId>.jsonl`，不会自动删；可手动清理。
+
+### 跨日
+
+午夜后自动写入新文件名；昨日文件保留，直至上述清理策略删除。
+
+### 去重与切换 session
+
+- 同一 `messageKey` 只 append 一次（进程内 `flushedKeys`）。
+- 切换 TUI 主 session：仍写**同日**文件，用 `rootSessionId` 过滤；**不**因切换而重复写同一 `messageKey`。
+- 插件重启后 `flushedKeys` 为空，可能对**同一批已完成消息**再写一遍（若需避免，需另做持久化去重，当前未做）。
+
+## 运行时接入
+
+```mermaid
+sequenceDiagram
+  participant E as message.updated
+  participant H as sidebar-host
+  participant B as timeline/build
+  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
+  end
+```
+
+- **与 `child-session-sync` 分工**：子 id 列表仍由 `session.list` 负责；时间轴只读 `messages()`，不额外 list。
+- **Debounce**：500ms（比 child list 的 200ms 略长，减少流式写盘）；仅 `timeline.enabled` 时注册。
+- **作用域**：只记录「当前 TUI 绑定的 `rootSessionId`」及其子 session；落盘路径按**当天**不变，切换主 session 仍写同一日文件。
+
+## UI（分阶段）
+
+### Phase 1 — 仅落盘（推荐先做）
+
+- 无侧栏改动；用户 `tail -f` / `jq` 分析。
+- 文档示例：
+
+```bash
+LOG=~/.config/opencode/plugins/opencode-cache-hit/logs/timeline-$(date +%Y-%m-%d).jsonl
+tail -f $LOG
+jq -r 'select(.rootSessionId=="YOUR_ROOT") | [.created,.scope,.hitPercent,.cost]|@tsv' $LOG
+```
+
+**画图（可选脚本）** — 见 [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
+```
+
+### Phase 2 — 侧栏「Timeline」折叠段
+
+- 在 `widget.tsx` 增加 `TuiSection`，展示最近 `maxMemoryRows` 条（窄屏每行一条）：
+  - `HH:mm:ss · main · 99.2% · ¥0.02`
+  - `HH:mm:ss · child …abc · 85.0% · 12k tok`
+- 不打开文件即可扫一眼；点击/快捷键打开文件路径（若 OpenCode 支持 `open` 再议）。
+
+### Phase 3 — 指标切换联动
+
+- 与 design 里「累计 / 最近 N 轮」共用 `buildCallRecords`：
+  - `window: "session" | "last1" | "lastN"`
+  - 侧栏 Hit 行可选显示「最近一轮」而非「最后一条非 summary」（与 JSONL 一致）。
+
+## 与现有模块关系
+
+| 模块 | 关系 |
+|------|------|
+| `message-timing.ts` | 提供 `created` / `completed` / `formatTimingShort` |
+| `stats.ts` | 抽出共享 `perMessageHitPercent(msg)`，供 `computePerCallHitTrend` 与 `buildCallRecords` 共用 |
+| `sidebar-host.tsx` | 挂载 `createTimelineCollector`（enabled 时） |
+| `plugin.tsx` | 无改动或仅读 config |
+
+## 测试
+
+| 用例 | 文件 |
+|------|------|
+| `buildCallRecords` 排序、summary、hitPercent | `tests/timeline-records.test.ts` |
+| 合成 `messageKey`、完成才 flush | `tests/timeline-writer.test.ts`（临时目录） |
+| 不启用时 writer 不被调用 | 可选 mock |
+
+## 风险与约束
+
+| 风险 | 缓解 |
+|------|------|
+| 流式写盘过多 | 默认仅 `isComplete` 落盘；debounce |
+| 无 message id | 合成键 + 完成时覆盖内存 |
+| 子 agent 嵌套 | 第一期只 `scope: child` 平铺；递归列入 Phase 4 |
+| 磁盘膨胀 | `maxLinesPerFile` / `rotateMaxBytes` / `maxAgeDays`（已实现） |
+| SDK 字段变更 | `schema: 1`；迁移时新文件或兼容读取 |
+
+## 实施顺序（建议）
+
+1. `timeline/records.ts` + 测试 + `stats` 抽取单条命中率  
+2. `timeline/writer.ts` + config + `sidebar-host` 接入（**enabled: false 默认**）  
+3. README 一段：如何开启、JSONL 路径、jq 示例  
+4. Phase 2 侧栏 Timeline 段（可选）  
+5. SQLite / 图表（远期）
+
+## 示例 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}
+```
+
+---
+
+维护说明：design.md「未来方向」中与按次日志相关的条目以本文 Phase 状态为准。

package/index.tsx

@@ -0,0 +1 @@
+export { default } from "./src/plugin.tsx"

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "opencode-cache-hit",
+  "version": "0.1.0",
+  "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"
+  },
+  "homepage": "https://github.com/zhumengzhu/opencode-cache-hit#readme",
+  "bugs": "https://github.com/zhumengzhu/opencode-cache-hit/issues",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tui",
+    "sidebar",
+    "cache",
+    "cache-hit",
+    "cache-hit-rate",
+    "prompt-cache",
+    "token",
+    "cost",
+    "cost-tracking",
+    "sub-agent",
+    "agent",
+    "opencode-visual-cache",
+    "jsonl",
+    "timeline"
+  ],
+  "exports": {
+    ".": "./index.tsx",
+    "./tui": "./index.tsx",
+    "./tui-panel": "./src/tui-panel/index.ts"
+  },
+  "files": [
+    "index.tsx",
+    "src",
+    "cache-hit.config.example.json",
+    "LICENSE",
+    "README.md",
+    "README.zh-CN.md",
+    "AGENTS.md",
+    "CONTRIBUTING.md",
+    "docs",
+    "scripts"
+  ],
+  "scripts": {
+    "test": "bun test tests/",
+    "check": "bun test tests/",
+    "syntax": "bun test tests/module-load.test.ts",
+    "prepublishOnly": "bun test tests/",
+    "prepare": "simple-git-hooks"
+  },
+  "simple-git-hooks": {
+    "pre-push": "bun test tests/"
+  },
+  "dependencies": {
+    "solid-js": "^1.9.0"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.14.0",
+    "@opencode-ai/sdk": ">=1.14.0",
+    "@opentui/core": ">=0.2.0",
+    "@opentui/solid": ">=0.2.0"
+  },
+  "devDependencies": {
+    "simple-git-hooks": "^2.13.1"
+  }
+}

package/scripts/README.md

@@ -0,0 +1,39 @@
+# Timeline analysis scripts
+
+Optional tools; not part of the OpenCode plugin runtime.
+
+## One-liners
+
+Quick stats (no extra deps):
+
+```bash
+# Python
+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}%\")" logs/timeline-2026-05-31.jsonl
+
+# Bun
+bun -e "const t=await Bun.file(process.argv[1]).text();const rows=t.trim().split('\n').filter(Boolean).map(l=>JSON.parse(l));const h=rows.map(r=>r.hitPercent).filter((p):p is number=>p!=null);console.log(rows.length+' calls, avg hit '+(h.reduce((a,b)=>a+b,0)/h.length).toFixed(1)+'%')" logs/timeline-2026-05-31.jsonl
+```
+
+Export TSV for spreadsheets:
+
+```bash
+jq -r 'select(.hitPercent!=null) | [.completedAt,.scope,.hitPercent,.cost]|@tsv' logs/timeline-2026-05-31.jsonl
+```
+
+## `plot-hit-rate.ts` (Bun, no install)
+
+Terminal ASCII chart; optional SVG (`open /tmp/hit.svg`):
+
+```bash
+bun scripts/plot-hit-rate.ts logs/timeline-2026-05-31.jsonl
+bun scripts/plot-hit-rate.ts logs/timeline-2026-05-31.jsonl --root YOUR_ROOT_SESSION_ID -o /tmp/hit.svg
+# one SVG, one colored line per rootSessionId (time-aligned)
+bun scripts/plot-hit-rate.ts logs/timeline-2026-05-31.jsonl --by-root -o /tmp/hit.svg
+```
+
+Use a real path, not `$LOG`, unless you exported it first:
+
+```bash
+set -x LOG logs/timeline-(date +%Y-%m-%d).jsonl   # fish: set log ...
+bun scripts/plot-hit-rate.ts $LOG -o /tmp/hit.svg
+```