Responses API 压缩进度事件解读：response.compaction.compacting、compaction_trigger 与长会话上下文压缩

长会话跑得越久，上下文窗口越紧，压缩（compaction）是 Responses API 给出的答案。2026-09-16，openai-node v7.17.0（19:23 UTC 发布）给这套体系补上了最后一块可观测性拼图：流式进度事件 response.compaction.compacting（PR #2749）。它是压缩过程的心跳信号——告诉客户端"压缩在推进"，但刻意不携带任何摘要内容。本文基于当日从 v7.17.0 tag 提取的类型定义与规范文本，逐项拆解事件语义、字段、它在整个压缩体系里的位置，以及 Python 侧的落地差异。

更新注记（2026-09-19）：本文成稿时 Python 侧尚未跟进；openai-python v3.15.0（2026-09-18 发布，PR #3866）已补齐同一事件——ResponseCompactionCompactingEvent（beta 变体 BetaResponseCompactionCompactingEvent 带可选 agent 字段），字段为 type / item_id / output_index / sequence_number，与 node 侧一致。下文所有"Python 截至 v3.14.1 无此事件""node 独有"的表述均为当时（2026-09-17 核对）的记录，现状以本注记为准；逐项拆解见《openai-python 3.15 / 3.16 与 openai-node 7.18 / 7.19 更新解读：缓存预热、Webhook 管理与 connector_id 弃用》。

1. 概述：一个不含内容的心跳事件

规范文本对这个事件的完整描述只有两句话："Emitted when new summary content is sampled for a compaction trigger. Contains no summary content."（为压缩触发器采样到新摘要内容时发出；不包含摘要内容。）展开后的行为约束更具体：

• 节流：处理 compaction_trigger 时，该事件至多每 30 秒上报一次新采样的摘要输出；
• 无内容：事件不携带摘要内容，也不修改 compaction 输出项本身；
• 生命周期分离：压缩输出项的建立与完成仍由既有的 response.output_item.added / response.output_item.done 事件标记，其中 done 携带该输出项最终的加密内容；
• 不保证发生：一次很短的压缩可能在没发出任何进度事件的情况下直接完成。

这四个约束共同指向一个设计意图：进度事件只做可观测性（让 UI 能显示"压缩中"），内容交付与完成判定仍走原有的输出项生命周期，客户端状态机不需要为它增加必经分支。

2. 事件字段与三种形态

标准形态（HTTP 流式）下，事件对象只有四个字段，全部是位置与排序信息：

在此之上还有两种变体，各自只多一个可选字段：

同一规范在 WebSocket 文档一节还补了一句：压缩进度遵循与 HTTP 流式相同的节奏（cadence）与输出项生命周期——即两种传输层下语义一致。

3. 压缩体系全景：这个事件补在哪一环

response.compaction.compacting 不是孤立的新端点，而是给一套已经存在的压缩体系补了进度观测。写本文时逐个核对过 v7.16.0 / v3.12.0 tag：下表前四行组件都不是本批新增。

换句话说：触发靠输入项或配置，产物靠输出项或 REST 端点，而 v7.17.0 补的是过程中"现在压到哪了"的信号。SDK 侧的处理方式也印证了定位——node 包内部的事件累加器（response-accumulator）把它登记为忽略类进度事件，并把它归属到输出项类型 compaction，不会把它累积成任何输出内容。

4. 最小接入示例

以下示例全部取自 v7.17.0 tag 上验证过的类型与文档写法（文档核对版；docs/responses.md 与 src/resources/responses/responses.ts）。

触发侧：把压缩触发项放在输入数组最后：

import OpenAI from 'openai';

const client = new OpenAI();

const response = await client.responses.create({
  model: 'gpt-5.6-terra',
  input: [
    { role: 'user', content: '把这份会议记录整理成行动项。' },
    // …此处省略此前累积的长上下文输入项…
    { type: 'compaction_trigger' }, // 必须是最后一个输入项
  ],
});

HTTP 流式消费侧：识别进度事件、但不指望它携带内容：

// 事件处理分支（节选）：进度事件只用于展示"压缩中"状态
function handleEvent(event: { type: string }) {
  switch (event.type) {
    case 'response.compaction.compacting':
      // item_id / output_index / sequence_number 可用于定位压缩项
      // 注意：事件不含摘要内容；完成与否以 output_item.done 为准
      showCompactingIndicator();
      break;
    case 'response.output_item.done':
      hideCompactingIndicator();
      break;
  }
}

