opencode-visual-cache 1.6.2 → 1.7.0-beta.1

package/src/v2/data.ts

@@ -0,0 +1,112 @@
+import type { Context, MessageInfo } from "./types"
+import { num } from "../core"
+
+/** 汇总一个会话的 token 用量与费用（V2 adapter → 同构模型）。 */
+export interface SessionStats {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+  reasoning: number
+  cost: number
+  hasData: boolean
+}
+
+/** 从 messages 汇总 token：统计全部 assistant 消息的 API 精确值。 */
+export function collectSessionStats(context: Context, sessionID: string): SessionStats {
+  const msgs = context.data.session.message.list(sessionID) ?? []
+  let input = 0
+  let output = 0
+  let cacheRead = 0
+  let cacheWrite = 0
+  let reasoning = 0
+  let cost = 0
+  let hasData = false
+
+  for (const m of msgs) {
+    if (m.type !== "assistant") continue
+    const t = m.tokens
+    if (!t) continue
+    input += num(t.input)
+    output += num(t.output)
+    reasoning += num(t.reasoning)
+    cacheRead += num(t.cache?.read)
+    cacheWrite += num(t.cache?.write)
+    hasData = true
+  }
+  // 会话级费用优先（V2 提供 cost()），消息级 cost 兜底（结构未知，宽松读取）
+  const sessionCost = context.data.session.cost(sessionID)
+  if (Number.isFinite(sessionCost) && sessionCost > 0) cost = sessionCost
+  else {
+    for (const m of msgs) {
+      if (m.type !== "assistant" || m.cost == null) continue
+      const c = m.cost as { amount?: unknown; total?: unknown } | { amount?: unknown } | number
+      if (typeof c === "number" && Number.isFinite(c)) cost += c
+      else {
+        const amt = (c as { amount?: unknown }).amount
+        if (typeof amt === "number" && Number.isFinite(amt)) cost += amt
+        else if (typeof amt === "string") {
+          const n = parseFloat(amt)
+          if (Number.isFinite(n)) cost += n
+        }
+      }
+    }
+  }
+  return { input, output, cacheRead, cacheWrite, reasoning, cost, hasData }
+}
+
+/** 缓存命中率（0–100）：缓存读 /（新鲜输入 + 缓存读 + 缓存写），与 V1 口径一致。 */
+export function hitRate(stats: SessionStats): number {
+  const denom = stats.input + stats.cacheRead + stats.cacheWrite
+  if (denom <= 0) return 0
+  return (stats.cacheRead / denom) * 100
+}
+
+/** 输入侧总量（底部栏口径，不含输出）。 */
+export function inputTotal(stats: SessionStats): number {
+  return stats.input + stats.cacheRead + stats.cacheWrite
+}
+
+/** 单条命中率（V1 底部栏口径）：最后一条有 token 的 assistant 消息，
+ *  分母含缓存写 read/(input+read+write)；prevHitRate 为上一条（趋势用）。 */
+export function collectLastHitRate(context: Context, sessionID: string): {
+  hitRate: number
+  prevHitRate: number
+  input: number
+  read: number
+  write: number
+} {
+  const msgs = context.data.session.message.list(sessionID) ?? []
+  const session = context.data.session.get(sessionID) as { tokens?: { input?: number; cache?: { read?: number; write?: number } } } | undefined
+  let input = num(session?.tokens?.input)
+  let read = num(session?.tokens?.cache?.read)
+  let write = num(session?.tokens?.cache?.write)
+  // 无 session 聚合字段 → 遍历消息累加（与 V1 fallback 一致）
+  if (session?.tokens == null) {
+    for (const m of msgs) {
+      if (m.type !== "assistant") continue
+      const t = m.tokens
+      if (!t) continue
+      input += num(t.input)
+      read += num(t.cache?.read)
+      write += num(t.cache?.write)
+    }
+  }
+  let hitRate = -1, prevHitRate = -1
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    const m = msgs[i]
+    if (m.type !== "assistant") continue
+    const tk = m.tokens
+    if (!tk) continue
+    const mit = num(tk.input) + num(tk.cache?.read) + num(tk.cache?.write)
+    const mrt = num(tk.cache?.read)
+    if (mit <= 0) continue
+    const rate = (mrt / mit) * 100
+    if (hitRate < 0) { hitRate = rate; continue }
+    prevHitRate = rate
+    break
+  }
+  return { hitRate, prevHitRate, input, read, write }
+}
+
+export type { MessageInfo }

