project-helper 项目学习助手

project-helper 是一个面向学生和初学开发者的 GitHub 开源项目学习助手。输入任意 GitHub 仓库地址后，系统会自动克隆源码、扫描目录结构、识别技术栈、提取关键文件，并调用 DeepSeek OpenAI-compatible API 生成通俗易懂的项目分析报告。分析完成后，用户还可以围绕真实源码继续问答，Agent 会通过文件读取、代码搜索、目录查看等工具查找源码后再回答。

功能亮点

• GitHub 仓库地址校验、克隆、失败重试和 Git CLI 兜底克隆
• 源码目录树扫描，自动过滤 .git、node_modules、target、dist 等无关目录
• 技术栈、主语言、入口文件、关键配置和核心源码文件识别
• DeepSeek / OpenAI-compatible 模型生成完整项目分析报告
• SSE 实时进度推送，前端链式展示每个分析步骤
• MySQL 持久化项目报告、目录树、关键文件和任务状态
• Redis 缓存已分析项目，避免重复分析
• 源码问答 Agent，支持读取文件、搜索代码、定位类和方法、查看目录结构
• Vue 3 工作台式界面，支持 Markdown 渲染和代码高亮

页面预览

┌───────────────────────────────┬─────────────────────┐
│ 输入 GitHub 仓库地址           │ 最近分析项目         │
│                               │                     │
│ 校验仓库地址      已完成       │ liyupi/yu-ai-agent  │
│ 克隆项目源码      进行中       │ Sj295/interview...  │
│ 扫描源码结构      等待中       │                     │
│ 生成分析报告      等待中       │                     │
│ 保存分析结果      等待中       │                     │
└───────────────────────────────┴─────────────────────┘

报告详情页：左侧阅读 Markdown 分析报告、目录树和关键文件，右侧对源码进行流式问答。

系统架构

flowchart LR
    User["用户"] --> Web["Vue 3 前端"]
    Web -->|REST| API["Spring Boot API"]
    Web -->|SSE| Progress["分析进度流"]
    API --> Git["JGit / Git CLI"]
    Git --> Repo["本地源码工作区"]
    API --> Scanner["源码扫描器"]
    Scanner --> Repo
    API --> AI["Spring AI + DeepSeek"]
    API --> DB["MySQL"]
    API --> Cache["Redis"]
    AI --> Tools["源码 Agent 工具"]
    Tools --> Repo

Loading

技术栈

后端：

• Java 17+
• Spring Boot 3.5
• Spring AI 1.1
• Spring Web + SseEmitter
• MyBatis-Plus
• MySQL 8
• Redis
• JGit + Git CLI fallback
• DeepSeek OpenAI-compatible API
• Lombok / Hutool
• Maven

前端：

• Vue 3
• Vite
• TypeScript
• Pinia
• Vue Router
• Element Plus
• Markdown-it
• Highlight.js
• EventSource / SSE

快速启动

1. 启动 MySQL 和 Redis

docker compose up -d

默认会创建：

• MySQL: localhost:3306
• Database: project_helper
• Username: project_helper
• Password: project_helper
• Redis: localhost:6379

2. 配置环境变量

Windows PowerShell:

$env:DEEPSEEK_API_KEY="你的 DeepSeek API Key"
$env:DEEPSEEK_MODEL="deepseek-chat"

macOS / Linux:

export DEEPSEEK_API_KEY="你的 DeepSeek API Key"
export DEEPSEEK_MODEL="deepseek-chat"

可选变量见 .env.example。

3. 启动后端

cd backend
mvn spring-boot:run

后端默认地址：http://localhost:8080

4. 启动前端

cd frontend
npm install
npm run dev

前端默认地址：http://localhost:5173

API 概览

方法	路径	说明
POST	/api/projects/analyze	提交 GitHub 仓库分析任务
GET	/api/projects/{id}/progress	SSE 订阅分析进度
GET	/api/projects/{id}	查询项目分析详情
GET	/api/projects	查询历史分析项目
GET	/api/projects/{id}/chat/stream	SSE 源码问答

更完整的接口说明见 docs/API.md。

目录结构

project-helper/
  backend/                  Spring Boot 后端
    src/main/java/
      common/               通用响应和异常处理
      config/               CORS、异步线程池、应用配置
      controller/           REST / SSE 接口
      dto/                  请求响应 DTO
      entity/               MySQL 实体
      mapper/               MyBatis-Plus Mapper
      service/              克隆、扫描、报告和问答服务
      tool/                 Spring AI 源码工具
    src/main/resources/
      application.yml       应用配置
      schema.sql            数据库表结构
  frontend/                 Vue 3 前端
    src/api/                HTTP API
    src/components/         Markdown 和 Chat 组件
    src/router/             Vue Router
    src/stores/             Pinia 状态
    src/views/              分析、历史、详情页面
  docs/                     文档
  docker-compose.yml        本地 MySQL / Redis

常见问题

为什么 DeepSeek V4 工具调用要禁用 thinking？

DeepSeek V4 thinking 模式在工具调用多轮续传时要求带回 reasoning_content。当前 Spring AI OpenAI 适配不会自动传递这个 DeepSeek 扩展字段，所以项目在工具问答请求中透传：

thinking:
  type: disabled

这样可以稳定支持 Spring AI Tools + DeepSeek 的源码问答。

为什么克隆失败后会自动切换 Git CLI？

JGit 在 Windows 或网络波动环境下偶尔会遇到 Connection reset。系统会先用 JGit 重试，再 fallback 到 git clone --depth 1，提高真实使用时的成功率。

开发与验证

cd backend
mvn -q -DskipTests package

cd ../frontend
npm run build

License

MIT