@luolingp/request-doctor 0.0.0-stage → 0.11.0

package/lib/repair-listeners.js

@@ -0,0 +1,126 @@
+// 几个修复监听器。
+//
+// 一个管模型请求失败，一个管工具调用失败，一个管浏览器载体请求失败。三者共用重试预算、
+// 诊断记录和插件生命周期，这些都是从参数传进来而不是从闭包里摸出去的，所以每个函数
+// 单独拎出来也能看懂。
+import { computeDelay, isTransientNetworkError, isTransientToolFailure } from './classify.js';
+import { cancellableSleep } from './sleep.js';
+import { createModelRepair } from './model-repair.js';
+
+export function createRepairListeners(input) {
+  const { config, lifetime, diagnostics, ledger, versionRepair, services, warn } = input;
+  const { record, stats } = diagnostics;
+  const modelRepair = createModelRepair({ config, lifetime, diagnostics, ledger, versionRepair, services, warn });
+
+  // 把请求自己的取消信号和插件生命周期绑在一起，插件卸载时正在等的重试能立刻醒。
+  const fuse = (signal) => {
+    if (signal === undefined) return lifetime.signal;
+    try {
+      return AbortSignal.any([signal, lifetime.signal]);
+    } catch {
+      return signal;
+    }
+  };
+
+  // 工具调用被瞬时传输故障打断时，只读的那些可以重放一次。
+  //
+  // 必须卡着白名单来：带副作用的工具重放一遍，就是真的多跑了一条命令、多发了一条消息。
+  async function onToolExecute(exec, next) {
+    let attempt = 0;
+    for (;;) {
+      const outcome = await attemptDispatch(exec, next, attempt);
+      if (outcome.retry === false) {
+        if (outcome.error !== undefined) throw outcome.error;
+        return outcome.result;
+      }
+      attempt += 1;
+      const policy = config();
+      if (attempt > policy.maxToolRetries) {
+        if (outcome.error !== undefined) throw outcome.error;
+        return outcome.result;
+      }
+      const delayMs = computeDelay(policy, attempt, undefined);
+      const waited = await cancellableSleep(delayMs, fuse(exec.signal));
+      if (!waited) {
+        if (outcome.error !== undefined) throw outcome.error;
+        return outcome.result;
+      }
+      stats.toolRepairs += 1;
+      record('tool', `${exec.name} replayed after a transient ${outcome.reason} failure (attempt ${attempt})`);
+    }
+  }
+
+  // 循环检测：同名同参的调用连着出现太多次，就不再重放。
+  //
+  // 宿主自己的循环检测若失效，重放会把循环放大。这里只约束「我们自己的重放」，
+  // 不改变调用本身的语义——正常调用该怎么走还怎么走。
+  const recent = new Map();
+  function signatureOf(exec) {
+    try {
+      return `${exec.name}:${JSON.stringify(exec.arguments ?? {}).slice(0, 400)}`;
+    } catch {
+      return String(exec.name);
+    }
+  }
+  function seenTooOften(exec) {
+    const key = signatureOf(exec);
+    const count = (recent.get(key) ?? 0) + 1;
+    recent.set(key, count);
+    if (recent.size > 64) recent.clear();
+    return count > config().maxRepeatedToolCalls;
+  }
+
+  // 跑一次调用，顺便判断这次失败值不值得重放。
+  async function attemptDispatch(exec, next, attempt) {
+    const policy = config();
+    if (attempt >= policy.maxToolRetries) {
+      try {
+        return { retry: false, result: await next() };
+      } catch (error) {
+        return { retry: false, error };
+      }
+    }
+    if (exec.signal?.aborted || lifetime.signal.aborted || seenTooOften(exec)) {
+      try {
+        return { retry: false, result: await next() };
+      } catch (error) {
+        return { retry: false, error };
+      }
+    }
+    try {
+      const result = await next();
+      if (!isTransientToolFailure(exec.name, result, policy.retryableToolPattern)) return { retry: false, result };
+      return { retry: true, reason: 'dispatch', result };
+    } catch (error) {
+      if (!isTransientNetworkError(error)) return { retry: false, error };
+      return { retry: true, reason: 'thrown transport', error };
+    }
+  }
+
+  // 浏览器载体的传输失败，如果响应头还没发出去，就换成可重试的 503。
+  //
+  // 头一发出去响应形状就定了，这时候只能把原始错误抛回去，硬写半截回复反而更糟。
+  async function onConnectionRequest(request, response, next) {
+    try {
+      return await next();
+    } catch (error) {
+      if (response.headersSent || response.writableEnded || !isTransientNetworkError(error)) throw error;
+      stats.connectionRepairs += 1;
+      record('connection', `replaced a failed ${String(request?.method ?? '')} ${String(request?.url ?? '')} with a retryable 503`);
+      try {
+        response.writeHead(503, { 'retry-after': '1', 'content-type': 'text/plain; charset=utf-8' });
+        response.end('request-doctor: transient client transport failure; retry the request');
+      } catch {
+        throw error;
+      }
+    }
+  }
+
+  return { onRequestError, onToolExecute, onConnectionRequest };
+
+  // 模型请求的修复交给 model-repair 那个模块，这里只转发一下。
+  // 放在后面是为了让工具和载体两个处理更靠前，读起来顺。
+  function onRequestError(payload, next) {
+    return modelRepair.handle(payload, next);
+  }
+}

