@cicctencent/agent-core 0.1.99 → 0.1.101

package/dist/cjs/agent/engine.d.ts

@@ -146,8 +146,19 @@ export declare class AgentEngine {
     private buildToolContext;
     /** 汇总准备阶段，生成 LoopState */
     private prepareRun;
+    /** 动态构建工具区 prompt（Available Tools + Tool Usage Guidelines）。
+     * 从 state.toolDefs 现场拼装，确保与可执行工具集一致，消除静态穿透。 */
+    private buildDynamicToolSection;
+    /** 刷新 system prompt 中的工具区，确保与 state.toolDefs 一致 */
+    private refreshToolSection;
     /** 主循环：迭代调用 LLM → 执行工具 → 直到完成或达到上限 */
     private agentLoop;
+    /**
+     * 生成兜底总结（当 LLM 调用失败或无内容输出时使用）。
+     * 从工具调用记录中提取摘要信息，确保用户始终能收到有意义的回复，
+     * 而非仅看到 "Max iterations reached"。
+     */
+    private generateFallbackSummary;
     /**
      * 向运行中的 Agent 注入 steering 消息
      * 消息将在下次 LLM 调用前注入对话上下文

package/dist/cjs/agent/engine.d.ts.map

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

package/dist/cjs/agent/engine.js

@@ -173,7 +173,8 @@ class AgentEngine {
         });
         // 初始化工具分类集合（可通过 config 覆盖默认值）
         this.dataFetchTools = new Set(config.dataFetchTools ?? [
-            'web_fetch', 'execute_command', 'write_file', 'append_file',
+            'web_fetch', 'http_request', 'browser_navigate', 'browser_click',
+            'execute_command', 'write_file', 'append_file',
             'run_script', 'read_file', 'read_tool_doc',
         ]);
         this.outputTools = new Set(config.outputTools ?? [
@@ -351,6 +352,15 @@ class AgentEngine {
                 iteration: 0,
                 rawError: err,
             });
+            // 异常终止时以 error 状态结束 trace（正常路径由 emitDone 触发 on_complete，
+            // 此处显式调用确保 trace 不会卡在 active，也不会被 runWithTrace 覆盖为 ok）
+            this.runHooks('on_complete', {
+                sessionId,
+                iteration: 0,
+                totalIterations: 0,
+                runStatus: 'error',
+                error: errorMsg,
+            }).catch(() => { });
             this.statusMap.set(sessionId, 'idle');
         }
         finally {
@@ -703,7 +713,9 @@ ${textHistory.join('\n')}`;
             abortSignal: internalAbort.signal,
             custom: {
                 ...custom,
-                toolRegistry: custom?.toolRegistry ?? this.config.toolRegistry,
+                // Fix A：始终使用引擎授权注册表（已按 selectedTools/disabledTools 过滤），
+                // 不接受 custom.toolRegistry 覆盖——防止 read_tool_doc/diagnose 泄漏被禁工具 schema。
+                toolRegistry: this.config.toolRegistry,
                 skillManager: custom?.skillManager ?? this.config.skillManager,
             },
             emitSubEvent: custom?.emitSubEvent,
@@ -716,9 +728,15 @@ ${textHistory.join('\n')}`;
         const { skillContent, actualMessage, skillMatched } = await this.resolveSkill(options, options.sessionId);
         const toolDefs = this.resolveToolDefs(options);
         (0, logger_ts_1.logEvent)({ event: 'engine.prepare', sessionId: options.sessionId, data: { toolCount: toolDefs.length, tools: toolDefs.map(t => t.function.name) } });
+        const messages = await this.buildInitialMessages(options, skillContent, actualMessage, skillMatched);
+        // 存储不含工具区的稳定系统提示词，首次注入动态工具区
+        const stableSystemPrompt = messages[0]?.content || '';
+        if (messages[0]) {
+            messages[0].content = stableSystemPrompt + this.buildDynamicToolSection(toolDefs);
+        }
         return {
             sessionId: options.sessionId,
-            messages: await this.buildInitialMessages(options, skillContent, actualMessage, skillMatched),
+            messages,
             toolDefs,
             toolContext: this.buildToolContext(options, internalAbort),
             internalAbort,
@@ -726,6 +744,7 @@ ${textHistory.join('\n')}`;
             lastContent: '',
             toolCallRecords: [],
             consecutiveToolFailures: new Map(),
+            blockedTools: new Set(),
             iterationGuardInjected: false,
             consecutiveSilentIterations: 0,
             lastIterationHadToolCalls: false,
@@ -733,8 +752,39 @@ ${textHistory.join('\n')}`;
             dataFetchGuardInjected: false,
             consecutiveAllFailIterations: 0,
             finalSummaryInjected: false,
+            hadFatalError: false,
+            fatalErrorMsg: undefined,
+            stableSystemPrompt,
         };
     }
+    /** 动态构建工具区 prompt（Available Tools + Tool Usage Guidelines）。
+     * 从 state.toolDefs 现场拼装，确保与可执行工具集一致，消除静态穿透。 */
+    buildDynamicToolSection(toolDefs) {
+        if (this.config.buildToolSection) {
+            return this.config.buildToolSection(toolDefs, this.config.toolRegistry);
+        }
+        if (toolDefs.length === 0)
+            return '';
+        const lines = toolDefs.map(d => `- \`${d.function.name}\`: ${d.function.description || ''}`);
+        let section = `\n\n## Available Tools\n${lines.join('\n')}`;
+        // 收集工具自带的使用引导（tool.prompt）
+        const prompts = [];
+        for (const def of toolDefs) {
+            const tool = this.config.toolRegistry.get(def.function.name);
+            if (tool?.prompt)
+                prompts.push(tool.prompt);
+        }
+        if (prompts.length > 0) {
+            section += `\n\n## Tool Usage Guidelines\n\n${prompts.join('\n\n')}`;
+        }
+        return section;
+    }
+    /** 刷新 system prompt 中的工具区，确保与 state.toolDefs 一致 */
+    refreshToolSection(state) {
+        if (state.messages[0] && state.stableSystemPrompt != null) {
+            state.messages[0].content = state.stableSystemPrompt + this.buildDynamicToolSection(state.toolDefs);
+        }
+    }
     // ---- Agent Loop ----
     /** 主循环：迭代调用 LLM → 执行工具 → 直到完成或达到上限 */
     async *agentLoop(state) {
@@ -742,6 +792,11 @@ ${textHistory.join('\n')}`;
             state.iteration++;
             // 中断检查
             if (state.internalAbort.signal.aborted) {
+                // 外部中断（客户端断开 / 用户主动 abort / 看门狗超时）：标记致命错误，
+                // 确保 emitDone → on_complete 将 trace 状态写为 error，而非默认的 ok，
+                // 避免 trace 卡在 active 或被误判为正常完成。
+                state.hadFatalError = true;
+                state.fatalErrorMsg = state.fatalErrorMsg || 'Run aborted before completion';
                 yield this.emitDone(state);
                 return;
             }
@@ -765,11 +820,28 @@ ${textHistory.join('\n')}`;
                             timestamp: Date.now(),
                             iteration: state.iteration,
                         });
