openDeepWiki

KO | EN

gitlite — search

#javascript #ai #typescript #llm #go #machine-learning #rust #linux #nodejs #awesome #vue #mcp #openai #open-source

(★ 97)

完全AI驱动的 DeepWiki ,使用 Go + Eino 技术栈开发

openDeepWiki Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# openDeepWiki

[English](./README_EN.md) | 简体中文

## 项目简介

openDeepWiki 是一个完全AI驱动的 DeepWiki ,使用 Go + Eino 技术栈开发的代码仓库智能解读平台，能够自动分析任意 GitHub 代码仓库，并生成结构化的项目文档。帮助开发者快速理解开源项目的架构、API 和业务流程。

## 🌟 在线体验

[https://opendeepwiki.k8m.site/](https://opendeepwiki.k8m.site/)

无需安装配置，立即体验 openDeepWiki 的强大功能！

## ✨ 功能特性亮点

### 🎯 核心功能

#### 1. 智能文档生成系统
- **多 Agent 协作架构**：基于 Eino ADK 框架的多角色智能体系统，支持目录制定、文档生成、校验等全流程协作
- **任务编排器与状态机**：引入任务编排器和状态机，实现任务的可靠调度、依赖管理和状态流转
- **任务依赖与重试机制**：支持 RunAfter 任务依赖检查，自动重试失败任务，支持批量重试和强制重置
- **任务用量监控**：实时记录和显示 Token 用量、任务执行耗时，提供透明的资源使用情况
- **文档多版本管理**：支持文档多版本保存，可查看历史版本并对比差异
- **事件总线系统**：支持任务事件发布与订阅，实现系统各组件间的松耦合通信

#### 2. 高级文档导出
- **PDF 导出功能**：
  - 支持完整文档导出为 PDF，保留原有格式和样式
  - 智能目录书签生成，支持层级嵌套和点击跳转
  - 表格优化渲染，支持紧凑布局和中文适配
  - 代码块中文支持，解决乱码问题
  - 字体回退机制，确保在不同环境下正常显示

#### 3. 智能代码分析
- **API 接口分析**：自动识别和解析 API 接口，生成接口文档
- **数据库模型解析**：分析数据库结构，生成数据模型文档
- **前端组件解析**：识别前端组件，生成组件使用文档
- **AST 与语义解析**：深度分析代码结构，提取核心逻辑
- **目录提纲输出**：自动生成结构化文档目录，支持自定义调整

#### 4. 多模型支持与智能切换
- **API Key 管理**：支持多个 API Key 配置，优先级管理和禁用控制
- **模型自动切换**：运行时动态切换模型，支持限流检测和自动降级
- **模型池代理**：统一管理多个模型，提供负载均衡和故障转移
- **智能兜底策略**：模型调用失败时自动切换到备用模型，提高稳定性

#### 5. 数据同步与备份
- **数据同步功能**：支持仓库数据双向同步，可按文档筛选同步任务
- **同步历史记录**：记录所有同步操作，支持查看历史和回滚
- **对端地址管理**：管理同步对端地址，支持添加、编辑和删除
- **清空目标数据**：支持一键清空目标服务器数据
- **TaskUsage 同步**：同步任务用量数据，实现分布式环境下的资源统计

### 🔧 技术特性

#### 6. 系统架构优化
- **分层架构设计**：
  - 领域层（Domain）：核心业务逻辑和领域模型
  - 服务层（Service）：业务服务和编排逻辑
  - 数据层（Repository）：数据访问和持久化
  - 处理器层（Handler）：HTTP 请求处理和响应
- **事件驱动架构**：基于事件总线实现系统解耦和异步处理
- **配置驱动 Agent**：基于 YAML 配置的 Agent 管理，支持热加载
- **模块化设计**：按功能模块拆分代码，提高可维护性

#### 7. 开发与运维支持
- **全局任务监控**：实时查看所有仓库的任务执行状态和进度
- **智能模板分配**：根据仓库类型自动选择合适的文档模板
- **仓库分支管理**：支持多分支管理，自动识别主分支
- **任务统计显示**：统计任务成功、失败、排队等状态数量
- **文档评分系统**：对生成的文档进行质量评分，提供改进建议

#### 8. 用户体验增强
- **响应式设计**：支持移动端和桌面端，自适应不同屏幕尺寸
- **主题切换**：支持亮色和暗色主题，满足不同环境需求
- **国际化支持**：支持中英文切换，可扩展多语言
- **文档概览页面**：快速查看仓库所有文档概览和任务状态
- **仓库信息展示**：显示仓库分支、大小、提交信息等元数据

#### 9. 开发工具与规范
- **严格的开发规范**：
  - 后端开发规范：分层架构、错误处理、测试规范等
  - 前端开发规范：组件编写、状态管理、样式规范等
  - 文档编写规范：需求文档、设计文档、测试文档等
- **AI 协作开发约定**：定义 AI 参与代码编写的完整协作流程
- **代码质量保证**：
  - 单元测试覆盖核心功能
  - 集成测试验证端到端流程
  - 代码审查清单确保代码质量
- **文档驱动开发**：先写设计文档，再写代码，确保思路清晰

#### 10. 部署与扩展
- **Docker 支持**：提供完整的 Dockerfile 和 Docker Compose 配置
- **多平台构建**：支持 Linux、macOS、Windows 等多平台编译
- **Fly.io 部署**：提供一键部署到 Fly.io 的配置
- **静态链接二进制**：生成无依赖的可执行文件，便于部署
- **热重载开发**：使用 Air 实现开发时自动重载，提高开发效率

#### 11. PDF 导出增强
- 书签层级管理，支持多级目录结构
- 自动链接生成，点击目录跳转到对应章节
- 表格样式优化，支持紧凑布局和无间隙渲染
- 代码块中文适配，解决中文字符乱码问题
- 字体支持与回退机制，确保跨平台兼容性

#### 12. 任务管理优化
- 任务事件总线，支持任务生命周期事件的发布和订阅
- 任务依赖检查，防止任务执行顺序错误
- Pending 任务自动入队，定期处理待处理任务
- 任务重试机制，失败任务自动重试
- 批量重试所有报错任务，提高任务执行效率

#### 13. Agent 系统增强
- Agent 配置文件驱动，支持热加载和动态更新
- 模型列表支持，一个 Agent 可配置多个模型
- 终端命令执行工具，扩展 Agent 能力
- Markdown 校验代理，检查文档格式和语法
- 目录提纲输出，生成结构化文档目录

#### 14. 文档管理改进
- 文档多版本保存，支持查看历史版本
- 文档评分系统，评估文档质量
- 文档元数据展示，显示创建时间和更新时间
- 文档列表优化，显示最后更新时间
- 文档概览页面，快速查看所有文档

#### 15. 仓库管理增强
- 仓库分支管理，支持多分支切换
- 仓库元数据记录，记录仓库大小、分支和提交信息
- 仓库 URL 规范化，支持多种格式
- 仓库删除优化，支持仅删除本地目录
- 仓库重新下载，快速更新仓库内容

#### 16. UI/UX 优化
- 响应式布局改进，支持移动端和桌面端
- 任务监控界面，实时查看任务执行状态
- 仓库信息展示，显示仓库分支和大小
- 任务统计显示，统计任务状态分布
- 任务列表优化，显示任务类型和写入器

---

## 技术栈

### 后端
- **语言**：Go 1.24+
- **框架**：Gin
- **数据库**：SQLite（默认）/ MySQL
- **ORM**：GORM
- **日志**：klog
- **开发工具**：Air（热重载）

### 前端
- **框架**：React 19 + TypeScript
- **构建工具**：Vite
- **UI 组件**：Ant Design 6
- **Markdown 渲染**：react-markdown / react-md-editor
- **路由**：React Router 7

### AI 集成
- 支持 OpenAI 兼容接口
- 可配置 API 地址、模型和 Token
- 支持通过环境变量配置

## 快速开始

### 环境要求

- Go 1.24+
- Node.js 18+
- Git

### 安装步骤

```bash
# 1. 克隆项目
git clone https://github.com/weibaohui/openDeepWiki.git
cd openDeepWiki

# 2. 安装依赖
make setup

# 3. 初始化配置
make init-config

# 4. 编辑配置文件，设置 LLM API Key
vim backend/config.yaml
# 或设置环境变量
export OPENAI_API_KEY="your-api-key"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL_NAME="gpt-4o"
```

### 启动服务

```bash
# 开发模式（推荐）：同时启动前后端，支持热重载
make dev

# 或分别启动
make air           # 后端（带热重载）
make run-frontend  # 前端

# 生产模式
make build
make run-backend
```

### 使用预编译二进制（无需源码）

从 [GitHub Releases](https://github.com/weibaohui/openDeepWiki/releases) 下载对应平台的二进制文件：

```bash
# 下载后解压运行（自动释放默认 agents）
./opendeepwiki
```

**说明：** 从 v0.x 版本开始，agents 文件夹已内嵌到二进制中，首次运行会自动释放到 `./agents` 目录。如需自定义 agent，可直接修改该目录下的 YAML 文件。

### 访问地址

- 前端页面：http://localhost:5173
- 后端 API：http://localhost:8080

## 使用指南

### 1. 配置 LLM

首次使用需要配置 LLM API：

**方式一：通过配置文件**

编辑 `backend/config.yaml`：

```yaml
llm:
  api_url: "https://api.openai.com/v1"
  api_key: "your-api-key"
  model: "gpt-4o"
  max_tokens: 4096
```

**方式二：通过环境变量（推荐）**

```bash
export OPENAI_API_KEY="your-api-key"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL_NAME="gpt-4o"
```

**方式三：通过前端界面**

访问 `http://localhost:5173/config` 进行配置。

### 2. 解读代码仓库

1. 在首页输入 GitHub 仓库 URL（支持 https 和 git@ 格式）
2. 点击「添加」，系统自动克隆仓库
3. 克隆完成后，点击「执行所有任务」开始分析
4. 等待任务执行完成（5 个任务：概览、架构、接口、业务流程、部署）
5. 点击「查看文档」阅读生成的结果

### 3. 文档管理

- **在线阅读**：左侧导航树，右侧 Markdown 渲染
- **在线编辑**：点击「编辑」按钮修改文档内容
- **导出文档**：支持单个文档或整体打包导出

## 系统架构
```mermaid
flowchart TB

%% 外部系统
    subgraph EXT[外部系统]
        GitRepo[代码仓库\nGitHub / GitLab / Gitee]
        User[用户 / 开发者]
    end

%% 代码接入与触发层
    subgraph L1[代码仓库接入与触发层]
        Importer[仓库导入器]
        BranchMgr[分支与主分支管理]
        Webhook[Webhook 触发器]
        Syncer[代码同步器]
    end

%% 版本与数据层
    subgraph L2[代码版本与数据层]
        CodeSnapshot[代码快照\nRepo + Branch + Commit]
        DiffAnalyzer[Commit 差异分析器]
        MetaDB[(元数据存储\nRepo / Branch / Commit / Tag)]
    end

%% 代码理解层
    subgraph L3[代码解析与结构化分析层]
        RepoScanner[仓库预处理分析\n结构 技术栈 入口]
        ASTParser[AST 与语义解析器]
        APIParser[API 专项解析器]
        DBParser[数据库结构解析器]
        FEParser[前端组件解析器]
        StructStore[(结构化分析结果存储)]
    end

%% AI 编排与生成核心层
    subgraph L4[AI 编排与文档生成核心层]
        TOCGen[目录生成器\nTOC Generator]
        UserTOCExt[用户目录扩展\n命题式调查]
        TaskPlanner[文档任务拆解器]
        DocWriter[文档生成器\nMarkdown 与 Mermaid]
        Reviewer[一致性校对与回顾分析]
        Incremental[增量更新处理器]
    end

%% 文档与知识资产层
    subgraph L5[文档与知识资产层]
        DocStore[(文档库\n多版本 多语言)]
        MermaidStore[(流程图与架构图)]
        BadgeSvc[状态徽标服务\nBadge API]
    end

%% 智能问答器
    subgraph L6[智能问答器]
        Embedding[内容向量化]
        VectorDB[(向量数据库)]
        QAChat[问答引擎]
        FAQGen[高频问题整理\n反向生成目录]
    end

%% 前端交互层
    subgraph L7[前端与交互层]
        DocUI[文档浏览\n多语言 多版本]
        TOCEditor[目录编辑器]
        MermaidUI[流程图编辑与预览]
        ChatUI[智能问答界面]
    end

%% 数据流关系
    GitRepo --> Importer
    Importer --> BranchMgr
    BranchMgr --> Syncer
    Webhook --> Syncer

Syncer --> CodeSnapshot
    CodeSnapshot --> DiffAnalyzer
    CodeSnapshot --> RepoScanner

RepoScanner --> ASTParser
    ASTParser --> APIParser
    ASTParser --> DBParser
    ASTParser --> FEParser

ASTParser --> StructStore
    APIParser --> StructStore
    DBParser --> StructStore
    FEParser --> StructStore

StructStore --> TOCGen
    TOCGen --> UserTOCExt
    UserTOCExt --> TaskPlanner
    TaskPlanner --> DocWriter
    DocWriter --> Reviewer
    Reviewer --> DocStore
    DocWriter --> MermaidStore

DiffAnalyzer --> Incremental
    Incremental --> TaskPlanner

DocStore --> Embedding
    Embedding --> VectorDB
    VectorDB --> QAChat
    QAChat --> FAQGen
    FAQGen --> TOCGen

DocStore --> BadgeSvc

%% 前端连接
    User --> DocUI
    User --> TOCEditor
    User --> MermaidUI
    User --> ChatUI

DocUI --> DocStore
    TOCEditor --> TOCGen
    MermaidUI --> MermaidStore
    ChatUI --> QAChat

```

## 开发规范

项目遵循严格的开发规范，详见：

- [后端开发规范](./doc/开发规范/后端规范/)
- [前端开发规范](./doc/开发规范/前端规范/)

## 许可证

[MIT License](./LICENSE)

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

如有问题或建议，请提交 Issue。

openDeepWiki

openDeepWiki Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

openDeepWiki

openDeepWiki Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README