@zhin.js/agent 0.1.20 → 0.1.22

package/lib/zhin-agent/index.js

@@ -15,28 +15,36 @@
  *  11. 定时任务：cron_add 持久化定时任务
  *  12. 多模态输入：图片/音频直接传给视觉模型
  */
-import { Logger, getPlugin } from '@zhin.js/core';
+import { getPlugin, Logger } from '@zhin.js/core';
+import { formatCompact, truncatePreview } from '@zhin.js/logger';
+import { ensureMcpConnections } from '../orchestrator/mcp-lifecycle.js';
 import { createAgent } from '@zhin.js/ai';
 import { SessionManager, createMemorySessionManager } from '@zhin.js/ai';
 import { ConversationMemory } from '@zhin.js/ai';
 import { parseOutput } from '@zhin.js/ai';
+import { addUsage, EMPTY_USAGE, } from './turn-metrics.js';
 import { UserProfileStore } from '../user-profile.js';
 import { WEB_SEARCH_LOCALE_EXTRA_KEY, normalizeWebSearchLocaleHint, } from '../builtin/web-search-locale.js';
 import { RateLimiter } from '@zhin.js/ai';
 import { detectTone } from '@zhin.js/ai';
 import { SubagentManager } from '../subagent.js';
 import { triggerAIHook, createAIHookEvent } from '../hooks.js';
+import { resolveAgentPromptMarkdown } from '../agent-prompt/index.js';
 // ── Sub-modules ─────────────────────────────────────────────────────
 import { DEFAULT_CONFIG, isPhaseTraceEnabled, } from './config.js';
 import { applyExecPolicyToTools } from '../security/exec-policy.js';
 import { runWithBashToolContext } from '../security/bash-tool-context.js';
-import { buildEnhancedPersona, buildContextHint, buildRichSystemPrompt, buildUserMessageWithHistory, FIXED_DISCIPLINE_RULES, } from './prompt.js';
+import { buildEnhancedPersona, buildContextHint, buildRichSystemPrompt, buildLiteSystemPromptWithPlatform, buildUserMessageWithHistory, FIXED_DISCIPLINE_RULES, } from './prompt.js';
 import { buildPreExecFastPathPrompt, collectRuntimeTools, planToolRun, } from './tool-runtime.js';
+import { DeferredWorkerRunner } from '../deferred-worker-runner.js';
+import { buildOrchestratorAgentTools } from './tool-search-orchestrator.js';
+import { filterToolsForToolSearchCatalog } from './tool-catalog.js';
 import { stripHallucinatedToolCalls, stripThinkBlocks } from './text-sanitize.js';
 import { pruneHistoryWithBudget } from './context-budget.js';
 import { resolveModelHarness } from './model-harness.js';
 import { RESERVED_TOOL_NAMES, RESERVED_TOOL_NAME_PREFIXES } from '../reserved-tools.js';
 import { createOwnerOrchestratedToolResultTransform } from '../orchestrator/owner-confirm-orchestration.js';
+export { formatAiHandlerCompleteLog, formatZhinAgentTurnUsage } from './turn-metrics.js';
 const logger = new Logger(null, 'ZhinAgent');
 const now = () => performance.now();
 // ============================================================================
