跳转到内容
tansr 资料站

QueryCompactionOptions

查询环压缩接线选项(RunQueryOptions.compaction;提供即启用)。

两种注入形态:

  • manager:装配层持有的跨轮 ContextManager(账本锚点/附件签名/熔断计数 跨 runQuery 存续)。提供时其余自建字段全部忽略(阈值/保留策略以 manager 构造配置为准)。
  • 缺省:查询环按下列字段自建(生命周期 = 本次查询;测量退化为全量本地 估算,保守可用)。contextWindow 取 thresholds.contextWindow,缺省回退 RunQueryOptions.contextWindowTokens;两者皆缺是编程错误(启用压缩必须 知道窗口大小)。

属性

Section titled “属性”

anchorLayer?

Section titled “anchorLayer?”
optional anchorLayer?: {
  budgetTokens?: number;
  enabled: boolean;
};

P-CTX4 K15:锚点层 L1 门(doc/34 §3.4 机制 1;方案参数 anchorLayer/ anchorBudgetTokens 经策略展开落此位)。映射为 manager 构造级配置 (语义见 ContextManagerCompactionOptions.anchorLayer)。缺席 = 关 (现状零漂移);manager 注入形态下忽略(锚点层随外部 manager 构造)。

budgetTokens?

Section titled “budgetTokens?”
optional budgetTokens?: number;

enabled

Section titled “enabled”
enabled: boolean;

attachments?

Section titled “attachments?”
optional attachments?: AttachmentRegistryOptions;

自建路径的附件注册表参数(TTL 轮数/session 字节 预算)。附件三态裁决(注入/引用化/预算拒绝)的调用方:TUI

File

Section titled “File”

引用 (装配层 session-driver)与查询环诊断类元注入(reminder 径)。 manager 注入形态下忽略(与其余自建字段同语义——注册表随 manager 构造,见 ContextManagerOptions.attachments)。

auto?

Section titled “auto?”
optional auto?: boolean;

轮间自动触发开关;默认 true。false 时仅手动(compactNow)与真溢出 reactive 恢复两条路径生效。

beforeCompact?

Section titled “beforeCompact?”
optional beforeCompact?: QueryBeforeCompactHook;

压缩前钩子(「compactNow 把选项传下」的注入面;装配层 落 pre_compaction 快照)。查询环在压缩屏障点组装为 CompactRequest. beforeCompact(经 GovernanceDirective 输入面,与 instructions 同位)交 manager 调用;compactNow({ checkpoint }) 的选项经 context.checkpoint 抵达 (false 则本次不调用)。auto/reactive 压缩同样调用(context.checkpoint 缺席,装配层按自身缺省决定)。缺席 = 不接线(现状零漂移)。 注意:本字段由查询环消费(非 manager 构造集)——manager 注入形态下同样 生效。装配层直调 ContextManager.compact(空闲直压)时应自行设置 CompactRequest.beforeCompact,本字段不覆盖该径。

bucketedCalibration?

Section titled “bucketedCalibration?”
optional bucketedCalibration?: {
  confidenceMarginRatio?: number;
  enabled: boolean;
};

P-CTX4 K16:估算-校准闭环门(doc/34 §3.4 机制 5;方案参数 bucketedCalibration/confidenceMarginRatio 经策略展开落此位)。映射为 manager 构造级配置(语义见 ContextManagerCompactionOptions. bucketedCalibration)。缺席 = 关(单标量校准语义零漂移);manager 注入形态下忽略(校准配置随外部 manager 构造)。

confidenceMarginRatio?

Section titled “confidenceMarginRatio?”
optional confidenceMarginRatio?: number;

enabled

Section titled “enabled”
enabled: boolean;

budgetAwareness?

Section titled “budgetAwareness?”
optional budgetAwareness?: {
  enabled: boolean;
};

P-CTX5 K22:预算自觉注入门(doc/35 机制 10;方案参数 budgetAwareness 经策略展开落此位)。消费方 = 查询环请求构造点:门开且本屏障有占用 估算时,请求副本尾部注入 <context-budget …/> 协议块(模型自主 收敛材料;不入 journal 正史/不进压缩候选/resume 重演恒重算,论证见 budget-awareness.ts)。缺席 = 关(请求体字节零漂移)。manager 注入 形态下同样生效(消费方是查询环,非 manager 构造集)。

enabled

Section titled “enabled”
enabled: boolean;

cacheAwareRewrite?

Section titled “cacheAwareRewrite?”
optional cacheAwareRewrite?: {
  enabled: boolean;
};

