dsh-skill-hub 0.2.4 → 0.2.6

package/lib/types/stats.d.ts

@@ -12,14 +12,40 @@
  *
  * 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';
-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 declare const STATS_FREEZE_AFTER_MS: number;
+/** Cadence of the full reconciliation that rebuilds the checkpoint (24 h). */
+export declare const STATS_FULL_RECONCILE_MS: number;
+/** Adaptive TTL factor: effective TTL ≥ this multiple of the last scan duration. */
+export declare const STATS_TTL_SCAN_FACTOR = 3;
 /** Narrow structural view of the session-query service (kept loose for tests). */
 export interface SessionQueryLike {
     listSessions(signal?: AbortSignal): Promise<Array<{
         header: {
             id: SessionId;
+            createdAt?: number;
         };
     }>>;
     readSession(id: SessionId): Promise<{
@@ -34,10 +60,27 @@ export interface InvocationStat {
 }
 /** Collect per-skill invocation counts and last-used times from one session. */
 export declare function countSkillInvocations(events: readonly SessionEvent[]): Map<string, InvocationStat>;
-/** Scan every session and total per-skill counts, keeping the latest lastUsed. */
-export declare function readSkillStats(query: SessionQueryLike): Promise<SkillStat[]>;
+/**
+ * Full-corpus totals in one shot (no checkpoint reuse). Kept as the
+ * reference implementation for tests and one-off callers.
+ */
+export declare function readSkillStats(query: SessionQueryLike, windowDays?: number): Promise<SkillStat[]>;
 /** 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
@@ -45,5 +88,11 @@ 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 declare function createSkillStatsReader(query: SessionQueryLike, ttlMs?: number): SkillStatsReader;
+export declare function createSkillStatsReader(query: SessionQueryLike, ttlMs?: number | (() => number), options?: SkillStatsReaderOptions): SkillStatsReader;

package/lib/types/store.d.ts

@@ -11,7 +11,7 @@
  * State file: $DSH_HOME/dsh-skill-hub.json — a small JSON document written
  * atomically (tmp file + rename).
  */
-import type { DisabledSkill, HubConfig, MarketSourceRecord, RepoRoot, SkillTag, SourceRecord, TrashEntry } from './protocol.ts';
+import type { DisabledSkill, HubConfig, MarketSourceRecord, RepoRoot, SkillStatsCheckpoint, SkillTag, SourceRecord, TrashEntry } from './protocol.ts';
 /** 默认场景名（系统预置的兜底场景，新技能自动归入）。 */
 export declare const DEFAULT_SCENE_NAME = "\u901A\u7528";
 /** Resolve the DSH home directory (the filesystem provider's user-dsh root base). */
@@ -19,7 +19,7 @@ export declare function dshHome(): string;
 /** Resolve the sidecar state path (injectable in tests). */
 export declare function statePath(home?: string): string;
 /** Current sidecar schema version. Bump on breaking shape changes and add a migration below. */
-export declare const STORE_VERSION = 3;
+export declare const STORE_VERSION = 4;
 /**
  * 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
@@ -39,6 +39,7 @@ export declare class SkillHubStore {
     private sourcesByRepo;
     private marketSources;
     private trashByName;
+    private skillStats;
     private loaded;
     /** Serializes persist runs: concurrent mutators must not let an earlier
      *  snapshot overwrite a later one (rename is atomic, ordering is not). */
@@ -138,5 +139,9 @@ export declare class SkillHubStore {
     addTrash(entry: TrashEntry): Promise<void>;
     /** Remove a trash record (after restore). */
     removeTrash(name: string): Promise<void>;
+    /** The persisted usage-statistics checkpoint (undefined until first saved). */
+    getSkillStatsState(): Promise<SkillStatsCheckpoint | undefined>;
+    /** Persist a usage-statistics checkpoint (written at most ~once a day, on full reconciliations). */
+    saveSkillStatsState(state: SkillStatsCheckpoint): Promise<void>;
     private persist;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-skill-hub",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "In-GUI skill hub for DeepSeek Harness (dsh): browse the full local skill catalog from the official ctx.skills registry (every root + third-party providers), toggle skills on/off, inspect bodies, surface frontmatter diagnostics, and scaffold new skills — plus a codex-style skill market (built-in catalog, upstream update checks, one-click update-all) with tracked source sync. The full manager beyond the read-only dsh-skill-manager browser.",
   "type": "module",
   "engines": {

package/src/client/SkillHubSettingsCard.tsx

@@ -6,11 +6,12 @@
  * namespace, so the plugin shows up in Settings → 插件 on dsh rc.7+.
  */
 
-import type { ReactElement } from 'react'
+import { useEffect, useState, type ReactElement } from 'react'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
-import { ColorField, PluginSettingsCard, SwitchField } from './settings-card.tsx'
-import { booleanField, CardForm, colorField, type CardShell, type FieldState, type FormScope } from './settings-form.ts'
+import { SkillHubApi } from './api.ts'
+import { ColorField, NumberField, PluginSettingsCard, SwitchField } from './settings-card.tsx'
+import { booleanField, CardForm, colorField, numberField, type CardShell, type FieldState, type FormScope } from './settings-form.ts'
 // Single source for the TS-side dot defaults (the panel CSS mirrors these).
 import { DEFAULT_DOT_MODEL_COLOR, DEFAULT_DOT_USER_COLOR } from './panel/format.ts'
 // Re-export for any consumer that imported them from the card before the move.
@@ -25,6 +26,8 @@ export interface SkillHubSettingsState extends CardShell {
   showUseCount: FieldState
   showUseTime: FieldState
   showGroupSummary: FieldState
+  statsWindowDays: FieldState
+  statsScanMinutes: FieldState
 }
 
 /** The business face the card's slot registration injects. */
@@ -50,7 +53,7 @@ export class SkillHubSettingsCardController {
 
   /** @param scope - the hub settings scope the card edits (FormScope-compatible). */
   constructor(scope: FormScope) {
-    this.form = new CardForm(scope, [booleanField('enabled'), booleanField('announceToAgent'), colorField('dotModelColor'), colorField('dotUserColor'), booleanField('showUseCount'), booleanField('showUseTime'), booleanField('showGroupSummary')])
+    this.form = new CardForm(scope, [booleanField('enabled'), booleanField('announceToAgent'), colorField('dotModelColor'), colorField('dotUserColor'), booleanField('showUseCount'), booleanField('showUseTime'), booleanField('showGroupSummary'), numberField('statsWindowDays', { min: 0, max: 3650 }), numberField('statsScanMinutes', { min: 1, max: 1440 })])
     this.store = this.form.bind(() => this.projection())
   }
 
@@ -64,6 +67,8 @@ export class SkillHubSettingsCardController {
       showUseCount: this.form.field('showUseCount'),
       showUseTime: this.form.field('showUseTime'),
       showGroupSummary: this.form.field('showGroupSummary'),
+      statsWindowDays: this.form.field('statsWindowDays'),
+      statsScanMinutes: this.form.field('statsScanMinutes'),
     }
   }
 
@@ -87,6 +92,15 @@ export class SkillHubSettingsCardController {
 export function SkillHubSettingsCard(props: SkillHubSettingsCardProps): ReactElement {
   const { t } = props
   const state = props.useSkillHubSettingsCard((snapshot) => snapshot)
+  // 插件自身版本：挂载时从 config 路由取一次（与面板标题徽标同源），失败静默不显示。
+  const [version, setVersion] = useState<string | undefined>(undefined)
+  useEffect(() => {
+    let cancelled = false
+    void new SkillHubApi().config()
+      .then((res) => { if (!cancelled && res.ok) setVersion(res.pluginVersion) })
+      .catch(() => { /* 版本徽标是装饰性的，失败不提示 */ })
+    return () => { cancelled = true }
+  }, [])
   const disabled = !state.writable
   const fieldProps = {
     overriddenLabel: t('settings.overridden'),
@@ -98,6 +112,7 @@ export function SkillHubSettingsCard(props: SkillHubSettingsCardProps): ReactEle
       t={t}
       titleKey='settings.title'
       descriptionKey='settings.description'
+      version={version}
       state={state}
       onSave={props.save}
       onDiscard={props.discard}
@@ -164,6 +179,30 @@ export function SkillHubSettingsCard(props: SkillHubSettingsCardProps): ReactEle
         onEdit={(text) => { props.edit('showGroupSummary', text) }}
         onReset={() => { props.resetField('showGroupSummary') }}
       />
+      <NumberField
+        id='skill-hub-stats-window-days'
+        label={t('settings.statsWindowDays')}
+        hint={t('settings.statsWindowDaysHint')}
+        inheritLabel={t('settings.inherit')}
+        {...fieldProps}
+        text={state.statsWindowDays.text}
+        overridden={state.statsWindowDays.overridden}
+        invalid={state.statsWindowDays.invalid}
+        onEdit={(text) => { props.edit('statsWindowDays', text) }}
+        onReset={() => { props.resetField('statsWindowDays') }}
+      />
+      <NumberField
+        id='skill-hub-stats-scan-minutes'
+        label={t('settings.statsScanMinutes')}
+        hint={t('settings.statsScanMinutesHint')}
+        inheritLabel={t('settings.inherit')}
+        {...fieldProps}
+        text={state.statsScanMinutes.text}
+        overridden={state.statsScanMinutes.overridden}
+        invalid={state.statsScanMinutes.invalid}
+        onEdit={(text) => { props.edit('statsScanMinutes', text) }}
+        onReset={() => { props.resetField('statsScanMinutes') }}
+      />
     </PluginSettingsCard>
   )
 }

package/src/client/locales.ts

@@ -181,7 +181,7 @@ export const zh = {
   'form.success': '已创建：',
   'form.error': '创建失败：',
   'err.dismiss': '知道了',
-  'settings.title': 'Skill Hub',
+  'settings.title': '技能中枢',
   'settings.description': '管理 dsh 本地技能目录：浏览、分组、来源同步与新建。',
   'settings.enabled': '启用插件',
   'settings.enabledHint': '关闭后技能中枢的路由、入口与公告全部下线。',
@@ -197,6 +197,10 @@ export const zh = {
   'settings.showUseTimeHint': '在技能名行右侧显示相对时间（如「3 天前」）。',
   'settings.showGroupSummary': '显示分组汇总',
   'settings.showGroupSummaryHint': '在分组标题后汇总调用次数与最近调用时间。',
+  'settings.statsWindowDays': '统计窗口（天）',
+  'settings.statsWindowDaysHint': '只统计最近 N 天的使用次数，默认 14 天；0 = 全部历史。改动立即生效。',
+  'settings.statsScanMinutes': '自动统计间隔（分钟）',
+  'settings.statsScanMinutesHint': '后台扫描会话日志的间隔，最小 1 分钟；扫描耗时会自动拉长间隔。',
   'settings.inherit': '继承',
   'settings.on': '开',
   'settings.off': '关',
@@ -406,6 +410,10 @@ export const en: Record<HubKey, string> = {
   'settings.showUseTimeHint': 'Show relative last-used time on the name row (e.g. "3 d ago").',
   'settings.showGroupSummary': 'Show group summaries',
   'settings.showGroupSummaryHint': 'Summarize invocation count and last-used time after group titles.',
+  'settings.statsWindowDays': 'Stats window (days)',
+  'settings.statsWindowDaysHint': 'Count only usage within the last N days (default 14); 0 = full history. Changes apply immediately.',
+  'settings.statsScanMinutes': 'Auto stats interval (minutes)',
+  'settings.statsScanMinutesHint': 'How often the background session-log scan runs (min 1); heavy scans automatically stretch it.',
   'settings.inherit': 'Inherit',
   'settings.on': 'On',
   'settings.off': 'Off',

package/src/client/panel/SkillHubPanel.tsx

@@ -119,7 +119,7 @@ export function SkillHubPanel(props: SkillHubPanelProps): React.JSX.Element {
   return (
     <div className={css.panel}>
       <div className={css.header}>
-        <h2 className={css.title}><IconSkillOutline16 size={16} className={css.titleIcon} /> {tt('panel.title')}</h2>
+        <h2 className={css.title}><IconSkillOutline16 size={16} className={css.titleIcon} /> {tt('panel.title')}{catalog !== null ? <span className={css.pluginVersion}>v{catalog.pluginVersion}</span> : null}</h2>
         {catalog !== null
           ? <span className={css.headerCount}>
               {tt('panel.count', { count: catalog.skills.length + catalog.disabled.length })}

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.module.css

@@ -8,6 +8,7 @@
 .headText { flex-direction: column; flex: 1; gap: 4px; min-width: 0; display: flex; }
 .name { color: var(--dsw-alias-label-primary); font-size: 15px; font-weight: 600; line-height: 1.4; }
 .description { color: var(--dsw-alias-label-tertiary); font-size: 13px; line-height: 1.5; }
+.versionTag { font-size: 12px; font-weight: 500; opacity: .45; margin-left: 6px; white-space: nowrap; font-variant-numeric: tabular-nums; vertical-align: 1px; }
 .pending { white-space: nowrap; background: var(--dsw-alias-bg-module-platform); color: var(--dsw-alias-label-secondary); border-radius: 999px; flex: none; padding: 1px 8px; font-size: 11px; font-weight: 500; line-height: 17px; }
 .chevron, .chevronOpen { color: var(--dsw-alias-label-tertiary); flex: none; transition: transform .16s; }
 .chevronOpen { transform: rotate(180deg); }

package/src/client/settings-card.tsx

@@ -20,6 +20,8 @@ export interface PluginSettingsCardProps {
   titleKey: HubKey
   /** Locale key of the card description. */
   descriptionKey: HubKey
+  /** 插件自身版本（可选）：显示在标题旁的小徽标；缺省不渲染。 */
+  version?: string
   /** The form shell state. */
   state: CardShell
   onSave: () => void
@@ -48,7 +50,7 @@ export function PluginSettingsCard(props: PluginSettingsCardProps): ReactElement
       onClick={() => { setOpen(!open) }}
     >
       <span className={css.headText}>
-        <span className={css.name}>{title}</span>
+        <span className={css.name}>{title}{props.version !== undefined ? <span className={css.versionTag}>v{props.version}</span> : null}</span>
         <span className={css.description}>{props.t(props.descriptionKey)}</span>
       </span>
       {state.dirty ? <span className={css.pending}>{props.t('settings.unsaved')}</span> : null}
@@ -236,3 +238,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/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,34 +277,49 @@ 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
 
 /** GET /api/skill-hub/config */
 export interface ConfigResponse {
   ok: true
+  /** 已安装插件自身的版本号（package.json version），设置卡标题旁显示。 */
+  pluginVersion: string
   /** Effective configuration (saved overrides merged over the defaults). */
   config: HubConfig
   /** Raw user overrides persisted in the sidecar (absent fields inherit defaults). */
@@ -298,6 +342,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. */

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,8 @@ 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.pluginVersion).toMatch(/^\d+\.\d+\.\d+$/)
+    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. */
@@ -719,7 +719,7 @@ export function makeRoutes(deps: SkillHubRouteDeps): WebRoute[] {
       skipGate: true,
       handler: async ({ req, res, body }) => {
         if (req.method === 'GET') {
-          writeJson(res, 200, { ok: true, config: configOf(deps), saved: savedOf(deps) } satisfies ConfigResponse)
+          writeJson(res, 200, { ok: true, pluginVersion: CURRENT_VERSION, config: configOf(deps), saved: savedOf(deps) } satisfies ConfigResponse)
           return
         }
         const raw = body
@@ -759,7 +759,7 @@ export function makeRoutes(deps: SkillHubRouteDeps): WebRoute[] {
         } else {
           config = await deps.updateConfig(patch)
         }
-        writeJson(res, 200, { ok: true, config, saved: savedOf(deps) } satisfies ConfigResponse)
+        writeJson(res, 200, { ok: true, pluginVersion: CURRENT_VERSION, config, saved: savedOf(deps) } satisfies ConfigResponse)
       },
     }),
     // --------------------------------------------------------------- market