dsh-skill-hub 0.3.18 → 0.3.20

package/src/repo.test.ts

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { mkdtemp, readFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { NO_COMPRESSION, apiHeaders, collectRepoSkillFiles, diffRemoteSkills, discoverRepoEntries, downloadGitHubFile, downloadRepoSkill, getLatestReleaseTag, getRepoStats, listRepoBranches, normalizeRepoInput, originForRoot, relativeToSkillDir, repoSkillEntry, repoSlug, skillDirOf, skillFileAt, skillManifest } from './repo.ts'
+import { NO_COMPRESSION, apiHeaders, collectRepoSkillFiles, diffRemoteSkills, discoverRepoEntries, downloadGitHubFile, downloadRepoSkill, getLatestReleaseTag, getRepoStats, listRepoBranches, normalizeRepoInput, originForRoot, rateLimitResetAt, relativeToSkillDir, repoSkillEntry, repoSlug, skillDirOf, skillFileAt, skillManifest } from './repo.ts'
 import type { RepoTreeItem } from './repo.ts'
 import type { RepoSkillEntry } from './protocol.ts'
 
@@ -366,6 +366,26 @@ describe('downloadGitHubFile', () => {
     expect(buffer.toString('utf8')).toContain('name: demo')
     expect(calls.length).toBe(2)
     expect(calls[1]).toContain('api.github.com/repos/example/repo/contents/skills/demo/SKILL.md')
+    expect(calls[1]).toContain('ref=main')
+  })
+
+  // issue #15: the fallback dropped the ref, so /contents/ served the default
+  // branch and a tag/branch-pinned import silently mixed main-branch content.
+  it('keeps the requested ref on the api fallback (never the default branch)', async () => {
+    const calls: string[] = []
+    const ref = 'andibrae/create-top-level-namespace'
+    const fetchImpl = async (url: string) => {
+      calls.push(url)
+      if (url.startsWith('https://raw.githubusercontent.com/')) throw new Error('raw blocked')
+      if (url.includes('/contents/')) return new Response('---\nname: demo\ndescription: x\n---\n\nref body', { status: 200 })
+      return new Response('nope', { status: 599 })
+    }
+    await downloadGitHubFile('example/repo', ref, 'skills/demo/SKILL.md', fetchImpl as typeof fetch)
+    expect(calls[1]).toBe(
+      'https://api.github.com/repos/example/repo/contents/skills/demo/SKILL.md?ref=' + encodeURIComponent(ref),
+    )
+    // The un-ref'd form is exactly what served default-branch content.
+    expect(calls[1]).not.toBe('https://api.github.com/repos/example/repo/contents/skills/demo/SKILL.md')
   })
 
   it('reports the original error when both hosts fail', async () => {
@@ -429,3 +449,22 @@ describe('GitHub 请求头', () => {
     expect(apiHeaders().accept).toBe('application/vnd.github+json')
   })
 })
+
+describe('rateLimitResetAt', () => {
+  const response = (status: number, headers: Record<string, string>): Response => new Response('', { status, headers })
+  const exhausted = { 'x-ratelimit-remaining': '0', 'x-ratelimit-reset': '1700000000' }
+
+  it('reports the reset instant for an exhausted 403 or 429', () => {
+    expect(rateLimitResetAt(response(403, exhausted))?.getTime()).toBe(1700000000 * 1000)
+    expect(rateLimitResetAt(response(429, exhausted))?.getTime()).toBe(1700000000 * 1000)
+  })
+
+  it('is undefined for anything that is not an exhausted rate limit', () => {
+    expect(rateLimitResetAt(response(500, exhausted))).toBeUndefined()
+    expect(rateLimitResetAt(response(404, exhausted))).toBeUndefined()
+    expect(rateLimitResetAt(response(403, { 'x-ratelimit-remaining': '57', 'x-ratelimit-reset': '1700000000' }))).toBeUndefined()
+    expect(rateLimitResetAt(response(403, { 'x-ratelimit-remaining': '0' }))).toBeUndefined()
+    // 头部存在但不是数字：宁可退回普通 HTTP 文案，也不要报 "Invalid Date"。
+    expect(rateLimitResetAt(response(403, { 'x-ratelimit-remaining': '0', 'x-ratelimit-reset': 'nope' }))).toBeUndefined()
+  })
+})

package/src/repo.ts

@@ -14,7 +14,7 @@
  */
 
 // 后向兼容：老 `from './repo.ts'` 写法继续可用，新代码可直引 github-client。
-export { NO_COMPRESSION, RepoFetchError, apiHeaders, fetchError, fetchJson, fetchJsonCached, githubAuthHeaders, isAbortError, setGithubToken } from './repo/github-client.ts'
+export { NO_COMPRESSION, RepoFetchError, apiHeaders, fetchError, fetchJson, fetchJsonCached, githubAuthHeaders, isAbortError, rateLimitResetAt, setGithubToken } from './repo/github-client.ts'
 
 export type { RepoRef, RepoTreeItem, RepoFile } from './repo/types.ts'
 

package/src/routes/catalog-data.ts

@@ -17,10 +17,21 @@ import { rootPath, readSkillInterface, scanDiagnostics, type SkillInterface } fr
 import { CURRENT_VERSION } from '../update.ts'
 import { homeOf, isWritableSource, type SkillHubRouteDeps } from './deps.ts'
 
-/** 目录中存在的技能名集合（tag 成员校验用）：启用目录 ∪ 已禁用名单，避免成员因禁用而丢失。 */
-export async function knownSkillNames(deps: SkillHubRouteDeps): Promise<Set<string>> {
+/**
+ * 目录中存在的技能名集合。默认（`includeDisabled` 未显式关闭）为「启用目录 ∪
+ * 已禁用名单」——tag 成员校验用：技能被禁用后不该从 tag 里掉出去。
+ *
+ * 导入去重必须传 `{ includeDisabled: false }`：禁用只意味着「暂不启用」，把它
+ * 算作「已存在」会让一次禁用产生「永久占名」的副作用，真技能再也导不进来
+ * （issue #16）。
+ */
+export async function knownSkillNames(
+  deps: SkillHubRouteDeps,
+  options?: { includeDisabled?: boolean },
+): Promise<Set<string>> {
   const snapshot = await deps.skills.snapshot()
   const names = new Set(snapshot.skills.map((skill) => skill.name))
+  if (options?.includeDisabled === false) return names
   for (const disabled of await deps.store.listDisabled()) names.add(disabled.name)
   return names
 }
@@ -188,10 +199,13 @@ export async function buildCatalog(deps: SkillHubRouteDeps, cwd?: string): Promi
     if (iface !== undefined) applyInterface(row, iface)
     return row
   })
