dsh-plugin-tool-management 0.9.1 → 0.11.0

package/lib/compat/preset-reach.js

@@ -56,6 +56,7 @@
  * exactly what its author asked for; the plugin's job is to say so out loud and
  * point at the switch that overrides it.
  */
+import { MCP_CLIENT_MODULE } from '../host-names.js';
 /** Whether a preset declares "no extra text": persona `complete: true` or runtime context off. */
 export function isSuppressingPreset(facts) {
     return facts.personaComplete === true || facts.includeRuntimeContext === false;
@@ -74,16 +75,6 @@ export function injectionFactsOf(facts) {
 const PERSONA_MODULE = '@deepseek-ai/dsh-persona';
 const AGENT_INSTRUCTIONS_MODULE = '@deepseek-ai/dsh-agent-instructions';
 const TOOL_SKILL_MODULE = '@deepseek-ai/dsh-tool-skill';
-/**
- * An MCP client mounted INSIDE a composition. The shipped presets mount none,
- * so MCP tools normally come from the host plane (the `$DSH_HOME/cordis.patch.yml`
- * layer) and are callable under every preset; a user-authored preset that mounts
- * its own client only carries those tools under itself, and this scan is how the
- * page can tell the two apart. Tool reachability is not the column's answer,
- * though — the server list and the user's notes are a prompt section, which a
- * complete persona suppresses whichever client serves the tools.
- */
-const MCP_CLIENT_MODULE = '@deepseek-ai/dsh-mcp-client';
 const NAME_LINE = /^(\s*)name:\s*(['"]?)([^'"\s#]+)\2\s*(?:#.*)?$/;
 const ENTRY_LINE = /^(\s*)-\s/;
 const DISABLED_LINE = /^\s*disabled:\s*(.+?)\s*(?:#.*)?$/;

package/lib/compat/probe.js

@@ -4,7 +4,7 @@
  *
  * WHY THIS REPLACES THE TEXT-COMPARISON GATE
  * ------------------------------------------
- * The previous gate in `history/bridge.js` compared each host method against
+ * The previous gate in `sessions/bridge.ts` compared each host method against
  * this plugin's own copy of the official prototype with
  * `Function.prototype.toString()`. That only ever answered one question —
  * "is the host running the same release I was written against?" — and it
@@ -139,22 +139,88 @@ function prototypeOf(instance) {
     const proto = Object.getPrototypeOf(instance);
     return proto !== null && typeof proto === 'object' ? proto : undefined;
 }
-/** Official prototypes this plugin's adapters mirror, when importable. */
-function referencePrototypes() {
-    const out = {};
+// 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' };
+const OWNER_CLASSES = {
+    workspace: WORKSPACE_CLASS,
+    projectionCache: PROJECTION_CLASS,
+    sessions: SESSIONS_CLASS,
+};
+/** The named export's prototype, or undefined when the package is absent/trimmed. */
+function classPrototypeOf(ref) {
     try {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const ws = createRequire(import.meta.url)('@deepseek-ai/dsh-workspace');
-        if (ws.WorkspaceRegistry?.prototype !== undefined)
-            out.workspace = ws.WorkspaceRegistry.prototype;
+        const mod = createRequire(import.meta.url)(ref.pkg);
+        const klass = mod[ref.target];
+        return klass?.prototype;
     }
-    catch { /* optional in tests and in trimmed deployments */ }
+    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 pc = createRequire(import.meta.url)('@deepseek-ai/dsh-session-projection-cache');
-        if (pc.SessionProjectionCache?.prototype !== undefined)
-            out.cache = pc.SessionProjectionCache.prototype;
+        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;
     }
-    catch { /* optional in tests */ }
+}
+/** 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;
     return out;
 }
 /**
@@ -170,7 +236,7 @@ const CAPABILITY_SPECS = [
         label: '读取工作区状态',
         kind: 'read',
         owner: 'workspace',
-        fallback: 'degrade-read',
+        fallback: 'refuse-operation',
         methods: ['requireState'],
         probe: (t) => {
             try {
@@ -194,7 +260,7 @@ const CAPABILITY_SPECS = [
         label: '读取工作区表',
         kind: 'read',
         owner: 'workspace',
-        fallback: 'degrade-read',
+        fallback: 'refuse-operation',
         methods: ['requireTable'],
         probe: (t) => {
             try {
@@ -213,7 +279,7 @@ const CAPABILITY_SPECS = [
         label: '工作区索引结构',
         kind: 'read',
         owner: 'workspace',
-        fallback: 'degrade-read',
+        fallback: 'refuse-operation',
         fields: [
             { name: 'headers', instanceOf: 'Map' },
             { name: 'sessionPaths', instanceOf: 'Map' },
@@ -226,7 +292,7 @@ const CAPABILITY_SPECS = [
         label: '读取会话头部',
         kind: 'read',
         owner: 'workspace',
-        fallback: 'degrade-read',
+        fallback: 'refuse-operation',
         methods: ['readSessionHeader'],
     },
     // ---- workspace registry: write side ------------------------------------
@@ -262,6 +328,9 @@ const CAPABILITY_SPECS = [
         fallback: 'native-entry',
         methods: ['archiveSession'],
         optional: true,
+        // 分层探针第二层（哨兵真调）：官方实现对未知 id 走读路径校验后受控拒绝
+        //（WorkspaceUnknownSessionError）；同步 TypeError 才是「不该路由信任」的信号。
+        probe: (t) => callableWithSentinel(t, 'archiveSession', PROBE_SENTINEL),
     },
     {
         id: 'workspace.unarchive-native',
@@ -271,6 +340,7 @@ const CAPABILITY_SPECS = [
         fallback: 'native-entry',
         methods: ['unarchiveSession'],
         optional: true,
+        probe: (t) => callableWithSentinel(t, 'unarchiveSession', PROBE_SENTINEL),
     },
     {
         id: 'workspace.batch-native',
@@ -280,6 +350,7 @@ const CAPABILITY_SPECS = [
         fallback: 'native-entry',
         methods: ['archiveWorkspaceSessions'],
         optional: true,
+        probe: (t) => callableWithSentinel(t, 'archiveWorkspaceSessions', [PROBE_SENTINEL]),
     },
     {
         id: 'workspace.delete-native',
@@ -292,6 +363,10 @@ const CAPABILITY_SPECS = [
         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) ---
     {
@@ -301,6 +376,11 @@ const CAPABILITY_SPECS = [
         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',
@@ -309,6 +389,9 @@ const CAPABILITY_SPECS = [
         owner: 'sessions',
         fallback: 'disable-destructive',
         methods: ['enter', 'announce'],
+        // announce 哨兵真调：内部先 liveEntryFor 查表，哨兵输入在查表处受控抛错。
+        // **enter 不真调**（官方实现对任意输入都会往 store 写入条目），它只有存在性 + 文本比对。
+        probe: (t) => callableWithSentinel(t, 'announce', PROBE_SENTINEL),
     },
     // ---- projection cache ---------------------------------------------------
     {
@@ -324,7 +407,7 @@ const CAPABILITY_SPECS = [
         label: '投影缓存删除屏障',
         kind: 'delete',
         owner: 'projectionCache',
-        // Absent on rc.2: `history/bridge.js` installs a checked write barrier
+        // 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',
@@ -365,7 +448,7 @@ export const OPERATION_ROUTES = {
         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` / `history/bridge.js`) and reports a
+        // 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.
@@ -437,6 +520,21 @@ function inspectCapability(spec, target, reference) {
             return { ...base, state: 'shape-mismatch', detail: failure, missing: [], ...(textMatch === undefined ? {} : { textMatch }) };
         }
     }
+    // 删除类收紧（2026-09-19，07 审查五档问题 2）：textMatch === false 意味着宿主运行的
+    // 不是本插件适配并验证过的实现（参考副本与宿主同源时恒真 —— junction 同物理文件；
+    // 只有宿主升级/漂移才会 false）。读/写类维持「按能力使用」的宽口径，但删除不可逆：
+    // 漂移的 flush/detachEntered/announce/deleteSession 一律不盲调，路由降级 adapter 或
+    // 拒绝，恢复文案引导更新插件。bridge.js 曾因无害重构误报而移除过文本比对 —— 本次
+    // 只收紧 delete 类，且参考副本不可解析时 textMatch 为 undefined，不拦截（优雅回退）。
+    if (textMatch === false && spec.kind === 'delete') {
+        return {
+            ...base,
+            state: 'shape-mismatch',
+            detail: '成员齐备但实现文本与本插件适配的版本不同：删除类能力不盲调漂移实现',
+            missing: [],
+            textMatch,
+        };
+    }
     return {
         ...base,
         state: 'ok',
@@ -458,6 +556,31 @@ function inspectCapability(spec, target, reference) {
 export const SUBSTITUTED_CAPABILITIES = CAPABILITY_SPECS
     .filter((spec) => spec.optional === true)
     .map((spec) => spec.id);
+/**
+ * The capability table as a *static* view: for each spec, the official class
+ * whose prototype must carry the required members. This exists so a CLI without
+ * a running host (the doctor) can still answer "can this build archive / delete /
+ * list?".
+ *
+ * Derived from {@link CAPABILITY_SPECS} — the previous hand-written second table
+ * drifted silently: it carried 9 of the 15 ids and missed every `sessions.*` and
+ * native-slot capability the routing actually needs.
+ */
+export const CAPABILITY_STATIC = CAPABILITY_SPECS.map((spec) => {
+    const ref = OWNER_CLASSES[spec.owner];
+    const methods = spec.methods;
+    return {
+        id: spec.id,
+        label: spec.label,
+        kind: spec.kind,
+        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
+            ? { pkg: ref.pkg, target: ref.target, members: methods }
+            : null,
+    };
+});
 /**
  * Inspect the live host behind one plugin context.
  *
@@ -478,6 +601,9 @@ export function assessHost(ctx) {
         }
     };
     // Cordis exposes traceable proxies; compare and inspect the original objects.
+    // `Symbol.for('cordis.original')` 与 cordis 导出的 `symbols.original` 是**同一个符号**
+    // （该包内即 `original: Symbol.for("cordis.original")`）。这里不 import cordis，是为了让
+    // 兼容探测在宿主包加载失败时仍能工作 —— 本文件对宿主零硬依赖（见文件头的 createRequire）。
     const unwrap = (value) => {
         if (value === null || typeof value !== 'object')
             return value;
@@ -496,7 +622,7 @@ export function assessHost(ctx) {
     const targets = {
         workspace: { target: registry, reference: references.workspace },
         projectionCache: { target: cache, reference: references.cache },
-        sessions: { target: sessions, reference: undefined },
+        sessions: { target: sessions, reference: references.sessions },
         persistence: { target: unwrap(get('sessionPersistence')), reference: undefined },
     };
     const findings = CAPABILITY_SPECS.map((spec) => {
@@ -507,6 +633,7 @@ export function assessHost(ctx) {
     const modules = {};
     const sameAsHost = {};
     const blockers = [];
+    const unverified = [];
     const hostRoot = hostPackageRoot();
     for (const name of IDENTITY_PACKAGES) {
         const resolved = safeResolve(name);
@@ -518,6 +645,7 @@ export function assessHost(ctx) {
         }
         if (hostRoot === null) {
             sameAsHost[name] = null;
+            unverified.push(name);
             continue;
         }
         // Resolve the same name from the host installation's own anchor, then
@@ -534,6 +662,10 @@ export function assessHost(ctx) {
         sameAsHost[name] = same;
         if (same === false)
             blockers.push(`${name}：插件与宿主加载的是两份不同拷贝（运行 node scripts/host-deps.mjs --fix）`);
+        // 解析得到、却比不了：宿主锚点里找不到它。不能静默 —— 否则整块身份校验等于没做，
+        // 而页头仍报「全部可用」（pnpm 的 .pnpm 隔离目录就是这种情形，见 hostPackageRoot）。
+        if (same === null)
+            unverified.push(name);
     }
     // Degraded = something is genuinely unavailable. Optional slots are excluded:
     // their absence selects the adapter route and leaves the feature fully
@@ -552,6 +684,7 @@ export function assessHost(ctx) {
             modules,
             sameAsHost,
             blockers,
+            unverified,
         },
         findings,
         degraded,
@@ -559,11 +692,6 @@ export function assessHost(ctx) {
         generatedAt: Date.now(),
     };
 }
-/** True when two paths denote the same file; falls back to string equality. */
-function samePath(a, b) {
-    const normalize = (value) => value.replace(/\\/g, '/').toLowerCase();
-    return normalize(realPathOf(a) ?? a) === normalize(realPathOf(b) ?? b);
-}
 /**
  * The `@deepseek-ai` directory of the DSH installation this plugin is attached
  * to, derived from where a shared package physically lives.
@@ -571,6 +699,11 @@ function samePath(a, b) {
  * Anchoring on the resolved entry rather than on `require.resolve('@deepseek-ai/dsh')`
  * matters: the plugin never imports the `dsh` app package, so it need not be
  * resolvable from the plugin at all — only the shared libraries are.
+ *
+ * 注意 pnpm：这里在 `.pnpm/<name>@<ver>/node_modules/` 布局下会返回**该包的隔离目录**
+ * （那也是一个 `node_modules/@deepseek-ai`）。它本身不是问题 —— node 的解析会继续向上走到
+ * 顶层 `node_modules`，所以能解析出的包集合与顶层锚点相同（实测确认）。真正的风险在
+ * 调用方：从锚点解析不到的包会被判成 `same = null`，见 assessHost 里的 `unverified`。
  */
 function hostPackageRoot() {
     for (const anchor of IDENTITY_PACKAGES) {