dsh-skill-hub 0.3.20 → 0.3.21

package/src/routes/sources.ts

@@ -4,7 +4,7 @@
  * handler 逻辑不变。
  */
 
-import { mkdir, rename } from 'node:fs/promises'
+import { mkdir, readdir, rename, rm } from 'node:fs/promises'
 import { join } from 'node:path'
 import { isSkillName } from '@deepseek-ai/dsh-skill'
 import {
@@ -30,7 +30,7 @@ import {
   skillFileAt,
   skillManifest,
 } from '../repo.ts'
-import { clearTrash, restoreSkill, rootOfPath, rootPath, trashSkill } from '../skillfs.ts'
+import { clearTrash, occupancyOf, restoreSkill, rootOfPath, rootPath, trashSkill, trashSourceOf, WRITABLE_ROOTS } from '../skillfs.ts'
 import { errorText } from '../error-text.ts'
 import {
   buildCollections,
@@ -43,7 +43,7 @@ import {
   type RouteSpec,
   type SkillHubRouteDeps,
 } from './helpers.ts'
-import { MIN_CHECK_INTERVAL_MS, lastSourceCheck, replaceSkillDir } from './route-state.ts'
+import { MIN_CHECK_INTERVAL_MS, lastSourceCheck, replaceInPlace, retireNamePlaceholders } from './route-state.ts'
 
 /** 来源跟踪域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
 export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
@@ -149,18 +149,28 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
             const files = collectRepoSkillFiles(tree, entry.dir)
             if (files.length === 0) { failed.push({ name, error: 'skill missing upstream' }); continue }
             const targetDir = join(targetRoot, name)
-            const wasDisabled = (await deps.store.getDisabled(name)) !== undefined
-            if (await pathExists(targetDir)) {
-              await replaceSkillDir(targetDir, async () => {
-                await downloadRepoSkill(repo, latest.commitSha, entry, files, targetRoot)
-              })
+            const record = await deps.store.getDisabled(name)
+            const occupancy = await occupancyOf(targetRoot, name)
+            // 落盘位置永远是目录包，所以本地无论是目录包还是扁平文件（启用或禁用）
+            // 都得先让开，否则同名两形态会并存（issue #16 类）。
+            const download = () => downloadRepoSkill(repo, latest.commitSha, entry, files, targetRoot)
+            // 1) 禁用件与空壳让位（顺带清掉 sidecar 禁用记录）。
+            await retireNamePlaceholders(deps, targetRoot, name)
+            // 2) 启用件按「替换」语义处理：先挪到点前缀备份，下载失败则原样恢复。
+            const enabled = occupancy.enabled[0]
+            if (enabled !== undefined) {
+              await replaceInPlace(trashSourceOf(enabled), download)
             } else {
-              await downloadRepoSkill(repo, latest.commitSha, entry, files, targetRoot)
+              await download()
             }
-            if (wasDisabled) {
+            if (record !== undefined) {
               // Preserve the disabled state: the fresh SKILL.md must not
-              // re-enter discovery.
-              await rename(join(targetDir, 'SKILL.md'), join(targetDir, 'SKILL.md.disabled'))
+              // re-enter discovery. 记录必须**无条件写回** —— 上面的
+              // retireNamePlaceholders 已经把它删过一遍，只按「path 变了才写」
+              // 判断会让「同步一个已禁用的技能」丢掉禁用状态与记录（活体实测过）。
+              const disabledPath = join(targetDir, 'SKILL.md.disabled')
+              await rename(join(targetDir, 'SKILL.md'), disabledPath)
+              await deps.store.addDisabled({ ...record, path: disabledPath })
             } else {
               await deps.store.removeDisabled(name)
             }
@@ -206,24 +216,29 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
             failed.push({ name, error: 'skill is not tracked by this source' })
             continue
           }
-          const sourcePath = join(rootPath('user-dsh', home), name)
-          if (rootOfPath(sourcePath, home) === undefined) {
-            failed.push({ name, error: 'skill path is outside the hub writable roots' })
+          // Resolve the on-disk occupation instead of assuming a `<root>/<name>`
+          // directory: the tracked skill can equally be a flat `<name>.md` file
+          // or a hub-disabled placeholder (issue #16 类).
+          const base = rootPath('user-dsh', home)
+          const occupancy = await occupancyOf(base, name)
+          const existing = occupancy.enabled[0] ?? occupancy.disabled[0] ?? occupancy.bareDir
+          if (existing === undefined) {
+            failed.push({ name, error: 'skill not found on disk' })
             continue
           }
-          if (!await pathExists(sourcePath)) {
-            failed.push({ name, error: 'skill directory not found' })
+          if (rootOfPath(existing, home) === undefined) {
+            failed.push({ name, error: 'skill path is outside the hub writable roots' })
             continue
           }
           try {
             // 入回收站前快照来源与场景归属，恢复时挂回（见 sourceRestore）。
             const tagIds = (await deps.store.listTags()).filter((tag) => tag.skillNames.includes(name)).map((tag) => tag.id)
-            const { path } = await trashSkill(sourcePath)
+            const { path, source: trashSource } = await trashSkill(existing)
             await deps.store.addTrash({
               name,
               path,
               movedAt: Date.now(),
-              sourcePath,
+              sourcePath: trashSource,
               origin: { repo: source.repo, root: source.root, ...(source.ref !== undefined && source.ref !== '' ? { ref: source.ref } : {}), commitSha: source.commitSha },
               ...(tagIds.length > 0 ? { tagIds } : {}),
             })
@@ -267,7 +282,7 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
         for (const tagId of entry.tagIds ?? []) {
           await deps.store.addSkillToTag(tagId, name)
         }
-        await deps.store.removeTrash(name)
+        await deps.store.removeTrash(entry.path)
         deps.invalidate?.()
         writeJson(res, 200, { ok: true, name, path } satisfies SourceRestoreResponse)
       },
@@ -281,6 +296,7 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
         const home = homeOf(deps)
         const entries = await deps.store.listTrash()
         const deleted: string[] = []
+        const removedPaths: string[] = []
         const failed: Array<{ name: string; error: string }> = []
         for (const entry of entries) {
           try {
@@ -288,14 +304,54 @@ export function sourceRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
             // A permanently deleted skill must not linger in user groups.
             await deps.store.removeSkillFromTags(entry.name)
             deleted.push(entry.name)
+            removedPaths.push(entry.path)
           } catch (error) {
             failed.push({ name: entry.name, error: errorText(error) })
           }
         }
-        for (const name of deleted) await deps.store.removeTrash(name)
-        if (deleted.length > 0) deps.invalidate?.()
-        writeJson(res, 200, { ok: true, deleted, failed } satisfies SourceTrashClearResponse)
+        for (const path of removedPaths) await deps.store.removeTrash(path)
+        // 回收站记录按名字索引：同名技能先后两次入站时旧记录被覆盖，但它的
+        // `<name>-<时间戳>` 目录还留在盘上，任何记录都指不到它 → 永久孤儿。
+        // 「清空回收站」正是它的回收时机，顺手扫掉并如实上报。
+        const orphans = await sweepOrphanTrash(deps, home, failed)
+        if (deleted.length > 0 || orphans.length > 0) deps.invalidate?.()
+        writeJson(res, 200, {
+          ok: true,
+          deleted,
+          failed,
+          ...(orphans.length > 0 ? { orphans } : {}),
+        } satisfies SourceTrashClearResponse)
       },
     },
   ]
 }
+
+/**
+ * 删除两个可写根 `.trash` 下不被任何回收站记录引用的残留目录。
+ * 只扫 `.trash` 的直接子项、跳过点开头项，失败项并入 `failed`（保留可重试）。
+ */
+async function sweepOrphanTrash(deps: SkillHubRouteDeps, home: string, failed: Array<{ name: string; error: string }>): Promise<string[]> {
+  const referenced = new Set((await deps.store.listTrash()).map((entry) => entry.path))
+  const orphans: string[] = []
+  for (const root of WRITABLE_ROOTS) {
+    const trashDir = join(rootPath(root, home), '.trash')
+    let names: string[]
+    try {
+      names = await readdir(trashDir)
+    } catch {
+      continue // 该根没有回收站目录
+    }
+    for (const name of names) {
+      if (name.startsWith('.')) continue
+      const full = join(trashDir, name)
+      if (referenced.has(full)) continue
+      try {
+        await rm(full, { recursive: true, force: true })
+        orphans.push(full)
+      } catch (error) {
+        failed.push({ name, error: errorText(error) })
+      }
+    }
+  }
+  return orphans
+}

package/src/routes.test.ts

@@ -1117,6 +1117,238 @@ describe('skill-hub routes', () => {
     expect(invalidate).toHaveBeenCalledTimes(1)
   })
 
+  // --------------------------- 同名双形态 / 陈旧禁用记录（issue #16 类，实测 G5/G7/G8）
+  it('self-heals a stale disabled record by pointing it at the surviving placeholder', async () => {
+    // 记录指目录形态，磁盘上只剩扁平占位 —— 导入让位/L2 迁移后的典型残留。
+    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 res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.toggle).handler(fakeReq('POST', SKILL_HUB_API.toggle, { name: 'code-review', enabled: true }), res as never)
+    expect(res.status).toBe(200)
+    await expect(access(join(home, 'skills', 'code-review.md'))).resolves.toBeUndefined()
+    expect(await store.getDisabled('code-review')).toBeUndefined()
+  })
+
+  it('drops a fully stale disabled record so the name becomes usable again', async () => {
+    await store.addDisabled({ name: 'ghost', description: 'x', path: join(home, 'skills', 'ghost', 'SKILL.md.disabled'), root: 'user-dsh', disabledAt: 1 })
+    // 记录还在时，新建同名技能被 409 挡住。
+    const blocked = new FakeResponse()
+    await routeFor(SKILL_HUB_API.create).handler(fakeReq('POST', SKILL_HUB_API.create, { name: 'ghost', description: 'x' }), blocked as never)
+    expect(blocked.status).toBe(409)
+    // 启用报「记录已失效」并把记录清掉，而不是留下一条谁都动不了的死记录。
+    const enable = new FakeResponse()
+    await routeFor(SKILL_HUB_API.toggle).handler(fakeReq('POST', SKILL_HUB_API.toggle, { name: 'ghost', enabled: true }), enable as never)
+    expect(enable.status).toBe(409)
+    expect(String((enable.json() as { error: string }).error)).toContain('stale')
+    expect(await store.getDisabled('ghost')).toBeUndefined()
+    // 名字已释放：新建成功，再次启用则报「不是禁用态」。
+    const created = new FakeResponse()
+    await routeFor(SKILL_HUB_API.create).handler(fakeReq('POST', SKILL_HUB_API.create, { name: 'ghost', description: 'x' }), created as never)
+    expect(created.status).toBe(201)
+    await expect(access(join(home, 'skills', 'ghost', 'SKILL.md'))).resolves.toBeUndefined()
+    const again = new FakeResponse()
+    await routeFor(SKILL_HUB_API.toggle).handler(fakeReq('POST', SKILL_HUB_API.toggle, { name: 'ghost', enabled: true }), again as never)
+    expect(again.status).toBe(404)
+  })
+
+  it('deletes a stale disabled record instead of failing on the missing file', async () => {
+    const tag = await store.saveTag({ name: 'scene-x' })
+    await store.setTagMembers(tag.id, ['ghost'])
+    await store.addDisabled({ name: 'ghost', description: 'x', path: join(home, 'skills', 'ghost', 'SKILL.md.disabled'), root: 'user-dsh', disabledAt: 1 })
+    const res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.skillDelete).handler(fakeReq('POST', SKILL_HUB_API.skillDelete, { name: 'ghost' }), res as never)
+    expect(res.status).toBe(200)
+    expect(await store.getDisabled('ghost')).toBeUndefined()
+    expect((await store.getTag(tag.id))?.skillNames).toEqual([])
+  })
+
+  it('flags two discovery forms occupying the same skill name in one root', async () => {
+    // 目录包与扁平文件同名：注册表只给一个，另一个静默不可达 → 必须报诊断。
+    await writeFile(join(home, 'skills', 'dup-skill.md'), '---\nname: dup-skill\ndescription: flat one\n---', 'utf8')
+    await mkdir(join(home, 'skills', 'dup-skill'), { recursive: true })
+    await writeFile(join(home, 'skills', 'dup-skill', 'SKILL.md'), '---\nname: dup-skill\ndescription: bundle one\n---', 'utf8')
+    const res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.catalog).handler(fakeReq('GET', SKILL_HUB_API.catalog), res as never)
+    expect(res.status).toBe(200)
+    const body = res.json() as CatalogResponse
+    const collisions = body.diagnostics.filter((d) => d.reason.includes('registers the same name'))
+    expect(collisions.map((d) => d.path).sort()).toEqual([
+      join(home, 'skills', 'dup-skill.md'),
+      join(home, 'skills', 'dup-skill', 'SKILL.md'),
+    ].sort())
+    expect(collisions[0].reason).toContain('"dup-skill"')
+  })
+
+  it('reclaims unreferenced trash directories when clearing the trash', async () => {
+    const trash = join(home, 'skills', '.trash')
+    await mkdir(join(trash, 'foo-1'), { recursive: true })
+    await mkdir(join(trash, 'foo-2'), { recursive: true })
+    // 名字索引只剩最新那条；foo-1 已经没有任何记录指得到它。
+    await store.addTrash({ name: 'foo', path: join(trash, 'foo-2'), movedAt: 2, sourcePath: join(home, 'skills', 'foo') })
+    const res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.sourceTrashClear).handler(fakeReq('POST', SKILL_HUB_API.sourceTrashClear), res as never)
+    expect(res.status).toBe(200)
+    const body = res.json() as import('./protocol.ts').SourceTrashClearResponse
+    expect(body.deleted).toEqual(['foo'])
+    expect(body.orphans).toEqual([join(trash, 'foo-1')])
+    await expect(access(join(trash, 'foo-1'))).rejects.toThrow()
+    await expect(access(join(trash, 'foo-2'))).rejects.toThrow()
+  })
+
+  // ------------------------- 导入/同步/删除/新建 遇到扁平形态（issue #16 类，实测 G1–G4）
+  /** 造一个「扁平已禁用占位」：`<name>.md.disabled` + 指向它的 sidecar 记录。 */
+  async function seedFlatDisabledPlaceholder(name: string) {
+    const flat = join(home, 'skills', name + '.md.disabled')
+    await writeFile(flat, `---\nname: ${name}\ndescription: stub\n---\n`, 'utf8')
+    await store.addDisabled({ name, description: 'stub', path: flat, root: 'user-dsh', disabledAt: Date.now() })
+    return flat
+  }
+
+  it('imports over a flat disabled placeholder instead of leaving it behind', async () => {
+    const flat = await seedFlatDisabledPlaceholder('code-review')
+    const skillMd = '---\nname: code-review\ndescription: Reviews code\n---\n\nbody'
+    stubFetch([
+      ['repos/example/repo/git/trees/main', jsonResponse({ tree: [
+        { path: 'skills/code-review/SKILL.md', type: 'blob', size: 60 },
+      ] })],
+      ['repos/example/repo/commits', jsonResponse({ sha: 'abc123', commit: { tree: { sha: 'tree1' } } })],
+      ['repos/example/repo', jsonResponse({ default_branch: 'main' })],
+      ['raw.githubusercontent.com/example/repo/main/skills/code-review/SKILL.md', new Response(skillMd, { status: 200 })],
+    ])
+    try {
+      const res = new FakeResponse()
+      await routeFor(SKILL_HUB_API.repoImport).handler(fakeReq('POST', SKILL_HUB_API.repoImport, { repo: 'example/repo', paths: ['skills/code-review/SKILL.md'] }), res as never)
+      const created = res.json() as import('./protocol.ts').RepoImportResponse
+      let prog: import('./protocol.ts').RepoImportProgressResponse | undefined
+      for (let i = 0; i < 30; i++) {
+        await new Promise((r) => setTimeout(r, 40))
+        const p = new FakeResponse()
+        await routeFor(SKILL_HUB_API.repoImportProgress).handler(fakeReq('GET', `${SKILL_HUB_API.repoImportProgress}?jobId=${created.jobId}`), p as never)
+        prog = p.json() as import('./protocol.ts').RepoImportProgressResponse
+        if (prog.status !== 'running') break
+      }
+      expect(prog!.status).toBe('done')
+      expect(prog!.skipped).toEqual([])
+      expect(prog!.imported.map((r) => r.name)).toEqual(['code-review'])
+      // 关键差异：扁平占位不再「看不见」——它被移入回收站、如实上报，真技能落地。
+      expect(prog!.replaced).toEqual(['code-review'])
+      await expect(access(flat)).rejects.toThrow()
+      await expect(readFile(join(home, 'skills', 'code-review', 'SKILL.md'), 'utf8')).resolves.toContain('name: code-review')
+      expect(await store.listDisabled()).toEqual([])
+      expect((await store.listTrash()).map((entry) => entry.name)).toEqual(['code-review'])
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  /** 同步一个已跟踪技能所需的 fetch 桩（tree + commit + raw）。 */
+  function stubSyncFetch(): void {
+    stubFetch([
+      ['repos/example/repo/git/trees/tree1', jsonResponse({ tree: [
+        { path: 'skills/code-review/SKILL.md', type: 'blob', size: 60 },
+      ] })],
+      ['repos/example/repo/commits', jsonResponse({ sha: 'abc123', commit: { tree: { sha: 'tree1' } } })],
+      ['raw.githubusercontent.com/example/repo/abc123/skills/code-review/SKILL.md', new Response('---\nname: code-review\ndescription: upstream\n---\n', { status: 200 })],
+    ])
+  }
+
+  it('syncs a flat-stored skill into the bundle slot instead of leaving both', async () => {
+    await writeFile(join(home, 'skills', 'code-review.md'), '---\nname: code-review\ndescription: flat\n---\n', 'utf8')
+    await store.addSourceSkill('example/repo', 'skills', '', 'main', 'code-review')
+    stubSyncFetch()
+    try {
+      const res = new FakeResponse()
+      await routeFor(SKILL_HUB_API.sourceSync).handler(fakeReq('POST', SKILL_HUB_API.sourceSync, { repo: 'example/repo' }), res as never)
+      expect(res.status).toBe(200)
+      expect((res.json() as import('./protocol.ts').SourceSyncResponse).synced).toEqual(['code-review'])
+      // 旧扁平文件必须先让开，否则同名两形态并存（注册表只会给一个）。
+      await expect(access(join(home, 'skills', 'code-review.md'))).rejects.toThrow()
+      await expect(readFile(join(home, 'skills', 'code-review', 'SKILL.md'), 'utf8')).resolves.toContain('description: upstream')
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  it('syncs a flat hub-disabled skill and repoints its record at the new bundle', async () => {
+    const flat = await seedFlatDisabledPlaceholder('code-review')
+    await store.addSourceSkill('example/repo', 'skills', '', 'main', 'code-review')
+    stubSyncFetch()
+    try {
+      const res = new FakeResponse()
+      await routeFor(SKILL_HUB_API.sourceSync).handler(fakeReq('POST', SKILL_HUB_API.sourceSync, { repo: 'example/repo' }), res as never)
+      expect(res.status).toBe(200)
+      // 禁用态要保持，但记录必须改指新形态 —— 否则「启用」会去动那个已被替换掉的旧文件。
+      const bundleDisabled = join(home, 'skills', 'code-review', 'SKILL.md.disabled')
+      await expect(access(bundleDisabled)).resolves.toBeUndefined()
+      await expect(access(flat)).rejects.toThrow()
+      expect((await store.getDisabled('code-review'))?.path).toBe(bundleDisabled)
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  it('keeps a bundle-disabled skill disabled after syncing it again', async () => {
+    // 记录本来就指向目录包形态（`<name>/SKILL.md.disabled`）：让位步骤会把记录删掉，
+    // 若只在「path 变了」时写回，这里就会连禁用状态和记录一起丢掉（活体实测抓到过）。
+    const dir = join(home, 'skills', 'code-review')
+    await mkdir(dir, { recursive: true })
+    const bundleDisabled = join(dir, 'SKILL.md.disabled')
+    await writeFile(bundleDisabled, '---\nname: code-review\ndescription: old\n---\n', 'utf8')
+    await store.addDisabled({ name: 'code-review', description: 'old', path: bundleDisabled, root: 'user-dsh', disabledAt: 1 })
+    await store.addSourceSkill('example/repo', 'skills', '', 'main', 'code-review')
+    stubSyncFetch()
+    try {
+      const res = new FakeResponse()
+      await routeFor(SKILL_HUB_API.sourceSync).handler(fakeReq('POST', SKILL_HUB_API.sourceSync, { repo: 'example/repo' }), res as never)
+      expect((res.json() as import('./protocol.ts').SourceSyncResponse).synced).toEqual(['code-review'])
+      await expect(access(bundleDisabled)).resolves.toBeUndefined()
+      expect((await store.getDisabled('code-review'))?.path).toBe(bundleDisabled)
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  it('follows an upstream delete for a flat-stored skill', async () => {
+    const flat = join(home, 'skills', 'code-review.md')
+    await writeFile(flat, '---\nname: code-review\ndescription: flat\n---\n', 'utf8')
+    await store.addSourceSkill('example/repo', 'skills', 'abc', undefined, 'code-review')
+    const res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.sourceDelete).handler(fakeReq('POST', SKILL_HUB_API.sourceDelete, { repo: 'example/repo', skills: ['code-review'] }), res as never)
+    expect(res.status).toBe(200)
+    const body = res.json() as import('./protocol.ts').SourceDeleteResponse
+    expect(body.failed).toEqual([])
+    expect(body.trashed).toEqual(['code-review'])
+    await expect(access(flat)).rejects.toThrow()
+    expect((await store.listTrash())[0]?.sourcePath).toBe(flat)
+  })
+
+  it('refuses to create a skill whose name is taken by a flat file on disk', async () => {
+    // frontmatter 坏 → 注册表看不见它，但名字确实被占了；建目录会立刻造出同名两形态。
+    await writeFile(join(home, 'skills', 'foo.md'), 'not a frontmatter file', 'utf8')
+    const res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.create).handler(fakeReq('POST', SKILL_HUB_API.create, { name: 'foo', description: 'x' }), res as never)
+    expect(res.status).toBe(409)
+    expect(String((res.json() as { error: string }).error)).toContain('occupies this name on disk')
+    await expect(access(join(home, 'skills', 'foo'))).rejects.toThrow()
+  })
+
+  it('refuses to create a skill whose name is held by a disabled placeholder', async () => {
+    // 有 sidecar 记录时走既有的「先重新启用」提示；没有记录（记录丢失/手改过）
+    // 时以前会直接建档造出同名两形态，现在由磁盘占位检查兜住。
+    await writeFile(join(home, 'skills', 'foo.md.disabled'), '---\nname: foo\ndescription: stub\n---\n', 'utf8')
+    const res = new FakeResponse()
+    await routeFor(SKILL_HUB_API.create).handler(fakeReq('POST', SKILL_HUB_API.create, { name: 'foo', description: 'x' }), res as never)
+    expect(res.status).toBe(409)
+    expect(String((res.json() as { error: string }).error)).toContain('disabled placeholder')
+    await expect(access(join(home, 'skills', 'foo'))).rejects.toThrow()
+    // 有记录时保持原有提示口径。
+    await seedFlatDisabledPlaceholder('bar')
+    const withRecord = new FakeResponse()
+    await routeFor(SKILL_HUB_API.create).handler(fakeReq('POST', SKILL_HUB_API.create, { name: 'bar', description: 'x' }), withRecord as never)
+    expect(withRecord.status).toBe(409)
+    expect(String((withRecord.json() as { error: string }).error)).toContain('re-enable it from the disabled list first')
+  })
+
   it('patches display toggles on the config route', async () => {
     const res = new FakeResponse()
     await routeFor(SKILL_HUB_API.config).handler(fakeReq('POST', SKILL_HUB_API.config, { showUseCount: false }), res as never)

package/src/skillfs/scan.ts

@@ -85,7 +85,9 @@ export async function scanDisabledRoot(base: string): Promise<string[]> {
       } catch {
         // 目录里没有禁用的发现文件，跳过
       }
-    } else if (name.endsWith('.md.disabled') && name !== 'SKILL.md.disabled') {
+    } else if (name.endsWith('.md.disabled')) {
+      // 扁平形态的禁用文件。根级 `SKILL.md.disabled` 也归这里：`scanRoot` 会把
+      // 根级 `SKILL.md` 文件当作一个扁平技能，它的禁用对应物就该被对账到。
       paths.push(absolute)
     }
   }
@@ -178,6 +180,12 @@ export async function findProjectRoot(cwd: string): Promise<string> {
  */
 export async function scanDiagnostics(root: WritableRoot, home = dshHome()): Promise<DiagnosticEntry[]> {
   const entries = await listSkillEntries(root, home)
+  // 同一个名字可以由两种发现形态同时占据（目录包 `<name>/SKILL.md` 与扁平
+  // `<name>.md`）。注册表只会给出其中一个，另一个静默不可达 —— 必须报出来，
+  // 否则面板上完全看不出「技能改了没生效」的原因。分组键同时取「发现路径名」
+  // 与「frontmatter 名」：前者是官方 provider 的注册键，后者是本插件 provider
+  // 的注册键，两边不一致时至少有一侧会撞上。
+  const discovered: Array<{ path: string; keys: string[] }> = []
   // Each entry is read and parsed independently, and the panel polls /catalog
   // every 5 seconds. A serial read would make the response time grow linearly
   // with the skill count — the same reason the per-skill `stat` collection in
@@ -210,6 +218,7 @@ export async function scanDiagnostics(root: WritableRoot, home = dshHome()): Pro
     // flat file name), so a frontmatter name that diverges from the path makes
     // the skill show up under a different identity than its metadata claims.
     const pathName = entry.kind === 'directory' ? basename(entry.directory) : basename(entry.path, '.md')
+    discovered.push({ path: entry.path, keys: [...new Set([pathName, value.name])] })
     if (value.name !== pathName) {
       found.push({ path: entry.path, root, reason: `frontmatter name "${value.name}" does not match the discovery path "${pathName}" (the provider registers by path)` })
     }
@@ -220,7 +229,87 @@ export async function scanDiagnostics(root: WritableRoot, home = dshHome()): Pro
     }
     return found
   })
+  // 同名冲突：把每个命中冲突的发现文件各报一条，让用户两边都能看到并选一个处理。
+  const owners = new Map<string, string[]>()
+  for (const item of discovered) {
+    for (const key of item.keys) {
+      const list = owners.get(key)
+      if (list === undefined) owners.set(key, [item.path])
+      else list.push(item.path)
+    }
+  }
+  const collisions: DiagnosticEntry[] = []
+  for (const item of discovered) {
+    const shared = item.keys.filter((key) => (owners.get(key)?.length ?? 0) > 1)
+    if (shared.length === 0) continue
+    collisions.push({
+      path: item.path,
+      root,
+      reason: `another skill in this root registers the same name (${shared.map((key) => '"' + key + '"').join(', ')}); the registry keeps only one of them, so this one is unreachable — delete or rename one of the two`,
+    })
+  }
   // mapConcurrent preserves index order, so flattening keeps the previous
   // per-entry ordering of the diagnostics.
-  return perEntry.flat()
+  return [...perEntry.flat(), ...collisions]
+}
+
+/**
+ * 某个名字在一个 root 下现存的禁用发现文件（两种形态都认），没有则 undefined。
+ * 目录包形态优先（`<name>/SKILL.md.disabled`），其次扁平 `<name>.md.disabled`。
+ * 单点定义「禁用态在磁盘上长什么样」，避免各处再拼一次路径（issue #16 类）。
+ */
+export async function disabledOccupancyIn(base: string, name: string): Promise<string | undefined> {
+  return (await occupancyOf(base, name)).disabled[0]
+}
+
+/** stat 一次给出形态；不存在或不可读时 undefined。 */
+async function statKind(path: string): Promise<'file' | 'directory' | undefined> {
+  try {
+    const info = await stat(path)
+    return info.isDirectory() ? 'directory' : 'file'
+  } catch {
+    return 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 async function occupancyOf(base: string, name: string): Promise<NameOccupancy> {
+  const bundleDir = join(base, name)
+  const bundleSkill = join(bundleDir, 'SKILL.md')
+  const bundleDisabled = join(bundleDir, 'SKILL.md.disabled')
+  const flatSkill = join(base, name + '.md')
+  const flatDisabled = join(base, name + '.md.disabled')
+  const [bundleSkillKind, bundleDisabledKind, flatSkillKind, flatDisabledKind, bundleDirKind] = await Promise.all([
+    statKind(bundleSkill),
+    statKind(bundleDisabled),
+    statKind(flatSkill),
+    statKind(flatDisabled),
+    statKind(bundleDir),
+  ])
+  const result: NameOccupancy = { enabled: [], disabled: [] }
+  if (bundleSkillKind === 'file') result.enabled.push(bundleSkill)
+  if (flatSkillKind === 'file') result.enabled.push(flatSkill)
+  if (bundleDisabledKind === 'file') result.disabled.push(bundleDisabled)
+  if (flatDisabledKind === 'file') result.disabled.push(flatDisabled)
+  if (bundleDirKind === 'directory' && bundleSkillKind !== 'file' && bundleDisabledKind !== 'file') result.bareDir = bundleDir
+  return result
 }

package/src/skillfs.ts

@@ -102,15 +102,27 @@ export async function moveIntoTrash(source: string): Promise<{ path: string; sou
   return { path: target, source }
 }
 
+/**
+ * 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 function trashSourceOf(discoveryPath: string): string {
+  const base = basename(discoveryPath)
+  return base === 'SKILL.md' || base === 'SKILL.md.disabled' ? dirname(discoveryPath) : discoveryPath
+}
+
 /**
  * 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 async function trashSkill(sourcePath: string): Promise<{ path: string; source: string }> {
-  return moveIntoTrash(basename(sourcePath) === 'SKILL.md' ? dirname(sourcePath) : sourcePath)
+  return moveIntoTrash(trashSourceOf(sourcePath))
 }
 
 /** Restore a trashed skill (directory or flat file) to its original location. */

package/src/store/migrate.ts

@@ -90,7 +90,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[]
@@ -179,14 +179,16 @@ export function hydrateMigratedState(migrated: MigratedStore): HydratedState {
     }
   }
 
-  const trashByName = new Map<string, TrashEntry>()
+  const trashByPath = new Map<string, TrashEntry>()
   if (Array.isArray(migrated.trash)) {
     for (const entry of migrated.trash as unknown[]) {
       const item = entry as { name?: unknown; path?: unknown; movedAt?: unknown; sourcePath?: unknown } | null
       if (item !== null && typeof item === 'object' && typeof item.name === 'string' && typeof item.path === 'string') {
         const origin = (item as Record<string, unknown>).origin as { repo?: unknown; root?: unknown; ref?: unknown; commitSha?: unknown } | undefined
         const tagIds = (item as Record<string, unknown>).tagIds
-        trashByName.set(item.name, {
+        // 按 path 建索引：回收站里同名可以有多条（跨形态/先后两次入站），按名字
+        // 索引会让后一条静默覆盖前一条、把前一份目录留成谁都指不到的孤儿。
+        trashByPath.set(item.path, {
           name: item.name,
           path: item.path,
           movedAt: typeof item.movedAt === 'number' ? item.movedAt : 0,
@@ -294,5 +296,5 @@ export function hydrateMigratedState(migrated: MigratedStore): HydratedState {
   const collectionOrder = cleanStringList(migrated.collectionOrder)
   const sourceGroupOrder = cleanStringList(migrated.sourceGroupOrder)
 
-  return { entries, config, tagsById, sourcesByRepo, marketSources, trashByName, skillStats, marketStats, collectionOrder, sourceGroupOrder }
+  return { entries, config, tagsById, sourcesByRepo, marketSources, trashByPath, skillStats, marketStats, collectionOrder, sourceGroupOrder }
 }