dsh-plugin-tool-management 0.20.2 → 0.21.0

package/lib/compat/capability-specs.js

@@ -3,7 +3,7 @@
 // 这张表就是与宿主的契约本体 —— 纯字面量，判定逻辑在 probe.ts 的 inspectCapability，
 // 取数原语在 host-probe.ts。缺一个成员时界面给出的是这一行点名的降级，而不是删除序列
 // 中途抛出的一次异常。
-import { callableWithSentinel, isFn, PROBE_SENTINEL } from './host-probe.js';
+import { callableWithSentinel, isFn, PROBE_SENTINEL, resolvableFromHost } from './host-probe.js';
 /**
  * The capability table. This IS the contract with the host: everything the
  * adapters reach for is listed here with what happens when it is absent, so a
@@ -318,4 +318,63 @@ export const CAPABILITY_SPECS = [
             return undefined;
         },
     },
+    // ---- 0.2.1 的四处新契约面 ------------------------------------------------
+    // 这四条都是**本版适配真实依赖**的宿主成员。它们与上面那些的区别是：上面那些从 0.1.x
+    // 起就在表里，而这四个是 0.2.1 才出现的 —— 下一代宿主改掉其中任何一个，对应的功能会
+    // **静默失效**（不抛错、只少一半），所以必须在升级后第一眼可见。
+    //
+    // 逐条的后果：
+    //   ① register 没了 → 带人设的子代理委派失败（临时预设注册不上去）；
+    //   ② restrict 没了 → 人设的 tools/toolsDeny 不生效，子代理继承父级全部工具；
+    //   ③ agent/created 不串行 → 工具限制慢一步（首轮看到的还是继承来的工具集）；
+    //   ④ admit 没了 → Web 鉴权退回本地回环判定，本机任意进程可调写 op。
+    {
+        id: 'agentPreset.register',
+        label: '临时子预设注册',
+        kind: 'write',
+        owner: 'presetRoster',
+        fallback: 'refuse-operation',
+        methods: ['register'],
+        // 只查存在性 + 与参考副本的文本比对，**不真注册**：register 会真的树上挂一棵插件树。
+        probe: (t) => isFn(t?.register) ? undefined : '宿主预设名册缺少 register()：带人设的子代理委派无法创建独立预设',
+    },
+    {
+        id: 'tools.restrict-method',
+        label: '工具限制施加（restrict）',
+        kind: 'write',
+        owner: 'tools',
+        fallback: 'disable-destructive',
+        methods: ['restrict'],
+        probe: (t) => isFn(t?.restrict) ? undefined : '宿主工具服务缺少 restrict()：人设的工具限制不生效，子代理将继承父级全部工具',
+    },
+    {
+        // 探测的是 **agent 作用域**上 `on` 在场这一事实。真正的时序保证（announce 等待
+        // 串行 agent/created 监听全部完成后才放行收件箱）藏在宿主源码里，探针看不见 ——
+        // 这一条能抓的是"ctx.on 整个没了 / 改名"，那时监听器挂不上、限制退化成事后施加。
+        id: 'agent.created-event',
+        label: '子代理创建事件（agent/created）',
+        kind: 'read',
+        owner: 'agentContext',
+        fallback: 'disable-destructive',
+        methods: ['on'],
+        probe: (t) => isFn(t?.on) ? undefined : 'agent 作用域缺少 on()：无法在子代理创建时施加工具限制',
+    },
+    {
+        // 0.2.1 起宿主把鉴权栅栏拆成 admit()/requestRejection() 两层（见 http-fence.ts）。
+        // admit 不在场时插件退回 requestRejection，再缺则退回本地回环判定 —— 每一级都少一层，
+        // 但都不抛错，所以必须单列一条让人看得见现在停在哪一级。
+        id: 'connection.admit',
+        label: '连接准入（admit）',
+        kind: 'read',
+        owner: 'connection',
+        fallback: 'refuse-operation',
+        methods: ['admit'],
+        probe: (t) => isFn(t?.admit) ? undefined : '宿主 connection 缺少 admit()：Web 鉴权降级（退到 requestRejection / 本地回环判定）',
+        // 静态检查的门槛：`dsh-client-connection` **不是**本插件的 peer（宿主不要求插件直接依赖
+        // 它），doctor 从插件锚点解析不到它。那时不能报 `missing` —— 那等于断言"宿主没有这个
+        // 能力"，而运行时探针看到的是 Web 组合里真实的 connection 服务（0.2.1 起一定带 admit）。
+        // 门槛取宿主侧：至少一个宿主锚点解析得到才查；解析不到退回 `runtime-only`（如实标注
+        // "只能对活的宿主查"），而不是编一个"缺失"。
+        staticWhen: () => resolvableFromHost('@deepseek-ai/dsh-client-connection'),
+    },
 ];

package/lib/compat/host-contracts.js

@@ -0,0 +1,72 @@
+// 宿主**非 peer** 契约的共享清单：运行时探测（compat/probe.ts 的 runtime-only 上报）与
+// `scripts/doctor.mjs` 都要读它们，所以只有这一份。
+//
+// 为什么单独一层：这些包**不在**本插件的 `peerDependencies` 里 —— 宿主不要求插件依赖它们，
+// 但插件在运行时按**裸模块名**直接 require（MCP 客户端、人设、全局指令、技能目录）。它们有
+// 两个共同点让它们必须被看见：
+//   (1) 官方改名或撤掉其中一个，对应功能**静默降级**（不抛错，只是少一半）；
+//   (2) 它们不参与模块身份比对（不是硬依赖），所以"两份不同拷贝"那一栏根本看不到它们。
+//
+// 此前这份清单只活在 doctor 里：命令行看得到，兼容页看不到。而兼容页正是用户升级 DSH 后
+// 第一眼看的界面 —— 于是同一个"官方把某个包撤了"的事实，CLI 报得出来、界面报不出来。
+// 提升到这里之后两边读同一份（doctor 从 lib/ import，不再自己维护一份）。
+/**
+ * `~/.dsh/AGENTS.md` 的**增量刷新**契约 —— 本插件"应用提示词预设"依赖它。
+ *
+ * 插件把预设正文写进全局 `AGENTS.md`，然后靠官方**每一步**重新读盘（对比 stat 的 version 与
+ * 内容 SHA-1）决定要不要把新正文送进模型。官方一旦改成事件驱动、加 touchedPaths 白名单、或改
+ * digest 口径，"应用预设"就会**静默失效**（旧正文继续注入），零报错。
+ */
+export const AGENTS_MD_REFRESH_PACKAGE = '@deepseek-ai/dsh-agent-instructions';
+export const AGENTS_MD_REFRESH_MARKERS = [
+    { needle: 'agentInstructionsHook', why: '每步重读全局 AGENTS.md 的钩子入口' },
+    { needle: 'trimmedInstructionDigest', why: '内容同一性 = 去掉首尾空白后的 SHA-1' },
+    { needle: 'instructionContentSha1', why: 'SHA-1 摘要口径' },
+    { needle: 'sameInstructionChange', why: '按 {action, scope, path, digest} 判「有没有变化」' },
+];
+/**
+ * 运行时按**裸模块名** require 的宿主包，以及每个包守着的契约。
+ *
+ * 与 `AGENTS_MD_REFRESH_MARKERS` 的分工：那一份是"同一个包内的若干标识符"，这一份是
+ * "若干不同的包各要求什么"。合起来才是"官方撤掉了什么"的完整清单。
+ */
+export const BARE_HOST_MODULE_CONTRACTS = [
+    {
+        package: '@deepseek-ai/dsh-mcp-client',
+        feature: 'MCP 客户端（MCP 服务器装配的宿主出口）',
+        markers: [],
+    },
+    {
+        package: '@deepseek-ai/dsh-persona',
+        feature: '人设（子代理人格的读取与解析）',
+        markers: [],
+    },
+    {
+        package: AGENTS_MD_REFRESH_PACKAGE,
+        feature: 'AGENTS.md 注入（应用提示词预设）',
+        markers: AGENTS_MD_REFRESH_MARKERS,
+    },
+    {
+        package: '@deepseek-ai/dsh-tool-skill',
+        feature: '技能目录（官方技能挂载的宿主出口）',
+        markers: [],
+    },
+];
+/** doctor 的 CLI 用：裸模块名清单（顺序与上面一致）。 */
+export const BARE_HOST_MODULE_NAMES = BARE_HOST_MODULE_CONTRACTS.map((item) => item.package);
+/**
+ * 官方 JSONL 会话目录布局的 canary —— 历史适配器（`src/sessions/workspace.ts` →
+ * `jsonlSessionDirectory`）硬编码了它。
+ *
+ * 这些是**行为常量**，不是装饰：任何一个变了，适配器就再也不能确认某个转写目录属于它正要删的
+ * 那个会话，删除会退化成"只删工件、保留父目录"，而唯一征兆只是插件侧一行日志。那种退化被刻意
+ * 做成非致命（工件仍然删掉，且删后经 `persistence.stat` 复核），所以对着一台没活着的宿主做静态
+ * 检查，是用户在自己翻出孤儿目录之前唯一能知道漂移的办法。
+ */
+export const JSONL_LAYOUT_PACKAGE = '@deepseek-ai/dsh-session-persistence-jsonl';
+export const JSONL_LAYOUT_MARKERS = [
+    { needle: 'session-persistence-jsonl', why: '适配器的后端名门槛' },
+    { needle: '_no-cwd', why: '会话头没有 cwd 时落进的桶' },
+    { needle: '251', why: '项目段截断长度' },
+    { needle: 'padStart(4', why: '~XXXX UTF-16 转义编码' },
+];

