简介

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

核心架构

系统组件

graph TD
    subgraph "前端层"
        FE[前端界面<br/>非交互式/交互式CDP渲染器]
    end
    
    subgraph "核心引擎"
        NAV[导航代理<br/>ExecutorNavAgent]
        RESP[响应解析器<br/>ResponseParser]
        TREE[无障碍树解析器<br/>AccessibilityTree]
    end
    
    subgraph "工具层"
        API[API安全调用<br/>APISecCalls]
        SANDBOX[Python沙箱执行]
        BROWSER[浏览器控制]
    end
    
    subgraph "配置层"
        CFG[配置解析器<br/>Config]
        TELE[遥测模块<br/>Telemetry]
    end
    
    FE --> NAV
    NAV --> RESP
    NAV --> TREE
    NAV --> API
    NAV --> SANDBOX
    NAV --> BROWSER
    NAV --> CFG
    NAV --> TELE

技术栈

资料来源：testzeus_hercules/core/tools/api_sec_calls.py:1 资料来源：testzeus_hercules/core/agents/executor_nav_agent.py:1

核心功能模块

1. 导航代理 (Navigation Agent)

导航代理是系统的核心决策单元，负责：

• 分析测试指令并规划执行步骤
• 调用浏览器工具执行用户交互
• 处理脚本执行和结果验证
• 管理错误恢复和重试逻辑

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

#### 交互式渲染器 支持用户直接与远程页面进行交互，包括：

• 点击操作
• 拖拽操作
• 文本输入

<img id="screencast" alt="Screencast will appear here" />
<input id="dummyInput" type="text" />
<p>Click, drag, and type into the remote page here.</p>

资料来源：frontend/interactive/index.html:1

5. 遥测模块 (Telemetry)

负责收集和上报安装数据：

• 生成唯一的安装 ID
• 记录用户信息（可手动配置）
• 通过 Sentry SDK 进行错误追踪

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 规范验证
• 漏洞扫描
• 自定义安全测试用例

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

配置与命令行选项

基础配置

LLM 配置

资料来源：testzeus_hercules/config.py:1

浏览器配置

测试执行选项

沙箱配置

批量执行模式

当启用 --bulk 参数时，系统会扫描项目根目录下的 tests 文件夹，并依次执行其中的测试用例：

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 格式的测试用例。

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

开发与贡献

项目设置

# 创建虚拟环境
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

快速开始

安装

# 通过 PyPI 安装
pip install testzeus-hercules

# 或通过 Docker
docker pull testzeus/hercules

基本使用

# 运行单个测试
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

技术特点

概述

Testzeus Hercules 是一个开源的端到端AI测试代理框架，其系统架构围绕浏览器自动化、AI代理协作和脚本执行三大核心能力构建。该框架采用模块化设计，通过动态加载机制和配置驱动的架构实现高度可扩展性。资料来源：testzeus_hercules/core/__init__.py:1-20

核心架构分层

系统架构从上至下分为四个主要层次：

资料来源：testzeus_hercules/core/simple_hercules.py:1-50

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

主要配置类别：

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. 评估阶段：验证执行结果，更新状态

# 核心执行伪代码
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 执行代理职责

#### 3.2 执行代理工作流

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 沙箱注入机制

沙箱支持三类依赖注入：

# 租户注入逻辑
if tenant_id == "executor_agent":
    injections['hercules_utils'] = utils

# 配置驱动注入
sandbox_packages = config.get("SANDBOX_PACKAGES", "").split(",")

#### 4.2 沙箱可用上下文

执行脚本自动获得以下上下文变量：

5. 工具系统

工具系统通过动态导入机制加载，存储在 testzeus_hercules/core/extra_tools/ 目录。资料来源：testzeus_hercules/core/extra_tools/__init__.py:1-25

# 动态工具加载
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)

#### 主要内置工具

6. 响应解析系统

响应解析器位于 testzeus_hercules/utils/response_parser.py，负责解析AI代理返回的消息。资料来源：testzeus_hercules/utils/response_parser.py:1-30

