mingdao-harness 0.2.4 → 0.2.6

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

@@ -0,0 +1,79 @@
+// 技能域（Phase C C1）：/api/skills /api/skill-library /api/mcp-presets
+// 技能列表/安装/卸载、内置技能库 + 线上注册表搜索、MCP 生态预设接入。
+import { listSkills, tamperedSkillNames } from '../../../skills.js';
+import { libraryList, installSkill, uninstallSkill, installedUserSkillNames } from '../../../skill-lib.js';
+import { presetList, buildPreset } from '../../../mcp-presets.js';
+import { saveConfig } from '../../../config.js';
+
+/**
+ * 技能域路由。命中返回 true，未命中返回 false。
+ * @param {{req:any,res:any,method:any,p:any,url:any}} ctx
+ * @param {any} deps
+ * @param {{json:any,readBody:any,MAX_API_BODY:any}} shared
+ */
+export async function handle({ req, res, method, p, url }, deps, shared) {
+  const { json, readBody, MAX_API_BODY } = shared;
+  const { cfg, state } = deps;
+
+  if (method === 'GET' && p === '/api/skills') {
+    json(res, 200, { ok: true, skills: listSkills(state.workingDir), tampered: tamperedSkillNames(state.workingDir) });
+    return true;
+  }
+
+  if (method === 'GET' && p === '/api/mcp-presets') {
+    json(res, 200, { ok: true, presets: presetList() });
+    return true;
+  }
+
+  if (method === 'POST' && p === '/api/mcp-presets') {
+    const body = await readBody(req, MAX_API_BODY);
+    const name = String(body.name || '').trim();
+    const r = buildPreset(name, body.arg, state.workingDir);
+    if (r.error) return json(res, 400, { error: r.error });
+    cfg.mcpServers = cfg.mcpServers || {};
+    cfg.mcpServers[name] = r.config;
+    saveConfig(cfg);
+    json(res, 200, { ok: true, name, note: '重启 mingdao web 后生效（/mcp 查看状态）' });
+    return true;
+  }
+
+  if (method === 'GET' && p === '/api/skill-library') {
+    const q = url.searchParams.get('q') || '';
+    const force = url.searchParams.get('refresh') === '1';
+    const local = q
+      ? libraryList().filter((s) => s.name.includes(q) || (s.description || '').includes(q))
+      : libraryList();
+    const { searchRegistry } = await import('../../../skill-registry.js');
+    const remote = await searchRegistry(q || '', { force, allowNetwork: force });
+    const localNames = new Set(local.map((s) => s.name));
+    const registryEntries = remote.skills
+      ? remote.skills.filter((/** @type {any} */ s) => !localNames.has(s.name)).map((/** @type {any} */ s) => ({ ...s, dir: null }))
+      : [];
+    json(res, 200, {
+      ok: true,
+      library: local.map((s) => ({ name: s.name, description: s.description, source: 'builtin-lib', installed: s.installed })).concat(
+        registryEntries.map((/** @type {any} */ s) => ({ name: s.name, description: s.description, source: 'registry', installed: s.installed }))
+      ),
+      installed: [...installedUserSkillNames()],
+      registry: remote.error ? { error: remote.error } : { host: remote.host, updatedAt: remote.updatedAt, stale: remote.stale || false },
+    });
+    return true;
+  }
+
+  if (method === 'POST' && p === '/api/skills') {
+    const body = await readBody(req, MAX_API_BODY);
+    if (body.action === 'install') {
+      const r = /** @type {any} */ (await installSkill(body.arg || body.name || ''));
+      if (r.error) return json(res, 400, { error: r.error });
+      return json(res, 200, { ok: true, name: r.name, names: r.names });
+    }
+    if (body.action === 'uninstall') {
+      const r = uninstallSkill(body.name);
+      if (r.error) return json(res, 400, { error: r.error });
+      return json(res, 200, { ok: true, name: r.name });
+    }
+    return json(res, 400, { error: '未知操作：install|uninstall' });
+  }
+
+  return false;
+}

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

