spectra-cli 4.1.1

package/dist/panoramic/anchoring/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * anchoring 模块对外接口
+ * 编排函数 anchorDocToCode：Chunking → Embedding → Similarity → EdgeBuilding
+ * 零 chunk 降级：直接返回空结果，不调用 EmbeddingProvider（FR-015）
+ * tokenUsage 记录与 BudgetGate F1 格式对齐（FR-016，AC-011）
+ */
+import type { GraphEdge, GraphNode } from '../graph/graph-types.js';
+import type { EmbeddingProvider, EmbeddingTokenUsage } from './embedding-provider.js';
+import { type DocChunkerOptions } from './chunker.js';
+/**
+ * anchorDocToCode 的输入选项
+ */
+export interface AnchorOptions {
+    /** 项目根目录（绝对路径，用于计算 repo-relative 路径） */
+    projectRoot: string;
+    /** Markdown 文档文件绝对路径列表（空时零 chunk 降级） */
+    markdownFiles: string[];
+    /** 图谱中的代码节点列表（用于生成 embedding 和边） */
+    graphNodes: GraphNode[];
+    /** EmbeddingProvider 实例（Local 或 OpenAI） */
+    provider: EmbeddingProvider;
+    /** 相似度阈值（默认 0.75，含边界） */
+    threshold?: number;
+    /** evidenceText 最大字符数（默认 200） */
+    maxEvidenceLength?: number;
+    /** Chunker 选项（默认 maxTokens=512） */
+    chunkerOptions?: DocChunkerOptions;
+}
+/**
+ * anchorDocToCode 的返回值
+ */
+export interface AnchorResult {
+    /** 生成的语义边列表 */
+    edges: GraphEdge[];
+    /**
+     * 所有 embedding 调用的 token 使用记录列表
+     * 格式与 BudgetGate F1 的 BudgetGateAttempt 兼容（含 llmModel + durationMs）
+     */
+    tokenUsage: EmbeddingTokenUsage[];
+    /** 统计信息 */
+    stats: {
+        /** 处理的 chunk 数量 */
+        chunksProcessed: number;
+        /** 生成的语义边数量 */
+        edgesGenerated: number;
+        /** 总耗时（毫秒） */
+        durationMs: number;
+    };
+}
+/**
+ * 文档 → 代码节点语义锚定编排函数
+ *
+ * 步骤：
+ * 1. chunkMarkdownFiles() → DocChunk[]
+ * 2. 若 chunks 为空，提前返回零结果（FR-015）
+ * 3. provider.embed(chunkTexts) → chunk 向量
+ * 4. provider.embed(nodeSignatures) → node 向量
+ * 5. filterByThreshold() → SimilarPair[]
+ * 6. buildSemanticEdges() → GraphEdge[]
+ * 7. 汇总 tokenUsage
+ *
+ * @param options AnchorOptions
+ * @returns AnchorResult
+ */
+export declare function anchorDocToCode(options: AnchorOptions): Promise<AnchorResult>;
+export type { DocChunk, DocChunkerOptions } from './chunker.js';
+export { chunkMarkdownFiles } from './chunker.js';
+export type { EmbeddingProvider, EmbedResult, EmbeddingTokenUsage } from './embedding-provider.js';
+export type { SimilarPair } from './similarity.js';
+export { cosineSimilarity, filterByThreshold } from './similarity.js';
+export type { BuildEdgesOptions, CodeNodeInfo } from './edge-builder.js';
+export { buildSemanticEdges } from './edge-builder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/panoramic/anchoring/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/panoramic/anchoring/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACtF,OAAO,EAAsB,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAQ1E;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,oCAAoC;IACpC,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,2CAA2C;IAC3C,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,yBAAyB;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mCAAmC;IACnC,cAAc,CAAC,EAAE,iBAAiB,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,eAAe;IACf,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB;;;OAGG;IACH,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,WAAW;IACX,KAAK,EAAE;QACL,mBAAmB;QACnB,eAAe,EAAE,MAAM,CAAC;QACxB,eAAe;QACf,cAAc,EAAE,MAAM,CAAC;QACvB,cAAc;QACd,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAmFnF;AAMD,YAAY,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnG,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/panoramic/anchoring/index.js

