spectra-cli 4.1.1 → 4.2.0

package/dist/panoramic/interface-surface-generator.js

@@ -0,0 +1,388 @@
+/**
+ * InterfaceSurfaceGenerator
+ *
+ * 面向 library / SDK / public interface 项目生成接口摘要文档。
+ * 复用既有 module spec 的 baseline skeleton，不新增新的底层语言解析链路。
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parseStoredModuleSpec, } from './stored-module-specs.js';
+import { loadTemplate } from './utils/template-loader.js';
+const ENTRYPOINT_FILE_PATTERN = /(^|\/)(__init__\.py|index\.(?:[cm]?js|[cm]?ts|jsx|tsx)|client\.(?:py|ts|js)|query\.(?:py|ts|js))$/i;
+const LOW_SIGNAL_PATH_PATTERN = /(^|\/)(tests?|specs?|examples?|demos?|scripts?|benchmarks?|fixtures?|e2e(?:-tests)?)($|\/)/i;
+const CORE_SIGNAL_PATTERN = /(client|query|sdk|session|transport|parser|types?|hooks?|tool|message|runtime|protocol|agent)/i;
+const IGNORED_DISCOVERY_DIRS = new Set([
+    '.git',
+    'node_modules',
+    'dist',
+    'build',
+    'coverage',
+    'bundles',
+]);
+const PUBLIC_SYMBOL_KINDS = new Set([
+    'function',
+    'class',
+    'interface',
+    'type',
+    'enum',
+    'const',
+    'variable',
+    'struct',
+    'trait',
+    'protocol',
+    'data_class',
+    'module',
+]);
+const PUBLIC_MEMBER_KINDS = new Set([
+    'method',
+    'getter',
+    'setter',
+    'classmethod',
+    'staticmethod',
+    'associated_function',
+]);
+export class InterfaceSurfaceGenerator {
+    id = 'interface-surface';
+    name = 'Interface Surface 生成器';
+    description = '为 library / SDK 项目生成公开接口、关键类与关键方法摘要';
+    async isApplicable(context) {
+        const modules = collectInterfaceModules(context);
+        if (modules.length === 0) {
+            return false;
+        }
+        return looksLikeLibrarySdkProject(context, modules);
+    }
+    async extract(context) {
+        const modules = collectInterfaceModules(context);
+        const warnings = [];
+        if (modules.length === 0) {
+            warnings.push('未发现可用于 interface-surface 的 module spec / baseline skeleton。');
+        }
+        return {
+            projectName: detectProjectName(context.projectRoot),
+            modules,
+            warnings,
+        };
+    }
+    async generate(input, _options) {
+        const sortedModules = [...input.modules].sort(compareInterfaceModules);
+        const entryModules = sortedModules.filter((module) => module.role === 'entrypoint');
+        const keySymbols = collectKeyItems(sortedModules, (module) => module.exportedSymbols, (item) => `${item.moduleName}:${item.kind}:${item.name}`, 12);
+        const keyMethods = collectKeyItems(sortedModules, (module) => module.publicMethods, (item) => `${item.moduleName}:${item.ownerName ?? 'module'}:${item.kind}:${item.name}`, 12);
+        const totalSymbols = sortedModules.reduce((sum, module) => sum + module.exportedSymbols.length, 0);
+        const totalMethods = sortedModules.reduce((sum, module) => sum + module.publicMethods.length, 0);
+        return {
+            title: `Interface Surface: ${input.projectName}`,
+            generatedAt: new Date().toISOString().split('T')[0],
+            projectName: input.projectName,
+            summary: buildSummary(input.projectName, sortedModules, totalSymbols, totalMethods),
+            modules: sortedModules,
+            entryModules,
+            keySymbols,
+            keyMethods,
+            totalModules: sortedModules.length,
+            totalSymbols,
+            totalMethods,
+            warnings: input.warnings,
+        };
+    }
+    render(output) {
+        const template = loadTemplate('interface-surface.hbs', import.meta.url);
+        return template(output);
+    }
+}
+function collectInterfaceModules(context) {
+    const storedModules = discoverStoredSpecPaths(context)
+        .map((specPath) => parseStoredModuleSpec(specPath, context.projectRoot))
+        .filter((record) => record !== null);
+    const interfaceModules = storedModules
+        .map((record) => toInterfaceModule(record))
+        .filter((module) => module !== null);
+    const highSignalModules = interfaceModules.filter((module) => !isLowSignalPath(module.sourceTarget));
+    return highSignalModules.length > 0 ? highSignalModules : interfaceModules;
+}
+function discoverStoredSpecPaths(context) {
+    const seen = new Set();
+    const specPaths = [];
+    for (const existingSpec of context.existingSpecs) {
+        seen.add(existingSpec);
+        specPaths.push(existingSpec);
+    }
+    walkStoredSpecPaths(context.projectRoot, specPaths, seen);
+    return specPaths.sort((left, right) => left.localeCompare(right));
+}
+function walkStoredSpecPaths(dir, results, seen) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.isSymbolicLink()) {
+            continue;
+        }
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (IGNORED_DISCOVERY_DIRS.has(entry.name)) {
+                continue;
+            }
+            walkStoredSpecPaths(fullPath, results, seen);
+            continue;
+        }
+        if (entry.isFile()
+            && entry.name.endsWith('.spec.md')
+            && entry.name !== '_index.spec.md'
+            && !seen.has(fullPath)) {
+            seen.add(fullPath);
+            results.push(fullPath);
+        }
+    }
+}
+function toInterfaceModule(record) {
+    const exportedSymbols = collectPublicSymbols(record);
+    const publicMethods = collectPublicMethods(record);
+    if (exportedSymbols.length === 0 && publicMethods.length === 0) {
+        return null;
+    }
+    return {
+        sourceTarget: record.sourceTarget,
+        displayName: record.sourceTarget,
+        role: classifyRole(record.sourceTarget),
+        confidence: record.confidence,
+        summary: pickFirstNonEmpty([
+            record.intentSummary,
+            record.businessSummary,
+            record.dependencySummary,
+            `${record.sourceTarget} 暴露项目的公开接口与关键入口`,
+        ]),
+        relatedFiles: record.relatedFiles,
+        exportedSymbols,
+        publicMethods,
+    };
+}
+function collectPublicSymbols(record) {
+    return (record.baselineSkeleton?.exports ?? [])
+        .filter((symbol) => PUBLIC_SYMBOL_KINDS.has(symbol.kind) && isPublicName(symbol.name))
+        .map((symbol) => ({
+        moduleName: record.sourceTarget,
+        name: symbol.name,
+        kind: symbol.kind,
+        signature: symbol.signature,
+        note: summarizeSymbolNote(symbol, record.intentSummary),
+        inferred: record.confidence === 'low',
+    }))
+        .sort(compareInterfaceSymbols);
+}
+function collectPublicMethods(record) {
+    const methods = [];
+    for (const symbol of record.baselineSkeleton?.exports ?? []) {
+        if (symbol.kind === 'function' && isPublicName(symbol.name)) {
+            methods.push({
+                moduleName: record.sourceTarget,
+                name: symbol.name,
+                kind: 'function',
+                signature: symbol.signature,
+                note: summarizeSymbolNote(symbol, record.businessSummary),
+                inferred: record.confidence === 'low',
+            });
+        }
+        for (const member of symbol.members ?? []) {
+            if (!PUBLIC_MEMBER_KINDS.has(member.kind)) {
+                continue;
+            }
+            if (member.visibility === 'private' || !isPublicName(member.name) || member.kind === 'constructor') {
+                continue;
+            }
+            methods.push({
+                moduleName: record.sourceTarget,
+                ownerName: symbol.name,
+                name: member.name,
+                kind: member.kind,
+                signature: member.signature,
+                note: summarizeMemberNote(member, symbol.name, record.businessSummary),
+                inferred: record.confidence === 'low',
+            });
+        }
+    }
+    return methods.sort(compareInterfaceSymbols);
+}
+function looksLikeLibrarySdkProject(context, modules) {
+    if (modules.length === 0) {
+        return false;
+    }
+    if (looksLikeNodeLibrary(context.projectRoot) || looksLikePythonLibrary(context.projectRoot)) {
+        return true;
+    }
+    if (hasRuntimeArtifacts(context)) {
+        return false;
+    }
+    return modules.some((module) => module.role === 'entrypoint');
+}
+function looksLikeNodeLibrary(projectRoot) {
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    if (!fs.existsSync(packageJsonPath)) {
+        return false;
+    }
+    try {
+        const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+        if (pkg.exports || pkg.main || pkg.module || pkg.types || pkg.typings) {
+            return true;
+        }
+        const keywords = Array.isArray(pkg.keywords)
+            ? pkg.keywords.filter((item) => typeof item === 'string')
+            : [];
+        return keywords.some((keyword) => /(sdk|library|client|plugin|toolkit|api-client)/i.test(keyword));
+    }
+    catch {
+        return false;
+    }
+}
+function looksLikePythonLibrary(projectRoot) {
+    const pyprojectPath = path.join(projectRoot, 'pyproject.toml');
+    if (!fs.existsSync(pyprojectPath)) {
+        return false;
+    }
+    try {
+        const content = fs.readFileSync(pyprojectPath, 'utf-8');
+        return /^\[project\]/m.test(content) || /^\[tool\.poetry\]/m.test(content);
+    }
+    catch {
+        return false;
+    }
+}
+function hasRuntimeArtifacts(context) {
+    const runtimeFiles = ['Dockerfile', 'docker-compose.yml', 'docker-compose.yaml'];
+    return runtimeFiles.some((fileName) => context.configFiles.has(fileName) || fs.existsSync(path.join(context.projectRoot, fileName)));
+}
+function detectProjectName(projectRoot) {
+    const packageJsonPath = path.join(projectRoot, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+            if (typeof pkg.name === 'string' && pkg.name.trim().length > 0) {
+                return pkg.name.trim();
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    const pyprojectPath = path.join(projectRoot, 'pyproject.toml');
+    if (fs.existsSync(pyprojectPath)) {
+        try {
+            const content = fs.readFileSync(pyprojectPath, 'utf-8');
+            const match = content.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
+            if (match?.[1]) {
+                return match[1];
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return path.basename(projectRoot);
+}
+function classifyRole(sourceTarget) {
+    if (ENTRYPOINT_FILE_PATTERN.test(sourceTarget)) {
+        return 'entrypoint';
+    }
+    if (CORE_SIGNAL_PATTERN.test(sourceTarget)) {
+        return 'core';
+    }
+    return 'support';
+}
+function isLowSignalPath(sourceTarget) {
+    return LOW_SIGNAL_PATH_PATTERN.test(sourceTarget);
+}
+function isPublicName(name) {
+    return name.length > 0 && !name.startsWith('_');
+}
+function summarizeSymbolNote(symbol, fallback) {
+    return pickFirstNonEmpty([
+        symbol.jsDoc ?? '',
+        symbol.kind === 'class' ? `${symbol.name} 是公开类入口` : '',
+        symbol.kind === 'function' ? `${symbol.name} 是公开函数入口` : '',
+        fallback,
+    ]);
+}
+function summarizeMemberNote(member, ownerName, fallback) {
+    return pickFirstNonEmpty([
+        member.jsDoc ?? '',
+        `${ownerName}.${member.name} 是对外可见的 ${member.kind}`,
+        fallback,
+    ]);
+}
+function pickFirstNonEmpty(values) {
+    return values.find((value) => value.trim().length > 0)?.trim() ?? '';
+}
+function compareInterfaceModules(left, right) {
+    return moduleScore(right) - moduleScore(left)
+        || right.exportedSymbols.length - left.exportedSymbols.length
+        || right.publicMethods.length - left.publicMethods.length
+        || left.sourceTarget.localeCompare(right.sourceTarget);
+}
+function moduleScore(module) {
+    const roleWeight = module.role === 'entrypoint'
+        ? 60
+        : module.role === 'core'
+            ? 40
+            : 20;
+    const confidenceWeight = module.confidence === 'high'
+        ? 12
+        : module.confidence === 'medium'
+            ? 6
+            : 0;
+    const signalWeight = CORE_SIGNAL_PATTERN.test(module.sourceTarget) ? 6 : 0;
+    const lowSignalPenalty = isLowSignalPath(module.sourceTarget) ? 30 : 0;
+    return roleWeight + confidenceWeight + signalWeight - lowSignalPenalty;
+}
+function compareInterfaceSymbols(left, right) {
+    return symbolWeight(right) - symbolWeight(left)
+        || left.name.localeCompare(right.name)
+        || left.moduleName.localeCompare(right.moduleName);
+}
+function symbolWeight(symbol) {
+    const kindWeight = symbol.kind === 'class'
+        ? 30
+        : symbol.kind === 'function'
+            ? 25
+            : symbol.kind === 'method' || symbol.kind === 'classmethod' || symbol.kind === 'staticmethod'
+                ? 22
+                : 16;
+    const ownerWeight = symbol.ownerName ? 5 : 0;
+    const inferredPenalty = symbol.inferred ? 6 : 0;
+    return kindWeight + ownerWeight - inferredPenalty;
+}
+function collectKeyItems(modules, selector, keySelector, limit) {
+    const seen = new Set();
+    const items = [];
+    for (const module of modules) {
+        const sortedItems = [...selector(module)].sort(compareInterfaceSymbols);
+        for (const item of sortedItems) {
+            const key = keySelector(item);
+            if (seen.has(key)) {
+                continue;
+            }
+            seen.add(key);
+            items.push(item);
+            if (items.length >= limit) {
+                return items;
+            }
+        }
+    }
+    return items;
+}
+function buildSummary(projectName, modules, totalSymbols, totalMethods) {
+    const entryModules = modules.filter((module) => module.role === 'entrypoint');
+    const coreModules = modules.filter((module) => module.role !== 'support');
+    return [
+        `${projectName} 当前识别出 ${modules.length} 个公开接口模块，其中 ${entryModules.length} 个为 entrypoint。`,
+        `共提取 ${totalSymbols} 个公开符号与 ${totalMethods} 个关键方法，优先围绕 SDK / library 的公开入口组织。`,
+        coreModules.length > 0
+            ? `核心接口模块集中在 ${coreModules.slice(0, 3).map((module) => `\`${module.sourceTarget}\``).join('、')}。`
+            : '当前未识别出高信号核心模块，输出已保守降级为现有公开符号摘要。',
+    ];
+}
+//# sourceMappingURL=interface-surface-generator.js.map

package/dist/panoramic/interface-surface-generator.js.map

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

package/dist/panoramic/interfaces.d.ts

@@ -35,12 +35,12 @@ export declare const GenerateOptionsSchema: z.ZodObject<{
     outputFormat: z.ZodDefault<z.ZodOptional<z.ZodEnum<["markdown", "json", "all"]>>>;
 }, "strip", z.ZodTypeAny, {
     useLLM: boolean;
-    outputFormat: "json" | "markdown" | "all";
+    outputFormat: "markdown" | "json" | "all";
     templateOverride?: string | undefined;
 }, {
     useLLM?: boolean | undefined;
     templateOverride?: string | undefined;
-    outputFormat?: "json" | "markdown" | "all" | undefined;
+    outputFormat?: "markdown" | "json" | "all" | undefined;
 }>;
 /** 文档生成通用选项类型 */
 export type GenerateOptions = z.infer<typeof GenerateOptionsSchema>;

