compressed-context 0.1.0 → 0.2.0

package/README.md

@@ -1,89 +1,97 @@
 # compressed-context
 
-OpenCode 的上下文压缩插件：把变长的旧历史折叠成自包含摘要块，让长会话在有限窗口里继续跑下去。
+OpenCode 的上下文压缩插件。它会将较早的对话历史折叠成独立的摘要块，让长会话在有限的上下文窗口里继续跑下去。
 
-## 功能
+![compressed-context TUI 面板](docs/panel.png)
 
-- **自动压缩**：上下文占用达到阈值时自动入队，工具循环里的后续 step 也能触发
-- **手动压缩**：模型可主动调用 `compress` 工具，在任意时刻打检查点
-- **分层摘要**：T1 压缩当前对话流；T2 / T3 合并相邻摘要，层级单调递减
-- **解压**：`decompress` 还原某个块覆盖的原始消息，可只还原下一层或展开到原文
-- **缓存友好**：压缩请求保持前缀不变，尽量减少缓存未命中
-- **摘要格式**：Markdown（默认）或 Babel（首行 `T=标题|G=目标`，正文自由高密度）
-- **主动提醒**：上下文增长超过设定值时，在请求尾部追加一次提醒，让模型自己决定何时压缩
-- **TUI 面板**：查看摘要块、缓存命中率、上下文构成，设置项在插件设置里直接改
+## 架构与工作原理
 
-## 安装
+插件接管发给模型的上下文：把较早的对话折叠成摘要块，让长会话继续跑下去：
 
-插件通过 npm 分发，OpenCode 会在启动时自行安装。
+```text
+原始上下文:
+[ 系统提示词 ][ 早期历史对话 ............................. ][ 最近活跃对话 ]
+                                      ↓ 触发压缩 (T1)
+一级压缩后:
+[ 系统提示词 ][ T1 摘要块 #1 ][ T1 摘要块 #2 ] ............ [ 最近活跃对话 ]
+                                      ↓ 摘要堆积达到阈值 (T2/T3)
+分层合并后:
+[ 系统提示词 ][ T2 合并摘要 (块#1+#2) ][ T1 摘要块 #3 ] .... [ 最近活跃对话 ]
+```
 
-### 方式一：npm 包名（推荐）
+- **递归分层折叠**：
+  - **T1 级**：将溢出的原始对话流折叠为自包含检查点（原始消息移入持久化存储，释放窗口）。
+  - **T2 / T3 级**：当摘要块自身占用接近预算上限时，自动在背景对相邻摘要进行高阶合并（`T1 + T1 → T2`，`T2 + T2 → T3`）。
+- **无损按需回溯**：模型可在需要时通过 `decompress` 按块还原历史，支持只解压下一层级摘要或直接恢复原始对话流。
 
-在 OpenCode 配置里加入 `plugin` 数组（全局配置 `~/.config/opencode/opencode.json`，或项目内 `opencode.json`）：
+## 核心特性
 
-```json
-{
-  "plugin": ["compressed-context"]
-}
-```
+- **自动压缩**：上下文达到阈值时自动触发（工具调用循环中的子步骤同样生效）。
+- **主动压缩**：向模型暴露 `compress` 工具，允许模型在阶段性任务完成后主动打检查点。
+- **多级合并**：T1 负责压缩原始对话；当摘要本身积攒过多时，会自动向上合并为 T2、T3 高阶摘要。
+- **按需解压**：模型可通过 `decompress` 工具还原指定摘要块（支持逐层展开或直接恢复为原始对话）。
+- **缓存友好**：压缩请求尽量保持前缀不变，避免破坏 Prompt Cache。
+- **双摘要格式**：支持标准 `markdown`（默认）和极致压缩的 `babel` 格式（首行 `T=标题|G=目标`，正文为高密度非自然语言）。
+- **超长提醒**：上下文增长超过设定阈值时，在请求尾部追加轻量提醒，引导模型自主决定压缩时机。
+- **TUI 面板**：直观查看摘要块、缓存命中率与上下文构成，支持在面板内直接修改配置。
+
+## 安装与配置
 
-### 方式二：本地路径
+插件通过 npm 分发，OpenCode 启动时会自动安装。
 
