opencode-cache-hit 0.1.0

package/AGENTS.md

@@ -0,0 +1,67 @@
+# AGENTS.md — maintainer & AI assistant guide
+
+Instructions for humans and coding agents working in **opencode-cache-hit**. End-user docs: [README.md](README.md) · [README.zh-CN.md](README.zh-CN.md).
+
+## Project purpose
+
+OpenCode TUI sidebar plugin: **cache hit rate**, **tokens**, **cost**, with **sub-agent (child session)** rollup. Optional per-call **JSONL timeline** (`timeline.enabled`).
+
+**Not** a fork of [opencode-visual-cache](https://github.com/Hotakus/opencode-visual-cache). UI patterns and `src/tui-panel/` are **heavily inspired by** visual-cache; product focus differs (see README comparison table).
+
+## Documentation map
+
+| Topic | English | 中文 |
+|-------|---------|------|
+| Users | [README.md](README.md) | [README.zh-CN.md](README.zh-CN.md) |
+| Architecture | [docs/en/design.md](docs/en/design.md) | [docs/zh-CN/design.md](docs/zh-CN/design.md) |
+| Timeline / JSONL | [docs/en/timeline.md](docs/en/timeline.md) | [docs/zh-CN/timeline.md](docs/zh-CN/timeline.md) |
+| TUI panel | [src/tui-panel/README.md](src/tui-panel/README.md) | [src/tui-panel/README.zh-CN.md](src/tui-panel/README.zh-CN.md) |
+| Contributing / npm | [CONTRIBUTING.md](CONTRIBUTING.md) | — |
+| Index | [docs/README.md](docs/README.md) | |
+
+## Commands
+
+```bash
+bun test          # full unit + module-load smoke
+bun run check     # same as test
+```
+
+After moving or renaming exports: run full `bun test`; `tests/module-load.test.ts` imports the real consumer graph.
+
+## Code conventions
+
+- **Minimal diffs**; match existing naming and module boundaries.
+- **Pure logic** in `stats.ts`, `timeline/`, `format-*.ts`, `tui-panel/layout.ts` — avoid pulling JSX into modules used by tests (import `layout.ts` / `palette.ts` directly, not `tui-panel/index.ts` when possible).
+- **`PLUGIN_ROOT`** in `load-config.ts` is `fileURLToPath(new URL("..", import.meta.url))` — do **not** wrap with an extra `dirname` (breaks config path).
+- **Sub-agent ids**: only from `session.list` overwrite in `child-session-sync.ts`; do not append via `session.get`.
+- **Agents UI totals**: child sessions only; main session excluded by design (see design doc).
+- Comments only for non-obvious behavior.
+
+## Configuration
+
+- Example: [cache-hit.config.example.json](cache-hit.config.example.json) — **included in npm** `files`.
+- Runtime: `cache-hit.config.json` beside package root (`CONFIG_PATH` in `load-config.ts`); **not** published; gitignored.
+- Defaults: [src/plugin-config.ts](src/plugin-config.ts).
+
+## npm publish
+
+- Tarball = `package.json` `"files"` only (source TSX, example config, docs — no `tests/`, `logs/`, user config).
+- No build step required for OpenCode `./tui` entry (`index.tsx`).
+- Run `bun test` before `npm publish`; see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## OpenCode integration
+
+- Entry: [index.tsx](index.tsx) → [src/plugin.tsx](src/plugin.tsx).
+- Slot: `sidebar_content`, `order: 56` (near visual-cache).
+- Peers: `@opencode-ai/plugin`, `@opencode-ai/sdk`, `@opentui/solid`, `solid-js` (see [package.json](package.json)).
+
+## Git / safety
+
+- Do not `git reset --hard`, `checkout --`, or force-push unless the user explicitly asks.
+- Do not commit unless asked; do not commit `logs/` or personal `cache-hit.config.json` if gitignored.
+
+## When adding features
+
+- Prefer config file over slash commands unless parity with visual-cache is an explicit goal.
+- Timeline changes: update **both** `docs/en/timeline.md` and `docs/zh-CN/timeline.md`.
+- User-facing README changes: update **English README** and mirror key points in **README.zh-CN.md**.

package/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing
+
+Development, packaging, and npm release notes for **opencode-cache-hit**. User install and configuration: [README.md](README.md) · [README.zh-CN.md](README.zh-CN.md).
+
+## Development
+
+```bash
+bun install   # dev: solid-js; peers resolved by OpenCode at runtime
+bun test
+bun run check
+```
+
+Architecture: [docs/en/design.md](docs/en/design.md). After refactors, `tests/module-load.test.ts` catches broken import paths.
+
+Coding agents: [AGENTS.md](AGENTS.md).
+
+After `bun install`, a **pre-push** hook runs `bun test` (skip with `git push --no-verify`). **CI** (GitHub Actions on `main` and PRs) runs the same tests on the server.
+
+## Configuration file (local)
+
+The plugin reads **`cache-hit.config.json`** from the package root (`PLUGIN_ROOT`, same directory as `index.tsx`). Code defaults apply if the file is missing.
+
+| File | In npm tarball? | Purpose |
+|------|-----------------|--------|
+| `cache-hit.config.example.json` | **Yes** | Template; copy and edit |
+| `cache-hit.config.json` | **No** | Your overrides (gitignored here) |
+| `logs/` | **No** | Timeline output when enabled |
+
+After OpenCode installs the package (npm or cache):
+
+```bash
+cd ~/.cache/opencode/packages/opencode-cache-hit@latest
+cp cache-hit.config.example.json cache-hit.config.json
+# edit, then restart OpenCode
+```
+
+For a **local path** in `tui.json`, put `cache-hit.config.json` in that folder (e.g. `~/.config/opencode/plugins/opencode-cache-hit/`).
+
+## Publishing to npm
+
+Published **as source** (TypeScript / TSX)—**no `dist/` build**. OpenCode loads `index.tsx` via the `./tui` export (same pattern as many TUI plugins).
+
+**Tarball contents** — `package.json` → `"files"`:
+
+- `index.tsx`, `src/`, docs, `cache-hit.config.example.json`, READMEs, `AGENTS.md`, `CONTRIBUTING.md`
+- Not included: `tests/`, `logs/`, personal `cache-hit.config.json`, `node_modules/`
+
+**npmjs.com page**
+
+| Source | Effect |
+|--------|--------|
+| `description` | One-line summary (keep under ~180 chars) |
+| `README.md` | Main package page |
+| `keywords` | Search tags |
+| `LICENSE` | License tab |
+
+`prepublishOnly` runs `bun test`. Set `author` in `package.json` before publish if not already present.
+
+**Release**
+
+```bash
+bun test
+npm publish --access public   # first time: npm login
+```
+
+[opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache) ships a `dist/` for its main export but still exposes `./tui` → source; we follow the source-only TUI entry for now.
+
+## Pull requests
+
+- Ensure the [test workflow](.github/workflows/test.yml) passes on your branch.
+- Run `bun test` locally (or rely on pre-push / CI).
+- User-facing README: update [README.md](README.md) and mirror key points in [README.zh-CN.md](README.zh-CN.md).
+- Timeline: update [docs/en/timeline.md](docs/en/timeline.md) and [docs/zh-CN/timeline.md](docs/zh-CN/timeline.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhumengzhu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+# opencode-cache-hit
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+OpenCode **TUI sidebar plugin** for prompt **cache hit rate**, **token usage**, and **cost**—with first-class **sub-agent (child session)** rollup. **Standalone by default** (main + sub-agents in one panel). Optional coexistence with [opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache).
+
+**Languages:** English (this file) · [简体中文](README.zh-CN.md) · [Documentation](docs/README.md)
+
+## Why this plugin
+
+[opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache) already covers **main-session** cache visualization (token distribution, savings, slash-driven settings). This project exists because that scope does not fit several real workflows:
+
+1. **Sub-agent visibility** — OpenCode spawns child sessions for Task / explore agents; you need **rolled-up** cache, tokens, and cost per sub-session, not only the main thread.
+2. **One panel for the whole session** — Main session Hit/tokens/cost **and** a collapsible **Agents** section for sub-agent rollup.
+3. **Analysis off the TUI** — Optional **timeline JSONL** (per assistant turn) for charts, jq, and billing post-mortems without scraping platform logs.
+4. **Shared TUI building blocks** — `src/tui-panel/` extracted so other sidebar plugins can reuse the same layout language as visual-cache.
+
+Roadmap items (sidebar Timeline section, metric windows, nested sub-agents) are described in [docs/en/timeline.md](docs/en/timeline.md) and [docs/en/design.md](docs/en/design.md).
+
+## Acknowledgments
+
+This plugin is **not** part of opencode-visual-cache. Its sidebar layout, panel components (`src/tui-panel/`), and coexistence patterns are **heavily inspired by** [opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache). visual-cache focuses on **main-session context / token distribution**; cache-hit focuses on **per-turn metrics and sub-agent totals**. We recommend installing both.
+
+## Screenshots
+
+![Cache Hit sidebar panel](docs/assets/cache-hit-panel.png)
+
+## Features
+
+- **Cache hit rate**: session total + **per-turn** rate with trend (↑ / ↓ / `-`) on the main block
+- **Token breakdown**: cache read / write / miss / output (aligned rows with visual-cache)
+- **Cost**: session cost with multi-currency config (`USD`, `CNY`, `EUR`, `GBP`, `JPY`)
+- **Sub-agents**: **Agents** section rolls up **child sessions only** (scope labeled in UI)
+- **Main + Agents**: main block always shown; **Agents** section when sub-agents exist (foldable)
+- **Collapsible sections**: Detail / Model (and Agents); theme-adaptive hit bar colors
+- **i18n**: `display.lang` — `en` / `zh` / `auto` via config (no slash commands yet)
+- **Timeline** (optional): daily JSONL per assistant turn for `jq` / scripts
+
+## Comparison with [opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache)
+
+**Standalone use is the default** (main + sub-agents in one panel). Layout patterns were inspired by visual-cache; that package is **not required**.
+
+| | visual-cache | opencode-cache-hit |
+|---|----------------|-------------------|
+| Main session context / token **distribution** estimate | Yes | No — use visual-cache |
+| Per-role token breakdown (system / tools / …) | Yes | No |
+| Cache **savings** estimate | Yes | No |
+| Model **per-million** pricing from provider | Yes | Model name + session cost only |
+| **Slash commands** (`/cache-lang`, `/cache-currency`, …) | Yes | Config file only |
+| Fold state in `api.kv` | Yes | In-session (not persisted) |
+| Loaded **skills** panel | Yes | No |
+| **Sub-agent** session rollup | No | **Yes** |
+| **Combined** hit (main + subs) | No | Yes when sub-agents exist |
+| Per-call **JSONL** export | No | Optional `timeline` |
+
+## Quick start
+
+### Option A: OpenCode command palette (recommended)
+
+`Ctrl+P` → **install plugin** → `opencode-cache-hit@latest` (when published) or your local path.
+
+### Option B: Manual
+
+Create or edit `~/.config/opencode/tui.json` / `tui.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["opencode-cache-hit@latest"]
+}
+```
+
+Local development: use `"./plugins/opencode-cache-hit"` instead of the npm name.
+
+Copy `cache-hit.config.example.json` → `cache-hit.config.json` next to the plugin root ([Configuration file](#configuration-file)). **Restart OpenCode** after changing plugin code or config.
+
+| Install | After update |
+|---------|----------------|
+| Local `./plugins/...` | Full restart |
+| npm `@latest` | Restart; if UI is stale, remove `~/.cache/opencode/packages/opencode-cache-hit@latest` |
+
+Load errors: `~/.local/share/opencode/log/` (search `cache-hit` or `failed to load tui plugin`).
+
+## Configuration
+
+### Cost display (USD → CNY example)
+
+```json
+{
+  "currency": "CNY",
+  "costUnit": "USD",
+  "rate": 7.2
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `costUnit` | Currency of `msg.cost` (usually `USD`) |
+| `currency` | Sidebar display currency |
+| `rate` | Multiply `costUnit` → `currency` |
+
+Use `"currency": "USD", "costUnit": "USD"` when no conversion is needed.
+
+Supported display currencies in config: `USD`, `CNY`, `EUR`, `GBP`, `JPY` (see `cache-hit.config.example.json`). Runtime slash switching like visual-cache’s `/cache-currency` is **not** implemented yet.
+
+### Display (`display`)
+
+```json
+"display": {
+  "lang": "en",
+  "panelBorder": true
+}
+```
+
+| Field | Default | Meaning |
+|-------|---------|---------|
+| `lang` | `"en"` | `en` / `zh` / `auto` |
+| `panelBorder` | `true` | Border/padding |
+| `mainHitLabel` | (i18n) | Optional override for the Hit row label |
+
+**Agents** totals sum **child sessions only**, not the main session (see `agentsScopeHint`). Main session metrics stay in the block above; collapse **Agents** to save space.
+
+### Timeline logs (`timeline`, default off)
+
+Per assistant turn → JSONL. [docs/en/timeline.md](docs/en/timeline.md) · [中文](docs/zh-CN/timeline.md).
+
+```json
+"timeline": {
+  "enabled": true,
+  "dir": "",
+  "rotateMaxBytes": 16777216,
+  "retainRotated": 5,
+  "maxAgeDays": 30,
+  "maxLogFiles": 20
+}
+```
+
+| Field | Default | Meaning |
+|-------|---------|---------|
+| `enabled` | `false` | Master switch |
+| `dir` | `""` | `logs/timeline-YYYY-MM-DD.jsonl` under plugin root |
+| `rotateMaxBytes` | `0` | Same-day size roll to `.jsonl.1` |
+| `retainRotated` | `5` | Backups kept per day |
+| `maxLogFiles` | `0` | Cap file count; deletes **earliest** logs first |
+
+```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"
+```
+
+Retention details: [Rotation and retention](docs/en/timeline.md#rotation-and-retention). Charts: [scripts/README.md](scripts/README.md).
+
+## Updating
+
+OpenCode may [cache plugins at first install](https://github.com/anomalyco/opencode/issues/6774) and not auto-refresh npm versions.
+
+```bash
+rm -rf ~/.cache/opencode/packages/opencode-cache-hit@latest
+```
+
+Then reinstall via `Ctrl+P` → install plugin, and **restart OpenCode**.
+
+## Compatibility
+
+Model-agnostic: any OpenCode provider that exposes assistant `tokens` / `cost` on messages (DeepSeek, Claude, GPT, etc.). Data comes from the OpenCode session API, same as visual-cache.
+
+**Requires** OpenCode with TUI plugin slots (`@opencode-ai/plugin` ≥ 1.14). Works alongside visual-cache; no extra dependencies at runtime beyond peers in [package.json](package.json).
+
+## Documentation
+
+| Audience | English | 中文 |
+|----------|---------|------|
+| Users | This README | [README.zh-CN.md](README.zh-CN.md) |
+| Maintainers | [docs/en/design.md](docs/en/design.md) | [docs/zh-CN/design.md](docs/zh-CN/design.md) |
+| Timeline / JSONL | [docs/en/timeline.md](docs/en/timeline.md) | [docs/zh-CN/timeline.md](docs/zh-CN/timeline.md) |
+| TUI panel reuse | [src/tui-panel/README.md](src/tui-panel/README.md) | [src/tui-panel/README.zh-CN.md](src/tui-panel/README.zh-CN.md) |
+| Contributing / npm | [CONTRIBUTING.md](CONTRIBUTING.md) | — |
+| Coding agents | [AGENTS.md](AGENTS.md) | — |
+| Index | [docs/README.md](docs/README.md) | |
+
+## Project layout
+
+```
+index.tsx
+cache-hit.config.example.json
+src/
+  plugin.tsx              # sidebar_content slot
+  sidebar-host.tsx        # messages, child sync, timeline
+  widget.tsx
+  stats.ts / timeline/ / tui-panel/
+tests/
+```
+
+## Configuration file
+
+Copy `cache-hit.config.example.json` → `cache-hit.config.json` next to the plugin root (`PLUGIN_ROOT`, same directory as `index.tsx`). Restart OpenCode after edits.
+
+```bash
+cd ~/.cache/opencode/packages/opencode-cache-hit@latest   # or your local plugin path
+cp cache-hit.config.example.json cache-hit.config.json
+```
+
+Details (tarball contents, local paths): [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Development
+
+```bash
+bun test
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, PR notes, and npm publishing. Architecture: [docs/en/design.md](docs/en/design.md).
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,186 @@
+# opencode-cache-hit
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+OpenCode **TUI 侧边栏插件**：展示 prompt cache 命中率、token 用量与成本；**主 session + 子 agent** 同屏汇总（默认开启主块）。可选与 [opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache) 共存。
+
+**语言：** [English](README.md) · 简体中文（本页）· [文档索引](docs/README.md)
+
+## 项目意图（为什么要做这个插件）
+
+[opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache) 已经很好地覆盖**主 session** 的 cache 可视化（Token 分布、节省估算、斜杠改配置等）。本仓库要补的是它**刻意不做或未覆盖**的部分：
+
+1. **子 agent 可观测性** — Task / explore 等会起子 session，需要把各子会话的 cache、token、费用**汇总**到侧栏。
+2. **一场对话一块面板** — 主 session 与子 agent 同屏；**Agents** 段可折叠收起。
+3. **离开 TUI 的分析** — 可选 **timeline JSONL**（按 assistant 轮次），便于画命中率曲线、jq 对账，而不去扒平台日志。
+4. **可复用 TUI 骨架** — `src/tui-panel/` 抽出来，方便做其它侧栏插件。
+
+后续（侧栏 Timeline 段、指标窗口、嵌套子 agent）见 [docs/zh-CN/timeline.md](docs/zh-CN/timeline.md)、[docs/zh-CN/design.md](docs/zh-CN/design.md)。
+
+## 致谢与借鉴说明
+
+本插件是**独立项目**，并非 opencode-visual-cache 官方维护。侧栏布局、面板组件（`src/tui-panel/`）及与 visual-cache **共存**的策略，**大量借鉴**自 [opencode-visual-cache](https://www.npmjs.com/package/opencode-visual-cache)：
+
+- visual-cache：主 session **上下文 / token 分布预估**
+- cache-hit：**按轮次指标、成本、子 agent 汇总**
+
+建议两个插件一起安装。
+
+## 截图
+
+![Cache Hit 侧边栏](docs/assets/cache-hit-panel.png)
+
+## 文档
+
+| 读者 | English | 中文 |
+|------|---------|------|
+| 使用者 | [README.md](README.md) | 本文 |
+| 维护者 | [docs/en/design.md](docs/en/design.md) | [docs/zh-CN/design.md](docs/zh-CN/design.md) |
+| 时间轴 / JSONL | [docs/en/timeline.md](docs/en/timeline.md) | [docs/zh-CN/timeline.md](docs/zh-CN/timeline.md) |
+| TUI 面板框架 | [src/tui-panel/README.md](src/tui-panel/README.md) | [src/tui-panel/README.zh-CN.md](src/tui-panel/README.zh-CN.md) |
+| 贡献 / npm | [CONTRIBUTING.md](CONTRIBUTING.md) | — |
+| AI 维护 | [AGENTS.md](AGENTS.md) | — |
+| 索引 | [docs/README.md](docs/README.md) | |
+
+## 功能一览
+
+- **命中率**：会话累计 + 主块**单轮**命中率与趋势
+- **Token 明细**：缓存读/写/未命中/输出
+- **费用**：多币种配置（`USD` / `CNY` / `EUR` / `GBP` / `JPY`）
+- **子 agent**：**Agents** 段仅汇总**子 session**（UI 有范围提示）
+- **主 session + Agents**：主块始终显示；有子 agent 时出现可折叠的 **Agents** 段
+- **可选时间轴**：按天 JSONL 落盘
+
+## 与 visual-cache 对比
+
+**默认独立使用**（主 session + 子 agent 同面板）。版式借鉴 visual-cache，**不依赖**该插件。
+
+| | visual-cache | cache-hit |
+|---|----------------|-----------|
+| 主 session 上下文 / Token **分布**估算 | 有 | 无 |
+| 按角色 Token 分布、缓存**节省**、百万 token **单价** | 有 | 无 |
+| **斜杠命令**改配置 | 有 | 仅配置文件 |
+| **子 agent** 汇总 | 无 | **有** |
+| 按次 **JSONL** | 无 | 可选 |
+
+完整英文对照表见 [README.md](README.md#comparison-with-opencode-visual-cache)。
+
+## 做什么、不做什么
+
+**本插件负责**
+
+- 主 session 与子 agent 的 cache / token / 成本聚合
+- 侧边栏 **Cache Hit** 面板（布局对齐 visual-cache）
+- 成本展示币种换算（默认 USD 成本 → CNY 显示）
+
+**本插件不负责**
+
+- 主 session 的「预估上下文 token」分布（由 visual-cache 提供）
+- 修改 OpenCode 计费；`msg.cost` 仍按 `opencode.json` 美元单价
+
+## 安装
+
+**方式一：** `Ctrl+P` → install plugin → `opencode-cache-hit@latest`（发布后）或本地路径。
+
+**方式二：** 编辑 `~/.config/opencode/tui.json` / `tui.jsonc`：
+
+```json
+{
+  "plugin": ["./plugins/opencode-cache-hit"]
+}
+```
+
+复制 `cache-hit.config.example.json` → `cache-hit.config.json`（与 `index.tsx` 同目录）。详见下文「[配置文件](#配置文件)」。
+
+| 安装方式 | 更新后 |
+|----------|--------|
+| 本地路径 | 重启 |
+| npm `@latest` | 重启；可删 `~/.cache/opencode/packages/opencode-cache-hit@latest` |
+
+加载失败：`~/.local/share/opencode/log/`（搜 `cache-hit`）。
+
+## 配置
+
+### 成本（USD → 人民币）
+
+```json
+{
+  "currency": "CNY",
+  "costUnit": "USD",
+  "rate": 7.2
+}
+```
+
+定价与展示同为美元：`"currency": "USD", "costUnit": "USD"`。
+
+### 展示（`display`）
+
+```json
+"display": {
+  "lang": "zh",
+  "panelBorder": true
+}
+```
+
+| 字段 | 默认 | 含义 |
+|------|------|------|
+| `lang` | `"en"` | `en` / `zh` / `auto` |
+| `panelBorder` | `true` | 外框与内边距 |
+| `mainHitLabel` | （i18n） | 可选，覆盖 Hit 行前缀 |
+
+**Agents 段**不含主 session token/费用（标题有「仅子会话」提示）；不需要看子 agent 时折叠 **Agents** 即可。
+
+### 时间轴日志（`timeline`，默认关闭）
+
+详见 [docs/zh-CN/timeline.md](docs/zh-CN/timeline.md)。
+
+```json
+"timeline": {
+  "enabled": true,
+  "rotateMaxBytes": 16777216,
+  "retainRotated": 5,
+  "maxAgeDays": 30,
+  "maxLogFiles": 20
+}
+```
+
+| 字段 | 代码默认 | 含义 |
+|------|----------|------|
+| `dir` | `""` | `logs/timeline-YYYY-MM-DD.jsonl` |
+| `retainRotated` | `5` | 同日大小轮转备份数 |
+| `maxLogFiles` | `0` | 超限时删**最早日期**日志 |
+
+```fish
+set 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
+```
+
+轮转与清理：[docs/zh-CN/timeline.md § 轮转与清理](docs/zh-CN/timeline.md#轮转与清理)。
+
+## 配置文件
+
+将 `cache-hit.config.example.json` 复制为 `cache-hit.config.json`，放在包根目录（与 `index.tsx` 同级）。修改后需重启 OpenCode。
+
+```bash
+cd ~/.cache/opencode/packages/opencode-cache-hit@latest   # 或本地插件路径
+cp cache-hit.config.example.json cache-hit.config.json
+```
+
+npm 打包、本地路径等说明见 [CONTRIBUTING.md](CONTRIBUTING.md)（英文）。
+
+## 开发
+
+```bash
+bun test
+```
+
+架构：[docs/zh-CN/design.md](docs/zh-CN/design.md)。贡献 / 发布：[CONTRIBUTING.md](CONTRIBUTING.md)。AI 维护：[AGENTS.md](AGENTS.md)。
+
+## 更新
+
+若 npm 版本不刷新，参见 [OpenCode #6774](https://github.com/anomalyco/opencode/issues/6774)，删除 `~/.cache/opencode/packages/opencode-cache-hit@latest` 后重装并重启。
+
+## License
+
+MIT

package/cache-hit.config.example.json

@@ -0,0 +1,22 @@
+{
+  "$comment": "lang: en | zh | auto (system locale). Default en.",
+  "currency": "CNY",
+  "costUnit": "USD",
+  "rate": 7.2,
+  "display": {
+    "lang": "en",
+    "panelBorder": true
+  },
+  "timeline": {
+    "enabled": false,
+    "dir": "",
+    "flushIncomplete": false,
+    "logSummaryMessages": true,
+    "maxMemoryRows": 50,
+    "maxLinesPerFile": 100000,
+    "rotateMaxBytes": 16777216,
+    "retainRotated": 5,
+    "maxAgeDays": 30,
+    "maxLogFiles": 20
+  }
+}

package/docs/README.md

@@ -0,0 +1,8 @@
+# Documentation
+
+| | User guide | Design | Timeline | TUI panel |
+|--|------------|--------|----------|-----------|
+| English | [README.md](../README.md) | [en/design.md](./en/design.md) | [en/timeline.md](./en/timeline.md) | [../src/tui-panel/README.md](../src/tui-panel/README.md) |
+| 中文 | [README.zh-CN.md](../README.zh-CN.md) | [zh-CN/design.md](./zh-CN/design.md) | [zh-CN/timeline.md](./zh-CN/timeline.md) | [../src/tui-panel/README.zh-CN.md](../src/tui-panel/README.zh-CN.md) |
+
+Contributing: [CONTRIBUTING.md](../CONTRIBUTING.md).