@luolingp/request-doctor 0.0.0-stage → 0.11.1

package/lib/model-repair.js

@@ -0,0 +1,190 @@
+// 模型请求的修复。
+//
+// 收到一次失败的模型请求后：判断属于哪一类，按这一类的策略先做本地修复，再决定要不要
+// 花掉一份重试预算。provider 自己声明了重试策略的，优先听它的——只有下游所有监听器都
+// 放弃重试了，这里才接手，免得出现两条重试链。
+//
+// 三类防护都在这层：
+// - 预算：按 turn:step:provider:kind 分组，同一处失败有统一上限；
+// - 并发：同一处同时只允许一个重试在飞，避免重试风暴把本机拖死；
+// - 无进展：压缩/修历史连续两轮都没让问题前进，就不再无限重试。
+import { classifyModelFailure, computeDelay } from './classify.js';
+import { cancellableSleep } from './sleep.js';
+
+// 每个策略分到的预算倍数。鉴权类的重试更贵（要换凭据），给的次数更少。
+const STRATEGY_BUDGET = { auth: 'auth', 'history-repair': 'history', compact: 'normal' };
+
+export function createModelRepair(input) {
+  const { config, lifetime, diagnostics, ledger, versionRepair, services, warn } = input;
+  const { record, stats } = diagnostics;
+
+  // 同一处同时在飞的重试：key 相同就只放一个进去。
+  const inFlight = new Set();
+  // 压缩/修历史有没有让问题前进：连着两轮没进展就停手。
+  const progress = new Map();
+
+  // 把请求自己的取消信号和插件生命周期绑在一起，插件卸载时正在等的重试能立刻醒。
+  const fuse = (signal) => {
+    if (signal === undefined) return lifetime.signal;
+    try {
+      return AbortSignal.any([signal, lifetime.signal]);
+    } catch {
+      return signal;
+    }
+  };
+
+  // 上下文超长时，重试之前先试着瘦身。
+  //
+  // 压缩和裁剪工具结果分别由两个可选服务提供，profile 里一个都没有也照样重试，
+  // 所以两个都是能成就成。
+  async function compactForOverflow(payload) {
+    const compaction = services.get('compaction');
+    if (compaction !== undefined) {
+      try {
+        await compaction.compactIfNeeded(payload.agent, 'context-overflow', payload.signal);
+      } catch (error) {
+        warn(`request-doctor: overflow compaction failed: ${String(error)}`);
+      }
+    }
+    pruneToolResults(payload);
+  }
+
+  // 裁掉过期的工具结果。裁剪器没有就跳过。
+  function pruneToolResults(payload) {
+    const pruner = services.get('toolResultPruner');
+    if (pruner === undefined) return;
+    try {
+      pruner.pruneSession(payload.agent.session);
+    } catch {
+      // 裁剪不了就算了
+    }
+  }
+
+  // 本地历史或规则文件坏了：清掉工具结果、让会话重新落盘，能救回来一部分。
+  async function repairHistory(payload) {
+    pruneToolResults(payload);
+    const store = services.get('sessionStore');
+    if (store === undefined) return;
+    try {
+      await store.flush?.(payload.agent.session);
+    } catch (error) {
+      warn(`request-doctor: history flush failed: ${String(error)}`);
+    }
+  }
+  // 请本机某个服务刷新一次。候选名字挨个试，第一个能刷的就够了；
+  // 一个都没有也不算错——下游自己的重试同样可能触发刷新。
+  async function ask(names, kind, payload) {
+    for (const name of names) {
+      const provider = services.get(name)
+      if (provider === undefined) continue
+      try {
+        await provider.refresh?.(payload.provider, payload.signal)
+        record(kind, `asked ${name} to refresh ${kind} for ${payload.provider}`)
+        return
+      } catch (error) {
+        warn(`request-doctor: ${name} refresh failed: ${String(error)}`)
+      }
+    }
+  }
+
+  // 凭据类失败：让本机的凭据层有机会刷新一次。
+  const refreshCredentials = (payload) => ask(['credentials', 'auth', 'accounts'], 'auth', payload)
+
+  // 模型选择类失败（模型 ID 写死、能力表判断错、模型列表缓存过期）：
+  // 让本机的模型目录服务重新拉一次，缓存过期是最常见的成因。
+  const refreshModelCatalog = (payload) => ask(['modelCatalog', 'models', 'providerRegistry'], 'model', payload)
+
+  // 按策略先做本地修复；返回 false 表示这一类的修复没成，重试也没意义。
+  async function prepare(decision, payload) {
+    if (decision.strategy === 'version-repair') {
+      const fixed = await versionRepair.run(`model-${decision.kind}`);
+      return fixed.length > 0;
+    }
+    if (decision.strategy === 'compact') {
+      await compactForOverflow(payload);
+      return true;
+    }
+    if (decision.strategy === 'history-repair') {
+      await repairHistory(payload);
+      return true;
+    }
+    if (decision.strategy === 'auth') {
+      await refreshCredentials(payload);
+      return true;
+    }
+    // retry 和 local 都是直接重来，local 的那点延迟由退避自动拉开。
+    return decision.strategy === 'retry' || decision.strategy === 'local';
+  }
+
+  // 这一类的次数上限。鉴权类更贵，单独一个更小的额度。
+  function budgetFor(decision) {
+    const policy = config();
+    if (STRATEGY_BUDGET[decision.strategy] === 'auth') return policy.maxAuthRetries;
+    if (STRATEGY_BUDGET[decision.strategy] === 'history') return Math.max(1, Math.floor(policy.maxRetries / 3));
+    return policy.maxRetries;
+  }
+
+  // 花掉一份重试预算，安排下一次尝试。
+  async function scheduleRetry(key, payload, decision, downstream) {
+    const entry = ledger.chainFor(payload.agent, key);
+    entry.count += 1;
+    const limit = budgetFor(decision);
+    if (entry.count > limit) {
+      stats.modelSkips += 1;
+      if (entry.count === limit + 1) record('give-up', `${decision.kind} from ${payload.provider} after ${limit} repairs`);
+      return downstream;
+    }
+    const delayMs = computeDelay(config(), entry.count, payload.failure);
+    ledger.recordScheduled(payload.agent, payload, decision.kind, entry, delayMs);
+    if (!(await cancellableSleep(delayMs, fuse(payload.signal)))) return downstream;
+    ledger.recordStarted(payload.agent, payload, entry);
+    stats.modelRepairs += 1;
+    record('model', `${decision.kind} from ${payload.provider} attempt ${entry.count} in ${delayMs}ms`);
+    return { kind: 'retry' };
+  }
+
+  // 处理一次失败的模型请求。
+  //
+  // 先让下游跑完：只要有人愿意重试，就不再插一脚。
+  async function handle(payload, next) {
+    const downstream = await next();
+    if (downstream?.kind === 'retry') return downstream;
+    if (payload.signal?.aborted || lifetime.signal.aborted) return downstream;
+
+    const decision = classifyModelFailure(payload.failure);
+    if (!decision.clientCaused || decision.strategy === 'skip') return downstream;
+
+    const key = `${payload.turn}:${payload.step}:${payload.provider}:${decision.kind}`;
+    // 同一处只放一个重试进去。并发的那几个直接让下游收场，避免重试互相叠加。
+    if (inFlight.has(key)) return downstream;
+    inFlight.add(key);
+    try {
+      return await attempt(key, payload, decision, downstream);
+    } finally {
+      inFlight.delete(key);
+    }
+  }
+
+  // 依次过三关：本地修复成不成、还有没有进展、预算还剩不剩。
+  async function attempt(key, payload, decision, downstream) {
+    if (!(await prepare(decision, payload))) {
+      stats.modelSkips += 1;
+      return downstream;
+    }
+    if (recordProgress(key) === false) {
+      record('give-up', `${decision.kind} made no progress after two attempts`);
+      return downstream;
+    }
+    return scheduleRetry(key, payload, decision, downstream);
+  }
+
+  // 记一次「这一处又失败了」。同一处连着两轮都失败，说明修复没起作用。
+  function recordProgress(key) {
+    const count = (progress.get(key) ?? 0) + 1;
+    if (count > 2) return false;
+    progress.set(key, count);
+    return true;
+  }
+
+  return { handle };
+}

