@zooique/memora 2.0.3 → 3.0.0

package/dist/agent/constants.js

@@ -6,31 +6,33 @@
  *
  * 10 个 magic number 分布在 2 文件，已达提取阈值，故集中提取。
  */
+// 上下文预算装配后，最近对话注入轮数由预算动态派生（见 budget.ts / contextPreparer.ts），
+// agent 常量层不再持有固定轮数默认。
+// SSOT：召回排除默认值下沉到 utils/recallDefaults（记忆层与 agent 层共享，避免两处定义），
+// 消费方 MemoryAdvisor 直接 import 源头，agent 常量层不 re-export。
 /**
  * Agent 门面层常量
  *
- * 用于 agent.ts 中的并发锁、输入限制、记忆衰减周期等。
+ * 用于 agent.ts 中的并发锁、输入限制、召回/上下文配置等。
  */
 export const AGENT_CONSTANTS = {
     /**
-     * chat() 并发锁超时（毫秒）。超时后中断 generator 并释放锁。
-     *
-     * 取 180s（LLM 120s + 60s 缓冲），与超时体系匹配，作为所有超时失败后的最后兜底：
-     * - chunk 级读超时 30s（openaiCompatible parseSseStream）
-     * - LLM 请求超时 120s（LLM_TIMEOUT_MS）
-     * - 宿主层无进展兜底 60s（chatHandlers STREAM_NO_PROGRESS_TIMEOUT_MS）
+     * chat() 并发锁超时。锁超时后仅自动释放锁（放行新对话），不中断生成流——
+     * LLM 无进展由 provider 层兜底（请求级 120s + SSE 事件停滞 120s），锁不对整次对话时长设上限。
      */
     CHAT_LOCK_TIMEOUT_MS: 180_000,
     /** close() 关闭时等待归档完成的超时（毫秒）。 */
     SHUTDOWN_ARCHIVE_TIMEOUT_MS: 5_000,
     /** chat() 输入最大长度（字节）。128KB。 */
     CHAT_INPUT_MAX_LENGTH: 128 * 1024,
-    /** 记忆衰减执行间隔（毫秒）。1 小时。 */
-    DECAY_INTERVAL_MS: 3_600_000,
-    /** AgentConfig.maxContextTokens 默认值。120K tokens。 */
+    /**
+     * AgentConfig.maxContextTokens 默认值。120K tokens。
+     * ⚠️ **本键为真源**；镜像一处须同步 = `src/config/loader.ts` 的 `DEFAULT_MAX_CONTEXT_TOKENS`
+     * （同语义同值：配置层默认窗口，分层不可 import，按本仓既有做法「重复 + 注释对冲」）。
+     * 注意：`strategyKeys.MIN_CONTEXT_LIMIT` **不是镜像**——它是角色包 contextLimit 的声明
+     * 下限语义（正数声明不得低于默认窗口，「收紧」无意义），取值依赖本键但不得随本键联动改。
+     */
     DEFAULT_MAX_CONTEXT_TOKENS: 120_000,
-    /** recallExcludeSources 默认值——永久记忆不参与增量召回。 */
-    DEFAULT_RECALL_EXCLUDE_SOURCES: ['persona', 'rule', 'skill'],
     /**
      * systemPrompt 时间注入的默认 locale（对齐"核心库领域无关"原则，可被 AssembleInput.locale 覆盖）。
      * 默认 'zh-CN' 是项目母语，宿主可注入其他 locale 实现国际化。
@@ -38,17 +40,29 @@ export const AGENT_CONSTANTS = {
     DEFAULT_LOCALE: 'zh-CN',
     /** 召回记忆数量上限。5 条记忆兼顾上下文窗口与召回质量。 */
     DEFAULT_RECALL_LIMIT: 5,
-    /** 最近对话历史注入轮数。3 轮（3 条 user + 3 条 assistant）。 */
-    DEFAULT_RECENT_HISTORY_ROUNDS: 3,
+    /** 暂停超时阈值（毫秒）。30 分钟内无心跳则视为超时，自动归档清理。 */
+    PAUSE_TIMEOUT_MS: 30 * 60 * 1000,
+    /**
+     * 孤儿 Round 垃圾回收周期（毫秒）。
+     * 每天执行一次：清理 refCount=0 且超龄的孤立问答闭环（崩溃残留 pending / 已删会话遗留）。
+     */
+    GC_INTERVAL_MS: 24 * 60 * 60 * 1000,
+    // ─── completedToolCalls FIFO 封顶 ─────────────────
+    //
+    // 工具执行日志无上限时，检查点内存快照开销随会话寿命线性增长。
+    // 48 条 ≈ 多回合工具调用上限，远超单回合调用量。
+    // 截断策略：优先丢弃幂等工具的最早记录，非幂等永不丢弃。
+    COMPLETED_TOOL_CALLS_MAX: 48,
 };
 /**
  * AgentLoop 引擎层常量
  *
  * 用于 loop.ts 中的 token 估算、召回上下文长度、LLM 重试、循环限制等。
  *
- * 注意：AgentLoop 构造选项中的默认值（maxIterations ?? 20 等）保留在 loop.ts 原地，
- * 因为它们是 API 契约的一部分——调用方期望"未传入时使用默认值"。
- * 这里只提取与 UI/重试/估算相关的纯常量。
+ * 注意：AgentLoop 构造选项中的默认值（maxIterations 兜底 DEFAULT_MAX_ITERATIONS 等）定义在
+ * role-pack/strategyKeys.ts——这是角色包策略边界层的常量，agent→role-pack 单向依赖引用。
+ * loop.ts runIterationLoop 入口动态计算 effectiveMax：角色包 stepBudget > 0 则覆盖，
+ * 否则用 maxIterations 兜底。角色包配多少给多少，内核不 clamp。
  */
 export const LOOP_CONSTANTS = {
     /**
@@ -76,17 +90,135 @@ export const LOOP_CONSTANTS = {
     RETRY_BASE_DELAY_MS: 1000,
     /** 单次 LLM 请求超时（毫秒）。120 秒。超时后可重试。 */
     LLM_TIMEOUT_MS: 120_000,
-    /** 上下文截断时给 LLM 响应预留的缓冲比例。0.9 = 留 10% 给响应。 */
+    /**
+     * 上下文截断时保留的窗口比例（**保留系数**：乘 `maxContextTokens` 得目标上限）。0.9 = 留 10% 缓冲。
+     *
+     * ⚠️ 与 `budget.ts` 的 `DEFAULT_OUTPUT_RESERVE_RATIO = 0.15` **不可直接比较**——两者基准不同、
+     * 语法相反（同属「给模型回答的预留」，但阶段与依据均不同）：
+     *   · 本常量（**截断线**）：`ContextManager.truncateMessages` 触发于 `token > maxContextTokens`，
+     *     把 payload 压到 `maxContextTokens × 0.9`。基准 = **窗口总量**；语义 = **保留 90%**（乘法）。
+     *   · `DEFAULT_OUTPUT_RESERVE_RATIO`（**装配线**）：`computeContextBudget` 的
+     *     `可用 = 窗口 × (1 − 0.15) − 固定开销`。基准 = **窗口总量**；语义 = **预留 15%**（减法）。
+     * 二者恰好互余（0.9 保留 ↔ 0.15 预留）纯属巧合，勿据此推导关联或试图统一。
+     */
     CONTEXT_TOKENS_BUFFER_RATIO: 0.9,
+    /**
+     * 软上限检测：摘要层 token 占容量阈值比例。
+     *
+     * 当摘要层（含 Round summary / Compressed context 标记的消息）token 占用
+     * 超过 maxContextTokens × SUMMARY_LAYER_TOKEN_RATIO 时，判定为"摘要层达容量上限"，
+     * 触发软上限收尾信号让 LLM 收敛。
+     *
+     * 0.3 = 摘要层占 30% 容量即触发，配合 CONTEXT_TOKENS_BUFFER_RATIO=0.9
+     * 使用：总上下文逼近上限 + 摘要层占比过高 → 注入软上限。
+     */
+    SUMMARY_LAYER_TOKEN_RATIO: 0.3,
+    /**
+     * 单条工具结果进入上下文的最大 token 数（≈ 上下文窗口的 5%）。6,000。
+     *
+     * **同源红线（一个键，三处引用，且只按 token 判定）**：
+     *   · **不变量**：任何进入上下文的单条 tool 消息（**含 `wrapToolResult` 包裹**）≤ 本键；
+     *   · `read_file` 分段预算 = 本键 − `TOOL_RESULT_WRAP_OVERHEAD_TOKENS`（生产者侧扣包裹开销）；
+     *   · 入口关落盘判据 = `estimateTokensText(content) > 本键`（`loop.appendToolMessage`，
+     *     content 即 wrapped 后待入上下文的内容）。
+     * 判据是**严格大于**，而 `read_file` 产出（含包裹）恒 ≤ 本键 → `read_file` **结构性不落盘**，
+     * 回取 offload 产物时不会再次落盘 → **无限嵌套不可能**。若本键被调到低于 read_file 产出口径、
+     * 或 read_file 预算不再扣包裹余量，读回产物即再次超阈 → 再落盘 → 拿到新路径 → 循环；
+     * `ToolResultCache` 拦不住这种嵌套（产物文件名含时间戳与随机串，每次去重 key 都不同）。
+     *
+     * ⚠️ 故本键**不可**改写成「24,000 字符」这类字符数限额 —— 同一字符数在中英文下 token 数
+     * 相差近 2 倍（CJK `CJK_CHARS_PER_TOKEN=1.5` vs 其他 `CHARS_PER_TOKEN=3`），按字符限额必然
+     * 让其中一侧实际越界。字符只是 token 的估算输入，不是限额本身。
+     */
+    SINGLE_TOOL_RESULT_MAX_TOKENS: 6_000,
+    /**
+     * `wrapToolResult` 包裹模板的 token 开销预留（含工具名）。
+     *
+     * `read_file` 的分段预算 = `SINGLE_TOOL_RESULT_MAX_TOKENS` − 本键，使**含包裹**的输出仍 ≤ 单条上限
+     * （不变量在生产者侧成立）。实测模板固定开销 ≈30 tokens（两行 ASCII 标签 + 一句 26 字中文提示）
+     * + 工具名（≤ 十余字符），100 已宽裕覆盖超长自定义工具名。
+     *
+     * ⚠️ 扣除方向不可反：若 `read_file` 直接以 `SINGLE_TOOL_RESULT_MAX_TOKENS` 作预算，其 wrapped 输出
+     * 会超出单条上限 → 被入口关落盘 → LLM 每次读文件只看得到路径（荒谬行为，且无测试会红）。
+     */
+    TOOL_RESULT_WRAP_OVERHEAD_TOKENS: 100,
+    /**
+     * `search_memories` 工具响应性护栏：整次关键词搜索的上限。
+     *
+     * 背景：搜索服务为网络调用（web/project search）时以 30s 超时为先例（webSearchProvider.ts），
+     * 本地记忆搜索更快，故收窄为 5s——超时降级为提示文案而非挂死工具。
+     */
+    MEMORY_SEARCH_TIMEOUT_MS: 5_000,
+    /**
+     * 情报区（LLM 私有工作笔记，大文本统一通道）字符数上限。
+     *
+     * LLM 经 `remember_intel` 自写的私有笔记累积；超限裁最旧（保留最新）。这是**数据上限**
+     * （防单 turn 内多次写入把笔记撑爆），**不是预算维度** —— 情报区仍作为尾部 system 消息
+     * 参与现有 `truncateMessages` 窗口淘汰（锚点 C：不新增第 5 个预算维度）。
+     */
+    MAX_INTEL_PREFIX_LEN: 4_000,
     /** 摘要缓存 TTL：消息数增长超过此值时缓存过期，需重新生成摘要。 */
     SUMMARY_CACHE_TTL_MSGS: 10,
-    /** 召回记忆内容注入上下文时的截断长度（字符）。 */
-    RECALL_CONTENT_SLICE: 200,
+    /** 流式中断的默认追加标记（SSOT）：含断点摘要，让 LLM 明确"以上已输出，请继续不重复"。
+     * loop（流式响应中断）与 orchestrator（历史写入中断标记）必须用同一份默认文案，
+     * 避免宿主未注入 messages 时两条路径降级出不同文案（另一路径为短 "[已中断]"）。
+     */
+    DEFAULT_INTERRUPTED_MARK: '\n\n[已中断]\n\n[断点摘要：以上内容已输出到 LLM，请在此基础上继续回答，不要重复已输出的内容]',
+    /** 达到最大迭代/步数预算的默认追加标记（SSOT）：loop 的撞线收尾文案默认值，
+     *  宿主可经 messages.maxIterationsReached 覆盖（与 DEFAULT_INTERRUPTED_MARK 同族文案）。 */
+    DEFAULT_MAX_ITERATIONS_REACHED_MARK: '\n\n[Max iterations reached]',
+    /**
+     * 上下文预算预警提示：容量逼近警戒线但摘要层未饱和时注入的温和提示，
+     * 引导 LLM 主动压缩 / 收敛——软上限（收尾信号）的前一级。低压通用文案不走 UIMessages 覆盖层，
+     * 如需宿主定制可后续升级（与 softLimitWrapup 同族，但非高频行为文案）。
+     */
+    CONTEXT_PRESSURE_HINT: '## 上下文空间提示\n' +
+        '当前上下文已接近容量上限。若后续步骤需要更多空间，可调用 compress_context 压缩较早 turn' +
+        '或超大工具结果；同时注意收敛回答篇幅，避免无谓展开。',
+    /**
+     * 搜索收敛护栏（实测：LLM 连续成功联网搜索 10+ 次不收敛，Bing 结果泛泛仍反复搜）。
+     * 单 turn（问答闭环）内成功 web_search 次数达到此阈值后，注入收敛提示引导 LLM 停止搜索直接作答。
+     * 计入成功（ok=true）与连续轮次无关——一次工具步内并行多个搜索按多次计。
+     */
+    SEARCH_CONVERGENCE_THRESHOLD: 2,
+    /** 搜索收敛提示（executionTemp 幂等：一轮内仅注入一次，下一闭环入口即弃） */
+    SEARCH_CONVERGENCE_HINT: '## 搜索收敛提示\n' +
+        '你已成功执行多次联网搜索并获取了可用信息。若现有信息已足够支撑回答，请停止继续搜索，' +
+        '直接基于已有信息作答；仅当存在明确信息缺口（如用户指定查询的最新数据确实缺失）时才继续搜索。',
+    /**
+     * 搜索硬上限（实测软提示未能阻止 LLM 持续重搜，故确定性拒绝）。
+     * 单 turn（问答闭环）内 web_search 调用次数超过此数后，后续搜索执行时直接拒绝并回填拒绝文案，
+     * 不依赖 LLM 听从软提示——软提示引导收敛（< 上限时），硬限兜底（达到上限强制停）。
+     */
+    MAX_WEB_SEARCH_CALLS: 6,
+    /**
+     * 工具调用导语纪律（分区式 UI 配套）：正文只承载最终交付，工具步的过程叙述
+     * 由内核 narrate 事件投影进过程区。约束模型在调用工具前不输出长段规划——长导语若发生在
+     * 首轮工具步（消息级分类前）会逐字混入正文，压到一句话可把残余影响降至可忽略。
+     * 随「可用工具」节一起注入，无工具定义时（纯对话角色）不出现。
+     */
+    TOOL_NARRATION_DISCIPLINE: '## 协作规范\n' +
+        '- 调用工具前若要说明意图，最多一句话（例如「先检索相关资料」）；不要在调用工具前输出长篇规划或过程叙述。\n' +
+        '- 工具执行完毕后，基于全部结果输出最终回答；完整的分析、解释与结论只在最终回答中展开。',
     /** 上下文摘要：参与摘要的最近消息条数。 */
     SUMMARY_MSG_COUNT: 6,
     /** 上下文摘要：单条消息内容截断长度（字符）。 */
     SUMMARY_CONTENT_SLICE: 200,
     /** 上下文摘要：LLM 调用 maxTokens 参数。 */
     SUMMARY_MAX_TOKENS: 150,
+    /**
+     * 任务分类启发式：用户消息超过此长度（字符）判定为 'reasoning'。
+     *
+     * 原 loop.determineTaskType 内的魔法数 500 归入内核常数。
+     * 注意这是内核启发式阈值，不属于角色包可影响的 L2 策略维度——任务类型分类是
+     * Provider 路由（影响成本）的内部决策，不开放给角色包配置（避免"策略全景物化"）。
+     */
+    REASONING_INPUT_CHARS: 500,
+    /**
+     * 任务分类检测窗口：determineTaskType 从后向前取最近 N 条 user 消息做代码块检测，
+     * 避免多轮对话中"含代码的请求不在最后一条"被误判为 simple（错配 Provider 成本失真）。
+     * 长文本（reasoning）判定仍以最近一条 user 消息为准（反映当前轮意图）。
+     */
+    TASK_TYPE_WINDOW: 3,
 };
 //# sourceMappingURL=constants.js.map

