mingdao-harness 0.2.3 → 0.2.5

package/docs/ROADMAP-NEXT.md

@@ -26,19 +26,19 @@
 9. cli.js 共享助手抽取（offpeak defer、mcpFacade 构建、run/run-worker 参数解析合一）
 - 验收：全绿 + 新增 fs-browse 越界与限流回归断言。
 
-### Phase B「省钱第二轮」v0.2.3（约 2–3 天）
-1. **工具 Schema 按需挂载**（每请求省 1–2K tokens）：只读阶段只发 read/ls/glob/grep/skill + 本回合已用工具；写类工具首次调用时动态注入
-2. **Batch 输入侧**：文本哈希去重（结果按 custom_id 回填全部位置）、单问超窗口预检报错、`--max-cost` 上限
-3. **费用二级分账 + 看板**：cache-stats 增 reasoning/tool 维度与 byTool 累加；WebUI 仪表盘加模型/工具 Top5 与按天折线（零依赖 SVG）
-4. **护栏 downgrade**：`action:'downgrade'` —— 触顶后自动切 flash + 明确提示（默认仍 warn/block 可选）
-5. **评测基准扩充**：压缩质量集（5 组长会话样本→压缩→关键事实追问断言）、路由 100 条标注集入 bench
-- 验收：bench 断言数 38→60+；覆盖率阈值上调至 60%。
-
-### Phase C「结构渐进」v0.2.4（约 2 天）
-1. routes/api.js 按域细分（config/sessions/sync/schedule/skills/workspace/misc 7 模块 + 共享中间件），每域配 API 契约测试
-2. cli.js REPL → commands/repl.js、worker → tasks/worker.js（e2e-local 16 项全绿做护栏）
-3. strict 棘轮削 300 条（先 credentials/permissions/config/sync-server/session 五个安全关键模块全量注解）
-- 验收：tsc full 错误数 ≤1284；结构清单在文档登记。
+### Phase B「省钱第二轮」v0.2.4（已完成 ✅）
+1. ✅ **工具 Schema 按需挂载**：只读阶段只发 read/ls/glob/grep/skill/todo + 已用工具；模型表达写意图后下一轮注入全量（`cfg.schemaTier=false` 可关）；已用工具深度瘦身（工具级 + 参数级描述清除，全用过降 48%）
+2. ✅ **Batch 输入侧**：文本哈希去重（结果按 custom_id 回填全部位置）、单问超窗口预检报错、`--max-cost` 提交前估算拦截
+3. ✅ **费用二级分账 + 看板**：cache-stats 增 reasoning / byTool 维度；WebUI 仪表盘加模型/工具 Top5 与近 14 天费用折线（零依赖 SVG）；`mingdao cost report` 增按工具分账表
+4. ✅ **护栏 downgrade**：`action:'downgrade'` —— 触顶后自动切 flash 继续执行 + 明确提示（warn/block 仍可选；已是 flash 则按 block 处理）
+5. ✅ **评测基准扩充**：压缩质量集（5 组长会话样本 → 压缩 → 关键事实存活断言 + 尾部字节不变）、路由标注集扩至 100 条；bench 断言数 38 → 150+；覆盖率阈值 55% → 60%
+- 版本说明：v0.2.3 被 0.2.2 桌面启动崩溃的紧急修复占用，Phase B 顺延为 v0.2.4。
+
+### Phase C「结构渐进」v0.2.5（进行中）
+1. ✅ routes/api.js 按域细分：`src/web/routes/domains/{config,sessions,skills,schedule,sync,workspace,misc}.js`（7 域，handle(ctx,deps,shared) 契约：命中返回 true）+ api.js 瘦身为编排器（访问控制/CSRF/静态壳 + 域循环）；`test/api-contracts.js` 8 组契约测试入 run-all；顺带修复 icon 路由路径 bug（routes/icons → web/icons，契约测试捕获）
+2. ✅ cli.js REPL → `src/commands/repl.js`（runRepl(ctx)）、worker → `src/tasks/worker.js`（runWorkerTask）；e2e-local 16 项全绿护栏
+3. ⏳ strict 棘轮削 300 条（五安全关键模块 credentials/permissions/config/sync-server/session 全量注解 + 批量文件注解）
+- 验收：tsc full 错误数 ≤812；结构清单在文档登记。
 
 ### Phase D「能力演进」v0.3.0（约 3–5 天，可按需裁剪）
 1. **跨平台沙箱补位**：Windows Job Object + 降权 token（零依赖原生 API）、macOS seatbelt 规则；敏感命令平台无关拦截清单兜底

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mingdao-harness",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "MingDao Harness —— 开源智能体框架（Agent Harness）。零依赖、开箱即用，针对 DeepSeek-V4 系列优化，开放主流模型接入。",
   "type": "module",
   "bin": {

package/skills/release-checklist/SKILL.md

@@ -11,9 +11,22 @@ description: 准备发布新版本、打包交付前使用
 2. **版本**：版本号统一（package.json / 配置 / 文档互相一致），遵循语义化版本。
 3. **变更说明**：changelog 用用户语言描述新增/修复/破坏性变更。
 4. **构建验证**：实际构建/打包一次，并在干净环境验证产物可安装可运行。
-5. **敏感信息**：密钥、token、内网地址、个人信息不得进入仓库与产物（`grep -rE 'sk-[A-Za-z0-9]{20,}' .`）。
-6. **回滚方案**：明确如何回退到上一版本（旧包/旧 tag 可恢复）。
-7. **发布后冒烟**：发布完成后立即做一次端到端验证。
+5. **桌面版打包冒烟（0.2.2 事故护栏，发版必经）**：主进程模块求值必须真实跑通打包产物——
+   - CI 已内置：desktop.yml 在 Linux 腿用 xvfb 运行 `dist/linux-unpacked/mingdao --no-sandbox`（`MINGDAO_DESKTOP_SMOKE=1`），模块求值通过输出 `MINGDAO_DESKTOP_SMOKE_OK` 并退出 0，否则 workflow 失败；
+   - 本地有显示器时可加验：`cd desktop && MINGDAO_DESKTOP_SMOKE=1 dist/linux-unpacked/mingdao --no-sandbox`（AppImage 加 `--appimage-extract-and-run`）；
+   - 教训：0.2.2 三平台启动即崩（main.js 顶层调用 createLogWriter 漏导入），打包期不报错、运行期才炸——静态护栏（test/smoke.js「桌面主进程静态护栏」组）与打包冒烟双保险。
+6. **敏感信息**：密钥、token、内网地址、个人信息不得进入仓库与产物（`grep -rE 'sk-[A-Za-z0-9]{20,}' .`）。
+7. **回滚方案**：明确如何回退到上一版本（旧包/旧 tag 可恢复）。
+8. **发布后冒烟**：发布完成后立即做一次端到端验证。
+
+## 桌面版发布流水线（官网分发 + 镜像 + 转运附件回收）
+
+1. `npm version <v>`（preversion 自动跑 smoke/e2e/bench，version 钩子自动插 changelog，postversion 自动提交）→ 推 3 远端 + tag。
+2. `npm publish` → GitHub desktop.yml CI 全绿（含打包冒烟）。
+3. 服务器收割：`/tmp/harvest-<ver>.sh`（下载 7 安装包 + 2 yml，sha512 交叉校验 MATCH，再生成官网 3 份 feed）。
+4. 官网 site/index.html 刷新版本/大小/sha256 校验行并部署；BBS 随 deploy.sh 重启。
+5. gitee/gitcode 创建 Release（正文指向官网，无附件）。
+6. 官网同步确认后：`MINGDAO_GITHUB_TOKEN=<PAT> node scripts/github-release-cleanup.mjs <版本号>` 删除 GitHub 转运附件（先 --dry-run）。
 
 ## 输出
 

package/src/agent.js

@@ -2,9 +2,9 @@
 // → PostToolUse 钩子 → 结果回填 → 循环，直到模型给出纯文本回复。
 // 附带：子代理（task 工具）、todo 清单状态、undo 备份仓、Ctrl+C 中断。
 
-import { trimMessages, clampText, messageTokens } from './context.js';
+import { trimMessages, clampText, messageTokens, approxTokens } from './context.js';
 import { compactConversation } from './compact.js';
-import { toolSchemas, dispatch } from './tools/index.js';
+import { buildToolSchemas, dispatch } from './tools/index.js';
 import { modelPreset } from './models.js';
 import { makeTokenCounter } from './tokenizer.js';
 import { createHooks } from './hooks.js';
@@ -29,7 +29,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
   const temperature = cfg.temperature ?? preset.temperature ?? 0.6;
   const reasoningEffort = cfg.reasoningEffort ?? preset.reasoningEffort?.default ?? undefined;
   const hooks = createHooks(cfg.hooks, workingDir);
-  const todos = [];
+  const todos = /** @type {any[]} */ ([]);
   // 会话级共享：调用方传入则复用（/model 切换、子代理均共享，undo 不丢失）
   const undo = undoStore || { backups: new Map() };
   const stepLimit = maxSteps || MAX_STEPS;
@@ -39,14 +39,33 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
   const count = makeTokenCounter(modelName);
   // MCP 工具集（每次取，服务器晚就绪也能在后续轮次出现）
   const mcpSchemas = () => (mcp ? mcp.toolSchemas() : []);
+  // 省钱 B1：本会话已调用过的工具名（内置名/MCP 前缀名）——其 schema 在后续轮次省略 description，
+  // 模型已在消息历史里见过用途；未用过的保留完整描述。省输入 token（工具 schema 按需瘦身）。
+  const usedToolNames = new Set();
+  // 省钱 B1（按需挂载）：回合起始为「只读阶段」时只发只读工具（read/ls/glob/grep/skill/todo）
+  // + 已用过的工具；检测到写意图（用户消息或模型明说需要写/改/建）后注入全量工具。
+  const READONLY_TIER_SET = new Set(['read', 'ls', 'glob', 'grep', 'skill', 'todo']);
+  const WRITE_INTENT_RE = /写|建|创|改|修|删|装|加|添|增|补|换|移|部署|执行|运行|实现|重构|生成|迁移|安装|更新|升级|发布|调整|优化|修复|提交|推送|打包|编译|测试/;
+  const hasWriteIntent = (/** @type {any} */ text) => WRITE_INTENT_RE.test(String(text || ''));
+  const toolsFor = (/** @type {boolean} */ readOnlyPhase) => {
+    const schemas = buildToolSchemas(usedToolNames, mcpSchemas());
+    if (!readOnlyPhase) return schemas;
+    return schemas.filter((/** @type {any} */ t) => {
+      const n = t?.function?.name;
+      if (!n) return true;
+      if (READONLY_TIER_SET.has(n) || usedToolNames.has(n)) return true;
+      if (n.startsWith('mcp__')) return mcp ? mcp.isReadonly(n) : false;
+      return false;
+    });
+  };
 
   // 子代理：全新上下文 + 同一 Provider/权限（提示带「子任务」标记），独立完成子任务后汇报
-  async function spawnTask(prompt, { description = '', readOnly = false } = {}) {
+  async function spawnTask(/** @type {any} */ prompt, { description = '', readOnly = false } = {}) {
     const subIo = createIO({ quiet: true });
     // 只读子代理（评估 A4：可并行）：只读工具自动放行、写类直接拒绝，无交互询问
     const subPermission = readOnly
-      ? { mode: 'readonly-noask', check: (name) => READONLY_TOOLS_SET.has(name) }
-      : { check: (name, args) => permission.check(name, args, '（子任务）') };
+      ? { mode: 'readonly-noask', check: (/** @type {any} */ name) => READONLY_TOOLS_SET.has(name) }
+      : { check: (/** @type {any} */ name, /** @type {any} */ args) => permission.check(name, args, '（子任务）') };
     // 自动路由：子代理固定走 executor 模型（便宜的执行单元）
     const subModel = subagentModel(cfg, modelName);
     const subAgent = createAgent({
@@ -91,23 +110,47 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
       budget,
       todos,
       undoStore: undo,
-      spawnTask: (prompt, opts) => spawnTask(prompt, opts),
+      spawnTask: (/** @type {any} */ prompt, /** @type {any} */ opts) => spawnTask(prompt, opts),
     };
   }
 
-  async function runTurn(messages) {
+  async function runTurn(/** @type {any} */ messages) {
     let steps = 0;
     let finish = null;
-    const usage = { prompt_tokens: 0, completion_tokens: 0 };
+    const usage = /** @type {{ prompt_tokens: number, completion_tokens: number, prompt_cache_hit_tokens?: number, prompt_cache_miss_tokens?: number }} */ ({ prompt_tokens: 0, completion_tokens: 0 });
     const startedAt = Date.now();
     // 回合性能指标（状态栏：LLM 时长 / 工具时长 / 首 token 延迟 / 步数）
     let llmMsTotal = 0;
     let toolMsTotal = 0;
-    let firstTokenAt = null;
-    const perf = () => ({ llmMs: llmMsTotal, toolMs: toolMsTotal, firstTokenMs: firstTokenAt == null ? null : firstTokenAt - startedAt, steps });
+    let firstTokenAt = /** @type {any} */ (null);
+    // 省钱 B3（费用二级分账）：推理 token 估算（按增量累计）与逐工具调用/耗时累加
+    let reasoningTokens = 0;
+    const toolStats = /** @type {Map<string, {calls: number, ms: number}>} */ (new Map());
+    const perf = () => ({
+      llmMs: llmMsTotal,
+      toolMs: toolMsTotal,
+      firstTokenMs: firstTokenAt == null ? null : firstTokenAt - startedAt,
+      steps,
+      reasoningTokens,
+      toolStats: [...toolStats.entries()].map(([tool, s]) => ({ tool, calls: s.calls, ms: s.ms })),
+      usedModel: activeModel, // 省钱 B4：本回合实际使用模型（降级后归属它）
+    });
     let aborted = false;
     let emptyRounds = 0; // 连续空/截断输出计数（防止无限续写）
-    let currentAc = null;
+    let currentAc = /** @type {any} */ (null);
+    // 省钱 B4（护栏降级）：action='downgrade' 超限后本回合切换到便宜模型继续执行；
+    // activeModel 是本回合实际使用的模型（分账/记录归属它），downgraded 保证只提示一次。
+    let activeModel = modelName;
+    let downgraded = false;
+    // 省钱 B1：本回合只读阶段判定——最新用户消息无写意图则先只发只读工具，
+    // 模型明确表达写意图后（下一轮）注入全量。cfg.schemaTier=false 可关。
+    let readOnlyPhase = true;
+    if (cfg.schemaTier !== false) {
+      const lastUser = [...messages].reverse().find((m) => m?.role === 'user');
+      readOnlyPhase = !hasWriteIntent(lastUser?.content);
+    } else {
+      readOnlyPhase = false;
+    }
     // 整个回合注册一次 SIGINT：思考、工具执行、权限询问期间都能中断
     const offSigint = io.onSigint ? io.onSigint(() => { aborted = true; currentAc?.abort(); }) : () => {};
     const ctx = makeCtx();
@@ -160,21 +203,22 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
       for (const m of sanitized) {
         const rc = m.reasoning_content;
         if (typeof rc === 'string' && rc.length > 4000) {
-          sanitized = sanitized.map((x) => (x === m ? { ...x, reasoning_content: `[思考过程已省略（原 ${rc.length} 字）]` } : x));
+          sanitized = sanitized.map((/** @type {any} */ x) => (x === m ? { ...x, reasoning_content: `[思考过程已省略（原 ${rc.length} 字）]` } : x));
         } else if (typeof rc === 'string' && rc.length > 1000) {
-          sanitized = sanitized.map((x) => (x === m ? { ...x, reasoning_content: rc.slice(-500) + ' …[思考过程已截断]' } : x));
+          sanitized = sanitized.map((/** @type {any} */ x) => (x === m ? { ...x, reasoning_content: rc.slice(-500) + ' …[思考过程已截断]' } : x));
         }
       }
 
       // 护栏前置预估（Kimi P2-E）：发送前按本轮最坏成本估算（trimmed prompt × 未命中输入价
       // + maxOutput × 输出价，峰谷按当前时段）；「今日已用 + 最坏成本」超上限时发送前拦截，
-      // 而不是等 200K 上下文的贵请求发出后才 block。
+      // 而不是等 200K 上下文的贵请求发出后才 block。action='downgrade'（省钱 B4）不在此拦截——
+      // 由降级流程接管：切到便宜模型后按 flash 价格重新估算，通常即可放行。
       if (cfg.costGuard) {
         const g = costGuardConfig();
-        if (g && Number(g.dailyLimitYuan) > 0) {
+        if (g && Number(g.dailyLimitYuan) > 0 && g.action !== 'downgrade') {
           let promptTokens = 0;
           for (const m of sanitized) promptTokens += messageTokens(m, count);
-          const worst = estimateCost(modelName, promptTokens, maxOutput, null, new Date());
+          const worst = estimateCost(activeModel, promptTokens, maxOutput, null, new Date());
           const used = todayCost();
           if (used + worst >= Number(g.dailyLimitYuan)) {
             stripOrphanCalls();
@@ -187,7 +231,8 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         }
       }
 
-      // 费用护栏（A2）：每轮开始前按今日实际费用检查；block 时暂停本轮并明确告知
+      // 费用护栏（A2/B4）：每轮开始前按今日实际费用检查；block 暂停本轮；
+      // downgrade 自动切换便宜模型继续执行（每回合只切一次，切换即粘滞）
       if (cfg.costGuard) {
         const guard = checkCostGuard();
         if (guard) {
@@ -206,7 +251,23 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
               perf: perf(),
             };
           }
-          io.print(style(guard.message, C.yellow));
+          if (guard.downgrade && !downgraded) {
+            if (guard.downgradeModel !== activeModel) {
+              activeModel = guard.downgradeModel;
+              downgraded = true;
+              io.print(style(guard.message, C.yellow));
+            } else {
+              // 已经是降级目标模型：无法再降，按 block 处理
+              stripOrphanCalls();
+              return {
+                text: null, reasoning: '', usage, steps, finish, truncated: false, aborted: false,
+                note: `今日费用已达上限（实际 ¥${String(todayCost().toFixed(4))}），且已在最便宜模型上执行，已暂停——调整 config.costGuard 或明天自动恢复。`,
+                durationMs: Date.now() - startedAt, perf: perf(),
+              };
+            }
+          } else if (!guard.downgrade) {
+            io.print(style(guard.message, C.yellow));
+          }
         }
       }
 
@@ -221,18 +282,21 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
       const llmT0 = Date.now();
       try {
         res = await provider.chat({
-          model: modelName,
+          model: activeModel,
           messages: sanitized,
-          tools: [...toolSchemas(), ...mcpSchemas()],
+          tools: toolsFor(readOnlyPhase),
           temperature,
           maxTokens: maxOutput,
           reasoningEffort,
           signal: ac.signal,
-          onDelta(d) {
+          onDelta(/** @type {any} */ d) {
             io.stopSpinner();
             if (firstTokenAt == null) firstTokenAt = Date.now(); // 首个增量即首 token
             if (d.text) io.writeText(d.text);
-            if (d.reasoning) io.writeReasoning(d.reasoning);
+            if (d.reasoning) {
+              reasoningTokens += approxTokens(d.reasoning); // 省钱 B3：推理 token 估算（分账维度）
+              io.writeReasoning(d.reasoning);
+            }
           },
         });
         llmMsTotal += Date.now() - llmT0;
@@ -248,6 +312,8 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
       }
 
       finish = res.finish ?? finish;
+      // 省钱 B1：只读阶段中模型文字明确表达写意图 → 下一轮注入全量工具（多一轮，几乎无感）
+      if (readOnlyPhase && hasWriteIntent(res.text)) readOnlyPhase = false;
       if (res.usage) {
         usage.prompt_tokens += res.usage.prompt_tokens || 0;
         usage.completion_tokens += res.usage.completion_tokens || 0;
@@ -273,7 +339,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
 
         // 预检：解析参数 → PreToolUse 钩子 → 权限检查；拒绝/失败只回填不执行（返回 null）
         // task 工具标记 readOnly 时也可并行（评估 A4：只读子代理 Promise.all）
-        async function prepTool(tc) {
+        async function prepTool(/** @type {any} */ tc) {
           const name = tc.function?.name || '';
           // 审计（P3-5）：参数与拒绝原因都记录（配置 audit:false 可关）
           const auditOn = cfg.audit !== false;
@@ -287,7 +353,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
               args: auditArgs(),
               ...extra,
             });
-          let args = null;
+          let args = /** @type {any} */ (null);
           try {
             args = JSON.parse(tc.function?.arguments || '{}');
           } catch {
@@ -337,8 +403,9 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         // 执行单个工具（渲染「执行中」→ dispatch → 捕获异常转错误结果）
         // 审计 Hermes C4：同回合相同参数的只读工具（read/ls/glob/grep/skill）合并执行一次，
         // 后续相同调用直接复用结果（仍逐个回填 tool 消息以保持 tool_call_id 配对）
-        async function runTool(prep) {
+        async function runTool(/** @type {any} */ prep) {
           io.renderToolStart?.(prep.name, prep.args);
+          usedToolNames.add(prep.name); // 省钱 B1：执行过即标记，后续轮次省略其 description
           const dedupKey = !prep.isMcp && READONLY_TOOLS_SET.has(prep.name) ? prep.name + ':' + JSON.stringify(prep.args || {}) : null;
           if (dedupKey && turnToolCache.has(dedupKey)) {
             prep.cached = true;
@@ -354,15 +421,20 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
             }
             if (dedupKey) turnToolCache.set(dedupKey, result);
             return result;
-          } catch (err) {
+          } catch (/** @type {any} */ err) {
             return JSON.stringify({ ok: false, error: String(err?.message || err) });
           }
         }
 
         // 收尾：渲染结果 → todo 更新 → PostToolUse 钩子 → 回填消息（顺序与串行一致）
-        function finishTool(prep, result, t0) {
+        function finishTool(/** @type {any} */ prep, /** @type {any} */ result, /** @type {any} */ t0) {
           const ms = Date.now() - t0;
           toolMsTotal += ms;
+          // 省钱 B3：逐工具调用/耗时累加（费用二级分账的 byTool 维度）
+          const ts = toolStats.get(prep.name) || { calls: 0, ms: 0 };
+          ts.calls += 1;
+          ts.ms += ms;
+          toolStats.set(prep.name, ts);
           io.renderTool(prep.name, prep.args, result, ms);
           if (prep.name === 'todo' && result?.todos) io.renderTodo(result.todos);
           hooks.post(prep.name, prep.args, typeof result === 'string' ? { output: result } : result).catch(() => {});
@@ -401,7 +473,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           const batch = []; // {prep, batchable}
           while (i < res.toolCalls.length) {
             const tc = res.toolCalls[i];
-            const prep = await prepTool(tc);
+            const prep = /** @type {any} */ (await prepTool(tc));
             const name = tc.function?.name || '';
             let batchable = canBatch && Boolean(prep) && !prep.isMcp && READONLY_BATCH.has(name);
             if (!batchable && canBatch && Boolean(prep) && name === 'task' && prep.args?.readOnly === true) batchable = true;
@@ -529,7 +601,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
     maxOutput,
     temperature,
     runTurn,
-    spawnTask: (prompt, opts) => spawnTask(prompt, opts),
+    spawnTask: (/** @type {any} */ prompt, /** @type {any} */ opts) => spawnTask(prompt, opts),
     getTodos: () => todos.slice(),
   };
 }

package/src/audit.js

@@ -17,11 +17,11 @@ export function auditFile() {
 }
 
 // 轻量脱敏：sk- 系 API Key 掩码（审计日志可安全共享排查）
-export function redactSecrets(text) {
+export function redactSecrets(/** @type {any} */ text) {
   return String(text ?? '').replace(/(sk-[A-Za-z0-9_-]{6,})/g, 'sk-***');
 }
 
-export function writeAudit(entry) {
+export function writeAudit(/** @type {any} */ entry) {
   try {
     ensureHome();
     const file = auditFile();

package/src/batch.js

@@ -8,15 +8,18 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { resolveProviderConfig } from './providers/index.js';
 import { estimateBatchCost, BATCH_DISCOUNT } from './pricing.js';
 import { recordCacheStats } from './cachestats.js';
+import { approxTokens } from './context.js';
+import { modelPreset } from './models.js';
 
 const DEFAULT_WINDOW = '24h';
 const DEFAULT_ENDPOINT = '/v1/chat/completions';
 
 // 批处理端点基址：config.batchBaseUrl 优先；否则取当前服务商 baseUrl 去掉 /v1 后缀
-function batchBase(cfg, model) {
+function batchBase(/** @type {any} */ cfg, /** @type {any} */ model) {
   const explicit = String(cfg?.batchBaseUrl || '').trim().replace(/\/+$/, '');
   if (explicit) return explicit;
   const pc = resolveProviderConfig(cfg, model);
@@ -26,7 +29,7 @@ function batchBase(cfg, model) {
 }
 
 /** @returns {Promise<any>} */
-async function api(base, apiKey, methodPath, payload, httpMethod = 'POST') {
+async function api(/** @type {any} */ base, /** @type {any} */ apiKey, /** @type {any} */ methodPath, /** @type {any} */ payload, httpMethod = 'POST') {
   const res = await fetch(base + methodPath, {
     method: httpMethod,
     headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${apiKey}` },
@@ -41,7 +44,7 @@ async function api(base, apiKey, methodPath, payload, httpMethod = 'POST') {
   return j;
 }
 
-async function uploadFile(base, apiKey, jsonl) {
+async function uploadFile(/** @type {any} */ base, /** @type {any} */ apiKey, /** @type {any} */ jsonl) {
   const form = new FormData();
   form.append('file', new Blob([jsonl], { type: 'application/jsonl' }), 'mingdao-batch.jsonl');
   form.append('purpose', 'batch');
@@ -59,7 +62,7 @@ async function uploadFile(base, apiKey, jsonl) {
   return j.id;
 }
 
-async function downloadResults(base, apiKey, batch) {
+async function downloadResults(/** @type {any} */ base, /** @type {any} */ apiKey, /** @type {any} */ batch) {
   // DeepSeek 风格：直接取结果文件；回退 OpenAI 风格：按 output_file_id 取内容
   const attempts = [
     `/batches/${batch.id}/files/result`,
@@ -84,10 +87,12 @@ async function downloadResults(base, apiKey, batch) {
   throw new Error('批处理结果文件不可用（端点不支持或文件已过期）');
 }
 
-/** 执行一次批处理。questions: string[]。返回 { ok, outputFile, results, usage, cost, batchId }
- * @param {{ cfg: any, model: any, questions: any, workingDir?: string, maxTokens?: number, temperature?: any, signal?: any, onStatus?: any }} opts */
-export async function runBatch({ cfg, model, questions, workingDir = process.cwd(), maxTokens = 4096, temperature, signal, onStatus }) {
-  const list = (questions || []).map((q) => String(q).trim()).filter(Boolean);
+/** 执行一次批处理。questions: string[]。返回 { ok, outputFile, results, usage, cost, batchId, deduped }
+ * 省钱 B2：①文本哈希去重（重复问题只提交一次，结果回填全部位置）；②单问超窗口预检（提交前报错，不烧钱）；
+ * ③maxCost 预算上限（提交前按估算费用拦截，超出直接中止不提交）。
+ * @param {{ cfg: any, model: any, questions: any, workingDir?: string, maxTokens?: number, temperature?: any, signal?: any, onStatus?: any, maxCost?: number }} opts */
+export async function runBatch({ cfg, model, questions, workingDir = process.cwd(), maxTokens = 4096, temperature, signal, onStatus, maxCost = 0 }) {
+  const list = (questions || []).map((/** @type {any} */ q) => String(q).trim()).filter(Boolean);
   if (!list.length) return { error: '没有可批处理的问题（每行一个问题）' };
   const pc = resolveProviderConfig(cfg, model);
   if (!pc.apiKey) return { error: `模型 ${model} 没有可用 API Key（mingdao key set ${pc.name}）` };
@@ -97,6 +102,50 @@ export async function runBatch({ cfg, model, questions, workingDir = process.cwd
   // 不再携带完整系统提示（技能清单/用户记忆/AGENTS.md 对无工具批任务毫无意义，1000 问
   // 可白烧 50-80 万 token）；改用一行精简角色提示，剩余能力损失为零。
   const systemPrompt = '你是 MingDao Harness 编程助手。直接针对每个问题给出准确、完整的答案，不要复述问题、不要解释过程。';
+
+  // —— 省钱 B2：文本哈希去重（trim 后逐字节一致视为重复）——
+  const positions = /** @type {Map<string, number[]>} */ (new Map()); // hash → [输入行下标...]
+  const unique = /** @type {string[]} */ ([]);
+  list.forEach((/** @type {string} */ q, /** @type {number} */ i) => {
+    const h = crypto.createHash('sha256').update(q).digest('hex');
+    if (!positions.has(h)) {
+      positions.set(h, [i]);
+      unique.push(q);
+    } else {
+      positions.get(h)?.push(i);
+    }
+  });
+  const posByUniqueIdx = unique.map((/** @type {string} */ q) => positions.get(crypto.createHash('sha256').update(q).digest('hex')) || []);
+  const deduped = list.length - unique.length;
+  if (deduped > 0) onStatus?.(`去重：${deduped} 条重复问题合并（${list.length} → ${unique.length} 条实际提交）`);
+
+  // —— 省钱 B2：单问超窗口预检（估算输入 + max_tokens 超过模型窗口 95% 即报错，绝不提交烧钱）——
+  const preset = modelPreset(model) || {};
+  const windowTokens = Number(preset.budgetTokens) || 128000;
+  const sysTokens = approxTokens(systemPrompt);
+  for (let i = 0; i < unique.length; i++) {
+    const est = sysTokens + approxTokens(unique[i]);
+    if (est + maxTokens > windowTokens * 0.95) {
+      return {
+        error: `第 ${posByUniqueIdx[i][0] + 1} 个问题超窗口：估算输入 ${est} + max_tokens ${maxTokens} > 模型窗口 ${windowTokens}（可 --max-tokens 调小或拆分问题）`,
+      };
+    }
+  }
+
+  // —— 省钱 B2：--max-cost 预算上限（提交前估算拦截）——
+  let estimatedCost = 0;
+  if (maxCost > 0) {
+    const estPrompt = unique.reduce((s, q) => s + sysTokens + approxTokens(q), 0);
+    const estCompletion = unique.length * Math.min(maxTokens, 2048); // 保守按平均 2K 输出估算
+    estimatedCost = estimateBatchCost(model, estPrompt, estCompletion);
+    if (estimatedCost > maxCost) {
+      return {
+        error: `预计费用 ≈¥${estimatedCost.toFixed(4)}（已按半价）超过 --max-cost ¥${maxCost}，已中止提交。可缩小问题集或调高上限。`,
+        estimatedCost,
+      };
+    }
+  }
+
   const bodyTemplate = {
     model,
     messages: null, // 逐行填充
@@ -105,7 +154,7 @@ export async function runBatch({ cfg, model, questions, workingDir = process.cwd
     stream: false,
   };
   const jsonl =
-    list
+    unique
       .map((q, i) =>
         JSON.stringify({
           custom_id: `md-${i}`,
@@ -143,7 +192,7 @@ export async function runBatch({ cfg, model, questions, workingDir = process.cwd
         failures = 0;
       } catch (err) {
         failures += 1;
-        if (failures >= 10) return { error: `轮询失败：${err?.message || err}（任务仍在服务端，ID ${batch.id}）`, batchId: batch.id };
+        if (failures >= 10) return { error: `轮询失败：${(/** @type {any} */ (err))?.message || err}（任务仍在服务端，ID ${batch.id}）`, batchId: batch.id };
         await new Promise((r) => setTimeout(r, Math.min(baseInterval * 1.5 ** failures, 30000)));
         continue;
       }
@@ -164,26 +213,35 @@ export async function runBatch({ cfg, model, questions, workingDir = process.cwd
     }
     onStatus?.('下载结果…');
     const results = await downloadResults(base, apiKey, batch);
-    // 汇总 usage 与费用（batch 半价）
+    // 汇总 usage 与费用（batch 半价）；结果按 custom_id 回填到全部重复位置（省钱 B2）
     let prompt = 0;
     let completion = 0;
-    const outputs = [];
+    const outputs = /** @type {Array<{id: string, content: string}>} */ (new Array(list.length));
     for (const r of results) {
       const body = r?.response?.body || {};
       prompt += body.usage?.prompt_tokens || 0;
       completion += body.usage?.completion_tokens || 0;
       const content = body.choices?.[0]?.message?.content ?? body.choices?.[0]?.text ?? (r?.response?.status_code !== 200 ? `（错误 ${r?.response?.status_code}）` : '');
-      outputs.push({ id: r.custom_id, content: String(content || '').trim() });
+      const m = /^md-(\d+)$/.exec(String(r.custom_id || ''));
+      const ui = m ? Number(m[1]) : -1;
+      const idxs = ui >= 0 && ui < posByUniqueIdx.length ? posByUniqueIdx[ui] : [];
+      for (const pos of idxs) {
+        outputs[pos] = { id: String(pos), content: String(content || '').trim() };
+      }
+    }
+    // 防御：服务端漏回的 custom_id 用占位补全，保证输出行数与输入行数一一对应
+    for (let i = 0; i < outputs.length; i++) {
+      if (!outputs[i]) outputs[i] = { id: String(i), content: '' };
     }
     const usage = { prompt_tokens: prompt, completion_tokens: completion };
     const cost = estimateBatchCost(model, prompt, completion);
     const outFile = path.join(workingDir, `mingdao-batch-result-${Date.now()}.jsonl`);
     fs.writeFileSync(outFile, outputs.map((o) => JSON.stringify(o)).join('\n') + '\n');
     recordCacheStats({ model, prompt, completion, hit: null, miss: null, cost, saved: null, batch: true });
-    onStatus?.(`完成：${outputs.length} 条结果`);
-    return { ok: true, batchId: batch.id, outputFile: outFile, results: outputs, usage, cost, discount: BATCH_DISCOUNT };
+    onStatus?.(`完成：${outputs.length} 条结果${deduped ? `（去重合并 ${deduped} 条）` : ''}`);
+    return { ok: true, batchId: batch.id, outputFile: outFile, results: outputs, usage, cost, discount: BATCH_DISCOUNT, deduped, estimatedCost };
   } catch (err) {
     // 批处理端点不支持（404/405 等）→ 明确告知，不静默
-    return { error: `批处理不可用：${err?.message || err}（该服务商可能不支持 Batch API，可用 config.batchBaseUrl 指定支持的网关）` };
+    return { error: `批处理不可用：${(/** @type {any} */ (err))?.message || err}（该服务商可能不支持 Batch API，可用 config.batchBaseUrl 指定支持的网关）` };
   }
 }