mingdao-harness 0.3.1 → 0.4.0

package/src/cli.js

@@ -79,6 +79,7 @@ const HELP_LINES = [
   ['  mingdao --journal          新会话带上最近会话日志（默认不注入，新会话全新开始）', null],
   ['  mingdao --resume           从会话列表选择恢复', null],
   ['  mingdao --model <模型名>   指定模型，例如 deepseek-v4-pro', null],
+  ['  mingdao --preset <名>      应用智能体预设（工具白名单/权限/参数，v0.4.0 契约化）', null],
   ['  mingdao init               初始化配置向导', null],
   ['  mingdao update [--check]   一键自更新（git 安装形态；--check 只对比版本）', null],
   ['  mingdao rollback           回滚到上次 update 之前的提交', null],
@@ -125,6 +126,8 @@ function parseArgs(/** @type {any} */ argv) {
     else if (a === '-v' || a === '--version') opts.version = true;
     else if (a === '-c' || a === '--continue') opts.continueSession = true;
     else if (a === '--journal') opts.journal = true;
+    else if (a === '-p' || a === '--preset') opts.preset = argv[++i];
+    else if (a.startsWith('--preset=')) opts.preset = a.slice(9);
     else if (a === '-r' || a === '--resume') opts.resume = true;
     else if (a === '--init' || a === 'init') opts.init = true;
     else if (a === '-m' || a === '--model') opts.model = argv[++i];
@@ -350,6 +353,29 @@ async function main() {
   // 模型回退链（向导允许跳过模型选择 → cfg.model 可缺省）：参数 > config > 该服务商首个预设模型 > flash
   let modelName = opts.model || cfg.model || /** @type {any} */ (PROVIDERS)[cfg.provider]?.models?.[0] || 'deepseek-v4-flash';
   const io = createIO();
+  const workingDir = process.cwd();
+
+  // v0.4.0 Agent Preset：--preset <名> 应用声明式预设（工具白名单/权限/模型/参数 + 系统提示定制段）。
+  // 预设覆盖优先级：CLI 显式参数 > 预设 > config.json。
+  // 会话级 overlay：不改写 cfg（否则 REPL /model、/think 的 saveConfig 会把预设字段持久化进 config.json）。
+  let activePreset = /** @type {any} */ (null);
+  let presetBlock = '';
+  let presetOverlay = /** @type {Record<string, any>} */ ({});
+  if (opts.preset) {
+    const { loadPreset, presetConfigOverrides, presetSystemBlock, listPresets } = await import('./presets.js');
+    activePreset = loadPreset(workingDir, opts.preset);
+    if (!activePreset) {
+      const names = listPresets(workingDir).map((/** @type {any} */ p) => p.name).join(', ') || '（无可用预设）';
+      io.print(style(`⚠ 预设 "${opts.preset}" 不存在。可用：${names}`, C.yellow));
+    } else {
+      presetOverlay = { ...presetConfigOverrides(activePreset), presetName: activePreset.name };
+      if (!opts.model && presetOverlay.model) modelName = presetOverlay.model;
+      presetBlock = presetSystemBlock(activePreset);
+      io.print(style(`▣ 已应用智能体预设：${activePreset.name}${activePreset.label ? '（' + activePreset.label + '）' : ''}`, C.cyan));
+    }
+  }
+  // agent 使用的配置 = cfg + 预设 overlay（presetTools/permission/参数按预设生效，cfg 本体保持干净）
+  const agentCfg = Object.keys(presetOverlay).length ? { ...cfg, ...presetOverlay } : cfg;
 
   const pc0 = resolveProviderConfig(cfg, modelName);
   if (!pc0.apiKey) {
@@ -367,8 +393,13 @@ async function main() {
   }
 
   let provider = await createProvider(cfg, modelName);
-  const permission = createPermission(cfg.permission ?? 'ask', io);
-  const workingDir = process.cwd();
+  const permission = createPermission(agentCfg.permission ?? 'ask', io);
+  // v0.4.0 契约化：挂载 config.tools 声明式第三方工具（幂等，重启生效）
+  {
+    const { mountConfigTools } = await import('./tools/index.js');
+    const mounted = mountConfigTools(cfg);
+    if (mounted.length) io.print(style(`🔧 已挂载声明式工具（config.tools）：${mounted.join(', ')}`, C.dim));
+  }
   // 会话级 undo 备份仓：模型切换、子代理均共享，撤销记录不丢失
   const sessionUndoStore = { backups: new Map() };
   // MCP 服务器：后台启动（不阻塞交互），就绪后工具自动出现在后续轮次
@@ -410,7 +441,7 @@ async function main() {
     io,
     modelName,
     workingDir,
-    cfg,
+    cfg: agentCfg,
     undoStore: sessionUndoStore,
     mcp: mcpFacade,
     sessionRef,
@@ -440,7 +471,7 @@ async function main() {
     const turnIo = jsonMode ? createIO({ quiet: true }) : io;
     const session = createSession(home);
     const messages = [
-      { role: 'system', content: buildSystemPrompt({ modelName, workingDir, withJournal }) },
+      { role: 'system', content: buildSystemPrompt({ modelName, workingDir, withJournal, presetBlock }) },
       { role: 'user', content: question },
     ];
     let oneShotPersisted = messages.length;
@@ -451,7 +482,7 @@ async function main() {
       io: turnIo,
       modelName,
       workingDir,
-      cfg,
+      cfg: agentCfg,
       undoStore: sessionUndoStore,
       mcp: mcpFacade,
       sessionRef: oneShotRef,
@@ -528,7 +559,7 @@ async function main() {
 
   // —— 交互式 TUI（Phase C C2：已抽取至 commands/repl.js） ——
   const { runRepl } = await import('./commands/repl.js');
-  await runRepl({ io, cfg, home, pc0, opts, modelName, provider, permission, workingDir, sessionUndoStore, mcpFacade, mcpManager, sessionRef, agent, preset, withJournal, tuiState });
+  await runRepl({ io, cfg, agentCfg, home, pc0, opts, modelName, provider, permission, workingDir, sessionUndoStore, mcpFacade, mcpManager, sessionRef, agent, preset, withJournal, presetBlock, tuiState });
   return;
 
 }

package/src/commands/repl.js

@@ -98,6 +98,7 @@ const HELP_LINES = [
   ['会话内命令', C.bold + C.yellow],
   ['  /help        显示帮助          /clear   清空上下文', null],
   ['  /model <名>  切换模型          /mode    pro/flash 快捷切换', null],
+  ['  /preset      列出/切换智能体预设（v0.4.0 契约化）', null],
   ['  /compact     压缩上下文        /plan    计划模式（先计划后执行）', null],
   ['  /init        生成 AGENTS.md    /memory add <内容> 追加用户记忆', null],
   ['  /skills      列出技能          /status  会话状态 · /cost 累计费用', null],
@@ -140,6 +141,10 @@ async function generatePlan(provider, modelName, task) {
  */
 export async function runRepl(ctx) {
   const { io, cfg, home, pc0, opts, permission, workingDir, sessionUndoStore, mcpFacade, sessionRef, preset, withJournal, tuiState } = ctx;
+  let presetBlock = ctx.presetBlock || ''; // v0.4.0 Agent Preset 系统提示定制段（/preset 可切换）
+  let permissionNow = permission; // /preset 可换权限模式
+  // v0.4.0 Agent Preset：agent 用 agentCfg（预设 overlay 会话级生效）；cfg 保持干净供 saveConfig 持久化
+  let agentCfg = ctx.agentCfg || cfg;
   let mcpManager = ctx.mcpManager;
   let modelName = ctx.modelName;
   let provider = ctx.provider;
@@ -216,7 +221,7 @@ export async function runRepl(ctx) {
   sessionRef.name = path.basename(session.file);
   io.print(style(`会话  ${path.basename(session.file)}`, C.dim));
 
-  const systemPrompt = buildSystemPrompt({ modelName, workingDir, withJournal });
+  const systemPrompt = buildSystemPrompt({ modelName, workingDir, withJournal, presetBlock });
   // 恢复会话时刷新 system prompt（用户记忆 / AGENTS.md / 技能清单 / 时间戳以当前为准），
   // 旧 system 消息保留在会话文件中，不影响追加历史。
   const loadedMsgs = session.messages || [];
@@ -258,11 +263,11 @@ export async function runRepl(ctx) {
       }
       agent = createAgent({
         provider,
-        permission,
+        permission: permissionNow,
         io,
         modelName,
         workingDir,
-        cfg,
+        cfg: agentCfg, // v0.4.0：预设 overlay 恒生效（/model 后白名单不丢）
         undoStore: sessionUndoStore,
         mcp: mcpFacade,
         sessionRef,
@@ -271,7 +276,7 @@ export async function runRepl(ctx) {
           tuiState.persisted = msgs.length;
         },
       });
-      messages[0] = { role: 'system', content: buildSystemPrompt({ workingDir, withJournal }) };
+      messages[0] = { role: 'system', content: buildSystemPrompt({ workingDir, withJournal, presetBlock }) };
       if (!silent) {
         const p2 = modelPreset(modelName);
         io.print(style(`✓ 已切换到 ${C.bold}${modelName}${C.reset}${p2 ? `（${p2.label}）` : ''}`, C.green));
@@ -309,6 +314,38 @@ export async function runRepl(ctx) {
         } catch {}
         tuiState.persisted = messages.length;
         io.print('已清空上下文（会话文件已同步重置）。');
+      } else if (cmd === '/preset') {
+        // v0.4.0 Agent Preset：列出/切换声明式智能体预设（工具白名单/权限/参数 + 系统提示定制段）
+        const { listPresets, loadPreset, presetConfigOverrides, presetSystemBlock } = await import('../presets.js');
+        if (!arg) {
+          const ps = listPresets(workingDir);
+          if (!ps.length) io.print(style('（无可用预设。目录：<项目>/.mingdao/presets/、~/.mingdao/presets/、内置 presets/）', C.dim));
+          else for (const p of ps) io.print(`  - ${p.name}（${p.label || '无标签'}，${p.source === 'project' ? '项目' : p.source === 'user' ? '用户' : '内置'}）${p.description ? '：' + p.description : ''}`);
+          continue;
+        }
+        const pname = arg.split(/\s+/)[0];
+        const p = loadPreset(workingDir, pname);
+        if (!p) {
+          io.print(style(`预设 "${pname}" 不存在（/preset 列出全部）。`, C.yellow));
+          continue;
+        }
+        const over = presetConfigOverrides(p);
+        // 应用覆盖：权限/参数/工具白名单/模型建议——只进 agentCfg（会话级 overlay），
+        // 绝不改写 cfg：否则后续 /model、/think 的 saveConfig 会把预设字段持久化进 config.json。
+        agentCfg = { ...cfg, ...over, presetName: p.name };
+        if (over.model) await switchToModel(over.model, { silent: true, persist: false });
+        presetBlock = presetSystemBlock(p);
+        permissionNow = createPermission(agentCfg.permission ?? 'ask', io);
+        agent = createAgent({
+          provider, permission: permissionNow, io, modelName, workingDir, cfg: agentCfg,
+          undoStore: sessionUndoStore, mcp: mcpFacade, sessionRef,
+          onCompact: (/** @type {any} */ msgs) => {
+            rewriteSession(session.file, msgs);
+            tuiState.persisted = msgs.length;
+          },
+        });
+        messages[0] = { role: 'system', content: buildSystemPrompt({ workingDir, withJournal, presetBlock }) };
+        io.print(style(`▣ 已应用智能体预设：${p.name}${p.label ? '（' + p.label + '）' : ''}${over.presetTools ? `，工具白名单 ${over.presetTools.length} 个` : ''}`, C.green));
       } else if (cmd === '/model') {
         if (!arg) {
           io.print(`当前模型：${modelName}`);
@@ -336,7 +373,7 @@ export async function runRepl(ctx) {
           saveConfig(cfg);
         } else { io.print(style('无效取值：low|high|max|off', C.red)); continue; }
         agent = createAgent({
-          provider, permission, io, modelName, workingDir, cfg,
+          provider, permission: permissionNow, io, modelName, workingDir, cfg: agentCfg,
           undoStore: sessionUndoStore, mcp: mcpFacade, sessionRef,
           onCompact: (/** @type {any} */ msgs) => {
             rewriteSession(session.file, msgs);

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/index.js

@@ -1,13 +1,35 @@
 // MingDao-Harness 公共 API：供第三方程序/插件以库形式复用核心能力。
+// 稳定性契约（v0.4.0 起）：@stable 在 minor 版本内保持向后兼容；@experimental 可能变更。
+// 详细契约与示例见 docs/DEVELOPER.md。
 
+// —— @stable：Agent 内核 ——
 export { createAgent } from './agent.js';
+export { createPermission } from './permissions.js';
+export { createIO, style, C } from './ui.js';
+
+// —— @stable：Provider 与模型 ——
 export { createProvider, resolveProviderConfig } from './providers/index.js';
-export { toolSchemas, dispatch } from './tools/index.js';
+export { MODELS, PROVIDERS, modelPreset, providerPreset } from './models.js';
+export { resolveModelCaps, safeBudget, isLocalBaseUrl } from './model-caps.js';
+
+// —— @stable：工具（含 v0.4.0 第三方注册）——
+export { toolSchemas, dispatch, registerTool, listRegisteredTools, mountConfigTools, buildToolSchemas } from './tools/index.js';
+
+// —— @stable：Agent Preset（v0.4.0）——
+export {
+  listPresets,
+  loadPreset,
+  validatePreset,
+  presetConfigOverrides,
+  presetSystemBlock,
+  presetDirs,
+} from './presets.js';
+
+// —— @stable：上下文与压缩 ——
 export { trimMessages, approxTokens, clampText, TOOL_RESULT_LIMIT } from './context.js';
 export { compactConversation, summarizeConversation } from './compact.js';
-export { createPermission } from './permissions.js';
-export { MODELS, PROVIDERS, modelPreset, providerPreset } from './models.js';
-export { createIO, style, C } from './ui.js';
+
+// —— @stable：配置与凭证 ——
 export {
   mingdaoHome,
   ensureHome,
@@ -26,8 +48,12 @@ export {
   maskKey,
   resolveApiKey,
 } from './credentials.js';
+
+// —— @stable：计价与计量 ——
 export { estimateCost, estimateCostLabel, isPeakHour, PRICE_DATA_AS_OF } from './pricing.js';
 export { countTokens, heuristicTokens, makeTokenCounter, isTokenizable } from './tokenizer.js';
+
+// —— @experimental：更新/审计/技能/会话（接口可能调整）——
 export { updateCheck, mingdaoUpdate, mingdaoRollback, findRepoRoot } from './update.js';
 export { writeAudit, listAudit, redactSecrets, auditFile } from './audit.js';
 export { trustSkill, skillDirHash, readSourceMeta } from './skill-lib.js';

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/presets.js

@@ -0,0 +1,154 @@
+// Agent Preset（v0.4.0 契约化）：声明式智能体预设——把「系统提示 + 工具集 + 权限 + 模型 + 参数」
+// 打包成一个可安装、可复用、可分享的 JSON 单元，让开发者/用户不改源码就能定制自己的智能体。
+//
+// 发现顺序（同名后者遮蔽前者）：
+//   1. 项目级  <工作目录>/.mingdao/presets/*.json
+//   2. 用户级  <mingdao-home>/presets/*.json
+//   3. 内置    随 npm 包分发的 presets/ 目录（只读参考实现）
+//
+// 预设字段（全部可选，缺省时保持当前配置不变）：
+//   name          唯一名（必填，字母/数字/-/_，1-64）
+//   label         展示名（可选，默认 name）
+//   description   一句话用途
+//   systemPrompt  追加到系统提示的定制段（角色/规则/上下文约定）
+//   tools         工具白名单（数组，省略=不限制）
+//   permission    权限模式 ask/auto/readonly（省略=当前配置）
+//   model         建议模型（省略=当前模型）
+//   temperature / maxOutputTokens / maxRounds / contextBudget  参数覆盖
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mingdaoHome, ensureHome } from './config.js';
+
+const PRESET_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+// 合法字段白名单：未知字段报错（防拼写错误静默失效——契约化核心）
+const KNOWN_FIELDS = new Set([
+  'name', 'label', 'description', 'systemPrompt', 'tools',
+  'permission', 'model', 'temperature', 'maxOutputTokens', 'maxRounds', 'contextBudget',
+]);
+const PERMISSION_MODES = ['ask', 'auto', 'readonly'];
+
+/** 内置预设目录（随 npm 包分发，只读参考）。 */
+export function builtinPresetDir() {
+  return path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'presets');
+}
+
+/** 发现目录与 source 标签对齐（遮蔽顺序：项目 → 用户 → 内置）。 */
+function presetLocations(/** @type {any} */ workingDir) {
+  const locs = [];
+  if (workingDir) locs.push({ dir: path.join(String(workingDir), '.mingdao', 'presets'), source: 'project' });
+  locs.push({ dir: path.join(mingdaoHome(), 'presets'), source: 'user' });
+  locs.push({ dir: builtinPresetDir(), source: 'builtin' });
+  return locs;
+}
+
+/** @param {any} workingDir 预设发现目录（按遮蔽顺序：项目 → 用户 → 内置）。 */
+export function presetDirs(/** @type {any} */ workingDir) {
+  return presetLocations(workingDir).map((/** @type {any} */ l) => l.dir);
+}
+
+/** @param {any} obj 校验预设对象，返回 { ok, errors: string[] }。 */
+export function validatePreset(/** @type {any} */ obj) {
+  const errors = [];
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return { ok: false, errors: ['预设必须是 JSON 对象'] };
+  const name = String(obj.name ?? '').trim();
+  if (!name) errors.push('缺少 name 字段');
+  else if (!PRESET_NAME_RE.test(name)) errors.push(`name 非法（${PRESET_NAME_RE}）：${name}`);
+  for (const k of Object.keys(obj)) {
+    if (!KNOWN_FIELDS.has(k)) errors.push(`未知字段：${k}（合法：${[...KNOWN_FIELDS].join('/')}）`);
+  }
+  if (obj.systemPrompt !== undefined && typeof obj.systemPrompt !== 'string') errors.push('systemPrompt 必须是字符串');
+  if (obj.tools !== undefined && (!Array.isArray(obj.tools) || obj.tools.some((/** @type {any} */ t) => typeof t !== 'string'))) {
+    errors.push('tools 必须是字符串数组');
+  }
+  if (obj.permission !== undefined && !PERMISSION_MODES.includes(String(obj.permission))) {
+    errors.push(`permission 必须是 ${PERMISSION_MODES.join('/')}`);
+  }
+  for (const k of ['temperature', 'maxOutputTokens', 'maxRounds', 'contextBudget']) {
+    if (obj[k] !== undefined && !(Number.isFinite(Number(obj[k])) && Number(obj[k]) > 0)) {
+      errors.push(`${k} 必须是正数`);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * 列出全部可用预设（发现顺序：项目遮蔽用户遮蔽内置，同名只留前者）。
+ * 返回 [{ name, label, description, source: 'project'|'user'|'builtin', file }]
+ */
+export function listPresets(/** @type {any} */ workingDir) {
+  ensureHome();
+  const seen = new Map();
+  const order = /** @type {string[]} */ ([]);
+  for (const { dir, source } of presetLocations(workingDir)) {
+    let files = [];
+    try {
+      files = fs.readdirSync(dir).filter((/** @type {any} */ f) => f.endsWith('.json'));
+    } catch {
+      continue;
+    }
+    for (const f of files) {
+      if (seen.has(f)) continue;
+      seen.set(f, { dir, source });
+      order.push(f);
+    }
+  }
+  const out = [];
+  for (const f of order) {
+    const { dir, source } = seen.get(f);
+    try {
+      const obj = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+      const v = validatePreset(obj);
+      if (!v.ok) continue; // 非法预设跳过并静默（不阻塞会话）；diagnose 可查
+      out.push({
+        name: String(obj.name),
+        label: String(obj.label || obj.name),
+        description: String(obj.description || ''),
+        source,
+        file: path.join(dir, f),
+        ...(obj.systemPrompt ? { systemPrompt: obj.systemPrompt } : {}),
+        ...(Array.isArray(obj.tools) ? { tools: obj.tools } : {}),
+        ...(obj.permission ? { permission: String(obj.permission) } : {}),
+        ...(obj.model ? { model: String(obj.model) } : {}),
+      });
+    } catch {
+      // JSON 解析失败：跳过
+    }
+  }
+  return out;
+}
+
+/**
+ * 按名解析单个预设（含全部字段），找不到返回 null。
+ * @param {any} workingDir @param {any} name
+ */
+export function loadPreset(/** @type {any} */ workingDir, /** @type {any} */ name) {
+  const all = listPresets(workingDir);
+  const hit = all.find((/** @type {any} */ p) => p.name === name || path.basename(String(p.file), '.json') === name);
+  if (!hit) return null;
+  try {
+    return JSON.parse(fs.readFileSync(hit.file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 预设 → cfg 覆盖：只返回预设声明的参数键（其余键保持调用方当前配置）。
+ * tools 单独走 cfg.presetTools（白名单在 agent 的 toolsFor 处生效）。
+ */
+export function presetConfigOverrides(/** @type {any} */ preset) {
+  const out = /** @type {Record<string, any>} */ ({});
+  for (const k of ['permission', 'model', 'temperature', 'maxOutputTokens', 'maxRounds', 'contextBudget']) {
+    if (preset && preset[k] !== undefined) out[k] = preset[k];
+  }
+  if (preset && Array.isArray(preset.tools)) out.presetTools = [...preset.tools];
+  return out;
+}
+
+/** 预设系统提示定制段（无则空串），插入系统提示 BASE 之后。 */
+export function presetSystemBlock(/** @type {any} */ preset) {
+  const s = preset && typeof preset.systemPrompt === 'string' ? preset.systemPrompt.trim() : '';
+  if (!s) return '';
+  return `\n\n<preset_rules>\n${s}\n</preset_rules>`;
+}

package/src/prompts.js

@@ -30,8 +30,8 @@ function loadFile(/** @type {any} */ p, /** @type {any} */ cap) {
   }
 }
 
-/** @param {{ workingDir: any, withJournal?: boolean, projectMemory?: string, [key: string]: any }} opts */
-export function buildSystemPrompt({ workingDir, withJournal = false, projectMemory }) {
+/** @param {{ workingDir: any, withJournal?: boolean, projectMemory?: string, presetBlock?: string, [key: string]: any }} opts */
+export function buildSystemPrompt({ workingDir, withJournal = false, projectMemory, presetBlock }) {
   // 前缀字节稳定性（评估 P1-1/P1-2，四份评估一致的最高价值项）：
   // 系统提示不含「当前模型」「当前日期」等易变字段——DeepSeek 上下文缓存按前缀字节匹配，
   // 路由 pro⇄flash 翻转或跨天会改变前缀 → 整段历史按未命中价重计（命中价的 30 倍）。
@@ -40,6 +40,9 @@ export function buildSystemPrompt({ workingDir, withJournal = false, projectMemo
 
 当前工作目录：${workingDir}`;
 
+  // v0.4.0 Agent Preset：预设定制的角色/规则段（会话内恒定，前缀稳定）
+  if (presetBlock) prompt += presetBlock;
+
   // 用户级记忆（~/.mingdao/AGENTS.md，/memory add 手动追加 + 会话结束自动提炼）
   const memory = loadFile(path.join(mingdaoHome(), 'AGENTS.md'), 8000);
   if (memory) prompt += `\n\n<user_memory>\n${memory}\n</user_memory>`;

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/tasks/worker.js

@@ -53,6 +53,9 @@ export async function runWorkerTask(id, question, { permission, model, offpeak }
     }
     const provider = await createProvider(cfg, modelName);
     const io = createIO({ quiet: true });
+    // v0.4.0 契约化：后台任务同样挂载 config.tools 声明式工具（幂等）
+    const { mountConfigTools } = await import('../tools/index.js');
+    mountConfigTools(cfg);
     const permissionObj = createPermission(perm, io);
     /** @type {any} */
     let mcpManager = null;