dsh-skill-hub 0.3.19 → 0.3.21

package/src/routes.test.ts

@@ -5,6 +5,7 @@ import type { IncomingMessage } from 'node:http'
 import type { SkillDefinition, SkillSummary } from '@deepseek-ai/dsh-skill'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { makeRoutes, type SkillHubRouteDeps } from './routes.ts'
+import { lastMarketCheck } from './routes/route-state.ts'
 import { SkillHubStore, statePath } from './store.ts'
 import { SKILL_HUB_API, SKILL_HUB_API_ROOT, type CatalogResponse, type ConfigResponse, type ErrorResponse, type HubConfig } from './protocol.ts'
 
@@ -645,6 +646,73 @@ describe('skill-hub routes', () => {
     expect((del.json() as import('./protocol.ts').MarketSourceResponse).repos).toEqual([{ repo: 'other/repo', ref: 'v2.0.0' }])
   })
 
+  // 回归：重复添加一个已存在的源只改它的 ref、不重排列表，所以响应必须回传
+  // 服务端归一化的 slug —— 客户端不能靠 `repos[repos.length - 1]` 猜操作对象。
+  it('returns the resolved slug of the added market source, not a list position', async () => {
+    const add = async (repo: string): Promise<import('./protocol.ts').MarketSourceAddResponse> => {
+      const res = new FakeResponse()
+      await routeFor(SKILL_HUB_API.marketSource).handler(fakeReq('POST', SKILL_HUB_API.marketSource, { repo }), res as never)
+      expect(res.status).toBe(200)
+      return res.json() as import('./protocol.ts').MarketSourceAddResponse
+    }
+    await add('first/repo')
+    await add('second/repo')
+    const again = await add('first/repo@v9.9.9')
+    expect(again.repo).toBe('first/repo')
+    // 本次操作对象并不在末位：按位置猜会拿到 second/repo。
+    expect(again.repos[again.repos.length - 1].repo).toBe('second/repo')
+    expect(again.repos).toEqual([{ repo: 'first/repo', ref: 'v9.9.9' }, { repo: 'second/repo' }])
+    // URL 输入也归一到同一个 slug。
+    expect((await add('https://github.com/third/repo')).repo).toBe('third/repo')
+  })
+
+  // 回归：未定版的市场源也必须吃 5 分钟节流。曾经把节流时间戳写在「未定版
+  // 早退」之后，于是未定版的源每次检查都重新打 GitHub /releases/latest。
+  it('throttles the market check for an unpinned source as well', async () => {
+    lastMarketCheck.clear()
+    await store.addMarketSource('unpinned/throttle-target')
+    let releaseLookups = 0
+    vi.stubGlobal('fetch', vi.fn(async (url: string) => {
+      if (url.includes('/releases/latest')) {
+        releaseLookups += 1
+        return jsonResponse({ tag_name: 'v3.1.4' })
+      }
+      return new Response('unexpected url: ' + url, { status: 599 })
+    }))
+    try {
+      const first = new FakeResponse()
+      await routeFor(SKILL_HUB_API.marketCheck).handler(fakeReq('GET', SKILL_HUB_API.marketCheck), first as never)
+      const firstBody = first.json() as import('./protocol.ts').MarketCheckResponse
+      expect(firstBody.results[0]).toMatchObject({ repo: 'unpinned/throttle-target', latestTag: 'v3.1.4' })
+      expect(firstBody.results[0].throttled).toBeUndefined()
+
+      const second = new FakeResponse()
+      await routeFor(SKILL_HUB_API.marketCheck).handler(fakeReq('GET', SKILL_HUB_API.marketCheck), second as never)
+      const secondBody = second.json() as import('./protocol.ts').MarketCheckResponse
+      expect(secondBody.results[0].throttled).toBe(true)
+      // 第二次没有发生任何上游查询。
+      expect(releaseLookups).toBe(1)
+    } finally {
+      vi.unstubAllGlobals()
+      lastMarketCheck.clear()
+    }
+  })
+
+  // resolveHubConfig 收敛为单参数后，越界值仍必须回落到 schema 默认，
+  // 而不是被写进有效配置。
+  it('clamps the numeric stats knobs and fills the remaining defaults', async () => {
+    const routes = makeRoutes({
+      ...deps,
+      config: () => ({ enabled: true, announceToAgent: true, statsWindowDays: -5, statsScanMinutes: 0 }),
+    })
+    const res = new FakeResponse()
+    await routes.find((r) => r.path === SKILL_HUB_API.config)?.handler(fakeReq('GET', SKILL_HUB_API.config), res as never)
+    expect(res.status).toBe(200)
+    const body = res.json() as ConfigResponse
+    expect(body.config.statsWindowDays).toBe(14)
+    expect(body.config.statsScanMinutes).toBe(5)
+  })
+
   // ------------------------------------------------------- repo import (B方案 job+轮询)
   it('imports repo skills and records the upstream source', async () => {
     const skillMd = '---\nname: code-review\ndescription: Reviews code\n---\n\nbody'
@@ -1049,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

@@ -4,8 +4,9 @@ import { load } from 'js-yaml'
 import { parseFrontmatter, repairFrontmatterFileText } from './frontmatter.ts'
 import { rootPath } from './paths.ts'
 import { errorText } from '../error-text.ts'
+import { mapConcurrent } from '../concurrency.ts'
 import { dshHome } from '../store.ts'
-import type { DiagnosticEntry, WritableRoot } from '../protocol.ts'
+import { HEX_COLOR_RE, type DiagnosticEntry, type WritableRoot } from '../protocol.ts'
 
 /** One discoverable skill file in a scanned root. */
 export interface SkillEntry {
@@ -84,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)
     }
   }
