@zhin.js/agent 0.1.25 → 0.1.26

package/lib/zhin-agent/index.js

@@ -15,39 +15,25 @@
  *  11. 定时任务：cron_add 持久化定时任务
  *  12. 多模态输入：图片/音频直接传给视觉模型
  */
-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 { Logger } from '@zhin.js/logger';
 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 { TurnTracker } from './turn-tracker.js';
+import { ZhinAgentEventEmitter } from './event-emitter.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, 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 { sanitizeAssistantReply, stripThinkBlocks } from './text-sanitize.js';
-import { formatToolCallsForUser } from './tool-calls-user-format.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';
+import { processTextTurn, processMultimodalTurn } from './turn-pipeline.js';
+import { asPrivate } from './zhin-agent-private.js';
+import { buildDisciplinedPrompt as assembleDisciplinedPrompt } from './prompt-assembly.js';
+import { resolveAgentToolsForTurn as resolveToolsForTurn, runDeferredWorker as runDeferredWorkerTurn, } from './tool-orchestration.js';
 export { formatAiHandlerCompleteLog, formatZhinAgentTurnUsage } from './turn-metrics.js';
+export * from './prompt-builder.js';
+export * from './prompt-templates.js';
+export * from './task-continuation.js';
 const logger = new Logger(null, 'ZhinAgent');
-const now = () => performance.now();
 // ============================================================================
 // ZhinAgent
 // ============================================================================
