dsh-plugin-tool-management 0.20.0 → 0.20.2

package/lib/tools/prompt.js

@@ -1,7 +1,14 @@
 // AGENTS.md 预设域的 model 工具（2026-09-19 从 index.ts 的注册区抽出）：
 // prompt_manager_list / prompt_manager_apply。
 //
-// 模型可查、可切，**不能造 / 不能删** —— 避免模型乱删用户预设。
+// 模型可查、可切；**不能造** —— 预设正文是用户自己写的一份长文（`AGENTS.md`），
+// 模型没有创建入口，要新建只能由用户在面板里写。
+//
+// 删除在 `tools/remove.ts` 的 `prompt_manager_remove`（2026-10-15 加）。此前这里写的是
+// 「不能造 / **不能删** —— 避免模型乱删用户预设」，那条理由针对的是**不可恢复**的删除：
+// 预设正文是用户手写的、删了就得重写。回收站把它的前提消掉了 —— 五条 `*_manager_remove`
+// 一律「进回收站、可恢复、需用户指令、过场景冻结守卫」，永久删除仍只留在面板。
+// 换句话说：**能删的是可恢复的那一步，不可逆的那一步照旧不给模型。**
 import { join } from 'node:path';
 import { normalizePresetDescription } from '../prompts/service.js';
 import { text } from './deps.js';