package/src/v2/index.tsx

@@ -0,0 +1,184 @@
+/** @jsxImportSource @opentui/solid */
+
+import { createSignal, createEffect, onMount, onCleanup, untrack } from "solid-js"
+import type { Context, PluginModule } from "./types"
+import { createPanelApi } from "./v2-panel-api"
+import { TokenCachePanel } from "../panel/TokenCachePanel"
+import type { BalanceState, PanelApi, PanelSignals } from "../panel/panel-api"
+import { StatusView } from "./status"
+import { mapTheme } from "./theme"
+import { makeCommands, findOpencodeKeyV2 } from "./commands"
+import { getBalanceProvider } from "../balance-providers"
+import { LANG_META, detectLang, type LangCode } from "../i18n"
+
+const KV_PREFIX = "cache_panel"
+const BALANCE_POLL_MS = 5 * 60 * 1000 // 5 minutes（对齐 V1）
+
+// 环境变量覆盖 + 自动检测（对齐 V1：CACHE_TUI_LANG 优先，其次系统 locale）
+declare const process: { env: Record<string, string | undefined> } | undefined
+const DEBUG_LANG = typeof process !== "undefined" ? process.env?.CACHE_TUI_LANG : undefined
+const INIT_LANG: LangCode = DEBUG_LANG !== undefined && LANG_META.some((m) => m.code === DEBUG_LANG)
+  ? (DEBUG_LANG as LangCode)
+  : detectLang()
+
+/** V2 侧创建面板信号（实验：默认值；偏好持久化经 PanelApi.kv → storage.store）。
+ *  返回 PanelSignals + setBalanceState：余额轮询由 PluginRoot 驱动（V1 同构）。 */
+function createPanelSignals(): PanelSignals & { setBalanceState: (v: BalanceState) => void } {
+  const [currencySymbol, setCurrencySymbol] = createSignal("$")
+  const [exchangeRate, setExchangeRate] = createSignal(1)
+  const [langCode, setLangCode] = createSignal(INIT_LANG)
+  const [sectionDetail, setSectionDetail] = createSignal(true)
+  const [sectionModel, setSectionModel] = createSignal(true)
+  const [sectionDist, setSectionDist] = createSignal(true)
+  const [sectionSkills, setSectionSkills] = createSignal(true)
+  const [sectionBalance, setSectionBalance] = createSignal(true)
+  const [sectionBottom, setSectionBottom] = createSignal(true)
+  const [balanceRefresh, setBalanceRefresh] = createSignal(0)
+  const [balanceProviderId, setBalanceProviderId] = createSignal("")
+  const [autoBalance, setAutoBalance] = createSignal(true)
+  const [balanceUnsupported, setBalanceUnsupported] = createSignal(false)
+  const [balanceState, setBalanceState] = createSignal<BalanceState>({ status: "idle", data: null, lastFetch: 0 })
+  const [balanceCurrency, setBalanceCurrency] = createSignal("")
+  const [borderVisible, setBorderVisible] = createSignal(true)
+  const [overrideSessionId, setOverrideSessionId] = createSignal<string | undefined>(undefined)
+  const [sidebarVisible, setSidebarVisible] = createSignal(true)
+  return {
+    currencySymbol, setCurrencySymbol,
+    exchangeRate, setExchangeRate,
+    langCode: langCode as PanelSignals["langCode"], setLangCode: setLangCode as PanelSignals["setLangCode"],
+    sectionDetail, setSectionDetail,
+    sectionModel, setSectionModel,
+    sectionDist, setSectionDist,
+    sectionSkills, setSectionSkills,
+    sectionBalance, setSectionBalance,
+    sectionBottom, setSectionBottom,
+    balanceRefresh, setBalanceRefresh,
+    balanceProviderId, setBalanceProviderId,
+    autoBalance, setAutoBalance,
+    balanceUnsupported, setBalanceUnsupported,
+    balanceState,
+    setBalanceState,
+    balanceCurrency, setBalanceCurrency,
+    borderVisible, setBorderVisible,
+    overrideSessionId, setOverrideSessionId,
+    sidebarVisible, setSidebarVisible,
+  }
+}
+
+/** 面板根组件：在组件渲染上下文注册命令 layer（keymap.layer 必须由组件调用），
+ *  再渲染共享 TokenCachePanel；同时驱动余额轮询（对齐 V1 tui() 的 pollBalance）。 */
+function PluginRoot(props: {
+  context: Context
+  api: PanelApi
+  signals: PanelSignals & { setBalanceState: (v: BalanceState) => void }
+  sessionID: string
+}) {
+  // 请求序号：防止定时轮询与手动刷新并发时，慢的旧请求覆盖新结果（对齐 V1）
+  let balanceSeq = 0
+  // 对齐官方内置插件示例（feature-plugins/system/plugins.tsx）：mode 用 global
+  props.context.keymap.layer(() => ({
+    mode: "global",
+    commands: makeCommands(props.context, props.api, props.signals),
+  }))
+  // 语言偏好恢复（对齐 V1 tui() restoreLang：优先用户 /cache-lang 设置，覆盖自动检测）
+  onMount(() => {
+    try {
+      const saved = props.api.kv.get<string>(`${KV_PREFIX}.lang`)
+      if (saved && LANG_META.some((m) => m.code === saved)) {
+        props.signals.setLangCode(saved as LangCode)
+      }
+    } catch {}
+  })
+
+  // ── 余额轮询（对齐 V1 tui() pollBalance）：手动 key 优先，缺失时自动复用 OpenCode 已认证 key ──
+  const pollBalance = async () => {
+    const provider = getBalanceProvider(props.signals.balanceProviderId())
+    const key = props.api.kv.get<string>(`${KV_PREFIX}.balance.${provider.id}.key`, "")
+      || findOpencodeKeyV2(props.context, provider)
+    const set = props.signals.setBalanceState
+    if (props.signals.balanceUnsupported()) { set({ status: "idle", data: null, lastFetch: 0, error: undefined, key: undefined }); return }
+    if (!key) { set({ status: "idle", data: null, lastFetch: 0, error: undefined, key: undefined }); return }
+    const now = Date.now()
+    const prev = props.signals.balanceState()
+    // key 已更换（重新输入）→ 强制重新查询，绕过缓存
+    if (prev.status === "ok" && prev.key === key && now - prev.lastFetch < BALANCE_POLL_MS) return
+    const seq = ++balanceSeq
+    set({ ...prev, status: "loading", error: undefined, key })
+    const controller = new AbortController()
+    let timedOut = false
+    const timer = setTimeout(() => { timedOut = true; controller.abort() }, 10_000)
+    try {
+      const data = await provider.fetchBalance(key, controller.signal)
+      clearTimeout(timer)
+      if (seq !== balanceSeq) return // 已被更新的请求取代，丢弃过期结果
+      set({ status: "ok", data, lastFetch: Date.now(), error: undefined, key })
+    } catch (err) {
+      clearTimeout(timer)
+      if (seq !== balanceSeq) return
+      const code = timedOut ? "TIMEOUT" : (err instanceof Error ? err.message : "")
+      set({ status: "error", data: null, lastFetch: 0, error: code, key })
+    }
+  }
+  // Re-fetch when the API key is (re)configured via /cache-balance-key。
+  // 注意：pollBalance 内部读写 balanceState 信号，若不做 untrack 包裹，
+  // effect 会追踪 balanceState 的变化并与 setBalanceState 形成无限循环。
+  createEffect(() => {
+    void props.signals.balanceRefresh()
+    untrack(() => { void pollBalance() })
+  })
+  // 定时轮询（5 分钟）；随插件生命周期清理
+  const balanceTimer = setInterval(pollBalance, BALANCE_POLL_MS)
+  onCleanup(() => clearInterval(balanceTimer))
+
+  // auto-clear override：用户导航到不同主会话时清除子代理视图（对齐 V1 createSidebarSlot）
+  let lastSlotSid = props.sessionID
+  createEffect(() => {
+    const sid = props.sessionID
+    if (sid !== lastSlotSid) {
+      lastSlotSid = sid
+      if (props.signals.overrideSessionId()) {
+        props.signals.setOverrideSessionId(undefined)
+        void props.api.kv.set(`${KV_PREFIX}.session`, "")
+      }
+    }
+  })
+
+  return (
+    <TokenCachePanel
+      theme={mapTheme(props.context.theme)}
+      api={props.api}
+      sessionId={props.sessionID}
+      signals={props.signals}
+    />
+  )
+}
+
+const mod: PluginModule = {
+  id: "opencode-visual-cache",
+  setup(context: Context) {
+    const api = createPanelApi(context)
+    const signals = createPanelSignals()
+
+    // 侧边栏完整面板（与 V1 同一组件；命令 layer 在组件内注册）。
+    // prepend：排在宿主官方信息（问候/Context/用量）之前，紧跟会话标题。
+    context.ui.slot({
+      prepend: "sidebar.content",
+      render: (props) => (
+        <PluginRoot context={context} api={api} signals={signals} sessionID={String(props.sessionID ?? "")} />
+      ),
+    })
+
+    // 底部状态栏（完整口径与 V1 一致；余额读共享 signals.balanceState）
+    context.ui.slot({
+      append: "prompt.footer.status",
+      render: (props) => (
+        <StatusView context={context} signals={signals} sessionID={String(props.sessionID ?? "")} />
+      ),
+    })
+
+    // 偏好持久化（实验：storage.store 用法验证）
+    context.storage.store("opencode-visual-cache.panel", { initial: { collapsed: false } })
+  },
+}
+
+export default mod

