mingdao-harness 0.2.4 → 0.2.5

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 = 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,113 @@
+// 工作空间域（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：目录浏览限定基目录（默认家目录 + config.web.browseRoots 显式授权），
+    // 拒绝越界——此前可枚举服务器任意绝对路径（整机目录结构探测面）
+    const browseRoots = [os.homedir(), startupCwd, state.workingDir, ...(Array.isArray(cfg.web?.browseRoots) ? cfg.web.browseRoots : [])].map((r) => path.resolve(String(r)));
+    const inRoot = browseRoots.some((r) => dir === r || dir.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) => parent === r || 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,17 @@ 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));
 }
 
+/** @param {any} req */
 function readBody(req) {
   const MAX_BODY = 40 * 1024 * 1024; // 附件 base64 上限（4×5MB 图片 + 文本）留余量
   return new Promise((resolve, reject) => {
+    /** @type {any[]} */
     const chunks = [];
     let size = 0;
     // 审计 P2-6：慢速连接防护——60s 未传完请求体即断开，防占满 socket
@@ -83,7 +86,7 @@ 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）'));
@@ -117,6 +120,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 +129,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 +137,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 +149,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 +174,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));
@@ -177,6 +185,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
   const undoStore = { backups: new Map() };
 
   // MCP：后台启动，就绪后工具并入后续轮次
+  /** @type {any} */
   let mcpManager = null;
   if (cfg.mcpServers && Object.keys(cfg.mcpServers).length) {
     startMcpServers(cfg.mcpServers, workingDir)
@@ -187,8 +196,8 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
   }
   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 +211,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,6 +226,7 @@ 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();
     if (!h) return true;
@@ -226,6 +237,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken
     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);
   }
+  /** @param {any} raw */
   function validateRemoteUrl(raw) {
     let u;
     try {
@@ -261,11 +273,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 +315,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 +370,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 +378,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 +399,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 +418,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 +450,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 +475,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 +491,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));

package/src/web/web-io.js

@@ -3,6 +3,9 @@
 
 import { estimateCostLabel } from '../pricing.js';
 
