# SUN_Agent

**Repository Path**: swlgitee/sun_agent

## Basic Information

- **Project Name**: SUN_Agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-20
- **Last Updated**: 2026-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🌞 SUN Agent - AI 自动化软件测试平台

<div align="center">

**Smart Unified Testing Agent**

> 极简 AI 自动化调度底座 + 可插拔 Skill 插件架构
> 
> 作者：孙文龙
> 
> 新增控制场景仅需新增 Skill 文件，无需修改核心底座代码

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

</div>

---

## ✨ 特性亮点

- 🧠 **AI 智能决策** - 对接大模型（智谱 GLM / OpenAI），内置模拟 LLM 快速测试
- 🔌 **可插拔 Skill 架构** - 新增控制场景只需添加 `.md` + `actions/`，底座零修改
- 🌐 **多平台支持** - Web (Playwright) / Android (ADB) / 微信小程序
- 📋 **多格式用例** - 支持 YAML / JSON / Excel / CSV 导入
- 📊 **HTML 可视化报告** - 含截图、状态图表、执行详情
- 🤖 **TUI 交互模式** - 类似 ChatGPT 的对话式测试体验
- 🔄 **自动重试机制** - 执行失败自动重试，保障测试稳定性
- 🔒 **安全配置** - `.env` 管理敏感信息，API Key 不泄露

---

## 📦 快速开始

### 1. 安装依赖

```bash
# 克隆项目
cd xlong-agent

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

# 安装 Playwright 浏览器
playwright install chromium
```

### 2. 配置环境

```bash
# 复制环境配置模板
cp .env.example .env

# 编辑 .env 文件，填入你的 API Key
```

`.env` 配置示例：
```bash
# 智谱 AI 配置
LLM_API_KEY=your-api-key-here
LLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4/
LLM_MODEL=glm-4.5-air

# ADB 配置（可选）
ADB_DEVICE=emulator-5554

# 浏览器配置
BROWSER_HEADLESS=false
```

### 3. 启动运行

```bash
# 交互模式（推荐）
python main.py

# 命令行模式
python main.py --mode import --file test_cases/manual/baidu_search_success.yaml
python main.py --mode generate --prompt "测试百度搜索功能"
python main.py --mode explore --target "https://www.baidu.com"
```

---

## 🏗️ 项目架构

```
xlong-agent/
├── core/                          # 核心底座（永不修改）
│   ├── ai_agent.py               # AI 交互模块（支持真实 API / 模拟降级）
│   ├── skill_loader.py           # MD Skill 动态加载器（自动发现插件）
│   ├── executor.py               # 多轮决策执行引擎（自动重试）
│   └── orchestrator.py           # 全局编排器（协调 Skill/用例/报告）
│
├── skills/                        # Skill 插件目录（按需新增）
│   ├── web_browser/              # 🌐 Web 浏览器控制
│   │   ├── skill.md              #    能力描述文件（声明式）
│   │   └── actions/              #    操作实现
│   ├── android_app/              # 📱 Android App 控制
│   │   ├── skill.md
│   │   └── actions/
│   ├── wechat_mini/              # 💬 微信小程序控制
│   │   ├── skill.md
│   │   └── actions/
│   ├── file_reader/              # 📂 用例文件导入
│   │   ├── skill.md
│   │   └── actions/
│   └── report_generator/         # 📊 HTML 报告生成
│       ├── skill.md
│       └── actions/
│
├── modules/                       # 业务功能模块
│   ├── test_case_manager.py      # 用例管理（增删改查）
│   ├── test_case_generator.py    # AI 智能生成用例
│   ├── test_case_optimizer.py    # 用例优化/去重/覆盖率分析
│   └── report_builder.py         # HTML 报告构建
│
├── test_cases/                    # 测试用例目录
│   ├── manual/                   # 手动编写用例
│   ├── generated/                # AI 生成用例
│   └── imported/                 # 导入的外部用例
│
├── reports/                       # 测试报告输出
├── screenshots/                   # 截图存档
├── utils/                         # 工具模块
│   ├── config.py                 # 配置管理（结合 .env）
│   ├── logger.py                 # 日志管理
│   ├── file_parser.py            # 文件解析器
│   ├── validators.py             # 数据校验
│   └── ocr_helper.py             # OCR 辅助
│
├── config.py                      # 全局默认配置
├── main.py                        # 项目入口（含 TUI 交互）
├── .env                           # 环境变量（不提交到 Git）
├── .env.example                   # 环境变量模板
└── requirements.txt               # Python 依赖清单
```

---