@@ -68,14 +54,14 @@ export class ZhinAgent {
     skillsSummaryXML = '';
     modelRegistry = null;
     phaseTraceEnabled;
-    /** 根插件（createZhinAgentContext 注入）；避免在 Agent.run 路径依赖 AsyncLocalStorage 上的 getPlugin() */
-    hostPlugin = null;
+    emitter = new ZhinAgentEventEmitter();
     deferredCatalog = [];
     deferredWorkerRunner = new DeferredWorkerRunner();
     lastToolSearchDeferredStats;
-    lastTurnMetrics = null;
-    activeTurnSubagentUsage = null;
-    activeTurnSubagentWaits = [];
+    turnTracker;
+    get phaseConfig() {
+        return { phaseTraceEnabled: this.phaseTraceEnabled, onPhaseTrace: this.config.onPhaseTrace };
+    }
     constructor(provider, config) {
         this.provider = provider;
         this.config = { ...DEFAULT_CONFIG, ...config };
@@ -90,6 +76,7 @@ export class ZhinAgent {
         this.memory.setProvider(provider);
         this.userProfiles = new UserProfileStore();
         this.rateLimiter = new RateLimiter(this.config.rateLimit);
+        this.turnTracker = new TurnTracker(this.config.subagentTurnWaitMs);
     }
     // ── DI setters ──────────────────────────────────────────────────────
     setSkillRegistry(registry) {
@@ -112,9 +99,8 @@ export class ZhinAgent {
         this.modelRegistry = registry;
         this.subagentManager?.setModelRegistry(registry);
     }
-    /** 由 init 注入根插件，供 Owner 编排 / ask_user（勿依赖消息处理时的 getPlugin ALS） */
     setHostPlugin(plugin) {
-        this.hostPlugin = plugin.root ?? plugin;
+        this.emitter.setHostPlugin(plugin);
     }
     upgradeMemoryToDatabase(msgModel, sumModel) {
         this.memory.upgradeToDatabase(msgModel, sumModel);
@@ -131,8 +117,35 @@ export class ZhinAgent {
             maxIterations: this.config.maxSubagentIterations,
             execPolicyConfig: this.config,
             modelRegistry: this.modelRegistry,
-            onSubagentUsage: (usage) => this.addActiveTurnSubagentUsage(usage),
-            registerSubagentTask: (done) => this.trackActiveTurnSubagent(done),
+            onSubagentUsage: (usage) => this.turnTracker.addSubagentUsage(usage),
+            registerSubagentTask: (done) => this.turnTracker.trackSubagent(done),
+            onEvent: (event) => {
+                const sessionId = SessionManager.generateId(event.origin.platform || '', event.origin.senderId || '', event.origin.sceneId);
+                const payload = this.emitter.createPayload(sessionId, {
+                    platform: event.origin.platform,
+                    botId: event.origin.botId,
+                    sceneId: event.origin.sceneId,
+                    senderId: event.origin.senderId,
+                    scope: event.origin.sceneType === 'group' ? 'group' : 'private',
+                }, 'text', {
+                    path: 'agent',
+                    taskId: event.taskId,
+                    label: event.label,
+                    content: event.task,
+                    status: event.status,
+                    error: event.error,
+                    reply: event.result,
+                });
+                if (event.phase === 'spawn') {
+                    this.emitter.emit('ai.subagent.spawn', payload);
+                }
+                else if (event.phase === 'start') {
+                    this.emitter.emit('ai.subagent.start', payload);
+                }
+                else {
+                    this.emitter.emit('ai.subagent.finish', payload);
+                }
+            },
         });
         logger.debug('SubagentManager initialized');
     }
@@ -147,38 +160,6 @@ export class ZhinAgent {
     getUserProfiles() {
         return this.userProfiles;
     }
-    /** 根据任务类型选择最合适的模型，优先使用 config 显式指定，其次 ModelRegistry，回退到 provider.models[0] */
-    resolveModel(task = 'chat', preferred) {
-        return this.resolveModelCandidates(task, preferred)[0];
-    }
-    /**
-     * 返回按优先级排序的候选模型列表（用于自动降级）。
-     * 第一个是最优选择，失败后依次尝试后续模型。
-     */
-    resolveModelCandidates(task = 'chat', preferred) {
-        const candidates = [];
-        // 1. 用户显式指定 / 配置指定优先
-        if (preferred)
-            candidates.push(preferred);
-        if (task === 'chat' && this.config.chatModel && !candidates.includes(this.config.chatModel)) {
-            candidates.push(this.config.chatModel);
-        }
-        if (task === 'vision' && this.config.visionModel && !candidates.includes(this.config.visionModel)) {
-            candidates.push(this.config.visionModel);
-        }
-        // 2. ModelRegistry 自动排序的候选列表
-        if (this.modelRegistry) {
-            for (const id of this.modelRegistry.selectModels(this.provider.name, task, 5)) {
-                if (!candidates.includes(id))
-                    candidates.push(id);
-            }
-        }
-        // 3. 兜底: provider.models[0]
-        const fallback = this.provider.models[0];
-        if (fallback && !candidates.includes(fallback))
-            candidates.push(fallback);
-        return candidates;
-    }
     registerTool(tool) {
         this.externalTools.set(tool.name, tool);
         return () => { this.externalTools.delete(tool.name); };
@@ -193,632 +174,49 @@ export class ZhinAgent {
     setSkillsSummaryXML(xml) {
         this.skillsSummaryXML = xml || '';
     }
-    /** 上一轮 `process` / `processMultimodal` 的 token 等指标（供 AI Handler 打汇总日志） */
     getLastTurnMetrics() {
-        return this.lastTurnMetrics;
+        return this.turnTracker.lastMetrics;
     }
     beginActiveTurn() {
-        this.activeTurnSubagentUsage = { ...EMPTY_USAGE };
-        this.activeTurnSubagentWaits = [];
+        this.turnTracker.begin();
     }
-    addActiveTurnSubagentUsage(usage) {
-        if (!this.activeTurnSubagentUsage)
-            return;
-        addUsage(this.activeTurnSubagentUsage, usage);
+    async finalizeActiveTurn(partial) {
+        await this.turnTracker.finalize(partial);
     }
-    trackActiveTurnSubagent(done) {
-        if (!this.activeTurnSubagentUsage)
-            return;
-        this.activeTurnSubagentWaits.push(done);
+    emitSessionNewEvent(sessionId, context, mode, content, reply) {
+        this.emitter.emit('ai.session.new', this.emitter.createPayload(sessionId, context, mode, {
+            reason: 'first_message',
+            content,
+            reply,
+        }));
     }
-    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 = [];
+    emitSessionCompactEvent(sessionId, context, mode, info) {
+        this.emitter.emit('ai.session.compact', this.emitter.createPayload(sessionId, context, mode, {
+            path: 'agent',
+            compactedCount: 1,
+            savedTokens: info.microSavedTokens + info.autoSavedTokens,
+            totalTokensBefore: info.totalTokensBefore,
+            totalTokensAfter: info.totalTokensAfter,
+            result: info,
+        }));
     }
     // ── Core processing ─────────────────────────────────────────────────
     async process(content, context, externalTools = [], onChunk) {
-        const t0 = now();
-        const { senderId, sceneId, platform } = context;
-        const sessionId = SessionManager.generateId(platform || '', senderId || '', sceneId);
-        const userId = senderId || 'unknown';
-        this.logPhase('turn.start', sessionId, {
-            mode: 'text',
-            provider: this.provider.name,
-        });
-        // 0. Rate limit
-        const rateCheck = this.rateLimiter.check(userId);
-        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, {
-            userId,
-            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,
-            externalTools,
-            config: this.config,
-            skillRegistry: this.skillRegistry,
-            externalRegistered: this.externalTools,
-            sessionId,
-            userId,
-            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: 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([
-            this.buildHistoryMessages(sessionId),
-            this.userProfiles.buildProfileSummary(userId),
-        ]);
-        const chatCandidates = this.resolveModelCandidates('chat');
-        const { messages: historyMessages, result: pruneResult, budget: contextBudget, } = pruneHistoryWithBudget({
-            messages: rawHistoryMessages,
-            config: this.config,
-            provider: this.provider,
-            modelRegistry: this.modelRegistry,
-            model: chatCandidates[0],
-        });
-        if (pruneResult.droppedCount > 0) {
-            logger.debug(`[上下文窗口] 丢弃 ${pruneResult.droppedCount} 条历史消息 (${pruneResult.droppedTokens} tokens)`);
-        }
-        const memMs = (now() - tMem).toFixed(0);
-        this.logPhase('context.ready', sessionId, { historyCount: historyMessages.length });
-        // 2.5 Tone + persona
-        const toneHint = this.config.toneAwareness ? detectTone(content).hint : '';
-        const personaEnhanced = buildEnhancedPersona(this.config, profileSummary, toneHint);
-        // 3. No tools → chat path (prefer per-session model, then lightweight model)
-        if (allTools.length === 0) {
-            this.logPhase('path.chat', sessionId, { toolCount: 0 });
-            const liteModel = this.config.chatLiteModel || undefined;
-            const chatSystemPrompt = this.buildDisciplinedPrompt(personaEnhanced);
-            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] || '' });
-            const chatResult = await this.streamChatWithHistory(content, chatSystemPrompt, historyMessages, onChunk, liteModel);
-            let reply = sanitizeAssistantReply(chatResult.content);
-            const llmMs = (now() - tLLM).toFixed(0);
-            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);
-        }
-        logger.debug(`[工具路径] 过滤=${filterMs}ms, 记忆=${memMs}ms, ${allTools.length} 工具 (${allTools.map(t => t.name).join(', ')})`);
-        // 4. Pre-executable tools
-        const preExecCandidates = allTools.filter(tool => tool.preExecutable);
-        const tPre = preExecCandidates.length > 0 ? now() : 0;
-        if (preExecCandidates.length > 0) {
-            logger.debug(`预执行: ${preExecCandidates.map(t => t.name).join(', ')}`);
-        }
-        const toolRun = await planToolRun(resolvedTools, this.config.preExecTimeout);
-        this.logPhase('preexec.done', sessionId, {
-            mode: toolRun.mode,
-            preExecutedTools: toolRun.preExecution.tools.length,
-        });
-        const preData = toolRun.preExecution.data;
-        if (tPre > 0) {
-            logger.debug(`预执行耗时: ${(now() - tPre).toFixed(0)}ms`);
-        }
-        // 6. Path selection
-        let reply;
-        if (toolRun.mode === 'pre-exec-fast-path') {
-            this.logPhase('path.pre_exec_fast', sessionId, { toolCount: allTools.length });
-            // Fast path
-            const tLLM = now();
-            const prompt = this.buildDisciplinedPrompt(buildPreExecFastPathPrompt(personaEnhanced, preData));
-            logger.debug(formatCompact({ mode: 'fast', prompt_chars: prompt.length }));
-            this.logPhase('fast.llm.start', sessionId, { model: chatCandidates[0] || '' });
-            const fastResult = await this.streamChatWithHistory(content, prompt, historyMessages, onChunk);
-            reply = sanitizeAssistantReply(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.debug(formatCompact({ mode: 'agent', prompt_chars: systemPrompt.length }));
-            logger.debug(`[System Prompt Full]\n${systemPrompt}\n---END---`);
-            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');
-            const harness = resolveModelHarness(this.provider.name, chatCandidates[0] || '', this.config.modelHarness);
-            const baseIterations = harness.maxIterations ?? this.config.maxIterations;
-            const effectiveMaxIterations = hasSkillActivation
-                ? baseIterations + SKILL_ITERATION_BOOST
-                : baseIterations;
-            this.logPhase('harness.resolved', sessionId, {
-                model: chatCandidates[0] || '',
-                harnessMaxIterations: harness.maxIterations ?? null,
-                effectiveMaxIterations,
-            });
-            let orchestrationPlugin = this.hostPlugin ?? undefined;
-            if (!orchestrationPlugin) {
-                try {
-                    orchestrationPlugin = getPlugin().root ?? getPlugin();
-                }
-                catch {
-                    logger.warn(formatCompact({ warn: 'no_host_plugin' }));
-                }
-            }
-            const agent = createAgent(this.provider, {
-                model: chatCandidates[0],
-                modelFallbacks: chatCandidates.slice(1),
-                systemPrompt,
-                tools: agentTools,
-                maxIterations: effectiveMaxIterations,
-                turnTimeout: this.config.timeout,
-                contextWindow: contextBudget.contextWindow,
-                reservedToolNames: RESERVED_TOOL_NAMES,
-                reservedToolNamePrefixes: RESERVED_TOOL_NAME_PREFIXES,
-                transformToolResult: createOwnerOrchestratedToolResultTransform({
-                    toolContext: contextForTools,
-                    disableHardOrchestration: false,
-                    plugin: orchestrationPlugin,
-                }),
-            });
-            const userMessageWithHistory = buildUserMessageWithHistory(historyMessages, content);
-            let result;
-            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,
-                    durationMs: Math.round(now() - tAgent),
-                    ...this.usageLogFields(result.usage),
-                });
-            }
-            finally {
-                agent.dispose();
-            }
-            reply = sanitizeAssistantReply(result.content, {
-                toolSummary: formatToolCallsForUser(result.toolCalls),
-            });
-            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: result.model ?? (chatCandidates[0] || undefined),
-            });
-        }
-        await this.saveToSession(sessionId, content, reply, sceneId);
-        triggerAIHook(createAIHookEvent('message', 'sent', sessionId, {
-            userId,
-            content: reply,
-            platform: platform || '',
-        })).catch(() => { });
-        this.logPhase('turn.end', sessionId, { path: toolRun.mode === 'pre-exec-fast-path' ? 'fast' : 'agent' });
-        return parseOutput(reply);
+        return processTextTurn(asPrivate(this), content, context, externalTools, onChunk);
     }
     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 };
