dsh-plugin-compat-check 0.1.2 → 0.1.4

package/README.md

@@ -1,16 +1,22 @@
 # 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.4**，支持 Node `^22.19.0 || >=24`。公开版本及 latest 以 [npm](https://www.npmjs.com/package/dsh-plugin-compat-check) 为准，发布和验收记录见 [Plan](https://github.com/lcy0121/dsh-plugin-compat-check/blob/main/docs/Plan.md)。
 
 ```bash
-dsh plugin --profile <profile> add dsh-plugin-compat-check@0.1.2
+dsh plugin --profile <profile> add dsh-plugin-compat-check
 ```
 
+DSH 0.2.1-rc.2 入口：**更多 → 设置 → 内置插件 → 兼容性**。agent 可调用 `compat_check`；请选择实际 profile，不默认使用 desktop。
+
+0.1.4 补充必需 inject 未观测时的激活前提说明，修正 Origin 校验以比较协议、主机和有效端口（保留本机无 Origin 调用），并提供 `repository.directory=plugin`。仓库另增强了进程回收、Chrome 启动诊断及 Linux CI；浏览器开发工具不随 npm 插件交付。市场显示名与 1024 Store 采集问题须由相应上游修复，不因本包升级自动解决。
+
 ## 从源码构建安装
 