-  const diagnostics = [
-    ...(await scanDiagnostics('user-dsh', home)),
-    ...(await scanDiagnostics('user-agents', home)),
-  ]
+  // 两个 root 的诊断扫描互不依赖：面板每 5 秒轮询一次 /catalog，串行会让响应
+  // 随技能数量线性变慢。扫描内部的逐条读盘也已是并发的（见 scanDiagnostics）。
+  const [userDshDiagnostics, userAgentsDiagnostics] = await Promise.all([
+    scanDiagnostics('user-dsh', home),
+    scanDiagnostics('user-agents', home),
+  ])
+  const diagnostics = [...userDshDiagnostics, ...userAgentsDiagnostics]
   return {
     ok: true,
     pluginVersion: CURRENT_VERSION,

package/src/routes/catalog.ts

@@ -3,8 +3,8 @@
  * create / stats。从 routes.ts 原样搬出，handler 逻辑不变。
  */
 
-import { mkdir, readFile, rename, stat } from 'node:fs/promises'
-import { basename, dirname, join } from 'node:path'
+import { readFile, stat } from 'node:fs/promises'
+import { dirname, join } 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, parseFrontmatter, readSkillInterface, rootOfPath, rootPath, trashSkill } from '../skillfs.ts'
+import { createSkill, disableSkill, enableSkill, moveIntoTrash, parseFrontmatter, readSkillInterface, rootOfPath, rootPath, trashSkill } from '../skillfs.ts'
 import { errorText } from '../error-text.ts'
 import {
   applyInterface,
@@ -156,12 +156,7 @@ export function catalogRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
             }
             // 禁用态：SKILL.md.disabled 或 *.md.disabled，直接将其所在技能整体移入回收站
             const isBundleDisabled = disabled.path.endsWith('SKILL.md.disabled')