解析流程：

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

graph LR
    A[Sentry SDK] --> B[错误收集]
    A --> C[安装ID生成]
    C --> D[installation_id.txt]
    B --> E[Sentry Dashboard]

安装ID管理：

• 自动生成UUID作为安装标识
• 支持手动模式下的用户邮箱收集
• 数据存储在 installation_id.txt

模块间交互

主执行流程

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 函数向调度器报告执行状态：

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,
)

配置参数总览

浏览器配置参数

LLM配置参数

Portkey集成参数

架构设计原则

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代理工作，工具层提供浏览器自动化和脚本执行能力，基础设施层保障配置的统一管理和遥测数据的收集。该架构支持从简单的端到端测试到复杂的多步骤业务流程验证。

概述

TestZeus-Hercules 是一个开源的端到端 AI 测试代理框架，其核心架构基于多代理系统（Multi-Agent System）设计。该系统通过协调多个专门的 AI 代理来执行复杂的自动化测试任务，主要包括浏览器导航代理（BrowserNavAgent）、API 执行代理和高级规划代理等组件。

多代理系统的设计目标是：

• 分工协作：将复杂的测试任务分解为多个子任务，由专门的代理负责执行
• LLM 驱动：每个代理由大语言模型驱动，具备独立的推理和决策能力
• 顺序执行：通过用户代理（UserProxyAgent）协调多个代理之间的消息传递和任务调度
• 脚本执行：通过 Python 沙箱环境执行自动化测试脚本，实现浏览器控制和 API 调用

资料来源：testzeus_hercules/core/simple_hercules.py:1-50

系统架构

整体架构图

graph TD
    subgraph 用户层
        User[用户/CLI]
    end

    subgraph 核心编排层
        Hercules[TestZeus Hercules 主类]
        UserProxy[UserProxyAgent<br/>用户代理]
    end

    subgraph 代理层
        PlannerAgent[高级规划代理<br/>HighLevelPlannerAgent]
        BrowserNavAgent[浏览器导航代理<br/>BrowserNavAgent]
        ExecutorAgent[执行代理<br/>ExecutorAgent]
        ApiNavAgent[API导航代理<br/>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

代理类型说明

资料来源：testzeus_hercules/core/simple_hercules.py:80-150

代理创建流程

主类初始化

TestZeusHercules 主类负责初始化所有代理实例。初始化过程遵循以下步骤：

class TestZeusHercules:
    def __init__(self, config: HerculesConfig):
        self.config = config
        self._init_agents()

代理工厂模式

系统采用工厂模式创建代理，每个代理都有独立的创建方法：

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 模型，提供灵活的架构设计：

# 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 设置：

--agents-llm-config-file           # 代理LLM配置文件路径
--agents-llm-config-file-ref-key   # 配置文件引用键

Portkey 集成

支持通过 Portkey 进行 LLM 路由和负载均衡：

--enable-portkey           # 启用Portkey集成
--portkey-api-key          # Portkey API密钥
--portkey-strategy         # 路由策略: fallback 或 loadbalance

资料来源：testzeus_hercules/config.py:50-100

代理通信机制

消息传递模式

代理之间通过消息传递进行协作，采用以下模式：

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: 返回执行结果

终止条件判断

每个代理都有独立的终止消息判断逻辑：

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 沙箱中执行测试脚本：

graph TD
    A[接收任务指令] --> B[选择脚本文件]
    B --> C[识别目标函数]
    C --> D[准备执行参数]
    D --> E[调用沙箱执行]
    E --> F{执行结果检查}
    F -->|成功| G[解析输出结果]
    F -->|失败| H[错误处理]
    G --> I[返回结果给用户代理]
    H --> I

执行配置

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. 状态验证：检查页面元素状态和内容

执行模式

# 顺序函数执行模式
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 响应：

def parse_response(message: str) -> dict[str, Any]:
    """解析浏览器代理响应"""
    # 处理 ```json ``` 代码块
    # 解析 JSON 数据
    # 处理解析失败情况

资料来源：testzeus_hercules/utils/response_parser.py:1-40

批量执行模式

目录扫描

系统支持批量执行测试目录中的所有测试用例：

graph LR
    A[tests/ 目录] --> B[扫描子文件夹]
    B --> C[遍历测试文件夹]
    C --> D[逐个执行测试]
    D --> E{是否完成}
    E -->|否| C
    E -->|是| F[汇总报告]

执行触发条件

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

配置选项汇总

命令行参数

资料来源：testzeus_hercules/config.py:100-150

代理注册机制

代理映射

系统维护一个代理注册表，用于追踪所有活跃的代理实例：

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,
}

