dsh-plugin-compat-check 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chenyu Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,79 +1,43 @@
 # dsh-plugin-compat-check
 
-告诉你**已经装好的 DSH 插件**跟**当前 DSH 版本**到底兼不兼容；不兼容的，给出**位置**
-（`file:line`）和**原因**。
+检查**已经安装的 DSH 插件**与当前 DSH 版本的兼容性，提供源码位置、运行时证据与覆盖限制。包含兼容性面板、插件详情角标、`compat_check` 对话工具和 skill provider。
 
-这是同一份判定内核的三个入口之一（DSH 插件）。另外两个是 CLI 与 skill —— 见仓库说明。
-
-## 为什么需要它
-
-四种"看起来没问题"其实都有问题：
-
-| 你可能会以为 | 实际情况 |
-|---|---|
-| `peerDependencies` 写了支持 → 能用 | 声明可能是错的。DSH 自带的版本闸门只做**字符串范围比对** |
-| DSH 版本闸门放行了 → 能用 | 同上，它不验证 API 是否存在 |
-| 启动没报错 → 能用 | 插件普遍 `try/catch` 降级，**API 缺失时它"激活成功"但功能是死的** |
-| 启动日志干净 → 客户端也没问题 | 客户端跑在浏览器里，日志里根本没有它 |
-
-## 安装
+本文件适用于 **0.1.2**。安装指定版本：
 
 ```bash
-dsh plugin --profile <你的 profile> add dsh-plugin-compat-check
+dsh plugin --profile <profile> add dsh-plugin-compat-check@0.1.2
 ```
 
-装好后插件会：
+## 从源码构建安装
 
-- 在**设置 → 内置插件**里加一个「**兼容性**」标签页，列出每个插件的结论
-- 在插件详情页给一个角标（可用 / 部分可用 / 不兼容）
-- 注册一个 `compat_check` 对话工具，可以直接问
-- 注册一个 skill，让 agent 知道何时该用它
+本仓库根为私有开发工作区，不声明DSH bundle。不要把根目录GitHub安装规格当成plugin子目录的安装方式。在仓库根运行 `npm ci --ignore-scripts`，然后：
 
