autosnippet 3.3.5 → 3.3.6

package/dist/lib/service/knowledge/RecipeProductionGateway.js

@@ -0,0 +1,384 @@
+/**
+ * RecipeProductionGateway — 统一 Recipe 生产入口
+ *
+ * 所有 Recipe 创建（Agent Tool / MCP / IDE Agent / Batch Import）
+ * 通过此 Gateway 的统一管道，保证前置校验一致：
+ *
+ *   1. Schema Validation (UnifiedValidator)
+ *   2. Similarity Check — 去重检测（可选跳过）
+ *   3. Consolidation Scan — 融合/重组建议（可选）
+ *   4. KnowledgeService.create() — 包含 ConfidenceRouter → staging / pending
+ *   5. Quality Scoring — 质量评分
+ *   6. Supersede Proposal — 创建替代提案
+ *   7. Audit — 统一审计
+ *
+ * @see docs/copilot/recipe-lifecycle-management.md §6
+ */
+import { UnifiedValidator } from '#domain/knowledge/UnifiedValidator.js';
+/* ═══════════════════ Gateway ═══════════════════ */
+export class RecipeProductionGateway {
+    #knowledgeService;
+    #projectRoot;
+    #logger;
+    #consolidationAdvisor;
+    #proposalRepo;
+    #findSimilarRecipes;
+    constructor(deps) {
+        this.#knowledgeService = deps.knowledgeService;
+        this.#projectRoot = deps.projectRoot;
+        this.#logger = deps.logger;
+        this.#consolidationAdvisor = deps.consolidationAdvisor ?? null;
+        this.#proposalRepo = deps.proposalRepository ?? null;
+        this.#findSimilarRecipes = deps.findSimilarRecipes ?? null;
+    }
+    /**
+     * 统一创建入口
+     *
+     * Pipeline:
+     *   1. Schema Validation (UnifiedValidator)
+     *   2. Similarity Check (除非 skipSimilarityCheck)
+     *   3. Consolidation Scan (除非 skipConsolidation)
+     *   4. KnowledgeService.create() — ConfidenceRouter → staging / pending
+     *   5. Quality Scoring
+     *   6. Supersede Proposal 创建 (if supersedes)
+     */
+    async create(request) {
+        const { source, items, options = {} } = request;
+        const userId = options.userId || this.#sourceToUserId(source);
+        const result = {
+            created: [],
+            rejected: [],
+            merged: [],
+            blocked: [],
+            duplicates: [],
+            supersedeProposal: null,
+        };
+        if (items.length === 0) {
+            return result;
+        }
+        // ── Step 1: Schema Validation ──
+        const validator = new UnifiedValidator({
+            existingTitles: options.existingTitles,
+            existingFingerprints: options.existingFingerprints,
+        });
+        const validItems = [];
+        for (let i = 0; i < items.length; i++) {
+            const item = items[i];
+            const validation = validator.validate(item, {
+                systemInjectedFields: options.systemInjectedFields,
+                skipUniqueness: options.skipUniqueness,
+            });
+            if (!validation.pass) {
+                result.rejected.push({
+                    index: i,
+                    title: item.title || '(untitled)',
+                    reason: 'validation_failed',
+                    errors: validation.errors,
+                    warnings: validation.warnings,
+                });
+                this.#logger?.info(`[Gateway] ✗ validation rejected item ${i}: ${validation.errors.join('; ')}`);
+            }
+            else {
+                validItems.push({ index: i, item });
+                // 记录已提交标题/指纹以防批量内重复
+                validator.recordSubmission(item.title, item.content?.pattern);
+            }
+        }
+        // ── Step 2: Similarity Check ──
+        let afterSimilarityItems = validItems;
+        if (!options.skipSimilarityCheck && this.#findSimilarRecipes) {
+            const threshold = options.similarityThreshold ?? 0.7;
+            afterSimilarityItems = [];
+            for (const entry of validItems) {
+                const { item, index } = entry;
+                const contentObj = item.content && typeof item.content === 'object' ? item.content : { markdown: '' };
+                const cand = {
+                    title: item.title || '',
+                    summary: item.description || '',
+                    code: contentObj.markdown || contentObj.pattern || '',
+                };
+                const similar = this.#findSimilarRecipes(this.#projectRoot, cand, {
+                    threshold: 0.5,
+                    topK: 5,
+                });
+                const hasDuplicate = similar.some((s) => s.similarity >= threshold);
+                if (hasDuplicate) {
+                    result.duplicates.push({
+                        index,
+                        title: item.title || '(untitled)',
+                        similarTo: similar,
+                    });
+                    this.#logger?.info(`[Gateway] ✗ duplicate blocked item ${index}: similarity ${similar[0]?.similarity}`);
+                }
+                else {
+                    afterSimilarityItems.push(entry);
+                }
+            }
+        }
+        // ── Step 3: Consolidation Scan ──
+        let submittableItems = afterSimilarityItems;
+        if (!options.skipConsolidation &&
+            this.#consolidationAdvisor &&
+            afterSimilarityItems.length > 0) {
+            submittableItems = [];
+            try {
+                const candidates = afterSimilarityItems.map((e) => ({
+                    title: e.item.title || '',
+                    category: e.item.category || e.item._category || '',
+                    ...e.item,
+                }));
+                const batchAdvice = this.#consolidationAdvisor.analyzeBatch(candidates);
+                for (let ai = 0; ai < batchAdvice.items.length; ai++) {
+                    const { advice } = batchAdvice.items[ai];
+                    const validEntry = afterSimilarityItems[ai];
+                    if (!validEntry) {
+                        continue;
+                    }
+                    if (advice.action === 'create') {
+                        submittableItems.push(validEntry);
+                    }
+                    else if (this.#proposalRepo) {
+                        const proposal = this.#createProposalFromAdvice(advice, validEntry.item);
+                        if (proposal) {
+                            result.merged.push({
+                                index: validEntry.index,
+                                proposalId: proposal.proposalId,
+                                type: proposal.type,
+                                targetRecipeId: proposal.targetRecipeId,
+                                targetTitle: proposal.targetTitle,
+                                status: proposal.status,
+                                expiresAt: proposal.expiresAt,
+                                message: proposal.message,
+                            });
+                        }
+                        else {
+                            // Proposal 创建失败 → blocked
+                            result.blocked.push({
+                                index: validEntry.index,
+                                title: validEntry.item.title || '(untitled)',
+                                consolidation: advice,
+                            });
+                        }
+                    }
+                    else {
+                        // 无 ProposalRepository → blocked
+                        result.blocked.push({
+                            index: validEntry.index,
+                            title: validEntry.item.title || '(untitled)',
+                            consolidation: advice,
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                this.#logger?.warn(`[Gateway] ConsolidationAdvisor error, falling back to direct submit: ${err instanceof Error ? err.message : String(err)}`);
+                submittableItems = afterSimilarityItems;
+            }
+        }
+        // ── Step 4: Create via KnowledgeService ──
+        const createdIds = [];
+        for (const { item } of submittableItems) {
+            try {
+                const data = this.#prepareCreateData(item, source, userId);
+                const saved = await this.#knowledgeService.create(data, { userId });
+                result.created.push({
+                    id: saved.id,
+                    title: saved.title,
+                    lifecycle: saved.lifecycle,
+                    raw: saved,
+                });
+                createdIds.push(saved.id);
+                // ── Step 5: Quality Scoring (best effort) ──
+                try {
+                    await this.#knowledgeService.updateQuality(saved.id, { userId });
+                }
+                catch {
+                    /* best effort — 不阻塞创建流程 */
+                }
+            }
+            catch (err) {
+                result.rejected.push({
+                    index: items.indexOf(item),
+                    title: item.title || '(untitled)',
+                    reason: 'create_failed',
+                    errors: [err instanceof Error ? err.message : String(err)],
+                    warnings: [],
+                });
+                this.#logger?.warn(`[Gateway] ✗ create failed for "${item.title}": ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // ── Step 6: Supersede Proposal ──
+        if (options.supersedes && createdIds.length > 0) {
+            try {
+                // 直接使用 ProposalRepository（Gateway 不依赖 ServiceContainer）
+                if (this.#proposalRepo) {
+                    const proposal = this.#proposalRepo.create({
+                        type: 'supersede',
+                        targetRecipeId: options.supersedes,
+                        relatedRecipeIds: createdIds,
+                        confidence: 0.9,
+                        source: source === 'mcp-external' ? 'ide-agent' : 'ide-agent',
+                        description: `Supersede proposal: ${createdIds.length} new recipe(s) replace ${options.supersedes}`,
+                        evidence: [{ snapshotAt: Date.now(), newRecipeIds: createdIds }],
+                    });
+                    if (proposal) {
+                        result.supersedeProposal = { proposalId: proposal.id };
+                    }
+                }
+            }
+            catch (err) {
+                this.#logger?.warn(`[Gateway] Supersede proposal creation failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        this.#logger?.info(`[Gateway] create complete: ${result.created.length} created, ${result.rejected.length} rejected, ${result.merged.length} merged, ${result.duplicates.length} duplicates | source=${source}`);
+        return result;
+    }
+    /* ═══════════════════ Private ═══════════════════ */
+    #sourceToUserId(source) {
+        switch (source) {
+            case 'agent-tool':
+                return 'agent';
+            case 'mcp-external':
+                return 'mcp';
+            case 'ide-agent':
+                return 'ide-agent';
+            case 'batch-import':
+                return 'batch-import';
+        }
+    }
+    #prepareCreateData(item, source, _userId) {
+        const contentObj = item.content && typeof item.content === 'object'
+            ? item.content
+            : { markdown: '', pattern: '' };
+        const reasoning = item.reasoning || {
+            whyStandard: '',
+            sources: ['agent'],
+            confidence: 0.7,
+        };
+        if (Array.isArray(reasoning.sources) && reasoning.sources.length === 0) {
+            reasoning.sources = ['agent'];
+        }
+        return {
+            language: item.language || '',
+            category: item.category || item._category || 'general',
+            knowledgeType: item.knowledgeType || 'code-pattern',
+            source: item.source || this.#sourceLabel(source),
+            title: item.title || '',
+            description: item.description || '',
+            tags: item.tags || [],
+            trigger: item.trigger || '',
+            kind: item.kind || 'pattern',
+            topicHint: item.topicHint || '',
+            whenClause: item.whenClause || '',
+            doClause: item.doClause || '',
+            dontClause: item.dontClause || '',
+            coreCode: item.coreCode || contentObj.pattern || '',
+            sourceRefs: item.sourceRefs || [],
+            content: contentObj,
+            reasoning,
+            headers: item.headers || [],
+            usageGuide: item.usageGuide || '',
+            scope: item.scope || '',
+            complexity: item.complexity || '',
+            sourceFile: '',
+            agentNotes: item.agentNotes || null,
+            aiInsight: reasoning.whyStandard || item.description || null,
+        };
+    }
+    #sourceLabel(source) {
+        switch (source) {
+            case 'agent-tool':
+                return 'agent';
+            case 'mcp-external':
+                return 'mcp';
+            case 'ide-agent':
+                return 'ide-agent';
+            case 'batch-import':
+                return 'batch-import';
+        }
+    }
+    #createProposalFromAdvice(advice, item) {
+        if (!this.#proposalRepo) {
+            return null;
+        }
+        const evidence = [
+            {
+                snapshotAt: Date.now(),
+                candidateTitle: item.title,
+                candidateCategory: item.category,
+                analysisReason: advice.reason,
+                mergeDirection: advice.mergeDirection,
+            },
+        ];
+        if (advice.action === 'merge' && advice.targetRecipe) {
+            const proposal = this.#proposalRepo.create({
+                type: 'merge',
+                targetRecipeId: advice.targetRecipe.id,
+                confidence: advice.confidence,
+                source: 'ide-agent',
+                description: advice.reason,
+                evidence,
+            });
+            if (!proposal) {
+                return null;
+            }
+            return {
+                proposalId: proposal.id,
+                type: 'merge',
+                targetRecipeId: advice.targetRecipe.id,
+                targetTitle: advice.targetRecipe.title,
+                status: proposal.status,
+                expiresAt: proposal.expiresAt,
+                message: `已为「${advice.targetRecipe.title}」创建融合提案，${proposal.status === 'observing' ? '观察窗口 72h 后自动执行' : '等待开发者确认'}。`,
+            };
+        }
+        if (advice.action === 'reorganize' && advice.reorganizeTargets?.length) {
+            const target = advice.reorganizeTargets[0];
+            const proposal = this.#proposalRepo.create({
+                type: 'reorganize',
+                targetRecipeId: target.id,
+                relatedRecipeIds: advice.reorganizeTargets.slice(1).map((t) => t.id),
+                confidence: advice.confidence,
+                source: 'ide-agent',
+                description: advice.reason,
+                evidence,
+            });
+            if (!proposal) {
+                return null;
+            }
+            return {
+                proposalId: proposal.id,
+                type: 'reorganize',
+                targetRecipeId: target.id,
+                targetTitle: target.title,
+                status: proposal.status,
+                expiresAt: proposal.expiresAt,
+                message: `已为 ${advice.reorganizeTargets.length} 条 Recipe 创建重组提案，需开发者在 Dashboard 确认。`,
+            };
+        }
+        if (advice.action === 'insufficient' && advice.coveredBy?.length) {
+            const target = advice.coveredBy[0];
+            const proposal = this.#proposalRepo.create({
+                type: 'enhance',
+                targetRecipeId: target.id,
+                confidence: advice.confidence,
+                source: 'ide-agent',
+                description: advice.reason,
+                evidence,
+            });
+            if (!proposal) {
+                return null;
+            }
+            return {
+                proposalId: proposal.id,
+                type: 'enhance',
+                targetRecipeId: target.id,
+                targetTitle: target.title,
+                status: proposal.status,
+                expiresAt: proposal.expiresAt,
+                message: `候选独立价值不足，已创建增强提案建议补充到「${target.title}」。`,
+            };
+        }
+        return null;
+    }
+}

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