package/dist/panoramic/mock-readme-generator.d.ts

@@ -0,0 +1,90 @@
+/**
+ * MockReadmeGenerator — 接口设计验证用的 Mock 实现
+ * 模拟一个 README 文档生成器，从 ProjectContext 的 package.json 信息中
+ * 提取项目名称和描述，生成简单的 README Markdown。
+ *
+ * 唯一目的：验证 DocumentGenerator 接口的四步生命周期在实际使用中是可行的。
+ */
+import type { DocumentGenerator, ProjectContext, GenerateOptions } from './interfaces.js';
+/**
+ * MockReadmeGenerator 的 extract() 输出类型
+ * 从 package.json 中提取的项目基本信息
+ */
+export interface ReadmeInput {
+    /** 项目名称（从 package.json 的 name 字段提取） */
+    projectName: string;
+    /** 项目描述（从 package.json 的 description 字段提取） */
+    description: string;
+    /** 是否存在 package.json */
+    hasPackageJson: boolean;
+}
+/**
+ * README 文档的单个章节
+ */
+export interface ReadmeSection {
+    /** 章节标题 */
+    heading: string;
+    /** 章节内容 */
+    content: string;
+}
+/**
+ * MockReadmeGenerator 的 generate() 输出类型
+ * 结构化的 README 文档数据
+ */
+export interface ReadmeOutput {
+    /** README 标题 */
+    title: string;
+    /** 项目描述段落 */
+    description: string;
+    /** README 的各个章节 */
+    sections: ReadmeSection[];
+}
+/**
+ * Mock README 文档生成器
+ * 实现 DocumentGenerator<ReadmeInput, ReadmeOutput> 接口的全部方法，
+ * 作为接口设计的冒烟验证。
+ *
+ * 生命周期：isApplicable -> extract -> generate -> render
+ */
+export declare class MockReadmeGenerator implements DocumentGenerator<ReadmeInput, ReadmeOutput> {
+    /** 唯一标识符 */
+    readonly id: "mock-readme";
+    /** 显示名称 */
+    readonly name: "Mock README Generator";
+    /** 功能描述 */
+    readonly description = "\u4ECE package.json \u63D0\u53D6\u9879\u76EE\u4FE1\u606F\uFF0C\u751F\u6210\u7B80\u5355\u7684 README.md \u6587\u6863";
+    /**
+     * 判断当前项目是否适用此 Generator
+     * 同步检查 configFiles 中是否包含 package.json
+     *
+     * @param context - 项目上下文
+     * @returns 如果 configFiles 包含 package.json 则返回 true
+     */
+    isApplicable(context: ProjectContext): boolean;
+    /**
+     * 从项目上下文中提取 README 所需的输入数据
+     * 读取 package.json 内容提取 name 和 description，缺失时使用默认值
+     *
+     * @param context - 项目上下文
+     * @returns ReadmeInput 数据
+     */
+    extract(context: ProjectContext): Promise<ReadmeInput>;
+    /**
+     * 将 ReadmeInput 转换为 ReadmeOutput
+     * 生成包含 Installation 和 Usage 两个默认 section 的文档结构
+     *
+     * @param input - extract 步骤的输出
+     * @param _options - 生成选项（当前未使用）
+     * @returns ReadmeOutput 文档结构
+     */
+    generate(input: ReadmeInput, _options?: GenerateOptions): Promise<ReadmeOutput>;
+    /**
+     * 将 ReadmeOutput 渲染为 Markdown 字符串
+     * 同步拼接标题 + 描述 + sections
+     *
+     * @param output - generate 步骤的输出
+     * @returns Markdown 字符串
+     */
+    render(output: ReadmeOutput): string;
+}
+//# sourceMappingURL=mock-readme-generator.d.ts.map

