dsh-plugin-tool-management 0.12.0 → 0.13.0

package/lib/skills/catalog.js

@@ -41,7 +41,7 @@ function isEnabled(row) {
  * 返回 `''` 表示没有可注入的技能 —— 没装技能的用户零 token 成本。
  * 名字按字典序排序：底层目录枚举顺序变化时文本仍逐字节稳定（前缀缓存契约）。
  */
-export function renderSkillCatalog(data, maxEntries = SKILL_CATALOG_MAX_ENTRIES, maxDescription = SKILL_CATALOG_DESCRIPTION_MAX_LENGTH) {
+export function renderSkillCatalog(data, maxEntries = SKILL_CATALOG_MAX_ENTRIES, maxDescription = SKILL_CATALOG_DESCRIPTION_MAX_LENGTH, listToolVisible = true) {
     const roots = (data && typeof data === 'object' ? data.roots : undefined) ?? [];
     const byName = new Map();
     if (Array.isArray(roots)) {
@@ -77,8 +77,13 @@ export function renderSkillCatalog(data, maxEntries = SKILL_CATALOG_MAX_ENTRIES,
     // （2026-09-18 起，见 context-inject.ts 的 DOMAIN_FRAME 的 `how` 行）—— 一处内容一个出处。
     const out = [...lines];
     const hidden = sorted.length - shown.length;
-    if (hidden > 0)
-        out.push('', `（另有 ${hidden} 个未列出，用 \`skill_manager_list\` 查。）`);
+    // 查询工具被关掉（兼容页的模型工具表）时只说"还有几个"：点名一个模型手里没有的工具，
+    // 它只会去猜名字。数量照报 —— 那是实话，与有没有出口无关。
+    if (hidden > 0) {
+        out.push('', listToolVisible
+            ? `（另有 ${hidden} 个未列出，用 \`skill_manager_list\` 查。）`
+            : `（另有 ${hidden} 个未列出。）`);
+    }
     return out.join('\n');
 }
 /**
@@ -95,7 +100,7 @@ export function createSkillCatalog(deps, opts = {}) {
         try {
             const result = await deps.state();
             if (result && result.ok !== false) {
-                value = renderSkillCatalog(result.data ?? result, opts.maxEntries, opts.maxDescription);
+                value = renderSkillCatalog(result.data ?? result, opts.maxEntries, opts.maxDescription, deps.listToolVisible ? deps.listToolVisible() : true);
             }
         }
         catch { /* 保留上一次的值；首次失败则维持 '' */ }

package/lib/skills/core.js

@@ -2840,6 +2840,15 @@ export async function getProviderSkill(candidate, options = {}) {
         typeof options.cwd === "string") {
         root = (await projectRoots([options.cwd])).find((item) => item.key === locator.rootKey);
     }
+    // 自定义技能目录不住在 `userRoots()` 里，它住在状态文件的 `customRoots` 里，所以
+    // `rootByKey()` 恒取不到。少了这一支就是「列得出、调不动」：`state()` 扫的是
+    // `userRoots() + customRootsFromState()`，官方 catalog 因此把目录里的技能列给模型，
+    // 而模型真去 `skill` 工具取正文时这里返回 undefined —— 症状是
+    // `skill "brainstorming" is unknown or no longer available`（用户 2026-09-22 报的）。
+    if (!root &&
+        CUSTOM_ROOT_KEY_RE.test(locator.rootKey)) {
+        root = customRootsFromState((await readManagerState()).state).find((item) => item.key === locator.rootKey);
+    }
     if (!root)
         return undefined;
     try {

package/lib/subagents/catalog.js

@@ -11,7 +11,7 @@ import { filterBySceneBinding } from './tools.js';
  */
 export const DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH = 500;
 /** 段里最多列几个人设；超出部分只报数量，让模型自己去调 subagent_manager_list。 */
-export const DEFAULT_CATALOG_MAX_ENTRIES = 40;
+export const DEFAULT_CATALOG_MAX_ENTRIES = 50;
 /** 无描述时的占位，与 `subagent_manager_list` 工具的输出保持同一口径。 */
 const NO_DESCRIPTION = '(无描述)';
 /**
@@ -43,7 +43,7 @@ export function catalogDescription(value, maxLength) {
  * （`- **名字** — 描述`），"这是什么 + 该拿它做什么"整句交给注入通道的引导语。于是这里
  * 既没有标题也没有"可委派给下列子智能体"那句：一处内容只有一个出处。
  */
-export function renderSubagentCatalog(allowed, maxEntries = DEFAULT_CATALOG_MAX_ENTRIES, maxDescription = DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH) {
+export function renderSubagentCatalog(allowed, maxEntries = DEFAULT_CATALOG_MAX_ENTRIES, maxDescription = DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH, listToolVisible = true) {
     if (!allowed.length)
         return '';
     const sorted = [...allowed].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
@@ -58,8 +58,12 @@ export function renderSubagentCatalog(allowed, maxEntries = DEFAULT_CATALOG_MAX_
     // 查询工具**只在真被 40 条上限截掉时**才出现：常态下不提，省常驻字符，也免得模型为了
     // 「确认一遍」去调它（用户裁定：没列出来的就是当前不想要的）。与 MCP 状态段的
     // `（另有 N 台未列出。）` 同一句式，但这里多给一个出口——不给人设就真的找不回来了。
-    if (hidden > 0)
-        out.push('', `（另有 ${hidden} 个未列出，用 \`subagent_manager_list\` 查。）`);
+    if (hidden > 0) {
+        // 与技能目录同一条纪律：点名一个被关掉的工具只会让模型去猜名字。数量照报。
+        out.push('', listToolVisible
+            ? `（另有 ${hidden} 个未列出，用 \`subagent_manager_list\` 查。）`
+            : `（另有 ${hidden} 个未列出。）`);
+    }
     return out.join('\n');
 }
 /**
@@ -101,7 +105,7 @@ export function createSubagentCatalog(deps, opts = {}) {
             const cached = rendered.get(depth);
             if (cached !== undefined)
                 return cached;
-            const out = renderSubagentCatalog(allowed.filter((p) => catalogInjectedAt(p, depth)), maxEntries, maxDescription);
+            const out = renderSubagentCatalog(allowed.filter((p) => catalogInjectedAt(p, depth)), maxEntries, maxDescription, deps.listToolVisible ? deps.listToolVisible() : true);
             rendered.set(depth, out);
             return out;
         },

package/lib/subagents/tools.js

@@ -22,7 +22,7 @@ export async function filterBySceneBinding(docs, enabledSceneLists) {
 export function defineSubagentManagerListTool(subagents) {
     return {
         name: 'subagent_manager_list',
-        description: 'List available personas (pre-configured subagent profiles) with their descriptions. The same catalog is injected into your context each turn (the「可委派的子智能体」system-reminder); call this tool before subagent_manager_run for the full, always-current list.',
+        description: 'List personas (pre-configured subagent profiles) with their descriptions. The「可委派的子智能体」reminder carries the same catalog; call this for the always-current full list before subagent_manager_run.',
         parameters: {},
         output: {
             schema: { type: 'string' },
@@ -59,7 +59,14 @@ export function defineSubagentManagerRunTool(subagents) {
         // 「何时不用」那一段保留（2026-09-17，用户采纳的四条里的第 6 条）：参照 Claude Code 的
         // Agent 工具（`AgentTool/prompt.ts:232-240`），把"不该用"写成**带替代工具**的具体清单
         // （具体路径→Read；找定义→Grep/Glob），比笼统说"这个很贵"有用得多。
-        description: 'Run a named persona as a subagent: it gets the persona as its own system prompt, works on `task`, and returns only its final output.\n\nTwo modes: by default the child starts fresh — it cannot see this conversation, so `task` must be self-contained. With `inherit: true` the child is seeded with this conversation\'s finished turns (the same mechanism as the host\'s `subagent_fork`), so `task` only states what is new — use it for follow-ups on work already completed. Only **finished** turns are inherited: a delegation made during the current turn inherits nothing from that turn, so a mid-turn hand-off still needs a self-contained `task`.\n\nWrite `task` as the goal plus the context it needs — do not prescribe method or output format: those belong to the persona.\n\nWhen to use: work that matches one of the personas in the「可委派的子智能体」system-reminder injected into your context (or from subagent_manager_list) — a review, a focused investigation, a piece of writing — where the detail does not belong in your own context. Work that matches a persona belongs here, not in the host\'s `subagent` / `subagent_fork`: those take no persona. Use them only when no persona fits, or when you need a background run (this tool waits for the result).\n\nWhen NOT to use: reading a specific file (use Read), finding a definition (use Grep/Glob), or touching two or three files (use Read directly).',
+        //
+        // 2026-09-23（用户裁定）：与官方两个委派工具的**分界规则**从描述里删掉 —— 注入通道的
+        // `how` 行（context-inject.ts 的 `DOMAIN_FRAME.subagents`）已经逐字说过一遍，而两份都在
+        // 每轮上下文里 = 同一件事付两次 token。留注入那份（它出现在"正在选工具"的那一刻）。
+        // 代价如实记下：子智能体域被关掉、或走压制型预设时上下文里没有那条 how 行，模型只剩本
+        // 描述与 `agent` 参数说明（"Persona name from subagent_manager_list"）—— 够它认出这条是
+        // 带人设的委派通道，但"没有人设贴合时才用官方那两个"这层分界就没人说了。
+        description: 'Run a named persona as a subagent: it gets the persona as its own system prompt, works on `task`, and returns only its final output.\n\nModes: by default a fresh child that cannot see this conversation, so `task` must be self-contained. With `inherit: true` it also gets this conversation\'s **finished** turns (like the host\'s `subagent_fork`) — the current turn is never included, so a mid-turn hand-off still needs a self-contained `task`.\n\n`task` = the goal plus the context it needs; leave method and output format to the persona.\n\nUse it when the work matches a persona in the「可委派的子智能体」reminder (a review, an investigation, a piece of writing) and the detail should not sit in your own context. Not for reading a file (Read), finding a definition (Grep/Glob), or touching two or three files.',
         parameters: {
             agent: { type: 'string', required: true, description: 'Persona name from subagent_manager_list.' },
             task: { type: 'string', required: true, description: 'The task for the subagent: the goal plus the context it needs. Self-contained by default; with inherit: true it only needs to state what is new. Leave method and output format to the persona.' },

package/lib/tools/mcp.js

@@ -48,7 +48,7 @@ export function buildMcpTools(deps) {
     }));
     register(defineTool({
         name: 'mcp_manager_set_enabled',
-        description: 'Enable or disable one configured MCP server (writes the patch file; takes effect via HMR).',
+        description: 'Enable or disable one configured MCP server (writes the patch file; hot-reloaded). Only when the user asks or approves.',
         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.' },
@@ -70,7 +70,7 @@ export function buildMcpTools(deps) {
     }));
     register(defineTool({
         name: 'mcp_manager_restart',
-        description: 'Restart one configured MCP server (disable + re-enable; reconnect and re-sync tools).',
+        description: 'Restart one configured MCP server (disable + re-enable; reconnects and re-syncs tools). Only when the user asks or approves.',
         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.' },
@@ -85,7 +85,7 @@ export function buildMcpTools(deps) {
     }));
     register(defineTool({
         name: 'mcp_manager_add',
-        description: 'Add a new MCP server (streamable-http or stdio) at project or global level.',
+        description: 'Add a new MCP server (streamable-http or stdio) at project or global level. Only on the user\'s explicit request.',
         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.' },

package/lib/tools/memory.js

@@ -1,5 +1,5 @@
 // 记忆（rules）域的 model 工具（2026-09-19 从 index.ts 的注册区抽出）：
-// memory_manager_list / memory_manager_read / memory_manager_write。
+// memory_manager_list / _read / _write / _set_enabled / _update。
 //
 // 活动场景的记忆正文会自动注入上下文（无需调用工具读取）；这里的工具用于查询/编辑规则
 // 本身。memory_manager_write 受 tools/pre-execute 审批门禁（D2）。
@@ -9,7 +9,7 @@ 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.',
+        description: 'List memories (id, scene, enabled, description). What is injected each turn is in the「本机当前的场景和记忆」reminder; use this for ids/paths and for entries that are off. Defaults to the ones that would be injected; 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).' },
@@ -52,7 +52,7 @@ export function buildMemoryTools(deps) {
     }));
     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).',
+        description: 'Read the full body of one memory. Only for ones not already in your context (disabled, scene not active, or dropped by the byte budget).',
         parameters: {
             id: { type: 'string', required: true, description: 'Memory id like <scene>/<name>.' },
         },
@@ -64,9 +64,79 @@ export function buildMemoryTools(deps) {
             return '# ' + r.rule.id + '\n\n' + (r.rule.body || '');
         },
     }));
+    register(defineTool({
+        name: 'memory_manager_set_enabled',
+        // 为什么单独一个工具：注入实况里「这个域注入了几次 / 模型调了几次」都看得到，但模型此前
+        // 看得到一份记忆却开关不了它 —— 只能回一句"请你去界面上点"。启停是它替用户调整环境时
+        // 最常碰的一格，而 `rules-toggle` 这个 op 早就带齐了门禁（写令牌 + 场景冻结）。
+        // 三个写侧工具共用一句 consent（`Only when the user asks or approves.` / `Only on the
+        // user's instruction.`）：这些动的都是"以后每一轮都会带上"的东西，模型不该顺手做。
+        // 描述同时按"省 token"重写了一遍 —— 这 20 段文字每次请求都要发出去，废话是常驻成本。
+        description: 'Enable or disable one memory (index switch; the .md file is untouched). Disabled memories stop being injected, freeing the byte budget. Prefer this over deleting — it is reversible. Only when the user asks or approves.',
+        parameters: {
+            id: { type: 'string', required: true, description: 'Memory id like <scene>/<name> (from memory_manager_list).' },
+            enabled: { type: 'boolean', required: true, description: 'true = enable, false = disable; omission is refused.' },
+        },
+        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-toggle'](args);
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || '切换记忆启停失败');
+            const rule = r.rule || {};
+            // 「启用了一条不在启用场景里的记忆」是一次静默无效：单条开关拨上去了,注入集里却没有它。
+            // 这一句不说,模型会以为已经生效 —— 与 skill_manager_set_enabled 说清影子副本同一条理由。
+            let sceneNote = '';
+            try {
+                const all = await deps.rulesOps['rules-list']({});
+                if (all && all.ok !== false) {
+                    const group = String(rule.group || '');
+                    const on = group === 'global' || (group !== '' && (all.activeMode === 'all' || String(all.activeScene || '') === group));
+                    if (!on)
+                        sceneNote = ' — BUT its scene「' + group + '」is not the active one, so it still will not be injected; enable that scene (or move it to global) first';
+                }
+            }
+            catch {
+                sceneNote = '';
+            }
+            return 'OK: memory ' + String(rule.id || args.id) + ' ' + (rule.enabled === false ? 'disabled' : 'enabled') + sceneNote;
+        },
+    }));
+    register(defineTool({
+        name: 'memory_manager_update',
+        description: 'Update a memory: body, description, or name (renaming keeps the old file in the trash). Omit a field to keep it — this merges. Read it with memory_manager_read first and change one part rather than restating the file; if a memory already covers this, update that one instead of adding a second. Only on the user\'s instruction.',
+        parameters: {
+            id: { type: 'string', required: true, description: 'Memory id like <scene>/<name> (from memory_manager_list).' },
+            body: { type: 'string', description: 'New Markdown body (<=256 KiB, non-empty). Omit to keep the current body.' },
+            description: { type: 'string', description: 'New one-sentence description (<=500 chars). Empty string = drop it and re-derive from the body; omit = keep.' },
+            name: { type: 'string', description: 'New memory name (= file name). Omit to keep it.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args) {
+            const blocked = await deps.lockedSceneGuard();
+            if (blocked)
+                throw new Error(blocked);
+            // 三个可改字段一个都没给 → 直接拒。`rules-update` 会按"保留现有"落一次盘并刷新
+            // updatedAt,模型以为改了点什么,其实只是把文件重写了一遍。
+            const touches = ['body', 'description', 'name'].filter((k) => args[k] !== undefined);
+            if (!touches.length)
+                throw new Error('没有要改的东西：body / description / name 至少给一个');
+            const r = await deps.rulesOps['rules-update'](args);
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || '更新记忆失败');
+            const rule = r.rule || {};
+            return 'OK: updated ' + String(rule.id || args.id) + '（改了 ' + touches.join('、') + '）' +
+                (rule.id && String(rule.id) !== String(args.id) ? ' → 现在是 ' + rule.id : '');
+        },
+    }));
     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).',
+        // 「能推导的别记」「先查重」这两句是 0.13.0 加的：记忆是唯一直接吃注入预算的域
+        // （场景段 128 KiB），而模型很乐意把「这个项目用 pnpm」记一条 —— 那看一眼 `package.json`
+        // 就知道，记下来却永久占着每一轮请求。
+        description: 'Create a memory (the scene must already exist; global is the always-on one). Memories cost context on EVERY later request, so record only what cannot be re-derived from code, config or git, and check the list for one that already says this — update that instead of adding a near-duplicate. Only on the user\'s instruction.',
         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.' },
@@ -78,10 +148,40 @@ export function buildMemoryTools(deps) {
             const blocked = await deps.lockedSceneGuard();
             if (blocked)
                 throw new Error(blocked);
+            // 先扫一遍已有的：疑似重复只**说出来**，不拒绝 —— 猜错一次就把该记的东西记不下去，
+            // 比多记一条代价大得多；而且"像不像同一条"本来就是人判断的事。
+            const norm = (value) => String(value ?? '').toLowerCase().replace(/\s+/g, ' ').trim();
+            const wantName = norm(args && args.name);
+            const wantDesc = norm(args && args.description);
+            let similar = [];
+            try {
+                const before = await deps.rulesOps['rules-list']({});
+                if (before && before.ok !== false) {
+                    similar = (before.rules || [])
+                        .filter((x) => {
+                        const have = norm(x.name);
+                        const desc = norm(x.description);
+                        if (have === wantName)
+                            return true;
+                        if (wantDesc !== '' && desc !== '' && desc === wantDesc)
+                            return true;
+                        // 名字互相包含：只在两边都不短于 4 个字符时算，否则 "git" 会把所有条目都匹配上。
+                        return have.length >= 4 && wantName.length >= 4 && (have.includes(wantName) || wantName.includes(have));
+                    })
+                        .map((x) => String(x.id))
+                        .slice(0, 3);
+                }
+            }
+            catch { /* 查重读不到就当没查到：它不该拦住写入 */ }
             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 || '未归属') + '」启用后自动生效）';
+            // 刚建好的这条自己会在列表里，从名单里去掉。
+            similar = similar.filter((id) => id !== String(r.rule.id));
+            const dup = similar.length
+                ? `\n注意：已有 ${similar.length} 条名字或描述与它很像（${similar.join('、')}）—— 若是同一件事，改那一条而不是留着两条。`
+                : '';
+            return 'OK: memory ' + r.rule.id + '（场景「' + (r.rule.group || '未归属') + '」启用后自动生效）' + dup;
         },
     }));
 }

