dsh-skill-hub 0.2.2 → 0.2.5

package/src/client/panel/SkillRow.tsx

@@ -5,7 +5,7 @@
 
 import type { JSX, KeyboardEvent } from 'react'
 import type { CatalogSkill } from '../../protocol.ts'
-import { IconTrashOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconTrashOutline16 } from '../icons.tsx'
 import { tt } from '../helpers.ts'
 import { dotStyle, relativeTimeText } from './format.ts'
 import type { SkillHubState } from './useSkillHub.ts'
@@ -16,6 +16,12 @@ export function SkillRow(props: { skill: CatalogSkill; hub: SkillHubState }): JS
   const stat = hub.uses.get(skill.name)
   const count = stat?.count ?? 0
   const lastUsed = stat?.lastUsed
+  /** 单一状态圆点：模型可调 → 蓝；否则用户可调 → 绿。与聊天 / 菜单同规则。 */
+  const dot = skill.invocation.modelInvocable
+    ? <span className={css.dot + ' ' + css.dotModel} style={dotStyle(hub.hubConfig?.dotModelColor)} title={tt('legend.model')} />
+    : skill.invocation.userInvocable
+      ? <span className={css.dot + ' ' + css.dotUser} style={dotStyle(hub.hubConfig?.dotUserColor)} title={tt('legend.user')} />
+      : null
   /** 键盘打开详情：Enter 或空格。仅当焦点在行本身（而非行内按钮）时生效。 */
   const onKeyDown = (event: KeyboardEvent<HTMLDivElement>): void => {
     if (event.target !== event.currentTarget) return
@@ -37,8 +43,7 @@ export function SkillRow(props: { skill: CatalogSkill; hub: SkillHubState }): JS
         <div className={css.rowName}>
           <span className={css.rowNameText}>{skill.name}</span>
           {count > 0 && hub.hubConfig?.showUseCount !== false ? <span className={css.useCount}>{count}</span> : null}
-          {skill.invocation.modelInvocable ? <span className={css.dot + ' ' + css.dotModel} style={dotStyle(hub.hubConfig?.dotModelColor)} title={tt('legend.model')} /> : null}
-          {skill.invocation.userInvocable ? <span className={css.dot + ' ' + css.dotUser} style={dotStyle(hub.hubConfig?.dotUserColor)} title={tt('legend.user')} /> : null}
+          {dot}
           {lastUsed !== undefined && hub.hubConfig?.showUseTime !== false ? <span className={css.useTime}>{relativeTimeText(lastUsed)}</span> : null}
         </div>
         <div className={css.rowDesc}>{skill.description}</div>

package/src/client/panel/format.ts

@@ -2,12 +2,23 @@
  * Shared display helpers for the panel views (skill rows, detail view, and
  * dialogs): dot color styling, relative/absolute time text, and commit-SHA
  * shortening. Kept in one place so the views render identically.
+ *
+ * The invocation-status dot defaults live here (not in the settings card) so
+ * both the panel legend and the chat `/` skill menu draw from one source and
+ * so this primitives-free module stays unit-testable.
  */
 
 import type { CSSProperties } from 'react'
 import { formatRelativeTime } from '../grouping.ts'
 import { tt } from '../helpers.ts'
 
+/** Model-invocable dot color default. Single source for the TS side; the
+ *  panel's CSS mirrors it via --hub-model (panel.module.css). */
+export const DEFAULT_DOT_MODEL_COLOR = '#2f81f7'
+/** User-invocable dot color default. Single source for the TS side; the
+ *  panel's CSS mirrors it via --hub-user (panel.module.css). */
+export const DEFAULT_DOT_USER_COLOR = '#3fb950'
+
 /** Dot inline style from the user-chosen color (undefined keeps the CSS default). */
 export function dotStyle(color: string | undefined): CSSProperties | undefined {
   if (color === undefined) return undefined

package/src/client/panel/panel.module.css

@@ -120,6 +120,7 @@
 
 /* Reduced header: title + quiet count on one line, controls on the next. */
 .headerCount { font-size: 12px; opacity: .5; margin-left: 2px; white-space: nowrap; }
+.pluginVersion { font-size: 12px; font-weight: 500; opacity: .45; margin-left: 6px; white-space: nowrap; font-variant-numeric: tabular-nums; }
 .subbar { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
 .legendToggle { flex: none; width: 22px; height: 22px; border-radius: 50%; border: none; background: rgba(128,128,128,.14); color: inherit; font-size: 12px; line-height: 1; cursor: pointer; opacity: .55; transition: opacity .15s ease, background .15s ease; }
 .legendToggle:hover { opacity: 1; }

package/src/client/settings-card.tsx

@@ -7,7 +7,7 @@
  */
 
 import { useState, type ReactElement } from 'react'
-import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
+import { IconChevronDownOutline14 } from './icons.tsx'
 import type { HubKey } from './locales.ts'
 import type { CardShell } from './settings-form.ts'
 import css from './settings-card.module.css'
@@ -236,3 +236,51 @@ export function ColorField(props: ColorFieldProps): ReactElement {
     </div>
   )
 }
+
+/** One staged numeric field: a numeric draft text input with inherit/reset semantics. */
+export interface NumberFieldProps {
+  id: string
+  label: string
+  hint: string
+  /** Placeholder shown while the field inherits its default. */
+  inheritLabel: string
+  overriddenLabel: string
+  resetLabel: string
+  disabled: boolean
+  /** Effective number when overridden; empty string means inherit. */
+  text: string
+  overridden: boolean
+  invalid?: boolean
+  onEdit: (text: string) => void
+  onReset: () => void
+}
+
+export function NumberField(props: NumberFieldProps): ReactElement {
+  return (
+    <div className={css.field}>
+      <div className={css.head}>
+        <label className={css.label} htmlFor={props.id}>{props.label}</label>
+        {props.overridden ? (
+          <span className={css.badges}>
+            <span className={css.badge}>{props.overriddenLabel}</span>
+            <button type='button' className={css.reset} disabled={props.disabled} onClick={props.onReset}>
+              {props.resetLabel}
+            </button>
+          </span>
+        ) : null}
+      </div>
+      <input
+        id={props.id}
+        type='text'
+        inputMode='numeric'
+        className={css.input}
+        value={props.text}
+        disabled={props.disabled}
+        placeholder={props.inheritLabel}
+        aria-invalid={props.invalid === true}
+        onChange={(event) => { props.onEdit(event.target.value) }}
+      />
+      <p className={css.hint}>{props.hint}</p>
+    </div>
+  )
+}

package/src/client/settings-form.ts

@@ -49,6 +49,27 @@ export function colorField(field: string): FieldSpec {
   }
 }
 
+/**
+ * A numeric field with range clamping. Integer by default: a fractional draft
+ * is truncated so "5.5 分钟" cannot sneak past an integer-only schema.
+ */
+export function numberField(field: string, options: { min?: number; max?: number; integer?: boolean } = {}): FieldSpec {
+  const min = options.min ?? Number.NEGATIVE_INFINITY
+  const max = options.max ?? Number.POSITIVE_INFINITY
+  const integer = options.integer ?? true
+  return {
+    field,
+    format: (value) => (typeof value === 'number' && Number.isFinite(value) ? String(value) : ''),
+    parse: (text) => {
+      const trimmed = text.trim()
+      if (!/^-?\d+(\.\d+)?$/.test(trimmed)) return undefined
+      const parsed = integer ? Math.trunc(Number(trimmed)) : Number(trimmed)
+      if (!Number.isFinite(parsed) || parsed < min || parsed > max) return undefined
+      return { kind: 'set', value: parsed }
+    },
+  }
+}
+
 /** Card-level state the chrome renders. */
 export interface CardShell {
   available: boolean

package/src/client/slash-dots.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Slash-menu skill dots: source lookup + candidates wrapping. The wrapper's
+ * contract is pure and injectable — fake api (catalog) and fake settings scope
+ * (getSnapshot), no DOM — so it tests cleanly in the node vitest environment.
+ * The module caches the catalog map; resetModelCache keeps tests independent.
+ */
+
+import { beforeEach, describe, expect, it } from 'vitest'
+import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/client'
+import type { InputTriggerCandidate, InputTriggerServiceContract, InputTriggerSource } from '@deepseek-ai/dsh-client-ui-input-trigger/client'
+import type { HubSettingsValue } from '../protocol.ts'
+import type { SkillHubApi } from './api.ts'
+import { findSkillSource, resetModelCache, wrapSkillSource } from './slash-dots.tsx'
+
+beforeEach(() => {
+  resetModelCache()
+})
+
+/** A `/` skill source stub with the core ui-skill shape. */
+function skillSource(candidates = async (): Promise<InputTriggerCandidate[]> => []): InputTriggerSource {
+  return {
+    trigger: '/',
+    name: 'skill',
+    order: 2,
+    candidates,
+    onPick: () => undefined,
+  }
+}
+
+/** Fake registry exposing `live.sources` the way the running service does. */
+function registry(...sources: InputTriggerSource[]): InputTriggerServiceContract {
+  return { live: { sources }, registerSource: () => () => {}, sessionOf: () => { throw new Error('not used in tests') } } as unknown as InputTriggerServiceContract
+}
+
+/** Fake settings scope snapshotting a fixed HubSettingsValue. */
+function scopeWith(value: HubSettingsValue): SettingsScope<HubSettingsValue> {
+  return {
+    getSnapshot: () => ({ status: 'ready', value, base: undefined, user: undefined, revision: 1, writable: true, mode: 'host' }),
+    subscribe: () => () => {},
+    set: async () => {},
+    unset: async () => {},
+  } as SettingsScope<HubSettingsValue>
+}
+
+/** Fake hub api whose catalog lists the given skills. */
+function apiWith(skills: Array<{ name: string; modelInvocable: boolean }>): SkillHubApi {
+  return {
+    catalog: async () => ({
+      ok: true,
+      complete: true,
+      skills: skills.map((s) => ({
+        name: s.name,
+        description: '',
+        invocation: { modelInvocable: s.modelInvocable, userInvocable: true },
+        provider: 'filesystem',
+        source: 'user-dsh',
+        writable: true,
+      })),
+      disabled: [],
+      diagnostics: [],
+    }),
+  } as unknown as SkillHubApi
+}
+
+describe('findSkillSource', () => {
+  it('finds the core /skill source among other sources', () => {
+    const source = skillSource()
+    const service = registry(
+      { trigger: '/', name: 'command', candidates: async () => [], onPick: () => undefined },
+      source,
+    )
+    expect(findSkillSource(service)).toBe(source)
+  })
+
+  it('returns undefined when the skill source is absent', () => {
+    const service = registry({ trigger: '/', name: 'command', candidates: async () => [], onPick: () => undefined })
+    expect(findSkillSource(service)).toBeUndefined()
+  })
+
+  it('never throws on a reshaped registry', () => {
+    expect(findSkillSource({} as InputTriggerServiceContract)).toBeUndefined()
+    expect(findSkillSource({ live: {} } as unknown as InputTriggerServiceContract)).toBeUndefined()
+  })
+})
+
+describe('wrapSkillSource', () => {
+  it('adds a model-colored dot to model-callable skills and a user-colored dot to user-only ones', async () => {
+    const source = skillSource(async () => [
+      { name: 'code-review', description: 'review code' },
+      { name: 'personal-note', description: 'only me' },
+      { name: 'known-default', description: 'fallback unknown' },
+    ])
+    const api = apiWith([
+      { name: 'code-review', modelInvocable: true },
+      { name: 'personal-note', modelInvocable: false },
+    ])
+    const scope = scopeWith({ enabled: true, announceToAgent: true, showUseCount: true, showUseTime: true, showGroupSummary: true, dotModelColor: '#112233', dotUserColor: '#445566' })
+
+    const restore = wrapSkillSource(source, api, scope)
+    try {
+      const rows = await source.candidates({ sessionId: 's1' as never }, { query: '', position: 'leading', signal: new AbortController().signal })
+
+      expect(rows).toHaveLength(3)
+      // Model-callable → model color.
+      expect((rows[0].icon as unknown as { props: { style: { background: string } } }).props.style.background).toBe('#112233')
+      // User-only → user color.
+      expect((rows[1].icon as unknown as { props: { style: { background: string } } }).props.style.background).toBe('#445566')
+      // Unknown name → model default (still a dot, safer than no dot).
+      expect(rows[2].icon).toBeDefined()
+      // Original fields pass through untouched.
+      expect(rows[0].name).toBe('code-review')
+      expect(rows[0].description).toBe('review code')
+    } finally {
+      restore()
+    }
+  })
+
+  it('falls back to the default colors when settings omit them and catalog fails', async () => {
+    const source = skillSource(async () => [{ name: 'lonely', description: '' }])
+    const api = { catalog: async () => { throw new Error('route down') } } as unknown as SkillHubApi
+    const scope = scopeWith({ enabled: true, announceToAgent: true, showUseCount: true, showUseTime: true, showGroupSummary: true })
+
+    const restore = wrapSkillSource(source, api, scope)
+    try {
+      const rows = await source.candidates({ sessionId: 's1' as never }, { query: '', position: 'leading', signal: new AbortController().signal })
+      // Catalog failed → unknown name → model default dot still renders.
+      expect(rows[0].icon).toBeDefined()
+      expect((rows[0].icon as unknown as { props: { style: { background: string } } }).props.style.background).toBe('#2f81f7')
+    } finally {
+      restore()
+    }
+  })
+
+  it('restores the original candidates on dispose', async () => {
+    const originalCandidates = async (): Promise<InputTriggerCandidate[]> => [{ name: 'plain', description: '' }]
+    const source = skillSource(originalCandidates)
+    const api = apiWith([])
+    const scope = scopeWith({ enabled: true, announceToAgent: true, showUseCount: true, showUseTime: true, showGroupSummary: true })
+
+    const restore = wrapSkillSource(source, api, scope)
+    expect(source.candidates).not.toBe(originalCandidates)
+    restore()
+    expect(source.candidates).toBe(originalCandidates)
+  })
+})

package/src/client/slash-dots.tsx

@@ -0,0 +1,190 @@
+/**
+ * Slash-menu skill dots: puts the invocation-status dot (model-callable blue /
+ * user-only green) in front of every skill candidate in the chat `/` menu.
+ *
+ * Mechanism (mirrors how dsh-at-file fills the menu icon slot): the candidate
+ * menu's rows already render an optional `icon` slot (`MenuView` renders
+ * `item.icon` in a 16×16 leading span when it's defined), but the core `/skill`
+ * source (`dsh-client-ui-skill`) returns candidates without `icon`. This module
+ * wraps that source's `candidates` and stamps each row with a colored dot,
+ * reusing the same settings (dotModelColor / dotUserColor) and the same
+ * `modelInvocable` classification the panel legend uses — so the chat menu and
+ * the Settings → 技能 panel stay in sync, and editing the color updates both.
+ *
+ * The skill source is registered by the core plugin under the `name` "skill"
+ * on the `/` trigger; re-registering the same name would throw, so this wraps
+ * the already-registered source object instead (found through the runtime
+ * source registry, which the frozen contract exposes only as `registerSource`
+ * / `sessionOf` — the lookup below is defensive: it never throws).
+ */
+
+import type { ClientContext, SettingsScope } from '@deepseek-ai/dsh-client-runtime/client'
+// Type-only: pulls the Context merge for ctx.inputTriggers.
+import type {} from '@deepseek-ai/dsh-client-ui-input-trigger/client'
+import type { InputTriggerCandidate, InputTriggerServiceContract, InputTriggerSource } from '@deepseek-ai/dsh-client-ui-input-trigger/client'
+import { createElement } from 'react'
+import type { HubSettingsValue } from '../protocol.ts'
+import type { SkillHubApi } from './api.ts'
+import { DEFAULT_DOT_MODEL_COLOR, DEFAULT_DOT_USER_COLOR } from './panel/format.ts'
+
+/** The core plugin's skill source identity on the '/' trigger. */
+const SKILL_SOURCE = { trigger: '/', name: 'skill' } as const
+
+/** How long one catalog-derived modelInvocable map stays hot before refresh. */
+const MODEL_TTL_MS = 60_000
+
+/** Runtime view of the source registry (the contract keeps `live` private). */
+type SourceRegistry = {
+  live?: { sources?: InputTriggerSource[] }
+}
+
+/**
+ * Find the core `/skill` source through the runtime registry, or undefined.
+ * The lookup never throws: a missing/reshaped registry just means no dots. Exported
+ * for unit tests; the apply path only calls it indirectly through setupSkillSlashDots.
+ * @param service - the ctx.inputTriggers service face.
+ * @returns the registered skill source, or undefined.
+ */
+export function findSkillSource(service: InputTriggerServiceContract): InputTriggerSource | undefined {
+  const live = (service as unknown as SourceRegistry).live
+  if (live?.sources === undefined) return undefined
+  return live.sources.find((source) => source.trigger === SKILL_SOURCE.trigger && source.name === SKILL_SOURCE.name)
+}
+
+/** One catalog-derived name → modelInvocable snapshot with a load timestamp. */
+let modelCache: { at: number; map: Map<string, boolean> } | { at: number; failed: true } | undefined
+
+/**
+ * Clear the modelInvocable cache. Called on connection/reset so a fresh
+ * catalog wins after reconnect; exported for deterministic unit tests.
+ */
+export function resetModelCache(): void {
+  modelCache = undefined
+}
+
+/**
+ * Resolve name → modelInvocable from the hub's catalog, cached for
+ * MODEL_TTL_MS. A failed load caches the failure briefly so a downed route
+ * doesn't hammer the host on every keystroke; the returned map is empty then
+ * (callers fall back to the model dot for unknown names).
+ * @param api - the hub browser API.
+ * @returns name → whether the model may call the skill.
+ */
+async function modelInvocableMap(api: SkillHubApi): Promise<Map<string, boolean>> {
+  const now = Date.now()
+  const cached = modelCache
+  if (cached !== undefined && now - cached.at < MODEL_TTL_MS) {
+    return 'failed' in cached ? new Map() : cached.map
+  }
+  try {
+    const catalog = await api.catalog()
+    const map = new Map<string, boolean>(catalog.skills.map((skill) => [skill.name, skill.invocation.modelInvocable]))
+    modelCache = { at: now, map }
+    return map
+  } catch (error) {
+    console.error('[dsh-skill-hub] slash dot color lookup failed:', error)
+    modelCache = { at: now, failed: true }
+    return new Map()
+  }
+}
+
+/**
+ * One menu-row dot element. Inline span so it needs no CSS module; the
+ * candidate menu centers it inside its 16×16 leading icon slot.
+ * @param color - the dot's background color.
+ * @returns a React node (memory-only, never crosses the Host boundary).
+ */
+function dotIcon(color: string): InputTriggerCandidate['icon'] {
+  return createElement('span', {
+    'aria-hidden': true,
+    style: {
+      display: 'inline-block',
+      width: 6,
+      height: 6,
+      borderRadius: 3,
+      background: color,
+      flex: 'none',
+    },
+  }) as unknown as InputTriggerCandidate['icon']
+}
+
+/**
+ * Wrap the core skill source so every menu row carries the invocation dot.
+ * Exported for unit tests; production wiring goes through setupSkillSlashDots.
+ * @param source - the registered `/skill` source.
+ * @param api - hub browser API for the modelInvocable lookup.
+ * @param scope - hub settings scope for the dot colors.
+ * @returns a disposer restoring the original candidates.
+ */
+export function wrapSkillSource(source: InputTriggerSource, api: SkillHubApi, scope: SettingsScope<HubSettingsValue>): () => void {
+  const original = source.candidates
+  source.candidates = async (session, req) => {
+    const items = await original(session, req)
+    if (req.signal.aborted) return items
+    const modelByName = await modelInvocableMap(api)
+    if (req.signal.aborted) return items
+    const snapshot = scope.getSnapshot()
+    const modelColor = snapshot.value?.dotModelColor ?? DEFAULT_DOT_MODEL_COLOR
+    const userColor = snapshot.value?.dotUserColor ?? DEFAULT_DOT_USER_COLOR
+    return items.map((item) => ({
+      ...item,
+      icon: dotIcon((modelByName.get(item.name) ?? true) ? modelColor : userColor),
+    }))
+  }
+  return () => {
+    source.candidates = original
+  }
+}
+
+/**
+ * Mount the slash-menu dots on the registered `/skill` source. Idempotent and
+ * defensive: if the core source isn't registered yet (or the registry shape
+ * changes), it retries briefly and then gives up silently — the chat keeps
+ * working, it simply shows no dots. The returned disposer restores the
+ * original candidates and clears the model cache.
+ * @param ctx - the client root context (inputTriggers + events).
+ * @param api - hub browser API.
+ * @param scope - hub settings scope for dot colors.
+ * @returns a cleanup function for `ctx.effect`.
+ */
+export function setupSkillSlashDots(
+  ctx: ClientContext,
+  api: SkillHubApi,
+  scope: SettingsScope<HubSettingsValue>,
+): () => void {
+  const inputTriggers = ctx.get('inputTriggers')
+  if (inputTriggers === undefined) return () => {}
+
+  let disposed = false
+  let restore: (() => void) | undefined
+  let attempts = 0
+
+  // The core ui-skill source registers early in the bundle, but not strictly
+  // before this apply runs — poll briefly so order never matters.
+  const attempt = (): void => {
+    if (disposed) return
+    const source = findSkillSource(inputTriggers)
+    if (source === undefined) {
+      if (attempts < 10) {
+        attempts += 1
+        setTimeout(attempt, 100)
+      }
+      return
+    }
+    restore = wrapSkillSource(source, api, scope)
+  }
+  attempt()
+
+  const clearCache = (): void => {
+    resetModelCache()
+  }
+  // ctx.on returns the listener disposer; cordis has no ctx.off.
+  const offReset = ctx.on('connection/reset', clearCache)
+
+  return () => {
+    disposed = true
+    offReset()
+    restore?.()
+    restore = undefined
+  }
+}

package/src/index.ts

@@ -40,6 +40,10 @@ export interface Config {
   showUseTime?: boolean
   /** Show group-header usage summaries (count + last used). Default true. */
   showGroupSummary?: boolean
+  /** 统计滚动窗口天数：只统计最近 N 天的使用；0 = 全部历史。默认 0。 */
+  statsWindowDays?: number
+  /** 自动统计扫描间隔（分钟，最小 1）。默认 5。 */
+  statsScanMinutes?: number
 }
 
 export const Config: z<Config> = z.object({
@@ -48,6 +52,8 @@ export const Config: z<Config> = z.object({
   showUseCount: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseCount),
   showUseTime: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseTime),
   showGroupSummary: z.boolean().default(HUB_CONFIG_DEFAULTS.showGroupSummary),
+  statsWindowDays: z.number().min(0).max(3650).default(HUB_CONFIG_DEFAULTS.statsWindowDays),
+  statsScanMinutes: z.number().min(1).max(1440).default(HUB_CONFIG_DEFAULTS.statsScanMinutes),
 })
 
 /**
@@ -68,6 +74,8 @@ export const HubSettingsSchema: z<HubSettingsValue> = z.object({
   showGroupSummary: z.boolean().default(HUB_CONFIG_DEFAULTS.showGroupSummary),
   dotModelColor: z.string().pattern(HEX_COLOR_RE),
   dotUserColor: z.string().pattern(HEX_COLOR_RE),
+  statsWindowDays: z.number().min(0).max(3650).default(HUB_CONFIG_DEFAULTS.statsWindowDays),
+  statsScanMinutes: z.number().min(1).max(1440).default(HUB_CONFIG_DEFAULTS.statsScanMinutes),
 })
 
 /** Order of the announcement section within the tool-guidance band. */
@@ -126,7 +134,7 @@ export function apply(ctx: Context, config?: Config): void {
   // surfaces once the namespace commits.
   const updateConfig = async (patch: Partial<HubConfig>): Promise<HubConfig> => {
     const user: Record<string, unknown> = { ...saved() }
-    for (const [key, value] of Object.entries(patch) as Array<[keyof HubConfig, boolean | string | undefined]>) {
+    for (const [key, value] of Object.entries(patch) as Array<[keyof HubConfig, boolean | string | number | undefined]>) {
       if (value === undefined) delete user[key]
       else user[key] = value
     }
@@ -222,7 +230,30 @@ export function apply(ctx: Context, config?: Config): void {
   // stats wiring — no sessionQuery service ever mounted means none of this
   // runs).
   ctx.inject(['sessionQuery'], (sctx) => {
-    stats = createSkillStatsReader(sctx.sessionQuery)
-    sync()
+    // 恢复 sidecar 里的增量扫描检查点后再建 reader（异步、不阻塞注入回调）：
+    // 重启后无需重新解压全部历史日志；检查点只在全量对账后落盘（约每天一次，
+    // 或统计窗口配置变化后的下一次扫描）。扫描间隔与滚动窗口都从设置命名空间
+    // 实时读取——卡片里改完即生效，无需重启。
+    void (async () => {
+      const saved = await store.getSkillStatsState().catch(() => undefined)
+      const scanMinutes = (): number => {
+        const value = current().statsScanMinutes
+        return typeof value === 'number' && value >= 1 ? Math.floor(value) : HUB_CONFIG_DEFAULTS.statsScanMinutes
+      }
+      const windowDays = (): number => {
+        const value = current().statsWindowDays
+        return typeof value === 'number' && value >= 0 ? Math.floor(value) : HUB_CONFIG_DEFAULTS.statsWindowDays
+      }
+      stats = createSkillStatsReader(sctx.sessionQuery, () => scanMinutes() * 60_000, {
+        checkpoint: saved,
+        windowDays,
+        onCheckpoint: (next) => {
+          void store.saveSkillStatsState(next).catch((error) => {
+            ctx.logger.warn('[dsh-skill-hub] persisting skill-stats checkpoint failed', error)
+          })
+        },
+      })
+      sync()
+    })()
   })
 }

package/src/protocol.ts

@@ -88,6 +88,8 @@ export interface DiagnosticEntry {
 /** GET /api/skill-hub/catalog */
 export interface CatalogResponse {
   ok: true
+  /** 已安装插件自身的版本号（package.json version），面板标题旁显示。 */
+  pluginVersion: string
   /** Whether discovery completed within a stable catalog revision. */
   complete: boolean
   /** Sorted winning summaries of every enabled skill (all roots + providers). */
@@ -196,6 +198,25 @@ export interface StatsResponse {
   stats: SkillStat[]
 }
 
+/**
+ * Persisted incremental-scan checkpoint for the usage statistics (sidecar
+ * `skillStats` field). Sessions created before `frozenBefore` are treated as
+ * finalized: their per-session counts live in `frozenSessions` (only sessions
+ * with at least one invocation are kept) and they are not re-read on
+ * incremental scans. A daily full reconciliation rebuilds the cache and
+ * advances the watermark, so a resumed old session is eventually re-counted.
+ */
+export interface SkillStatsCheckpoint {
+  /** The rolling-window configuration this checkpoint was built for (0 = all history). */
+  windowDays: number
+  /** Watermark: every session with header.createdAt < this value is frozen. */
+  frozenBefore: number
+  /** Per-session counts of finalized sessions, keyed by session id. */
+  frozenSessions: Record<string, { createdAt: number; counts: Record<string, { count: number; lastUsed: number }> }>
+  /** Epoch ms of the last full reconciliation (drives the daily cadence). */
+  lastFullReconcile: number
+}
+
 /** JSON error body shared by every route. */
 export interface ErrorResponse {
   error: string
@@ -217,6 +238,10 @@ export interface HubConfig {
   showUseTime?: boolean
   /** Show group-header usage summaries (count + last used). Default true. */
   showGroupSummary?: boolean
+  /** 统计滚动窗口天数：只统计最近 N 天的使用；0 = 全部历史。默认 0。 */
+  statsWindowDays?: number
+  /** 自动统计扫描间隔（分钟，最小 1）。默认 5。 */
+  statsScanMinutes?: number
 }
 
 /**
@@ -235,6 +260,10 @@ export type HubSettingsValue = {
   dotModelColor?: string
   /** User-invocable dot color (#rrggbb); absent means the panel default. */
   dotUserColor?: string
+  /** 统计滚动窗口天数（0 = 全部历史）。 */
+  statsWindowDays?: number
+  /** 自动统计扫描间隔（分钟）。 */
+  statsScanMinutes?: number
 }
 
 /**
@@ -248,28 +277,41 @@ export const HUB_CONFIG_DEFAULTS = {
   showUseCount: true,
   showUseTime: true,
   showGroupSummary: true,
+  statsWindowDays: 14,
+  statsScanMinutes: 5,
 } as const
 
 /**
  * Resolve the effective hub config: saved sidecar overrides win over the
  * cordis composition entry (the web card owns runtime config), missing
  * booleans fall back to HUB_CONFIG_DEFAULTS, and dot colors pass through
- * (saved first, then base) only when set.
+ * (saved first, then base) only when set. Numeric stats knobs are clamped to
+ * their sane ranges (window ≥ 0, scan interval ≥ 1 minute).
  */
 export function resolveHubConfig(saved: Partial<HubConfig>, base: Partial<HubConfig> = {}): HubConfig {
   const dotModelColor = saved.dotModelColor !== undefined ? saved.dotModelColor : base.dotModelColor
   const dotUserColor = saved.dotUserColor !== undefined ? saved.dotUserColor : base.dotUserColor
+  const windowDays = clampNumber(saved.statsWindowDays ?? base.statsWindowDays, 0) ?? HUB_CONFIG_DEFAULTS.statsWindowDays
+  const scanMinutes = clampNumber(saved.statsScanMinutes ?? base.statsScanMinutes, 1) ?? HUB_CONFIG_DEFAULTS.statsScanMinutes
   return {
     enabled: saved.enabled ?? base.enabled ?? HUB_CONFIG_DEFAULTS.enabled,
     announceToAgent: saved.announceToAgent ?? base.announceToAgent ?? HUB_CONFIG_DEFAULTS.announceToAgent,
     showUseCount: saved.showUseCount ?? base.showUseCount ?? HUB_CONFIG_DEFAULTS.showUseCount,
     showUseTime: saved.showUseTime ?? base.showUseTime ?? HUB_CONFIG_DEFAULTS.showUseTime,
     showGroupSummary: saved.showGroupSummary ?? base.showGroupSummary ?? HUB_CONFIG_DEFAULTS.showGroupSummary,
+    statsWindowDays: windowDays,
+    statsScanMinutes: scanMinutes,
     ...(dotModelColor !== undefined ? { dotModelColor } : {}),
     ...(dotUserColor !== undefined ? { dotUserColor } : {}),
   }
 }
 
+/** Clamp a numeric override into a valid value; undefined/invalid stays undefined. */
+function clampNumber(value: unknown, min: number): number | undefined {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < min) return undefined
+  return Math.floor(value)
+}
+
 /** HEX color validation shared by host routes and the settings card. */
 export const HEX_COLOR_RE = /^#[0-9a-f]{6}$/i
 
@@ -298,6 +340,10 @@ export interface ConfigRequest {
   dotModelColor?: string | null
   /** Set the dot color; null clears the saved override so it re-inherits the default. */
   dotUserColor?: string | null
+  /** 统计滚动窗口天数（0 = 全部历史）；null 清除覆盖回默认。 */
+  statsWindowDays?: number | null
+  /** 自动统计扫描间隔（分钟）；null 清除覆盖回默认。 */
+  statsScanMinutes?: number | null
 }
 
 /** One market source: a tracked upstream repo plus its pinned version. */