# kb-bug-system

**Repository Path**: panzuji/kb-bug-system

## Basic Information

- **Project Name**: kb-bug-system
- **Description**: kb bug 分析系统，基于 hermes 来执行日志分析
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-24
- **Last Updated**: 2026-05-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# KB Bug Analysis System

自动化 KB 项目 Bug 分析工单管理系统。用户在线提交 bug 分析工单，上传日志文件（.zip），系统自动调用 Hermes + kb-bug-analyzer 技能进行分析，分析结果通过聊天界面实时流式返回。

## 架构

```
前端 (React + Vite)  →  Nginx (反向代理)  →  后端 (FastAPI)
                                                    │
                                                    ├─→ Claude Code (kb-bug-analyzer)
                                                    ├─→ SQLite (数据库)
                                                    └─→ 本地文件系统 (日志存储)
```

## 快速开始

### 1. 环境准备

```bash
# 克隆或进入项目
cd /root/kb-bug-system

# 安装 Python 依赖
cd backend
pip install -r requirements.txt
cd ..

# 安装前端依赖
cd frontend
npm install
cd ..
```

### 2. 配置

```bash
# 创建环境变量文件
cp .env.example .env
# 编辑 .env 设置 KB_ADMIN_ROOT 等路径
```

### 3. 启动

#### 方式 A: Docker Compose（推荐）
```bash
docker-compose up --build
```

#### 方式 B: 开发模式
```bash
# Terminal 1: 后端
cd backend
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Terminal 2: 前端
cd frontend
npm run dev
```

### 4. 访问

- 前端: http://localhost:3000
- 后端 API: http://localhost:8000/api
- API 文档: http://localhost:8000/docs

nginx 访问地址：http://192.168.30.63:9999/

## 功能

### 工单管理
- 创建 bug 分析工单
- 工单状态跟踪（待创建 → 等待日志 → 分析中 → 已完成/失败）
- 工单列表分页浏览和状态筛选

### 文件上传
- 支持拖拽上传 .zip 日志文件
- 多文件同时上传
- 大文件流式处理（不占用内存）
- 文件大小限制 10GB/个

### 自动化分析
- 点击"开始分析"触发 kb-bug-analyzer 分析流程
- 自动解压 .zip 日志文件
- 调用 Claude Code 执行完整的 bug 分析工作流
- 支持多工单并行分析（可配置并发数）

### 实时聊天
- 分析结果通过 SSE 流式返回
- 用户可通过聊天窗口追加指令
- 支持多轮对话和追问
- 分析日志实时查看

## API 文档

启动后端后访问 `/docs` 查看完整的 Swagger API 文档。

主要端点：
- `POST /api/tickets` — 创建工单
- `GET /api/tickets` — 工单列表
- `POST /api/tickets/{id}/files` — 上传日志文件
- `POST /api/tickets/{id}/analyze` — 触发分析
- `GET /api/tickets/{id}/stream` — SSE 分析流
- `POST /api/tickets/{id}/messages` — 发送聊天消息
- `GET /api/tickets/{id}/messages` — 获取消息历史

## 配置项

| 变量 | 说明 | 默认值 |
|------|------|--------|
| KB_ADMIN_ROOT | KB-admin 仓库路径 | /root/KB-admin |
| KB_ALG_ROOT | 算法模块路径 | - |
| KB_AGV_ROOT | AGV 插件路径 | - |
| KB_AGV_DEVICE | 设备插件路径 | - |
| ANALYSIS_WORKERS | 最大并发分析数 | 2 |
| MAX_FILE_SIZE | 单文件最大大小 | 10GB |
| UPLOAD_DIR | 文件上传目录 | /var/lib/bugsystem/uploads |

## 项目结构

```
kb-bug-system/
├── backend/              # FastAPI 后端
│   ├── main.py           # 入口
│   ├── config.py         # 配置
│   ├── database.py       # 数据库
│   ├── models.py         # ORM 模型
│   ├── schemas.py        # Pydantic schemas
│   ├── api/              # API 路由
│   │   ├── tickets.py    # 工单 CRUD
│   │   ├── uploads.py    # 文件上传
│   │   ├── analysis.py   # 分析触发
│   │   └── chat.py       # 聊天 + SSE
│   └── workers/          # 后台工作进程
│       ├── analyzer.py   # 分析引擎
│       └── task_queue.py # 任务队列
├── frontend/             # React 前端
│   ├── src/
│   │   ├── App.tsx       # 主组件
│   │   ├── types/        # TypeScript 类型
│   │   └── utils/        # API 客户端
│   └── package.json
├── docker-compose.yml    # Docker 编排
├── Dockerfile            # 后端镜像
├── frontend/Dockerfile   # 前端镜像
├── nginx.conf            # Nginx 配置
└── README.md
```

Configuration
Environment variables
Variable	Default	Description
CLAUDE_CODE_BIN	claude	Path to Claude Code CLI binary
CLAUDE.md integration
Add to your project's CLAUDE.md to guide Hermes on when to delegate:

## Claude Code Delegation

When implementing features or fixing bugs, delegate self-contained sub-tasks
to Claude Code using the `claude_code_delegate` tool.

### When to delegate
- Writing new functions, modules, or files with clear requirements
- Bug fixes with clear scope
- Refactoring specific files
- Running tests and fixing failures

### When NOT to delegate
- Tasks requiring back-and-forth with the user
- Architecture decisions
- Tasks that depend on conversation context Hermes hasn't passed