-## 结论怎么读
-
-```
-部分可用  dsh-keep-awake@0.2.0
-     功能失效 / 宿主方法缺失  settings.register  @ lib/index.js:466
-       影响: 插件的设置页/设置项会消失
-       依据: 运行时里没有这个方法；规则表给出影响面
-     客户端半边（命令行测不到，需界面验证）: locale, slots
-     已过滤（判为噪音/有兜底）: jobs.onJobsChanged
+```bash
+cd plugin
+npm pack --pack-destination <已存在的绝对输出目录>
+dsh plugin --profile <临时profile> add file:<生成的tgz绝对路径>
 ```
 
-- **每条发现都带位置**：只说"不兼容"而不给 `file:line`，用户就无法验证我们凭什么判
-- **`[疑似]`**：这一条没有运行时面支撑。转述时**必须**带上「疑似」
-- **`已过滤（判为噪音/有兜底）`**：报了但判定为不构成问题（例如作者自己写了
-  `typeof x.y === 'function'` 能力检测）。**过滤也是结论的一部分**，不要只报红叉
-- **`客户端半边`**：列出来的服务命令行测不到，只能人工在界面上确认 —— 工具不下结论
+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。
 
-| 档 | 判据 |
-|---|---|
-| **确定** | 服务名出现在可信声明里（`inject` / `ctx.get` / `ctx.inject`），或有运行时面实证 |
-| **疑似** | 只靠官方 API 目录推断 —— **那份目录是契约目录，不是运行时面** |
-| **已过滤** | 判为噪音（vendored 代码里的同名变量）或作者有兜底 |
+0.1.2修正发布状态文案并统一版本标记；判定算法与0.1.1一致。规则/API目录仍基于0.2.0-rc.2，不把新版接入测试当作全面适配。
 
-官方目录与运行时面**差别很大**：实测 `jobs` 在目录里 0 个方法、运行时 29 个；
-`settings` 目录 6 个、运行时 10 个；`loader` 完全不收录。
-所以**没有运行时面时，方法级结论一律降为「疑似」**。
+## 判定与边界
 
-## 安全边界
+当前profile在宿主进程内采样服务描述符，不执行getter；未知访问器保留未知，并纳入能可靠映射的loader FAILED/PENDING。查询其它profile只用静态证据，不借用当前宿主服务。Babel AST扫描不执行目标源码，分析运行在有时间和内存上限的worker中；动态调用和跨函数数据流仍有限。
 
-这个插件**严格只读**：不装包、不起子进程、不联网（默认）、只碰当前 profile。
+`certainty`为certain或suspected；过滤、守卫、弃权是独立去处。省略的probe键表示未采样，不表示服务缺失。现代观测匹配profile/DSH版本且默认24小时过期；旧报告标记未绑定。声明不能代替API实测，官方peer冲突以推断影响呈现，当前实现仍按0.2.0-rc.2把engines.dsh作建议处理。0.2.1-rc.1宿主已优先按该字段判断，声明有误报/漏报风险，应核对实际宿主结果；本补丁未改判定算法。
 
-**唯一的副作用**是它会把自己的体检记录写成本机基线
-（`$DSH_HOME/dsh-plugin-compat-check/baseline.<profile>.json`），
-好让下次对比出「相比上次变了什么」。它不写别的地方。
+转述时保留 `impactBasis=inferred`（影响为推断，非实测）、coverage限制和vacuous结果。API发现通常有file:line，loader/元数据发现可能没有源码位置。客户端服务列为待界面核验项；独立浏览器开发工具不属于本面板，且不验证业务交互。
 
-如果连这个也不想让它写，用 CLI 形态加 `--no-baseline`。
+插件体检不安装包、不调用外部命令或联网；会启动分析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；不把历史测试数字作为当前版本的完整功能认证。
 
-`--json` 输出的 `toolVersion`（CLI 形态下 `--version`）是**这份结论是哪一版工具给的**。
-注意它和 `dshVersion` 是两件事：后者是**被体检对象**的版本。
-同一个插件在不同版本的规则表/提取器下结论会变，所以报结论时请带上 `toolVersion`。
+报告结构由仓库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-报告结构与兼容策略)。
 
-## 许可证
+## License
 
-MIT。源码与完整说明：<https://github.com/lcy0121/dsh-plugin-compat-check>
+MIT。源码、问题反馈与仓库文档：[GitHub](https://github.com/lcy0121/dsh-plugin-compat-check)。

package/index.js

@@ -1,8 +1,8 @@
 // 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,
+// (docs/Plan.md §2.4: read ctx.loader.entries(), recover failure reasons,
 // never throw).
 //
-// HARD RULE (Plan.md §4 第 6 条：绝不抛、绝不拖累宿主): this plugin must never
+// HARD RULE (docs/Plan.md §3 第 3 条：绝不抛、绝不拖累宿主): 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
@@ -11,14 +11,14 @@
 // 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 地雷清单).
+// exact way to park this plugin's own fiber in PENDING (docs/Plan.md §2.4 接入要点).
 // `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
+//   ${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';
@@ -27,6 +27,9 @@ import path, { join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createRequire as __createRequire } from 'node:module';
 
+import {loaderObservations,privateDiagnostic} from './lib/host-resources.js';
+import {assertEnvelope,failureEnvelope} from './lib/report-contract.js';
+
 export const name = 'dsh-plugin-compat-check';
 
 /**
@@ -53,8 +56,8 @@ const FIBER_STATES = {
   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');
+const OUT_DIR = process.env.DSC_OUT_DIR || null;
+const OUT_JSON = OUT_DIR ? join(OUT_DIR, 'loader-introspect.json') : null;
 
 /** Defensive cap: a pathological iterable must not exhaust the host's heap. */
 const MAX_ENTRIES = 20000;
@@ -125,21 +128,7 @@ function describe(value) {
   }
 }
 
-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;
-}
+function writeReport(report) { return privateDiagnostic(OUT_JSON, report); }
 
 // ---------------------------------------------------------------------------
 // B1: loader access
@@ -317,7 +306,7 @@ function declaredInjectKeys(fiber) {
   }
 }
 
