# @deepagents/compaction 中文文档

规范地址：https://npmcn.com/package/%40deepagents/compaction/

版本：7\.5\.2
npm 元数据更新时间：2026-11-08T13:58:33.610Z
中文译文更新时间：2026-11-14T14:57:56.217Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40deepagents/compaction
原文对照：https://npmcn.com/package/%40deepagents/compaction/?lang=original
项目主页：https://github.com/JanuaryLabs/deepagents#readme
源码仓库：https://github.com/JanuaryLabs/deepagents

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：48.8 kB，12 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：ai ^7\.0\.153
- 首次发布：2026-10-03T08:28:20.952Z
- 最新版本发布：2026-11-08T13:58:33.276Z
- 近 30 天下载量：2010（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

AI SDK - 内在对话紧凑 有明确的预算和来源.

## 安装

```sh
npm install @deepagents/compaction
```

也可以使用：`pnpm add @deepagents/compaction`、`yarn add @deepagents/compaction`、`bun add @deepagents/compaction`

## README

# @ diepagents/ compaction (签名)

将AI SDK对话的快照简化为摘要和近期历史. 这个 软件包直接使用 AI SDK v7 类型,不依赖 `@deepagents/context` 或者苏克鲁夫 它不拥有商店,调度员, 或谈话状态.

