spectra-cli 4.1.1 → 4.3.0

package/dist/batch/batch-orchestrator.js

@@ -8,7 +8,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import pLimit from 'p-limit';
 import { findReadmePath } from '../extraction/index.js';
-import { buildGraph } from '../graph/dependency-graph.js';
+import { buildModuleGraphForProject } from '../knowledge-graph/module-derivation.js';
 import { generateSpec } from '../core/single-spec-orchestrator.js';
 import { generateIndex } from '../generator/index-generator.js';
 import { renderIndex, initRenderer } from '../generator/spec-renderer.js';
@@ -20,10 +20,11 @@ import { estimateModuleCost, buildDryRunReport, renderDryRunReport, runBudgetGat
 import { decideModelOverride } from './model-override-decision.js';
 import { createLogger } from '../panoramic/utils/logger.js';
 import { groupFilesToModules } from './module-grouper.js';
+import { buildSpecCacheKey, normalizeProjectPath, resolveRegenPlan, resolveSourceTarget } from './regen-plan.js';
 import { groupFilesByLanguage } from './language-grouper.js';
-import { scanFiles } from '../utils/file-scanner.js';
+import { scanFiles, createGitignoreFilter } from '../utils/file-scanner.js';
 import { LanguageAdapterRegistry } from '../adapters/language-adapter-registry.js';
-import { buildDocGraph, runAnchorIntegration, runHyperedgeIntegration, scanStoredModuleSpecs, } from '../panoramic/builders/doc-graph-builder.js';
+import { buildDocGraph, isBatchGenerated, runAnchorIntegration, runHyperedgeIntegration, scanStoredModuleSpecs, } from '../panoramic/builders/doc-graph-builder.js';
 import { chunkMarkdownFiles } from '../panoramic/anchoring/chunker.js';
 import { createEmbeddingProvider } from '../panoramic/anchoring/providers/factory.js';
 import { DOC_NODE_KINDS } from '../panoramic/hyperedges/constants.js';
@@ -37,10 +38,13 @@ import { detectAuth } from '../auth/auth-detector.js';
 import { orchestrateDocsBundle } from '../panoramic/pipelines/docs-bundle-orchestrator.js';
 import { generateDebtIntelligence, } from '../panoramic/pipelines/debt-intelligence-pipeline.js';
 import { BATCH_OUTPUT_SUBDIRS } from '../panoramic/output-filenames.js';
-import { buildKnowledgeGraph, writeKnowledgeGraph } from '../panoramic/graph/index.js';
+import { buildKnowledgeGraph, writeKnowledgeGraph, normalizeGraphForWrite } from '../panoramic/graph/index.js';
+import { buildUnifiedGraph, setCurrentUnifiedGraph, getCurrentUnifiedGraph, } from '../knowledge-graph/index.js';
 import { buildHtmlTemplate } from '../panoramic/exporters/html-template.js';
 import { SpecStore } from '../spec-store/index.js';
 import { createRequire } from 'node:module';
+import { resolvePythonImport } from '../knowledge-graph/import-resolver.js';
+import { resolveTsJsImport, findNearestTsConfig, buildTsConfigContext, } from '../core/import-resolver.js';
 // 从 package.json 读取版本号（避免硬编码）
 const _require = createRequire(import.meta.url);
 const SPECTRA_VERSION = _require('../../package.json').version;
@@ -63,7 +67,40 @@ const logger = createLogger('batch-orchestrator');
 // 内部辅助函数
 // ============================================================
 /**
- * 合并多个语言的 DependencyGraph 用于全局拓扑排序
+ * Feature 182 修复面 4：checkpoint replace 语义（completed/failed 互斥去重）。
+ *
+ * 背景：F175 给 checkpoint 加了「mustRegen 失效重跑」（fall-through）语义，但 completedModules
+ * 仍沿用 append-only 写法——已完成 module 被重跑后会二次 push，导致 resume 进度超 totalModules，
+ * 且 completed / failed 可能交叉污染（同一 module 同时出现在两个集合）。
+ *
+ * 本 helper 以 path 为身份键先剔除两个集合中的同名旧条目，再 push 到目标集合，保证：
+ *   (1) 同一 module 在每个集合最多出现一次；(2) completed 与 failed 互斥。
+ *
+ * 注意：helper 内不得有 await——JS 单线程下同步段不被 pLimit 并发交错，
+ * 保持纯同步可防未来插入 await 后语义退化为「读-改-写」竞态。
+ */
+function upsertCompletedModule(state, entry) {
+    state.completedModules = state.completedModules.filter((m) => m.path !== entry.path);
+    state.failedModules = state.failedModules.filter((m) => m.path !== entry.path);
+    state.completedModules.push(entry);
+}
+function recordFailedModule(state, entry) {
+    state.failedModules = state.failedModules.filter((m) => m.path !== entry.path);
+    state.completedModules = state.completedModules.filter((m) => m.path !== entry.path);
+    state.failedModules.push(entry);
+}
+/**
+ * F175 FR-017/EC-009：判定 absPath 是否位于受管 modules/ 输出目录内（孤儿删除 ownership 必要条件2）。
+ *
+ * 用 path.relative 判定目录归属，禁用字符串 startsWith——否则 `specs/modules-old/...` 这类
+ * sibling 目录会被前缀匹配误判为受管目录（目录穿越）。同时校验 .spec.md 后缀。
+ */
+function isInManagedOutputDir(absPath, modulesDir) {
+    const rel = path.relative(modulesDir, path.resolve(absPath));
+    return !rel.startsWith('..') && !path.isAbsolute(rel) && absPath.endsWith('.spec.md');
+}
+/**
+ * 合并多个语言的 ModuleGraph 用于全局拓扑排序
  * 仅合并 modules 和 edges，SCC/Mermaid 按语言独立保留（TD-002 选项 C）
  */
 export function mergeGraphsForTopologicalSort(graphs, projectRoot) {
@@ -170,7 +207,14 @@ export async function runBatch(projectRoot, options = {}) {
     const effectiveMode = options.mode ?? 'full';
     // F5：FR-006 — 日志输出当前 mode
     logger.info(`[info] batch mode: ${effectiveMode}`);
-    const { force = false, incremental = false, maxRetries = 3, outputDir = 'specs', } = options;
+    const { maxRetries = 3, outputDir = 'specs', } = options;
+    // F175 FR-002：唯一默认值来源——对直接调用方兜底解析 RegenPlan（CLI/MCP 已在各自入口解析后传入有效值）。
+    // 删除原 `incremental = false` 硬编码，默认增量（regenPlan.incremental）由 resolveRegenPlan 决定（FR-001）。
+    const regenPlan = resolveRegenPlan({
+        incremental: options.incremental,
+        full: options.full,
+        force: options.force,
+    });
     const startTime = Date.now();
     const resolvedRoot = path.resolve(projectRoot);
     const resolvedOutputDir = path.isAbsolute(outputDir)
@@ -185,7 +229,6 @@ export async function runBatch(projectRoot, options = {}) {
         const rel = path.relative(resolvedRoot, absPath);
         return rel.startsWith('..') ? absPath : rel;
     };
-    const normalizeProjectPath = (inputPath) => inputPath.split(path.sep).join('/');
     // 步骤 1：扫描文件获取 languageStats
     const scanResult = scanFiles(resolvedRoot, { projectRoot: resolvedRoot });
     const languageStats = scanResult.languageStats;
@@ -214,14 +257,14 @@ export async function runBatch(projectRoot, options = {}) {
         // 步骤 1.7：合并拓扑排序
         mergedGraph = perLangGraphs.length > 0
             ? mergeGraphsForTopologicalSort(perLangGraphs, resolvedRoot)
-            : await buildGraph(resolvedRoot);
+            : await buildModuleGraphForProject(resolvedRoot);
     }
     else if (isSingleNonTsJs && languageGroupsList[0]) {
         mergedGraph = await buildGraphForLanguageGroup(languageGroupsList[0], resolvedRoot);
     }
     else {
-        // 纯 TS/JS 或未识别受支持语言：保持 dependency-cruiser 现有路径
-        mergedGraph = await buildGraph(resolvedRoot);
+        // 纯 TS/JS 或未识别受支持语言：走 UnifiedGraph 派生路径（Feature 156 删除 dependency-cruiser）
+        mergedGraph = await buildModuleGraphForProject(resolvedRoot);
     }
     // 步骤 2：文件→模块聚合 + 模块级拓扑排序
     const groupingOptions = {
@@ -235,42 +278,34 @@ export async function runBatch(projectRoot, options = {}) {
     const moduleGroups = new Map(groupResult.groups.map((g) => [g.name, g]));
     const rootModuleName = options.grouping?.rootModuleName ?? 'root';
     const existingStoredSpecs = scanStoredModuleSpecs(resolvedOutputDir, resolvedRoot);
-    const storedSpecByTarget = new Map(existingStoredSpecs.map((spec) => [spec.sourceTarget, spec]));
+    // Feature 182：以 cache key 入索引（languageSplit 组带 `::language` 后缀），与 processOneModule
+    // 的 moduleCacheKey 口径对齐；旧 spec 无 sourceTargetKey 时回落纯路径 sourceTarget。
+    const storedSpecByTarget = new Map(existingStoredSpecs.map((spec) => [spec.sourceTargetKey ?? spec.sourceTarget, spec]));
+    // F175：全量逃生口（--full / --force 合并为 regenPlan.full）打可观测日志，
+    // 替代原 fallbackReason='force-enabled' 内部信号（W-1 取舍）。
+    if (regenPlan.full) {
+        logger.info(`[regen] full regeneration (source=${regenPlan.source})`);
+    }
+    // F175：仅增量路径（regenPlan.incremental）调用 DeltaRegenerator；full 路径直接走全量。
     let deltaReport;
-    if (incremental) {
-        if (force) {
-            deltaReport = {
-                title: 'Delta Regeneration Report',
-                generatedAt: new Date().toISOString(),
-                projectRoot: resolvedRoot,
-                mode: 'full',
-                totalTargets: groupResult.groups.reduce((sum, group) => {
-                    const isRootGroup = group.name === rootModuleName || group.name.startsWith(`${rootModuleName}--`);
-                    return sum + (isRootGroup ? group.files.length : 1);
-                }, 0),
-                regenerateTargets: [],
-                directChanges: [],
-                propagatedChanges: [],
-                unchangedTargets: [],
-                fallbackReason: 'force-enabled',
-            };
-        }
-        else {
-            const deltaRegenerator = new DeltaRegenerator();
-            deltaReport = await deltaRegenerator.plan({
-                projectRoot: resolvedRoot,
-                dependencyGraph: mergedGraph,
-                moduleGroups: groupResult.groups,
-                storedSpecs: existingStoredSpecs,
-                // Bug 142：传入 effectiveMode 启用 mode-aware cache，
-                // 旧 spec（无 generatedByMode）或 mode 不匹配时强制 cache miss。
-                effectiveMode,
-            });
-        }
+    if (regenPlan.incremental) {
+        const deltaRegenerator = new DeltaRegenerator();
+        deltaReport = await deltaRegenerator.plan({
+            projectRoot: resolvedRoot,
+            dependencyGraph: mergedGraph,
+            moduleGroups: groupResult.groups,
+            storedSpecs: existingStoredSpecs,
+            // Bug 142：传入 effectiveMode 启用 mode-aware cache，
+            // 旧 spec（无 generatedByMode）或 mode 不匹配时强制 cache miss。
+            effectiveMode,
+        });
     }
     const regenerateTargets = new Set(deltaReport?.regenerateTargets ?? []);
-    const forceFullRegeneration = force || (incremental && deltaReport?.mode === 'full');
-    const shouldUseIncrementalPlan = incremental && !force && deltaReport?.mode === 'incremental';
+    // EC-001 force/full 优先：regenPlan.full 直接全量；增量路径 deltaReport.mode==='full'
+    //（首次运行 / 无历史 spec / mode 切换）退化全量仍走 forceFullRegeneration。
+    // Feature 182：改为 let——full-resume 时序修复需在 checkpoint 加载后回写（见下方 isResume 块）。
+    let forceFullRegeneration = regenPlan.full || (regenPlan.incremental && deltaReport?.mode === 'full');
+    let shouldUseIncrementalPlan = regenPlan.incremental && deltaReport?.mode === 'incremental';
     console.log(`发现 ${mergedGraph.modules.length} 个文件，聚合为 ${processingOrder.length} 个模块`);
     if (isMultiLang) {
         console.log(`检测到 ${processedLanguages.length} 种语言: ${processedLanguages.join(', ')}`);
@@ -361,6 +396,18 @@ export async function runBatch(projectRoot, options = {}) {
     }
     // 步骤 3：检查是否存在检查点
     let state = loadCheckpoint(checkpointPath);
+    // F175 FR-016/EC-007：full/force 启动时丢弃已加载的 checkpoint completed + failed state，
+    // 防止残留 checkpoint 命中导致全量语义被绕过（必须在 completedPaths 构建前清空——
+    // 加载时即清，而非在 processOneModule 内"忽略"，避免中途崩溃 resume 复用脏 set）。
+    // W-1：必须同时清空 failedModules——否则 full 后 summary（:1749 起用 checkedState.failedModules）
+    // 仍混入上一轮的旧失败详情，与"full 是干净全量"语义矛盾。
+    if (state &&
+        regenPlan.full &&
+        (state.completedModules.length > 0 || state.failedModules.length > 0)) {
+        logger.info(`[regen] full regeneration 丢弃残留 checkpoint state（completed ${state.completedModules.length} / failed ${state.failedModules.length} 模块）`);
+        state = { ...state, completedModules: [], failedModules: [] };
+        saveCheckpoint(state, checkpointPath);
+    }
     const isResume = state !== null;
     if (!state) {
         state = {
@@ -372,7 +419,7 @@ export async function runBatch(projectRoot, options = {}) {
             processingOrder,
             completedModules: [],
             failedModules: [],
-            forceRegenerate: force,
+            forceRegenerate: regenPlan.full,
             // 多语言扩展字段
             languageGroups: isMultiLang
                 ? Object.fromEntries(languageGroupsList.map((g) => [g.adapterId, g.files]))
@@ -382,6 +429,17 @@ export async function runBatch(projectRoot, options = {}) {
     }
     if (isResume) {
         console.log(`恢复断点: 已完成 ${state.completedModules.length}/${state.totalModules} 模块`);
+        // Feature 182 修复面 5：恢复中断的 --full run 意图。
+        // 背景：首轮 --full 把 forceRegenerate=true 落盘到 checkpoint（:660），但 runtime 仅用本轮
+        // regenPlan 重算的 forceFullRegeneration——裸增量 resume 时为 false，剩余模块静默降级为增量，
+        // 产出半新半旧混合产物。此处从 checkpoint 恢复 full 意图，剩余模块继续全量。
+        // 时序安全：两变量消费点全在 processOneModule 内（在此回写之后才被调用）。
+        // 注意：full-resume 不清空 completed（:636 清空条件用 regenPlan.full 而非本变量），正是 resume 语义。
+        if (state.forceRegenerate && !forceFullRegeneration) {
+            forceFullRegeneration = true;
+            shouldUseIncrementalPlan = false;
+            logger.info('[resume] 检测到中断的 full run，剩余模块继续全量');
+        }
     }
     // 步骤 4：按模块级拓扑顺序处理
     // Feature 146 FR-010/FR-011：通过 getActiveCount getter 注入 limit.activeCount，
@@ -441,16 +499,30 @@ export async function runBatch(projectRoot, options = {}) {
         const group = moduleGroups.get(moduleName);
         if (!group)
             return;
-        if (completedPaths.has(moduleName))
-            return;
         const isRoot = moduleName === rootModuleName || moduleName.startsWith(`${rootModuleName}--`);
         const specPath = path.join(modulesDir, `${moduleName}.spec.md`);
-        // H4 修复：文件级降级场景下 moduleSourceTarget 须与 targetPath 保持一致（文件路径）
-        // 否则 --incremental 的 regenerateTargets 查询和 storedSpecByTarget 查询全部错位
-        const hasDirPathConflict = !isRoot && group.files.length === 1 && conflictingDirPaths.has(group.dirPath);
-        const moduleSourceTarget = hasDirPathConflict
-            ? normalizeProjectPath(group.files[0])
-            : normalizeProjectPath(group.dirPath);
+        // FR-019：target 口径与 DeltaRegenerator 共用 resolveSourceTarget（文件级降级分支一致），
+        // 否则 --incremental 的 regenerateTargets 查询和 storedSpecByTarget 查询全部错位。
+        // T020：target 计算前移到 checkpoint 判定之前，供增量 resume 失效判定使用。
+        const moduleSourceTarget = resolveSourceTarget(group, conflictingDirPaths, isRoot);
+        // Feature 182：cache key（languageSplit 组带 `::language` 后缀），用于 regenerateTargets /
+        // storedSpecByTarget / existingVersion 查询，消除同目录多语言组键碰撞；targetPath 与
+        // frontmatter 继续用纯路径 moduleSourceTarget（statSync 路径 + panoramic 匹配口径不变）。
+        const moduleCacheKey = buildSpecCacheKey(moduleSourceTarget, group);
+        // F175 FR-016：checkpoint 判定。full 路径已在加载时清空 completedPaths（必为干净）；
+        // 增量 resume 下若 checkpoint 命中但本轮 delta 要求重生成该 target，则失效重跑。
+        // C-3：root 模块的 regenerateTargets 是文件级（DeltaRegenerator 对 root 按每个文件
+        // 产出 snapshot），但 moduleSourceTarget（root 时为 group.dirPath）不在文件级集合里，
+        // 用 dirPath 查永远 miss → mustRegen=false → root 文件变更时 checkpoint 命中被错误跳过。
+        // 故 root 模块改判 group.files 中任一文件 target 是否命中 regenerateTargets。
+        if (completedPaths.has(moduleName)) {
+            const mustRegen = shouldUseIncrementalPlan &&
+                (isRoot
+                    ? group.files.some((filePath) => regenerateTargets.has(normalizeProjectPath(filePath)))
+                    : regenerateTargets.has(moduleCacheKey));
+            if (!mustRegen)
+                return;
+        }
         const rootTargetsToGenerate = isRoot
             ? group.files
                 .map((filePath) => normalizeProjectPath(filePath))
@@ -473,7 +545,7 @@ export async function runBatch(projectRoot, options = {}) {
         else {
             const shouldGenerate = forceFullRegeneration
                 || (shouldUseIncrementalPlan
-                    ? regenerateTargets.has(moduleSourceTarget)
+                    ? regenerateTargets.has(moduleCacheKey)
                     : !fs.existsSync(specPath));
             if (!shouldGenerate) {
                 skipped.push(moduleName);
@@ -587,24 +659,32 @@ export async function runBatch(projectRoot, options = {}) {
                     }
                     successful.push(moduleName);
                     reporter.complete(moduleName, 'success');
-                    checkedState.completedModules.push({
+                    // Feature 182：replace 语义（失效重跑时去重 + completed/failed 互斥）
+                    upsertCompletedModule(checkedState, {
                         path: moduleName,
                         specPath: generatedRootSpecs[0],
                         completedAt: new Date().toISOString(),
                     });
                 }
                 else {
-                    // BUG-A 修复：同一 dirPath 下有多个单文件模块时（如 graphify/ 下有 a.py/b.py），
-                    // 使用文件路径避免多个模块覆盖同一个 {dirName}.spec.md；
-                    // 否则仍使用目录路径（每个目录只有一个文件时，目录名才是有意义的模块标识）
-                    // 注意：hasDirPathConflict 已在上方计算（H4 修复）
-                    const targetPath = hasDirPathConflict
-                        ? path.join(resolvedRoot, group.files[0])
-                        : path.join(resolvedRoot, group.dirPath);
+                    // BUG-A / H4 修复：targetPath 直接由 moduleSourceTarget 推导（FR-019：resolveSourceTarget
+                    // 已处理"同一 dirPath 多单文件冲突走文件路径"的降级分支），与 sourceTarget 口径保持一致。
+                    const targetPath = path.join(resolvedRoot, moduleSourceTarget);
                     // genOptions.skipEnrichment 已在 L648 处理 reading/code-only 模式分派
                     const result = await generateSpec(targetPath, {
                         ...genOptions,
-                        existingVersion: storedSpecByTarget.get(moduleSourceTarget)?.version,
+                        // Feature 182：注入 group.files（语言限定子集，绝对路径），使写侧只分析本语言文件，
+                        // 与读侧 group.files 文件集口径一致（消除混语言 hash 分叉 + 双倍分析）。
+                        files: group.files.map((f) => path.join(resolvedRoot, f)),
+                        existingVersion: storedSpecByTarget.get(moduleCacheKey)?.version,
+                        // Feature 182 修复 1：仅 languageSplit 组按 moduleName 显式命名输出文件，
+                        // 避免同目录多语言组(ts / py)都派生为同名 `<dir>.spec.md` 互相覆盖；
+                        // 非拆分组不传 → basename 派生，存量单语言仓库命名零变化。
+                        ...(group.languageSplit ? { outputFileName: `${moduleName}.spec.md` } : {}),
+                        // Feature 182 修复 2：languageSplit 组首写即落入 frontmatter.sourceTargetKey，
+                        // 消除「post-mutation 依赖 doc-graph re-render 落盘晚于 checkpoint save」崩溃窗口；
+                        // in-memory moduleSpec.frontmatter 由 generateFrontmatter 返回自然带上。
+                        sourceTargetKey: group.languageSplit ? moduleCacheKey : undefined,
                     });
                     // Bug 142：非 root 分支累积 input token，供 catch 块统一做预算检查。
                     if (result.costMetadata?.tokenUsage.input) {
@@ -629,7 +709,8 @@ export async function runBatch(projectRoot, options = {}) {
                         successful.push(moduleName);
                         reporter.complete(moduleName, 'success');
                     }
-                    checkedState.completedModules.push({
+                    // Feature 182：replace 语义（失效重跑时去重 + completed/failed 互斥）
+                    upsertCompletedModule(checkedState, {
                         path: moduleName,
                         specPath: toProjectPath(path.resolve(result.specPath)),
                         completedAt: new Date().toISOString(),
@@ -684,7 +765,8 @@ export async function runBatch(projectRoot, options = {}) {
                         reason: 'retry-budget-exceeded',
                     };
                     failed.push(failedModule);
-                    checkedState.failedModules.push(failedModule);
+                    // Feature 182：replace 语义（失效重跑时去重 + completed/failed 互斥）
+                    recordFailedModule(checkedState, failedModule);
                     reporter.complete(moduleName, 'failed');
                     break;
                 }
@@ -698,7 +780,8 @@ export async function runBatch(projectRoot, options = {}) {
                         degradedToAstOnly: false,
                     };
                     failed.push(failedModule);
-                    checkedState.failedModules.push(failedModule);
+                    // Feature 182：replace 语义（失效重跑时去重 + completed/failed 互斥）
+                    recordFailedModule(checkedState, failedModule);
                     reporter.complete(moduleName, 'failed');
                 }
             }
@@ -743,7 +826,8 @@ export async function runBatch(projectRoot, options = {}) {
                 reason: 'unhandled-exception',
             };
             failed.push(failedModule);
-            checkedState.failedModules.push(failedModule);
+            // Feature 182：replace 语义（失效重跑时去重 + completed/failed 互斥）
+            recordFailedModule(checkedState, failedModule);
             try {
                 reporter.complete(moduleName, 'failed');
             }
@@ -762,10 +846,63 @@ export async function runBatch(projectRoot, options = {}) {
     let projectDocsResult;
     let docsBundleManifestPath;
     let docsBundleProfiles;
-    // SpecStore 统一查询入口：所有消费方（README、graph、coverage、index、cross-ref）共享此源
+    // F175 FR-017/EC-008/EC-009：删除孤儿 spec（源文件已删除的 batch 产物），使增量产物文件集与全量一致。
+    // 必须在构造 SpecStore 之前执行 + 从 storedSpecs 集合中剔除已删项（C-2）——否则后续
+    // 所有聚合（index/graph/coverage/cross-ref）仍引用陈旧的已删 spec 视图，产生 stale 输出。
+    // 仅在增量/全量路径执行；ownership 边界缺一不删：(1) generatedByMode 存在（batch 专属标记）+
+    // (2) 位于受管 modules/ 输出目录内（path.relative 防目录穿越，禁字符串 startsWith）+
+    // (3) sourceTarget 已无任何在库源文件（EC-008：删除模块最后一个源文件后，空目录仍 existsSync=true，
+    //     故不能仅靠目录存在性判定——以当前扫描到的源文件集合为准）。
+    let storedSpecsForStore = existingStoredSpecs;
+    if (regenPlan.incremental || regenPlan.full) {
+        // 当前扫描到的源文件（项目相对，正斜杠口径），用于判定 sourceTarget 是否仍有活跃源文件
+        const liveSourceFiles = new Set(scanResult.files.map((f) => normalizeProjectPath(f)));
+        const hasLiveSource = (sourceTarget) => {
+            const prefix = `${sourceTarget}/`;
+            for (const f of liveSourceFiles) {
+                if (f === sourceTarget || f.startsWith(prefix))
+                    return true;
+            }
+            return false;
+        };
+        // 已确认删除的孤儿 outputPath 集合，用于从 storedSpecs 中剔除，使 SpecStore 不持有陈旧视图。
+        const deletedOrphanPaths = new Set();
+        for (const orphan of existingStoredSpecs) {
+            if (!isBatchGenerated(orphan))
+                continue; // 必要条件1：无 generatedByMode → 跳过（防误删手写 / 单文件 generate 产物）
+            if (hasLiveSource(orphan.sourceTarget))
+                continue; // 必要条件3：仍有活跃源文件 → 非孤儿
+            const absPath = path.isAbsolute(orphan.outputPath)
+                ? orphan.outputPath
+                : path.join(resolvedRoot, orphan.outputPath);
+            if (!isInManagedOutputDir(absPath, modulesDir))
+                continue; // 必要条件2：受管 modules/ 目录外 → 跳过
+            // 磁盘文件已被本轮其它逻辑清理：视为已删除，从内存视图剔除（保持内存与磁盘一致）。
+            if (!fs.existsSync(absPath)) {
+                deletedOrphanPaths.add(orphan.outputPath);
+                continue;
+            }
+            // W-1（quality-review）：rmSync 是破坏性新操作，权限/OS 错误不应让整个 batch 崩溃。
+            // 失败时 warn + 跳过，且【不】加入 deletedOrphanPaths——文件仍在磁盘，内存视图须保留它，
+            // 避免"内存说已删、磁盘还在"的不一致。仅删除成功才剔除内存视图。
+            try {
+                logger.info(`[orphan-cleanup] 删除孤儿 spec: ${orphan.outputPath}`);
+                fs.rmSync(absPath, { force: true });
+                deletedOrphanPaths.add(orphan.outputPath);
+            }
+            catch (err) {
+                logger.warn(`[orphan-cleanup] 删除孤儿 spec 失败，保守跳过: ${orphan.outputPath}（${err.message}）`);
+            }
+        }
+        if (deletedOrphanPaths.size > 0) {
+            storedSpecsForStore = existingStoredSpecs.filter((spec) => !deletedOrphanPaths.has(spec.outputPath));
+        }
+    }
+    // SpecStore 统一查询入口：所有消费方（README、graph、coverage、index、cross-ref）共享此源。
+    // 使用已剔除孤儿的 storedSpecsForStore，确保后续聚合不引用已删 spec（C-2）。
     const specStore = new SpecStore({
         currentSpecs: collectedModuleSpecs,
-        storedSpecs: existingStoredSpecs,
+        storedSpecs: storedSpecsForStore,
         projectRoot: resolvedRoot,
         toProjectPath,
     });
@@ -824,6 +961,34 @@ export async function runBatch(projectRoot, options = {}) {
                 logger.warn(`README 早期读取失败（不阻断 narrative 主流程）: ${String(readmeErr)}`);
             }
         }
+        // Feature 151 Codex Final C-1 修订 — 在 generateBatchProjectDocs 之前构建 UnifiedGraph
+        // 让 component-view-builder 能在生成时获取 graph（DI provider getCurrentUnifiedGraph）
+        //
+        // Feature 152 Codex final C-1 修复 — 同时合并 Python + TS/JS codeSkeletons，
+        // 否则用户跑 spectra batch 后 TS 项目 graph.json 中没有 calls 边（US-001 失败）
+        setCurrentUnifiedGraph(null);
+        try {
+            const pythonSkeletons = await collectPythonCodeSkeletons(resolvedRoot);
+            const tsJsSkeletons = await collectTsJsCodeSkeletons(resolvedRoot, {
+                extractCallSites: true,
+            });
+            // 合并两个 Map（projectRoot 都已 normalize 为绝对路径，key 形态一致）
+            const earlyCodeSkeletons = new Map([...pythonSkeletons, ...tsJsSkeletons]);
+            if (earlyCodeSkeletons.size > 0) {
+                const earlyUg = buildUnifiedGraph({
+                    projectRoot: resolvedRoot,
+                    codeSkeletons: earlyCodeSkeletons,
+                });
+                setCurrentUnifiedGraph(earlyUg);
+                const callEdges = earlyUg.edges.filter((e) => e.relation === 'calls').length;
+                logger.info(`[Feature 151+152] 早期 UnifiedGraph 构建：${earlyUg.nodes.length} 节点 / ${callEdges} calls 边 ` +
+                    `(${pythonSkeletons.size} .py + ${tsJsSkeletons.size} .ts/.tsx/.js/.jsx 文件)`);
+            }
+        }
+        catch (ugErr) {
+            setCurrentUnifiedGraph(null);
+            logger.warn(`[Feature 151+152] 早期 UnifiedGraph 构建失败（不阻塞）: ${String(ugErr)}`);
+        }
         try {
             projectDocsResult = await generateBatchProjectDocs({
                 projectRoot: resolvedRoot,
@@ -913,11 +1078,22 @@ export async function runBatch(projectRoot, options = {}) {
                 ...pythonSymbolResults,
                 ...(extractionResults ?? []),
             ];
+            // Feature 151 — UnifiedGraph 接入 graph-builder 第五路（早期已在 generateBatchProjectDocs 之前构建，此处复用 cache）
+            // 复用早期构建结果（Codex Final C-1 修订）：cache 在 generateBatchProjectDocs 之前已 set
+            const unifiedGraph = getCurrentUnifiedGraph();
+            if (unifiedGraph) {
+                const callEdgeCount = unifiedGraph.edges.filter((e) => e.relation === 'calls').length;
+                const dependEdgeCount = unifiedGraph.edges.filter((e) => e.relation === 'depends-on').length;
+                logger.info(`[Feature 151] graph-builder 注入 UnifiedGraph：${unifiedGraph.nodes.length} 节点，` +
+                    `${callEdgeCount} calls 边，${dependEdgeCount} depends-on 边`);
+            }
             const graphJson = buildKnowledgeGraph({
                 architectureIR: projectDocsResult?.architectureIR,
                 docGraph,
                 crossReferenceLinks,
                 extractionResults: mergedResults.length > 0 ? mergedResults : undefined, // Feature 107 + 143 第四路数据源
+                // Feature 151 T-012a：UnifiedGraph 第五路（calls + depends-on 边 + per-file callSitesCount metadata）
+                ...(unifiedGraph ? { unifiedGraph } : {}),
             });
             // Feature 133 P1-1（adversarial-review post-fix）：anchor + hyperedge 集成
             // F4 提供了 runAnchorIntegration / runHyperedgeIntegration 集成函数，
@@ -1074,6 +1250,11 @@ export async function runBatch(projectRoot, options = {}) {
             catch (communityErr) {
                 logger.warn(`community-analysis: 社区分析失败，跳过报告生成: ${communityErr instanceof Error ? communityErr.message : String(communityErr)}`);
             }
+            // F175 FR-006/FR-007：写盘前归一化（byte-stable）——nodes/links/hyperedges 确定性排序，
+            // 在追加 semantic edges + 社区分析之后调用，覆盖完整边集。
+            // F179：stripTimestamps:true 使 graph.generatedAt 固定为 epoch，落盘 graph.json 真 byte-stable
+            // （此前 F175 仅在测试读取侧 delete generatedAt，是 over-claim；现在落盘侧直接固定）。
+            normalizeGraphForWrite(graphJson, { stripTimestamps: true });
             // 社区分析完成后写盘（graphJson 已含 degree metadata）
             const graphWrittenPath = writeKnowledgeGraph(graphJson, resolvedOutputDir);
             docGraphPath = toProjectPath(graphWrittenPath);
@@ -1333,6 +1514,7 @@ export async function runBatch(projectRoot, options = {}) {
         docGraphPath,
         coverageReportPath,
         deltaReportPath,
+        deltaReport,
         projectDocs,
         docsBundleManifestPath,
         docsBundleProfiles,
@@ -1345,9 +1527,9 @@ export async function runBatch(projectRoot, options = {}) {
 async function buildGraphForLanguageGroup(langGroup, projectRoot) {
     const registry = LanguageAdapterRegistry.getInstance();
     const adapter = registry.getAllAdapters().find((item) => item.id === langGroup.adapterId);
-    if (adapter?.buildDependencyGraph) {
+    if (adapter?.buildModuleGraph) {
         try {
-            const langGraph = await adapter.buildDependencyGraph(projectRoot);
+            const langGraph = await adapter.buildModuleGraph(projectRoot);
             for (const node of langGraph.modules) {
                 node.language = langGroup.adapterId;
             }
@@ -1549,4 +1731,335 @@ function collectMdRecursive(dir, out) {
         }
     }
 }
+// ============================================================
+// Feature 151 — Python CodeSkeleton 收集（含 callSites 抽取）
+// ============================================================
+const PY_SKELETON_IGNORE_DIRS = new Set([
+    'node_modules', '.git', '__pycache__', '.venv', 'venv',
+    'build', 'dist', 'coverage', 'out', 'target', '.tox',
+]);
+/**
+ * Feature 151 T-008c — 收集 .py 文件 CodeSkeleton（含 callSites + 本地 import 解析）。
+ *
+ * 与 PythonLanguageAdapter.extractSymbolNodes / buildModuleGraph 不同：
+ * - 显式传 extractCallSites=true，让 graph.json 含 callSites 字段
+ * - 在 PythonMapper 输出基础上补充 import 的 resolvedPath（基于项目内 .py 模块 basename map）
+ *   — Codex P1 C-1 修订：mapper 当前只输出 moduleSpecifier，resolvedPath 始终 null，
+ *     导致 deriveImportEdges / call-resolver Stage 3 cross-module 全部失效
+ *
+ * 单文件解析失败 / 大文件 / 非 UTF-8 都按 EC-14 兜底（mapper 已处理），不影响整体 collection。
+ */
+export async function collectPythonCodeSkeletons(projectRoot) {
+    const out = new Map();
+    const { PythonLanguageAdapter } = await import('../adapters/python-adapter.js');
+    const adapter = new PythonLanguageAdapter();
+    // Codex P3+P4 复审 C-2 修复：projectRoot 显式 normalize 为绝对路径
+    // 避免调用方传相对路径 → Map key 与 imports[].resolvedPath 形态不一致
+    // → call-resolver buildImportIndex lookup miss
+    const resolvedProjectRoot = path.resolve(projectRoot);
+    // F194：构建 .gitignore 过滤器，基准 = resolvedProjectRoot（与 walk 内 path.relative 同口径）
+    const isGitignored = createGitignoreFilter(resolvedProjectRoot);
+    const pyFiles = [];
+    walkPyFiles(resolvedProjectRoot, pyFiles, isGitignored, resolvedProjectRoot);
+    // Feature 152 P3 T-017：大文件 size guard 提前到 parse 之前（避免 tree-sitter 解析阻塞）
+    // 1MB 阈值与 PythonMapper.CALLSITES_MAX_FILE_BYTES 对齐（EC-14）
+    const MAX_FILE_BYTES = 1_000_000;
+    for (const filePath of pyFiles) {
+        try {
+            let stat;
+            try {
+                stat = fs.statSync(filePath);
+            }
+            catch {
+                continue; // 文件读不到 stat → 跳过
+            }
+            if (stat.size > MAX_FILE_BYTES) {
+                // 大文件 skip — 不调 analyzeFile（避免 tree-sitter parse 巨型文件）
+                continue;
+            }
+            const skeleton = await adapter.analyzeFile(filePath, { extractCallSites: true });
+            // Feature 152 P3 T-017：使用 resolvePythonImport 替换 basename map（plan §5.1）
+            // C-1 修复：from . import X1, X2 形态（moduleSpecifier='.'/'..') 需对每个 namedImport 单独调用
+            // EC-10 修复：resolvedPath 转为绝对路径，与 Map key 格式对齐
+            const resolvedSkeleton = {
+                ...skeleton,
+                imports: skeleton.imports.flatMap((imp) => {
+                    if (imp.resolvedPath)
+                        return [imp];
+                    const spec = imp.moduleSpecifier;
+                    // C-1：裸相对 import —— moduleSpecifier 仅为纯点（'.' / '..' / '...' / 更深）
+                    // "from . import nn, Value" → imp.namedImports=['nn','Value']，逐个拆解
+                    // quality-review W-2 修复：扩展到任意点深度（PEP 328 不限层数），
+                    // 避免 'from ... import a, b' 时 a/b 都映射到同一 resolvedPath（namedImports 污染）
+                    if (/^\.+$/.test(spec)) {
+                        const namedImports = Array.isArray(imp.namedImports)
+                            ? imp.namedImports
+                            : [];
+                        if (namedImports.length === 0) {
+                            // 没有 namedImports（罕见），仅尝试解析包 __init__
+                            const result = resolvePythonImport(spec, filePath, resolvedProjectRoot);
+                            const resolvedPath = result.resolvedPath
+                                ? path.resolve(resolvedProjectRoot, result.resolvedPath)
+                                : null;
+                            return [{ ...imp, resolvedPath }];
+                        }
+                        // 每个 namedImport 单独解析为独立 import 记录
+                        // Codex P3+P4 复审 C-1 修复：每条拆出记录的 namedImports 必须**只**含
+                        // 当前拆出的 name，否则 buildImportIndex 会把所有 namedImports 都映射到
+                        // 同一 resolvedPath（最后一条胜出），导致 alias 污染
+                        return namedImports.map((name) => {
+                            const combinedSpec = `${spec}${name}`; // '.' + 'nn' → '.nn'
+                            const result = resolvePythonImport(combinedSpec, filePath, resolvedProjectRoot);
+                            const resolvedPath = result.resolvedPath
+                                ? path.resolve(resolvedProjectRoot, result.resolvedPath)
+                                : null;
+                            return {
+                                ...imp,
+                                moduleSpecifier: combinedSpec,
+                                namedImports: [name], // 关键：仅含本次拆出的 name，避免 alias 污染
+                                resolvedPath,
+                            };
+                        });
+                    }
+                    // 常规形态：直接调用 resolver（from pkg.engine import Value / import os）
+                    const result = resolvePythonImport(spec, filePath, resolvedProjectRoot);
+                    // EC-10：resolver 返回相对 projectRoot 的 POSIX 路径，需转绝对路径与 Map key 对齐
+                    const resolvedPath = result.resolvedPath
+                        ? path.resolve(resolvedProjectRoot, result.resolvedPath)
+                        : null;
+                    return [{ ...imp, resolvedPath }];
+                }),
+            };
+            out.set(filePath, resolvedSkeleton);
+        }
+        catch {
+            // 单文件失败不影响整体
+        }
+    }
+    return out;
+}
+/**
+ * F194：isGitignored 与 resolvedRoot 由 collectPythonCodeSkeletons 构建并通过参数传入，
+ * 在自写 walk 上叠加 .gitignore 过滤层（保留 PY_SKELETON_IGNORE_DIRS 与点前缀剪枝不变）。
+ */
+function walkPyFiles(dir, out, isGitignored, resolvedRoot) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        // 基准 = resolvedRoot，path.relative 输出不做 sep 转换（与 file-scanner walkDir 一致）
+        const relPath = path.relative(resolvedRoot, path.join(dir, entry.name));
+        if (entry.isDirectory()) {
+            if (entry.name.startsWith('.'))
+                continue;
+            if (PY_SKELETON_IGNORE_DIRS.has(entry.name))
+                continue;
+            if (isGitignored(relPath))
+                continue; // 目录命中 .gitignore → 剪枝
+            walkPyFiles(path.join(dir, entry.name), out, isGitignored, resolvedRoot);
+        }
+        else if (entry.isFile() && (entry.name.endsWith('.py') || entry.name.endsWith('.pyi'))) {
+            if (isGitignored(relPath))
+                continue; // 文件命中 .gitignore → 跳过
+            out.push(path.join(dir, entry.name));
+        }
+    }
+}
+// ============================================================
+// Feature 152 — TypeScript/JavaScript CodeSkeleton 收集
+// ============================================================
+/** T-020：TS/JS 文件扫描时忽略的目录集合（与 Python 对齐，增加 .next / .nuxt 等前端产物目录） */
+const TSJS_SKELETON_IGNORE_DIRS = new Set([
+    'node_modules', '.git', 'dist', 'build', 'coverage', 'out', 'target',
+    '.next', '.nuxt', '.turbo', '.cache', 'tmp', '.tmp',
+    '__pycache__', '.pytest_cache', '.tox',
+]);
+/**
+ * Feature 152 T-020 — 收集 .ts/.tsx/.js/.jsx 文件 CodeSkeleton（含 callSites + import 路径解析）。
+ *
+ * 与 collectPythonCodeSkeletons 设计对齐：
+ * - 可选 extractCallSites，走 TsJsLanguageAdapter 双路径 merge（Feature 152 T-013/T-014）
+ * - 解析 imports[].resolvedPath：findNearestTsConfig + buildTsConfigContext + resolveTsJsImport
+ * - EC-10：resolvedPath 转绝对路径与 Map key 格式对齐
+ * - T-021a：tsconfig context 按 configDir 缓存，避免每文件重复读
+ * - 单文件失败不阻塞整体（catch 吞掉，同 Python 版本 EC-14 兜底）
+ */
+export async function collectTsJsCodeSkeletons(projectRoot, options) {
+    const out = new Map();
+    const { TsJsLanguageAdapter } = await import('../adapters/ts-js-adapter.js');
+    const adapter = new TsJsLanguageAdapter();
+    // Codex P3+P4 复审 C-2 修复：projectRoot 显式 normalize 为绝对路径
+    // 避免调用方传相对路径 → Map key 与 imports[].resolvedPath 形态不一致
+    const resolvedProjectRoot = path.resolve(projectRoot);
+    // F194：构建 .gitignore 过滤器，基准 = resolvedProjectRoot（与 walk 内 path.relative 同口径）
+    const isGitignored = createGitignoreFilter(resolvedProjectRoot);
+    const tsJsFiles = [];
+    walkTsJsFiles(resolvedProjectRoot, tsJsFiles, isGitignored, resolvedProjectRoot);
+    // T-021a：tsconfig context 缓存（by configDir），避免每个文件重复读
+    const tsConfigCache = new Map();
+    // 大文件 size guard 与 Python 版本对齐（EC-14：1MB 阈值）
+    const MAX_FILE_BYTES = 1_000_000;
+    for (const filePath of tsJsFiles) {
+        try {
+            let stat;
+            try {
+                stat = fs.statSync(filePath);
+            }
+            catch {
+                continue; // 文件读不到 stat → 跳过
+            }
+            if (stat.size > MAX_FILE_BYTES) {
+                continue; // 大文件 skip
+            }
+            // 主分析（含 callSites if options.extractCallSites）
+            const skeleton = await adapter.analyzeFile(filePath, {
+                extractCallSites: options?.extractCallSites,
+            });
+            // T-021a：查找最近的 tsconfig.json 并缓存 context（Feature 181：loader 收口为 configPath 单参）
+            const configPath = findNearestTsConfig(filePath, resolvedProjectRoot);
+            let tsConfigContext = null;
+            if (configPath) {
+                if (!tsConfigCache.has(configPath)) {
+                    tsConfigCache.set(configPath, buildTsConfigContext(configPath));
+                }
+                tsConfigContext = tsConfigCache.get(configPath) ?? null;
+            }
+            // 解析 imports[].resolvedPath（EC-10：转绝对路径）
+            const resolvedSkeleton = {
+                ...skeleton,
+                imports: skeleton.imports.map((imp) => {
+                    if (imp.resolvedPath)
+                        return imp;
+                    const result = resolveTsJsImport(imp.moduleSpecifier, filePath, resolvedProjectRoot, tsConfigContext);
+                    // EC-10：resolver 返回相对 projectRoot 的 POSIX 路径，需转绝对路径与 Map key 对齐
+                    const resolvedPath = result.resolvedPath
+                        ? path.resolve(resolvedProjectRoot, result.resolvedPath)
+                        : null;
+                    return { ...imp, resolvedPath };
+                }),
+            };
+            out.set(filePath, resolvedSkeleton);
+        }
+        catch {
+            // 单文件失败不影响整体（与 collectPythonCodeSkeletons EC-14 一致）
+        }
+    }
+    return out;
+}
+/**
+ * 递归扫描 .ts/.tsx/.js/.jsx 文件（排除产物目录）。
+ * 复用 walkPyFiles 的扫描模式，扩展 TS/JS 扩展名集合。
+ *
+ * F194：isGitignored 与 resolvedRoot 由 collectTsJsCodeSkeletons 构建并通过参数传入，
+ * 在自写 walk 上叠加 .gitignore 过滤层（保留 TSJS_SKELETON_IGNORE_DIRS 与点前缀剪枝不变）。
+ */
+function walkTsJsFiles(dir, out, isGitignored, resolvedRoot) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        // 基准 = resolvedRoot，path.relative 输出不做 sep 转换（与 file-scanner walkDir 一致）
+        const relPath = path.relative(resolvedRoot, path.join(dir, entry.name));
+        if (entry.isDirectory()) {
+            if (entry.name.startsWith('.'))
+                continue;
+            if (TSJS_SKELETON_IGNORE_DIRS.has(entry.name))
+                continue;
+            if (isGitignored(relPath))
+                continue; // 目录命中 .gitignore → 剪枝
+            walkTsJsFiles(path.join(dir, entry.name), out, isGitignored, resolvedRoot);
+        }
+        else if (entry.isFile()) {
+            const name = entry.name;
+            if (name.endsWith('.ts') ||
+                name.endsWith('.tsx') ||
+                name.endsWith('.js') ||
+                name.endsWith('.jsx')) {
+                if (isGitignored(relPath))
+                    continue; // 文件命中 .gitignore → 跳过
+                out.push(path.join(dir, entry.name));
+            }
+        }
+    }
+}
+/**
+ * Feature 195：全仓纯 AST、零 LLM 的 graph-only 建图。
+ *
+ * 与 runBatch 解耦的姊妹管线——只跑 AST 采集 → unifiedGraph（call graph + depends-on）
+ * + Python 符号节点 → buildKnowledgeGraph → writeKnowledgeGraph，全程不调用任何
+ * spec-gen / enrichment / hyperedge LLM，也不需要认证。
+ *
+ * why 复用 collectPython/collectTsJs 而非 scanFiles：batch 的 unifiedGraph（见 runBatch
+ * 内早期 UnifiedGraph 构建段）正是用这两个采集器构建，复用它们使 graph-only 的 unifiedGraph
+ * 与 batch 口径逐一对齐（扩展名集合 + ignore 规则一致）。不按 languages 过滤，与 batch
+ * unifiedGraph 行为一致。
+ *
+ * why writeKnowledgeGraph 传 stripTimestamps:true：与 batch 写盘一致，剥除 generatedAt
+ * 实时戳，保 byte-stable 与跨 worktree 一致（F193/NFR-002）。
+ */
+export async function buildAstGraphOnly(projectRoot, options) {
+    const startTime = Date.now();
+    const resolvedRoot = path.resolve(projectRoot);
+    const outputDir = options?.outputDir ?? 'specs';
+    const resolvedOutputDir = path.isAbsolute(outputDir)
+        ? outputDir
+        : path.join(resolvedRoot, outputDir);
+    logger.info('[Feature 195] graph-only 建图：纯 AST / 零 LLM');
+    // 步骤 1：AST 采集（与 batch unifiedGraph 同款采集器，合并 Python + TS/JS）
+    const pythonSkeletons = await collectPythonCodeSkeletons(resolvedRoot);
+    const tsJsSkeletons = await collectTsJsCodeSkeletons(resolvedRoot, {
+        extractCallSites: true,
+    });
+    const codeSkeletons = new Map([...pythonSkeletons, ...tsJsSkeletons]);
+    if (codeSkeletons.size === 0) {
+        // EC-001：无可解析源码 → 仍产出 schema 合法的空图，不崩溃
+        logger.warn('[Feature 195] 未发现可建图的源码（将产出空图）');
+    }
+    // 步骤 2：UnifiedGraph（calls + depends-on，纯 AST）
+    const unifiedGraph = codeSkeletons.size > 0
+        ? buildUnifiedGraph({ projectRoot: resolvedRoot, codeSkeletons })
+        : undefined;
+    // 步骤 3：Python 符号节点（纯 AST，extractionResults 第四路）
+    // EC-003：extractSymbolNodes 内部已 best-effort（单文件失败仍产文件级节点），此处仅兜底捕获
+    let pythonSymbolResults = [];
+    try {
+        const { PythonLanguageAdapter } = await import('../adapters/python-adapter.js');
+        pythonSymbolResults = await new PythonLanguageAdapter().extractSymbolNodes(resolvedRoot);
+    }
+    catch (pyErr) {
+        logger.warn(`[Feature 195] Python 符号提取失败，跳过: ${String(pyErr)}`);
+    }
+    const pythonSymbolCount = pythonSymbolResults.reduce((sum, r) => sum + r.nodes.filter((n) => n.kind === 'component').length, 0);
+    // 步骤 4：合并构建 knowledge graph（不传 docGraph/architectureIR/crossReferenceLinks——
+    // 那三路依赖 spec-gen 产物；EC-004：buildKnowledgeGraph 对缺席数据源 graceful skip）
+    const graphJson = buildKnowledgeGraph({
+        ...(unifiedGraph ? { unifiedGraph } : {}),
+        ...(pythonSymbolResults.length > 0 ? { extractionResults: pythonSymbolResults } : {}),
+    });
+    // 步骤 5：复用 F183 写盘出口（内部 portable 守卫扫描 → normalizeGraphForWrite → 原子写）
+    const graphPath = writeKnowledgeGraph(graphJson, resolvedOutputDir, {
+        stripTimestamps: true,
+    });
+    const callEdgeCount = graphJson.links.filter((e) => e.relation === 'calls').length;
+    const dependsOnEdgeCount = graphJson.links.filter((e) => e.relation === 'depends-on').length;
+    logger.info(`[Feature 195] graph-only 完成：${graphJson.nodes.length} 节点 / ${graphJson.links.length} 边 ` +
+        `(${callEdgeCount} calls, ${dependsOnEdgeCount} depends-on, ${pythonSymbolCount} Python 符号)`);
+    return {
+        graphPath,
+        nodeCount: graphJson.nodes.length,
+        edgeCount: graphJson.links.length,
+        callEdgeCount,
+        dependsOnEdgeCount,
+        pythonSymbolCount,
+        durationMs: Date.now() - startTime,
+    };
+}
 //# sourceMappingURL=batch-orchestrator.js.map