mingdao-harness 0.2.4 → 0.2.5

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.5",
   "description": "MingDao Harness —— 开源智能体框架（Agent Harness）。零依赖、开箱即用，针对 DeepSeek-V4 系列优化，开放主流模型接入。",
   "type": "module",
   "bin": {

package/src/agent.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;
@@ -60,12 +60,12 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
   };
 
   // 子代理：全新上下文 + 同一 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 +110,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,7 +137,7 @@ 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;
@@ -203,9 +203,9 @@ 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));
         }
       }
 
@@ -289,7 +289,7 @@ export function createAgent({ provider, permission, io, modelName, workingDir, c
           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);
@@ -339,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;
@@ -353,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 {
@@ -403,7 +403,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 +421,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 +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;
@@ -601,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

@@ -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();