spectra-cli 4.1.1

package/dist/panoramic/hyperedges/schema.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Hyperedge Zod schema 定义
+ *
+ * 校验 LLM 输出的超边结构，确保：
+ * - label 最多 8 个 Unicode 字符
+ * - nodes 至少 3 个（语义上混合节点约束由 extractor.ts 做语义校验）
+ * - rationale 非空且最多 200 字符
+ * - confidence 为三级枚举之一
+ * - 每 batch 最多 10 个 hyperedge（FR-018）
+ */
+import { z } from 'zod';
+/**
+ * 单条超边的 Zod schema
+ *
+ * label 使用 refine 做严格 Unicode grapheme 计数（每个中文字符算 1 个）
+ */
+export declare const HyperedgeSchema: z.ZodObject<{
+    /** 超边唯一标识符 */
+    id: z.ZodString;
+    /** 超边标签：最多 8 个 Unicode 字符 */
+    label: z.ZodEffects<z.ZodString, string, string>;
+    /** 参与节点 ID 列表：至少 3 个 */
+    nodes: z.ZodArray<z.ZodString, "many">;
+    /** LLM 提取的设计依据：非空，最多 200 字符 */
+    rationale: z.ZodString;
+    /** 置信度：三级枚举 */
+    confidence: z.ZodEnum<["EXTRACTED", "INFERRED", "AMBIGUOUS"]>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    nodes: string[];
+    label: string;
+    confidence: "EXTRACTED" | "INFERRED" | "AMBIGUOUS";
+    rationale: string;
+}, {
+    id: string;
+    nodes: string[];
+    label: string;
+    confidence: "EXTRACTED" | "INFERRED" | "AMBIGUOUS";
+    rationale: string;
+}>;
+/**
+ * LLM batch 输出的 Zod schema
+ * LLM 需返回包含 hyperedges 数组的 JSON 对象
+ */
+export declare const HyperedgesOutputSchema: z.ZodObject<{
+    hyperedges: z.ZodArray<z.ZodObject<{
+        /** 超边唯一标识符 */
+        id: z.ZodString;
+        /** 超边标签：最多 8 个 Unicode 字符 */
+        label: z.ZodEffects<z.ZodString, string, string>;
+        /** 参与节点 ID 列表：至少 3 个 */
+        nodes: z.ZodArray<z.ZodString, "many">;
+        /** LLM 提取的设计依据：非空，最多 200 字符 */
+        rationale: z.ZodString;
+        /** 置信度：三级枚举 */
+        confidence: z.ZodEnum<["EXTRACTED", "INFERRED", "AMBIGUOUS"]>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        nodes: string[];
+        label: string;
+        confidence: "EXTRACTED" | "INFERRED" | "AMBIGUOUS";
+        rationale: string;
+    }, {
+        id: string;
+        nodes: string[];
+        label: string;
+        confidence: "EXTRACTED" | "INFERRED" | "AMBIGUOUS";
+        rationale: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    hyperedges: {
+        id: string;
+        nodes: string[];
+        label: string;
+        confidence: "EXTRACTED" | "INFERRED" | "AMBIGUOUS";
+        rationale: string;
+    }[];
+}, {
+    hyperedges: {
+        id: string;
+        nodes: string[];
+        label: string;
+        confidence: "EXTRACTED" | "INFERRED" | "AMBIGUOUS";
+        rationale: string;
+    }[];
+}>;
+/** 单条 hyperedge 的输入类型（Zod 推断） */
+export type HyperedgeInput = z.infer<typeof HyperedgeSchema>;
+/** LLM batch 输出类型（Zod 推断） */
+export type HyperedgeOutput = z.infer<typeof HyperedgesOutputSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/panoramic/hyperedges/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/panoramic/hyperedges/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;;;GAIG;AACH,eAAO,MAAM,eAAe;IAC1B,cAAc;;IAEd,6BAA6B;;IAK7B,wBAAwB;;IAIxB,+BAA+B;;IAK/B,eAAe;;;;;;;;;;;;;;EAEf,CAAC;AAMH;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;QA5BjC,cAAc;;QAEd,6BAA6B;;QAK7B,wBAAwB;;QAIxB,+BAA+B;;QAK/B,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgBf,CAAC;AAMH,iCAAiC;AACjC,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE7D,6BAA6B;AAC7B,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}

