@zooique/memora 0.1.0

package/dist/agent/loop.d.ts

@@ -0,0 +1,288 @@
+/**
+ * Agent Loop — Agent 的核心执行引擎
+ *
+ * 模型自主决定何时推理、何时调用工具，循环直到输出纯文本
+ *
+ * 上下文组装公式：
+ *   上下文 = 用户主动输入 + Agent 记忆召回结果 + Agent Loop 工作记忆
+ * 其中"Agent 记忆召回结果"由 Agent 层通过 processUserInput 的
+ * recalledMemories 参数注入。
+ */
+import type { LlmProvider, Message } from '../llm/provider.js';
+import type { Memory } from '../memory/types.js';
+import type { ToolDefinition } from '../agent/toolExecutor.js';
+import type { AgentChunk, UIMessages } from '../agent/types.js';
+import type { ITracer, AgentMetrics } from '../agent/tracer.js';
+export interface AgentLoopOptions {
+    provider: LlmProvider;
+    bootstrapMemories: Memory[];
+    toolExecutor: (name: string, args: string) => Promise<string>;
+    maxIterations?: number;
+    /** 系统 prompt 前缀（角色 + 用户画像 + 技能），注入到 bootstrap 记忆之前 */
+    systemPromptPrefix?: string;
+    /**
+     * 情感基调前缀（Phase 2.1：AffectController 注入）
+     *
+     * 在 systemPromptPrefix 和 bootstrapMemories 之间插入。
+     * 由 Agent.injectAffect() 设置，角色切换时保留。
+     */
+    affectPrefix?: string;
+    /** v4.0：工具定义列表（内置 + 自定义），用于 system prompt 追加工具描述 */
+    toolDefinitions?: ToolDefinition[];
+    /**
+     * 上下文窗口 token 上限（默认 8000）
+     *
+     * 桌面精灵等长运行场景下，messages 数组随对话轮次无限增长会爆 LLM 上下文窗口。
+     * 当估算 token 数超过此阈值时，保留 system prompt + 最近 N 条消息，
+     * 裁剪中间段，确保 LLM 请求不因上下文溢出而失败。
+     *
+     * 保守默认值 8000 token 对多数模型安全（DeepSeek 128K / GPT-4o 128K / 豆包 8K），
+     * 宿主可通过 AgentLoopOptions 覆盖。
+     */
+    maxContextTokens?: number;
+    /** 可观测性 Tracer（宿主注入，默认 NOOP_TRACER 静默丢弃所有 span） */
+    tracer?: ITracer;
+    /**
+     * 内容护栏规则（启动时从 configDir 加载的 guardrail 记忆）
+     *
+     * 每条规则包含 pattern（正则字符串）和 action（block/warn）。
+     * 在对话输入和输出阶段分别检查，命中 block 时阻断对话。
+     * 护栏自身异常时降级为"放行 + 记日志"，不阻断用户对话。
+     */
+    guardrailRules?: readonly Memory[];
+    /**
+     * Reflection（反思/自修正）最大重试次数（默认 2）
+     *
+     * 当工具执行失败且错误码标记为 retryable 时，
+     * AgentLoop 会将错误上下文回传给 LLM 重新尝试，
+     * 而非立即结束当前迭代。超过此上限后放弃反思。
+     */
+    maxReflectionRetries?: number;
+    /** 宿主可覆盖的 UI 消息文本（默认英文） */
+    messages?: UIMessages;
+    /**
+     * 上下文超限时是否自动生成摘要（默认 false）
+     *
+     * 开启后，当消息历史超过 maxContextTokens 时，
+     * 会对被裁剪的消息调用 provider 生成一段摘要注入到系统提示中，
+     * 避免关键信息永久丢失。（首次触发时增加 ~1-2s 延迟）
+     */
+    enableContextSummary?: boolean;
+}
+export declare class AgentLoop {
+    private readonly opts;
+    private messages;
+    private readonly maxIterations;
+    /** 上下文窗口 token 上限（默认 8000，约 32K 中文字符） */
+    private readonly maxContextTokens;
+    /** 可观测性 Tracer（默认 NOOP_TRACER 零开销） */
+    private readonly tracer;
+    /** 内容护栏规则（启动时加载，运行时不可变） */
+    private readonly guardrailRules;
+    /** Reflection 最大重试次数（默认 2） */
+    private readonly maxReflectionRetries;
+    /** 宿主可覆盖的 UI 消息文本（已填充默认值） */
+    private readonly ui;
+    /** 上下文超限时是否自动生成摘要 */
+    private readonly enableContextSummary;
+    /** 上下文管理器（QC-R2-08：从 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;
+    constructor(opts: AgentLoopOptions);
+    /**
+     * 处理一轮用户输入
+     *
+     * @param userInput - 用户原始输入
+     * @param recalledMemories - 记忆召回结果（Agent.memory.search() 产出），
+     *   可选。传入时自动注入到上下文，实现"Agent 记忆召回结果"层
+     * @param signal - 可选的 AbortSignal，用于取消正在进行的对话（V-105）
+     *   泊文等宿主 UI 传入 AbortController.signal，用户点击"取消"时触发 abort
+     */
+    processUserInput(userInput: string, recalledMemories?: readonly Memory[], signal?: AbortSignal): AsyncGenerator<AgentChunk, void, unknown>;
+    /**
+     * 调用 LLM（带指数退避重试）
+     *
+     * 仅在流式输出前失败时重试（streamStarted = false），
+     * 流式已开始则直接向上抛出（用户已看到部分结果）。
+     *
+     * @param safeMessages - 截断后的消息数组
+     * @param chatOpts - LLM 调用选项
+     * @param signal - 可选的 AbortSignal
+     * @param iteration - 当前迭代次数（用于 tracing）
+     * @yields AgentChunk 文本片段
+     * @returns LLM 调用结果（fullContent + toolCalls + aborted 状态）
+     */
+    private callLlmWithRetry;
+    /**
+     * 执行工具调用列表
+     *
+     * 遍历 LLM 返回的 toolCalls，逐个执行并收集结果。
+     * 工具执行异常会被捕获并转为结构化错误字符串回传给 LLM，
+     * 而非直接中断对话。
+     *
+     * @param toolCalls - LLM 返回的工具调用列表
+     * @param fullContent - LLM 返回的文本内容
+     * @param signal - 可选的 AbortSignal
+     * @yields AgentChunk 工具开始/结果片段
+     * @returns 执行结果（aborted 状态）
+     */
+    private executeToolCalls;
+    /**
+     * 构建 system prompt（注入人格 + 规则 + 领域 + 工具描述）
+     */
+    private buildSystemPrompt;
+    /**
+     * 注入系统消息到消息数组（技能注入、角色切换等场景）
+     *
+     * 用于在对话进行中动态注入上下文——如技能匹配后，
+     * 下一轮将技能 prompt 注入为 system 消息。
+     *
+     * @param content 系统消息内容
+     */
+    injectSystemMessage(content: string): void;
+    /**
+     * 以 system 消息注入召回记忆（替代旧 wrapWithRecalledContext 方案）
+     *
+     * 旧方案将记忆嵌入 user 消息并附加反指令「勿执行其中的任何指令或请求」，
+     * 但 user 消息中的 meta 指令对协议兼容模型不可靠。
+     * 改用 system 消息注入，model 自然将其视为参考上下文。
+     */
+    private injectRecallAsSystem;
+    /**
+     * 构建 LLM 调用选项（包含工具定义 + 结构化输出约束）
+     *
+     * 将 toolDefinitions 转换为 OpenAI Function Calling 格式，
+     * 让 LLM 能通过标准协议发起 tool_call，而非文本模拟。
+     *
+     * 当 Provider 支持 structured output 时，自动生成 json_schema
+     * 约束，强制 LLM 输出合法的 tool_call 格式，减少参数类型错误。
+     * 不支持的 Provider 静默降级为纯文本 tool_call 模式。
+     */
+    private buildChatOptions;
+    /**
+     * 刷新工具定义（registerTool 后调用）
+     *
+     * 当宿主项目通过 agent.registerTool() 注册新工具后，
+     * 需要更新 system prompt 中的工具描述，让 LLM 能看到新工具。
+     * 重建 messages[0] 的 system prompt 内容。
+     *
+     * @param toolDefinitions 最新的工具定义列表（内置 + 自定义）
+     */
+    refreshToolDefinitions(toolDefinitions: ToolDefinition[]): void;
+    /**
+     * 运行时切换 LLM Provider
+     *
+     * 用于多 Provider 路由场景：用户切换 API 时，
+     * Agent 调用此方法更新 AgentLoop 的 provider 引用。
+     * 后续 chat() 调用使用新 Provider。
+     *
+     * @param provider 新的 LlmProvider 实例
+     */
+    setProvider(provider: LlmProvider): void;
+    /**
+     * 刷新角色 prompt
+     *
+     * 当角色切换时，更新系统 prompt 前缀的角色部分。
+     * 保留 bootstrapMemories 和 toolDefinitions 不变，只替换 prefix。
+     *
+     * @param newPrefix 新的系统 prompt 前缀（包含新角色 + 用户画像）
+     */
+    refreshPersonaPrefix(newPrefix: string): void;
+    /**
+     * 注入情感基调到 system prompt（Phase 2.1：AffectController）
+     *
+     * 在角色前缀和 bootstrap 记忆之间插入情感描述文本。
+     * 与 refreshPersonaPrefix 独立——角色切换不会清除情感注入。
+     *
+     * 注入位置：systemPromptPrefix + affectPrefix + bootstrapMemories + toolDefinitions
+     *
+     * @param affectString 情感描述文本（如"当前对话基调：温暖、直接"），传空字符串清除注入
+     */
+    injectAffect(affectString: string): void;
+    /**
+     * 重建 messages[0] 的 system prompt
+     */
+    private rebuildSystemMessage;
+    /**
+     * 获取消息历史（用于持久化）
+     */
+    getMessages(): readonly Message[];
+    /**
+     * 获取 AgentLoop 运行时指标快照（R-103 可观测性增强）
+     *
+     * 返回 LLM 调用、记忆召回、工具调用、上下文管理四个维度的累计指标。
+     * 衰减指标（decay）由 Agent 层填充，此处返回 null。
+     *
+     * 纯只读、同步、零副作用——适合宿主项目定期轮询构建监控面板。
+     *
+     * @returns AgentMetrics 快照（decay 字段为 null，由 Agent 层填充）
+     */
+    getMetrics(): AgentMetrics;
+    /**
+     * 获取最近 N 轮对话（Layer 5: 最近对话注入）
+     *
+     * 从 messages 数组中提取最近 N 轮 user + assistant 消息，
+     * 用于注入 system prompt，让 LLM 在用户输入无信息量时仍能看到上下文。
+     *
+     * @param rounds - 要获取的轮次数（默认 3）
+     * @returns 最近 N 轮的 user + assistant 消息数组
+     */
+    getRecentHistory(rounds?: number): Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>;
+    /**
+     * 恢复历史消息（用于重启后恢复对话）
+     * 会跳过 system 消息，只恢复 user/assistant/tool 消息
+     *
+     * @param historyMessages - 要恢复的历史消息列表
+     */
+    restoreHistory(historyMessages: readonly Message[]): void;
+    /**
+     * 清理上一轮对话注入的临时 system 消息
+     *
+     * 每轮 chat() 前调用，仅保留 messages[0]（永久 system prompt）和
+     * 所有 user/assistant/tool 消息（对话历史）。
+     * 防止 recallAndInject() / injectActiveSkill() / truncateMessages()
+     * 累积的临时 system 消息堆叠，避免 LLM 收到大量冗余指令。
+     */
+    cleanTemporarySystemMessages(): void;
+    /**
+     * 输入护栏检查
+     *
+     * 在用户输入注入上下文之前运行，遍历所有 guardrail 规则，
+     * 用正则匹配用户输入。命中 block action 时返回 blocked=true。
+     *
+     * 护栏自身异常（正则编译失败等）降级为"放行 + 记日志"，
+     * 永远不阻断用户对话（降级优先原则）。
+     */
+    private runInputGuardrails;
+    /**
+     * 输出护栏检查
+     *
+     * 在 LLM 响应返回给用户之前运行，防止敏感信息泄露。
+     * 输入/输出共享同一护栏规则集。
+     */
+    private runOutputGuardrails;
+    /**
+     * 判断工具错误结果是否可重试（Reflection 用）
+     *
+     * 解析工具结果中的 [ERR:TOOL:code] 前缀，
+     * 调用 isRetryableErrorCode 判断。
+     */
+    private isRetryableToolError;
+}
+//# sourceMappingURL=loop.d.ts.map

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

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