autosnippet 3.3.0 → 3.3.3

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

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

@@ -0,0 +1,318 @@
+/**
+ * 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 { tokenize } from './tokenizer.js';
+// ── 字段权重常量（可调） ──
+const TRIGGER_WEIGHT = 5.0;
+const TITLE_WEIGHT = 3.0;
+const TAG_WEIGHT = 2.0;
+const DESCRIPTION_WEIGHT = 1.5;
+const CONTENT_WEIGHT = 1.0;
+const FACET_WEIGHT = 0.5;
+/**
+ * FieldWeightedScorer — 加权字段匹配评分器
+ *
+ * 接口与 BM25Scorer 完全兼容（实现 Scorer 接口），可作为 drop-in 替换。
+ */
+export class FieldWeightedScorer {
+    avgLength;
+    docFreq;
+    documents;
+    totalDocs;
+    _idIndex;
+    _totalLength;
+    constructor() {
+        this.documents = [];
+        this.totalDocs = 0;
+        this.docFreq = {};
+        this._idIndex = new Map();
+        this._totalLength = 0;
+        this.avgLength = 0;
+    }
+    /** 添加文档到索引 */
+    addDocument(id, text, meta = {}) {
+        if (this._idIndex.has(id)) {
+            this.removeDocument(id);
+        }
+        // 从 meta 提取结构化字段
+        const trigger = meta.trigger || '';
+        const title = meta.title || '';
+        const description = meta.description || '';
+        const tags = Array.isArray(meta.tags) ? meta.tags : [];
+        const language = meta.language || '';
+        const category = meta.category || '';
+        const knowledgeType = meta.knowledgeType || '';
+        const contentText = meta.contentText || '';
+        // 独立分词每个字段
+        const triggerTokens = tokenize(trigger);
+        const titleTokens = tokenize(title);
+        const descTokens = tokenize(description);
+        // contentText 优先；若 meta 无 contentText 则用拼接文本 text 作为回退
+        const contentTokens = tokenize(contentText || text);
+        // 合并所有唯一 token 用于 DF 计算
+        const allUnique = new Set();
+        for (const t of triggerTokens) {
+            allUnique.add(t);
+        }
+        for (const t of titleTokens) {
+            allUnique.add(t);
+        }
+        for (const t of descTokens) {
+            allUnique.add(t);
+        }
+        for (const t of contentTokens) {
+            allUnique.add(t);
+        }
+        for (const tag of tags) {
+            for (const t of tokenize(tag)) {
+                allUnique.add(t);
+            }
+        }
+        const doc = {
+            id,
+            fields: { trigger, title, description, tags, language, category, knowledgeType },
+            tokenizedFields: {
+                trigger: triggerTokens,
+                title: titleTokens,
+                description: descTokens,
+                content: contentTokens,
+                allUnique,
+            },
+            meta,
+        };
+        const idx = this.documents.length;
+        this.documents.push(doc);
+        this._idIndex.set(id, idx);
+        for (const token of allUnique) {
+            this.docFreq[token] = (this.docFreq[token] || 0) + 1;
+        }
+        this.totalDocs = this._idIndex.size;
+        this._totalLength += allUnique.size;
+        this.avgLength = this.totalDocs > 0 ? this._totalLength / this.totalDocs : 0;
+    }
+    /**
+     * 移除文档（tombstone + 懒压缩）
+     * @returns 是否成功移除
+     */
+    removeDocument(id) {
+        const idx = this._idIndex.get(id);
+        if (idx === undefined) {
+            return false;
+        }
+        const doc = this.documents[idx];
+        if (!doc) {
+            return false;
+        }
+        for (const token of doc.tokenizedFields.allUnique) {
+            if (this.docFreq[token]) {
+                this.docFreq[token]--;
+                if (this.docFreq[token] <= 0) {
+                    delete this.docFreq[token];
+                }
+            }
+        }
+        this._totalLength -= doc.tokenizedFields.allUnique.size;
+        this.documents[idx] = null;
+        this._idIndex.delete(id);
+        this.totalDocs = this._idIndex.size;
+        this.avgLength = this.totalDocs > 0 ? this._totalLength / this.totalDocs : 0;
+        const nullCount = this.documents.length - this.totalDocs;
+        if (this.documents.length > 100 && nullCount / this.documents.length > 0.3) {
+            this._compact();
+        }
+        return true;
+    }
+    /** 更新文档（remove + add） */
+    updateDocument(id, text, meta = {}) {
+        this.removeDocument(id);
+        this.addDocument(id, text, meta);
+    }
+    /** 检查文档是否存在 */
+    hasDocument(id) {
+        return this._idIndex.has(id);
+    }
+    /** 清空索引 */
+    clear() {
+        this.documents = [];
+        this.docFreq = {};
+        this.totalDocs = 0;
+        this._totalLength = 0;
+        this.avgLength = 0;
+        this._idIndex.clear();
+    }
+    /** 压缩 documents 数组，清除 tombstone 空洞 */
+    _compact() {
+        const alive = this.documents.filter((d) => d !== null);
+        this.documents = alive;
+        this._idIndex.clear();
+        for (let i = 0; i < alive.length; i++) {
+            this._idIndex.set(alive[i].id, i);
+        }
+    }
+    /** 搜索：对每个文档按字段加权评分，返回降序结果 */
+    search(query, limit = 20) {
+        const queryTokens = tokenize(query);
+        if (queryTokens.length === 0) {
+            return [];
+        }
+        const scores = [];
+        for (const doc of this.documents) {
+            if (!doc) {
+                continue;
+            }
+            let totalScore = 0;
+            // 1. Trigger 评分 — 最高权重，精确标识
+            const triggerString = this._stringMatchScore(query, doc.fields.trigger);
+            const triggerToken = this._tokenOverlap(queryTokens, doc.tokenizedFields.trigger);
+            totalScore += TRIGGER_WEIGHT * Math.max(triggerString, triggerToken);
+            // 2. Title 评分 — 主要描述性字段
+            const titleString = this._stringMatchScore(query, doc.fields.title);
+            const titleToken = this._tokenOverlap(queryTokens, doc.tokenizedFields.title);
+            totalScore += TITLE_WEIGHT * Math.max(titleString, titleToken);
+            // 3. Tags 评分 — 分类标记
+            totalScore += TAG_WEIGHT * this._tagScore(queryTokens, doc.fields.tags);
+            // 4. Description 评分 — IDF 加权 token overlap
+            totalScore +=
+                DESCRIPTION_WEIGHT * this._idfWeightedOverlap(queryTokens, doc.tokenizedFields.description);
+            // 5. Content 评分 — IDF 加权 token overlap
+            totalScore +=
+                CONTENT_WEIGHT * this._idfWeightedOverlap(queryTokens, doc.tokenizedFields.content);
+            // 6. Facet 评分 — language/category/knowledgeType 精确匹配
+            totalScore += FACET_WEIGHT * this._facetScore(queryTokens, doc.fields);
+            if (totalScore > 0) {
+                scores.push({ id: doc.id, score: totalScore, meta: doc.meta });
+            }
+        }
+        scores.sort((a, b) => b.score - a.score);
+        return scores.slice(0, limit);
+    }
+    // ── 内部评分方法 ──
+    /** 字符串级别匹配评分（用于 trigger / title） */
+    _stringMatchScore(query, field) {
+        if (!field) {
+            return 0;
+        }
+        const q = query.toLowerCase();
+        const f = field.toLowerCase();
+        if (f === q) {
+            return 1.0;
+        }
+        if (f.startsWith(q)) {
+            return 0.7;
+        }
+        if (f.includes(q)) {
+            return 0.5;
+        }
+        if (q.includes(f) && f.length > 3) {
+            return 0.3;
+        }
+        return 0;
+    }
+    /** Token 集合重叠率（查询侧召回） */
+    _tokenOverlap(queryTokens, fieldTokens) {
+        if (queryTokens.length === 0) {
+            return 0;
+        }
+        const fieldSet = new Set(fieldTokens);
+        let matched = 0;
+        for (const qt of queryTokens) {
+            if (fieldSet.has(qt)) {
+                matched++;
+            }
+        }
+        return matched / queryTokens.length;
+    }
+    /** IDF 加权 token overlap（用于长文本字段） */
+    _idfWeightedOverlap(queryTokens, fieldTokens) {
+        if (queryTokens.length === 0) {
+            return 0;
+        }
+        const fieldSet = new Set(fieldTokens);
+        let matchedIdf = 0;
+        let totalIdf = 0;
+        for (const qt of queryTokens) {
+            const idf = this._idf(qt);
+            totalIdf += idf;
+            if (fieldSet.has(qt)) {
+                matchedIdf += idf;
+            }
+        }
+        return totalIdf > 0 ? matchedIdf / totalIdf : 0;
+    }
+    /** Tag 匹配评分 */
+    _tagScore(queryTokens, tags) {
+        if (tags.length === 0 || queryTokens.length === 0) {
+            return 0;
+        }
+        let score = 0;
+        const qtSet = new Set(queryTokens);
+        for (const tag of tags) {
+            const lowTag = tag.toLowerCase();
+            // 精确 token 匹配
+            if (qtSet.has(lowTag)) {
+                score += 1.0;
+                continue;
+            }
+            // 部分匹配：query token 包含 tag 或 tag 包含 query token
+            let partialFound = false;
+            for (const qt of queryTokens) {
+                if (lowTag.includes(qt) || qt.includes(lowTag)) {
+                    score += 0.5;
+                    partialFound = true;
+                    break;
+                }
+            }
+            if (!partialFound) {
+                // 对 tag 分词再匹配
+                const tagTokens = tokenize(tag);
+                for (const tt of tagTokens) {
+                    if (qtSet.has(tt)) {
+                        score += 0.3;
+                        break;
+                    }
+                }
+            }
+        }
+        return Math.min(score / queryTokens.length, 1.0);
+    }
+    /** Facet 匹配评分（language / category / knowledgeType） */
+    _facetScore(queryTokens, fields) {
+        const facets = [fields.language, fields.category, fields.knowledgeType].filter(Boolean);
+        if (facets.length === 0) {
+            return 0;
+        }
+        let matched = 0;
+        const qtSet = new Set(queryTokens);
+        for (const facet of facets) {
+            const lower = facet.toLowerCase();
+            if (qtSet.has(lower)) {
+                matched++;
+                continue;
+            }
+            for (const ft of tokenize(facet)) {
+                if (qtSet.has(ft)) {
+                    matched++;
+                    break;
+                }
+            }
+        }
+        return matched / facets.length;
+    }
+    /** 计算 IDF（平滑，始终为正） */
+    _idf(token) {
+        const df = this.docFreq[token] || 0;
+        return Math.log2(1 + this.totalDocs / (df + 1));
+    }
+}

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

