spectra-cli 4.1.1

package/dist/panoramic/anchoring/chunker.js

@@ -0,0 +1,274 @@
+/**
+ * Hybrid Chunker — 以 H2/H3 标题为主边界切分 Markdown 文档
+ * 段落合并策略：相邻段落合并直到接近 512 tokens（字符数/4 粗估）
+ * 每个 chunk 记录 startLine/endLine（1-based）和 headingPath
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+// ============================================================
+// 主函数
+// ============================================================
+/**
+ * 批量切分 Markdown 文件为 DocChunk 数组
+ *
+ * @param filePaths   绝对路径列表（若为空则直接返回 []，FR-015 降级场景）
+ * @param projectRoot 项目根目录（用于计算 repo-relative 路径）
+ * @param options     Chunker 选项（默认 maxTokens=512）
+ */
+export function chunkMarkdownFiles(filePaths, projectRoot, options) {
+    // 零 doc-file 降级：直接返回空数组（FR-015）
+    if (filePaths.length === 0) {
+        return [];
+    }
+    const maxTokens = options?.maxTokens ?? 512;
+    const allChunks = [];
+    for (const absPath of filePaths) {
+        const chunks = chunkSingleFile(absPath, projectRoot, maxTokens);
+        allChunks.push(...chunks);
+    }
+    return allChunks;
+}
+// ============================================================
+// 单文件处理
+// ============================================================
+/** 切分单个 Markdown 文件 */
+function chunkSingleFile(absPath, projectRoot, maxTokens) {
+    let content;
+    try {
+        content = fs.readFileSync(absPath, 'utf-8');
+    }
+    catch {
+        // 文件不可读时降级为空（不抛错）
+        return [];
+    }
+    // 空文件降级
+    if (!content.trim()) {
+        return [];
+    }
+    const repoRelPath = toRepoRelative(absPath, projectRoot);
+    const rawLines = content.split('\n');
+    // 提取所有 H2/H3 章节
+    const sections = extractSections(rawLines);
+    // 如果没有任何 H2/H3，把整个文档作为一个 chunk
+    if (sections.length === 0) {
+        const text = rawLines.join('\n').trim();
+        if (!text) {
+            return [];
+        }
+        // 超长时分段
+        return splitLongText(text, repoRelPath, 1, rawLines.length, '', maxTokens);
+    }
+    const chunks = [];
+    // 处理各章节：段落合并 + 超长拆分
+    for (const section of sections) {
+        const sectionChunks = sectionToChunks(section, repoRelPath, maxTokens);
+        chunks.push(...sectionChunks);
+    }
+    return chunks;
+}
+// ============================================================
+// 章节提取
+// ============================================================
+/** 从行数组中提取所有 H2/H3 章节 */
+function extractSections(lines) {
+    const sections = [];
+    // 记录各级别当前 heading，用于构造 headingPath
+    let currentH2 = '';
+    // 找出所有 H2/H3 heading 的行号
+    const headingIndices = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        // 匹配 H2：以 "## " 或 "##\t" 开头，但不是 H3
+        if (/^##\s/.test(line) && !/^###/.test(line)) {
+            headingIndices.push({ lineIdx: i, level: 2, text: line.trim() });
+        }
+        else if (/^###\s/.test(line)) {
+            headingIndices.push({ lineIdx: i, level: 3, text: line.trim() });
+        }
+    }
+    if (headingIndices.length === 0) {
+        return [];
+    }
+    for (let i = 0; i < headingIndices.length; i++) {
+        const current = headingIndices[i];
+        if (!current)
+            continue;
+        const nextEntry = headingIndices[i + 1];
+        const nextStartLineIdx = nextEntry !== undefined ? nextEntry.lineIdx : lines.length;
+        // 更新 H2 上下文
+        if (current.level === 2) {
+            currentH2 = current.text;
+        }
+        // 构造 headingPath
+        const headingPath = current.level === 2
+            ? current.text
+            : `${currentH2} > ${current.text}`;
+        // body lines（不含 heading 自身）
+        const bodyLines = lines.slice(current.lineIdx + 1, nextStartLineIdx);
+        sections.push({
+            level: current.level,
+            headingLine: current.text,
+            headingPath,
+            startLine: current.lineIdx + 1, // 1-based
+            endLine: nextStartLineIdx, // 最后一行 1-based
+            bodyLines,
+        });
+    }
+    return sections;
+}
+// ============================================================
+// 章节 → Chunk
+// ============================================================
+/** 将单个章节转换为一个或多个 chunk（段落合并 + 超长拆分） */
+function sectionToChunks(section, repoRelPath, maxTokens) {
+    // 把 body 按空行分割为段落
+    const paragraphs = splitIntoParagraphs(section.bodyLines);
+    if (paragraphs.length === 0) {
+        return [];
+    }
+    const chunks = [];
+    // 当前合并中的段落文本（以 heading 行开头）
+    let currentLines = [section.headingLine];
+    // 当前 chunk 起始行（1-based）：heading 行本身
+    let chunkStartLine = section.startLine;
+    // 当前在 bodyLines 中已消费的行数
+    let lineOffset = 0;
+    for (const para of paragraphs) {
+        const paraText = para.lines.join('\n');
+        const candidateText = currentLines.join('\n') + '\n' + paraText;
+        const candidateTokens = estimateTokens(candidateText);
+        if (candidateTokens <= maxTokens || currentLines.length === 1) {
+            // 可以合并（若只有 heading，即使超限也要接纳第一段以避免空 chunk）
+            currentLines.push(paraText);
+            lineOffset += para.lineCount;
+        }
+        else {
+            // 当前 chunk 已满，先输出当前 chunk
+            const chunkText = currentLines.join('\n').trim();
+            if (chunkText) {
+                const endLine = section.startLine + lineOffset - para.lineCount;
+                chunks.push(...splitLongText(chunkText, repoRelPath, chunkStartLine, Math.max(chunkStartLine, endLine), section.headingPath, maxTokens));
+            }
+            // 开始新 chunk
+            chunkStartLine = section.startLine + lineOffset - para.lineCount + 1;
+            currentLines = [section.headingLine, paraText];
+            lineOffset += para.lineCount;
+        }
+    }
+    // 输出最后一个 chunk
+    const remainingText = currentLines.join('\n').trim();
+    if (remainingText) {
+        chunks.push(...splitLongText(remainingText, repoRelPath, chunkStartLine, section.endLine, section.headingPath, maxTokens));
+    }
+    return chunks;
+}
+// ============================================================
+// 超长 chunk 拆分
+// ============================================================
+/**
+ * 将超长文本拆分为 ≤maxTokens 的 chunk
+ * 按行拆分，尽量在空行处断开
+ */
+function splitLongText(text, repoRelPath, startLine, endLine, headingPath, maxTokens) {
+    const tokenCount = estimateTokens(text);
+    if (tokenCount <= maxTokens) {
+        return [
+            {
+                filePath: repoRelPath,
+                startLine,
+                endLine,
+                headingPath,
+                text,
+                tokenCount,
+            },
+        ];
+    }
+    // 按行拆分
+    const lines = text.split('\n');
+    const chunks = [];
+    let currentLines = [];
+    let currentLineStart = startLine;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        currentLines.push(line);
+        const ct = estimateTokens(currentLines.join('\n'));
+        if (ct >= maxTokens && currentLines.length > 1) {
+            // 输出当前 chunk（不含最后一行）
+            const chunkLines = currentLines.slice(0, -1);
+            const chunkText = chunkLines.join('\n').trim();
+            const chunkEndLine = currentLineStart + chunkLines.length - 1;
+            if (chunkText) {
+                chunks.push({
+                    filePath: repoRelPath,
+                    startLine: currentLineStart,
+                    endLine: chunkEndLine,
+                    headingPath,
+                    text: chunkText,
+                    tokenCount: estimateTokens(chunkText),
+                });
+            }
+            currentLineStart = currentLineStart + chunkLines.length;
+            currentLines = [line];
+        }
+    }
+    // 输出剩余
+    if (currentLines.length > 0) {
+        const chunkText = currentLines.join('\n').trim();
+        if (chunkText) {
+            chunks.push({
+                filePath: repoRelPath,
+                startLine: currentLineStart,
+                endLine: endLine,
+                headingPath,
+                text: chunkText,
+                tokenCount: estimateTokens(chunkText),
+            });
+        }
+    }
+    if (chunks.length > 0) {
+        return chunks;
+    }
+    // 兜底：直接输出整块
+    return [{ filePath: repoRelPath, startLine, endLine, headingPath, text, tokenCount }];
+}
+// ============================================================
+// 工具函数
+// ============================================================
+/** 按空行将行数组分割为段落 */
+function splitIntoParagraphs(lines) {
+    const paragraphs = [];
+    let current = [];
+    let lineCount = 0;
+    for (const line of lines) {
+        if (line.trim() === '') {
+            if (current.length > 0) {
+                paragraphs.push({ lines: current, lineCount });
+                current = [];
+                lineCount = 0;
+            }
+            lineCount++;
+        }
+        else {
+            current.push(line);
+            lineCount++;
+        }
+    }
+    if (current.length > 0) {
+        paragraphs.push({ lines: current, lineCount });
+    }
+    return paragraphs;
+}
+/** 粗估 token 数：字符数 / 4（与 Local Provider 保持一致） */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/** 将绝对路径转换为 repo-relative 路径（正斜杠） */
+function toRepoRelative(absPath, projectRoot) {
+    const rel = path.isAbsolute(absPath)
+        ? path.relative(projectRoot, absPath)
+        : absPath;
+    return rel.split(path.sep).join('/');
+}
+//# sourceMappingURL=chunker.js.map

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

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

