dsh-plugin-compat-check 0.1.4 → 0.1.5

package/index.js

@@ -21,14 +21,17 @@
 //   ${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, realpathSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, realpathSync, promises as fsPromises } 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';
+import { createHash } from 'node:crypto';
 
 import {loaderObservations,privateDiagnostic} from './lib/host-resources.js';
-import {assertEnvelope,failureEnvelope} from './lib/report-contract.js';
+import {assertEnvelope,failureEnvelope,catalogLines} from './lib/report-contract.js';
+import {nextSteps} from './lib/finding-guidance.js';
+import {createUpgradeFailure as upgradeFailure, SUPPORTED_PREVIEW_VERSIONS} from './lib/upgrade-contract.js';
 
 export const name = 'dsh-plugin-compat-check';
 
@@ -786,33 +789,67 @@ function resolveNodeModules(requestedProfile = null) {
 }
 
 /**
- * 把结论交给面板 —— **F2 的缓存策略集中在这里**。
- *
- * ## 策略：stale-while-revalidate（先给旧的，后台再刷）
- *
- * 为什么不是"到点就重算"：一次体检 0.5–1.5 秒（desktop profile 21 个插件）。
- * 让面板的请求**等**这 1.5 秒，用户看到的是转圈；而结论晚 1.5 秒到完全无所谓 ——
- * 这份数据说的是"你装的插件跟这版 DSH 兼不兼容"，它不是秒级指标。
- * 所以：有缓存就先给，同时在后台刷新的。**响应速度与正确性都不牺牲**。
- *
- * 三种情况：
- *   - `?refresh=1` 或没有缓存 → **同步算**（用户明确要新的，或者根本没有旧的）
- *   - 缓存在有效期内         → 直接给
- *   - 缓存过期               → 先给旧的，并触发一次后台刷新（同一时刻只跑一个）
- *
- * 并发安全：`state.computing` 保存"正在跑的那一个 promise"，所以十个面板请求
- * 同时到达也只会算一次 —— 否则它们会各自算一遍，白烧 1.5 秒 × 10。
+ * Ordinary report cache is scoped to the canonical profile and DSH context.
+ * Verified loader/manager events trigger coalesced identity checks; a bounded
+ * worker watchdog also notices same-path source and judgment-input changes.
+ * Valid reports remain visible while a replacement generation runs. Cold and
+ * forced requests await a current generation; failed refreshes retain the
+ * previous report with explicit stale/error metadata. The TTL still refreshes
+ * time-dependent observations even when the sampled identity is unchanged.
  */
 async function serveReport(state, ctx, force, options = {}) {
   if(state.disposed)return failureEnvelope('Plugin generation disposed / 已卸载');
+  const kernel=resolveKernelDir(),nm=resolveNodeModules(options.profile || null);
+  if(!kernel)return failureEnvelope('找不到判定内核');
+  if(!nm.dir){
+    // Keep computeReport's version identity on target-resolution failures.
+    const out=await computeReport(state,ctx,options);
+    return failureEnvelope(out.error,out);
+  }
+  const canonical=await fsPromises.realpath(nm.dir),version=resolveDshVersion();
+  const context={nodeModules:canonical,observationProfile:path.resolve(nm.dir),kernel:await fsPromises.realpath(kernel),dshVersion:version,probe:process.env.DSC_PROBE_REPORT || null};
   if(!state.reportService){
-    const kernel=resolveKernelDir();
-    if(!kernel)return failureEnvelope('找不到判定内核');
-    const {ReportService}=await import(pathToFileURL(join(kernel,'lib','report-service.mjs')).href);
-    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 [{ReportService},{reportIdentity},{catalogPathFor},{sampleServices}]=await Promise.all([
+      import(pathToFileURL(join(kernel,'lib','report-service.mjs')).href),
+      import(pathToFileURL(join(kernel,'lib','report-identity.mjs')).href),
+      import(pathToFileURL(join(kernel,'lib','catalog.mjs')).href),
+      import(pathToFileURL(join(kernel,'lib','observation.mjs')).href),
+    ]);
+    if(state.disposed)return failureEnvelope('Plugin generation disposed / 已卸载');
+    if(!state.reportService)state.reportService=new ReportService(async (options,guard)=>{
+      const out=await computeReport(state,ctx,{...options,_cacheGuard:guard});
+      return out.ok?assertEnvelope(out):failureEnvelope(out.error,out);
+    },{ttlMs:state.cacheTtlMs,watchMs:state.cacheWatchMs,identity:async options=>{
+      const scope=options._cacheContext,current=resolveNodeModules(),currentVersion=resolveDshVersion();
+      const active=current.dir?await fsPromises.realpath(current.dir):null;
+      const requestedTarget=await fsPromises.realpath(options._nodeModules.dir);
+      const identity=await reportIdentity({nodeModules:scope.nodeModules,context:{...scope,currentVersion,active,requestedTarget,probe:process.env.DSC_PROBE_REPORT || null},files:[join(scope.kernel,'rules','severity.json'),catalogPathFor(scope.kernel,currentVersion),process.env.DSC_PROBE_REPORT,join(path.dirname(options._nodeModules.dir),'compatibility.json')]});
+      const sameHost=active===scope.nodeModules;
+      const itemListing=sameHost?await (async()=>{try{const listing=await ctx.get?.('pluginManager',false)?.list?.();return (Array.isArray(listing)?listing:listing?.items||listing?.plugins||[]).map(i=>({id:i.id??i.entryId??i.slotId,packageName:i.packageName??i.package??i.name}));}catch{return [];}})():[];
+      const loader=sameHost?loaderObservations(ctx,identity.manifests,itemListing):null;
+      const observation=sameHost?sampleServices(ctx,[...identity.services,...(options._cacheInputs.services || [])],{profileId:scope.nodeModules,dshVersion:currentVersion}):null;
+      // Sampling timestamps are evidence, not a changing service identity.
+      return JSON.stringify([identity.digest,loader,observation?.root || null]);
+    }});
   }
-  const key=options.profile?`profile:${options.profile}`:'current';
-  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||{});
+  if(!state.cacheEventDisposers && typeof ctx.on==='function'){
+    state.cacheEventDisposers=[];
+    // Verified in the bundled loader and plugin-manager emit sites; the
+    // bounded watchdog also catches source edits and hosts without ctx.on.
+    for(const event of ['plugin-manager/changed','plugin-manager/install-state','loader/entry-init','loader/partial-dispose','loader/volatile-update']){
+      try{const off=ctx.on(event,()=>state.reportService?.notify());if(typeof off==='function')state.cacheEventDisposers.push(off);}catch{}
+    }
+  }
+  const key=JSON.stringify(context);
+  state.reportInputs ||= new Map();
+  if(!state.reportInputs.has(key))state.reportInputs.set(key,{services:[]});
+  const inputs=state.reportInputs.get(key);
+  // Canonicalize cache identity only: preserve the requested path for the
+  // existing exact probe/profile binding and the report's business target.
+  const out=await state.reportService.get(key,{...options,_cacheContext:context,_cacheInputs:inputs,_nodeModules:{dir:nm.dir,why:nm.why}},force);
+  if(state.disposed)return failureEnvelope('Plugin generation disposed / 已卸载');
+  if (!out?.ok) return failureEnvelope(out?.error,out||{});
+  return attachFindingReviews(state,assertEnvelope(out),key,kernel);
 }
 
 /**
@@ -860,6 +897,7 @@ async function computeReport(state, ctx, options = {}) {
   };
   try {
     const kernel = resolveKernelDir();
+    if(options._cacheContext && (options._cacheContext.dshVersion!==resolveDshVersion() || options._cacheContext.probe!==(process.env.DSC_PROBE_REPORT || null) || options._cacheContext.nodeModules!==(await fsPromises.realpath(options._nodeModules.dir)) || options._cacheContext.kernel!==(kernel && await fsPromises.realpath(kernel))))return failureEnvelope('报告上下文已变化，等待目标报告刷新');
     out.kernelDir = kernel;
     // 版本要**尽早**拿到：连"找不到内核"这条错误路径上，用户也需要知道
     // 是哪一版工具报的这个错。`version.mjs` 只在有内核时才读得到 ——
@@ -877,7 +915,7 @@ async function computeReport(state, ctx, options = {}) {
         + '插件形态下它们是同仓库的相邻目录；发布形态请设 DSC_KERNEL。';
       return out;
     }
-    const nm = resolveNodeModules(options.profile || null);
+    const nm = options._nodeModules || resolveNodeModules(options.profile || null);
     out.nodeModules = nm.dir;
     out.nodeModulesWhy = nm.why;
     if (!nm.dir) {
@@ -888,11 +926,12 @@ 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 {catalogPathFor}=await import(pathToFileURL(join(kernel,'lib','catalog.mjs')).href);
-    const catalogPath = catalogPathFor(kernel,resolveDshVersion());
+    const {loadCatalog}=await import(pathToFileURL(join(kernel,'lib','catalog.mjs')).href);
+    const {file:catalogPath,catalog,evidence:catalogEvidence} = loadCatalog(kernel,resolveDshVersion());
     const rulesPath = join(kernel, 'rules', 'severity.json');
-    const catalog = JSON.parse(readFileSync(catalogPath, 'utf8'));
-    const rules = JSON.parse(readFileSync(rulesPath, 'utf8'));
+    const rulesBytes = readFileSync(rulesPath);
+    const rules = JSON.parse(rulesBytes);
+    out.analysisIdentity={rulesSha256:createHash('sha256').update(rulesBytes).digest('hex'),catalogSha256:catalogEvidence.sha256};
 
     // 运行时面：宿主半边**自己就在进程里**，所以它能拿到比探针更准的东西。
     // 第一版先读探针报告（如果外层给了路径），没有就退回目录 —— 并如实标注。
@@ -911,9 +950,10 @@ async function computeReport(state, ctx, options = {}) {
 
     const extracted = await extractInWorker(nm.dir, { catalog });
     if(state.disposed)return failureEnvelope('Plugin generation disposed / 已卸载');
+    if(options._cacheInputs)options._cacheInputs.services=extracted.report.services;
     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);
+    const sameHost=currentTarget.dir&&(await fsPromises.realpath(currentTarget.dir))===(await fsPromises.realpath(nm.dir));
     if(!hostSurface && sameHost){
       hostSurface=sampleServices(ctx,extracted.report.services,{profileId:nm.dir,dshVersion:resolveDshVersion()});
       surfaceWhy='当前宿主进程内采集的服务结构；未采集或读取失败不等于缺失';
@@ -940,7 +980,7 @@ async function computeReport(state, ctx, options = {}) {
     // ── C4：基线差分 ──
     // 用**与 CLI 完全相同**的 lib/baseline.mjs。面板说"变差了"而命令行说"没变"
     // 这种分叉在结构上就不可能发生。
-    let baseline = null;
+    let baseline = null, finalizeBaseline = null;
     try {
       const { snapshotForBaseline, diffAgainstBaseline, badgeFor } =
         await import(pathToFileURL(join(kernel, 'lib', 'baseline.mjs')).href);
@@ -949,7 +989,8 @@ async function computeReport(state, ctx, options = {}) {
       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});
+      finalizeBaseline=()=>store.baselineTransaction(bfile,snap,{advance:extracted.report.scanComplete});
+      if(!options._cacheGuard)baseline=finalizeBaseline();
     } catch (error) {
       baseline = { error: errText(error), note: '基线差分没算成（不影响本次结论）' };
     }
@@ -980,8 +1021,17 @@ async function computeReport(state, ctx, options = {}) {
     }
 
     const {toJSON}=await import(pathToFileURL(join(kernel,'lib','report.mjs')).href);
+    const {renderIssueReport}=await import(pathToFileURL(join(kernel,'lib','issue-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}});
+    const canonical=toJSON({error:null,extract:extracted,verdict,entryStates:loaderState.rows,baseline,catalog:catalogEvidence,inputs:{nodeModules:nm.dir,hasRuntimeSurface:verdict.observation.usable,catalog:catalogPath,rules:rulesPath}});
+    if(options._cacheGuard && finalizeBaseline)options._cacheGuard.commit(()=>{
+      baseline=finalizeBaseline();
+      canonical.baseline=baseline;
+      out.baseline=baseline;
+      out.report.baseline=baseline;
+      out.issueReport=renderIssueReport(canonical);
+    });
+    out.issueReport=renderIssueReport(canonical);
     out.baseline = canonical.baseline;
     out.dshVersion = canonical.dshVersion;
     out.exitCode = canonical.exitCode;
@@ -1034,8 +1084,9 @@ function renderForModel(compat) {
     const L = [];
     const s = r.summary || {};
     L.push(`结论：可用 ${s.ok || 0}　部分可用 ${s.partial || 0}　不兼容 ${s.broken || 0}`
-      + (s.vacuousOk ? `（其中 ${s.vacuousOk} 个「可用」是空洞的：该插件没有用过任何 DSH 服务，因此没有可检查的东西）` : ''));
+      + (s.vacuousOk ? `（其中 ${s.vacuousOk} 个「可用」没有已验证调用，不等于业务通过）` : ''));
     L.push(`工具版本：${compat.toolVersion || '未知'}`);
+    L.push(...catalogLines(r.catalog));
     for(const note of r.observation?.notes||[])L.push(`采样说明：${note}`);
     if(s.limited)L.push(`证据覆盖有限：${s.limited} 个插件尚有未验证部分`);
     L.push(`体检对象：${compat.nodeModules}（${compat.nodeModulesWhy}）`);
@@ -1052,19 +1103,22 @@ function renderForModel(compat) {
     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 ? '　[空洞的结论：无可检查对象]' : ''}`);
+      L.push(`${label}  ${name}@${p.version || '?'}${p.vacuous ? '　[无已验证调用]' : ''}`);
+      if(p.coverage){L.push(`    证据覆盖：${p.coverage.status==='complete'?'完整':'有限'}；已验证调用 ${p.coverage.verifiedCalls}`);for(const note of p.coverage.limitations)L.push(`      覆盖限制：${note}`);}
       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': '声明与实测不符',
+          'unprovided-dependency': '依赖服务待确认', 'declaration-mismatch': '声明与实测不符',
+          'client-entry-missing': '客户端入口不可交付', 'host-entry-inactive': '宿主条目未激活',
       'declared-incompatible':'版本声明不支持',
         }[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.impactBasis==='inferred'?'（推断，非实测）':''}：${f.impact}`);
+        L.push(`    ${sev} / ${cat}${f.certainty === 'certain' ? ' [确定]' : ' [疑似]'}  ${api}  @ ${loc}`);
+        if (f.impact) L.push(`      影响${f.impactBasis==='measured'?'（实测）':f.impactBasis==='inferred'?'（推断，非实测）':'（依据未提供）'}：${f.impact}`);
         if(f.basis)L.push(`      依据：${f.basis}`);
+        for(const step of nextSteps(f))L.push(`      下一步：${step}`);
       }
       const cs = p.clientSide || [];
       if (cs.length) L.push(`    客户端半边（命令行测不到，需界面验证）：${cs.map((c) => c.service).join('、')}`);
@@ -1074,11 +1128,14 @@ function renderForModel(compat) {
     }
 
     L.push('');
-    L.push('读这个结果时注意两点：');
+    L.push('确定（certain）表示当前证据足以支持该条发现，可来自明确静态事实或合格运行时观测；疑似（suspected）表示当前证据不足以确定该条发现。');
+    L.push('impactBasis=measured/inferred 分别表示影响有对应实测依据/影响由证据推断；确定发现不等于影响已实测。未观测不等于缺失。');
+    L.push('没有已验证调用仍可能存在服务依赖或客户端功能；调用核验和覆盖完整均不等于业务验收通过。');
+    L.push('下一步是核实建议；本工具不会自动安装、升级或修改配置与源码。');
+    L.push('读这个结果时注意：');
     L.push('  1) 「可用」不等于"功能验证过"。它只说明本轮未发现冲突；请同时看证据覆盖与未验证项。'
       + '插件仍然可能因为自身逻辑、配置或第三方依赖而出问题。');
-    L.push('  2) 「客户端半边」的那些服务默认报告不验证 —— 它们活在浏览器里，'
-      + '只能靠"界面上有没有出现该插件的 UI"来验证。别把"没报错"当成"没问题"。');
+    L.push('  2) 客户端功能需在浏览器实际操作并核验结果；元素出现和没有报错均不等于业务成功。');
     return L.join('\n');
   } catch (error) {
     return `渲染结论时出错（工具的问题）：${errText(error)}`;
@@ -1086,12 +1143,163 @@ function renderForModel(compat) {
 }
 
 /** 工具的服务集合：`tools`；`agents` 用来把相对路径解析到会话工作目录。 */
