dsh-skill-hub 0.3.7 → 0.3.8

package/src/stats.test.ts

@@ -199,6 +199,29 @@ async function flush(): Promise<void> {
   await new Promise((resolve) => setTimeout(resolve, 20))
 }
 
+describe('scan read concurrency', () => {
+  it('reads session logs in parallel, not one by one', async () => {
+    const ids = Array.from({ length: 8 }, (_, i) => 's' + i)
+    let inFlight = 0
+    let peak = 0
+    const query: SessionQueryLike = {
+      listSessions: async () => ids.map((id) => record(id)),
+      readSession: async (id) => {
+        inFlight += 1
+        peak = Math.max(peak, inFlight)
+        await new Promise((resolve) => setTimeout(resolve, 5))
+        inFlight -= 1
+        return { events: [invocationEvent(String(id))] }
+      },
+    }
+    // No checkpoint → full path, all 8 sessions read.
+    const stats = await readSkillStats(query)
+    expect(stats).toHaveLength(8)
+    expect(peak).toBeGreaterThan(1)
+    expect(peak).toBeLessThanOrEqual(6)
+  })
+})
+
 describe('frozen-bucket incremental scans', () => {
   it('skips frozen sessions and merges checkpoint totals with the recent window', async () => {
     const reads: string[] = []
@@ -221,15 +244,15 @@ describe('frozen-bucket incremental scans', () => {
       },
       onCheckpoint: () => { checkpoints += 1 },
     })
-    expect(await reader()).toEqual([]) // 首次调用不等待扫描
+    expect(await reader()).toEqual([]) // 首次调用不等待扫描（无上次总数可端）
     await flush()
     expect(await reader()).toEqual([
       { name: 'oldskill', count: 5, lastUsed: NOW - 20 * DAY },
       { name: 'tdd', count: 2, lastUsed: 0 },
     ])
-    // 冻结会话没有被重读；增量扫描不改检查点 → 不触发持久化回调。
+    // 冻结会话没有被重读；增量扫描也落盘（含新总数）→ 回调恰好一次。
     expect(reads).toEqual(['fresh'])
-    expect(checkpoints).toBe(0)
+    expect(checkpoints).toBe(1)
   })
 
   it('runs a full reconciliation when due: rebuilds the frozen bucket and advances the watermark', async () => {
@@ -263,9 +286,41 @@ describe('frozen-bucket incremental scans', () => {
       // 全历史模式（windowDays=0）：冻结会话进缓存且仍计入总数。
       frozenSessions: { ancient: { createdAt: NOW - 30 * DAY, counts: { a: { count: 1, lastUsed: 5 } } } },
       lastFullReconcile: NOW,
+      lastTotals: [
+        { name: 'a', count: 1, lastUsed: 5 },
+        { name: 'b', count: 2, lastUsed: 0 },
+      ],
     })
   })
 
+  it('serves persisted lastTotals instantly on cold start, then merges the rescan', async () => {
+    const reads: string[] = []
+    const query = fakeQuery(
+      [record('fresh', NOW - 1 * DAY)],
+      { fresh: [invocationEvent('tdd', 1)] },
+      reads,
+    )
+    const saved: Array<Record<string, unknown>> = []
+    const reader = createSkillStatsReader(query, 60_000, {
+      now: () => NOW,
+      checkpoint: {
+        windowDays: 0,
+        frozenBefore: 0,
+        frozenSessions: {},
+        lastFullReconcile: NOW, // 对账刚做过 → 增量路径
+        lastTotals: [{ name: 'oldskill', count: 9, lastUsed: 7 }],
+      },
+      onCheckpoint: (cp) => { saved.push(cp as unknown as Record<string, unknown>) },
+    })
+    // 冷启动直接端上次总数，同时后台重扫；重扫后以新鲜值为准（旧数不复活）。
+    expect(await reader()).toEqual([{ name: 'oldskill', count: 9, lastUsed: 7 }])
+    await flush()
+    expect(await reader()).toEqual([{ name: 'tdd', count: 1, lastUsed: 0 }])
+    expect(reads).toEqual(['fresh'])
+    expect(saved).toHaveLength(1)
+    expect((saved[0] as { lastTotals: unknown }).lastTotals).toEqual([{ name: 'tdd', count: 1, lastUsed: 0 }])
+  })
+
   it('re-reads sessions without createdAt on incremental scans (never freezes)', async () => {
     const reads: string[] = []
     const query = fakeQuery(

package/src/stats.ts

@@ -103,6 +103,24 @@ function isFrozen(record: { header: { createdAt?: number } }, watermark: number)
   return typeof created === 'number' && created > 0 && created < watermark
 }
 
+/** Bounded-concurrency map: session-log reads are independent decompressions, so wall time scales ~1/limit. Merge stays sequential in index order. */
+async function mapConcurrent<T, R>(items: readonly T[], limit: number, worker: (item: T, index: number) => Promise<R>): Promise<R[]> {
+  const results = new Array<R>(items.length)
+  let cursor = 0
+  const runners = Array.from({ length: Math.min(Math.max(limit, 1), items.length) }, async () => {
+    while (cursor < items.length) {
+      const index = cursor
+      cursor += 1
+      results[index] = await worker(items[index], index)
+    }
+  })
+  await Promise.all(runners)
+  return results
+}
+
+/** Max parallel session-log reads per scan (read-only; merge is order-independent). */
+const SCAN_READ_CONCURRENCY = 6
+
 function mergeInto(totals: Totals, counted: Map<string, InvocationStat>): void {
   for (const [name, stat] of counted) {
     const total = totals[name]
@@ -153,19 +171,22 @@ async function scan(query: SessionQueryLike, checkpoint: SkillStatsCheckpoint, n
   if (dueFullScan) {
     const cache: SkillStatsCheckpoint['frozenSessions'] = {}
     const totals: Totals = {}
-    for (const record of sessions) {
-      let counted: Map<string, InvocationStat>
+    const countedList = await mapConcurrent(sessions, SCAN_READ_CONCURRENCY, async (record) => {
       try {
-        counted = countSkillInvocations((await query.readSession(record.header.id)).events)
+        return countSkillInvocations((await query.readSession(record.header.id)).events)
       } catch {
-        continue // unreadable sessions are skipped, never fatal
+        return undefined // unreadable sessions are skipped, never fatal
       }
+    })
+    sessions.forEach((record, index) => {
+      const counted = countedList[index]
+      if (counted === undefined) return
       const created = record.header.createdAt
       if (isFrozen(record, cutoff) && counted.size > 0 && typeof created === 'number') {
         cache[record.header.id as unknown as string] = { createdAt: created, counts: Object.fromEntries(counted) }
       }
       if (inWindow(created, windowDays, nowMs)) mergeInto(totals, counted)
-    }
+    })
     checkpoint.frozenSessions = cache
     checkpoint.frozenBefore = cutoff
     checkpoint.windowDays = windowDays
@@ -174,13 +195,17 @@ async function scan(query: SessionQueryLike, checkpoint: SkillStatsCheckpoint, n
   }
 
   const recent: Totals = {}
-  for (const record of sessions) {
-    if (isFrozen(record, checkpoint.frozenBefore)) continue
+  const unfrozen = sessions.filter((record) => !isFrozen(record, checkpoint.frozenBefore))
+  const recentList = await mapConcurrent(unfrozen, SCAN_READ_CONCURRENCY, async (record) => {
     try {
-      mergeInto(recent, countSkillInvocations((await query.readSession(record.header.id)).events))
+      return countSkillInvocations((await query.readSession(record.header.id)).events)
     } catch {
-      continue // unreadable sessions are skipped, never fatal
+      return undefined // unreadable sessions are skipped, never fatal
     }
+  })
+  for (const counted of recentList) {
+    if (counted === undefined) continue
+    mergeInto(recent, counted)
   }
   const totals: Totals = {}
   for (const [id, entry] of Object.entries(checkpoint.frozenSessions)) {
@@ -216,8 +241,9 @@ export interface SkillStatsReaderOptions {
   ttlMs?: number | (() => number)
   /** Rolling window in days; a getter reads the live config each scan. 0 = all history. */
   windowDays?: () => number
-  /** Called after a full reconciliation mutated the checkpoint (never after an
-   *  incremental scan) so the host can persist it to the sidecar. */
+  /** Called after every completed scan (full or incremental) so the host can
+   *  persist the checkpoint including the fresh totals. Cadence follows the
+   *  scan TTL (minutes, not days) — the payload is tiny and writes are atomic. */
   onCheckpoint?: (checkpoint: SkillStatsCheckpoint) => void
 }
 
@@ -238,7 +264,9 @@ export interface SkillStatsReaderOptions {
 export function createSkillStatsReader(query: SessionQueryLike, ttlMs: number | (() => number) = 300_000, options: SkillStatsReaderOptions = {}): SkillStatsReader {
   const checkpoint: SkillStatsCheckpoint = options.checkpoint ?? { windowDays: 0, frozenBefore: 0, frozenSessions: {}, lastFullReconcile: 0 }
   const now = options.now ?? (() => Date.now())
-  let cached: SkillStat[] | undefined
+  // Cold start serves the last persisted totals instantly (may be a window
+  // behind); cachedAt stays 0 so the first call still kicks a background rescan.
+  let cached: SkillStat[] | undefined = checkpoint.lastTotals !== undefined ? [...checkpoint.lastTotals] : undefined
   let cachedAt = 0
   let refreshing: Promise<void> | null = null
   let lastScanDurationMs = 0
@@ -248,16 +276,17 @@ export function createSkillStatsReader(query: SessionQueryLike, ttlMs: number |
     const base = typeof ttlMs === 'function' ? ttlMs() : ttlMs
     const ttl = Math.max(base, lastScanDurationMs * STATS_TTL_SCAN_FACTOR)
     if (cached !== undefined && startedAt - cachedAt < ttl) return cached
-    // Expired (or first call): hand back the stale totals (empty on first
-    // call) and kick off one background rescan.
+    // Expired (or first call): hand back the stale totals (empty on a truly
+    // fresh start) and kick off one background rescan.
     if (refreshing === null) {
       const windowDays = options.windowDays?.() ?? 0
       refreshing = scan(query, checkpoint, startedAt, windowDays)
-        .then(({ stats, mutated }) => {
+        .then(({ stats }) => {
           cached = stats
           cachedAt = now()
           lastScanDurationMs = Math.max(0, cachedAt - startedAt)
-          if (mutated) options.onCheckpoint?.({ ...checkpoint, frozenSessions: { ...checkpoint.frozenSessions } })
+          checkpoint.lastTotals = stats
+          options.onCheckpoint?.({ ...checkpoint, frozenSessions: { ...checkpoint.frozenSessions } })
         })
         .catch(() => { /* keep the previous totals on scan failure */ })
         .finally(() => { refreshing = null })

package/src/store/errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Business-rule failure the routes layer can map onto a 4xx status instead
+ * of a blanket 500: user input is invalid (validation → 400), the target
+ * does not exist (not-found → 404), or the operation conflicts with an
+ * invariant (conflict → 409).
+ */
+export class StoreError extends Error {
+  readonly kind: 'validation' | 'not-found' | 'conflict'
+  constructor(kind: StoreError['kind'], message: string) {
+    super(message)
+    this.name = 'StoreError'
+    this.kind = kind
+  }
+}

package/src/store/migrate.ts

@@ -0,0 +1,272 @@
+import type { DisabledSkill, HubConfig, MarketSourceRecord, MarketStatsSnapshot, SkillStatsCheckpoint, SkillTag, SourceRecord, TrashEntry } from '../protocol.ts'
+import { STORE_VERSION } from './paths.ts'
+
+/** Normalized raw sidecar document after schema migration (fields still unvalidated). */
+export interface MigratedStore {
+  version: number
+  disabled: unknown
+  config?: unknown
+  tags?: unknown
+  sources?: unknown
+  marketSources?: unknown
+  trash?: unknown
+  skillStats?: unknown
+  marketStats?: unknown
+  collectionOrder?: unknown
+  sourceGroupOrder?: unknown
+}
+
+/**
+ * Normalize an arbitrary parsed sidecar document to the current schema.
+ * v1 to v2: scenes are dropped (the one-click role merged into group
+ * switches), and origins are migrated into source records (repo = origin
+ * value, commit snapshot empty — the first update check backfills it).
+ * v2 to v3: market sources become records ({ repo, ref?, commitSha? })
+ * instead of bare repo slugs, so a source can pin a release/branch version.
+ * Returns null when the file claims a newer schema than this plugin
+ * understands, so the caller starts empty instead of risking data loss.
+ */
+export function migrateStore(parsed: unknown): MigratedStore | null {
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) return null
+  const record = parsed as Record<string, unknown>
+  const version = typeof record.version === 'number' ? record.version : 0
+  if (version > STORE_VERSION) return null
+  const disabled = Array.isArray(record.disabled) ? record.disabled : []
+  const config = typeof record.config === 'object' && record.config !== null && !Array.isArray(record.config) ? record.config : undefined
+  const tags = Array.isArray(record.tags) ? record.tags : undefined
+  const trash = Array.isArray(record.trash) ? record.trash : undefined
+  // v2 stored bare slugs; v3 stores records. Normalize both shapes here.
+  const marketSources = Array.isArray(record.marketSources)
+    ? record.marketSources.map((entry) => typeof entry === 'string'
+      ? { repo: entry }
+      : entry)
+    : undefined
+
+  // v2 stores structured source records; v1 only had a skillName to
+  // collection string map (origins). Migrate each origin into a SourceRecord
+  // whose repo is the collection string itself and whose commit snapshot is
+  // empty.
+  let sources: unknown
+  if (Array.isArray(record.sources)) {
+    sources = record.sources
+  } else if (version < 2 && typeof record.origins === 'object' && record.origins !== null && !Array.isArray(record.origins)) {
+    const byOrigin = new Map<string, string[]>()
+    for (const [name, origin] of Object.entries(record.origins as Record<string, unknown>)) {
+      if (typeof origin !== 'string' || origin === '') continue
+      const list = byOrigin.get(origin)
+      if (list === undefined) byOrigin.set(origin, [name])
+      else list.push(name)
+    }
+    sources = [...byOrigin.entries()].map(([repo, skillNames]) => ({
+      repo,
+      root: 'skills',
+      commitSha: '',
+      skills: skillNames.sort((a, b) => a.localeCompare(b)),
+    }))
+  }
+  return {
+    version: STORE_VERSION,
+    disabled,
+    ...(config !== undefined ? { config } : {}),
+    ...(tags !== undefined ? { tags } : {}),
+    ...(sources !== undefined ? { sources } : {}),
+    ...(marketSources !== undefined ? { marketSources } : {}),
+    ...(trash !== undefined ? { trash } : {}),
+    // v4 (skillStats) is a pure addition — older files simply lack the field,
+    // and the loader validates its shape, so pass it through untouched.
+    // marketStats follows the same pattern (validated on load below).
+    ...(record.skillStats !== undefined ? { skillStats: record.skillStats } : {}),
+    ...(record.marketStats !== undefined ? { marketStats: record.marketStats } : {}),
+    ...(Array.isArray(record.collectionOrder) ? { collectionOrder: record.collectionOrder } : {}),
+    ...(Array.isArray(record.sourceGroupOrder) ? { sourceGroupOrder: record.sourceGroupOrder } : {}),
+  }
+}
+
+/** Validated in-memory state hydrated from a migrated document. */
+export interface HydratedState {
+  entries: Map<string, DisabledSkill>
+  config: Partial<HubConfig>
+  tagsById: Map<string, SkillTag>
+  sourcesByRepo: Map<string, SourceRecord>
+  marketSources: MarketSourceRecord[]
+  trashByName: Map<string, TrashEntry>
+  skillStats: SkillStatsCheckpoint | undefined
+  marketStats: MarketStatsSnapshot | undefined
+  collectionOrder: string[]
+  sourceGroupOrder: string[]
+}
+
+/** 小优化：统一的非空字符串数组清洗（去空、去重可选由调用方处理）。 */
+function cleanStringList(value: unknown): string[] {
+  if (!Array.isArray(value)) return []
+  return value.filter((n): n is string => typeof n === 'string' && n !== '')
+}
+
+/**
+ * 把迁移后的原始文档校验为内存状态：坏条目丢弃、坏桶降级为空，
+ * 绝不因一条脏数据丢掉整个 sidecar（与原 ensureLoaded 内联逻辑一致）。
+ */
+export function hydrateMigratedState(migrated: MigratedStore): HydratedState {
+  const entries = new Map<string, DisabledSkill>()
+  if (Array.isArray(migrated.disabled)) {
+    for (const entry of migrated.disabled) {
+      if (typeof entry?.name === 'string' && typeof entry?.path === 'string') {
+        entries.set(entry.name, entry)
+      }
+    }
+  }
+
+  const config: Partial<HubConfig> = {}
+  const saved = migrated.config as { enabled?: unknown; announceToAgent?: unknown; dotModelColor?: unknown; dotUserColor?: unknown; showUseCount?: unknown; showUseTime?: unknown; showGroupSummary?: unknown } | undefined
+  if (typeof saved === 'object' && saved !== null) {
+    if (typeof saved.enabled === 'boolean') config.enabled = saved.enabled
+    if (typeof saved.announceToAgent === 'boolean') config.announceToAgent = saved.announceToAgent
+    if (typeof saved.dotModelColor === 'string' && saved.dotModelColor !== '') config.dotModelColor = saved.dotModelColor
+    if (typeof saved.dotUserColor === 'string' && saved.dotUserColor !== '') config.dotUserColor = saved.dotUserColor
+    if (typeof saved.showUseCount === 'boolean') config.showUseCount = saved.showUseCount
+    if (typeof saved.showUseTime === 'boolean') config.showUseTime = saved.showUseTime
+    if (typeof saved.showGroupSummary === 'boolean') config.showGroupSummary = saved.showGroupSummary
+  }
+
+  const tagsById = new Map<string, SkillTag>()
+  if (Array.isArray(migrated.tags)) {
+    for (const entry of migrated.tags as unknown[]) {
+      const tag = entry as { id?: unknown; name?: unknown; skillNames?: unknown; default?: unknown } | null
+      if (tag !== null && typeof tag === 'object' && typeof tag.id === 'string' && typeof tag.name === 'string' && Array.isArray(tag.skillNames)) {
+        tagsById.set(tag.id, {
+          id: tag.id,
+          name: tag.name,
+          skillNames: tag.skillNames.filter((n): n is string => typeof n === 'string'),
+          ...(tag.default === true ? { default: true } : {}),
+        })
+      }
+    }
+  }
+
+  const sourcesByRepo = new Map<string, SourceRecord>()
+  if (Array.isArray(migrated.sources)) {
+    for (const entry of migrated.sources as unknown[]) {
+      const source = entry as { repo?: unknown; ref?: unknown; root?: unknown; commitSha?: unknown; skills?: unknown; manifest?: unknown } | null
+      if (source !== null && typeof source === 'object' && typeof source.repo === 'string' && source.repo !== '' && Array.isArray(source.skills)) {
+        const manifest = source.manifest as Record<string, unknown> | undefined
+        const rawRoot = typeof source.root === 'string' && source.root !== '' && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(source.root) ? source.root : 'skills'
+        sourcesByRepo.set(source.repo, {
+          repo: source.repo,
+          ...(typeof source.ref === 'string' && source.ref !== '' ? { ref: source.ref } : {}),
+          root: rawRoot,
+          commitSha: typeof source.commitSha === 'string' ? source.commitSha : '',
+          skills: source.skills.filter((n): n is string => typeof n === 'string'),
+          ...(manifest !== null && typeof manifest === 'object' && !Array.isArray(manifest)
+            ? { manifest: Object.fromEntries(Object.entries(manifest).filter(([, size]) => typeof size === 'number')) as Record<string, number> }
+            : {}),
+        })
+      }
+    }
+  }
+
+  const marketSources: MarketSourceRecord[] = []
+  if (Array.isArray(migrated.marketSources)) {
+    for (const entry of migrated.marketSources as unknown[]) {
+      const item = entry as { repo?: unknown; ref?: unknown; commitSha?: unknown } | null
+      if (item !== null && typeof item === 'object' && typeof item.repo === 'string' && item.repo !== '' && !marketSources.some((s) => s.repo === item.repo)) {
+        marketSources.push({
+          repo: item.repo,
+          ...(typeof item.ref === 'string' && item.ref !== '' ? { ref: item.ref } : {}),
+          ...(typeof item.commitSha === 'string' && item.commitSha !== '' ? { commitSha: item.commitSha } : {}),
+        })
+      }
+    }
+  }
+
+  const trashByName = 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, {
+          name: item.name,
+          path: item.path,
+          movedAt: typeof item.movedAt === 'number' ? item.movedAt : 0,
+          ...(typeof item.sourcePath === 'string' && item.sourcePath !== '' ? { sourcePath: item.sourcePath } : {}),
+          ...(origin !== null && typeof origin === 'object' && typeof origin.repo === 'string' && origin.repo !== '' && typeof origin.root === 'string' && origin.root !== '' && /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(origin.root)
+            ? {
+                origin: {
+                  repo: origin.repo,
+                  root: origin.root,
+                  ...(typeof origin.ref === 'string' && origin.ref !== '' ? { ref: origin.ref } : {}),
+                  commitSha: typeof origin.commitSha === 'string' ? origin.commitSha : '',
+                },
+              }
+            : {}),
+          ...(Array.isArray(tagIds) ? { tagIds: tagIds.filter((id): id is string => typeof id === 'string') } : {}),
+        })
+      }
+    }
+  }
+
+  let skillStats: SkillStatsCheckpoint | undefined = undefined
+  const savedStats = migrated.skillStats as Partial<SkillStatsCheckpoint> | null | undefined
+  if (savedStats !== null && typeof savedStats === 'object'
+    && typeof savedStats.frozenBefore === 'number' && typeof savedStats.lastFullReconcile === 'number'
+    && typeof savedStats.windowDays === 'number'
+    && typeof savedStats.frozenSessions === 'object' && savedStats.frozenSessions !== null) {
+    // Validate entry shapes too: a corrupt bucket degrades to a fresh
+    // checkpoint (one extra full reconciliation), never to bad counts.
+    const sessions: SkillStatsCheckpoint['frozenSessions'] = {}
+    for (const [id, entry] of Object.entries(savedStats.frozenSessions)) {
+      if (entry === null || typeof entry !== 'object' || typeof entry.createdAt !== 'number'
+        || typeof entry.counts !== 'object' || entry.counts === null) continue
+      const counts: Record<string, { count: number; lastUsed: number }> = {}
+      for (const [name, stat] of Object.entries(entry.counts)) {
+        if (stat !== null && typeof stat === 'object'
+          && typeof (stat as { count?: unknown }).count === 'number'
+          && typeof (stat as { lastUsed?: unknown }).lastUsed === 'number') {
+          counts[name] = { count: (stat as { count: number }).count, lastUsed: (stat as { lastUsed: number }).lastUsed }
+        }
+      }
+      sessions[id] = { createdAt: entry.createdAt, counts }
+    }
+    const rawTotals = (savedStats as { lastTotals?: unknown }).lastTotals
+    const lastTotals = Array.isArray(rawTotals)
+      ? rawTotals.filter((entry): entry is { name: string; count: number; lastUsed?: number } =>
+          entry !== null && typeof entry === 'object'
+          && typeof (entry as { name?: unknown }).name === 'string'
+          && typeof (entry as { count?: unknown }).count === 'number').map((entry) => ({
+            name: (entry as { name: string }).name,
+            count: (entry as { count: number }).count,
+            ...(typeof (entry as { lastUsed?: unknown }).lastUsed === 'number' ? { lastUsed: (entry as { lastUsed: number }).lastUsed } : {}),
+          }))
+      : undefined
+    skillStats = {
+      windowDays: savedStats.windowDays,
+      frozenBefore: savedStats.frozenBefore,
+      frozenSessions: sessions,
+      lastFullReconcile: savedStats.lastFullReconcile,
+      ...(lastTotals !== undefined ? { lastTotals } : {}),
+    }
+  }
+
+  let marketStats: MarketStatsSnapshot | undefined = undefined
+  const savedMarketStats = migrated.marketStats as Partial<MarketStatsSnapshot> | null | undefined
+  if (savedMarketStats !== null && typeof savedMarketStats === 'object'
+    && typeof savedMarketStats.fetchedAt === 'number'
+    && typeof savedMarketStats.stats === 'object' && savedMarketStats.stats !== null) {
+    // A corrupt bucket degrades to no snapshot (one cold fetch), never to bad numbers.
+    const stats: MarketStatsSnapshot['stats'] = {}
+    for (const [repo, entry] of Object.entries(savedMarketStats.stats)) {
+      if (entry !== null && typeof entry === 'object'
+        && typeof (entry as { stars?: unknown }).stars === 'number'
+        && typeof (entry as { downloads?: unknown }).downloads === 'number') {
+        stats[repo] = { stars: (entry as { stars: number }).stars, downloads: (entry as { downloads: number }).downloads }
+      }
+    }
+    marketStats = { fetchedAt: savedMarketStats.fetchedAt, stats }
+  }
+
+  const collectionOrder = cleanStringList(migrated.collectionOrder)
+  const sourceGroupOrder = cleanStringList(migrated.sourceGroupOrder)
+
+  return { entries, config, tagsById, sourcesByRepo, marketSources, trashByName, skillStats, marketStats, collectionOrder, sourceGroupOrder }
+}

package/src/store/paths.ts

@@ -0,0 +1,43 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import type { DisabledSkill, HubConfig, MarketSourceRecord, MarketStatsSnapshot, SkillStatsCheckpoint, SkillTag, SourceRecord, TrashEntry } from '../protocol.ts'
+
+/** 默认场景名（系统预置的兜底场景，新技能自动归入）。 */
+export const DEFAULT_SCENE_NAME = '通用'
+
+/** Wire shape persisted on disk. */
+export interface StoreFile {
+  version: number
+  disabled: DisabledSkill[]
+  /** Runtime configuration edited from the web settings card (hub-owned, not settings-service). */
+  config?: Partial<HubConfig>
+  /** User-defined tag groups (pure organization; skill files untouched). */
+  tags?: SkillTag[]
+  /** Upstream source tracking records (repo + commit snapshot). */
+  sources?: SourceRecord[]
+  /** User-added market sources (owner/repo slugs + optional pinned ref). */
+  marketSources?: MarketSourceRecord[]
+  /** Trashed skills (removed after upstream deletion, restorable). */
+  trash?: TrashEntry[]
+  /** Usage-statistics incremental-scan checkpoint (frozen watermark + totals). */
+  skillStats?: SkillStatsCheckpoint
+  /** Market-stats snapshot (stars/downloads per repo, hourly TTL). */
+  marketStats?: MarketStatsSnapshot
+  /** Drag-reorder: collection name order for 来源分组 */
+  collectionOrder?: string[]
+  /** Drag-reorder: 来源顶层分组整体顺序（project / col:xxx / uncategorized-source） */
+  sourceGroupOrder?: string[]
+}
+
+/** Resolve the DSH home directory (the filesystem provider's user-dsh root base). */
+export function dshHome(): string {
+  return process.env.DSH_HOME ?? join(homedir(), '.dsh')
+}
+
+/** Resolve the sidecar state path (injectable in tests). */
+export function statePath(home = dshHome()): string {
+  return join(home, 'dsh-skill-hub.json')
+}
+
+/** Current sidecar schema version. Bump on breaking shape changes and add a migration below. */
+export const STORE_VERSION = 4