# appui_agent

**Repository Path**: aiagentdemo/appui_agent

## Basic Information

- **Project Name**: appui_agent
- **Description**: App UI 自动化 AI Agent
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-20
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# App UI 自动化 AI Agent

一个用大模型驱动的 **App UI 自动化测试 Agent**。它把"一句话需求"逐步变成可在真机上执行的自动化用例，全流程五步，关键节点有人工确认。

```
需求/用例 ──①LLM解析──> 手工测试用例 ──②人工确认──> ✅
                                                      │
项目源码 ──③LLM分析──> 页面地图(JSON+Mermaid) ───────┤
                                                      ▼
   ④LLM生成 ──> agent-device 命令序列 ──⑤检测设备并执行──> 执行报告
```

## 界面预览

![App UI 自动化 AI Agent](./docs/screenshot.png)


## 五个步骤

1. **需求 → 手工用例**：输入需求描述或粗略用例，大模型解析成结构化手工测试用例（标题、前置条件、步骤、每步预期结果、优先级）。
2. **人工确认**：展示生成的用例，用户确认后才继续。CLI 是终端确认，Web 是"确认"按钮。
3. **页面地图**：扫描被测项目源码（自动适配 Android/iOS 原生、RN/Flutter、Vue 等任意技术栈），大模型推导页面间的跳转关系，输出页面地图（`page_map.json` + `page_map.mmd` Mermaid 图）。
4. **命令序列**：结合手工用例 + 页面地图，大模型生成 [agent-device](https://) 可执行的命令序列（`open/snapshot/find/click/fill/wait/is/close` 等），并为每条用例导出一个可直接运行的 shell 脚本。
5. **设备执行**：检测本机连接的手机/模拟器，按 `open → snapshot → act → verify` 循环执行命令序列，输出 PASS/FAIL 报告。未安装 agent-device 时自动降级为 dry-run 预览。

## 扩展能力：Skill 与 MCP 工具

除五步流程外，Web 界面还提供两类扩展能力，二者都会增强大模型的请求：

**Skill 管理（`/skills`）**：上传 zip 格式的 Skill 包（内含 `SKILL.md` + 任意支持文件），后端自动解压到 `data/skills/<name>/`。界面可查看 Skill 的 `SKILL.md` 正文、frontmatter，以及包内**所有文件的内容**。已启用的 Skill，其 `SKILL.md` 正文会注入到用例生成 / 页面地图 / 命令序列各阶段的系统提示词中，让大模型参考其中的最佳实践。可随时启用/停用/删除。

**MCP 工具管理（`/tools`）**：配置 MCP (Model Context Protocol) server（command / args / env），后端通过 stdio JSON-RPC **真实连接**该 server，完成 `initialize` 握手并拉取 `tools/list`，也支持 `tools/call`。已启用 server 的工具清单会作为"当前可用工具"上下文提供给大模型。配置保存在 `data/mcp_servers.json`。

## 目录结构

```
appui_agent/
├── core/                  # 核心引擎（仅依赖 Python 标准库）
│   ├── config.py          # 配置（LLM 端点、数据目录等，全部可用环境变量覆盖）
│   ├── llm.py             # OpenAI 兼容 LLM 客户端（含 JSON 解析与重试）
│   ├── models.py          # 数据模型：TestCase / PageMap / CommandSequence
│   ├── prompts.py         # 各阶段提示词
│   ├── case_generator.py  # 步骤1
│   ├── page_mapper.py     # 步骤3：源码扫描 + 页面地图推导
│   ├── command_generator.py # 步骤4
│   ├── device_runner.py   # 步骤5：agent-device 封装、设备检测、执行
│   └── pipeline.py        # 串联五步 + 产物持久化
├── cli.py                 # 命令行入口（含人工确认）
├── webapp/
│   ├── server.py          # FastAPI 后端
│   └── index.html         # 单文件 Web 向导界面（5 步 + Mermaid 页面图）
├── data/                  # 生成的产物（用例/页面地图/命令序列/脚本/报告）
└── requirements.txt
```

## 快速开始

### 准备

核心引擎 **无需任何第三方依赖**（只用标准库）。LLM 默认复用项目内置的万擎(快手) OpenAI 兼容端点，开箱即用；也可用环境变量切换：

```bash
export WQ_BASE_URL="https://your-endpoint/v1"   # OpenAI 兼容端点
export WQ_API_KEY="sk-..."
export WQ_MODEL="gpt-4o-mini"                    # 或任意兼容模型
```

执行真机用例需要安装 [agent-device](https://) CLI 并连接设备；未安装时可用 `--dry-run` 预览。

### 命令行（CLI）

```bash
cd /Users/dragonking/Documents/AiAgentTest

# 完整流水线（交互式，含人工确认）
python -m appui_agent.cli run \
    --requirement "测试登录功能：输入邮箱和密码后点击登录，进入首页显示欢迎语" \
    --context "英语学习 App" \
    --project ./englishstudy-master \
    --platform android --app com.example.app

# 只跑单个阶段
python -m appui_agent.cli cases   --requirement "测试登录功能…"
python -m appui_agent.cli pagemap --project ./englishstudy-master
python -m appui_agent.cli devices --platform android

# 非交互（CI）：--yes 跳过确认，--dry-run 不连真机，--no-execute 只生成不执行
python -m appui_agent.cli run --requirement "…" --platform android --app com.x.app --yes --dry-run
```

### Web 界面

```bash
pip install -r appui_agent/requirements.txt
uvicorn appui_agent.webapp.server:app --reload --port 8010
# 浏览器打开 http://localhost:8010
```

Web 界面是一个 5 步向导：填需求 → 生成用例 → **点击确认** → 填项目路径生成页面地图 → 选平台/填 App 生成命令序列 → 检测设备 → Dry-run 预览或真机执行。页面地图用 Mermaid 渲染成可视化流程图。

## 产物

每次运行后，产物保存在 `appui_agent/data/`：

- `test_cases.json` —— 手工测试用例
- `page_map.json` / `page_map.mmd` —— 页面地图（数据 + Mermaid 图）
- `command_sequences.json` —— agent-device 命令序列
- `scripts/<用例ID>.sh` —— 每条用例对应的可执行 shell 脚本
- `reports/<用例ID>-<时间>.json` —— 执行报告

## 设计要点

- **核心与界面分离**：`core/` 是纯引擎，CLI 和 Web 共用同一套引擎与磁盘格式。
- **agent-device 是唯一真相源**：执行阶段直接 shell 调用 agent-device，绝不模拟；ref（`@eN`）只对最近一次 snapshot 有效，所以生成的序列会在每次界面变化后插入 `snapshot -i`。
- **大模型输出健壮性**：每个 LLM 阶段都要求严格 JSON，解析器容忍 markdown 围栏、裸数组、字符串步骤等常见偏差，并在结构/命令不合规时自动纠正重试一次。
- **优雅降级**：未安装 agent-device 时不假装执行，而是明确报告"不可执行"并建议 dry-run。

## 配置项（环境变量）

| 变量 | 说明 | 默认 |
| --- | --- | --- |
| `WQ_BASE_URL` | LLM OpenAI 兼容端点 | 万擎端点 |
| `WQ_API_KEY` | API Key | 内置 |
| `WQ_MODEL` | 模型 ID | 内置 |
| `WQ_TEMPERATURE` | 采样温度 | 0.3 |
| `AGENT_DEVICE_CMD` | agent-device 命令 | `agent-device` |
| `APPUI_DATA_DIR` | 产物目录 | `appui_agent/data` |
| `APPUI_MAX_FILES` | 页面地图分析最多读取的源文件数 | 60 |