dsh-skill-hub 0.3.20 → 0.3.22

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/deps.ts

@@ -1,6 +1,6 @@
 /**
  * routes 共享层 · 依赖视图：路由依赖接口、配置解析与可写技能解析（HTTP
- * 围栏在 ./http.ts）。从 helpers.ts 原样搬出，行为不变。
+ * 围栏在 ./http.ts）。
  */
 
 import type { ServerResponse } from 'node:http'
@@ -8,7 +8,7 @@ import type { SkillDefinition, SkillSummary } from '@deepseek-ai/dsh-skill'
 import { resolveHubConfig, type HubConfig, type WritableRoot } from '../protocol.ts'
 import { rootOfPath } from '../skillfs.ts'
 import { dshHome, type SkillHubStore } from '../store.ts'
-import { writeError } from './http.ts'
+import { writeError, type RouteFence } from './http.ts'
 
 /** Sources the hub may toggle (the user-level filesystem roots). */
 export function isWritableSource(source: string): source is WritableRoot {
@@ -27,6 +27,12 @@ export interface SkillHubRouteDeps {
     get(name: string, options?: SkillLookupLike): Promise<SkillDefinition | undefined>
   }
   store: SkillHubStore
+  /**
+   * Request fence for the whole family: returns the rejection status (401/403)
+   * or `undefined` to proceed. Production passes the host's own `/api` fence
+   * (`ctx.connection.requestRejection`); absent falls back to literal loopback.
+   */
+  fence?: RouteFence
   /** DSH home override (tests isolate the writable roots; defaults to ~/.dsh). */
   home?: string
   /** Invalidate the registry catalog cache after hub-driven mutations. */

package/src/routes/helpers.ts

@@ -1,8 +1,7 @@
 /**
- * routes 共享层：请求围栏（回环信任/方法/总开关/JSON 体）、统一错误映射、
- * 可写技能解析、目录/分组数据装配。handler 只写业务，从这里 import。
- * 从 routes.ts 原样搬出，行为不变。
- * 本文件是聚合出口（barrel）：实现按域拆到 ./http.ts（围栏/错误映射/读体）、
+ * routes 共享层：请求栅栏（宿主 /api 信任模型 → 方法 → 总开关 → JSON 体）、
+ * 统一错误映射、可写技能解析、目录/分组数据装配。handler 只写业务，从这里 import。
+ * 本文件是聚合出口（barrel）：实现按域拆到 ./http.ts（栅栏/错误映射/读体）、
  * ./deps.ts（依赖视图/可写解析）、./collection.ts（集合装配）、
  * ./catalog-data.ts（目录装配）；对外导出面保持不变。
  */
@@ -10,12 +9,13 @@
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { WebRoute, WebRouteKind } from '@deepseek-ai/dsh-host-webserver'
 import { disabledGate, type SkillHubRouteDeps } from './deps.ts'
-import { isLoopbackRequest, readJsonBody, writeError, writeRouteError } from './http.ts'
+import { loopbackOnlyFence, readJsonBody, writeError, writeRouteError } from './http.ts'
 
 export {
   MAX_JSON_BODY_BYTES,
   STORE_ERROR_STATUS,
   isLoopbackRequest,
+  loopbackOnlyFence,
   pathExists,
   queryParam,
   readJsonBody,
@@ -25,6 +25,7 @@ export {
   writeJson,
   writeRouteError,
 } from './http.ts'
+export type { RouteFence } from './http.ts'
 export {
   configOf,
   disabledGate,
@@ -83,16 +84,26 @@ export interface RouteSpec {
 
 /**
  * Wrap one handler in the shared request fences. Order matches the
- * original per-handler prologue: loopback trust → HTTP method → master
+ * original per-handler prologue: trust fence → HTTP method → master
  * switch → JSON body. The outer catch maps errors onto the JSON error
  * body (preserving RepoFetchError status codes).
+ *
+ * The trust fence is the host's `/api` model (`deps.fence`) whenever the
+ * composition mounts Connection, so a reverse-proxied deployment is judged by
+ * the same authorities dsh already trusts; without that service the historical
+ * literal-loopback check stands in.
  */
 export function createRoute(deps: SkillHubRouteDeps, spec: RouteSpec): WebRoute {
+  const fence = deps.fence ?? loopbackOnlyFence
   return {
     kind: spec.kind ?? 'exact',
     path: spec.path,
     handler: async (req, res) => {
-      if (!isLoopbackRequest(req)) { writeError(res, 403, 'forbidden: loopback-only'); return }
+      const rejection = fence(req)
+      if (rejection !== undefined) {
+        writeError(res, rejection, rejection === 401 ? 'unauthorized: browser session required' : 'forbidden: untrusted authority')
+        return
+      }
       if (!spec.methods.includes(req.method as 'GET' | 'POST')) {
         writeError(res, 405, 'method not allowed: ' + (req.method ?? ''))
         return

package/src/routes/http.ts

@@ -1,6 +1,6 @@
 /**
- * routes 共享层 · HTTP 围栏：回环信任检查、JSON 响应与错误映射、请求体读取、
- * 查询/字段读取与文件存在性检查。从 helpers.ts 原样搬出，行为不变。
+ * routes 共享层 · HTTP 围栏：请求信任栅栏（复用宿主 `/api` 模型，见 RouteFence）、
+ * JSON 响应与错误映射、请求体读取、查询/字段读取与文件存在性检查。
  */
 
 import { stat } from 'node:fs/promises'
@@ -35,6 +35,35 @@ export function isLoopbackRequest(request: IncomingMessage): boolean {
   }
 }
 
+/**
+ * The route family's request fence: the HTTP status a request is rejected
+ * with (`401` unauthenticated / `403` untrusted authority), or `undefined`
+ * when it may reach the handler.
+ *
+ * dsh owns **one** browser-trust model for the whole `/api` tree — loopback,
+ * the listener's own bind address, every `--trusted-host` authority, then the
+ * browser session — and publishes it as `ctx.connection.requestRejection`,
+ * whose contract is written for exactly this case ("apply Connection's
+ * Host/Origin checks ... to another Web route"). Our paths are exact routes
+ * registered beside the shared `/api` prefix, so the host's own fence never
+ * sees them; asking its entry point instead of re-deriving the rule keeps a
+ * single trust model rather than a second, stricter one. Issue #17 is what the
+ * second one cost: behind a reverse proxy the literals checkable in this file
+ * are the gateway address and the public domain, so every route answered 403
+ * while the rest of the GUI worked.
+ */
+export type RouteFence = (request: IncomingMessage) => number | undefined
+
+/**
+ * Fallback fence for a host that mounts no Connection service (unit tests, and
+ * any composition serving the webserver alone): the historical literal-loopback
+ * check, so a missing service degrades to the previous behaviour instead of an
+ * open or a dead route family.
+ */
+export function loopbackOnlyFence(request: IncomingMessage): number | undefined {
+  return isLoopbackRequest(request) ? undefined : 403
+}
+
 /** One JSON response. */
 export function writeJson(res: ServerResponse, status: number, body: unknown): void {
   const payload = JSON.stringify(body)

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
+}