opencode-cache-hit 0.1.0

package/scripts/plot-hit-rate.ts

@@ -0,0 +1,222 @@
+#!/usr/bin/env bun
+/**
+ * Plot cache hit % from timeline JSONL (Bun, no npm deps).
+ *
+ *   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 ses_xxx -o hit.svg
+ *   bun scripts/plot-hit-rate.ts logs/timeline-2026-05-31.jsonl --by-root -o hit.svg
+ */
+
+type Row = {
+  rootSessionId?: string
+  scope?: string
+  created?: number
+  completedAt?: number
+  hitPercent?: number | null
+  skippedForHit?: boolean
+}
+
+type Point = { t: number; y: number }
+
+const COLORS = ["#3fb950", "#58a6ff", "#d29922", "#f85149", "#a371f7", "#79c0ff"]
+
+function parseArgs(argv: string[]) {
+  const positional: string[] = []
+  let root: string | undefined
+  let output: string | undefined
+  let byRoot = false
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === "--root") root = argv[++i]
+    else if (a === "--by-root") byRoot = true
+    else if (a === "-o" || a === "--output") output = argv[++i]
+    else if (!a.startsWith("-")) positional.push(a)
+  }
+  if (!positional[0]) {
+    console.error(
+      "usage: bun scripts/plot-hit-rate.ts <file.jsonl> [--root ID | --by-root] [-o out.svg]",
+    )
+    process.exit(1)
+  }
+  return { file: positional[0], root, byRoot, output }
+}
+
+async function loadRecords(path: string, root?: string): Promise<Row[]> {
+  const text = await Bun.file(path).text()
+  const rows: Row[] = []
+  for (const line of text.split("\n")) {
+    const s = line.trim()
+    if (!s) continue
+    const rec = JSON.parse(s) as Row
+    if (root && rec.rootSessionId !== root) continue
+    if (rec.skippedForHit) continue
+    if (rec.hitPercent == null) continue
+    rows.push(rec)
+  }
+  return rows
+}
+
+function timeOf(r: Row): number {
+  return r.completedAt ?? r.created ?? 0
+}
+
+function groupByRoot(rows: Row[]): Map<string, Row[]> {
+  const map = new Map<string, Row[]>()
+  for (const r of rows) {
+    const id = r.rootSessionId ?? "(unknown)"
+    const list = map.get(id) ?? []
+    list.push(r)
+    map.set(id, list)
+  }
+  for (const list of map.values()) {
+    list.sort((a, b) => timeOf(a) - timeOf(b))
+  }
+  return new Map([...map.entries()].sort((a, b) => a[0].localeCompare(b[0])))
+}
+
+function shortId(id: string, max = 20): string {
+  return id.length <= max ? id : `…${id.slice(-max)}`
+}
+
+function asciiChart(values: number[], width = 48, height = 8): string {
+  const grid: string[][] = Array.from({ length: height }, () => Array(width).fill(" "))
+  const row = (v: number) =>
+    Math.min(height - 1, Math.max(0, Math.round((v / 100) * (height - 1))))
+  for (let i = 0; i < values.length; i++) {
+    const x = Math.round((i / Math.max(1, values.length - 1)) * (width - 1))
+    grid[height - 1 - row(values[i])][x] = "●"
+  }
+  const yLabels = ["100", " 50", "  0"]
+  return grid.map((line, i) => `${yLabels[i] ?? "    "} │${line.join("")}`).join("\n")
+}
+
+function esc(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;")
+}
+
+function svgChartSingle(values: number[], title: string, w = 640, h = 240): string {
+  const pad = { l: 48, r: 16, t: 24, b: 32 }
+  const innerW = w - pad.l - pad.r
+  const innerH = h - pad.t - pad.b
+  const pts = values.map((v, i) => {
+    const x = pad.l + (i / Math.max(1, values.length - 1)) * innerW
+    const y = pad.t + innerH - (v / 100) * innerH
+    return { x, y, v }
+  })
+  const poly = pts.map((p) => `${p.x.toFixed(1)},${p.y.toFixed(1)}`).join(" ")
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">
+  <rect width="100%" height="100%" fill="#0d1117"/>
+  <text x="${pad.l}" y="16" fill="#e6edf3" font-family="system-ui,sans-serif" font-size="12">${esc(title)}</text>
+  <line x1="${pad.l}" y1="${pad.t + innerH}" x2="${pad.l + innerW}" y2="${pad.t + innerH}" stroke="#30363d"/>
+  <line x1="${pad.l}" y1="${pad.t}" x2="${pad.l}" y2="${pad.t + innerH}" stroke="#30363d"/>
+  <text x="8" y="${pad.t + 4}" fill="#8b949e" font-size="10">100%</text>
+  <text x="8" y="${pad.t + innerH}" fill="#8b949e" font-size="10">0%</text>
+  <polyline fill="none" stroke="${COLORS[0]}" stroke-width="2" points="${poly}"/>
+  ${pts.map((p) => `<circle cx="${p.x.toFixed(1)}" cy="${p.y.toFixed(1)}" r="3" fill="${COLORS[0]}"/>`).join("\n  ")}
+</svg>`
+}
+
+function svgChartByRoot(
+  series: { id: string; points: Point[] }[],
+  title: string,
+  w = 720,
+  h = 280,
+): string {
+  const pad = { l: 48, r: 16, t: 28, b: 56 }
+  const innerW = w - pad.l - pad.r
+  const innerH = h - pad.t - pad.b
+  let tMin = Infinity
+  let tMax = -Infinity
+  for (const s of series) {
+    for (const p of s.points) {
+      if (p.t < tMin) tMin = p.t
+      if (p.t > tMax) tMax = p.t
+    }
+  }
+  const span = Math.max(1, tMax - tMin)
+  const toXY = (p: Point) => ({
+    x: pad.l + ((p.t - tMin) / span) * innerW,
+    y: pad.t + innerH - (p.y / 100) * innerH,
+  })
+
+  const bodies: string[] = []
+  const legend: string[] = []
+  series.forEach((s, i) => {
+    const color = COLORS[i % COLORS.length]
+    const xy = s.points.map(toXY)
+    const poly = xy.map((p) => `${p.x.toFixed(1)},${p.y.toFixed(1)}`).join(" ")
+    bodies.push(
+      `<polyline fill="none" stroke="${color}" stroke-width="2" points="${poly}"/>`,
+    )
+    for (const p of xy) {
+      bodies.push(`<circle cx="${p.x.toFixed(1)}" cy="${p.y.toFixed(1)}" r="2.5" fill="${color}"/>`)
+    }
+    const ly = pad.t + innerH + 18 + i * 14
+    legend.push(
+      `<line x1="${pad.l}" y1="${ly - 4}" x2="${pad.l + 20}" y2="${ly - 4}" stroke="${color}" stroke-width="2"/>`,
+      `<text x="${pad.l + 26}" y="${ly}" fill="#e6edf3" font-size="11" font-family="ui-monospace,monospace">${esc(shortId(s.id))} (${s.points.length})</text>`,
+    )
+  })
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">
+  <rect width="100%" height="100%" fill="#0d1117"/>
+  <text x="${pad.l}" y="18" fill="#e6edf3" font-family="system-ui,sans-serif" font-size="12">${esc(title)}</text>
+  <line x1="${pad.l}" y1="${pad.t + innerH}" x2="${pad.l + innerW}" y2="${pad.t + innerH}" stroke="#30363d"/>
+  <line x1="${pad.l}" y1="${pad.t}" x2="${pad.l}" y2="${pad.t + innerH}" stroke="#30363d"/>
+  <text x="8" y="${pad.t + 4}" fill="#8b949e" font-size="10">100%</text>
+  <text x="8" y="${pad.t + innerH}" fill="#8b949e" font-size="10">0%</text>
+  ${bodies.join("\n  ")}
+  ${legend.join("\n  ")}
+</svg>`
+}
+
+const { file, root, byRoot, output } = parseArgs(process.argv.slice(2))
+const allRows = await loadRecords(file, root)
+
+if (allRows.length === 0) {
+  console.error("no plottable rows (check --root or hitPercent)")
+  process.exit(1)
+}
+
+const useByRoot = byRoot && !root
+
+if (useByRoot) {
+  const groups = groupByRoot(allRows)
+  console.log(`${groups.size} root session(s), ${allRows.length} calls total`)
+  for (const [id, list] of groups) {
+    const hits = list.map((r) => r.hitPercent as number)
+    const avg = hits.reduce((a, b) => a + b, 0) / hits.length
+    console.log(`  ${shortId(id, 28)}: ${list.length} calls, avg hit ${avg.toFixed(1)}%`)
+  }
+  if (output) {
+    const series = [...groups.entries()].map(([id, list]) => ({
+      id,
+      points: list.map((r) => ({ t: timeOf(r), y: r.hitPercent as number })),
+    }))
+    await Bun.write(output, svgChartByRoot(series, `${file} · by rootSessionId`))
+    console.log("")
+    console.log(`wrote ${output} (${groups.size} series)`)
+  } else {
+    console.log("")
+    console.log("tip: add -o /tmp/hit.svg (time-aligned, one color per rootSessionId)")
+  }
+} else {
+  const sorted = [...allRows].sort((a, b) => timeOf(a) - timeOf(b))
+  const hits = sorted.map((r) => r.hitPercent as number)
+  const avg = hits.reduce((a, b) => a + b, 0) / hits.length
+  const label = root ? ` (${shortId(root)})` : " (all roots merged)"
+  console.log(`${sorted.length} calls, avg hit ${avg.toFixed(1)}%${label}`)
+  console.log("")
+  console.log(asciiChart(hits))
+  if (output) {
+    const title = root ? `${file} · ${shortId(root)}` : `${file} · merged`
+    await Bun.write(output, svgChartSingle(hits, title))
+    console.log("")
+    console.log(`wrote ${output}`)
+  } else {
+    console.log("")
+    console.log("tip: -o /tmp/hit.svg | --by-root for multi-session chart")
+  }
+}