+        return resolveToolsForTurn(asPrivate(this), allTools, context);
     }
     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;
+        return runDeferredWorkerTurn(asPrivate(this), goal, toolQuery, context, allTools);
     }
     buildDisciplinedPrompt(basePrompt) {
-        const guidance = [
-            '# Style',
-            '- Lead with the answer or result.',
-            '- Be concise, direct, and useful.',
-            '',
-            '# Safety',
-            ...FIXED_DISCIPLINE_RULES.map(rule => `- ${rule}`),
-        ].join('\n');
-        return `${basePrompt}\n\n${guidance}`;
-    }
-    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;
-        this.config.onPhaseTrace?.({ phase, sessionId, extra });
-        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));
+        return assembleDisciplinedPrompt(asPrivate(this), basePrompt);
     }
     async processMultimodal(parts, context, onChunk) {
-        const { senderId, sceneId, platform } = context;
-        const sessionId = SessionManager.generateId(platform || '', senderId || '', sceneId);
-        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, ''));
-        // Build text summary describing the multimodal content
-        const textFragments = [];
-        const llmParts = [];
-        for (const p of parts) {
-            switch (p.type) {
-                case 'text':
-                    textFragments.push(p.text);
-                    llmParts.push(p);
-                    break;
-                case 'image_url':
-                    textFragments.push('[图片]');
-                    llmParts.push(p);
-                    break;
-                case 'video_url':
-                    textFragments.push('[视频]');
-                    // Most LLMs don't support video natively; describe it as a URL for context
-                    llmParts.push({ type: 'text', text: `[用户发送了一个视频: ${p.video_url.url}]` });
-                    break;
-                case 'audio':
-                    textFragments.push('[音频]');
-                    llmParts.push(p);
-                    break;
-                case 'face':
-                    textFragments.push(p.face.text || `[表情:${p.face.id}]`);
-                    llmParts.push({ type: 'text', text: p.face.text ? `[表情: ${p.face.text}]` : `[表情ID: ${p.face.id}]` });
-                    break;
-            }
-        }
-        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,
-            config: this.config,
-            provider: this.provider,
-            modelRegistry: this.modelRegistry,
-            model: visionCandidates[0],
-        });
-        if (pruneResult.droppedCount > 0) {
-            logger.debug(`[多模态上下文窗口] 丢弃 ${pruneResult.droppedCount} 条历史消息 (${pruneResult.droppedTokens} tokens)`);
-        }
-        const messages = [
-            { 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;
-                    const text = typeof delta.content === 'string' ? delta.content : '';
-                    if (text) {
-                        reply += text;
-                        if (onChunk)
-                            onChunk(text, reply);
-                    }
-                }
-                reply = stripThinkBlocks(reply);
-                if (!reply) {
-                    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 : '');
-                }
-                if (reply)
-                    break; // 成功，退出循环
-            }
-            catch (err) {
-                const isLast = i === visionCandidates.length - 1;
-                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(formatCompact({
-                        mode: 'multimodal',
-                        fallback: `${visionModel}→${visionCandidates[i + 1]}`,
-                        error: truncatePreview(err.message),
-                    }));
-                }
-            }
-        }
-        if (!reply)
-            reply = '抱歉，我无法理解这条消息。';
-        reply = sanitizeAssistantReply(reply);
-        await this.saveToSession(sessionId, textContent, reply, sceneId);
-        await this.finalizeActiveTurn({
-            usage: lastUsage ?? EMPTY_USAGE,
-            path: 'multimodal',
-            model: usedVisionModel,
-        });
-        return parseOutput(reply);
+        return processMultimodalTurn(asPrivate(this), parts, context, onChunk);
     }
     // ── Internal helpers ────────────────────────────────────────────────