-            const sourceToTrash = isBundleDisabled ? dirname(disabled.path) : disabled.path
-            const trashDir = join(dirname(sourceToTrash), '.trash')
-            await mkdir(trashDir, { recursive: true })
-            const target = join(trashDir, basename(sourceToTrash) + '-' + Date.now())
-            await rename(sourceToTrash, target)
-            trashResult = { path: target, source: sourceToTrash }
+            trashResult = await moveIntoTrash(isBundleDisabled ? dirname(disabled.path) : disabled.path)
           } else {
             writeError(res, resolved.status, resolved.error); return
           }

package/src/routes/deps.ts

@@ -43,10 +43,15 @@ export interface SkillHubRouteDeps {
 
 /** The resolved hub config a route sees (the shared resolver fills defaults). */
 export function configOf(deps: SkillHubRouteDeps): HubConfig {
-  return resolveHubConfig({}, deps.config?.() ?? {})
+  return resolveHubConfig(deps.config?.() ?? {})
 }
 
-/** The raw saved config layer a route reports (empty when the owner omits it). */
+/**
+ * The raw saved config layer as persisted in the sidecar, reported for display
+ * only. Since dsh 0.1.7 the settings namespace is the one user layer, so this
+ * is legacy data: nothing writes it any more and the effective config above
+ * never merges it.
+ */
 export function savedOf(deps: SkillHubRouteDeps): Partial<HubConfig> {
   return deps.saved?.() ?? {}
 }

package/src/routes/market.ts

@@ -7,6 +7,7 @@
 import {
   SKILL_HUB_API,
   type MarketCheckResponse,
+  type MarketSourceAddResponse,
   type MarketSourceResponse,
   type MarketSourcesResponse,
   type MarketSourceVersionsResponse,
@@ -60,6 +61,13 @@ export function marketRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
       }
       try {
         const latestTag = await getLatestReleaseTag(source.repo)
+        // Book the attempt as soon as the GitHub call has been spent, before
+        // the unpinned branch below can `continue`: otherwise an unpinned
+        // source never records a timestamp and the 5-minute throttle promised
+        // above never applies to it (every check re-hits /releases/latest).
+        // A call that throws is deliberately not booked, so a failing repo is
+        // retried on the next check — same as the source check in sources.ts.
+        lastMarketCheck.set(source.repo, now)
         if (source.ref === undefined) {
           // Not pinned yet: report the latest release so the UI can
           // suggest pinning, but never claim an update.
@@ -67,7 +75,6 @@ export function marketRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
           continue
         }
         const latest = await getLatestCommit(source.repo, source.ref)
-        lastMarketCheck.set(source.repo, now)
         const commitMoved = source.commitSha !== undefined && latest.commitSha !== source.commitSha
         const newRelease = latestTag !== undefined && latestTag !== source.ref
         results.push({ ...base, updateAvailable: commitMoved || newRelease, commitSha: latest.commitSha, ...(newRelease ? { latestTag } : {}) })
@@ -99,7 +106,11 @@ export function marketRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
         // An explicit @ref pins the source immediately (e.g. repo@v1.2.3);
         // otherwise the first scan resolves latest-release / branch choice.
         const ref = parsed.ref
-        writeJson(res, 200, { ok: true, repos: await deps.store.addMarketSource(repoSlug(parsed), ref) } satisfies MarketSourceResponse)
+        const slug = repoSlug(parsed)
+        // Return the normalized slug explicitly: the client scans it right
+        // away, and `repos` order carries no "this one" signal (re-adding an
+        // existing repo only rewrites its ref in place).
+        writeJson(res, 200, { ok: true, repo: slug, repos: await deps.store.addMarketSource(slug, ref) } satisfies MarketSourceAddResponse)
       },
     },
     {

package/src/routes/repo-import.ts

@@ -4,7 +4,7 @@
  */
 
 import { mkdir } from 'node:fs/promises'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import {
   SKILL_HUB_API,
@@ -28,7 +28,7 @@ import {
   skillManifest,
   skillPathIn,
 } from '../repo.ts'
-import { rootPath } from '../skillfs.ts'
+import { moveIntoTrash, rootPath } from '../skillfs.ts'
 import { errorText } from '../error-text.ts'
 import {
   homeOf,
@@ -44,6 +44,29 @@ import {
 } from './helpers.ts'
 import { gcImportJobs, importJobs, type ImportJob } from './route-state.ts'
 
+/**
+ * 导入去重只认「已启用」的目录，但磁盘上仍可能躺着一个已禁用的同名占位 ——
+ * 禁用只是把 SKILL.md 改名成 SKILL.md.disabled，目录本身还在。这种占位不该
+ * 堵住真技能：把它连同禁用记录一起移入回收站让位（issue #16）。
+ *
+ * 只有「禁用记录确实指向 `targetRoot/<name>` 的整目录禁用」才处理，且该目录
+ * 必须已经没有 SKILL.md；其余不确定情形一律返回 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
+}
+
 /** 仓库导入域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
 export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
   return [
@@ -86,7 +109,8 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
           }
         }
         const { ref: resolvedRef, tree, truncated } = await loadRepoTree(repo, ref)
-        const existing = await knownSkillNames(deps)
+        // 发现态也只看「已启用」：否则已禁用占位会把真技能标成「已存在」并禁掉勾选（issue #16）。
+        const existing = await knownSkillNames(deps, { includeDisabled: false })
         const entries = discoverRepoEntries(tree, repo, existing)
         writeJson(res, 200, { ok: true, repo, ref: resolvedRef, entries, ...(truncated ? { truncated: true } : {}) } satisfies RepoDiscoverResponse)
       },
@@ -108,7 +132,8 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
         const requestedRef = readString(body, 'ref')
         const ref = requestedRef !== '' ? requestedRef : parsed.ref
         const { ref: resolvedRef, tree } = await loadRepoTree(repo, ref)
-        const existing = await knownSkillNames(deps)
+        // 导入去重同 discover：已禁用不算「已存在」（issue #16）。
+        const existing = await knownSkillNames(deps, { includeDisabled: false })
         const entries = discoverRepoEntries(tree, repo, existing)
         // truncated tree is still usable for the selected paths the user already picked from the prior discover response
         const byPath = new Map(entries.map((entry) => [entry.path, entry]))
@@ -139,6 +164,7 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
           imported: [],
           skipped: [],
           failed: [],
+          replaced: [],
           status: 'running',
           controller,
           createdAt: now,
@@ -166,11 +192,25 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
               job.done += 1
               continue
             }
+            // 磁盘上有同名目录。若它只是一个已禁用的占位（目录里只剩
+            // SKILL.md.disabled），先把旧目录移入回收站再继续导入；移不动或
+            // 不是这种形态时退回原本的「跳过」（issue #16）。
             if (await pathExists(join(targetRoot, entry.name))) {
-              job.skipped.push({ name: entry.name, reason: 'exists' })
-              job.downloadedBytes += entry.totalBytes
-              job.done += 1
-              continue
+              let cleared = false
+              try {
+                cleared = await clearDisabledPlaceholder(deps, targetRoot, entry.name)
+              } catch {
+                cleared = false
+              }
+              if (!cleared) {
+                job.skipped.push({ name: entry.name, reason: 'exists' })
+                job.downloadedBytes += entry.totalBytes
+                job.done += 1
+                continue
+              }
+              // 旧目录已经进了回收站（可恢复）。即使随后的下载失败也必须如实
+              // 上报，否则用户不知道自己的占位被挪走了。
+              job.replaced.push(entry.name)
             }
             if (controller.signal.aborted) break
             const files = collectRepoSkillFiles(tree, entry.dir)
@@ -241,6 +281,7 @@ export function repoImportRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
           imported: [...job.imported],
           skipped: [...job.skipped],
           failed: [...job.failed],
+          ...(job.replaced.length > 0 ? { replaced: [...job.replaced] } : {}),
           ...(job.error !== undefined ? { error: job.error } : {}),
         } satisfies RepoImportProgressResponse)
       },

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

@@ -16,6 +16,7 @@ function job(jobId: string, createdAt: number, status: ImportJob['status'] = 'do
     imported: [],
     skipped: [],
     failed: [],
+    replaced: [],
     status,
     controller: new AbortController(),
     createdAt,

package/src/routes/route-state.ts

@@ -51,6 +51,11 @@ export interface ImportJob {
   imported: Array<{ name: string; origin: string; path: string }>
   skipped: Array<{ name: string; reason: 'exists' }>
   failed: Array<{ name: string; error: string }>
+  /**
+   * 导入时被移入回收站让位的「已禁用同名占位」名字（issue #16）。占位已挪走
+   * 即计入，即使随后的下载失败也在列 —— 否则用户不知道自己的占位不见了。
+   */
+  replaced: string[]
   status: 'running' | 'done' | 'cancelled' | 'error'
   error?: string
   controller: AbortController

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'
@@ -695,6 +763,125 @@ describe('skill-hub routes', () => {
     }
   })
 
+  // ------------------------------------ 导入去重 vs 已禁用占位（issue #16）
+  /** 造一个「已禁用同名占位」：目录还在，SKILL.md 被改名成 SKILL.md.disabled。 */
+  async function seedDisabledPlaceholder(name: string) {
+    const dir = join(home, 'skills', name)
+    await mkdir(dir, { recursive: true })
+    await writeFile(join(dir, 'SKILL.md.disabled'), `---\nname: ${name}\ndescription: stub\n---\n`, 'utf8')
+    await store.addDisabled({
+      name,
+      description: 'stub',
+      path: join(dir, 'SKILL.md.disabled'),
+      root: 'user-dsh',
+      disabledAt: Date.now(),
+    })
+    return dir
+  }
+
+  it('does not flag a hub-disabled placeholder as existing when discovering', async () => {
+    await seedDisabledPlaceholder('code-review')
+    stubFetch([
+      ['repos/example/repo/releases/latest', jsonResponse({ tag_name: 'v1.0.0' })],
+      ['repos/example/repo/git/trees/v1.0.0', jsonResponse({ tree: [
+        { path: 'skills/code-review/SKILL.md', type: 'blob', size: 60 },
+      ] })],
+      ['repos/example/repo', jsonResponse({ default_branch: 'main' })],
+    ])
+    try {
+      const res = new FakeResponse()
+      await routeFor(SKILL_HUB_API.repo).handler(fakeReq('GET', `${SKILL_HUB_API.repo}?repo=example/repo`), res as never)
+      expect(res.status).toBe(200)
+      const body = res.json() as import('./protocol.ts').RepoDiscoverResponse
+      expect(body.ref).toBe('v1.0.0')
+      // 禁用只该影响启用态；被算成 existing 会让勾选框直接 disabled，用户无从下手。
+      expect(body.entries).toHaveLength(1)
+      expect(body.entries[0]).toMatchObject({ name: 'code-review', existing: false })
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  it('imports over a hub-disabled placeholder instead of skipping it', async () => {
+    const dir = await seedDisabledPlaceholder('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)
+      expect(res.status).toBe(200)
+      const created = res.json() as import('./protocol.ts').RepoImportResponse
+      let prog: import('./protocol.ts').RepoImportProgressResponse | undefined
+      for (let i = 0; i < 20; i++) {
+        await new Promise((r) => setTimeout(r, 50))
+        const progRes = new FakeResponse()
+        await routeFor(SKILL_HUB_API.repoImportProgress).handler(fakeReq('GET', `${SKILL_HUB_API.repoImportProgress}?jobId=${created.jobId}`), progRes as never)
+        prog = progRes.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(readFile(join(dir, 'SKILL.md'), 'utf8')).resolves.toContain('name: code-review')
+      // 旧占位进回收站（可恢复），禁用记录被清掉，不然目录会留个幽灵禁用项。
+      await expect(access(join(dir, 'SKILL.md.disabled'))).rejects.toThrow()
+      expect(await store.listDisabled()).toEqual([])
+      const trash = await store.listTrash()
+      expect(trash).toHaveLength(1)
+      expect(trash[0].name).toBe('code-review')
+      expect(trash[0].path.startsWith(join(home, 'skills', '.trash', 'code-review-'))).toBe(true)
+      expect(trash[0].sourcePath).toBe(dir)
+      expect(await store.listSources()).toHaveLength(1)
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
+  it('still skips a same-name directory that is not a disabled placeholder', async () => {
+    // 同名目录里还有真实 SKILL.md、且没有对应的禁用记录：不是占位，不许动。
+    const dir = join(home, 'skills', 'code-review')
+    await mkdir(dir, { recursive: true })
+    await writeFile(join(dir, 'SKILL.md'), '---\nname: code-review\ndescription: real\n---\n', 'utf8')
+    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' })],
+    ])
+    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 < 20; i++) {
+        await new Promise((r) => setTimeout(r, 50))
+        const progRes = new FakeResponse()
+        await routeFor(SKILL_HUB_API.repoImportProgress).handler(fakeReq('GET', `${SKILL_HUB_API.repoImportProgress}?jobId=${created.jobId}`), progRes as never)
+        prog = progRes.json() as import('./protocol.ts').RepoImportProgressResponse
+        if (prog.status !== 'running') break
+      }
+      expect(prog!.status).toBe('done')
+      expect(prog!.skipped).toEqual([{ name: 'code-review', reason: 'exists' }])
+      expect(prog!.imported).toEqual([])
+      expect(prog!.replaced ?? []).toEqual([])
+      // 原目录原封不动，也没进回收站。
+      await expect(readFile(join(dir, 'SKILL.md'), 'utf8')).resolves.toContain('description: real')
+      expect(await store.listTrash()).toEqual([])
+    } finally {
+      vi.unstubAllGlobals()
+    }
+  })
+
   // -------------------------------------------------------------- groups
   it('serves groups: user tags + system collections + origins', async () => {
     const tag = await store.saveTag({ name: 'web' })

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 {
@@ -130,7 +131,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,33 +170,40 @@ 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)
+  // 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
@@ -201,13 +211,16 @@ export async function scanDiagnostics(root: WritableRoot, home = dshHome()): Pro
     // the skill show up under a different identity than its metadata claims.
     const pathName = entry.kind === 'directory' ? basename(entry.directory) : basename(entry.path, '.md')
     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 diagnostics
+    return found
+  })
+  // mapConcurrent preserves index order, so flattening keeps the previous
+  // per-entry ordering of the diagnostics.
+  return perEntry.flat()
 }