-/** 缺服务 = fiber.ctx.get(key) === undefined (Plan.md §5 B1). */
+/** 缺服务 = fiber.ctx.get(key) === undefined (docs/Plan.md §2.4). */
 function missingServices(fiber, keys) {
   const missing = [];
   const present = [];
@@ -638,7 +627,7 @@ function resolveKernelDir() {
 /**
  * 当前 profile 的 node_modules。
  *
- * 优先级：显式覆盖 → DSH 正在跑的 profile → `desktop`。
+ * 优先级：显式请求/覆盖 → DSH 正在跑的 profile；无法确认时返回错误，不回退 desktop。
  * 「正在跑的是哪个 profile」没有正式服务暴露，只能靠环境变量与目录推断 ——
  * 所以这里把推断的**依据**一起放进报告，让结论可追溯，而不是猜一个就不吭声。
  */
@@ -647,7 +636,7 @@ function resolveKernelDir() {
  *
  * ## 为什么必须拿到它
  *
- * `dshVersion` 是基线的三个字段之一（Plan.md §5 F1），也是「**声明与实测不符**」
+ * `dshVersion` 是基线差分的输入（docs/Plan.md §2.2），也是「**声明与实测不符**」
  * 这类结论的**前提** —— 没有它就没法把插件的 `dsh.compatibility` 声明与实际版本对上，
  * 于是那一类发现（本工具相对既有方案唯一不可替代的结论）在插件形态下根本不成立。
  *
@@ -666,10 +655,10 @@ function resolveKernelDir() {
  * ### 被否掉的方案，以及为什么
  *
  * - **`process.env.DSH_VERSION`**：不存在（就是这次要解决的缺口本身）。
- * - **`dsh --version` 起子进程**：不行，而且**不是**能力问题 —— Plan.md §2 第 1 题锁定了
+ * - **`dsh --version` 起子进程**：不行，而且**不是**能力问题 —— docs/Plan.md §1 锁定了
  *   「插件严格只读：不装包、不起子进程、不联网」。为拿一个版本号破这条边界不值。
  * - **`Info.plist`**：macOS 专有（`CFBundleShortVersionString` = 0.2.0-rc.2，能读到）。
- *   本产品要跨平台（§2 第 6 题），不能把它当主路。
+ *   本产品要跨平台（§5.1 的验证边界），不能把它当主路。
  *
  * ## 拿不到时返回 null，而不是猜
  *
@@ -769,29 +758,17 @@ function resolveActiveProfile() {
   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 { /* 下一个 */ }
+function resolveNodeModules(requestedProfile = null) {
+  const dshHome=process.env.DSH_HOME || join(homedir(),'.dsh');
+  const inferred=resolveActiveProfile();
+  const selected=requestedProfile || inferred.name;
+  if(selected){
+    if(!/^[\w.-]+$/.test(selected) || selected==='.' || selected==='..')return {dir:null,why:'profile 名称非法'};
+    const dir=join(dshHome,'profiles',selected,'node_modules');
+    return existsSync(dir)?{dir,why:requestedProfile?'请求明确指定的 profile '+selected:inferred.why}:{dir:null,why:'指定 profile 不存在: '+selected};
   }
-  return { dir: null, why: '没有任何候选目录存在' };
+  if(process.env.DSH_PROFILE_DIR){const dir=join(process.env.DSH_PROFILE_DIR,'node_modules');return existsSync(dir)?{dir,why:'显式 DSH_PROFILE_DIR'}:{dir:null,why:'DSH_PROFILE_DIR 不存在'};}
+  return {dir:null,why:'无法确认当前 profile；请显式指定'};
 }
 
 /**
@@ -812,38 +789,15 @@ function resolveNodeModules() {
  * 并发安全：`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 } };
+async function serveReport(state, ctx, force, options = {}) {
+  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});
   }
-  // 过期：**不等它**。给旧的，后台刷。
-  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 } };
+  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||{});
 }
 
 /**
@@ -869,7 +823,7 @@ function baselineFileFor(nmDir) {
  *   - 客户端跑在浏览器里，读不了文件系统；
  *   - 结论（五元组 + 确定性）是内核的产物，算出唯一一份才不会两边漂移。
  */
-async function computeReport(state, ctx) {
+async function computeReport(state, ctx, options = {}) {
   const started = Date.now();
   const out = {
     schemaVersion: 1,
@@ -880,7 +834,7 @@ async function computeReport(state, ctx) {
     kernelDir: null,
     // 「这份结论是哪一版工具给的」。面板是本插件的主要入口，
     // 少了它，用户来问"凭什么"时第一句就卡住 —— 而同一插件在不同版本的
-    // 规则表/提取器下结论会变（见 lib/version.mjs 与 Plan.md §5.2.8）。
+    // 规则表/提取器下结论会变（见 lib/version.mjs 和 docs/Plan.md §1、§3 第 2 条）。
     toolVersion: null,
     nodeModules: null,
     nodeModulesWhy: null,
@@ -907,7 +861,7 @@ async function computeReport(state, ctx) {
         + '插件形态下它们是同仓库的相邻目录；发布形态请设 DSC_KERNEL。';
       return out;
     }
-    const nm = resolveNodeModules();
+    const nm = resolveNodeModules(options.profile || null);
     out.nodeModules = nm.dir;
     out.nodeModulesWhy = nm.why;
     if (!nm.dir) {
@@ -915,7 +869,7 @@ async function computeReport(state, ctx) {
       return out;
     }
 
-    const { extractWithProvenance } = await import(pathToFileURL(join(kernel, 'lib', 'extract.mjs')).href);
+    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');
@@ -938,13 +892,27 @@ async function computeReport(state, ctx) {
     }
     out.surfaceWhy = surfaceWhy;
 
-    const extracted = extractWithProvenance(nm.dir, { catalog });
+    const extracted = await extractInWorker(nm.dir, { catalog });
+    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);
+    if(!hostSurface && sameHost){
+      hostSurface=sampleServices(ctx,extracted.report.services,{profileId:nm.dir,dshVersion:resolveDshVersion()});
+      surfaceWhy='当前宿主进程内采集的服务结构；未采集或读取失败不等于缺失';
+    }
+    const itemListing=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 loaderState=sameHost?loaderObservations(ctx,extracted.report.manifests,itemListing):{rows:[],unmapped:[],available:false};
+    out.loaderCoverage=loaderState;
+
+    out.surfaceWhy=surfaceWhy;
     const verdict = buildVerdicts({
       report: extracted.report,
       hostSurface,
       rules,
       catalog,
       dshVersion: resolveDshVersion(),
+      entryStates: loaderState.rows,
+      observationTarget: {profileId:nm.dir,maxAgeMs:24*60*60*1000},
     });
 
     // ── C4：基线差分 ──
@@ -954,29 +922,11 @@ async function computeReport(state, ctx) {
     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)}）`;
-      }
+      const store=await import(pathToFileURL(join(kernel,'lib','state-store.mjs')).href);
+      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);
+      baseline=store.baselineTransaction(bfile,snap,{advance:extracted.report.scanComplete});
     } catch (error) {
       baseline = { error: errText(error), note: '基线差分没算成（不影响本次结论）' };
     }
@@ -1006,22 +956,12 @@ async function computeReport(state, ctx) {
       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,
-    };
+    const {toJSON}=await import(pathToFileURL(join(kernel,'lib','report.mjs')).href);
+    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;
+    out.exitCode = canonical.exitCode;
+    out.report = {...canonical,hasRuntimeSurface:verdict.observation.usable,loaderCoverage:out.loaderCoverage,surfaceWhy,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) {
@@ -1067,9 +1007,12 @@ function renderForModel(compat) {
     const s = r.summary || {};
     L.push(`结论：可用 ${s.ok || 0}　部分可用 ${s.partial || 0}　不兼容 ${s.broken || 0}`
       + (s.vacuousOk ? `（其中 ${s.vacuousOk} 个「可用」是空洞的：该插件没有用过任何 DSH 服务，因此没有可检查的东西）` : ''));
+    L.push(`工具版本：${compat.toolVersion || '未知'}`);
+    for(const note of r.observation?.notes||[])L.push(`采样说明：${note}`);
+    if(s.limited)L.push(`证据覆盖有限：${s.limited} 个插件尚有未验证部分`);
     L.push(`体检对象：${compat.nodeModules}（${compat.nodeModulesWhy}）`);
     L.push(r.hasRuntimeSurface
-      ? '方法级判定依据：宿主运行时面 —— 这类结论是确定的。'
+      ? '方法级判定依据：宿主运行时面；具体确定性仍以每条发现和覆盖限制为准。'
       : '方法级判定依据：官方 API 目录（**契约目录，不是运行时面**）—— 因此方法级结论一律标「疑似」。'
         + '「疑似」不是缺陷，是诚实：判不准时降级标注，而不是升格成确定。');
     L.push('');
@@ -1088,10 +1031,12 @@ function renderForModel(compat) {
         const cat = {
           'host-service-missing': '服务缺失', 'host-method-missing': '方法缺失',
           'unprovided-dependency': '无人提供的依赖', 'declaration-mismatch': '声明与实测不符',
+      '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.impact}`);
+        if (f.impact) L.push(`      影响${f.impactBasis==='inferred'?'（推断，非实测）':''}：${f.impact}`);
+        if(f.basis)L.push(`      依据：${f.basis}`);
       }
       const cs = p.clientSide || [];
       if (cs.length) L.push(`    客户端半边（命令行测不到，需界面验证）：${cs.map((c) => c.service).join('、')}`);
@@ -1102,9 +1047,9 @@ function renderForModel(compat) {
 
     L.push('');
     L.push('读这个结果时注意两点：');
-    L.push('  1) 「可用」不等于"功能验证过"。它只说明**用到的 DSH 服务与 API 都在**。'
+    L.push('  1) 「可用」不等于"功能验证过"。它只说明本轮未发现冲突；请同时看证据覆盖与未验证项。'
       + '插件仍然可能因为自身逻辑、配置或第三方依赖而出问题。');
-    L.push('  2) 「客户端半边」的那些服务命令行永远测不到 —— 它们活在浏览器里，'
+    L.push('  2) 「客户端半边」的那些服务默认报告不验证 —— 它们活在浏览器里，'
       + '只能靠"界面上有没有出现该插件的 UI"来验证。别把"没报错"当成"没问题"。');
     return L.join('\n');
   } catch (error) {
@@ -1115,6 +1060,12 @@ function renderForModel(compat) {
 /** 工具的服务集合：`tools`；`agents` 用来把相对路径解析到会话工作目录。 */
 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};
+}
+
 function registerTool(ctx, state) {
   // 与 C2 路由同一个理由：走作用域 ctx.inject，headless/CLI 形态下 `tools` 不在场时
   // 这段根本不注册，本插件的 fiber 也就不会去等一个不存在的服务（`inject` 保持 []）。
@@ -1158,12 +1109,21 @@ function registerTool(ctx, state) {
             type: 'object',
             additionalProperties: false,
             properties: {
+              schemaVersion: {type:'integer',enum:[1]},
+              kind: {type:'string'},
+              ok: {type:'boolean'},
+              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},
+              baseline: {oneOf:[{type:'object',additionalProperties:true},{type:'null'}]},
+              cache: {oneOf:[{type:'object',additionalProperties:true},{type:'null'}]},
               summary: { type: 'string' },
               nodeModules: { type: 'string' },
               hasRuntimeSurface: { type: 'boolean' },
               text: { type: 'string' },
             },
-            required: ['summary', 'nodeModules', 'hasRuntimeSurface', 'text'],
+            required: ['schemaVersion','kind','ok','error','exitCode','toolVersion','report','baseline','summary','nodeModules','hasRuntimeSurface','text'],
           },
           render: (_args, value) => [{ type: 'text', text: value && typeof value.text === 'string' ? value.text : '' }],
         },
@@ -1179,35 +1139,13 @@ function registerTool(ctx, state) {
             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 compat = await serveReport(state,ctx,false,wanted?{profile:wanted}:{});
             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,
-            };
+            return toolResult(compat,text);
           } catch (error) {
             // 工具的 execute 抛错会把整轮对话变成错误 —— 而"体检失败"不是用户的错，
             // 也不该让他重来一遍。所以这里**不抛**，把失败也变成一段可读的文本。
-            return {
-              summary: '无法判定',
-              nodeModules: '',
-              hasRuntimeSurface: false,
-              text: `体检没跑成（这是工具的问题，不是插件的结论）：${errText(error)}\n`
-                + '请不要据此判断兼容性。',
-            };
+            return toolResult(failureEnvelope(errText(error)),`体检没跑成（这是工具的问题，不是插件的结论）：${errText(error)}`);
           }
         },
       });
@@ -1428,7 +1366,7 @@ export function apply(ctx) {
                 } catch (error) {
                   // 连处理器里都不抛：把错误变成一条可读的 JSON，而不是 500 空响应。
                   res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
-                  res.end(JSON.stringify({ ok: false, error: errText(error) }));
+                  res.end(JSON.stringify(failureEnvelope(errText(error))));
                 }
               },
             });
@@ -1530,7 +1468,7 @@ export function apply(ctx) {
       if (state.autoCheckStarted) return;   // 幂等：只跑一次
       state.autoCheckStarted = true;
       try {
-        computeReport(state, ctx)
+        serveReport(state, ctx, false)
           .then((out) => {
             state.lastReport = out;
             state.lastReportAt = Date.now();