repowiki

RepoWiki — 仓库报告生成器

基于当前仓库的代码结构、配置文件和依赖关系，生成一份类似 DeepWiki 的深度分析报告。

报告结构规范

生成的报告必须严格遵循以下分层结构，并以单个 Markdown 文件输出。

第 1 层：项目概览

# {Project Name}

> {One-line project positioning description}

## Purpose & Scope

{2-3 paragraphs describing what problem the project solves, core value, target users}

## Tech Stack

| Category | Technology | Purpose |
|----------|-----------|---------|
| Language | ... | ... |
| Framework | ... | ... |
| Build Tool | ... | ... |
| Testing | ... | ... |
| Database | ... | ... |

## Repository Structure

{Mermaid graph showing top-level directory structure and module relationships}

## Core Systems Overview

{Mermaid graph showing interactions between major subsystems}

第 1.5 层：概念与设计理念

在项目概览与模块分析之间，添加一个章节，解释项目背后的核心理念和技术依据——不是说明项目做什么，而是阐述为何采用这样的构建方式。

## Design Philosophy & Key Decisions

### Core Concept
{1-2 paragraphs explaining the fundamental insight or approach that drives the project's design.
 What problem does the conventional approach have? What alternative mental model does this project adopt?}

### Key Technical Decisions

| Decision | Chose | Over | Rationale |
|----------|-------|------|-----------|
| {e.g., State management} | {Zustand} | {Redux, Context API} | {Why — specific trade-off reasoning} |
| ... | ... | ... | ... |

### Architecture Principles
{2-4 bullet points capturing the non-obvious design principles extracted from the code.
 Each should explain a constraint or convention the codebase follows, and WHY.}

这一层对于生成达到 DeepWiki 水准的报告至关重要：读者需要先了解**“为什么”，再深入了解“是什么”**。

第 2 层：模块与包分析

## Module Inventory

| Module | Path | Responsibility | Key Dependencies |
|--------|------|---------------|-----------------|
| ... | ... | ... | ... |

## Module Dependency Architecture

{Mermaid graph: inter-module dependency diagram}

## {Module Name} Detailed Analysis

<details>
<summary>Related Source Files</summary>

- `path/to/file1.ts`
- `path/to/file2.ts`
</details>