package/dist/panoramic/anchoring/edge-builder.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 语义边构建器
+ * 从 (DocChunk, CodeNode) 相似对生成 GraphEdge
+ * 边类型：references（函数名精确匹配）| conceptually_related_to（向量相似度）
+ * 不生成 rationale_for 边（仅由 LLM hyperedge 提取生成，FR-013）
+ * 去重：同一三元组 (source, target, relation) 保留 confidence 最高版本（FR-014）
+ * evidenceText：对称扩展截断算法（plan.md §9，max 200 字符）
+ */
+import type { GraphEdge } from '../graph/graph-types.js';
+import type { DocChunk } from './chunker.js';
+import type { SimilarPair } from './similarity.js';
+/**
+ * 代码节点精简信息（buildSemanticEdges 所需字段）
+ */
+export interface CodeNodeInfo {
+    /** 节点 ID（通常为文件路径或元素 ID） */
+    id: string;
+    /** 节点名称（函数名/变量名等，用于 references 边升级检测） */
+    name: string;
+}
+/**
+ * buildSemanticEdges 的输入选项
+ */
+export interface BuildEdgesOptions {
+    /** Markdown 文档 chunks */
+    chunks: DocChunk[];
+    /** 相似对（从 filterByThreshold 产出） */
+    pairs: SimilarPair[];
+    /** 代码节点信息数组（需含 id 和 name） */
+    codeNodes: CodeNodeInfo[];
+    /** 项目根目录（计算 repo-relative 路径） */
+    projectRoot: string;
+    /** evidenceText 最大字符数（默认 200） */
+    maxEvidenceLength?: number;
+}
+/**
+ * 从相似对构建语义边数组
+ * - 精确匹配函数名 → references
+ * - 向量相似度 → conceptually_related_to
+ * - 所有 embedding 生成的边 confidence 为 INFERRED
+ * - INFERRED 边若无 evidenceText 则丢弃（Risk 1 缓解）
+ * - 同一三元组去重，保留 confidence 最高版本（FR-014）
+ */
+export declare function buildSemanticEdges(options: BuildEdgesOptions): GraphEdge[];
+/**
+ * 从 chunk 文本中提取 evidenceText
+ * 规则：
+ * 1. 若 text 包含 nodeName → 从 match 位置向两侧对称扩展
+ * 2. 若无精确 match → 取 chunk 前 maxLength 字符（heading 整行保留）
+ * 3. 最终结果截断为 maxLength 字符
+ */
+export declare function buildEvidenceText(text: string, nodeName: string, maxLength?: number): string;
+//# sourceMappingURL=edge-builder.d.ts.map

