mingdao-harness 0.6.17 → 0.6.19

package/docs/ARCHITECTURE.md

@@ -131,7 +131,7 @@ MingDao 是一个「模型循环 + 工具 + 权限」内核，纯 Node.js ≥ 18
 - `web/constants.js` —— 前端与服务端共享常量：并发上限 8（`MAX_CONCURRENT`）、附件数与体积上限、单文件读取上限 —— 数值只在此定义，防客户端预检/服务端校验/工具读取三处漂移。
 - `web/attachments.js` —— 聊天附件构造（纯函数）：图片转 `data:` URL（仅视觉模型，单张 ≤5MB、最多 4 个），文本文件拼接进消息（≤200KB）—— 服务端按同一组常量校验。
 - `web/web-io.js` —— WebUI 的 io 适配器：把 Agent 的 io 事件翻译为 SSE 事件，权限确认/选择类交互经 `askHandler` 转发到浏览器模态框并等待 `POST /api/permission` 应答。
-- `web/util.js` / `web/app.js` —— 前端：`util.js` 是零状态工具（选择器/转义/Markdown/格式化），`app.js` 是页面主脚本（消息渲染与轨迹、设置面板、自绘气泡与模态框）—— 地址带 `?token=` 时记入 `sessionStorage` 并从地址栏移除，此后请求统一附加 `X-MingDao-Token`。
+- `web/util.js` / `web/app.js` / `web/i18n.js` —— 前端：`util.js` 是零状态工具（选择器/转义/Markdown/格式化），`app.js` 是页面主脚本（消息渲染与轨迹、设置面板、自绘气泡与模态框），`i18n.js` 是零依赖 UI 文案表（zh/en 同键、默认跟随 `navigator.language`、`localStorage` 覆盖）—— 地址带 `?token=` 时记入 `sessionStorage` 并从地址栏移除，此后请求统一附加 `X-MingDao-Token`。
 
 ### 2.8 CLI 层（13）
 

package/docs/CODE-SIGNING.md

@@ -6,7 +6,7 @@
 
 > 自动更新包的**来源签名**是**另一件事**（防"更新源被投毒"，不是防 SmartScreen），见 §五：
 > 代码已就位且判据 fail-closed，但**发布链路尚未接入**——默认档为 `warn-and-install`
-> （照旧安装，但 UI/日志明确写出"本次更新未验证来源签名"）。
+> （照旧安装，弹窗只给两行「未验证来源签名 + 怎么变严」，完整说明写进日志）。
 
 ---
 
@@ -102,9 +102,12 @@ macOS 作业的 `--mac dmg` 在检测到 `CSC_LINK` + Apple 凭证时自动完
 >
 > **本轮状态（诚实标注）**：代码已就位并 fail-closed，但**发布链路尚未接入签名**——
 > `desktop/gen-update-yml.mjs` 与服务器发布脚本都没有签名步骤，feed 里**没有** `.sig` 文件。
-> 因此客户端当前实际走的是**默认档 `warn-and-install`**：照旧安装，但在日志与 UI 里明确写出
-> 「**本次更新未验证来源签名**」。要让"没签名就拒绝"生效，发行方需要：① 按下面步骤接入签名；
-> ② 在客户端设 `MINGDAO_REQUIRE_UPDATE_SIGNATURE=1`（或改成默认值）。
+> 因此客户端当前实际走的是**默认档 `warn-and-install`**：照旧安装，弹窗给两行——
+> 「本次更新未验证来源签名（发布链路尚未接入签名）——已按默认策略安装。」+
+> 「高安全场景可设 `MINGDAO_REQUIRE_UPDATE_SIGNATURE=1` 拒绝无签名更新；详情见日志与官网。」
+> 完整解释（为什么无法用密码学证明来源、feed 被投毒时无法区分、不改配置与会话）写在**日志**里：
+> 桌面版 `<userData>/logs/mingdao.log` 的 `更新来源校验：…` 行。要让"没签名就拒绝"生效，发行方需要：
+> ① 按下面步骤接入签名；② 在客户端设 `MINGDAO_REQUIRE_UPDATE_SIGNATURE=1`（或改成默认值）。
 
 ### 5.1 为什么不是"再算一次 sha512"
 
@@ -154,7 +157,7 @@ node scripts/update-sign.mjs --verify desktop/dist/mingdao-setup-<ver>-x64.exe -
 | --- | --- | --- |
 | 有签名 + 验签通过 | `install` | 提示"来源签名校验通过（ed25519 · keyId=…）"，正常安装 |
 | **有签名 + 验签失败 / 拿不到证据** | `reject` | **一律拒绝**：UI"更新包来源不可信，已拒绝"+ 引导官网手动下载；并**关闭 `autoInstallOnAppQuit`**（否则退出应用时照样装） |
-| 无签名 + 默认 | `warn-and-install` | 照旧安装，但日志与 UI 都写明"**本次更新未验证来源签名**"、并说明当前发布链路没有签名步骤 |
+| 无签名 + 默认 | `warn-and-install` | 照旧安装；弹窗**两行**（"未验证来源签名…已按默认策略安装" + "可设 `REQUIRE=1` 拒绝；详情见日志与官网"），完整解释写进日志行 |
 | 无签名 + `MINGDAO_REQUIRE_UPDATE_SIGNATURE=1` | `reject` | fail-closed：发行方/高安全用户的开关 |
 
 **为什么不默认 reject**：当前发布链路还没有签名，默认 reject 等于一夜之间掐死所有存量用户的自动更新。

