berry-agent 0.1.0-alpha.1

package/dist/compaction/ccr-tools.js

@@ -0,0 +1,112 @@
+import { Type } from 'typebox';
+import { deriveMessages } from '../session/index.js';
+import { CCR_MARKER_PREFIX, ccrDirectoryOf } from './ccr.js';
+/** 渲染预算 56KiB（05 §2.1 分段续取律定值——留界外余量给尾部账，常态不触 append 刀） */
+const RENDER_BUDGET_CHARS = 56 * 1024;
+/** 内容块面 → 纯文本（string 直通；块数组 text 块取文本、他块 JSON 形——渲染面保真不猜） */
+function textOf(content) {
+    if (typeof content === 'string')
+        return content;
+    return content
+        .map((block) => {
+        const b = block;
+        return b.type === 'text' && typeof b.text === 'string' ? b.text : JSON.stringify(block);
+    })
+        .join('\n');
+}
+/** 投影消息 → 可读文本行（模型消费形——角色标注 + 工具调用/结果结构呈现） */
+function renderProjected(message) {
+    switch (message.type) {
+        case 'user':
+            return `[user] ${textOf(message.content)}`;
+        case 'assistant': {
+            const parts = [`[assistant] ${textOf(message.content)}`];
+            for (const call of message.toolCalls) {
+                parts.push(`  · 工具调用 ${call.toolName}(${call.toolCallId}) 参数: ${call.arguments}`);
+            }
+            if (message.errorMessage !== undefined)
+                parts.push(`  · 错误: ${message.errorMessage}`);
+            return parts.join('\n');
+        }
+        case 'toolResult':
+            return `[${message.isError ? 'toolResult·出错' : 'toolResult'} ${message.toolName}] ${textOf(message.output)}`;
+    }
+}
+/** 归档目录形（hash 缺省消费面）：空目录诚实明示 */
+function directoryText(events) {
+    const entries = ccrDirectoryOf(events);
+    if (entries.length === 0)
+        return '本会话暂无 CCR 归档（未压缩过，或遮蔽段早于 CCR 机制引入——批前历史不可回取）。';
+    const lines = entries.map((e) => `${CCR_MARKER_PREFIX}${e.hash}>> ${e.messages} 条消息 / ${e.chars} 字符`);
+    return `本会话已归档压缩段（hash 传入 ccr_retrieve 可取回原文）：\n${lines.join('\n')}`;
+}
+/** 区间命中形：事件切片重导 + 分段续取窗口（冷读闸 M1——至少渲染一条 + 预算累加） */
+function rangeText(events, start, end, fromMessage, budget) {
+    const slice = events.filter((event) => event.seq >= start && event.seq <= end);
+    const messages = deriveMessages(slice);
+    if (messages.length === 0)
+        return '区间不可读：遮蔽区间内无可重导的消息（事件残缺或形态不规则）。';
+    const from = Math.max(0, Math.min(fromMessage, messages.length - 1));
+    const rendered = [];
+    let used = 0;
+    let taken = 0;
+    for (let i = from; i < messages.length; i += 1) {
+        const line = renderProjected(messages[i]);
+        // 至少渲染一条（首条无条件收）；随后累加至预算即止——尾部恒可续取
+        if (taken > 0 && used + line.length > budget)
+            break;
+        rendered.push(line);
+        used += line.length;
+        taken += 1;
+    }
+    const total = messages.length;
+    const tail = from + taken < total
+        ? `（已渲染 ${from + taken}/${total} 条——续取传 fromMessage=${from + taken} 可取余下）`
+        : `（已渲染 ${from + taken}/${total} 条，本段已取尽）`;
+    return `${rendered.join('\n\n')}\n\n${tail}`;
+}
+/** ccr_retrieve 工具工厂（装载位/测试唯一入口）——单件定义数组（族位形，obs/control 同构） */
+export function createCcrRetrieveTool(deps) {
+    const budget = deps.renderBudgetChars ?? RENDER_BUDGET_CHARS;
+    return [
+        {
+            name: 'ccr_retrieve',
+            description: '取回本会话压缩归档段的原文（可逆压缩——摘要是有损呈现、原文无损归档）。' +
+                `上下文里形如 ${CCR_MARKER_PREFIX}哈希>> 的标记即归档锚：把哈希传入本工具即得该段原文。` +
+                '不传 hash 返回归档目录（逐段哈希/消息数/字符数）。' +
+                '大段自动分窗：返回尾部标注「已渲染 X/N 条」，传 fromMessage=X 续取余下。' +
+                '只读本会话历史（曾可见内容，非新信息）；哈希不在归档集时如实回报原因。',
+            parameters: Type.Object({
+                hash: Type.Optional(Type.String({ description: '归档哈希（<<ccr:…>> 标记内的 16 位十六进制串；缺省返回目录）' })),
+                fromMessage: Type.Optional(Type.Number({ description: '续取位（区间内消息 0 基序——分窗续取用；缺省 0）' })),
+            }, { additionalProperties: false }),
+            effect: 'read',
+            execute: async (args) => {
+                const events = deps.events();
+                const hash = args.hash;
+                if (hash === undefined)
+                    return { content: [{ type: 'text', text: directoryText(events) }] };
+                // 命中匹配：只认本会话 surface 事件的存储哈希（归属结构性免疫——伪标记必 miss 零副作用）
+                const hit = events.find((event) => event.type === 'compaction/surface' && event.data.ccrHash === hash);
+                if (hit === undefined) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `未找到哈希 ${hash} 的归档段。可能原因：哈希不在本会话归档集` +
+                                    '（标记来自其他来源或已损坏）、或该段遮蔽早于 CCR 机制引入（批前历史不可回取）。' +
+                                    '可先不传 hash 查看本会话归档目录核对。',
+                            },
+                        ],
+                    };
+                }
+                const op = hit.surfaceOp;
+                if (op === undefined) {
+                    return { content: [{ type: 'text', text: '区间不可读：归档事件缺少区间信封（数据形态异常）。' }] };
+                }
+                const fromMessage = typeof args.fromMessage === 'number' && Number.isFinite(args.fromMessage) ? args.fromMessage : 0;
+                return { content: [{ type: 'text', text: rangeText(events, op.start, op.end, fromMessage, budget) }] };
+            },
+        },
+    ];
+}

