dsh-plugin-tool-management 0.16.6 → 0.18.0

package/lib/compat/probe.js

@@ -30,18 +30,18 @@
  * leave the rest working.
  */
 import { createRequire } from 'node:module';
-import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { existsSync } 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';
+// 宿主安装根的发现与「该走哪条恢复路」的判定 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';
 /** Packages whose physical module identity matters to this plugin. */
-export const IDENTITY_PACKAGES = [
-    '@deepseek-ai/cordis',
-    '@deepseek-ai/dsh-tools',
-    '@deepseek-ai/dsh-workspace',
-    '@deepseek-ai/dsh-session-projection-cache',
-    '@deepseek-ai/dsh-storage-domain',
-    '@deepseek-ai/dsh-spill-local',
-];
 /**
  * 本插件是不是从**源码检出**跑起来的（仓库里那份，`scripts/host-deps.mjs` 就躺在旁边）。
  *
@@ -55,17 +55,33 @@ export function isSourceInstall() {
     return SOURCE_INSTALL;
 }
 /**
- * peer range 与已验证版本。官方全程走 prerelease 渠道（x.y.z-rc.N），semver 的
- * 预发布规则（prerelease 版本只匹配同 [major,minor,patch] 元组的比较器）意味着**每一代
- * rc 都要显式列进范围**：`>=0.1.5-rc.2` 匹配不了 `0.1.7-rc.2`（实测），所以范围是逐代
- * 枚举的并集。上界依旧不设：宿主跨代升级由运行时能力探测兜底（见下）。
+ * peer range 与已验证版本。
  *
- * 0.2.0-rc.2（桌面版首发）已实测通过：`assessHost` 18/18 全通过，宿主版本读得出来，
+ * 官方全程走 prerelease 渠道（x.y.z-rc.N），而 semver 有一条硬规则：**带 prerelease 标签的
+ * 版本，只有在"同 [major,minor,patch] 元组"的比较器也带 prerelease 标签时才能匹配**。所以
+ * `>=0.1.5-rc.2` 匹配不了 `0.1.7-rc.2`，`^0.2.0-rc.2` 也匹配不了 `0.2.1-rc.1`（实测：
+ * `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 时把插件挡在门外 —— 与"不设上界"自相矛盾）。
+ *
+ * 2026-09-30 审查 §5 F9 + §5.4：这一段此前与 `package.json` 的 peerDependencies **漂移**成
+ * 两种写法（这里是 `^` 三段、那里是 `>=` 两段，且下界不同）。现在两处是**同一个字符串**，
+ * 并由 `test/contracts.test.mjs` 的一条断言钉住 —— 漂移会让"界面/doctor 报的范围"与
+ * "安装期实际校验的范围"各说各话，而两者都自称是插件的兼容范围。
+ *
+ * 已知且**无法**用 range 消除的缺口（如实标注）：尚未枚举的新 rc 元组（如 0.2.1-rc.1）
+ * 在 npm7+ 下会触发 ERESOLVE 告警。这不是写法问题 —— semver 规则决定了不存在能匹配
+ * "任意未来 prerelease"的 range。缓解方式：README 写明宿主升级时同步这段范围，
+ * 以及 `--legacy-peer-deps` 这条逃生门。
+ *
+ * 0.2.0-rc.2（桌面版首发）已实测通过：`assessHost` 全通过，宿主版本读得出来，
  * 归档宿主的身份判定见 `hostPackageRoot` / `isAsarPath`。所以它同时进范围与「已验证」。
  */
-export const EXPECTED_PEER_RANGE = '^0.1.5-rc.2 || ^0.1.7-rc.2 || ^0.2.0-rc.2';
+export const EXPECTED_PEER_RANGE = '>=0.1.7-rc.2 || >=0.2.0-rc.1';
 /** The release this plugin's adapters were last verified against. */
-export const VERIFIED_HOST_VERSION = '0.2.0-rc.2';
 /**
  * peer range 的下界。
  *
@@ -80,550 +96,6 @@ export const VERIFIED_HOST_VERSION = '0.2.0-rc.2';
  * `compat-status` 的载荷，doctor 与外部脚本可能仍在读。
  */
 export const EXPECTED_MIN_HOST_VERSION = EXPECTED_PEER_RANGE.match(/(\d+\.\d+\.\d+(?:-rc\.\d+)?)/)?.[1] ?? VERIFIED_HOST_VERSION;