package/lib/retry-ledger.js

@@ -0,0 +1,67 @@
+// 重试账本。
+//
+// 记住每个 agent 每条链已经重试过几次，并且把修复写进既有的 llm/retry 事件里，
+// 这样对话里能直接看到重试记录。单拎出来是为了让预算规则能被单独读懂和测试。
+import { randomUUID } from 'node:crypto';
+
+// 每个 agent 最多留这么多条链。老 turn 不可能再重试了，留着没用。
+const MAX_CHAINS_PER_AGENT = 128;
+
+export function createRetryLedger(input) {
+  const chains = new WeakMap();
+
+  // 取一条链的预算记录，没有就建。键是 turn:step:provider:kind，
+  // 换句话说同一处失败共用一份预算，换一处就重新开始算。
+  const chainFor = (agent, key) => {
+    let map = chains.get(agent);
+    if (map === undefined) chains.set(agent, (map = new Map()));
+    let entry = map.get(key);
+    if (entry === undefined) {
+      if (map.size >= MAX_CHAINS_PER_AGENT) {
+        const oldest = map.keys().next().value;
+        if (oldest !== undefined) map.delete(oldest);
+      }
+      map.set(key, (entry = { count: 0, retryId: randomUUID() }));
+    }
+    return entry;
+  };
+
+  // 排上重试时写 llm/retry。只用既有事件类型，新类型会被读取端当成未知事件拒掉。
+  const recordScheduled = (agent, payload, kind, entry, delayMs) => {
+    const config = input.config();
+    if (!config.recordRetryEvents) return;
+    try {
+      agent.session.append('llm/retry', {
+        retryId: entry.retryId,
+        turn: payload.turn,
+        step: payload.step,
+        provider: payload.provider,
+        mode: 'normal',
+        policyKey: `request-doctor:${kind}`,
+        retry: entry.count,
+        maxRetries: config.maxRetries,
+        delayMs,
+        failure: payload.failure,
+      });
+    } catch (error) {
+      input.warn(`request-doctor: could not record the repair event: ${String(error)}`);
+    }
+  };
+
+  // 真正开始重试时补一条 llm/retry-started，把这条记录闭环。
+  const recordStarted = (agent, payload, entry) => {
+    if (!input.config().recordRetryEvents) return;
+    try {
+      agent.session.append('llm/retry-started', {
+        retryId: entry.retryId,
+        turn: payload.turn,
+        step: payload.step,
+        retry: entry.count,
+      });
+    } catch {
+      // 只是展示用，写不进去不影响修复
+    }
+  };
+
+  return { chainFor, recordScheduled, recordStarted };
+}

package/lib/runtime-probe.js

