mingdao-harness 0.2.4 → 0.2.6

package/docs/EVALUATION-ROUND2.md

@@ -0,0 +1,58 @@
+# 六方技术评估 · 第二轮甄别与迭代方案（v0.2.5 → v0.2.6）
+
+> 2026-09-02。对 CodeBuddy / MiniMax / Kimi / OfficeACE / workbuddy / CodeArts Agent 六家对
+> MingDao Harness v0.2.5 的评估报告逐条对照真实代码甄别（每份报告均由独立子代理核实：
+> 文件+行号证据、区分「真实缺陷」与「过时/误判/空泛套话」）。已修复项随本轮提交 `20693ee`。
+
+## 一、本轮已修复（按严重度）
+
+### 崩溃类（0.2.2 教训：打包期无声、运行期爆炸）
+1. **域路由 400/403 双写崩溃【最高】**：C1 拆分后 `json()` 无返回值，`return json(...)` 被编排器视为「未处理」→ 兜底 404 对已结束响应二次写入 → Node 18 未捕获 write-after-end 整服务崩溃（CI ubuntu-18 腿连续红灯的真因，报告们误归因于 Windows）。修复：`json()` 返回 truthy。
+2. **reasoning_content 工具轮未完整回传**：DeepSeek thinking_mode 官方要求带 tool_calls 的 assistant 消息在后续请求中原样回传 reasoning_content，否则 400——多轮工具会话真实 API 必崩（mock 测试看不见）。修复：回填完整 reasoning；裁剪逻辑只对纯文本回复生效。
+3. **降级模型零校验**：`downgradeModel` 填错/跨服务商 → provider.chat 必然 400 终止回合。修复：校验同服务商，失败按 block 处理并给修复指引。
+4. **reasoning_effort 无门控**：全局配置发给不支持 reasoning 的模型 → 400。修复：仅 `supportsReasoning` 模型发送；`/think off` 改为显式 `thinking:{type:'disabled'}`（此前 off 无效，pro 默认思考开启）。
+
+### 安全类
+5. **SSRF 域名 DNS 重绑定绕过**：校验不解析域名。修复：`validateRemoteUrl` 对域名做 `dns.lookup` 全量 A/AAAA 复检；IPv6 字面量去括号归一（`[::1]`/`[::ffff:127.0.0.1]` 此前直接放行）。
+6. **readBody limit 形同虚设**：1MB 注释 vs 实际 40MB 全接口。修复：limit 参数生效 + 超限返回真 413（排水保留连接）+ 契约断言；chat 保留 40MB（附件 base64）。
+7. **project 级技能无指纹校验**：仓库投毒可直通提示词注入。修复：project 级同样校验 `.source.json` 指纹（无指纹的旧仓库不受影响）。
+8. **Windows fs-browse 白名单过宽**：家目录覆盖整个用户配置树（AppData）。修复：win32 收紧为 桌面/文档/下载 + 启动/工作目录 + 显式授权；路径比较大小写归一。
+
+### 省钱与正确性类
+9. **护栏在途费用失明**：长回合内统计文件不变，可烧穿日限。修复：回合内累计 usage 保守估算并入检查/前置拦截。
+10. **语义回收缺陷**：>80% 即回收（能塞下也截断丢内容）；回收窗口与被丢弃前缀不相交（白做）。修复：仅真超预算触发 + 按丢弃边界回收 + 只接受变短替换。
+11. **工具 Schema 会话内多次变化破坏前缀缓存**（三家共识）：每轮剥描述 + 只读阶段翻转 + MCP 晚到 → 前缀反复失配。**列入 v0.2.6 计划**（需要在线基准裁决收益，见下）。
+12. **英文任务只读死锁/误路由**：写意图与生成意图正则纯中文，英文会话整回合只读、生成任务落 8192 输出。修复：双语正则 + 路由标注集英文子集（113 条）。
+13. 杂项：PID 归属 `null`（无法校验）不再盲杀；SSE 尾字节并入 buf 统一行解析；原子写陈旧锁回收 TOCTOU 比对；tokenCache 整体清空改 LRU；`todayCost` 读失败返回 null + 一次性告警（不再静默归零）。
+
+### 质量基础设施
+14. CI 补跑 `api-contracts`（此前漏掉）；`run-all` spawn 加 error 监听 + Windows `npm.cmd`；e2e-web 越界用例改用系统目录（Windows %TEMP% 在家目录内的假阴性）。
+
+## 二、下一迭代（v0.2.6）方案
+
+**A. 前缀缓存稳定性（省钱核心，唯一需要「先测量再动手」的项）**
+- A1：会话内工具 Schema 两态冻结——回合首轮定档后恒定（不再逐轮剥描述/MCP 晚到突变），回合间才更新；
+- A2：MCP 预热：启动时 await 连接（带超时，超时本会话冻结工具集）；
+- A3：新建 `test/bench/bench-cost.mjs`——mock 模型费用对照（schema 收益、前缀命中、护栏拦截），把「48%/1/30/半价」营销数字变成可回归断言；
+- A4：`trimMessages` 前沿对齐（P1-1：轮重写头部消息导致前缀整体失配）——在 A3 基准下裁决是否采纳。
+
+**B. 会话与索引扩展**
+- B1：session-index 按会话名分片（>1000 会话时避免全量 JSON.parse）；
+- B2：常量单源化（MAX_CONCURRENT=8 实测值、200KB/5MB 附件上限去重，防 app.js/attachments.js/fs-tools.js 漂移）。
+
+**C. 桌面与 WebUI**
+- C1：面板推开布局（已随本次提交：轨迹/子代理/任务面板以 body class 推开内容区，≤560px 退化为全宽面板；附件行不再被遮挡）；
+- C2：app.js（88KB）原生 ES Modules 零构建拆分（可选，收益=可维护性）。
+
+**D. 文档与门禁**
+- D1：docs/QA-REPORT.md 断言数（14→60+）、CONFIG.md 补 `costGuard.action:'downgrade'`；
+- D2：CI 类型门禁统一为 tsconfig.full.json（现仍跑弱版 tsconfig.json 双轨）。
+
+**E. 缓做/不采纳（已甄别）**
+- sync-server 非 loopback 无 TLS 拒启（需 `--insecure` 逃生门，改行为需用户确认）；87 处空 catch 加 debug 开关（收益低，优先关键路径）；WebUI SPA 拆分；i18n；SQLite（需 Node≥22.5，破坏 18/20 兼容矩阵）；报告中的 roadmap 型空泛项（收益数字无测量依据）。
+
+## 三、验收门槛（防 0.2.2 式回归）
+1. 6 套测试全绿 + api-contracts 每域契约 + 新增 bench-cost 断言；
+2. strict 棘轮 0/0 不回升；覆盖率 ≥60% 门禁；
+3. **每次发版前 CI 打包冒烟（xvfb 真实运行打包产物主进程）**——已固化，不可省略；
+4. 新增「Node 18 兼容」意识：CI 已有 ubuntu-18 腿（本次双写崩溃即由它抓住），任何路由改动必须过该腿。

