compressed-context 0.0.0-stage → 0.1.1

package/src/shared/media.ts

@@ -0,0 +1,184 @@
+/**
+ * 多模态附件 token 估算。
+ *
+ * 输入：mime、base64/字节数据、可选时长。
+ * 输出：粗略 token 数。
+ * 预期：拿不到宽高/页数/时长时使用保守固定值；这里只做估算，不伪装成精确 tokenizer。
+ */
+
+/** 图片拿不到尺寸时的固定估算。 */
+export const IMAGE_FALLBACK_TOKENS = 1_500
+/** PDF 拿不到页数时的固定估算。 */
+export const PDF_FALLBACK_TOKENS = 2_000
+/** PDF 每页按一张图估算。 */
+export const PDF_PAGE_TOKENS = 1_500
+/** 音频每秒估算。 */
+export const AUDIO_TOKENS_PER_SECOND = 32
+/** 音频拿不到时长时的固定估算。 */
+export const AUDIO_FALLBACK_TOKENS = 1_000
+/** 视频每秒估算。 */
+export const VIDEO_TOKENS_PER_SECOND = 263
+/** 视频拿不到时长时的固定估算。 */
+export const VIDEO_FALLBACK_TOKENS = 10_000
+/** 未知二进制文件固定估算。 */
+export const FILE_FALLBACK_TOKENS = 2_000
+
+export interface AttachmentInput {
+  readonly mime?: string | undefined
+  readonly data?: string | Uint8Array | undefined
+  readonly width?: number | undefined
+  readonly height?: number | undefined
+  readonly durationSeconds?: number | undefined
+}
+
+export interface ImageSize {
+  readonly width: number
+  readonly height: number
+}
+
+/** 输入：base64 或字节；输出：字节；失败返回 undefined。 */
+function toBytes(data: string | Uint8Array | undefined): Uint8Array | undefined {
+  if (data === undefined) return undefined
+  if (data instanceof Uint8Array) return data
+  try {
+    return Uint8Array.from(Buffer.from(data, "base64"))
+  } catch {
+    return undefined
+  }
+}
+
+/** 输入：字节 + 偏移；输出：大端 u32；越界返回 0。 */
+function u32be(bytes: Uint8Array, offset: number): number {
+  const a = bytes[offset] ?? 0
+  const b = bytes[offset + 1] ?? 0
+  const c = bytes[offset + 2] ?? 0
+  const d = bytes[offset + 3] ?? 0
+  return ((a << 24) | (b << 16) | (c << 8) | d) >>> 0
+}
+
+/** 输入：字节 + 偏移；输出：小端 u16；越界返回 0。 */
+function u16le(bytes: Uint8Array, offset: number): number {
+  return (bytes[offset] ?? 0) | ((bytes[offset + 1] ?? 0) << 8)
+}
+
+/** 输入：字节 + 偏移；输出：大端 u16；越界返回 0。 */
+function u16be(bytes: Uint8Array, offset: number): number {
+  return ((bytes[offset] ?? 0) << 8) | (bytes[offset + 1] ?? 0)
+}
+
+/** 输入：字节 + 偏移；输出：小端 u24；越界返回 0。 */
+function u24le(bytes: Uint8Array, offset: number): number {
+  return (bytes[offset] ?? 0) | ((bytes[offset + 1] ?? 0) << 8) | ((bytes[offset + 2] ?? 0) << 16)
+}
+
+/** 输入：PNG 字节；输出：尺寸；不是 PNG 返回 undefined。 */
+function pngSize(bytes: Uint8Array): ImageSize | undefined {
+  if (bytes.length < 24) return undefined
+  const signature = [137, 80, 78, 71, 13, 10, 26, 10]
+  if (!signature.every((value, index) => bytes[index] === value)) return undefined
+  const width = u32be(bytes, 16)
+  const height = u32be(bytes, 20)
+  return width > 0 && height > 0 ? { width, height } : undefined
+}
+
+/** 输入：GIF 字节；输出：尺寸；不是 GIF 返回 undefined。 */
+function gifSize(bytes: Uint8Array): ImageSize | undefined {
+  if (bytes.length < 10) return undefined
+  const header = String.fromCharCode(...bytes.slice(0, 6))
+  if (header !== "GIF87a" && header !== "GIF89a") return undefined
+  const width = u16le(bytes, 6)
+  const height = u16le(bytes, 8)
+  return width > 0 && height > 0 ? { width, height } : undefined
+}
+
+/** 输入：JPEG 字节；输出：尺寸；找不到 SOF 返回 undefined。 */
+function jpegSize(bytes: Uint8Array): ImageSize | undefined {
+  if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8) return undefined
+  let offset = 2
+  while (offset + 9 < bytes.length) {
+    if (bytes[offset] !== 0xff) {
+      offset += 1
+      continue
+    }
+    const marker = bytes[offset + 1] ?? 0
+    const length = u16be(bytes, offset + 2)
+    if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+      const height = u16be(bytes, offset + 5)
+      const width = u16be(bytes, offset + 7)
+      return width > 0 && height > 0 ? { width, height } : undefined
+    }
+    if (length < 2) return undefined
+    offset += 2 + length
+  }
+  return undefined
+}
+
+/** 输入：WebP 字节；输出：尺寸；VP8X 之外的编码回退 undefined。 */
+function webpSize(bytes: Uint8Array): ImageSize | undefined {
+  if (bytes.length < 30) return undefined
+  const riff = String.fromCharCode(...bytes.slice(0, 4))
+  const webp = String.fromCharCode(...bytes.slice(8, 12))
+  const chunk = String.fromCharCode(...bytes.slice(12, 16))
+  if (riff !== "RIFF" || webp !== "WEBP" || chunk !== "VP8X") return undefined
+  const width = 1 + u24le(bytes, 24)
+  const height = 1 + u24le(bytes, 27)
+  return width > 0 && height > 0 ? { width, height } : undefined
+}
+
+/** 输入：附件数据；输出：图片尺寸；不是图片或解析失败返回 undefined。 */
+export function imageSize(data: string | Uint8Array | undefined): ImageSize | undefined {
+  const bytes = toBytes(data)
+  if (bytes === undefined) return undefined
+  return pngSize(bytes) ?? gifSize(bytes) ?? jpegSize(bytes) ?? webpSize(bytes)
+}
+
+/** 输入：图片宽高；输出：通用经验公式估算。 */
+export function imageTokens(width: number, height: number): number {
+  if (width <= 0 || height <= 0) return IMAGE_FALLBACK_TOKENS
+  return Math.max(258, Math.ceil((width * height) / 750))
+}
+
+/** 输入：PDF 字节；输出：页数；解析失败返回 undefined。 */
+export function pdfPages(data: string | Uint8Array | undefined): number | undefined {
+  const bytes = toBytes(data)
+  if (bytes === undefined) return undefined
+  const text = Buffer.from(bytes).toString("latin1")
+  const pages = text.match(/\/Type\s*\/Page\b/g)
+  return pages === null ? undefined : pages.length
+}
+
+/** 输入：文本类文件字节；输出：粗略 token。 */
+function textFileTokens(bytes: Uint8Array): number {
+  return Math.max(1, Math.ceil(bytes.length / 4))
+}
+
+/** 输入：附件；输出：通用经验估算。 */
+export function attachmentTokens(input: AttachmentInput): number {
+  const mime = (input.mime ?? "").toLowerCase()
+  const bytes = toBytes(input.data)
+  if (mime.startsWith("image/")) {
+    if (input.width !== undefined && input.height !== undefined) {
+      return imageTokens(input.width, input.height)
+    }
+    const size = imageSize(input.data)
+    return size === undefined ? IMAGE_FALLBACK_TOKENS : imageTokens(size.width, size.height)
+  }
+  if (mime === "application/pdf") {
+    const pages = pdfPages(input.data)
+    return pages === undefined ? PDF_FALLBACK_TOKENS : pages * PDF_PAGE_TOKENS
+  }
+  if (mime.startsWith("audio/")) {
+    return input.durationSeconds === undefined
+      ? AUDIO_FALLBACK_TOKENS
+      : Math.max(1, Math.ceil(input.durationSeconds * AUDIO_TOKENS_PER_SECOND))
+  }
+  if (mime.startsWith("video/")) {
+    return input.durationSeconds === undefined
+      ? VIDEO_FALLBACK_TOKENS
+      : Math.max(1, Math.ceil(input.durationSeconds * VIDEO_TOKENS_PER_SECOND))
+  }
+  if (mime.startsWith("text/") || mime === "application/json") {
+    return bytes === undefined ? FILE_FALLBACK_TOKENS : textFileTokens(bytes)
+  }
+  return FILE_FALLBACK_TOKENS
+}

