dsh-plugin-compat-check 0.0.0-stage → 0.1.0

package/index.js

@@ -0,0 +1,1584 @@
+// Host half of the dsh-plugin-compat-check plugin — loader self-introspection
+// (Plan.md §5 B1/B2/B3: read ctx.loader.entries(), recover failure reasons,
+// never throw).
+//
+// HARD RULE (Plan.md §4 第 6 条：绝不抛、绝不拖累宿主): this plugin must never
+// throw and must never keep the host from booting. A health-check plugin that
+// breaks host startup becomes an instance of the very class of problem it is
+// meant to detect. Every host object in here is touched behind try/catch, and
+// the one call that can hang (`fiber.await()`) is raced against a timeout.
+//
+// Why `inject` stays empty: `ctx.loader` is a Cordis service, and the context
+// proxy resolves it by walking the fiber chain — declaring it in `inject` is
+// not required to read it. Declaring a service we do not strictly need is the
+// exact way to park this plugin's own fiber in PENDING (Plan.md §6 地雷清单).
+// `resolveLoader()` below therefore tries the inject-free lookup first, and the
+// plugin additionally runs a one-shot child-fiber probe (`ctx.inject`) to
+// record, empirically, whether `inject: ["loader"]` *would* have been safe —
+// without risking its own activation.
+//
+// Output (the verifiable form required before any UI exists):
+//   ${DSC_OUT_DIR:-$TMPDIR/dsh-plugin-compat-check}/loader-introspect.json
+// plus structured console lines prefixed with [dsh-plugin-compat-check].
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import path, { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire as __createRequire } from 'node:module';
+
+export const name = 'dsh-plugin-compat-check';
+
+/**
+ * Deliberately empty: every service this plugin reads is read through
+ * `ctx.get(...)`, which returns `undefined` instead of throwing when a service
+ * is absent. See the header comment.
+ *
+ * Measured 2026-10-10 on DSH 0.2.0-rc.2: `inject: ["loader"]` ALSO activates
+ * (the fiber ends up ACTIVE with `loader` present), so this is the safe choice
+ * rather than the only workable one — declaring nothing keeps the health-check
+ * plugin independent of the very service it audits.
+ */
+export const inject = [];
+
+const SCHEMA_VERSION = 1;
+
+/** Cordis FiberState (const enum in the host, so mirrored here as data). */
+const FIBER_STATES = {
+  0: 'PENDING',
+  1: 'LOADING',
+  2: 'ACTIVE',
+  3: 'FAILED',
+  4: 'DISPOSED',
+  5: 'UNLOADING',
+};
+
+const OUT_DIR = process.env.DSC_OUT_DIR || join(tmpdir(), 'dsh-plugin-compat-check');
+const OUT_JSON = join(OUT_DIR, 'loader-introspect.json');
+
+/** Defensive cap: a pathological iterable must not exhaust the host's heap. */
+const MAX_ENTRIES = 20000;
+
+/** `fiber.await()` may never settle for a fiber stuck mid-load: always race it. */
+const AWAIT_TIMEOUT_MS = toPositiveInt(process.env.DSC_AWAIT_TIMEOUT_MS, 1500);
+/** Extra passes catch late transitions (entries import asynchronously). */
+const SCAN_DELAYS = parseDelays(process.env.DSC_SCAN_DELAYS, [4000, 9000]);
+
+function toPositiveInt(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) && n > 0 ? Math.trunc(n) : fallback;
+}
+
+function parseDelays(value, fallback) {
+  if (typeof value !== 'string' || value.trim() === '') return fallback;
+  const parsed = value
+    .split(',')
+    .map((part) => toPositiveInt(part.trim(), 0))
+    .filter((n) => n > 0);
+  return parsed.length > 0 ? parsed : fallback;
+}
+
+/** `createRequire` 的小包装：同步可用，不要用 await import（apply 不是 async）。 */
+function reqNode() {
+  return { createRequire: __createRequire };
+}
+
+function log(message) {
+  try {
+    console.log(`[dsh-plugin-compat-check] ${message}`);
+  } catch {
+    /* 打日志失败也绝不能影响宿主 */
+  }
+}
+
+/** Never let an unknown throw escape as itself. */
+function errText(error) {
+  try {
+    if (error === null || error === undefined) return String(error);
+    if (typeof error === 'string') return error;
+    if (error instanceof Error) {
+      const stack = typeof error.stack === 'string' ? error.stack : '';
+      return stack || `${error.name}: ${error.message}`;
+    }
+    const text = String(error);
+    return text === '[object Object]' ? safeJson(error) : text;
+  } catch {
+    return '<unprintable error>';
+  }
+}
+
+function safeJson(value) {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return '<unserializable>';
+  }
+}
+
+function describe(value) {
+  try {
+    if (value === undefined) return 'undefined';
+    if (value === null) return 'null';
+    return typeof value;
+  } catch {
+    return '<unreadable>';
+  }
+}
+
+function writeReport(report) {
+  try {
+    mkdirSync(OUT_DIR, { recursive: true });
+  } catch {
+    /* 目录已存在或不可写 */
+  }
+  let written = false;
+  try {
+    writeFileSync(OUT_JSON, `${JSON.stringify(report, null, 2)}\n`);
+    written = true;
+  } catch (error) {
+    log(`WARN could not write ${OUT_JSON}: ${errText(error)}`);
+  }
+  return written;
+}
+
+// ---------------------------------------------------------------------------
+// B1: loader access
+// ---------------------------------------------------------------------------
+
+/**
+ * Obtain the loader without declaring `inject: ["loader"]`.
+ *
+ * Cordis resolves service reads by walking the fiber chain, so
+ * `ctx.get("loader")` works from a plugin fiber; `ctx.loader` is the same
+ * lookup through the proxy trap. Both are tried and the route that worked is
+ * recorded, so the answer is evidence rather than assumption.
+ *
+ * The returned object is JSON-safe: the live loader instance is never included.
+ */
+function resolveLoader(ctx) {
+  const attempts = [];
+  let loader;
+  let via;
+
+  const looksLikeLoader = (value) => value !== undefined && value !== null && typeof value.entries === 'function';
+
+  try {
+    const value = ctx.get('loader');
+    attempts.push(`ctx.get('loader') -> ${describe(value)}`);
+    if (looksLikeLoader(value)) {
+      loader = value;
+      via = "ctx.get('loader')";
+    }
+  } catch (error) {
+    attempts.push(`ctx.get('loader') threw: ${errText(error)}`);
+  }
+
+  if (loader === undefined) {
+    try {
+      const value = ctx.get('loader', false);
+      attempts.push(`ctx.get('loader', false) -> ${describe(value)}`);
+      if (looksLikeLoader(value)) {
+        loader = value;
+        via = "ctx.get('loader', false)";
+      }
+    } catch (error) {
+      attempts.push(`ctx.get('loader', false) threw: ${errText(error)}`);
+    }
+  }
+
+  let direct;
+  let directError = null;
+  try {
+    direct = ctx.loader;
+    attempts.push(`ctx.loader -> ${describe(direct)}`);
+    if (loader === undefined && looksLikeLoader(direct)) {
+      loader = direct;
+      via = 'ctx.loader';
+    }
+  } catch (error) {
+    directError = errText(error);
+    attempts.push(`ctx.loader threw: ${errText(error)}`);
+  }
+
+  return {
+    loader,
+    via: via ?? null,
+    attempts,
+    directPropertyReadable: directError === null && looksLikeLoader(direct),
+    directSameInstance: loader !== undefined && direct === loader,
+  };
+}
+
+/** Drop the live loader instance so the access record stays JSON-safe. */
+function publicLoaderAccess(resolved) {
+  return {
+    via: resolved.via ?? null,
+    attempts: resolved.attempts ?? [],
+    directPropertyReadable: resolved.directPropertyReadable === true,
+    directSameInstance: resolved.directSameInstance === true,
+  };
+}
+
+/**
+ * One-shot, side-effect-free probe: would `inject: ["loader"]` have kept this
+ * plugin PENDING? `ctx.inject` spawns a *child* fiber, so a loader that cannot
+ * be resolved leaves that child PENDING while this plugin stays ACTIVE — the
+ * exact question, answered without risking our own activation.
+ *
+ * Returns a disposer for the child fiber (or null).
+ */
+function startInjectProbe(ctx, record) {
+  const startedAt = Date.now();
+  record.startedAt = new Date(startedAt).toISOString();
+  try {
+    if (typeof ctx.inject !== 'function') {
+      record.outcome = 'ctx.inject is not a function';
+      return null;
+    }
+    record.registered = true;
+    const dispose = ctx.inject(['loader'], (scoped) => {
+      try {
+        record.outcome = 'fired (child fiber activated)';
+        record.firedAfterMs = Date.now() - startedAt;
+        const value = scoped?.loader ?? scoped?.get?.('loader');
+        record.scopedLoader = describe(value);
+        record.scopedLoaderHasEntries = typeof value?.entries === 'function';
+      } catch (error) {
+        record.outcome = `callback threw: ${errText(error)}`;
+      }
+    });
+    return typeof dispose === 'function' ? dispose : null;
+  } catch (error) {
+    record.outcome = `ctx.inject threw: ${errText(error)}`;
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// B2: failure reasons
+// ---------------------------------------------------------------------------
+
+/**
+ * `await fiber.await()` without ever being able to hang the host.
+ *
+ * Resolves to `{ ok, reason, timedOut }`. The underlying promise gets a
+ * rejection handler attached immediately so a late rejection after the timeout
+ * cannot surface as an unhandled rejection (which Node would turn into a fatal
+ * error — the opposite of "绝不抛").
+ */
+async function awaitFiber(fiber, timeoutMs) {
+  let promise;
+  try {
+    promise = fiber.await();
+  } catch (error) {
+    return { ok: false, reason: errText(error), timedOut: false };
+  }
+  if (promise === undefined || promise === null || typeof promise.then !== 'function') {
+    return { ok: true, reason: null, timedOut: false };
+  }
+
+  const settled = Promise.resolve(promise).then(
+    () => ({ ok: true, reason: null, timedOut: false }),
+    (error) => ({ ok: false, reason: errText(error), timedOut: false }),
+  );
+
+  let timer;
+  try {
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(() => resolve({ ok: false, reason: null, timedOut: true }), timeoutMs);
+      if (timer && typeof timer.unref === 'function') timer.unref();
+    });
+    return await Promise.race([settled, timeout]);
+  } catch (error) {
+    return { ok: false, reason: errText(error), timedOut: false };
+  } finally {
+    try {
+      clearTimeout(timer);
+    } catch {
+      /* 忽略 */
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// B1/B2: per-entry introspection
+// ---------------------------------------------------------------------------
+
+function declaredInjectKeys(fiber) {
+  try {
+    const inject = fiber?.inject;
+    if (inject === undefined || inject === null) return [];
+    if (Array.isArray(inject)) return inject.map(String);
+    if (typeof inject === 'object') return Object.keys(inject);
+    if (inject instanceof Set) return [...inject].map(String);
+    return [];
+  } catch (error) {
+    return [`<unreadable inject: ${errText(error)}>`];
+  }
+}
+
+/** 缺服务 = fiber.ctx.get(key) === undefined (Plan.md §5 B1). */
+function missingServices(fiber, keys) {
+  const missing = [];
+  const present = [];
+  const unreadable = [];
+  for (const key of keys) {
+    try {
+      const value = fiber.ctx.get(key);
+      if (value === undefined) missing.push(key);
+      else present.push(key);
+    } catch (error) {
+      unreadable.push({ key, error: errText(error) });
+    }
+  }
+  return { missing, present, unreadable };
+}
+
+function optionsOf(entry) {
+  try {
+    const options = entry?.options;
+    return options !== undefined && options !== null && typeof options === 'object' ? options : {};
+  } catch (error) {
+    return { __unreadable: errText(error) };
+  }
+}
+
+async function introspectEntry(entry) {
+  const options = optionsOf(entry);
+  const row = {
+    id: options.id,
+    name: options.name,
+    group: options.group === true,
+    disabled: null,
+    disabledError: null,
+    fiberState: 'NO_FIBER',
+    fiberStateCode: null,
+    declaredInject: [],
+    declaredInjectCount: 0,
+    missingServices: [],
+    presentServices: [],
+    unreadableServices: [],
+    failureReason: null,
+    awaitTimedOut: false,
+    notes: [],
+  };
+
+  try {
+    row.id = entry?.id;
+  } catch (error) {
+    row.notes.push(`entry.id unreadable: ${errText(error)}`);
+  }
+  if (row.id === undefined) row.id = options.id;
+
+  // `entry.disabled` can throw for a `!!js` expression (the host wraps it too).
+  try {
+    row.disabled = Boolean(entry.disabled);
+  } catch (error) {
+    row.disabledError = errText(error);
+    row.notes.push('disabled expression threw');
+  }
+
+  let fiber;
+  try {
+    fiber = entry?.fiber;
+  } catch (error) {
+    row.notes.push(`entry.fiber unreadable: ${errText(error)}`);
+  }
+
+  if (fiber === undefined || fiber === null) {
+    row.fiberState = 'NO_FIBER';
+    row.notes.push('no fiber (loader did not import this entry)');
+    if (row.group) row.notes.push('options.group is true');
+    return row;
+  }
+
+  try {
+    const code = fiber.state;
+    row.fiberStateCode = typeof code === 'number' ? code : null;
+    row.fiberState = FIBER_STATES[code] ?? `UNKNOWN(${String(code)})`;
+  } catch (error) {
+    row.fiberState = 'UNREADABLE';
+    row.notes.push(`fiber.state threw: ${errText(error)}`);
+  }
+
+  try {
+    row.declaredInject = declaredInjectKeys(fiber);
+    row.declaredInjectCount = row.declaredInject.length;
+    const { missing, present, unreadable } = missingServices(fiber, row.declaredInject);
+    row.missingServices = missing;
+    row.presentServices = present;
+    row.unreadableServices = unreadable;
+  } catch (error) {
+    row.notes.push(`inject/missing-service scan threw: ${errText(error)}`);
+  }
+
+  // Only a fiber that is not ACTIVE can carry an unobserved rejection.
+  if (row.fiberState !== 'ACTIVE' && row.fiberState !== 'DISPOSED') {
+    const awaited = await awaitFiber(fiber, AWAIT_TIMEOUT_MS);
+    if (awaited.timedOut) {
+      row.awaitTimedOut = true;
+      row.notes.push(`fiber.await() exceeded ${AWAIT_TIMEOUT_MS}ms`);
+    } else if (!awaited.ok) {
+      row.failureReason = awaited.reason;
+    } else if (row.fiberState === 'PENDING') {
+      row.notes.push('fiber.await() resolved without error (PENDING: waiting for services)');
+    }
+  }
+
+  if (row.disabled === true) row.notes.push('entry is disabled');
+  return row;
+}
+
+/**
+ * `loader.entries()` is an iterable, not necessarily an array (measured: a
+ * plain `object` whose iterator yields the entries). Accept everything that can
+ * be walked, never assume a shape, and never walk an unbounded sequence — a
+ * pathological iterator must not be able to exhaust the host's heap.
+ *
+ * @returns {{entries: any[]|null, truncated: boolean, error: string|null}}
+ */
+function toEntryArray(value) {
+  const fail = (error) => ({ entries: null, truncated: false, error });
+  if (value === null || value === undefined) return fail(`entries() returned ${describe(value)}`);
+  if (Array.isArray(value)) return { entries: value, truncated: false, error: null };
+
+  let iterable = false;
+  try {
+    iterable = typeof value[Symbol.iterator] === 'function';
+  } catch (error) {
+    return fail(`probing Symbol.iterator threw: ${errText(error)}`);
+  }
+  if (iterable) {
+    const out = [];
+    try {
+      for (const item of value) {
+        out.push(item);
+        if (out.length >= MAX_ENTRIES) return { entries: out, truncated: true, error: null };
+      }
+      return { entries: out, truncated: false, error: null };
+    } catch (error) {
+      return { entries: out, truncated: false, error: `iterating entries threw: ${errText(error)}` };
+    }
+  }
+
+  try {
+    if (typeof value.length === 'number') {
+      const length = Math.min(value.length, MAX_ENTRIES);
+      return { entries: Array.prototype.slice.call(value, 0, length), truncated: value.length > length, error: null };
+    }
+  } catch (error) {
+    return fail(`reading array-like entries threw: ${errText(error)}`);
+  }
+  return fail(`entries() returned a non-iterable ${describe(value)}`);
+}
+
+async function scan(ctx, state, pass) {
+  const report = {
+    schemaVersion: SCHEMA_VERSION,
+    plugin: name,
+    pid: process.pid,
+    node: process.version,
+    platform: process.platform,
+    scannedAt: new Date().toISOString(),
+    pass,
+    passCount: SCAN_DELAYS.length,
+    applyAt: state.applyAt,
+    loaderAccess: state.loaderAccess,
+    outPath: OUT_JSON,
+    awaitTimeoutMs: AWAIT_TIMEOUT_MS,
+    entryCount: 0,
+    stateHistogram: {},
+    problems: [],
+    entries: [],
+    errors: [],
+  };
+
+  let loader = state.loader;
+  let via = state.loaderVia;
+  if (loader === undefined) {
+    const resolved = resolveLoader(ctx);
+    loader = resolved.loader;
+    via = resolved.via;
+    state.loader = loader;
+    state.loaderVia = via;
+    report.loaderAccess = { ...state.loaderAccess, ...publicLoaderAccess(resolved) };
+  }
+
+  if (loader === undefined) {
+    report.errors.push('loader service not reachable from this plugin context');
+    log(`ERROR loader not reachable (${JSON.stringify(state.loaderAccess.attempts ?? [])})`);
+    writeReport(report);
+    return report;
+  }
+
+  let entries;
+  let rawEntries;
+  try {
+    rawEntries = loader.entries();
+    const walked = toEntryArray(rawEntries);
+    report.entriesSource = {
+      typeof: describe(rawEntries),
+      isArray: Array.isArray(rawEntries),
+      constructorName: safeJson(rawEntries?.constructor?.name ?? null),
+      iterable: typeof rawEntries?.[Symbol.iterator] === 'function',
+      truncated: walked.truncated,
+    };
+    entries = walked.entries;
+    if (walked.error !== null) report.errors.push(`loader.entries(): ${walked.error}`);
+  } catch (error) {
+    report.errors.push(`loader.entries() threw: ${errText(error)}`);
+    log(`ERROR scan#${pass}: loader.entries() threw: ${errText(error)}`);
+    writeReport(report);
+    return report;
+  }
+  if (entries === null) {
+    const detail = report.errors.length > 0 ? report.errors.join('; ') : 'unknown reason';
+    log(`ERROR scan#${pass}: could not read entries (${detail})`);
+    writeReport(report);
+    return report;
+  }
+
+  report.entryCount = entries.length;
+  for (const entry of entries) {
+    let row;
+    try {
+      row = await introspectEntry(entry);
+    } catch (error) {
+      row = {
+        id: '<unreadable entry>',
+        fiberState: 'UNREADABLE',
+        notes: [`entry introspection threw: ${errText(error)}`],
+      };
+      report.errors.push(`entry introspection threw: ${errText(error)}`);
+    }
+    report.entries.push(row);
+    report.stateHistogram[row.fiberState] = (report.stateHistogram[row.fiberState] ?? 0) + 1;
+  }
+
+  report.problems = report.entries.filter((row) => {
+    if (row.disabled === true) return false;
+    if (row.fiberState === 'ACTIVE') return false;
+    return true;
+  });
+
+  const written = writeReport(report);
+  log(
+    `scan#${pass}/${SCAN_DELAYS.length} loader-via=${via} entries=${report.entryCount} states=${safeJson(report.stateHistogram)} problems=${report.problems.length} report=${OUT_JSON}${written ? '' : ' (WRITE FAILED)'}`,
+  );
+  for (const row of report.problems) {
+    log(
+      `  PROBLEM id=${safeJson(row.id)} name=${safeJson(row.name)} state=${row.fiberState}` +
+        ` missing=[${row.missingServices.join(', ')}]` +
+        (row.failureReason ? ` reason=${firstLine(row.failureReason)}` : '') +
+        (row.awaitTimedOut ? ' (await timed out)' : ''),
+    );
+  }
+  return report;
+}
+
+function firstLine(text) {
+  try {
+    const line = String(text).split('\n')[0];
+    return line.length > 300 ? `${line.slice(0, 300)}…` : line;
+  } catch {
+    return '<unprintable>';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// apply
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// C2: 面板数据通道（宿主半边算结论，客户端半边渲染）
+// ---------------------------------------------------------------------------
+
+/**
+ * 内核的位置。插件半边**不自己实现判定** —— 它 import 内核。
+ *
+ * 四条候选路径，按可靠性排序：
+ *   1. 环境变量 `DSC_KERNEL`（打包/发布形态下由外层指定）
+ *   2. **本包自己就是自足包**（`here` 下有 `lib/` 与 `rules/`）—— npm 发布形态
+ *   3. 本包在仓库里的位置（`plugin/` 的上一级）—— 开发与 GitHub 分发时的形态
+ *
+ * ## ⚠️ 为什么 `here` 必须排在 `here/..` 前面
+ *
+ * 这两种形态在**文件系统上长得一样但含义相反**：
+ *
+ * | 形态 | `here` | 内核在 |
+ * |---|---|---|
+ * | 仓库检出 | `<repo>/plugin` | `here/..` = `<repo>` |
+ * | npm 装好的包 | `<...>/node_modules/dsh-plugin-compat-check` | **`here/kernel`** |
+ *
+ * 在 npm 形态下，`here/..` 是 `node_modules/` —— 那里当然没有 `lib/extract.mjs`，
+ * 于是**内核永远找不到，插件静默变成一个只会说"找不到判定内核"的壳**。
+ * 而 `here` 先试的代价是零（仓库形态下 `plugin/lib/` 不存在，直接落到下一条）。
+ *
+ * 找不到就返回 null，**由调用方决定怎么说**，这里不抛。
+ */
+function resolveKernelDir() {
+  const { dirname: dir } = path;
+  const here = dir(fileURLToPath(import.meta.url));
+  const candidates = [
+    process.env.DSC_KERNEL,
+    path.join(here, 'kernel'), // npm 自足包形态（`npm pack` 时由 prepack 暂存到此）
+    here, // 另一种自足布局：内核与 index.js 同级
+    path.resolve(here, '..'), // 仓库形态：plugin/ → 仓库根
+  ].filter(Boolean);
+  for (const c of candidates) {
+    try {
+      if (existsSync(path.join(c, 'lib', 'extract.mjs')) && existsSync(path.join(c, 'lib', 'verdict.mjs'))) {
+        return c;
+      }
+    } catch { /* 下一个候选 */ }
+  }
+  return null;
+}
+
+/**
+ * 当前 profile 的 node_modules。
+ *
+ * 优先级：显式覆盖 → DSH 正在跑的 profile → `desktop`。
+ * 「正在跑的是哪个 profile」没有正式服务暴露，只能靠环境变量与目录推断 ——
+ * 所以这里把推断的**依据**一起放进报告，让结论可追溯，而不是猜一个就不吭声。
+ */
+/**
+ * 当前 DSH 的版本。
+ *
+ * ## 为什么必须拿到它
+ *
+ * `dshVersion` 是基线的三个字段之一（Plan.md §5 F1），也是「**声明与实测不符**」
+ * 这类结论的**前提** —— 没有它就没法把插件的 `dsh.compatibility` 声明与实际版本对上，
+ * 于是那一类发现（本工具相对既有方案唯一不可替代的结论）在插件形态下根本不成立。
+ *
+ * ## 实测过的四条路（按可靠性排序）
+ *
+ * 在真实桌面端里把宿主进程打出来（`--profile vprobe`，VERPROBE 那一次）：
+ *
+ *   process.env.DSH_VERSION          → null          （不存在）
+ *   process.versions.electron        → "44.0.0"      （说明宿主跑在 Electron 里）
+ *   argv 里指向 `…/dsh/node_modules/…` 的路径，从中反推 dsh 根
+ *   createRequire(dshRoot).resolve('@deepseek-ai/dsh-desktop-host/package.json')
+ *     → @deepseek-ai/dsh-desktop-host@0.2.0-rc.2     ✅ 与 `dsh --version` 一致
+ *   createRequire(dshRoot).resolve('@deepseek-ai/dsh/package.json')
+ *     → @deepseek-ai/dsh@0.2.0-rc.2                  ✅ 两个都行
+ *
+ * ### 被否掉的方案，以及为什么
+ *
+ * - **`process.env.DSH_VERSION`**：不存在（就是这次要解决的缺口本身）。
+ * - **`dsh --version` 起子进程**：不行，而且**不是**能力问题 —— Plan.md §2 第 1 题锁定了
+ *   「插件严格只读：不装包、不起子进程、不联网」。为拿一个版本号破这条边界不值。
+ * - **`Info.plist`**：macOS 专有（`CFBundleShortVersionString` = 0.2.0-rc.2，能读到）。
+ *   本产品要跨平台（§2 第 6 题），不能把它当主路。
+ *
+ * ## 拿不到时返回 null，而不是猜
+ *
+ * `dshVersion: null` 会让「声明与实测不符」这类结论自动不成立（判定层已经这样处理）。
+ * 猜一个版本字符进去，会**凭空造出**声明不符的结论 —— 那比缺一条结论糟得多。
+ */
+function resolveDshVersion() {
+  // ① 显式覆盖（CLI 形态与测试用）
+  if (process.env.DSH_VERSION) return process.env.DSH_VERSION;
+
+  // ② 从 argv 反推 dsh 根，再用 Node 自己的解析器问它
+  //
+  //    真实桌面端的 argv（实测）：
+  //      [ …/MacOS/DeepSeek Harness, --expose-internals,
+  //        …/app.asar/dsh/node_modules/@deepseek-ai/dsh-desktop-host/lib/index.js,
+  //        …/app.asar/dsh,                                            ← dsh 根
+  //        /Users/…/.dsh/profiles/vprobe, … ]
+  //
+  //    注意 **不写死 macOS 路径**：任何 `<…>/dsh/node_modules/<…>` 都能反推出根，
+  //    Windows 的 `\dsh\node_modules\` 形态也一并处理。
+  try {
+    const argv = (process.argv || []).map(String);
+    const sep = argv.find((a) => /[\\/]dsh[\\/]node_modules[\\/]/.test(a));
+    if (sep) {
+      const m = /^(.*[\\/]dsh)[\\/]node_modules[\\/]/.exec(sep);
+      if (m && m[1]) {
+        const dshRoot = m[1];
+        const req = __createRequire(join(dshRoot, 'probe.js'));
+        // 两个包实测都能解析；都试一遍是为了不依赖某一个包的存在
+        for (const spec of ['@deepseek-ai/dsh-desktop-host/package.json', '@deepseek-ai/dsh/package.json']) {
+          try {
+            const meta = req(req.resolve(spec));
+            if (meta && typeof meta.version === 'string' && meta.version) {
+              return meta.version;
+            }
+          } catch { /* 试下一个 */ }
+        }
+      }
+    }
+  } catch { /* 继续 */ }
+
+  // ③ 都没有 → **null，不猜**（判定层会据此不产出声明不符的结论）
+  return null;
+}
+
+/**
+ * 当前正在跑的是哪个 profile。
+ *
+ * ## 为什么这里必须小心：环境变量会**主动骗人**
+ *
+ * 实测（在 `--profile gverify` 下启动宿主，让插件把进程环境打出来）：
+ *
+ * ```
+ * DSH_PROFILE=desktop          ← 过期值！
+ * DSH_PROFILE_DIR=…/profiles/desktop
+ * process.argv = [ …/dsh-desktop-host/lib/cli.js, "--profile", "gverify" ]
+ * ```
+ *
+ * 那两个 `DSH_PROFILE*` 是从**启动这个 app 的那个 shell** 继承来的，与实际加载的
+ * profile 无关。信它们会把 gverify 的结论写进 `baseline.desktop.json`，
+ * 于是差分会报出"移除了 17 个插件"这种**完全是编出来的变化**。
+ *
+ * 所以顺序是：argv（宿主自己声明的）> 显式覆盖 > 环境变量（可能是陈的）> 回退。
+ */
+function resolveActiveProfile() {
+  // ① 宿主自己的启动参数 —— 最权威。**两种形态都要认**：
+  //
+  //    CLI：     … dsh-desktop-host/lib/cli.js --profile gverify
+  //    桌面 app：… dsh-desktop-host/lib/index.js <dsh 根> /Users/…/profiles/desktop <runtime> …
+  //
+  //    桌面端把 **profile 目录路径按位置传**，没有 `--profile` 标志。
+  //    只认 `--profile` 时，真实 app 里会走"回退到 desktop" —— 幸亏这次的结论恰好
+  //    就是 desktop，否则会把别的 profile 的结论写进 desktop 的基线。**那次是运气，不是正确。**
+  try {
+    const argv = (process.argv || []).map(String);
+    for (let i = argv.length - 1; i >= 0; i--) {
+      const inline = /^--profile=(.+)$/.exec(argv[i]);
+      if (inline) return { name: inline[1], why: `process.argv 的 --profile=${inline[1]}` };
+      if (argv[i] === '--profile' && argv[i + 1] && !argv[i + 1].startsWith('-')) {
+        return { name: argv[i + 1], why: `process.argv 的 --profile ${argv[i + 1]}` };
+      }
+    }
+    // 位置形态：任何指向 `<…>/profiles/<名字>`（或它下面的 node_modules）的绝对路径
+    for (const a of argv) {
+      if (!a.startsWith('/')) continue;
+      const m = /\/profiles\/([^/]+)(?:\/|$)/.exec(a);
+      if (m && m[1]) return { name: m[1], why: `process.argv 里的 profile 路径 ${a}` };
+    }
+  } catch { /* 继续 */ }
+  // ② 显式覆盖（工具/测试用）
+  if (process.env.DSC_PROFILE) return { name: process.env.DSC_PROFILE, why: `DSC_PROFILE=${process.env.DSC_PROFILE}` };
+  // ③ 环境变量 —— **可能是陈的**，所以带上警示写进 why
+  for (const key of ['DSH_PROFILE', 'DSH_ACTIVE_PROFILE', 'DSH_PROFILE_NAME']) {
+    const v = process.env[key];
+    if (v) return { name: v, why: `${key}=${v}（环境变量可能来自启动 app 的那个 shell，未必是当前加载的 profile）` };
+  }
+  return { name: null, why: '无法判断' };
+}
+
+function resolveNodeModules() {
+  const dshHome = process.env.DSH_HOME || join(homedir(), '.dsh');
+  const candidates = [];
+
+  const inferred = resolveActiveProfile();
+  if (inferred.name) {
+    candidates.push({ dir: join(dshHome, 'profiles', inferred.name, 'node_modules'), why: inferred.why });
+  }
+
+  // 兜底：从 `DSH_PROFILE_DIR` 直接拿目录（它指向 profile 根，不是 node_modules）
+  if (process.env.DSH_PROFILE_DIR) {
+    candidates.push({ dir: join(process.env.DSH_PROFILE_DIR, 'node_modules'), why: `DSH_PROFILE_DIR=${process.env.DSH_PROFILE_DIR}` });
+  }
+  // 最后回退。到这一步说明前面都没中（例如插件是从仓库直接跑的、或发布形态装在别处），
+  // 那就只能挑一个 —— 但 why 里会**写明这是回退**，否则用户会以为它检查的是当前 profile。
+  candidates.push({ dir: join(dshHome, 'profiles', 'desktop', 'node_modules'), why: '回退到 desktop profile（没能判断出正在跑哪一个）' });
+
+  for (const c of candidates) {
+    try {
+      if (existsSync(c.dir)) return { dir: c.dir, why: c.why };
+    } catch { /* 下一个 */ }
+  }
+  return { dir: null, why: '没有任何候选目录存在' };
+}
+
+/**
+ * 把结论交给面板 —— **F2 的缓存策略集中在这里**。
+ *
+ * ## 策略：stale-while-revalidate（先给旧的，后台再刷）
+ *
+ * 为什么不是"到点就重算"：一次体检 0.5–1.5 秒（desktop profile 21 个插件）。
+ * 让面板的请求**等**这 1.5 秒，用户看到的是转圈；而结论晚 1.5 秒到完全无所谓 ——
+ * 这份数据说的是"你装的插件跟这版 DSH 兼不兼容"，它不是秒级指标。
+ * 所以：有缓存就先给，同时在后台刷新的。**响应速度与正确性都不牺牲**。
+ *
+ * 三种情况：
+ *   - `?refresh=1` 或没有缓存 → **同步算**（用户明确要新的，或者根本没有旧的）
+ *   - 缓存在有效期内         → 直接给
+ *   - 缓存过期               → 先给旧的，并触发一次后台刷新（同一时刻只跑一个）
+ *
+ * 并发安全：`state.computing` 保存"正在跑的那一个 promise"，所以十个面板请求
+ * 同时到达也只会算一次 —— 否则它们会各自算一遍，白烧 1.5 秒 × 10。
+ */
+async function serveReport(state, ctx, force) {
+  const now = Date.now();
+  const age = now - state.lastReportAt;
+
+  if (force || !state.lastReport) {
+    // 没有缓存时不并发去重：第一次访问就该拿到真结果。
+    const out = await computeReport(state, ctx);
+    state.lastReport = out;
+    state.lastReportAt = Date.now();
+    return out;
+  }
+  if (age <= state.cacheTtlMs) {
+    return { ...state.lastReport, cache: { hit: true, ageMs: age, refreshing: false } };
+  }
+  // 过期：**不等它**。给旧的，后台刷。
+  if (!state.computing) {
+    state.computing = computeReport(state, ctx)
+      .then((out) => {
+        state.lastReport = out;
+        state.lastReportAt = Date.now();
+        return out;
+      })
+      .catch((error) => {
+        // 后台刷新失败**不能影响已经发出去的那份**，但必须留下痕迹：
+        // 静默失败的刷新会让面板一直显示过期数据，而用户以为那是当前的。
+        try { log(`WARN F2 background refresh failed: ${errText(error)}`); } catch { /* 忽略 */ }
+        state.lastRefreshError = errText(error);
+        return null;
+      })
+      .finally(() => { state.computing = null; });
+  }
+  return { ...state.lastReport, cache: { hit: true, ageMs: age, refreshing: true } };
+}
+
+/**
+ * 基线文件的位置。**必须与 CLI 的 `bin/compat-check.mjs` 推导出同一个路径** ——
+ * 两份基线会立刻分叉，而用户在面板和命令行看到的"变化"就会是两件事。
+ * 按 profile 分文件：不同 profile 的插件集合不同，混在一起会让差分变成噪音。
+ */
+function baselineFileFor(nmDir) {
+  const dshHome = process.env.DSH_HOME || join(homedir(), '.dsh');
+  let key = 'unknown';
+  try {
+    const parts = String(nmDir).split(path.sep);
+    const i = parts.lastIndexOf('profiles');
+    if (i >= 0 && parts[i + 1]) key = parts[i + 1];
+  } catch { /* 保持 unknown */ }
+  return join(dshHome, 'dsh-plugin-compat-check', `baseline.${key.replace(/[^\w.-]/g, '_')}.json`);
+}
+
+/**
+ * 跑一次体检。**同步、纯计算、不抛**。
+ *
+ * 为什么宿主半边要算而不是把原始数据丢给客户端：
+ *   - 客户端跑在浏览器里，读不了文件系统；
+ *   - 结论（五元组 + 确定性）是内核的产物，算出唯一一份才不会两边漂移。
+ */
+async function computeReport(state, ctx) {
+  const started = Date.now();
+  const out = {
+    schemaVersion: 1,
+    kind: 'plugin-compat-check/report',
+    computedAt: new Date().toISOString(),
+    ok: false,
+    error: null,
+    kernelDir: null,
+    // 「这份结论是哪一版工具给的」。面板是本插件的主要入口，
+    // 少了它，用户来问"凭什么"时第一句就卡住 —— 而同一插件在不同版本的
+    // 规则表/提取器下结论会变（见 lib/version.mjs 与 Plan.md §5.2.8）。
+    toolVersion: null,
+    nodeModules: null,
+    nodeModulesWhy: null,
+    // C4：与上次体检的差分包（没有基线时为 null，并带 note 说明为什么）
+    baseline: null,
+    report: null,
+  };
+  try {
+    const kernel = resolveKernelDir();
+    out.kernelDir = kernel;
+    // 版本要**尽早**拿到：连"找不到内核"这条错误路径上，用户也需要知道
+    // 是哪一版工具报的这个错。`version.mjs` 只在有内核时才读得到 ——
+    // 读不到就保持 null，**不猜**。
+    if (kernel) {
+      try {
+        const vmod = await import(pathToFileURL(join(kernel, 'lib', 'version.mjs')).href);
+        out.toolVersion = vmod.TOOL_VERSION ?? null;
+      } catch (error) {
+        log(`版本读不到（${errText(error)}）—— 报告里的 toolVersion 将是 null`);
+      }
+    }
+    if (!kernel) {
+      out.error = '找不到判定内核（lib/extract.mjs + lib/verdict.mjs）。'
+        + '插件形态下它们是同仓库的相邻目录；发布形态请设 DSC_KERNEL。';
+      return out;
+    }
+    const nm = resolveNodeModules();
+    out.nodeModules = nm.dir;
+    out.nodeModulesWhy = nm.why;
+    if (!nm.dir) {
+      out.error = `找不到要体检的 node_modules：${nm.why}`;
+      return out;
+    }
+
+    const { extractWithProvenance } = await import(pathToFileURL(join(kernel, 'lib', 'extract.mjs')).href);
+    const { buildVerdicts } = await import(pathToFileURL(join(kernel, 'lib', 'verdict.mjs')).href);
+
+    const catalogPath = join(kernel, 'rules', 'dsh-api-catalog.json');
+    const rulesPath = join(kernel, 'rules', 'severity.json');
+    const catalog = JSON.parse(readFileSync(catalogPath, 'utf8'));
+    const rules = JSON.parse(readFileSync(rulesPath, 'utf8'));
+
+    // 运行时面：宿主半边**自己就在进程里**，所以它能拿到比探针更准的东西。
+    // 第一版先读探针报告（如果外层给了路径），没有就退回目录 —— 并如实标注。
+    let hostSurface = null;
+    let surfaceWhy = '没有运行时面：结论中的方法级判定降为「疑似」';
+    const probePath = process.env.DSC_PROBE_REPORT;
+    if (probePath && existsSync(probePath)) {
+      try {
+        hostSurface = JSON.parse(readFileSync(probePath, 'utf8'));
+        surfaceWhy = `运行时面来自探针报告 ${probePath}`;
+      } catch (error) {
+        surfaceWhy = `探针报告读不动（${errText(error)}），退回目录`;
+      }
+    }
+    out.surfaceWhy = surfaceWhy;
+
+    const extracted = extractWithProvenance(nm.dir, { catalog });
+    const verdict = buildVerdicts({
+      report: extracted.report,
+      hostSurface,
+      rules,
+      catalog,
+      dshVersion: resolveDshVersion(),
+    });
+
+    // ── C4：基线差分 ──
+    // 用**与 CLI 完全相同**的 lib/baseline.mjs。面板说"变差了"而命令行说"没变"
+    // 这种分叉在结构上就不可能发生。
+    let baseline = null;
+    try {
+      const { snapshotForBaseline, diffAgainstBaseline, badgeFor } =
+        await import(pathToFileURL(join(kernel, 'lib', 'baseline.mjs')).href);
+      const snap = snapshotForBaseline(verdict, resolveDshVersion());
+      const bfile = baselineFileFor(nm.dir);
+      let prev = null;
+      let readNote = null;
+      try {
+        if (existsSync(bfile)) prev = JSON.parse(readFileSync(bfile, 'utf8'));
+        else readNote = '还没有基线（这是第一次体检）';
+      } catch (error) {
+        // 读不出来**不是**"没有变化"。必须区分"你没跑过"与"你的基线坏了" ——
+        // 后者会让用户以为一切照旧，继续用着已经变坏的环境。
+        readNote = `基线读不出来（${errText(error)}）—— 这次不做比较`;
+      }
+      const diff = diffAgainstBaseline(prev, snap);
+      baseline = { file: bfile, note: readNote, diff, badge: badgeFor(diff), wrote: false };
+      // 只有这一次真的算出了结论才写基线：一次失败的体检写下的基线，
+      // 会把"读不到"记成"这些插件都没了"，下次比较全是假变化。
+      try {
+        mkdirSync(path.dirname(bfile), { recursive: true });
+        writeFileSync(bfile, `${JSON.stringify(snap, null, 2)}\n`);
+        baseline.wrote = true;
+      } catch (error) {
+        baseline.writeError = `基线写不进去（${errText(error)}）`;
+      }
+    } catch (error) {
+      baseline = { error: errText(error), note: '基线差分没算成（不影响本次结论）' };
+    }
+
+    // 只把面板要用的部分送过去：完整 report 在 desktop profile 上是 ~1 MB，
+    // 而面板要的只是每个插件的结论与去处。
+    // ── 面板条目台账：id → 包名 ──
+    // `plugins.detail.*` 只收到 `{subject:{kind,id}}`，**没有包名**，而 id 常常
+    // 不等于包名（插件面板自己那个条目的 id 就叫 `plugins`）。所以从面板管理器
+    // 自己的只读服务里取这张表，让客户端能解析出"这是哪个插件"。
+    // 取不到不算失败：客户端会退回到"id 就是包名"的判断，并如实不渲染角标。
+    try {
+      const pm = typeof ctx.get === 'function' ? ctx.get('pluginManager', false) : undefined;
+      const listing = pm && typeof pm.list === 'function' ? await pm.list() : null;
+      if (listing) {
+        const arr = Array.isArray(listing) ? listing : (listing.items || listing.plugins || []);
+        out.items = arr
+          .map((it) => {
+            if (!it || typeof it !== 'object') return null;
+            const id = it.id ?? it.entryId ?? it.slotId ?? null;
+            const pkg = it.packageName ?? it.package ?? it.name ?? null;
+            return (id && pkg) ? { id, packageName: String(pkg), label: it.label ?? null } : null;
+          })
+          .filter(Boolean);
+      }
+    } catch (error) {
+      out.itemsError = errText(error);
+    }
+
+    out.baseline = baseline;
+    out.dshVersion = resolveDshVersion();
+    out.report = {
+      summary: verdict.summary,
+      dshVersion: verdict.dshVersion,
+      hasRuntimeSurface: Boolean(hostSurface),
+      surfaceWhy,
+      plugins: verdict.plugins,
+      // 逐条发现的证据形态：面板要能回答「凭什么这么判」
+      // 条目台账（id → 包名），客户端解析角标归属时用
+      items: out.items || [],
+      itemsError: out.itemsError || null,
+      manifests: extracted.report.manifests,
+      serviceCount: extracted.report.services.length,
+      siteTotal: (extracted.report.callSites || []).length,
+    };
+    out.ok = true;
+    out.elapsedMs = Date.now() - started;
+  } catch (error) {
+    out.error = errText(error);
+  }
+  return out;
+}
+
+/** 本地信任栅栏：只有本机的 DSH 界面该读到这份数据。 */
+function isTrustedRequest(req) {
+  try {
+    const host = String((req.headers && (req.headers.host || req.headers.Host)) || '');
+    const origin = String((req.headers && (req.headers.origin || req.headers.Origin)) || '');
+    const hostOk = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i.test(host);
+    if (!origin) return hostOk;
+    return hostOk && /^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i.test(origin);
+  } catch {
+    return false;
+  }
+}
+
+
+// ---------------------------------------------------------------------------
+// D1: 对话工具 —— 让 agent 能直接答「我这插件兼容吗」
+// ---------------------------------------------------------------------------
+
+/**
+ * 把结论渲染成一段**给模型读**的文本。
+ *
+ * 与 CLI 的 `lib/report.mjs` 是同一口径：本函数只负责把已经算好的结论翻译成
+ * 文本，不做任何判定。这样"面板说可用、工具说部分可用"在结构上不可能发生。
+ *
+ * 为什么工具**必须**能给出结论而不是只丢一个文件名：
+ * 用户问的是"兼不兼容"，一个"报告写好了，你自己去看"的回答等于没答。
+ */
+function renderForModel(compat) {
+  try {
+    if (!compat || compat.ok !== true) {
+      return `体检没跑成（这是工具的问题，不是插件的结论）：${(compat && compat.error) || '未知原因'}`;
+    }
+    const r = compat.report;
+    const L = [];
+    const s = r.summary || {};
+    L.push(`结论：可用 ${s.ok || 0}　部分可用 ${s.partial || 0}　不兼容 ${s.broken || 0}`
+      + (s.vacuousOk ? `（其中 ${s.vacuousOk} 个「可用」是空洞的：该插件没有用过任何 DSH 服务，因此没有可检查的东西）` : ''));
+    L.push(`体检对象：${compat.nodeModules}（${compat.nodeModulesWhy}）`);
+    L.push(r.hasRuntimeSurface
+      ? '方法级判定依据：宿主运行时面 —— 这类结论是确定的。'
+      : '方法级判定依据：官方 API 目录（**契约目录，不是运行时面**）—— 因此方法级结论一律标「疑似」。'
+        + '「疑似」不是缺陷，是诚实：判不准时降级标注，而不是升格成确定。');
+    L.push('');
+
+    const rank = { broken: 0, partial: 1, unknown: 2, ok: 3 };
+    const names = Object.keys(r.plugins).sort((a, b) =>
+      (rank[r.plugins[a].verdict] - rank[r.plugins[b].verdict]) || a.localeCompare(b));
+
+    for (const name of names) {
+      const p = r.plugins[name];
+      const label = { broken: '不兼容', partial: '部分可用', unknown: '未知', ok: '可用' }[p.verdict] || p.verdict;
+      L.push(`${label}  ${name}@${p.version || '?'}${p.vacuous ? '　[空洞的结论：无可检查对象]' : ''}`);
+      for (const f of p.findings || []) {
+        const api = f.service ? (f.method ? `${f.service}.${f.method}` : f.service) : '(包声明)';
+        const loc = f.location ? `${f.location.file}:${f.location.line}` : '—';
+        const cat = {
+          'host-service-missing': '服务缺失', 'host-method-missing': '方法缺失',
+          'unprovided-dependency': '无人提供的依赖', 'declaration-mismatch': '声明与实测不符',
+        }[f.category] || f.category;
+        const sev = { fatal: '致命', 'feature-dead': '功能失效', degraded: '降级' }[f.severity] || f.severity;
+        L.push(`    ${sev} / ${cat}${f.certainty === 'certain' ? '' : ' [疑似]'}  ${api}  @ ${loc}`);
+        if (f.impact) L.push(`      影响：${f.impact}`);
+      }
+      const cs = p.clientSide || [];
+      if (cs.length) L.push(`    客户端半边（命令行测不到，需界面验证）：${cs.map((c) => c.service).join('、')}`);
+      const noCalls = Object.values(p.resolved || {})
+        .filter((c) => c.disposition === 'no-calls').map((c) => c.service);
+      if (noCalls.length) L.push(`    无证据可判（只出现名字，没有调用点）：${noCalls.join('、')}`);
+    }
+
+    L.push('');
+    L.push('读这个结果时注意两点：');
+    L.push('  1) 「可用」不等于"功能验证过"。它只说明**用到的 DSH 服务与 API 都在**。'
+      + '插件仍然可能因为自身逻辑、配置或第三方依赖而出问题。');
+    L.push('  2) 「客户端半边」的那些服务命令行永远测不到 —— 它们活在浏览器里，'
+      + '只能靠"界面上有没有出现该插件的 UI"来验证。别把"没报错"当成"没问题"。');
+    return L.join('\n');
+  } catch (error) {
+    return `渲染结论时出错（工具的问题）：${errText(error)}`;
+  }
+}
+
+/** 工具的服务集合：`tools`；`agents` 用来把相对路径解析到会话工作目录。 */
+const TOOL_SERVICES = ['tools', 'agents'];
+
+function registerTool(ctx, state) {
+  // 与 C2 路由同一个理由：走作用域 ctx.inject，headless/CLI 形态下 `tools` 不在场时
+  // 这段根本不注册，本插件的 fiber 也就不会去等一个不存在的服务（`inject` 保持 []）。
+  if (typeof ctx.inject !== 'function') return;
+  ctx.inject(TOOL_SERVICES, (scope) => {
+    try {
+      if (!scope.tools || typeof scope.tools.register !== 'function') {
+        log('D1 tool skipped: scoped ctx has no tools.register');
+        return;
+      }
+      scope.tools.register({
+        name: 'compat_check',
+        description:
+          'Check whether the DSH plugins installed in this profile are actually compatible with the '
+          + 'current DSH version, and report the exact file:line and reason for anything that is not. '
+          + 'Use it when the user asks whether a plugin still works, why a feature disappeared after '
+          + 'updating DSH, or whether something they installed is safe to keep. It reads the installed '
+          + 'profile; it does not install anything or check a plugin that is not yet installed. '
+          + 'Findings are labelled "certain" (backed by the live runtime surface) or "suspected" '
+          + '(inferred from the official API catalogue, which is a contract catalogue and not the '
+          + 'runtime surface) — report that distinction to the user instead of flattening it.',
+        parameters: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            profile: {
+              type: 'string',
+              description:
+                'Optional profile name to inspect (e.g. "desktop"). Defaults to the profile this '
+                + 'DSH instance is running, or desktop if it cannot be determined.',
+            },
+          },
+        },
+        output: {
+          // ⚠️ **工具 DSL 不是 JSON Schema**：`required` 是**顶层数组**，
+          // 不是每个属性上的 `required: true`。写成后者会被宿主直接拒掉，
+          // 报 `schema.properties.X.required is not supported on type "string"`。
+          // 实测踩过：注册失败、工具不存在，而**面板与路由照常工作** ——
+          // 所以只有真的去调一次工具才发现得了。
+          schema: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              summary: { type: 'string' },
+              nodeModules: { type: 'string' },
+              hasRuntimeSurface: { type: 'boolean' },
+              text: { type: 'string' },
+            },
+            required: ['summary', 'nodeModules', 'hasRuntimeSurface', 'text'],
+          },
+          render: (_args, value) => [{ type: 'text', text: value && typeof value.text === 'string' ? value.text : '' }],
+        },
+        isConcurrencySafe: () => false,
+        presentCall: (args) => ({
+          card: 'generic',
+          title: 'compat_check',
+          kind: 'read',
+          rawInput: args || {},
+        }),
+        async execute(args) {
+          try {
+            const wanted = args && typeof args.profile === 'string' && args.profile.trim() !== ''
+              ? args.profile.trim()
+              : null;
+            const prev = process.env.DSC_PROFILE;
+            if (wanted) process.env.DSC_PROFILE = wanted;
+            let compat;
+            try {
+              compat = await computeReport(state, ctx);
+            } finally {
+              if (wanted) {
+                if (prev === undefined) delete process.env.DSC_PROFILE;
+                else process.env.DSC_PROFILE = prev;
+              }
+            }
+            const text = renderForModel(compat);
+            const s = (compat.report && compat.report.summary) || {};
+            return {
+              summary: `可用 ${s.ok || 0} / 部分可用 ${s.partial || 0} / 不兼容 ${s.broken || 0}`,
+              nodeModules: compat.nodeModules || '',
+              hasRuntimeSurface: Boolean(compat.report && compat.report.hasRuntimeSurface),
+              text,
+            };
+          } catch (error) {
+            // 工具的 execute 抛错会把整轮对话变成错误 —— 而"体检失败"不是用户的错，
+            // 也不该让他重来一遍。所以这里**不抛**，把失败也变成一段可读的文本。
+            return {
+              summary: '无法判定',
+              nodeModules: '',
+              hasRuntimeSurface: false,
+              text: `体检没跑成（这是工具的问题，不是插件的结论）：${errText(error)}\n`
+                + '请不要据此判断兼容性。',
+            };
+          }
+        },
+      });
+      log('D1 tool registered: compat_check');
+    } catch (error) {
+      log(`WARN D1 tool registration failed: ${errText(error)}`);
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// E1: skill 半边 —— 把 skill/SKILL.md 注册进 ctx.skills
+// ---------------------------------------------------------------------------
+//
+// **放在包里不算数。** DSH 不扫描插件包内的文件（实测见 skill/README.md）：
+// `@liustack/modlens` 发了 `skills/modlens/SKILL.md` 却没注册，运行时根本没有这个 skill。
+// 两条路能进 skill 目录：① 文件落进文件系统扫描根（那是脚本 --install-skill 的路）；
+// ② 运行时注册 —— 就是下面这段。
+//
+// 为什么用 `ctx.inject` 而不是静态 `inject = ['skills']`：与本文件开头同一条理由 ——
+// 静态 inject 会让本插件的 fiber 依赖 skills 服务，缺服务时整条条目停在 PENDING；
+// 而这个插件的职责正是"宿主缺了什么"，它自己更不能因为缺服务而消失。
+//
+// 字段约束读自运行时源码（`@deepseek-ai/dsh-skill` 的 validateCandidate），不是照抄：
+//   name 必须 kebab-case；description 必须非空；
+//   provider 必须**等于** provider 自己的 name（否则报 returned skill "x" for provider "y"）；
+//   rank 必须是有限数，600 是官方 bundled skill 用的 BUNDLED_SKILL_RANK。
+
+const SKILL_NAME = 'dsh-plugin-compat-check';
+const SKILL_PROVIDER = 'dsh-plugin-compat-check';
+const SKILL_RANK = 600;
+
+/**
+ * 随包的 SKILL.md 在哪。
+ *
+ * ## ⚠️ 候选顺序是**实测换来的**，不要随手调
+ *
+ * 原来只有 `join(here, '..', 'skill', 'SKILL.md')`（仓库形态）。
+ * 而**装进 profile 之后**它是 `<profile>/node_modules/dsh-plugin-compat-check`，
+ * 上一层是 `node_modules/` —— 那里当然没有 `skill/`。
+ *
+ * 实测的后果是**静默失效**：宿主日志只有一句
+ * `SKILL registration skipped: 找不到随包的 skill/SKILL.md`，
+ * 而 skill 是本项目三类产物之一。E1 当年报"跑通"是因为那次**在仓库里**跑的。
+ *
+ * 根因是 pnpm 按 `package.json` 的 `files` 字段**复制**目录（不是符号链接），
+ * 而当时 `files` 里没有 `skill/`。所以现在两件事一起做：
+ *   1. `files` 加了 `skill/`，且 `plugin/skill/SKILL.md` 是**提交的副本**
+ *      （`file:` 安装路径**不跑 `prepack`**，所以不能像 kernel/ 那样只在打包时暂存）；
+ *   2. 候选顺序把**包内**的放第一位 —— 那才是安装后的真实位置。
+ *
+ * 副本会漂移，所以 `test/skill.test.mjs` 有一条断言：两份必须逐字节相同。
+ */
+function readPackagedSkill() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(here, 'skill', 'SKILL.md'),        // **安装形态**：包内自带（files 里有 skill/）
+    join(here, '..', 'skill', 'SKILL.md'),  // 仓库形态：<repo>/plugin/index.js → <repo>/skill/SKILL.md
+    join(here, 'SKILL.md'),
+    join(here, 'assets', 'SKILL.md'),
+  ];
+  for (const file of candidates) {
+    try {
+      if (!existsSync(file)) continue;
+      const raw = readFileSync(file, 'utf8');
+      const fm = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(raw);
+      if (fm === null) continue;
+      // 只按**单行标量**读这两个字段。写成多行 YAML 时这里读不到 ——
+      // 宁可读不到（打一条日志），也好过猜一个错的 description。
+      const field = (key) => {
+        const m = new RegExp(`^${key}:[ \t]*(.+)$`, 'm').exec(fm[1]);
+        return m === null ? null : m[1].trim().replace(/^["']|["']$/g, '');
+      };
+      const skillName = field('name');
+      const description = field('description');
+      if (skillName === null || description === null) continue;
+      return { file, name: skillName, description, content: raw.slice(fm[0].length).trim() };
+    } catch {
+      /* 读不到就试下一个候选 */
+    }
+  }
+  return null;
+}
+
+function registerSkill(ctx) {
+  try {
+    if (typeof ctx.inject !== 'function') {
+      log('SKILL registration skipped: ctx.inject is not a function');
+      return;
+    }
+    ctx.inject(['skills'], (skillCtx) => {
+      try {
+        if (!skillCtx.skills || typeof skillCtx.skills.registerProvider !== 'function') {
+          log('SKILL registration skipped: scoped ctx has no skills.registerProvider');
+          return;
+        }
+        const skill = readPackagedSkill();
+        if (skill === null) {
+          log('SKILL registration skipped: 找不到随包的 skill/SKILL.md');
+          return;
+        }
+        // 正文在注册时读进内存：包内文件运行时不会变，这样 get() 永不抛。
+        const invocation = { modelInvocable: true, userInvocable: true };
+        const summary = {
+          name: SKILL_NAME,
+          description: skill.description,
+          invocation,
+          provider: SKILL_PROVIDER,
+          source: 'bundled',
+          rank: SKILL_RANK,
+          locator: skill.file,
+          path: skill.file,
+          resourceBase: { kind: 'directory', path: path.dirname(skill.file) },
+        };
+        skillCtx.skills.registerProvider(() => ({
+          name: SKILL_PROVIDER,
+          list: () => Promise.resolve([summary]),
+          get: () => Promise.resolve({
+            name: SKILL_NAME,
+            description: skill.description,
+            invocation,
+            provider: SKILL_PROVIDER,
+            source: summary.source,
+            path: skill.file,
+            content: skill.content,
+          }),
+        }));
+        log(`SKILL registered: ${SKILL_NAME} <- ${skill.file}`);
+      } catch (error) {
+        log(`SKILL registration failed: ${errText(error)}`);
+      }
+    });
+  } catch (error) {
+    log(`SKILL registration subscribe failed: ${errText(error)}`);
+  }
+}
+
+export function apply(ctx) {
+  // Nothing below may throw: a throw here fails this plugin's own fiber.
+  try {
+    log(`HOST-HALF-ACTIVATED pid=${process.pid} node=${process.version}`);
+
+    const state = {
+      applyAt: new Date().toISOString(),
+      loader: undefined,
+      loaderVia: null,
+      loaderAccess: {
+        attempts: [],
+        injectProbe: { registered: false, outcome: 'not run' },
+      },
+      disposeInjectProbe: null,
+      // ── F2：结果缓存 ──
+      // 面板打开时可能连着拉几次，而一次体检是几百毫秒到 1.5 秒的活。
+      // 更重要的是**启动时就先跑一次**（见下面的预热），这样用户点开面板是即时的。
+      lastReport: null,
+      lastReportAt: 0,
+      computing: null,
+      /** 缓存有效期。到点不清空，而是**先返回旧的、后台再刷新** —— 见下面的 stale-while-revalidate。 */
+      cacheTtlMs: toPositiveInt(process.env.DSC_CACHE_TTL_MS, 5 * 60 * 1000),
+      /** 启动后多久自动跑第一次（默认落在最后一次 loader 扫描之后） */
+      autoRunDelayMs: toPositiveInt(process.env.DSC_AUTORUN_MS, (SCAN_DELAYS[SCAN_DELAYS.length - 1] || 4000) + 2000),
+      autoRunTimer: null,
+    };
+
+    // Resolve the loader immediately: it is a plain service read and must not
+    // depend on the entry tree having settled.
+    try {
+      const resolved = resolveLoader(ctx);
+      state.loader = resolved.loader;
+      state.loaderVia = resolved.via;
+      state.loaderAccess = { ...state.loaderAccess, ...publicLoaderAccess(resolved) };
+      log(
+        `loader access: via=${resolved.via ?? 'UNREACHABLE'} attempts=${JSON.stringify(resolved.attempts)}`,
+      );
+    } catch (error) {
+      state.loaderAccess.attempts.push(`resolveLoader threw: ${errText(error)}`);
+      log(`ERROR resolving loader: ${errText(error)}`);
+    }
+
+    // The `inject: ["loader"]` safety experiment (see startInjectProbe).
+    try {
+      state.disposeInjectProbe = startInjectProbe(ctx, state.loaderAccess.injectProbe);
+    } catch (error) {
+      state.loaderAccess.injectProbe.outcome = `probe setup threw: ${errText(error)}`;
+    }
+
+    // ── C2 数据通道 ──
+    //
+    // 路由挂在**作用域 ctx** 上，而不是本插件自己的 ctx 上：这样
+    // webServer 缺席时（headless / CLI 形态）这一段根本不注册，
+    // 本插件的 fiber 也不会去等一个不存在的服务 —— `inject` 保持 []，
+    // 与本文件的整体设计一致（见文件头）。
+    try {
+      if (typeof ctx.inject === 'function') {
+        ctx.inject(['webServer'], (scope) => {
+          try {
+            scope.webServer.register({
+              name: 'dsh-plugin-compat-check',
+              kind: 'exact',
+              path: '/plugin-compat-check/report',
+              handler: async (req, res) => {
+                // 体检结论是本机信息（装了哪些插件、用了哪些 API），
+                // 不该被这台机器上的任意页面读到。
+                if (!isTrustedRequest(req)) {
+                  res.writeHead(403, { 'content-type': 'application/json; charset=utf-8' });
+                  res.end(JSON.stringify({ error: 'refused: untrusted request' }));
+                  return;
+                }
+                try {
+                  const url = new URL(req.url || '/', 'http://127.0.0.1');
+                  const force = url.searchParams.get('refresh') === '1';
+                  const out = await serveReport(state, ctx, force);
+                  res.writeHead(200, {
+                    'content-type': 'application/json; charset=utf-8',
+                    'cache-control': 'no-store',
+                  });
+                  res.end(JSON.stringify(out));
+                } catch (error) {
+                  // 连处理器里都不抛：把错误变成一条可读的 JSON，而不是 500 空响应。
+                  res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
+                  res.end(JSON.stringify({ ok: false, error: errText(error) }));
+                }
+              },
+            });
+            log('C2 route registered: GET /plugin-compat-check/report');
+          } catch (error) {
+            log(`WARN C2 route registration failed: ${errText(error)}`);
+          }
+        });
+      } else {
+        log('C2 route skipped: ctx.inject is not a function');
+      }
+    } catch (error) {
+      log(`WARN C2 route setup threw: ${errText(error)}`);
+    }
+
+    // E1：注册随包的 skill。**失败只留日志，绝不抛** —— 见文件顶部硬规矩。
+    try {
+      registerSkill(ctx);
+    } catch (error) {
+      log(`WARN SKILL registration threw: ${errText(error)}`);
+    }
+
+    // D1：对话工具（同一个 computeReport，所以工具与面板不可能给出不同答案）
+    try {
+      registerTool(ctx, state);
+    } catch (error) {
+      log(`WARN D1 tool setup threw: ${errText(error)}`);
+    }
+
+    const finish = () => {
+      const probe = state.loaderAccess.injectProbe;
+      if (probe.registered && probe.firedAfterMs === undefined && probe.outcome === 'not run') {
+        probe.outcome = 'did not fire before the final scan (would have stayed PENDING)';
+      }
+      log(
+        `inject-probe: registered=${probe.registered} outcome=${probe.outcome}${
+          probe.firedAfterMs !== undefined ? ` firedAfterMs=${probe.firedAfterMs}` : ''
+        }`,
+      );
+      // ⚠️ 这里**不要**动 `state.autoRunTimer`。它是 F2 的启动自检，与 loader 扫描
+      // 是两件事 —— 但它们**时间上相邻**：默认时机就落在最后一次扫描之后 2 秒。
+      // 早先写成了 `finish()` 里 clearTimeout(autoRunTimer)，于是最后一次扫描一结束
+      // 就把启动自检取消了：**它从来没跑过，也没有任何报错**（性能测量看不见的静默失效）。
+      // 教训：清理定时器必须由创建它的那一方负责。
+      // F2：最后一次扫描之后跑启动自检 —— 这时候条目状态才是稳的。
+      try {
+        if (typeof state.runAutoCheck === 'function') state.runAutoCheck();
+      } catch (error) {
+        log(`WARN F2 启动自检触发失败: ${errText(error)}`);
+      }
+      try {
+        if (typeof state.disposeInjectProbe === 'function') {
+          state.disposeInjectProbe();
+          state.disposeInjectProbe = null;
+        }
+      } catch (error) {
+        log(`WARN disposing inject probe failed: ${errText(error)}`);
+      }
+    };
+
+    // Passes are serialized: each scan is time-bounded internally, so the next
+    // one can safely wait for it and the report file is never written twice
+    // concurrently.
+    const schedulePass = (index) => {
+      const previous = index === 0 ? 0 : SCAN_DELAYS[index - 1];
+      const delay = Math.max(0, SCAN_DELAYS[index] - previous);
+      const timer = setTimeout(() => {
+        const pass = index + 1;
+        try {
+          scan(ctx, state, pass)
+            .catch((error) => log(`ERROR scan#${pass} failed: ${errText(error)}`))
+            .finally(() => {
+              if (pass < SCAN_DELAYS.length) schedulePass(index + 1);
+              else finish();
+            });
+        } catch (error) {
+          log(`ERROR scan#${pass} threw synchronously: ${errText(error)}`);
+        }
+      }, delay);
+      // unref: a scan timer must never keep the host process alive.
+      if (timer && typeof timer.unref === 'function') timer.unref();
+    };
+    schedulePass(0);
+
+    // ── F2：启动后自动跑一次，并把「变了没有」直接打进启动日志 ──
+    //
+    // 为什么值得单独做：本产品最大的风险不是"算错"，而是**用户想不起来看**。
+    // 角标只在他点开面板时才存在；而"上次是好的、这次不行了"这件事，
+    // 最该被知道的时间点就是**启动时**。
+    //
+    // 时机：**由最后一次 loader 扫描完成来触发**，而不是另起一个定时器。
+    // 两个理由：
+    //   1. 插件条目的状态在启动后几秒内还会变（异步 import），太早跑会把
+    //      "还在加载"误记成"没起来"；
+    //   2. 早先用独立定时器，结果它和 `finish()` 的时间**相邻**，被 `finish()`
+    //      的清理顺手取消掉了 —— 启动自检从未运行、且**没有任何报错**。
+    //      一个"看起来做了其实没做"的定时器，比没有更糟。
+    state.runAutoCheck = () => {
+      if (state.autoCheckStarted) return;   // 幂等：只跑一次
+      state.autoCheckStarted = true;
+      try {
+        computeReport(state, ctx)
+          .then((out) => {
+            state.lastReport = out;
+            state.lastReportAt = Date.now();
+            if (out && out.ok) {
+              const sum = out.report.summary || {};
+              const b = out.baseline || {};
+              const badge = b.badge || {};
+              log(`F2 启动自检: 可用 ${sum.ok || 0} 部分可用 ${sum.partial || 0} 不兼容 ${sum.broken || 0}`
+                + (sum.vacuousOk ? ` (${sum.vacuousOk} 个为空洞的可用)` : ''));
+              // 有变化就打成一条显眼的日志；没变化也要有一条。
+              // 「没有变化」必须说出来 —— 沉默会被读成"没检查"或"坏消息被藏起来了"。
+              if (badge.show) log(`F2 与上次相比: ${badge.text} —— ${badge.detail || ''}`);
+              else log(`F2 与上次相比: ${badge.detail || b.note || '没有可比基线'}`);
+            } else if (out) {
+              log(`WARN F2 启动自检没跑成: ${out.error || '未知原因'}`);
+            }
+          })
+          .catch((error) => log(`WARN F2 启动自检失败: ${errText(error)}`));
+      } catch (error) {
+        log(`WARN F2 启动自检同步失败: ${errText(error)}`);
+      }
+    };
+
+    // 兜底：万一 loader 扫描那条路没走到（例如 loader 完全不可达，
+    // `scan` 会提前 return），启动自检也必须跑。两条路都调 `runAutoCheck`，
+    // 由它自己保证幂等 —— 谁先到都算数。
+    {
+      const timer = setTimeout(() => { try { state.runAutoCheck(); } catch { /* 忽略 */ } }, state.autoRunDelayMs);
+      if (timer && typeof timer.unref === 'function') timer.unref();
+      state.fallbackTimer = timer;
+    }
+
+    // Manual re-scan handle for tooling/experiments (no host service needed).
+    try {
+      globalThis.__DSH_COMPAT_CHECK__ = {
+        rescan: () => scan(ctx, state, 0),
+        reportPath: OUT_JSON,
+        // 面板用的那份结论（同一个函数，所以界面与工具不可能给出不同答案）
+        compatReport: (c) => computeReport(state, c || ctx),
+      };
+    } catch {
+      /* 忽略 */
+    }
+  } catch (error) {
+    try {
+      log(`FATAL-SWALLOWED apply() failed: ${errText(error)}`);
+    } catch {
+      /* 连打日志都失败就只能咽下去 */
+    }
+  }
+}