mingdao-harness 0.2.4 → 0.2.6

package/src/sync.js

@@ -23,15 +23,21 @@ const insecureOn = () => syncSettings()?.insecure === true;
 
 // 请求级不安全 TLS 传输（P1-6）：为本次请求单独建立 rejectUnauthorized:false 的 https.Agent，
 // 与并发的 provider 请求（各自的 TLS 校验）互不干扰；安全路径仍走 fetch（连接复用）。
+/**
+ * @param {any} target
+ * @param {{ headers?: any, body?: any, timeoutMs?: any, insecure?: any }} opts
+ */
 function rawRequest(target, { headers, body, timeoutMs, insecure }) {
   return new Promise((resolve, reject) => {
     const mod = target.protocol === 'http:' ? http : https;
+    /** @type {any} */
     const opts = { method: 'POST', headers };
     if (insecure && target.protocol === 'https:') opts.agent = new https.Agent({ rejectUnauthorized: false });
     const req = mod.request(target, opts, (res) => {
+      /** @type {any[]} */
       const chunks = [];
       let size = 0;
-      res.on('data', (d) => {
+      res.on('data', (/** @type {any} */ d) => {
         size += d.length;
         if (size > 25 * 1024 * 1024) {
           req.destroy();
@@ -56,6 +62,12 @@ function rawRequest(target, { headers, body, timeoutMs, insecure }) {
   });
 }
 
+/**
+ * @param {any} baseUrl
+ * @param {any} method
+ * @param {any} payload
+ * @param {any} token
+ */
 async function apiCall(baseUrl, method, payload, token, timeoutMs = TIMEOUT_MS, insecure = false) {
   const target = new URL(baseUrl.replace(/\/+$/, '') + method);
   const body = JSON.stringify(payload || {});
@@ -92,7 +104,7 @@ async function apiCall(baseUrl, method, payload, token, timeoutMs = TIMEOUT_MS,
       clearTimeout(timer);
     }
   } catch (e) {
-    if (e.name === 'AbortError' || e.message === '请求超时') throw new Error('请求超时（20s）');
+    if (/** @type {any} */ (e).name === 'AbortError' || /** @type {any} */ (e).message === '请求超时') throw new Error('请求超时（20s）');
     throw e;
   }
 }
@@ -120,6 +132,9 @@ export function syncStatus() {
 }
 
 // 登录/注册 + 设备配对：注册失败（用户不存在）先注册再配对
+/**
+ * @param {{ url?: any, username?: any, password?: any, deviceName?: any, insecure?: any }} opts
+ */
 export async function syncLogin({ url, username, password, deviceName, insecure = false }) {
   const base = String(url || '').trim().replace(/\/+$/, '');
   if (!/^https?:\/\//i.test(base)) return { error: '服务器地址需以 http(s):// 开头' };
@@ -133,8 +148,8 @@ export async function syncLogin({ url, username, password, deviceName, insecure
     try {
       pair = await apiCall(base, '/api/pair', { username: name, password, deviceName: dev }, undefined, TIMEOUT_MS, loginInsecure);
     } catch (e) {
-      if (e.status === 401) return { error: '用户名或密码错误' };
-      if (e.status !== 404) return { error: `连接失败：${e.message}` };
+      if (/** @type {any} */ (e).status === 401) return { error: '用户名或密码错误' };
+      if (/** @type {any} */ (e).status !== 404) return { error: `连接失败：${/** @type {any} */ (e).message}` };
       pair = { notFound: true }; // 用户不存在 → 先注册
     }
     if (pair.notFound) {
@@ -152,9 +167,9 @@ export async function syncLogin({ url, username, password, deviceName, insecure
     saveCredentials(creds);
     return { ok: true, username: name, deviceName: dev, url: base };
   } catch (e) {
-    if (e.status === 401) return { error: '用户名或密码错误' };
-    if (e.status === 404) return { error: '服务器接口不存在（确认是 mingdao 同步服务端）' };
-    return { error: `连接失败：${e.message}` };
+    if (/** @type {any} */ (e).status === 401) return { error: '用户名或密码错误' };
+    if (/** @type {any} */ (e).status === 404) return { error: '服务器接口不存在（确认是 mingdao 同步服务端）' };
+    return { error: `连接失败：${/** @type {any} */ (e).message}` };
   }
 }
 
@@ -190,15 +205,20 @@ export async function syncRemoteList() {
     const r = await apiCall(g.url, '/api/sessions/list', {}, g.token, TIMEOUT_MS, insecureOn());
     return { ok: true, sessions: r.sessions || [] };
   } catch (e) {
-    return { error: e.message };
+    return { error: /** @type {any} */ (e).message };
   }
 }
 
 // 会话名白名单（与 sync-server 同款）：远端返回的名字不满足即拒绝落盘，防恶意服务器任意文件写
+/** @param {any} n */
 function isValidRemoteName(n) {
   return typeof n === 'string' && /^[\w\u4e00-\u9fa5.-]{1,140}\.jsonl$/.test(n) && !n.includes('..');
 }
 // 冲突副本名：时间戳 + 随机后缀，防同一毫秒冲突静默覆盖
+/**
+ * @param {any} base
+ * @param {any} side
+ */
 function conflictCopyName(base, side) {
   return base.replace(/\.jsonl$/, `.${side}-${Date.now()}-${Math.random().toString(36).slice(2, 6)}.jsonl`);
 }
@@ -214,6 +234,7 @@ function readState() {
     return {};
   }
 }
+/** @param {any} state */
 function writeState(state) {
   ensureHome();
   const target = stateFile();
@@ -221,6 +242,7 @@ function writeState(state) {
 }
 
 // 推送单个/全部会话。仅当远端被其他设备改过（mtime 与本地记录不一致且内容不同）才视为冲突并备份远端。
+/** @param {any} [name] */
 export async function syncPush(name) {
   const g = tokenGuard();
   if (g.error) return { error: g.error };
@@ -257,7 +279,7 @@ export async function syncPush(name) {
     try {
       remote = await apiCall(g.url, '/api/sessions/pull', { name: s.name }, g.token, TIMEOUT_MS, insecureOn());
     } catch (e) {
-      if (e.status !== 404) return { error: `读取远端 ${s.name} 失败：${e.message}` };
+      if (/** @type {any} */ (e).status !== 404) return { error: `读取远端 ${s.name} 失败：${/** @type {any} */ (e).message}` };
     }
     if (remote?.ok) {
       const lastMtime = state[s.name]?.remoteMtime;
@@ -275,7 +297,7 @@ export async function syncPush(name) {
         state[s.name] = { remoteMtime: r.mtime, localMtime: localStat.mtimeMs };
       }
     } catch (e) {
-      return { error: `推送 ${s.name} 失败：${e.message}` };
+      return { error: `推送 ${s.name} 失败：${/** @type {any} */ (e).message}` };
     }
   }
   writeState(state);
@@ -283,6 +305,7 @@ export async function syncPush(name) {
 }
 
 // 拉取单个/全部会话。本地有不同内容时保留本地，远端写入 .remote- 副本。
+/** @param {any} [name] */
 export async function syncPull(name) {
   const g = tokenGuard();
   if (g.error) return { error: g.error };
@@ -290,9 +313,9 @@ export async function syncPull(name) {
   let sessions;
   try {
     const r = await apiCall(g.url, '/api/sessions/list', {}, g.token, TIMEOUT_MS, insecureOn());
-    sessions = (r.sessions || []).filter((s) => !name || s.name === name);
+    sessions = (r.sessions || []).filter((/** @type {any} */ s) => !name || s.name === name);
   } catch (e) {
-    return { error: `获取远端清单失败：${e.message}` };
+    return { error: `获取远端清单失败：${/** @type {any} */ (e).message}` };
   }
   if (!sessions.length) return { error: name ? `远端没有会话 ${name}` : '远端没有会话' };
   const state = readState();
@@ -330,6 +353,9 @@ export async function syncPull(name) {
 }
 
 // ---------- 密码修改 ----------
+/**
+ * @param {{ oldPassword?: any, newPassword?: any }} opts
+ */
 export async function syncChangePassword({ oldPassword, newPassword }) {
   const g = tokenGuard();
   if (g.error) return { error: g.error };
@@ -338,12 +364,13 @@ export async function syncChangePassword({ oldPassword, newPassword }) {
     const r = await apiCall(g.url, '/api/password', { oldPassword: oldPassword || '', newPassword }, g.token, TIMEOUT_MS, insecureOn());
     return r.ok ? { ok: true } : { error: r.error || '修改失败' };
   } catch (e) {
-    if (e.status === 401) return { error: '旧密码错误' };
-    return { error: `修改失败：${e.message}` };
+    if (/** @type {any} */ (e).status === 401) return { error: '旧密码错误' };
+    return { error: `修改失败：${/** @type {any} */ (e).message}` };
   }
 }
 
 // ---------- 会话分享与协作 ----------
+/** @param {any} name */
 export async function syncShareCreate(name) {
   const g = tokenGuard();
   if (g.error) return { error: g.error };
@@ -351,7 +378,7 @@ export async function syncShareCreate(name) {
     const r = await apiCall(g.url, '/api/share/create', { name }, g.token, TIMEOUT_MS, insecureOn());
     return r.ok ? { ok: true, shareId: r.shareId, name: r.name } : { error: r.error };
   } catch (e) {
-    return { error: `分享失败：${e.status === 404 ? '你还没有这个会话' : e.message}` };
+    return { error: `分享失败：${/** @type {any} */ (e).status === 404 ? '你还没有这个会话' : /** @type {any} */ (e).message}` };
   }
 }
 
@@ -362,10 +389,11 @@ export async function syncShareList() {
     const r = await apiCall(g.url, '/api/share/list', {}, g.token, TIMEOUT_MS, insecureOn());
     return { ok: true, mine: r.mine || [], accepted: r.accepted || [] };
   } catch (e) {
-    return { error: `获取分享列表失败：${e.message}` };
+    return { error: `获取分享列表失败：${/** @type {any} */ (e).message}` };
   }
 }
 
+/** @param {any} shareId */
 export async function syncShareAccept(shareId) {
   const g = tokenGuard();
   if (g.error) return { error: g.error };
@@ -382,10 +410,11 @@ export async function syncShareAccept(shareId) {
     writeState(state);
     return { ok: true, shareId, savedAs: r.savedAs, conflict: r.conflict || false };
   } catch (e) {
-    return { error: `接受分享失败：${e.status === 404 ? '分享不存在（可能已撤销）' : e.message}` };
+    return { error: `接受分享失败：${/** @type {any} */ (e).status === 404 ? '分享不存在（可能已撤销）' : /** @type {any} */ (e).message}` };
   }
 }
 
+/** @param {any} shareId */
 export async function syncShareRevoke(shareId) {
   const g = tokenGuard();
   if (g.error) return { error: g.error };
@@ -393,7 +422,7 @@ export async function syncShareRevoke(shareId) {
     const r = await apiCall(g.url, '/api/share/revoke', { shareId }, g.token, TIMEOUT_MS, insecureOn());
     return r.ok ? { ok: true } : { error: r.error };
   } catch (e) {
-    return { error: `撤销失败：${e.status === 404 ? '分享不存在' : e.status === 403 ? '只能撤销自己的分享' : e.message}` };
+    return { error: `撤销失败：${/** @type {any} */ (e).status === 404 ? '分享不存在' : /** @type {any} */ (e).status === 403 ? '只能撤销自己的分享' : /** @type {any} */ (e).message}` };
   }
 }
 
@@ -421,12 +450,16 @@ export function listSyncConflicts() {
     .map(([base, entries]) => ({
       base,
       localExists: fs.existsSync(path.join(home, 'sessions', base)),
-      entries: entries.sort((a, b) => b.ts - a.ts),
+      entries: entries.sort((/** @type {any} */ a, /** @type {any} */ b) => b.ts - a.ts),
     }))
     .sort((a, b) => a.base.localeCompare(b.base));
 }
 
 // choice: local（保留本地，删除备份）| remote（采用远端备份替换本地）| both（把最新备份转正为可见会话）
+/**
+ * @param {any} base
+ * @param {any} choice
+ */
 export function resolveSyncConflict(base, choice) {
   const home = mingdaoHome();
   if (!/^[\w\u4e00-\u9fa5.-]{1,140}\.jsonl$/.test(base)) return { error: '会话名非法' };
@@ -443,7 +476,7 @@ export function resolveSyncConflict(base, choice) {
       const mm = f.match(m);
       return mm && `${mm[1]}.jsonl` === base;
     })
-    .sort((a, b) => Number(b.match(m)[3]) - Number(a.match(m)[3]));
+    .sort((a, b) => Number(/** @type {any} */ (b.match(m))[3]) - Number(/** @type {any} */ (a.match(m))[3]));
   if (!backups.length) return { error: `没有找到 ${base} 的冲突备份` };
   const newest = backups[0];
   if (choice === 'local') {

package/src/tasks/worker.js

@@ -0,0 +1,126 @@
+// 后台任务 worker（Phase C C2）：独立进程执行一轮任务并写状态文件。
+// 由 cli.js 的内部入口 `mingdao run-worker <id> ...` 启动（startTask 拉起的子进程）。
+// 无交互：ask 权限降级 readonly；支持避峰顺延、MCP、自动标题、费用入账、完成通知与自动同步。
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig, ensureHome } from '../config.js';
+import { createProvider, resolveProviderConfig, helperProvider } from '../providers/index.js';
+import { startMcpServers } from '../mcp.js';
+import { patchTask } from '../tasks.js';
+import { notifyTaskDone } from '../notify.js';
+import { createAgent } from '../agent.js';
+import { createPermission } from '../permissions.js';
+import { buildSystemPrompt } from '../prompts.js';
+import { createSession, appendMessages, rewriteSession } from '../session.js';
+import { recordUsage } from '../cachestats.js';
+import { maybeAutoSync } from '../sync.js';
+import { isPeakHour, deferToOffpeak } from '../pricing.js';
+import { createIO } from '../ui.js';
+import { generateTitle, renameSessionFile, titleModel } from '../titles.js';
+
+/**
+ * 执行一轮后台任务：加载配置 → 建 agent → 跑回合 → 回写状态文件。
+ * @param {string} id 任务 id
+ * @param {string} question 任务内容
+ * @param {{permission?: any, model?: any, offpeak?: any}} opts
+ */
+export async function runWorkerTask(id, question, { permission, model, offpeak }) {
+  const home = ensureHome();
+  const finish = (/** @type {any} */ patch) => patchTask(home, id, patch);
+  let mcpFacade = null;
+  let cfg = null; // 提到 try 外：catch 分支也要读 cfg.notify
+  try {
+    cfg = loadConfig();
+    if (!cfg) throw new Error('未初始化配置，请先运行 mingdao init');
+    const modelName = model || cfg.model || 'deepseek-v4-flash';
+    const pc = resolveProviderConfig(cfg, modelName);
+    if (!pc.apiKey) throw new Error(`模型 ${modelName} 没有可用 API Key`);
+    const workingDir = process.cwd();
+    // 后台无交互：ask 权限降级为 readonly 并注明（需要写权限请 mingdao run --permission auto）
+    let perm = permission || cfg.permission || 'ask';
+    let note = '';
+    if (perm === 'ask') {
+      perm = 'readonly';
+      note = 'ask 权限下后台任务按只读执行';
+    }
+    // 避峰（评估 A2/Kimi P-1）：高峰时段（北京工作日 9:00–12:00、14:00–18:00）
+    // 自动顺延到最近闲时起点（12:00 / 18:00）执行，输入价省 50%
+    if (offpeak && isPeakHour(new Date())) {
+      const defer = deferToOffpeak(new Date());
+      finish({ note: `避峰等待至北京时间 ${defer.toISOString().slice(11, 16)}（闲时起执行，输入价省 50%）` });
+      await new Promise((r) => setTimeout(r, defer.getTime() - Date.now() + 2000));
+      finish({ note: '' });
+    }
+    const provider = await createProvider(cfg, modelName);
+    const io = createIO({ quiet: true });
+    const permissionObj = createPermission(perm, io);
+    /** @type {any} */
+    let mcpManager = null;
+    if (cfg.mcpServers && Object.keys(cfg.mcpServers).length) {
+      mcpFacade = {
+        toolSchemas: () => (mcpManager ? mcpManager.toolSchemas() : []),
+        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),
+        stop: () => {
+          if (mcpManager) mcpManager.stop();
+        },
+      };
+      startMcpServers(cfg.mcpServers, workingDir).then((m) => (mcpManager = m)).catch(() => {});
+    }
+    const sessionRef = /** @type {{name: any}} */ ({ name: null });
+    let persistedCount = 0;
+    const agent = createAgent({
+      provider,
+      permission: permissionObj,
+      io,
+      modelName,
+      workingDir,
+      cfg,
+      mcp: mcpFacade || undefined,
+      sessionRef,
+      onCompact: (/** @type {any} */ msgs) => {
+        rewriteSession(session.file, msgs);
+        persistedCount = msgs.length;
+      },
+    });
+    const session = createSession(home);
+    sessionRef.name = path.basename(session.file);
+    const messages = [
+      { role: 'system', content: buildSystemPrompt({ modelName, workingDir }) },
+      { role: 'user', content: question },
+    ];
+    appendMessages(session.file, messages);
+    persistedCount = messages.length;
+    const t0 = Date.now();
+    const res = await agent.runTurn(messages);
+    appendMessages(session.file, messages.slice(persistedCount));
+    if (cfg.autoTitle !== false && res.text) {
+      try {
+        const tModel = titleModel(cfg, modelName);
+        const title = await generateTitle(await helperProvider(cfg, tModel, provider), tModel, question);
+        if (title) renameSessionFile(fs, path, home, session, title);
+      } catch {}
+    }
+    const finalStatus = res.truncated ? 'failed' : res.aborted ? 'killed' : 'done';
+    recordUsage(res.perf?.usedModel || modelName, res.usage, /** @type {any} */ (res.perf));
+    finish({
+      status: finalStatus,
+      text: (res.text || '').slice(0, 2000),
+      usage: res.usage,
+      durationMs: Date.now() - t0,
+      session: path.basename(session.file),
+      note,
+    });
+    if (cfg.notify !== false && !process.env.MINGDAO_TASK_QUIET_NOTIFY) notifyTaskDone(question, finalStatus === 'killed' ? 'failed' : finalStatus);
+    try {
+      await maybeAutoSync();
+    } catch {}
+    process.exitCode = res.truncated ? 1 : 0;
+  } catch (/** @type {any} */ err) {
+    finish({ status: 'failed', error: String(err?.message || err) });
+    if (cfg?.notify !== false && !process.env.MINGDAO_TASK_QUIET_NOTIFY) notifyTaskDone(question, 'failed');
+    process.exitCode = 2;
+  } finally {
+    if (mcpFacade) mcpFacade.stop();
+  }
+}

package/src/tasks.js

@@ -11,11 +11,11 @@ import { atomicWriteFileSync, withFileLockSync } from './atomic-write.js';
 
 const CLI_PATH = fileURLToPath(new URL('./cli.js', import.meta.url));
 
-export function tasksDir(home) {
+export function tasksDir(/** @type {any} */ home) {
   return path.join(home, 'tasks');
 }
 
-export function listTasks(home) {
+export function listTasks(/** @type {any} */ home) {
   const dir = tasksDir(home);
   let files;
   try {
@@ -33,7 +33,7 @@ export function listTasks(home) {
   return out.sort((a, b) => b.startedAt - a.startedAt);
 }
 
-export function readTask(home, id) {
+export function readTask(/** @type {any} */ home, /** @type {any} */ id) {
   if (!isValidTaskId(id)) return null; // 防 id 路径穿越（id 直接拼进文件路径）
   try {
     return JSON.parse(fs.readFileSync(path.join(tasksDir(home), id + '.json'), 'utf8'));
@@ -42,18 +42,18 @@ export function readTask(home, id) {
   }
 }
 
-export function writeTask(home, task) {
+export function writeTask(/** @type {any} */ home, /** @type {any} */ task) {
   fs.mkdirSync(tasksDir(home), { recursive: true });
   // 原子写：先临时文件再改名，避免崩溃留下半截 JSON
   const target = path.join(tasksDir(home), task.id + '.json');
   atomicWriteFileSync(target, JSON.stringify(task, null, 2) + '\n'); // 质检 H4：tmp 名含 pid+随机
 }
 
-export function isValidTaskId(id) {
+export function isValidTaskId(/** @type {any} */ id) {
   return typeof id === 'string' && /^[a-z0-9]+$/.test(id) && id.length >= 4 && id.length <= 40;
 }
 
-export function startTask(home, question, { permission, model, cwd, offpeak, quietNotify } = /** @type {any} */ ({})) {
+export function startTask(/** @type {any} */ home, /** @type {any} */ question, { permission, model, cwd, offpeak, quietNotify } = /** @type {any} */ ({})) {
   const id = Date.now().toString(36) + Math.random().toString(36).slice(2, 6) + process.pid.toString(36);
   const task = {
     id,
@@ -83,16 +83,16 @@ export function startTask(home, question, { permission, model, cwd, offpeak, qui
   // 质检 M12：spawn 失败（ENOENT/ARG_MAX）必须有 error 监听，否则未捕获事件直接崩进程
   child.on('error', (err) => {
     try {
-      patchTask(home, id, { status: 'failed', error: `worker 启动失败：${err?.message || err}`, durationMs: Date.now() - task.startedAt });
+      patchTask(home, id, { status: 'failed', error: `worker 启动失败：${(/** @type {any} */ (err))?.message || err}`, durationMs: Date.now() - task.startedAt });
     } catch {}
   });
-  task.pid = child.pid;
+  task.pid = /** @type {any} */ (child.pid);
   writeTask(home, task);
   child.unref();
   return task;
 }
 
-export function patchTask(home, id, patch) {
+export function patchTask(/** @type {any} */ home, /** @type {any} */ id, /** @type {any} */ patch) {
   // 质检 H3：读-改-写加锁（worker finish 与 CLI kill 互斥，防 killed/done 互相覆盖）
   return withFileLockSync(path.join(tasksDir(home), '.lock'), () => {
     const t = readTask(home, id);
@@ -101,12 +101,12 @@ export function patchTask(home, id, patch) {
   });
 }
 
-export function killTask(home, id) {
+export function killTask(/** @type {any} */ home, /** @type {any} */ id) {
   if (!isValidTaskId(id)) return false;
   // 质检 H3：读-改-写加锁（与 worker 自身的状态写互斥）
   return withFileLockSync(path.join(tasksDir(home), '.lock'), () => killTaskInner(home, id));
 }
-function killTaskInner(home, id) {
+function killTaskInner(/** @type {any} */ home, /** @type {any} */ id) {
   const t = readTask(home, id);
   if (!t) return false;
   if (t.status === 'running' && t.pid) {
@@ -115,7 +115,7 @@ function killTaskInner(home, id) {
     try {
       owned = fs.readFileSync(`/proc/${t.pid}/cmdline`, 'utf8').includes(id);
     } catch {}
-    if (owned !== false) {
+    if (owned === true) { // 非 Linux/无法校验（null）不盲杀（CodeBuddy 报告：PID 复用误杀风险）
       try {
         // worker 是 detached 进程（自成进程组）：优先杀整组，避免工具子进程成孤儿
         process.kill(-t.pid, 'SIGTERM');
@@ -132,8 +132,8 @@ function killTaskInner(home, id) {
 
 const MARK = { running: '▶', done: '✓', failed: '✖', killed: '■' };
 
-export function formatTaskRow(t) {
-  const mark = MARK[t.status] || '?';
+export function formatTaskRow(/** @type {any} */ t) {
+  const mark = /** @type {any} */ (MARK)[t.status] || '?';
   const elapsed =
     t.status === 'running'
       ? relativeTime(t.startedAt).replace('前', '')

package/src/titles.js

@@ -4,21 +4,21 @@
 import { modelPreset } from './models.js';
 import { routingConfig } from './routing.js';
 
-export function titleModel(cfg, currentModel) {
+export function titleModel(/** @type {any} */ cfg, /** @type {any} */ currentModel) {
   const rc = routingConfig(cfg);
   if (rc) return rc.executor;
   // 路由关闭：辅助调用用当前模型（评估 P2-2：硬编码 flash 会在自定义网关 404 静默失败）
   return currentModel;
 }
 
-function cleanTitle(s) {
+function cleanTitle(/** @type {any} */ s) {
   return String(s ?? '')
     .trim()
     .replace(/["「」『』"'`*#\n\r]/g, '')
     .slice(0, 20);
 }
 
-export async function generateTitle(provider, model, firstUserText, { timeoutMs = 10000 } = {}) {
+export async function generateTitle(/** @type {any} */ provider, /** @type {any} */ model, /** @type {any} */ firstUserText, { timeoutMs = 10000 } = {}) {
   // 硬超时护栏（审计：「第二问无反应」根因）：标题生成发生在回合收尾阶段，若网关/网络层
   // 挂起（不抛错），回合永远无法 complete——前端停在生成态、后续发送全部静默。20s 兜底：
   // 超时放弃标题（会话仍以时间戳命名），绝不阻塞下一问。
@@ -65,13 +65,13 @@ export async function generateTitle(provider, model, firstUserText, { timeoutMs
   }
 }
 
-export function sanitizeTitle(s) {
+export function sanitizeTitle(/** @type {any} */ s) {
   const clean = String(s).replace(/[^\w\u4e00-\u9fa5 .-]/g, '_').slice(0, 40).trim();
   return clean || '会话';
 }
 
 // 重命名会话文件（与 /title 一致：确保存在、同名加随机后缀）
-export function renameSessionFile(fs, pathMod, home, session, title) {
+export function renameSessionFile(/** @type {any} */ fs, /** @type {any} */ pathMod, /** @type {any} */ home, /** @type {any} */ session, /** @type {any} */ title) {
   const safe = sanitizeTitle(title);
   let newFile = pathMod.join(home, 'sessions', safe + '.jsonl');
   try {

package/src/tokenizer.js

@@ -22,6 +22,7 @@ const SPLIT_RES = [
   /[!"#$%&'()*+,\-./:;<=>?@\[\\\]^_`{|}~][A-Za-z]+|[^\r\n\p{L}\p{P}\p{S}]?[\p{L}\p{M}]+| ?[\p{P}\p{S}]+[\r\n]*|\s*[\r\n]+|\s+(?!\S)|\s+/gu,
 ];
 
+/** @param {string} text */
 function pretokenize(text) {
   let pieces = [text];
   for (const re of SPLIT_RES) {
@@ -48,6 +49,7 @@ function pretokenize(text) {
 // 汉字会退化为逐字节计数（如「的」被计为 3 tokens 而非 1）。
 const BYTE_TO_UNICODE = (() => {
   const m = new Array(256);
+  /** @param {number} b */
   const self = (b) => (b >= 0x21 && b <= 0x7e) || (b >= 0xa1 && b <= 0xac) || (b >= 0xae);
   let n = 0;
   for (let b = 0; b < 256; b++) {
@@ -60,11 +62,14 @@ const BYTE_TO_UNICODE = (() => {
   return m;
 })();
 
+/** @param {string} s */
 function escapeRe(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/** @type {any} */
 let data = null;
+/** @type {any} */
 let loadError = null;
 
 function loadData() {
@@ -78,7 +83,7 @@ function loadData() {
       const [a, b] = parsed.merges[i];
       mergeRank.set(a + '\u0001' + b, i);
     }
-    const added = (parsed.added || []).filter(Boolean).sort((a, b) => b.length - a.length);
+    const added = (parsed.added || []).filter(Boolean).sort((/** @type {any} */ a, /** @type {any} */ b) => b.length - a.length);
     // 全部 added token 合并成单个正则（按长度降序排列 → 左起最长优先，与逐 token startsWith 语义一致），
     // 一次 matchAll 定位所有特殊 token，把 O(文本长 × 818 个 indexOf) 降到 O(n)
     const addedRe = added.length ? new RegExp(added.map(escapeRe).join('|'), 'gu') : null;
@@ -89,6 +94,7 @@ function loadData() {
   return data;
 }
 
+/** @param {any} modelName */
 export function isTokenizable(modelName) {
   if (typeof modelName !== 'string') return false;
   if (modelName.startsWith('deepseek')) return true;
@@ -124,15 +130,17 @@ const CJK_RANGES = [
   [0x3400, 0x4dbf], [0x4e00, 0x9fff], [0xf900, 0xfaff], // CJK 扩展/基本区/兼容
   [0x3040, 0x30ff], [0xac00, 0xd7af], // 假名 / 谚文
 ];
+/** @param {number} code */
 const isCjk = (code) => CJK_RANGES.some(([lo, hi]) => code >= lo && code <= hi);
 
+/** @param {any} text */
 export function heuristicTokens(text) {
   if (!text) return 0;
   let ascii = 0;
   let cjk = 0;
   let other = 0;
   for (const ch of String(text)) {
-    const code = ch.codePointAt(0);
+    const code = /** @type {number} */ (ch.codePointAt(0));
     if (code < 128) ascii += 1;
     else if (isCjk(code)) cjk += 1;
     else other += code > 0xffff ? 2 : 1; // 审计 B5：增补平面 emoji 按 2 token 保守计
@@ -144,6 +152,7 @@ export function heuristicTokens(text) {
 
 // 单个预分词片段的 BPE 计数（tiktoken 语义：优先合并 rank 最小的对，同 rank 取最左）。
 // 惰性最小堆实现（O(n log n)）：大文本（中文长文/工具输出）不再 O(n²) 全表扫描。
+/** @param {any} piece @param {any} d */
 function countPiece(piece, d) {
   const bytes = Buffer.from(piece, 'utf8');
   const syms = [];
@@ -151,17 +160,21 @@ function countPiece(piece, d) {
   if (syms.length <= 1) return syms.length;
 
   const alive = new Uint8Array(syms.length).fill(1);
+  /** @param {number} i */
   const leftOf = (i) => {
     for (let j = i - 1; j >= 0; j--) if (alive[j]) return j;
     return -1;
   };
+  /** @param {number} i */
   const rightOf = (i) => {
     for (let j = i + 1; j < syms.length; j++) if (alive[j]) return j;
     return -1;
   };
 
   // 最小堆（rank, leftIndex）；过期条目惰性丢弃/重推
+  /** @type {any[]} */
   const heap = [];
+  /** @param {number} rank @param {number} idx */
   const push = (rank, idx) => {
     heap.push([rank, idx]);
     let c = heap.length - 1;
@@ -182,6 +195,7 @@ function countPiece(piece, d) {
         const l = c * 2 + 1;
         const r = l + 1;
         let m = c;
+        /** @param {number} x */
         const better = (x) => heap[x][0] < heap[m][0] || (heap[x][0] === heap[m][0] && heap[x][1] < heap[m][1]);
         if (l < heap.length && better(l)) m = l;
         if (r < heap.length && better(r)) m = r;
@@ -238,6 +252,7 @@ const TOKEN_CACHE_MAX_ENTRIES = 512;
 const TOKEN_CACHE_MAX_LEN = 50000;
 const tokenCache = new Map();
 
+/** @param {string} s */
 function countDeepseek(s) {
   const d = loadData();
   if (!d) return heuristicTokens(s); // 词表缺失时优雅回退
@@ -254,12 +269,14 @@ function countDeepseek(s) {
   return total;
 }
 
+/** @param {any} piece @param {any} d */
 function countGap(piece, d) {
   let total = 0;
   for (const m of pretokenize(piece)) total += countPiece(m, d);
   return total;
 }
 
+/** @param {any} text @param {any} modelName */
 export function countTokens(text, modelName) {
   if (!text) return 0;
   const s = String(text);
@@ -273,15 +290,16 @@ export function countTokens(text, modelName) {
   const hit = byModel.get(s);
   if (hit !== undefined) return hit;
   const n = countDeepseek(s);
-  if (byModel.size >= TOKEN_CACHE_MAX_ENTRIES) byModel.clear();
+  if (byModel.size >= TOKEN_CACHE_MAX_ENTRIES) byModel.delete(byModel.keys().next().value); // LRU：删最旧（Map 迭代序）
   byModel.set(s, n);
   return n;
 }
 
 // 供上下文预算使用的计数器工厂
+/** @param {any} modelName */
 export function makeTokenCounter(modelName) {
   if (isTokenizable(modelName)) {
-    return (text) => countTokens(text, modelName);
+    return (/** @type {any} */ text) => countTokens(text, modelName);
   }
-  return (text) => heuristicTokens(text);
+  return (/** @type {any} */ text) => heuristicTokens(text);
 }