package/dist/compaction/ccr.js

@@ -0,0 +1,84 @@
+/**
+ * compaction — CCR 可逆压缩纯函数件（05 §2.1「压缩可逆性 CCR」子节——2026-09-11
+ * 立题批落码；立题档《00-立题-压缩可逆性CCR-20260911》+ 冷读闸 M1-M7 修订形）。
+ *
+ * 机制三面（第四面「两路一形」由 fiveStep 共用自动获得）：
+ *  - 归档映射：ccrHashOf = sha256(遮蔽区间投影消息序列规范化 JSON——**含 seq
+ *    位**〔冷读闸 M4：内容+序寻址，fork 平移后同内容异哈希；兑换按存储哈希
+ *    匹配不重算比对〕) 前 16 hex。events 表即归档 store（零新增存储位）；
+ *  - 标记段：摘要载体尾部 host 追加（非摘要算法产物）；当次标记行 + **目录
+ *    恒链**（此前历次 surface 事件全量——旧载体被遮蔽后历史哈希仍可达）；
+ *    文案不点名工具（冷读闸 M5：无工具面形态下点名即对模型的空承诺）；
+ *  - 目录源：从 surface 事件重建（孤儿摘要无映射不入目录——冷读闸 M2 自愈
+ *    三径之一）；CCR 批前历史事件 ccrHash 缺席不列（冷读闸 M6：无检索键
+ *    不可回取）。
+ *
+ * 纯函数零 I/O（events 读面由调用方注入）。
+ */
+import { createHash } from 'node:crypto';
+/** CCR 标记行前缀（<<ccr:HASH>> ——标记段构造与剥离的判据锚） */
+export const CCR_MARKER_PREFIX = '<<ccr:';
+/**
+ * 规范序列化：对象键递归排序的确定性 JSON（哈希源的单义形——ProjectedMessage
+ * 构造路径键序天然可异，键序差不应改哈希；含 seq 位——冷读闸 M4 定形）。
+ */
+function canonicalJson(value) {
+    return JSON.stringify(value, (_key, val) => {
+        if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+            const record = val;
+            const sorted = {};
+            for (const key of Object.keys(record).sort())
+                sorted[key] = record[key];
+            return sorted;
+        }
+        return val;
+    });
+}
+/**
+ * 归档哈希：遮蔽区间投影消息序列 → sha256 前 16 hex。
+ * 确定性：同序列同哈希；seq 变（fork 平移/区间漂移）即异——兑换按存储哈希
+ * 匹配、不重算比对（重算比对会在 fork 会话全数 miss）。
+ */
+export function ccrHashOf(occluded) {
+    return createHash('sha256').update(canonicalJson(occluded)).digest('hex').slice(0, 16);
+}
+/** 目录重建：surface 事件 → 检索面条目（seq 序 = 时间序；批前缺 ccrHash 位者跳过） */
+export function ccrDirectoryOf(events) {
+    const entries = [];
+    for (const event of events) {
+        if (event.type !== 'compaction/surface')
+            continue;
+        const data = event.data;
+        // 兼容位（05 §1.1 ccrHash?）：CCR 批前历史事件缺席——无检索键不可回取，不列
+        if (typeof data.ccrHash !== 'string')
+            continue;
+        if (typeof data.occludedMessages !== 'number' || typeof data.occludedChars !== 'number')
+            continue;
+        entries.push({ hash: data.ccrHash, messages: data.occludedMessages, chars: data.occludedChars });
+    }
+    return entries;
+}
+/** 标记行（单条）：`<<ccr:HASH>> 原文已归档（N 条消息 / M 字符）` */
+function ccrMarkerLine(entry) {
+    return `${CCR_MARKER_PREFIX}${entry.hash}>> 原文已归档（${entry.messages} 条消息 / ${entry.chars} 字符）`;
+}
+/**
+ * 标记段追加：摘要正文 + `\n\n` + 目录全量标记行（时间序，当次条目由调用方
+ * 末位并入——目录恒链）。标记段不计入摘要预算（机制面固定开销非摘要正文）。
+ */
+export function withCcrSection(summaryBody, entries) {
+    if (entries.length === 0)
+        return summaryBody;
+    return `${summaryBody}\n\n${entries.map(ccrMarkerLine).join('\n')}`;
+}
+/**
+ * 标记段剥离：首条 `<<ccr:` 行起截断（previousSummaryText 迭代链消费——目录
+ * 行是机制噪声非摘要素材）。无标记行原样返回（CCR 批前载体兼容）。
+ */
+export function stripCcrSection(text) {
+    const lines = text.split('\n');
+    const cut = lines.findIndex((line) => line.startsWith(CCR_MARKER_PREFIX));
+    if (cut === -1)
+        return text;
+    return lines.slice(0, cut).join('\n').trimEnd();
+}