package/src/agents-view.tsx

@@ -0,0 +1,55 @@
+/** @jsxImportSource @opentui/solid */
+import { For, Show } from "solid-js"
+import { TokenDetailRows } from "./cache-hit-rows.tsx"
+import type { CacheHitMetrics } from "./use-cache-hit-metrics.ts"
+import { aggregateSubAgents } from "./stats.ts"
+import { formatTokenCount } from "./format-tokens.ts"
+import { TuiMetricRow, truncateVisual, type PanelLayout } from "./tui-panel/index.ts"
+import type { SubAgentSummary } from "./types.ts"
+
+function agentRowLabel(id: string, gauge: number): string {
+  const tail = id.length > 10 ? id.slice(-8) : id
+  const raw = id.length > 10 ? "\u2026" + tail : tail
+  return truncateVisual(raw, Math.max(6, gauge - 14))
+}
+
+function subHasActivity(sub: SubAgentSummary): boolean {
+  return sub.cost > 0 || sub.cacheRead > 0 || sub.cacheWrite > 0 || sub.input > 0
+}
+
+export function AgentsView(props: {
+  m: CacheHitMetrics
+  layout: PanelLayout
+  formatCost: (n: number) => string
+}) {
+  const { m, layout } = props
+  const total = () => aggregateSubAgents(m.subs())
+
+  return (
+    <>
+      <TokenDetailRows pal={m.pal()} layout={layout} t={m.t()} snap={total()} />
+      <Show when={total().cost > 0}>
+        <TuiMetricRow
+          pal={m.pal()}
+          layout={layout}
+          label={m.t().cost}
+          value={props.formatCost(total().cost)}
+          fg={m.pal().success}
+        />
+      </Show>
+      <For each={m.subs()}>
+        {(sub) => (
+          <Show when={subHasActivity(sub)}>
+            <TuiMetricRow
+              pal={m.pal()}
+              layout={layout}
+              label={"  " + agentRowLabel(sub.id, layout.gauge())}
+              value={sub.cost > 0 ? props.formatCost(sub.cost) : formatTokenCount(sub.input)}
+              unit={sub.cost > 0 ? "" : m.t().tok}
+            />
+          </Show>
+        )}
+      </For>
+    </>
+  )
+}