@@ -0,0 +1,91 @@
+import { chunkMarkdownFiles } from './chunker.js';
+import { filterByThreshold } from './similarity.js';
+import { buildSemanticEdges } from './edge-builder.js';
+// ============================================================
+// 主函数
+// ============================================================
+/**
+ * 文档 → 代码节点语义锚定编排函数
+ *
+ * 步骤：
+ * 1. chunkMarkdownFiles() → DocChunk[]
+ * 2. 若 chunks 为空，提前返回零结果（FR-015）
+ * 3. provider.embed(chunkTexts) → chunk 向量
+ * 4. provider.embed(nodeSignatures) → node 向量
+ * 5. filterByThreshold() → SimilarPair[]
+ * 6. buildSemanticEdges() → GraphEdge[]
+ * 7. 汇总 tokenUsage
+ *
+ * @param options AnchorOptions
+ * @returns AnchorResult
+ */
+export async function anchorDocToCode(options) {
+    const startMs = performance.now();
+    const { projectRoot, markdownFiles, graphNodes, provider, threshold = 0.75, maxEvidenceLength = 200, chunkerOptions, } = options;
+    const tokenUsageList = [];
+    // Step 1：Hybrid Chunking
+    const chunks = chunkMarkdownFiles(markdownFiles, projectRoot, chunkerOptions);
+    // Step 2：零 chunk 降级（FR-015）
+    if (chunks.length === 0) {
+        return {
+            edges: [],
+            tokenUsage: [],
+            stats: {
+                chunksProcessed: 0,
+                edgesGenerated: 0,
+                durationMs: performance.now() - startMs,
+            },
+        };
+    }
+    // Step 3：Embed chunks
+    const chunkTexts = chunks.map(c => c.text);
+    const chunkEmbedResult = await provider.embed(chunkTexts);
+    tokenUsageList.push(chunkEmbedResult.tokenUsage);
+    // Step 4：Embed code node signatures
+    // 使用 node.id + node.label 作为代码节点签名（提升语义匹配质量）
+    const codeNodes = graphNodes.map(n => ({
+        id: n.id,
+        name: n.label || n.id,
+    }));
+    let nodeVectors;
+    if (codeNodes.length > 0) {
+        const nodeTexts = codeNodes.map(n => `${n.name} ${n.id}`);
+        const nodeEmbedResult = await provider.embed(nodeTexts);
+        tokenUsageList.push(nodeEmbedResult.tokenUsage);
+        // 构造 nodeId → vector Map
+        nodeVectors = new Map();
+        for (let i = 0; i < codeNodes.length; i++) {
+            const vec = nodeEmbedResult.vectors[i];
+            const node = codeNodes[i];
+            if (vec && node) {
+                nodeVectors.set(node.id, vec);
+            }
+        }
+    }
+    else {
+        nodeVectors = new Map();
+    }
+    // Step 5：相似度过滤
+    const pairs = filterByThreshold(chunkEmbedResult.vectors, nodeVectors, threshold);
+    // Step 6：生成语义边
+    const edges = buildSemanticEdges({
+        chunks,
+        pairs,
+        codeNodes,
+        projectRoot,
+        maxEvidenceLength,
+    });
+    return {
+        edges,
+        tokenUsage: tokenUsageList,
+        stats: {
+            chunksProcessed: chunks.length,
+            edgesGenerated: edges.length,
+            durationMs: performance.now() - startMs,
+        },
+    };
+}
+export { chunkMarkdownFiles } from './chunker.js';
+export { cosineSimilarity, filterByThreshold } from './similarity.js';
+export { buildSemanticEdges } from './edge-builder.js';
+//# sourceMappingURL=index.js.map

package/dist/panoramic/anchoring/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/panoramic/anchoring/index.ts"],"names":[],"mappings":"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"}

package/dist/panoramic/anchoring/providers/factory.d.ts

