mingdao-harness 0.2.4 → 0.2.5

package/src/mcp.js

@@ -25,13 +25,13 @@ const HANDSHAKE_TIMEOUT_MS = 20000;
 let nextId = 1;
 
 export class McpClient {
-  constructor(name, { command, args = [], env = {} }, workingDir) {
+  constructor(/** @type {any} */ name, /** @type {any} */ { command, args = [], env = {} }, /** @type {any} */ workingDir) {
     this.name = name;
     this.command = command;
     this.args = args;
     this.env = env;
     this.workingDir = workingDir;
-    this.tools = [];
+    this.tools = /** @type {any[]} */ ([]);
     this.child = null;
     this.pending = new Map();
     this.buf = '';
@@ -66,14 +66,14 @@ export class McpClient {
       await this._handshake();
       await this._listTools();
     } catch (err) {
-      this.error = String(err?.message || err);
+      this.error = String((/** @type {any} */ (err))?.message || err);
       this.stop(); // 审计 P1-3：握手/列工具失败时清理 detached 子进程树，防孤儿
       throw err;
     }
     return this;
   }
 
-  _onData(d) {
+  _onData(/** @type {any} */ d) {
     this.buf += d.toString('utf8');
     if (this.buf.length > 20 * 1024 * 1024) {
       // 恶意/异常服务器灌入超量数据：放弃解析，避免内存膨胀
@@ -104,7 +104,7 @@ export class McpClient {
     }
   }
 
-  _failAll(reason) {
+  _failAll(/** @type {any} */ reason) {
     for (const [, p] of this.pending) {
       clearTimeout(p.timer);
       p.reject(new Error(reason));
@@ -112,7 +112,7 @@ export class McpClient {
     this.pending.clear();
   }
 
-  request(method, params = {}) {
+  request(/** @type {any} */ method, params = {}) {
     if (!this.child || this.child.killed) {
       return Promise.reject(new Error(`MCP 服务器 ${this.name} 未运行`));
     }
@@ -124,16 +124,16 @@ export class McpClient {
       }, REQUEST_TIMEOUT_MS);
       this.pending.set(id, { resolve, reject, timer });
       try {
-        this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+        (/** @type {any} */ (this.child)).stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
       } catch (err) {
         clearTimeout(timer);
         this.pending.delete(id);
-        reject(new Error(`MCP [${this.name}] 写入失败：${err.message}`));
+        reject(new Error(`MCP [${this.name}] 写入失败：${(/** @type {any} */ (err)).message}`));
       }
     });
   }
 
-  notify(method, params = {}) {
+  notify(/** @type {any} */ method, params = {}) {
     try {
       this.child?.stdin?.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n');
     } catch {}
@@ -165,7 +165,7 @@ export class McpClient {
     this.tools = Array.isArray(res?.tools) ? res.tools : [];
   }
 
-  prefixedName(toolName) {
+  prefixedName(/** @type {any} */ toolName) {
     return `mcp__${this.name}__${toolName}`;
   }
 
@@ -182,18 +182,18 @@ export class McpClient {
       }));
   }
 
-  isReadonly(toolName) {
+  isReadonly(/** @type {any} */ toolName) {
     const t = this.tools.find((x) => x.name === toolName);
     return Boolean(t?.annotations?.readOnlyHint);
   }
 
-  async callTool(toolName, args) {
+  async callTool(/** @type {any} */ toolName, /** @type {any} */ args) {
     const res = await this.request('tools/call', { name: toolName, arguments: args });
     if (res?.isError) {
-      const text = (res.content || []).map((c) => c.text || '').join('\n');
+      const text = (res.content || []).map((/** @type {any} */ c) => c.text || '').join('\n');
       return { ok: false, error: text || 'MCP 工具返回错误' };
     }
-    let parts = (res?.content || []).map((c) => (c.type === 'text' ? c.text : `[${c.type}] ${JSON.stringify(c)}`));
+    let parts = (res?.content || []).map((/** @type {any} */ c) => (c.type === 'text' ? c.text : `[${c.type}] ${JSON.stringify(c)}`));
     let text = parts.join('\n') || '(无输出)';
     if (text.length > 100 * 1024) text = text.slice(0, 100 * 1024) + `\n…[MCP 输出过长已截断，原文共 ${text.length} 字符]`;
     return { ok: true, output: text };
@@ -214,7 +214,7 @@ export class McpClient {
 }
 
 // 多服务器管理器：部分服务器启动失败不影响其余
-export async function startMcpServers(mcpCfg, workingDir) {
+export async function startMcpServers(/** @type {any} */ mcpCfg, /** @type {any} */ workingDir) {
   const clients = new Map();
   const entries = Object.entries(mcpCfg || {});
   await Promise.all(
@@ -225,7 +225,7 @@ export async function startMcpServers(mcpCfg, workingDir) {
       try {
         await client.start();
       } catch (err) {
-        client.error = String(err?.message || err);
+        client.error = String((/** @type {any} */ (err))?.message || err);
       }
     })
   );
@@ -246,7 +246,7 @@ export async function startMcpServers(mcpCfg, workingDir) {
       }
       return out;
     },
-    lookup(prefixedName) {
+    lookup(/** @type {any} */ prefixedName) {
       const exact = managerExact.get(prefixedName);
       if (exact) {
         const c = clients.get(exact.server);
@@ -255,12 +255,12 @@ export async function startMcpServers(mcpCfg, workingDir) {
       }
       return null;
     },
-    async call(prefixedName, args) {
+    async call(/** @type {any} */ prefixedName, /** @type {any} */ args) {
       const found = this.lookup(prefixedName);
       if (!found) return { ok: false, error: `MCP 工具不可用：${prefixedName}` };
       return found.client.callTool(found.toolName, args);
     },
-    isReadonly(prefixedName) {
+    isReadonly(/** @type {any} */ prefixedName) {
       const found = this.lookup(prefixedName);
       return found ? found.client.isReadonly(found.toolName) : false;
     },

package/src/memory.js

@@ -25,14 +25,14 @@ export function loadMemory() {
   }
 }
 
-export function appendMemory(lines) {
-  const add = lines.map((l) => l.trim()).filter(Boolean);
+export function appendMemory(/** @type {any} */ lines) {
+  const add = lines.map((/** @type {any} */ l) => l.trim()).filter(Boolean);
   if (!add.length) return 0;
   ensureHome();
   // 审计 B9 + 质检 M8：与费用统计同口径，用配置时区（默认北京时间）自然日做记忆日期戳
   const bp = beijingParts(new Date());
   const date = `${bp.year}-${String(bp.month).padStart(2, '0')}-${String(bp.day).padStart(2, '0')}`;
-  fs.appendFileSync(memoryFile(), add.map((l) => (l.startsWith('-') ? `- [${date}] ${l.slice(1).trim()}` : `- [${date}] ${l}`)).join('\n') + '\n');
+  fs.appendFileSync(memoryFile(), add.map((/** @type {any} */ l) => (l.startsWith('-') ? `- [${date}] ${l.slice(1).trim()}` : `- [${date}] ${l}`)).join('\n') + '\n');
   return add.length;
 }
 
@@ -43,7 +43,7 @@ function backupMemory() {
 }
 
 // 整体覆写（编辑面板保存用，自动备份）
-export function writeMemory(content) {
+export function writeMemory(/** @type {any} */ content) {
   backupMemory();
   ensureHome();
   fs.writeFileSync(memoryFile(), String(content ?? ''));
@@ -75,7 +75,7 @@ export function dedupeMemory() {
 }
 
 // 删除包含关键词的条目
-export function removeMemoryLines(keyword) {
+export function removeMemoryLines(/** @type {any} */ keyword) {
   const raw = loadMemory();
   const kw = String(keyword).trim().toLowerCase();
   if (!raw.trim() || !kw) return 0;
@@ -97,7 +97,7 @@ export function removeMemoryLines(keyword) {
 
 let journalCount = 0; // 内存计数（评估 P3-2）：避免每次写入都整文件读一遍只为查行数
 
-export function appendJournal(home, entry) {
+export function appendJournal(/** @type {any} */ home, /** @type {any} */ entry) {
   try {
     // journalFile() 已含 mingdaoHome()（home 参数仅为兼容旧签名保留）。
     // 不能 path.join(home, dirname(journalFile()))：journalFile() 是绝对路径，join 会拼出
@@ -108,7 +108,7 @@ export function appendJournal(home, entry) {
     journalCount += 1;
   } catch (err) {
     // 静默吞错面收窄（评估建议 3）：调试开关可见原因，正常使用仍零打扰
-    if (process.env.MINGDAO_DEBUG) console.warn('[MingDao] journal 写入失败：' + (err?.message || err));
+    if (process.env.MINGDAO_DEBUG) console.warn('[MingDao] journal 写入失败：' + ((/** @type {any} */ (err))?.message || err));
   }
   // 低频截断：超过 600 行时重写保留最近 500 行（跨过上限后每 200 条检查一次）
   if (journalCount > 600 && journalCount % 200 === 0) {
@@ -123,7 +123,7 @@ export function appendJournal(home, entry) {
   }
 }
 
-export function recentJournal(home, n = 3) {
+export function recentJournal(/** @type {any} */ home, n = 3) {
   try {
     const raw = fs.readFileSync(journalFile(), 'utf8');
     return raw
@@ -143,7 +143,7 @@ export function recentJournal(home, n = 3) {
   }
 }
 
-export function recentJournalBlock(home) {
+export function recentJournalBlock(/** @type {any} */ home) {
   const entries = recentJournal(home, 3);
   if (!entries.length) return '';
   return (
@@ -160,12 +160,12 @@ export function recentJournalBlock(home) {
 }
 
 // 自动记忆提取：从对话提炼值得长期记住的用户偏好/事实（去重：已有记忆会先提供给模型）
-export async function extractMemory(provider, model, messages, existingMemory) {
+export async function extractMemory(/** @type {any} */ provider, /** @type {any} */ model, /** @type {any} */ messages, /** @type {any} */ existingMemory) {
   try {
     const convo = messages
-      .filter((m) => m.role === 'user' || m.role === 'assistant')
+      .filter((/** @type {any} */ m) => m.role === 'user' || m.role === 'assistant')
       .slice(-20)
-      .map((m) => `${m.role === 'user' ? '用户' : 'MingDao'}：${String(m.content || '').slice(0, 500)}`)
+      .map((/** @type {any} */ m) => `${m.role === 'user' ? '用户' : 'MingDao'}：${String(m.content || '').slice(0, 500)}`)
       .join('\n');
     const msgs = [
       {
@@ -182,9 +182,9 @@ export async function extractMemory(provider, model, messages, existingMemory) {
       const j = JSON.parse(String(res.text || '').trim());
       const items = Array.isArray(j?.items) ? j.items : [];
       const clean = items
-        .map((l) => String(l).trim())
+        .map((/** @type {any} */ l) => String(l).trim())
         .filter(Boolean)
-        .map((l) => (/^[·•]/.test(l) ? '- ' + l.replace(/^[·•]\s*/, '') : l.startsWith('-') ? l : '- ' + l)) // 审计 Q4：非前缀条目规整为 "- "，不再二次回退调用
+        .map((/** @type {any} */ l) => (/^[·•]/.test(l) ? '- ' + l.replace(/^[·•]\s*/, '') : l.startsWith('-') ? l : '- ' + l)) // 审计 Q4：非前缀条目规整为 "- "，不再二次回退调用
         .slice(0, 10);
       if (clean.length || items.length === 0) return clean; // 空数组 = 无新增；有内容即返回
     } catch {}
@@ -217,8 +217,8 @@ export async function extractMemory(provider, model, messages, existingMemory) {
 }
 
 // 会话收尾：写日志 + 自动记忆（turns 太少的一次性会话只记日志不提取）
-export async function finalizeSession({ cfg, provider, model, home, workingDir, messages, turns, lastText }) {
-  const firstUser = messages.find((m) => m.role === 'user')?.content || '';
+export async function finalizeSession(/** @type {any} */ { cfg, provider, model, home, workingDir, messages, turns, lastText }) {
+  const firstUser = messages.find((/** @type {any} */ m) => m.role === 'user')?.content || '';
   try {
     const wsName = null; // 由调用方通过 currentWorkspace 提供会更好，这里保持轻量
     appendJournal(home, {

package/src/model-discovery.js

@@ -25,38 +25,38 @@ function loadCache() {
   }
 }
 
-function saveCache(data) {
+function saveCache(/** @type {any} */ data) {
   try {
     ensureHome();
     fs.writeFileSync(modelCacheFile(), JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
   } catch {}
 }
 
-export function providerHasKey(providerName) {
-  const pp = PROVIDERS[providerName];
+export function providerHasKey(/** @type {any} */ providerName) {
+  const pp = /** @type {any} */ (PROVIDERS)[providerName];
   if (!pp) return false;
   if (getStoredKey(providerName)) return true;
   if (pp.envKey && process.env[pp.envKey]) return true;
   return false;
 }
 
-export function providerBaseUrl(cfg, providerName) {
-  const pp = PROVIDERS[providerName];
+export function providerBaseUrl(/** @type {any} */ cfg, /** @type {any} */ providerName) {
+  const pp = /** @type {any} */ (PROVIDERS)[providerName];
   if (!pp) return '';
   // 当前服务商的 baseUrl 覆盖优先
   if (providerName === cfg?.provider && cfg?.baseUrl) return cfg.baseUrl;
   return pp.baseUrl || '';
 }
 
-export function providerApiKey(providerName) {
-  const pp = PROVIDERS[providerName];
+export function providerApiKey(/** @type {any} */ providerName) {
+  const pp = /** @type {any} */ (PROVIDERS)[providerName];
   const stored = getStoredKey(providerName);
   if (stored) return stored;
   if (pp?.envKey && process.env[pp.envKey]) return process.env[pp.envKey];
   return '';
 }
 
-function isChatModel(id) {
+function isChatModel(/** @type {any} */ id) {
   return !/embedding|rerank|moderation/i.test(id);
 }
 
@@ -64,7 +64,7 @@ function isChatModel(id) {
 // 返回 { models: [名称], fromCache, fetchedAt }；失败返回 { error }
 const inflight = new Map(); // 同服务商并发去重：合并为同一请求
 
-export async function fetchProviderModels(cfg, providerName, { force = false } = {}) {
+export async function fetchProviderModels(/** @type {any} */ cfg, /** @type {any} */ providerName, { force = false } = {}) {
   const base = providerBaseUrl(cfg, providerName).replace(/\/+$/, '');
   const key = providerApiKey(providerName);
   if (!base || !key) return { error: '该服务商未设置 API Key' };
@@ -86,8 +86,8 @@ export async function fetchProviderModels(cfg, providerName, { force = false } =
       if (!res.ok) return { error: `HTTP ${res.status}` };
       const j = /** @type {any} */ (await res.json().catch(() => null));
       const list = (j?.data || [])
-        .map((m) => String(m?.id || '').trim())
-        .filter((id) => id && isChatModel(id))
+        .map((/** @type {any} */ m) => String(m?.id || '').trim())
+        .filter((/** @type {any} */ id) => id && isChatModel(id))
         .slice(0, 200);
       if (!list.length) return { error: '接口未返回可用模型' };
       const cache2 = loadCache(); // 重新读取：避免与并发写入互相覆盖
@@ -95,7 +95,8 @@ export async function fetchProviderModels(cfg, providerName, { force = false } =
       saveCache(cache2);
       return { models: list, fromCache: false, fetchedAt: Date.now() };
     } catch (e) {
-      return { error: e.name === 'AbortError' ? '请求超时（8s）' : e.message };
+      const ee = /** @type {any} */ (e);
+      return { error: ee.name === 'AbortError' ? '请求超时（8s）' : ee.message };
     } finally {
       clearTimeout(timer);
     }
@@ -109,7 +110,7 @@ export async function fetchProviderModels(cfg, providerName, { force = false } =
 }
 
 // 合并可用模型列表：只含已设置 Key 的服务商；动态名单优先、预设回退；自定义模型恒在。
-export async function availableModels(cfg, currentModel) {
+export async function availableModels(/** @type {any} */ cfg, /** @type {any} */ currentModel) {
   const out = [];
   const seen = new Set();
   for (const [pname, pp] of Object.entries(PROVIDERS)) {
@@ -120,13 +121,13 @@ export async function availableModels(cfg, currentModel) {
     for (const n of names) {
       if (seen.has(n)) continue;
       seen.add(n);
-      const preset = MODELS[n];
+      const preset = /** @type {any} */ (MODELS)[n];
       out.push({
         name: n,
         label: preset ? `${n} — ${preset.label}` : `${n}（线上最新）`,
         provider: pname,
         providerLabel: pp.label,
-        dynamic: !MODELS[n],
+        dynamic: !(/** @type {any} */ (MODELS))[n],
       });
     }
   }

package/src/models.js

@@ -183,10 +183,10 @@ export const MODELS = {
   },
 };
 
-export function modelPreset(name) {
-  return MODELS[name] || null;
+export function modelPreset(/** @type {any} */ name) {
+  return /** @type {any} */ (MODELS)[name] || null;
 }
 
-export function providerPreset(name) {
-  return PROVIDERS[name] || null;
+export function providerPreset(/** @type {any} */ name) {
+  return /** @type {any} */ (PROVIDERS)[name] || null;
 }

package/src/notify.js

@@ -6,7 +6,7 @@
 
 import { spawn } from 'node:child_process';
 
-export function notify(title, message) {
+export function notify(/** @type {any} */ title, /** @type {any} */ message) {
   try {
     const text = String(message).replace(/\s+/g, ' ').slice(0, 120);
     // 审计 P2-12：title 同样转义（mac 反斜杠/引号、win 单引号），防注入破坏命令
@@ -33,6 +33,6 @@ export function notify(title, message) {
   }
 }
 
-export function notifyTaskDone(question, status) {
+export function notifyTaskDone(/** @type {any} */ question, /** @type {any} */ status) {
   notify('MingDao', `${status === 'done' ? '✓ 完成' : '✖ 失败'}：${String(question).slice(0, 60)}`);
 }

package/src/permissions.js

@@ -12,6 +12,7 @@
 import { style, C } from './ui.js';
 import { READONLY_TOOLS } from './tools/index.js';
 
+/** @param {any} name @param {any} args */
 function summarize(name, args) {
   try {
     if (name === 'bash') return ` ${args.command ?? ''}`;
@@ -22,6 +23,7 @@ function summarize(name, args) {
   }
 }
 
+/** @param {any} rule @param {any} name @param {any} args */
 function ruleMatches(rule, name, args) {
   const idx = rule.indexOf(':');
   if (idx > 0) {
@@ -37,6 +39,7 @@ function ruleMatches(rule, name, args) {
   return rule === name;
 }
 
+/** @param {any} rawMode @param {any} io */
 export function createPermission(rawMode, io) {
   let mode = 'ask';
   let allow = [];
@@ -52,8 +55,9 @@ export function createPermission(rawMode, io) {
 
   return {
     mode,
+    /** @param {any} name @param {any} args @param {any} label */
     async check(name, args = {}, label = '') {
-      const askOverride = async (question) => {
+      const askOverride = async (/** @type {any} */ question) => {
         try {
           const answer = await io.ask(style(question, C.yellow));
           return /^y(es)?$/i.test(answer);
@@ -63,10 +67,10 @@ export function createPermission(rawMode, io) {
       };
       // 需要特殊授权时弹出对话框与用户交互，而不是静默拒绝：
       // 1) 被 deny 规则拦截 → 询问是否本次强制放行
-      if (deny.some((r) => ruleMatches(r, name, args))) {
+      if (deny.some((/** @type {any} */ r) => ruleMatches(r, name, args))) {
         return askOverride(`规则拦截了 ${name}${summarize(name, args)}，是否本次强制放行？[y/N] `);
       }
-      if (allow.some((r) => ruleMatches(r, name, args))) return true;
+      if (allow.some((/** @type {any} */ r) => ruleMatches(r, name, args))) return true;
       if (mode === 'auto') return true;
       if (mode === 'readonly') {
         // 2) 只读模式下的写操作 → 询问是否本次放行

package/src/pricing.js

@@ -16,6 +16,7 @@ export const PRICE_DATA_AS_OF = '2026-08';
 // cfg.pricing.source 拉取（TTL 默认 7 天，cfg.pricing.ttlDays 可调）；TTL 内覆盖内置表，
 // 过期自动回退内置并置 stale 标记（/cost 与费用标签会提示）。
 function pricingFilePath() { return path.join(mingdaoHome(), 'pricing.json'); }
+/** @type {{ mtime: number, data: any, stale: boolean }} */
 let extCache = { mtime: -1, data: null, stale: false };
 function externalPricing() {
   try {
@@ -35,6 +36,9 @@ function externalPricing() {
 export function pricingDataStale() { return externalPricing().stale; }
 
 // 拉取官方价格表（零依赖 fetch）：cfg.pricing.source 为 JSON 地址，返回 { models: { <模型名>: { input, output, cacheHit, peak? } } }
+/**
+ * @param {any} cfg
+ */
 export async function refreshPricingFromSource(cfg) {
   const src = String(cfg?.pricing?.source || '').trim();
   if (!src) return { ok: false, lines: ['未配置 pricing.source（config.json 的 pricing.source 填官方价格 JSON 地址后重试）'] };
@@ -58,6 +62,7 @@ export async function refreshPricingFromSource(cfg) {
 // 用本机时区判断会让海外用户计费错位。config.pricing.timezone 可覆盖时区、
 // config.pricing.peakWindows 可覆盖高峰窗口（[[起,止],...] 北京时间整点），mtime 缓存避免每次读盘。
 const DEFAULT_PEAK_WINDOWS = [[9, 12], [14, 18]];
+/** @type {{ mtime: number, timezone: string, peakWindows: number[][], ttlDays?: number }} */
 let tzCache = { mtime: 0, timezone: 'Asia/Shanghai', peakWindows: DEFAULT_PEAK_WINDOWS };
 function peakCfg() {
   try {
@@ -116,11 +121,14 @@ export function beijingParts(date = new Date()) {
     second: '2-digit',
     hourCycle: 'h23',
   }).formatToParts(date);
-  const g = (t) => Number(parts.find((p) => p.type === t)?.value);
+  const g = /** @type {(t: any) => number} */ ((t) => Number(parts.find((p) => p.type === t)?.value));
   return { year: g('year'), month: g('month'), day: g('day'), hour: g('hour'), minute: g('minute'), second: g('second') };
 }
 
 // 北京时间墙钟 → Date（UTC+8）
+/**
+ * @param {any} parts
+ */
 export function beijingToDate(parts) {
   return new Date(Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second) - 8 * 3600 * 1000);
 }
@@ -153,6 +161,11 @@ export function beijingDayStart(date = new Date()) {
 
 // —— Batch API 半价计价：批量任务无缓存语义，按闲时全未命中 × 0.5 ——
 export const BATCH_DISCOUNT = 0.5;
+/**
+ * @param {any} modelName
+ * @param {any} promptTokens
+ * @param {any} completionTokens
+ */
 export function estimateBatchCost(modelName, promptTokens, completionTokens) {
   const pricing = effectivePricing(modelName);
   if (!pricing) return 0;
@@ -160,6 +173,9 @@ export function estimateBatchCost(modelName, promptTokens, completionTokens) {
 }
 
 // usage 中的缓存拆分（DeepSeek 返回字段）
+/**
+ * @param {any} usage
+ */
 export function cacheSplit(usage) {
   const hit = usage?.prompt_cache_hit_tokens;
   const miss = usage?.prompt_cache_miss_tokens;
@@ -170,6 +186,7 @@ export function cacheSplit(usage) {
 }
 
 // 合并内置价与用户覆盖：offpeak 字段覆盖 offpeak，over.peak 覆盖 peak（缺省沿用 offpeak）
+/** @type {{ mtime: number, overrides: Record<string, any> }} */
 let overridesCache = { mtime: 0, overrides: {} };
 function pricingOverrides() {
   try {
@@ -182,6 +199,9 @@ function pricingOverrides() {
   } catch {}
   return overridesCache.overrides;
 }
+/**
+ * @param {any} modelName
+ */
 function effectivePricing(modelName) {
   const preset = modelPreset(modelName);
   const ext = externalPricing().data?.models?.[modelName] || null;
@@ -189,6 +209,7 @@ function effectivePricing(modelName) {
   const base = ext || preset?.pricing || null;
   if (!base) return null;
   const over = pricingOverrides()[modelName] || {}; // 审计 Q3：mtime 缓存替代每轮读盘
+  /** @type {(b: any, o?: any) => { input: number, output: number, cacheHit: number }} */
   const merge = (b, o = {}) => ({
     input: Number(o.input ?? b?.input ?? 0),
     output: Number(o.output ?? b?.output ?? 0),
@@ -208,6 +229,13 @@ function effectivePricing(modelName) {
   };
 }
 
+/**
+ * @param {any} modelName
+ * @param {any} promptTokens
+ * @param {any} completionTokens
+ * @param {{ hit: number, miss: number, rate?: number } | null} [cache]
+ * @param {Date} [date]
+ */
 export function estimateCost(modelName, promptTokens, completionTokens, cache = null, date = new Date()) {
   const pricing = effectivePricing(modelName);
   if (!pricing) return 0;
@@ -221,6 +249,12 @@ export function estimateCost(modelName, promptTokens, completionTokens, cache =
   return (promptTokens * price.input + completionTokens * price.output) / 1e6;
 }
 
+/**
+ * @param {any} modelName
+ * @param {any} promptTokens
+ * @param {any} completionTokens
+ * @param {any} [usage]
+ */
 export function estimateCostLabel(modelName, promptTokens, completionTokens, usage = null) {
   const pricing = effectivePricing(modelName);
   if (!pricing) return '';

package/src/prompts.js

@@ -21,7 +21,7 @@ const BASE = `你是 MingDao Harness，一个由 MingDao Harness 驱动的 AI
 9. 善用工具：能用工具确认的事实就用工具确认；多个只读工具可连续调用以提高效率。
 10. 交付收尾：完成工具操作后必须给出简短交付总结——生成了哪些文件（路径）、如何运行/使用（如「浏览器打开 angry-birds.html 即可游玩」或运行命令）、以及未完成或注意事项（若有）。绝不能不声不响结束。`;
 
-function loadFile(p, cap) {
+function loadFile(/** @type {any} */ p, /** @type {any} */ cap) {
   try {
     const s = fs.readFileSync(p, 'utf8');
     return s.length > cap ? s.slice(0, cap) + '\n…[过长已截断]' : s;

package/src/providers/index.js

@@ -16,7 +16,7 @@ import { modelPreset, providerPreset } from '../models.js';
 import { mingdaoHome } from '../config.js';
 import { resolveApiKey } from '../credentials.js';
 
-export function resolveProviderConfig(cfg, modelName) {
+export function resolveProviderConfig(/** @type {any} */ cfg, /** @type {any} */ modelName) {
   // 自定义模型（config.customModels，WebUI 可增删改）：优先于内置预设
   const cm = cfg?.customModels?.[modelName];
   if (cm) {
@@ -47,16 +47,16 @@ export function resolveProviderConfig(cfg, modelName) {
   };
 }
 
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const sleep = (/** @type {any} */ ms) => new Promise((r) => setTimeout(r, ms));
 
-function isTransient(err) {
+function isTransient(/** @type {any} */ err) {
   const status = err?.status;
   if (status === 429 || (status >= 500 && status <= 504)) return true;
   // 注意：不含 abort —— 用户 Ctrl+C 主动中断不应触发重试
   return /timeout|超时|ECONNRESET|fetch failed/i.test(String(err?.message || ''));
 }
 
-export async function createProvider(cfg, modelName, { timeoutMs = 300000, retries = 2 } = {}) {
+export async function createProvider(/** @type {any} */ cfg, /** @type {any} */ modelName, { timeoutMs = 300000, retries = 2 } = {}) {
   const pc = resolveProviderConfig(cfg, modelName);
 
   // 自定义 Provider 模块优先（仅普通自定义端点；custom:<模型名> 走 OpenAI 兼容直连）
@@ -77,7 +77,7 @@ export async function createProvider(cfg, modelName, { timeoutMs = 300000, retri
   return {
     name: pc.name,
     config: pc,
-    async chat(opts) {
+    async chat(/** @type {any} */ opts) {
       let attempt = 0;
       for (;;) {
         const ac = new AbortController();
@@ -105,7 +105,7 @@ export async function createProvider(cfg, modelName, { timeoutMs = 300000, retri
           attempt += 1;
           // 指数退避 + 尊重 Retry-After（评估 P3-1）：基础 1s/2s，服务端指定时取其值（封顶 30s）
           let backoff = 1000 * attempt;
-          const ra = Number(err?.headers?.get?.('retry-after'));
+          const ra = Number((/** @type {any} */ (err))?.headers?.get?.('retry-after'));
           if (Number.isFinite(ra) && ra > 0) backoff = Math.max(backoff, ra * 1000);
           backoff = Math.min(backoff, 30000);
           await sleep(backoff);
@@ -121,7 +121,7 @@ export async function createProvider(cfg, modelName, { timeoutMs = 300000, retri
 // 辅助调用（标题生成/记忆提取等）的 provider 解析（评估 P2-2）：辅助模型与当前模型
 // 分属不同服务商时单独创建 provider——避免拿 deepseek-v4-flash 模型名去自定义网关请求
 // 而 404 被静默吞掉（标题缺失、记忆永不沉淀且零感知）。
-export async function helperProvider(cfg, helperModel, currentProvider) {
+export async function helperProvider(/** @type {any} */ cfg, /** @type {any} */ helperModel, /** @type {any} */ currentProvider) {
   try {
     const curName = String(currentProvider?.name || '');
     const helperName = String(resolveProviderConfig(cfg, helperModel)?.name || '');