-const isFn = (value) => typeof value === 'function';
-/**
- * Resolve a package the way this plugin resolves it, without throwing.
- *
- * `import.meta.resolve` 给的是**URL**：目录里带空格的路径（桌面版装在
- * `D:\DeepSeek Harness\...`）会以 `%20` 形式回来，直接当路径用会得到一个
- * 永远打不开的名字 —— 版本号读不出来（显示 `unknown`）、asar 路径也匹配不上。
- * 用 `fileURLToPath` 老实解码（它同时处理盘符与百分号转义）。
- */
-function safeResolve(specifier) {
-    try {
-        return fileURLToPath(import.meta.resolve(specifier));
-    }
-    catch {
-        try {
-            return createRequire(import.meta.url).resolve(specifier);
-        }
-        catch {
-            return null;
-        }
-    }
-}
-/**
- * Whether a path lives inside an electron `app.asar` archive.
- *
- * 桌面版把整个 DSH 装进 `resources/app.asar`：宿主的 `@deepseek-ai/*` 物理上就在
- * 归档里，插件（装在 `$DSH_HOME/profiles/<name>/node_modules`）在外面的磁盘上。
- * 归档里的模块**不可能**与外面的目录是同一个物理文件，`@deepseek-ai/*` 又是
- * peer（官方包由宿主提供），所以「不同路径」是这种打包方式的必然结果，不是安装
- * 故障。判据取 `.asar` 这个路径段（`join` 出来的分隔符在 Windows 上是 `\`）。
- */
-function isAsarPath(value) {
-    if (value === null)
-        return false;
-    return /[\\/][^\\/]+\.asar[\\/]/i.test(value);
-}
-/**
- * Resolve a path through every junction/symlink to its physical file.
- * Node loads modules by real path, so two different-looking paths that
- * realpath to one file ARE the same module — which is exactly the property
- * this plugin depends on, and the reason `@deepseek-ai/*` is junctioned into
- * the host installation instead of being copied.
- *
- * 取不到真实形态时**不再拿输入去比**（issue #1 要求）：那会把「路径不可解析」
- * 伪装成「两份不同拷贝」，给出一个编出来的结论。改由调用方把原因报成说明。
- */
-function realPathWithReason(value) {
-    if (value === null)
-        return { reason: '路径为空' };
-    try {
-        return { path: realpathSync.native !== undefined ? realpathSync.native(value) : realpathSync(value) };
-    }
-    catch (error) {
-        const detail = error;
-        const code = typeof detail.code === 'string' ? detail.code : '';
-        const message = typeof detail.message === 'string' ? detail.message : String(error);
-        return { reason: code === '' ? message : `${code} ${message}` };
-    }
-}
-/** Read a package version from a resolvable manifest. */
-function versionOf(specifier) {
-    const entry = safeResolve(specifier);
-    if (entry === null)
-        return undefined;
-    let dir = dirname(entry);
-    for (let i = 0; i < 4; i += 1) {
-        try {
-            const parsed = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
-            if (parsed.name === specifier && typeof parsed.version === 'string')
-                return parsed.version;
-        }
-        catch {
-            /* keep walking up */
-        }
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return undefined;
-}
-/**
- * Version of the package a resolved entry path belongs to: walk up until a
- * `package.json` whose `name` matches the package directory we came from.
- *
- * 与 `versionOf` 的分工：那个从**说明符**出发（要能解析），这个从**已经拿到的路径**
- * 出发。归档宿主那种「路径不同但版本相同」的判断只能用后者 —— 前者在 `.asar` 里
- * 读得动，但两边路径不同时它无法回答「这两个文件各属于哪个版本」。
- */
-function versionOfPackageAt(entry) {
-    const expected = packageNameOfPath(entry);
-    let dir = dirname(entry);
-    for (let i = 0; i < 5; i += 1) {
-        try {
-            const parsed = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
-            if (typeof parsed.version === 'string' && (expected === null || parsed.name === expected))
-                return parsed.version;
-        }
-        catch { /* keep walking up */ }
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    return null;
-}
-/** `.../node_modules/@scope/name/lib/index.js` -> `@scope/name` (null when the path has no such segment). */
-function packageNameOfPath(entry) {
-    const parts = entry.split(/[\\/]/);
-    const at = parts.lastIndexOf('node_modules');
-    if (at === -1 || at + 1 >= parts.length)
-        return null;
-    const first = parts[at + 1];
-    if (first === undefined)
-        return null;
-    if (first.startsWith('@')) {
-        const second = parts[at + 2];
-        return second === undefined ? null : `${first}/${second}`;
-    }
-    return first;
-}
-/**
- * Compare a live member with this plugin's copy of the implementation.
- * `undefined` means "not comparable" — the member is absent on the live object
- * or the reference copy does not have it either.
- */
-function textMatchOf(live, reference) {
-    if (!isFn(live) || !isFn(reference))
-        return undefined;
-    if (live === reference)
-        return true;
-    try {
-        return Function.prototype.toString.call(live) === Function.prototype.toString.call(reference);
-    }
-    catch {
-        return undefined;
-    }
-}
-/**
- * The prototype that defines a live instance's members, following the prototype
- * chain so proxies, subclass instances and cross-realm objects all answer
- * honestly.
- */
-function prototypeOf(instance) {
-    if (instance === null || typeof instance !== 'object')
-        return undefined;
-    if (typeof instance === 'function')
-        return instance;
-    const proto = Object.getPrototypeOf(instance);
-    return proto !== null && typeof proto === 'object' ? proto : undefined;
-}
-// The official package + class each capability owner's members live on. This is
-// the single answer to "which class defines this owner" — both the live
-// reference-prototype lookup below and the exported static table read it, so a
-// host drift is described in exactly one place.
-const WORKSPACE_CLASS = { pkg: '@deepseek-ai/dsh-workspace', target: 'WorkspaceRegistry' };
-const PROJECTION_CLASS = { pkg: '@deepseek-ai/dsh-session-projection-cache', target: 'SessionProjectionCache' };
-// `sessions.*` members are host-private members, but they are still declared on
-// an official class: `@deepseek-ai/dsh-session` is a peer this plugin declares,
-// and `SessionStore` is where `flush`/`liveEntryFor`/`detachEntered`/`enter`/
-// `announce` live. Without this entry the doctor could not see the two
-// capabilities the delete route depends on.
-const SESSIONS_CLASS = { pkg: '@deepseek-ai/dsh-session', target: 'SessionStore' };
-// 0.15.0 新增的两块契约面 —— 恰是 0.1.7 升级咬人的两处（prepareDocument 返回语义变了、
-// read 改名 readDocument），此前不在表里，故障只能靠用户实测发现。类名按官方安装源码核对
-// （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' };
-const OWNER_CLASSES = {
-    workspace: WORKSPACE_CLASS,
-    projectionCache: PROJECTION_CLASS,
-    sessions: SESSIONS_CLASS,
-    settings: SETTINGS_CLASS,
-    presetRoster: ROSTER_CLASS,
-};
-/** The named export's prototype, or undefined when the package is absent/trimmed. */
-function classPrototypeOf(ref) {
-    try {
-        const mod = createRequire(import.meta.url)(ref.pkg);
-        const klass = mod[ref.target];
-        return klass?.prototype;
-    }
-    catch {
-        return undefined; // optional in tests and in trimmed deployments
-    }
-}
-/**
- * 哨兵值：不可能命中任何真实会话/工作区（会话 id 由宿主生成，不含此串）。
- * 行为探针真调宿主方法时一律传它 —— 最坏情形是宿主受控拒绝（not found），
- * 而「哨兵输入都能产生意外效果」本身就是要探出来的「不该路由信任」。
- */
-const PROBE_SENTINEL = '__dshm_probe_never_exists__';
-/**
- * 用哨兵实参**真调**一个宿主方法（2026-09-19 分层探针第二层），验证「存在且可调用」：
- * - 同步抛 `TypeError` → 实现坏了/签名漂移，返回失败详情（shape-mismatch）；
- * - 受控同步拒绝（普通 `Error`，如 not found）或返回值（含 rejected Promise）→ 通过。
- *
- * 只判同步段：探针框架是同步的（`assessHost` 不能 await），异步结果分类留待
- * 异步化改造（见审查 07 跟进项）。返回的 Promise 一律挂 `.catch` 吞掉，探针
- * 不制造 unhandled rejection。调用必须以 `target` 为 receiver —— 私有方法全靠
- * `this.*` 拿内部状态，脱离 receiver 调用会把好实现误判成 TypeError。
- *
- * 副作用口径（按官方源码逐个核过）：liveEntryFor/announce/flush 哨兵输入在
- * 查表处受控抛错，零副作用；detachEntered 传普通对象在未知 id 处早退；
- * deleteSession/archiveSession 等原生入口对未知 id 是读路径校验后受控拒绝。
- * `enter` 不在此列（会往 store 里写哨兵条目），它只做存在性 + 文本比对。
- */
-function callableWithSentinel(target, name, ...args) {
-    try {
-        const method = target[name];
-        if (!isFn(method))
-            return `${name} 不是函数（methods 检查应已拦下，此处兜底）`;
-        const returned = method.call(target, ...args);
-        if (returned !== null && typeof returned === 'object' && isFn(returned.then)) {
-            const settled = returned;
-            if (isFn(settled.catch))
-                settled.catch(() => { });
-        }
-        return undefined;
-    }
-    catch (error) {
-        if (error instanceof TypeError)
-            return `${name} 哨兵真调抛 TypeError：${String(error?.message ?? error)}`;
-        return undefined;
-    }
-}
-/** Official prototypes this plugin's adapters mirror, when importable. */
-function referencePrototypes() {
-    const out = {};
-    const workspace = classPrototypeOf(WORKSPACE_CLASS);
-    if (workspace !== undefined)
-        out.workspace = workspace;
-    const cache = classPrototypeOf(PROJECTION_CLASS);
-    if (cache !== undefined)
-        out.cache = cache;
-    // sessions 的五个私有方法全声明在官方 SessionStore.prototype 上（本插件 peer 依赖
-    // 同包同版本），与 workspace/cache 同机制接入文本比对 —— 此前该域只有存在性检查。
-    const sessions = classPrototypeOf(SESSIONS_CLASS);
-    if (sessions !== undefined)
-        out.sessions = sessions;
-    // 两块新契约面的参考副本：包不在 devDeps/宿主锚点里时优雅缺省（textMatch 记 undefined），
-    // 存在性探测不依赖它们。
-    const settings = classPrototypeOf(SETTINGS_CLASS);
-    if (settings !== undefined)
-        out.settings = settings;
-    const roster = classPrototypeOf(ROSTER_CLASS);
-    if (roster !== undefined)
-        out.roster = roster;
-    return out;
-}
-/**
- * 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
- * missing member produces a named, visible degradation instead of a throw from
- * somewhere in the middle of a delete sequence.
- */
-const CAPABILITY_SPECS = [
-    // ---- workspace registry: read side -------------------------------------
-    {
-        id: 'workspace.read-state',
-        label: '读取工作区状态',
-        kind: 'read',
-        owner: 'workspace',
-        fallback: 'refuse-operation',
-        methods: ['requireState'],
-        probe: (t) => {
-            try {
-                const state = t.requireState();
-                if (state === null || typeof state !== 'object')
-                    return 'requireState() 未返回对象';
-                const value = state;
-                if (!Array.isArray(value.archivedSessionIds))
-                    return 'requireState().archivedSessionIds 不是数组';
-                if (!Array.isArray(value.workspaceIds))
-                    return 'requireState().workspaceIds 不是数组';
-                return undefined;
-            }
-            catch (error) {
-                return `requireState() 抛错：${String(error?.message ?? error)}`;
-            }
-        },
-    },
-    {
-        id: 'workspace.read-table',
-        label: '读取工作区表',
-        kind: 'read',
-        owner: 'workspace',
-        fallback: 'refuse-operation',
-        methods: ['requireTable'],
-        probe: (t) => {
-            try {
-                const table = t.requireTable();
-                if (table === null || typeof table !== 'object' || !isFn(table.get))
-                    return 'requireTable() 未返回可 get 的表';
-                return undefined;
-            }
-            catch (error) {
-                return `requireTable() 抛错：${String(error?.message ?? error)}`;
-            }
-        },
-    },
-    {
-        id: 'workspace.index-shape',
-        label: '工作区索引结构',
-        kind: 'read',
-        owner: 'workspace',
-        fallback: 'refuse-operation',
-        fields: [
-            { name: 'headers', instanceOf: 'Map' },
-            { name: 'sessionPaths', instanceOf: 'Map' },
-            { name: 'invalidSessionPaths', instanceOf: 'Map' },
-            { name: 'entities', instanceOf: 'Map' },
-        ],
-    },
-    {
-        id: 'workspace.read-header',
-        label: '读取会话头部',
-        kind: 'read',
-        owner: 'workspace',
-        fallback: 'refuse-operation',
-        methods: ['readSessionHeader'],
-    },
-    // ---- workspace registry: write side ------------------------------------
-    {
-        id: 'workspace.enqueue',
-        label: '串行写事务',
-        kind: 'write',
-        owner: 'workspace',
-        fallback: 'disable-destructive',
-        methods: ['enqueueOperation'],
-    },
-    {
-        id: 'workspace.set-state',
-        label: '写工作区状态',
-        kind: 'write',
-        owner: 'workspace',
-        fallback: 'disable-destructive',
-        methods: ['setState'],
-    },
-    {
-        id: 'workspace.index-header',
-        label: '索引会话头部',
-        kind: 'write',
-        owner: 'workspace',
-        fallback: 'disable-destructive',
-        methods: ['indexHeader'],
-    },
-    {
-        id: 'workspace.archive-native',
-        label: '宿主原生归档入口',
-        kind: 'write',
-        owner: 'workspace',
-        fallback: 'native-entry',
-        methods: ['archiveSession'],
-        optional: true,
-        // 分层探针第二层（哨兵真调）：官方实现对未知 id 走读路径校验后受控拒绝
-        //（WorkspaceUnknownSessionError）；同步 TypeError 才是「不该路由信任」的信号。
-        probe: (t) => callableWithSentinel(t, 'archiveSession', PROBE_SENTINEL),
-    },
-    {
-        id: 'workspace.unarchive-native',
-        label: '宿主原生恢复入口',
-        kind: 'write',
-        owner: 'workspace',
-        fallback: 'native-entry',
-        methods: ['unarchiveSession'],
-        optional: true,
-        probe: (t) => callableWithSentinel(t, 'unarchiveSession', PROBE_SENTINEL),
-    },
-    {
-        id: 'workspace.batch-native',
-        label: '宿主原生批量入口',
-        kind: 'write',
-        owner: 'workspace',
-        fallback: 'native-entry',
-        methods: ['archiveWorkspaceSessions'],
-        optional: true,
-        probe: (t) => callableWithSentinel(t, 'archiveWorkspaceSessions', [PROBE_SENTINEL]),
-    },
-    {
-        id: 'workspace.delete-native',
-        label: '宿主原生删除入口',
-        kind: 'delete',
-        owner: 'workspace',
-        // NOT `disable-destructive`: when this slot is empty the plugin performs the
-        // whole delete itself, so nothing is disabled. `native-entry` describes what
-        // actually happens (the adapter takes over).
-        fallback: 'native-entry',
-        methods: ['deleteSession'],
-        optional: true,
-        // 删除路由的 native 判定此前只看方法存在（07 审查五档问题 2）：宿主升级把同名
-        // 方法换成别的签名，路由仍会走 native 裸调。哨兵真调把口径提到「可调用」，
-        // 文本比对收紧（见 inspectCapability 的 delete 类分支）负责「实现漂移」那一层。
-        probe: (t) => callableWithSentinel(t, 'deleteSession', PROBE_SENTINEL),
-    },
-    // ---- sessions runtime (private members, used only on the live branch) ---
-    {
-        id: 'sessions.detach-live',
-        label: '实时会话落盘与分离',
-        kind: 'delete',
-        owner: 'sessions',
-        fallback: 'disable-destructive',
-        methods: ['flush', 'liveEntryFor', 'detachEntered'],
-        // 零副作用真调（按官方源码核对）：liveEntryFor/flush 对哨兵在查表处受控抛错；
-        // detachEntered 传普通对象在未知 id 处早退（entry 形状 {id} 即可）。
-        probe: (t) => callableWithSentinel(t, 'liveEntryFor', PROBE_SENTINEL)
-            ?? callableWithSentinel(t, 'flush', PROBE_SENTINEL)
-            ?? callableWithSentinel(t, 'detachEntered', { id: PROBE_SENTINEL }),
-    },
-    {
-        id: 'sessions.cold-announce',
-        label: '冷会话移除广播',
-        kind: 'delete',
-        owner: 'sessions',
-        fallback: 'disable-destructive',
-        methods: ['enter', 'announce'],
-        // announce 哨兵真调：内部先 liveEntryFor 查表，哨兵输入在查表处受控抛错。
-        // **enter 不真调**（官方实现对任意输入都会往 store 写入条目），它只有存在性 + 文本比对。
-        probe: (t) => callableWithSentinel(t, 'announce', PROBE_SENTINEL),
-    },
-    // ---- projection cache ---------------------------------------------------
-    {
-        id: 'projection.write',
-        label: '投影缓存写入路径',
-        kind: 'write',
-        owner: 'projectionCache',
-        fallback: 'disable-destructive',
-        methods: ['write', 'put', 'requireTable'],
-    },
-    {
-        // B2：此前它只是 bridge 运行时那句拒绝里的**临时 id**（`acquireCacheGuard` 里现场拼的），
-        // 于是客户端压根不知道它 —— 宿主表不可删时，"路由说可用、点下去必拒"（V13）。提升为
-        // 能力表的正式条目后，路由判定与运行时前提同一份依据。
-        id: 'projection.table-delete',
-        label: '投影缓存行删除',
-        kind: 'delete',
-        owner: 'projectionCache',
-        fallback: 'disable-destructive',
-        // 探测内容就是运行时那句硬前提：`requireTable().delete` 在不在。
-        probe: (target) => {
-            if (typeof target?.requireTable !== 'function')
-                return '宿主投影缓存缺少 requireTable';
-            let table;
-            try {
-                table = target.requireTable();
-            }
-            catch (error) {
-                return `宿主投影缓存 requireTable() 抛错：${String(error)}`;
-            }
-            if (typeof table?.delete !== 'function')
-                return '宿主投影缓存存储不支持安全删除（table.delete 缺失）';
-            return undefined;
-        },
-    },
-    {
-        id: 'projection.delete-native',
-        label: '投影缓存删除屏障',
-        kind: 'delete',
-        owner: 'projectionCache',
-        // Absent on rc.2: `sessions/bridge.ts` installs a checked write barrier
-        // instead, so absence is a routing fact, not a failure. Only a cache whose
-        // write path cannot be wrapped at all is a real problem.
-        fallback: 'native-entry',
-        optional: true,
-        probe: (t) => {
-            if (isFn(t?.delete) && isFn(t?.whenIdle))
-                return undefined;
-            const wrappable = ['write', 'put'].filter((name) => !isFn(t?.[name]));
-            if (wrappable.length > 0)
-                return `宿主缓存无法安全包裹（缺少 ${wrappable.join(', ')}）`;
-            let table;
-            try {
-                table = t.requireTable();
-            }
-            catch (error) {
-                return `requireTable() 抛错：${String(error?.message ?? error)}`;
-            }
-            if (!isFn(table?.delete))
-                return '宿主缓存存储不支持行删除（table.delete 缺失）';
-            return undefined;
-        },
-    },
-    // ---- settings document path（0.1.7 的两处适配面之一）----------------------
-    // `prepareDocument()` 在 0.1.7 把返回值从「主目录下的设置文档路径」改成「profile 补丁
-    // 路径」（`configEditor.documentPath`）—— 方法一直在、语义变了，方法存在性探测抓不住
-    // （0.15.0 的 MCP 页事故就是这么静默发生的）。这一条能拦的是「方法消失 / 签名漂移到
-    // 同步抛 TypeError」；**返回值形状**是异步结果，同步探针看不到，那一半由 ensurePaths
-    // 的 await 后自检负责（src/index.ts：认 profile 形状上溯 + 主目录不变量检查，异常走
-    // noteRuntime）。两半合起来才是这个契约的完整探测。
-    {
-        id: 'settings.document-path',
-        label: '设置文档路径（主目录推导源）',
-        kind: 'read',
-        owner: 'settings',
-        fallback: 'refuse-operation',
-        methods: ['prepareDocument'],
-        // 零副作用真调：官方实现就是 `Promise.resolve(this.documentPath)`，纯读。拿不到
-        // 异步结果没关系 —— 同步 TypeError（签名漂移）才是这一层要拦的。
-        probe: (t) => callableWithSentinel(t, 'prepareDocument'),
-        // 健康行也常显观测路径（官方 SettingsForms 有同步的 `documentPath` getter，
-        // prepareDocument 就是它的 Promise 包装）：语义再变，页面上这行字一眼见底。
-        describe: (t) => {
-            try {
-                const p = t.documentPath;
-                return typeof p === 'string' && p !== '' ? `观测路径：${p}` : undefined;
-            }
-            catch {
-                return undefined;
-            }
-        },
-    },
-    // ---- agent preset roster（0.1.7 的两处适配面之二）-------------------------
-    // 0.1.7 把 `read(id)`（直返组合文本）改名成 `readDocument(id)`（返回文档对象，组合
-    // YAML 在 `.content`）。读取口是「read 优先、readDocument 兜底」双入口
-    // （preset-reach.ts 的 readCompositionText），两个名字**任一在场即可** —— 这正是
-    // methods 列表表达不了的 either-or，用 probe 写。list / composedPreset 缺一个，
-    // 注入边界矩阵与边界提示就瞎一半，同为必需。
-    {
-        id: 'preset.roster-surface',
-        label: '预设名册读取面',
-        kind: 'read',
-        owner: 'presetRoster',
-        fallback: 'inform-only',
-        probe: (t) => {
-            const o = t;
-            const hasRead = isFn(o.read);
-            const hasDoc = isFn(o.readDocument);
-            if (!hasRead && !hasDoc)
-                return 'read 与 readDocument 都缺失：组合文本读不到，注入边界矩阵与极简兜底注入失明';
-            const missing = ['list', 'composedPreset'].filter((name) => !isFn(o[name]));
-            if (missing.length > 0)
-                return `名册缺少 ${missing.join(', ')}：注入边界矩阵不完整`;
-            return undefined;
-        },
-        // 健康行附注实际走的读取路。0.1.7 起 `read` 改名 `readDocument`，兜底成功是**正常形态**
-        // 而非降级 —— 这句话只出现在绿色行上（运行时上报会渲染成问题行，那里不放）。
-        describe: (t) => {
-            const o = t;
-            if (!isFn(o.read) && isFn(o.readDocument))
-                return '读取走 readDocument（宿主 0.1.7 起的形态）';
-            return undefined;
-        },
-    },
-];
 /**
  * The capability sets each operation depends on, grouped by how the plugin
  * reaches the same outcome when a member is missing. Order matters: the first
@@ -633,33 +105,7 @@ const CAPABILITY_SPECS = [
  * - `adapter`: the checked compatibility adapter (the only route that touches
  *   private members), used when the host has no native entry.
  */
-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'] },
-    batch: { native: ['workspace.batch-native'], adapter: ['workspace.enqueue', 'workspace.set-state'] },
-    delete: {
-        native: ['workspace.delete-native'],
-        // NOTE: `projection.delete-native` is deliberately NOT a route requirement.
-        // A host cache without its own delete barrier is expected on rc.2; the
-        // bridge wraps it (`workspace.js` / `sessions/bridge.ts`) and reports a
-        // refusal itself when even that is impossible. Requiring the native barrier
-        // here would disable deletion on exactly the host this plugin was verified
-        // against.
-        adapter: [
-            'workspace.enqueue', 'workspace.set-state', 'workspace.index-header',
-            'sessions.detach-live', 'sessions.cold-announce', 'projection.write',
-            // B2：运行时硬前提（`table.delete`）也算一条路由要求 —— 不算进来的话，宿主表不可删时
-            // 路由说可用、点下去必拒。batch 的 adapter 路由**有意**保持只有 enqueue/set-state：
-            // 它的逐条失败会在结果里按 sessionId 报出来，此处不放宽也不收紧。
-            'projection.table-delete',
-        ],
-    },
-    list: { native: [], adapter: ['workspace.read-state', 'workspace.read-table', 'workspace.index-shape'] },
-};
 /** Texts a user can act on, per capability, when it is the reason for a refusal. */
-function recoveryFor(_finding) {
-    return `宿主 ${VERIFIED_HOST_VERSION} 的该项能力未通过探测；请更新本插件到与本机 DSH 匹配的版本，或改用宿主原生入口（先运行 node scripts/doctor.mjs 查看差异）。`;
-}
 /**
  * One capability's result. `target` is the live host object; `reference` is
  * this plugin's copy of the same implementation when the package is importable.
@@ -830,6 +276,8 @@ export function assessHost(ctx) {
     // （'agentPresets' 与 preset-reach.ts 的 presetRosterOf 同名 —— 注入矩阵实际用的就是它）。
     const settings = unwrap(ctx.settings !== undefined ? ctx.settings : get('settings'));
     const roster = unwrap(get('agentPresets'));
+    // fs 走 ctx 属性优先（它在插件 inject 清单里），与 settings 同一条取法。
+    const fsService = unwrap(ctx.fs !== undefined ? ctx.fs : get('fs'));
     const references = referencePrototypes();
     const targets = {
         workspace: { target: registry, reference: references.workspace },
@@ -838,6 +286,7 @@ export function assessHost(ctx) {
         persistence: { target: unwrap(get('sessionPersistence')), reference: undefined },
         settings: { target: settings, reference: references.settings },
         presetRoster: { target: roster, reference: references.roster },
+        fs: { target: fsService, reference: undefined },
     };
     const findings = CAPABILITY_SPECS.map((spec) => {
         const slot = targets[spec.owner];
@@ -991,50 +440,30 @@ export function assessHost(ctx) {
  * 调用方：从锚点解析不到的包会被判成 `same = null`，见 assessHost 里的 `unverified`。
  */
 function hostPackageRoot() {
-    // 与 doctor 的 `findHost` **同一套策略**（先看 `$DSH_HOME/profiles/node_modules/@deepseek-ai`，
-    // 再从插件自身位置逐级上溯，最后扫 npx 缓存，并确认那一层里真有 `dsh/package.json`）。此前运行时只按"插件
-    // 自己解析到的包"上溯，dev 布局下会把仓库里的副本当成宿主锚点、比出假的 `true` —— 于是
-    // 界面说 ok、doctor 说 SEPARATE COPY（V8）。两处口径分裂本身就是缺陷。
-    const home = process.env.DSH_HOME || join(process.env.USERPROFILE || process.env.HOME || '', '.dsh');
-    const candidates = [];
-    if (home !== '')
-        candidates.push(join(home, 'profiles', 'node_modules', '@deepseek-ai'));
-    // 桌面版：整个 DSH 装进 `resources/app.asar`，宿主的 `@deepseek-ai/*` 就在归档里。
-    // 这一候选必须排在 npx 缓存**之前** —— 否则装过 web 版的机器上会先命中 npx 缓存里
-    // 那个 0.1.7，于是拿「另一个安装」当锚点比出 6 条假的「两份不同拷贝」（实测事故）。
-    const asarHost = asarHostPackageRoot();
-    if (asarHost !== null)
-        candidates.push(asarHost);
-    for (const anchor of IDENTITY_PACKAGES) {
-        // 锚点候选只认**真实形态**：取不到就跳过（这里没有可比的对象，如实跳过即可，
-        // 与身份比对不同 —— 那边取不到必须报出来，见 assessHost 的 realpath 说明）。
-        const real = realPathWithReason(safeResolve(anchor));
-        if ('reason' in real)
-            continue;
-        const resolved = real.path;
-        let dir = dirname(resolved);
-        for (let i = 0; i < 4; i += 1) {
-            if (dir.endsWith(join('node_modules', '@deepseek-ai'))) {
-                candidates.push(dir);
-                break;
-            }
-            const parent = dirname(dir);
-            if (parent === dir)
-                break;
-            dir = parent;
-        }
-    }
-    // 0.1.7 起宿主不再维护 `profiles/node_modules` 那棵 junction 树（link-backend 已移除），
-    // `dsh web` 经 npx 跑在 `<npm 缓存>/_npx/<hash>/node_modules` 里 —— 缓存扫描是 dev 场景
-    // （上溯只找到 checkout 自己的副本）下最后的宿主发现手段。多命中时取最新（npx 升级会
-    // 换 hash 目录、删旧目录）。
-    candidates.push(...npxCacheHostRoots());
-    for (const candidate of candidates) {
+    for (const candidate of hostRootCandidates()) {
         if (existsSync(join(candidate, 'dsh', 'package.json')))
             return candidate;
     }
     return null;
 }
+/**
+ * 宿主 `@deepseek-ai` 目录的**候选序列**（按优先级）—— 全仓"宿主在哪"的唯一口径。
+ *
+ * 为什么单独导出（2026-09-30 审查 §5 F10）：运行时（本文件）与 `scripts/doctor.mjs` /
+ * `scripts/host-deps.mjs` 此前**各写一份**，而且顺序不一样 —— doctor 少了桌面版那一条，
+ * 于是在桌面宿主上要么报 "host installation not found"，要么拿 npx 缓存里**另一代宿主**
+ * 当锚点比出假 SEPARATE COPY。那正是本文件注释里记过的实测事故，只修了运行时。
+ *
+ * 顺序是有讲究的：
+ *   ① 桌面版归档（`resources/app.asar`）—— 必须排在 npx 缓存**之前**，否则装过 web 版的
+ *      机器上会先命中缓存里那个 0.1.7；
+ *   ② `$DSH_HOME/profiles/node_modules/@deepseek-ai`（web 版旧布局的 junction 树）；
+ *   ③ 从本插件自身解析到的锚点逐级上溯（dev 布局：仓库/安装目录自己的 node_modules）；
+ *   ④ npx 缓存（`dsh web` 经 npx 跑时的落点；多命中取最新）。
+ *
+ * 只列候选、不判存在性：调用方各有自己的"像不像一份安装"的判据（运行时要求
+ * `dsh/package.json`，host-deps 还要读出版本号）。
+ */
 /**
  * 正在运行的桌面版 DSH 的 `@deepseek-ai` 目录（在 `resources/app.asar` 里），没有则 null。
  *
@@ -1042,59 +471,11 @@ function hostPackageRoot() {
  * 包名或环境变量猜，因此在 `dsh web`（node 跑）下一律返回 null。归档内路径由 electron
  * 自己的 fs 修补解析，归档外的普通 node 读不到，所以这一步失败是静默的正常路径。
  */
-function asarHostPackageRoot() {
-    const resources = process.resourcesPath;
-    if (typeof resources !== 'string' || resources === '')
-        return null;
-    const dir = join(resources, 'app.asar', 'dsh', 'node_modules', '@deepseek-ai');
-    try {
-        if (!existsSync(join(dir, 'dsh', 'package.json')))
-            return null;
-    }
-    catch {
-        return null;
-    }
-    return dir;
-}
 /**
  * npx 缓存里的宿主 `@deepseek-ai` 目录，按目录 mtime 新到旧排。npm 缓存位置依次看
  * `npm_config_cache`、`~/.npmrc` 的 `cache=`、`%LOCALAPPDATA%\npm-cache` —— probe 全程同步，
  * 不起子进程，读不到就当没有这批候选。
  */
-function npxCacheHostRoots() {
-    const home = process.env.USERPROFILE || process.env.HOME || '';
-    let cache = process.env.npm_config_cache || '';
-    if (!cache && home) {
-        try {
-            const rc = readFileSync(join(home, '.npmrc'), 'utf8');
-            cache = rc.match(/^\s*cache\s*=\s*(.+?)\s*$/m)?.[1] ?? '';
-        }
-        catch { /* no .npmrc — defaults below */ }
-    }
-    if (!cache && process.env.LOCALAPPDATA)
-        cache = join(process.env.LOCALAPPDATA, 'npm-cache');
-    if (!cache)
-        return [];
-    const roots = [];
-    const npxRoot = join(cache, '_npx');
-    let entries = [];
-    try {
-        entries = readdirSync(npxRoot);
-    }
-    catch {
-        return [];
-    }
-    for (const entry of entries) {
-        const dir = join(npxRoot, entry, 'node_modules', '@deepseek-ai');
-        if (!existsSync(join(dir, 'dsh', 'package.json')))
-            continue;
-        try {
-            roots.push({ dir, mtime: statSync(dir).mtimeMs });
-        }
-        catch { /* raced — skip */ }
-    }
-    return roots.sort((left, right) => right.mtime - left.mtime).map((root) => root.dir);
-}
 /** Human-readable summary line for logs and the settings page header. */
 export function summarize(assessment) {
     const total = assessment.findings.length;
@@ -1103,21 +484,7 @@ export function summarize(assessment) {
     return `宿主 ${assessment.identity.version} · 能力 ${ok}/${total} · ${state}`;
 }
 /** Findings by id, for route decisions. */
-export function findingsById(assessment) {
-    return new Map(assessment.findings.map((finding) => [finding.id, finding]));
-}
 /** Refusals for every degraded capability in the list, in list order. */
-export function refusalsFor(assessment, ids) {
-    const index = findingsById(assessment);
-    const out = [];
-    for (const id of ids) {
-        const finding = index.get(id);
-        if (finding === undefined || finding.state === 'ok')
-            continue;
-        out.push({ id: finding.id, label: finding.label, detail: finding.detail, recovery: recoveryFor(finding) });
-    }
-    return out;
-}
 /**
  * Choose how one operation should reach the host.
  *
@@ -1128,33 +495,6 @@ export function refusalsFor(assessment, ids) {
  * @param operation - operation name from {@link OPERATION_ROUTES}.
  * @returns the route to take plus, when `none`, what is missing and why.
  */
-export function routeFor(assessment, operation) {
-    const routes = OPERATION_ROUTES[operation];
-    const index = findingsById(assessment);
-    const allOk = (ids) => ids.every((id) => {
-        const finding = index.get(id);
-        // A capability that the host does not expose at all cannot block a route
-        // it is not part of; absent ids are treated as satisfied.
-        return finding === undefined || finding.state === 'ok';
-    });
-    if (routes.native.length > 0 && allOk(routes.native))
-        return { via: 'native', refusals: [] };
-    if (allOk(routes.adapter))
-        return { via: 'adapter', refusals: [] };
-    const needed = routes.native.length > 0 ? [...new Set([...routes.native, ...routes.adapter])] : routes.adapter;
-    const refusals = refusalsFor(assessment, needed);
-    if (refusals.length > 0)
-        return { via: 'none', refusals };
-    return {
-        via: 'none',
-        refusals: [{
-                id: operation,
-                label: operation,
-                detail: '宿主未提供该操作的任何可用路径',
-                recovery: recoveryFor({ id: operation }),
-            }],
-    };
-}
 /**
  * The error a refused operation throws. Kept as a distinct class so callers can
  * tell "the host cannot do this safely" from "the operation failed".