@@ -0,0 +1,35 @@
+/**
+ * EmbeddingProvider 工厂函数
+ * 根据 SPECTRA_EMBEDDING_PROVIDER 环境变量选择提供方
+ *
+ * 支持的值：
+ *   - 'local'（默认）：使用 @huggingface/transformers 本地推理
+ *   - 'openai'：使用 OpenAI text-embedding-3-small API
+ *
+ * 设计决策：
+ *   - 不自动 fallback（NFR-002）：local 加载失败时抛出含安装指引的错误；
+ *     openai 缺 API key 时抛出提示切换的错误
+ *   - 未知 provider 名称时立即抛错，防止静默降级导致行为不一致
+ */
+import type { EmbeddingProvider } from '../embedding-provider.js';
+export type EmbeddingProviderName = 'local' | 'openai';
+export interface EmbeddingProviderFactoryOptions {
+    /** 显式指定 provider 名称（覆盖环境变量） */
+    providerName?: EmbeddingProviderName | string;
+    /** 显式传入 OpenAI API key（覆盖 OPENAI_API_KEY 环境变量） */
+    openaiApiKey?: string;
+}
+/**
+ * 创建 EmbeddingProvider 实例
+ *
+ * 选择优先级：
+ * 1. options.providerName（显式参数）
+ * 2. process.env.SPECTRA_EMBEDDING_PROVIDER（环境变量）
+ * 3. 默认值 'local'
+ *
+ * @throws Error 当 provider 名称无效时（有效值：local | openai）
+ * @throws Error 当选择 openai 但 API key 不可用时
+ * @throws Error 当选择 local 但 @huggingface/transformers 不可用时（在 embed() 调用时抛出）
+ */
+export declare function createEmbeddingProvider(options?: EmbeddingProviderFactoryOptions): EmbeddingProvider;
+//# sourceMappingURL=factory.d.ts.map

package/dist/panoramic/anchoring/providers/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../src/panoramic/anchoring/providers/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAQlE,MAAM,MAAM,qBAAqB,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,+BAA+B;IAC9C,+BAA+B;IAC/B,YAAY,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC;IAC9C,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,+BAAoC,GAC5C,iBAAiB,CAmBnB"}

package/dist/panoramic/anchoring/providers/factory.js

@@ -0,0 +1,33 @@
+import { LocalEmbeddingProvider } from './local-provider.js';
+import { createOpenAIProvider } from './openai-provider.js';
+// ============================================================
+// 工厂函数
+// ============================================================
+/**
+ * 创建 EmbeddingProvider 实例
+ *
+ * 选择优先级：
+ * 1. options.providerName（显式参数）
+ * 2. process.env.SPECTRA_EMBEDDING_PROVIDER（环境变量）
+ * 3. 默认值 'local'
+ *
+ * @throws Error 当 provider 名称无效时（有效值：local | openai）
+ * @throws Error 当选择 openai 但 API key 不可用时
+ * @throws Error 当选择 local 但 @huggingface/transformers 不可用时（在 embed() 调用时抛出）
+ */
+export function createEmbeddingProvider(options = {}) {
+    // 确定 provider 名称（选项 > 环境变量 > 默认值）
+    const raw = options.providerName ?? process.env.SPECTRA_EMBEDDING_PROVIDER ?? 'local';
+    const name = raw.toLowerCase();
+    if (name === 'local') {
+        // local provider 的依赖缺失错误将在 embed() 首次调用时才会抛出（lazy load）
+        return new LocalEmbeddingProvider();
+    }
+    if (name === 'openai') {
+        // API key 缺失时 createOpenAIProvider 内部会抛出清晰错误
+        return createOpenAIProvider({ apiKey: options.openaiApiKey });
+    }
+    // 未知 provider 名称：立即抛错，不静默降级
+    throw new Error(`未知的 EmbeddingProvider: "${raw}"。有效值：local | openai（通过 SPECTRA_EMBEDDING_PROVIDER 环境变量设置）`);
+}
+//# sourceMappingURL=factory.js.map

