dsh-plugin-tool-management 0.19.1 → 0.20.1

package/lib/skills/manager-state.js

@@ -269,6 +269,8 @@ export function defaultManagerState() {
         // 也不参与 provider 候选）。与「停用来源」不同——停用仍列出技能、只是不可调用。
         // 源文件一个字节都不动；清空这个数组即可恢复。
         removedSources: [],
+        // 用户从回收站「永久删除」的来源：连"已移除"这条记录都不再出现（见 core-types 的说明）。
+        forgottenSources: [],
     };
 }
 export function validStateSkillName(name) {
@@ -324,6 +326,12 @@ export function validManagerStateDocument(value) {
             value.removedSources.some((key) => typeof key !== "string" || key.length === 0 || key.length > 128))
             return false;
     }
+    // 永久删除的来源：同上（可选字段、同样的 key 形状）。
+    if (value.forgottenSources !== undefined) {
+        if (!Array.isArray(value.forgottenSources) ||
+            value.forgottenSources.some((key) => typeof key !== "string" || key.length === 0 || key.length > 128))
+            return false;
+    }
     // 同名首选表：可选字段；只校验容器与值类型，键值逐条在 normalize 里裁剪（见 validPreferredSkillName）。
     if (value.preferredSkills !== undefined) {
         if (!value.preferredSkills ||
@@ -426,6 +434,47 @@ export function normalizeManagerState(value) {
                 !isDefaultSkillSource(key))),
         ].sort();
     }
+    // 永久删除的来源：同一套口径（已知 key、非默认来源），另外**从 removedSources 里摘掉**
+    // —— 一条来源要么"已移除"、要么"已永久删除"，同时挂在两份名单上只会让两处显示打架。
+    {
+        const raw = Array.isArray(value.forgottenSources) ? value.forgottenSources : [];
+        const known = new Set([
+            ...userRoots().map((root) => root.key),
+            ...customKeys,
+        ]);
+        const forgotten = [
+            ...new Set(raw.filter((key) => typeof key === "string" &&
+                known.has(key) &&
+                !isDefaultSkillSource(key))),
+        ].sort();
+        normalized.forgottenSources = forgotten;
+        if (forgotten.length)
+            normalized.removedSources = normalized.removedSources.filter((key) => !forgotten.includes(key));
+    }
+    /*
+     * 自愈：同一个名字不许同时挂在 `disabledSkills` 与 `enabledSkills` 上 —— 那是
+     * `validManagerStateDocument` 判整份文档非法的一种形状。
+     *
+     * 为什么这里**自愈**而不是照旧报错：`readManagerState` 碰到非法文档会 fail-closed 停用
+     * **所有**技能，并且把 `writable` 一起置 false —— 用户在界面上连一个开关都按不动，等于被
+     * 锁死在一份自己造不出来的状态里（用户 2026-10-14 实测踩到，出这条冲突的链是
+     * 「显式启用 → 删除 → 从回收站恢复」，写入侧已在 `markSkillsDisabled` 修掉）。
+     * 而这条不一致本身是无害的：两份名单都只是"用户显式说过什么"，选哪边都能让插件正常工作。
+     * 这与本函数既有的自愈口径一致（指向未知来源的首选、非法的自定义来源条目都是逐条丢掉）。
+     *
+     * 收敛方向取**保守的那一边**：保留 disabled、摘掉 enabled。反向（让 enabled 赢）会静默把
+     * 一个技能打开并送进模型上下文 —— 那才是危险方向；而"关着"用户看得见，翻一下开关就好。
+     * 这也正是 v0.8.5「新建 / 导入 / 恢复默认停用」本来要的落点。
+     */
+    for (const [key, disabled] of Object.entries(normalized.disabledSkills)) {
+        const enabled = normalized.enabledSkills[key];
+        if (!Array.isArray(disabled) || !disabled.length)
+            continue;
+        if (!Array.isArray(enabled) || !enabled.length)
+            continue;
+        const off = new Set(disabled);
+        normalized.enabledSkills[key] = enabled.filter((name) => !off.has(name));
+    }
     return normalized;
 }
 export function normalizeCustomRoots(value) {
@@ -605,6 +654,17 @@ export function markWinners(items, options = {}) {
                     name: winner.entry.name,
                     enabled: winnerEnabled,
                 };
+            /*
+             * 契约：`shadowedBy.root === item.root.key` ⟺ 撞名发生在**同一个来源目录内部**
+             * （两个文件夹都写着 `name: X`），而不是"同一个技能在两个来源里各有一份"。
+             *
+             * 两者必须分得开，因为界面能采取的动作完全不同：跨来源时那颗「启用这个」写的是
+             * `preferredSkills[名] = 来源 key`（真的能换掉生效的那一份）；同来源内部则怎么写都
+             * 指不出区别 —— 首选表的值就是来源 key，两份都在同一个来源里。用户 2026-10-14 报的
+             * 正是这颗**按下去什么都不会变**的假按钮（技能页把它摆在两份同名之间）。
+             * 界面按这个判据收掉按钮（见 client 的 `renderSkill`），但**保留"被覆盖"这个标记**：
+             * 同来源里的落选那份确实不会被加载，如实说比什么都不说好。
+             */
         }
         if (options.markWinner !== false)
             winner.view.winner = true;