package/docs/CONFIG.md

@@ -29,6 +29,27 @@
 `stream_options` 时设 `false`）、`autoTitle`（自动生成会话标题，默认开）、`notify`（任务桌面通知，默认开）、
 `autoCompact`（上下文自动压缩，默认开，见下）、`audit`（工具调用审计，默认开，见下）。
 
+### WebUI 设置项的「默认值」列（只读，不落盘）
+
+设置面板每个可改项显示 **默认 / 当前 / 影响** 三列。默认值来自 `src/config.js` 的内置默认表，
+`GET /api/state` 以**只读字段 `defaults`** 透出（不接受写入，也不参与任何判定）：
+
+```json
+"defaults": {
+  "permission": "ask", "sandbox": "off", "routing": false,
+  "contextBudget": 128000, "timeout": { "firstTokenMs": null, "streamIdleMs": null, "totalMs": null },
+  "autostart": false, "notify": true, "reasoningEffort": "high",
+  "theme": "system", "language": "auto"
+}
+```
+
+- `timeout.*` 为 `null` 表示**按模型自适应**（与「留空」同义）。
+- `theme` / `language` 是浏览器侧偏好：`theme` 落 `mingdao-theme`、`language` 落 `mingdao-lang`；
+  `language: "auto"` 表示跟随 `navigator.language`。
+- 「影响」一句话写在前端映射表（`src/web/app.js` 的 `SETTING_IMPACT`，英文文案在
+  `src/web/i18n.js` 的 `impact.*`），说明「改了会怎样」，例如改小 `contextBudget` 会减少可容纳历史、
+  长任务更易触发压缩。
+
 ## 工具调用审计（P3-5）
 
 每个工具调用（含被拒/被钩子阻止/参数解析失败）自动落 `~/.mingdao/audit.jsonl`（600 权限）：
@@ -552,6 +573,11 @@ API id，不参与 `modelLabels`（其条目仍带 `id`，等于自定义模型
   模型兜底 **32k**、远程兜底 **128k**。
 - **安全预算**：`contextBudget` 会被自动收紧到 `min(contextBudget, 窗口×75%, 窗口−maxOutput−余量)`，
   prompt 永不逼近窗口边缘（75% 舒适区以上 prefill 时间陡增）。
+- **按引擎自述 `n_ctx` clamp（v0.6.18 §3.74）**：预检（`GET /props`）读到引擎真实 `n_ctx` 后，
+  若预算超过 `n_ctx × 0.8`，**发请求前**就 clamp 到该上限并打印
+  `⚠ 引擎自述上下文 32768：config.contextBudget 131072 超过其 80%（26214），发请求前已自动 clamp …`。
+  这是为了避免"明知引擎装不下还照发"——那种请求只会在 prefill 阶段被 `insufficient memory` 拒绝。
+  想真正用更大上下文，必须调引擎侧 `--ctx-size`，改 `config.contextBudget` 只会被 clamp。
 - **边缘检测**：模型每轮上报真实 `prompt_tokens`，≥ 窗口 85% 时下一轮强制压缩历史（即使启发式
   计数低估也强制触发）。
 - **工具输出截断**：单条工具结果按 `窗口/16` 封顶（最少 2000 字），小窗口不再整条回灌大段代码。