package/dist/panoramic/mock-readme-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-readme-generator.d.ts","sourceRoot":"","sources":["../../src/panoramic/mock-readme-generator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAM1F;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,gBAAgB;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB;IACnB,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAMD;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,iBAAiB,CAAC,WAAW,EAAE,YAAY,CAAC;IACtF,YAAY;IACZ,QAAQ,CAAC,EAAE,EAAG,aAAa,CAAU;IAErC,WAAW;IACX,QAAQ,CAAC,IAAI,EAAG,uBAAuB,CAAU;IAEjD,WAAW;IACX,QAAQ,CAAC,WAAW,yHAA8C;IAElE;;;;;;OAMG;IACH,YAAY,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO;IAI9C;;;;;;OAMG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC;IA2B5D;;;;;;;OAOG;IACG,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,CAAC;IAmBrF;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM;CAqBrC"}

package/dist/panoramic/mock-readme-generator.js

@@ -0,0 +1,111 @@
+// ============================================================
+// MockReadmeGenerator 实现
+// ============================================================
+/**
+ * Mock README 文档生成器
+ * 实现 DocumentGenerator<ReadmeInput, ReadmeOutput> 接口的全部方法，
+ * 作为接口设计的冒烟验证。
+ *
+ * 生命周期：isApplicable -> extract -> generate -> render
+ */
+export class MockReadmeGenerator {
+    /** 唯一标识符 */
+    id = 'mock-readme';
+    /** 显示名称 */
+    name = 'Mock README Generator';
+    /** 功能描述 */
+    description = '从 package.json 提取项目信息，生成简单的 README.md 文档';
+    /**
+     * 判断当前项目是否适用此 Generator
+     * 同步检查 configFiles 中是否包含 package.json
+     *
+     * @param context - 项目上下文
+     * @returns 如果 configFiles 包含 package.json 则返回 true
+     */
+    isApplicable(context) {
+        return context.configFiles.has('package.json');
+    }
+    /**
+     * 从项目上下文中提取 README 所需的输入数据
+     * 读取 package.json 内容提取 name 和 description，缺失时使用默认值
+     *
+     * @param context - 项目上下文
+     * @returns ReadmeInput 数据
+     */
+    async extract(context) {
+        const packageJsonContent = context.configFiles.get('package.json');
+        if (!packageJsonContent) {
+            return {
+                projectName: 'unknown-project',
+                description: 'No description provided',
+                hasPackageJson: false,
+            };
+        }
+        try {
+            const parsed = JSON.parse(packageJsonContent);
+            return {
+                projectName: typeof parsed['name'] === 'string' ? parsed['name'] : 'unknown-project',
+                description: typeof parsed['description'] === 'string' ? parsed['description'] : 'No description provided',
+                hasPackageJson: true,
+            };
+        }
+        catch {
+            // JSON 解析失败，使用默认值
+            return {
+                projectName: 'unknown-project',
+                description: 'No description provided',
+                hasPackageJson: true,
+            };
+        }
+    }
+    /**
+     * 将 ReadmeInput 转换为 ReadmeOutput
+     * 生成包含 Installation 和 Usage 两个默认 section 的文档结构
+     *
+     * @param input - extract 步骤的输出
+     * @param _options - 生成选项（当前未使用）
+     * @returns ReadmeOutput 文档结构
+     */
+    async generate(input, _options) {
+        const sections = [
+            {
+                heading: 'Installation',
+                content: `npm install ${input.projectName}`,
+            },
+            {
+                heading: 'Usage',
+                content: `Import and use ${input.projectName} in your project.`,
+            },
+        ];
+        return {
+            title: input.projectName,
+            description: input.description,
+            sections,
+        };
+    }
+    /**
+     * 将 ReadmeOutput 渲染为 Markdown 字符串
+     * 同步拼接标题 + 描述 + sections
+     *
+     * @param output - generate 步骤的输出
+     * @returns Markdown 字符串
+     */
+    render(output) {
+        const lines = [];
+        // 标题
+        lines.push(`# ${output.title}`);
+        lines.push('');
+        // 描述
+        lines.push(output.description);
+        lines.push('');
+        // 各章节
+        for (const section of output.sections) {
+            lines.push(`## ${section.heading}`);
+            lines.push('');
+            lines.push(section.content);
+            lines.push('');
+        }
+        return lines.join('\n').trimEnd() + '\n';
+    }
+}
+//# sourceMappingURL=mock-readme-generator.js.map

