mingdao-harness 0.1.54

package/src/commands/update.js

@@ -0,0 +1,157 @@
+// 命令族：mingdao update / rollback / batch / cost / audit（自 cli.js 拆出，评估 P0-1 拆包）
+// 每个 handler 返回 true 表示已处理（主流程 return）；false 表示按普通提问继续（子命令劫持防护）。
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig } from '../config.js';
+
+export async function handleUpdateFamily(cmd, args) {
+  // 自更新与回滚（git 安装形态）。
+  // 评估 P3-1 子命令劫持防护：参数不合法时回退为普通提问（如 "mingdao update the docs" 是提问而非更新命令）
+  if (cmd === 'update' && args.every((a) => a === '--check')) {
+    const { updateCheck, mingdaoUpdate } = await import('../update.js');
+    const checkOnly = args.includes('--check');
+    const r = await (checkOnly ? updateCheck() : mingdaoUpdate());
+    console.log(r.lines?.join('\n') || '');
+    process.exitCode = r.ok ? 0 : 1;
+    return true;
+  }
+  if (cmd === 'rollback' && args.length === 0) {
+    const { mingdaoRollback } = await import('../update.js');
+    const r = mingdaoRollback();
+    console.log(r.lines?.join('\n') || '');
+    process.exitCode = r.ok ? 0 : 1;
+    return true;
+  }
+
+  // Batch API 半价批处理（A1）：mingdao batch <问题文件|-> [--model 名] [--max-tokens n]
+  if (cmd === 'batch') {
+    const { runBatch } = await import('../batch.js');
+    const cfgB = loadConfig();
+    if (!cfgB) {
+      console.log('[错误] 未初始化配置：请先运行 mingdao init');
+      process.exitCode = 1;
+      return true;
+    }
+    let model = cfgB.model || 'deepseek-v4-flash';
+    let maxTokens = 4096;
+    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 === '--out') { i += 1; /* 输出默认落工作目录 */ }
+      else if (!srcFile) srcFile = a;
+    }
+    if (!srcFile) {
+      console.log('用法：mingdao batch <问题文件|-> 每行一个问题（--model 名 --max-tokens n）');
+      process.exitCode = 1;
+      return true;
+    }
+    let questions = [];
+    try {
+      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));
+      process.exitCode = 1;
+      return true;
+    }
+    if (!questions.length) {
+      console.log('[错误] 问题文件为空');
+      process.exitCode = 1;
+      return true;
+    }
+    console.log(`Batch 半价批处理：${questions.length} 个问题 · 模型 ${model}（价格 ×${0.5}，结果异步返回，最长 24h）`);
+    const ac = new AbortController();
+    process.on('SIGINT', () => ac.abort());
+    const r = await runBatch({
+      cfg: cfgB,
+      model,
+      questions,
+      workingDir: process.cwd(),
+      maxTokens,
+      signal: ac.signal,
+      onStatus: (st) => console.log('  ' + st),
+    });
+    process.removeAllListeners('SIGINT');
+    if (r.error) {
+      console.log('[错误] ' + r.error);
+      process.exitCode = 1;
+      return true;
+    }
+    console.log(`✓ 完成 ${r.results.length} 条 · ↑${r.usage.prompt_tokens} ↓${r.usage.completion_tokens} tokens · 费用 ≈¥${r.cost.toFixed(5)}（已按半价）`);
+    console.log(`  结果文件：${r.outputFile}`);
+    console.log(`  任务 ID：${r.batchId}（结果已计入 /cost 分账）`);
+    return true;
+  }
+
+  // 费用报告（/cost 月度导出）：mingdao cost [report [YYYY-MM|all]]
+  if (cmd === 'cost') {
+    const valid = args.length === 0 || (args.length >= 1 && args[0] === 'report' && args.length <= 2 && (!args[1] || args[1] === 'all' || /^\d{4}-\d{2}$/.test(args[1])));
+    if (!valid) return false; // 参数不合法 → 按提问处理
+    const { costMonthlyReport } = await import('../cachestats.js');
+    const months = args.length === 0 ? null : args[1] && args[1] !== 'all' ? args[1] : null;
+    const rows = costMonthlyReport(months);
+    if (!rows.length) {
+      console.log(args.length === 0 ? '暂无费用数据（对话若干轮后自动累积）。' : `没有 ${months || '任何'} 月份的记录。`);
+      return true;
+    }
+    if (args.length === 0) {
+      const total = rows.reduce((s, r) => s + r.cost, 0);
+      console.log(`累计费用 ≈¥${total.toFixed(5)}（${rows.length} 个月份）· 最近：`);
+      for (const r of rows.slice(-3)) {
+        console.log(`  ${r.month}：≈¥${r.cost.toFixed(5)}${r.rate != null ? ` · 命中 ${(r.rate * 100).toFixed(0)}%` : ''}`);
+      }
+      console.log('月度报告导出：mingdao cost report [YYYY-MM|all]');
+      return true;
+    }
+    const bar = (cost, 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);
+      md.push(`# MingDao 费用报告 ${r.month}`);
+      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('');
+      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)} |`);
+      md.push('');
+      md.push('## 每日费用');
+      md.push('');
+      md.push('```');
+      for (const d of r.days) md.push(`${d.day}  ${bar(d.cost, maxDay)}  ¥${d.cost.toFixed(5)}`);
+      md.push('```');
+      md.push('');
+    }
+    const outFile = path.join(process.cwd(), `mingdao-cost-report-${rows.length === 1 ? rows[0].month : 'all'}.md`);
+    fs.writeFileSync(outFile, md.join('\n') + '\n');
+    console.log(`✓ 已导出 ${rows.length} 个月份报告 → ${outFile}`);
+    return true;
+  }
+
+  // 审计日志查看（P3-5）：mingdao audit [数量]（仅裸命令或单个数字；其余按提问处理）
+  if (cmd === 'audit' && (args.length === 0 || (args.length === 1 && /^\d+$/.test(args[0])))) {
+    const { listAudit, auditFile } = await import('../audit.js');
+    const n = Number(args[0]) || 20;
+    const rows = listAudit(n);
+    if (!rows.length) {
+      console.log(`暂无审计记录（工具调用将自动记录到 ${auditFile()}）。`);
+      return true;
+    }
+    console.log(`审计日志（最近 ${rows.length} 条）：${auditFile()}`);
+    for (const r of rows) {
+      const when = new Date(r.at).toISOString().slice(0, 19).replace('T', ' ');
+      const status = r.denied ? `✖拒绝(${r.reason || ''})` : r.ok ? '✓' : '✖错误';
+      const extra = !r.denied && r.timedOut ? '（超时）' : !r.denied && r.exitCode !== null && r.exitCode !== undefined ? `（exit ${r.exitCode}）` : '';
+      const sess = r.session ? `  [会话 ${String(r.session).slice(0, 28)}]` : '';
+      console.log(`  ${when}  ${status} ${r.tool} ${(r.args || '').slice(0, 80)} ${extra}${sess}`);
+    }
+    return true;
+  }
+  return false;
+}

