dsh-plugin-tool-management 0.13.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;
@@ -225,7 +226,7 @@ export function deriveReach(facts, ctx) {
     const forceUnderSuppressing = ctx?.inject?.underSuppressingPresets === true;
     const domainOff = (key) => ctx?.inject?.domains?.[key] === false;
     /**
-     * 本插件自己的文本（场景和记忆 / MCP 服务器与备注 / 技能目录 / 子智能体目录 / 提示词）
+     * 本插件自己的文本（场景 / 记忆 / MCP 服务器与备注 / 技能目录 / 子智能体目录 / 提示词）
      * 走 `agent/pre-step` 注入消息（src/context-inject.ts）—— 不再依赖系统提示词段，所以
      * `persona complete` 压不到它。可达性只看两件事：域开关有没有关、预设压制时有没有开
      * 「仍然注入」。预设信息读不到（`personaUnknown` 且无压制信号）时按可达处理。
@@ -237,6 +238,7 @@ export function deriveReach(facts, ctx) {
             return 'suppressed';
         return 'ok';
     };
+    const scene = pluginText('scene');
     const memory = pluginText('memory');
     const mcp = pluginText('mcp');
     /**
@@ -275,7 +277,37 @@ export function deriveReach(facts, ctx) {
     const subagent = pluginText('subagents');
     // MCP 列答的是"服务器清单与备注到不到得了"：宿主工具数不再参与 —— 清单为空时注入出去
     // 也是空段（没什么可看的），"有几台 server"由插件页面回答，不是这一列的事。
-    return { memory, agentsMd, skillCatalog, subagent, mcp };
+    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) {
@@ -300,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',
@@ -308,17 +340,18 @@ async function composeRow(roster, meta, ctx) {
             agentInstructions: 'absent',
             toolSkill: 'absent',
             suppressing: false,
+            scene: 'unknown',
             memory: 'unknown',
             agentsMd: 'unknown',
             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 {
@@ -328,6 +361,7 @@ async function composeRow(roster, meta, ctx) {
             agentInstructions: 'absent',
             toolSkill: 'absent',
             suppressing: false,
+            scene: 'unknown',
             memory: 'unknown',
             agentsMd: 'unknown',
             skillCatalog: 'unknown',
@@ -435,7 +469,7 @@ export function reachNoticeFor(presetId, facts, inject) {
     const domainOff = (key) => inject?.domains?.[key] === false;
     if (isSuppressingPreset(facts) && inject?.underSuppressingPresets !== true) {
         parts.push(`预设「${presetId}」声明只要它自己的文本（persona complete / 关闭运行时上下文）：` +
-            '本插件注入的 —— 场景和记忆、MCP、技能、子智能体、提示词 —— 默认不注入，' +
+            '本插件注入的 —— 场景、记忆、MCP、技能、子智能体、提示词 —— 默认不注入，' +
             '需要时用对应的 list / read 工具按需读取；不要假设你已经看到它们。' +
             '（想让它在这类预设下也注入：插件的「兼容」页 → 注入。）');
     }
@@ -467,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,8 +15,9 @@
 // 形态（2026-09-16 第二版，用户裁定）：**每个域一条自己的消息**，不再是一条大快照 ——
 // 与官方 skill-catalog 同款：各自的来源 kind（轨迹里各自一行、各显各的名字）、各自的
 // form、各自的去重。好处是"只改了一个域就只重发那一条"；代价是进场景这类多域同时变的
-// 时刻会一次发几条（每条带一句自己的引导语）。五个域与轨迹行名：
-//   memory    → scene-memory-manager-catalog（场景和记忆）
+// 时刻会一次发几条（每条带一句自己的引导语）。各域与轨迹行名（清单见下 INJECT_DOMAIN_KEYS）：
+//   scene     → scene-manager-catalog（场景：启用的场景 + 场景说明，约定）
+//   memory    → memory-manager-catalog（记忆：各场景下的条目，记录）
 //   mcp       → mcp-manager-catalog
 //   skills    → skill-manager-catalog（不叫 skill-catalog：那是官方那条行的名字）
 //   subagents → subagent-manager-catalog
@@ -34,7 +35,7 @@
 //     免得旧目录继续被当成现状。
 //
 // 2026-09-17 第二版加的两件事：
-//   - **按深度抑制人设目录**：宿主平面注册意味着子代理派生的会话也收到五域。而人设目录
+//   - **按深度抑制人设目录**：宿主平面注册意味着子代理派生的会话也收到全部域。而人设目录
 //     要不要出现在某个深度的会话里，由人设的 `catalogDepth`（默认 1 = 只在顶层注入）决定；
 //     判定放在域声明的 `applicableTo` 上，通道只负责问一句 —— "哪个域对哪类会话不成立"
 //     是域的语义，不是通道的机制。
@@ -74,17 +75,23 @@ import { SessionSeq } from '@deepseek-ai/dsh-session';
 import { clearRuntimeNote, noteRuntime } from './compat/runtime-notes.js';
 /**
  * 权威域顺序（界面勾选、注入消息先后都按它）。
- * 场景和记忆排第一：它是"当前模式"的框架，先给框架再给内容。
+ * 场景排第一、记忆紧跟：场景是"当前模式"的**框架**（有哪些场景、各自是什么约定），
+ * 记忆是各场景下的**内容** —— 先给框架再给内容。
  */
-export const INJECT_DOMAIN_KEYS = ['memory', 'mcp', 'skills', 'subagents', 'prompt'];
+export const INJECT_DOMAIN_KEYS = ['scene', 'memory', 'mcp', 'skills', 'subagents', 'prompt'];
 /**
  * 域 → 消息来源 kind（轨迹行标签，也是去重时的身份）。
  *
  * 命名对齐官方 `*-catalog` 风格与本插件的工具族（`*_manager_*`）；改名等于换身份，
  * 旧消息会被当成"不在上下文里"而重发一次，所以这几个字符串是稳定契约。
+ *
+ * ⚠️ 0.14.0 把 `memory` 的 kind 从 `scene-memory-manager-catalog` 改成
+ * `memory-manager-catalog`，并把场景拆成独立的 `scene` 域 —— 升级后每个会话**会重发一次**
+ * 这两段（旧消息认不出来）。一次性代价，换来的是两段能各自开关、各自去重。
  */
 export const INJECT_KIND_OF = {
-    memory: 'scene-memory-manager-catalog',
+    scene: 'scene-manager-catalog',
+    memory: 'memory-manager-catalog',
     mcp: 'mcp-manager-catalog',
     skills: 'skill-manager-catalog',
     subagents: 'subagent-manager-catalog',
@@ -98,22 +105,30 @@ export const INJECT_KIND_OF = {
  * 「用了」长得一模一样。有了映射，就能把「投递 N 次 / 调用 M 次」并排摆出来，
  * 措辞与形式的调整才有依据（否则改文案就是猜）。
  *
- * 前缀而不是精确名：`memory_manager_*` 有 list/read/write/delete 等，任何一个都
- * 说明模型确实在读这一域。改工具名等于换身份，这五个字符串是稳定契约。
+ * 前缀而不是精确名：`memory_manager_*` 有 list/read/switch/save 等，任何一个
+ * 都说明模型确实在读这一域。改工具名等于换身份，这几个字符串是稳定契约。
+ *
+ * 为什么值是**数组**：工具族与注入域不是一一对应的概念 —— 域是"给模型看的信息分组"
+ * （界面上的勾选），族是"操作哪类对象"。0.14.0 里场景与记忆就一度同域两族
+ * （`memory_manager_*` + `scene_manager_*`），拆开后现在每个域各一个前缀。留着数组是
+ * 为了让"一个域挂多个族"在类型上成立，将来加族不必改类型。顺序不影响判定。
  */
 export const DOMAIN_TOOL_PREFIX = {
-    memory: 'memory_manager_',
-    mcp: 'mcp_manager_',
-    skills: 'skill_manager_',
-    subagents: 'subagent_manager_',
-    prompt: 'prompt_manager_',
+    scene: ['scene_manager_'],
+    memory: ['memory_manager_'],
+    mcp: ['mcp_manager_'],
+    skills: ['skill_manager_'],
+    subagents: ['subagent_manager_'],
+    prompt: ['prompt_manager_'],
 };
 /** 工具名 → 域（`undefined` = 不是本插件的域工具）。纯函数，便于单独推理。 */
 export function domainOfTool(toolName) {
     const name = String(toolName ?? '');
     for (const key of INJECT_DOMAIN_KEYS) {
-        if (name.startsWith(DOMAIN_TOOL_PREFIX[key]))
-            return key;
+        for (const prefix of DOMAIN_TOOL_PREFIX[key]) {
+            if (name.startsWith(prefix))
+                return key;
+        }
     }
     return undefined;
 }
@@ -170,7 +185,7 @@ const CARRIER_FACT_OF = {
 };
 export const DEFAULT_INJECT_SETTINGS = {
     underSuppressingPresets: false,
-    domains: { memory: true, mcp: true, skills: true, subagents: true, prompt: true },
+    domains: { scene: true, memory: true, mcp: true, skills: true, subagents: true, prompt: true },
 };
 /** 把任意输入夹成合法设置（缺项/类型不对一律退回默认；默认从不阻止注入）。 */
 export function normalizeInjectSettings(raw) {
@@ -276,31 +291,59 @@ export function explainInjections(domains, settings, facts, agent) {
     }
     return reasons;
 }
+/**
+ * 权威声明的统一句（用户 2026-09-23 看到实际注入后要求精简）。
+ *
+ * 此前五个域各写一份 —— `本份场景取代…同类场景` / `本份记忆取代…同类记忆` /
+ * `本份状态…` / `本份目录…` —— 说的是**同一条规则**却用了四种措辞，模型读到四条不同的句子
+ * 还得自己判断它们是不是一条。统一成一句：被取代的是"同类内容"，与域无关。
+ *
+ * 为什么不能并进 `cue`（那能省下整整一行 ≈16 tok/段）：用户 2026-09-18 定过"权威声明单独
+ * 成句" —— 它和动作句是两种东西（一句说"什么时候用它"，一句说"以哪份为准"），合并后容易
+ * 被一眼带过。所以这里的收益只有约 6 tok/轮，**主要收益是消除四种措辞**，不是省字节。
+ */
+const SUPERSEDE_NOTE = '本份取代本次会话中更早注入的同类内容。';
 const DOMAIN_FRAME = {
+    scene: {
+        // 场景段只有标题 + 正文 + 权威声明（**没有 cue 是六个域的共同决定**，理由见 `DomainFrame`）。
+        //
+        // 这一段的演进值得记下来，因为每一次都是被实际注入推着改的：
+        //   ① 最早它把「场景说明」当**约定**授权（"一律照办，覆盖你的默认做法"）—— 而它的实例
+        //      是「写代码」这种**标签**，让模型"照办一个标签"，这正是它读不懂这段的原因；
+        //   ② 去掉授权后换成一句定义（"场景是用户给这台机器配的工作模式"）—— 定义不是动作，
+        //      模型读完还是不知道该拿它做什么；
+        //   ③ 再加一句因果（"下面四段都已按它筛过"）—— 用户 2026-09-23 看到渲染效果后给了
+        //      **原则**：「上下文注入就是当前的情况，目的是让 agent 知道现在的情况，不需要它
+        //      知道没用的信息，反推更是浪费 token」。于是三句全删。
+        //
+        // 现在这一段只回答一个问题：**当前处在哪个场景、它是什么**（`**「代码」—— 写代码**`）。
+        // 它还比别的段少一层：因果句也删了 —— 它解释的是"另外四段是怎么产生的"（机制），
+        // 不是当前情况本身，而且"清单里没有 ≠ 本机没有"这层反推被用户明确判为浪费。
+        title: '本机当前的场景',
+        supersede: SUPERSEDE_NOTE,
+    },
     memory: {
-        title: '本机当前的场景和记忆',
-        cue: '在回答涉及本机的事之前，先核对这里。',
-        supersede: '本份记忆取代本次会话中更早注入的同类记忆。',
+        title: '本机当前的记忆',
+        supersede: SUPERSEDE_NOTE,
     },
     mcp: {
         title: '本机 MCP 服务器的当前状态',
-        cue: '要用某个 MCP 工具前，先在这里确认这台服务器在不在、开没开。',
-        how: '工具名是 `mcp__<服务器>__<工具>`；带「用户提示：」的行是用户写给这台服务器的决策提示，选服务器之前先看一眼。',
-        supersede: '本份状态取代本次会话中更早注入的同类状态。',
+        // how 只剩"怎么用备注"这半句：前半个分句「工具名是 `mcp__<服务器>__<工具>`」删掉了
+        // —— 模型自己的工具表里就是这个命名（`mcp__context7__xxx`），告诉它格式是零信息量。
+        how: '带「用户提示：」的行是用户写给这台服务器的决策提示，选服务器之前先看一眼。',
+        supersede: SUPERSEDE_NOTE,
     },
     skills: {
         title: '本机技能目录',
-        cue: '需要某项能力时，先在这里找。',
         // 两句都只在预设没挂官方 `skill` 工具时出现，差别只在点名不点名那个取正文的工具
         // （工具被用户在兼容页关掉时不点名 —— 点名一个模型手里没有的工具只会让它去猜名字）。
         how: (toolHidden) => toolHidden('skill_manager_read')
             ? '本预设没有官方 `skill` 工具：目录只有摘要，读完再照做。'
             : '本预设没有官方 `skill` 工具：要正文用 `skill_manager_read`（按名字直接给正文与路径）；目录只有摘要，读完再照做。',
-        supersede: '本份目录取代本次会话中更早注入的同类目录；只列当前可调用的技能。',
+        supersede: `${SUPERSEDE_NOTE.slice(0, -1)}；只列当前可调用的技能。`,
     },
     subagents: {
         title: '可委派的子智能体',
-        cue: '在决定自己做还是委派之前，先在这里选人设。',
         // 分界规则（2026-09-17 方案 C，本机实测 session-ee722e23 逼出来的）：官方那两个
         // 委派工具（`subagent` / `subagent_fork`）不带人设，而此前没有任何一句话说明何时该
         // 用谁 —— 模型在"审查刚读过的 README"时选了 `subagent_fork`（fork 能继承已读内容、
@@ -310,19 +353,17 @@ const DOMAIN_FRAME = {
         how: (toolHidden) => toolHidden('subagent_manager_run')
             ? '本会话没有带人设的委派工具；官方 `subagent` / `subagent_fork` 不带人设，只在没有人设贴合、或要后台跑时用。'
             : '贴合人设的任务一律用 `subagent_manager_run`（要它看到本次会话就开 `inherit`）；官方 `subagent` / `subagent_fork` 不带人设，只在没有人设贴合、或要后台跑时用。',
-        supersede: '本份目录取代本次会话中更早注入的同类目录。',
+        supersede: SUPERSEDE_NOTE,
     },
     prompt: {
         title: '本机提示词',
-        cue: '动手之前先按它对齐，与它冲突的默认做法一律让位。',
-        supersede: '本份提示词取代本次会话中更早注入的同类提示词。',
+        supersede: SUPERSEDE_NOTE,
     },
 };
 /** 域声明里没登记的 key（理论上到不了这里）：给一个不出错的通用框架。 */
 const fallbackFrame = (label) => ({
     title: `本机的${label}`,
-    cue: `需要这台机器的${label}时，先核对这里。`,
-    supersede: '本份内容取代本次会话中更早注入的同类内容。',
+    supersede: SUPERSEDE_NOTE,
 });
 const domainFrame = (key, label) => DOMAIN_FRAME[key] ?? fallbackFrame(label);
 /**
@@ -347,7 +388,7 @@ export function escapeFrameBody(body) {
 }
 /**
  * 一条注入消息的正文（纯函数）：`<system-reminder>` 里 = 框架（标题 + 动作 + 补充 + 权威
- * 声明）+ 空行 + 域正文。**五个域一律带框架**，没有例外。
+ * 声明）+ 空行 + 域正文。**所有域一律带框架**，没有例外。
  *
  * 历史（每一版都是被具体毛病逼出来的，别把结论当套话读）：
  *   - 第一版（2026-09-17 前）：五域共用「以下是本机插件的X（取代…）。」——「本机插件」是实现
@@ -367,20 +408,33 @@ export function escapeFrameBody(body) {
  */
 export function renderDomainText(section, toolHidden = () => false) {
     const frame = domainFrame(section.key, section.label);
-    const lines = [FRAME_OPEN, `## ${frame.title}`, `**${frame.cue}**`];
+    // 层级（2026-09-23 用户看到实际注入后指出「记忆内的场景怎么都是 ## 标题」）：**`#` 一级给板块**
+    // （场景 / 记忆 / MCP / 技能 / 子智能体 / 提示词），域正文里的 `##` 才是它的下一层
+    // （记忆段的 `## 场景：X`、超预算时的 `## 未注入的参考信息`）。此前标题也是 `##`，两者平级，
+    // 模型读不出主次 —— 而"哪些内容归在哪个板块/场景下"正是它做判断时要用的结构。
+    //
+    // 开标签后**必须空一行**：markdown 里 `#` 紧跟在一行文字后面只是**段落续行**，不会被渲染成
+    // 标题 —— 用户截图里 `## 本机当前的场景` 就是这么被吞掉的（和 `<system-reminder>` 挤成一段）。
+    // 收尾同理：正文末尾先归一成单个空行，免得 `</system-reminder>` 粘在最后一行上。
+    // 结构：标题 → 补充说明（有才发）→ 权威声明 → 正文。没有 cue 那一行（见 `DomainFrame` 的注释）。
+    const lines = [FRAME_OPEN, '', `# ${frame.title}`];
     const how = typeof frame.how === 'function' ? frame.how(toolHidden) : frame.how;
     if (how !== undefined)
         lines.push(how);
-    lines.push(frame.supersede, '', escapeFrameBody(section.text), FRAME_CLOSE);
+    lines.push(frame.supersede, '', escapeFrameBody(section.text).replace(/\n+$/, ''), '', FRAME_CLOSE);
     return lines.join('\n');
 }
 /** 「已清空」通知正文：某个域曾经注入过、现在没有内容时发一条（纯函数，测试用）。 */
 export function clearedDomainText(key, label) {
     const frame = domainFrame(key, label);
+    // 形状与 `renderDomainText` 一致（开标签后空行、板块 `#`、收尾空行）—— 这两条都是同一个
+    // 通道发出去的消息，层级与留白不该有两套。
     return [
         FRAME_OPEN,
-        `## ${frame.title}`,
+        '',
+        `# ${frame.title}`,
         '**已清空** —— 本次会话中此前注入的同类内容不再有效。',
+        '',
         FRAME_CLOSE,
     ].join('\n');
 }
@@ -455,6 +509,8 @@ function suppressionVerdict(active, dropped, counter) {
         kind: 'read',
         fallback: 'inform-only',
         detail: `关掉的注入域已连续 ${counter.turns} 轮没有拦到任何官方消息（自检）：可能是瀑布注册顺序变了导致拦截失效，也可能是官方那两条注入行这几轮本来就没有内容。可到「注入实况」对照模型实际收到的内容。`,
+        detailKey: 'official-suppression',
+        params: { turns: counter.turns },
     });
 }
 /** 实况展示用的 kind 表：本插件的五条 + 官方两条。 */
@@ -621,7 +677,7 @@ export function createContextInjector(deps) {
                 return;
             const at = Date.now();
             // 记在**发起这次调用的那个会话**的账上。`exec.agent` 与 pre-step 的 `payload.agent`
-            // 是同一个对象（dsh-scope 的不变量要求，见 review/后续方向.md §2 末），所以这里
+            // 是同一个对象（`dsh-scope` 的不变量要求），所以这里
             // 落账的会话与上面 `liveDomainsByAgent` 记现场的会话必然一致。
             let owner = typeof agent === 'object' && agent !== null ? agent : undefined;
             if (owner === undefined) {