first commit

2026-09-19 12:54:45 +08:00
commit 6fc5b64077
126 changed files with 8601 additions and 0 deletions
@@ -0,0 +1,112 @@
+# 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
+```