@@ -46,6 +54,7 @@ export class ZhinAgent {
     provider;
     config;
     skillRegistry = null;
+    orchestrator = null;
     sessions;
     contextManager = null;
     memory;
@@ -60,6 +69,12 @@ export class ZhinAgent {
     phaseTraceEnabled;
     /** 根插件（createZhinAgentContext 注入）；避免在 Agent.run 路径依赖 AsyncLocalStorage 上的 getPlugin() */
     hostPlugin = null;
+    deferredCatalog = [];
+    deferredWorkerRunner = new DeferredWorkerRunner();
+    lastToolSearchDeferredStats;
+    lastTurnMetrics = null;
+    activeTurnSubagentUsage = null;
+    activeTurnSubagentWaits = [];
     constructor(provider, config) {
         this.provider = provider;
         this.config = { ...DEFAULT_CONFIG, ...config };
@@ -79,6 +94,10 @@ export class ZhinAgent {
         this.skillRegistry = registry;
         logger.debug(`SkillRegistry connected (${registry.size} skills)`);
     }
+    setOrchestrator(orchestrator) {
+        this.orchestrator = orchestrator;
+        logger.debug('AgentOrchestrator connected for MCP and resources');
+    }
     setSessionManager(manager) {
         this.sessions.dispose();
         this.sessions = manager;
@@ -110,6 +129,8 @@ export class ZhinAgent {
             maxIterations: this.config.maxSubagentIterations,
             execPolicyConfig: this.config,
             modelRegistry: this.modelRegistry,
+            onSubagentUsage: (usage) => this.addActiveTurnSubagentUsage(usage),
+            registerSubagentTask: (done) => this.trackActiveTurnSubagent(done),
         });
         logger.debug('SubagentManager initialized');
     }
@@ -170,6 +191,51 @@ export class ZhinAgent {
     setSkillsSummaryXML(xml) {
         this.skillsSummaryXML = xml || '';
     }
+    /** 上一轮 `process` / `processMultimodal` 的 token 等指标（供 AI Handler 打汇总日志） */
+    getLastTurnMetrics() {
+        return this.lastTurnMetrics;
+    }
+    beginActiveTurn() {
+        this.activeTurnSubagentUsage = { ...EMPTY_USAGE };
+        this.activeTurnSubagentWaits = [];
+    }
+    addActiveTurnSubagentUsage(usage) {
+        if (!this.activeTurnSubagentUsage)
+            return;
+        addUsage(this.activeTurnSubagentUsage, usage);
+    }
+    trackActiveTurnSubagent(done) {
+        if (!this.activeTurnSubagentUsage)
+            return;
+        this.activeTurnSubagentWaits.push(done);
+    }
+    async finalizeActiveTurn(partial) {
+        const waitMs = this.config.subagentTurnWaitMs;
+        if (this.activeTurnSubagentWaits.length > 0 && waitMs > 0) {
+            await Promise.race([
+                Promise.allSettled(this.activeTurnSubagentWaits),
+                new Promise(resolve => setTimeout(resolve, waitMs)),
+            ]);
+        }
+        const mainUsage = { ...partial.usage };
+        const subagentUsage = this.activeTurnSubagentUsage
+            && (this.activeTurnSubagentUsage.total_tokens > 0
+                || this.activeTurnSubagentUsage.prompt_tokens > 0
+                || this.activeTurnSubagentUsage.completion_tokens > 0)
+            ? { ...this.activeTurnSubagentUsage }
+            : undefined;
+        const totalUsage = { ...mainUsage };
+        if (subagentUsage)
+            addUsage(totalUsage, subagentUsage);
+        this.lastTurnMetrics = {
+            ...partial,
+            usage: totalUsage,
+            mainUsage,
+            ...(subagentUsage ? { subagentUsage } : {}),
+        };
+        this.activeTurnSubagentUsage = null;
+        this.activeTurnSubagentWaits = [];
+    }
     // ── Core processing ─────────────────────────────────────────────────
     async process(content, context, externalTools = [], onChunk) {
         const t0 = now();
@@ -185,8 +251,10 @@ export class ZhinAgent {
         if (!rateCheck.allowed) {
             this.logPhase('turn.rate_limited', sessionId, { userId });
             logger.debug(`[速率限制] 用户 ${userId} 被限制: ${rateCheck.message}`);
+            await this.finalizeActiveTurn({ usage: EMPTY_USAGE, path: 'rate_limited' });
             return parseOutput(rateCheck.message || '请稍后再试');
         }
+        this.beginActiveTurn();
         // 0.5 工具上下文：web_search 语言（档案 preferred_language / language，否则默认中文）
         const contextForTools = await this.attachWebSearchLocale(context, userId);
         triggerAIHook(createAIHookEvent('message', 'received', sessionId, {
@@ -194,8 +262,13 @@ export class ZhinAgent {
             content,
             platform: platform || '',
         })).catch(() => { });
+        // 0.9 Lazy-connect configured MCP servers before tool collection
+        if (this.orchestrator) {
+            await ensureMcpConnections(this.orchestrator.mcps);
+        }
         // 1. Collect tools
         const tFilter = now();
+        const mcpTools = this.orchestrator?.mcps.getAllMcpTools() ?? [];
         const allTools = collectRuntimeTools({
             content,
             context: contextForTools,
@@ -208,10 +281,17 @@ export class ZhinAgent {
             memory: this.memory,
             userProfiles: this.userProfiles,
             subagentManager: this.subagentManager,
+            mcpTools,
         });
+        const { tools: resolvedTools, deferredStats } = this.resolveAgentToolsForTurn(allTools, contextForTools);
+        this.lastToolSearchDeferredStats = deferredStats;
         const filterMs = (now() - tFilter).toFixed(0);
-        this.logPhase('tools.collected', sessionId, { count: allTools.length });
-        logger.info(`[工具过滤] ${allTools.length} 个工具: ${allTools.map(t => t.name).join(', ') || '(无)'}`);
+        this.logPhase('tools.collected', sessionId, { count: resolvedTools.length });
+        logger.debug(formatCompact({
+            tools: resolvedTools.length,
+            tool_search: this.config.toolSearch || undefined,
+            names: resolvedTools.map(t => t.name).join(',') || '(none)',
+        }));
         // 2. History + profile (parallel)
         const tMem = now();
         const [rawHistoryMessages, profileSummary] = await Promise.all([
@@ -239,16 +319,33 @@ export class ZhinAgent {
             this.logPhase('path.chat', sessionId, { toolCount: 0 });
             const liteModel = this.config.chatLiteModel || undefined;
             const chatSystemPrompt = this.buildDisciplinedPrompt(personaEnhanced);
-            logger.info(`[System Prompt] chat-path: ${chatSystemPrompt.length} chars${liteModel ? `, model=${liteModel}` : ''}`);
-            logger.debug(`[闲聊路径] 过滤=${filterMs}ms, 记忆=${memMs}ms (${historyMessages.length}条), 0 工具`);
+            logger.debug(formatCompact({
+                mode: 'chat',
+                prompt_chars: chatSystemPrompt.length,
+                model: liteModel || chatCandidates[0] || undefined,
+            }));
             const tLLM = now();
             this.logPhase('chat.llm.start', sessionId, { model: liteModel || chatCandidates[0] || '' });
-            let reply = await this.streamChatWithHistory(content, chatSystemPrompt, historyMessages, onChunk, liteModel);
-            reply = stripHallucinatedToolCalls(reply);
+            const chatResult = await this.streamChatWithHistory(content, chatSystemPrompt, historyMessages, onChunk, liteModel);
+            let reply = stripHallucinatedToolCalls(chatResult.content);
             const llmMs = (now() - tLLM).toFixed(0);
-            this.logPhase('chat.llm.end', sessionId, { durationMs: Number(llmMs) });
-            logger.info(`[闲聊路径] 过滤=${filterMs}ms, 记忆=${memMs}ms, LLM=${llmMs}ms, 总=${(now() - t0).toFixed(0)}ms`);
+            this.logPhase('chat.llm.end', sessionId, {
+                durationMs: Number(llmMs),
+                ...this.usageLogFields(chatResult.usage ?? undefined),
+            });
+            logger.debug(formatCompact({
+                mode: 'chat',
+                filter_ms: filterMs,
+                mem_ms: memMs,
+                llm_ms: llmMs,
+                total_ms: Math.round(now() - t0),
+            }));
             await this.saveToSession(sessionId, content, reply, sceneId);
+            await this.finalizeActiveTurn({
+                usage: chatResult.usage ?? EMPTY_USAGE,
+                path: 'chat',
+                model: chatResult.model,
+            });
             this.logPhase('turn.end', sessionId, { path: 'chat' });
             return parseOutput(reply);
         }
@@ -259,7 +356,7 @@ export class ZhinAgent {
         if (preExecCandidates.length > 0) {
             logger.debug(`预执行: ${preExecCandidates.map(t => t.name).join(', ')}`);
         }
-        const toolRun = await planToolRun(allTools, this.config.preExecTimeout);
+        const toolRun = await planToolRun(resolvedTools, this.config.preExecTimeout);
         this.logPhase('preexec.done', sessionId, {
             mode: toolRun.mode,
             preExecutedTools: toolRun.preExecution.tools.length,
@@ -275,30 +372,52 @@ export class ZhinAgent {
             // Fast path
             const tLLM = now();
             const prompt = this.buildDisciplinedPrompt(buildPreExecFastPathPrompt(personaEnhanced, preData));
-            logger.info(`[System Prompt] fast-path: ${prompt.length} chars`);
+            logger.debug(formatCompact({ mode: 'fast', prompt_chars: prompt.length }));
             this.logPhase('fast.llm.start', sessionId, { model: chatCandidates[0] || '' });
-            reply = await this.streamChatWithHistory(content, prompt, historyMessages, onChunk);
-            this.logPhase('fast.llm.end', sessionId, { durationMs: Math.round(now() - tLLM) });
-            logger.info(`[快速路径] 过滤=${filterMs}ms, 记忆=${memMs}ms, LLM=${(now() - tLLM).toFixed(0)}ms, 总=${(now() - t0).toFixed(0)}ms`);
+            const fastResult = await this.streamChatWithHistory(content, prompt, historyMessages, onChunk);
+            reply = fastResult.content;
+            this.logPhase('fast.llm.end', sessionId, {
+                durationMs: Math.round(now() - tLLM),
+                ...this.usageLogFields(fastResult.usage ?? undefined),
+            });
+            logger.debug(`[快速路径] 过滤=${filterMs}ms, 记忆=${memMs}ms, LLM=${(now() - tLLM).toFixed(0)}ms, 总=${(now() - t0).toFixed(0)}ms`);
+            await this.finalizeActiveTurn({
+                usage: fastResult.usage ?? EMPTY_USAGE,
+                path: 'fast',
+                model: fastResult.model,
+            });
         }
         else {
             this.logPhase('path.agent', sessionId, { toolCount: allTools.length });
             const tAgent = now();
             logger.debug(`Agent 路径: ${allTools.length} 个工具`);
             const contextHint = buildContextHint(context, content);
+            const platformMarkdown = await resolveAgentPromptMarkdown({
+                ctx: {
+                    slot: 'orchestrator',
+                    toolContext: context,
+                    toolSearch: !!this.config.toolSearch,
+                    userMessagePreview: content.slice(0, 500),
+                    deferred: deferredStats ? { goal: content, domainStats: deferredStats } : undefined,
+                },
+                config: this.config,
+                sessionId,
+            });
             const richPrompt = buildRichSystemPrompt({
                 config: this.config,
                 skillRegistry: this.skillRegistry,
                 skillsSummaryXML: this.skillsSummaryXML,
                 activeSkillsContext: this.activeSkillsContext,
                 bootstrapContext: this.bootstrapContext,
+                toolSearchDeferredStats: deferredStats,
+                platformSections: platformMarkdown,
             });
             const systemPrompt = `${richPrompt}
 ${contextHint}
 ${preData ? `\nPre-fetched data:\n${preData}\n` : ''}`;
-            logger.info(`[System Prompt] ${systemPrompt.length} chars`);
+            logger.debug(formatCompact({ mode: 'agent', prompt_chars: systemPrompt.length }));
             logger.debug(`[System Prompt Full]\n${systemPrompt}\n---END---`);
-            const agentTools = applyExecPolicyToTools(this.config, allTools);
+            const agentTools = applyExecPolicyToTools(this.config, resolvedTools);
             // Adaptive maxIterations: boost when skills are active (multi-step skill flows)
             const SKILL_ITERATION_BOOST = 3;
             const hasSkillActivation = agentTools.some(t => t.name === 'activate_skill' || t.name === 'install_skill');
@@ -318,7 +437,7 @@ ${preData ? `\nPre-fetched data:\n${preData}\n` : ''}`;
                     orchestrationPlugin = getPlugin().root ?? getPlugin();
                 }
                 catch {
-                    logger.warn('[ZhinAgent] 无 hostPlugin 且 getPlugin() 不可用，Owner 硬编排可能无法自动 ask_user');
+                    logger.warn(formatCompact({ warn: 'no_host_plugin' }));
                 }
             }
             const agent = createAgent(this.provider, {
@@ -342,13 +461,23 @@ ${preData ? `\nPre-fetched data:\n${preData}\n` : ''}`;
             try {
                 this.logPhase('agent.run.start', sessionId, { model: chatCandidates[0] || '' });
                 result = await runWithBashToolContext(contextForTools, () => agent.run(userMessageWithHistory, []));
-                this.logPhase('agent.run.end', sessionId, { iterations: result.iterations });
+                this.logPhase('agent.run.end', sessionId, {
+                    iterations: result.iterations,
+                    durationMs: Math.round(now() - tAgent),
+                    ...this.usageLogFields(result.usage),
+                });
             }
             finally {
                 agent.dispose();
             }
             reply = stripHallucinatedToolCalls(stripThinkBlocks(result.content)) || this.fallbackFormat(result.toolCalls);
-            logger.info(`[Agent 路径] 过滤=${filterMs}ms, 记忆=${memMs}ms, Agent=${(now() - tAgent).toFixed(0)}ms, 总=${(now() - t0).toFixed(0)}ms`);
+            logger.debug(`[Agent 路径] 过滤=${filterMs}ms, 记忆=${memMs}ms, Agent=${(now() - tAgent).toFixed(0)}ms, 总=${(now() - t0).toFixed(0)}ms`);
+            await this.finalizeActiveTurn({
+                usage: result.usage,
+                path: 'agent',
+                iterations: result.iterations,
+                model: chatCandidates[0] || undefined,
+            });
         }
         await this.saveToSession(sessionId, content, reply, sceneId);
         triggerAIHook(createAIHookEvent('message', 'sent', sessionId, {
@@ -359,14 +488,71 @@ ${preData ? `\nPre-fetched data:\n${preData}\n` : ''}`;
         this.logPhase('turn.end', sessionId, { path: toolRun.mode === 'pre-exec-fast-path' ? 'fast' : 'agent' });
         return parseOutput(reply);
     }
+    resolveAgentToolsForTurn(allTools, context) {
+        if (!this.config.toolSearch) {
+            return { tools: allTools };
+        }
+        const toolSearchPool = filterToolsForToolSearchCatalog(allTools);
+        const built = buildOrchestratorAgentTools({
+            allTools: toolSearchPool,
+            config: this.config,
+            context,
+            getDeferredCatalog: () => this.deferredCatalog,
+            runWorker: (goal, toolQuery) => this.runDeferredWorker(goal, toolQuery, context, toolSearchPool),
+        });
+        this.deferredCatalog = built.deferred;
+        logger.debug(formatCompact({
+            tool_search: `${built.orchestratorTools.length}+${built.deferred.length}`,
+            stats: built.domainStats,
+        }));
+        return { tools: built.orchestratorTools, deferredStats: built.domainStats };
+    }
+    async runDeferredWorker(goal, toolQuery, context, allTools) {
+        const allByName = new Map(allTools.map(t => [t.name, t]));
+        const workerBase = [];
+        for (const name of this.config.toolSearchWorkerBaseTools) {
+            const t = allByName.get(name);
+            if (t)
+                workerBase.push(t);
+        }
+        const result = await this.deferredWorkerRunner.runSync({
+            goal,
+            toolQuery,
+            deferredCatalog: this.deferredCatalog,
+            workerBaseTools: workerBase,
+            allToolsByName: allByName,
+            origin: context,
+            maxToolResults: this.config.toolSearchMaxResults,
+            execPolicyConfig: this.config,
+            modelRegistry: this.modelRegistry,
+            provider: this.provider,
+            maxIterations: this.config.maxSubagentIterations,
+        });
+        return result.summary;
+    }
     buildDisciplinedPrompt(basePrompt) {
         const discipline = `# Discipline\n${FIXED_DISCIPLINE_RULES.map(rule => `- ${rule}`).join('\n')}`;
         return `${discipline}\n\n${basePrompt}`;
     }
+    usageLogFields(usage) {
+        if (!usage)
+            return {};
+        return {
+            promptTokens: usage.prompt_tokens,
+            completionTokens: usage.completion_tokens,
+            totalTokens: usage.total_tokens,
+        };
+    }
     logPhase(phase, sessionId, extra = {}) {
         if (!this.phaseTraceEnabled)
             return;
-        logger.info({ phase, sessionId, ...extra }, '[AGENT_PHASE]');
+        const flat = { phase, session: sessionId };
+        for (const [k, v] of Object.entries(extra)) {
+            if (v === undefined || v === null)
+                continue;
+            flat[k] = typeof v === 'object' ? JSON.stringify(v) : v;
+        }
+        logger.info(formatCompact(flat));
     }
     async processMultimodal(parts, context, onChunk) {
         const { senderId, sceneId, platform } = context;
@@ -374,8 +560,10 @@ ${preData ? `\nPre-fetched data:\n${preData}\n` : ''}`;
         const userId = senderId || 'unknown';
         const rateCheck = this.rateLimiter.check(userId);
         if (!rateCheck.allowed) {
+            await this.finalizeActiveTurn({ usage: EMPTY_USAGE, path: 'rate_limited' });
             return parseOutput(rateCheck.message || '请稍后再试');
         }
+        this.beginActiveTurn();
         const rawHistoryMessages = await this.buildHistoryMessages(sessionId);
         const profileSummary = await this.userProfiles.buildProfileSummary(userId);
         const personaEnhanced = this.buildDisciplinedPrompt(buildEnhancedPersona(this.config, profileSummary, ''));
@@ -408,6 +596,17 @@ ${preData ? `\nPre-fetched data:\n${preData}\n` : ''}`;
             }
         }
         const textContent = textFragments.join(' ') || '[多模态消息]';
+        const platformMarkdown = await resolveAgentPromptMarkdown({
+            ctx: {
+                slot: 'orchestrator',
+                toolContext: context,
+                toolSearch: !!this.config.toolSearch,
+                userMessagePreview: textContent.slice(0, 500),
+            },
+            config: this.config,
+            sessionId,
+        });
+        const visionSystemPrompt = buildLiteSystemPromptWithPlatform(personaEnhanced, platformMarkdown, buildContextHint(context, textContent));
         const visionCandidates = this.resolveModelCandidates('vision');
         const { messages: historyMessages, result: pruneResult } = pruneHistoryWithBudget({
             messages: rawHistoryMessages,
@@ -420,16 +619,21 @@ ${preData ? `\nPre-fetched data:\n${preData}\n` : ''}`;
             logger.debug(`[多模态上下文窗口] 丢弃 ${pruneResult.droppedCount} 条历史消息 (${pruneResult.droppedTokens} tokens)`);
         }
         const messages = [
-            { role: 'system', content: personaEnhanced },
+            { role: 'system', content: visionSystemPrompt },
             ...historyMessages,
             { role: 'user', content: llmParts },
         ];
         let reply = '';
+        let lastUsage = null;
+        let usedVisionModel = visionCandidates[0] || '';
         for (let i = 0; i < visionCandidates.length; i++) {
             const visionModel = visionCandidates[i];
+            usedVisionModel = visionModel;
             try {
                 reply = '';
                 for await (const chunk of this.provider.chatStream({ model: visionModel, messages })) {
+                    if (chunk.usage)
+                        lastUsage = chunk.usage;
                     const delta = chunk.choices?.[0]?.delta;
                     if (!delta)
                         continue;
@@ -442,8 +646,10 @@ ${preData ? `\nPre-fetched data:\n${preData}\n` : ''}`;
                 }
                 reply = stripThinkBlocks(reply);
                 if (!reply) {
-                    logger.warn(`[processMultimodal] ${visionModel} 流式为空，尝试非流式`);
+                    logger.warn(formatCompact({ mode: 'multimodal', fallback: visionModel, reason: 'empty_stream' }));
                     const response = await this.provider.chat({ model: visionModel, messages });
+                    if (response.usage)
+                        lastUsage = response.usage;
                     const msg = response.choices[0]?.message?.content;
                     reply = stripThinkBlocks(typeof msg === 'string' ? msg : '');
                 }
@@ -455,13 +661,19 @@ ${preData ? `\nPre-fetched data:\n${preData}\n` : ''}`;
                 if (isLast) {
                     try {
                         const response = await this.provider.chat({ model: visionModel, messages });
+                        if (response.usage)
+                            lastUsage = response.usage;
                         const msg = response.choices[0]?.message?.content;
                         reply = stripThinkBlocks(typeof msg === 'string' ? msg : '');
                     }
                     catch { /* all candidates exhausted */ }
                 }
                 else {
-                    logger.warn(`[processMultimodal] ${visionModel} 失败，降级到 ${visionCandidates[i + 1]}: ${err.message}`);
+                    logger.warn(formatCompact({
+                        mode: 'multimodal',
+                        fallback: `${visionModel}→${visionCandidates[i + 1]}`,
+                        error: truncatePreview(err.message, 80),
+                    }));
                 }
             }
         }
@@ -469,6 +681,11 @@ ${preData ? `\nPre-fetched data:\n${preData}\n` : ''}`;
             reply = '抱歉，我无法理解这条消息。';
         reply = stripHallucinatedToolCalls(reply);
         await this.saveToSession(sessionId, textContent, reply, sceneId);
+        await this.finalizeActiveTurn({
+            usage: lastUsage ?? EMPTY_USAGE,
+            path: 'multimodal',
+            model: usedVisionModel,
+        });
         return parseOutput(reply);
     }
     // ── Internal helpers ────────────────────────────────────────────────
@@ -500,6 +717,7 @@ ${preData ? `\nPre-fetched data:\n${preData}\n` : ''}`;
     }
     async streamChatWithHistory(content, systemPrompt, history, onChunk, preferredModel) {
         const candidates = this.resolveModelCandidates('chat', preferredModel);
+        const empty = (model) => ({ content: '', usage: null, model });
         const turnTimeout = this.config.timeout;
         const userContent = history.length > 0
             ? buildUserMessageWithHistory(history, content)
@@ -535,21 +753,19 @@ ${preData ? `\nPre-fetched data:\n${preData}\n` : ''}`;
                         }
                     }
                 })());
-                if (lastUsage) {
-                    logger.info(`[闲聊] token 用量: prompt=${lastUsage.prompt_tokens}, completion=${lastUsage.completion_tokens}, total=${lastUsage.total_tokens} (model=${model})`);
-                }
                 result = stripThinkBlocks(result);
-                if (result)
-                    return result;
+                if (result) {
+                    return { content: result, usage: lastUsage, model };
+                }
                 // Streaming returned empty content — try non-streaming with same model
-                logger.warn(`[streamChat] ${model} 流式响应为空，尝试非流式`);
+                logger.warn(formatCompact({ stream: 'empty', model }));
                 const response = await withTurnTimeout(this.provider.chat({ model, messages }));
                 const msg = response.choices?.[0]?.message?.content;
                 result = stripThinkBlocks(typeof msg === 'string' ? msg : '');
                 if (result) {
                     if (onChunk)
                         onChunk(result, result);
-                    return result;
+                    return { content: result, usage: response.usage ?? null, model };
                 }
             }
             catch (err) {
@@ -562,16 +778,22 @@ ${preData ? `\nPre-fetched data:\n${preData}\n` : ''}`;
                         let result = stripThinkBlocks(typeof msg === 'string' ? msg : '');
                         if (onChunk && result)
                             onChunk(result, result);
-                        return result;
+                        if (result) {
+                            return { content: result, usage: response.usage ?? null, model };
+                        }
+                        return empty(model);
                     }
                     catch {
-                        return '';
+                        return empty(model);
                     }
                 }
-                logger.warn(`[streamChat] ${model} 失败，降级到 ${candidates[i + 1]}: ${err.message}`);
+                logger.warn(formatCompact({
+                    fallback: `${model}→${candidates[i + 1]}`,
+                    error: truncatePreview(err.message, 80),
+                }));
             }
         }
-        return '';
+        return empty(candidates[0] || '');
     }
     async saveToSession(sessionId, userContent, assistantContent, sceneId) {
         await this.memory.saveRound(sessionId, userContent, assistantContent);