访问模式

通过代理名称字符串访问对应的代理实例：

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 提供商和配置
• 可靠性：完善的错误处理和日志机制
• 自动化：从任务规划到执行的全流程自动化

概述

工具注册与工具集是 Testzeus Hercules 自动化测试框架的核心组件，负责管理和加载所有可用的测试工具。这些工具通过动态导入机制注册到系统中，使 AI Agent 能够执行各种浏览器操作、API 调用、安全扫描等任务。

工具系统的设计遵循模块化原则，每个工具都是独立的功能单元，通过统一的注册机制暴露给上层调用者。框架使用 pkgutil 动态发现和导入所有工具模块，无需手动维护导入列表。资料来源：testzeus_hercules/core/tools/__init__.py:1-17

工具注册机制

动态模块发现

工具注册采用 Python 的 pkgutil 模块实现动态发现。系统会扫描 testzeus_hercules.core.tools 包目录，自动识别并加载所有非私有模块。这种设计使得添加新工具变得简单——只需在 tools 目录下创建新的 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

注册流程

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[所有模块处理完成]

工具属性过滤规则

在导入每个模块时，系统会遍历模块的所有属性，并按照特定规则进行过滤：

资料来源：testzeus_hercules/core/tools/__init__.py:17-18

核心工具集

浏览器操作工具

浏览器操作工具集提供页面导航、元素交互等核心功能。

资料来源：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 调用工具支持与后端服务交互和安全扫描。

资料来源：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 代码脚本。

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" 时才加载扩展工具。

if get_global_conf().get_load_extra_tools().lower().strip() != "false":
    # 执行扩展工具加载

资料来源：testzeus_hercules/core/extra_tools/__init__.py:13-15

配置驱动的包注入

沙箱环境支持通过配置文件动态注入 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

工具执行上下文

脚本执行环境

在 execute_python_sandbox 工具中执行的 Python 脚本会自动获得以下内置对象的访问权限：

资料来源：testzeus_hercules/core/agents/executor_nav_agent.py:10-14

脚本执行约束

框架对脚本执行有明确的约束和规范：

1. 顺序执行 - 一次只执行一个脚本或函数，等待结果后再继续下一步
2. 结果验证 - 必须验证每个脚本的执行结果，检查执行状态
3. 错误处理 - 适当处理执行错误、超时和异常
4. 参数准确性 - 提供正确的文件路径和超时值

资料来源：testzeus_hercules/core/agents/executor_nav_agent.py:20-40

工具调用示例

基本调用模式

# 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
)

配置注入调用

# 使用自定义注入执行脚本
result = execute_python_sandbox(
    script_path="scripts/data_analysis.py",
    custom_injections_json='{"pandas": "pandas", "numpy": "numpy"}'
)

响应解析

框架提供统一的响应解析机制处理 LLM 返回的结果：

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

配置与初始化

全局配置检查点

工具系统在初始化时会检查多个配置选项：

资料来源：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. 确保工具函数有清晰的文档字符串

工具开发规范

"""
工具模块示例
"""

def my_tool(param1: str, param2: int) -> dict:
    """
    工具功能描述
    
    Args:
        param1: 参数1说明
        param2: 参数2说明
        
    Returns:
        dict: 返回值说明
    """
    # 实现逻辑
    return {"status": "success"}

