repowiki-core 0.1.0

package/src/llm/prompt-manager.ts

@@ -0,0 +1,325 @@
+/**
+ * @module prompt-manager
+ * @description 提示词模板管理器，使用 Handlebars 构建 LLM 提示词。
+ *
+ * 提供以下五类提示词构建函数：
+ * 1. buildModuleAnalysisPrompt  - 模块分析
+ * 2. buildMermaidPrompt         - Mermaid 架构图生成
+ * 3. buildWikiPagePrompt        - Wiki 页面生成
+ * 4. buildWikiPlanPrompt        - Wiki 规划
+ * 5. buildSourceSummaryPrompt   - 源码摘要
+ */
+
+import Handlebars from 'handlebars';
+import type { ChatMessage } from './llm-client.js';
+
+// ============================================================================
+// Handlebars 模板定义
+// ============================================================================
+
+// --- 模块分析 ---
+
+const MODULE_ANALYSIS_SYSTEM = `你是一个资深软件架构师。你的目标是理解给定的模块作用，并用专业的语言描述它。
+
+严格要求:
+- 严禁使用任何 Emoji 表情符号
+- 使用准确、专业的中文描述
+- 基于提供的文件列表和 AST 摘要进行分析，不要编造不存在的内容`;
+
+const MODULE_ANALYSIS_USER_TEMPLATE = Handlebars.compile(`请分析以下模块:
+
+## 模块路径
+{{modulePath}}
+
+## 文件列表
+{{fileList}}
+
+## AST 摘要
+{{astSummaries}}
+
+## 输出格式
+请以如下 JSON 格式输出（不要包含其他任何内容）:
+
+\`\`\`json
+{
+  "summary": "模块的功能概述",
+  "core_components": [
+    {
+      "name": "组件名称",
+      "description": "组件的职责描述"
+    }
+  ]
+}
+\`\`\``, { noEscape: true });
+
+// --- Mermaid 架构图 ---
+
+const MERMAID_SYSTEM = `你是一个架构制图专家。你的任务是根据提供的模块和依赖关系，生成清晰的 Mermaid 流程图。
+
+严格要求:
+- 严禁使用任何 Emoji 表情符号
+- 生成合法的 Mermaid flowchart LR 语法
+- 使用 subgraph 对相关模块进行逻辑分组
+- 节点标签使用简洁的中文或英文名称
+- 箭头标注使用简短的依赖描述
+- 只输出 \`\`\`mermaid 代码块，不要输出任何其他内容`;
+
+const MERMAID_USER_TEMPLATE = Handlebars.compile(`请根据以下信息生成 Mermaid 架构流程图:
+
+## 模块列表
+{{modules}}
+
+## 依赖关系
+{{dependencies}}
+
+请生成一个 Mermaid flowchart LR 图，使用 subgraph 对模块进行合理分组。
+只输出 \`\`\`mermaid 代码块。`, { noEscape: true });
+
+// --- Wiki 页面 ---
+
+const WIKI_PAGE_SYSTEM = `你是一个资深技术文档工程师。你的任务是根据提供的项目信息和源码摘要，生成高质量的技术文档 Wiki 页面。
+
+严格要求:
+- 使用清晰的中文，严禁使用任何 Emoji
+- 不能编造不在上下文中出现的文件或服务
+- 每个章节必须注明 章节来源 (引用对应的源文件)
+- 每个图表必须注明 图表来源 (引用生成图表所依据的源文件)
+- 来源引用格式: [file:line-line](file://project/path#Lstart-Lend)
+
+你必须严格遵循以下 12 节模板结构:
+
+1. H1 标题
+2. <cite> 块 - 列出所有相关源文件
+3. 目录 (ToC) - 使用 Markdown 链接的目录
+4. 引言 - 模块/功能的简介
+5. 项目结构 - 含 Mermaid 目录树图
+6. 核心组件 - 主要组件列表与简述
+7. 架构总览 - 含 Mermaid 架构图
+8. 详细组件分析 - 每个组件含 Mermaid 类图或流程图
+9. 依赖分析 - 含 Mermaid 依赖关系图
+10. 故障排查指南 - 常见问题与排查步骤
+11. 结论 - 总结性评述
+12. 附录 - 补充信息、配置参考等`;
+
+const WIKI_PAGE_USER_TEMPLATE = Handlebars.compile(`请为以下内容生成技术文档 Wiki 页面:
+
+## 页面标题
+{{pageTitle}}
+
+## 项目结构
+{{projectTree}}
+
+## 源码摘要
+{{sourceSummaries}}
+
+{{#if existingPages}}
+## 已有 Wiki 页面
+以下是已生成的其他 Wiki 页面，请在文档中合理交叉引用:
+{{existingPages}}
+{{/if}}
+
+请严格按照 12 节模板结构输出完整的 Markdown 文档。
+每个章节需注明 章节来源，每个图表需注明 图表来源。
+来源格式: [file:line-line](file://project/path#Lstart-Lend)`, { noEscape: true });
+
+// --- Wiki 规划 ---
+
+const WIKI_PLAN_SYSTEM = `你是一个技术文档规划专家。你的任务是根据项目信息规划一组结构化的 Wiki 页面。
+
+严格要求:
+- 严禁使用任何 Emoji 表情符号
+- 页面规划应覆盖项目的所有核心方面
+- 遵循标准文档层级结构
+- 以 JSON 数组格式输出，不要包含其他内容
+
+标准文档层级参考:
+- 项目概述/
+- 架构设计/
+- 前端应用架构/
+- 后端服务架构/
+- 核心功能模块/
+- 数据库设计/
+- API参考文档/
+- 部署运维/
+- 开发指南/`;
+
+const WIKI_PLAN_USER_TEMPLATE = Handlebars.compile(`请根据以下项目信息，规划 Wiki 文档页面:
+
+## 项目结构
+{{projectTree}}
+
+## 技术栈
+{{techStack}}
+
+## 模块列表
+{{modules}}
+
+请以如下 JSON 数组格式输出（不要包含其他任何内容）:
+
+\`\`\`json
+[
+  {
+    "title": "页面标题",
+    "filename": "文件名.md",
+    "summary": "页面内容概述",
+    "requiredModules": ["模块路径1", "模块路径2"]
+  }
+]
+\`\`\`
+
+注意:
+- filename 使用英文命名，使用连字符分隔
+- 页面应按照标准文档层级结构进行组织
+- requiredModules 关联生成该页面所需的源码模块路径`, { noEscape: true });
+
+// --- 源码摘要 ---
+
+const SOURCE_SUMMARY_SYSTEM = `你是一个代码分析专家。你的任务是对给定的源代码文件生成精练的摘要。
+
+摘要应保留以下关键信息:
+- 所有导出的符号 (export)
+- 类和函数的签名 (参数类型、返回类型)
+- 关键的类型定义和接口
+- 重要的注释和文档说明
+- 核心的业务逻辑描述
+
+严格要求:
+- 严禁使用任何 Emoji 表情符号
+- 输出纯文本摘要，不要使用 JSON 格式
+- 摘要控制在约 200 行以内
+- 使用中文描述，代码签名保留原文`;
+
+const SOURCE_SUMMARY_USER_TEMPLATE = Handlebars.compile(`请为以下源代码文件生成精练摘要:
+
+## 文件路径
+{{filePath}}
+
+## 文件内容
+\`\`\`
+{{fileContent}}
+\`\`\`
+
+请输出纯文本摘要（不要使用 JSON），控制在约 200 行以内。
+保留所有导出符号、类/函数签名、关键类型定义和重要注释。`, { noEscape: true });
+
+// ============================================================================
+// 公开 API
+// ============================================================================
+
+/**
+ * 构建模块分析提示词。
+ *
+ * 用于分析指定模块的功能和核心组件，输出结构化 JSON。
+ *
+ * @param modulePath   - 模块路径
+ * @param fileList     - 模块包含的文件列表
+ * @param astSummaries - AST 分析摘要
+ * @returns 准备好的 ChatMessage 数组
+ */
+export function buildModuleAnalysisPrompt(
+    modulePath: string,
+    fileList: string,
+    astSummaries: string,
+): ChatMessage[] {
+    return [
+        { role: 'system', content: MODULE_ANALYSIS_SYSTEM },
+        {
+            role: 'user',
+            content: MODULE_ANALYSIS_USER_TEMPLATE({ modulePath, fileList, astSummaries }),
+        },
+    ];
+}
+
+/**
+ * 构建 Mermaid 架构图提示词。
+ *
+ * 用于根据模块和依赖信息生成 Mermaid flowchart LR 图。
+ *
+ * @param modules      - 模块列表描述
+ * @param dependencies - 依赖关系描述
+ * @returns 准备好的 ChatMessage 数组
+ */
+export function buildMermaidPrompt(
+    modules: string,
+    dependencies: string,
+): ChatMessage[] {
+    return [
+        { role: 'system', content: MERMAID_SYSTEM },
+        {
+            role: 'user',
+            content: MERMAID_USER_TEMPLATE({ modules, dependencies }),
+        },
+    ];
+}
+
+/**
+ * 构建 Wiki 页面生成提示词。
+ *
+ * 用于根据项目结构和源码摘要生成标准 12 节结构的技术文档页面。
+ *
+ * @param pageTitle       - 页面标题
+ * @param projectTree     - 项目目录结构
+ * @param sourceSummaries - 源码摘要集合
+ * @param existingPages   - 已有的 Wiki 页面列表（可选，用于交叉引用）
+ * @returns 准备好的 ChatMessage 数组
+ */
+export function buildWikiPagePrompt(
+    pageTitle: string,
+    projectTree: string,
+    sourceSummaries: string,
+    existingPages?: string,
+): ChatMessage[] {
+    return [
+        { role: 'system', content: WIKI_PAGE_SYSTEM },
+        {
+            role: 'user',
+            content: WIKI_PAGE_USER_TEMPLATE({ pageTitle, projectTree, sourceSummaries, existingPages }),
+        },
+    ];
+}
+
+/**
+ * 构建 Wiki 规划提示词。
+ *
+ * 用于根据项目信息规划 Wiki 文档页面结构，输出结构化 JSON。
+ *
+ * @param projectTree - 项目目录结构
+ * @param techStack   - 技术栈描述
+ * @param modules     - 模块列表描述
+ * @returns 准备好的 ChatMessage 数组
+ */
+export function buildWikiPlanPrompt(
+    projectTree: string,
+    techStack: string,
+    modules: string,
+): ChatMessage[] {
+    return [
+        { role: 'system', content: WIKI_PLAN_SYSTEM },
+        {
+            role: 'user',
+            content: WIKI_PLAN_USER_TEMPLATE({ projectTree, techStack, modules }),
+        },
+    ];
+}
+
+/**
+ * 构建源码摘要提示词。
+ *
+ * 用于对单个源文件生成精练摘要，保留关键代码签名和类型信息。
+ *
+ * @param filePath    - 文件路径
+ * @param fileContent - 文件内容
+ * @returns 准备好的 ChatMessage 数组
+ */
+export function buildSourceSummaryPrompt(
+    filePath: string,
+    fileContent: string,
+): ChatMessage[] {
+    return [
+        { role: 'system', content: SOURCE_SUMMARY_SYSTEM },
+        {
+            role: 'user',
+            content: SOURCE_SUMMARY_USER_TEMPLATE({ filePath, fileContent }),
+        },
+    ];
+}