@@ -1,13 +1,14 @@
 /**
  * DimensionAnalyzer — 多维度知识健康分析
  *
+ * **v2: 从统一维度注册表 (DimensionRegistry) 派生维度**
+ *
  * 灵感来源:
  *   - ISO/IEC 25010 质量模型 (8 大特性: 可靠性、安全性、可维护性…)
  *   - ThoughtWorks Tech Radar (Adopt/Trial/Assess/Hold 四环)
  *   - 雷达图/蛛网图可视化模型
  *
- * 核心思路: 不再按「模块 × 文件数」衡量覆盖，
- * 而是按「知识维度」衡量项目在各工程方向上的规范成熟度。
+ * 核心思路: 按「知识维度」衡量项目在各工程方向上的规范成熟度。
  * 某维度 Recipe 为 0 → 该方向完全空白，标示为 gap。
  *
  * @module DimensionAnalyzer

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

@@ -1,135 +1,26 @@
 /**
  * DimensionAnalyzer — 多维度知识健康分析
  *
+ * **v2: 从统一维度注册表 (DimensionRegistry) 派生维度**
+ *
  * 灵感来源:
  *   - ISO/IEC 25010 质量模型 (8 大特性: 可靠性、安全性、可维护性…)
  *   - ThoughtWorks Tech Radar (Adopt/Trial/Assess/Hold 四环)
  *   - 雷达图/蛛网图可视化模型
  *
- * 核心思路: 不再按「模块 × 文件数」衡量覆盖，
- * 而是按「知识维度」衡量项目在各工程方向上的规范成熟度。
+ * 核心思路: 按「知识维度」衡量项目在各工程方向上的规范成熟度。
  * 某维度 Recipe 为 0 → 该方向完全空白，标示为 gap。
  *
  * @module DimensionAnalyzer
  */
