@zooique/memora 1.0.1 → 2.0.3

package/dist/agent/loop.d.ts

@@ -68,6 +68,20 @@ export interface AgentLoopOptions {
      * 避免关键信息永久丢失。（首次触发时增加 ~1-2s 延迟）
      */
     enableContextSummary?: boolean;
+    /**
+     * 上下文截断回调（宿主可据此发射 contextTruncated 事件通知用户）
+     *
+     * 每次 truncateMessages 触发截断时调用，传入被裁剪和保留的消息数量。
+     * 未注入时静默忽略。
+     */
+    onContextTruncated?: (skippedCount: number, keptCount: number) => void;
+    /**
+     * 护栏规则正则编译失败回调（宿主可据此发射 guardrailError 事件通知用户）
+     *
+     * 每次 runGuardrails 遇到正则编译异常时调用。
+     * 未注入时仅记日志（降级优先原则，不阻断对话）。
+     */
+    onGuardrailError?: (rule: string, message: string) => void;
 }
 export declare class AgentLoop {
     private readonly opts;
@@ -81,29 +95,32 @@ export declare class AgentLoop {
     private readonly guardrailRules;
     /** Reflection 最大重试次数（默认 2） */
     private readonly maxReflectionRetries;
+    /**
+     * 当前轮次已推送的 REFLECTION_HINT 次数（显式计数器）
+     *
+     * 替代旧实现通过 messages.filter(startsWith('[REFLECTION_HINT]')).length 推断的方式——
+     * 当 ContextManager 裁剪中间段消息时，REFLECTION_HINT 可能被裁掉导致计数失真。
+     * 显式字段不受 messages 数组变动影响，状态机更健壮。
+     */
+    private reflectionCountThisTurn;
     /** 宿主可覆盖的 UI 消息文本（已填充默认值） */
     private readonly ui;
+    /** 护栏规则正则编译失败回调（从 opts.onGuardrailError 提取，用于 GuardrailUI） */
+    private readonly guardrailUI;
     /** 上下文超限时是否自动生成摘要 */
     private readonly enableContextSummary;
     /** 上下文管理器（从 loop 提取的 token 估算 + 截断 + 摘要职责） */
     private readonly contextManager;
-    /** LLM 调用总次数（含重试，每次 provider.chat 调用 +1） */
-    private metricLlmCallCount;
-    /** 累计输入 token 数（基于 estimateTokens 粗略估算） */
-    private metricTotalInputTokens;
-    /** 累计输出 token 数（基于 estimateTokens 粗略估算） */
-    private metricTotalOutputTokens;
-    /** 记忆召回总次数（每轮 processUserInput +1） */
-    private metricRecallTotalCount;
-    /** 记忆召回命中次数（召回结果非空 +1） */
-    private metricRecallHitCount;
-    /** 工具调用总次数 */
-    private metricToolCallCount;
-    /** 工具调用失败次数（结果以 [ERR 开头） */
-    private metricToolFailureCount;
+    private metrics;
     constructor(opts: AgentLoopOptions);
     /**
-     * 处理一轮用户输入
+     * 处理一轮用户输入（编排方法）
+     *
+     * 拆分为 4 个子方法：
+     *   - handleRecallAndInputGuard：召回注入 + 输入护栏
+     *   - handleIteration：单次迭代编排（abort 检查 + LLM 调用 + 分支路由）
+     *   - handleToolCalls：工具调用分支 + Reflection
+     *   - handleTextResponse：纯文本结束 + 输出护栏
      *
      * @param userInput - 用户原始输入
      * @param recalledMemories - 记忆召回结果（Agent.memory.search() 产出），
@@ -112,6 +129,57 @@ export declare class AgentLoop {
      *   泊文等宿主 UI 传入 AbortController.signal，用户点击"取消"时触发 abort
      */
     processUserInput(userInput: string, recalledMemories?: readonly Memory[], signal?: AbortSignal): AsyncGenerator<AgentChunk, void, unknown>;
+    /**
+     * 召回注入 + 输入护栏（processUserInput 子方法 1/4）
+     *
+     * 职责：
+     *   - 注入记忆召回结果（system 消息，优先级高、不污染 user 输入）
+     *   - 召回命中率统计（metricRecallTotalCount / metricRecallHitCount）
+     *   - 通知上层 UI 召回透明度（yield recall chunk）
+     *   - 输入护栏检查（block 时 yield text + done，warn 时 yield text）
+     *
+     * @yields recall / text（guardrail block/warn）/ done（block 时）
+     * @returns true 表示输入被 block 已 yield done，调用方应 return；false 表示继续
+     */
+    private handleRecallAndInputGuard;
+    /**
+     * 单次迭代编排（processUserInput 子方法 2/4）
+     *
+     * 职责：
+     *   - abort 检查
+     *   - 上下文摘要 + 截断
+     *   - LLM 调用（callLlmWithRetry）
+     *   - LLM 中断处理
+     *   - 分支路由：工具调用 → handleToolCalls；纯文本 → handleTextResponse
+     *
+     * @yields text / aborted / done（由子方法委托）
+     * @returns 'aborted' | 'done' | 'continue'（continue 表示继续下一轮迭代）
+     */
+    private handleIteration;
+    /**
+     * 工具调用分支 + Reflection（processUserInput 子方法 3/4）
+     *
+     * 职责：
+     *   - executeToolCalls 执行工具调用
+     *   - abort 检查（工具执行中断）
+     *   - Reflection：检查可重试错误，追加反思提示
+     *
+     * @yields aborted（工具执行中断时）
+     * @returns 'aborted' | 'continue'（continue 表示工具结果已回填，继续下一轮 LLM 调用）
+     */
+    private handleToolCalls;
+    /**
+     * 纯文本结束 + 输出护栏（processUserInput 子方法 4/4）
+     *
+     * 职责：
+     *   - push assistant 消息（含空响应兜底）
+     *   - 输出护栏检查（block 时 yield text + done，warn 时 yield text）
+     *   - yield done 结束本轮对话
+     *
+     * @yields text（空响应兜底 / guardrail block/warn）/ done
+     * @returns 'done'（调用方收到后 return）
+     */
+    private handleTextResponse;
     /**
      * 调用 LLM（带指数退避重试）
      *
@@ -164,6 +232,27 @@ export declare class AgentLoop {
      * @returns 工具结果字符串，或 [ERR:TOOL:ABORTED] 表示被中断
      */
     private raceToolWithSignal;
+    /**
+     * 执行单个工具（E-803 抽取：为并行化提供独立执行单元）
+     *
+     * 职责：
+     *   - startSpan / endSpan（工具执行 Span，并发时 span 时间重叠，可观测性改进）
+     *   - raceToolWithSignal 竞争包裹（兼容 signal 中断，每个工具独立 race）
+     *   - 异常捕获并转为结构化错误字符串（[ERR:TOOL:code] 前缀，供 Reflection 解析）
+     *
+     * 不含职责（由 executeToolCalls 主循环控制，保证顺序确定）：
+     *   - yield tool_start / tool_result（事件顺序由主循环批量 yield 保证）
+     *   - messages.push（消息顺序由主循环按原始顺序 push，确保 Reflection slice 正确）
+     *   - metricToolCallCount / metricToolFailureCount（统计由主循环控制）
+     *
+     * 并发安全：本方法无共享状态，多个 executeOneTool 可同时执行。
+     * toolExecutor 内部无状态（纯分发 + 参数校验），天然支持并发调用。
+     *
+     * @param tc 单个工具调用描述（id + function.name + function.arguments）
+     * @param signal 可选的 AbortSignal
+     * @returns 工具结果字符串（成功）或 [ERR:TOOL:code] 错误字符串（失败）
+     */
+    private executeOneTool;
     /**
      * 构建 system prompt（注入人格 + 规则 + 领域 + 工具描述）
      */
@@ -231,6 +320,24 @@ export declare class AgentLoop {
      * @param newPrefix 新的系统 prompt 前缀（包含新角色 + 用户画像）
      */
     refreshPersonaPrefix(newPrefix: string): void;
+    /**
+     * 刷新 bootstrap 记忆段（设定面板 CRUD 专用）
+     *
+     * 设定面板对 rule/skill 执行增删改后，调用此方法用最新的记忆数组
+     * 重建 system prompt 中的 bootstrap 段，使变更立即对当前会话生效。
+     *
+     * 与 refreshPersonaPrefix 的区别：
+     *   - refreshPersonaPrefix 替换 systemPromptPrefix（角色 + 画像）
+     *   - refreshBootstrapMemories 替换 bootstrapMemories（rule + skill）
+     *
+     * 调用链：ConfigManager.deleteRule/updateRule/deleteSkill
+     *   → refreshBootstrapMemories 回调（assembler 注入）
+     *   → loop.refreshBootstrapMemories(memories)
+     *   → rebuildSystemMessage()
+     *
+     * @param memories 最新的 rule + skill 活跃记忆数组（由 ConfigManager.getBootstrapMemories 提供）
+     */
+    refreshBootstrapMemories(memories: Memory[]): void;
     /**
      * 注入情感基调到 system prompt（Phase 2.1：AffectController）
      *
@@ -297,5 +404,20 @@ export declare class AgentLoop {
      * 调用 isRetryableErrorCode 判断。
      */
     private isRetryableToolError;
+    /**
+     * 重试延迟 + abort 支持（从 callLlmWithRetry 提取，编码约定 §6 ≤60 行约束）
+     *
+     * 发射 retry chunk、等待指数退避延迟（支持中途 abort），返回 void。
+     * 调用方在延迟后自行检查 signal.aborted 决定是否退出重试循环。
+     */
+    private _waitForRetryWithAbort;
+    /**
+     * 处理工具执行结果：push messages + yield tool_result（从 executeToolCalls 提取）
+     */
+    private _processToolResults;
+    /**
+     * 注入记忆召回结果 + 统计 + 透明度通知（从 handleRecallAndInputGuard 提取）
+     */
+    private _injectRecall;
 }
 //# sourceMappingURL=loop.d.ts.map

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

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