+                        // 记录可观测 error 事件：让 trace 时间线解释"为何熔断"，
+                        // 与 on_complete(runStatus='error') 闭环，确保异常被统计进可观测。
+                        await this.runHooks('on_error', {
+                            sessionId: state.sessionId,
+                            iteration: state.iteration,
+                            error: budgetErrMsg,
+                            recoverable: false,
+                        });
+                        state.hadFatalError = true;
+                        state.fatalErrorMsg = budgetErrMsg;
                         yield this.emitDone(state);
                         return;
                     }
                     else {
                         (0, logger_ts_1.logEvent)({ event: 'engine.token_budget_warning', sessionId: state.sessionId, level: 'warn', data: { current: budgetCheck.currentTokens, max: budgetCheck.maxTokens } });
+                        await this.runHooks('on_budget_warning', {
+                            sessionId: state.sessionId,
+                            iteration: state.iteration,
+                            currentTokens: budgetCheck.currentTokens,
+                            maxTokens: budgetCheck.maxTokens,
+                            traceId: state.toolContext?.custom?.traceId,
+                        });
                     }
                 }
             }
@@ -787,6 +859,12 @@ ${textHistory.join('\n')}`;
                     messages: steeringResult.messages,
                     count: steeringResult.count,
                 });
+                await this.runHooks('on_steering', {
+                    sessionId: state.sessionId,
+                    iteration: state.iteration,
+                    steeringMessages: steeringResult.messages,
+                    traceId: state.toolContext?.custom?.traceId,
+                });
             }
             // 迭代预算提醒：接近上限时注入提醒，防止 agent 耗尽迭代仍在收集数据
             this.injectIterationGuard(state);
@@ -794,6 +872,8 @@ ${textHistory.join('\n')}`;
             // 首次触发：注入 guard 消息让 LLM 下轮产出总结；不立即终止，给 LLM 一次产出机会
             // 若 LLM 继续失败，全局连续失败熔断器（consecutiveAllFailIterations >= 3）会兜底
             this.checkDataFetchLoop(state);