package/dist/compaction/codes.js

@@ -0,0 +1,21 @@
+/**
+ * compaction 域错误码注册（02 §5.3 COMPACTION_ 族——2026-09-09 U4 规范
+ * 先行批明列两码；03 §2.2 第十二面/§2.7 两动词行）。
+ *
+ * 两码同为槽位占用拒（单席位先到占的执法位）——装载窗 only 的窗外拒
+ * 复用 PLUGIN_WINDOW_CLOSED（host 既有码，不在本册）。本文件由模块公开面
+ * index.ts 引入（注册纪律：import 发生才注册）。
+ */
+import { registerErrorCodes } from '../contracts/index.js';
+registerErrorCodes([
+    {
+        code: 'COMPACTION_CONFIG_TAKEN',
+        module: 'compaction',
+        description: '数值配置槽席位已占拒（03 §2.7 ctx.compaction.setConfig——单席位先到占、后到拒；配置主权单源：两插件各设阈值 = 用户装配面错误，fail-loud 拒不静默 last-wins）',
+    },
+    {
+        code: 'COMPACTION_SUMMARIZER_TAKEN',
+        module: 'compaction',
+        description: '摘要 provider 槽席位已占拒（03 §2.7 ctx.compaction.registerSummarizer——单席位先到占；溢出兜底恒宿主缺省算法系既有立法，槽不可及）',
+    },
+]);

package/dist/compaction/index.js