+/**
+ * @param {{ send: any, askHandler: any, setAbortHandler: any }} param0
+ */
 export function createWebIO({ send, askHandler, setAbortHandler }) {
   const io = {
     isTTY: false,
@@ -10,12 +13,13 @@ export function createWebIO({ send, askHandler, setAbortHandler }) {
     _pending: null,
     _toolCount: 0,
     _taskCount: 0, // 子代理（task 工具）次数：进度心跳与轨迹面板用
-    _deliverables: [],
-    _activeTools: [], // {seq, key}：并行批次下 toolStart↔tool 按 name+args 配对（审计 P2-7）
+    _deliverables: /** @type {any[]} */ ([]),
+    _activeTools: /** @type {any[]} */ ([]), // {seq, key}：并行批次下 toolStart↔tool 按 name+args 配对（审计 P2-7）
     // 交付物与步数统计：写/编辑成功的文件路径（去重）
     stats() {
       return { toolCount: io._toolCount, taskCount: io._taskCount, deliverables: [...new Set(io._deliverables)] };
     },
+    /** @param {any} v */
     setShowReasoning(v) {
       io.showReasoning = !!v;
     },
@@ -26,6 +30,10 @@ export function createWebIO({ send, askHandler, setAbortHandler }) {
     print(text = '') {
       send({ type: 'banner', text });
     },
+    /**
+     * @param {any} title
+     * @param {any} lines
+     */
     box(title, lines) {
       send({ type: 'banner', title, lines });
     },
@@ -35,27 +43,39 @@ export function createWebIO({ send, askHandler, setAbortHandler }) {
     beginTurn() {},
     endTurn() {},
     startSpinner() {
-      if (!io._turnActive) {
-        io._turnActive = true;
+      if (!/** @type {any} */ (io)._turnActive) {
+        /** @type {any} */ (io)._turnActive = true;
         send({ type: 'turnStart', toolSteps: io._toolCount });
       }
     },
     stopSpinner() {
-      if (io._turnActive) {
-        io._turnActive = false;
+      if (/** @type {any} */ (io)._turnActive) {
+        /** @type {any} */ (io)._turnActive = false;
         send({ type: 'turnEnd', toolSteps: io._toolCount });
       }
     },
+    /** @param {any} t */
     writeText(t) {
       send({ type: 'text', delta: String(t) });
     },
+    /** @param {any} t */
     writeReasoning(t) {
       if (!io.showReasoning) return;
       send({ type: 'reasoning', delta: String(t) });
     },
+    /**
+     * @param {any} code
+     * @param {any} lang
+     */
     printCodeBlock(code, lang) {
       send({ type: 'code', code, lang });
     },
+    /**
+     * @param {any} name
+     * @param {any} args
+     * @param {any} result
+     * @param {any} durationMs
+     */
     renderTool(name, args, result, durationMs) {
       io._toolCount += 1;
       if (name === 'task') io._taskCount += 1;
@@ -64,16 +84,25 @@ export function createWebIO({ send, askHandler, setAbortHandler }) {
       }
       // 审计 P2-7：按 name+args 找回 toolStart 的 seq（并行批次下各卡片配对正确）
       const key = name + ':' + JSON.stringify(args || {});
-      const idx = io._activeTools.findIndex((a) => a.key === key);
-      const seq = idx !== -1 ? io._activeTools.splice(idx, 1)[0].seq : (io._toolSeq || 0) + 1;
+      const idx = io._activeTools.findIndex((/** @type {any} */ a) => a.key === key);
+      const seq = idx !== -1 ? io._activeTools.splice(idx, 1)[0].seq : (/** @type {any} */ (io)._toolSeq || 0) + 1;
       send({ type: 'tool', name, args, result, durationMs, seq });
     },
     // 工具开始执行：前端先渲染带旋转状态的卡片，完成后原地更新（seq 配对）
+    /**
+     * @param {any} name
+     * @param {any} args
+     */
     renderToolStart(name, args) {
-      io._toolSeq = (io._toolSeq || 0) + 1;
-      io._activeTools.push({ seq: io._toolSeq, key: name + ':' + JSON.stringify(args || {}) });
-      send({ type: 'toolStart', name, args, seq: io._toolSeq });
-    },
+      /** @type {any} */ (io)._toolSeq = (/** @type {any} */ (io)._toolSeq || 0) + 1;
+      io._activeTools.push({ seq: /** @type {any} */ (io)._toolSeq, key: name + ':' + JSON.stringify(args || {}) });
+      send({ type: 'toolStart', name, args, seq: /** @type {any} */ (io)._toolSeq });
+    },
+    /**
+     * @param {any} name
+     * @param {any} args
+     * @param {any} reason
+     */
     renderToolDenied(name, args, reason) {
       // 质检 L2：被拒的 toolStart 也要从 _activeTools 移除——否则条目无界增长、
       // 且后续同名同参工具可能 findIndex 命中陈旧 seq 导致卡片配对错位
@@ -82,9 +111,11 @@ export function createWebIO({ send, askHandler, setAbortHandler }) {
       if (idx !== -1) io._activeTools.splice(idx, 1);
       send({ type: 'toolDenied', name, args, reason: reason || '未授权' });
     },
+    /** @param {any} todos */
     renderTodo(todos) {
       send({ type: 'todo', todos });
     },
+    /** @param {{ modelName: any, usage: any, durationMs: any }} param0 */
     printUsageLine({ modelName, usage, durationMs }) {
       send({
         type: 'usage',
@@ -94,22 +125,33 @@ export function createWebIO({ send, askHandler, setAbortHandler }) {
         cost: estimateCostLabel(modelName, usage?.prompt_tokens ?? 0, usage?.completion_tokens ?? 0, usage),
       });
     },
+    /** @param {any} fn */
     onSigint(fn) {
       if (setAbortHandler) setAbortHandler(fn);
       return () => {
         if (setAbortHandler) setAbortHandler(null);
       };
     },
+    /**
+     * @param {any} question
+     * @param {any} opts
+     */
     ask(question, opts = {}) {
       return askHandler({ question, hidden: Boolean(opts.hidden) });
     },
+    /** @param {any} prompt */
     async askMultiline(prompt) {
       return askHandler({ question: prompt });
     },
+    /** @param {any} question */
     async confirm(question) {
       const a = await askHandler({ question: question + ' ', confirm: true });
       return /^y(es)?$/i.test(String(a));
     },
+    /**
+     * @param {any} label
+     * @param {any} options
+     */
     async choose(label, options) {
       return askHandler({ label, options });
     },