@zooique/memora 0.1.0

package/dist/agent/constants.js

@@ -0,0 +1,67 @@
+/**
+ * Agent 模块常量集合
+ *
+ * 集中管理 agent.ts 与 loop.ts 中的 magic numbers，便于统一调整与审查。
+ * 按模块分两个命名空间，不创建全局 constants（避免垃圾桶反模式）。
+ *
+ * 触发提取的决策记录：A-006（原"暂缓"判断已失效——10 个 magic number 分布在 2 文件，已达提取阈值）。
+ */
+/**
+ * Agent 门面层常量
+ *
+ * 用于 agent.ts 中的并发锁、输入限制、记忆衰减周期等。
+ */
+export const AGENT_CONSTANTS = {
+    /**
+     * chat() 并发锁超时（毫秒）。超时后中断 generator 并释放锁。
+     *
+     * BUG-STREAM-05 修复：原值 300_000（5 分钟）与超时体系不匹配：
+     * - chunk 级读超时 30s（openaiCompatible parseSseStream）
+     * - LLM 请求超时 120s（LLM_TIMEOUT_MS）
+     * - 宿主层无进展兜底 60s（chatHandlers STREAM_NO_PROGRESS_TIMEOUT_MS）
+     * 现调整为 180s（LLM 120s + 60s 缓冲），作为所有超时失败后的最后兜底。
+     */
+    CHAT_LOCK_TIMEOUT_MS: 180_000,
+    /** chat() 输入最大长度（字节）。128KB。 */
+    CHAT_INPUT_MAX_LENGTH: 128 * 1024,
+    /** 记忆衰减执行间隔（毫秒）。1 小时。 */
+    DECAY_INTERVAL_MS: 3_600_000,
+    /** AgentConfig.maxContextTokens 默认值。120K tokens。 */
+    DEFAULT_MAX_CONTEXT_TOKENS: 120_000,
+    /** recallExcludeSources 默认值——永久记忆不参与增量召回。 */
+    DEFAULT_RECALL_EXCLUDE_SOURCES: ['persona', 'rule', 'skill'],
+};
+/**
+ * AgentLoop 引擎层常量
+ *
+ * 用于 loop.ts 中的 token 估算、召回上下文长度、LLM 重试、循环限制等。
+ *
+ * 注意：AgentLoop 构造选项中的默认值（maxIterations ?? 20 等）保留在 loop.ts 原地，
+ * 因为它们是 API 契约的一部分——调用方期望"未传入时使用默认值"。
+ * 这里只提取与 UI/重试/估算相关的纯常量。
+ */
+export const LOOP_CONSTANTS = {
+    /** 粗略 token 估算：每 token 约 3 字符（非精确 tokenizer）。 */
+    CHARS_PER_TOKEN: 3,
+    /** 召回记忆注入到上下文的最大字符数。超出会截断。 */
+    RECALL_CONTEXT_MAX_CHARS: 2000,
+    /** LLM 调用最大重试次数（不含首次调用）。 */
+    MAX_LLM_RETRIES: 2,
+    /** LLM 重试基础延迟（毫秒），指数退避 base。 */
+    RETRY_BASE_DELAY_MS: 1000,
+    /** 单次 LLM 请求超时（毫秒）。120 秒。超时后可重试。 */
+    LLM_TIMEOUT_MS: 120_000,
+    /** 上下文截断时给 LLM 响应预留的缓冲比例。0.9 = 留 10% 给响应。 */
+    CONTEXT_TOKENS_BUFFER_RATIO: 0.9,
+    /** 摘要缓存 TTL：消息数增长超过此值时缓存过期，需重新生成摘要。 */
+    SUMMARY_CACHE_TTL_MSGS: 10,
+    /** 召回记忆内容注入上下文时的截断长度（字符）。 */
+    RECALL_CONTENT_SLICE: 200,
+    /** 上下文摘要：参与摘要的最近消息条数。 */
+    SUMMARY_MSG_COUNT: 6,
+    /** 上下文摘要：单条消息内容截断长度（字符）。 */
+    SUMMARY_CONTENT_SLICE: 200,
+    /** 上下文摘要：LLM 调用 maxTokens 参数。 */
+    SUMMARY_MAX_TOKENS: 150,
+};
+//# sourceMappingURL=constants.js.map

