minimal-agent 0.8.2 → 0.10.0

package/src/tools/advisor/advisor.js

@@ -0,0 +1,379 @@
+/**
+ * ============================================================
+ *  src/tools/advisor/advisor.ts —— Advisor 工具（顾问模型第二意见）
+ * ------------------------------------------------------------
+ *  独立配置的第二个 LLM，供主循环的模型在关键判断点
+ *  （方案/诊断成型前、卡住时、收尾汇报前——具体见 CORE_IDENTITY 的"顾问咨询
+ *  原则"）主动调用，拿到一个不同模型的第二意见。
+ *
+ *  设计要点（吸收自 Claude Code 官方 /advisor 的架构，但按 minimal-agent
+ *  的实际约束做了取舍——不照搬服务端单请求内编排/模型分级/加密返回等
+ *  与我们架构无关的部分，见设计计划）：
+ *    - 输入 schema 几乎为空（只有可选的 note）：模型调用前自己写的方案/
+ *      诊断文字，早就随 assistant 消息 push 进了 history，顾问能从
+ *      ctx.history 里直接看到，不需要模型重复手填一段结构化 question。
+ *    - 顾问自己独立的 persona system prompt，与主 provider 的五层提示词
+ *      完全无关。
+ *    - 顾问不给工具权限，只做单轮只读推理（tools: []）——避免变成一个
+ *      带自己循环的子 agent，那是远比"第二意见"更大的功能。
+ *    - 未配置 / 被 /advisor off 关闭 / 调用报错，全部走 ToolResult 的
+ *      ok:false 路径——这条路径本来就有成熟的"错误喂回 LLM 自行判断"
+ *      机制，loop.ts 不需要为此新增任何代码。
+ * ============================================================
+ */
+import { z } from 'zod';
+import { configService } from '../../config/configService.js';
+import { countMessagesTokens } from '../../context/tokenCounter.js';
+import { chat } from '../../llm/client.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
+// ---------------- 1. Zod 输入 schema ----------------
+const inputSchema = z.object({
+    note: z
+        .string()
+        .max(2000, 'note 太长（>2000 字）')
+        .optional()
+        .describe('可选。大多数情况下不需要填——你此前说过的方案/诊断已经在会话历史里，顾问会自动看到。' +
+        '只有需要额外强调、历史里没体现的点时才填一句话。'),
+});
+const parameters = toToolParameters(inputSchema);
+// ---------------- 2. Description（给 LLM 看的工具说明） ----------------
+const description = `- Consults an independent, separately-configured second LLM ("顾问模型" / advisor) for a second opinion on your current plan, diagnosis, or progress.
+- Call with no arguments in most cases — the advisor receives a bounded, relevant view of the current session (the original request, recent discussion, current plan/diagnosis, and key tool results). Only pass \`note\` if something important is not otherwise clear.
+- Exception: if your current plan/diagnosis relies on things you saw in images (screenshots, photos, diagrams), summarize the key visual facts in \`note\` in 1-2 sentences (what each image shows and what you concluded from it) — the advisor may not be able to see the images themselves, and any visual judgment you never wrote down as text does not exist for it.
+- Call this: (1) after a plan/diagnosis has taken shape but before you commit to it (write code, declare a conclusion); (2) when you're stuck — the same error keeps recurring, your fixes aren't converging, or the user has pushed back and you're reconsidering direction; (3) before declaring a multi-step task complete and reporting back to the user.
+- The advisor has no tool access and does a single read-only pass over the transcript — it cannot verify anything itself, only reason about what it's shown.
+- If this tool errors (advisor not configured in shared settings, disabled, manual-only, or a call failure), that's not a signal to stop — treat it as "no second opinion available this time" and continue with your own judgment. Do not block or retry in a loop.`;
+// ---------------- 3. 顾问 persona system prompt ----------------
+const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技术顾问，为正在独立执行任务的另一个 AI 助手提供第二意见评审。
+你的职责：技术方案评估、代码评审、疑难问题的根因定位与解决方向判断。
+
+你会看到该助手当前会话的完整历史——包括用户最初的需求、双方历次交流、以及它已经做过的工具调用
+与执行结果，以及它现在想让你重点关注的内容（如果有）。
+
+审视时请做到：
+- 像资深工程师做方案评审/代码评审一样直接、具体——发现问题就明说，不要无条件附和或说套话。
+- 优先检查：方案是否遗漏了风险或边界情况、诊断是否真的找到了根因还是只是让症状消失、
+  是否存在更简单或更稳妥的替代方向。
+- 结论必须基于你在历史记录里看到的实际证据，不要脱离上下文给泛泛的通用建议。
+- 篇幅精炼：只讲最关键的 1-3 点，不要复述历史、不要客套开场白。`;
+// ---------------- 4. 消息构造（纯函数，单独导出可测） ----------------
+/**
+ * 把主循环的 history 转成喂给顾问模型的 messages。
+ *
+ * 过滤掉所有 role==='system' 的消息——同时去掉了 minimal-agent 自己的系统提示词
+ * 和 TUI 的 ephemeral 提示消息（两者都是 role:'system'），换成顾问自己的 persona。
+ */
+const MAX_TOOL_RESULT_CHARS = 12_000;
+function truncateMiddle(value, limit = MAX_TOOL_RESULT_CHARS) {
+    if (value.length <= limit)
+        return value;
+    const half = Math.floor((limit - 100) / 2);
+    return `${value.slice(0, half)}\n\n[... 顾问上下文已省略 ${value.length - half * 2} 个字符 ...]\n\n${value.slice(-half)}`;
+}
+function redactSensitiveText(value, secrets) {
+    let output = value;
+    for (const secret of secrets) {
+        if (secret.length >= 6)
+            output = output.split(secret).join('[REDACTED]');
+    }
+    return output
+        .replace(/\b(sk-[A-Za-z0-9._-]{12,}|tvly-[A-Za-z0-9._-]{12,})\b/g, '[REDACTED]')
+        .replace(/((?:api[_-]?key|token|secret|password)\s*[:=]\s*)[^\s,;]+/gi, '$1[REDACTED]');
+}
+function redactAdvisorHistory(history, secrets) {
+    return history.map((message) => {
+        if (message.role === 'user') {
+            const content = typeof message.content === 'string'
+                ? redactSensitiveText(message.content, secrets)
+                : message.content.map((part) => part.type === 'text'
+                    ? { ...part, text: redactSensitiveText(part.text, secrets) }
+                    : part);
+            return { ...message, content };
+        }
+        if (message.role === 'assistant')
+            return {
+                ...message,
+                content: message.content ? redactSensitiveText(message.content, secrets) : message.content,
+                tool_calls: message.tool_calls?.map((call) => ({
+                    ...call,
+                    function: { ...call.function, arguments: redactSensitiveText(call.function.arguments, secrets) },
+                })),
+            };
+        return { ...message, content: redactSensitiveText(message.content, secrets) };
+    });
+}
+const MAX_ADVISOR_IMAGES = 4;
+const MAX_ADVISOR_IMAGE_BYTES = 8 * 1024 * 1024;
+function contentForAdvisor(message, supportsVision, allowImages, imageBudget) {
+    if (!Array.isArray(message.content))
+        return truncateMiddle(message.content ?? '');
+    const parts = message.content.map((part) => {
+        if (part.type === 'text')
+            return { ...part, text: truncateMiddle(part.text) };
+        if (part.type === 'image_url' && supportsVision && allowImages) {
+            const encodedBytes = part.image_url.url.startsWith('data:')
+                ? new TextEncoder().encode(part.image_url.url).byteLength
+                : 0;
+            if (imageBudget.count >= MAX_ADVISOR_IMAGES ||
+                imageBudget.encodedBytes + encodedBytes > MAX_ADVISOR_IMAGE_BYTES) {
+                return { type: 'text', text: '[图片未发送：超过顾问视觉输入的数量或体积限制。]' };
+            }
+            imageBudget.count++;
+            imageBudget.encodedBytes += encodedBytes;
+            return part;
+        }
+        if (part.type === 'image_url' && supportsVision && !allowImages) {
+            return { type: 'text', text: '[图片未发送：未允许向顾问模型共享敏感原文或图像。]' };
+        }
+        if (part.type === 'image_url') {
+            return { type: 'text', text: '[图片未发送：顾问模型未启用视觉能力；请结合会话中已有的图片描述评审。]' };
+        }
+        return { type: 'text', text: '[视频内容未发送给顾问模型。]' };
+    });
+    return parts;
+}
+function normalizeAdvisorMessage(message, supportsVision, allowImages, imageBudget) {
+    if (message.role === 'system')
+        return null;
+    if (message.role === 'tool') {
+        return { role: 'user', content: `[工具结果 ${message.tool_call_id}]\n${truncateMiddle(message.content)}` };
+    }
+    if (message.role === 'assistant') {
+        const calls = message.tool_calls?.map((call) => `[调用工具 ${call.function.name}] ${truncateMiddle(call.function.arguments, 2000)}`).join('\n');
+        return {
+            role: 'assistant',
+            content: [message.content ?? '', calls ?? ''].filter(Boolean).join('\n'),
+        };
+    }
+    const attachmentSummary = message.attachments?.length
+        ? `\n[附件] ${message.attachments.map((item) => `${item.name} (${item.mime}, ${item.size} bytes)`).join('、')}`
+        : '';
+    const content = contentForAdvisor(message, supportsVision, allowImages, imageBudget);
+    if (typeof content === 'string')
+        return { role: 'user', content: `${content}${attachmentSummary}` };
+    return attachmentSummary
+        ? { role: 'user', content: [...content, { type: 'text', text: attachmentSummary }] }
+        : { role: 'user', content };
+}
+function fitAdvisorBudget(messages, inputBudget) {
+    if (countMessagesTokens(messages) <= inputBudget)
+        return messages;
+    const system = messages[0];
+    const closing = messages[messages.length - 1];
+    const body = messages.slice(1, -1);
+    const firstUserIndex = body.findIndex((message) => message.role === 'user');
+    const selected = [];
+    let used = countMessagesTokens([system, closing]);
+    if (firstUserIndex >= 0) {
+        const first = body[firstUserIndex];
+        selected.push(first);
+        used += countMessagesTokens([first]);
+    }
+    const recent = [];
+    for (let index = body.length - 1; index >= 0; index--) {
+        if (index === firstUserIndex)
+            continue;
+        const message = body[index];
+        const cost = countMessagesTokens([message]);
+        if (used + cost > inputBudget)
+            continue;
+        recent.unshift(message);
+        used += cost;
+    }
+    if (selected.length + recent.length < body.length) {
+        selected.push({ role: 'user', content: `[较早历史因顾问上下文预算省略 ${body.length - selected.length - recent.length} 条；已保留最初需求和最近相关记录。]` });
+    }
+    return [system, ...selected, ...recent, closing];
+}
+export function buildAdvisorMessages(history, note, options = {}) {
+    const imageBudget = { count: 0, encodedBytes: 0 };
+    const nonSystem = history
+        .map((message) => normalizeAdvisorMessage(message, options.supportsVision === true, options.allowImages ?? (options.supportsVision === true), imageBudget))
+        .filter((message) => message !== null);
+    const closing = [
+        '以上是执行助手当前会话的受预算约束相关记录（保留最初需求、近期交流、当前方案与关键工具结果）。',
+        note ? `\n执行助手额外补充：\n${note}` : '',
+        '\n请审视以上内容——它当前的方案/诊断/进展是否存在问题、遗漏的风险，或有没有更好的方向？给出你的意见。',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    const messages = [
+        { role: 'system', content: ADVISOR_SYSTEM_PROMPT },
+        ...nonSystem,
+        { role: 'user', content: closing },
+    ];
+    const contextWindow = options.contextWindow ?? 128_000;
+    const maxTokens = options.maxTokens ?? 4096;
+    const configuredBudget = Math.min(128_000, Math.max(8_000, options.inputTokenBudget ?? 128_000));
+    const providerBudget = Math.max(8_000, contextWindow - maxTokens - 4096);
+    const inputBudget = Math.min(configuredBudget, providerBudget);
+    return fitAdvisorBudget(messages, inputBudget);
+}
+/** 轻量错误分类：把第三方 HTTP/网络报错文本归到几类可操作的提示上。 */
+function classifyAdvisorError(e) {
+    const msg = e.message ?? String(e);
+    const lower = msg.toLowerCase();
+    if (lower.includes('context') ||
+        lower.includes('too long') ||
+        lower.includes('maximum context') ||
+        lower.includes('token limit')) {
+        return `顾问模型上下文超限（当前会话历史过长，超出顾问的上下文窗口）：${msg}`;
+    }
+    if (lower.includes('429') || lower.includes('rate limit') || lower.includes('too many requests')) {
+        return `顾问模型被限流：${msg}`;
+    }
+    if (lower.includes('timeout') || lower.includes('timed out') || lower.includes('network') || lower.includes('econnreset')) {
+        return `顾问模型响应超时或网络错误：${msg}`;
+    }
+    return `顾问模型调用失败：${msg}`;
+}
+// ---------------- 5. 执行逻辑（导出供测试 DI） ----------------
+/**
+ * 真正的执行逻辑，chatFn 可注入 stub（测试用，镜像 compact.ts::runCompaction 的
+ * `chatFn: typeof chat = chat` 模式），不需要 mock.module。
+ */
+export async function runAdvisor(input, signal, ctx, chatFn = chat, runtime = {}) {
+    const advisor = await configService.advisor();
+    if (!advisor) {
+        return {
+            ok: false,
+            error: '顾问模型未配置。请在设置 → 模型中完成专家顾问配置。' +
+                '可继续凭自己判断推进，不必等待顾问。',
+        };
+    }
+    if (!advisor.enabled) {
+        return {
+            ok: false,
+            error: '顾问模型当前已关闭（/advisor on 开启）。可继续凭自己判断推进，不必等待顾问。',
+        };
+    }
+    if (advisor.mode === 'manual' && ctx?.advisorInvocation !== 'manual') {
+        return { ok: false, error: '顾问模型当前为“仅手动”模式；请使用 /advisor ask 发起咨询。' };
+    }
+    if (ctx?.advisorCalls && ctx.advisorCalls.used >= ctx.advisorCalls.max) {
+        return { ok: false, error: `本回合已达到顾问咨询上限（${ctx.advisorCalls.max} 次），请继续按已有意见推进。` };
+    }
+    if (ctx?.advisorCalls)
+        ctx.advisorCalls.used++;
+    const provider = advisor.provider;
+    const snapshot = await configService.getSnapshot();
+    const secrets = [
+        ...(snapshot.config?.models.map((entry) => entry.apiKey) ?? []),
+        snapshot.config?.tools.webSearch?.apiKey,
+        snapshot.config?.tools.imageGeneration?.apiKey,
+        snapshot.config?.tools.openRouter?.apiKey,
+        snapshot.config?.tools.textToSpeech?.apiKey,
+    ].filter((value) => !!value);
+    const history = advisor.shareSensitive
+        ? [...(ctx?.history ?? [])]
+        : redactAdvisorHistory(ctx?.history ?? [], secrets);
+    const messages = buildAdvisorMessages(history, input.note, {
+        supportsVision: advisor.supportsVision,
+        allowImages: advisor.supportsVision && advisor.shareSensitive,
+        contextWindow: provider.contextWindow,
+        maxTokens: provider.maxTokens,
+        inputTokenBudget: advisor.inputTokenBudget,
+    });
+    // Advisor 是可降级的第二意见：使用独立、可配置的总时限，不影响主模型的流式时限。
+    // 默认 180 秒，直接使用所选模型的上下文窗口配置。
+    const timeoutMs = runtime.timeoutMs ?? advisor.timeoutMs;
+    const timeoutController = new AbortController();
+    const timer = setTimeout(() => timeoutController.abort(new Error('advisor-timeout')), timeoutMs);
+    const combinedSignal = signal ? AbortSignal.any([signal, timeoutController.signal]) : timeoutController.signal;
+    let content = '';
+    let reasoningChars = 0;
+    // 发布端节流：LoopEvent 消费端直接更新对应 toolCallId，这里控制事件频率，
+    // 而流式 delta 每秒可达几十上百条——阶段切换（思考中→整理意见）立即发保证切换及时可见，
+    // 同阶段后续 delta 以 ≥200ms 门控，与主循环流式 setState 的 100ms 节流纪律同量级。
+    let lastPhase = null;
+    let lastPublishAt = 0;
+    const publishProgress = (phase, buildLine) => {
+        const now = Date.now();
+        if (phase === lastPhase && now - lastPublishAt < 200)
+            return;
+        lastPhase = phase;
+        lastPublishAt = now;
+        ctx?.reportProgress?.(buildLine());
+    };
+    // 步内实时进度：治"顾问模型思考阶段 reasoning_delta 被静默丢弃、TUI 看起来像卡住"
+    // （2026-07 真实反馈：2m05s 无任何变化，用户误判死机）。无 UI 宿主时 no-op，零副作用。
+    const streamOnce = async (advisorMessages) => {
+        let output = '';
+        for await (const ev of chatFn({ provider, messages: advisorMessages, tools: [], signal: combinedSignal })) {
+            if (ev.type === 'reasoning_delta' && ev.delta) {
+                reasoningChars += ev.delta.length;
+                publishProgress('reasoning', () => `顾问模型思考中…（已生成 ${reasoningChars} 字思考）`);
+            }
+            else if (ev.type === 'text_delta') {
+                output += ev.delta;
+                publishProgress('text', () => `顾问模型正在整理意见…（已输出 ${output.length} 字）`);
+            }
+        }
+        return output;
+    };
+    const sentImageParts = messages.some((message) => Array.isArray(message.content) && message.content.some((part) => part.type === 'image_url'));
+    let degradedWithoutImages = false;
+    try {
+        try {
+            content = await streamOnce(messages);
+        }
+        catch (e) {
+            // 剥图重试保底：配置声称 supportsVision 但 provider 实际拒收图片（能力不符/图片
+            // 格式不合口味）时，把图片降级成占位文本重试一次，别白丢一次咨询。只在真的发过
+            // 图、且失败不是超时/用户中断时触发；共用同一个超时预算（timer 不重置，不叠加等待）。
+            if (!sentImageParts || timeoutController.signal.aborted || signal?.aborted)
+                throw e;
+            content = await streamOnce(buildAdvisorMessages(history, input.note, {
+                supportsVision: false,
+                contextWindow: provider.contextWindow,
+                maxTokens: provider.maxTokens,
+                inputTokenBudget: advisor.inputTokenBudget,
+            }));
+            degradedWithoutImages = true;
+        }
+    }
+    catch (e) {
+        if (timeoutController.signal.aborted && !signal?.aborted) {
+            return {
+                ok: false,
+                error: `顾问模型响应超过 ${Math.round(timeoutMs / 1000)}s 未完成，已跳过。` +
+                    '可继续凭自己判断推进，不必等待顾问。',
+            };
+        }
+        return {
+            ok: false,
+            error: `${classifyAdvisorError(e)} 可继续凭自己判断推进，不必等待顾问。`,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (degradedWithoutImages) {
+        // 让主模型如实理解这份意见的局限：顾问没看到图，评的是纯文本上下文。
+        content = `（顾问未能接收图片，本意见基于纯文本上下文。）\n${content}`;
+    }
+    if (content.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
+        content =
+            content.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) +
+                `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
+    }
+    return { ok: true, content };
+}
+// 无宿主上下文的调用视为用户手动咨询；生产主循环使用 callWithContext。
+async function call(input, signal) {
+    return runAdvisor(input, signal, { advisorInvocation: 'manual' });
+}
+// ---------------- 6. 导出 ----------------
+export const advisorTool = {
+    name: 'Advisor',
+    description,
+    inputSchema,
+    parameters,
+    isReadOnly: true,
+    isConcurrencySafe: false,
+    maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+    interruptBehavior: () => 'cancel',
+    call,
+    callWithContext: runAdvisor,
+};