@@ -0,0 +1,171 @@
+// 运行时探测。
+//
+// 负责问清楚：当前跑的是哪个 DSH 版本、profile 在哪儿、DSH 自己的包装在哪儿、
+// 以及现在真正注册了哪些 provider 路由。这些都是"查一下"的事，不涉及"怎么修"，
+// 所以跟用它们的修复流程分开放。
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { entryPathOf, packageDir } from './compat-repair.js';
+import { createFactsReader, createManifestReader } from './stat-cache.js';
+
+// DSH 自己的包可能装在安装目录里，也可能打在 asar 里。
+// 前者能直接用文件系统找到，后者 existsSync 看不见，只能靠路径拼。
+function packageDirInInstallation(packageName) {
+  for (const root of installationRoots()) {
+    const candidate = join(root, 'node_modules', ...packageName.split('/'));
+    // asar 里的目录 existsSync 返回 false，但路径本身可用，直接交出去。
+    if (root.includes('app.asar')) return candidate;
+    if (existsSync(join(candidate, 'package.json'))) return candidate;
+  }
+  return undefined;
+}
+
+// 找出 DSH 装在哪里。按可靠性从高到低试几个来源。
+function installationRoots() {
+  const roots = [];
+
+  // 最可靠的一条：从正在运行的模块 URL 反推。插件自己就加载自 DSH 安装目录。
+  try {
+    const self = import.meta.url;
+    const marker = self.indexOf('/dsh/');
+    if (marker > 0) roots.push(decodeURIComponent(new URL(self).pathname).slice(0, marker).replace(/^\//, '') + '/dsh');
+  } catch {
+    /* 拿不到就算了 */
+  }
+
+  // Electron 会给出 resources 目录。
+  if (typeof process.resourcesPath === 'string' && process.resourcesPath !== '') {
+    roots.push(join(process.resourcesPath, 'app.asar', 'dsh'));
+    roots.push(join(process.resourcesPath, 'app.asar.unpacked', 'dsh'));
+    roots.push(join(process.resourcesPath, 'dsh'));
+  }
+
+  // 从可执行文件位置推，覆盖非 Electron 的安装方式。
+  if (typeof process.execPath === 'string' && process.execPath !== '') {
+    const exeDir = dirname(process.execPath);
+    roots.push(join(exeDir, 'resources', 'app.asar', 'dsh'));
+    roots.push(join(exeDir, 'resources', 'dsh'));
+    roots.push(join(exeDir, 'dsh'));
+  }
+
+  return [...new Set(roots.filter((root) => root !== ''))];
+}
+
+export function createRuntimeProbe(input) {
+  const readManifestCached = createManifestReader();
+  const factsOf = createFactsReader(input.collectFacts);
+
+  // 可选服务，没有就算了，不该因此中断。
+  const safeGet = (name) => {
+    try {
+      return input.ctx.get(name);
+    } catch {
+      return undefined;
+    }
+  };
+
+  // DSH 的包走的是 profile 的运行时拦截，不是普通 Node 解析，
+  // 所以得问管这块映射的服务，而不是自己去 require。
+  const runtimeVersionOf = (packages, baseUrl) => {
+    try {
+      const manifestPath = packages?.packageOf('@deepseek-ai/dsh-app-boot', baseUrl)?.manifestPath;
+      return manifestPath === undefined ? undefined : readManifestCached(manifestPath)?.version;
+    } catch {
+      return undefined;
+    }
+  };
+
+  // 先问服务，问不到再看环境变量——有些 profile 是在没有这些服务的情况下跑起来的。
+  const profileDirOf = () => {
+    const fromServices = safeGet('profileContext')?.dir ?? safeGet('pluginManager')?.profile?.dir;
+    if (fromServices !== undefined) return fromServices;
+    const home = process.env.DSH_HOME;
+    const profile = process.env.DSH_PROFILE;
+    return home === undefined || profile === undefined ? undefined : join(home, 'profiles', profile);
+  };
+
+  const runtimeFacts = () => {
+    const packages = safeGet('pluginPackages');
+    const baseUrl = input.ctx.baseUrl;
+    return {
+      runtimeVersion: runtimeVersionOf(packages, baseUrl),
+      profileDir: profileDirOf(),
+      packages,
+      baseUrl,
+    };
+  };
+
+  // DSH 自带的包在安装目录里（甚至是 asar 里），不在 profile 的 node_modules。
+  // 先问 pluginPackages，它最清楚；问不到就用别的包探出安装根，最后才去翻安装目录。
+  const runtimeDirOf = (facts) => (packageName) => {
+    try {
+      const resolved = facts.packages?.packageOf(packageName, facts.baseUrl);
+      if (resolved?.dir !== undefined) return resolved.dir;
+    } catch {
+      // 落到后面几条路
+    }
+    // 同一个安装里的包都在同一个 node_modules 下，拿找得到的那个反推即可。
+    const anchor = probeAnchor(facts);
+    if (anchor !== undefined) {
+      const candidate = join(anchor, ...packageName.split('/'));
+      if (candidate.includes('app.asar') || existsSync(join(candidate, 'package.json'))) return candidate;
+    }
+    if (facts.profileDir !== undefined) {
+      const inProfile = packageDir(facts.profileDir, packageName);
+      if (inProfile !== undefined) return inProfile;
+    }
+    return packageDirInInstallation(packageName);
+  };
+
+  // 用运行时里一定找得到的包，反推它所在的 node_modules 目录。
+  // app-boot 每个 profile 都必然加载，拿它当锚点最稳。
+  const probeAnchor = (facts) => {
+    for (const name of ['@deepseek-ai/dsh-app-boot', '@deepseek-ai/dsh-llm', '@deepseek-ai/cordis']) {
+      try {
+        const resolved = facts.packages?.packageOf(name, facts.baseUrl);
+        if (resolved?.dir === undefined) continue;
+        const parts = resolved.dir.replace(/\\/g, '/').split('/');
+        const scope = parts.lastIndexOf('@deepseek-ai');
+        if (scope > 0) return parts.slice(0, scope).join('/');
+      } catch {
+        // 换下一个
+      }
+    }
+    return undefined;
+  };
+
+  const runtimeEntryOf = (facts) => (packageName) => {
+    const dir = runtimeDirOf(facts)(packageName);
+    if (dir === undefined) return;
+    const manifest = readManifestCached(join(dir, 'package.json'));
+    if (manifest !== undefined) return entryPathOf(dir, manifest);
+    // manifest 读不到（asar 里的情况）就按惯例猜入口：先 lib/index.js，再 index.js。
+    for (const guess of ['lib/index.js', 'index.js', 'lib/index.mjs']) {
+      const candidate = join(dir, guess);
+      if (candidate.includes('app.asar') || existsSync(candidate)) return candidate;
+    }
+    return undefined;
+  };
+
+  // 以运行时注册表为准。插件常常声明好几条路由，实际按地区或配置只注册一部分，
+  // 光看源码会把根本不存在冲突也算出来。
+  const activeProviders = () => {
+    const llm = safeGet('llm');
+    if (llm === undefined || typeof llm.listProviders !== 'function') return undefined;
+    try {
+      return llm.listProviders().map((entry) => entry?.id).filter((id) => typeof id === 'string');
+    } catch {
+      return undefined;
+    }
+  };
+
+  return {
+    readManifestCached,
+    runtimeFacts,
+    runtimeDirOf,
+    runtimeEntryOf,
+    activeProviders,
+    factsOf,
+    get: safeGet,
+  };
+}

package/lib/semver.js

@@ -0,0 +1,159 @@
+// 版本号解析、比较，以及判断某个版本是否满足 manifest 里写的范围。
+//
+// 自己实现而不是引依赖：本插件要在没装任何额外包的 profile 里也能跑，而 DSH manifest
+// 用到的语法其实不多，正好可以全测到。
+/** 解析 major.minor.patch[-prerelease][+build]。 */
+export function parseSemver(text) {
+  if (typeof text !== 'string') return undefined;
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/.exec(text.trim());
+  if (match === null) return undefined;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] === undefined ? [] : match[4].split('.'),
+    raw: text.trim(),
+  };
+}
+
+// 按 SemVer 规范第 11 条比预发布标识：数字段按数值比，字母段按字典序比，
+// 数字段永远小于字母段，短的排在长的前面。
+function comparePrerelease(a, b) {
+  if (a.length === 0 && b.length === 0) return 0;
+  if (a.length === 0) return 1; // 正式版比它的任何预发布都大
+  if (b.length === 0) return -1;
+  for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+    const left = a[i];
+    const right = b[i];
+    if (left === undefined) return -1;
+    if (right === undefined) return 1;
+    const leftNumeric = /^\d+$/.test(left);
+    const rightNumeric = /^\d+$/.test(right);
+    if (leftNumeric && rightNumeric) {
+      const delta = Number(left) - Number(right);
+      if (delta !== 0) return delta < 0 ? -1 : 1;
+    } else if (leftNumeric !== rightNumeric) {
+      return leftNumeric ? -1 : 1;
+    } else if (left !== right) {
+      return left < right ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+/** 比较两个已解析的版本，返回 -1 / 0 / 1。 */
+export function compareVersions(a, b) {
+  for (const key of ['major', 'minor', 'patch']) {
+    if (a[key] !== b[key]) return a[key] < b[key] ? -1 : 1;
+  }
+  return comparePrerelease(a.prerelease, b.prerelease);
+}
+
+// 把范围拆成若干组比较项。用 || 分隔的每一组都要单独满足。
+function comparatorTerms(range) {
+  return String(range)
+    .split('||')
+    .map((alternative) => alternative.trim().split(/\s+/).filter((term) => term !== ''));
+}
+
+// 判断单个比较项，比如 ">=1.2.3" 或 "^0.2.1"。
+function termSatisfied(version, term) {
+  const operator = /^(>=|<=|>|<|=|\^|~)?/.exec(term)?.[1] ?? '';
+  const body = term.slice(operator.length);
+  if (body === '' || body === '*' || body === 'x' || body === 'X') return true;
+  const parsed = parseSemver(body.replace(/\.(?:x|X|\*)$/, '.0'));
+  if (parsed === undefined) return undefined; // 解析不了，交给调用方决定
+  const order = compareVersions(version, parsed);
+  return compareByOperator(operator, order, version, parsed);
+}
+
+// 从 termSatisfied 里拆出来的，专门处理各个比较符。
+// 一开始全塞在一起的时候，^ 和 ~ 的边界规则读起来像一堆嵌套 if。
+function compareByOperator(operator, order, version, parsed) {
+  const simple = {
+    '': order === 0,
+    '=': order === 0,
+    '>': order > 0,
+    '>=': order >= 0,
+    '<': order < 0,
+    '<=': order <= 0,
+  };
+  if (Object.hasOwn(simple, operator)) return simple[operator];
+  if (operator === '^') return satisfiesCaret(version, parsed, order);
+  if (operator === '~') return satisfiesTilde(version, parsed, order);
+  return undefined;
+}
+
+// ^1.2.3 的意思是最左边那个非零位锁住：1.x 都行，0.2.x 只到 0.2，0.0.x 就只能 0.0.x。
+function satisfiesCaret(version, parsed, order) {
+  if (order < 0) return false;
+  if (parsed.major > 0) return version.major === parsed.major;
+  if (parsed.minor > 0) return version.major === 0 && version.minor === parsed.minor;
+  return version.major === 0 && version.minor === 0 && version.patch === parsed.patch;
+}
+
+// ~1.2.3 是主次版本钉死，补丁位往上都行。
+function satisfiesTilde(version, parsed, order) {
+  return order >= 0 && version.major === parsed.major && version.minor === parsed.minor;
+}
+
+// 判断版本满不满足范围。返回 true/false；范围本身解析不了就返回 undefined
+// （workspace: 协议、git tag、写坏的字符串都会走这条路），由调用方自己拿主意。
+// 预发布版本能不能落进这个范围。
+//
+// 这是 semver 里最容易被忽略的一条：预发布版本只对它自己那一组 major.minor.patch 的
+// 比较符有效。所以 0.2.1-rc.3 不满足 ">=0.2.0-rc.2 <0.3.0-0"——那组的预发布是
+// 0.2.0 和 0.3.0，跟它不同组。不按这条判，会把运行时明确拒绝的版本当成满足，
+// 于是插件永远显示成「已经没问题」，实际根本加载不了。
+function prereleaseAllowed(parsed, terms) {
+  if (parsed.prerelease.length === 0) return true;
+  return terms.some((term) => {
+    const body = term.replace(/^(?:>=|<=|>|<|=|\^|~)/, '');
+    // 通配符没有具体版本可比，对预发布一视同仁。
+    if (body === '' || body === '*' || body === 'x' || body === 'X') return true;
+    const candidate = parseSemver(body.replace(/\.(?:x|X|\*)$/, '.0'));
+    if (candidate === undefined || candidate.prerelease.length === 0) return false;
+    return candidate.major === parsed.major
+      && candidate.minor === parsed.minor
+      && candidate.patch === parsed.patch;
+  });
+}
+
+export function satisfies(version, range) {
+  const parsed = typeof version === 'string' ? parseSemver(version) : version;
+  if (parsed === undefined) return undefined;
+  if (typeof range !== 'string' || range.trim() === '') return undefined;
+  const groups = comparatorTerms(range);
+  let answered = false;
+  for (const terms of groups) {
+    let all = true;
+    for (const term of terms) {
+      const result = termSatisfied(parsed, term);
+      if (result === undefined) continue;
+      answered = true;
+      if (!result) {
+        all = false;
+        break;
+      }
+    }
+    if (all && answered) return prereleaseAllowed(parsed, terms);
+  }
+  return answered ? false : undefined;
+}
+
+// 估算声明的版本要求跟当前运行时差多远。用来区分"差不多能用"和"差了一个大版本"，
+// 前者值得自动适配，后者得让人看一眼。
+export function classifyDistance(declaredRange, runtimeVersion) {
+  const satisfied = satisfies(runtimeVersion, declaredRange);
+  if (satisfied === true) return 'satisfied';
+  if (satisfied === undefined) return 'unknown';
+  const runtime = parseSemver(runtimeVersion);
+  const floor = typeof declaredRange === 'string'
+    ? parseSemver(String(declaredRange).replace(/^[\^~>=<\s]+/, '').split(/\s+/)[0])
+    : undefined;
+  if (runtime === undefined || floor === undefined) return 'unknown';
+  if (runtime.major !== floor.major) return 'major-delta';
+  if (runtime.minor !== floor.minor) return 'minor-delta';
+  if (runtime.patch !== floor.patch) return 'patch-delta';
+  return 'prerelease-delta';
+}

package/lib/sleep.js

@@ -0,0 +1,18 @@
+// 可中断的等待。
+//
+// 退避期间如果请求被取消或插件被卸载，必须立刻醒过来，所以这里返回布尔值而不是抛错——
+// 由调用方决定是交还下游结果还是把原始异常抛出去。
+export function cancellableSleep(ms, signal) {
+  if (signal?.aborted) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve(true);
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      resolve(false);
+    }
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}

package/lib/stat-cache.js

@@ -0,0 +1,67 @@
+// manifest 和模块图的缓存。
+//
+// 一次扫描要摸遍所有插件，后台轮询还会定期重来；但 manifest 和源码图只在安装、升级、
+// 换运行时的时候才会变。所以两边都用文件签名做键，文件一动自然失效，不需要挂文件监听。
+// 两个缓存都有上限，卸载掉的插件不会一直占着内存。
+import { readFileSync, statSync } from 'node:fs';
+
+const MAX_MANIFESTS = 512;
+const MAX_FACTS = 256;
+
+// 塞进去，满了就丢最早的那个。
+function put(cache, limit, key, value) {
+  if (cache.size >= limit && !cache.has(key)) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== undefined) cache.delete(oldest);
+  }
+  cache.set(key, value);
+}
+
+// mtime + size 就够判断变没变，不读文件内容。
+function signature(path) {
+  try {
+    const stat = statSync(path);
+    return `${stat.mtimeMs}:${stat.size}`;
+  } catch {
+    return undefined;
+  }
+}
+
+export function createManifestReader() {
+  const cache = new Map();
+  return (path) => {
+    const key = signature(path);
+    // asar 里的文件 stat 拿不到签名，但内容能读，所以不能因此直接放弃。
+    // 这类路径内容不会变，用固定键缓存即可。
+    const fallbackKey = path.includes('app.asar') ? 'asar' : undefined;
+    const effectiveKey = key ?? fallbackKey;
+    if (effectiveKey === undefined) {
+      cache.delete(path);
+      return undefined;
+    }
+    const cached = cache.get(path);
+    if (cached !== undefined && cached.key === effectiveKey) return cached.manifest;
+    try {
+      const manifest = JSON.parse(readFileSync(path, 'utf8'));
+      put(cache, MAX_MANIFESTS, path, { key: effectiveKey, manifest });
+      return manifest;
+    } catch {
+      cache.delete(path);
+      return undefined;
+    }
+  };
+}
+
+// 运行时版本也算进键里：同一个插件在换 DSH 版本后必须重新解析。
+export function createFactsReader(collect) {
+  const cache = new Map();
+  return (dir, entry, runtimeVersion) => {
+    const stamp = signature(entry);
+    const key = stamp === undefined ? `${dir}:${runtimeVersion}` : `${dir}:${runtimeVersion}:${stamp}`;
+    const cached = cache.get(dir);
+    if (cached !== undefined && cached.key === key) return cached.value;
+    const value = collect(dir, entry);
+    put(cache, MAX_FACTS, dir, { key, value });
+    return value;
+  };
+}