总结

工具注册与工具集系统为 Testzeus Hercules 提供了高度可扩展的架构。动态模块发现机制使得添加新工具变得简单，无需修改导入代码；条件加载机制允许灵活控制工具集的规模；沙箱执行环境则提供了安全的脚本执行能力。这些设计使得框架能够适应各种复杂的端到端测试场景。

概述

记忆管理系统（Memory Management System）是TestZeus Hercules的核心组件，负责管理和维护AI代理在测试执行过程中的上下文信息、长期记忆和状态数据。该系统通过整合静态数据和动态数据，为代理提供持续一致的测试环境感知能力。

记忆管理系统的主要职责包括：

• 加载和管理项目级静态数据（如测试数据文件、配置信息）
• 维护运行时的动态上下文状态
• 提供检索增强生成（RAG）能力，支持向量数据库查询
• 在测试执行过程中存储和恢复中间状态
• 压缩和优化提示内容以适应上下文窗口限制

资料来源：testzeus_hercules/core/memory/static_ltm.py:1-20

概述

Playwright 浏览器自动化模块是 TestZeus Hercules 项目的核心组件，负责管理与浏览器的所有交互操作。该模块基于 Playwright 框架构建，提供了一套完整的浏览器控制能力，包括页面导航、元素交互、DOM 提取、事件监听等高级功能。

该系统的主要职责包括：

• 管理 Playwright 实例的启动、初始化和关闭生命周期
• 处理浏览器上下文和多标签页管理
• 捕获控制台日志和请求/响应数据
• 提供 DOM 观察者机制以检测页面变化
• 生成无障碍信息树用于 AI Agent 决策
• 执行截图和视频录制

资料来源：testzeus_hercules/core/playwright_manager.py:1-50

核心架构

组件关系图

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

#### 初始化参数

资料来源：testzeus_hercules/core/playwright_manager.py:20-45

#### 核心方法

资料来源：testzeus_hercules/core/playwright_manager.py:45-80

生命周期管理

初始化流程

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 方法采用延迟初始化模式，确保只初始化一次：

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 代理调用：

@tool(
    agent_names=["browser_nav_agent"],
    description="""工具描述文本""",
    name="tool_name",
)
async def tool_function(params):
    # 实现代码

资料来源：testzeus_hercules/core/tools/open_url.py:1-30

核心工具列表

资料来源：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 工具负责页面导航，支持多种导航策略：

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

元素交互

#### 悬停操作

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

#### 下拉选择

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

#### 按键操作

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 变化监听功能，支持订阅和取消订阅模式：

graph LR
    A[DOM 变化] --> B[MutationObserver]
    B --> C{订阅者数量}
    C -->|有订阅者| D[通知回调函数]
    C -->|无订阅者| E[忽略]
    D --> F[detect_dom_changes]
    F --> G[dom_changes_detected]

主要函数：

资料来源：testzeus_hercules/utils/dom_mutation_observer.py:1-50

DOM 辅助工具

dom_helper 模块提供多种 DOM 操作工具：

资料来源：testzeus_hercules/utils/dom_helper.py:1-100

无障碍信息树

get_detailed_accessibility_tree 模块生成页面的无障碍信息树，供 AI Agent 理解页面结构：

async def do_get_accessibility_info(page) -> str:
    """获取详细的无障碍信息树"""
    # 实现代码

关键函数：

资料来源：testzeus_hercules/utils/get_detailed_accessibility_tree.py:1-80

日志与遥测

浏览器日志

BrowserLogger 负责捕获和控制浏览器相关的日志信息：

资料来源：testzeus_hercules/core/browser_logger.py:1-50

遥测系统

系统集成 Sentry 进行错误追踪和遥测数据收集：

def add_event(event_type: EventType, event_data: EventData):
    """记录交互事件"""

资料来源：testzeus_hercules/telemetry.py:1-100

配置选项

