mingdao-harness 0.2.4 → 0.2.6

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}（已尝试全部镜像）` };

package/src/skills.js

@@ -15,7 +15,7 @@ import { skillDirHash, readSourceMeta } from './skill-lib.js';
 
 const BUILTIN_DIR = fileURLToPath(new URL('../skills', import.meta.url));
 
-export function skillDirs(workingDir) {
+export function skillDirs(/** @type {any} */ workingDir) {
   return [
     { dir: path.join(mingdaoHome(), 'skills'), source: 'user' },
     { dir: path.join(workingDir, '.mingdao', 'skills'), source: 'project' },
@@ -23,7 +23,7 @@ export function skillDirs(workingDir) {
   ];
 }
 
-function readDescription(skillMd) {
+function readDescription(/** @type {any} */ skillMd) {
   try {
     const text = fs.readFileSync(skillMd, 'utf8');
     const fm = text.match(/^---\n([\s\S]*?)\n---/);
@@ -39,7 +39,7 @@ function readDescription(skillMd) {
 }
 
 // 完整性校验（P3-3）：带指纹（sha256）来源记录的技能，内容与安装时不一致 → 拒绝加载
-function isTampered(dir) {
+function isTampered(/** @type {any} */ dir) {
   const meta = readSourceMeta(dir);
   if (!meta?.sha256) return false; // 旧版安装（无指纹）不拦截
   try {
@@ -50,14 +50,14 @@ function isTampered(dir) {
 }
 
 // 被篡改的用户级技能清单（CLI/WebUI 提示用；这些技能已被 listSkills 排除加载）
-export function tamperedSkillNames(workingDir) {
+export function tamperedSkillNames(/** @type {any} */ workingDir) {
   const dir = path.join(mingdaoHome(), 'skills');
-  const out = [];
+  const /** @type {any} */ out = [];
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
   } catch {
-    return out;
+    return /** @type {any} */ out;
   }
   for (const e of entries) {
     if (!e.isDirectory()) continue;
@@ -75,7 +75,7 @@ export function tamperedSkillNames(workingDir) {
   return out;
 }
 
-export function listSkills(workingDir) {
+export function listSkills(/** @type {any} */ workingDir) {
   const seen = new Set();
   const out = [];
   for (const { dir, source } of skillDirs(workingDir)) {
@@ -94,8 +94,10 @@ export function listSkills(workingDir) {
         continue;
       }
       seen.add(e.name); // 优先级：user > project > builtin，先出现的生效
-      // P3-3：用户级技能指纹不符 → 拒绝加载（绝不静默执行被篡改的提示词）
-      if (source === 'user' && isTampered(path.join(dir, e.name))) continue;
+      // P3-3：技能指纹不符 → 拒绝加载（绝不静默执行被篡改的提示词）。
+      // project 级（.mingdao/skills/）同样校验（CodeBuddy 报告：仓库投毒可直通提示词注入）；
+      // 无 .source.json 指纹的旧仓库/手写技能不受影响（isTampered 返回 false）。
+      if ((source === 'user' || source === 'project') && isTampered(path.join(dir, e.name))) continue;
       out.push({
         name: e.name,
         dir: path.join(dir, e.name),
@@ -108,7 +110,7 @@ export function listSkills(workingDir) {
   return out;
 }
 
-export function loadSkill(workingDir, name) {
+export function loadSkill(/** @type {any} */ workingDir, /** @type {any} */ name) {
   const s = listSkills(workingDir).find((x) => x.name === name);
   if (!s) return null;
   try {
@@ -118,14 +120,14 @@ export function loadSkill(workingDir, name) {
   }
 }
 
-function sourceLabel(source) {
+function sourceLabel(/** @type {any} */ source) {
   if (source === 'user') return '（用户级）';
   if (source === 'builtin') return '（内置）';
   return '';
 }
 
 // 注入系统提示的技能清单（仅名称+描述）
-export function skillsRegistryBlock(workingDir) {
+export function skillsRegistryBlock(/** @type {any} */ workingDir) {
   const skills = listSkills(workingDir);
   if (!skills.length) return '';
   return (

package/src/sync-server.js

@@ -39,9 +39,14 @@ const INVITE_CODES = new Set(
     .filter(Boolean)
 );
 
+/** @type {(...a: any[]) => void} */
 const log = (...a) => console.log(new Date().toISOString(), ...a);
 
 // ---------- 存储 ----------
+/**
+ * @param {any} file
+ * @param {any} fallback
+ */
 function readJson(file, fallback) {
   try {
     return JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -49,6 +54,10 @@ function readJson(file, fallback) {
     return fallback;
   }
 }
+/**
+ * @param {any} file
+ * @param {any} obj
+ */
 function writeJson(file, obj) {
   fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
   atomicWriteFileSync(file, JSON.stringify(obj, null, 2) + '\n', { mode: 0o600 }); // 质检 H4
@@ -59,12 +68,15 @@ function usersFile() {
 function devicesFile() {
   return path.join(ACTIVE_DIR, 'devices.json');
 }
+/** @param {any} username */
 function userDir(username) {
   return path.join(ACTIVE_DIR, 'data', username);
 }
+/** @param {any} username */
 function sessionsDir(username) {
   return path.join(userDir(username), 'sessions');
 }
+/** @param {any} username */
 function metaFile(username) {
   return path.join(userDir(username), 'meta.json');
 }
@@ -75,8 +87,13 @@ function acceptedFile() {
   return path.join(ACTIVE_DIR, 'accepted.json');
 }
 
+/** @type {(s: any) => string} */
 const sha = (s) => crypto.createHash('sha256').update(String(s)).digest('hex');
 // 常量时间比较（P3-10）：token/密码哈希等值判断防时序侧信道
+/**
+ * @param {any} a
+ * @param {any} b
+ */
 function safeEqualHex(a, b) {
   try {
     const ba = Buffer.from(String(a), 'hex');
@@ -87,9 +104,18 @@ function safeEqualHex(a, b) {
   }
 }
 // 密码存储用 scrypt（带盐 KDF）；旧数据兼容：verify 时 sha256 回退
+/**
+ * @param {any} password
+ * @param {any} salt
+ */
 function hashPassword(password, salt) {
   return crypto.scryptSync(String(password), String(salt), 32).toString('hex');
 }
+/**
+ * @param {any} password
+ * @param {any} salt
+ * @param {any} hash
+ */
 function verifyPassword(password, salt, hash) {
   if (!hash) return false;
   try {
@@ -98,9 +124,11 @@ function verifyPassword(password, salt, hash) {
   // 兼容早期 sha256 存储
   return safeEqualHex(hash, sha(`${salt}:${password}`));
 }
+/** @param {any} u */
 function isValidUsername(u) {
   return typeof u === 'string' && /^[A-Za-z0-9_.-]{2,32}$/.test(u) && u !== '.' && u !== '..';
 }
+/** @param {any} n */
 function isValidSessionName(n) {
   return typeof n === 'string' && /^[\w\u4e00-\u9fa5.-]{1,140}\.jsonl$/.test(n) && !n.includes('..');
 }
@@ -108,6 +136,7 @@ function isValidSessionName(n) {
 // ---------- 限速（防爆破/枚举；内存表，进程级） ----------
 const TRUST_PROXY = process.env.SYNC_TRUST_PROXY === '1'; // 仅部署在可信反代后时开启
 const rateBuckets = new Map();
+/** @param {any} req */
 function clientKey(req) {
   let ip = req.socket?.remoteAddress || 'x';
   if (TRUST_PROXY) {
@@ -116,6 +145,7 @@ function clientKey(req) {
   }
   return ip;
 }
+/** @param {any} req */
 function rateLimited(req, limit = 20, extra = '') {
   // 质检 M5：键 = IP + 路由 + 用户名——单账号爆破按用户名限（分布式 IP 无法绕过）；
   // 表满按最旧淘汰而非整表 clear（整表 clear 可被攻击者重置全员限额）
@@ -140,11 +170,13 @@ function rateLimited(req, limit = 20, extra = '') {
 }
 
 // ---------- HTTP 工具 ----------
+/** @param {any} req */
 function readBody(req, limit = MAX_BODY) {
   return new Promise((resolve, reject) => {
+    /** @type {any[]} */
     const chunks = [];
     let size = 0;
-    req.on('data', (d) => {
+    req.on('data', (/** @type {any} */ d) => {
       size += d.length;
       if (size > limit) {
         reject(new Error('body 超限'));
@@ -157,20 +189,27 @@ function readBody(req, limit = MAX_BODY) {
     req.on('error', reject);
   });
 }
+/**
+ * @param {any} res
+ * @param {any} code
+ * @param {any} obj
+ */
 function json(res, code, obj) {
   const body = JSON.stringify(obj);
   res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8', 'Content-Length': Buffer.byteLength(body) });
   res.end(body);
 }
+/** @param {any} req */
 async function parseBody(req) {
   try {
     return JSON.parse(await readBody(req) || '{}');
   } catch (e) {
-    return { __error: e.message };
+    return { __error: /** @type {any} */ (e).message };
   }
 }
 
 // ---------- 认证 ----------
+/** @param {any} req */
 function tokenOf(req) {
   const h = req.headers.authorization || '';
   const m = h.match(/^Bearer\s+(.+)$/i);
@@ -181,6 +220,7 @@ const deviceTokenCache = new Map();
 function invalidateDeviceCache() {
   deviceTokenCache.clear();
 }
+/** @param {any} token */
 function findDeviceByToken(token) {
   if (!token) return null;
   const tokenHash = sha(token);
@@ -202,9 +242,12 @@ function findDeviceByToken(token) {
 
 // ---------- 业务 ----------
 // 质检 A1：通用写互斥（注册/pair/lastSeen/meta 更新串行化），防 devices.json/meta.json 读改写竞态
+/** @type {any} */
 let writeLock = null;
+/** @param {any} fn */
 async function withWriteLock(fn) {
   const prev = writeLock || Promise.resolve();
+  /** @type {any} */
   let release;
   writeLock = new Promise((resolve) => {
     release = resolve;
@@ -216,7 +259,9 @@ async function withWriteLock(fn) {
     release();
   }
 }
+/** @type {any} */
 let registerLock = null;
+/** @param {any} body */
 async function doRegister(body) {
   const username = String(body.username || '').trim();
   const password = String(body.password || '');
@@ -229,6 +274,7 @@ async function doRegister(body) {
     });
   }
   const prev = registerLock;
+  /** @type {any} */
   let release;
   registerLock = new Promise((resolve) => {
     release = resolve;
@@ -247,6 +293,7 @@ async function doRegister(body) {
   }
 }
 
+/** @param {any} body */
 async function doPair(body) {
   const username = String(body.username || '').trim();
   const password = String(body.password || '');
@@ -268,10 +315,12 @@ async function doPair(body) {
   });
 }
 
+/** @param {any} username */
 function doListSessions(username) {
   const dir = sessionsDir(username);
   const meta = readJson(metaFile(username), {});
   const out = [];
+  /** @type {any[]} */
   let entries = [];
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -285,6 +334,10 @@ function doListSessions(username) {
   return out;
 }
 
+/**
+ * @param {any} username
+ * @param {any} body
+ */
 function doPush(username, body) {
   const name = String(body.name || '').trim();
   const content = typeof body.content === 'string' ? body.content : '';
@@ -305,6 +358,10 @@ function doPush(username, body) {
   });
 }
 
+/**
+ * @param {any} username
+ * @param {any} name
+ */
 function doPull(username, name) {
   if (!isValidSessionName(name)) return { notFound: '会话不存在' };
   const file = path.join(sessionsDir(username), name);
@@ -317,6 +374,10 @@ function doPull(username, name) {
   }
 }
 
+/**
+ * @param {any} username
+ * @param {any} name
+ */
 function doDelete(username, name) {
   if (!isValidSessionName(name)) return { notFound: '会话不存在' };
   const dir = sessionsDir(username);
@@ -335,6 +396,10 @@ function doDelete(username, name) {
 }
 
 // ---------- 密码修改 ----------
+/**
+ * @param {any} username
+ * @param {any} body
+ */
 function doChangePassword(username, body) {
   const oldPassword = String(body.oldPassword || '');
   const newPassword = String(body.newPassword || '');
@@ -356,6 +421,10 @@ function doChangePassword(username, body) {
 }
 
 // ---------- 会话分享 ----------
+/**
+ * @param {any} username
+ * @param {any} name
+ */
 function doShareCreate(username, name) {
   if (!isValidSessionName(name)) return { error: `会话名非法：${name}` };
   if (!fs.existsSync(path.join(sessionsDir(username), name))) return { notFound: '你还没有这个会话' };
@@ -367,6 +436,7 @@ function doShareCreate(username, name) {
   return { ok: true, shareId, name };
 }
 
+/** @param {any} username */
 function doShareList(username) {
   const shares = readJson(sharesFile(), {});
   const accepted = readJson(acceptedFile(), {})[username] || {};
@@ -383,6 +453,10 @@ function doShareList(username) {
   return { ok: true, mine, accepted: mineAccepted };
 }
 
+/**
+ * @param {any} username
+ * @param {any} shareId
+ */
 function doShareRevoke(username, shareId) {
   const shares = readJson(sharesFile(), {});
   const s = shares[shareId];
@@ -396,6 +470,10 @@ function doShareRevoke(username, shareId) {
 // 接受/刷新分享：克隆（或更新）到接受者自己的会话列表。
 //  - 首次接受 → 写入同名文件（同名已有不同内容则另存 .shared- 副本，绝不覆盖）
 //  - 再次接受：接受者未修改过副本 → 就地刷新；已修改 → 另存新副本（冲突保留双方）
+/**
+ * @param {any} username
+ * @param {any} shareId
+ */
 function doShareAccept(username, shareId) {
   const shares = readJson(sharesFile(), {});
   const s = shares[shareId];
@@ -453,6 +531,10 @@ function doShareAccept(username, shareId) {
 }
 
 // ---------- 路由 ----------
+/**
+ * @param {any} req
+ * @param {any} res
+ */
 async function handle(req, res) {
   const u = new URL(req.url, 'http://x');
   const p = u.pathname;
@@ -569,7 +651,7 @@ async function handle(req, res) {
     }
     return json(res, 404, { error: '未知接口' });
   } catch (e) {
-    log('error', p, e.message);
+    log('error', p, /** @type {any} */ (e).message);
     return json(res, 500, { error: '服务器内部错误' });
   }
 }
@@ -584,6 +666,7 @@ export function runSyncServer({ port, host, dataDir, cert, key } = {}) {
   const certFile = cert || CERT;
   const keyFile = key || KEY;
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  /** @type {(req: any, res: any) => void} */
   const handler = (req, res) => {
     handle(req, res).catch(() => {});
   };