package/src/models/analysis-result.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+
+import { ProjectProfileSchema } from './project-profile.js';
+import { WikiPageSchema } from './wiki-page.js';
+import {
+    ModuleInfoSchema,
+    ApiRouteSchema,
+    DatabaseModelSchema,
+} from './analysis-types.js';
+
+/**
+ * 依赖关系边 Schema
+ */
+export const DependencyEdgeSchema = z.object({
+    source: z.string().describe('源文件相对路径'),
+    target: z.string().describe('依赖目标相对路径或包名'),
+    isExternal: z.boolean().describe('是否为外部依赖'),
+});
+
+/**
+ * 依赖关系图 Schema
+ */
+export const DependencyGraphSchema = z.object({
+    edges: z.array(DependencyEdgeSchema).default([]).describe('依赖边列表'),
+    internalModules: z.array(z.string()).default([]).describe('内部模块路径列表'),
+    externalPackages: z.array(z.string()).default([]).describe('外部依赖包名列表'),
+});
+
+/**
+ * 分析结果 Schema
+ * 整合项目概要、目录树、模块、依赖、API 路由、数据模型和 Wiki 页面。
+ */
+export const AnalysisResultSchema = z.object({
+    project: ProjectProfileSchema,
+    tree: z.string().describe('纯文本树结构'),
+    modules: z.array(ModuleInfoSchema),
+    dependencies: DependencyGraphSchema,
+    apiRoutes: z.array(ApiRouteSchema),
+    databaseModels: z.array(DatabaseModelSchema),
+    wikiPages: z.array(WikiPageSchema).default([]),
+});
+
+/** 分析结果类型 */
+export type AnalysisResult = z.infer<typeof AnalysisResultSchema>;

