compressed-context 0.0.0-stage → 0.1.1

package/src/compression/tool.ts

@@ -0,0 +1,142 @@
+import type { Plugin } from "@opencode/plugin"
+import { Schema } from "effect"
+
+import { resolveSummaryLimits } from "../shared/settings.ts"
+import { createT1Block } from "./block.ts"
+import { toSummary } from "./normalize.ts"
+import { SummaryInput } from "./schema.ts"
+import { RESOLVED_WINDOW_KEY, loadServerSettings, windowKey } from "./settings.ts"
+import { eligibleMessages, messageRange, type MessageLike } from "./select.ts"
+import { sessionMessagesToMessageLikes } from "./session-message.ts"
+import { loadState, saveState, withPending } from "./state.ts"
+import type { Disposable } from "./settings-rpc.ts"
+import { buildTranscript } from "./transcript.ts"
+import { saveTranscript } from "./transcript-store.ts"
+import { MIN_SOURCE_CHARS, validateSummary } from "./validate.ts"
+
+const DESCRIPTION =
+  "Compress the conversation so far into a structured checkpoint. Call this when the context is getting full. " +
+  "It covers every message since the last compressed block, up to the current user message, and replaces them with " +
+  "one block. In JSON mode provide `goal` plus the optional fields; in Markdown mode provide `markdown`; in Babel " +
+  "mode provide `babel` with first line `T=<short title>|G=<one-line goal>` and a dense body. Omit any " +
+  "optional field that has no real content instead of inventing entries. Do not call while a compression is already " +
+  "pending. " +
+  "Add a short title if useful. " +
+  "The block is the only remaining record of those messages, so copy exact paths with line numbers, signatures, the " +
+  "code lines that carry the logic, error text, versions, config keys, thresholds, and measured values. " +
+  "Use `files` only for real file paths; put config keys and function names in `facts`. " +
+  "Put work in `progress.completed` only when it was actually finished; plans go in `progress.active` or `open_items`. " +
+  "Give the reason for each decision, keep the objective and any pivots, why important actions were taken, unanswered " +
+  "questions, and work the user still expects. Describe the past as past, not as a new instruction. " +
+  "Leave out logs, repeated reads, exploration that produced nothing, abandoned attempts (one line on why), and " +
+  "repeated status checks. If space is tight, keep objective and constraints first, then decisions and reasons, then " +
+  "exact technical facts, then conclusions, then lessons. Write short factual entries, not prose."
+
+function failure(message: string) {
+  return {
+    output: { block: "", status: "error" },
+    content: `ERROR: ${message}`,
+    metadata: { error: true },
+  }
+}
+
+/**
+ * 输入：服务端上下文。
+ * 输出：注册 compress 工具。
+ * 预期：执行时从会话上下文按需取消息，不再把整段历史常驻内存。
+ */
+export async function registerCompressTool(
+  ctx: Plugin.Context,
+  legacyCache?: ReadonlyMap<string, readonly MessageLike[]>,
+): Promise<Disposable> {
+  const registration = await ctx.tool.transform((tools) => {
+    tools.add({
+      name: "compress",
+      options: { codemode: false },
+      description: DESCRIPTION,
+      input: SummaryInput,
+      output: Schema.Struct({ block: Schema.String, status: Schema.String }),
+      execute: async (input, toolCtx) => {
+        const sessionID = toolCtx.sessionID
+        const state = await loadState(ctx.storage, sessionID)
+        if (state.terminal !== undefined) return failure(state.terminal)
+        if (state.pending || state.phase !== undefined) return failure("compression already in progress")
+
+        let eligible: readonly MessageLike[] | undefined
+        try {
+          const raw = await ctx.session.context({ sessionID })
+          eligible = eligibleMessages(sessionMessagesToMessageLikes(raw))
+        } catch {
+          // 兼容旧测试替身；生产路径不传 legacyCache。
+          eligible = legacyCache === undefined ? undefined : (legacyCache.get(sessionID) ?? [])
+        }
+        if (eligible === undefined) return failure("failed to read session context")
+        const transcript = buildTranscript(eligible)
+        const sourceChars = transcript.length
+        if (eligible.length === 0) return failure("nothing to compress")
+        if (sourceChars < MIN_SOURCE_CHARS) {
+          return failure(
+            `not enough content to compress (${sourceChars.toString()} chars, min ${MIN_SOURCE_CHARS.toString()})`,
+          )
+        }
+
+        const settings = await loadServerSettings(ctx.storage)
+        if (!settings.enableCompressTool) return failure("compress tool is disabled in settings")
+        // 优先用当前会话模型自己的窗口；取不到再回退最近一次解析值。
+        let windowTokens: number | undefined
+        try {
+          const session = await ctx.session.get({ sessionID })
+          const model = session.model
+          const stored =
+            model === undefined ? undefined : await ctx.storage.get(windowKey(model.providerID, model.id))
+          if (typeof stored === "number" && stored > 0) windowTokens = stored
+        } catch {
+          // 会话或模型未知：回退到最近一次解析值
+        }
+        if (windowTokens === undefined) {
+          const resolved = await ctx.storage.get(RESOLVED_WINDOW_KEY)
+          if (typeof resolved === "number" && resolved > 0) windowTokens = resolved
+        }
+        const limits = resolveSummaryLimits(settings, windowTokens)
+        const summary = toSummary(input, settings.summaryFormat)
+        if (summary === undefined) return failure("invalid summary shape")
+        const validation = validateSummary(summary, sourceChars, undefined, limits.blockChars)
+        if (!validation.ok) return failure(validation.message)
+
+        const range = messageRange(eligible)
+        if (range === undefined) {
+          return failure("messages are missing ids")
+        }
+
+        const block = createT1Block({
+          blocks: state.blocks,
+          summary,
+          fromId: range.fromId,
+          toId: range.toId,
+          sourceChars,
+        })
+
+        // transcript 落盘失败不应阻断摘要；解压时会降级为占位符。
+        try {
+          await saveTranscript(ctx.storage, sessionID, block, eligible)
+        } catch {
+          // best effort
+        }
+
+        await saveState(ctx.storage, sessionID, withPending(state, block))
+        try {
+          await ctx.session.compact({ sessionID })
+        } catch (error) {
+          await saveState(ctx.storage, sessionID, { ...state, lastError: String(error) })
+          return failure(`failed to start compaction: ${String(error)}`)
+        }
+
+        return {
+          output: { block: block.id, status: "queued" },
+          content: `queued compression ${block.id}`,
+        }
+      },
+    })
+  })
+  return registration
+}

