mingdao-harness 0.2.4 → 0.2.5

package/src/tools/fs-tools.js

@@ -9,11 +9,18 @@ const MAX_GLOB_RESULTS = 1000;
 const MAX_GREP_MATCHES = 250;
 const MAX_FILE_BYTES = 5 * 1024 * 1024;
 
+/**
+ * @param {any} cwd
+ * @param {any} p
+ */
 function resolvePath(cwd, p) {
   if (path.isAbsolute(p)) return path.normalize(p);
   return path.resolve(cwd, p);
 }
 
+/**
+ * @param {any} buf
+ */
 function isProbablyBinary(buf) {
   const head = buf.subarray(0, 8192);
   for (let i = 0; i < head.length; i++) {
@@ -25,6 +32,10 @@ function isProbablyBinary(buf) {
 // —— undo 备份（会话级，每文件最多 10 份 + 全局上限，质检 M9） ——
 const UNDO_MAX_FILES = 64;
 const UNDO_MAX_BYTES = 20 * 1024 * 1024;
+/**
+ * @param {any} ctx
+ * @param {any} p
+ */
 function backup(ctx, p) {
   try {
     const store = ctx?.undoStore?.backups;
@@ -57,6 +68,10 @@ function backup(ctx, p) {
   } catch {}
 }
 
+/**
+ * @param {any} args
+ * @param {any} ctx
+ */
 export function undo(args, ctx) {
   const store = ctx?.undoStore?.backups;
   if (!(store instanceof Map) || !store.size) return { ok: false, error: '没有可撤销的修改。' };
@@ -68,7 +83,7 @@ export function undo(args, ctx) {
     try {
       fs.writeFileSync(p, last.content);
       return { ok: true, output: `已撤销 ${p} 的最近一次修改（该文件剩余备份 ${list.length} 个）。` };
-    } catch (err) {
+    } catch (/** @type {any} */ err) {
       return { ok: false, error: `撤销失败：${err?.message || err}` };
     }
   }
@@ -87,7 +102,7 @@ export function undo(args, ctx) {
   try {
     fs.writeFileSync(latestFile, last.content);
     return { ok: true, output: `已撤销 ${latestFile} 的最近一次修改。` };
-  } catch (err) {
+  } catch (/** @type {any} */ err) {
     return { ok: false, error: `撤销失败：${err?.message || err}` };
   }
 }
@@ -95,10 +110,17 @@ export function undo(args, ctx) {
 const READ_CACHE_MAX = 200; // 会话级 read 缓存条数上限（超出清最旧，防止无界增长）
 const readCache = new Map(); // 绝对路径 → { mtimeMs, size, lines }
 
+/**
+ * @param {any} p
+ */
 export function invalidateReadCache(p) {
   readCache.delete(p);
 }
 
+/**
+ * @param {any} args
+ * @param {any} ctx
+ */
 export function read(args, ctx) {
   try {
     const p = resolvePath(ctx.cwd, args.path ?? '');
@@ -145,13 +167,17 @@ export function read(args, ctx) {
         out.join('\n') + (truncated ? `\n…[共 ${lines.length} 行，已显示第 ${offset}-${end} 行]` : ''),
       totalLines: lines.length,
     };
-  } catch (err) {
+  } catch (/** @type {any} */ err) {
     return { ok: false, error: `读取失败：${err?.message || err}` };
   }
 }
 
 const MAX_WRITE_BYTES = 2 * 1024 * 1024; // write 单次内容上限（防模型输出超大文件打爆磁盘）
 
+/**
+ * @param {any} args
+ * @param {any} ctx
+ */
 export function write(args, ctx) {
   try {
     const p = resolvePath(ctx.cwd, args.path ?? '');
@@ -171,12 +197,17 @@ export function write(args, ctx) {
     fs.writeFileSync(p, content);
     invalidateReadCache(p);
     return { ok: true, output: `已写入 ${p}（${Buffer.byteLength(content)} 字节）。` };
-  } catch (err) {
+  } catch (/** @type {any} */ err) {
     return { ok: false, error: `写入失败：${err?.message || err}` };
   }
 }
 
 // 提取替换区域（含上下文），供 TUI 渲染变更预览
+/**
+ * @param {any} text
+ * @param {any} lineStart
+ * @param {any} lineCount
+ */
 function regionAround(text, lineStart, lineCount, context = 2) {
   const lines = text.split('\n');
   const from = Math.max(0, lineStart - context);
@@ -184,6 +215,10 @@ function regionAround(text, lineStart, lineCount, context = 2) {
   return lines.slice(from, to).join('\n');
 }
 
+/**
+ * @param {any} args
+ * @param {any} ctx
+ */
 export function edit(args, ctx) {
   try {
     const p = resolvePath(ctx.cwd, args.path ?? '');
@@ -218,11 +253,15 @@ export function edit(args, ctx) {
       output: `已编辑 ${p}（替换 ${count} 处）。`,
       diff: { before, after },
     };
-  } catch (err) {
+  } catch (/** @type {any} */ err) {
     return { ok: false, error: `编辑失败：${err?.message || err}` };
   }
 }
 
+/**
+ * @param {any} args
+ * @param {any} ctx
+ */
 export function ls(args, ctx) {
   try {
     const p = resolvePath(ctx.cwd, args.path || '.');
@@ -243,11 +282,14 @@ export function ls(args, ctx) {
         return ad - bd || a.localeCompare(b);
       });
     return { ok: true, output: rows.join('\n') || '(空目录)' };
-  } catch (err) {
+  } catch (/** @type {any} */ err) {
     return { ok: false, error: `列目录失败：${err?.message || err}` };
   }
 }
 
+/**
+ * @param {any} pattern
+ */
 function globToRegExp(pattern) {
   let re = '';
   for (let i = 0; i < pattern.length; i++) {
@@ -275,6 +317,10 @@ function globToRegExp(pattern) {
   return new RegExp('^' + re + '$');
 }
 
+/**
+ * @param {any} root
+ * @param {(full: any) => any} visitor
+ */
 function walkFiles(root, visitor) {
   const stack = [root];
   let scanned = 0;
@@ -300,6 +346,10 @@ function walkFiles(root, visitor) {
   return scanned;
 }
 
+/**
+ * @param {any} args
+ * @param {any} ctx
+ */
 export function glob(args, ctx) {
   try {
     const pattern = String(args.pattern ?? '*');
@@ -307,6 +357,7 @@ export function glob(args, ctx) {
     if (!fs.existsSync(root)) return { ok: false, error: `目录不存在：${root}` };
     const re = globToRegExp(pattern);
     const matchRel = pattern.includes('/');
+    /** @type {any[]} */
     const results = [];
     let truncated = false;
     walkFiles(root, (full) => {
@@ -321,11 +372,15 @@ export function glob(args, ctx) {
     if (!results.length) output = '(无匹配)';
     if (truncated) output += `\n…[结果超过 ${MAX_GLOB_RESULTS} 条，已截断]`;
     return { ok: true, output };
-  } catch (err) {
+  } catch (/** @type {any} */ err) {
     return { ok: false, error: `glob 失败：${err?.message || err}` };
   }
 }
 
+/**
+ * @param {any} args
+ * @param {any} ctx
+ */
 export function grep(args, ctx) {
   try {
     const pattern = String(args.pattern ?? '');
@@ -338,14 +393,16 @@ export function grep(args, ctx) {
     let re;
     try {
       re = new RegExp(pattern);
-    } catch (e) {
+    } catch (/** @type {any} */ e) {
       return { ok: false, error: `无效的正则表达式：${e.message}` };
     }
     // 单行截断：超长行（如压缩的 JS/日志）截到 20KB 再匹配，防止正则开销失控
     const MAX_LINE = 20 * 1024;
+    /** @type {(line: any) => any} */
     const testLine = (line) => (line.length > MAX_LINE ? re.test(line.slice(0, MAX_LINE)) : re.test(line));
     const root = resolvePath(ctx.cwd, args.path || '.');
     const include = args.include ? globToRegExp(String(args.include)) : null;
+    /** @type {any[]} */
     const matches = [];
     let truncated = false;
     let scannedFiles = 0;
@@ -386,7 +443,7 @@ export function grep(args, ctx) {
       ? `\n…[匹配超过 ${MAX_GREP_MATCHES} 条，已截断；已扫描 ${scannedFiles} 个文件]`
       : `\n[已扫描 ${scannedFiles} 个文件]`;
     return { ok: true, output };
-  } catch (err) {
+  } catch (/** @type {any} */ err) {
     return { ok: false, error: `grep 失败：${err?.message || err}` };
   }
 }

package/src/tools/index.js

@@ -252,10 +252,10 @@ export function buildToolSchemas(usedNames, extra = []) {
   return [...strip(TOOLS), ...strip(extra)];
 }
 
-function runSkill(args, ctx) {
+function runSkill(/** @type {any} */ args, /** @type {any} */ ctx) {
   const name = String(args.name ?? '').trim();
   const skills = listSkills(ctx.workingDir);
-  const label = (s) => `${s.name}${s.source === 'user' ? '（用户级）' : s.source === 'builtin' ? '（内置）' : ''}`;
+  const label = (/** @type {any} */ s) => `${s.name}${s.source === 'user' ? '（用户级）' : s.source === 'builtin' ? '（内置）' : ''}`;
   if (!name) {
     return {
       ok: true,
@@ -271,7 +271,7 @@ function runSkill(args, ctx) {
   return { ok: true, output: `技能 ${name}${s.source === 'builtin' ? '（内置）' : ''}（${s.path}）：\n\n${s.content}` };
 }
 
-async function runTask(args, ctx) {
+async function runTask(/** @type {any} */ args, /** @type {any} */ ctx) {
   const prompt = String(args.prompt ?? '');
   const description = String(args.description ?? '');
   if (!prompt) return { ok: false, error: '缺少 prompt 参数。' };
@@ -280,11 +280,11 @@ async function runTask(args, ctx) {
     const out = await ctx.spawnTask(prompt, { description, readOnly: args.readOnly === true });
     return { ok: true, output: out };
   } catch (err) {
-    return { ok: false, error: `子任务失败：${err?.message || err}` };
+    return { ok: false, error: `子任务失败：${(/** @type {any} */ (err))?.message || err}` };
   }
 }
 
-function runTodo(args, ctx) {
+function runTodo(/** @type {any} */ args, /** @type {any} */ ctx) {
   const list = Array.isArray(args.todos) ? args.todos : [];
   if (Array.isArray(ctx.todos)) {
     ctx.todos.splice(0, ctx.todos.length, ...list);
@@ -293,12 +293,12 @@ function runTodo(args, ctx) {
     ok: true,
     output:
       `任务清单已更新（${list.length} 项）：\n` +
-      list.map((t) => `- [${t.status || 'pending'}] ${t.content}`).join('\n'),
+      list.map((/** @type {any} */ t) => `- [${t.status || 'pending'}] ${t.content}`).join('\n'),
     todos: list,
   };
 }
 
-export async function dispatch(name, args, ctx) {
+export async function dispatch(/** @type {any} */ name, /** @type {any} */ args, /** @type {any} */ ctx) {
   switch (name) {
     case 'read':
       return read(args, ctx);

package/src/ui.js

@@ -26,6 +26,10 @@ export const C = {
 
 const stdoutTTY = () => Boolean(process.stdout.isTTY);
 
+/**
+ * @param {any} text
+ * @param {any} code
+ */
 export function style(text, code) {
   if (!stdoutTTY()) {
     // 非 TTY（管道/重定向）：剥离所有内嵌 ANSI 码，保证输出干净可解析
@@ -35,10 +39,11 @@ export function style(text, code) {
 }
 
 // ---------- 终端显示宽度（CJK 占 2 列） ----------
+/** @param {any} s */
 function displayWidth(s) {
   let w = 0;
   for (const ch of String(s)) {
-    const c = ch.codePointAt(0);
+    const c = /** @type {any} */ (ch.codePointAt(0));
     const wide =
       c >= 0x1100 &&
       (c <= 0x115f ||
@@ -57,10 +62,18 @@ function displayWidth(s) {
   return w;
 }
 
+/**
+ * @param {any} s
+ * @param {any} w
+ */
 function padTo(s, w) {
   return String(s) + ' '.repeat(Math.max(0, w - displayWidth(s)));
 }
 
+/**
+ * @param {any} s
+ * @param {any} prefix
+ */
 function indent(s, prefix) {
   return String(s)
     .split('\n')
@@ -70,6 +83,7 @@ function indent(s, prefix) {
 
 // ---------- 轻量代码高亮 ----------
 const HASH_LANGS = new Set(['py', 'python', 'sh', 'bash', 'yaml', 'yml', 'toml', 'markdown', 'md']);
+/** @type {Record<string, string[]>} */
 const LANG_KEYWORDS = {
   js: ['const', 'let', 'var', 'function', 'return', 'if', 'else', 'for', 'while', 'import', 'from', 'export', 'default', 'class', 'extends', 'new', 'await', 'async', 'try', 'catch', 'finally', 'throw', 'typeof', 'instanceof', 'null', 'undefined', 'true', 'false', 'this', 'super', 'switch', 'case', 'break', 'continue', 'do', 'of', 'in', 'static', 'get', 'set', 'delete', 'void', 'yield'],
   ts: ['interface', 'type', 'enum', 'implements', 'readonly', 'private', 'public', 'protected', 'namespace', 'declare', 'as', 'any', 'unknown', 'never', 'string', 'number', 'boolean'],
@@ -83,6 +97,10 @@ const LANG_KEYWORDS = {
   yaml: [],
 };
 
+/**
+ * @param {any} code
+ * @param {any} lang
+ */
 export function highlightCode(code, lang = '') {
   if (!stdoutTTY()) return code;
   const kws = new Set([...(LANG_KEYWORDS[lang] || []), ...(LANG_KEYWORDS[lang.replace(/-.*/, '')] || [])]);
@@ -117,6 +135,7 @@ export function highlightCode(code, lang = '') {
 }
 
 // ---------- Markdown 行内样式 ----------
+/** @param {any} s */
 function inline(s) {
   const parts = [];
   const re = /(`[^`]+`|\*\*[^*]+\*\*|\*[^*\s][^*]*\*)/g;
@@ -134,6 +153,7 @@ function inline(s) {
   return parts.join('');
 }
 
+/** @param {any} line */
 function renderInline(line) {
   const trimmed = line.trim();
   if (/^#{1,6}\s/.test(trimmed)) return style(inline(line), C.bold + C.cyan);
@@ -145,13 +165,16 @@ function renderInline(line) {
 }
 
 // ---------- 流式渲染器 ----------
+/** @param {any} io */
 function createStreamRenderer(io) {
   let buf = '';
   let inCode = false;
   let lang = '';
+  /** @type {any[]} */
   let codeLines = [];
   let streamed = false;
 
+  /** @param {any} line */
   function renderLine(line) {
     const trimmed = line.trim();
     if (trimmed.startsWith('```')) {
@@ -174,6 +197,7 @@ function createStreamRenderer(io) {
   }
 
   return {
+    /** @param {any} text */
     push(text) {
       streamed = true;
       buf += String(text);
@@ -202,6 +226,10 @@ function createStreamRenderer(io) {
 }
 
 // ---------- 行级 diff（编辑预览用，仅小区域） ----------
+/**
+ * @param {any} a
+ * @param {any} b
+ */
 function diffLines(a, b) {
   const n = a.length;
   const m = b.length;
@@ -253,6 +281,7 @@ const COMMANDS = [
   '/quit',
 ];
 
+/** @param {any} line */
 function completeLine(line) {
   if (line.startsWith('/model ') && line.length >= 7) {
     const pre = line.slice(7);
@@ -261,6 +290,10 @@ function completeLine(line) {
   return [COMMANDS.filter((c) => c.startsWith(line)), line];
 }
 
+/**
+ * @param {any} name
+ * @param {any} args
+ */
 function summarizeArgs(name, args) {
   try {
     if (name === 'bash') return ` ${args.command ?? ''}`;
@@ -274,12 +307,19 @@ function summarizeArgs(name, args) {
 
 // ---------- io 工厂 ----------
 export function createIO({ quiet = false } = {}) {
+  /** @type {any} */
   let rl = null;
+  /** @type {any} */
   let spinnerTimer = null;
+  /** @type {any} */
   let renderer = null;
+  /** @type {any[]} */
   let askQueue = []; // 非 TTY：挂起的输入请求
+  /** @type {any[]} */
   let lineQueue = []; // 非 TTY：已缓冲但未被消费的行
+  /** @type {any} */
   let sigintHandler = null; // TTY 下 rl 'SIGINT' 事件转发目标
+  /** @type {any} */
   let ttyPending = null;
   let closed = false;
 
@@ -291,6 +331,7 @@ export function createIO({ quiet = false } = {}) {
     isTTY: Boolean(process.stdin.isTTY),
     showReasoning: true,
 
+    /** @param {any} v */
     setShowReasoning(v) {
       io.showReasoning = !!v;
     },
@@ -304,7 +345,7 @@ export function createIO({ quiet = false } = {}) {
           output: process.stdout,
           terminal,
           historySize: 200,
-          completer: (line) => completeLine(line),
+          completer: (/** @type {any} */ line) => completeLine(line),
         });
         if (terminal) {
           // 关键：TTY 下 Ctrl+C 由 readline 捕获（raw 模式），需要在这里转发给中断处理器；
@@ -321,7 +362,7 @@ export function createIO({ quiet = false } = {}) {
         }
         if (!terminal) {
           // 非 TTY（管道输入）：持久 line 监听 + 队列，避免 rl.question 丢弃首行之后的输入
-          rl.on('line', (line) => {
+          rl.on('line', (/** @type {any} */ line) => {
             const trimmed = line.trim();
             const pending = askQueue.shift();
             if (pending) pending.resolve(trimmed);
@@ -344,6 +385,7 @@ export function createIO({ quiet = false } = {}) {
       return rl;
     },
 
+    /** @param {any} lines */
     setHistory(lines) {
       try {
         const r = io.ensureRl();
@@ -357,6 +399,10 @@ export function createIO({ quiet = false } = {}) {
       if (!quiet) console.log(text);
     },
 
+    /**
+     * @param {any} title
+     * @param {any} lines
+     */
     box(title, lines) {
       if (quiet) return;
       if (!stdoutTTY()) {
@@ -389,6 +435,7 @@ export function createIO({ quiet = false } = {}) {
       io.stopSpinner();
     },
 
+    /** @param {any} label */
     startSpinner(label) {
       if (quiet || !stdoutTTY()) return;
       io.stopSpinner();
@@ -408,6 +455,7 @@ export function createIO({ quiet = false } = {}) {
       }
     },
 
+    /** @param {any} text */
     writeText(text) {
       if (quiet) return;
       if (io._reasoningStarted && !io._answerStarted && stdoutTTY()) {
@@ -417,6 +465,7 @@ export function createIO({ quiet = false } = {}) {
       renderer?.push(String(text));
     },
 
+    /** @param {any} text */
     writeReasoning(text) {
       if (quiet || !io.showReasoning) return;
       if (!io._reasoningStarted) {
@@ -426,6 +475,7 @@ export function createIO({ quiet = false } = {}) {
       process.stdout.write(style(String(text), C.dim));
     },
 
+    /** @param {any} todos */
     renderTodo(todos) {
       if (quiet || !todos?.length) return;
       io.print(style('  ☑ 任务清单', C.bold));
@@ -436,6 +486,10 @@ export function createIO({ quiet = false } = {}) {
       }
     },
 
+    /**
+     * @param {any} code
+     * @param {any} lang
+     */
     printCodeBlock(code, lang) {
       if (quiet) return;
       const label = lang || 'code';
@@ -446,6 +500,12 @@ export function createIO({ quiet = false } = {}) {
     },
 
     // —— 工具执行可视化 ——
+    /**
+     * @param {any} name
+     * @param {any} args
+     * @param {any} result
+     * @param {any} durationMs
+     */
     renderTool(name, args, result, durationMs) {
       if (quiet) return;
       const r = result && typeof result === 'object' ? result : { ok: false, error: String(result ?? '') };
@@ -525,6 +585,11 @@ export function createIO({ quiet = false } = {}) {
       io.print(style(`  ✓ 输出 ${out.length} 字符${ms}`, C.green));
     },
 
+    /**
+     * @param {any} name
+     * @param {any} args
+     * @param {any} reason
+     */
     renderToolDenied(name, args, reason) {
       if (quiet) return;
       const label = reason === '未授权' || !reason ? '未授权，已跳过' : reason;
@@ -532,11 +597,12 @@ export function createIO({ quiet = false } = {}) {
     },
 
     // —— 用量与费用状态行 ——
+    /** @param {{ modelName: any, usage: any, durationMs: any }} param0 */
     printUsageLine({ modelName, usage, durationMs }) {
       if (quiet) return;
       const p = usage?.prompt_tokens ?? 0;
       const c = usage?.completion_tokens ?? 0;
-      const fmt = (n) => (n >= 1000 ? (n / 1000).toFixed(1) + 'k' : String(n));
+      const fmt = (/** @type {any} */ n) => (n >= 1000 ? (n / 1000).toFixed(1) + 'k' : String(n));
       const secs = ((durationMs ?? 0) / 1000).toFixed(1) + 's';
       const costPart = estimateCostLabel(modelName, p, c, usage);
       io.print(
@@ -550,6 +616,7 @@ export function createIO({ quiet = false } = {}) {
     // —— SIGINT（Ctrl+C 中断生成，不退出程序） ——
     // TTY 下 readline raw 模式会把 Ctrl+C 转成 rl 的 'SIGINT' 事件（ensureRl 转发到 sigintHandler），
     // 非 TTY/其他来源走 process 级 SIGINT；两层都注册，保证任何路径都能中断
+    /** @param {any} fn */
     onSigint(fn) {
       const h = () => {
         try {
@@ -564,6 +631,10 @@ export function createIO({ quiet = false } = {}) {
       };
     },
 
+    /**
+     * @param {any} question
+     * @param {any} opts
+     */
     ask(question, opts = {}) {
       if (!process.stdin.isTTY) {
         // 非 TTY：优先消费已缓冲的行（接口关闭后仍可能有剩余行），不打印提示符
@@ -592,7 +663,7 @@ export function createIO({ quiet = false } = {}) {
         }
         const entry = { resolve, restore };
         ttyPending = entry;
-        r.question(question, (answer) => {
+        r.question(question, (/** @type {any} */ answer) => {
           restore();
           if (ttyPending === entry) ttyPending = null;
           resolve(answer.trim());
@@ -601,6 +672,7 @@ export function createIO({ quiet = false } = {}) {
     },
 
     // 行尾反斜杠续行，支持多行输入
+    /** @param {any} prompt */
     async askMultiline(prompt, continuation = '…> ') {
       const lines = [];
       for (;;) {
@@ -615,14 +687,19 @@ export function createIO({ quiet = false } = {}) {
       }
     },
 
+    /** @param {any} question */
     async confirm(question) {
       const a = await io.ask(question + ' ');
       return /^y(es)?$/i.test(a);
     },
 
+    /**
+     * @param {any} label
+     * @param {any} options
+     */
     async choose(label, options) {
       io.print(style(label, C.bold));
-      options.forEach((o, i) => io.print(`  ${style(String(i + 1), C.cyan)}. ${o.label}`));
+      options.forEach((/** @type {any} */ o, /** @type {any} */ i) => io.print(`  ${style(String(i + 1), C.cyan)}. ${o.label}`));
       for (;;) {
         const ans = await io.ask('请输入序号：');
         const n = Number(ans);

package/src/update.js

@@ -12,7 +12,7 @@ import { fileURLToPath } from 'node:url';
 import { mingdaoHome, ensureHome } from './config.js';
 import { atomicWriteFileSync } from './atomic-write.js';
 
-function git(args, cwd) {
+function git(/** @type {any} */ args, /** @type {any} */ cwd) {
   const r = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 120000 });
   return {
     ok: r.status === 0 && !r.error,
@@ -36,11 +36,11 @@ export function findRepoRoot() {
   return null;
 }
 
-function resolveRepo(override) {
+function resolveRepo(/** @type {any} */ override) {
   return override || findRepoRoot();
 }
 
-function versionAt(repo, ref = 'HEAD') {
+function versionAt(/** @type {any} */ repo, ref = 'HEAD') {
   const r = git(['show', `${ref}:package.json`], repo);
   if (!r.ok) return null;
   try {
@@ -50,7 +50,7 @@ function versionAt(repo, ref = 'HEAD') {
   }
 }
 
-function compareVersions(a, b) {
+function compareVersions(/** @type {any} */ a, /** @type {any} */ b) {
   const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
   const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
   for (let i = 0; i < 3; i++) {
@@ -71,7 +71,7 @@ function readState() {
     return null;
   }
 }
-function writeState(s) {
+function writeState(/** @type {any} */ s) {
   ensureHome();
   atomicWriteFileSync(stateFile(), JSON.stringify(s, null, 2) + '\n', { mode: 0o600 }); // 质检 H4：更新状态原子写
 }
@@ -79,20 +79,20 @@ function writeState(s) {
 // 直接向远端指定分支要版本（评估 D6）：fetch 到 FETCH_HEAD 再读 package.json，
 // 不依赖本地 refs 落盘——部分 Windows git 环境存在「fetch 成功但 refs 不更新」的异常，
 // 按本地 refs 判断会误报「已是最新」。ls-remote 思路的等价实现。
-function remoteVersion(repo, remote, branch) {
+function remoteVersion(/** @type {any} */ repo, /** @type {any} */ remote, /** @type {any} */ branch) {
   const r = git(['fetch', '--quiet', remote, branch], repo);
   if (!r.ok) return null;
   return versionAt(repo, 'FETCH_HEAD');
 }
 
-function listRemotes(repo) {
+function listRemotes(/** @type {any} */ repo) {
   const r = git(['remote'], repo);
   if (!r.ok) return [];
   return r.out.split('\n').filter(Boolean);
 }
 
 // 各远端（main/master 任一存在）中版本号最大的（多镜像部署：github/gitee/gitcode 谁新跟谁）
-function newestRemote(repo) {
+function newestRemote(/** @type {any} */ repo) {
   let latest = '';
   let ref = '';
   for (const remote of listRemotes(repo)) {

package/src/web/attachments.js

@@ -7,7 +7,7 @@
 const MAX_IMAGE_DATAURL = 7 * 1024 * 1024; // base64 膨胀 1.33 倍，对应约 5MB 原图
 const MAX_TEXT = 200 * 1024;
 
-export function buildUserContent(message, attachments, visionSupported) {
+export function buildUserContent(/** @type {any} */ message, /** @type {any} */ attachments, /** @type {any} */ visionSupported) {
   const text = String(message ?? '').trim();
   const list = Array.isArray(attachments) ? attachments.slice(0, 4) : [];
   const imageParts = [];