package/lib/package-fetch.js

@@ -0,0 +1,181 @@
+// 从 npm 取一个指定版本的包，解到本地。
+//
+// 兼容模式要真的把旧实现放回去，而不是假装。插件当初是对着某个版本写的，
+// 那个版本的代码还在仓库里，取下来装上就行——这才是「给它一个能跑的旧环境」。
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { gunzipSync } from 'node:zlib';
+
+const REGISTRY = 'https://registry.npmjs.org';
+const TIMEOUT_MS = 20000;
+
+// 元数据留一会儿。一次扫描里同一个包会被问好几遍（取地址、列版本），
+// 每次都打注册表既慢又没礼貌。
+const META_TTL_MS = 10 * 60 * 1000;
+const metaCache = new Map();
+
+// 取包的元数据，带缓存。
+async function metadataOf(name) {
+  const cached = metaCache.get(name);
+  const now = Date.now();
+  if (cached !== undefined && now - cached.at < META_TTL_MS) return cached.value;
+
+  const response = await fetch(`${REGISTRY}/${encodedName(name)}`, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+  if (!response.ok) return undefined;
+  const value = await response.json();
+  metaCache.set(name, { at: now, value });
+  return value;
+}
+
+// scoped 包的路径要编码成 %2F，否则注册表会当成两个路径段。
+const encodedName = (name) => name.replace('/', '%2F');
+
+// 取元数据，拿到指定版本的 tarball 地址。
+async function tarballUrlOf(name, version) {
+  const meta = await metadataOf(name);
+  const url = meta?.versions?.[version]?.dist?.tarball;
+  return typeof url === 'string' ? url : undefined;
+}
+
+// 列出注册表里所有已发布的版本。
+//
+// 缺符号时要挨个试，所以得先知道有哪些版本可选。取不到就返回空数组，
+// 调用方据此退回「只试钉住的那个版本」。
+export async function listVersions(name) {
+  try {
+    const meta = await metadataOf(name);
+    return Object.keys(meta?.versions ?? {});
+  } catch {
+    return [];
+  }
+}
+
+// 读 tar 头里的字符串字段，遇 NUL 截断。
+function readString(block, offset, length) {
+  let end = offset;
+  while (end < offset + length && block[end] !== 0) end += 1;
+  return block.subarray(offset, end).toString('utf8');
+}
+
+// 读八进制数字字段，空值按 0 处理。
+function readOctal(block, offset, length) {
+  const text = readString(block, offset, length).trim();
+  return text === '' ? 0 : parseInt(text, 8);
+}
+
+// 解 PAX 扩展头。`path=` 那一行给出下一个条目的真实路径，长文件名靠它。
+function paxPathOf(buffer) {
+  const text = buffer.toString('utf8');
+  for (const line of text.split('\n')) {
+    const match = /^\d+ path=(.*)$/.exec(line);
+    if (match !== null) return match[1];
+  }
+  return undefined;
+}
+
+// 解 tar。npm 的包是 gzip 压缩的 tar，里面统一带一层 `package/` 前缀。
+//
+// 两种长文件名写法都要认：GNU 用一个独立的 `L` 条目把名字放在数据区，PAX 用 `x` 条目里的
+// `path=`。不认的话，路径超过一百字节的文件会被截断或丢掉——装出来的包看着完整，
+// 加载时却报「找不到某个文件」，而且很难看出问题出在解包这一步。
+function extractTar(buffer, destDir) {
+  let offset = 0;
+  let pendingName;
+  // npm 的包里所有条目都在同一层根目录下，但那个目录叫什么并不固定：
+  // 常见是 `package/`，也有用 `<repo>-<commit>/` 的。按实际首段剥掉，别写死。
+  let rootPrefix;
+
+  while (offset + 512 <= buffer.length) {
+    const header = buffer.subarray(offset, offset + 512);
+    if (header.every((byte) => byte === 0)) break;
+
+    const name = readString(header, 0, 100);
+    const prefix = readString(header, 345, 155);
+    const size = readOctal(header, 124, 12);
+    const type = readString(header, 156, 1) || '0';
+    const dataStart = offset + 512;
+    const data = buffer.subarray(dataStart, dataStart + size);
+
+    pendingName = nameFromHeaderRecord(type, data, pendingName);
+    if (isMetaRecord(type) === false) {
+      const declared = pendingName ?? (prefix === '' ? name : `${prefix}/${name}`);
+      pendingName = undefined;
+      rootPrefix = rootPrefix ?? rootPrefixOf(type, declared);
+      writeMember(destDir, stripRoot(declared, rootPrefix), type, data);
+    }
+
+    // 数据区按 512 向上取整。
+    offset = dataStart + Math.ceil(size / 512) * 512;
+  }
+}
+
+// 名字单独占一条记录的两种写法：GNU 的 L 和 PAX 的 x。全局头 g 跟名字无关。
+const META_RECORDS = new Set(['L', 'x', 'g']);
+
+function isMetaRecord(type) {
+  return META_RECORDS.has(type);
+}
+
+// 元数据记录里带着下一个条目的真实路径，记下来交给下一条用。
+function nameFromHeaderRecord(type, data, previous) {
+  if (type === 'L') return data.toString('utf8').replace(/\0+$/, '');
+  if (type === 'x') return paxPathOf(data) ?? previous;
+  return previous;
+}
+
+// 包的根目录只在第一个目录条目上取一次，之后一直用它。
+function rootPrefixOf(type, declared) {
+  if (type !== '5' || !declared.includes('/')) return undefined;
+  return declared.replace(/\/+$/, '');
+}
+
+// 落一个文件。目录、空路径、越界路径都不写。
+function writeMember(destDir, relative, type, data) {
+  if (relative === '' || type !== '0') return;
+  const target = join(destDir, ...relative.split('/'));
+  // 防目录穿越：解出来的路径必须还在目标目录里。
+  // 比较前统一分隔符——join 在 Windows 上给的是反斜杠。
+  if (!resolve(target).startsWith(resolve(destDir) + sep)) return;
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, data);
+}
+
+// 剥掉包的根目录，留下包内的相对路径。
+//
+// 根目录还没认出来时按第一段剥——tar 里第一个文件条目总在根目录下。
+function stripRoot(declared, rootPrefix) {
+  if (rootPrefix !== undefined) {
+    if (!declared.startsWith(`${rootPrefix}/`)) return '';
+    return declared.slice(rootPrefix.length + 1);
+  }
+  const cut = declared.indexOf('/');
+  return cut < 0 ? declared : declared.slice(cut + 1);
+}
+
+// 解一段已经拿到手的 tar 数据。抽出来单测用，也方便别处复用。
+export function readPackageFromTar(buffer, destDir) {
+  extractTar(buffer, destDir);
+}
+
+// 把 name@version 完整取下来解到 destDir。
+//
+// @param {string} name - 包名。
+// @param {string} version - 精确版本号。
+// @param {string} destDir - 解压目标目录。
+// @returns {Promise<{ok: boolean, error?: string}>}
+export async function fetchPackage(name, version, destDir) {
+  try {
+    const url = await tarballUrlOf(name, version);
+    if (url === undefined) return { ok: false, error: `${name}@${version} 在注册表里找不到` };
+
+    const response = await fetch(url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    if (!response.ok) return { ok: false, error: `下载 ${name}@${version} 失败：HTTP ${response.status}` };
+
+    const tar = gunzipSync(Buffer.from(await response.arrayBuffer()));
+    mkdirSync(destDir, { recursive: true });
+    extractTar(tar, destDir);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: String(error) };
+  }
+}