package/src/commands/workspace.js

@@ -0,0 +1,109 @@
+// 命令族：mingdao workspace / mcp preset（自 cli.js 拆出，评估 P0-1 拆包）
+import { addWorkspace, listWorkspaces, removeWorkspace, workspacePath, touchWorkspace } from '../workspace.js';
+import { presetList, buildPreset } from '../mcp-presets.js';
+import { ensureHome, loadConfig, saveConfig } from '../config.js';
+
+export async function handleWorkspace(cmd, args) {
+  const sub = args[0] || 'list';
+  const name = args[1];
+  if (sub === 'add') {
+    if (!name) {
+      console.log('用法：mingdao workspace add <名称> [目录]');
+      process.exitCode = 1;
+      return true;
+    }
+    const r = addWorkspace(name, args[2]);
+    if (r.error) {
+      console.log('[错误] ' + r.error);
+      process.exitCode = 1;
+      return true;
+    }
+    console.log(`✓ 已登记工作空间 ${r.name} → ${r.dir}`);
+    return true;
+  }
+  if (sub === 'remove') {
+    if (!name) {
+      console.log('用法：mingdao workspace remove <名称>');
+      process.exitCode = 1;
+      return true;
+    }
+    console.log(removeWorkspace(name) ? `✓ 已移除 ${name}` : '未找到该工作空间');
+    return true;
+  }
+  if (sub === 'path') {
+    if (!name) {
+      console.log('用法：mingdao workspace path <名称>');
+      process.exitCode = 1;
+      return true;
+    }
+    const p = workspacePath(name);
+    if (p) console.log(p);
+    else {
+      console.error('未找到该工作空间（mingdao workspace list 查看）');
+      process.exitCode = 1;
+    }
+    return true;
+  }
+  if (sub === 'use') {
+    if (!name) {
+      console.log('用法：mingdao workspace use <名称>');
+      process.exitCode = 1;
+      return true;
+    }
+    const p = workspacePath(name);
+    if (!p) {
+      console.log('未找到该工作空间（mingdao workspace list 查看）');
+      process.exitCode = 1;
+      return true;
+    }
+    touchWorkspace(name);
+    console.log(`✓ 工作空间 ${name}：${p}`);
+    console.log(`  快速进入：cd "$(mingdao workspace path ${name})"（建议做成 shell 函数/别名，如 mdw() { cd "$(mingdao workspace path "$1")"; }）`);
+    return true;
+  }
+  const ws = listWorkspaces();
+  if (!ws.length) {
+    console.log('暂无工作空间。添加：mingdao workspace add <名称> [目录]');
+  } else {
+    console.log('工作空间（最近使用优先）');
+    for (const w of ws) console.log(`  ${w.name.padEnd(16)} ${w.dir}`);
+    console.log('\n  进入：cd "$(mingdao workspace path <名称>)"');
+  }
+  return true;
+}
+
+// MCP 预设：mingdao mcp preset list|add <名称> [参数]
+export async function handleMcp(cmd, args) {
+  if (args[0] !== 'preset') return false;
+  const home0 = ensureHome();
+  if (args[1] === 'add') {
+    const name = args[2];
+    if (!name) {
+      console.log('用法：mingdao mcp preset add <名称> [参数]（列表见 mingdao mcp preset list）');
+      process.exitCode = 1;
+      return true;
+    }
+    const r = buildPreset(name, args[3], process.cwd());
+    if (r.error) {
+      console.log('[错误] ' + r.error);
+      process.exitCode = 1;
+      return true;
+    }
+    const cfg0 = loadConfig();
+    if (!cfg0) {
+      console.log('未初始化配置，请先运行 mingdao init');
+      process.exitCode = 1;
+      return true;
+    }
+    cfg0.mcpServers = cfg0.mcpServers || {};
+    cfg0.mcpServers[name] = r.config;
+    saveConfig(cfg0);
+    console.log(`✓ 已添加 MCP 服务器 ${name}（重启 mingdao web 后生效；会话内 /mcp 查看状态）`);
+    return true;
+  }
+  console.log('MCP 生态预设（mingdao mcp preset add <名称> 一键接入）：');
+  for (const p of presetList()) {
+    console.log(`  ${p.name.padEnd(20)} ${p.label}${p.argLabel ? `（参数：${p.argLabel}）` : ''}`);
+  }
+  return true;
+}