package/lib/symbol-alias.js

@@ -0,0 +1,44 @@
+/**
+ * 从旧符号名猜它在新版本里叫什么。
+ *
+ * 老插件引用的名字消失时，绝大多数情况不是功能没了，而是被改名或者挪了位置。
+ * 这里按几种常见的改名规律去猜，猜中就当成别名接上，猜不中再报缺。
+ *
+ * @param {string} symbol - 插件要的符号名。
+ * @param {string[]} available - 当前运行时实际导出的名字。
+ * @returns {string|undefined} 猜到的名字，猜不到就 undefined。
+ */
+export function guessRenamedSymbol(symbol, available) {
+  if (!Array.isArray(available) || available.length === 0) return undefined;
+
+  const lower = symbol.toLowerCase();
+  const matches = (candidate) => candidate.toLowerCase() === lower;
+  const direct = available.find(matches);
+  if (direct !== undefined) return direct;
+
+  // 去掉常见前缀再比：getXxx / useXxx / createXxx 这类包装。
+  const stripped = symbol.replace(/^(get|use|create|make|build|resolve|load|read|parse)/, '');
+  if (stripped !== '' && stripped !== symbol) {
+    const byStripped = available.find((candidate) => candidate.toLowerCase() === stripped.toLowerCase());
+    if (byStripped !== undefined) return byStripped;
+  }
+
+  // 反向：给新名字加上同样的前缀。
+  const prefixed = /^(get|use|create|make|build|resolve|load|read|parse)/.exec(symbol)?.[1];
+  if (prefixed !== undefined) {
+    const withPrefix = available.find((candidate) => candidate === `${prefixed}${symbol.slice(prefixed.length)}`);
+    if (withPrefix !== undefined) return withPrefix;
+  }
+
+  // 单复数差异，比如 homePaths / homePath。
+  const singular = symbol.endsWith('s') ? symbol.slice(0, -1) : `${symbol}s`;
+  const byPlural = available.find((candidate) => candidate.toLowerCase() === singular.toLowerCase());
+  if (byPlural !== undefined) return byPlural;
+
+  // 只差大小写或者下划线，比如 home_paths / homePaths。
+  const normalized = (text) => text.replace(/[_-]/g, '').toLowerCase();
+  const byShape = available.find((candidate) => normalized(candidate) === normalized(symbol));
+  if (byShape !== undefined) return byShape;
+
+  return undefined;
+}