compressed-context 0.0.0-stage → 0.1.0

package/src/i18n/types.ts

@@ -0,0 +1,89 @@
+import type { CategoryKey } from "../shared/stats.ts"
+
+/**
+ * 面板文案。
+ *
+ * 源码里只引用键名，所有用户可见文字都来自语言文件。
+ */
+export interface Messages {
+  readonly title: string
+  readonly labels: Readonly<Record<CategoryKey, string>>
+  readonly approximate: string
+  readonly terminal: string
+  readonly cacheTitle: string
+  readonly cacheChart: string
+  readonly cacheLog: string
+  readonly cacheInput: string
+  readonly cacheOutput: string
+  readonly cacheCached: string
+  readonly cacheHit: string
+  readonly summariesTitle: string
+  readonly noData: string
+  readonly command: {
+    readonly title: string
+    readonly description: string
+    readonly group: string
+  }
+  readonly settings: {
+    readonly title: string
+    readonly show: string
+    readonly limit: string
+    readonly limitAuto: string
+    readonly limitCustom: string
+    readonly limitHint: string
+    readonly limitInvalid: string
+    readonly limitPlaceholder: string
+    readonly limitPreview: (value: string) => string
+    readonly limitCapped: (requested: string, actual: string) => string
+    readonly threshold: string
+    readonly thresholdHint: string
+    readonly thresholdInvalid: string
+    readonly thresholdPreview: (value: string) => string
+    readonly nudgeGrowth: string
+    readonly nudgeGrowthHint: string
+    readonly nudgeGrowthInvalid: string
+    readonly summaryBlockPercent: string
+    readonly summaryBlockPercentHint: string
+    readonly summaryTotalPercent: string
+    readonly summaryTotalPercentHint: string
+    readonly summaryPercentInvalid: string
+    readonly windowKnown: (value: string) => string
+    readonly windowUnknown: string
+    readonly summaryLanguage: string
+    readonly summaryFormat: string
+    readonly summaryFormatJson: string
+    readonly summaryFormatMarkdown: string
+    readonly summaryFormatBabel: string
+    readonly autoCompress: string
+    readonly enableCompressTool: string
+    readonly enableDecompressTool: string
+    readonly showTimeline: string
+    readonly showBlockTokens: string
+    readonly showCacheChart: string
+    readonly showCacheLog: string
+    readonly showSummaries: string
+    readonly categories: {
+      readonly compress: string
+      readonly summary: string
+      readonly panel: string
+      readonly decompress: string
+      readonly interface: string
+    }
+    readonly decompressInlineMax: string
+    readonly decompressInlineMaxHint: string
+    readonly decompressInlineMaxInvalid: string
+    readonly decompressTempCap: string
+    readonly decompressTempCapHint: string
+    readonly decompressTempCapInvalid: string
+    readonly decompressShowTokens: string
+    readonly submit: string
+    readonly language: string
+    readonly auto: string
+    readonly on: string
+    readonly off: string
+  }
+  readonly languages: {
+    readonly zh: string
+    readonly en: string
+  }
+}

package/src/i18n/zh.ts

