minimal-agent 0.10.0 → 0.12.0

package/src/tools/advisor/advisor.js

@@ -2,9 +2,10 @@
  * ============================================================
  *  src/tools/advisor/advisor.ts —— Advisor 工具（顾问模型第二意见）
  * ------------------------------------------------------------
- *  独立配置的第二个 LLM，供主循环的模型在关键判断点
- *  （方案/诊断成型前、卡住时、收尾汇报前——具体见 CORE_IDENTITY 的"顾问咨询
- *  原则"）主动调用，拿到一个不同模型的第二意见。
+ *  独立配置的第二个 LLM，供主循环的模型在关键判断点（方案/诊断成型后动手写改之前、
+ *  受阻或要改方向时、收尾汇报之前）主动调用，拿到一个不同模型的第二意见。
+ *  时机规则的真身在 `prompts/promptAssembly.ts` 的 Advisor 工具规则 + 本文件的
+ *  `description`；配额曲线在 `loop.ts::advisorQuotaFor`。
  *
  *  设计要点（吸收自 Claude Code 官方 /advisor 的架构，但按 minimal-agent
  *  的实际约束做了取舍——不照搬服务端单请求内编排/模型分级/加密返回等
@@ -23,8 +24,10 @@
  */
 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 { toToolParameters } from '../../utils/zodToJson.js';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 // ---------------- 1. Zod 输入 schema ----------------
@@ -48,14 +51,21 @@ const description = `- Consults an independent, separately-configured second LLM
 const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技术顾问，为正在独立执行任务的另一个 AI 助手提供第二意见评审。
 你的职责：技术方案评估、代码评审、疑难问题的根因定位与解决方向判断。
 
-你会看到该助手当前会话的完整历史——包括用户最初的需求、双方历次交流、以及它已经做过的工具调用
-与执行结果，以及它现在想让你重点关注的内容（如果有）。
+你会看到该助手当前会话中受预算约束的相关记录——包括首要需求、近期交流、它的思考过程、当前方案
+和关键工具结果与执行结果，以及它现在想让你重点关注的内容（如果有）。
 
 审视时请做到：
 - 像资深工程师做方案评审/代码评审一样直接、具体——发现问题就明说，不要无条件附和或说套话。
 - 优先检查：方案是否遗漏了风险或边界情况、诊断是否真的找到了根因还是只是让症状消失、
   是否存在更简单或更稳妥的替代方向。
-- 结论必须基于你在历史记录里看到的实际证据，不要脱离上下文给泛泛的通用建议。
+- 分清它「跑出来的」和「读代码推出来的」：后者常被当成事实陈述。它声称已验证、而记录里
+  找不到对应工具结果的关键结论，直接指出来并要求补验证。
+- 测试全绿不等于改对了：留意「测的是被改的那个函数，而真实调用路径根本走不到它」这类
+  情况——绿灯来自覆盖错了层，不是行为正确。
+- 若它此前已征求过你的意见，检查后续动作是否真的落实到位：改了一半、只动了表层、
+  或换个方式绕开，都要点出来。
+- 结论必须基于你在历史记录里看到的实际证据，不要脱离上下文给泛泛的通用建议；
+  被省略的记录（尤其工具结果原文）所涉及的判断，明说你无法核实。
 - 篇幅精炼：只讲最关键的 1-3 点，不要复述历史、不要客套开场白。`;
 // ---------------- 4. 消息构造（纯函数，单独导出可测） ----------------
 /**
@@ -65,6 +75,8 @@ const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技
  * 和 TUI 的 ephemeral 提示消息（两者都是 role:'system'），换成顾问自己的 persona。
  */
 const MAX_TOOL_RESULT_CHARS = 12_000;
+/** 归一化后的工具结果前缀；裁剪统计要靠它反查，两处必须共用同一常量。 */
+const TOOL_RESULT_PREFIX = '[工具结果 ';
 function truncateMiddle(value, limit = MAX_TOOL_RESULT_CHARS) {
     if (value.length <= limit)
         return value;
@@ -81,7 +93,7 @@ function redactSensitiveText(value, secrets) {
         .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) {
+export function redactAdvisorHistory(history, secrets) {
     return history.map((message) => {
         if (message.role === 'user') {
             const content = typeof message.content === 'string'
@@ -95,6 +107,15 @@ function redactAdvisorHistory(history, secrets) {
             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) },
@@ -137,13 +158,25 @@ function normalizeAdvisorMessage(message, supportsVision, allowImages, imageBudg
     if (message.role === 'system')
         return null;
     if (message.role === 'tool') {
-        return { role: 'user', content: `[工具结果 ${message.tool_call_id}]\n${truncateMiddle(message.content)}` };
+        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: [message.content ?? '', calls ?? ''].filter(Boolean).join('\n'),
+            content: [thinkingLine, message.content ?? '', calls ?? ''].filter(Boolean).join('\n'),
         };
     }
     const attachmentSummary = message.attachments?.length
@@ -181,8 +214,23 @@ function fitAdvisorBudget(messages, inputBudget) {
         recent.unshift(message);
         used += cost;
     }
-    if (selected.length + recent.length < body.length) {
-        selected.push({ role: 'user', content: `[较早历史因顾问上下文预算省略 ${body.length - selected.length - recent.length} 条；已保留最初需求和最近相关记录。]` });
+    const droppedCount = body.length - selected.length - recent.length;
+    if (droppedCount > 0) {
+        // 单独点出被丢掉的**工具结果**条数：顾问最有价值的用法之一是发现执行助手误读了
+        // 自己跑出来的证据，而裁剪一旦只留下助手的转述、丢掉原始工具输出，这个能力就归零。
+        // 与其让它对着转述给出自信结论，不如如实告诉它「这里有盲区」。
+        const kept = new Set([...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];
 }
@@ -205,8 +253,8 @@ export function buildAdvisorMessages(history, note, options = {}) {
     ];
     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 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);
 }
@@ -252,7 +300,14 @@ export async function runAdvisor(input, signal, ctx, chatFn = chat, runtime = {}
         return { ok: false, error: '顾问模型当前为“仅手动”模式；请使用 /advisor ask 发起咨询。' };
     }
     if (ctx?.advisorCalls && ctx.advisorCalls.used >= ctx.advisorCalls.max) {
-        return { ok: false, error: `本回合已达到顾问咨询上限（${ctx.advisorCalls.max} 次），请继续按已有意见推进。` };
+        // ⚠️ 必须说明「配额会增长」：配额随本回合工作量上调（loop.ts::advisorQuotaFor），
+        // 若这里只说「已达上限」，模型会当成本回合的硬上限而不再尝试 —— 那样长回合里
+        // 「批次做完再复核一次」的配额永远不会被用到，增长机制等于没做。
+        return {
+            ok: false,
+            error: `本回合顾问咨询配额暂时用完（当前 ${ctx.advisorCalls.max} 次）。` +
+                '配额会随本回合的工作量增长，继续推进一段后可以再次咨询；现在请按已有意见继续。',
+        };
     }
     if (ctx?.advisorCalls)
         ctx.advisorCalls.used++;
@@ -300,7 +355,13 @@ export async function runAdvisor(input, signal, ctx, chatFn = chat, runtime = {}
     // （2026-07 真实反馈：2m05s 无任何变化，用户误判死机）。无 UI 宿主时 no-op，零副作用。
     const streamOnce = async (advisorMessages) => {
         let output = '';
-        for await (const ev of chatFn({ provider, messages: advisorMessages, tools: [], signal: combinedSignal })) {
+        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} 字思考）`);