package/dist/panoramic/anchoring/providers/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../../src/panoramic/anchoring/providers/factory.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAe5D,+DAA+D;AAC/D,OAAO;AACP,+DAA+D;AAE/D;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CACrC,UAA2C,EAAE;IAE7C,kCAAkC;IAClC,MAAM,GAAG,GAAG,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,OAAO,CAAC;IACtF,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAE/B,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,wDAAwD;QACxD,OAAO,IAAI,sBAAsB,EAAE,CAAC;IACtC,CAAC;IAED,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,6CAA6C;QAC7C,OAAO,oBAAoB,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,4BAA4B;IAC5B,MAAM,IAAI,KAAK,CACb,2BAA2B,GAAG,4DAA4D,CAC3F,CAAC;AACJ,CAAC"}

package/dist/panoramic/anchoring/providers/local-provider.d.ts

@@ -0,0 +1,48 @@
+/**
+ * LocalEmbeddingProvider — @huggingface/transformers 实现
+ * 使用 all-MiniLM-L6-v2 模型，动态导入避免包缺失时同步 crash
+ * tokenUsage 记录：llmModel='local-embedding'，inputTokens=字符数/4，outputTokens=0，durationMs=精确计时
+ *
+ * 设计：将动态 import 抽取为可替换的 _importTransformers 函数，便于测试注入
+ */
+import type { EmbeddingProvider, EmbedResult } from '../embedding-provider.js';
+export declare const LOAD_ERROR_MSG = "\u65E0\u6CD5\u52A0\u8F7D @huggingface/transformers\uFF0C\u8BF7\u6267\u884C npm install @huggingface/transformers \u6216\u5207\u6362 SPECTRA_EMBEDDING_PROVIDER=openai";
+/**
+ * 默认的动态 import 函数
+ * 测试中可通过 setTransformersImporter 替换为 mock
+ */
+type TransformersImporter = () => Promise<any>;
+/**
+ * 设置自定义的 transformers 加载函数（仅供测试使用）
+ */
+export declare function _setTransformersImporter(importer: TransformersImporter): void;
+/**
+ * 重置 singleton 状态（仅供测试使用）
+ */
+export declare function _resetPipelineForTest(): void;
+/**
+ * 基于 @huggingface/transformers 的本地 embedding 提供方
+ * 使用 all-MiniLM-L6-v2 模型，向量维度 384
+ *
+ * 特性：
+ * - lazy load pipeline：首次调用时加载，后续复用 singleton
+ * - 依赖缺失时抛出含安装指引的清晰错误（FR-011）
+ * - tokenUsage 记录与 BudgetGate F1 格式对齐（FR-016）
+ */
+export declare class LocalEmbeddingProvider implements EmbeddingProvider {
+    readonly providerName: "local";
+    readonly llmModelLabel = "local-embedding";
+    readonly dimensions = 384;
+    /**
+     * 批量 embed 文本
+     * @throws Error 当 @huggingface/transformers 不可用时
+     */
+    embed(texts: string[]): Promise<EmbedResult>;
+    /**
+     * 获取 singleton pipeline（lazy load）
+     * 通过 _transformersImporter 加载（测试可注入 mock）
+     */
+    private loadPipeline;
+}
+export {};
+//# sourceMappingURL=local-provider.d.ts.map

package/dist/panoramic/anchoring/providers/local-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-provider.d.ts","sourceRoot":"","sources":["../../../../src/panoramic/anchoring/providers/local-provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAuB,MAAM,0BAA0B,CAAC;AAMpG,eAAO,MAAM,cAAc,0KACuF,CAAC;AAenH;;;GAGG;AAEH,KAAK,oBAAoB,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;AAW/C;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAE7E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAY5C;AAMD;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,YAAW,iBAAiB;IAC9D,QAAQ,CAAC,YAAY,EAAG,OAAO,CAAU;IACzC,QAAQ,CAAC,aAAa,qBAAqB;IAC3C,QAAQ,CAAC,UAAU,OAAO;IAE1B;;;OAGG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAkClD;;;OAGG;YAEW,YAAY;CA+B3B"}