命令行参数

通过命令行可以配置浏览器行为：

资料来源：testzeus_hercules/config.py:1-100

前端渲染器

项目包含两个 HTML 前端用于 CDP 流渲染：

非交互模式

文件位置：frontend/non-interactive/index.html

功能：

• 实时显示浏览器截图流
• 显示文本输出信息
• 简单的状态显示

交互模式

文件位置：frontend/interactive/index.html

功能：

• 支持鼠标点击和拖拽
• 支持键盘输入
• 虚拟输入框捕获焦点
• 跨设备交互支持

工作流程示例

页面内容抓取流程

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[返回文本内容]

元素交互流程

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 选择器：

# 推荐
selector = "[md='element_id']"

# 内部会自动处理
if "md=" not in selector:
    selector = f"[md='{selector}']"

资料来源：testzeus_hercules/core/tools/hover.py:25-30

异步操作

所有 Playwright 操作必须使用 async/await 模式：

async def example():
    browser_manager = PlaywrightManager()
    page = await browser_manager.get_current_page()
    await page.click("[md='button_id']")

错误处理

使用 try-except 捕获 Playwright 超时和状态错误：

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 提供了可靠的浏览器控制能力。

概述

TestZeus Hercules 是一个开源的端到端 AI 测试代理平台，专注于自动化测试能力建设。该系统通过多智能体架构实现对 Web 应用、API 接口、数据库操作的全面自动化测试覆盖。测试框架支持从传统的 UI 交互测试到高级的安全扫描和可视化验证，为测试团队提供了一站式解决方案。

Hercules 的核心设计理念是将人工智能融入软件测试生命周期的各个环节，从测试用例生成、执行、到结果验证，全部实现智能化处理。系统基于 Playwright 浏览器自动化框架，结合大型语言模型（LLM）的推理能力，能够自主理解和执行复杂的测试场景。

系统架构

整体架构图

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

核心组件说明

测试类型支持

Web UI 自动化测试

Web UI 测试是 Hercules 的核心能力之一。系统通过 Playwright 框架实现对现代 Web 应用的全面自动化测试覆盖，支持 Chrome、Firefox 等多浏览器渠道。

#### 浏览器配置选项

系统提供丰富的浏览器配置选项，支持不同测试场景的需求：

资料来源：testzeus_hercules/config.py:85-112

#### 脚本执行机制

Executor Nav Agent 负责在浏览器上下文中执行测试脚本。代理接收导航指令后，通过 Playwright API 执行相应的用户交互操作。

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 helper_scripts/generate_api_functional_gherkin_test.py \
    --output ./tests/api \
    --model o1-preview \
    --number_of_testcase 100 \
    openapi_spec.yaml

# 安全测试生成
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 流渲染模式：

前端通过 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

可用上下文变量

执行脚本时可自动访问以下上下文变量：

模块注入机制

系统支持根据租户配置动态注入额外模块：

# 环境变量配置
SANDBOX_TENANT_ID=executor_agent
SANDBOX_CUSTOM_INJECTIONS='["requests", "pandas", "bs4"]'
SANDBOX_PACKAGES='["numpy", "json"]'

注入的模块可直接在脚本中使用，无需额外导入操作。

配置驱动注入

通过配置文件可以定义沙箱可用的包列表：

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

测试用例生成流程

graph LR
    A[OpenAPI Spec] --> B[生成器脚本]
    B --> C[LLM 模型]
    C --> D[Gherkin 场景]
    D --> E[测试数据文件]
    E --> F[执行测试]

输出格式规范

生成的 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. 回退到键值对提取模式

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 模型配置

#### Portkey 集成

#### 测试执行选项

遥测与监控

安装标识管理

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（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 与浏览器建立长连接，实时接收浏览器的状态更新并发送控制指令。

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 服务器配置

MCP 服务器通过 JSON 格式的配置文件进行管理。项目中提供了 mcp_servers.example.json 作为配置模板，开发者需要创建 mcp_servers.json 文件来定义实际的 MCP 服务器配置。