package/dist/agent/constants.js.map

@@ -1 +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;;;;;;;OAOG;IACH,oBAAoB,EAAE,OAAO;IAE7B,gCAAgC;IAChC,2BAA2B,EAAE,KAAK;IAElC,+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;IAErE;;;OAGG;IACH,cAAc,EAAE,OAAO;IAEvB,kCAAkC;IAClC,oBAAoB,EAAE,CAAC;IAEvB,gDAAgD;IAChD,6BAA6B,EAAE,CAAC;CACxB,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B;;;;;OAKG;IACH,eAAe,EAAE,CAAC;IAElB;;;;;;;;;;OAUG;IACH,mBAAmB,EAAE,GAAG;IAExB,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"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/agent/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,8DAA8D;AAC9D,uBAAuB;AACvB,+DAA+D;AAC/D,uDAAuD;AAEvD;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B;;;OAGG;IACH,oBAAoB,EAAE,OAAO;IAE7B,gCAAgC;IAChC,2BAA2B,EAAE,KAAK;IAElC,+BAA+B;IAC/B,qBAAqB,EAAE,GAAG,GAAG,IAAI;IAEjC;;;;;;OAMG;IACH,0BAA0B,EAAE,OAAO;IAEnC;;;OAGG;IACH,cAAc,EAAE,OAAO;IAEvB,kCAAkC;IAClC,oBAAoB,EAAE,CAAC;IAEvB,wCAAwC;IACxC,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI;IAEhC;;;OAGG;IACH,cAAc,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI;IAEnC,mDAAmD;IACnD,EAAE;IACF,iCAAiC;IACjC,6BAA6B;IAC7B,8BAA8B;IAC9B,wBAAwB,EAAE,EAAE;CACpB,CAAC;AAEX;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B;;;;;OAKG;IACH,eAAe,EAAE,CAAC;IAElB;;;;;;;;;;OAUG;IACH,mBAAmB,EAAE,GAAG;IAExB,4BAA4B;IAC5B,eAAe,EAAE,CAAC;IAElB,gCAAgC;IAChC,mBAAmB,EAAE,IAAI;IAEzB,oCAAoC;IACpC,cAAc,EAAE,OAAO;IAEvB;;;;;;;;;;OAUG;IACH,2BAA2B,EAAE,GAAG;IAEhC;;;;;;;;;OASG;IACH,yBAAyB,EAAE,GAAG;IAE9B;;;;;;;;;;;;;;;;OAgBG;IACH,6BAA6B,EAAE,KAAK;IAEpC;;;;;;;;;OASG;IACH,gCAAgC,EAAE,GAAG;IAErC;;;;;OAKG;IACH,wBAAwB,EAAE,KAAK;IAE/B;;;;;;OAMG;IACH,oBAAoB,EAAE,KAAK;IAE3B,uCAAuC;IACvC,sBAAsB,EAAE,EAAE;IAE1B;;;OAGG;IACH,wBAAwB,EACtB,wDAAwD;IAE1D;kFAC8E;IAC9E,mCAAmC,EAAE,8BAA8B;IAEnE;;;;OAIG;IACH,qBAAqB,EACnB,cAAc;QACd,yDAAyD;QACzD,4BAA4B;IAE9B;;;;OAIG;IACH,4BAA4B,EAAE,CAAC;IAE/B,iDAAiD;IACjD,uBAAuB,EACrB,aAAa;QACb,4CAA4C;QAC5C,gDAAgD;IAElD;;;;OAIG;IACH,oBAAoB,EAAE,CAAC;IAEvB;;;;;OAKG;IACH,yBAAyB,EACvB,WAAW;QACX,yDAAyD;QACzD,8CAA8C;IAEhD,yBAAyB;IACzB,iBAAiB,EAAE,CAAC;IAEpB,4BAA4B;IAC5B,qBAAqB,EAAE,GAAG;IAE1B,iCAAiC;IACjC,kBAAkB,EAAE,GAAG;IAEvB;;;;;;OAMG;IACH,qBAAqB,EAAE,GAAG;IAE1B;;;;OAIG;IACH,gBAAgB,EAAE,CAAC;CACX,CAAC"}