package/src/v2/sidebar.tsx

@@ -0,0 +1,69 @@
+/** @jsxImportSource @opentui/solid */
+
+import { createMemo, For, Show } from "solid-js"
+import type { Context } from "./types"
+import { collectSessionStats, hitRate } from "./data"
+import { fmt, fmtCost, progressBar, visualPadEnd } from "../core"
+
+const LABEL_GAP = 1
+const BAR_BRACKETS = 2
+const BAR_GAP = 1
+const PCT_FIXED_WIDTH = 5
+const MIN_PANEL_WIDTH = 20
+const DEFAULT_PANEL_WIDTH = 26
+
+export function SidebarView(props: { context: Context; sessionID: string }) {
+  const stats = createMemo(() => collectSessionStats(props.context, props.sessionID))
+  const rate = createMemo(() => hitRate(stats()))
+  const theme = props.context.theme
+
+  const rateColor = () => {
+    const r = rate()
+    if (r >= 85) return theme.text.feedback.success.default
+    if (r >= 70) return theme.text.feedback.warning.default
+    return theme.text.feedback.error.default
+  }
+  const barWidth = () =>
+    Math.max(MIN_PANEL_WIDTH, Math.min(DEFAULT_PANEL_WIDTH, props.context.app.version ? DEFAULT_PANEL_WIDTH : DEFAULT_PANEL_WIDTH)) -
+    LABEL_GAP - BAR_BRACKETS - BAR_GAP - PCT_FIXED_WIDTH - 1
+
+  const rows = () => {
+    const s = stats()
+    return [
+      { label: "Hit", value: fmt(s.cacheRead) + " tok", color: rateColor() },
+      { label: "Miss", value: fmt(s.input + s.cacheWrite) + " tok", color: theme.text.default },
+      { label: "Write", value: fmt(s.cacheWrite) + " tok", color: theme.text.subdued },
+      { label: "Out", value: fmt(s.output) + " tok", color: theme.text.subdued },
+    ]
+  }
+
+  return (
+    <Show when={stats().hasData}>
+      <box>
+        <box flexDirection="row" gap={LABEL_GAP}>
+          <text fg={theme.text.default}>Cache</text>
+          <text fg={rateColor()}>
+            {"["}
+            {progressBar(rate(), barWidth())}
+            {"]"}
+          </text>
+          <text fg={rateColor()}>{rate().toFixed(1) + "%"}</text>
+        </box>
+        <For each={rows()}>
+          {(row) => (
+            <box flexDirection="row" gap={LABEL_GAP}>
+              <text fg={theme.text.default}>{visualPadEnd(row.label, 5)}</text>
+              <text fg={row.color}>{row.value}</text>
+            </box>
+          )}
+        </For>
+        <Show when={stats().cost > 0}>
+          <box flexDirection="row" gap={LABEL_GAP}>
+            <text fg={theme.text.default}>{"Cost"}</text>
+            <text fg={theme.text.default}>{fmtCost(stats().cost)}</text>
+          </box>
+        </Show>
+      </box>
+    </Show>
+  )
+}