package/dist/panoramic/mock-readme-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-readme-generator.js","sourceRoot":"","sources":["../../src/panoramic/mock-readme-generator.ts"],"names":[],"mappings":"AAiDA,+DAA+D;AAC/D,yBAAyB;AACzB,+DAA+D;AAE/D;;;;;;GAMG;AACH,MAAM,OAAO,mBAAmB;IAC9B,YAAY;IACH,EAAE,GAAG,aAAsB,CAAC;IAErC,WAAW;IACF,IAAI,GAAG,uBAAgC,CAAC;IAEjD,WAAW;IACF,WAAW,GAAG,0CAA0C,CAAC;IAElE;;;;;;OAMG;IACH,YAAY,CAAC,OAAuB;QAClC,OAAO,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,OAAuB;QACnC,MAAM,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACnE,IAAI,CAAC,kBAAkB,EAAE,CAAC;YACxB,OAAO;gBACL,WAAW,EAAE,iBAAiB;gBAC9B,WAAW,EAAE,yBAAyB;gBACtC,cAAc,EAAE,KAAK;aACtB,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,kBAAkB,CAA4B,CAAC;YACzE,OAAO;gBACL,WAAW,EAAE,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,iBAAiB;gBACpF,WAAW,EAAE,OAAO,MAAM,CAAC,aAAa,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,yBAAyB;gBAC1G,cAAc,EAAE,IAAI;aACrB,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;YAClB,OAAO;gBACL,WAAW,EAAE,iBAAiB;gBAC9B,WAAW,EAAE,yBAAyB;gBACtC,cAAc,EAAE,IAAI;aACrB,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,CAAC,KAAkB,EAAE,QAA0B;QAC3D,MAAM,QAAQ,GAAoB;YAChC;gBACE,OAAO,EAAE,cAAc;gBACvB,OAAO,EAAE,eAAe,KAAK,CAAC,WAAW,EAAE;aAC5C;YACD;gBACE,OAAO,EAAE,OAAO;gBAChB,OAAO,EAAE,kBAAkB,KAAK,CAAC,WAAW,mBAAmB;aAChE;SACF,CAAC;QAEF,OAAO;YACL,KAAK,EAAE,KAAK,CAAC,WAAW;YACxB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,QAAQ;SACT,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,MAAoB;QACzB,MAAM,KAAK,GAAa,EAAE,CAAC;QAE3B,KAAK;QACL,KAAK,CAAC,IAAI,CAAC,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEf,KAAK;QACL,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEf,MAAM;QACN,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACtC,KAAK,CAAC,IAAI,CAAC,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;YACpC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YAC5B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;IAC3C,CAAC;CACF"}

package/dist/panoramic/models/component-view-model.d.ts

@@ -4,7 +4,7 @@
  * 057 的共享结构边界，供 batch 文档层和后续 059 provenance / quality gate 复用。
  */
 export type ComponentConfidence = 'high' | 'medium' | 'low';
-export type ComponentEvidenceSourceType = 'architecture-ir' | 'module-spec' | 'baseline-skeleton' | 'architecture-narrative' | 'runtime-topology' | 'event-surface' | 'test-file';
+export type ComponentEvidenceSourceType = 'architecture-ir' | 'module-spec' | 'baseline-skeleton' | 'architecture-narrative' | 'runtime-topology' | 'event-surface' | 'test-file' | 'unified-graph';
 export type ComponentCategory = 'client' | 'query' | 'transport' | 'parser' | 'session' | 'store' | 'adapter' | 'service' | 'module' | 'external';
 export type ComponentMethodKind = 'entrypoint' | 'transport' | 'parser' | 'session' | 'event-handler' | 'supporting';
 export type ComponentRelationshipKind = 'depends-on' | 'calls' | 'uses-transport' | 'parses' | 'publishes' | 'subscribes' | 'manages-session' | 'hosts';