@@ -0,0 +1,101 @@
+// 同步域（Phase C C1）：/api/sync /api/sync-conflicts
+// 云同步登录/登出/推拉/改密/分享与冲突处理。
+import {
+  syncStatus,
+  syncLogin,
+  syncLogout,
+  syncPush,
+  syncPull,
+  syncRemoteList,
+  syncChangePassword,
+  syncShareCreate,
+  syncShareList,
+  syncShareAccept,
+  syncShareRevoke,
+  listSyncConflicts,
+  resolveSyncConflict,
+} from '../../../sync.js';
+
+/**
+ * 同步域路由。命中返回 true，未命中返回 false。
+ * @param {{req:any,res:any,method:any,p:any,url:any}} ctx
+ * @param {any} deps
+ * @param {{json:any,readBody:any,MAX_API_BODY:any,validateRemoteUrl:any}} shared
+ */
+export async function handle({ req, res, method, p, url }, deps, shared) {
+  const { json, readBody, MAX_API_BODY, validateRemoteUrl } = shared;
+
+  if (method === 'GET' && p === '/api/sync') {
+    const st = syncStatus();
+    let remote = null;
+    if (st.loggedIn) {
+      const r = await syncRemoteList();
+      remote = r.ok ? { sessions: r.sessions.slice(0, 50) } : { error: r.error };
+    }
+    json(res, 200, { ok: true, ...st, remote });
+    return true;
+  }
+
+  if (method === 'POST' && p === '/api/sync') {
+    const body = await readBody(req, MAX_API_BODY);
+    if (body.action === 'login') {
+      const vurl = await validateRemoteUrl(body.url); // 质检 S1：SSRF 防护（同步端点同样只允许公网）
+      if (vurl.error) return json(res, 400, { error: vurl.error });
+      const r = await syncLogin({ url: body.url, username: body.username, password: body.password, deviceName: body.deviceName });
+      if (r.error) return json(res, 400, { error: r.error });
+      return json(res, 200, { ok: true, ...r });
+    }
+    if (body.action === 'logout') {
+      syncLogout();
+      return json(res, 200, { ok: true });
+    }
+    if (body.action === 'push') {
+      const r = /** @type {any} */ (await syncPush(body.name));
+      if (r.error) return json(res, 400, { error: r.error });
+      return json(res, 200, { ok: true, pushed: r.pushed.length, conflicts: r.conflicts });
+    }
+    if (body.action === 'pull') {
+      const r = /** @type {any} */ (await syncPull(body.name));
+      if (r.error) return json(res, 400, { error: r.error });
+      return json(res, 200, { ok: true, pulled: r.pulled.length, conflicts: r.conflicts });
+    }
+    if (body.action === 'passwd') {
+      const r = await syncChangePassword({ oldPassword: body.oldPassword, newPassword: body.newPassword });
+      if (r.error) return json(res, 400, { error: r.error });
+      return json(res, 200, { ok: true });
+    }
+    if (body.action === 'share') {
+      const r = await syncShareCreate(body.name);
+      if (r.error) return json(res, 400, { error: r.error });
+      return json(res, 200, { ok: true, shareId: r.shareId, name: r.name });
+    }
+    if (body.action === 'shares') {
+      const r = await syncShareList();
+      if (r.error) return json(res, 400, { error: r.error });
+      return json(res, 200, { ok: true, mine: r.mine, accepted: r.accepted });
+    }
+    if (body.action === 'accept') {
+      const r = await syncShareAccept(body.shareId);
+      if (r.error) return json(res, 400, { error: r.error });
+      return json(res, 200, { ok: true, ...r });
+    }
+    if (body.action === 'unshare') {
+      const r = await syncShareRevoke(body.shareId);
+      if (r.error) return json(res, 400, { error: r.error });
+      return json(res, 200, { ok: true });
+    }
+    if (body.action === 'resolveConflict') {
+      const r = resolveSyncConflict(body.base, body.choice);
+      if (r.error) return json(res, 400, { error: r.error });
+      return json(res, 200, { ok: true, ...r });
+    }
+    return json(res, 400, { error: '未知操作：login|logout|push|pull|passwd|share|shares|accept|unshare|resolveConflict' });
+  }
+
+  if (method === 'GET' && p === '/api/sync-conflicts') {
+    json(res, 200, { ok: true, conflicts: listSyncConflicts() });
+    return true;
+  }
+
+  return false;
+}

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

