mingdao-harness 0.2.4 → 0.2.6

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,25 +60,37 @@ 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);
-  // —— 轻量语义回收（Hermes B1）：预算 >80% 时先对最老消息做无模型压缩 ——
-  // 最老 tool 消息 → 单行摘要；老 assistant 长文 → 前 200 字；逐条向新推进直到回到 80% 线。
-  // 相比直接丢弃，被修改的只有前端旧消息——其后未被触碰的近期尾部字节保持不变，
-  // 下一轮前缀缓存从首个未修改消息起继续命中（直接丢弃反而让整段前缀失配）。
-  // 质检 M10：维护增量 total（替换消息后按新旧 token 差调整），不再每步全量重算（原 ≤500×n）。
+  const totalOf = (/** @type {any} */ arr) => arr.reduce((/** @type {any} */ s, /** @type {any} */ m) => s + messageTokens(m, count), 0);
+  // —— 轻量语义回收（Hermes B1 + workbuddy P0-1 修正）——
+  // 只在「真的超预算」时回收（此前 >80% 即动手，能塞下的会话也被白白截断丢内容）；
+  // 回收边界 = 按尾部保留规则确定将被丢弃的前缀（此前固定扫前 500 条，超长会话时回收全白做）；
+  // 替换仅当摘要确实更短才接受（防短消息被摘要撑长）。
   const sysTokens = totalOf(system);
   let total = sysTokens + totalOf(rest);
-  if (total > budget * 0.8) {
+  if (total > budget) {
     const out = [...rest];
-    for (let i = 0; i < out.length && i < 500; i++) {
-      if (total <= budget * 0.8) break;
+    // 丢弃边界：从后往前贪心，确定尾部保留起点 s（s 之前的消息将被丢弃，只对它们回收）
+    let s = out.length;
+    {
+      let acc = sysTokens;
+      for (let i = out.length - 1; i >= 0; i--) {
+        const t = messageTokens(out[i], count);
+        if (acc + t > budget) { s = i + 1; break; }
+        acc += t;
+      }
+    }
+    for (let i = 0; i < s && i < 500; i++) {
+      if (total <= budget) break;
       const m = out[i];
       const c = typeof m.content === 'string' ? m.content : JSON.stringify(m?.content ?? '');
+      // 幂等守卫（A4）：已回收过的内容跳过——否则「截断标记」把长度再次顶过阈值，逐轮嵌套重截，
+      // 被保留消息字节逐轮漂移（前缀缓存连尾部都失配）
+      if (c.includes('已回收')) continue;
       let next = null;
       if (m.role === 'tool' && c.length > 40) {
         next = { ...m, content: `[工具 ${m.tool_call_id || ''} 结果摘要：${c.slice(0, 40).replace(/\n/g, ' ')}…（已回收，原 ${c.length} 字）]` };
@@ -86,8 +98,12 @@ export function trimMessages(messages, budget, count = approxTokens) {
         next = { ...m, content: c.slice(0, 200) + ` …[已回收，原 ${c.length} 字]` };
       }
       if (next) {
-        total += messageTokens(next, count) - messageTokens(m, count);
-        out[i] = next;
+        const oldT = messageTokens(m, count);
+        const newT = messageTokens(next, count);
+        if (newT < oldT) {
+          total += newT - oldT;
+          out[i] = next;
+        }
       }
     }
     // 回收后仍超预算 → 从尾部保留（必要时继续丢弃最老，清洗 tool 配对）
@@ -104,7 +120,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

@@ -32,9 +32,15 @@ export function todayCost() {
     todayCache = { mtime: st.mtimeMs, size: st.size, start, sum };
     return sum;
   } catch {
-    return 0;
+    // MiniMax P0：统计文件损坏/不可读时返回 null（护栏全部失效）而不是静默 0——并一次性告警
+    if (!todayCostWarned) {
+      todayCostWarned = true;
+      console.warn('[MingDao] 费用统计读取失败：今日费用护栏暂时无法判断（修复 cache-stats.jsonl 或重启后恢复）。');
+    }
+    return null;
   }
 }
+let todayCostWarned = false;
 
 export function costGuardStatus() {
   const g = costGuardConfig();
@@ -49,8 +55,9 @@ export function costGuardStatus() {
     warnAt,
     action,
     downgradeModel: String(g.downgradeModel || 'deepseek-v4-flash'),
-    overWarn: limit > 0 && cost >= warnAt,
-    overLimit: limit > 0 && cost >= limit,
+    degraded: cost === null, // 统计不可读：护栏降级为「无法判断」
+    overWarn: cost !== null && limit > 0 && cost >= warnAt,
+    overLimit: cost !== null && limit > 0 && cost >= limit,
   };
 }
 
@@ -58,10 +65,11 @@ export function costGuardStatus() {
 export function checkCostGuard() {
   const st = costGuardStatus();
   if (!st) return null;
+  if (st.degraded) return null; // 统计不可读：不误拦也不放水（已告警），按无法判断处理
   if (st.overLimit && st.action === 'block') {
     return {
       blocked: true,
-      message: `今日费用已达上限 ¥${st.limit.toFixed(2)}（实际 ¥${st.cost.toFixed(4)}），已暂停执行——调整 config.costGuard 或明天自动恢复。`,
+      message: `今日费用已达上限 ¥${st.limit.toFixed(2)}（实际 ¥${(st.cost ?? 0).toFixed(4)}），已暂停执行——调整 config.costGuard 或明天自动恢复。`,
     };
   }
   if (st.overLimit && st.action === 'downgrade') {
@@ -69,13 +77,13 @@ export function checkCostGuard() {
       blocked: false,
       downgrade: true,
       downgradeModel: st.downgradeModel,
-      message: `⚠ 费用护栏：今日已用 ¥${st.cost.toFixed(4)} 超上限 ¥${st.limit.toFixed(2)}——已自动降级到便宜模型 ${st.downgradeModel} 继续执行（config.costGuard.action 可改回 warn/block）。`,
+      message: `⚠ 费用护栏：今日已用 ¥${(st.cost ?? 0).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 !== 'warn' ? `（${st.action === 'block' ? '到达即暂停' : '到达自动降级 ' + st.downgradeModel}）` : '（仅提醒）'}。`,
+      message: `⚠ 费用护栏：今日已用 ¥${(st.cost ?? 0).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) {