P-CTX5 K21:缓存感知改写节律门(doc/35 机制 9;方案参数 cacheAwareRewrite 经策略展开落此位)。仅 baseline 会话策略半边消费 ——高命中率(EWMA ≥ CACHE_HIT_DEFER_THRESHOLD)且水位非紧急时推迟 microcompact 原位改写(改写必破缓存前缀);命中率材料由 manager recordUsage 恒观测(纯观测,门关零行为)。缺席 = 关(现状零漂移)。 manager 注入形态下同样生效(本键消费方是 baseline 会话,非 manager 构造集)。

enabled

Section titled “enabled”
enabled: boolean;

client?

Section titled “client?”
optional client?: ModelClient;

自建路径:摘要模型客户端;缺省复用主 client(fork 同模型,doc/07 §3.2)

endpointAware?

Section titled “endpointAware?”
optional endpointAware?: {
  enabled: boolean;
};

P-CTX4 K14:端点感知压缩门(doc/34 §3.4 机制 3+4;方案参数 endpointAwareCompaction 经策略展开落此位)。生效面两半:manager 构造级 halfOpenBackoff(半开探测指数退避)+ baseline 会话 endpointAware (劣化升级折叠与延迟决策,消费下方 endpointHealthProbe)。缺席 = 关 (现状零漂移)。manager 注入形态下 backoff 半边随外部 manager 构造, 本键只驱动会话半边。

enabled

Section titled “enabled”
enabled: boolean;

endpointHealthProbe?

Section titled “endpointHealthProbe?”
optional endpointHealthProbe?: EndpointHealthProbe;

P-CTX4 K14:端点健康探针(装配事实,非方案参数——attempt 传输观测的 滚动聚合快照闭包,目标 = 压缩链路主端点)。仅 endpointAware.enabled 时被消费;缺席 = 劣化判定失明回落现状(fail-open)。

estimator?

Section titled “estimator?”
optional estimator?: TokenEstimator;

自建路径:token 估算器注入缝。 例外注记:压缩后文件重建的预算估算(run-query 注入点)也消费 本字段,且不受「manager 在场忽略自建字段」通则约束——manager 内部 估算器为私有不可达,重建预算独立取本字段(缺省回退默认估算器);两者 口径偏差由 H2 帽(min(20K, 压缩回收量-1))兜底,方向安全。

instructionTemplate?

Section titled “instructionTemplate?”
optional instructionTemplate?: string;

自建路径:摘要指令模板/前导句注入缝

keepFirstUserMessage?

Section titled “keepFirstUserMessage?”
optional keepFirstUserMessage?: boolean;

自建路径:首条用户消息(任务锚点)恒保留;默认 true

keepRecentRounds?

Section titled “keepRecentRounds?”
optional keepRecentRounds?: number;

自建路径:保留最近 N 轮(round 粒度;单 round 超长时退化为折叠单元粒度);默认 2

manager?

Section titled “manager?”
optional manager?: ContextManager;

跨轮共享的 ContextManager(优先;提供时下列自建字段忽略)

maxOutputTokens?

Section titled “maxOutputTokens?”
optional maxOutputTokens?: number;

装配层注入的当前压缩模型 maxOutput 上限(来源 = cli 侧静态侧表,官方值带出处)。 压缩输出预算 = min(maxOutputTokens ?? 20_000, thresholds.compactOutputBudget); 不得再与会话 options.maxTokens 钳制(否则摘要会被静默截断)。

model?

Section titled “model?”
optional model?: ResolvedModel;

压缩 fork 的模型标识(OPT-10 降档;CompactRequest.model 留口的注入面): 与摘要客户端成对注入——client 发什么 wire 请求由本字段决定,两者 必须指向同一模型(manager 注入形态下与 manager 持有的 client 成对)。 缺省 = 主模型(fork 同模型,doc/07 §3.2)。压缩 round 自身的 cost.usage.updated 以本字段归因(byModel 分桶独立可见)。 分层铁律:kernel 不解析别名——fast 档解析在 cli 装配层(providers/ registry 事实),此处只接受已解析的 (provider, model) 标识。

observer?

Section titled “observer?”
optional observer?: CompactionObserver;

上下文治理只读观测缝(压缩生命周期 + microcompact 应用 + 入史 clamp 计数)。kernel 公共 API(非 protocol);装配层消费写 context-events.jsonl。签发权分布见 CompactionObserver 注释 (成功结局经统一应用器;失败/no-op 在 manager 返回面)。回调异常不得 影响压缩主链(fail-open,由消费侧自行捕获)。

restoreFileReader?

Section titled “restoreFileReader?”
optional restoreFileReader?: RestoreFileReader;