package/dist/panoramic/anchoring/edge-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-builder.d.ts","sourceRoot":"","sources":["../../../src/panoramic/anchoring/edge-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,SAAS,EAAmB,MAAM,yBAAyB,CAAC;AAC1E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAMnD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,MAAM,EAAE,QAAQ,EAAE,CAAC;IACnB,kCAAkC;IAClC,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,6BAA6B;IAC7B,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAiBD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,SAAS,EAAE,CA6E1E;AAMD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,MAAY,GACtB,MAAM,CAcR"}

package/dist/panoramic/anchoring/edge-builder.js

@@ -0,0 +1,183 @@
+// ============================================================
+// Confidence 优先级（用于去重）
+// ============================================================
+/** ConfidenceLevel 的优先级（数值越大优先级越高） */
+const CONFIDENCE_PRIORITY = {
+    EXTRACTED: 3,
+    INFERRED: 2,
+    AMBIGUOUS: 1,
+};
+// ============================================================
+// 主函数
+// ============================================================
+/**
+ * 从相似对构建语义边数组
+ * - 精确匹配函数名 → references
+ * - 向量相似度 → conceptually_related_to
+ * - 所有 embedding 生成的边 confidence 为 INFERRED
+ * - INFERRED 边若无 evidenceText 则丢弃（Risk 1 缓解）
+ * - 同一三元组去重，保留 confidence 最高版本（FR-014）
+ */
+export function buildSemanticEdges(options) {
+    const { chunks, pairs, codeNodes, maxEvidenceLength = 200 } = options;
+    if (pairs.length === 0 || chunks.length === 0) {
+        return [];
+    }
+    // 构建 nodeId → CodeNodeInfo 的 Map（快速查找）
+    const nodeMap = new Map();
+    for (const node of codeNodes) {
+        nodeMap.set(node.id, node);
+    }
+    // 去重 Map：三元组 key → 候选边
+    const dedupeMap = new Map();
+    for (const pair of pairs) {
+        const chunk = chunks[pair.chunkIndex];
+        if (!chunk) {
+            continue;
+        }
+        const node = nodeMap.get(pair.nodeId);
+        if (!node) {
+            continue;
+        }
+        // 决定边类型：chunk 文本中精确包含函数名 → references；否则 → conceptually_related_to
+        const relation = containsName(chunk.text, node.name)
+            ? 'references'
+            : 'conceptually_related_to';
+        const confidence = 'INFERRED';
+        // 生成 evidenceText（对称扩展截断）
+        const evidenceText = buildEvidenceText(chunk.text, node.name, maxEvidenceLength);
+        // INFERRED 边必须有非空 evidenceText，否则丢弃（Risk 1 缓解）
+        if (!evidenceText) {
+            continue;
+        }
+        // evidenceSource 格式：repo-relative-path:startLine-endLine
+        const evidenceSource = `${chunk.filePath}:${chunk.startLine}-${chunk.endLine}`;
+        const edge = {
+            source: chunk.filePath,
+            target: node.id,
+            relation,
+            confidence,
+            confidenceScore: pair.similarity,
+            evidenceText,
+            evidenceSource,
+        };
+        // 去重 key：(source, target, relation)
+        const key = `${edge.source}||${edge.target}||${edge.relation}`;
+        const existing = dedupeMap.get(key);
+        if (!existing) {
+            dedupeMap.set(key, edge);
+        }
+        else {
+            // 保留 confidence 最高版本（FR-014）
+            const existPriority = CONFIDENCE_PRIORITY[existing.confidence] ?? 0;
+            const newPriority = CONFIDENCE_PRIORITY[edge.confidence] ?? 0;
+            if (newPriority > existPriority) {
+                dedupeMap.set(key, edge);
+            }
+            else if (newPriority === existPriority) {
+                // 同 confidence 保留 confidenceScore 较高的
+                if (edge.confidenceScore > (existing.confidenceScore ?? 0)) {
+                    dedupeMap.set(key, edge);
+                }
+            }
+        }
+    }
+    return [...dedupeMap.values()];
+}
+// ============================================================
+// evidenceText 截断算法（plan.md §9）
+// ============================================================
+/**
+ * 从 chunk 文本中提取 evidenceText
+ * 规则：
+ * 1. 若 text 包含 nodeName → 从 match 位置向两侧对称扩展
+ * 2. 若无精确 match → 取 chunk 前 maxLength 字符（heading 整行保留）
+ * 3. 最终结果截断为 maxLength 字符
+ */
+export function buildEvidenceText(text, nodeName, maxLength = 200) {
+    if (!text.trim()) {
+        return '';
+    }
+    const matchIdx = text.indexOf(nodeName);
+    if (matchIdx >= 0) {
+        // 从 match 位置向两侧对称扩展
+        return symmetricExpand(text, matchIdx, nodeName.length, maxLength);
+    }
+    else {
+        // 无精确 match：取 chunk 前 maxLength 字符
+        return truncateFromStart(text, maxLength);
+    }
+}
+/**
+ * 从 match 位置对称扩展，heading 行整行纳入
+ */
+function symmetricExpand(text, matchIdx, matchLen, maxLength) {
+    const halfWindow = Math.floor(maxLength / 2);
+    const start = Math.max(0, matchIdx - halfWindow);
+    const end = Math.min(text.length, matchIdx + matchLen + halfWindow);
+    let excerpt = text.slice(start, end);
+    // 若起始处是行中间，尝试找到行头（保留 heading 行完整）
+    if (start > 0) {
+        const lineStart = text.lastIndexOf('\n', start);
+        const lineEnd = text.indexOf('\n', start);
+        // 检查该行是否是 heading 行
+        if (lineStart >= 0 && lineEnd >= 0) {
+            const lineContent = text.slice(lineStart + 1, lineEnd);
+            if (lineContent.startsWith('##')) {
+                // heading 行：整行纳入
+                excerpt = lineContent + '\n' + text.slice(lineEnd + 1, end);
+            }
+        }
+        // 非 heading：添加省略号
+        if (!excerpt.startsWith('##')) {
+            excerpt = '...' + excerpt;
+        }
+    }
+    if (end < text.length) {
+        excerpt = excerpt + '...';
+    }
+    // 最终截断保证 ≤ maxLength
+    return excerpt.slice(0, maxLength);
+}
+/**
+ * 从文本开头截取，优先保留完整 heading 行
+ */
+function truncateFromStart(text, maxLength) {
+    if (text.length <= maxLength) {
+        return text;
+    }
+    // 若文本以 heading 开头，保留 heading 行完整
+    const firstNewline = text.indexOf('\n');
+    const firstLine = firstNewline >= 0 ? text.slice(0, firstNewline) : text;
+    if (firstLine.startsWith('##') && firstLine.length < maxLength) {
+        // 保留 heading 行，后续内容截断
+        const rest = text.slice(firstNewline + 1, maxLength - firstLine.length - 4);
+        return firstLine + '\n' + rest + '...';
+    }
+    return text.slice(0, maxLength - 3) + '...';
+}
+// ============================================================
+// 工具函数
+// ============================================================
+/**
+ * 检查文本中是否精确包含节点名称（区分大小写，整词匹配优先）
+ * 整词匹配：前后是非字母数字下划线的字符（或文本边界）
+ */
+function containsName(text, name) {
+    if (!name || !text) {
+        return false;
+    }
+    // 先做简单包含检查
+    if (!text.includes(name)) {
+        return false;
+    }
+    // 整词边界匹配（兼容中文场景，非严格）
+    const idx = text.indexOf(name);
+    const before = idx > 0 ? text[idx - 1] : ' ';
+    const after = idx + name.length < text.length ? text[idx + name.length] : ' ';
+    // 前后字符为非单词字符，或者是字符边界
+    const wordBoundaryBefore = before !== undefined && !/[a-zA-Z0-9_]/.test(before);
+    const wordBoundaryAfter = after !== undefined && !/[a-zA-Z0-9_]/.test(after);
+    return wordBoundaryBefore && wordBoundaryAfter;
+}
+//# sourceMappingURL=edge-builder.js.map