@@ -618,11 +678,17 @@ export async function state(options = {}) {
     const removedKeys = new Set(Array.isArray(policyResult.state.removedSources)
         ? policyResult.state.removedSources
         : []);
+    // 「永久删除」过的来源（回收站 → 目录 里那条记录的终点）：连行都不留 —— 界面不该再有
+    // 它的位置，「恢复读取」也无从谈起（用户 2026-10-12 要求 codex / Claude 也能永久删除）。
+    // 注意它同时也在 `activeUserRoots` 里被摘掉，所以下面这层过滤只影响**列表展示**。
+    const forgottenKeys = new Set(Array.isArray(policyResult.state.forgottenSources)
+        ? policyResult.state.forgottenSources
+        : []);
     // 已移除的来源仍然出现在 roots 里（界面要能显示「已移除」并允许恢复），但**不扫描**：
     // 技能不入列表、不参与重名决胜 —— 这正是用户要的「不读取这个文件夹」。
     // 注意这里必须用**全部**来源 + 自定义来源，不能只用 activeUserRoots()，
     // 否则被移除的来源会连行都不剩，界面就无从提供「恢复读取」。
-    const user = [...userRoots(), ...customRootsFromState(policyResult.state)];
+    const user = [...userRoots(), ...customRootsFromState(policyResult.state)].filter((root) => !forgottenKeys.has(root.key));
     const scannable = user.filter((root) => !removedKeys.has(root.key));
     const userScans = await scanDeduplicatedRoots(scannable);
     const projectWarnings = [];
@@ -685,8 +751,12 @@ export async function state(options = {}) {
             });
             continue;
         }