package/src/cache-hit-rows.tsx

@@ -0,0 +1,68 @@
+/** @jsxImportSource @opentui/solid */
+import { Show, type JSX } from "solid-js"
+import type { UiStrings } from "./i18n.ts"
+import { formatTokenCount } from "./format-tokens.ts"
+import { TuiMetricRow } from "./tui-panel/index.ts"
+import type { PanelLayout, PanelPalette } from "./tui-panel/index.ts"
+import type { SessionSnapshot } from "./types.ts"
+
+export type TokenSnap = Pick<
+  SessionSnapshot,
+  "cacheRead" | "cacheWrite" | "input" | "output" | "reasoning"
+>
+
+export function TokenDetailRows(props: {
+  pal: PanelPalette
+  layout: PanelLayout
+  t: UiStrings
+  snap: TokenSnap
+  children?: JSX.Element
+}) {
+  const tok = (n: number) => formatTokenCount(n)
+  return (
+    <>
+      <Show when={props.snap.cacheRead > 0}>
+        <TuiMetricRow
+          pal={props.pal}
+          layout={props.layout}
+          label={props.t.read}
+          value={tok(props.snap.cacheRead)}
+          unit={props.t.tok}
+        />
+      </Show>
+      <Show when={props.snap.cacheWrite > 0}>
+        <TuiMetricRow
+          pal={props.pal}
+          layout={props.layout}
+          label={props.t.write}
+          value={tok(props.snap.cacheWrite)}
+          unit={props.t.tok}
+        />
+      </Show>
+      <TuiMetricRow
+        pal={props.pal}
+        layout={props.layout}
+        label={props.t.miss}
+        value={tok(props.snap.input)}
+        unit={props.t.tok}
+      />
+      <TuiMetricRow
+        pal={props.pal}
+        layout={props.layout}
+        label={props.t.out}
+        value={tok(props.snap.output)}
+        unit={props.t.tok}
+      />
+      <Show when={props.snap.reasoning > 0}>
+        <TuiMetricRow
+          pal={props.pal}
+          layout={props.layout}
+          label={props.t.reasoning}
+          value={tok(props.snap.reasoning)}
+          unit={props.t.tok}
+        />
+      </Show>
+      {props.children}
+    </>
+  )
+}

