dsh-skill-hub 0.2.4 → 0.2.5

package/lib/index.js

@@ -53,27 +53,39 @@ const HUB_CONFIG_DEFAULTS = {
 	announceToAgent: true,
 	showUseCount: true,
 	showUseTime: true,
-	showGroupSummary: true
+	showGroupSummary: true,
+	statsWindowDays: 14,
+	statsScanMinutes: 5
 };
 /**
 * 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).
 */
 function resolveHubConfig(saved, base = {}) {
 	const dotModelColor = saved.dotModelColor !== void 0 ? saved.dotModelColor : base.dotModelColor;
 	const dotUserColor = saved.dotUserColor !== void 0 ? 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 !== void 0 ? { dotModelColor } : {},
 		...dotUserColor !== void 0 ? { dotUserColor } : {}
 	};
 }
+/** Clamp a numeric override into a valid value; undefined/invalid stays undefined. */
+function clampNumber(value, min) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < min) return void 0;
+	return Math.floor(value);
+}
 /** HEX color validation shared by host routes and the settings card. */
 const HEX_COLOR_RE = /^#[0-9a-f]{6}$/i;
 //#endregion
@@ -129,7 +141,7 @@ function migrateStore(parsed) {
 	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
 	const record = parsed;
 	const version = typeof record.version === "number" ? record.version : 0;
-	if (version > 3) return null;
+	if (version > 4) 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 : void 0;
 	const tags = Array.isArray(record.tags) ? record.tags : void 0;
@@ -153,13 +165,14 @@ function migrateStore(parsed) {
 		}));
 	}
 	return {
-		version: 3,
+		version: 4,
 		disabled,
 		...config !== void 0 ? { config } : {},
 		...tags !== void 0 ? { tags } : {},
 		...sources !== void 0 ? { sources } : {},
 		...marketSources !== void 0 ? { marketSources } : {},
-		...trash !== void 0 ? { trash } : {}
+		...trash !== void 0 ? { trash } : {},
+		...record.skillStats !== void 0 ? { skillStats: record.skillStats } : {}
 	};
 }
 /** Sidecar state owner. */
@@ -171,6 +184,7 @@ var SkillHubStore = class {
 	sourcesByRepo = /* @__PURE__ */ new Map();
 	marketSources = [];
 	trashByName = /* @__PURE__ */ new Map();
+	skillStats = void 0;
 	loaded = false;
 	/** Serializes persist runs: concurrent mutators must not let an earlier
 	*  snapshot overwrite a later one (rename is atomic, ordering is not). */
@@ -250,6 +264,28 @@ var SkillHubStore = class {
 						});
 					}
 				}
