autosnippet 3.3.0 → 3.3.3

package/dist/lib/service/evolution/EnhancementSuggester.js

@@ -0,0 +1,220 @@
+/**
+ * EnhancementSuggester — 使用数据反推增强建议
+ *
+ * 4 种增强策略：
+ *   ① Guard 频繁命中但无 coreCode → 建议补充代码示例
+ *   ② Search 高频命中但 adoptions=0 → 建议改善 usageGuide
+ *   ③ 同类知识中 authority 偏低 → 建议补充 whenClause
+ *   ④ 关联 Recipe 已 deprecated → 建议检查引用是否过时
+ */
+import Logger from '../../infrastructure/logging/Logger.js';
+/* ────────────────────── Constants ────────────────────── */
+const GUARD_HIT_THRESHOLD = 5;
+const SEARCH_HIT_THRESHOLD = 10;
+const LOW_AUTHORITY_PERCENTILE = 0.25;
+/* ────────────────────── Class ────────────────────── */
+export class EnhancementSuggester {
+    #db;
+    #signalBus;
+    #reportStore;
+    #logger = Logger.getInstance();
+    constructor(db, options = {}) {
+        this.#db = db;
+        this.#signalBus = options.signalBus ?? null;
+        this.#reportStore = options.reportStore ?? null;
+    }
+    /**
+     * 运行全部 4 种增强策略
+     */
+    analyzeAll() {
+        const suggestions = [
+            ...this.#checkMissingCodeExamples(),
+            ...this.#checkLowAdoption(),
+            ...this.#checkLowAuthority(),
+            ...this.#checkDeprecatedReferences(),
+        ];
+        if (this.#reportStore && suggestions.length > 0) {
+            void this.#reportStore.write({
+                category: 'analysis',
+                type: 'enhancement_suggestions',
+                producer: 'EnhancementSuggester',
+                data: {
+                    count: suggestions.length,
+                    byType: this.#countByType(suggestions),
+                },
+                timestamp: Date.now(),
+            });
+        }
+        this.#logger.info(`EnhancementSuggester: ${suggestions.length} suggestions generated`);
+        return suggestions;
+    }
+    /* ── Strategy ①: Guard 频繁命中但无 coreCode ── */
+    #checkMissingCodeExamples() {
+        const rows = this.#db
+            .prepare(`SELECT id, title, coreCode, stats
+       FROM knowledge_entries
+       WHERE lifecycle IN ('active', 'staging') AND kind = 'rule'`)
+            .all();
+        const suggestions = [];
+        for (const row of rows) {
+            const hasCode = row.coreCode && row.coreCode.trim().length > 10;
+            if (hasCode) {
+                continue;
+            }
+            let stats = {};
+            try {
+                stats = JSON.parse(row.stats || '{}');
+            }
+            catch {
+                continue;
+            }
+            const guardHits = stats.guardHits || 0;
+            if (guardHits >= GUARD_HIT_THRESHOLD) {
+                suggestions.push({
+                    recipeId: row.id,
+                    title: row.title,
+                    type: 'missing_code_example',
+                    description: `Guard 已命中 ${guardHits} 次但无代码示例，建议补充 coreCode 帮助开发者理解正确用法`,
+                    priority: guardHits >= GUARD_HIT_THRESHOLD * 3 ? 'high' : 'medium',
+                    evidence: [`guardHits: ${guardHits}`, 'coreCode: empty'],
+                });
+            }
+        }
+        return suggestions;
+    }
+    /* ── Strategy ②: Search 高频命中但 adoptions=0 ── */
+    #checkLowAdoption() {
+        const rows = this.#db
+            .prepare(`SELECT id, title, stats
+       FROM knowledge_entries
+       WHERE lifecycle IN ('active', 'staging')`)
+            .all();
+        const suggestions = [];
+        for (const row of rows) {
+            let stats = {};
+            try {
+                stats = JSON.parse(row.stats || '{}');
+            }
+            catch {
+                continue;
+            }
+            const searchHits = stats.searchHits || 0;
+            const adoptions = stats.adoptions || 0;
+            if (searchHits >= SEARCH_HIT_THRESHOLD && adoptions === 0) {
+                suggestions.push({
+                    recipeId: row.id,
+                    title: row.title,
+                    type: 'low_adoption',
+                    description: `搜索命中 ${searchHits} 次但采纳为 0，建议改善 usageGuide 或 whenClause 使知识更具可操作性`,
+                    priority: searchHits >= SEARCH_HIT_THRESHOLD * 3 ? 'high' : 'medium',
+                    evidence: [`searchHits: ${searchHits}`, `adoptions: ${adoptions}`],
+                });
+            }
+        }
+        return suggestions;
+    }
+    /* ── Strategy ③: 同类知识中 authority 偏低 ── */
+    #checkLowAuthority() {
+        const rows = this.#db
+            .prepare(`SELECT id, title, category, stats
+       FROM knowledge_entries
+       WHERE lifecycle IN ('active', 'staging')`)
+            .all();
+        // 按 category 分组计算 authority 分位
+        const byCategory = new Map();
+        for (const row of rows) {
+            let stats = {};
+            try {
+                stats = JSON.parse(row.stats || '{}');
+            }
+            catch {
+                continue;
+            }
+            const authority = stats.authority || 0;
+            const cat = row.category || 'general';
+            if (!byCategory.has(cat)) {
+                byCategory.set(cat, []);
+            }
+            byCategory.get(cat).push({ id: row.id, title: row.title, authority });
+        }
+        const suggestions = [];
+        for (const [category, entries] of byCategory) {
+            if (entries.length < 3) {
+                continue; // 同类太少，无法比较
+            }
+            const sorted = entries.sort((a, b) => a.authority - b.authority);
+            const cutoff = Math.floor(sorted.length * LOW_AUTHORITY_PERCENTILE);
+            for (let i = 0; i < cutoff; i++) {
+                const entry = sorted[i];
+                suggestions.push({
+                    recipeId: entry.id,
+                    title: entry.title,
+                    type: 'low_authority',
+                    description: `在 "${category}" 类别中 authority 偏低 (${entry.authority})，建议补充 whenClause 和上下文描述`,
+                    priority: 'low',
+                    evidence: [
+                        `authority: ${entry.authority}`,
+                        `category: ${category}`,
+                        `rank: ${i + 1}/${sorted.length}`,
+                    ],
+                });
+            }
+        }
+        return suggestions;
+    }
+    /* ── Strategy ④: 关联 Recipe 已 deprecated ── */
+    #checkDeprecatedReferences() {
+        const rows = this.#db
+            .prepare(`SELECT id, title, relations
+       FROM knowledge_entries
+       WHERE lifecycle IN ('active', 'staging')`)
+            .all();
+        const suggestions = [];
+        for (const row of rows) {
+            let relations = {};
+            try {
+                relations = JSON.parse(row.relations || '{}');
+            }
+            catch {
+                continue;
+            }
+            // 检查 related, depends_on 等关系桶中的 ID
+            const relatedIds = [];
+            for (const [bucket, ids] of Object.entries(relations)) {
+                if (bucket === 'deprecated_by') {
+                    continue; // 自身的 deprecated_by 不算
+                }
+                if (Array.isArray(ids)) {
+                    relatedIds.push(...ids);
+                }
+            }
+            if (relatedIds.length === 0) {
+                continue;
+            }
+            // 批量检查关联条目的 lifecycle
+            const placeholders = relatedIds.map(() => '?').join(',');
+            const deprecated = this.#db
+                .prepare(`SELECT id, title FROM knowledge_entries WHERE id IN (${placeholders}) AND lifecycle = 'deprecated'`)
+                .all(...relatedIds);
+            for (const dep of deprecated) {
+                suggestions.push({
+                    recipeId: row.id,
+                    title: row.title,
+                    type: 'deprecated_reference',
+                    description: `引用了已废弃的 Recipe "${dep.title}" (${dep.id})，建议检查引用是否过时`,
+                    priority: 'high',
+                    evidence: [`referenced: ${dep.id}`, `referenced_title: ${dep.title}`],
+                });
+            }
+        }
+        return suggestions;
+    }
+    /* ── Helpers ── */
+    #countByType(suggestions) {
+        const counts = {};
+        for (const s of suggestions) {
+            counts[s.type] = (counts[s.type] || 0) + 1;
+        }
+        return counts;
+    }
+}

