spectra-cli 4.1.1

package/dist/panoramic/pipelines/architecture-narrative-mapreduce.js

@@ -0,0 +1,412 @@
+import { z } from 'zod';
+import { clusterDispatch } from '../cluster-orchestrator.js';
+import { createLogger } from '../utils/logger.js';
+const logger = createLogger('narrative-mapreduce');
+// ============================================================
+// 常量
+// ============================================================
+/** Phase D Critique 失败后允许的最大 Refine 次数（spec：1 次）*/
+const MAX_REFINE_ATTEMPTS = 1;
+/** Phase F: domain-words 校验最低门槛（spec：≥3 个核心抽象名）*/
+const MIN_DOMAIN_WORDS = 3;
+/** 默认 LLM 模型（spec FR-008：narrative 用 sonnet）*/
+const DEFAULT_NARRATIVE_MODEL = 'claude-sonnet-4-6';
+/** narrative 段落数量目标（spec：4-6 段）*/
+const NARRATIVE_PARAGRAPHS_MIN = 4;
+const NARRATIVE_PARAGRAPHS_MAX = 6;
+// ============================================================
+// Zod schemas (LLM output validation)
+// ============================================================
+/** Phase B Map 输出：每 cluster 的 mini-narrative + 关键抽象 */
+export const MapOutputSchema = z.object({
+    clusterNarrative: z.string().min(20).max(2000),
+    keyAbstractions: z.array(z.string().min(1)).min(1).max(20),
+});
+/** Phase C Reduce 输出：项目级 4-6 段 narrative */
+export const ReduceOutputSchema = z.object({
+    paragraphs: z.array(z.string().min(20)).min(NARRATIVE_PARAGRAPHS_MIN).max(NARRATIVE_PARAGRAPHS_MAX),
+    abstractionGlossary: z.array(z.string().min(1)).min(1).max(50),
+});
+/** Phase D Critique 输出 */
+export const CritiqueOutputSchema = z.object({
+    passed: z.boolean(),
+    issues: z.array(z.string()),
+});
+// ============================================================
+// 内部辅助：从 module spec 提取领域抽象名
+// ============================================================
+/**
+ * 从 module spec 接口段提取核心抽象名（函数名 / 类名 / 接口名）。
+ * 用于 Phase F 程序化 domain-words 校验。
+ *
+ * 提取规则（保守正则）：
+ * - 匹配 `^### .*?: <Identifier>` 类型（spec sections 接口定义段）
+ * - 匹配 markdown code block 中的 export class / function / interface
+ * - 仅采集大写开头的标识符（CamelCase / PascalCase 是抽象名典型特征）
+ */
+function moduleSummaryText(m) {
+    // StoredModuleSpecRecord 是结构化摘要而非完整 markdown，组合 3 段供 LLM/正则消费
+    return [m.intentSummary, m.businessSummary, m.dependencySummary]
+        .filter((s) => s && s.trim().length > 0)
+        .join('\n\n');
+}
+function extractDomainAbstractions(modules) {
+    const abstractions = new Set();
+    // 标识符正则：PascalCase / lowerCamel ≥ 3 字符（修复 Codex W-3 — 部分支持 Go/Rust 项目中的
+    // PascalCase 类型名；snake_case 仍需 LLM 阶段引导，本正则不强求覆盖所有命名约定）
+    const identifierRe = /\b([A-Z][A-Za-z0-9]{2,})\b/g;
+    // 修复 Codex W-4 — 扩充 stop words 黑名单（新增 Service / Manager / Config / Type 等高频泛词，
+    // 防止 narrative 仅靠泛词凑够 3 个 domain-words 通过校验）
+    const stopWords = new Set([
+        'README', 'TODO', 'NOTE', 'WARNING', 'ERROR', 'INFO', 'DEBUG',
+        'JSON', 'YAML', 'XML', 'HTML', 'CSS', 'API', 'URL', 'URI', 'HTTP', 'HTTPS',
+        'GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS',
+        'MIT', 'LICENSE', 'BSD',
+        // 高频通用泛词（非项目特有抽象）
+        'Service', 'Services', 'Manager', 'Managers', 'Config', 'Configs',
+        'Type', 'Types', 'Module', 'Modules', 'Package', 'Packages',
+        'Helper', 'Helpers', 'Utility', 'Utilities', 'Util', 'Utils',
+        'Component', 'Components', 'Handler', 'Handlers',
+        'Result', 'Results', 'Response', 'Responses', 'Request', 'Requests',
+        'Default', 'Defaults', 'Constant', 'Constants', 'Const',
+        'Builder', 'Builders', 'Factory', 'Factories',
+        'TEST', 'TESTS', 'Test', 'Tests',
+    ]);
+    for (const module of modules) {
+        const content = moduleSummaryText(module);
+        let match;
+        while ((match = identifierRe.exec(content)) !== null) {
+            const name = match[1];
+            if (!stopWords.has(name)) {
+                abstractions.add(name);
+            }
+        }
+    }
+    return abstractions;
+}
+/**
+ * Phase F: 校验 narrative 文本中是否出现 ≥ MIN_DOMAIN_WORDS 个项目特有抽象名。
+ *
+ * @returns 命中的领域词列表（去重）；caller 可根据 length 判定是否通过。
+ */
+export function validateDomainWords(paragraphs, modules) {
+    const abstractions = extractDomainAbstractions(modules);
+    const narrativeText = paragraphs.join('\n\n');
+    const found = new Set();
+    for (const abstraction of abstractions) {
+        // 用 word boundary 匹配避免子串误命中（如 'Service' 不应命中 'ServiceImpl' 内部）
+        const re = new RegExp(`\\b${escapeRegex(abstraction)}\\b`);
+        if (re.test(narrativeText)) {
+            found.add(abstraction);
+        }
+    }
+    return [...found];
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function buildSharedHeader(ctx) {
+    const parts = [];
+    if (ctx.readmeContent && ctx.readmeContent.trim().length > 0) {
+        parts.push(`## README（项目顶层叙述）\n\n${ctx.readmeContent.trim()}`);
+    }
+    if (ctx.projectContextSummary && ctx.projectContextSummary.trim().length > 0) {
+        parts.push(`## Project Context\n\n${ctx.projectContextSummary.trim()}`);
+    }
+    parts.push(`## 全模块 Inventory\n\n${ctx.moduleInventory}`);
+    return parts.join('\n\n---\n\n');
+}
+function buildModuleInventory(modules) {
+    return modules
+        .map((m) => `- \`${m.sourceTarget}\`: ${m.intentSummary.slice(0, 200).replace(/\n/g, ' ').trim()}`)
+        .join('\n');
+}
+function buildMapPrompt(cluster, sharedHeader) {
+    const clusterContent = cluster
+        .map((m) => `### \`${m.sourceTarget}\`\n\n${moduleSummaryText(m).slice(0, 3000)}`)
+        .join('\n\n---\n\n');
+    return `你是高级架构师，需要从给定的模块 spec 中提炼这个 cluster 的核心叙述。
+
+# 全局上下文（所有 cluster 共享）
+
+${sharedHeader}
+
+# 当前 Cluster 的模块 spec 内容
+
+${clusterContent}
+
+# 任务
+
+输出 JSON：
+\`\`\`json
+{
+  "clusterNarrative": "3-5 句中文叙述：这个 cluster 在项目中扮演什么角色？解决了什么核心问题？关键抽象是什么？必须提及具体的项目特有抽象名（不要泛泛而谈）。",
+  "keyAbstractions": ["项目特有的抽象名1", "项目特有的抽象名2", ..., "至少 1 个，最多 20 个"]
+}
+\`\`\`
+
+要求：
+- clusterNarrative 长度 20-2000 字符；
+- keyAbstractions 必须是该 cluster 实际出现的代码标识符（类名 / 函数名 / 接口名）；不接受 "API" / "Service" 这类泛词；
+- 仅输出 JSON 对象（不含 markdown 代码块包装）。`;
+}
+function buildReducePrompt(mapOutputs, sharedHeader) {
+    const clusterSummaries = mapOutputs
+        .map((mo, idx) => `## Cluster ${idx + 1}\n\nNarrative: ${mo.clusterNarrative}\n\n关键抽象: ${mo.keyAbstractions.join(', ')}`)
+        .join('\n\n---\n\n');
+    return `你是高级架构师，需要将多个 cluster 的叙述合并为项目级 4-6 段 narrative。
+
+# 全局上下文
+
+${sharedHeader}
+
+# Cluster 叙述（待合并）
+
+${clusterSummaries}
+
+# 任务
+
+输出 JSON：
+\`\`\`json
+{
+  "paragraphs": [
+    "段落 1：项目整体定位与价值",
+    "段落 2：核心架构（关键抽象间的协作）",
+    "段落 3-N：各子系统重点（按 cluster 重要性）",
+    "最后段：未解决问题 / 演进方向"
+  ],
+  "abstractionGlossary": ["项目级核心抽象名 1", "项目级核心抽象名 2", ...]
+}
+\`\`\`
+
+要求：
+- paragraphs 数组长度必须在 ${NARRATIVE_PARAGRAPHS_MIN}-${NARRATIVE_PARAGRAPHS_MAX} 之间；
+- 每段 ≥ 20 字符；
+- abstractionGlossary 至少包含 ${MIN_DOMAIN_WORDS} 个项目特有抽象名（综合所有 cluster）；
+- 仅输出 JSON 对象。`;
+}
+function buildCritiquePrompt(reduceOutput, modules) {
+    const moduleList = modules.map((m) => `- ${m.sourceTarget}`).join('\n');
+    return `你是技术审查者，需要批判性审视下面的 narrative，判断是否反映了项目真实技术本质。
+
+# Narrative
+
+${reduceOutput.paragraphs.map((p, i) => `${i + 1}. ${p}`).join('\n\n')}
+
+# 项目模块清单
+
+${moduleList}
+
+# 审查要点
+
+1. narrative 是否包含 ≥ ${MIN_DOMAIN_WORDS} 个项目特有的抽象名（如类名 / 函数名 / 概念）？泛词（API / Service / Module）不算。
+2. 是否准确反映模块 spec 实际职责，而不是套用通用模板？
+3. 段落间是否逻辑连贯（架构总览 → 核心机制 → 子系统重点 → 演进方向）？
+
+# 任务
+
+输出 JSON：
+\`\`\`json
+{
+  "passed": true/false,
+  "issues": ["如果 passed=false，列出具体问题（每条 < 100 字符）"]
+}
+\`\`\`
+
+仅输出 JSON 对象。`;
+}
+function buildRefinePrompt(reduceOutput, critique, sharedHeader) {
+    return `你是高级架构师，根据审查反馈改进 narrative。
+
+# 上下文
+
+${sharedHeader}
+
+# 当前 Narrative
+
+${reduceOutput.paragraphs.map((p, i) => `${i + 1}. ${p}`).join('\n\n')}
+
+# 审查反馈（必须解决）
+
+${critique.issues.map((iss, i) => `${i + 1}. ${iss}`).join('\n')}
+
+# 任务
+
+输出 JSON（结构同上一轮 Reduce 输出）：
+\`\`\`json
+{
+  "paragraphs": [...],
+  "abstractionGlossary": [...]
+}
+\`\`\`
+
+要求同 Reduce：${NARRATIVE_PARAGRAPHS_MIN}-${NARRATIVE_PARAGRAPHS_MAX} 段，每段 ≥ 20 字符，至少 ${MIN_DOMAIN_WORDS} 个项目特有抽象名。
+仅输出 JSON 对象。`;
+}
+// ============================================================
+// LLM call wrapper
+// ============================================================
+async function callLLM(client, prompt, schema, model, signal) {
+    const startMs = Date.now();
+    // 修复 Codex W-5 — 透传 AbortSignal 给 Anthropic SDK（cluster-orchestrator 超时时
+    // 会 abort 此 signal，让底层 LLM 调用真正取消而非 background 跑完浪费 token）
+    const response = await client.messages.create({
+        model,
+        max_tokens: 4096,
+        temperature: 0.3,
+        messages: [{ role: 'user', content: prompt }],
+    }, signal !== undefined ? { signal } : undefined);
+    const text = response.content
+        .filter((block) => block.type === 'text')
+        .map((block) => block.text)
+        .join('\n');
+    // 提取 JSON（可能被 ```json ``` 包裹）
+    const cleaned = text.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/i, '').trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(cleaned);
+    }
+    catch (err) {
+        throw new Error(`LLM JSON 解析失败: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const validation = schema.safeParse(parsed);
+    if (!validation.success) {
+        throw new Error(`LLM 输出 Zod schema 校验失败: ${validation.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')}`);
+    }
+    return {
+        output: validation.data,
+        telemetry: {
+            inputTokens: response.usage.input_tokens,
+            outputTokens: response.usage.output_tokens,
+            durationMs: Date.now() - startMs,
+            modelId: model,
+        },
+    };
+}
+// ============================================================
+// 主入口：enrichNarrativeWithLLM
+// ============================================================
+/**
+ * 基于 cluster orchestrator 的 4 段 LLM narrative 生成。
+ *
+ * 阶段：
+ *   A: 聚类（cluster orchestrator 内置 community → directory → single fallback）
+ *   B Map: per cluster mini-narrative + key abstractions（sonnet）
+ *   C Reduce: 合并为 4-6 段 narrative（sonnet）
+ *   D Critique: 独立 LLM 判定通过 / 失败（sonnet）
+ *   E Refine: 仅 D fail 时执行，最多 1 次（sonnet）
+ *   F 程序化 domain-words 校验（≥3 个核心抽象名）
+ *
+ * fail-closed 触发条件：
+ *   - Map < 50% 成功 → finalOutput=null
+ *   - Reduce 重试 1 次仍失败 → finalOutput=null
+ *   - Refine 后 domain-words 仍 < 3 → finalOutput=null（spec 锁定）
+ *
+ * @param options 包含 LLM 客户端、modules、可选 readme + projectContext
+ * @returns paragraphs（成功时 4-6 段；fail-closed 时 null）+ critique + domain-words + telemetry
+ */
+export async function enrichNarrativeWithLLM(options) {
+    const model = options.model ?? DEFAULT_NARRATIVE_MODEL;
+    const totalTokens = { input: 0, output: 0 };
+    // Phase A + B：通过 clusterDispatch 拆 cluster + Map per cluster
+    const moduleInventory = buildModuleInventory(options.modules);
+    const sharedHeaderText = buildSharedHeader({
+        readmeContent: options.readmeContent,
+        projectContextSummary: options.projectContextSummary,
+        moduleInventory,
+    });
+    const dispatchResult = await clusterDispatch({
+        inputs: options.modules,
+        // narrative 不依赖图结构，按 directory fallback chain 即可
+        // （Step 2 ADR 接 orchestrator 后会改为 community；narrative 当前简化为 directory）
+        clusterStrategy: {
+            kind: 'directory',
+            getInputPath: (m) => m.sourceTarget,
+        },
+        sharedHeader: async () => sharedHeaderText,
+        map: {
+            fn: async (cluster, _sharedHeader, signal) => {
+                const result = await callLLM(options.anthropicClient, buildMapPrompt(cluster, sharedHeaderText), MapOutputSchema, model, signal);
+                totalTokens.input += result.telemetry.inputTokens;
+                totalTokens.output += result.telemetry.outputTokens;
+                return result;
+            },
+            maxConcurrency: 4,
+        },
+        reduce: {
+            fn: async (mapOutputs, _sharedHeader, signal) => {
+                const result = await callLLM(options.anthropicClient, buildReducePrompt(mapOutputs, sharedHeaderText), ReduceOutputSchema, model, signal);
+                totalTokens.input += result.telemetry.inputTokens;
+                totalTokens.output += result.telemetry.outputTokens;
+                return result;
+            },
+        },
+    });
+    if (dispatchResult.finalOutput === null) {
+        // 修复 Codex W-2 — 透传 cluster orchestrator 的 failClosedReason union（不再压缩为 2 个值）
+        const reason = dispatchResult.diagnostics.failClosedReason ?? 'map-below-threshold';
+        return {
+            paragraphs: null,
+            domainWordsFound: [],
+            critiqueResult: { passed: false, issues: [`cluster dispatch ${reason}`], refineAttempted: false },
+            failClosed: true,
+            failClosedReason: reason,
+            totalTokens,
+        };
+    }
+    let currentReduce = dispatchResult.finalOutput;
+    // Phase D: Critique（独立 LLM 调用）
+    let critique;
+    let refineAttempted = false;
+    try {
+        const critiqueResult = await callLLM(options.anthropicClient, buildCritiquePrompt(currentReduce, options.modules), CritiqueOutputSchema, model);
+        totalTokens.input += critiqueResult.telemetry.inputTokens;
+        totalTokens.output += critiqueResult.telemetry.outputTokens;
+        critique = critiqueResult.output;
+    }
+    catch (err) {
+        // 修复 Codex C-2 — Critique 失败应显式 passed=false（fail-closed 语义而非 fail-open），
+        // 让下游 caller / Refine 路径可见质量门未通过，避免无人察觉。
+        // issues 含 critique-skipped 标记便于诊断。
+        logger.warn(`Critique LLM 调用失败，记录为 passed=false: ${String(err)}`);
+        critique = { passed: false, issues: [`critique-skipped: ${String(err).slice(0, 80)}`] };
+    }
+    // Phase E: Refine（仅 D fail 时执行，最多 1 次）
+    // 修复 Codex W-1 — passed=false 即触发，不再要求 issues.length > 0
+    // （之前的 issues=[] 边界 case 会绕过 Refine，留下"审查失败但 narrative 通过"的不一致状态）
+    if (!critique.passed) {
+        refineAttempted = true;
+        for (let attempt = 0; attempt < MAX_REFINE_ATTEMPTS; attempt++) {
+            try {
+                const refineResult = await callLLM(options.anthropicClient, buildRefinePrompt(currentReduce, critique, sharedHeaderText), ReduceOutputSchema, model);
+                totalTokens.input += refineResult.telemetry.inputTokens;
+                totalTokens.output += refineResult.telemetry.outputTokens;
+                currentReduce = refineResult.output;
+            }
+            catch (err) {
+                logger.warn(`Refine LLM 调用失败（attempt ${attempt + 1}），保留 critique 失败状态: ${String(err)}`);
+            }
+        }
+    }
+    // Phase F: 程序化 domain-words 校验
+    const domainWordsFound = validateDomainWords(currentReduce.paragraphs, options.modules);
+    if (domainWordsFound.length < MIN_DOMAIN_WORDS) {
+        // 即便 Critique passed，domain-words 不达标也 fail-closed（spec 强制要求）
+        return {
+            paragraphs: null,
+            domainWordsFound,
+            critiqueResult: { passed: critique.passed, issues: critique.issues, refineAttempted },
+            failClosed: true,
+            failClosedReason: 'domain-words-insufficient',
+            totalTokens,
+        };
+    }
+    return {
+        paragraphs: currentReduce.paragraphs,
+        domainWordsFound,
+        critiqueResult: { passed: critique.passed, issues: critique.issues, refineAttempted },
+        failClosed: false,
+        totalTokens,
+    };
+}
+//# sourceMappingURL=architecture-narrative-mapreduce.js.map

package/dist/panoramic/pipelines/architecture-narrative-mapreduce.js.map

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

package/dist/panoramic/pipelines/architecture-narrative.d.ts

@@ -0,0 +1,123 @@
+import type { DocumentGenerator, GenerateOptions, ProjectContext } from '../interfaces.js';
+import type { ArchitectureOverviewOutput } from '../generators/architecture-overview-generator.js';
+import { type StoredModuleSpecRecord } from '../stored-module-specs.js';
+export interface BatchGeneratedDocSummary {
+    generatorId: string;
+    writtenFiles: string[];
+    warnings: string[];
+}
+type NarrativeModuleRole = 'core' | 'support' | 'validation';
+export interface NarrativeSymbolInsight {
+    moduleName: string;
+    ownerName?: string;
+    name: string;
+    kind: string;
+    signature: string;
+    note: string;
+    inferred: boolean;
+}
+export interface NarrativeModuleInsight {
+    sourceTarget: string;
+    displayName: string;
+    role: NarrativeModuleRole;
+    relatedFiles: string[];
+    confidence: 'high' | 'medium' | 'low';
+    intentSummary: string;
+    businessSummary: string;
+    dependencySummary: string;
+    keySymbols: NarrativeSymbolInsight[];
+    keyMethods: NarrativeSymbolInsight[];
+    inferred: boolean;
+}
+export interface RepositoryMapEntry {
+    path: string;
+    category: string;
+    moduleCount: number;
+    fileCount: number;
+    summary: string;
+}
+export interface SupportingDocLink {
+    generatorId: string;
+    title: string;
+    path: string;
+}
+export interface ArchitectureNarrativeOutput {
+    title: string;
+    generatedAt: string;
+    projectName: string;
+    executiveSummary: string[];
+    repositoryMap: RepositoryMapEntry[];
+    keyModules: NarrativeModuleInsight[];
+    keySymbols: NarrativeSymbolInsight[];
+    keyMethods: NarrativeSymbolInsight[];
+    observations: string[];
+    supportingDocs: SupportingDocLink[];
+    /**
+     * Feature 140 FR-010 — README 摘录（前 1000 chars）。
+     * 仅 caller 提供 readmeContent 时填充；Step 4 (Phase 3b) MapReduce 集成后，
+     * 当 anthropicClient 提供时本字段被 LLM 段落替换（写入 executiveSummary）。
+     */
+    readmeExcerpt?: string;
+    /**
+     * Feature 140 Step 4 (FR-008/FR-009) — LLM 增强路径的诊断字段（可选）。
+     * 仅 batch-project-docs 在 anthropicClient 提供时由 enrichNarrativeWithLLM 填充。
+     * caller 可在 module spec frontmatter 中写入，让用户观察 LLM narrative 路径状态。
+     */
+    llmCritiqueResult?: {
+        passed: boolean;
+        issues: string[];
+        refineAttempted: boolean;
+    };
+    llmDomainWordsFound?: string[];
+    llmTotalTokens?: {
+        input: number;
+        output: number;
+    };
+    llmFailClosedReason?: 'map-below-threshold' | 'reduce-failed' | 'clustering-failed' | 'shared-header-failed' | 'domain-words-insufficient';
+}
+type StoredNarrativeModule = StoredModuleSpecRecord;
+export interface BuildArchitectureNarrativeOptions {
+    projectRoot: string;
+    outputDir: string;
+    /** specs 根目录（用于扫描模块 specs，默认 outputDir） */
+    specsRootDir?: string;
+    projectContext: ProjectContext;
+    architectureOverview?: ArchitectureOverviewOutput;
+    generatedDocs: BatchGeneratedDocSummary[];
+    /**
+     * Feature 140 FR-010 — README 全量内容（仅 --include-docs=true 时由 extraction-pipeline 提供）。
+     *
+     * **本 Step 5 接通数据流**：参数透传到 ArchitectureNarrativeOutput.readmeExcerpt（截断到
+     * 1000 chars 用于 v4.1 当前 template-based 渲染）。
+     *
+     * **Step 4 (Phase 3b) 完整 MapReduce 重构后**：本字段将作为 cluster orchestrator shared header
+     * 注入 Map prompt（架构文档 §四 Phase B），让 LLM 在生成 narrative 时直接看到原始 README，
+     * 而非依赖二次提炼的 module spec。届时本 readmeExcerpt 字段会被废弃或重新定位。
+     *
+     * 未传时（默认 / --include-docs=false）行为完全不变，向后兼容。
+     */
+    readmeContent?: string;
+}
+export declare function buildArchitectureNarrative(options: BuildArchitectureNarrativeOptions): ArchitectureNarrativeOutput;
+export declare function renderArchitectureNarrative(output: ArchitectureNarrativeOutput): string;
+export declare function loadStoredNarrativeModules(outputDir: string, projectRoot: string): StoredNarrativeModule[];
+/**
+ * ArchitectureNarrativeGenerator
+ *
+ * 将 buildArchitectureNarrative() 适配为 DocumentGenerator 接口。
+ * 面向人类阅读的技术架构说明文档。
+ *
+ * TInput: BuildArchitectureNarrativeOptions
+ * TOutput: ArchitectureNarrativeOutput
+ */
+export declare class ArchitectureNarrativeGenerator implements DocumentGenerator<BuildArchitectureNarrativeOptions, ArchitectureNarrativeOutput> {
+    readonly id: "architecture-narrative";
+    readonly name: "\u6280\u672F\u67B6\u6784\u8BF4\u660E\u751F\u6210\u5668";
+    readonly description = "\u9762\u5411\u4EBA\u7C7B\u9605\u8BFB\u7684\u6280\u672F\u67B6\u6784\u53D9\u4E8B\u6587\u6863\uFF0C\u805A\u5408 module spec \u4E0E\u67B6\u6784\u4E8B\u5B9E\uFF0C\u751F\u6210\u5173\u952E\u6A21\u5757/\u7C7B/\u65B9\u6CD5\u7684\u7ED3\u6784\u5316\u8BF4\u660E";
+    isApplicable(context: ProjectContext): boolean;
+    extract(context: ProjectContext): Promise<BuildArchitectureNarrativeOptions>;
+    generate(input: BuildArchitectureNarrativeOptions, _options?: GenerateOptions): Promise<ArchitectureNarrativeOutput>;
+    render(output: ArchitectureNarrativeOutput): string;
+}
+export {};
+//# sourceMappingURL=architecture-narrative.d.ts.map

package/dist/panoramic/pipelines/architecture-narrative.d.ts.map

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