# CodeLintAI

**Repository Path**: luo-youlu6/code-lint-ai

## Basic Information

- **Project Name**: CodeLintAI
- **Description**: 基于 LangChain 、LangGraph引擎 、Langfuse监控和LangServe 的智能代码分析服务，提供 Commit Message 生成、RAG 文档问答和知识库管理功能。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-08-05
- **Last Updated**: 2025-11-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CodeLintAI - 智能代码分析服务

[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-green.svg)](https://fastapi.tiangolo.com/)
[![LangChain](https://img.shields.io/badge/LangChain-0.1+-orange.svg)](https://www.langchain.com/)
[![Langfuse](https://img.shields.io/badge/Langfuse-2.x-purple.svg)](https://langfuse.com/)

CodeLintAI 是一个基于 LangChain 、 Langfuse 2.x、LangServe、LangGraph 的智能代码分析服务，提供代码规范检查、Commit Message 生成、RAG 文档问答等功能。

## ✨ 核心特性

- 🔍 **智能代码规范检查**: 基于 RAG 检索相关规范文档进行代码审查
- 📝 **Commit Message 生成**: 自动生成符合规范的 Git 提交信息
- 🤖 **RAG 文档问答**: 基于知识库的智能问答系统
- 📊 **Langfuse 监控集成**: 完整的调用链路追踪和性能监控
- 🔄 **LangGraph 工作流**: 支持复杂的工作流编排
- 🐳 **Docker 部署**: 一键部署，开箱即用

## 🚀 快速开始

### 环境要求

- Python 3.11+
- Docker (可选)
- OpenAI API Key
- Langfuse 账户

## 一、本地部署（开发/测试环境）

### 前置条件
- 操作系统：Windows/macOS/Linux
- 依赖工具：
  - Python 3.8 及以上版本
  - pip（Python 包管理器）
  - Git（代码克隆）


### 部署步骤

#### 1. 克隆项目代码
打开终端（Windows 用 PowerShell/CMD，macOS/Linux 用终端），执行以下命令：
```bash
git clone https://github.com/your-username/CodeLintAI.git
cd CodeLintAI
```


#### 2. 配置 Python 虚拟环境（推荐）
创建独立虚拟环境，避免依赖冲突：
```bash
# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows (PowerShell)
.\venv\Scripts\Activate.ps1
# Windows (CMD)
venv\Scripts\activate.bat
# macOS/Linux
source venv/bin/activate
```
激活后终端提示符会显示 `(venv)`，表示虚拟环境已生效。


#### 3. 安装项目依赖
通过 `requirements.txt` 安装所有依赖：
```bash
# 基础安装
pip install -r requirements.txt

# 若速度慢，可添加国内镜像源（如阿里云）
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
```
- 若出现依赖冲突，尝试升级 pip 后重试：
  ```bash
  pip install --upgrade pip
  ```


#### 4. 配置环境变量
在项目根目录创建 `.env` 文件，填入以下配置（替换为实际值）：
```env
# OpenAI API 配置
OPENAI_API_KEY=3fd1db3b-eaf9-48d5-90cc-xxxxxxxxxxx

# Langfuse 监控配置
LANGFUSE_PUBLIC_KEY=pk-lf-73b135d1-ac15-4da4-85c0-xxxxxxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-60f3b528-5673-4e6d-afef-xxxxxxxxxxxx

# OpenAI API 基础 URL
OPENAI_BASE_URL=https://ark.cn-beijing.volces.com/api/v3

# Langfuse 服务地址
LANGFUSE_HOST=https://test.langfuse.cyouai.com

# 服务端口
PORT=8000
```
- 注意：`.env` 文件需与 `app.py` 同级，否则程序无法读取环境变量。


#### 5. 启动服务
根据场景选择启动方式：
```bash
# 开发模式（代码修改后自动重启）
uvicorn app:app --reload --host 0.0.0.0 --port 8000

# 生产模式（稳定性优先，无自动重启）
python app.py
```


#### 6. 验证部署
服务启动后，通过以下地址访问：
- API 文档：http://localhost:8000/docs
- 健康检查：http://localhost:8000/api/code-review/health


## 二、Docker Compose 部署（推荐生产环境）

### 前置条件
- 安装 Docker（20.10+）和 Docker Compose（v2+）
  - 安装指南：[Docker 官方文档](https://docs.docker.com/get-docker/)


### 部署步骤

#### 1. 克隆项目代码
```bash
git clone https://github.com/your-username/CodeLintAI.git
cd CodeLintAI
```


#### 2. 配置环境变量
同本地部署，在项目根目录创建 `.env` 文件，填入环境变量配置（见上文）。


#### 3. 构建并启动服务
执行以下命令构建镜像并启动容器（后台运行）：
```bash
docker-compose up -d --build
```
- `--build`：强制重新构建镜像（确保使用最新代码）
- `-d`：后台运行容器


#### 4. 查看服务状态
```bash
# 查看容器状态
docker-compose ps

# 查看实时日志
docker-compose logs -f

# 停止服务
docker-compose down

# 停止并删除数据卷（谨慎操作，会删除持久化数据）
docker-compose down -v
```


#### 5. 验证部署
同本地部署，访问：
- API 文档：http://localhost:8000/docs
- 健康检查：http://localhost:8000/api/code-review/health


### 优势
- 配置集中管理（通过 `.env` 和 `docker-compose.yml`）
- 自动处理数据持久化（向量库、日志目录挂载）
- 一键启停，适合生产环境维护


## 三、Docker 命令部署（轻量生产环境）

### 前置条件
- 安装 Docker（20.10+）


### 部署步骤

#### 1. 克隆项目代码
```bash
git clone https://github.com/your-username/CodeLintAI.git
cd CodeLintAI
```


#### 2. 构建 Docker 镜像
```bash
docker build -t codelintai:latest .
```
- 镜像名称 `codelintai:latest` 可自定义，`latest` 为标签（版本标识）。


#### 3. 启动容器（带数据持久化）
```bash
docker run -d \
  --name codelintai \
  -p 8000:8000 \
  -e OPENAI_API_KEY=3fd1db3b-eaf9-48d5-90cc-xxxxxxxxxxx \
  -e LANGFUSE_PUBLIC_KEY=pk-lf-73b135d1-ac15-4da4-85c0-xxxxxxxxxxxx \
  -e LANGFUSE_SECRET_KEY=sk-lf-60f3b528-5673-4e6d-afef-xxxxxxxxxxxx \
  -e OPENAI_BASE_URL=https://ark.cn-beijing.volces.com/api/v3 \
  -e LANGFUSE_HOST=https://test.langfuse.cyouai.com \
  -e PORT=8000 \
  -v $(pwd)/vector_db:/app/vector_db \
  --restart unless-stopped \
  codelintai:latest
```

#### 参数说明：
- `-d`：后台运行容器
- `--name codelintai`：指定容器名称
- `-p 8000:8000`：端口映射（宿主机端口:容器内端口）
- `-e KEY=VALUE`：设置环境变量（替换为实际值）
- `-v $(pwd)/vector_db:/app/vector_db`：挂载向量库目录（持久化数据）
- `--restart unless-stopped`：容器退出时自动重启（除非手动停止）


#### 4. 容器管理命令
```bash
# 查看容器状态
docker ps | grep codelintai

# 查看日志
docker logs -f codelintai

# 停止容器
docker stop codelintai

# 启动容器
docker start codelintai

# 删除容器（需先停止）
docker rm codelintai

# 删除镜像（需先删除依赖该镜像的容器）
docker rmi codelintai:latest
```


#### 5. 验证部署
同本地部署，访问：
- API 文档：http://localhost:8000/docs
- 健康检查：http://localhost:8000/api/code-review/health


## 总结

| 部署方式       | 适用场景       | 优势                                  | 劣势                                  |
|----------------|----------------|---------------------------------------|---------------------------------------|
| 本地部署       | 开发/测试      | 配置简单，便于调试                    | 依赖本地环境，难以迁移                |
| Docker Compose | 生产环境       | 配置集中，一键启停，适合团队协作      | 需要学习 Docker Compose 语法          |
| Docker 命令    | 轻量生产环境   | 轻量灵活，无需额外配置文件            | 命令冗长，环境变量修改需重建容器      |

推荐优先使用 **Docker Compose 部署**，兼顾易用性和可维护性。


## 📚 API 使用

### 代码规范检查

```bash
curl -X POST "http://localhost:8000/api/code-review/check" \
  -H "Content-Type: application/json" \
  -d '{
    "git_diff": "diff --git a/file.py b/file.py...",
    "use_rag": true,
    "user_id": "user123",
    "session_id": "session456"
  }'
```

### RAG 文档问答

```bash
curl -X POST "http://localhost:8000/api/rag/ask" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "如何使用 FastAPI 创建 API？",
    "collection_name": "default",
    "user_id": "user123",
    "session_id": "session456"
  }'
```

### 知识库管理

```bash
# 创建知识库
curl -X POST "http://localhost:8000/api/kb/create" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "python_standards",
    "description": "Python 代码规范文档"
  }'

# 上传文档
curl -X POST "http://localhost:8000/api/kb/smart-upload" \
  -F "file=@docs/python_standards.md" \
  -F "knowledge_base_name=python_standards"

# 提问
curl -X POST "http://localhost:8000/api/kb/ask" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Python 函数的命名规范是什么？",
    "knowledge_base_name": "python_standards"
  }'
```

## 🔧 配置说明

### 模型配置

```python
# config/config.py
LLM_MODEL_NAME = "doubao-1-5-pro-32k-250115"
EMBEDDING_MODEL_NAME = "text-embedding-3-small"
```

### RAG 配置

```python
# config/thresholds.py
DEFAULT_TOP_K = 5
DEFAULT_RERANK_THRESHOLD = 0.7
DEFAULT_CHUNK_SIZE = 1000
DEFAULT_CHUNK_OVERLAP = 200
```

### Langfuse 配置

```python
# monitoring/langfuse_manager.py
LANGFUSE_ENABLED = True
LANGFUSE_DEBUG = False
```

## 📊 监控和分析

### Langfuse 集成

CodeLintAI 完全集成 Langfuse 2.x 监控系统：

- **调用链路追踪**: 完整的 API 调用链路
- **性能监控**: 响应时间、错误率等指标
- **用户行为分析**: 基于 user_id 和 session_id 的用户行为追踪
- **RAG 检索监控**: 文档检索质量和相关性分析

### 关键指标

- API 响应时间
- 代码检查通过率
- RAG 检索相关性
- 用户满意度

## 🧪 测试

### 运行测试套件

```bash
# 运行完整测试
python test/test_code_review_rag.py

# 运行特定测试
python test/test_suite.py
```

### 测试覆盖

- ✅ 代码规范检查
- ✅ RAG 文档检索
- ✅ Commit Message 生成
- ✅ 知识库管理
- ✅ Langfuse 追踪验证

## 📁 项目结构

```
CodeLintAI/
├── api/                    # API 路由
│   ├── code_review_routes.py
│   ├── knowledge_base_routes.py
│   ├── rag_routes.py
│   └── workflow_routes.py
├── config/                 # 配置管理
│   ├── config.py
│   ├── thresholds.py
│   └── validators.py
├── models/                 # 模型定义
│   ├── base_model.py
│   ├── llm_models.py
│   └── langgraph_workflows.py
├── monitoring/             # 监控系统
│   ├── langfuse_manager.py
│   └── decorators.py
├── rag/                    # RAG 系统
│   ├── knowledge_base_manager.py
│   ├── document_processor.py
│   ├── embedding_manager.py
│   └── rag_system.py
├── test/                   # 测试文件
├── docs/                   # 文档
├── app.py                  # 主应用
├── requirements.txt        # 依赖
├── Dockerfile             # Docker 配置
├── docker-compose.yml     # Docker Compose 配置
└── README.md              # 项目说明
```

## 🔄 工作流

### Commit Message 工作流

```mermaid
graph TD
    A[Git Diff] --> B[关键词提取]
    B --> C[RAG 检索]
    C --> D[代码规范检查]
    D --> E[生成 Commit Message]
    E --> F[返回结果]
```

### RAG 问答工作流

```mermaid
graph TD
    A[用户问题] --> B[文档检索]
    B --> C[相关性重排序]
    C --> D[上下文构建]
    D --> E[答案生成]
    E --> F[返回结果]
```

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- [LangChain](https://www.langchain.com/) - LLM 应用开发框架
- [Langfuse](https://langfuse.com/) - LLM 应用监控平台
- [FastAPI](https://fastapi.tiangolo.com/) - 现代 Web 框架
- [ChromaDB](https://www.trychroma.com/) - 向量数据库

## 📞 联系我们

- 项目主页: https://gitee.com/luo-youlu6/code-lint-ai
- 问题反馈: https://gitee.com/luo-youlu6/code-lint-ai/issues
- 邮箱: 1632373384@qq.com

---

⭐ 如果这个项目对您有帮助，请给我们一个星标！