dsh-skill-hub 0.3.20 → 0.3.21

package/lib/types/skillfs/scan.d.ts

@@ -46,3 +46,29 @@ export declare function findProjectRoot(cwd: string): Promise<string>;
  * a defect.
  */
 export declare function scanDiagnostics(root: WritableRoot, home?: string): Promise<DiagnosticEntry[]>;
+/**
+ * 某个名字在一个 root 下现存的禁用发现文件（两种形态都认），没有则 undefined。
+ * 目录包形态优先（`<name>/SKILL.md.disabled`），其次扁平 `<name>.md.disabled`。
+ * 单点定义「禁用态在磁盘上长什么样」，避免各处再拼一次路径（issue #16 类）。
+ */
+export declare function disabledOccupancyIn(base: string, name: string): Promise<string | undefined>;
+/**
+ * 一个名字在某个 root 下的全部磁盘占位。技能名是系统里唯一的身份，但同一个名字
+ * 可以被两种形态（目录包 `<name>/SKILL.md` / 扁平 `<name>.md`）× 两种状态
+ * （启用 / `.disabled` 改名）占据，而且两种形态可以**同时存在** —— 注册表只会
+ * 给出其中一个，另一个静默不可达。所有按名字操作文件的路径都应该从这里取值，
+ * 而不是各自拼一次路径（issue #16 类的根因）。
+ *
+ * 两个数组都按「目录包优先」排序：目录包是 hub 自己写入的形态（导入、创建、
+ * 同步都建目录包），冲突时它是更「权威」的那份。
+ */
+export interface NameOccupancy {
+    /** 启用态发现文件（目录包 `<name>/SKILL.md` 在前，扁平 `<name>.md` 在后）。 */
+    enabled: string[];
+    /** 禁用态发现文件（`<name>/SKILL.md.disabled` 在前，`<name>.md.disabled` 在后）。 */
+    disabled: string[];
+    /** `<name>/` 存在，但既没有 `SKILL.md` 也没有 `SKILL.md.disabled`（空壳/残留目录）。 */
+    bareDir?: string;
+}
+/** 读一个名字在某个 skills root 下的全部占位。只读，不修改磁盘。 */
+export declare function occupancyOf(base: string, name: string): Promise<NameOccupancy>;

package/lib/types/skillfs.d.ts

@@ -45,11 +45,19 @@ export declare function moveIntoTrash(source: string): Promise<{
     path: string;
     source: string;
 }>;
