mingdao-harness 0.3.2 → 0.4.1

package/src/tools/fetch.js

@@ -9,7 +9,7 @@ function isPrivateHost(/** @type {string} */ hostname) {
   if (h === 'localhost' || h.endsWith('.localhost') || h === '::1') return true;
   if (h.includes(':')) {
     if (/^::ffff:/.test(h)) return isPrivateHost(h.slice(7));
-    return /^fe[89ab]/.test(h) || /^f[c d]/.test(h) || h === '::' || h === '::1';
+    return /^fe[89ab]/.test(h) || /^f[cd]/.test(h) || h === '::' || h === '::1';
   }
   const m = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
   if (!m) return false;
@@ -39,10 +39,42 @@ export async function runFetch(/** @type {any} */ args, /** @type {any} */ _ctx)
     }
   }
   if (blocked) return { ok: false, error: `拒绝访问内网/本机地址（${host}）——SSRF 防护。` };
+  // 302 重定向复检（P0 安全，v0.4.1）：redirect:'follow' 只检查初始 URL，攻击者可用公网 302 跳回内网。
+  // 改 redirect:'manual' 手动跟随，每一跳重新 isPrivateHost + DNS 复检，跳数上限 5。
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), 15000);
   try {
-    const res = await fetch(u, { signal: ac.signal, redirect: 'follow' });
+    let cur = u;
+    let res = /** @type {any} */ (null);
+    for (let hop = 0; hop <= 5; hop++) {
+      if (hop > 5) return { ok: false, error: '重定向次数超过上限（5 跳）。' };
+      const ch = String(cur.hostname || '').toLowerCase();
+      let hopBlocked = isPrivateHost(ch);
+      if (!hopBlocked && ch && ch !== 'localhost' && !/^\d{1,3}(\.\d{1,3}){3}$/.test(ch)) {
+        try {
+          const addrs = await lookup(ch, { all: true, verbatim: true });
+          hopBlocked = addrs.some((/** @type {any} */ a) => isPrivateHost(a.address));
+        } catch {
+          // DNS 解析失败：放行，连接阶段会报错
+        }
+      }
+      if (hopBlocked) return { ok: false, error: `拒绝访问内网/本机地址（${ch}）——SSRF 重定向防护。` };
+      res = await fetch(cur, { signal: ac.signal, redirect: 'manual' });
+      if (res.status >= 300 && res.status < 400) {
+        const loc = res.headers.get('location');
+        if (!loc) break; // 无 Location：按最终响应处理
+        try {
+          cur = new URL(loc, cur);
+        } catch {
+          return { ok: false, error: `非法重定向地址：${loc}` };
+        }
+        if (cur.protocol !== 'http:' && cur.protocol !== 'https:') {
+          return { ok: false, error: '重定向到非 http(s) 地址，已拒绝。' };
+        }
+        continue;
+      }
+      break;
+    }
     const buf = await res.arrayBuffer();
     clearTimeout(timer);
     if (buf.byteLength > 512 * 1024) return { ok: false, error: `响应超过 512KB 上限（实际 ${buf.byteLength} 字节）。` };

package/src/tools/fs-tools.js

@@ -19,6 +19,53 @@ function resolvePath(cwd, p) {
   return path.resolve(cwd, p);
 }
 
+// —— 路径穿越防护（P0 安全，v0.4.1）——
+// 文件工具限定在「工作目录 + config.fsAllowDirs 白名单」内；realpath 逐级校验防软链接逃逸。
+// auto 模式下模型（或被提示注入诱导）也无法 read ~/.ssh、~/.mingdao/credentials.json 等越界文件。
+// 白名单：config.json 的 fsAllowDirs 数组（绝对目录），需要访问工作目录外时显式添加。
+function normCmp(/** @type {any} */ p) {
+  return process.platform === 'win32' ? String(p).toLowerCase() : String(p);
+}
+function realPathOrNull(/** @type {any} */ p) {
+  try {
+    return normCmp(fs.realpathSync(p));
+  } catch {
+    return null;
+  }
+}
+// 判断 target 是否在 root 内：对 target 逐级向上找最近的已存在祖先 realpath，再与 root realpath 比较。
+// （write 新文件时父目录可能尚不存在，逐级向上即可正确处理；软链接已被 realpath 展开。）
+function withinRoot(/** @type {any} */ root, /** @type {any} */ target) {
+  const rr = realPathOrNull(root);
+  if (!rr) return false;
+  let cur = target;
+  for (let i = 0; i < 64; i++) {
+    const rp = realPathOrNull(cur);
+    if (rp) return rp === rr || rp.startsWith(rr + path.sep);
+    const parent = path.dirname(cur);
+    if (parent === cur) return false;
+    cur = parent;
+  }
+  return false;
+}
+/**
+ * 解析路径并做工作目录边界检查。
+ * @param {any} ctx
+ * @param {any} p
+ * @returns {{ ok: true, path: string } | { ok: false, error: string }}
+ */
+function boundedPath(/** @type {any} */ ctx, /** @type {any} */ p) {
+  const cwd = ctx?.cwd || ctx?.workingDir || process.cwd();
+  const raw = resolvePath(cwd, p ?? '');
+  if (!raw) return { ok: false, error: '缺少 path 参数。' };
+  const allowDirs = Array.isArray(ctx?.cfg?.fsAllowDirs) ? ctx.cfg.fsAllowDirs : [];
+  const roots = [cwd, ...allowDirs.map((/** @type {any} */ d) => path.resolve(String(d)))];
+  for (const r of roots) {
+    if (withinRoot(r, raw)) return { ok: true, path: raw };
+  }
+  return { ok: false, error: `路径越界（工作目录外）：${raw}。如需访问请将目录加入 config.fsAllowDirs 白名单。` };
+}
+
 /**
  * @param {any} buf
  */
@@ -76,7 +123,7 @@ function backup(ctx, p) {
 export function undo(args, ctx) {
   const store = ctx?.undoStore?.backups;
   if (!(store instanceof Map) || !store.size) return { ok: false, error: '没有可撤销的修改。' };
-  const p = args.path ? resolvePath(ctx.cwd, args.path) : null;
+  const p = args.path ? (() => { const bb = boundedPath(ctx, args.path); return bb.ok ? bb.path : null; })() : null;
   if (p) {
     const list = store.get(p);
     if (!list?.length) return { ok: false, error: `${p} 没有可撤销的修改记录。` };
@@ -124,8 +171,9 @@ export function invalidateReadCache(p) {
  */
 export function read(args, ctx) {
   try {
-    const p = resolvePath(ctx.cwd, args.path ?? '');
-    if (!p) return { ok: false, error: '缺少 path 参数。' };
+    const b = boundedPath(ctx, args.path ?? '');
+    if (!b.ok) return b;
+    const p = b.path;
     const st = fs.statSync(p);
     if (st.isDirectory()) return { ok: false, error: `"${p}" 是目录，请使用 ls 查看。` };
     if (st.size > MAX_FILE_BYTES) {
@@ -181,8 +229,9 @@ const MAX_WRITE_BYTES = 2 * 1024 * 1024; // write 单次内容上限（防模型
  */
 export function write(args, ctx) {
   try {
-    const p = resolvePath(ctx.cwd, args.path ?? '');
-    if (!p) return { ok: false, error: '缺少 path 参数。' };
+    const b = boundedPath(ctx, args.path ?? '');
+    if (!b.ok) return b;
+    const p = b.path;
     const content = String(args.content ?? '');
     if (Buffer.byteLength(content) > MAX_WRITE_BYTES) {
       return { ok: false, error: `内容超过 ${MAX_WRITE_BYTES / 1024 / 1024}MB 上限，请分多次写入。` };
@@ -222,11 +271,12 @@ function regionAround(text, lineStart, lineCount, context = 2) {
  */
 export function edit(args, ctx) {
   try {
-    const p = resolvePath(ctx.cwd, args.path ?? '');
+    const b = boundedPath(ctx, args.path ?? '');
+    if (!b.ok) return b;
+    const p = b.path;
     const oldString = String(args.old_string ?? '');
     const newString = String(args.new_string ?? '');
     const replaceAll = Boolean(args.replace_all);
-    if (!p) return { ok: false, error: '缺少 path 参数。' };
     if (!oldString) return { ok: false, error: '缺少 old_string 参数。' };
     try {
       if (fs.statSync(p).size > MAX_FILE_BYTES) {
@@ -265,7 +315,9 @@ export function edit(args, ctx) {
  */
 export function ls(args, ctx) {
   try {
-    const p = resolvePath(ctx.cwd, args.path || '.');
+    const b = boundedPath(ctx, args.path || '.');
+    if (!b.ok) return b;
+    const p = b.path;
     const entries = fs.readdirSync(p, { withFileTypes: true });
     const rows = entries
       .map((e) => {
@@ -354,7 +406,9 @@ function walkFiles(root, visitor) {
 export function glob(args, ctx) {
   try {
     const pattern = String(args.pattern ?? '*');
-    const root = resolvePath(ctx.cwd, args.path || '.');
+    const b = boundedPath(ctx, args.path || '.');
+    if (!b.ok) return b;
+    const root = b.path;
     if (!fs.existsSync(root)) return { ok: false, error: `目录不存在：${root}` };
     const re = globToRegExp(pattern);
     const matchRel = pattern.includes('/');
@@ -401,7 +455,9 @@ export function grep(args, ctx) {
     const MAX_LINE = 20 * 1024;
     /** @type {(line: any) => any} */
     const testLine = (line) => (line.length > MAX_LINE ? re.test(line.slice(0, MAX_LINE)) : re.test(line));
-    const root = resolvePath(ctx.cwd, args.path || '.');
+    const root0 = boundedPath(ctx, args.path || '.');
+    if (!root0.ok) return root0;
+    const root = root0.path;
     const include = args.include ? globToRegExp(String(args.include)) : null;
     /** @type {any[]} */
     const matches = [];

package/src/tools/git.js

@@ -14,10 +14,18 @@ export async function runGit(/** @type {any} */ args, /** @type {any} */ ctx) {
   if (!GIT_READONLY.has(sub)) {
     return { ok: false, error: `git ${sub} 不是只读子命令（仅支持 ${[...GIT_READONLY].join(' / ')}）。写操作请用 bash 并注意授权。` };
   }
-  // 追加默认防超大输出：log/diff 限量（除非模型显式给了 -n/--max-count）
+  // 追加默认防超大输出：log/diff 限量（除非模型显式给了 -n/--max-count）——
+  // v0.4.1 P2 修复：此前注释声明限量但无实现，git log -p 在大型仓库会撞 maxBuffer 4MB 报 ENOBUFS。
+  let effectiveArgv = argv;
+  if ((sub === 'log' || sub === 'shortlog') && !argv.some((/** @type {string} */ a) => /^-(n|\d+)$/.test(a) || a === '--max-count')) {
+    effectiveArgv = [...argv, '-n', '50'];
+  } else if (sub === 'diff' && !argv.some((/** @type {string} */ a) => a === '--stat')) {
+    // diff 全量可能极巨：默认 --stat 概览，模型需要全文再显式加 --no-stat 或指定文件
+    effectiveArgv = [...argv, '--stat'];
+  }
   const cwd = ctx.workingDir || process.cwd();
   try {
-    const { stdout, stderr } = await execFile('git', argv, {
+    const { stdout, stderr } = await execFile('git', effectiveArgv, {
       cwd,
       timeout: 15000,
       maxBuffer: 4 * 1024 * 1024,

package/src/tools/index.js

@@ -6,6 +6,7 @@ import { runBash } from './bash.js';
 import { runGit } from './git.js';
 import { runFetch } from './fetch.js';
 import { listSkills, loadSkill } from '../skills.js';
+import { spawn } from 'node:child_process';
 
 // 只读工具集合的单一来源：permissions.js 引用此导出，新增只读工具时只需改这里
 export const READONLY_TOOLS = new Set(['read', 'glob', 'grep', 'ls', 'skill', 'git', 'fetch']);
@@ -245,6 +246,140 @@ export function toolSchemas() {
   return TOOLS;
 }
 
+// —— 第三方工具注册表（v0.4.0 契约化）：程序化 registerTool 注册的自定义工具 ——
+// 与内置工具同一链路：schema 进 buildToolSchemas（省钱剥描述/只读档/预设白名单全适用）、
+// dispatch 执行、审计/权限由 agent 外层统一处理。注册名不得与内置工具同名。
+const customTools = new Map(); // name -> { schema, run }
+const CUSTOM_TOOL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+
+/**
+ * 注册第三方工具（进程级，重复注册同名会报错——避免静默覆盖）。
+ * readOnly（v0.4.1 P2 新增）：标注后进 READONLY_TOOLS 集合——只读档自动放行、ask 档不询问、
+ * 只读子代理可用。默认 false（写类/副作用工具仍走权限询问）。
+ * @param {{ name: string, description?: string, parameters?: any, readOnly?: boolean, run: (args: any, ctx: any) => any | Promise<any> }} tool
+ */
+export function registerTool(/** @type {any} */ tool) {
+  const name = String(tool?.name ?? '').trim();
+  if (!CUSTOM_TOOL_NAME_RE.test(name)) {
+    throw new Error(`自定义工具名非法（${CUSTOM_TOOL_NAME_RE}）：${name}`);
+  }
+  // mcp__ 前缀保留给 MCP 工具（agent 按前缀路由到 mcp.call），自定义工具占用会静默错路由
+  if (name.startsWith('mcp__')) {
+    throw new Error(`自定义工具名不能以 mcp__ 开头（该前缀保留给 MCP 工具）：${name}`);
+  }
+  if (TOOLS.some((/** @type {any} */ t) => t.function.name === name) || customTools.has(name)) {
+    throw new Error(`工具 ${name} 已存在（内置或已注册），不能重复注册`);
+  }
+  if (typeof tool?.run !== 'function') {
+    throw new Error(`自定义工具 ${name} 必须提供 run(args, ctx) 函数`);
+  }
+  const parameters =
+    tool.parameters && typeof tool.parameters === 'object' ? tool.parameters : { type: 'object', properties: {} };
+  const entry = {
+    schema: {
+      type: 'function',
+      function: { name, description: String(tool.description || ''), parameters },
+    },
+    run: tool.run,
+    readOnly: tool.readOnly === true,
+  };
+  customTools.set(name, entry);
+  if (tool.readOnly === true) READONLY_TOOLS.add(name);
+  return entry.schema;
+}
+
+/** 判断第三方工具是否标注只读。 */
+export function isRegisteredToolReadonly(/** @type {any} */ name) {
+  return customTools.get(name)?.readOnly === true;
+}
+
+/** 已注册的第三方工具名列表。 */
+export function listRegisteredTools() {
+  return [...customTools.keys()];
+}
+
+/** 第三方工具 schema 列表（与内置 TOOLS 合并进 buildToolSchemas）。 */
+function customToolSchemas() {
+  return [...customTools.values()].map((/** @type {any} */ t) => t.schema);
+}
+
+// —— config.tools 声明式工具挂载（v0.4.0 契约化）——
+// config.json: { "tools": [ { "name": "ping", "description": "...", "parameters": {...}, "command": "..." } ] }
+// command 经 /bin/bash -lc 执行；参数以 MINGDAO_TOOL_ARGS（JSON）环境变量传入——参数不经字符串拼接进
+// shell（防注入），由命令自行解析；执行受 agent 权限引擎门控（与 bash 同权重，权限提示含参数）。
+// 进程级挂载（幂等：同名已挂载则跳过），改 config.tools 需重启生效（与 MCP 预设一致）。
+const mountedConfigTools = new Set();
+
+/**
+ * 把 config.tools 声明式工具挂载进注册表（幂等，可在启动路径重复调用）。
+ * 返回本次新挂载的工具名数组。非法条目（坏名/与内置冲突）跳过不挂载——
+ * 用户配置错误绝不能让 CLI/WebUI 启动崩溃，用 console.error 提示即可。
+ */
+export function mountConfigTools(/** @type {any} */ cfg) {
+  const entries = Array.isArray(cfg?.tools) ? cfg.tools : [];
+  const mounted = [];
+  for (const e of entries) {
+    const name = String(e?.name ?? '').trim();
+    if (!name || mountedConfigTools.has(name)) continue;
+    if (typeof e?.command !== 'string' || !e.command.trim()) continue; // 缺 command 的条目跳过
+    try {
+      registerTool({
+        name,
+        description: String(e.description || ''),
+        parameters: e.parameters,
+        // v0.4.1 P1 修复：异步 spawn 而非 spawnSync——spawnSync 最长阻塞 600s，WebUI 下单个请求
+        // 即冻结整个 Node 进程（所有并发会话/权限确认/SSE 流全无响应）。异步执行不阻塞事件循环。
+        run: (/** @type {any} */ args, /** @type {any} */ ctx) =>
+          new Promise((resolve) => {
+            const shell = process.platform === 'win32' ? 'cmd.exe' : '/bin/bash';
+            const shellArgs = process.platform === 'win32' ? ['/d', '/s', '/c', e.command] : ['-lc', e.command];
+            const timeoutMs = Math.min(Number(e.timeout) > 0 ? Number(e.timeout) : 120, 600) * 1000;
+            const child = spawn(shell, shellArgs, {
+              cwd: ctx.cwd,
+              env: { ...process.env, MINGDAO_TOOL_ARGS: JSON.stringify(args ?? {}) },
+            });
+            let out = '';
+            let err = '';
+            let done = false;
+            let timedOut = false;
+            const cap = (/** @type {any} */ s, /** @type {any} */ d) => {
+              const t = s + d;
+              return t.length > 20000 * 2 ? t.slice(-20000 * 2) : t;
+            };
+            const finish = (/** @type {any} */ result) => {
+              if (done) return;
+              done = true;
+              clearTimeout(timer);
+              resolve(result);
+            };
+            const timer = setTimeout(() => {
+              timedOut = true;
+              try { child.kill('SIGKILL'); } catch {}
+            }, timeoutMs);
+            child.stdout.on('data', (d) => { out = cap(out, d); });
+            child.stderr.on('data', (d) => { err = cap(err, d); });
+            child.on('error', (er) => finish({ ok: false, error: `命令执行失败：${String(er?.message || er)}` }));
+            child.on('close', (code) => {
+              const capped = out.length > 20000 ? out.slice(0, 20000) + `\n…[输出过长已截断，共 ${out.length} 字]` : out;
+              finish({
+                ok: timedOut ? false : (code ?? 0) === 0,
+                exitCode: timedOut ? null : (code ?? null),
+                output: (capped || '（无输出）').trim(),
+                ...(err.trim() ? { stderr: err.trim().slice(0, 4000) } : {}),
+                ...(timedOut ? { error: `命令执行超时（${Math.round(timeoutMs / 1000)}s），已终止` } : {}),
+              });
+            });
+          }),
+      });
+      mountedConfigTools.add(name);
+      mounted.push(name);
+    } catch (/** @type {any} */ err) {
+      console.error(`[MingDao] ⚠ config.tools 条目 "${name}" 挂载失败（已跳过）：${String(err?.message || err)}`);
+    }
+  }
+  return mounted;
+}
+
 /**
  * 递归去除对象中的全部 description 键（保留类型/required/enum 等结构性字段）。
  * @param {any} obj
@@ -283,7 +418,7 @@ export function buildToolSchemas(usedNames, extra = []) {
       }
       return t;
     });
-  return [...strip(TOOLS), ...strip(extra)];
+  return [...strip(TOOLS), ...strip(customToolSchemas()), ...strip(extra)];
 }
 
 function runSkill(/** @type {any} */ args, /** @type {any} */ ctx) {
@@ -333,6 +468,15 @@ function runTodo(/** @type {any} */ args, /** @type {any} */ ctx) {
 }
 
 export async function dispatch(/** @type {any} */ name, /** @type {any} */ args, /** @type {any} */ ctx) {
+  const custom = customTools.get(name);
+  if (custom) {
+    try {
+      const r = await custom.run(args, ctx);
+      return r && typeof r === 'object' ? r : { ok: true, output: String(r ?? '') };
+    } catch (/** @type {any} */ err) {
+      return { ok: false, error: `自定义工具 ${name} 执行失败：${String(err?.message || err)}` };
+    }
+  }
   switch (name) {
     case 'read':
       return read(args, ctx);

package/src/web/app.js

@@ -345,6 +345,9 @@ async function send(){
   arm();
   input.value=''; input.style.height='44px';
   const payload={message:text,file:currentSession};
+  // v0.4.0 Agent Preset：选择器选中的预设随本轮发送（服务端按会话应用一次）
+  const presetVal=$('#presetSel')?.value;
+  if(presetVal) payload.preset=presetVal;
   // 带上文开关：勾选后系统提示注入最近会话日志（默认不注入——新会话全新开始，避免串到历史会话上下文）
   if($('#journalChk')?.checked) payload.withJournal=true;
   if(attachments.length) payload.attachments=attachments;
@@ -647,6 +650,11 @@ async function init(){
   }
   refreshSessions();
   refreshWsSel();
+  try{
+    // v0.4.0 Agent Preset：加载预设列表进下拉（项目 → 用户 → 内置）
+    const pr=await fetch('/api/presets',{cache:'no-store'}).catch(()=>null); const pj=pr?await pr.json():{presets:[]};
+    const psel=$('#presetSel'); if(psel&&pj.presets){ for(const p of pj.presets){ const o=document.createElement('option'); o.value=p.name; o.textContent=p.label+'（'+(p.source==='project'?'项目':p.source==='user'?'用户':'内置')+'）'; o.title=p.description||p.name; psel.appendChild(o); } }
+  }catch(e){}
   try{
     const dr=await fetch('/api/draft?file='+encodeURIComponent(currentSession||''),{cache:'no-store'}); const dj=await dr.json();
     if(dj.text){ input.value=dj.text; input.style.height=Math.min(input.scrollHeight,200)+'px'; input.focus(); }
@@ -922,7 +930,8 @@ async function refreshModelsCfg(){
     div.innerHTML='<span style="flex:1;min-width:0"><b>'+esc(c.name)+'</b> <span style="color:var(--faint)">'+esc(c.label)+' · '+esc(c.baseUrl)+'</span></span><span style="white-space:nowrap">'+kstate+'</span>';
     const sk=document.createElement('button'); sk.textContent='设Key'; sk.style.cssText='padding:1px 8px;font-size:11px'; sk.onclick=async()=>{ const k=await uiPrompt('API Key（'+c.name+'）：', null, {hidden:true}); if(k===null) return; fetch('/api/models-config',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({action:'setCustomKey',name:c.name,key:k})}).then(rr=>rr.json()).then(jj=>{ if(jj.ok) refreshModelsCfg(); else uiAlert(jj.error||'设置失败'); }); };
     const test=document.createElement('button'); test.textContent='测试'; test.style.cssText='padding:1px 8px;font-size:11px'; test.onclick=async()=>{ test.disabled=true; test.textContent='测试中…'; try{ const rr=await fetch('/api/models-config',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({action:'testCustom',name:c.name})}); const jj=await rr.json().catch(()=>({error:'请求失败'})); if(jj.ok){ await uiAlert('✅ 连接成功（'+jj.latencyMs+'ms）：'+esc(jj.reply||'空回复')); } else { await uiAlert('✖ 连接失败：'+esc(jj.error||'未知错误')); } } finally { test.disabled=false; test.textContent='测试'; } };
-    const ed=document.createElement('button'); ed.textContent='修改'; ed.style.cssText='padding:1px 8px;font-size:11px'; ed.onclick=async()=>{ const u=await uiPrompt('API 地址：', c.baseUrl); if(u===null) return; const l=await uiPrompt('标签：', c.label); if(l===null) return; fetch('/api/models-config',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({action:'updateCustom',name:c.name,baseUrl:u,label:l})}).then(rr=>rr.json()).then(jj=>{ if(jj.ok){ refreshModelsCfg(); reloadModels(); } else uiAlert(jj.error||'修改失败'); }); };
+    const ed=document.createElement('button'); ed.textContent='修改'; ed.style.cssText='padding:1px 8px;font-size:11px'; ed.onclick=async()=>{ const u=await uiPrompt('API 地址：', c.baseUrl); if(u===null) return; const l=await uiPrompt('标签：', c.label); if(l===null) return; // v0.4.1：本地模型上下文窗口/最大输出可在设置里直接改（此前只能改 baseUrl+label，本地模型补 contextWindow 需手改 config.json）
+    const cw=await uiPrompt('上下文窗口 tokens（本地模型必填，如 131072；留空=不变）', c.contextWindow||''); if(cw===null) return; const mo=await uiPrompt('最大输出 tokens（可选，如 8192；留空=不变）', c.maxOutputTokens||''); if(mo===null) return; fetch('/api/models-config',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({action:'updateCustom',name:c.name,baseUrl:u,label:l,contextWindow:Number(cw)||undefined,maxOutputTokens:Number(mo)||undefined})}).then(rr=>rr.json()).then(jj=>{ if(jj.ok){ refreshModelsCfg(); reloadModels(); } else uiAlert(jj.error||'修改失败'); }); };
     const rm=document.createElement('button'); rm.textContent='删除'; rm.className='danger'; rm.style.cssText='padding:1px 8px;font-size:11px'; rm.onclick=async()=>{ if(!await uiConfirm('删除自定义模型 '+c.name+'？')) return; const rr=await fetch('/api/models-config',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({action:'removeCustom',name:c.name})}); const jj=await rr.json().catch(()=>({error:'失败'})); if(jj.ok){ refreshModelsCfg(); reloadModels(); } else uiAlert(jj.error||'删除失败'); };
     div.appendChild(sk); div.appendChild(test); div.appendChild(ed); div.appendChild(rm); cl.appendChild(div);
   }

package/src/web/index.html

@@ -57,6 +57,7 @@ header button{white-space:nowrap;flex:none}
 header select{flex:none}
 #sessionSearch{flex:1 1 auto;min-width:70px;max-width:220px;background:var(--bg3);color:var(--text);border:1px solid var(--border);border-radius:8px;padding:6px 12px;font-size:13px}
 #modelSel{max-width:170px;min-width:0}
+#presetSel{max-width:140px;min-width:0}
 #permSel{max-width:150px;min-width:0}
 #sessions{max-width:150px;min-width:0}
 #wsSel{max-width:130px;min-width:64px}
@@ -197,11 +198,12 @@ footer{flex:none;border-top:1px solid var(--border);background:var(--bg2);paddin
 #composer #permSel{max-width:96px;min-width:64px;flex:none;padding:8px 8px}
 #composer #reasoningSel{max-width:64px;min-width:48px;flex:none;padding:8px 6px;font-size:12px}
 #composer #modelSel{max-width:150px;min-width:88px;flex:none;padding:8px 8px;font-size:12px}
+#composer #presetSel{max-width:130px;min-width:76px;flex:none;padding:8px 8px;font-size:12px}
 #input{flex:1;background:var(--bg3);border:1px solid var(--border);border-radius:12px;color:var(--text);padding:10px 14px;font:14px/1.6 inherit;resize:none;min-height:44px;max-height:200px;min-width:0}
 #input:focus{outline:none;border-color:var(--accent2)}
 #hint{font-size:11.5px;color:var(--faint);margin-top:6px;max-width:860px;margin-left:auto;margin-right:auto}
 #statusBar{font-size:11.5px;color:var(--faint);margin-top:2px;max-width:860px;margin-left:auto;margin-right:auto;font-variant-numeric:tabular-nums;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
-@media (max-width:560px){footer{padding:10px 8px}#composer{gap:6px}#composer #permSel{min-width:52px;padding:8px 4px}#composer #reasoningSel{min-width:44px;padding:8px 4px}#composer #modelSel{min-width:72px;padding:8px 4px}#attachBtn{padding:10px 9px}}
+@media (max-width:560px){footer{padding:10px 8px}#composer{gap:6px}#composer #permSel{min-width:52px;padding:8px 4px}#composer #reasoningSel{min-width:44px;padding:8px 4px}#composer #modelSel{min-width:72px;padding:8px 4px}#composer #presetSel{min-width:64px;max-width:88px;padding:8px 4px}#attachBtn{padding:10px 9px}}
 .modal-mask{position:fixed;inset:0;background:rgba(0,0,0,.55);display:flex;align-items:center;justify-content:center;z-index:50}
 .modal{background:var(--panel);border:1px solid var(--border);border-radius:14px;width:min(520px,92vw);padding:18px;max-height:88vh;overflow-y:auto}
 /* 设置多级菜单（审计：一拉到底改为左侧分组导航 + 右侧面板） */
@@ -330,6 +332,7 @@ footer{flex:none;border-top:1px solid var(--border);background:var(--bg2);paddin
       <option value="readonly">只读</option>
     </select>
     <select id="modelSel" title="切换模型"></select>
+    <select id="presetSel" title="智能体预设：一键切换工具白名单/权限/参数组合（v0.4.0 契约化）"><option value="">预设…</option></select>
     <select id="reasoningSel" title="思考模式（推理等级）：关＝不推理省 token · 低 · 高（默认）· 最高＝最强推理" style="display:none">
       <option value="off">关</option>
       <option value="low">低</option>

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

@@ -3,6 +3,7 @@
 import { loadMemory, writeMemory, dedupeMemory } from '../../../memory.js';
 import { recordUsage, listCacheStats, summarizeCacheStats, costBreakdown } from '../../../cachestats.js';
 import { costGuardStatus } from '../../../cost-guard.js';
+import { listPresets } from '../../../presets.js';
 
 /**
  * 杂项域路由。命中返回 true，未命中返回 false。
@@ -100,6 +101,13 @@ export async function handle({ req, res, method, p, url }, deps, shared) {
     return true;
   }
 
+  // v0.4.0 Agent Preset：列出可用预设（项目 → 用户 → 内置，同名遮蔽）
+  if (method === 'GET' && p === '/api/presets') {
+    const workingDir = deps.state?.workingDir || process.cwd();
+    json(res, 200, { ok: true, presets: listPresets(workingDir) });
+    return true;
+  }
+
   if (method === 'POST' && p === '/api/memory') {
     const body = await readBody(req, MAX_API_BODY);
     if (body.action === 'dedupe') {

package/src/web/server.js

@@ -194,6 +194,13 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
   const provider = await getProviderFor(modelName);
   const undoStore = { backups: new Map() };
 
+  // v0.4.0 契约化：挂载 config.tools 声明式第三方工具（幂等，重启生效）
+  {
+    const { mountConfigTools } = await import('../tools/index.js');
+    const mounted = mountConfigTools(cfg);
+    if (mounted.length) console.error(`[MingDao] 🔧 已挂载声明式工具（config.tools）：${mounted.join(', ')}`);
+  }
+
   // MCP：A2 预热——await 连接（6s 超时）；超时本会话冻结工具集（不再中途注入，保护前缀缓存）
   /** @type {any} */
   let mcpManager = null;
@@ -250,7 +257,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
     if (h.includes(':')) {
       // IPv6：回环 ::1、链路本地 fe80::/10、唯一本地 fc00::/7、IPv4 映射 ::ffff:私网
       if (/^::ffff:/.test(h)) return isPrivateHost(h.slice(7));
-      return /^fe[89ab]/.test(h) || /^f[c d]/.test(h) || h === '::' || h === '::1';
+      return /^fe[89ab]/.test(h) || /^f[cd]/.test(h) || h === '::' || h === '::1';
     }
     const m = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
     if (!m) return false; // 域名：由 validateRemoteUrl 的 DNS 解析复检
@@ -408,7 +415,32 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
         sessionMemoryCache.delete(oldest);
       }
     }
-    const systemPrompt = buildSystemPrompt({ workingDir: taskDir, withJournal: body.withJournal === true, projectMemory: projectMemorySnapshot });
+    // v0.4.0 Agent Preset：body.preset 按会话一次选定（新会话或显式传值）；应用工具白名单/参数覆盖，
+    // 系统提示注入预设定制段。预设覆盖优先级：CLI/WebUI 显式 > 预设 > config.json。
+    let chatPreset = /** @type {any} */ (null);
+    let presetBlock = '';
+    let chatCfg = cfg;
+    if (typeof body.preset === 'string' && body.preset) {
+      const { loadPreset, presetConfigOverrides, presetSystemBlock, presetPermissionOverride } = await import('../presets.js');
+      chatPreset = loadPreset(taskDir, body.preset);
+      if (chatPreset) {
+        const over = presetConfigOverrides(chatPreset);
+        // P0（v0.4.1）：预设 permission 提权防护——不得把 ask/readonly 静默改成 auto
+        const permOv = presetPermissionOverride(chatPreset, cfg.permission ?? 'ask');
+        if (permOv.escalated) {
+          delete over.permission;
+          send({ type: 'banner', text: `⚠ 预设 "${chatPreset.name}" 声明 permission=${chatPreset.permission} 属提权（当前 ${cfg.permission ?? 'ask'}），已忽略并保持 ${permOv.permission}。` });
+        } else if (chatPreset.permission !== undefined) {
+          over.permission = permOv.permission;
+        }
+        chatCfg = { ...cfg, ...over, presetName: chatPreset.name };
+        presetBlock = presetSystemBlock(chatPreset);
+      } else {
+        // 预设不存在：不静默——banner 告知（前端下拉与磁盘不同步/项目级预设未带入时可见）
+        send({ type: 'banner', text: `⚠ 预设 "${String(body.preset)}" 不存在，已按当前配置继续。` });
+      }
+    }
+    const systemPrompt = buildSystemPrompt({ workingDir: taskDir, withJournal: body.withJournal === true, projectMemory: projectMemorySnapshot, presetBlock });
     let messages =
       session.messages?.length && session.messages[0]?.role === 'system'
         ? session.messages
@@ -448,7 +480,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
         entry.abortHandler = fn;
       },
     }));
-    const permission = createPermission(cfg.permission ?? 'ask', io);
+    const permission = createPermission(chatCfg.permission ?? 'ask', io);
     let providerNow;
     try {
       // 首次使用引导：未配置密钥时给明确指引，而不是晦涩的 401 原始报错
@@ -471,7 +503,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
       io,
       modelName: runModel,
       workingDir: taskDir,
-      cfg,
+      cfg: chatCfg, // v0.4.0：预设覆盖后的配置（工具白名单 presetTools/参数/权限）
       undoStore,
       mcp: mcpFacade,
       // 自动压缩后重写会话文件（否则每次加载历史都会重新触发压缩），并同步落盘游标