+            // 动态拼装工具区，确保 system prompt 工具列表与 state.toolDefs 一致
+            this.refreshToolSection(state);
             // 调用 LLM（流式，含重试与降级）
             this.statusMap.set(state.sessionId, 'thinking');
             const llmStart = Date.now();
@@ -809,9 +889,12 @@ ${textHistory.join('\n')}`;
                 state.totalUsage.totalTokens += usage.totalTokens || 0;
             }
             if (!assistant) {
-                // 所有 LLM provider 均已失败（callWithRetry 内部已重试+降级），
-                // 不再发 done 事件（callWithRetry 已发出带详细错误信息的 error 事件），
-                // 仅完成清理，避免 done 事件覆盖前端已展示的错误消息
+                // 所有 LLM provider 均已失败（callWithRetry 内部已重试+降级）。
+                // callWithRetry 已发出 error 事件，此处补充 done 事件以正确关闭 SSE 流。
+                // 不发 done 事件会导致：SSE 流不关闭、DB 消息状态卡在 streaming、
+                // 前端 onDone 回调不触发（无法更新 UI 状态）。
+                // error 和 done 是不同的 SSE 事件类型，前端分别用 onError 和 onDone 处理，
+                // done 事件携带 lastContent（之前成功迭代的输出）或兜底总结，不会覆盖 error 消息。
                 const errorMsg = 'All LLM providers exhausted (all calls failed including retries and fallback)';
                 (0, logger_ts_1.logEvent)({ event: 'engine.llm_exhausted', sessionId: state.sessionId, level: 'warn', data: { iteration: state.iteration } });
                 this.statusMap.set(state.sessionId, 'idle');
@@ -823,25 +906,11 @@ ${textHistory.join('\n')}`;
                     timestamp: Date.now(),
                     iteration: state.iteration,
                 });
-                // 记录 Token 用量到 UsageTracker
-                if (this.config.usageTracker && state.totalUsage) {
-                    const modelInfo = this.config.llmProvider.getModel();
-                    this.config.usageTracker.record({
-                        sessionId: state.sessionId,
-                        provider: modelInfo.provider,
-                        model: modelInfo.model,
-                        usage: state.totalUsage,
-                        iterations: state.iteration,
-                    });
-                }
-                this.runHooks('on_complete', {
-                    sessionId: state.sessionId,
-                    iteration: state.iteration,
-                    totalIterations: state.iteration,
-                    usage: state.totalUsage,
-                    traceId: state.toolContext?.custom?.traceId,
-                    output: state.lastContent || undefined,
-                }).catch(() => { });
+                state.hadFatalError = true;
+                state.fatalErrorMsg = errorMsg;
+                // 发出 done 事件，确保 SSE 流正确关闭、DB 状态正确更新
+                // emitDone 内部会记录 Token 用量、调用 on_complete hook 并生成兜底总结
+                yield this.emitDone(state);
                 return;
             }
             // Hook: after_ll_call
@@ -877,6 +946,12 @@ ${textHistory.join('\n')}`;
                     state.lastIterationHadToolCalls = false; // 已消费标记，避免重复注入
                     (0, logger_ts_1.logEvent)({ event: 'engine.continuation_nudge', sessionId: state.sessionId, data: { nudge: state.continuationNudges, iteration: state.iteration } });
                     this.injectContinuationNudge(state);
+                    await this.runHooks('on_continuation_nudge', {
+                        sessionId: state.sessionId,
+                        iteration: state.iteration,
+                        nudgeCount: state.continuationNudges,
+                        traceId: state.toolContext?.custom?.traceId,
+                    });
                     // 不退出，继续下一轮迭代让 LLM 继续执行任务
                     continue;
                 }
@@ -913,6 +988,17 @@ ${textHistory.join('\n')}`;
                             timestamp: Date.now(),
                             iteration: state.iteration,
                         });
