dsh-skill-hub 0.2.2 → 0.2.5

package/src/routes.test.ts

@@ -127,6 +127,8 @@ describe('skill-hub routes', () => {
     expect(body.skills[1].writable).toBe(false)
     expect(body.diagnostics).toHaveLength(1)
     expect(body.diagnostics[0].reason).toBe('missing YAML frontmatter (--- block)')
+    // 面板标题旁的插件版本徽标数据源：随 catalog 附带当前安装版本。
+    expect(body.pluginVersion).toMatch(/^\d+\.\d+\.\d+$/)
   })
 
   it('forwards the cwd query to the registry snapshot', async () => {
@@ -394,7 +396,7 @@ describe('skill-hub routes', () => {
     expect(res.status).toBe(200)
     const body = res.json() as ConfigResponse
     expect(body.ok).toBe(true)
-    expect(body.config).toEqual({ enabled: false, announceToAgent: true, showUseCount: true, showUseTime: true, showGroupSummary: true })
+    expect(body.config).toEqual({ enabled: false, announceToAgent: true, showUseCount: true, showUseTime: true, showGroupSummary: true, statsWindowDays: 14, statsScanMinutes: 5 })
     expect(body.saved).toEqual({ enabled: false })
   })
 

package/src/routes.ts

@@ -85,7 +85,7 @@ import {
   resolveHubConfig,
 } from './protocol.ts'
 import { clearTrash, createSkill, disableSkill, enableSkill, restoreSkill, rootOfPath, rootPath, scanDiagnostics, trashSkill } from './skillfs.ts'
-import { checkLatestRelease } from './update.ts'
+import { checkLatestRelease, CURRENT_VERSION } from './update.ts'
 import { dshHome, StoreError, type SkillHubStore } from './store.ts'
 import type { SkillStatsReader } from './stats.ts'
 
@@ -410,7 +410,7 @@ async function buildCatalog(deps: SkillHubRouteDeps, cwd?: string): Promise<Cata
     ...(await scanDiagnostics('user-dsh', home)),
     ...(await scanDiagnostics('user-agents', home)),
   ]
-  return { ok: true, complete, skills, disabled, diagnostics }
+  return { ok: true, pluginVersion: CURRENT_VERSION, complete, skills, disabled, diagnostics }
 }
 
 /** Map a loaded definition onto the wire shape. */

package/src/stats.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
-import { countSkillInvocations, createSkillStatsReader, readSkillStats, type SessionQueryLike } from './stats.ts'
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { countSkillInvocations, createSkillStatsReader, readSkillStats, STATS_FREEZE_AFTER_MS, type SessionQueryLike } from './stats.ts'
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 
 /** Minimal user/message event carrying a skill-invocation source. */
 function invocationEvent(name: string, seq = 1, time = 0): SessionEvent {
@@ -166,3 +166,274 @@ describe('createSkillStatsReader', () => {
     expect(reads).toBe(2)
   })
 })