@@ -0,0 +1,93 @@
+import type { Messages } from "./types.ts"
+
+/** 中文文案。标签控制在 4 个字以内，侧栏窄也能放下。 */
+export const zh: Messages = {
+  title: "上下文构成",
+  labels: {
+    system: "系统",
+    tools: "工具定义",
+    tool: "工具结果",
+    text: "文本",
+    recent: "最近保留",
+    summaries: "摘要",
+    media: "媒体",
+  },
+  approximate: "≈",
+  terminal: "上下文无法继续压缩，请开新会话或使用原生压缩",
+  cacheTitle: "缓存记录",
+  cacheChart: "折线图",
+  cacheLog: "日志",
+  cacheInput: "输入",
+  cacheOutput: "输出",
+  cacheCached: "缓存",
+  cacheHit: "命中",
+  summariesTitle: "摘要块",
+  noData: "—",
+  command: {
+    title: "压缩上下文设置",
+    description: "打开插件设置",
+    group: "插件",
+  },
+  settings: {
+    title: "压缩上下文插件设置",
+    show: "显示面板",
+    limit: "上下文上限",
+    limitAuto: "模型原生",
+    limitCustom: "自定义上限…",
+    limitHint: "填的是上限；实际窗口取「设置值」和「模型原生窗口」中较小的那个。纯数字或带 k/m 后缀",
+    limitInvalid: "请输入有效的 token 数",
+    limitPlaceholder: "200k",
+    limitPreview: (value) => `= ${value} tokens`,
+    limitCapped: (requested, actual) => `${requested}（模型上限 ${actual}）`,
+    threshold: "压缩阈值",
+    thresholdHint: "输入 60 ~ 95 之间的整数（百分比）",
+    thresholdInvalid: "阈值必须在 60 ~ 95 之间",
+    thresholdPreview: (value) => `= ${value}%`,
+    nudgeGrowth: "压缩提醒间隔",
+    nudgeGrowthHint: "上下文每增长这么多 token 提醒模型可主动压缩；0 关闭",
+    nudgeGrowthInvalid: "请输入 0，或 1k ~ 200k",
+    summaryBlockPercent: "单条摘要上限",
+    summaryBlockPercentHint: "单条摘要最多占窗口的百分比；可输入 10% 或 20k",
+    summaryTotalPercent: "全部摘要上限",
+    summaryTotalPercentHint: "所有摘要加起来最多占窗口的百分比；可输入 50% 或 100k",
+    summaryPercentInvalid: "请输入 1% ~ 90%，或一个能换算成百分比的 token 数",
+    windowKnown: (value) => `当前窗口：${value}`,
+    windowUnknown: "当前窗口未知（先跑一次模型请求）",
+    summaryLanguage: "摘要语言",
+    summaryFormat: "摘要格式",
+    summaryFormatJson: "JSON（结构化）",
+    summaryFormatMarkdown: "Markdown（自然语言）",
+    summaryFormatBabel: "Babel（模型间高密度）",
+    autoCompress: "自动压缩",
+    enableCompressTool: "compress 工具",
+    enableDecompressTool: "decompress 工具",
+    showTimeline: "块头时间线",
+    showBlockTokens: "块头 token 估算",
+    showCacheChart: "显示缓存折线图",
+    showCacheLog: "显示缓存日志",
+    showSummaries: "显示摘要块",
+    categories: {
+      compress: "压缩",
+      summary: "摘要",
+      panel: "面板",
+      decompress: "解压",
+      interface: "界面",
+    },
+    decompressInlineMax: "解压内联上限",
+    decompressInlineMaxHint: "超过这个字符数就写成临时文件；输入纯数字或带 k/m 后缀",
+    decompressInlineMaxInvalid: "请输入 1k ~ 1m 之间的字符数",
+    decompressTempCap: "解压临时文件上限",
+    decompressTempCapHint: "最多保留多少个解压临时文件",
+    decompressTempCapInvalid: "请输入 1 ~ 1000 之间的整数",
+    decompressShowTokens: "解压返回 token 估算",
+    submit: "提交",
+    language: "语言",
+    auto: "自动",
+    on: "开",
+    off: "关",
+  },
+  languages: {
+    zh: "中文",
+    en: "English",
+  },
+}

package/src/index.ts

