dsh-plugin-tool-management 0.10.0 → 0.11.0

package/lib/subagents/service.js

@@ -5,8 +5,9 @@
 // v0.4 目录变更：人设由 `$DSH_HOME/subagents/` 搬到 `$DSH_HOME/tool-management/agents/`
 // （插件产生的文件统一收在 tool-management/ 下）。旧目录在首次扫描时搬入，见 relocateLegacyPersonas。
 import { createRequire } from 'node:module';
-import { mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { isValidSegment } from '../paths.js';
 import { resolveDshHome } from '../skills/core.js';
 import { listTrashEntries, moveOutOfTrash, moveToTrash, purgeTrashEntry, readTrashEntry } from '../hub.js';
 import { expandUploads, planPersonaImport } from '../imports/upload.js';
@@ -357,32 +358,85 @@ export function createSubagentService(ctx, opts) {
     const stateFile = join(stateDir, 'subagents-index.json');
     const req = createRequire(import.meta.url);
     let cache = null;
+    // ── 写操作串行队列 ──────────────────────────────────────────────────────
+    // 状态文件的「读-改-写」必须整体串行：两个并发开关各自读到同一份快照、各自写回，
+    // 后写的会把先写的改动抹掉（用户关掉的人设会自己回来）。人设文件的建/改/删也走这里，
+    // 否则「查重 → 写入」之间的空窗会让两次同名导入互相覆盖。
+    // 与 rules / skills 两域同一实现（`then(task, task)` 让前一个失败后队列照样继续）。
+    let mutationQueue = Promise.resolve();
+    const enqueueMutation = (task) => {
+        const queued = mutationQueue.then(task, task);
+        mutationQueue = queued.catch(() => undefined);
+        return queued;
+    };
     // ── 人设启用集合（子智能体开关）────────────────────────────────────────
     // subagents-index.json：{ version: 1, enabled: string[] }（与 memories-index.json 同目录约定）。
-    //   - 文件缺失/损坏 = **全部启用**（老用户升级零感知，行为与开关上线前一致）；
+    //   - 文件**缺失** = **全部启用**（老用户升级零感知，行为与开关上线前一致）；
+    //   - 文件**存在但解析失败** = **全部停用** + 告警一次（fail-closed：损坏不该把用户停用的
+    //     人设一次性重新暴露给模型，且用户看不到任何提示；与 rules 域索引隔离同口径）；
     //   - 文件一旦写出即为权威：之后新建/导入/回收站恢复的人设**自动启用**（刚建就想用是常理）；
     //   - 停用只影响注入与 subagent_* 工具的可见性，人设文件一个字节不动。
     // 缓存约定：undefined = 还没读过盘；null = 文件缺失（全部启用）；数组 = 权威集合。
     let enabledCache = undefined;
+    // 与缓存配对的文件指纹（mtimeMs；文件不存在时 null）。**必须比对指纹**：这个文件可能被
+    // 另一个 DSH 实例（多 profile 共享 state 目录）或手工编辑改动，只在自身写入时失效缓存
+    // 会让插件一直返回旧集合 —— 用户停用的人设悄悄回来。一次 stat 比重新读 + 解析便宜，
+    // 而且立刻跟上外部改动，不引入新的 TTL 窗口。
+    let enabledStamp = null;
+    // 解析失败只告警一次：readEnabled 每次读都会走到那段，不设标志会刷屏。
+    let warnedBrokenState = false;
+    /** 文件 mtimeMs；不存在或读不到时 null（与「文件缺失」同一判定）。 */
+    const fileStamp = async (path) => {
+        try {
+            return (await stat(path)).mtimeMs;
+        }
+        catch {
+            return null;
+        }
+    };
     async function readEnabled() {
-        if (enabledCache !== undefined)
+        const stamp = await fileStamp(stateFile);
+        if (enabledCache !== undefined && stamp === enabledStamp)
             return enabledCache;
         // 用局部变量过渡：await 之后 TS 对闭包级缓存变量的收窄会失效，直接返回会报 undefined。
         let next;
+        let text;
         try {
-            const raw = JSON.parse(await readFile(stateFile, 'utf8'));
-            next = Array.isArray(raw && raw.enabled) ? raw.enabled.map((x) => String(x)) : [];
+            text = await readFile(stateFile, 'utf8');
         }
         catch {
+            text = null;
+        }
+        if (text === null) {
+            // 文件不存在 → 全部启用（升级零感知，见上方约定）。
             next = null;
         }
+        else {
+            try {
+                const raw = JSON.parse(text);
+                next = Array.isArray(raw && raw.enabled) ? raw.enabled.map((x) => String(x)) : [];
+            }
+            catch (e) {
+                // 文件**存在**却解析失败 → fail-closed 成「谁都不启用」。沿用「全部启用」会把用户
+                // 停用的人设一次性全部重新暴露给模型，而用户看不到任何提示；空集合至少可见、可恢复
+                // （重新开启即可）。文件本身一个字节不动，修好后重启即恢复。
+                if (!warnedBrokenState) {
+                    warnedBrokenState = true;
+                    ctx.logger?.warn?.(`[dsh-plugin-tool-management] 人设索引解析失败（${message(e)}）；已按「全部停用」处理，请检查 ${stateFile}`);
+                }
+                next = [];
+            }
+        }
         enabledCache = next;
+        enabledStamp = stamp;
         return next;
     }
     async function writeEnabled(list) {
         await mkdir(stateDir, { recursive: true });
         await writeFile(stateFile, JSON.stringify({ version: 1, enabled: list }, null, 2), 'utf8');
         enabledCache = list;
+        // 写入后重取指纹，让下一次 readEnabled 直接命中缓存（否则会白读一次）。
+        enabledStamp = await fileStamp(stateFile);
     }
     /** 新建/导入/恢复的人设默认停用（v0.8.5 用户裁定，与技能 / MCP 同口径）：
      *  文件缺失（含旧数据）时先把「全部启用」物化成显式全集**并排除新名**——
@@ -414,6 +468,25 @@ export function createSubagentService(ctx, opts) {
             return;
         await writeEnabled(set.filter((n) => n !== name));
     }
+    /**
+     * 启用集合的「跟随写」失败**不能吞**。原先这五处一律 `.catch(() => undefined)`，
+     * 而写盘失败时后果是静默改变开关状态：新建/导入/恢复的人设会停在**启用**态（下一轮就进
+     * 模型上下文），改名的人设会停在**停用**态 —— 用户看到的却都是成功。
+     *
+     * 沿用 `sceneSyncError` 的形状：只给**原因原文**，句子由界面按当前语言拼。
+     */
+    async function withEnabledNote(res, task) {
+        try {
+            await task();
+            return res;
+        }
+        catch (e) {
+            const reason = message(e);
+            return res && res.ok === false
+                ? { ...res, error: `${res.error}；另外，启停状态没能同步（${reason}）` }
+                : { ...res, stateSyncError: reason };
+        }
+    }
     /** list() 输出统一附上 enabled：文件缺失 → 全 true；否则按集合。 */
     function withEnabled(docs, set) {
         if (set === null)
@@ -576,6 +649,11 @@ export function createSubagentService(ctx, opts) {
         chain = queued.catch(() => undefined);
         return queued;
     };
+    /** 写操作 op 名集合（HTTP 端 WRITE_OPS 由它派生）。 */
+    const writeOps = new Set([
+        'subagent-create', 'subagent-update', 'subagent-delete', 'subagent-import',
+        'subagent-toggle', 'subagent-trash-restore', 'subagent-trash-delete',
+    ]);
     const ops = {
         'subagent-list': async () => {
             const docs = await list();
@@ -611,9 +689,8 @@ export function createSubagentService(ctx, opts) {
             }
             await writeFile(target, serializePersona(args), 'utf8');
             // v0.8.5：新建默认不启动——显式集合下新名天然停用；文件缺失时先物化全集并排除新名。
-            await materializeEnabledExcluding([name]).catch(() => undefined);
             cache = null;
-            return { ok: true, name };
+            return withEnabledNote({ ok: true, name }, () => materializeEnabledExcluding([name]));
         },
         /**
          * 保存人设，**可选改名**（nextName）。
@@ -640,20 +717,28 @@ export function createSubagentService(ctx, opts) {
                 const taken = await readFile(nextTarget, 'utf8').then(() => true).catch(() => false);
                 if (taken)
                     return { ok: false, error: `人设已存在: ${nextRaw}` };
-                try {
-                    await rename(target, nextTarget);
-                }
-                catch (e) {
-                    return { ok: false, error: `人设改名失败: ${message(e)}` };
-                }
                 finalName = nextRaw;
                 renamedFrom = name;
             }
-            await writeFile(join(dir, finalName + '.md'), serializePersona({ ...args, name: finalName }), 'utf8');
+            // 先把新内容写进临时文件、再一次性改名到位。原先的顺序是「先 rename 旧文件 → 再
+            // writeFile 新文件」，writeFile 一旦失败就留下「新名字 + 旧内容」的半态 —— 用户看到
+            // 改名成功、内容却还是旧的。临时名以 `.` 开头且不以 `.md` 结尾，扫描时天然被忽略。
+            const finalTarget = join(dir, finalName + '.md');
+            const tmp = join(dir, `.${finalName}.tmp-${process.pid}-${Date.now()}`);
+            try {
+                await writeFile(tmp, serializePersona({ ...args, name: finalName }), 'utf8');
+                await rename(tmp, finalTarget);
+            }
+            catch (e) {
+                await rm(tmp, { force: true }).catch(() => undefined);
+                return { ok: false, error: `保存人设失败: ${message(e)}` };
+            }
+            // 改名时旧文件等新文件就位后再清：清失败只多一份副本，不丢数据。
             if (renamedFrom)
-                await renamePersonaInEnabled(renamedFrom, finalName).catch(() => undefined);
+                await rm(join(dir, renamedFrom + '.md'), { force: true }).catch(() => undefined);
             cache = null;
-            return { ok: true, name: finalName, ...(renamedFrom ? { renamedFrom } : {}) };
+            return withEnabledNote({ ok: true, name: finalName, ...(renamedFrom ? { renamedFrom } : {}) }, async () => { if (renamedFrom)
+                await renamePersonaInEnabled(renamedFrom, finalName); });
         },
         /**
          * 删除人设 = **移入回收站**（`hub/trash/agents-trash/<id>/persona.md`）。
@@ -671,9 +756,8 @@ export function createSubagentService(ctx, opts) {
             const moved = await moveToTrash('subagents', name, [{ from: target, dest: 'persona.md' }]);
             if (moved.ok === false)
                 return { ok: false, error: `移入回收站失败: ${moved.error}` };
-            await removePersonaFromEnabled(name).catch(() => undefined);
             cache = null;
-            return { ok: true, name, trashId: moved.id };
+            return withEnabledNote({ ok: true, name, trashId: moved.id }, () => removePersonaFromEnabled(name));
         },
         'subagent-trash-list': async () => ({ ok: true, trash: await listTrashEntries('subagents') }),
         'subagent-trash-restore': async (args) => {
@@ -697,9 +781,8 @@ export function createSubagentService(ctx, opts) {
             }
             await purgeTrashEntry('subagents', id);
             // v0.8.5：回收站恢复默认不启动（与新建/导入同口径）。
-            await materializeEnabledExcluding([entry.name]).catch(() => undefined);
             cache = null;
-            return { ok: true, name: entry.name };
+            return withEnabledNote({ ok: true, name: entry.name }, () => materializeEnabledExcluding([entry.name]));
         },
         'subagent-trash-delete': async (args) => {
             const id = String((args && args.id) || '').trim();
@@ -747,11 +830,10 @@ export function createSubagentService(ctx, opts) {
                 }
                 imported.push(target.name);
             }
-            if (imported.length) {
-                await materializeEnabledExcluding(imported).catch(() => undefined);
+            if (imported.length)
                 cache = null;
-            }
-            return { ok: true, imported, skipped };
+            return withEnabledNote({ ok: true, imported, skipped }, async () => { if (imported.length)
+                await materializeEnabledExcluding(imported); });
         },
         /**
          * 子智能体开关（v0.8）：停用 = 不注入目录段、subagent_manager_list/run 不可见；文件本体不动。
@@ -784,6 +866,13 @@ export function createSubagentService(ctx, opts) {
             return { ok: true, name, enabled: args.enabled === true };
         },
     };
+    // 写 op 统一进串行队列（理由见上方 mutationQueue 的说明）。放在这里统一包、而不是逐个手写：
+    // 以后新增写 op 只改 writeOps 一处，不会漏掉。
+    for (const name of writeOps) {
+        const fn = ops[name];
+        if (typeof fn === 'function')
+            ops[name] = (args) => enqueueMutation(() => fn(args));
+    }
     const enabledStore = {
         /** 指定名单里当前被停用的（进入模式拍快照用：只记将被启用的行，退出时精确停回）。 */
         async disabledAmong(names) {
@@ -803,35 +892,64 @@ export function createSubagentService(ctx, opts) {
             const state = new Map(docs.map((d) => [d.name, d.enabled !== false]));
             return docs.map((d) => d.name).filter((n) => state.get(n) === true);
         },
-        /** 批量启停；只碰给出的名字，人设已不存在的跳过（别把悬空名写进集合）。 */
+        /** 批量启停；只碰给出的名字，人设已不存在的跳过（别把悬空名写进集合）。
+         *  同样走写队列：它由场景档案引擎直接调用（不经 op 表），不排队就会与开关 op 互相覆盖。 */
         async setEnabled(names, enabled) {
-            const docs = await list();
-            const set = await readEnabled();
-            const base = (set === null ? docs.map((d) => d.name) : set.slice()).filter((n) => docs.some((d) => d.name === n));
-            let dirty = false;
-            for (const n of names) {
-                if (!docs.some((d) => d.name === n))
-                    continue;
-                const i = base.indexOf(n);
-                if (enabled && i < 0) {
-                    base.push(n);
-                    dirty = true;
+            await enqueueMutation(async () => {
+                const docs = await list();
+                const set = await readEnabled();
+                const base = (set === null ? docs.map((d) => d.name) : set.slice()).filter((n) => docs.some((d) => d.name === n));
+                let dirty = false;
+                for (const n of names) {
+                    if (!docs.some((d) => d.name === n))
+                        continue;
+                    const i = base.indexOf(n);
+                    if (enabled && i < 0) {
+                        base.push(n);
+                        dirty = true;
+                    }
+                    if (!enabled && i >= 0) {
+                        base.splice(i, 1);
+                        dirty = true;
+                    }
                 }
-                if (!enabled && i >= 0) {
-                    base.splice(i, 1);
-                    dirty = true;
+                if (dirty) {
+                    await writeEnabled(base);
+                    cache = null;
                 }
-            }
-            if (dirty) {
-                await writeEnabled(base);
-                cache = null;
-            }
+            });
         },
     };
-    return { list, runSerial, ops, enabledStore, writeOps: new Set(['subagent-create', 'subagent-update', 'subagent-delete', 'subagent-import', 'subagent-toggle', 'subagent-trash-restore', 'subagent-trash-delete']) };
+    return { list, runSerial, ops, enabledStore, writeOps };
 }
-function validPersonaName(name) {
-    return name.length > 0 && name.length <= 64 && !name.startsWith('.') && !/[\\/<>:"|?*]/.test(name);
+/** 人设名长度上限（字符）。 */
+const PERSONA_NAME_MAX = 64;
+/**
+ * 官方 `tools.restrict()` 的**保留名**：名单里出现它时，官方不是"当它不存在"，而是**直接抛错**
+ * （`dsh-tools/lib/index.js:2800`：cannot name reserved PTC mode presentation transport），
+ * 子代理当场起不来。
+ *
+ * 为什么必须在这里显式剔除：`run_code` 在宿主面上是**合法可见**的工具名（非 native 模式下
+ * 由官方补进可见集合），所以"按当前存在的工具名过滤未知项"剔不掉它 —— 过滤留下的正好是
+ * 会让官方抛错的那个。用户的直观预期是"写了就生效（或至少被忽略）"，实际却是整个委派失败。
+ */
+const RESERVED_TOOL_NAMES = new Set(['run_code']);
+/** 把保留名从名单里剔掉，并说明剔了什么（不静默）。 */
+function stripReserved(names) {
+    const kept = [];
+    const dropped = [];
+    for (const name of names)
+        (RESERVED_TOOL_NAMES.has(name) ? dropped : kept).push(name);
+    return { kept, dropped };
+}
+/**
+ * 人设名合法性：谓词收敛到 `../paths.ts`（此前这里与 rules / imports / skills 各写一套，
+ * 缺了 Windows 保留设备名与控制字符检查 —— 设备名在 Windows 上创建即失败）。
+ * 注意：**不挡花括号**，手写 frontmatter 仍造得出 `{{…}}` 名字，渲染侧照旧做中和
+ * （见 renderPersonaPrompt）。
+ */
+export function validPersonaName(name) {
+    return isValidSegment(name, PERSONA_NAME_MAX);
 }
 /** 字符串数组规范化（非数组/空项都丢掉）。 */
 function toStringList(value) {
@@ -908,34 +1026,57 @@ export function serializePersona(args) {
  * 按**当前会话的 Agent 预设**决定这次委派下发什么工具限制。
  *
  * 为什么必须按预设分：子代理跑在父会话的预设里（官方 `composeFrom(childCtx, parent.ctx)`），
- * 而各预设的工具集合差别极大（极简模式只有持久 shell），官方 `tools.restrict()` 遇到
- * 名单里不存在的工具名会直接抛错、子代理根本起不来。所以：
+ * 而各预设的工具集合差别极大（极简模式只有持久 shell）。官方 `tools.restrict()` 实有
+ * **四个**抛错点（`dsh-tools/lib/index.js:2790-2803`），抛了子代理就起不来：
+ *
+ *   ① 非 scoped context 调用（宿主 `childCtx` 已满足，无风险）；
+ *   ② `allow` 与 `deny` 同时缺省 ⇒ `restrict({})` 抛 —— 本函数用 `filter: null`（不下发）
+ *      表达"不加限制"，**从不**调用 `restrict({})`；
+ *   ③ **名单含保留名 `run_code` 即抛** —— 而它在宿主面上是合法可见名，"按现有工具名过滤"
+ *      剔不掉它，所以这里**显式剔除**并写进 note（见 `stripReserved`）；
+ *   ④ 未知名 ⇒ 抛（唯一此前被记录的那条）。
  *
+ * 所以：
  *   - 当前预设配了名单（且名单非空）→ 用它；白名单额外并入**当时真实在跑的 MCP 工具**
  *     （官方 allow 是"清单之外全砍"，不并进来会把 MCP 一起砍掉；用户裁定：子代理要能
  *     用当前启动的 MCP）；
  *   - 当前预设没配 → 回落旧的全局 `tools` / `toolsDeny`（老文件行为不变）；
- *   - 名单里有已经消失的工具名 → **丢掉并在 note 里如实说明**（不接受静默失效）；
+ *   - 名单里有已经消失的工具名、或写了保留名 → **丢掉并在 note 里如实说明**（不接受静默失效）；
  *   - 判断不了当前预设（老宿主 / 异常）→ 不按模式施加，并在 note 里说明。
  *
+ * ⚠ 两种失败方向都要记账（它们互斥，且都不是"没生效"这么简单）：名单全落空时本函数返回
+ * `filter: null` = **放宽到不限制**（fail-open）；保留名没剔干净时官方抛错 = **收紧到起不来**。
+ *
  * 三态返回：`filter: null` = 明确不加限制；`filter: {...}` = 下发该限制。
  */
 export function decideToolFilter(persona, presetId, known) {
     const rule = presetId === null ? undefined : persona.toolsByPreset?.[presetId];
     if (rule && rule.names.length) {
-        const usable = rule.names.filter((name) => known.names.has(name));
+        const knownNames = rule.names.filter((name) => known.names.has(name));
+        const reserved = stripReserved(knownNames);
+        const usable = reserved.kept;
         const dropped = rule.names.filter((name) => !known.names.has(name));
-        const droppedNote = dropped.length ? `名单里这些工具当前不存在，已忽略：${dropped.join('、')}` : undefined;
+        const notes = [];
+        if (dropped.length)
+            notes.push(`名单里这些工具当前不存在，已忽略：${dropped.join('、')}`);
+        if (reserved.dropped.length) {
+            notes.push(`名单里的 ${reserved.dropped.join('、')} 是官方保留名（写进工具限制会让子代理直接起不来），已忽略`);
+        }
         if (!usable.length) {
-            return { filter: null, note: `「${presetId}」的${rule.mode === 'allow' ? '白' : '黑'}名单里没有当前存在的工具，本次不施加工具限制` };
+            const note = notes.length ? notes.join('；') : undefined;
+            return { filter: null, note: note ?? `「${presetId}」的${rule.mode === 'allow' ? '白' : '黑'}名单里没有当前存在的工具，本次不施加工具限制` };
         }
+        const droppedNote = notes.length ? notes.join('；') : undefined;
         if (rule.mode === 'allow')
             return { filter: { allow: [...new Set([...usable, ...known.mcp])] }, ...(droppedNote === undefined ? {} : { note: droppedNote }) };
         return { filter: { deny: usable }, ...(droppedNote === undefined ? {} : { note: droppedNote }) };
     }
     // 旧格式（全局名单）：保持老行为，白名单同样并入 MCP。
-    const legacyAllow = (persona.tools || []).filter((name) => known.names.has(name));
-    const legacyDeny = (persona.toolsDeny || []).filter((name) => known.names.has(name));
+    const legacyKnown = [...(persona.tools || []), ...(persona.toolsDeny || [])].filter((name) => known.names.has(name));
+    const legacyReserved = stripReserved(legacyKnown);
+    const legacyKept = new Set(legacyReserved.kept);
+    const legacyAllow = (persona.tools || []).filter((name) => legacyKept.has(name));
+    const legacyDeny = (persona.toolsDeny || []).filter((name) => legacyKept.has(name));
     const legacyDropped = [...(persona.tools || []), ...(persona.toolsDeny || [])].filter((name) => !known.names.has(name));
     const filter = {
         ...(legacyAllow.length ? { allow: [...new Set([...legacyAllow, ...known.mcp])] } : {}),
@@ -951,6 +1092,9 @@ export function decideToolFilter(persona, presetId, known) {
     }
     if (legacyDropped.length)
         notes.push(`名单里这些工具当前不存在，已忽略：${legacyDropped.join('、')}`);
+    if (legacyReserved.dropped.length) {
+        notes.push(`名单里的 ${legacyReserved.dropped.join('、')} 是官方保留名（写进工具限制会让子代理直接起不来），已忽略`);
+    }
     if (!Object.keys(filter).length) {
         if (presetId === null && !notes.length)
             notes.push('没能判断当前会话的 Agent 预设，本次不施加工具限制');

package/lib/tools/deps.js

@@ -0,0 +1,8 @@
+// model 工具（ctx.tools.register + defineTool）各域共用的依赖与 helper。
+//
+// 为什么单独一个文件：五个域的工具都要同一批依赖（defineTool 包装、注册出口、场景锁定
+// 守卫、注入边界提示），各写一份会漂移。
+/** 每个工具 output.render 的统一出口：把字符串包成宿主要的 content 数组。 */
+export function text(value) {
+    return [{ type: 'text', text: value }];
+}

package/lib/tools/mcp.js

@@ -0,0 +1,110 @@
+// MCP 域的 model 工具（2026-09-19 从 index.ts 的注册区抽出）：
+// mcp_manager_list / mcp_manager_set_enabled / mcp_manager_restart / mcp_manager_add。
+import { DEFAULT_MCP_NOTE_MAX_LENGTH, normalizeMcpNote } from '../mcp/state-section.js';
+import { text } from './deps.js';
+export function buildMcpTools(deps) {
+    const { defineTool, register } = deps;
+    register(defineTool({
+        name: 'mcp_manager_list',
+        description: 'List configured MCP servers (level, enabled state, live loader status, tool count excluding switched-off tools, note). Read a server\'s note before choosing it. The same list is injected into your context each turn (the「本机 MCP 服务器的当前状态」system-reminder); this tool is the raw view — all=true includes disabled servers. Defaults to enabled servers; pass all=true for every configured server.',
+        parameters: {
+            all: { type: 'boolean', description: 'Include disabled servers (default false).' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args, exec) {
+            const showAll = Boolean(args && args.all === true);
+            // 必须走 mcpmListView()（= mcpmRowsWithNotes(false)）：备注在这里合入，且未打码的
+            // url/headers/env 已被打码。备注是本插件 MCP 这一项的真正价值（用户写给未来模型的
+            // 决策提示，如「A 挂了改用 B」），而它只走注入通道 —— 压制型预设下不注入时，
+            // 这里就是唯一的读取路径。
+            const r = await deps.mcpmListView();
+            if (!r.ok)
+                throw new Error(r.error);
+            const all = r.rows || [];
+            // 默认只列「已启用」的（用户裁定 2026-09-16，与技能 / 记忆列表同口径）：停用的服务器
+            // 模型调不到，列出来只是噪音。表头给出全量口径，所以不会变成盲区。
+            const shown = showAll ? all : all.filter((x) => !x.disabled);
+            const summary = shown.map((x) => {
+                const note = normalizeMcpNote(x.notes, DEFAULT_MCP_NOTE_MAX_LENGTH);
+                // 工具数 = 可用数（停用表扣减后）：段里给模型的是同一个口径，模型据此与
+                // 自己 schema 里的 `mcp__*` 工具对得上；被场景收窄 / 手动关掉的工具不算。
+                const usableTools = typeof x.enabledToolCount === 'number' ? x.enabledToolCount : x.toolCount;
+                return x.id + ' | ' + x.serverName + ' | ' + x.level + ' | ' + (x.disabled ? 'disabled' : 'enabled') +
+                    (x.live ? ' | loader:' + (x.live.enabled ? 'on' : 'off') + (x.live.phase ? ':' + x.live.phase : '') : '') +
+                    (typeof usableTools === 'number' ? ' | tools:' + usableTools : '') +
+                    (note ? ' | user-hint:' + note : '');
+            });
+            const header = 'MCP servers: ' + (showAll
+                ? all.length + ' configured'
+                : shown.length + ' enabled of ' + all.length + ' configured' +
+                    (shown.length === all.length ? '' : ' (pass all=true for every configured server)')) + '\n';
+            // 注入边界：压制型预设（persona complete / 关闭运行时上下文，如极简）下本插件
+            // 默认不注入 —— 模型只有 mcp__* 的工具名与参数，没有服务级信息。不说明的话，
+            // 模型会把「能调用这些工具」当成「已经知道有哪些 server、用户给它们写了什么备注」。
+            // 提示本身不点名任何工具，所以挂在哪个发现型工具上都不会出现循环指引。
+            const notice = await deps.reachNoticeForAgent(deps.presetRoster(), exec && exec.agent && exec.agent.ctx, deps.injectNoticeOptions());
+            return header + (summary.join('\n') || '(none)') + notice;
+        },
+    }));
+    register(defineTool({
+        name: 'mcp_manager_set_enabled',
+        description: 'Enable or disable one configured MCP server (writes the patch file; takes effect via HMR).',
+        parameters: {
+            id: { type: 'string', required: true, description: 'Entry id of the MCP server, e.g. mcp-stepfun-web-search.' },
+            level: { type: 'string', required: true, description: 'project or global.' },
+            enabled: { type: 'boolean', required: true, description: 'true to enable, false to disable.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args) {
+            const blocked = await deps.lockedSceneGuard();
+            if (blocked)
+                throw new Error(blocked);
+            const r = await deps.mcpmSetEnabled({ id: args.id, level: args.level, enabled: args.enabled });
+            if (!r.ok)
+                throw new Error(r.error);
+            // 场景未锁定时，页面 / 模型改的开关都要落进当前场景的档案（与 handlers 层同一套同步）。
+            const syncErr = await deps.syncSwitchToScene('mcpm-set-enabled', args);
+            return 'OK: ' + args.id + ' now ' + (args.enabled ? 'enabled' : 'disabled') +
+                (syncErr ? '\nWARN: 当前场景档案未同步（' + syncErr + '）' : '');
+        },
+    }));
+    register(defineTool({
+        name: 'mcp_manager_restart',
+        description: 'Restart one configured MCP server (disable + re-enable; reconnect and re-sync tools).',
+        parameters: {
+            id: { type: 'string', required: true, description: 'Entry id of the MCP server, e.g. mcp-stepfun-web-search.' },
+            level: { type: 'string', required: true, description: 'project or global.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args) {
+            const r = await deps.mcpmRestart({ id: args.id, level: args.level });
+            if (!r.ok)
+                throw new Error(r.error);
+            return 'OK: ' + args.id + ' restarted';
+        },
+    }));
+    register(defineTool({
+        name: 'mcp_manager_add',
+        description: 'Add a new MCP server (streamable-http or stdio) at project or global level.',
+        parameters: {
+            serverName: { type: 'string', required: true, description: 'Unique server name (1-32 chars, [A-Za-z0-9_-]).' },
+            transport: { type: 'string', required: true, description: 'streamable-http or stdio.' },
+            url: { type: 'string', description: 'Server URL (required for streamable-http).' },
+            command: { type: 'string', description: 'Executable (required for stdio).' },
+            args: { type: 'string', description: 'Arguments, space separated (stdio).' },
+            headers: { type: 'string', description: 'Extra headers as key=value lines (streamable-http).' },
+            env: { type: 'string', description: 'Extra env vars as key=value lines (stdio).' },
+            level: { type: 'string', description: 'project or global (default project).' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args) {
+            const blocked = await deps.lockedSceneGuard();
+            if (blocked)
+                throw new Error(blocked);
+            const r = await deps.mcpmAdd(args);
+            if (!r.ok)
+                throw new Error(r.error);
+            return 'OK: added ' + r.row.id + ' at ' + r.row.level;
+        },
+    }));
+}

package/lib/tools/memory.js

@@ -0,0 +1,87 @@
+// 记忆（rules）域的 model 工具（2026-09-19 从 index.ts 的注册区抽出）：
+// memory_manager_list / memory_manager_read / memory_manager_write。
+//
+// 活动场景的记忆正文会自动注入上下文（无需调用工具读取）；这里的工具用于查询/编辑规则
+// 本身。memory_manager_write 受 tools/pre-execute 审批门禁（D2）。
+// 路径锚点：$DSH_HOME/tool-management/memories/<场景>/…（场景 `global` = 界面「全局」）。
+import { text } from './deps.js';
+export function buildMemoryTools(deps) {
+    const { defineTool, register } = deps;
+    register(defineTool({
+        name: 'memory_manager_list',
+        description: 'List memories under ~/.dsh/tool-management/memories (id, scene, enabled, description). The ones actually injected are carried in your context each turn (the「本机当前的场景和记忆」system-reminder); use this tool to find ids/paths or to see entries that are off. Defaults to the memories that will actually be injected; pass all=true for every entry.',
+        parameters: {
+            group: { type: 'string', description: 'Optional scene filter.' },
+            all: { type: 'boolean', description: 'Include memories that are off, in an inactive scene, or shadowed (default false).' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args, exec) {
+            const showAll = Boolean(args && args.all === true);
+            const r = await deps.rulesOps['rules-list'](args);
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || '读取规则失败');
+            // 「会注入」的判定与记忆段同源（renderSceneMemory）：global 场景恒常注入，其余场景要
+            // 在 index.active 里，再叠加单条 enabled 与同名 bundle 的 shadowed。默认只列这些，
+            // 全列一次会把没启用的条目也算进上下文（用户裁定 2026-09-16，与技能列表同口径）。
+            const sceneOn = (group) => group === 'global' ||
+                (group !== '' && (r.activeMode === 'all' || String(r.activeScene || '') === group));
+            const stateOf = (x) => {
+                if (x.shadowed === true)
+                    return { injects: false, label: '被同名覆盖' };
+                if (x.enabled === false)
+                    return { injects: false, label: '已停用' };
+                if (!sceneOn(String(x.group || '')))
+                    return { injects: false, label: '场景未启用' };
+                return { injects: true, label: '已启用' };
+            };
+            const rows = (r.rules || []).map((x) => ({ x, ...stateOf(x) }));
+            const shown = showAll ? rows : rows.filter((row) => row.injects);
+            const lines = shown.map(({ x, label }) => ('- ' + x.id + ' [' + (x.group || '未归属场景') + '] ' + label +
+                (x.description ? ' — ' + x.description : '')));
+            const scenes = (r.scenes || []).map((s) => (s.label || s.name) + (s.active ? '(启用)' : '(未启用)')).join('、');
+            const header = '记忆：' + (showAll
+                ? rows.length + ' 条'
+                : shown.length + ' 条会注入 / 共 ' + rows.length + ' 条' +
+                    (shown.length === rows.length ? '' : '（传 all=true 看全部）')) + '\n';
+            // 注入边界：压制型预设（persona complete / 关闭运行时上下文）下本插件默认不注入，
+            // 此时列出的记忆**不在**模型上下文里。必须说出来，否则模型会假设自己已经看到正文。
+            const notice = await deps.reachNoticeForAgent(deps.presetRoster(), exec && exec.agent && exec.agent.ctx, deps.injectNoticeOptions());
+            return header + (lines.join('\n') || '(无记忆)') +
+                '\n场景：' + (scenes || '(无)') + (r.activeMode === 'all' ? '（默认全部启用）' : '（已收窄）') + notice;
+        },
+    }));
+    register(defineTool({
+        name: 'memory_manager_read',
+        description: 'Read the full body of one memory under ~/.dsh/tool-management/memories. Call it only for memories that are not already in your context (disabled, unassigned to a scene, or dropped by the injection budget).',
+        parameters: {
+            id: { type: 'string', required: true, description: 'Memory id like <scene>/<name>.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args) {
+            const r = await deps.rulesOps['rules-read'](args);
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || '读取规则失败');
+            return '# ' + r.rule.id + '\n\n' + (r.rule.body || '');
+        },
+    }));
+    register(defineTool({
+        name: 'memory_manager_write',
+        description: 'Create a new memory as ~/.dsh/tool-management/memories/<scene>/<name>.md. The scene must already exist (use global for the always-on scene).',
+        parameters: {
+            group: { type: 'string', required: true, description: 'Scene name (no path separators or < > : " | ? *); `global` = the always-on scene.' },
+            name: { type: 'string', required: true, description: 'Memory name = .md file name without extension; <=64 chars, no path separators or < > : " | ? *, must not start with a dot.' },
+            description: { type: 'string', required: true, description: 'One-sentence description (<=500 chars).' },
+            body: { type: 'string', required: true, description: 'Markdown body (<=256 KiB).' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args) {
+            const blocked = await deps.lockedSceneGuard();
+            if (blocked)
+                throw new Error(blocked);
+            const r = await deps.rulesOps['rules-create'](args);
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || '创建规则失败');
+            return 'OK: memory ' + r.rule.id + '（场景「' + (r.rule.group || '未归属') + '」启用后自动生效）';
+        },
+    }));
+}