minimal-agent 0.10.0 → 0.12.0

package/src/tools/advisor/advisor.ts

@@ -0,0 +1,512 @@
+/**
+ * ============================================================
+ *  src/tools/advisor/advisor.ts —— Advisor 工具（顾问模型第二意见）
+ * ------------------------------------------------------------
+ *  独立配置的第二个 LLM，供主循环的模型在关键判断点（方案/诊断成型后动手写改之前、
+ *  受阻或要改方向时、收尾汇报之前）主动调用，拿到一个不同模型的第二意见。
+ *  时机规则的真身在 `prompts/promptAssembly.ts` 的 Advisor 工具规则 + 本文件的
+ *  `description`；配额曲线在 `loop.ts::advisorQuotaFor`。
+ *
+ *  设计要点（吸收自 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 { CONFIG_LIMITS, normalizeLimited } from '../../config/numericLimits.js';
+import { countMessagesTokens } from '../../context/tokenCounter.js';
+import { chat } from '../../llm/client.js';
+import { derivePromptCacheContext } from '../../llm/promptCache.js';
+import type { Message, Tool, ToolCallContext, ToolResult } from '../../types.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(
+      '可选。大多数情况下不需要填——你此前说过的方案/诊断已经在会话历史里，顾问会自动看到。' +
+        '只有需要额外强调、历史里没体现的点时才填一句话。',
+    ),
+});
+type AdvisorInput = z.infer<typeof inputSchema>;
+
+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;
+
+/** 归一化后的工具结果前缀；裁剪统计要靠它反查，两处必须共用同一常量。 */
+const TOOL_RESULT_PREFIX = '[工具结果 ';
+
+function truncateMiddle(value: string, limit = MAX_TOOL_RESULT_CHARS): string {
+  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: string, secrets: readonly string[]): string {
+  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]');
+}
+
+export function redactAdvisorHistory(history: readonly Message[], secrets: readonly string[]): Message[] {
+  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,
+      // ⚠️ 思维链必须一起脱敏。它现在会被送给顾问（见 normalizeAdvisorMessage），
+      // 而顾问常常是**另一家 provider**；模型在思考里复述 apiKey/token 完全可能发生。
+      // 少脱这一处，等于开一个只在「顾问启用」时才生效的泄漏口子。
+      ...(typeof message.reasoning_content === 'string'
+        ? { reasoning_content: redactSensitiveText(message.reasoning_content, secrets) }
+        : {}),
+      ...(typeof message.reasoning === 'string'
+        ? { reasoning: redactSensitiveText(message.reasoning, secrets) }
+        : {}),
+      tool_calls: message.tool_calls?.map((call) => ({
+        ...call,
+        function: { ...call.function, arguments: redactSensitiveText(call.function.arguments, secrets) },
+      })),
+    };
+    return { ...message, content: redactSensitiveText(message.content, secrets) };
+  });
+}
+
+interface AdvisorImageBudget {
+  count: number;
+  encodedBytes: number;
+}
+
+const MAX_ADVISOR_IMAGES = 4;
+const MAX_ADVISOR_IMAGE_BYTES = 8 * 1024 * 1024;
+
+function contentForAdvisor(
+  message: Extract<Message, { role: 'user' }>,
+  supportsVision: boolean,
+  allowImages: boolean,
+  imageBudget: AdvisorImageBudget,
+): Extract<Message, { role: 'user' }>['content'] {
+  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' as const, text: '[图片未发送：超过顾问视觉输入的数量或体积限制。]' };
+      }
+      imageBudget.count++;
+      imageBudget.encodedBytes += encodedBytes;
+      return part;
+    }
+    if (part.type === 'image_url' && supportsVision && !allowImages) {
+      return { type: 'text' as const, text: '[图片未发送：未允许向顾问模型共享敏感原文或图像。]' };
+    }
+    if (part.type === 'image_url') {
+      return { type: 'text' as const, text: '[图片未发送：顾问模型未启用视觉能力；请结合会话中已有的图片描述评审。]' };
+    }
+    return { type: 'text' as const, text: '[视频内容未发送给顾问模型。]' };
+  });
+  return parts;
+}
+
+function normalizeAdvisorMessage(
+  message: Message,
+  supportsVision: boolean,
+  allowImages: boolean,
+  imageBudget: AdvisorImageBudget,
+): Message | null {
+  if (message.role === 'system') return null;
+  if (message.role === 'tool') {
+    return { role: 'user', content: `${TOOL_RESULT_PREFIX}${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');
+    // 思维链一并送给顾问：评审「方案对不对」很大程度上要看**它是怎么想到这个方案的**——
+    // 推理里的跳跃（把推断当已验证、跳过一个没排除的可能）在最终结论文本里往往看不出来。
+    // 截断比正文更狠（2000）：重思考模型的 reasoning 常比 content 长几倍，不设限会把
+    // 预算吃光、反而挤掉更该保留的工具结果原文。
+    // reasoning_details（结构化数组）不传：结构因 provider 而异，既无法可靠脱敏也无法
+    // 稳定转成文本，传过去只会变成噪声。
+    const thinking = typeof message.reasoning_content === 'string' && message.reasoning_content.length > 0
+      ? message.reasoning_content
+      : (typeof message.reasoning === 'string' ? message.reasoning : '');
+    const thinkingLine = thinking.length > 0
+      ? `[思考过程]\n${truncateMiddle(thinking, 2000)}`
+      : '';
+    return {
+      role: 'assistant',
+      content: [thinkingLine, 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: Message[], inputBudget: number): Message[] {
+  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: Message[] = [];
+  let used = countMessagesTokens([system, closing]);
+  if (firstUserIndex >= 0) {
+    const first = body[firstUserIndex]!;
+    selected.push(first);
+    used += countMessagesTokens([first]);
+  }
+  const recent: Message[] = [];
+  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;
+  }
+  const droppedCount = body.length - selected.length - recent.length;
+  if (droppedCount > 0) {
+    // 单独点出被丢掉的**工具结果**条数：顾问最有价值的用法之一是发现执行助手误读了
+    // 自己跑出来的证据，而裁剪一旦只留下助手的转述、丢掉原始工具输出，这个能力就归零。
+    // 与其让它对着转述给出自信结论，不如如实告诉它「这里有盲区」。
+    const kept = new Set<Message>([...selected, ...recent]);
+    const droppedToolResults = body.filter((message) =>
+      !kept.has(message)
+      && message.role === 'user'
+      && typeof message.content === 'string'
+      && message.content.startsWith(TOOL_RESULT_PREFIX)).length;
+    const toolNote = droppedToolResults > 0
+      ? `其中 ${droppedToolResults} 条是工具执行结果原文——这部分证据你看不到，只能看到执行助手的转述，涉及它们的判断请明确说明无法核实。`
+      : '';
+    selected.push({
+      role: 'user',
+      content: `[较早历史因顾问上下文预算省略 ${droppedCount} 条；已保留最初需求和最近相关记录。${toolNote}]`,
+    });
+  }
+  return [system, ...selected, ...recent, closing];
+}
+
+export function buildAdvisorMessages(
+  history: readonly Message[],
+  note?: string,
+  options: {
+    supportsVision?: boolean;
+    allowImages?: boolean;
+    contextWindow?: number;
+    maxTokens?: number;
+    inputTokenBudget?: number;
+  } = {},
+): Message[] {
+  const imageBudget: AdvisorImageBudget = { count: 0, encodedBytes: 0 };
+  const nonSystem = history
+    .map((message) => normalizeAdvisorMessage(
+      message,
+      options.supportsVision === true,
+      options.allowImages ?? (options.supportsVision === true),
+      imageBudget,
+    ))
+    .filter((message): message is Message => message !== null);
+
+  const closing = [
+    '以上是执行助手当前会话的受预算约束相关记录（保留最初需求、近期交流、当前方案与关键工具结果）。',
+    note ? `\n执行助手额外补充：\n${note}` : '',
+    '\n请审视以上内容——它当前的方案/诊断/进展是否存在问题、遗漏的风险，或有没有更好的方向？给出你的意见。',
+  ]
+    .filter(Boolean)
+    .join('\n');
+
+  const messages: Message[] = [
+    { role: 'system', content: ADVISOR_SYSTEM_PROMPT },
+    ...nonSystem,
+    { role: 'user', content: closing },
+  ];
+  const contextWindow = options.contextWindow ?? 128_000;
+  const maxTokens = options.maxTokens ?? 4096;
+  const configuredBudget = normalizeLimited(
+    options.inputTokenBudget, CONFIG_LIMITS.advisorInputTokenBudget, 128_000);
+  const providerBudget = Math.max(CONFIG_LIMITS.advisorInputTokenBudget.min, contextWindow - maxTokens - 4096);
+  const inputBudget = Math.min(configuredBudget, providerBudget);
+  return fitAdvisorBudget(messages, inputBudget);
+}
+
+/** 轻量错误分类：把第三方 HTTP/网络报错文本归到几类可操作的提示上。 */
+function classifyAdvisorError(e: Error): string {
+  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: AdvisorInput,
+  signal?: AbortSignal,
+  ctx?: ToolCallContext,
+  chatFn: typeof chat = chat,
+  runtime: { timeoutMs?: number } = {},
+): Promise<ToolResult> {
+  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) {
+    // ⚠️ 必须说明「配额会增长」：配额随本回合工作量上调（loop.ts::advisorQuotaFor），
+    // 若这里只说「已达上限」，模型会当成本回合的硬上限而不再尝试 —— 那样长回合里
+    // 「批次做完再复核一次」的配额永远不会被用到，增长机制等于没做。
+    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 is string => !!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: 'reasoning' | 'text' | null = null;
+  let lastPublishAt = 0;
+  const publishProgress = (phase: 'reasoning' | 'text', buildLine: () => string) => {
+    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: Message[]): Promise<string> => {
+    let output = '';
+    for await (const ev of chatFn({
+      provider,
+      messages: advisorMessages,
+      tools: [],
+      signal: combinedSignal,
+      promptCache: derivePromptCacheContext(ctx?.promptCache, 'advisor'),
+    })) {
+      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 as Error)} 可继续凭自己判断推进，不必等待顾问。`,
+    };
+  } 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: AdvisorInput, signal?: AbortSignal): Promise<ToolResult> {
+  return runAdvisor(input, signal, { advisorInvocation: 'manual' });
+}
+
+// ---------------- 6. 导出 ----------------
+export const advisorTool: Tool<AdvisorInput> = {
+  name: 'Advisor',
+  description,
+  inputSchema,
+  parameters,
+  isReadOnly: true,
+  isConcurrencySafe: false,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  interruptBehavior: () => 'cancel',
+  call,
+  callWithContext: runAdvisor,
+};