package/dist/panoramic/anchoring/providers/local-provider.js

@@ -0,0 +1,145 @@
+// ============================================================
+// 加载失败错误信息
+// ============================================================
+export const LOAD_ERROR_MSG = '无法加载 @huggingface/transformers，请执行 npm install @huggingface/transformers 或切换 SPECTRA_EMBEDDING_PROVIDER=openai';
+// ============================================================
+// Singleton Pipeline 缓存
+// ============================================================
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let cachedPipeline = null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let pipelineLoading = null;
+let _transformersImporter = async () => {
+    try {
+        // @ts-ignore — @huggingface/transformers 为 optionalDependencies，类型声明不保证存在
+        return await import('@huggingface/transformers');
+    }
+    catch {
+        throw new Error(LOAD_ERROR_MSG);
+    }
+};
+/**
+ * 设置自定义的 transformers 加载函数（仅供测试使用）
+ */
+export function _setTransformersImporter(importer) {
+    _transformersImporter = importer;
+}
+/**
+ * 重置 singleton 状态（仅供测试使用）
+ */
+export function _resetPipelineForTest() {
+    cachedPipeline = null;
+    pipelineLoading = null;
+    // 重置为默认加载函数
+    _transformersImporter = async () => {
+        try {
+            // @ts-ignore — @huggingface/transformers 为 optionalDependencies
+            return await import('@huggingface/transformers');
+        }
+        catch {
+            throw new Error(LOAD_ERROR_MSG);
+        }
+    };
+}
+// ============================================================
+// LocalEmbeddingProvider
+// ============================================================
+/**
+ * 基于 @huggingface/transformers 的本地 embedding 提供方
+ * 使用 all-MiniLM-L6-v2 模型，向量维度 384
+ *
+ * 特性：
+ * - lazy load pipeline：首次调用时加载，后续复用 singleton
+ * - 依赖缺失时抛出含安装指引的清晰错误（FR-011）
+ * - tokenUsage 记录与 BudgetGate F1 格式对齐（FR-016）
+ */
+export class LocalEmbeddingProvider {
+    providerName = 'local';
+    llmModelLabel = 'local-embedding';
+    dimensions = 384;
+    /**
+     * 批量 embed 文本
+     * @throws Error 当 @huggingface/transformers 不可用时
+     */
+    async embed(texts) {
+        const startMs = performance.now();
+        // 动态加载 @huggingface/transformers（lazy，首次调用时）
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const pipe = await this.loadPipeline();
+        // 计算粗估 inputTokens：字符总数 / 4
+        const inputTokens = Math.ceil(texts.reduce((sum, t) => sum + t.length, 0) / 4);
+        // 批量推理
+        const vectors = [];
+        for (const text of texts) {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const output = await pipe(text, { pooling: 'mean', normalize: true });
+            // 兼容不同版本的 output 格式（.data 或 .ort_tensor.cpuData 或直接 Float32Array）
+            vectors.push(extractVector(output));
+        }
+        const durationMs = performance.now() - startMs;
+        const tokenUsage = {
+            llmModel: this.llmModelLabel,
+            inputTokens,
+            outputTokens: 0,
+            durationMs,
+        };
+        return { vectors, tokenUsage };
+    }
+    /**
+     * 获取 singleton pipeline（lazy load）
+     * 通过 _transformersImporter 加载（测试可注入 mock）
+     */
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    async loadPipeline() {
+        if (cachedPipeline !== null) {
+            return cachedPipeline;
+        }
+        // 防止并发重复加载
+        if (pipelineLoading) {
+            return pipelineLoading;
+        }
+        pipelineLoading = (async () => {
+            // 通过可替换的 importer 加载 transformers 模块
+            const transformersModule = await _transformersImporter();
+            cachedPipeline = await transformersModule.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2');
+            return cachedPipeline;
+        })();
+        try {
+            return await pipelineLoading;
+        }
+        finally {
+            // 清除 loading promise（成功或失败都清除以允许重试）
+            if (!cachedPipeline) {
+                pipelineLoading = null;
+            }
+        }
+    }
+}
+// ============================================================
+// 工具函数
+// ============================================================
+/**
+ * 从不同版本 transformers 的输出中提取 Float32Array
+ * 兼容：output.data、output.ort_tensor.cpuData、直接 Float32Array
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractVector(output) {
+    if (output instanceof Float32Array) {
+        return output;
+    }
+    // transformers v3 Tensor 格式：{ data: Float32Array, dims: number[] }
+    if (output?.data instanceof Float32Array) {
+        return output.data;
+    }
+    // 数组格式（某些版本返回嵌套数组）
+    if (Array.isArray(output)) {
+        return new Float32Array(output.flat());
+    }
+    // ort_tensor 格式（旧版本兼容）
+    if (output?.ort_tensor?.cpuData instanceof Float32Array) {
+        return output.ort_tensor.cpuData;
+    }
+    // 兜底：返回空向量
+    return new Float32Array(0);
+}
+//# sourceMappingURL=local-provider.js.map

package/dist/panoramic/anchoring/providers/local-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-provider.js","sourceRoot":"","sources":["../../../../src/panoramic/anchoring/providers/local-provider.ts"],"names":[],"mappings":"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"}

package/dist/panoramic/anchoring/providers/openai-provider.d.ts

@@ -0,0 +1,45 @@
+/**
+ * OpenAIEmbeddingProvider — text-embedding-3-small via fetch 实现
+ * 不依赖任何 openai SDK，直接调用 https://api.openai.com/v1/embeddings
+ * tokenUsage 记录：
+ *   - llmModel: 'text-embedding-3-small'
+ *   - inputTokens: API 返回的 usage.prompt_tokens（真实计数）
+ *   - outputTokens: 0（embedding 无输出）
+ *   - durationMs: 从请求发出到响应解析完成的耗时
+ *
+ * API key 缺失时构造器即抛清晰错误（FR-010）
+ */
+import type { EmbeddingProvider, EmbedResult } from '../embedding-provider.js';
+/**
+ * 基于 OpenAI text-embedding-3-small 的 embedding 提供方
+ * 向量维度 1536，直接通过 fetch 调用 OpenAI Embeddings API
+ *
+ * 特性：
+ * - API key 缺失时在构造阶段立即抛出清晰错误（FR-010）
+ * - tokenUsage 使用 API 返回的真实 prompt_tokens（非粗估）
+ * - 按 index 排序保证输出向量顺序与输入 texts 对应
+ */
+export declare class OpenAIEmbeddingProvider implements EmbeddingProvider {
+    private readonly apiKey;
+    readonly providerName: "openai";
+    readonly llmModelLabel = "text-embedding-3-small";
+    readonly dimensions = 1536;
+    private static readonly MODEL;
+    private static readonly ENDPOINT;
+    constructor(apiKey: string);
+    /**
+     * 批量 embed 文本，调用 OpenAI Embeddings API
+     * @param texts 待 embed 的文本列表（非空数组）
+     * @throws Error 当 API 请求失败（HTTP 非 200）或网络异常时
+     */
+    embed(texts: string[]): Promise<EmbedResult>;
+}
+/**
+ * 创建 OpenAIEmbeddingProvider 实例
+ * 优先使用 options.apiKey，其次从 OPENAI_API_KEY 环境变量读取
+ * @throws Error 当 API key 不可用时
+ */
+export declare function createOpenAIProvider(options?: {
+    apiKey?: string;
+}): OpenAIEmbeddingProvider;
+//# sourceMappingURL=openai-provider.d.ts.map

