mingdao-harness 0.3.2 → 0.4.1

package/src/batch.js

@@ -13,7 +13,6 @@ import { resolveProviderConfig } from './providers/index.js';
 import { estimateBatchCost, BATCH_DISCOUNT } from './pricing.js';
 import { recordCacheStats } from './cachestats.js';
 import { approxTokens } from './context.js';
-import { modelPreset } from './models.js';
 
 const DEFAULT_WINDOW = '24h';
 const DEFAULT_ENDPOINT = '/v1/chat/completions';
@@ -120,8 +119,10 @@ export async function runBatch({ cfg, model, questions, workingDir = process.cwd
   if (deduped > 0) onStatus?.(`去重：${deduped} 条重复问题合并（${list.length} → ${unique.length} 条实际提交）`);
 
   // —— 省钱 B2：单问超窗口预检（估算输入 + max_tokens 超过模型窗口 95% 即报错，绝不提交烧钱）——
-  const preset = modelPreset(model) || {};
-  const windowTokens = Number(preset.budgetTokens) || 128000;
+  // v0.4.1 P1 修复：接入 resolveModelCaps 取真实 contextWindow（此前用 preset.budgetTokens 当窗口，
+  // 本地小模型 32k 窗口会套 128000 默认 → 超窗口预检完全失效，提交后烧钱且失败）。
+  const { resolveModelCaps } = await import('./model-caps.js');
+  const windowTokens = resolveModelCaps(cfg, model).contextWindow;
   const sysTokens = approxTokens(systemPrompt);
   for (let i = 0; i < unique.length; i++) {
     const est = sysTokens + approxTokens(unique[i]);

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,37 @@ 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, presetPermissionOverride, 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 };
+      // P0（v0.4.1）：预设 permission 提权防护——预设不得把 ask/readonly 静默改成 auto
+      const permOv = presetPermissionOverride(activePreset, cfg.permission ?? 'ask');
+      if (permOv.escalated) {
+        delete presetOverlay.permission;
+        io.print(style(`⚠ 预设 "${activePreset.name}" 声明 permission=${activePreset.permission} 属提权（当前 ${cfg.permission ?? 'ask'}），已忽略并保持 ${permOv.permission}。`, C.yellow));
+      } else if (activePreset.permission !== undefined) {
+        presetOverlay.permission = permOv.permission;
+      }
+      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 +401,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 +449,7 @@ async function main() {
     io,
     modelName,
     workingDir,
-    cfg,
+    cfg: agentCfg,
     undoStore: sessionUndoStore,
     mcp: mcpFacade,
     sessionRef,
@@ -440,7 +479,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 +490,7 @@ async function main() {
       io: turnIo,
       modelName,
       workingDir,
-      cfg,
+      cfg: agentCfg,
       undoStore: sessionUndoStore,
       mcp: mcpFacade,
       sessionRef: oneShotRef,
@@ -528,7 +567,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/diagnose.js

@@ -52,6 +52,21 @@ export async function handleDiagnose(/** @type {any} */ _cmd, /** @type {any} */
     const cfg = loadConfig();
     push(cfg ? redactSensitive(JSON.stringify(cfg, null, 2)) : '（不存在或读取失败）');
 
+    // v0.4.1：模型能力定位——本地模型未声明 contextWindow 会兜底 32k → maxOutput/budget 偏小，
+    // 表现为「输出截断/频繁压缩」。此处显式提示，帮用户自诊。
+    if (cfg?.model) {
+      push('');
+      push('## 当前模型能力');
+      try {
+        const { resolveModelCaps, safeBudget } = await import('../model-caps.js');
+        const caps = resolveModelCaps(cfg, cfg.model);
+        push(`- 模型：${cfg.model}（${caps.isLocal ? '本地部署' : '远程'}）`);
+        push(`- 上下文窗口：${caps.contextWindow}${caps.isLocal && !((cfg.customModels || {})[cfg.model]?.contextWindow) ? '（未在 customModels 声明 contextWindow，按本地兜底 32k——建议声明真实窗口，如 131072，否则输出/预算被压缩）' : ''}`);
+        push(`- 最大输出：${caps.maxOutputTokens} · 预算：${safeBudget(cfg, caps)}`);
+        push(`- 自动路由：${cfg.routing?.enabled ? '开（planner=' + cfg.routing.planner + ' executor=' + cfg.routing.executor + '）' : '关'}`);
+      } catch {}
+    }
+
     push('');
     push('## 凭证库');
     push(`${redactSensitive(credentialsPath())}：${fs.existsSync(credentialsPath()) ? '已存在（内容不打包）' : '无'}`);

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,46 @@ 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, presetPermissionOverride } = 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。
+        // P0（v0.4.1）：预设 permission 提权防护——不得把 ask/readonly 静默改成 auto
+        const permOv = presetPermissionOverride(p, cfg.permission ?? 'ask');
+        if (permOv.escalated) {
+          delete over.permission;
+          io.print(style(`⚠ 预设 "${p.name}" 声明 permission=${p.permission} 属提权（当前 ${cfg.permission ?? 'ask'}），已忽略并保持 ${permOv.permission}。`, C.yellow));
+        } else if (p.permission !== undefined) {
+          over.permission = permOv.permission;
+        }
+        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 +381,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/context.js

@@ -88,9 +88,9 @@ export function trimMessages(/** @type {any} */ messages, /** @type {any} */ bud
       if (total <= budget) break;
       const m = out[i];
       const c = typeof m.content === 'string' ? m.content : JSON.stringify(m?.content ?? '');
-      // 幂等守卫（A4）：已回收过的内容跳过——否则「截断标记」把长度再次顶过阈值，逐轮嵌套重截，
-      // 被保留消息字节逐轮漂移（前缀缓存连尾部都失配）
-      if (c.includes('已回收')) continue;
+      // 注：无幂等守卫——回收结果只写在投影副本 out 上、从不回写原 messages（trimMessages 是投影，
+      // 每次调用从原 messages 重新拷贝），故「已回收」标记不会进入下一次调用的输入，无需守卫。
+      // 截断逻辑确定（同输入同输出），字节稳定，不会逐轮嵌套重截（审计 v0.4.1 确认的死代码已移除）。
       let next = null;
       if (m.role === 'tool' && c.length > 40) {
         next = { ...m, content: `[工具 ${m.tool_call_id || ''} 结果摘要：${c.slice(0, 40).replace(/\n/g, ' ')}…（已回收，原 ${c.length} 字）]` };

package/src/cost-guard.js

@@ -17,6 +17,9 @@ export function costGuardConfig() {
 // 质检 M10：按 cache-stats 文件 mtime 缓存统计结果——文件未变直接复用，
 // 避免 Agent 每步对整文件（可能数千行）重复解析与累加。
 let todayCache = { mtime: -1, size: -1, start: 0, sum: 0 };
+// v0.4.1 P2 修复（TDZ）：todayCostWarned 提到 todayCost 使用点之前声明——
+// 此前在第 44 行才 let 声明、第 36 行已使用（模块加载顺序碰巧掩盖了风险，循环依赖场景会抛 ReferenceError）。
+let todayCostWarned = false;
 export function todayCost() {
   const start = beijingDayStart().getTime();
   try {
@@ -40,7 +43,6 @@ export function todayCost() {
     return null;
   }
 }
-let todayCostWarned = false;
 
 export function costGuardStatus() {
   const g = costGuardConfig();

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

@@ -25,11 +25,12 @@ const HANDSHAKE_TIMEOUT_MS = 20000;
 let nextId = 1;
 
 export class McpClient {
-  constructor(/** @type {any} */ name, /** @type {any} */ { command, args = [], env = {} }, /** @type {any} */ workingDir) {
+  constructor(/** @type {any} */ name, /** @type {any} */ { command, args = [], env = {}, trusted = false }, /** @type {any} */ workingDir) {
     this.name = name;
     this.command = command;
     this.args = args;
     this.env = env;
+    this.trusted = trusted === true; // v0.4.1 P0：仅 trusted 服务器的 readOnlyHint 才被信任自动放行
     this.workingDir = workingDir;
     this.tools = /** @type {any[]} */ ([]);
     this.child = null;
@@ -262,7 +263,11 @@ export async function startMcpServers(/** @type {any} */ mcpCfg, /** @type {any}
     },
     isReadonly(/** @type {any} */ prefixedName) {
       const found = this.lookup(prefixedName);
-      return found ? found.client.isReadonly(found.toolName) : false;
+      if (!found) return false;
+      // v0.4.1 P0：未授信服务器（未设 mcpServers.<name>.trusted）即使工具标注 readOnlyHint 也不自动放行——
+      // 服务器可谎称只读绕过权限确认；只有显式 trusted 才信任其标注。
+      if (!found.client.trusted) return false;
+      return found.client.isReadonly(found.toolName);
     },
     status() {
       const rows = [];

package/src/memory.js

@@ -255,7 +255,11 @@ export function retrieveRelevant(/** @type {any[]} */ entries, /** @type {any} *
     return { e, score: overlap / union };
   });
   scored.sort((/** @type {any} */ a, /** @type {any} */ b) => b.score - a.score);
-  return scored.filter((/** @type {any} */ s) => s.score > 0).slice(0, topN).map((/** @type {any} */ s) => s.e);
+  const hits = scored.filter((/** @type {any} */ s) => s.score > 0).slice(0, topN).map((/** @type {any} */ s) => s.e);
+  // v0.4.1 P1 修复：无匹配时回退最近 N 条（entries 按「旧→新」追加，尾部即最新）——此前 filter(score>0)
+  // 在 query 与记忆无共同词时返回空数组，项目记忆完全消失（相关性判断失败 ≠ 记忆不存在）。
+  if (hits.length) return hits;
+  return entries.slice(-topN);
 }
 
 export function appendProjectMemory(/** @type {any} */ workingDir, /** @type {any} */ lines) {

package/src/permissions.js

@@ -31,8 +31,10 @@ function ruleMatches(rule, name, args) {
     if (ruleName !== name) return false;
     const want = rule.slice(idx + 1).trim();
     const have = summarize(name, args).trim();
-    // bash 前缀规则防链式命令绕过：含 && / ; / | / ` / $( 的复合命令不匹配前缀规则，回落权限确认
-    if (name === 'bash' && /&&|\|\||[;|`]|\$\(|\n/.test(have)) return false;
+    // bash 前缀规则防链式命令绕过（P0 安全，v0.4.1）：白名单字符法——前缀规则仅匹配
+    // 单条简单命令（字母数字/空格/下划线/./-/），任何 shell 元字符（&&/||/;|&<>`$()\n\r）都不匹配，
+    // 回落权限确认。黑名单枚举永远追不上绕过手法（单 & 后台串联、重定向、\r 等），白名单才可靠。
+    if (name === 'bash' && !/^[A-Za-z0-9_ ./\\:-]+$/.test(have)) return false;
     if (want.endsWith('*')) return have.startsWith(want.slice(0, -1));
     return have === want;
   }

package/src/presets.js

@@ -0,0 +1,175 @@
+// 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 处生效）。
+ * 注意：permission 提权由调用方用 presetPermissionOverride 过滤（防项目级预设提权，见下）。
+ */
+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;
+}
+
+// 权限宽松度排序（数值越大越宽松/越危险）。
+const PERM_RANK = /** @type {Record<string, number>} */ ({ readonly: 0, ask: 1, auto: 2 });
+
+/**
+ * 预设 permission 提权防护（P0 安全，v0.4.1）：预设声明的 permission 不得比当前配置更宽松
+ * （如当前 ask → 预设 auto 属提权，忽略并返回当前值）。clone 恶意仓库含 .mingdao/presets/*.json
+ * 声明 auto 时，不能静默跳过用户全部确认。返回 { permission, escalated }：escalated=true 表示已拦截提权。
+ * @param {any} preset @param {string} currentPermission
+ */
+export function presetPermissionOverride(/** @type {any} */ preset, /** @type {any} */ currentPermission) {
+  const want = preset && preset.permission !== undefined ? String(preset.permission) : null;
+  if (!want || !(want in PERM_RANK)) return { permission: currentPermission, escalated: false };
+  const cur = currentPermission in PERM_RANK ? currentPermission : 'ask';
+  if (PERM_RANK[want] > PERM_RANK[cur]) {
+    // 提权：忽略预设值，保持当前更保守的权限
+    return { permission: cur, escalated: true };
+  }
+  return { permission: want, escalated: false };
+}
+
+/** 预设系统提示定制段（无则空串），插入系统提示 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/routing.js

@@ -139,9 +139,13 @@ export async function routeTask(/** @type {any} */ { cfg, provider, currentModel
   return rc.executor === currentModel ? { model: currentModel, reason: null } : { model: rc.executor, reason: '回退执行模型' };
 }
 
-// 子代理模型选择：路由开启时固定 executor
+// 子代理模型选择：路由开启时固定 executor——但当前模型不在路由池（如本地/自定义模型）时
+// 必须跟随当前模型，否则子代理会把 executor 模型名（deepseek-v4-flash）发到当前模型的 baseUrl
+// （本地 8081），服务端不认识 → 400 → 子代理全灭，表现为主线程「子代理无反馈」。
 export function subagentModel(/** @type {any} */ cfg, /** @type {any} */ currentModel) {
   const rc = routingConfig(cfg);
   if (!rc) return currentModel;
+  // v0.4.1 修复：与 routeTask 的池外检查一致——当前模型不在 planner/executor 池内时不干预
+  if (currentModel !== rc.planner && currentModel !== rc.executor) return currentModel;
   return modelPreset(rc.executor) ? rc.executor : currentModel;
 }

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;

package/src/tools/bash.js

@@ -34,8 +34,16 @@ export function detectSandbox() {
   sandboxSupport = 'none';
   if (process.platform === 'linux') {
     try {
-      const r = spawnSync('bwrap', ['--version'], { stdio: 'ignore', timeout: 3000 });
-      sandboxSupport = r.error ? 'none' : 'bwrap';
+      // v0.4.1 P1 修复：实际能力探测而非仅 --version——bwrap 存在但 /proc 挂载受限（Docker/devcontainer/
+      // CI 流水线等容器环境）时 --version 能跑、真正建沙箱却失败。用最小真实沙箱命令验证：
+      // --ro-bind / / --tmpfs /tmp true 能成功退出 0 才算可用，否则降级 none（runBash 会注明降级）。
+      const v = spawnSync('bwrap', ['--version'], { stdio: 'ignore', timeout: 3000 });
+      if (v.error) {
+        sandboxSupport = 'none';
+      } else {
+        const probe = spawnSync('bwrap', ['--die-with-parent', '--ro-bind', '/', '/', '--dev', '/dev', '--proc', '/proc', '--tmpfs', '/tmp', 'true'], { stdio: 'ignore', timeout: 5000 });
+        sandboxSupport = probe.error || probe.status !== 0 ? 'none' : 'bwrap';
+      }
     } catch {
       sandboxSupport = 'none';
     }