### Responsibilities & Boundaries
{What this module is and isn't responsible for}

### Internal Architecture
{Mermaid graph: class/function relationships within the module}

### Key Interfaces
{Code block: main exported APIs, type definitions, interfaces}

### Data Flow
{Mermaid sequence/flowchart: how data flows within the module}

第 3 层：核心系统深度分析

为每个核心系统单独生成一个章节：

## {System Name}

<details>
<summary>Related Source Files</summary>

- `path/to/relevant/file.ts`
</details>

### Problem & Approach
{Start each core system section with a narrative arc:
 1. What problem does this system solve?
 2. What is the conventional/naive approach, and why doesn't it work here?
 3. What insight or approach does this project use instead?
 This "problem → conventional failure → project's solution" arc is critical for DeepWiki-quality analysis.}

### System Architecture
{Mermaid graph: overall architecture diagram of the system}

### Core Workflows
{Mermaid sequence diagram: main business processes}

### Key Components

| Component | File | Responsibility |
|-----------|------|---------------|
| ... | ... | ... |

### Design Decisions & Trade-offs

| Decision | Chose | Over | Rationale |
|----------|-------|------|-----------|
| ... | ... | ... | ... |

{For each major design decision within this system, explain what was chosen over what alternatives, and why. This comparison table is required for every core system section.}

### Configuration & Extension Points
{Code block: key configuration file snippets}

第 4 层：基础设施与工具链

## Build System

### Build Pipeline
{Mermaid flowchart: complete process from source to artifacts}

### Build Configuration
{Table: key build configuration items}

## Testing Infrastructure

### Testing Strategy
| Test Type | Tool | Coverage |
|-----------|------|----------|
| Unit Tests | ... | ... |
| Integration Tests | ... | ... |
| E2E Tests | ... | ... |

### Test Configuration
{Code block: key test configuration file snippets}

## CI/CD Pipeline
{Mermaid flowchart: CI/CD process}

## Dependency Management
### Key Dependencies
| Dependency | Version | Purpose |
|-----------|---------|---------|
| ... | ... | ... |

### Dependency Strategy
{Version locking, update strategy, security auditing}

Mermaid 图表规范

重要：避免以下 Mermaid 语法问题：

• 节点标签或边标签中不得使用圆括号 ()，否则会导致解析器报错。请改用全角括号 （） 或换一种表述。
• 标签字符串中不得直接使用特殊字符 {}[]()。如果标签包含这些字符，请用 ["..."] 包裹。
• 请始终确认图表类型声明（graph、flowchart、sequenceDiagram、stateDiagram-v2）与正文所用语法相符。

每份报告必须包含以下类型的图表：

1. 仓库结构图（必需）

graph TD
    Root[Project Root]
    Root --> Src[src/]
    Root --> Config[Configuration]
    Root --> Tests[tests/]
    Src --> Core[core/]
    Src --> Utils[utils/]
    Src --> Types[types/]

2. 模块依赖关系图（必需）

graph LR
    A[Module A] --> B[Module B]
    A --> C[Module C]
    B --> D[Module D]
    C --> D

3. 核心工作流图（必需）

sequenceDiagram
    participant User
    participant API
    participant Service
    participant DB
    User->>API: Request
    API->>Service: Process
    Service->>DB: Query
    DB-->>Service: Result
    Service-->>API: Response
    API-->>User: Return

4. 数据流图（按需）

flowchart LR
    Input[Input] --> Validate[Validate]
    Validate --> Transform[Transform]
    Transform --> Process[Process]
    Process --> Output[Output]

5. 状态／生命周期图（按需）

stateDiagram-v2
    [*] --> Created
    Created --> Active
    Active --> Paused
    Paused --> Active
    Active --> Completed
    Completed --> [*]

分析执行流程

步骤 1：收集仓库元数据

使用以下工具收集信息（并行执行）：

1. 目录结构 — 使用 Glob 扫描 **/*，获取完整文件树
2. 包管理 — 读取 package.json、go.mod、Cargo.toml、pyproject.toml、pom.xml 等文件
3. 配置文件 — 读取 tsconfig.json、.eslintrc.*、vite.config.*、webpack.config.* 等文件
4. CI/CD — 读取 .github/workflows/*、.gitlab-ci.yml、Dockerfile 等文件
5. Git 历史记录 — 统计最近 100 次提交中的文件变更频率

步骤 2：识别核心系统

根据以下信号确定核心系统：

信号	权重	方法
文件变更频率	高	git log 统计
目录大小	中	文件计数
入口文件引用	高	grep import/require
README 提及	中	阅读文档
导出数量	中	grep export

步骤 3：深度分析每个系统

对每个核心系统，执行以下操作：

1. 阅读该目录下的所有文件
2. 识别主要的类、函数和类型定义——对关键定义提供文件:行号引用（例如 src/engine.ts:42），方便读者直接跳转到源代码
3. 梳理导入／导出依赖链
4. 识别设计模式（Repository、Factory、Observer 等）
5. 提取关键配置和常量
6. 对于关键算法或工作流，提供逐步代码逻辑分析——追踪实际实现过程，而不只是描述接口层面的功能

步骤 4：生成 Mermaid 图表

根据分析结果生成：

• 至少 1 张架构概览图
• 至少 1 张模块依赖关系图
• 至少 1 张核心工作流时序图
• 按需添加状态图和数据流图

步骤 5：汇总报告

按照上述结构规范汇总完整报告，并输出到 REPOWIKI.md。

源文件引用规范

每个章节都必须包含可折叠的源文件引用：

<details>
<summary>Related Source Files</summary>

- `src/core/engine.ts` - Core engine implementation
- `src/core/types.ts` - Type definitions
- `src/config/default.ts` - Default configuration
</details>

引用规则：

• 仅引用与当前章节直接相关的文件
• 每条引用都包含简短说明
• 按重要性排序，最关键的文件排在前面
• 每个章节引用 3-10 个文件

表格使用规范

在以下场景中必须使用表格：

1. 技术栈 - 语言、框架和工具清单
2. 模块清单 - 所有模块的路径、职责和依赖项
3. 配置对比 - 不同环境／模式下的配置差异
4. API 清单 - 公共 API 的方法、参数和返回值
5. 依赖项清单 - 关键依赖项的版本和用途

输出要求

1. 文件名：REPOWIKI.md，放置在仓库根目录
2. 语言：与用户的对话语言一致（中文对话 = 中文报告）
3. 长度：
   • 小型项目（<50 个文件）：800-1500 行
   • 中型项目（50-200 个文件）：1500-3000 行
   • 大型项目（>200 个文件）：3000-6000 行
4. 图表数量：至少 3 个 Mermaid 图表；大型项目需 6-10 个
5. 表格数量：至少 3 个
6. 代码块：关键配置和接口定义，每个代码块不超过 30 行

质量检查清单

生成报告后，请核实以下各项：

• 包含项目概述和一句话定位
• 技术栈表格完整且准确
• 仓库结构 Mermaid 图与实际情况相符
• 每个核心系统都有独立章节
• 每个章节都包含可折叠的源文件引用
• 模块依赖关系图准确反映实际依赖
• 至少有一个序列图展示核心工作流
• 所有表格格式正确且内容准确
• 代码块语法高亮标注正确
• 未虚构文件或模块
• Mermaid 图表语法正确且可渲染

示例片段

以下是 TypeScript Web 项目的报告片段示例：

# MyApp

> A full-stack e-commerce platform built on Next.js, supporting multi-tenancy and real-time inventory management.

## Purpose & Scope

MyApp is an e-commerce SaaS platform for small and medium-sized merchants. It provides
product management, order processing, payment integration, and real-time inventory
synchronization as core features. The project uses Next.js App Router architecture,
Prisma as the ORM, and PostgreSQL as the primary database.

## Tech Stack

| Category | Technology | Purpose |
|----------|-----------|---------|
| Language | TypeScript 5.3 | Full-stack development language |
| Framework | Next.js 14 | Full-stack React framework |
| ORM | Prisma 5.8 | Database access layer |
| Database | PostgreSQL 16 | Primary data storage |
| Cache | Redis 7 | Session and hot data caching |
| Testing | Vitest + Playwright | Unit and E2E testing |

## Repository Structure

```mermaid
graph TD
    Root["myapp/"]
    Root --> App["app/ - Next.js App Router"]
    Root --> Lib["lib/ - Shared Business Logic"]
    Root --> Components["components/ - UI Components"]
    Root --> Prisma["prisma/ - Database Schema"]
    Root --> Tests["tests/ - Test Files"]

    App --> API["api/ - API Routes"]
    App --> Pages["(routes)/ - Pages"]
    Lib --> Services["services/ - Business Services"]
    Lib --> Utils["utils/ - Utility Functions"]

核心系统概览

graph LR
    Client["Client"] --> AppRouter["App Router"]
    AppRouter --> Auth["Auth System"]
    AppRouter --> API["API Layer"]
    API --> OrderService["Order Service"]
    API --> ProductService["Product Service"]
    API --> PaymentService["Payment Service"]
    OrderService --> DB["PostgreSQL"]
    ProductService --> DB
    ProductService --> Cache["Redis"]
    PaymentService --> Stripe["Stripe API"]

订单系统

相关源文件

• lib/services/order.ts - 订单服务核心逻辑
• app/api/orders/route.ts - 订单 API 路由
• prisma/schema.prisma - 订单数据模型
• lib/validators/order.ts - 订单数据校验
• components/order/OrderForm.tsx - 订单表单组件

用途与范围

订单系统负责管理从购物车到付款完成的完整订单生命周期。 这包括创建订单、锁定库存、处理付款、状态流转以及发送通知。

订单生命周期

stateDiagram-v2
    [*] --> Created: User places order
    Created --> Paying: Initiate payment
    Paying --> Paid: Payment successful
    Paying --> Cancelled: Payment timeout/failure
    Paid --> Shipping: Merchant ships
    Shipping --> Completed: Delivery confirmed
    Completed --> [*]
    Cancelled --> [*]

## Language/Framework Adaptation

Adjust analysis focus based on project type:

| Project Type | Analysis Focus |
|-------------|---------------|
| Node.js/TypeScript | package.json, tsconfig, module exports |
| Go | go.mod, package structure, interface definitions |
| Python | pyproject.toml, package structure, class hierarchy |
| Rust | Cargo.toml, crate structure, trait definitions |
| Java/Kotlin | pom.xml/build.gradle, package structure, class hierarchy |
| Monorepo | workspace config, inter-package dependencies, build order |
| Frontend SPA | routing structure, state management, component tree |
| Backend API | route definitions, middleware chain, data models |
| CLI Tool | command structure, argument parsing, subcommands |