package/src/models/analysis-types.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+
+// ============================================================================
+// ModuleInfo — 模块聚类分析结果
+// ============================================================================
+
+/**
+ * 核心组件 Schema
+ * 描述某模块中的关键类、函数或子系统。
+ */
+export const CoreComponentSchema = z.object({
+    /** 组件名称（类名、函数名或子系统名） */
+    name: z.string().describe('核心组件名称'),
+    /** 组件的作用描述 */
+    description: z.string().describe('用途和调用逻辑'),
+});
+
+/** 核心组件类型 */
+export type CoreComponent = z.infer<typeof CoreComponentSchema>;
+
+/**
+ * 模块信息 Schema
+ * 描述由 ModuleAnalyzer 聚类生成的逻辑模块。
+ */
+export const ModuleInfoSchema = z.object({
+    /** 模块名称（如 api, web, components） */
+    moduleName: z.string().describe('模块名称'),
+    /** 模块所在的目录相对路径 */
+    directory: z.string().describe('目录相对路径'),
+    /** 模块内包含的文件相对路径列表 */
+    files: z.array(z.string()).default([]).describe('文件相对路径列表'),
+    /** 模块职责描述 */
+    summary: z.string().default('').describe('模块职责描述'),
+    /** 模块分类标签 */
+    category: z.string().default('').describe('分类标签'),
+    /** 核心组件列表 */
+    coreComponents: z.array(CoreComponentSchema).default([]).describe('核心组件'),
+});
+
+/** 模块信息类型 */
+export type ModuleInfo = z.infer<typeof ModuleInfoSchema>;
+
+// ============================================================================
+// ApiRoute — API 路由分析结果
+// ============================================================================
+
+/**
+ * API 路由 Schema
+ * 描述从源码中提取的单个 HTTP 路由定义。
+ */
+export const ApiRouteSchema = z.object({
+    /** HTTP 方法（GET, POST, PUT, DELETE, PATCH） */
+    method: z.string().describe('HTTP 方法'),
+    /** 路由路径 */
+    path: z.string().describe('路由路径'),
+    /** 处理函数名称 */
+    handler: z.string().default('').describe('处理函数名称'),
+    /** 所在文件的相对路径 */
+    filePath: z.string().describe('文件相对路径'),
+    /** 路由定义所在的行号 */
+    lineNumber: z.number().default(0).describe('行号'),
+    /** 检测到的框架类型 */
+    framework: z.string().default('').describe('框架类型'),
+});
+
+/** API 路由类型 */
+export type ApiRoute = z.infer<typeof ApiRouteSchema>;
+
+// ============================================================================
+// DatabaseModel — 数据库模型分析结果
+// ============================================================================
+
+/**
+ * 数据库字段 Schema
+ */
+export const DatabaseFieldSchema = z.object({
+    /** 字段名称 */
+    name: z.string().describe('字段名称'),
+    /** 字段类型 */
+    type: z.string().describe('字段类型'),
+    /** 是否可空 */
+    nullable: z.boolean().default(false).describe('是否可空'),
+});
+
+/** 数据库字段类型 */
+export type DatabaseField = z.infer<typeof DatabaseFieldSchema>;
+
+/**
+ * 数据库关系 Schema
+ */
+export const DatabaseRelationSchema = z.object({
+    /** 关系字段名 */
+    fieldName: z.string().describe('关系字段名'),
+    /** 关联的模型名 */
+    relatedModel: z.string().describe('关联模型'),
+    /** 关系类型（OneToMany, ManyToOne 等） */
+    relationType: z.string().default('').describe('关系类型'),
+});
+
+/** 数据库关系类型 */
+export type DatabaseRelation = z.infer<typeof DatabaseRelationSchema>;
+
+/**
+ * 数据库模型 Schema
+ * 描述从 ORM 定义中提取的数据模型。
+ */
+export const DatabaseModelSchema = z.object({
+    /** 模型名称 */
+    name: z.string().describe('模型名称'),
+    /** 所在文件相对路径 */
+    filePath: z.string().describe('文件相对路径'),
+    /** 检测到的 ORM 类型 */
+    orm: z.string().default('').describe('ORM 类型'),
+    /** 字段列表 */
+    fields: z.array(DatabaseFieldSchema).default([]).describe('字段列表'),
+    /** 关系列表 */
+    relations: z.array(DatabaseRelationSchema).default([]).describe('关系列表'),
+});
+
+/** 数据库模型类型 */
+export type DatabaseModel = z.infer<typeof DatabaseModelSchema>;

