spectra-cli 4.2.0 → 4.3.0

package/dist/batch/regen-plan.d.ts

@@ -0,0 +1,78 @@
+import type { ModuleGroup } from './module-grouper.js';
+/** RegenPlan 的来源标记，用于可观测日志与降级追溯 */
+export type RegenPlanSource = 'full' | 'incremental-explicit' | 'default';
+/**
+ * resolveRegenPlan 的扁平输入。
+ * config 合并由各入口在自己现状位置完成（CLI 在 batch.ts，MCP 在 server.ts 用 `?? fileConfig.x`），
+ * 本函数只接收"合并后的有效值"，不做 cli/mcp/config 笛卡尔积。
+ */
+export interface RegenPlanInput {
+    /** 已合并：--incremental / mcp.incremental / config.incremental */
+    incremental?: boolean;
+    /** 已合并：--full / mcp.full（config 无 full 字段，用 force 表达） */
+    full?: boolean;
+    /** 已合并：--force / mcp.force / config.force（--full 的等义别名） */
+    force?: boolean;
+}
+/** resolveRegenPlan 的解析结果（唯一真值） */
+export interface RegenPlan {
+    /** true = 走 DeltaRegenerator */
+    incremental: boolean;
+    /** true = 绕 DeltaRegenerator + 绕 checkpoint 全量重生成（full|force 合并真值） */
+    full: boolean;
+    /** 来源标记 */
+    source: RegenPlanSource;
+}
+/**
+ * 把"合并后的有效输入"解析为唯一的 RegenPlan。
+ *
+ * 解析规则（优先级自上而下）：
+ *   (1) full===true || force===true → { incremental:false, full:true, source:'full' }
+ *   (2) incremental===true（显式 opt-in，未给 full/force）→ { incremental:true, full:false, source:'incremental-explicit' }
+ *   (3) incremental===false（显式 opt-out）→ { incremental:false, full:false, source:'incremental-explicit' }
+ *   (4) 全 undefined（默认）→ { incremental:true, full:false }（FR-001 默认翻转）
+ *
+ * 显式 incremental===true（规则 2）与显式 incremental===false（规则 3）都尊重调用方意图；
+ * 仅在未给出任何 regen 轴参数时（规则 4）落默认增量（FR-001）。
+ */
+export declare function resolveRegenPlan(input: RegenPlanInput): RegenPlan;
+/**
+ * 把系统路径分隔符归一化为正斜杠。
+ *
+ * Feature 178：batch 内单参口径的唯一来源（delta-regenerator / batch-orchestrator import 此处），
+ * 消除三份逐字副本。注意与 panoramic 的双参变体 `(inputPath, projectRoot)`（先 path.relative）
+ * 语义不同，不在此合并范围。
+ */
+export declare function normalizeProjectPath(inputPath: string): string;
+/**
+ * 计算单个模块的 sourceTarget（与 batch-orchestrator.processOneModule:713-720 等价）。
+ *
+ * H4 修复语义：文件级降级场景（非 root + 单文件 + dirPath 冲突）下 sourceTarget 须与文件路径
+ * 保持一致，否则 --incremental 的 regenerateTargets 查询与 storedSpecByTarget 查询全部错位。
+ *
+ * @param group 模块分组
+ * @param conflictingDirPaths 与其他单文件目录冲突的 dirPath 集合
+ * @param isRoot 是否 root 模块（root 模块按文件展开，调用方自行处理，本函数返回 dirPath 口径）
+ * @returns 归一化后的 sourceTarget
+ */
+export declare function resolveSourceTarget(group: ModuleGroup, conflictingDirPaths: Set<string>, isRoot: boolean): string;
+/**
+ * 从纯路径 sourceTarget 派生增量缓存 key（Feature 182）。
+ *
+ * 修复同目录多语言组 Map 键碰撞：同一 dirPath 被 language-split 成两个 ModuleGroup 时，
+ * resolveSourceTarget 对两组返回相同纯路径，导致 storedSpecByTarget / regenerateTargets
+ * 键碰撞、后写覆盖前写、增量永久 miss。
+ *
+ * 本 helper 仅在 languageSplit 组追加 `::language` 后缀派生唯一 cache key；
+ * 单语言目录维持纯路径（最小化存量缓存失效面）。
+ *
+ * 关键不变量：frontmatter 的 sourceTarget 保持纯路径不变（panoramic / spec-store 路径
+ * 匹配消费方零改动）；cache key 只存在于 src/batch/ 内的 Map/Set 与新增 frontmatter
+ * 字段 sourceTargetKey。
+ *
+ * @param sourceTarget resolveSourceTarget 返回的纯路径
+ * @param group 仅需 language / languageSplit 两字段
+ * @returns 单语言：原路径；语言拆分组：`${sourceTarget}::${language}`
+ */
+export declare function buildSpecCacheKey(sourceTarget: string, group: Pick<ModuleGroup, 'language' | 'languageSplit'>): string;
+//# sourceMappingURL=regen-plan.d.ts.map

package/dist/batch/regen-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regen-plan.d.ts","sourceRoot":"","sources":["../../src/batch/regen-plan.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAMvD,mCAAmC;AACnC,MAAM,MAAM,eAAe,GACvB,MAAM,GACN,sBAAsB,GACtB,SAAS,CAAC;AAEd;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,yDAAyD;IACzD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,mCAAmC;AACnC,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,WAAW,EAAE,OAAO,CAAC;IACrB,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,WAAW;IACX,MAAM,EAAE,eAAe,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CAmBjE;AAMD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,EAChC,MAAM,EAAE,OAAO,GACd,MAAM,CAMR;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,UAAU,GAAG,eAAe,CAAC,GACrD,MAAM,CAIR"}