## 🎮 使用教程

### 交互模式（推荐）

```bash
python main.py
```

进入类似 ChatGPT 的 TUI 对话界面：

```
╔══════════════════════════════════════════════════════════╗
║                                                          ║
║    ███████╗██╗  ██╗    ██████╗  █████╗ ████████╗        ║
║    ██╔════╝╚██╗██╔╝    ██╔══██╗██╔══██╗╚══██╔══╝        ║
║    █████╗   ╚███╔╝     ██████╔╝███████║   ██║           ║
║    ██╔══╝   ██╔██╗     ██╔══██╗██╔══██║   ██║           ║
║    ███████╗██╔╝ ██╗    ██║  ██║██║  ██║   ██║           ║
║    ╚══════╝╚═╝  ╚═╝    ╚═╝  ╚═╝╚═╝  ╚═╝   ╚═╝           ║
║                                                          ║
║        Smart Unified Testing Agent (SUN)                 ║
║            AI 自动化软件测试平台                           ║
║                                                          ║
╚══════════════════════════════════════════════════════════╝

📋 支持命令列表：
────────────────────────────────────────────────────────────
  import   <文件路径>    - 导入并执行测试用例
  generate <需求描述>    - AI 自动生成用例并执行
  explore  <目标地址>    - AI 自主探索测试
  report                 - 查看测试报告统计
  skills                 - 查看已加载的 Skill 插件
  help                   - 显示此帮助信息
  quit / exit            - 退出程序
────────────────────────────────────────────────────────────

💡 提示: 输入命令开始测试，输入 'quit' 或 'exit' 退出

🔹 SUN Agent > import test_cases/manual/baidu_search_success.yaml
```

### 典型使用场景

#### 场景 1：导入现有用例执行

```
🔹 SUN Agent > import test_cases/manual/baidu_search_success.yaml

📂 导入模式: test_cases/manual/baidu_search_success.yaml
解析到 1 个测试用例
开始执行任务...

📊 执行结果:
  1. 百度搜索 - 成功场景
     状态: ✅ 通过
     耗时: 6.90s

📄 报告已生成: reports/report_1.html
```

#### 场景 2：模糊需求 → AI 生成用例 → 执行

```
🔹 SUN Agent > generate 测试微信登录功能

🤖 AI 生成模式: 测试微信登录功能
AI 生成 1 个测试用例
开始执行...

📊 执行结果:
  1. 微信登录测试
     状态: ✅ 通过
     耗时: 12.5s
```

#### 场景 3：自主探索测试

```
🔹 SUN Agent > explore https://example.com

🔍 探索测试: https://example.com
AI 自主规划探索步骤...
```

#### 场景 4：查看 Skill 插件

```
🔹 SUN Agent > skills

📦 已加载的 Skill 插件:
  ✅ web_browser v1.0.0
     描述: 控制网页浏览器
     操作: navigate, click, input_text, screenshot, get_text, wait_element
  ✅ android_app v1.0.0
     描述: 控制安卓 App
     操作: launch_app, tap, input_text, screenshot, swipe, get_ui_tree
  ✅ wechat_mini v1.0.0
     描述: 控制微信小程序
     操作: launch_mini, tap, input_text, screenshot
  ✅ file_reader v1.0.0
     描述: 读取测试用例文件
     操作: read
  ✅ report_generator v1.0.0
     描述: 生成 HTML 测试报告
     操作: generate_html
```

---

## 📝 用例文件格式

### YAML 格式

```yaml
# test_cases/manual/login_test.yaml
name: "登录功能测试"
platform: "web"  # web / app / mini_program

steps:
  - action: "navigate"
    url: "https://example.com/login"
    
  - action: "wait_element"
    selector: "#username"
    timeout: 10000
    
  - action: "input_text"
    selector: "#username"
    value: "test_user"
    
  - action: "click"
    selector: "#login-btn"
    
  - action: "screenshot"
    save_path: "screenshots/login_result.png"
```

### JSON 格式

```json
{
  "name": "登录功能测试",
  "platform": "web",
  "steps": [
    {
      "action": "navigate",
      "url": "https://example.com/login"
    },
    {
      "action": "click",
      "selector": "#login-btn"
    }
  ]
}
```

### Excel/CSV 格式

| name | platform | action | selector | value |
|------|----------|--------|----------|-------|
| 登录测试 | web | navigate | | https://example.com |
| 登录测试 | web | click | #login-btn | |

---

## 🔌 Skill 插件扩展教程

### 新增控制场景只需 3 步

假设我们要新增一个 **数据库测试 Skill**：