+/** Static version comparisons never enter the ordinary report cache or baseline path. */
+function unavailableUpgrade(error, options = {}) {
+  let toolVersion = 'unknown';
+  try { toolVersion = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version; } catch {}
+  return upgradeFailure(error, {toolVersion, currentVersion:resolveDshVersion(), targetVersion:options.targetVersion, ...options});
+}
+
+async function serveUpgradePreview(state, options = {}) {
+  const currentVersion = resolveDshVersion(), targetVersion = options.targetVersion || null;
+  const failure = error => unavailableUpgrade(error,{currentVersion,targetVersion});
+  try {
+    if (state.disposed) return failure('Plugin generation disposed / 已卸载');
+    if (options.currentVersion && options.currentVersion !== currentVersion)
+      return failure('当前 DSH 版本已变化，请刷新普通报告后重新预检');
+    if (options.invalidRequest) return failure(options.invalidRequest);
+    if (!SUPPORTED_PREVIEW_VERSIONS.includes(currentVersion) || !SUPPORTED_PREVIEW_VERSIONS.includes(targetVersion))
+      return unavailableUpgrade('版本未认证：仅支持有明确 API 目录的精确版本 '+SUPPORTED_PREVIEW_VERSIONS.join('、'),{currentVersion,targetVersion,status:'unsupported-version'});
+    const kernel = resolveKernelDir();
+    if (!kernel) return failure('找不到升级预检内核');
+    const engine = await import(pathToFileURL(join(kernel, 'lib/upgrade-preview.mjs')).href);
+    if (state.disposed) return failure('Plugin generation disposed / 已卸载');
+    const nm = resolveNodeModules(options.profile || null);
+    const canonical = nm.dir && await fsPromises.realpath(nm.dir);
+    if (state.disposed) return failure('Plugin generation disposed / 已卸载');
+    const key = JSON.stringify([canonical, currentVersion, targetVersion]);
+    if (state.upgradeFlight && state.upgradeFlight.key !== key)
+      return failure('另一目标的升级预检正在运行，请稍后重试');
+    let flight = state.upgradeFlight;
+    if (!flight) {
+      const controller = new AbortController();
+      flight = {key, controller, promise: engine.runUpgradePreview({nm:nm.dir, currentVersion, targetVersion},{signal:controller.signal})};
+      state.upgradeFlight = flight;
+    }
+    try {
+      const result = await flight.promise;
+      if (!state.disposed) return result;
+      return failure([result.ok ? null : result.error, 'Plugin generation disposed / 已卸载'].filter(Boolean).join('；'));
+    } finally {
+      if (state.upgradeFlight === flight) state.upgradeFlight = null;
+    }
+  } catch (error) {return failure(errText(error));}
+}
+
+async function upgradeToolResult(state, options) {
+  let preview, text;
+  try {
+    const kernel = resolveKernelDir();
+    if (!kernel) throw Error('找不到升级预检内核');
+    const {renderUpgradePreview} = await import(pathToFileURL(join(kernel, 'lib/upgrade-preview.mjs')).href);
+    preview = await serveUpgradePreview(state, options);
+    text = renderUpgradePreview(preview);
+  } catch (error) {
+    preview = unavailableUpgrade(errText(error),{targetVersion:options.targetVersion});
+    text = '升级预检无法比较：'+preview.error+'；静态预测不等于目标版本业务通过。';
+  }
+  return {schemaVersion:1,kind:'plugin-compat-check/tool-result',ok:preview.ok,error:preview.error,exitCode:preview.exitCode,toolVersion:preview.toolVersion,
+    report:null,baseline:null,cache:null,nodeModules:'',hasRuntimeSurface:false,
+    summary:preview.ok?`静态升级预检：新增 ${preview.summary.added} / 变重 ${preview.summary.worsened}；不等于目标版本业务通过`:'升级预检无法比较',
+    text,upgradePreview:preview};
+}
+
+function registerUpgradeRoute(ctx, state) {
+  if (typeof ctx.inject !== 'function') return;
+  ctx.inject(['webServer'], scope => {
+    try {
+      return scope.webServer.register({name:'dsh-plugin-compat-check/upgrade-preview',kind:'exact',path:'/plugin-compat-check/upgrade-preview',handler:async(req,res)=>{
+        const send=(status,body)=>{res.writeHead(status,{'content-type':'application/json; charset=utf-8','cache-control':'no-store'});res.end(JSON.stringify(body));};
+        if (!isTrustedRequest(req)) return send(403,{error:'refused: untrusted request'});
+        if (req.method !== 'GET') return send(405,{error:'升级预检仅支持 GET'});
+        try {
+          const url=new URL(req.url||'/', 'http://127.0.0.1');
+          const invalid=(req.url||'').length>2048 || [...url.searchParams.keys()].some(k=>!['targetVersion','currentVersion'].includes(k));
+          const out=await serveUpgradePreview(state,{targetVersion:url.searchParams.get('targetVersion'),currentVersion:url.searchParams.get('currentVersion'),invalidRequest:invalid?'升级预检请求参数无效':null});
+          send(200,out);
+        } catch (error) {send(500,{error:'升级预检无法完成，请在本机核对插件与宿主版本'});}
+      }});
+    } catch (error) {log('Upgrade preview route registration failed: '+errText(error));}
+  });
+}
+
+/** Human review is an independently loaded sidecar, never a verdict override. */
+async function attachFindingReviews(state,out,key,kernel) {
+  try {
+    const store=await import(pathToFileURL(join(kernel,'lib','finding-review-store.mjs')).href);
+    const inputIdentity=state.reportService.identityForReport(key,out.report);
+    if(typeof inputIdentity!=='string')throw new Error('当前报告缺少可绑定的分析输入身份');
+    const sourceIdentity=createHash('sha256').update(inputIdentity).digest('hex');
+    const context=await store.reviewContext(out.report,{nodeModules:out.nodeModules,sourceIdentity,rulesIdentity:out.analysisIdentity?.rulesSha256,catalogIdentity:out.report.catalog?.sha256,toolVersion:out.toolVersion});
+    const reviews=await store.readReviews(context);
+    if(state.disposed)return failureEnvelope('Plugin generation disposed / 已卸载',out);
+    state.reviewTargets ||= new Map();
+    state.reviewTargets.set(context.contextToken,{context,key,report:out.report,nodeModules:out.nodeModules,store});
+    while(state.reviewTargets.size>32)state.reviewTargets.delete(state.reviewTargets.keys().next().value);
+    return {...out,reviews};
+  } catch(error) {
+    return {...out,reviews:{schemaVersion:1,contextToken:null,revision:null,items:[],history:[],error:'人工处置记录不可用：'+errText(error)}};
+  }
+}
+
+function readReviewRequest(req,signal) {
+  return new Promise((resolve,reject)=>{
+    const maxBytes=16384,chunks=[];let bytes=0,settled=false;
+    const finish=(error,value)=>{
+      if(settled)return;settled=true;clearTimeout(timer);
+      req.removeListener('data',data);req.removeListener('end',end);req.removeListener('error',errorEvent);req.removeListener('aborted',abort);
+      signal.removeEventListener('abort',abort);
+      if(error){req.pause?.();reject(error);}else resolve(value);
+    };
+    const invalid=(message,status)=>Object.assign(new Error(message),{status});
+    const data=chunk=>{const buffer=Buffer.from(chunk);bytes+=buffer.length;if(bytes>maxBytes)return finish(invalid('人工处置请求超过大小限制',413));chunks.push(buffer);};
+    const end=()=>{try{finish(null,JSON.parse(new TextDecoder('utf-8',{fatal:true}).decode(Buffer.concat(chunks))));}catch{finish(invalid('人工处置请求不是有效JSON',400));}};
+    const errorEvent=()=>finish(invalid('人工处置请求读取失败',400));
+    const abort=()=>finish(invalid('人工处置请求已取消或插件已卸载',409));
+    const timer=setTimeout(()=>finish(invalid('人工处置请求读取超时',408)),5000);timer.unref?.();
+    req.on('data',data);req.once('end',end);req.once('error',errorEvent);req.once('aborted',abort);signal.addEventListener('abort',abort,{once:true});
+    if(signal.aborted)abort();
+    const length=req.headers?.['content-length'];
+    if(length!==undefined&&(!/^\d+$/.test(String(length))||Number(length)>maxBytes))finish(invalid('人工处置请求超过大小限制',413));
+  });
+}
+function registerFindingReviewRoute(ctx,state) {
+  if(typeof ctx.inject!=='function')return;
+  ctx.inject(['webServer'],scope=>{
+    try{return scope.webServer.register({name:'dsh-plugin-compat-check/reviews',kind:'exact',path:'/plugin-compat-check/reviews',handler:async(req,res)=>{
+      const send=(status,body)=>{res.writeHead(status,{'content-type':'application/json; charset=utf-8','cache-control':'no-store'});res.end(JSON.stringify(body));};
+      if(!isTrustedRequest(req))return send(403,{ok:false,error:'refused: untrusted request'});
+      if(req.method!=='POST')return send(405,{ok:false,error:'人工处置仅支持POST'});
+      if(!/^application\/json(?:\s*;|$)/i.test(req.headers?.['content-type']||''))return send(415,{ok:false,error:'人工处置需要application/json'});
+      if(state.disposed)return send(409,{ok:false,error:'Plugin generation disposed / 已卸载'});
+      const controller=new AbortController();state.reviewRequests ||= new Set();state.reviewRequests.add(controller);
+      try {
+        const body=await readReviewRequest(req,controller.signal);
+        const target=state.reviewTargets?.get(body?.contextToken);
+        if(!target) return send(409,{ok:false,error:'报告已变化，请重新检查后核实此发现'});
+        const canCommit=async()=>{
+          if(state.disposed||controller.signal.aborted)return false;
+          const current=resolveNodeModules();
+          if(!current.dir||path.resolve(current.dir)!==path.resolve(target.nodeModules))return false;
+          return state.reportService.isCurrent(target.key,target.report);
+        };
+        if(!await canCommit())return send(409,{ok:false,error:'体检输入已变化，请重新检查后核实此发现'});
+        const reviews=await target.store.saveReview(target.context,body,{canCommit});
+        send(200,{ok:true,reviews});
+      } catch(error) {
+        const status=error.status||(error.code==='REVIEW_STALE'||error.code==='REVIEW_BUSY'?409:error.code==='REVIEW_STORAGE'?422:400);
+        send(status,{ok:false,error:errText(error)});
+      } finally {state.reviewRequests.delete(controller);}
+    }});}catch(error){log('Review route registration failed: '+errText(error));}
+  });
+}
+
 const TOOL_SERVICES = ['tools', 'agents'];
 
 function toolResult(compat,text){
  const s=compat.report?.summary||{};
- return {schemaVersion:1,kind:'plugin-compat-check/tool-result',ok:compat.ok,error:compat.error,toolVersion:compat.toolVersion,exitCode:compat.exitCode,report:compat.report,baseline:compat.baseline,cache:compat.cache||null,
- summary:compat.ok?`可用 ${s.ok||0} / 部分可用 ${s.partial||0} / 不兼容 ${s.broken||0}`:'无法判定',nodeModules:compat.nodeModules||'',hasRuntimeSurface:!!compat.report?.hasRuntimeSurface,text};
+ return {schemaVersion:1,kind:'plugin-compat-check/tool-result',ok:compat.ok,error:compat.error,toolVersion:compat.toolVersion,exitCode:compat.exitCode,report:compat.report,baseline:compat.baseline,cache:compat.cache||null,reviews:compat.reviews||null,
+ summary:compat.ok?`可用 ${s.ok||0} / 部分可用 ${s.partial||0} / 不兼容 ${s.broken||0}；覆盖有限 ${s.limited||0}；无已验证调用 ${s.vacuousOk||0}`:'无法判定',nodeModules:compat.nodeModules||'',hasRuntimeSurface:!!compat.report?.hasRuntimeSurface,text};
 }
 
 function registerTool(ctx, state) {
@@ -1107,18 +1315,23 @@ function registerTool(ctx, state) {
       const dispose = 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. '
+          'Assess compatibility risks for the DSH plugins installed in this profile against the '
+          + 'current DSH version, reporting evidence, coverage limits and file:line locations where available. '
           + '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 '
+          + 'updating DSH, or what compatibility evidence is available for an installed plugin. 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.',
+          + 'Certainty is separate from impact evidence: certain means supported by explicit static facts or qualified runtime observations; '
+          + 'suspected means insufficient evidence to establish that finding, even when some runtime observations exist. '
+          + 'impactBasis=measured requires corresponding impact/state observations; inferred means an inferred impact, not a measured business outcome. '
+          + 'vacuous means no verified calls in an otherwise ok result; service dependencies or unverified client features may still exist. '
+          + 'Preserve coverage limits: unobserved does not mean absent, and no findings or verified calls do not certify business behavior. '
+          + 'The official API catalogue is a contract catalogue, not a runtime observation. '
+          + 'Provide upgradeTo for a separate static pre-upgrade comparison against an exact supported DSH version. It reuses no live observations, cache or baseline, performs no upgrade and does not certify future business behavior.',
         parameters: {
           type: 'object',
           additionalProperties: false,
           properties: {
+            upgradeTo: {type:'string',description:'Optional exact target DSH version for static upgrade preflight; known catalogues: 0.2.0-rc.2 and 0.2.1-rc.2. Unknown versions are uncertified.'},
             profile: {
               type: 'string',
               description:
@@ -1143,9 +1356,11 @@ function registerTool(ctx, state) {
               error: {oneOf:[{type:'string'},{type:'null'}]},
               exitCode: {type:'integer',enum:[0,1,2,3]},
               toolVersion: {oneOf:[{type:'string'},{type:'null'}]},
-              report: {type:'object',additionalProperties:true},
+              report: {oneOf:[{type:'object',additionalProperties:true},{type:'null'}]},
+              upgradePreview: {type:'object',additionalProperties:true},
               baseline: {oneOf:[{type:'object',additionalProperties:true},{type:'null'}]},
               cache: {oneOf:[{type:'object',additionalProperties:true},{type:'null'}]},
+              reviews: {oneOf:[{type:'object',additionalProperties:true},{type:'null'}]},
               summary: { type: 'string' },
               nodeModules: { type: 'string' },
               hasRuntimeSurface: { type: 'boolean' },
@@ -1167,6 +1382,9 @@ function registerTool(ctx, state) {
             const wanted = args && typeof args.profile === 'string' && args.profile.trim() !== ''
               ? args.profile.trim()
               : null;
+            if (args && Object.prototype.hasOwnProperty.call(args,'upgradeTo')) {
+              return await upgradeToolResult(state,{profile:wanted,targetVersion:args.upgradeTo,invalidRequest:typeof args.upgradeTo !== 'string'?'upgradeTo 必须为确切 DSH 版本':null});
+            }
             const compat = await serveReport(state,ctx,false,wanted?{profile:wanted}:{});
             const text = renderForModel(compat);
             return toolResult(compat,text);
@@ -1334,9 +1552,10 @@ export function apply(ctx) {
       // 更重要的是**启动时就先跑一次**（见下面的预热），这样用户点开面板是即时的。
       lastReport: null,
       lastReportAt: 0,
-      computing: null,
       /** 缓存有效期。到点不清空，而是**先返回旧的、后台再刷新** —— 见下面的 stale-while-revalidate。 */
       cacheTtlMs: toPositiveInt(process.env.DSC_CACHE_TTL_MS, 5 * 60 * 1000),
+      // A caller may shorten the observation interval; never enlarge its default.
+      cacheWatchMs: Math.min(5000,toPositiveInt(process.env.DSC_CACHE_WATCH_MS,5000)),
       /** 启动后多久自动跑第一次（默认落在最后一次 loader 扫描之后） */
       autoRunDelayMs: toPositiveInt(process.env.DSC_AUTORUN_MS, (SCAN_DELAYS[SCAN_DELAYS.length - 1] || 4000) + 2000),
       autoRunTimer: null,
@@ -1394,7 +1613,9 @@ export function apply(ctx) {
                     'content-type': 'application/json; charset=utf-8',
                     'cache-control': 'no-store',
                   });
-                  res.end(JSON.stringify(out));
+                  res.end(JSON.stringify(url.searchParams.get('metadata')==='1' && out.ok ? {
+                    kind:'plugin-compat-check/report-metadata',ok:true,computedAt:out.computedAt,nodeModules:out.nodeModules,dshVersion:out.report.dshVersion,cache:out.cache || null,reviewsRevision:out.reviews?.revision || null,reviewsError:out.reviews?.error || null,reviewsContextToken:out.reviews?.contextToken || null,
+                  } : out));
                 } catch (error) {
                   // 连处理器里都不抛：把错误变成一条可读的 JSON，而不是 500 空响应。
                   res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
@@ -1417,7 +1638,9 @@ export function apply(ctx) {
 
     // E1：注册随包的 skill。**失败只留日志，绝不抛** —— 见文件顶部硬规矩。
     try {
-      registerSkill(ctx);
+      registerFindingReviewRoute(ctx, state);
+      registerUpgradeRoute(ctx, state);
+    registerSkill(ctx);
     } catch (error) {
       log(`WARN SKILL registration threw: ${errText(error)}`);
     }
@@ -1551,6 +1774,12 @@ export function apply(ctx) {
       globalThis.__DSH_COMPAT_CHECK__ = handle;
       if(typeof ctx.effect==='function')ctx.effect(()=>()=>{
         state.disposed=true;
+        for (const request of state.reviewRequests || []) request.abort();
+        state.reviewTargets?.clear();
+        state.reportService?.dispose();
+        for(const off of state.cacheEventDisposers || []){try{off();}catch{}}
+        state.cacheEventDisposers=[];
+        state.upgradeFlight?.controller?.abort();
         for(const timer of state.scanTimers)clearTimeout(timer);
         state.scanTimers.clear();
         clearTimeout(state.fallbackTimer);