package/src/shared/parse.ts

@@ -0,0 +1,25 @@
+/** 输入：任意值 + 范围；输出：合法整数；非法返回 fallback。 */
+export function readInt(value: unknown, min: number, max: number, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback
+  const rounded = Math.round(value)
+  if (rounded < min || rounded > max) return fallback
+  return rounded
+}
+
+/** 输入：任意值 + 范围；输出：合法整数；非法返回 undefined。 */
+export function readOptionalInt(value: unknown, min: number, max: number): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) return undefined
+  const rounded = Math.round(value)
+  if (rounded < min || rounded > max) return undefined
+  return rounded
+}
+
+/**
+ * 输入：任意值 + 默认值。
+ * 输出：布尔；缺省返回 fallback，类型不对返回 undefined。
+ * 预期：服务端设置对错误类型严格拒绝；TUI 迁移用宽松版本。
+ */
+export function readStrictBoolean(value: unknown, fallback: boolean): boolean | undefined {
+  if (value === undefined) return fallback
+  return typeof value === "boolean" ? value : undefined
+}

package/src/shared/parts.ts

@@ -0,0 +1,72 @@
+/**
+ * OpenCode 消息 part 的兼容层。
+ *
+ * OpenCode v2 的工具 part 是 `type: "tool"`，输入/输出在 `state.input` /
+ * `state.content`；旧测试和部分 provider 仍用 `tool-call` / `tool-result`。
+ * 这里只做形状归一，避免 tokens / transcript / select 各自漏一种形状。
+ */
+
+/** 工具 part 的 state；只保留计数和转录需要的字段。 */
+export interface ToolStateLike {
+  readonly input?: unknown
+  readonly content?: unknown
+  readonly output?: unknown
+}
+
+/** 工具 part 的最小形状。 */
+export interface ToolPartLike {
+  readonly name?: string | undefined
+  readonly input?: unknown
+  readonly result?: unknown
+  readonly state?: ToolStateLike | undefined
+}
+
+/** 输入：任意值；输出：可计数文本；不可序列化时返回空串。 */
+export function stringify(value: unknown): string {
+  if (typeof value === "string") return value
+  if (value === undefined) return ""
+  try {
+    const encoded: unknown = JSON.stringify(value)
+    return typeof encoded === "string" ? encoded : ""
+  } catch {
+    return ""
+  }
+}
+
+/** 输入：工具 part；输出：工具调用参数。 */
+export function toolInput(part: ToolPartLike): unknown {
+  return part.input ?? part.state?.input
+}
+
+/** 输入：工具 part；输出：工具结果。 */
+export function toolResult(part: ToolPartLike): unknown {
+  return part.result ?? part.state?.content ?? part.state?.output
+}
+
+/**
+ * 输入：工具结果（v2 state.content 数组、字符串、对象或旧 result.value）。
+ * 输出：可读文本；数组只拼 text 项，其余项退回 JSON。
+ * 预期：不丢工具输出，同时避免把媒体 base64 当普通文本展开。
+ */
+export function toolResultText(value: unknown): string {
+  if (typeof value === "string") return value
+  if (Array.isArray(value)) {
+    return value
+      .map((item) => {
+        if (typeof item === "object" && item !== null) {
+          const record = item as { readonly type?: unknown; readonly text?: unknown }
+          if (record.type === "text" && typeof record.text === "string") return record.text
+        }
+        return stringify(item)
+      })
+      .filter((text) => text.length > 0)
+      .join("\n")
+  }
+  if (typeof value === "object" && value !== null) {
+    const record = value as { readonly content?: unknown; readonly output?: unknown; readonly value?: unknown }
+    if (record.content !== undefined) return toolResultText(record.content)
+    if (record.output !== undefined) return toolResultText(record.output)
+    if (record.value !== undefined) return toolResultText(record.value)
+  }
+  return stringify(value)
+}