@@ -0,0 +1,119 @@
+// 工作空间域（Phase C C1）：/api/workspaces /api/fs-browse
+// 工作空间登记/切换/重命名/删除；受限目录浏览（基目录白名单）。
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  currentWorkspace,
+  listWorkspaces,
+  addWorkspace,
+  removeWorkspace,
+  renameWorkspace,
+  setWorkspaceDir,
+  workspacePath,
+  touchWorkspace,
+  setSessionWorkspace,
+} from '../../../workspace.js';
+
+/**
+ * 工作空间域路由。命中返回 true，未命中返回 false。
+ * @param {{req:any,res:any,method:any,p:any,url:any}} ctx
+ * @param {any} deps
+ * @param {{json:any,readBody:any,MAX_API_BODY:any}} shared
+ */
+export async function handle({ req, res, method, p, url }, deps, shared) {
+  const { json, readBody, MAX_API_BODY } = shared;
+  const { cfg, state, startupCwd } = deps;
+
+  if (method === 'GET' && p === '/api/workspaces') {
+    json(res, 200, { ok: true, workspaces: listWorkspaces(), current: currentWorkspace(state.workingDir)?.name || null, cwd: state.workingDir });
+    return true;
+  }
+
+  if (method === 'POST' && p === '/api/workspaces') {
+    const body = await readBody(req, MAX_API_BODY);
+    const name = String(body.name || '').trim();
+    if (body.action === 'add') {
+      if (!name) return json(res, 400, { error: '名称不能为空' });
+      // 目录为空/不存在时自动新建（默认开，create:false 关闭）
+      const target = path.resolve(body.dir || state.workingDir);
+      if (body.create !== false) {
+        try {
+          fs.mkdirSync(target, { recursive: true });
+        } catch (/** @type {any} */ e) {
+          return json(res, 400, { error: `无法创建目录：${target}（${e.message}）` });
+        }
+      }
+      const r = addWorkspace(name, target);
+      if (r.error) return json(res, 400, { error: r.error });
+      return json(res, 200, { ok: true, name: r.name, dir: r.dir, created: body.create !== false });
+    }
+    if (body.action === 'rename') {
+      const r = renameWorkspace(name, body.newName);
+      if (r.error) return json(res, 400, { error: r.error });
+      return json(res, 200, { ok: true, name: r.name });
+    }
+    if (body.action === 'set') {
+      // 切换全局工作空间（新会话默认目录；可带 dir 修改目录）；目录缺失自动重建。
+      // 携带 file 时同时把当前会话的工作空间切过去（P3-4：会话跟随显式切换）。
+      if (body.dir) {
+        const r = setWorkspaceDir(name, body.dir);
+        if (r.error) return json(res, 400, { error: r.error });
+      }
+      const dir = workspacePath(name);
+      if (!dir) return json(res, 400, { error: `工作空间 ${name} 不存在` });
+      try {
+        fs.mkdirSync(dir, { recursive: true });
+      } catch (/** @type {any} */ e) {
+        return json(res, 400, { error: `无法创建目录：${dir}（${e.message}）` });
+      }
+      touchWorkspace(name);
+      state.workingDir = dir;
+      // 不再 process.chdir：运行中任务的 cwd 在创建时已固定，全局切换只影响新会话
+      if (body.file) setSessionWorkspace(String(body.file), dir, /** @type {any} */ (name));
+      return json(res, 200, { ok: true, name, dir, current: name });
+    }
+    if (body.action === 'remove') {
+      if (!name) return json(res, 400, { error: '缺少名称' });
+      return json(res, 200, { ok: removeWorkspace(name) });
+    }
+    return json(res, 400, { error: '未知操作：add|rename|set|remove' });
+  }
+
+  // 目录浏览器（「新建工作空间」选择电脑磁盘目录用）：本机运行时即用户电脑的目录树；
+  // 只列子目录（不含隐藏目录），供前端逐级导航选择
+  if (method === 'GET' && p === '/api/fs-browse') {
+    let dir = String(url.searchParams.get('dir') || '').trim();
+    if (!path.isAbsolute(dir)) return json(res, 400, { error: '需要绝对路径' });
+    // 质检 A3：目录浏览限定基目录，拒绝越界。Windows（CodeArts 报告）：家目录覆盖整个用户配置树
+    // （AppData 等）——收紧为 桌面/文档/下载 三常用目录 + 启动目录 + 工作目录 + web.browseRoots 显式授权；
+    // 路径比较在 win32 下大小写归一（D:\\ vs d:\\ 不再误拒）。
+    const base = process.platform === 'win32' && process.env.USERPROFILE
+      ? [path.join(process.env.USERPROFILE, 'Desktop'), path.join(process.env.USERPROFILE, 'Documents'), path.join(process.env.USERPROFILE, 'Downloads')]
+      : [os.homedir()];
+    const norm = (/** @type {string} */ x) => (process.platform === 'win32' ? x.toLowerCase() : x);
+    const browseRoots = [...base, startupCwd, state.workingDir, ...(Array.isArray(cfg.web?.browseRoots) ? cfg.web.browseRoots : [])].map((r) => norm(path.resolve(String(r))));
+    const ndir = norm(dir);
+    const inRoot = browseRoots.some((r) => ndir === r || ndir.startsWith(r + path.sep));
+    if (!inRoot) return json(res, 403, { error: '目录不在可浏览范围内（授权目录或 web.browseRoots 显式添加）' });
+    try {
+      const st = fs.statSync(dir);
+      if (!st.isDirectory()) return json(res, 400, { error: '不是目录' });
+      const entries = fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
+        .map((e) => ({ name: e.name, path: path.join(dir, e.name) }))
+        .sort((a, b) => a.name.localeCompare(b.name, 'zh-CN'))
+        .slice(0, 300);
+      let parent = path.dirname(dir);
+      // 父目录同样不得越出基目录
+      if (!browseRoots.some((r) => norm(parent) === r || norm(parent).startsWith(r + path.sep))) parent = /** @type {any} */ (null);
+      json(res, 200, { ok: true, path: dir, parent: parent === dir ? null : parent, entries });
+    } catch (/** @type {any} */ err) {
+      json(res, 400, { error: String(err?.message || err) });
+    }
+    return true;
+  }
+
+  return false;
+}