package/src/compression/transcript-store.ts

@@ -0,0 +1,258 @@
+import type { Schema } from "effect"
+
+import { isSessionDeleted } from "./deleted-sessions.ts"
+import { forEachScannedEntry } from "../shared/scan.ts"
+import type { Block, StorageLike } from "./state.ts"
+import type { MediaSourceLike, MessageLike } from "./select.ts"
+
+/** 落盘的媒体 source：bytes 统一转 base64；url/ref 只存引用。 */
+export interface StoredMediaSource {
+  readonly type: "base64" | "url" | "ref" | "unknown"
+  readonly data?: string
+  readonly mediaType?: string
+  readonly url?: string
+  readonly provider?: string
+  readonly id?: string
+  readonly expiresAt?: number
+}
+
+/** 落盘的单条 part；reasoning 不进入这里。 */
+export interface StoredPart {
+  readonly type: "text" | "tool-call" | "tool-result" | "media"
+  readonly text?: string
+  readonly name?: string
+  readonly input?: unknown
+  readonly result?: unknown
+  readonly filename?: string
+  readonly media?: {
+    readonly source: StoredMediaSource
+    readonly info?: unknown
+  }
+}
+
+/** 落盘的单条消息。 */
+export interface StoredMessage {
+  readonly id?: string
+  readonly role: string
+  readonly content: readonly StoredPart[]
+}
+
+/** 一个 T1 块的 transcript manifest；消息本体按 msg:<index> 分开存。 */
+export interface TranscriptManifest {
+  readonly v: 1
+  readonly sessionID: string
+  readonly blockID: string
+  readonly fromId: string
+  readonly toId: string
+  readonly count: number
+  readonly createdAt: number
+}
+
+const PREFIX = "compression:transcript:"
+
+/** 输入：sessionID；输出：该会话全部 transcript key 的公共前缀。 */
+export function transcriptSessionPrefix(sessionID: string): string {
+  return `${PREFIX}${sessionID}:`
+}
+
+/** 输入：sessionID + blockID；输出：manifest key。 */
+export function transcriptManifestKey(sessionID: string, blockID: string): string {
+  return `${transcriptSessionPrefix(sessionID)}${blockID}:manifest`
+}
+
+/** 输入：sessionID + blockID + 序号；输出：单条消息 key。 */
+export function transcriptMessageKey(sessionID: string, blockID: string, index: number): string {
+  return `${transcriptSessionPrefix(sessionID)}${blockID}:msg:${index.toString()}`
+}
+
+/** 输入：任意数据；输出：是否 Uint8Array。 */
+function isBytes(value: unknown): value is Uint8Array {
+  return value instanceof Uint8Array
+}
+
+/** 输入：media source；输出：可 JSON 化的 source；未知形状保留 unknown。 */
+function storeSource(source: MediaSourceLike | undefined): StoredMediaSource {
+  if (source === undefined) return { type: "unknown" }
+  if (source.type === "bytes") {
+    const data = isBytes(source.data)
+      ? Buffer.from(source.data).toString("base64")
+      : typeof source.data === "string"
+        ? source.data
+        : ""
+    return {
+      type: "base64",
+      ...(data.length === 0 ? {} : { data }),
+      ...(source.mediaType === undefined ? {} : { mediaType: source.mediaType }),
+    }
+  }
+  if (source.type === "base64") {
+    return {
+      type: "base64",
+      ...(typeof source.data === "string" ? { data: source.data } : {}),
+      ...(source.mediaType === undefined ? {} : { mediaType: source.mediaType }),
+    }
+  }
+  if (source.type === "url") {
+    return {
+      type: "url",
+      ...(source.url === undefined ? {} : { url: source.url }),
+      ...(source.mediaType === undefined ? {} : { mediaType: source.mediaType }),
+      ...(source.expiresAt === undefined ? {} : { expiresAt: source.expiresAt }),
+    }
+  }
+  if (source.type === "ref") {
+    return {
+      type: "ref",
+      ...(source.provider === undefined ? {} : { provider: source.provider }),
+      ...(source.id === undefined ? {} : { id: source.id }),
+      ...(source.mediaType === undefined ? {} : { mediaType: source.mediaType }),
+    }
+  }
+  return { type: "unknown", ...(source.mediaType === undefined ? {} : { mediaType: source.mediaType }) }
+}
+
+/** 输入：可压缩消息；输出：落盘消息；预期：跳过 reasoning 和其他未知 part。 */
+export function toStoredMessage(message: MessageLike): StoredMessage {
+  const content: StoredPart[] = []
+  for (const part of message.content) {
+    if (part.type === "text" && typeof part.text === "string") {
+      content.push({ type: "text", text: part.text })
+      continue
+    }
+    if (part.type === "tool-call") {
+      content.push({
+        type: "tool-call",
+        ...(part.name === undefined ? {} : { name: part.name }),
+        input: part.input,
+      })
+      continue
+    }
+    if (part.type === "tool-result") {
+      content.push({
+        type: "tool-result",
+        ...(part.name === undefined ? {} : { name: part.name }),
+        result: part.result,
+      })
+      continue
+    }
+    if (part.type === "media") {
+      content.push({
+        type: "media",
+        ...(part.filename === undefined ? {} : { filename: part.filename }),
+        media: {
+          source: storeSource(part.media?.source),
+          ...(part.media?.info === undefined ? {} : { info: part.media.info }),
+        },
+      })
+    }
+  }
+  return {
+    ...(message.id === undefined ? {} : { id: message.id }),
+    role: message.role,
+    content,
+  }
+}
+
+/**
+ * 输入：storage + 会话 + T1 块 + 覆盖的消息。
+ * 输出：无。
+ * 预期：先写 manifest，再逐条写消息；删除墓碑存在时整体跳过。
+ */
+export async function saveTranscript(
+  storage: StorageLike,
+  sessionID: string,
+  block: Pick<Block, "id" | "fromId" | "toId">,
+  messages: readonly MessageLike[],
+): Promise<void> {
+  if (isSessionDeleted(sessionID)) return
+  const manifest: TranscriptManifest = {
+    v: 1,
+    sessionID,
+    blockID: block.id,
+    fromId: block.fromId,
+    toId: block.toId,
+    count: messages.length,
+    createdAt: Date.now(),
+  }
+  await storage.set(transcriptManifestKey(sessionID, block.id), manifest as unknown as Schema.Json)
+  for (const [index, message] of messages.entries()) {
+    await storage.set(
+      transcriptMessageKey(sessionID, block.id, index),
+      toStoredMessage(message) as unknown as Schema.Json,
+    )
+  }
+}
+
+/** 输入：storage + 会话 + 块；输出：合法 manifest 或 undefined。 */
+export async function loadTranscriptManifest(
+  storage: StorageLike,
+  sessionID: string,
+  blockID: string,
+): Promise<TranscriptManifest | undefined> {
+  const raw = await storage.get(transcriptManifestKey(sessionID, blockID))
+  if (typeof raw !== "object" || raw === null) return undefined
+  const record = raw as Record<string, unknown>
+  if (
+    record["v"] !== 1 ||
+    typeof record["sessionID"] !== "string" ||
+    typeof record["blockID"] !== "string" ||
+    typeof record["fromId"] !== "string" ||
+    typeof record["toId"] !== "string" ||
+    typeof record["count"] !== "number" ||
+    !Number.isInteger(record["count"]) ||
+    record["count"] < 0
+  ) {
+    return undefined
+  }
+  return {
+    v: 1,
+    sessionID: record["sessionID"],
+    blockID: record["blockID"],
+    fromId: record["fromId"],
+    toId: record["toId"],
+    count: record["count"],
+    createdAt: typeof record["createdAt"] === "number" ? record["createdAt"] : 0,
+  }
+}
+
+/** 输入：storage + 会话 + 块 + 序号；输出：落盘消息或 undefined。 */
+export async function loadTranscriptMessage(
+  storage: StorageLike,
+  sessionID: string,
+  blockID: string,
+  index: number,
+): Promise<StoredMessage | undefined> {
+  const raw = await storage.get(transcriptMessageKey(sessionID, blockID, index))
+  if (typeof raw !== "object" || raw === null) return undefined
+  const record = raw as Record<string, unknown>
+  if (typeof record["role"] !== "string" || !Array.isArray(record["content"])) return undefined
+  return {
+    ...(typeof record["id"] === "string" ? { id: record["id"] } : {}),
+    role: record["role"],
+    content: record["content"] as StoredPart[],
+  }
+}
+
+/** 输入：storage + 会话；输出：无；预期：删掉该会话所有 manifest/message key。 */
+export async function deleteTranscriptsForSession(
+  storage: StorageLike & {
+    scan?: (options: { prefix: string; limit: number; after?: string }) => Promise<{
+      entries: readonly { key: string; value: unknown }[]
+      next?: string
+    }>
+  },
+  sessionID: string,
+): Promise<void> {
+  await forEachScannedEntry(storage, transcriptSessionPrefix(sessionID), async (entry) => {
+    await storage.remove(entry.key)
+  })
+}
+
+/** 输入：storage + 会话 + 块；输出：manifest 是否存在。 */
+export async function hasTranscript(
+  storage: StorageLike,
+  sessionID: string,
+  blockID: string,
+): Promise<boolean> {
+  return (await loadTranscriptManifest(storage, sessionID, blockID)) !== undefined
+}