+                        // 记录可观测 error 事件：让 trace 时间线解释"为何熔断"，
+                        // 与 on_complete(runStatus='error') 闭环，确保异常被统计进可观测。
+                        await this.runHooks('on_error', {
+                            sessionId: state.sessionId,
+                            iteration: state.iteration,
+                            error: failMsg,
+                            recoverable: false,
+                        });
+                        state.hadFatalError = true;
+                        state.fatalErrorMsg = failMsg;
+                        state.lastContent = this.generateFallbackSummary(state);
                         yield this.emitDone(state);
                         return;
                     }
@@ -922,7 +1008,15 @@ ${textHistory.join('\n')}`;
                 }
             }
             // 渐进式结果交付：并行分发多个 delegate_task 后，提示 LLM 逐步呈现结果
+            const delegateCount = assistant.tool_calls?.filter(tc => tc.function.name === 'delegate_task').length ?? 0;
             this.injectProgressiveNudge(state, assistant.tool_calls);
+            if (delegateCount >= 2) {
+                await this.runHooks('on_progressive_nudge', {
+                    sessionId: state.sessionId,
+                    iteration: state.iteration,
+                    traceId: state.toolContext?.custom?.traceId,
+                });
+            }
             // 标记本轮有工具调用（用于下一轮检测 LLM 是否提前停止）
             state.lastIterationHadToolCalls = true;
             // Middleware.after
@@ -958,8 +1052,13 @@ ${textHistory.join('\n')}`;
             };
             state.messages.push(summaryMsg);
             this.historyManager.addHistory(state.sessionId, summaryMsg);
-            (0, logger_ts_1.logEvent)({ event: 'engine.final_summary_injected', sessionId: state.sessionId, data: { iteration: state.iteration, max: maxIter } });
+            // 主动压缩上下文：防止累积的工具结果导致 prompt 过大、LLM 调用失败
+            const maxContextTokens = this.config.contextBudget?.maxContextTokens ?? 100000;
+            const compressedTarget = Math.floor(maxContextTokens * 0.6);
+            const tokensAfter = this.historyManager.compressMessages(state.messages, compressedTarget);
+            (0, logger_ts_1.logEvent)({ event: 'engine.final_summary_injected', sessionId: state.sessionId, data: { iteration: state.iteration, max: maxIter, compressedTokens: tokensAfter } });
             // 最后一次 LLM 调用（不再执行工具，直接产出文本）