-    /**
-     * 为内置工具注入 `extra.web_search_locale`：
-     * - 若调用方已在 `context.extra.web_search_locale` 中设置，则规范化后沿用；
-     * - 否则读取用户档案 `preferred_language` / `language`；
-     * - 均未设置时不在 extra 中写入，web_search 默认使用中文市场。
-     */
-    async attachWebSearchLocale(context, userId) {
-        const extra = { ...(context.extra ?? {}) };
-        const existing = extra[WEB_SEARCH_LOCALE_EXTRA_KEY];
-        if (typeof existing === 'string' && existing.trim()) {
-            extra[WEB_SEARCH_LOCALE_EXTRA_KEY] = normalizeWebSearchLocaleHint(existing);
-            return { ...context, extra };
-        }
-        const [preferred, language] = await Promise.all([
-            this.userProfiles.get(userId, 'preferred_language'),
-            this.userProfiles.get(userId, 'language'),
-        ]);
-        const hint = (preferred ?? language)?.trim();
-        if (hint) {
-            extra[WEB_SEARCH_LOCALE_EXTRA_KEY] = normalizeWebSearchLocaleHint(hint);
-        }
-        return { ...context, extra };
-    }
-    async buildHistoryMessages(sessionId) {
-        return this.memory.buildContext(sessionId);
-    }
-    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)
-            : content;
-        const messages = [
-            { role: 'system', content: systemPrompt },
-            { role: 'user', content: userContent },
-        ];
-        const withTurnTimeout = (promise) => turnTimeout
-            ? Promise.race([
-                promise,
-                new Promise((_, rej) => setTimeout(() => rej(new Error(`LLM 单轮响应超时 (${turnTimeout}ms)`)), turnTimeout)),
-            ])
-            : promise;
-        for (let i = 0; i < candidates.length; i++) {
-            const model = candidates[i];
-            try {
-                let result = '';
-                let lastUsage = null;
-                // 对整个流式消费过程应用超时
-                await withTurnTimeout((async () => {
-                    for await (const chunk of this.provider.chatStream({ model, messages })) {
-                        if (chunk.usage)
-                            lastUsage = chunk.usage;
-                        const delta = chunk.choices?.[0]?.delta;
-                        if (!delta)
-                            continue;
-                        const text = typeof delta.content === 'string' ? delta.content : '';
-                        if (text) {
-                            result += text;
-                            if (onChunk)
-                                onChunk(text, result);
-                        }
-                    }
-                })());
-                result = stripThinkBlocks(result);
-                if (result) {
-                    return { content: result, usage: lastUsage, model };
-                }
-                // Streaming returned empty content — try non-streaming with same 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 { content: result, usage: response.usage ?? null, model };
-                }
-            }
-            catch (err) {
-                const isLast = i === candidates.length - 1;
-                if (isLast) {
-                    // No more candidates — try non-streaming as final attempt
-                    try {
-                        const response = await withTurnTimeout(this.provider.chat({ model, messages }));
-                        const msg = response.choices?.[0]?.message?.content;
-                        let result = stripThinkBlocks(typeof msg === 'string' ? msg : '');
-                        if (onChunk && result)
-                            onChunk(result, result);
-                        if (result) {
-                            return { content: result, usage: response.usage ?? null, model };
-                        }
-                        return empty(model);
-                    }
-                    catch {
-                        return empty(model);
-                    }
-                }
-                logger.warn(formatCompact({
-                    fallback: `${model}→${candidates[i + 1]}`,
-                    error: truncatePreview(err.message),
-                }));
-            }
-        }
-        return empty(candidates[0] || '');
-    }
-    async saveToSession(sessionId, userContent, assistantContent, sceneId) {
-        await this.memory.saveRound(sessionId, userContent, assistantContent);
-        await this.sessions.addMessage(sessionId, { role: 'user', content: userContent });
-        await this.sessions.addMessage(sessionId, { role: 'assistant', content: assistantContent });
-        if (this.contextManager && sceneId) {
-            this.contextManager.autoSummarizeIfNeeded(sceneId).catch(() => { });
-        }
-    }
-    /** @deprecated 使用 {@link formatToolCallsForUser} */
-    fallbackFormat(toolCalls) {
-        return formatToolCallsForUser(toolCalls);
-    }
     // ── Lifecycle ───────────────────────────────────────────────────────
     isReady() {
         return true;