# PromptCR-Lab

多模型 × 多提示词策略代码审查实验支撑平台。

## 功能

- **数据集管理**：从 Git 仓库筛选 commit、提取 Unidiff、按可插拔规则预埋缺陷、生成 Ground Truth。
- **模型接入**：DeepSeek / Kimi / 通义千问统一 OpenAI 兼容适配器，内置并发控制与指数退避重试。
- **提示词策略**：L1/L2/L3 三级 Jinja2 模板，版本化管理，旧版本只读。
- **实验调度**：3 模型 × N 级 × 12 commit × 3 重复全因子矩阵，asyncio 异步调度，失败重试 + 断点续跑。
- **结果分析**：检出率 / 误报率 / 覆盖率 / 李克特五级量表 / 输出稳定性；统计分析与论文图表。
- **接入层**：FastAPI RESTful API + Typer CLI。
- **Web 前端**：React 18 + Tailwind CSS 3 + shadcn/ui + Vite + ECharts。
- **部署**：`docker compose up` 一键拉起 PostgreSQL + 后端 + 前端（Nginx）。

## 安装

### 本地开发

```bash
# 后端
cd backend
python3 -m pip install -r ../requirements.txt
DATABASE_URL="postgresql+psycopg://postgres:postgres@localhost:5432/promptcr" \
  uvicorn app.api.main:app --reload

# 前端
cd frontend
npm install
npm run dev
```

### Docker

```bash
cp .env.example .env
# 编辑 .env 填入模型 API 密钥
docker compose up --build
```

访问 http://localhost

## 配置

在 `.env` 中配置：

```env
DATABASE_URL=postgresql+psycopg://postgres:postgres@db:5432/promptcr
DEEPSEEK_API_KEY=your_key
KIMI_API_KEY=your_key
QWEN_API_KEY=your_key
```

密钥仅通过环境变量读取，仓库中无硬编码。

## 断点续跑

实验运行中断后，重新调用：

```bash
# CLI
python3 -m app.cli.main run-experiment <experiment_id>

# API
POST /api/experiments/<experiment_id>/run
```

调度器会自动扫描 `pending` / `failed`（未超重试）单元继续执行，已完成的 `run` 不会重复调用。

## 数据库 ER 说明

核心表：

- `samples`：commit 样本（repo, commit_sha, language, diff, 变更前后上下文）
- `defects`：预埋缺陷 Ground Truth（类型、位置行号、参考修复）
- `prompt_templates` / `prompt_template_versions`：提示词模板与版本（旧版本只读）
- `experiments`：实验批次配置快照
- `experiment_runs`：实验单元（唯一 run_id、状态、重试次数、采样参数快照）
- `results`：单元结果（原始输出、token、耗时、解析出的指出项、五维指标、李克特分）

## 测试

```bash
# 后端
cd backend
python3 -m pytest

# 前端
cd frontend
npm run test
```

## 项目结构

```
.
├── backend/          # Python 后端 (FastAPI + SQLAlchemy + asyncio)
│   ├── app/
│   │   ├── api/      # RESTful API
│   │   ├── cli/      # Typer CLI
│   │   ├── dataset/  # Git 解析 / diff 提取 / 缺陷规则
│   │   ├── model_adapters/  # LLM 适配器
│   │   ├── prompts/  # 模板管理
│   │   ├── experiments/     # 矩阵生成 / 异步调度
│   │   └── analysis/        # 指标 / 统计 / 图表
│   └── tests/
├── frontend/         # React SPA
├── docker-compose.yml
├── backend/Dockerfile
├── frontend/Dockerfile
└── requirements.txt
```