# entropy-check

**Repository Path**: jeanlv/entropy-check

## Basic Information

- **Project Name**: entropy-check
- **Description**: AI智能体驱动测试开发平台
“验” 涵盖测试中的验证、校验场景；“熵” 源自信息论与热力学，象征系统的无序度（软件缺陷本质是系统 “无序” 的体现），测试智能体的核心价值是降低 “熵值”（减少缺陷）；“核” 凸显平台作为智能测试核心引擎的定位，结合 langgraph 的智能体协同逻辑，暗合 “从无序中找规律” 的技术内核。名称融入理科概念，科技感独特。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-12-21
- **Last Updated**: 2026-02-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 验熵核 (Entropy Check) - AI 驱动的自动化测试平台

<p align="center">
  <strong>🚀 基于 LangGraph 的智能测试用例生成 | 🔗 混合动力依赖分析 | ⚡ 高性能异步执行引擎</strong>
</p>

---

## 项目简介

验熵核是一个现代化的 **AI 驱动自动化测试平台**，核心亮点在于利用 **大语言模型 (LLM)** 技术辅助接口测试。系统采用前后端分离架构，提供了完整的 RBAC 权限管理和丰富的功能模块。

### 核心能力

| 能力 | 描述 |
|------|------|
| 🤖 **AI 用例生成** | 基于 LangGraph 的多节点工作流，自动生成多维度测试用例（正向/反向/边界/异常） |
| 🔄 **自愈修复** | 预执行失败时自动分析错误并修正脚本，保证生成代码的可执行性 |
| 🧠 **记忆复用** | MongoDB 存储历史生成结果，支持断点续存和智能复用 |
| 🔗 **依赖分析** | 混合规则引擎 + LLM 推理，自动识别接口间数据流依赖 |
| ⚡ **执行引擎** | 自研高性能引擎，支持三级变量作用域、脚本沙箱、配置式断言 |
| 📡 **AG-UI 协议** | 基于 SSE 的实时状态推送，前端可观察 AI 执行全过程 |

---

## 技术栈

### 后端 (Backend)