package/dist/panoramic/anchoring/providers/openai-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-provider.d.ts","sourceRoot":"","sources":["../../../../src/panoramic/anchoring/providers/openai-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAuB,MAAM,0BAA0B,CAAC;AAqBpG;;;;;;;;GAQG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAQnD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAPnC,QAAQ,CAAC,YAAY,EAAG,QAAQ,CAAU;IAC1C,QAAQ,CAAC,aAAa,4BAA4B;IAClD,QAAQ,CAAC,UAAU,QAAQ;IAE3B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAA4B;IACzD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAA0C;gBAE7C,MAAM,EAAE,MAAM;IAQ3C;;;;OAIG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;CAwCnD;AAMD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,uBAAuB,CAG/F"}

package/dist/panoramic/anchoring/providers/openai-provider.js

@@ -0,0 +1,78 @@
+// ============================================================
+// OpenAIEmbeddingProvider
+// ============================================================
+/**
+ * 基于 OpenAI text-embedding-3-small 的 embedding 提供方
+ * 向量维度 1536，直接通过 fetch 调用 OpenAI Embeddings API
+ *
+ * 特性：
+ * - API key 缺失时在构造阶段立即抛出清晰错误（FR-010）
+ * - tokenUsage 使用 API 返回的真实 prompt_tokens（非粗估）
+ * - 按 index 排序保证输出向量顺序与输入 texts 对应
+ */
+export class OpenAIEmbeddingProvider {
+    apiKey;
+    providerName = 'openai';
+    llmModelLabel = 'text-embedding-3-small';
+    dimensions = 1536;
+    static MODEL = 'text-embedding-3-small';
+    static ENDPOINT = 'https://api.openai.com/v1/embeddings';
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+        if (!apiKey) {
+            throw new Error('OPENAI_API_KEY 未设置。请通过环境变量提供，或设置 SPECTRA_EMBEDDING_PROVIDER=local');
+        }
+    }
+    /**
+     * 批量 embed 文本，调用 OpenAI Embeddings API
+     * @param texts 待 embed 的文本列表（非空数组）
+     * @throws Error 当 API 请求失败（HTTP 非 200）或网络异常时
+     */
+    async embed(texts) {
+        // 与 LocalEmbeddingProvider 统一使用 performance.now()（亚毫秒精度）
+        const startedAt = performance.now();
+        const response = await fetch(OpenAIEmbeddingProvider.ENDPOINT, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({
+                model: OpenAIEmbeddingProvider.MODEL,
+                input: texts,
+                encoding_format: 'float',
+            }),
+        });
+        if (!response.ok) {
+            // 读取响应体以提供更详细的错误信息（读取失败时降级为占位符）
+            const errorBody = await response.text().catch(() => '<no body>');
+            throw new Error(`OpenAI embeddings 调用失败（HTTP ${response.status}）：${errorBody}`);
+        }
+        const payload = (await response.json());
+        // 按 index 排序，确保输出向量顺序与输入 texts 严格对应
+        const vectors = payload.data
+            .sort((a, b) => a.index - b.index)
+            .map((item) => Float32Array.from(item.embedding));
+        const tokenUsage = {
+            llmModel: OpenAIEmbeddingProvider.MODEL,
+            // 使用 API 返回的真实 token 计数，而非字符数粗估
+            inputTokens: payload.usage.prompt_tokens,
+            outputTokens: 0,
+            durationMs: performance.now() - startedAt,
+        };
+        return { vectors, tokenUsage };
+    }
+}
+// ============================================================
+// 工厂入口（供 factory.ts 使用）
+// ============================================================
+/**
+ * 创建 OpenAIEmbeddingProvider 实例
+ * 优先使用 options.apiKey，其次从 OPENAI_API_KEY 环境变量读取
+ * @throws Error 当 API key 不可用时
+ */
+export function createOpenAIProvider(options = {}) {
+    const apiKey = options.apiKey ?? process.env.OPENAI_API_KEY ?? '';
+    return new OpenAIEmbeddingProvider(apiKey);
+}
+//# sourceMappingURL=openai-provider.js.map

