dsh-plugin-tool-management 0.9.1 → 0.10.0

package/lib/rules/service.js

@@ -27,9 +27,10 @@
 //
 // 错误约定：业务校验失败返回 { ok:false, error: 中文, code, params? }（与 skills core 一致）；
 // ops 成功返回扁平 { ok:true, ... }，不套 { ok:true, data }。
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { copyFile, cp, lstat, mkdir, readFile, readdir, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { parseSkillDoc, renameWithRetry, resolveDshHome, unquote } from '../skills/core.js';
 import { expandUploads, planMemoryImport } from '../imports/upload.js';
@@ -957,7 +958,7 @@ function probeSceneFilesSync(rulesRoot, index) {
     ].join('\u0002');
     return { refs, scenes, truncated, signature };
 }
-/** 指纹里必须包含一切影响渲染的索引字段（active / enabled / order / groups.order / scenes.order）。 */
+/** 指纹里必须包含一切影响渲染的索引字段（active / enabled / order / groups.order / scenes.order / label / description）。 */
 function signatureOfIndex(index) {
     const active = normalizeActive(index.active);
     const rules = Object.keys(index.rules).sort().map((id) => {
@@ -966,9 +967,11 @@ function signatureOfIndex(index) {
     });
     const groups = Object.keys(index.groups).sort().map((g) => `${g}\u0000${index.groups[g]?.order ?? DEFAULT_GROUP_ORDER}`);
     // 场景顺序决定段内场景的先后 → 必须进指纹，否则改顺序后段文本不会重算。
+    // label 与 description 同理（sceneHeader 的「场景说明」一行直接渲染 description）——
+    // 手改索引文件（带外变更）时只有指纹变化才会触发重算。
     const scenes = Object.keys(index.scenes || {}).sort().map((s) => {
         const e = index.scenes[s];
-        return `${s}\u0000${e.order ?? (s === GLOBAL_SCENE ? 0 : DEFAULT_GROUP_ORDER)}\u0000${e.label ?? ''}`;
+        return `${s}\u0000${e.order ?? (s === GLOBAL_SCENE ? 0 : DEFAULT_GROUP_ORDER)}\u0000${e.label ?? ''}\u0000${e.description ?? ''}`;
     });
     return `A:${active === null ? '*' : active.join(',')}|R:${rules.join(';')}|G:${groups.join(';')}|S:${scenes.join(';')}`;
 }
@@ -1204,8 +1207,8 @@ function sceneHeader(scene, index) {
     return `${head}\n\n**场景说明：${description}**\n\n`;
 }
 /**
- * 段首的引导语：让模型知道下面是**用户提供的参考信息**，而不是对话历史或临时说明
- * —— 相关就用、无关可忽略。
+ * 段首的引导语：让模型知道下面是**用户为本机写的参考信息**，并且**以它为准**
+ * —— 涉及本机的事一律照它办，确实无关时才放下。
  *
  * 写法（2026-09-16 用户裁定，基于真实注入结果的三次修正）：
  *   - **单行、加粗**，不再用括号分两行 —— 括号跨行在真实提示词里读起来像被截断，
@@ -1220,10 +1223,37 @@ function sceneHeader(scene, index) {
  *
  * 用词：不用「常驻」「注入」这类内部行话（模型没有先验）；用户裁定用「信息」而不是
  * 「记忆」——「记忆」在系统提示词里指代不明，而这段的实质就是用户写的参考信息。
+ *
+ * 2026-09-17 重写（用户：「当前模式会不重视这些提示词」）。上一版的三个毛病都在**授权**
+ * 上，而不在措辞好不好看上：
+ *   1. 「与当前任务相关时直接采用」——**没有给"相关"的判据**。最省力的解读永远是"无关"，
+ *      因为判成无关不需要任何工作；
+ *   2. 通篇没有优先级规则。与本机实际情况冲突时，模型会默默按自己的默认假设走，
+ *      而用户完全不知道发生了什么；
+ *   3. 「无关时忽略」——「忽略」是这句话里**最后一个动词**，也是记得最牢的那个。它把
+ *      一个免打扰出口写成了对内容的态度许可。
+ * 现在：给出**判据**（凡涉及本机路径 / 配置 / 工具 / 习惯）、给出**裁决规则**、把出口降级为
+ * 「不必提及」（关于**要不要声明**，不是关于**要不要采用**）。出口保留是必要的 —— 去掉它
+ * 会让模型对无关条目强行攀附，那是另一种失真。
+ *
+ * 2026-09-17 第二版：**按条目类型分级授权**（用户采纳的四条里的第 1、4 条）。Claude Code
+ * 把两类内容分进两个系统、用**相反**的授权：用户指令（`claudemd.ts:89`）是
+ * "These instructions OVERRIDE any default behavior and you MUST follow them exactly as
+ * written"，而记忆（`memdir/memoryTypes.ts:202`）是
+ * "If a recalled memory conflicts with current information, trust what you observe now"
+ * —— 书里（ch11:25）说记忆是 "working notes, not gospel"。上一版把两类塞进一句授权，
+ * 对**场景说明**（用户写的约定）是对的，对**记忆条目**（可能是几个月前记下的事实）是错的。
+ * 好在这两类在渲染时就分处不同位置：场景说明在 `sceneHeader` 的 `**场景说明：…**` 里，
+ * 记忆条目在 `memoryBlock` 里 —— 所以一句话就能分级，不必改数据结构。
+ *
+ * 冲突阶梯（第 4 条）来自 Codex `base_instructions/default.md:22-27` 与 Claude Code 的
+ * `caller override > agent definition > parent model > default`：把"谁高于谁"写明，
+ * 模型才不会在「用户当场说的 ≠ 本机记录」时悬空。写明它还有一个反直觉的好处 ——
+ * 它让授权更可信：这说明本条不是要让记忆压过用户，只是要压过模型的默认假设。
  */
-const SCENE_MEMORY_NOTE = '**用户提供的参考信息：与当前任务相关时直接采用，无关时忽略。以下就是全部信息。**';
+const SCENE_MEMORY_NOTE = '**用户为本机写的参考信息：「场景说明」是用户的约定，一律照办，覆盖你的默认做法；其余条目是记录，可能已过期 —— 与当前实际情况冲突时以你看到的为准，与用户当场说的冲突时以用户为准。无关时不必提及。以下就是全部信息。**';
 /** 有未注入条目时的版本：去掉完整性声明（见上）。 */
-const SCENE_MEMORY_NOTE_PARTIAL = '**用户提供的参考信息：与当前任务相关时直接采用，无关时忽略。**';
+const SCENE_MEMORY_NOTE_PARTIAL = '**用户为本机写的参考信息：「场景说明」是用户的约定，一律照办，覆盖你的默认做法；其余条目是记录，可能已过期 —— 与当前实际情况冲突时以你看到的为准，与用户当场说的冲突时以用户为准。无关时不必提及。**';
 /**
  * 段首固定块。以 `\n` 结尾，与场景块 join 后自然空一行。
  * 预算按**较长**的那版算（见 renderSceneMemory），保守一点只会浪费几个字节。
@@ -1599,12 +1629,20 @@ export function createRulesService(ctx, deps) {
         }
     }
     // ── 规则文件序列化 ──────────────────────────────────────────────────────
-    /** 值含换行用 `|` 块（保留换行）；否则 `key: value` 原样（parseSkillDoc 按行贪婪解析）。 */
+    /**
+     * 值含换行用 `|` 块（保留换行）；否则 `key: value` 原样（parseSkillDoc 按行贪婪解析）。
+     * 例外：多行值里有去空白后恰为 `---` 的行时改用 JSON 引号标量 —— 块标量把内容行缩进
+     * 两格也躲不开 parseSkillDoc 的 frontmatter 结束扫描（`trim() === '---'`），描述会被
+     * 截断、残片混进正文；引号形式是单物理行，扫描无从误判，decodeYamlScalar 无损还原
+     * （skills 写侧的引号标量正是靠这一点免疫同一断裂）。
+     */
     function yamlField(key, value) {
         if (typeof value === 'boolean')
             return [`${key}: ${value}`];
         const s = String(value);
         if (s.includes('\n')) {
+            if (s.split('\n').some((line) => line.trim() === '---'))
+                return [`${key}: ${JSON.stringify(s)}`];
             return [`${key}: |`, ...s.split('\n').map((line) => `  ${line}`)];
         }
         return [`${key}: ${s}`];
@@ -1890,7 +1928,7 @@ export function createRulesService(ctx, deps) {
         const indexForScene = await readIndex(stateDir);
         // 保留场景 global 恒存在（不用先建）；其余场景必须已存在——见上方注释。
         if (targetGroup !== GLOBAL_SCENE && !indexForScene.scenes?.[targetGroup] && !(await pathExists(join(rulesRoot, targetGroup)))) {
-            return fail('error.rules.sceneNotFound', `场景不存在：${targetGroup}（请先在「场景」页创建该场景）`);
+            return fail('error.rules.sceneNotFound', `场景不存在：${targetGroup}（请先在「场景」页创建该场景）`, { group: targetGroup });
         }
         if (!isValidGroupSegment(name))
             return fail('error.rules.invalidName', `记忆名非法：${name}（非空、≤${MAX_GROUP_SEGMENT_LENGTH} 字符、不含 / \\ < > : " | ? *、不以 . 开头）`);
@@ -2118,7 +2156,8 @@ export function createRulesService(ctx, deps) {
             else
                 description = deriveDescription(newBody) || undefined;
         }
-        // 形态转换 / 改名：先建新形态文件，再清理旧形态（确保任意失败点不产生半份规则）。
+        // 形态转换 / 改名：先建新形态文件，再把旧形态复制进回收站、最后删原件
+        // （确保任意失败点不产生半份规则；旧形态随时可恢复，README「删除都进回收站」无例外）。
         // description 写回约定：显式传 → string/null（删除）；未传 → undefined（保留原字段）。
         const serialize = () => {
             let descArg;
@@ -2131,16 +2170,19 @@ export function createRulesService(ctx, deps) {
         if (located.kind === 'bundle' && newForm === 'flat') {
             await mkdir(join(rulesRoot, parts.group), { recursive: true });
             await writeFileAtomically(join(rulesRoot, parts.group, newName + '.md'), serialize());
+            await copyIntoMemoriesTrash(located, parts.group, parts.name);
             await rm(located.entryPath, { recursive: true, force: true });
         }
         else if (located.kind === 'flat' && newForm === 'bundle') {
             await mkdir(join(rulesRoot, parts.group, newName), { recursive: true });
             await writeFileAtomically(join(rulesRoot, parts.group, newName, bundleDocName(newName)), serialize());
+            await copyIntoMemoriesTrash(located, parts.group, parts.name);
             await rm(join(rulesRoot, parts.group, parts.name + '.md'), { force: true });
         }
         else if (located.kind === 'flat' && newName !== parts.name) {
             // flat 改名 = 文件改名
             await writeFileAtomically(join(rulesRoot, parts.group, newName + '.md'), serialize());
+            await copyIntoMemoriesTrash(located, parts.group, parts.name);
             await rm(join(rulesRoot, parts.group, parts.name + '.md'), { force: true });
         }
         else {
@@ -2161,28 +2203,40 @@ export function createRulesService(ctx, deps) {
         invalidateSnapshot();
         return { ok: true, rule: await buildProjected(newId) };
     }
-    async function rulesRemove(args) {
-        const id = String((args && args.id) || '');
-        const parts = parseId(id);
-        if (!parts)
-            return fail('error.rules.notFound', `规则不存在：${id}`);
-        const located = await locateRule(parts.group, parts.name);
-        if (!located)
-            return fail('error.rules.notFound', `规则不存在：${id}`);
+    /**
+     * 把条目原件复制进 memories 回收站并写 manifest，返回 trashId。只复制、不删除：
+     * 原件的 rm 由调用方在复制成功后执行 —— 先有副本才允许删，rm 永远不会销毁唯一数据。
+     * manifest 先于原件删除落盘：中途崩溃最坏留下「原件还在 + 一份完整回收站副本」，
+     * 不会出现「有文件没清单」的损坏条目。
+     */
+    async function copyIntoMemoriesTrash(located, group, name) {
         const trashId = Date.now().toString(36) + '-' + randomUUID().slice(0, 8);
         const trashDir = join(stateDir, MEMORIES_TRASH_DIR, trashId);
-        const manifest = { group: parts.group, name: parts.name, form: located.kind, deletedAt: new Date().toISOString() };
+        const manifest = { group, name, form: located.kind, deletedAt: new Date().toISOString() };
         await mkdir(trashDir, { recursive: true });
         if (located.kind === 'bundle') {
             const { cp } = await import('node:fs/promises');
             await cp(located.entryPath, join(trashDir, 'bundle'), { recursive: true });
-            await rm(located.entryPath, { recursive: true, force: true });
         }
         else {
             await copyFile(located.docPath, join(trashDir, 'rule.md'));
-            await rm(located.docPath, { force: true });
         }
         await writeFileAtomically(join(trashDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
+        return trashId;
+    }
+    async function rulesRemove(args) {
+        const id = String((args && args.id) || '');
+        const parts = parseId(id);
+        if (!parts)
+            return fail('error.rules.notFound', `规则不存在：${id}`);
+        const located = await locateRule(parts.group, parts.name);
+        if (!located)
+            return fail('error.rules.notFound', `规则不存在：${id}`);
+        const trashId = await copyIntoMemoriesTrash(located, parts.group, parts.name);
+        if (located.kind === 'bundle')
+            await rm(located.entryPath, { recursive: true, force: true });
+        else
+            await rm(located.docPath, { force: true });
         const index = await readIndex(stateDir);
         delete index.rules[id];
         await writeIndex(stateDir, index);
@@ -2427,7 +2481,7 @@ export function createRulesService(ctx, deps) {
             return fail('error.rules.invalidArgs', '缺少参数：需要 scenes:[...]（启用集合，至多一个场景）');
         }
         if (hasAll) {
-            return fail('error.rules.singleSceneOnly', '除「全局」外同时只能启用一个场景：不支持"全部启用"，请改用 scenes:[<场景名>] 或 scenes:[]（全部关闭）');
+            return fail('error.rules.singleSceneOnly', '除「全局」外同时只能启用一个场景：不支持"全部启用"，请改用 scenes:[<场景名>] 或 scenes:[]（全部关闭）', { detail: '：不支持"全部启用"，请改用 scenes:[<场景名>] 或 scenes:[]（全部关闭）' });
         }
         const index = await readIndex(stateDir);
         const raw = Array.isArray(args && args.scenes) ? args.scenes : [];
@@ -2447,7 +2501,7 @@ export function createRulesService(ctx, deps) {
             names.push(name);
         }
         if (names.length > 1) {
-            return fail('error.rules.singleSceneOnly', `除「全局」外同时只能启用一个场景（收到 ${names.length} 个：${names.join('、')}）`);
+            return fail('error.rules.singleSceneOnly', `除「全局」外同时只能启用一个场景（收到 ${names.length} 个：${names.join('、')}）`, { detail: `（收到 ${names.length} 个：${names.join('、')}）` });
         }
         index.active = names;
         await writeIndex(stateDir, index);
@@ -2578,7 +2632,7 @@ export function createRulesService(ctx, deps) {
                 return fail('error.rules.invalidGroup', `新场景名非法：${nextRaw}（非空、≤${MAX_GROUP_SEGMENT_LENGTH} 字符、不含路径分隔符与 < > : " | ? *、不以 . 开头）`);
             }
             if (name === GLOBAL_SCENE)
-                return fail('error.rules.reservedScene', '「全局」是保留场景，不可改名');
+                return fail('error.rules.reservedScene', '「全局」是保留场景，不可改名', { name: GLOBAL_SCENE, action: 'rename', reason: '' });
             if (name === SHARED_GROUP || nextRaw === SHARED_GROUP)
                 return fail('error.rules.invalidGroup', '_shared 是保留场景名，不可改名');
             if ((index.scenes && index.scenes[nextRaw]) || (await pathExists(join(rulesRoot, nextRaw)))) {
@@ -2653,7 +2707,7 @@ export function createRulesService(ctx, deps) {
         if (!isValidGroupPath(name))
             return fail('error.rules.invalidGroup', `场景名非法：${name || '(空)'}`);
         if (name === GLOBAL_SCENE || name === SHARED_GROUP)
-            return fail('error.rules.reservedScene', '「全局 / _shared」是保留场景，不可锁定');
+            return fail('error.rules.reservedScene', '「全局 / _shared」是保留场景，不可锁定', { name: '全局 / _shared', action: 'lock', reason: '' });
         if (typeof (args && args.locked) !== 'boolean') {
             return fail('error.rules.invalidArgs', '缺少参数：locked 必须是布尔值（只按传入值写入，不做"翻转"推断）');
         }
@@ -2682,7 +2736,7 @@ export function createRulesService(ctx, deps) {
         if (name === SHARED_GROUP)
             return fail('error.rules.invalidGroup', `_shared 是保留场景名，不可删除`);
         if (name === GLOBAL_SCENE)
-            return fail('error.rules.reservedScene', `「全局」是保留场景，不可删除（它的记忆对任何对话都生效）`);
+            return fail('error.rules.reservedScene', `「全局」是保留场景，不可删除（它的记忆对任何对话都生效）`, { name: GLOBAL_SCENE, action: 'delete', reason: '（它的记忆对任何对话都生效）' });
         const index = await readIndex(stateDir);
         // 场景不存在（既无记录也无目录）→ 明确报错，而不是假装删成功。
         if (!index.scenes?.[name] && !(await pathExists(join(rulesRoot, name)))) {
@@ -2895,24 +2949,76 @@ export function createRulesService(ctx, deps) {
     //     （注入侧会跳过整个域），没挂时（极简）才需要注入兜底；判定在注入器的 `selectInjections` 里。
     const memoryText = () => sceneMemory().text;
     /**
-     * `~/.dsh/AGENTS.md` 正文。上限与官方那一行的 `maxBytes` 同量级（64 KiB）：超大文件按字节
+     * `~/.dsh/AGENTS.md` 正文的上限，与官方那一行的 `maxBytes` 同量级（64 KiB）：超大文件按字节
      * 截断并留一行标记，免得一份手写的巨型基线把上下文撑爆。
      */
     const AGENTS_MD_MAX_BYTES = 65536;
-    const agentsMdText = () => {
-        const text = readGlobalAgentsMdSync();
-        if (text.trim() === '')
-            return '';
-        if (Buffer.byteLength(text, 'utf8') <= AGENTS_MD_MAX_BYTES)
-            return text;
-        const cut = Buffer.from(text, 'utf8').subarray(0, AGENTS_MD_MAX_BYTES).toString('utf8');
-        return cut + `\n\n（…文件超过 ${Math.floor(AGENTS_MD_MAX_BYTES / 1024)} KiB，已截断。）`;
+    /**
+     * DSH home 的**展示形态**，规则与官方 `dsh-home-paths` 的 `dshHomeDisplay()` 一致
+     * （`dsh-home-paths/lib/index.js:93`）：默认位置显示 `~/.dsh`，被 `DSH_HOME` 指到别处时
+     * 才显示 `$DSH_HOME`。只在给**界面**看的字符串里用 —— 读盘一律用真实路径。
+     */
+    const dshHomeDisplay = () => {
+        const home = resolveDshHome();
+        return resolve(home) === resolve(join(homedir(), '.dsh')) ? '~/.dsh' : '$DSH_HOME';
+    };
+    /**
+     * 当前生效的提示词：**来源文件 + 正文**，一次解析、两处出口共用（模型侧 `promptText`、
+     * 界面清单 `promptFiles`）。`null` = 现在没有提示词。
+     *
+     * 为什么合并成一处：两条出口必须给出**同一个**结论（文件是哪个、正文取哪份），分开写两份
+     * 同样的分支判断迟早分叉 —— 分叉的后果就是界面标错文件、或模型看到与文件不符的正文。
+     * 合并前那里已经有一处小分叉：场景预设在场但正文为空时，文本退回 AGENTS.md、清单却仍报
+     * 预设路径。现在两边同源，这类角落不可能再各说各话。
+     *
+     * `digest` 照抄官方 `instructionContentSha1`（`dsh-agent-instructions/lib/index.js:90`，
+     * sha1 hex）：算的是**文件内容**（AGENTS.md 取截断前的原文），是"文件这一版"的身份，
+     * 不是"这次注入了什么"；界面只拿它当悬停提示，不参与任何判定。
+     *
+     * `text` 是**模型侧**正文，开头一行 `来源：<展示路径>` —— 照抄官方 agent-instructions 的
+     * 写法（`Instructions from: <path>`，`render.js` 的 `sectionText`）。模型据此知道这些规则
+     * 写在哪个文件里：用户说"把这条记下来"时它知道该改哪份文件，而不是只能凭印象回答。
+     */
+    const resolvePrompt = () => {
+        // 场景提示词与 AGENTS.md 正文在用户眼里就是同一件事（"全局提示词"）：场景期间前者取代后者，
+        // 与官方语义一致（进场景改写文件、退出恢复）。所以一个域、一份文本，取到非空的场景提示词就用它。
+        const scene = resolveScenePreset();
+        if (scene && scene.text.trim() !== '') {
+            const path = `${dshHomeDisplay()}/${HUB_DIR}/${PRESETS_DIR}/${scene.presetId}/AGENTS.md`;
+            return {
+                path,
+                digest: createHash('sha1').update(scene.text).digest('hex'),
+                text: `来源：${path}\n\n${scene.text}`,
+            };
+        }
+        const raw = readGlobalAgentsMdSync();
+        if (raw.trim() === '')
+            return null;
+        const path = `${dshHomeDisplay()}/AGENTS.md`;
+        const body = Buffer.byteLength(raw, 'utf8') <= AGENTS_MD_MAX_BYTES
+            ? raw
+            : Buffer.from(raw, 'utf8').subarray(0, AGENTS_MD_MAX_BYTES).toString('utf8') +
+                `\n\n（…文件超过 ${Math.floor(AGENTS_MD_MAX_BYTES / 1024)} KiB，已截断。）`;
+        return { path, digest: createHash('sha1').update(raw).digest('hex'), text: `来源：${path}\n\n${body}` };
     };
-    // 场景提示词与 AGENTS.md 正文在用户眼里就是同一件事（"全局提示词"）：场景期间前者取代后者，
-    // 与官方语义一致（进场景改写文件、退出恢复）。所以一个域、一份文本，取到非空的场景提示词就用它。
-    const promptText = () => {
-        const scene = resolveScenePreset()?.text ?? '';
-        return scene.trim() !== '' ? scene : agentsMdText();
+    /**
+     * 模型侧的提示词正文（`''` = 没有可注入的内容）。
+     *
+     * **不判"与文件重复"** —— 预设挂了官方 agent-instructions 时那份正文已经由文件送达
+     * （注入侧会跳过整个域），没挂时（极简）才需要注入兜底；判定在注入器的 `selectInjections` 里。
+     */
+    const promptText = () => resolvePrompt()?.text ?? '';
+    /**
+     * `promptText()` 的**来源文件**（同步）：注入通道把它当作 instructions 形态的
+     * `changes` 交给界面（文件清单 + 已载入/已更新），见 context-inject.ts 的 `files`。
+     * 与文本同源（都走 `resolvePrompt`），所以两边不会分叉；`[]` = 无正文。
+     *
+     * 路径用**展示形态**（见 `dshHomeDisplay`）：界面里官方 agent-instructions 那条行写的是
+     * `~/.dsh/AGENTS.md`，我们写绝对路径的话，同一个界面上会出现两种风格。
+     */
+    const promptFiles = () => {
+        const resolved = resolvePrompt();
+        return resolved === null ? [] : [{ path: resolved.path, digest: resolved.digest }];
     };
     /** 写操作：串行队列内执行，成功后触发 refresh（失效缓存，下一请求即生效）。 */
     const runWrite = (task) => enqueueMutation(async () => {
@@ -2963,6 +3069,7 @@ export function createRulesService(ctx, deps) {
         writeOps,
         memoryText,
         promptText,
+        promptFiles,
         refresh,
         patchIndex,
         readArchiveSlice,

package/lib/skills/catalog.js

@@ -11,8 +11,9 @@
 //
 // 与官方目录的两处有意差别：
 //   - 只列**当前启用且可被模型调用**的（官方只过滤可调用性，不管用户在插件页关掉了谁）。
-//   - 结尾多一行：本预设没有官方 `skill` 加载工具（目录与工具是一起挂的），需要正文时得先
-//     `skill_manager_list` 取源文件路径再读那个文件 —— 不写这句，模型会以为有 `skill` 工具可调。
+//   - 「本预设没有官方 `skill` 加载工具，要正文先用 `skill_manager_list` 取源文件路径」那句
+//     2026-09-18 起挪进注入框架的 `how` 行（context-inject.ts 的 DOMAIN_FRAME.skills）——
+//     本段只排版清单，标题与"怎么用"一处一个出处。
 //
 // 同步性：`text()` 必须同步返回（注入通道每个 step 同步取文本），而技能清单是异步读盘 →
 // 与子智能体目录同构的 stale-while-revalidate：`text()` 返回缓存值并在超龄时后台重算，
@@ -72,13 +73,9 @@ export function renderSkillCatalog(data, maxEntries = SKILL_CATALOG_MAX_ENTRIES,
     const sorted = [...byName.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
     const shown = sorted.slice(0, Math.max(0, maxEntries));
     const lines = shown.map((row) => (row.description ? '- `' + row.name + '`: ' + row.description : '- `' + row.name + '`'));
-    const out = [
-        '## 技能',
-        '',
-        '**本预设没有官方 `skill` 加载工具；要技能正文时用 `skill_manager_list` 取源文件路径再读。**',
-        '',
-        ...lines,
-    ];
+    // 只有清单：标题、工具名与"只给摘要、读完再用"的纪律由注入通道的框架承担
+    // （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\` 查。）`);

package/lib/skills/core.js

@@ -564,13 +564,14 @@ function notDeletableError(definition) {
  */
 function reservedSourceError(root) {
     const key = root && root.key ? root.key : "";
+    const origin = key === "dsh"
+        ? "DSH 技能目录是默认来源，必须读取"
+        : "导入技能目录是默认来源、插件新建/导入的落点，必须读取";
     return {
         ok: false,
         code: "error.source.reserved",
-        params: { root: key },
-        error: key === "dsh"
-            ? "DSH 技能目录是默认来源，必须读取：不能停用或移除（里面的技能可以删除）"
-            : "导入技能目录是默认来源、插件新建/导入的落点，必须读取：不能停用或移除（里面的技能可以删除）",
+        params: { root: key, origin },
+        error: `${origin}：不能停用或移除（里面的技能可以删除）`,
     };
 }
 function rootDefinition(root) {

package/lib/subagents/catalog.js

@@ -1,3 +1,5 @@
+import { catalogInjectedAt } from './service.js';
+import { subagentDepthOf } from '../context-inject.js';
 import { filterBySceneBinding } from './tools.js';
 /**
  * 描述截断长度 —— 照抄官方技能目录的默认值
@@ -25,6 +27,10 @@ export function catalogDescription(value, maxLength) {
 /**
  * 渲染人设目录段（纯函数，便于单独推理）。
  *
+ * ⚠️ 传进来的 `allowed` 必须**已经按当前会话的目录注入深度过滤过**（调用方
+ * `createSubagentCatalog.text` 负责，用 `catalogInjectedAt`）。这里刻意不再过滤一遍：
+ * 判据只该有一个来源，本函数只管排版。
+ *
  * 返回 `''` 表示不注入 —— `renderPrompt` 会删除空段，所以不用人设的用户零 token 成本。
  * 名字按字典序排序：即使底层目录枚举顺序变化，段文本也保持逐字节稳定（前缀缓存契约）。
  *
@@ -32,8 +38,10 @@ export function catalogDescription(value, maxLength) {
  * 「该人设的完整提示词会成为子代理的系统提示词」「子代理在独立上下文中执行」都是宿主内部
  * 机制，模型无法据此行动；而委派的调用语义与成本（自包含任务、只回最终结果、会开新会话）
  * 已经写在 `subagent_manager_run` 的描述里 —— 常驻层再重复一遍等于同一件事付两次 token。
- * 第二版（用户指出"太冗余"）：引导语压成**半行** —— 只留「怎么用」，"下面是名字与摘要"这类
- * 自明的话删掉；域是什么由消息引导语与轨迹行名交代，细节由 `subagent_manager_list` 承担。
+ *
+ * 第三版（2026-09-17 用户指出"还是那句套话"）：**职责彻底切开** —— 本函数只排版清单
+ * （`- **名字** — 描述`），"这是什么 + 该拿它做什么"整句交给注入通道的引导语。于是这里
+ * 既没有标题也没有"可委派给下列子智能体"那句：一处内容只有一个出处。
  */
 export function renderSubagentCatalog(allowed, maxEntries = DEFAULT_CATALOG_MAX_ENTRIES, maxDescription = DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH) {
     if (!allowed.length)
@@ -42,13 +50,11 @@ export function renderSubagentCatalog(allowed, maxEntries = DEFAULT_CATALOG_MAX_
     const shown = sorted.slice(0, Math.max(0, maxEntries));
     const lines = shown.map((p) => '- **' + p.name + '** — ' + (catalogDescription(p.description, maxDescription) || NO_DESCRIPTION));
     const hidden = sorted.length - shown.length;
-    const out = [
-        '## 子智能体',
-        '',
-        '**可委派给下列子智能体（调 `subagent_manager_run`）。**',
-        '',
-        ...lines,
-    ];
+    // 只给清单。"这是什么"与"该拿它做什么"由注入通道的框架交代 —— 2026-09-18 起是
+    // context-inject.ts 的 `DOMAIN_FRAME.subagents`（标题 + 加粗的动作句 + 工具名行）。
+    // 这里原本还有 `## 子智能体` 标题与一句加粗的「可委派给下列子智能体（调 `subagent_manager_run`）。」
+    // —— 加上引导语，同一件事说了三遍（用户 2026-09-17 指出）。正文从此只管排版。
+    const out = [...lines];
     // 查询工具**只在真被 40 条上限截掉时**才出现：常态下不提，省常驻字符，也免得模型为了
     // 「确认一遍」去调它（用户裁定：没列出来的就是当前不想要的）。与 MCP 状态段的
     // `（另有 N 台未列出。）` 同一句式，但这里多给一个出口——不给人设就真的找不回来了。
@@ -67,15 +73,18 @@ export function createSubagentCatalog(deps, opts = {}) {
     const maxDescription = opts.maxDescription ?? DEFAULT_CATALOG_DESCRIPTION_MAX_LENGTH;
     const ttlMs = opts.ttlMs ?? 1000;
     const now = opts.now ?? (() => Date.now());
-    let value = '';
+    let allowed = [];
     let loadedAt = Number.NEGATIVE_INFINITY;
     let inflight = null;
+    // 渲染结果按**深度**缓存：过滤只依赖深度这一个整数，而实际出现的深度就 0/1/2 三档，
+    // 于是"每个 step 同步渲染"退化成一次查表。重算成功时清空。
+    const rendered = new Map();
     const recompute = async () => {
         try {
-            const { allowed } = await filterBySceneBinding(await deps.list(), await deps.sceneLists());
-            value = renderSubagentCatalog(allowed, maxEntries, maxDescription);
+            allowed = (await filterBySceneBinding(await deps.list(), await deps.sceneLists())).allowed;
+            rendered.clear();
         }
-        catch { /* 保留上一次的值；首次失败则维持 '' */ }
+        catch { /* 保留上一次的值；首次失败则维持 [] */ }
         loadedAt = now();
     };
     const revalidate = () => {
@@ -85,11 +94,18 @@ export function createSubagentCatalog(deps, opts = {}) {
         return inflight;
     };
     return {
-        text: () => {
+        text: (agent) => {
             if (now() - loadedAt > ttlMs)
                 void revalidate();
-            return value;
+            const depth = subagentDepthOf(agent);
+            const cached = rendered.get(depth);
+            if (cached !== undefined)
+                return cached;
+            const out = renderSubagentCatalog(allowed.filter((p) => catalogInjectedAt(p, depth)), maxEntries, maxDescription);
+            rendered.set(depth, out);
+            return out;
         },
+        catalogVisibleAt: (depth) => allowed.some((p) => catalogInjectedAt(p, depth)),
         refresh: () => {
             loadedAt = Number.NEGATIVE_INFINITY;
             return revalidate();