package/dist/agent/contextManager.d.ts

@@ -7,6 +7,8 @@
  *   3. 关键消息提取（extractKeyMessages）—— 按重要性权重贪心选取
  *   4. 上下文摘要生成（generateContextSummary）—— LLM 生成"遗忘补偿"
  *   5. 摘要缓存管理（getOrCreateSummary）—— 缓存 TTL + 过期重生成
+ *   6. 软上限判定（shouldInjectSoftLimitWrapup）—— 摘要层饱和注入收尾信号（自 AgentLoop 迁入）
+ *   7. 压力预警（shouldInjectContextPressureHint）—— 容量到线但摘要健康的前一级提示
  *
  * 设计理由：AgentLoop 1151 行超阈值，上下文管理是独立职责，
  * 拆分后 AgentLoop 聚焦对话循环，ContextManager 聚焦上下文窗口管理。
@@ -15,13 +17,25 @@
  * 所有方法接收 messages 作为参数，是无状态的纯计算 + 缓存。
  */
 import type { LlmProvider, Message } from '../llm/provider.js';
+import type { ProviderRouter } from '../llm/types.js';
 import { type ITracer } from '../agent/tracer.js';
+/** 软上限摘要化判定标记：第一级替换产物文案前缀（compaction.ts ReplaceRoundsStrategy） */
+export declare const SOFT_LIMIT_SUMMARY_MARKER_ROUND = "Round summary \u00B7 roundId:";
+/** 软上限摘要化判定标记：第二级压缩产物文案前缀（loop.compressContext） */
+export declare const SOFT_LIMIT_SUMMARY_MARKER_COMPRESS = "Compressed context";
 /** ContextManager 构造选项（模块私有，0 外部 import） */
 interface ContextManagerOptions {
     /** 上下文窗口 token 上限 */
     readonly maxContextTokens: number;
     /** LLM Provider（用于生成上下文摘要） */
     readonly provider: LlmProvider;
+    /**
+     * Provider 路由选择器（多模型路由基础，可选）
+     *
+     * 有配置时，摘要生成走 'summary' 路由，使用轻量模型。
+     * 不配置时回退到主 Provider（完全向后兼容）。
+     */
+    readonly providerRouter?: ProviderRouter;
     /** 截断时生成占位消息的文案函数（来自 UIMessages.contextTruncated） */
     readonly contextTruncatedFn: (skipped: number, kept: number) => string;
     /**
@@ -36,7 +50,50 @@ interface ContextManagerOptions {
      * 未注入时静默忽略。宿主可通过此回调向用户通知上下文被截断。
      */
     readonly onContextTruncated?: (skippedCount: number, keptCount: number) => void;
+    /**
+     * 已存轮次摘要加载器（截断优先复用，可选）
+     *
+     * 截断生成上下文摘要前，先尝试取已持久化的 round-summary（零成本、保真），
+     * 仅当没有已存摘要时才现调 LLM——让摘要生成退出截断关键路径。
+     * 返回空字符串/undefined 表示无已存摘要，回退 LLM 生成。
+     */
+    readonly roundSummaryLoader?: () => string;
+    /**
+     * 最少保留的最近原始对话轮数（可选，默认 0）
+     *
+     * 截断时强制保留最近 N 轮完整原始对话（不被摘要替代），在此基础上再按 token 上限收集。
+     * 宿主可据 provider 的 prompt caching（KV cache 复用）能力放宽此值——多塞原始对话几乎
+     * 零成本且保真。0 表示不强制（保持纯 token 驱动截断）。
+     */
+    readonly minRecentRounds?: number;
+}
+/** 可估算 token 的最小消息形状（宿主历史会话重算无需构造完整内核 Message） */
+export interface EstimableMessage {
+    readonly content: string;
+    readonly toolCalls?: unknown;
 }
