mingdao-harness 0.2.4 → 0.2.5

package/src/commands/schedule.js

@@ -14,7 +14,7 @@ import {
 import { listTasks, killTask, formatTaskRow } from '../tasks.js';
 import { ensureHome } from '../config.js';
 
-function printTasks(home) {
+function printTasks(/** @type {any} */ home) {
   const tasks = listTasks(home);
   if (!tasks.length) {
     console.log('暂无任务。启动：mingdao run "<任务>"');
@@ -26,7 +26,7 @@ function printTasks(home) {
   console.log(running ? `\n${running} 个运行中 · mingdao tasks watch 实时刷新 · kill <id> 停止` : '\n无运行中任务');
 }
 
-async function watchTasks(home) {
+async function watchTasks(/** @type {any} */ home) {
   if (!process.stdout.isTTY) {
     printTasks(home);
     return;
@@ -45,7 +45,7 @@ async function watchTasks(home) {
   }
 }
 
-export async function handleTasks(cmd, args) {
+export async function handleTasks(/** @type {any} */ cmd, /** @type {any} */ args) {
   const home0 = ensureHome();
   reconcileSchedules(home0);
   const sub = args[0];
@@ -67,7 +67,7 @@ export async function handleTasks(cmd, args) {
   return true;
 }
 
-export async function handleSchedule(cmd, args) {
+export async function handleSchedule(/** @type {any} */ cmd, /** @type {any} */ args) {
   const home0 = ensureHome();
   reconcileSchedules(home0);
   const sub = args[0];
@@ -86,7 +86,7 @@ export async function handleSchedule(cmd, args) {
     let at = null;
     let every = null;
     let anchor = null;
-    let after = [];
+    let /** @type {any} */ after = [];
     let permission = null;
     let model = null;
     let offpeak = false;
@@ -106,7 +106,7 @@ export async function handleSchedule(cmd, args) {
       process.exitCode = 1;
       return true;
     }
-    const r = addSchedule(home0, question, { at, every, after, permission, model, cwd: process.cwd(), anchor, offpeak });
+    const r = addSchedule(home0, question, { at, every, /** @type {any} */ after, permission, model, cwd: process.cwd(), anchor, offpeak });
     if (r.error) {
       console.log('[错误] ' + r.error);
       process.exitCode = 1;
@@ -162,7 +162,7 @@ export async function handleSchedule(cmd, args) {
       process.exitCode = 1;
       return true;
     }
-    const r = chainSchedules(home0, rest);
+    const r = /** @type {any} */ (chainSchedules(home0, rest));
     if (r.error) {
       console.log('[错误] ' + r.error);
       process.exitCode = 1;

package/src/commands/skill.js

@@ -18,14 +18,14 @@ function askAutoStart() {
   });
 }
 
-export async function handleSkill(cmd, args) {
+export async function handleSkill(/** @type {any} */ cmd, /** @type {any} */ args) {
   const sub = args[0] || 'list';
   const arg = args[1];
   if (sub === 'search') {
     const local = searchLibrary(arg || '');
     const remote = await searchRegistry(arg || '');
     const localNames = new Set(local.map((s) => s.name));
-    const remoteOnly = remote.skills ? remote.skills.filter((s) => !localNames.has(s.name)) : [];
+    const remoteOnly = remote.skills ? remote.skills.filter((/** @type {any} */ s) => !localNames.has(s.name)) : [];
     console.log(
       `技能库匹配：内置 ${local.length}${remote.error ? '' : ` + 线上 ${remoteOnly.length}`} · 安装：mingdao skill install <名称>`
     );
@@ -41,15 +41,17 @@ export async function handleSkill(cmd, args) {
   if (sub === 'install') {
     const r = await installSkill(arg);
     if (r.error) {
-      console.log('[错误] ' + r.error);
+      console.log('[错误] ' + (/** @type {any} */ (r)).error);
       process.exitCode = 1;
       return true;
     }
-    if (r.names) {
-      console.log(`✓ 已从 git 仓库安装 ${r.names.length} 个技能：${r.names.join(', ')}`);
+    if ((/** @type {any} */ (r)).names) {
+      const rn = /** @type {any} */ (r);
+      console.log(`✓ 已从 git 仓库安装 ${rn.names.length} 个技能：${rn.names.join(', ')}`);
     } else {
-      const srcLabel = r.host ? '（线上 registry）' : '';
-      console.log(`✓ 已安装技能 ${r.name}${srcLabel} → ~/.mingdao/skills/${r.name}/（可编辑/删除，下次会话生效）`);
+      const rn = /** @type {any} */ (r);
+      const srcLabel = rn.host ? '（线上 registry）' : '';
+      console.log(`✓ 已安装技能 ${rn.name}${srcLabel} → ~/.mingdao/skills/${rn.name}/（可编辑/删除，下次会话生效）`);
     }
     return true;
   }
@@ -61,7 +63,7 @@ export async function handleSkill(cmd, args) {
     }
     const r = uninstallSkill(arg);
     if (r.error) {
-      console.log('[错误] ' + r.error);
+      console.log('[错误] ' + (/** @type {any} */ (r)).error);
       process.exitCode = 1;
       return true;
     }
@@ -76,11 +78,11 @@ export async function handleSkill(cmd, args) {
     }
     const r = await reinstallSkill(arg);
     if (r.error) {
-      console.log('[错误] ' + r.error);
+      console.log('[错误] ' + (/** @type {any} */ (r)).error);
       process.exitCode = 1;
       return true;
     }
-    console.log(`✓ 已更新技能 ${r.name}`);
+    console.log(`✓ 已更新技能 ${(/** @type {any} */ (r)).name}`);
     return true;
   }
   if (sub === 'trust') {
@@ -91,7 +93,7 @@ export async function handleSkill(cmd, args) {
     }
     const r = trustSkill(arg);
     if (r.error) {
-      console.log('[错误] ' + r.error);
+      console.log('[错误] ' + (/** @type {any} */ (r)).error);
       process.exitCode = 1;
       return true;
     }
@@ -116,7 +118,7 @@ export async function handleSkill(cmd, args) {
 // WebUI：mingdao web [端口] [--auth-token <令牌>] [--autostart|--no-autostart]（评估 P3-1：参数结构不合法的按提问处理）
 // --autostart/--no-autostart：写 config.web.autoStart——开启后每次运行 mingdao 会自动后台拉起 WebUI；
 // 首次交互运行且未设置时，询问一次「下次是否自动启动」。
-export async function handleWeb(cmd, args) {
+export async function handleWeb(/** @type {any} */ cmd, /** @type {any} */ args) {
   let portIndex = -1;
   let tokenSeen = false;
   let autoChoice; // undefined=未指定；true/false=显式指定
@@ -165,7 +167,7 @@ export async function handleWeb(cmd, args) {
   const host = cfg0?.web?.host || '127.0.0.1';
   // 访问令牌优先级：--auth-token 参数 > 环境变量 MINGDAO_WEB_TOKEN > config.json 的 web.token
   let authToken = process.env.MINGDAO_WEB_TOKEN || cfg0?.web?.token || undefined;
-  const atIdx = args.findIndex((a) => typeof a === 'string' && a.startsWith('--auth-token'));
+  const atIdx = args.findIndex((/** @type {any} */ a) => typeof a === 'string' && a.startsWith('--auth-token'));
   if (atIdx !== -1) {
     const raw = args[atIdx];
     authToken = raw.includes('=') ? raw.slice(raw.indexOf('=') + 1) : args[atIdx + 1];
@@ -179,14 +181,14 @@ export async function handleWeb(cmd, args) {
     await runWebServer({ host, port, authToken });
   } catch (err) {
     // 质检 C2：listen 现在会 reject（如端口占用），CLI 给出明确提示而非挂起
-    console.error(`[MingDao] WebUI 启动失败：${err?.message || err}`);
+    console.error(`[MingDao] WebUI 启动失败：${(/** @type {any} */ (err))?.message || err}`);
     process.exitCode = 1;
   }
   return true;
 }
 
 // 会话检索：mingdao sessions search <关键词>
-export async function handleSessions(cmd, args) {
+export async function handleSessions(/** @type {any} */ cmd, /** @type {any} */ args) {
   if (args[0] !== 'search') return false;
   const kw = args.slice(1).join(' ').trim();
   if (!kw) {
@@ -200,7 +202,7 @@ export async function handleSessions(cmd, args) {
   else {
     console.log(`找到 ${hits.length} 个会话：`);
     for (const h of hits) {
-      console.log(`  ${h.name}（${relativeTime(h.mtime)}）\n    ${h.snippet}`);
+      console.log(`  ${h.name}（${relativeTime(h.mtime)}）\n    ${(/** @type {any} */ (h)).snippet}`);
     }
     console.log(`\n恢复：mingdao --resume（选择器中可见全部会话）`);
   }

package/src/commands/sync.js

@@ -16,13 +16,13 @@ import {
   resolveSyncConflict,
 } from '../sync.js';
 
-async function askHidden(question) {
+async function askHidden(/** @type {any} */ question) {
   return new Promise((resolve) => {
     // _writeToOutput 为 readline 内部接口：静音回显（密码输入），类型护栏下显式 any
     const rl = /** @type {any} */ (readline.createInterface({ input: process.stdin, output: process.stdout }));
     const orig = rl._writeToOutput;
     rl._writeToOutput = () => {};
-    rl.question(question, (a) => {
+    rl.question(question, (/** @type {any} */ a) => {
       if (typeof orig === 'function') rl._writeToOutput = orig;
       rl.close();
       resolve(a.trim());
@@ -30,7 +30,7 @@ async function askHidden(question) {
   });
 }
 
-export async function handleSync(cmd, args) {
+export async function handleSync(/** @type {any} */ cmd, /** @type {any} */ args) {
   const sub = args[0] || 'status';
   if (sub === 'login') {
     const username = args[1];
@@ -191,7 +191,7 @@ export async function handleSync(cmd, args) {
     return true;
   }
   if (sub === 'push') {
-    const r = await syncPush(args[1]);
+    const r = /** @type {any} */ (await syncPush(args[1]));
     if (r.error) {
       console.log('[错误] ' + r.error);
       process.exitCode = 1;
@@ -201,7 +201,7 @@ export async function handleSync(cmd, args) {
     return true;
   }
   if (sub === 'pull') {
-    const r = await syncPull(args[1]);
+    const r = /** @type {any} */ (await syncPull(args[1]));
     if (r.error) {
       console.log('[错误] ' + r.error);
       process.exitCode = 1;

package/src/commands/update.js

@@ -4,7 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { loadConfig } from '../config.js';
 
-export async function handleUpdateFamily(cmd, args) {
+export async function handleUpdateFamily(/** @type {any} */ cmd, /** @type {any} */ args) {
   // 价格表外置刷新（Hermes C1）：mingdao update --pricing —— 从 cfg.pricing.source 拉取官方价格 JSON
   if (cmd === 'update' && args.includes('--pricing')) {
     const cfg = loadConfig();
@@ -17,7 +17,7 @@ export async function handleUpdateFamily(cmd, args) {
   }
   // 自更新与回滚（git 安装形态）。
   // 评估 P3-1 子命令劫持防护：参数不合法时回退为普通提问（如 "mingdao update the docs" 是提问而非更新命令）
-  if (cmd === 'update' && args.every((a) => a === '--check')) {
+  if (cmd === 'update' && args.every((/** @type {any} */ a) => a === '--check')) {
     const { updateCheck, mingdaoUpdate } = await import('../update.js');
     const checkOnly = args.includes('--check');
     const r = await (checkOnly ? updateCheck() : mingdaoUpdate());
@@ -64,7 +64,7 @@ export async function handleUpdateFamily(cmd, args) {
       const raw = srcFile === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(srcFile, 'utf8');
       questions = raw.split(/\r?\n/).map((l) => l.trim()).filter(Boolean).slice(0, 1000);
     } catch (err) {
-      console.log('[错误] 读取问题文件失败：' + (err?.message || err));
+      console.log('[错误] 读取问题文件失败：' + ((/** @type {any} */ (err))?.message || err));
       process.exitCode = 1;
       return true;
     }
@@ -84,7 +84,7 @@ export async function handleUpdateFamily(cmd, args) {
       maxTokens,
       maxCost,
       signal: ac.signal,
-      onStatus: (st) => console.log('  ' + st),
+      onStatus: (/** @type {any} */ st) => console.log('  ' + st),
     });
     process.removeAllListeners('SIGINT');
     if (r.error) {
@@ -92,7 +92,8 @@ export async function handleUpdateFamily(cmd, args) {
       process.exitCode = 1;
       return true;
     }
-    console.log(`✓ 完成 ${r.results.length} 条 · ↑${r.usage.prompt_tokens} ↓${r.usage.completion_tokens} tokens · 费用 ≈¥${r.cost.toFixed(5)}（已按半价）`);
+    const rr = /** @type {any} */ (r);
+    console.log(`✓ 完成 ${rr.results.length} 条 · ↑${rr.usage.prompt_tokens} ↓${rr.usage.completion_tokens} tokens · 费用 ≈¥${rr.cost.toFixed(5)}（已按半价）`);
     if (r.deduped) console.log(`  （去重合并 ${r.deduped} 条重复问题，结果已回填全部位置）`);
     console.log(`  结果文件：${r.outputFile}`);
     console.log(`  任务 ID：${r.batchId}（结果已计入 /cost 分账）`);
@@ -119,7 +120,7 @@ export async function handleUpdateFamily(cmd, args) {
       console.log('月度报告导出：mingdao cost report [YYYY-MM|all]');
       return true;
     }
-    const bar = (cost, max) => '█'.repeat(Math.max(1, Math.round((cost / max) * 20)));
+    const bar = (/** @type {any} */ cost, /** @type {any} */ max) => '█'.repeat(Math.max(1, Math.round((cost / max) * 20)));
     const md = [];
     for (const r of rows) {
       const maxDay = Math.max(...r.days.map((d) => d.cost), 1e-9);

package/src/commands/workspace.js

@@ -3,7 +3,7 @@ import { addWorkspace, listWorkspaces, removeWorkspace, workspacePath, touchWork
 import { presetList, buildPreset } from '../mcp-presets.js';
 import { ensureHome, loadConfig, saveConfig } from '../config.js';
 
-export async function handleWorkspace(cmd, args) {
+export async function handleWorkspace(/** @type {any} */ cmd, /** @type {any} */ args) {
   const sub = args[0] || 'list';
   const name = args[1];
   if (sub === 'add') {
@@ -73,7 +73,7 @@ export async function handleWorkspace(cmd, args) {
 }
 
 // MCP 预设：mingdao mcp preset list|add <名称> [参数]
-export async function handleMcp(cmd, args) {
+export async function handleMcp(/** @type {any} */ cmd, /** @type {any} */ args) {
   if (args[0] !== 'preset') return false;
   const home0 = ensureHome();
   if (args[1] === 'add') {

package/src/compact.js

@@ -23,7 +23,7 @@ const SUMMARY_SYSTEM =
   '保留用户目标与关键要求、已完成的步骤与结论、修改/创建的文件、未完成事项、重要约定与决策；' +
   '省略已完成的中间过程与细节。只输出 JSON：{"summary": "摘要内容"}。';
 
-export async function summarizeConversation(provider, model, convoText) {
+export async function summarizeConversation(/** @type {any} */ provider, /** @type {any} */ model, /** @type {any} */ convoText) {
   const base = {
     model,
     messages: [
@@ -54,7 +54,7 @@ export async function summarizeConversation(provider, model, convoText) {
   return { text: text.slice(0, SUMMARY_MAX_CHARS), usage };
 }
 
-export async function compactConversation({ messages, budget, count, provider, executorModel, triggerRatio, force = false }) {
+export async function compactConversation(/** @type {any} */ { messages, budget, count, provider, executorModel, triggerRatio, force = false }) {
   if (!messages.length) return null;
   // 各消息 token 与总量；低于触发线（默认预算 80%）无需压缩
   const sizes = [];
@@ -85,14 +85,14 @@ export async function compactConversation({ messages, budget, count, provider, e
   // 被裁段落 → 文本（工具结果截断；tool_calls 带名称标注）
   const convoText = messages
     .slice(1, boundary)
-    .map((m) => {
+    .map((/** @type {any} */ m) => {
       if (m.role === 'tool') {
         return `工具结果(${m.tool_call_id ?? ''}): ${clampText(String(m.content ?? ''), TOOL_OUTPUT_CAP)}`;
       }
       const head = m.role === 'user' ? '用户' : m.role === 'assistant' ? 'MingDao' : String(m.role);
       const calls =
         Array.isArray(m.tool_calls) && m.tool_calls.length
-          ? ` [调用: ${m.tool_calls.map((tc) => `${tc.function?.name ?? ''}(${String(tc.function?.arguments ?? '').slice(0, 200)})`).join('; ')}]`
+          ? ` [调用: ${m.tool_calls.map((/** @type {any} */ tc) => `${tc.function?.name ?? ''}(${String(tc.function?.arguments ?? '').slice(0, 200)})`).join('; ')}]`
           : '';
       return `${head}: ${String(m.content ?? '')}${calls}`;
     })
@@ -102,7 +102,7 @@ export async function compactConversation({ messages, budget, count, provider, e
   // —— 增量压缩（Kimi P2-D）：已压缩过的会话只压「旧摘要之后的新增段」，与旧摘要合并（摘要的摘要），
   // 不再反复把早期内容送进摘要输入——第 N 次压缩输入从 O(历史) 降为 O(增量)。 ——
   const sumIdx = messages.findIndex(
-    (m) => m.role === 'user' && typeof m.content === 'string' && m.content.includes('<conversation_summary>')
+    (/** @type {any} */ m) => m.role === 'user' && typeof m.content === 'string' && m.content.includes('<conversation_summary>')
   );
   let incremental = false;
   let summary = null;
@@ -113,7 +113,7 @@ export async function compactConversation({ messages, budget, count, provider, e
     const oldSummary = (m && m[1]) || '';
     const newText = messages
       .slice(sumIdx + 1, boundary)
-      .map((msg) => {
+      .map((/** @type {any} */ msg) => {
         if (msg.role === 'tool') {
           return `工具结果(${msg.tool_call_id ?? ''}): ${clampText(String(msg.content ?? ''), TOOL_OUTPUT_CAP)}`;
         }

package/src/config.js

@@ -54,6 +54,7 @@ export function ensureMinimalConfig() {
   return cfg;
 }
 
+/** @param {any} cfg */
 export function saveConfig(cfg) {
   ensureHome();
   const p = configPath();
@@ -63,10 +64,12 @@ export function saveConfig(cfg) {
   } catch {}
 }
 
+/** @param {any} cfg @param {any} providerName */
 export function effectiveApiKey(cfg, providerName) {
   return resolveApiKey(cfg, providerName, providerPreset(providerName)?.envKey);
 }
 
+/** @param {any} io */
 export async function runWizard(io) {
   io.box('MingDao Harness 初始化向导', ['① 选服务商 → ② 填 API Key（自动验证）→ ③ 选模型（可跳过）']);
   io.print('');
@@ -74,9 +77,9 @@ export async function runWizard(io) {
   const providerKeys = Object.keys(PROVIDERS);
   const provider = await io.choose(
     '① 选择模型服务商：',
-    providerKeys.map((k) => ({ value: k, label: `${k} — ${PROVIDERS[k].label}` }))
+    providerKeys.map((k) => ({ value: k, label: `${k} — ${/** @type {Record<string, any>} */ (PROVIDERS)[k].label}` }))
   );
-  const pp = PROVIDERS[provider];
+  const pp = /** @type {Record<string, any>} */ (PROVIDERS)[provider];
 
   let baseUrl = '';
   if (provider === 'custom') {
@@ -163,13 +166,13 @@ export async function runWizard(io) {
   const contextBudget = Number(budgetInput) > 0 ? Number(budgetInput) : defaultBudget;
 
   // 注意：config.json 不含任何密钥（可安全分享/提交），密钥只存 credentials.json。
-  const cfg = {
+  const cfg = /** @type {any} */ ({
     provider,
     baseUrl: baseUrl || pp.baseUrl,
     permission: perm,
     sandbox,
     contextBudget,
-  };
+  });
   if (model) cfg.model = model;
   if (routing) cfg.routing = routing;
   saveConfig(cfg);

package/src/context.js

@@ -6,11 +6,11 @@ import { heuristicTokens } from './tokenizer.js';
 export const TOOL_RESULT_LIMIT = 20000;
 
 // 兼容旧接口的启发式估算（英文≈4 字符/token，CJK≈1 字符/token）
-export function approxTokens(text) {
+export function approxTokens(/** @type {any} */ text) {
   return heuristicTokens(text);
 }
 
-function partTokens(msg, count) {
+function partTokens(/** @type {any} */ msg, /** @type {any} */ count) {
   let total = count(msg.content || '');
   for (const tc of msg.tool_calls || []) {
     total += count(JSON.stringify(tc));
@@ -24,7 +24,7 @@ function partTokens(msg, count) {
 // 模型切换（新计数器）后自动失效重算。
 const messageTokenCache = new WeakMap();
 
-export function messageTokens(msg, count = approxTokens) {
+export function messageTokens(/** @type {any} */ msg, count = approxTokens) {
   const hit = messageTokenCache.get(msg);
   if (hit && hit.fn === count) return hit.value;
   const total = partTokens(msg, count) + 4; // 每条消息的协议开销
@@ -35,20 +35,20 @@ export function messageTokens(msg, count = approxTokens) {
 // 从尾部向前保留消息，直到预算用尽；始终保留首条 system 消息。
 // 裁剪可能切断 assistant(tool_calls) ↔ tool 的配对，清洗掉孤立消息，
 // 否则 OpenAI 兼容 API 会因 tool_call_id 找不到对应调用而报 400。
-export function cleanToolPairing(kept) {
+export function cleanToolPairing(/** @type {any} */ kept) {
   const callIds = new Set();
   for (const m of kept) {
     if (m.role === 'assistant' && Array.isArray(m.tool_calls)) {
       for (const tc of m.tool_calls) if (tc?.id) callIds.add(tc.id);
     }
   }
-  const clean = kept.filter((m) => m.role !== 'tool' || callIds.has(m.tool_call_id));
-  const toolIds = new Set(clean.filter((m) => m.role === 'tool').map((m) => m.tool_call_id));
+  const clean = kept.filter((/** @type {any} */ m) => m.role !== 'tool' || callIds.has(m.tool_call_id));
+  const toolIds = new Set(clean.filter((/** @type {any} */ m) => m.role === 'tool').map((/** @type {any} */ m) => m.tool_call_id));
   // 注意：裁剪是每次请求的投影，绝不能改写调用方 messages 里的原对象
   // （否则会话历史被永久污染：assistant 消息丢失 tool_calls，下一轮 API 报 400）
-  return clean.map((m) => {
+  return clean.map((/** @type {any} */ m) => {
     if (m.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length) {
-      const keptCalls = m.tool_calls.filter((tc) => toolIds.has(tc.id));
+      const keptCalls = m.tool_calls.filter((/** @type {any} */ tc) => toolIds.has(tc.id));
       if (keptCalls.length !== m.tool_calls.length) {
         if (keptCalls.length) return { ...m, tool_calls: keptCalls };
         const copy = { ...m };
@@ -60,12 +60,12 @@ export function cleanToolPairing(kept) {
   });
 }
 
-export function trimMessages(messages, budget, count = approxTokens) {
+export function trimMessages(/** @type {any} */ messages, /** @type {any} */ budget, count = approxTokens) {
   if (!messages.length) return [];
   const hasSystem = messages[0]?.role === 'system';
   const system = hasSystem ? [messages[0]] : [];
   const rest = hasSystem ? messages.slice(1) : messages;
-  const totalOf = (arr) => arr.reduce((s, m) => s + messageTokens(m, count), 0);
+  const totalOf = (/** @type {any} */ arr) => arr.reduce((/** @type {any} */ s, /** @type {any} */ m) => s + messageTokens(m, count), 0);
   // —— 轻量语义回收（Hermes B1）：预算 >80% 时先对最老消息做无模型压缩 ——
   // 最老 tool 消息 → 单行摘要；老 assistant 长文 → 前 200 字；逐条向新推进直到回到 80% 线。
   // 相比直接丢弃，被修改的只有前端旧消息——其后未被触碰的近期尾部字节保持不变，
@@ -104,7 +104,7 @@ export function trimMessages(messages, budget, count = approxTokens) {
   return cleanToolPairing(system.concat(rest));
 }
 
-export function clampText(text, maxChars = TOOL_RESULT_LIMIT) {
+export function clampText(/** @type {any} */ text, maxChars = TOOL_RESULT_LIMIT) {
   const s = String(text);
   if (s.length <= maxChars) return s;
   return s.slice(0, maxChars) + `\n…[输出过长已截断，原文共 ${s.length} 字符]`;

package/src/credentials.js

@@ -24,6 +24,7 @@ export function loadCredentials() {
   }
 }
 
+/** @param {any} creds */
 export function saveCredentials(creds) {
   ensureHome();
   const p = credentialsPath();
@@ -34,10 +35,12 @@ export function saveCredentials(creds) {
   } catch {}
 }
 
+/** @param {any} providerName */
 export function getStoredKey(providerName) {
   return loadCredentials()[providerName] || null;
 }
 
+/** @param {any} providerName @param {any} key */
 export function setStoredKey(providerName, key) {
   const creds = loadCredentials();
   if (key) creds[providerName] = String(key);
@@ -45,11 +48,13 @@ export function setStoredKey(providerName, key) {
   saveCredentials(creds);
 }
 
+/** @param {any} providerName */
 export function removeStoredKey(providerName) {
   setStoredKey(providerName, null);
 }
 
 // 脱敏展示：只显示首 6 位与末 4 位，永不输出完整 Key。
+/** @param {any} key */
 export function maskKey(key) {
   if (!key) return null;
   const s = String(key);
@@ -58,6 +63,7 @@ export function maskKey(key) {
 }
 
 // 统一的 Key 解析链：环境变量 → 本地凭证库 → config.json 显式字段
+/** @param {any} cfg @param {any} providerName @param {any} envKeyHint */
 export function resolveApiKey(cfg, providerName, envKeyHint) {
   const envKeys = [envKeyHint, 'MINGDAO_API_KEY'].filter((k, i, a) => k && a.indexOf(k) === i);
   for (const k of envKeys) {

package/src/hooks.js

@@ -10,12 +10,12 @@
 
 import { spawn } from 'node:child_process';
 
-function normalize(list) {
+function normalize(/** @type {any} */ list) {
   if (!Array.isArray(list)) return [];
   return list.filter((h) => h && typeof h.cmd === 'string' && h.cmd.trim());
 }
 
-function match(hook, toolName) {
+function match(/** @type {any} */ hook, /** @type {any} */ toolName) {
   const m = String(hook.matcher || '*').trim();
   if (!m || m === '*') return true;
   return m.split(',').some((part) => {
@@ -25,11 +25,11 @@ function match(hook, toolName) {
   });
 }
 
-export function createHooks(hooksCfg = {}, workingDir) {
-  const pre = normalize(hooksCfg?.PreToolUse);
-  const post = normalize(hooksCfg?.PostToolUse);
+export function createHooks(hooksCfg = {}, /** @type {any} */ workingDir) {
+  const pre = normalize((/** @type {any} */ (hooksCfg))?.PreToolUse);
+  const post = normalize((/** @type {any} */ (hooksCfg))?.PostToolUse);
 
-  function run(hook, payload) {
+  function run(/** @type {any} */ hook, /** @type {any} */ payload) {
     return new Promise((resolve) => {
       const child = spawn(hook.cmd, {
         shell: true,
@@ -40,12 +40,12 @@ export function createHooks(hooksCfg = {}, workingDir) {
       let out = '';
       let err = '';
       const MAX_HOOK_OUT = 64 * 1024;
-      const cap = (acc, d) => {
+      const cap = (/** @type {any} */ acc, /** @type {any} */ d) => {
         const t = acc + d;
         return t.length > MAX_HOOK_OUT ? t.slice(-MAX_HOOK_OUT) : t;
       };
       let settled = false;
-      const finish = (result) => {
+      const finish = (/** @type {any} */ result) => {
         if (settled) return;
         settled = true;
         resolve(result);
@@ -53,7 +53,7 @@ export function createHooks(hooksCfg = {}, workingDir) {
       const timer = setTimeout(() => {
         // 审计质量项：超时杀整组（shell:true 的孙进程不成孤儿）
         try {
-          process.kill(-child.pid, 'SIGKILL');
+          process.kill(-(/** @type {any} */ (child)).pid, 'SIGKILL');
         } catch {
           child.kill('SIGKILL');
         }
@@ -77,7 +77,7 @@ export function createHooks(hooksCfg = {}, workingDir) {
   }
 
   return {
-    async pre(toolName, args) {
+    async pre(/** @type {any} */ toolName, /** @type {any} */ args) {
       let decision = 'approve';
       let reason = '';
       for (const h of pre) {
@@ -106,7 +106,7 @@ export function createHooks(hooksCfg = {}, workingDir) {
       }
       return { decision, reason };
     },
-    async post(toolName, args, result) {
+    async post(/** @type {any} */ toolName, /** @type {any} */ args, /** @type {any} */ result) {
       for (const h of post) {
         if (!match(h, toolName)) continue;
         try {

package/src/mcp-presets.js

@@ -57,22 +57,22 @@ export function presetList() {
   return Object.entries(MCP_PRESETS).map(([name, p]) => ({
     name,
     label: p.label,
-    argLabel: p.argLabel || null,
+    argLabel: (/** @type {any} */ (p)).argLabel || null,
     args: p.args,
     command: p.command,
   }));
 }
 
-export function buildPreset(name, arg, cwd) {
-  const p = MCP_PRESETS[name];
+export function buildPreset(/** @type {any} */ name, /** @type {any} */ arg, /** @type {any} */ cwd) {
+  const p = /** @type {any} */ (MCP_PRESETS)[name];
   if (!p) return { error: `未知预设 ${name}（mingdao mcp preset list 查看）` };
-  if (p.argLabel && !arg) {
+  if ((/** @type {any} */ (p)).argLabel && !arg) {
     if (p.args.includes('{dir}')) {
       arg = cwd; // 目录类参数默认当前工作目录
     } else {
       return { error: `该预设需要参数：${p.argLabel}` };
     }
   }
-  const args = p.args.map((a) => (a === '{dir}' ? arg : a));
+  const args = p.args.map((/** @type {any} */ a) => (a === '{dir}' ? arg : a));
   return { config: { command: p.command, args } };
 }