-本仓库根为私有开发工作区，不声明DSH bundle。不要把根目录GitHub安装规格当成plugin子目录的安装方式。在仓库根运行 `npm ci --ignore-scripts`，然后：
+仓库根是 private 开发工作区，不是可激活的插件包。先在根运行 `npm ci --ignore-scripts`，然后：
 
 ```bash
 cd plugin
@@ -18,26 +24,20 @@ npm pack --pack-destination <已存在的绝对输出目录>
 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。
+prepack 同步权威 skill/报告契约，暂存共享 kernel 和 MIT LICENSE，postpack 清理 kernel。运行时依赖固定为 `@babel/parser@7.29.9`、`semver@7.7.3`。不要将根 GitHub spec、裸 `plugin/` 复制或源码 file 安装等同完整 tgz。
 
-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。
-
-0.1.2修正发布状态文案并统一版本标记；判定算法与0.1.1一致。规则/API目录仍基于0.2.0-rc.2，不把新版接入测试当作全面适配。
+npm 产物**没有 CLI bin、安装检查 shell 或 probe 入口**，不支持 `npx dsh-plugin-compat-check`，本面板不做安装前检查。这些入口及 `--issue-report` 默认脱敏 Markdown 导出从[仓库](https://github.com/lcy0121/dsh-plugin-compat-check#readme)使用。显式安装检查会联网、启动宿主并执行目标插件；临时 profile 不是 OS 沙箱。
 
 ## 判定与边界
 
-当前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宿主已优先按该字段判断，声明有误报/漏报风险，应核对实际宿主结果；本补丁未改判定算法。
-
-转述时保留 `impactBasis=inferred`（影响为推断，非实测）、coverage限制和vacuous结果。API发现通常有file:line，loader/元数据发现可能没有源码位置。客户端服务列为待界面核验项；独立浏览器开发工具不属于本面板，且不验证业务交互。
-
-插件体检不安装包、不调用外部命令或联网；会启动分析worker，并默认写自己的schema2基线：`$DSH_HOME/dsh-plugin-compat-check/baseline.<profile>.<path-hash>.<mode>.json`。模式分离、锁内比较、原子替换；源码扫描不完整不推进基线。默认不输出共享loader诊断；诊断需显式私有DSC_OUT_DIR。若需完全禁止基线读写，请使用仓库CLI的 `--no-baseline`。
-
-0.1.1的分阶段证据包括默认回归、独立tarball执行及2026-10-15的真实DSH0.2.0-rc.2/macOS arm64验收：工具、skill、面板、详情角标、基线及Chrome正负向对照。2026-10-16另在Ubuntu24.04.5 arm64 VM通过Node22.19.0/24.21.0、真实DSH/tgz/HTTP及资源边界验收。同日提交38fa4a0的[GitHub Actions](https://github.com/lcy0121/dsh-plugin-compat-check/actions/runs/38892527900)在Ubuntu x64通过Node22/24资源检查及联合18项检查（4项真实DSH、1项冻结pnpm安装、13项离线）。后续main提交49403d7的[CI](https://github.com/lcy0121/dsh-plugin-compat-check/actions/runs/38923778251)再次通过Node22/24发布前与资源检查、Linux真实集成。Windows按约定待验收；skill正文修订后的仓库验证不冒充旧现场正文验收。具体测试数量与证据见仓库docs/current-state.json、docs/Plan.md；不把历史测试数字作为当前版本的完整功能认证。
-
-报告结构由仓库lib/contracts.mjs校验：HTTP envelope.report与compat_check.report均保留完整发现、覆盖、观测和基线；工具原summary/text字段保留。新面板拒绝损坏或不支持版本的负载，提示刷新和对齐版本。旧probe保持未绑定警告，旧schema1基线中性重建；内核现支持有界常量属性、函数参数/返回值、包内模块别名及透明Proxy；未知动态行为与超预算继续显示覆盖限制。具体字段与错误码见 [Plan契约记录](https://github.com/lcy0121/dsh-plugin-compat-check/blob/main/docs/Plan.md#23-报告结构与兼容策略)。
+- 当前 profile 在宿主进程内采样服务描述符，不执行 getter，纳入可靠映射且启用的 loader FAILED/PENDING。其它 profile 仅用静态证据，不借用当前宿主服务；未知、未采样或省略键不等于缺失。
+- Babel AST 扫描不执行目标源码，分析运行在有时间/内存上限的 worker 中；有界包内值流支持部分别名、参数/返回值和透明 Proxy，动态行为仍有限。必需 inject 的激活障碍与方法失效分别判断。
+- 转述保留 `certainty`、`impactBasis`、`coverage` 和 `vacuous`。API 发现通常有 `file:line`，loader/声明事实可能无位置；声明放行、激活成功、条目到货和 ok 均不证明业务正常，客户端功能须另验收。
+- 从 DSH 0.2.1-rc.1 起优先自有 `engines.dsh`，缺失才回退官方 peer，旧目标保留旧规则。声明冲突/非法字段是推断风险，不冒充实际加载失败。只读独立 `compatibility.json`，按插件名、插件精确版本、DSH 精确版本匹配豁免；无效/不可读/超64KiB保留限制，不自动授予，非法字段不可豁免。
+- DSH≥0.2.1-rc.2 用新目录（host98/client8），其余/未知用旧0.2.0-rc.2目录（host91/client8）；未来 DSH 未认证。rc.2 的真实 Chrome 验收覆盖导航、报告渲染、禁用后路由移除及重启用后恢复/标签唯一；不认证所有插件业务。
+- 体检不装包、不调用外部命令或联网；默认写自身 schema2 基线：`$DSH_HOME/dsh-plugin-compat-check/baseline.<profile>.<path-hash>.<mode>.json`。模式隔离、锁内比较、原子替换，不完整扫描不推进。完全禁基线读写须用仓库 CLI 的 `--no-baseline`。
+- HTTP envelope.report 和 `compat_check.report` 保留完整发现、覆盖、观测和基线，原 summary/text 保留；新面板拒绝损坏或不支持版本的负载。旧 probe 提示未绑定，旧 schema1 基线中性重建，不兼容报告变更须升 schema。
 
-## License
+限定 macOS/Linux、真实 DSH/Chrome、独立 tgz 和工程验收的逐次版本及证据见 [current-state.json](https://github.com/lcy0121/dsh-plugin-compat-check/blob/main/docs/current-state.json)。Windows 待真实验收。独立业务/模型度量属于仓库开发工具，不随 npm 分发、不进入产品判定，默认测试/CI不调用模型；固定样本不是生态准确率或完整模型质量认证。
 
-MIT。源码、问题反馈与仓库文档：[GitHub](https://github.com/lcy0121/dsh-plugin-compat-check)。
+[完整契约与复现](https://github.com/lcy0121/dsh-plugin-compat-check/blob/main/docs/Plan.md#2-现行判定与集成契约) · [源码及问题反馈](https://github.com/lcy0121/dsh-plugin-compat-check) · [MIT License](https://github.com/lcy0121/dsh-plugin-compat-check/blob/main/LICENSE)

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;
@@ -976,8 +1000,12 @@ function isTrustedRequest(req) {
     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);
+    if (!hostOk) return false;
+    const protocol = req.socket?.encrypted === true ? 'https:' : 'http:';
+    const expectedOrigin = new URL(`${protocol}//${host}`).origin;
+    if (!origin) return true;
+    if ( !/^https?:\/\/(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/i.test(origin)) return false;
+    return new URL(origin).origin === expectedOrigin;
   } catch {
     return false;
   }
@@ -1076,7 +1104,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 +1178,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 +1289,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 +1303,7 @@ function registerSkill(ctx) {
           }),
         }));
         log(`SKILL registered: ${SKILL_NAME} <- ${skill.file}`);
+        return dispose;
       } catch (error) {
         log(`SKILL registration failed: ${errText(error)}`);
       }
@@ -1289,6 +1319,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 +1374,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 +1403,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 +1464,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 +1485,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 +1503,7 @@ export function apply(ctx) {
     //      的清理顺手取消掉了 —— 启动自检从未运行、且**没有任何报错**。
     //      一个"看起来做了其实没做"的定时器，比没有更糟。
     state.runAutoCheck = () => {
+      if(state.disposed)return;
       if (state.autoCheckStarted) return;   // 幂等：只跑一次
       state.autoCheckStarted = true;
       try {
@@ -1503,12 +1542,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),