配置文件主要包含以下结构：

{
  "mcp_servers": [
    {
      "name": "server_name",
      "command": "command_to_run",
      "args": ["arg1", "arg2"],
      "env": {
        "KEY": "value"
      }
    }
  ]
}

资料来源：mcp_servers.example.json

配置参数说明

MCP 导航代理

核心功能

MCP 导航代理（mcp_nav_agent.py）是整个 MCP 集成的核心组件，负责协调浏览器操作和任务执行。该代理继承了 NavigatorAgentBase 基类，实现了浏览器导航和控制的核心逻辑。

导航代理的主要职责包括：

• 任务解析：解析 AI Agent 的自然语言指令，转换为可执行的浏览器操作
• 脚本执行：通过 Python 沙箱执行浏览器控制脚本
• 结果验证：验证每个操作的结果，确保任务正确完成
• 错误处理：捕获并处理执行过程中的各种异常情况

资料来源：testzeus_hercules/core/agents/mcp_nav_agent.py:1-50

执行流程

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 能够以统一的方式执行各种任务。

资料来源：testzeus_hercules/core/tools/mcp_tools.py:1-30

工具使用示例

MCP 工具通过统一的接口暴露给 AI Agent，每个工具都包含以下标准属性：

• tool_name：工具名称，用于标识具体操作
• function_name：对应的函数名
• function_args：函数参数对象
• timeout：执行超时时间