+/**
+ * The filesystem entry behind a discovery file: a directory bundle is addressed
+ * by its `SKILL.md` (or `SKILL.md.disabled`) and moved as a whole directory, a
+ * flat `<name>.md` file is moved as itself. Single definition of that mapping —
+ * delete, restore, sync-replace and placeholder retirement must all agree on it,
+ * or one of them moves a bundle's discovery file and leaves an empty directory.
+ */
+export declare function trashSourceOf(discoveryPath: string): string;
 /**
  * Move a skill (directory bundle or flat .md file) into the root's trash.
  * The skill stays recoverable: the source is renamed into
  * <root>/.trash/<name>-<timestamp>. A directory bundle is addressed by its
- * SKILL.md path and moved as a whole directory.
+ * SKILL.md (or SKILL.md.disabled) path and moved as a whole directory.
  * @returns the trashed path plus the original path that was moved.
  */
 export declare function trashSkill(sourcePath: string): Promise<{

package/lib/types/store/migrate.d.ts

@@ -31,7 +31,7 @@ export interface HydratedState {
     tagsById: Map<string, SkillTag>;
     sourcesByRepo: Map<string, SourceRecord>;
     marketSources: MarketSourceRecord[];
-    trashByName: Map<string, TrashEntry>;
+    trashByPath: Map<string, TrashEntry>;
     skillStats: SkillStatsCheckpoint | undefined;
     marketStats: MarketStatsSnapshot | undefined;
     collectionOrder: string[];

package/lib/types/store/store.d.ts

@@ -7,7 +7,7 @@ export declare class SkillHubStore {
     private tagsById;
     private sourcesByRepo;
     private marketSources;
-    private trashByName;
+    private trashByPath;
     private skillStats;
     private marketStats;
     private collectionOrder;
@@ -119,12 +119,17 @@ export declare class SkillHubStore {
     setMarketSourceCommit(repo: string, commitSha: string): Promise<void>;
     /** All trashed skills, newest first. */
     listTrash(): Promise<TrashEntry[]>;
-    /** One trash entry by skill name (undefined when absent). */
+    /** One trash entry by skill name — the newest when a name has several. */
     getTrash(name: string): Promise<TrashEntry | undefined>;
-    /** Record a trashed skill. */
+    /**
+     * Record a trashed skill, keyed by its trashed path. Keying by name used to
+     * silently drop the previous record when the same name landed in the trash
+     * twice (a re-delete, or the two on-disk discovery forms), orphaning its
+     * directory with nothing left pointing at it.
+     */
     addTrash(entry: TrashEntry): Promise<void>;
-    /** Remove a trash record (after restore). */
-    removeTrash(name: string): Promise<void>;
+    /** Remove a trash record by its trashed path (after restore or permanent clear). */
+    removeTrash(path: string): Promise<void>;
     /** The persisted usage-statistics checkpoint (undefined until first saved). */
     getSkillStatsState(): Promise<SkillStatsCheckpoint | undefined>;
     /** Persist a usage-statistics checkpoint (after every completed scan; cadence follows the scan TTL). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-skill-hub",
-  "version": "0.3.20",
+  "version": "0.3.21",
   "description": "In-GUI skill hub for DeepSeek Harness (dsh): browse the full local skill catalog from the official ctx.skills registry (every root + third-party providers), toggle skills on/off, inspect bodies, surface frontmatter diagnostics, and scaffold new skills — plus a codex-style skill market (built-in catalog, upstream update checks, one-click update-all) with tracked source sync. The full manager beyond the read-only dsh-skill-manager browser.",
   "type": "module",
   "engines": {

package/src/index.ts

@@ -24,7 +24,7 @@ import { SkillHubProvider } from './provider.ts'
 import { makeRoutes } from './routes.ts'
 import { createSkillStatsReader, asPersistenceSeam, type SessionPersistenceLike, type SessionQueryLike, type SkillStatsReader } from './stats.ts'
 import { SkillHubStore } from './store.ts'
-import { reconcileDisabledSkills } from './reconcile.ts'
+import { reconcileDisabledSkills, pruneStaleDisabledSkills } from './reconcile.ts'
 import { cleanupLeftoverImportDirs, setGithubToken } from './repo.ts'
 import { dshHome } from './store.ts'
 import { join } from 'node:path'
@@ -307,6 +307,16 @@ export function apply(ctx: Context, config?: Config): void {
     } catch (error) {
       ctx.logger.warn('[dsh-skill-hub] startup disabled-skill reconcile failed', error)
     }
+    // 反向对账：记录还在、文件已不在 → 修路径或删记录。不做这一步，那条记录会
+    // 把名字永久锁死（启用/新建/删除三条路都失败）。
+    try {
+      const pruned = await pruneStaleDisabledSkills(store, home)
+      if (pruned.repaired.length > 0 || pruned.removed.length > 0) {
+        ctx.logger.info(`[dsh-skill-hub] startup pruned disabled records: repaired ${pruned.repaired.length} (${pruned.repaired.map((entry) => entry.name).join(', ') || '-'}), removed ${pruned.removed.length} (${pruned.removed.join(', ') || '-'})`)
+      }
+    } catch (error) {
+      ctx.logger.warn('[dsh-skill-hub] startup disabled-record prune failed', error)
+    }
   })()
 
   void (async () => {

package/src/protocol/sources.ts

@@ -138,6 +138,11 @@ export interface SourceTrashClearResponse {
   deleted: string[]
   /** 未能删除的技能（保留在回收站中）。 */
   failed: Array<{ name: string; error: string }>
+  /**
+   * `.trash` 里没有对应记录的残留目录（同名技能先后两次入站时，旧记录被覆盖，
+   * 目录却留了下来）。清空回收站时一并回收，这里上报它们的路径；没有则省略。
+   */
+  orphans?: string[]
 }
 
 /** 项目级技能来源（它们有 workspace 归属，不属于「个人」组）。 */

package/src/reconcile.test.ts

@@ -2,7 +2,7 @@ import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { reconcileDisabledSkills } from './reconcile.ts'
+import { pruneStaleDisabledSkills, reconcileDisabledSkills } from './reconcile.ts'
 import { SkillHubStore, statePath } from './store.ts'
 
 describe('reconcileDisabledSkills', () => {
@@ -73,4 +73,77 @@ describe('reconcileDisabledSkills', () => {
     expect(await reconcileDisabledSkills(store, home)).toEqual([])
     expect(await store.listDisabled()).toHaveLength(1)
   })
+
+  it('reconciles a root-level SKILL.md.disabled (a flat skill literally named SKILL)', async () => {
+    // scanRoot 会把根级 SKILL.md 文件当一个扁平技能，它的禁用对应物就不能被漏掉。
+    await writeFile(join(home, 'skills', 'SKILL.md.disabled'), '---\nname: root-flat\ndescription: Root flat\n---', 'utf8')
+    const added = await reconcileDisabledSkills(store, home)
+    expect(added.map((entry) => entry.name)).toEqual(['root-flat'])
+    expect((await store.getDisabled('root-flat'))?.path).toBe(join(home, 'skills', 'SKILL.md.disabled'))
+  })
+})
+
+describe('pruneStaleDisabledSkills', () => {
+  let dir: string
+  let home: string
+  let agentsHome: string
+  let previousAgentsHome: string | undefined
+  let store: SkillHubStore
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'dsh-skill-hub-prune-'))
+    home = join(dir, 'home')
+    agentsHome = join(dir, 'agents')
+    await mkdir(join(home, 'skills'), { recursive: true })
+    await mkdir(join(agentsHome, 'skills'), { recursive: true })
+    previousAgentsHome = process.env.DSH_AGENTS_HOME
+    process.env.DSH_AGENTS_HOME = agentsHome
+    store = new SkillHubStore(statePath(home))
+  })
+
+  afterEach(async () => {
+    if (previousAgentsHome === undefined) delete process.env.DSH_AGENTS_HOME
+    else process.env.DSH_AGENTS_HOME = previousAgentsHome
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('drops a record whose file is gone and frees the name', async () => {
+    await store.addDisabled({ name: 'ghost', description: 'x', path: join(home, 'skills', 'ghost', 'SKILL.md.disabled'), root: 'user-dsh', disabledAt: 1 })
+    const result = await pruneStaleDisabledSkills(store, home)
+    expect(result).toEqual({ repaired: [], removed: ['ghost'] })
+    expect(await store.listDisabled()).toEqual([])
+  })
+
+  it('repoints a record to the surviving flat placeholder instead of dropping it', async () => {
+    // 记录指目录形态，磁盘上只剩扁平形态（导入让位过一次的典型残留）。
+    await writeFile(join(home, 'skills', 'code-review.md.disabled'), '---\nname: code-review\ndescription: stub\n---', 'utf8')
+    await store.addDisabled({ name: 'code-review', description: 'stub', path: join(home, 'skills', 'code-review', 'SKILL.md.disabled'), root: 'user-dsh', disabledAt: 1 })
+    const result = await pruneStaleDisabledSkills(store, home)
+    expect(result.removed).toEqual([])
+    expect(result.repaired.map((entry) => entry.path)).toEqual([join(home, 'skills', 'code-review.md.disabled')])
+    expect((await store.getDisabled('code-review'))?.path).toBe(join(home, 'skills', 'code-review.md.disabled'))
+  })
+
+  it('repoints to the bundle placeholder when that is the surviving form', async () => {
+    await mkdir(join(home, 'skills', 'paused'))
+    await writeFile(join(home, 'skills', 'paused', 'SKILL.md.disabled'), '---\nname: paused\ndescription: b\n---', 'utf8')
+    await store.addDisabled({ name: 'paused', description: 'b', path: join(home, 'skills', 'paused.md.disabled'), root: 'user-dsh', disabledAt: 1 })
+    const result = await pruneStaleDisabledSkills(store, home)
+    expect(result.repaired.map((entry) => entry.path)).toEqual([join(home, 'skills', 'paused', 'SKILL.md.disabled')])
+  })
+
+  it('leaves records whose file still exists alone, and is idempotent', async () => {
+    await writeFile(join(home, 'skills', 'alive.md.disabled'), '---\nname: alive\ndescription: x\n---', 'utf8')
+    await store.addDisabled({ name: 'alive', description: 'x', path: join(home, 'skills', 'alive.md.disabled'), root: 'user-dsh', disabledAt: 1 })
+    expect(await pruneStaleDisabledSkills(store, home)).toEqual({ repaired: [], removed: [] })
+    expect(await pruneStaleDisabledSkills(store, home)).toEqual({ repaired: [], removed: [] })
+    expect(await store.listDisabled()).toHaveLength(1)
+  })
+
+  it('prunes records from the other writable root too', async () => {
+    await store.addDisabled({ name: 'agent-ghost', description: 'x', path: join(agentsHome, 'skills', 'agent-ghost', 'SKILL.md.disabled'), root: 'user-agents', disabledAt: 1 })
+    await writeFile(join(agentsHome, 'skills', 'agent-ghost.md.disabled'), '---\nname: agent-ghost\ndescription: x\n---', 'utf8')
+    const result = await pruneStaleDisabledSkills(store, home)
+    expect(result.repaired.map((entry) => entry.path)).toEqual([join(agentsHome, 'skills', 'agent-ghost.md.disabled')])
+  })
 })

package/src/reconcile.ts

@@ -12,7 +12,7 @@
 
 import { readFile, stat } from 'node:fs/promises'
 import type { DisabledSkill } from './protocol.ts'
-import { parseFrontmatter, rootPath, scanDisabledRoot, WRITABLE_ROOTS } from './skillfs.ts'
+import { disabledOccupancyIn, parseFrontmatter, rootPath, scanDisabledRoot, WRITABLE_ROOTS } from './skillfs.ts'
 import { dshHome } from './store.ts'
 
 /** Narrow store view used by the reconcile (SkillHubStore satisfies it). */
@@ -21,6 +21,11 @@ export interface DisabledReconcileStore {
   addDisabled(entry: DisabledSkill): Promise<void>
 }
 
+/** Narrow store view used by the reverse reconcile (adds record removal). */
+export interface DisabledPruneStore extends DisabledReconcileStore {
+  removeDisabled(name: string): Promise<void>
+}
+
 /**
  * Add sidecar disabled records for every `.disabled` discovery file that has
  * none yet. Existing records (matched by path or by name) win, so this never
@@ -60,3 +65,47 @@ export async function reconcileDisabledSkills(store: DisabledReconcileStore, hom
   }
   return added
 }
+
+/** 反向对账的结果：修好路径的记录 + 被清掉的死记录。 */
+export interface DisabledPruneResult {
+  /** 记录还在、但 path 指向的文件已不在：已改指向现存的 `.disabled` 文件。 */
+  repaired: DisabledSkill[]
+  /** 文件与禁用占位都已不存在：记录已删除，名字被释放。 */
+  removed: string[]
+}
+
+/**
+ * 反向对账：`reconcileDisabledSkills` 只处理「磁盘有 `.disabled`、sidecar 没记录」。
+ * 反方向（sidecar 有记录、磁盘上那个文件已经不在了）以前永不清理，于是留下一条
+ * 干掉不掉的记录：`/toggle` 启用会 rename 失败，`/create` 被 409 挡住，`/skill/delete`
+ * 也 rename 失败 —— 名字被永久锁死（issue #16 类，实测 G5）。
+ *
+ * 两种处理，都不动启用态技能：
+ * - 名字在该 root 下仍有 `.disabled` 占位（目录包或扁平形态）→ 把记录指向真实文件；
+ * - 一个都没有 → 删记录，把名字还给用户。
+ *
+ * 只处理合法可写 root 的记录；root 值异常（历史损坏数据）时原样保留，不擅自删。
+ */
+export async function pruneStaleDisabledSkills(store: DisabledPruneStore, home = dshHome()): Promise<DisabledPruneResult> {
+  const result: DisabledPruneResult = { repaired: [], removed: [] }
+  for (const record of await store.listDisabled()) {
+    let exists = false
+    try {
+      exists = (await stat(record.path)).isFile()
+    } catch {
+      exists = false
+    }
+    if (exists) continue
+    if (!WRITABLE_ROOTS.includes(record.root)) continue
+    const occupancy = await disabledOccupancyIn(rootPath(record.root, home), record.name)
+    if (occupancy === undefined) {
+      await store.removeDisabled(record.name)
+      result.removed.push(record.name)
+      continue
+    }
+    const repaired: DisabledSkill = { ...record, path: occupancy }
+    await store.addDisabled(repaired)
+    result.repaired.push(repaired)
+  }
+  return result
+}

package/src/routes/catalog.ts

@@ -4,7 +4,7 @@
  */
 
 import { readFile, stat } from 'node:fs/promises'
-import { dirname, join } from 'node:path'
+import { dirname } from 'node:path'
 import type { SkillDefinition } from '@deepseek-ai/dsh-skill'
 import { isSkillName } from '@deepseek-ai/dsh-skill'
 import {
@@ -18,7 +18,7 @@ import {
   type ToggleResponse,
   type WritableRoot,
 } from '../protocol.ts'
-import { createSkill, disableSkill, enableSkill, moveIntoTrash, parseFrontmatter, readSkillInterface, rootOfPath, rootPath, trashSkill } from '../skillfs.ts'
+import { createSkill, disableSkill, disabledOccupancyIn, enableSkill, occupancyOf, parseFrontmatter, readSkillInterface, rootOfPath, rootPath, trashSkill } from '../skillfs.ts'
 import { errorText } from '../error-text.ts'
 import {
   applyInterface,
@@ -146,18 +146,27 @@ export function catalogRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
         // 已禁用的技能不在 registry 中，resolve 会 404，这里单独处理：允许整组删除未开启的技能
         let trashResult: { path: string; source: string } | null = null
         if (!resolved.ok) {
-          const disabled = await deps.store.getDisabled(name)
-          if (disabled !== undefined) {
-            // sidecar 里的路径可能是外部写入/损坏的：移动前必须确认它落在
-            // 可写根内（正常路径由 disableSkill 保证，这里只拦异常数据）。
-            if (rootOfPath(disabled.path, homeOf(deps)) === undefined) {
-              writeError(res, 409, 'disabled skill path is outside the hub writable roots')
-              return
-            }
-            // 禁用态：SKILL.md.disabled 或 *.md.disabled，直接将其所在技能整体移入回收站
-            const isBundleDisabled = disabled.path.endsWith('SKILL.md.disabled')
-            trashResult = await moveIntoTrash(isBundleDisabled ? dirname(disabled.path) : disabled.path)
-          } else {
+        const disabled = await deps.store.getDisabled(name)
+        if (disabled !== undefined) {
+          // sidecar 里的路径可能是外部写入/损坏的：移动前必须确认它落在
+          // 可写根内（正常路径由 disableSkill 保证，这里只拦异常数据）。
+          if (rootOfPath(disabled.path, homeOf(deps)) === undefined) {
+            writeError(res, 409, 'disabled skill path is outside the hub writable roots')
+            return
+          }
+          // 记录还在、文件已经不在（手工删了 / 从备份恢复过 sidecar）：这条记录
+          // 只是残留，清掉即算删除完成，否则它会永久占住这个名字。
+          if (!await pathExists(disabled.path)) {
+            await deps.store.removeDisabled(name)
+            await deps.store.removeSkillFromTags(name)
+            deps.invalidate?.()
+            writeJson(res, 200, { ok: true, name, path: disabled.path } satisfies SkillDeleteResponse)
+            return
+          }
+          // 禁用态：SKILL.md.disabled 或 *.md.disabled，直接将其所在技能整体移入回收站
+          // （trashSkill 认两种发现文件名，目录包按整目录搬）。
+          trashResult = await trashSkill(disabled.path)
+        } else {
             writeError(res, resolved.status, resolved.error); return
           }
         }
@@ -196,13 +205,28 @@ export function catalogRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
         if (body.enabled === true) {
           const record = await deps.store.getDisabled(name)
           if (record === undefined) { writeError(res, 404, 'skill is not hub-disabled: ' + name); return }
+          // 记录里的路径可能已经失效（文件被手工删/搬走）。先在同 root 下找现存的
+          // 禁用占位：找得到就把记录指向它，找不到说明这条记录是残留 —— 清掉并把
+          // 名字还给用户，而不是让「启用」永远失败把名字锁死。
+          let disabledPath = record.path
+          if (!await pathExists(disabledPath)) {
+            // root 从记录路径反推，不直接信 sidecar 里的 root 字段（可能是损坏数据）。
+            const root = rootOfPath(disabledPath, homeOf(deps))
+            const occupancy = root === undefined ? undefined : await disabledOccupancyIn(rootPath(root, homeOf(deps)), name)
+            if (occupancy === undefined) {              await deps.store.removeDisabled(name)
+              deps.invalidate?.()
+              writeError(res, 409, 'disabled record was stale (its file no longer exists); the record has been removed — retry now')
+              return
+            }
+            disabledPath = occupancy
+          }
           try {
-            await enableSkill(record.path)
+            await enableSkill(disabledPath)
           } catch (error) {
             // The renamed file may have vanished (external cleanup); report
             // precisely instead of a generic 500, like toggle-batch does.
             if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-              writeError(res, 409, 'disabled skill file is missing on disk: ' + record.path)
+              writeError(res, 409, 'disabled skill file is missing on disk: ' + disabledPath)
               return
             }
             throw error
@@ -275,12 +299,16 @@ export function catalogRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
         const existing = await deps.skills.get(name)
         if (existing !== undefined) { writeError(res, 409, 'skill name already exists: ' + name); return }
         if (await deps.store.getDisabled(name) !== undefined) { writeError(res, 409, 'skill name is disabled: re-enable it from the disabled list first'); return }
-        // A directory may exist without producing a registry entry (invalid
-        // frontmatter — exactly what the diagnostics section reports).
-        // Refuse to overwrite it instead of silently truncating its SKILL.md.
-        const target = join(rootPath(root, homeOf(deps)), name)
-        if (await pathExists(target)) {
-          writeError(res, 409, 'skill directory already exists on disk: ' + name + ' (check the discovery diagnostics)')
+        // 建档前先看磁盘：三种占位都会让新目录与旧文件并存成同名两形态 ——
+        // 已启用的发现文件（frontmatter 坏了因此注册表看不见）、已禁用的占位
+        // （目录包或扁平）、以及没有 SKILL.md 的空壳目录（正是发现诊断在报的东西）。
+        const occupancy = await occupancyOf(rootPath(root, homeOf(deps)), name)
+        if (occupancy.enabled.length > 0) {
+          writeError(res, 409, 'a skill file already occupies this name on disk: ' + name + ' (check the discovery diagnostics)')
+          return
+        }
+        if (occupancy.disabled.length > 0 || occupancy.bareDir !== undefined) {
+          writeError(res, 409, 'name is occupied by a disabled placeholder or an empty directory on disk: ' + name + ' (check the discovery diagnostics)')
           return
         }
         const path = await createSkill(root, name, readString(body, 'description'), homeOf(deps))

package/src/routes/repo-import.ts

@@ -4,7 +4,6 @@
  */
 
 import { mkdir } from 'node:fs/promises'
-import { dirname, join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import {
   SKILL_HUB_API,
@@ -28,12 +27,11 @@ import {
   skillManifest,
   skillPathIn,
 } from '../repo.ts'
-import { moveIntoTrash, rootPath } from '../skillfs.ts'
+import { occupancyOf, rootPath } from '../skillfs.ts'
 import { errorText } from '../error-text.ts'
 import {
   homeOf,
   knownSkillNames,
-  pathExists,
   queryParam,
   readString,
   readStrings,
@@ -42,29 +40,20 @@ import {
   type RouteSpec,
   type SkillHubRouteDeps,
 } from './helpers.ts'
-import { gcImportJobs, importJobs, type ImportJob } from './route-state.ts'
+import { gcImportJobs, importJobs, retireNamePlaceholders, type ImportJob } from './route-state.ts'
 
 /**
- * 导入去重只认「已启用」的目录，但磁盘上仍可能躺着一个已禁用的同名占位 ——
- * 禁用只是把 SKILL.md 改名成 SKILL.md.disabled，目录本身还在。这种占位不该
- * 堵住真技能：把它连同禁用记录一起移入回收站让位（issue #16）。
+ * 导入让位（issue #16）：磁盘上已有同名占位但**没有启用的技能**时，把占位移入
+ * 回收站，把名字让给即将导入的真技能。占位有两种 —— 已禁用的发现文件（目录包或
+ * 扁平，后者曾长期漏处理：`clearDisabledPlaceholder` 只认 `<name>` 这个目录，
+ * 扁平占位占的是 `<name>.md.disabled`，判据为假，分支根本进不去）和没有 `SKILL.md`
+ * 的空壳目录。判据统一走 `occupancyOf`，形态判断集中在 `retireNamePlaceholders`。
  *
- * 只有「禁用记录确实指向 `targetRoot/<name>` 的整目录禁用」才处理，且该目录
- * 必须已经没有 SKILL.md；其余不确定情形一律返回 false，交回原本的「跳过」。
+ * 返回 false = 磁盘上有启用的同名技能（真货），一律不动，交回原本的「跳过」。
  */
 async function clearDisabledPlaceholder(deps: SkillHubRouteDeps, targetRoot: string, name: string): Promise<boolean> {
-  const record = await deps.store.getDisabled(name)
-  if (record === undefined) return false
-  const dir = join(targetRoot, name)
-  const sourceToTrash = record.path.endsWith('SKILL.md.disabled') ? dirname(record.path) : record.path
-  if (sourceToTrash !== dir) return false
-  // 目录里还有 SKILL.md 说明它其实是启用态的真实技能，不动。
-  if (await pathExists(join(dir, 'SKILL.md'))) return false
-  // 与 skill/delete 走同一个回收站落盘规则（moveIntoTrash），恢复流程依赖它。
-  const { path: target } = await moveIntoTrash(sourceToTrash)
-  await deps.store.addTrash({ name, path: target, movedAt: Date.now(), sourcePath: sourceToTrash })
-  await deps.store.removeDisabled(name)
-  return true
+  if ((await occupancyOf(targetRoot, name)).enabled.length > 0) return false
+  return (await retireNamePlaceholders(deps, targetRoot, name)) !== undefined
 }
 
 /** 仓库导入域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
@@ -192,10 +181,11 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
               job.done += 1
               continue
             }
-            // 磁盘上有同名目录。若它只是一个已禁用的占位（目录里只剩
-            // SKILL.md.disabled），先把旧目录移入回收站再继续导入；移不动或
-            // 不是这种形态时退回原本的「跳过」（issue #16）。
-            if (await pathExists(join(targetRoot, entry.name))) {
+            // 磁盘上有同名占位。若它只是一个已禁用的占位（目录包或扁平）或一个空壳
+            // 目录，先把旧东西移入回收站再继续导入；有启用的同名技能时退回「跳过」
+            // （issue #16）。
+            const occupancy = await occupancyOf(targetRoot, entry.name)
+            if (occupancy.enabled.length > 0 || occupancy.disabled.length > 0 || occupancy.bareDir !== undefined) {
               let cleared = false
               try {
                 cleared = await clearDisabledPlaceholder(deps, targetRoot, entry.name)
@@ -208,7 +198,7 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
                 job.done += 1
                 continue
               }
-              // 旧目录已经进了回收站（可恢复）。即使随后的下载失败也必须如实
+              // 占位已经进了回收站（可恢复）。即使随后的下载失败也必须如实
               // 上报，否则用户不知道自己的占位被挪走了。
               job.replaced.push(entry.name)
             }

package/src/routes/route-state.test.ts

@@ -2,7 +2,7 @@ import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promis
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
-import { IMPORT_JOB_MAX, gcImportJobs, importJobs, replaceSkillDir, type ImportJob } from './route-state.ts'
+import { IMPORT_JOB_MAX, gcImportJobs, importJobs, replaceInPlace, type ImportJob } from './route-state.ts'
 
 /** One import job with sane defaults; override what the test cares about. */
 function job(jobId: string, createdAt: number, status: ImportJob['status'] = 'done'): ImportJob {
@@ -50,7 +50,7 @@ describe('gcImportJobs', () => {
   })
 })
 
-describe('replaceSkillDir', () => {
+describe('replaceInPlace', () => {
   let dir: string
 
   afterEach(async () => { await rm(dir, { recursive: true, force: true }) })
@@ -60,7 +60,7 @@ describe('replaceSkillDir', () => {
     const target = join(dir, 'skill')
     await mkdir(target, { recursive: true })
     await writeFile(join(target, 'old.txt'), 'old', 'utf8')
-    await replaceSkillDir(target, async () => {
+    await replaceInPlace(target, async () => {
       // 下载方负责重建目标目录（downloadRepoSkill 就是这么做的）。
       await mkdir(target, { recursive: true })
       await writeFile(join(target, 'new.txt'), 'new', 'utf8')
@@ -76,7 +76,7 @@ describe('replaceSkillDir', () => {
     const target = join(dir, 'skill')
     await mkdir(target, { recursive: true })
     await writeFile(join(target, 'old.txt'), 'old', 'utf8')
-    await expect(replaceSkillDir(target, async () => { throw new Error('download failed') })).rejects.toThrow('download failed')
+    await expect(replaceInPlace(target, async () => { throw new Error('download failed') })).rejects.toThrow('download failed')
     expect(await readFile(join(target, 'old.txt'), 'utf8')).toBe('old')
     expect((await readdir(dir)).filter((name) => name.startsWith('.'))).toEqual([])
   })

package/src/routes/route-state.ts

@@ -6,6 +6,7 @@
 import { rm, rename } from 'node:fs/promises'
 import { basename, dirname, join } from 'node:path'
 import { errorText } from '../error-text.ts'
+import { moveIntoTrash, occupancyOf, trashSourceOf } from '../skillfs.ts'
 import type { SkillHubRouteDeps } from './helpers.ts'
 
 /** Minimum interval between network update checks per source (GitHub rate limits). */
@@ -79,21 +80,55 @@ export function gcImportJobs(): void {
   }
 }
 
-/** Replace one skill directory with a fresh download; restores the old dir on failure. */
-export async function replaceSkillDir(targetDir: string, download: () => Promise<void>): Promise<void> {
-  // 点前缀：发现扫描跳过点开头的目录（与导入临时目录 .<name>.import- 同一
-  // 约定），备份即使删除失败残留下来，也不会混进目录/发现诊断，更不会
-  // 造成同名技能重复注册。
-  const backup = join(dirname(targetDir), '.' + basename(targetDir) + '.sync-bak-' + Date.now())
-  await rename(targetDir, backup)
+/**
+ * Replace whatever currently occupies a skill slot with a fresh download;
+ * restores the previous state on failure.
+ *
+ * `target` is the entry to move aside — a bundle **directory** or a flat
+ * `<name>.md` file, whichever the download is replacing (the rename/rm below
+ * are form-neutral). The backup is dot-prefixed (discovery skips dot entries),
+ * so even a failed cleanup can never register as a duplicate skill.
+ */
+export async function replaceInPlace(target: string, download: () => Promise<unknown>): Promise<void> {
+  const backup = join(dirname(target), '.' + basename(target) + '.sync-bak-' + Date.now())
+  await rename(target, backup)
   try {
     await download()
   } catch (error) {
-    await rename(backup, targetDir).catch((rollbackError) => {
-      // 回滚失败会让技能只剩点前缀的备份目录（发现扫描会跳过它）：必须留痕。
-      console.warn('[dsh-skill-hub] restoring ' + targetDir + ' from ' + backup + ' failed:', errorText(rollbackError))
+    await rename(backup, target).catch((rollbackError) => {
+      // 回滚失败会让技能只剩点前缀的备份：必须留痕。
+      console.warn('[dsh-skill-hub] restoring ' + target + ' from ' + backup + ' failed:', errorText(rollbackError))
     })
     throw error
   }
   await rm(backup, { recursive: true, force: true })
 }
+
+/**
+ * 让位：把一个名字下的「非启用态占位」移入回收站并清掉它的 sidecar 禁用记录。
+ * 只动这两类，**启用的技能一律不碰**：
+ * - 禁用发现文件（`<name>/SKILL.md.disabled` 或 `<name>.md.disabled`，两种形态都认）；
+ * - 同名目录存在但既无 `SKILL.md` 也无 `SKILL.md.disabled`（导入中断/手工删除的空壳）。
+ *
+ * 回收站按名字索引，所以多形态只会记下最后一条的恢复指针；其余的那份会在
+ * 「清空回收站」时被孤儿回收扫掉（见 sourceTrashClear）。
+ *
+ * @returns 被移入回收站的路径列表，没有可让位的东西时 undefined。
+ */
+export async function retireNamePlaceholders(deps: SkillHubRouteDeps, base: string, name: string): Promise<string[] | undefined> {
+  const occupancy = await occupancyOf(base, name)
+  // trashSourceOf 让「目录包禁用件」与「空壳目录」自然去重（同一个目录只搬一次）。
+  const sources = [...new Set([
+    ...occupancy.disabled.map((path) => trashSourceOf(path)),
+    ...(occupancy.bareDir !== undefined ? [occupancy.bareDir] : []),
+  ])]
+  if (sources.length === 0) return undefined
+  const trashed: string[] = []
+  for (const source of sources) {
+    const moved = await moveIntoTrash(source)
+    await deps.store.addTrash({ name, path: moved.path, movedAt: Date.now(), sourcePath: moved.source })
+    trashed.push(moved.path)
+  }
+  await deps.store.removeDisabled(name)
+  return trashed
+}