mingdao-harness 0.3.1 → 0.3.2

package/docs/CONFIG.md

@@ -23,7 +23,7 @@
 | `baseUrl` | OpenAI 兼容 API 地址（可覆盖内置服务商默认值） |
 | `permission` | `ask`（默认）/ `auto` / `readonly`，或规则对象（见下） |
 | `sandbox` | `off` / `readonly` / `safe`（Linux + bubblewrap；其余平台自动降级） |
-| `contextBudget` | 上下文预算 tokens（模型预设默认值：flash 128k / pro 200k） |
+| `contextBudget` | 期望的上下文预算 tokens；实际预算按模型窗口自动收紧（见「本地模型自适应」） |
 
 可选字段：`temperature`、`maxOutputTokens`、`includeUsage`（流式请求 usage 统计，个别网关不支持
 `stream_options` 时设 `false`）、`autoTitle`（自动生成会话标题，默认开）、`notify`（任务桌面通知，默认开）、
@@ -221,7 +221,8 @@ completion 计费，防止推理吃满上限时空轮白烧）、`compactTrigger
 {
   "customModels": {
     "my-gpt4": { "label": "我的 GPT-4 网关", "baseUrl": "https://gateway.example.com/v1" },
-    "my-ds": { "label": "自建 DeepSeek 网关", "baseUrl": "https://gw.example.com/v1", "tokenizer": "deepseek" }
+    "my-ds": { "label": "自建 DeepSeek 网关", "baseUrl": "https://gw.example.com/v1", "tokenizer": "deepseek" },
+    "local-qwen": { "label": "本机 Qwen", "baseUrl": "http://127.0.0.1:8081/v1", "contextWindow": 131072, "maxOutputTokens": 8192 }
   }
 }
 ```