package/src/shared/rpc.ts

@@ -0,0 +1,145 @@
+import { Rpc } from "@opencode/plugin/rpc"
+
+import type { SummaryBlock } from "./blocks.ts"
+import type { CacheSample } from "./cache.ts"
+import type { CompressionSettings } from "./settings.ts"
+
+const SettingsGetInputJson = {
+  type: "object",
+  properties: { sessionID: { type: "string" } },
+  additionalProperties: false,
+} as const
+
+const SettingsProperties = {
+  contextLimit: {
+    anyOf: [{ type: "string", enum: ["auto"] }, { type: "number" }],
+  },
+  triggerPercent: { type: "number" },
+  nudgeGrowthTokens: { type: "number" },
+  summaryBlockPercent: { type: "number" },
+  summaryTotalPercent: { type: "number" },
+  summaryLanguage: { type: "string", enum: ["auto", "zh", "en"] },
+  summaryFormat: { type: "string", enum: ["json", "markdown", "babel"] },
+  autoCompress: { type: "boolean" },
+  enableCompressTool: { type: "boolean" },
+  enableDecompressTool: { type: "boolean" },
+  showTimeline: { type: "boolean" },
+  showBlockTokens: { type: "boolean" },
+  decompressInlineMax: { type: "number" },
+  decompressTempCap: { type: "number" },
+  decompressShowTokens: { type: "boolean" },
+} as const
+
+const SettingsInputJson = {
+  type: "object",
+  properties: SettingsProperties,
+  required: ["contextLimit", "triggerPercent"],
+  additionalProperties: false,
+} as const
+
+/** 读取结果比写入多一个 resolvedWindow：auto 时从模型原生窗口解析出来的值。 */
+const SettingsOutputJson = {
+  type: "object",
+  properties: {
+    ...SettingsProperties,
+    resolvedWindow: { type: "number" },
+  },
+  required: ["contextLimit", "triggerPercent"],
+  additionalProperties: false,
+} as const
+
+const OkJson = {
+  type: "object",
+  properties: { ok: { type: "boolean" } },
+  required: ["ok"],
+  additionalProperties: false,
+} as const
+
+/** 需要明确指定会话的只读查询。 */
+const SessionInputJson = {
+  type: "object",
+  properties: { sessionID: { type: "string" } },
+  required: ["sessionID"],
+  additionalProperties: false,
+} as const
+
+/** 摘要块：服务端返回 active 链，body 是渲染好的 markdown。 */
+const BlockJson = {
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    tier: { type: "number", enum: [1, 2, 3] },
+    format: { type: "string", enum: ["json", "markdown", "babel"] },
+    title: { type: "string" },
+    at: { type: "number" },
+    tokensBefore: { type: "number" },
+    tokensAfter: { type: "number" },
+    sourceBlockIds: { type: "array", items: { type: "string" } },
+    body: { type: "string" },
+  },
+  required: ["id", "tier", "format", "title", "at", "tokensBefore", "tokensAfter", "body"],
+  additionalProperties: false,
+} as const
+
+const BlocksOutputJson = {
+  type: "object",
+  properties: { blocks: { type: "array", items: BlockJson } },
+  required: ["blocks"],
+  additionalProperties: false,
+} as const
+
+/** 一条缓存命中样本。 */
+const CacheSampleJson = {
+  type: "object",
+  properties: {
+    messageID: { type: "string" },
+    at: { type: "number" },
+    input: { type: "number" },
+    output: { type: "number" },
+    cached: { type: "number" },
+    hitRate: { type: "number" },
+  },
+  required: ["messageID", "at", "input", "output", "cached", "hitRate"],
+  additionalProperties: false,
+} as const
+
+const CacheHistoryOutputJson = {
+  type: "object",
+  properties: { samples: { type: "array", items: CacheSampleJson } },
+  required: ["samples"],
+  additionalProperties: false,
+} as const
+
+/** TUI 与服务端共用的设置 / 面板 RPC。 */
+export const ContextRpc: Rpc.PortableDefinition = Rpc.define({
+  id: "compressed-context",
+  methods: {
+    settingsGet: { input: SettingsGetInputJson, output: SettingsOutputJson },
+    settingsSet: { input: SettingsInputJson, output: OkJson },
+    blocksGet: { input: SessionInputJson, output: BlocksOutputJson },
+    cacheHistoryGet: { input: SessionInputJson, output: CacheHistoryOutputJson },
+  },
+  events: {},
+})
+
+/** 服务端设置读取结果。 */
+export interface ContextSettingsResult extends CompressionSettings {
+  readonly resolvedWindow?: number
+}
+
+/** TUI 侧对 ContextRpc 的类型化视图。 */
+export interface ContextRpcClient {
+  settingsGet(input: { readonly sessionID?: string }): Promise<ContextSettingsResult>
+  settingsSet(input: CompressionSettings): Promise<{ readonly ok: boolean }>
+  blocksGet(input: { readonly sessionID: string }): Promise<{ readonly blocks: readonly SummaryBlock[] }>
+  cacheHistoryGet(input: {
+    readonly sessionID: string
+  }): Promise<{ readonly samples: readonly CacheSample[] }>
+}
+
+/** 输入：带 rpc 方法的 TUI client；输出：类型化 RPC 客户端。 */
+export function contextRpc(client: {
+  rpc(definition: Rpc.PortableDefinition): unknown
+}): ContextRpcClient {
+  return client.rpc(ContextRpc) as ContextRpcClient
+}

package/src/shared/scan.ts

@@ -0,0 +1,32 @@
+/**
+ * 输入：具备 scan 能力的 storage + 前缀 + 每条目的处理函数。
+ * 输出：无。
+ * 预期：按 next 游标分页遍历全部匹配条目，逐条串行 await，避免一次性把 key 全读进内存。
+ */
+export interface ScanStorageLike {
+  readonly scan?: (options: { prefix: string; limit: number; after?: string }) => Promise<{
+    entries: readonly { key: string; value: unknown }[]
+    next?: string
+  }>
+}
+
+/** 输入：storage + 前缀 + 访问函数 + 每页条数；输出：无；预期：storage 无 scan 时直接返回。 */
+export async function forEachScannedEntry(
+  storage: ScanStorageLike,
+  prefix: string,
+  visit: (entry: { key: string; value: unknown }) => Promise<void>,
+  limit = 100,
+): Promise<void> {
+  if (storage.scan === undefined) return
+  let after: string | undefined
+  for (;;) {
+    const page = await storage.scan({
+      prefix,
+      limit,
+      ...(after === undefined ? {} : { after }),
+    })
+    for (const entry of page.entries) await visit(entry)
+    if (page.next === undefined) return
+    after = page.next
+  }
+}