autosnippet 3.3.2 → 3.3.3

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;
@@ -84,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);

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,7 +25,7 @@ export declare class SearchEngine {
     _cacheMaxAge: number;
     _coarseRanker: CoarseRanker;
     _crossEncoder: SearchCrossEncoder | null;
-    _fusionBm25Weight: number;
+    _fusionRecallWeight: number;
     _fusionSemanticWeight: number;
     _indexed: boolean;
     _lastIndexTime: string | null;
@@ -35,7 +35,7 @@ export declare class SearchEngine {
     db: SearchDb;
     hybridRetriever: SearchHybridRetriever | null;
     logger: ReturnType<typeof Logger.getInstance>;
-    scorer: BM25Scorer;
+    scorer: Scorer;
     vectorService: SearchVectorService | null;
     vectorStore: SearchVectorStore | null;
     constructor(db: SearchDb & {
@@ -76,7 +76,6 @@ export declare class SearchEngine {
         headers?: string;
         moduleName?: string;
         knowledgeType?: string;
-        bm25Score?: number;
         qualityScore?: number;
         usageCount?: number;
         authorityScore?: number;
@@ -151,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,24 +5,25 @@
  * 从 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;
@@ -42,15 +43,15 @@ 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;
     }
@@ -214,7 +215,8 @@ 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) {
@@ -254,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,
         }));
     }
     /**
@@ -286,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,
@@ -633,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 */
+        }
     }
     /**
      * 刷新索引（增量模式）
@@ -764,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',

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

@@ -20,6 +20,25 @@ export interface BM25SearchResult {
     score: number;
     meta: Record<string, unknown>;
 }
+/**
+ * Scorer 通用接口 — BM25Scorer 与 FieldWeightedScorer 共同实现
+ *
+ * SearchEngine 通过此接口与具体评分器解耦，可在运行时切换。
+ */
+export interface Scorer {
+    totalDocs: number;
+    avgLength: number;
+    docFreq: Record<string, number>;
+    documents: ({
+        id: string;
+    } | null)[];
+    addDocument(id: string, text: string, meta: Record<string, unknown>): void;
+    removeDocument(id: string): boolean;
+    updateDocument(id: string, text: string, meta: Record<string, unknown>): void;
+    hasDocument(id: string): boolean;
+    search(query: string, limit?: number): BM25SearchResult[];
+    clear(): void;
+}
 /** Meta structure produced by _buildDocMeta */
 export interface BM25DocMeta {
     type: string;
@@ -56,7 +75,6 @@ export interface SearchResultItem {
     headers?: string;
     moduleName?: string;
     knowledgeType?: string;
-    bm25Score?: number;
     qualityScore?: number;
     usageCount?: number;
     authorityScore?: number;
@@ -191,7 +209,7 @@ export interface SearchEngineOptions {
     crossEncoderReranker?: SearchCrossEncoder | null;
     signalBus?: SignalBus | null;
     cacheMaxAge?: number;
-    fusionBm25Weight?: number;
+    fusionRecallWeight?: number;
     fusionSemanticWeight?: number;
     [key: string]: unknown;
 }
@@ -210,12 +228,14 @@ export interface SlimSearchResult {
     actionHint?: string;
     /** 知识类型 (code-standard/code-pattern/...) — Bridge 场景需要 */
     knowledgeType?: string;
+    /** 已验证的项目来源文件路径（可信度证据链） */
+    sourceRefs?: string[];
 }
 /**
  * 统一投影函数 — 将 SearchResultItem 投影为 SlimSearchResult。
  *
  * 合并了 mcp/search.ts#_slimSearchItem() 和 TaskKnowledgeBridge#_projectItem() 的逻辑：
- * - 去除内部信号 (bm25Score, coarseScore, rankerScore, contextScore, content, code...)
+ * - 去除内部信号 (recallScore, coarseScore, rankerScore, contextScore, content, code...)
  * - description 截断 120 字符
  * - 生成 actionHint (whenClause → doClause)
  *

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

@@ -10,7 +10,7 @@
  * 统一投影函数 — 将 SearchResultItem 投影为 SlimSearchResult。
  *
  * 合并了 mcp/search.ts#_slimSearchItem() 和 TaskKnowledgeBridge#_projectItem() 的逻辑：
- * - 去除内部信号 (bm25Score, coarseScore, rankerScore, contextScore, content, code...)
+ * - 去除内部信号 (recallScore, coarseScore, rankerScore, contextScore, content, code...)
  * - description 截断 120 字符
  * - 生成 actionHint (whenClause → doClause)
  *
@@ -23,6 +23,10 @@ export function slimSearchResult(item) {
     const actionHint = doText || whenText
         ? `${whenText ? `${whenText} → ` : ''}${doText}`.replace(/ → $/, '')
         : undefined;
+    const rawRefs = item.sourceRefs;
+    const sourceRefs = Array.isArray(rawRefs) && rawRefs.length > 0
+        ? rawRefs.filter((s) => typeof s === 'string' && s.length > 0)
+        : undefined;
     return {
         id: item.id,
         title: item.title || '',
@@ -33,6 +37,7 @@ export function slimSearchResult(item) {
         description: (item.description || '').slice(0, 120),
         actionHint,
         knowledgeType: item.knowledgeType || undefined,
+        sourceRefs,
     };
 }
 /** items → byKind 分组（统一实现） */

package/dist/lib/service/task/IntentExtractor.d.ts

@@ -10,6 +10,8 @@ export type SearchScenario = 'lint' | 'generate' | 'search' | 'learning';
 export interface ExtractedIntent {
     /** Multi-query set: Q1 raw + Q2 tech terms + Q3 file context */
     queries: string[];
+    /** Cross-language synonym queries (run in keyword mode to bypass semantic normalization) */
+    keywordQueries: string[];
     /** Inferred language from activeFile or args */
     language: string | null;
     /** Inferred module path from activeFile */
@@ -37,8 +39,14 @@ export declare function extract(userQuery: string, activeFile?: string, language
 /**
  * Build multi-query set from user query + active file.
  * Q1: raw query, Q2: extracted tech terms, Q3: file context.
+ * Q1 is enriched with cross-language synonyms to bridge EN↔CJK matching.
  */
 export declare function buildQueries(userQuery: string, activeFile?: string, termOpts?: TechTermOptions): string[];
+/**
+ * Build keyword-mode queries for cross-language synonym matching.
+ * Uses keyword mode to preserve raw FWS scores without CoarseRanker semantic normalization.
+ */
+export declare function buildKeywordQueries(userQuery: string): string[];
 /**
  * Extract tech terms from query using universal patterns + dynamic project prefixes.
  */