package/src/models/file-reference.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+
+/**
+ * 文件节点 Schema
+ * 表示扫描到的单个文件或目录。
+ */
+export const FileNodeSchema = z.object({
+    /** 文件的绝对路径 */
+    path: z.string().describe('文件的绝对路径'),
+    /** 相对于项目根目录的路径 */
+    relativePath: z.string().describe('相对于项目根目录的路径'),
+    /** 节点类型 */
+    nodeType: z.enum(['file', 'directory']).describe('节点类型'),
+    /** 文件大小 (字节) */
+    sizeBytes: z.number().describe('文件大小'),
+    /** 检测到的编程语言 */
+    language: z.string().optional().describe('语言类型'),
+    /** 非空代码行数 */
+    lineCount: z.number().optional().describe('非空代码行数'),
+});
+
+/** 文件节点类型 */
+export type FileNode = z.infer<typeof FileNodeSchema>;
+
+/**
+ * 源码引用 Schema
+ * 指向特定代码片段的行范围，用于 Wiki 页面追溯。
+ */
+export const SourceReferenceSchema = z.object({
+    /** 相对文件路径 */
+    filePath: z.string().describe('相对文件路径'),
+    /** 开始行号 */
+    startLine: z.number().describe('开始行'),
+    /** 结束行号 */
+    endLine: z.number().describe('结束行'),
+    /** 引用说明 */
+    reason: z.string().describe('引用说明'),
+});
+
+/** 源码引用类型 */
+export type SourceReference = z.infer<typeof SourceReferenceSchema>;

