minimal-agent 0.14.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Bun-first 的本地 Agent 内核，支持工具、插件、工作流、上下文压缩、长期记忆与 OpenAI 兼容接口；Tauri 桌面宿主和 Node.js npm 发布可复用同一内核",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",

package/src/advisor/advisorCoordinator.js

@@ -58,7 +58,23 @@ function versionsOf(metadata) {
         evidenceVersion: metadata.evidenceVersion,
     };
 }
-function checkpointKey(checkpoint, versions) {
+function checkpointKey(checkpoint, versions, signature) {
+    // pre-execution/pre-delivery 的意图是"本任务版本内只问一次"（见 beforeTool()
+    // 的 reason 文案"即将进行本任务版本的首次实质写入"）。旧实现把 workVersion/
+    // evidenceVersion 也编进 key，而这两个计数器在几乎每次成功的工具调用（包括
+    // 纯 Read/Grep，见 observeToolResult）后都会变化——"首次"因此从未真正生效，
+    // 任务里的每一次不同写入都会重新触发一轮完整 Advisor+AdvisorDecision，同时
+    // 让 MAX_CONSECUTIVE_DEFERRALS 的连续暂缓降级网因为 key 很少连续重复而基本
+    // 失效。改成只用 taskVersion，让这两个检查点在一个任务版本内真正只问一次。
+    if (checkpoint === 'pre-execution' || checkpoint === 'pre-delivery') {
+        return `${versions.taskVersion}:${checkpoint}`;
+    }
+    // high-risk 的意图相反：每个不同的危险动作都该有自己的把关，但不能被"中间
+    // 插了一次无关的成功调用"误判成新动作——用动作自身的签名代替会漂移的全局
+    // 版本计数器，同一动作的重试才能被正确识别为"同一个"。
+    if (checkpoint === 'high-risk') {
+        return `${versions.taskVersion}:high-risk:${signature ?? 'unknown'}`;
+    }
     return `${versions.taskVersion}:${checkpoint}:${versions.workVersion}:${versions.evidenceVersion}`;
 }
 /**
@@ -166,6 +182,9 @@ export class AdvisorCoordinator {
         const successful = this.#successfulConsultationsByKey.get(this.#pending.checkpointKey) ?? 0;
         return successful <= MAX_FREE_RECONCILIATIONS_PER_CHECKPOINT;
     }
+    get hasActiveGate() {
+        return this.#required !== undefined || this.#softCheckpoint !== undefined;
+    }
     setAvailable(available) {
         this.#advisorAvailable = available;
     }
@@ -193,7 +212,15 @@ export class AdvisorCoordinator {
             return this.#deferPending('顾问意见已返回，但尚未调用 AdvisorDecision 记录主 Agent 的采纳判断。');
         }
         if (semantics.highRisk) {
-            return this.requestCheckpoint('high-risk', semantics.riskReason ?? '即将执行不可逆操作');
+            // 用动作自身的签名（工具名+参数的短哈希）代替会被无关调用带动的全局版本
+            // 计数器：同一个危险动作的重试仍归到同一个 key，不同的危险动作各自独立
+            // 把关，两者都不受"中间插了一次成功的 Read"影响。
+            const signature = crypto
+                .createHash('sha1')
+                .update(`${call.function.name}:${call.function.arguments}`)
+                .digest('hex')
+                .slice(0, 16);
+            return this.requestCheckpoint('high-risk', semantics.riskReason ?? '即将执行不可逆操作', { signature });
         }
         if (semantics.mutatesWorkspace) {
             return this.requestCheckpoint('pre-execution', '即将进行本任务版本的首次实质写入');
@@ -204,7 +231,7 @@ export class AdvisorCoordinator {
         if (!this.#advisorAvailable)
             return { allow: true };
         this.#commitTask();
-        const key = checkpointKey(checkpoint, this.versions);
+        const key = checkpointKey(checkpoint, this.versions, options.signature);
         if (this.#completed.has(key))
             return { allow: true };
         if (options.oneShot && this.#deferredOnce.has(key)) {
@@ -287,7 +314,13 @@ export class AdvisorCoordinator {
             : this.#required ??
                 this.#softCheckpoint ?? {
                 checkpoint: 'pre-execution',
-                key: checkpointKey('pre-execution', this.versions),
+                // 刻意不用 checkpointKey('pre-execution', ...)：这个分支只在没有任何
+                // 活跃检查点时才会走到，即模型是主动/复核性质地咨询。pre-execution
+                // 的 key 现在只随 taskVersion 变化（见 checkpointKey 头注），如果这里
+                // 复用同一个 key，一次纯主动咨询 + AdvisorDecision 就会把 #completed
+                // 里真正的首次写入检查点提前标记掉，导致它对本任务版本永久失效。
+                // 'voluntary' 是任何真实检查点都不会产生的命名空间，两者永远不会撞车。
+                key: `${this.versions.taskVersion}:voluntary`,
             };
         return {
             kind: 'advisor_consultation',

package/src/advisor/advisorCoordinator.ts

@@ -92,7 +92,24 @@ function versionsOf(
 function checkpointKey(
   checkpoint: AdvisorCheckpoint,
   versions: AdvisorVersions,
+  signature?: string,
 ): string {
+  // pre-execution/pre-delivery 的意图是"本任务版本内只问一次"（见 beforeTool()
+  // 的 reason 文案"即将进行本任务版本的首次实质写入"）。旧实现把 workVersion/
+  // evidenceVersion 也编进 key，而这两个计数器在几乎每次成功的工具调用（包括
+  // 纯 Read/Grep，见 observeToolResult）后都会变化——"首次"因此从未真正生效，
+  // 任务里的每一次不同写入都会重新触发一轮完整 Advisor+AdvisorDecision，同时
+  // 让 MAX_CONSECUTIVE_DEFERRALS 的连续暂缓降级网因为 key 很少连续重复而基本
+  // 失效。改成只用 taskVersion，让这两个检查点在一个任务版本内真正只问一次。
+  if (checkpoint === 'pre-execution' || checkpoint === 'pre-delivery') {
+    return `${versions.taskVersion}:${checkpoint}`;
+  }
+  // high-risk 的意图相反：每个不同的危险动作都该有自己的把关，但不能被"中间
+  // 插了一次无关的成功调用"误判成新动作——用动作自身的签名代替会漂移的全局
+  // 版本计数器，同一动作的重试才能被正确识别为"同一个"。
+  if (checkpoint === 'high-risk') {
+    return `${versions.taskVersion}:high-risk:${signature ?? 'unknown'}`;
+  }
   return `${versions.taskVersion}:${checkpoint}:${versions.workVersion}:${versions.evidenceVersion}`;
 }
 
@@ -245,6 +262,10 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
     return successful <= MAX_FREE_RECONCILIATIONS_PER_CHECKPOINT;
   }
 
+  get hasActiveGate(): boolean {
+    return this.#required !== undefined || this.#softCheckpoint !== undefined;
+  }
+
   setAvailable(available: boolean): void {
     this.#advisorAvailable = available;
   }
@@ -283,9 +304,18 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
       );
     }
     if (semantics.highRisk) {
+      // 用动作自身的签名（工具名+参数的短哈希）代替会被无关调用带动的全局版本
+      // 计数器：同一个危险动作的重试仍归到同一个 key，不同的危险动作各自独立
+      // 把关，两者都不受"中间插了一次成功的 Read"影响。
+      const signature = crypto
+        .createHash('sha1')
+        .update(`${call.function.name}:${call.function.arguments}`)
+        .digest('hex')
+        .slice(0, 16);
       return this.requestCheckpoint(
         'high-risk',
         semantics.riskReason ?? '即将执行不可逆操作',
+        { signature },
       );
     }
     if (semantics.mutatesWorkspace) {
@@ -300,11 +330,11 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
   requestCheckpoint(
     checkpoint: AdvisorCheckpoint,
     reason: string,
-    options: { oneShot?: boolean } = {},
+    options: { oneShot?: boolean; signature?: string } = {},
   ): CheckpointDecision {
     if (!this.#advisorAvailable) return { allow: true };
     this.#commitTask();
-    const key = checkpointKey(checkpoint, this.versions);
+    const key = checkpointKey(checkpoint, this.versions, options.signature);
     if (this.#completed.has(key)) return { allow: true };
     if (options.oneShot && this.#deferredOnce.has(key)) {
       this.#required = undefined;
@@ -402,7 +432,13 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
       : this.#required ??
         this.#softCheckpoint ?? {
           checkpoint: 'pre-execution' as const,
-          key: checkpointKey('pre-execution', this.versions),
+          // 刻意不用 checkpointKey('pre-execution', ...)：这个分支只在没有任何
+          // 活跃检查点时才会走到，即模型是主动/复核性质地咨询。pre-execution
+          // 的 key 现在只随 taskVersion 变化（见 checkpointKey 头注），如果这里
+          // 复用同一个 key，一次纯主动咨询 + AdvisorDecision 就会把 #completed
+          // 里真正的首次写入检查点提前标记掉，导致它对本任务版本永久失效。
+          // 'voluntary' 是任何真实检查点都不会产生的命名空间，两者永远不会撞车。
+          key: `${this.versions.taskVersion}:voluntary`,
         };
     return {
       kind: 'advisor_consultation',

package/src/cli/quickModelSetup.js

@@ -9,10 +9,17 @@ export function QuickModelSetup({ onDone }) {
     const [adding, setAdding] = useState(false);
     const [readOnly, setReadOnly] = useState(false);
     const [message, setMessage] = useState(null);
+    // config.json 与 env 都不存在时 reload() 返回 config:null——这是唯一能安全
+    // 区分「本机从未配置过」与「配置存在但暂无可用模型」的信号。只在前者把
+    // 内置浏览器的 CLI 默认值显式落盘为关闭（见 DEFAULT_BROWSER_CONFIG 的注释：
+    // 这个共享常量本身仍是 true，Desktop 走同一常量不受影响；只有 CLI 首次建档
+    // 这一次性写入路径改默认）。
+    const [freshInstall, setFreshInstall] = useState(false);
     useEffect(() => {
         void configService.reload().then((snapshot) => {
             setReadOnly(snapshot.readOnly);
             setModels(snapshot.config?.models ?? []);
+            setFreshInstall(snapshot.config === null);
         });
     }, []);
     useInput((input, key) => {
@@ -50,7 +57,11 @@ export function QuickModelSetup({ onDone }) {
         return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsx(Text, { color: "yellow", bold: true, children: "\u5F53\u524D\u4E3A\u73AF\u5883\u53D8\u91CF\u53EA\u8BFB\u914D\u7F6E\uFF0C\u4F46\u6CA1\u6709\u53EF\u7528\u57FA\u5EA7\u6A21\u578B" }), _jsx(Text, { children: "\u8BF7\u68C0\u67E5 MINIMAL_AGENT_BASE_URL\u3001MINIMAL_AGENT_API_KEY \u548C MINIMAL_AGENT_MODEL\uFF0C\u7136\u540E\u91CD\u65B0\u542F\u52A8\u3002" })] }));
     if (adding)
         return (_jsx(ProviderWizard, { quick: true, setAsBase: true, onDone: () => {
-                void configService.provider().then((provider) => {
+                void (freshInstall
+                    ? configService.savePatch({ browser: { enabled: false } })
+                    : Promise.resolve())
+                    .then(() => configService.provider())
+                    .then((provider) => {
                     if (provider)
                         onDone(provider);
                 });

package/src/cli/quickModelSetup.tsx

@@ -16,10 +16,17 @@ export function QuickModelSetup({ onDone }: Props): JSX.Element {
   const [adding, setAdding] = useState(false);
   const [readOnly, setReadOnly] = useState(false);
   const [message, setMessage] = useState<string | null>(null);
+  // config.json 与 env 都不存在时 reload() 返回 config:null——这是唯一能安全
+  // 区分「本机从未配置过」与「配置存在但暂无可用模型」的信号。只在前者把
+  // 内置浏览器的 CLI 默认值显式落盘为关闭（见 DEFAULT_BROWSER_CONFIG 的注释：
+  // 这个共享常量本身仍是 true，Desktop 走同一常量不受影响；只有 CLI 首次建档
+  // 这一次性写入路径改默认）。
+  const [freshInstall, setFreshInstall] = useState(false);
   useEffect(() => {
     void configService.reload().then((snapshot) => {
       setReadOnly(snapshot.readOnly);
       setModels(snapshot.config?.models ?? []);
+      setFreshInstall(snapshot.config === null);
     });
   }, []);
   useInput((input, key) => {
@@ -63,9 +70,14 @@ export function QuickModelSetup({ onDone }: Props): JSX.Element {
         quick
         setAsBase
         onDone={() => {
-          void configService.provider().then((provider) => {
-            if (provider) onDone(provider);
-          });
+          void (freshInstall
+            ? configService.savePatch({ browser: { enabled: false } })
+            : Promise.resolve()
+          )
+            .then(() => configService.provider())
+            .then((provider) => {
+              if (provider) onDone(provider);
+            });
         }}
         onCancel={() => setAdding(false)}
       />

package/src/cli/wizards/providerPresets.js

@@ -20,22 +20,32 @@ export const PRESETS = [
     },
     {
         // 火山方舟 ARK Coding Plan —— 一个 endpoint 后挂多个 model id，
-        // model 字段大小写严格匹配（'glm-5.1' 而非 'GLM-5.1'）。
+        // model 字段大小写严格匹配（'glm-5.3' 而非 'GLM-5.3'）。
+        // ⚠️ 必须是 /api/coding/v3/（Coding Plan 折扣路由），不是 /api/v3/
+        // （官网原价路由）——控制台原文明确警告后者「会产生额外费用」。
+        // 2026-09 按控制台最新模型列表刷新（原列表含已下线的 doubao-seed-2.0-pro/
+        // doubao-seed-code/glm-5.1/minimax-latest/deepseek-v3.2/kimi-k2.6）。
         name: 'volces',
         label: '火山方舟 Coding Plan (ARK)',
         baseURL: 'https://ark.cn-beijing.volces.com/api/coding/v3/chat/completions',
         models: [
-            'doubao-seed-2.0-pro',
-            'doubao-seed-2.0-code',
-            'doubao-seed-code',
-            'glm-5.1',
-            'minimax-latest',
-            'deepseek-v3.2',
+            'auto',
+            'doubao-seed-evolving',
+            'doubao-seed-2.1-turbo',
+            'doubao-seed-2.0-lite',
+            'glm-5.3-flash',
+            'glm-5.3',
+            'deepseek-v4-pro',
+            'deepseek-v4-flash',
             'kimi-k2.7-code',
-            'kimi-k2.6',
+            'minimax-m3',
         ],
         contextWindow: 204_800,
         modelContextWindows: {
+            // 控制台标注「支持 1M 超长上下文」的三个。
+            'doubao-seed-evolving': 1_000_000,
+            'glm-5.3': 1_000_000,
+            'deepseek-v4-pro': 1_000_000,
             'kimi-k2.7-code': 512_000,
         },
     },

package/src/cli/wizards/providerPresets.ts

@@ -35,22 +35,32 @@ export const PRESETS: ProviderPreset[] = [
   },
   {
     // 火山方舟 ARK Coding Plan —— 一个 endpoint 后挂多个 model id，
-    // model 字段大小写严格匹配（'glm-5.1' 而非 'GLM-5.1'）。
+    // model 字段大小写严格匹配（'glm-5.3' 而非 'GLM-5.3'）。
+    // ⚠️ 必须是 /api/coding/v3/（Coding Plan 折扣路由），不是 /api/v3/
+    // （官网原价路由）——控制台原文明确警告后者「会产生额外费用」。
+    // 2026-09 按控制台最新模型列表刷新（原列表含已下线的 doubao-seed-2.0-pro/
+    // doubao-seed-code/glm-5.1/minimax-latest/deepseek-v3.2/kimi-k2.6）。
     name: 'volces',
     label: '火山方舟 Coding Plan (ARK)',
     baseURL: 'https://ark.cn-beijing.volces.com/api/coding/v3/chat/completions',
     models: [
-      'doubao-seed-2.0-pro',
-      'doubao-seed-2.0-code',
-      'doubao-seed-code',
-      'glm-5.1',
-      'minimax-latest',
-      'deepseek-v3.2',
+      'auto',
+      'doubao-seed-evolving',
+      'doubao-seed-2.1-turbo',
+      'doubao-seed-2.0-lite',
+      'glm-5.3-flash',
+      'glm-5.3',
+      'deepseek-v4-pro',
+      'deepseek-v4-flash',
       'kimi-k2.7-code',
-      'kimi-k2.6',
+      'minimax-m3',
     ],
     contextWindow: 204_800,
     modelContextWindows: {
+      // 控制台标注「支持 1M 超长上下文」的三个。
+      'doubao-seed-evolving': 1_000_000,
+      'glm-5.3': 1_000_000,
+      'deepseek-v4-pro': 1_000_000,
       'kimi-k2.7-code': 512_000,
     },
   },

package/src/loop.js

@@ -234,7 +234,15 @@ export async function* runQuery(userInput, options) {
         history,
         sessionState,
         // 配额随本回合工作量增长（见 advisorQuotaFor）；下面每轮工具执行完后上调。
-        advisorCalls: { used: 0, max: advisorQuotaFor(0) },
+        // mandatoryUsed/mandatoryMax 是独立的"强制检查点"配额池，不随工具调用数
+        // 增长——它是安全闸门的固定配额，不是"干得越多奖励越多"的自愿咨询配额；
+        // 复用 ADVISOR_QUOTA_MAX 而不新增字面量，避免和自愿池的封顶各写各的漂移。
+        advisorCalls: {
+            used: 0,
+            max: advisorQuotaFor(0),
+            mandatoryUsed: 0,
+            mandatoryMax: ADVISOR_QUOTA_MAX,
+        },
         advisorInvocation: 'agent',
         // Agent 等派生工具起嵌套子查询所需的运行态：与主循环同一 provider、
         // 同一审批闸门（子 agent 不绕过宿主策略）。agentCalls 与 advisorCalls 同构，

package/src/loop.ts

@@ -436,7 +436,15 @@ export async function* runQuery(
     history,
     sessionState,
     // 配额随本回合工作量增长（见 advisorQuotaFor）；下面每轮工具执行完后上调。
-    advisorCalls: { used: 0, max: advisorQuotaFor(0) },
+    // mandatoryUsed/mandatoryMax 是独立的"强制检查点"配额池，不随工具调用数
+    // 增长——它是安全闸门的固定配额，不是"干得越多奖励越多"的自愿咨询配额；
+    // 复用 ADVISOR_QUOTA_MAX 而不新增字面量，避免和自愿池的封顶各写各的漂移。
+    advisorCalls: {
+      used: 0,
+      max: advisorQuotaFor(0),
+      mandatoryUsed: 0,
+      mandatoryMax: ADVISOR_QUOTA_MAX,
+    },
     advisorInvocation: 'agent',
     // Agent 等派生工具起嵌套子查询所需的运行态：与主循环同一 provider、
     // 同一审批闸门（子 agent 不绕过宿主策略）。agentCalls 与 advisorCalls 同构，

package/src/tools/advisor/advisor.js

@@ -4,7 +4,7 @@
  * ------------------------------------------------------------
  *  独立配置的第二个 LLM，供主循环的模型在关键判断点（方案/诊断成型后动手写改之前、
  *  受阻或要改方向时、收尾汇报之前）主动调用，拿到一个不同模型的第二意见。
- *  时机规则的真身在 `prompts/promptAssembly.ts` 的 Advisor 工具规则 + 本文件的
+ *  时机规则的真身在 `prompts/policyRegistry.ts` 的 `capability.advisor` 能力块 + 本文件的
  *  `description`；配额曲线在 `loop.ts::advisorQuotaFor`。
  *
  *  设计要点（吸收自 Claude Code 官方 /advisor 的架构，但按 minimal-agent
@@ -378,18 +378,39 @@ export async function runAdvisor(input, signal, ctx, chatFn = chat, runtime = {}
     const isReconcile = ctx?.advisorInvocation === 'agent'
         && Boolean(ctx.advisorRuntime?.pendingConsultationId)
         && ctx.advisorRuntime?.canReconcileConsultation === true;
-    if (!isReconcile && ctx?.advisorCalls && ctx.advisorCalls.used >= ctx.advisorCalls.max) {
+    // 检查点强制咨询 vs 自愿咨询分池计费：宿主主动拦下模型、强制它咨询的这一次
+    // 调用（hasActiveGate === true）走独立的 mandatoryUsed/mandatoryMax 池，
+    // 永远不会被自愿/复核性质的咨询挤占配额。旧版只有一个共享池，配额起点为 1
+    // 时一个回合里第二个检查点几乎必然撞墙——这不是顾问后端配置问题，是结构性的。
+    const isMandated = ctx?.advisorInvocation === 'agent'
+        && ctx.advisorRuntime?.hasActiveGate === true;
+    const quota = ctx?.advisorCalls;
+    const usesMandatoryPool = isMandated && quota?.mandatoryMax !== undefined;
+    const quotaUsed = usesMandatoryPool ? (quota.mandatoryUsed ?? 0) : quota?.used;
+    const quotaMax = usesMandatoryPool ? quota.mandatoryMax : quota?.max;
+    if (!isReconcile && quota && quotaUsed !== undefined && quotaMax !== undefined && quotaUsed >= quotaMax) {
         // ⚠️ 必须说明「配额会增长」：配额随本回合工作量上调（loop.ts::advisorQuotaFor），
         // 若这里只说「已达上限」，模型会当成本回合的硬上限而不再尝试 —— 那样长回合里
         // 「批次做完再复核一次」的配额永远不会被用到，增长机制等于没做。
+        // ⚠️ 只有确实存在一个待结清的咨询（pendingConsultationId）时才能说"按已有
+        // 意见继续"——否则这一步可能压根没有产生过任何意见，那句话就是误导。
+        const hasPendingAdvice = ctx?.advisorRuntime?.pendingConsultationId !== undefined;
+        const poolLabel = usesMandatoryPool ? '检查点强制咨询配额' : '顾问咨询配额';
+        const guidance = hasPendingAdvice
+            ? '配额会随本回合的工作量增长，继续推进一段后可以再次咨询；现在请按已有意见继续。'
+            : '配额会随本回合的工作量增长，继续推进一段后可以再次咨询；这一步目前没有可参考的顾问意见，' +
+                '请基于代码、测试等一手证据自行判断，并在汇报时如实说明这一步未获得第二意见背书。';
         return finish({
             ok: false,
-            error: `本回合顾问咨询配额暂时用完（当前 ${ctx.advisorCalls.max} 次）。` +
-                '配额会随本回合的工作量增长，继续推进一段后可以再次咨询；现在请按已有意见继续。',
+            error: `本回合${poolLabel}暂时用完（当前 ${quotaMax} 次）。${guidance}`,
         });
     }
-    if (!isReconcile && ctx?.advisorCalls)
-        ctx.advisorCalls.used++;
+    if (!isReconcile && quota) {
+        if (usesMandatoryPool)
+            quota.mandatoryUsed = (quota.mandatoryUsed ?? 0) + 1;
+        else
+            quota.used++;
+    }
     const provider = advisor.provider;
     const snapshot = await configService.getSnapshot();
     const secrets = [

package/src/tools/advisor/advisor.ts

@@ -4,7 +4,7 @@
  * ------------------------------------------------------------
  *  独立配置的第二个 LLM，供主循环的模型在关键判断点（方案/诊断成型后动手写改之前、
  *  受阻或要改方向时、收尾汇报之前）主动调用，拿到一个不同模型的第二意见。
- *  时机规则的真身在 `prompts/promptAssembly.ts` 的 Advisor 工具规则 + 本文件的
+ *  时机规则的真身在 `prompts/policyRegistry.ts` 的 `capability.advisor` 能力块 + 本文件的
  *  `description`；配额曲线在 `loop.ts::advisorQuotaFor`。
  *
  *  设计要点（吸收自 Claude Code 官方 /advisor 的架构，但按 minimal-agent
@@ -453,18 +453,38 @@ export async function runAdvisor(
     && Boolean(ctx.advisorRuntime?.pendingConsultationId)
     && ctx.advisorRuntime?.canReconcileConsultation === true;
 
-  if (!isReconcile && ctx?.advisorCalls && ctx.advisorCalls.used >= ctx.advisorCalls.max) {
+  // 检查点强制咨询 vs 自愿咨询分池计费：宿主主动拦下模型、强制它咨询的这一次
+  // 调用（hasActiveGate === true）走独立的 mandatoryUsed/mandatoryMax 池，
+  // 永远不会被自愿/复核性质的咨询挤占配额。旧版只有一个共享池，配额起点为 1
+  // 时一个回合里第二个检查点几乎必然撞墙——这不是顾问后端配置问题，是结构性的。
+  const isMandated = ctx?.advisorInvocation === 'agent'
+    && ctx.advisorRuntime?.hasActiveGate === true;
+  const quota = ctx?.advisorCalls;
+  const usesMandatoryPool = isMandated && quota?.mandatoryMax !== undefined;
+  const quotaUsed = usesMandatoryPool ? (quota!.mandatoryUsed ?? 0) : quota?.used;
+  const quotaMax = usesMandatoryPool ? quota!.mandatoryMax! : quota?.max;
+
+  if (!isReconcile && quota && quotaUsed !== undefined && quotaMax !== undefined && quotaUsed >= quotaMax) {
     // ⚠️ 必须说明「配额会增长」：配额随本回合工作量上调（loop.ts::advisorQuotaFor），
     // 若这里只说「已达上限」，模型会当成本回合的硬上限而不再尝试 —— 那样长回合里
     // 「批次做完再复核一次」的配额永远不会被用到，增长机制等于没做。
+    // ⚠️ 只有确实存在一个待结清的咨询（pendingConsultationId）时才能说"按已有
+    // 意见继续"——否则这一步可能压根没有产生过任何意见，那句话就是误导。
+    const hasPendingAdvice = ctx?.advisorRuntime?.pendingConsultationId !== undefined;
+    const poolLabel = usesMandatoryPool ? '检查点强制咨询配额' : '顾问咨询配额';
+    const guidance = hasPendingAdvice
+      ? '配额会随本回合的工作量增长，继续推进一段后可以再次咨询；现在请按已有意见继续。'
+      : '配额会随本回合的工作量增长，继续推进一段后可以再次咨询；这一步目前没有可参考的顾问意见，' +
+        '请基于代码、测试等一手证据自行判断，并在汇报时如实说明这一步未获得第二意见背书。';
     return finish({
       ok: false,
-      error:
-        `本回合顾问咨询配额暂时用完（当前 ${ctx.advisorCalls.max} 次）。` +
-        '配额会随本回合的工作量增长，继续推进一段后可以再次咨询；现在请按已有意见继续。',
+      error: `本回合${poolLabel}暂时用完（当前 ${quotaMax} 次）。${guidance}`,
     });
   }
-  if (!isReconcile && ctx?.advisorCalls) ctx.advisorCalls.used++;
+  if (!isReconcile && quota) {
+    if (usesMandatoryPool) quota.mandatoryUsed = (quota.mandatoryUsed ?? 0) + 1;
+    else quota.used++;
+  }
 
   const provider = advisor.provider;
   const snapshot = await configService.getSnapshot();

package/src/tools/toolPromptGuides.js

@@ -89,6 +89,14 @@ export const CONTRACT_DESCRIPTION_OVERRIDES = {
         return notice ? `${base}\n\n${notice}` : base;
     },
     Advisor: '向无工具权限的顾问模型请求一次结构化第二意见。',
+    // 通用兜底截断逻辑会在 280 字符处硬切原始 description，此前把"partial/reject
+    // 必须列出被拒绝的意见点并给出一手证据"这条唯一的自然语言说明整句吞掉（schema
+    // 的 superRefine 仍会强制校验字段，但模型看不到为什么）。用覆写绕开截断。
+    AdvisorDecision: '记录主 Agent 在一次成功的 Advisor 咨询后对其意见作出的证据判断。' +
+        '应在恢复被暂缓的写入、不可逆操作或最终交付之前调用。' +
+        '顾问只是第二意见，不是权威结论——判断必须基于代码、测试或用户约束等一手证据，不能默认采纳顾问结论。' +
+        '选择 partial 或 reject 时必须明确列出被拒绝的意见点（rejectedPoints）并说明支持该判断的一手证据；' +
+        '未经过一次成功的 Advisor 咨询时不要调用本工具。',
     Agent: '启动一个具有明确任务书和隔离边界的子 Agent。',
 };
 function compactContractDescription(tool) {

package/src/tools/toolPromptGuides.ts

@@ -107,6 +107,15 @@ export const CONTRACT_DESCRIPTION_OVERRIDES: Readonly<Record<string, string | ((
     return notice ? `${base}\n\n${notice}` : base;
   },
   Advisor: '向无工具权限的顾问模型请求一次结构化第二意见。',
+  // 通用兜底截断逻辑会在 280 字符处硬切原始 description，此前把"partial/reject
+  // 必须列出被拒绝的意见点并给出一手证据"这条唯一的自然语言说明整句吞掉（schema
+  // 的 superRefine 仍会强制校验字段，但模型看不到为什么）。用覆写绕开截断。
+  AdvisorDecision:
+    '记录主 Agent 在一次成功的 Advisor 咨询后对其意见作出的证据判断。' +
+    '应在恢复被暂缓的写入、不可逆操作或最终交付之前调用。' +
+    '顾问只是第二意见，不是权威结论——判断必须基于代码、测试或用户约束等一手证据，不能默认采纳顾问结论。' +
+    '选择 partial 或 reject 时必须明确列出被拒绝的意见点（rejectedPoints）并说明支持该判断的一手证据；' +
+    '未经过一次成功的 Advisor 咨询时不要调用本工具。',
   Agent: '启动一个具有明确任务书和隔离边界的子 Agent。',
 };
 

package/src/types.ts

@@ -493,8 +493,19 @@ export interface ToolCallContext {
   history?: readonly Message[];
   /** Per-conversation mutable state; file freshness and background tasks must not leak across sessions. */
   sessionState?: import('./session/sessionState.js').SessionState;
-  /** 同一用户回合内共享的 Advisor 调用计数，防止模型循环咨询。 */
-  advisorCalls?: { used: number; max: number };
+  /**
+   * 同一用户回合内共享的 Advisor 调用计数，防止模型循环咨询。
+   * `mandatoryUsed`/`mandatoryMax` 是可选的独立"强制检查点"配额池
+   * （见 advisorRuntime.hasActiveGate）——宿主主动拦下模型、强制它咨询的
+   * 这一次调用走这个池，永远不会被自愿/复核性质的咨询挤占；缺失时
+   * （如手动 /advisor ask 场景）行为与改动前完全一致，只走 used/max。
+   */
+  advisorCalls?: {
+    used: number;
+    max: number;
+    mandatoryUsed?: number;
+    mandatoryMax?: number;
+  };
   /** 区分主模型自动咨询与用户显式 /advisor ask。 */
   advisorInvocation?: 'agent' | 'manual';
   /** Advisor 协调器运行时桥；只存在于主循环，不暴露给模型或持久化。 */
@@ -618,6 +629,12 @@ export interface AdvisorRuntimeBridge {
   readonly pendingConsultationId: string | undefined;
   /** 同一检查点最多允许一次不占配额的证据冲突复核。 */
   readonly canReconcileConsultation: boolean;
+  /**
+   * true = 当前有一个硬检查点（#required）或软提醒（#softCheckpoint）正在
+   * 生效——即接下来的 Advisor 调用是宿主强制模型做的，不是模型自愿发起的。
+   * `advisor.ts` 用它判断这次调用该走 advisorCalls 的哪个配额池。
+   */
+  readonly hasActiveGate: boolean;
   beginConsultation(): AdvisorConsultationMetadata;
   finishConsultation(
     metadata: AdvisorConsultationMetadata,