aws-runtime-bridge 1.9.33 → 1.9.41

package/package/acode/dist/compaction.d.ts

@@ -0,0 +1,242 @@
+/**
+ * 上下文压缩模块 — 参考 OpenCode compaction.ts 的设计
+ *
+ * 核心策略：
+ * 1. Prune（裁剪）：从旧到新遍历工具输出，超过保护线后用占位符替换内容
+ * 2. Summarize（摘要）：将早期对话结构化摘要，保留目标/指令/发现/已完成/相关文件
+ *
+ * 触发时机：在每次 AI 请求前检测 token 是否溢出，溢出则执行压缩
+ *
+ * 与 OpenCode 的对应关系：
+ * - isOverflow  ↔  SessionCompaction.isOverflow
+ * - prune       ↔  SessionCompaction.prune
+ * - summarize   ↔  SessionCompaction.process (LLM 摘要的简化版)
+ */
+/** 压缩缓冲区：保留这么多 token 的空闲空间，避免压缩过程中溢出 */
+export declare const COMPACTION_BUFFER = 20000;
+/**
+ * 基础压缩触发比例（兜底默认值，仅用于 contextLimit <= 0 的异常场景）。
+ * 正常情况下通过 {@link getCompactionTriggerRatio} 按窗口大小动态分级。
+ */
+export declare const COMPACTION_TRIGGER_RATIO = 0.55;
+/** 按上下文窗口大小返回压缩触发比例（大窗口更高，充分利用空间）。 */
+export declare function getCompactionTriggerRatio(contextLimit: number): number;
+/** Prune 保护线默认值：保留最近 PRUNE_PROTECT token 的工具输出完整。
+ *  注意：实际使用时会按 contextLimit 比例调整（见 pruneToolOutputs），
+ *  避免在小上下文窗口（如 60k）下保护线过高导致 prune 永不触发。
+ */
+export declare const PRUNE_PROTECT = 40000;
+/** Prune 最小收益默认值：累计可释放 token 不足此数时跳过修剪。
+ *  注意：实际使用时会按 contextLimit 比例调整。
+ */
+export declare const PRUNE_MINIMUM = 20000;
+/**
+ * LLM 摘要 prompt 模板（OpenCode 风格结构化摘要）。
+ *
+ * 用于 summarizeConversationWithLLM：追加到 user 消息末尾，指导 LLM 按结构化
+ * 段落（Goal/Instructions/Discoveries/Accomplished/Files）输出摘要，便于后续
+ * 轮次快速恢复上下文。LLM 摘要失败时降级到 rule-based summarizeConversation。
+ */
+export declare const COMPACTION_LLM_PROMPT_TEMPLATE: string;
+interface ChatMessageLike {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | unknown[] | null;
+    tool_call_id?: string;
+    tool_calls?: unknown[];
+}
+/** 压缩结果 */
+export interface CompactionResult {
+    /** 使用的策略 */
+    strategy: "prune" | "summarize" | "prune+summarize" | "none";
+    /** 释放的 token 数 */
+    freedTokens: number;
+    /** 压缩前对话大小（KB） */
+    sizeBeforeKB: number;
+    /** 压缩后对话大小（KB） */
+    sizeAfterKB: number;
+    /** 压缩前估算 token 数 */
+    tokensBefore: number;
+    /** 压缩后估算 token 数 */
+    tokensAfter: number;
+    /** 压缩前消息数 */
+    messageCountBefore: number;
+    /** 压缩后消息数 */
+    messageCountAfter: number;
+    /** 被裁剪的工具消息数 */
+    prunedToolMessages: number;
+    /** 被摘要化的消息数 */
+    summarizedMessages: number;
+}
+/**
+ * 压缩阶段事件：由 performCompaction 通过 onPhase 回调发射，
+ * 供 runtime 转换为时间线父子树结构（start → phase* → end）。
+ */
+export interface CompactionPhaseEvent {
+    phase: "prune_start" | "prune_end" | "summarize_start" | "summarize_end";
+    /** 涉及的消息数（prune/summarize 阶段开始时） */
+    messageCount?: number;
+    /** 已裁剪的工具消息数（prune_end） */
+    prunedCount?: number;
+    /** 释放的 token 数（prune_end） */
+    freedTokens?: number;
+    /** 已摘要化的消息数（summarize_end） */
+    summarizedCount?: number;
+    /** 是否使用了 LLM 摘要（summarize_end） */
+    usedLLM?: boolean;
+}
+/**
+ * LLM 摘要器：由 runtime 注入，调用当前 provider 发起一次非流式摘要请求。
+ * 失败时抛出异常，由 summarizeConversation 降级到规则摘要。
+ */
+export type LLMSummarizer = (input: {
+    conversationText: string;
+    messageCount: number;
+    contextLimit: number;
+}) => Promise<string>;
+/**
+ * 计算压缩触发阈值：取 min(contextLimit × 动态比例, hardLimit - reserved)。
+ *
+ * - ratioBased = contextLimit × getCompactionTriggerRatio(contextLimit)（按窗口大小动态分级）
+ * - hardLimit = inputLimit ?? contextLimit（provider 显式 inputLimit 优先）
+ * - reserved = min(COMPACTION_BUFFER, maxOutput)（buffer 不超过输出上限）
+ *
+ * 取两者较小者，既避免小窗口下过早触发，又避免接近硬上限时来不及压缩。
+ */
+export declare function calculateCompactionThreshold(contextLimit: number, maxOutput: number, inputLimit?: number): number;
+/**
+ * 根据模型名查找上下文窗口大小。
+ * 主流程：优先使用传入的 configOverrides → 精确匹配 → 前缀匹配（按长度降序）→ 默认值。
+ *
+ * @param modelName 模型名
+ * @param configOverrides 可选的配置覆盖值（来自 acode.json 的 contextLimit/maxOutput）
+ */
+export declare function lookupModelLimits(modelName: string, configOverrides?: {
+    contextLimit?: number;
+    maxOutput?: number;
+}): {
+    contextLimit: number;
+    maxOutput: number;
+};
+/**
+ * 中英文分离的文本 token 估算。
+ * 对纯 ASCII 约 4 字符/token，对中文约 1.5 字符/token。
+ * 参考：context-manager.ts 的同名方法。
+ */
+export declare function estimateTextTokens(text: string): number;
+/**
+ * 粗略估算文本的 token 数（保留向后兼容）。
+ * 使用 estimateTextTokens 的中英文分离 + 安全填充。
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * 估算整个对话的 token 数。
+ * 使用块级识别 + 中英文分离 + 安全填充。
+ */
+export declare function estimateConversationTokens(messages: readonly ChatMessageLike[]): number;
+/**
+ * 计算对话的 KB 大小。
+ */
+export declare function conversationSizeKB(messages: readonly ChatMessageLike[]): number;
+/**
+ * 判断对话是否上下文溢出（基于文本估算）。
+ * 使用显式传入的 contextLimit 和比例触发，不依赖模型名查找表。
+ *
+ * @param messages 对话消息数组
+ * @param contextLimit 上下文窗口上限
+ * @param maxOutput 模型最大输出 token（未使用，保留参数兼容）
+ */
+export declare function isOverflow(messages: readonly ChatMessageLike[], contextLimit: number, _maxOutput?: number): boolean;
+/**
+ * 基于 provider 实际返回的累积 token 使用量判断是否应触发压缩。
+ *
+ * provider 每次请求都会返回实际 token 计数（input + output），
+ * 这个计数比基于文本的估算（estimateConversationTokens）要准确得多。
+ *
+ * 触发条件：累积 tokens >= contextLimit * getCompactionTriggerRatio(contextLimit)
+ * 使用显式传入的 contextLimit，不依赖模型名查找表。
+ *
+ * @param accumulatedInput  provider 实际累积的 input tokens
+ * @param accumulatedOutput provider 实际累积的 output tokens
+ * @param contextLimit 上下文窗口上限（来自模板配置，未配置时使用默认值）
+ */
+export declare function isOverflowByActualUsage(accumulatedInput: number, accumulatedOutput: number, contextLimit: number): boolean;
+/**
+ * Prune：从消息列表中裁剪旧工具消息的输出内容。
+ *
+ * 算法（参考 OpenCode compaction.ts:58-99）：
+ * 1. 从最新消息往旧遍历
+ * 2. 跳过前 2 轮对话（保护最近上下文）
+ * 3. 累计工具消息的 token
+ * 4. 超过保护线后，将工具输出替换为占位符
+ * 5. 只有收益超过最小阈值才真正执行
+ *
+ * 保护线和最小阈值会按 contextLimit 比例调整：
+ *   - protectLine = min(PRUNE_PROTECT, contextLimit * PRUNE_PROTECT_RATIO)
+ *   - minimumGain = min(PRUNE_MINIMUM, contextLimit * PRUNE_MINIMUM_RATIO)
+ * 这样在小上下文窗口（如 60k）下也能正常触发 prune，
+ * 而不是固定 40k/20k 导致 60k 上下文永远无法 prune。
+ *
+ * @param messages 对话消息数组（会被原地修改）
+ * @param contextLimit 上下文窗口大小，用于按比例调整阈值（默认使用 DEFAULT_CONTEXT_LIMIT）
+ * @returns 裁剪结果
+ */
+export declare function pruneToolOutputs(messages: ChatMessageLike[], contextLimit?: number): {
+    prunedCount: number;
+    freedTokens: number;
+};
+/**
+ * Summarize：将早期对话消息替换为结构化摘要。
+ *
+ * 算法（参考 OpenCode compaction.ts:101-229 的 process 函数）：
+ * 1. 分离 base system 消息和可压缩消息
+ * 2. 保留最近 COMPACTION_RECENT_MESSAGE_COUNT 条消息
+ * 3. 将早期消息生成结构化摘要
+ * 4. 用摘要消息替换早期消息
+ *
+ * @param messages 对话消息数组（会被原地修改）
+ * @returns 摘要化的消息数
+ */
+export declare function summarizeConversation(messages: ChatMessageLike[], options?: {
+    llmSummarizer?: LLMSummarizer;
+    contextLimit?: number;
+}): Promise<number>;
+/**
+ * Snip：删除最旧的一组消息（从第一个非 system 消息到下一个 user 消息之前）。
+ *
+ * 作为压缩的最终手段——当 prune 和 summarize 都无法释放足够空间时使用。
+ * 能确保：
+ *   1. 不删除 system 消息
+ *   2. 删除的组不跨 user 边界（保证一个完整轮次）
+ *   3. 删除后至少保留 1 组非 system 消息
+ *
+ * @param messages 对话消息数组（会被原地修改，通过 splice 删除）
+ * @returns 删除的消息数
+ */
+export declare function snipOldestMessageGroup(messages: ChatMessageLike[]): number;
+/**
+ * 执行完整压缩流程：Prune → 若仍溢出则 Summarize。
+ *
+ * 参考 OpenCode 的两阶段策略：
+ * 1. 先尝试 prune（低成本，只清除旧工具输出）
+ * 2. 若 prune 后仍溢出，执行 summarize（高成本，摘要化早期对话）
+ *
+ * @param messages 对话消息数组（会被原地修改）
+ * @param contextLimit 上下文窗口上限（来自模板配置，未配置时使用默认值）
+ * @param maxOutput 模型最大输出 token
+ * @param options 可选：llmSummarizer（LLM 摘要器，失败降级到规则摘要）、onPhase（阶段事件回调）
+ * @returns 压缩结果
+ */
+export declare function performCompaction(messages: ChatMessageLike[], contextLimit: number, maxOutput?: number, options?: {
+    llmSummarizer?: LLMSummarizer;
+    onPhase?: (event: CompactionPhaseEvent) => void;
+    /**
+     * Provider 实际累积 token 用量（来自 AI 请求返回的 usage）。
+     * 文本估算（estimateConversationTokens）可能低估实际 token 数，
+     * 导致 prune 后 isOverflow 返回 false 而跳过 summarize，最终策略为 "none"。
+     * 传入此值后，post-prune overflow 检测使用 textEstimated 与 actualUsed 的较大值，
+     * 避免因估算偏差导致压缩失效。
+     */
+    actualUsedTokens?: number;
+}): Promise<CompactionResult>;
+export {};
+//# sourceMappingURL=compaction.d.ts.map

package/package/acode/dist/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../src/compaction.ts"],"names":[],"mappings":"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"}