压缩后文件重建的读文件闭包(kernel 零文件 IO, 装配层注入,与 toolResultBudget.persist 先例同构)。在场时查询环维护 Read/Edit/Write 触达台账,压缩成功后把最近触达 top-3 文件以合成 tool 对 + <system-reminder> 注入摘要之后、保留尾段之前(预算:单文件 5K / 总 20K tokens,常量出处见 context/file-restore.ts)。 缺席 = 功能静默关闭(不记台账、不注入),行为与现状逐字节一致。 注意:本字段由查询环消费(非 manager 构造集)——manager 注入形态下 与自建形态同样生效,不受「manager 在场忽略自建字段」语义约束。 本闭包由内置 baseline 治理会话消费(台账与注入随策略), 注入语义与生命周期不变。

segmentLookback?

Section titled “segmentLookback?”
optional segmentLookback?: {
  enabled: boolean;
};

CW14-N5:压缩段回查节门(方案参数 compactionSegmentLookback 经策略 展开落此位)。映射为 manager 构造级配置(语义见 ContextManagerCompactionOptions.segmentLookback)。缺席 = 关(摘要 字节零漂移);manager 注入形态下忽略(随外部 manager 构造)。

enabled

Section titled “enabled”
enabled: boolean;

session?

Section titled “session?”
optional session?: GovernanceSession;

治理策略会话注入缝(@experimental)。缺省 = 内置 baseline 策略包装本查询解析出的 ContextManager(行为与策略化前逐字节一致)。 注入时查询环五点位改经注入会话,ContextManager 仍作 账本/测量引擎由查询环持有(recordUsage/compactNow 守卫不变)。 注入面限装配层(围栏 3);会话生命周期由注入方管理。

summaryPreamble?

Section titled “summaryPreamble?”
optional summaryPreamble?: string;

thinkingMode?

Section titled “thinkingMode?”
optional thinkingMode?: "off" | "inherit";

压缩 fork 思考旋钮(2026-08-25 拍板;方案参数 compactionThinking 经 策略展开落此位)。‘off’ = fork 显式关思考(摘要任务思考增益低, Codex compact_model_reasoning_effort 同哲学——降配不换模);缺席/ ‘inherit’ = 继承主请求 thinking(现状零漂移)。门判在查询环 governance 组装点(run-query):‘off’ 的落线形态取决于下方 thinkingOffSupported 能力位。

thinkingOffSupported?

Section titled “thinkingOffSupported?”
optional thinkingOffSupported?: boolean;

压缩模型「思考可关」实证能力位(装配层随 maxOutputTokens 同通道穿入:压缩模型解析后 capability.reasoning===true 且 thinkingOptional===true 的白名单实证,RFC-M3 B2 词表)。消费点 = thinkingMode=‘off’ 的落线分派:

  • true → fork 请求显式注 thinking:{off:true}(适配器按方言关断)—— RFC-M3 B2 已实证 openai 兼容面思考模型缺省仍开思考,单纯省略 thinking 字段是静默失效;
  • 缺席/false(未实证端点/非思考模型)→ 保持省略字段。已知限界 (据实登记,恒不猜):未实证的思考模型此形态下 fork 是否思考随 上游缺省(可能仍开思考)——显式 off 参数对未实证方言有 400 风险, 保守方向与 aux-model mainFastModeEligible 白名单制同律;非思考模型 省略即正确(无思考可关,发关断参数徒增方言 400 风险)。

thresholds?

Section titled “thresholds?”
optional thresholds?: Partial<ThresholdConfig>;

自建路径:阈值配置。缺省口径见 doc/07 §3.1(200K 窗口下自动触发线 = effectiveWindow(180K)- 13K = 167K,约 effectiveWindow 的 92%)。

timeoutMs?

Section titled “timeoutMs?”
optional timeoutMs?: number;

自建路径的压缩 round 模型调用超时(ms)。映射为 manager 构造级 timeoutMs(取值链:CompactRequest 请求级 > 本构造级 > kernel 90s 缺省)——装配层方案 manager 级参数自此不再需要 compact 包装缝。quirk 下限换算(max(90s, minTimeoutMs))仍是装配层 注入前的责任。manager 注入形态下忽略(与其余自建字段同语义)。

toolResultDecay?

Section titled “toolResultDecay?”
optional toolResultDecay?: ToolResultDecayConfig;

P-CTX3:自建路径的 L3 工具结果分级衰减配置(doc/34 §3.4 机制 2;语义 见 ContextManagerCompactionOptions.toolResultDecay)。映射为 manager 构造级配置。缺席 = 关(现状 microcompact 零漂移);方案参数 toolResultDecay/decayHysteresisTokens 经策略展开落此位。 manager 注入形态下忽略(与其余自建字段同语义)。

transcriptHint?

Section titled “transcriptHint?”
optional transcriptHint?: string | (() => string | undefined);

自建路径的转录回查路径提示(字符串或求值闭包; 语义见 ContextManagerCompactionOptions.transcriptHint)。映射为 manager 构造级配置(请求级覆盖仍胜出)。manager 注入形态下忽略。