Skip to content

codewriterYang/RepoLens

BranchesTags

Repository files navigation

RepoLens — AI 驱动的仓库分析平台

在 3 分钟内分析任意 GitHub 仓库。 获取代码质量洞察、仓库结构理解、Git 活动趋势和结构化 HTML 报告 — 全部通过一个 API 调用完成。

项目简介

RepoLens 对克隆的仓库并行运行三个 Agent（静态/仓库/Git），通过 AgentRegistry 统一调度：

Agent（底层分析器） 检查内容 产出
StaticAgent（StaticAnalyzer） Pylint + Radon 圈复杂度 高风险文件、复杂函数、lint 热力图
RepoAgent（RepoAnalyzer） README + 目录树 + 包元数据（LLM 推理） 使用模式、核心模块、推断风险
GitAgent（GitAnalyzer） git log、git shortlog、CI/CD 配置 提交历史、贡献者、活动时间线

Reporter（报告生成器） 将所有结果合并为自包含的 HTML 报告，包含可折叠区域、行内图表和优先排序的改进建议。

🖥️ 运行效果预览
页面 截图
分析输入页 分析输入页
报告概览 报告概览
代码质量详情 代码质量详情

架构概览

POST /api/analyze
       │
       ▼
   Orchestrator（异步编排 + AgentRegistry + ContextManager）
       │
       ├──▶ git clone（300s 超时）
       │     └─→ ContextManager.create()
       │
       ├──▶ StaticAgent ←─┐
       ├──▶ RepoAgent   ←─┼── Context 统一传递
       └──▶ GitAgent    ←─┘
              │
              ▼
          Reporter（报告生成）
              │
              ▼
       GET /api/report/{job_id}

三个 Agent 互相独立 — 任何一个失败都不会阻碍其他 Agent。Reporter 优雅处理缺失结果，部分结果在流水线运行期间可通过 GET /api/status/{job_id} 获取。

📖 文档导航：架构设计 · 工作流程 · 技术选型 · 演进日志 · 架构图 · ADR · 测试 · 案例

快速开始

Docker 一键启动（推荐）

# 1. 配置 API Key
cp .env.example .env
# 编辑 .env，填入 LLM_API_KEY

# 2. 启动（前后端全栈）
docker compose up -d

镜像内置 Python + Git + Pylint + Radon（后端）+ Node/Nginx（前端），无需手动安装任何依赖。

服务 地址 用途
前端 UI http://localhost:5173 网页界面，输入仓库链接即可分析
API 文档 http://localhost:8770/docs Swagger，直接调用接口
健康检查 http://localhost:8770/api/health 确认后端存活