@@ -231,6 +232,27 @@ completion 计费，防止推理吃满上限时空轮白烧）、`compactTrigger
 自定义端点若跑的是 DeepSeek 系模型（模型名不以 `deepseek` 开头时默认走启发式估算、预算误差
 可达 ±2 倍），加 `"tokenizer": "deepseek"` 即按官方词表精确计数：
 
+### 本地模型自适应（v0.3.2）
+
+本机/内网部署的推理框架（baseUrl 为 `127.0.0.1`/`localhost`/私网 IP）自动按「资源有限」对待，
+避免长任务把上下文撑到窗口边缘后 prefill 指数恶化、被客户端超时掐断（典型：127k 上下文首 token
+需 200s+，客户端 3 分钟无响应断开 → network error）。机制：
+
+- **上下文窗口感知**：`customModels.<name>.contextWindow` 显式声明模型真实窗口；未声明时本地
+  模型兜底 **32k**、远程兜底 **128k**。
+- **安全预算**：`contextBudget` 会被自动收紧到 `min(contextBudget, 窗口×75%, 窗口−maxOutput−余量)`，
+  prompt 永不逼近窗口边缘（75% 舒适区以上 prefill 时间陡增）。
+- **边缘检测**：模型每轮上报真实 `prompt_tokens`，≥ 窗口 85% 时下一轮强制压缩历史（即使启发式
+  计数低估也强制触发）。
+- **工具输出截断**：单条工具结果按 `窗口/16` 封顶（最少 2000 字），小窗口不再整条回灌大段代码。
+- **分层超时**：`timeout.firstTokenMs`（首 token 等待，本地默认 600s / 远程 300s）、
+  `timeout.streamIdleMs`（流式空闲，默认 120s）、`timeout.totalMs`（总量，本地 30min / 远程 10min），
+  留空则自适应；本地慢 prefill 不再被一刀切超时误杀。
+
+```json
+{ "timeout": { "firstTokenMs": 600000, "streamIdleMs": 120000, "totalMs": 1800000 } }
+```
+
 ## 自定义 Provider 模块（非 OpenAI 兼容协议）
 
 在 `~/.mingdao/providers/<name>.mjs` 导出：

package/docs/PLAN-v0.3.2.md

@@ -0,0 +1,65 @@
+# v0.3.2 规划：本地模型自适应（资源受限部署不中断）
+
+## 背景（用户 MacBook M5 Pro 实测定位结论）
+
+本地部署 `mtplx-qwen38-27b`（131072 窗口 + q8 KV 量化）跑 71 步长任务时 network error。
+其他 agent 定位结论：**不是内存拒绝，是「长上下文 prefill 过慢 → 客户端等待超时主动断连」**。
+
+- 服务端无任何 507/内存拒绝，q8 生效，峰值 47.38GB < 48G 预算。
+- 失败请求：prompt=127,912 / 131,072（窗口边缘），`request_cancelled=client_disconnected`，
+  188.9s 内 0 token 输出。
+- prefill 指数恶化：ttft 46.4s → 67.8s → 96.0s → 196.5s → 中断（189s 无输出）。
+  根因：每轮全量历史 + 上一轮大段代码输出回灌，新增 prefill 从 7.9k 涨到 32k，
+  prefill 速度仅 ~165–185 tok/s，ttft 超过客户端等待阈值。
+
+调用 DeepSeek 官方 API 无此问题（窗口 1M + prefill 极快），说明瓶颈在「资源受限的本地模型」，
+必须做成**共性能力**：其他客户本地部署更小模型（窗口小/内存少）也会踩，不能只修 MacBook。
+
+## 目标
+
+让 MingDao 针对不同「参数 / 上下文窗口 / KV cache / 机器资源」的模型**灵活自适应**，
+小模型、低内存自动收紧参数适应，不撑爆、不误杀；本地慢 prefill 不被一刀切超时掐断。
+
+## 方案（本次实现）
+
+### 1. 模型能力解析（`src/model-caps.js` 新增）
+单一来源解析 `contextWindow / maxOutputTokens / isLocal`：
+- 优先级：`customModels.<name>.contextWindow/maxOutputTokens` > 内置 preset > 兜底。
+- 兜底：本地模型 32k、远程 128k（本地小模型宁可保守不撑爆）。
+- `isLocalBaseUrl`：127.0.0.1 / localhost / 私网 IP 判定本地推理框架。
+
+### 2. 安全预算推导（`safeBudget`）
+`budget = min(期望 contextBudget, 窗口×75% 舒适区, 窗口 − maxOutput − 2048 余量)`。
+prompt 永不逼近窗口边缘（75% 以上 prefill 时间陡增），从根上避免 prefill 爆炸。
+对内置模型零影响（pro 200k / flash 128k 均远小于各自窗口 75%）。
+
+### 3. 分层超时（providers）
+- 首 token 等待：本地 600s / 远程 300s（覆盖慢 prefill）。
+- 流式空闲：有帧后 120s 无新帧即断（真挂死才断）。
+- 总量：本地 30min / 远程 10min。
+- `config.timeout.{firstTokenMs,streamIdleMs,totalMs}` 可覆盖；`parseStream` 按「帧到达」刷新
+  空闲计时（prefill 阶段服务端可能先发 usage-only 帧，不误杀）。
+
+### 4. 边缘检测 + 强制压缩
+模型每轮上报真实 `prompt_tokens`，≥ 窗口 85% 时下一轮 `force` 压缩——即便非 DeepSeek 模型
+启发式计数低估（误差 ±2 倍）也强制触发（`compact.js` force 绕过触发线门槛）。
+
+### 5. 工具输出截断自适应
+单条工具结果按 `窗口/16` 封顶（最少 2000 字），小窗口不再整条回灌大段代码。
+
+### 6. 配置/UI 打通
+- `customModels.<name>.contextWindow/maxOutputTokens`（WebUI 添加自定义模型表单新增两项）。
+- `config.timeout.*`（设置 → 通用面板新增三项，秒为单位，留空自适应）。
+- `/api/config`、`/api/models-config` 契约扩展。
+
+## 验收
+
+- smoke 新增 model-caps（本地/远程判定、窗口兜底/显式声明、舒适区+输出余量预算）与
+  provider 分层超时（首 token vs 流式空闲）两组断言。
+- 全绿：smoke 69 组 / e2e-local / e2e-web / e2e-schedule / api-contracts / bench；strict 0/0。
+- 用户在 3820 用本地模型跑长任务验收，确认无 network error 中断后发布。
+
+## 非目标（顺延）
+
+- 增量上下文（基线+变化）——自动续跑 + 语义检索已覆盖省钱与长程主场景。
+- 本地窗口自动探测（从服务端 /models 读 max_model_len）——依赖各家推理框架能力，暂用显式声明。

package/package.json

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

package/src/agent.js

@@ -6,6 +6,7 @@ import { trimMessages, clampText, messageTokens, approxTokens } from './context.
 import { compactConversation } from './compact.js';
 import { buildToolSchemas, dispatch } from './tools/index.js';
 import { modelPreset } from './models.js';
+import { resolveModelCaps, safeBudget, EDGE_RATIO } from './model-caps.js';
 import { makeTokenCounter } from './tokenizer.js';
 import { createHooks } from './hooks.js';
 import { createIO, style, C } from './ui.js';
@@ -29,8 +30,19 @@ const SUBAGENT_MAX_STEPS = 24;
  */
 export function createAgent({ provider, permission, io, modelName, workingDir, cfg = {}, undoStore, maxSteps, mcp, onCompact, sessionRef }) {
   const preset = modelPreset(modelName) || {};
-  const budget = cfg.contextBudget || preset.budgetTokens || 128000;
-  const maxOutput = cfg.maxOutputTokens || preset.maxOutputTokens || 8192;
+  // v0.3.2 模型自适应：预算按模型上下文窗口推导（留输出余量 + 75% 舒适区），
+  // 自定义/本地小模型不再套 128000 默认撑爆窗口；prompt 永不逼近窗口边缘（prefill 不爆炸）。
+  const caps = resolveModelCaps(cfg, modelName);
+  // safeBudget 恒用：即使用户显式 contextBudget 也套「窗口−输出−余量」上限与 75% 舒适区，
+  // 防显式值撑爆窗口（本地模型窗口可能只有 32k/131k，用户却留了默认 128000）。
+  const budget = safeBudget(cfg, caps);
+  // maxOutput 也按窗口封顶：显式配超大 maxOutputTokens 时，prompt(预算)+output 仍不得越过窗口
+  // （预算已按 caps.maxOutputTokens 留余量，但显式值可能更大——此处兜底，防服务端截断/拒绝）
+  const maxOutput = Math.min(cfg.maxOutputTokens || caps.maxOutputTokens, Math.max(1024, caps.contextWindow - budget));
+  // v0.3.2 工具输出截断自适应：窗口越小截得越狠（单条工具结果按窗口 1/16 封顶，最少 2000 字），
+  // 但绝不超过旧默认 20000（大窗口模型如 1M 不因公式放大回灌、不推高成本）。
+  // 本地小模型（32k 窗口 → 2k 字）不再把大段代码/日志整条回灌，省 prompt 且不撑爆窗口。
+  const toolResultCap = Math.min(20000, Math.max(2000, Math.floor(caps.contextWindow / 16)));
   const temperature = cfg.temperature ?? preset.temperature ?? 0.6;
   const reasoningEffort = cfg.reasoningByModel?.[modelName] ?? cfg.reasoningEffort ?? preset.reasoningEffort?.default ?? undefined;
   const hooks = createHooks(cfg.hooks, workingDir);
@@ -152,6 +164,9 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
     let aborted = false;
     let emptyRounds = 0; // 连续空/截断输出计数（防止无限续写）
     let currentAc = /** @type {any} */ (null);
+    // v0.3.2 边缘检测状态：模型上报 prompt_tokens 逼近窗口 → 下一轮强制压缩（见下方 compactConversation force）
+    let windowPressure = false;
+    let pressureWarned = false;
     // 省钱 B4（护栏降级）：action='downgrade' 超限后本回合切换到便宜模型继续执行；
     // activeModel 是本回合实际使用的模型（分账/记录归属它），downgraded 保证只提示一次。
     let activeModel = modelName;
@@ -201,6 +216,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
             provider,
             executorModel: subagentModel(cfg, modelName),
             triggerRatio: cfg.compactTrigger, // 可配置触发线（默认 80%）
+            force: windowPressure, // v0.3.2：逼近窗口时强制压缩（忽略最小阈值门槛）
           });
           if (compacted) {
             messages.splice(0, messages.length, ...compacted.messages);
@@ -368,6 +384,16 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         if (Number.isFinite(res.usage.prompt_cache_miss_tokens)) {
           usage.prompt_cache_miss_tokens = (usage.prompt_cache_miss_tokens || 0) + res.usage.prompt_cache_miss_tokens;
         }
+        // v0.3.2 边缘检测：模型上报的真实 prompt_tokens（含缓存命中）逼近窗口 85% 即标记——
+        // 下一轮强制激进压缩（force），不让 prompt 逼近窗口边缘导致 prefill 指数恶化。
+        const realPrompt = Number(res.usage.prompt_tokens);
+        if (Number.isFinite(realPrompt) && realPrompt > 0 && realPrompt >= caps.contextWindow * EDGE_RATIO) {
+          windowPressure = true;
+          if (!pressureWarned) {
+            pressureWarned = true;
+            io.print(style(`⚠ 上下文已逼近模型窗口（${realPrompt}/${caps.contextWindow}，≥${Math.round(EDGE_RATIO * 100)}%），下轮将强制压缩历史防 prefill 恶化`, C.yellow));
+          }
+        }
       }
 
       if (res.toolCalls?.length) {
@@ -529,7 +555,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           }
           const text = typeof result === 'string' ? result : JSON.stringify(result); // 紧凑 JSON（评估 B3）：嵌套结果省 10-20% 回填 token，且下轮按 prompt 重复计费
           const prefix = prep.cached ? '（与同回合相同调用结果一致，已复用）\n' : '';
-          messages.push({ role: 'tool', tool_call_id: prep.tc.id, content: prefix + clampText(text) });
+          messages.push({ role: 'tool', tool_call_id: prep.tc.id, content: prefix + clampText(text, toolResultCap) });
         }
 
         let i = 0;

package/src/compact.js

@@ -65,7 +65,9 @@ export async function compactConversation(/** @type {any} */ { messages, budget,
     total += t;
   }
   const trigger = Number.isFinite(Number(triggerRatio)) ? Number(triggerRatio) : DEFAULT_TRIGGER_RATIO;
-  if (total <= budget * trigger) return null;
+  // force（v0.3.2 边缘检测）：逼近窗口时即便启发式计数低估（total 未达触发线）也强制压缩——
+  // 非 DeepSeek 模型启发式计数误差可达 ±2 倍，等它越过触发线时真实 prompt 可能已到窗口边缘。
+  if (total <= budget * trigger && !force) return null;
   // 保留边界：保留段（boundary..end）≤ budget×TARGET_RATIO（system 恒保留）
   let keepTokens = sizes[0] ?? 0;
   let boundary = messages.length;

package/src/model-caps.js

@@ -0,0 +1,69 @@
+// 模型能力解析（v0.3.2 本地模型自适应）：
+// 把「模型能装多少上下文、单次最多输出多少、是否本地部署」收敛成单一来源，
+// 供预算推导、超时、工具截断统一引用——避免各层各自猜一份 128000 默认，
+// 本地小模型（窗口小/内存少）自动收紧预算与超时，不撑爆、不误杀。
+import { modelPreset } from './models.js';
+
+// 兜底：未知模型默认上下文窗口。本地小模型宁可保守（不撑爆）也不乐观。
+export const UNKNOWN_LOCAL_WINDOW = 32768;
+export const UNKNOWN_REMOTE_WINDOW = 128000;
+export const DEFAULT_MAX_OUTPUT = 8192;
+// 输出余量：prompt 预算必须给模型输出留足空间，否则 prompt+output 越过窗口 → 服务端截断/拒绝。
+export const OUTPUT_HEADROOM = 2048;
+// 舒适区：prompt 预算最多占窗口 75%——逼近 75% 以上时 prefill 时间陡增（长上下文 dequant 开销），
+// 留 25% 给输出 + 抗抖缓冲，从根上避免「prompt 到窗口边缘 → 首 token 等 200s+ 被客户端掐断」。
+export const COMFORT_RATIO = 0.75;
+// 边缘比：模型上报的真实 prompt_tokens 逼近窗口 85% 即视为「边缘」，本回合结束强制激进压缩。
+export const EDGE_RATIO = 0.85;
+
+/** 判断 baseUrl 是否指向本机/内网（本地推理框架部署）。 */
+export function isLocalBaseUrl(/** @type {any} */ baseUrl) {
+  try {
+    const u = new URL(String(baseUrl || ''));
+    const h = u.hostname.toLowerCase();
+    if (!h) return false;
+    if (h === 'localhost' || h === '::1') return true;
+    const m = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (!m) return false;
+    const a = Number(m[1]);
+    const b = Number(m[2]);
+    return a === 10 || a === 127 || a === 0 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 解析模型能力。优先级：customModels.<name>.contextWindow/maxOutputTokens > 内置 preset > 兜底。
+ * @param {any} cfg
+ * @param {string} modelName
+ * @returns {{ contextWindow: number, maxOutputTokens: number, isLocal: boolean, budgetTokens: number|null, preset: any }}
+ */
+export function resolveModelCaps(/** @type {any} */ cfg, /** @type {any} */ modelName) {
+  const preset = modelPreset(modelName);
+  const cm = (cfg?.customModels || {})[modelName] || {};
+  const baseUrl = cm.baseUrl || cfg?.baseUrl || '';
+  const isLocal = isLocalBaseUrl(baseUrl);
+  const contextWindow =
+    Number(cm.contextWindow) > 0
+      ? Number(cm.contextWindow)
+      : preset?.contextWindow || (isLocal ? UNKNOWN_LOCAL_WINDOW : UNKNOWN_REMOTE_WINDOW);
+  const maxOutputTokens =
+    Number(cm.maxOutputTokens) > 0
+      ? Number(cm.maxOutputTokens)
+      : preset?.maxOutputTokens || Math.min(DEFAULT_MAX_OUTPUT, Math.max(1024, Math.floor(contextWindow / 8)));
+  const budgetTokens = preset?.budgetTokens || null;
+  return { contextWindow, maxOutputTokens, isLocal, budgetTokens, preset };
+}
+
+/**
+ * 安全 prompt 预算：min(用户配置/预设, 窗口×75% 舒适区, 窗口−输出−余量)。
+ * 保证 prompt + maxOutput + 余量 ≤ contextWindow，且 prompt 不越舒适区（prefill 不爆炸）。
+ */
+export function safeBudget(/** @type {any} */ cfg, /** @type {any} */ caps) {
+  const ceiling = Math.max(1024, caps.contextWindow - caps.maxOutputTokens - OUTPUT_HEADROOM);
+  const comfort = Math.max(1024, Math.floor(caps.contextWindow * COMFORT_RATIO));
+  const configured = Number(cfg?.contextBudget) > 0 ? Number(cfg.contextBudget) : null;
+  const base = configured ?? caps.budgetTokens ?? comfort;
+  return Math.max(1024, Math.min(base, ceiling, comfort));
+}

package/src/providers/index.js

@@ -15,6 +15,7 @@ import { chat as openaiChat } from './openai-compatible.js';
 import { modelPreset, providerPreset } from '../models.js';
 import { mingdaoHome } from '../config.js';
 import { resolveApiKey } from '../credentials.js';
+import { isLocalBaseUrl } from '../model-caps.js';
 
 export function resolveProviderConfig(/** @type {any} */ cfg, /** @type {any} */ modelName) {
   // 自定义模型（config.customModels，WebUI 可增删改）：优先于内置预设
@@ -56,7 +57,7 @@ function isTransient(/** @type {any} */ err) {
   return /timeout|超时|ECONNRESET|fetch failed/i.test(String(err?.message || ''));
 }
 
-export async function createProvider(/** @type {any} */ cfg, /** @type {any} */ modelName, { timeoutMs = 300000, retries = 2 } = {}) {
+export async function createProvider(/** @type {any} */ cfg, /** @type {any} */ modelName, /** @type {{ timeoutMs?: number, retries?: number }} */ { timeoutMs, retries = 2 } = {}) {
   const pc = resolveProviderConfig(cfg, modelName);
 
   // 自定义 Provider 模块优先（仅普通自定义端点；custom:<模型名> 走 OpenAI 兼容直连）
@@ -74,6 +75,18 @@ export async function createProvider(/** @type {any} */ cfg, /** @type {any} */
     throw new Error(`服务商 "${pc.name}" 缺少 baseUrl，请运行 mingdao init 重新配置。`);
   }
 
+  // v0.3.2 本地模型自适应：本地推理框架（CPU/GPU 有限）长上下文 prefill 极慢（诊断实测 127k 上下文
+  // 首 token 需 196s+，q8 dequant 下 prefill 仅 ~165 tok/s）。默认超时按是否本地分层：
+  //  - 首 token 等待：本地 600s / 远程 300s（覆盖慢 prefill，而非 189s 被掐断）
+  //  - 流式空闲：有帧后 120s 无新帧即断（真正挂死才断，慢速吐字不误杀）
+  //  - 总量：本地 30min / 远程 10min（长生成不误杀）
+  // 均可用 cfg.timeout.firstTokenMs / streamIdleMs / totalMs 覆盖。
+  const isLocal = isLocalBaseUrl(pc.baseUrl);
+  const tCfg = cfg?.timeout || {};
+  const firstTokenMs = Number(tCfg.firstTokenMs) > 0 ? Number(tCfg.firstTokenMs) : (isLocal ? 600000 : 300000);
+  const streamIdleMs = Number(tCfg.streamIdleMs) > 0 ? Number(tCfg.streamIdleMs) : 120000;
+  const totalMs = Number(tCfg.totalMs) > 0 ? Number(tCfg.totalMs) : (Number(timeoutMs) > 0 ? Number(timeoutMs) : (isLocal ? 1800000 : 600000));
+
   return {
     name: pc.name,
     config: pc,
@@ -82,10 +95,32 @@ export async function createProvider(/** @type {any} */ cfg, /** @type {any} */
       for (;;) {
         const ac = new AbortController();
         let timedOut = false; // 审计 P2-6：用标志而非 name/字符串匹配识别内部超时
-        const timer = setTimeout(() => {
+        // 总量护栏：整次请求（prefill+生成）的绝对上限
+        const totalTimer = setTimeout(() => {
+          timedOut = true;
+          ac.abort(new Error(`请求总时长超限（${Math.round(totalMs / 1000)}s），已中断`));
+        }, totalMs);
+        // 首 token 等待：prefill 阶段无任何帧到达即断（覆盖长上下文慢 prefill）
+        let firstTokenTimer = /** @type {ReturnType<typeof setTimeout> | null} */ (setTimeout(() => {
           timedOut = true;
-          ac.abort(new Error('请求超时'));
-        }, timeoutMs);
+          ac.abort(new Error(`首 token 等待超限（${Math.round(firstTokenMs / 1000)}s，本地模型长上下文 prefill 可能很慢）——可调大 config.timeout.firstTokenMs，或拆分任务/压缩上下文`));
+        }, firstTokenMs));
+        // 流式空闲：有帧后 120s 无新帧即断；每收到一帧重置
+        let idleTimer = /** @type {ReturnType<typeof setTimeout> | null} */ (null);
+        const armIdle = () => {
+          if (idleTimer) clearTimeout(idleTimer);
+          idleTimer = setTimeout(() => {
+            timedOut = true;
+            ac.abort(new Error(`流式响应空闲超限（${Math.round(streamIdleMs / 1000)}s 无新数据）`));
+          }, streamIdleMs);
+        };
+        const onActivity = () => {
+          if (firstTokenTimer) {
+            clearTimeout(firstTokenTimer);
+            firstTokenTimer = null;
+          }
+          armIdle();
+        };
         // 转发外部信号（用户 Ctrl+C 中断），避免被内部超时信号覆盖
         const onUserAbort = () => ac.abort(opts.signal?.reason);
         if (opts.signal?.aborted) onUserAbort();
@@ -97,20 +132,24 @@ export async function createProvider(/** @type {any} */ cfg, /** @type {any} */
             apiKey: pc.apiKey,
             signal: ac.signal,
             includeUsage: cfg?.includeUsage !== false,
+            onActivity,
           });
         } catch (err) {
           // 内部超时经 abort 抛出，用标志识别（审计 P2-6）；用户 Ctrl+C 的中断不算超时、不重试
           const transient = (timedOut && !opts.signal?.aborted) || isTransient(err);
           if (!transient || attempt >= retries) throw err;
           attempt += 1;
-          // 指数退避 + 尊重 Retry-After（评估 P3-1）：基础 1s/2s，服务端指定时取其值（封顶 30s）
+          // 首 token 等待超时通常不是偶发网络抖动（是模型/上下文慢），重试价值低但保留一次机会；
+          // 其余瞬态错误指数退避 + 尊重 Retry-After（评估 P3-1）：基础 1s/2s，封顶 30s
           let backoff = 1000 * attempt;
           const ra = Number((/** @type {any} */ (err))?.headers?.get?.('retry-after'));
           if (Number.isFinite(ra) && ra > 0) backoff = Math.max(backoff, ra * 1000);
           backoff = Math.min(backoff, 30000);
           await sleep(backoff);
         } finally {
-          clearTimeout(timer);
+          clearTimeout(totalTimer);
+          if (firstTokenTimer) clearTimeout(firstTokenTimer);
+          if (idleTimer) clearTimeout(idleTimer);
           opts.signal?.removeEventListener('abort', onUserAbort);
         }
       }

package/src/providers/openai-compatible.js

@@ -6,7 +6,7 @@
  * @typedef {Error & { status?: number, headers?: Headers }} ApiError
  */
 
-export async function chat(/** @type {any} */ { baseUrl, apiKey, model, messages, tools, temperature, maxTokens, signal, onDelta, includeUsage = true, responseFormat, reasoningEffort }) {
+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 });
   if (temperature != null) payload.temperature = temperature;
@@ -62,7 +62,7 @@ export async function chat(/** @type {any} */ { baseUrl, apiKey, model, messages
     if (!json) throw new Error(`[${model}] 响应解析失败。`);
     return parseNonStream(json, onDelta);
   }
-  return parseStream(res.body, onDelta);
+  return parseStream(res.body, onDelta, onActivity);
 }
 
 export function parseNonStream(/** @type {any} */ json, /** @type {any} */ onDelta) {
@@ -81,7 +81,9 @@ export function parseNonStream(/** @type {any} */ json, /** @type {any} */ onDel
 }
 
 // 解析 SSE 流：处理跨 chunk 断行、增量 content / reasoning_content / tool_calls。
-export async function parseStream(/** @type {any} */ body, /** @type {any} */ onDelta) {
+// onActivity：每收到一个有效 SSE 数据帧即回调（含 usage-only 帧），供上层做「首 token 等待/流式空闲」超时仲裁——
+// 长上下文 prefill 时服务端可能 200s+ 无正文，靠「有帧到达」而非「有正文」判定存活，避免误杀慢 prefill。
+export async function parseStream(/** @type {any} */ body, /** @type {any} */ onDelta, /** @type {any} */ onActivity) {
   const reader = body.getReader();
   const decoder = new TextDecoder();
   let buf = '';
@@ -151,6 +153,9 @@ export async function parseStream(/** @type {any} */ body, /** @type {any} */ on
     while ((nl = buf.indexOf('\n')) >= 0) {
       const line = buf.slice(0, nl);
       buf = buf.slice(nl + 1);
+      // 有帧到达即视为「活着」：prefill 阶段服务端可能先发 usage-only/空帧，正文迟迟不来，
+      // 靠帧到达刷新上层流式空闲计时器（首 token 等待则仍由「无任何帧」触发）
+      if (line.trim()) onActivity?.();
       if (handleLine(line)) break;
     }
   }

package/src/web/app.js

@@ -629,6 +629,10 @@ async function init(){
     $('#sbxHint').textContent=j.sandboxSupported?'':'当前环境未检测到 bubblewrap，readonly/safe 将自动降级为 off';
     $('#routeChk').checked=Boolean(j.routing);
     $('#budgetInput').value=j.contextBudget||128000;
+    const to=j.timeout||{};
+    $('#toFirstToken').value=to.firstTokenMs?Math.round(to.firstTokenMs/1000):'';
+    $('#toStreamIdle').value=to.streamIdleMs?Math.round(to.streamIdleMs/1000):'';
+    $('#toTotal').value=to.totalMs?Math.round(to.totalMs/1000):'';
     $('#autoStartChk').checked=Boolean(j.autostart);
     $('#notifyChk').checked=j.notify!==false;
     applyReasoningUI(j.reasoning);
@@ -928,9 +932,9 @@ $('#cmAdd').onclick=async ()=>{
   const name=$('#cmName').value.trim();
   const url=$('#cmUrl').value.trim();
   if(!name||!url){ uiAlert('模型名与 API 地址必填'); return; }
-  const r=await fetch('/api/models-config',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({action:'addCustom',name,label:$('#cmLabel').value.trim(),baseUrl:url,key:$('#cmKey').value})});
+  const r=await fetch('/api/models-config',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({action:'addCustom',name,label:$('#cmLabel').value.trim(),baseUrl:url,key:$('#cmKey').value,contextWindow:Number($('#cmCtx').value)||undefined,maxOutputTokens:Number($('#cmMaxOut').value)||undefined})});
   const j=await r.json().catch(()=>({error:'请求失败'}));
-  if(j.ok){ $('#cmName').value=''; $('#cmLabel').value=''; $('#cmUrl').value=''; $('#cmKey').value=''; refreshModelsCfg(); reloadModels(); } else uiAlert(j.error||'添加失败');
+  if(j.ok){ $('#cmName').value=''; $('#cmLabel').value=''; $('#cmUrl').value=''; $('#cmKey').value=''; $('#cmCtx').value=''; $('#cmMaxOut').value=''; refreshModelsCfg(); reloadModels(); } else uiAlert(j.error||'添加失败');
 };
 $('#baseUrlSave').onclick=async ()=>{
   const r=await fetch('/api/models-config',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({action:'setBaseUrl',baseUrl:$('#baseUrlOverride').value.trim()})});
@@ -1021,7 +1025,7 @@ async function refreshSyncConflicts(){
     list.appendChild(div);
   }
 }
-$('#cfgSave').onclick=()=>{ applyConfig({sandbox:$('#sbxSel').value, routing:$('#routeChk').checked, contextBudget:Number($('#budgetInput').value), autostart:$('#autoStartChk').checked, notify:$('#notifyChk').checked}); $('#cfgModal').style.display='none'; };
+$('#cfgSave').onclick=()=>{ const to={}; const ft=Number($('#toFirstToken').value), si=Number($('#toStreamIdle').value), tt=Number($('#toTotal').value); if(ft>0) to.firstTokenMs=Math.round(ft*1000); if(si>0) to.streamIdleMs=Math.round(si*1000); if(tt>0) to.totalMs=Math.round(tt*1000); const payload={sandbox:$('#sbxSel').value, routing:$('#routeChk').checked, contextBudget:Number($('#budgetInput').value), autostart:$('#autoStartChk').checked, notify:$('#notifyChk').checked}; if(Object.keys(to).length) payload.timeout=to; applyConfig(payload); $('#cfgModal').style.display='none'; };
 async function applyConfig(payload, revertTarget){
   const r=await fetch('/api/config',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(payload)});
   const j=await r.json().catch(()=>({error:'请求失败'}));

package/src/web/index.html

@@ -378,6 +378,11 @@ footer{flex:none;border-top:1px solid var(--border);background:var(--bg2);paddin
       <input id="cmUrl" placeholder="API 地址 https://…/v1" style="flex:1.4;min-width:170px;background:var(--bg3);color:var(--text);border:1px solid var(--border);border-radius:8px;padding:6px 10px;font-size:13px">
       <input id="cmKey" type="password" placeholder="API Key（可选）" style="flex:1;min-width:120px;background:var(--bg3);color:var(--text);border:1px solid var(--border);border-radius:8px;padding:6px 10px;font-size:13px">
     </div>
+    <div class="cfg-row" style="display:flex;gap:6px;flex-wrap:wrap">
+      <input id="cmCtx" type="number" placeholder="上下文窗口 tokens（本地模型建议填，如 131072）" style="flex:1.6;min-width:180px;background:var(--bg3);color:var(--text);border:1px solid var(--border);border-radius:8px;padding:6px 10px;font-size:13px">
+      <input id="cmMaxOut" type="number" placeholder="最大输出 tokens（可选，如 8192）" style="flex:1;min-width:120px;background:var(--bg3);color:var(--text);border:1px solid var(--border);border-radius:8px;padding:6px 10px;font-size:13px">
+    </div>
+    <div class="cfg-hint">本地部署模型（127.0.0.1/localhost）：填「上下文窗口」后预算自动收紧到窗口 75% 以内并留输出余量，长任务不再撑爆窗口。</div>
     <div class="row" style="justify-content:flex-start"><button id="cmAdd">＋ 添加自定义模型</button></div>
     <div class="cfg-row" style="display:flex;gap:6px"><input id="baseUrlOverride" placeholder="API 地址覆盖（可选，覆盖当前服务商地址）" style="flex:1;background:var(--bg3);color:var(--text);border:1px solid var(--border);border-radius:8px;padding:6px 10px;font-size:13px"><button id="baseUrlSave">保存</button></div>
       </section>
@@ -418,6 +423,12 @@ footer{flex:none;border-top:1px solid var(--border);background:var(--bg2);paddin
     </div>
     <div class="cfg-row"><label><input type="checkbox" id="routeChk"> 自动模型路由（规划→pro / 执行→flash）</label></div>
     <div class="cfg-row"><label>上下文预算 tokens <input type="number" id="budgetInput" min="1000" step="1000"></label></div>
+    <div class="cfg-row" style="display:flex;gap:6px;flex-wrap:wrap;align-items:flex-end">
+      <label style="font-size:12px">首 token 等待（秒）<input type="number" id="toFirstToken" min="0" step="10" placeholder="自动"></label>
+      <label style="font-size:12px">流式空闲（秒）<input type="number" id="toStreamIdle" min="0" step="10" placeholder="自动"></label>
+      <label style="font-size:12px">总量（秒）<input type="number" id="toTotal" min="0" step="10" placeholder="自动"></label>
+    </div>
+    <div class="cfg-hint">留空 = 自适应：本地模型自动给更长首 token 等待（慢 prefill 不被误杀）。仅在默认值仍不够/过松时手填。</div>
     <div class="cfg-row"><label><input type="checkbox" id="autoStartChk"> 开机自启（登录后自动启动服务器）</label></div>
     <div class="cfg-row"><label><input type="checkbox" id="notifyChk"> 后台任务完成/失败时桌面通知</label></div>
       </section>

package/src/web/routes/domains/config.js

@@ -50,6 +50,7 @@ export async function handle({ req, res, method, p, url }, deps, shared) {
       routing: cfg.routing?.enabled ? cfg.routing : null,
       reasoning,
       contextBudget: cfg.contextBudget || 128000,
+      timeout: cfg.timeout || null, // v0.3.2：分层超时（firstTokenMs/streamIdleMs/totalMs）
       pricingAsOf: PRICE_DATA_AS_OF,
       autostart: autostartStatus(),
       notify: cfg.notify !== false,
@@ -112,6 +113,17 @@ export async function handle({ req, res, method, p, url }, deps, shared) {
       next.contextBudget = n;
       cfg.contextBudget = n;
     }
+    // v0.3.2 超时分层：firstTokenMs（首 token 等待）/ streamIdleMs（流式空闲）/ totalMs（总量）
+    if (body.timeout !== undefined && body.timeout && typeof body.timeout === 'object') {
+      cfg.timeout = cfg.timeout || {};
+      for (const k of ['firstTokenMs', 'streamIdleMs', 'totalMs']) {
+        const v = Number(body.timeout[k]);
+        if (Number.isFinite(v) && v > 0) cfg.timeout[k] = Math.round(v);
+        else if (body.timeout[k] === null || body.timeout[k] === '') delete cfg.timeout[k];
+      }
+      // 超时在 createProvider 时按 cfg 固化进实例，改后清缓存让新值即时生效（否则要重启）
+      providerCache.clear();
+    }
     if (body.reasoningEffort !== undefined) {
       const re = String(body.reasoningEffort);
       if (!['off', 'low', 'high', 'max'].includes(re)) {
@@ -165,6 +177,8 @@ export async function handle({ req, res, method, p, url }, deps, shared) {
         baseUrl: cm.baseUrl || '',
         envKey: cm.envKey || null,
         vision: Boolean(cm.vision),
+        contextWindow: Number(cm.contextWindow) > 0 ? Number(cm.contextWindow) : null,
+        maxOutputTokens: Number(cm.maxOutputTokens) > 0 ? Number(cm.maxOutputTokens) : null,
         keyState: stored ? 'stored' : 'none',
         keyMasked: stored ? maskKey(stored) : null,
       };
@@ -232,14 +246,23 @@ export async function handle({ req, res, method, p, url }, deps, shared) {
         return json(res, 400, { error: `自定义模型 ${name} 已存在（可修改）` });
       }
       cfg.customModels = cfg.customModels || {};
+      // 修改时保留未提交字段（tokenizer/contextWindow/maxOutputTokens/vision）——
+      // 前端「修改」只发 baseUrl+label，整体替换会丢这些声明，导致本地模型窗口回退兜底
+      const prev = action === 'updateCustom' ? (cfg.customModels[name] || {}) : {};
       cfg.customModels[name] = {
         label,
         baseUrl,
-        envKey: String(body.envKey || '').trim() || undefined,
-        vision: body.vision === true || body.vision === 'on' ? true : undefined,
+        envKey: String(body.envKey || '').trim() || prev.envKey || undefined,
+        vision: body.vision === true || body.vision === 'on' ? true : prev.vision === true ? true : undefined,
+        ...(prev.tokenizer ? { tokenizer: prev.tokenizer } : {}),
+        // v0.3.2 本地模型自适应：显式声明上下文窗口/最大输出，预算据此推导（不撑爆窗口）
+        ...(Number(body.contextWindow) > 0 ? { contextWindow: Math.round(Number(body.contextWindow)) } : (prev.contextWindow ? { contextWindow: prev.contextWindow } : {})),
+        ...(Number(body.maxOutputTokens) > 0 ? { maxOutputTokens: Math.round(Number(body.maxOutputTokens)) } : (prev.maxOutputTokens ? { maxOutputTokens: prev.maxOutputTokens } : {})),
       };
       if (String(body.key || '').trim()) setStoredKey(`custom:${name}`, String(body.key).trim());
       saveConfig(cfg);
+      // baseUrl 改动影响 isLocal 判定 → 超时档位变化；清缓存让新超时/新端点即时生效
+      providerCache.clear();
       return json(res, 200, { ok: true, name });
     }
     if (action === 'removeCustom') {
@@ -252,6 +275,7 @@ export async function handle({ req, res, method, p, url }, deps, shared) {
         cfg.model = state.modelName;
       }
       saveConfig(cfg);
+      providerCache.clear();
       return json(res, 200, { ok: true, name, model: state.modelName });
     }
     // 质检（自定义模型连通性）：发起一次最小对话验证 baseUrl+Key 可用

package/src/web/server.js

@@ -551,7 +551,9 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
         const { messageTokens } = await import('../context.js');
         const counter = makeTokenCounter(runModel);
         const used = messages.reduce((/** @type {any} */ sum, /** @type {any} */ m) => sum + messageTokens(m, counter), 0);
-        budgetInfo = { used, total: cfg.contextBudget || modelPreset(runModel)?.budgetTokens || 128000 };
+        // v0.3.2：展示用 total 与 Agent 实际预算同源（safeBudget 按窗口推导），避免「显示 128k 实际 98k」的误导
+        const { resolveModelCaps, safeBudget } = await import('../model-caps.js');
+        budgetInfo = { used, total: safeBudget(cfg, resolveModelCaps(cfg, runModel)) };
       } catch {}
       send({
         type: 'done',