@@ -4,7 +4,7 @@
  * 不同场景使用不同权重配置（向后兼容旧配置中的 'seasonality' 键）
  */
 interface SignalCandidate {
-    bm25Score?: number;
+    recallScore?: number;
     score?: number;
     title?: string;
     trigger?: string;
@@ -74,6 +74,7 @@ export declare class MultiSignalRanker {
     #private;
     constructor(options?: {
         scenarioWeights?: Record<string, Record<string, number>>;
+        signalBus?: import('../../infrastructure/signal/SignalBus.js').SignalBus;
     });
     /**
      * 对候选列表进行多信号加权排序
@@ -83,7 +84,7 @@ export declare class MultiSignalRanker {
     rank(candidates: SignalCandidate[], context?: SignalContext): {
         rankerScore: number;
         signals: Record<string, number>;
-        bm25Score?: number;
+        recallScore?: number;
         score?: number;
         title?: string;
         trigger?: string;

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

@@ -54,7 +54,7 @@ const SCENARIO_WEIGHTS = {
 /** 相关性信号 — BM25 + 标题匹配 + 内容匹配 */
 export class RelevanceSignal {
     compute(candidate, context) {
-        let score = candidate.bm25Score || candidate.score || 0;
+        let score = candidate.recallScore || candidate.score || 0;
         const query = (context.query || '').toLowerCase();
         if (!query) {
             return Math.min(score, 1.0);
@@ -209,6 +209,8 @@ export class VectorSignal {
 export class MultiSignalRanker {
     #signals;
     #scenarioWeights;
+    #realtimeWeights = new Map();
+    #recentlyUsed = new Set();
     constructor(options = {}) {
         this.#signals = {
             relevance: new RelevanceSignal(),
@@ -230,6 +232,20 @@ export class MultiSignalRanker {
             }
         }
         this.#scenarioWeights = { ...SCENARIO_WEIGHTS, ...remapped };
+        // Phase 2: 订阅实时信号更新权重
+        if (options.signalBus) {
+            options.signalBus.subscribe('quality|usage', (signal) => {
+                this.#onSignal(signal);
+            });
+        }
+    }
+    #onSignal(signal) {
+        if (signal.type === 'quality' && signal.target) {
+            this.#realtimeWeights.set(signal.target, signal.value);
+        }
+        if (signal.type === 'usage' && signal.target) {
+            this.#recentlyUsed.add(signal.target);
+        }
     }
     /**
      * 对候选列表进行多信号加权排序

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

@@ -5,17 +5,17 @@
  * 从 V1 SearchServiceV2 迁移，适配 V2 架构
  */
 import Logger from '../../infrastructure/logging/Logger.js';
-import { BM25Scorer } from './BM25Scorer.js';
 import { CoarseRanker } from './CoarseRanker.js';
 import { MultiSignalRanker } from './MultiSignalRanker.js';
-import type { DbRow, RankingContext, SearchAiProvider, SearchCrossEncoder, SearchDb, SearchEngineOptions, SearchHybridRetriever, SearchOptions, SearchResponse, SearchResultItem, SearchVectorService, SearchVectorStore } from './SearchTypes.js';
+import type { DbRow, RankingContext, Scorer, SearchAiProvider, SearchCrossEncoder, SearchDb, SearchEngineOptions, SearchHybridRetriever, SearchOptions, SearchResponse, SearchResultItem, SearchVectorService, SearchVectorStore } from './SearchTypes.js';
 export { BM25Scorer } from './BM25Scorer.js';
-export type { BM25DocMeta, BM25SearchResult, DbRow, RankingContext, RrfHit, SearchAiProvider, SearchCrossEncoder, SearchDb, SearchEngineOptions, SearchHybridRetriever, SearchOptions, SearchResponse, SearchResultItem, SearchVectorService, SearchVectorStore, SlimSearchResult, VectorHit, } from './SearchTypes.js';
+export { FieldWeightedScorer } from './FieldWeightedScorer.js';
+export type { BM25DocMeta, BM25SearchResult, DbRow, RankingContext, RrfHit, Scorer, SearchAiProvider, SearchCrossEncoder, SearchDb, SearchEngineOptions, SearchHybridRetriever, SearchOptions, SearchResponse, SearchResultItem, SearchVectorService, SearchVectorStore, SlimSearchResult, VectorHit, } from './SearchTypes.js';
 export { groupByKind, slimSearchResult } from './SearchTypes.js';
 export { tokenize } from './tokenizer.js';
 /**
  * SearchEngine - 完整搜索服务
- * 整合 BM25 + 关键词 + 可选 AI 增强
+ * 整合召回评分 + 关键词 + 可选 AI 增强
  */
 export declare class SearchEngine {
     _cache: Map<string, {
@@ -25,16 +25,17 @@ export declare class SearchEngine {
     _cacheMaxAge: number;
     _coarseRanker: CoarseRanker;
     _crossEncoder: SearchCrossEncoder | null;
-    _fusionBm25Weight: number;
+    _fusionRecallWeight: number;
     _fusionSemanticWeight: number;
     _indexed: boolean;
     _lastIndexTime: string | null;
     _multiSignalRanker: MultiSignalRanker;
+    _signalBus: import('../../infrastructure/signal/SignalBus.js').SignalBus | null;
     aiProvider: SearchAiProvider | null;
     db: SearchDb;
     hybridRetriever: SearchHybridRetriever | null;
     logger: ReturnType<typeof Logger.getInstance>;
-    scorer: BM25Scorer;
+    scorer: Scorer;
     vectorService: SearchVectorService | null;
     vectorStore: SearchVectorStore | null;
     constructor(db: SearchDb & {
@@ -75,7 +76,6 @@ export declare class SearchEngine {
         headers?: string;
         moduleName?: string;
         knowledgeType?: string;
-        bm25Score?: number;
         qualityScore?: number;
         usageCount?: number;
         authorityScore?: number;
@@ -150,6 +150,8 @@ export declare class SearchEngine {
         type: string;
         title: string | undefined;
         trigger: string;
+        description: string;
+        contentText: string;
         status: string | undefined;
         knowledgeType: string | undefined;
         kind: string;

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

@@ -5,28 +5,30 @@
  * 从 V1 SearchServiceV2 迁移，适配 V2 架构
  */
 import Logger from '../../infrastructure/logging/Logger.js';
-import { BM25Scorer } from './BM25Scorer.js';
 import { CoarseRanker } from './CoarseRanker.js';
 import { contextBoost } from './contextBoost.js';
+import { FieldWeightedScorer } from './FieldWeightedScorer.js';
 import { MultiSignalRanker } from './MultiSignalRanker.js';
 // ── Re-exports for backward compatibility ──
 export { BM25Scorer } from './BM25Scorer.js';
+export { FieldWeightedScorer } from './FieldWeightedScorer.js';
 export { groupByKind, slimSearchResult } from './SearchTypes.js';
 export { tokenize } from './tokenizer.js';
 /**
  * SearchEngine - 完整搜索服务
- * 整合 BM25 + 关键词 + 可选 AI 增强
+ * 整合召回评分 + 关键词 + 可选 AI 增强
  */
 export class SearchEngine {
     _cache;
     _cacheMaxAge;
     _coarseRanker;
     _crossEncoder;
-    _fusionBm25Weight;
+    _fusionRecallWeight;
     _fusionSemanticWeight;
     _indexed;
     _lastIndexTime = null;
     _multiSignalRanker;
+    _signalBus;
     aiProvider;
     db;
     hybridRetriever;
@@ -41,16 +43,17 @@ export class SearchEngine {
         this.vectorStore = options.vectorStore || null;
         this.vectorService = options.vectorService || null;
         this.hybridRetriever = options.hybridRetriever || null;
-        this.scorer = new BM25Scorer();
+        this.scorer = new FieldWeightedScorer();
         this._coarseRanker = new CoarseRanker(options);
         this._multiSignalRanker = new MultiSignalRanker(options);
         this._crossEncoder = options.crossEncoderReranker || null;
         this._indexed = false;
         this._cache = new Map();
         this._cacheMaxAge = options.cacheMaxAge || 300_000; // 5min
-        // auto 模式 BM25+semantic 融合权重（可配置）
-        this._fusionBm25Weight = options.fusionBm25Weight ?? 0.6;
+        // auto 模式 召回+semantic 融合权重（可配置）
+        this._fusionRecallWeight = options.fusionRecallWeight ?? 0.6;
         this._fusionSemanticWeight = options.fusionSemanticWeight ?? 0.4;
+        this._signalBus = options.signalBus || null;
     }
     /** 构建搜索索引 - 从数据库加载所有可搜索实体 */
     buildIndex() {
@@ -212,12 +215,19 @@ export class SearchEngine {
             response.byKind = { rule: [], pattern: [], fact: [] };
             for (const r of results) {
                 const kind = r.kind || 'pattern';
-                (response.byKind[kind] || response.byKind.pattern).push(r);
+                const bucket = response.byKind[kind] ?? response.byKind.pattern;
+                bucket.push(r);
             }
         }
         if (cacheKey) {
             this._setCache(cacheKey, response);
         }
+        // ── Signal emission ──
+        if (this._signalBus && response.total > 0) {
+            this._signalBus.send('search', 'SearchEngine', Math.min(response.total / limit, 1), {
+                metadata: { query, mode: actualMode, total: response.total },
+            });
+        }
         return response;
     }
     // ── Ranking Pipeline ────────────────────────────────────────────
@@ -246,8 +256,8 @@ export class SearchEngine {
         }
         return ranked.map((r) => ({
             ...r,
-            recallScore: r.bm25Score || 0,
-            score: r.contextScore || r.rankerScore || r.coarseScore || r.bm25Score || 0,
+            recallScore: r.recallScore || 0,
+            score: r.contextScore || r.rankerScore || r.coarseScore || r.recallScore || 0,
         }));
     }
     /**
@@ -278,7 +288,7 @@ export class SearchEngine {
             return {
                 ...item,
                 code: codeText || item.code || '',
-                bm25Score: item.score || 0,
+                recallScore: item.score || 0,
                 qualityScore: item.qualityScore || (item.status === 'active' ? 70 : 40),
                 usageCount: item.usageCount || 0,
                 authorityScore: item.authorityScore || 0,
@@ -625,6 +635,40 @@ export class SearchEngine {
         catch {
             /* DB may not be available */
         }
+        // ── 从 recipe_source_refs 桥接表批量读取已验证的 sourceRefs ──
+        try {
+            const ids = items.map((it) => it.id);
+            if (ids.length === 0) {
+                return;
+            }
+            const placeholders = ids.map(() => '?').join(',');
+            const refsRows = this.db
+                .prepare(`SELECT recipe_id, source_path, status, new_path
+           FROM recipe_source_refs
+           WHERE recipe_id IN (${placeholders}) AND status != 'stale'`)
+                .all(...ids);
+            this.logger.debug('recipe_source_refs query', {
+                idCount: ids.length,
+                rowCount: refsRows.length,
+            });
+            const refsMap = new Map();
+            for (const row of refsRows) {
+                const refPath = row.status === 'renamed' && row.new_path ? row.new_path : row.source_path;
+                if (!refsMap.has(row.recipe_id)) {
+                    refsMap.set(row.recipe_id, []);
+                }
+                refsMap.get(row.recipe_id)?.push(refPath);
+            }
+            for (const item of items) {
+                const refs = refsMap.get(item.id);
+                if (refs && refs.length > 0) {
+                    item.sourceRefs = refs;
+                }
+            }
+        }
+        catch {
+            /* recipe_source_refs table may not exist */
+        }
     }
     /**
      * 刷新索引（增量模式）
@@ -756,10 +800,23 @@ export class SearchEngine {
         catch {
             /* ignore */
         }
+        // 提取 description 和 contentText 供 FieldWeightedScorer 字段级评分使用
+        let contentText = '';
+        try {
+            const content = JSON.parse(r.content || '{}');
+            contentText = [content.pattern, content.rationale, content.markdown]
+                .filter(Boolean)
+                .join(' ');
+        }
+        catch {
+            /* ignore */
+        }
         return {
             type: 'knowledge',
             title: r.title,
             trigger: r.trigger || '',
+            description: r.description || '',
+            contentText,
             status: r.lifecycle,
             knowledgeType: r.knowledgeType,
             kind: r.kind || 'pattern',