@@ -9,7 +16,10 @@ export function buildPromptTools(deps) {
     const { defineTool, register } = deps;
     register(defineTool({
         name: 'prompt_manager_list',
-        description: 'List AGENTS.md presets (id, description, 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.',
+        // 那句 `(that reminder is absent when the preset carries the official instructions line)`
+        // 删掉（2026-10-15 注入文本审查）：模型**观测不到**"official instructions line"这个条件，
+        // 拿它做不了任何决定 —— reminder 在不在，它抬头就能看见，不必由描述来预告。
+        description: 'List AGENTS.md presets (id, description, 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).' },
         },
@@ -20,7 +30,7 @@ export function buildPromptTools(deps) {
             if (!r || r.ok === false)
                 throw new Error((r && r.error) || '读取提示词预设失败');
             const all = r.presets || [];
-            // 默认只列「当前这份 ~/.dsh/AGENTS.md 是从哪个预设来的」（用户裁定 2026-09-16）。
+            // 默认只列「这份 AGENTS.md 来自哪个预设」（用户裁定 2026-09-16）。
             // 判定分两级：`active`（场景驱动时 = 场景绑的那份；否则 = 内容逐字节相同）优先，
             // 否则看服务层记下的「最近一次应用」—— 用户手改过全局文件时，第二级仍能给出答案，
             // 不必退化成全列（那会白烧上下文）。
@@ -53,15 +63,19 @@ export function buildPromptTools(deps) {
             // 同上：AGENTS.md 由官方 dsh-agent-instructions 行承载（极简没挂这一行），
             // 这一行不在时文件内容不会进上下文。
             const notice = await deps.reachNoticeForAgent(deps.presetRoster(), exec && exec.agent && exec.agent.ctx, deps.injectNoticeOptions());
-            return header + (summary.join('\n') || '(none)') + '\n(DSH re-reads ~/.dsh/AGENTS.md every turn, so applying takes effect on the next turn.)' + notice;
+            return header + (summary.join('\n') || '(none)') + notice;
         },
     }));
     register(defineTool({
         name: 'prompt_manager_apply',
         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. Pass apply=false to cancel instead — AGENTS.md goes back to what it was before the run of applies (the file is removed if there was none to begin with); a scene driving the baseline refuses that, rebind the scene instead. Only on the user\'s instruction.',
         parameters: {
-            id: { type: 'string', required: true, description: 'Preset id (lowercase letters, digits, hyphens). Ignored when apply=false.' },
-            apply: { type: 'boolean', description: 'Omit or true = apply the preset in `id`; false = cancel — undo the run of applies.' },
+            // `id` 从 required 摘掉（2026-10-15 smoke-test P1-5）：描述一直写着 "Ignored when
+            // apply=false"，schema 却把它标成必填 —— 模型照描述「取消不用给 id」操作，先被 schema
+            // 拒掉（missing required property "id"），只能编一个 dummy id 才过得去。条件必填由
+            // execute 里那句守卫表达，与 `skill_manager_switch` 的 enabled / prefer 同一形状。
+            id: { type: 'string', description: 'Preset id (lowercase letters, digits, hyphens). Required unless apply=false.' },
+            apply: { type: 'boolean', description: 'Omit or true = apply the preset in `id`; false = cancel — undo the run of applies (no `id` needed).' },
         },
         output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
         async execute(args) {
@@ -79,18 +93,21 @@ export function buildPromptTools(deps) {
                     ? 'OK: application cancelled — ~/.dsh/AGENTS.md did not exist before the run started, so the file was removed (effective next turn).'
                     : 'OK: application cancelled — ~/.dsh/AGENTS.md is back to what it was before the run started (effective next turn).';
             }
-            const r = await deps.applyPresetGuarded(args.id);
+            const id = String((args && args.id) || '').trim();
+            if (id === '')
+                throw new Error('缺少参数：id（只有 apply=false 取消时才不用给）');
+            const r = await deps.applyPresetGuarded(id);
             if (!r.ok)
                 throw new Error(r.error);
             // 场景驱动时写的是「场景绑定」，回执必须说清改的是哪个场景 —— 只说「已应用到
             // AGENTS.md」会让模型对用户谎报（用户不知道自己的场景绑定被换掉了）。
             if (r.viaScene) {
-                return 'OK: preset ' + args.id + ' is now the prompt binding of scene 「' + (r.scene || '') + '」 and the scene was re-synced (effective next turn; ~/.dsh/AGENTS.md now carries that scene\'s binding).';
+                return 'OK: preset ' + id + ' is now the prompt binding of scene 「' + (r.scene || '') + '」 and the scene was re-synced (effective next turn; ~/.dsh/AGENTS.md now carries that scene\'s binding).';
             }
             // 生效时机与宿主行为对齐（index.ts 提示词服务一节考证过）：dsh-agent-instructions
             // 每个 pre-step 都 stat 比对版本，写文件即下一轮重读 —— 不是"下个会话"。说错了
             // 模型会劝用户重开会话，而其实下一句话就已经在新基线下跑。
-            return 'OK: preset ' + args.id + ' applied to ~/.dsh/AGENTS.md — effective next turn' + (r.backedUp ? ' (previous backed up to __last-applied__)' : '');
+            return 'OK: preset ' + id + ' applied to ~/.dsh/AGENTS.md — effective next turn' + (r.backedUp ? ' (previous backed up to __last-applied__)' : '');
         },
     }));
 }

package/lib/tools/remove.js