package/dist/batch/regen-plan.js

@@ -0,0 +1,93 @@
+/**
+ * Batch 重生成计划解析（regen-plan）
+ *
+ * 提供两个纯函数，供 batch 三入口（CLI / MCP / runBatch 直调）与 DeltaRegenerator 共享：
+ *   - resolveRegenPlan：把"已合并后的有效输入"解析为唯一的 RegenPlan 真值
+ *   - resolveSourceTarget：统一 module → sourceTarget 的口径（含目录冲突分支）
+ *
+ * 从 batch-orchestrator.ts 提取，消除 GREEN 阶段在两处分别推演 target / regen 语义的认知负担。
+ */
+import * as path from 'node:path';
+/**
+ * 把"合并后的有效输入"解析为唯一的 RegenPlan。
+ *
+ * 解析规则（优先级自上而下）：
+ *   (1) full===true || force===true → { incremental:false, full:true, source:'full' }
+ *   (2) incremental===true（显式 opt-in，未给 full/force）→ { incremental:true, full:false, source:'incremental-explicit' }
+ *   (3) incremental===false（显式 opt-out）→ { incremental:false, full:false, source:'incremental-explicit' }
+ *   (4) 全 undefined（默认）→ { incremental:true, full:false }（FR-001 默认翻转）
+ *
+ * 显式 incremental===true（规则 2）与显式 incremental===false（规则 3）都尊重调用方意图；
+ * 仅在未给出任何 regen 轴参数时（规则 4）落默认增量（FR-001）。
+ */
+export function resolveRegenPlan(input) {
+    // 规则 (1)：full 或 force 优先（force 是 full 的等义别名）
+    if (input.full === true || input.force === true) {
+        return { incremental: false, full: true, source: 'full' };
+    }
+    // 规则 (2)：显式 incremental=true → 走增量（任何阶段都尊重显式 opt-in）
+    if (input.incremental === true) {
+        return { incremental: true, full: false, source: 'incremental-explicit' };
+    }
+    // 规则 (3)：显式 incremental=false 走旧"仅看文件存在"兼容路径
+    if (input.incremental === false) {
+        return { incremental: false, full: false, source: 'incremental-explicit' };
+    }
+    // 规则 (4)：undefined 默认路径
+    // FR-001 默认翻转：未传任何 regen 轴参数时走增量（DeltaRegenerator）。
+    return { incremental: true, full: false, source: 'default' };
+}
+// ============================================================
+// resolveSourceTarget：统一 module → sourceTarget 口径
+// ============================================================
+/**
+ * 把系统路径分隔符归一化为正斜杠。
+ *
+ * Feature 178：batch 内单参口径的唯一来源（delta-regenerator / batch-orchestrator import 此处），
+ * 消除三份逐字副本。注意与 panoramic 的双参变体 `(inputPath, projectRoot)`（先 path.relative）
+ * 语义不同，不在此合并范围。
+ */
+export function normalizeProjectPath(inputPath) {
+    return inputPath.split(path.sep).join('/');
+}
+/**
+ * 计算单个模块的 sourceTarget（与 batch-orchestrator.processOneModule:713-720 等价）。
+ *
+ * H4 修复语义：文件级降级场景（非 root + 单文件 + dirPath 冲突）下 sourceTarget 须与文件路径
+ * 保持一致，否则 --incremental 的 regenerateTargets 查询与 storedSpecByTarget 查询全部错位。
+ *
+ * @param group 模块分组
+ * @param conflictingDirPaths 与其他单文件目录冲突的 dirPath 集合
+ * @param isRoot 是否 root 模块（root 模块按文件展开，调用方自行处理，本函数返回 dirPath 口径）
+ * @returns 归一化后的 sourceTarget
+ */
+export function resolveSourceTarget(group, conflictingDirPaths, isRoot) {
+    const hasDirPathConflict = !isRoot && group.files.length === 1 && conflictingDirPaths.has(group.dirPath);
+    return hasDirPathConflict
+        ? normalizeProjectPath(group.files[0])
+        : normalizeProjectPath(group.dirPath);
+}
+/**
+ * 从纯路径 sourceTarget 派生增量缓存 key（Feature 182）。
+ *
+ * 修复同目录多语言组 Map 键碰撞：同一 dirPath 被 language-split 成两个 ModuleGroup 时，
+ * resolveSourceTarget 对两组返回相同纯路径，导致 storedSpecByTarget / regenerateTargets
+ * 键碰撞、后写覆盖前写、增量永久 miss。
+ *
+ * 本 helper 仅在 languageSplit 组追加 `::language` 后缀派生唯一 cache key；
+ * 单语言目录维持纯路径（最小化存量缓存失效面）。
+ *
+ * 关键不变量：frontmatter 的 sourceTarget 保持纯路径不变（panoramic / spec-store 路径
+ * 匹配消费方零改动）；cache key 只存在于 src/batch/ 内的 Map/Set 与新增 frontmatter
+ * 字段 sourceTargetKey。
+ *
+ * @param sourceTarget resolveSourceTarget 返回的纯路径
+ * @param group 仅需 language / languageSplit 两字段
+ * @returns 单语言：原路径；语言拆分组：`${sourceTarget}::${language}`
+ */
+export function buildSpecCacheKey(sourceTarget, group) {
+    return group.languageSplit && group.language
+        ? `${sourceTarget}::${group.language}`
+        : sourceTarget;
+}
+//# sourceMappingURL=regen-plan.js.map