+
+// ------------------------------------------------ 增量扫描与自适应 TTL
+
+const NOW = 1_000_000_000_000
+const DAY = 24 * 60 * 60 * 1000
+
+/** One fake corpus record (createdAt omitted → never freezes). */
+function record(id: string, createdAt?: number): { header: { id: SessionId; createdAt?: number } } {
+  return { header: { id: id as never, ...(createdAt !== undefined ? { createdAt } : {}) } }
+}
+
+/** Fake session-query that records which sessions were actually read. */
+function fakeQuery(
+  records: ReturnType<typeof record>[],
+  eventsById: Record<string, SessionEvent[] | 'corrupt'>,
+  reads: string[],
+): SessionQueryLike {
+  return {
+    listSessions: async () => records,
+    readSession: async (id) => {
+      reads.push(String(id))
+      const events = eventsById[String(id)]
+      if (events === 'corrupt') throw new Error('corrupt')
+      return { events: events ?? [] }
+    },
+  }
+}
+
+/** Let the background scan's promise chain settle. */
+async function flush(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 20))
+}
+
+describe('frozen-bucket incremental scans', () => {
+  it('skips frozen sessions and merges checkpoint totals with the recent window', async () => {
+    const reads: string[] = []
+    const query = fakeQuery(
+      [record('frozen-skill', NOW - 30 * DAY), record('fresh', NOW - 1 * DAY)],
+      {
+        'frozen-skill': [invocationEvent('oldskill', 1, NOW - 20 * DAY)],
+        fresh: [invocationEvent('tdd', 1), invocationEvent('tdd', 2)],
+      },
+      reads,
+    )
+    let checkpoints = 0
+    const reader = createSkillStatsReader(query, 60_000, {
+      now: () => NOW,
+      checkpoint: {
+        windowDays: 0,
+        frozenBefore: NOW - 10 * DAY,
+        frozenSessions: { 'frozen-skill': { createdAt: NOW - 30 * DAY, counts: { oldskill: { count: 5, lastUsed: NOW - 20 * DAY } } } },
+        lastFullReconcile: NOW - 3_600_000, // 1h ago → incremental path
+      },
+      onCheckpoint: () => { checkpoints += 1 },
+    })
+    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)
+  })
+
+  it('runs a full reconciliation when due: rebuilds the frozen bucket and advances the watermark', async () => {
+    const reads: string[] = []
+    const query = fakeQuery(
+      [record('ancient', NOW - 30 * DAY), record('recent', NOW - 1 * DAY)],
+      {
+        ancient: [invocationEvent('a', 1, 5)],
+        recent: [invocationEvent('b', 1), invocationEvent('b', 2)],
+      },
+      reads,
+    )
+    const saved: Array<Record<string, unknown>> = []
+    const reader = createSkillStatsReader(query, 60_000, {
+      now: () => NOW,
+      // lastFullReconcile = 0 → 对账到期（全量路径）
+      checkpoint: { windowDays: 0, frozenBefore: 0, frozenSessions: {}, lastFullReconcile: 0 },
+      onCheckpoint: (cp) => { saved.push(cp as unknown as Record<string, unknown>) },
+    })
+    expect(await reader()).toEqual([])
+    await flush()
+    expect(await reader()).toEqual([
+      { name: 'a', count: 1, lastUsed: 5 },
+      { name: 'b', count: 2, lastUsed: 0 },
+    ])
+    expect(reads).toEqual(['ancient', 'recent']) // 全量：两个都读
+    expect(saved).toHaveLength(1)
+    expect(saved[0]).toEqual({
+      windowDays: 0,
+      frozenBefore: NOW - STATS_FREEZE_AFTER_MS,
+      // 全历史模式（windowDays=0）：冻结会话进缓存且仍计入总数。
+      frozenSessions: { ancient: { createdAt: NOW - 30 * DAY, counts: { a: { count: 1, lastUsed: 5 } } } },
+      lastFullReconcile: NOW,
+    })
+  })
+
+  it('re-reads sessions without createdAt on incremental scans (never freezes)', async () => {
+    const reads: string[] = []
+    const query = fakeQuery(
+      [record('no-stamp'), record('fresh', NOW - 1 * DAY)],
+      { 'no-stamp': [invocationEvent('x', 1)], fresh: [invocationEvent('y', 1)] },
+      reads,
+    )
+    const reader = createSkillStatsReader(query, 60_000, {
+      now: () => NOW,
+      checkpoint: {
+        windowDays: 0,
+        frozenBefore: NOW - 10 * DAY,
+        frozenSessions: {},
+        lastFullReconcile: NOW - 3_600_000,
+      },
+    })
+    expect(await reader()).toEqual([])
+    await flush()
+    expect(await reader().then((s) => s.map((stat) => stat.name))).toEqual(['x', 'y'])
+    expect(reads).toEqual(['no-stamp', 'fresh'])
+  })
+
+  it('skips unreadable recent sessions on incremental scans without failing', async () => {
+    const reads: string[] = []
+    const query = fakeQuery(
+      [record('bad', NOW - 2 * DAY), record('good', NOW - 1 * DAY)],
+      { bad: 'corrupt', good: [invocationEvent('tdd', 1)] },
+      reads,
+    )
+    const reader = createSkillStatsReader(query, 60_000, {
+      now: () => NOW,
+      checkpoint: {
+        windowDays: 0,
+        frozenBefore: NOW - 10 * DAY,
+        frozenSessions: { cached: { createdAt: NOW - 30 * DAY, counts: { oldskill: { count: 3, lastUsed: 0 } } } },
+        lastFullReconcile: NOW - 3_600_000,
+      },
+    })
+    expect(await reader()).toEqual([])
+    await flush()
+    expect(await reader()).toEqual([
+      { name: 'oldskill', count: 3, lastUsed: 0 },
+      { name: 'tdd', count: 1, lastUsed: 0 },
+    ])
+  })
+})
+
+describe('adaptive rescan TTL', () => {
+  it('extends the effective TTL to three times the measured scan duration', async () => {
+    let clock = 0
+    let scans = 0
+    const query: SessionQueryLike = {
+      listSessions: async () => [{ header: { id: 'a' as never } }, { header: { id: 'b' as never } }],
+      readSession: async () => {
+        clock += 60_000 // 每个会话耗时 60s → 扫描总耗时 120s
+        scans += 1
+        return { events: [invocationEvent('tdd')] }
+      },
+    }
+    const reader = createSkillStatsReader(query, 300_000, { now: () => clock })
+    expect(await reader()).toEqual([])
+    await flush() // 扫描完成：cachedAt=120_000，lastScanDuration=120s
+    expect(scans).toBe(2)
+
+    // 自适应 TTL = max(300s, 3×120s) = 360s。固定 TTL 在 310s 时就该重扫了，
+    // 这里必须仍然命中缓存 —— 证明自适应生效。
+    clock += 310_000
+    await reader()
+    expect(scans).toBe(2)
+
+    clock += 60_000 // 距上次缓存 370s ≥ 360s → 触发后台重扫
+    await reader()
+    await flush()
+    expect(scans).toBe(4)
+  })
+})
+
+describe('rolling stats window (configurable days)', () => {
+  it('counts only sessions inside the window when windowDays > 0', async () => {
+    const reads: string[] = []
+    const query = fakeQuery(
+      [record('old', NOW - 10 * DAY), record('fresh', NOW - 1 * DAY)],
+      {
+        old: [invocationEvent('oldskill', 1)],
+        fresh: [invocationEvent('tdd', 1)],
+      },
+      reads,
+    )
+    const reader = createSkillStatsReader(query, 60_000, {
+      now: () => NOW,
+      windowDays: () => 7, // 只统计最近 7 天
+    })
+    expect(await reader()).toEqual([])
+    await flush()
+    // 10 天前的会话超出窗口：不计入，也不进缓存。
+    expect(await reader()).toEqual([{ name: 'tdd', count: 1, lastUsed: 0 }])
+  })
+
+  it('keeps full history when the window is 0 (default)', async () => {
+    const query = fakeQuery(
+      [record('old', NOW - 400 * DAY), record('fresh', NOW - 1 * DAY)],
+      {
+        old: [invocationEvent('oldskill', 1)],
+        fresh: [invocationEvent('tdd', 1)],
+      },
+      [],
+    )
+    const reader = createSkillStatsReader(query, 60_000, { now: () => NOW })
+    expect(await reader()).toEqual([])
+    await flush()
+    expect(await reader().then((s) => s.map((stat) => stat.name))).toEqual(['oldskill', 'tdd'])
+  })
+
+  it('forces a full reconciliation when the configured window changes', async () => {
+    let window = 0
+    const reads: string[] = []
+    const query = fakeQuery(
+      [record('ancient', NOW - 30 * DAY), record('mid', NOW - 20 * DAY), record('fresh', NOW - 1 * DAY)],
+      {
+        ancient: [invocationEvent('a', 1)],
+        mid: [invocationEvent('b', 1)],
+        fresh: [invocationEvent('c', 1)],
+      },
+      reads,
+    )
+    let clock = NOW
+    const reader = createSkillStatsReader(query, 3_600_000, {
+      now: () => clock,
+      windowDays: () => window,
+      checkpoint: { windowDays: 0, frozenBefore: NOW - STATS_FREEZE_AFTER_MS, frozenSessions: {}, lastFullReconcile: NOW - 1000 },
+    })
+    // 全历史首轮：增量水位（NOW-14d）之后的只有 fresh；mid/ancient 被冻结跳过。
+    expect(await reader()).toEqual([])
+    await flush()
+    expect(await reader()).toEqual([{ name: 'c', count: 1, lastUsed: 0 }])
+    const afterFirst = reads.length
+
+    // 窗口切到 7 天：检查点记录的 windowDays 不一致 → 强制全量对账，
+    // 老会话也会被重读一次，随后合计只含窗内的 c。（推进时钟使 TTL 过期）
+    window = 7
+    clock += 2 * 3_600_000
+    expect(await reader()).toEqual([{ name: 'c', count: 1, lastUsed: 0 }]) // 先回 stale 缓存并触发重扫
+    await flush()
+    await reader()
+    expect(reads.length).toBeGreaterThan(afterFirst)
+    const names = (await reader()).map((stat) => stat.name)
+    expect(names).not.toContain('a')
+    expect(names).not.toContain('b')
+    expect(names).toContain('c')
+  })
+
+  it('filters and prunes over-window cache entries on incremental reads', async () => {
+    // 防御行为：检查点里残留了超出当前窗口的缓存条目时（例如窗口曾收窄），
+    // 增量读取直接把它过滤掉并顺手清除，而不是计入总数。
+    const query = fakeQuery([], {}, [])
+    const checkpoint = {
+      windowDays: 7,
+      frozenBefore: NOW - 7 * DAY,
+      frozenSessions: {
+        'stale-entry': { createdAt: NOW - 10 * DAY, counts: { oldskill: { count: 9, lastUsed: NOW - 10 * DAY } } },
+      },
+      lastFullReconcile: NOW - 1000, // 对账未到期 → 增量路径
+    }
+    const reader = createSkillStatsReader(query, 3_600_000, { now: () => NOW, checkpoint, windowDays: () => 7 })
+    expect(await reader()).toEqual([])
+    await flush()
+    const stats = await reader()
+    expect(stats).toEqual([])
+    expect(checkpoint.frozenSessions['stale-entry']).toBeUndefined() // 已被懒清理
+  })
+})