package/dist/lib/service/evolution/KnowledgeMetabolism.d.ts

@@ -0,0 +1,82 @@
+/**
+ * KnowledgeMetabolism — 知识新陈代谢总线
+ *
+ * 治理总线：编排三种进化策略 (矛盾检测 + 冗余分析 + 衰退检测)
+ * 产出 EvolutionProposal，通过 ConfidenceRouter + 状态机 驱动转换。
+ *
+ * 入口：
+ *   - runFullCycle() — 完整治理周期（日常定时 / 手动触发）
+ *   - checkDecay() — 只做衰退扫描
+ *   - checkContradictions() — 只做矛盾检测
+ *   - checkRedundancy() — 只做冗余分析
+ */
+import type { ReportStore } from '../../infrastructure/report/ReportStore.js';
+import type { SignalBus } from '../../infrastructure/signal/SignalBus.js';
+import type { ContradictionDetector, ContradictionResult } from './ContradictionDetector.js';
+import type { DecayDetector, DecayScoreResult } from './DecayDetector.js';
+import type { RedundancyAnalyzer, RedundancyResult } from './RedundancyAnalyzer.js';
+export type ProposalType = 'merge' | 'enhance' | 'refine_guard' | 'split' | 'deprecate' | 'review';
+export interface EvolutionProposal {
+    /** 进化提案类型 */
+    type: ProposalType;
+    /** 目标 Recipe ID */
+    targetRecipeId: string;
+    /** 关联 Recipe IDs（合并/矛盾对象） */
+    relatedRecipeIds: string[];
+    /** 置信度 0-1 */
+    confidence: number;
+    /** 触发来源 */
+    source: 'contradiction' | 'redundancy' | 'decay' | 'enhancement';
+    /** 描述 */
+    description: string;
+    /** 原始信号证据 */
+    evidence: string[];
+    /** 创建时间 */
+    proposedAt: number;
+    /** 过期时间 (proposedAt + 7d) */
+    expiresAt: number;
+}
+export interface MetabolismReport {
+    /** 矛盾检测结果 */
+    contradictions: ContradictionResult[];
+    /** 冗余分析结果 */
+    redundancies: RedundancyResult[];
+    /** 衰退评估结果 */
+    decayResults: DecayScoreResult[];
+    /** 生成的进化提案 */
+    proposals: EvolutionProposal[];
+    /** 统计摘要 */
+    summary: {
+        totalScanned: number;
+        contradictionCount: number;
+        redundancyCount: number;
+        decayingCount: number;
+        proposalCount: number;
+    };
+}
+export declare class KnowledgeMetabolism {
+    #private;
+    constructor(options: {
+        contradictionDetector: ContradictionDetector;
+        redundancyAnalyzer: RedundancyAnalyzer;
+        decayDetector: DecayDetector;
+        signalBus?: SignalBus;
+        reportStore?: ReportStore;
+    });
+    /**
+     * 执行完整治理周期
+     */
+    runFullCycle(): MetabolismReport;
+    /**
+     * 只执行衰退扫描
+     */
+    checkDecay(): DecayScoreResult[];
+    /**
+     * 只执行矛盾检测
+     */
+    checkContradictions(): ContradictionResult[];
+    /**
+     * 只执行冗余分析
+     */
+    checkRedundancy(): RedundancyResult[];
+}

