# entropy-check

**Repository Path**: rain_yang/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**: 0
- **Forks**: 1
- **Created**: 2026-01-12
- **Last Updated**: 2026-01-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

## 项目简介
验熵核是一个现代化的自动化测试平台，核心亮点在于利用 **AI (大模型)** 技术辅助接口测试，包括自动生成测试用例、智能分析接口依赖关系以及全自动化的执行编排。系统采用前后端分离架构，提供了完整的 RBAC 权限管理和丰富的功能模块。

---

## 技术栈

### 后端 (Backend)
- **核心框架**: [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) - 用于构建智能体(Agents)和复杂的工作流，实现测试用例自动生成。
- **存储服务**: [Minio](https://min.io/) - 对象存储，用于管理测试相关文件。
- **任务编排**: 自研执行引擎，支持场景(Scene)和集合(Collection)的并发/顺序执行。
- **依赖管理**: `pyproject.toml` (uv/pip)。

### 前端 (Frontend)
- **核心框架**: [Next.js 15+](https://nextjs.org/) (App Router) - 基于 React 19 的现代前端框架。
- **UI 组件库**: [Ant Design (antd)](https://ant.design/) - 企业级 UI 组件库。
- **样式处理**: [Tailwind CSS](https://tailwindcss.com/) - 原子化 CSS 框架。
- **状态管理**: [Zustand](https://github.com/pmndrs/zustand) - 轻量级状态管理工具。
- **编辑器**: [Monaco Editor](https://microsoft.github.io/monaco-editor/) - 用于测试脚本和 JSON 的在线编辑。
- **图表展示**: [ECharts](https://echarts.apache.org/) - 数据可视化分析。

---

## 目录结构

```text
.
├── backend/                # 后端源码
│   ├── main.py            # 入口文件
│   ├── src/
│   │   ├── apps/          # 业务逻辑模块
│   │   │   ├── api_test/  # 接口测试核心逻辑 (AI生成、依赖分析、执行引擎)
│   │   │   ├── system_manage/ # RBAC 系统管理 (用户、角色、菜单、权限)
│   │   │   ├── file_manage/   # 文件管理模块
│   │   │   └── project/       # 项目与模块管理
│   │   ├── core/          # 核心配置 (DB、日志、异常处理、中间件)
│   │   └── engines/       # 自研测试引擎
│   └── migrations/        # 数据库迁移文件
├── frontend/               # 前端源码
│   ├── src/
│   │   ├── app/           # Next.js 页面路由
│   │   ├── api/           # 后端接口请求封装
│   │   ├── components/    # 通用组件 (AI分析弹窗、执行模态框等)
│   │   ├── store/         # Zustand 状态库
│   │   └── utils/         # 工具函数 (权限校验、格式化)
│   ├── public/            # 静态资源
│   └── package.json       # 项目依赖
└── README.md              # 项目文档
```

---

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

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

```mermaid
graph TD
    A[加载接口元数据 & Spec] --> B[环境加载 & 数据库 Schema 提取]
    B --> C[智能生成多维度测试点]
    C --> D[覆盖率验证 & 场景补充]
    D -- 覆盖不足 --> E[AI 针对性补全]
    E --> D
    D -- 覆盖充足 --> F[并发生成结构化用例]
    F --> G[用例预执行校验]
    G -- 报错/失败 --> H[自愈修复: 分析报错并重正脚本]
    H --> G
    G -- 成功/达标 --> I[持久化保存至用例库]
```

**关键逻辑详解：**
- **LangGraph 并发调度**: 利用 `Send` API 为每个测试点（Positive/Negative/Boundary）分发独立 Worker，极大提升生成吞吐量。
- **自愈式修复 (Self-Healing)**: `RetryHandler` 节点会捕获预执行中的 `RequestError` 或 `AssertionError`，将错误栈反馈给 LLM，实现脚本的自动修正。
- **上下文感知**: 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)
- **多维度权限**: 基于用户-角色-菜单-权限的经典模型。
- **动态路由**: 前端根据后端返回的菜单权限动态生成侧边栏。
- **数据隔离**: 支持按照项目粒度进行数据访问控制。

---

## 快速开始

### 后端启动
1. 进入目录: `cd backend`
2. 安装依赖: `pip install -e .` 或 `uv sync`
3. 配置环境: 修改 `.env` 文件中的数据库和 OpenAI 配置
4. 启动服务: `python main.py`

### 前端启动
1. 进入目录: `cd frontend`
2. 安装依赖: `npm install`
3. 启动开发模式: `npm run dev`
4. 访问地址: `http://localhost:3000`

---

## 开发建议
- **后端**: 新增功能请在 `src/apps` 下创建子模块，遵循 `api -> schemas -> crud -> models` 的层次结构。
- **前端**: 页面逻辑位于 `src/app/dashboard` 下，公用业务组件存放在 `src/components`。
- **AI 调优**: 提示词和智能体逻辑位于 `backend/src/apps/api_test/services/ai_case_generator`。