package/src/stats.ts

@@ -12,16 +12,44 @@
  *
  * Counting is per-skill-name, not per-source: a name may resolve to different
  * files across projects, but the model-facing identity is the kebab-case name.
+ *
+ * Scaling (per-session checkpoint + incremental scans): a full scan
+ * decompresses every session log, which grows linearly with total history.
+ * Sessions older than the effective watermark are therefore treated as
+ * finalized — their per-session counts live in the checkpoint (persisted by
+ * the host via the sidecar) and are skipped on incremental scans; only the
+ * recent window is re-read. A daily full reconciliation rebuilds the cache
+ * and advances the watermark, so a resumed old session is eventually
+ * re-counted. On top of that, the reader's TTL adapts to the measured scan
+ * duration (STATS_TTL_SCAN_FACTOR), so a heavy scan also lowers its own
+ * frequency.
+ *
+ * Rolling window (statsWindowDays > 0): totals only include sessions created
+ * within the last N days. The watermark then equals the window edge, so
+ * sessions outside the window are neither re-read nor counted, and the
+ * reconciliation prunes their cache entries. Changing the configured window
+ * forces one full reconciliation immediately (the checkpoint records the
+ * window it was built for), so the new semantics take effect on the next scan
+ * instead of up to a day later.
  */
 
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
 // Type-only: pulls the 'skill-invocation' MessageSourceMap augmentation.
 import type {} from '@deepseek-ai/dsh-skill'