package/dist/panoramic/anchoring/providers/openai-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-provider.js","sourceRoot":"","sources":["../../../../src/panoramic/anchoring/providers/openai-provider.ts"],"names":[],"mappings":"AA4BA,+DAA+D;AAC/D,0BAA0B;AAC1B,+DAA+D;AAE/D;;;;;;;;GAQG;AACH,MAAM,OAAO,uBAAuB;IAQL;IAPpB,YAAY,GAAG,QAAiB,CAAC;IACjC,aAAa,GAAG,wBAAwB,CAAC;IACzC,UAAU,GAAG,IAAI,CAAC;IAEnB,MAAM,CAAU,KAAK,GAAG,wBAAwB,CAAC;IACjD,MAAM,CAAU,QAAQ,GAAG,sCAAsC,CAAC;IAE1E,YAA6B,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;QACzC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,mEAAmE,CACpE,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,KAAe;QACzB,yDAAyD;QACzD,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAEpC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,uBAAuB,CAAC,QAAQ,EAAE;YAC7D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;aACvC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,KAAK,EAAE,uBAAuB,CAAC,KAAK;gBACpC,KAAK,EAAE,KAAK;gBACZ,eAAe,EAAE,OAAO;aACzB,CAAC;SACH,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,gCAAgC;YAChC,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC;YACjE,MAAM,IAAI,KAAK,CAAC,+BAA+B,QAAQ,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC,CAAC;QAClF,CAAC;QAED,MAAM,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA4B,CAAC;QAEnE,oCAAoC;QACpC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI;aACzB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;aACjC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;QAEpD,MAAM,UAAU,GAAwB;YACtC,QAAQ,EAAE,uBAAuB,CAAC,KAAK;YACvC,gCAAgC;YAChC,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC,aAAa;YACxC,YAAY,EAAE,CAAC;YACf,UAAU,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS;SAC1C,CAAC;QAEF,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IACjC,CAAC;;AAGH,+DAA+D;AAC/D,wBAAwB;AACxB,+DAA+D;AAE/D;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAA+B,EAAE;IACpE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC;IAClE,OAAO,IAAI,uBAAuB,CAAC,MAAM,CAAC,CAAC;AAC7C,CAAC"}