+/**
+ * 估算消息序列 token 数（CJK 感知，零状态纯函数）。
+ *
+ * 单一真理源：先累计全部字符、最后一次向上取整——与逐条取整再求和**不等价**
+ * （后者系统性高估）。运行时（`ContextManager.estimateTokens` / contextPreparer
+ * 各层计量）与宿主历史会话占用重算共用本函数，两端口径不漂移。
+ *
+ * @param messages 待估算的消息序列（content 计入，toolCalls 序列化后计入）
+ * @returns token 数（按 CJK/其他字符分轨估算后向上取整）
+ */
+export declare function estimateTokensMessages(messages: readonly EstimableMessage[]): number;
+/**
+ * 估算单段文本 token 数（CJK 感知，零状态纯函数）。
+ *
+ * 供「单段文本」场景使用（如宿主对一条记忆正文的独立计量）。
+ * 计量**消息序列**须用 `estimateTokensMessages`：本函数逐条调用再求和会放大
+ * 取整误差，与本函数同口径但结果不等价。
+ *
+ * @param text 待估算文本
+ * @returns token 数（按 CJK/其他字符分轨估算后向上取整）
+ */
+export declare function estimateTokensText(text: string): number;
 /**
  * 上下文窗口管理器
  *
@@ -44,119 +101,104 @@ interface ContextManagerOptions {
  * 从 AgentLoop 提取，保持无状态设计（不持有 messages 引用）。
  */
 export declare class ContextManager {
-    /** 上下文窗口 token 上限（readonly，构造时传入） */
-    private readonly maxContextTokens;
-    /** LLM Provider（用于 generateContextSummary） */
+    private maxContextTokens;
     private readonly provider;
-    /** 截断占位消息文案函数 */
+    private readonly providerRouter;
     private readonly contextTruncatedFn;
-    /** 可观测性 Tracer（用于 generateContextSummary span 埋点，默认 NOOP） */
     private readonly tracer;
-    /** 上下文摘要缓存（首次截断后生成，后续截断复用） */
     private contextSummary;
-    /** 摘要缓存生成时的消息数量，用于判断缓存是否过期 */
     private contextSummaryMsgCount;
-    /** 截断次数统计（truncateMessages 实际触发截断 +1，供 getMetrics 读取） */
     private _truncationCount;
-    /** 截断事件回调（宿主可注入以通知用户） */
     private readonly onContextTruncated;
+    private readonly roundSummaryLoader;
+    private readonly minRecentRounds;
     constructor(opts: ContextManagerOptions);
-    /** 截断次数（供 AgentLoop.getMetrics 读取） */
-    get truncationCount(): number;
     /**
-     * 估算消息数组的 token 数（CJK 中文适配）
+     * 运行时更新上下文窗口上限（token）
      *
-     * 区分 CJK 与非 CJK 字符分别估算：
-     *   - CJK 字符（中文/日文/韩文）：cjkChars / CJK_CHARS_PER_TOKEN（1.5）
-     *   - 非 CJK 字符（英文/数字/符号）：otherChars / CHARS_PER_TOKEN（3）
-     * 统一字符估算会严重低估中文（4 字符 ≈ 1.3 token，实际约 4-8 token）。
+     * 截断判定 / 软上限 / 召回注入警戒线均内读本字段，更新即刻生效。
      *
-     * toolCalls 的 JSON 序列化字符数也计入（同样区分 CJK/非 CJK）。
-     *
-     * @param messages 消息数组
-     * @returns 估算的 token 数
+     * @param tokens 新窗口 token 数
      */
-    estimateTokens(messages: readonly Message[]): number;
+    setMaxContextTokens(tokens: number): void;
+    get truncationCount(): number;
     /**
-     * 检查是否需要截断（token 超阈值 + 消息数 > 3）
+     * 估算消息 token 数。
      *
-     * @param messages 消息数组
-     * @returns 是否需要截断
+     * CJK（中/日/韩）与其它字符密度不同需分开估算：
+     * 统一按 3 字符/token 会严重低估中文（实际约 1.5 字符/token）。
+     * toolCalls 序列化字符同样计入。
      */
+    estimateTokens(messages: readonly Message[]): number;
+    /** token 超阈值且消息数 > 3（避免单条消息触发截断）时才需要截断 */
     shouldTruncate(messages: readonly Message[]): boolean;
     /**
-     * 截断消息数组以适配上下文窗口
-     *
-     * 策略：保留下方、裁中间、提取关键消息。
-     * - messages[0]（system prompt）始终保留（这是 Agent 的"灵魂"）
-     * - 从尾部向前取最近的消息对（user + assistant + tool），直到估算 token 接近上限
-     * - 从被裁剪的消息中按重要性权重提取关键用户消息，插入到 placeholder 之前
-     * - 头部被裁剪的消息替换为一条摘要占位消息
+     * 软上限判定：上下文逼近容量上限（≥ 缓冲阈值）且摘要层 token 占比过高时，注入收尾信号让 LLM 收敛。
+     * 从 AgentLoop._shouldInjectSoftLimitWrapup 迁入（与 estimateTokens/maxContextTokens 同属上下文预算层）。
      *
-     * 重要性权重：user 消息 > tool 结果 > assistant 回复
-     * 被裁剪的用户消息中，内容较长的（信息量大）优先保留
+     * 精确检测摘要层 token 占用（替代原"存在标记即触发"的近似判断）：
+     *   - 过滤出标记为摘要的消息（Round summary / Compressed context）
+     *   - 计算摘要层 token 占用
+     *   - 当摘要层 token ≥ maxContextTokens × SUMMARY_LAYER_TOKEN_RATIO 时判定为"摘要层达容量上限"
      *
-     * 如果 system prompt 本身就超过 maxContextTokens，不做截断（让 LLM API 报错，
-     * 开发者需要缩减 bootstrapMemories 或 toolDefinitions）。
-     *
-     * @param messages 完整消息数组
-     * @param summary 可选的上下文摘要（注入到 system prompt 和 placeholder 之间）
-     * @returns 截断后的消息数组（可能是原数组引用，无修改时）
+     * @param messages 当前工作记忆（读型判定，不修改）
+     * @returns 是否应注入软上限收尾信号
      */
-    truncateMessages(messages: readonly Message[], summary?: string): readonly Message[];
+    shouldInjectSoftLimitWrapup(messages: readonly Message[]): boolean;
     /**
-     * 从被裁剪的消息中按重要性提取关键消息
+     * 上下文压力预警判定：容量表达警戒线（≥ CONTEXT_TOKENS_BUFFER_RATIO）但
+     * 摘要层未饱和（低于 SUMMARY_LAYER_TOKEN_RATIO）时 → 可注入温和提示（压缩/收敛引导）。
      *
-     * 重要性权重：
-     * - user 消息：权重 3（用户输入信息量最高）
-     * - tool 消息：权重 2（工具结果有参考价值）
-     * - assistant 消息：权重 1（助手回复可从上下文推断）
+     * 与 shouldInjectSoftLimitWrapup 互补——同一容量闸的两级：
+     *   摘要层饱和       → shouldInjectSoftLimitWrapup（收尾信号）
+     *   容量到线但摘要健康 → shouldInjectContextPressureHint（软上限的前一级预警）
      *
-     * 贪心选取：按权重降序 + 内容长度降序排列，逐条选取直到 token 用完。
-     * 最终按原始顺序返回（保持时间线一致性）。
-     *
-     * @param cutMessages 被裁剪的消息数组
-     * @param availableTokens 可用 token 数
-     * @returns 提取的关键消息数组（按原始顺序）
+     * @param messages 当前工作记忆（读型判定，不修改）
+     * @returns 是否应注入上下文空间预警提示
      */
-    private extractKeyMessages;
+    shouldInjectContextPressureHint(messages: readonly Message[]): boolean;
     /**
-     * 评估单条消息的重要性权重
+     * 截断消息数组以适配上下文窗口。
      *
-     * @param msg 消息
-     * @returns 权重值（user=3, tool=2, assistant=1）
+     * 策略：保留下方（最近）、裁中间、头部折叠成占位消息。
+     * - messages[0]（system prompt）始终保留；
+     * - 从被裁剪段按重要性（user > tool > assistant）提取关键消息；
+     * - 若 system prompt 本身已超窗口则不截断（配置问题，交由 LLM API 报错）。
      */
+    truncateMessages(messages: readonly Message[], summary?: string): readonly Message[];
+    /**
+     * 从被裁剪段按重要性贪心选取关键消息，保留信息量最高的用户输入。
+     * 权重：user=3 > tool=2 > assistant=1，同级按内容长度；最后恢复原始顺序。
+     */
+    private extractKeyMessages;
+    /** 消息重要性权重：user>tool>assistant */
     private messageImportance;
     /**
-     * 获取或创建上下文摘要（带缓存管理）
+     * 作废摘要缓存
      *
-     * 缓存 TTL：消息数增长超过 SUMMARY_CACHE_TTL_MSGS 时缓存过期，需重新生成。
-     * 首次调用时生成摘要并缓存，后续调用复用缓存直到过期。
+     * 缓存过期靠 `messages.length - contextSummaryMsgCount > TTL` 这个**单向**数值判断，
+     * 只覆盖「消息增长」。当消息集合被整体替换（`AgentLoop.restoreHistory` 恢复检查点）
+     * 且新历史更短时，差值为负 → 陈旧摘要永不过期，会把上一段会话的摘要注入新上下文。
      *
-     * signal 参数让摘要生成可被用户取消中断，
-     * 避免摘要 LLM 调用卡住时 generator 永久挂起（与 executeToolCalls 同源问题）。
+     * 修法不是把条件改成 `Math.abs`：truncateMessages 的正常裁剪同样让消息变少，
+     * 而那时摘要恰恰更该保留（它描述的就是被裁掉的历史）。真理源是「消息集合是否被替换」
+     * 这一事实，故由替换方显式作废，而非从长度差反推。
+     */
+    resetSummary(): void;
+    /**
+     * 获取或创建上下文摘要（带缓存）。
      *
-     * @param messages 当前消息数组（用于生成摘要和判断缓存过期）
-     * @param signal 可选的 AbortSignal，中断摘要生成
-     * @returns 摘要字符串（失败/中断时返回空字符串，降级为无摘要）
+     * 缓存 TTL：消息数增长超 SUMMARY_CACHE_TTL_MSGS 即过期重生成。
+     * signal 使摘要 LLM 可被中断，避免其卡住时挂起调用方。
      */
     getOrCreateSummary(messages: readonly Message[], signal?: AbortSignal): Promise<string>;
     /**
-     * 生成上下文摘要（enableContextSummary 时调用）
-     *
-     * 在首次截断时，提取即将被裁剪的消息中最近几条用户/助手对话，
-     * 调用 provider 生成一句摘要，作为"遗忘补偿"注入到 system prompt 中。
-     *
-     * 通过 tracer span 埋点（TRACE_SPANS.CONTEXT_SUMMARY），
-     * 让宿主监控面板能观察截断频率、摘要生成耗时与失败率。
-     *
-     * signal 参数传入 provider.chat 的 ChatOptions，
-     * 让 fetch 请求和 SSE 流读取都能被 abort 中断；
-     * for await 循环中也检查 signal.aborted 提前退出。
+     * 生成上下文摘要：把被裁剪段压缩成"遗忘补偿"注入 system prompt。
      *
-     * @param messages 当前消息数组
-     * @param signal 可选的 AbortSignal
-     * @returns 摘要字符串（失败/中断时返回空字符串，降级为无摘要）
+     * 策略：
+     * - 优先复用已存的 round-summary（每轮后台生成的零成本产物），仅无已存摘要才调 LLM；
+     * - 走 providerRouter 的 'summary' 路由（轻量模型），未配置则回退主 provider；
+     * - abort 或失败一律降级为空串返回，不影响主流程。
      */
     private generateContextSummary;
 }

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

@@ -1 +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;AAG9D,OAAO,EAA4B,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAG3E,4CAA4C;AAC5C,UAAU,qBAAqB;IAC7B,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;IACvE;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;CACjF;AAiDD;;;;;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;IAC/E,6DAA6D;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IAEjC,8BAA8B;IAC9B,OAAO,CAAC,cAAc,CAAuB;IAC7C,8BAA8B;IAC9B,OAAO,CAAC,sBAAsB,CAAa;IAC3C,yDAAyD;IACzD,OAAO,CAAC,gBAAgB,CAAa;IACrC,yBAAyB;IACzB,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAwD;gBAE/E,IAAI,EAAE,qBAAqB;IASvC,sCAAsC;IACtC,IAAI,eAAe,IAAI,MAAM,CAE5B;IAED;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM;IAsBpD;;;;;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;IAgGpF;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,kBAAkB;IA+B1B;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;;;;;;;;;;OAYG;IACG,kBAAkB,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC;IAiB7F;;;;;;;;;;;;;;;;OAgBG;YACW,sBAAsB;CAgFrC"}
+{"version":3,"file":"contextManager.d.ts","sourceRoot":"","sources":["../../src/agent/contextManager.ts"],"names":[],"mappings":"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"}