-import type { SkillStat } from './protocol.ts'
+import type { SkillStat, SkillStatsCheckpoint } from './protocol.ts'
+
+/** Fallback freeze horizon when no rolling window is configured (14 days). */
+export const STATS_FREEZE_AFTER_MS = 14 * 24 * 60 * 60 * 1000
+/** Cadence of the full reconciliation that rebuilds the checkpoint (24 h). */
+export const STATS_FULL_RECONCILE_MS = 24 * 60 * 60 * 1000
+/** Adaptive TTL factor: effective TTL ≥ this multiple of the last scan duration. */
+export const STATS_TTL_SCAN_FACTOR = 3
+
+const DAY_MS = 24 * 60 * 60 * 1000
 
 /** Narrow structural view of the session-query service (kept loose for tests). */
 export interface SessionQueryLike {
-  listSessions(signal?: AbortSignal): Promise<Array<{ header: { id: SessionId } }>>
+  listSessions(signal?: AbortSignal): Promise<Array<{ header: { id: SessionId; createdAt?: number } }>>
   readSession(id: SessionId): Promise<{ events: SessionEvent[] }>
 }
 
@@ -65,34 +93,134 @@ export function countSkillInvocations(events: readonly SessionEvent[]): Map<stri
   return stats
 }
 
-/** Scan every session and total per-skill counts, keeping the latest lastUsed. */
-export async function readSkillStats(query: SessionQueryLike): Promise<SkillStat[]> {
-  const totals = new Map<string, InvocationStat>()
+/** Aggregated totals bucket keyed by skill name. */
+type Totals = Record<string, InvocationStat>
+
+function isFrozen(record: { header: { createdAt?: number } }, watermark: number): boolean {
+  const created = record.header.createdAt
+  // Missing or non-positive timestamps never freeze: the session stays on the
+  // re-read path, which is merely slower — never wrong.
+  return typeof created === 'number' && created > 0 && created < watermark
+}
+
+function mergeInto(totals: Totals, counted: Map<string, InvocationStat>): void {
+  for (const [name, stat] of counted) {
+    const total = totals[name]
+    if (total === undefined) totals[name] = { ...stat }
+    else {
+      total.count += stat.count
+      if (stat.lastUsed > total.lastUsed) total.lastUsed = stat.lastUsed
+    }
+  }
+}
+
+function toSorted(totals: Totals): SkillStat[] {
+  return Object.entries(totals)
+    .map(([name, stat]) => ({ name, count: stat.count, lastUsed: stat.lastUsed }))
+    .sort((x, y) => x.name.localeCompare(y.name))
+}
+
+/** Effective freeze watermark for the configured rolling window (0 = all history → freeze horizon). */
+function watermarkFor(windowDays: number, nowMs: number): number {
+  return windowDays > 0 ? nowMs - windowDays * DAY_MS : nowMs - STATS_FREEZE_AFTER_MS
+}
+
+/**
+ * Whether a session's usage counts toward the configured window. With no
+ * window (0) everything counts — full history; with a window, only sessions
+ * created inside it do. Distinct from the freeze watermark, which is purely a
+ * re-read optimization.
+ */
+function inWindow(createdAt: number | undefined, windowDays: number, nowMs: number): boolean {
+  if (windowDays <= 0) return true
+  return typeof createdAt === 'number' && createdAt > 0 && createdAt >= nowMs - windowDays * DAY_MS
+}
+
+/**
+ * One pass over the corpus. Runs either a full reconciliation (rebuilds the
+ * per-session cache and advances the watermark — mutates the checkpoint) or a
+ * cheap incremental scan (re-reads everything at or after the watermark and
+ * merges over the cached sessions — leaves the checkpoint untouched). Totals
+ * always apply the CURRENT window filter over the cached sessions, so a
+ * window shrink takes effect immediately even before the next reconciliation.
+ */
+async function scan(query: SessionQueryLike, checkpoint: SkillStatsCheckpoint, nowMs: number, windowDays: number): Promise<{ stats: SkillStat[]; mutated: boolean }> {
   const sessions = await query.listSessions()
+  const cutoff = watermarkFor(windowDays, nowMs)
+  const dueFullScan = nowMs - checkpoint.lastFullReconcile >= STATS_FULL_RECONCILE_MS
+    || checkpoint.windowDays !== windowDays
+
+  if (dueFullScan) {
+    const cache: SkillStatsCheckpoint['frozenSessions'] = {}
+    const totals: Totals = {}
+    for (const record of sessions) {
+      let counted: Map<string, InvocationStat>
+      try {
+        counted = countSkillInvocations((await query.readSession(record.header.id)).events)
+      } catch {
+        continue // unreadable sessions are skipped, never fatal
+      }
+      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
+    checkpoint.lastFullReconcile = nowMs
+    return { stats: toSorted(totals), mutated: true }
+  }
+
+  const recent: Totals = {}
   for (const record of sessions) {
-    let snapshot: { events: SessionEvent[] }
+    if (isFrozen(record, checkpoint.frozenBefore)) continue
     try {
-      snapshot = await query.readSession(record.header.id)
+      mergeInto(recent, countSkillInvocations((await query.readSession(record.header.id)).events))
     } catch {
       continue // unreadable sessions are skipped, never fatal
     }
-    for (const [name, stat] of countSkillInvocations(snapshot.events)) {
-      const total = totals.get(name)
-      if (total === undefined) totals.set(name, { ...stat })
-      else {
-        total.count += stat.count
-        if (stat.lastUsed > total.lastUsed) total.lastUsed = stat.lastUsed
-      }
+  }
+  const totals: Totals = {}
+  for (const [id, entry] of Object.entries(checkpoint.frozenSessions)) {
+    if (!inWindow(entry.createdAt, windowDays, nowMs)) {
+      delete checkpoint.frozenSessions[id] // lazily prune entries outside the window
+      continue
     }
+    mergeInto(totals, new Map(Object.entries(entry.counts)))
   }
-  return [...totals.entries()]
-    .map(([name, stat]) => ({ name, count: stat.count, lastUsed: stat.lastUsed }))
-    .sort((a, b) => a.name.localeCompare(b.name))
+  mergeInto(totals, new Map(Object.entries(recent)))
+  return { stats: toSorted(totals), mutated: false }
+}
+
+/**
+ * Full-corpus totals in one shot (no checkpoint reuse). Kept as the
+ * reference implementation for tests and one-off callers.
+ */
+export async function readSkillStats(query: SessionQueryLike, windowDays = 0): Promise<SkillStat[]> {
+  const checkpoint: SkillStatsCheckpoint = { windowDays, frozenBefore: 0, frozenSessions: {}, lastFullReconcile: 0 }
+  return (await scan(query, checkpoint, Date.now(), windowDays)).stats
 }
 
 /** A memoized stats reader (the panel polls, but logs change slowly). */
 export type SkillStatsReader = () => Promise<SkillStat[]>
 
+/** Optional wiring for {@link createSkillStatsReader}. */
+export interface SkillStatsReaderOptions {
+  /** Checkpoint restored from the sidecar; absent means "start from zero". */
+  checkpoint?: SkillStatsCheckpoint
+  /** Injectable clock (epoch ms); defaults to Date.now. Tests drive time with it. */
+  now?: () => number
+  /** Base rescan interval in ms; a getter reads the live config each check. */
+  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. */
+  onCheckpoint?: (checkpoint: SkillStatsCheckpoint) => void
+}
+
 /**
  * Wrap a query in a stale-while-revalidate cache: responses never wait for a
  * full session-log scan. While the TTL is fresh the cached totals are
@@ -100,21 +228,36 @@ export type SkillStatsReader = () => Promise<SkillStat[]>
  * single background rescan refreshes them — the panel's next poll picks the
  * fresh numbers. A full scan decompresses every session log and can take
  * seconds, so it must never sit on the request path.
+ *
+ * Two scaling mechanisms keep this sane as history grows:
+ *  - the rescan is incremental (per-session checkpoint, see module doc);
+ *  - the effective TTL adapts to the measured scan duration, so a heavier
+ *    corpus automatically lowers the rescan cadence instead of burning CPU
+ *    on every poll interval.
  */
-export function createSkillStatsReader(query: SessionQueryLike, ttlMs = 300_000): SkillStatsReader {
+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
   let cachedAt = 0
   let refreshing: Promise<void> | null = null
+  let lastScanDurationMs = 0
+
   return async () => {
-    const now = Date.now()
-    if (cached !== undefined && now - cachedAt < ttlMs) return cached
+    const startedAt = now()
+    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.
     if (refreshing === null) {
-      refreshing = readSkillStats(query)
-        .then((stats) => {
+      const windowDays = options.windowDays?.() ?? 0
+      refreshing = scan(query, checkpoint, startedAt, windowDays)
+        .then(({ stats, mutated }) => {
           cached = stats
-          cachedAt = Date.now()
+          cachedAt = now()
+          lastScanDurationMs = Math.max(0, cachedAt - startedAt)
+          if (mutated) options.onCheckpoint?.({ ...checkpoint, frozenSessions: { ...checkpoint.frozenSessions } })
         })
         .catch(() => { /* keep the previous totals on scan failure */ })
         .finally(() => { refreshing = null })

package/src/store.test.ts

@@ -250,4 +250,36 @@ describe('SkillHubStore', () => {
     expect(await fresh.listDisabled()).toEqual([])
   })
 
+  it('migrates a v3 file (no skillStats) and persists a checkpoint round-trip at v4', async () => {
+    // v3 旧文件：无 skillStats 字段 → 装载后检查点为空，写盘时版本升到当前。
+    await writeFile(file, JSON.stringify({
+      version: 3,
+      disabled: [],
+      tags: [{ id: 't1', name: '通用', skillNames: [], default: true }],
+    }), 'utf8')
+    expect(await store.getSkillStatsState()).toBeUndefined()
+    const checkpoint = {
+      windowDays: 0,
+      frozenBefore: 1000,
+      frozenSessions: { 'session-a': { createdAt: 900, counts: { tdd: { count: 7, lastUsed: 900 }, 'code-review': { count: 2, lastUsed: 800 } } } },
+      lastFullReconcile: 1234,
+    }
+    await store.saveSkillStatsState(checkpoint)
+    // 新实例读回一致（含深拷贝的 frozenTotals）。
+    const reloaded = new SkillHubStore(file)
+    expect(await reloaded.getSkillStatsState()).toEqual(checkpoint)
+    const raw = JSON.parse(await readFile(file, 'utf8')) as { version: number; skillStats?: unknown }
+    expect(raw.version).toBe(4)
+    expect(raw.skillStats).toEqual(checkpoint)
+  })
+
+  it('drops a corrupt skillStats bucket instead of trusting bad counts', async () => {
+    await writeFile(file, JSON.stringify({
+      version: 4,
+      disabled: [],
+      skillStats: { windowDays: 'x', frozenBefore: true, lastFullReconcile: false, frozenSessions: { bad: { createdAt: 'y', counts: [] } } },
+    }), 'utf8')
+    expect(await store.getSkillStatsState()).toBeUndefined()
+  })
+
 })