@@ -0,0 +1,18 @@
+/**
+ * compaction 模块公开面（L3 宿主固定件——02 篇席 9，随裁决①入宿主；机制真源 05 篇 §2.1/§2.3）。
+ *
+ * 本批落码：五步骨架两事件形（摘要普通 append + compaction/surface 正门信封）
+ * + 阈值/溢出双触发路 + 全局串行队列 + per-session 防抖分账（帽 256 空闲逐出）。
+ * host 装配四件（阈值配置/触发器接线/complete 通道 provide/防抖参数）随 host 批。
+ * 2026-09-09 U4 批：槽位化三类型（SummarizerFn/SessionBeforeCompactInput）+
+ * COMPACTION_ 码族注册（import 发生才注册——公开面引入即注册纪律）+ U4-3
+ * 装配件（席位容器 slots——createCompactionSlots 席位状态机 + 值链归因铸造
+ * 两律机制件，host 装配层消费）。
+ */
+import './codes.js';
+export * from './types.js';
+export { BEFORE_COMPACT_ATTRIB, createCompactionSlots, forgeBeforeCompactIdentity, markBeforeCompactRewrite, } from './slots.js';
+export { SUMMARY_PREFIX, buildSummaryPrompt, evaluateThreshold, inCooldown, planFromRange, planSegment, previousSummaryText, summaryBudgetFor, validateAdjustedRange, } from './policy.js';
+export { createCompactionService } from './service.js';
+export { CCR_MARKER_PREFIX, ccrDirectoryOf, ccrHashOf, stripCcrSection, withCcrSection, } from './ccr.js';
+export { createCcrRetrieveTool } from './ccr-tools.js';

package/dist/compaction/policy.js