package/src/v2/status.tsx

@@ -0,0 +1,96 @@
+/** @jsxImportSource @opentui/solid */
+
+import { createMemo, For, Show } from "solid-js"
+import type { Context } from "./types"
+import type { PanelSignals } from "../panel/panel-api"
+import { collectLastHitRate } from "./data"
+import { desaturateTo, fmtCompact, formatBalanceText, MAX_SAT, FALLBACK, visualWidth } from "../core"
+import { createT } from "../i18n"
+import { mapTheme } from "./theme"
+
+/**
+ * 底部状态栏（prompt.footer.status）——对齐 V1 BottomStatusBar 统计段口径：
+ * 单条命中率（最后一条有 token 的 assistant 消息）+ 趋势 + Tokens 总量 + 余额。
+ * 余额读共享 signals.balanceState（PluginRoot 驱动轮询）；provider 不支持余额时隐藏余额段（对齐 V1）。
+ * 颜色经 mapTheme（V1 形状）——与侧边栏命中率颜色同源，保证两处一致。
+ */
+export function StatusView(props: {
+  context: Context
+  signals: PanelSignals
+  sessionID: string
+}) {
+  const t = createT(() => props.signals.langCode())
+
+  // 与侧边栏 TokenCachePanel 同一颜色来源（mapTheme → desaturateTo）
+  const pal = createMemo(() => {
+    const th = mapTheme(props.context.theme) as unknown as Record<string, string>
+    const sat = (k: string, fb: string) => desaturateTo(th[k], MAX_SAT, fb)
+    return {
+      text: sat("text", FALLBACK.text),
+      muted: sat("textMuted", FALLBACK.muted),
+      success: sat("success", FALLBACK.success),
+      warning: sat("warning", FALLBACK.warning),
+      error: sat("error", FALLBACK.error),
+    }
+  })
+
+  const stats = createMemo(() => collectLastHitRate(props.context, props.sessionID))
+
+  const hitColor = createMemo(() => {
+    const r = stats().hitRate
+    if (r >= 85) return pal().success
+    if (r >= 70) return pal().warning
+    return pal().error
+  })
+
+  // 命中率趋势：最后一条与上一条的差值；|Δ| < 0.05 视为无变化（null = 不显示）
+  const trend = createMemo(() => {
+    const s = stats()
+    if (s.prevHitRate < 0 || s.hitRate < 0) return null
+    const d = s.hitRate - s.prevHitRate
+    return Math.abs(d) < 0.05 ? null : d
+  })
+
+  // 余额文本（对齐 V1）：ok → 数值；loading → …；error → ⚠；idle → -
+  const balanceText = createMemo(() => {
+    const s = props.signals.balanceState()
+    if (s.status === "ok" && s.data) return formatBalanceText(s.data, props.signals.balanceCurrency(), props.signals.exchangeRate())
+    if (s.status === "loading") return "\u2026"
+    if (s.status === "error") return "\u26a0"
+    return "-"
+  })
+
+  const segs = createMemo<{ text: string; color: string | undefined }[]>(() => {
+    const s = stats()
+    const hr = s.hitRate >= 0 ? (Math.floor(s.hitRate * 10) / 10).toFixed(1) + "%" : "--"
+    const out: { text: string; color: string | undefined }[] = [
+      { text: t("barHit") + " ", color: pal().muted },
+      { text: hr, color: hitColor() },
+    ]
+    const tr = trend()
+    if (tr !== null) {
+      out.push({ text: " " + (tr > 0 ? "\u2191" : "\u2193") + Math.abs(tr).toFixed(1) + "%", color: tr > 0 ? pal().success : pal().error })
+    }
+    out.push({ text: " \u00b7 " + t("barTok") + " ", color: pal().muted })
+    out.push({ text: s ? fmtCompact(s.input + s.read + s.write) : "--", color: pal().text })
+    if (!props.signals.balanceUnsupported()) {
+      out.push({ text: " \u00b7 " + t("barBal") + " ", color: pal().muted })
+      out.push({ text: balanceText(), color: pal().text })
+    }
+    out.push({ text: " \u00b7 ", color: pal().muted })
+    return out
+  })
+  const segsW = createMemo(() => {
+    let w = 0
+    for (const sg of segs()) w += visualWidth(sg.text)
+    return w
+  })
+
+  return (
+    <Show when={segsW() > 0}>
+      <text>
+        <For each={segs()}>{(sg) => <span style={{ fg: sg.color }}>{sg.text}</span>}</For>
+      </text>
+    </Show>
+  )
+}