package/src/child-session-sync.ts

@@ -0,0 +1,93 @@
+import { childSessionIdsForParent, parseSessionListResponse } from "./session-list.ts"
+import type { OpenCodeTuiApi } from "./types.ts"
+
+/** Debounce for session.list after foreign-session message.updated (streaming fires often). */
+export const CHILD_LIST_DEBOUNCE_MS = 200
+
+/** Pass `api.client.session`, never `api.client`. */
+export type ChildSessionListClient = OpenCodeTuiApi["client"]["session"]
+
+/**
+ * Keeps child session ids in sync with session.list for a single parent session.
+ * - Parent change: invalidate in-flight work, clear ids, list immediately.
+ * - Foreign message.updated: debounced list (source of truth; no append-only).
+ */
+export function createChildSessionSync(opts: {
+  client: ChildSessionListClient
+  getDirectory: () => string
+  getParentId: () => string
+  setChildIds: (ids: string[]) => void
+  onSynced?: () => void
+  debounceMs?: number
+}) {
+  let listGen = 0
+  let debounceTimer: ReturnType<typeof setTimeout> | undefined
+
+  const clearDebounce = () => {
+    if (debounceTimer !== undefined) clearTimeout(debounceTimer)
+    debounceTimer = undefined
+  }
+
+  const loadChildren = () => {
+    clearDebounce()
+    const parentId = opts.getParentId()
+    if (!parentId) {
+      opts.setChildIds([])
+      return
+    }
+    const gen = listGen
+    const directory = opts.getDirectory()
+    opts.client
+      .list({ query: { directory } })
+      .then(
+        (all) => {
+          if (gen !== listGen || opts.getParentId() !== parentId) return
+          opts.setChildIds(childSessionIdsForParent(parseSessionListResponse(all), parentId))
+          opts.onSynced?.()
+        },
+        () => {
+          if (gen !== listGen || opts.getParentId() !== parentId) return
+          opts.setChildIds([])
+        },
+      )
+  }
+
+  const scheduleLoad = () => {
+    clearDebounce()
+    if (!opts.getParentId()) return
+    const ms = opts.debounceMs ?? CHILD_LIST_DEBOUNCE_MS
+    debounceTimer = setTimeout(() => {
+      debounceTimer = undefined
+      loadChildren()
+    }, ms)
+  }
+
+  /** Call when the sidebar parent session id changes. */
+  const resetForParentChange = () => {
+    listGen++
+    clearDebounce()
+    opts.setChildIds([])
+  }
+
+  /** message.updated on a session other than the current parent. */
+  const onForeignSessionActivity = (sessionId: string | undefined) => {
+    const parentId = opts.getParentId()
+    if (!parentId || !sessionId || sessionId === parentId) return
+    scheduleLoad()
+  }
+
+  const dispose = () => {
+    listGen++
+    clearDebounce()
+  }
+
+  return {
+    loadChildren,
+    scheduleLoad,
+    resetForParentChange,
+    onForeignSessionActivity,
+    dispose,
+    /** Test hook: current generation token. */
+    _generation: () => listGen,
+  }
+}

