aerovato/magic-compact

# Magic Compact English | [中文](./README.zh-CN.md) OpenCode 的无损上下文压缩机制。

## 为什么需要 OpenCode 内置的压缩功能会将整个对话替换为一个摘要块。用户消息、助手的推理、工具调用、设计决策以及工作流程全都被压平为一个通用的模板（目标、进度、关键决策……）。Agent 醒来时就像失忆了一样，只能被迫从仅仅捕捉到一小部分关键信息的抽象描述中重建其工作状态。 Magic Compact 采用了不同的方法：保留对话骨架，将每个旧的助手回合浓缩为其各自的摘要，剔除冗长的工具 I/O，并确保所有内容都是可检索的。Agent 依然保留着对它做过什么、为什么这么做以及下一步该做什么的记忆。 ## 如何工作 Magic Compact 没有将整个会话折叠成一个通用的摘要，而是用高保真的摘要替换了旧的助手回合，同时保留了用户消息和工具调用。 助手的思考过程、决策和行动，连同你的所有命令，都保留在上下文中，同时剔除了不必要的冗余信息。冗长的工具调用会被积极地修剪，但可以通过自定义的 `read_omitted_content` 工具进行检索。

## 功能 - 无损上下文压缩 —— 完全保留工作记忆，而不是将历史记录压平为一个回顾。 - 零压缩开销 —— 压缩是根据你的命令一次性发生的，而不是在 Agent 循环期间发生。最大化节省 token，最小化缓存失效。 - 保留用户消息 —— 确切的要求和指导依然对 Agent 可见，原封不动。 - 智能工具调用修剪 —— 冗长且已完成的工具 I/O 会被替换为省略通知，原始内容会被缓存，并可通过 `read_omitted_content` 按需检索。 - 可重新压缩 —— 以后再次运行 `/magic-compact` 可以压缩新的回合，同时保留之前的摘要。 ## 安装 从 CLI 安装： ``` opencode plugin magic-compact --global # 如果您遇到 "No versions available: NPM_CONFIG_MIN_RELEASE_AGE=0 opencode plugin magic-compact --global ``` 这将安装该包并将其添加到你的全局 OpenCode 配置中。 ## 使用方法 ### `/magic-compact` 要执行压缩，请运行 `/magic-compact [N]`，带有一个可选参数表示要保留多少个回合。 - `N` 是要原样保留的最近的助手回合数。默认值：`0`（全部摘要）。 - 在当前对话被压缩之前，会创建一个备份会话。如果压缩失败，你将恢复到备份状态。 示例： - `/magic-compact` —— 摘要所有旧的助手回合。 - `/magic-compact 3` —— 保留最近 3 个助手回合，其余进行摘要。 ### `/magic-stats` 运行 `/magic-stats` 以显示当前对话累计节省的 token：修剪掉的 token、节省的缓存 token、预计节省的费用，以及其他统计数据。 ### 省略内容工具 Magic Compact 注册了一个 `read_omitted_content` 工具，Agent 可以调用它来检索在压缩期间被修剪掉的任何工具输入或输出。 对话中的每个省略通知都包含一个 Content ID（例如 `omitted-001`）。当 Agent 需要无法通过新的工具调用重新生成的旧信息时，它会使用该 ID 来获取原始内容。 ## 修剪规则 修剪仅适用于已摘要的回合。 保留的内容： - 用户消息（原封不动） - 每个回合的摘要 - 工具调用（保留结构） - 选定的高价值合成消息（shell 包装器、后台任务结果、工作目录更改提醒） 移除或浓缩的内容： - 助手推理、文本和步骤标记 —— 由每个回合的摘要代替 - 大多数合成/注入的消息（文件展开、计划提醒、之前的压缩通知等） - 冗长且已完成的工具 I/O —— 替换为指向缓存的省略通知 ### 工具 I/O 规则 超过 128 个单词或 1024 个字符的已完成工具输出默认会被省略。少数工具有特殊处理： - `read` —— 输出总是被省略（陈旧的文件内容可重新加载） - `write` / `edit` / `apply_patch` —— 大文件内容被省略 - `bash` —— 超过 1024 个字符的命令会被截断 - `task` —— 输出超过更高的阈值（512 个单词 / 4096 个字符）时被省略 - `question` —— 输入和输出被保留 - `todowrite` / `skill` —— 输出被丢弃且不缓存（冗余或可重新加载） 挂起、运行中和错误的工具调用始终保持原样。 ## 与 DCP 插件对比 OpenCode-DCP 是一个运行时上下文管理系统，它会在模型请求时重写消息。Magic Compact 采取了不同的方法。 Magic Compact 提供： - 简单易用 —— 一个命令，零配置。 - 无损质量 —— 逐步的流程保持完整。所有用户命令都被保留。所有过去的工具调用都被保留。 - 最大化的 token 节省 —— 整个对话仅用一个请求进行摘要。冗长的工具调用被积极地修剪。 - 无缓存动荡 —— 压缩只发生一次并且对缓存友好，而 DCP 可能会在一个请求中多次使整个对话失效。 - 零助手开销 —— 没有要求助手进行压缩的提示词注入。你的助手始终专注于其任务。 如果你想要模型驱动的压缩，并接受随之而来的缓存失效增加和 token 消耗，请考虑使用 DCP。 ## 开发 ``` bun install bun run typecheck # TypeScript type checking bun run lint # ESLint bun run format # Prettier ``` `src/` - `index.ts` —— 插件入口点：注册 `/magic-compact`、`/magic-stats`、`read_omitted_content` 以及统计事件记录 - `magic-compact.ts` —— `/magic-compact` 命令编排：优先备份的压缩流程、修剪、统计记录、故障恢复 - `magic-stats.ts` —— `/magic-stats` 命令执行：统计信息读取和通知注入 - `api.ts` —— SDK 辅助层：V2 客户端构建、响应解包、toast 助手、会话清理 - `util.ts` —— 共享助手：`isRecord` 类型守卫、`unwrapString` `src/compact/` - `compact.ts` —— 核心压缩编排：计划创建、临时会话摘要、摘要注入 - `plan.ts` —— 压缩计划：消息获取、回合分组、已摘要/下一回合选择 - `prune.ts` —— 工具 I/O 修剪：省略分配、按工具划分的输出/输入阈值、省略通知 - `session.ts` —— 备份和会话助手：分支备份、缓存/统计复制、边界通知注入、压缩后清理 - `template.ts` —— 压缩提示词构建器：用于临时会话的 XML 摘要模板 - `constants.ts` —— 压缩常量：部分 ID 助手、省略通知格式、边界元数据 `src/storage/` - `store.ts` —— 文件系统助手：插件存储目录、经 Zod 验证的 JSON 读写 - `omission.ts` —— 省略缓存：Content ID 分配、按会话划分的条目存储和检索 - `stats.ts` —— 统计存储：按对话划分的统计持久化 schema 以及读/写/复制 `src/stats/` - `events.ts` —— 实时事件记录：助手消息完成处理、缓存 token 节省 - `tokenize.ts` —— Token 计数：基于 GPT 分词器的部分/消息 token 估算 - `pricing.ts` —— 缓存读取定价表：按模型划分的每百万 token 价格查询 - `constants.ts` —— 统计格式化：压缩和摘要消息构建器、统计元数据

标签：AI编程助手, DLL 劫持, SOC Prime, 上下文压缩, 上下文管理, 大语言模型, 开发工具, 自动化攻击