autosnippet 3.2.15 → 3.2.17

package/dist/lib/service/skills/EventAggregator.js

@@ -32,10 +32,9 @@ export class EventAggregator {
     #dedupeMs;
     #logger;
     /**
-     * @param {object} [opts]
-     * @param {number} [opts.windowMs=5000]    聚合时间窗口（毫秒）
-     * @param {number} [opts.maxBatch=50]      单次 batch 最大事件数
-     * @param {number} [opts.dedupeMs=60000]   相同事件去重窗口（毫秒）
+     * @param [opts.windowMs=5000] 聚合时间窗口（毫秒）
+     * @param [opts.maxBatch=50] 单次 batch 最大事件数
+     * @param [opts.dedupeMs=60000] 相同事件去重窗口（毫秒）
      */
     constructor({ windowMs = DEFAULT_WINDOW_MS, maxBatch = DEFAULT_MAX_BATCH, dedupeMs = DEFAULT_DEDUPE_MS, } = {}) {
         this.#windowMs = windowMs;
@@ -45,10 +44,9 @@ export class EventAggregator {
     }
     /**
      * 推送一个事件到聚合器
-     * @param {string} key 聚合键（如 'file_change', 'guard_violation'）
-     * @param {object} event 事件数据
-     * @param {object} [opts]
-     * @param {string} [opts.dedupeId] 去重标识（默认为 JSON hash）
+     * @param key 聚合键（如 'file_change', 'guard_violation'）
+     * @param event 事件数据
+     * @param [opts.dedupeId] 去重标识（默认为 JSON hash）
      */
     push(key, event, { dedupeId } = {}) {
         // 去重检查
@@ -75,28 +73,20 @@ export class EventAggregator {
         }
         bucket.timer = setTimeout(() => this.#flush(key), this.#windowMs);
     }
-    /**
-     * 注册 batch 事件监听器
-     * @param {'batch'} eventName
-     * @param {(key: string, events: Record<string, unknown>[]) => void} fn
-     */
+    /** 注册 batch 事件监听器 */
     on(eventName, fn) {
         if (!this.#listeners.has(eventName)) {
             this.#listeners.set(eventName, []);
         }
         this.#listeners.get(eventName).push(fn);
     }
-    /**
-     * 立即刷新所有待处理 bucket
-     */
+    /** 立即刷新所有待处理 bucket */
     flushAll() {
         for (const key of this.#buckets.keys()) {
             this.#flush(key);
         }
     }
-    /**
-     * 停止所有计时器
-     */
+    /** 停止所有计时器 */
     destroy() {
         for (const [, bucket] of this.#buckets) {
             if (bucket.timer) {
@@ -107,9 +97,7 @@ export class EventAggregator {
         this.#dedupeMap.clear();
         this.#listeners.clear();
     }
-    /**
-     * 获取待处理事件数
-     */
+    /** 获取待处理事件数 */
     get pendingCount() {
         let count = 0;
         for (const [, bucket] of this.#buckets) {
@@ -175,4 +163,3 @@ export class EventAggregator {
     }
 }
 export default EventAggregator;
-//# sourceMappingURL=EventAggregator.js.map

package/dist/lib/service/skills/FeedbackStore.d.ts

@@ -0,0 +1,35 @@
+/**
+ * FeedbackStore — 推荐反馈持久化与用户偏好推导
+ *
+ * 存储位置: {projectRoot}/.autosnippet/feedback.jsonl
+ * 格式: 每行一个 JSON 对象 (append-only log)
+ *
+ * 职责:
+ *   - 记录用户对推荐的反馈 (adopted / dismissed / expired / viewed / modified)
+ *   - 计算采纳率、查看率、按来源分组的采纳率
+ *   - 推导用户偏好向量 (喜欢/回避的类别和来源)
+ *   - 检测被频繁忽略的推荐类别
+ */
+import type { RecommendationFeedback, RecommendationMetricsSnapshot, UserPreference } from './types.js';
+export declare class FeedbackStore {
+    #private;
+    constructor(projectRoot: string);
+    /** 记录一条反馈 */
+    record(feedback: RecommendationFeedback): Promise<void>;
+    /**
+     * 获取采纳率
+     * @param source 可选 — 按推荐来源过滤
+     */
+    getAdoptionRate(source?: string): number;
+    /** 获取用户偏好向量 (基于历史反馈推导) */
+    getUserPreference(): UserPreference;
+    /** 特定类别的推荐是否被用户频繁忽略 */
+    isFrequentlyDismissed(category: string): boolean;
+    /** 获取推荐效果指标快照 */
+    getMetricsSnapshot(since?: Date): RecommendationMetricsSnapshot;
+    /** 获取指定推荐 ID 的反馈历史 */
+    getFeedbackFor(recommendationId: string): RecommendationFeedback[];
+    /** 全部反馈条数 */
+    get size(): number;
+}
+export default FeedbackStore;

package/dist/lib/service/skills/FeedbackStore.js

@@ -0,0 +1,240 @@
+/**
+ * FeedbackStore — 推荐反馈持久化与用户偏好推导
+ *
+ * 存储位置: {projectRoot}/.autosnippet/feedback.jsonl
+ * 格式: 每行一个 JSON 对象 (append-only log)
+ *
+ * 职责:
+ *   - 记录用户对推荐的反馈 (adopted / dismissed / expired / viewed / modified)
+ *   - 计算采纳率、查看率、按来源分组的采纳率
+ *   - 推导用户偏好向量 (喜欢/回避的类别和来源)
+ *   - 检测被频繁忽略的推荐类别
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { RUNTIME_DIR } from '#shared/ProjectMarkers.js';
+import Logger from '../../infrastructure/logging/Logger.js';
+const FEEDBACK_FILE = 'feedback.jsonl';
+/** 频繁忽略阈值: 该类别至少 5 次且忽略率 >= 70% */
+const DISMISS_MIN_COUNT = 5;
+const DISMISS_THRESHOLD = 0.7;
+/** 内存缓存条数上限 (JSONL 可无限追加，但内存只保留最近 N 条) */
+const MAX_MEMORY_ENTRIES = 2000;
+export class FeedbackStore {
+    #filePath;
+    #logger;
+    #entries = [];
+    #loaded = false;
+    constructor(projectRoot) {
+        this.#filePath = path.join(projectRoot, RUNTIME_DIR, FEEDBACK_FILE);
+        this.#logger = Logger.getInstance();
+    }
+    // ─── 公共 API ──────────────────────────────────────────
+    /** 记录一条反馈 */
+    async record(feedback) {
+        this.#ensureLoaded();
+        const entry = {
+            ...feedback,
+            timestamp: feedback.timestamp || new Date().toISOString(),
+            _ts: new Date().toISOString(),
+        };
+        this.#entries.push(entry);
+        // 内存溢出保护
+        if (this.#entries.length > MAX_MEMORY_ENTRIES) {
+            this.#entries = this.#entries.slice(-MAX_MEMORY_ENTRIES);
+        }
+        // 追加写入 JSONL
+        try {
+            const dir = path.dirname(this.#filePath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            fs.appendFileSync(this.#filePath, `${JSON.stringify(entry)}\n`, 'utf-8');
+        }
+        catch (err) {
+            this.#logger.warn('FeedbackStore: failed to persist feedback', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    /**
+     * 获取采纳率
+     * @param source 可选 — 按推荐来源过滤
+     */
+    getAdoptionRate(source) {
+        this.#ensureLoaded();
+        const filtered = source ? this.#entries.filter((e) => e.source === source) : this.#entries;
+        const adopted = filtered.filter((e) => e.action === 'adopted' || e.action === 'modified').length;
+        const dismissed = filtered.filter((e) => e.action === 'dismissed').length;
+        const total = adopted + dismissed;
+        if (total === 0) {
+            return 0;
+        }
+        return adopted / total;
+    }
+    /** 获取用户偏好向量 (基于历史反馈推导) */
+    getUserPreference() {
+        this.#ensureLoaded();
+        const categoryStats = new Map();
+        const sourceStats = new Map();
+        for (const entry of this.#entries) {
+            const cat = entry.category ?? 'unknown';
+            const src = entry.source ?? 'unknown';
+            // 按类别
+            if (!categoryStats.has(cat)) {
+                categoryStats.set(cat, { adopted: 0, dismissed: 0 });
+            }
+            const cs = categoryStats.get(cat);
+            if (entry.action === 'adopted' || entry.action === 'modified') {
+                cs.adopted++;
+            }
+            if (entry.action === 'dismissed') {
+                cs.dismissed++;
+            }
+            // 按来源
+            if (!sourceStats.has(src)) {
+                sourceStats.set(src, { adopted: 0, dismissed: 0 });
+            }
+            const ss = sourceStats.get(src);
+            if (entry.action === 'adopted' || entry.action === 'modified') {
+                ss.adopted++;
+            }
+            if (entry.action === 'dismissed') {
+                ss.dismissed++;
+            }
+        }
+        const preferredCategories = [];
+        const avoidedCategories = [];
+        for (const [cat, stats] of categoryStats) {
+            const total = stats.adopted + stats.dismissed;
+            if (total < 3) {
+                continue;
+            }
+            const rate = stats.adopted / total;
+            if (rate >= 0.6) {
+                preferredCategories.push(cat);
+            }
+            if (rate <= 0.3) {
+                avoidedCategories.push(cat);
+            }
+        }
+        const preferredSources = [];
+        for (const [src, stats] of sourceStats) {
+            const total = stats.adopted + stats.dismissed;
+            if (total >= 3 && stats.adopted / total >= 0.5) {
+                preferredSources.push(src);
+            }
+        }
+        return {
+            preferredCategories,
+            avoidedCategories,
+            preferredSources,
+            adoptionRate: this.getAdoptionRate(),
+        };
+    }
+    /** 特定类别的推荐是否被用户频繁忽略 */
+    isFrequentlyDismissed(category) {
+        this.#ensureLoaded();
+        const entries = this.#entries.filter((e) => e.category === category);
+        const dismissed = entries.filter((e) => e.action === 'dismissed').length;
+        const adopted = entries.filter((e) => e.action === 'adopted' || e.action === 'modified').length;
+        const total = dismissed + adopted;
+        if (total < DISMISS_MIN_COUNT) {
+            return false;
+        }
+        return dismissed / total >= DISMISS_THRESHOLD;
+    }
+    /** 获取推荐效果指标快照 */
+    getMetricsSnapshot(since) {
+        this.#ensureLoaded();
+        const sinceTs = since?.toISOString() ?? '1970-01-01T00:00:00.000Z';
+        const filtered = this.#entries.filter((e) => e.timestamp >= sinceTs);
+        const totalRecommendations = filtered.length;
+        const totalViewed = filtered.filter((e) => e.action === 'viewed').length;
+        const totalAdopted = filtered.filter((e) => e.action === 'adopted' || e.action === 'modified').length;
+        const totalDismissed = filtered.filter((e) => e.action === 'dismissed').length;
+        const totalExpired = filtered.filter((e) => e.action === 'expired').length;
+        // 按来源分组采纳率
+        const sourceMap = new Map();
+        for (const entry of filtered) {
+            const src = entry.source ?? 'unknown';
+            if (!sourceMap.has(src)) {
+                sourceMap.set(src, { adopted: 0, total: 0 });
+            }
+            const s = sourceMap.get(src);
+            if (entry.action === 'adopted' ||
+                entry.action === 'modified' ||
+                entry.action === 'dismissed') {
+                s.total++;
+            }
+            if (entry.action === 'adopted' || entry.action === 'modified') {
+                s.adopted++;
+            }
+        }
+        const adoptionRateBySource = {};
+        for (const [src, stats] of sourceMap) {
+            adoptionRateBySource[src] = stats.total > 0 ? stats.adopted / stats.total : 0;
+        }
+        const decisionTotal = totalAdopted + totalDismissed;
+        return {
+            totalRecommendations,
+            totalViewed,
+            totalAdopted,
+            totalDismissed,
+            totalExpired,
+            adoptionRate: decisionTotal > 0 ? totalAdopted / decisionTotal : 0,
+            viewRate: totalRecommendations > 0 ? totalViewed / totalRecommendations : 0,
+            adoptionRateBySource,
+            since: sinceTs,
+        };
+    }
+    /** 获取指定推荐 ID 的反馈历史 */
+    getFeedbackFor(recommendationId) {
+        this.#ensureLoaded();
+        return this.#entries.filter((e) => e.recommendationId === recommendationId);
+    }
+    /** 全部反馈条数 */
+    get size() {
+        this.#ensureLoaded();
+        return this.#entries.length;
+    }
+    // ─── 内部方法 ──────────────────────────────────────────
+    /** 惰性加载: 首次访问时从 JSONL 文件读取历史 */
+    #ensureLoaded() {
+        if (this.#loaded) {
+            return;
+        }
+        this.#loaded = true;
+        this.#loadFromDisk();
+    }
+    #loadFromDisk() {
+        try {
+            if (!fs.existsSync(this.#filePath)) {
+                return;
+            }
+            const content = fs.readFileSync(this.#filePath, 'utf-8');
+            const lines = content.trim().split('\n').filter(Boolean);
+            const entries = [];
+            for (const line of lines) {
+                try {
+                    entries.push(JSON.parse(line));
+                }
+                catch {
+                    // 跳过损坏行
+                }
+            }
+            // 只保留最近 N 条
+            this.#entries =
+                entries.length > MAX_MEMORY_ENTRIES ? entries.slice(-MAX_MEMORY_ENTRIES) : entries;
+            if (this.#entries.length > 0) {
+                this.#logger.debug(`FeedbackStore: loaded ${this.#entries.length} entries from disk`);
+            }
+        }
+        catch (err) {
+            this.#logger.warn('FeedbackStore: failed to load from disk', {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+}
+export default FeedbackStore;

package/dist/lib/service/skills/RecommendationMetrics.d.ts

@@ -0,0 +1,45 @@
+/**
+ * RecommendationMetrics — 推荐效果度量追踪
+ *
+ * 追踪推荐系统的关键指标:
+ *   - 展示次数 (display)
+ *   - 查看次数 (view)
+ *   - 采纳次数 (adopt)
+ *   - 忽略次数 (dismiss)
+ *   - 采纳率 = adopt / (adopt + dismiss)
+ *   - CTR = view / display
+ *
+ * 所有数据委托给 FeedbackStore 持久化。
+ * 本类只负责实时聚合 + 对外暴露接口。
+ */
+import type { FeedbackStore } from './FeedbackStore.js';
+import type { RecommendationMetricsSnapshot, ScoredRecommendation } from './types.js';
+interface MetricsCounters {
+    displayed: number;
+    viewed: number;
+    adopted: number;
+    dismissed: number;
+    expired: number;
+}
+export declare class RecommendationMetrics {
+    #private;
+    constructor(feedbackStore: FeedbackStore);
+    /** 记录推荐已展示 (dashboard/MCP 返回推荐列表时调用) */
+    trackDisplayed(recommendations: ScoredRecommendation[]): void;
+    /** 记录推荐被采纳 */
+    trackAdopted(recommendationId: string, source?: string, category?: string): Promise<void>;
+    /** 记录推荐被忽略 */
+    trackDismissed(recommendationId: string, reason?: string, source?: string, category?: string): Promise<void>;
+    /** 记录推荐过期 */
+    trackExpired(recommendationId: string, source?: string): Promise<void>;
+    /** 获取当前会话的指标 */
+    getSessionMetrics(): MetricsCounters & {
+        adoptionRate: number;
+        ctr: number;
+    };
+    /** 获取全局指标快照 (含持久化历史) */
+    getGlobalSnapshot(since?: Date): RecommendationMetricsSnapshot;
+    /** 获取指定来源的采纳率 */
+    getAdoptionRateBySource(source: string): number;
+}
+export default RecommendationMetrics;

package/dist/lib/service/skills/RecommendationMetrics.js

@@ -0,0 +1,105 @@
+/**
+ * RecommendationMetrics — 推荐效果度量追踪
+ *
+ * 追踪推荐系统的关键指标:
+ *   - 展示次数 (display)
+ *   - 查看次数 (view)
+ *   - 采纳次数 (adopt)
+ *   - 忽略次数 (dismiss)
+ *   - 采纳率 = adopt / (adopt + dismiss)
+ *   - CTR = view / display
+ *
+ * 所有数据委托给 FeedbackStore 持久化。
+ * 本类只负责实时聚合 + 对外暴露接口。
+ */
+import Logger from '../../infrastructure/logging/Logger.js';
+export class RecommendationMetrics {
+    #feedbackStore;
+    #logger;
+    /** 内存计数器 — 只追踪本次进程的增量 */
+    #session = {
+        displayed: 0,
+        viewed: 0,
+        adopted: 0,
+        dismissed: 0,
+        expired: 0,
+    };
+    constructor(feedbackStore) {
+        this.#feedbackStore = feedbackStore;
+        this.#logger = Logger.getInstance();
+    }
+    // ─── 事件记录 ──────────────────────────────────────────
+    /** 记录推荐已展示 (dashboard/MCP 返回推荐列表时调用) */
+    trackDisplayed(recommendations) {
+        this.#session.displayed += recommendations.length;
+        // 记录 viewed 事件到 FeedbackStore (展示即视为曝光)
+        for (const rec of recommendations) {
+            this.#feedbackStore
+                .record({
+                recommendationId: rec.recommendationId,
+                action: 'viewed',
+                timestamp: new Date().toISOString(),
+                source: rec.source,
+                category: rec.signals.category,
+            })
+                .catch((err) => {
+                this.#logger.warn('RecommendationMetrics: failed to record viewed', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            });
+        }
+    }
+    /** 记录推荐被采纳 */
+    async trackAdopted(recommendationId, source, category) {
+        this.#session.adopted++;
+        await this.#feedbackStore.record({
+            recommendationId,
+            action: 'adopted',
+            timestamp: new Date().toISOString(),
+            source,
+            category,
+        });
+    }
+    /** 记录推荐被忽略 */
+    async trackDismissed(recommendationId, reason, source, category) {
+        this.#session.dismissed++;
+        await this.#feedbackStore.record({
+            recommendationId,
+            action: 'dismissed',
+            timestamp: new Date().toISOString(),
+            source,
+            category,
+            reason,
+        });
+    }
+    /** 记录推荐过期 */
+    async trackExpired(recommendationId, source) {
+        this.#session.expired++;
+        await this.#feedbackStore.record({
+            recommendationId,
+            action: 'expired',
+            timestamp: new Date().toISOString(),
+            source,
+        });
+    }
+    // ─── 查询 ──────────────────────────────────────────────
+    /** 获取当前会话的指标 */
+    getSessionMetrics() {
+        const s = this.#session;
+        const decisionTotal = s.adopted + s.dismissed;
+        return {
+            ...s,
+            adoptionRate: decisionTotal > 0 ? s.adopted / decisionTotal : 0,
+            ctr: s.displayed > 0 ? s.viewed / s.displayed : 0,
+        };
+    }
+    /** 获取全局指标快照 (含持久化历史) */
+    getGlobalSnapshot(since) {
+        return this.#feedbackStore.getMetricsSnapshot(since);
+    }
+    /** 获取指定来源的采纳率 */
+    getAdoptionRateBySource(source) {
+        return this.#feedbackStore.getAdoptionRate(source);
+    }
+}
+export default RecommendationMetrics;

package/dist/lib/service/skills/RecommendationPipeline.d.ts

@@ -0,0 +1,38 @@
+/**
+ * RecommendationPipeline — 统一推荐管线
+ *
+ * 多阶段处理:
+ *   1. Recall  — 多策略并行召回候选 (Rule / AI / Vector / Popularity)
+ *   2. Score   — 综合评分 (信号强度 × 用户偏好 × 新鲜度)
+ *   3. Rank    — 排序 + 截断
+ *   4. Filter  — 去重、过滤已有 Skill、过滤频繁忽略的类别
+ *   5. Deliver — 输出最终推荐列表 + 触发 Hook
+ *
+ * 设计原则:
+ *   - 静默降级: 任何策略失败不影响其他策略
+ *   - 离线优先: 无 AI 时降级到规则召回
+ *   - 反馈闪环: 利用 FeedbackStore 调整排序权重
+ */
+import type { FeedbackStore } from './FeedbackStore.js';
+import type { SkillHooks } from './SkillHooks.js';
+import type { RecallStrategy, RecommendationContext, ScoredRecommendation } from './types.js';
+export declare class RecommendationPipeline {
+    #private;
+    constructor(opts?: {
+        feedbackStore?: FeedbackStore | null;
+        skillHooks?: SkillHooks | null;
+    });
+    /** 注册召回策略 */
+    addStrategy(strategy: RecallStrategy): void;
+    /** 获取已注册策略列表 */
+    getStrategies(): ReadonlyArray<RecallStrategy>;
+    /**
+     * 执行推荐管线
+     *
+     * @param context 推荐上下文
+     * @param topK 最多返回数量
+     * @returns 排序后的推荐结果列表
+     */
+    recommend(context: RecommendationContext, topK?: number): Promise<ScoredRecommendation[]>;
+}
+export default RecommendationPipeline;