# 工具调用示例结构
{
    "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 添加实际配置 ``

1. 初始化 MCP 连接

在测试脚本中导入并初始化 MCP 模块：

``python from testzeus_hercules.core.tools.mcp_tools import MCPTools from testzeus_hercules.utils.mcp_helper import MCPHelper ``

1. 执行浏览器操作

使用 MCP 工具执行所需的浏览器操作：

``python tools = MCPTools() await tools.navigate_to("https://example.com") ``

高级配置

#### 自定义 MCP 服务器

可以通过配置文件添加自定义的 MCP 服务器：

{
  "mcp_servers": [
    {
      "name": "custom_server",
      "command": "npx",
      "args": ["-y", "@custom/mcp-server"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  ]
}

#### 环境变量配置

最佳实践

性能优化

1. 减少不必要的截图：截图操作会消耗较多资源，应在必要时使用
2. 批量操作：将多个相关操作组合执行，减少网络往返
3. 连接复用：保持长连接避免重复建立的开销
4. 超时设置：根据网络状况合理设置超时时间

稳定性保障

1. 错误重试：实现指数退避策略处理临时性失败
2. 状态验证：每个关键操作后验证预期结果
3. 日志记录：详细记录操作日志便于问题排查
4. 资源清理：确保操作完成后释放资源

故障排查

常见问题

调试技巧

1. 启用详细日志：设置日志级别为 DEBUG 获取更多信息
2. 单步执行：逐步执行操作定位问题发生位置
3. 截图验证：在关键步骤保存截图辅助排查
4. 状态检查：使用 MCP Helper 查看当前连接状态

相关资源

• 项目文档：docs/MCP_Usage.md
• 示例配置：mcp_servers.example.json
• 核心源码：testzeus_hercules/core/agents/mcp_nav_agent.py

概述

testzeus-hercules 提供了完整的 API 功能测试与安全测试解决方案。该系统通过 OpenAPI 规范文件自动生成 Gherkin 格式的测试用例，并支持使用 LLM（大语言模型）智能生成针对 API 功能的测试场景以及针对安全漏洞的测试场景。

API 测试模块主要位于 testzeus_hercules/core/tools/ 目录下，而辅助脚本则位于 helper_scripts/ 目录，用于从 OpenAPI 规范自动生成测试用例。

核心组件

测试工具模块

测试生成脚本

架构设计

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

组件交互流程

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

命令行参数

使用方法

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

核心函数流程

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

安全测试生成器配置

使用方法

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 格式：

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 相关选项：

资料来源：testzeus_hercules/config.py:1-60

Portkey 集成配置

系统支持使用 Portkey 进行 LLM 路由：

配置文件方式

可以使用 JSON 配置文件定义各代理的 LLM 配置：

{
    "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

执行测试

批量执行模式

python -m testzeus_hercules --bulk --test-data-path ./tests/data

使用自定义测试数据

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: 脚本会打印错误信息并退出：

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: 脚本支持一次性处理多个文件：

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 端点是否可达

相关文件索引

概述

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 环境中运行，通过预定义的注入模块与外部系统交互。执行流程如下：

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

核心注入系统

内置核心模块

所有脚本执行环境默认提供以下核心模块：

资料来源：testzeus_hercules/core/agents/executor_nav_agent.py:40-43

租户特定模块注入

租户注入系统根据配置的环境变量 SANDBOX_TENANT_ID 动态加载不同的模块集合：

租户注入逻辑实现于 _get_tenant_injections() 方法，该方法在沙箱初始化时自动调用，遍历配置中定义的模块列表并逐一导入。资料来源：testzeus_hercules/core/tools/execute_python_sandbox.py:30-55

配置驱动注入

通过配置文件中的 SANDBOX_PACKAGES 选项可以动态指定要加载的包列表。配置格式如下：

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

自动访问对象

脚本执行时可自动访问以下预定义对象，这些对象由执行框架在调用时自动注入到沙箱环境中：

资料来源：testzeus_hercules/core/agents/executor_nav_agent.py:15-22

执行参数与配置

执行超时管理

超时机制在脚本执行层和工具调用层均有所体现，确保长时运行的脚本能够被正确终止并报告。资料来源：testzeus_hercules/core/agents/executor_nav_agent.py:50-55

命令行配置参数

沙箱系统可通过以下命令行参数进行配置：

资料来源：testzeus_hercules/config.py:80-90

执行结果处理

成功响应格式

{
  "status": "success",
  "stdout": "脚本标准输出",
  "stderr": "脚本标准错误",
  "return_value": "函数返回值或 _sandbox_result",
  "execution_time": 1.23
}

错误处理机制

沙箱系统捕获以下类型的错误并返回结构化响应：

资料来源：testzeus_hercules/core/tools/execute_python_sandbox.py:40-45

脚本编写规范

基本结构

# 脚本可包含函数或直接执行代码
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 参数指定要调用的函数：

# 同步函数
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 的专属模块，防止潜在的模块冲突和安全风险。

导入失败处理

当模块导入失败时，系统记录警告日志而非抛出异常，确保沙箱的鲁棒性：

try:
    injections[module_name] = __import__(module_name)
except ImportError:
    logger.warning(f"Module {module_name} not available for tenant {tenant_id}")

环境变量配置

关键安全参数通过环境变量控制：

资料来源：testzeus_hercules/core/tools/execute_python_sandbox.py:45-50

最佳实践

1. 选择合适的租户类型

根据测试场景选择对应的租户标识，避免加载不必要的模块以减少安全风险。

2. 设置合理的超时时间

对于网络请求或复杂计算类脚本，适当延长超时时间；对于简单 DOM 操作，使用默认值即可。

3. 错误处理

在脚本中实现适当的异常捕获，提高测试的稳定性：

try:
    result = page.locator("#submit").click()
except Exception as e:
    logger.error(f"Click failed: {e}")
    raise

4. 返回结构化数据

始终返回 JSON 兼容的字典或列表结构，便于上层系统解析和处理。

总结

Python 沙箱执行系统为 TestZeus Hercules 提供了安全、可控的动态代码执行能力。通过多层级模块注入、租户隔离、超时控制和全面的错误处理机制，该系统能够在保证执行安全性的同时，为自动化测试代理提供强大的脚本执行能力。开发者应遵循上述最佳实践，充分利用沙箱系统提供的功能，同时注意安全配置的正确使用。

Pitfall Log / 踩坑日志

项目：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