#### 步骤 1：创建目录

```bash
mkdir -p skills/database/actions
```

#### 步骤 2：编写 skill.md

```markdown
---
name: database
version: 1.0.0
description: 数据库操作，支持查询、插入、删除
author: your_name
dependencies:
  - pymysql
---

# Database Skill

## 能力描述
自动化数据库操作测试

## 操作列表

### query
执行查询
- 参数: `sql` (必填) - SQL 语句
- 返回: 查询结果

### insert
插入数据
- 参数: `table` (必填) - 表名
- 参数: `data` (必填) - 数据字典
- 返回: 插入是否成功
```

#### 步骤 3：实现 actions

```python
# skills/database/actions/query.py
"""执行数据库查询"""
from utils.logger import logger

def execute(sql: str, **kwargs) -> dict:
    """
    执行 SQL 查询
    
    Args:
        sql: SQL 语句
    
    Returns:
        查询结果
    """
    try:
        import pymysql
        conn = pymysql.connect(host='localhost', user='root', password='', database='test')
        cursor = conn.cursor()
        cursor.execute(sql)
        result = cursor.fetchall()
        conn.close()
        
        logger.info(f"查询成功: {sql}")
        return {"rows": result}
    except Exception as e:
        logger.error(f"查询失败: {e}")
        raise
```

#### 完成！重启程序自动加载

```bash
python main.py

🔹 SUN Agent > skills
📦 已加载的 Skill 插件:
  ✅ database v1.0.0
     描述: 数据库操作
     操作: query, insert
```

**核心底座完全不需要修改！**

---

## 🔧 替换真实大模型 API

当前项目已对接智谱 GLM API，如需更换其他模型：

### 智谱 GLM（已配置）

```bash
# .env
LLM_API_KEY=your-zhipu-api-key
LLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4/
LLM_MODEL=glm-4.5-air
```

### OpenAI GPT

```bash
# .env
LLM_API_KEY=sk-your-openai-key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4
```

### 本地模型（Ollama）

```bash
# .env
LLM_API_KEY=ollama
LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL=llama3
```

### 模拟模式（无需 API Key）

不配置 `LLM_API_KEY` 时自动使用模拟回复，适合快速测试流程。

---

## 📱 Android 环境准备

### 自动检测

项目已内置 ADB 环境自动检测，运行 App 测试时会自动检查：

```
正在检测 Android 环境...
检测到 1 个设备: ['emulator-5554']
使用第一个设备: emulator-5554
ADB 设备连接成功
```

### 手动配置

1. **安装 Android SDK Platform Tools**
   ```bash
   # macOS
   brew install android-platform-tools
   
   # Windows
   # 下载: https://developer.android.com/studio/releases/platform-tools
   # 解压后将 adb.exe 所在目录加入系统 PATH
   ```

2. **连接手机并开启 USB 调试**
   - 手机设置 → 关于手机 → 连续点击版本号开启开发者模式
   - 开发者选项 → 开启 USB 调试

3. **验证连接**
   ```bash
   adb devices
   # 输出:
   # List of devices attached
   # ABC123DEF    device
   ```

4. **配置 .env**
   ```bash
   ADB_DEVICE=ABC123DEF  # 替换为你的设备 ID
   ```

---

## 🌐 Web 环境准备

### 安装 Playwright

```bash
pip install playwright
playwright install chromium
```

### 浏览器配置

```bash
# .env
BROWSER_HEADLESS=false  # 设为 true 则无头模式
```

---

## 💬 微信小程序环境准备

1. 安装微信开发者工具
2. 开启服务端口（设置 → 安全 → 开启服务端口）
3. 配置 .env：
   ```bash
   WECHAT_CLI_PATH=/path/to/wechat-devtools/cli
   ```

---

## 📊 测试报告示例

运行测试后自动生成 HTML 报告：

```
reports/
├── report_1.html    # 成功案例
├── report_2.html    # 错误案例
└── report_3.html    # 探索测试
```

报告包含：
- ✅/❌ 状态标识
- 📈 统计图表（总计/通过/失败/耗时）
- 🖼️ 截图展示
- 📋 步骤详情
- 🔴 错误信息

---

## 📜 许可证

MIT License

---

## 🙏 致谢

- [Playwright](https://playwright.dev/) - Web 自动化
- [adbutils](https://github.com/openatx/adbutils) - Android 自动化
- [OpenAI Python SDK](https://github.com/openai/openai-python) - AI 交互
- [Jinja2](https://jinja.palletsprojects.com/) - HTML 模板