@@ -130,7 +133,9 @@ export async function readSkillInterface(directory: string): Promise<SkillInterf
   const hexColor = (value: unknown): string | undefined => {
     if (typeof value !== 'string') return undefined
     const trimmed = value.trim()
-    return /^#[0-9a-fA-F]{6}$/.test(trimmed) ? trimmed : undefined
+    // Shared with the settings card and the config route: one definition, so a
+    // change to the accepted color format cannot land in only some of them.
+    return HEX_COLOR_RE.test(trimmed) ? trimmed : undefined
   }
   const iconPath = (value: unknown): string | undefined => {
     if (typeof value !== 'string' || value.trim() === '') return undefined
@@ -167,47 +172,144 @@ export async function findProjectRoot(cwd: string): Promise<string> {
 }
 
 /**
- * Scan one writable root for files the provider ignores, so the GUI can
- * show why a skill never appears — a
- * missing frontmatter must be visible, not silent). .disabled files belong
- * to the hub and are skipped.
+ * Scan one writable root for files the provider ignores, so the GUI can show
+ * why a skill never appears — a missing frontmatter, a name that disagrees
+ * with the discovery path, and the like must be visible, not silent. Files the
+ * hub itself disabled (`.disabled`) are skipped: they are a toggle state, not
+ * a defect.
  */
 export async function scanDiagnostics(root: WritableRoot, home = dshHome()): Promise<DiagnosticEntry[]> {
-  const diagnostics: DiagnosticEntry[] = []
-  for (const entry of await listSkillEntries(root, home)) {
+  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
+  // routes/catalog-data.ts is already parallel. Bounded, not a bare
+  // Promise.all: a root can hold hundreds of entries.
+  const perEntry = await mapConcurrent(entries, 8, async (entry): Promise<DiagnosticEntry[]> => {
+    const found: DiagnosticEntry[] = []
     let text: string
     try {
       text = await readFile(entry.path, 'utf8')
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
-        diagnostics.push({ path: entry.path, root, reason: 'unreadable: ' + (errorText(error)) })
+        found.push({ path: entry.path, root, reason: 'unreadable: ' + (errorText(error)) })
       }
-      continue
+      return found
     }
     const parsed = parseFrontmatter(text)
     if ('error' in parsed) {
       const fixable = repairFrontmatterFileText(text) !== null
-      diagnostics.push({ path: entry.path, root, reason: parsed.error, ...(fixable ? { fixable: true } : {}) })
-      continue
+      found.push({ path: entry.path, root, reason: parsed.error, ...(fixable ? { fixable: true } : {}) })
+      return found
     }
     // File was auto-repaired in memory (e.g. unquoted `:`); surface a fixable hint so the user can persist it.
     const repaired = repairFrontmatterFileText(text)
     if (repaired !== null) {
-      diagnostics.push({ path: entry.path, root, reason: 'frontmatter contains unquoted colon/bracket (auto-repaired in memory; click Fix to persist)', fixable: true })
+      found.push({ path: entry.path, root, reason: 'frontmatter contains unquoted colon/bracket (auto-repaired in memory; click Fix to persist)', fixable: true })
     }
     const { value } = parsed
     // The provider registers a skill by its discovery path (directory name or
     // 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) {
-      diagnostics.push({ path: entry.path, root, reason: `frontmatter name "${value.name}" does not match the discovery path "${pathName}" (the provider registers by path)` })
+      found.push({ path: entry.path, root, reason: `frontmatter name "${value.name}" does not match the discovery path "${pathName}" (the provider registers by path)` })
     }
     // Agents decide to auto-activate a skill from its one-line description, so
     // a too-short description leaves the skill hard to discover automatically.
     if (value.description.length < 10) {
-      diagnostics.push({ path: entry.path, root, reason: `description is only ${value.description.length} chars; write a one-line description so agents can auto-activate this skill` })
+      found.push({ path: entry.path, root, reason: `description is only ${value.description.length} chars; write a one-line description so agents can auto-activate this skill` })
+    }
+    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)
     }
   }