package/lib/compat/host-probe.js

@@ -177,12 +177,18 @@ const SESSIONS_CLASS = { pkg: '@deepseek-ai/dsh-session', target: 'SessionStore'
 // （dsh-settings 导出 SettingsForms；dsh-agent-preset-registry 导出 AgentPresetRegistry）。
 const SETTINGS_CLASS = { pkg: '@deepseek-ai/dsh-settings', target: 'SettingsForms' };
 const ROSTER_CLASS = { pkg: '@deepseek-ai/dsh-agent-preset-registry', target: 'AgentPresetRegistry' };
+// 0.2.1 的两块契约面（tools.restrict / connection.admit）也都声明在官方类上，所以同样接入
+// 「参考副本 + 文本比对」：官方改了实现，比对的结论从"一致"变成"漂移"，界面上看得见。
+const TOOLS_CLASS = { pkg: '@deepseek-ai/dsh-tools', target: 'ToolRuntime' };
+const CONNECTION_CLASS = { pkg: '@deepseek-ai/dsh-client-connection', target: 'HostConnectionService' };
 export const OWNER_CLASSES = {
     workspace: WORKSPACE_CLASS,
     projectionCache: PROJECTION_CLASS,
     sessions: SESSIONS_CLASS,
     settings: SETTINGS_CLASS,
     presetRoster: ROSTER_CLASS,
+    tools: TOOLS_CLASS,
+    connection: CONNECTION_CLASS,
 };
 /** The named export's prototype, or undefined when the package is absent/trimmed. */
 function classPrototypeOf(ref) {
@@ -257,5 +263,58 @@ export function referencePrototypes() {
     const roster = classPrototypeOf(ROSTER_CLASS);
     if (roster !== undefined)
         out.roster = roster;
+    // 0.2.1 的两块：`dsh-tools` 是本插件的 peerDependency（参考副本拿得到）；
+    // `dsh-client-connection` **不在** peerDependencies 里（宿主不要求插件直接依赖它），
+    // 所以参考副本常态取不到 —— textMatch 记 undefined，那条能力退化成纯存在性检查。
+    // 这是如实的能力边界：能验"admit 在不在"，验不了"实现漂没漂"。
+    const tools = classPrototypeOf(TOOLS_CLASS);
+    if (tools !== undefined)
+        out.tools = tools;
+    const connection = classPrototypeOf(CONNECTION_CLASS);
+    if (connection !== undefined)
+        out.connection = connection;
     return out;
 }
+/**
+ * 从**宿主侧**能不能解析到一个包（不 import，只看解析）。
+ *
+ * 为什么需要它：有一部分官方包**不是**本插件的 peer（宿主不要求插件依赖它们），插件自己的
+ * `node_modules` 里就没有 —— `safeResolve`/`classPrototypeOf` 一律取不到。运行时探测不看
+ * 插件侧（它看的是 ctx 上的活服务），所以只有 doctor 这种"没有活宿主"的静态视图会被误导：
+ * 它从插件锚点解析，解析不到就把一条**运行时确实存在**的能力记成 `missing`
+ * （2026-10-17 `connection.admit` 就这么误报过：`dsh-client-connection` 不在插件依赖图里，
+ * 而它承载的 `admit()` 在 0.2.1 的 Web 组合里一定有）。
+ *
+ * 判据必须是宿主侧：逐个宿主安装锚点试着解析（纯 `require.resolve`，不 import），只要有
+ * **一个**能解析到就算能查。与 `safeResolve` 的分工：那个回答"本插件能不能 import 它"，
+ * 这个回答"宿主装不装它" —— 后者才是静态能力表该用的口径。
+ */
+export function resolvableFromHost(specifier) {
+    for (const anchor of hostResolveAnchors()) {
+        try {
+            createRequire(anchor).resolve(specifier);
+            return true;
+        }
+        catch {
+            /* try the next anchor */
+        }
+    }
+    return false;
+}
+/**
+ * 宿主安装的解析锚点（`package.json` 路径，按候选顺序）。
+ *
+ * 与 probe.ts 的 `hostPackageRoot()` 共用同一份 `hostRootCandidates()`，但这里**不要求**
+ * `dsh/package.json` 在场：即使那一层只剩空壳（0.1.5 时代的悬空 junction 树，本机正是如此），
+ * 它下面的 `node_modules/@deepseek-ai/<pkg>` 仍可能解析得到。判据各取所需 —— probe.ts 要
+ * "像不像一份完整安装"，这里只问"这个包从这里能不能解析到"。
+ */
+function hostResolveAnchors() {
+    return hostRootCandidatesFn().map((dir) => join(dirname(dir), 'package.json'));
+}
+// `hostRootCandidates()` 的注入点：由 probe.ts 在模块加载时填进来。不反向 import 是为了
+// 不成环（probe.ts → host-probe.ts → probe.ts），而"宿主在哪"的口径仍然只有一份。
+let hostRootCandidatesFn = () => [];
+export function provideHostRootCandidates(fn) {
+    hostRootCandidatesFn = fn;
+}

package/lib/compat/host-roots.js

@@ -20,7 +20,7 @@ export const IDENTITY_PACKAGES = [
     '@deepseek-ai/dsh-storage-domain',
     '@deepseek-ai/dsh-spill-local',
 ];
-export const VERIFIED_HOST_VERSION = '0.2.0-rc.2';
+export const VERIFIED_HOST_VERSION = '0.2.1-rc.2';
 export const OPERATION_ROUTES = {
     archive: { native: ['workspace.archive-native'], adapter: ['workspace.enqueue', 'workspace.set-state'] },
     unarchive: { native: ['workspace.unarchive-native'], adapter: ['workspace.enqueue', 'workspace.set-state'] },

package/lib/compat/probe.js

@@ -30,17 +30,23 @@
  * leave the rest working.
  */
 import { createRequire } from 'node:module';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { CAPABILITY_SPECS } from './capability-specs.js';
-import { isAsarPath, isFn, OWNER_CLASSES, realPathWithReason, referencePrototypes, safeResolve, textMatchOf, versionOf, versionOfPackageAt, } from './host-probe.js';
+import { BARE_HOST_MODULE_CONTRACTS } from './host-contracts.js';
+import { isAsarPath, isFn, OWNER_CLASSES, realPathWithReason, referencePrototypes, provideHostRootCandidates, safeResolve, textMatchOf, versionOf, versionOfPackageAt, } from './host-probe.js';
 // 宿主安装根的发现与「该走哪条恢复路」的判定 2026-10-01 整段搬到 ./host-roots.js，正文一字
 // 未改（moved-verify 逐字对拍）。probe.js 的公开面照旧：搬走的那 12 件全部从这里再出口 ——
 // index.ts / ops/compat.ts / sessions/bridge.ts 都按 ./compat/probe.js 引它们，少一件 equiv
 // 对拍就报「导出面丢失」。
 export { asarHostPackageRoot, findingsById, hostRootCandidates, IDENTITY_PACKAGES, npxCacheHostRoots, OPERATION_ROUTES, recoveryFor, refusalsFor, routeFor, VERIFIED_HOST_VERSION, } from './host-roots.js';
 import { hostRootCandidates, IDENTITY_PACKAGES, routeFor, VERIFIED_HOST_VERSION } from './host-roots.js';
+// 「宿主在哪」这份口径只有一份（host-roots.ts 的 hostRootCandidates）。静态能力表里有条目要
+// 按宿主侧解析结果决定**这一轮能不能查**（`staticWhen`，见 connection.admit 那条），而
+// capability-specs.ts 不能反向 import 本文件（probe → specs → probe 成环）。所以在这里把
+// 函数本体注入 host-probe.ts：它只调用、不 import，加载顺序天然正确（本文件先被求值）。
+provideHostRootCandidates(hostRootCandidates);
 /** Packages whose physical module identity matters to this plugin. */
 /**
  * 本插件是不是从**源码检出**跑起来的（仓库里那份，`scripts/host-deps.mjs` 就躺在旁边）。
@@ -63,9 +69,15 @@ export function isSourceInstall() {
  * `0.1.8-rc.1` / `0.2.1-rc.1` / `0.3.0-rc.1` 全部 false）—— 范围只能**逐代枚举并集**，
  * 每适配一代新 rc 就补一段（见 README 的升级清单）。
  *
- * 上界刻意不设：宿主跨代升级由**运行时能力探测**兜底（`assessHost` 逐项探测并降级），
- * 而不是在安装期拒绝整包。所以这里用不带上界的 `>=`，**不用** `^`（`^0.2.0` 的隐含上界
- * `<0.3.0` 会在宿主发稳定版 0.3.0 时把插件挡在门外 —— 与"不设上界"自相矛盾）。
+ * 每一代各自**带上界**（0.1.7 → `<0.2.0-rc.1`、0.2.0 → `<0.2.1-rc.2`、
+ * 0.2.1 → `<0.2.2`）：宿主跨 minor 升级时不给"装进去再说"，而是**主动发一版**。新的 minor
+ * 已经动过 SubagentStartRequest、身份比对这些会静默改行为的契约，旧适配继续跑在一份新宿主上，
+ * 失败会以"功能莫名不工作"的形式出现 —— 那时用户无法判断是插件问题还是版本问题。装上被拒 +
+ * 一版新适配，优于装上然后部分功能悄悄失效。
+ * 上界**必须逐段写**：只在最后一段挂 `<0.2.2` 是无效的 —— `>=0.2.0-rc.1` 那一支没有上界，
+ * 并集仍会匹配 0.3.0 / 1.0.0（实测：那种写法下 0.3.0 satisfies 为 true）。`^` 更不能用：
+ * `^0.2.0` 的隐含上界是 `<0.3.0`，而 0.2.1-rc.2 这个已适配版本自己都满足不了它（prerelease
+ * 只在同元组比较器带 prerelease 时才匹配）。
  *
  * 2026-09-30 审查 §5 F9 + §5.4：这一段此前与 `package.json` 的 peerDependencies **漂移**成
  * 两种写法（这里是 `^` 三段、那里是 `>=` 两段，且下界不同）。现在两处是**同一个字符串**，
@@ -80,16 +92,13 @@ export function isSourceInstall() {
  * 0.2.0-rc.2（桌面版首发）已实测通过：`assessHost` 全通过，宿主版本读得出来，
  * 归档宿主的身份判定见 `hostPackageRoot` / `isAsarPath`。所以它同时进范围与「已验证」。
  */
-export const EXPECTED_PEER_RANGE = '>=0.1.7-rc.2 || >=0.2.0-rc.1';
+export const EXPECTED_PEER_RANGE = '>=0.1.7-rc.2 <0.2.0-rc.1 || >=0.2.0-rc.1 <0.2.1-rc.2 || >=0.2.1-rc.2 <0.2.2';
 /** The release this plugin's adapters were last verified against. */
 /**
- * peer range 的下界。
+ * peer range 的下界。仍从 EXPECTED_PEER_RANGE 派生，避免两处手写漂移。
  *
- * 刻意不带 semver 上界：官方持续发版，硬上界会在宿主跨 minor 升级时直接挡住
- * 插件安装（pnpm peer 校验失败）。上界改为由**运行时能力探测**兜底 ——
- * 宿主版本高于已验证范围时，`assessHost` 会逐项探测并把缺失能力降级/禁用，
- * 而不是在安装期拒绝整包。
- * 从 EXPECTED_PEER_RANGE 派生，避免两处手写漂移。
+ * 注意它取的是范围里的**最低**那个版本号（`>=0.1.7-rc.2`），不是已验证版本 —— 与上界收敛
+ * 不冲突：这条讲的是"最早支持哪一代"，上界讲的是"当前适配覆盖到哪一代"。
  *
  * 2026-09-29 起**不再出现在界面上**（用户裁定：删掉「最低要求 ≥ …」那一行 —— 它是安装期
  * 门槛，摆在"当前宿主"卡片下面会被读成对当前宿主的断言）。保留此导出是因为它进了
@@ -223,6 +232,11 @@ export const SUBSTITUTED_CAPABILITIES = CAPABILITY_SPECS
 export const CAPABILITY_STATIC = CAPABILITY_SPECS.map((spec) => {
     const ref = OWNER_CLASSES[spec.owner];
     const methods = spec.methods;
+    // `staticWhen` 是"这一轮能不能静态检查"的门槛。它说不的时候，`check` 必须是 null ——
+    // 否则 doctor 会从插件锚点解析一个本插件不依赖的包，然后把"解析不到"写成"宿主缺失"
+    // （2026-10-17 `connection.admit` 的误报正是这条路径）。null 让它落到 `runtime-only`：
+    // 「只能对活的宿主查」是事实，"missing" 不是。
+    const checkableByStaticView = spec.staticWhen === undefined || spec.staticWhen();
     return {
         id: spec.id,
         label: spec.label,
@@ -230,7 +244,7 @@ export const CAPABILITY_STATIC = CAPABILITY_SPECS.map((spec) => {
         optional: spec.optional === true,
         // A `fields`-only spec (instance Maps) and a spec whose judgement lives in
         // its `probe` have nothing a prototype can answer — they stay runtime-only.
-        check: ref !== undefined && methods !== undefined && methods.length > 0
+        check: checkableByStaticView && ref !== undefined && methods !== undefined && methods.length > 0
             ? { pkg: ref.pkg, target: ref.target, members: methods }
             : null,
     };
@@ -272,6 +286,15 @@ export function assessHost(ctx) {
     const registry = unwrap(get('workspaceRegistry'));
     const cache = unwrap(get('sessionProjectionCache'));
     const sessions = unwrap(ctx.sessions !== undefined ? ctx.sessions : get('sessions'));
+    // tools 走 ctx 属性优先（它在插件 inject 清单里）。它有两层取法：宿主平面的 ctx.tools
+    // 与**子代理 scope 里**的那个（restrict 在子 scope 上才作用于该子代理，run-provider.ts
+    // 就是 `childAgent.ctx.get('tools')` 取的）。探测只能看宿主平面那一层 —— 子 scope 还没建。
+    const tools = unwrap(ctx.tools !== undefined ? ctx.tools : get('tools'));
+    // agent 作用域：探测对象是 agent 自己的 ctx（`on` 挂在它上面）。这里没有活的 agent 可看，
+    // 所以拿宿主平面的 ctx 代答 —— 同一个类实例链上的成员存在性，`on` 改名时两边一起改。
+    // 局限如实标注：探得到"on 在不在"，探不到"agent/created 是否仍串行"。
+    const agentContext = ctx;
+    const connection = unwrap(get('connection'));
     // settings 走 ctx 属性优先（插件 inject 清单里的正式服务），roster 走服务名查找
     // （'agentPresets' 与 preset-reach.ts 的 presetRosterOf 同名 —— 注入矩阵实际用的就是它）。
     const settings = unwrap(ctx.settings !== undefined ? ctx.settings : get('settings'));
@@ -287,6 +310,9 @@ export function assessHost(ctx) {
         settings: { target: settings, reference: references.settings },
         presetRoster: { target: roster, reference: references.roster },
         fs: { target: fsService, reference: undefined },
+        tools: { target: tools, reference: references.tools },
+        agentContext: { target: agentContext, reference: undefined },
+        connection: { target: connection, reference: references.connection },
     };
     const findings = CAPABILITY_SPECS.map((spec) => {
         const slot = targets[spec.owner];
@@ -308,6 +334,8 @@ export function assessHost(ctx) {
     let pluginRealpathNote = null;
     let asarHostVersion = null;
     let asarPluginVersion = null;
+    // 宿主非 peer 契约只跟"宿主装在哪"有关，与下面那个逐包 identity 循环无关，先量一次。
+    const contracts = hostContractStatus(hostRoot);
     for (const name of IDENTITY_PACKAGES) {
         const resolved = safeResolve(name);
         modules[name] = resolved;
@@ -424,6 +452,49 @@ export function assessHost(ctx) {
         degraded,
         mayDelete: delta,
         generatedAt: Date.now(),
+        ...(contracts === null ? {} : { contracts }),
+    };
+}
+/**
+ * 宿主**非 peer** 契约的实况：插件按裸模块名 require 的那几个官方包，宿主还暴不暴露、
+ * 入口里那几条 canary 还在不在。
+ *
+ * 为什么在探测里量而不是只在 doctor 里量：doctor 是"没有活宿主"的静态视图，而兼容页看到的是
+ * 正在跑的宿主。升级 DSH 后第一眼该看见的正是这一块 —— 官方撤掉某个包时**不抛错**，功能只是
+ * 少一半，除此之外没有任何信号。
+ *
+ * 口径从宿主安装锚点解析（不是插件侧）：这些包**不是**本插件的 peer，插件 `node_modules`
+ * 里通常没有，从插件侧解析只会得到一律"解析不到"，那不是一个结论。
+ *
+ * @param hostRoot - `.../node_modules/@deepseek-ai` 或 `null`（找不到宿主）。
+ */
+function hostContractStatus(hostRoot) {
+    if (hostRoot === null)
+        return null;
+    const packages = BARE_HOST_MODULE_CONTRACTS.map((contract) => {
+        let resolved = null;
+        try {
+            resolved = createRequire(join(dirname(hostRoot), 'package.json')).resolve(contract.package);
+        }
+        catch {
+            resolved = null;
+        }
+        let missingMarkers = [];
+        if (resolved !== null && contract.markers.length > 0) {
+            try {
+                const source = readFileSync(resolved, 'utf8');
+                missingMarkers = contract.markers.filter((marker) => !source.includes(marker.needle)).map((marker) => marker.needle);
+            }
+            catch { /* 入口读不到时只报"解析不到"，不额外造一条 canary 结论 */ }
+        }
+        return { package: contract.package, feature: contract.feature, resolved, missingMarkers };
+    });
+    return {
+        packages,
+        missing: packages.filter((item) => item.resolved === null).map((item) => item.package),
+        drifted: packages
+            .filter((item) => item.missingMarkers.length > 0)
+            .map((item) => ({ package: item.package, missingMarkers: item.missingMarkers })),
     };
 }
 /**