package/src/web/server.js

@@ -64,14 +64,22 @@ import { syncStatus, syncLogin, syncLogout, syncPush, syncPull, syncRemoteList,
 
 const INDEX_HTML = path.join(path.dirname(fileURLToPath(import.meta.url)), 'index.html');
 
+/** @param {any} res @param {any} code @param {any} obj */
 function json(res, code, obj) {
   res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
   res.end(JSON.stringify(obj));
+  // 返回 truthy：域路由 `return json(...)` 必须被编排器视为「已处理」——
+  // 否则兜底 404 会对已结束的响应二次写入（Node 18 下 write-after-end 未捕获 → 整服务崩溃）
+  return true;
 }
 
-function readBody(req) {
-  const MAX_BODY = 40 * 1024 * 1024; // 附件 base64 上限（4×5MB 图片 + 文本）留余量
+/** 读取请求体。limit 默认 40MB（附件 base64 上限：4×5MB 图片 + 文本）；
+ * 普通 JSON 接口必须显式传较小 limit（质检 A4；此前第二参数被忽略 → 1MB 限制形同虚设）。 */
+/** @param {any} req @param {number} [limit] */
+function readBody(req, limit = 40 * 1024 * 1024) {
+  const MAX_BODY = limit; // 附件 base64 上限（4×5MB 图片 + 文本）留余量
   return new Promise((resolve, reject) => {
+    /** @type {any[]} */
     const chunks = [];
     let size = 0;
     // 审计 P2-6：慢速连接防护——60s 未传完请求体即断开，防占满 socket
@@ -83,12 +91,14 @@ function readBody(req) {
     }, 60000);
     req.on('end', () => clearTimeout(slowTimer));
     req.on('close', () => clearTimeout(slowTimer));
-    req.on('data', (d) => {
+    req.on('data', (/** @type {any} */ d) => {
       size += d.length;
       if (size > MAX_BODY) {
-        const err = /** @type {Error & { status?: number }} */ (new Error('请求体过大（>40MB）'));
+        const err = /** @type {Error & { status?: number }} */ (new Error(`请求体过大（>${Math.round(MAX_BODY / 1048576)}MB）`));
         err.status = 413;
-        req.destroy();
+        // 排空残余数据但保留连接：让上层 catch 返回真 413（此前 destroy 导致客户端只收到连接重置）
+        req.pause();
+        req.resume();
         reject(err);
         return;
       }
@@ -117,6 +127,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
   }
   // 访问令牌（P1-3）：非回环绑定时强制——配置的 token / 启动参数 / 环境变量优先，
   // 都没有则本次随机生成并打印带 token 的访问地址。回环绑定且未配置时保持无认证（本机信任）。
+  /** @param {any} h */
   const isLoopbackHost = (h) => h === '127.0.0.1' || h === 'localhost' || h === '::1';
   let webToken = String(authToken || cfg?.web?.token || '').trim() || null;
   let tokenGenerated = false;
@@ -125,6 +136,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
     tokenGenerated = true;
   }
   const authEnabled = Boolean(webToken);
+  /** @param {any} got */
   const tokenMatches = (got) => {
     if (!webToken) return true;
     if (!got) return false;
@@ -132,6 +144,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
     const b = Buffer.from(webToken);
     return a.length === b.length && crypto.timingSafeEqual(a, b);
   };
+  /** @param {any} req @param {any} url */
   const requestToken = (req, url) => {
     const q = url.searchParams.get('token');
     if (q) return q;
@@ -143,6 +156,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
   // Host 白名单（P1-4，防 DNS rebinding）：只接受回环名 + 绑定地址；
   // 绑定 0.0.0.0 且启用 token 时放行任意 Host（此时 token 才是访问边界，攻击者页面拿不到）。
   let boundPort = port;
+  /** @param {any} reqHost */
   const trustedHost = (reqHost) => {
     const h = String(reqHost || '').toLowerCase();
     const names = new Set(['127.0.0.1', 'localhost', '::1']);
@@ -167,6 +181,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
   const startupCwd = workingDir; // 质检 A3：启动工作目录恒为合法浏览根（工作空间切换后仍可浏览原位）
   // Provider 按模型懒加载缓存：界面切换模型后即时生效
   const providerCache = new Map();
+  /** @param {any} m */
   async function getProviderFor(m) {
     if (!providerCache.has(m)) {
       providerCache.set(m, await createProvider(cfg, m));
@@ -176,19 +191,20 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
   const provider = await getProviderFor(modelName);
   const undoStore = { backups: new Map() };
 
-  // MCP：后台启动，就绪后工具并入后续轮次
+  // MCP：A2 预热——await 连接（6s 超时）；超时本会话冻结工具集（不再中途注入，保护前缀缓存）
+  /** @type {any} */
   let mcpManager = null;
   if (cfg.mcpServers && Object.keys(cfg.mcpServers).length) {
-    startMcpServers(cfg.mcpServers, workingDir)
-      .then((m) => {
-        mcpManager = m;
-      })
-      .catch(() => {});
+    mcpManager = await Promise.race([
+      startMcpServers(cfg.mcpServers, workingDir).catch(() => null),
+      new Promise((/** @type {any} */ r) => setTimeout(() => r(null), 6000)),
+    ]);
+    if (!mcpManager) console.error('[MingDao] ⚠ MCP 连接超时（6s）：本会话不注入 MCP 工具（重启 mingdao web 可重试）');
   }
   const mcpFacade = {
     toolSchemas: () => (mcpManager ? mcpManager.toolSchemas() : []),
-    call: (n, a) => (mcpManager ? mcpManager.call(n, a) : Promise.reject(new Error('MCP 未就绪'))),
-    isReadonly: (n) => (mcpManager ? mcpManager.isReadonly(n) : false),
+    call: (/** @type {any} */ n, /** @type {any} */ a) => (mcpManager ? mcpManager.call(n, a) : Promise.reject(new Error('MCP 未就绪'))),
+    isReadonly: (/** @type {any} */ n) => (mcpManager ? mcpManager.isReadonly(n) : false),
     status: () => (mcpManager ? mcpManager.status() : []),
     stop: () => {
       if (mcpManager) mcpManager.stop();
@@ -202,6 +218,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
   let taskSeq = 0;
   // 会话文件互斥（质检 C1/M3）：同一 session 文件的 append 与 compact 整文件重写必须串行
   const sessionLocks = new Map();
+  /** @param {any} file @param {any} fn */
   function withSessionLock(file, fn) {
     const prev = sessionLocks.get(file) || Promise.resolve();
     const next = prev.then(fn, fn);
@@ -216,17 +233,25 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
   const srvlog = createLogWriter(path.join(mingdaoHome(), 'logs', 'web-server.log'));
 
   // —— SSRF 防护（质检 S1）：远端地址校验 ——
+  /** @param {any} hostname */
   function isPrivateHost(hostname) {
-    const h = String(hostname || '').toLowerCase();
+    let h = String(hostname || '').toLowerCase();
     if (!h) return true;
-    if (h === 'localhost' || h.endsWith('.localhost') || h === '::1' || h === '::ffff:127.0.0.1') return true;
+    h = h.replace(/^\[|\]$/g, ''); // IPv6 字面量去括号（URL('http://[::1]/').hostname 带方括号）
+    if (h === 'localhost' || h.endsWith('.localhost') || h === '::1') return true;
+    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';
+    }
     const m = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
-    if (!m) return false; // 域名：交给 DNS 解析（无法静态判定）
+    if (!m) return false; // 域名：由 validateRemoteUrl 的 DNS 解析复检
     const a = Number(m[1]);
     const b = Number(m[2]);
     return a === 10 || a === 127 || a === 0 || a >= 224 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127);
   }
-  function validateRemoteUrl(raw) {
+  /** @param {any} raw */
+  async function validateRemoteUrl(raw) {
     let u;
     try {
       u = new URL(String(raw));
@@ -235,10 +260,24 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
     }
     if (u.protocol !== 'http:' && u.protocol !== 'https:') return { error: '仅支持 http/https 地址' };
     // 威胁模型：本机回环绑定时（默认/桌面版），本机模型服务（如 Ollama）属可信场景，放行；
-    // 对外监听（0.0.0.0）时拒绝私网目标——除非显式 allowPrivateEndpoints
+    // 对外监听（0.0.0.0）时拒绝私网目标——除非显式 allowPrivateEndpoints。
+    // 域名目标：DNS 解析后逐条校验（2026-09-02 加固，防 DNS 重绑定把域名指向内网绕过字面量检查）。
     const serverBoundLocal = isLoopbackHost(host);
-    if (!cfg.web?.allowPrivateEndpoints && !serverBoundLocal && isPrivateHost(u.hostname)) {
-      return { error: `拒绝访问内网/本机地址（${u.hostname}）——服务已对外监听，如确需连接可信内网服务，请在 config.json 设 web.allowPrivateEndpoints: true` };
+    if (!cfg.web?.allowPrivateEndpoints && !serverBoundLocal) {
+      const h = String(u.hostname || '').toLowerCase();
+      let blocked = isPrivateHost(h);
+      if (!blocked && h && h !== 'localhost' && !/^\d{1,3}(\.\d{1,3}){3}$/.test(h)) {
+        try {
+          const { lookup } = await import('node:dns/promises');
+          const addrs = await lookup(h, { all: true, verbatim: true });
+          blocked = addrs.some((/** @type {any} */ a) => isPrivateHost(a.address));
+        } catch {
+          // DNS 解析失败：保持放行（服务端会在连接时报错）；解析成功且指向内网 → 拦截
+        }
+      }
+      if (blocked) {
+        return { error: `拒绝访问内网/本机地址（${u.hostname}）——服务已对外监听，如确需连接可信内网服务，请在 config.json 设 web.allowPrivateEndpoints: true` };
+      }
     }
     return { ok: true };
   }
@@ -261,11 +300,13 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
     }
   }
 
+  /** @param {any} res @param {any} body */
   async function handleChat(res, body) {
     const taskId = `t${++taskSeq}`; // 服务端生成：客户端自选 taskId 可能覆盖他人任务
-    const entry = { res, send: null, abortHandler: null, pendingAsk: null, session: null, startedAt: Date.now(), status: 'running', message: '', durationMs: 0 };
+    const entry = /** @type {any} */ ({ res, send: null, abortHandler: null, pendingAsk: null, session: null, startedAt: Date.now(), status: 'running', message: '', durationMs: 0 });
     srvlog('chat 开始 ' + taskId + ' session=' + (body.file || '新会话') + ' 消息长度=' + String(body.message || '').length);
     tasks.set(taskId, entry);
+    /** @param {any} obj */
     const send = (obj) => {
       try {
         res.write(`data: ${JSON.stringify({ ...obj, taskId })}\n\n`);
@@ -301,6 +342,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
       return;
     }
 
+    /** @type {any} */
     let session = null;
     const isNew = !body.file;
     if (body.file) {
@@ -355,7 +397,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
     let persistedBefore = messages.length;
 
     // 权限/选择类交互：发 ask 事件（带 taskId），等待 POST /api/permission 应答
-    const askHandler = ({ question, hidden, options, label, confirm }) =>
+    const askHandler = (/** @type {any} */ { question, hidden, options, label, confirm }) =>
       new Promise((resolve) => {
         const id = Math.random().toString(36).slice(2);
         entry.pendingAsk = { id, resolve };
@@ -363,19 +405,19 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
           type: 'ask',
           id,
           question: question ?? label ?? '',
-          options: options ? options.map((o) => ({ value: o.value, label: o.label })) : null,
+          options: options ? options.map((/** @type {any} */ o) => ({ value: o.value, label: o.label })) : null,
           confirm: Boolean(confirm ?? !options),
           hidden: Boolean(hidden),
         });
       });
 
-    const io = createWebIO({
+    const io = /** @type {any} */ (createWebIO({
       send,
       askHandler,
-      setAbortHandler: (fn) => {
+      setAbortHandler: (/** @type {any} */ fn) => {
         entry.abortHandler = fn;
       },
-    });
+    }));
     const permission = createPermission(cfg.permission ?? 'ask', io);
     let providerNow;
     try {
@@ -384,7 +426,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
         throw new Error(`模型 ${runModel} 尚未配置 API Key：请点击右上角 ⚙ 设置 →「模型与 API Key」填入密钥。`);
       }
       providerNow = await getProviderFor(runModel); // 审计 P1-1：失败时清理任务占位，避免僵尸 running 耗尽并发
-    } catch (err) {
+    } catch (/** @type {any} */ err) {
       entry.status = 'failed';
       entry.durationMs = Date.now() - entry.startedAt;
       send({ type: 'error', message: `模型 ${runModel} 不可用：${String(err?.message || err)}` });
@@ -403,7 +445,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
       undoStore,
       mcp: mcpFacade,
       // 自动压缩后重写会话文件（否则每次加载历史都会重新触发压缩），并同步落盘游标
-      onCompact: (msgs) => {
+      onCompact: (/** @type {any} */ msgs) => {
         withSessionLock(session.file, () => rewriteSession(session.file, msgs)).catch(() => {}); // onCompact 为同步回调：入队串行即可
         persistedBefore = msgs.length;
       },
@@ -435,7 +477,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
       session.routeStats = { steps: st.steps + (io.stats().toolCount || 0), truncated: st.truncated + (r.truncated ? 1 : 0) };
       await withSessionLock(session.file, () => appendMessages(session.file, messages.slice(persistedBefore)));
       io.printUsageLine({ modelName: runModel, usage: r.usage, durationMs: r.durationMs });
-      recordUsage(r.perf?.usedModel || runModel, r.usage, r.perf);
+      recordUsage(r.perf?.usedModel || runModel, r.usage, /** @type {any} */ (r.perf));
       maybeAutoSync().catch(() => {});
       // 新会话自动标题（可配置关闭）
       srvlog('chat 标题生成前 ' + taskId);
@@ -460,7 +502,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
         const { makeTokenCounter } = await import('../tokenizer.js');
         const { messageTokens } = await import('../context.js');
         const counter = makeTokenCounter(runModel);
-        const used = messages.reduce((sum, m) => sum + messageTokens(m, counter), 0);
+        const used = messages.reduce((/** @type {any} */ sum, /** @type {any} */ m) => sum + messageTokens(m, counter), 0);
         budgetInfo = { used, total: cfg.contextBudget || modelPreset(runModel)?.budgetTokens || 128000 };
       } catch {}
       send({
@@ -476,7 +518,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
         stats: io.stats(),
         session: path.basename(session.file),
       });
-    } catch (err) {
+    } catch (/** @type {any} */ err) {
       entry.status = 'failed';
       entry.durationMs = Date.now() - entry.startedAt;
       srvlog('chat 错误 ' + taskId + ' ' + String(err?.message || err));