# sakura-ai

**Repository Path**: BruceQiang/sakura-ai

## Basic Information

- **Project Name**: sakura-ai
- **Description**: 🔥Sakura AI🔥是一个基于TestFlow改造过后的新一代AI自动化平台，主要用于从产品原型一键生成需求文档 + 测试场景 + 测试点 + 测试用例 + UI 自动化测试（用自然语言执行 UI 自动化）
- **Primary Language**: TypeScript
- **License**: GPL-3.0
- **Default Branch**: dev
- **Homepage**: https://sakura.hk.cn
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 52
- **Created**: 2026-01-27
- **Last Updated**: 2026-01-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Sakura AI

<div align="center">

**AI 驱动的全栈测试自动化平台：从 Axure 原型生成测试用例，到自然语言执行 UI 自动化** 🚀

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/SakuraTechy/sakura-ai)
[![License](https://img.shields.io/badge/license-GNU%20GPL-green.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D20.19.0-brightgreen.svg)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.5.3-blue.svg)](https://www.typescriptlang.org/)
[![React](https://img.shields.io/badge/React-18.3.1-blue.svg)](https://reactjs.org/)

[快速开始](#-快速开始)  [核心功能](#-核心功能)  [技术栈](#-技术栈)  [文档](docs/)  [问题反馈](https://github.com/SakuraTechy/sakura-ai/issues)

</div>

---

## 💡 为什么选择 Sakura AI？

### 传统测试的三大痛点

** 编写用例阶段**：
- ⏱️ 耗时 2-3 天手工编写测试用例
- 📉 覆盖率仅 60-70%，边界值和风险场景容易遗漏
- 🔁 重复劳动多，专业度依赖个人经验

** 执行用例阶段**：
- 💻 需要编写 Selenium/Playwright 代码
- 🎬 录制回放工具 UI 变化即失效
- 🔧 维护成本高，技术门槛大

** 管理与协作**：
- 📊 测试进度难以实时跟踪
- 🤝 团队协作缺乏统一平台
- 📈 测试质量难以量化评估

### Sakura AI 的完整解决方案

** AI 生成测试用例**：
- ⚡ **10 分钟完成**（从 Axure 原型一键生成）
- 🎯 **覆盖率 85-95%**（AI + RAG 知识库增强）
- 🧠 **自动补充边界值和风险场景**（+40% 专业度）
- 🎨 **智能 UI 文案校验**（页面布局与文案自动验证）

** 自然语言执行自动化**：
- 🗣️ **无需编写代码**（用中文描述即可执行）
- 🤖 **AI 智能元素定位**（UI 变化自动适配）
- 📊 **实时进度监控**（WebSocket 推送 + 自动截图）
- 🎯 **多浏览器支持**（Chrome、Firefox、Safari）

** 全栈测试管理平台**：
- 📁 **多项目版本管理**（支持项目分支和版本控制）
- 🔄 **AI 批量更新**（智能修改相关测试用例）
- 📚 **RAG 知识库**（团队经验持续积累）
- 📈 **多维度统计**（测试覆盖率、执行趋势、质量指标）

---

## 🚀 核心功能

### 1️⃣ 🤖 AI 测试用例生成器

#### 从 Axure 原型到专业测试用例，效率提升 20-50 倍

**工作流程：4 步审核 + 3 阶段生成**

```
📤 上传 Axure HTML 文件
    AI 深度解析页面结构
🤖 生成需求文档（Markdown）+ UI 文案校验章节
   
✋ 人工审核修正需求文档（第 1 个审核点）
   
🔄 阶段 1：AI 智能拆分测试模块（3-6 个功能模块）
   
✋ 选择要生成的模块（第 2 个审核点）
   
🎯 阶段 2：AI 生成测试目的（每个模块 2-8 个测试场景）
   
✋ 选择要生成的测试目的（第 3 个审核点）
   
✅ 阶段 3：AI 生成测试点 + RAG 知识库增强（每个目的 3-10 个测试点）
   
✋ 审核/编辑/保存（第 4 个审核点）
   
💾 一键保存到用例库
```

**核心特性**：
- 🎯 **智能页面解析**：深度分析 Axure 原型结构和交互逻辑
- 🎨 **UI 文案校验**：自动生成页面布局与文案验证测试点
- 🧠 **RAG 知识增强**：融入团队历史经验和最佳实践
- 📊 **多维度覆盖**：功能测试 + 边界值 + 异常场景 + 风险测试

**量化效果**：

| 指标 | 传统手工 | Sakura AI AI | 提升 |
|------|---------|------------|------|
| **编写时间** | 2-3 天 | **10-30 分钟** | **20-50x** ⚡ |
| **功能覆盖率** | 60-70% | **85-95%** | **+25-35%** |
| **UI 文案校验** | 0% | **80-95%** | **+80-95%** 🎨 |
| **边界值覆盖** | 40-60% | **80-95%** | **+40-55%** 🔍 |
| **风险场景识别** | 50-70% | **85-95%** | **+35-45%** 🛡️ |

---

### 2️⃣ 🗣️ 自然语言执行引擎

#### 无需编写代码，用中文描述即可执行浏览器自动化

**对比传统自动化方式**：

**❌ 传统 Selenium/Playwright 代码**：
```python
from selenium import webdriver
from selenium.webdriver.common.by import By

driver = webdriver.Chrome()
driver.get("https://example.com/login")
username = driver.find_element(By.XPATH, "//input[@id=
username]")
username.send_keys("admin@test.com")
# ... 数十行复杂代码
```

**✅ Sakura AI 自然语言执行**：
```
1. 打开登录页面 https://example.com/login
2. 在用户名输入框填入 admin@test.com
3. 在密码输入框填入 password123
4. 点击登录按钮
5. 验证页面显示"欢迎回来"
```

**技术架构**：
```
自然语言描述
    AI 语义理解
🤖 生成 MCP 命令序列
    智能元素定位
🎯 Playwright 执行自动化
    实时监控反馈
📊 WebSocket 推送进度 + 自动截图
```

**核心优势**：

| 维度 | Selenium/Playwright | 录制回放工具 | **Sakura AI** |
|------|---------------------|-------------|-------------|
| **编写方式** | 编写代码 | 录制操作 | **自然语言描述** ✍️ |
| **技术门槛** | 需要编程基础 | 无需编程 | **无需编程** 👍 |
| **维护成本** | 中等（需修改选择器） | 极高（UI 变化即失效） | **极低（AI 智能适配）** 💰 |
| **灵活性** | 高 | 低（无法修改录制脚本） | **极高** 🔧 |
| **元素定位** | 手动写选择器 | 固定坐标/选择器 | **AI 智能匹配** 🤖 |
| **执行监控** | 需额外开发 | 无 | **实时进度 + 截图** 📊 |

---

### 3️⃣ 🧠 RAG 智能知识库

#### 让 AI 记住团队的测试经验，避免重复踩坑

**四大知识维度**：

| 维度 | 说明 | 示例场景 |
|------|------|---------|
| 📘 **业务规则** | 业务逻辑验证规则 | "订单金额必须 > 0，小数点后最多2位" |
| 📗 **测试模式** | 成熟的测试设计模式 | "组合查询边界值测试模板" |
| 📙 **历史踩坑** | 团队遇到的易错点 | "库存扣减未考虑并发导致超卖" |
| 📕 **风险场景** | 高风险安全测试点 | "支付回调重复通知导致重复扣款" |

**工作原理**：
```
用户输入："生成用户注册的测试用例"
   
🔍 向量化查询（阿里通义 Embedding 1024 维）
   
📚 Qdrant 语义检索（相似度阈值  0.5）
   📘 业务规则："密码强度要求8位以上"
   📗 测试模式："表单验证边界值测试"
   📙 历史踩坑："手机号格式验证遗漏"
   📕 风险场景："短信验证码防刷机制"
   
🎯 注入 AI Prompt 增强上下文
   
📝 输出专业测试用例
   ✅ 密码强度边界值测试（7位、8位、特殊字符）
   ✅ 手机号格式验证测试（+86、空格、字母混入）
   ✅ 短信验证码防刷测试（同一手机号频繁请求）
```

**核心价值**：

| 指标 | 无 RAG | 有 RAG | 提升 |
|------|--------|--------|------|
| **边界值覆盖率** | 40-60% | **80-95%** | **+40-55%** |
| **风险场景识别** | 50-70% | **85-95%** | **+35-45%** |
| **专业准确性** | 75-85% | **90-98%** | **+15-20%** |
| **团队经验传承** | 0% | **100%** | **质的飞跃** |

---

### 4️⃣ 📊 全栈测试管理平台

#### 完整的测试生命周期管理解决方案

**🏗️ 多项目版本管理系统**
- 📁 **项目管理**：支持多项目/系统并行管理
- 🏷️ **版本控制**：每个项目支持多版本分支
- 👥 **权限控制**：基于角色的访问控制

**🔄 AI 批量更新引擎**
- 🎯 **智能识别**：自动识别变更影响范围
- 📝 **批量提案**：生成批量修改建议
- ✅ **人工审核**：支持逐个审核和批量应用

**📈 多维度统计分析**
- 📊 **执行统计**：通过率、执行时长、失败趋势
- 🎯 **覆盖分析**：测试覆盖率、模块分布
- 📈 **质量指标**：缺陷密度、修复效率

**🎨 现代化用户界面**
- 💳 **多视图展示**：卡片视图、表格视图、看板视图、时间线视图
- 🔍 **智能筛选**：多条件组合筛选和搜索
- 📱 **响应式设计**：支持桌面端和移动端访问

---

## ��️ 技术栈

### 前端技术栈

| 层级 | 技术 | 版本 | 说明 |
|------|------|------|------|
| **框架** | React | 18.3.1 | 现代化前端框架，支持并发特性 |
| **语言** | TypeScript | 5.5.3 | 类型安全的 JavaScript 超集 |
| **样式** | Tailwind CSS | 3.4.1 | 原子化 CSS 框架 |
| **组件库** | Ant Design | 5.26.7 | 企业级 React 组件库 |
| **状态管理** | Zustand | 4.4.7 | 轻量级状态管理库 |
| **路由** | React Router | 6.20.1 | 声明式路由管理 |
| **动画** | Framer Motion | 10.16.16 | 流畅动画效果 |
| **图表** | Recharts | 2.9.3 | React 图表库 |

### 后端技术栈

| 层级 | 技术 | 版本 | 说明 |
|------|------|------|------|
| **运行时** | Node.js | 18.0.0 | JavaScript 运行环境 |
| **框架** | Express | 4.18.0 | 轻量级 Web 框架 |
| **语言** | TypeScript | 5.5.3 | 服务端类型安全 |
| **ORM** | Prisma | 6.11.1 | 现代化数据库 ORM |
| **数据库** | MySQL | 8.0 | 关系型数据库 |
| **缓存** | Redis | - | 会话和缓存存储 |
| **队列** | Bull | 4.16.5 | Redis 基础的任务队列 |

### AI 与自动化技术栈

| 层级 | 技术 | 版本 | 说明 |
|------|------|------|------|
| **AI 服务** | OpenRouter | - | 多模型 AI 服务 (GPT-4o/Claude/Gemini) |
| **向量数据库** | Qdrant | - | 高性能向量搜索引擎 |
| **Embedding** | 阿里通义 | 1024 维 | 中文语义向量生成 |
| **浏览器自动化** | Playwright | 1.56.1 | 跨浏览器自动化测试 |
| **协议** | MCP | 1.0.0 | Model Context Protocol |

### 开发与部署工具

| 工具类型 | 技术 | 版本 | 说明 |
|------|------|------|------|
| **构建工具** | Vite | 5.4.2 | 快速前端构建工具 |
| **测试框架** | Jest | 30.0.5 | JavaScript 测试框架 |
| **代码检查** | ESLint | 9.9.1 | 代码质量检查 |
| **容器化** | Docker | 26.1.3 | 应用容器化部署 |
| **CI/CD** | Jenkins | 2.452.1 | 持续集成部署 |

---

## 🚀 快速开始

### 一键启动（推荐）

```bash
# 1. 克隆项目
git clone https://github.com/SakuraTechy/sakura-ai.git
cd sakura-ai

# 2. 环境要求
node >= 20.19.0
npm >= 10.8.2

# 3. 切换到淘宝 NPM 镜像
npm config set registry https://registry.npmmirror.com

# 4. 安装依赖
npm install

# 5. 复制.env文件，修改数据库配置连接
copy .env.example .env
>>> DATABASE_URL=mysql://root:7PhaaEL3REbCabRb@172.19.5.111:3306/sakura_ai

# 6. 启动项目（自动安装依赖、配置环境、启动服务）
npm run start
```

### 访问系统

```
前端界面: http://localhost:5173
默认账号: admin / admin
```

### 可选：启用 AI 增强功能

```bash
# 1. 启动 Qdrant 向量数据库
docker run -d -p 6333:6333 qdrant/qdrant

# 2. 配置环境变量 (.env 文件)
QDRANT_URL=http://localhost:6333
EMBEDDING_PROVIDER=aliyun
EMBEDDING_API_KEY=your_aliyun_api_key

# 3. 重启服务
npm run dev
```

详细安装指南：[INSTALLATION.md](docs/INSTALLATION.md)

---

## 🎮 使用指南

### 1. AI 生成测试用例

```
功能测试用例  AI 生成器  上传 Axure HTML  生成需求文档
 审核修正  生成测试模块  选择模块  生成测试目的
 选择目的  生成测试点（RAG 增强） 保存
```

### 2. 执行测试用例

```
测试用例管理  选择用例  点击执行  实时监控  查看结果和截图
```

### 3. AI 批量修改

```
测试用例管理  AI 批量更新  描述变更需求  审核提案  应用修改
```

---

## 📁 项目结构

```
Sakura AI/
 src/                          # 前端源码
    components/               # React 组件
       ai-generator/         # AI 生成器组件
       common/               # 通用组件
       ui/                   # UI 组件
    pages/                    # 页面组件
       FunctionalTestCases/  # 功能测试用例页面
       KnowledgeManagement/  # 知识库管理
       SystemManagement/     # 系统管理
    services/                 # API 服务客户端
    types/                    # TypeScript 类型定义
    utils/                    # 工具函数
 server/                       # 后端源码
    routes/                   # API 路由
    services/                 # 核心业务服务
       aiParser.ts           # AI 解析器
       functionalTestCaseAIService.ts # AI 生成服务
       aiBulkUpdateService.ts # AI 批量更新
       testExecution.ts      # 测试执行服务
       knowledgeManagementService.ts # 知识库服务
    middleware/               # 中间件
    prompts/                  # AI Prompt 模板
    types/                    # 服务端类型定义
    utils/                    # 服务端工具函数
 prisma/                       # 数据库模式
    schema.prisma             # Prisma 数据库模式
 docs/                         # 项目文档
 scripts/                      # 构建和部署脚本
 tests/                        # 测试文件
```

---

## 📚 文档

- [安装指南](docs/INSTALLATION.md) - 详细安装步骤和系统要求
- [AI 生成器详解](docs/AI_GENERATOR.md) - 从 Axure 到测试用例的完整流程
- [RAG 知识库配置](docs/RAG_SETUP.md) - 向量数据库配置和知识管理
- [自然语言执行原理](docs/EXECUTION.md) - 技术实现详解和最佳实践
- [技术架构](docs/ARCHITECTURE.md) - 系统架构和核心服务
- [配置说明](docs/CONFIGURATION.md) - 环境变量配置详解
- [故障排除](docs/TROUBLESHOOTING.md) - 常见问题和解决方案

---

## 🐛 常见问题

### 数据库连接失败

```bash
# 确保 MySQL 服务运行
sudo systemctl start mysql

# 运行数据库迁移
npx prisma migrate deploy
npx prisma generate
```

### Playwright 浏览器缺失

```bash
# 安装浏览器
npx playwright install chromium
```

### RAG 知识库连接失败

```bash
# 检查 Qdrant 服务状态
curl http://localhost:6333/health

# 重启 Qdrant 容器
docker restart <qdrant_container_id>
```

更多问题：[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)

---

## 🤝 贡献 & 支持

欢迎 Star ⭐ / Fork 🍴 / PR 🔧

- [提交 Bug](https://github.com/SakuraTechy/sakura-ai/issues)
- [功能建议](https://github.com/SakuraTechy/sakura-ai/issues)
- [贡献指南](CONTRIBUTING.md)

---

## 📄 开源许可

GNU General Public License v3.0 © Sakura AI Team

查看完整许可：[LICENSE](LICENSE)

---

## 🌟 致谢

感谢以下项目和团队：

- [Anthropic](https://www.anthropic.com) - MCP 协议
- [Playwright](https://playwright.dev) - 浏览器自动化
- [Qdrant](https://qdrant.tech) - 向量数据库
- [React](https://reactjs.org) - 前端框架
- [阿里云通义千问](https://dashscope.aliyuncs.com) - Embedding API
- [OpenRouter](https://openrouter.ai) - 多模型 AI 服务

---

<div align="center">

**Sakura AI - 让自动化测试变得简单而强大！** 🚀

Made with ❤️ by Sakura AI Team

[⬆ 返回顶部](#Sakura AI)

</div>