package/dist/panoramic/hyperedges/schema.js

@@ -0,0 +1,52 @@
+/**
+ * Hyperedge Zod schema 定义
+ *
+ * 校验 LLM 输出的超边结构，确保：
+ * - label 最多 8 个 Unicode 字符
+ * - nodes 至少 3 个（语义上混合节点约束由 extractor.ts 做语义校验）
+ * - rationale 非空且最多 200 字符
+ * - confidence 为三级枚举之一
+ * - 每 batch 最多 10 个 hyperedge（FR-018）
+ */
+import { z } from 'zod';
+// ============================================================
+// 单条 Hyperedge schema
+// ============================================================
+/**
+ * 单条超边的 Zod schema
+ *
+ * label 使用 refine 做严格 Unicode grapheme 计数（每个中文字符算 1 个）
+ */
+export const HyperedgeSchema = z.object({
+    /** 超边唯一标识符 */
+    id: z.string().min(1),
+    /** 超边标签：最多 8 个 Unicode 字符 */
+    label: z
+        .string()
+        .min(1, { message: 'hyperedge label 不能为空' })
+        .refine((v) => [...v].length <= 8, { message: 'hyperedge label 最多 8 个 Unicode 字符' }),
+    /** 参与节点 ID 列表：至少 3 个 */
+    nodes: z
+        .array(z.string().min(1))
+        .min(3, { message: 'hyperedge nodes 至少需要 3 个节点' }),
+    /** LLM 提取的设计依据：非空，最多 200 字符 */
+    rationale: z
+        .string()
+        .min(1, { message: 'hyperedge rationale 不能为空' })
+        .max(200, { message: 'hyperedge rationale 最多 200 字符' }),
+    /** 置信度：三级枚举 */
+    confidence: z.enum(['EXTRACTED', 'INFERRED', 'AMBIGUOUS']),
+});
+// ============================================================
+// Batch 输出 schema（每 batch 最多 10 条）
+// ============================================================
+/**
+ * LLM batch 输出的 Zod schema
+ * LLM 需返回包含 hyperedges 数组的 JSON 对象
+ */
+export const HyperedgesOutputSchema = z.object({
+    hyperedges: z
+        .array(HyperedgeSchema)
+        .max(10, { message: '每 batch 最多 10 个 hyperedge' }),
+});
+//# sourceMappingURL=schema.js.map

package/dist/panoramic/hyperedges/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/panoramic/hyperedges/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+DAA+D;AAC/D,sBAAsB;AACtB,+DAA+D;AAE/D;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,cAAc;IACd,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACrB,6BAA6B;IAC7B,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,sBAAsB,EAAE,CAAC;SAC3C,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,mCAAmC,EAAE,CAAC;IACtF,wBAAwB;IACxB,KAAK,EAAE,CAAC;SACL,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACxB,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,4BAA4B,EAAE,CAAC;IACpD,+BAA+B;IAC/B,SAAS,EAAE,CAAC;SACT,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,0BAA0B,EAAE,CAAC;SAC/C,GAAG,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,+BAA+B,EAAE,CAAC;IACzD,eAAe;IACf,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;CAC3D,CAAC,CAAC;AAEH,+DAA+D;AAC/D,mCAAmC;AACnC,+DAA+D;AAE/D;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,UAAU,EAAE,CAAC;SACV,KAAK,CAAC,eAAe,CAAC;SACtB,GAAG,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,2BAA2B,EAAE,CAAC;CACrD,CAAC,CAAC"}