package/dist/agent/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/agent/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B;;;;;;;;OAQG;IACH,oBAAoB,EAAE,OAAO;IAE7B,+BAA+B;IAC/B,qBAAqB,EAAE,GAAG,GAAG,IAAI;IAEjC,yBAAyB;IACzB,iBAAiB,EAAE,SAAS;IAE5B,oDAAoD;IACpD,0BAA0B,EAAE,OAAO;IAEnC,6CAA6C;IAC7C,8BAA8B,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAU;CAC7D,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,iDAAiD;IACjD,eAAe,EAAE,CAAC;IAElB,8BAA8B;IAC9B,wBAAwB,EAAE,IAAI;IAE9B,4BAA4B;IAC5B,eAAe,EAAE,CAAC;IAElB,gCAAgC;IAChC,mBAAmB,EAAE,IAAI;IAEzB,oCAAoC;IACpC,cAAc,EAAE,OAAO;IAEvB,6CAA6C;IAC7C,2BAA2B,EAAE,GAAG;IAEhC,uCAAuC;IACvC,sBAAsB,EAAE,EAAE;IAE1B,6BAA6B;IAC7B,oBAAoB,EAAE,GAAG;IAEzB,yBAAyB;IACzB,iBAAiB,EAAE,CAAC;IAEpB,4BAA4B;IAC5B,qBAAqB,EAAE,GAAG;IAE1B,iCAAiC;IACjC,kBAAkB,EAAE,GAAG;CACf,CAAC"}

package/dist/agent/contextManager.d.ts

