dsh-plugin-tool-management 0.19.1 → 0.20.1

package/lib/scene-prompt-sync.js

@@ -173,30 +173,47 @@ export function createScenePromptSync(deps) {
         }
         return complete ? out : null;
     }
+    /**
+     * 进场景的第一笔写入之前，把当时的基线记下来（已有待恢复的基线就不覆盖：连续切场景时
+     * 基线始终是「进场景之前」那一份）。
+     * @returns 需要让用户知道的原因（写不进去 / 记下来是空的）；一切正常返回 undefined。
+     */
+    async function captureBaseline(scene) {
+        const saved = await readBaseline();
+        if (saved && saved.content !== null)
+            return undefined;
+        const cur = await deps.prompts.getCurrent();
+        const content = cur && cur.ok && cur.exists ? String(cur.content) : null;
+        const failed = await writeBaseline({
+            v: 1,
+            at: Date.now(),
+            presetId: cur && cur.ok && cur.presetId ? String(cur.presetId) : null,
+            content,
+        });
+        // 基线写不进去 = 退出场景时恢复不回来。**照旧进场景**（那是用户的要求），
+        // 但必须当场说出来，别让用户以为还能退回去（审查 F14）。
+        if (failed !== null) {
+            return `进场景前的提示词基线没能写入（${failed}）：AGENTS.md 已切到场景「${scene}」绑定的预设，但退出场景时恢复不回原来的内容（${deps.baselineFile}）。`;
+        }
+        // 记下来的是**空的**（进场景时 AGENTS.md 就不存在、或读不出来）：退出场景时没有正文
+        // 可写回，AGENTS.md 会留在场景态。与「写失败」是两件事，后果一样，同样当场说
+        // （2026-10-15 smoke-test P0-2：这一种此前要等到退出之后，才被误报成「快照损坏」）。
+        if (content === null) {
+            return `进场景前的 AGENTS.md 没有内容可记（文件不存在或读不出来）：退出场景时恢复不回原来的状态，AGENTS.md 会留在场景「${scene}」绑定的预设上。`;
+        }
+        return undefined;
+    }
     async function sync() {
         const current = await state();
         if (!current)
             return { unchanged: true };
         if (drives(current)) {
-            if (current.duplicate)
-                return { applied: current.presetId, unchanged: true };
-            // 进场景的第一笔写入之前，先记下当时的基线（已有快照就不覆盖：连续切场景时
-            // 基线始终是"进场景之前"那一份）。
-            let baselineError;
-            const saved = await readBaseline();
-            if (!saved || saved.content === null) {
-                const cur = await deps.prompts.getCurrent();
-                const failed = await writeBaseline({
-                    v: 1,
-                    at: Date.now(),
-                    presetId: cur && cur.ok && cur.presetId ? String(cur.presetId) : null,
-                    content: cur && cur.ok && cur.exists ? String(cur.content) : null,
-                });
-                // 基线写不进去 = 退出场景时恢复不回来。**照旧进场景**（那是用户的要求），
-                // 但必须当场说出来，别让用户以为还能退回去（审查 F14）。
-                if (failed !== null) {
-                    baselineError = `进场景前的提示词基线没能写入（${failed}）：AGENTS.md 已切到场景「${current.scene}」绑定的预设，但退出场景时恢复不回原来的内容（${deps.baselineFile}）。`;
-                }
+            // 基线必须在 `duplicate` 早退**之前**记（2026-10-15 smoke-test P0-2）：早退省的只是
+            // 「AGENTS.md 不用再写一遍」，不是「不用留退路」。原先这一句在早退之后，于是
+            // 「进一个内容已经等于该预设的场景」完全不记基线 —— 退出时恢复不回原内容。
+            const baselineError = await captureBaseline(current.scene);
+            if (current.duplicate) {
+                return { applied: current.presetId, unchanged: true, ...(baselineError ? { baselineError } : {}) };
             }
             const res = await deps.prompts.apply(current.presetId);
             if (res && res.ok === false)
@@ -205,16 +222,24 @@ export function createScenePromptSync(deps) {
         }
         // 没有场景驱动 → 如果刚从驱动态退出，把进场景前的基线写回去。
         const saved = await readBaseline();
-        if (!saved || saved.content === null) {
-            // 「没有快照」是常态（没进过场景）；「快照文件在、但读不出来」是**故障** ——
-            // 那意味着恢复目标丢了，AGENTS.md 的提示词基线会悄悄留在场景态。这里曾经一律
-            // 静默 `unchanged`，用户看到的是"没场景驱动所以什么都没做"（审查 P2-16）。
+        // 「快照文件在、但读不出来」是**故障** —— 那意味着恢复目标丢了，AGENTS.md 的提示词基线
+        // 会悄悄留在场景态。这里曾经一律静默 `unchanged`，用户看到的是"没场景驱动所以什么都没做"
+        // （审查 P2-16）。但两种"没有正文"必须分开（2026-10-15 smoke-test P0-2）：
+        //   · `saved === null`         → 文件缺失 / 半截 JSON / 解析失败；
+        //   · `saved.content === null` → 下面 `writeBaseline({presetId:null, content:null})` 写下的
+        //     「没有待恢复基线」哨兵，是**正常终态**（每次正常退出场景之后都会留下它）。
+        // 原先两者共用 `!saved || saved.content === null` 一个条件，于是每次正常退出之后，下一次
+        // 无场景驱动的同步都把哨兵判成损坏，报一句假 WARN —— 而假 WARN 长得和真故障一样，
+        // 反过来把"恢复目标真丢了"这条信号淹掉。
+        if (saved === null) {
             if (await baselineExists()) {
                 warn(`scene-prompt: baseline snapshot exists but is unreadable: ${deps.baselineFile}`);
                 return { error: `基线快照读不出来（文件可能损坏），未能恢复 AGENTS.md：${deps.baselineFile}` };
             }
             return { unchanged: true };
         }
+        if (saved.content === null)
+            return { unchanged: true };
         const res = await deps.prompts.restore(saved.content);
         if (res && res.ok === false)
             return { error: String(res.error || '恢复 AGENTS.md 失败') };

package/lib/sessions/history.js

@@ -205,6 +205,24 @@ export function createHistoryDomain(deps) {
             const liveByPath = new Map();
             const owned = new Map();
             const liveRecords = [];
+            // 「目录真实存在」检查缓存：活登记与重建组共用同一份探测，同一目录只 stat 一次；
+            // 结果按归一化键缓存，避免每次刷新重复探盘。
+            const dirExistsCache = new Map();
+            async function directoryExists(p) {
+                const k = workspacePathKey(p);
+                const hit = dirExistsCache.get(k);
+                if (hit !== undefined)
+                    return hit;
+                let ok = false;
+                try {
+                    ok = (await stat(p)).isDirectory();
+                }
+                catch {
+                    ok = false;
+                }
+                dirExistsCache.set(k, ok);
+                return ok;
+            }
             const table = typeof registry.requireTable === 'function' ? registry.requireTable() : undefined;
             const state = typeof registry.requireState === 'function' ? registry.requireState() : undefined;
             if (table) {
@@ -224,7 +242,14 @@ export function createHistoryDomain(deps) {
                         liveByPath.set(workspacePathKey(path), wid);
                         liveRecords.push({ id: String(wid), path, title });
                     }
-                    const view = { id: 'ws:' + wid, title, kind: 'live', registered: true, ...(path ? { path } : {}) };
+                    // 活登记也要探一次盘：登记还在、但磁盘上的工作区文件夹被删掉时，界面必须能及时
+                    // 标出来（用户 2026-10-12：「要怎么及时知道这个工作区实际文件夹已经被删除了」）。
+                    const liveDirMissing = path !== undefined && !(await directoryExists(path));
+                    const view = {
+                        id: 'ws:' + wid, title, kind: 'live', registered: true,
+                        ...(path ? { path } : {}),
+                        ...(liveDirMissing ? { dirMissing: true } : {}),
+                    };
                     groupsById.set(view.id, view);
                     groups.push(view);
                     workspaces[wid] = { title, ...(path ? { path } : {}) };
@@ -240,24 +265,6 @@ export function createHistoryDomain(deps) {
             }
             const sessionPaths = registry.sessionPaths instanceof Map ? registry.sessionPaths : undefined;
             const headers = registry.headers instanceof Map ? registry.headers : undefined;
-            // 「目录真实存在」检查缓存：canRegister 从「宿主 sessionPaths 命中」放宽为
-            // 「目录存在」时，同一目录只 stat 一次；结果按归一化键缓存，避免每次刷新重复探盘。
-            const dirExistsCache = new Map();
-            async function directoryExists(p) {
-                const k = workspacePathKey(p);
-                const hit = dirExistsCache.get(k);
-                if (hit !== undefined)
-                    return hit;
-                let ok = false;
-                try {
-                    ok = (await stat(p)).isDirectory();
-                }
-                catch {
-                    ok = false;
-                }
-                dirExistsCache.set(k, ok);
-                return ok;
-            }
             for (const it of items) {
                 const sid = it.sessionId;
                 let wid = owned.get(sid);
@@ -287,14 +294,17 @@ export function createHistoryDomain(deps) {
                 const known = snapshot ? snapshot.get(workspacePathKey(path)) : undefined;
                 const existing = groupsById.get(key);
                 if (existing) {
-                    // 同目录的多个会话：宿主索引命中，或磁盘目录真实存在，即可重新登记。
-                    if (canonical !== undefined || (await directoryExists(path))) {
+                    // 同目录的多个会话：只要磁盘目录真实存在，即可重新登记。
+                    // 注意：不能只看宿主 sessionPaths 命中——索引里可能残留已被删除目录的 sessionId。
+                    if (await directoryExists(path)) {
                         existing.canRegister = true;
                         existing.dirMissing = false;
                     }
                     continue;
                 }
-                const canRegister = canonical !== undefined || (await directoryExists(path));
+                // canRegister 必须落到「目录真实存在」：仅靠 canonical/sessionPaths 命中会把
+                // 已被删除的工作区目录误判为可登记，界面继续显示「重新登记」。
+                const canRegister = await directoryExists(path);
                 const view = {
                     id: key,
                     title: known?.title || workspaceBaseName(path) || path,

package/lib/sessions/workspace.js

@@ -544,16 +544,6 @@ var ArchiveWorkspaceRegistry = class {
         }
         return { attached, attachSkipped };
     }
-    /**
-     * 归档委托宿主。官方 UI 不经过本方法，而由 domain/changed 事件
-     * 同步归档时刻；重复归档不重置保留期。
-     */
-    async archiveSession(sessionId) {
-        // 委托宿主原生入口；宿主没有原生入口时走本门面的适配路径（能力探测决定）。
-        this.bridge.checkWorkspace("archive");
-        await this.registry.archiveSession(sessionId);
-        await this.reconcileArchiveLedger();
-    }
     /**
      * 列出已归档会话的展示元数据：sessionId / createdAt / cwd / title / archivedAt。
      * title 经投影缓存 best-effort 读取（cachedSnapshot 的标题行，旧格式记录退

package/lib/skills/catalog.js

@@ -93,17 +93,22 @@ export function renderSkillCatalog(data, maxEntries = SKILL_CATALOG_MAX_ENTRIES,
 export function createSkillCatalog(deps, opts = {}) {
     const ttlMs = opts.ttlMs ?? 30_000;
     const now = opts.now ?? (() => Date.now());
-    let value = '';
+    // 缓存的是**清单数据**而不是渲染结果：清单本体只依赖磁盘（一次读盘），而尾句要不要点名那个
+    // 查询工具取决于**这个 agent 手里有没有它**。渲染是纯字符串操作，代价可忽略；这个布尔就
+    // 两档，于是"每个 step 同步渲染"退化成一次查表（与人设目录按深度缓存同一手法）。
+    let data = null;
     let loadedAt = Number.NEGATIVE_INFINITY;
     let inflight = null;
+    let rendered = null;
     const recompute = async () => {
         try {
             const result = await deps.state();
             if (result && result.ok !== false) {
-                value = renderSkillCatalog(result.data ?? result, opts.maxEntries, opts.maxDescription, deps.listToolVisible ? deps.listToolVisible() : true);
+                data = result.data ?? result;
+                rendered = null;
             }
         }
-        catch { /* 保留上一次的值；首次失败则维持 '' */ }
+        catch { /* 保留上一次的值；首次失败则维持 null */ }
         loadedAt = now();
     };
     const revalidate = () => {
@@ -113,10 +118,17 @@ export function createSkillCatalog(deps, opts = {}) {
         return inflight;
     };
     return {
-        text: () => {
+        text: (agent) => {
             if (now() - loadedAt > ttlMs)
                 void revalidate();
-            return value;
+            if (data === null)
+                return '';
+            const visible = deps.listToolVisible ? deps.listToolVisible(agent) : true;
+            if (rendered && rendered.visible === visible)
+                return rendered.text;
+            const out = renderSkillCatalog(data, opts.maxEntries, opts.maxDescription, visible);
+            rendered = { visible, text: out };
+            return out;
         },
         refresh: () => {
             loadedAt = Number.NEGATIVE_INFINITY;

package/lib/skills/core.js

@@ -17,6 +17,9 @@ import { promises as fs, } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { discoverReadonlyEntries, validDiscoveryName, } from "./readonly-discovery.js";
 import { isSameOrDescendant } from "../paths.js";
+// 回收站条目 id（与 hub / 记忆 / 人设 / 场景 / 提示词共用一个生成器）。不能引 `../hub.js` ——
+// 那边引了本文件的 resolveDshHome，引回去就是环；所以生成器放在 `../trash-id.js` 这一叶上。
+import { newTrashId } from "../trash-id.js";
 import { OFFICE_SKILL_NAMES, OFFICIAL_SOURCE_KEY, officialOfficeRuntimeSection, } from "./official.js";
 import { parseSkillDoc, toKebab, unquote } from "./frontmatter.js";
 // 拆出去的公开函数照旧挂在 core.js 上（tools/skills.ts 引 toKebab，memories/* 与 ops/memory.ts
@@ -49,7 +52,7 @@ import { checkedWritableRootDefinition, movePathWithFallback, safeExistingEntryP
 // ./core.js 引），照旧再出口一次。
 export { customRootsFromState, effectiveSkillPolicy, entryOf, groupLoadableSkillsByName, parseBoolValue, readManagerState, scanEntries, state, writeManagerState, } from "./manager-state.js";
 import { CUSTOM_ROOT_KEY_RE, PROJECT_ROOT_KEY_RE, customRootsFromState, effectiveSkillPolicy, entryOf, groupLoadableSkillsByName, isInsideResolvedRoot, readManagerState, scanDeduplicatedRoots, writeFileAtomically, writeManagerState, } from "./manager-state.js";
-import { KEBAB_RE, pathsOverlap, } from "./upload-pipeline.js";
+import { KEBAB_RE, normalizeUploadPath, pathsOverlap, uploadError, writeUploadedEntries, } from "./upload-pipeline.js";
 import { customRootKey, dshRootPath, isDefaultSkillSource, managerHomePath, managerStatePath, projectIdentity, projectRoots, projectSourceSafe, readonlyError, resolvedPath, rootByKey, rootDefinition, trashRootPath, userRoots, } from "./skill-roots.js";
 import { codedError, entryPath, lstatOrNull, renameWithRetry, pathIdentity, temporaryPath, TRANSIENT_RENAME_CODES, } from "./core-util.js";
 const USER_DSH_POLICY_RANK = 399;
@@ -124,7 +127,15 @@ export async function addCustomRoot(inputPath, label, log) {
     if (current.writable === false)
         return invalidManagerStateWrite();
     const existing = customRootsFromState(current.state);
+    // 「永久删除」过的来源不再参与重叠判定：用户在回收站里把它彻底删掉之后，要能把同一个
+    // 目录**作为自定义来源重新加回来**（`confirm.source.forget.desc` 那句「需要时只能重新
+    // 添加这个目录」说的就是这条路）。不放过它的话，那句提示就是一句空话 —— 路径仍被
+    // `userRoots()` 认领，添加只会吃一个「目录与已有技能来源重叠」。
+    const forgotten = new Set(Array.isArray(current.state.forgottenSources)
+        ? current.state.forgottenSources
+        : []);
     for (const known of userRoots()
+        .filter((root) => !forgotten.has(root.key))
         .map((root) => root.path)
         .concat(existing.map((root) => root.path))) {
         if (await pathsOverlap(canonical, known))
@@ -189,6 +200,59 @@ export async function removeCustomRoot(key, log) {
         log("custom-remove", `移除自定义技能目录 ${target.path} (${clean})`);
     return { key: clean, path: target.path };
 }
+/**
+ * 永久删除一条**按约定发现**的来源记录（回收站 → 目录 里那颗「永久删除」）。
+ *
+ * 与 `removeCustomRoot` 的分工：那条管的是"用户手加的自定义目录"，删掉 `customRoots` 里
+ * 的记录就完事；这条管的是 `agents` / `codex` / `claude` 这类**由 `userRoots()` 按约定推导**
+ * 出来的来源 —— 它们不在状态文件的 customRoots 里，路径每次启动都会重新算出来，所以只把 key
+ * 从 `removedSources` 里摘掉的话，下一轮它又原样回来了。
+ *
+ * 于是另记一份 `forgottenSources`：进了这份名单的来源既不读取（`activeUserRoots` 摘掉它）、
+ * 也不列出（`state()` 的 roots 过滤掉它）—— 等于从插件里彻底消失。用户想反悔有两条路：
+ * 清掉状态文件里这个 key，或者把它**作为自定义来源重新添加**（`addCustomRoot` 的重叠判定
+ * 已经跳过已忘记的来源，所以那条路真的走得通）。
+ *
+ * **磁盘上的源文件一个字节都不动** —— 这条函数自始至终只写状态文件。
+ */
+export async function forgetSource(key, log) {
+    const clean = String(key == null ? "" : key).trim();
+    const root = userRoots().find((item) => item.key === clean);
+    if (!root)
+        return {
+            ok: false,
+            error: `未知的来源: ${clean}`,
+            code: "error.root.unknown",
+            params: { root: clean },
+        };
+    // 默认来源（dsh / hub / 官方）必须读取：它们不在移除候选里，也不该能被永久删除。
+    if (isDefaultSkillSource(clean))
+        return {
+            ok: false,
+            error: `默认来源不能永久删除: ${clean}`,
+            code: "error.root.default",
+            params: { root: clean },
+        };
+    const current = await readManagerState();
+    if (current.writable === false)
+        return invalidManagerStateWrite();
+    const forgotten = new Set(Array.isArray(current.state.forgottenSources)
+        ? current.state.forgottenSources
+        : []);
+    forgotten.add(clean);
+    current.state.forgottenSources = [...forgotten].sort();
+    // 「已移除」那条记录一起摘掉：留着它只会在状态文件里多一条指向"已经不存在"的脏键，
+    // 而且归一化那一步本来也会把它去掉 —— 没理由写进去（与 removeCustomRoot 同一口径）。
+    if (Array.isArray(current.state.removedSources))
+        current.state.removedSources = current.state.removedSources.filter((item) => item !== clean);
+    delete current.state.sources[clean];
+    delete current.state.disabledSkills[clean];
+    delete current.state.enabledSkills[clean];
+    await writeManagerState(current.state);
+    if (log)
+        log("source-forget", `永久删除来源记录 ${clean}: ${root.path}`);
+    return { root: clean, path: root.path };
+}
 /**
  * 从活动 Session cwd 推导项目技能根。只接受宿主上可解析的绝对目录，
  * 同一项目的多个 Session 会折叠到同一组稳定 key，避免跨 workspace 合并同名技能。
@@ -434,17 +498,22 @@ async function visibleEntryForRoot(root, name) {
  */
 /** 状态文件已存在但不可用时一律关闭外部来源，避免损坏配置重新暴露技能。 */
 /**
- * 参与扫描的来源 = 全部来源 − 用户已移除的。
+ * 参与扫描的来源 = 全部来源 − 用户已移除的 − 用户已永久删除的。
  *
  * 「移除来源」与「停用来源」是两件事：
  *   - 停用（`sources[key] = false`）：仍然读取并列出技能，只是不可调用；
  *   - 移除（出现在 `removedSources`）：**连目录都不读**，技能不出现在列表里，
  *     也不参与 provider 候选。源文件不动，清掉这个标记即恢复。
+ *
+ * 「永久删除」（`forgottenSources`）是移除的**终点**：这条来源从插件里彻底消失 ——
+ * 不再读取（与移除同）、并且连"已移除"那行记录也不再出现（见 `state()` 的 roots 过滤）。
+ * 两者都**不碰磁盘**。
  */
 export function activeUserRoots(stateValue) {
     const state = stateValue;
     const removed = new Set(state && Array.isArray(state.removedSources) ? state.removedSources : []);
-    return userRoots().filter((root) => !removed.has(root.key));
+    const forgotten = new Set(state && Array.isArray(state.forgottenSources) ? state.forgottenSources : []);
+    return userRoots().filter((root) => !removed.has(root.key) && !forgotten.has(root.key));
 }
 /** 裁剪自定义来源列表：非法条目丢弃，key/path 绑定校验，label 规整。 */
 /**
@@ -647,6 +716,24 @@ export async function markSkillsDisabled(entries, log) {
         return invalidManagerStateWrite();
     let dirty = false;
     for (const e of clean) {
+        /*
+         * 同一张表里的两个名单**互斥**（`disabledSkills` = 显式关、`enabledSkills` = 显式开，
+         * 见 manager-state 的 validManagerStateDocument）。名字进了 disabled 就必须从 enabled 摘掉。
+         *
+         * 少了这一步，「显式启用过 → 删除 → 从回收站恢复」这条链会把同一个名字同时留在两份名单
+         * 上（删除不清策略、恢复又要默认停用），整份状态随即被判非法 —— 插件 fail-closed 停用
+         * **所有**技能，而且 `writable` 一并变 false，用户在界面上连一个开关都按不动，等于被锁死在
+         * 一份自己造不出来的状态上（用户 2026-10-14 实测踩到）。
+         *
+         * 摘除要放在下面那个 `continue` **之前**：名字已经在 disabled 里、却还挂在 enabled 上
+         * （就是被锁死的那份文件的形状）时，`continue` 会把清理一并跳过去。
+         */
+        const explicit = current.state.enabledSkills[e.root] || [];
+        const keptExplicit = explicit.filter((name) => name !== e.name);
+        if (keptExplicit.length !== explicit.length) {
+            current.state.enabledSkills[e.root] = keptExplicit;
+            dirty = true;
+        }
         const prev = current.state.disabledSkills[e.root] || [];
         if (prev.indexOf(e.name) >= 0)
             continue;
@@ -807,7 +894,11 @@ export async function deleteSkill(root, name, log, options = {}) {
             params: { name },
         };
     const targets = await safeExistingEntryPaths(definition.path, name);
-    const id = `${Date.now()}-${randomUUID()}`;
+    // 回收站条目 id 走五个域共用的那个生成器（2026-10-15 smoke-test P1-7）：此前这里另写了一套
+    // `${Date.now()}-${randomUUID()}`，于是同一次操作里记忆/人设/场景/提示词拿到 `mv8faxqe-…`
+    // 这种形状、技能拿到 `1792001296466-62d3d393-…`。模型按 `action=list` 的 id 跨域 restore，
+    // 两种长相只会让它多猜一层。读侧只校验单个合法路径段，旧条目照旧能列、能恢复。
+    const id = newTrashId();
     const trashRoot = trashRootPath();
     const stage = join(trashRoot, `.stage-${randomUUID()}`);
     const finalPath = join(trashRoot, id);
@@ -906,11 +997,12 @@ function yamlString(value) {
     return JSON.stringify(String(value));
 }
 export async function createSkill(input, log, options = {}) {
-    // v0.4：默认落点由「DSH 技能目录」改为 hub 内的 `tool-management/skills/`；
-    // 调用方显式传 options.root（如项目根）时仍以调用方为准。
+    // 默认落点是「DSH 技能目录」（用户裁定 2026-10-15 改回）：v0.4-v0.20.0 期间这里是 hub。
+    // hub（`tool-management/skills/`）现在只服务「导入技能」功能 —— 那边走
+    // `skillCreateRootPath()`，不经这里。调用方显式传 options.root（如项目根）时仍以调用方为准。
     const requestedRoot = Object.prototype.hasOwnProperty.call(options, "root")
         ? options.root
-        : rootByKey("hub") || rootByKey("dsh");
+        : rootByKey("dsh") || rootByKey("hub");
     const definition = await checkedWritableRootDefinition(requestedRoot);
     if (definition && definition.ok === false)
         return definition;
@@ -954,6 +1046,31 @@ export async function createSkill(input, log, options = {}) {
         };
     if (description.length > 500 || body.length > 1 << 18)
         return { ok: false, error: "技能内容过长", code: "error.create.tooLarge" };
+    // 附件的闸一律复用导入那条链（normalizeUploadPath + writeUploadedEntries 里的 32 MiB /
+    // 64 MiB / 1000 条），不另立规矩：界面上新建的技能与导入的技能带同一份 `references/`
+    // 时，落盘形态必须一致。SKILL.md 是本次要写的正文，不能被附件占用。
+    const files = Array.isArray(input && input.files) ? input.files : [];
+    try {
+        for (const item of files) {
+            const rel = normalizeUploadPath(item?.path).path;
+            if (/(^|\/)skill\.md$/i.test(rel))
+                return {
+                    ok: false,
+                    error: `附件不能占用 SKILL.md（正文由本次创建写入）: ${rel}`,
+                    code: "error.create.reservedPath",
+                    params: { path: rel },
+                };
+        }
+    }
+    catch (error) {
+        return uploadError(error);
+    }
+    if (files.length && form === "flat")
+        return {
+            ok: false,
+            error: "单文件技能不能带附件：附件需要目录形态",
+            code: "error.create.filesWithFlat",
+        };
     if (await safeExistingEntryPaths(root, name).then((items) => items.length > 0))
         return {
             ok: false,
@@ -977,10 +1094,18 @@ export async function createSkill(input, log, options = {}) {
     try {
         await fs.mkdir(stage);
         await fs.writeFile(join(stage, "SKILL.md"), content, "utf8");
+        // 附件写进**同一个临时目录**再整体改名到位：中途失败时目标路径根本不存在，
+        // 不会留下「有 SKILL.md 没有 references」的半截技能（下方 catch 顺手把 stage 清掉）。
+        if (files.length)
+            await writeUploadedEntries(stage, files);
         await renameWithRetry(stage, target);
     }
     catch (error) {
         await fs.rm(stage, { recursive: true, force: true }).catch(() => undefined);
+        // 带附件时把失败收拢成结果对象：路径非法 / 超限这些都是用户输入问题，抛出去只会
+        // 让界面拿到一句英文堆栈。不带附件时照旧抛（与改动前一字不差）。
+        if (files.length)
+            return uploadError(error);
         throw error;
     }
     if (log)
@@ -1080,6 +1205,59 @@ export async function updateSkill(input, log, options = {}) {
         log("update", `更新 ${existingDoc}`);
     return { name, path: existingDoc, root: definition.key };
 }
+/** 详情弹窗列出的 bundle 附件上限：再多就不是给人看的清单了（2026-10-16）。 */
+const MAX_DETAIL_ATTACHMENTS = 200;
+const MAX_DETAIL_ATTACHMENT_DEPTH = 6;
+/**
+ * 列出 bundle 目录里除顶层 `SKILL.md` 之外的普通文件（相对路径 + 字节数）。
+ *
+ * 走 lstat 并跳过符号链：这份清单会原样列进详情弹窗、也会打印给模型看，
+ * 里面混一条指向目录树之外的链就是误导。深度与条数都有上限，超了如实标 truncated。
+ */
+async function listBundleAttachments(dir) {
+    const files = [];
+    let truncated = false;
+    async function walk(base, prefix, depth) {
+        let items;
+        try {
+            items = await fs.readdir(base, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const item of items) {
+            const rel = prefix ? `${prefix}/${item.name}` : item.name;
+            if (depth === 0 && item.name.toLowerCase() === "skill.md")
+                continue;
+            const abs = join(base, item.name);
+            let stat;
+            try {
+                stat = await fs.lstat(abs);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isSymbolicLink())
+                continue;
+            if (stat.isDirectory()) {
+                if (depth + 1 >= MAX_DETAIL_ATTACHMENT_DEPTH)
+                    continue;
+                await walk(abs, rel, depth + 1);
+                continue;
+            }
+            if (!stat.isFile())
+                continue;
+            if (files.length >= MAX_DETAIL_ATTACHMENTS) {
+                truncated = true;
+                return;
+            }
+            files.push({ path: rel, size: stat.size });
+        }
+    }
+    await walk(dir, "", 0);
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return { files, truncated };
+}
 export async function skillDetail(keyOrRoot, name, options = {}) {
     const scopedRoots = await projectRoots(options.projectCwds);
     // 支持传 key 或 definition（自定义来源由 service 层解析后传入）。
@@ -1117,6 +1295,8 @@ export async function skillDetail(keyOrRoot, name, options = {}) {
     }
     const doc = parseSkillDoc(raw);
     const summary = entryOf(name, entry.kind, entry.docPath, doc);
+    // bundle 才有附件；flat 是单文件，给 null 让调用方分清"没有目录"与"目录是空的"。
+    const attachments = entry.kind === "bundle" ? await listBundleAttachments(dirname(entry.docPath)) : null;
     return {
         root: root.key,
         name,
@@ -1131,6 +1311,8 @@ export async function skillDetail(keyOrRoot, name, options = {}) {
         diagnostics: summary.diagnostics,
         loadable: summary.loadable,
         sourceReadOnly: !root.mutable,
+        attachments: attachments ? attachments.files : null,
+        attachmentsTruncated: attachments ? attachments.truncated : false,
     };
 }
 /**

package/lib/skills/frontmatter.js

@@ -94,3 +94,34 @@ export function unquote(v) {
     }
     return s;
 }
+// ── 声明名改写（退号落盘后同步 frontmatter）─────────────────────────────────
+/** frontmatter 整块（开栏 / 字段区 / 闭栏三段各自成组，便于逐字回拼）。 */
+const DECLARED_NAME_BLOCK_RE = /^(?<open>(?:\uFEFF)?[^\S\r\n]*---[^\S\r\n]*(?:\r\n|\n))(?<fields>[\s\S]*?)(?<close>^[^\S\r\n]*---[^\S\r\n]*(?:\r\n|\n|$))/m;
+/** 顶格的 `name:` 行；缩进的嵌套字段（块标量的续行等）不匹配。 */
+const DECLARED_NAME_LINE_RE = /^name[^\S\r\n]*:[^\r\n]*/m;
+/**
+ * 把 frontmatter 的 `name:` 行改写成新名字，其余逐字节保留（连 CRLF 都不动）；
+ * 认不出形态（没有 frontmatter / 没有 `name:` 行 / 改完不变）时返回 null。
+ *
+ * **调用方保证 `name` 过 KEBAB_RE**（只含 `[a-z0-9-]`，无需转义；本模块不引
+ * upload-pipeline 的 KEBAB_RE —— 那边引了本模块，引回来就成了环）。
+ *
+ * 退号落盘后必须调用（导入撞名、回收站恢复）：`canonicalSkillName` 取的是
+ * 声明名而不是条目名，只改目录会"看着叫 foo-1、其实还是 foo"—— 两份同名
+ * 技能在「同名首选」里被并成一组，而那颗开关挑的是来源，按下去什么都不会变。
+ * 没有 `name:` 行的文档返回 null 是**良性**的：声明名为空时 canonicalSkillName
+ * 回落到条目名，退号后的目录名就是它的名字。
+ */
+export function rewriteDeclaredName(text, name) {
+    const match = DECLARED_NAME_BLOCK_RE.exec(text);
+    if (!match || !match.groups)
+        return null;
+    const fields = match.groups.fields;
+    // 函数式替换：字段区里可能带 `$&` / `$'` 之类字面量，字符串式替换会把它们当占位符展开。
+    const rewritten = fields.replace(DECLARED_NAME_LINE_RE, () => `name: ${name}`);
+    if (rewritten === fields)
+        return null;
+    const open = match.groups.open;
+    const close = match.groups.close;
+    return text.replace(DECLARED_NAME_BLOCK_RE, () => `${open}${rewritten}${close}`);
+}