package/lib/tools/prompt.js

@@ -8,7 +8,7 @@ export function buildPromptTools(deps) {
     const { defineTool, register } = deps;
     register(defineTool({
         name: 'prompt_manager_list',
-        description: 'List AGENTS.md presets (id, active state, file path). Read that file to see a preset body. The preset in effect right now is injected into your context each turn (the「本机提示词」system-reminder, whose「来源：」line names the file). Defaults to the preset currently in effect; pass all=true for the whole library.',
+        description: 'List AGENTS.md presets (id, active state, file path); read that file for a preset body. The one in effect is in the「本机提示词」reminder, whose「来源：」line names the file. Defaults to the one in effect; all=true for the whole library.',
         parameters: {
             all: { type: 'boolean', description: 'Include inactive presets (default false).' },
         },
@@ -47,7 +47,7 @@ export function buildPromptTools(deps) {
     }));
     register(defineTool({
         name: 'prompt_manager_apply',
-        description: 'Apply one AGENTS.md preset by id; effective on the next turn. If a scene currently drives the baseline, this does NOT refuse: it rebinds that scene\'s prompt binding to the preset and re-syncs the scene, so ~/.dsh/AGENTS.md ends up holding the scene\'s (new) binding — tell the user which scene was rebound. Otherwise the preset is written to ~/.dsh/AGENTS.md directly. A locked scene blocks the call.',
+        description: 'Apply one AGENTS.md preset by id; effective next turn. If a scene drives the baseline this does NOT refuse — it rebinds that scene to the preset and re-syncs it, so tell the user which scene was rebound. A locked scene blocks the call. Only on the user\'s instruction.',
         parameters: {
             id: { type: 'string', required: true, description: 'Preset id (lowercase letters, digits, hyphens).' },
         },

package/lib/tools/skills.js

@@ -1,5 +1,5 @@
 // 技能域的 model 工具（2026-09-19 从 index.ts 的注册区抽出）：
-// skill_manager_list / skill_manager_set_enabled / skill_manager_create。
+// skill_manager_list / skill_manager_read / skill_manager_set_enabled / skill_manager_create。
 import { text } from './deps.js';
 export function buildSkillTools(deps) {
     const { defineTool, register } = deps;
@@ -7,7 +7,7 @@ export function buildSkillTools(deps) {
     // tools/pre-execute hook below (the model must ask before writing files).
     register(defineTool({
         name: 'skill_manager_list',
-        description: 'List DSH skills with enabled state, effective/shadowed status and source file path. The injected「本机技能目录」system-reminder carries callable skills and summaries only; use this tool to get a source file path (read the file for the full body) and to see entries that are off. Defaults to enabled skills only; pass all=true for every entry. A copy marked "shadowed by <root>" stays inactive even if enabled.',
+        description: 'List skills with enabled state, effective/shadowed status and source file path. The「本机技能目录」reminder carries callable skills and summaries only; use this for entries that are off and to see which source wins a name collision, and skill_manager_read for a body. Defaults to enabled only; all=true for every entry. A copy marked "shadowed by <root>" stays inactive even if enabled.',
         parameters: {
             all: { type: 'boolean', description: 'Include disabled and shadowed entries (default false).' },
         },
@@ -67,9 +67,87 @@ export function buildSkillTools(deps) {
             return header + (shown.map((row) => row.text).join('\n') || '(none)') + notice;
         },
     }));
+    // 一次拿到技能正文。此前读正文要两步：`skill_manager_list` 拿路径 → 自己再去读那个文件。
+    // 少的那一步不只是省一次调用 —— 目录里只有名字没有路径，而**同名技能常几份并存**（dsh /
+    // agents / claude / 自定义目录各一份），模型自己挑路径时很容易读到被覆盖的那份影子副本：
+    // 读完以为在用这个技能，其实生效的是另一份。这里先走 `skill-state`（core 的 markWinners
+    // 已在上面标出胜出者），再走 `skill-detail` 读那一份 —— 读到的永远是目录列出来的那一份。
+    register(defineTool({
+        name: 'skill_manager_read',
+        description: 'Read one skill\'s full SKILL.md body by name — what the「本机技能目录」reminder deliberately leaves out (it has names and summaries only). Resolves name collisions the same way, so you get the copy actually in effect; pass root only to inspect a specific (e.g. shadowed) source. Read-only.',
+        parameters: {
+            name: { type: 'string', required: true, description: 'Skill name, exactly as it appears in the catalog (kebab-case).' },
+            root: { type: 'string', description: 'Source root key (dsh/hub/agents/codex/claude, a project key, or a custom one). Default: the winning copy of this name.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
+        async execute(args, exec) {
+            const wanted = String((args && args.name) || '').trim();
+            if (!wanted)
+                throw new Error('name is required');
+            const rootWanted = String((args && args.root) || '').trim();
+            const state = await deps.skillsOps['skill-state']({});
+            if (!state || state.ok === false)
+                throw new Error((state && state.error) || 'skill-state failed');
+            const data = state.data || {};
+            const hits = [];
+            for (const root of data.roots || []) {
+                for (const skill of root.skills || []) {
+                    if (String(skill.declaredName || skill.name || '') !== wanted && String(skill.name || '') !== wanted)
+                        continue;
+                    if (rootWanted && String(root.key || '') !== rootWanted)
+                        continue;
+                    hits.push({
+                        rootKey: String(root.key || ''),
+                        // `skill-detail` 按**目录名**认条目（core 的 visibleEntryForRoot 比的是 entry.name），
+                        // 而目录名与 frontmatter 的 name 可以不同 —— 传错一个就读不到。
+                        entryName: String(skill.name || wanted),
+                        path: String(skill.path || ''),
+                        shadowedBy: skill.shadowedBy && skill.shadowedBy.root ? String(skill.shadowedBy.root) : '',
+                        preferred: skill.preferred === true,
+                        // 与 skill_manager_list 同一套启停推导（影子副本没有 enabled 字段）。
+                        enabled: skill.enabled !== undefined
+                            ? skill.enabled === true
+                            : (skill.invocationPolicyValid && skill.modelInvocable && skill.userInvocable && skill.managerEnabled !== false),
+                    });
+                }
+            }
+            if (!hits.length) {
+                throw new Error(rootWanted
+                    ? `no skill named "${wanted}" in source "${rootWanted}" — call skill_manager_list (pass all=true) to see what is installed`
+                    : `no skill named "${wanted}" — call skill_manager_list (pass all=true) to see what is installed`);
+            }
+            // 胜出者优先：同名的影子副本读得到，但那不是生效的一份，所以默认不选它。
+            const picked = hits.find((hit) => !hit.shadowedBy && hit.enabled)
+                || hits.find((hit) => !hit.shadowedBy)
+                || hits[0];
+            const res = await deps.skillsOps['skill-detail']({ root: picked.rootKey, name: picked.entryName });
+            if (!res || res.ok === false)
+                throw new Error((res && res.error) || 'skill-detail failed');
+            const detail = res.data || res;
+            const marks = [];
+            if (picked.shadowedBy)
+                marks.push('shadowed by "' + picked.shadowedBy + '" — the copy actually in effect is a different one');
+            if (picked.preferred)
+                marks.push('preferred copy');
+            if (!picked.enabled)
+                marks.push('disabled');
+            const dup = hits.filter((hit) => !hit.shadowedBy).length > 1
+                ? hits.filter((hit) => !hit.shadowedBy).map((hit) => hit.rootKey).filter((k) => k !== picked.rootKey)
+                : [];
+            const header = 'Skill ' + wanted + ' · source ' + picked.rootKey + (marks.length ? ' (' + marks.join('; ') + ')' : '') + '\n' +
+                'Path: ' + (detail.path || picked.path || '(unknown)') + '\n' +
+                'Description: ' + String(detail.description || '(none)').replace(/\s+/g, ' ').trim() + '\n' +
+                (dup.length ? 'Other callable copies with the same name: ' + dup.join(', ') + ' (this one wins; read them only to compare)\n' : '') +
+                '--- SKILL.md body ---\n';
+            // 注入边界：正文读进来就永久留在这一轮的 transcript 里，压制型预设下目录也可能不在 ——
+            // 与 skill_manager_list 同一句说明，别让模型以为"读过就等于技能开着"。
+            const notice = await deps.reachNoticeForAgent(deps.presetRoster(), exec && exec.agent && exec.agent.ctx, deps.injectNoticeOptions());
+            return header + String(detail.body || '').trim() + notice;
+        },
+    }));
     register(defineTool({
         name: 'skill_manager_set_enabled',
-        description: 'Enable or disable one DSH skill (manager policy only; source files are never modified). Enabling a shadowed copy has no effect.',
+        description: 'Enable or disable one DSH skill (manager policy only; source files are never modified). Enabling a shadowed copy has no effect. Only when the user asks or approves.',
         parameters: {
             name: { type: 'string', required: true, description: 'Skill name (kebab-case).' },
             enabled: { type: 'boolean', required: true, description: 'true to enable, false to disable.' },

package/lib/tools/subagent.js

@@ -1,11 +1,12 @@
 // 子智能体域的 model 工具（2026-09-19 从 index.ts 的注册区抽出）：
-// subagent_manager_list / subagent_manager_run。
+// subagent_manager_list / subagent_manager_run / _set_enabled / _create / _update。
 //
 // exec.agent / exec.signal 由工具运行时提供（parent 与取消信号的官方通道）。
 //
 // 两个工具**各自** try/catch：一个注册失败不该把另一个也带走，而且失败必须说得出
 // 「是哪一个没注册上」——只打一行日志时，模型侧只会「查无此工具」、界面毫无痕迹。
 import { defineSubagentManagerListTool, defineSubagentManagerRunTool } from '../subagents/tools.js';
+import { text } from './deps.js';
 export function buildSubagentTools(deps) {
     const { defineTool, register } = deps;
     const recordFailure = (name, e) => {
@@ -16,7 +17,7 @@ export function buildSubagentTools(deps) {
         console.error('[dsh-plugin-tool-management] subagent tool registration failed:', name, deps.message(e));
     };
     try {
-        // 与其余 12 个工具同一条注册通道：defineTool 负责编译 parameters（object root + required），
+        // 与其余 19 个工具同一条注册通道：defineTool 负责编译 parameters（object root + required），
         // 裸 register 会把未编译的参数声明直接发给模型 API。
         register(defineTool(defineSubagentManagerListTool({
             list: () => deps.subagentService.list(),
@@ -37,4 +38,118 @@ export function buildSubagentTools(deps) {
     catch (e) {
         recordFailure('subagent_manager_run', e);
     }
+    // ── 管理侧的三个（启停 / 建 / 改）────────────────────────────────────────────
+    // 与上面两个不同，这三个**不依赖** provider：动的只是 hub 里的人设文件与启停名单，
+    // 宿主没挂 `dsh-subagent-*` 也照样该能用（恰恰那时更需要：能把人设建好、开关拨对，
+    // 等 provider 回来就可用）。所以各自单独 try/catch，不与 `_run` 绑在一起失败。
+    //
+    // 参数表刻意只给 name / description / body / output 四个：工具限制（tools / toolsDeny /
+    // toolsByPreset）与 provider/model 留给面板。理由不是"怕模型不会填"，而是填错的后果
+    // 不对称 —— 一个错误的 toolsDeny 会静默改变子代理能做什么，而模型看不到自己改对了没有。
+    const ops = () => deps.subagentService.ops;
+    try {
+        register(deps.defineTool({
+            name: 'subagent_manager_set_enabled',
+            description: 'Enable or disable one persona. Only enabled personas appear in the「可委派的子智能体」catalog and can be given work by subagent_manager_run. Reversible, and the file is untouched. Only when the user asks or approves.',
+            parameters: {
+                name: { type: 'string', required: true, description: 'Persona name.' },
+                enabled: { type: 'boolean', required: true, description: 'true = enable, false = disable; omission is refused.' },
+            },
+            output: { schema: { type: 'string' }, render: (_a, v) => text(String(v)) },
+            async execute(args) {
+                const blocked = await deps.lockedSceneGuard();
+                if (blocked)
+                    throw new Error(blocked);
+                const name = String((args && args.name) || '').trim();
+                const r = await ops()['subagent-toggle']({ name, enabled: args.enabled === true });
+                if (!r || r.ok === false)
+                    throw new Error((r && r.error) || '切换人设启停失败');
+                // 场景内改开关要同步进当前场景档案（与 HTTP 层 syncsArchive 同一口径 —— 模型工具
+                // 直接调 service op，绕过了那一层包装，所以这里自己叫一声）。
+                const syncErr = await deps.syncSwitchToScene('subagent-toggle', { name, enabled: args.enabled === true });
+                return 'OK: persona ' + name + ' ' + (args.enabled === true ? 'enabled' : 'disabled') +
+                    (syncErr ? '\nWARN: 当前场景档案未同步（' + syncErr + '）' : '');
+            },
+        }));
+    }
+    catch (e) {
+        recordFailure('subagent_manager_set_enabled', e);
+    }
+    try {
+        register(deps.defineTool({
+            name: 'subagent_manager_create',
+            description: 'Create a persona at ~/.dsh/tool-management/subagents/<name>.md. Only on the user\'s explicit request. Write `body` as who this is and how it judges its own work — not the steps or paths, those belong to the task; put hard output requirements in `output` (one per line), not buried in prose. New personas start disabled: enable with subagent_manager_set_enabled before delegating.',
+            parameters: {
+                name: { type: 'string', required: true, description: 'Persona name (= file name); ≤64 chars, no path separators or < > : " | ? *, must not start with a dot.' },
+                description: { type: 'string', required: true, description: 'One-line routing description: what it is for and when to pick it. This is what shows up in the delegation catalog.' },
+                body: { type: 'string', required: true, description: 'Markdown role definition.' },
+                output: { type: 'string', description: 'Output contract, one requirement per line (rendered to the persona as its own 「输出要求」 section). Omit for no hard requirements.' },
+            },
+            output: { schema: { type: 'string' }, render: (_a, v) => text(String(v)) },
+            async execute(args) {
+                const blocked = await deps.lockedSceneGuard();
+                if (blocked)
+                    throw new Error(blocked);
+                const r = await ops()['subagent-create'](args);
+                if (!r || r.ok === false)
+                    throw new Error((r && r.error) || '创建人设失败');
+                return 'OK: persona ' + String(r.name || args.name) + ' created（默认未启用,要委派它先 subagent_manager_set_enabled）';
+            },
+        }));
+    }
+    catch (e) {
+        recordFailure('subagent_manager_create', e);
+    }
+    try {
+        register(deps.defineTool({
+            name: 'subagent_manager_update',
+            // 为什么不是直通 `subagent-update`：那个 op 走 serializePersona **整份重写**文件,
+            // 缺席的字段一律按空处理。界面每次都带全量表单所以没事,模型只改一句 description
+            // 却直通过去,就会把人设正文与工具限制一起冲掉。这里先读现状再合并 —— 合并发生在
+            // 工具这一侧,op 的语义不动。
+            description: 'Update a persona: body, description, output contract, or name (renaming re-points scene-profile bindings). Omit a field to keep it — this merges, so you can change one part without restating the role. Only on the user\'s instruction.',
+            parameters: {
+                name: { type: 'string', required: true, description: 'Current persona name.' },
+                nextName: { type: 'string', description: 'New name (rename). Omit to keep it. Refused if a persona already has that name — nothing is overwritten.' },
+                description: { type: 'string', description: 'New one-line routing description. Omit to keep it.' },
+                body: { type: 'string', description: 'New Markdown role definition. Omit to keep it.' },
+                output: { type: 'string', description: 'New output contract, one requirement per line. Empty string clears it. Omit to keep it.' },
+            },
+            output: { schema: { type: 'string' }, render: (_a, v) => text(String(v)) },
+            async execute(args) {
+                const blocked = await deps.lockedSceneGuard();
+                if (blocked)
+                    throw new Error(blocked);
+                const name = String((args && args.name) || '').trim();
+                const current = await ops()['subagent-get']({ name });
+                if (!current || current.ok === false)
+                    throw new Error((current && current.error) || '人设不存在: ' + name);
+                const keep = current.persona || {};
+                const touched = ['nextName', 'description', 'body', 'output'].filter((k) => args && args[k] !== undefined);
+                if (!touched.length)
+                    throw new Error('没有要改的东西：nextName / description / body / output 至少给一个');
+                const merged = {
+                    name,
+                    nextName: args.nextName,
+                    description: args.description !== undefined ? String(args.description) : String(keep.description ?? ''),
+                    body: args.body !== undefined ? String(args.body) : String(keep.body ?? ''),
+                    output: args.output !== undefined ? String(args.output) : (Array.isArray(keep.output) ? keep.output.join('\n') : String(keep.output ?? '')),
+                    provider: keep.provider ?? '',
+                    model: keep.model ?? '',
+                    tools: keep.tools ?? [],
+                    toolsDeny: keep.toolsDeny ?? [],
+                    toolsByPreset: keep.toolsByPreset ?? {},
+                    catalogDepth: keep.catalogDepth,
+                };
+                const r = await ops()['subagent-update'](merged);
+                if (!r || r.ok === false)
+                    throw new Error((r && r.error) || '更新人设失败');
+                return 'OK: persona ' + String(r.name || name) + ' updated（改了 ' + touched.join('、') + '）' +
+                    (r.renamedFrom ? ' — 原名「' + r.renamedFrom + '」,场景档案里的绑定已一起改名' : '');
+            },
+        }));
+    }
+    catch (e) {
+        recordFailure('subagent_manager_update', e);
+    }
 }