dsh-plugin-tool-management 0.20.0 → 0.20.1

package/lib/skills/service.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() {
@@ -312,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();
@@ -347,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, {
@@ -369,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] : []);
@@ -376,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);
             }

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())

package/lib/skills/upload-pipeline.js

@@ -12,8 +12,8 @@ import { promises as fs } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { unzipSync } from "fflate";
 import { isSameOrDescendant } from "../paths.js";
-import { parseSkillDoc, toKebab } from "./frontmatter.js";
-import { attachCode, codedError, entryPath, lstatOrNull, MAX_ENTRY_NAME_LENGTH, renameWithRetry, } from "./core-util.js";
+import { parseSkillDoc, rewriteDeclaredName, toKebab } from "./frontmatter.js";
+import { attachCode, codedError, entryPath, lstatOrNull, MAX_ENTRY_NAME_LENGTH, renameWithRetry, temporaryPath, } from "./core-util.js";
 import { analyzeSource, collectCandidates, MAX_SOURCE_DEPTH, preflightCandidates, replaceWithCopy, } from "./import-pipeline.js";
 import { managerHomePath, resolvedPath, skillCreateRootPath } from "./skill-roots.js";
 export const KEBAB_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -28,6 +28,37 @@ export async function pathsOverlap(a, b) {
     const right = await resolvedPath(b);
     return isSameOrDescendant(left, right) || isSameOrDescendant(right, left);
 }
+/** 目标根下已存在的条目路径：目录 `<name>` 或文件 `<name>.md`，两者都可能占。 */
+async function existingEntryPaths(root, name) {
+    const paths = [join(root, name), join(root, `${name}.md`)];
+    const existing = [];
+    for (const path of paths) {
+        try {
+            await fs.stat(path);
+            existing.push(path);
+        }
+        catch { }
+    }
+    return existing;
+}
+/**
+ * 退号取名：`foo` → `foo-1` → `foo-2`…（与 skill-trash 的 nextFreeSkillName、
+ * 界面 `uniqueName` 的 'dash' 档同一口径）。占用表 = 磁盘现有条目 + 本批次已定名
+ * （`claimed`：防先退号出来的名字又被同批后续候选占用）。候选本身不合法
+ * （entryPath 为 null，如超长）时直接放弃 —— 再往后试也不会变合法。
+ */
+async function nextFreeImportName(root, base, claimed) {
+    for (let i = 1; i <= 999; i += 1) {
+        const candidate = `${base}-${i}`;
+        if (claimed.has(candidate))
+            continue;
+        if (entryPath(root, candidate) === null)
+            return null;
+        if ((await existingEntryPaths(root, candidate)).length === 0)
+            return candidate;
+    }
+    return null;
+}
 export async function importSkill(source, log, options = {}) {
     const targetRoot = skillCreateRootPath();
     const conflict = options.conflict === "overwrite" ? "overwrite" : "skip";
@@ -88,6 +119,9 @@ export async function importSkill(source, log, options = {}) {
             entryPath(targetRoot, candidate.kebab) !== null)
             nameCount.set(candidate.kebab, (nameCount.get(candidate.kebab) || 0) + 1);
     }
+    // 本批次已定名的集合（含退号名）：批量内同名由上方的 nameCount 先拒掉，这里防的是
+    // 退号名与后续候选原名的交叉占用（`foo` 退号成 `foo-1`，同批又来个 `foo-1`）。
+    const claimed = new Set();
     function failureResult() {
         return {
             ok: false,
@@ -122,31 +156,39 @@ export async function importSkill(source, log, options = {}) {
             });
             continue;
         }
+        const existing = await existingEntryPaths(targetRoot, c.kebab);
+        let renamedFrom;
+        if (existing.length) {
+            // 上传导入撞名一律退号新增（用户 2026-10-15）：旧行为是静默跳过，结果里只多
+            // 一行"已跳过"，用户想要的那份根本没进来。`skill-import`（目录导入）不带
+            // dedupe，仍是 skip / overwrite 二选一。
+            if (options.dedupe !== true) {
+                conflicts.push({
+                    name: c.kebab,
+                    source: c.source,
+                    isDir: c.isDir,
+                    paths: existing,
+                });
+                continue;
+            }
+            const free = await nextFreeImportName(targetRoot, c.kebab, claimed);
+            if (!free) {
+                failed.push({
+                    source: c.source,
+                    error: `同名条目太多，无法生成退号名称: ${c.kebab}`,
+                    code: "error.import.renameExhausted",
+                    params: { name: c.kebab },
+                });
+                continue;
+            }
+            renamedFrom = c.kebab;
+            c.kebab = free;
+        }
         const dest = c.isDir
             ? join(targetRoot, c.kebab)
             : join(targetRoot, `${c.kebab}.md`);
