minimal-agent 0.12.0 → 0.13.0

package/src/plugins/pluginRunner.ts

@@ -9,8 +9,8 @@
  *    2) / 输入 → discoverPlugins → resolveCommand
  *       a) 命中插件且其 plugin.ts 暴露 runCommand → 让 plugin.ts 接管
  *       b) 命中插件但只有声明式 commands/*.md → 把 prompt 拼好喂给 runQuery
- *       c) 未命中 → 静默透传 runQuery（/ 只是激活前缀，不是严格命令系统；
- *          未知的 /xxx 当普通用户输入处理，不报错）
+ *       c) 未命中 -> warning 提示未知命令后透传 runQuery（/ 只是激活前缀，
+ *          不是严格命令系统；未知的 /xxx 当普通用户输入处理，不报错）
  * ============================================================
  */
 
@@ -19,6 +19,7 @@ import type { LoopEvent, Message, Provider } from '../types.js';
 import {
   buildCommandInput,
   discoverPlugins,
+  listAvailableCommands,
   resolveCommand,
 } from './commandRouter.js';
 import type { PluginEvent } from './pluginApi.js';
@@ -106,10 +107,23 @@ export async function* runWithPlugins(
   const matched = resolveCommand(userInput);
 
   if (!matched) {
-    // 未命中任何插件命令 → 静默透传 runQuery。
-    // / 只是激活前缀（类似 Claude Code 的 / 模式），不是严格命令系统。
-    // 用户可能输入 /init、/help、/任何东西 —— 不匹配就当普通对话处理，
-    // 让 LLM 自行理解意图。不报错、不提示、不打断用户体验。
+    // 未命中任何插件命令 -> 提示后透传 runQuery。
+    // / 只是激活前缀（类似 Claude Code 的 / 模式），不是严格命令系统：
+    // 不匹配仍当普通对话处理，让 LLM 自行理解意图。但 -p 等无人值守场景里
+    // 拼错的 /reseach 会被静默当文本烧一轮 LLM（实战：用户以为在跑工作流，
+    // 实际什么都没发生）--先 warning 列出已注册命令，零成本纠正拼写。
+    const trimmedUnknown = userInput.trimStart();
+    const spaceUnknown = trimmedUnknown.indexOf(' ', 1);
+    const unknownCmd = (
+      spaceUnknown >= 0 ? trimmedUnknown.slice(1, spaceUnknown) : trimmedUnknown.slice(1)
+    ).trim();
+    if (unknownCmd) {
+      const available = listAvailableCommands().map((c) => c.command);
+      yield {
+        type: 'warning',
+        message: `未知命令 /${unknownCmd}（已注册：${available.length ? available.join('、') : '无'}），已按普通对话处理。`,
+      };
+    }
     yield* runQuery(userInput, {
       provider,
       history,

package/src/prompts/policyRegistry.js

@@ -232,7 +232,34 @@ const CAPABILITY_POLICIES = [
     {
         id: 'capability.advisor', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',
         requiresTools: ['Advisor'],
-        render: () => '- Advisor 是可选的第二意见：复杂架构决策、高风险修改、反复受阻、证据冲突或用户明确要求时再调用。普通实现和收尾不固定咨询；顾问不可用不得阻塞主流程。咨询前先落盘成果，顾问意见与实测冲突时以实测为准并明确核对冲突。',
+        // 注意：文本内不得硬编码其他工具名（如 PresentResult），否则该工具缺席时这里
+        // 成为唯一残留的「幽灵引用」——capability 规则交叉引用必须在 toolNames 条件下拼接。
+        render: ({ toolNames }) => `- Advisor（顾问模型）使用规则：
+  **在动手之前问，不是出事之后问**：顾问的价值在方案定型前最大——代码一旦写下去，换方向的成本就变了。
+  「摸清现状」不算动手（找文件、读代码、跑命令看状态，这些先做完再问）；
+  「动手」指写文件、认定某个解释、在假设上继续搭、给出结论。
+  **当 Advisor 工具出现在当前可用工具列表中时**，以下 5 种场景必须主动调用，不要等到出错或用户问了才想起来：
+  1. 方案/开发计划成型后、动手执行前（先让顾问挑刺，避免做一半才发现方向错了）
+  2. 最终结果提交用户前${toolNames.has('PresentResult') ? '（PresentResult 之前）' : ''}：代码评审、评估报告、技术选型、重构方案等所有"给出结论"的场合
+  3. 连续 2 次遇到同类错误或修复不收敛（死循环前兆，立刻换思路）
+  4. 同一轮内用户第 2 次反馈不满意（不要在原地打转，先找顾问换角度）
+  5. 涉及安全性、数据丢失、不可逆操作的决策（顾问双保险）
+  调用时 note 里必须包含：你的完整结论/方案 + 关键代码原文或证据摘要，不要只写结论摘要。
+  场景 2 有个前置动作：**先把产出落盘再调用**（写文件、保存结果）。这一次调用要花时间，
+  回合若在此期间结束，写下的文件还在，没写的答案就没了。
+  长任务至少咨询两次：方案定型前一次、宣布完成前一次；短的、下一步由刚读到的输出直接决定的任务，一次即可。
+  **顾问返回后必须做验证，不能盲信：**
+  - 顾问的意见只是第二视角的候选诊断，不是事实。它没有工具访问权，无法自行验证。
+  - 对顾问提出的每一条严重问题/反例，都必须回到代码、测试、原始资料或工具输出核实。
+  - 核实后分类：真问题（有证据支撑）、误报（被事实推翻）、待澄清（暂时无法验证）。
+  - 未经核实的顾问意见，不得写成确定结论；与实测冲突时，以实测为准。
+  - ⚠️ 但「自测通过」不等于顾问说错了：那往往只说明你的测试没测到它指的那一层。
+  - 与你已掌握的证据冲突时**不要默默改方向**：再调一次顾问，把冲突摆出来
+    （「我实测是 X，你建议 Y，哪个约束更硬？」）。它看过你的证据但可能低估了，
+    一次对账远比顺着错误分支做下去便宜。
+  **如果 Advisor 不在工具列表中**（未配置、已关闭、仅手动模式或当前不可用）：视为用户明确选择跳过，不得尝试调用，也不阻塞流程，无需在输出中专门说明。
+  咨询前先落盘成果，顾问意见与实测冲突时以实测为准并明确核对冲突。
+  补充：任何评审/评估/结论输出前，先用 adversarial-review 的方法论自我审查（拆原子主张、反向提问、去现场核对），再决定是否需要顾问。`,
     },
     {
         id: 'capability.subagent', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',

package/src/prompts/policyRegistry.ts

@@ -274,7 +274,34 @@ const CAPABILITY_POLICIES: PromptPolicySpec[] = [
   {
     id: 'capability.advisor', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',
     requiresTools: ['Advisor'],
-    render: () => '- Advisor 是可选的第二意见：复杂架构决策、高风险修改、反复受阻、证据冲突或用户明确要求时再调用。普通实现和收尾不固定咨询；顾问不可用不得阻塞主流程。咨询前先落盘成果，顾问意见与实测冲突时以实测为准并明确核对冲突。',
+    // 注意：文本内不得硬编码其他工具名（如 PresentResult），否则该工具缺席时这里
+    // 成为唯一残留的「幽灵引用」——capability 规则交叉引用必须在 toolNames 条件下拼接。
+    render: ({ toolNames }) => `- Advisor（顾问模型）使用规则：
+  **在动手之前问，不是出事之后问**：顾问的价值在方案定型前最大——代码一旦写下去，换方向的成本就变了。
+  「摸清现状」不算动手（找文件、读代码、跑命令看状态，这些先做完再问）；
+  「动手」指写文件、认定某个解释、在假设上继续搭、给出结论。
+  **当 Advisor 工具出现在当前可用工具列表中时**，以下 5 种场景必须主动调用，不要等到出错或用户问了才想起来：
+  1. 方案/开发计划成型后、动手执行前（先让顾问挑刺，避免做一半才发现方向错了）
+  2. 最终结果提交用户前${toolNames.has('PresentResult') ? '（PresentResult 之前）' : ''}：代码评审、评估报告、技术选型、重构方案等所有"给出结论"的场合
+  3. 连续 2 次遇到同类错误或修复不收敛（死循环前兆，立刻换思路）
+  4. 同一轮内用户第 2 次反馈不满意（不要在原地打转，先找顾问换角度）
+  5. 涉及安全性、数据丢失、不可逆操作的决策（顾问双保险）
+  调用时 note 里必须包含：你的完整结论/方案 + 关键代码原文或证据摘要，不要只写结论摘要。
+  场景 2 有个前置动作：**先把产出落盘再调用**（写文件、保存结果）。这一次调用要花时间，
+  回合若在此期间结束，写下的文件还在，没写的答案就没了。
+  长任务至少咨询两次：方案定型前一次、宣布完成前一次；短的、下一步由刚读到的输出直接决定的任务，一次即可。
+  **顾问返回后必须做验证，不能盲信：**
+  - 顾问的意见只是第二视角的候选诊断，不是事实。它没有工具访问权，无法自行验证。
+  - 对顾问提出的每一条严重问题/反例，都必须回到代码、测试、原始资料或工具输出核实。
+  - 核实后分类：真问题（有证据支撑）、误报（被事实推翻）、待澄清（暂时无法验证）。
+  - 未经核实的顾问意见，不得写成确定结论；与实测冲突时，以实测为准。
+  - ⚠️ 但「自测通过」不等于顾问说错了：那往往只说明你的测试没测到它指的那一层。
+  - 与你已掌握的证据冲突时**不要默默改方向**：再调一次顾问，把冲突摆出来
+    （「我实测是 X，你建议 Y，哪个约束更硬？」）。它看过你的证据但可能低估了，
+    一次对账远比顺着错误分支做下去便宜。
+  **如果 Advisor 不在工具列表中**（未配置、已关闭、仅手动模式或当前不可用）：视为用户明确选择跳过，不得尝试调用，也不阻塞流程，无需在输出中专门说明。
+  咨询前先落盘成果，顾问意见与实测冲突时以实测为准并明确核对冲突。
+  补充：任何评审/评估/结论输出前，先用 adversarial-review 的方法论自我审查（拆原子主张、反向提问、去现场核对），再决定是否需要顾问。`,
   },
   {
     id: 'capability.subagent', layer: 'capability', profiles: MAIN_PROFILE, source: 'native',

package/src/tools/advisor/advisor.js

@@ -42,11 +42,23 @@ const inputSchema = z.object({
 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.
+- 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). Always pass key evidence (original code snippets, raw data, full plan text) in \`note\`, not just your summary — the advisor cannot verify things you never wrote down.
+- 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.
+- **Call it BEFORE substantive work, not after things go wrong.** The advisor is worth the most before an approach hardens — once you have written the code, the plan is expensive to abandon.
+  - Orientation is NOT substantive work: finding files, reading code, running a command to see the current state. Do that first, then consult.
+  - Substantive work IS: writing or editing files, committing to an interpretation, building on an assumption, declaring an answer.
+- **MUST call Advisor in all 5 of these situations — do not wait for errors or user prompts:**
+  1. After a plan / development plan is finalized, **before** executing it (get critique first, avoid discovering wrong direction halfway)
+  2. **Before** submitting final results to the user (before PresentResult): code reviews, assessment reports, technical selections, refactoring plans — any time you "deliver a conclusion"
+  3. The same error occurs 2+ times in a row, or fixes are not converging (early sign of infinite loop — switch approach immediately)
+  4. The user gives unsatisfied feedback a **second time** in the same turn (stop spinning in place, get a fresh perspective first)
+  5. Decisions involving security, data loss, or irreversible operations (advisor double-check)
+- **Make your work durable BEFORE calling in situation 2.** Write the file, save the result. This call takes time; if the turn ends during it, a written file survives and an unwritten answer does not.
+- On a long task, consult at least twice: once before the approach is locked in, once before you declare it done. On a short reactive task whose next step is dictated by output you just read, one call is enough — the advisor adds most of its value early.
+- **Take the advice seriously, but do not obey it blindly.** Adapt if you follow a step and it empirically fails, or you hold primary-source evidence contradicting a specific claim (the file says X, the test output says Y). A passing self-test is NOT evidence the advice is wrong — it is evidence your test does not check what the advice checks.
+- **If the advisor contradicts evidence you already gathered, do not silently switch.** Call Advisor once more stating the conflict outright ("I measured X, you advise Y — which constraint breaks the tie?"). The advisor saw your evidence but may have underweighted it; one reconciling call is far cheaper than committing to the wrong branch.
 - 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.`;
+- 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, but **explicitly note "not cross-verified by advisor" in your final output**. Do not block or retry in a loop.`;
 // ---------------- 3. 顾问 persona system prompt ----------------
 const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技术顾问，为正在独立执行任务的另一个 AI 助手提供第二意见评审。
 你的职责：技术方案评估、代码评审、疑难问题的根因定位与解决方向判断。
@@ -54,6 +66,14 @@ const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技
 你会看到该助手当前会话中受预算约束的相关记录——包括首要需求、近期交流、它的思考过程、当前方案
 和关键工具结果与执行结果，以及它现在想让你重点关注的内容（如果有）。
 
+重要：你**没有工具访问权，无法自行验证任何事实**。你只是提供一个不同视角的怀疑和推理，
+不能把自己的推测当成确定结论。每条指出的问题都要明确标注：
+  - 【有证据】：基于记录里明确出现的代码/测试结果/事实
+  - 【推断】：基于已有信息的合理推断，但未被证实
+  - 【存疑】：信息不足，需要执行助手回去核实
+不要过度自信，不要给出确定性语气的未验证判断——执行助手会对你的意见逐条做验证，
+夸大其词会被判定为误报。
+
 审视时请做到：
 - 像资深工程师做方案评审/代码评审一样直接、具体——发现问题就明说，不要无条件附和或说套话。
 - 优先检查：方案是否遗漏了风险或边界情况、诊断是否真的找到了根因还是只是让症状消失、
@@ -66,7 +86,16 @@ const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技
   或换个方式绕开，都要点出来。
 - 结论必须基于你在历史记录里看到的实际证据，不要脱离上下文给泛泛的通用建议；
   被省略的记录（尤其工具结果原文）所涉及的判断，明说你无法核实。
-- 篇幅精炼：只讲最关键的 1-3 点，不要复述历史、不要客套开场白。`;
+- 篇幅精炼：只讲最关键的 1-3 点，不要复述历史、不要客套开场白。
+
+关于「带着反证回来」的那一次咨询（助手被要求这样做，不是在质疑你）：
+当它说「我实测是 X，你上次建议 Y」时，它手里的是一手证据，你手里的是推理——
+默认它的观测为真，然后只回答一个问题：**哪个约束更硬**。
+  - 你上次漏看了它给出的证据 → 直接认，并说清结论怎么变。
+  - 它的观测其实没测到你担心的那一层（测了被改的函数，而真实调用路径根本走不到）
+    → 指出这个错位，并说要测什么才算数。
+  - 两者都成立、只是适用范围不同 → 说清各自的边界，别硬选一个。
+不要为了显得一致而坚持原判，也不要因为被反驳就整个收回——两种都会让它失去判断依据。`;
 // ---------------- 4. 消息构造（纯函数，单独导出可测） ----------------
 /**
  * 把主循环的 history 转成喂给顾问模型的 messages。
@@ -203,6 +232,13 @@ function fitAdvisorBudget(messages, inputBudget) {
         selected.push(first);
         used += countMessagesTokens([first]);
     }
+    // 从最近往前收，**装不下就停**（break，不是 continue）。
+    //
+    // ⚠️ 曾经是 continue：一条大消息放不下就跳过它、继续往前捡更小的旧消息。
+    // 结果是给顾问一段**中间有洞**的对话 —— 而洞恰好开在信息量最大的地方（长工具
+    // 结果、完整方案文本），偏偏下面那句省略提示还写着「保留最初需求和最近相关记录」，
+    // 顾问于是把两条本不相邻的消息读成前后相接，在残缺的因果链上给出自信结论。
+    // 宁可少给，不可给错：连续的尾部 + 如实说明从哪里开始省略。
     const recent = [];
     for (let index = body.length - 1; index >= 0; index--) {
         if (index === firstUserIndex)
@@ -210,7 +246,7 @@ function fitAdvisorBudget(messages, inputBudget) {
         const message = body[index];
         const cost = countMessagesTokens([message]);
         if (used + cost > inputBudget)
-            continue;
+            break;
         recent.unshift(message);
         used += cost;
     }
@@ -287,17 +323,22 @@ export async function runAdvisor(input, signal, ctx, chatFn = chat, runtime = {}
         return {
             ok: false,
             error: '顾问模型未配置。请在设置 → 模型中完成专家顾问配置。' +
-                '可继续凭自己判断推进，不必等待顾问。',
+                '本回合后续不要再次尝试调用 Advisor；可继续凭自己判断推进，不必等待顾问。',
         };
     }
     if (!advisor.enabled) {
         return {
             ok: false,
-            error: '顾问模型当前已关闭（/advisor on 开启）。可继续凭自己判断推进，不必等待顾问。',
+            error: '顾问模型当前已关闭（/advisor on 开启）。' +
+                '本回合后续不要再次尝试调用 Advisor；可继续凭自己判断推进，不必等待顾问。',
         };
     }
     if (advisor.mode === 'manual' && ctx?.advisorInvocation !== 'manual') {
-        return { ok: false, error: '顾问模型当前为“仅手动”模式；请使用 /advisor ask 发起咨询。' };
+        return {
+            ok: false,
+            error: '顾问模型当前为"仅手动"模式；请使用 /advisor ask 发起咨询。' +
+                '本回合后续不要再次尝试自动调用 Advisor。',
+        };
     }
     if (ctx?.advisorCalls && ctx.advisorCalls.used >= ctx.advisorCalls.max) {
         // ⚠️ 必须说明「配额会增长」：配额随本回合工作量上调（loop.ts::advisorQuotaFor），
@@ -435,6 +476,32 @@ export const advisorTool = {
     isConcurrencySafe: false,
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
     interruptBehavior: () => 'cancel',
+    /**
+     * 动态可用性探测：未配置 / 已关闭 / 仅手动模式 → 工具不暴露给模型。
+     * 对齐 ComputerUse / WebBrowser 的模式：关闭时工具直接从 LLM 视野消失，
+     * 避免"看到工具但调不了→反复尝试"的流畅度问题。
+     *
+     * signature 随 enabled/mode/modelId 变化，确保配置改动后工具集签名更新、
+     * 模型下一轮拿到的是新工具列表。
+     */
+    resolveAvailability() {
+        // 走同步探测（读内存快照），不触发磁盘 IO；
+        // resolveAvailability 是工具集构造阶段的同步调用，不能 await。
+        const avail = configService.advisorAvailabilitySync();
+        // ⚠️ 安全兜底：如果 snapshot 尚未初始化（极端情况：工具集构造发生在任何
+        // configService 异步调用之前），宁可返回 available=true 让工具显示出来
+        // （调用时 runAdvisor 会做真正的 fresh reload 校验），也不能误判为
+        // "未配置" 导致 Advisor 从工具列表里消失——少一个工具比多一个工具严重得多。
+        if (avail.configured && !avail.enabled) {
+            return { available: false, signature: 'disabled' };
+        }
+        if (avail.configured && avail.mode === 'manual') {
+            return { available: false, signature: 'manual-only' };
+        }
+        // 未初始化 / 已配置且可用 → 都显示工具（未配置时调用会有明确错误提示）
+        // modelId 进签名：不同顾问模型 = 不同能力 = 工具语义不同。
+        return { available: true, signature: avail.modelId ?? 'initializing' };
+    },
     call,
     callWithContext: runAdvisor,
 };

package/src/tools/advisor/advisor.ts

@@ -51,11 +51,23 @@ 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.
+- 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). Always pass key evidence (original code snippets, raw data, full plan text) in \`note\`, not just your summary — the advisor cannot verify things you never wrote down.
+- 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.
+- **Call it BEFORE substantive work, not after things go wrong.** The advisor is worth the most before an approach hardens — once you have written the code, the plan is expensive to abandon.
+  - Orientation is NOT substantive work: finding files, reading code, running a command to see the current state. Do that first, then consult.
+  - Substantive work IS: writing or editing files, committing to an interpretation, building on an assumption, declaring an answer.
+- **MUST call Advisor in all 5 of these situations — do not wait for errors or user prompts:**
+  1. After a plan / development plan is finalized, **before** executing it (get critique first, avoid discovering wrong direction halfway)
+  2. **Before** submitting final results to the user (before PresentResult): code reviews, assessment reports, technical selections, refactoring plans — any time you "deliver a conclusion"
+  3. The same error occurs 2+ times in a row, or fixes are not converging (early sign of infinite loop — switch approach immediately)
+  4. The user gives unsatisfied feedback a **second time** in the same turn (stop spinning in place, get a fresh perspective first)
+  5. Decisions involving security, data loss, or irreversible operations (advisor double-check)
+- **Make your work durable BEFORE calling in situation 2.** Write the file, save the result. This call takes time; if the turn ends during it, a written file survives and an unwritten answer does not.
+- On a long task, consult at least twice: once before the approach is locked in, once before you declare it done. On a short reactive task whose next step is dictated by output you just read, one call is enough — the advisor adds most of its value early.
+- **Take the advice seriously, but do not obey it blindly.** Adapt if you follow a step and it empirically fails, or you hold primary-source evidence contradicting a specific claim (the file says X, the test output says Y). A passing self-test is NOT evidence the advice is wrong — it is evidence your test does not check what the advice checks.
+- **If the advisor contradicts evidence you already gathered, do not silently switch.** Call Advisor once more stating the conflict outright ("I measured X, you advise Y — which constraint breaks the tie?"). The advisor saw your evidence but may have underweighted it; one reconciling call is far cheaper than committing to the wrong branch.
 - 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.`;
+- 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, but **explicitly note "not cross-verified by advisor" in your final output**. Do not block or retry in a loop.`;
 
 // ---------------- 3. 顾问 persona system prompt ----------------
 const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技术顾问，为正在独立执行任务的另一个 AI 助手提供第二意见评审。
@@ -64,6 +76,14 @@ const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技
 你会看到该助手当前会话中受预算约束的相关记录——包括首要需求、近期交流、它的思考过程、当前方案
 和关键工具结果与执行结果，以及它现在想让你重点关注的内容（如果有）。
 
+重要：你**没有工具访问权，无法自行验证任何事实**。你只是提供一个不同视角的怀疑和推理，
+不能把自己的推测当成确定结论。每条指出的问题都要明确标注：
+  - 【有证据】：基于记录里明确出现的代码/测试结果/事实
+  - 【推断】：基于已有信息的合理推断，但未被证实
+  - 【存疑】：信息不足，需要执行助手回去核实
+不要过度自信，不要给出确定性语气的未验证判断——执行助手会对你的意见逐条做验证，
+夸大其词会被判定为误报。
+
 审视时请做到：
 - 像资深工程师做方案评审/代码评审一样直接、具体——发现问题就明说，不要无条件附和或说套话。
 - 优先检查：方案是否遗漏了风险或边界情况、诊断是否真的找到了根因还是只是让症状消失、
@@ -76,7 +96,16 @@ const ADVISOR_SYSTEM_PROMPT = `你是一位经验丰富的全栈开发专家技
   或换个方式绕开，都要点出来。
 - 结论必须基于你在历史记录里看到的实际证据，不要脱离上下文给泛泛的通用建议；
   被省略的记录（尤其工具结果原文）所涉及的判断，明说你无法核实。
-- 篇幅精炼：只讲最关键的 1-3 点，不要复述历史、不要客套开场白。`;
+- 篇幅精炼：只讲最关键的 1-3 点，不要复述历史、不要客套开场白。
+
+关于「带着反证回来」的那一次咨询（助手被要求这样做，不是在质疑你）：
+当它说「我实测是 X，你上次建议 Y」时，它手里的是一手证据，你手里的是推理——
+默认它的观测为真，然后只回答一个问题：**哪个约束更硬**。
+  - 你上次漏看了它给出的证据 → 直接认，并说清结论怎么变。
+  - 它的观测其实没测到你担心的那一层（测了被改的函数，而真实调用路径根本走不到）
+    → 指出这个错位，并说要测什么才算数。
+  - 两者都成立、只是适用范围不同 → 说清各自的边界，别硬选一个。
+不要为了显得一致而坚持原判，也不要因为被反驳就整个收回——两种都会让它失去判断依据。`;
 
 // ---------------- 4. 消息构造（纯函数，单独导出可测） ----------------
 
@@ -234,12 +263,19 @@ function fitAdvisorBudget(messages: Message[], inputBudget: number): Message[] {
     selected.push(first);
     used += countMessagesTokens([first]);
   }
+  // 从最近往前收，**装不下就停**（break，不是 continue）。
+  //
+  // ⚠️ 曾经是 continue：一条大消息放不下就跳过它、继续往前捡更小的旧消息。
+  // 结果是给顾问一段**中间有洞**的对话 —— 而洞恰好开在信息量最大的地方（长工具
+  // 结果、完整方案文本），偏偏下面那句省略提示还写着「保留最初需求和最近相关记录」，
+  // 顾问于是把两条本不相邻的消息读成前后相接，在残缺的因果链上给出自信结论。
+  // 宁可少给，不可给错：连续的尾部 + 如实说明从哪里开始省略。
   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;
+    if (used + cost > inputBudget) break;
     recent.unshift(message);
     used += cost;
   }
@@ -348,19 +384,26 @@ export async function runAdvisor(
       ok: false,
       error:
         '顾问模型未配置。请在设置 → 模型中完成专家顾问配置。' +
-        '可继续凭自己判断推进，不必等待顾问。',
+        '本回合后续不要再次尝试调用 Advisor；可继续凭自己判断推进，不必等待顾问。',
     };
   }
 
   if (!advisor.enabled) {
     return {
       ok: false,
-      error: '顾问模型当前已关闭（/advisor on 开启）。可继续凭自己判断推进，不必等待顾问。',
+      error:
+        '顾问模型当前已关闭（/advisor on 开启）。' +
+        '本回合后续不要再次尝试调用 Advisor；可继续凭自己判断推进，不必等待顾问。',
     };
   }
 
   if (advisor.mode === 'manual' && ctx?.advisorInvocation !== 'manual') {
-    return { ok: false, error: '顾问模型当前为“仅手动”模式；请使用 /advisor ask 发起咨询。' };
+    return {
+      ok: false,
+      error:
+        '顾问模型当前为"仅手动"模式；请使用 /advisor ask 发起咨询。' +
+        '本回合后续不要再次尝试自动调用 Advisor。',
+    };
   }
 
   if (ctx?.advisorCalls && ctx.advisorCalls.used >= ctx.advisorCalls.max) {
@@ -507,6 +550,33 @@ export const advisorTool: Tool<AdvisorInput> = {
   isConcurrencySafe: false,
   maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
   interruptBehavior: () => 'cancel',
+  /**
+   * 动态可用性探测：未配置 / 已关闭 / 仅手动模式 → 工具不暴露给模型。
+   * 对齐 ComputerUse / WebBrowser 的模式：关闭时工具直接从 LLM 视野消失，
+   * 避免"看到工具但调不了→反复尝试"的流畅度问题。
+   *
+   * signature 随 enabled/mode/modelId 变化，确保配置改动后工具集签名更新、
+   * 模型下一轮拿到的是新工具列表。
+   */
+  resolveAvailability() {
+    // 走同步探测（读内存快照），不触发磁盘 IO；
+    // resolveAvailability 是工具集构造阶段的同步调用，不能 await。
+    const avail = configService.advisorAvailabilitySync();
+
+    // ⚠️ 安全兜底：如果 snapshot 尚未初始化（极端情况：工具集构造发生在任何
+    // configService 异步调用之前），宁可返回 available=true 让工具显示出来
+    // （调用时 runAdvisor 会做真正的 fresh reload 校验），也不能误判为
+    // "未配置" 导致 Advisor 从工具列表里消失——少一个工具比多一个工具严重得多。
+    if (avail.configured && !avail.enabled) {
+      return { available: false, signature: 'disabled' };
+    }
+    if (avail.configured && avail.mode === 'manual') {
+      return { available: false, signature: 'manual-only' };
+    }
+    // 未初始化 / 已配置且可用 → 都显示工具（未配置时调用会有明确错误提示）
+    // modelId 进签名：不同顾问模型 = 不同能力 = 工具语义不同。
+    return { available: true, signature: avail.modelId ?? 'initializing' };
+  },
   call,
   callWithContext: runAdvisor,
 };

package/src/tools/bash/bash.js

@@ -56,7 +56,7 @@ import { requestUserChoice } from '../../askBridge.js';
 import { classifyCommand } from '../../irreversible/rules.js';
 import { startBackgroundTask } from '../tasks/backgroundTaskService.js';
 import { processExecutionMetadata } from '../tasks/processEvidence.js';
-import { permanentDeleteReason } from '../shared/permanentDeleteGuard.js';
+import { permanentDeleteReason, } from '../shared/permanentDeleteGuard.js';
 import { ToolOutputStore } from '../shared/toolOutputStore.js';
 // ---------------- 0. 常量 ----------------
 const DEFAULT_TIMEOUT_MS = 120_000; // 2 min
@@ -105,6 +105,16 @@ function detectWindowsBash() {
     return null;
 }
 const WIN_BASH = detectWindowsBash();
+/**
+ * 本工具这一刻**真正**把命令交给谁执行。
+ *
+ * 单一出处：description（告诉模型该写哪种语法）与 permanentDeleteGuard（按哪套动词
+ * 匹配删除命令）必须看同一个判断，否则就会出现「description 说这是 cmd、守卫却按
+ * bash 匹配」这种两头对不上的裂缝 —— del / rd 会因此直接穿过全部三层防护。
+ */
+function effectiveShellKind() {
+    return process.platform === 'win32' && !WIN_BASH ? 'cmd' : 'bash';
+}
 /**
  * G1：stdout / stderr 即时缓冲上限（各自）。命令狂输出（如 cat 大文件 / yes）时，
  * 在最终统一截断之前先把内存封顶，防 OOM。取最终展示截断阈值的 2 倍 —— 正常输出不受影响，
@@ -311,8 +321,11 @@ Some commands return non-zero exit codes for informational (non-error) reasons.
  - \`test\` / \`[\` exit 1 → condition is false (the answer to a question, not a failure)
 Only exit codes ≥ 2 from these commands indicate a real failure. For all other commands, non-zero exit codes are treated as failures normally.
 
-# Safety
-The following command patterns are blocked at the tool level and will fail before execution (no need to try them):
+# Safety - three levels, from strict to lenient
+
+## 1. Blocked outright (fails before execution - do NOT retry with variants)
+
+Catastrophic commands (no legitimate use):
  - \`rm -rf /\` and variants targeting root, $HOME, ~, or system directories (/etc, /usr, /bin, /Windows, /Users, /home, ...)
  - Filesystem destruction: \`mkfs\`, \`format X:\`, \`dd of=/dev/sdX\`, redirects to raw block devices
  - Power management: \`shutdown\`, \`reboot\`, \`halt\`, \`poweroff\`, \`init 0/6\`
@@ -320,9 +333,37 @@ The following command patterns are blocked at the tool level and will fail befor
  - Pipe-to-shell from network: \`curl ... | sh\`, \`wget ... | bash\`, etc.
  - \`chmod 777 /\`, Windows full-disk \`del /s\` / \`rmdir /s\`, \`diskpart\`
 
-If you have a legitimate use case that requires one of the above patterns, ask the user to run the command themselves in their terminal — do not try to bypass the check.
+Permanent deletion (bypasses the OS Trash / Recycle Bin - use the Trash tool instead):
+ - \`rm\`, \`unlink\`, \`rmdir\` (any shell-level file/dir deletion, any target)
+ - \`find ... -delete\`
+ - \`git clean -f\` / \`git clean --force\` (\`-n\` / \`--dry-run\` is fine)
+
+To delete files or directories use the **Trash** tool (\`action: "move"\` - recoverable); to clean Git untracked files use Trash with \`action: "git-clean"\`.
+Do NOT work around this by switching to \`find -delete\`, Python \`os.remove\`, Node \`fs.rm\`, or other shell variants - they are blocked the same way.
+If a permanent deletion is truly required, ask the user to run it themselves in their terminal.
+
+## 2. Requires user confirmation (irreversible)
+
+These have legitimate uses but destroy the last copy - execution pauses and asks the user to confirm. In non-interactive contexts (sub-agents, cron, batch mode) they are automatically cancelled.
+ - \`git push --force\` / \`-f\`, and \`git push origin +branch\` (+refspec = force push)
+ - \`git push --delete <branch>\` / \`git push :<branch>\` (deleting remote branches)
+ - \`git filter-branch\` / \`git filter-repo\` (rewriting history)
+ - \`git reflog expire --expire=now\` / \`git gc --prune=now\` (destroying reflog)
+ - \`shred -u\` / \`shred --remove\` (overwrite and delete - unrecoverable)
+ - SQL data destruction: \`DROP DATABASE\`, \`DROP TABLE\`, \`TRUNCATE TABLE\`
+
+## 3. Warning only (command still runs)
+
+These execute normally; a \`⚠️ 警告:\` line is prepended to the output as a reminder. They are NOT blocked.
+ - \`git reset --hard\` (reflog keeps it recoverable)
+ - \`git push --force-with-lease\` (rejects if the remote has unseen commits - the safe force-push form)
+ - \`git checkout -- .\` / \`git restore .\` (discards uncommitted changes)
+ - \`git branch -D\`, \`git stash drop\` / \`git stash clear\` (local, recoverable via reflog in most cases)
+ - \`git commit --amend\`, \`git commit --no-verify\`
+ - \`DELETE FROM ...\` (SQL row deletion; DROP/TRUNCATE are in level 2)
+ - \`kubectl delete\`, \`terraform destroy\`
 
-Separately, Bash scans for common destructive-but-recoverable patterns (\`git reset --hard\`, \`git push -f\` / \`--force\` / \`--force-with-lease\`, \`git checkout .\`, \`git restore .\`, \`git clean -f\`, \`git stash drop/clear\`, \`git branch -D\`, \`git commit --amend\` / \`--no-verify\`, \`rm -rf <path>\`, \`DROP TABLE\`, \`TRUNCATE\`, \`DELETE FROM\`, \`kubectl delete\`, \`terraform destroy\`, etc.) and prepends a \`⚠️ 警告:\` line to the output. These commands are NOT blocked — the warning is informational. Treat it as a signal to double-check intent and surface the warning to the user when relevant.${process.platform !== 'win32'
+Regular Git operations (commit, add, status, log, diff, pull, fetch, checkout <branch>, merge, rebase, etc.) run without extra restrictions.${process.platform !== 'win32'
     ? ''
     : WIN_BASH
         ? `
@@ -349,7 +390,11 @@ async function call(input, signal, context) {
             error: `安全检查拒绝执行：${forbiddenReason}\n命令：${command}`,
         };
     }
-    const permanentDelete = permanentDeleteReason(command, 'bash');
+    // 传**实际执行命令的 shell**，不是工具名：win32 上找不到 Git Bash 时下面走的是
+    // cmd.exe（见 WIN_BASH 探测），description 也会告诉模型「这里是 cmd」，模型于是写
+    // del / rd —— 按 'bash' 匹配的话这两个词一个都拦不住（黑名单与 irreversible 规则表
+    // 同样只认 POSIX 形态），等于三层全空。
+    const permanentDelete = permanentDeleteReason(command, effectiveShellKind());
     if (permanentDelete)
         return { ok: false, error: `永久删除检查拒绝执行：${permanentDelete}\n命令：${command}` };
     // 4a-1. 不可逆动作闸门：毁掉「最后一份副本」的命令要**停下来问人**。

package/src/tools/bash/bash.ts

@@ -63,7 +63,10 @@ import { requestUserChoice } from '../../askBridge.js';
 import { classifyCommand } from '../../irreversible/rules.js';
 import { startBackgroundTask } from '../tasks/backgroundTaskService.js';
 import { processExecutionMetadata } from '../tasks/processEvidence.js';
-import { permanentDeleteReason } from '../shared/permanentDeleteGuard.js';
+import {
+  permanentDeleteReason,
+  type ShellKind,
+} from '../shared/permanentDeleteGuard.js';
 import { ToolOutputStore } from '../shared/toolOutputStore.js';
 
 // ---------------- 0. 常量 ----------------
@@ -112,6 +115,17 @@ function detectWindowsBash(): string | null {
 
 const WIN_BASH = detectWindowsBash();
 
+/**
+ * 本工具这一刻**真正**把命令交给谁执行。
+ *
+ * 单一出处：description（告诉模型该写哪种语法）与 permanentDeleteGuard（按哪套动词
+ * 匹配删除命令）必须看同一个判断，否则就会出现「description 说这是 cmd、守卫却按
+ * bash 匹配」这种两头对不上的裂缝 —— del / rd 会因此直接穿过全部三层防护。
+ */
+function effectiveShellKind(): ShellKind {
+  return process.platform === 'win32' && !WIN_BASH ? 'cmd' : 'bash';
+}
+
 /**
  * G1：stdout / stderr 即时缓冲上限（各自）。命令狂输出（如 cat 大文件 / yes）时，
  * 在最终统一截断之前先把内存封顶，防 OOM。取最终展示截断阈值的 2 倍 —— 正常输出不受影响，
@@ -332,8 +346,11 @@ Some commands return non-zero exit codes for informational (non-error) reasons.
  - \`test\` / \`[\` exit 1 → condition is false (the answer to a question, not a failure)
 Only exit codes ≥ 2 from these commands indicate a real failure. For all other commands, non-zero exit codes are treated as failures normally.
 
-# Safety
-The following command patterns are blocked at the tool level and will fail before execution (no need to try them):
+# Safety - three levels, from strict to lenient
+
+## 1. Blocked outright (fails before execution - do NOT retry with variants)
+
+Catastrophic commands (no legitimate use):
  - \`rm -rf /\` and variants targeting root, $HOME, ~, or system directories (/etc, /usr, /bin, /Windows, /Users, /home, ...)
  - Filesystem destruction: \`mkfs\`, \`format X:\`, \`dd of=/dev/sdX\`, redirects to raw block devices
  - Power management: \`shutdown\`, \`reboot\`, \`halt\`, \`poweroff\`, \`init 0/6\`
@@ -341,9 +358,37 @@ The following command patterns are blocked at the tool level and will fail befor
  - Pipe-to-shell from network: \`curl ... | sh\`, \`wget ... | bash\`, etc.
  - \`chmod 777 /\`, Windows full-disk \`del /s\` / \`rmdir /s\`, \`diskpart\`
 
-If you have a legitimate use case that requires one of the above patterns, ask the user to run the command themselves in their terminal — do not try to bypass the check.
-
-Separately, Bash scans for common destructive-but-recoverable patterns (\`git reset --hard\`, \`git push -f\` / \`--force\` / \`--force-with-lease\`, \`git checkout .\`, \`git restore .\`, \`git clean -f\`, \`git stash drop/clear\`, \`git branch -D\`, \`git commit --amend\` / \`--no-verify\`, \`rm -rf <path>\`, \`DROP TABLE\`, \`TRUNCATE\`, \`DELETE FROM\`, \`kubectl delete\`, \`terraform destroy\`, etc.) and prepends a \`⚠️ 警告:\` line to the output. These commands are NOT blocked — the warning is informational. Treat it as a signal to double-check intent and surface the warning to the user when relevant.${
+Permanent deletion (bypasses the OS Trash / Recycle Bin - use the Trash tool instead):
+ - \`rm\`, \`unlink\`, \`rmdir\` (any shell-level file/dir deletion, any target)
+ - \`find ... -delete\`
+ - \`git clean -f\` / \`git clean --force\` (\`-n\` / \`--dry-run\` is fine)
+
+To delete files or directories use the **Trash** tool (\`action: "move"\` - recoverable); to clean Git untracked files use Trash with \`action: "git-clean"\`.
+Do NOT work around this by switching to \`find -delete\`, Python \`os.remove\`, Node \`fs.rm\`, or other shell variants - they are blocked the same way.
+If a permanent deletion is truly required, ask the user to run it themselves in their terminal.
+
+## 2. Requires user confirmation (irreversible)
+
+These have legitimate uses but destroy the last copy - execution pauses and asks the user to confirm. In non-interactive contexts (sub-agents, cron, batch mode) they are automatically cancelled.
+ - \`git push --force\` / \`-f\`, and \`git push origin +branch\` (+refspec = force push)
+ - \`git push --delete <branch>\` / \`git push :<branch>\` (deleting remote branches)
+ - \`git filter-branch\` / \`git filter-repo\` (rewriting history)
+ - \`git reflog expire --expire=now\` / \`git gc --prune=now\` (destroying reflog)
+ - \`shred -u\` / \`shred --remove\` (overwrite and delete - unrecoverable)
+ - SQL data destruction: \`DROP DATABASE\`, \`DROP TABLE\`, \`TRUNCATE TABLE\`
+
+## 3. Warning only (command still runs)
+
+These execute normally; a \`⚠️ 警告:\` line is prepended to the output as a reminder. They are NOT blocked.
+ - \`git reset --hard\` (reflog keeps it recoverable)
+ - \`git push --force-with-lease\` (rejects if the remote has unseen commits - the safe force-push form)
+ - \`git checkout -- .\` / \`git restore .\` (discards uncommitted changes)
+ - \`git branch -D\`, \`git stash drop\` / \`git stash clear\` (local, recoverable via reflog in most cases)
+ - \`git commit --amend\`, \`git commit --no-verify\`
+ - \`DELETE FROM ...\` (SQL row deletion; DROP/TRUNCATE are in level 2)
+ - \`kubectl delete\`, \`terraform destroy\`
+
+Regular Git operations (commit, add, status, log, diff, pull, fetch, checkout <branch>, merge, rebase, etc.) run without extra restrictions.${
   process.platform !== 'win32'
     ? ''
     : WIN_BASH
@@ -374,7 +419,11 @@ async function call(input: BashInput, signal?: AbortSignal, context?: ToolCallCo
       error: `安全检查拒绝执行：${forbiddenReason}\n命令：${command}`,
     };
   }
-  const permanentDelete = permanentDeleteReason(command, 'bash');
+  // 传**实际执行命令的 shell**，不是工具名：win32 上找不到 Git Bash 时下面走的是
+  // cmd.exe（见 WIN_BASH 探测），description 也会告诉模型「这里是 cmd」，模型于是写
+  // del / rd —— 按 'bash' 匹配的话这两个词一个都拦不住（黑名单与 irreversible 规则表
+  // 同样只认 POSIX 形态），等于三层全空。
+  const permanentDelete = permanentDeleteReason(command, effectiveShellKind());
   if (permanentDelete) return { ok:false, error:`永久删除检查拒绝执行：${permanentDelete}\n命令：${command}` };
 
   // 4a-1. 不可逆动作闸门：毁掉「最后一份副本」的命令要**停下来问人**。