codepulse-ai 1.0.0
基于 FastAPI 和 Streamlit 的开源项目健康诊断工具
Requires Python: >=3.10

# CodePulse AI

## 简介

CodePulse AI 是一个 AI 驱动的代码库健康度分析工具，能够全面评估代码质量、社区健康度、文档完整性、维护活跃度和潜在风险。

## 功能特点

- **AI 驱动分析**：利用大型语言模型深入分析代码质量和潜在问题
- **全面评估**：涵盖代码质量、社区健康度、文档完整性、维护活跃度和风险评估
- **多平台支持**：支持 GitHub 和 Gitee 仓库分析
- **外部配置**：支持外部配置文件自定义黑白名单和其他配置项
- **成本估算**：提供 AI 分析成本估算功能
- **多提供商支持**：支持多种 AI 服务提供商

## 安装

```bash
pip install codepulse-ai
```

## 命令行工具 (CLI)

CodePulse AI 提供了强大的命令行工具，方便您快速分析仓库和管理配置。

### 常用命令

1. **分析仓库**
   ```bash
   # 基本用法
   codepulse-ai analyze https://github.com/username/repo

   # 指定 AI 提供商 (支持 deepseek, kimi, doubao, openai, custom)
   codepulse-ai analyze https://github.com/username/repo --provider deepseek

   # 限制分析规模 (适合配置较低的机器)
   codepulse-ai analyze https://github.com/username/repo --max-files 50 --max-file-size 30000

   # 生成 JSON 或 Markdown 报告
   codepulse-ai analyze https://github.com/username/repo --format md --output report.md
   ```

2. **配置管理**
   ```bash
   # 设置 API 密钥 (自动保存到 ~/.codepulse_ai/.env)
   codepulse-ai config set DEEPSEEK_API_KEY your_key_here
   codepulse-ai config set GITHUB_TOKEN your_token_here

   # 设置自定义 AI 模型
   codepulse-ai config set CUSTOM_API_KEY sk-xxx
   codepulse-ai config set CUSTOM_API_BASE https://api.example.com/v1
   codepulse-ai config set CUSTOM_MODEL_NAME my-custom-model
   ```

3. **批量分析**
   ```bash
   codepulse-ai batch repos.txt --format json --output ./reports/
   ```

## 配置指南

### 环境变量与 .env 文件

CodePulse AI 会自动加载以下位置的 `.env` 文件：
1. 当前工作目录下的 `.env`
2. 用户目录下的 `~/.codepulse_ai/.env` (推荐)

您可以使用 CLI 工具方便地设置这些环境变量：
```bash
codepulse-ai config set DEEPSEEK_API_KEY xxx
```

### 自定义文件过滤

您可以通过创建 `~/.codepulse_ai/file_filters.json` 文件来覆盖默认的文件过滤规则。这对于排除特定目录或包含特定文件类型非常有用。

文件格式如下：
```json
{
  "code_extensions": [".py", ".js", ".java"],
  "exclude_dirs": ["node_modules", "venv", "dist"],
  "exclude_files": ["*.log", "package-lock.json"]
}
```

## Python 版本支持

CodePulse AI 完全支持 **Python 3.8+**，包括最新的 **Python 3.10** 和 **3.11**。
如果您在 Python 3.10+ 环境下遇到依赖问题，请确保使用最新版本的 `pip` 安装。

## 高级功能

### 自定义 AI 模型

如果您想使用其他兼容 OpenAI 接口的 AI 模型，可以通过以下配置启用：
```bash
codepulse-ai config set CUSTOM_API_KEY your_key
codepulse-ai config set CUSTOM_API_BASE https://api.your-provider.com/v1
codepulse-ai config set CUSTOM_MODEL_NAME model-name
```
然后在分析时指定 `--provider custom`。

### OAuth2 配置 (预留)

为了支持未来的 Web 端 GitHub/Gitee 登录功能，您现在可以预先配置 OAuth2 凭证：
```bash
codepulse-ai config set GITHUB_CLIENT_ID xxx
codepulse-ai config set GITHUB_CLIENT_SECRET xxx
```

## API 支持

支持 GitHub 和 Gitee 平台的 API 访问，可提供访问令牌以提高 API 限制：

```python
result = await analyzer.analyze_repository(
    "https://github.com/username/repo",
    github_token="your_github_token"
)
```

## 成本估算

使用成本估算功能了解分析所需的大致费用：

```python
from codepulse_ai.services.cost_estimation_service import CostEstimationService

estimator = CostEstimationService()
cost_result = await estimator.estimate_repository_cost("https://github.com/username/repo")
print(f"估算成本: {cost_result['estimated_cost_rmb']}元")
```

## 分析结果

分析结果包含以下维度：

- **代码质量**：复杂度、文档评分、安全问题、代码规范等
- **社区健康度**：贡献者数量、活动频率、问题响应等
- **文档完整性**：README 质量、许可证、贡献指南等
- **维护活跃度**：更新频率、依赖更新、发布频率等
- **风险评估**：安全风险、维护风险、社区风险等

## 许可证

MIT