@@ -0,0 +1,108 @@
+import { Plugin } from "@opencode/plugin"
+
+import { maybeAutoCompress, maybeAutoCompressStep, maybeNudge } from "./compression/auto.ts"
+import { recordCacheHistoryStep } from "./compression/cache-history.ts"
+import { adoptNativeCheckpoint } from "./compression/adopt.ts"
+import { handleCompaction } from "./compression/compaction.ts"
+import { reconcileAll, startSessionEvents } from "./compression/events.ts"
+import { registerSettingsRpc, type Disposable } from "./compression/settings-rpc.ts"
+import { loadState } from "./compression/state.ts"
+import { registerCompressTool } from "./compression/tool.ts"
+import { registerDecompressTool } from "./compression/decompress-tool.ts"
+import { createStats, mergeMetadata, shouldPublish, type ContextStats } from "./shared/stats.ts"
+import { estimateCategories } from "./shared/tokens.ts"
+
+export default Plugin.define({
+  id: "compressed-context",
+
+  /**
+   * 输入：OpenCode 注入的插件上下文 ctx。
+   * 输出：注册 compress 工具、设置 RPC、context / compaction 钩子与事件订阅。
+   * 预期：块链通过 compaction 落盘；失败不破坏历史。
+   */
+  async setup(ctx) {
+    const published = new Map<string, ContextStats>()
+    const disposables: Disposable[] = []
+
+    /** 输入：sessionID；输出：无；预期：会话空闲/删除时清掉进程内统计缓存。 */
+    const forgetMemory = (sessionID: string): void => {
+      published.delete(sessionID)
+    }
+
+    const publishStats = async (sessionID: string, stats: ContextStats): Promise<void> => {
+      const session = await ctx.session.get({ sessionID })
+      await ctx.session.update({
+        sessionID,
+        metadata: mergeMetadata(session.metadata, stats),
+      })
+    }
+
+    disposables.push(await registerCompressTool(ctx))
+    disposables.push(await registerDecompressTool(ctx))
+    disposables.push(await registerSettingsRpc(ctx))
+    const stopEvents = startSessionEvents(ctx, {
+      onSessionIdle: forgetMemory,
+      onSessionDeleted: forgetMemory,
+      onStepEnded: ({ sessionID, messageID, tokens }) =>
+        void (async () => {
+          await recordCacheHistoryStep(ctx, sessionID, { messageID, tokens })
+          await maybeAutoCompressStep({ ctx, sessionID, tokens })
+        })(),
+    })
+    void reconcileAll(ctx)
+
+    disposables.push(
+      await ctx.session.hook("context", async (event) => {
+        await adoptNativeCheckpoint(ctx, event.sessionID, event.messages)
+
+        await maybeNudge({
+          ctx,
+          sessionID: event.sessionID,
+          messages: event.messages,
+          system: event.system,
+          tools: event.tools,
+          model: event.model,
+        })
+
+        const stats = createStats(
+          estimateCategories({
+            system: event.system,
+            tools: event.tools,
+            messages: event.messages,
+          }),
+          Date.now(),
+        )
+        if (shouldPublish(published.get(event.sessionID), stats)) {
+          published.set(event.sessionID, stats)
+          void publishStats(event.sessionID, stats).catch(() => undefined)
+        }
+
+        await maybeAutoCompress({
+          ctx,
+          sessionID: event.sessionID,
+          messages: event.messages,
+          system: event.system,
+          tools: event.tools,
+          model: event.model,
+        })
+      }),
+    )
+
+    disposables.push(
+      await ctx.session.hook("compaction", (event) => handleCompaction(ctx, event)),
+    )
+
+    // 终止后拒绝一切新输入：把真实原因直接抛给宿主，TUI 会显示这条错误。
+    disposables.push(
+      await ctx.session.hook("prompt", async (event) => {
+        const state = await loadState(ctx.storage, event.sessionID)
+        if (state.terminal !== undefined) throw new Error(state.terminal)
+      }),
+    )
+
+    return () => {
+      stopEvents()
+      for (const disposable of disposables) void disposable.dispose()
+    }
+  },
+})

package/src/shared/blocks.ts

@@ -0,0 +1,17 @@
+/**
+ * 摘要块的跨进程 DTO。
+ *
+ * 服务端把 active 链渲染成 body，TUI 只负责展示。
+ */
+export interface SummaryBlock {
+  readonly id: string
+  readonly tier: 1 | 2 | 3
+  /** 摘要格式；Babel 正文不能按 Markdown 渲染。 */
+  readonly format: "json" | "markdown" | "babel"
+  readonly title: string
+  readonly at: number
+  readonly tokensBefore: number
+  readonly tokensAfter: number
+  readonly sourceBlockIds?: readonly string[]
+  readonly body: string
+}

package/src/shared/cache.ts