package/dist/panoramic/anchoring/edge-builder.js.map

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

package/dist/panoramic/anchoring/embedding-provider.d.ts

@@ -0,0 +1,51 @@
+/**
+ * EmbeddingProvider 接口及相关类型定义
+ * 采用 Strategy Pattern 隔离 Local/OpenAI embedding 实现
+ * tokenUsage 格式与 BudgetGate（F1）保持一致
+ */
+/**
+ * Embedding 调用的 token 使用记录
+ * - Local 模式：inputTokens 为字符数/4 粗估；outputTokens 固定为 0
+ * - OpenAI 模式：inputTokens 来自 API 响应的实际计数
+ */
+export interface EmbeddingTokenUsage {
+    /** 模型标识（'local-embedding' 或 'text-embedding-3-small'） */
+    llmModel: string;
+    /** 输入 token 数（Local 模式为粗估，OpenAI 模式为实际值） */
+    inputTokens?: number;
+    /** 输出 token 数（embedding 无输出，固定为 0） */
+    outputTokens?: number;
+    /** 推理耗时（毫秒，performance.now() 精确计时） */
+    durationMs: number;
+}
+/**
+ * EmbeddingProvider.embed() 的返回值
+ * - vectors：各输入文本对应的 embedding 向量（Float32Array 节省内存）
+ * - tokenUsage：本次调用的 token 使用记录
+ */
+export interface EmbedResult {
+    /** 各输入文本对应的 embedding 向量，顺序与输入 texts 对应 */
+    vectors: Float32Array[];
+    /** 本次 embed 调用的 token 使用记录 */
+    tokenUsage: EmbeddingTokenUsage;
+}
+/**
+ * Embedding 提供方接口
+ * 具体实现：LocalEmbeddingProvider（@huggingface/transformers）、OpenAIEmbeddingProvider
+ * 通过 providers/factory.ts 的 createEmbeddingProvider() 按环境变量选择
+ */
+export interface EmbeddingProvider {
+    /** 提供方名称（用于日志/诊断） */
+    readonly providerName: 'local' | 'openai';
+    /** LLM 模型标签（写入 tokenUsage.llmModel） */
+    readonly llmModelLabel: string;
+    /** 向量维度（Local: 384，OpenAI: 1536） */
+    readonly dimensions: number;
+    /**
+     * 批量 embed 文本
+     * @param texts 待 embed 的文本列表（非空数组）
+     * @returns EmbedResult（vectors 与 texts 顺序对应）
+     */
+    embed(texts: string[]): Promise<EmbedResult>;
+}
+//# sourceMappingURL=embedding-provider.d.ts.map

package/dist/panoramic/anchoring/embedding-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-provider.d.ts","sourceRoot":"","sources":["../../../src/panoramic/anchoring/embedding-provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,8BAA8B;IAC9B,UAAU,EAAE,mBAAmB,CAAC;CACjC;AAMD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,qBAAqB;IACrB,QAAQ,CAAC,YAAY,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC1C,uCAAuC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,oCAAoC;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAC9C"}

package/dist/panoramic/anchoring/embedding-provider.js

@@ -0,0 +1,7 @@
+/**
+ * EmbeddingProvider 接口及相关类型定义
+ * 采用 Strategy Pattern 隔离 Local/OpenAI embedding 实现
+ * tokenUsage 格式与 BudgetGate（F1）保持一致
+ */
+export {};
+//# sourceMappingURL=embedding-provider.js.map

package/dist/panoramic/anchoring/embedding-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-provider.js","sourceRoot":"","sources":["../../../src/panoramic/anchoring/embedding-provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}