@@ -0,0 +1,200 @@
+import { stripCcrSection } from './ccr.js';
+/** 摘要载体前缀（防注入标记：模型可辨框架文本与用户话语；提取前次摘要时剥除） */
+export const SUMMARY_PREFIX = '[COMPACTION-SUMMARY]';
+/* ---------------- 阈值判定（05 §2.1「阈值」段单源） ---------------- */
+/**
+ * 阈值判定：真 token 计量主判（provider 报的 input 真值），投影字符数仅作
+ * 无真值时的保守兜底（字符/4 估算——换算不稳定，真值可用时不猜）。
+ * 返回 fire（是否触发）+ basis 三件（阈值路落 compaction/start 的判据快照）。
+ */
+export function evaluateThreshold(input) {
+    // 无真值且投影为零（空会话）——无从判阈，null = 不触发也无判据可记
+    if (input.usageInput === null && input.projectedChars === 0)
+        return null;
+    const effectiveWindow = input.contextWindow ?? input.config.fallbackWindowTokens;
+    if (effectiveWindow <= 0)
+        return null; // 防御：非正窗口无从比较
+    // 真值可用时不猜——估算仅兜底（chars/4：粗略 4 字符/token 换算）
+    const estTokens = input.usageInput !== null ? input.usageInput : Math.ceil(input.projectedChars / 4);
+    return {
+        basis: input.usageInput !== null ? 'usage' : 'estimate',
+        estTokens,
+        effectiveWindow,
+        fire: estTokens / effectiveWindow >= input.config.thresholdRatio,
+    };
+}
+/* ---------------- 区间规划（05 §2.1「区间规划三则」+ 边缘纪律） ---------------- */
+/**
+ * 区间规划：在合法跨度（终点 ≤ 最近完整 turn 边界；起点对齐 turn 边界）内按
+ * 三则细化——head 保首个完整 turn（任务锚；切点须 turn/start 对齐——正门对齐
+ * 律的结构推论）、tail 保末 tailKeep 条、最小条数保护（head+tail 之外中段
+ * ≥ 1 条放不下即不压）。
+ *
+ * 返回 null = 诚实无操作（区间不足/日志无闭合 turn/骨架不规则）；规划输入
+ * 须为互斥锁内新投影（service 全局串行队列保证——排队等待期间他路压缩可能
+ * 已改写投影，规划与落账同账零迟滞窗）。
+ */
+export function planSegment(input) {
+    const { events, messages, tailKeep } = input;
+    // 终点界桩：最近完整 turn 边界（无闭合 turn = 无可压区间）
+    let boundary = -1;
+    for (let i = events.length - 1; i >= 0; i--) {
+        if (events[i].type === 'turn/end') {
+            boundary = events[i].seq;
+            break;
+        }
+    }
+    if (boundary < 0)
+        return null;
+    // 最小条数保护：head（首 turn 投影消息 ≥ 1 条）+ 中段 ≥ 1 条 + tail tailKeep 条
+    if (messages.length < tailKeep + 2)
+        return null;
+    // tail 锚：末 tailKeep 条的首条消息 seq——遮蔽不得侵入
+    const tailAnchor = messages[messages.length - tailKeep].seq;
+    const end = Math.min(boundary, tailAnchor - 1);
+    // 起点两形：既有遮蔽 → 紧接上次遮蔽终点（正门对齐律第三形——连续压缩切点，
+    // 不论该位置事件类型）；无遮蔽 → head 保首个完整 turn（首个 turn/end + 1，
+    // 该位置须是 turn/start——正门对齐律第二形；无 turn 骨架的裸消息流诚实跳过）
+    let lastOcclusionEnd = -1;
+    let firstTurnEnd = -1;
+    for (const event of events) {
+        if (event.surfaceOp && event.surfaceOp.end > lastOcclusionEnd)
+            lastOcclusionEnd = event.surfaceOp.end;
+        if (firstTurnEnd < 0 && event.type === 'turn/end')
+            firstTurnEnd = event.seq;
+    }
+    let start;
+    if (lastOcclusionEnd >= 0) {
+        start = lastOcclusionEnd + 1;
+        // 起点撞载体（连续压缩紧邻前指令事件的形态）→ 跳过载体链即止（载体是
+        // 结构指令事件非 turn 体；其后首位即 turn 单元首位——真实 driver 形为随
+        // turn 的 user/message。原「进到下一个 turn/start 对齐位」在真实形会把
+        // user/message 留在区间外拆散其 turn——U4-3 装配批集成勘正）
+        if (events[start]?.surfaceOp) {
+            let next = start;
+            while (next < events.length && events[next].surfaceOp)
+                next++;
+            if (next >= events.length || next > end)
+                return null;
+            start = next;
+        }
+    }
+    else {
+        if (firstTurnEnd < 0)
+            return null; // 防御（boundary ≥ 0 已保证存在——死码注明不删）
+        // 起点对齐 turn 单元边界（05 §2.1 边缘纪律 5）：首 turn/end 后一位即次
+        // turn 单元首位——真实 driver 形该位是随 turn 的 user/message〔提交先落
+        // 消息后起 turn〕、合成形是 turn/start，两者皆完整 turn 单元首位。原
+        // 「该位置须是 turn/start」系合成形状的过强表述，真实日志形下永假（阈值
+        // 路生产从未可规划——U4-3 装配批 e2e 抓获勘正）
+        start = firstTurnEnd + 1;
+    }
+    if (start > end)
+        return null; // 中段空（tail 窗已压到头/仅单闭合 turn）
+    // 防嵌套律的规划面推论：区间须整段避开一切 surfaceOp 载体（载体永不可被遮——
+    // 正门防嵌套校验会拒写）。终点收在起点后最近载体之前（前次摘要载体恰在其前，
+    // 天然并入区间——迭代链承接面）
+    const carrierAbove = events.find((e) => e.seq > start && e.surfaceOp);
+    const effectiveEnd = carrierAbove !== undefined ? Math.min(end, carrierAbove.seq - 1) : end;
+    if (start > effectiveEnd)
+        return null;
+    // 区间内投影消息与字符量（字符尺与 fold.chars 同源：逐消息 JSON 长度和）
+    const result = planFromRange(start, effectiveEnd, messages);
+    if (result.occludedMessages < 1)
+        return null; // 防御：区间内无投影消息（纯骨架区间不值得压）
+    return result;
+}
+/**
+ * 区间 → SegmentPlan（素材三件宿主重算单源——planSegment 尾部与 U4 调整途
+ * 共用：调整案的 occluded/occludedMessages/occludedChars 恒宿主按区间从投影
+ * 重算，不信载荷〔区间主权 = 唯一采用面〕）。区间内投影消息可空——调用方
+ * 自查（planSegment 视为 null、调整途视为非法调整）。
+ */
+export function planFromRange(start, end, messages) {
+    const occluded = messages.filter((m) => m.seq >= start && m.seq <= end);
+    const occludedChars = occluded.reduce((sum, m) => sum + JSON.stringify(m).length, 0);
+    return { start, end, occludedMessages: occluded.length, occludedChars, occluded };
+}
+/* ---------------- 调整值校验（U4 调整途——05 §2.1 槽位化第 3 层） ---------------- */
+/**
+ * 调整值校验器（「调整值过宿主同一规划校验器」的码面单源）：调整案区间须
+ * 落在宿主原案区间内——宿主原案已过规划全律（turn 边界/tail 界/起点对齐/避
+ * 载体），子区间天然合法；扩界不合法（扩 tail/扩进载体区属越权——界桩移动是
+ * 配置槽射程〔tailKeep 等〕非调整途）。
+ */
+export function validateAdjustedRange(adjusted, host) {
+    return adjusted.start >= host.start && adjusted.end <= host.end && adjusted.start <= adjusted.end;
+}
+/* ---------------- 摘要预算（字符制——05 §2.1「摘要参数」） ---------------- */
+/** 摘要目标长度：被遮蔽字符量 × 压缩率，钳在 [min, max] 字符区间 */
+export function summaryBudgetFor(occludedChars, config) {
+    const target = Math.ceil(occludedChars * config.summaryRatio);
+    return Math.min(Math.max(target, config.summaryMinChars), config.summaryMaxChars);
+}
+/* ---------------- 迭代链（05 §2.1「迭代链」段） ---------------- */
+/**
+ * 前次摘要提取：倒扫日志取末条 source='compaction' 的 user/message（其自身
+ * 多已被后续遮蔽——读事件本体而非投影；前次既被遮蔽，其内容唯经并入新摘要
+ * 存活）。剥除载体前缀返回正文；无前次摘要返回 null。
+ */
+export function previousSummaryText(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.type !== 'user/message')
+            continue;
+        const data = event.data;
+        if (data.source !== 'compaction')
+            continue;
+        const text = plainTextOf(data.content);
+        if (text === null || text.length === 0)
+            continue; // 载体形坏（防御）——继续倒扫
+        // 前缀剥除 + CCR 标记段剥离（05 §2.1 压缩可逆性——目录行是机制噪声非
+        // 摘要素材，迭代链提示词只喂摘要正文；批前载体无标记段原样兼容）
+        if (!text.startsWith(SUMMARY_PREFIX))
+            return stripCcrSection(text).trim();
+        return stripCcrSection(text.slice(SUMMARY_PREFIX.length)).trim();
+    }
+    return null;
+}
+/** 内容块面 → 纯文本（string 原样；块数组取 text 块拼接——摘要载体只会有文本） */
+function plainTextOf(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((block) => block.type === 'text' ? String(block.text) : '')
+            .join('');
+    }
+    return null;
+}
+/* ---------------- 摘要提示词（05 §2.1「摘要参数」五段结构） ---------------- */
+/**
+ * 摘要提示词组装：五段结构（任务概述/关键决策/未竟事项/工具与文件痕迹/下一步
+ * 建议）+ 迭代链前次摘要并入 + 目标长度预算行。对话原文以 JSON 透传（complete
+ * 通道对素材自行取舍——投影消息形即对话真身）。
+ */
+export function buildSummaryPrompt(input) {
+    const transcript = JSON.stringify(input.occluded, null, 2);
+    const previous = input.previousSummary
+        ? `\n\n## 前次压缩摘要（迭代链——此前历史已并入其中，本摘要须承接不可丢）\n${input.previousSummary}`
+        : '';
+    return [
+        '请将以下对话压缩为一份上下文摘要，供后续轮次代替被压缩的原文使用。',
+        `目标长度：不超过 ${input.maxChars} 字符。`,
+        `摘要须按五段结构组织：`,
+        '1. 任务概述：用户在做什么、目标是什么；',
+        '2. 关键决策：已确定的技术/方案决策及其理由；',
+        '3. 未竟事项：已开始未完成的工作、待验证的假设；',
+        '4. 工具与文件痕迹：已用工具、已读写的关键文件路径与结果要点；',
+        '5. 下一步建议：紧接着最该做的事。',
+        '只输出摘要正文，不要输出其他说明。' + previous,
+        '',
+        '## 待压缩对话（投影消息 JSON）',
+        transcript,
+    ].join('\n');
+}
+/* ---------------- 冷却判定（防抖三件之一） ---------------- */
+/** 冷却判定：距上次成功压缩不足 cooldownMs → true（抑制触发） */
+export function inCooldown(lastCompactAt, nowMs, config) {
+    return lastCompactAt !== null && nowMs - lastCompactAt < config.cooldownMs;
+}