package/src/format-cache-ui.ts

@@ -0,0 +1,21 @@
+/** deltaPercent: change in hit % points. Visual-cache trendLabel (0 → "-"). */
+export function formatTrendLabel(deltaPercent: number): string {
+  const t = deltaPercent
+  return (t > 0 ? "\u2191" : t < 0 ? "\u2193" : "-") + (t !== 0 ? Math.abs(t).toFixed(1) + "%" : "")
+}
+
+/** One decimal place, e.g. 98.8% */
+export function formatPercentOneDecimal(percent0to100: number): string {
+  return (Math.floor(percent0to100 * 10) / 10).toFixed(1) + "%"
+}
+
+export function formatRatioAsPercent(ratio0to1: number): string {
+  return formatPercentOneDecimal(ratio0to1 * 100)
+}
+
+/** Block chars only — wrap with `[` `]` in UI. */
+export function formatHitBar(ratio: number, width = 16): string {
+  const filled = Math.max(0, Math.min(width, Math.round(ratio * width)))
+  const empty = Math.max(0, width - filled)
+  return "\u2588".repeat(filled) + "\u2591".repeat(empty)
+}

package/src/format-cost.ts

@@ -0,0 +1,90 @@
+export type CurrencyCode = "USD" | "CNY" | "EUR" | "GBP" | "JPY"
+
+/** How to render msg.cost in the sidebar. */
+export type CostDisplayConfig = {
+  /** Display currency (symbol / decimals). */
+  currency: CurrencyCode
+  symbol?: string
+  decimals?: number
+  minDisplay?: number
+  /** Unit of msg.cost from OpenCode (typically USD per opencode.json). */
+  costUnit?: CurrencyCode
+  /** USD → display currency. Shorthand for convert.rate. */
+  rate?: number
+  convert?: { from: CurrencyCode; rate: number }
+}
+
+export const CURRENCY_PRESETS: Record<CurrencyCode, { symbol: string; decimals: number; minDisplay: number }> = {
+  USD: { symbol: "$", decimals: 4, minDisplay: 0.0001 },
+  CNY: { symbol: "¥", decimals: 3, minDisplay: 0.01 },
+  EUR: { symbol: "€", decimals: 3, minDisplay: 0.01 },
+  GBP: { symbol: "£", decimals: 3, minDisplay: 0.01 },
+  JPY: { symbol: "¥", decimals: 2, minDisplay: 1 },
+}
+
+/** OpenCode msg.cost is USD; show RMB by default. */
+export const DEFAULT_COST_DISPLAY: CostDisplayConfig = {
+  currency: "CNY",
+  costUnit: "USD",
+  rate: 7.2,
+}
+
+function resolveExchangeRate(cfg: CostDisplayConfig): number {
+  if (cfg.convert?.rate && cfg.convert.rate > 0) return cfg.convert.rate
+  if (cfg.rate && cfg.rate > 0) return cfg.rate
+  const unit = cfg.costUnit ?? "USD"
+  if (unit === cfg.currency) return 1
+  return 1
+}
+
+export function normalizeCostDisplay(raw: unknown): CostDisplayConfig {
+  if (!raw || typeof raw !== "object") return { ...DEFAULT_COST_DISPLAY }
+  const o = raw as Record<string, unknown>
+  const currency =
+    typeof o.currency === "string" && o.currency in CURRENCY_PRESETS
+      ? (o.currency as CurrencyCode)
+      : DEFAULT_COST_DISPLAY.currency
+
+  const cfg: CostDisplayConfig = { currency }
+
+  if (typeof o.symbol === "string" && o.symbol.length > 0) cfg.symbol = o.symbol
+  if (typeof o.decimals === "number" && o.decimals >= 0) cfg.decimals = o.decimals
+  if (typeof o.minDisplay === "number" && o.minDisplay > 0) cfg.minDisplay = o.minDisplay
+
+  if (typeof o.costUnit === "string" && o.costUnit in CURRENCY_PRESETS) {
+    cfg.costUnit = o.costUnit as CurrencyCode
+  }
+
+  if (typeof o.rate === "number" && o.rate > 0) cfg.rate = o.rate
+
+  const c = o.convert
+  if (c && typeof c === "object") {
+    const co = c as Record<string, unknown>
+    if (typeof co.from === "string" && co.from in CURRENCY_PRESETS && typeof co.rate === "number" && co.rate > 0) {
+      cfg.convert = { from: co.from as CurrencyCode, rate: co.rate }
+    }
+  }
+
+  if (!cfg.costUnit && !cfg.convert) cfg.costUnit = DEFAULT_COST_DISPLAY.costUnit
+  if (!cfg.rate && !cfg.convert?.rate && cfg.costUnit !== cfg.currency) {
+    cfg.rate = DEFAULT_COST_DISPLAY.rate
+  }
+
+  return cfg
+}
+
+export function createCostFormatter(config: CostDisplayConfig): (amountUsd: number) => string {
+  const preset = CURRENCY_PRESETS[config.currency]
+  const symbol = config.symbol ?? preset.symbol
+  const decimals = config.decimals ?? preset.decimals
+  const minDisplay = config.minDisplay ?? preset.minDisplay
+  const unit = config.costUnit ?? config.convert?.from ?? "USD"
+  const rate = unit === config.currency ? 1 : resolveExchangeRate(config)
+
+  return (amount: number) => {
+    if (amount <= 0) return ""
+    const v = amount * rate
+    if (v < minDisplay) return `<${symbol}${minDisplay}`
+    return "~" + symbol + v.toFixed(decimals)
+  }
+}

