dsh-plugin-tool-management 0.13.0 → 0.14.0

package/lib/compat/preset-reach.js

@@ -225,7 +225,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 +237,7 @@ export function deriveReach(facts, ctx) {
             return 'suppressed';
         return 'ok';
     };
+    const scene = pluginText('scene');
     const memory = pluginText('memory');
     const mcp = pluginText('mcp');
     /**
@@ -275,7 +276,7 @@ export function deriveReach(facts, ctx) {
     const subagent = pluginText('subagents');
     // MCP 列答的是"服务器清单与备注到不到得了"：宿主工具数不再参与 —— 清单为空时注入出去
     // 也是空段（没什么可看的），"有几台 server"由插件页面回答，不是这一列的事。
-    return { memory, agentsMd, skillCatalog, subagent, mcp };
+    return { scene, memory, agentsMd, skillCatalog, subagent, mcp };
 }
 /** Narrow the roster off a cordis context without throwing. */
 export function presetRosterOf(ctx) {
@@ -308,6 +309,7 @@ async function composeRow(roster, meta, ctx) {
             agentInstructions: 'absent',
             toolSkill: 'absent',
             suppressing: false,
+            scene: 'unknown',
             memory: 'unknown',
             agentsMd: 'unknown',
             skillCatalog: 'unknown',
@@ -328,6 +330,7 @@ async function composeRow(roster, meta, ctx) {
             agentInstructions: 'absent',
             toolSkill: 'absent',
             suppressing: false,
+            scene: 'unknown',
             memory: 'unknown',
             agentsMd: 'unknown',
             skillCatalog: 'unknown',
@@ -435,7 +438,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 工具按需读取；不要假设你已经看到它们。' +
             '（想让它在这类预设下也注入：插件的「兼容」页 → 注入。）');
     }

package/lib/context-inject.js

@@ -16,7 +16,8 @@
 // 与官方 skill-catalog 同款：各自的来源 kind（轨迹里各自一行、各显各的名字）、各自的
 // form、各自的去重。好处是"只改了一个域就只重发那一条"；代价是进场景这类多域同时变的
 // 时刻会一次发几条（每条带一句自己的引导语）。五个域与轨迹行名：
-//   memory    → scene-memory-manager-catalog（场景和记忆）
+//   scene     → scene-manager-catalog（场景：启用的场景 + 场景说明，约定）
+//   memory    → memory-manager-catalog（记忆：各场景下的条目，记录）
 //   mcp       → mcp-manager-catalog
 //   skills    → skill-manager-catalog（不叫 skill-catalog：那是官方那条行的名字）
 //   subagents → subagent-manager-catalog
@@ -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);
 /**
@@ -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');
 }
@@ -621,7 +675,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) {