package/src/compact.js

@@ -0,0 +1,112 @@
+// 上下文自动压缩（P3-1，复审建议第一优先）：
+// 长会话超出预算、静默裁剪即将丢弃早期段落时，先用 executor 模型把被裁段落压成摘要，
+// 以单条 user 消息注入（替代「失忆」）；被裁段落不足最小阈值时仍走普通裁剪（省一次模型调用）。
+// 摘要失败绝不阻塞会话：任何异常回退普通裁剪。
+//
+// 触发条件：总 token 数 > 预算，且被裁段落（不含 system）≥ MIN_DROP_MESSAGES 条、≥ MIN_DROP_TOKENS tokens。
+// 注入格式：system → 摘要(user) → 保留段（保留段头部经 cleanToolPairing 清洗孤儿 tool 消息）。
+
+import { messageTokens, cleanToolPairing, clampText } from './context.js';
+
+const MIN_DROP_MESSAGES = 3; // 至少裁掉 3 条才值得压缩
+const MIN_DROP_TOKENS = 2000; // 被裁段落 token 数低于此值不值得一次模型调用
+// B1/B2（评估建议）：达到预算 80% 即提前压缩、压到 60%——滞回缓冲带避免在预算线附近
+// 反复触发裁剪/压缩，让摘要成为稳定前缀、后续轮次全程缓存命中；压缩触发频率也大幅下降。
+const DEFAULT_TRIGGER_RATIO = 0.8;
+const TARGET_RATIO = 0.6;
+const SUMMARY_MAX_CHARS = 1600; // 摘要上限（约几百 token，远小于被裁段落）
+const INPUT_MAX_CHARS = 30000; // 摘要输入上限（防超长工具输出撑爆摘要请求）
+const TOOL_OUTPUT_CAP = 300; // 摘要输入中每条工具结果截断长度
+
+const SUMMARY_SYSTEM =
+  '你是 MingDao 的会话压缩器。把对话记录压成紧凑中文摘要（≤500 字，要点列表）：' +
+  '保留用户目标与关键要求、已完成的步骤与结论、修改/创建的文件、未完成事项、重要约定与决策；' +
+  '省略已完成的中间过程与细节。只输出摘要本身，不要任何解释。';
+
+export async function summarizeConversation(provider, model, convoText) {
+  const res = await provider.chat({
+    model,
+    messages: [
+      { role: 'system', content: SUMMARY_SYSTEM },
+      { role: 'user', content: convoText },
+    ],
+    tools: [],
+    temperature: 0.2,
+    maxTokens: 2048, // 审计 Q2：与 SUMMARY_MAX_CHARS(1600 字) 匹配，避免模型侧先截断
+  });
+  const text = String(res?.text || '').trim();
+  if (!text) return { text: null, usage: res?.usage || null };
+  return { text: text.slice(0, SUMMARY_MAX_CHARS), usage: res?.usage || null };
+}
+
+export async function compactConversation({ messages, budget, count, provider, executorModel, triggerRatio }) {
+  if (!messages.length) return null;
+  // 各消息 token 与总量；低于触发线（默认预算 80%）无需压缩
+  const sizes = [];
+  let total = 0;
+  for (const m of messages) {
+    const t = messageTokens(m, count);
+    sizes.push(t);
+    total += t;
+  }
+  const trigger = Number.isFinite(Number(triggerRatio)) ? Number(triggerRatio) : DEFAULT_TRIGGER_RATIO;
+  if (total <= budget * trigger) return null;
+  // 保留边界：保留段（boundary..end）≤ budget×TARGET_RATIO（system 恒保留）
+  let keepTokens = sizes[0] ?? 0;
+  let boundary = messages.length;
+  for (let i = messages.length - 1; i >= 1; i--) {
+    if (keepTokens + sizes[i] > budget * TARGET_RATIO) {
+      boundary = i + 1;
+      break;
+    }
+    keepTokens += sizes[i];
+  }
+  const droppedCount = boundary - 1; // 不含 system
+  if (droppedCount < MIN_DROP_MESSAGES) return null;
+  let droppedTokens = 0;
+  for (let i = 1; i < boundary; i++) droppedTokens += sizes[i];
+  if (droppedTokens < MIN_DROP_TOKENS) return null;
+
+  // 被裁段落 → 文本（工具结果截断；tool_calls 带名称标注）
+  const convoText = messages
+    .slice(1, boundary)
+    .map((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('; ')}]`
+          : '';
+      return `${head}: ${String(m.content ?? '')}${calls}`;
+    })
+    .join('\n')
+    .slice(0, INPUT_MAX_CHARS);
+
+  let summary = null;
+  let usage = null;
+  try {
+    const r = await summarizeConversation(provider, executorModel, convoText);
+    summary = r.text;
+    usage = r.usage;
+  } catch {
+    return null; // 摘要失败：退回普通裁剪
+  }
+  if (!summary) return null;
+
+  // 组装：system + 摘要(user) + 保留段（清洗保留段头部因裁剪而孤立的 tool 消息）
+  const kept = cleanToolPairing(messages.slice(boundary));
+  const next = [
+    messages[0],
+    {
+      role: 'user',
+      content:
+        '（以下是本会话早期内容的自动压缩摘要，细节已省略；如摘要与你的最新要求冲突，以最新指令为准）\n<conversation_summary>\n' +
+        summary +
+        '\n</conversation_summary>',
+    },
+    ...kept,
+  ];
+  return { messages: next, droppedCount, droppedTokens, summary, usage };
+}

package/src/config.js

@@ -0,0 +1,134 @@
+// 配置管理：<mingdao-home>/config.json（默认 ~/.mingdao/config.json）与初始化向导。
+// 优先级：命令行参数 > 环境变量 > config.json > 内置预设。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { PROVIDERS, modelPreset, providerPreset } from './models.js';
+import { setStoredKey, resolveApiKey, maskKey } from './credentials.js';
+
+export function mingdaoHome() {
+  return process.env.MINGDAO_HOME || path.join(os.homedir(), '.mingdao');
+}
+
+export function ensureHome() {
+  const home = mingdaoHome();
+  for (const sub of ['', 'sessions', 'providers']) {
+    fs.mkdirSync(sub ? path.join(home, sub) : home, { recursive: true, mode: 0o700 });
+  }
+  return home;
+}
+
+export function configPath() {
+  return path.join(mingdaoHome(), 'config.json');
+}
+
+export function loadConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(configPath(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function saveConfig(cfg) {
+  ensureHome();
+  const p = configPath();
+  fs.writeFileSync(p, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+  try {
+    fs.chmodSync(p, 0o600);
+  } catch {}
+}
+
+export function effectiveApiKey(cfg, providerName) {
+  return resolveApiKey(cfg, providerName, providerPreset(providerName)?.envKey);
+}
+
+export async function runWizard(io) {
+  io.box('MingDao 初始化向导', ['三步完成：选服务商/模型 → 填 API Key → 选权限模式']);
+  io.print('');
+
+  const providerKeys = Object.keys(PROVIDERS);
+  const provider = await io.choose(
+    '① 选择模型服务商：',
+    providerKeys.map((k) => ({ value: k, label: `${k} — ${PROVIDERS[k].label}` }))
+  );
+  const pp = PROVIDERS[provider];
+
+  let model;
+  if (provider === 'custom') {
+    model = await io.ask('② 模型名（例如 deepseek-v4-flash）：');
+  } else {
+    const options = pp.models.map((m) => {
+      const preset = modelPreset(m);
+      return { value: m, label: preset ? `${m} — ${preset.label}` : m };
+    });
+    options.push({ value: '__custom__', label: '自定义模型名（手动输入）' });
+    const choice = await io.choose('② 选择模型：', options);
+    model = choice === '__custom__' ? await io.ask('模型名：') : choice;
+  }
+
+  const envDetected = pp.envKey && process.env[pp.envKey] ? `（检测到环境变量 ${pp.envKey}，回车直接使用）` : '';
+  const apiKey = await io.ask(`③ API Key${envDetected}：`, { hidden: true });
+
+  if (apiKey) {
+    setStoredKey(provider, apiKey);
+    io.print(`✓ API Key 已保存到独立凭证库（权限 600），不会写入 config.json。`);
+  } else {
+    io.print(`✓ 未输入 API Key：将使用环境变量 ${pp.envKey || 'MINGDAO_API_KEY'}。`);
+  }
+
+  let baseUrl = '';
+  if (provider === 'custom') {
+    baseUrl = await io.ask(`API 地址（回车默认 ${pp.baseUrl}）：`);
+  }
+
+  const perm = await io.choose('权限模式（写文件 / 执行命令时）：', [
+    { value: 'ask', label: 'ask — 每次询问（推荐，最安全）' },
+    { value: 'auto', label: 'auto — 全部自动允许（完全自主，注意风险）' },
+    { value: 'readonly', label: 'readonly — 只读模式，不允许修改或执行' },
+  ]);
+
+  const sandbox = await io.choose('沙箱模式（bash 工具执行隔离，Linux + bubblewrap）：', [
+    { value: 'off', label: 'off — 直接执行（默认）' },
+    { value: 'readonly', label: 'readonly — 全盘只读（/tmp 可写，网络可用）' },
+    { value: 'safe', label: 'safe — 只读 + 断网（工作目录与 /tmp 可写，最安全）' },
+  ]);
+
+  let routing = null;
+  if (modelPreset('deepseek-v4-pro') && modelPreset('deepseek-v4-flash')) {
+    const routeChoice = await io.choose('自动模型路由（规划类任务→pro，执行类→flash）：', [
+      { value: 'on', label: 'on — 开启（省钱又高效，推荐）' },
+      { value: 'off', label: 'off — 关闭（始终用当前模型）' },
+    ]);
+    if (routeChoice === 'on') routing = { enabled: true, planner: 'deepseek-v4-pro', executor: 'deepseek-v4-flash' };
+  }
+
+  const preset = modelPreset(model);
+  const defaultBudget = preset?.budgetTokens ?? 128000;
+  const budgetInput = await io.ask(`上下文预算 tokens（回车默认 ${defaultBudget}）：`);
+  const contextBudget = Number(budgetInput) > 0 ? Number(budgetInput) : defaultBudget;
+
+  // 注意：config.json 不含任何密钥（可安全分享/提交），密钥只存 credentials.json。
+  const cfg = {
+    provider,
+    model,
+    baseUrl: baseUrl || pp.baseUrl,
+    permission: perm,
+    sandbox,
+    contextBudget,
+  };
+  if (routing) cfg.routing = routing;
+  saveConfig(cfg);
+  io.print('');
+  io.box('配置完成 ✓', [
+    `服务商  ${provider}（${pp.label}）`,
+    `模型    ${model}`,
+    `权限    ${perm} · 沙箱  ${sandbox}`,
+    `路由    ${routing ? '自动（pro⇄flash）' : '关闭'}`,
+    `密钥    ${apiKey ? '凭证库 ' + maskKey(apiKey) : '环境变量 ' + (pp.envKey || 'MINGDAO_API_KEY')}`,
+    `保存于  ${configPath()}`,
+  ]);
+  io.print('现在输入 mingdao 即可开始对话。');
+  return cfg;
+}

package/src/context.js

@@ -0,0 +1,86 @@
+// 上下文管理：token 计数与预算裁剪。
+// 计数优先级：DeepSeek 词表精确计数（tokenizer.js）→ 启发式估算（无词表模型回退）。
+
+import { heuristicTokens } from './tokenizer.js';
+
+export const TOOL_RESULT_LIMIT = 20000;
+
+// 兼容旧接口的启发式估算（英文≈4 字符/token，CJK≈1 字符/token）
+export function approxTokens(text) {
+  return heuristicTokens(text);
+}
+
+function partTokens(msg, count) {
+  let total = count(msg.content || '');
+  for (const tc of msg.tool_calls || []) {
+    total += count(JSON.stringify(tc));
+  }
+  return total;
+}
+
+// 消息对象级 token 缓存（WeakMap：消息被会话持有期间有效，随消息一起回收）。
+// 会话历史消息内容基本不可变（裁剪是投影，不改原对象），同一回合的 24 步里
+// trimMessages 每步全量重算时直接命中，跳过重复 BPE 计数；key 附上 count 函数，
+// 模型切换（新计数器）后自动失效重算。
+const messageTokenCache = new WeakMap();
+
+export function messageTokens(msg, count = approxTokens) {
+  const hit = messageTokenCache.get(msg);
+  if (hit && hit.fn === count) return hit.value;
+  const total = partTokens(msg, count) + 4; // 每条消息的协议开销
+  messageTokenCache.set(msg, { fn: count, value: total });
+  return total;
+}
+
+// 从尾部向前保留消息，直到预算用尽；始终保留首条 system 消息。
+// 裁剪可能切断 assistant(tool_calls) ↔ tool 的配对，清洗掉孤立消息，
+// 否则 OpenAI 兼容 API 会因 tool_call_id 找不到对应调用而报 400。
+export function cleanToolPairing(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));
+  // 注意：裁剪是每次请求的投影，绝不能改写调用方 messages 里的原对象
+  // （否则会话历史被永久污染：assistant 消息丢失 tool_calls，下一轮 API 报 400）
+  return clean.map((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));
+      if (keptCalls.length !== m.tool_calls.length) {
+        if (keptCalls.length) return { ...m, tool_calls: keptCalls };
+        const copy = { ...m };
+        delete copy.tool_calls; // 无任何对应 tool 响应，退化为纯文本消息
+        return copy;
+      }
+    }
+    return m;
+  });
+}
+
+export function trimMessages(messages, 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;
+  let total = system.reduce((s, m) => s + messageTokens(m, count), 0);
+  const tail = [];
+  for (let i = rest.length - 1; i >= 0; i--) {
+    const t = messageTokens(rest[i], count);
+    if (total + t > budget) break;
+    total += t;
+    tail.unshift(rest[i]);
+  }
+  const kept = cleanToolPairing(system.concat(tail));
+  // 静默裁剪：不向中间插入说明消息——保持消息前缀字节稳定，
+  // 让 DeepSeek 等支持上下文缓存的 API 最大化缓存命中（命中价仅为未命中的约 1/30）。
+  return kept;
+}
+
+export function clampText(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

@@ -0,0 +1,58 @@
+// 费用护栏（四报告共识 A2/Kimi P-1：把峰谷定价从「展示」升级为「主动约束」）：
+// config.costGuard = { dailyLimitYuan: 10, warnAtYuan: 8, action: 'warn'|'block' }
+// 按北京时间自然日累计 cache-stats 实际费用（含 batch 半价与缓存折扣后的真实口径）。
+// Agent 每轮开始前检查：超 warn 线提醒、超 limit 且 action=block 时暂停执行。
+
+import { listCacheStats } from './cachestats.js';
+import { beijingDayStart } from './pricing.js';
+import { loadConfig } from './config.js';
+
+export function costGuardConfig() {
+  return loadConfig()?.costGuard || null;
+}
+
+// 今日（北京时间 0 点起）累计实际费用
+export function todayCost() {
+  const start = beijingDayStart().getTime();
+  let sum = 0;
+  for (const e of listCacheStats(100000)) {
+    if (e.at >= start) sum += Number(e.cost) || 0;
+  }
+  return sum;
+}
+
+export function costGuardStatus() {
+  const g = costGuardConfig();
+  if (!g) return null;
+  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';
+  return {
+    cost,
+    limit,
+    warnAt,
+    action,
+    overWarn: limit > 0 && cost >= warnAt,
+    overLimit: limit > 0 && cost >= limit,
+  };
+}
+
+// Agent 每轮开始前调用：返回 null 放行；blocked=true 表示应暂停本轮
+export function checkCostGuard() {
+  const st = costGuardStatus();
+  if (!st) return null;
+  if (st.overLimit && st.action === 'block') {
+    return {
+      blocked: true,
+      message: `今日费用已达上限 ¥${st.limit.toFixed(2)}（实际 ¥${st.cost.toFixed(4)}），已暂停执行——调整 config.costGuard 或明天自动恢复。`,
+    };
+  }
+  if (st.overWarn) {
+    return {
+      blocked: false,
+      message: `⚠ 费用护栏：今日已用 ¥${st.cost.toFixed(4)} / 上限 ¥${st.limit.toFixed(2)}${st.action === 'block' ? '（到达即暂停）' : '（仅提醒）'}。`,
+    };
+  }
+  return null;
+}