@@ -729,6 +755,37 @@ request failed.` 同一错误此前在 60091 的 35B 上也出现过 → **不
   3. 临时把 `localConcurrency` 保持 `1`，并减少子代理数量（读只读子代理在本地模型下已不并行）；
   4. **不要**因为 `engine shed its caches and stays up` 去重启引擎——它没有崩；重启只会重新加载模型。
 
+#### 内存/显存不足时的自动降级重试（v0.6.18 §3.74）
+
+即使有串行化，本地引擎仍可能因**子代理并发 / 长解码 / 其他进程占显存**在 prefill 时拒绝请求：
+
+```
+insufficient memory: the request exceeded available GPU memory
+(sustained critical memory pressure during prefill; aborted before the allocator wall).
+The engine shed its caches and stays up; this request failed.
+```
+
+真机（v0.6.17，8081 qwen）当时上下文只有 ≈2,773 tokens、预算 32,768——**整回合却直接失败**。
+现在对**本地端点**（`isLocalBaseUrl` 为真，或 `customModels.<名>.local: true`）改为**一次**有界降级重试：
+
+| 动作 | 数值 |
+| --- | --- |
+| 压缩上下文预算 | 本回合 `contextBudget × 0.6`，**下限 4096**（例：32,768 → ~19,660） |
+| 降低输出上限 | 本回合 `maxOutputTokens × 0.5`（例：8,192 → 4,096） |
+| 串行化加强 | 该重试传 `localConcurrency: 1`（复用既有的 `acquireLocalSlot`），即便你配了 0/2 |
+| 重试次数 | **最多一次**；第二次仍失败即如实报错，绝不无限重试 |
+
+- **可见性**：界面与日志出现
+  `♻ 因本地引擎内存不足，已压缩上下文（32,768 → ~19,660）…并重试一次`；
+  回合成功时 `done.note` 追加压缩前后数值、重试次数与最终结果（`↩ 内存降级重试（1 次）…重试后成功`）。
+- **第二次仍失败**：回合失败，错误文案带压缩前后数值与具体建议——把 `config.contextBudget` 调到多少、
+  关闭其他占用显存的模型进程/并行会话、引擎侧调大 `--ctx-size` 或使用 q8 KV 量化。
+- **云端端点不重试**：云 API 的 507/容量问题不是本地上下文能改的，压缩重试只会多烧一次请求；
+  400/401/429 等非内存错误同样不触发该恢复。
+- **判据单一来源**：`isMemoryPressureError`（协议层：507 / `insufficient memory` / `memory_refusal` /
+  `allocator wall` / `engine shed its caches and stays up` / OOM 措辞）＋
+  `describeUpstreamError(err, { isLocal })` 的 `recoverableByShrinking` 才决定是否重试。
+
 ### 用本地模型测 harness（测试者步骤清单）
 
 > 这一段是**操作清单**，不是原理说明。按顺序做，能在几分钟内区分"端点不行"和"harness 不行"。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mingdao-harness",
-  "version": "0.6.17",
+  "version": "0.6.19",
   "description": "MingDao Harness —— 开源智能体框架（Agent Harness）。零依赖、开箱即用，针对 DeepSeek-V4 系列优化，开放主流模型接入。",
   "type": "module",
   "bin": {

package/src/agent.js

@@ -8,7 +8,9 @@ import { compactConversation } from './compact.js';
 // 两个对象从此分开：内核 ctx（makeCtx() 的产物）只在循环内用；工具只拿到 makeToolCtx() 的白名单对象。
 import { buildToolSchemas, dispatch, makeToolCtx } from './tools/index.js';
 import { DEFAULT_MODEL, modelPreset } from './models.js';
-import { resolveModelCaps, safeBudget, EDGE_RATIO } from './model-caps.js';
+import { resolveModelCaps, safeBudget, EDGE_RATIO, isLocalBaseUrl } from './model-caps.js';
+// v0.6.18 §3.74：预检已读到引擎自述 n_ctx 时，**发请求前**按 n_ctx×0.8 clamp 预算（纯函数）。
+import { clampContextBudgetToEngine } from './model-discovery.js';
 import { makeTokenCounter } from './tokenizer.js';
 import { createHooks } from './hooks.js';
 import { createIO, style, C } from './ui.js';
@@ -18,7 +20,7 @@ import { redactSecrets } from './redact.js';
 import { checkCostGuard, costGuardConfig, todayCost, preflightBlockMessage, roundGuardAction } from './cost-guard.js';
 import { recordCacheStats, packDailyCost } from './cachestats.js';
 import { estimateCost, cacheSplit, isPeakHour } from './pricing.js';
-import { resolveProviderConfig, createProvider, localGateSnapshot, localConcurrencyLimit } from './providers/index.js';
+import { resolveProviderConfig, createProvider, localGateSnapshot, localConcurrencyLimit, isMemoryPressureError } from './providers/index.js';
 import { compileConstraints, checkPreTool, checkPostTool, checkOutput, blockedOutputText } from './constraints.js';
 import { createLedger, newRunId } from './ledger.js';
 import { registerEgressSink } from './net-guard.js';
@@ -77,6 +79,13 @@ export const DEFAULT_NO_PROGRESS_TIMEOUT_MS = 3600000;
  *  形态下多等 15s（相对默认 60 分钟是 0.4%），换"子代理自己的结论能回传父回合"。 */
 export const SUBAGENT_WAIT_GRACE_MS = 15000;
 
+/** 本地引擎内存不足时允许的**降级重试次数**（v0.6.18 §3.74）。
+ *
+ *  只允许一次：内存墙不是网络抖动——同一份大 prompt 重发只会再撞一次。第一次失败后
+ *  agent 会压缩上下文 + 输出减半 + 强制串行；第二次仍失败就如实报错，绝不无限重试。
+ *  抽成常量是为了让"最多一次"可被断言/变异钉住（不是散在 if 里的魔法值）。 */
+export const MAX_MEMORY_RETRIES = 1;
+
 /** 解析无进展阈值：非正/非有限一律回落默认（fail-safe，防"配置写 0 就静默失去看门狗"）。 */
 export function resolveNoProgressTimeoutMs(/** @type {any} */ cfg) {
   const v = Number(cfg?.noProgressTimeoutMs);
@@ -281,13 +290,20 @@ export function zeroToolCallNotice({ modelRounds, steps = 0, taskLike = false })
 /**
  * 上游/引擎错误的可操作解读（纯函数）：把「HTTP 400 + 一段 Jinja/模板报错」这类原文
  * 变成「原文 + 这是什么 + 该怎么办」。识别不出时 hint 为 null（**绝不改原文**）。
+ *
+ * v0.6.18 §3.74：额外返回 `recoverableByShrinking`——**只有本地端点**的内存/显存不足
+ * 才是"压缩上下文 + 降输出 + 串行重试一次"能救的；云端 API 的 507/内存报错不在此列
+ * （云端的容量/配额不是本地上下文能改的，对云 API 做压缩重试只会多烧一次请求）。
  * @param {any} err
- * @returns {{ message: string, hint: string|null, status: number|null }}
+ * @param {{ isLocal?: boolean }} [opts]
+ * @returns {{ message: string, hint: string|null, status: number|null, recoverableByShrinking: boolean }}
  */
-export function describeUpstreamError(/** @type {any} */ err) {
+export function describeUpstreamError(/** @type {any} */ err, opts = {}) {
   const raw = String(err?.message ?? err ?? '').trim();
   const status = Number(err?.status) > 0 ? Number(err.status) : null;
   const t = raw.toLowerCase();
+  const memoryPressure = isMemoryPressureError(err);
+  const recoverableByShrinking = Boolean(memoryPressure && opts?.isLocal === true);
   /** @type {string|null} */
   let hint = null;
   if (/jinja|template|no user query|parser for this template/.test(t)) {
@@ -321,7 +337,7 @@ export function describeUpstreamError(/** @type {any} */ err) {
   }
   // 上游原文可能很长（内核只保留前 400 字）：如实标注它被截断过，避免用户以为这就是全部
   const truncated = /…|\.\.\.$/.test(raw) || raw.length >= 380;
-  return { message: raw, hint: hint ? `💡 ${hint}${truncated ? '（上面的上游原文可能被截断）' : ''}` : null, status };
+  return { message: raw, hint: hint ? `💡 ${hint}${truncated ? '（上面的上游原文可能被截断）' : ''}` : null, status, recoverableByShrinking };
 }
 
 /**
@@ -436,7 +452,17 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
   const caps = resolveModelCaps(cfg, modelName);
   // safeBudget 恒用：即使用户显式 contextBudget 也套「窗口−输出−余量」上限与 75% 舒适区，
   // 防显式值撑爆窗口（本地模型窗口可能只有 32k/131k，用户却留了默认 128000）。
-  const budget = safeBudget(cfg, caps);
+  const safeB = safeBudget(cfg, caps);
+  // v0.6.18 §3.74（自适应上下文）：预检若已读到**引擎自述 n_ctx**，配置预算再大也没用——
+  // 发出去就会在 prefill 阶段被引擎以 insufficient memory 拒绝。这里在**创建 agent 时**
+  // （即第一次请求之前）就 clamp 到 n_ctx×0.8，并在第一回合开始前打印一条明确提示。
+  const budgetClamp = clampContextBudgetToEngine({
+    contextBudget: safeB,
+    configuredBudget: Number(cfg?.contextBudget) > 0 ? Number(cfg.contextBudget) : null,
+    engineCtx: cfg?.endpointProbe?.engineCtx ?? null,
+  });
+  const budget = budgetClamp.budget ?? safeB;
+  const budgetClampNotice = budgetClamp.clamped ? budgetClamp.notice : '';
   // maxOutput 也按窗口封顶：显式配超大 maxOutputTokens 时，prompt(预算)+output 仍不得越过窗口
   // （预算已按 caps.maxOutputTokens 留余量，但显式值可能更大——此处兜底，防服务端截断/拒绝）
   const maxOutput = Math.min(
@@ -480,6 +506,13 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
   // （CLI/REPL 每次派子代理都漏计；README 主推的「多方向并行调研」场景漏计最重）。
   // runTurn 开始时指向本轮 usage，finally 清空；runTurn 之外调用 spawnTask 时为 null（安全跳过）。
   let currentUsage = /** @type {any} */ (null);
+  // v0.6.18 §3.74：本回合的「内存降级重试」记录（runTurn 内写、runTurn 包装层读）与本回合
+  // 必须进 done.note 的提示（clamp 提示 / 压缩重试提示）。声明在 runTurn 之外，包装层才能把
+  // 这些提示统一追加到**每一条** return 路径上（runTurn 内部有十几个 return，逐条补会漏）。
+  let lastMemoryRecovery = /** @type {any} */ (null);
+  let turnNotes = /** @type {string[]} */ ([]);
+  /** clamp 提示每个 agent 只打一次（子代理各自持有一份，但只在各自第一回合出现）。 */
+  let clampNoticeShown = false;
   // v0.6.0 C1：当前回合的账本写入器（与 currentUsage 同款：runTurn 内赋值、finally 清空）。
   // 账本不可用/被关闭时它是 no-op，**绝不影响主流程**——与 writeAudit 同款容错。
   let turnLedger = /** @type {any} */ (null);
@@ -746,9 +779,16 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
     };
   }
 
-  async function runTurn(/** @type {any} */ messages) {
+  async function runTurnInner(/** @type {any} */ messages) {
     let steps = 0;
     let finish = null;
+    // v0.6.18 §3.74：本回合实际生效的 prompt 预算 / 输出上限——内存不足时**只在本回合内**
+    // 压小（contextBudget ×0.6、maxOutputTokens ×0.5），不写回用户配置。
+    let turnBudget = budget;
+    let turnMaxOutput = maxOutput;
+    /** 本回合已用掉的内存降级重试次数（上限 MAX_MEMORY_RETRIES，默认 1）。 */
+    let memoryRetries = 0;
+    lastMemoryRecovery = null;
     /** v0.6.3（M-16）：本回合是否出现过"上游提前关流"（回答可能不完整）。
      * 刻意不叫 truncated——既有 `truncated` 的含义是"步数兜底总结也失败了"，两者必须分开。 */
     let upstreamTruncated = false;
@@ -1163,7 +1203,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           if (turnProgress.phase !== '已中止（无进展）') turnProgress.phase = '压缩上下文';
           const compacted = await compactConversation({
             messages,
-            budget,
+            budget: turnBudget,
             count,
             provider,
             executorModel: subagentModel(cfg, modelName),
@@ -1203,7 +1243,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           }
         } catch {}
       }
-      const trimmed = trimMessages(messages, budget, count);
+      const trimmed = trimMessages(messages, turnBudget, count);
 
       // reasoning 回填防护（Kimi P0 修正）：带 tool_calls 的 assistant 消息必须「完整」回传
       // reasoning_content（DeepSeek thinking_mode 官方要求：后续请求含 tools 时缺/截断即 400，
@@ -1239,7 +1279,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         if (g && Number(g.dailyLimitYuan) > 0 && g.action !== 'downgrade') {
           let promptTokens = 0;
           for (const m of sanitized) promptTokens += messageTokens(m, count);
-          const worst = estimateCost(activeModel, promptTokens, maxOutput, null, new Date());
+          const worst = estimateCost(activeModel, promptTokens, turnMaxOutput, null, new Date());
           // 判据本身抽到 cost-guard.js 的 preflightBlockMessage（v0.6.11 / P1-1 第一刀）：
           // 它能被单测逐条钉边界，而 runTurn 只负责"拿到数字 → 问判据 → 该拦就拦"。
           // 统计不可读 / 无价格数据时判据返回 null（不误拦、也不静默放行——主检查会告警）。
@@ -1332,7 +1372,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
             contextWindow: caps.contextWindow,
             isLocal: caps.isLocal,
             firstTokenMs: Number(cfg?.timeout?.firstTokenMs) > 0 ? Number(cfg.timeout.firstTokenMs) : effFirstTokenMs,
-            budget,
+            budget: turnBudget,
             probe: cfg?.endpointProbe || null,
             localBusy: Boolean(caps.isLocal && (gate.active > 0 || gate.queued > 0)),
             localActive: gate.active,
@@ -1358,9 +1398,12 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           messages: sanitized,
           tools: toolsFor(readOnlyPhase, turnStrippedSet),
           temperature,
-          maxTokens: maxOutput,
+          maxTokens: turnMaxOutput,
           // MiniMax P0：仅当 activeModel 声明支持 reasoning 才发送（否则 400 终止回合）；'off' 显式禁用例外
           reasoningEffort: modelPreset(activeModel)?.supportsReasoning || reasoningEffort === 'off' ? reasoningEffort : undefined,
+          // v0.6.18 §3.74：发生过内存降级后，本回合后续请求**一律压回单并发**（即便用户把
+          // config.localConcurrency 配成 0/2）——provider 会把它传给 acquireLocalSlot。
+          ...(memoryRetries > 0 ? { localConcurrency: 1 } : {}),
           signal: ac.signal,
           // v0.6.15（§3.59 第 1 条）：本地端点串行化必须**在界面上可见**——
           // 排队时状态条/进度行写"排队等待本地端点（已串行化防内存压力）"，
@@ -1440,6 +1483,68 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         // MacBook 本地 507 memory_refusal 根因（v0.4.5）：服务端内存拒绝不是「空输出」——
         // 直接终结合合并透出降级提示，不计入空轮、不注入续写重试（内存未释放必再 507，空烧请求）。
         const e = /** @type {any} */ (err);
+        // ---------------------------------------------------------------------------
+        // v0.6.18 §3.74：**本地引擎内存/显存不足 → 压缩上下文 + 降输出 + 强制串行，重试一次**
+        //
+        // 真机（v0.6.17，8081 qwen）：子代理并发/长解码导致显存峰值超限，引擎在 prefill 前拒绝，
+        // 整回合直接失败；而当时上下文只有 ≈2,773 tokens、预算 32,768——压小预算/输出上限后
+        // 极可能成功。这里不再立刻判失败，而是**只对本地端点**做一次有界降级重试：
+        //   · contextBudget ×0.6（下限 4k，避免压到连系统提示都放不下）；
+        //   · maxOutputTokens ×0.5（只用于本回合后续请求）；
+        //   · 该次重试传 localConcurrency=1（provider 的 acquireLocalSlot 会把并发上限压回 1）；
+        //   · 只重试一次：memoryRetryUsed 一旦置真，第二次失败就如实抛错（不无限重试）。
+        // 云端端点不在此列：云 API 的 507/容量问题不是本地上下文能改的，压缩重试只会多烧一次请求。
+        // ---------------------------------------------------------------------------
+        let localEndpoint = false;
+        try {
+          // 用**本回合实际使用**的模型判本地：费用护栏可能把 activeModel 降级到云端模型，
+          // 此时不能拿原始 modelName 的 caps.isLocal 误判成"本地内存不足"。
+          const activeCaps = resolveModelCaps(cfg, activeModel);
+          const pcNow = resolveProviderConfig(cfg, activeModel);
+          localEndpoint = Boolean(activeCaps.isLocal || isLocalBaseUrl(pcNow?.baseUrl || provider?.config?.baseUrl || ''));
+        } catch {}
+        const localMemory = describeUpstreamError(e, { isLocal: localEndpoint });
+        if (localMemory.recoverableByShrinking) {
+          if (memoryRetries >= MAX_MEMORY_RETRIES) {
+            // 第二次仍失败：不掩盖，把压缩前后数值、重试次数、具体建议一起抛给用户/日志。
+            const rec = /** @type {any} */ (lastMemoryRecovery) || {};
+            const suggest = Math.max(4096, Math.floor(Number(rec.toBudget) > 0 ? Number(rec.toBudget) * 0.7 : 8192));
+            const detail =
+              `本地引擎内存不足：已压缩上下文（${fmtTok(rec.fromBudget)} → ~${fmtTok(rec.toBudget)}）、` +
+              `输出上限 ${fmtTok(rec.fromMaxOutput)} → ${fmtTok(rec.toMaxOutput)}，并重试 1 次（最多一次），仍失败——不再重试。` +
+              `建议：把 config.contextBudget 调到 ${fmtTok(suggest)} 左右（或更低），关闭其他占用显存的模型进程/并行会话，` +
+              `并在引擎侧调大 --ctx-size 或使用 q8 KV 量化。`;
+            try { io.print(style(`⚠ ${localMemory.message}\n   ${detail}`, C.yellow)); } catch {}
+            const enriched = new Error(`${localMemory.message}\n   ${localMemory.hint || ''}\n   ↩ ${detail}`);
+            /** @type {any} */ (enriched).status = e?.status ?? 507;
+            if (e?.headers !== undefined) /** @type {any} */ (enriched).headers = e.headers;
+            throw enriched;
+          }
+          memoryRetries += 1;
+          const fromBudget = turnBudget;
+          const fromMaxOutput = turnMaxOutput;
+          // 压缩比例 0.6、下限 4096：0.6 在真机 32,768 → ~19,660 的区间内足够把 KV cache 峰值压下来；
+          // 再低会伤任务质量，且 4k 以下连系统提示 + 一轮工具结果都放不下（重启永远失败）。
+          turnBudget = Math.max(4096, Math.floor(fromBudget * 0.6));
+          turnMaxOutput = Math.max(256, Math.floor(fromMaxOutput * 0.5));
+          lastMemoryRecovery = {
+            attempts: memoryRetries,
+            fromBudget,
+            toBudget: turnBudget,
+            fromMaxOutput,
+            toMaxOutput: turnMaxOutput,
+            at: Date.now(),
+          };
+          const msg =
+            `♻ 因本地引擎内存不足，已压缩上下文（${fmtTok(fromBudget)} → ~${fmtTok(turnBudget)}）、` +
+            `输出上限 ${fmtTok(fromMaxOutput)} → ${fmtTok(turnMaxOutput)}，并重试一次（串行化：并发上限 1）`;
+          try { io.print(style(msg, C.yellow)); } catch {}
+          turnNotes.push(msg);
+          turnProgress.phase = '内存降级重试（已压缩上下文）';
+          turnProgress.memoryRecovery = lastMemoryRecovery;
+          steps = Math.max(0, steps - 1); // 重试不额外消耗一步，避免 maxSteps=1 时根本没机会重试
+          continue;
+        }
         // v0.6.15（§3.59 第 2 条）：`engine shed its caches and stays up` / `allocator wall`
         // 说明引擎**活着**（自己丢缓存后继续服务）——不走这条"507 旧文案"（那里建议重启引擎，
         // 对活着但内存吃紧的引擎是错误处置）；交给下面 describeUpstreamError 的独立分型。
@@ -1552,7 +1657,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         if (steps === stepLimit) {
           io.endTurn();
           if (res.text) {
-            const ap = await applyOutputConstraints(res.text, { messages, provider, activeModel, temperature, maxOutput, usage, signal: currentAc?.signal });
+            const ap = await applyOutputConstraints(res.text, { messages, provider, activeModel, temperature, maxOutput: turnMaxOutput, usage, signal: currentAc?.signal });
             messages.push({ role: 'assistant', content: ap.text });
             // 步数已耗尽：这一条与下方 `break`（→ 兜底总结/截断收尾）必须是同一口径
             markOutcome('capped', { capHit: true });
@@ -1907,7 +2012,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         if (res.text) {
           // v0.5.0 A3 ③：输出前领域约束必须在**回填历史之前**应用——
           // 否则被拦下的违规措辞会留在会话里，下一轮又被当作既成事实喂回模型。
-          const ap = await applyOutputConstraints(res.text, { messages, provider, activeModel, temperature, maxOutput, usage, signal: currentAc?.signal });
+          const ap = await applyOutputConstraints(res.text, { messages, provider, activeModel, temperature, maxOutput: turnMaxOutput, usage, signal: currentAc?.signal });
           finalText = ap.text;
           outputNote = ap.note;
           messages.push({ role: 'assistant', content: finalText });
@@ -2080,7 +2185,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           messages: wrapReq,
           tools: [],
           temperature,
-          maxTokens: Math.min(maxOutput, 2048),
+          maxTokens: Math.min(turnMaxOutput, 2048),
           reasoningEffort: modelPreset(activeModel)?.supportsReasoning ? 'low' : undefined,
           signal: currentAc.signal,
           onDelta(/** @type {any} */ d) {
@@ -2094,7 +2199,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         }
         // v0.5.0 A3 ③：兜底总结同样过一遍输出约束
         const wrapApplied = wrapRes.text
-          ? await applyOutputConstraints(wrapRes.text, { messages, provider, activeModel, temperature, maxOutput, usage, signal: currentAc?.signal })
+          ? await applyOutputConstraints(wrapRes.text, { messages, provider, activeModel, temperature, maxOutput: turnMaxOutput, usage, signal: currentAc?.signal })
           : { text: null, note: null };
         if (wrapApplied.text) messages.push({ role: 'assistant', content: wrapApplied.text });
         // capHit：本轮因步数上限被迫收尾（任务可能未真正完成）→ 供上层落检查点续跑
@@ -2213,6 +2318,38 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
     }
   }
 
+  /**
+   * 回合包装层（v0.6.18 §3.74）：把「本回合必须让用户看见」的提示统一追加到 done.note。
+   *
+   * 为什么需要包装：`runTurnInner` 有十几个 return 路径（工具收尾、cap、stalled、aborted…），
+   * 逐条补 note 必漏。这里只做两件事：
+   *   ① 第一回合发请求前打印「按引擎 n_ctx clamp 预算」的提示（只打一次，避免每回合刷屏）；
+   *   ② 回合结束后把 clamp 提示与内存降级重试的**压缩前后数值 / 重试次数 / 最终结果**
+   *      追加到 `note`——WebUI 的 done.note、CLI 的收尾说明因此共用同一份口径。
+   */
+  async function runTurn(/** @type {any} */ messages) {
+    turnNotes = [];
+    if (budgetClampNotice && !clampNoticeShown) {
+      clampNoticeShown = true;
+      try { io.print(style(budgetClampNotice, C.yellow)); } catch {}
+      turnNotes.push(budgetClampNotice);
+    }
+    const r = await runTurnInner(messages);
+    const notes = turnNotes.filter(Boolean);
+    if (lastMemoryRecovery && r) {
+      const rec = lastMemoryRecovery;
+      const final = r.aborted ? '重试后被中断' : r.stalled ? '重试后无进展中止' : r.text ? '重试后成功' : '重试后仍无正文';
+      notes.push(
+        `↩ 内存降级重试（${Number(rec.attempts) || 1} 次）：上下文预算 ${fmtTok(rec.fromBudget)} → ${fmtTok(rec.toBudget)}、` +
+          `输出上限 ${fmtTok(rec.fromMaxOutput)} → ${fmtTok(rec.toMaxOutput)}；${final}。`
+      );
+    }
+    if (notes.length && r && typeof r === 'object') {
+      r.note = [r.note, ...notes].filter(Boolean).join('\n');
+    }
+    return r;
+  }
+
   return {
     modelName,
     budget,

package/src/model-discovery.js

@@ -866,6 +866,45 @@ export function engineContextNotice({ engineCtx = null, configuredWindow = null,
   return `引擎自述上下文 ${eng} vs 配置 ${conf ?? '（未声明）'} —— 配置未超出引擎能力${where}`;
 }
 
+// ---------------------------------------------------------------------------
+// v0.6.18 §3.74：**发请求前按引擎自述 n_ctx clamp 预算**
+//
+// 只"提示配置超出引擎能力"还不够：真机（v0.6.17，8081 qwen）配置 contextBudget=32768、
+// 引擎自述 n_ctx 也很小，请求照样发出去，然后整回合被 `insufficient memory` 拒绝。
+// 既然预检已经读到了 n_ctx，就在**发请求之前**把 prompt 预算压到 n_ctx×0.8 以下——
+// 明知会炸还发，等于把一次必然失败的 prefill 再烧一遍。
+//
+// 为什么留 20%：引擎的 n_ctx 是 prompt+输出/KV cache 的总窗口，输出上限、模板开销与
+// 并发请求都要占同一份窗口；贴着 n_ctx 发等于没有余量。0.8 与 PREFILL_WARN_RATIO 同口径。
+// ---------------------------------------------------------------------------
+
+/** 引擎自述 n_ctx 的预算占比（超过即 clamp）。 */
+export const ENGINE_BUDGET_RATIO = 0.8;
+
+/**
+ * 按引擎自述上下文 clamp prompt 预算（纯函数，便于断言/变异）。
+ *
+ * @param {{ contextBudget?: number|null, configuredBudget?: number|null, engineCtx?: number|null, ratio?: number }} [input]
+ * @returns {{ clamped: boolean, budget: number|null, from: number|null, to: number|null,
+ *             engineCtx: number|null, ceiling: number|null, ratio: number, notice: string }}
+ */
+export function clampContextBudgetToEngine({ contextBudget = null, configuredBudget = null, engineCtx = null, ratio = ENGINE_BUDGET_RATIO } = {}) {
+  const raw = Number(contextBudget) > 0 ? Math.floor(Number(contextBudget)) : null;
+  const confRaw = Number(configuredBudget) > 0 ? Math.floor(Number(configuredBudget)) : raw;
+  const eng = Number(engineCtx) > 0 ? Math.floor(Number(engineCtx)) : null;
+  const r = Number(ratio) > 0 && Number(ratio) < 1 ? Number(ratio) : ENGINE_BUDGET_RATIO;
+  const base = { clamped: false, budget: raw, from: raw, to: raw, engineCtx: eng, ceiling: null, ratio: r, notice: '' };
+  if (raw == null || eng == null) return base; // 没配置/没读到 n_ctx → 不猜、不 clamp
+  const ceiling = Math.max(1024, Math.floor(eng * r));
+  if (raw <= ceiling) return { ...base, ceiling };
+  const to = ceiling;
+  const notice =
+    `⚠ 引擎自述上下文 ${eng}：config.contextBudget ${confRaw} 超过其 ${Math.round(r * 100)}%（${ceiling}），` +
+    `发请求前已自动 clamp 上下文预算 ${raw} → ${ceiling}——否则长上下文会在 prefill 阶段被引擎直接拒绝` +
+    `（insufficient memory）。如需更大上下文，请在引擎侧调大 --ctx-size，而不是只改 config.contextBudget。`;
+  return { clamped: true, budget: to, from: raw, to, engineCtx: eng, ceiling, ratio: r, notice };
+}
+
 export function modelCacheFile() {
   return path.join(mingdaoHome(), 'model-cache.json');
 }

package/src/providers/index.js

@@ -11,7 +11,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { chat as openaiChat } from './openai-compatible.js';
+import { chat as openaiChat, isMemoryPressureError } from './openai-compatible.js';
+// 供 agent/model-discovery 与回归套件复用同一条「内存压力」判据（单一来源，避免各层各写一份正则）。
+export { isMemoryPressureError };
 import { modelPreset, providerPreset } from '../models.js';
 import { mingdaoHome } from '../config.js';
 import { resolveApiKey, getStoredKey } from '../credentials.js';
@@ -421,6 +423,11 @@ const sleep = (/** @type {any} */ ms, /** @type {any} */ signal) =>
   });
 
 function isTransient(/** @type {any} */ err) {
+  // v0.6.18 §3.74：内存/显存不足**不是瞬态网络抖动**——原样重发同一份大 prompt 只会再撞一次
+  // 内存墙（真机 8081：父回合 + 子代理并发 prefill）。这类错误交给 agent 做「压缩上下文 +
+  // 输出减半 + 强制串行」的一次性恢复；这里必须**不重试**，否则同回合会白烧 2 次请求
+  // （且 500+insufficient memory 会被 `status >= 500` 误判成瞬态）。
+  if (isMemoryPressureError(err)) return false;
   const status = err?.status;
   if (status === 429 || (status >= 500 && status <= 504)) return true;
   // 注意：不含 abort —— 用户 Ctrl+C 主动中断不应触发重试
@@ -511,7 +518,9 @@ export async function createProvider(/** @type {any} */ cfg, /** @type {any} */
           // 必须在**首 token 计时之前**排队：排队是内核自己的调度，不是"引擎迟迟不出首帧"。
           // 云端端点由 acquireLocalSlot 内部直接放行（不排队、不记日志、不加延迟）。
           releaseLocal = await acquireLocalSlot(pc.baseUrl, {
-            cfg,
+            // v0.6.18 §3.74：内存降级重试时 agent 传 localConcurrency=1，**临时把该端点压回单并发**
+            // （即便用户把 config.localConcurrency 配成 0/2）——重试期间不允许父回合/子代理再同时 prefill。
+            cfg: opts.localConcurrency != null ? { ...cfg, localConcurrency: opts.localConcurrency } : cfg,
             signal: ac.signal,
             onWait: opts.onQueueWait,
             endpoint: pc.name || pc.baseUrl,

package/src/providers/openai-compatible.js

@@ -17,9 +17,36 @@ function extractStreamError(/** @type {any} */ json) {
   /** @type {ApiError} */
   const e = new Error(`[流式响应错误${code ? ' ' + code : ''}] ${msg}`);
   if (code) e.status = code;
+  if (isMemoryPressureError(e)) /** @type {any} */ (e).memoryPressure = true;
   return e;
 }
 
+// 本地引擎「内存/显存不足」的判据（纯函数，v0.6.18 §3.74）：
+//   · HTTP 507（Insufficient Storage，llama.cpp / vLLM 的内存拒绝常用）；
+//   · 真机原文 `insufficient memory … aborted before the allocator wall` /
+//     `The engine shed its caches and stays up` / `memory_refusal`；
+//   · 中文本地引擎常见措辞（内存不足 / 内存拒绝 / 显存不足）；
+//   · 通用 OOM 措辞（CUDA out of memory / OOM）。
+// **只认"内存类"**：400/401/429 与普通 5xx 一律不命中——否则会把重试/压缩用在无意义的场景上。
+// 注意：这是**协议层**判据（有没有可能是内存问题）；「能不能压缩重试」还要叠加
+// `isLocalBaseUrl` —— 云 API 的 507 不压缩重试（见 agent.js 的 describeUpstreamError）。
+const MEMORY_PRESSURE_RE =
+  /insufficient memory|memory_refusal|allocator wall|engine shed its caches and stays up|out of memory|\boom\b|cuda.*memory|gpu memory|显存(?:不足|不够)|内存(?:不足|拒绝|不够)/i;
+
+/**
+ * 这次错误是否属于「本地引擎内存/显存不足」（纯函数）。
+ * @param {any} err
+ * @returns {boolean}
+ */
+export function isMemoryPressureError(/** @type {any} */ err) {
+  const status = Number(err?.status);
+  if (status === 507) return true;
+  const text = String(err?.message ?? err ?? '');
+  if (!text) return false;
+  if (MEMORY_PRESSURE_RE.test(text)) return true;
+  return Boolean(err?.memoryPressure);
+}
+
 export async function chat(/** @type {any} */ { baseUrl, apiKey, model, messages, tools, temperature, maxTokens, signal, onDelta, onActivity, includeUsage = true, responseFormat, reasoningEffort }) {
   const url = String(baseUrl).replace(/\/+$/, '') + '/chat/completions';
   const payload = /** @type {Record<string, any>} */ ({ model, messages });
@@ -76,6 +103,7 @@ export async function chat(/** @type {any} */ { baseUrl, apiKey, model, messages
     const e = new Error(`[${model}] API 错误 ${res.status}: ${detail}${hint}`);
     e.status = res.status;
     e.headers = res.headers; // 重试退避读取 Retry-After 用
+    if (isMemoryPressureError(e)) /** @type {any} */ (e).memoryPressure = true;
     throw e;
   }