+import { classifyRecipeToDimension, DIMENSION_REGISTRY } from '#domain/dimension/index.js';
+/* ═══ 维度定义 — 从统一注册表派生 ═══════════════════════ */
 /**
- * 标准维度列表
- *
- * 覆盖主流软件工程关切方向，任何项目都应有所涉猎。
- * `topics` 与 `categories` 匹配 knowledge_entries 的字段。
+ * Panorama 使用全量维度注册表进行健康评估。
+ * 所有维度（含语言/框架条件维度）都参与评估 —
+ * 若该语言未激活但有 Recipe → 仍计入(只是不生成 gap 建议)。
  */
-const DIMENSION_DEFS = [
-    {
-        id: 'architecture',
-        name: '架构设计',
-        description: '模块结构、分层策略、依赖管理、设计模式',
-        topics: ['architecture', 'scaffold', 'workflow'],
-        categories: ['architecture', 'project-profile'],
-        weight: 1.0,
-        suggestedTopics: ['module-boundary', 'dependency-rule', 'layer-strategy'],
-        relatedRoles: ['core', 'foundation', 'app'],
-    },
-    {
-        id: 'coding-standards',
-        name: '编码规范',
-        description: '命名约定、代码风格、文档注释、import 顺序',
-        topics: ['conventions'],
-        categories: ['code-standard'],
-        weight: 0.8,
-        suggestedTopics: ['naming-convention', 'code-style', 'documentation'],
-        relatedRoles: [],
-    },
-    {
-        id: 'error-handling',
-        name: '错误处理',
-        description: '异常模式、错误恢复、输入验证、防御性编程',
-        topics: ['error-handling', 'constraints'],
-        categories: [],
-        weight: 1.0,
-        suggestedTopics: ['exception-pattern', 'error-recovery', 'input-validation'],
-        relatedRoles: ['service', 'networking', 'core'],
-    },
-    {
-        id: 'concurrency',
-        name: '并发与线程',
-        description: '线程安全、异步模式、竞态条件防护、锁策略',
-        topics: ['concurrency', 'async'],
-        categories: [],
-        weight: 0.9,
-        suggestedTopics: ['thread-safety', 'async-pattern', 'race-condition'],
-        relatedRoles: ['service', 'networking', 'storage'],
-    },
-    {
-        id: 'data-management',
-        name: '数据管理',
-        description: '持久化、缓存、序列化、数据流向完整性',
-        topics: ['data', 'data-flow', 'memory'],
-        categories: ['event-and-data-flow'],
-        weight: 0.8,
-        suggestedTopics: ['persistence', 'caching', 'serialization', 'data-integrity'],
-        relatedRoles: ['storage', 'model'],
-    },
-    {
-        id: 'networking',
-        name: '网络通信',
-        description: 'API 契约、请求模式、重试策略、实时通信',
-        topics: ['networking', 'real-time'],
-        categories: [],
-        weight: 0.7,
-        suggestedTopics: ['api-contract', 'retry-strategy', 'request-pattern'],
-        relatedRoles: ['networking'],
-    },
-    {
-        id: 'ui-patterns',
-        name: '界面模式',
-        description: 'UI 组件规范、生命周期、导航、数据绑定',
-        topics: ['ui', 'binding', 'pagination'],
-        categories: [],
-        weight: 0.7,
-        suggestedTopics: ['component-pattern', 'lifecycle', 'navigation'],
-        relatedRoles: ['ui', 'feature'],
-    },
-    {
-        id: 'testing',
-        name: '测试策略',
-        description: '测试模式、Mock 策略、CI/CD 流程',
-        topics: ['testing', 'test'],
-        categories: [],
-        weight: 0.9,
-        suggestedTopics: ['unit-test', 'mock-strategy', 'ci-cd'],
-        relatedRoles: [],
-    },
-    {
-        id: 'security',
-        name: '安全',
-        description: '认证授权、输入校验、加密、权限控制',
-        topics: ['security', 'auth'],
-        categories: [],
-        weight: 1.0,
-        suggestedTopics: ['authentication', 'authorization', 'encryption'],
-        relatedRoles: ['networking', 'service'],
-    },
-    {
-        id: 'performance',
-        name: '性能优化',
-        description: '内存管理、懒加载、缓存策略、渲染优化',
-        topics: ['performance', 'optimization'],
-        categories: [],
-        weight: 0.8,
-        suggestedTopics: ['memory-management', 'lazy-loading', 'rendering'],
-        relatedRoles: ['ui', 'storage'],
-    },
-    {
-        id: 'observability',
-        name: '可观测性',
-        description: '日志规范、事件追踪、监控诊断',
-        topics: ['logging', 'event', 'monitoring'],
-        categories: [],
-        weight: 0.7,
-        suggestedTopics: ['logging-standard', 'event-tracking', 'diagnostics'],
-        relatedRoles: ['service', 'core'],
-    },
-];
+const DIMENSION_DEFS = DIMENSION_REGISTRY;
 /* ═══ DimensionAnalyzer Class ═════════════════════════════ */
 export class DimensionAnalyzer {
     #db;
@@ -213,26 +104,10 @@ export class DimensionAnalyzer {
     /**
      * 将 recipe 分类到最匹配的维度
      *
-     * 优先级: topicHint 精确匹配 → category 匹配 → null
+     * 委托给 DimensionRegistry.classifyRecipeToDimension()
      */
     #classifyRecipe(recipe) {
-        // 1. topicHint 精确匹配
-        if (recipe.topicHint) {
-            for (const def of DIMENSION_DEFS) {
-                if (def.topics.includes(recipe.topicHint)) {
-                    return def.id;
-                }
-            }
-        }
-        // 2. category 匹配
-        if (recipe.category) {
-            for (const def of DIMENSION_DEFS) {
-                if (def.categories.includes(recipe.category)) {
-                    return def.id;
-                }
-            }
-        }
-        return null;
+        return classifyRecipeToDimension(recipe.topicHint, recipe.category);
     }
     /* ─── 维度评分 ─────────────────────────────────── */
     #scoreDimension(def, recipeCount, titles) {
@@ -268,8 +143,8 @@ export class DimensionAnalyzer {
         }
         return {
             id: def.id,
-            name: def.name,
-            description: def.description,
+            name: def.label,
+            description: def.qualityDescription,
             recipeCount,
             score,
             status,
@@ -305,11 +180,11 @@ export class DimensionAnalyzer {
             const affectedRoles = def.relatedRoles.filter((r) => moduleRoles.has(r));
             gaps.push({
                 dimension: def.id,
-                dimensionName: def.name,
+                dimensionName: def.label,
                 recipeCount: dim.recipeCount,
                 status: dim.status,
                 priority,
-                suggestedTopics: def.suggestedTopics,
+                suggestedTopics: [...def.suggestedTopics],
                 affectedRoles,
             });
         }

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

@@ -6,7 +6,7 @@
  *
  * @module BM25Scorer
  */
-import type { BM25Document, BM25SearchResult, Scorer } from './SearchTypes.js';
+import type { BM25Document, Scorer } from './SearchTypes.js';
 /** BM25 评分器 */
 export declare class BM25Scorer implements Scorer {
     _idIndex: Map<string, number>;
@@ -31,7 +31,7 @@ export declare class BM25Scorer implements Scorer {
     /** 压缩 documents 数组，清除 tombstone 空洞 */
     _compact(): void;
     /** 查询文档，返回按 BM25 分数排序的结果 */
-    search(query: string, limit?: number): BM25SearchResult[];
+    search(query: string, limit?: number): import("./SearchTypes.js").ScorerResult[];
     /** 清空索引 */
     clear(): void;
 }

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

@@ -1,7 +1,7 @@
 /**
  * SearchEngine - 统一搜索引擎
  *
- * 三级搜索策略: keyword → BM25 ranking → semantic(可选)
+ * 三级搜索策略: keyword → FieldWeighted ranking → semantic(可选)
  * 从 V1 SearchServiceV2 迁移，适配 V2 架构
  */
 import Logger from '../../infrastructure/logging/Logger.js';
@@ -10,7 +10,7 @@ import { MultiSignalRanker } from './MultiSignalRanker.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 { 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 type { BM25DocMeta, DbRow, DocMeta, RankingContext, RrfHit, Scorer, ScorerResult, 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';
 /**
@@ -97,18 +97,18 @@ export declare class SearchEngine {
     /**
      * 关键词搜索 - 直接 SQL LIKE
      * 返回包含 kind 字段的完整结果，使用 ESCAPE 防止通配符注入
-     * 当 SQL LIKE 无结果时，降级到 BM25 搜索以提升自然语言查询的召回率
+     * 当 SQL LIKE 无结果时，降级到 FieldWeighted 搜索以提升自然语言查询的召回率
      */
     _keywordSearch(query: string, type: string, limit: number): SearchResultItem[];
     /**
-     * BM25 排序搜索
+     * 加权字段搜索（FieldWeightedScorer）
      * 增加 Title/Trigger 精确匹配 bonus — 当 query 出现在标题/触发词中时
-     * 给予额外 BM25 分数加成，确保精确匹配的条目排名靠前
+     * 给予额外分数加成，确保精确匹配的条目排名靠前
      */
-    _bm25Search(query: string, type: string, limit: number): SearchResultItem[];
+    _scorerSearch(query: string, type: string, limit: number): SearchResultItem[];
     /**
      * 语义搜索 - 需要 AI Provider 的 embed 功能
-     * 降级到 BM25 如果 AI 不可用
+     * 不可用时降级到 FieldWeighted 搜索
      * @returns >}
      */
     _semanticSearch(query: string, type: string, limit: number): Promise<{
@@ -117,7 +117,7 @@ export declare class SearchEngine {
     }>;
     /**
      * 补充详细字段（content / description / trigger / delivery 字段）— 批量 IN 查询
-     * 用于向量搜索结果与 BM25 结果的一致性
+     * 用于向量搜索结果与 FieldWeighted 结果的一致性
      */
     _supplementDetails(items: SearchResultItem[]): void;
     /**
@@ -138,9 +138,10 @@ export declare class SearchEngine {
     /**
      * 从 DB 行构建索引文本
      *
-     * 使用 BM25F 思想：高价值字段（title, trigger）重复出现以提升 TF 权重
+     * 高价值字段（title, trigger）通过重复出现提升 TF 权重
      * — title ×3, trigger ×2, description ×1.5（通过重复 token 实现）
-     * 这确保标题匹配的文档获得显著更高的 BM25 分数
+     * 这确保标题匹配的文档获得显著更高的分数
+     * 注：此逻辑主要服务于 BM25Scorer，FieldWeightedScorer 内部已有字段权重机制
      */
     _buildDocText(r: DbRow): string;
     /**