@@ -0,0 +1,199 @@
+/**
+ * 缓存命中历史的跨进程载体。
+ *
+ * 服务端插件在 session.idle 时把最近 10 条 assistant 消息的 usage 追加到
+ * storage（`cache:history:<sessionID>`）；TUI 通过 RPC 读取。
+ * 本模块只放纯函数：采样、追加、校验、排序，方便单测。
+ */
+
+/** 每个会话一份，key 里带 sessionID，父/子会话互不影响。 */
+export const CACHE_HISTORY_PREFIX = "cache:history:"
+
+/** 只保留最近 10 次请求。 */
+export const CACHE_HISTORY_LIMIT = 10
+
+/** 一条缓存命中样本；hitRate 是 0..100，向下截断到两位小数。 */
+export interface CacheSample {
+  readonly messageID: string
+  readonly at: number
+  readonly input: number
+  readonly output: number
+  readonly cached: number
+  readonly hitRate: number
+}
+
+/** storage 里的持久化结构。 */
+export interface CacheHistory {
+  readonly v: 1
+  readonly samples: readonly CacheSample[]
+}
+
+export const EMPTY_CACHE_HISTORY: CacheHistory = { v: 1, samples: [] }
+
+/**
+ * 输入：总输入 token + 命中 token。
+ * 输出：0..100 的百分比，向下截断到两位小数。
+ * 预期：不四舍五入；99.999% 显示 99.99，不会变成 100.00。
+ */
+export function hitRatePercent(input: number, cached: number): number {
+  if (input <= 0) return 0
+  return Math.floor(Math.min(1, cached / input) * 10_000) / 100
+}
+
+/** 输入：命中率；输出：固定两位小数的百分比文本（不含 `%`）。 */
+export function formatHitRate(hitRate: number): string {
+  return hitRate.toFixed(2)
+}
+
+/** 输入：sessionID；输出：该会话的 storage key。 */
+export function cacheHistoryKey(sessionID: string): string {
+  return CACHE_HISTORY_PREFIX + sessionID
+}
+
+/**
+ * 输入：消息（结构最小化，便于测试替身）。
+ * 输出：assistant 且带 tokens 时返回样本，否则 undefined。
+ */
+export interface CacheMessage {
+  readonly id: string
+  readonly type: string
+  readonly time?: { readonly created?: number }
+  readonly tokens?: {
+    readonly input: number
+    readonly output: number
+    readonly reasoning: number
+    readonly cache: { readonly read: number; readonly write: number }
+  }
+}
+
+/** 输入：消息 + 缺时间时的回退值；输出：样本或 undefined。 */
+export function sampleFromMessage(message: CacheMessage, fallbackAt: number): CacheSample | undefined {
+  if (message.type !== "assistant") return undefined
+  const tokens = message.tokens
+  if (tokens === undefined) return undefined
+  const input = tokens.input + tokens.cache.read + tokens.cache.write
+  const output = tokens.output + tokens.reasoning
+  const cached = tokens.cache.read
+  return {
+    messageID: message.id,
+    at: message.time?.created ?? fallbackAt,
+    input,
+    output,
+    cached,
+    hitRate: hitRatePercent(input, cached),
+  }
+}
+
+/** 输入：样本列表；输出：按时间升序、去重、只留最新 10 条。 */
+function normalizeSamples(samples: readonly CacheSample[]): readonly CacheSample[] {
+  const unique = new Map<string, CacheSample>()
+  for (const sample of samples) {
+    // 同一条消息重复出现时保留第一次记录，避免重试把同一条刷成多条。
+    if (!unique.has(sample.messageID)) unique.set(sample.messageID, sample)
+  }
+  return [...unique.values()]
+    .sort((left, right) => left.at - right.at || left.messageID.localeCompare(right.messageID))
+    .slice(-CACHE_HISTORY_LIMIT)
+}
+
+/**
+ * 输入：已有历史 + 当前可见消息。
+ * 输出：追加未记录过的 assistant 样本后的新历史。
+ * 预期：按 messageID 去重；按时间排序；只保留最新 10 条。
+ */
+export function appendCacheSamples(
+  existing: readonly CacheSample[],
+  messages: readonly CacheMessage[],
+  now: number = Date.now(),
+): readonly CacheSample[] {
+  const known = new Set(existing.map((sample) => sample.messageID))
+  const added: CacheSample[] = []
+  for (const message of messages) {
+    if (known.has(message.id)) continue
+    const sample = sampleFromMessage(message, now)
+    if (sample === undefined) continue
+    known.add(sample.messageID)
+    added.push(sample)
+  }
+  return normalizeSamples([...existing, ...added])
+}
+
+/**
+ * 输入：已有历史 + 单个 step 的 assistant usage。
+ * 输出：追加该 step 样本后的新历史。
+ * 预期：tool loop 里 context/usage.updated 拿不到最新 step usage，
+ *       `session.step.ended` 事件直接携带 tokens，这里按 messageID 去重落一条。
+ */
+export function appendCacheSampleFromStep(
+  existing: readonly CacheSample[],
+  messageID: string,
+  tokens: {
+    readonly input: number
+    readonly output: number
+    readonly reasoning: number
+    readonly cache: { readonly read: number; readonly write: number }
+  },
+  fallbackAt: number = Date.now(),
+): readonly CacheSample[] {
+  return appendCacheSamples(existing, [{ id: messageID, type: "assistant", tokens }], fallbackAt)
+}
+
+/** 输入：任意 storage 值；输出：合法历史；损坏时返回空历史，绝不抛错。hitRate 按 input/cached 重算。 */
+export function parseCacheHistory(value: unknown): CacheHistory {
+  if (typeof value !== "object" || value === null) return EMPTY_CACHE_HISTORY
+  const record = value as Record<string, unknown>
+  if (record["v"] !== 1 || !Array.isArray(record["samples"])) return EMPTY_CACHE_HISTORY
+  const samples: CacheSample[] = []
+  for (const item of record["samples"]) {
+    if (typeof item !== "object" || item === null) continue
+    const sample = item as Record<string, unknown>
+    const messageID = sample["messageID"]
+    const at = sample["at"]
+    const input = sample["input"]
+    const output = sample["output"]
+    const cached = sample["cached"]
+    if (typeof messageID !== "string" || messageID.length === 0) continue
+    if (
+      typeof at !== "number" ||
+      !Number.isFinite(at) ||
+      at < 0 ||
+      typeof input !== "number" ||
+      !Number.isFinite(input) ||
+      input < 0 ||
+      typeof output !== "number" ||
+      !Number.isFinite(output) ||
+      output < 0 ||
+      typeof cached !== "number" ||
+      !Number.isFinite(cached) ||
+      cached < 0
+    ) {
+      continue
+    }
+    samples.push({
+      messageID,
+      at,
+      input,
+      output,
+      cached,
+      hitRate: hitRatePercent(input, cached),
+    })
+  }
+  return { v: 1, samples: normalizeSamples(samples) }
+}
+
+/** 输入：两条历史；输出：样本是否完全一致；用于避免无变化的重复写盘。 */
+export function cacheHistoryEquals(left: readonly CacheSample[], right: readonly CacheSample[]): boolean {
+  if (left.length !== right.length) return false
+  return left.every((sample, index) => {
+    const other = right[index]
+    if (other === undefined) return false
+    return (
+      sample.messageID === other.messageID &&
+      sample.at === other.at &&
+      sample.input === other.input &&
+      sample.output === other.output &&
+      sample.cached === other.cached &&
+      sample.hitRate === other.hitRate
+    )
+  })
+}