| 类别 | 技术 | 说明 |
|------|------|------|
| **Web 框架** | [FastAPI](https://fastapi.tiangolo.com/) | 高性能异步 Python Web 框架 |
| **ORM** | [Tortoise-ORM](https://tortoise.github.io/) | 异步 ORM，支持 MySQL |
| **AI 框架** | [LangChain](https://www.langchain.com/) + [LangGraph](https://www.langchain.com/langgraph) | 构建智能体工作流 |
| **对象存储** | [MinIO](https://min.io/) | 文件存储服务 |
| **数据库** | MySQL + MongoDB | 业务数据 + AI 记忆存储 |
| **脚本沙箱** | [RestrictedPython](https://restrictedpython.readthedocs.io/) | 安全执行用户脚本 |
| **依赖管理** | uv / pip | 基于 `pyproject.toml` |

### 前端 (Frontend)

| 类别 | 技术 | 说明 |
|------|------|------|
| **框架** | [Next.js 16](https://nextjs.org/) (App Router) | React 19 全栈框架 |
| **组件库** | [Ant Design 5](https://ant.design/) | 企业级 UI 组件 |
| **样式** | [Tailwind CSS 4](https://tailwindcss.com/) | 原子化 CSS |
| **状态管理** | [Zustand 5](https://github.com/pmndrs/zustand) | 轻量级状态管理 |
| **编辑器** | [Monaco Editor](https://microsoft.github.io/monaco-editor/) | VS Code 同款编辑器 |
| **图表** | [ECharts 6](https://echarts.apache.org/) | 数据可视化 |

---

## 目录结构

```text
entropy-check/
├── backend/                    # 后端源码
│   ├── main.py                 # 应用入口
│   ├── pyproject.toml          # Python 依赖配置
│   ├── .env                    # 环境变量
│   ├── migrations/             # 数据库迁移 (Aerich)
│   └── src/
│       ├── apps/               # 业务模块
│       │   ├── api_test/       # 接口测试核心
│       │   │   ├── agents/     # LangGraph AI 工作流
│       │   │   ├── api/        # API 路由
│       │   │   ├── services/   # 业务服务
│       │   │   ├── parser/     # 文档解析器
│       │   │   ├── models.py   # 数据模型
│       │   │   ├── schemas.py  # 请求/响应模型
│       │   │   └── crud.py     # 数据操作
│       │   ├── system_manage/  # RBAC 系统管理
│       │   │   ├── user/       # 用户管理
│       │   │   ├── role/       # 角色管理
│       │   │   ├── menu/       # 菜单管理
│       │   │   ├── permission/ # 权限管理
│       │   │   └── organization/ # 组织管理
│       │   ├── file_manage/    # 文件管理
│       │   └── project/        # 项目管理
│       ├── common/             # 公共模块
│       │   └── agui/           # AG-UI 协议实现
│       ├── core/               # 核心配置
│       │   ├── config.py       # 应用配置
│       │   ├── db/             # 数据库配置
│       │   ├── auth.py         # 认证授权
│       │   ├── middleware.py   # 中间件
│       │   └── exception.py    # 异常处理
│       └── engines/            # 自研引擎
│           └── api_test_engine/ # 测试执行引擎
│               ├── core/       # 执行器核心
│               ├── variable/   # 变量管理
│               ├── assertion/  # 断言处理
│               ├── script/     # 脚本沙箱
│               └── request/    # HTTP 客户端
│
├── frontend/                   # 前端源码
│   ├── src/
│   │   ├── app/                # Next.js App Router
│   │   │   ├── page.tsx        # 登录页
│   │   │   ├── project-selector/ # 项目选择
│   │   │   └── dashboard/      # 主控制台
│   │   │       ├── api-manage/ # 接口测试管理
│   │   │       │   ├── apis/           # 接口管理
│   │   │       │   ├── cases/          # 用例管理
│   │   │       │   ├── ai-case-generator/ # AI 生成器
│   │   │       │   ├── dependencies/   # 依赖分析
│   │   │       │   ├── scenes/         # 业务流
│   │   │       │   ├── collections/    # 用例集合
│   │   │       │   ├── envs/           # 环境管理
│   │   │       │   └── execution-reports/ # 执行报告
│   │   │       ├── file-manage/  # 文件管理
│   │   │       ├── users/        # 用户管理
│   │   │       ├── roles/        # 角色管理
│   │   │       └── ...
│   │   ├── api/                # API 请求封装
│   │   ├── components/         # 公共组件
│   │   ├── hooks/              # 自定义 Hooks
│   │   ├── store/              # Zustand 状态
│   │   └── types/              # TypeScript 类型
│   ├── package.json            # 依赖配置
│   └── next.config.ts          # Next.js 配置
│
└── README.md                   # 项目文档
```

---

## 核心业务流程 (Core Business Flows)

### 1. AI 智能用例生成流程 (AI Case Generation)
系统采用 **LangGraph** 构建了一个具备“自愈能力”的智能体工作流，实现了从需求到脚本的闭环。

```mermaid
graph TD
    A[记忆检查] --> B{命中有效记忆?}
    B -- 是 --> C[复用历史用例]
    B -- 否 --> D[数据准备 & 环境加载]
    D --> E[上下文分析子图]
    E --> F[测试点生成]
    F --> G[覆盖率验证]
    G -- 覆盖不足 --> H[补充生成]
    H --> G
    G -- 覆盖充足 --> I[Send 并发生成用例]
    I --> J[用例审核]
    J -- 等待确认 --> K[暂停流程]
    J -- 继续执行 --> L[预执行校验]
    L -- 失败 --> M[自愈修复]
    M --> L
    L -- 成功 --> N[保存用例]
    N --> O[更新记忆]
```

**工作流节点说明：**

| 节点 | 功能 |
|------|------|
| `memory_check` | 检查 MongoDB 中是否有可复用的历史生成结果 |
| `data_preparation` | 加载接口元数据、依赖关系 |
| `environment_loading` | 加载环境配置、数据库 Schema、全局函数 |
| `context_analysis_subgraph` | 子图：压缩大数据为摘要，减少 Token 消耗 |
| `test_point_generation` | 生成多维度测试点（正向/反向/边界/异常） |
| `coverage_verification` | 验证测试点覆盖率，不足则补充 |
| `case_gen_worker` | **Send 并发**：为每个测试点分发独立 Worker |
| `case_review` | 用户审核节点，可暂停等待人工确认 |
| `case_pre_execution` | 预执行用例，验证可运行性 |
| `retry_failed_cases` | 自愈修复：分析错误并重新生成 |
| `save_cases` | 持久化保存到数据库 |
| `update_memory` | 更新 MongoDB 记忆，供后续复用 |

**关键特性：**
- **LangGraph Send 并发调度**：利用 `Send` API 为每个测试点分发独立 Worker，极大提升生成吞吐量
- **自愈式修复 (Self-Healing)**：`RetryHandler` 节点捕获预执行中的错误，将错误栈反馈给 LLM 自动修正
- **记忆机制**：基于 MongoDB 存储历史结果，支持断点续存和完全复用
- **人工审核**：支持在用例生成后暂停，等待用户确认后继续执行
- **上下文感知**：AI 感知 `Project Spec`（项目规范）和 `Database Schema`，生成更精准的用例

### 2. 混合动力接口依赖分析 (Hybrid Dependency Inference)
采用“确定性规则 + 模糊 LLM 推理”的架构。

```mermaid
graph LR
    subgraph "规则引擎 (Rule-based)"
    R1[外键映射: project_id]
    R2[标准 Auth: Authorization]
    R3[RESTful CRUD 模式]
    end

    subgraph "LLM 推理 (AI-based)"
    L1[业务语义关联]
    L2[嵌套字段数据流提取]
    end

    Input[接口列表] --> R1 & R2 & R3
    Input --> L1 & L2
    R1 & R2 & R3 & L1 & L2 --> Merge[拓扑排序 & 冲突合并]
    Merge --> Output[依赖关系图谱]
```

**关键逻辑详解：**
- **Data Mappings**: 每一条依赖均包含具体的字段映射路径（如 `response.data.id -> body.user_id`）。
- **执行优先级排序**: 基于分析出的依赖图进行拓扑排序，确保在执行业务流时，前置资源（如用户、权限）已准备就绪。

### 3. 测试执行引擎与变量生命周期 (Execution Engine)
自研的执行引擎支持复杂的上下文管理。

```mermaid
sequenceDiagram
    participant UI as 触发端
    participant Service as 执行编排服务
    participant Engine as TestExecutor
    participant Sandbox as RestrictedPython 沙箱
    participant Context as ExecutionContext

    UI->>Service: 发起任务 (Scene/Collection)
    Service->>Context: 初始化 (注入环境变量/DB连接)
    
    loop 遍历用例
        Service->>Engine: 执行用例
        Engine->>Engine: 变量解析 ({{var}} 替换)
        Engine->>Sandbox: 执行 Setup 脚本 (加密、签名等)
        Engine->>Target: 发起异步 HTTP 请求
        Target-->>Engine: 返回结果
        Engine->>Context: 变量提取 (Extracts) & 存入作用域
        Engine->>Engine: 配置式断言 + 脚本断言
        Engine->>Sandbox: 执行 Teardown 脚本 (清理数据)
    end

    Service->>UI: SSE 流式推送结果报告
```

**关键逻辑详解：**
- **作用域隔离 (Scoping)**: 严格区分 `Global` (环境)、`Suite` (集合) 和 `Case` (单用例) 三级作用域。
- **安全沙箱 (Sandboxing)**: 使用 `RestrictedPython` 执行用户脚本，在保证灵活性的同时，防止危险系统调用。
- **动态注入**: 支持动态函数调用，如 `{{get_current_time()}}` 可实时注入脚本执行结果。

---

## 技术亮点 (Project Highlights)
- **AG-UI Protocol**: 自研流式状态转换协议，前端可通过 SSE (Server-Sent Events) 实时观察 AI 思考过程和节点流转。
- **全异步链路**: 从 FastAPI 接口到 Tortoise-ORM 数据库操作，再到 HTTPX 请求，全链路异步处理，支持大规模并发执行。
- **AI 智能驱动**: 核心逻辑不仅是“生成”，更侧重于通过自愈机制保证生成代码的“可执行性”。

---

## AG-UI 协议深度解析 (AG-UI Protocol Deep Dive)

验熵核采用自研的 **AG-UI 协议** 解决大模型生成任务执行时间长、过程黑盒的问题。该协议通过 Server-Sent Events (SSE) 实现了后端执行引擎与前端 UI 的实时状态同步。

### 1. 协议核心组件
- **`AGUIEventEmitter`**: 标准化事件发射器，负责将后端逻辑（如：加载配置、调用 LLM、执行校验）转化为标准协议包。
- **`StreamingService`**: 流式服务基类，内置了 **进度节流 (Throttle)** 和 **日志缓冲 (Buffer)** 机制，确保在高并发日志输出时前端渲染不卡顿。

### 2. 标准化事件流 (Standardized Events)
协议定义了一系列标准事件类型，涵盖了任务的完整生命周期：
- **生命周期**: `RUN_STARTED` / `RUN_FINISHED` / `RUN_ERROR`
- **执行步骤**: `STEP_STARTED` / `STEP_FINISHED` (用于展示左侧步骤条流转)
- **实时日志**: `TEXT_MESSAGE_CONTENT` (用于实时滚动展示 AI 思考过程或执行日志)
- **数据快照**: 
    - `PROGRESS`: 实时进度百分比（0.0 - 1.0）。
    - `STATS`: 统计信息快照（如：成功数、失败数、跳过数）。
    - `CASE_GENERATED`: 实时推送新生成的用例预览。

### 3. 应用场景示例
在 **AI 用例生成** 过程中，协议驱动前端实现以下动态效果：
1. **进度条**: 随着 `PROGRESS` 事件平滑移动。
2. **步骤条**: 实时高亮当前所在的 LangGraph 节点（如：从“测试点生成”自动跳至“覆盖率验证”）。
3. **控制台**: 实时输出 LLM 的分析过程和执行引擎的原始请求响应。

### 4. 开发者快速上手 (Quick Start for Developers)

后端开发者可以通过 `AGUIEventEmitter` 轻松接入协议：

```python
from src.common.agui import AGUIEventEmitter

# 1. 初始化发射器
emitter = AGUIEventEmitter(thread_id="task_001", run_id="run_001")

# 2. 发送任务生命周期事件
yield emitter.run_started()

# 3. 推送实时日志
yield emitter.log_message("🔍 正在分析接口元数据...")

# 4. 更新进度与状态
yield emitter.progress_update(0.45, "analysis", {"detail": "识别到 5 个潜在依赖"})

# 5. 推送业务快照 (如生成的用例)
yield emitter.activity_snapshot("CASE_GENERATED", {"title": "登录成功场景", "id": 101})

# 6. 结束任务
yield emitter.run_finished({"status": "completed"})
```

---

## 核心功能详解

### 1. AI 智能驱动 (AI-Powered)
- **自动用例生成**: 基于 LangGraph 的智能体流，通过分析接口定义自动生成结构化的测试用例，包含前置步骤、请求参数、断言配置。
- **依赖关系分析**: 利用 LLM 自动识别接口间的参数传递关系（如：登录接口返回的 Token 用于后续接口），并自动构建依赖图和执行顺序。
- **数据自动填充**: AI 根据参数类型和描述自动生成符合业务逻辑的测试数据。

### 2. 自动化测试引擎
- **执行编排**: 支持将多个用例组合为“业务流（Scene）”，支持串行执行。支持“用例集合（Collection）”，支持并行执行和多 Worker 调度。
- **环境管理**: 支持多套测试环境配置，动态替换 BaseURL 和全局变量。
- **断言与提取**: 丰富的断言方式（JSONPath, JMESPath, Status Code）和参数提取机制。
- **报告分析**: 详细的执行报告，支持查看原始请求响应、日志记录和性能耗时。

### 3. 系统管理 (RBAC)
- **多维度权限**: 基于用户-角色-菜单-权限的经典模型。
- **动态路由**: 前端根据后端返回的菜单权限动态生成侧边栏。
- **数据隔离**: 支持按照项目粒度进行数据访问控制。

---

## 快速开始

### 环境要求

| 依赖 | 版本 |
|------|------|
| Python | ≥ 3.13 |
| Node.js | ≥ 18.x |
| MySQL | ≥ 8.0 |
| MongoDB | ≥ 6.0 |
| MinIO | 最新版 |

### 后端启动

```bash
# 1. 进入后端目录
cd backend

# 2. 安装依赖（推荐使用 uv）
uv sync
# 或使用 pip
pip install -e .

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 配置数据库、AI 大模型、MinIO 等

# 4. 初始化数据库
aerich upgrade

# 5. 启动服务
python main.py
```

服务启动后：
- **API 文档**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc

### 前端启动

```bash
# 1. 进入前端目录
cd frontend

# 2. 安装依赖
npm install

# 3. 配置环境变量
cp .env.example .env.local
# 编辑 .env.local 配置 API 地址

# 4. 启动开发服务器
npm run dev
```

访问地址: http://localhost:3000

### 环境变量配置示例

**后端 `.env`**:
```bash
# 应用配置
APP_NAME=验熵核
DEBUG=True
HOST=0.0.0.0
PORT=8000

# MySQL 数据库
DATABASE_NAME=entropy_check
DATABASE_HOST=localhost
DATABASE_PORT=3306
DATABASE_USER=root
DATABASE_PASSWORD=your_password

# AI 大模型（DeepSeek/OpenAI）
DEEPSEEK_API_KEY=your_api_key
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL_NAME=deepseek-chat

# MinIO 对象存储
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=your_access_key
MINIO_SECRET_KEY=your_secret_key
MINIO_BUCKET_NAME=entropy-check

# MongoDB（AI 记忆存储）
MONGODB_URL=mongodb://localhost:27017
MONGODB_DB_NAME=ai_case_memory
```

**前端 `.env.local`**:
```bash
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
```

---

## 功能模块总览

| 模块 | 功能 | 前端路由 |
|------|------|----------|
| **接口管理** | 接口信息的增删改查、调试 | `/dashboard/api-manage/apis` |
| **用例管理** | 测试用例管理、编辑、执行 | `/dashboard/api-manage/cases` |
| **AI 用例生成** | AI 自动生成测试用例 | `/dashboard/api-manage/ai-case-generator` |
| **依赖分析** | 接口依赖关系分析与可视化 | `/dashboard/api-manage/dependencies` |
| **业务流** | 场景编排、串行执行 | `/dashboard/api-manage/scenes` |
| **用例集合** | 用例集合、并行执行 | `/dashboard/api-manage/collections` |
| **环境管理** | 测试环境配置 | `/dashboard/api-manage/envs` |
| **项目规范** | 项目级接口规范配置 | `/dashboard/api-manage/project-spec` |
| **文档解析** | Swagger/Postman 文档导入 | `/dashboard/api-manage/doc-parse` |
| **执行报告** | 执行历史记录和报告 | `/dashboard/api-manage/execution-reports` |
| **文件管理** | MinIO 文件管理 | `/dashboard/file-manage` |
| **用户管理** | 用户增删改查、角色分配 | `/dashboard/users` |
| **角色管理** | 角色权限配置 | `/dashboard/roles` |
| **菜单管理** | 动态菜单配置 | `/dashboard/menus` |
| **组织管理** | 组织架构管理 | `/dashboard/organizations` |
| **项目管理** | 项目的增删改查 | `/dashboard/projects` |

---

## 数据模型概览

### 接口测试模块

| 模型 | 说明 |
|------|------|
| `ApiEnvs` | 测试环境（Host、全局变量、请求头、数据库配置） |
| `ApisInfos` | 接口信息（URL、Method、Headers、Request） |
| `ApiCases` | 测试用例（脚本、断言、提取、类型） |
| `ApiScenes` | 业务流场景（串行执行编排） |
| `ApiCollections` | 用例集合（并行执行） |
| `ApiTestRuns` | 执行记录（状态、报告、耗时） |
| `ApiDependency` | 接口依赖关系（数据流映射） |
| `ApiProjectSpecs` | 项目级接口规范 |

### 系统管理模块

| 模型 | 说明 |
|------|------|
| `User` | 用户信息（认证、角色关联） |
| `Role` | 角色（权限集合） |
| `Menu` | 菜单（动态路由） |
| `Permission` | 细粒度权限 |
| `Organization` | 组织架构 |

### 文件管理模块

| 模型 | 说明 |
|------|------|
| `FileInfo` | 文件元信息（OSS 路径、MD5） |
| `Document` | 业务文档（需求、设计、用例） |
| `ApiDocConfig` | 接口文档配置（Swagger/Postman） |

---

## 开发规范

### 后端开发

```text
新增模块步骤：
1. 在 src/apps/ 下创建模块目录
2. 创建 models.py - 数据模型
3. 创建 schemas.py - 请求/响应模型
4. 创建 crud.py - 数据操作
5. 创建 api/ 目录 - 接口路由
6. 在 main.py 中注册路由
```

### 前端开发

```text
目录约定：
- 页面: src/app/dashboard/[module]/page.tsx
- 组件: src/components/[ComponentName]/index.tsx
- API: src/api/[module]/[resource].ts
- 类型: src/types/[module]/[type].ts
- Store: src/store/use[Name]Store.ts
- Hook: src/hooks/use[Name].ts
```

### AI 调优

- **提示词模板**: `backend/src/apps/api_test/agents/prompts/`
- **工作流节点**: `backend/src/apps/api_test/agents/nodes/`
- **子图定义**: `backend/src/apps/api_test/agents/subgraphs/`

---

## 相关文档

- **后端详细文档**: [backend/README.md](./backend/README.md)
- **前端详细文档**: [frontend/README.md](./frontend/README.md)
- **AG-UI 协议文档**: [backend/src/common/agui/README.md](./backend/src/common/agui/README.md)



---

## 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request