package/dist/panoramic/anchoring/similarity.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Cosine 相似度计算 + 阈值过滤
+ * 使用 Float32Array 优化计算性能
+ * 阈值过滤：similarity >= threshold（含边界值，FR-012）
+ */
+/**
+ * 相似对（Chunk × CodeNode）
+ */
+export interface SimilarPair {
+    /** chunk 在输入数组中的索引 */
+    chunkIndex: number;
+    /** 代码节点 ID */
+    nodeId: string;
+    /** 余弦相似度得分（0.0 到 1.0） */
+    similarity: number;
+}
+/**
+ * 计算两个 Float32Array 向量的余弦相似度
+ * 假设向量已归一化（all-MiniLM-L6-v2 输出已 normalize=true）
+ * 若未归一化则计算点积 / (||a|| × ||b||)
+ *
+ * @param a 向量 a
+ * @param b 向量 b
+ * @returns 余弦相似度，范围 [-1, 1]（已归一化向量为 [0, 1]）
+ */
+export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+/**
+ * 对所有 (chunkIndex, nodeId) 组合批量计算余弦相似度，
+ * 过滤出 similarity >= threshold 的对（含边界值，FR-012）
+ *
+ * @param chunkVectors  各 chunk 的 embedding 向量列表（顺序与 chunks 对应）
+ * @param nodeVectors   代码节点 ID → embedding 向量的 Map
+ * @param threshold     相似度阈值（默认 0.75，含边界）
+ * @returns 所有满足阈值的相似对，按 similarity 降序排列
+ */
+export declare function filterByThreshold(chunkVectors: Float32Array[], nodeVectors: Map<string, Float32Array>, threshold: number): SimilarPair[];
+//# sourceMappingURL=similarity.d.ts.map

package/dist/panoramic/anchoring/similarity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"similarity.d.ts","sourceRoot":"","sources":["../../../src/panoramic/anchoring/similarity.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,sBAAsB;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc;IACd,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAwBzE;AAMD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,YAAY,EAAE,EAC5B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,EACtC,SAAS,EAAE,MAAM,GAChB,WAAW,EAAE,CA0Bf"}