package/src/shared/format.ts

@@ -0,0 +1,23 @@
+/**
+ * 面板数字格式化。
+ *
+ * 输入：token 数量（非负整数）。
+ * 输出：紧凑字符串：<1000 原样、<10000 一位小数 k、<1e6 取整 k、
+ *       <1e7 一位小数 M、更大取整 M。
+ * 预期：侧栏一行内放得下。
+ */
+export function formatTokens(count: number): string {
+  if (!Number.isFinite(count) || count <= 0) return "0"
+  if (count < 1_000) return count.toString()
+  if (count < 10_000) return `${(count / 1_000).toFixed(1)}k`
+  if (count < 1_000_000) return `${Math.round(count / 1_000).toString()}k`
+  if (count < 10_000_000) return `${(count / 1_000_000).toFixed(1)}M`
+  return `${Math.round(count / 1_000_000).toString()}M`
+}
+
+/** 输入：毫秒时间戳；输出：本地时间 `YYYY/MM/DD HH:mm`；预期：固定格式，不依赖 locale。 */
+export function formatTimestamp(at: number): string {
+  const date = new Date(at)
+  const pad = (value: number): string => value.toString().padStart(2, "0")
+  return `${date.getFullYear().toString()}/${pad(date.getMonth() + 1)}/${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`
+}