-从源码使用或自己改代码时，直接指向仓库目录：
+由于本插件会接管上下文管理，**建议同时关闭 OpenCode 原生的自动压缩**，避免两套策略打架。在全局配置 `~/.config/opencode/opencode.json`（或项目级 `opencode.json`）中加入：
 
 ```json
 {
-  "plugin": ["/absolute/path/to/compressed-context"]
+  "plugin": ["compressed-context"],
+  "compaction": { "auto": false }
 }
 ```
 
-### 配置建议
-
-插件会接管上下文压缩，建议关掉 OpenCode 原生自动压缩，避免两套策略互相干扰：
+**本地开发调试**：如果你拉取了源码自行修改，直接填入本地仓库的绝对路径即可：
 
 ```json
 {
-  "plugin": ["compressed-context"],
+  "plugin": ["/absolute/path/to/compressed-context"],
   "compaction": { "auto": false }
 }
 ```
 
 ## 配置项
 
-都能在 TUI 的插件设置里改，也可以通过设置接口写入：
+所有配置均可直接在 TUI 的插件设置面板中修改，或通过配置文件写入：
 
-| 键 | 默认 | 说明 |
-|---|---|---|
-| `contextLimit` | `"auto"` | 上下文窗口上限；数字表示上限，实际取它与模型原生窗口的较小值 |
-| `triggerPercent` | `80` | 占用达到窗口的百分之多少时自动压缩 |
-| `autoCompress` | 开 | 是否允许自动压缩 |
-| `summaryBlockPercent` | 单条摘要占窗口的百分比 | 单个摘要块的 token 预算 |
-| `summaryTotalPercent` | 全部摘要占窗口的百分比 | 摘要总量预算，超过后触发 T2 / T3 |
-| `summaryFormat` | `markdown` | `markdown` 或 `babel` |
-| `summaryLanguage` | `auto` | 摘要语言；`babel` 格式下忽略 |
-| `nudgeGrowthTokens` | `50000` | 主动提醒的增长阈值，`0` 关闭 |
-| `enableCompressTool` | 开 | 是否暴露 `compress` 工具 |
-| `enableDecompressTool` | 开 | 是否暴露 `decompress` 工具 |
+| 配置项                 | 默认值             | 说明                                                           |
+| ---------------------- | ------------------ | -------------------------------------------------------------- |
+| `contextLimit`         | `"auto"`           | 上下文窗口上限。填具体数字时，实际取该值与模型原生窗口的较小值 |
+| `triggerPercent`       | `80`               | 上下文占用达到百分之多少时触发自动压缩                         |
+| `autoCompress`         | `true`             | 是否开启自动压缩                                               |
+| `summaryBlockPercent`  | `10` | 单个摘要块的 Token 预算（占窗口的百分比）                      |
+| `summaryTotalPercent`  | `50` | 所有摘要的总 Token 预算占比，超出后触发 T2 / T3 合并           |
+| `summaryFormat`        | `"markdown"`       | 摘要格式：`markdown` 或 `babel`                                |
+| `summaryLanguage`      | `"auto"`           | 摘要语言（`babel` 格式下忽略此项）                             |
+| `nudgeGrowthTokens`    | `50000`            | 触发“主动压缩提醒”的 Token 增长阈值，设为 `0` 则关闭           |
+| `enableCompressTool`   | `true`             | 是否允许模型调用 `compress` 工具                               |
+| `enableDecompressTool` | `true`             | 是否允许模型调用 `decompress` 工具                             |
 
-## 开发
+## 本地开发
 
 ```bash
 pnpm install
-pnpm check          # typecheck + lint + 单测 + TUI 测试
-bun scripts/e2e-nudge.mjs      # 隔离环境 + 假 provider 的提醒 e2e
-bun scripts/e2e-tool-loop.mjs  # 工具循环里的自动压缩 e2e
+pnpm check                     # 运行 typecheck + lint + 单测 + TUI 测试
+bun scripts/e2e-nudge.mjs      # E2E 测试：主动提醒（隔离环境 + Mock Provider）
+bun scripts/e2e-tool-loop.mjs  # E2E 测试：工具循环内的自动压缩
 ```
 
-## 基准
+## 效果参考
 
-在 Terminal-Bench 的 `schemelike-metacircular-eval` 上做过一次粗略对比：100k 窗口下插件把单步上下文
-压在 93,560 并让该次运行通过验证。**只跑了一次，波动很大，只能当参考**，详见
-[docs/benchmark.md](docs/benchmark.md)。
+在 Terminal-Bench 的 `schemelike-metacircular-eval` 任务上做过初步实测：在 100k 窗口限制下，插件成功将单步上下文峰值压在 93,560 tokens 并顺利通过验证。由于单次测试存在随机波动，数据仅供参考，详细记录见 [docs/benchmark.md](docs/benchmark.md)。
 