@@ -0,0 +1,130 @@
+/**
+ * 上下文窗口管理器（从 AgentLoop 提取的独立职责）
+ *
+ * 职责：
+ *   1. token 估算（estimateTokens）
+ *   2. 消息截断（truncateMessages）—— 保留下方、裁中间、提取关键消息
+ *   3. 关键消息提取（extractKeyMessages）—— 按重要性权重贪心选取
+ *   4. 上下文摘要生成（generateContextSummary）—— LLM 生成"遗忘补偿"
+ *   5. 摘要缓存管理（getOrCreateSummary）—— 缓存 TTL + 过期重生成
+ *
+ * 设计理由（QC-R2-08）：AgentLoop 1151 行超阈值，上下文管理是独立职责，
+ * 拆分后 AgentLoop 聚焦对话循环，ContextManager 聚焦上下文窗口管理。
+ *
+ * 自然生长原则：ContextManager 不持有 messages 引用（避免与 AgentLoop 状态耦合），
+ * 所有方法接收 messages 作为参数，是无状态的纯计算 + 缓存。
+ */
+import type { LlmProvider, Message } from '../llm/provider.js';
+/** ContextManager 构造选项 */
+export interface ContextManagerOptions {
+    /** 上下文窗口 token 上限 */
+    readonly maxContextTokens: number;
+    /** LLM Provider（用于生成上下文摘要） */
+    readonly provider: LlmProvider;
+    /** 截断时生成占位消息的文案函数（来自 UIMessages.contextTruncated） */
+    readonly contextTruncatedFn: (skipped: number, kept: number) => string;
+}
+/**
+ * 上下文窗口管理器
+ *
+ * 管理 token 估算、消息截断、摘要生成与缓存。
+ * 从 AgentLoop 提取，保持无状态设计（不持有 messages 引用）。
+ */
+export declare class ContextManager {
+    /** 上下文窗口 token 上限（readonly，构造时传入） */
+    private readonly maxContextTokens;
+    /** LLM Provider（用于 generateContextSummary） */
+    private readonly provider;
+    /** 截断占位消息文案函数 */
+    private readonly contextTruncatedFn;
+    /** 上下文摘要缓存（首次截断后生成，后续截断复用） */
+    private contextSummary;
+    /** 摘要缓存生成时的消息数量，用于判断缓存是否过期 */
+    private contextSummaryMsgCount;
+    /** 截断次数统计（truncateMessages 实际触发截断 +1，供 getMetrics 读取） */
+    private _truncationCount;
+    constructor(opts: ContextManagerOptions);
+    /** 截断次数（供 AgentLoop.getMetrics 读取） */
+    get truncationCount(): number;
+    /**
+     * 估算消息数组的 token 数
+     *
+     * 粗略估算：总字符数 / CHARS_PER_TOKEN（默认 3）。
+     * toolCalls 的 JSON 序列化字符数也计入。
+     *
+     * @param messages 消息数组
+     * @returns 估算的 token 数
+     */
+    estimateTokens(messages: readonly Message[]): number;
+    /**
+     * 检查是否需要截断（token 超阈值 + 消息数 > 3）
+     *
+     * @param messages 消息数组
+     * @returns 是否需要截断
+     */
+    shouldTruncate(messages: readonly Message[]): boolean;
+    /**
+     * 截断消息数组以适配上下文窗口
+     *
+     * 策略：保留下方、裁中间、提取关键消息。
+     * - messages[0]（system prompt）始终保留（这是 Agent 的"灵魂"）
+     * - 从尾部向前取最近的消息对（user + assistant + tool），直到估算 token 接近上限
+     * - 从被裁剪的消息中按重要性权重提取关键用户消息，插入到 placeholder 之前
+     * - 头部被裁剪的消息替换为一条摘要占位消息
+     *
+     * 重要性权重：user 消息 > tool 结果 > assistant 回复
+     * 被裁剪的用户消息中，内容较长的（信息量大）优先保留
+     *
+     * 如果 system prompt 本身就超过 maxContextTokens，不做截断（让 LLM API 报错，
+     * 开发者需要缩减 bootstrapMemories 或 toolDefinitions）。
+     *
+     * @param messages 完整消息数组
+     * @param summary 可选的上下文摘要（注入到 system prompt 和 placeholder 之间）
+     * @returns 截断后的消息数组（可能是原数组引用，无修改时）
+     */
+    truncateMessages(messages: readonly Message[], summary?: string): readonly Message[];
+    /**
+     * 从被裁剪的消息中按重要性提取关键消息
+     *
+     * 重要性权重：
+     * - user 消息：权重 3（用户输入信息量最高）
+     * - tool 消息：权重 2（工具结果有参考价值）
+     * - assistant 消息：权重 1（助手回复可从上下文推断）
+     *
+     * 贪心选取：按权重降序 + 内容长度降序排列，逐条选取直到 token 用完。
+     * 最终按原始顺序返回（保持时间线一致性）。
+     *
+     * @param cutMessages 被裁剪的消息数组
+     * @param availableTokens 可用 token 数
+     * @returns 提取的关键消息数组（按原始顺序）
+     */
+    private extractKeyMessages;
+    /**
+     * 评估单条消息的重要性权重
+     *
+     * @param msg 消息
+     * @returns 权重值（user=3, tool=2, assistant=1）
+     */
+    private messageImportance;
+    /**
+     * 获取或创建上下文摘要（带缓存管理）
+     *
+     * 缓存 TTL：消息数增长超过 SUMMARY_CACHE_TTL_MSGS 时缓存过期，需重新生成。
+     * 首次调用时生成摘要并缓存，后续调用复用缓存直到过期。
+     *
+     * @param messages 当前消息数组（用于生成摘要和判断缓存过期）
+     * @returns 摘要字符串（失败时返回空字符串，降级为无摘要）
+     */
+    getOrCreateSummary(messages: readonly Message[]): Promise<string>;
+    /**
+     * 生成上下文摘要（enableContextSummary 时调用）
+     *
+     * 在首次截断时，提取即将被裁剪的消息中最近几条用户/助手对话，
+     * 调用 provider 生成一句摘要，作为"遗忘补偿"注入到 system prompt 中。
+     *
+     * @param messages 当前消息数组
+     * @returns 摘要字符串（失败时返回空字符串，降级为无摘要）
+     */
+    private generateContextSummary;
+}
+//# sourceMappingURL=contextManager.d.ts.map

package/dist/agent/contextManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextManager.d.ts","sourceRoot":"","sources":["../../src/agent/contextManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAI9D,0BAA0B;AAC1B,MAAM,WAAW,qBAAqB;IACpC,qBAAqB;IACrB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,qDAAqD;IACrD,QAAQ,CAAC,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACxE;AAED;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,8CAA8C;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,iBAAiB;IACjB,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA4C;IAE/E,8BAA8B;IAC9B,OAAO,CAAC,cAAc,CAAuB;IAC7C,8BAA8B;IAC9B,OAAO,CAAC,sBAAsB,CAAa;IAC3C,yDAAyD;IACzD,OAAO,CAAC,gBAAgB,CAAa;gBAEzB,IAAI,EAAE,qBAAqB;IAMvC,sCAAsC;IACtC,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;;;;;;;OAQG;IACH,cAAc,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM;IAapD;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO;IAIrD;;;;;;;;;;;;;;;;;;OAkBG;IACH,gBAAgB,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE;IA8FpF;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,kBAAkB;IA+B1B;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;;;;;;OAQG;IACG,kBAAkB,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBvE;;;;;;;;OAQG;YACW,sBAAsB;CAoCrC"}