package/src/models/index.ts

@@ -0,0 +1,44 @@
+/**
+ * models 模块入口
+ * 统一导出所有数据模型 Schema 及类型定义。
+ */
+
+export {
+    FileNodeSchema,
+    type FileNode,
+    SourceReferenceSchema,
+    type SourceReference,
+} from './file-reference.js';
+
+export {
+    ProjectProfileSchema,
+    type ProjectProfile,
+} from './project-profile.js';
+
+export {
+    CoreComponentSchema,
+    type CoreComponent,
+    ModuleInfoSchema,
+    type ModuleInfo,
+    ApiRouteSchema,
+    type ApiRoute,
+    DatabaseFieldSchema,
+    type DatabaseField,
+    DatabaseRelationSchema,
+    type DatabaseRelation,
+    DatabaseModelSchema,
+    type DatabaseModel,
+} from './analysis-types.js';
+
+export {
+    WikiPageSchema,
+    type WikiPage,
+} from './wiki-page.js';
+
+export {
+    DependencyEdgeSchema,
+    DependencyGraphSchema,
+    AnalysisResultSchema,
+    type AnalysisResult,
+} from './analysis-result.js';
+

package/src/models/project-profile.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+
+/**
+ * 项目概要 Schema
+ * 描述被分析项目的基本元信息，包括技术栈、入口点和配置文件等。
+ */
+export const ProjectProfileSchema = z.object({
+    /** 项目名称 */
+    name: z.string().describe('项目名称'),
+    /** 项目根目录的绝对路径 */
+    rootPath: z.string().describe('绝对路径'),
+    /** 使用的主力编程语言 */
+    languages: z.array(z.string()).default([]).describe('使用的主力语言'),
+    /** 推断出的框架信息 */
+    frameworks: z.array(z.string()).default([]).describe('框架推断结果'),
+    /** 检测到的包管理器 */
+    packageManagers: z.array(z.string()).default([]).describe('包管理器'),
+    /** 使用的数据库 */
+    databases: z.array(z.string()).default([]).describe('数据库'),
+    /** 接入的外部服务 */
+    services: z.array(z.string()).default([]).describe('外部服务'),
+    /** 入口文件列表 */
+    entrypoints: z.array(z.string()).default([]).describe('入口点'),
+    /** 配置文件列表 */
+    configFiles: z.array(z.string()).default([]).describe('配置文件'),
+});
+
+/** 项目概要类型 */
+export type ProjectProfile = z.infer<typeof ProjectProfileSchema>;

package/src/models/wiki-page.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+
+import { SourceReferenceSchema } from './file-reference.js';
+
+/**
+ * Wiki 页面 Schema
+ * 表示一篇生成的 Wiki 文档。
+ */
+export const WikiPageSchema = z.object({
+    /** 页面标题 */
+    title: z.string().describe('标题'),
+    /** docs/wiki/ 下的相对文件名 */
+    filename: z.string().describe('docs/wiki/ 下的相对路径'),
+    /** 页面摘要 */
+    summary: z.string().describe('简述'),
+    /** 最终渲染的 Markdown 正文 */
+    content: z.string().describe('最终 Markdown 文本'),
+    /** 引用的源码片段 */
+    sourceRefs: z.array(SourceReferenceSchema).default([]),
+});
+
+/** Wiki 页面类型 */
+export type WikiPage = z.infer<typeof WikiPageSchema>;