package/src/compression/transcript.ts

@@ -0,0 +1,63 @@
+import { stringify, toolInput, toolResult, toolResultText } from "../shared/parts.ts"
+import type { ContentPartLike, MessageLike } from "./select.ts"
+
+/** 单条工具输出最多保留的字符数。 */
+const TOOL_RESULT_MAX = 2_000
+/** 工具调用参数最多保留的字符数。 */
+const TOOL_INPUT_MAX = 500
+/** 整份 transcript 的字符上限，防止侧调用自身溢出。 */
+export const TRANSCRIPT_MAX = 200_000
+
+function truncate(value: string, max: number): string {
+  return value.length <= max ? value : `${value.slice(0, max)}…[truncated]`
+}
+
+function renderMessage(message: MessageLike): string {
+  const lines: string[] = []
+  if (typeof message.text === "string" && message.text.length > 0) {
+    lines.push(message.role === "user" ? `[User]\n${message.text}` : message.text)
+  }
+  const content: readonly ContentPartLike[] = Array.isArray(message.content)
+    ? message.content
+    : []
+  for (const part of content) {
+    if (part.type === "text") {
+      const text = part.text ?? ""
+      if (text.length > 0) lines.push(message.role === "user" ? `[User]\n${text}` : text)
+      continue
+    }
+    if (part.type === "tool") {
+      lines.push(`[Tool call ${part.name ?? "?"}] ${truncate(stringify(toolInput(part)), TOOL_INPUT_MAX)}`)
+      lines.push(`[Tool result ${part.name ?? "?"}] ${truncate(toolResultText(toolResult(part)), TOOL_RESULT_MAX)}`)
+      continue
+    }
+    if (part.type === "tool-call") {
+      lines.push(`[Tool call ${part.name ?? "?"}] ${truncate(stringify(toolInput(part)), TOOL_INPUT_MAX)}`)
+      continue
+    }
+    if (part.type === "tool-result") {
+      lines.push(`[Tool result ${part.name ?? "?"}] ${truncate(toolResultText(toolResult(part)), TOOL_RESULT_MAX)}`)
+    }
+  }
+  return lines.join("\n")
+}
+
+/**
+ * 输入：可压缩消息。
+ * 输出：给侧调用使用的纯文本 transcript。
+ * 预期：跳过 reasoning/media；工具输出截断；整体超限时丢弃最老的消息。
+ */
+export function buildTranscript(messages: readonly MessageLike[]): string {
+  const rendered = messages.map(renderMessage).filter((text) => text.length > 0)
+  let total = rendered.reduce((sum, text) => sum + text.length + 2, 0)
+  let start = 0
+  while (total > TRANSCRIPT_MAX && start < rendered.length - 1) {
+    const item = rendered[start]
+    if (item === undefined) break
+    total -= item.length + 2
+    start += 1
+  }
+  const kept = rendered.slice(start)
+  const prefix = start > 0 ? `[older messages omitted: ${start.toString()}]\n\n` : ""
+  return prefix + kept.join("\n\n")
+}