@@ -0,0 +1,206 @@
+// 删除 / 回收站族的 model 工具（2026-10-15）：五个域各一条 `*_manager_remove`。
+//
+// 为什么单开一族：此前模型**只能停用、不能删除** —— "把这条过时的记忆删掉"这类要求手里
+// 没有出口，模型会去调 `*_switch(enabled:false)` 然后回一句"已停用"，用户以为删了。面板上
+// 每个域都有删除，模型侧一条都没有。
+//
+// 三条纪律：
+//   · **删除一律进回收站**（可恢复），与面板同一条路 —— 回执如实说"可恢复"。
+//   · **不做 purge**（永久删除）：低频且不可恢复，用户裁定"使用频率低的可以不要，
+//     太多功能反而冗余" —— 清空回收站留给面板。
+//   · `list` 是只读（不进场景冻结守卫，与 `trash-preview` 只读口径一致）；`trash` /
+//     `restore` 是写，过 `lockedSceneGuard()`。
+//
+// 参数名统一 `id`：`trash` 时是资源标识（记忆 `<场景>/<名>`、技能名、人设名、预设 id、
+// 场景名），`restore` 时是 `action=list` 给出的**回收站条目 id** —— 两种含义在描述里写清。
+import { locateSkillRoot, text } from './deps.js';
+/** 三个动词共用的描述骨架。 */
+function removeDescription(noun) {
+    return 'Delete one ' + noun + ' (moves it to the trash), restore one from the trash, or list the trash. '
+        + 'Nothing here is permanent — emptying the trash is a panel action. '
+        + 'Blocked while the active scene is locked. Only on the user\'s instruction.';
+}
+/** `action` 参数：三个动词 + 每个动词要哪个 `id`。 */
+const ACTION_DESC = 'trash = delete the item named in `id` (moves it to the trash); restore = put back the trash entry `id` (get its id from action=list); list = list the trash (no `id`).';
+/**
+ * 恢复 op 回传的**最终落盘名**。五个域把名字放在不同字段上：
+ *   · 记忆 / 技能 / 人设 / 场景 → `name`（退号恢复时它是新名字，不是回收站里的原名）
+ *   · 提示词预设               → `id`（预设的 id 就是它的名字）
+ * 记忆还会把投影对象放在 `rule.id` 上，作为第三顺位兜底。
+ *
+ * 还要解一层 `data`（2026-10-15 复核 P1-6 时漏掉的那半）：技能的 op 表外面包了
+ * `wrap`（`skills/service.ts:239` —— `{ ok: true, data: result }`），名字在 `r.data.name`，
+ * 不在 `r.name` 上。其余四个域的 op 是扁平返回。两边都要看，否则技能域的回执仍会退回 trashId。
+ */
+function restoredName(r) {
+    const pick = (o) => {
+        if (!o || typeof o !== 'object')
+            return '';
+        if (typeof o.name === 'string' && o.name !== '')
+            return o.name;
+        if (o.rule && typeof o.rule.id === 'string' && o.rule.id !== '')
+            return o.rule.id;
+        if (typeof o.id === 'string' && o.id !== '')
+            return o.id;
+        return '';
+    };
+    return pick(r) || pick(r && r.data);
+}
+/** 一条删除工具的 execute：三个动词的分派与回执。 */
+async function runRemove(deps, cfg, args) {
+    const action = String((args && args.action) || '');
+    if (action !== 'trash' && action !== 'restore' && action !== 'list') {
+        throw new Error('action 只能是 trash / restore / list（收到：' + (action || '(空)') + '）');
+    }
+    if (action === 'list') {
+        const entries = await cfg.list();
+        return entries.length
+            ? '回收站（' + entries.length + ' 条）：\n' + entries.map((e) => '- ' + e.id + ' · ' + e.name + (e.deletedAt ? ' · ' + e.deletedAt : '')).join('\n')
+            : '回收站是空的。';
+    }
+    // 进 / 出回收站都是写：过场景冻结守卫（与面板的删除按钮同一档）。
+    const blocked = await deps.lockedSceneGuard();
+    if (blocked)
+        throw new Error(blocked);
+    const id = String((args && args.id) || '').trim();
+    if (id === '')
+        throw new Error('缺少参数：id（action=' + action + ' 需要）');
+    const r = action === 'trash' ? await cfg.trash(args) : await cfg.restore(args);
+    if (!r || r.ok === false)
+        throw new Error((r && r.error) || (action === 'trash' ? '移入回收站失败' : '恢复失败'));
+    if (action === 'trash') {
+        return 'OK: ' + cfg.label + '「' + id + '」已移入回收站（可恢复；永久删除在面板的回收站里）';
+    }
+    // 恢复的回执要说**恢复成了什么**，而不是回收站条目 id（2026-10-15 smoke-test P1-6）：
+    // `id` 是 `action=list` 给的那一串（记忆 `mv…`、技能 `<时间戳>-<uuid>`），模型看到它
+    // 认不出恢复了哪一条；退号恢复时最终落盘的名字还与回收站里的原名不同，更要说准。
+    const name = restoredName(r) || id;
+    return 'OK: 已从回收站恢复 ' + cfg.label + '「' + name + '」' +
+        (name === id ? '' : '（回收站条目 ' + id + '）');
+}
+export function buildRemoveTools(deps) {
+    const { defineTool, register } = deps;
+    const mem = deps.memoryOps;
+    const sk = deps.skillOps;
+    const sub = deps.subagentOps;
+    const pr = deps.promptOps;
+    const sc = deps.sceneOps;
+    const memoryCfg = {
+        noun: 'memory', label: '记忆',
+        trash: (a) => mem['rules-remove']({ id: String(a.id || '') }),
+        restore: (a) => mem['rules-restore']({ trashId: String(a.id || '') }),
+        list: async () => {
+            const r = await mem['rules-trash-list']({});
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || '读取回收站失败');
+            return (r.entries || []).map((e) => ({ id: String(e.trashId), name: String(e.name), deletedAt: e.deletedAt }));
+        },
+    };
+    const skillCfg = {
+        noun: 'skill', label: '技能',
+        // 与 `skill_manager_switch` 同一条（smoke-test P0-1）：不给 root 就按名字在全部来源里
+        // 找胜出的那一份。默认值原本是 dsh，而 `skill_manager_save` 落 hub —— 「建完就删」
+        // 必然报「技能不存在」。删一个真的不存在的技能时退回 dsh，交给 op 报它自己的错。
+        trash: async (a) => {
+            const name = String((a && a.id) || '');
+            const explicit = String((a && a.root) || '').trim();
+            const root = explicit !== '' ? explicit : ((await locateSkillRoot(sk, name)).root || 'dsh');
+            return sk['skill-delete']({ root, name });
+        },
+        restore: (a) => sk['skill-trash-restore']({ id: String(a.id || '') }),
+        // 技能没有独立的回收站列表 op：它挂在 `skill-state` 的 `data.trash` 上（界面同一条来源）。
+        list: async () => {
+            const r = await sk['skill-state']({});
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || 'skill-state failed');
+            return ((r.data && r.data.trash) || []).map((e) => ({ id: String(e.id), name: String(e.name), deletedAt: e.deletedAt }));
+        },
+    };
+    const subagentCfg = {
+        noun: 'persona', label: '人设',
+        trash: (a) => sub['subagent-delete']({ name: String(a.id || '') }),
+        restore: (a) => sub['subagent-trash-restore']({ id: String(a.id || '') }),
+        list: async () => {
+            const r = await sub['subagent-trash-list']({});
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || '读取回收站失败');
+            return (r.trash || []).map((e) => ({ id: String(e.id), name: String(e.name), deletedAt: e.deletedAt }));
+        },
+    };
+    const promptCfg = {
+        noun: 'preset', label: '提示词预设',
+        trash: (a) => pr['agentsmd-remove']({ id: String(a.id || '') }),
+        restore: (a) => pr['agentsmd-trash-restore']({ id: String(a.id || '') }),
+        list: async () => {
+            const r = await pr['agentsmd-trash-list']({});
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || '读取回收站失败');
+            const arr = Array.isArray(r) ? r : (r.presets || r.trash || r.entries || []);
+            return arr.map((e) => ({ id: String(e.id), name: String(e.name || e.id), deletedAt: e.deletedAt }));
+        },
+    };
+    const sceneCfg = {
+        noun: 'scene', label: '场景',
+        // 删场景走 handlers 里那份（`withAgentsMdSync` 包过）：直调 `memoriesService.ops` 会漏掉
+        // 「场景绑的预设曾写进 AGENTS.md，删了要跟着处理」那一步。
+        trash: (a) => deps.sceneRemove({ name: String(a.id || '') }),
+        restore: (a) => sc['scene-trash-restore']({ id: String(a.id || '') }),
+        list: async () => {
+            const r = await sc['scene-trash-list']({});
+            if (!r || r.ok === false)
+                throw new Error((r && r.error) || '读取回收站失败');
+            return (r.trash || []).map((e) => ({ id: String(e.id), name: String(e.name), deletedAt: e.deletedAt }));
+        },
+    };
+    register(defineTool({
+        name: 'memory_manager_remove',
+        description: removeDescription('memory'),
+        parameters: {
+            action: { type: 'string', required: true, enum: ['trash', 'restore', 'list'], description: ACTION_DESC },
+            id: { type: 'string', description: 'For trash: the memory id `<scene>/<name>`. For restore: the trash entry id from action=list. Not needed for list.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(String(v)) },
+        async execute(args) { return runRemove(deps, memoryCfg, args); },
+    }));
+    register(defineTool({
+        name: 'skill_manager_remove',
+        description: removeDescription('skill'),
+        parameters: {
+            action: { type: 'string', required: true, enum: ['trash', 'restore', 'list'], description: ACTION_DESC },
+            id: { type: 'string', description: 'For trash: the skill name. For restore: the trash entry id from action=list. Not needed for list.' },
+            root: { type: 'string', description: 'Source root the skill lives in. Default: whichever source holds that skill; only used by action=trash.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(String(v)) },
+        async execute(args) { return runRemove(deps, skillCfg, args); },
+    }));
+    register(defineTool({
+        name: 'subagent_manager_remove',
+        description: removeDescription('persona'),
+        parameters: {
+            action: { type: 'string', required: true, enum: ['trash', 'restore', 'list'], description: ACTION_DESC },
+            id: { type: 'string', description: 'For trash: the persona name. For restore: the trash entry id from action=list. Not needed for list.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(String(v)) },
+        async execute(args) { return runRemove(deps, subagentCfg, args); },
+    }));
+    register(defineTool({
+        name: 'prompt_manager_remove',
+        description: removeDescription('AGENTS.md preset'),
+        parameters: {
+            action: { type: 'string', required: true, enum: ['trash', 'restore', 'list'], description: ACTION_DESC },
+            id: { type: 'string', description: 'For trash: the preset id. For restore: the trash entry id from action=list. Not needed for list.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(String(v)) },
+        async execute(args) { return runRemove(deps, promptCfg, args); },
+    }));
+    register(defineTool({
+        name: 'scene_manager_remove',
+        description: removeDescription('scene'),
+        parameters: {
+            action: { type: 'string', required: true, enum: ['trash', 'restore', 'list'], description: ACTION_DESC },
+            id: { type: 'string', description: 'For trash: the scene name. For restore: the trash entry id from action=list. Not needed for list.' },
+        },
+        output: { schema: { type: 'string' }, render: (_a, v) => text(String(v)) },
+        async execute(args) { return runRemove(deps, sceneCfg, args); },
+    }));
+}

package/lib/tools/scene.js

@@ -87,9 +87,14 @@ function archiveText(archive) {
         parts.push('工具表方案「' + tt + '」');
     // 快捷提示词绑定（0.20.0）：进了这个场景会动到 `/` 菜单里哪些条目，不报就只能靠猜。
     // 空表是"进入后全部停用"，与"没绑"（这一域不碰）是两句相反的话，不能压成一个 "0 条"。
+    //
+    // 印 **id 而不是条数**（2026-10-15）：`scene_manager_save.quickPrompts` 的描述让模型
+    // "copy them from a scene binding in the listing" —— 而此前这里只印「N 条」，清单里根本
+    // 没有 id 可抄，那句是一条**指不到的死路**（模型照做只会白跑一趟，然后去问用户）。
+    // 与 `skills` / `subagents` 两段同款（那两段本来就是 `toolNameList` 印名字）。
     const qp = archive.quickPrompts;
     if (Array.isArray(qp))
-        parts.push(qp.length ? '快捷提示词 ' + qp.length + ' 条' : '快捷提示词：进入后全部停用');
+        parts.push(qp.length ? '快捷提示词 ' + toolNameList(qp) : '快捷提示词：进入后全部停用');
     return parts.join(' ｜ ');
 }
 /**
@@ -143,16 +148,16 @@ export function buildSceneTools(deps) {
         // 这种筛选（未启用的场景照样要能被进入，藏着只会让模型以为它不存在）。
         // 描述与参数说明里**不点名同族工具**（scene_manager_list / _switch / _save 三条都在出厂
         // 默认的隐藏名单里）：静态文本没法按 toolVisible 改写，点名一条模型没有的工具只会让它
-        // 白跑一趟。要说"去哪看"就用中性说法（the scene listing / the「本机当前的场景」reminder
+        // 白跑一趟。要说"去哪看"就用中性说法（the scene listing / the「当前场景」reminder
         // —— 后者是常驻源，只要场景域开着就在）。点名只留在**运行时回执**里、按可见性分叉。
-        description: 'List every scene with its archive (what entering it switches on: MCP servers, skills, personas, quick prompts, and the bound model tool-table scheme when there is one), bound prompt preset, memory count and enabled / entered / locked state. Read the archive here before saving a scene: a section you give later replaces it whole. Read-only; the scene in effect now is also the「本机当前的场景」reminder.',
+        description: 'List every scene with its archive (what entering it switches on: MCP servers, skills, personas, quick prompts, and the bound model tool-table scheme when there is one), bound prompt preset, memory count and enabled / entered / locked state. The scene currently entered is also shown in the「当前场景」reminder.',
         parameters: {},
         output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
         async execute() {
             const r = await deps.rulesOps['rules-list']({});
             if (!r || r.ok === false)
                 throw new Error((r && r.error) || '读取场景失败');
-            // 档案与「当前进入的是哪个」要额外读一次（纯读盘，`scene-mode-get`）。
+            // 档案与「已进入哪个场景」要额外读一次（纯读盘，`scene-mode-get`）。
             // 读不到**不阻断**清单：场景行退化成只有名字与启用状态，而不是让整条工具失败 ——
             // 一份少了档案的清单仍然有用，一次失败什么都没有。
             // `archives = null` 是"没读到"，与"读到了但某个场景没建档案"是两件事：混成一份会让
@@ -204,10 +209,10 @@ export function buildSceneTools(deps) {
         // 为什么 `action` 是必填枚举而不是一个布尔：与 `mcp_manager_switch` 同一条理由 ——
         // 让模型在 enter / exit 两个动词里选一个，比让它猜"scene 传 null 是什么意思"省一次往返。
         // 参数里刻意不出现 `null`：那是 op（`scene-mode-set`）的形态，模型照着填只会填错。
-        description: 'Enter a scene, or leave the one currently entered. Entering switches on exactly what its archive lists and everything else off — MCP servers, skills, personas, quick prompts, and the model tool table when the scene binds a scheme — narrows injection to its memories, and applies its bound prompt preset to AGENTS.md. Leaving restores the runtime snapshot taken on entry. Check the scene\'s archive in the scene listing before entering. Only when the user asks or approves.',
+        description: 'Enter a scene, or leave the one currently entered. Entering switches on its archive and everything else off, narrows injection to its memories, and applies its bound prompt preset to AGENTS.md. Leaving restores the runtime snapshot taken on entry. Only when the user asks or approves.',
         parameters: {
             action: { type: 'string', required: true, enum: ['enter', 'exit'], description: 'enter = switch to the scene named in `scene`; exit = leave the current one (no scene needed).' },
-            scene: { type: 'string', description: 'Scene name (one path segment), required for enter. Use the exact name, not the display label — the scene listing and the「本机当前的场景」reminder both print names.' },
+            scene: { type: 'string', description: 'Scene name (one path segment), required for enter. Use the exact name, not the display label — the scene listing and the「当前场景」reminder both print names.' },
         },
         output: { schema: { type: 'string' }, render: (_a, v) => text(v) },
         async execute(args) {
@@ -292,11 +297,11 @@ export function buildSceneTools(deps) {
         // 「写入指引」保留（"写成指令而不是备注"—— 这是场景说明质量的杠杆），但不再声称
         // "注入后模型会被要求照办"：2026-09-23 定稿把场景段的授权语删了（注入只陈述现状），
         // 参数说明与注入侧各说各话时，模型信的那份是错的。改为如实说明去向。
-        description: 'Save a scene — a named bundle the user enters: entering it switches on exactly what its archive lists (MCP servers, skills, personas, quick prompts, and the model tool table when a scheme is bound) and everything else off. Creates it if absent, else updates it. An archive section you give replaces that section whole — include what should stay; the receipt reports what got displaced. Saving does not enter it; entering is a separate action. Only on the user\'s instruction.',
+        description: 'Save a scene — a named bundle the user enters: entering it switches on exactly what its archive lists (MCP servers, scene-level MCP note overrides, skills, personas, quick prompts, and the model tool table when a scheme is bound) and everything else off. Creates it if absent, else updates it. An archive section you give replaces that section whole — include what should stay; the receipt reports what got displaced. Saving does not enter it; entering is a separate action. Only on the user\'s instruction.',
         parameters: {
-            scene: { type: 'string', required: true, description: 'Scene name (one path segment, no slashes). Created if absent.' },
-            label: { type: 'string', description: 'Display name shown in the UI. Omit = keep.' },
-            description: { type: 'string', description: 'What this scene is for; shown beside the scene name in the「本机当前的场景」reminder while the scene is on — write an instruction, not a note. Omit = keep.' },
+            scene: { type: 'string', required: true, description: 'Scene name (one path segment, ≤64 chars, no / \\ or < > : " | ? *, not `_shared`). Created if absent.' },
+            label: { type: 'string', description: 'Display name for this scene. Omit = keep.' },
+            description: { type: 'string', description: 'What this scene is for; shown beside the scene name in the「当前场景」reminder while the scene is on — write an instruction, not a note. Omit = keep.' },
             // 与下面 `mcp` / `skills` / `subagents` 同一句式（"Omit = keep; X = 一个都不"）：
             // 界面 2026-10-10 补了「无」这个选项，工具侧的空串语义要跟着说清，否则模型只知道
             // 「省略 = 保持」，不知道还有一条「解绑」的路。
@@ -378,7 +383,7 @@ export function buildSceneTools(deps) {
             const setToolTable = args.toolTablePreset !== undefined && String(args.toolTablePreset).trim() !== '';
             const setQuickPrompts = args.quickPrompts !== undefined;
             if (setQuickPrompts && !Array.isArray(args.quickPrompts)) {
-                throw new Error('quickPrompts 必须是 id 数组（[] = 进入后全部停用；要解绑请到「场景」页）');
+                throw new Error('quickPrompts 必须是 id 数组（[] = 进入后全部停用；解绑需用户手动操作，本工具不提供）');
             }
             const touched = ARCHIVE_SECTIONS.filter((k) => args[k] !== undefined);
             const mustWriteArchive = touched.length > 0 || setToolTable || setQuickPrompts;
@@ -492,10 +497,10 @@ export function buildSceneTools(deps) {
             // 与 mcp/skill 的 listHint 同一条纪律。
             const enterHint = deps.toolVisible('scene_manager_switch')
                 ? '要让它生效，用 scene_manager_switch 进入。'
-                : '要让它生效，由用户在「场景」页进入。';
+                : '要让它生效，需用户手动进入该场景（本会话未开放 scene_manager_switch）。';
             return 'OK: scene「' + scene + '」' + parts.join('；') + warnTail + clearWarn +
                 (collapsed
-                    ? '\n注意：此前所有场景都处于启用状态（历史「全部启用」默认），本次已收窄为只启用一个，新建的这个不在其中 —— 让用户到「场景」页确认。'
+                    ? '\n注意：此前所有场景都处于启用状态（历史「全部启用」默认），本次已收窄为只启用一个，新建的这个不在其中 —— 需用户确认启用状态。'
                     : '') +
                 '\n保存不改运行时：' + enterHint;
         },