package/src/v2/theme.ts

@@ -0,0 +1,19 @@
+import type { TuiThemeCurrent } from "@opencode-ai/plugin/tui"
+import type { Context } from "./types"
+
+/** V2 theme → V1 形状映射（组件按 primary/text/textMuted/… 字段消费）。
+ *  侧边栏与底部栏共用——保证命中率颜色等两处一致。
+ *  - V1 primary → V2 interactive（v1-migrate.ts 官方映射：interactive = hues.byToken.primary）
+ *  - step 取 300：更亮（对齐 V2 暗色强调惯例的亮端），500/400 在暗背景下偏深
+ */
+export function mapTheme(theme: Context["theme"]): TuiThemeCurrent {
+  return {
+    primary: theme.hue.interactive[300],
+    text: theme.text.default,
+    textMuted: theme.text.subdued,
+    success: theme.text.feedback.success.default,
+    warning: theme.text.feedback.warning.default,
+    error: theme.text.feedback.error.default,
+    border: theme.text.subdued,
+  } as unknown as TuiThemeCurrent
+}

package/src/v2/types.ts

@@ -0,0 +1,159 @@
+/**
+ * V2 (opencode2) TUI plugin API — 最小本地类型（实验版）。
+ * 运行时由 opencode2 提供，此处仅用于本地类型检查；
+ * 结构对应 v2 分支 packages/plugin/src/tui/context.ts。
+ */
+
+export interface App {
+  readonly version: string
+  readonly channel: string
+}
+
+export interface Theme {
+  readonly hue: {
+    /** V1 primary 的 V2 等价（v1-migrate.ts：interactive = hues.byToken.primary）。
+     *  取 300：更亮（暗背景下 400/500 偏深）。 */
+    readonly interactive: { readonly 300: string }
+    /** 主题强调色别名。 */
+    readonly accent: { readonly 500: string }
+  }
+  readonly text: {
+    readonly default: string
+    readonly subdued: string
+    readonly feedback: {
+      readonly success: { readonly default: string }
+      readonly error: { readonly default: string }
+      readonly warning: { readonly default: string }
+    }
+  }
+}
+
+/** token 用量：结构与 V1 的 message.tokens 同构，字段以运行时实际数据为准。 */
+export interface TokenUsage {
+  input?: number
+  output?: number
+  reasoning?: number
+  cache?: { read?: number; write?: number }
+}
+
+export interface MessageInfo {
+  readonly id: string
+  readonly type: string
+  readonly agent?: string
+  readonly model?: string
+  readonly time: { readonly created: number; readonly completed?: number }
+  readonly cost?: unknown
+  readonly tokens?: TokenUsage
+  readonly content?: unknown[]
+}
+
+export interface SessionInfo {
+  readonly id: string
+  readonly title?: string
+  readonly time?: { readonly created: number; readonly updated: number }
+  readonly model?: string
+  readonly agent?: string
+  readonly parentID?: string
+}
+
+export interface Data {
+  readonly session: {
+    get(sessionID: string): SessionInfo | undefined
+    list(): SessionInfo[]
+    cost(sessionID: string): number
+    status(sessionID: string): string
+    readonly message: {
+      list(sessionID: string): MessageInfo[]
+      sync(sessionID: string): Promise<void>
+    }
+  }
+  readonly location: {
+    readonly provider: { list(location?: unknown): unknown[] }
+    readonly model: { list(location?: unknown): unknown[] }
+    readonly mcp: { readonly server: { list(location?: unknown): unknown[] } }
+  }
+  readonly on: (type: string, handler: (event: unknown) => void) => () => void
+  readonly listen: (handler: (event: unknown) => void) => () => void
+}
+
+export interface Storage {
+  store<Value extends object>(
+    key: string,
+    options: { readonly initial: Value },
+  ): readonly [Value, (mutation: (draft: Value) => void) => Promise<void>]
+  memory<Value extends object>(
+    key: string,
+    options: { readonly initial: Value },
+  ): readonly [Value, (mutation: (draft: Value) => void) => void]
+}
+
+export type SlotClaim = {
+  readonly render: (input: Record<string, any>) => unknown
+} & (
+  | { readonly append: string; readonly prepend?: never; readonly before?: never; readonly after?: never; readonly replace?: never }
+  | { readonly prepend: string; readonly append?: never; readonly before?: never; readonly after?: never; readonly replace?: never }
+  | { readonly before: string; readonly append?: never; readonly prepend?: never; readonly after?: never; readonly replace?: never }
+  | { readonly after: string; readonly append?: never; readonly prepend?: never; readonly before?: never; readonly replace?: never }
+  | { readonly replace: string; readonly append?: never; readonly prepend?: never; readonly before?: never; readonly after?: never }
+)
+
+export interface KeymapCommand {
+  readonly id?: string
+  readonly title?: string
+  readonly description?: string
+  readonly group?: string
+  readonly palette?: true
+  readonly slash?: { readonly name: string; readonly aliases?: string[]; readonly arguments?: true }
+  /** 旧字段（opencode-dcp 兼容写法：palette 可见性 + slash 补全依赖它们） */
+  readonly namespace?: string
+  readonly name?: string
+  readonly desc?: string
+  readonly category?: string
+  readonly slashName?: string
+  readonly slashAliases?: string[]
+  readonly run: (input?: string) => void | false | Promise<void>
+}
+
+export interface Context {
+  readonly app: App
+  readonly options: Record<string, any>
+  readonly location: { readonly directory?: string } | undefined
+  readonly renderer: { readonly terminalWidth: number }
+  readonly theme: Theme
+  readonly data: Data
+  readonly storage: Storage
+  readonly ui: {
+    slot(claim: SlotClaim): () => void
+    readonly toast: {
+      show(options: { readonly message: string; readonly title?: string; readonly variant?: string }): void
+    }
+    readonly dialog: {
+      prompt(options: { readonly title: string; readonly message?: string; readonly placeholder?: string }): Promise<string | undefined>
+      select<Value>(options: {
+        readonly title: string
+        readonly placeholder?: string
+        readonly options: readonly {
+          readonly title: string
+          readonly value: Value
+          readonly description?: string
+          readonly category?: string
+          readonly disabled?: boolean
+        }[]
+        readonly current?: Value
+      }): Promise<Value | undefined>
+    }
+    /** 当前路由：命令需要当前会话 ID（V2 Route = { type: "session", sessionID }）。 */
+    readonly router: {
+      current(): { readonly type?: string; readonly sessionID?: string; readonly params?: Record<string, unknown> }
+    }
+  }
+  readonly keymap: {
+    layer(input: () => { readonly commands?: readonly KeymapCommand[] }): void
+    shortcuts(id: string): readonly string[]
+  }
+}
+
+export type PluginModule = {
+  readonly id: string
+  readonly setup: (context: Context) => void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>
+}