dsh-skill-hub 0.3.7 → 0.3.8

package/src/routes/catalog.ts

@@ -0,0 +1,309 @@
+/**
+ * 目录域路由：catalog / skill 详情 / skill 删除 / toggle / toggle-batch /
+ * create / stats。从 routes.ts 原样搬出，handler 逻辑不变。
+ */
+
+import { mkdir, readFile, rename, stat } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import type { SkillDefinition } from '@deepseek-ai/dsh-skill'
+import { isSkillName } from '@deepseek-ai/dsh-skill'
+import {
+  SKILL_HUB_API,
+  type CreateRequest,
+  type CreateResponse,
+  type SkillDeleteRequest,
+  type SkillDeleteResponse,
+  type SkillDetail,
+  type SkillDetailResponse,
+  type StatsResponse,
+  type ToggleBatchRequest,
+  type ToggleBatchResponse,
+  type ToggleRequest,
+  type ToggleResponse,
+  type WritableRoot,
+} from '../protocol.ts'
+import { createSkill, disableSkill, enableSkill, parseFrontmatter, readSkillInterface, rootPath, trashSkill } from '../skillfs.ts'
+import {
+  buildCatalog,
+  homeOf,
+  pathExists,
+  queryParam,
+  resolveWritableSkill,
+  toDetail,
+  workspaceEntries,
+  writeError,
+  writeJson,
+  type RouteSpec,
+  type SkillHubRouteDeps,
+} from './helpers.ts'
+
+/** 目录域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
+export function catalogRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
+  return [
+    // ------------------------------------------------------------ catalog
+    {
+      path: SKILL_HUB_API.catalog,
+      methods: ['GET'],
+      handler: async ({ res, url }) => {
+        const cwd = queryParam(url, 'cwd')
+        writeJson(res, 200, await buildCatalog(deps, cwd))
+      },
+    },
+    // -------------------------------------------------------------- detail
+    {
+      path: SKILL_HUB_API.skill,
+      methods: ['GET'],
+      handler: async ({ res, url }) => {
+        const name = queryParam(url, 'name')
+        if (name === undefined || name === '') { writeError(res, 400, 'name query parameter is required'); return }
+        const cwd = queryParam(url, 'cwd')
+        // 显式 cwd 只看该工作区；否则按已知工作区逐个查找（与目录默认视图
+        // 一致），最后回退用户级根，保证默认视图里可见的项目技能能打开详情。
+        let skill: SkillDefinition | undefined
+        if (cwd !== undefined && cwd !== '') {
+          skill = await deps.skills.get(name, { cwd })
+        } else {
+          for (const ws of await workspaceEntries(homeOf(deps))) {
+            skill = await deps.skills.get(name, { cwd: ws.path })
+            if (skill !== undefined) break
+          }
+          if (skill === undefined) skill = await deps.skills.get(name)
+        }
+        if (skill === undefined) {
+          // Hub-disabled skills live outside registry discovery (renamed to .disabled);
+          // serve their detail straight from the sidecar record + file.
+          const record = await deps.store.getDisabled(name)
+          if (record !== undefined) {
+            try {
+              const text = await readFile(record.path, 'utf8')
+              const parsed = parseFrontmatter(text)
+              if (!('error' in parsed)) {
+                const disabledDetail: SkillDetail = {
+                  name: record.name,
+                  description: parsed.value.description,
+                  ...(parsed.value.whenToUse !== undefined ? { whenToUse: parsed.value.whenToUse } : {}),
+                  invocation: { ...parsed.value.invocation },
+                  provider: 'skill-hub (disabled)',
+                  path: record.path,
+                  content: parsed.value.content,
+                }
+                try {
+                  const times = await stat(record.path)
+                  disabledDetail.addedAt = times.birthtimeMs
+                  disabledDetail.updatedAt = times.mtimeMs
+                } catch {
+                  // ignore
+                }
+                writeJson(res, 200, { ok: true, skill: disabledDetail } satisfies SkillDetailResponse)
+                return
+              }
+            } catch {
+              // fall through to 404 below
+            }
+          }
+          writeError(res, 404, 'skill not found: ' + name)
+          return
+        }
+        const detail = toDetail(skill)
+        if (skill.path !== undefined) {
+          try {
+            const times = await stat(skill.path)
+            detail.addedAt = times.birthtimeMs
+            detail.updatedAt = times.mtimeMs
+          } catch {
+            // 文件不可读时省略时间字段，详情页不显示这两行。
+          }
+          // UI metadata from agents/openai.yaml beside the skill directory (codex).
+          try {
+            const rb = skill.resourceBase as { kind?: string; path?: string } | undefined
+            const dir = rb?.kind === 'directory' && typeof rb.path === 'string' ? rb.path : (skill.path.endsWith('SKILL.md') ? dirname(skill.path) : undefined)
+            if (dir !== undefined) {
+              const iface = await readSkillInterface(dir)
+              if (iface !== undefined) {
+                if (iface.displayName !== undefined) detail.displayName = iface.displayName
+                if (iface.shortDescription !== undefined) detail.shortDescription = iface.shortDescription
+                if (iface.brandColor !== undefined) detail.brandColor = iface.brandColor
+                if (iface.iconSmall !== undefined) detail.iconSmall = iface.iconSmall
+                if (iface.iconLarge !== undefined) detail.iconLarge = iface.iconLarge
+                if (iface.defaultPrompt !== undefined) detail.defaultPrompt = iface.defaultPrompt
+              }
+            }
+          } catch {
+            // best-effort
+          }
+        }
+        writeJson(res, 200, { ok: true, skill: detail } satisfies SkillDetailResponse)
+      },
+    },
+    // -------------------------------------------------------- skill/delete
+    // 把单个技能（目录或平面文件）移入回收站（可恢复），并清理禁用记录、tag 成员与来源映射。
+    {
+      path: SKILL_HUB_API.skillDelete,
+      methods: ['POST'],
+      jsonBody: true,
+      handler: async ({ res, body }) => {
+        const request = body as unknown as SkillDeleteRequest & { cwd?: string }
+        const name = typeof request.name === 'string' ? request.name : ''
+        if (name === '') { writeError(res, 400, 'name is required'); return }
+        const resolved = await resolveWritableSkill(deps, name, typeof request.cwd === 'string' ? request.cwd : undefined)
+        // 已禁用的技能不在 registry 中，resolve 会 404，这里单独处理：允许整组删除未开启的技能
+        let trashResult: { path: string; source: string } | null = null
+        if (!resolved.ok) {
+          const disabled = await deps.store.getDisabled(name)
+          if (disabled !== undefined) {
+            // 禁用态：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 }
+          } else {
+            writeError(res, resolved.status, resolved.error); return
+          }
+        }
+        // 入回收站前快照来源归属与场景成员：恢复时把它们加回来，否则恢复
+        // 后的技能会丢失来源（变成「个人技能」）和场景分组。
+        const tracked = await deps.store.getSourceForSkill(name)
+        const tagIds = (await deps.store.listTags()).filter((tag) => tag.skillNames.includes(name)).map((tag) => tag.id)
+        const { path, source } = trashResult ?? await trashSkill((resolved as { ok: true; path: string }).path)
+        await deps.store.addTrash({
+          name,
+          path,
+          movedAt: Date.now(),
+          sourcePath: source,
+          ...(tracked !== undefined
+            ? { origin: { repo: tracked.repo, root: tracked.root, ...(tracked.ref !== undefined && tracked.ref !== '' ? { ref: tracked.ref } : {}), commitSha: tracked.commitSha } }
+            : {}),
+          ...(tagIds.length > 0 ? { tagIds } : {}),
+        })
+        await deps.store.removeDisabled(name)
+        await deps.store.removeSkillFromSources(name)
+        await deps.store.removeSkillFromTags(name)
+        deps.invalidate?.()
+        writeJson(res, 200, { ok: true, name, path } satisfies SkillDeleteResponse)
+      },
+    },
+    // -------------------------------------------------------------- toggle
+    {
+      path: SKILL_HUB_API.toggle,
+      methods: ['POST'],
+      jsonBody: true,
+      handler: async ({ res, body }) => {
+        const request = body as unknown as ToggleRequest & { cwd?: string }
+        const name = typeof request.name === 'string' ? request.name : ''
+        if (name === '') { writeError(res, 400, 'name is required'); return }
+        const lookup = typeof request.cwd === 'string' && request.cwd !== '' ? { cwd: request.cwd } : undefined
+        if (request.enabled === true) {
+          const record = await deps.store.getDisabled(name)
+          if (record === undefined) { writeError(res, 404, 'skill is not hub-disabled: ' + name); return }
+          try {
+            await enableSkill(record.path)
+          } catch (error) {
+            // The renamed file may have vanished (external cleanup); report
+            // precisely instead of a generic 500, like toggle-batch does.
+            if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+              writeError(res, 409, 'disabled skill file is missing on disk: ' + record.path)
+              return
+            }
+            throw error
+          }
+          await deps.store.removeDisabled(name)
+        } else {
+          const resolved = await resolveWritableSkill(deps, name, typeof request.cwd === 'string' ? request.cwd : undefined)
+          if (!resolved.ok) { writeError(res, resolved.status, resolved.error); return }
+          const disabledPath = await disableSkill(resolved.path)
+          await deps.store.addDisabled({
+            name,
+            description: resolved.skill.description,
+            path: disabledPath,
+            root: resolved.root,
+            disabledAt: Date.now(),
+          })
+        }
+        deps.invalidate?.()
+        writeJson(res, 200, { ok: true, catalog: await buildCatalog(deps, lookup?.cwd) } satisfies ToggleResponse)
+      },
+    },
+    // -------------------------------------------------------- toggle-batch
+    // One write for a whole group: enables every hub-disabled name, or
+    // disables every writable name. Skips already-target states as no-ops;
+    // per-name failures are reported, never fatal.
+    {
+      path: SKILL_HUB_API.toggleBatch,
+      methods: ['POST'],
+      jsonBody: true,
+      handler: async ({ res, body }) => {
+        const request = body as unknown as ToggleBatchRequest & { cwd?: string }
+        const names = Array.isArray(request.names) ? request.names.filter((n): n is string => typeof n === 'string' && n !== '') : []
+        if (names.length === 0) { writeError(res, 400, 'names must be a non-empty array'); return }
+        const enabled = request.enabled === true
+        const lookup = typeof request.cwd === 'string' && request.cwd !== '' ? { cwd: request.cwd } : undefined
+        const failures: Array<{ name: string; error: string }> = []
+        for (const name of names) {
+          try {
+            if (enabled) {
+              const record = await deps.store.getDisabled(name)
+              if (record === undefined) continue // already enabled: no-op
+              await enableSkill(record.path)
+              await deps.store.removeDisabled(name)
+            } else {
+              const resolved = await resolveWritableSkill(deps, name, typeof request.cwd === 'string' ? request.cwd : undefined)
+              if (!resolved.ok) { failures.push({ name, error: resolved.error }); continue }
+              const disabledPath = await disableSkill(resolved.path)
+              await deps.store.addDisabled({ name, description: resolved.skill.description, path: disabledPath, root: resolved.root, disabledAt: Date.now() })
+            }
+          } catch (error) {
+            failures.push({ name, error: error instanceof Error ? error.message : String(error) })
+          }
+        }
+        deps.invalidate?.()
+        writeJson(res, 200, { ok: true, catalog: await buildCatalog(deps, lookup?.cwd), failures } satisfies ToggleBatchResponse)
+      },
+    },
+    // -------------------------------------------------------------- create
+    {
+      path: SKILL_HUB_API.create,
+      methods: ['POST'],
+      jsonBody: true,
+      handler: async ({ res, body }) => {
+        const request = body as unknown as CreateRequest
+        const name = typeof request.name === 'string' ? request.name.trim() : ''
+        if (!isSkillName(name)) { writeError(res, 400, 'skill name must be kebab-case (lowercase letters, digits, dashes)'); return }
+        const root: WritableRoot = request.root ?? 'user-dsh'
+        if (root !== 'user-dsh' && root !== 'user-agents') { writeError(res, 400, 'root must be user-dsh or user-agents'); return }
+        const existing = await deps.skills.get(name)
+        if (existing !== undefined) { writeError(res, 409, 'skill name already exists: ' + name); return }
+        if (await deps.store.getDisabled(name) !== undefined) { writeError(res, 409, 'skill name is disabled: re-enable it from the disabled list first'); return }
+        // A directory may exist without producing a registry entry (invalid
+        // frontmatter — exactly what the diagnostics section reports).
+        // Refuse to overwrite it instead of silently truncating its SKILL.md.
+        const target = join(rootPath(root, homeOf(deps)), name)
+        if (await pathExists(target)) {
+          writeError(res, 409, 'skill directory already exists on disk: ' + name + ' (check the discovery diagnostics)')
+          return
+        }
+        const path = await createSkill(root, name, typeof request.description === 'string' ? request.description : '', homeOf(deps))
+        // 新技能自动归入默认场景（「通用」）。
+        const defaultTag = await deps.store.getDefaultTag()
+        if (defaultTag !== undefined) await deps.store.addSkillToTag(defaultTag.id, name)
+        deps.invalidate?.()
+        writeJson(res, 201, { ok: true, path, root } satisfies CreateResponse)
+      },
+    },
+    // ---------------------------------------------------------------- stats
+    {
+      path: SKILL_HUB_API.stats,
+      methods: ['GET'],
+      handler: async ({ res }) => {
+        if (deps.stats === undefined) {
+          writeJson(res, 200, { ok: true, available: false, stats: [] } satisfies StatsResponse)
+          return
+        }
+        const stats = await deps.stats()
+        writeJson(res, 200, { ok: true, available: true, stats } satisfies StatsResponse)
+      },
+    },
+  ]
+}

package/src/routes/config.ts

@@ -0,0 +1,119 @@
+/**
+ * 配置域路由：config（总开关开着也可用，设置卡自救入口）/ update 自身更新
+ * 检查 / diagnosticFix。从 routes.ts 原样搬出，handler 逻辑不变。
+ */
+
+import {
+  SKILL_HUB_API,
+  GITHUB_TOKEN_RE,
+  HEX_COLOR_RE,
+  type ConfigResponse,
+  type DiagnosticFixRequest,
+  type DiagnosticFixResponse,
+  type HubConfig,
+} from '../protocol.ts'
+import { fixDiagnosticFile } from '../skillfs.ts'
+import { checkLatestRelease, CURRENT_VERSION } from '../update.ts'
+import {
+  configOf,
+  homeOf,
+  savedOf,
+  writeError,
+  writeJson,
+  writeRouteError,
+  type RouteSpec,
+  type SkillHubRouteDeps,
+} from './helpers.ts'
+
+/** 配置域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
+export function configRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
+  return [
+    // --------------------------------------------------------------- config
+    // The config route stays mounted even with the master switch off, so the
+    // settings card can always read and re-enable the hub.
+    {
+      path: SKILL_HUB_API.config,
+      methods: ['GET', 'POST'],
+      jsonBody: true,
+      skipGate: true,
+      handler: async ({ req, res, body }) => {
+        if (req.method === 'GET') {
+          writeJson(res, 200, { ok: true, pluginVersion: CURRENT_VERSION, config: configOf(deps), saved: savedOf(deps) } satisfies ConfigResponse)
+          return
+        }
+        const raw = body
+        const patch: Partial<HubConfig> = {}
+        if (raw.enabled !== undefined) {
+          if (raw.enabled === null) patch.enabled = undefined
+          else if (typeof raw.enabled !== 'boolean') { writeError(res, 400, 'enabled must be a boolean or null'); return }
+          else patch.enabled = raw.enabled
+        }
+        if (raw.announceToAgent !== undefined) {
+          if (raw.announceToAgent === null) patch.announceToAgent = undefined
+          else if (typeof raw.announceToAgent !== 'boolean') { writeError(res, 400, 'announceToAgent must be a boolean or null'); return }
+          else patch.announceToAgent = raw.announceToAgent
+        }
+        for (const key of ['showUseCount', 'showUseTime', 'showGroupSummary'] as const) {
+          const value = raw[key]
+          if (value === undefined) continue
+          if (value === null) { patch[key] = undefined; continue }
+          if (typeof value !== 'boolean') { writeError(res, 400, key + ' must be a boolean or null'); return }
+          patch[key] = value
+        }
+        for (const key of ['dotModelColor', 'dotUserColor'] as const) {
+          const value = raw[key]
+          if (value === undefined) continue
+          if (value === null) { patch[key] = undefined; continue }
+          if (typeof value !== 'string' || !HEX_COLOR_RE.test(value)) { writeError(res, 400, key + ' must be a #rrggbb color or null'); return }
+          patch[key] = value
+        }
+        if (raw.githubToken !== undefined) {
+          const value = raw.githubToken
+          if (value === null) { patch.githubToken = undefined; /* cleared → anonymous/env */ }
+          else if (typeof value !== 'string' || value.trim() === '') { patch.githubToken = undefined }
+          else if (!GITHUB_TOKEN_RE.test(value.trim())) { writeError(res, 400, 'githubToken looks invalid (expected a personal access token)'); return }
+          else patch.githubToken = value.trim()
+        }
+        let config: HubConfig
+        if (deps.updateConfig === undefined) {
+          const merged: HubConfig = { ...configOf(deps) }
+          for (const [key, value] of Object.entries(patch) as Array<[keyof HubConfig, boolean | string | undefined]>) {
+            if (value === undefined) delete merged[key]
+            else (merged as unknown as Record<string, unknown>)[key] = value
+          }
+          config = merged
+        } else {
+          config = await deps.updateConfig(patch)
+        }
+        writeJson(res, 200, { ok: true, pluginVersion: CURRENT_VERSION, config, saved: savedOf(deps) } satisfies ConfigResponse)
+      },
+    },
+    // -------------------------------------------------------------- update
+    // 自身更新检查：查询 GitHub latest release。
+    {
+      path: SKILL_HUB_API.update,
+      methods: ['GET'],
+      handler: async ({ res }) => {
+        writeJson(res, 200, await checkLatestRelease())
+      },
+    },
+    // -------------------------------------------------------- diagnostic fix
+    {
+      path: SKILL_HUB_API.diagnosticFix,
+      methods: ['POST'],
+      jsonBody: true,
+      handler: async ({ res, body }) => {
+        const request = body as unknown as DiagnosticFixRequest
+        const rawPath = typeof request.path === 'string' ? request.path.trim() : ''
+        if (rawPath === '') { writeError(res, 400, 'path is required'); return }
+        try {
+          await fixDiagnosticFile(rawPath, homeOf(deps))
+          deps.invalidate?.()
+          writeJson(res, 200, { ok: true, path: rawPath } satisfies DiagnosticFixResponse)
+        } catch (error) {
+          writeRouteError(res, error)
+        }
+      },
+    },
+  ]
+}