package/src/compression/validate.ts

@@ -0,0 +1,81 @@
+import { isBabelSummary, isMarkdownSummary, type Summary } from "./schema.ts"
+import { summaryChars } from "./summary.ts"
+
+export const MIN_SUMMARY_CHARS = 200
+export const MIN_MERGE_SUMMARY_CHARS = 80
+export const MIN_ULTRA_SUMMARY_CHARS = 40
+export const MAX_SUMMARY_CHARS = 20_000
+
+/** 输入：层级；输出：该层允许的最短摘要字符数。 */
+export function minSummaryChars(tier: 1 | 2 | 3): number {
+  if (tier === 3) return MIN_ULTRA_SUMMARY_CHARS
+  if (tier === 2) return MIN_MERGE_SUMMARY_CHARS
+  return MIN_SUMMARY_CHARS
+}
+/** 可压缩原文的最小字符数，低于它不生成块。 */
+export const MIN_SOURCE_CHARS = 5_000
+
+export interface ValidationResult {
+  readonly ok: boolean
+  readonly fields: readonly string[]
+  readonly message: string
+}
+
+/**
+ * 输入：结构化摘要或 Markdown 摘要 + 原文总字符数。
+ * 输出：校验结果。
+ * 预期：JSON 检查字段；Markdown 检查标题/正文/长度，且摘要必须比原文小。
+ */
+export function validateSummary(
+  summary: Summary,
+  sourceChars: number,
+  minChars: number = MIN_SUMMARY_CHARS,
+  maxChars: number = MAX_SUMMARY_CHARS,
+): ValidationResult {
+  const fields: string[] = []
+  if (isBabelSummary(summary)) {
+    if (summary.title.trim().length === 0 || summary.title.length > 80) fields.push("title")
+    if (summary.goal.trim().length === 0) fields.push("goal")
+    const body = summary.text.split(/\r?\n/).slice(1).join("\n").trim()
+    if (body.length === 0) fields.push("text")
+  } else if (isMarkdownSummary(summary)) {
+    if (summary.title.trim().length === 0 || summary.title.length > 80) fields.push("title")
+    if (summary.text.trim().length === 0) fields.push("text")
+  } else {
+    if (summary.goal.trim().length === 0) fields.push("goal")
+    if (summary.title.trim().length === 0 || summary.title.length > 80) fields.push("title")
+    if (summary.constraints.some((item) => item.trim().length === 0)) fields.push("constraints")
+    if (summary.decisions.some((item) => item.trim().length === 0)) fields.push("decisions")
+    if (summary.open_items.some((item) => item.trim().length === 0)) fields.push("open_items")
+    if (summary.files.some((item) => item.trim().length === 0)) fields.push("files")
+    if (summary.facts.some((item) => item.trim().length === 0)) fields.push("facts")
+  }
+
+  if (fields.length > 0) {
+    return { ok: false, fields, message: `empty field: ${fields.join(", ")}` }
+  }
+
+  const chars = summaryChars(summary)
+  if (chars < minChars) {
+    return {
+      ok: false,
+      fields: ["summary"],
+      message: `summary too short (${chars.toString()} chars, min ${minChars.toString()})`,
+    }
+  }
+  if (chars > maxChars) {
+    return {
+      ok: false,
+      fields: ["summary"],
+      message: `summary too long (${chars.toString()} chars, max ${maxChars.toString()})`,
+    }
+  }
+  if (sourceChars > 0 && chars >= sourceChars) {
+    return {
+      ok: false,
+      fields: ["summary"],
+      message: `summary (${chars.toString()} chars) is not smaller than the source (${sourceChars.toString()} chars)`,
+    }
+  }
+  return { ok: true, fields: [], message: "ok" }
+}

