mingdao-harness 0.2.4 → 0.2.5

package/src/providers/openai-compatible.js

@@ -6,9 +6,9 @@
  * @typedef {Error & { status?: number, headers?: Headers }} ApiError
  */
 
-export async function chat({ baseUrl, apiKey, model, messages, tools, temperature, maxTokens, signal, onDelta, includeUsage = true, responseFormat, reasoningEffort }) {
+export async function chat(/** @type {any} */ { baseUrl, apiKey, model, messages, tools, temperature, maxTokens, signal, onDelta, includeUsage = true, responseFormat, reasoningEffort }) {
   const url = String(baseUrl).replace(/\/+$/, '') + '/chat/completions';
-  const payload = { model, messages };
+  const payload = /** @type {Record<string, any>} */ ({ model, messages });
   if (temperature != null) payload.temperature = temperature;
   if (tools && tools.length) {
     payload.tools = tools;
@@ -36,7 +36,7 @@ export async function chat({ baseUrl, apiKey, model, messages, tools, temperatur
     });
   } catch (err) {
     /** @type {ApiError} */
-    const e = new Error(`网络请求失败：${err?.message || err}`);
+    const e = new Error(`网络请求失败：${(/** @type {any} */ (err))?.message || err}`);
     e.status = 0;
     throw e;
   }
@@ -64,7 +64,7 @@ export async function chat({ baseUrl, apiKey, model, messages, tools, temperatur
   return parseStream(res.body, onDelta);
 }
 
-export function parseNonStream(json, onDelta) {
+export function parseNonStream(/** @type {any} */ json, /** @type {any} */ onDelta) {
   const choice = json?.choices?.[0];
   const msg = choice?.message ?? {};
   if (msg.content) onDelta?.({ text: msg.content });
@@ -80,7 +80,7 @@ export function parseNonStream(json, onDelta) {
 }
 
 // 解析 SSE 流：处理跨 chunk 断行、增量 content / reasoning_content / tool_calls。
-export async function parseStream(body, onDelta) {
+export async function parseStream(/** @type {any} */ body, /** @type {any} */ onDelta) {
   const reader = body.getReader();
   const decoder = new TextDecoder();
   let buf = '';
@@ -90,15 +90,15 @@ export async function parseStream(body, onDelta) {
   const indexKeys = new Map(); // index -> key（id 只在首片出现，后续分片按 index 找回同一条目）
   let autoKey = 0;
   let usage = null;
-  let finish = null;
+  let /** @type {any} */ finish = null;
 
   let doneFlag = false;
-  const handleLine = (lineRaw) => {
+  const handleLine = (/** @type {any} */ lineRaw) => {
     const line = lineRaw.trim();
     if (!line.startsWith('data:')) return;
     const data = line.slice(5).trim();
     if (data === '[DONE]') {
-      finish = finish || 'stop';
+      finish = /** @type {any} */ finish || 'stop';
       doneFlag = true;
       return true; // 通知外层终止读取（审计 P2-4：[DONE] 后不再消费残帧、不挂到超时）
     }

package/src/routing.js

@@ -9,7 +9,7 @@
 import crypto from 'node:crypto';
 import { modelPreset } from './models.js';
 
-export function routingConfig(cfg) {
+export function routingConfig(/** @type {any} */ cfg) {
   const r = cfg?.routing;
   if (!r || r.enabled === false) return null;
   const planner = r.planner || 'deepseek-v4-pro';
@@ -25,7 +25,7 @@ const PLAN_HINTS =
 const GENERATION_HINTS =
   /(生成|制作|编写|创建|写|开发|实现|做).{0,30}(游戏|网页|页面|网站|应用|程序|文档|报告|简历|PPT|演示|完整|详细|小工具)|网页版|游戏/;
 
-export function heuristicRoute(text, rc) {
+export function heuristicRoute(/** @type {any} */ text, /** @type {any} */ rc) {
   const s = String(text ?? '');
   if (GENERATION_HINTS.test(s)) return rc.planner; // 生成类：大输出优先
   if (PLAN_HINTS.test(s)) {
@@ -41,7 +41,7 @@ export function heuristicRoute(text, rc) {
 const ROUTE_CACHE_MAX = 100;
 const routeCache = new Map();
 
-export async function routeTask({ cfg, provider, currentModel, text, sticky = null, sessionStats = null }) {
+export async function routeTask(/** @type {any} */ { cfg, provider, currentModel, text, sticky = null, sessionStats = null }) {
   const rc = routingConfig(cfg);
   if (!rc) return { model: currentModel, reason: null };
   // 当前模型已在路由池外（用户手动指定）：不干预
@@ -59,7 +59,7 @@ export async function routeTask({ cfg, provider, currentModel, text, sticky = nu
   // 会话粘滞 + 升级检测（Hermes C2）：执行类会话不再逐轮分类（生成类关键词已在启发式拦截），
   // 但会话内复杂度信号累积（工具步数/截断次数）时允许升级 planner——「开头简单、中途复杂」不再被 flash 硬扛。
   if (sticky === rc.executor) {
-    const stats = sessionStats || {};
+    const stats = /** @type {any} */ (sessionStats || {});
     const steps = Number(stats.steps) || 0;
     const truncated = Number(stats.truncated) || 0;
     const UPGRADE_STEPS = Number(cfg?.routing?.upgradeSteps) || 10;
@@ -140,7 +140,7 @@ export async function routeTask({ cfg, provider, currentModel, text, sticky = nu
 }
 
 // 子代理模型选择：路由开启时固定 executor
-export function subagentModel(cfg, currentModel) {
+export function subagentModel(/** @type {any} */ cfg, /** @type {any} */ currentModel) {
   const rc = routingConfig(cfg);
   if (!rc) return currentModel;
   return modelPreset(rc.executor) ? rc.executor : currentModel;

package/src/schedule.js

@@ -11,7 +11,7 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { startTask, readTask, killTask } from './tasks.js';
 
-function isRunningTask(home, taskId) {
+function isRunningTask(/** @type {any} */ home, /** @type {any} */ taskId) {
   const t = readTask(home, taskId);
   return Boolean(t && t.status === 'running');
 }
@@ -21,21 +21,21 @@ const CLI_PATH = fileURLToPath(new URL('./cli.js', import.meta.url));
 import { isPeakHour, deferToOffpeak } from './pricing.js';
 import { atomicWriteFileSync, withFileLockSync } from './atomic-write.js';
 
-export function scheduleDir(home) {
+export function scheduleDir(/** @type {any} */ home) {
   return path.join(home, 'schedule');
 }
 
-export function parseInterval(s) {
+export function parseInterval(/** @type {any} */ s) {
   const m = /^(\d+)(s|m|h|d)$/.exec(String(s).trim());
   if (!m) return null;
   const n = Number(m[1]);
-  const unit = { s: 1000, m: 60000, h: 3600000, d: 86400000 }[m[2]];
+  const unit = /** @type {Record<string, number>} */ ({ s: 1000, m: 60000, h: 3600000, d: 86400000 })[m[2]];
   if (!(n > 0)) return null;
   return n * unit;
 }
 
 // 解析 --at：'YYYY-MM-DD HH:MM' 或 'HH:MM'（今天；已过则明天）
-export function parseAt(s) {
+export function parseAt(/** @type {any} */ s) {
   const t = String(s).trim();
   const full = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})$/.exec(t);
   if (full) {
@@ -56,7 +56,7 @@ export function parseAt(s) {
   return null;
 }
 
-export function listSchedules(home) {
+export function listSchedules(/** @type {any} */ home) {
   const dir = scheduleDir(home);
   let files;
   try {
@@ -74,11 +74,11 @@ export function listSchedules(home) {
   return out.sort((a, b) => (a.nextRunAt || 0) - (b.nextRunAt || 0));
 }
 
-function isValidScheduleId(id) {
+function isValidScheduleId(/** @type {any} */ id) {
   return typeof id === 'string' && /^[a-z0-9]+$/.test(id) && id.length >= 2 && id.length <= 40;
 }
 
-export function readSchedule(home, id) {
+export function readSchedule(/** @type {any} */ home, /** @type {any} */ id) {
   if (!isValidScheduleId(id)) return null; // 防 id 路径穿越
   try {
     return JSON.parse(fs.readFileSync(path.join(scheduleDir(home), id + '.json'), 'utf8'));
@@ -87,7 +87,7 @@ export function readSchedule(home, id) {
   }
 }
 
-export function writeSchedule(home, job) {
+export function writeSchedule(/** @type {any} */ home, /** @type {any} */ job) {
   if (!isValidScheduleId(job?.id)) return null;
   fs.mkdirSync(scheduleDir(home), { recursive: true });
   const target = path.join(scheduleDir(home), job.id + '.json');
@@ -96,7 +96,7 @@ export function writeSchedule(home, job) {
 }
 
 /** 新建调度任务；after: 依赖的任务 ID（全部成功后才启动，任一失败则跳过） */
-export function addSchedule(home, question, /** @type {any} */ { at, every, after, permission, model, cwd, anchor, offpeak }) {
+export function addSchedule(/** @type {any} */ home, /** @type {any} */ question, /** @type {any} */ { at, every, after, permission, model, cwd, anchor, offpeak }) {
   const id = 'sc' + Date.now().toString(36) + Math.random().toString(36).slice(2, 5);
   const interval = every != null ? parseInterval(every) : null;
   const afterList = Array.isArray(after) ? after.filter(Boolean).map(String) : after ? String(after).split(',').map((x) => x.trim()).filter(Boolean) : [];
@@ -147,7 +147,7 @@ export function addSchedule(home, question, /** @type {any} */ { at, every, afte
 // 质检 H2（pause 失效确定性回归）：runOnce 返回后的状态决策抽为纯函数——
 // 用户在执行期间 pause/remove 的指令（paused/failed/文件已删）绝不被 pending 覆盖；
 // 连续失败 3 次熔断；否则排下一次（锚点对齐避免逐日漂移）。
-export function postRunStatus(cur2, result) {
+export function postRunStatus(/** @type {any} */ cur2, /** @type {any} */ result) {
   if (!cur2) return null;
   if (cur2.status === 'paused' || cur2.status === 'failed') return null;
   if (result !== 'done' && (cur2.consecutiveFailures || 0) >= 3) {
@@ -157,7 +157,7 @@ export function postRunStatus(cur2, result) {
   return { status: 'pending', nextRunAt: next };
 }
 
-export function removeSchedule(home, id) {
+export function removeSchedule(/** @type {any} */ home, /** @type {any} */ id) {
   // 质检 H3：读-改-写序列加锁，与 sleeper 循环的状态写互斥（防丢更新）
   return withFileLockSync(path.join(scheduleDir(home), '.lock'), () => {
     const job = readSchedule(home, id);
@@ -179,7 +179,7 @@ export function removeSchedule(home, id) {
   });
 }
 
-export function pauseSchedule(home, id) {
+export function pauseSchedule(/** @type {any} */ home, /** @type {any} */ id) {
   // 质检 H3：读-改-写序列加锁（pause 与 sleeper 的 postRunStatus 写互斥，杜绝 pause 被覆盖）
   return withFileLockSync(path.join(scheduleDir(home), '.lock'), () => {
     const job = readSchedule(home, id);
@@ -198,7 +198,7 @@ export function pauseSchedule(home, id) {
   });
 }
 
-export function resumeSchedule(home, id) {
+export function resumeSchedule(/** @type {any} */ home, /** @type {any} */ id) {
   const job = readSchedule(home, id);
   if (!job || job.status !== 'paused') return false;
   let next = job.nextRunAt;
@@ -215,7 +215,7 @@ export function resumeSchedule(home, id) {
 }
 
 // 每日锚点：锚点时刻（HH:MM）对齐到 now 之后的最近一次
-function nextAnchorAfter(anchor, interval) {
+function nextAnchorAfter(/** @type {any} */ anchor, /** @type {any} */ interval) {
   const a = parseAt(anchor);
   if (a == null) return null;
   let n = a;
@@ -224,7 +224,7 @@ function nextAnchorAfter(anchor, interval) {
 }
 
 // 链式编排：A→B→C，后者依赖前者成功
-export function chainSchedules(home, questions, opts = {}) {
+export function chainSchedules(/** @type {any} */ home, /** @type {any} */ questions, opts = {}) {
   const ids = [];
   let prev = null;
   for (const q of questions) {
@@ -237,7 +237,7 @@ export function chainSchedules(home, questions, opts = {}) {
   return { ids };
 }
 
-export function sleeperAlive(pid) {
+export function sleeperAlive(/** @type {any} */ pid) {
   if (!pid) return false;
   try {
     process.kill(pid, 0);
@@ -247,7 +247,7 @@ export function sleeperAlive(pid) {
   }
 }
 
-function spawnSleeper(home, job) {
+function spawnSleeper(/** @type {any} */ home, /** @type {any} */ job) {
   const child = spawn(process.execPath, [CLI_PATH, 'schedule-worker', job.id], {
     detached: true,
     stdio: 'ignore',
@@ -260,12 +260,12 @@ function spawnSleeper(home, job) {
 }
 
 // —— 单守护进程调度器（评估 P3-5）：一进程监督全部任务 ——
-export function daemonPidFile(home) {
+export function daemonPidFile(/** @type {any} */ home) {
   return path.join(scheduleDir(home), 'daemon.pid');
 }
 // pid 文件内容 "pid nonce"：校验进程存在 + 命令行含同一 nonce，防止陈旧 PID 被无关进程复用而误判（审计 P2-7）
 // 质检 M11：kill 前校验 PID 归属（/proc/<pid>/cmdline 含 needle 才动手，防 PID 复用误杀）
-function pidOwnedBy(pid, needle) {
+function pidOwnedBy(/** @type {any} */ pid, /** @type {any} */ needle) {
   try {
     const cmdline = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8');
     return cmdline.includes(needle);
@@ -274,7 +274,7 @@ function pidOwnedBy(pid, needle) {
   }
 }
 
-export function daemonAlive(home) {
+export function daemonAlive(/** @type {any} */ home) {
   try {
     const [pidStr, nonce] = fs.readFileSync(daemonPidFile(home), 'utf8').trim().split(/\s+/);
     const pid = Number(pidStr);
@@ -291,7 +291,7 @@ export function daemonAlive(home) {
     return false;
   }
 }
-export function stopDaemon(home) {
+export function stopDaemon(/** @type {any} */ home) {
   try {
     const pid = Number(fs.readFileSync(daemonPidFile(home), 'utf8'));
     if (pid) {
@@ -305,7 +305,7 @@ export function stopDaemon(home) {
   } catch {}
   return true;
 }
-export function spawnDaemon(home) {
+export function spawnDaemon(/** @type {any} */ home) {
   if (daemonAlive(home)) return true;
   const nonce = Math.random().toString(36).slice(2, 10);
   const child = spawn(process.execPath, [CLI_PATH, 'schedule-daemon', nonce], {
@@ -324,7 +324,7 @@ export function spawnDaemon(home) {
 }
 
 // 重启自愈：有非终态任务且 daemon 不在 → 拉起单守护（失败才回退旧式逐任务 sleeper）
-export function reconcileSchedules(home) {
+export function reconcileSchedules(/** @type {any} */ home) {
   const jobs = listSchedules(home);
   const hasPending = jobs.some((j) => j.status === 'pending' || j.status === 'running');
   if (!hasPending) return;
@@ -343,14 +343,14 @@ export function reconcileSchedules(home) {
   spawnDaemon(home);
 }
 // —— sleeper 主循环（schedule-worker 进程内运行）——
-export async function runSleeper(home, id) {
+export async function runSleeper(/** @type {any} */ home, /** @type {any} */ id) {
   const job = readSchedule(home, id);
   if (!job) return;
 
-  const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+  const wait = (/** @type {any} */ ms) => new Promise((r) => setTimeout(r, ms));
 
   // 依赖检查：支持两种依赖——调度任务 id（chain 编排）或后台任务 id（mingdao run 输出）
-  async function depsSatisfied(deps) {
+  async function depsSatisfied(/** @type {any} */ deps) {
     for (const dep of deps) {
       const sch = readSchedule(home, dep);
       if (sch) {
@@ -476,7 +476,7 @@ export async function runSleeper(home, id) {
   }
 }
 
-export function formatScheduleRow(j) {
+export function formatScheduleRow(/** @type {any} */ j) {
   const mark = j.status === 'pending' ? '⏳' : j.status === 'running' ? '▶' : j.status === 'paused' ? '⏸' : j.status === 'done' ? '✓' : '✖';
   const when =
     j.kind === 'every'

package/src/session-index.js

@@ -25,6 +25,7 @@ export function loadSessionIndex() {
   }
 }
 
+/** @param {any} idx */
 export function saveSessionIndex(idx) {
   try {
     ensureHome();
@@ -34,9 +35,10 @@ export function saveSessionIndex(idx) {
 }
 
 // 分词：ASCII 词（小写）+ 中文 bigram + 中文单字；返回 Map<词, 次数>
+/** @param {any} text */
 export function tokenize(text) {
   const terms = new Map();
-  const add = (t) => {
+  const add = (/** @type {any} */ t) => {
     if (t) terms.set(t, (terms.get(t) || 0) + 1);
   };
   const s = String(text ?? '');
@@ -61,6 +63,7 @@ export function tokenize(text) {
 }
 
 // 从会话文件提取可检索文本（user/assistant 内容拼接）
+/** @param {any} file */
 export function extractSessionText(file) {
   const parts = [];
   for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
@@ -79,6 +82,7 @@ export function extractSessionText(file) {
 }
 
 // 增量同步索引（对比 mtime/size，只重算变化的文件；清理已删除条目）
+/** @param {any} home @param {any} sessions */
 export function syncSessionIndex(home, sessions) {
   const idx = loadSessionIndex();
   const dir = path.join(home, 'sessions');

package/src/session.js

@@ -4,6 +4,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+/** @param {any} home */
 export function listSessions(home) {
   const dir = path.join(home, 'sessions');
   try {
@@ -20,10 +21,12 @@ export function listSessions(home) {
   }
 }
 
+/** @param {any} home */
 export function latestSession(home) {
   return listSessions(home)[0] || null;
 }
 
+/** @param {any} home */
 export function createSession(home) {
   const dir = path.join(home, 'sessions');
   fs.mkdirSync(dir, { recursive: true });
@@ -33,18 +36,21 @@ export function createSession(home) {
   return { file, name: path.basename(file) };
 }
 
+/** @param {any} file @param {any} messages */
 export function appendMessages(file, messages) {
   if (!messages?.length) return;
-  const lines = messages.map((m) => JSON.stringify(m)).join('\n') + '\n';
+  const lines = messages.map((/** @type {any} */ m) => JSON.stringify(m)).join('\n') + '\n';
   fs.appendFileSync(file, lines);
 }
 
 // 整文件原子重写：自动压缩后把会话文件同步为压缩形态（否则每次加载历史都会重新触发压缩）
+/** @param {any} file @param {any} messages */
 export function rewriteSession(file, messages) {
-  const lines = messages.map((m) => JSON.stringify(m)).join('\n');
+  const lines = messages.map((/** @type {any} */ m) => JSON.stringify(m)).join('\n');
   atomicWriteFileSync(file, lines + (lines ? '\n' : ''), { mode: 0o600 }); // 质检 H4：会话文件原子写
 }
 
+/** @param {any} file */
 export function loadSession(file) {
   const raw = fs.readFileSync(file, 'utf8');
   const messages = [];
@@ -61,6 +67,7 @@ export function loadSession(file) {
 }
 
 // 会话预览：第一条用户消息（用于会话选择器）
+/** @param {any} file */
 export function sessionPreview(file) {
   try {
     const raw = fs.readFileSync(file, 'utf8');
@@ -79,6 +86,7 @@ export function sessionPreview(file) {
   }
 }
 
+/** @param {any} mtime */
 export function relativeTime(mtime) {
   const diff = Date.now() - mtime;
   if (diff < 60000) return '刚刚';
@@ -92,6 +100,7 @@ export function relativeTime(mtime) {
 import { syncSessionIndex, tokenize, extractSessionText } from './session-index.js';
 import { atomicWriteFileSync } from './atomic-write.js';
 
+/** @param {any} home @param {any} keyword */
 export function searchSessions(home, keyword, { limit = 20 } = {}) {
   const kw = String(keyword ?? '').trim();
   if (!kw) return listSessions(home).slice(0, limit);

package/src/skill-lib.js

@@ -22,8 +22,13 @@ const LIB_DIR = fileURLToPath(new URL('../skills-lib', import.meta.url));
 // ---------- 完整性（P3-3）：技能目录联合哈希 ----------
 // 对目录内全部文件（排除 .mingdao-source.json 自身）按相对路径排序，
 // 逐文件 sha256 后拼成 "rel:hash\n" 再取一次 sha256，作为目录内容指纹。
+/**
+ * @param {any} dir
+ */
 export function skillDirHash(dir) {
+  /** @type {any[]} */
   const out = [];
+  /** @type {(d: any, base: any) => void} */
   const walk = (d, base) => {
     let entries;
     try {
@@ -47,6 +52,9 @@ export function skillDirHash(dir) {
     .digest('hex');
 }
 
+/**
+ * @param {any} dir
+ */
 export function readSourceMeta(dir) {
   try {
     return JSON.parse(fs.readFileSync(path.join(dir, '.mingdao-source.json'), 'utf8'));
@@ -55,11 +63,18 @@ export function readSourceMeta(dir) {
   }
 }
 
+/**
+ * @param {any} dir
+ * @param {any} meta
+ */
 export function writeSourceMeta(dir, meta) {
   fs.writeFileSync(path.join(dir, '.mingdao-source.json'), JSON.stringify(meta, null, 2) + '\n', { mode: 0o600 });
 }
 
 // 显式信任当前内容（用户改过 registry/library 安装的技能后重新记录指纹）
+/**
+ * @param {any} name
+ */
 export function trustSkill(name) {
   const target = path.join(userSkillsDir(), name);
   const meta = readSourceMeta(target);
@@ -79,6 +94,10 @@ export function userSkillsDir() {
 }
 
 // 从技能目录读取 name / description（frontmatter 优先，回退标题/目录名）
+/**
+ * @param {any} dir
+ * @returns {any}
+ */
 function readSkillMeta(dir) {
   try {
     const text = fs.readFileSync(path.join(dir, 'SKILL.md'), 'utf8');
@@ -116,6 +135,7 @@ export function installedUserSkillNames() {
 
 export function libraryList() {
   const installed = installedUserSkillNames();
+  /** @type {any[]} */
   const out = [];
   let entries;
   try {
@@ -132,6 +152,9 @@ export function libraryList() {
   return out.sort((a, b) => a.name.localeCompare(b.name));
 }
 
+/**
+ * @param {any} kw
+ */
 export function searchLibrary(kw) {
   const k = String(kw || '').trim().toLowerCase();
   return libraryList().filter(
@@ -144,6 +167,10 @@ export function searchLibrary(kw) {
 //  - name：字母/数字/连字符/点/下划线，1–64 位
 //  - description：非空且 ≤ 200 字
 // 校验失败返回具体错误，绝不装入技能目录。
+/**
+ * @param {any} text
+ * @param {any} hint
+ */
 export function validateSkillMarkdown(text, hint) {
   const src = hint ? `（${hint}）` : '';
   if (!text || !String(text).trim()) return { error: `SKILL.md 为空${src}` };
@@ -159,6 +186,10 @@ export function validateSkillMarkdown(text, hint) {
   return { ok: true, name, description: desc };
 }
 
+/**
+ * @param {any} dir
+ * @param {any} hint
+ */
 export function validateSkillDir(dir, hint) {
   const skillMd = path.join(dir, 'SKILL.md');
   let text;
@@ -170,6 +201,12 @@ export function validateSkillDir(dir, hint) {
   return validateSkillMarkdown(text, hint);
 }
 
+/**
+ * @param {any} dir
+ * @param {any} name
+ * @param {any} source
+ * @param {any} extra
+ */
 function copySkillIntoUser(dir, name, source, extra) {
   ensureHome();
   const target = path.join(userSkillsDir(), name);
@@ -188,12 +225,18 @@ function copySkillIntoUser(dir, name, source, extra) {
   return { name, dir: target };
 }
 
+/**
+ * @param {any} name
+ */
 export function installFromLibrary(name) {
   const found = libraryList().find((s) => s.name === name);
   if (!found) return { error: `技能库中没有 ${name}（mingdao skill search 查看全部）` };
   return copySkillIntoUser(found.dir, found.name, 'library', {});
 }
 
+/**
+ * @param {any} dir
+ */
 export function installFromDir(dir) {
   const abs = path.resolve(dir);
   if (!fs.existsSync(path.join(abs, 'SKILL.md'))) {
@@ -204,6 +247,9 @@ export function installFromDir(dir) {
   return copySkillIntoUser(abs, meta.name, 'dir', { from: abs });
 }
 
+/**
+ * @param {any} url
+ */
 export async function installFromUrl(url) {
   let u;
   try {
@@ -222,7 +268,7 @@ export async function installFromUrl(url) {
     if (!res.ok) return { error: `下载失败：HTTP ${res.status}` };
     text = await res.text();
     if (text.length > 512 * 1024) return { error: 'SKILL.md 超过 512KB 上限' };
-  } catch (e) {
+  } catch (/** @type {any} */ e) {
     return { error: `下载失败：${e.name === 'AbortError' ? '30 秒超时' : e.message}` };
   } finally {
     clearTimeout(timer);
@@ -244,6 +290,9 @@ export async function installFromUrl(url) {
   return r;
 }
 
+/**
+ * @param {any} gitUrl
+ */
 export function installFromGit(gitUrl) {
   if (typeof gitUrl !== 'string' || gitUrl.trim().startsWith('-')) {
     return { error: 'git 地址不能以 - 开头（防选项注入）' };
@@ -262,7 +311,8 @@ export function installFromGit(gitUrl) {
   const found = [];
   const stack = [tmp];
   while (stack.length && found.length < 20) {
-    const dir = stack.pop();
+    const dir = /** @type {any} */ (stack.pop());
+    /** @type {any[]} */
     let entries = [];
     try {
       entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -297,6 +347,9 @@ export function installFromGit(gitUrl) {
   return { names: installed.map((i) => i.name), dirs: installed.map((i) => i.dir), skipped };
 }
 
+/**
+ * @param {any} name
+ */
 export function uninstallSkill(name) {
   const key = String(name).trim();
   // '.'/'..' 会拼出上级目录，必须硬拒绝（正则 [A-Za-z0-9_.-]+ 会放行纯点号名）
@@ -310,9 +363,12 @@ export function uninstallSkill(name) {
 }
 
 // 按元数据来源重新安装（库：重新复制；url：重新下载；git：重新克隆）
+/**
+ * @param {any} name
+ */
 export async function reinstallSkill(name) {
   const target = path.join(userSkillsDir(), name);
-  let meta = {};
+  let meta = /** @type {any} */ ({});
   try {
     meta = JSON.parse(fs.readFileSync(path.join(target, '.mingdao-source.json'), 'utf8'));
   } catch {
@@ -330,6 +386,9 @@ export async function reinstallSkill(name) {
 }
 
 // 统一入口：自动识别 库名 | 本地目录 | SKILL.md URL | git 仓库
+/**
+ * @param {any} arg
+ */
 export async function installSkill(arg) {
   const a = String(arg || '').trim();
   if (!a) return { error: '缺少参数：mingdao skill install <库名|目录|SKILL.md URL|git 仓库地址>' };

package/src/skill-registry.js

@@ -42,14 +42,14 @@ function loadCache() {
   }
 }
 
-function saveCache(data, host) {
+function saveCache(/** @type {any} */ data, /** @type {any} */ host) {
   try {
     ensureHome();
     fs.writeFileSync(cacheFile(), JSON.stringify({ fetchedAt: Date.now(), host, data }, null, 2) + '\n', { mode: 0o600 });
   } catch {}
 }
 
-async function fetchText(url, timeoutMs = 20000, maxBytes = 2 * 1024 * 1024) {
+async function fetchText(/** @type {any} */ url, timeoutMs = 20000, maxBytes = 2 * 1024 * 1024) {
   const ctrl = new AbortController();
   const timer = setTimeout(() => ctrl.abort(), timeoutMs);
   try {
@@ -91,26 +91,26 @@ export async function fetchRegistryIndex({ force = false, allowNetwork = true }
   }
   // 网络失败时回退旧缓存（过期也可用）
   if (cached?.data?.skills) return { data: cached.data, host: cached.host, fromCache: true, stale: true };
-  return { error: `无法获取线上技能库：${lastErr?.message || '网络不可达'}（可用 MINGDAO_REGISTRY_URL 指向自建 registry）` };
+  return { error: `无法获取线上技能库：${(/** @type {any} */ (lastErr))?.message || '网络不可达'}（可用 MINGDAO_REGISTRY_URL 指向自建 registry）` };
 }
 
 // 远端搜索（合并展示：name/description/source/installed）
-export async function searchRegistry(kw, { force = false, allowNetwork = true } = {}) {
+export async function searchRegistry(/** @type {any} */ kw, { force = false, allowNetwork = true } = {}) {
   const r = await fetchRegistryIndex({ force, allowNetwork });
   if (r.error) return { error: r.error };
   const k = String(kw || '').trim().toLowerCase();
   const installed = installedUserSkillNames();
   const skills = r.data.skills
-    .filter((s) => !k || s.name.toLowerCase().includes(k) || (s.description || '').toLowerCase().includes(k))
-    .map((s) => ({ name: s.name, description: s.description, source: 'registry', installed: installed.has(s.name) }));
+    .filter((/** @type {any} */ s) => !k || s.name.toLowerCase().includes(k) || (s.description || '').toLowerCase().includes(k))
+    .map((/** @type {any} */ s) => ({ name: s.name, description: s.description, source: 'registry', installed: installed.has(s.name) }));
   return { skills, host: r.host, updatedAt: r.data.updatedAt, fromCache: r.fromCache, stale: r.stale || false };
 }
 
 // 按索引安装（逐文件下载 + dry-run 校验）
-export async function installFromRegistry(name) {
+export async function installFromRegistry(/** @type {any} */ name) {
   const r = await fetchRegistryIndex();
   if (r.error) return { error: r.error };
-  const entry = r.data.skills.find((s) => s.name === name);
+  const entry = r.data.skills.find((/** @type {any} */ s) => s.name === name);
   if (!entry) return { error: `线上技能库中没有 ${name}（mingdao skill search 查看）` };
   if (!Array.isArray(entry.files) || !entry.files.length) return { error: `技能 ${name} 的索引缺少文件清单` };
 
@@ -134,7 +134,8 @@ export async function installFromRegistry(name) {
           text = await fetchText(`${host}/skills-lib/${encodeURI(name)}/${rel.split('/').map(encodeURIComponent).join('/')}`, 30000, MAX_FILE);
           break;
         } catch (e) {
-          lastErr = e?.name === 'AbortError' ? '下载超时' : String(e?.message || e);
+          const ee = /** @type {any} */ (e);
+          lastErr = ee?.name === 'AbortError' ? '下载超时' : String(ee?.message || ee);
         }
       }
       if (text === null) return { error: `下载 ${name}/${rel} 失败：${lastErr}（已尝试全部镜像）` };