package/src/routes/groups.ts

@@ -0,0 +1,133 @@
+/**
+ * 分组域路由：groups / tag 新建重命名 / tag 删除 / tag 成员 / tag 重排 /
+ * collection 重排 / source-group 重排。从 routes.ts 原样搬出，handler 逻辑不变。
+ */
+
+import {
+  SKILL_HUB_API,
+  type CollectionReorderRequest,
+  type CollectionReorderResponse,
+  type SourceGroupReorderRequest,
+  type SourceGroupReorderResponse,
+  type TagDeleteRequest,
+  type TagDeleteResponse,
+  type TagMembersRequest,
+  type TagMembersResponse,
+  type TagReorderRequest,
+  type TagReorderResponse,
+  type TagSaveResponse,
+} from '../protocol.ts'
+import { StoreError } from '../store.ts'
+import {
+  buildGroups,
+  knownSkillNames,
+  writeError,
+  writeJson,
+  type RouteSpec,
+  type SkillHubRouteDeps,
+} from './helpers.ts'
+
+/** 分组域全部路由 spec（由 routes.ts 经 createRoute 包上统一围栏）。 */
+export function groupRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
+  return [
+    // -------------------------------------------------------------- groups
+    // 用户 tag 分组 + 系统集合组 + origin 映射（前端分组栏的数据源）。
+    {
+      path: SKILL_HUB_API.groups,
+      methods: ['GET'],
+      handler: async ({ res }) => {
+        writeJson(res, 200, await buildGroups(deps))
+      },
+    },
+    // ----------------------------------------------------------------- tag
+    // 新建（缺省 id）或重命名（带 id）一个用户 tag 分组。
+    {
+      path: SKILL_HUB_API.tag,
+      methods: ['POST'],
+      jsonBody: true,
+      handler: async ({ res, body }) => {
+        const name = typeof body.name === 'string' ? body.name.trim() : ''
+        if (name === '') { writeError(res, 400, 'tag name is required'); return }
+        const id = typeof body.id === 'string' && body.id !== '' ? body.id : undefined
+        await deps.store.saveTag({ id, name })
+        writeJson(res, 200, { ok: true, tags: await deps.store.listTags() } satisfies TagSaveResponse)
+      },
+    },
+    // ----------------------------------------------------------- tag/delete
+    {
+      path: SKILL_HUB_API.tagDelete,
+      methods: ['POST'],
+      jsonBody: true,
+      handler: async ({ res, body }) => {
+        const id = typeof (body as unknown as TagDeleteRequest).id === 'string' ? (body as unknown as TagDeleteRequest).id : ''
+        if (id === '') { writeError(res, 400, 'tag id is required'); return }
+        const tag = await deps.store.getTag(id)
+        if (tag?.default === true) { writeError(res, 409, 'the default scene cannot be deleted'); return }
+        await deps.store.deleteTag(id)
+        writeJson(res, 200, { ok: true, tags: await deps.store.listTags() } satisfies TagDeleteResponse)
+      },
+    },
+    // ---------------------------------------------------------- tag/members
+    // 直接设置某 tag 的完整成员列表；后端只保留目录中实际存在的技能名。
+    {
+      path: SKILL_HUB_API.tagMembers,
+      methods: ['POST'],
+      jsonBody: true,
+      handler: async ({ res, body }) => {
+        const request = body as unknown as TagMembersRequest
+        const id = typeof request.id === 'string' ? request.id : ''
+        if (id === '') { writeError(res, 400, 'tag id is required'); return }
+        const names = Array.isArray(request.skillNames) ? request.skillNames.filter((n): n is string => typeof n === 'string') : []
+        const known = await knownSkillNames(deps)
+        const saved = await deps.store.setTagMembers(id, names.filter((n) => known.has(n)))
+        if (saved === undefined) { writeError(res, 404, 'tag not found: ' + id); return }
+        writeJson(res, 200, { ok: true, tags: await deps.store.listTags() } satisfies TagMembersResponse)
+      },
+    },
+    // ---------------------------------------------------------- tag/reorder
+    // 拖拽重排场景分组顺序
+    {
+      path: SKILL_HUB_API.tagReorder,
+      methods: ['POST'],
+      jsonBody: true,
+      handler: async ({ res, body }) => {
+        const request = body as unknown as TagReorderRequest
+        const orderedIds = Array.isArray(request.orderedIds) ? request.orderedIds.filter((id): id is string => typeof id === 'string' && id !== '') : []
+        try {
+          const tags = await deps.store.reorderTags(orderedIds)
+          writeJson(res, 200, { ok: true, tags } satisfies TagReorderResponse)
+        } catch (error) {
+          if (error instanceof StoreError) { writeError(res, error.kind === 'validation' ? 400 : error.kind === 'not-found' ? 404 : 409, error.message); return }
+          throw error
+        }
+      },
+    },
+    // ------------------------------------------------- collection/reorder
+    // 拖拽重排来源集合顺序
+    {
+      path: SKILL_HUB_API.collectionReorder,
+      methods: ['POST'],
+      jsonBody: true,
+      handler: async ({ res, body }) => {
+        const request = body as unknown as CollectionReorderRequest
+        const orderedNames = Array.isArray(request.orderedNames) ? request.orderedNames.filter((n): n is string => typeof n === 'string' && n !== '') : []
+        const order = await deps.store.reorderCollections(orderedNames)
+        const groups = await buildGroups(deps)
+        writeJson(res, 200, { ok: true, collections: groups.collections, order } satisfies CollectionReorderResponse)
+      },
+    },
+    // ------------------------------------------------ source-group/reorder
+    // 拖拽重排来源顶层分组（project / collections / personal 统一顺序）
+    {
+      path: SKILL_HUB_API.sourceGroupReorder,
+      methods: ['POST'],
+      jsonBody: true,
+      handler: async ({ res, body }) => {
+        const request = body as unknown as SourceGroupReorderRequest
+        const orderedKeys = Array.isArray(request.orderedKeys) ? request.orderedKeys.filter((k): k is string => typeof k === 'string' && k !== '') : []
+        const order = await deps.store.reorderSourceGroups(orderedKeys)
+        writeJson(res, 200, { ok: true, order } satisfies SourceGroupReorderResponse)
+      },
+    },
+  ]
+}