-## 协议
+## 致谢与灵感
 
-[MIT](LICENSE) © 1cyberlangke1
+- [billion-context](https://github.com/ranxianglei/billion-context)
+- [Large Language Models Do Not Always Need Readable Language](https://arxiv.org/abs/2606.19857) —— Babel 摘要格式（BabelTele）的灵感来源
 
-## 灵感
+## 协议
 
-- [billion-context](https://github.com/ranxianglei/billion-context)
+[MIT](LICENSE) © 1cyberlangke1

package/package.json

@@ -1,64 +1,64 @@
-{
-  "name": "compressed-context",
-  "version": "0.1.0",
-  "description": "OpenCode 上下文管理插件：按需压缩、自包含摘要",
-  "type": "module",
-  "license": "MIT",
-  "author": "1cyberlangke1",
-  "homepage": "https://github.com/1cyberlangke1/compressed-context#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/1cyberlangke1/compressed-context.git"
-  },
-  "bugs": {
-    "url": "https://github.com/1cyberlangke1/compressed-context/issues"
-  },
-  "keywords": [
-    "opencode",
-    "plugin",
-    "context",
-    "compression",
-    "summarization",
-    "llm"
-  ],
-  "exports": {
-    ".": "./src/index.ts",
-    "./tui": "./src/tui/index.tsx"
-  },
-  "files": [
-    "src"
-  ],
-  "peerDependencies": {
-    "@opencode/plugin": "^2.0.32",
-    "@opentui/core": ">=0.5.17",
-    "@opentui/solid": ">=0.5.17",
-    "solid-js": ">=1.9.0"
-  },
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm test:tui",
-    "test": "vitest run",
-    "test:tui": "cd tui-test && bun test",
-    "test:e2e:nudge": "bun scripts/e2e-nudge.mjs",
-    "test:e2e:tool-loop": "bun scripts/e2e-tool-loop.mjs",
-    "test:watch": "vitest"
-  },
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@opencode/plugin": "^2.0.32",
-    "@opencode/theme": "2.0.32",
-    "@opentui/core": "0.5.17",
-    "@opentui/solid": "0.5.17",
-    "@types/node": "^26.6.5",
-    "eslint": "^10.13.0",
-    "solid-js": "1.9.15",
-    "typescript": "^6.0.3",
-    "typescript-eslint": "^8.71.2",
-    "vitest": "^5.0.5"
-  },
-  "dependencies": {
-    "effect": "4.0.1",
-    "jsonrepair": "^3.15.0"
-  }
-}
+{
+  "name": "compressed-context",
+  "version": "0.2.0",
+  "description": "OpenCode 上下文管理插件：按需压缩、自包含摘要",
+  "type": "module",
+  "license": "MIT",
+  "author": "1cyberlangke1",
+  "homepage": "https://github.com/1cyberlangke1/compressed-context#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1cyberlangke1/compressed-context.git"
+  },
+  "bugs": {
+    "url": "https://github.com/1cyberlangke1/compressed-context/issues"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "context",
+    "compression",
+    "summarization",
+    "llm"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./tui": "./src/tui/index.tsx"
+  },
+  "files": [
+    "src"
+  ],
+  "peerDependencies": {
+    "@opencode/plugin": "^2.0.32",
+    "@opentui/core": ">=0.5.17",
+    "@opentui/solid": ">=0.5.17",
+    "solid-js": ">=1.9.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm test:tui",
+    "test": "vitest run",
+    "test:tui": "cd tui-test && bun test",
+    "test:e2e:nudge": "bun scripts/e2e-nudge.mjs",
+    "test:e2e:tool-loop": "bun scripts/e2e-tool-loop.mjs",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@opencode/plugin": "^2.1.2",
+    "@opencode/theme": "2.1.2",
+    "@opentui/core": "0.6.6",
+    "@opentui/solid": "0.6.6",
+    "@types/node": "^26.6.5",
+    "eslint": "^10.13.0",
+    "solid-js": "1.9.15",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.2",
+    "vitest": "^5.0.5"
+  },
+  "dependencies": {
+    "effect": "4.0.1",
+    "jsonrepair": "^3.15.0"
+  }
+}

