@cicctencent/agent-core 0.1.98 → 0.1.100

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

@@ -148,6 +148,12 @@ export declare class AgentEngine {
     private prepareRun;
     /** 主循环：迭代调用 LLM → 执行工具 → 直到完成或达到上限 */
     private agentLoop;
+    /**
+     * 生成兜底总结（当 LLM 调用失败或无内容输出时使用）。
+     * 从工具调用记录中提取摘要信息，确保用户始终能收到有意义的回复，
+     * 而非仅看到 "Max iterations reached"。
+     */
+    private generateFallbackSummary;
     /**
      * 向运行中的 Agent 注入 steering 消息
      * 消息将在下次 LLM 调用前注入对话上下文
@@ -167,6 +173,12 @@ export declare class AgentEngine {
      * 解决 agent 在数据查询循环中耗尽迭代、永远无法进入文档生成/委托阶段的问题。
      */
     private injectIterationGuard;
+    /**
+     * 从可用工具列表中移除数据获取类工具，强制 LLM 转向产出。
+     * 在 iterationGuard / dataFetchGuard 触发后调用。
+     * 仅移除尚未执行的 toolDefs，不影响正在执行的工具。
+     */
+    private disableDataFetchTools;
     /**
      * 数据获取循环检测 + 连续失败熔断
      *

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,
@@ -726,12 +738,16 @@ ${textHistory.join('\n')}`;
             lastContent: '',
             toolCallRecords: [],
             consecutiveToolFailures: new Map(),
+            blockedTools: new Set(),
             iterationGuardInjected: false,
             consecutiveSilentIterations: 0,
             lastIterationHadToolCalls: false,
             continuationNudges: 0,
             dataFetchGuardInjected: false,
             consecutiveAllFailIterations: 0,
+            finalSummaryInjected: false,
+            hadFatalError: false,
+            fatalErrorMsg: undefined,
         };
     }
     // ---- Agent Loop ----
@@ -741,6 +757,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;
             }
@@ -764,11 +785,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,
+                        });
                     }
                 }
             }
@@ -786,6 +824,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);
@@ -808,9 +852,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');
@@ -822,24 +869,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,
-                }).catch(() => { });
+                state.hadFatalError = true;
+                state.fatalErrorMsg = errorMsg;
+                // 发出 done 事件，确保 SSE 流正确关闭、DB 状态正确更新
+                // emitDone 内部会记录 Token 用量、调用 on_complete hook 并生成兜底总结
+                yield this.emitDone(state);
                 return;
             }
             // Hook: after_ll_call
@@ -875,6 +909,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;
                 }
@@ -911,6 +951,16 @@ ${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;
                         yield this.emitDone(state);
                         return;
                     }
@@ -920,15 +970,118 @@ ${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
             await this.runMiddlewarePhase('after', state);
         }
-        // 达到最大迭代
+        // 达到最大迭代 - 注入最终总结提示，给 LLM 最后一次机会输出结果
+        if (!state.finalSummaryInjected) {
+            state.finalSummaryInjected = true;
+            // 禁用所有数据获取工具，确保 LLM 只能产出结果
+            this.disableDataFetchTools(state);
+            const maxIter = this.config.maxIterations;
+            const summaryMsg = {
+                role: 'user',
+                content: [
+                    `[SYSTEM: MAX ITERATIONS REACHED - FINAL OUTPUT REQUIRED]`,
+                    '',
+                    `You have reached the maximum number of iterations (${maxIter}). Your task is now OVER.`,
+                    '',
+                    '**You MUST produce your final output NOW.**',
+                    '',
+                    'Rules:',
+                    '1. Do NOT attempt any more tool calls - data gathering tools have been disabled.',
+                    '2. If you have data from previous tool calls, present it directly in text.',
+                    ...(this.hasTool('show_widget') ? ['3. Use `show_widget` to visualize any data you have.'] : []),
+                    ...(this.hasTool('create_document') ? ['4. Use `create_document` to create a structured report.'] : []),
+                    '5. If you do NOT have sufficient data, clearly explain to the user:',
+                    '   - What you were trying to find',
+                    '   - Which data sources you tried and why they failed',
+                    '   - What the user can do to get the data they need',
+                    '',
+                    'The user is waiting for a response. Provide it NOW.',
+                ].join('\n'),
+            };
+            state.messages.push(summaryMsg);
+            this.historyManager.addHistory(state.sessionId, summaryMsg);
+            // 主动压缩上下文：防止累积的工具结果导致 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.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) {
+                if (!state.totalUsage) {
+                    state.totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+                }
+                state.totalUsage.promptTokens += finalUsage.promptTokens || 0;
+                state.totalUsage.completionTokens += finalUsage.completionTokens || 0;
+                state.totalUsage.totalTokens += finalUsage.totalTokens || 0;
+            }
+            if (finalAssistant) {
+                state.messages.push(finalAssistant);
+                this.historyManager.addHistory(state.sessionId, finalAssistant);
+                if (finalAssistant.content) {
+                    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 消息
@@ -1040,6 +1193,29 @@ ${textHistory.join('\n')}`;
             state.messages.push(msg);
             this.historyManager.addHistory(state.sessionId, msg);
             (0, logger_ts_1.logEvent)({ event: 'engine.iteration_guard', sessionId: state.sessionId, data: { iteration: cur, max } });
+            // 硬性禁用数据获取工具，防止 LLM 无视文字提示继续调用
+            this.disableDataFetchTools(state);
+        }
+    }
+    /**
+     * 从可用工具列表中移除数据获取类工具，强制 LLM 转向产出。
+     * 在 iterationGuard / dataFetchGuard 触发后调用。
+     * 仅移除尚未执行的 toolDefs，不影响正在执行的工具。
+     */
+    disableDataFetchTools(state) {
+        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, blocked: state.blockedTools.size } });
         }
     }
     /**
@@ -1079,6 +1255,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) {
@@ -1115,6 +1302,8 @@ ${textHistory.join('\n')}`;
         state.messages.push(msg);
         this.historyManager.addHistory(state.sessionId, msg);
         (0, logger_ts_1.logEvent)({ event: 'engine.data_fetch_guard', sessionId: state.sessionId, data: { reason, iteration: state.iteration, recent: toolSummary } });
+        // 硬性禁用数据获取工具，防止 LLM 无视文字提示继续调用
+        this.disableDataFetchTools(state);
     }
     /**
      * 任务继续提示
@@ -1276,10 +1465,13 @@ ${textHistory.join('\n')}`;
             totalIterations: state.iteration,
             usage: state.totalUsage,
             traceId: state.toolContext?.custom?.traceId,
+            output: state.lastContent || undefined,
+            runStatus: state.hadFatalError ? 'error' : 'ok',
+            error: state.fatalErrorMsg,
         }).catch(() => { });
         return this.createEvent(state.sessionId, {
             type: 'done',
-            content: state.lastContent || 'Max iterations reached',
+            content: state.lastContent || this.generateFallbackSummary(state),
             iterations: state.iteration,
             usage: state.totalUsage,
         });