@luolingp/request-doctor 0.0.0-stage → 0.11.1

package/lib/compat-env.js

@@ -0,0 +1,490 @@
+// 兼容环境的搭建与拆除。
+//
+// 这一半负责「让旧插件在它以为的旧环境里跑」：在插件目录里建一个嵌套 node_modules，
+// 每个包都是一层很薄的垫片，声明的是旧版本号，转发的是当前真正的实现。Node 往上找包
+// 时会先撞上嵌套的这一份，插件于是拿到了它期望的版本，而实跑的仍是新代码。
+//
+// 没有任何版本检查被绕过——插件解析到的那份声明，是真的满足它的。
+import { copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { bareNameOf, parseExportedNames } from './compat.js';
+import { guessRenamedSymbol } from './symbol-alias.js';
+import { entryPathOf } from './compat-repair.js';
+
+// 标记文件，说明这个目录是模块自己建的
+export const ENV_MARKER = '.@luolingp/request-doctor-compat.json';
+
+// 原样保存的 manifest 副本
+export const MANIFEST_BACKUP = 'package.json.@luolingp/request-doctor-original';
+
+// 运行时自己发布的包，版本跟 DSH 一起走。schemastery、cordis 这些虽然也在
+// @deepseek-ai 下，但它们有自己的版本线（3.x、4.x），不能跟着运行时改。
+const RUNTIME_OWNED = /^@deepseek-ai\/dsh(?:[-/]|$)/;
+
+// 需要建垫片的范围：整个 @deepseek-ai 生态都由运行时供给，插件解析到哪一份
+// 取决于环境，所以都要拦下来。
+const DSH_PACKAGE = /^@deepseek-ai\/[a-z]/;
+
+// 读 JSON，读不出来就返回 undefined
+export function readJson(path) {
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    return value !== null && typeof value === 'object' ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// 从 peer 范围里推出它当初是按哪个版本写的。
+export function pinnedVersion(range, fallback) {
+  if (typeof range !== 'string') return fallback;
+  const match = /\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?/.exec(range);
+  return match === null ? fallback : match[0];
+}
+
+// 找出某个 DSH 包真正装在哪儿。
+export function resolveInstalledDir(input) {
+  const fromRuntime = input.resolveDir?.(input.name);
+  // asar 里的路径 existsSync 看不到，但 Electron 的 fs 能读，直接认下来。
+  if (typeof fromRuntime === 'string' && (fromRuntime.includes('app.asar') || existsSync(join(fromRuntime, 'package.json')))) {
+    return fromRuntime;
+  }
+  const candidate = join(input.profileDir, 'node_modules', ...input.name.split('/'));
+  return existsSync(join(candidate, 'package.json')) ? candidate : undefined;
+}
+
+// 写一个最小垫片包，把真实实现转发出去。
+function writeShimPackage(input) {
+  const manifest = {
+    name: input.name,
+    version: input.version,
+    type: 'module',
+    private: true,
+    description: '@luolingp/request-doctor compatibility environment: re-exports the current runtime under the version this plugin expects.',
+    main: 'index.js',
+    exports: { '.': './index.js', './package.json': './package.json' },
+  };
+  mkdirSync(input.shimDir, { recursive: true });
+
+  const target = pathToFileURL(input.realEntry).href;
+  const realSource = readFileSync(input.realEntry, 'utf8');
+  // export * 把当前运行时还提供的东西全转发出去，旧接口因此能继续用，这里一行实现都不用抄。
+  // default 那一句只在目标真有默认导出时才写：指名一个不存在的导出是语法错误，不会软失败。
+  // 默认导出有两种写法：export default X 和 export { X as default }。
+  // 只认前一种会漏掉后者，而 export * 又不转发 default，插件导入就会报错。
+  const hasDefault = parseExportedNames(input.realEntry, (file) => readFileSync(file, 'utf8'))?.includes('default')
+    ?? /\bexport\s+default\b/.test(realSource);
+
+  // 旧名字在新版本里改了名的，在这里以旧名重新导出一次。
+  // 只做名字层面的转发，不编造任何实现：指向的仍是运行时里真实存在的那个导出。
+  const aliases = Object.entries(input.aliases ?? {});
+  const aliasLines = aliases
+    .filter(([oldName, newName]) => typeof newName === 'string' && newName !== oldName)
+    .map(([oldName, newName]) => `export { ${newName} as ${oldName} } from ${JSON.stringify(target)};`);
+
+  // 插件从子路径导入时，那些导出在子路径模块里，根入口没有。
+  // 一并转发出去，`pkg/lib/x.js` 那样的导入才拿得到东西。
+  const extraLines = (input.extraTargets ?? [])
+    .map((path) => `export * from ${JSON.stringify(pathToFileURL(path).href)};`);
+
+  const body = [
+    `// Generated by @luolingp/request-doctor. Do not edit: this file is replaced on every`,
+    `// compatibility scan, and deleted when the plugin is restored.`,
+    `export * from ${JSON.stringify(target)};`,
+    ...(hasDefault ? [`export { default } from ${JSON.stringify(target)};`] : []),
+    ...extraLines,
+    ...aliasLines,
+    '',
+  ].join('\n');
+
+  // 每次扫描都把同样的内容重写一遍，既折腾文件系统，有监听器的话还会触发没必要的重载。
+  // 只在内容真变了的时候写。
+  writeIfChanged(join(input.shimDir, 'package.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+  writeIfChanged(join(input.shimDir, 'index.js'), body);
+  return { ok: true, missing: [] };
+}
+
+// 内容没变就不写盘。
+function writeIfChanged(path, content) {
+  try {
+    if (readFileSync(path, 'utf8') === content) return false;
+  } catch {
+    /* missing or unreadable: fall through and write */
+  }
+  writeFileSync(path, content, 'utf8');
+  return true;
+}
+
+// 给一个插件装好兼容环境。
+export function installCompatEnvironment(input) {
+  const root = join(input.pluginDir, 'node_modules');
+
+  // 先把每个包都核一遍，一个字节都不写。
+  //
+  // 这一点很关键：边核边写的话，中途发现某个包拿不到，就得把已经写好的删掉，
+  // 连上一轮本来能用的环境也一起没了——插件从"能跑"变成"彻底起不来"。
+  // 先全部核对，全部通过才动手，拒绝时现场原样不动。
+  const plans = [];
+  const missing = [];
+  const needed = [];
+  // 按包名归组：插件可能既从包根导入、也从子路径导入（`pkg/lib/extra.js`）。
+  // 后者不是独立的包，当成包处理会去一个不存在的地方找 package.json，整个环境就被拒了。
+  for (const group of groupImports(input.imports)) {
+    const plan = planPackage(group, input);
+    if (plan.missing.length > 0) missing.push(...plan.missing);
+    else if (plan.needsOldVersion !== undefined) needed.push(plan.needsOldVersion);
+    else plans.push(plan);
+  }
+
+  // 有包需要旧版本而还没拿到：交给调用方去取，这一轮什么都不改。
+  if (needed.length > 0) {
+    return { status: 'needs-old-version', packages: [], missing: [], needed };
+  }
+  if (missing.length > 0) {
+    // 什么都不改，让插件继续用它现有的环境。
+    return { status: 'refused', packages: [], missing, error: `cannot provide ${missing.join(', ')}` };
+  }
+  if (plans.length === 0) return { status: 'unchanged', packages: [], missing: [] };
+  // 只是问一句能不能建，不要动磁盘。调用方用它来判断需不需要先去取旧版本。
+  if (input.dryRun === true) return { status: 'installable', packages: plans.map((plan) => plan.name), missing: [] };
+
+  const created = [];
+  const renamed = [];
+  for (const plan of plans) {
+    const shimDir = join(root, ...plan.name.split('/'));
+    // 拿到了真实旧版本，就把整份旧实现放进去。这才是兼容模式：
+    // 插件跑的是它当初对着写的那份代码，不是一个转发到今天实现的替身。
+    if (plan.copyFrom !== undefined) {
+      rmSync(shimDir, { recursive: true, force: true });
+      cpSync(plan.copyFrom, shimDir, { recursive: true });
+      created.push(plan.name);
+      renamed.push(`${plan.name} 使用真实旧版本（${plan.oldVersion}）`);
+      continue;
+    }
+    // 当前实现就够用，写一层薄垫片指着它。垫片服务的就是当前实现，所以声明当前版本是真的。
+    writeShimPackage({
+      shimDir,
+      name: plan.name,
+      version: input.runtimeVersion,
+      realEntry: plan.realEntry,
+      symbols: plan.symbols,
+      aliases: plan.aliases,
+      extraTargets: plan.extraTargets,
+    });
+    created.push(plan.name);
+    for (const [from, to] of Object.entries(plan.aliases)) renamed.push(`${plan.name}:${from} -> ${to}`);
+  }
+
+  // 旧版本自己的依赖也要跟着放进来，而且必须是同一批版本。
+  // 只装一个包，它加载时 import 的兄弟包要么找不到，要么拿到新版本，两种都不是插件当初的环境。
+  for (const [name, entry] of input.closure ?? new Map()) {
+    if (created.includes(name)) continue;
+    const destination = join(root, ...name.split('/'));
+    rmSync(destination, { recursive: true, force: true });
+    cpSync(entry.dir, destination, { recursive: true });
+    created.push(name);
+    renamed.push(`${name} 使用真实旧版本（${entry.version}）`);
+  }
+
+
+  dropStaleShims(input.pluginDir, root, created);
+
+  writeFileSync(
+    join(input.pluginDir, ENV_MARKER),
+    `${JSON.stringify({ runtimeVersion: input.runtimeVersion, packages: created }, null, 2)}\n`,
+    'utf8',
+  );
+  return { status: 'installed', packages: created, missing: [], renamed };
+}
+
+// 把导入清单按包名归组，顺带记下每个包被用到的子路径。
+//
+// 返回 [{ name, symbols, subpaths }]，name 一定是裸包名。
+function groupImports(imports) {
+  const groups = new Map();
+  for (const [specifier, symbols] of imports ?? new Map()) {
+    if (!DSH_PACKAGE.test(specifier)) continue;
+    const name = bareNameOf(specifier);
+    if (groups.has(name) === false) groups.set(name, { name, symbols: new Set(), subpaths: new Set() });
+    const group = groups.get(name);
+    for (const symbol of symbols ?? []) group.symbols.add(symbol);
+    // 包名之后的部分就是子路径，例如 lib/extra.js。
+    const tail = specifier.slice(name.length).replace(/^\//, '');
+    if (tail !== '') group.subpaths.add(tail);
+  }
+  return [...groups.values()].map((group) => ({
+    name: group.name,
+    symbols: [...group.symbols],
+    subpaths: [...group.subpaths],
+  }));
+}
+
+// 决定一个包该怎么装。不碰磁盘。
+//
+// 三条路：当前实现就满足，写一层薄垫片；当前实现缺符号，但已经拿到插件期望的
+// 真实旧版本，就把旧版本整份放进去；旧版本还没拿到，就告诉调用方去取。
+function planPackage(group, input) {
+  const { name, symbols } = group;
+  const realDir = resolveInstalledDir({ profileDir: input.profileDir, name, resolveDir: input.resolveDir });
+  if (realDir === undefined) return { name, symbols, missing: [`${name} (not installed in the profile)`] };
+
+  const realEntry = resolveEntryOf(realDir);
+  if (realEntry === undefined) return { name, symbols, missing: [`${name} (no resolvable entry module)`] };
+
+  // 插件从子路径导入时，那些符号在子路径模块里，根入口不一定有。
+  // 把可用的子路径文件也收进来，符号核对才看得全。
+  const extraTargets = group.subpaths
+    .map((tail) => join(realDir, ...tail.split('/')))
+    .filter((path) => existsSync(path));
+
+  const resolved = resolveSymbols(name, symbols, [realEntry, ...extraTargets]);
+
+  if (resolved.missing.length === 0) {
+    return { name, symbols, realEntry, extraTargets, aliases: resolved.aliases, missing: [] };
+  }
+
+  // 当前实现确实缺东西。要么用插件期望的那份真实旧版本，要么如实报缺。
+  const old = input.oldVersionDirs?.get(name);
+  if (old === undefined) {
+    return { name, symbols, missing: [], needsOldVersion: { name, version: declaredVersionOf(input, name), symbols: resolved.missing } };
+  }
+
+  // 拿到旧版本了，再核一遍：旧版本里必须真的有这些符号，否则装上去也没用。
+  const oldEntry = resolveEntryOf(old.dir);
+  if (oldEntry === undefined) return { name, symbols, missing: [`${name}@${old.version} (旧版本没有可用的入口文件)`] };
+  const againstOld = resolveSymbols(name, symbols, [oldEntry]);
+  if (againstOld.missing.length > 0) {
+    return { name, symbols, missing: [`${name}@${old.version} 里也没有 ${againstOld.missing.map((item) => item.split(':')[1]).join(', ')}`] };
+  }
+  return { name, symbols, copyFrom: old.dir, oldVersion: old.version, missing: [] };
+}
+
+// 插件声明的是哪个版本；没声明就跟着运行时走。
+function declaredVersionOf(input, name) {
+  const range = input.requirements?.[name];
+  return pinnedVersion(range, input.runtimeVersion);
+}
+
+// 定位包入口。asar 内的入口 existsSync 看不到，但能读，所以只在非 asar 路径上做这个检查。
+function resolveEntryOf(realDir) {
+  const realManifest = readJson(join(realDir, 'package.json'));
+  const realEntry = realManifest === undefined ? undefined : entryPathOf(realDir, realManifest);
+  if (realEntry === undefined) return undefined;
+  if (realEntry.includes('app.asar')) return realEntry;
+  return existsSync(realEntry) ? realEntry : undefined;
+}
+
+// 核对一个包里插件要用的符号，把改名的、缺失的分出来。
+//
+// 目标可能不止一个文件：插件从包根和子路径都导入时，符号散在几处，都得算数。
+function resolveSymbols(name, symbols, targets) {
+  const available = [];
+  const needles = [];
+  for (const target of targets) {
+    const exported = parseExportedNames(target, (file) => readFileSync(file, 'utf8'));
+    // 空清单同样不可信：CommonJS 包读出来的就是空数组，不能据此判它什么也没导出。
+    if (exported !== undefined && exported.length > 0) {
+      available.push(...exported);
+      continue;
+    }
+    // 导出清单读不出来时退回按词边界搜源码，粗一点但能抓到一个明摆着不存在的符号。
+    const source = readFileSync(target, 'utf8');
+    needles.push(source);
+  }
+
+  const present = (symbol) => {
+    if (available.includes(symbol)) return true;
+    const pattern = new RegExp(`\\b${symbol.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`);
+    return needles.some((source) => pattern.test(source));
+  };
+
+  const aliases = {};
+  const missing = [];
+  for (const symbol of symbols) {
+    if (symbol === 'default' || present(symbol)) continue;
+    const candidate = guessRenamedSymbol(symbol, available);
+    if (candidate !== undefined && present(candidate)) {
+      aliases[symbol] = candidate;
+      continue;
+    }
+    // 当前实现确实没有这个符号。不编造、也不放会抛错的占位——
+    // 要么换上插件期望的真实旧版本（由调用方去取），要么如实报缺。
+    missing.push(`${name}:${symbol}`);
+  }
+  return { aliases, missing };
+}
+
+// 清掉这个插件已经不需要的垫片。升级后不再导入某个包了，那层旧副本不能留着遮住真身。
+function dropStaleShims(pluginDir, root, created) {
+  const previous = readCompatEnvironment(pluginDir);
+  for (const stale of previous?.packages ?? []) {
+    if (created.includes(stale)) continue;
+    try {
+      rmSync(join(root, ...stale.split('/')), { recursive: true, force: true });
+    } catch {
+      // 目录被占用就留给下一轮
+    }
+  }
+}
+
+// 拆掉兼容环境，把插件还原成它发布时的样子。
+export function removeCompatEnvironment(pluginDir) {
+  const marker = join(pluginDir, ENV_MARKER);
+  const environment = readJson(marker);
+  const root = join(pluginDir, 'node_modules');
+  let removed = false;
+  // 只删这个环境自己建的包。插件可能自带 node_modules（打包进来的依赖），
+  // 整个目录一删就把跟兼容无关的东西也毁了。
+  for (const name of environment?.packages ?? []) {
+    try {
+      rmSync(join(root, ...name.split('/')), { recursive: true, force: true });
+      removed = true;
+    } catch {
+      /* a locked directory is retried on the next scan */
+    }
+  }
+  // 把环境留下的空目录收掉，这样没有自带依赖的插件能恢复成发布时的样子。
+  pruneEmptyTree(root);
+  try {
+    rmSync(marker, { force: true });
+  } catch {
+    /* nothing to do */
+  }
+  return removed;
+}
+
+// 从最里层往外删空目录，碰到非空就停。
+function pruneEmptyTree(root) {
+  // 只走本模块自己造的 @scope/name 这种形状。插件自己的依赖树可能有几百个目录，
+  // 为了发现它非空而整个扫一遍，代价比这点清理本身还大。
+  const removeIfEmpty = (dir) => {
+    try {
+      if (readdirSync(dir).length === 0) rmdirSync(dir);
+    } catch {
+      /* missing or in use: nothing to prune */
+    }
+  };
+  let scopes;
+  try {
+    scopes = readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+  } catch {
+    return;
+  }
+  for (const scope of scopes) {
+    const dir = join(root, scope.name);
+    // A scoped package directory (`@deepseek-ai`) is pruned after its children.
+    if (scope.name.startsWith('@')) {
+      let children;
+      try {
+        children = readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+      } catch {
+        continue;
+      }
+      for (const child of children) removeIfEmpty(join(dir, child.name));
+    }
+    removeIfEmpty(dir);
+  }
+  removeIfEmpty(root);
+}
+
+// 把插件自己的 DSH 声明改成当前运行时满足的版本。
+export function alignManifest(input) {
+  const manifestPath = join(input.pluginDir, 'package.json');
+  const manifest = readJson(manifestPath);
+  if (manifest === undefined) return { status: 'skipped', rewrote: [], error: 'package.json is unreadable' };
+
+  const { next, rewrote } = realignDeclarations(manifest, input.versions, input.runtimeVersion);
+  if (rewrote.length === 0) return { status: 'already', rewrote: [] };
+
+  const preserved = preserveOriginal(manifestPath, join(input.pluginDir, MANIFEST_BACKUP));
+  if (preserved !== undefined) return { status: 'failed', rewrote: [], error: preserved };
+  const written = replaceAtomically(manifestPath, `${JSON.stringify(next, null, 2)}\n`);
+  if (written !== undefined) return { status: 'failed', rewrote: [], error: written };
+  return { status: 'aligned', rewrote };
+}
+
+// 算出插件在这个运行时下应该声明成什么样。
+function realignDeclarations(manifest, versions, runtimeVersion) {
+  const next = JSON.parse(JSON.stringify(manifest));
+  const rewrote = [];
+  for (const [name, target] of peerTargets(next, versions, runtimeVersion)) {
+    next.peerDependencies[name] = target;
+    rewrote.push(`peerDependencies.${name}`);
+  }
+  if (alignEnginesDsh(next, runtimeVersion)) rewrote.push('engines.dsh');
+  return { next, rewrote };
+}
+
+// 列出需要改动的那些 DSH peer 范围。
+//
+// 只改运行时自己发布的那几个（dsh*）。schemastery、cordis 有自己的版本线，
+// 把 "^3.18.5" 改成 "0.2.1-rc.3" 只会让声明变成假话——它们的实现根本没变。
+function peerTargets(manifest, versions, runtimeVersion) {
+  const peers = manifest.peerDependencies;
+  if (!isPlainObject(peers)) return [];
+  return Object.entries(peers)
+    .filter(([name, range]) => RUNTIME_OWNED.test(name) && typeof range === 'string')
+    .map(([name, range]) => [name, versions?.[name] ?? runtimeVersion, range])
+    .filter(([, target, range]) => typeof target === 'string' && range !== target)
+    .map(([name, target]) => [name, target]);
+}
+
+// 是不是普通对象（数组和 null 不算）。
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+// 把 engines.dsh 指到当前运行时。
+function alignEnginesDsh(manifest, runtimeVersion) {
+  const engines = manifest.engines;
+  if (engines === null || typeof engines !== 'object') return false;
+  if (typeof engines.dsh !== 'string' || typeof runtimeVersion !== 'string') return false;
+  if (engines.dsh === runtimeVersion) return false;
+  engines.dsh = runtimeVersion;
+  return true;
+}
+
+// 把原来的 manifest 备份一份，只备一次。
+function preserveOriginal(manifestPath, backupPath) {
+  try {
+    if (!existsSync(backupPath)) copyFileSync(manifestPath, backupPath);
+    return undefined;
+  } catch (error) {
+    return `could not preserve the original manifest: ${String(error)}`;
+  }
+}
+
+// 走临时文件再改名的方式替换文件。
+function replaceAtomically(path, content) {
+  const temporary = `${path}.@luolingp/request-doctor-tmp`;
+  try {
+    writeFileSync(temporary, content, 'utf8');
+    renameSync(temporary, path);
+    return undefined;
+  } catch (error) {
+    try {
+      rmSync(temporary, { force: true });
+    } catch {
+      /* the temp file is harmless if it cannot be removed */
+    }
+    return String(error);
+  }
+}
+// 还原插件原本的 manifest。
+export function restoreManifest(pluginDir) {
+  const manifestPath = join(pluginDir, 'package.json');
+  const backupPath = join(pluginDir, MANIFEST_BACKUP);
+  if (!existsSync(backupPath)) return false;
+  try {
+    renameSync(backupPath, manifestPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// 读一下已装环境的标记，没有就返回 undefined。
+export function readCompatEnvironment(pluginDir) {
+  return readJson(join(pluginDir, ENV_MARKER));
+}

package/lib/compat-repair.js

@@ -0,0 +1,196 @@
+// 找到装好的插件，拿它跟当前运行时对一遍。
+//
+// 这是版本修复里「能不能真跑」那一半：manifest 里的 peer 范围只是句声明，
+// 所以放行之前要拿插件实际导入的东西，去对运行时实际导出的东西。
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import {
+  auditPluginCompatibility,
+  collectDshImports,
+  collectIdLiterals,
+  collectProviderIds,
+  parseExportedNames,
+  registersVariantRoute,
+} from './compat.js';
+
+// 一个插件的模块图最多读这么多个文件
+const MAX_GRAPH_FILES = 40;
+
+// 读文件，读不到就返回 undefined
+function readText(path) {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return undefined;
+  }
+}
+
+// 从 profile 目录推算某个包的安装位置
+export function packageDir(profileDir, name) {
+  if (profileDir === undefined) return undefined;
+  try {
+    const require = createRequire(join(profileDir, 'package.json'));
+    return dirname(require.resolve(`${name}/package.json`));
+  } catch {
+    return undefined;
+  }
+}
+
+// 算出某个已装包的入口文件路径。
+export function installedEntryPath(profileDir, name) {
+  const dir = packageDir(profileDir, name);
+  if (dir === undefined) return undefined;
+  const manifestText = readText(join(dir, 'package.json'));
+  if (manifestText === undefined) return undefined;
+  let manifest;
+  try {
+    manifest = JSON.parse(manifestText);
+  } catch {
+    return undefined;
+  }
+  return entryPathOf(dir, manifest);
+}
+
+// 算出一个包的入口文件在哪。
+export function entryPathOf(dir, manifest) {
+  const pick = (value) => {
+    if (typeof value === 'string') return value;
+    if (value !== null && typeof value === 'object') {
+      for (const key of ['default', 'import', 'node', 'require']) {
+        const nested = pick(value[key]);
+        if (nested !== undefined) return nested;
+      }
+    }
+    return undefined;
+  };
+  const exported = manifest?.exports;
+  const fromExports = pick(exported?.['.'] ?? (typeof exported === 'string' ? exported : undefined));
+  const relative = fromExports ?? (typeof manifest?.main === 'string' ? manifest.main : 'index.js');
+  return relative === undefined ? undefined : resolve(dir, relative);
+}
+
+// 把一个插件的 DSH 导入和 LLM provider 路由一起收上来。
+export function collectPackageFacts(dir, entryPath) {
+  const scan = { imports: new Map(), providers: new Set(), literals: new Set(), variantRoute: false };
+  walkModuleGraph(entryPath, scan);
+  // A variant route's id lives in a sibling chunk; any declared id could be it.
+  if (scan.variantRoute) for (const id of scan.literals) scan.providers.add(id);
+  return { imports: scan.imports, providers: [...scan.providers] };
+}
+
+// 读一个模块和它相对路径上的依赖，把结果累计起来。
+//
+// 只跟相对导入：打包进来的 chunk 自己的 DSH 导入属于这个插件的契约，
+// 但它的第三方依赖不算。
+function walkModuleGraph(entryPath, scan) {
+  const queue = [entryPath];
+  const seen = new Set();
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === undefined || seen.has(current)) continue;
+    seen.add(current);
+    if (seen.size > MAX_GRAPH_FILES) break;
+    const source = readText(current);
+    if (source === undefined) continue;
+    absorbModule(source, current, scan, queue);
+  }
+}
+
+// 把一个模块里的声明并进累加器，再把它导入的模块排进队列。
+function absorbModule(source, current, scan, queue) {
+  for (const [packageName, symbols] of collectDshImports(source)) {
+    scan.imports.set(packageName, [...new Set([...(scan.imports.get(packageName) ?? []), ...symbols])]);
+  }
+  for (const id of collectProviderIds(source)) scan.providers.add(id);
+  for (const id of collectIdLiterals(source)) scan.literals.add(id);
+  if (registersVariantRoute(source)) scan.variantRoute = true;
+  for (const target of relativeImportsOf(source, current)) queue.push(target);
+}
+
+// 把模块里的相对导入解析成真实存在的文件路径。
+function relativeImportsOf(source, current) {
+  const found = [];
+  const pattern = /\bfrom\s*["'](\.[^"']+)["']/g;
+  let match;
+  while ((match = pattern.exec(source)) !== null) {
+    const target = resolve(dirname(current), match[1]);
+    for (const candidate of [target, `${target}.js`, join(target, 'index.js')]) {
+      if (readText(candidate) !== undefined) {
+        found.push(candidate);
+        break;
+      }
+    }
+  }
+  return found;
+}
+
+// 拿一个已装的 bundle 跟当前运行时对一遍。
+// 插件查不了的时候，按这个形状返回。
+function review(reason) {
+  return { verdict: 'review', reasons: [reason], missing: [], imports: [], providers: [] };
+}
+
+export async function auditInstalledPlugin(input) {
+  const dir = packageDir(input.profileDir, input.name);
+  if (dir === undefined) {
+    return review(`${input.name} is not installed under ${input.profileDir}`);
+  }
+  // 调用方判断「要审计」的时候八成已经解析过这个 manifest 了，直接拿来用，别读第二遍。
+  let manifest = input.manifest;
+  if (manifest === undefined) {
+    const manifestText = readText(join(dir, 'package.json'));
+    if (manifestText === undefined) {
+      return review(`${input.name} has no readable package.json`);
+    }
+    try {
+      manifest = JSON.parse(manifestText);
+    } catch (error) {
+      return review(`${input.name}/package.json is not valid JSON: ${String(error)}`);
+    }
+  }
+  const entry = entryPathOf(dir, manifest);
+  if (entry === undefined) {
+    return review(`${input.name} declares no resolvable entry module`);
+  }
+  const facts = collectPackageFacts(dir, entry);
+  const { imports, providers } = facts;
+  // 一个 DSH 包都不导入的插件，就没有符号可验。这时候声明满足就够了——
+  // 它跟运行时之间只有 manifest 这一层契约，没有别的可能出错的地方。
+  // 一个 DSH 包都不导入的插件，就没有符号可验。它跟运行时之间只有 manifest 这一层契约，
+  // 声明对不上也只是这一层的事——把声明对齐过去就能跑，不需要人来点头。
+  // 皮肤、纯客户端界面这类插件全是这种。
+  if (imports.size === 0) {
+    const unmet = Object.keys(input.requirements ?? {});
+    return {
+      verdict: 'compatible',
+      reasons: [unmet.length === 0
+        ? `${input.name} imports no @deepseek-ai package, so its manifest declaration is the whole contract, and it holds`
+        : `${input.name} imports no @deepseek-ai package; only its manifest declaration needs realigning`],
+      missing: [],
+      imports: [],
+      providers,
+    };
+  }
+  const exportsCache = new Map();
+  const exportsOf = async (packageName) => {
+    if (exportsCache.has(packageName)) return exportsCache.get(packageName);
+    const runtimeEntry = input.runtimeEntryOf?.(packageName);
+    const names = runtimeEntry === undefined ? undefined : parseExportedNames(runtimeEntry, readText);
+    exportsCache.set(packageName, names);
+    return names;
+  };
+  const audit = input.assumeCompatible === true
+    ? { verdict: 'compatible', reasons: ['already aligned for this runtime by a prepared install'], missing: [], conflicts: [] }
+    : await auditPluginCompatibility({
+    runtimeVersion: input.runtimeVersion,
+    requirements: input.requirements,
+    imports,
+    exportsOf,
+    providerIds: providers,
+    takenProviders: input.takenProviders ?? [],
+  });
+  // `importMap` is what the environment builder needs: which symbols to verify
+  // 在重定位插件导入之前，先拿每个真实包核一遍。
+  return { ...audit, imports: [...imports.keys()], importMap: imports, providers };
+}