+				const savedStats = migrated.skillStats;
+				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) {
+					const sessions = {};
+					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 = {};
+						for (const [name, stat] of Object.entries(entry.counts)) if (stat !== null && typeof stat === "object" && typeof stat.count === "number" && typeof stat.lastUsed === "number") counts[name] = {
+							count: stat.count,
+							lastUsed: stat.lastUsed
+						};
+						sessions[id] = {
+							createdAt: entry.createdAt,
+							counts
+						};
+					}
+					this.skillStats = {
+						windowDays: savedStats.windowDays,
+						frozenBefore: savedStats.frozenBefore,
+						frozenSessions: sessions,
+						lastFullReconcile: savedStats.lastFullReconcile
+					};
+				}
 			}
 		} catch (error) {
 			if (error.code !== "ENOENT") console.warn("[dsh-skill-hub] sidecar state unreadable, starting empty:", error instanceof Error ? error.message : error);
@@ -594,16 +630,36 @@ var SkillHubStore = class {
 		if (!this.trashByName.delete(name)) return;
 		await this.persist();
 	}
+	/** The persisted usage-statistics checkpoint (undefined until first saved). */
+	async getSkillStatsState() {
+		await this.ensureLoaded();
+		return this.skillStats !== void 0 ? {
+			...this.skillStats,
+			frozenSessions: { ...this.skillStats.frozenSessions }
+		} : void 0;
+	}
+	/** Persist a usage-statistics checkpoint (written at most ~once a day, on full reconciliations). */
+	async saveSkillStatsState(state) {
+		await this.ensureLoaded();
+		this.skillStats = {
+			windowDays: state.windowDays,
+			frozenBefore: state.frozenBefore,
+			frozenSessions: { ...state.frozenSessions },
+			lastFullReconcile: state.lastFullReconcile
+		};
+		await this.persist();
+	}
 	persist() {
 		const run = this.writeChain.then(async () => {
 			const payload = {
-				version: 3,
+				version: 4,
 				disabled: [...this.entries.values()],
 				config: this.config,
 				...this.tagsById.size > 0 ? { tags: [...this.tagsById.values()] } : {},
 				...this.sourcesByRepo.size > 0 ? { sources: [...this.sourcesByRepo.values()] } : {},
 				...this.marketSources.length > 0 ? { marketSources: [...this.marketSources] } : {},
-				...this.trashByName.size > 0 ? { trash: [...this.trashByName.values()] } : {}
+				...this.trashByName.size > 0 ? { trash: [...this.trashByName.values()] } : {},
+				...this.skillStats !== void 0 ? { skillStats: this.skillStats } : {}
 			};
 			const tmp = this.file + ".tmp";
 			await mkdir(dirname(this.file), { recursive: true });
@@ -1904,6 +1960,7 @@ async function buildCatalog(deps, cwd) {
 	const diagnostics = [...await scanDiagnostics("user-dsh", home), ...await scanDiagnostics("user-agents", home)];
 	return {
 		ok: true,
+		pluginVersion: CURRENT_VERSION,
 		complete,
 		skills,
 		disabled,
@@ -3011,6 +3068,9 @@ function makeRoutes(deps) {
 }
 //#endregion
 //#region src/stats.ts
+/** Fallback freeze horizon when no rolling window is configured (14 days). */
+const STATS_FREEZE_AFTER_MS = 336 * 60 * 60 * 1e3;
+const DAY_MS = 1440 * 60 * 1e3;
 /** Collect per-skill invocation counts and last-used times from one session. */
 function countSkillInvocations(events) {
 	const stats = /* @__PURE__ */ new Map();
@@ -3041,31 +3101,100 @@ function countSkillInvocations(events) {
 	}
 	return stats;
 }
-/** Scan every session and total per-skill counts, keeping the latest lastUsed. */
-async function readSkillStats(query) {
-	const totals = /* @__PURE__ */ new Map();
+function isFrozen(record, watermark) {
+	const created = record.header.createdAt;
+	return typeof created === "number" && created > 0 && created < watermark;
+}
+function mergeInto(totals, counted) {
+	for (const [name, stat] of counted) {
+		const total = totals[name];
+		if (total === void 0) totals[name] = { ...stat };
+		else {
+			total.count += stat.count;
+			if (stat.lastUsed > total.lastUsed) total.lastUsed = stat.lastUsed;
+		}
+	}
+}
+function toSorted(totals) {
+	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, nowMs) {
+	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, windowDays, nowMs) {
+	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, checkpoint, nowMs, windowDays) {
 	const sessions = await query.listSessions();
+	const cutoff = watermarkFor(windowDays, nowMs);
+	if (nowMs - checkpoint.lastFullReconcile >= 864e5 || checkpoint.windowDays !== windowDays) {
+		const cache = {};
+		const totals = {};
+		for (const record of sessions) {
+			let counted;
+			try {
+				counted = countSkillInvocations((await query.readSession(record.header.id)).events);
+			} catch {
+				continue;
+			}
+			const created = record.header.createdAt;
+			if (isFrozen(record, cutoff) && counted.size > 0 && typeof created === "number") cache[record.header.id] = {
+				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 = {};
 	for (const record of sessions) {
-		let snapshot;
+		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;
 		}
-		for (const [name, stat] of countSkillInvocations(snapshot.events)) {
-			const total = totals.get(name);
-			if (total === void 0) totals.set(name, { ...stat });
-			else {
-				total.count += stat.count;
-				if (stat.lastUsed > total.lastUsed) total.lastUsed = stat.lastUsed;
-			}
+	}
+	const totals = {};
+	for (const [id, entry] of Object.entries(checkpoint.frozenSessions)) {
+		if (!inWindow(entry.createdAt, windowDays, nowMs)) {
+			delete checkpoint.frozenSessions[id];
+			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
+	};
 }
 /**
 * Wrap a query in a stale-while-revalidate cache: responses never wait for a
@@ -3074,19 +3203,44 @@ async function readSkillStats(query) {
 * 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.
 */
-function createSkillStatsReader(query, ttlMs = 3e5) {
+function createSkillStatsReader(query, ttlMs = 3e5, options = {}) {
+	const checkpoint = options.checkpoint ?? {
+		windowDays: 0,
+		frozenBefore: 0,
+		frozenSessions: {},
+		lastFullReconcile: 0
+	};
+	const now = options.now ?? (() => Date.now());
 	let cached;
 	let cachedAt = 0;
 	let refreshing = null;
+	let lastScanDurationMs = 0;
 	return async () => {
-		if (cached !== void 0 && Date.now() - cachedAt < ttlMs) return cached;
-		if (refreshing === null) refreshing = readSkillStats(query).then((stats) => {
-			cached = stats;
-			cachedAt = Date.now();
-		}).catch(() => {}).finally(() => {
-			refreshing = null;
-		});
+		const startedAt = now();
+		const base = typeof ttlMs === "function" ? ttlMs() : ttlMs;
+		const ttl = Math.max(base, lastScanDurationMs * 3);
+		if (cached !== void 0 && startedAt - cachedAt < ttl) return cached;
+		if (refreshing === null) {
+			const windowDays = options.windowDays?.() ?? 0;
+			refreshing = scan(query, checkpoint, startedAt, windowDays).then(({ stats, mutated }) => {
+				cached = stats;
+				cachedAt = now();
+				lastScanDurationMs = Math.max(0, cachedAt - startedAt);
+				if (mutated) options.onCheckpoint?.({
+					...checkpoint,
+					frozenSessions: { ...checkpoint.frozenSessions }
+				});
+			}).catch(() => {}).finally(() => {
+				refreshing = null;
+			});
+		}
 		return cached ?? [];
 	};
 }
@@ -3106,7 +3260,9 @@ const Config = z.object({
 	enabled: z.boolean().default(HUB_CONFIG_DEFAULTS.enabled),
 	showUseCount: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseCount),
 	showUseTime: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseTime),
-	showGroupSummary: z.boolean().default(HUB_CONFIG_DEFAULTS.showGroupSummary)
+	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)
 });
 /**
 * Settings namespace hosting the hub's runtime config. Since dsh rc.7 the
@@ -3124,7 +3280,9 @@ const HubSettingsSchema = z.object({
 	showUseTime: z.boolean().default(HUB_CONFIG_DEFAULTS.showUseTime),
 	showGroupSummary: z.boolean().default(HUB_CONFIG_DEFAULTS.showGroupSummary),
 	dotModelColor: z.string().pattern(HEX_COLOR_RE),
-	dotUserColor: 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. */
 const SECTION_ORDER = 152;
@@ -3211,8 +3369,27 @@ function apply(ctx, config) {
 		}
 	})();
 	ctx.inject(["sessionQuery"], (sctx) => {
-		stats = createSkillStatsReader(sctx.sessionQuery);
-		sync();
+		(async () => {
+			const saved = await store.getSkillStatsState().catch(() => void 0);
+			const scanMinutes = () => {
+				const value = current().statsScanMinutes;
+				return typeof value === "number" && value >= 1 ? Math.floor(value) : HUB_CONFIG_DEFAULTS.statsScanMinutes;
+			};
+			const windowDays = () => {
+				const value = current().statsWindowDays;
+				return typeof value === "number" && value >= 0 ? Math.floor(value) : HUB_CONFIG_DEFAULTS.statsWindowDays;
+			};
+			stats = createSkillStatsReader(sctx.sessionQuery, () => scanMinutes() * 6e4, {
+				checkpoint: saved,
+				windowDays,
+				onCheckpoint: (next) => {
+					store.saveSkillStatsState(next).catch((error) => {
+						ctx.logger.warn("[dsh-skill-hub] persisting skill-stats checkpoint failed", error);
+					});
+				}
+			});
+			sync();
+		})();
 	});
 }
 //#endregion

package/lib/types/client/SkillHubSettingsCard.d.ts

@@ -20,6 +20,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. */
 export interface SkillHubSettingsCardFace {

package/lib/types/client/locales.d.ts

@@ -196,6 +196,10 @@ export declare const zh: {
     readonly 'settings.showUseTimeHint': "在技能名行右侧显示相对时间（如「3 天前」）。";
     readonly 'settings.showGroupSummary': "显示分组汇总";
     readonly 'settings.showGroupSummaryHint': "在分组标题后汇总调用次数与最近调用时间。";
+    readonly 'settings.statsWindowDays': "统计窗口（天）";
+    readonly 'settings.statsWindowDaysHint': "只统计最近 N 天的使用次数，默认 14 天；0 = 全部历史。改动立即生效。";
+    readonly 'settings.statsScanMinutes': "自动统计间隔（分钟）";
+    readonly 'settings.statsScanMinutesHint': "后台扫描会话日志的间隔，最小 1 分钟；扫描耗时会自动拉长间隔。";
     readonly 'settings.inherit': "继承";
     readonly 'settings.on': "开";
     readonly 'settings.off': "关";

package/lib/types/client/settings-card.d.ts

@@ -80,3 +80,21 @@ export interface ColorFieldProps {
     onReset: () => void;
 }
 export declare function ColorField(props: ColorFieldProps): ReactElement;
+/** 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 declare function NumberField(props: NumberFieldProps): ReactElement;

package/lib/types/client/settings-form.d.ts

@@ -23,6 +23,15 @@ export interface FieldSpec {
 export declare function booleanField(field: string): FieldSpec;
 /** A #rrggbb color field, edited through hex draft text. */
 export declare 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 declare function numberField(field: string, options?: {
+    min?: number;
+    max?: number;
+    integer?: boolean;
+}): FieldSpec;
 /** Card-level state the chrome renders. */
 export interface CardShell {
     available: boolean;

package/lib/types/index.d.ts

@@ -25,6 +25,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 declare const Config: z<Config>;
 /**

package/lib/types/protocol.d.ts

@@ -81,6 +81,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). */
@@ -179,6 +181,30 @@ export interface StatsResponse {
     /** Sorted per-skill invocation counts. */
     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;
@@ -199,6 +225,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;
 }
 /**
  * The resolved shape of the hub's settings namespace (schema defaults, then
@@ -216,6 +246,10 @@ export type HubSettingsValue = {
     dotModelColor?: string;
     /** User-invocable dot color (#rrggbb); absent means the panel default. */
     dotUserColor?: string;
+    /** 统计滚动窗口天数（0 = 全部历史）。 */
+    statsWindowDays?: number;
+    /** 自动统计扫描间隔（分钟）。 */
+    statsScanMinutes?: number;
 };
 /**
  * Hub config defaults — the single source every layer reads: the cordis
@@ -228,12 +262,15 @@ export declare const HUB_CONFIG_DEFAULTS: {
     readonly showUseCount: true;
     readonly showUseTime: true;
     readonly showGroupSummary: true;
+    readonly statsWindowDays: 14;
+    readonly statsScanMinutes: 5;
 };
 /**
  * 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 declare function resolveHubConfig(saved: Partial<HubConfig>, base?: Partial<HubConfig>): HubConfig;
 /** HEX color validation shared by host routes and the settings card. */
@@ -262,6 +299,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. */
 export interface MarketSourceRecord {

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;
 }