autosnippet 3.3.2 → 3.3.3

package/dist/lib/service/panorama/PanoramaService.d.ts

@@ -57,6 +57,23 @@ export interface PanoramaModuleDetail {
         direction: 'in' | 'out';
         weight: number;
     }>;
+    /** File groups by subdirectory within the module */
+    fileGroups: Array<{
+        group: string;
+        files: string[];
+        count: number;
+    }>;
+    /** Recipes matched to this module (by category/trigger/file path) */
+    recipes: Array<{
+        id: string;
+        title: string;
+        trigger: string;
+        kind: string;
+    }>;
+    /** Files not covered by any matched recipe */
+    uncoveredFileCount: number;
+    /** Auto-generated structural summary for the agent */
+    summary: string;
 }
 export interface PanoramaHealth {
     /** 多维度知识健康雷达 */
@@ -77,7 +94,7 @@ export declare class PanoramaService {
      */
     getOverview(): PanoramaOverview;
     /**
-     * 获取单模块详情
+     * 获取单模块详情 (enriched with file groups, recipes, and summary)
      */
     getModule(moduleName: string): PanoramaModuleDetail | null;
     /**

package/dist/lib/service/panorama/PanoramaService.js

@@ -96,7 +96,7 @@ export class PanoramaService {
         return overview;
     }
     /**
-     * 获取单模块详情
+     * 获取单模块详情 (enriched with file groups, recipes, and summary)
      */
     getModule(moduleName) {
         const result = this.#getOrCompute();
@@ -104,9 +104,16 @@ export class PanoramaService {
         if (!mod) {
             return null;
         }
-        // 找到该模块所在层级
-        const layerName = result.layers.levels.find((l) => l.modules.includes(moduleName))?.name ?? 'Unknown';
-        // 从 DB 查邻居边
+        // Layer name: derive from module's own refinedRole (more accurate than level vote)
+        const layerName = PanoramaService.#roleToLayer(mod.refinedRole || mod.inferredRole);
+        // File groups: group by immediate subdirectory within the module
+        const fileGroups = PanoramaService.#groupFilesBySubdir(mod.files);
+        // Matched recipes from DB
+        const recipes = this.#findModuleRecipes(moduleName, mod);
+        // Uncovered file count estimate
+        const coveredFileCount = Math.min(recipes.length * 2, mod.fileCount); // rough heuristic
+        const uncoveredFileCount = Math.max(0, mod.fileCount - coveredFileCount);
+        // Neighbors from DB edges
         const neighbors = [];
         const outNeighbors = this.#db
             .prepare(`SELECT DISTINCT to_id, weight FROM knowledge_edges
@@ -130,7 +137,143 @@ export class PanoramaService {
                 weight: Number(n.weight ?? 1),
             });
         }
-        return { module: mod, layerName, neighbors };
+        // Generate summary
+        const summary = PanoramaService.#generateModuleSummary(mod, layerName, fileGroups, recipes, neighbors);
+        return { module: mod, layerName, neighbors, fileGroups, recipes, uncoveredFileCount, summary };
+    }
+    /* ─── Module detail helpers ─────────────────────── */
+    /** Role → layer name mapping (consistent with PanoramaAggregator) */
+    static #roleToLayer(role) {
+        const map = {
+            core: 'Foundation',
+            foundation: 'Foundation',
+            model: 'Model',
+            service: 'Service',
+            networking: 'Infrastructure',
+            storage: 'Infrastructure',
+            ui: 'UI',
+            feature: 'Feature',
+            config: 'Configuration',
+            test: 'Test',
+            app: 'Application',
+        };
+        return map[role] ?? 'Feature';
+    }
+    /** Group file paths by their immediate subdirectory within the module */
+    static #groupFilesBySubdir(files) {
+        if (files.length === 0) {
+            return [];
+        }
+        // Find common prefix to determine module root
+        const prefix = PanoramaService.#commonPathPrefix(files);
+        const groups = new Map();
+        for (const f of files) {
+            const relative = f.slice(prefix.length);
+            const firstSlash = relative.indexOf('/');
+            const group = firstSlash > 0 ? relative.slice(0, firstSlash) : '(root)';
+            if (!groups.has(group)) {
+                groups.set(group, []);
+            }
+            groups.get(group).push(f);
+        }
+        return [...groups.entries()]
+            .sort((a, b) => b[1].length - a[1].length)
+            .map(([group, groupFiles]) => ({ group, files: groupFiles, count: groupFiles.length }));
+    }
+    static #commonPathPrefix(paths) {
+        if (paths.length === 0) {
+            return '';
+        }
+        let prefix = paths[0];
+        for (const p of paths) {
+            while (!p.startsWith(prefix)) {
+                const lastSlash = prefix.lastIndexOf('/');
+                if (lastSlash < 0) {
+                    return '';
+                }
+                prefix = prefix.slice(0, lastSlash + 1);
+            }
+        }
+        return prefix;
+    }
+    /** Find recipes related to this module by category, trigger, or title match */
+    #findModuleRecipes(moduleName, mod) {
+        try {
+            // Map refined role to typical recipe categories
+            const roleCategories = {
+                networking: ['Network', 'API', 'Http'],
+                storage: ['Storage', 'Database', 'Cache'],
+                ui: ['UI', 'View', 'Component'],
+                service: ['Service', 'Manager'],
+                model: ['Model', 'Entity'],
+                core: ['Core', 'Foundation', 'Utility'],
+                foundation: ['Core', 'Foundation', 'Utility'],
+                feature: ['Feature'],
+            };
+            const categories = roleCategories[mod.refinedRole] ?? [];
+            // Build a LIKE query that matches module name or related categories
+            const conditions = [];
+            const params = [];
+            // Match by module name in title or trigger
+            conditions.push('(title LIKE ? OR trigger LIKE ?)');
+            params.push(`%${moduleName}%`, `%${moduleName}%`);
+            // Match by category
+            for (const cat of categories) {
+                conditions.push('category = ?');
+                params.push(cat);
+            }
+            const whereClause = conditions.join(' OR ');
+            const rows = this.#db
+                .prepare(`SELECT id, title, trigger, kind FROM knowledge_entries
+           WHERE lifecycle IN ('active', 'staging', 'pending')
+             AND (${whereClause})
+           ORDER BY lifecycle ASC
+           LIMIT 20`)
+                .all(...params);
+            return rows.map((r) => ({
+                id: String(r.id ?? ''),
+                title: String(r.title ?? ''),
+                trigger: String(r.trigger ?? ''),
+                kind: String(r.kind ?? ''),
+            }));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Generate a structural summary for the agent */
+    static #generateModuleSummary(mod, layerName, fileGroups, recipes, neighbors) {
+        const lines = [];
+        // Identity
+        lines.push(`${mod.name} is a ${layerName} layer module (role: ${mod.refinedRole}, confidence: ${(mod.roleConfidence * 100).toFixed(0)}%).`);
+        // Structure
+        const groupDesc = fileGroups.map((g) => `${g.group}(${g.count})`).join(', ');
+        lines.push(`Contains ${mod.fileCount} files in ${fileGroups.length} groups: ${groupDesc}.`);
+        // Dependencies
+        const dependsOn = neighbors.filter((n) => n.direction === 'out').map((n) => n.name);
+        const usedBy = neighbors.filter((n) => n.direction === 'in').map((n) => n.name);
+        if (dependsOn.length > 0) {
+            lines.push(`Depends on: ${dependsOn.join(', ')}.`);
+        }
+        if (usedBy.length > 0) {
+            lines.push(`Used by: ${usedBy.join(', ')}.`);
+        }
+        if (dependsOn.length === 0 && usedBy.length === 0) {
+            lines.push('No dependency edges recorded (consider running a full bootstrap scan).');
+        }
+        // Knowledge coverage
+        lines.push(`Knowledge coverage: ${recipes.length} recipes matched, ${(mod.coverageRatio * 100).toFixed(0)}% estimated coverage.`);
+        if (recipes.length > 0) {
+            const recipeList = recipes
+                .slice(0, 5)
+                .map((r) => r.title)
+                .join('; ');
+            lines.push(`Key recipes: ${recipeList}.`);
+        }
+        if (mod.coverageRatio < 0.5) {
+            lines.push('Coverage is below 50% — consider submitting knowledge for uncovered file groups.');
+        }
+        return lines.join(' ');
     }
     /**
      * 获取知识空白区

package/dist/lib/service/search/BM25Scorer.d.ts

@@ -6,9 +6,9 @@
  *
  * @module BM25Scorer
  */
-import type { BM25Document, BM25SearchResult } from './SearchTypes.js';
+import type { BM25Document, BM25SearchResult, Scorer } from './SearchTypes.js';
 /** BM25 评分器 */
-export declare class BM25Scorer {
+export declare class BM25Scorer implements Scorer {
     _idIndex: Map<string, number>;
     _totalLength: number;
     avgLength: number;

package/dist/lib/service/search/CoarseRanker.d.ts

@@ -1,9 +1,10 @@
 /**
  * CoarseRanker — 粗排器
- * 基于 E-E-A-T 标准的 5 维加权排序（BM25 + Semantic + Quality + Freshness + Popularity）
+ * 多维加权排序（Recall + Semantic + Freshness + Popularity）
+ * Quality 维度保留但默认权重 0 — 待场景化区分后按需启用
  */
 interface RankerCandidate {
-    bm25Score?: number;
+    recallScore?: number;
     score?: number;
     semanticScore?: number;
     title?: string;
@@ -23,7 +24,7 @@ interface RankerCandidate {
 export declare class CoarseRanker {
     #private;
     constructor(options?: {
-        bm25Weight?: number;
+        recallWeight?: number;
         semanticWeight?: number;
         qualityWeight?: number;
         freshnessWeight?: number;
@@ -31,19 +32,19 @@ export declare class CoarseRanker {
     });
     /**
      * 粗排
-     * @param candidates 需有 bm25Score、semanticScore 等字段
+     * @param candidates 需有 recallScore、semanticScore 等字段
      * @returns sorted with coarseScore
      */
     rank(candidates: RankerCandidate[]): {
         coarseScore: number;
         coarseSignals: {
-            bm25: number;
+            recall: number;
             semantic: number;
             quality: number;
             freshness: number;
             popularity: number;
         };
-        bm25Score?: number;
+        recallScore?: number;
         score?: number;
         semanticScore?: number;
         title?: string;

package/dist/lib/service/search/CoarseRanker.js

@@ -1,21 +1,22 @@
 /**
  * CoarseRanker — 粗排器
- * 基于 E-E-A-T 标准的 5 维加权排序（BM25 + Semantic + Quality + Freshness + Popularity）
+ * 多维加权排序（Recall + Semantic + Freshness + Popularity）
+ * Quality 维度保留但默认权重 0 — 待场景化区分后按需启用
  */
 export class CoarseRanker {
     #weights;
     constructor(options = {}) {
         this.#weights = {
-            bm25: options.bm25Weight ?? 0.3,
+            recall: options.recallWeight ?? 0.45,
             semantic: options.semanticWeight ?? 0.3,
-            quality: options.qualityWeight ?? 0.2,
-            freshness: options.freshnessWeight ?? 0.1,
+            quality: options.qualityWeight ?? 0,
+            freshness: options.freshnessWeight ?? 0.15,
             popularity: options.popularityWeight ?? 0.1,
         };
     }
     /**
      * 粗排
-     * @param candidates 需有 bm25Score、semanticScore 等字段
+     * @param candidates 需有 recallScore、semanticScore 等字段
      * @returns sorted with coarseScore
      */
     rank(candidates) {
@@ -38,16 +39,16 @@ export class CoarseRanker {
             }
             effectiveWeights.semantic = 0;
         }
-        // BM25 分数 max-based 归一化（保留相对排序，避免 clamp 截断高分差异）
-        const maxBm25 = candidates.reduce((m, c) => Math.max(m, c.bm25Score || c.score || 0), 0) || 1;
+        // 召回分数 max-based 归一化（保留相对排序，避免 clamp 截断高分差异）
+        const maxRecall = candidates.reduce((m, c) => Math.max(m, c.recallScore || c.score || 0), 0) || 1;
         return candidates
             .map((c) => {
-            const bm25 = Math.min((c.bm25Score || c.score || 0) / maxBm25, 1.0);
+            const recall = Math.min((c.recallScore || c.score || 0) / maxRecall, 1.0);
             const semantic = this.#normalize(c.semanticScore || 0);
             const quality = this.#computeQuality(c);
             const freshness = this.#computeFreshness(c);
             const popularity = this.#computePopularity(c);
-            const coarseScore = bm25 * effectiveWeights.bm25 +
+            const coarseScore = recall * effectiveWeights.recall +
                 semantic * effectiveWeights.semantic +
                 quality * effectiveWeights.quality +
                 freshness * effectiveWeights.freshness +
@@ -55,7 +56,7 @@ export class CoarseRanker {
             return {
                 ...c,
                 coarseScore,
-                coarseSignals: { bm25, semantic, quality, freshness, popularity },
+                coarseSignals: { recall, semantic, quality, freshness, popularity },
             };
         })
             .sort((a, b) => b.coarseScore - a.coarseScore);

package/dist/lib/service/search/FieldWeightedScorer.d.ts

@@ -0,0 +1,81 @@
+/**
+ * FieldWeightedScorer — 加权字段匹配评分器
+ *
+ * 替代 BM25Scorer 作为结构化知识库的默认搜索评分引擎。
+ *
+ * 设计动机:
+ * - BM25 将所有字段拼接为文本做统计评分，tokenize 去重导致 TF 恒为 1，BM25F boost 失效
+ * - 对于 ~50–500 条结构化知识条目，BM25 的大规模语料假设不成立
+ * - FieldWeightedScorer 对每个字段独立打分并加权合并，精确匹配 > token 重叠 > IDF 加权
+ *
+ * 字段权重:
+ *   trigger (5.0) > title (3.0) > tags (2.0) > description (1.5) > content (1.0) > facets (0.5)
+ *
+ * @module FieldWeightedScorer
+ */
+import type { BM25SearchResult, Scorer } from './SearchTypes.js';
+/** 字段加权文档内部表示 */
+interface FieldWeightedDocument {
+    id: string;
+    fields: {
+        trigger: string;
+        title: string;
+        description: string;
+        tags: string[];
+        language: string;
+        category: string;
+        knowledgeType: string;
+    };
+    tokenizedFields: {
+        trigger: string[];
+        title: string[];
+        description: string[];
+        content: string[];
+        allUnique: Set<string>;
+    };
+    meta: Record<string, unknown>;
+}
+/**
+ * FieldWeightedScorer — 加权字段匹配评分器
+ *
+ * 接口与 BM25Scorer 完全兼容（实现 Scorer 接口），可作为 drop-in 替换。
+ */
+export declare class FieldWeightedScorer implements Scorer {
+    avgLength: number;
+    docFreq: Record<string, number>;
+    documents: (FieldWeightedDocument | null)[];
+    totalDocs: number;
+    _idIndex: Map<string, number>;
+    _totalLength: number;
+    constructor();
+    /** 添加文档到索引 */
+    addDocument(id: string, text: string, meta?: Record<string, unknown>): void;
+    /**
+     * 移除文档（tombstone + 懒压缩）
+     * @returns 是否成功移除
+     */
+    removeDocument(id: string): boolean;
+    /** 更新文档（remove + add） */
+    updateDocument(id: string, text: string, meta?: Record<string, unknown>): void;
+    /** 检查文档是否存在 */
+    hasDocument(id: string): boolean;
+    /** 清空索引 */
+    clear(): void;
+    /** 压缩 documents 数组，清除 tombstone 空洞 */
+    _compact(): void;
+    /** 搜索：对每个文档按字段加权评分，返回降序结果 */
+    search(query: string, limit?: number): BM25SearchResult[];
+    /** 字符串级别匹配评分（用于 trigger / title） */
+    _stringMatchScore(query: string, field: string): number;
+    /** Token 集合重叠率（查询侧召回） */
+    _tokenOverlap(queryTokens: string[], fieldTokens: string[]): number;
+    /** IDF 加权 token overlap（用于长文本字段） */
+    _idfWeightedOverlap(queryTokens: string[], fieldTokens: string[]): number;
+    /** Tag 匹配评分 */
+    _tagScore(queryTokens: string[], tags: string[]): number;
+    /** Facet 匹配评分（language / category / knowledgeType） */
+    _facetScore(queryTokens: string[], fields: FieldWeightedDocument['fields']): number;
+    /** 计算 IDF（平滑，始终为正） */
+    _idf(token: string): number;
+}
+export {};