package/dist/lib/service/evolution/KnowledgeMetabolism.js

@@ -0,0 +1,167 @@
+/**
+ * KnowledgeMetabolism — 知识新陈代谢总线
+ *
+ * 治理总线：编排三种进化策略 (矛盾检测 + 冗余分析 + 衰退检测)
+ * 产出 EvolutionProposal，通过 ConfidenceRouter + 状态机 驱动转换。
+ *
+ * 入口：
+ *   - runFullCycle() — 完整治理周期（日常定时 / 手动触发）
+ *   - checkDecay() — 只做衰退扫描
+ *   - checkContradictions() — 只做矛盾检测
+ *   - checkRedundancy() — 只做冗余分析
+ */
+import Logger from '../../infrastructure/logging/Logger.js';
+/* ────────────────────── Constants ────────────────────── */
+const PROPOSAL_TTL = 7 * 24 * 60 * 60 * 1000; // 7 days
+/* ────────────────────── Class ────────────────────── */
+export class KnowledgeMetabolism {
+    #contradictionDetector;
+    #redundancyAnalyzer;
+    #decayDetector;
+    #signalBus;
+    #reportStore;
+    #logger = Logger.getInstance();
+    #pendingTriggers = [];
+    #debounceTimer = null;
+    constructor(options) {
+        this.#contradictionDetector = options.contradictionDetector;
+        this.#redundancyAnalyzer = options.redundancyAnalyzer;
+        this.#decayDetector = options.decayDetector;
+        this.#signalBus = options.signalBus ?? null;
+        this.#reportStore = options.reportStore ?? null;
+        // Phase 2: 订阅告警型信号，触发代谢周期
+        if (this.#signalBus) {
+            this.#signalBus.subscribe('decay|quality|anomaly', (signal) => {
+                this.#pendingTriggers.push(signal);
+                this.#scheduleMetabolism();
+            });
+        }
+    }
+    #scheduleMetabolism() {
+        if (this.#debounceTimer) {
+            return;
+        }
+        this.#debounceTimer = setTimeout(() => {
+            this.#debounceTimer = null;
+            if (this.#pendingTriggers.length > 0) {
+                this.runFullCycle();
+                this.#pendingTriggers = [];
+            }
+        }, 30_000);
+    }
+    /**
+     * 执行完整治理周期
+     */
+    runFullCycle() {
+        this.#logger.info('KnowledgeMetabolism: starting full governance cycle');
+        // 1. 衰退检测
+        const decayResults = this.#decayDetector.scanAll();
+        // 2. 矛盾检测
+        const contradictions = this.#contradictionDetector.detectAll();
+        // 3. 冗余分析
+        const redundancies = this.#redundancyAnalyzer.analyzeAll();
+        // 4. 生成进化提案
+        const proposals = [
+            ...this.#proposalsFromContradictions(contradictions),
+            ...this.#proposalsFromRedundancies(redundancies),
+            ...this.#proposalsFromDecay(decayResults),
+        ];
+        // 5. 写入治理报告（降级：不再发射 Signal，改为 Report）
+        if (this.#reportStore && proposals.length > 0) {
+            void this.#reportStore.write({
+                category: 'governance',
+                type: 'metabolism_cycle',
+                producer: 'KnowledgeMetabolism',
+                data: {
+                    proposalCount: proposals.length,
+                    contradictionCount: contradictions.length,
+                    redundancyCount: redundancies.length,
+                    decayingCount: decayResults.filter((d) => d.level !== 'healthy' && d.level !== 'watch')
+                        .length,
+                },
+                timestamp: Date.now(),
+            });
+        }
+        const report = {
+            contradictions,
+            redundancies,
+            decayResults,
+            proposals,
+            summary: {
+                totalScanned: decayResults.length,
+                contradictionCount: contradictions.length,
+                redundancyCount: redundancies.length,
+                decayingCount: decayResults.filter((d) => d.level !== 'healthy' && d.level !== 'watch')
+                    .length,
+                proposalCount: proposals.length,
+            },
+        };
+        this.#logger.info(`KnowledgeMetabolism: cycle complete — ${report.summary.proposalCount} proposals generated`);
+        return report;
+    }
+    /**
+     * 只执行衰退扫描
+     */
+    checkDecay() {
+        return this.#decayDetector.scanAll();
+    }
+    /**
+     * 只执行矛盾检测
+     */
+    checkContradictions() {
+        return this.#contradictionDetector.detectAll();
+    }
+    /**
+     * 只执行冗余分析
+     */
+    checkRedundancy() {
+        return this.#redundancyAnalyzer.analyzeAll();
+    }
+    /* ── Proposal Generation ── */
+    #proposalsFromContradictions(results) {
+        const now = Date.now();
+        return results.map((r) => ({
+            type: r.type === 'hard' ? 'merge' : 'review',
+            targetRecipeId: r.recipeA,
+            relatedRecipeIds: [r.recipeB],
+            confidence: r.confidence,
+            source: 'contradiction',
+            description: `${r.type === 'hard' ? 'Hard' : 'Soft'} contradiction detected between recipes`,
+            evidence: r.evidence,
+            proposedAt: now,
+            expiresAt: now + PROPOSAL_TTL,
+        }));
+    }
+    #proposalsFromRedundancies(results) {
+        const now = Date.now();
+        return results.map((r) => ({
+            type: 'merge',
+            targetRecipeId: r.recipeA,
+            relatedRecipeIds: [r.recipeB],
+            confidence: r.similarity,
+            source: 'redundancy',
+            description: `Redundant content detected (similarity: ${(r.similarity * 100).toFixed(0)}%)`,
+            evidence: Object.entries(r.dimensions)
+                .filter(([, v]) => v > 0)
+                .map(([k, v]) => `${k}: ${(v * 100).toFixed(0)}%`),
+            proposedAt: now,
+            expiresAt: now + PROPOSAL_TTL,
+        }));
+    }
+    #proposalsFromDecay(results) {
+        const now = Date.now();
+        return results
+            .filter((r) => r.level === 'decaying' || r.level === 'severe' || r.level === 'dead')
+            .map((r) => ({
+            type: 'deprecate',
+            targetRecipeId: r.recipeId,
+            relatedRecipeIds: [],
+            confidence: Math.max(0.4, 1 - r.decayScore / 100),
+            source: 'decay',
+            description: `Decay detected: score=${r.decayScore}, level=${r.level}`,
+            evidence: r.signals.map((s) => `${s.strategy}: ${s.detail}`),
+            proposedAt: now,
+            expiresAt: now + PROPOSAL_TTL,
+        }));
+    }
+}