package/dist/panoramic/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * panoramic 模块 — 公共 API 导出
+ *
+ * 仅包含经审计确认的 15 个稳定公共 API 符号。
+ * 内部实现类型、Generator 实现、细粒度模型类型等请从 internal.ts 导入。
+ */
+export { bootstrapGenerators } from './generator-registry.js';
+export { bootstrapParsers } from './parser-registry.js';
+export { buildProjectContext } from './project-context.js';
+export { CoverageAuditor } from './pipelines/coverage-auditor.js';
+export { orchestrateDocsBundle } from './pipelines/docs-bundle-orchestrator.js';
+export type { DocsBundleProfileSummary } from './models/docs-bundle-types.js';
+export { loadTemplate } from './utils/template-loader.js';
+export { buildDocGraph, scanStoredModuleSpecs, resolveSpecForSource, type StoredModuleSpecSummary, } from './builders/doc-graph-builder.js';
+export { buildCrossReferenceIndex } from './cross-reference-index.js';
+export { generateBatchProjectDocs, generateDocsQualityReport, type BatchProjectDocsResult, } from './batch-project-docs.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/panoramic/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAGlE,OAAO,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AAChF,YAAY,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAG9E,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG1D,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,oBAAoB,EACpB,KAAK,uBAAuB,GAC7B,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,KAAK,sBAAsB,GAC5B,MAAM,yBAAyB,CAAC"}

package/dist/panoramic/index.js

@@ -0,0 +1,22 @@
+/**
+ * panoramic 模块 — 公共 API 导出
+ *
+ * 仅包含经审计确认的 15 个稳定公共 API 符号。
+ * 内部实现类型、Generator 实现、细粒度模型类型等请从 internal.ts 导入。
+ */
+// Registry 启动函数
+export { bootstrapGenerators } from './generator-registry.js';
+export { bootstrapParsers } from './parser-registry.js';
+// 上下文构建
+export { buildProjectContext } from './project-context.js';
+// 覆盖率审计
+export { CoverageAuditor } from './pipelines/coverage-auditor.js';
+// 文档 Bundle 编排
+export { orchestrateDocsBundle } from './pipelines/docs-bundle-orchestrator.js';
+// 模板加载
+export { loadTemplate } from './utils/template-loader.js';
+// DocGraph、Spec 索引与批量生成（批量链路核心）
+export { buildDocGraph, scanStoredModuleSpecs, resolveSpecForSource, } from './builders/doc-graph-builder.js';
+export { buildCrossReferenceIndex } from './cross-reference-index.js';
+export { generateBatchProjectDocs, generateDocsQualityReport, } from './batch-project-docs.js';
+//# sourceMappingURL=index.js.map

package/dist/panoramic/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/panoramic/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,gBAAgB;AAChB,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,QAAQ;AACR,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,QAAQ;AACR,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,eAAe;AACf,OAAO,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AAGhF,OAAO;AACP,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,gCAAgC;AAChC,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,oBAAoB,GAErB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAEtE,OAAO,EACL,wBAAwB,EACxB,yBAAyB,GAE1B,MAAM,yBAAyB,CAAC"}

package/dist/panoramic/interfaces.d.ts