package/docs/ROADMAP-NEXT.md

@@ -34,11 +34,11 @@
 5. ✅ **评测基准扩充**：压缩质量集（5 组长会话样本 → 压缩 → 关键事实存活断言 + 尾部字节不变）、路由标注集扩至 100 条；bench 断言数 38 → 150+；覆盖率阈值 55% → 60%
 - 版本说明：v0.2.3 被 0.2.2 桌面启动崩溃的紧急修复占用，Phase B 顺延为 v0.2.4。
 
-### Phase C「结构渐进」v0.2.5（约 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 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.4",
+  "version": "0.2.6",
   "description": "MingDao Harness —— 开源智能体框架（Agent Harness）。零依赖、开箱即用，针对 DeepSeek-V4 系列优化，开放主流模型接入。",
   "type": "module",
   "bin": {
@@ -54,7 +54,7 @@
     "desktop": "npm --prefix desktop start",
     "desktop:dist": "node scripts/sync-versions.mjs && npm --prefix desktop run dist:dir",
     "desktop:sync": "node scripts/sync-versions.mjs",
-    "bench": "node test/bench/bench-tokenizer.mjs && node test/bench/bench-routing.mjs && node test/bench/bench-compaction.mjs",
+    "bench": "node test/bench/bench-tokenizer.mjs && node test/bench/bench-routing.mjs && node test/bench/bench-compaction.mjs && node test/bench/bench-cost.mjs",
     "coverage": "node test/run-all.mjs --coverage && node scripts/coverage-report.mjs",
     "typecheck:strict": "node scripts/strict-ratchet.mjs",
     "preversion": "node test/smoke.js && node test/e2e-local.js && npm run bench",

package/src/agent.js

@@ -13,6 +13,7 @@ import { subagentModel } from './routing.js';
 import { writeAudit, redactSecrets } from './audit.js';
 import { checkCostGuard, costGuardConfig, todayCost } from './cost-guard.js';
 import { estimateCost } from './pricing.js';
+import { resolveProviderConfig } from './providers/index.js';
 
 const MAX_STEPS = 24;
 const SUBAGENT_MAX_STEPS = 12;
@@ -29,7 +30,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;
@@ -45,27 +46,30 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
   // 省钱 B1（按需挂载）：回合起始为「只读阶段」时只发只读工具（read/ls/glob/grep/skill/todo）
   // + 已用过的工具；检测到写意图（用户消息或模型明说需要写/改/建）后注入全量工具。
   const READONLY_TIER_SET = new Set(['read', 'ls', 'glob', 'grep', 'skill', 'todo']);
-  const WRITE_INTENT_RE = /写|建|创|改|修|删|装|加|添|增|补|换|移|部署|执行|运行|实现|重构|生成|迁移|安装|更新|升级|发布|调整|优化|修复|提交|推送|打包|编译|测试/;
+  // 中英双语写意图（CodeArts 报告：纯中文正则让英文会话整回合只读死锁）
+  const WRITE_INTENT_RE = /写|建|创|改|修|删|装|加|添|增|补|换|移|部署|执行|运行|实现|重构|生成|迁移|安装|更新|升级|发布|调整|优化|修复|提交|推送|打包|编译|测试|implement|fix|create|modify|update|delete|deploy|build|make|generate|install|write|refactor|migrate|test|run|commit|push|remove|add|change|patch/i;
   const hasWriteIntent = (/** @type {any} */ text) => WRITE_INTENT_RE.test(String(text || ''));
-  const toolsFor = (/** @type {boolean} */ readOnlyPhase) => {
-    const schemas = buildToolSchemas(usedToolNames, mcpSchemas());
+  // A1（前缀稳定）：剥描述集合按「回合冻结快照」——回合内恒定（至多两态：只读档/全量档），
+  // 新使用的工具只在下一回合才进入剥描述集合；回合边界本身就有新 user 消息，schema 变化免费。
+  const toolsFor = (/** @type {boolean} */ readOnlyPhase, /** @type {Set<string>} */ strippedSet) => {
+    const schemas = buildToolSchemas(strippedSet, 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 (READONLY_TIER_SET.has(n) || strippedSet.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({
@@ -110,19 +114,19 @@ 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;
+    let firstTokenAt = /** @type {any} */ (null);
     // 省钱 B3（费用二级分账）：推理 token 估算（按增量累计）与逐工具调用/耗时累加
     let reasoningTokens = 0;
     const toolStats = /** @type {Map<string, {calls: number, ms: number}>} */ (new Map());
@@ -137,11 +141,18 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
     });
     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;
+    // 护栏在途费用（MiniMax P0）：本回合已累计 usage 的保守估算（无缓存折扣），
+    // 护栏检查/前置拦截时并入今日已用——否则长回合内统计文件不变，可烧穿日限。
+    const inFlightCost = () => estimateCost(activeModel, usage.prompt_tokens, usage.completion_tokens, null, new Date());
+    const usedTodayWithInflight = () => {
+      const today = todayCost();
+      return today == null ? null : today + inFlightCost();
+    };
     // 省钱 B1：本回合只读阶段判定——最新用户消息无写意图则先只发只读工具，
     // 模型明确表达写意图后（下一轮）注入全量。cfg.schemaTier=false 可关。
     let readOnlyPhase = true;
@@ -151,6 +162,8 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
     } else {
       readOnlyPhase = false;
     }
+    // A1：本回合的剥描述冻结快照（会话级 usedToolNames 的副本）——回合内 schema 字节不变
+    const turnStrippedSet = new Set(usedToolNames);
     // 整个回合注册一次 SIGINT：思考、工具执行、权限询问期间都能中断
     const offSigint = io.onSigint ? io.onSigint(() => { aborted = true; currentAc?.abort(); }) : () => {};
     const ctx = makeCtx();
@@ -197,15 +210,17 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
       }
       const trimmed = trimMessages(messages, budget, count);
 
-      // reasoning 回填防护（MiniMax P0-2）：推理链只在 UI 流式展示、不回传消息（本就不回填）；
-      // 防御性保证——任何携带 reasoning_content 的消息发送前裁剪：>4000 字仅留概括，>1000 字截尾 500。
+      // reasoning 回填防护（Kimi P0 修正）：带 tool_calls 的 assistant 消息必须「完整」回传
+      // reasoning_content（DeepSeek thinking_mode 官方要求：后续请求含 tools 时缺/截断即 400，
+      // 多轮工具会话必崩）；仅纯文本回复的 reasoning 可裁剪（不回传也不影响）。
       let sanitized = trimmed;
       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));
-        } else if (typeof rc === 'string' && rc.length > 1000) {
-          sanitized = sanitized.map((x) => (x === m ? { ...x, reasoning_content: rc.slice(-500) + ' …[思考过程已截断]' } : x));
+        if (typeof rc !== 'string' || (Array.isArray(m.tool_calls) && m.tool_calls.length)) continue;
+        if (rc.length > 4000) {
+          sanitized = sanitized.map((/** @type {any} */ x) => (x === m ? { ...x, reasoning_content: `[思考过程已省略（原 ${rc.length} 字）]` } : x));
+        } else if (rc.length > 1000) {
+          sanitized = sanitized.map((/** @type {any} */ x) => (x === m ? { ...x, reasoning_content: rc.slice(-500) + ' …[思考过程已截断]' } : x));
         }
       }
 