package/src/format-tokens.ts

@@ -0,0 +1,5 @@
+export function formatTokenCount(n: number): string {
+  if (n >= 1_000_000) return (n / 1_000_000).toFixed(1) + "M"
+  if (n >= 1_000) return (n / 1_000).toFixed(1) + "K"
+  return String(Math.round(n))
+}

package/src/i18n.ts

@@ -0,0 +1,82 @@
+export type Lang = "en" | "zh"
+
+export type UiStrings = {
+  title: string
+  hit: string
+  totalHit: string
+  read: string
+  write: string
+  miss: string
+  out: string
+  reasoning: string
+  cost: string
+  withAgents: string
+  hitFolded: string
+  noData: string
+  secDetail: string
+  secModel: string
+  model: string
+  secAgents: string
+  /** Shown in Agents section header: totals are child sessions only, not the parent session. */
+  agentsScopeHint: string
+  tok: string
+}
+
+const EN: UiStrings = {
+  title: "Cache Hit",
+  hit: "Hit",
+  totalHit: "Total Hit:",
+  read: "Read:",
+  write: "Write:",
+  miss: "Miss:",
+  out: "Out:",
+  reasoning: "Reason:",
+  cost: "Cost:",
+  withAgents: "w/ Agents:",
+  hitFolded: "hit",
+  noData: "Waiting for cache data...",
+  secDetail: "Detail",
+  secModel: "Model",
+  model: "Model:",
+  secAgents: "Agents",
+  agentsScopeHint: " · sub-sessions",
+  tok: "tok",
+}
+
+const ZH: UiStrings = {
+  title: "缓存命中",
+  hit: "命中率",
+  totalHit: "总命中:",
+  read: "缓存读:",
+  write: "缓存写:",
+  miss: "未命中:",
+  out: "输出:",
+  reasoning: "推理:",
+  cost: "费用:",
+  withAgents: "含 Agents:",
+  hitFolded: "命中",
+  noData: "等待缓存数据...",
+  secDetail: "明细",
+  secModel: "模型",
+  model: "模型:",
+  secAgents: "子 Agent",
+  agentsScopeHint: " · 仅子会话",
+  tok: "tok",
+}
+
+export function resolveLang(raw: unknown): Lang {
+  if (raw === "zh" || raw === "cn" || raw === "zh-CN") return "zh"
+  if (raw === "en") return "en"
+  if (raw === "auto") {
+    try {
+      return Intl.DateTimeFormat().resolvedOptions().locale.toLowerCase().startsWith("zh") ? "zh" : "en"
+    } catch {
+      return "en"
+    }
+  }
+  return "en"
+}
+
+export function getUiStrings(lang: Lang): UiStrings {
+  return lang === "zh" ? ZH : EN
+}

package/src/load-config.ts

@@ -0,0 +1,29 @@
+import { existsSync, readFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import {
+  type PluginConfig,
+  normalizePluginConfig,
+  DEFAULT_PLUGIN_CONFIG,
+} from "./plugin-config.ts"
+
+/** Parent of `src/` (plugin package root). Do not wrap in `dirname` — `..` already resolves there. */
+export const PLUGIN_ROOT = fileURLToPath(new URL("..", import.meta.url))
+export const CONFIG_PATH = join(PLUGIN_ROOT, "cache-hit.config.json")
+
+function cloneDefault(): PluginConfig {
+  return {
+    cost: { ...DEFAULT_PLUGIN_CONFIG.cost },
+    display: { ...DEFAULT_PLUGIN_CONFIG.display },
+    timeline: { ...DEFAULT_PLUGIN_CONFIG.timeline },
+  }
+}
+
+export function loadPluginConfig(): PluginConfig {
+  if (!existsSync(CONFIG_PATH)) return cloneDefault()
+  try {
+    return normalizePluginConfig(JSON.parse(readFileSync(CONFIG_PATH, "utf8")))
+  } catch {
+    return cloneDefault()
+  }
+}