前端自动通过 Nginx 将 /api/* 请求代理到后端，无需额外配置。

📦 分析数据持久化在 ./data/ 目录（参见 docker-compose.yml），docker compose down 不会删除历史记录。

📖 更多 Docker 命令（构建、日志、容器调试、排错等）见 docs/DEPLOYMENT.md。

本地开发启动

环境要求

  • Python 3.11+
  • Git 已安装并位于 PATH
  • 一个 OpenAI 兼容的 API Key（或其他提供 /v1/chat/completions 的厂商）

1. 配置

cd repolens

# 从模板创建 .env 文件
cp .env.example .env
# 编辑 .env 填入你的 LLM_API_KEY

2. 安装依赖

cd backend
pip install -e .        # 生产依赖
pip install -e ".[dev]" # 含 pytest + ruff（开发用）

3. 启动后端

python -m uvicorn repolens.main:app --host 0.0.0.0 --port 8770 --reload

4. 启动前端（可选）

cd frontend
pnpm install
pnpm dev
# 访问 http://localhost:5173，已配置 API 代理到后端

5. 提交分析请求

# 分析 GitHub 仓库
curl -X POST http://localhost:8770/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "https://github.com/psf/requests"}'

# 返回：{"job_id": "abc123...", "status": "queued"}

6. 轮询进度

curl http://localhost:8770/api/status/abc123
# 返回：{"status": "analyzing", "progress_pct": 45, "stage_label": "正在分析代码...", ...}

7. 获取报告

# JSON 格式报告
curl http://localhost:8770/api/report/abc123

# 自包含 HTML 报告
curl http://localhost:8770/api/report/abc123/html

API 接口

方法 路径 说明
POST /api/analyze 提交仓库分析请求
GET /api/status/{job_id} 轮询进度与部分结果
GET /api/report/{job_id} 获取完成报告（JSON）
GET /api/report/{job_id}/html 获取完成报告（HTML）
GET /api/history 列出最近的分析任务
GET /api/health 健康检查

报告内容

HTML 报告包含以下内容：

  • 健康评分 — 0-100 综合评分，含 4 个维度细分（代码质量、仓库清晰度、社区活跃、工程实践）
  • 改进建议 — 跨三个分析器的优先排序建议，包含交叉分析洞察（如"高频变更与高风险文件重叠"）
  • 代码质量 — 可折叠文件风险表（按 HIGH/MEDIUM/LOW 排序）、高复杂度函数列表
  • 仓库洞察 — 使用模式、核心模块、LLM 推断风险、README 质量评分
  • Git 活动 — 提交统计、行内 SVG 时间线图表（12 周趋势）、贡献者表格、活跃文件

不知道分析哪个仓库？参见 samples/README.md 的推荐测试仓库列表。

项目结构

repolens/
├── backend/
│   ├── repolens/              # Python 包
│   │   ├── main.py            # FastAPI 应用与路由
│   │   ├── config.py          # 环境变量配置
│   │   ├── schemas.py         # Pydantic 数据模型（API 契约）
│   │   ├── db.py              # SQLite 持久化层
│   │   ├── orchestrator.py    # 流水线编排器
│   │   ├── reporter.py        # HTML 报告生成器
│   │   ├── cloner.py          # Git 克隆/清理工具
│   │   ├── llm_service.py     # OpenAI 兼容 LLM 客户端
│   │   ├── agents/              # Agent 层（v2.0）
│   │   │   ├── base.py          # BaseAgent 抽象基类
│   │   │   ├── registry.py      # AgentRegistry 注册中心
│   │   │   ├── planner_agent.py # PlannerAgent（策略制定，Phase 5）
│   │   │   ├── static_agent.py  # 封装 StaticAnalyzer
│   │   │   ├── repo_agent.py    # 封装 RepoAnalyzer
│   │   │   ├── git_agent.py     # 封装 GitAnalyzer
│   │   │   └── report_agent.py  # ReportAgent（汇总报告，Phase 6）
│   │   ├── context/             # Context 层（v2.1）
│   │   │   ├── base.py          # RepositoryContext 不可变上下文
│   │   │   ├── repository_context.py  # 上下文工厂函数
│   │   │   └── context_manager.py     # ContextManager 生命周期
│   │   ├── memory/              # Memory 层（v2.2）
│   │   │   ├── base.py          # SharedMemory 线程安全 KV 存储
│   │   │   ├── shared_memory.py # 辅助函数
│   │   │   └── memory_manager.py     # MemoryManager 生命周期
│   │   ├── planner/             # Planner 层（v2.5，动态策略引擎）
│   │   │   ├── repository_profiler.py # 仓库特征分析
│   │   │   ├── planning_rules.py      # 规则引擎
│   │   │   └── dynamic_planner.py     # 动态策略编排
│   │   └── analyzers/
│   │       ├── static_analyzer.py  # Pylint + Radon
│   │       ├── repo_analyzer.py    # README + 目录树 + LLM
│   │       └── git_analyzer.py     # Git 活动 + CI/CD
│   ├── pyproject.toml
│   └── README.md
├── frontend/                  # React + TypeScript 界面
│   ├── src/
│   │   ├── components/        # UI 组件
│   │   │   └── __tests__/     # 组件测试
│   │   ├── hooks/             # 自定义 React Hook
│   │   ├── store/             # Zustand 状态管理
│   │   ├── types/             # TypeScript 类型定义
│   │   └── lib/               # API 客户端、工具函数
│   ├── Dockerfile             # 多阶段构建（Node → Nginx）
│   ├── nginx.conf             # SPA 路由 + API 反向代理
│   ├── package.json
│   ├── vite.config.ts
│   └── README.md
├── tests/                     # 集成测试
├── images/                    # 界面截图
├── scripts/                   # 开发辅助脚本
├── samples/                   # 推荐测试仓库列表
├── ARCHITECTURE.md            # 系统架构文档
├── WORKFLOW.md                # 完整工作流程详解
├── DECISIONS.md               # 技术选型说明
├── docs/
│   └── EVOLUTION_LOG.md       # 项目演进日志
└── README.md

Agent 工作流

POST /api/analyze
  → Clone → ContextManager → MemoryManager
  → PlannerAgent (strategy: full/focused/fast)
  → StaticAgent ╗
  → RepoAgent   ║ 并行执行
  → GitAgent    ╝
  → Reporter → ReportJson → SQLite
  → GET /api/report/{id}

策略引擎

仓库规模决定 StaticAgent 的执行深度（所有 Agent 始终执行，不跳过）：

文件数 策略 置信度 行为
≤ 500 full 100% 完整 pylint + radon
501–1000 focused 75% 排除测试文件 pylint + 全量 radon
> 1000 fast 50% 仅 radon cc

设计原则

  • 清晰优先于复杂 — 单文件分析器、扁平包结构、无依赖注入框架
  • 优雅降级 — 每个分析器的失败都不会导致整体崩溃；部分结果始终可用
  • 自包含输出 — HTML 报告零外部依赖（无 CDN、无 JS 框架）
  • 跨平台兼容 — 子进程通过 subprocess.run + asyncio.to_thread 执行，兼容 Windows/Linux/macOS
  • 可配置超时 — 分析器级和流水线级超时防止失控任务

文档导航

文档 说明
ARCHITECTURE.md 系统架构设计
WORKFLOW.md 完整分析工作流程
DECISIONS.md 技术选型说明
docs/DEPLOYMENT.md Docker 部署运维指南
docs/EVOLUTION_LOG.md 项目演进日志
docs/architecture/ 架构图（Mermaid）
docs/adr/ 架构决策记录（ADR）
docs/testing/ 测试报告
docs/case-studies/ 真实案例分析
docs/performance/ 性能基准
samples/ 推荐测试仓库

配置说明

所有设置通过环境变量配置（参见 .env.example）：

变量 默认值 说明
LLM_BASE_URL https://api.openai.com/v1 OpenAI 兼容 API 地址
LLM_API_KEY （必填） LLM 厂商的 API Key
LLM_MODEL gpt-4o-mini 模型名称
HOST 0.0.0.0 服务器绑定地址
PORT 8770 服务器端口
DB_PATH data/repolens.db SQLite 数据库路径
TMP_DIR （自动检测系统临时目录） 仓库克隆临时目录。可选，留空自动适配系统。Linux/Mac → /tmp/repolens，Windows → %TEMP%\repolens
PIPELINE_TIMEOUT_SECONDS 600 流水线总超时（秒），大仓库可适当调大
CLONE_TIMEOUT_SECONDS 300 克隆超时（秒），大仓库可适当调大
LLM_TIMEOUT_SECONDS 120 LLM API 请求超时（秒），慢速 API 可调大

测试

# 从项目根目录运行集成测试
PYTHONPATH=backend python -m pytest tests/ -v

# 或直接运行集成测试脚本
PYTHONPATH=backend python tests/test_integration.py

许可证

MIT — 详见 LICENSE。

About

AI 驱动的 Python 仓库分析平台 — 代码质量、仓库意图、Git 活动、结构化洞察

Topics

react python typescript static-analysis code-analysis openai developer-tools software-engineering fastapi repository-analysis llm git-analytics

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

2 tags

Packages

 
 
 

Contributors

Languages