repowiki-core 0.1.0

package/src/generator/wiki-generator.ts

@@ -0,0 +1,281 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { AnalysisResult, WikiPage, ProjectProfile, ModuleInfo } from '../models/index.js';
+import type { LLMClient } from '../llm/index.js';
+import { buildWikiPlanPrompt, buildWikiPagePrompt, buildSourceSummaryPrompt } from '../llm/index.js';
+import { assembleWikiPage, formatTroubleshootingTable } from './markdown-generator.js';
+import {
+    generateArchitectureDiagram,
+    generateERDiagram,
+    generateDependencyDiagram,
+    generateApiDiagram,
+} from './mermaid-generator.js';
+
+export interface WikiGeneratorConfig {
+    outputDir: string;
+    concurrency?: number;
+}
+
+export interface PlannedPage {
+    title: string;
+    filename: string;
+    summary: string;
+    requiredModules: string[];
+}
+
+/**
+ * 核心 Wiki 生成器
+ */
+export class WikiGenerator {
+    private config: Required<WikiGeneratorConfig>;
+    private llmClient: LLMClient | null;
+
+    constructor(llmClient: LLMClient | null, config: WikiGeneratorConfig) {
+        this.llmClient = llmClient;
+        this.config = {
+            outputDir: config.outputDir,
+            concurrency: config.concurrency ?? 3,
+        };
+    }
+
+    /**
+     * 规划 Wiki 页面列表
+     */
+    public async planPages(analysisResult: AnalysisResult): Promise<PlannedPage[]> {
+        if (!this.llmClient) {
+            return this.getDefaultPagePlan(analysisResult);
+        }
+
+        try {
+            const modulesStr = JSON.stringify(
+                analysisResult.modules.map((m) => ({
+                    moduleName: m.moduleName,
+                    directory: m.directory,
+                    summary: m.summary,
+                    filesCount: m.files.length,
+                })),
+                null,
+                2
+            );
+
+            const techStackStr = JSON.stringify(analysisResult.project, null, 2);
+            const prompt = buildWikiPlanPrompt(analysisResult.tree, techStackStr, modulesStr);
+
+            const planned = await this.llmClient.chatJSON<PlannedPage[]>(prompt);
+            if (Array.isArray(planned) && planned.length > 0) {
+                return planned;
+            }
+        } catch {
+            // 回退到默认规划
+        }
+
+        return this.getDefaultPagePlan(analysisResult);
+    }
+
+    /**
+     * 默认的 Wiki 页面规划（无 LLM 或 LLM 规划失败时使用）
+     */
+    private getDefaultPagePlan(analysisResult: AnalysisResult): PlannedPage[] {
+        const plan: PlannedPage[] = [
+            {
+                title: '项目概述',
+                filename: '项目概述/项目概述.md',
+                summary: '项目概要介绍与基本结构',
+                requiredModules: ['.'],
+            },
+        ];
+
+        // 为每个主要逻辑模块分别规划一个文档页面
+        for (const mod of analysisResult.modules) {
+            if (mod.directory === '.') continue;
+            plan.push({
+                title: `${mod.moduleName} 模块分析`,
+                filename: `核心功能模块/${mod.moduleName}.md`,
+                summary: `${mod.moduleName} 模块的设计与实现细节`,
+                requiredModules: [mod.directory],
+            });
+        }
+
+        if (analysisResult.databaseModels.length > 0) {
+            plan.push({
+                title: '数据库设计',
+                filename: '数据库设计/数据库设计.md',
+                summary: '项目数据库结构及实体模型定义',
+                requiredModules: [],
+            });
+        }
+
+        if (analysisResult.apiRoutes.length > 0) {
+            plan.push({
+                title: 'API 参考文档',
+                filename: 'API参考文档/API参考文档.md',
+                summary: '项目公开的 HTTP 接口路由规范',
+                requiredModules: [],
+            });
+        }
+
+        return plan;
+    }
+
+    /**
+     * 对文件列表进行摘要压缩（如文件太大，先使用 LLM 摘要以节省 Context 空间）
+     */
+    private async prepareSourceSummaries(
+        rootPath: string,
+        plannedPage: PlannedPage,
+        analysisResult: AnalysisResult
+    ): Promise<string> {
+        const summaries: string[] = [];
+
+        // 收集所有关联模块内的文件
+        const relatedFiles: string[] = [];
+        for (const modDir of plannedPage.requiredModules) {
+            const mod = analysisResult.modules.find((m) => m.directory === modDir);
+            if (mod) {
+                relatedFiles.push(...mod.files);
+            }
+        }
+
+        // 如果没有关联模块，则提取根目录附近的重要源文件
+        if (relatedFiles.length === 0) {
+            relatedFiles.push(
+                ...analysisResult.modules
+                    .filter((m) => m.directory !== '.')
+                    .slice(0, 3)
+                    .flatMap((m) => m.files.slice(0, 2))
+            );
+        }
+
+        // 限制最多分析前 8 个文件，防止 Context 溢出
+        const targetFiles = relatedFiles.slice(0, 8);
+
+        for (const relPath of targetFiles) {
+            try {
+                const absPath = path.resolve(rootPath, relPath);
+                const content = await fs.readFile(absPath, 'utf-8');
+
+                // 超过 4KB 的文件进行 LLM 摘要，小文件直接使用首部几行
+                if (content.length > 4000 && this.llmClient) {
+                    const prompt = buildSourceSummaryPrompt(relPath, content.slice(0, 20000));
+                    const summaryResult = await this.llmClient.chat(prompt);
+                    summaries.push(`### 文件: ${relPath} (代码摘要)\n${summaryResult.content}`);
+                } else {
+                    const lines = content.split('\n');
+                    const truncated = lines.slice(0, 100).join('\n');
+                    summaries.push(`### 文件: ${relPath}\n\`\`\`\n${truncated}\n\`\`\``);
+                }
+            } catch {
+                // 忽略单个文件读取错误
+            }
+        }
+
+        return summaries.join('\n\n');
+    }
+
+    /**
+     * 生成单个页面内容
+     */
+    public async generatePage(
+        rootPath: string,
+        page: PlannedPage,
+        analysisResult: AnalysisResult,
+        existingPagesSummary?: string
+    ): Promise<WikiPage> {
+        if (this.llmClient) {
+            try {
+                const sourceSummaries = await this.prepareSourceSummaries(rootPath, page, analysisResult);
+                const prompt = buildWikiPagePrompt(
+                    page.title,
+                    analysisResult.tree,
+                    sourceSummaries,
+                    existingPagesSummary
+                );
+
+                const response = await this.llmClient.chat(prompt);
+                const content = response.content;
+
+                return {
+                    title: page.title,
+                    filename: page.filename,
+                    summary: page.summary,
+                    content,
+                    sourceRefs: [], // 稍后在后置处理中补充或由 LLM 直接写在 Markdown 中
+                };
+            } catch {
+                // LLM 生成失败时回退到模板组装
+            }
+        }
+
+        // 本地模板组装（免 LLM 回退逻辑）
+        return this.assembleFallbackPage(page, analysisResult);
+    }
+
+    /**
+     * 无大模型回退页面生成逻辑
+     */
+    private assembleFallbackPage(page: PlannedPage, analysisResult: AnalysisResult): WikiPage {
+        // 构建默认的图表
+        let archDiagram: string | undefined;
+        let erDiagram: string | undefined;
+        let depDiagram: string | undefined;
+        let apiDiagram: string | undefined;
+
+        if (page.title.includes('架构') || page.title.includes('概述')) {
+            archDiagram = generateArchitectureDiagram(analysisResult.modules, analysisResult.dependencies.edges || []);
+        }
+        if (page.title.includes('数据') || page.title.includes('DB') || page.filename.includes('database')) {
+            erDiagram = generateERDiagram(analysisResult.databaseModels);
+        }
+        if (page.title.includes('依赖') || page.filename.includes('dependency')) {
+            depDiagram = generateDependencyDiagram(analysisResult.modules, analysisResult.dependencies.edges || []);
+        }
+        if (page.title.includes('API') || page.filename.includes('api')) {
+            apiDiagram = generateApiDiagram(analysisResult.apiRoutes);
+        }
+
+        const projectRoot = analysisResult.project.rootPath;
+
+        const content = assembleWikiPage({
+            title: page.title,
+            citeRefs: [],
+            projectRoot,
+            introduction: `该文档是针对 "${page.title}" 模块的自动生成概要文档。\n${page.summary}`,
+            projectStructure: '项目整体目录结构树状视图如下。',
+            projectStructureDiagram: 'flowchart TD\n    Root["项目根目录"]', // 简易树
+            coreComponents: '以下是该页面对应模块的核心类与组件列表。',
+            architectureOverview: archDiagram ? '项目整体模块架构设计及数据交互图如下。' : undefined,
+            architectureDiagram: archDiagram,
+            detailedAnalysis: erDiagram ? '数据表关系 (ER) 设计图如下。' : undefined,
+            troubleshooting: formatTroubleshootingTable([
+                {
+                    problem: '模块无法加载/包缺失',
+                    cause: '依赖未正确安装',
+                    resolution: '在根目录下运行 `pnpm install` 或对应的依赖安装指令。',
+                },
+            ]),
+            conclusion: '文档自动构建完毕，详细系统设计请参考内部核心组件代码。',
+            appendix: `技术栈详情: ${analysisResult.project.languages.join(', ')}`,
+        });
+
+        return {
+            title: page.title,
+            filename: page.filename,
+            summary: page.summary,
+            content,
+            sourceRefs: [],
+        };
+    }
+
+    /**
+     * 保存 Wiki 页面文件到 docs/wiki 目录
+     */
+    public async savePage(page: WikiPage): Promise<string> {
+        const destPath = path.join(this.config.outputDir, page.filename);
+        const destDir = path.dirname(destPath);
+
+        await fs.mkdir(destDir, { recursive: true });
+        await fs.writeFile(destPath, page.content, 'utf-8');
+
+        return destPath;
+    }
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * RepoWiki Core API
+ * 包含代码库扫描、技术栈检测、静态代码分析、LLM 集成及 Markdown Wiki 生成的完整流程。
+ */
+
+export * from './models/index.js';
+export * from './scanner/index.js';
+export * from './detector/index.js';
+export * from './analyzer/index.js';
+export * from './llm/index.js';
+export * from './generator/index.js';
+export * from './pipeline.js';

package/src/llm/auth-manager.ts

@@ -0,0 +1,207 @@
+/**
+ * @module auth-manager
+ * @description 管理 LLM API 凭证，支持多来源优先级链解析配置。
+ *
+ * 优先级链（按优先级从高到低）：
+ * 1. 环境变量: REPOWIKI_API_KEY, REPOWIKI_BASE_URL, REPOWIKI_MODEL
+ * 2. 环境变量 (OpenAI 兼容): OPENAI_API_KEY, OPENAI_BASE_URL
+ * 3. 全局配置文件: ~/.repowiki/config.json
+ * 4. 工作区 .env 文件（使用 dotenv 解析）
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import dotenv from 'dotenv';
+
+// ============================================================================
+// 类型定义
+// ============================================================================
+
+/** LLM 服务配置 */
+export interface LLMConfig {
+    /** API 端点地址 */
+    apiEndpoint: string;
+    /** 模型名称 */
+    modelName: string;
+    /** API 密钥 */
+    apiKey: string;
+}
+
+// ============================================================================
+// 常量
+// ============================================================================
+
+/** 默认 API 端点 */
+const DEFAULT_API_ENDPOINT = 'https://api.openai.com/v1';
+
+/** 默认模型名称 */
+const DEFAULT_MODEL_NAME = 'gpt-4o';
+
+/** 全局配置目录名 */
+const GLOBAL_CONFIG_DIR = '.repowiki';
+
+/** 全局配置文件名 */
+const GLOBAL_CONFIG_FILE = 'config.json';
+
+// ============================================================================
+// 内部工具函数
+// ============================================================================
+
+/**
+ * 获取全局配置文件的绝对路径
+ */
+function getGlobalConfigPath(): string {
+    return path.join(os.homedir(), GLOBAL_CONFIG_DIR, GLOBAL_CONFIG_FILE);
+}
+
+/**
+ * 尝试读取并解析 JSON 配置文件，若文件不存在或解析失败则返回空对象
+ */
+async function readJsonConfig(filePath: string): Promise<Record<string, unknown>> {
+    try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const parsed: unknown = JSON.parse(content);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed as Record<string, unknown>;
+        }
+        return {};
+    } catch {
+        // 文件不存在或内容无效，均视为空配置
+        return {};
+    }
+}
+
+/**
+ * 尝试解析工作区 .env 文件，返回解析后的键值对
+ */
+async function readWorkspaceEnv(workspacePath: string): Promise<Record<string, string>> {
+    const envFilePath = path.join(workspacePath, '.env');
+    try {
+        const content = await fs.readFile(envFilePath, 'utf-8');
+        const parsed = dotenv.parse(content);
+        return parsed;
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * 返回第一个非空字符串值，若全部为空则返回 undefined
+ */
+function firstNonEmpty(...values: Array<string | undefined | null>): string | undefined {
+    for (const v of values) {
+        if (v && v.trim().length > 0) {
+            return v.trim();
+        }
+    }
+    return undefined;
+}
+
+// ============================================================================
+// 公开 API
+// ============================================================================
+
+/**
+ * 按优先级链加载 LLM 配置。
+ *
+ * 解析顺序：
+ * 1. 进程环境变量（REPOWIKI_* 优先，其次 OPENAI_*）
+ * 2. 全局配置文件 ~/.repowiki/config.json
+ * 3. 工作区 .env 文件
+ *
+ * 对于每个字段，取优先级最高的非空值；若全部为空则使用默认值或空字符串。
+ *
+ * @param workspacePath - 可选的工作区路径，用于读取 .env 文件
+ * @returns 解析后的 LLM 配置
+ */
+export async function loadLLMConfig(workspacePath?: string): Promise<LLMConfig> {
+    // --- 来源 1 & 2: 环境变量（已在 process.env 中） ---
+    const envApiKey = firstNonEmpty(process.env['REPOWIKI_API_KEY'], process.env['OPENAI_API_KEY']);
+    const envEndpoint = firstNonEmpty(process.env['REPOWIKI_BASE_URL'], process.env['OPENAI_BASE_URL']);
+    const envModel = firstNonEmpty(process.env['REPOWIKI_MODEL']);
+
+    // --- 来源 3: 全局配置文件 ---
+    const globalConfig = await readJsonConfig(getGlobalConfigPath());
+    const globalApiKey = typeof globalConfig['apiKey'] === 'string' ? globalConfig['apiKey'] : undefined;
+    const globalEndpoint = typeof globalConfig['apiEndpoint'] === 'string' ? globalConfig['apiEndpoint'] : undefined;
+    const globalModel = typeof globalConfig['modelName'] === 'string' ? globalConfig['modelName'] : undefined;
+
+    // --- 来源 4: 工作区 .env ---
+    let wsApiKey: string | undefined;
+    let wsEndpoint: string | undefined;
+    let wsModel: string | undefined;
+    if (workspacePath) {
+        const wsEnv = await readWorkspaceEnv(workspacePath);
+        wsApiKey = firstNonEmpty(wsEnv['REPOWIKI_API_KEY'], wsEnv['OPENAI_API_KEY']);
+        wsEndpoint = firstNonEmpty(wsEnv['REPOWIKI_BASE_URL'], wsEnv['OPENAI_BASE_URL']);
+        wsModel = firstNonEmpty(wsEnv['REPOWIKI_MODEL']);
+    }
+
+    // --- 合并：对每个字段，按优先级取第一个非空值 ---
+    const apiKey = firstNonEmpty(envApiKey, globalApiKey, wsApiKey) ?? '';
+    const apiEndpoint = firstNonEmpty(envEndpoint, globalEndpoint, wsEndpoint) ?? DEFAULT_API_ENDPOINT;
+    const modelName = firstNonEmpty(envModel, globalModel, wsModel) ?? DEFAULT_MODEL_NAME;
+
+    return { apiEndpoint, modelName, apiKey };
+}
+
+/**
+ * 将配置保存到全局配置文件 ~/.repowiki/config.json。
+ *
+ * 如果文件已存在，则与现有配置合并（新值覆盖旧值）。
+ * 如果目录不存在，则自动创建。
+ *
+ * @param config - 要保存的部分配置
+ */
+export async function saveGlobalConfig(config: Partial<LLMConfig>): Promise<void> {
+    const configPath = getGlobalConfigPath();
+    const configDir = path.dirname(configPath);
+
+    // 确保配置目录存在
+    await fs.mkdir(configDir, { recursive: true });
+
+    // 读取现有配置并合并
+    const existing = await readJsonConfig(configPath);
+
+    // 仅合并非 undefined 的字段
+    const merged: Record<string, unknown> = { ...existing };
+    if (config.apiEndpoint !== undefined) merged['apiEndpoint'] = config.apiEndpoint;
+    if (config.modelName !== undefined) merged['modelName'] = config.modelName;
+    if (config.apiKey !== undefined) merged['apiKey'] = config.apiKey;
+
+    await fs.writeFile(configPath, JSON.stringify(merged, null, 2), 'utf-8');
+}
+
+/**
+ * 验证 LLM 配置的完整性。
+ *
+ * @param config - 待验证的配置
+ * @returns 错误消息数组。若为空数组，则配置有效。
+ */
+export function validateConfig(config: LLMConfig): string[] {
+    const errors: string[] = [];
+
+    if (!config.apiKey || config.apiKey.trim().length === 0) {
+        errors.push('缺少 API 密钥 (apiKey)。请通过环境变量 REPOWIKI_API_KEY 或全局配置文件设置。');
+    }
+
+    if (!config.apiEndpoint || config.apiEndpoint.trim().length === 0) {
+        errors.push('缺少 API 端点 (apiEndpoint)。');
+    }
+
+    if (!config.modelName || config.modelName.trim().length === 0) {
+        errors.push('缺少模型名称 (modelName)。');
+    }
+
+    // 验证 apiEndpoint 是合法 URL
+    if (config.apiEndpoint && config.apiEndpoint.trim().length > 0) {
+        try {
+            new URL(config.apiEndpoint);
+        } catch {
+            errors.push(`API 端点格式无效: "${config.apiEndpoint}"。请提供合法的 URL。`);
+        }
+    }
+
+    return errors;
+}

package/src/llm/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @module llm
+ * @description LLM 层入口 - 统一导出认证管理、客户端和提示词管理功能。
+ */
+
+// 认证管理
+export type { LLMConfig } from './auth-manager.js';
+export { loadLLMConfig, saveGlobalConfig, validateConfig } from './auth-manager.js';
+
+// LLM 客户端
+export type { ChatMessage, LLMClientOptions, LLMResponse, ChatOptions } from './llm-client.js';
+export { LLMClient, LLMError, LLMAuthError, LLMRateLimitError, LLMJsonParseError } from './llm-client.js';
+
+// 提示词管理
+export {
+    buildModuleAnalysisPrompt,
+    buildMermaidPrompt,
+    buildWikiPagePrompt,
+    buildWikiPlanPrompt,
+    buildSourceSummaryPrompt,
+} from './prompt-manager.js';