dsh-plugin-tool-management 0.14.0 → 0.15.0

package/lib/compat/patch-dialect.js

@@ -6,7 +6,7 @@
 // 解析失败 = DSH **下次启动直接起不来**（`CHANGELOG.md` 里记过这次事故）。三条写入路径
 // （`profiles/<名>/cordis.patch.yml`、`~/.dsh/cordis.patch.yml`、bundle 的 `cordis.patch.yml`）
 // 走的是同一份方言（前者 `loadOverlayPatches`、后者 `loadOptionalPatches` → `parsePatchList`；
-// `userPatchesSchema === entryListSchema`，实测于 dsh-app-boot 0.1.5-rc.2）。
+// `userPatchesSchema === entryListSchema`，实测于 dsh-app-boot 0.1.5-rc.2，0.1.7-rc.2 复核未变）。
 //
 // 官方**没有**导出这份 schema（导出清单见同文件 :1575，无 `entryListSchema`），所以只能复刻。
 // 复刻**必然会过期**（官方加方言 / 换 js-yaml 大版本），因此判定策略是**非对称**的：
@@ -135,6 +135,8 @@ function record(report) {
         fallback: 'inform-only',
         detail: (report.kind === 'no-dep' ? '校验依赖不可用' : '复刻可能已过期')
             + `：${report.detail}（写入照常进行，仅少一道「把启动配置写坏」的拦截）`,
+        detailKey: report.kind === 'no-dep' ? 'patch-write-guard.no-dep' : 'patch-write-guard.stale',
+        params: { detail: report.detail },
     });
     pendingWarnings.push(report.kind === 'no-dep'
         ? '补丁写入未做解析校验（依赖不可用）：' + report.detail

package/lib/compat/preset-reach.js

@@ -47,7 +47,7 @@
  *     nothing about the servers behind them — no names, no tool counts, no
  *     enablement, and none of the user's notes.
  *
- * Reading never mounts. `list()`/`read(id)` are roster reads, so building the
+ * Reading never mounts. `list()`/`read(id)`/`readDocument(id)` are roster reads, so building the
  * matrix cannot activate a preset early — the same guarantee
  * `compositionInventory()` gives the plugin-listing surfaces.
  *
@@ -57,6 +57,7 @@
  * point at the switch that overrides it.
  */
 import { MCP_CLIENT_MODULE } from '../host-names.js';
+import { noteRuntime } from './runtime-notes.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;
@@ -278,6 +279,36 @@ export function deriveReach(facts, ctx) {
     // 也是空段（没什么可看的），"有几台 server"由插件页面回答，不是这一列的事。
     return { scene, memory, agentsMd, skillCatalog, subagent, mcp };
 }
+/**
+ * 读一个预设的组合文本。两代宿主同一个出口：
+ * `read(id)`（0.1.5 直返文本）或 `readDocument(id).content`（0.1.7 文档对象）。
+ * 两者都不可用时抛错，由调用方决定降级口径 —— reason 文案由此保持单一来源。
+ *
+ * 兜底路径的可见性（0.15.0）：兜底成功**不留运行时上报** —— 上报一律渲染成问题行，
+ * 而「read 改名 readDocument 后走兜底」是 0.1.7 的正常形态，不是降级（琥珀只留给故障，
+ * 2026-09-28 用户反馈）。走的哪条路由探测表 `preset.roster-surface` 的健康行说明承担；
+ * 这里只在**真异常**（readDocument 在场但文档缺 `.content`）时留痕。同 id 覆盖，不堆积。
+ */
+export async function readCompositionText(roster, presetId) {
+    if (typeof roster.read === 'function') {
+        return String((await roster.read(presetId)) ?? '');
+    }
+    if (typeof roster.readDocument === 'function') {
+        const doc = (await roster.readDocument(presetId));
+        if (doc === null || typeof doc !== 'object' || doc.content === undefined) {
+            // 文档形状的第二次漂移：readDocument 在、`.content` 不在 —— 当年 read 改名的翻版。
+            noteRuntime({
+                id: 'preset.roster-read-route',
+                label: '预设名册读取',
+                kind: 'read',
+                fallback: 'inform-only',
+                detail: `readDocument(${presetId}) 返回的文档没有 content 字段：组合文本按空处理，注入边界将显示「无法判断」。宿主的名册文档契约可能又变了。`,
+            });
+        }
+        return String(doc?.content ?? '');
+    }
+    throw new Error('预设名单未提供 read()/readDocument()：无法读取组合文件');
+}
 /** Narrow the roster off a cordis context without throwing. */
 export function presetRosterOf(ctx) {
     try {
@@ -301,7 +332,7 @@ async function composeRow(roster, meta, ctx) {
         isDefault,
         ...(broken === undefined ? {} : { broken }),
     };
-    if (typeof roster.read !== 'function') {
+    if (typeof roster.read !== 'function' && typeof roster.readDocument !== 'function') {
         return {
             ...base,
             personaComplete: 'unknown',
@@ -315,12 +346,12 @@ async function composeRow(roster, meta, ctx) {
             skillCatalog: 'unknown',
             subagent: 'unknown',
             mcp: 'unknown',
-            reason: '预设名单未提供 read()：无法读取组合文件',
+            reason: '预设名单未提供 read()/readDocument()：无法读取组合文件',
         };
     }
     let text;
     try {
-        text = String((await roster.read(presetId)) ?? '');
+        text = await readCompositionText(roster, presetId);
     }
     catch (error) {
         return {
@@ -470,10 +501,10 @@ export async function reachNoticeForAgent(roster, agentCtx, inject) {
     catch {
         return '';
     }
-    if (presetId === '' || typeof roster.read !== 'function')
+    if (presetId === '' || (typeof roster.read !== 'function' && typeof roster.readDocument !== 'function'))
         return '';
     try {
-        return reachNoticeFor(presetId, readCompositionFacts(String((await roster.read(presetId)) ?? '')), inject);
+        return reachNoticeFor(presetId, readCompositionFacts(await readCompositionText(roster, presetId)), inject);
     }
     catch {
         return '';

package/lib/compat/probe.js

@@ -30,7 +30,7 @@
  * leave the rest working.
  */
 import { createRequire } from 'node:module';
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 /** Packages whose physical module identity matters to this plugin. */
 export const IDENTITY_PACKAGES = [
@@ -41,10 +41,15 @@ export const IDENTITY_PACKAGES = [
     '@deepseek-ai/dsh-storage-domain',
     '@deepseek-ai/dsh-spill-local',
 ];
-/** Peers this plugin was written and verified against（只声明最低版本，无上界）。 */
-export const EXPECTED_PEER_RANGE = '>=0.1.5-rc.2';
+/**
+ * peer range 的下界与已验证版本。官方全程走 prerelease 渠道（x.y.z-rc.N），semver 的
+ * 预发布规则（prerelease 版本只匹配同 [major,minor,patch] 元组的比较器）意味着**每一代
+ * rc 都要显式列进范围**：`>=0.1.5-rc.2` 匹配不了 `0.1.7-rc.2`（实测），所以范围是逐代
+ * 枚举的并集。上界依旧不设：宿主跨代升级由运行时能力探测兜底（见下）。
+ */
+export const EXPECTED_PEER_RANGE = '^0.1.5-rc.2 || ^0.1.7-rc.2';
 /** The release this plugin's adapters were last verified against. */
-export const VERIFIED_HOST_VERSION = '0.1.5-rc.2';
+export const VERIFIED_HOST_VERSION = '0.1.7-rc.2';
 /**
  * peer range 的下界 —— 界面展示用。
  *
@@ -54,7 +59,7 @@ export const VERIFIED_HOST_VERSION = '0.1.5-rc.2';
  * 而不是在安装期拒绝整包。展示时只应把「最低要求版本」当事实。
  * 从 EXPECTED_PEER_RANGE 派生，避免两处手写漂移。
  */
-export const EXPECTED_MIN_HOST_VERSION = EXPECTED_PEER_RANGE.match(/^>=\s*([^\s]+)/)?.[1] ?? VERIFIED_HOST_VERSION;
+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. */
 function safeResolve(specifier) {
@@ -151,10 +156,17 @@ const PROJECTION_CLASS = { pkg: '@deepseek-ai/dsh-session-projection-cache', tar
 // `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) {
@@ -221,6 +233,14 @@ function referencePrototypes() {
     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;
 }
 /**
@@ -455,6 +475,67 @@ const CAPABILITY_SPECS = [
             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
@@ -564,10 +645,21 @@ function inspectCapability(spec, target, reference) {
             textMatch,
         };
     }
+    // describe 是健康行也带的观测值（如 settings 的 documentPath）；只挂 ok 路径，
+    // 摸宿主属性一律 try/catch —— 观测失败就少一句后缀，不把好端端的能力报成问题。
+    let described = '';
+    if (spec.describe !== undefined) {
+        try {
+            const extra = spec.describe(target);
+            if (typeof extra === 'string' && extra !== '')
+                described = `；${extra}`;
+        }
+        catch { /* 观测值拿不到就算了 */ }
+    }
     return {
         ...base,
         state: 'ok',
-        detail: textMatch === false ? '成员齐备（实现文本与本插件适配的版本不同，按能力使用）' : '成员齐备',
+        detail: (textMatch === false ? '成员齐备（实现文本与本插件适配的版本不同，按能力使用）' : '成员齐备') + described,
         missing: [],
         ...(textMatch === undefined ? {} : { textMatch }),
     };
@@ -647,12 +739,18 @@ export function assessHost(ctx) {
     const registry = unwrap(get('workspaceRegistry'));
     const cache = unwrap(get('sessionProjectionCache'));
     const sessions = unwrap(ctx.sessions !== undefined ? ctx.sessions : get('sessions'));
+    // settings 走 ctx 属性优先（插件 inject 清单里的正式服务），roster 走服务名查找
+    // （'agentPresets' 与 preset-reach.ts 的 presetRosterOf 同名 —— 注入矩阵实际用的就是它）。
+    const settings = unwrap(ctx.settings !== undefined ? ctx.settings : get('settings'));
+    const roster = unwrap(get('agentPresets'));
     const references = referencePrototypes();
     const targets = {
         workspace: { target: registry, reference: references.workspace },
         projectionCache: { target: cache, reference: references.cache },
         sessions: { target: sessions, reference: references.sessions },
         persistence: { target: unwrap(get('sessionPersistence')), reference: undefined },
+        settings: { target: settings, reference: references.settings },
+        presetRoster: { target: roster, reference: references.roster },
     };
     const findings = CAPABILITY_SPECS.map((spec) => {
         const slot = targets[spec.owner];
@@ -736,7 +834,7 @@ export function assessHost(ctx) {
  */
 function hostPackageRoot() {
     // 与 doctor 的 `findHost` **同一套策略**（先看 `$DSH_HOME/profiles/node_modules/@deepseek-ai`，
-    // 再从插件自身位置逐级上溯，并确认那一层里真有 `dsh/package.json`）。此前运行时只按"插件
+    // 再从插件自身位置逐级上溯，最后扫 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');
@@ -759,12 +857,56 @@ function hostPackageRoot() {
             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) {
         if (existsSync(join(candidate, 'dsh', 'package.json')))
             return candidate;
     }
     return null;
 }
+/**
+ * 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;

package/lib/context-inject.js

@@ -15,7 +15,7 @@
 // 形态（2026-09-16 第二版，用户裁定）：**每个域一条自己的消息**，不再是一条大快照 ——
 // 与官方 skill-catalog 同款：各自的来源 kind（轨迹里各自一行、各显各的名字）、各自的
 // form、各自的去重。好处是"只改了一个域就只重发那一条"；代价是进场景这类多域同时变的
-// 时刻会一次发几条（每条带一句自己的引导语）。五个域与轨迹行名：
+// 时刻会一次发几条（每条带一句自己的引导语）。各域与轨迹行名（清单见下 INJECT_DOMAIN_KEYS）：
 //   scene     → scene-manager-catalog（场景：启用的场景 + 场景说明，约定）
 //   memory    → memory-manager-catalog（记忆：各场景下的条目，记录）
 //   mcp       → mcp-manager-catalog
@@ -35,7 +35,7 @@
 //     免得旧目录继续被当成现状。
 //
 // 2026-09-17 第二版加的两件事：
-//   - **按深度抑制人设目录**：宿主平面注册意味着子代理派生的会话也收到五域。而人设目录
+//   - **按深度抑制人设目录**：宿主平面注册意味着子代理派生的会话也收到全部域。而人设目录
 //     要不要出现在某个深度的会话里，由人设的 `catalogDepth`（默认 1 = 只在顶层注入）决定；
 //     判定放在域声明的 `applicableTo` 上，通道只负责问一句 —— "哪个域对哪类会话不成立"
 //     是域的语义，不是通道的机制。
@@ -388,7 +388,7 @@ export function escapeFrameBody(body) {
 }
 /**
  * 一条注入消息的正文（纯函数）：`<system-reminder>` 里 = 框架（标题 + 动作 + 补充 + 权威
- * 声明）+ 空行 + 域正文。**五个域一律带框架**，没有例外。
+ * 声明）+ 空行 + 域正文。**所有域一律带框架**，没有例外。
  *
  * 历史（每一版都是被具体毛病逼出来的，别把结论当套话读）：
  *   - 第一版（2026-09-17 前）：五域共用「以下是本机插件的X（取代…）。」——「本机插件」是实现
@@ -509,6 +509,8 @@ function suppressionVerdict(active, dropped, counter) {
         kind: 'read',
         fallback: 'inform-only',
         detail: `关掉的注入域已连续 ${counter.turns} 轮没有拦到任何官方消息（自检）：可能是瀑布注册顺序变了导致拦截失效，也可能是官方那两条注入行这几轮本来就没有内容。可到「注入实况」对照模型实际收到的内容。`,
+        detailKey: 'official-suppression',
+        params: { turns: counter.turns },
     });
 }
 /** 实况展示用的 kind 表：本插件的五条 + 官方两条。 */