-  return diagnostics
+  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(), ...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.test.ts

@@ -1,8 +1,8 @@
-import { access, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { access, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { clearTrash, createSkill, disableSkill, enableSkill, parseFrontmatter, restoreSkill, rootOfPath, scanDiagnostics, trashSkill } from './skillfs.ts'
+import { clearTrash, createSkill, disableSkill, enableSkill, fixDiagnosticFile, parseFrontmatter, restoreSkill, rootOfPath, scanDiagnostics, trashSkill } from './skillfs.ts'
 
 describe('parseFrontmatter', () => {
   it('parses a healthy frontmatter', () => {
@@ -260,6 +260,20 @@ describe('scanDiagnostics', () => {
     expect(await scanDiagnostics('user-dsh', join(dir, 'missing'))).toEqual([])
   })
 
+  // 并发化（读盘 + 解析从串行改为有界并发）不得让输出变得不确定：
+  // 诊断顺序必须仍然等于发现顺序（按路径排序）。
+  it('keeps diagnostics in discovery order now that the scan is concurrent', async () => {
+    await writeFile(join(skills, 'b-bad.md'), '# nope', 'utf8')
+    await writeFile(join(skills, 'a-bad.md'), '# nope', 'utf8')
+    await writeFile(join(skills, 'c-bad.md'), '# nope', 'utf8')
+    const entries = await scanDiagnostics('user-dsh', home)
+    expect(entries.map((entry) => entry.path)).toEqual([
+      join(skills, 'a-bad.md'),
+      join(skills, 'b-bad.md'),
+      join(skills, 'c-bad.md'),
+    ])
+  })
+
   it('flags a frontmatter name that diverges from the discovery path', async () => {
     await mkdir(join(skills, 'folder-name'))
     await writeFile(join(skills, 'folder-name', 'SKILL.md'), '---\nname: other-name\ndescription: A decent longer description\n---', 'utf8')
@@ -277,6 +291,53 @@ describe('scanDiagnostics', () => {
   })
 })
 
+describe('fixDiagnosticFile', () => {
+  let dir: string
+  let home: string
+  let skills: string
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'dsh-skill-hub-fixdiag-'))
+    home = join(dir, 'home')
+    skills = join(home, 'skills')
+    await mkdir(skills, { recursive: true })
+  })
+
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('persists the repair atomically and leaves no temp file behind', async () => {
+    const path = join(skills, 'needs-fix', 'SKILL.md')
+    await mkdir(dirname(path), { recursive: true })
+    // Unquoted colon in the description: parseable only after an in-memory
+    // repair, which is exactly what the "Fix" action persists.
+    await writeFile(path, '---\nname: needs-fix\ndescription: Build for AWS: ECS\n---\nbody', 'utf8')
+    const before = await scanDiagnostics('user-dsh', home)
+    expect(before).toHaveLength(1)
+    expect(before[0]).toMatchObject({ path, fixable: true })
+
+    expect(await fixDiagnosticFile(path, home)).toBe(path)
+
+    const parsed = parseFrontmatter(await readFile(path, 'utf8'))
+    if ('error' in parsed) throw new Error('repaired file should parse: ' + parsed.error)
+    expect(parsed.value.description).toBe('Build for AWS: ECS')
+    expect(await scanDiagnostics('user-dsh', home)).toEqual([])
+    // Atomic write = sibling temp file + rename, so no .tmp may survive.
+    expect(await readdir(dirname(path))).toEqual(['SKILL.md'])
+  })
+
+  it('refuses paths outside the writable roots and files that need no repair', async () => {
+    await expect(fixDiagnosticFile(join(dir, 'outside', 'SKILL.md'), home)).rejects.toThrow(/not a hub writable skill path/)
+
+    const healthy = join(skills, 'fine', 'SKILL.md')
+    await mkdir(dirname(healthy), { recursive: true })
+    await writeFile(healthy, '---\nname: fine\ndescription: A perfectly fine description\n---\nbody', 'utf8')
+    await expect(fixDiagnosticFile(healthy, home)).rejects.toThrow(/not auto-fixable/)
+    expect(await readdir(dirname(healthy))).toEqual(['SKILL.md'])
+  })
+})
+
 describe('rootOfPath', () => {
   it('recognizes the writable roots', async () => {
     const dir = await mkdtemp(join(tmpdir(), 'dsh-skill-hub-root-'))