package/lib/plugin-discovery.js

@@ -0,0 +1,232 @@
+// 找出所有需要处理的插件。
+//
+// 一个插件需要处理，有四种可能：声明不满足、Loader 拒绝过、装好了但起不来、为安装准备的
+// 环境还没建成。代码会从这几个来源分别收一遍，按包名去重后交给审计。
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { unmetPeers } from './compat.js';
+import { entryPathOf, packageDir } from './compat-repair.js';
+import { verifyEnvironment } from './env-verify.js';
+import { readStagedPreparation } from './install-support.js';
+
+  // 找出所有声明不满足的已装插件，要的是全集，不是一个例子。
+//
+// 四个来源都看，因为不匹配可能藏在任何一处：
+//  - Loader 拒绝的 bundle 自带它算出的未满足集合；
+//  - 已启用的插件也可能不匹配，DSH 未必会说；
+//  - 已禁用但装着的也算，用户哪天启用时应该已经适配好；
+//  - 为安装准备好的插件如果环境还欠着，manifest 已经对齐，只有标记能看出来。
+export async function collectMismatched(bundles, facts, plugins, probe) {
+  const all = [
+    ...deferredCandidates(plugins, facts, probe),
+    ...refusedCandidates(bundles, facts),
+    ...installedCandidates(plugins, facts, probe),
+    // 加载失败的插件不会出现在 listPlugins() 里，所以还得自己去目录里翻一遍。
+    ...scannedCandidates(plugins, facts, probe),
+  ];
+  const seen = new Set();
+  return all.filter((item) => admit(item, seen));
+}
+
+// 直接扫 profile 的 node_modules，把 listPlugins() 看不到的插件也找出来。
+//
+// 插件一旦加载失败就不在 Loader 树里，listPlugins() 自然不会返回它——可它恰恰是最需要
+// 处理的那种。这里按目录兜底：凡是有 dsh.bundle 声明、且清单里没出现过的，都算候选。
+function scannedCandidates(plugins, facts, probe) {
+  if (facts.profileDir === undefined) return [];
+  const known = new Set((plugins ?? []).map((entry) => entry?.moduleName).filter((name) => typeof name === 'string'));
+  return installedPluginNames(facts.profileDir)
+    .map((name) => scanOne(name, facts, probe, known))
+    .filter((item) => item !== undefined);
+}
+
+// 扫到一个插件目录后，判断它要不要进候选。
+function scanOne(name, facts, probe, known) {
+  const dir = packageDir(facts.profileDir, name);
+  if (dir === undefined) return;
+  const manifest = probe.readManifestCached(join(dir, 'package.json'));
+  if (manifest?.dsh?.bundle === undefined) return undefined;
+
+  const requirements = unmetPeers(manifest, facts.runtimeVersion);
+  // 声明就不满足的，肯定要处理，不必再去看源码。
+  if (Object.keys(requirements).length > 0) return candidate(name, manifest, requirements, facts);
+
+  // 声明已经满足，就看环境齐不齐：它实际导入的每个 DSH 包都要有垫片，
+  // 否则加载时照样找不到东西，表现就是装上了却起不来。
+  const imports = pluginImports(dir, manifest, probe, facts);
+  // 光有垫片不算数，内容也得对：缺一个导出插件照样起不来。
+  // 环境核对通过才算齐，否则重新适配一遍。
+  if (environmentCovers(dir, imports) && verifyEnvironment({ pluginDir: dir, imports }).ok) return undefined;
+  // 环境不齐就得补，跟它在不在 listPlugins 里无关——
+  // 恰恰是已启用却加载失败的插件最需要处理。
+  return candidate(name, manifest, declaredPeers(manifest), facts);
+}
+
+// 读出插件实际导入了哪些 DSH 包。
+function pluginImports(dir, manifest, probe, facts) {
+  const entry = entryPathOf(dir, manifest);
+  if (entry === undefined) return new Map();
+  try {
+    return probe.factsOf(dir, entry, facts.runtimeVersion).imports;
+  } catch {
+    return new Map();
+  }
+}
+
+// 组装一条候选。
+function candidate(name, manifest, requirements, facts) {
+  return {
+    name,
+    version: manifest.version ?? '0.0.0',
+    requirements,
+    runtimeVersion: facts.runtimeVersion,
+    needsEnvironment: true,
+  };
+}
+
+// 检查插件实际导入的那些 DSH 包，是不是都在自己的 node_modules 里有垫片。
+//
+// 判据必须用它真正 import 的包，而不是 peerDependencies 里声明的全部。
+// 声明往往列出十几个包，实际代码只用到两三个；按声明来判，环境永远显得"不完整"，
+// 于是每轮都重试，把真正该做的事淹没在重复劳动里。
+function environmentCovers(pluginDir, imports) {
+  if (imports === undefined || imports.size === 0) return true;
+  const nested = join(pluginDir, 'node_modules');
+  for (const name of imports.keys()) {
+    if (!name.startsWith('@deepseek-ai/')) continue;
+    if (!existsSync(join(nested, ...name.split('/'), 'package.json'))) return false;
+  }
+  return true;
+}
+// 列出 profile 的 node_modules 里所有包名，包括 @scope/name 两层结构。
+export function installedPluginNames(profileDir) {
+  const root = join(profileDir, 'node_modules');
+  const names = [];
+  let entries;
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return names;
+  }
+  for (const entry of entries) {
+    // 符号链接也要算：link: 安装的插件在 node_modules 里就是个链接。
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (entry.name.startsWith('.')) continue;
+    if (entry.name.startsWith('@')) {
+      let scoped;
+      try {
+        scoped = readdirSync(join(root, entry.name), { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const child of scoped) {
+        if (child.isDirectory() || child.isSymbolicLink()) names.push(entry.name + "/" + child.name);
+      }
+      continue;
+    }
+    names.push(entry.name);
+  }
+  return names;
+}
+
+// 一个候选该不该进审计。首次遇到以先到的为准，没有未满足要求的不必审计。
+function admit(item, seen) {
+  if (typeof item.name !== 'string' || item.name === '') return false;
+  if (Object.keys(item.requirements).length === 0) return false;
+  if (seen.has(item.name)) return false;
+  seen.add(item.name);
+  return true;
+}
+// 把一个插件条目解析成目录和 manifest。
+export function resolveEntry(entry, facts, probe) {
+  if (typeof entry?.moduleName !== 'string') return undefined;
+  if (facts.profileDir === undefined) return undefined;
+  const dir = packageDir(facts.profileDir, entry.moduleName);
+  if (dir === undefined) return undefined;
+  const manifest = probe.readManifestCached(join(dir, 'package.json'));
+  return manifest === undefined ? undefined : { name: entry.moduleName, dir, manifest };
+}
+
+// 为安装做好准备、但环境还欠着的插件。它们的 manifest 已经对齐，只有准备标记能说明还差什么。
+// 准备标记还代表有待办吗。已经建好包的就是完事了，只有延后的才要补建。
+function needsEnvironment(pending) {
+  if (pending === undefined) return false;
+  return (pending.packages ?? []).length === 0;
+}
+function deferredCandidates(plugins, facts, probe) {
+  return (plugins ?? [])
+    .map((entry) => resolveEntry(entry, facts, probe))
+    .filter((resolved) => resolved !== undefined)
+    .map((resolved) => ({ resolved, pending: readStagedPreparation(resolved.dir) }))
+    .filter(({ pending }) => needsEnvironment(pending))
+    .map(({ resolved, pending }) => ({
+      name: resolved.name,
+      version: resolved.manifest.version ?? '0.0.0',
+      requirements: pending.requirements ?? {},
+      runtimeVersion: facts.runtimeVersion,
+      deferred: true,
+    }));
+}
+
+// 准备标记还代表有待办吗。已经建好包的就是完事了，只有延后的才要 Host 补建。
+function refusedCandidates(bundles, facts) {
+  const found = [];
+  for (const bundle of bundles ?? []) {
+    const issues = bundle?.error?.incompatible;
+    if (!Array.isArray(issues)) continue;
+    for (const issue of issues) {
+      if (typeof issue?.version !== 'string') continue;
+      found.push({
+        name: issue.name,
+        version: issue.version,
+        requirements: issue.requirements ?? {},
+        runtimeVersion: issue.runtimeVersion ?? facts.runtimeVersion,
+      });
+    }
+  }
+  return found;
+}
+
+// manifest 自己声明了未满足 peer 范围的已装插件。
+//
+// 既覆盖 DSH 没拒绝过的已启用插件，也覆盖已禁用的，这样后者被启用时已经是适配好的。
+function installedCandidates(plugins, facts, probe) {
+  return (plugins ?? [])
+    .map((entry) => installOne(entry, facts, probe))
+    .filter((item) => item !== undefined);
+}
+
+// 清单里已有的插件，判断它要不要进候选。
+function installOne(entry, facts, probe) {
+  const resolved = resolveEntry(entry, facts, probe);
+  if (resolved === undefined) return undefined;
+
+  const requirements = unmetPeers(resolved.manifest, facts.runtimeVersion);
+  const unmet = Object.keys(requirements).length > 0;
+  // manifest 已经满足、但插件根本没激活起来，也要管。
+  // 这种情况通常是声明之前对齐过、环境却没建成，光看 manifest 看不出来。
+  const failedToActivate = entry?.enabled === true && entry?.fiberPhase !== 'active';
+  const needsEnvironment = !unmet && failedToActivate;
+  if (!unmet && !needsEnvironment) return undefined;
+
+  return {
+    name: resolved.name,
+    version: resolved.manifest.version ?? '0.0.0',
+    // 声明没问题但起不来时，按它自己声明的 peer 范围去建环境。
+    requirements: needsEnvironment ? declaredPeers(resolved.manifest) : requirements,
+    runtimeVersion: facts.runtimeVersion,
+    needsEnvironment,
+  };
+}
+
+// 把 manifest 里所有 DSH peer 都列出来，不管当前满不满足。
+export function declaredPeers(manifest) {
+  const peers = manifest?.peerDependencies;
+  if (peers === null || typeof peers !== 'object' || Array.isArray(peers)) return {};
+  const declared = {};
+  for (const [name, range] of Object.entries(peers)) {
+    if (!/^@deepseek-ai\/dsh(?:[-/]|$)/.test(name) || typeof range !== 'string') continue;
+    declared[name] = range;
+  }
+  return declared;
+}