# BUGreview

**Repository Path**: westwest233/bugreview

## Basic Information

- **Project Name**: BUGreview
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Bug Review AI — 研发知识沉淀平台

![Python](https://img.shields.io/badge/Python-3.12+-3776AB?logo=python&logoColor=white)
![FastAPI](https://img.shields.io/badge/FastAPI-Backend-009688?logo=fastapi&logoColor=white)
![Vue](https://img.shields.io/badge/Vue-3-42b883?logo=vue.js&logoColor=white)
![Vite](https://img.shields.io/badge/Vite-Frontend-646CFF?logo=vite&logoColor=white)
![Element Plus](https://img.shields.io/badge/Element_Plus-UI-409EFF?logo=element&logoColor=white)
![Pinia](https://img.shields.io/badge/Pinia-State-42b883?logo=pinia&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green)

面向研发团队的**智能化 Bug Review 平台**。围绕 GitHub PR 与线上故障修复场景，打通**代码变更接入 → LLM 根因分析 → 审核发布 → 知识库沉淀**全流程，把团队踩过的坑结构化地沉淀为可检索的知识，实现研发经验的结构化复用与问题定位效率的提升。

一句话：**当有人修好一个 Bug，平台自动帮团队记住「为什么错、怎么修、下次怎么防」，并让所有人能搜到。**

---

## 核心流程

```
GitHub PR/Webhook          LLM 结构化抽取          人工审核             知识库沉淀
     │                         │                    │                    │
┌────▼────┐  触发      ┌───────▼──────┐   draft  ┌──▼──┐  approved  ┌──▼──────┐
│ PR #42  │──────────▶│ Bug Review    │─────────▶│ 审核  │──────────▶│ 知识条目  │
│ fix(xxx)│ commit SHA│ Document      │  pending │      │ published │· 可检索  │
└─────────┘           │· 根因         │         └──────┘           │· 关联PR  │
                      │· 修复方案     │◄──────── rejected ────────│· 关键词  │
                      │· 预防措施     │                            └─────────┘
                      └──────────────┘
```

LLM 抽取出的复盘文档会经过四态审核生命周期，只有「通过并发布」的才进入知识库：

| 状态 | 含义 | 示例 |
|------|------|------|
| `draft` | 刚生成，尚未提交 | fix(style): CSS 样式回归 |
| `pending` | 已提交，待人工审核 | fix(editor): 运行按钮空参数 |
| `approved` | 审核通过，可发布 | fix(applist): 重复创建示例应用 |
| `rejected` | 被驳回（可改后重提） | 根因分析不足被退回 |
| `published` | 已发布到知识库（终态） | fix(rag): 上传文件报500 |

## 架构：六层管道

```
┌──────────────┐     ┌─────────────────────────────────────────────┐
│  GitHub PR   │────▶│          六层管道架构                        │
│  Webhook     │     │                                             │
│  Manual      │     │  ① 事件采集 ──▶ ② 任务编排 ──▶ ③ LLM 抽取    │
└──────────────┘     │       │              │              │        │
                     │  ④ RAG 增强 ◀── ⑤ 审核发布 ──▶ ⑥ 知识检索    │
                     │       │              │              │        │
                     │  BM25+向量    审核状态机    语义搜索+关键词    │
                     │  混合召回    (状态转移矩阵)    混合召回        │
                     └─────────────────────────────────────────────┘
```

**六大模块总览：**

| # | 模块 | 核心文件 | 职责 |
|---|------|----------|------|
| ① | 事件采集 | `pr_listener.py` | 接收 GitHub/GitLab Webhook，HMAC-SHA256 验签，解析为标准 `BugReport` |
| ② | 任务编排 | `scheduler.py`、`idempotency.py` | 编排处理步骤、SQLite 幂等键防重放、复杂度决策 |
| ③ | LLM 抽取 | `llm_executor.py`、`map_reduce_summary.py`、`log_compressor.py`、`bug_schema.py` | 抽根因/修复/预防，JSON Schema 防幻觉，指数退避，长文本 Map-Reduce |
| ④ | RAG 增强 | `retrieval.py`、`bm25_index.py`、`embeddings.py`、`reranker.py` | BM25 + 向量混合召回 + 精排 + MMR 去重 |
| ⑤ | 审核发布 | `review_workflow.py`、`wiki_publisher.py` | 状态机审核流转，审核通过后发布为 Markdown 知识条目 |
| ⑥ | 知识检索 | `knowledge_base.py`、`retrieval.py` | 语义 + 关键词混合检索历史踩坑经验 |

**技术栈：**

| 层 | 技术 |
|----|------|
| 后端框架 | FastAPI + Uvicorn |
| 前端框架 | Vue 3 + Vite + Pinia + TypeScript |
| UI 组件库 | Element Plus |
| 可视化 | ECharts |
| 数据存储 | JSON 文件 + SQLite（幂等键 / BM25 倒排索引） |
| LLM 集成 | OpenAI 兼容 API（支持 DeepSeek / 百炼 / Ollama 等） |
| 检索 | BM25 关键词索引 + 向量语义搜索 + Reranker |
| 发布（阶段一） | 本地 Markdown 输出 |

## 快速开始

### 1. 启动后端（Demo 模式）

无需配置 LLM Key，直接启动即可体验完整流程：

```bash
cd backend
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .
python start_demo.py
```

后端地址：`http://localhost:8000`

Demo 模式会预置 `example-org/bug-review-demo` 的 **4 条 Bug 报告、5 条知识条目和完整审核历史**，覆盖四种审核状态，开箱即用。

> 如需真实 LLM 抽取，把 `.env`（参考 `.env.example`）中的 `LLM_PROVIDER`、`LLM_API_KEY`、`LLM_MODEL`、`LLM_BASE_URL` 配置好即可。

### 2. 启动前端

```bash
cd frontend
npm install
npm run dev
```

前端地址：`http://localhost:5173`

### 3. 试用完整链路

1. 打开**工作台** → 看到新手引导卡和 4 条 Demo Bug 报告；
2. 进入 **Bug 复盘** → 左侧选一条报告，右侧查看 **LLM 抽取结果**（根因 / 修复方案 / 预防措施 / 来源引用）；
3. 修改抽取字段 → 点击 **通过审核** 或 **驳回**（驳回须填理由）；
4. 审核通过后点击 **发布到知识库**；
5. 进入 **踩坑知识库**，搜索关键词（如 `upload`、`500`、`embedding`）验证混合召回效果；
6. 在 **抽取管道 / 管道监控** 查看任务流转与各层指标；点 **重置示例** 可恢复初始数据。

## Web 控制台

| 页面 | 路径 | 功能 |
|------|------|------|
| 工作台 | `/dashboard` | 管道总览：沉淀时效、审核进度、知识库增长、Token 消耗 |
| Bug 复盘 | `/ci-autofix` | 核心工作台：LLM 抽取结果查看/编辑 + 审核操作 |
| 踩坑知识库 | `/skill-library` | 语义搜索 + BM25 关键词混合召回 |
| 抽取管道 | `/task-scheduling` | 六层管道任务流转可视化 + Agent 协作拓扑 |
| 数据源管理 | `/repo-management` | GitHub 仓库接入 + Webhook 配置 |
| 上下文 | `/context-management` | 代码上下文索引与依赖图 |
| 管道监控 | `/observability` | 各层延迟、成功率、降级触发率、阈值告警 |

## Demo 数据

预置的演示数据基于示例仓库 `example-org/bug-review-demo`，覆盖一个典型 RAG 知识库项目的四类 Bug：

| Bug 报告 | PR | Commit SHA | 审核状态 |
|----------|----|-----------|----------|
| `bug-demo-001` | fix(rag): 上传文件报500 | `6ae78ab` | published |
| `bug-demo-002` | fix(editor): 运行按钮空参数 | `b30d696` | approved |
| `bug-demo-003` | fix(style): CSS 样式回归 | `70fafa3` | draft |
| `bug-demo-004` | fix(applist): 重复创建示例应用 | `08c2141` | rejected |

## 目录结构

```
.
├── backend/
│   ├── src/bug_review_platform/
│   │   ├── api.py               # FastAPI 路由
│   │   ├── models.py            # BugReport / KnowledgeEntry 数据模型
│   │   ├── bug_schema.py        # LLM 抽取结果 Schema + 防幻觉 SourceRef
│   │   ├── pr_listener.py       # GitHub/GitLab Webhook 解析 + HMAC 验签
│   │   ├── idempotency.py       # 幂等键 SQLite 存储（防重放）
│   │   ├── scheduler.py         # 任务编排 / 复杂度决策
│   │   ├── map_reduce_summary.py# 长上下文 Map-Reduce 压缩
│   │   ├── log_compressor.py    # 日志智能裁剪
│   │   ├── llm_executor.py      # LLM 抽取 + 指数退避重试
│   │   ├── bm25_index.py        # BM25 关键词倒排索引
│   │   ├── retrieval.py         # BM25 + 向量混合召回
│   │   ├── review_workflow.py   # 审核状态机（状态转移矩阵）
│   │   ├── wiki_publisher.py    # Markdown 知识发布
│   │   ├── knowledge_base.py    # 知识库沉淀 / 检索
│   │   ├── observability.py     # 指标采集与监控
│   │   └── frontend_service.py  # 前端数据服务
│   ├── tests/                   # 测试
│   ├── start_demo.py            # Demo 数据注入 + 启动
│   ├── main.py / app.py         # 入口
│   └── pyproject.toml
├── frontend/
│   ├── src/
│   │   ├── views/               # 页面组件（Dashboard/Bug复盘/知识库/管道/监控…）
│   │   ├── components/          # 通用组件 + 布局（ConsoleLayout 等）
│   │   ├── api/platform.ts      # API 调用层
│   │   ├── types/platform.ts    # TS 类型定义（BugReport 等）
│   │   ├── stores/app.ts        # Pinia 全局状态
│   │   └── styles/global.css    # 设计系统
│   └── index.html
└── README.md
```

## 配置说明

核心环境变量（`backend/.env`，参考 `.env.example`）：

| 变量 | 说明 | Demo 模式 |
|------|------|-----------|
| `LLM_PROVIDER` | LLM 供应商（openai/alibaba/bytedance/kimi/google/custom） | 不需要 |
| `LLM_API_KEY` | LLM API Key | 不需要 |
| `LLM_MODEL` | 模型名称 | 不需要 |
| `LLM_BASE_URL` | API 地址 | 不需要 |
| `EMBEDDING_API_KEY` | Embedding API Key | 不需要 |
| `API_HOST` | 后端监听地址 | `0.0.0.0` |
| `API_PORT` | 后端监听端口 | `8000` |

> Demo 模式无需任何配置，数据预注入，可直接体验完整流程。未配置 LLM / Embedding 时，系统会自动降级使用本地启发式规则与哈希向量，保证流程可运行。

## 常用命令

```bash
# 后端：启动 Demo 服务
cd backend && python start_demo.py

# 后端：运行测试
cd backend && pytest

# 前端：开发模式
cd frontend && npm run dev

# 前端：生产构建
cd frontend && npm run build
```

## 许可

MIT License