dsh-plugin-compat-check 0.1.2 → 0.1.3

package/README.md

@@ -1,11 +1,13 @@
 # dsh-plugin-compat-check
 
-检查**已经安装的 DSH 插件**与当前 DSH 版本的兼容性，提供源码位置、运行时证据与覆盖限制。包含兼容性面板、插件详情角标、`compat_check` 对话工具和 skill provider。
+检查**已经安装的 DSH 插件**与当前 DSH 版本的兼容性，提供源码位置、运行时证据与覆盖限制。包含兼容性标签、插件详情发现/角标、`compat_check` 对话工具和skill provider。
 
-本文件适用于 **0.1.2**。安装指定版本：
+![插件详情页：部分可用，含 file:line、影响与依据](https://raw.githubusercontent.com/lcy0121/dsh-plugin-compat-check/main/plugin/assets/compat-detail-partial.png)
+
+本文描述 **0.1.3** 的实现；是否已发布及 npm latest 以[发布记录](https://github.com/lcy0121/dsh-plugin-compat-check/blob/main/docs/Plan.md)与registry为准。安装公开版本（发布前不能用源码测试代替公开包验收）：
 
 ```bash
-dsh plugin --profile <profile> add dsh-plugin-compat-check@0.1.2
+dsh plugin --profile <profile> add dsh-plugin-compat-check
 ```
 
 ## 从源码构建安装
@@ -20,17 +22,19 @@ dsh plugin --profile <临时profile> add file:<生成的tgz绝对路径>
 
 prepack复制权威skill、同步单源报告契约的宿主/客户端产物，并暂存共享kernel和MIT LICENSE，postpack清理kernel。固定运行时依赖为 `@babel/parser@7.29.9` 与 `semver@7.7.3`，支持 Node `^22.19.0 || >=24`。源码裸复制或file安装不保证prepack运行，应使用完整仓库开发布局或预打包tarball。
 
-npm产物**不带CLI bin、安装检查shell或probe入口**。CLI和安装检查从仓库使用；本插件不能做安装前检查。仓库使用说明：[README](https://github.com/lcy0121/dsh-plugin-compat-check#readme)。版本说明与发布状态请查看[开发计划与验收记录](https://github.com/lcy0121/dsh-plugin-compat-check/blob/main/docs/Plan.md)，本地路径为docs/Plan.md。
+npm产物**不带CLI bin、安装检查shell或probe入口**。CLI和安装检查从仓库使用；仓库源码现提供`--issue-report`默认脱敏Markdown导出，不读写基线、保留原退出码，须预览后自行分享，该功能不在npm包内。本插件不能做安装前检查。仓库使用说明：[README](https://github.com/lcy0121/dsh-plugin-compat-check#readme)。版本说明与发布状态请查看[开发计划与验收记录](https://github.com/lcy0121/dsh-plugin-compat-check/blob/main/docs/Plan.md)，本地路径为docs/Plan.md。
 
-0.1.2修正发布状态文案并统一版本标记；判定算法与0.1.1一致。规则/API目录仍基于0.2.0-rc.2，不把新版接入测试当作全面适配。
+0.1.3增加目标版本声明适配、rc.2目录与卸载清理；历史0.1.2只修正文案和版本，算法与0.1.1一致；0.1.3改变了新版DSH声明判定。
 
 ## 判定与边界
 
+2026-10-18从候选完整tgz在私有rc.2宿主和真实Chrome验证：“更多 → 设置 → 内置插件 → 兼容性”可见标签和报告；禁用后报告路由消失，启用后恢复且标签唯一。59714e7中10月17日标签未显示的历史记录本次未复现，原因未定；不把这次局部UI验收当作所有业务功能认证。
+
 当前profile在宿主进程内采样服务描述符，不执行getter；未知访问器保留未知，并纳入能可靠映射的loader FAILED/PENDING。查询其它profile只用静态证据，不借用当前宿主服务。Babel AST扫描不执行目标源码，分析运行在有时间和内存上限的worker中；动态调用和跨函数数据流仍有限。
 
-`certainty`为certain或suspected；过滤、守卫、弃权是独立去处。省略的probe键表示未采样，不表示服务缺失。现代观测匹配profile/DSH版本且默认24小时过期；旧报告标记未绑定。声明不能代替API实测，官方peer冲突以推断影响呈现，当前实现仍按0.2.0-rc.2把engines.dsh作建议处理。0.2.1-rc.1宿主已优先按该字段判断，声明有误报/漏报风险，应核对实际宿主结果；本补丁未改判定算法。
+`certainty`为certain或suspected；过滤、守卫、弃权另列。省略probe键为未采样，现代观测绑定profile/DSH版本且默认24小时过期，旧报告标记未绑定。0.1.3对DSH≥0.2.1-rc.1优先自有engines.dsh，缺失时回退官方peer；旧目标保持旧规则。声明冲突/非法字段的影响为推断，不冒充实测加载失败。只读profile独立compatibility.json，按插件名、插件精确版本及DSH精确版本匹配；无效记录整条忽略并限制覆盖，不可读/超64KiB则豁免未观测，不自动写入豁免。
 
-转述时保留 `impactBasis=inferred`（影响为推断，非实测）、coverage限制和vacuous结果。API发现通常有file:line，loader/元数据发现可能没有源码位置。客户端服务列为待界面核验项；独立浏览器开发工具不属于本面板，且不验证业务交互。
+按已知目标选目录：DSH≥0.2.1-rc.2用rc.2快照（host98/client8），其余/未知用原0.2.0-rc.2快照（host91/client8）；未来版本未经认证。转述保留 `impactBasis=inferred`、coverage限制和vacuous。API发现通常有file:line，loader/声明事实可能无位置；声明获准不证明API或业务成功。客户端待界面核验；到货工具与新增的独立业务队列均不属于本面板。仓库业务队列覆盖固定dshmarket的备注/收藏，以及dsh-better-sidebar的保存/预览HTTP路径、编码/换行保留及失败后恢复；对照仅在浏览器注入POST503，业务标签不进入兼容性判定，结果不认证其它路径或原插件有缺陷。
 
 插件体检不安装包、不调用外部命令或联网；会启动分析worker，并默认写自己的schema2基线：`$DSH_HOME/dsh-plugin-compat-check/baseline.<profile>.<path-hash>.<mode>.json`。模式分离、锁内比较、原子替换；源码扫描不完整不推进基线。默认不输出共享loader诊断；诊断需显式私有DSC_OUT_DIR。若需完全禁止基线读写，请使用仓库CLI的 `--no-baseline`。
 

package/index.js

@@ -21,7 +21,7 @@
 //   ${DSC_OUT_DIR}/loader-introspect.json (explicit owned private directory only)
 // plus structured console lines prefixed with [dsh-plugin-compat-check].
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, realpathSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import path, { join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -462,6 +462,7 @@ function toEntryArray(value) {
 }
 
 async function scan(ctx, state, pass) {
+  if(state.disposed)return;
   const report = {
     schemaVersion: SCHEMA_VERSION,
     plugin: name,
@@ -550,6 +551,7 @@ async function scan(ctx, state, pass) {
     return true;
   });
 
+  if(state.disposed)return report;
   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)'}`,
@@ -700,6 +702,18 @@ function resolveDshVersion() {
     }
   } catch { /* 继续 */ }
 
+  // npm prefixes need not end in /dsh/. Read only an official runtime's own
+  // manifest above the real entry; package.json need not be an exported subpath.
+  try {
+    let dir=path.dirname(path.resolve(realpathSync(process.argv[1])));
+    for(let depth=0;depth<32;depth++){
+      try{
+        const meta=JSON.parse(readFileSync(join(dir,'package.json'),'utf8'));
+        if(['@deepseek-ai/dsh','@deepseek-ai/dsh-desktop-host','@deepseek-ai/dsh-app-boot'].includes(meta.name)&&typeof meta.version==='string'&&meta.version)return meta.version;
+      }catch{}
+      const parent=path.dirname(dir);if(parent===dir)break;dir=parent;
+    }
+  }catch{}
   // ③ 都没有 → **null，不猜**（判定层会据此不产出声明不符的结论）
   return null;
 }
@@ -790,6 +804,7 @@ function resolveNodeModules(requestedProfile = null) {
  * 同时到达也只会算一次 —— 否则它们会各自算一遍，白烧 1.5 秒 × 10。
  */
 async function serveReport(state, ctx, force, options = {}) {
+  if(state.disposed)return failureEnvelope('Plugin generation disposed / 已卸载');
   if(!state.reportService){
     const kernel=resolveKernelDir();
     if(!kernel)return failureEnvelope('找不到判定内核');
@@ -797,7 +812,7 @@ async function serveReport(state, ctx, force, options = {}) {
     if(!state.reportService)state.reportService=new ReportService(async options=>{const out=await computeReport(state,ctx,options);return out.ok?assertEnvelope(out):failureEnvelope(out.error,out);},{ttlMs:state.cacheTtlMs});
   }
   const key=options.profile?`profile:${options.profile}`:'current';
-  const out=await state.reportService.get(key,options,force);return out?.ok?assertEnvelope(out):failureEnvelope(out?.error,out||{});
+  const out=await state.reportService.get(key,options,force);if(state.disposed)return failureEnvelope('Plugin generation disposed / 已卸载');return out?.ok?assertEnvelope(out):failureEnvelope(out?.error,out||{});
 }
 
 /**
@@ -817,13 +832,14 @@ function baselineFileFor(nmDir) {
 }
 
 /**
- * 跑一次体检。**同步、纯计算、不抛**。
+ * 跑一次有界体检；异步分析、可写自身基线，错误由报告返回。
  *
  * 为什么宿主半边要算而不是把原始数据丢给客户端：
  *   - 客户端跑在浏览器里，读不了文件系统；
  *   - 结论（五元组 + 确定性）是内核的产物，算出唯一一份才不会两边漂移。
  */
 async function computeReport(state, ctx, options = {}) {
+  if(state.disposed)return failureEnvelope('Plugin generation disposed / 已卸载');
   const started = Date.now();
   const out = {
     schemaVersion: 1,
@@ -872,7 +888,8 @@ async function computeReport(state, ctx, options = {}) {
     const { extractInWorker } = await import(pathToFileURL(join(kernel, 'lib', 'worker-analysis.mjs')).href);
     const { buildVerdicts } = await import(pathToFileURL(join(kernel, 'lib', 'verdict.mjs')).href);
 
-    const catalogPath = join(kernel, 'rules', 'dsh-api-catalog.json');
+    const {catalogPathFor}=await import(pathToFileURL(join(kernel,'lib','catalog.mjs')).href);
+    const catalogPath = catalogPathFor(kernel,resolveDshVersion());
     const rulesPath = join(kernel, 'rules', 'severity.json');
     const catalog = JSON.parse(readFileSync(catalogPath, 'utf8'));
     const rules = JSON.parse(readFileSync(rulesPath, 'utf8'));
@@ -893,6 +910,7 @@ async function computeReport(state, ctx, options = {}) {
     out.surfaceWhy = surfaceWhy;
 
     const extracted = await extractInWorker(nm.dir, { catalog });
+    if(state.disposed)return failureEnvelope('Plugin generation disposed / 已卸载');
     const { sampleServices } = await import(pathToFileURL(join(kernel,'lib','observation.mjs')).href);
     const currentTarget=resolveNodeModules();
     const sameHost=currentTarget.dir&&path.resolve(currentTarget.dir)===path.resolve(nm.dir);
@@ -905,6 +923,8 @@ async function computeReport(state, ctx, options = {}) {
     out.loaderCoverage=loaderState;
 
     out.surfaceWhy=surfaceWhy;
+    const {readProfileCompatibility}=await import(pathToFileURL(join(kernel,'lib','profile-compatibility.mjs')).href);
+    const compatibility=readProfileCompatibility(nm.dir);
     const verdict = buildVerdicts({
       report: extracted.report,
       hostSurface,
@@ -913,6 +933,8 @@ async function computeReport(state, ctx, options = {}) {
       dshVersion: resolveDshVersion(),
       entryStates: loaderState.rows,
       observationTarget: {profileId:nm.dir,maxAgeMs:24*60*60*1000},
+      compatibilityExemptions: compatibility.exemptions,
+      compatibilityNotes: compatibility.notes,
     });
 
     // ── C4：基线差分 ──
@@ -926,6 +948,7 @@ async function computeReport(state, ctx, options = {}) {
       const identity=store.baselineIdentity(nm.dir,verdict.observation.mode,rules,catalog);
       const snap = snapshotForBaseline(verdict, resolveDshVersion(),identity);
       const bfile = store.baselinePath(nm.dir,verdict.observation.mode);
+      if(state.disposed)return failureEnvelope('Plugin generation disposed / 已卸载');
       baseline=store.baselineTransaction(bfile,snap,{advance:extracted.report.scanComplete});
     } catch (error) {
       baseline = { error: errText(error), note: '基线差分没算成（不影响本次结论）' };
@@ -957,6 +980,7 @@ async function computeReport(state, ctx, options = {}) {
     }
 
     const {toJSON}=await import(pathToFileURL(join(kernel,'lib','report.mjs')).href);
+    if(state.disposed)return failureEnvelope('Plugin generation disposed / 已卸载');
     const canonical=toJSON({error:null,extract:extracted,verdict,baseline,inputs:{nodeModules:nm.dir,hasRuntimeSurface:verdict.observation.usable,catalog:catalogPath,rules:rulesPath}});
     out.baseline = canonical.baseline;
     out.dshVersion = canonical.dshVersion;
@@ -1076,7 +1100,7 @@ function registerTool(ctx, state) {
         log('D1 tool skipped: scoped ctx has no tools.register');
         return;
       }
-      scope.tools.register({
+      const dispose = scope.tools.register({
         name: 'compat_check',
         description:
           'Check whether the DSH plugins installed in this profile are actually compatible with the '
@@ -1150,6 +1174,7 @@ function registerTool(ctx, state) {
         },
       });
       log('D1 tool registered: compat_check');
+      return dispose;
     } catch (error) {
       log(`WARN D1 tool registration failed: ${errText(error)}`);
     }
@@ -1260,7 +1285,7 @@ function registerSkill(ctx) {
           path: skill.file,
           resourceBase: { kind: 'directory', path: path.dirname(skill.file) },
         };
-        skillCtx.skills.registerProvider(() => ({
+        const dispose = skillCtx.skills.registerProvider(() => ({
           name: SKILL_PROVIDER,
           list: () => Promise.resolve([summary]),
           get: () => Promise.resolve({
@@ -1274,6 +1299,7 @@ function registerSkill(ctx) {
           }),
         }));
         log(`SKILL registered: ${SKILL_NAME} <- ${skill.file}`);
+        return dispose;
       } catch (error) {
         log(`SKILL registration failed: ${errText(error)}`);
       }
@@ -1289,6 +1315,8 @@ export function apply(ctx) {
     log(`HOST-HALF-ACTIVATED pid=${process.pid} node=${process.version}`);
 
     const state = {
+      disposed: false,
+      scanTimers: new Set(),
       applyAt: new Date().toISOString(),
       loader: undefined,
       loaderVia: null,
@@ -1342,7 +1370,7 @@ export function apply(ctx) {
       if (typeof ctx.inject === 'function') {
         ctx.inject(['webServer'], (scope) => {
           try {
-            scope.webServer.register({
+            const dispose = scope.webServer.register({
               name: 'dsh-plugin-compat-check',
               kind: 'exact',
               path: '/plugin-compat-check/report',
@@ -1371,6 +1399,7 @@ export function apply(ctx) {
               },
             });
             log('C2 route registered: GET /plugin-compat-check/report');
+            return dispose;
           } catch (error) {
             log(`WARN C2 route registration failed: ${errText(error)}`);
           }
@@ -1431,14 +1460,18 @@ export function apply(ctx) {
     // one can safely wait for it and the report file is never written twice
     // concurrently.
     const schedulePass = (index) => {
+      if(state.disposed)return;
       const previous = index === 0 ? 0 : SCAN_DELAYS[index - 1];
       const delay = Math.max(0, SCAN_DELAYS[index] - previous);
       const timer = setTimeout(() => {
+        state.scanTimers.delete(timer);
+        if(state.disposed)return;
         const pass = index + 1;
         try {
           scan(ctx, state, pass)
             .catch((error) => log(`ERROR scan#${pass} failed: ${errText(error)}`))
             .finally(() => {
+              if(state.disposed)return;
               if (pass < SCAN_DELAYS.length) schedulePass(index + 1);
               else finish();
             });
@@ -1448,6 +1481,7 @@ export function apply(ctx) {
       }, delay);
       // unref: a scan timer must never keep the host process alive.
       if (timer && typeof timer.unref === 'function') timer.unref();
+      state.scanTimers.add(timer);
     };
     schedulePass(0);
 
@@ -1465,6 +1499,7 @@ export function apply(ctx) {
     //      的清理顺手取消掉了 —— 启动自检从未运行、且**没有任何报错**。
     //      一个"看起来做了其实没做"的定时器，比没有更糟。
     state.runAutoCheck = () => {
+      if(state.disposed)return;
       if (state.autoCheckStarted) return;   // 幂等：只跑一次
       state.autoCheckStarted = true;
       try {
@@ -1503,12 +1538,21 @@ export function apply(ctx) {
 
     // Manual re-scan handle for tooling/experiments (no host service needed).
     try {
-      globalThis.__DSH_COMPAT_CHECK__ = {
+      const handle = {
         rescan: () => scan(ctx, state, 0),
         reportPath: OUT_JSON,
         // 面板用的那份结论（同一个函数，所以界面与工具不可能给出不同答案）
         compatReport: (c) => computeReport(state, c || ctx),
       };
+      globalThis.__DSH_COMPAT_CHECK__ = handle;
+      if(typeof ctx.effect==='function')ctx.effect(()=>()=>{
+        state.disposed=true;
+        for(const timer of state.scanTimers)clearTimeout(timer);
+        state.scanTimers.clear();
+        clearTimeout(state.fallbackTimer);
+        state.disposeInjectProbe?.();state.disposeInjectProbe=null;
+        if(globalThis.__DSH_COMPAT_CHECK__===handle)delete globalThis.__DSH_COMPAT_CHECK__;
+      },'compat-check: generation cleanup');
     } catch {
       /* 忽略 */
     }

package/kernel/lib/catalog.mjs

@@ -0,0 +1,16 @@
+/** Keep the frozen legacy catalogue available for older targets and overrides. */
+import path from "node:path";
+import semver from "semver";
+
+export function catalogPathFor(root, version, override) {
+  if (override) return override;
+  const modern =
+    typeof version === "string" &&
+    semver.valid(version) &&
+    semver.gte(version, "0.2.1-rc.2");
+  return path.join(
+    root,
+    "rules",
+    modern ? "dsh-api-catalog-0.2.1-rc.2.json" : "dsh-api-catalog.json",
+  );
+}

package/kernel/lib/declarations.mjs

@@ -1,7 +1,7 @@
 import semver from "semver";
 
 /** DSH app-boot 0.2.0-rc.2 checks every official dsh peer, including prereleases. */
-export function declaredSupport(pkg, version) {
+function legacySupport(pkg, version) {
   if (!version || !semver.valid(version)) return null;
   const requirements = [];
   for (const [name, range] of Object.entries(pkg.peerDependencies || {})) {
@@ -48,3 +48,102 @@ export function declaredSupport(pkg, version) {
       .map((r) => `Invalid declared range for ${r.name}`),
   };
 }
+
+const own = (value, key) => value != null && Object.hasOwn(value, key);
+const record = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** Match the engines-first policy introduced by app-boot 0.2.1-rc.1.
+ * This predicts declaration acceptance, never plugin activation or behavior.
+ */
+export function declaredSupport(pkg, version, { exemptions } = {}) {
+  if (!version || !semver.valid(version)) return null;
+  if (semver.lt(version, "0.2.1-rc.1")) return legacySupport(pkg, version);
+  const compatibility = pkg.compatibility;
+  pkg = pkg.declarationManifest ?? pkg;
+  const requirements = [];
+  let error = null;
+  if (!record(pkg)) return null;
+  const engines = own(pkg, "engines") ? pkg.engines : {};
+  if (!record(engines)) error = "Plugin manifest engines must be an object";
+  else if (own(engines, "dsh")) {
+    if (typeof engines.dsh !== "string")
+      error = "Plugin manifest engines.dsh must be a string";
+    else
+      requirements.push({
+        name: "dsh",
+        range: engines.dsh,
+        source: "engines.dsh",
+      });
+  } else if (own(pkg, "peerDependencies")) {
+    if (!record(pkg.peerDependencies))
+      error = "Plugin manifest peerDependencies must be an object";
+    else
+      for (const [name, range] of Object.entries(pkg.peerDependencies)) {
+        if (typeof range !== "string") {
+          error = "Plugin manifest peerDependencies ranges must be strings";
+          break;
+        }
+        if (name === "@deepseek-ai/dsh" || name.startsWith("@deepseek-ai/dsh-"))
+          requirements.push({ name, range, source: "peerDependencies" });
+      }
+  }
+  const checks = requirements.map((r) => {
+    const range =
+      r.source === "peerDependencies" &&
+      ["workspace:^", "workspace:~", "workspace:*"].includes(r.range)
+        ? version
+        : r.range;
+    return {
+      ...r,
+      valid: semver.validRange(range) !== null,
+      compatible:
+        range.trim() !== "" &&
+        semver.satisfies(version, range, { includePrerelease: true }),
+    };
+  });
+  const rejected = checks.filter((r) => !r.compatible);
+  if (
+    !error &&
+    rejected.length &&
+    ["name", "version"].some(
+      (key) =>
+        !own(pkg, key) || typeof pkg[key] !== "string" || !pkg[key].trim(),
+    )
+  )
+    error =
+      "Plugin manifest name/version must be non-empty strings when requirements are unmet";
+  const exact =
+    compatibility?.[version] ?? compatibility?.dshReleases?.[version];
+  const exactClaim =
+    exact === "compatible" ? true : exact === "incompatible" ? false : null;
+  if (!error && !checks.length && exactClaim === null) return null;
+  const grant = error
+    ? false
+    : exemptions === undefined
+      ? null
+      : own(exemptions, pkg.name + "@" + pkg.version) &&
+        Array.isArray(exemptions[pkg.name + "@" + pkg.version]) &&
+        exemptions[pkg.name + "@" + pkg.version].includes(version);
+  return {
+    claimsCompatible:
+      !error &&
+      (checks.length
+        ? checks.every((r) => r.compatible) && exactClaim !== false
+        : exactClaim),
+    policy: "engines-first",
+    invalid: error,
+    rejected,
+    exempted: grant,
+    raw: {
+      compatibility: compatibility ?? null,
+      engines: own(pkg, "engines") ? pkg.engines : null,
+      peers: checks,
+    },
+    notes: error
+      ? [error]
+      : checks
+          .filter((r) => !r.valid)
+          .map((r) => "Invalid declared range for " + r.name),
+  };
+}

package/kernel/lib/extract.mjs

@@ -232,6 +232,11 @@ export function extractWithProvenance(nm, options = {}) {
       clientInject: client.inject ?? null,
       peerDependencies: j.peerDependencies ?? null,
       // 声明的兼容性口径（第 8 题：「声明与实测不符」这一类结论的输入）
+      declarationManifest: Object.fromEntries(
+        ["name", "version", "engines", "peerDependencies"]
+          .filter((key) => Object.hasOwn(j, key))
+          .map((key) => [key, j[key]]),
+      ),
       engines: j.engines ?? null,
       compatibility: dsh.compatibility ?? null,
       declaredClientEntry: declaredClientEntry(j),

package/kernel/lib/profile-compatibility.mjs

@@ -0,0 +1,69 @@
+/** Read independent profile grants without importing or changing target plugins. */
+import fs from "node:fs";
+import path from "node:path";
+import semver from "semver";
+
+const exact = (value) => {
+  const parsed = typeof value === "string" ? semver.parse(value) : null;
+  return (
+    parsed !== null &&
+    value ===
+      parsed.version + (parsed.build.length ? "+" + parsed.build.join(".") : "")
+  );
+};
+export function readProfileCompatibility(nodeModules) {
+  const file = path.join(path.dirname(nodeModules), "compatibility.json");
+  const unavailable = (note) => ({
+    file,
+    exemptions: undefined,
+    notes: [note],
+  });
+  let fd;
+  try {
+    fd = fs.openSync(
+      file,
+      fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK || 0),
+    );
+    if (!fs.fstatSync(fd).isFile())
+      return unavailable("compatibility.json 不是普通文件，精确豁免未观测");
+    const buffer = Buffer.alloc(65537),
+      length = fs.readSync(fd, buffer, 0, buffer.length, 0);
+    if (length > 65536)
+      return unavailable(
+        "compatibility.json 超过64KiB读取预算，精确豁免未观测",
+      );
+    const value = JSON.parse(buffer.subarray(0, length).toString("utf8"));
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+      return unavailable(
+        "compatibility.json 必须为精确版本豁免对象，记录未采用",
+      );
+    const exemptions = Object.create(null),
+      notes = [];
+    for (const [key, versions] of Object.entries(value)) {
+      const i = key.lastIndexOf("@");
+      if (
+        i <= 0 ||
+        !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(
+          key.slice(0, i),
+        ) ||
+        !exact(key.slice(i + 1)) ||
+        !Array.isArray(versions) ||
+        !versions.every(exact)
+      ) {
+        notes.push("compatibility.json 含无效的精确版本豁免记录，已忽略");
+        continue;
+      }
+      Object.defineProperty(exemptions, key, {
+        value: versions,
+        enumerable: true,
+      });
+    }
+    return { file, exemptions, notes };
+  } catch (error) {
+    return error.code === "ENOENT"
+      ? { file, exemptions: {}, notes: [] }
+      : unavailable("compatibility.json 不可读或JSON无效，精确豁免未观测");
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}

package/kernel/lib/verdict.mjs

@@ -99,8 +99,8 @@ export function methodRule(rules, service, method, side = "host") {
     return null;
   return rule;
 }
-export function declarationOf(p, version) {
-  return declaredSupport(p, version);
+export function declarationOf(p, version, options) {
+  return declaredSupport(p, version, options);
 }
 export function buildVerdicts({
   report,
@@ -110,6 +110,8 @@ export function buildVerdicts({
   dshVersion = null,
   entryStates = [],
   observationTarget = {},
+  compatibilityExemptions,
+  compatibilityNotes = [],
 }) {
   const observation = normalizeObservation(hostSurface, {
     dshVersion,
@@ -146,6 +148,7 @@ export function buildVerdicts({
     const resolved = Object.create(null);
     const limitations = [
       ...observation.notes,
+      ...compatibilityNotes,
       ...(p.diagnostics || []).map((d) => `${d.kind}: ${d.file ?? ""}`),
     ];
     let verified = 0;
@@ -422,14 +425,32 @@ export function buildVerdicts({
           (s) => methods.includes(s.method) || protectedCall(s),
         ).length;
     }
-    const declaration = declarationOf(p, dshVersion);
+    const declaration = declarationOf(p, dshVersion, {
+      exemptions: compatibilityExemptions,
+    });
     const rejectedPeers =
+      declaration?.rejected ??
       declaration?.raw?.peers?.filter(
         (r) => r.source === "peerDependencies" && !r.compatible,
-      ) || [];
-    if (rejectedPeers.length) {
+      ) ??
+      [];
+    const modern = declaration?.policy === "engines-first";
+    if (modern && rejectedPeers.length && declaration.exempted === true)
+      limitations.push(
+        "声明范围未满足，但存在此插件与目标DSH的精确版本豁免；加载许可不证明API或业务兼容",
+      );
+    if (
+      (rejectedPeers.length || declaration?.invalid) &&
+      declaration?.exempted !== true
+    ) {
       limitations.push(
-        "官方 peer 范围不匹配；未读取 exact-version 豁免，不能断言实际加载失败",
+        modern
+          ? declaration.invalid
+            ? declaration.invalid
+            : "声明范围不匹配；精确版本豁免" +
+              (declaration.exempted === null ? "未观测" : "未授予") +
+              "，未实测加载结果"
+          : "官方 peer 范围不匹配；未读取 exact-version 豁免，不能断言实际加载失败",
       );
       add({
         category: CATEGORY.DECLARED_INCOMPATIBLE,
@@ -439,18 +460,31 @@ export function buildVerdicts({
         method: null,
         location: null,
         severity: "degraded",
-        impact:
-          "官方 peer 声明不支持当前 DSH；请确认版本范围与精确版本豁免，API 存在不等于完整兼容",
-        basis: rejectedPeers
-          .map((r) => `${r.name}: ${r.range}，当前 ${dshVersion}`)
-          .join("; "),
+        impact: modern
+          ? "按目标DSH声明规则未获放行；须核对精确豁免及实际加载，API存在不等于完整兼容"
+          : "官方 peer 声明不支持当前 DSH；请确认版本范围与精确版本豁免，API 存在不等于完整兼容",
+        basis:
+          declaration.invalid ||
+          rejectedPeers
+            .map((r) => `${r.name}: ${r.range}，当前 ${dshVersion}`)
+            .join("; "),
         evidence: {
           runtimeVersion: dshVersion,
           peers: rejectedPeers,
-          exemption: "unobserved",
+          exemption: modern
+            ? declaration.exempted === null
+              ? "unobserved"
+              : "not-granted"
+            : "unobserved",
+          policy: declaration.policy ?? "legacy-peers",
+          invalid: declaration.invalid ?? null,
         },
         ruleSource: "declaration",
-        ruleRef: "package.peerDependencies",
+        ruleRef: declaration.invalid
+          ? "package.declaration"
+          : rejectedPeers.some((r) => r.source === "engines.dsh")
+            ? "package.engines.dsh"
+            : "package.peerDependencies",
       });
     }
     if (declaration?.claimsCompatible && findings.length) {

package/kernel/lib/version.mjs

@@ -29,7 +29,7 @@
  */
 
 /** 语义化版本。改动它会同时影响三个入口的 `--version` 与报告 JSON 的 `toolVersion`。 */
-export const TOOL_VERSION = '0.1.2';
+export const TOOL_VERSION = '0.1.3';
 
 /** 人类可读的一行，给 `--version` 用 */
 export function versionLine() {

package/kernel/rules/README.md

@@ -1,18 +1,18 @@
 # 严重度规则表与维护
 
-适用于0.1.2，判定算法与0.1.1一致。当前契约见 [Plan现行契约](../docs/Plan.md)，验证见 [自动统计](../docs/current-state.json)。本页后半保留2026-10-11旧提取器的规则依据；其中表格不是当前覆盖率，也不是当前运行时真值。
+适用于0.1.3；公开版本以registry和Plan发布记录为准。当前契约见 [Plan](../docs/Plan.md)，验证见 [自动统计](../docs/current-state.json)。后半保留2026-10-11旧提取器的依据，历史表不是当前覆盖率或运行时真值。
 
 ## 文件与运行时消费者
 
 | 文件 | 用途 |
 |---|---|
 | severity.json | 方法严重度/影响文案；引擎读取services下的方法规则，并与代码内默认档合用 |
-| dsh-api-catalog.json | 指定DSH版本生成的宿主/客户端契约目录；不证明当次运行时提供某方法 |
+| dsh-api-catalog.json / dsh-api-catalog-0.2.1-rc.2.json | 原0.2.0-rc.2（host91/client8）与新rc.2（host98/client8）契约快照；DSH≥0.2.1-rc.2选新目录，其余/未知选旧目录，CLI显式覆盖优先；未来版本未认证 |
 | usage-inventory.json | 带日期/版本/profile及完整性标记的AST库存快照；由coverage显式刷新，不保证与后续提取器重扫同数 |
 
 严重度由 `lib/verdict.mjs` 的确定性逻辑、缺失证据、方法规则及默认档共同决定，不由LLM决定。方法规则的severity/impact参与判定与输出，layer控制端别：方法自身优先、服务layer回退。summary/basis/evidence/knownGoneIn/needsReview等用于解释与维护；knownExtractionArtifacts是历史反例登记，不是自动过滤黑名单。
 
-0.2.1-rc.1宿主改为优先按engines.dsh判断；本版尚未同步该逻辑，已复现声明误报与漏报，规则/API目录也未更新为新版。新版接入验证不代表这些判定已适配，实施顺序见Plan后续。
+0.1.3按DSH目标分流声明：从0.2.1-rc.1起自有engines.dsh优先，缺失才回退全部官方peer；旧目标保留旧行为。非法/空范围、预发布和peer workspace别名均有回归；engines中的workspace不获放行。独立compatibility.json仅按插件/运行时精确版本豁免，非法字段不能靠豁免绕过；无效记录忽略并保留覆盖限制。
 
 ## 当前证据与严重度
 
@@ -21,15 +21,19 @@
 | 可映射loader条目FAILED/PENDING | fatal，影响依据measured；禁用、LOADING、无法映射不冒充同一事实 |
 | 宿主硬依赖且明确absent | 可判fatal；仅catalog缺项不冒充运行时缺失 |
 | 非硬依赖服务明确absent，或有足够方法证据 | 按规则/默认档给feature-dead或degraded；用户影响通常是inferred |
-| 官方peer范围冲突 | declared-incompatible，degraded及推断影响；不是实测加载失败；当前内核沿用0.2.0-rc.2，将engines.dsh作建议处理 |
+| 官方声明冲突或非法字段 | declared-incompatible，degraded及推断影响；不冒充实测加载失败；有效精确豁免可消除范围冲突，但保留限制且不证明业务成功 |
 | 未采样、读取失败、访问器未知、源码不完整 | 保留覆盖限制；不以省略键认定不存在 |
 
 方法规则中的degraded应有具体降级/回退依据；peer声明冲突的degraded是引擎针对声明风险的独立默认，不代表观察到回退。方法缺失但没有语义规则时会明确“影响面未知”。声明provide只是候选提供方，不证明已激活，不能遮住完整的present方法观测。
 
 宿主、客户端及shared调用点必须分开。客户端方法不能拿宿主probe判缺失；同名服务也不保证同一语义。对源码归属不确定的Context/别名保留suspected。certainty与impactBasis分别表达证据强度和影响是否实测。
 
+仓库独立业务队列将手审的功能调用区间内API风险与真实备注/收藏及侧栏保存/预览结果对照，保持业务、loader标签及预测隔离；不把整个插件的其它发现挪给本功能。正常/HTTP503故障组分别计分，限定样本不能改变生产报告中的certainty或impactBasis，也不是新增严重度规则的充分证据。复现见[Plan](../docs/Plan.md#52-日常检查与真实集成)。
+
 ## 如何更新
 
+ASAR读取器已修正数据起点为8+headerSize，并校验头长、边界、完整读取、UTF-8/JSON及归档SHA256。2026-10-18与Electron原生ASAR读取逐字节及首尾交叉校验后生成独立rc.2目录，旧目录未改。新host增加8项、移除invariants；subagents移除start/startContinuable/drainContinuableChildren/drainContinuableDescendants，增加startActivation/drainChildren/drainDescendants/waitForChildren；其它方法差异和源摘要见current-state。client方法集合未变。旧方法规则保留其原调用语义；不把新方法当同义重命名，也不只凭目录变化新增严重度，未知影响继续回退。
+
 先读调用点和目标版本的真实描述符/官方源码，再修改规则，添加行为回归并审查快照差异。原needsReview已在2026-10-15逐条复核，决定与证据保留于severity.json的needsReview.reviewed/evidence及 [Plan](../docs/Plan.md)。
 
 `tools/coverage.mjs` 从AST调用点按host/client/shared分端计数，规则命中与默认影响、类别发现分列。**knownExtractionArtifacts只保留历史反例，不过滤现在的真实调用**；纯客户端规则不用于宿主同名方法。probe须为现代格式并绑定本目标/版本/时间，不能借别的profile的面。写库存要求显式或观测到的合法semver版本，非法版本退出3且不覆盖旧文件。