package/dist/agent/contextManager.js

@@ -0,0 +1,287 @@
+/**
+ * 上下文窗口管理器（从 AgentLoop 提取的独立职责）
+ *
+ * 职责：
+ *   1. token 估算（estimateTokens）
+ *   2. 消息截断（truncateMessages）—— 保留下方、裁中间、提取关键消息
+ *   3. 关键消息提取（extractKeyMessages）—— 按重要性权重贪心选取
+ *   4. 上下文摘要生成（generateContextSummary）—— LLM 生成"遗忘补偿"
+ *   5. 摘要缓存管理（getOrCreateSummary）—— 缓存 TTL + 过期重生成
+ *
+ * 设计理由（QC-R2-08）：AgentLoop 1151 行超阈值，上下文管理是独立职责，
+ * 拆分后 AgentLoop 聚焦对话循环，ContextManager 聚焦上下文窗口管理。
+ *
+ * 自然生长原则：ContextManager 不持有 messages 引用（避免与 AgentLoop 状态耦合），
+ * 所有方法接收 messages 作为参数，是无状态的纯计算 + 缓存。
+ */
+import { LOOP_CONSTANTS } from '../agent/constants.js';
+import { logger } from '../logging/logger.js';
+/**
+ * 上下文窗口管理器
+ *
+ * 管理 token 估算、消息截断、摘要生成与缓存。
+ * 从 AgentLoop 提取，保持无状态设计（不持有 messages 引用）。
+ */
+export class ContextManager {
+    /** 上下文窗口 token 上限（readonly，构造时传入） */
+    maxContextTokens;
+    /** LLM Provider（用于 generateContextSummary） */
+    provider;
+    /** 截断占位消息文案函数 */
+    contextTruncatedFn;
+    /** 上下文摘要缓存（首次截断后生成，后续截断复用） */
+    contextSummary = null;
+    /** 摘要缓存生成时的消息数量，用于判断缓存是否过期 */
+    contextSummaryMsgCount = 0;
+    /** 截断次数统计（truncateMessages 实际触发截断 +1，供 getMetrics 读取） */
+    _truncationCount = 0;
+    constructor(opts) {
+        this.maxContextTokens = opts.maxContextTokens;
+        this.provider = opts.provider;
+        this.contextTruncatedFn = opts.contextTruncatedFn;
+    }
+    /** 截断次数（供 AgentLoop.getMetrics 读取） */
+    get truncationCount() {
+        return this._truncationCount;
+    }
+    /**
+     * 估算消息数组的 token 数
+     *
+     * 粗略估算：总字符数 / CHARS_PER_TOKEN（默认 3）。
+     * toolCalls 的 JSON 序列化字符数也计入。
+     *
+     * @param messages 消息数组
+     * @returns 估算的 token 数
+     */
+    estimateTokens(messages) {
+        let totalChars = 0;
+        for (const m of messages) {
+            // 消息本身的内容字符数
+            totalChars += m.content.length;
+            // toolCalls 的 JSON 序列化字符数
+            if (m.toolCalls) {
+                totalChars += JSON.stringify(m.toolCalls).length;
+            }
+        }
+        return Math.ceil(totalChars / LOOP_CONSTANTS.CHARS_PER_TOKEN);
+    }
+    /**
+     * 检查是否需要截断（token 超阈值 + 消息数 > 3）
+     *
+     * @param messages 消息数组
+     * @returns 是否需要截断
+     */
+    shouldTruncate(messages) {
+        return this.estimateTokens(messages) > this.maxContextTokens && messages.length > 3;
+    }
+    /**
+     * 截断消息数组以适配上下文窗口
+     *
+     * 策略：保留下方、裁中间、提取关键消息。
+     * - messages[0]（system prompt）始终保留（这是 Agent 的"灵魂"）
+     * - 从尾部向前取最近的消息对（user + assistant + tool），直到估算 token 接近上限
+     * - 从被裁剪的消息中按重要性权重提取关键用户消息，插入到 placeholder 之前
+     * - 头部被裁剪的消息替换为一条摘要占位消息
+     *
+     * 重要性权重：user 消息 > tool 结果 > assistant 回复
+     * 被裁剪的用户消息中，内容较长的（信息量大）优先保留
+     *
+     * 如果 system prompt 本身就超过 maxContextTokens，不做截断（让 LLM API 报错，
+     * 开发者需要缩减 bootstrapMemories 或 toolDefinitions）。
+     *
+     * @param messages 完整消息数组
+     * @param summary 可选的上下文摘要（注入到 system prompt 和 placeholder 之间）
+     * @returns 截断后的消息数组（可能是原数组引用，无修改时）
+     */
+    truncateMessages(messages, summary) {
+        const estimated = this.estimateTokens(messages);
+        if (estimated <= this.maxContextTokens || messages.length <= 3) {
+            return messages; // 未超阈值，无需截断
+        }
+        // system prompt 单独保留
+        const systemMsg = messages[0];
+        if (!systemMsg || systemMsg.role !== 'system') {
+            return messages; // 异常：没有 system prompt，不截断
+        }
+        const systemTokens = this.estimateTokens([systemMsg]);
+        if (systemTokens >= this.maxContextTokens) {
+            // system prompt 本身就超了——这是配置问题，不应该截断
+            logger.warn({ systemTokens, maxContextTokens: this.maxContextTokens }, 'system prompt 已超过上下文窗口上限，请缩减 bootstrapMemories 或 toolDefinitions');
+            return messages;
+        }
+        // 剩余可用 token 数（留 10% 缓冲给 LLM 响应）
+        const availableTokens = Math.floor(this.maxContextTokens * LOOP_CONSTANTS.CONTEXT_TOKENS_BUFFER_RATIO) - systemTokens;
+        // 从尾部向前收集消息（最近的最重要）
+        const tail = [];
+        let tailTokens = 0;
+        let cutIndex = messages.length; // 被裁剪区域的起始索引
+        for (let i = messages.length - 1; i >= 1; i--) {
+            // QC-17 移除非空断言：循环条件保证索引有效，null 检查兜底
+            const msg = messages[i];
+            if (!msg)
+                break;
+            const msgTokens = this.estimateTokens([msg]);
+            if (tailTokens + msgTokens > availableTokens) {
+                cutIndex = i + 1; // cutIndex 是第一条被保留的尾部消息
+                break; // 再加这条就超了
+            }
+            tail.unshift(msg); // 保持顺序：从尾部取，但插入时保持时间顺序
+            tailTokens += msgTokens;
+            cutIndex = i;
+        }
+        // 计算被裁剪的消息
+        const skipped = cutIndex - 1; // -1 是 system prompt
+        if (skipped <= 0) {
+            return messages; // 全部保留
+        }
+        // 截断次数统计：确实发生了截断（skipped > 0）
+        this._truncationCount++;
+        // 从被裁剪的消息中按重要性提取关键消息
+        // 重要性权重：user > tool > assistant；内容较长的用户消息优先
+        const cutMessages = messages.slice(1, cutIndex);
+        const keyMessages = this.extractKeyMessages(cutMessages, availableTokens - tailTokens);
+        // 构造一条占位消息，让 LLM 知道有历史被裁剪了
+        const placeholder = {
+            role: 'system',
+            content: this.contextTruncatedFn(skipped, tail.length),
+        };
+        const truncated = [systemMsg];
+        // 如果有摘要，插入到 system prompt 和 placeholder 之间
+        if (summary) {
+            truncated.push({ role: 'system', content: summary });
+        }
+        // 插入从被裁剪区域提取的关键消息
+        truncated.push(...keyMessages);
+        truncated.push(placeholder);
+        truncated.push(...tail);
+        const newEstimated = this.estimateTokens(truncated);
+        logger.info({
+            originalCount: messages.length,
+            truncatedCount: truncated.length,
+            skipped,
+            keyExtracted: keyMessages.length,
+            originalTokens: estimated,
+            newTokens: newEstimated,
+        }, '上下文窗口截断完成');
+        return truncated;
+    }
+    /**
+     * 从被裁剪的消息中按重要性提取关键消息
+     *
+     * 重要性权重：
+     * - user 消息：权重 3（用户输入信息量最高）
+     * - tool 消息：权重 2（工具结果有参考价值）
+     * - assistant 消息：权重 1（助手回复可从上下文推断）
+     *
+     * 贪心选取：按权重降序 + 内容长度降序排列，逐条选取直到 token 用完。
+     * 最终按原始顺序返回（保持时间线一致性）。
+     *
+     * @param cutMessages 被裁剪的消息数组
+     * @param availableTokens 可用 token 数
+     * @returns 提取的关键消息数组（按原始顺序）
+     */
+    extractKeyMessages(cutMessages, availableTokens) {
+        if (availableTokens <= 0 || cutMessages.length === 0)
+            return [];
+        // 计算每条消息的权重和 token 数
+        const weighted = cutMessages.map((msg, index) => ({
+            msg,
+            index, // 原始顺序索引
+            weight: this.messageImportance(msg),
+            tokens: this.estimateTokens([msg]),
+        }));
+        // 按权重降序 + 内容长度降序排列
+        weighted.sort((a, b) => {
+            if (b.weight !== a.weight)
+                return b.weight - a.weight;
+            return b.msg.content.length - a.msg.content.length;
+        });
+        // 贪心选取，直到 token 用完
+        const selected = [];
+        let usedTokens = 0;
+        for (const item of weighted) {
+            if (usedTokens + item.tokens > availableTokens)
+                break;
+            selected.push(item);
+            usedTokens += item.tokens;
+        }
+        // 恢复原始顺序（保持时间线一致性）
+        selected.sort((a, b) => a.index - b.index);
+        return selected.map((item) => item.msg);
+    }
+    /**
+     * 评估单条消息的重要性权重
+     *
+     * @param msg 消息
+     * @returns 权重值（user=3, tool=2, assistant=1）
+     */
+    messageImportance(msg) {
+        if (msg.role === 'user')
+            return 3;
+        if (msg.role === 'tool')
+            return 2;
+        return 1;
+    }
+    /**
+     * 获取或创建上下文摘要（带缓存管理）
+     *
+     * 缓存 TTL：消息数增长超过 SUMMARY_CACHE_TTL_MSGS 时缓存过期，需重新生成。
+     * 首次调用时生成摘要并缓存，后续调用复用缓存直到过期。
+     *
+     * @param messages 当前消息数组（用于生成摘要和判断缓存过期）
+     * @returns 摘要字符串（失败时返回空字符串，降级为无摘要）
+     */
+    async getOrCreateSummary(messages) {
+        // 检查缓存是否有效
+        const summaryExpired = this.contextSummary !== null &&
+            messages.length - this.contextSummaryMsgCount > LOOP_CONSTANTS.SUMMARY_CACHE_TTL_MSGS;
+        if (this.contextSummary && !summaryExpired) {
+            return this.contextSummary;
+        }
+        // 生成新摘要
+        const summary = await this.generateContextSummary(messages);
+        this.contextSummary = summary;
+        this.contextSummaryMsgCount = messages.length;
+        return summary;
+    }
+    /**
+     * 生成上下文摘要（enableContextSummary 时调用）
+     *
+     * 在首次截断时，提取即将被裁剪的消息中最近几条用户/助手对话，
+     * 调用 provider 生成一句摘要，作为"遗忘补偿"注入到 system prompt 中。
+     *
+     * @param messages 当前消息数组
+     * @returns 摘要字符串（失败时返回空字符串，降级为无摘要）
+     */
+    async generateContextSummary(messages) {
+        const messagesToSummarize = messages.slice(1);
+        const recentMessages = messagesToSummarize
+            .filter((m) => m.role === 'user' || (m.role === 'assistant' && typeof m.content === 'string'))
+            .slice(-LOOP_CONSTANTS.SUMMARY_MSG_COUNT)
+            .map((m) => `${m.role}: ${typeof m.content === 'string' ? m.content.substring(0, LOOP_CONSTANTS.SUMMARY_CONTENT_SLICE) : '[tool]'}`)
+            .join('\n');
+        if (!recentMessages)
+            return '';
+        try {
+            const stream = this.provider.chat([
+                {
+                    role: 'system',
+                    content: 'Summarize the following conversation excerpt in 1-2 sentences. Focus on key facts, decisions, and user preferences. Be concise.',
+                },
+                { role: 'user', content: recentMessages },
+            ], { maxTokens: LOOP_CONSTANTS.SUMMARY_MAX_TOKENS, temperature: 0 });
+            let summary = '';
+            for await (const chunk of stream) {
+                if (chunk.content)
+                    summary += chunk.content;
+            }
+            logger.info({ summaryLength: summary.length }, '上下文摘要已生成');
+            return `[Context summary of earlier conversation]\n${summary}`;
+        }
+        catch (err) {
+            logger.warn({ err }, '上下文摘要生成失败，降级为无摘要');
+            return '';
+        }
+    }
+}
+//# sourceMappingURL=contextManager.js.map

package/dist/agent/contextManager.js.map

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