-        const paths = [
-            join(targetRoot, c.kebab),
-            join(targetRoot, `${c.kebab}.md`),
-        ];
-        const existing = [];
-        for (const path of paths) {
-            try {
-                await fs.stat(path);
-                existing.push(path);
-            }
-            catch { }
-        }
-        if (existing.length) {
-            conflicts.push({
-                name: c.kebab,
-                source: c.source,
-                isDir: c.isDir,
-                paths: existing,
-            });
-            continue;
-        }
-        pending.push({ name: c.kebab, source: c.source, isDir: c.isDir, dest });
+        claimed.add(c.kebab);
+        pending.push({ name: c.kebab, source: c.source, isDir: c.isDir, dest, renamedFrom });
     }
     if (pending.length === 0 && conflicts.length === 0)
         return failureResult();
@@ -164,6 +206,31 @@ export async function importSkill(source, log, options = {}) {
     for (const p of pending) {
         try {
             const warnings = await replaceWithCopy(p.source, p.dest, p.isDir);
+            // 退号落盘后把声明名改成新名字：`canonicalSkillName` 取的是 frontmatter 的
+            // `name:`，只改目录会"看着叫 foo-1、其实还是 foo"—— 两份同名技能在「同名
+            // 首选」里被并成一组，而那颗开关挑的是来源，按下去什么都不会变（skill-trash.ts
+            // 的 retitleRestoredSkill 同一理由）。返回 null（没有 `name:` 行）是良性的：
+            // 声明名为空时 canonicalSkillName 回落到条目名，退号目录名就是它的名字。
+            // 写盘失败记一条 warning，不阻断导入 —— 技能已按退号名落盘。
+            if (p.renamedFrom) {
+                try {
+                    const docPath = p.isDir ? join(p.dest, "SKILL.md") : p.dest;
+                    const doc = await fs.readFile(docPath, "utf8");
+                    const content = rewriteDeclaredName(doc, p.name);
+                    if (content !== null) {
+                        const temp = temporaryPath(docPath, "retitle");
+                        await fs.writeFile(temp, content, "utf8");
+                        await renameWithRetry(temp, docPath);
+                    }
+                }
+                catch (e) {
+                    warnings.push({
+                        code: "warning.retitleFailed",
+                        params: { path: p.dest },
+                        error: String(e && e.message ? e.message : e),
+                    });
+                }
+            }
             imported.push({ name: p.name, overwritten: false, warnings });
             if (log)
                 log("import", `导入 ${p.source} -> ${p.dest}`);
@@ -337,8 +404,25 @@ export async function prepareUploadedSource(sessionRoot, input) {
         await writeUploadedEntries(contentRoot, input && input.entries);
     const rootSkill = join(contentRoot, "SKILL.md");
     const rootSkillStat = await lstatOrNull(rootSkill);
-    if (!rootSkillStat || !rootSkillStat.isFile())
-        return contentRoot;
+    if (!rootSkillStat || !rootSkillStat.isFile()) {
+        // 没有根级 SKILL.md：剩下的合法形态只有两种 —— 根级 .md（单文件技能）或子目录
+        // 带 SKILL.md（批量），与 importSkill 的 collectCandidates 收录口径一一对应。
+        // 两者都不占，这个包就打不开：此时说清缺的是 SKILL.md、以及是哪个包（用户
+        // 2026-10-15：老报错是 importSkill 的空来源错误，带着 uuid 临时目录路径、落在
+        // 通用「文件要求」段，认不出是谁、也看不出缺什么）。
+        const items = await fs.readdir(contentRoot, { withFileTypes: true });
+        for (const it of items) {
+            if (it.isFile() && it.name.toLowerCase().endsWith(".md"))
+                return contentRoot;
+            if (it.isDirectory()) {
+                const st = await lstatOrNull(join(contentRoot, it.name, "SKILL.md"));
+                if (st && st.isFile())
+                    return contentRoot;
+            }
+        }
+        const label = String((input && input.name) || "").trim() || "上传内容";
+        throw codedError(`${label} 中未找到 SKILL.md：需放在根目录，或放在某个子目录下`, "error.upload.noSkillMd", { name: label });
+    }
     const doc = parseSkillDoc(await fs.readFile(rootSkill, "utf8"));
     const fallback = String((input && input.name) || "uploaded-skill")
         .replace(/\.zip$/i, "")

package/lib/subagents/catalog.js

@@ -80,8 +80,10 @@ export function createSubagentCatalog(deps, opts = {}) {
     let allowed = [];
     let loadedAt = Number.NEGATIVE_INFINITY;
     let inflight = null;
-    // 渲染结果按**深度**缓存：过滤只依赖深度这一个整数，而实际出现的深度就 0/1/2 三档，
-    // 于是"每个 step 同步渲染"退化成一次查表。重算成功时清空。
+    // 渲染结果按**深度 + 尾句前提**缓存：过滤只依赖深度这一个整数（实际出现的深度就 0/1/2 三档），
+    // 而尾句点不点名 `subagent_manager_list` 取决于**这个 agent 手里有没有它**（2026-10-14
+    // 审查 P1-8：此前只按深度缓存，于是尾句用的是第一个来问的 agent 的答案）。
+    // 两维都是小枚举，于是"每个 step 同步渲染"退化成一次查表。重算成功时清空。
     const rendered = new Map();
     const recompute = async () => {
         try {
@@ -102,11 +104,13 @@ export function createSubagentCatalog(deps, opts = {}) {
             if (now() - loadedAt > ttlMs)
                 void revalidate();
             const depth = subagentDepthOf(agent);
-            const cached = rendered.get(depth);
+            const visible = deps.listToolVisible ? deps.listToolVisible(agent) : true;
+            const key = depth + '|' + (visible ? '1' : '0');
+            const cached = rendered.get(key);
             if (cached !== undefined)
                 return cached;
-            const out = renderSubagentCatalog(allowed.filter((p) => catalogInjectedAt(p, depth)), maxEntries, maxDescription, deps.listToolVisible ? deps.listToolVisible() : true);
-            rendered.set(depth, out);
+            const out = renderSubagentCatalog(allowed.filter((p) => catalogInjectedAt(p, depth)), maxEntries, maxDescription, visible);
+            rendered.set(key, out);
             return out;
         },
         catalogVisibleAt: (depth) => allowed.some((p) => catalogInjectedAt(p, depth)),

package/lib/subagents/service.js

@@ -196,6 +196,24 @@ export function createSubagentService(ctx, opts) {
                 : { ...res, stateSyncError: reason };
         }
     }
+    /**
+     * 目标目录里第一个空出来的退号名：`写作助手` → `写作助手（1）` → `写作助手（2）`…
+     * （全角括号，与界面 `uniqueName` 同一写法 —— 人设名就是文件名，不做任何归一化，
+     * `validPersonaName` 也放行全角括号）。
+     *
+     * 候选本身不合法（超长 / 空）时直接放弃：再往后试也不会变合法。
+     */
+    async function nextFreePersonaName(name) {
+        for (let i = 1; i <= 999; i += 1) {
+            const candidate = `${name}（${i}）`;
+            if (!validPersonaName(candidate))
+                return null;
+            const taken = await readFile(join(dir, candidate + '.md'), 'utf8').then(() => true).catch(() => false);
+            if (!taken)
+                return candidate;
+        }
+        return null;
+    }
     /** list() 输出统一附上 enabled：文件缺失 → 全 true；否则按集合。 */
     function withEnabled(docs, set) {
         if (set === null)
@@ -361,11 +379,30 @@ export function createSubagentService(ctx, opts) {
                 return { ok: false, error: `回收站条目不存在: ${id}` };
             if (!validPersonaName(entry.name))
                 return { ok: false, error: `回收站里的人设名不合法: ${entry.name}` };
-            const target = join(dir, entry.name + '.md');
-            const exists = await readFile(target, 'utf8').then(() => true).catch(() => false);
-            // 绝不覆盖：同名人设已经存在时如实拒绝，让人自己决定怎么办。
-            if (exists)
-                return { ok: false, error: `无法恢复，同名人设已存在: ${entry.name}` };
+            /*
+             * 同名先问一句（用户 2026-10-14）：撞名时**默认仍拒绝**（绝不覆盖），但把候选名字一起
+             * 回（`params.next`），界面弹窗才能如实写出"确认后会叫 `写作助手（1）`"；用户确认后带
+             * `dedupe: true` 重来，这一次真的按退号的名字落盘。
+             *
+             * `dedupe` 缺省即旧行为：这条 op 目前只有界面在用，但默认值必须是"拒" —— 一个默认
+             * 静默改名的恢复口，早晚会有人踩。
+             */
+            let name = entry.name;
+            const exists = await readFile(join(dir, name + '.md'), 'utf8').then(() => true).catch(() => false);
+            if (exists) {
+                const next = await nextFreePersonaName(name);
+                if (args?.dedupe !== true || !next) {
+                    // 专用错误码（四个回收站统一）：界面按它认出"这是撞名"并弹确认窗。
+                    return {
+                        ok: false,
+                        error: `已存在同名人设: ${name}`,
+                        code: 'error.dup.conflict',
+                        params: { name, ...(next ? { next } : {}) },
+                    };
+                }
+                name = next;
+            }
+            const target = join(dir, name + '.md');
             try {
                 await mkdir(dir, { recursive: true });
                 await moveOutOfTrash('subagents', id, 'persona.md', target);
@@ -375,8 +412,9 @@ export function createSubagentService(ctx, opts) {
             }
             await purgeTrashEntry('subagents', id);
             // v0.8.5：回收站恢复默认不启动（与新建/导入同口径）。
+            // 启停名单必须按**最终落盘的名字**写：退号恢复时它不是回收站里的原名。
             cache = null;
-            return withEnabledNote({ ok: true, name: entry.name }, () => materializeEnabledExcluding([entry.name]));
+            return withEnabledNote({ ok: true, name, renamed: name !== entry.name }, () => materializeEnabledExcluding([name]));
         },
         'subagent-trash-delete': async (args) => {
             const id = String((args && args.id) || '').trim();