spectra-cli 4.1.1

package/dist/extraction/image-extractor.js

@@ -0,0 +1,211 @@
+/**
+ * 图像/图表 Vision 提取器（Feature 107）
+ * 通过 Claude Vision API 分析图像，生成 diagram 节点（INFERRED）
+ *
+ * 三级降级路径（FR-008）：
+ * 1. ANTHROPIC_API_KEY 不存在 → 跳过全部图像，返回 EMPTY_EXTRACTION_RESULT
+ * 2. Vision API 调用失败 → 单张图片跳过，返回 EMPTY_EXTRACTION_RESULT
+ * 3. LLM 返回无法解析为 JSON → 返回 EMPTY_EXTRACTION_RESULT
+ *
+ * 安全：API key 脱敏（FR-022），日志只显示前 4 位 + ***
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import Anthropic from '@anthropic-ai/sdk';
+import { createLogger } from '../panoramic/utils/logger.js';
+import { EMPTY_EXTRACTION_RESULT } from './extraction-types.js';
+const logger = createLogger('extraction-image');
+// ============================================================
+// 常量
+// ============================================================
+/** 默认 Vision 模型（可通过 SPECTRA_VISION_MODEL 环境变量覆盖） */
+const DEFAULT_VISION_MODEL = 'claude-sonnet-4-5';
+/** 文件大小上限：10 MB（FR-009） */
+const MAX_FILE_SIZE_BYTES = 10 * 1024 * 1024;
+/** 支持的二进制图像格式（可转换为 base64 传入 Vision API） */
+const BINARY_IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg']);
+/** SVG 以文本方式处理（不转 base64） */
+const SVG_EXTENSION = '.svg';
+// ============================================================
+// API key 脱敏（FR-022）
+// ============================================================
+/**
+ * 脱敏 API key，仅显示前 4 位 + ***
+ */
+function maskApiKey(key) {
+    if (!key || key.length < 4)
+        return '****';
+    return key.slice(0, 4) + '***';
+}
+// ============================================================
+// Vision API 调用
+// ============================================================
+/** Vision 提取 system prompt */
+const VISION_SYSTEM_PROMPT = `你是一个结构化信息提取器，专门分析软件工程图表。
+请分析提供的图像，提取图中的组件、关系和描述。
+
+以 JSON 格式返回：
+{
+  "description": "图表的简短描述（一句话）",
+  "components": ["组件1", "组件2", "组件3"]
+}
+
+只返回 JSON，不添加其他内容。`;
+/**
+ * 调用 Vision API 分析图像
+ *
+ * @param client - Anthropic 客户端
+ * @param imageContent - 图像内容（base64 字符串或 SVG 文本）
+ * @param mediaType - MIME 类型
+ * @param isSvg - 是否为 SVG 文本
+ * @param model - 使用的模型
+ * @returns 解析结果或 null（降级）
+ */
+async function callVisionApi(client, imageContent, mediaType, isSvg, model) {
+    const messageContent = isSvg
+        ? `以下是一个 SVG 图表的内容：\n\n${imageContent}\n\n请分析此图表。`
+        : [
+            {
+                type: 'image',
+                source: {
+                    type: 'base64',
+                    media_type: mediaType,
+                    data: imageContent,
+                },
+            },
+        ];
+    const response = await client.messages.create({
+        model,
+        max_tokens: 1024,
+        system: VISION_SYSTEM_PROMPT,
+        messages: [
+            {
+                role: 'user',
+                content: messageContent,
+            },
+        ],
+    });
+    const textContent = response.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('\n');
+    if (!textContent)
+        return null;
+    // 解析 JSON
+    try {
+        const codeBlockMatch = textContent.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+        const jsonStr = codeBlockMatch ? codeBlockMatch[1] : textContent;
+        const parsed = JSON.parse(jsonStr.trim());
+        if (typeof parsed.description !== 'string')
+            return null;
+        return {
+            description: parsed.description,
+            components: Array.isArray(parsed.components) ? parsed.components : [],
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================
+// 公开 API
+// ============================================================
+/**
+ * 从单个图像文件提取节点和边
+ *
+ * @param filePath - 图像文件绝对路径
+ * @param options - 提取器选项
+ * @returns ExtractionResult（不抛出异常，失败时返回 EMPTY_EXTRACTION_RESULT）
+ */
+export async function extractImage(filePath, options) {
+    const ext = path.extname(filePath).toLowerCase();
+    // 格式过滤：只支持 PNG/JPG/JPEG/SVG
+    if (!BINARY_IMAGE_EXTENSIONS.has(ext) && ext !== SVG_EXTENSION) {
+        logger.debug(`不支持的图像格式，跳过: ${filePath}`);
+        return EMPTY_EXTRACTION_RESULT;
+    }
+    // 降级级别 1：API key 检查（FR-022 脱敏）
+    const apiKey = process.env['ANTHROPIC_API_KEY'];
+    if (!apiKey || !apiKey.trim()) {
+        logger.info('ANTHROPIC_API_KEY 未设置，跳过图像提取（Vision API 不可用）');
+        return EMPTY_EXTRACTION_RESULT;
+    }
+    // 文件大小检查（FR-009）
+    try {
+        const stat = fs.statSync(filePath);
+        if (stat.size > MAX_FILE_SIZE_BYTES) {
+            const sizeMB = (stat.size / (1024 * 1024)).toFixed(1);
+            logger.warn(`图像文件过大（${sizeMB} MB），跳过: ${filePath}`);
+            return EMPTY_EXTRACTION_RESULT;
+        }
+    }
+    catch (err) {
+        logger.warn(`无法读取文件信息，跳过: ${filePath} — ${String(err)}`);
+        return EMPTY_EXTRACTION_RESULT;
+    }
+    // 计算相对路径
+    const relPath = path.relative(options.projectRoot, filePath).replace(/\\/g, '/');
+    const nodeId = `diagram:${relPath}`;
+    // 读取文件内容
+    let imageContent;
+    let mediaType;
+    const isSvg = ext === SVG_EXTENSION;
+    try {
+        if (isSvg) {
+            // SVG 以文本方式读取
+            imageContent = fs.readFileSync(filePath, 'utf-8');
+            mediaType = 'image/svg+xml';
+        }
+        else {
+            // 二进制图像转 base64
+            const buffer = fs.readFileSync(filePath);
+            imageContent = buffer.toString('base64');
+            mediaType = ext === '.png' ? 'image/png' : 'image/jpeg';
+        }
+    }
+    catch (err) {
+        logger.warn(`读取图像文件失败: ${filePath} — ${String(err)}`);
+        return EMPTY_EXTRACTION_RESULT;
+    }
+    // 构建 Anthropic 客户端
+    const model = process.env['SPECTRA_VISION_MODEL'] ?? DEFAULT_VISION_MODEL;
+    const client = options.anthropicClientFactory
+        ? options.anthropicClientFactory(apiKey)
+        : new Anthropic({ apiKey });
+    // 降级级别 2/3：Vision API 调用 + JSON 解析
+    let visionResult;
+    try {
+        visionResult = await callVisionApi(client, imageContent, mediaType, isSvg, model);
+    }
+    catch (err) {
+        // 降级级别 2：API 调用失败
+        logger.warn(`Vision API 调用失败，跳过: ${filePath} — ${String(err)}`);
+        return EMPTY_EXTRACTION_RESULT;
+    }
+    // 降级级别 3：解析失败
+    if (!visionResult) {
+        logger.debug(`Vision 返回内容无法解析为 JSON，跳过: ${filePath}`);
+        return EMPTY_EXTRACTION_RESULT;
+    }
+    // 构建 diagram 节点
+    const nodes = [
+        {
+            id: nodeId,
+            label: visionResult.description || path.basename(filePath),
+            kind: 'diagram',
+            source_file: filePath,
+            confidence: 'INFERRED',
+            metadata: {
+                description: visionResult.description,
+                components: visionResult.components,
+                model,
+                apiKeyMasked: maskApiKey(apiKey),
+            },
+        },
+    ];
+    // depicts 边已移除：Vision API 返回的组件名（自由文本）无法与图谱节点 ID 对应，
+    // 生成的边会因 source/target 不存在而被 graph-builder 静默过滤。
+    // 识别到的组件名保留在 diagram 节点的 metadata.components 字段中。
+    return { nodes, edges: [] };
+}
+//# sourceMappingURL=image-extractor.js.map

package/dist/extraction/image-extractor.js.map

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

package/dist/extraction/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 多模态提取模块公开 API（Feature 107）
+ * 导出 runExtractionPipeline 函数及关键类型
+ */
+export { runExtractionPipeline, findReadmePath } from './extraction-pipeline.js';
+export type { ExtractionPipelineOptions, ExtractionPipelineOutput } from './extraction-pipeline.js';
+export type { ExtractionResult, ExtractedNode, ExtractedEdge, ArtifactKind, ExtractedNodeKind, } from './extraction-types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/extraction/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/extraction/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AACjF,YAAY,EAAE,yBAAyB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAEpG,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,iBAAiB,GAClB,MAAM,uBAAuB,CAAC"}

package/dist/extraction/index.js

@@ -0,0 +1,6 @@
+/**
+ * 多模态提取模块公开 API（Feature 107）
+ * 导出 runExtractionPipeline 函数及关键类型
+ */
+export { runExtractionPipeline, findReadmePath } from './extraction-pipeline.js';
+//# sourceMappingURL=index.js.map

package/dist/extraction/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/extraction/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/extraction/markdown-extractor.d.ts

@@ -0,0 +1,11 @@
+import type { ExtractionResult } from './extraction-types.js';
+/**
+ * 提取单个 Markdown 文件的节点和边
+ *
+ * @param filePath - 文件绝对路径
+ * @param content - 文件内容
+ * @param projectRoot - 项目根目录（计算相对路径）
+ * @returns ExtractionResult（不抛出异常，失败时降级为 EMPTY_EXTRACTION_RESULT）
+ */
+export declare function extractMarkdown(filePath: string, content: string, projectRoot: string): Promise<ExtractionResult>;
+//# sourceMappingURL=markdown-extractor.d.ts.map

package/dist/extraction/markdown-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-extractor.d.ts","sourceRoot":"","sources":["../../src/extraction/markdown-extractor.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,gBAAgB,EAAgC,MAAM,uBAAuB,CAAC;AAwL5F;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAuD3B"}

package/dist/extraction/markdown-extractor.js

@@ -0,0 +1,212 @@
+/**
+ * Markdown 文档提取器（Feature 107）
+ * 两阶段提取：
+ * 1. 确定性提取（无 LLM）：标题树 + frontmatter 解析 → document 节点（EXTRACTED）
+ * 2. LLM 实体提取（可选）：命名实体 + 决策段落 → 丰富 document metadata（INFERRED）
+ * 3. 文件路径引用检测：反引号内文件路径 → references 边（INFERRED）
+ */
+import * as path from 'node:path';
+import { createLogger } from '../panoramic/utils/logger.js';
+import { callLLM } from '../panoramic/utils/llm-facade.js';
+import { EMPTY_EXTRACTION_RESULT } from './extraction-types.js';
+const logger = createLogger('extraction-markdown');
+/**
+ * 解析 YAML frontmatter（--- 分隔块）
+ * 仅支持一级 key: value 形式，足够覆盖 Markdown 文档的常见字段
+ */
+function parseFrontmatter(content) {
+    if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) {
+        return { frontmatter: {}, body: content };
+    }
+    const lines = content.split('\n');
+    let endIdx = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i]?.trimEnd() === '---') {
+            endIdx = i;
+            break;
+        }
+    }
+    if (endIdx === -1) {
+        return { frontmatter: {}, body: content };
+    }
+    const frontmatterLines = lines.slice(1, endIdx);
+    const body = lines.slice(endIdx + 1).join('\n').trimStart();
+    const frontmatter = {};
+    for (const line of frontmatterLines) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        const value = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
+        if (key)
+            frontmatter[key] = value;
+    }
+    return { frontmatter, body };
+}
+/**
+ * 从 Markdown body 提取标题列表
+ * 识别 ATX 标题（# / ## / ###）
+ */
+function extractHeadings(body) {
+    const headings = [];
+    const lines = body.split('\n');
+    for (const line of lines) {
+        const match = /^(#{1,6})\s+(.+)$/.exec(line.trimEnd());
+        if (match && match[1] && match[2]) {
+            headings.push({ level: match[1].length, text: match[2].trim() });
+        }
+    }
+    return headings;
+}
+// ============================================================
+// 文件路径引用检测
+// ============================================================
+/** 匹配反引号内的路径（如 `src/auth/auth.ts`） */
+const FILE_PATH_PATTERN = /`([^`]*(?:\/[^`]*)+\.[a-zA-Z0-9]+)`/g;
+/**
+ * 扫描 Markdown body 中的文件路径引用
+ * 生成 references 边（INFERRED）
+ *
+ * @param body - Markdown body 内容
+ * @param sourceNodeId - 来源文档节点 ID
+ * @returns 检测到的 references 边列表
+ */
+function detectFileReferences(body, sourceNodeId) {
+    const edges = [];
+    const seen = new Set();
+    let match;
+    FILE_PATH_PATTERN.lastIndex = 0;
+    while ((match = FILE_PATH_PATTERN.exec(body)) !== null) {
+        const filePath = match[1].trim();
+        // 过滤掉看起来不像代码文件路径的内容
+        if (filePath.length < 5 || seen.has(filePath))
+            continue;
+        seen.add(filePath);
+        // 生成模块 ID（使用 posix 格式）
+        const targetId = `module:${filePath.replace(/\\/g, '/')}`;
+        edges.push({
+            source: sourceNodeId,
+            target: targetId,
+            relation: 'references',
+            confidence: 'INFERRED',
+            weight: 1.0,
+        });
+    }
+    return edges;
+}
+// ============================================================
+// LLM 实体提取
+// ============================================================
+/** LLM 实体提取 system prompt */
+const ENTITY_EXTRACTION_SYSTEM_PROMPT = `你是一个结构化信息提取器。请从提供的 Markdown 文档中提取关键信息。
+
+请以 JSON 格式返回，格式如下：
+{
+  "concepts": ["概念1", "概念2"],
+  "decisions": ["决策描述1", "决策描述2"]
+}
+
+规则：
+- concepts：文档中提到的核心技术概念、组件名称、服务名称（最多 10 个）
+- decisions：文档中记录的设计决策或架构决定（最多 5 个）
+- 如果没有相关内容，对应字段返回空数组
+- 只返回 JSON，不添加其他内容`;
+/**
+ * 调用 LLM 提取文档实体
+ * 失败时返回 null（调用方降级处理）
+ */
+async function extractEntitiesWithLLM(body) {
+    // 限制输入长度（约 8000 token ≈ 24000 字符）
+    const truncatedBody = body.length > 24000 ? body.slice(0, 24000) + '\n...[内容过长已截断]' : body;
+    let response;
+    try {
+        response = await callLLM(truncatedBody, {
+            systemPrompt: ENTITY_EXTRACTION_SYSTEM_PROMPT,
+            maxTokens: 1024,
+            timeout: 8000, // FR-016：超时 8 秒
+            temperature: 0.1,
+        });
+    }
+    catch (err) {
+        logger.debug(`LLM 实体提取调用失败: ${String(err)}`);
+        return null;
+    }
+    if (!response)
+        return null;
+    // 尝试解析 JSON
+    try {
+        // 尝试从 markdown 代码块中提取
+        const codeBlockMatch = response.match(/```(?:json)?\s*\n?([\s\S]*?)```/);
+        const jsonStr = codeBlockMatch ? codeBlockMatch[1] : response;
+        const parsed = JSON.parse(jsonStr.trim());
+        if (!Array.isArray(parsed.concepts) || !Array.isArray(parsed.decisions)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        logger.debug('LLM 返回内容无法解析为 JSON，跳过 LLM 实体提取');
+        return null;
+    }
+}
+// ============================================================
+// 公开 API
+// ============================================================
+/**
+ * 提取单个 Markdown 文件的节点和边
+ *
+ * @param filePath - 文件绝对路径
+ * @param content - 文件内容
+ * @param projectRoot - 项目根目录（计算相对路径）
+ * @returns ExtractionResult（不抛出异常，失败时降级为 EMPTY_EXTRACTION_RESULT）
+ */
+export async function extractMarkdown(filePath, content, projectRoot) {
+    try {
+        const relPath = path.relative(projectRoot, filePath).replace(/\\/g, '/');
+        const nodeId = `doc:${relPath}`;
+        // 第一步：确定性提取（frontmatter + 标题树）
+        const { frontmatter, body } = parseFrontmatter(content);
+        const headings = extractHeadings(body);
+        // 文档标题：优先使用 frontmatter.title，其次 H1 标题，最后用文件名
+        const title = (typeof frontmatter.title === 'string' ? frontmatter.title : '') ||
+            headings.find((h) => h.level === 1)?.text ||
+            path.basename(filePath, path.extname(filePath));
+        const docNode = {
+            id: nodeId,
+            label: title,
+            kind: 'document',
+            source_file: filePath,
+            confidence: 'EXTRACTED',
+            metadata: {
+                frontmatter,
+                headings: headings.map((h) => `${'#'.repeat(h.level)} ${h.text}`),
+            },
+        };
+        const nodes = [docNode];
+        const edges = [];
+        // 第二步：文件路径引用检测 → references 边
+        const refEdges = detectFileReferences(body, nodeId);
+        edges.push(...refEdges);
+        // 第三步：LLM 实体提取（可选，失败不影响确定性结果）
+        if (body.trim().length > 0) {
+            const llmResult = await extractEntitiesWithLLM(body).catch(() => null);
+            if (llmResult) {
+                // 将 LLM 提取结果追加到 metadata
+                docNode.metadata = {
+                    ...docNode.metadata,
+                    concepts: llmResult.concepts,
+                    decisions: llmResult.decisions,
+                    llmEnriched: true,
+                };
+                // FR-003：LLM 富化后整体节点标注 INFERRED，不允许标记为 EXTRACTED
+                docNode.confidence = 'INFERRED';
+            }
+        }
+        return { nodes, edges };
+    }
+    catch (err) {
+        logger.warn(`Markdown 提取失败: ${filePath} — ${String(err)}`);
+        return EMPTY_EXTRACTION_RESULT;
+    }
+}
+//# sourceMappingURL=markdown-extractor.js.map

package/dist/extraction/markdown-extractor.js.map

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

package/dist/extraction/openapi-extractor.d.ts

@@ -0,0 +1,10 @@
+import type { ExtractionResult } from './extraction-types.js';
+/**
+ * 从单个 OpenAPI/AsyncAPI 文件提取节点和边
+ *
+ * @param filePath - 文件绝对路径
+ * @param projectRoot - 项目根目录（用于计算相对路径）
+ * @returns ExtractionResult（降级时返回 EMPTY_EXTRACTION_RESULT）
+ */
+export declare function extractOpenApi(filePath: string, projectRoot: string): ExtractionResult;
+//# sourceMappingURL=openapi-extractor.d.ts.map

package/dist/extraction/openapi-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi-extractor.d.ts","sourceRoot":"","sources":["../../src/extraction/openapi-extractor.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,gBAAgB,EAAgC,MAAM,uBAAuB,CAAC;AAoZ5F;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAiEtF"}