+            this.refreshToolSection(state);
             this.statusMap.set(state.sessionId, 'thinking');
             const { assistant: finalAssistant, usage: finalUsage } = yield* this.llmCaller.callWithRetry(state.sessionId, state.messages, state.toolDefs, state.internalAbort.signal);
             if (finalUsage) {
@@ -977,10 +1076,51 @@ ${textHistory.join('\n')}`;
                     state.lastContent = (0, types_ts_1.extractTextFromContent)(finalAssistant.content);
                 }
             }
+            else {
+                // LLM 调用失败：生成兜底总结，确保用户始终能收到有意义的回复
+                state.lastContent = this.generateFallbackSummary(state);
+                (0, logger_ts_1.logEvent)({ event: 'engine.fallback_summary', sessionId: state.sessionId, level: 'warn', data: { iteration: state.iteration, toolCalls: state.toolCallRecords.length } });
+            }
             this.statusMap.set(state.sessionId, 'idle');
         }
         yield this.emitDone(state);
     }
+    /**
+     * 生成兜底总结（当 LLM 调用失败或无内容输出时使用）。
+     * 从工具调用记录中提取摘要信息，确保用户始终能收到有意义的回复，
+     * 而非仅看到 "Max iterations reached"。
+     */
+    generateFallbackSummary(state) {
+        const records = state.toolCallRecords;
+        if (records.length === 0) {
+            return '任务未能完成：未执行任何工具调用，可能由于配置问题或会话被中断。请重试或联系管理员。';
+        }
+        // 按工具名分组统计
+        const byTool = new Map();
+        for (const r of records) {
+            const entry = byTool.get(r.tool) || { total: 0, failed: 0 };
+            entry.total++;
+            if (r.isError)
+                entry.failed++;
+            byTool.set(r.tool, entry);
+        }
+        const lines = [
+            '抱歉，任务未能完成。以下是执行摘要：',
+            '',
+            `**执行轮次**: ${state.iteration} 轮`,
+            `**工具调用**: ${records.length} 次`,
+            '',
+            '**尝试的工具及结果**:',
+        ];
+        for (const [tool, info] of byTool) {
+            const status = info.failed === info.total
+                ? '全部失败'
+                : info.failed > 0 ? `${info.failed}/${info.total} 失败` : '成功但未获得有效数据';
+            lines.push(`- \`${tool}\`: ${info.total} 次调用 (${status})`);
+        }
+        lines.push('', '**可能的原因**:', '- 外部数据源无法访问（网络限制/API密钥/数据源变更）', '', '**建议**:', '1. 提供具体的数据文件或 API 密钥', '2. 手动提供数据让我进行分析', '3. 稍后重试或更换网络环境');
+        return lines.join('\n');
+    }
     // ---- Live Steering（实时转向）----
     /**
      * 向运行中的 Agent 注入 steering 消息
@@ -1105,8 +1245,16 @@ ${textHistory.join('\n')}`;
         const before = state.toolDefs.length;
         state.toolDefs = state.toolDefs.filter(t => !this.dataFetchTools.has(t.function.name));
         const removed = before - state.toolDefs.length;
+        // 同步将禁用的工具名加入 blockedTools 集合，供 tool executor 在执行层拦截
+        // LLM 基于对话历史的幻觉调用（toolDefs 仅控制 LLM 可见的工具列表，
+        // 但 tool executor 检查的是 toolRegistry，不会拦截已注册但被禁用的工具）
+        if (!state.blockedTools)
+            state.blockedTools = new Set();
+        for (const name of this.dataFetchTools) {
+            state.blockedTools.add(name);
+        }
         if (removed > 0) {
-            (0, logger_ts_1.logEvent)({ event: 'engine.tools_disabled', sessionId: state.sessionId, data: { removed, remaining: state.toolDefs.length } });
+            (0, logger_ts_1.logEvent)({ event: 'engine.tools_disabled', sessionId: state.sessionId, data: { removed, remaining: state.toolDefs.length, blocked: state.blockedTools.size } });
         }
     }
     /**
@@ -1146,6 +1294,17 @@ ${textHistory.join('\n')}`;
                 return;
             }
         }
+        // --- 条件 3：跨迭代累计失败（总调用 >=8 且失败率 >=70%） ---
+        // 解决 LLM 在不同迭代中切换工具类型（web_fetch -> http_request -> browser_navigate）
+        // 导致每种工具的连续失败计数都不够触发条件 2 的问题。
+        const totalCalls = state.toolCallRecords.length;
+        if (totalCalls >= 8) {
+            const totalErrors = state.toolCallRecords.filter(r => r.isError).length;
+            if (totalErrors >= Math.floor(totalCalls * 0.7)) {
+                this.injectDataFetchGuard(state, state.toolCallRecords.slice(-6), 'cumulative_failures');
+                return;
+            }
+        }
     }
     /** 注入数据获取循环/连续失败熔断提示 */
     injectDataFetchGuard(state, recent, reason) {
@@ -1339,17 +1498,20 @@ ${textHistory.join('\n')}`;
                 totalUsage: state.totalUsage,
             });
         }
+        const finalContent = state.lastContent || this.generateFallbackSummary(state);
         this.runHooks('on_complete', {
             sessionId: state.sessionId,
             iteration: state.iteration,
             totalIterations: state.iteration,
             usage: state.totalUsage,
             traceId: state.toolContext?.custom?.traceId,
-            output: state.lastContent || undefined,
+            output: finalContent,
+            runStatus: state.hadFatalError ? 'error' : 'ok',
+            error: state.fatalErrorMsg,
         }).catch(() => { });
         return this.createEvent(state.sessionId, {
             type: 'done',
-            content: state.lastContent || 'Max iterations reached',
+            content: finalContent,
             iterations: state.iteration,
             usage: state.totalUsage,
         });