@@ -219,8 +234,10 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           let promptTokens = 0;
           for (const m of sanitized) promptTokens += messageTokens(m, count);
           const worst = estimateCost(activeModel, promptTokens, maxOutput, null, new Date());
-          const used = todayCost();
-          if (used + worst >= Number(g.dailyLimitYuan)) {
+          const used = usedTodayWithInflight(); // 含本回合在途费用（防长回合烧穿）
+          if (used == null) {
+            // todayCost 读取失败：无法判断，跳过前置拦截（护栏主检查同样跳过并告警）
+          } else if (used + worst >= Number(g.dailyLimitYuan)) {
             stripOrphanCalls();
             return {
               text: null, reasoning: '', usage, steps, finish, truncated: false, aborted: false,
@@ -253,15 +270,29 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           }
           if (guard.downgrade && !downgraded) {
             if (guard.downgradeModel !== activeModel) {
-              activeModel = guard.downgradeModel;
-              downgraded = true;
-              io.print(style(guard.message, C.yellow));
+              // MiniMax P0：降级目标零校验会崩溃——必须与当前模型同服务商且已有 Key，
+              // 否则 provider.chat 必然 400；校验失败按 block 处理并给修复指引。
+              const curPc = resolveProviderConfig(cfg, activeModel);
+              const dgPc = resolveProviderConfig(cfg, guard.downgradeModel);
+              // Key 归属服务商（provider 级），同服务商即天然共享同一 Key，无需再查 apiKey
+              if (dgPc && dgPc.name === curPc.name) {
+                activeModel = guard.downgradeModel;
+                downgraded = true;
+                io.print(style(guard.message, C.yellow));
+              } else {
+                stripOrphanCalls();
+                return {
+                  text: null, reasoning: '', usage, steps, finish, truncated: false, aborted: false,
+                  note: `费用护栏想降级到 ${guard.downgradeModel}，但它与当前服务商不一致或缺少 API Key——已暂停执行。请把 config.costGuard.downgradeModel 改为与当前模型同服务商（当前：${curPc.name}）的模型名，或调高 dailyLimitYuan。`,
+                  durationMs: Date.now() - startedAt, perf: perf(),
+                };
+              }
             } else {
               // 已经是降级目标模型：无法再降，按 block 处理
               stripOrphanCalls();
               return {
                 text: null, reasoning: '', usage, steps, finish, truncated: false, aborted: false,
-                note: `今日费用已达上限（实际 ¥${String(todayCost().toFixed(4))}），且已在最便宜模型上执行，已暂停——调整 config.costGuard 或明天自动恢复。`,
+                note: `今日费用已达上限（实际 ¥${String((todayCost() ?? 0).toFixed(4))}），且已在最便宜模型上执行，已暂停——调整 config.costGuard 或明天自动恢复。`,
                 durationMs: Date.now() - startedAt, perf: perf(),
               };
             }
@@ -284,12 +315,13 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
         res = await provider.chat({
           model: activeModel,
           messages: sanitized,
-          tools: toolsFor(readOnlyPhase),
+          tools: toolsFor(readOnlyPhase, turnStrippedSet),
           temperature,
           maxTokens: maxOutput,
-          reasoningEffort,
+          // MiniMax P0：仅当 activeModel 声明支持 reasoning 才发送（否则 400 终止回合）；'off' 显式禁用例外
+          reasoningEffort: modelPreset(activeModel)?.supportsReasoning || reasoningEffort === 'off' ? reasoningEffort : undefined,
           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);
@@ -328,7 +360,13 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
 
       if (res.toolCalls?.length) {
         io.endTurn();
-        const assistantMsg = { role: 'assistant', content: res.text || null, tool_calls: res.toolCalls };
+        const assistantMsg = {
+          role: 'assistant',
+          content: res.text || null,
+          tool_calls: res.toolCalls,
+          // Kimi P0：带工具调用的消息必须携带完整 reasoning_content（否则下一轮 400）
+          ...(res.toolCalls?.length && res.reasoning ? { reasoning_content: res.reasoning } : {}),
+        };
         messages.push(assistantMsg);
 
         // 只读工具并行（P2-8）：同一 response 里的连续 read/ls/glob/grep 无相互依赖，
@@ -339,7 +377,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;
@@ -353,7 +391,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 {
@@ -403,7 +441,7 @@ 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;
@@ -421,13 +459,13 @@ 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 维度）
@@ -473,7 +511,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;
@@ -601,7 +639,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/atomic-write.js

@@ -57,10 +57,16 @@ export function withFileLockSync(/** @type {string} */ lockPath, /** @type {() =
       try {
         const st = fs.statSync(lockPath);
         if (Date.now() - st.mtimeMs > staleMs) {
+          // TOCTOU 防护（OfficeACE 报告）：unlink 前读锁内容并二次 stat 比对，
+          // 防两个进程同时判定陈旧、后者误删前者刚创建的新锁（互斥失效）
           try {
-            fs.unlinkSync(lockPath);
+            const before = fs.readFileSync(lockPath, 'utf8');
+            const st2 = fs.statSync(lockPath);
+            if (st2.mtimeMs === st.mtimeMs && before === fs.readFileSync(lockPath, 'utf8')) {
+              fs.unlinkSync(lockPath);
+            }
           } catch {}
-          continue; // 回收陈旧锁后立即重试
+          continue; // 无论是否回收成功都重试一次（若锁刚被他人更新则继续等待）
         }
       } catch {
         continue; // 锁文件刚被释放

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

@@ -19,7 +19,7 @@ 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);
@@ -29,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}` },
@@ -44,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');
@@ -62,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`,
@@ -92,7 +92,7 @@ async function downloadResults(base, apiKey, batch) {
  * ③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((q) => String(q).trim()).filter(Boolean);
+  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}）` };
@@ -192,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;
       }
@@ -242,6 +242,6 @@ export async function runBatch({ cfg, model, questions, workingDir = process.cwd
     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 指定支持的网关）` };
   }
 }

package/src/cachestats.js

@@ -16,7 +16,7 @@ const MAX_LINES = 20000;
 const KEEP_LINES = 10000;
 let cacheStatsCount = 0;
 
-export function recordCacheStats(entry) {
+export function recordCacheStats(/** @type {any} */ entry) {
   try {
     ensureHome(); // 审计 B10：与 audit/journal 一致，目录缺失不静默丢统计
     const line = JSON.stringify({
@@ -54,13 +54,13 @@ export function recordCacheStats(entry) {
 // listCacheStats 读取缓存（审计：costGuard 每步 / WebUI 每 15s / /cost 命令都调用——
 // 四报告共识 P2-2/§3.3-A：全文件读+逐行 parse 会随 JSONL 增长线性放大 IO。
 // 按 mtimeMs+size 双键缓存；写入追加会改两者，轮转重写同样改，缓存自动失效）
-let _statsCache = null;
+let /** @type {any} */ _statsCache = null;
 
 export function listCacheStats(limit = 2000) {
   try {
     const file = cacheStatsFile();
     const st = fs.statSync(file);
-    if (!_statsCache || _statsCache.mtimeMs !== st.mtimeMs || _statsCache.size !== st.size || _statsCache.limit < limit) {
+    if (!/** @type {any} */ _statsCache || _statsCache.mtimeMs !== st.mtimeMs || _statsCache.size !== st.size || _statsCache.limit < limit) {
       const raw = fs.readFileSync(file, 'utf8');
       const out = [];
       for (const l of raw.split('\n')) {
@@ -77,8 +77,8 @@ export function listCacheStats(limit = 2000) {
   }
 }
 
-export function summarizeCacheStats(entries) {
-  const sum = { turns: entries.length, prompt: 0, completion: 0, hit: 0, miss: 0, cost: 0, saved: 0, steps: 0, llmMs: 0, toolMs: 0, firstTokenCount: 0, firstTokenSumMs: 0 };
+export function summarizeCacheStats(/** @type {any} */ entries) {
+  const sum = /** @type {any} */ ({ turns: entries.length, prompt: 0, completion: 0, hit: 0, miss: 0, cost: 0, saved: 0, steps: 0, llmMs: 0, toolMs: 0, firstTokenCount: 0, firstTokenSumMs: 0 });
   for (const e of entries) {
     sum.prompt += e.prompt || 0;
     sum.completion += e.completion || 0;
@@ -102,7 +102,7 @@ export function summarizeCacheStats(entries) {
 
 // 记录一次用量（agent 侧调用）：自动计算命中拆分与节省额
 // 记录一次用量（agent 侧调用）：自动计算命中拆分与节省额；perf 为回合性能指标（状态栏）
-export function recordUsage(modelName, usage, perf = null) {
+export function recordUsage(/** @type {any} */ modelName, /** @type {any} */ usage, /** @type {any} */ perf = null) {
   const split = cacheSplit(usage);
   const prompt = usage?.prompt_tokens || 0;
   const completion = usage?.completion_tokens || 0;
@@ -132,8 +132,8 @@ export function recordUsage(modelName, usage, perf = null) {
   });
 }
 
-export function formatCacheSummary(sum) {
-  const fmt = (n) => (n >= 1000 ? (n / 1000).toFixed(1) + 'k' : String(n));
+export function formatCacheSummary(/** @type {any} */ sum) {
+  const fmt = (/** @type {any} */ n) => (n >= 1000 ? (n / 1000).toFixed(1) + 'k' : String(n));
   const lines = [
     `轮次  ${sum.turns} · ↑${fmt(sum.prompt)} ↓${fmt(sum.completion)} tokens`,
     `缓存命中率  ${sum.rate != null ? (sum.rate * 100).toFixed(0) + '%' : '暂无缓存数据'}`,
@@ -213,7 +213,7 @@ export function costBreakdown() {
 
 // 月度费用报告（/cost 导出）：按北京时间月份聚合，month 形如 'YYYY-MM'，缺省返回全部月份
 // 省钱 B3：月度聚合增加 reasoning 与 byTool 维度
-export function costMonthlyReport(month) {
+export function costMonthlyReport(/** @type {any} */ month) {
   const entries = listCacheStats(100000);
   const want = String(month || '').trim();
   const months = new Map();