package/src/compression/active-summary-cache.ts

@@ -1,50 +1,50 @@
-import { renderAll, type RenderOptions } from "./render.ts"
-import type { State } from "./state.ts"
-
-interface Entry {
-  readonly revision: string
-  readonly text: string
-}
-
-const LIMIT = 32
-const cache = new Map<string, Entry>()
-
-/** 输入：状态 + 渲染选项；输出：只由块身份决定的 revision。 */
-function revisionOf(state: State, options: RenderOptions): string {
-  return JSON.stringify({
-    blocks: state.blocks.map((block) => [
-      block.id,
-      block.tier,
-      block.order,
-      block.at,
-      block.sourceBlockIds ?? [],
-    ]),
-    pending: state.pending?.id ?? null,
-    options,
-  })
-}
-
-/** 输入：sessionID + 状态 + 渲染选项；输出：活跃摘要文本。 */
-export function renderActiveSummary(
-  sessionID: string,
-  state: State,
-  options: RenderOptions,
-): string {
-  const revision = revisionOf(state, options)
-  const hit = cache.get(sessionID)
-  if (hit?.revision === revision) return hit.text
-  const text = renderAll(state.blocks, state.pending, options)
-  cache.delete(sessionID)
-  cache.set(sessionID, { revision, text })
-  while (cache.size > LIMIT) {
-    const oldest = cache.keys().next().value
-    if (oldest === undefined) break
-    cache.delete(oldest)
-  }
-  return text
-}
-
-/** 输入：sessionID；输出：无；预期：会话删除时丢掉活跃摘要缓存。 */
-export function clearActiveSummary(sessionID: string): void {
-  cache.delete(sessionID)
-}
+import { renderAll, type RenderOptions } from "./render.ts"
+import type { State } from "./state.ts"
+
+interface Entry {
+  readonly revision: string
+  readonly text: string
+}
+
+const LIMIT = 32
+const cache = new Map<string, Entry>()
+
+/** 输入：状态 + 渲染选项；输出：只由块身份决定的 revision。 */
+function revisionOf(state: State, options: RenderOptions): string {
+  return JSON.stringify({
+    blocks: state.blocks.map((block) => [
+      block.id,
+      block.tier,
+      block.order,
+      block.at,
+      block.sourceBlockIds ?? [],
+    ]),
+    pending: state.pending?.id ?? null,
+    options,
+  })
+}
+
+/** 输入：sessionID + 状态 + 渲染选项；输出：活跃摘要文本。 */
+export function renderActiveSummary(
+  sessionID: string,
+  state: State,
+  options: RenderOptions,
+): string {
+  const revision = revisionOf(state, options)
+  const hit = cache.get(sessionID)
+  if (hit?.revision === revision) return hit.text
+  const text = renderAll(state.blocks, state.pending, options)
+  cache.delete(sessionID)
+  cache.set(sessionID, { revision, text })
+  while (cache.size > LIMIT) {
+    const oldest = cache.keys().next().value
+    if (oldest === undefined) break
+    cache.delete(oldest)
+  }
+  return text
+}
+
+/** 输入：sessionID；输出：无；预期：会话删除时丢掉活跃摘要缓存。 */
+export function clearActiveSummary(sessionID: string): void {
+  cache.delete(sessionID)
+}

package/src/compression/adopt.ts