-        // 即使项目 .dsh/skills 尚不存在，也要把可写根返回给创建表单；只读项目根仍按实际存在性展示。
-        if (root.scope === "project" && !exists && root.kind !== "project-dsh")
+        // 项目来源只在真的有技能条目时才注册（skill-roots.ts 的 projectRoots，用户
+        // 2026-10-15 裁定「无技能的项目来源不注册」）；走到这里还不存在的项目根没有可显示的
+        // 内容，跳过。旧实现曾反过来 —— 「即使 .dsh/skills 不存在也把可写根返给创建表单」，
+        // 而创建落点 2026-10-15 已收敛到用户级目录（createRoots 排除 scope=project），
+        // 那条 carve-out 只剩把空来源泵进场景切换的副作用，故删。
+        if (root.scope === "project" && !exists)
             continue;
         if (truncated)
             result.warnings.push({

package/lib/skills/service.js

@@ -5,7 +5,7 @@
 // 沿用上游机制：全局层接管 + 每个活动 agent scope 内二次注册。
 import { appendFile, rename, rm, stat } from 'node:fs/promises';
 import { isInsideRootResolved } from '../paths.js';
-import { state, setSkillEnabled, setPreferredSkill, markSkillsDisabled, setSourceEnabled, setSourceRemoved, deleteSkill, restoreTrash, importSkill, importUploadedSkill, browseDirectories, createSkill, updateSkill, skillDetail, userRoots, projectRoots, readManagerState, customRootsFromState, addCustomRoot, removeCustomRoot, logPath, } from './core.js';
+import { state, setSkillEnabled, setPreferredSkill, markSkillsDisabled, setSourceEnabled, setSourceRemoved, deleteSkill, restoreTrash, importSkill, importUploadedSkill, browseDirectories, createSkill, updateSkill, skillDetail, userRoots, projectRoots, readManagerState, customRootsFromState, addCustomRoot, removeCustomRoot, forgetSource, logPath, } from './core.js';
 import { watchDirectories } from './dir-watch.js';
 import { registerAgentSkillProviders, externalSkillProvider } from './provider-registration.js';
 import { permanentlyDeleteTrashSafely } from './system-trash.js';
@@ -79,6 +79,21 @@ function notifyChatCatalog(ctx, invalidateSkills) {
     }
     catch { /* 斜杠菜单刷新失败不影响已完成的操作 */ }
 }
+/**
+ * 本插件**可写**的技能来源集合，共两员：
+ *
+ * - `hub`（`$DSH_HOME/tool-management/skills/`，界面名「导入技能」）—— 导入 / 上传的落点；
+ * - `dsh`（`$DSH_HOME/skills/`，界面名「DSH 技能」）—— **新建**技能的落点（用户裁定
+ *   2026-10-15：「新增技能默认 DSH 技能；导入技能功能才是导入技能目录」）。
+ *
+ * 其余根（官方内置 / agents / codex / claude / 自定义 / 项目）一律不碰。
+ *
+ * 这个集合曾经只有 `hub`：新建默认落点还在 hub 的年代那么判够用。落点改到 dsh 之后，
+ * 只认 hub 会把「新建 → 再存一次」整条回路掐断 —— 新建默认落 dsh，改的分支永远找不到
+ * hub 里的胜出者，每次都回 `error.update.notOwnRoot`。所以它与新建落点是同一条裁定
+ * 的两面，必须一起扩。
+ */
+const PLUGIN_WRITABLE_ROOTS = new Set(['hub', 'dsh']);
 /** 全插件共用的审计日志：单一串行写队列，避免多处写同一文件交叉。 */
 let sharedLog = null;
 export function pluginLog() {
@@ -233,6 +248,8 @@ export function createSkillsService(ctx) {
         // 批量启停与单条启停同权：配了访问令牌的宿主必须同样要求带令牌。
         'skill-set-all',
         'skill-trash-restore', 'skill-trash-delete', 'skill-custom-add', 'skill-custom-remove',
+        // 「永久删除来源记录」（回收站 → 目录）：与上面两条同权，是写操作。
+        'skill-source-forget',
     ]);
     /**
      * 新建 / 导入 / 恢复技能后统一「默认停用」。**失败不能吞。**
@@ -310,23 +327,30 @@ export function createSkillsService(ctx) {
             return { enabled, changed, failed };
         }), afterWrite),
         // 创建 / 导入 / 删除 / 回收站
-        // 创建默认落 hub（`tool-management/skills/`）：UI 不传 root 时走这里；
-        // core.js 的 createSkill 默认值是第二道保险（同口径）。官方 `~/.dsh/skills/` 仍作为来源列出。
+        // 创建默认落 **DSH 技能目录**（用户裁定 2026-10-15）：v0.4 起这里是 hub，现在改回 dsh ——
+        // hub（`tool-management/skills/`）只服务「导入技能」功能。与 UI「创建技能」的
+        // `defaultCreateRoot`、core.js 的 createSkill 默认值同口径；core 里的那份是第二道保险。
+        // 落点变了但有一件事没变：`skill_manager_switch` / `_remove` 侧跨来源解析照旧兜得住（P0-1）。
         'skill-create': wrap((args) => write(async () => {
             // requestRoot 未命中时回传原始 key，让 core 的 error.root.unknown 带上来源名
             // （否则传了不存在的 root 会收到「技能来源不存在：(空)」这种指错方向的提示）。
-            const key = String(args.root || 'hub');
-            const res = await createSkill({ name: args.name, description: args.description, body: args.body }, log, { root: (await requestRoot(key)) || key });
+            const key = String(args.root || 'dsh');
+            const res = await createSkill({ name: args.name, description: args.description, body: args.body, files: args.files }, log, { root: (await requestRoot(key)) || key });
             // v0.8.5：新建技能默认不启动（用户裁定）——与子智能体 / MCP 同口径。
             if (res && res.ok !== false && res.name) {
                 return disableNewSkills([{ root: String(res.root || 'hub'), name: String(res.name) }], res);
             }
             return res;
         }), afterWrite),
-        // 改写**本插件自己写的那一份**技能。只认 hub 里的胜出者：同名技能在 dsh / agents /
-        // claude / 自定义根各有一份时只有一份生效，改错那一份会返回 OK 而技能毫无变化
-        // （用户实测踩过：同一技能四份并存，启错根等于没启）。胜出者判定要读来源排序与首选
-        // 设置，属于状态层，所以在这里做；core 的 `updateSkill` 只保证不越出给定根。
+        // 改写**本插件自己写的那一份**技能。先跨来源找胜出者，再要求它落在本插件可写的两个根
+        // （hub / dsh，见 PLUGIN_WRITABLE_ROOTS）里：同名技能在 dsh / agents / claude / 自定义根
+        // 各有一份时只有一份生效，改错那一份会返回 OK 而技能毫无变化（用户实测踩过：同一技能
+        // 四份并存，启错根等于没启）。胜出者判定要读来源排序与首选设置，属于状态层，所以在这里
+        // 做；core 的 `updateSkill` 只保证不越出给定根。
+        //
+        // 门禁为什么不能只认 hub：新建默认落点 2026-10-15 改到 dsh 后，模型 `skill_manager_save`
+        // 建出来的技能全在 dsh；只认 hub 时改的分支永远找不到 hub 胜出者，「新建 → 再存一次」
+        // 直接回 error.update.notOwnRoot。可写集合跟着落点一起扩才闭环。
         'skill-update': wrap((args) => write(async () => {
             const wanted = String(args.name || '').trim();
             const s = await readState();
@@ -345,15 +369,17 @@ export function createSkillsService(ctx) {
                 return { ok: false, code: 'error.update.notFound', params: { name: wanted }, error: `技能不存在：${wanted}` };
             }
             const winner = hits.find((h) => !h.shadowedBy) || hits[0];
-            if (winner.rootKey !== 'hub') {
+            if (!PLUGIN_WRITABLE_ROOTS.has(winner.rootKey)) {
                 return {
                     ok: false,
                     code: 'error.update.notOwnRoot',
                     params: { name: wanted, root: winner.rootKey },
-                    error: `技能 ${wanted} 的生效副本在来源「${winner.rootKey}」，不在本插件落点（hub = $DSH_HOME/tool-management/skills）：本插件不修改官方根里的技能`,
+                    error: `技能 ${wanted} 的生效副本在来源「${winner.rootKey}」，不在本插件可写的目录（hub = 导入落点；dsh = $DSH_HOME/skills）：本插件不修改官方根里的技能`,
                 };
             }
-            return updateSkill({ name: args.name, description: args.description, body: args.body }, log, { root: (await requestRoot('hub')) || 'hub' });
+            // 写**胜出者所在的那个根**，不能写死 hub：同名两边各有一份时写错那份，
+            // 正是这道判定要防的「返回 OK 而技能毫无变化」。
+            return updateSkill({ name: args.name, description: args.description, body: args.body }, log, { root: (await requestRoot(winner.rootKey)) || winner.rootKey });
         }), afterWrite),
         'skill-import': wrap((args) => write(async () => {
             const res = await importSkill(String(args.source || ''), log, {
@@ -367,6 +393,10 @@ export function createSkillsService(ctx) {
         'skill-upload': wrap((args) => write(async () => {
             const res = await importUploadedSkill({ name: args.name, entries: args.entries, zip: args.zip }, log, {
                 conflict: args.conflict === 'overwrite' ? 'overwrite' : 'skip',
+                // 上传导入撞名一律退号新增（用户 2026-10-15）：静默跳过会让用户想要的
+                // 那份根本没进来，结果里只多一行"已跳过"。目录导入（skill-import）
+                // 不带这个开关，仍是 skip / overwrite 二选一。
+                dedupe: true,
             });
             // 上传/导入同口径：默认停用。
             const names = res && Array.isArray(res.imported) ? res.imported : (res && res.name ? [res.name] : []);
@@ -374,8 +404,14 @@ export function createSkillsService(ctx) {
         }), afterWrite),
         'skill-delete': wrap((args) => write(async () => deleteSkill(await requestRoot(String(args.root || 'dsh')), String(args.name || ''), log)), afterWrite),
         'skill-trash-restore': wrap((args) => write(async () => {
-            const res = await restoreTrash(String(args.id || ''), log, projectOptions());
+            // `dedupe: true` = 界面上"已存在同名技能，是否恢复为 foo-1"确认过之后那一次
+            // （用户 2026-10-14）；不带时撞名照旧拒绝，并把候选名字放在 `params.next` 里回给弹窗。
+            const res = await restoreTrash(String(args.id || ''), log, {
+                ...projectOptions(),
+                dedupe: args.dedupe === true,
+            });
             // 恢复的技能默认停用（v0.8.5 用户裁定：新建/导入/恢复一律不启动，手动开启）。
+            // `res.name` 是**最终落盘的名字**（退号恢复时不是回收站里的原名），启停状态必须按它写。
             if (res && res.ok !== false && res.name) {
                 return disableNewSkills([{ root: String(res.root || 'hub'), name: String(res.name) }], res);
             }
@@ -385,6 +421,10 @@ export function createSkillsService(ctx) {
         // 自定义技能目录：添加（绝对路径，只读接入）/ 移除（连同策略键）。
         'skill-custom-add': wrap((args) => write(() => addCustomRoot(args && args.path, args && args.label, log)), afterWrite),
         'skill-custom-remove': wrap((args) => write(() => removeCustomRoot(args && args.key, log)), afterWrite),
+        // 永久删除一条**按约定发现**的来源记录（agents / codex / claude）。与 `skill-custom-remove`
+        // 的分工见 core.ts 的 `forgetSource`：那条管用户手加的自定义目录，这条管推导出来的来源
+        // —— 后者不在状态文件的 customRoots 里，必须另记一份"已永久删除"名单才删得掉。
+        'skill-source-forget': wrap((args) => write(() => forgetSource(args && args.root, log)), afterWrite),
     };
     /**
      * 该绝对路径是否落在「本插件认识的技能来源」内。

package/lib/skills/skill-roots.js

@@ -34,11 +34,13 @@ export function userRoots() {
         // 官方内置紧随 DSH 技能之后（用户裁定）：同为一眼要看的来源，排在导入技能之前。
         ...(official === null ? [] : [official]),
         {
-            // v0.4：插件**新建/导入**的技能落到 hub 内（用户要求：插件产生的文件收在
+            // v0.4：插件**导入/上传**的技能落到 hub 内（用户要求：插件产生的文件收在
             // $DSH_HOME/tool-management/）。rank 高于 DSH 技能，同名时 hub 版本遮蔽官方目录里的；
             // 官方 ~/.dsh/skills/ 仍作为可切换来源列出（不搬走、不删）。
             //
-            // 界面名「导入技能」：它是插件导入/新建技能的落点，不是"管理器自己的一类技能"。
+            // 界面名「导入技能」：它是插件**导入/上传**的落点 —— v0.20.0 及以前新建也落这里，
+            // 2026-10-15 用户裁定「新增技能默认 DSH 技能，导入技能功能才用导入技能目录」后，
+            // 新建改走 DSH 技能目录（见 core.ts 的 createSkill 默认值）。
             // 与 dsh 同为默认来源：路径必须读取（不可移除、不可停用），里面的技能可删。
             key: "hub",
             path: join(resolveDshHome(), "tool-management", "skills"),
@@ -137,6 +139,46 @@ export async function projectSourceSafe(definition) {
     }
     return !(await overlapsUserSkillRoot(definition.path));
 }
+/**
+ * 项目来源目录底下有没有至少一条技能条目（只看形状，不读正文）：
+ *   · 可写来源（`.dsh/skills`）—— 至少一个子目录里带 `SKILL.md`（与 scanEntries 的
+ *     mutable 分支同形状：顶层 flat `.md` 只属于只读来源）；
+ *   · 只读来源（`.agents/skills`）—— 顶层有子目录（里面才可能藏 bundle）或 `.md` 文件
+ *     （含根自身的 SKILL.md），与 discoverReadonlyEntries 同一形状。
+ *
+ * 目录缺失 / 是链接 / 读不了，以及点号开头的隐藏条目，一律按「没有」处理 —— 注册一个
+ * 没有技能的来源只有噪音：占一个来源位，还会在场景切换时产生「停用 project-dsh:<路径
+ * 哈希>」这类只有内部键的提示（用户 2026-10-15 报的）。
+ */
+async function hasSkillEntry(path, mutable) {
+    const stat = await lstatOrNull(path);
+    if (!stat || !stat.isDirectory() || stat.isSymbolicLink())
+        return false;
+    let items;
+    try {
+        items = await fs.readdir(path, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const item of items) {
+        if (item.isSymbolicLink() || item.name.startsWith("."))
+            continue;
+        if (mutable) {
+            if (!item.isDirectory())
+                continue;
+            const doc = await lstatOrNull(join(path, item.name, "SKILL.md"));
+            if (doc && doc.isFile() && !doc.isSymbolicLink())
+                return true;
+            continue;
+        }
+        if (item.isDirectory())
+            return true;
+        if (item.isFile() && item.name.toLowerCase().endsWith(".md"))
+            return true;
+    }
+    return false;
+}
 export async function projectRoots(projectCwds = [], diagnostics) {
     const projects = new Map();
     for (const cwd of Array.isArray(projectCwds) ? projectCwds : []) {
@@ -207,8 +249,16 @@ export async function projectRoots(projectCwds = [], diagnostics) {
             },
         ];
         for (const candidate of candidates) {
-            if (await projectSourceSafe(candidate))
-                roots.push(candidate);
+            if (!(await projectSourceSafe(candidate)))
+                continue;
+            // 无技能的项目来源不注册（用户 2026-10-15 裁定）：目录不存在、是链接或底下没有
+            // 一条技能条目时，这个来源对用户不可见也不可用 —— 硬注册出来只会平白占一个来源位、
+            // 在场景切换时弹「停用 project-dsh:<路径哈希>」这类只有内部键的提示，而新建技能的
+            // 落点也早已不含项目来源（createRoots 只收用户级）。本仓库就没有 .dsh/skills，
+            // 用户就是在场景预览卡上看到这一条才裁的。
+            if (!(await hasSkillEntry(candidate.path, candidate.mutable === true)))
+                continue;
+            roots.push(candidate);
         }
     }
     return roots;

package/lib/skills/skill-trash.js

@@ -9,8 +9,11 @@ import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { promises as fs } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { isSameOrDescendant } from "../paths.js";
-import { codedError, entryPath, lstatOrNull, pathIdentity, renameWithRetry, } from "./core-util.js";
+import { codedError, entryPath, lstatOrNull, pathIdentity, renameWithRetry, temporaryPath, } from "./core-util.js";
+import { rewriteDeclaredName } from "./frontmatter.js";
 import { dshRootPath, overlapsUserSkillRoot, projectIdentity, projectRoots, readonlyError, rootByKey, rootDefinition, skillCreateRootPath, trashRootPath, } from "./skill-roots.js";
+// `KEBAB_RE` 的单一真相源在 upload-pipeline（manager-state / core 也都从那里取）。
+import { KEBAB_RE } from "./upload-pipeline.js";
 export function writableRootDefinition(root) {
     const definition = rootDefinition(root);
     if (!definition || definition.mutable !== true)
@@ -19,7 +22,7 @@ export function writableRootDefinition(root) {
         return resolve(definition.path) === resolve(dshRootPath())
             ? rootByKey("dsh")
             : null;
-    // v0.4：hub 内技能目录同为用户级可写根（插件新建/导入的落点）。
+    // v0.4：hub 内技能目录同为用户级可写根（插件导入/上传的落点）。
     if (definition.key === "hub")
         return resolve(definition.path) === resolve(skillCreateRootPath())
             ? rootByKey("hub")
@@ -204,6 +207,75 @@ export async function listTrash() {
     }
     return result.sort((a, b) => String(b.deletedAt).localeCompare(String(a.deletedAt)));
 }
+/**
+ * 目标根里第一个空出来的退号名：`foo` → `foo-1` → `foo-2`…（与界面 `uniqueName` 的
+ * `'dash'` 档同一写法）。
+ *
+ * 用半角连字符而不是全角括号：技能条目名必须过 `KEBAB_RE`，`foo（1）` 会被 `toKebab` 抹成
+ * `foo-1` —— 写出来本来就是 `foo-1`，不如一开始就按这个写，省得"看着叫甲、落盘叫乙"。
+ *
+ * 候选本身不合法（超长 / 空）时直接放弃：再往后试也不会变合法。
+ */
+async function nextFreeSkillName(root, name) {
+    for (let i = 1; i <= 999; i += 1) {
+        const candidate = `${name}-${i}`;
+        if (entryPath(root, candidate) === null)
+            return null;
+        if ((await safeExistingEntryPaths(root, candidate)).length === 0)
+            return candidate;
+    }
+    return null;
+}
+/**
+ * 退号恢复时把技能**声明名**改成新的落盘名（用户 2026-10-14）。
+ *
+ * 为什么必须改：`canonicalSkillName()` 取的是 frontmatter 里的 `name:`，**不是文件夹名** ——
+ * 技能页的同名判定、`preferredSkills` 首选表、喂给宿主的 provider 候选名，全都以它为准。
+ * 只把目录改成 `foo-1` 而里面仍写着 `name: foo`，等于恢复出一份"看着叫 foo-1、其实还是 foo"
+ * 的技能：它会跟原件被判成同名，技能页于是给它一颗「启用这个」——而那颗按钮挑的是**来源**，
+ * 两份都在同一个来源目录里，按下去什么都不会变。
+ *
+ * 只重写 `name:` 那一行的值，其余 frontmatter（块标量、`disable-model-invocation` 等）与正文
+ * **逐字节保留**（正则只吃一个行内片段，连 CRLF 都不动）：恢复的语义是"把原件放回去"，
+ * 不是"按当前模板重写一遍"——后者会顺手把用户写在别的键上的东西抹掉。
+ *
+ * 不动内容的情形一律返回 false（调用方只用来记日志）：名字不过 `KEBAB_RE`、形态认不出、
+ * 没有 frontmatter、原本就没有 `name:` 行、声明名本来就对。**认不出就一个字节都不写** ——
+ * 猜错形态会把附件目录里的 SKILL.md 当成技能文档改掉；替用户补一个缺失的 `name:` 也不行，
+ * 那会把一份坏技能伪装成好的。
+ */
+async function retitleRestoredSkill(root, name, metadata) {
+    if (!KEBAB_RE.test(name))
+        return false;
+    // 形态与上面的 `entryNameFor` 同一口径：bundle 收的是 `<原名>`，flat 收的是 `<原名>.md`。
+    const isBundle = metadata.entries.includes(metadata.name);
+    const isFlat = metadata.entries.includes(`${metadata.name}.md`);
+    // 两个都认得出或都认不出 = 形状不明，不猜。
+    if (isBundle === isFlat)
+        return false;
+    const docPath = isBundle
+        ? join(root, name, "SKILL.md")
+        : resolve(root, `${name}.md`);
+    const doc = await fs.readFile(docPath, "utf8");
+    // 声明名改写走 frontmatter.ts 的共享助手（导入撞名的退号也用它）：只换 `name:`
+    // 一行的值，其余逐字节保留；认不出形态返回 null —— 一个字节都不写。
+    // 不加引号：`KEBAB_RE` 已经保证这个名字只含 `[a-z0-9-]`，没有任何需要转义的字符 ——
+    // 与插件自己的写手（`createSkill` / `updateSkill` 的 `name: ${name}`）同一形状，
+    // 免得"新建出来叫 demo-1、恢复出来叫 \"demo-1\""这种无谓的差别。
+    const content = rewriteDeclaredName(doc, name);
+    if (content === null)
+        return false;
+    const temp = temporaryPath(docPath, "restore");
+    try {
+        await fs.writeFile(temp, content, "utf8");
+        await renameWithRetry(temp, docPath);
+    }
+    catch (error) {
+        await fs.rm(temp, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    return true;
+}
 export async function restoreTrash(id, log, options = {}) {
     const metadata = await readTrashMetadata(id);
     if (!metadata)
@@ -217,31 +289,65 @@ export async function restoreTrash(id, log, options = {}) {
     if (!definition || definition.ok === false)
         return definition || readonlyError("restore");
     const root = definition.path;
+    /*
+     * 同名先问一句（用户 2026-10-14）：撞名时**默认仍拒绝**，但把候选名字一起回（`params.next`），
+     * 界面弹窗才能如实写出"确认后会叫 `foo-1`"；用户确认后带 `dedupe: true` 重来，这一次真的
+     * 按退号的名字落盘。
+     *
+     * `dedupe` 缺省即旧行为 —— 这条 op 目前只有界面在用，但保留"缺省拒"这层是为了不给未来的
+     * 调用方埋一个"撞名就悄悄改名"的默认值。
+     */
+    let name = metadata.name;
     const conflicts = await safeExistingEntryPaths(root, metadata.name);
-    if (conflicts.length)
-        return {
-            ok: false,
-            error: `无法恢复，同名技能已存在: ${metadata.name}`,
-            code: "error.trash.conflict",
-            params: { name: metadata.name },
-        };
+    if (conflicts.length) {
+        const candidate = await nextFreeSkillName(root, metadata.name);
+        if (options.dedupe !== true || candidate === null)
+            return {
+                ok: false,
+                error: `已存在同名技能: ${metadata.name}`,
+                // 专用错误码（四个回收站统一）：界面按它认出"这是撞名"并弹确认窗，而不是靠比文案。
+                code: "error.dup.conflict",
+                params: { name: metadata.name, ...(candidate ? { next: candidate } : {}) },
+            };
+        name = candidate;
+    }
+    const renamed = name !== metadata.name;
+    /**
+     * 回收站条目里的**顶层条目名**跟着退号，其余（bundle 目录里的附件 / 脚本）原样 ——
+     * `entries` 装的是当初移进回收站时那批顶层名字：bundle 是 `<名>`，flat 是 `<名>.md`
+     * （见 core.ts 的 deleteSkill）。只有这两个与名字有关，别的名字改了就是改坏内容。
+     */
+    const entryNameFor = (fileName) => {
+        if (!renamed)
+            return fileName;
+        if (fileName === metadata.name)
+            return name;
+        if (fileName === `${metadata.name}.md`)
+            return `${name}.md`;
+        return fileName;
+    };
     await fs.mkdir(root, { recursive: true });
     const itemRoot = join(trashRootPath(), id);
     const moved = [];
     try {
         for (const fileName of metadata.entries) {
             const source = join(itemRoot, fileName);
-            const destination = join(root, fileName);
+            const destination = join(root, entryNameFor(fileName));
             if (!isSameOrDescendant(itemRoot, source) ||
                 !isSameOrDescendant(root, destination))
                 throw codedError("回收站条目路径非法", "error.trash.invalid", { id });
             await movePathWithFallback(source, destination, options.renameOptions);
             moved.push({ source, destination });
         }
+        // 顶层名字改完，文档里声明的名字也要跟上 —— 否则"看着叫 foo-1、其实还是 foo"，
+        // 技能页仍按 foo 判同名。失败即抛：半份的恢复（目录改了、声明没改）正是要修的那个 bug。
+        if (renamed && (await retitleRestoredSkill(root, name, metadata)))
+            if (log)
+                log("restore", `恢复技能时改写声明名 ${metadata.name} -> ${name}`);
         await fs.rm(itemRoot, { recursive: true, force: true });
         if (log)
-            log("restore", `从回收站恢复 ${metadata.name} -> ${root}`);
-        return { id, name: metadata.name, root: trashRootMetadata(definition) };
+            log("restore", `从回收站恢复 ${name} -> ${root}`);
+        return { id, name, renamed, root: trashRootMetadata(definition) };
     }
     catch (error) {
         for (const item of moved.reverse())