mingdao-harness 0.2.3 → 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());
@@ -33,7 +33,7 @@ export async function handleUpdateFamily(cmd, args) {
     return true;
   }
 
-  // Batch API 半价批处理（A1）：mingdao batch <问题文件|-> [--model 名] [--max-tokens n]
+  // Batch API 半价批处理（A1/B2）：mingdao batch <问题文件|-> [--model 名] [--max-tokens n] [--max-cost 元]
   if (cmd === 'batch') {
     const { runBatch } = await import('../batch.js');
     const cfgB = loadConfig();
@@ -44,16 +44,18 @@ export async function handleUpdateFamily(cmd, args) {
     }
     let model = cfgB.model || 'deepseek-v4-flash';
     let maxTokens = 4096;
+    let maxCost = 0; // 省钱 B2：预算上限（元），提交前按估算拦截
     let srcFile = null;
     for (let i = 0; i < args.length; i++) {
       const a = args[i];
       if (a === '--model') model = args[++i];
       else if (a === '--max-tokens') maxTokens = Number(args[++i]) || 4096;
+      else if (a === '--max-cost') maxCost = Number(args[++i]) || 0;
       else if (a === '--out') { i += 1; /* 输出默认落工作目录 */ }
       else if (!srcFile) srcFile = a;
     }
     if (!srcFile) {
-      console.log('用法：mingdao batch <问题文件|-> 每行一个问题（--model 名 --max-tokens n）');
+      console.log('用法：mingdao batch <问题文件|-> 每行一个问题（--model 名 --max-tokens n --max-cost 元）');
       process.exitCode = 1;
       return true;
     }
@@ -62,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;
     }
@@ -80,8 +82,9 @@ export async function handleUpdateFamily(cmd, args) {
       questions,
       workingDir: process.cwd(),
       maxTokens,
+      maxCost,
       signal: ac.signal,
-      onStatus: (st) => console.log('  ' + st),
+      onStatus: (/** @type {any} */ st) => console.log('  ' + st),
     });
     process.removeAllListeners('SIGINT');
     if (r.error) {
@@ -89,7 +92,9 @@ 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 分账）`);
     return true;
@@ -115,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);
@@ -123,13 +128,21 @@ export async function handleUpdateFamily(cmd, args) {
       md.push('');
       md.push(`- 实际费用 ≈¥${r.cost.toFixed(5)}${r.batchCost > 0 ? `（含 Batch 半价任务 ≈¥${r.batchCost.toFixed(5)}）` : ''}`);
       md.push(`- 相比全未命中已节省 ≈¥${r.saved.toFixed(5)}${r.rate != null ? ` · 缓存命中率 ${(r.rate * 100).toFixed(0)}%` : ''}`);
-      md.push(`- Tokens：↑${r.prompt} / ↓${r.completion}`);
+      md.push(`- Tokens：↑${r.prompt} / ↓${r.completion}${r.reasoning ? ` · 推理 ${r.reasoning}` : ''}`);
       md.push('');
       md.push('## 按模型分账');
       md.push('');
       md.push('| 模型 | 轮次 | ↑prompt | ↓completion | 费用 |');
       md.push('| --- | --- | --- | --- | --- |');
       for (const m of r.models) md.push(`| ${m.model} | ${m.turns} | ${m.prompt} | ${m.completion} | ≈¥${m.cost.toFixed(5)} |`);
+      if (r.tools.length) {
+        md.push('');
+        md.push('## 按工具分账');
+        md.push('');
+        md.push('| 工具 | 调用 | 耗时(ms) |');
+        md.push('| --- | --- | --- |');
+        for (const t of r.tools.slice(0, 10)) md.push(`| ${t.tool} | ${t.calls} | ${t.ms} |`);
+      }
       md.push('');
       md.push('## 每日费用');
       md.push('');

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/cost-guard.js

@@ -1,7 +1,8 @@
 // 费用护栏（四报告共识 A2/Kimi P-1：把峰谷定价从「展示」升级为「主动约束」）：
-// config.costGuard = { dailyLimitYuan: 10, warnAtYuan: 8, action: 'warn'|'block' }
+// config.costGuard = { dailyLimitYuan: 10, warnAtYuan: 8, action: 'warn'|'block'|'downgrade', downgradeModel?: 'deepseek-v4-flash' }
 // 按北京时间自然日累计 cache-stats 实际费用（含 batch 半价与缓存折扣后的真实口径）。
-// Agent 每轮开始前检查：超 warn 线提醒、超 limit 且 action=block 时暂停执行。
+// Agent 每轮开始前检查：超 warn 线提醒；超 limit 时按 action 处理——
+//   block：暂停执行；downgrade（省钱 B4）：自动切换便宜模型继续跑（默认 deepseek-v4-flash）。
 
 import fs from 'node:fs';
 import { listCacheStats, cacheStatsFile } from './cachestats.js';
@@ -41,18 +42,19 @@ export function costGuardStatus() {
   const cost = todayCost();
   const limit = Number(g.dailyLimitYuan) || 0;
   const warnAt = Number(g.warnAtYuan) || (limit > 0 ? limit * 0.8 : 0);
-  const action = g.action === 'block' ? 'block' : 'warn';
+  const action = g.action === 'block' || g.action === 'downgrade' ? g.action : 'warn';
   return {
     cost,
     limit,
     warnAt,
     action,
+    downgradeModel: String(g.downgradeModel || 'deepseek-v4-flash'),
     overWarn: limit > 0 && cost >= warnAt,
     overLimit: limit > 0 && cost >= limit,
   };
 }
 
-// Agent 每轮开始前调用：返回 null 放行；blocked=true 表示应暂停本轮
+// Agent 每轮开始前调用：返回 null 放行；blocked=true 应暂停本轮；downgrade=true 应切换便宜模型
 export function checkCostGuard() {
   const st = costGuardStatus();
   if (!st) return null;
@@ -62,10 +64,18 @@ export function checkCostGuard() {
       message: `今日费用已达上限 ¥${st.limit.toFixed(2)}（实际 ¥${st.cost.toFixed(4)}），已暂停执行——调整 config.costGuard 或明天自动恢复。`,
     };
   }
+  if (st.overLimit && st.action === 'downgrade') {
+    return {
+      blocked: false,
+      downgrade: true,
+      downgradeModel: st.downgradeModel,
+      message: `⚠ 费用护栏：今日已用 ¥${st.cost.toFixed(4)} 超上限 ¥${st.limit.toFixed(2)}——已自动降级到便宜模型 ${st.downgradeModel} 继续执行（config.costGuard.action 可改回 warn/block）。`,
+    };
+  }
   if (st.overWarn) {
     return {
       blocked: false,
-      message: `⚠ 费用护栏：今日已用 ¥${st.cost.toFixed(4)} / 上限 ¥${st.limit.toFixed(2)}${st.action === 'block' ? '（到达即暂停）' : '（仅提醒）'}。`,
+      message: `⚠ 费用护栏：今日已用 ¥${st.cost.toFixed(4)} / 上限 ¥${st.limit.toFixed(2)}${st.action !== 'warn' ? `（${st.action === 'block' ? '到达即暂停' : '到达自动降级 ' + st.downgradeModel}）` : '（仅提醒）'}。`,
     };
   }
   return null;

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) {