package/dist/lib/service/evolution/RedundancyAnalyzer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * RedundancyAnalyzer — 多维冗余检测
+ *
+ * 从 CandidateAggregator 的标题 Jaccard 扩展到四维内容级相似度：
+ *   维度 1: title Jaccard ≥ 0.7
+ *   维度 2: doClause + dontClause 文本相似度 ≥ 0.6
+ *   维度 3: coreCode 去空白后字符级相似度 ≥ 0.8
+ *   维度 4: guard regex 完全相同
+ *
+ * 综合: weighted_sum(0.2*d1 + 0.3*d2 + 0.3*d3 + 0.2*d4) ≥ 0.65
+ */
+import type { ReportStore } from '../../infrastructure/report/ReportStore.js';
+import type { SignalBus } from '../../infrastructure/signal/SignalBus.js';
+interface DatabaseLike {
+    prepare(sql: string): {
+        all(...params: unknown[]): Record<string, unknown>[];
+    };
+}
+export interface RedundancyResult {
+    recipeA: string;
+    recipeB: string;
+    similarity: number;
+    dimensions: {
+        title: number;
+        clause: number;
+        code: number;
+        guard: number;
+    };
+}
+interface RecipeForRedundancy {
+    id: string;
+    title: string;
+    doClause: string | null;
+    dontClause: string | null;
+    coreCode: string | null;
+    guardPattern: string | null;
+}
+export declare class RedundancyAnalyzer {
+    #private;
+    constructor(db: DatabaseLike, options?: {
+        signalBus?: SignalBus;
+        reportStore?: ReportStore;
+    });
+    /**
+     * 分析所有 active/staging 条目之间的冗余
+     */
+    analyzeAll(): RedundancyResult[];
+    /**
+     * 分析两条 Recipe 的冗余度
+     */
+    analyzePair(a: RecipeForRedundancy, b: RecipeForRedundancy): RedundancyResult | null;
+}
+export {};