执行决定和核查记录在 [相位文件](https://npmcn.com/package/%40deepagents/compaction/plan/README.md)。 。 。 .

```ts
import { compact } from '@deepagents/compaction';

const result = await compact({
  messages, // AI SDK ModelMessage[]
  model: summaryModel, // Your explicitly configured summarization model
  targetTokens: 20_000,
  keepLastMessages: 4, // Optional; defaults to 4
  instructions: 'Preserve exact customer commitments and record IDs.',
  abortSignal,
});

switch (result.status) {
  case 'compacted':
    // Persist the result and its source-message mapping before adopting it.
    // result.replacedRange contains half-open indices into the input snapshot.
    break;
  case 'cannot-fit':
    // result.reason explains the failure. result.messages still holds the input.
    break;
}
```

## 结果合同

-   `messages`: 已准备好的关于成功的信息,否则,一份未修改的复印件 输入数组。 输入信息及其提供者元数据从未变异.
-   `tokens.before` 编号 : `tokens.after`: 输入和返回信件的估计值.
-   `usage`: 原生AI SDK `LanguageModelUsage` 当总和运行时,包括 当其输出被拒绝时; 否则 `undefined`。 。 。 .
-   打开 `compacted`, (中文(简体) ), `summary` 包含生成的文本和 `replacedRange` 准确识别 `messages.slice(start, end)` 从输入快照.
-   打开 `cannot-fit`, (中文(简体) ), `reason` 实值 `no-safe-boundary`, (中文(简体) ), `protected-history`, (中文(简体) ), `incomplete-summary`, (中文(简体) ), `empty-summary`,或 `summary-too-large`。 。 。 .

索引描述的是这个调用输入,而不是永久历史ID. 呼叫者将其映射到 他们自己的稳定识别特征,坚持绘制地图和汇总,并保持 用于显示或检索的原始记录。 保留信件对象为 复用不变. 将输入和输出都视为不可改变的快照.

## 何等为一字不差

压缩以普通用户信息取代一个相接的旧范围 标签 `Previous conversation summary`。它从不宣传历史内容 到系统指令.

后四条消息默认保留. `keepLastMessages` 更改此选项 最小值, 但保留后缀扩展为包含未解决的工具调用/ 批准 和完整的工具/核准关系。 已完成 交换可在用户回合内进行总结。 当最新的用户请求落下时 在被替换的区域内,在摘要和 在保留步骤之前。 完全在被替换范围内的闭合交换是: 与汇总模型一起提供.

主要系统信息仍然有效。 后来的系统消息、文件、媒体和 不透明的提供者内容保护从他们的位置开始的后缀. 他们是 未转换为丢失的文本。 如果保护历史没有留下空间 汇总,结果为 `cannot-fit`;包裹从不默默地丢弃.

## 预算和模式呼吁

`targetTokens` 仅覆盖提供的消息。 打电话的人必须分开 允许外部指令、工具定义、提供者间接费用和输出 头室. 默认估计每四条按一令牌排序的短信 字符,四舍五入(空数组为零)。 这是热心症,不是 保证任何供应商的代币或账单.

对于媒体或不透明的提供者内容,提供能理解 选中的对话模式 。 这也允许只使用文本的呼叫者使用更精确的 供应商专用计数器 :

```ts
const result = await compact({
  messages,
  model: summaryModel,
  targetTokens: 20_000,
  countTokens: async (candidateMessages) => {
    return countForConversationModel(candidateMessages);
  },
});
```

`estimateTokens(messages)` 显示与调用者相同的默认文本计数器 需要先检查自动触发器,然后再援引 `compact()`。 。 。 .

计数器接收完整的候选信件数组,包括摘要 包装 它必须返回一个非负式的安全整数,并且不得改变其输入. 包裹在返回成功前用同样的计数器检查最终结果.

一通电话最多发出一次汇总请求,SDK复写被禁用. 其产出津贴是估计的剩余预算,上限为2 048先令. 不采用空的、短的、非文本的或超预算摘要. 提供者出错,输入/计数器无效,取消则拒绝承诺. 汇总模型本身必须支持序列历史的输入大小; 此软件包不会将一个超大小的历史分割成多个模型调用 .

## 持续对话

来电者选择何时收紧. 例如,运行时间可能触发60,000 估计输入令牌,并通过可得到的电文指标为20 000个令牌。 A 类 扳机比目标高,为以后的转弯留有余地.

保存成功结果后, 重复使用 `result.messages` 并附加新信件. 不要在每个回合重编一个摘要 。 以后的收缩可以消耗 前一个摘要和新的历史。 简表之间保持不变 因此重放的压缩件保持稳定; 提供者缓存保留 供应商的责任.

## 苏克鲁夫整编

在代理声明上配置自动收缩,同时使用其模型和 指令:

```ts
import {
  cacheLikelyCold,
  messagesExceed,
  tokensExceed,
} from '@deepagents/compaction';

const root = defineAgent({
  name: 'assistant',
  model,
  sandbox,
  instructions,
  compaction: {
    model: summaryModel,
    triggers: [tokensExceed(60_000), messagesExceed(100)],
    targetTokens: 20_000,
    keepLastMessages: 4,
  },
});
```

`defineAgent` 来自 `@deepagents/experimental/zukhruf`供应 明确归纳模型. `triggers` 是一种非空的上游阵列; Zukhruf按顺序评价它们,并在首场对决(OR)时止步. 门槛 帮助者需要一个正的安全整数,并严格地与阈值相匹配, 而不是在平等. `messagesExceed` 计数所有当前模式信件,包括 摘要和工具消息,不由用户翻转或原始存储的记录.

触发器只接收一个读取 `{ messages, tokens, cacheAgeMs, cacheRetentionMs }` 检查站后快照 重放和上下文准备. `tokens` 估计完整的模型输入 : 信件、指示、工具定义和任何结构化输出计划. 运行时间对消息和请求信封使用相同的字符heuristic. 提供方框架、代码-模式包装和服务器工具仍然大致相同. 自定义上方可以返回布尔或承诺; 采样前错误会停止转弯 。 这些帮助者不需要网络访问.

使用 `cacheLikelyCold()` 当观察到的快速缓存到达 提供者请求的保留窗口 :

```ts
import { cacheLikelyCold } from '@deepagents/compaction';

const triggers = [cacheLikelyCold()];
```

Zukhruf 读取本地 SDK 请求元数据 `include.requestBody`,在模型之后 中间软件应用了其设置。 它把假设的窗口与 ; 不需要额外的提供者 API 调用.

-   OpenAI GPT-5.6,后使用所记录的30分钟政策. 较早的模型 明确 `in_memory` 或者说 `24h` 设置使用保守的上限 1小时或24小时。 省略的旧模式政策不详,因为 组织可以确定默认. [OpenAI 缓存寿命](https://developers.openai.com/api/docs/guides/prompt-caching#cache-lifetime)。 。 。 .
-   Anthropic(包括本地的 Claude 提供者) 使用请求的缓存 控制:5分钟 `ttl` 删除或 `5m`,一个小时 `1h`。 。 。 . 所观察的缓存-写用法区分了五分钟和一小时的写作. 没有足够使用证据的混合断点有一个未知窗口; 请求更长的 TTL 不确定它的前缀被缓存 . [Athropic 缓存持续时间](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration)。 。 。 .
-   OpenRouter使用报告的上游提供者和解答模式. OpenAI和Anthropic路线使用这些政策。 未经承认的上游地区依然存在 未知;该型号的供应商前缀本身不足.

未经确认的提供者、缺少请求机构、没有支持的政策以及双子座 隐性缓存没有推断出保留窗口。 触发器仍未激活. 对自定义提供者来说,有明确的覆盖: `cacheLikelyCold({ retentionMs: yourProviderRetentionMs })`。强制必须是一个 以毫秒计的正安全整数。 平等相对.

Zukhruf 记录了主模型报告为阳性的启动请求时间 缓存读取或写出,包括最后一步。 写作零读取建立 一个新的基线。 用于远程测量的录制工作被禁用,在新鲜设备中存活 主持人。 没有正缓存计数器的成功反应可以清除基线.

`cacheAgeMs` 在不匹配证据的情况下未定义:分支、模型、, 指令、工具定义、 SDK 请求设置以及先前发送的信件 前缀必须仍然匹配,而时钟不能向后移动。 追加 信件保存前缀证据. 当证据或保留不明时,帮助者返回虚假. 估计 过期;它不查询提供者缓存状态或预测路由变化. 它不配置提供者缓存 。 无触发需要网络访问.

匹配触发器决定压缩 . `targetTokens` 限制由此产生的上下文; 它从来不压制比赛。 直接电话: `compact()` 也尝试减少, 即使输入已经符合目标. 设定超过目标的迹象阈值,以便在收缩间离开前厅. 在Zukhruf中,符号触发器和目标都覆盖了估计的全部输入. 这个 运行时间将指令/工具信封从 `targetTokens` 打电话前 `compact()`,然后将其添加到报告的结果中。 如果只有那个信封 使目标耗尽,转弯失败 `request-overhead` 在总结之前. 独立 `compact()` 仍然只预算它提供的信息。 储备产出 单间和供应 `countTokens` 为了媒体.

运行时间持续成功 `chat.metadata.zukhruf.inputUsage`,独立于遥测。 同样的 模型、分支、指令、工具、设置和未改变的预测消息 前缀,下一个估计数是所测量的输入和附加的估计 留言。 保留了缓存输入;产出和摘要模型使用不包括在内 再说一遍。 协会在东道主重启和检查站恢复后幸存. 更改设置/ 前缀或应用摘要使其无效 。 失踪或无效 使用量和本地公司/汇总迭代使用量回到新的估计数; 他们从未被视为可靠的上下文。 本地供货商压缩 无法使用此特性.

明确 `countTokens(messages)` 优于计量的使用。 运行时间 然后添加估计信封;独立通话只使用自定义计数. 这两种方法都无法保证一个精确的模型封顶。 不计算终点或模式 联系上目录了.

Zukhruf在每个模式步骤、邮箱输入和上下文提醒之前检查. 它在通过紧凑的元数据之前,坚持对对话进行检查 留言。 原始UI笔录保存完好. 后转和新主机 仅在检查点源前缀仍然匹配时重新使用; 倒带或编辑 更改前缀使其不适用。 压缩失败停止转弯 而不取代历史。 总结用法包括在谈话用法中.

### 生命周期事件

苏克鲁夫发射AI SDK `data-compaction` 转弯道上有块 他们打的 有效载荷, `CompactionEvent`,从 `@deepagents/experimental/zukhruf`。 。 。 . 同一事件 `id` 属于一项评价:

| `data.status` | 含义 | 细节 |
| --- | --- | --- |
| `started` | 匹配触发器; 正在尝试压缩 | 基于零 `triggerIndex`, (中文(简体) ), `tokensBefore`, (中文(简体) ), `targetTokens`, (中文(简体) ), `messageCount` |
| `completed` | 通过了摘要验证,并节省了检查站 | `tokens.before/after`, (中文(简体) ), `replacedRange`,总结 `usage` |
| `failed` | 评价、减少或检查站持续存在失败 | `phase` 财务报告和审定财务报表 `reason`;转会结束,没有通过新的摘要 |
| `restored` | 应用了兼容的保存检查站 | `sourceMessages`, (中文(简体) ), `replacementMessages` |

新设 `started` 财务报告和审定财务报表 `completed` 活动包括: `tokenScope: "request"`; DevTools 软件 将其计数标记为估计输入符。 没有这个历史事件 标记保留其信息估计含义.

例如,41条短信息,估计总输入量为2 000个信使匹配 `messagesExceed(40)` 即使有4000个目标: `started` 随后是 `completed` 当一个有效的摘要符合条件并保存了检查站时。 保险 边框和输出验证仍然适用:空的或完全被保护的历史 返回时 `cannot-fit`,以及一个过大的摘要。 无法匹配的触发器会发出否 紧凑尝试.

这些是原生的持久性数据部分。 每个块ID结合其评价ID 和状态,所以重放保留一个保存的每个状态的部分. AI SDK 软件 `onData` 还是 接收它们; 普通的 UI 语录保存它们重新打开 。 SDK 排除 数据部件来自模型输入,没有自定义转换器。 DevTools 组匹配 将评价ID输入一个可扩展的内入条目,并注明值和检查站 细节. 数据块即使在总和化等待时也会迅速冲出. 取消 使用现有的可持久转弯状态`cancelled`); 开始尝试,没有 当转弯不再流出时,终端事件似乎中断. 生命周期有效载荷中未包括概要文本或原始提供者出错.

## 核查

```sh
npx nx run @deepagents/compaction:typecheck
npx nx run @deepagents/compaction:test
```

集成测试使用公用包导出和AI SDK v7的V4模型固定. 他们行使预算成果,下游SDK生成,出处,重复 收缩、触发阈值、受保护的工具/核准边界、媒体计数器、, 错误和中止。 Zukhruf的融合测试 附加锻炼 工具循环、检查点重放、同步决定和触发出错.

## 常见问题

### @deepagents/compaction 是什么？

AI SDK - 内在对话紧凑 有明确的预算和来源\.

### 如何安装 @deepagents/compaction？

在项目目录运行 npm install @deepagents/compaction，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：ai（^7\.0\.153）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @deepagents/compaction 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @deepagents/compaction 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @deepagents/compaction 可以商用吗？

@deepagents/compaction 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @deepagents/compaction 的下载量有多少？

根据 npm 官方下载统计，@deepagents/compaction 在 2026/10/12 – 2026/11/10 这 30 天内被下载 2,010 次，日均约 67 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @deepagents/compaction 还在维护吗？

最新版本 7\.5\.2 发布于 2026/11/08（6 天前）；至今共发布 15 个版本，其中过去 12 个月发布了 15 个；首次发布于 2026/10/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。