@@ -0,0 +1,243 @@
+/**
+ * 全景文档化核心接口定义
+ * DocumentGenerator + ArtifactParser 泛型接口 + Zod Schema + 辅助类型
+ *
+ * 文件组织顺序（参考 code-skeleton.ts 的 Zod + type 同文件模式）：
+ * 1. 导入（zod）
+ * 2. OutputFormat 枚举 Schema + type
+ * 3. GenerateOptions Schema + type
+ * 4. ProjectContext Schema + type（最小占位版本）
+ * 5. GeneratorMetadata Schema + type
+ * 6. ArtifactParserMetadata Schema + type
+ * 7. DocumentGenerator<TInput, TOutput> interface
+ * 8. ArtifactParser<T> interface
+ */
+import { z } from 'zod';
+/**
+ * 输出格式枚举 Schema
+ * 支持 markdown（默认）、json（结构化数据）、all（markdown + json + mermaid）
+ */
+export declare const OutputFormatSchema: z.ZodEnum<["markdown", "json", "all"]>;
+/** 输出格式类型 */
+export type OutputFormat = z.infer<typeof OutputFormatSchema>;
+/**
+ * 文档生成通用选项 Schema
+ * - useLLM: 是否启用 LLM 增强生成（默认 false）
+ * - templateOverride: 自定义 Handlebars 模板路径
+ * - outputFormat: 输出格式（默认 'markdown'）
+ */
+export declare const GenerateOptionsSchema: z.ZodObject<{
+    /** 是否启用 LLM 增强生成。false 时仅使用 AST/正则分析 */
+    useLLM: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    /** 自定义 Handlebars 模板路径。未指定时使用内置模板 */
+    templateOverride: z.ZodOptional<z.ZodString>;
+    /** 输出格式。支持 'markdown'（默认）、'json'（结构化数据）、'all'（全格式输出） */
+    outputFormat: z.ZodDefault<z.ZodOptional<z.ZodEnum<["markdown", "json", "all"]>>>;
+}, "strip", z.ZodTypeAny, {
+    useLLM: boolean;
+    outputFormat: "json" | "markdown" | "all";
+    templateOverride?: string | undefined;
+}, {
+    useLLM?: boolean | undefined;
+    templateOverride?: string | undefined;
+    outputFormat?: "json" | "markdown" | "all" | undefined;
+}>;
+/** 文档生成通用选项类型 */
+export type GenerateOptions = z.infer<typeof GenerateOptionsSchema>;
+/**
+ * 包管理器枚举 Schema
+ * 11 个枚举值：npm/yarn/pnpm/pip/uv/poetry/go/maven/gradle/pipenv/unknown
+ * pip 为 pyproject.toml 存在但无特定工具链标识时的降级值
+ * poetry 由 pyproject.toml 中 [tool.poetry] 段触发
+ * unknown 为无法识别时的默认值
+ */
+export declare const PackageManagerSchema: z.ZodEnum<["npm", "yarn", "pnpm", "pip", "uv", "poetry", "go", "maven", "gradle", "pipenv", "unknown"]>;
+/** 包管理器类型 */
+export type PackageManager = z.infer<typeof PackageManagerSchema>;
+/**
+ * Workspace 类型枚举 Schema
+ * single: 单包项目; monorepo: 多包/工作区项目
+ */
+export declare const WorkspaceTypeSchema: z.ZodEnum<["single", "monorepo"]>;
+/** Workspace 类型 */
+export type WorkspaceType = z.infer<typeof WorkspaceTypeSchema>;
+/**
+ * 项目上下文 Schema（完整版本）
+ * 在基础版上扩展四个新属性，全部提供 .default() 值以保持向后兼容
+ * - packageManager: 检测到的包管理器类型（默认 'unknown'）
+ * - workspaceType: 项目类型（默认 'single'）
+ * - detectedLanguages: 检测到的编程语言列表（默认 []）
+ * - existingSpecs: 已有 spec 文件绝对路径列表（默认 []）
+ */
+export declare const ProjectContextSchema: z.ZodObject<{
+    /** 项目根目录绝对路径 */
+    projectRoot: z.ZodString;
+    /** 已识别的配置文件映射（文件名 -> 绝对路径） */
+    configFiles: z.ZodMap<z.ZodString, z.ZodString>;
+} & {
+    /** 检测到的包管理器类型 */
+    packageManager: z.ZodDefault<z.ZodEnum<["npm", "yarn", "pnpm", "pip", "uv", "poetry", "go", "maven", "gradle", "pipenv", "unknown"]>>;
+    /** 项目类型——单包或 Monorepo */
+    workspaceType: z.ZodDefault<z.ZodEnum<["single", "monorepo"]>>;
+    /** 检测到的编程语言适配器 ID 列表 */
+    detectedLanguages: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** 已有 spec 文件的绝对路径列表 */
+    existingSpecs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    projectRoot: string;
+    configFiles: Map<string, string>;
+    packageManager: "go" | "unknown" | "npm" | "yarn" | "pnpm" | "pip" | "uv" | "poetry" | "maven" | "gradle" | "pipenv";
+    workspaceType: "single" | "monorepo";
+    detectedLanguages: string[];
+    existingSpecs: string[];
+}, {
+    projectRoot: string;
+    configFiles: Map<string, string>;
+    packageManager?: "go" | "unknown" | "npm" | "yarn" | "pnpm" | "pip" | "uv" | "poetry" | "maven" | "gradle" | "pipenv" | undefined;
+    workspaceType?: "single" | "monorepo" | undefined;
+    detectedLanguages?: string[] | undefined;
+    existingSpecs?: string[] | undefined;
+}>;
+/** 项目上下文类型（完整版本） */
+export type ProjectContext = z.infer<typeof ProjectContextSchema>;
+/**
+ * DocumentGenerator 元数据 Schema
+ * 用于运行时验证 Generator 的 id、name、description
+ * - id: kebab-case 唯一标识符，匹配 /^[a-z][a-z0-9-]*$/
+ * - name: 显示名称（非空）
+ * - description: 功能描述（非空）
+ */
+export declare const GeneratorMetadataSchema: z.ZodObject<{
+    /** 唯一标识符，kebab-case 格式 */
+    id: z.ZodString;
+    /** 显示名称 */
+    name: z.ZodString;
+    /** 功能描述 */
+    description: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    description: string;
+}, {
+    name: string;
+    id: string;
+    description: string;
+}>;
+/** DocumentGenerator 元数据类型 */
+export type GeneratorMetadata = z.infer<typeof GeneratorMetadataSchema>;
+/**
+ * ArtifactParser 元数据 Schema
+ * 用于运行时验证 Parser 的 id、name、filePatterns
+ * - id: kebab-case 唯一标识符
+ * - name: 显示名称（非空）
+ * - filePatterns: 支持的文件匹配模式（glob 格式，至少一个）
+ */
+export declare const ArtifactParserMetadataSchema: z.ZodObject<{
+    /** 唯一标识符，kebab-case 格式 */
+    id: z.ZodString;
+    /** 显示名称 */
+    name: z.ZodString;
+    /** 支持的文件匹配模式（glob 格式），至少包含一个 */
+    filePatterns: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    id: string;
+    filePatterns: string[];
+}, {
+    name: string;
+    id: string;
+    filePatterns: string[];
+}>;
+/** ArtifactParser 元数据类型 */
+export type ArtifactParserMetadata = z.infer<typeof ArtifactParserMetadataSchema>;
+/**
+ * 文档生成策略接口
+ * 定义从项目中提取信息并生成特定类型文档的统一契约。
+ * 采用 Strategy 模式，与现有 LanguageAdapter 接口设计一致。
+ *
+ * 生命周期：isApplicable -> extract -> generate -> render
+ *
+ * @typeParam TInput - extract 步骤的输出数据结构
+ * @typeParam TOutput - generate 步骤的输出数据结构
+ */
+export interface DocumentGenerator<TInput, TOutput> {
+    /** 唯一标识符，用于 GeneratorRegistry 注册和查询（kebab-case） */
+    readonly id: string;
+    /** 显示名称，用于日志和 CLI 输出 */
+    readonly name: string;
+    /** 功能描述，用于 help 信息和 MCP 工具描述 */
+    readonly description: string;
+    /**
+     * 判断当前项目是否适用此 Generator
+     * 支持同步/异步联合返回——轻量检查可同步，复杂分析可异步
+     *
+     * @param context - 项目上下文
+     * @returns 是否适用
+     */
+    isApplicable(context: ProjectContext): boolean | Promise<boolean>;
+    /**
+     * 从项目中提取该 Generator 需要的输入数据
+     * 强制异步——数据提取通常涉及文件 I/O
+     *
+     * @param context - 项目上下文
+     * @returns 提取的输入数据
+     */
+    extract(context: ProjectContext): Promise<TInput>;
+    /**
+     * 将提取的原始数据转换为结构化的文档输出对象
+     * 强制异步——转换可能涉及 LLM 调用
+     *
+     * @param input - extract 步骤的输出
+     * @param options - 生成选项（可选）
+     * @returns 结构化文档输出
+     */
+    generate(input: TInput, options?: GenerateOptions): Promise<TOutput>;
+    /**
+     * 将文档输出对象渲染为 Markdown 字符串
+     * 支持同步/异步联合返回——简单拼接可同步，复杂渲染可异步
+     *
+     * @param output - generate 步骤的输出
+     * @returns Markdown 字符串
+     */
+    render(output: TOutput): string | Promise<string>;
+    /**
+     * （可选）声明此 generator 依赖的文件路径列表
+     * 用于 ContentHasher 精确计算聚合 hash，提升缓存精度。
+     * 未实现时，CacheManager 退回到扫描 projectRoot 下所有源文件的 fallback 策略。
+     *
+     * 注意：应包含 generator 在 extract() 中直接读取的所有文件路径，
+     * 不仅是源代码文件，还包括依赖的配置文件路径（如 tsconfig.json、package.json 等）。
+     */
+    getDependencies?(context: ProjectContext): string[] | Promise<string[]>;
+}
+/**
+ * 非代码制品解析接口
+ * 定义非代码制品（SKILL.md、behavior YAML、Dockerfile 等）的解析契约。
+ * 与 LanguageAdapter 正交——LanguageAdapter 处理代码 AST，ArtifactParser 处理非代码制品。
+ *
+ * @typeParam T - parse 步骤的输出数据结构
+ */
+export interface ArtifactParser<T> {
+    /** 唯一标识符（如 'skill-md'、'dockerfile'） */
+    readonly id: string;
+    /** 显示名称（如 'SKILL.md Parser'） */
+    readonly name: string;
+    /** 支持的文件匹配模式，glob 格式（如 ['SKILL.md']） */
+    readonly filePatterns: readonly string[];
+    /**
+     * 解析单个制品文件，返回结构化数据
+     * 强制异步——文件读取为 I/O 操作
+     *
+     * @param filePath - 制品文件绝对路径
+     * @returns 结构化解析结果
+     */
+    parse(filePath: string): Promise<T>;
+    /**
+     * 批量解析多个同类制品文件
+     *
+     * @param filePaths - 制品文件路径数组
+     * @returns 解析结果数组
+     */
+    parseAll(filePaths: string[]): Promise<T[]>;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/panoramic/interfaces.d.ts.map

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

package/dist/panoramic/interfaces.js

@@ -0,0 +1,130 @@
+/**
+ * 全景文档化核心接口定义
+ * DocumentGenerator + ArtifactParser 泛型接口 + Zod Schema + 辅助类型
+ *
+ * 文件组织顺序（参考 code-skeleton.ts 的 Zod + type 同文件模式）：
+ * 1. 导入（zod）
+ * 2. OutputFormat 枚举 Schema + type
+ * 3. GenerateOptions Schema + type
+ * 4. ProjectContext Schema + type（最小占位版本）
+ * 5. GeneratorMetadata Schema + type
+ * 6. ArtifactParserMetadata Schema + type
+ * 7. DocumentGenerator<TInput, TOutput> interface
+ * 8. ArtifactParser<T> interface
+ */
+import { z } from 'zod';
+// ============================================================
+// OutputFormat 枚举
+// ============================================================
+/**
+ * 输出格式枚举 Schema
+ * 支持 markdown（默认）、json（结构化数据）、all（markdown + json + mermaid）
+ */
+export const OutputFormatSchema = z.enum(['markdown', 'json', 'all']);
+// ============================================================
+// GenerateOptions
+// ============================================================
+/**
+ * 文档生成通用选项 Schema
+ * - useLLM: 是否启用 LLM 增强生成（默认 false）
+ * - templateOverride: 自定义 Handlebars 模板路径
+ * - outputFormat: 输出格式（默认 'markdown'）
+ */
+export const GenerateOptionsSchema = z.object({
+    /** 是否启用 LLM 增强生成。false 时仅使用 AST/正则分析 */
+    useLLM: z.boolean().optional().default(false),
+    /** 自定义 Handlebars 模板路径。未指定时使用内置模板 */
+    templateOverride: z.string().optional(),
+    /** 输出格式。支持 'markdown'（默认）、'json'（结构化数据）、'all'（全格式输出） */
+    outputFormat: OutputFormatSchema.optional().default('markdown'),
+});
+// ============================================================
+// PackageManager 枚举
+// ============================================================
+/**
+ * 包管理器枚举 Schema
+ * 11 个枚举值：npm/yarn/pnpm/pip/uv/poetry/go/maven/gradle/pipenv/unknown
+ * pip 为 pyproject.toml 存在但无特定工具链标识时的降级值
+ * poetry 由 pyproject.toml 中 [tool.poetry] 段触发
+ * unknown 为无法识别时的默认值
+ */
+export const PackageManagerSchema = z.enum([
+    'npm', 'yarn', 'pnpm', 'pip', 'uv', 'poetry',
+    'go', 'maven', 'gradle', 'pipenv', 'unknown',
+]);
+// ============================================================
+// WorkspaceType 枚举
+// ============================================================
+/**
+ * Workspace 类型枚举 Schema
+ * single: 单包项目; monorepo: 多包/工作区项目
+ */
+export const WorkspaceTypeSchema = z.enum(['single', 'monorepo']);
+// ============================================================
+// ProjectContext（完整版本）
+// ============================================================
+/**
+ * 项目上下文基础 Schema（Feature 034 原始定义）
+ * 保留为内部常量，对外导出扩展后的完整版本
+ */
+const BaseProjectContextSchema = z.object({
+    /** 项目根目录绝对路径 */
+    projectRoot: z.string().min(1),
+    /** 已识别的配置文件映射（文件名 -> 绝对路径） */
+    configFiles: z.map(z.string(), z.string()),
+});
+/**
+ * 项目上下文 Schema（完整版本）
+ * 在基础版上扩展四个新属性，全部提供 .default() 值以保持向后兼容
+ * - packageManager: 检测到的包管理器类型（默认 'unknown'）
+ * - workspaceType: 项目类型（默认 'single'）
+ * - detectedLanguages: 检测到的编程语言列表（默认 []）
+ * - existingSpecs: 已有 spec 文件绝对路径列表（默认 []）
+ */
+export const ProjectContextSchema = BaseProjectContextSchema.extend({
+    /** 检测到的包管理器类型 */
+    packageManager: PackageManagerSchema.default('unknown'),
+    /** 项目类型——单包或 Monorepo */
+    workspaceType: WorkspaceTypeSchema.default('single'),
+    /** 检测到的编程语言适配器 ID 列表 */
+    detectedLanguages: z.array(z.string()).default([]),
+    /** 已有 spec 文件的绝对路径列表 */
+    existingSpecs: z.array(z.string()).default([]),
+});
+// ============================================================
+// GeneratorMetadata
+// ============================================================
+/**
+ * DocumentGenerator 元数据 Schema
+ * 用于运行时验证 Generator 的 id、name、description
+ * - id: kebab-case 唯一标识符，匹配 /^[a-z][a-z0-9-]*$/
+ * - name: 显示名称（非空）
+ * - description: 功能描述（非空）
+ */
+export const GeneratorMetadataSchema = z.object({
+    /** 唯一标识符，kebab-case 格式 */
+    id: z.string().min(1).regex(/^[a-z][a-z0-9-]*$/),
+    /** 显示名称 */
+    name: z.string().min(1),
+    /** 功能描述 */
+    description: z.string().min(1),
+});
+// ============================================================
+// ArtifactParserMetadata
+// ============================================================
+/**
+ * ArtifactParser 元数据 Schema
+ * 用于运行时验证 Parser 的 id、name、filePatterns
+ * - id: kebab-case 唯一标识符
+ * - name: 显示名称（非空）
+ * - filePatterns: 支持的文件匹配模式（glob 格式，至少一个）
+ */
+export const ArtifactParserMetadataSchema = z.object({
+    /** 唯一标识符，kebab-case 格式 */
+    id: z.string().min(1).regex(/^[a-z][a-z0-9-]*$/),
+    /** 显示名称 */
+    name: z.string().min(1),
+    /** 支持的文件匹配模式（glob 格式），至少包含一个 */
+    filePatterns: z.array(z.string().min(1)).min(1),
+});
+//# sourceMappingURL=interfaces.js.map

package/dist/panoramic/interfaces.js.map

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