@@ -1,57 +1,57 @@
-import type { Plugin } from "@opencode/plugin"
-
-import { createT1Block } from "./block.ts"
-import { toMarkdownSummary } from "./markdown.ts"
-import { isCheckpoint, messageText, type MessageLike } from "./select.ts"
-import { loadState, saveState } from "./state.ts"
-
-/** 原生 checkpoint 里抽出的摘要与 recent 上下文。 */
-export interface NativeCheckpoint {
-  readonly summary: string
-  readonly recent?: string
-}
-
-/**
- * 输入：OpenCode checkpoint 文本。
- * 输出：`<summary>` / `<recent-context>` 内容；不是 checkpoint 时 undefined。
- * 预期：只做只读解析，不改原文。
- */
-export function extractCheckpoint(text: string): NativeCheckpoint | undefined {
-  if (!text.trimStart().startsWith("<conversation-checkpoint>")) return undefined
-  const summary = /<summary>\n?([\s\S]*?)\n?<\/summary>/.exec(text)?.[1]?.trim()
-  if (summary === undefined || summary.length === 0) return undefined
-  const recent = /<recent-context>\n?([\s\S]*?)\n?<\/recent-context>/.exec(text)?.[1]?.trim()
-  return recent === undefined || recent.length === 0 ? { summary } : { summary, recent }
-}
-
-/**
- * 输入：插件上下文 + sessionID + 当前请求消息。
- * 输出：是否收养了原生摘要。
- * 预期：仅当插件还没有任何块时，把 OpenCode 自己的 checkpoint 摘要当作 b1:T1；
- *       它没有原始 transcript，fromId/toId 指向 checkpoint 消息本身。
- */
-export async function adoptNativeCheckpoint(
-  ctx: Plugin.Context,
-  sessionID: string,
-  messages: readonly MessageLike[],
-): Promise<boolean> {
-  const state = await loadState(ctx.storage, sessionID)
-  if (state.blocks.length > 0 || state.pending !== undefined || state.terminal !== undefined) return false
-
-  const checkpoint = messages.findLast((message) => isCheckpoint(message))
-  if (checkpoint === undefined) return false
-  const parsed = extractCheckpoint(messageText(checkpoint))
-  if (parsed === undefined) return false
-
-  const summary = toMarkdownSummary(parsed.summary)
-  const block = createT1Block({
-    blocks: [],
-    summary,
-    // 原生摘要没有原始 transcript；空范围让 decompress full 返回 unavailable，而不是伪造原文。
-    fromId: "",
-    toId: "",
-    sourceChars: parsed.summary.length,
-  })
-  await saveState(ctx.storage, sessionID, { blocks: [block], attempts: 0 })
-  return true
-}
+import type { Plugin } from "@opencode/plugin"
+
+import { createT1Block } from "./block.ts"
+import { toMarkdownSummary } from "./markdown.ts"
+import { isCheckpoint, messageText, type MessageLike } from "./select.ts"
+import { loadState, saveState } from "./state.ts"
+
+/** 原生 checkpoint 里抽出的摘要与 recent 上下文。 */
+export interface NativeCheckpoint {
+  readonly summary: string
+  readonly recent?: string
+}
+
+/**
+ * 输入：OpenCode checkpoint 文本。
+ * 输出：`<summary>` / `<recent-context>` 内容；不是 checkpoint 时 undefined。
+ * 预期：只做只读解析，不改原文。
+ */
+export function extractCheckpoint(text: string): NativeCheckpoint | undefined {
+  if (!text.trimStart().startsWith("<conversation-checkpoint>")) return undefined
+  const summary = /<summary>\n?([\s\S]*?)\n?<\/summary>/.exec(text)?.[1]?.trim()
+  if (summary === undefined || summary.length === 0) return undefined
+  const recent = /<recent-context>\n?([\s\S]*?)\n?<\/recent-context>/.exec(text)?.[1]?.trim()
+  return recent === undefined || recent.length === 0 ? { summary } : { summary, recent }
+}
+
+/**
+ * 输入：插件上下文 + sessionID + 当前请求消息。
+ * 输出：是否收养了原生摘要。
+ * 预期：仅当插件还没有任何块时，把 OpenCode 自己的 checkpoint 摘要当作 b1:T1；
+ *       它没有原始 transcript，fromId/toId 指向 checkpoint 消息本身。
+ */
+export async function adoptNativeCheckpoint(
+  ctx: Plugin.Context,
+  sessionID: string,
+  messages: readonly MessageLike[],
+): Promise<boolean> {
+  const state = await loadState(ctx.storage, sessionID)
+  if (state.blocks.length > 0 || state.pending !== undefined || state.terminal !== undefined) return false
+
+  const checkpoint = messages.findLast((message) => isCheckpoint(message))
+  if (checkpoint === undefined) return false
+  const parsed = extractCheckpoint(messageText(checkpoint))
+  if (parsed === undefined) return false
+
+  const summary = toMarkdownSummary(parsed.summary)
+  const block = createT1Block({
+    blocks: [],
+    summary,
+    // 原生摘要没有原始 transcript；空范围让 decompress full 返回 unavailable，而不是伪造原文。
+    fromId: "",
+    toId: "",
+    sourceChars: parsed.summary.length,
+  })
+  await saveState(ctx.storage, sessionID, { blocks: [block], attempts: 0 })
+  return true
+}