WebSocket 侧（Node 侧需要 ws 对等依赖）：WebSocket 变体多了可选的 stream_id，其余字段一致：

import OpenAI from 'openai';
import { ResponsesWS } from 'openai/resources/responses/ws';

const client = new OpenAI();
const socket = new ResponsesWS(client);

socket.on('event', (event) => {
  if (event.type === 'response.compaction.compacting') {
    // event.stream_id 仅在 response.create 指定了 stream_id 时出现
    console.log('compacting', event.item_id, event.output_index);
  }
});

5. 版本与跨包差异

• openai-node v7.17.0（2026-09-16T19:23 UTC）：事件进入标准与 beta 两套 responses 类型；同批规范把 compact 端点摘要改名为 "Compact conversation"，并在 WebSocket 文档中补齐进度节奏说明。
• openai-python 截至 v3.14.1（2026-09-15T23:12 UTC 发布，为当日最新版）：api.md 无 CompactingEvent 条目，tag 树中没有对应类型文件（2026-09-17 当日以 raw 文件与 git trees API 双重核对，均为 0 命中）。该事件当时是 node 侧先行——这一差距已于 2026-09-18 随 python v3.15.0 补齐（见文首更新注记）；两包版本号本就不一一对应，同一 API 改动落在不同版本是常态（本站此前批次已多次遇到）。
• 基线归属：第 3 节表格里的四个既有组件并非本批新增——node v7.16.0（2026-09-15 发布）的 responses.ts 与 api.md 里已能找到 compaction_trigger 输入项、context_management 配置、compact 端点与压缩输出项类型，python v3.12.0（2026-09-10 发布）的 tag 树里也已有压缩项与 compact 参数的类型文件（2026-09-17 逐项核对）。

6. 常见错误与排查

• 把进度事件当内容事件读：事件里没有摘要内容——这是规范明确设计，不是缺陷。摘要内容只在 response.output_item.done 携带的压缩项 encrypted_content 里。
• 状态机强依赖进度事件：短压缩可能一个进度事件都不发。完成判定只能锚定 output_item.done；进度事件只适合做 UI 提示或日志。
• beta 多智能体流里不区分归属：多个 agent 各自压缩时，用可选的 agent.agent_name 区分事件归属；BetaResponseCompactionItem 同样带该字段。
• WebSocket 下期待 stream_id 恒存在：该字段仅当发起 response.create 时指定了 stream_id 才会出现，按可选处理。
• 把 /responses/compact 与流式进度混为一谈：REST 端点是一次性拿到压缩结果；进度事件服务于流式过程中的观测，两者入参出参不同。

7. 下一步

• 《gpt-6-astra 现身 OpenAI SDK：ChatModel 枚举新模型 ID 与 Safety Alerts API 解读》：context_management 配置（压缩自动触发的 token 阈值）的类型拆解在本文第 5 节。
• 《Codex CLI 0.154.0 与 SDK 0.154.0 发布解读：worktree、ExternalMessage 与 ultra 推理档》：Codex CLI 产品层的压缩与审批上下文行为，与本文的 API 层事件分属两面。
• 《Agents API 现身 OpenAI SDK（beta）：/agents CRUD、environments、sessions 与 vaults 全景》：多智能体会话背景——beta 事件变体的 agent.agent_name 正是给这类场景准备的。
• 《Live API 现身 OpenAI SDK：gpt-live-1、WebRTC/WebSocket 双通道与 SIP 通话控制解读》：另一套走 WebSocket 的实时接口面。
• 《Responses API 高级实战：structured outputs / 流式 SSE / Batch / prompt caching》：流式消费与长上下文的机制底座。
• 《openai-python 3.14.x 与 openai-node 7.16 / 7.17 更新解读：流式错误规范化、WebSocket 背压与 SSE 兜底》：同一批发布的可靠性改动全景，含 WebSocket 迭代器背压。
• 《openai-python 3.15 / 3.16 与 openai-node 7.18 / 7.19 更新解读：缓存预热、Webhook 管理与 connector_id 弃用》：Python 侧补齐本事件的那一批（v3.15.0）的全景解读。
• 《OpenAI 模型更新日志（2026 持续更新）》：所有发布的时间线总览。