# https://github.com/test-zeus-ai/testzeus-hercules 项目说明书
生成时间：2026-05-17 00:18:55 UTC
## 目录
- [项目概述](#page-project-overview)
- [系统架构](#page-system-architecture)
- [多代理系统](#page-agent-system)
- [工具注册与工具集](#page-tool-registry)
- [记忆管理系统](#page-memory-management)
- [Playwright 浏览器自动化](#page-playwright-automation)
- [测试能力总览](#page-testing-capabilities)
- [MCP 集成与使用](#page-mcp-integration)
- [API 测试与安全测试](#page-api-testing)
- [Python 沙箱执行](#page-python-sandbox)
## 项目概述
### 相关页面
相关主题：[系统架构](#page-system-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [frontend/non-interactive/index.html](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/frontend/non-interactive/index.html)
- [frontend/interactive/index.html](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/frontend/interactive/index.html)
- [testzeus_hercules/__main__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/__main__.py)
- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)
- [testzeus_hercules/telemetry.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/telemetry.py)
- [testzeus_hercules/utils/response_parser.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/response_parser.py)
- [CONTRIBUTING.md](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/CONTRIBUTING.md)
- [helper_scripts/generate_api_functional_gherkin_test.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/helper_scripts/generate_api_functional_gherkin_test.py)
- [testzeus_hercules/core/agents/executor_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/executor_nav_agent.py)
- [helper_scripts/cdp_journey_script.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/helper_scripts/cdp_journey_script.py)
- [testzeus_hercules/core/tools/api_sec_calls.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/api_sec_calls.py)
- [testzeus_hercules/utils/get_detailed_accessibility_tree.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/get_detailed_accessibility_tree.py)
# 项目概述
## 简介
TestZeus-Hercules 是全球首个**开源 AI 端到端测试代理**（Open-Source AI Agent for End-to-End Testing）。该项目利用大型语言模型（LLM）驱动的智能代理技术，实现浏览器自动化测试的智能化执行。 资料来源：[testzeus_hercules/__main__.py:1]()
Hercules 能够理解测试意图、自动生成和执行测试脚本，并通过 CDP（Chrome DevTools Protocol）协议与浏览器进行实时交互。项目的核心设计理念是通过 AI 技术降低端到端测试的门槛，让测试工程师能够专注于业务逻辑验证而非技术实现细节。 资料来源：[CONTRIBUTING.md:1]()
## 核心架构
### 系统组件
```mermaid
graph TD
subgraph "前端层"
FE[前端界面
非交互式/交互式CDP渲染器]
end
subgraph "核心引擎"
NAV[导航代理
ExecutorNavAgent]
RESP[响应解析器
ResponseParser]
TREE[无障碍树解析器
AccessibilityTree]
end
subgraph "工具层"
API[API安全调用
APISecCalls]
SANDBOX[Python沙箱执行]
BROWSER[浏览器控制]
end
subgraph "配置层"
CFG[配置解析器
Config]
TELE[遥测模块
Telemetry]
end
FE --> NAV
NAV --> RESP
NAV --> TREE
NAV --> API
NAV --> SANDBOX
NAV --> BROWSER
NAV --> CFG
NAV --> TELE
```
### 技术栈
| 组件 | 技术 | 说明 |
|------|------|------|
| 浏览器自动化 | Playwright | 跨浏览器自动化框架 |
| LLM 集成 | OpenAI/Anthropic/Azure/Portkey | 多模型支持 |
| 安全测试 | Nuclei | API 安全扫描工具 |
| 前端渲染 | CDP Stream | 实时浏览器画面流 |
| 沙箱执行 | Python Sandbox | 安全的脚本执行环境 |
资料来源：[testzeus_hercules/core/tools/api_sec_calls.py:1]()
资料来源：[testzeus_hercules/core/agents/executor_nav_agent.py:1]()
## 核心功能模块
### 1. 导航代理 (Navigation Agent)
导航代理是系统的核心决策单元，负责：
- 分析测试指令并规划执行步骤
- 调用浏览器工具执行用户交互
- 处理脚本执行和结果验证
- 管理错误恢复和重试逻辑
```mermaid
graph LR
A[接收测试指令] --> B[解析响应]
B --> C{执行判断}
C -->|脚本| D[执行Python脚本]
C -->|浏览器操作| E[CDP操作]
D --> F[处理结果]
E --> F
F --> G{继续?}
G -->|是| A
G -->|否| H[结束]
```
资料来源：[testzeus_hercules/core/agents/executor_nav_agent.py:1]()
### 2. 响应解析器 (Response Parser)
负责解析 LLM 返回的响应内容，支持多种格式：
- JSON 格式的标准响应
- Markdown 代码块包裹的 JSON
- 自然语言描述的错误信息
解析器会自动处理转义字符、格式规范化，并提供容错处理机制。 资料来源：[testzeus_hercules/utils/response_parser.py:1]()
### 3. 无障碍树解析器 (Accessibility Tree)
通过 CDP 协议获取 DOM 信息，构建页面的无障碍树结构，识别：
- 可交互元素（按钮、链接、表单控件）
- 可拖拽元素
- 内容可编辑区域
- ARIA 属性标记的元素
该模块会过滤掉非交互性元素（如纯装饰性元素），只保留用户可操作的对象。 资料来源：[testzeus_hercules/utils/get_detailed_accessibility_tree.py:1]()
### 4. CDP 渲染器
项目提供两种前端渲染模式：
#### 非交互式渲染器
用于展示浏览器画面流，适用于日志记录和测试回放。 资料来源：[frontend/non-interactive/index.html:1]()
#### 交互式渲染器
支持用户直接与远程页面进行交互，包括：
- 点击操作
- 拖拽操作
- 文本输入
```html
![Screencast will appear here]()
Click, drag, and type into the remote page here.
```
资料来源：[frontend/interactive/index.html:1]()
### 5. 遥测模块 (Telemetry)
负责收集和上报安装数据：
- 生成唯一的安装 ID
- 记录用户信息（可手动配置）
- 通过 Sentry SDK 进行错误追踪
```python
def get_installation_id(file_path: str = "installation_id.txt", is_manual_run: bool = True) -> Dict[str, Any]:
```
资料来源：[testzeus_hercules/telemetry.py:1]()
### 6. 安全测试工具
集成 Nuclei 扫描引擎，支持：
- OpenAPI 规范验证
- 漏洞扫描
- 自定义安全测试用例
```python
async def run_nuclei_command(
is_open_api_spec: bool,
open_api_spec_path: Optional[str],
target_url: Optional[str],
tag: str,
output_file: Path,
...
)
```
资料来源：[testzeus_hercules/core/tools/api_sec_calls.py:1]()
## 配置与命令行选项
### 基础配置
| 参数 | 类型 | 说明 |
|------|------|------|
| `--input-file` | str | 输入文件路径 |
| `--output-path` | str | 输出目录路径 |
| `--test-data-path` | str | 测试数据目录路径 |
| `--project-base` | str | 项目根目录路径 |
### LLM 配置
| 参数 | 类型 | 说明 |
|------|------|------|
| `--llm-model` | str | LLM 模型名称 |
| `--llm-model-api-key` | str | API 密钥 |
| `--llm-model-base-url` | str | API 基础 URL |
| `--llm-model-api-type` | str | API 类型 (openai/anthropic/azure) |
| `--llm-temperature` | float | 采样温度 (0.0-1.0) |
| `--agents-llm-config-file` | str | LLM 配置文件路径 |
| `--enable-portkey` | flag | 启用 Portkey 路由 |
| `--portkey-api-key` | str | Portkey API 密钥 |
| `--portkey-strategy` | str | 路由策略 (fallback/loadbalance) |
资料来源：[testzeus_hercules/config.py:1]()
### 浏览器配置
| 参数 | 类型 | 说明 |
|------|------|------|
| `--browser-channel` | str | 浏览器通道 (chrome-beta/firefox-nightly) |
| `--browser-path` | str | 自定义浏览器路径 |
| `--browser-version` | str | 指定浏览器版本 |
| `--enable-ublock` | flag | 启用 uBlock Origin |
| `--disable-ublock` | flag | 禁用 uBlock Origin |
| `--auto-accept-screen-sharing` | flag | 自动接受屏幕共享 |
### 测试执行选项
| 参数 | 类型 | 说明 |
|------|------|------|
| `--bulk` | flag | 批量执行 tests 目录下的测试 |
| `--reuse-vector-db` | flag | 复用现有向量数据库 |
### 沙箱配置
| 参数 | 类型 | 说明 |
|------|------|------|
| `--sandbox-tenant-id` | str | 沙箱租户 ID |
| `--sandbox-custom-injections` | str | 自定义注入脚本 |
## 批量执行模式
当启用 `--bulk` 参数时，系统会扫描项目根目录下的 `tests` 文件夹，并依次执行其中的测试用例：
```python
if get_global_conf().should_execute_bulk():
project_base = get_global_conf().get_project_source_root()
tests_dir = os.path.join(project_base, "tests")
if os.path.isdir(tests_dir) and os.listdir(tests_dir):
for test_folder in os.listdir(tests_dir):
test_dir = os.path.join(tests_dir, test_folder)
# 执行测试...
```
资料来源：[testzeus_hercules/__main__.py:1]()
## 测试用例生成工具
### API 功能性 Gherkin 测试生成器
位于 `helper_scripts/generate_api_functional_gherkin_test.py`，支持从 OpenAPI 规范自动生成 Gherkin 格式的测试用例。
```bash
python generate_api_functional_gherkin_test.py \
--model o1-preview \
--number_of_testcase 100 \
--output ./features \
openapi.yaml
```
参数说明：
- `input_files`: OpenAPI 规范文件路径 (YAML 或 JSON)
- `--output`: 输出目录
- `--model`: 使用的 LLM 模型 (默认: o1-preview)
- `--number_of_testcase`: 生成测试用例数量 (默认: 100)
资料来源：[helper_scripts/generate_api_functional_gherkin_test.py:1]()
### CDP 旅程脚本生成器
位于 `helper_scripts/cdp_journey_script.py`，根据用户旅程数据生成测试脚本：
- 支持导航、点击、输入等操作类型
- 自动将敏感数据参数化为占位符
- 生成 Gherkin 规格和测试数据文件
资料来源：[helper_scripts/cdp_journey_script.py:1]()
## 开发与贡献
### 项目设置
```bash
# 创建虚拟环境
make virtualenv
source .venv/bin/activate
# 安装开发模式
make install
# 格式化代码
make fmt
# 运行测试
make test
```
### 代码规范
- 使用 Black 进行代码格式化
- 使用 isort 进行导入排序
- 使用 Mypy 进行类型检查
- 遵循 Conventional Commits 规范提交信息
- 要求 100% 测试覆盖率
资料来源：[CONTRIBUTING.md:1]()
### 发布流程
项目使用语义化版本控制 (SemVer)，通过 Git tag 触发发布：
1. 创建并推送新标签
2. GitHub Actions 自动构建
3. 自动发布到 PyPI
需要配置 PyPI API Token 作为项目密钥。
资料来源：[CONTRIBUTING.md:1]()
## 快速开始
### 安装
```bash
# 通过 PyPI 安装
pip install testzeus-hercules
# 或通过 Docker
docker pull testzeus/hercules
```
### 基本使用
```bash
# 运行单个测试
hercules --input-file test.yaml --output-path ./results
# 使用指定 LLM
hercules --llm-model gpt-4 --llm-model-api-key $OPENAI_API_KEY
# 批量执行
hercules --bulk --project-base /path/to/project
# 启用安全扫描
hercules --enable-nuclei --target-url https://example.com
```
## 技术特点
| 特点 | 描述 |
|------|------|
| AI 驱动 | 基于 LLM 理解测试意图，自动生成执行策略 |
| 多模型支持 | 支持 OpenAI、Anthropic、Azure、Portkey 等 |
| 实时可视化 | CDP 流渲染，实时展示浏览器操作 |
| 安全沙箱 | Python 脚本隔离执行，防止恶意代码 |
| 批量执行 | 支持 tests 目录批量测试 |
| 安全扫描 | 集成 Nuclei 漏洞扫描 |
| 参数化测试 | 支持测试数据和参数化输入 |
| 开放标准 | 输出 Gherkin 格式，兼容 CI/CD |
---
## 系统架构
### 相关页面
相关主题：[多代理系统](#page-agent-system), [工具注册与工具集](#page-tool-registry), [记忆管理系统](#page-memory-management)
相关源码文件
以下源码文件用于生成本页说明：
- [testzeus_hercules/core/__init__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/__init__.py)
- [testzeus_hercules/core/simple_hercules.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)
- [testzeus_hercules/core/agents/executor_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/executor_nav_agent.py)
- [testzeus_hercules/core/tools/execute_python_sandbox.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/execute_python_sandbox.py)
- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)
- [testzeus_hercules/telemetry.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/telemetry.py)
# 系统架构
## 概述
Testzeus Hercules 是一个开源的端到端AI测试代理框架，其系统架构围绕浏览器自动化、AI代理协作和脚本执行三大核心能力构建。该框架采用模块化设计，通过动态加载机制和配置驱动的架构实现高度可扩展性。资料来源：[testzeus_hercules/core/__init__.py:1-20]()
## 核心架构分层
系统架构从上至下分为四个主要层次：
| 层级 | 名称 | 职责 |
|------|------|------|
| 接口层 | CLI/交互层 | 命令行参数解析、交互式界面提供 |
| 核心层 | Core Engine | AI代理编排、任务执行、流程控制 |
| 工具层 | Tools | 浏览器控制、API调用、沙箱执行 |
| 基础设施层 | Infrastructure | 配置管理、遥测、依赖管理 |
资料来源：[testzeus_hercules/core/simple_hercules.py:1-50]()
```mermaid
graph TD
A[CLI 接口] --> B[核心引擎]
B --> C[执行代理]
B --> D[导航代理]
C --> E[工具层]
D --> E
E --> F[浏览器自动化]
E --> G[API 安全调用]
E --> H[Python 沙箱]
F --> I[Playwright]
G --> J[外部服务]
H --> K[动态依赖注入]
```
## 核心组件详解
### 1. 配置管理系统
配置系统是整个框架的基础，采用单例模式通过 `get_global_conf()` 全局访问。配置支持命令行参数、环境变量和配置文件三种方式。资料来源：[testzeus_hercules/config.py:1-100]()
**主要配置类别：**
| 配置类别 | 参数 | 说明 |
|----------|------|------|
| LLM模型 | `--llm-model`, `--llm-model-api-key`, `--llm-model-base-url` | 大语言模型连接配置 |
| 浏览器控制 | `--browser-channel`, `--browser-path`, `--browser-version` | 浏览器实例配置 |
| 沙箱配置 | `--sandbox-tenant-id` | Python沙箱租户隔离 |
| Portkey集成 | `--enable-portkey`, `--portkey-api-key` | LLM路由和负载均衡 |
```mermaid
graph LR
A[命令行参数] --> B[ArgumentParser]
C[环境变量] --> B
D[配置文件] --> B
B --> E[GlobalConfig 单例]
E --> F[各模块访问]
```
### 2. 核心执行引擎
核心执行引擎位于 `testzeus_hercules/core/simple_hercules.py`，负责协调AI代理之间的通信和任务执行流程。该模块基于 AutoGen 多代理框架构建，支持代理间的消息传递和任务委派。资料来源：[testzeus_hercules/core/simple_hercules.py:1-80]()
**执行引擎关键流程：**
1. **计划阶段**：接收用户输入，生成执行计划
2. **分派阶段**：根据计划类型分派给相应代理
3. **执行阶段**：代理执行具体任务，调用工具层
4. **评估阶段**：验证执行结果，更新状态
```python
# 核心执行伪代码
def execute():
plan = generate_plan(input)
for step in plan:
if is_assert:
executor.assert_step(step)
else:
executor.execute_step(step)
notify_planner_messages(step)
```
### 3. 执行代理系统
执行代理是完成具体任务的工作单元，主要包括执行代理（Executor Agent）和导航代理（Navigation Agent）。资料来源：[testzeus_hercules/core/agents/executor_nav_agent.py:1-50]()
#### 3.1 执行代理职责
| 职责 | 描述 |
|------|------|
| 脚本执行 | 通过 `execute_python_sandbox` 执行Python脚本 |
| 验证断言 | 执行断言验证测试结果 |
| 错误处理 | 解析执行错误并做出响应 |
| 输出处理 | 提取和解析脚本执行结果 |
#### 3.2 执行代理工作流
```mermaid
graph TD
A[接收任务] --> B{任务类型判断}
B -->|脚本执行| C[选择脚本文件]
B -->|验证断言| D[构造断言脚本]
C --> E[调用execute_python_sandbox]
D --> E
E --> F{执行结果检查}
F -->|成功| G[解析JSON输出]
F -->|失败| H[记录错误信息]
G --> I[返回结果给调度器]
H --> I
```
### 4. Python沙箱执行系统
Python沙箱是框架的核心安全执行环境，允许AI代理动态执行Python代码而不会影响主系统。资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py:1-80]()
#### 4.1 沙箱注入机制
沙箱支持三类依赖注入：
| 注入类型 | 来源 | 示例 |
|----------|------|------|
| 租户注入 | 预配置的租户包 | `playwright`, `bs4`, `requests` |
| 配置注入 | `SANDBOX_PACKAGES` 配置项 | 用户自定义包 |
| 自定义注入 | `SANDBOX_CUSTOM_INJECTIONS` | 运行时动态指定 |
```python
# 租户注入逻辑
if tenant_id == "executor_agent":
injections['hercules_utils'] = utils
# 配置驱动注入
sandbox_packages = config.get("SANDBOX_PACKAGES", "").split(",")
```
#### 4.2 沙箱可用上下文
执行脚本自动获得以下上下文变量：
| 变量名 | 类型 | 说明 |
|--------|------|------|
| `page` | Playwright Page | 当前浏览器页面 |
| `browser` | Browser | 浏览器实例 |
| `context` | BrowserContext | 浏览器上下文 |
| `playwright_manager` | PlaywrightManager | Playwright管理器 |
| `logger` | Logger | 日志记录器 |
| `config` | GlobalConfig | 全局配置 |
### 5. 工具系统
工具系统通过动态导入机制加载，存储在 `testzeus_hercules/core/extra_tools/` 目录。资料来源：[testzeus_hercules/core/extra_tools/__init__.py:1-25]()
```python
# 动态工具加载
if get_global_conf().get_load_extra_tools().lower().strip() != "false":
for _, module_name, _ in pkgutil.iter_modules([str(package_path)]):
module = importlib.import_module(f"testzeus_hercules.core.extra_tools.{module_name}")
globals()[attribute_name] = getattr(module, attribute_name)
```
#### 主要内置工具
| 工具 | 功能 | 源码位置 |
|------|------|----------|
| `api_sec_calls` | 安全API调用，支持Nuclei扫描 | `core/tools/api_sec_calls.py` |
| `execute_python_sandbox` | Python沙箱执行 | `core/tools/execute_python_sandbox.py` |
| 浏览器控制工具 | 点击、输入、导航等 | Playwright集成 |
### 6. 响应解析系统
响应解析器位于 `testzeus_hercules/utils/response_parser.py`，负责解析AI代理返回的消息。资料来源：[testzeus_hercules/utils/response_parser.py:1-30]()
**解析流程：**
```mermaid
graph TD
A[接收LLM响应] --> B{检测JSON块}
B -->|```json| C[提取JSON内容]
B -->|```| D[移除代码块标记]
C --> E[JSON.loads解析]
D --> E
E --> F{解析成功?}
F -->|是| G[返回dict]
F -->|否| H[尝试关键字段提取]
H --> I[返回部分解析结果]
```
### 7. 遥测与监控
遥测系统使用Sentry进行错误跟踪和安装统计。资料来源：[testzeus_hercules/telemetry.py:1-50]()
```mermaid
graph LR
A[Sentry SDK] --> B[错误收集]
A --> C[安装ID生成]
C --> D[installation_id.txt]
B --> E[Sentry Dashboard]
```
**安装ID管理：**
- 自动生成UUID作为安装标识
- 支持手动模式下的用户邮箱收集
- 数据存储在 `installation_id.txt`
## 模块间交互
### 主执行流程
```mermaid
sequenceDiagram
participant User as 用户
participant CLI as 命令行接口
participant Engine as 核心引擎
participant Executor as 执行代理
participant Sandbox as Python沙箱
participant Browser as Playwright
User->>CLI: 启动命令
CLI->>Engine: 初始化配置
Engine->>Executor: 分派任务
Executor->>Sandbox: 执行脚本
Sandbox->>Browser: 浏览器操作
Browser-->>Sandbox: 操作结果
Sandbox-->>Executor: 脚本输出
Executor-->>Engine: 解析结果
Engine-->>User: 最终响应
```
### 消息通知机制
核心引擎使用 `notify_planner_messages` 函数向调度器报告执行状态：
```python
notify_planner_messages(
next_step,
message_type=MessageType.STEP,
stake_id=self.stake_id,
helper_name=target_helper,
is_assert=is_assert,
is_passed=is_passed,
assert_summary=assert_summary,
is_terminated=is_terminated,
is_completed=is_completed,
final_response=final_response,
)
```
## 配置参数总览
### 浏览器配置参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--browser-channel` | str | None | 浏览器渠道 (chrome-beta, firefox-nightly) |
| `--browser-path` | str | None | 自定义浏览器路径 |
| `--browser-version` | str | None | 指定浏览器版本 |
| `--enable-ublock` | flag | False | 启用uBlock扩展 |
| `--auto-accept-screen-sharing` | flag | False | 自动接受屏幕共享 |
### LLM配置参数
| 参数 | 类型 | 说明 |
|------|------|------|
| `--llm-model` | str | 模型名称 |
| `--llm-model-api-key` | str | API密钥 |
| `--llm-model-base-url` | str | API基础URL |
| `--llm-model-api-type` | str | API类型 (openai, anthropic, azure) |
| `--llm-temperature` | float | 采样温度 (0.0-1.0) |
| `--agents-llm-config-file` | str | LLM配置文件路径 |
### Portkey集成参数
| 参数 | 类型 | 可选值 | 说明 |
|------|------|--------|------|
| `--enable-portkey` | flag | - | 启用Portkey |
| `--portkey-api-key` | str | - | Portkey API密钥 |
| `--portkey-strategy` | str | fallback, loadbalance | 路由策略 |
## 架构设计原则
### 1. 配置驱动
所有功能通过配置参数控制，核心逻辑不包含硬编码值。配置系统支持多层级覆盖：命令行参数 > 环境变量 > 默认值。资料来源：[testzeus_hercules/config.py:20-80]()
### 2. 动态加载
工具系统和扩展功能采用动态导入机制，支持按需加载和运行时扩展。资料来源：[testzeus_hercules/core/extra_tools/__init__.py:10-20]()
### 3. 租户隔离
通过租户ID实现不同使用场景的依赖隔离，`executor_agent` 租户拥有预定义的工具集和上下文。
### 4. 安全沙箱
Python代码执行在受限的沙箱环境中，通过注入机制控制可用资源，防止恶意代码执行。
## 总结
Testzeus Hercules的系统架构采用分层设计，通过配置驱动和动态加载实现高度灵活性。核心引擎协调多个AI代理工作，工具层提供浏览器自动化和脚本执行能力，基础设施层保障配置的统一管理和遥测数据的收集。该架构支持从简单的端到端测试到复杂的多步骤业务流程验证。
---
## 多代理系统
### 相关页面
相关主题：[系统架构](#page-system-architecture), [工具注册与工具集](#page-tool-registry), [记忆管理系统](#page-memory-management)
相关源码文件
以下源码文件用于生成本页说明：
- [testzeus_hercules/core/simple_hercules.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)
- [testzeus_hercules/core/agents/executor_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/executor_nav_agent.py)
- [testzeus_hercules/__main__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/__main__.py)
- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)
- [testzeus_hercules/core/agents_llm_config_manager.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents_llm_config_manager.py)
- [testzeus_hercules/core/agents_llm_config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents_llm_config.py)
# 多代理系统
## 概述
TestZeus-Hercules 是一个开源的端到端 AI 测试代理框架，其核心架构基于**多代理系统（Multi-Agent System）**设计。该系统通过协调多个专门的 AI 代理来执行复杂的自动化测试任务，主要包括浏览器导航代理（BrowserNavAgent）、API 执行代理和高级规划代理等组件。
多代理系统的设计目标是：
- **分工协作**：将复杂的测试任务分解为多个子任务，由专门的代理负责执行
- **LLM 驱动**：每个代理由大语言模型驱动，具备独立的推理和决策能力
- **顺序执行**：通过用户代理（UserProxyAgent）协调多个代理之间的消息传递和任务调度
- **脚本执行**：通过 Python 沙箱环境执行自动化测试脚本，实现浏览器控制和 API 调用
资料来源：[testzeus_hercules/core/simple_hercules.py:1-50]()
## 系统架构
### 整体架构图
```mermaid
graph TD
subgraph 用户层
User[用户/CLI]
end
subgraph 核心编排层
Hercules[TestZeus Hercules 主类]
UserProxy[UserProxyAgent
用户代理]
end
subgraph 代理层
PlannerAgent[高级规划代理
HighLevelPlannerAgent]
BrowserNavAgent[浏览器导航代理
BrowserNavAgent]
ExecutorAgent[执行代理
ExecutorAgent]
ApiNavAgent[API导航代理
ApiNavAgent]
end
subgraph 工具层
Playwright[Playwright管理器]
PythonSandbox[Python沙箱]
Nuclei[安全扫描工具]
end
User --> Hercules
Hercules --> UserProxy
UserProxy --> PlannerAgent
UserProxy --> BrowserNavAgent
UserProxy --> ExecutorAgent
UserProxy --> ApiNavAgent
BrowserNavAgent --> Playwright
ExecutorAgent --> PythonSandbox
ApiNavAgent --> Nuclei
```
### 代理类型说明
| 代理类型 | 类名 | 职责 | LLM配置 |
|---------|------|------|---------|
| 高级规划代理 | HighLevelPlannerAgent | 分析测试需求，生成执行计划 | 独立LLM配置 |
| 浏览器导航代理 | BrowserNavAgent | 控制浏览器执行UI测试 | 独立LLM配置 |
| 执行代理 | ExecutorAgent | 执行Python测试脚本 | 共享或独立配置 |
| API导航代理 | ApiNavAgent | 执行API测试和安全扫描 | 独立LLM配置 |
资料来源：[testzeus_hercules/core/simple_hercules.py:80-150]()
## 代理创建流程
### 主类初始化
`TestZeusHercules` 主类负责初始化所有代理实例。初始化过程遵循以下步骤：
```python
class TestZeusHercules:
def __init__(self, config: HerculesConfig):
self.config = config
self._init_agents()
```
### 代理工厂模式
系统采用工厂模式创建代理，每个代理都有独立的创建方法：
```python
def __create_browser_nav_executor_agent(self) -> autogen.UserProxyAgent:
"""创建浏览器导航执行代理"""
browser_nav_executor_agent = UserProxyAgent_SequentialFunctionExecution(
name="browser_nav_executor",
is_termination_msg=is_browser_nav_termination_msg,
max_consecutive_auto_reply=self.nav_agent_number_of_rounds,
code_execution_config={...}
)
def __create_browser_nav_agent(self, user_proxy_agent) -> autogen.ConversableAgent:
"""创建浏览器导航代理"""
browser_nav_agent = BrowserNavAgent(
self.browser_nav_agent_model_config,
self.nav_agent_config["llm_config_params"],
self.nav_agent_config.get("other_settings", {}).get("system_prompt"),
user_proxy_agent,
)
return browser_nav_agent.agent
```
资料来源：[testzeus_hercules/core/simple_hercules.py:150-200]()
## LLM 配置管理
### 多模型配置支持
系统支持为不同代理配置不同的 LLM 模型，提供灵活的架构设计：
```python
# config.py 中的 LLM 配置参数
--llm-model # LLM 模型名称
--llm-model-api-key # API密钥
--llm-model-base-url # API基础URL
--llm-model-api-type # API类型 (openai, anthropic, azure等)
--llm-temperature # 采样温度 (0.0-1.0)
```
### 配置文件机制
系统支持通过配置文件管理代理的 LLM 设置：
```python
--agents-llm-config-file # 代理LLM配置文件路径
--agents-llm-config-file-ref-key # 配置文件引用键
```
### Portkey 集成
支持通过 Portkey 进行 LLM 路由和负载均衡：
```bash
--enable-portkey # 启用Portkey集成
--portkey-api-key # Portkey API密钥
--portkey-strategy # 路由策略: fallback 或 loadbalance
```
资料来源：[testzeus_hercules/config.py:50-100]()
## 代理通信机制
### 消息传递模式
代理之间通过消息传递进行协作，采用以下模式：
```mermaid
sequenceDiagram
participant User as 用户代理
participant Planner as 规划代理
participant Browser as 浏览器导航代理
participant Executor as 执行代理
User->>Planner: 发送测试需求
Planner->>User: 返回执行计划
User->>Browser: 分发浏览器任务
Browser->>User: 返回执行结果
User->>Executor: 分发脚本执行任务
Executor->>User: 返回执行结果
```
### 终止条件判断
每个代理都有独立的终止消息判断逻辑：
```python
def is_api_executor_termination_message(x: dict[str, str]) -> bool:
"""API执行代理终止条件"""
tools_call = x.get("tool_calls", "")
if tools_call:
# 分析工具调用结果
chat_messages = self.agents_map["api_nav_executor"].chat_messages
agent_key = next(iter(chat_messages))
# 判断是否应终止
```
资料来源：[testzeus_hercules/core/simple_hercules.py:200-250]()
## 执行代理工作流
### 脚本执行流程
执行代理（ExecutorAgent）负责在 Python 沙箱中执行测试脚本：
```mermaid
graph TD
A[接收任务指令] --> B[选择脚本文件]
B --> C[识别目标函数]
C --> D[准备执行参数]
D --> E[调用沙箱执行]
E --> F{执行结果检查}
F -->|成功| G[解析输出结果]
F -->|失败| H[错误处理]
G --> I[返回结果给用户代理]
H --> I
```
### 执行配置
```python
code_execution_config = {
"last_n_messages": 1, # 包含最近N条消息
"work_dir": "tasks", # 工作目录
"use_docker": False, # 是否使用Docker
}
```
### 自动上下文注入
脚本执行时自动注入以下上下文变量：
- `page` - Playwright 页面对象
- `browser` - 浏览器实例
- `context` - 浏览器上下文
- `playwright_manager` - Playwright 管理器
- `logger` - 日志记录器
- `config` - 配置对象
资料来源：[testzeus_hercules/core/agents/executor_nav_agent.py:1-50]()
## 浏览器导航代理
### 功能职责
BrowserNavAgent 是系统的核心代理之一，负责：
1. **页面导航**：打开指定 URL 的网页
2. **元素交互**：点击、输入、悬停等用户操作
3. **内容提取**：获取页面文本、元素属性等信息
4. **状态验证**：检查页面元素状态和内容
### 执行模式
```python
# 顺序函数执行模式
browser_nav_executor_agent = UserProxyAgent_SequentialFunctionExecution(
name="browser_nav_executor",
max_consecutive_auto_reply=self.nav_agent_number_of_rounds,
code_execution_config={...}
)
```
### 响应解析
系统提供专门的响应解析器处理 LLM 返回的 JSON 响应：
```python
def parse_response(message: str) -> dict[str, Any]:
"""解析浏览器代理响应"""
# 处理 ```json ``` 代码块
# 解析 JSON 数据
# 处理解析失败情况
```
资料来源：[testzeus_hercules/utils/response_parser.py:1-40]()
## 批量执行模式
### 目录扫描
系统支持批量执行测试目录中的所有测试用例：
```mermaid
graph LR
A[tests/ 目录] --> B[扫描子文件夹]
B --> C[遍历测试文件夹]
C --> D[逐个执行测试]
D --> E{是否完成}
E -->|否| C
E -->|是| F[汇总报告]
```
### 执行触发条件
```python
if get_global_conf().should_execute_bulk():
project_base = get_global_conf().get_project_source_root()
tests_dir = os.path.join(project_base, "tests")
if os.path.isdir(tests_dir) and os.listdir(tests_dir):
for test_folder in os.listdir(tests_dir):
# 执行每个测试文件夹
```
资料来源：[testzeus_hercules/__main__.py:100-150]()
## 配置选项汇总
### 命令行参数
| 参数 | 类型 | 说明 |
|------|------|------|
| `--bulk` | flag | 批量执行测试目录 |
| `--reuse-vector-db` | flag | 复用现有向量数据库 |
| `--browser-channel` | str | 浏览器通道 (chrome-beta, firefox-nightly) |
| `--browser-path` | str | 自定义浏览器路径 |
| `--browser-version` | str | 浏览器版本 |
| `--enable-ublock` | flag | 启用 uBlock Origin |
| `--sandbox-tenant-id` | str | Python 沙箱租户ID |
资料来源：[testzeus_hercules/config.py:100-150]()
## 代理注册机制
### 代理映射
系统维护一个代理注册表，用于追踪所有活跃的代理实例：
```python
self.agents_map = {
"browser_nav_executor": browser_nav_executor_agent,
"browser_nav": browser_nav_agent,
"api_nav_executor": api_nav_executor_agent,
"api_nav": api_nav_agent,
}
```
### 访问模式
通过代理名称字符串访问对应的代理实例：
```python
chat_messages = self.agents_map["api_nav_executor"].chat_messages
agent_key = next(iter(chat_messages))
```
## 最佳实践
### 代理配置建议
1. **模型选择**：为不同复杂度的任务选择合适的模型
2. **温度参数**：规划代理使用较低温度保证稳定性，执行代理可适当提高
3. **上下文窗口**：合理设置 `last_n_messages` 控制上下文长度
### 错误处理
- 每个代理应独立处理错误，避免级联失败
- 使用日志记录关键决策点
- 提供清晰的错误消息便于调试
### 性能优化
- 批量执行时注意资源限制
- 合理复用向量数据库
- 使用浏览器通道加速启动
## 总结
TestZeus-Hercules 的多代理系统通过模块化的设计实现了灵活的自动化测试能力。每个代理专注于特定任务领域，通过标准化的消息传递机制协调工作。系统支持多种 LLM 配置选项，可以根据不同场景灵活部署。
核心优势包括：
- **可扩展性**：易于添加新的代理类型
- **灵活性**：支持多种 LLM 提供商和配置
- **可靠性**：完善的错误处理和日志机制
- **自动化**：从任务规划到执行的全流程自动化
---
## 工具注册与工具集
### 相关页面
相关主题：[多代理系统](#page-agent-system), [Playwright 浏览器自动化](#page-playwright-automation), [Python 沙箱执行](#page-python-sandbox)
相关源码文件
以下源码文件用于生成本页说明：
- [testzeus_hercules/core/tools/__init__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/__init__.py)
- [testzeus_hercules/core/extra_tools/__init__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/extra_tools/__init__.py)
- [testzeus_hercules/core/agents/executor_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/executor_nav_agent.py)
- [testzeus_hercules/core/tools/execute_python_sandbox.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/execute_python_sandbox.py)
- [testzeus_hercules/core/tools/api_sec_calls.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/api_sec_calls.py)
- [testzeus_hercules/utils/response_parser.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/response_parser.py)
- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)
# 工具注册与工具集
## 概述
工具注册与工具集是 Testzeus Hercules 自动化测试框架的核心组件，负责管理和加载所有可用的测试工具。这些工具通过动态导入机制注册到系统中，使 AI Agent 能够执行各种浏览器操作、API 调用、安全扫描等任务。
工具系统的设计遵循模块化原则，每个工具都是独立的功能单元，通过统一的注册机制暴露给上层调用者。框架使用 `pkgutil` 动态发现和导入所有工具模块，无需手动维护导入列表。资料来源：[testzeus_hercules/core/tools/__init__.py:1-17]()
## 工具注册机制
### 动态模块发现
工具注册采用 Python 的 `pkgutil` 模块实现动态发现。系统会扫描 `testzeus_hercules.core.tools` 包目录，自动识别并加载所有非私有模块。这种设计使得添加新工具变得简单——只需在 tools 目录下创建新的 Python 文件，框架会自动将其纳入工具集。
```python
# 伪代码展示核心逻辑
for _, module_name, _ in pkgutil.iter_modules([str(package_path)]):
full_module_name = f"testzeus_hercules.core.tools.{module_name}"
module = importlib.import_module(full_module_name)
```
资料来源：[testzeus_hercules/core/tools/__init__.py:13-16]()
### 注册流程
```mermaid
graph TD
A[启动工具加载] --> B[扫描 tools 目录]
B --> C{目录可访问?}
C -->|是| D[使用 pkgutil.iter_modules 扫描]
C -->|否| E[跳过该目录]
D --> F[发现模块]
F --> G[构造完整模块路径]
G --> H[使用 importlib 动态导入]
H --> I[遍历模块属性]
I --> J{属性以 _ 开头?}
J -->|是| K[跳过私有属性]
J -->|否| L[添加到全局命名空间]
L --> M[继续处理下一模块]
K --> M
M --> N[所有模块处理完成]
```
### 工具属性过滤规则
在导入每个模块时，系统会遍历模块的所有属性，并按照特定规则进行过滤：
| 过滤条件 | 处理方式 | 说明 |
|---------|---------|------|
| 以单下划线 `_` 开头 | 跳过 | 不导入私有属性 |
| 以双下划线 `__` 开头 | 跳过 | 不导入 dunder 属性 |
| 其他属性 | 导入 | 添加到当前命名空间 |
资料来源：[testzeus_hercules/core/tools/__init__.py:17-18]()
## 核心工具集
### 浏览器操作工具
浏览器操作工具集提供页面导航、元素交互等核心功能。
| 工具名称 | 功能描述 | 关键参数 |
|---------|---------|---------|
| `open_url` | 打开指定 URL | url, timeout |
| `click_using_selector` | 使用选择器点击元素 | selector, offset_x, offset_y |
| `enter_text_using_selector` | 使用选择器输入文本 | selector, text |
| `accessibility_calls` | 获取页面无障碍信息 | - |
资料来源：[testzeus_hercules/core/tools/open_url.py](), [testzeus_hercules/core/tools/click_using_selector.py](), [testzeus_hercules/core/tools/enter_text_using_selector.py](), [testzeus_hercules/core/tools/accessibility_calls.py]()
### API 调用工具
API 调用工具支持与后端服务交互和安全扫描。
| 工具类别 | 子工具 | 功能 |
|---------|-------|------|
| REST API | `api_calls` | 发送 HTTP 请求 |
| 安全扫描 | `api_sec_calls` | 使用 Nuclei 进行漏洞扫描 |
| 响应解析 | `response_parser` | 解析 LLM 返回的 JSON 响应 |
资料来源：[testzeus_hercules/core/tools/api_calls.py](), [testzeus_hercules/core/tools/api_sec_calls.py](), [testzeus_hercules/utils/response_parser.py]()
### 沙箱执行工具
`execute_python_sandbox` 是框架中功能最强大的工具之一，允许在受控环境中执行 Python 代码脚本。
```mermaid
graph TD
A[execute_python_sandbox 调用] --> B[获取配置信息]
B --> C[检查租户 ID]
C --> D{租户特定模块?}
D -->|是| E[注入 hercules_utils]
D -->|否| F[跳过租户注入]
E --> G[应用配置驱动注入]
F --> G
G --> H[解析自定义注入 JSON]
H --> I[构建脚本执行上下文]
I --> J[执行 Python 脚本]
J --> K[返回执行结果]
```
资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py](), [testzeus_hercules/core/agents/executor_nav_agent.py:1-50]()
## 扩展工具集
### 条件加载机制
扩展工具集位于 `testzeus_hercules.core.extra_tools` 包，采用条件加载机制。系统会检查全局配置中的 `load_extra_tools` 选项，仅当其值不为 `"false"` 时才加载扩展工具。
```python
if get_global_conf().get_load_extra_tools().lower().strip() != "false":
# 执行扩展工具加载
```
资料来源：[testzeus_hercules/core/extra_tools/__init__.py:13-15]()
### 配置驱动的包注入
沙箱环境支持通过配置文件动态注入 Python 包，允许在运行时扩展可用的模块范围。
```python
sandbox_packages = config.get_config().get("SANDBOX_PACKAGES", "").split(",")
for package_name in sandbox_packages:
if package_name:
injections[package_name] = __import__(package_name)
```
资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py:50-60]()
| 配置项 | 类型 | 说明 | 示例 |
|-------|------|------|------|
| `SANDBOX_PACKAGES` | 字符串 | 逗号分隔的包名列表 | `requests,pandas,numpy` |
| `SANDBOX_TENANT_ID` | 字符串 | 租户标识符 | `executor_agent` |
| `SANDBOX_CUSTOM_INJECTIONS` | JSON 字符串 | 自定义模块注入配置 | `{"my_module": "path"}` |
## 工具执行上下文
### 脚本执行环境
在 `execute_python_sandbox` 工具中执行的 Python 脚本会自动获得以下内置对象的访问权限：
| 上下文对象 | 用途 |
|-----------|------|
| `page` | Playwright 页面对象 |
| `browser` | Playwright 浏览器实例 |
| `context` | Playwright 浏览器上下文 |
| `playwright_manager` | Playwright 管理器 |
| `logger` | 日志记录器 |
| `config` | 全局配置对象 |
资料来源：[testzeus_hercules/core/agents/executor_nav_agent.py:10-14]()
### 脚本执行约束
框架对脚本执行有明确的约束和规范：
1. **顺序执行** - 一次只执行一个脚本或函数，等待结果后再继续下一步
2. **结果验证** - 必须验证每个脚本的执行结果，检查执行状态
3. **错误处理** - 适当处理执行错误、超时和异常
4. **参数准确性** - 提供正确的文件路径和超时值
资料来源：[testzeus_hercules/core/agents/executor_nav_agent.py:20-40]()
## 工具调用示例
### 基本调用模式
```python
# 1. 直接调用已注册的全局工具
result = execute_python_sandbox(
script_path="scripts/my_test.py",
function_name="test_login",
function_args={"username": "test", "password": "pass"},
timeout=30
)
# 2. 使用 open_url 打开页面
result = open_url("https://example.com")
# 3. 使用选择器交互
result = click_using_selector(
selector="#login-button",
offset_x=0,
offset_y=0
)
```
### 配置注入调用
```python
# 使用自定义注入执行脚本
result = execute_python_sandbox(
script_path="scripts/data_analysis.py",
custom_injections_json='{"pandas": "pandas", "numpy": "numpy"}'
)
```
## 响应解析
框架提供统一的响应解析机制处理 LLM 返回的结果：
```mermaid
graph TD
A[接收 LLM 响应] --> B{响应包含 ```json?}
B -->|是| C[提取 json 代码块内容]
B -->|否| D[移除 ``` 标记]
D --> E[移除 json 前缀]
C --> F[去除转义字符]
E --> F
F --> G[JSON 解析]
G --> H{解析成功?}
H -->|是| I[返回解析结果]
H -->|否| J[尝试提取 plan 和 next_step]
J --> K[返回部分解析结果]
```
资料来源：[testzeus_hercules/utils/response_parser.py:1-35]()
## 配置与初始化
### 全局配置检查点
工具系统在初始化时会检查多个配置选项：
| 配置项 | 来源 | 用途 |
|-------|------|------|
| `load_extra_tools` | 全局配置 | 控制扩展工具加载 |
| `SANDBOX_PACKAGES` | 环境变量/配置 | 沙箱包注入 |
| `SANDBOX_TENANT_ID` | 环境变量/配置 | 租户特定行为 |
| `enable-portkey` | 命令行参数 | 启用 Portkey 路由 |
| `llm-model` | 命令行参数 | LLM 模型选择 |
资料来源：[testzeus_hercules/config.py:1-100](), [testzeus_hercules/core/extra_tools/__init__.py]()
## 最佳实践
### 添加工具模块
在 Testzeus Hercules 中添加新工具的推荐步骤：
1. 在 `testzeus_hercules/core/tools/` 目录下创建新的 Python 文件
2. 命名遵循 `snake_case` 命名规范
3. 避免在模块级别使用私有属性（以 `_` 开头的属性不会被自动导入）
4. 确保工具函数有清晰的文档字符串
### 工具开发规范
```python
"""
工具模块示例
"""
def my_tool(param1: str, param2: int) -> dict:
"""
工具功能描述
Args:
param1: 参数1说明
param2: 参数2说明
Returns:
dict: 返回值说明
"""
# 实现逻辑
return {"status": "success"}
```
## 总结
工具注册与工具集系统为 Testzeus Hercules 提供了高度可扩展的架构。动态模块发现机制使得添加新工具变得简单，无需修改导入代码；条件加载机制允许灵活控制工具集的规模；沙箱执行环境则提供了安全的脚本执行能力。这些设计使得框架能够适应各种复杂的端到端测试场景。
---
## 记忆管理系统
### 相关页面
相关主题：[多代理系统](#page-agent-system), [系统架构](#page-system-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [testzeus_hercules/core/memory/__init__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/__init__.py)
- [testzeus_hercules/core/memory/dynamic_ltm.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/dynamic_ltm.py)
- [testzeus_hercules/core/memory/static_ltm.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/static_ltm.py)
- [testzeus_hercules/core/memory/state_handler.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/state_handler.py)
- [testzeus_hercules/core/memory/prompt_compressor.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/prompt_compressor.py)
- [testzeus_hercules/core/memory/static_data_loader.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/static_data_loader.py)
# 记忆管理系统
## 概述
记忆管理系统（Memory Management System）是TestZeus Hercules的核心组件，负责管理和维护AI代理在测试执行过程中的上下文信息、长期记忆和状态数据。该系统通过整合静态数据和动态数据，为代理提供持续一致的测试环境感知能力。
记忆管理系统的主要职责包括：
- 加载和管理项目级静态数据（如测试数据文件、配置信息）
- 维护运行时的动态上下文状态
- 提供检索增强生成（RAG）能力，支持向量数据库查询
- 在测试执行过程中存储和恢复中间状态
- 压缩和优化提示内容以适应上下文窗口限制
资料来源：[testzeus_hercules/core/memory/static_ltm.py:1-20](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/static_ltm.py)
---
## 系统架构
### 组件层次结构
记忆管理系统由多个相互协作的模块组成，形成了清晰的分层架构：
```mermaid
graph TD
A[记忆管理系统] --> B[静态长期记忆 StaticLTM]
A --> C[动态长期记忆 DynamicLTM]
A --> D[状态处理器 StateHandler]
A --> E[提示压缩器 PromptCompressor]
B --> F[静态数据加载器]
C --> G[RetrieveUserProxyAgent]
D --> H[状态存储]
E --> I[上下文优化]
F --> J[test_data.txt]
F --> K[test_data_path 目录]
```
### 核心组件职责
| 组件 | 类型 | 主要功能 |
|------|------|----------|
| StaticLTM | 单例类 | 加载和管理静态测试数据 |
| DynamicLTM | 类 | 提供基于RAG的动态记忆检索 |
| StateHandler | 模块 | 管理运行时的键值状态存储 |
| PromptCompressor | 模块 | 压缩提示内容以适应上下文限制 |
| StaticDataLoader | 模块 | 从文件系统加载测试数据 |
资料来源：[testzeus_hercules/core/memory/static_ltm.py:21-36](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/static_ltm.py)
---
## 静态长期记忆（StaticLTM）
### 概述
StaticLTM是静态长期记忆的实现，采用单例模式确保全局只有一个实例。它负责从文件系统加载测试数据，并将加载的数据与运行时的状态信息整合，为AI代理提供统一的静态上下文视图。
资料来源：[testzeus_hercules/core/memory/static_ltm.py:21-30](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/static_ltm.py)
### 初始化流程
```python
def _initialize(self) -> None:
"""Initialize the StaticLTM instance by loading data."""
result = load_data()
stored_data = get_stored_data()
run_data = get_run_data()
if stored_data:
result += "\nStored Data:" + stored_data
if run_data:
result += f"\nprevious_context_data: {run_data}"
self.consolidated_data: str = result
```
初始化过程中，StaticLTM执行以下操作：
1. 调用`load_data()`加载测试数据文件内容
2. 通过`get_stored_data()`获取持久化存储的数据
3. 通过`get_run_data()`获取当前运行会话的数据
4. 将所有数据整合到`consolidated_data`属性中
资料来源：[testzeus_hercules/core/memory/static_ltm.py:31-44](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/static_ltm.py)
### 对外接口
```python
def get_user_ltm(self) -> Optional[str]:
"""
获取存储在test_data.txt文件中的测试数据。
Returns:
Optional[str]: 测试数据内容，如不存在则返回None
"""
return self.consolidated_data
```
该接口以字符串形式返回整合后的所有静态数据，包括原始测试数据和运行时上下文信息。
资料来源：[testzeus_hercules/core/memory/static_ltm.py:46-56](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/static_ltm.py)
### 便捷函数
```python
def get_user_ltm() -> Optional[str]:
"""获取用户长期记忆的便捷函数"""
return StaticLTM().get_user_ltm()
```
通过模块级函数提供对单例实例的直接访问，简化调用方的代码。
资料来源：[testzeus_hercules/core/memory/static_ltm.py:59-66](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/static_ltm.py)
---
## 动态长期记忆（DynamicLTM）
### 概述
DynamicLTM负责管理动态长期记忆，它基于Autogen框架的`RetrieveUserProxyAgent`实现检索增强生成能力。与StaticLTM的静态数据不同，DynamicLTM支持向量数据库检索，能够在运行时动态查询相关的上下文信息。
资料来源：[testzeus_hercules/core/memory/dynamic_ltm.py:1-25](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/dynamic_ltm.py)
### 组件架构
```mermaid
graph TD
A[DynamicLTM] --> B[SilentRetrieveUserProxyAgent]
B --> C[suppress_prints 装饰器]
B --> D[RetrieveUserProxyAgent]
D --> E[initiate_chat]
D --> F[a_initiate_chat]
G[自动抑制输出方法] --> E
G --> F
```
DynamicLTM通过继承`RetrieveUserProxyAgent`获得RAG能力，同时使用自定义的`SilentRetrieveUserProxyAgent`子类来抑制框架的打印输出。
资料来源：[testzeus_hercules/core/memory/dynamic_ltm.py:27-46](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/dynamic_ltm.py)
### 输出抑制机制
系统使用装饰器模式实现打印输出的全局抑制：
```python
def suppress_prints(func):
"""装饰器，用于抑制函数内部的打印语句"""
@functools.wraps(func)
def wrapper(*args, **kwargs):
silent_stdout = io.StringIO()
original_stdout, sys.stdout = sys.stdout, silent_stdout
try:
return func(*args, **kwargs)
finally:
sys.stdout = original_stdout
return wrapper
```
被装饰的方法包括：
- `initiate_chat()` - 同步发起聊天
- `a_initiate_chat()` - 异步发起聊天
资料来源：[testzeus_hercules/core/memory/dynamic_ltm.py:17-42](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/dynamic_ltm.py)
### SilentRetrieveUserProxyAgent实现
```python
class SilentRetrieveUserProxyAgent(RetrieveUserProxyAgent):
"""派生类，用于抑制嘈杂方法中的打印输出"""
@suppress_prints
def initiate_chat(self, *args: Any, **kwargs: Any) -> Any:
return super().initiate_chat(*args, **kwargs)
@suppress_prints
async def a_initiate_chat(self, *args: Any, **kwargs: Any) -> Any:
return await super().a_initiate_chat(*args, **kwargs)
```
通过重写父类方法并应用`@suppress_prints`装饰器，确保RAG检索过程中的中间输出不会干扰测试日志。
资料来源：[testzeus_hercules/core/memory/dynamic_ltm.py:44-55](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/dynamic_ltm.py)
---
## 状态处理器（StateHandler）
### 概述
StateHandler模块负责管理运行时的键值状态存储，提供数据持久化和跨会话状态恢复能力。它与StaticLTM紧密协作，将运行时的中间数据与静态测试数据整合。
资料来源：[testzeus_hercules/core/memory/state_handler.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/state_handler.py)
### 核心功能
| 功能 | 说明 |
|------|------|
| `store_run_data()` | 存储当前运行会话的数据 |
| `get_run_data()` | 获取之前运行会话的数据 |
| `get_stored_data()` | 获取持久化存储的数据 |
这些函数构成状态管理的基本API，支持数据的写入、读取和持久化操作。
资料来源：[testzeus_hercules/core/memory/state_handler.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/state_handler.py)
### 数据整合流程
```mermaid
sequenceDiagram
participant S1 as StateHandler
participant SDL as StaticDataLoader
participant SLTM as StaticLTM
S1->>S1: store_run_data()
S1->>S1: get_stored_data()
S1->>S1: get_run_data()
SLTM->>SDL: load_data()
SLTM->>S1: get_stored_data()
SLTM->>S1: get_run_data()
Note over SLTM: 整合为consolidated_data
```
StaticLTM在初始化时调用StateHandler的各个接口，将运行时状态与静态数据合并，形成完整的上下文环境。
资料来源：[testzeus_hercules/core/memory/static_ltm.py:31-44](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/static_ltm.py)
---
## 静态数据加载器（StaticDataLoader）
### 概述
StaticDataLoader负责从文件系统加载测试数据文件，是记忆管理系统的数据入口点。它支持从多个来源加载数据，包括指定的测试数据目录和配置文件。
资料来源：[testzeus_hercules/core/memory/static_data_loader.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/static_data_loader.py)
### 主要函数
| 函数 | 返回类型 | 功能描述 |
|------|----------|----------|
| `load_data()` | str | 加载所有测试数据文件内容 |
| `get_test_data_file_paths()` | list | 获取测试数据文件路径列表 |
| `list_load_data()` | list | 列出加载的数据项 |
`get_test_data_file_paths()`函数用于获取项目中所有测试数据文件的路径，为批量加载提供支持。
资料来源：[testzeus_hercules/core/memory/static_data_loader.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/static_data_loader.py)
### 数据来源
测试数据可以从以下位置加载：
- 项目根目录的`test_data.txt`文件
- 通过`--test-data-path`参数指定的目录
- 配置中定义的其他数据源路径
加载器会递归扫描指定目录，收集所有符合格式的测试数据文件。
资料来源：[testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)
---
## 提示压缩器（PromptCompressor）
### 概述
PromptCompressor负责优化和压缩提示内容，确保发送给大语言模型的消息不超过上下文窗口限制。这是记忆管理系统中至关重要的一个组件，因为测试代理需要处理大量上下文信息。
资料来源：[testzeus_hercules/core/memory/prompt_compressor.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/prompt_compressor.py)
### 压缩策略
提示压缩器采用多种策略来减少上下文长度：
1. **语义摘要** - 识别并移除冗余信息
2. **上下文截断** - 在达到限制时保留关键信息
3. **结构优化** - 重组提示结构以提高信息密度
### 使用场景
在以下场景中会触发提示压缩：
- 发送聊天消息前检查上下文长度
- 加载大量静态数据后
- 多轮对话累积大量历史消息时
资料来源：[testzeus_hercules/core/memory/prompt_compressor.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/prompt_compressor.py)
---
## 模块初始化（__init__.py）
### 动态导入机制
记忆管理系统的`__init__.py`使用Python的动态导入机制，支持按需加载额外工具模块：
```python
import importlib
import pkgutil
from pathlib import Path
package_path = Path(__file__).parent
if get_global_conf().get_load_extra_tools().lower().strip() != "false":
for _, module_name, _ in pkgutil.iter_modules([str(package_path)]):
full_module_name = f"testzeus_hercules.core.memory.{module_name}"
module = importlib.import_module(full_module_name)
for attribute_name in dir(module):
if not attribute_name.startswith("_"):
globals()[attribute_name] = getattr(module, attribute_name)
```
资料来源：[testzeus_hercules/core/memory/__init__.py:1-22](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/__init__.py)
### 导入配置
动态导入可通过全局配置控制：
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `load_extra_tools` | 非"false" | 设为"false"时禁用动态导入 |
当配置为"false"时，系统跳过额外的工具模块导入，减少内存占用和启动时间。
资料来源：[testzeus_hercules/core/memory/__init__.py:8](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/__init__.py)
---
## 数据流与集成
### 与其他系统的集成
记忆管理系统与TestZeus Hercules的核心执行流程深度集成：
```mermaid
graph LR
A[Hercules Core] --> B[StaticLTM]
A --> C[DynamicLTM]
A --> D[StateHandler]
B --> E[测试数据]
C --> F[向量数据库]
D --> G[持久化存储]
H[LLM Agent] --> I[上下文输入]
B --> I
C --> I
D --> I
```
AI代理在执行测试时，会接收来自记忆管理系统的综合上下文信息，包括静态测试数据、动态检索结果和运行时状态。
资料来源：[testzeus_hercules/core/simple_hercules.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)
### 上下文构建过程
```
┌─────────────────────────────────────────────────────────────┐
│ 上下文构建流程 │
├─────────────────────────────────────────────────────────────┤
│ 1. StaticLTM 初始化 │
│ ├── load_data() → 加载 test_data.txt │
│ ├── get_stored_data() → 获取持久化数据 │
│ └── get_run_data() → 获取运行数据 │
│ │
│ 2. 数据整合 │
│ └── consolidated_data = 静态数据 + 存储数据 + 运行数据 │
│ │
│ 3. 动态检索（可选） │
│ └── DynamicLTM 查询向量数据库 │
│ │
│ 4. 提示优化 │
│ └── PromptCompressor 压缩上下文 │
│ │
│ 5. 上下文传递给 LLM Agent │
└─────────────────────────────────────────────────────────────┘
```
资料来源：[testzeus_hercules/core/memory/static_ltm.py:31-44](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/static_ltm.py)
---
## 配置参数
### 记忆系统相关配置
| 参数 | 类型 | 说明 | 来源 |
|------|------|------|------|
| `--test-data-path` | str | 测试数据目录路径 | config.py |
| `--reuse-vector-db` | bool | 复用现有向量数据库 | config.py |
| `load_extra_tools` | str | 是否加载额外工具（"false"禁用） | __init__.py |
### 状态存储配置
| 配置项 | 说明 |
|--------|------|
| `installation_id.txt` | 安装标识符存储文件 |
| `user_email` | 用户邮箱（手动运行时提示输入） |
资料来源：[testzeus_hercules/telemetry.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/telemetry.py)
---
## 最佳实践
### 数据组织建议
1. **测试数据文件**：将测试数据组织在`test_data.txt`或`test_data/`目录中
2. **命名规范**：使用清晰的数据描述性名称，便于RAG检索
3. **格式选择**：推荐使用YAML或JSON格式的结构化数据
### 性能优化
1. **向量数据库复用**：使用`--reuse-vector-db`参数避免重复构建索引
2. **按需加载**：将`load_extra_tools`设为"false"以减少启动开销
3. **数据分区**：大型测试数据按功能模块分区存储
### 故障排查
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 记忆数据未加载 | 文件路径错误 | 检查`--test-data-path`参数 |
| 向量检索失败 | 向量数据库未初始化 | 运行初始化流程或使用`--reuse-vector-db` |
| 上下文过长 | 数据量超出限制 | 使用PromptCompressor或精简数据 |
---
## 总结
记忆管理系统是TestZeus Hercules实现智能测试代理的关键基础设施。通过StaticLTM的静态数据管理、DynamicLTM的动态检索能力、StateHandler的状态持久化以及PromptCompressor的上下文优化，该系统为AI代理提供了完整、一致且可扩展的记忆能力。
系统的模块化设计允许各组件独立工作，同时通过标准化的接口实现紧密协作。开发者可以根据具体需求选择启用或禁用特定功能，实现性能与功能的平衡。
---
## Playwright 浏览器自动化
### 相关页面
相关主题：[工具注册与工具集](#page-tool-registry), [测试能力总览](#page-testing-capabilities)
相关源码文件
以下源码文件用于生成本页说明：
- [testzeus_hercules/core/playwright_manager.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/playwright_manager.py)
- [testzeus_hercules/core/browser_logger.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/browser_logger.py)
- [testzeus_hercules/utils/get_detailed_accessibility_tree.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/get_detailed_accessibility_tree.py)
- [testzeus_hercules/utils/dom_helper.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/dom_helper.py)
- [testzeus_hercules/utils/dom_mutation_observer.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/dom_mutation_observer.py)
- [testzeus_hercules/utils/js_helper.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/js_helper.py)
# Playwright 浏览器自动化
## 概述
Playwright 浏览器自动化模块是 TestZeus Hercules 项目的核心组件，负责管理与浏览器的所有交互操作。该模块基于 Playwright 框架构建，提供了一套完整的浏览器控制能力，包括页面导航、元素交互、DOM 提取、事件监听等高级功能。
该系统的主要职责包括：
- 管理 Playwright 实例的启动、初始化和关闭生命周期
- 处理浏览器上下文和多标签页管理
- 捕获控制台日志和请求/响应数据
- 提供 DOM 观察者机制以检测页面变化
- 生成无障碍信息树用于 AI Agent 决策
- 执行截图和视频录制
资料来源：[testzeus_hercules/core/playwright_manager.py:1-50]()
## 核心架构
### 组件关系图
```mermaid
graph TD
subgraph "核心管理层"
PM[PlaywrightManager]
BL[BrowserLogger]
TM[Telemetry]
end
subgraph "工具层"
OU[open_url]
GIE[get_interactive_elements]
GPT[get_page_text]
HOV[hover]
SC[select_option]
end
subgraph "工具函数层"
DOM[dom_helper]
DAT[get_detailed_accessibility_tree]
DMO[dom_mutation_observer]
JSH[js_helper]
end
subgraph "Playwright API"
PA[Playwright API]
PC[Page Context]
BR[Browser]
end
PM --> BL
PM --> TM
PM --> PA
PA --> PC
PA --> BR
OU --> PM
GIE --> PM
GPT --> PM
HOV --> PM
DOM --> DAT
DOM --> DMO
DMO --> JSH
GIE --> DAT
GPT --> DOM
```
### PlaywrightManager 核心类
`PlaywrightManager` 是整个浏览器自动化的核心管理类，采用单例模式设计，负责协调所有浏览器操作。
资料来源：[testzeus_hercules/core/playwright_manager.py:50-120]()
#### 初始化参数
| 参数名 | 类型 | 说明 | 默认值 |
|--------|------|------|--------|
| browser_type | str | 浏览器类型 (chromium/firefox/webkit) | chromium |
| headless | bool | 是否以无头模式运行 | False |
| device_name | str | 模拟设备名称 | None |
| user_viewport | tuple | 视口尺寸 (width, height) | (1280, 720) |
| user_locale | str | 区域设置 | en-US |
| user_timezone | str | 时区 | America/New_York |
| user_geolocation | dict | 地理位置 | None |
| user_color_scheme | str | 颜色方案 (light/dark) | light |
资料来源：[testzeus_hercules/core/playwright_manager.py:20-45]()
#### 核心方法
| 方法名 | 返回类型 | 功能描述 |
|--------|----------|----------|
| async_initialize | None | 异步初始化 Playwright 和浏览器上下文 |
| ensure_browser_context | None | 确保浏览器上下文存在 |
| get_current_page | Page | 获取当前活动页面 |
| reuse_or_create_tab | Page | 重用或创建新标签页 |
| take_screenshots | None | 拍摄页面截图 |
| highlight_element | None | 高亮显示元素 |
| wait_for_load_state_if_enabled | None | 等待页面加载状态 |
| go_to_homepage | None | 导航到首页 |
资料来源：[testzeus_hercules/core/playwright_manager.py:45-80]()
## 生命周期管理
### 初始化流程
```mermaid
sequenceDiagram
participant User as 用户/Agent
participant PM as PlaywrightManager
participant PW as Playwright
participant BC as BrowserContext
User->>PM: async_initialize()
PM->>PM: 创建必要目录
PM->>PM: start_playwright()
PM->>PW: playwright().start()
PW-->>PM: _playwright 实例
PM->>PM: ensure_browser_context()
PM->>PM: create_browser_context()
PM->>BC: 浏览器上下文
PM->>PM: setup_handlers()
PM->>PM: go_to_homepage()
PM-->>User: 初始化完成
```
### 异步初始化详解
`async_initialize` 方法采用延迟初始化模式，确保只初始化一次：
```python
async def async_initialize(self) -> None:
if self.__async_initialize_done:
return
# 创建所需目录
os.makedirs(self._screenshots_dir, exist_ok=True)
os.makedirs(self._video_dir, exist_ok=True)
if self._enable_tracing:
os.makedirs(self._trace_dir, exist_ok=True)
await self.start_playwright()
await self.ensure_browser_context()
await self.setup_handlers()
await self.go_to_homepage()
self.__async_initialize_done = True
```
资料来源：[testzeus_hercules/core/playwright_manager.py:45-65]()
## 浏览器工具集
### 工具注册与调用
所有浏览器工具通过 `@tool` 装饰器注册，支持 `browser_nav_agent` 代理调用：
```python
@tool(
agent_names=["browser_nav_agent"],
description="""工具描述文本""",
name="tool_name",
)
async def tool_function(params):
# 实现代码
```
资料来源：[testzeus_hercules/core/tools/open_url.py:1-30]()
### 核心工具列表
| 工具名称 | 功能描述 | 主要参数 |
|----------|----------|----------|
| openurl | 打开指定 URL | url, timeout, force_new_tab |
| get_page_text | 获取页面文本内容 | 无 |
| get_interactive_elements | 获取所有可交互元素 | 无 |
| get_input_fields | 获取输入字段 | 无 |
| hover | 悬停在元素上 | selector, wait_before_execution |
| select_option | 选择下拉选项 | (selector, value_to_fill) |
| press_key_combination | 按键操作 | key_combination |
| read_clipboard | 读取剪贴板 | clipboard_type |
| extract_text_from_pdf | 提取 PDF 文本 | pdf_url |
资料来源：[testzeus_hercules/core/tools/open_url.py:1-40]()
资料来源：[testzeus_hercules/core/tools/get_page_text.py:1-50]()
资料来源：[testzeus_hercules/core/tools/get_interactive_elements.py:1-40]()
### 页面导航
`openurl` 工具负责页面导航，支持多种导航策略：
```python
async def openurl(
url: Annotated[str, "URL to navigate to"],
timeout: Annotated[int, "Additional wait time in seconds"] = 3,
force_new_tab: Annotated[bool, "Force opening in a new tab"] = False,
) -> Annotated[str, "Returns the result of this request"]
```
导航流程：
1. 调用 `PlaywrightManager` 获取浏览器上下文
2. 使用 `reuse_or_create_tab` 方法获取页面
3. 设置导航超时时间
4. 执行 URL 导航
5. 记录浏览器日志
资料来源：[testzeus_hercules/core/tools/open_url.py:20-50]()
### 元素交互
#### 悬停操作
```python
async def hover(
selector: Annotated[str, "selector using md attribute"],
wait_before_execution: Annotated[float, "Wait time in seconds"] = 0.0,
) -> Annotated[str, "Result of hover action with tooltip text"]
```
悬停机制通过 `md` 属性选择器定位元素，支持等待时间配置。
资料来源：[testzeus_hercules/core/tools/hover.py:1-40]()
#### 下拉选择
```python
async def select_option(
entry: Annotated[
tuple[str, str],
"tuple containing 'selector' and 'value_to_fill'",
],
) -> Annotated[str, "Explanation of the outcome"]
```
资料来源：[testzeus_hercules/core/tools/dropdown_using_selector.py:1-50]()
#### 按键操作
```python
async def press_key_combination(
key_combination: Annotated[str, "key to press, e.g., Enter, PageDown"],
) -> str
```
支持组合键操作，如 `Ctrl+C`、`Shift+Tab` 等。
资料来源：[testzeus_hercules/core/tools/press_key_combination.py:1-40]()
## DOM 处理机制
### DOM 观察者
`dom_mutation_observer` 模块提供 DOM 变化监听功能，支持订阅和取消订阅模式：
```mermaid
graph LR
A[DOM 变化] --> B[MutationObserver]
B --> C{订阅者数量}
C -->|有订阅者| D[通知回调函数]
C -->|无订阅者| E[忽略]
D --> F[detect_dom_changes]
F --> G[dom_changes_detected]
```
主要函数：
| 函数名 | 功能 |
|--------|------|
| subscribe | 注册 DOM 变化回调 |
| unsubscribe | 取消注册回调 |
资料来源：[testzeus_hercules/utils/dom_mutation_observer.py:1-50]()
### DOM 辅助工具
`dom_helper` 模块提供多种 DOM 操作工具：
| 函数名 | 功能描述 |
|--------|----------|
| wait_for_non_loading_dom_state | 等待 DOM 加载完成 |
| get_element_outer_html | 获取元素 HTML |
| get_filtered_text_content | 获取过滤后的文本 |
资料来源：[testzeus_hercules/utils/dom_helper.py:1-100]()
### 无障碍信息树
`get_detailed_accessibility_tree` 模块生成页面的无障碍信息树，供 AI Agent 理解页面结构：
```python
async def do_get_accessibility_info(page) -> str:
"""获取详细的无障碍信息树"""
# 实现代码
```
关键函数：
| 函数名 | 功能 |
|--------|------|
| do_get_accessibility_info | 生成无障碍信息树 |
| rename_children | 重命名子元素以提高可读性 |
资料来源：[testzeus_hercules/utils/get_detailed_accessibility_tree.py:1-80]()
## 日志与遥测
### 浏览器日志
`BrowserLogger` 负责捕获和控制浏览器相关的日志信息：
| 日志类型 | 文件路径 | 内容 |
|----------|----------|------|
| 控制台日志 | console_log_file | console.log 输出 |
| 请求/响应日志 | request_response_log_file | HTTP 请求和响应 |
| 截图 | screenshots_dir | 页面截图 |
资料来源：[testzeus_hercules/core/browser_logger.py:1-50]()
### 遥测系统
系统集成 Sentry 进行错误追踪和遥测数据收集：
```python
def add_event(event_type: EventType, event_data: EventData):
"""记录交互事件"""
```
| 事件类型 | 说明 |
|----------|------|
| INTERACTION | 用户交互事件 |
| NAVIGATION | 页面导航事件 |
| ERROR | 错误事件 |
资料来源：[testzeus_hercules/telemetry.py:1-100]()
## 配置选项
### 命令行参数
通过命令行可以配置浏览器行为：
| 参数 | 类型 | 说明 |
|------|------|------|
| --browser-type | str | 浏览器类型 |
| --headless | flag | 无头模式 |
| --device | str | 模拟设备 |
| --viewport | str | 视口尺寸 |
| --locale | str | 区域设置 |
| --timezone | str | 时区设置 |
| --screenshots-dir | str | 截图保存目录 |
| --enable-tracing | flag | 启用追踪 |
资料来源：[testzeus_hercules/config.py:1-100]()
## 前端渲染器
项目包含两个 HTML 前端用于 CDP 流渲染：
### 非交互模式
文件位置：`frontend/non-interactive/index.html`
功能：
- 实时显示浏览器截图流
- 显示文本输出信息
- 简单的状态显示
### 交互模式
文件位置：`frontend/interactive/index.html`
功能：
- 支持鼠标点击和拖拽
- 支持键盘输入
- 虚拟输入框捕获焦点
- 跨设备交互支持
## 工作流程示例
### 页面内容抓取流程
```mermaid
graph TD
A[Agent 请求页面内容] --> B[get_page_text 调用]
B --> C[PlaywrightManager 获取页面]
C --> D[等待 DOM 加载完成]
D --> E[wait_for_non_loading_dom_state]
E --> F[获取过滤文本内容]
F --> G[保存到日志文件]
G --> H[返回文本内容]
```
### 元素交互流程
```mermaid
graph TD
A[Agent 请求交互] --> B[选择器解析]
B --> C{选择器格式}
C -->|无 md= 前缀| D[添加 md= 前缀]
C -->|有 md= 前缀| E[直接使用]
D --> E
E --> F[高亮元素]
F --> G[订阅 DOM 变化]
G --> H[执行交互操作]
H --> I[等待延迟时间]
I --> J[取消订阅]
J --> K[拍摄截图]
K --> L[返回结果]
```
## 最佳实践
### 选择器使用
始终使用 `md` 属性作为元素选择器，避免使用 CSS 或 XPath 选择器：
```python
# 推荐
selector = "[md='element_id']"
# 内部会自动处理
if "md=" not in selector:
selector = f"[md='{selector}']"
```
资料来源：[testzeus_hercules/core/tools/hover.py:25-30]()
### 异步操作
所有 Playwright 操作必须使用 `async/await` 模式：
```python
async def example():
browser_manager = PlaywrightManager()
page = await browser_manager.get_current_page()
await page.click("[md='button_id']")
```
### 错误处理
使用 `try-except` 捕获 Playwright 超时和状态错误：
```python
from playwright.async_api import TimeoutError as PlaywrightTimeoutError
try:
await page.click(selector)
except PlaywrightTimeoutError:
logger.warning("Element not found within timeout")
```
资料来源：[testzeus_hercules/core/tools/open_url.py:10-20]()
## 总结
Playwright 浏览器自动化模块构成了 TestZeus Hercules 的核心能力基础，通过模块化的工具设计和统一的管理接口，实现了高效的浏览器自动化操作。该系统采用事件驱动的架构，支持实时 DOM 观察和状态追踪，为 AI Agent 提供了可靠的浏览器控制能力。
---
## 测试能力总览
### 相关页面
相关主题：[API 测试与安全测试](#page-api-testing), [Python 沙箱执行](#page-python-sandbox), [MCP 集成与使用](#page-mcp-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [testzeus_hercules/utils/gherkin_helper.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/gherkin_helper.py)
- [testzeus_hercules/utils/response_parser.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/response_parser.py)
- [testzeus_hercules/core/tools/api_sec_calls.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/api_sec_calls.py)
- [testzeus_hercules/core/tools/sql_calls.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/sql_calls.py)
- [testzeus_hercules/core/extra_tools/visual_skill.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/extra_tools/visual_skill.py)
# 测试能力总览
## 概述
TestZeus Hercules 是一个开源的端到端 AI 测试代理平台，专注于自动化测试能力建设。该系统通过多智能体架构实现对 Web 应用、API 接口、数据库操作的全面自动化测试覆盖。测试框架支持从传统的 UI 交互测试到高级的安全扫描和可视化验证，为测试团队提供了一站式解决方案。
Hercules 的核心设计理念是将人工智能融入软件测试生命周期的各个环节，从测试用例生成、执行、到结果验证，全部实现智能化处理。系统基于 Playwright 浏览器自动化框架，结合大型语言模型（LLM）的推理能力，能够自主理解和执行复杂的测试场景。
## 系统架构
### 整体架构图
```mermaid
graph TD
subgraph "表现层"
A[Frontend 交互界面]
B[Frontend 非交互界面]
end
subgraph "核心引擎"
C[Simple Hercules 主控制器]
D[Executor Nav Agent 执行导航代理]
E[Planner Agent 计划代理]
end
subgraph "工具层"
F[API 调用工具]
G[SQL 调用工具]
H[Python 沙箱执行器]
I[可视化技能工具]
J[Gherkin 解析器]
end
subgraph "底层服务"
K[Playwright 浏览器管理器]
L[LLM 模型接口]
M[向量数据库]
N[遥测系统]
end
A --> C
B --> C
C --> D
C --> E
D --> F
D --> G
D --> H
D --> I
D --> J
F --> L
G --> L
H --> K
I --> K
J --> L
```
### 核心组件说明
| 组件名称 | 文件位置 | 功能描述 |
|---------|---------|---------|
| Simple Hercules | `testzeus_hercules/core/simple_hercules.py` | 主控制器，协调各代理之间的通信和任务分发 |
| Executor Nav Agent | `testzeus_hercules/core/agents/executor_nav_agent.py` | 负责浏览器导航和交互执行 |
| API 调用工具 | `testzeus_hercules/core/tools/api_sec_calls.py` | 处理 API 安全测试和接口验证 |
| SQL 调用工具 | `testzeus_hercules/core/tools/sql_calls.py` | 数据库操作和验证测试 |
| Python 沙箱 | `testzeus_hercules/core/tools/execute_python_sandbox.py` | 安全执行 Python 代码片段 |
| 可视化技能 | `testzeus_hercules/core/extra_tools/visual_skill.py` | 页面截图和视觉对比验证 |
| Gherkin 助手 | `testzeus_hercules/utils/gherkin_helper.py` | Gherkin 格式解析和转换 |
| 响应解析器 | `testzeus_hercules/utils/response_parser.py` | LLM 响应解析和 JSON 提取 |
## 测试类型支持
### Web UI 自动化测试
Web UI 测试是 Hercules 的核心能力之一。系统通过 Playwright 框架实现对现代 Web 应用的全面自动化测试覆盖，支持 Chrome、Firefox 等多浏览器渠道。
#### 浏览器配置选项
系统提供丰富的浏览器配置选项，支持不同测试场景的需求：
| 参数 | 类型 | 说明 | 示例值 |
|-----|------|------|--------|
| `--browser-channel` | str | 浏览器渠道选择 | `chrome-beta`, `firefox-nightly` |
| `--browser-path` | str | 自定义浏览器路径 | `/usr/bin/chromium` |
| `--browser-version` | str | 指定浏览器版本 | `114`, `115.0.1`, `latest` |
| `--enable-ublock` | flag | 启用广告拦截扩展 | - |
| `--auto-accept-screen-sharing` | flag | 自动接受屏幕共享请求 | - |
资料来源：[testzeus_hercules/config.py:85-112]()
#### 脚本执行机制
Executor Nav Agent 负责在浏览器上下文中执行测试脚本。代理接收导航指令后，通过 Playwright API 执行相应的用户交互操作。
```mermaid
sequenceDiagram
participant U as 用户输入
participant E as Executor Agent
participant P as Playwright
participant B as Browser Page
U->>E: 发送测试指令
E->>P: 调用 execute_python_sandbox
P->>B: 执行浏览器操作
B-->>P: 返回执行结果
P-->>E: 脚本执行响应
E-->>U: 任务完成状态
```
### API 接口测试
#### API 安全调用模块
`api_sec_calls.py` 模块提供了全面的 API 安全测试能力，支持对 RESTful 接口进行多种安全场景验证。模块设计遵循现代 API 安全测试的最佳实践，能够自动化检测常见的安全漏洞。
资料来源：[testzeus_hercules/core/tools/api_sec_calls.py]()
#### API 测试生成器
系统提供命令行工具用于自动生成 API 测试用例：
```python
# 功能测试生成
python helper_scripts/generate_api_functional_gherkin_test.py \
--output ./tests/api \
--model o1-preview \
--number_of_testcase 100 \
openapi_spec.yaml
```
```python
# 安全测试生成
python helper_scripts/generate_api_security_gherkin_test.py \
--output ./tests/security \
--model o1-preview
```
资料来源：[helper_scripts/generate_api_functional_gherkin_test.py]()
资料来源：[helper_scripts/generate_api_security_gherkin_test.py]()
### 数据库测试
#### SQL 调用工具
`sql_calls.py` 模块封装了数据库操作的核心功能，支持对数据库状态进行验证和查询。该工具允许测试代理执行 SQL 语句并验证返回结果，适用于数据驱动测试场景。
资料来源：[testzeus_hercules/core/tools/sql_calls.py]()
### 可视化测试
#### 视觉技能工具
`visual_skill.py` 提供了基于截图的视觉对比测试能力。该工具能够在测试执行过程中捕获页面状态，并将其与预期结果进行对比分析，检测 UI 渲染异常。
资料来源：[testzeus_hercules/core/extra_tools/visual_skill.py]()
#### CDP 流渲染器
系统前端提供两种 CDP 流渲染模式：
| 模式 | 文件 | 用途 |
|-----|------|------|
| 非交互模式 | `frontend/non-interactive/index.html` | 仅展示浏览器画面 |
| 交互模式 | `frontend/interactive/index.html` | 支持远程控制页面交互 |
前端通过 WebSocket 与后端 CDP 服务器通信，实时流式传输浏览器画面至前端展示界面。
资料来源：[frontend/interactive/index.html]()
资料来源：[frontend/non-interactive/index.html]()
## Python 沙箱执行
### 执行架构
Python 沙箱是 Hercules 测试能力的核心组成部分，允许在隔离环境中动态执行测试代码。沙箱通过 `execute_python_sandbox.py` 模块实现，提供了安全且灵活的代码执行能力。
资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py]()
### 可用上下文变量
执行脚本时可自动访问以下上下文变量：
| 变量名 | 类型 | 说明 |
|-------|------|------|
| `page` | Playwright Page | 当前浏览器页面对象 |
| `browser` | Browser | 浏览器实例 |
| `context` | BrowserContext | 浏览器上下文 |
| `playwright_manager` | PlaywrightManager | Playwright 管理器 |
| `logger` | Logger | 日志记录器 |
| `config` | Config | 全局配置对象 |
### 模块注入机制
系统支持根据租户配置动态注入额外模块：
```python
# 环境变量配置
SANDBOX_TENANT_ID=executor_agent
SANDBOX_CUSTOM_INJECTIONS='["requests", "pandas", "bs4"]'
SANDBOX_PACKAGES='["numpy", "json"]'
```
注入的模块可直接在脚本中使用，无需额外导入操作。
### 配置驱动注入
通过配置文件可以定义沙箱可用的包列表：
```python
def _get_config_driven_injections(config: Any) -> Dict[str, Any]:
sandbox_packages = config.get_config().get("SANDBOX_PACKAGES", "").split(",")
# 动态加载配置的包
```
## Gherkin 集成
### Gherkin 助手功能
`gherkin_helper.py` 模块负责 Gherkin 格式的解析和转换工作。该工具将自然语言描述的测试场景转换为可执行的测试代码，支持 BDD（行为驱动开发）工作流。
资料来源：[testzeus_hercules/utils/gherkin_helper.py]()
### 测试用例生成流程
```mermaid
graph LR
A[OpenAPI Spec] --> B[生成器脚本]
B --> C[LLM 模型]
C --> D[Gherkin 场景]
D --> E[测试数据文件]
E --> F[执行测试]
```
### 输出格式规范
生成的 Gherkin 文件遵循以下格式：
```gherkin
Feature: 功能描述
Scenario: 测试场景
Given 初始条件
When 执行操作
Then 验证结果
```
测试数据以键值对形式存储在单独文件中：
```
PARAM_USERNAME: testuser
PARAM_PASSWORD: SecurePass123
```
## 响应解析机制
### JSON 响应解析
`response_parser.py` 模块负责解析 LLM 返回的响应内容。由于大型语言模型的输出格式可能存在变体，解析器实现了多种容错处理机制。
资料来源：[testzeus_hercules/utils/response_parser.py]()
#### 解析流程
1. 检测并提取 ```json ``` 代码块包裹的内容
2. 处理 ``` ``` 包裹的原始文本
3. 清理转义字符和多余空白
4. 尝试 JSON 解析
5. 回退到键值对提取模式
```python
def parse_response(message: str) -> dict[str, Any]:
if "```json" in message:
# 提取 JSON 代码块
start_idx = message.find("```json") + 7
end_idx = message.find("```", start_idx + 7)
message = message[start_idx:end_idx]
# ... 后续处理
```
### 错误处理
解析器实现了健壮的错误处理机制，当 JSON 解析失败时，能够从文本中提取 `plan` 和 `next_step` 字段作为备选方案。
## 配置管理
### 命令行参数体系
Hercules 通过 `config.py` 提供全面的命令行配置选项，支持灵活定制测试执行行为。
资料来源：[testzeus_hercules/config.py]()
#### LLM 模型配置
| 参数 | 说明 |
|-----|------|
| `--llm-model` | 模型名称 |
| `--llm-model-api-key` | API 密钥 |
| `--llm-model-base-url` | API 基础地址 |
| `--llm-model-api-type` | API 类型（openai/anthropic/azure） |
| `--llm-temperature` | 采样温度（0.0-1.0） |
#### Portkey 集成
| 参数 | 说明 |
|-----|------|
| `--enable-portkey` | 启用 Portkey 路由 |
| `--portkey-api-key` | Portkey API 密钥 |
| `--portkey-strategy` | 路由策略（fallback/loadbalance） |
#### 测试执行选项
| 参数 | 说明 |
|-----|------|
| `--bulk` | 批量执行 tests 目录下的测试 |
| `--reuse-vector-db` | 复用现有向量数据库 |
| `--input-file` | 输入文件路径 |
| `--output-path` | 输出目录路径 |
## 遥测与监控
### 安装标识管理
`telemetry.py` 模块负责生成和管理安装标识符，用于追踪匿名使用统计信息。系统遵循隐私保护原则，默认不收集个人身份信息。
资料来源：[testzeus_hercules/telemetry.py]()
### 数据收集策略
- 最大面包屑数设置为 0，禁用详细轨迹记录
- 默认不发送 PII（个人身份信息）
- 客户端报告功能默认禁用
- 敏感数据通过 `EventScrubber` 自动过滤
## 开发工作流
### 本地开发配置
参考 CONTRIBUTING.md 中的开发指南：
1. 创建个人仓库分支
2. 配置虚拟环境 `make virtualenv`
3. 安装开发依赖 `make install`
4. 运行测试验证 `make test`
5. 代码格式化 `make fmt`
6. 提交前检查 `make lint`
资料来源：[CONTRIBUTING.md]()
### 发布流程
项目采用语义化版本控制，通过 Git Tag 触发自动化发布流程。每次推送新标签时，GitHub Actions 会自动构建并发布到 PyPI。
## 总结
TestZeus Hercules 提供了全面的自动化测试能力，涵盖 Web UI 测试、API 接口测试、数据库验证和可视化对比等多个维度。系统通过模块化设计和智能代理架构，实现了测试用例的自动生成、动态执行和结果验证，为现代软件开发团队提供了高效可靠的测试解决方案。
---
## MCP 集成与使用
### 相关页面
相关主题：[测试能力总览](#page-testing-capabilities)
相关源码文件
以下源码文件用于生成本页说明：
- [testzeus_hercules/core/agents/mcp_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/mcp_nav_agent.py)
- [testzeus_hercules/core/tools/mcp_tools.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/mcp_tools.py)
- [testzeus_hercules/utils/mcp_helper.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/mcp_helper.py)
- [docs/MCP_Usage.md](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/docs/MCP_Usage.md)
- [mcp_servers.example.json](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/mcp_servers.example.json)
- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)
- [frontend/interactive/index.html](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/frontend/interactive/index.html)
- [frontend/non-interactive/index.html](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/frontend/non-interactive/index.html)
# MCP 集成与使用
## 概述
MCP（Model Context Protocol）集成是 testzeus-hercules 项目中用于实现浏览器自动化测试的核心组件。该模块通过 CDP（Chrome DevTools Protocol）协议与浏览器进行通信，支持交互式和非交互式两种操作模式。开发者可以利用 MCP 集成来驱动浏览器执行各种操作，包括页面导航、元素交互、表单填写、截图等高级功能。
MCP 集成的主要目标是提供一个灵活、可扩展的浏览器自动化框架，使 AI Agent 能够通过自然语言指令控制浏览器行为。系统采用模块化设计，将不同的功能分离到独立的模块中，包括导航代理（Nav Agent）、工具集（Tools）和辅助工具（Helper）。 资料来源：[testzeus_hercules/core/agents/mcp_nav_agent.py:1-30]()
## 架构设计
### 整体架构
MCP 集成采用客户端-服务器架构，核心组件包括 MCP 导航代理、MCP 工具集和 MCP 辅助工具三个主要部分。客户端通过 WebSocket 与浏览器建立长连接，实时接收浏览器的状态更新并发送控制指令。
```mermaid
graph TD
A[AI Agent] --> B[MCP Nav Agent]
B --> C[MCP Tools]
C --> D[MCP Helper]
D --> E[CDP Stream]
E --> F[Browser]
F --> E
E --> G[Frontend Display]
H[MCP Servers Config] --> B
I[mcp_servers.json] --> H
```
### 组件职责
| 组件 | 文件路径 | 主要职责 |
|------|----------|----------|
| MCP Nav Agent | `testzeus_hercules/core/agents/mcp_nav_agent.py` | 处理导航逻辑和任务规划 |
| MCP Tools | `testzeus_hercules/core/tools/mcp_tools.py` | 提供浏览器操作工具集 |
| MCP Helper | `testzeus_hercules/utils/mcp_helper.py` | 辅助功能和状态管理 |
| Frontend Display | `frontend/interactive/` | 用户界面展示 |
## 配置管理
### MCP 服务器配置
MCP 服务器通过 JSON 格式的配置文件进行管理。项目中提供了 `mcp_servers.example.json` 作为配置模板，开发者需要创建 `mcp_servers.json` 文件来定义实际的 MCP 服务器配置。
配置文件主要包含以下结构：
```json
{
"mcp_servers": [
{
"name": "server_name",
"command": "command_to_run",
"args": ["arg1", "arg2"],
"env": {
"KEY": "value"
}
}
]
}
```
资料来源：[mcp_servers.example.json](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/mcp_servers.example.json)
### 配置参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | MCP 服务器名称 |
| command | string | 是 | 启动服务器的命令 |
| args | array | 否 | 命令行参数列表 |
| env | object | 否 | 环境变量配置 |
## MCP 导航代理
### 核心功能
MCP 导航代理（`mcp_nav_agent.py`）是整个 MCP 集成的核心组件，负责协调浏览器操作和任务执行。该代理继承了 NavigatorAgentBase 基类，实现了浏览器导航和控制的核心逻辑。
导航代理的主要职责包括：
- **任务解析**：解析 AI Agent 的自然语言指令，转换为可执行的浏览器操作
- **脚本执行**：通过 Python 沙箱执行浏览器控制脚本
- **结果验证**：验证每个操作的结果，确保任务正确完成
- **错误处理**：捕获并处理执行过程中的各种异常情况
资料来源：[testzeus_hercules/core/agents/mcp_nav_agent.py:1-50]()
### 执行流程
```mermaid
graph LR
A[接收指令] --> B[解析任务]
B --> C[选择工具]
C --> D[执行脚本]
D --> E{执行成功?}
E -->|是| F[验证结果]
E -->|否| G[错误处理]
F --> H[返回结果]
G --> I[重试或终止]
```
## MCP 工具集
### 工具类型
MCP 工具集（`mcp_tools.py`）提供了一系列用于浏览器控制的工具函数。这些工具封装了常见的浏览器操作，使 AI Agent 能够以统一的方式执行各种任务。
| 工具类型 | 功能描述 |
|----------|----------|
| 导航工具 | 页面跳转、前进、后退、刷新 |
| 交互工具 | 点击、悬停、拖拽、双击 |
| 输入工具 | 文本输入、文件上传、下拉选择 |
| 状态工具 | 获取元素信息、页面标题、URL |
| 截图工具 | 全屏截图、元素截图 |
资料来源：[testzeus_hercules/core/tools/mcp_tools.py:1-30]()
### 工具使用示例
MCP 工具通过统一的接口暴露给 AI Agent，每个工具都包含以下标准属性：
- **tool_name**：工具名称，用于标识具体操作
- **function_name**：对应的函数名
- **function_args**：函数参数对象
- **timeout**：执行超时时间
```python
# 工具调用示例结构
{
"tool_name": "click",
"function_name": "click_element",
"function_args": {
"selectors": [["#button-id"]],
"button": "left",
"click_count": 1
},
"timeout": 30000
}
```
## MCP 辅助工具
### 辅助功能
MCP 辅助工具（`mcp_helper.py`）提供了一系列辅助功能，用于支持核心模块的运行。这些功能包括状态管理、连接维护、日志记录等。
主要功能包括：
- **连接管理**：维护与浏览器的 WebSocket 连接
- **状态同步**：确保客户端和服务器状态一致
- **日志记录**：记录操作日志便于调试和追踪
- **资源清理**：管理资源生命周期，防止内存泄漏
资料来源：[testzeus_hercules/utils/mcp_helper.py:1-30]()
### 状态管理
系统采用集中式状态管理，所有与 MCP 相关的状态信息都通过 `mcp_helper` 模块进行统一管理。这种设计确保了状态的一致性和可追踪性。
## 前端组件
### 交互式界面
交互式前端（`frontend/interactive/index.html`）提供了一个实时显示浏览器状态的界面，用户可以直接与浏览器进行交互。该界面支持鼠标点击、键盘输入等交互操作。
界面特点：
- 实时屏幕广播显示
- 鼠标交互支持（点击、拖拽）
- 键盘输入捕获
- 焦点管理机制
资料来源：[frontend/interactive/index.html:1-40]()
### 非交互式界面
非交互式前端（`frontend/non-interactive/index.html`）主要用于监控和日志记录场景。该界面仅显示浏览器的屏幕广播，不支持用户交互。
## 使用指南
### 快速开始
1. **配置 MCP 服务器**
创建 `mcp_servers.json` 配置文件，定义需要启动的 MCP 服务器：
```bash
cp mcp_servers.example.json mcp_servers.json
# 编辑 mcp_servers.json 添加实际配置
```
2. **初始化 MCP 连接**
在测试脚本中导入并初始化 MCP 模块：
```python
from testzeus_hercules.core.tools.mcp_tools import MCPTools
from testzeus_hercules.utils.mcp_helper import MCPHelper
```
3. **执行浏览器操作**
使用 MCP 工具执行所需的浏览器操作：
```python
tools = MCPTools()
await tools.navigate_to("https://example.com")
```
### 高级配置
#### 自定义 MCP 服务器
可以通过配置文件添加自定义的 MCP 服务器：
```json
{
"mcp_servers": [
{
"name": "custom_server",
"command": "npx",
"args": ["-y", "@custom/mcp-server"],
"env": {
"API_KEY": "your-api-key"
}
}
]
}
```
#### 环境变量配置
| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| MCP_SERVER_CONFIG | MCP 服务器配置路径 | `mcp_servers.json` |
| CDP_ENDPOINT | CDP 端点地址 | 自动检测 |
| MCP_TIMEOUT | 操作超时时间（毫秒） | 30000 |
## 最佳实践
### 性能优化
1. **减少不必要的截图**：截图操作会消耗较多资源，应在必要时使用
2. **批量操作**：将多个相关操作组合执行，减少网络往返
3. **连接复用**：保持长连接避免重复建立的开销
4. **超时设置**：根据网络状况合理设置超时时间
### 稳定性保障
1. **错误重试**：实现指数退避策略处理临时性失败
2. **状态验证**：每个关键操作后验证预期结果
3. **日志记录**：详细记录操作日志便于问题排查
4. **资源清理**：确保操作完成后释放资源
## 故障排查
### 常见问题
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 连接失败 | MCP 服务器未启动 | 检查服务器状态并重新启动 |
| 超时错误 | 网络延迟或服务器负载高 | 增加超时时间或检查网络 |
| 元素未找到 | 选择器错误或页面未加载完成 | 添加等待或更新选择器 |
| 权限错误 | 缺少必要的系统权限 | 以管理员权限运行 |
### 调试技巧
1. **启用详细日志**：设置日志级别为 DEBUG 获取更多信息
2. **单步执行**：逐步执行操作定位问题发生位置
3. **截图验证**：在关键步骤保存截图辅助排查
4. **状态检查**：使用 MCP Helper 查看当前连接状态
## 相关资源
- 项目文档：[docs/MCP_Usage.md](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/docs/MCP_Usage.md)
- 示例配置：[mcp_servers.example.json](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/mcp_servers.example.json)
- 核心源码：[testzeus_hercules/core/agents/mcp_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/mcp_nav_agent.py)
---
## API 测试与安全测试
### 相关页面
相关主题：[测试能力总览](#page-testing-capabilities), [Python 沙箱执行](#page-python-sandbox)
相关源码文件
以下源码文件用于生成本页说明：
- [testzeus_hercules/core/tools/api_calls.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/api_calls.py)
- [testzeus_hercules/core/tools/api_sec_calls.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/api_sec_calls.py)
- [helper_scripts/generate_api_functional_gherkin_test.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/helper_scripts/generate_api_functional_gherkin_test.py)
- [helper_scripts/generate_api_security_gherkin_test.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/helper_scripts/generate_api_security_gherkin_test.py)
- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)
# API 测试与安全测试
## 概述
testzeus-hercules 提供了完整的 API 功能测试与安全测试解决方案。该系统通过 OpenAPI 规范文件自动生成 Gherkin 格式的测试用例，并支持使用 LLM（大语言模型）智能生成针对 API 功能的测试场景以及针对安全漏洞的测试场景。
API 测试模块主要位于 `testzeus_hercules/core/tools/` 目录下，而辅助脚本则位于 `helper_scripts/` 目录，用于从 OpenAPI 规范自动生成测试用例。
## 核心组件
### 测试工具模块
| 组件文件 | 路径 | 功能说明 |
|---------|------|----------|
| api_calls.py | testzeus_hercules/core/tools/ | API 功能测试执行核心 |
| api_sec_calls.py | testzeus_hercules/core/tools/ | API 安全测试执行核心 |
### 测试生成脚本
| 脚本文件 | 路径 | 功能说明 |
|---------|------|----------|
| generate_api_functional_gherkin_test.py | helper_scripts/ | 从 OpenAPI 规范生成功能测试 Gherkin 用例 |
| generate_api_security_gherkin_test.py | helper_scripts/ | 从 OpenAPI 规范生成安全测试 Gherkin 用例 |
## 架构设计
```mermaid
graph TD
A[OpenAPI 规范文件] --> B[测试生成脚本]
B --> C{Gherkin 测试用例}
C --> D[功能测试]
C --> E[安全测试]
D --> F[api_calls.py]
E --> G[api_sec_calls.py]
F --> H[Playwright 测试引擎]
G --> H
```
### 组件交互流程
```mermaid
sequenceDiagram
participant User as 用户
participant GenFunc as 生成功能测试脚本
participant GenSec as 生成安全测试脚本
participant LLM as OpenAI API
participant Executor as 测试执行器
participant Hercules as Hercules 核心引擎
User->>GenFunc: 输入 OpenAPI 规范
GenFunc->>LLM: 请求生成测试用例
LLM-->>GenFunc: 返回 Gherkin 用例
GenFunc-->>User: 输出 feature 文件
User->>GenSec: 输入 OpenAPI 规范
GenSec->>LLM: 请求生成安全测试
LLM-->>GenSec: 返回安全 Gherkin 用例
GenSec-->>User: 输出安全 feature 文件
User->>Executor: 执行测试
Executor->>Hercules: 调用 api_calls / api_sec_calls
Hercules-->>User: 返回测试结果
```
## 功能测试生成
### 脚本位置与用途
`helper_scripts/generate_api_functional_gherkin_test.py` 脚本用于从 OpenAPI 规范文件自动生成功能测试的 Gherkin 用例。
资料来源：[helper_scripts/generate_api_functional_gherkin_test.py:1-50]()
### 命令行参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| input_files | str (可变数量) | 必需 | 一个或多个 OpenAPI 规范文件路径 (YAML 或 JSON) |
| --output | str | 必需 | 输出文件夹路径，用于存放生成的 feature 文件 |
| --model | str | o1-preview | 用于调用 OpenAI API 的模型名称 |
| --number_of_testcase | int | 100 | 要生成的测试用例数量 |
### 使用方法
```bash
OPENAI_API_KEY=your_api_key python helper_scripts/generate_api_functional_gherkin_test.py \
input_files/openapi.yaml \
input_files/api_spec.json \
--output ./tests/features \
--model gpt-4o \
--number_of_testcase 50
```
### 核心函数流程
```mermaid
graph TD
A[读取 OpenAPI 规范] --> B[prepare_prompt 准备提示词]
B --> C[generate_test_cases 调用 LLM]
C --> D{成功?}
D -->|是| E[拆分 feature 文件]
D -->|否| F[打印错误并继续下一个文件]
E --> G[ensure_output_folder 确保输出目录存在]
G --> H[write_feature_files 写入文件]
```
## 安全测试生成
### 脚本位置与用途
`helper_scripts/generate_api_security_gherkin_test.py` 脚本专门用于从 OpenAPI 规范生成安全测试用例。生成的测试用例聚焦于以下安全主题：
- API 漏洞检测
- 配置弱点分析
- 敏感数据处理验证
资料来源：[helper_scripts/generate_api_security_gherkin_test.py:1-80]()
### 安全测试生成器配置
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| input_files | str (可变数量) | 必需 | OpenAPI 规范文件列表 |
| --output | str | 必需 | 输出文件夹路径 |
| --model | str | gpt-4o | 使用的 LLM 模型 |
| --topics | str 列表 | 必需 | 安全测试主题列表 |
### 使用方法
```bash
OPENAI_API_KEY=your_api_key python helper_scripts/generate_api_security_gherkin_test.py \
api_spec.yaml \
--output ./tests/security \
--model gpt-4o \
--topics injection xss auth
```
### 安全测试输出格式
生成的安全测试用例遵循标准 Gherkin 格式：
```gherkin
Feature: API 安全测试 - SQL 注入防护
Scenario: 验证 API 对 SQL 注入攻击的防护
Given API 规范路径 "api_spec.yaml"
When 发送包含 SQL 注入载荷的请求
Then 响应应返回 400 错误码
And 不应包含数据库错误信息
Feature: API 安全测试 - 认证验证
Scenario: 验证未授权访问被正确阻止
Given API 规范路径 "api_spec.yaml"
When 发送未携带认证令牌的请求
Then 响应应返回 401 未授权状态码
```
## 配置选项
### LLM 模型配置
通过命令行参数或配置文件设置 LLM 相关选项：
| 参数 | 说明 |
|------|------|
| --llm-model | LLM 模型名称 |
| --llm-model-api-key | API 密钥 |
| --llm-model-base-url | API 基础 URL |
| --llm-model-api-type | API 类型 (openai, anthropic, azure, ollama 等) |
| --llm-temperature | 采样温度 (0.0-1.0) |
资料来源：[testzeus_hercules/config.py:1-60]()
### Portkey 集成配置
系统支持使用 Portkey 进行 LLM 路由：
| 参数 | 说明 |
|------|------|
| --enable-portkey | 启用 Portkey 集成 |
| --portkey-api-key | Portkey API 密钥 |
| --portkey-strategy | 路由策略 (fallback 或 loadbalance) |
### 配置文件方式
可以使用 JSON 配置文件定义各代理的 LLM 配置：
```json
{
"openai": {
"planner_agent": {
"model_name": "gpt-4o",
"model_api_key": "",
"model_api_type": "openai",
"llm_config_params": {
"temperature": 0.0,
"cache_seed": null
}
}
}
}
```
资料来源：[agents_llm_config-example.json:1-40]()
## 执行测试
### 批量执行模式
```bash
python -m testzeus_hercules --bulk --test-data-path ./tests/data
```
### 使用自定义测试数据
```bash
python -m testzeus_hercules \
--input-file ./tests/features/api_test.feature \
--test-data-path ./tests/testdata.yaml
```
## 最佳实践
### 1. OpenAPI 规范准备
- 确保 OpenAPI 规范文件格式正确 (支持 YAML 和 JSON)
- 规范中应包含完整的 API 端点定义
- 安全测试建议包含认证和授权相关的端点描述
### 2. 测试用例数量控制
- 功能测试建议设置 50-100 个用例以平衡覆盖率和执行时间
- 安全测试建议针对每个安全主题生成独立测试场景
### 3. LLM 模型选择
- 功能测试可使用 o1-preview 或 gpt-4o
- 安全测试建议使用 gpt-4o 以获得更好的安全分析能力
- 适当调整 temperature 参数：功能测试推荐 0.0-0.3，安全测试推荐 0.7
### 4. 敏感信息处理
- 生成测试用例时不要在代码中硬编码敏感凭证
- 使用环境变量或配置文件管理 API 密钥
- 测试数据文件应使用占位符如 `PARAM_USERNAME`
## 常见问题
### Q: OPENAI_API_KEY 未设置怎么办？
**A:** 脚本会打印错误信息并退出：
```python
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
print("Error: OPENAI_API_KEY environment variable not set.")
sys.exit(1)
```
资料来源：[helper_scripts/generate_api_functional_gherkin_test.py:40-45]()
### Q: 如何处理多个 OpenAPI 规范文件？
**A:** 脚本支持一次性处理多个文件：
```bash
python generate_api_functional_gherkin_test.py spec1.yaml spec2.yaml spec3.json --output ./tests
```
### Q: 生成的测试用例无法运行怎么办？
**A:** 检查以下几点：
1. OpenAPI 规范格式是否正确
2. LLM 返回的 Gherkin 语法是否有效
3. 测试数据文件路径是否正确配置
4. API 端点是否可达
## 相关文件索引
| 文件路径 | 用途 |
|---------|------|
| testzeus_hercules/core/tools/api_calls.py | API 功能测试执行工具 |
| testzeus_hercules/core/tools/api_sec_calls.py | API 安全测试执行工具 |
| testzeus_hercules/config.py | 全局配置与命令行参数定义 |
| testzeus_hercules/core/simple_hercules.py | 核心执行引擎 |
| helper_scripts/generate_api_functional_gherkin_test.py | 功能测试生成器 |
| helper_scripts/generate_api_security_gherkin_test.py | 安全测试生成器 |
| agents_llm_config-example.json | LLM 配置示例文件 |
---
## Python 沙箱执行
### 相关页面
相关主题：[测试能力总览](#page-testing-capabilities), [工具注册与工具集](#page-tool-registry)
相关源码文件
以下源码文件用于生成本页说明：
- [testzeus_hercules/core/tools/execute_python_sandbox.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/execute_python_sandbox.py)
- [testzeus_hercules/core/agents/executor_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/executor_nav_agent.py)
- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)
# Python 沙箱执行
## 概述
Python 沙箱执行（Python Sandbox Execution）是 TestZeus Hercules 框架的核心安全执行机制，用于在隔离的 Python 环境中安全地执行动态生成的 Python 脚本。该系统通过多层次的模块注入、租户隔离和超时控制，确保浏览器自动化测试和 API 测试过程中的代码执行安全性和可控性。
沙箱系统允许测试代理（Agent）在受控环境中执行 Python 代码，同时提供对浏览器对象（page、browser、context）、配置信息和日志系统的访问能力。资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py:1-50]()
## 架构设计
### 执行模型
沙箱执行采用客户端-服务端架构，脚本在隔离的 Python 环境中运行，通过预定义的注入模块与外部系统交互。执行流程如下：
```mermaid
graph TD
A[Agent 请求执行] --> B[解析脚本内容]
B --> C{检查注入配置}
C -->|租户注入| D[加载租户特定模块]
C -->|配置注入| E[加载配置文件模块]
C -->|自定义注入| F[解析 JSON 注入]
D --> G[合并所有注入模块]
E --> G
F --> G
G --> H[创建沙箱执行环境]
H --> I[执行 Python 脚本]
I --> J{执行结果}
J -->|成功| K[返回执行结果]
J -->|超时| L[超时错误]
J -->|异常| M[捕获并返回错误]
```
### 模块注入层级
沙箱系统支持三层模块注入机制，按优先级从高到低依次为：
1. **内置核心模块**：re、datetime、pathlib、uuid
2. **租户特定模块**：根据 SANDBOX_TENANT_ID 配置自动加载
3. **自定义注入**：通过环境变量或配置动态指定
资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py:25-60]()
## 核心注入系统
### 内置核心模块
所有脚本执行环境默认提供以下核心模块：
| 模块名称 | 功能描述 |
|---------|---------|
| `re` | 正则表达式处理 |
| `datetime` | 日期时间操作 |
| `pathlib` | 路径操作 |
| `uuid` | UUID 生成 |
资料来源：[testzeus_hercules/core/agents/executor_nav_agent.py:40-43]()
### 租户特定模块注入
租户注入系统根据配置的环境变量 `SANDBOX_TENANT_ID` 动态加载不同的模块集合：
| 租户标识 | 可用模块 |
|---------|---------|
| `executor_agent` | requests, pandas, numpy, BeautifulSoup, hercules_utils |
| `data_agent` | pandas, numpy |
| `api_agent` | requests, httpx |
租户注入逻辑实现于 `_get_tenant_injections()` 方法，该方法在沙箱初始化时自动调用，遍历配置中定义的模块列表并逐一导入。资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py:30-55]()
### 配置驱动注入
通过配置文件中的 `SANDBOX_PACKAGES` 选项可以动态指定要加载的包列表。配置格式如下：
```python
SANDBOX_PACKAGES="requests,pandas,numpy"
```
系统会按照逗号分隔的包名列表逐个导入，并记录成功加载的模块信息。资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py:58-75]()
### 自定义注入
`_parse_custom_injections()` 函数支持从 JSON 字符串解析自定义模块注入配置。这种方式允许在每次调用时动态指定要注入的模块，无需修改全局配置。资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py:78-90]()
## 自动访问对象
脚本执行时可自动访问以下预定义对象，这些对象由执行框架在调用时自动注入到沙箱环境中：
| 对象名称 | 类型 | 描述 |
|---------|------|------|
| `page` | Playwright Page | 当前浏览器页面对象 |
| `browser` | Playwright Browser | 浏览器实例 |
| `context` | Playwright BrowserContext | 浏览器上下文 |
| `playwright_manager` | Manager | Playwright 管理器实例 |
| `logger` | Logger | 日志记录器 |
| `config` | Config | 全局配置对象 |
资料来源：[testzeus_hercules/core/agents/executor_nav_agent.py:15-22]()
## 执行参数与配置
### 执行超时管理
| 参数 | 默认值 | 说明 |
|-----|-------|------|
| 执行超时 | 300 秒 | 单次脚本执行的最长允许时间 |
| 超时处理 | 区分超时错误与执行错误 | 超时错误会明确标记 |
超时机制在脚本执行层和工具调用层均有所体现，确保长时运行的脚本能够被正确终止并报告。资料来源：[testzeus_hercules/core/agents/executor_nav_agent.py:50-55]()
### 命令行配置参数
沙箱系统可通过以下命令行参数进行配置：
| 参数 | 类型 | 说明 |
|-----|------|------|
| `--sandbox-tenant-id` | str | 指定租户标识以加载对应的模块集合 |
| `--reuse-vector-db` | flag | 重用现有向量数据库而非新建 |
资料来源：[testzeus_hercules/config.py:80-90]()
## 执行结果处理
### 成功响应格式
```json
{
"status": "success",
"stdout": "脚本标准输出",
"stderr": "脚本标准错误",
"return_value": "函数返回值或 _sandbox_result",
"execution_time": 1.23
}
```
### 错误处理机制
沙箱系统捕获以下类型的错误并返回结构化响应：
| 错误类型 | 处理方式 |
|---------|---------|
| 语法错误 | 捕获 SyntaxError，返回错误详情和行号 |
| 运行时异常 | 返回完整堆栈跟踪信息 |
| 超时错误 | 标记为超时错误，中断执行 |
| 导入错误 | 记录警告，返回可用模块列表 |
资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py:40-45]()
## 脚本编写规范
### 基本结构
```python
# 脚本可包含函数或直接执行代码
async def main():
# 主执行逻辑
result = await page.evaluate("document.title")
return {"title": result}
# 设置返回值
_sandbox_result = main() if 'main' in dir() else None
```
### 函数调用模式
当脚本包含多个函数时，可通过 `function_name` 和 `function_args` 参数指定要调用的函数：
```python
# 同步函数
def process_data(data):
return data.upper()
# 异步函数
async def fetch_url(url):
import requests
return requests.get(url).text
```
### 返回值约定
- **变量模式**：设置 `_sandbox_result` 变量返回自定义数据
- **返回值模式**：主函数直接返回数据对象
- **JSON 兼容**：返回值需为 JSON 可序列化对象
资料来源：[testzeus_hercules/core/agents/executor_nav_agent.py:35-50]()
## 安全机制
### 模块隔离
不同租户之间的模块注入相互隔离，租户 A 无法访问租户 B 的专属模块，防止潜在的模块冲突和安全风险。
### 导入失败处理
当模块导入失败时，系统记录警告日志而非抛出异常，确保沙箱的鲁棒性：
```python
try:
injections[module_name] = __import__(module_name)
except ImportError:
logger.warning(f"Module {module_name} not available for tenant {tenant_id}")
```
### 环境变量配置
关键安全参数通过环境变量控制：
| 环境变量 | 用途 |
|---------|------|
| `SANDBOX_TENANT_ID` | 租户标识 |
| `SANDBOX_CUSTOM_INJECTIONS` | 自定义模块 JSON 配置 |
| `SANDBOX_PACKAGES` | 配置文件中的包列表 |
资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py:45-50]()
## 最佳实践
### 1. 选择合适的租户类型
根据测试场景选择对应的租户标识，避免加载不必要的模块以减少安全风险。
### 2. 设置合理的超时时间
对于网络请求或复杂计算类脚本，适当延长超时时间；对于简单 DOM 操作，使用默认值即可。
### 3. 错误处理
在脚本中实现适当的异常捕获，提高测试的稳定性：
```python
try:
result = page.locator("#submit").click()
except Exception as e:
logger.error(f"Click failed: {e}")
raise
```
### 4. 返回结构化数据
始终返回 JSON 兼容的字典或列表结构，便于上层系统解析和处理。
## 总结
Python 沙箱执行系统为 TestZeus Hercules 提供了安全、可控的动态代码执行能力。通过多层级模块注入、租户隔离、超时控制和全面的错误处理机制，该系统能够在保证执行安全性的同时，为自动化测试代理提供强大的脚本执行能力。开发者应遵循上述最佳实践，充分利用沙箱系统提供的功能，同时注意安全配置的正确使用。
---
---
## Doramagic 踩坑日志
项目：test-zeus-ai/testzeus-hercules
摘要：发现 13 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 来源证据：0.1.1。
## 1. 配置坑 · 来源证据：0.1.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：0.1.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_87e563b6a81f4a529799ac528ee21610 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.1 | 来源类型 github_release 暴露的待验证使用条件。
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 来源证据：0.0.40
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.0.40
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_02c1945d063b4151a3df1526b85e9d50 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.0.40 | 来源类型 github_release 暴露的待验证使用条件。
## 4. 维护坑 · 来源证据：0.1.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1d1eb9ae89f04ff9b339c73cc932f2f7 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.0 | 来源类型 github_release 暴露的待验证使用条件。
## 5. 维护坑 · 来源证据：0.1.2
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.2
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e0e02b07ea6845eaac8c4f18871aaa32 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.2 | 来源类型 github_release 暴露的待验证使用条件。
## 6. 维护坑 · 来源证据：0.1.6
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.6
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_41cf6e34c47b4f929a67426b258b8fd8 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.6 | 来源类型 github_release 暴露的待验证使用条件。
## 7. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | last_activity_observed missing
## 8. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | no_demo; severity=medium
## 9. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | no_demo; severity=medium
## 10. 安全/权限坑 · 来源证据：0.1.4
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.1.4
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d6aeb053b3a541778b07c0bca68c5c82 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.4 | 来源类型 github_release 暴露的待验证使用条件。
## 11. 安全/权限坑 · 来源证据：0.2.2
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.2.2
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_963ec16ebc32452a8ca13e8ebc1aed96 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.2.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 12. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | issue_or_pr_quality=unknown
## 13. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | release_recency=unknown