package/dist/batch/regen-plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"regen-plan.js","sourceRoot":"","sources":["../../src/batch/regen-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAqClC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAqB;IACpD,6CAA6C;IAC7C,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC5D,CAAC;IAED,qDAAqD;IACrD,IAAI,KAAK,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QAC/B,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAC5E,CAAC;IAED,6CAA6C;IAC7C,IAAI,KAAK,CAAC,WAAW,KAAK,KAAK,EAAE,CAAC;QAChC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAC7E,CAAC;IAED,wBAAwB;IACxB,oDAAoD;IACpD,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC/D,CAAC;AAED,+DAA+D;AAC/D,kDAAkD;AAClD,+DAA+D;AAE/D;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAiB;IACpD,OAAO,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAkB,EAClB,mBAAgC,EAChC,MAAe;IAEf,MAAM,kBAAkB,GACtB,CAAC,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,mBAAmB,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAChF,OAAO,kBAAkB;QACvB,CAAC,CAAC,oBAAoB,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;QACvC,CAAC,CAAC,oBAAoB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,YAAoB,EACpB,KAAsD;IAEtD,OAAO,KAAK,CAAC,aAAa,IAAI,KAAK,CAAC,QAAQ;QAC1C,CAAC,CAAC,GAAG,YAAY,KAAK,KAAK,CAAC,QAAQ,EAAE;QACtC,CAAC,CAAC,YAAY,CAAC;AACnB,CAAC"}

package/dist/cli/commands/batch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/batch.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAqBzD;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAmHzF"}
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/batch.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAqBzD;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkJzF"}

package/dist/cli/commands/batch.js

@@ -3,7 +3,8 @@
  * 对当前项目执行批量 Spec 生成
  */
 import { resolve } from 'node:path';
-import { runBatch } from '../../batch/batch-orchestrator.js';
+import { runBatch, buildAstGraphOnly } from '../../batch/batch-orchestrator.js';
+import { resolveRegenPlan } from '../../batch/regen-plan.js';
 import { checkAuth, handleError, EXIT_CODES } from '../utils/error-handler.js';
 import { loadProjectConfig, mergeConfig } from '../../config/project-config.js';
 import { readBatchConcurrency } from '../../config/spec-driver-config.js';