package/src/i18n/en.ts

@@ -0,0 +1,93 @@
+import type { Messages } from "./types.ts"
+
+/** English copy. Labels stay short so they fit the narrow sidebar. */
+export const en: Messages = {
+  title: "Context breakdown",
+  labels: {
+    system: "System",
+    tools: "Tool defs",
+    tool: "Tool I/O",
+    text: "Text",
+    recent: "Kept",
+    summaries: "Summary",
+    media: "Media",
+  },
+  approximate: "≈",
+  terminal: "Context cannot be compressed further; start a new session or use native compaction",
+  cacheTitle: "Cache",
+  cacheChart: "Chart",
+  cacheLog: "Log",
+  cacheInput: "In",
+  cacheOutput: "Out",
+  cacheCached: "Cached",
+  cacheHit: "Hit",
+  summariesTitle: "Summaries",
+  noData: "—",
+  command: {
+    title: "Compressed context settings",
+    description: "Open plugin settings",
+    group: "Plugins",
+  },
+  settings: {
+    title: "Compressed context plugin settings",
+    show: "Show panel",
+    limit: "Context limit",
+    limitAuto: "Model native",
+    limitCustom: "Custom limit…",
+    limitHint: "Upper bound; the effective window is the smaller of this value and the model's native window. Digits or a k/m suffix",
+    limitInvalid: "Enter a valid token count",
+    limitPlaceholder: "200k",
+    limitPreview: (value) => `= ${value} tokens`,
+    limitCapped: (requested, actual) => `${requested} (model max ${actual})`,
+    threshold: "Compression threshold",
+    thresholdHint: "Enter an integer between 60 and 95 (percent)",
+    thresholdInvalid: "Threshold must be between 60 and 95",
+    thresholdPreview: (value) => `= ${value}%`,
+    nudgeGrowth: "Compression reminder",
+    nudgeGrowthHint: "Remind the model after this much context growth; 0 disables it",
+    nudgeGrowthInvalid: "Enter 0, or 1k to 200k",
+    summaryBlockPercent: "Summary block limit",
+    summaryBlockPercentHint: "Max share of the window for one summary; enter 10% or 20k",
+    summaryTotalPercent: "Total summary limit",
+    summaryTotalPercentHint: "Max share of the window for all summaries; enter 50% or 100k",
+    summaryPercentInvalid: "Enter 1% to 90%, or a token count that fits the window",
+    windowKnown: (value) => `Current window: ${value}`,
+    windowUnknown: "Current window unknown (run one model request first)",
+    summaryLanguage: "Summary language",
+    summaryFormat: "Summary format",
+    summaryFormatJson: "JSON (structured)",
+    summaryFormatMarkdown: "Markdown (natural language)",
+    summaryFormatBabel: "Babel (model-to-model dense)",
+    autoCompress: "Auto compression",
+    enableCompressTool: "compress tool",
+    enableDecompressTool: "decompress tool",
+    showTimeline: "Block timeline",
+    showBlockTokens: "Block token estimate",
+    showCacheChart: "Show cache chart",
+    showCacheLog: "Show cache log",
+    showSummaries: "Show summary blocks",
+    categories: {
+      compress: "Compression",
+      summary: "Summary",
+      panel: "Panel",
+      decompress: "Decompression",
+      interface: "Interface",
+    },
+    decompressInlineMax: "Decompress inline limit",
+    decompressInlineMaxHint: "Above this many characters the content goes to a temp file; digits or a k/m suffix",
+    decompressInlineMaxInvalid: "Enter a character limit between 1k and 1m",
+    decompressTempCap: "Decompress temp file cap",
+    decompressTempCapHint: "Maximum number of decompress temp files to keep",
+    decompressTempCapInvalid: "Enter an integer between 1 and 1000",
+    decompressShowTokens: "Decompress token estimate",
+    submit: "Submit",
+    language: "Language",
+    auto: "Auto",
+    on: "On",
+    off: "Off",
+  },
+  languages: {
+    zh: "中文",
+    en: "English",
+  },
+}

package/src/i18n/index.ts

@@ -0,0 +1,28 @@
+import { en } from "./en.ts"
+import type { Messages } from "./types.ts"
+import { zh } from "./zh.ts"
+
+export type { Messages }
+
+/**
+ * 输入：locale 字符串（可为空）。
+ * 输出：对应语言的消息表。
+ * 预期：`zh*` 用中文，其余一律英文；空值回退到系统 locale。
+ */
+export function resolveMessages(locale: string | undefined): Messages {
+  const value = (locale ?? detectLocale()).toLowerCase()
+  return value.startsWith("zh") ? zh : en
+}
+
+/**
+ * 输入：无。
+ * 输出：系统 locale。
+ * 预期：运行时拿不到时回退 `en`，保证始终有文案。
+ */
+export function detectLocale(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().locale
+  } catch {
+    return "en"
+  }
+}