@@ -27,10 +28,6 @@ function resolveBatchConcurrency(cliConcurrency, projectRoot) {
  */
 export async function runBatchCommand(command, version) {
     console.log(`spectra v${version} — 批量生成`);
-    if (!checkAuth()) {
-        process.exitCode = EXIT_CODES.API_ERROR;
-        return;
-    }
     try {
         // 解析目标路径：优先使用 CLI 传入的 target，其次使用 cwd
         const projectRoot = resolve(command.target ?? process.cwd());
@@ -42,15 +39,46 @@ export async function runBatchCommand(command, version) {
             languages: command.languages,
             outputDir: command.outputDir,
         }, fileConfig, command._explicitFlags ?? new Set());
+        // F195：graph-only 零 LLM 建图——在 checkAuth 之前拦截并 dispatch 到姊妹管线。
+        // why 不调 checkAuth：graph-only 纯 AST、不调任何 LLM，行为对齐 prepare（FR-005）。
+        // why 放在 projectRoot + config merge 之后：buildAstGraphOnly 需要 projectRoot 与 outputDir。
+        if (command.batchMode === 'graph-only') {
+            if (command.languages?.length) {
+                console.warn('⚠ graph-only 不支持 --languages 过滤，将构建全仓 AST 图');
+            }
+            const graphResult = await buildAstGraphOnly(projectRoot, {
+                outputDir: merged.outputDir,
+            });
+            console.log('  模式: graph-only（纯 AST · 零 LLM）');
+            console.log(`  节点: ${graphResult.nodeCount} | 边: ${graphResult.edgeCount} ` +
+                `(calls ${graphResult.callEdgeCount}, depends-on ${graphResult.dependsOnEdgeCount}) ` +
+                `| Python 符号: ${graphResult.pythonSymbolCount} | 耗时: ${(graphResult.durationMs / 1000).toFixed(1)}s`);
+            console.log(`✓ 知识图谱: ${graphResult.graphPath}`);
+            process.exitCode = EXIT_CODES.SUCCESS;
+            return;
+        }
+        // 非 graph-only 路径：spec-gen 需要认证
+        if (!checkAuth()) {
+            process.exitCode = EXIT_CODES.API_ERROR;
+            return;
+        }
+        // F175 FR-002：合并后统一解析 regen 计划（唯一默认值来源，消除三处漂移）。
+        // --full（regen 轴逃生口）仅来自 CLI，不参与 config 合并；--force 为等义别名（已合并）。
+        const regenPlan = resolveRegenPlan({
+            incremental: merged.incremental,
+            full: command.full,
+            force: merged.force,
+        });
         // Feature 135 Bug 4：reading 模式 TTY hint
         // 避免用户误以为 reading 模式是"快速模式"——模块级 LLM 仍会运行
         if (command.batchMode === 'reading' && process.stdout.isTTY) {
             console.log('提示：reading 模式省约 38% 时间，但模块级 LLM 仍运行（非快速模式）。\n' +
-                '如需最快分析（< 30s），请使用 --mode code-only');
+                '如需进一步跳过 enrichment 层，可使用 --mode code-only（注：仍逐模块调 spec-gen LLM，非零成本）');
         }
         const result = await runBatch(projectRoot, {
-            force: merged.force,
-            incremental: merged.incremental,
+            // F175：传入已解析的 RegenPlan 真值（runBatch 内对直接调用方仍会兜底解析，幂等）。
+            incremental: regenPlan.incremental,
+            full: regenPlan.full,
             languages: merged.languages,
             outputDir: merged.outputDir,
             concurrency: resolveBatchConcurrency(command.concurrency, projectRoot),

package/dist/cli/commands/batch.js.map

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

package/dist/cli/commands/scaffold-kb.d.ts

@@ -0,0 +1,9 @@
+/**
+ * F190 scaffold-kb 子命令入口（build | serve）
+ *
+ * build：文档目录 / llms.txt → kb/（doc-graph.json + chunks.sqlite）
+ * serve：启动 KB MCP server（Phase B 接入，demo plugin .mcp.json 调用此路径）
+ */
+import type { CLICommand } from '../utils/parse-args.js';
+export declare function runScaffoldKb(command: CLICommand): Promise<void>;
+//# sourceMappingURL=scaffold-kb.d.ts.map

package/dist/cli/commands/scaffold-kb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-kb.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/scaffold-kb.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AA0HzD,wBAAsB,aAAa,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAqDtE"}

package/dist/cli/commands/scaffold-kb.js

@@ -0,0 +1,179 @@
+/**
+ * F190 scaffold-kb 子命令入口（build | serve）
+ *
+ * build：文档目录 / llms.txt → kb/（doc-graph.json + chunks.sqlite）
+ * serve：启动 KB MCP server（Phase B 接入，demo plugin .mcp.json 调用此路径）
+ */
+import { join } from 'node:path';
+import { buildKb } from '../../scaffold-kb/index.js';
+import { extractKeywords } from '../../scaffold-kb/keyword-extract.js';
+import { searchKbCore } from '../../scaffold-kb/search-core.js';
+import { formatInjectionBlock } from '../../scaffold-kb/injection-format.js';
+import { loadKbContext } from '../../kb-mcp/lib/kb-locator.js';
+import { mergeResults } from '../../kb-mcp/lib/result-merger.js';
+import { prepareIngest, commitIngest, IngestError } from '../../scaffold-kb/ingest/ingest-core.js';
+const QUERY_PROBE_SENTINEL = 'scaffold-kb-query:1';
+/** scaffold-kb query：一次性预查，输出注入块（markdown）或结构化结果（json）；KB 不可用 → exit 0 空 stdout */
+async function runQuery(command) {
+    if (command.scaffoldKbProbe) {
+        process.stdout.write(`${QUERY_PROBE_SENTINEL}\n`);
+        return;
+    }
+    const requirement = command.scaffoldKbRequirement;
+    const vendorKbPath = command.scaffoldKbVendorKb;
+    if (!requirement || !vendorKbPath) {
+        console.error('用法: spectra scaffold-kb query --requirement "<需求>" --vendor-kb <path> [--project-kb <path>] [--top-k N] [--max-inject-chars N] [--format markdown|json] [--probe]');
+        process.exitCode = 1;
+        return;
+    }
+    const topK = command.scaffoldKbTopK ?? 3;
+    const maxInjectChars = command.scaffoldKbMaxInjectChars ?? 6000;
+    const format = command.scaffoldKbFormat ?? 'markdown';
+    // KB 加载失败（不可用）→ 降级：exit 0 + 空 stdout（FR-005 / EC-002 统一退出契约）
+    const loaded = await loadKbContext(command.scaffoldKbProjectKb !== undefined
+        ? { vendorKbPath, projectKbPath: command.scaffoldKbProjectKb }
+        : { vendorKbPath });
+    if (!loaded.ok) {
+        console.error(`[scaffold-kb query] kb-missing: ${loaded.code}`);
+        return; // exit 0, stdout 空
+    }
+    const query = extractKeywords(requirement);
+    if (query.length === 0) {
+        console.error('[scaffold-kb query] no-query: 关键词为空');
+        return;
+    }
+    const ctx = loaded.context;
+    // preTokenized=true：query 已由 extractKeywords 规范化，避免 sanitizeQuery 二次 CJK 展开（修 Codex W5）
+    const vendorHits = ctx.vendor ? searchKbCore(ctx.vendor.db, query, topK * 2, undefined, true) : null;
+    const projectHits = ctx.project ? searchKbCore(ctx.project.db, query, topK * 2, undefined, true) : null;
+    const vendorResults = vendorHits && vendorHits.ok ? vendorHits.results : [];
+    const projectResults = projectHits && projectHits.ok ? projectHits.results : [];
+    const merged = mergeResults(vendorResults, projectResults, topK);
+    if (merged.length === 0) {
+        console.error('[scaffold-kb query] no-hit');
+        return; // exit 0, stdout 空
+    }
+    if (format === 'json') {
+        process.stdout.write(JSON.stringify({ query, results: merged }) + '\n');
+        return;
+    }
+    // markdown：MergedResult 结构兼容 EvidenceResult
+    const block = formatInjectionBlock(merged, maxInjectChars);
+    if (block.length > 0)
+        process.stdout.write(block + '\n');
+}
+/** scaffold-kb ingest：三方源（url/file/minutes）→ 预览 → --yes 落项目库（FR-009/013） */
+async function runIngest(command) {
+    const sources = [];
+    if (command.scaffoldKbUrl)
+        sources.push({ kind: 'url', value: command.scaffoldKbUrl });
+    if (command.scaffoldKbFile)
+        sources.push({ kind: 'file', value: command.scaffoldKbFile });
+    if (command.scaffoldKbMinutes)
+        sources.push({ kind: 'minutes', value: command.scaffoldKbMinutes });
+    if (sources.length === 0) {
+        console.error('用法: spectra scaffold-kb ingest (--url <url> | --file <path> | --minutes <path>) ' +
+            '[--project-kb <path>] [--yes | --dry-run] [--no-llm]');
+        process.exitCode = 1;
+        return;
+    }
+    const projectKb = command.scaffoldKbProjectKb ?? join(process.cwd(), '.spectra', 'kb');
+    const opts = {};
+    if (command.scaffoldKbNoLlm === true)
+        opts.noLlm = true;
+    let plan;
+    try {
+        plan = await prepareIngest(sources, projectKb, opts);
+    }
+    catch (e) {
+        // 既有项目库读取失败等 fail-closed → 拒绝导入（C-2）
+        console.error(`[scaffold-kb ingest] 失败：${e instanceof IngestError ? e.message : String(e)}`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log('[scaffold-kb ingest] 预览:');
+    for (const s of plan.sources) {
+        console.log(`  ${s.ok ? '✓' : '✗'} ${s.origin}${s.ok ? ` (${s.type})` : ` — ${s.reason ?? ''}`}`);
+    }
+    console.log(`  新增 ${plan.newDocs} 文档 / ${plan.newChunks} chunk / ${plan.newEntities} 实体` +
+        `（合并后共 ${plan.totalChunks} chunk / ${plan.totalEntities} 实体）`);
+    const okCount = plan.sources.filter((s) => s.ok).length;
+    // 全部源失败 → 拒绝落库 + exit 1（W-4）
+    if (okCount === 0) {
+        console.error('  所有源均失败，未落库');
+        process.exitCode = 1;
+        return;
+    }
+    if (command.scaffoldKbDryRun === true) {
+        console.log('  --dry-run：仅预览，不落库');
+        return;
+    }
+    if (command.scaffoldKbYes !== true) {
+        console.log('  预览模式：加 --yes 落库，或 --dry-run 仅预览');
+        return;
+    }
+    commitIngest(projectKb, plan);
+    console.log(`  ✓ 已落库 → ${projectKb}`);
+    // 部分源失败 → exit 2（信号，已落成功的部分，W-4）
+    if (okCount < plan.sources.length)
+        process.exitCode = 2;
+}
+export async function runScaffoldKb(command) {
+    const op = command.scaffoldKbOperation;
+    if (op === 'build') {
+        const llmsTxtUrl = command.scaffoldKbLlmsTxt;
+        const dirPath = command.scaffoldKbDir;
+        if (!llmsTxtUrl && !dirPath) {
+            console.error('用法: spectra scaffold-kb build (--dir <路径> | --llms-txt <URL>) [--output <kb/>] [--sdk-version <版本>]');
+            process.exitCode = 1;
+            return;
+        }
+        const opts = {};
+        if (llmsTxtUrl !== undefined)
+            opts.llmsTxtUrl = llmsTxtUrl;
+        if (dirPath !== undefined)
+            opts.dirPath = dirPath;
+        if (command.scaffoldKbOutput !== undefined)
+            opts.outputPath = command.scaffoldKbOutput;
+        if (command.scaffoldKbSdkVersion !== undefined)
+            opts.sdkVersion = command.scaffoldKbSdkVersion;
+        if (command.scaffoldKbLang !== undefined)
+            opts.lang = command.scaffoldKbLang;
+        if (command.scaffoldKbNoLlm === true)
+            opts.noLlm = true;
+        const res = await buildKb(opts);
+        console.log(`[scaffold-kb] 构建完成：${res.docCount} 文档 / ${res.chunkCount} chunk / ` +
+            `${res.entityCount} 实体（${res.extractionMethod}）→ ${res.outputPath}`);
+        return;
+    }
+    if (op === 'query') {
+        await runQuery(command);
+        return;
+    }
+    if (op === 'ingest') {
+        await runIngest(command);
+        return;
+    }
+    if (op === 'serve') {
+        // Phase B：启动 KB MCP server。serve 实现随 KB MCP 层（src/kb-mcp/）接入（T046）。
+        const vendorKbPath = command.scaffoldKbVendorKb;
+        if (!vendorKbPath) {
+            console.error('用法: spectra scaffold-kb serve --vendor-kb <path> [--project-kb <path>]');
+            process.exitCode = 1;
+            return;
+        }
+        await startServe(vendorKbPath, command.scaffoldKbProjectKb);
+        return;
+    }
+    console.error('用法: spectra scaffold-kb <build|serve> ...');
+    process.exitCode = 1;
+}
+/** serve 启动点：加载双库上下文并起 KB MCP stdio server（T046） */
+async function startServe(vendorKbPath, projectKbPath) {
+    const { startKbMcpServer } = await import('../../kb-mcp/index.js');
+    const opts = { vendorKbPath };
+    if (projectKbPath !== undefined)
+        opts.projectKbPath = projectKbPath;
+    await startKbMcpServer(opts);
+}
+//# sourceMappingURL=scaffold-kb.js.map

package/dist/cli/commands/scaffold-kb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold-kb.js","sourceRoot":"","sources":["../../../src/cli/commands/scaffold-kb.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AACvE,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAuB,MAAM,uCAAuC,CAAC;AAClG,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAqB,MAAM,yCAAyC,CAAC;AAEtH,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AAEnD,mFAAmF;AACnF,KAAK,UAAU,QAAQ,CAAC,OAAmB;IACzC,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;QAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,oBAAoB,IAAI,CAAC,CAAC;QAClD,OAAO;IACT,CAAC;IACD,MAAM,WAAW,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAClD,MAAM,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAChD,IAAI,CAAC,WAAW,IAAI,CAAC,YAAY,EAAE,CAAC;QAClC,OAAO,CAAC,KAAK,CAAC,mKAAmK,CAAC,CAAC;QACnL,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,cAAc,IAAI,CAAC,CAAC;IACzC,MAAM,cAAc,GAAG,OAAO,CAAC,wBAAwB,IAAI,IAAI,CAAC;IAChE,MAAM,MAAM,GAAG,OAAO,CAAC,gBAAgB,IAAI,UAAU,CAAC;IAEtD,6DAA6D;IAC7D,MAAM,MAAM,GAAG,MAAM,aAAa,CAChC,OAAO,CAAC,mBAAmB,KAAK,SAAS;QACvC,CAAC,CAAC,EAAE,YAAY,EAAE,aAAa,EAAE,OAAO,CAAC,mBAAmB,EAAE;QAC9D,CAAC,CAAC,EAAE,YAAY,EAAE,CACrB,CAAC;IACF,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,mCAAmC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAChE,OAAO,CAAC,mBAAmB;IAC7B,CAAC;IAED,MAAM,KAAK,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;IAC3C,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,CAAC,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACrD,OAAO;IACT,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC;IAC3B,wFAAwF;IACxF,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACrG,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACxG,MAAM,aAAa,GAAG,UAAU,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5E,MAAM,cAAc,GAAG,WAAW,IAAI,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;IAChF,MAAM,MAAM,GAAG,YAAY,CAAC,aAAa,EAAE,cAAc,EAAE,IAAI,CAAC,CAAC;IAEjE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAC5C,OAAO,CAAC,mBAAmB;IAC7B,CAAC;IAED,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;QACxE,OAAO;IACT,CAAC;IACD,4CAA4C;IAC5C,MAAM,KAAK,GAAG,oBAAoB,CAAC,MAA0B,EAAE,cAAc,CAAC,CAAC;IAC/E,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;AAC3D,CAAC;AAED,4EAA4E;AAC5E,KAAK,UAAU,SAAS,CAAC,OAAmB;IAC1C,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,IAAI,OAAO,CAAC,aAAa;QAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACvF,IAAI,OAAO,CAAC,cAAc;QAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAC1F,IAAI,OAAO,CAAC,iBAAiB;QAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACnG,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,CAAC,KAAK,CACX,kFAAkF;YAChF,sDAAsD,CACzD,CAAC;QACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,mBAAmB,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;IACvF,MAAM,IAAI,GAAwC,EAAE,CAAC;IACrD,IAAI,OAAO,CAAC,eAAe,KAAK,IAAI;QAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IAExD,IAAI,IAAI,CAAC;IACT,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,aAAa,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,qCAAqC;QACrC,OAAO,CAAC,KAAK,CAAC,2BAA2B,CAAC,YAAY,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC7F,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAC7B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IACpG,CAAC;IACD,OAAO,CAAC,GAAG,CACT,QAAQ,IAAI,CAAC,OAAO,SAAS,IAAI,CAAC,SAAS,YAAY,IAAI,CAAC,WAAW,KAAK;QAC1E,SAAS,IAAI,CAAC,WAAW,YAAY,IAAI,CAAC,aAAa,MAAM,CAChE,CAAC;IACF,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC;IACxD,6BAA6B;IAC7B,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QAC9B,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,IAAI,OAAO,CAAC,gBAAgB,KAAK,IAAI,EAAE,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC;QACnC,OAAO;IACT,CAAC;IACD,IAAI,OAAO,CAAC,aAAa,KAAK,IAAI,EAAE,CAAC;QACnC,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;QACjD,OAAO;IACT,CAAC;IACD,YAAY,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC9B,OAAO,CAAC,GAAG,CAAC,aAAa,SAAS,EAAE,CAAC,CAAC;IACtC,iCAAiC;IACjC,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM;QAAE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAmB;IACrD,MAAM,EAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAEvC,IAAI,EAAE,KAAK,OAAO,EAAE,CAAC;QACnB,MAAM,UAAU,GAAG,OAAO,CAAC,iBAAiB,CAAC;QAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC;QACtC,IAAI,CAAC,UAAU,IAAI,CAAC,OAAO,EAAE,CAAC;YAC5B,OAAO,CAAC,KAAK,CACX,qGAAqG,CACtG,CAAC;YACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAkC,EAAE,CAAC;QAC/C,IAAI,UAAU,KAAK,SAAS;YAAE,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC3D,IAAI,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAClD,IAAI,OAAO,CAAC,gBAAgB,KAAK,SAAS;YAAE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,gBAAgB,CAAC;QACvF,IAAI,OAAO,CAAC,oBAAoB,KAAK,SAAS;YAAE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,oBAAoB,CAAC;QAC/F,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,cAAc,CAAC;QAC7E,IAAI,OAAO,CAAC,eAAe,KAAK,IAAI;YAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAExD,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAChC,OAAO,CAAC,GAAG,CACT,sBAAsB,GAAG,CAAC,QAAQ,SAAS,GAAG,CAAC,UAAU,WAAW;YAClE,GAAG,GAAG,CAAC,WAAW,OAAO,GAAG,CAAC,gBAAgB,MAAM,GAAG,CAAC,UAAU,EAAE,CACtE,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,EAAE,KAAK,OAAO,EAAE,CAAC;QACnB,MAAM,QAAQ,CAAC,OAAO,CAAC,CAAC;QACxB,OAAO;IACT,CAAC;IAED,IAAI,EAAE,KAAK,QAAQ,EAAE,CAAC;QACpB,MAAM,SAAS,CAAC,OAAO,CAAC,CAAC;QACzB,OAAO;IACT,CAAC;IAED,IAAI,EAAE,KAAK,OAAO,EAAE,CAAC;QACnB,oEAAoE;QACpE,MAAM,YAAY,GAAG,OAAO,CAAC,kBAAkB,CAAC;QAChD,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,OAAO,CAAC,KAAK,CAAC,wEAAwE,CAAC,CAAC;YACxF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QACD,MAAM,UAAU,CAAC,YAAY,EAAE,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAC5D,OAAO;IACT,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC3D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC;AAED,oDAAoD;AACpD,KAAK,UAAU,UAAU,CAAC,YAAoB,EAAE,aAAsB;IACpE,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAAC;IACnE,MAAM,IAAI,GAAqD,EAAE,YAAY,EAAE,CAAC;IAChF,IAAI,aAAa,KAAK,SAAS;QAAE,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;IACpE,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC"}

package/dist/cli/index.js

@@ -8,6 +8,7 @@ import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from './utils/parse-args.js';
 import { printError } from './utils/error-handler.js';
+import { resolveVersionString } from './version-meta.js';
 import { runGenerate } from './commands/generate.js';
 import { runBatchCommand } from './commands/batch.js';
 import { runDiff } from './commands/diff.js';
@@ -31,13 +32,20 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgPath = resolve(__dirname, '..', '..', 'package.json');
 const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
 const version = pkg.version;
+/**
+ * 组装 `--version` 实际输出。
+ * __dirname 在 dist 编译产物中为 dist/cli/，故 meta 在上一级 dist/.spectra-build-meta.json。
+ */
+function formatVersion() {
+    return resolveVersionString(resolve(__dirname, '..', '.spectra-build-meta.json'), version);
+}
 // 帮助文本
 const HELP_TEXT = `spectra — 代码逆向工程 Spec 生成工具 v${version}
 
 用法:
   spectra generate <target> [--deep] [--output-dir <dir>]
   spectra prepare <target> [--deep]
-  spectra batch [--force] [--incremental] [--languages <lang,...>] [--include-docs] [--include-images] [--mode <full|reading|code-only>] [--hyperedges] [--concurrency <N>] [--no-html] [--output-dir <dir>]
+  spectra batch [--full] [--force] [--incremental] [--languages <lang,...>] [--include-docs] [--include-images] [--mode <full|reading|code-only|graph-only>] [--hyperedges] [--concurrency <N>] [--no-html] [--output-dir <dir>]
   spectra diff <spec-file> <source> [--output-dir <dir>]
   spectra init [--global] [--remove] [--target <claude|codex|both>]
   spectra auth-status [--verify]
@@ -53,6 +61,10 @@ const HELP_TEXT = `spectra — 代码逆向工程 Spec 生成工具 v${version}
   spectra direction-audit --snapshot <path>
   spectra direction-audit --compare-snapshot <path>
   spectra index [--watch] [--incremental] [--caller-depth <N>] [--project-root <dir>]
+  spectra scaffold-kb build (--dir <path> | --llms-txt <url>) [--output <kb/>] [--sdk-version <ver>] [--lang <code>] [--no-llm]
+  spectra scaffold-kb ingest (--url <url> | --file <path> | --minutes <path>) [--project-kb <path>] [--yes|--dry-run] [--no-llm]
+  spectra scaffold-kb serve --vendor-kb <path> [--project-kb <path>]
+  spectra scaffold-kb query --requirement "<需求>" --vendor-kb <path> [--top-k N] [--max-inject-chars N] [--format markdown|json] [--probe]
   spectra mcp-server
   spectra --version / --help
 
@@ -73,6 +85,7 @@ const HELP_TEXT = `spectra — 代码逆向工程 Spec 生成工具 v${version}
   export        将知识图谱导出为 Obsidian Vault 或 HTML 交互式可视化
   direction-audit 依赖方向自查工具（SC-006 CI regression guard）
   index         构建并持久化 UnifiedGraph snapshot 到 .spectra/unified-graph.json（Feature 156）
+  scaffold-kb   领域知识脚手架（Feature 190）：build 构建 kb/（doc-graph + FTS5）；serve 启动 KB MCP server
   mcp-server    启动 MCP stdio server（供 Claude Code 插件调用）
 
 认证:
@@ -87,12 +100,13 @@ const HELP_TEXT = `spectra — 代码逆向工程 Spec 生成工具 v${version}
   --target       目标平台: claude | codex | both（仅 init，默认按当前运行时自动选择）
   --verify       在线验证认证凭证（仅 auth-status）
   --deep         包含函数体进行深度分析（generate / prepare）
-  --force        强制重新生成所有 Spec（仅 batch）
-  --incremental  仅重生成受影响的 Spec（仅 batch）
+  --full         全量重生成所有模块（regen 轴，绕过增量 cache + checkpoint，仅 batch）。注：与 --mode full（文档质量维度）无关，二者正交可同时指定
+  --force        同 --full（向后兼容别名，仅 batch）
+  --incremental  仅重生成受影响的 Spec（仅 batch）。注：未指定任何 regen 轴参数时默认即走增量
   --languages    仅处理指定语言，逗号分隔（如 typescript,python）（仅 batch）
   --include-docs 启用 Markdown 文档和 OpenAPI/AsyncAPI 规范提取（仅 batch）
   --include-images 启用图像/图表 Vision 提取（仅 batch）
-  --mode         批处理运行模式: full（默认，完整文档，LLM 全量）| reading（省约 38% 时间，模块级 LLM 仍运行，跳过架构叙事/ADR/产品文档层）| code-only（纯 AST，< 30s，无 LLM，最快）（仅 batch）
+  --mode         批处理运行模式（spec 文档质量维度，与 --full regen 轴正交）: full（默认，完整文档，LLM 全量）| reading（省约 38% 时间，模块级 LLM 仍运行，跳过架构叙事/ADR/产品文档层）| code-only（仅跳 enrichment 层，仍逐模块调 spec-gen LLM，非零成本/非最快，耗时随模块数增长）| graph-only（纯 AST / 零 LLM：只建 call graph + knowledge graph 写 graph.json，不调任何 spec-gen LLM、无需认证，耗时随文件数线性，<2min 量级）（仅 batch）
   --hyperedges   启用 hyperedge LLM 提取（仅 batch + mode=full 生效，默认 false；可用 env SPECTRA_HYPEREDGES_ENABLED=true 等价开启）
   --enable-adr   显式启用 ADR pipeline（v4.0.1 临时禁用，将在 v4.1 evidence-binding 重构后恢复；默认 false）（仅 batch）
   --concurrency  最大并发模块数（仅 batch，默认 3；优先级 CLI > spec-driver.config.yaml batch.concurrency > 默认 3；≤0 / 非整数会规范化为 1 并打印 warn）
@@ -125,7 +139,7 @@ async function main() {
     }
     const { command } = result;
     if (command.version) {
-        console.log(`spectra v${version}`);
+        console.log(formatVersion());
         return;
     }
     if (command.help) {
@@ -181,6 +195,11 @@ async function main() {
         case 'index':
             await runIndexCommand(command);
             break;
+        case 'scaffold-kb': {
+            const { runScaffoldKb } = await import('./commands/scaffold-kb.js');
+            await runScaffoldKb(command);
+            break;
+        }
         case 'mcp-server':
             await runMcpServer(command);
             break;

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,sBAAsB;AACtB,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;AAC/D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,CAAwB,CAAC;AAC9E,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;AAE5B;;;GAGG;AACH,SAAS,aAAa;IACpB,OAAO,oBAAoB,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,0BAA0B,CAAC,EAAE,OAAO,CAAC,CAAC;AAC7F,CAAC;AAED,OAAO;AACP,MAAM,SAAS,GAAG,+BAA+B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAqFhC,CAAC;AAEzB,KAAK,UAAU,IAAI;IACjB,4CAA4C;IAC5C,gBAAgB,EAAE,CAAC;IAEnB,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAEhD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACjC,OAAO,CAAC,GAAG,EAAE,CAAC;QACd,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACvB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAE3B,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,CAAC,CAAC;QAC7B,OAAO;IACT,CAAC;IAED,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACvB,OAAO;IACT,CAAC;IAED,QAAQ,OAAO,CAAC,UAAU,EAAE,CAAC;QAC3B,KAAK,UAAU;YACb,MAAM,WAAW,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACpC,MAAM;QACR,KAAK,OAAO;YACV,MAAM,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACxC,MAAM;QACR,KAAK,MAAM;YACT,MAAM,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAChC,MAAM;QACR,KAAK,MAAM;YACT,OAAO,CAAC,OAAO,CAAC,CAAC;YACjB,MAAM;QACR,KAAK,SAAS;YACZ,MAAM,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACnC,MAAM;QACR,KAAK,aAAa;YAChB,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC;YAC7B,MAAM;QACR,KAAK,WAAW;YACd,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAC;YACnC,MAAM;QACR,KAAK,OAAO;YACV,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;YAC/B,MAAM;QACR,KAAK,OAAO;YACV,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;YAC/B,MAAM;QACR,KAAK,OAAO;YACV,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;YAC/B,MAAM;QACR,KAAK,WAAW;YACd,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAC;YACnC,MAAM;QACR,KAAK,OAAO;YACV,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;YAC/B,MAAM;QACR,KAAK,SAAS;YACZ,UAAU,CAAC,OAAO,CAAC,CAAC;YACpB,MAAM;QACR,KAAK,QAAQ;YACX,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAC;YAChC,MAAM;QACR,KAAK,iBAAiB;YACpB,MAAM,wBAAwB,CAAC,OAAO,CAAC,CAAC;YACxC,MAAM;QACR,KAAK,OAAO;YACV,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC;YAC/B,MAAM;QACR,KAAK,aAAa,CAAC,CAAC,CAAC;YACnB,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,MAAM,CAAC,2BAA2B,CAAC,CAAC;YACpE,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC;YAC7B,MAAM;QACR,CAAC;QACD,KAAK,YAAY;YACf,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC;YAC5B,MAAM;IACV,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,UAAU,CAAC,SAAS,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACxE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/cli/utils/error-handler.d.ts

@@ -15,12 +15,6 @@ export declare const EXIT_CODES: {
  * @returns 如果路径不存在则输出错误信息并返回 false
  */
 export declare function validateTargetPath(target: string): boolean;
-/**
- * 检查 ANTHROPIC_API_KEY 环境变量
- * @deprecated 使用 checkAuth() 替代，支持 API Key 和 CLI 代理两种认证方式
- * @returns 如果缺失则输出错误信息并返回 false
- */
-export declare function checkApiKey(): boolean;
 /**
  * 检查是否有可用的认证方式（API Key 或 Claude CLI）
  * @returns 如果无可用方式则输出错误信息并返回 false

package/dist/cli/utils/error-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/error-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,YAAY;AACZ,eAAO,MAAM,UAAU;;;;IAIrB,yDAAyD;;CAEjD,CAAC;AAEX;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAO1D;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,OAAO,CASrC;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAYnC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAmBhD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAElD"}
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/error-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,YAAY;AACZ,eAAO,MAAM,UAAU;;;;IAIrB,yDAAyD;;CAEjD,CAAC;AAEX;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAO1D;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,OAAO,CAYnC;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAmBhD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEhD;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAElD"}