{
"canonical_name": "test-zeus-ai/testzeus-hercules",
"compilation_id": "pack_59efac94556e431b95606f6a9ff03dc4",
"created_at": "2026-05-17T01:21:49.167626+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install testzeus-hercules` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install testzeus-hercules",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_08e69d225efa4d5797c2e5c9fea32966"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_b19624f630f0ec0067e9a2bb69969276",
"canonical_name": "test-zeus-ai/testzeus-hercules",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/test-zeus-ai/testzeus-hercules",
"slug": "testzeus-hercules",
"source_packet_id": "phit_653011fc0af34bbcbfa5a47615f5e8db",
"source_validation_id": "dval_9c77890b81fa43109bad142f3501b30e"
},
"merchandising": {
"best_for": "需要安全审查与权限治理能力，并使用 local_cli的用户",
"github_forks": 152,
"github_stars": 1014,
"one_liner_en": "Hercules is the world’s first open-source testing agent, enabling UI, API, Security, Accessibility, and Visual validations – all without code or maintenance. Automate testing effortlessly and let Hercules handle the heavy lifting! ⚡",
"one_liner_zh": "Hercules is the world’s first open-source testing agent, enabling UI, API, Security, Accessibility, and Visual validations – all without code or maintenance. Automate testing effortlessly and let Hercules handle the heavy lifting! ⚡",
"primary_category": {
"category_id": "security-permissions",
"confidence": "high",
"name_en": "Security & Permissions",
"name_zh": "安全审查与权限治理",
"reason": "strong category phrase match from project identity and outcome"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "testzeus-hercules",
"title_zh": "testzeus-hercules 能力包",
"visible_tags": [
{
"label_en": "Security & Permissions",
"label_zh": "安全审查与权限治理",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-security-permissions",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Natural-language Web Actions",
"label_zh": "自然语言网页操作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-natural-language-web-actions",
"type": "core_capability"
},
{
"label_en": "Page Observation and Action Planning",
"label_zh": "页面观察与动作规划",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-page-observation-and-action-planning",
"type": "workflow_pattern"
},
{
"label_en": "Structured Data Extraction",
"label_zh": "结构化数据提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-structured-data-extraction",
"type": "selection_signal"
}
]
},
"packet_id": "phit_653011fc0af34bbcbfa5a47615f5e8db",
"page_model": {
"artifacts": {
"artifact_slug": "testzeus-hercules",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install testzeus-hercules",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/test-zeus-ai/testzeus-hercules#readme",
"verified": true
}
],
"display_tags": [
"安全审查与权限治理",
"网页任务自动化",
"自然语言网页操作",
"页面观察与动作规划",
"结构化数据提取"
],
"eyebrow": "安全审查与权限治理",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要安全审查与权限治理能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Hercules is the world’s first open-source testing agent, enabling UI, API, Security, Accessibility, and Visual validations – all without code or maintenance. Automate testing effortlessly and let Hercules handle the heavy lifting! ⚡"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：0.1.1",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_87e563b6a81f4a529799ac528ee21610 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：0.1.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.0.40",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_02c1945d063b4151a3df1526b85e9d50 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.0.40 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：0.0.40",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.0",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_1d1eb9ae89f04ff9b339c73cc932f2f7 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：0.1.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.2",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_e0e02b07ea6845eaac8c4f18871aaa32 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：0.1.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.6",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_41cf6e34c47b4f929a67426b258b8fd8 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.6 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：0.1.6",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.1.4",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_d6aeb053b3a541778b07c0bca68c5c82 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.4 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：0.1.4",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.2.2",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_963ec16ebc32452a8ca13e8ebc1aed96 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.2.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：0.2.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 13 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 来源证据：0.1.1。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 14,
"forks": 152,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 1014
},
"source_url": "https://github.com/test-zeus-ai/testzeus-hercules",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Hercules is the world’s first open-source testing agent, enabling UI, API, Security, Accessibility, and Visual validations – all without code or maintenance. Automate testing effortlessly and let Hercules handle the heavy lifting! ⚡",
"title": "testzeus-hercules 能力包",
"trial_prompt": "# testzeus-hercules - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for test-zeus-ai/testzeus-hercules.\n\nProject:\n- Name: testzeus-hercules\n- Repository: https://github.com/test-zeus-ai/testzeus-hercules\n- Summary: Hercules is the world’s first open-source testing agent, enabling UI, API, Security, Accessibility, and Visual validations – all without code or maintenance. Automate testing effortlessly and let Hercules handle the heavy lifting! ⚡\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Hercules is the world’s first open-source testing agent, enabling UI, API, Security, Accessibility, and Visual validations – all without code or maintenance. Automate testing effortlessly and let Hercules handle the heavy lifting! ⚡\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Hercules is the world’s first open-source testing agent, enabling UI, API, Security, Accessibility, and Visual validations – all without code or maintenance. Automate testing effortlessly and let Hercules handle the heavy lifting! ⚡\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. getting-started: Getting Started with TestZeus Hercules. Produce one small intermediate artifact and wait for confirmation.\n2. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. agent-system: Agent System. Produce one small intermediate artifact and wait for confirmation.\n4. browser-automation: Browser Automation. Produce one small intermediate artifact and wait for confirmation.\n5. tool-system: Tool System. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/test-zeus-ai/testzeus-hercules\n- https://github.com/test-zeus-ai/testzeus-hercules#readme\n- README.md\n- pyproject.toml\n- Dockerfile\n- helper_scripts/hercules_setup.sh\n- docs/run_guide.md\n- testzeus_hercules/core/runner.py\n- testzeus_hercules/core/simple_hercules.py\n- testzeus_hercules/core/__init__.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_release: 0.2.2（https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.2.2）；github/github_release: 0.1.6（https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.6）；github/github_release: 0.1.4（https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.4）；github/github_release: 0.1.2（https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.2）；github/github_release: 0.1.1（https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.1）；github/github_release: 0.1.0（https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.0）；github/github_release: 0.0.40（https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.0.40）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_release",
"source": "github",
"title": "0.2.2",
"url": "https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.2.2"
},
{
"kind": "github_release",
"source": "github",
"title": "0.1.6",
"url": "https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.6"
},
{
"kind": "github_release",
"source": "github",
"title": "0.1.4",
"url": "https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.4"
},
{
"kind": "github_release",
"source": "github",
"title": "0.1.2",
"url": "https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.2"
},
{
"kind": "github_release",
"source": "github",
"title": "0.1.1",
"url": "https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.1"
},
{
"kind": "github_release",
"source": "github",
"title": "0.1.0",
"url": "https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.0"
},
{
"kind": "github_release",
"source": "github",
"title": "0.0.40",
"url": "https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.0.40"
}
],
"status": "已收录 7 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "安全审查与权限治理",
"desc": "Hercules is the world’s first open-source testing agent, enabling UI, API, Security, Accessibility, and Visual validations – all without code or maintenance. Automate testing effortlessly and let Hercules handle the heavy lifting! ⚡",
"effort": "安装已验证",
"forks": 152,
"icon": "shield",
"name": "testzeus-hercules 能力包",
"risk": "可发布",
"slug": "testzeus-hercules",
"stars": 1014,
"tags": [
"安全审查与权限治理",
"网页任务自动化",
"自然语言网页操作",
"页面观察与动作规划",
"结构化数据提取"
],
"thumb": "purple",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/test-zeus-ai/testzeus-hercules 项目说明书\n\n生成时间：2026-05-17 01:20:40 UTC\n\n## 目录\n\n- [Getting Started with TestZeus Hercules](#getting-started)\n- [System Architecture](#system-architecture)\n- [Agent System](#agent-system)\n- [Browser Automation](#browser-automation)\n- [Tool System](#tool-system)\n- [LLM Configuration](#llm-configuration)\n- [Memory Management](#memory-management)\n- [API Testing](#api-testing)\n- [Security Testing](#security-testing)\n- [MCP Integration](#mcp-integration)\n\n\n\n## Getting Started with TestZeus Hercules\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/CONTRIBUTING.md)\n- [testzeus_hercules/__main__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/__main__.py)\n- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)\n- [testzeus_hercules/telemetry.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/telemetry.py)\n- [testzeus_hercules/utils/response_parser.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/response_parser.py)\n- [frontend/non-interactive/index.html](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/frontend/non-interactive/index.html)\n- [frontend/interactive/index.html](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/frontend/interactive/index.html)\n\n\n# Getting Started with TestZeus Hercules\n\nTestZeus Hercules is an open-source AI-powered end-to-end testing framework that leverages large language models (LLMs) to automate browser testing. It provides both interactive and non-interactive modes for executing automated tests against web applications.\n\n## Overview\n\nTestZeus Hercules serves as an intelligent testing agent that can:\n\n- Navigate web pages and interact with UI elements\n- Generate and execute Gherkin-style test scenarios\n- Perform API security scanning using Nuclei\n- Parse accessibility trees for element identification\n- Execute Python scripts in a sandboxed environment\n\n资料来源：[CONTRIBUTING.md]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[User Input] --> B[CLI / Main Entry]\n B --> C[Global Configuration]\n C --> D[Navigation Agent]\n D --> E[Browser Controller]\n E --> F[CDP Stream Renderer]\n F --> G[Accessibility Tree]\n G --> D\n D --> H[Python Sandbox Executor]\n H --> I[Test Results]\n D --> J[API Security Scanner]\n J --> K[Nuclei Integration]\n```\n\n### Core Components\n\n| Component | Purpose |\n|-----------|---------|\n| `testzeus_hercules/__main__.py` | Entry point handling bulk test execution |\n| `testzeus_hercules/config.py` | Command-line argument parsing and configuration |\n| `testzeus_hercules/telemetry.py` | Installation tracking and error reporting |\n| `testzeus_hercules/core/agents/executor_nav_agent.py` | Navigation agent for browser automation |\n| `frontend/*/index.html` | CDP stream rendering interfaces |\n\n资料来源：[testzeus_hercules/__main__.py:25-45]()\n资料来源：[testzeus_hercules/config.py]()\n\n## Installation\n\n### Prerequisites\n\n- Python 3.x\n- Git\n- Make\n\n### Setup Steps\n\n1. **Fork the repository**\n\n ```bash\n git clone git@github.com:YOUR_GIT_USERNAME/testzeus-hercules.git\n cd testzeus-hercules\n git remote add upstream https://github.com/test-zeus-ai/testzeus-hercules\n ```\n\n2. **Create virtual environment**\n\n ```bash\n make virtualenv\n source .venv/bin/activate\n ```\n\n3. **Install in development mode**\n\n ```bash\n make install\n ```\n\n资料来源：[CONTRIBUTING.md]()\n\n## Command-Line Interface\n\nTestZeus Hercules provides extensive CLI options for configuration.\n\n### Basic Options\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `--input-file` | str | Path to the input file |\n| `--output-path` | str | Path to the output directory |\n| `--test-data-path` | str | Path to the test data directory |\n| `--project-base` | str | Path to the project base directory |\n\n资料来源：[testzeus_hercules/config.py]()\n\n### LLM Configuration\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `--llm-model` | str | Name of the LLM model |\n| `--llm-model-api-key` | str | API key for the LLM model |\n| `--llm-model-base-url` | str | Base URL for the LLM API |\n| `--llm-model-api-type` | str | Type of API (openai, anthropic, azure) |\n| `--llm-temperature` | float | Temperature for LLM sampling (0.0-1.0) |\n| `--agents-llm-config-file` | str | Path to agents LLM configuration file |\n\n资料来源：[testzeus_hercules/config.py]()\n\n### Browser Options\n\n| Parameter | Description |\n|-----------|-------------|\n| `--browser-channel` | Browser channel (e.g., chrome-beta, firefox-nightly) |\n| `--browser-path` | Custom path to browser executable |\n| `--browser-version` | Specific browser version (e.g., '114', '115.0.1', 'latest') |\n| `--enable-ublock` | Enable uBlock Origin extension |\n| `--disable-ublock` | Disable uBlock Origin extension |\n| `--auto-accept-screen-sharing` | Automatically accept screen sharing prompts |\n\n资料来源：[testzeus_hercules/config.py]()\n\n### Test Execution Options\n\n| Parameter | Description |\n|-----------|-------------|\n| `--bulk` | Execute tests in bulk from tests directory |\n| `--reuse-vector-db` | Reuse existing vector DB instead of creating fresh one |\n\n资料来源：[testzeus_hercules/config.py]()\n资料来源：[testzeus_hercules/__main__.py:45-60]()\n\n### Portkey Integration\n\n| Parameter | Description |\n|-----------|-------------|\n| `--enable-portkey` | Enable Portkey integration for LLM routing |\n| `--portkey-api-key` | API key for Portkey |\n| `--portkey-strategy` | Routing strategy (fallback or loadbalance) |\n\n资料来源：[testzeus_hercules/config.py]()\n\n### Sandbox Configuration\n\n| Parameter | Description |\n|-----------|-------------|\n| `--sandbox-tenant-id` | Tenant ID for sandbox isolation |\n\n资料来源：[testzeus_hercules/config.py]()\n\n## Running TestZeus Hercules\n\n### Interactive Mode\n\nRun the interactive CDP stream renderer with user input capabilities:\n\n```bash\nmake run-interactive\n```\n\nThis launches the frontend at `frontend/interactive/index.html` which provides:\n\n- Real-time screencast display\n- Crosshair cursor for element selection\n- Input capture for typing into the remote page\n\n资料来源：[frontend/interactive/index.html]()\n\n### Non-Interactive Mode\n\nRun tests without user interaction:\n\n```bash\nmake run\n```\n\nThis uses the non-interactive frontend at `frontend/non-interactive/index.html` which displays:\n\n- Connection status\n- Screencast output only\n\n资料来源：[frontend/non-interactive/index.html]()\n\n### Bulk Execution\n\nExecute multiple tests from a tests directory:\n\n```bash\npython -m testzeus_hercules --bulk\n```\n\nThe system checks for a `tests` directory in the project source root and processes each test folder:\n\n```python\nif get_global_conf().should_execute_bulk():\n project_base = get_global_conf().get_project_source_root()\n tests_dir = os.path.join(project_base, \"tests\")\n```\n\n资料来源：[testzeus_hercules/__main__.py:45-55]()\n\n## Response Parsing\n\nTestZeus Hercules includes a robust response parser for handling LLM outputs:\n\n```mermaid\ngraph LR\n A[LLM Response] --> B{Is JSON?}\n B -->|Yes| C[Parse JSON]\n B -->|No| D[Extract Plan/Next Step]\n C --> E[Return Dict]\n D --> E\n```\n\nThe parser handles:\n\n- JSON wrapped in ```json code blocks\n- Plain JSON responses\n- Fallback extraction for `plan` and `next_step` fields\n\n资料来源：[testzeus_hercules/utils/response_parser.py]()\n\n## Telemetry and Installation Tracking\n\nOn first run, TestZeus Hercules generates a unique installation ID:\n\n```python\ndef get_installation_id(file_path: str = \"installation_id.txt\", is_manual_run: bool = True):\n if os.path.exists(file_path):\n # Load existing installation data\n else:\n # Generate new installation ID\n installation_id = str(uuid.uuid4())\n```\n\n资料来源：[testzeus_hercules/telemetry.py]()\n\n## Development Workflow\n\n### Code Quality\n\n| Command | Purpose |\n|---------|---------|\n| `make fmt` | Format code using black & isort |\n| `make lint` | Run pep8, black, mypy linters |\n| `make test` | Run tests and generate coverage report |\n| `make watch` | Run tests on every change |\n\n资料来源：[CONTRIBUTING.md]()\n\n### Testing Requirements\n\n- Code coverage must show `100%` coverage\n- Add tests for all changes in your PR\n\n```bash\nmake test\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### Release Process\n\n1. Make changes following the contribution guidelines\n2. Commit using conventional commit messages\n3. Run tests to ensure everything works\n4. Execute `make release` to create a new tag and push\n\n> **CAUTION**: The make release will change local changelog files and commit all unstaged changes.\n\n资料来源：[CONTRIBUTING.md]()\n\n## Navigation Agent Execution\n\nThe executor navigation agent follows specific guidelines:\n\n### Execution Principles\n\n1. **Error Review**: Review previous step outcomes before proceeding\n2. **Script Execution**: Use `execute_python_sandbox` tool with access to `page`, `browser`, `context`, `playwright_manager`, `logger`, `config`\n3. **Sequential Execution**: Execute one script at a time and await results\n4. **Validation**: Check for successful execution status before proceeding\n\n资料来源：[testzeus_hercules/core/agents/executor_nav_agent.py]()\n\n## API Security Scanning\n\nTestZeus Hercules integrates with Nuclei for API security testing:\n\n```python\nasync def run_nuclei_command(\n is_open_api_spec: bool,\n open_api_spec_path: Optional[str],\n target_url: Optional[str],\n tag: str,\n output_file: Path,\n headers: Optional[List[Tuple[str, str]]] = None,\n):\n```\n\n资料来源：[testzeus_hercules/core/tools/api_sec_calls.py]()\n\n## Helper Scripts\n\n### CDP Journey Script\n\nGenerate test cases from journey data:\n\n```bash\npython helper_scripts/cdp_journey_script.py --number_of_testcase 5\n```\n\nThis produces Gherkin specifications and test data files from JSON journey definitions.\n\n资料来源：[helper_scripts/cdp_journey_script.py]()\n\n### API Functional Gherkin Test Generator\n\nGenerate Gherkin test cases from OpenAPI specifications:\n\n```bash\npython helper_scripts/generate_api_functional_gherkin_test.py spec.yaml --output ./features --number_of_testcase 100\n```\n\n资料来源：[helper_scripts/generate_api_functional_gherkin_test.py]()\n\n## Accessibility Tree Processing\n\nTestZeus Hercules processes DOM elements to generate accessibility trees:\n\n- Identifies interactive elements (buttons, links, inputs)\n- Detects draggable elements\n- Filters out non-interactive elements\n- Provides detailed element metadata for the AI agent\n\n资料来源：[testzeus_hercules/utils/get_detailed_accessibility_tree.py]()\n\n## Summary\n\nTestZeus Hercules provides a comprehensive end-to-end testing solution with:\n\n- AI-powered browser automation via LLM integration\n- Flexible deployment (interactive and non-interactive modes)\n- Extensive CLI configuration options\n- Built-in support for bulk test execution\n- API security scanning capabilities\n- Gherkin test generation from various sources\n\n资料来源：[CONTRIBUTING.md]()\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Agent System](#agent-system), [Tool System](#tool-system)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [testzeus_hercules/core/runner.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/runner.py)\n- [testzeus_hercules/core/simple_hercules.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)\n- [testzeus_hercules/core/__init__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/__init__.py)\n- [testzeus_hercules/interactive.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/interactive.py)\n- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)\n- [testzeus_hercules/core/extra_tools/__init__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/extra_tools/__init__.py)\n- [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)\n- [testzeus_hercules/telemetry.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/telemetry.py)\n\n\n# System Architecture\n\n## Overview\n\nTestZeus Hercules is an open-source AI agent framework designed for **end-to-end testing** of web applications. The system leverages Large Language Models (LLMs) to orchestrate browser automation through Playwright, enabling natural language-driven test execution without requiring users to write traditional test scripts.\n\nThe architecture follows a modular design pattern with clear separation between:\n- Core execution engine\n- Agent-based navigation and task handling\n- Python sandbox environment for script execution\n- Frontend visualization components\n- Configuration and telemetry systems\n\n**资料来源：** [testzeus_hercules/__main__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/__main__.py)\n\n---\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n User[User / CI Pipeline] --> CLI[CLI Entry Point __main__.py]\n CLI --> Config[Global Configuration config.py]\n CLI --> Runner[CommandPromptRunner runner.py]\n \n Runner --> SimpleHercules[SimpleHercules simple_hercules.py]\n Runner --> Interactive[Interactive Runner interactive.py]\n \n SimpleHercules --> AgentSystem[Agent System]\n AgentSystem --> ExecutorNavAgent[ExecutorNavAgent]\n AgentSystem --> ExtraTools[Extra Tools Loader extra_tools/__init__.py]\n \n ExecutorNavAgent --> Sandbox[Python Sandbox execute_python_sandbox.py]\n Sandbox --> Playwright[Playwright Browser Automation]\n \n SimpleHercules --> Telemetry[Telemetry Module telemetry.py]\n SimpleHercules --> ResponseParser[Response Parser response_parser.py]\n \n Interactive --> CDPStream[CDP Stream Frontend frontend/interactive]\n \n Config --> LLMConfig[LLM Configuration openai, anthropic, azure]\n Config --> Portkey[Portkey Integration]\n```\n\n---\n\n## Core Components\n\n### 1. Entry Points\n\nThe framework provides multiple entry points for different use cases:\n\n| Entry Point | File | Purpose |\n|-------------|------|---------|\n| CLI | `testzeus_hercules/__main__.py` | Main command-line interface with ASCII banner |\n| Interactive | `testzeus_hercules/interactive.py` | Interactive test session runner |\n| Module Import | `testzeus_hercules/core/__init__.py` | Programmatic API for embedding |\n\n**资料来源：** [testzeus_hercules/interactive.py:1-9](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/interactive.py)\n\n#### Interactive Entry Point\n```python\nimport asyncio\nfrom testzeus_hercules.config import get_global_conf\nfrom testzeus_hercules.core.runner import CommandPromptRunner\n\nif __name__ == \"__main__\":\n conf = get_global_conf()\n conf.set_default_test_id(\"interactive_runner\")\n runner = CommandPromptRunner()\n asyncio.run(runner.start())\n```\n\n### 2. Configuration System\n\nThe configuration system (`config.py`) manages all runtime parameters:\n\n**资料来源：** [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)\n\n#### Configuration Categories\n\n| Category | Parameters |\n|----------|------------|\n| **Path Configuration** | `--input-file`, `--output-path`, `--test-data-path`, `--project-base` |\n| **LLM Model** | `--llm-model`, `--llm-model-api-key`, `--llm-model-base-url`, `--llm-model-api-type` |\n| **LLM Sampling** | `--llm-temperature` (0.0-1.0) |\n| **LLM Config Files** | `--agents-llm-config-file`, `--agents-llm-config-file-ref-key` |\n| **Portkey Integration** | `--enable-portkey`, `--portkey-api-key`, `--portkey-strategy` (fallback/loadbalance) |\n| **Browser Options** | `--browser-channel`, `--browser-path`, `--browser-version` |\n| **Browser Extensions** | `--enable-ublock`, `--disable-ublock` |\n| **Screen Sharing** | `--auto-accept-screen-sharing`, `--disable-auto-accept-screen-sharing` |\n| **Execution** | `--bulk`, `--reuse-vector-db` |\n| **Sandbox** | `--sandbox-tenant-id`, `--sandbox-custom-injections` |\n\n---\n\n## Agent System Architecture\n\n### SimpleHercules Core\n\nThe `SimpleHercules` class is the central orchestration engine:\n\n```mermaid\ngraph TD\n subgraph \"SimpleHercules Core\"\n Planner[Planner Agent]\n Executor[ExecutorNavAgent]\n Notifier[Message Notification System]\n State[State Management]\n end\n \n Planner --> LLM[LLM Provider]\n Executor --> Sandbox[Python Sandbox]\n Executor --> Playwright[Playwright Manager]\n Notifier --> UI[Frontend / CLI Output]\n \n State --> PlanSteps[Plan Steps]\n State --> StepHistory[Step History]\n State --> Assertions[Assertion Results]\n```\n\n**资料来源：** [testzeus_hercules/core/simple_hercules.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)\n\n#### Message Flow\n\nThe system processes responses through a structured message format:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `plan` | `List[str]` | List of planned test steps |\n| `next_step` | `str` | Current step instruction |\n| `is_assert` | `bool` | Whether current step is an assertion |\n| `is_passed` | `bool` | Assertion pass/fail status |\n| `assert_summary` | `str` | Summary of assertion results |\n| `is_terminated` | `bool` | Whether execution is terminated |\n| `is_completed` | `bool` | Whether test suite is completed |\n| `final_response` | `str` | Final summary response |\n\n#### Message Notification Types\n\n```python\nclass MessageType(Enum):\n PLAN = \"plan\" # Plan step notifications\n STEP = \"step\" # Current step notifications\n INFO = \"info\" # Information messages\n ERROR = \"error\" # Error messages\n RESULT = \"result\" # Execution results\n```\n\n**资料来源：** [testzeus_hercules/core/simple_hercules.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)\n\n### Executor Navigation Agent\n\nThe `ExecutorNavAgent` handles the execution of browser automation scripts:\n\n**资料来源：** [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)\n\n#### Execution Guidelines\n\n| Rule | Description |\n|------|-------------|\n| **Step Review** | Review previous step outcome before proceeding |\n| **Sequential Execution** | Execute one script/function at a time |\n| **Sandbox Usage** | Execute scripts using `execute_python_sandbox` tool |\n| **Access Variables** | Scripts have access to: `page`, `browser`, `context`, `playwright_manager`, `logger`, `config` |\n| **Validation** | Verify each script execution result before moving on |\n| **Output Processing** | Parse JSON outputs, handle stdout/stderr |\n\n---\n\n## Python Sandbox Architecture\n\nThe sandbox system (`execute_python_sandbox.py`) provides secure script execution with configurable injections:\n\n**资料来源：** [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)\n\n```mermaid\ngraph TD\n Request[Sandbox Request] --> TenantCheck{Tenant ID Check}\n \n TenantCheck -->|executor_agent| HerculesUtils[hercules_utils from testzeus_hercules]\n TenantCheck -->|tenant specific| TenantModules[Custom Modules from SANDBOX_TENANT_ID]\n TenantCheck -->|none| DefaultModules[Default Modules requests, beautifulsoup, etc.]\n \n ConfigDriven -->|SANDBOX_PACKAGES| ConfigPackages[Config-defined packages]\n CustomInjections -->|JSON string| CustomPackages[Custom Package Injections]\n \n DefaultModules --> Merge[Injection Merge]\n TenantModules --> Merge\n ConfigPackages --> Merge\n CustomPackages --> Merge\n \n Merge --> SandboxEnv[Sandbox Environment]\n```\n\n#### Injection Sources\n\n| Source | Configuration Key | Example |\n|--------|-------------------|---------|\n| Default packages | Built-in | `requests`, `beautifulsoup4` |\n| Tenant-specific | `SANDBOX_TENANT_ID` | Custom module per tenant |\n| Config-driven | `SANDBOX_PACKAGES` | Package list from config |\n| Per-call | `--sandbox-custom-injections` | JSON-formatted custom injections |\n\n---\n\n## Extra Tools System\n\nThe extra tools loader (`extra_tools/__init__.py`) dynamically imports all modules in the `extra_tools` directory:\n\n**资料来源：** [testzeus_hercules/core/extra_tools/__init__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/extra_tools/__init__.py)\n\n```python\n# Dynamic module loading pattern\nif get_global_conf().get_load_extra_tools().lower().strip() != \"false\":\n for _, module_name, _ in pkgutil.iter_modules([str(package_path)]):\n full_module_name = f\"testzeus_hercules.core.extra_tools.{module_name}\"\n module = importlib.import_module(full_module_name)\n for attribute_name in dir(module):\n if not attribute_name.startswith(\"_\"):\n globals()[attribute_name] = getattr(module, attribute_name)\n```\n\n---\n\n## Telemetry System\n\nThe telemetry module (`telemetry.py`) handles installation tracking and error reporting:\n\n**资料来源：** [testzeus_hercules/telemetry.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/telemetry.py)\n\n#### Installation ID Management\n\n```python\ndef get_installation_id(file_path: str = \"installation_id.txt\", is_manual_run: bool = True) -> Dict[str, Any]\n```\n\n| Scenario | Behavior |\n|----------|----------|\n| File exists with dict | Return parsed dict with `installation_id` |\n| File exists with string | Return dict with `installation_id` and default email |\n| File not exists + manual run | Prompt for `user_email` |\n| File not exists + automated | Use default values, generate new UUID |\n\n#### Sentry Integration\n\n| Configuration | Purpose |\n|---------------|---------|\n| `max_breadcrumbs=0` | Disable breadcrumb collection |\n| `send_default_pii=False` | Exclude personally identifiable information |\n| `send_client_reports=False` | Disable client reports |\n| `sys.argv` extra | Set to `None` to prevent leakage |\n| `denylist` | Scrub sensitive fields recursively |\n\n---\n\n## Frontend Architecture\n\n### CDP Stream Renderer\n\nThe frontend provides real-time browser visualization:\n\n**资料来源：** [frontend/interactive/index.html](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/frontend/interactive/index.html)\n\n| Version | File | Features |\n|---------|------|----------|\n| Interactive | `frontend/interactive/index.html` | Mouse/keyboard input capture, crosshair cursor |\n| Non-interactive | `frontend/non-interactive/index.html` | Display-only screencast |\n\n#### Interactive Features\n\n- Real-time screencast display via CDP\n- Input capture via hidden dummy input field\n- Crosshair cursor for element selection\n- Pre-formatted output log display\n\n---\n\n## Response Parser\n\nThe response parser (`response_parser.py`) handles LLM output normalization:\n\n**资料来源：** [testzeus_hercules/utils/response_parser.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/response_parser.py)\n\n```python\ndef parse_response(message: str) -> dict[str, Any]\n```\n\n#### Parsing Flow\n\n1. **Strip markdown code blocks**: Handle ` ```json ` and ` ``` ` wrappers\n2. **Normalize whitespace**: Replace `\\n` with spaces\n3. **JSON parsing**: Attempt `json.loads()`\n4. **Fallback parsing**: If JSON fails, extract `plan` and `next_step` via string matching\n5. **Error logging**: Warn and continue if parsing fails\n\n---\n\n## Execution Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant Config\n participant Runner\n participant SimpleHercules\n participant Executor\n participant Sandbox\n participant Playwright\n\n User->>CLI: Run command\n CLI->>Config: Parse arguments\n Config-->>CLI: Global config\n CLI->>Runner: Create CommandPromptRunner\n Runner->>SimpleHercules: Initialize\n SimpleHercules->>Executor: Create ExecutorNavAgent\n \n loop Test Execution\n SimpleHercules->>SimpleHercules: Generate plan via LLM\n SimpleHercules->>Executor: Execute next_step\n Executor->>Sandbox: Run Python script\n Sandbox->>Playwright: Browser automation\n Playwright-->>Sandbox: Result\n Sandbox-->>Executor: Execution result\n Executor-->>SimpleHercules: Response with plan/next_step\n SimpleHercules->>SimpleHercules: Parse and notify\n end\n \n SimpleHercules-->>Runner: Completion / Termination\n Runner-->>User: Final response\n```\n\n---\n\n## LLM Integration\n\n### Supported Providers\n\n| Provider | Configuration | Reference |\n|----------|---------------|-----------|\n| OpenAI | `--llm-model-api-type=openai` | Default |\n| Anthropic | `--llm-model-api-type=anthropic` | Claude models |\n| Azure OpenAI | `--llm-model-api-type=azure` | Azure-hosted |\n| Custom | `--llm-model-base-url` | Self-hosted endpoints |\n\n### Portkey Integration\n\nFor production routing and observability:\n\n```bash\n--enable-portkey\n--portkey-api-key=\n--portkey-strategy=[fallback|loadbalance]\n```\n\n---\n\n## Configuration File Structure\n\nThe system supports YAML/JSON configuration files via `--agents-llm-config-file`:\n\n| Parameter | Description |\n|-----------|-------------|\n| `ref_key` | Reference key for loading specific config sections |\n| `temperature` | Sampling temperature (0.0-1.0) |\n| `max_tokens` | Maximum response length |\n| `model` | Model identifier |\n\n---\n\n## Summary\n\nThe TestZeus Hercules architecture demonstrates a clean separation of concerns:\n\n1. **Entry Layer**: CLI and interactive interfaces for user access\n2. **Configuration Layer**: Centralized parameter management with environment and file support\n3. **Orchestration Layer**: `SimpleHercules` coordinates agent communication\n4. **Execution Layer**: `ExecutorNavAgent` handles browser automation\n5. **Sandbox Layer**: Secure Python script execution with dynamic injections\n6. **Telemetry Layer**: Installation tracking and error reporting via Sentry\n7. **Presentation Layer**: CDP-based frontend for real-time visualization\n\nThis design enables the system to serve as both a standalone testing tool and an embeddable library for larger test frameworks.\n\n---\n\n\n\n## Agent System\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Memory Management](#memory-management), [LLM Configuration](#llm-configuration)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [testzeus_hercules/core/agents/high_level_planner_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/high_level_planner_agent.py)\n- [testzeus_hercules/core/agents/browser_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/browser_nav_agent.py)\n- [testzeus_hercules/core/agents/api_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/api_nav_agent.py)\n- [testzeus_hercules/core/agents/sql_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/sql_nav_agent.py)\n- [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)\n- [testzeus_hercules/core/agents/sec_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/sec_nav_agent.py)\n- [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)\n- [testzeus_hercules/core/agents/time_keeper_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/time_keeper_nav_agent.py)\n- [testzeus_hercules/core/agent_registry.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agent_registry.py)\n\n\n# Agent System\n\n## Overview\n\nThe Agent System is the core orchestration layer of the Hercules testing framework. It implements a multi-agent architecture where specialized agents collaborate to execute end-to-end testing scenarios across web browsers, APIs, databases, and other system components.\n\n**资料来源：** [testzeus_hercules/core/agent_registry.py:1-50](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agent_registry.py)\n\n## Architecture Overview\n\nThe system follows a hierarchical agent design where a central planner coordinates specialized navigation agents, each responsible for a specific domain of interaction.\n\n```mermaid\ngraph TD\n A[HighLevelPlannerAgent] --> B[BrowserNavAgent]\n A --> C[ApiNavAgent]\n A --> D[SqlNavAgent]\n A --> E[McpNavAgent]\n A --> F[SecNavAgent]\n A --> G[TimeKeeperNavAgent]\n B --> H[ExecutorNavAgent]\n C --> H\n D --> H\n E --> H\n F --> H\n G --> H\n \n H --> I[Browser/API/SQL/MCP/Security]\n```\n\n**资料来源：** [testzeus_hercules/core/simple_hercules.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)\n\n## Agent Types\n\n### High-Level Planner Agent\n\nThe `HighLevelPlannerAgent` serves as the central coordinator that receives high-level test instructions and decomposes them into executable steps for specialized agents.\n\n**Key Responsibilities:**\n- Parsing test instructions and generating execution plans\n- Routing tasks to appropriate specialized agents\n- Aggregating results and handling test completion\n- Managing assertions and validating expected outcomes\n\n**资料来源：** [testzeus_hercules/core/agents/high_level_planner_agent.py:1-80](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/high_level_planner_agent.py)\n\n### Browser Navigation Agent\n\nThe `BrowserNavAgent` handles all browser-based interactions including page navigation, element interaction, and DOM manipulation.\n\n**Capabilities:**\n- Web page navigation and URL handling\n- Element clicking and text input\n- Screenshot capture and visual validation\n- Cookie and session management\n\n**资料来源：** [testzeus_hercules/core/agents/browser_nav_agent.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/browser_nav_agent.py)\n\n### API Navigation Agent\n\nThe `ApiNavAgent` manages HTTP-based interactions for testing RESTful APIs and web services.\n\n**Capabilities:**\n- HTTP request construction and execution\n- Response validation and assertion\n- Authentication handling (OAuth, API keys, Bearer tokens)\n- Multi-step API workflows\n\n**资料来源：** [testzeus_hercules/core/agents/api_nav_agent.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/api_nav_agent.py)\n\n### SQL Navigation Agent\n\nThe `SqlNavAgent` handles database interactions for data validation and setup during test execution.\n\n**Capabilities:**\n- SQL query execution\n- Database connection management\n- Result set validation\n- Test data preparation and teardown\n\n**资料来源：** [testzeus_hercules/core/agents/sql_nav_agent.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/sql_nav_agent.py)\n\n### MCP Navigation Agent\n\nThe `McpNavAgent` provides Model Context Protocol integration for interacting with external AI models and tools.\n\n**Capabilities:**\n- MCP server connection management\n- Tool invocation through MCP protocol\n- Context propagation for AI-assisted testing\n\n**资料来源：** [testzeus_hercules/core/agents/mcp_nav_agent.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/mcp_nav_agent.py)\n\n### Security Navigation Agent\n\nThe `SecNavAgent` handles security-related testing scenarios including authentication flows, authorization checks, and vulnerability scanning.\n\n**Capabilities:**\n- Authentication flow testing\n- Session security validation\n- Authorization boundary testing\n- Security header verification\n\n**资料来源：** [testzeus_hercules/core/agents/sec_nav_agent.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/sec_nav_agent.py)\n\n### Time Keeper Navigation Agent\n\nThe `TimeKeeperNavAgent` manages time-related test scenarios including scheduling, delays, and time-based assertions.\n\n**Capabilities:**\n- Time-based test scheduling\n- Delay and timeout management\n- Timestamp validation\n- Scheduled task execution\n\n**资料来源：** [testzeus_hercules/core/agents/time_keeper_nav_agent.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/time_keeper_nav_agent.py)\n\n### Executor Navigation Agent\n\nThe `ExecutorNavAgent` serves as the execution engine that runs Python scripts and commands within a sandboxed environment.\n\n**Key Features:**\n- Python script execution in isolated sandbox\n- Dynamic module injection based on tenant configuration\n- Access to browser context, page objects, and configuration\n- Custom injection support for tenant-specific utilities\n\n**资料来源：** [testzeus_hercules/core/agents/executor_nav_agent.py:1-150](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/executor_nav_agent.py)\n\n## Agent Registry\n\nThe `AgentRegistry` provides a centralized registration and lookup mechanism for all agents in the system.\n\n### Registry Operations\n\n| Operation | Description |\n|-----------|-------------|\n| `register_agent(name, agent)` | Register a new agent with a unique name |\n| `get_agent(name)` | Retrieve an agent by name |\n| `list_agents()` | List all registered agents |\n| `remove_agent(name)` | Remove an agent from the registry |\n\n**资料来源：** [testzeus_hercules/core/agent_registry.py:50-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agent_registry.py)\n\n## Agent Creation Flow\n\nThe `SimpleHercules` class orchestrates agent creation with the following workflow:\n\n```mermaid\nsequenceDiagram\n participant SH as SimpleHercules\n participant Planner as HighLevelPlannerAgent\n participant Nav as Navigation Agents\n participant Exec as ExecutorNavAgent\n \n SH->>SH: Initialize configuration\n SH->>Planner: Create planner agent\n SH->>Nav: Create navigation agents (Browser, API, SQL, etc.)\n SH->>Exec: Create executor agent\n SH->>SH: Register all agents in registry\n Planner->>Nav: Route tasks based on type\n Nav->>Exec: Execute concrete actions\n```\n\n**资料来源：** [testzeus_hercules/core/simple_hercules.py:100-200](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)\n\n## Message Flow\n\nAgents communicate through a structured message passing system with the following message types:\n\n| Message Type | Purpose |\n|--------------|---------|\n| `PLAN` | Initial test plan and steps |\n| `STEP` | Individual test step execution |\n| `INFO` | Informational messages |\n| `ASSERT` | Assertion results |\n| `COMPLETED` | Task completion notification |\n| `TERMINATED` | Agent termination signal |\n\n**资料来源：** [testzeus_hercules/core/simple_hercules.py:200-300](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)\n\n## Configuration\n\n### LLM Model Configuration\n\nEach agent supports individual LLM model configuration:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `model` | string | Model name (e.g., gpt-4, claude-3) |\n| `temperature` | float | Sampling temperature (0.0-1.0) |\n| `max_tokens` | int | Maximum response tokens |\n| `api_key` | string | API authentication key |\n| `base_url` | string | Custom API endpoint URL |\n\n**资料来源：** [testzeus_hercules/config.py:1-80](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)\n\n### Agent-Specific Settings\n\n```python\n# Example agent configuration structure\nagent_config = {\n \"model_config_params\": {\n \"model\": \"gpt-4\",\n \"temperature\": 0.7,\n \"max_tokens\": 2000\n },\n \"llm_config_params\": {\n \"timeout\": 60,\n \"retry_attempts\": 3\n },\n \"other_settings\": {\n \"system_prompt\": \"You are a testing agent...\",\n \"max_chat_rounds\": 10\n }\n}\n```\n\n## Response Parsing\n\nThe system uses `parse_response()` from the response parser module to extract structured data from agent outputs:\n\n```python\ndef parse_response(message: str) -> dict[str, Any]:\n # Handles JSON extraction from markdown code blocks\n # Normalizes newlines and whitespace\n # Extracts plan and next_step fields\n```\n\n**资料来源：** [testzeus_hercules/utils/response_parser.py:1-60](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/response_parser.py)\n\n## Sandbox Execution\n\nThe ExecutorNavAgent provides a secure Python execution environment with configurable module injection:\n\n### Available Injections\n\n| Module | Description |\n|--------|-------------|\n| `playwright` | Browser automation library |\n| `requests` | HTTP client library |\n| `beautifulsoup4` | HTML parsing |\n| `hercules_utils` | Project utility functions |\n| Custom packages | Configured via SANDBOX_PACKAGES |\n\n**资料来源：** [testzeus_hercules/core/tools/execute_python_sandbox.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/execute_python_sandbox.py)\n\n### Sandbox Context Variables\n\nScripts executed in the sandbox have automatic access to:\n\n| Variable | Type | Description |\n|----------|------|-------------|\n| `page` | Playwright Page | Current browser page |\n| `browser` | Playwright Browser | Browser instance |\n| `context` | Playwright Context | Browser context |\n| `playwright_manager` | Manager | Playwright management |\n| `logger` | Logger | Logging interface |\n| `config` | Config | Global configuration |\n\n## Command-Line Interface\n\nThe agent system supports configuration via command-line arguments:\n\n| Argument | Description |\n|----------|-------------|\n| `--llm-model` | Specify LLM model name |\n| `--llm-temperature` | Set sampling temperature |\n| `--agents-llm-config-file` | Path to agent config file |\n| `--enable-portkey` | Enable Portkey routing |\n| `--browser-channel` | Browser channel selection |\n| `--reuse-vector-db` | Reuse existing vector database |\n\n**资料来源：** [testzeus_hercules/config.py:80-150](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)\n\n## Error Handling\n\nAgents implement robust error handling with:\n\n1. **Termination Message Check**: Each agent validates termination conditions via `is_xxx_termination_message()` functions\n2. **Tool Call Monitoring**: Tracks pending tool calls to prevent premature termination\n3. **Graceful Degradation**: Continues execution with alternative approaches on failure\n4. **Logging**: Comprehensive logging for debugging and audit trails\n\n**资料来源：** [testzeus_hercules/core/simple_hercules.py:300-400](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)\n\n---\n\n\n\n## Browser Automation\n\n### 相关页面\n\n相关主题：[Tool System](#tool-system)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [testzeus_hercules/core/playwright_manager.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/playwright_manager.py)\n- [testzeus_hercules/core/browser_logger.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/browser_logger.py)\n- [testzeus_hercules/utils/dom_helper.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/dom_helper.py)\n- [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)\n- [helper_scripts/browser_stack_generate_cdp_url.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/helper_scripts/browser_stack_generate_cdp_url.py)\n- [helper_scripts/lambda_test_generate_cdp_url.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/helper_scripts/lambda_test_generate_cdp_url.py)\n\n\n# Browser Automation\n\n## Overview\n\nBrowser Automation in TestZeus Hercules provides a comprehensive framework for controlling web browsers through Playwright, enabling autonomous agents to perform complex web interactions, testing, and data extraction tasks. The system acts as a bridge between LLM-powered agents and real browser instances, translating natural language instructions into precise DOM manipulations.\n\nThe automation layer handles multiple browser types (Chromium, Firefox, WebKit), manages browser contexts with device emulation, supports cloud-based testing platforms via CDP (Chrome DevTools Protocol) tunneling, and provides sophisticated DOM interaction tools including accessibility-aware element selection and real-time mutation observation.\n\n**资料来源：** [testzeus_hercules/core/playwright_manager.py:1-50]()\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n A[SimpleHercules Core] --> B[PlaywrightManager]\n B --> C[Browser Context]\n C --> D[Browser Instance Chromium|Firefox|WebKit]\n B --> E[Tool Registry]\n E --> F[Navigation Tools]\n E --> G[Interaction Tools]\n E --> H[Extraction Tools]\n B --> I[DOM Mutation Observer]\n B --> J[BrowserLogger]\n J --> K[Interaction Logs]\n K --> L[Accessibility Tree]\n L --> M[AccessibilityInfo]\n```\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| PlaywrightManager | `core/playwright_manager.py` | Central browser lifecycle management |\n| BrowserLogger | `core/browser_logger.py` | Interaction logging and proof generation |\n| DOMHelper | `utils/dom_helper.py` | DOM state management and waiting |\n| AccessibilityTree | `utils/get_detailed_accessibility_tree.py` | Extract and format accessibility information |\n| ToolRegistry | `core/tools/tool_registry.py` | Dynamic tool registration and routing |\n\n**资料来源：** [testzeus_hercules/core/playwright_manager.py]()\n**资料来源：** [testzeus_hercules/utils/dom_helper.py]()\n\n---\n\n## PlaywrightManager\n\nThe `PlaywrightManager` class is the central orchestrator for all browser operations. It handles browser launching, page management, element location, and interaction recording.\n\n### Browser Launch Modes\n\n```mermaid\ngraph LR\n A[Browser Launch Request] --> B{Launch Type?}\n B -->|Persistent| C[Launch Persistent Context]\n B -->|Remote CDP| D[Connect via CDP URL]\n B -->|Recording| E[Launch with Video Recording]\n C --> F[Browser Instance]\n D --> F\n E --> F\n```\n\n**资料来源：** [testzeus_hercules/core/playwright_manager.py:100-200]()\n\n### Browser Types\n\nThe system supports three browser engines:\n\n| Browser | Type Identifier | Extensions Support | Certificate Handling |\n|---------|-----------------|-------------------|---------------------|\n| Chromium | `chromium` | Yes (uBlock Origin) | Default ignore |\n| Firefox | `firefox` | Yes | Via args |\n| WebKit | `webkit` | Limited | Via args |\n\n**资料来源：** [testzeus_hercules/core/playwright_manager.py:180-220]()\n\n### Context Options\n\nThe `_build_emulation_context_options` method configures device emulation:\n\n```mermaid\ngraph TD\n A[Build Context Options] --> B{Device Name?}\n B -->|Yes| C[Get Device from Playwright]\n C --> D[Merge Device Properties]\n B -->|No| E[Skip Device Emulation]\n D --> F[Return Context Options]\n E --> F\n```\n\nContext options include viewport size, user agent, device scale factor, and touch capabilities based on the selected device profile.\n\n**资料来源：** [testzeus_hercules/core/playwright_manager.py:200-230]()\n\n### CDP Remote Connection\n\nThe system supports connecting to remote browser instances through BrowserStack and LambdaTest via CDP tunneling.\n\n#### BrowserStack Integration\n\nThe `browser_stack_generate_cdp_url.py` helper generates CDP URLs for BrowserStack's remote browser grid:\n\n```python\n# Simplified flow from helper_scripts/browser_stack_generate_cdp_url.py\ndef generate_cdp_url(username, access_key, session_id):\n ws_endpoint = f\"wss://{username}:{access_key}@cdp.browserstack.com\"\n return f\"{ws_endpoint}/playwright?sessionId={session_id}\"\n```\n\n**资料来源：** [helper_scripts/browser_stack_generate_cdp_url.py]()\n\n#### LambdaTest Integration\n\nSimilarly, LambdaTest provides CDP access through their Selenium Smart Proxy:\n\n```python\n# Simplified flow from helper_scripts/lambda_test_generate_cdp_url.py\ndef generate_cdp_url(username, access_key, session_id):\n hub_endpoint = f\"wss://{username}:{access_key}@hub.lambdatest.com/cdp\"\n return f\"{hub_endpoint}/{session_id}\"\n```\n\n**资料来源：** [helper_scripts/lambda_test_generate_cdp_url.py]()\n\n---\n\n## Browser Tools\n\nBrowser automation tools are registered in the Tool Registry and decorated with `@tool` to enable agent consumption.\n\n### Tool Categories\n\n| Category | Tools | Purpose |\n|----------|-------|---------|\n| Navigation | `open_url`, `go_back`, `go_forward` | URL navigation and history |\n| Interaction | `click`, `hover`, `type`, `upload_file` | User interaction simulation |\n| Extraction | `get_page_text`, `get_input_fields`, `get_interactive_elements` | DOM content retrieval |\n| Accessibility | `get_accessibility_info`, `run_accessibility_check` | WCAG compliance testing |\n| Special | `set_date_time_value`, `read_clipboard` | Specialized interactions |\n\n**资料来源：** [testzeus_hercules/core/tools/tool_registry.py]()\n**资料来源：** [testzeus_hercules/core/tools/open_url.py]()\n\n### Selector Convention\n\nAll tools use the `md` attribute for element selection, enabling stable selectors independent of DOM structure changes:\n\n```python\n# Selector format\nselector = \"[md='element_id']\"\n\n# Automatic conversion if not present\nif \"md=\" not in selector:\n selector = f\"[md='{selector}']\"\n```\n\n**资料来源：** [testzeus_hercules/core/tools/hover.py:25-30]()\n\n### Interactive Elements Extraction\n\nThe `get_interactive_elements` tool retrieves all clickable, focusable, and input elements with their accessibility properties:\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"\"\"DOM Type dict Retrieval Tool, giving all interactive elements on page.\nNotes: [Elements ordered as displayed, Consider ordinal/numbered item positions, List ordinal represent z-index on page]\"\"\",\n name=\"get_interactive_elements\",\n)\n```\n\nElements are ordered by visual display position and include z-index representation.\n\n**资料来源：** [testzeus_hercules/core/tools/get_interactive_elements.py]()\n\n### Input Fields Retrieval\n\nThe `get_input_fields` tool specifically targets form input elements:\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"\"\"DOM Type dict Retrieval Tool, giving only html input types elements on page.\nNotes: [Elements ordered as displayed, Consider ordinal/numbered item positions]\"\"\",\n name=\"get_input_fields\",\n)\n```\n\n**资料来源：** [testzeus_hercules/core/tools/get_input_fields.py]()\n\n### Page Text Extraction\n\nThe `get_page_text` tool fetches text content from the DOM, stripping HTML tags for readability:\n\n```python\nasync def get_page_text() -> Annotated[str, \"DOM content based on type to analyze and decide\"]:\n # Uses innerText or documentElement.innerText\n text_content = await page.evaluate(\"() => document.body.innerText || document.documentElement.innerText\")\n```\n\n**资料来源：** [testzeus_hercules/core/tools/get_page_text.py]()\n\n### File Upload Handling\n\nThe `upload_file` tool supports two upload mechanisms:\n\n1. Direct file input: Sets files directly on `` elements\n2. File chooser API: Clicks element, intercepts file chooser, and sets files\n\n```python\n# Check element type\nelement_type = await element.evaluate(\"el => el.type\")\nif element_type != \"file\":\n # Use FileChooser API\n async with page.expect_file_chooser() as fc_info:\n await element.click()\n file_chooser = await fc_info.value\n await file_chooser.set_files(file_path)\n```\n\n**资料来源：** [testzeus_hercules/core/tools/upload_file.py]()\n\n### Clipboard Operations\n\nThe `read_clipboard` tool reads clipboard content with type specification:\n\n```python\n@tool(\n name=\"read_clipboard\",\n description=\"\"\"Reads the clipboard content from the current page.\n Accepts a parameter to specify the clipboard type: 'text' for plain text\n or 'binary' for a binary object representation.\"\"\"\n)\nasync def read_clipboard(clipboard_type: Annotated[str, \"'text' or 'binary'\"] = \"text\")\n```\n\n**资料来源：** [testzeus_hercules/core/extra_tools/clipboard_tools.py]()\n\n---\n\n## DOM Mutation Observation\n\nThe system monitors DOM changes in real-time using a mutation observer pattern, enabling agents to detect when actions cause new elements to appear.\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Tool\n participant Observer\n participant Page\n \n Agent->>Tool: Execute action\n Tool->>Observer: Subscribe to changes\n Tool->>Page: Perform DOM operation\n Page->>Observer: Mutation detected\n Observer->>Tool: DOM changes detected\n Tool->>Agent: Return result with new elements info\n Tool->>Observer: Unsubscribe\n```\n\n**资料来源：** [testzeus_hercules/utils/dom_mutation_observer.py]()\n**资料来源：** [testzeus_hercules/core/tools/enter_date_time.py]()\n\n### Wait Strategies\n\nThe `wait_for_non_loading_dom_state` function waits for the DOM to reach a stable state before proceeding:\n\n```python\nawait wait_for_non_loading_dom_state(page, max_wait_seconds=1)\n```\n\nThis prevents race conditions where tools attempt to interact with elements that are still being loaded or rendered.\n\n**资料来源：** [testzeus_hercules/utils/dom_helper.py]()\n\n---\n\n## Accessibility Integration\n\n### Accessibility Tree Generation\n\nThe `get_detailed_accessibility_tree.py` module extracts and formats accessibility information using Playwright's accessibility API:\n\n```python\nfrom testzeus_hercules.utils.get_detailed_accessibility_tree import (\n do_get_accessibility_info,\n rename_children,\n)\n```\n\n**资料来源：** [testzeus_hercules/utils/get_detailed_accessibility_tree.py]()\n\n### Accessibility Testing\n\nThe `run_accessibility_check` tool integrates axe-core for automated accessibility audits:\n\n```python\n# Inject axe-core from CDN\nresponse = await page.evaluate(f'fetch(\"{AXE_SCRIPT_URL}\").then(res => res.text())')\nawait page.add_script_tag(content=response)\n\n# Run accessibility checks\naxe_results = await page.evaluate(\"\"\"\n async () => {\n return await axe.run();\n }\n\"\"\")\n```\n\nViolations are logged with detailed failure summaries, enabling agents to identify and address accessibility issues.\n\n**资料来源：** [testzeus_hercules/core/tools/accessibility_calls.py]()\n\n---\n\n## Configuration\n\n### Command-Line Arguments\n\nThe `config.py` file defines extensive browser automation configuration options:\n\n| Argument | Type | Default | Description |\n|----------|------|---------|-------------|\n| `--browser-channel` | str | None | Browser channel (e.g., chrome-beta, firefox-nightly) |\n| `--browser-path` | str | None | Custom path to browser executable |\n| `--browser-version` | str | None | Specific browser version (e.g., '114', '115.0.1') |\n| `--enable-ublock` | flag | False | Enable uBlock Origin extension |\n| `--disable-ublock` | flag | False | Disable uBlock Origin extension |\n| `--auto-accept-screen-sharing` | flag | False | Auto-accept screen sharing prompts |\n| `--disable-auto-accept-screen-sharing` | flag | False | Disable auto screen sharing acceptance |\n\n**资料来源：** [testzeus_hercules/config.py]()\n\n### Global Configuration\n\nThe `get_global_conf()` function provides runtime configuration access for:\n\n- Source log folder paths\n- Proof path for screenshots and logs\n- Delay time between operations\n- Load state configuration\n\n**资料来源：** [testzeus_hercules/config.py]()\n\n---\n\n## Browser Logging\n\n### Interaction Logging\n\nThe `BrowserLogger` class records all browser interactions for debugging and proof generation:\n\n```python\nawait browser_logger.log_browser_interaction(\n tool_name=\"openurl\",\n action=\"navigate\",\n interaction_type=\"navigation\",\n success=True,\n additional_data={\n \"url\": url,\n \"title\": title,\n \"from_cache\": True,\n },\n)\n```\n\n**资料来源：** [testzeus_hercules/core/browser_logger.py]()\n**资料来源：** [testzeus_hercules/core/tools/open_url.py]()\n\n### Screenshot Capture\n\nTools automatically capture screenshots before and after execution:\n\n```python\nawait browser_manager.take_screenshots(f\"{function_name}_start\", page)\n# ... perform action ...\nawait browser_manager.take_screenshots(f\"{function_name}_end\", page)\n```\n\n**资料来源：** [testzeus_hercules/core/tools/hover.py]()\n\n### Selector Logging\n\nFailed selector interactions are logged with detailed error information:\n\n```python\nawait selector_logger.log_selector_interaction(\n tool_name=\"upload_file\",\n selector=selector,\n action=\"upload\",\n selector_type=\"css\",\n success=False,\n error_message=f\"Error: Selector '{selector}' not found.\",\n)\n```\n\n**资料来源：** [testzeus_hercules/core/tools/upload_file.py]()\n\n---\n\n## Agent Integration\n\n### BrowserNavAgent\n\nThe `SimpleHercules` class orchestrates agent-based browser automation:\n\n```python\nbrowser_nav_agent = BrowserNavAgent(\n self.browser_nav_agent_model_config,\n self.nav_agent_config[\"llm_config_params\"],\n self.nav_agent_config.get(\"other_settings\", {}).get(\"system_prompt\"),\n user_proxy_agent,\n)\n```\n\nAgents receive tools through the Tool Registry and execute browser operations autonomously based on natural language instructions.\n\n**资料来源：** [testzeus_hercules/core/simple_hercules.py]()\n\n### System Prompts\n\nAgent behavior is guided by system prompts that define DOM handling rules:\n\n```python\n# From prompts.py - key instructions for agents:\n- Use md attribute selectors for element identification\n- Never substring extracted HTML DOM\n- Remove entire sections if not needed (scripts, links)\n- Use innerText for text content retrieval\n- Verify task completion after execution\n- Use ##TERMINATE## signal when complete\n```\n\n**资料来源：** [testzeus_hercules/core/prompts.py]()\n\n---\n\n## Frontend Interface\n\n### CDP Stream Renderer\n\nThe project includes frontend interfaces for viewing browser sessions in real-time:\n\n| File | Purpose |\n|------|---------|\n| `frontend/non-interactive/index.html` | Basic screencast display |\n| `frontend/interactive/index.html` | Interactive viewer with mouse/keyboard input forwarding |\n\nThe interactive interface uses a hidden input element to capture focus and prevent scrolling while forwarding input events to the remote browser session.\n\n**资料来源：** [frontend/non-interactive/index.html]()\n**资料来源：** [frontend/interactive/index.html]()\n\n---\n\n## Summary\n\nBrowser Automation in TestZeus Hercules provides a production-ready framework for autonomous web interaction. Key capabilities include:\n\n1. **Multi-Browser Support**: Chromium, Firefox, and WebKit with extension support\n2. **Remote Browser Access**: CDP tunneling for BrowserStack and LambdaTest\n3. **Sophisticated Element Selection**: Accessibility-aware tools using the `md` attribute convention\n4. **Real-Time DOM Monitoring**: Mutation observers for detecting dynamic content changes\n5. **Comprehensive Logging**: Screenshots, interaction logs, and accessibility audits\n6. **Agent Integration**: LLM-powered automation through BrowserNavAgent\n\n---\n\n\n\n## Tool System\n\n### 相关页面\n\n相关主题：[Browser Automation](#browser-automation)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [testzeus_hercules/core/tools/tool_registry.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/tool_registry.py)\n- [testzeus_hercules/core/tools/click_using_selector.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/click_using_selector.py)\n- [testzeus_hercules/core/tools/enter_text_using_selector.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/enter_text_using_selector.py)\n- [testzeus_hercules/core/tools/hover.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/hover.py)\n- [testzeus_hercules/core/tools/drag_and_drop_tool.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/drag_and_drop_tool.py)\n- [testzeus_hercules/core/tools/get_interactive_elements.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/get_interactive_elements.py)\n- [testzeus_hercules/core/tools/accessibility_calls.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/accessibility_calls.py)\n- [testzeus_hercules/core/tools/upload_file.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/upload_file.py)\n- [testzeus_hercules/core/extra_tools/browser_assist_tools.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/extra_tools/browser_assist_tools.py)\n\n\n# Tool System\n\n## Overview\n\nThe Tool System is the core execution layer of TestZeus Hercules, providing AI agents with capabilities to interact with web pages through a unified, decorator-based interface. The system abstracts browser automation operations (clicking, typing, hovering, dragging, etc.) into discrete, callable tools that agents can invoke during test execution.\n\nTools serve as the fundamental building blocks that bridge natural language agent instructions with Playwright browser automation. Each tool encapsulates a specific browser interaction pattern, handles error cases gracefully, and returns structured results that agents can parse and respond to. 资料来源：[testzeus_hercules/core/tools/click_using_selector.py:1-50]()\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n subgraph \"Agent Layer\"\n A[\"Browser Nav Agent\"]\n B[\"Executor Nav Agent\"]\n end\n \n subgraph \"Tool Registry\"\n C[\"tool_registry.py\"]\n D[\"Tool Decorator\"]\n end\n \n subgraph \"Core Browser Tools\"\n E[\"click_using_selector\"]\n F[\"enter_text_using_selector\"]\n G[\"hover\"]\n H[\"drag_and_drop_tool\"]\n I[\"get_interactive_elements\"]\n end\n \n subgraph \"Extra Tools\"\n J[\"browser_assist_tools\"]\n K[\"accessibility_calls\"]\n L[\"upload_file\"]\n end\n \n subgraph \"Browser Automation\"\n M[\"Playwright Manager\"]\n N[\"Page Object\"]\n end\n \n A --> C\n B --> C\n C --> E\n C --> F\n C --> G\n C --> H\n C --> I\n C --> J\n J --> K\n J --> L\n E --> M\n F --> M\n G --> M\n M --> N\n```\n\n### Tool Categories\n\n| Category | Purpose | Location | Example Tools |\n|----------|---------|----------|---------------|\n| **Core Browser Tools** | Primary page interactions | `testzeus_hercules/core/tools/` | click, enter_text, hover, drag_drop |\n| **Extra Tools** | Auxiliary functionality | `testzeus_hercules/core/extra_tools/` | accessibility, browser_assist |\n| **Upload Tools** | File handling | `testzeus_hercules/core/tools/` | upload_file |\n\n## Tool Definition Pattern\n\n### The `@tool` Decorator\n\nAll tools in the system are defined using the `@tool` decorator, which registers the function with the tool registry and provides metadata for agent consumption.\n\n```python\nfrom functools import wraps\nfrom typing import Annotated, Any, Dict, List, Optional\n\ndef tool(agent_names: List[str], description: str, name: str):\n \"\"\"Decorator to register a function as a callable tool.\"\"\"\n def decorator(func):\n @wraps(func)\n async def wrapper(*args, **kwargs):\n return await func(*args, **kwargs)\n wrapper._tool_config = {\n \"agent_names\": agent_names,\n \"description\": description,\n \"name\": name,\n }\n return wrapper\n return decorator\n```\n\n### Tool Registration Metadata\n\n| Parameter | Type | Description | Required |\n|-----------|------|-------------|----------|\n| `agent_names` | `List[str]` | List of agent identifiers that can call this tool | Yes |\n| `description` | `str` | Human-readable description for the LLM | Yes |\n| `name` | `str` | Unique identifier for the tool | Yes |\n\nExample usage:\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"Click on an element using selector\",\n name=\"click\"\n)\nasync def click_element(selector: Annotated[str, \"CSS selector\"]) -> dict:\n # Implementation\n pass\n```\n\n资料来源：[testzeus_hercules/core/tools/click_using_selector.py:1-30]()\n\n## Core Browser Tools\n\n### Click Tool (`click_using_selector`)\n\nThe primary interaction tool for clicking on page elements.\n\n**Function Signature:**\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"used to click on an element in the DOM.\",\n name=\"click\"\n)\nasync def click_using_selector(\n selector: Annotated[\n str,\n \"md attribute value of the dom element to interact, md is an ID\"\n ],\n click_type: Annotated[\n Optional[str],\n \"type of click - left, right, double, mouseover, mouseenter, mouseleave, mouseexit, mousedown, mouseup\"\n ] = \"left\",\n timeout: Annotated[int, \"Timeout in milliseconds\"] = 30000,\n) -> Annotated[Dict[str, Any], \"Result of the click operation\"]\n```\n\n**Execution Flow:**\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant ClickTool\n participant PlaywrightManager\n participant Page\n participant SelectorLogger\n\n Agent->>ClickTool: click_using_selector(selector, click_type)\n ClickTool->>PlaywrightManager: find_element(selector)\n PlaywrightManager->>Page: locator(selector).first\n Page-->>PlaywrightManager: ElementHandle\n PlaywrightManager-->>ClickTool: element\n \n alt Element not found\n ClickTool->>SelectorLogger: log_selector_interaction(success=False)\n ClickTool-->>Agent: Error response\n end\n \n ClickTool->>Page: element.scroll_into_view_if_needed()\n ClickTool->>Page: element.is_visible()\n \n alt Element not visible\n ClickTool-->>Agent: Try another element response\n end\n \n ClickTool->>SelectorLogger: get_alternative_selectors()\n ClickTool->>SelectorLogger: get_element_attributes()\n ClickTool->>Page: element.click(click_type)\n \n alt Click success\n ClickTool->>SelectorLogger: log_selector_interaction(success=True)\n ClickTool-->>Agent: Success response\n else Click fails\n ClickTool->>SelectorLogger: log_selector_interaction(success=False)\n ClickTool-->>Agent: Error response\n end\n```\n\n**Error Handling:**\n\nThe click tool performs comprehensive error handling:\n\n1. **Element Not Found**: Logs selector interaction with `success=False` and raises `ValueError`\n2. **Element Not Visible**: Returns alternative suggestion response\n3. **Scroll Failure**: Gracefully continues (non-blocking)\n4. **Click Execution Failure**: Logs failure and returns error dictionary\n\n```python\nif element is None:\n await selector_logger.log_selector_interaction(\n tool_name=\"click\",\n selector=selector,\n action=type_of_click,\n selector_type=\"css\" if \"md=\" in selector else \"custom\",\n success=False,\n error_message=f'Element with selector: \"{selector}\" not found',\n )\n raise ValueError(f'Element with selector: \"{selector}\" not found')\n```\n\n资料来源：[testzeus_hercules/core/tools/click_using_selector.py:40-80]()\n\n### Enter Text Tool (`enter_text_using_selector`)\n\nHandles text input into form fields and contenteditable elements.\n\n**Function Signature:**\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"used to enter the given text into an input field or a contenteditable element.\",\n name=\"enter_text\"\n)\nasync def enter_text_using_selector(\n selector: Annotated[str, \"md attribute value of the dom element to interact\"],\n text_to_fill: Annotated[str, \"text to enter into the element\"],\n submit: Annotated[Optional[bool], \"whether to submit after entering text\"] = False,\n press_enter_after_input: Annotated[bool, \"press Enter key after filling text\"] = False,\n) -> Annotated[Dict[str, str], \"Result dictionary with summary and details\"]\n```\n\n### Hover Tool (`hover`)\n\nMoves mouse cursor over an element without clicking.\n\n**Function Signature:**\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"used to hover over an element in the DOM.\",\n name=\"hover\"\n)\nasync def hover_using_selector(\n selector: Annotated[str, \"md attribute value of the dom element to interact\"],\n timeout: Annotated[int, \"Timeout in milliseconds\"] = 30000,\n) -> Annotated[Dict[str, Any], \"Result of the hover operation\"]\n```\n\n### Drag and Drop Tool (`drag_and_drop_tool`)\n\nPerforms HTML5 drag-and-drop operations between elements.\n\n**Function Signature:**\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"used to drag and drop an element.\",\n name=\"drag_and_drop\"\n)\nasync def drag_and_drop(\n source: Annotated[str, \"md attribute value of source element\"],\n target: Annotated[str, \"md attribute value of target element\"],\n) -> Annotated[Dict[str, str], \"Result of the drag and drop operation\"]\n```\n\n### Get Interactive Elements (`get_interactive_elements`)\n\nRetrieves all interactive elements from the current page DOM.\n\n**Function Signature:**\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"Get interactive elements from the current page\",\n name=\"get_interactive_elements\"\n)\nasync def get_interactive_elements() -> Annotated[str, \"JSON string of interactive elements\"]\n```\n\n**DOM Processing Logic:**\n\nThe tool executes JavaScript in the browser context to identify interactive elements:\n\n```javascript\nconst isInteractive = (element) => {\n // Check input-related elements\n const inputRelatedTags = new Set(['input', 'textarea', 'select', ...]);\n const interactiveRoles = new Set(['button', 'link', 'checkbox', ...]);\n \n // Check for ARIA attributes\n const hasAriaProps = element.hasAttribute('aria-haspopup') ||\n element.hasAttribute('aria-expanded') ||\n element.hasAttribute('aria-checked');\n \n // Check cursor style\n const style = window.getComputedStyle(element);\n const hasPointerCursor = style.cursor === 'pointer';\n \n // Check draggable attribute\n const isDraggable = element.draggable;\n \n // Skip body and its direct children\n if (element.tagName.toLowerCase() === 'body') return false;\n \n return hasAriaProps || hasClickHandler || isDraggable;\n};\n```\n\n资料来源：[testzeus_hercules/core/tools/get_interactive_elements.py:1-50]()\n\n### Upload File Tool (`upload_file`)\n\nHandles file upload dialogs by setting file paths on input elements.\n\n**Function Signature:**\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"Upload a file to the page\",\n name=\"upload_file\"\n)\nasync def upload_file(\n selector: Annotated[str, \"md attribute value of file input element\"],\n file_path: Annotated[str, \"Path to the file to upload\"],\n) -> Annotated[Dict[str, str], \"Result of the upload operation\"]\n```\n\n## Extra Tools System\n\n### Dynamic Tool Loading\n\nThe extra tools are loaded dynamically at runtime using Python's `pkgutil` module. This allows the system to extend functionality without modifying core code.\n\n**Loading Mechanism:**\n\n```python\n# testzeus_hercules/core/extra_tools/__init__.py\nimport importlib\nimport pkgutil\nfrom pathlib import Path\n\nfrom testzeus_hercules.config import get_global_conf\n\npackage_path = Path(__file__).parent\n\nif get_global_conf().get_load_extra_tools().lower().strip() != \"false\":\n for _, module_name, _ in pkgutil.iter_modules([str(package_path)]):\n full_module_name = f\"testzeus_hercules.core.extra_tools.{module_name}\"\n module = importlib.import_module(full_module_name)\n \n # Export all public attributes to current namespace\n for attribute_name in dir(module):\n if not attribute_name.startswith(\"_\"):\n globals()[attribute_name] = getattr(module, attribute_name)\n```\n\n**Configuration:**\n\nExtra tools can be disabled via configuration:\n\n```bash\npython -m testzeus_hercules --load-extra-tools=false\n```\n\n资料来源：[testzeus_hercules/core/extra_tools/__init__.py:1-25]()\n\n### Accessibility Calls (`accessibility_calls`)\n\nProvides accessibility testing using the axe-core library.\n\n**Function Signature:**\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"Check page accessibility using axe-core\",\n name=\"check_accessibility\"\n)\nasync def check_accessibility(page_path: Annotated[str, \"Page path or URL\"]) -> str\n```\n\n**Execution Flow:**\n\n1. Fetches axe-core script from CDN\n2. Injects script into page\n3. Runs `axe.run()` in browser context\n4. Collects violations and incomplete checks\n5. Logs results in structured format\n\n```javascript\n// Inject axe-core\nawait page.evaluate(\n `fetch(\"${AXE_SCRIPT_URL}\").then(res => res.text())`\n);\n\n// Run accessibility checks\nconst results = await page.evaluate(\"async () => { return await axe.run(); }\");\n```\n\n**Response Format:**\n\n```json\n{\n \"status\": \"success|failure\",\n \"message\": \"Human readable summary\",\n \"details\": [\"failure summary 1\", \"failure summary 2\"]\n}\n```\n\n资料来源：[testzeus_hercules/core/tools/accessibility_calls.py:1-80]()\n\n## Tool Return Format\n\nAll tools return a standardized dictionary structure:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `summary_message` | `str` | Brief status message for agent consumption |\n| `detailed_message` | `str` | Extended information including errors if any |\n| `status` | `str` | Operation status (success/failure) |\n\n**Success Response Example:**\n\n```python\nreturn {\n \"summary_message\": f'Successfully clicked element with selector: \"{selector}\"',\n \"detailed_message\": f'Element with selector: \"{selector}\" clicked successfully. Tag: {element_tag_name}',\n}\n```\n\n**Error Response Example:**\n\n```python\nreturn {\n \"summary_message\": f'Element with selector: \"{selector}\" is not visible, Try another element',\n \"detailed_message\": f'Element with selector: \"{selector}\" is not visible, Try another element',\n}\n```\n\n## Selector Logging System\n\nEvery tool interaction is logged using the `SelectorLogger` for proof generation and debugging.\n\n### Logging Interface\n\n```python\nfrom testzeus_hercules.utils.browser_logger import get_browser_logger\n\nselector_logger = get_browser_logger(get_global_conf().get_proof_path())\n\n# Log successful interaction\nawait selector_logger.log_selector_interaction(\n tool_name=\"click\",\n selector=selector,\n action=\"left\",\n selector_type=\"css\",\n success=True,\n)\n\n# Log failed interaction\nawait selector_logger.log_selector_interaction(\n tool_name=\"click\",\n selector=selector,\n action=\"left\",\n selector_type=\"css\",\n success=False,\n error_message=\"Element not found\",\n)\n```\n\n### Captured Data\n\nThe logger captures:\n- Tool name and action type\n- Selector used\n- Selector type (CSS vs custom)\n- Success/failure status\n- Alternative selectors for the element\n- Element attributes\n- Error messages on failure\n\n## Agent Integration\n\n### Browser Nav Agent\n\nThe primary agent that consumes browser tools. It receives natural language instructions and translates them into tool calls.\n\n**Tool Invocation Pattern:**\n\n```python\n# From executor_nav_agent.py\nasync def execute_task(self, instruction: str):\n # Agent decides which tool to call\n # Tool receives selector from instruction\n result = await click_using_selector(\n selector=\"[md='submit-button']\",\n click_type=\"left\"\n )\n \n # Agent processes result\n if \"error\" in result.get(\"summary_message\", \"\").lower():\n # Handle error or try alternative\n```\n\n### Executor Nav Agent\n\nHandles script execution and Python sandbox operations:\n\n**Script Execution Context:**\n\n| Variable | Type | Description |\n|----------|------|-------------|\n| `page` | `Page` | Playwright page object |\n| `browser` | `Browser` | Playwright browser instance |\n| `context` | `BrowserContext` | Browser context |\n| `playwright_manager` | `PlaywrightManager` | Manager instance |\n| `logger` | `Logger` | Logging utility |\n| `config` | `GlobalConf` | Global configuration |\n\n资料来源：[testzeus_hercules/core/agents/executor_nav_agent.py:1-50]()\n\n## Bulk Operations\n\nThe tool system supports bulk execution for batch operations:\n\n### Bulk Slider Tool\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"used to set slider values in multiple sliders in single attempt.\",\n name=\"bulk_set_slider\"\n)\nasync def bulk_set_slider(\n entries: Annotated[\n List[List[str]],\n \"List of [selector, value] pairs\",\n ],\n) -> Annotated[List[Dict[str, str]], \"List of results\"]\n```\n\n## Configuration\n\n### Command Line Arguments\n\nThe tool system behavior can be configured via CLI:\n\n| Argument | Type | Description |\n|----------|------|-------------|\n| `--llm-model` | `str` | LLM model for agent decisions |\n| `--llm-temperature` | `float` | LLM sampling temperature (0.0-1.0) |\n| `--agents-llm-config-file` | `str` | Path to agents LLM config file |\n| `--enable-portkey` | `flag` | Enable Portkey LLM routing |\n| `--portkey-api-key` | `str` | Portkey API key |\n| `--browser-channel` | `str` | Browser channel (chrome-beta, etc.) |\n| `--browser-version` | `str` | Specific browser version |\n| `--enable-ublock` | `flag` | Enable uBlock Origin extension |\n| `--load-extra-tools` | `str` | Load extra tools (default: true) |\n\n资料来源：[testzeus_hercules/config.py:1-100]()\n\n## Summary\n\nThe Tool System provides:\n\n1. **Unified Interface**: All browser interactions follow the `@tool` decorator pattern\n2. **Agent Compatibility**: Tools specify which agents can invoke them\n3. **Error Resilience**: Graceful handling of element not found, not visible, and execution failures\n4. **Proof Generation**: Comprehensive logging of all selector interactions\n5. **Extensibility**: Dynamic loading of extra tools without core modifications\n6. **Standardized Results**: Consistent return format across all tools\n\nThis architecture enables AI agents to reliably control browser automation while maintaining clean separation of concerns and testable component boundaries.\n\n---\n\n\n\n## LLM Configuration\n\n### 相关页面\n\n相关主题：[Agent System](#agent-system), [Memory Management](#memory-management)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [testzeus_hercules/core/agents_llm_config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents_llm_config.py)\n- [agents_llm_config-example.json](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/agents_llm_config-example.json)\n- [testzeus_hercules/utils/llm_helper.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/llm_helper.py)\n- [testzeus_hercules/utils/model_utils.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/model_utils.py)\n- [docs/GPT5_USAGE.md](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/docs/GPT5_USAGE.md)\n\n\n# LLM Configuration\n\n## Overview\n\nThe LLM Configuration system in testzeus-hercules provides a flexible, multi-provider framework for configuring Large Language Models across different agent types. This system enables the framework to support various LLM providers (OpenAI, Anthropic, Ollama, Azure) while maintaining provider-specific configurations through a centralized registry mechanism.\n\nThe configuration architecture supports:\n- Multiple LLM providers simultaneously\n- Per-agent model selection\n- Dynamic parameter adaptation based on model family\n- External configuration file loading\n- Environment variable integration\n\n资料来源：[testzeus_hercules/core/agents_llm_config.py:1-20]()\n\n## Architecture\n\n### High-Level Component Architecture\n\n```mermaid\ngraph TD\n A[CLI Arguments / Environment] --> B[Global Config]\n C[agents-llm-config-file.json] --> D[AgentsLLMConfig]\n D --> E[AgentRegistry]\n E --> F[Provider Configs]\n F --> G[planner_agent]\n F --> H[nav_agent]\n F --> I[mem_agent]\n F --> J[helper_agent]\n B --> K[Model Utils]\n K --> L[adapt_llm_params_for_model]\n L --> G\n L --> H\n L --> I\n L --> J\n```\n\n### Configuration Flow\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI Arguments\n participant Config as Global Config\n participant JSON as LLM Config File\n participant Processor as AgentsLLMConfig\n participant Registry as AgentRegistry\n participant Agent as SimpleHercules\n \n CLI->>Config: Parse --llm-* arguments\n JSON->>Processor: load_from_file()\n Processor->>Registry: register_provider()\n Registry->>Registry: Store configs per provider\n Config->>Agent: Pass model configs\n Agent->>ModelUtils: adapt_llm_params_for_model()\n ModelUtils->>Agent: Adapted LLM params\n```\n\n资料来源：[testzeus_hercules/core/agents_llm_config.py:25-50]()\n\n## Core Components\n\n### AgentRegistry\n\nThe `AgentRegistry` manages configurations for multiple providers and supports switching between them.\n\n```python\nclass AgentRegistry:\n def __init__(self) -> None:\n self._providers: Dict[str, Dict[str, AgentConfig]] = {}\n self._active_provider: Optional[str] = None\n```\n\n| Method | Purpose |\n|--------|---------|\n| `register_provider(provider_key, configs)` | Register agent configs for a provider |\n| `get_active_provider()` | Retrieve currently active provider configuration |\n| `set_active_provider(provider_key)` | Switch active provider |\n| `get_all_providers()` | List all registered providers |\n\n资料来源：[testzeus_hercules/core/agents_llm_config.py:20-35]()\n\n### AgentsLLMConfig\n\nThe main configuration processor that handles loading and normalization of agent configurations.\n\n```python\nclass AgentsLLMConfig:\n def __init__(self) -> None:\n self.registry = AgentRegistry()\n \n def load_from_file(self, file_path: str, provider_key: Optional[str] = None) -> None\n def normalize_agent_config(self, agent_config: Dict[str, Any]) -> AgentConfig\n```\n\n资料来源：[testzeus_hercules/core/agents_llm_config.py:40-70]()\n\n## Agent Types\n\nThe framework defines four specialized agent roles, each with configurable LLM parameters:\n\n| Agent Type | Purpose | Typical Model Requirements |\n|------------|---------|----------------------------|\n| `planner_agent` | Strategic task planning and decomposition | High reasoning capability |\n| `nav_agent` | Browser navigation and UI interaction | Vision-capable, fast response |\n| `mem_agent` | Memory and context management | Balanced performance |\n| `helper_agent` | Utility functions and data processing | Variable based on task |\n\n资料来源：[testzeus_hercules/core/simple_hercules.py:1-30]()\n\n## Configuration File Format\n\n### JSON Schema Structure\n\n```json\n{\n \"provider_name\": {\n \"agent_type\": {\n \"model_name\": \"string\",\n \"model_api_key\": \"string\",\n \"model_api_type\": \"openai|anthropic|azure|ollama\",\n \"model_client_host\": \"string (optional)\",\n \"model_native_tool_calls\": true|false,\n \"model_hide_tools\": \"if_any_run|user|never\",\n \"llm_config_params\": {\n \"cache_seed\": null|integer,\n \"temperature\": 0.0,\n \"seed\": 12345,\n \"max_tokens\": 4096,\n \"presence_penalty\": 0.0,\n \"frequency_penalty\": 0.0,\n \"stop\": []\n }\n }\n }\n}\n```\n\n### Example Configuration\n\n```json\n{\n \"openai\": {\n \"planner_agent\": {\n \"model_name\": \"gpt-4o\",\n \"model_api_key\": \"${OPENAI_API_KEY}\",\n \"model_api_type\": \"openai\",\n \"llm_config_params\": {\n \"cache_seed\": null,\n \"temperature\": 0.0,\n \"seed\": 12345\n }\n }\n },\n \"anthropic\": {\n \"nav_agent\": {\n \"model_name\": \"claude-3-5-haiku-latest\",\n \"model_api_key\": \"\",\n \"model_api_type\": \"anthropic\",\n \"llm_config_params\": {\n \"cache_seed\": null,\n \"temperature\": 0.0\n }\n }\n }\n}\n```\n\n资料来源：[agents_llm_config-example.json:1-60]()\n\n## CLI Configuration Options\n\nThe framework provides comprehensive command-line arguments for LLM configuration:\n\n### Basic LLM Parameters\n\n| Argument | Type | Description |\n|----------|------|-------------|\n| `--llm-model` | string | Name of the LLM model |\n| `--llm-model-api-key` | string | API key for the LLM model |\n| `--llm-model-base-url` | string | Base URL for the LLM API |\n| `--llm-model-api-type` | string | API type (openai, anthropic, azure, etc.) |\n| `--llm-temperature` | float | Temperature for LLM sampling (0.0-1.0) |\n\n### LLM Configuration File Options\n\n| Argument | Type | Description |\n|----------|------|-------------|\n| `--agents-llm-config-file` | string | Path to the agents LLM configuration file |\n| `--agents-llm-config-file-ref-key` | string | Reference key for selecting provider |\n\n### Parameter Configuration\n\n| Argument | Type | Description |\n|----------|------|-------------|\n| `LLM_MODEL_PRICING` | env | Model pricing for cost tracking |\n| `LLM_MODEL_TEMPERATURE` | env | Default temperature setting |\n| `LLM_MODEL_CACHE_SEED` | env | Cache seed for reproducible results |\n| `LLM_MODEL_SEED` | env | Random seed for generation |\n| `LLM_MODEL_MAX_TOKENS` | env | Maximum tokens in response |\n| `LLM_MODEL_PRESENCE_PENALTY` | env | Presence penalty (-2.0 to 2.0) |\n| `LLM_MODEL_FREQUENCY_PENALTY` | env | Frequency penalty (-2.0 to 2.0) |\n| `LLM_MODEL_STOP` | env | Stop sequences |\n\n资料来源：[testzeus_hercules/config.py:1-100]()\n\n## Portkey Integration\n\nThe framework supports Portkey for advanced LLM routing with fallback and load balancing capabilities.\n\n### Portkey Configuration Options\n\n| Argument | Type | Description |\n|----------|------|-------------|\n| `--enable-portkey` | flag | Enable Portkey integration |\n| `--portkey-api-key` | string | API key for Portkey |\n| `--portkey-strategy` | choice | Routing strategy: `fallback` or `loadbalance` |\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `ENABLE_PORTKEY` | Enable/disable Portkey |\n| `PORTKEY_API_KEY` | Portkey API key |\n| `PORTKEY_STRATEGY` | Routing strategy |\n| `PORTKEY_CACHE_ENABLED` | Enable response caching |\n| `PORTKEY_TARGETS` | Target models for routing |\n| `PORTKEY_GUARDRAILS` | Enable safety guardrails |\n| `PORTKEY_RETRY_COUNT` | Number of retries on failure |\n\n资料来源：[testzeus_hercules/config.py:50-80]()\n\n## Model Parameter Adaptation\n\nThe `model_utils` module provides intelligent parameter adaptation based on the model family being used.\n\n### adapt_llm_params_for_model\n\n```python\ndef adapt_llm_params_for_model(model_name: str, llm_config_params: Dict) -> Dict\n```\n\nThis function automatically adjusts LLM parameters based on the detected model family:\n\n| Model Family | Adaptation Behavior |\n|--------------|---------------------|\n| o1-series | Removes temperature, adjusts max_tokens handling |\n| GPT-4o | Standard parameters |\n| Claude | Adjusts for Anthropic API format |\n| Ollama | Configures for local inference |\n\n### Applied to All Agents\n\n```python\n# In SimpleHercules initialization\nplanner_model = self.planner_agent_config[\"model_config_params\"].get(\"model\") or \\\n self.planner_agent_config[\"model_config_params\"].get(\"model_name\")\n\nself.planner_agent_config[\"llm_config_params\"] = adapt_llm_params_for_model(\n planner_model, \n self.planner_agent_config[\"llm_config_params\"]\n)\n```\n\n资料来源：[testzeus_hercules/core/simple_hercules.py:100-130]()\n\n## LLM Helper Utilities\n\nThe `llm_helper` module provides utility functions for LLM interactions:\n\n| Function | Purpose |\n|----------|---------|\n| `convert_model_config_to_autogen_format()` | Convert config to AutoGen format |\n| `create_multimodal_agent()` | Create agents with vision capabilities |\n| `extract_target_helper()` | Extract target information from responses |\n| `format_plan_steps()` | Format planning step outputs |\n| `parse_agent_response()` | Parse agent response structure |\n| `process_chat_message_content()` | Process chat message content |\n| `parse_response()` | General response parsing |\n\n资料来源：[testzeus_hercules/utils/llm_helper.py:1-30]()\n\n## Environment Variable Configuration\n\n### Full Configuration Matrix\n\n| Environment Variable | Type | Default | Purpose |\n|---------------------|------|---------|---------|\n| `LLM_MODEL_PRICING` | dict | - | Model pricing information |\n| `LLM_MODEL_TEMPERATURE` | float | 0.0 | Default sampling temperature |\n| `LLM_MODEL_CACHE_SEED` | int | null | Caching seed |\n| `LLM_MODEL_SEED` | int | - | Random seed |\n| `LLM_MODEL_MAX_TOKENS` | int | 4096 | Max response tokens |\n| `LLM_MODEL_PRESENCE_PENALTY` | float | 0.0 | Presence penalty |\n| `LLM_MODEL_FREQUENCY_PENALTY` | float | 0.0 | Frequency penalty |\n| `LLM_MODEL_STOP` | list | [] | Stop sequences |\n| `TOKEN_VERBOSE` | bool | false | Enable token verbose logging |\n| `HF_HOME` | path | - | HuggingFace cache location |\n| `TOKENIZERS_PARALLELISM` | bool | false | Parallel tokenizer config |\n\n资料来源：[testzeus_hercules/config.py:100-150]()\n\n## Multi-Provider Configuration\n\n### Provider Switching\n\nThe system supports runtime provider switching through the configuration file:\n\n```mermaid\ngraph LR\n A[Config File] --> B[\"provider: openai\"]\n A --> C[\"provider: anthropic\"]\n B --> D[\"planner_agent: GPT-4\"]\n B --> E[\"nav_agent: GPT-4o-mini\"]\n C --> F[\"planner_agent: Claude-3\"]\n C --> G[\"nav_agent: Claude-3-Haiku\"]\n```\n\n### Selecting Active Provider\n\n```bash\npython -m testzeus_hercules \\\n --agents-llm-config-file ./config.json \\\n --agents-llm-config-file-ref-key \"anthropic\"\n```\n\n资料来源：[testzeus_hercules/core/agents_llm_config.py:60-80]()\n\n## Integration with SimpleHercules\n\nThe `SimpleHercules` class integrates all LLM configurations:\n\n```python\nclass SimpleHercules:\n def __init__(\n self,\n planner_agent_config: Dict[str, Any],\n nav_agent_config: Dict[str, Any],\n mem_agent_config: Dict[str, Any],\n helper_agent_config: Dict[str, Any],\n planner_max_chat_round: int = 50,\n browser_nav_max_chat_round: int = 100,\n ):\n # Configuration processing\n self.planner_agent_config = planner_agent_config\n self.nav_agent_config = nav_agent_config\n self.mem_agent_config = mem_agent_config\n self.helper_agent_config = helper_agent_config\n \n # Parameter adaptation per agent\n from testzeus_hercules.utils.model_utils import adapt_llm_params_for_model\n \n self.planner_agent_config[\"llm_config_params\"] = adapt_llm_params_for_model(\n planner_model, \n self.planner_agent_config[\"llm_config_params\"]\n )\n```\n\n资料来源：[testzeus_hercules/core/simple_hercules.py:50-100]()\n\n## Best Practices\n\n### 1. Configuration File Organization\n\n- Group configurations by provider (openai, anthropic, etc.)\n- Use environment variables for sensitive API keys\n- Maintain consistent agent naming across providers\n\n### 2. Model Selection Guidelines\n\n| Use Case | Recommended Models |\n|----------|-------------------|\n| Complex planning | GPT-4, Claude-3-Opus |\n| Fast navigation | GPT-4o-mini, Claude-3-Haiku |\n| Vision tasks | GPT-4o, Claude-3-Sonnet |\n| Local inference | Ollama models |\n\n### 3. Parameter Tuning\n\n- Use `temperature: 0.0` for deterministic outputs\n- Set appropriate `max_tokens` based on expected response length\n- Enable `model_native_tool_calls` for better function calling\n\n### 4. Cost Optimization\n\n- Use `LLM_MODEL_PRICING` for tracking\n- Enable Portkey caching with `PORTKEY_CACHE_ENABLED`\n- Consider fallback strategies for reliability\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Model not recognized | Check `model_name` matches provider format |\n| Temperature ignored | Some models (o1-series) ignore temperature parameter |\n| API key errors | Ensure `${ENV_VAR}` syntax or actual key in config |\n| Provider not found | Verify provider key matches config file structure |\n\n### Debug Configuration\n\n```bash\nexport TOKEN_VERBOSE=true\nexport ENABLE_BROWSER_LOGS=true\npython -m testzeus_hercules --llm-model gpt-4o --llm-temperature 0.7\n```\n\n## See Also\n\n- [GPT-5 Usage Guide](../docs/GPT5_USAGE.md)\n- [Browser Configuration](./browser-configuration.md)\n- [Agent Architecture](./agent-architecture.md)\n\n---\n\n\n\n## Memory Management\n\n### 相关页面\n\n相关主题：[Agent System](#agent-system), [LLM Configuration](#llm-configuration)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [testzeus_hercules/core/memory/state_handler.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/state_handler.py)\n- [testzeus_hercules/core/memory/dynamic_ltm.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/dynamic_ltm.py)\n- [testzeus_hercules/core/memory/static_ltm.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/static_ltm.py)\n\n\n# Memory Management\n\n## Overview\n\nThe Memory Management system in testzeus-hercules provides persistent and contextual memory capabilities for AI agents executing browser automation tests. The system consists of three primary components: **Static LTM** (Long Term Memory), **Dynamic LTM**, and **State Handler**, each serving distinct purposes in managing test execution context and data persistence.\n\nThe architecture follows a multi-layered approach where Static LTM loads pre-configured test data, Dynamic LTM manages vector-based retrieval augmented memory, and State Handler provides runtime state tracking for agent coordination.\n\n```mermaid\ngraph TD\n A[Testzeus-Hercules] --> B[Static LTM]\n A --> C[Dynamic LTM]\n A --> D[State Handler]\n \n B --> E[Test Data Files]\n B --> F[Stored Data]\n B --> G[Run Data]\n \n C --> H[Vector Store]\n C --> I[RetrieveUserProxyAgent]\n \n D --> J[_state_string]\n D --> K[_state_dict]\n \n L[Agents] --> M[Memory Access]\n M --> B\n M --> C\n M --> D\n```\n\n## Static LTM (Long Term Memory)\n\n### Purpose and Scope\n\nStatic LTM is responsible for loading and consolidating pre-configured test data at application initialization. It operates as a singleton pattern, ensuring that all test data is loaded once and made available throughout the test execution lifecycle.\n\n资料来源：[testzeus_hercules/core/memory/static_ltm.py:1-47]()\n\n### Implementation\n\nThe `StaticLTM` class extends the singleton pattern to ensure only one instance exists:\n\n```python\nclass StaticLTM:\n _instance = None\n\n def __new__(cls) -> \"StaticLTM\":\n if cls._instance is None:\n cls._instance = super().__new__(cls)\n cls._instance._initialize()\n return cls._instance\n```\n\n资料来源：[testzeus_hercules/core/memory/static_ltm.py:17-22]()\n\n### Data Consolidation\n\nDuring initialization, Static LTM consolidates three types of data sources:\n\n| Data Source | Description | Method |\n|-------------|-------------|--------|\n| Base Test Data | Loaded from `test_data.txt` via `load_data()` | `StaticDataLoader` |\n| Stored Data | User-defined test artifacts | `get_stored_data()` |\n| Run Data | Previous test execution context | `get_run_data()` |\n\n资料来源：[testzeus_hercules/core/memory/static_ltm.py:26-34]()\n\nThe consolidated data is stored in `self.consolidated_data` and accessed via `get_user_ltm()`:\n\n```python\ndef get_user_ltm(self) -> Optional[str]:\n return self.consolidated_data\n```\n\n资料来源：[testzeus_hercules/core/memory/static_ltm.py:40-47]()\n\n### Usage Pattern\n\nAgents access Static LTM through a module-level function:\n\n```python\ndef get_user_ltm() -> Optional[str]:\n return StaticLTM().get_user_ltm()\n```\n\n资料来源：[testzeus_hercules/core/memory/static_ltm.py:50-54]()\n\n## Dynamic LTM\n\n### Purpose and Scope\n\nDynamic LTM provides runtime memory management with vector-based retrieval capabilities. It enables agents to store, retrieve, and utilize contextual information during test execution using a `RetrieveUserProxyAgent` backed by ChromaDB for vector storage.\n\n资料来源：[testzeus_hercules/core/memory/dynamic_ltm.py:1-40]()\n\n### Core Components\n\n#### SilentRetrieveUserProxyAgent\n\nA specialized agent that extends `RetrieveUserProxyAgent` with suppressed output to prevent console noise during agent conversations:\n\n```python\nclass SilentRetrieveUserProxyAgent(RetrieveUserProxyAgent):\n @suppress_prints\n def initiate_chat(self, *args: Any, **kwargs: Any) -> Any:\n return super().initiate_chat(*args, **kwargs)\n\n @suppress_prints\n async def a_initiate_chat(self, *args: Any, **kwargs: Any) -> Any:\n return await super().a_initiate_chat(*args, **kwargs)\n```\n\n资料来源：[testzeus_hercules/core/memory/dynamic_ltm.py:37-46]()\n\n#### Print Suppression Decorator\n\nThe `@suppress_prints` decorator redirects stdout to a `StringIO` buffer during function execution:\n\n```python\ndef suppress_prints(func):\n @functools.wraps(func)\n def wrapper(*args, **kwargs):\n silent_stdout = io.StringIO()\n original_stdout, sys.stdout = sys.stdout, silent_stdout\n try:\n return func(*args, **kwargs)\n finally:\n sys.stdout = original_stdout\n return wrapper\n```\n\n资料来源：[testzeus_hercules/core/memory/dynamic_ltm.py:17-29]()\n\n### Integration with Configuration\n\nDynamic LTM respects global configuration to enable or disable its functionality:\n\n```python\nfrom testzeus_hercules.config import get_global_conf\n\ndef save_content(self, content: str) -> None:\n config = get_global_conf()\n if not config.should_use_dynamic_ltm():\n return # Skip when disabled\n```\n\n资料来源：[testzeus_hercules/core/simple_hercules.py:89-94]()\n\n### External Dependencies\n\nDynamic LTM utilizes the `unstructured` library for document parsing:\n\n```python\nfrom unstructured.documents.elements import NarrativeText, Text, Title\nfrom unstructured.partition.auto import partition\n```\n\n资料来源：[testzeus_hercules/core/memory/dynamic_ltm.py:13-14]()\n\n## State Handler\n\n### Purpose and Scope\n\nState Handler provides lightweight runtime state management for coordinating data between agents during test execution. It maintains module-level dictionaries for storing string-based state and structured data.\n\n资料来源：[testzeus_hercules/core/memory/state_handler.py:1-70]()\n\n### Module-Level State Storage\n\n```python\n# Module-level state string\n_state_string: Dict[str, str] = defaultdict(str)\n_state_dict: Dict[str, Any] = defaultdict(deque)\n```\n\n资料来源：[testzeus_hercules/core/memory/state_handler.py:13-14]()\n\n### store_data Tool\n\nThe `store_data` function is registered as a tool for browser, API, and SQL navigation agents to persist information:\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\", \"api_nav_agent\", \"sql_nav_agent\"],\n description=\"Tool to store information.\",\n name=\"store_data\",\n)\ndef store_data(\n text: Annotated[str, \"The confirmation of stored value.\"],\n) -> Annotated[Dict[str, Union[str, None]], \"A dictionary containing a 'message' key...\"]:\n global _state_string\n try:\n DynamicLTM().save_content(text)\n _state_string[get_global_conf().get_default_test_id()] += text\n return {\"message\": \"Text appended successfully.\"}\n except Exception as e:\n return {\"error\": str(e)}\n```\n\n资料来源：[testzeus_hercules/core/memory/state_handler.py:23-47]()\n\n### Key Behaviors\n\n| Behavior | Description |\n|----------|-------------|\n| Test ID Isolation | State is keyed by `get_global_conf().get_default_test_id()` |\n| Dual Storage | Data propagates to both `_state_string` and Dynamic LTM |\n| Error Resilience | Returns error dictionary instead of raising exceptions |\n\n资料来源：[testzeus_hercules/core/memory/state_handler.py:30-46]()\n\n## Memory Architecture Diagram\n\n```mermaid\ngraph LR\n subgraph \"Initialization Phase\"\n A[Load Config] --> B[StaticLTM Singleton]\n B --> C[Load test_data.txt]\n C --> D[Consolidate Data]\n end\n \n subgraph \"Runtime Phase\"\n E[Agents Execute Tests]\n E --> F[store_data Tool Call]\n F --> G[State Handler]\n G --> H[DynamicLTM.save_content]\n H --> I[Vector Store Update]\n \n J[Test Query] --> K[RetrieveUserProxyAgent]\n K --> L[Vector Similarity Search]\n L --> M[Context Injection]\n M --> E\n end\n```\n\n## Integration with SimpleHercules\n\nThe `SimpleHercules` class coordinates all memory components:\n\n```python\nclass SimpleHercules:\n def _save_to_memory(self, content: str) -> None:\n \"\"\"Helper method to save content to memory.\"\"\"\n config = get_global_conf()\n if not config.should_use_dynamic_ltm():\n return\n\n if self.memory:\n self.memory.save_content(content)\n else:\n logger.warning(\"Memory system not initialized\")\n```\n\n资料来源：[testzeus_hercules/core/simple_hercules.py:85-97]()\n\n### Memory Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant SH as SimpleHercules\n participant DLT as DynamicLTM\n participant CFG as Config\n participant LOG as Logger\n\n SH->>CFG: should_use_dynamic_ltm()\n CFG-->>SH: boolean\n SH->>DLT: save_content(content)\n alt LTM Enabled\n DLT->>DLT: Vector store update\n DLT-->>SH: success\n else LTM Disabled\n DLT-->>SH: skipped\n end\n```\n\n## Configuration\n\n### Global Configuration Methods\n\n| Method | Purpose |\n|--------|---------|\n| `should_use_dynamic_ltm()` | Check if Dynamic LTM is enabled |\n| `get_hf_home()` | Get HuggingFace cache directory for vector store |\n| `get_default_test_id()` | Get current test execution identifier |\n\n### Related Configuration File\n\nThe configuration is managed through `testzeus_hercules/config.py`, which provides command-line arguments for memory-related settings including:\n\n- `--reuse-vector-db`: Reuse existing vector DB instead of creating fresh one\n- `--sandbox-tenant-id`: Python sandbox tenant configuration\n\n资料来源：[testzeus_hercules/config.py:45-58]()\n\n## Data Flow Summary\n\n| Layer | Storage Type | Access Pattern | Persistence |\n|-------|--------------|----------------|-------------|\n| Static LTM | In-memory string | Singleton `get_user_ltm()` | Session-scoped |\n| Dynamic LTM | Vector (ChromaDB) | RetrieveUserProxyAgent | Persistent |\n| State Handler | In-memory dict | Module-level `_state_string` | Test execution-scoped |\n\n## Error Handling\n\nAll memory components implement robust error handling:\n\n```python\ntry:\n DynamicLTM().save_content(text)\n _state_string[get_global_conf().get_default_test_id()] += text\n return {\"message\": \"Text appended successfully.\"}\nexcept Exception as e:\n traceback.print_exc()\n logger.error(f\"An error occurred while appending to state: {e}\")\n return {\"error\": str(e)}\n```\n\n资料来源：[testzeus_hercules/core/memory/state_handler.py:30-42]()\n\n## Related Components\n\n| Component | File Path | Role |\n|-----------|-----------|------|\n| PlannerAgent | `core/agents/high_level_planner_agent.py` | Consumes memory for test planning |\n| ExecutorNavAgent | `core/agents/executor_nav_agent.py` | Executes test steps with memory context |\n| BaseNavAgent | `core/agents/base_nav_agent.py` | Agent base class with memory integration |\n\n## Summary\n\nThe Memory Management system in testzeus-hercules implements a comprehensive multi-tier approach:\n\n1. **Static LTM** provides pre-loaded test data consolidation via singleton pattern\n2. **Dynamic LTM** offers vector-based retrieval augmented memory for contextual queries\n3. **State Handler** enables runtime state sharing between agents through the `store_data` tool\n\nThis architecture ensures agents have access to both static test fixtures and dynamic execution context, enabling sophisticated AI-driven browser automation testing.\n\n---\n\n\n\n## API Testing\n\n### 相关页面\n\n相关主题：[Security Testing](#security-testing), [Tool System](#tool-system)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [testzeus_hercules/core/tools/api_calls.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/api_calls.py)\n- [testzeus_hercules/core/tools/sql_calls.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/sql_calls.py)\n- [testzeus_hercules/core/agents/api_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/api_nav_agent.py)\n- [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)\n- [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)\n- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)\n- [testzeus_hercules/utils/response_parser.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/response_parser.py)\n\n\n# API Testing\n\n## Overview\n\nAPI Testing in testzeus-hercules enables automated end-to-end testing of REST APIs through AI-driven agents. The system leverages LLM-powered agents to parse OpenAPI specifications, generate Gherkin test scenarios, execute API calls, and validate responses against expected outcomes. This module integrates with the broader Hercules testing framework to provide comprehensive API validation capabilities alongside browser-based UI testing.\n\nThe API Testing feature accepts OpenAPI specification files (YAML or JSON format) and automatically generates executable Gherkin test cases that can be run against live API endpoints. The generated tests follow behavior-driven development (BDD) conventions, making them readable for both technical and non-technical stakeholders.\n\n## Architecture\n\nThe API Testing module consists of several interconnected components that work together to provide end-to-end API testing capabilities.\n\n### Component Overview\n\n```mermaid\ngraph TD\n A[OpenAPI Specification] --> B[generate_api_functional_gherkin_test.py]\n B --> C[Gherkin Test Cases]\n C --> D[API Navigation Agent]\n D --> E[API Calls Tool]\n E --> F[SQL Calls Tool]\n E --> G[Python Sandbox Executor]\n F --> H[Database Validation]\n G --> I[Custom Logic Validation]\n D --> J[Response Parser]\n J --> K[Test Results]\n```\n\n### Core Components\n\n| Component | File Path | Purpose |\n|-----------|-----------|---------|\n| API Navigation Agent | `testzeus_hercules/core/agents/api_nav_agent.py` | Orchestrates API test execution using LLM-driven decision making |\n| API Calls Tool | `testzeus_hercules/core/tools/api_calls.py` | Executes HTTP requests to API endpoints |\n| SQL Calls Tool | `testzeus_hercules/core/tools/sql_calls.py` | Validates API data against database state |\n| Python Sandbox | `testzeus_hercules/core/tools/execute_python_sandbox.py` | Executes custom validation logic |\n| Gherkin Generator | `helper_scripts/generate_api_functional_gherkin_test.py` | Generates test cases from OpenAPI specs |\n| Response Parser | `testzeus_hercules/utils/response_parser.py` | Parses and validates API responses |\n\n资料来源：[helper_scripts/generate_api_functional_gherkin_test.py:1-80]()\n\n## Test Generation Workflow\n\n### OpenAPI Specification Processing\n\nThe test generation process begins with parsing OpenAPI specification files. The system accepts both YAML and JSON formatted OpenAPI specs through the `generate_api_functional_gherkin_test.py` helper script.\n\n```python\nparser.add_argument(\n \"input_files\",\n metavar=\"input_files\",\n type=str,\n nargs=\"+\",\n help=\"One or more OpenAPI spec files (YAML or JSON).\",\n)\n```\n\n资料来源：[helper_scripts/generate_api_functional_gherkin_test.py:15-22]()\n\n### Gherkin Test Case Generation\n\nThe LLM generates test cases based on the OpenAPI specification content. The generation uses a specialized prompt that instructs the model to produce Gherkin-format scenarios covering functional test cases.\n\n```python\ndef generate_test_cases(prompt: str, model: str) -> str:\n \"\"\"Generates test cases using the OpenAI API.\"\"\"\n client = OpenAI()\n completion = client.chat.completions.create(\n model=model,\n messages=[{\"role\": \"user\", \"content\": prompt}],\n temperature=0.7,\n )\n return completion.choices[0].message.content\n```\n\n资料来源：[helper_scripts/generate_api_functional_gherkin_test.py:82-90]()\n\n### Generation Parameters\n\n| Parameter | CLI Flag | Default | Description |\n|-----------|----------|---------|-------------|\n| Model | `--model` | o1-preview | LLM model for test generation |\n| Output Folder | `--output` | (required) | Destination for generated feature files |\n| Number of Test Cases | `--number_of_testcase` | 100 | Maximum test cases to generate per endpoint |\n\n## API Navigation Agent\n\nThe API Navigation Agent (`api_nav_agent.py`) serves as the orchestrator for executing API tests. It receives parsed test scenarios and coordinates execution across multiple tools to validate API behavior.\n\n```mermaid\nsequenceDiagram\n participant Test as Test Scenario\n participant Agent as API Nav Agent\n participant API as API Calls Tool\n participant SQL as SQL Calls Tool\n participant Sandbox as Python Sandbox\n \n Test->>Agent: Execute scenario\n Agent->>API: Send HTTP request\n API-->>Agent: Response data\n Agent->>SQL: Validate database state\n SQL-->>Agent: Validation result\n Agent->>Sandbox: Run custom assertions\n Sandbox-->>Agent: Assertion results\n Agent->>Test: Pass/Fail outcome\n```\n\n资料来源：[testzeus_hercules/core/agents/api_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/api_nav_agent.py)\n\n## Execution Environment\n\n### Python Sandbox\n\nAPI tests execute within a secured Python sandbox environment that provides controlled access to necessary resources while maintaining isolation.\n\n```python\ndef _get_config_driven_injections(config: Any) -> Dict[str, Any]:\n \"\"\"\n Get injections defined in configuration.\n Allows dynamic configuration of available modules.\n \"\"\"\n injections = {}\n \n # Read from config: SANDBOX_PACKAGES=\"requests,pandas,numpy\"\n sandbox_packages = config.get_config().get(\"SANDBOX_PACKAGES\", \"\").split(\",\")\n \n for package_name in sandbox_packages:\n package_name = package_name.strip()\n if package_name:\n try:\n injections[package_name] = __import__(package_name)\n except ImportError:\n logger.warning(f\"Could not import configured package: {package_name}\")\n \n return injections\n```\n\n资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py:80-100]()\n\n### Sandbox Access Variables\n\nScripts executing within the sandbox have automatic access to the following variables:\n\n| Variable | Type | Description |\n|----------|------|-------------|\n| `page` | Playwright Page | Current browser page context |\n| `browser` | Browser instance | Active browser session |\n| `context` | Browser Context | Isolated browsing context |\n| `playwright_manager` | PlaywrightManager | Manages Playwright lifecycle |\n| `logger` | Logger | Logging utility |\n| `config` | Configuration | Global configuration object |\n\nAdditional tenant-specific modules can be injected based on the `SANDBOX_TENANT_ID` environment variable, and custom injections are available via the `SANDBOX_CUSTOM_INJECTIONS` environment variable.\n\n资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py:40-55]()\n\n## Response Handling\n\n### JSON Response Parsing\n\nThe response parser handles API responses with multiple fallback strategies for extracting structured data:\n\n```python\ndef parse_response(message: str) -> dict[str, Any]:\n # Check if message is wrapped in ```json ``` blocks\n if \"```json\" in message:\n start_idx = message.find(\"```json\") + 7\n end_idx = message.find(\"```\", start_idx + 7)\n message = message[start_idx:end_idx]\n else:\n if message.startswith(\"```\"):\n message = message[3:]\n if message.endswith(\"```):\n message = message[:-3]\n if message.startswith(\"json\"):\n message = message[4:]\n\n message = message.strip()\n message = message.replace(\"\\\\n\", \"\\n\")\n \n json_response: dict[str, Any] = json.loads(message)\n```\n\n资料来源：[testzeus_hercules/utils/response_parser.py:9-35]()\n\n### Error Recovery\n\nWhen JSON parsing fails, the response parser attempts to extract plan and next_step fields from unstructured responses, ensuring graceful degradation when APIs return non-standard response formats.\n\n## Configuration\n\n### LLM Configuration\n\nAPI Testing relies on LLM configuration for test generation and agent decision-making. Configuration can be provided via command-line arguments or through a dedicated configuration file.\n\n```python\nparser.add_argument(\n \"--llm-model\",\n type=str,\n help=\"Name of the LLM model.\",\n required=False,\n)\nparser.add_argument(\n \"--llm-temperature\",\n type=float,\n help=\"Temperature for LLM sampling (0.0-1.0).\",\n required=False,\n)\n```\n\n资料来源：[testzeus_hercules/config.py:35-45]()\n\n### Agents LLM Config File\n\nFor multi-agent configurations, specify the configuration file path:\n\n```bash\n--agents-llm-config-file /path/to/agents_llm_config.json\n--agents-llm-config-file-ref-key \n```\n\n### Portkey Integration\n\nEnable Portkey for LLM routing with fallback or load balancing strategies:\n\n```bash\n--enable-portkey\n--portkey-api-key \n--portkey-strategy fallback|loadbalance\n```\n\n资料来源：[testzeus_hercules/config.py:60-75]()\n\n## Usage Examples\n\n### Generate Gherkin Tests from OpenAPI Spec\n\n```bash\npython helper_scripts/generate_api_functional_gherkin_test.py \\\n spec/openapi.yaml \\\n --output tests/api/ \\\n --model gpt-4 \\\n --number_of_testcase 50\n```\n\n### Run API Tests\n\nTests can be executed through the main Hercules CLI or integrated into CI/CD pipelines. The agent configuration file supports specifying different models for different agents:\n\n```json\n{\n \"openai\": {\n \"planner_agent\": {\n \"model_name\": \"gpt-4\",\n \"model_api_type\": \"openai\"\n }\n }\n}\n```\n\n资料来源：[agents_llm_config-example.json](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/agents_llm_config-example.json)\n\n## Integration with Browser Testing\n\nThe API Testing module integrates seamlessly with browser-based testing capabilities. The API Navigation Agent can coordinate with the Browser Navigation Agent to perform scenarios that span both API validation and UI verification.\n\nWhen executing multi-step workflows, the system can:\n1. Call API endpoints to set up test data\n2. Launch browsers to verify UI state reflects API changes\n3. Execute SQL queries to validate data persistence\n4. Run custom Python assertions for complex business logic\n\n## Security Considerations\n\n### API Key Management\n\nAPI keys should be provided through environment variables or secure configuration management, never hardcoded in test files:\n\n```bash\nexport OPENAI_API_KEY=\nexport PORTKEY_API_KEY=\n```\n\n### Sandbox Isolation\n\nThe Python sandbox provides execution isolation for custom test logic. Configure allowed packages through the `SANDBOX_PACKAGES` configuration parameter to limit access to only required libraries.\n\n## Best Practices\n\n1. **Organize OpenAPI specs by version** - Maintain separate specification files for different API versions\n2. **Use meaningful test case names** - Generated tests should clearly describe the scenario being validated\n3. **Combine with database validation** - Use SQL Calls Tool to verify data consistency\n4. **Leverage response parsing** - Use the response parser for handling complex API response formats\n5. **Configure appropriate LLM models** - Use faster models for generation and more capable models for complex validation logic\n\n## Related Documentation\n\n- [CONTRIBUTING.md](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/CONTRIBUTING.md) - Contribution guidelines for the project\n- [Makefile](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/Makefile) - Build and test automation targets\n- [Browser Testing](https://github.com/test-zeus-ai/testzeus-hercules) - Companion documentation for UI testing\n\n---\n\n\n\n## Security Testing\n\n### 相关页面\n\n相关主题：[API Testing](#api-testing), [Tool System](#tool-system)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [testzeus_hercules/core/agents/sec_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/sec_nav_agent.py)\n- [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)\n\n\n# Security Testing\n\nSecurity Testing in TestZeus Hercules is an automated framework designed to validate API security by generating and executing Gherkin-based test scenarios. The system leverages LLM-powered agents to analyze OpenAPI specifications and produce comprehensive security validation tests that check for vulnerabilities, configuration weaknesses, and proper handling of sensitive data.\n\n## Overview\n\nThe Security Testing module provides an end-to-end solution for validating API security without requiring manual test case authoring. It integrates with the broader Hercules testing framework to execute security validation scenarios alongside functional and navigation tests.\n\n### Core Components\n\n| Component | File Path | Purpose |\n|-----------|-----------|---------|\n| Security Navigation Agent | `testzeus_hercules/core/agents/sec_nav_agent.py` | Orchestrates security test execution using LLM-driven agents |\n| API Security Calls | `testzeus_hercules/core/tools/api_sec_calls.py` | Provides low-level HTTP client operations for security validation |\n| Gherkin Test Generator | `helper_scripts/generate_api_security_gherkin_test.py` | Generates security-focused Gherkin test cases from OpenAPI specs |\n\n## Architecture\n\n```mermaid\ngraph TD\n A[OpenAPI Spec Files] --> B[generate_api_security_gherkin_test.py]\n B --> C[LLM API - OpenAI]\n C --> D[Security Gherkin Test Cases]\n D --> E[Hercules Test Executor]\n E --> F[sec_nav_agent.py]\n F --> G[api_sec_calls.py]\n G --> H[Target API Endpoints]\n H --> I[Security Validation Results]\n \n J[Configuration] --> F\n K[LLM Config] --> B\n```\n\n## Security Navigation Agent\n\nThe `sec_nav_agent.py` module implements the `BrowserNavAgent` pattern specialized for security testing scenarios. It follows the same agent architecture used by the browser navigation agent but focuses on API security validation.\n\n### Agent Configuration\n\nThe security agent inherits the core agent configuration structure from the Hercules framework, utilizing the same LLM integration patterns as the main navigation agent defined in `simple_hercules.py`. 资料来源：[testzeus_hercules/core/agents/sec_nav_agent.py:1-50]()\n\n### Execution Flow\n\n```mermaid\nsequenceDiagram\n participant TestRunner\n participant SecNavAgent\n participant APISecCalls\n participant TargetAPI\n participant ResponseParser\n \n TestRunner->>SecNavAgent: Execute security test scenario\n SecNavAgent->>APISecCalls: Send HTTP request with security payload\n APISecCalls->>TargetAPI: Validated HTTP request\n TargetAPI->>APISecCalls: Response with headers/body\n APISecCalls->>ResponseParser: Parse response data\n ResponseParser->>SecNavAgent: Structured security results\n SecNavAgent->>TestRunner: Security validation report\n```\n\n## API Security Calls Module\n\nThe `api_sec_calls.py` module provides the foundational HTTP client capabilities for executing security tests. It supports various HTTP methods and authentication schemes required for comprehensive API security testing.\n\n### Supported Security Test Operations\n\n| Operation | Description | Authentication Support |\n|-----------|-------------|----------------------|\n| GET Security Headers | Validate presence and correctness of security headers | Bearer, API Key, Basic |\n| POST Injection Tests | Execute payload injection for XSS, SQLi validation | Bearer, API Key |\n| Authentication Bypass | Test unauthorized access to protected endpoints | Token validation |\n| Rate Limiting | Verify rate limiting mechanisms | None required |\n| CORS Validation | Check cross-origin resource sharing policies | None required |\n\n资料来源：[testzeus_hercules/core/tools/api_sec_calls.py:1-100]()\n\n### Request Configuration\n\n```python\n# Security test request structure\n{\n \"method\": \"GET|POST|PUT|DELETE|PATCH\",\n \"url\": \"https://api.target.com/endpoint\",\n \"headers\": {\n \"Authorization\": \"Bearer {token}\",\n \"Content-Type\": \"application/json\"\n },\n \"params\": {}, # Query parameters\n \"data\": {}, # Request body for POST/PUT/PATCH\n \"timeout\": 30,\n \"verify_ssl\": true\n}\n```\n\n## Gherkin Test Generation\n\nThe `generate_api_security_gherkin_test.py` helper script uses LLM to automatically generate security-focused Gherkin test cases from OpenAPI specification files.\n\n### Input Processing\n\nThe generator accepts OpenAPI specifications in both YAML and JSON formats, parsing the specification to identify:\n\n- Endpoints and their HTTP methods\n- Security schemes defined in the spec\n- Request/response schemas\n- Authentication requirements\n\n资料来源：[helper_scripts/generate_api_security_gherkin_test.py:1-60]()\n\n### Generation Prompt Strategy\n\nThe LLM prompt instructs the model to focus on generating tests that validate:\n\n1. **Vulnerability Detection**: Tests that check for common vulnerabilities\n2. **Configuration Weaknesses**: Validation of security configurations\n3. **Sensitive Data Handling**: Verification of proper data protection\n4. **Authentication/Authorization**: Access control testing\n5. **Input Validation**: Sanitization and validation checks\n\n### Output Format\n\nGenerated test cases follow this structure:\n\n```gherkin\nFeature: API Security Validation - {Endpoint_Name}\n Scenario: Validate security headers on {method} {path}\n Given the API endpoint \"{path}\" requires authentication\n When I send a {method} request without authorization\n Then the response should have status code 401\n And the response should include \"WWW-Authenticate\" header\n \n Scenario: Test for SQL injection vulnerability on {path}\n Given the API endpoint \"{path}\" accepts query parameters\n When I send a GET request with malicious payload in parameter \"id\"\n Then the response should have status code 400 or 422\n And no SQL error should be present in response body\n```\n\n资料来源：[helper_scripts/generate_api_security_gherkin_test.py:80-120]()\n\n## Command Line Interface\n\n### Running Security Tests\n\n```bash\n# Generate security tests from OpenAPI spec\npython -m helper_scripts.generate_api_security_gherkin_test \\\n --input spec.yaml \\\n --output ./tests/security \\\n --model gpt-4o \\\n --number_of_testcase 50\n\n# Execute security tests with Hercules\ntestzeus-hercules --input-file ./tests/security/api_security.feature\n```\n\n### Generation Script Arguments\n\n| Argument | Type | Default | Description |\n|----------|------|---------|-------------|\n| `input_files` | list[str] | required | One or more OpenAPI spec files (YAML or JSON) |\n| `--output` | str | required | Output folder for generated feature files |\n| `--model` | str | o1-preview | OpenAI model for test generation |\n| `--number_of_testcase` | int | 100 | Number of test cases to generate |\n\n资料来源：[helper_scripts/generate_api_security_gherkin_test.py:30-55]()\n\n## Integration with Hercules Framework\n\n### Agent Initialization\n\nThe security agent is initialized through the same mechanism as other Hercules agents, using configuration from the LLM configuration file specified via CLI:\n\n```bash\ntestzeus-hercules \\\n --input-file security_tests.feature \\\n --agents-llm-config-file ./config/security_agent.yaml \\\n --llm-model gpt-4o\n```\n\n### Execution Context\n\nSecurity tests execute within the same context as functional tests, providing:\n\n- Shared browser/playwright session management\n- Consistent logging and telemetry\n- Unified reporting and result aggregation\n- Access to shared utilities and helpers\n\n## Security Test Scenarios\n\n### Common Test Categories\n\n| Category | Test Focus | Example Validation |\n|----------|------------|-------------------|\n| Authentication | Token validation, session management | Invalid token returns 401 |\n| Authorization | Access control, privilege escalation | User cannot access admin endpoints |\n| Input Validation | Payload sanitization, type checking | Malformed input returns 400 |\n| Headers | Security header presence | X-Frame-Options, CSP headers present |\n| Rate Limiting | Request throttling | Excessive requests return 429 |\n| CORS | Cross-origin policy | Invalid origins rejected |\n\n## Best Practices\n\n### Test Data Management\n\n- Use dedicated security test environments\n- Isolate security tests from production data\n- Implement proper cleanup for test artifacts\n- Rotate API keys/tokens used in tests\n\n### Test Coverage\n\n- Aim for comprehensive endpoint coverage\n- Include both positive and negative test cases\n- Validate all security headers defined in your policy\n- Test authentication bypass scenarios\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `OPENAI_API_KEY` | Required for LLM-powered test generation |\n| `SECURITY_TEST_API_KEY` | API key for testing authenticated endpoints |\n| `SECURITY_TEST_BASE_URL` | Override target API base URL |\n\n### LLM Configuration\n\nThe security agent uses the same LLM configuration structure as other agents, specified through:\n\n```yaml\n# security_agent_config.yaml\nllm_config:\n model: gpt-4o\n temperature: 0.7\n max_tokens: 4096\n\nother_settings:\n system_prompt: \"You are a security testing expert...\"\n max_consecutive_auto_reply: 10\n```\n\n## Reporting\n\nSecurity test results are integrated into the standard Hercules reporting format:\n\n- Test pass/fail status per scenario\n- Detailed assertion results\n- HTTP request/response logging\n- Security-specific metrics (headers present, vulnerabilities detected)\n\n## Related Documentation\n\n- [Browser Navigation Agent](testzeus_hercules/core/agents/executor_nav_agent.py) - Core navigation patterns\n- [Simple Hercules](testzeus_hercules/core/simple_hercules.py) - Main framework architecture\n- [API Functional Testing](helper_scripts/generate_api_functional_gherkin_test.py) - Functional test generation\n\n---\n\n\n\n## MCP Integration\n\n### 相关页面\n\n相关主题：[Agent System](#agent-system), [Tool System](#tool-system)\n\n\nRelated Source Files\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [testzeus_hercules/core/tools/mcp_tools.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/mcp_tools.py)\n- [testzeus_hercules/utils/mcp_helper.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/mcp_helper.py)\n- [mcp_servers.example.json](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/mcp_servers.example.json)\n- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)\n\n\n# MCP Integration\n\n## Overview\n\nThe MCP (Model Context Protocol) Integration in TestZeus Hercules enables the testing agent to discover, catalog, and execute tools exposed by external MCP servers. This integration allows Hercules to extend its capabilities by leveraging tools from multiple Model Context Protocol-compliant servers during end-to-end testing workflows.\n\nMCP serves as a standardized communication layer that allows the testing framework to:\n\n- Enumerate and connect to configured MCP servers\n- List available tools and resource namespaces from each connected server\n- Execute remote tool calls with correct parameters\n- Retrieve resources by URI when required for test execution\n\n资料来源：[testzeus_hercules/core/agents/mcp_nav_agent.py:1-10]()\n\n## Architecture\n\n### System Components\n\nThe MCP integration is built on three primary components:\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| McpNavAgent | `core/agents/mcp_nav_agent.py` | Main navigation agent that orchestrates MCP server interactions |\n| MCPHelper | `utils/mcp_helper.py` | Utility class providing MCP client functionality |\n| MCP Tools | `core/tools/mcp_tools.py` | Tool implementations for MCP operations |\n\n### Component Relationship\n\n```mermaid\ngraph TD\n A[TestZeus Hercules Core] --> B[McpNavAgent]\n B --> C[MCPHelper]\n C --> D[MCP Servers]\n \n B --> E[get_configured_mcp_servers]\n B --> F[check_mcp_server_connection]\n B --> G[execute_mcp_tool]\n B --> H[read_mcp_resource]\n \n E --> I[Server Discovery]\n F --> J[Connection Status]\n G --> K[Tool Execution]\n H --> L[Resource Retrieval]\n```\n\n## McpNavAgent\n\nThe `McpNavAgent` is the central agent responsible for all MCP-related operations. It inherits from `BaseNavAgent` and implements the Model Context Protocol interaction patterns.\n\n资料来源：[testzeus_hercules/core/agents/mcp_nav_agent.py:6-9]()\n\n### Agent Configuration\n\n| Property | Value | Description |\n|----------|-------|-------------|\n| `agent_name` | `mcp_nav_agent` | Unique identifier for the agent |\n| Inherits | `BaseNavAgent` | Base navigation agent functionality |\n\n### Core Functions\n\nThe MCP Navigation Agent implements the following core functions:\n\n1. **Server Discovery** - Enumerate configured MCP servers and their connection status\n2. **Capability Cataloging** - List tools and resource namespaces for each connected server\n3. **Tool Execution** - Call tools with correct parameters and handle responses\n4. **Resource Retrieval** - Read resources by URI when required\n5. **Result Summarization** - Capture server, tool, arguments, outputs; include timings and status\n\n资料来源：[testzeus_hercules/core/agents/mcp_nav_agent.py:14-28]()\n\n### Operational Rules\n\n#### Rule 1: Previous Step Validation\n\nBefore any new action, explicitly review the previous step and its outcome. Do not proceed if the prior critical step failed; address it first.\n\n```mermaid\ngraph TD\n A[Execute Action] --> B{Previous Step Succeeded?}\n B -->|No| C[Address Failure First]\n B -->|Yes| D[Continue to Next Action]\n C --> D\n```\n\n#### Rule 2: Server Scan First\n\nThe agent must call `get_configured_mcp_servers` and for each server, call `check_mcp_server_connection` before taking any other action.\n\n资料来源：[testzeus_hercules/core/agents/mcp_nav_agent.py:31-35]()\n\n### Agent Prompt\n\nThe agent uses a specialized system prompt that defines its role and behavioral guidelines:\n\n```\n### MCP Navigation Agent\n\nYou are an MCP (Model Context Protocol) Navigation Agent that assists the Testing Agent by discovering MCP servers, cataloging their exposed tools/resources, and executing the right tool calls to complete the task. Always begin by scanning all configured servers before taking any action.\n```\n\n资料来源：[testzeus_hercules/core/agents/mcp_nav_agent.py:11-21]()\n\n## MCPHelper Utility\n\nThe `MCPHelper` class provides the underlying functionality for MCP server interactions. It is exported through the `mcp_helper.py` module and integrates with the agent system through `set_mcp_agents`.\n\n资料来源：[testzeus_hercules/utils/mcp_helper.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/mcp_helper.py)\n\n### Key Functions\n\n| Function | Purpose |\n|----------|---------|\n| `MCPHelper` | Main helper class for MCP operations |\n| `set_mcp_agents` | Configures MCP agents within the testing framework |\n\n## Configuration\n\n### Configuration File Format\n\nMCP servers are configured using a JSON file. The example file `mcp_servers.example.json` demonstrates the expected format:\n\n```json\n{\n \"mcpServers\": {\n \"server_name\": {\n \"command\": \"command_to_run\",\n \"args\": [\"arg1\", \"arg2\"],\n \"env\": {\n \"KEY\": \"value\"\n }\n }\n }\n}\n```\n\n### Command Line Arguments\n\nThe MCP integration can be configured through command line arguments:\n\n| Argument | Type | Description |\n|----------|------|-------------|\n| `--agents-llm-config-file` | string | Path to the agents LLM configuration file |\n| `--agents-llm-config-file-ref-key` | string | Reference key for the agents LLM configuration file |\n\n资料来源：[testzeus_hercules/config.py:27-39]()\n\n## Workflow\n\n### Standard MCP Interaction Flow\n\n```mermaid\ngraph TD\n A[Start Test Execution] --> B[Initialize McpNavAgent]\n B --> C[Call get_configured_mcp_servers]\n C --> D[For Each Server]\n D --> E[Call check_mcp_server_connection]\n E --> F{Server Connected?}\n F -->|No| G[Log Error / Skip Server]\n F -->|Yes| H[Catalog Tools & Resources]\n H --> I[Task Requires MCP Tool?]\n I -->|Yes| J[Call execute_mcp_tool]\n I -->|No| K[Continue with Other Tasks]\n J --> L[Process Tool Response]\n L --> M[Return Results to Testing Agent]\n G --> D\n K --> N[Complete Test]\n M --> N\n```\n\n### Tool Execution Workflow\n\nWhen executing MCP tools, the agent follows this sequence:\n\n1. Identify the target MCP server\n2. Verify server connection status\n3. Determine the correct tool and parameters\n4. Execute the tool call via MCP protocol\n5. Capture response including timing and status\n6. Return formatted results to the testing agent\n\n## Integration with Testing Framework\n\n### Agent Hierarchy\n\n```mermaid\ngraph BT\n A[BrowserNavAgent] --> B[BaseNavAgent]\n C[ApiNavAgent] --> B\n D[SqlNavAgent] --> B\n E[McpNavAgent] --> B\n F[SecNavAgent] --> B\n \n B --> G[TestZeus Hercules Core]\n```\n\nAll navigation agents, including `McpNavAgent`, inherit from `BaseNavAgent`, ensuring consistent behavior and integration with the core testing framework.\n\n资料来源：[testzeus_hercules/core/agents/__init__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/__init__.py)\n\n### Available Navigation Agents\n\n| Agent | Purpose |\n|-------|---------|\n| `BrowserNavAgent` | Web browser interaction and navigation |\n| `ApiNavAgent` | API testing and validation |\n| `SqlNavAgent` | Database query execution |\n| `McpNavAgent` | MCP server tool execution |\n| `SecNavAgent` | Security testing operations |\n\n## Best Practices\n\n### Initialization\n\n1. Always ensure MCP servers are properly configured before test execution\n2. Verify server connectivity before attempting tool calls\n3. Use the configured servers list as the authoritative source of available MCP servers\n\n### Error Handling\n\n1. Check previous step outcomes before proceeding\n2. Log connection failures with server identification\n3. Handle tool execution errors with proper parameter validation\n4. Provide clear error messages when MCP operations fail\n\n### Task Focus\n\n- Execute only actions required by the primary testing task\n- Use extra information from MCP responses cautiously\n- Avoid unnecessary server scans after initial discovery\n\n## Security Considerations\n\nThe MCP integration supports sensitive operations requiring careful configuration:\n\n- API keys should be provided through secure environment variables\n- Server configurations should be validated before use\n- Tool execution permissions should be properly scoped\n- Resource access should follow least-privilege principles\n\n## Summary\n\nThe MCP Integration module provides TestZeus Hercules with the ability to extend its testing capabilities through external MCP servers. By implementing a dedicated `McpNavAgent` that follows standardized MCP protocols, the framework can seamlessly discover servers, catalog their capabilities, and execute tools as needed during end-to-end testing scenarios.\n\nKey benefits include:\n\n- **Extensibility**: Add new testing capabilities without modifying core framework code\n- **Standardization**: Uses the Model Context Protocol for consistent server communication\n- **Resource Management**: Access remote resources via standardized URI-based retrieval\n- **Comprehensive Logging**: Captures server status, tool execution times, and results\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：test-zeus-ai/testzeus-hercules\n\n摘要：发现 13 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 来源证据：0.1.1。\n\n## 1. 配置坑 · 来源证据：0.1.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：0.1.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_87e563b6a81f4a529799ac528ee21610 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 来源证据：0.0.40\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.0.40\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_02c1945d063b4151a3df1526b85e9d50 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.0.40 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 维护坑 · 来源证据：0.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1d1eb9ae89f04ff9b339c73cc932f2f7 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 维护坑 · 来源证据：0.1.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e0e02b07ea6845eaac8c4f18871aaa32 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 维护坑 · 来源证据：0.1.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.6\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_41cf6e34c47b4f929a67426b258b8fd8 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.6 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | last_activity_observed missing\n\n## 8. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | no_demo; severity=medium\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 来源证据：0.1.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.1.4\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d6aeb053b3a541778b07c0bca68c5c82 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 安全/权限坑 · 来源证据：0.2.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.2.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_963ec16ebc32452a8ca13e8ebc1aed96 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.2.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | issue_or_pr_quality=unknown\n\n## 13. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | release_recency=unknown\n\n\n",
"markdown_key": "testzeus-hercules",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:888701643",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/test-zeus-ai/testzeus-hercules"
},
{
"evidence_id": "art_0861c6b28570423d9149e75334232a7a",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/test-zeus-ai/testzeus-hercules#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "testzeus-hercules 说明书",
"toc": [
"https://github.com/test-zeus-ai/testzeus-hercules 项目说明书",
"目录",
"Getting Started with TestZeus Hercules",
"Overview",
"Architecture",
"Installation",
"Command-Line Interface",
"Running TestZeus Hercules",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "e8bf322a1cd894b1b7b18b4d3c44a4767788363a",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"Dockerfile",
"README.md",
"uv.lock",
"docs/GPT5_USAGE.md",
"docs/run_guide.md",
"docs/python_sandbox_execution.md",
"docs/sandbox_quick_reference.md",
"docs/environment_variables.md",
"docs/MCP_Usage.md"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# testzeus-hercules - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 testzeus-hercules 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install testzeus-hercules` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `git clone git@github.com:test-zeus-ai/testzeus-hercules.git` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install --upgrade testzeus-hercules` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `curl -sS https://raw.githubusercontent.com/test-zeus-ai/testzeus-hercules/main/agents_llm_config-example.json > agents_llm_config-example.json` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `curl -sS https://raw.githubusercontent.com/test-zeus-ai/testzeus-hercules/main/.env-example > .env-example` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `curl -sS https://raw.githubusercontent.com/test-zeus-ai/testzeus-hercules/main/opt/input/test.feature > opt/input/test.feature` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `curl -sS https://raw.githubusercontent.com/test-zeus-ai/testzeus-hercules/main/opt/test_data/test_data.json > opt/test_data/test_data.json` 证据：`README.md` Claim：`clm_0009` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、环境变量 / API Key\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `docs/environment_variables.md`, `docs/run_guide.md`, `entrypoint.sh` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0010` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0011` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：196\n- 重要文件覆盖：40/196\n- 证据索引条目：49\n- 角色 / Skill 条目：14\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 testzeus-hercules 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 testzeus-hercules 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 testzeus-hercules 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 14 个角色 / Skill / 项目文档条目。\n\n- **💪 Hercules**（project_doc）：! PyPI Total Downloads https://static.pepy.tech/badge/testzeus-hercules https://pepy.tech/projects/testzeus-hercules ! Docker Pulls https://img.shields.io/docker/pulls/testzeus/hercules ! CI Test https://github.com/test-zeus-ai/testzeus-hercules/actions/workflows/main-test.yml/badge.svg https://github.com/test-zeus-ai/testzeus-hercules/actions/workflows/main-test.yml ! Slack https://img.shields.io/badge/slack-TestZe… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **FastAPI SQLite Demo with Extended Entities and Authentication**（project_doc）：Below is an example README.md for the project: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`tests/api_testing_app/Readme.md`\n- **How to contribute to this project**（project_doc）：Hercules is a project from the community and for the community. So we welcome all kinds of contributions: - Technical contributions: Review the instructions below and feel free to open a PR. - Want to start small? No problem. Contribute to documentation, build a tool, recreate a bug. We all started in one of these places. - Organize a local meetup, talk to people, or answer a question: The power lies in your hands. 💪 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **GPT-5 Support in Hercules**（project_doc）：This document explains how to use GPT-5 models gpt-5, gpt-5-mini, gpt-5-nano with the Hercules framework. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/GPT5_USAGE.md`\n- **Using MCP with Hercules**（project_doc）：This guide explains how to connect Hercules to an MCP server and execute tools, with Composio as a ready-to-use provider. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/MCP_Usage.md`\n- **Environment Variables and Configuration Guide**（project_doc）：Environment Variables and Configuration Guide 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/environment_variables.md`\n- **Python Sandbox Execution Feature**（project_doc）：Hercules now supports executing custom Python scripts directly from your Gherkin test cases through the Python Sandbox Execution feature. This powerful capability allows you to run complex automation workflows, custom business logic, and multi-step operations with full Playwright browser access—all from simple Gherkin steps. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/python_sandbox_execution.md`\n- **TestZeus Hercules Project Structure Guide**（project_doc）：TestZeus Hercules Project Structure Guide 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/run_guide.md`\n- **Python Sandbox - Quick Reference**（project_doc）：python async def my function param1: str, param2: int - dict: \"\"\"Your automation logic.\"\"\" page, logger, asyncio automatically available! await page.goto \"https://example.com\" 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/sandbox_quick_reference.md`\n- **Summary :memo:**（project_doc）：Summary :memo: Write an overview about it. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Code of conduct**（project_doc）：Hercules is a powerful tool, but the strength of the Hercules community lies in the people who build, use, and support it. We’re committed to maintaining a friendly, safe, and welcoming environment for all, regardless of gender, gender identity and expression, sexual orientation, ability, appearance, body size, race, age, socioeconomic status, religion or lack thereof , or any other aspect of identity. We expect all… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CodeofConduct.md`\n- **History**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`HISTORY.md`\n- **Bug report**（project_doc）：Describe the bug A clear and concise description of what the bug is. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Feature request**（project_doc）：Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is. Ex. I'm always frustrated when ... 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n\n## 证据索引\n\n- 共索引 49 条证据。\n\n- **💪 Hercules**（documentation）：! PyPI Total Downloads https://static.pepy.tech/badge/testzeus-hercules https://pepy.tech/projects/testzeus-hercules ! Docker Pulls https://img.shields.io/docker/pulls/testzeus/hercules ! CI Test https://github.com/test-zeus-ai/testzeus-hercules/actions/workflows/main-test.yml/badge.svg https://github.com/test-zeus-ai/testzeus-hercules/actions/workflows/main-test.yml ! Slack https://img.shields.io/badge/slack-TestZeus-brightgreen.svg?logo=slack https://join.slack.com/t/testzeuscommunityhq/shared invite/zt-376oeo99x-3RAWe C0H7x9zP0rtACcPA 证据：`README.md`\n- **FastAPI SQLite Demo with Extended Entities and Authentication**（documentation）：Below is an example README.md for the project: 证据：`tests/api_testing_app/Readme.md`\n- **How to contribute to this project**（documentation）：Hercules is a project from the community and for the community. So we welcome all kinds of contributions: - Technical contributions: Review the instructions below and feel free to open a PR. - Want to start small? No problem. Contribute to documentation, build a tool, recreate a bug. We all started in one of these places. - Organize a local meetup, talk to people, or answer a question: The power lies in your hands. 💪 证据：`CONTRIBUTING.md`\n- **License**（source_file）：GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 证据：`LICENSE`\n- **GPT-5 Support in Hercules**（documentation）：This document explains how to use GPT-5 models gpt-5, gpt-5-mini, gpt-5-nano with the Hercules framework. 证据：`docs/GPT5_USAGE.md`\n- **Using MCP with Hercules**（documentation）：This guide explains how to connect Hercules to an MCP server and execute tools, with Composio as a ready-to-use provider. 证据：`docs/MCP_Usage.md`\n- **Environment Variables and Configuration Guide**（documentation）：Environment Variables and Configuration Guide 证据：`docs/environment_variables.md`\n- **Python Sandbox Execution Feature**（documentation）：Hercules now supports executing custom Python scripts directly from your Gherkin test cases through the Python Sandbox Execution feature. This powerful capability allows you to run complex automation workflows, custom business logic, and multi-step operations with full Playwright browser access—all from simple Gherkin steps. 证据：`docs/python_sandbox_execution.md`\n- **TestZeus Hercules Project Structure Guide**（documentation）：TestZeus Hercules Project Structure Guide 证据：`docs/run_guide.md`\n- **Python Sandbox - Quick Reference**（documentation）：python async def my function param1: str, param2: int - dict: \"\"\"Your automation logic.\"\"\" page, logger, asyncio automatically available! await page.goto \"https://example.com\" 证据：`docs/sandbox_quick_reference.md`\n- **Summary :memo:**（documentation）：Summary :memo: Write an overview about it. 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Code of conduct**（documentation）：Hercules is a powerful tool, but the strength of the Hercules community lies in the people who build, use, and support it. We’re committed to maintaining a friendly, safe, and welcoming environment for all, regardless of gender, gender identity and expression, sexual orientation, ability, appearance, body size, race, age, socioeconomic status, religion or lack thereof , or any other aspect of identity. We expect all members of the Hercules community to follow this Code of Conduct whenever interacting within Hercules venues e.g., GitHub pull requests, issues, chat rooms, forums, conferences, etc. . 证据：`CodeofConduct.md`\n- **History**（documentation）：Changelog ========= 证据：`HISTORY.md`\n- **Bug Report**（documentation）：Describe the bug A clear and concise description of what the bug is. 证据：`.github/ISSUE_TEMPLATE/bug_report.md`\n- **Feature Request**（documentation）：Is your feature request related to a problem? Please describe. A clear and concise description of what the problem is. Ex. I'm always frustrated when ... 证据：`.github/ISSUE_TEMPLATE/feature_request.md`\n- **Agents Llm Config Example**（structured_config）：{ \"mistral\": { \"planner agent\": { \"model name\": \"ministral-8b-latest\", \"model api key\": \"\", \"model base url\": \"https://api.mistral.ai/v1\", \"model api type\": \"mistral\", \"llm config params\": { \"cache seed\": null, \"temperature\": 0.0, 证据：`agents_llm_config-example.json`\n- **Mcp Servers.Example**（structured_config）：{ \"mcpServers\": { \"server name\":{ \"transport\": \"streamable-http\", \"url\": \"https://mcp.composio.dev/composio/server/ /mcp?user id=user123@example.com\" } } } 证据：`mcp_servers.example.json`\n- **Unit test / coverage reports**（source_file）：pycache .pyc .pyo .pyd .Python .env venv .venv .env build dist .log /tmp /temp /log files /screen shots /opt /output /gherkin files /cache /.DS Store / .feature / .xml 证据：`.dockerignore`\n- **For GPT-5 models, use max completion tokens instead of max tokens**（source_file）：LLM MODEL NAME=PUT YOUR MODEL NAME HERE, for example: gpt-4o, gpt-5, gpt-5-mini, gpt-5-nano LLM MODEL API KEY=PUT YOUR MODEL API KEY HERE 证据：`.env-example`\n- **Dependabot**（source_file）：version: 2 updates: - package-ecosystem: \"github-actions\" directory: \"/\" schedule: interval: \"weekly\" - package-ecosystem: \"pip\" directory: \"/\" schedule: interval: \"weekly\" 证据：`.github/dependabot.yml`\n- **!/usr/bin/env bash**（source_file）：!/usr/bin/env bash overwrite template dir=0 证据：`.github/init.sh`\n- **!/usr/bin/env bash**（source_file）：!/usr/bin/env bash previous tag=$ git tag --sort=-creatordate sed -n 2p git shortlog \"${previous tag}..\" sed 's/^./ &/' 证据：`.github/release_message.sh`\n- **Byte-compiled / optimized / DLL files**（source_file）：Byte-compiled / optimized / DLL files pycache / .py cod $py.class 证据：`.gitignore`\n- **Use an official Python 3.11 image based on Ubuntu**（source_file）：Use an official Python 3.11 image based on Ubuntu FROM python:3.11-slim 证据：`Dockerfile`\n- **Manifest**（source_file）：include LICENSE include HISTORY.md include README.md include Containerfile graft tests graft testzeus hercules 证据：`MANIFEST.in`\n- **uv run mypy --ignore-missing-imports testzeus hercules/**（source_file）：.ONESHELL: ENV PREFIX=$ shell python -c \"if import 'pathlib' .Path '.venv/bin/pip' .exists : print '.venv/bin/' \" USING UV=$ shell grep \"uv\" pyproject.toml && echo \"yes\" 证据：`Makefile`\n- **!/bin/sh**（source_file）：Check that either LLM MODEL NAME and LLM MODEL API KEY are set together, or AGENTS LLM CONFIG FILE and AGENTS LLM CONFIG FILE REF KEY are set together if { -n \"$LLM MODEL NAME\" && -n \"$LLM MODEL API KEY\" ; } && \\ { -n \"$AGENTS LLM CONFIG FILE\" -n \"$AGENTS LLM CONFIG FILE REF KEY\" ; }; then echo \"Error: Provide either LLM MODEL NAME and LLM MODEL API KEY together, or AGENTS LLM CONFIG FILE and AGENTS LLM CONFIG FILE REF KEY together, not both.\" exit 1 fi 证据：`entrypoint.sh`\n- **Agents Env**（source_file）：export AGENTS LLM CONFIG JSON='' 证据：`helper_scripts/agents_env.sh`\n- **!/usr/bin/env python3**（source_file）：import os import json import urllib.parse import subprocess 证据：`helper_scripts/browser_stack_generate_cdp_url.py`\n- **!/usr/bin/env python**（source_file）：python vir migration script.py raw jsons/test1.json --output=output txt --model=gpt-4o 证据：`helper_scripts/cdp_journey_script.py`\n- **!/usr/bin/env python**（source_file）：how to run python helper scripts/generate api functional gherkin test.py tests/test features/ApiTesting/api spec.yml --output=helper scripts/output --model=gpt-4o --number of testcase=50 证据：`helper_scripts/generate_api_functional_gherkin_test.py`\n- **!/usr/bin/env python**（source_file）：how to run python helper scripts/generate api security gherkin test.py tests/test features/ApiTesting/api spec.yml --output=helper scripts/output --model=gpt-4o 证据：`helper_scripts/generate_api_security_gherkin_test.py`\n- **!/bin/bash**（source_file）：curl -sS https://bootstrap.pypa.io/get-pip.py python3.11 证据：`helper_scripts/hercules_setup.sh`\n- **!/bin/bash**（source_file）：curl -sS https://bootstrap.pypa.io/get-pip.py python3.11 证据：`helper_scripts/hercules_setup_custom.sh`\n- **Ensure the script runs with administrator privileges**（source_file）：Ensure the script runs with administrator privileges if -not Security.Principal.WindowsPrincipal Security.Principal.WindowsIdentity ::GetCurrent .IsInRole Security.Principal.WindowsBuiltInRole \"Administrator\" { Write-Host \"This script must be run as Administrator!\" -ForegroundColor Red Exit 1 } 证据：`helper_scripts/hercules_windows_setup.ps1`\n- **Instead of journeys, call them 'features'**（source_file）：def generate features report virtuoso data - str: \"\"\" Generate a human-readable test steps report where: - 'journeys' are called 'Features' - 'cases' are called 'Scenarios' 证据：`helper_scripts/json_clearner.py`\n- **!/usr/bin/env python3**（source_file）：import os import json import urllib.parse import subprocess 证据：`helper_scripts/lambda_test_generate_cdp_url.py`\n- **Run Hercules Docker**（source_file）：< .SYNOPSIS Pull the testzeus/hercules Docker image, ensure .env and agents llm config.json exist, optionally launch Chrome or Firefox in remote debugging mode based on user selection , and run Hercules in Docker. 证据：`helper_scripts/run_hercules_docker.ps1`\n- **!/usr/bin/env bash**（source_file）：Parse input parameter: --browser=chrome or --browser=none BROWSER CHOICE=\"none\" 证据：`helper_scripts/run_hercules_docker.sh`\n- **!/usr/bin/env python**（source_file）：python vir migration script.py raw jsons/test1.json --output=output txt --model=gpt-4o 证据：`helper_scripts/vir_migration_script.py`\n- **!/bin/bash**（source_file）：Usage: ./write json to var.sh x.json 证据：`helper_scripts/write_json_to_var.sh`\n- **!/bin/bash**（source_file）：Usage: ./write var to json.sh x1.json 证据：`helper_scripts/write_var_to_json.sh`\n- **List of enabled rulsets.**（source_file）：project name = \"testzeus-hercules\" version = \"0.2.0\" description = \"Hercules: The World's First Open-Source AI Agent for End-to-End Testing\" authors = { name = \"Shriyansh Agnihotri\", email = \"shriyansh@testzeus.com\" } requires-python = \" =3.11, =1.6.0, =12.2.0, =2.6.2, =1.0.0, =2.0.7, =6.0.1, =2.0.36, =3.2.0, =2.18.0, =0.5.1, =31.0.2, =3.13.2, =0.5.1, =0.10.0, =1.23.3, =5.9.0, =24.1.0, =1.0.16, =5.0.0, =0.18.18, =0.28.1, =1.11.1, =1.27.0\", \"starlette =0.50.0, =2.6.1, =6.10.2, =4.61.0, =5.0.0rc3, =2.32.5, =2.9.1, =6.33.5, =46.0.7, =0.87.0\", \"python-multipart =0.0.26\", 证据：`pyproject.toml`\n- **Global constants**（source_file）：import pytest import os import shutil 证据：`tests/conftest.py`\n- **Init**（source_file）：from testzeus hercules import core type: ignore noqa: F401 证据：`testzeus_hercules/__init__.py`\n- **get name of the feature file using os package**（source_file）：import asyncio import json import os 证据：`testzeus_hercules/__main__.py`\n- **config manager.py**（source_file）：import argparse import json import os from typing import Any, Dict, List, Literal, Optional, Union 证据：`testzeus_hercules/config.py`\n- **Interactive**（source_file）：from testzeus hercules.config import get global conf from testzeus hercules.core.runner import CommandPromptRunner 证据：`testzeus_hercules/interactive.py`\n- **Telemetry flag, default is enabled 1 unless set to \"0\" in the environment variable**（source_file）：import asyncio import atexit import json import os import signal import uuid from datetime import datetime from enum import Enum from typing import Any, Dict, Optional 证据：`testzeus_hercules/telemetry.py`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `tests/api_testing_app/Readme.md`, `CONTRIBUTING.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `tests/api_testing_app/Readme.md`, `CONTRIBUTING.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **Getting Started with TestZeus Hercules**：importance `high`\n - source_paths: README.md, pyproject.toml, Dockerfile, helper_scripts/hercules_setup.sh, docs/run_guide.md\n- **System Architecture**：importance `high`\n - source_paths: testzeus_hercules/core/runner.py, testzeus_hercules/core/simple_hercules.py, testzeus_hercules/core/__init__.py, testzeus_hercules/interactive.py\n- **Agent System**：importance `high`\n - source_paths: testzeus_hercules/core/agents/high_level_planner_agent.py, testzeus_hercules/core/agents/browser_nav_agent.py, testzeus_hercules/core/agents/api_nav_agent.py, testzeus_hercules/core/agents/sql_nav_agent.py, testzeus_hercules/core/agents/mcp_nav_agent.py\n- **Browser Automation**：importance `high`\n - source_paths: testzeus_hercules/core/playwright_manager.py, testzeus_hercules/core/browser_logger.py, testzeus_hercules/utils/dom_helper.py, testzeus_hercules/utils/get_detailed_accessibility_tree.py, helper_scripts/browser_stack_generate_cdp_url.py\n- **Tool System**：importance `high`\n - source_paths: testzeus_hercules/core/tools/tool_registry.py, testzeus_hercules/core/tools/click_using_selector.py, testzeus_hercules/core/tools/enter_text_using_selector.py, testzeus_hercules/core/tools/hover.py, testzeus_hercules/core/tools/drag_and_drop_tool.py\n- **LLM Configuration**：importance `high`\n - source_paths: testzeus_hercules/core/agents_llm_config_manager.py, testzeus_hercules/core/agents_llm_config.py, agents_llm_config-example.json, testzeus_hercules/utils/llm_helper.py, testzeus_hercules/utils/model_utils.py\n- **Memory Management**：importance `medium`\n - source_paths: testzeus_hercules/core/memory/state_handler.py, testzeus_hercules/core/memory/dynamic_ltm.py, testzeus_hercules/core/memory/static_ltm.py, testzeus_hercules/core/memory/prompt_compressor.py, testzeus_hercules/core/memory/static_data_loader.py\n- **API Testing**：importance `medium`\n - source_paths: testzeus_hercules/core/tools/api_calls.py, testzeus_hercules/core/tools/sql_calls.py, testzeus_hercules/core/agents/api_nav_agent.py, helper_scripts/generate_api_functional_gherkin_test.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `e8bf322a1cd894b1b7b18b4d3c44a4767788363a`\n- inspected_files: `pyproject.toml`, `Dockerfile`, `README.md`, `uv.lock`, `docs/GPT5_USAGE.md`, `docs/run_guide.md`, `docs/python_sandbox_execution.md`, `docs/sandbox_quick_reference.md`, `docs/environment_variables.md`, `docs/MCP_Usage.md`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：0.1.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：0.1.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_87e563b6a81f4a529799ac528ee21610 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：0.0.40\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.0.40\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_02c1945d063b4151a3df1526b85e9d50 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.0.40 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：0.1.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_1d1eb9ae89f04ff9b339c73cc932f2f7 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：0.1.2\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.2\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e0e02b07ea6845eaac8c4f18871aaa32 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.2 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：0.1.6\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.6\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_41cf6e34c47b4f929a67426b258b8fd8 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.6 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：0.1.4\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.1.4\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_d6aeb053b3a541778b07c0bca68c5c82 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.4 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：test-zeus-ai/testzeus-hercules\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：0.1.1（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 来源证据：0.0.40（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：0.1.0（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：0.1.2（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/test-zeus-ai/testzeus-hercules 项目说明书\n\n生成时间：2026-05-17 01:20:40 UTC\n\n## 目录\n\n- [Getting Started with TestZeus Hercules](#getting-started)\n- [System Architecture](#system-architecture)\n- [Agent System](#agent-system)\n- [Browser Automation](#browser-automation)\n- [Tool System](#tool-system)\n- [LLM Configuration](#llm-configuration)\n- [Memory Management](#memory-management)\n- [API Testing](#api-testing)\n- [Security Testing](#security-testing)\n- [MCP Integration](#mcp-integration)\n\n\n\n## Getting Started with TestZeus Hercules\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/CONTRIBUTING.md)\n- [testzeus_hercules/__main__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/__main__.py)\n- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)\n- [testzeus_hercules/telemetry.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/telemetry.py)\n- [testzeus_hercules/utils/response_parser.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/response_parser.py)\n- [frontend/non-interactive/index.html](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/frontend/non-interactive/index.html)\n- [frontend/interactive/index.html](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/frontend/interactive/index.html)\n\n\n# Getting Started with TestZeus Hercules\n\nTestZeus Hercules is an open-source AI-powered end-to-end testing framework that leverages large language models (LLMs) to automate browser testing. It provides both interactive and non-interactive modes for executing automated tests against web applications.\n\n## Overview\n\nTestZeus Hercules serves as an intelligent testing agent that can:\n\n- Navigate web pages and interact with UI elements\n- Generate and execute Gherkin-style test scenarios\n- Perform API security scanning using Nuclei\n- Parse accessibility trees for element identification\n- Execute Python scripts in a sandboxed environment\n\n资料来源：[CONTRIBUTING.md]()\n\n## Architecture\n\n```mermaid\ngraph TD\n A[User Input] --> B[CLI / Main Entry]\n B --> C[Global Configuration]\n C --> D[Navigation Agent]\n D --> E[Browser Controller]\n E --> F[CDP Stream Renderer]\n F --> G[Accessibility Tree]\n G --> D\n D --> H[Python Sandbox Executor]\n H --> I[Test Results]\n D --> J[API Security Scanner]\n J --> K[Nuclei Integration]\n```\n\n### Core Components\n\n| Component | Purpose |\n|-----------|---------|\n| `testzeus_hercules/__main__.py` | Entry point handling bulk test execution |\n| `testzeus_hercules/config.py` | Command-line argument parsing and configuration |\n| `testzeus_hercules/telemetry.py` | Installation tracking and error reporting |\n| `testzeus_hercules/core/agents/executor_nav_agent.py` | Navigation agent for browser automation |\n| `frontend/*/index.html` | CDP stream rendering interfaces |\n\n资料来源：[testzeus_hercules/__main__.py:25-45]()\n资料来源：[testzeus_hercules/config.py]()\n\n## Installation\n\n### Prerequisites\n\n- Python 3.x\n- Git\n- Make\n\n### Setup Steps\n\n1. **Fork the repository**\n\n ```bash\n git clone git@github.com:YOUR_GIT_USERNAME/testzeus-hercules.git\n cd testzeus-hercules\n git remote add upstream https://github.com/test-zeus-ai/testzeus-hercules\n ```\n\n2. **Create virtual environment**\n\n ```bash\n make virtualenv\n source .venv/bin/activate\n ```\n\n3. **Install in development mode**\n\n ```bash\n make install\n ```\n\n资料来源：[CONTRIBUTING.md]()\n\n## Command-Line Interface\n\nTestZeus Hercules provides extensive CLI options for configuration.\n\n### Basic Options\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `--input-file` | str | Path to the input file |\n| `--output-path` | str | Path to the output directory |\n| `--test-data-path` | str | Path to the test data directory |\n| `--project-base` | str | Path to the project base directory |\n\n资料来源：[testzeus_hercules/config.py]()\n\n### LLM Configuration\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `--llm-model` | str | Name of the LLM model |\n| `--llm-model-api-key` | str | API key for the LLM model |\n| `--llm-model-base-url` | str | Base URL for the LLM API |\n| `--llm-model-api-type` | str | Type of API (openai, anthropic, azure) |\n| `--llm-temperature` | float | Temperature for LLM sampling (0.0-1.0) |\n| `--agents-llm-config-file` | str | Path to agents LLM configuration file |\n\n资料来源：[testzeus_hercules/config.py]()\n\n### Browser Options\n\n| Parameter | Description |\n|-----------|-------------|\n| `--browser-channel` | Browser channel (e.g., chrome-beta, firefox-nightly) |\n| `--browser-path` | Custom path to browser executable |\n| `--browser-version` | Specific browser version (e.g., '114', '115.0.1', 'latest') |\n| `--enable-ublock` | Enable uBlock Origin extension |\n| `--disable-ublock` | Disable uBlock Origin extension |\n| `--auto-accept-screen-sharing` | Automatically accept screen sharing prompts |\n\n资料来源：[testzeus_hercules/config.py]()\n\n### Test Execution Options\n\n| Parameter | Description |\n|-----------|-------------|\n| `--bulk` | Execute tests in bulk from tests directory |\n| `--reuse-vector-db` | Reuse existing vector DB instead of creating fresh one |\n\n资料来源：[testzeus_hercules/config.py]()\n资料来源：[testzeus_hercules/__main__.py:45-60]()\n\n### Portkey Integration\n\n| Parameter | Description |\n|-----------|-------------|\n| `--enable-portkey` | Enable Portkey integration for LLM routing |\n| `--portkey-api-key` | API key for Portkey |\n| `--portkey-strategy` | Routing strategy (fallback or loadbalance) |\n\n资料来源：[testzeus_hercules/config.py]()\n\n### Sandbox Configuration\n\n| Parameter | Description |\n|-----------|-------------|\n| `--sandbox-tenant-id` | Tenant ID for sandbox isolation |\n\n资料来源：[testzeus_hercules/config.py]()\n\n## Running TestZeus Hercules\n\n### Interactive Mode\n\nRun the interactive CDP stream renderer with user input capabilities:\n\n```bash\nmake run-interactive\n```\n\nThis launches the frontend at `frontend/interactive/index.html` which provides:\n\n- Real-time screencast display\n- Crosshair cursor for element selection\n- Input capture for typing into the remote page\n\n资料来源：[frontend/interactive/index.html]()\n\n### Non-Interactive Mode\n\nRun tests without user interaction:\n\n```bash\nmake run\n```\n\nThis uses the non-interactive frontend at `frontend/non-interactive/index.html` which displays:\n\n- Connection status\n- Screencast output only\n\n资料来源：[frontend/non-interactive/index.html]()\n\n### Bulk Execution\n\nExecute multiple tests from a tests directory:\n\n```bash\npython -m testzeus_hercules --bulk\n```\n\nThe system checks for a `tests` directory in the project source root and processes each test folder:\n\n```python\nif get_global_conf().should_execute_bulk():\n project_base = get_global_conf().get_project_source_root()\n tests_dir = os.path.join(project_base, \"tests\")\n```\n\n资料来源：[testzeus_hercules/__main__.py:45-55]()\n\n## Response Parsing\n\nTestZeus Hercules includes a robust response parser for handling LLM outputs:\n\n```mermaid\ngraph LR\n A[LLM Response] --> B{Is JSON?}\n B -->|Yes| C[Parse JSON]\n B -->|No| D[Extract Plan/Next Step]\n C --> E[Return Dict]\n D --> E\n```\n\nThe parser handles:\n\n- JSON wrapped in ```json code blocks\n- Plain JSON responses\n- Fallback extraction for `plan` and `next_step` fields\n\n资料来源：[testzeus_hercules/utils/response_parser.py]()\n\n## Telemetry and Installation Tracking\n\nOn first run, TestZeus Hercules generates a unique installation ID:\n\n```python\ndef get_installation_id(file_path: str = \"installation_id.txt\", is_manual_run: bool = True):\n if os.path.exists(file_path):\n # Load existing installation data\n else:\n # Generate new installation ID\n installation_id = str(uuid.uuid4())\n```\n\n资料来源：[testzeus_hercules/telemetry.py]()\n\n## Development Workflow\n\n### Code Quality\n\n| Command | Purpose |\n|---------|---------|\n| `make fmt` | Format code using black & isort |\n| `make lint` | Run pep8, black, mypy linters |\n| `make test` | Run tests and generate coverage report |\n| `make watch` | Run tests on every change |\n\n资料来源：[CONTRIBUTING.md]()\n\n### Testing Requirements\n\n- Code coverage must show `100%` coverage\n- Add tests for all changes in your PR\n\n```bash\nmake test\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n### Release Process\n\n1. Make changes following the contribution guidelines\n2. Commit using conventional commit messages\n3. Run tests to ensure everything works\n4. Execute `make release` to create a new tag and push\n\n> **CAUTION**: The make release will change local changelog files and commit all unstaged changes.\n\n资料来源：[CONTRIBUTING.md]()\n\n## Navigation Agent Execution\n\nThe executor navigation agent follows specific guidelines:\n\n### Execution Principles\n\n1. **Error Review**: Review previous step outcomes before proceeding\n2. **Script Execution**: Use `execute_python_sandbox` tool with access to `page`, `browser`, `context`, `playwright_manager`, `logger`, `config`\n3. **Sequential Execution**: Execute one script at a time and await results\n4. **Validation**: Check for successful execution status before proceeding\n\n资料来源：[testzeus_hercules/core/agents/executor_nav_agent.py]()\n\n## API Security Scanning\n\nTestZeus Hercules integrates with Nuclei for API security testing:\n\n```python\nasync def run_nuclei_command(\n is_open_api_spec: bool,\n open_api_spec_path: Optional[str],\n target_url: Optional[str],\n tag: str,\n output_file: Path,\n headers: Optional[List[Tuple[str, str]]] = None,\n):\n```\n\n资料来源：[testzeus_hercules/core/tools/api_sec_calls.py]()\n\n## Helper Scripts\n\n### CDP Journey Script\n\nGenerate test cases from journey data:\n\n```bash\npython helper_scripts/cdp_journey_script.py --number_of_testcase 5\n```\n\nThis produces Gherkin specifications and test data files from JSON journey definitions.\n\n资料来源：[helper_scripts/cdp_journey_script.py]()\n\n### API Functional Gherkin Test Generator\n\nGenerate Gherkin test cases from OpenAPI specifications:\n\n```bash\npython helper_scripts/generate_api_functional_gherkin_test.py spec.yaml --output ./features --number_of_testcase 100\n```\n\n资料来源：[helper_scripts/generate_api_functional_gherkin_test.py]()\n\n## Accessibility Tree Processing\n\nTestZeus Hercules processes DOM elements to generate accessibility trees:\n\n- Identifies interactive elements (buttons, links, inputs)\n- Detects draggable elements\n- Filters out non-interactive elements\n- Provides detailed element metadata for the AI agent\n\n资料来源：[testzeus_hercules/utils/get_detailed_accessibility_tree.py]()\n\n## Summary\n\nTestZeus Hercules provides a comprehensive end-to-end testing solution with:\n\n- AI-powered browser automation via LLM integration\n- Flexible deployment (interactive and non-interactive modes)\n- Extensive CLI configuration options\n- Built-in support for bulk test execution\n- API security scanning capabilities\n- Gherkin test generation from various sources\n\n资料来源：[CONTRIBUTING.md]()\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Agent System](#agent-system), [Tool System](#tool-system)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [testzeus_hercules/core/runner.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/runner.py)\n- [testzeus_hercules/core/simple_hercules.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)\n- [testzeus_hercules/core/__init__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/__init__.py)\n- [testzeus_hercules/interactive.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/interactive.py)\n- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)\n- [testzeus_hercules/core/extra_tools/__init__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/extra_tools/__init__.py)\n- [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)\n- [testzeus_hercules/telemetry.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/telemetry.py)\n\n\n# System Architecture\n\n## Overview\n\nTestZeus Hercules is an open-source AI agent framework designed for **end-to-end testing** of web applications. The system leverages Large Language Models (LLMs) to orchestrate browser automation through Playwright, enabling natural language-driven test execution without requiring users to write traditional test scripts.\n\nThe architecture follows a modular design pattern with clear separation between:\n- Core execution engine\n- Agent-based navigation and task handling\n- Python sandbox environment for script execution\n- Frontend visualization components\n- Configuration and telemetry systems\n\n**资料来源：** [testzeus_hercules/__main__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/__main__.py)\n\n---\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n User[User / CI Pipeline] --> CLI[CLI Entry Point __main__.py]\n CLI --> Config[Global Configuration config.py]\n CLI --> Runner[CommandPromptRunner runner.py]\n \n Runner --> SimpleHercules[SimpleHercules simple_hercules.py]\n Runner --> Interactive[Interactive Runner interactive.py]\n \n SimpleHercules --> AgentSystem[Agent System]\n AgentSystem --> ExecutorNavAgent[ExecutorNavAgent]\n AgentSystem --> ExtraTools[Extra Tools Loader extra_tools/__init__.py]\n \n ExecutorNavAgent --> Sandbox[Python Sandbox execute_python_sandbox.py]\n Sandbox --> Playwright[Playwright Browser Automation]\n \n SimpleHercules --> Telemetry[Telemetry Module telemetry.py]\n SimpleHercules --> ResponseParser[Response Parser response_parser.py]\n \n Interactive --> CDPStream[CDP Stream Frontend frontend/interactive]\n \n Config --> LLMConfig[LLM Configuration openai, anthropic, azure]\n Config --> Portkey[Portkey Integration]\n```\n\n---\n\n## Core Components\n\n### 1. Entry Points\n\nThe framework provides multiple entry points for different use cases:\n\n| Entry Point | File | Purpose |\n|-------------|------|---------|\n| CLI | `testzeus_hercules/__main__.py` | Main command-line interface with ASCII banner |\n| Interactive | `testzeus_hercules/interactive.py` | Interactive test session runner |\n| Module Import | `testzeus_hercules/core/__init__.py` | Programmatic API for embedding |\n\n**资料来源：** [testzeus_hercules/interactive.py:1-9](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/interactive.py)\n\n#### Interactive Entry Point\n```python\nimport asyncio\nfrom testzeus_hercules.config import get_global_conf\nfrom testzeus_hercules.core.runner import CommandPromptRunner\n\nif __name__ == \"__main__\":\n conf = get_global_conf()\n conf.set_default_test_id(\"interactive_runner\")\n runner = CommandPromptRunner()\n asyncio.run(runner.start())\n```\n\n### 2. Configuration System\n\nThe configuration system (`config.py`) manages all runtime parameters:\n\n**资料来源：** [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)\n\n#### Configuration Categories\n\n| Category | Parameters |\n|----------|------------|\n| **Path Configuration** | `--input-file`, `--output-path`, `--test-data-path`, `--project-base` |\n| **LLM Model** | `--llm-model`, `--llm-model-api-key`, `--llm-model-base-url`, `--llm-model-api-type` |\n| **LLM Sampling** | `--llm-temperature` (0.0-1.0) |\n| **LLM Config Files** | `--agents-llm-config-file`, `--agents-llm-config-file-ref-key` |\n| **Portkey Integration** | `--enable-portkey`, `--portkey-api-key`, `--portkey-strategy` (fallback/loadbalance) |\n| **Browser Options** | `--browser-channel`, `--browser-path`, `--browser-version` |\n| **Browser Extensions** | `--enable-ublock`, `--disable-ublock` |\n| **Screen Sharing** | `--auto-accept-screen-sharing`, `--disable-auto-accept-screen-sharing` |\n| **Execution** | `--bulk`, `--reuse-vector-db` |\n| **Sandbox** | `--sandbox-tenant-id`, `--sandbox-custom-injections` |\n\n---\n\n## Agent System Architecture\n\n### SimpleHercules Core\n\nThe `SimpleHercules` class is the central orchestration engine:\n\n```mermaid\ngraph TD\n subgraph \"SimpleHercules Core\"\n Planner[Planner Agent]\n Executor[ExecutorNavAgent]\n Notifier[Message Notification System]\n State[State Management]\n end\n \n Planner --> LLM[LLM Provider]\n Executor --> Sandbox[Python Sandbox]\n Executor --> Playwright[Playwright Manager]\n Notifier --> UI[Frontend / CLI Output]\n \n State --> PlanSteps[Plan Steps]\n State --> StepHistory[Step History]\n State --> Assertions[Assertion Results]\n```\n\n**资料来源：** [testzeus_hercules/core/simple_hercules.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)\n\n#### Message Flow\n\nThe system processes responses through a structured message format:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `plan` | `List[str]` | List of planned test steps |\n| `next_step` | `str` | Current step instruction |\n| `is_assert` | `bool` | Whether current step is an assertion |\n| `is_passed` | `bool` | Assertion pass/fail status |\n| `assert_summary` | `str` | Summary of assertion results |\n| `is_terminated` | `bool` | Whether execution is terminated |\n| `is_completed` | `bool` | Whether test suite is completed |\n| `final_response` | `str` | Final summary response |\n\n#### Message Notification Types\n\n```python\nclass MessageType(Enum):\n PLAN = \"plan\" # Plan step notifications\n STEP = \"step\" # Current step notifications\n INFO = \"info\" # Information messages\n ERROR = \"error\" # Error messages\n RESULT = \"result\" # Execution results\n```\n\n**资料来源：** [testzeus_hercules/core/simple_hercules.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)\n\n### Executor Navigation Agent\n\nThe `ExecutorNavAgent` handles the execution of browser automation scripts:\n\n**资料来源：** [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)\n\n#### Execution Guidelines\n\n| Rule | Description |\n|------|-------------|\n| **Step Review** | Review previous step outcome before proceeding |\n| **Sequential Execution** | Execute one script/function at a time |\n| **Sandbox Usage** | Execute scripts using `execute_python_sandbox` tool |\n| **Access Variables** | Scripts have access to: `page`, `browser`, `context`, `playwright_manager`, `logger`, `config` |\n| **Validation** | Verify each script execution result before moving on |\n| **Output Processing** | Parse JSON outputs, handle stdout/stderr |\n\n---\n\n## Python Sandbox Architecture\n\nThe sandbox system (`execute_python_sandbox.py`) provides secure script execution with configurable injections:\n\n**资料来源：** [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)\n\n```mermaid\ngraph TD\n Request[Sandbox Request] --> TenantCheck{Tenant ID Check}\n \n TenantCheck -->|executor_agent| HerculesUtils[hercules_utils from testzeus_hercules]\n TenantCheck -->|tenant specific| TenantModules[Custom Modules from SANDBOX_TENANT_ID]\n TenantCheck -->|none| DefaultModules[Default Modules requests, beautifulsoup, etc.]\n \n ConfigDriven -->|SANDBOX_PACKAGES| ConfigPackages[Config-defined packages]\n CustomInjections -->|JSON string| CustomPackages[Custom Package Injections]\n \n DefaultModules --> Merge[Injection Merge]\n TenantModules --> Merge\n ConfigPackages --> Merge\n CustomPackages --> Merge\n \n Merge --> SandboxEnv[Sandbox Environment]\n```\n\n#### Injection Sources\n\n| Source | Configuration Key | Example |\n|--------|-------------------|---------|\n| Default packages | Built-in | `requests`, `beautifulsoup4` |\n| Tenant-specific | `SANDBOX_TENANT_ID` | Custom module per tenant |\n| Config-driven | `SANDBOX_PACKAGES` | Package list from config |\n| Per-call | `--sandbox-custom-injections` | JSON-formatted custom injections |\n\n---\n\n## Extra Tools System\n\nThe extra tools loader (`extra_tools/__init__.py`) dynamically imports all modules in the `extra_tools` directory:\n\n**资料来源：** [testzeus_hercules/core/extra_tools/__init__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/extra_tools/__init__.py)\n\n```python\n# Dynamic module loading pattern\nif get_global_conf().get_load_extra_tools().lower().strip() != \"false\":\n for _, module_name, _ in pkgutil.iter_modules([str(package_path)]):\n full_module_name = f\"testzeus_hercules.core.extra_tools.{module_name}\"\n module = importlib.import_module(full_module_name)\n for attribute_name in dir(module):\n if not attribute_name.startswith(\"_\"):\n globals()[attribute_name] = getattr(module, attribute_name)\n```\n\n---\n\n## Telemetry System\n\nThe telemetry module (`telemetry.py`) handles installation tracking and error reporting:\n\n**资料来源：** [testzeus_hercules/telemetry.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/telemetry.py)\n\n#### Installation ID Management\n\n```python\ndef get_installation_id(file_path: str = \"installation_id.txt\", is_manual_run: bool = True) -> Dict[str, Any]\n```\n\n| Scenario | Behavior |\n|----------|----------|\n| File exists with dict | Return parsed dict with `installation_id` |\n| File exists with string | Return dict with `installation_id` and default email |\n| File not exists + manual run | Prompt for `user_email` |\n| File not exists + automated | Use default values, generate new UUID |\n\n#### Sentry Integration\n\n| Configuration | Purpose |\n|---------------|---------|\n| `max_breadcrumbs=0` | Disable breadcrumb collection |\n| `send_default_pii=False` | Exclude personally identifiable information |\n| `send_client_reports=False` | Disable client reports |\n| `sys.argv` extra | Set to `None` to prevent leakage |\n| `denylist` | Scrub sensitive fields recursively |\n\n---\n\n## Frontend Architecture\n\n### CDP Stream Renderer\n\nThe frontend provides real-time browser visualization:\n\n**资料来源：** [frontend/interactive/index.html](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/frontend/interactive/index.html)\n\n| Version | File | Features |\n|---------|------|----------|\n| Interactive | `frontend/interactive/index.html` | Mouse/keyboard input capture, crosshair cursor |\n| Non-interactive | `frontend/non-interactive/index.html` | Display-only screencast |\n\n#### Interactive Features\n\n- Real-time screencast display via CDP\n- Input capture via hidden dummy input field\n- Crosshair cursor for element selection\n- Pre-formatted output log display\n\n---\n\n## Response Parser\n\nThe response parser (`response_parser.py`) handles LLM output normalization:\n\n**资料来源：** [testzeus_hercules/utils/response_parser.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/response_parser.py)\n\n```python\ndef parse_response(message: str) -> dict[str, Any]\n```\n\n#### Parsing Flow\n\n1. **Strip markdown code blocks**: Handle ` ```json ` and ` ``` ` wrappers\n2. **Normalize whitespace**: Replace `\\n` with spaces\n3. **JSON parsing**: Attempt `json.loads()`\n4. **Fallback parsing**: If JSON fails, extract `plan` and `next_step` via string matching\n5. **Error logging**: Warn and continue if parsing fails\n\n---\n\n## Execution Workflow\n\n```mermaid\nsequenceDiagram\n participant User\n participant CLI\n participant Config\n participant Runner\n participant SimpleHercules\n participant Executor\n participant Sandbox\n participant Playwright\n\n User->>CLI: Run command\n CLI->>Config: Parse arguments\n Config-->>CLI: Global config\n CLI->>Runner: Create CommandPromptRunner\n Runner->>SimpleHercules: Initialize\n SimpleHercules->>Executor: Create ExecutorNavAgent\n \n loop Test Execution\n SimpleHercules->>SimpleHercules: Generate plan via LLM\n SimpleHercules->>Executor: Execute next_step\n Executor->>Sandbox: Run Python script\n Sandbox->>Playwright: Browser automation\n Playwright-->>Sandbox: Result\n Sandbox-->>Executor: Execution result\n Executor-->>SimpleHercules: Response with plan/next_step\n SimpleHercules->>SimpleHercules: Parse and notify\n end\n \n SimpleHercules-->>Runner: Completion / Termination\n Runner-->>User: Final response\n```\n\n---\n\n## LLM Integration\n\n### Supported Providers\n\n| Provider | Configuration | Reference |\n|----------|---------------|-----------|\n| OpenAI | `--llm-model-api-type=openai` | Default |\n| Anthropic | `--llm-model-api-type=anthropic` | Claude models |\n| Azure OpenAI | `--llm-model-api-type=azure` | Azure-hosted |\n| Custom | `--llm-model-base-url` | Self-hosted endpoints |\n\n### Portkey Integration\n\nFor production routing and observability:\n\n```bash\n--enable-portkey\n--portkey-api-key=\n--portkey-strategy=[fallback|loadbalance]\n```\n\n---\n\n## Configuration File Structure\n\nThe system supports YAML/JSON configuration files via `--agents-llm-config-file`:\n\n| Parameter | Description |\n|-----------|-------------|\n| `ref_key` | Reference key for loading specific config sections |\n| `temperature` | Sampling temperature (0.0-1.0) |\n| `max_tokens` | Maximum response length |\n| `model` | Model identifier |\n\n---\n\n## Summary\n\nThe TestZeus Hercules architecture demonstrates a clean separation of concerns:\n\n1. **Entry Layer**: CLI and interactive interfaces for user access\n2. **Configuration Layer**: Centralized parameter management with environment and file support\n3. **Orchestration Layer**: `SimpleHercules` coordinates agent communication\n4. **Execution Layer**: `ExecutorNavAgent` handles browser automation\n5. **Sandbox Layer**: Secure Python script execution with dynamic injections\n6. **Telemetry Layer**: Installation tracking and error reporting via Sentry\n7. **Presentation Layer**: CDP-based frontend for real-time visualization\n\nThis design enables the system to serve as both a standalone testing tool and an embeddable library for larger test frameworks.\n\n---\n\n\n\n## Agent System\n\n### 相关页面\n\n相关主题：[System Architecture](#system-architecture), [Memory Management](#memory-management), [LLM Configuration](#llm-configuration)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [testzeus_hercules/core/agents/high_level_planner_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/high_level_planner_agent.py)\n- [testzeus_hercules/core/agents/browser_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/browser_nav_agent.py)\n- [testzeus_hercules/core/agents/api_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/api_nav_agent.py)\n- [testzeus_hercules/core/agents/sql_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/sql_nav_agent.py)\n- [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)\n- [testzeus_hercules/core/agents/sec_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/sec_nav_agent.py)\n- [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)\n- [testzeus_hercules/core/agents/time_keeper_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/time_keeper_nav_agent.py)\n- [testzeus_hercules/core/agent_registry.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agent_registry.py)\n\n\n# Agent System\n\n## Overview\n\nThe Agent System is the core orchestration layer of the Hercules testing framework. It implements a multi-agent architecture where specialized agents collaborate to execute end-to-end testing scenarios across web browsers, APIs, databases, and other system components.\n\n**资料来源：** [testzeus_hercules/core/agent_registry.py:1-50](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agent_registry.py)\n\n## Architecture Overview\n\nThe system follows a hierarchical agent design where a central planner coordinates specialized navigation agents, each responsible for a specific domain of interaction.\n\n```mermaid\ngraph TD\n A[HighLevelPlannerAgent] --> B[BrowserNavAgent]\n A --> C[ApiNavAgent]\n A --> D[SqlNavAgent]\n A --> E[McpNavAgent]\n A --> F[SecNavAgent]\n A --> G[TimeKeeperNavAgent]\n B --> H[ExecutorNavAgent]\n C --> H\n D --> H\n E --> H\n F --> H\n G --> H\n \n H --> I[Browser/API/SQL/MCP/Security]\n```\n\n**资料来源：** [testzeus_hercules/core/simple_hercules.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)\n\n## Agent Types\n\n### High-Level Planner Agent\n\nThe `HighLevelPlannerAgent` serves as the central coordinator that receives high-level test instructions and decomposes them into executable steps for specialized agents.\n\n**Key Responsibilities:**\n- Parsing test instructions and generating execution plans\n- Routing tasks to appropriate specialized agents\n- Aggregating results and handling test completion\n- Managing assertions and validating expected outcomes\n\n**资料来源：** [testzeus_hercules/core/agents/high_level_planner_agent.py:1-80](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/high_level_planner_agent.py)\n\n### Browser Navigation Agent\n\nThe `BrowserNavAgent` handles all browser-based interactions including page navigation, element interaction, and DOM manipulation.\n\n**Capabilities:**\n- Web page navigation and URL handling\n- Element clicking and text input\n- Screenshot capture and visual validation\n- Cookie and session management\n\n**资料来源：** [testzeus_hercules/core/agents/browser_nav_agent.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/browser_nav_agent.py)\n\n### API Navigation Agent\n\nThe `ApiNavAgent` manages HTTP-based interactions for testing RESTful APIs and web services.\n\n**Capabilities:**\n- HTTP request construction and execution\n- Response validation and assertion\n- Authentication handling (OAuth, API keys, Bearer tokens)\n- Multi-step API workflows\n\n**资料来源：** [testzeus_hercules/core/agents/api_nav_agent.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/api_nav_agent.py)\n\n### SQL Navigation Agent\n\nThe `SqlNavAgent` handles database interactions for data validation and setup during test execution.\n\n**Capabilities:**\n- SQL query execution\n- Database connection management\n- Result set validation\n- Test data preparation and teardown\n\n**资料来源：** [testzeus_hercules/core/agents/sql_nav_agent.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/sql_nav_agent.py)\n\n### MCP Navigation Agent\n\nThe `McpNavAgent` provides Model Context Protocol integration for interacting with external AI models and tools.\n\n**Capabilities:**\n- MCP server connection management\n- Tool invocation through MCP protocol\n- Context propagation for AI-assisted testing\n\n**资料来源：** [testzeus_hercules/core/agents/mcp_nav_agent.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/mcp_nav_agent.py)\n\n### Security Navigation Agent\n\nThe `SecNavAgent` handles security-related testing scenarios including authentication flows, authorization checks, and vulnerability scanning.\n\n**Capabilities:**\n- Authentication flow testing\n- Session security validation\n- Authorization boundary testing\n- Security header verification\n\n**资料来源：** [testzeus_hercules/core/agents/sec_nav_agent.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/sec_nav_agent.py)\n\n### Time Keeper Navigation Agent\n\nThe `TimeKeeperNavAgent` manages time-related test scenarios including scheduling, delays, and time-based assertions.\n\n**Capabilities:**\n- Time-based test scheduling\n- Delay and timeout management\n- Timestamp validation\n- Scheduled task execution\n\n**资料来源：** [testzeus_hercules/core/agents/time_keeper_nav_agent.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/time_keeper_nav_agent.py)\n\n### Executor Navigation Agent\n\nThe `ExecutorNavAgent` serves as the execution engine that runs Python scripts and commands within a sandboxed environment.\n\n**Key Features:**\n- Python script execution in isolated sandbox\n- Dynamic module injection based on tenant configuration\n- Access to browser context, page objects, and configuration\n- Custom injection support for tenant-specific utilities\n\n**资料来源：** [testzeus_hercules/core/agents/executor_nav_agent.py:1-150](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/executor_nav_agent.py)\n\n## Agent Registry\n\nThe `AgentRegistry` provides a centralized registration and lookup mechanism for all agents in the system.\n\n### Registry Operations\n\n| Operation | Description |\n|-----------|-------------|\n| `register_agent(name, agent)` | Register a new agent with a unique name |\n| `get_agent(name)` | Retrieve an agent by name |\n| `list_agents()` | List all registered agents |\n| `remove_agent(name)` | Remove an agent from the registry |\n\n**资料来源：** [testzeus_hercules/core/agent_registry.py:50-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agent_registry.py)\n\n## Agent Creation Flow\n\nThe `SimpleHercules` class orchestrates agent creation with the following workflow:\n\n```mermaid\nsequenceDiagram\n participant SH as SimpleHercules\n participant Planner as HighLevelPlannerAgent\n participant Nav as Navigation Agents\n participant Exec as ExecutorNavAgent\n \n SH->>SH: Initialize configuration\n SH->>Planner: Create planner agent\n SH->>Nav: Create navigation agents (Browser, API, SQL, etc.)\n SH->>Exec: Create executor agent\n SH->>SH: Register all agents in registry\n Planner->>Nav: Route tasks based on type\n Nav->>Exec: Execute concrete actions\n```\n\n**资料来源：** [testzeus_hercules/core/simple_hercules.py:100-200](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)\n\n## Message Flow\n\nAgents communicate through a structured message passing system with the following message types:\n\n| Message Type | Purpose |\n|--------------|---------|\n| `PLAN` | Initial test plan and steps |\n| `STEP` | Individual test step execution |\n| `INFO` | Informational messages |\n| `ASSERT` | Assertion results |\n| `COMPLETED` | Task completion notification |\n| `TERMINATED` | Agent termination signal |\n\n**资料来源：** [testzeus_hercules/core/simple_hercules.py:200-300](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)\n\n## Configuration\n\n### LLM Model Configuration\n\nEach agent supports individual LLM model configuration:\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `model` | string | Model name (e.g., gpt-4, claude-3) |\n| `temperature` | float | Sampling temperature (0.0-1.0) |\n| `max_tokens` | int | Maximum response tokens |\n| `api_key` | string | API authentication key |\n| `base_url` | string | Custom API endpoint URL |\n\n**资料来源：** [testzeus_hercules/config.py:1-80](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)\n\n### Agent-Specific Settings\n\n```python\n# Example agent configuration structure\nagent_config = {\n \"model_config_params\": {\n \"model\": \"gpt-4\",\n \"temperature\": 0.7,\n \"max_tokens\": 2000\n },\n \"llm_config_params\": {\n \"timeout\": 60,\n \"retry_attempts\": 3\n },\n \"other_settings\": {\n \"system_prompt\": \"You are a testing agent...\",\n \"max_chat_rounds\": 10\n }\n}\n```\n\n## Response Parsing\n\nThe system uses `parse_response()` from the response parser module to extract structured data from agent outputs:\n\n```python\ndef parse_response(message: str) -> dict[str, Any]:\n # Handles JSON extraction from markdown code blocks\n # Normalizes newlines and whitespace\n # Extracts plan and next_step fields\n```\n\n**资料来源：** [testzeus_hercules/utils/response_parser.py:1-60](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/response_parser.py)\n\n## Sandbox Execution\n\nThe ExecutorNavAgent provides a secure Python execution environment with configurable module injection:\n\n### Available Injections\n\n| Module | Description |\n|--------|-------------|\n| `playwright` | Browser automation library |\n| `requests` | HTTP client library |\n| `beautifulsoup4` | HTML parsing |\n| `hercules_utils` | Project utility functions |\n| Custom packages | Configured via SANDBOX_PACKAGES |\n\n**资料来源：** [testzeus_hercules/core/tools/execute_python_sandbox.py:1-100](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/execute_python_sandbox.py)\n\n### Sandbox Context Variables\n\nScripts executed in the sandbox have automatic access to:\n\n| Variable | Type | Description |\n|----------|------|-------------|\n| `page` | Playwright Page | Current browser page |\n| `browser` | Playwright Browser | Browser instance |\n| `context` | Playwright Context | Browser context |\n| `playwright_manager` | Manager | Playwright management |\n| `logger` | Logger | Logging interface |\n| `config` | Config | Global configuration |\n\n## Command-Line Interface\n\nThe agent system supports configuration via command-line arguments:\n\n| Argument | Description |\n|----------|-------------|\n| `--llm-model` | Specify LLM model name |\n| `--llm-temperature` | Set sampling temperature |\n| `--agents-llm-config-file` | Path to agent config file |\n| `--enable-portkey` | Enable Portkey routing |\n| `--browser-channel` | Browser channel selection |\n| `--reuse-vector-db` | Reuse existing vector database |\n\n**资料来源：** [testzeus_hercules/config.py:80-150](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)\n\n## Error Handling\n\nAgents implement robust error handling with:\n\n1. **Termination Message Check**: Each agent validates termination conditions via `is_xxx_termination_message()` functions\n2. **Tool Call Monitoring**: Tracks pending tool calls to prevent premature termination\n3. **Graceful Degradation**: Continues execution with alternative approaches on failure\n4. **Logging**: Comprehensive logging for debugging and audit trails\n\n**资料来源：** [testzeus_hercules/core/simple_hercules.py:300-400](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/simple_hercules.py)\n\n---\n\n\n\n## Browser Automation\n\n### 相关页面\n\n相关主题：[Tool System](#tool-system)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [testzeus_hercules/core/playwright_manager.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/playwright_manager.py)\n- [testzeus_hercules/core/browser_logger.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/browser_logger.py)\n- [testzeus_hercules/utils/dom_helper.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/dom_helper.py)\n- [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)\n- [helper_scripts/browser_stack_generate_cdp_url.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/helper_scripts/browser_stack_generate_cdp_url.py)\n- [helper_scripts/lambda_test_generate_cdp_url.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/helper_scripts/lambda_test_generate_cdp_url.py)\n\n\n# Browser Automation\n\n## Overview\n\nBrowser Automation in TestZeus Hercules provides a comprehensive framework for controlling web browsers through Playwright, enabling autonomous agents to perform complex web interactions, testing, and data extraction tasks. The system acts as a bridge between LLM-powered agents and real browser instances, translating natural language instructions into precise DOM manipulations.\n\nThe automation layer handles multiple browser types (Chromium, Firefox, WebKit), manages browser contexts with device emulation, supports cloud-based testing platforms via CDP (Chrome DevTools Protocol) tunneling, and provides sophisticated DOM interaction tools including accessibility-aware element selection and real-time mutation observation.\n\n**资料来源：** [testzeus_hercules/core/playwright_manager.py:1-50]()\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n A[SimpleHercules Core] --> B[PlaywrightManager]\n B --> C[Browser Context]\n C --> D[Browser Instance Chromium|Firefox|WebKit]\n B --> E[Tool Registry]\n E --> F[Navigation Tools]\n E --> G[Interaction Tools]\n E --> H[Extraction Tools]\n B --> I[DOM Mutation Observer]\n B --> J[BrowserLogger]\n J --> K[Interaction Logs]\n K --> L[Accessibility Tree]\n L --> M[AccessibilityInfo]\n```\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| PlaywrightManager | `core/playwright_manager.py` | Central browser lifecycle management |\n| BrowserLogger | `core/browser_logger.py` | Interaction logging and proof generation |\n| DOMHelper | `utils/dom_helper.py` | DOM state management and waiting |\n| AccessibilityTree | `utils/get_detailed_accessibility_tree.py` | Extract and format accessibility information |\n| ToolRegistry | `core/tools/tool_registry.py` | Dynamic tool registration and routing |\n\n**资料来源：** [testzeus_hercules/core/playwright_manager.py]()\n**资料来源：** [testzeus_hercules/utils/dom_helper.py]()\n\n---\n\n## PlaywrightManager\n\nThe `PlaywrightManager` class is the central orchestrator for all browser operations. It handles browser launching, page management, element location, and interaction recording.\n\n### Browser Launch Modes\n\n```mermaid\ngraph LR\n A[Browser Launch Request] --> B{Launch Type?}\n B -->|Persistent| C[Launch Persistent Context]\n B -->|Remote CDP| D[Connect via CDP URL]\n B -->|Recording| E[Launch with Video Recording]\n C --> F[Browser Instance]\n D --> F\n E --> F\n```\n\n**资料来源：** [testzeus_hercules/core/playwright_manager.py:100-200]()\n\n### Browser Types\n\nThe system supports three browser engines:\n\n| Browser | Type Identifier | Extensions Support | Certificate Handling |\n|---------|-----------------|-------------------|---------------------|\n| Chromium | `chromium` | Yes (uBlock Origin) | Default ignore |\n| Firefox | `firefox` | Yes | Via args |\n| WebKit | `webkit` | Limited | Via args |\n\n**资料来源：** [testzeus_hercules/core/playwright_manager.py:180-220]()\n\n### Context Options\n\nThe `_build_emulation_context_options` method configures device emulation:\n\n```mermaid\ngraph TD\n A[Build Context Options] --> B{Device Name?}\n B -->|Yes| C[Get Device from Playwright]\n C --> D[Merge Device Properties]\n B -->|No| E[Skip Device Emulation]\n D --> F[Return Context Options]\n E --> F\n```\n\nContext options include viewport size, user agent, device scale factor, and touch capabilities based on the selected device profile.\n\n**资料来源：** [testzeus_hercules/core/playwright_manager.py:200-230]()\n\n### CDP Remote Connection\n\nThe system supports connecting to remote browser instances through BrowserStack and LambdaTest via CDP tunneling.\n\n#### BrowserStack Integration\n\nThe `browser_stack_generate_cdp_url.py` helper generates CDP URLs for BrowserStack's remote browser grid:\n\n```python\n# Simplified flow from helper_scripts/browser_stack_generate_cdp_url.py\ndef generate_cdp_url(username, access_key, session_id):\n ws_endpoint = f\"wss://{username}:{access_key}@cdp.browserstack.com\"\n return f\"{ws_endpoint}/playwright?sessionId={session_id}\"\n```\n\n**资料来源：** [helper_scripts/browser_stack_generate_cdp_url.py]()\n\n#### LambdaTest Integration\n\nSimilarly, LambdaTest provides CDP access through their Selenium Smart Proxy:\n\n```python\n# Simplified flow from helper_scripts/lambda_test_generate_cdp_url.py\ndef generate_cdp_url(username, access_key, session_id):\n hub_endpoint = f\"wss://{username}:{access_key}@hub.lambdatest.com/cdp\"\n return f\"{hub_endpoint}/{session_id}\"\n```\n\n**资料来源：** [helper_scripts/lambda_test_generate_cdp_url.py]()\n\n---\n\n## Browser Tools\n\nBrowser automation tools are registered in the Tool Registry and decorated with `@tool` to enable agent consumption.\n\n### Tool Categories\n\n| Category | Tools | Purpose |\n|----------|-------|---------|\n| Navigation | `open_url`, `go_back`, `go_forward` | URL navigation and history |\n| Interaction | `click`, `hover`, `type`, `upload_file` | User interaction simulation |\n| Extraction | `get_page_text`, `get_input_fields`, `get_interactive_elements` | DOM content retrieval |\n| Accessibility | `get_accessibility_info`, `run_accessibility_check` | WCAG compliance testing |\n| Special | `set_date_time_value`, `read_clipboard` | Specialized interactions |\n\n**资料来源：** [testzeus_hercules/core/tools/tool_registry.py]()\n**资料来源：** [testzeus_hercules/core/tools/open_url.py]()\n\n### Selector Convention\n\nAll tools use the `md` attribute for element selection, enabling stable selectors independent of DOM structure changes:\n\n```python\n# Selector format\nselector = \"[md='element_id']\"\n\n# Automatic conversion if not present\nif \"md=\" not in selector:\n selector = f\"[md='{selector}']\"\n```\n\n**资料来源：** [testzeus_hercules/core/tools/hover.py:25-30]()\n\n### Interactive Elements Extraction\n\nThe `get_interactive_elements` tool retrieves all clickable, focusable, and input elements with their accessibility properties:\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"\"\"DOM Type dict Retrieval Tool, giving all interactive elements on page.\nNotes: [Elements ordered as displayed, Consider ordinal/numbered item positions, List ordinal represent z-index on page]\"\"\",\n name=\"get_interactive_elements\",\n)\n```\n\nElements are ordered by visual display position and include z-index representation.\n\n**资料来源：** [testzeus_hercules/core/tools/get_interactive_elements.py]()\n\n### Input Fields Retrieval\n\nThe `get_input_fields` tool specifically targets form input elements:\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"\"\"DOM Type dict Retrieval Tool, giving only html input types elements on page.\nNotes: [Elements ordered as displayed, Consider ordinal/numbered item positions]\"\"\",\n name=\"get_input_fields\",\n)\n```\n\n**资料来源：** [testzeus_hercules/core/tools/get_input_fields.py]()\n\n### Page Text Extraction\n\nThe `get_page_text` tool fetches text content from the DOM, stripping HTML tags for readability:\n\n```python\nasync def get_page_text() -> Annotated[str, \"DOM content based on type to analyze and decide\"]:\n # Uses innerText or documentElement.innerText\n text_content = await page.evaluate(\"() => document.body.innerText || document.documentElement.innerText\")\n```\n\n**资料来源：** [testzeus_hercules/core/tools/get_page_text.py]()\n\n### File Upload Handling\n\nThe `upload_file` tool supports two upload mechanisms:\n\n1. Direct file input: Sets files directly on `` elements\n2. File chooser API: Clicks element, intercepts file chooser, and sets files\n\n```python\n# Check element type\nelement_type = await element.evaluate(\"el => el.type\")\nif element_type != \"file\":\n # Use FileChooser API\n async with page.expect_file_chooser() as fc_info:\n await element.click()\n file_chooser = await fc_info.value\n await file_chooser.set_files(file_path)\n```\n\n**资料来源：** [testzeus_hercules/core/tools/upload_file.py]()\n\n### Clipboard Operations\n\nThe `read_clipboard` tool reads clipboard content with type specification:\n\n```python\n@tool(\n name=\"read_clipboard\",\n description=\"\"\"Reads the clipboard content from the current page.\n Accepts a parameter to specify the clipboard type: 'text' for plain text\n or 'binary' for a binary object representation.\"\"\"\n)\nasync def read_clipboard(clipboard_type: Annotated[str, \"'text' or 'binary'\"] = \"text\")\n```\n\n**资料来源：** [testzeus_hercules/core/extra_tools/clipboard_tools.py]()\n\n---\n\n## DOM Mutation Observation\n\nThe system monitors DOM changes in real-time using a mutation observer pattern, enabling agents to detect when actions cause new elements to appear.\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Tool\n participant Observer\n participant Page\n \n Agent->>Tool: Execute action\n Tool->>Observer: Subscribe to changes\n Tool->>Page: Perform DOM operation\n Page->>Observer: Mutation detected\n Observer->>Tool: DOM changes detected\n Tool->>Agent: Return result with new elements info\n Tool->>Observer: Unsubscribe\n```\n\n**资料来源：** [testzeus_hercules/utils/dom_mutation_observer.py]()\n**资料来源：** [testzeus_hercules/core/tools/enter_date_time.py]()\n\n### Wait Strategies\n\nThe `wait_for_non_loading_dom_state` function waits for the DOM to reach a stable state before proceeding:\n\n```python\nawait wait_for_non_loading_dom_state(page, max_wait_seconds=1)\n```\n\nThis prevents race conditions where tools attempt to interact with elements that are still being loaded or rendered.\n\n**资料来源：** [testzeus_hercules/utils/dom_helper.py]()\n\n---\n\n## Accessibility Integration\n\n### Accessibility Tree Generation\n\nThe `get_detailed_accessibility_tree.py` module extracts and formats accessibility information using Playwright's accessibility API:\n\n```python\nfrom testzeus_hercules.utils.get_detailed_accessibility_tree import (\n do_get_accessibility_info,\n rename_children,\n)\n```\n\n**资料来源：** [testzeus_hercules/utils/get_detailed_accessibility_tree.py]()\n\n### Accessibility Testing\n\nThe `run_accessibility_check` tool integrates axe-core for automated accessibility audits:\n\n```python\n# Inject axe-core from CDN\nresponse = await page.evaluate(f'fetch(\"{AXE_SCRIPT_URL}\").then(res => res.text())')\nawait page.add_script_tag(content=response)\n\n# Run accessibility checks\naxe_results = await page.evaluate(\"\"\"\n async () => {\n return await axe.run();\n }\n\"\"\")\n```\n\nViolations are logged with detailed failure summaries, enabling agents to identify and address accessibility issues.\n\n**资料来源：** [testzeus_hercules/core/tools/accessibility_calls.py]()\n\n---\n\n## Configuration\n\n### Command-Line Arguments\n\nThe `config.py` file defines extensive browser automation configuration options:\n\n| Argument | Type | Default | Description |\n|----------|------|---------|-------------|\n| `--browser-channel` | str | None | Browser channel (e.g., chrome-beta, firefox-nightly) |\n| `--browser-path` | str | None | Custom path to browser executable |\n| `--browser-version` | str | None | Specific browser version (e.g., '114', '115.0.1') |\n| `--enable-ublock` | flag | False | Enable uBlock Origin extension |\n| `--disable-ublock` | flag | False | Disable uBlock Origin extension |\n| `--auto-accept-screen-sharing` | flag | False | Auto-accept screen sharing prompts |\n| `--disable-auto-accept-screen-sharing` | flag | False | Disable auto screen sharing acceptance |\n\n**资料来源：** [testzeus_hercules/config.py]()\n\n### Global Configuration\n\nThe `get_global_conf()` function provides runtime configuration access for:\n\n- Source log folder paths\n- Proof path for screenshots and logs\n- Delay time between operations\n- Load state configuration\n\n**资料来源：** [testzeus_hercules/config.py]()\n\n---\n\n## Browser Logging\n\n### Interaction Logging\n\nThe `BrowserLogger` class records all browser interactions for debugging and proof generation:\n\n```python\nawait browser_logger.log_browser_interaction(\n tool_name=\"openurl\",\n action=\"navigate\",\n interaction_type=\"navigation\",\n success=True,\n additional_data={\n \"url\": url,\n \"title\": title,\n \"from_cache\": True,\n },\n)\n```\n\n**资料来源：** [testzeus_hercules/core/browser_logger.py]()\n**资料来源：** [testzeus_hercules/core/tools/open_url.py]()\n\n### Screenshot Capture\n\nTools automatically capture screenshots before and after execution:\n\n```python\nawait browser_manager.take_screenshots(f\"{function_name}_start\", page)\n# ... perform action ...\nawait browser_manager.take_screenshots(f\"{function_name}_end\", page)\n```\n\n**资料来源：** [testzeus_hercules/core/tools/hover.py]()\n\n### Selector Logging\n\nFailed selector interactions are logged with detailed error information:\n\n```python\nawait selector_logger.log_selector_interaction(\n tool_name=\"upload_file\",\n selector=selector,\n action=\"upload\",\n selector_type=\"css\",\n success=False,\n error_message=f\"Error: Selector '{selector}' not found.\",\n)\n```\n\n**资料来源：** [testzeus_hercules/core/tools/upload_file.py]()\n\n---\n\n## Agent Integration\n\n### BrowserNavAgent\n\nThe `SimpleHercules` class orchestrates agent-based browser automation:\n\n```python\nbrowser_nav_agent = BrowserNavAgent(\n self.browser_nav_agent_model_config,\n self.nav_agent_config[\"llm_config_params\"],\n self.nav_agent_config.get(\"other_settings\", {}).get(\"system_prompt\"),\n user_proxy_agent,\n)\n```\n\nAgents receive tools through the Tool Registry and execute browser operations autonomously based on natural language instructions.\n\n**资料来源：** [testzeus_hercules/core/simple_hercules.py]()\n\n### System Prompts\n\nAgent behavior is guided by system prompts that define DOM handling rules:\n\n```python\n# From prompts.py - key instructions for agents:\n- Use md attribute selectors for element identification\n- Never substring extracted HTML DOM\n- Remove entire sections if not needed (scripts, links)\n- Use innerText for text content retrieval\n- Verify task completion after execution\n- Use ##TERMINATE## signal when complete\n```\n\n**资料来源：** [testzeus_hercules/core/prompts.py]()\n\n---\n\n## Frontend Interface\n\n### CDP Stream Renderer\n\nThe project includes frontend interfaces for viewing browser sessions in real-time:\n\n| File | Purpose |\n|------|---------|\n| `frontend/non-interactive/index.html` | Basic screencast display |\n| `frontend/interactive/index.html` | Interactive viewer with mouse/keyboard input forwarding |\n\nThe interactive interface uses a hidden input element to capture focus and prevent scrolling while forwarding input events to the remote browser session.\n\n**资料来源：** [frontend/non-interactive/index.html]()\n**资料来源：** [frontend/interactive/index.html]()\n\n---\n\n## Summary\n\nBrowser Automation in TestZeus Hercules provides a production-ready framework for autonomous web interaction. Key capabilities include:\n\n1. **Multi-Browser Support**: Chromium, Firefox, and WebKit with extension support\n2. **Remote Browser Access**: CDP tunneling for BrowserStack and LambdaTest\n3. **Sophisticated Element Selection**: Accessibility-aware tools using the `md` attribute convention\n4. **Real-Time DOM Monitoring**: Mutation observers for detecting dynamic content changes\n5. **Comprehensive Logging**: Screenshots, interaction logs, and accessibility audits\n6. **Agent Integration**: LLM-powered automation through BrowserNavAgent\n\n---\n\n\n\n## Tool System\n\n### 相关页面\n\n相关主题：[Browser Automation](#browser-automation)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [testzeus_hercules/core/tools/tool_registry.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/tool_registry.py)\n- [testzeus_hercules/core/tools/click_using_selector.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/click_using_selector.py)\n- [testzeus_hercules/core/tools/enter_text_using_selector.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/enter_text_using_selector.py)\n- [testzeus_hercules/core/tools/hover.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/hover.py)\n- [testzeus_hercules/core/tools/drag_and_drop_tool.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/drag_and_drop_tool.py)\n- [testzeus_hercules/core/tools/get_interactive_elements.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/get_interactive_elements.py)\n- [testzeus_hercules/core/tools/accessibility_calls.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/accessibility_calls.py)\n- [testzeus_hercules/core/tools/upload_file.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/upload_file.py)\n- [testzeus_hercules/core/extra_tools/browser_assist_tools.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/extra_tools/browser_assist_tools.py)\n\n\n# Tool System\n\n## Overview\n\nThe Tool System is the core execution layer of TestZeus Hercules, providing AI agents with capabilities to interact with web pages through a unified, decorator-based interface. The system abstracts browser automation operations (clicking, typing, hovering, dragging, etc.) into discrete, callable tools that agents can invoke during test execution.\n\nTools serve as the fundamental building blocks that bridge natural language agent instructions with Playwright browser automation. Each tool encapsulates a specific browser interaction pattern, handles error cases gracefully, and returns structured results that agents can parse and respond to. 资料来源：[testzeus_hercules/core/tools/click_using_selector.py:1-50]()\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n subgraph \"Agent Layer\"\n A[\"Browser Nav Agent\"]\n B[\"Executor Nav Agent\"]\n end\n \n subgraph \"Tool Registry\"\n C[\"tool_registry.py\"]\n D[\"Tool Decorator\"]\n end\n \n subgraph \"Core Browser Tools\"\n E[\"click_using_selector\"]\n F[\"enter_text_using_selector\"]\n G[\"hover\"]\n H[\"drag_and_drop_tool\"]\n I[\"get_interactive_elements\"]\n end\n \n subgraph \"Extra Tools\"\n J[\"browser_assist_tools\"]\n K[\"accessibility_calls\"]\n L[\"upload_file\"]\n end\n \n subgraph \"Browser Automation\"\n M[\"Playwright Manager\"]\n N[\"Page Object\"]\n end\n \n A --> C\n B --> C\n C --> E\n C --> F\n C --> G\n C --> H\n C --> I\n C --> J\n J --> K\n J --> L\n E --> M\n F --> M\n G --> M\n M --> N\n```\n\n### Tool Categories\n\n| Category | Purpose | Location | Example Tools |\n|----------|---------|----------|---------------|\n| **Core Browser Tools** | Primary page interactions | `testzeus_hercules/core/tools/` | click, enter_text, hover, drag_drop |\n| **Extra Tools** | Auxiliary functionality | `testzeus_hercules/core/extra_tools/` | accessibility, browser_assist |\n| **Upload Tools** | File handling | `testzeus_hercules/core/tools/` | upload_file |\n\n## Tool Definition Pattern\n\n### The `@tool` Decorator\n\nAll tools in the system are defined using the `@tool` decorator, which registers the function with the tool registry and provides metadata for agent consumption.\n\n```python\nfrom functools import wraps\nfrom typing import Annotated, Any, Dict, List, Optional\n\ndef tool(agent_names: List[str], description: str, name: str):\n \"\"\"Decorator to register a function as a callable tool.\"\"\"\n def decorator(func):\n @wraps(func)\n async def wrapper(*args, **kwargs):\n return await func(*args, **kwargs)\n wrapper._tool_config = {\n \"agent_names\": agent_names,\n \"description\": description,\n \"name\": name,\n }\n return wrapper\n return decorator\n```\n\n### Tool Registration Metadata\n\n| Parameter | Type | Description | Required |\n|-----------|------|-------------|----------|\n| `agent_names` | `List[str]` | List of agent identifiers that can call this tool | Yes |\n| `description` | `str` | Human-readable description for the LLM | Yes |\n| `name` | `str` | Unique identifier for the tool | Yes |\n\nExample usage:\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"Click on an element using selector\",\n name=\"click\"\n)\nasync def click_element(selector: Annotated[str, \"CSS selector\"]) -> dict:\n # Implementation\n pass\n```\n\n资料来源：[testzeus_hercules/core/tools/click_using_selector.py:1-30]()\n\n## Core Browser Tools\n\n### Click Tool (`click_using_selector`)\n\nThe primary interaction tool for clicking on page elements.\n\n**Function Signature:**\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"used to click on an element in the DOM.\",\n name=\"click\"\n)\nasync def click_using_selector(\n selector: Annotated[\n str,\n \"md attribute value of the dom element to interact, md is an ID\"\n ],\n click_type: Annotated[\n Optional[str],\n \"type of click - left, right, double, mouseover, mouseenter, mouseleave, mouseexit, mousedown, mouseup\"\n ] = \"left\",\n timeout: Annotated[int, \"Timeout in milliseconds\"] = 30000,\n) -> Annotated[Dict[str, Any], \"Result of the click operation\"]\n```\n\n**Execution Flow:**\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant ClickTool\n participant PlaywrightManager\n participant Page\n participant SelectorLogger\n\n Agent->>ClickTool: click_using_selector(selector, click_type)\n ClickTool->>PlaywrightManager: find_element(selector)\n PlaywrightManager->>Page: locator(selector).first\n Page-->>PlaywrightManager: ElementHandle\n PlaywrightManager-->>ClickTool: element\n \n alt Element not found\n ClickTool->>SelectorLogger: log_selector_interaction(success=False)\n ClickTool-->>Agent: Error response\n end\n \n ClickTool->>Page: element.scroll_into_view_if_needed()\n ClickTool->>Page: element.is_visible()\n \n alt Element not visible\n ClickTool-->>Agent: Try another element response\n end\n \n ClickTool->>SelectorLogger: get_alternative_selectors()\n ClickTool->>SelectorLogger: get_element_attributes()\n ClickTool->>Page: element.click(click_type)\n \n alt Click success\n ClickTool->>SelectorLogger: log_selector_interaction(success=True)\n ClickTool-->>Agent: Success response\n else Click fails\n ClickTool->>SelectorLogger: log_selector_interaction(success=False)\n ClickTool-->>Agent: Error response\n end\n```\n\n**Error Handling:**\n\nThe click tool performs comprehensive error handling:\n\n1. **Element Not Found**: Logs selector interaction with `success=False` and raises `ValueError`\n2. **Element Not Visible**: Returns alternative suggestion response\n3. **Scroll Failure**: Gracefully continues (non-blocking)\n4. **Click Execution Failure**: Logs failure and returns error dictionary\n\n```python\nif element is None:\n await selector_logger.log_selector_interaction(\n tool_name=\"click\",\n selector=selector,\n action=type_of_click,\n selector_type=\"css\" if \"md=\" in selector else \"custom\",\n success=False,\n error_message=f'Element with selector: \"{selector}\" not found',\n )\n raise ValueError(f'Element with selector: \"{selector}\" not found')\n```\n\n资料来源：[testzeus_hercules/core/tools/click_using_selector.py:40-80]()\n\n### Enter Text Tool (`enter_text_using_selector`)\n\nHandles text input into form fields and contenteditable elements.\n\n**Function Signature:**\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"used to enter the given text into an input field or a contenteditable element.\",\n name=\"enter_text\"\n)\nasync def enter_text_using_selector(\n selector: Annotated[str, \"md attribute value of the dom element to interact\"],\n text_to_fill: Annotated[str, \"text to enter into the element\"],\n submit: Annotated[Optional[bool], \"whether to submit after entering text\"] = False,\n press_enter_after_input: Annotated[bool, \"press Enter key after filling text\"] = False,\n) -> Annotated[Dict[str, str], \"Result dictionary with summary and details\"]\n```\n\n### Hover Tool (`hover`)\n\nMoves mouse cursor over an element without clicking.\n\n**Function Signature:**\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"used to hover over an element in the DOM.\",\n name=\"hover\"\n)\nasync def hover_using_selector(\n selector: Annotated[str, \"md attribute value of the dom element to interact\"],\n timeout: Annotated[int, \"Timeout in milliseconds\"] = 30000,\n) -> Annotated[Dict[str, Any], \"Result of the hover operation\"]\n```\n\n### Drag and Drop Tool (`drag_and_drop_tool`)\n\nPerforms HTML5 drag-and-drop operations between elements.\n\n**Function Signature:**\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"used to drag and drop an element.\",\n name=\"drag_and_drop\"\n)\nasync def drag_and_drop(\n source: Annotated[str, \"md attribute value of source element\"],\n target: Annotated[str, \"md attribute value of target element\"],\n) -> Annotated[Dict[str, str], \"Result of the drag and drop operation\"]\n```\n\n### Get Interactive Elements (`get_interactive_elements`)\n\nRetrieves all interactive elements from the current page DOM.\n\n**Function Signature:**\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"Get interactive elements from the current page\",\n name=\"get_interactive_elements\"\n)\nasync def get_interactive_elements() -> Annotated[str, \"JSON string of interactive elements\"]\n```\n\n**DOM Processing Logic:**\n\nThe tool executes JavaScript in the browser context to identify interactive elements:\n\n```javascript\nconst isInteractive = (element) => {\n // Check input-related elements\n const inputRelatedTags = new Set(['input', 'textarea', 'select', ...]);\n const interactiveRoles = new Set(['button', 'link', 'checkbox', ...]);\n \n // Check for ARIA attributes\n const hasAriaProps = element.hasAttribute('aria-haspopup') ||\n element.hasAttribute('aria-expanded') ||\n element.hasAttribute('aria-checked');\n \n // Check cursor style\n const style = window.getComputedStyle(element);\n const hasPointerCursor = style.cursor === 'pointer';\n \n // Check draggable attribute\n const isDraggable = element.draggable;\n \n // Skip body and its direct children\n if (element.tagName.toLowerCase() === 'body') return false;\n \n return hasAriaProps || hasClickHandler || isDraggable;\n};\n```\n\n资料来源：[testzeus_hercules/core/tools/get_interactive_elements.py:1-50]()\n\n### Upload File Tool (`upload_file`)\n\nHandles file upload dialogs by setting file paths on input elements.\n\n**Function Signature:**\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"Upload a file to the page\",\n name=\"upload_file\"\n)\nasync def upload_file(\n selector: Annotated[str, \"md attribute value of file input element\"],\n file_path: Annotated[str, \"Path to the file to upload\"],\n) -> Annotated[Dict[str, str], \"Result of the upload operation\"]\n```\n\n## Extra Tools System\n\n### Dynamic Tool Loading\n\nThe extra tools are loaded dynamically at runtime using Python's `pkgutil` module. This allows the system to extend functionality without modifying core code.\n\n**Loading Mechanism:**\n\n```python\n# testzeus_hercules/core/extra_tools/__init__.py\nimport importlib\nimport pkgutil\nfrom pathlib import Path\n\nfrom testzeus_hercules.config import get_global_conf\n\npackage_path = Path(__file__).parent\n\nif get_global_conf().get_load_extra_tools().lower().strip() != \"false\":\n for _, module_name, _ in pkgutil.iter_modules([str(package_path)]):\n full_module_name = f\"testzeus_hercules.core.extra_tools.{module_name}\"\n module = importlib.import_module(full_module_name)\n \n # Export all public attributes to current namespace\n for attribute_name in dir(module):\n if not attribute_name.startswith(\"_\"):\n globals()[attribute_name] = getattr(module, attribute_name)\n```\n\n**Configuration:**\n\nExtra tools can be disabled via configuration:\n\n```bash\npython -m testzeus_hercules --load-extra-tools=false\n```\n\n资料来源：[testzeus_hercules/core/extra_tools/__init__.py:1-25]()\n\n### Accessibility Calls (`accessibility_calls`)\n\nProvides accessibility testing using the axe-core library.\n\n**Function Signature:**\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"Check page accessibility using axe-core\",\n name=\"check_accessibility\"\n)\nasync def check_accessibility(page_path: Annotated[str, \"Page path or URL\"]) -> str\n```\n\n**Execution Flow:**\n\n1. Fetches axe-core script from CDN\n2. Injects script into page\n3. Runs `axe.run()` in browser context\n4. Collects violations and incomplete checks\n5. Logs results in structured format\n\n```javascript\n// Inject axe-core\nawait page.evaluate(\n `fetch(\"${AXE_SCRIPT_URL}\").then(res => res.text())`\n);\n\n// Run accessibility checks\nconst results = await page.evaluate(\"async () => { return await axe.run(); }\");\n```\n\n**Response Format:**\n\n```json\n{\n \"status\": \"success|failure\",\n \"message\": \"Human readable summary\",\n \"details\": [\"failure summary 1\", \"failure summary 2\"]\n}\n```\n\n资料来源：[testzeus_hercules/core/tools/accessibility_calls.py:1-80]()\n\n## Tool Return Format\n\nAll tools return a standardized dictionary structure:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `summary_message` | `str` | Brief status message for agent consumption |\n| `detailed_message` | `str` | Extended information including errors if any |\n| `status` | `str` | Operation status (success/failure) |\n\n**Success Response Example:**\n\n```python\nreturn {\n \"summary_message\": f'Successfully clicked element with selector: \"{selector}\"',\n \"detailed_message\": f'Element with selector: \"{selector}\" clicked successfully. Tag: {element_tag_name}',\n}\n```\n\n**Error Response Example:**\n\n```python\nreturn {\n \"summary_message\": f'Element with selector: \"{selector}\" is not visible, Try another element',\n \"detailed_message\": f'Element with selector: \"{selector}\" is not visible, Try another element',\n}\n```\n\n## Selector Logging System\n\nEvery tool interaction is logged using the `SelectorLogger` for proof generation and debugging.\n\n### Logging Interface\n\n```python\nfrom testzeus_hercules.utils.browser_logger import get_browser_logger\n\nselector_logger = get_browser_logger(get_global_conf().get_proof_path())\n\n# Log successful interaction\nawait selector_logger.log_selector_interaction(\n tool_name=\"click\",\n selector=selector,\n action=\"left\",\n selector_type=\"css\",\n success=True,\n)\n\n# Log failed interaction\nawait selector_logger.log_selector_interaction(\n tool_name=\"click\",\n selector=selector,\n action=\"left\",\n selector_type=\"css\",\n success=False,\n error_message=\"Element not found\",\n)\n```\n\n### Captured Data\n\nThe logger captures:\n- Tool name and action type\n- Selector used\n- Selector type (CSS vs custom)\n- Success/failure status\n- Alternative selectors for the element\n- Element attributes\n- Error messages on failure\n\n## Agent Integration\n\n### Browser Nav Agent\n\nThe primary agent that consumes browser tools. It receives natural language instructions and translates them into tool calls.\n\n**Tool Invocation Pattern:**\n\n```python\n# From executor_nav_agent.py\nasync def execute_task(self, instruction: str):\n # Agent decides which tool to call\n # Tool receives selector from instruction\n result = await click_using_selector(\n selector=\"[md='submit-button']\",\n click_type=\"left\"\n )\n \n # Agent processes result\n if \"error\" in result.get(\"summary_message\", \"\").lower():\n # Handle error or try alternative\n```\n\n### Executor Nav Agent\n\nHandles script execution and Python sandbox operations:\n\n**Script Execution Context:**\n\n| Variable | Type | Description |\n|----------|------|-------------|\n| `page` | `Page` | Playwright page object |\n| `browser` | `Browser` | Playwright browser instance |\n| `context` | `BrowserContext` | Browser context |\n| `playwright_manager` | `PlaywrightManager` | Manager instance |\n| `logger` | `Logger` | Logging utility |\n| `config` | `GlobalConf` | Global configuration |\n\n资料来源：[testzeus_hercules/core/agents/executor_nav_agent.py:1-50]()\n\n## Bulk Operations\n\nThe tool system supports bulk execution for batch operations:\n\n### Bulk Slider Tool\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\"],\n description=\"used to set slider values in multiple sliders in single attempt.\",\n name=\"bulk_set_slider\"\n)\nasync def bulk_set_slider(\n entries: Annotated[\n List[List[str]],\n \"List of [selector, value] pairs\",\n ],\n) -> Annotated[List[Dict[str, str]], \"List of results\"]\n```\n\n## Configuration\n\n### Command Line Arguments\n\nThe tool system behavior can be configured via CLI:\n\n| Argument | Type | Description |\n|----------|------|-------------|\n| `--llm-model` | `str` | LLM model for agent decisions |\n| `--llm-temperature` | `float` | LLM sampling temperature (0.0-1.0) |\n| `--agents-llm-config-file` | `str` | Path to agents LLM config file |\n| `--enable-portkey` | `flag` | Enable Portkey LLM routing |\n| `--portkey-api-key` | `str` | Portkey API key |\n| `--browser-channel` | `str` | Browser channel (chrome-beta, etc.) |\n| `--browser-version` | `str` | Specific browser version |\n| `--enable-ublock` | `flag` | Enable uBlock Origin extension |\n| `--load-extra-tools` | `str` | Load extra tools (default: true) |\n\n资料来源：[testzeus_hercules/config.py:1-100]()\n\n## Summary\n\nThe Tool System provides:\n\n1. **Unified Interface**: All browser interactions follow the `@tool` decorator pattern\n2. **Agent Compatibility**: Tools specify which agents can invoke them\n3. **Error Resilience**: Graceful handling of element not found, not visible, and execution failures\n4. **Proof Generation**: Comprehensive logging of all selector interactions\n5. **Extensibility**: Dynamic loading of extra tools without core modifications\n6. **Standardized Results**: Consistent return format across all tools\n\nThis architecture enables AI agents to reliably control browser automation while maintaining clean separation of concerns and testable component boundaries.\n\n---\n\n\n\n## LLM Configuration\n\n### 相关页面\n\n相关主题：[Agent System](#agent-system), [Memory Management](#memory-management)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [testzeus_hercules/core/agents_llm_config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents_llm_config.py)\n- [agents_llm_config-example.json](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/agents_llm_config-example.json)\n- [testzeus_hercules/utils/llm_helper.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/llm_helper.py)\n- [testzeus_hercules/utils/model_utils.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/model_utils.py)\n- [docs/GPT5_USAGE.md](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/docs/GPT5_USAGE.md)\n\n\n# LLM Configuration\n\n## Overview\n\nThe LLM Configuration system in testzeus-hercules provides a flexible, multi-provider framework for configuring Large Language Models across different agent types. This system enables the framework to support various LLM providers (OpenAI, Anthropic, Ollama, Azure) while maintaining provider-specific configurations through a centralized registry mechanism.\n\nThe configuration architecture supports:\n- Multiple LLM providers simultaneously\n- Per-agent model selection\n- Dynamic parameter adaptation based on model family\n- External configuration file loading\n- Environment variable integration\n\n资料来源：[testzeus_hercules/core/agents_llm_config.py:1-20]()\n\n## Architecture\n\n### High-Level Component Architecture\n\n```mermaid\ngraph TD\n A[CLI Arguments / Environment] --> B[Global Config]\n C[agents-llm-config-file.json] --> D[AgentsLLMConfig]\n D --> E[AgentRegistry]\n E --> F[Provider Configs]\n F --> G[planner_agent]\n F --> H[nav_agent]\n F --> I[mem_agent]\n F --> J[helper_agent]\n B --> K[Model Utils]\n K --> L[adapt_llm_params_for_model]\n L --> G\n L --> H\n L --> I\n L --> J\n```\n\n### Configuration Flow\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI Arguments\n participant Config as Global Config\n participant JSON as LLM Config File\n participant Processor as AgentsLLMConfig\n participant Registry as AgentRegistry\n participant Agent as SimpleHercules\n \n CLI->>Config: Parse --llm-* arguments\n JSON->>Processor: load_from_file()\n Processor->>Registry: register_provider()\n Registry->>Registry: Store configs per provider\n Config->>Agent: Pass model configs\n Agent->>ModelUtils: adapt_llm_params_for_model()\n ModelUtils->>Agent: Adapted LLM params\n```\n\n资料来源：[testzeus_hercules/core/agents_llm_config.py:25-50]()\n\n## Core Components\n\n### AgentRegistry\n\nThe `AgentRegistry` manages configurations for multiple providers and supports switching between them.\n\n```python\nclass AgentRegistry:\n def __init__(self) -> None:\n self._providers: Dict[str, Dict[str, AgentConfig]] = {}\n self._active_provider: Optional[str] = None\n```\n\n| Method | Purpose |\n|--------|---------|\n| `register_provider(provider_key, configs)` | Register agent configs for a provider |\n| `get_active_provider()` | Retrieve currently active provider configuration |\n| `set_active_provider(provider_key)` | Switch active provider |\n| `get_all_providers()` | List all registered providers |\n\n资料来源：[testzeus_hercules/core/agents_llm_config.py:20-35]()\n\n### AgentsLLMConfig\n\nThe main configuration processor that handles loading and normalization of agent configurations.\n\n```python\nclass AgentsLLMConfig:\n def __init__(self) -> None:\n self.registry = AgentRegistry()\n \n def load_from_file(self, file_path: str, provider_key: Optional[str] = None) -> None\n def normalize_agent_config(self, agent_config: Dict[str, Any]) -> AgentConfig\n```\n\n资料来源：[testzeus_hercules/core/agents_llm_config.py:40-70]()\n\n## Agent Types\n\nThe framework defines four specialized agent roles, each with configurable LLM parameters:\n\n| Agent Type | Purpose | Typical Model Requirements |\n|------------|---------|----------------------------|\n| `planner_agent` | Strategic task planning and decomposition | High reasoning capability |\n| `nav_agent` | Browser navigation and UI interaction | Vision-capable, fast response |\n| `mem_agent` | Memory and context management | Balanced performance |\n| `helper_agent` | Utility functions and data processing | Variable based on task |\n\n资料来源：[testzeus_hercules/core/simple_hercules.py:1-30]()\n\n## Configuration File Format\n\n### JSON Schema Structure\n\n```json\n{\n \"provider_name\": {\n \"agent_type\": {\n \"model_name\": \"string\",\n \"model_api_key\": \"string\",\n \"model_api_type\": \"openai|anthropic|azure|ollama\",\n \"model_client_host\": \"string (optional)\",\n \"model_native_tool_calls\": true|false,\n \"model_hide_tools\": \"if_any_run|user|never\",\n \"llm_config_params\": {\n \"cache_seed\": null|integer,\n \"temperature\": 0.0,\n \"seed\": 12345,\n \"max_tokens\": 4096,\n \"presence_penalty\": 0.0,\n \"frequency_penalty\": 0.0,\n \"stop\": []\n }\n }\n }\n}\n```\n\n### Example Configuration\n\n```json\n{\n \"openai\": {\n \"planner_agent\": {\n \"model_name\": \"gpt-4o\",\n \"model_api_key\": \"${OPENAI_API_KEY}\",\n \"model_api_type\": \"openai\",\n \"llm_config_params\": {\n \"cache_seed\": null,\n \"temperature\": 0.0,\n \"seed\": 12345\n }\n }\n },\n \"anthropic\": {\n \"nav_agent\": {\n \"model_name\": \"claude-3-5-haiku-latest\",\n \"model_api_key\": \"\",\n \"model_api_type\": \"anthropic\",\n \"llm_config_params\": {\n \"cache_seed\": null,\n \"temperature\": 0.0\n }\n }\n }\n}\n```\n\n资料来源：[agents_llm_config-example.json:1-60]()\n\n## CLI Configuration Options\n\nThe framework provides comprehensive command-line arguments for LLM configuration:\n\n### Basic LLM Parameters\n\n| Argument | Type | Description |\n|----------|------|-------------|\n| `--llm-model` | string | Name of the LLM model |\n| `--llm-model-api-key` | string | API key for the LLM model |\n| `--llm-model-base-url` | string | Base URL for the LLM API |\n| `--llm-model-api-type` | string | API type (openai, anthropic, azure, etc.) |\n| `--llm-temperature` | float | Temperature for LLM sampling (0.0-1.0) |\n\n### LLM Configuration File Options\n\n| Argument | Type | Description |\n|----------|------|-------------|\n| `--agents-llm-config-file` | string | Path to the agents LLM configuration file |\n| `--agents-llm-config-file-ref-key` | string | Reference key for selecting provider |\n\n### Parameter Configuration\n\n| Argument | Type | Description |\n|----------|------|-------------|\n| `LLM_MODEL_PRICING` | env | Model pricing for cost tracking |\n| `LLM_MODEL_TEMPERATURE` | env | Default temperature setting |\n| `LLM_MODEL_CACHE_SEED` | env | Cache seed for reproducible results |\n| `LLM_MODEL_SEED` | env | Random seed for generation |\n| `LLM_MODEL_MAX_TOKENS` | env | Maximum tokens in response |\n| `LLM_MODEL_PRESENCE_PENALTY` | env | Presence penalty (-2.0 to 2.0) |\n| `LLM_MODEL_FREQUENCY_PENALTY` | env | Frequency penalty (-2.0 to 2.0) |\n| `LLM_MODEL_STOP` | env | Stop sequences |\n\n资料来源：[testzeus_hercules/config.py:1-100]()\n\n## Portkey Integration\n\nThe framework supports Portkey for advanced LLM routing with fallback and load balancing capabilities.\n\n### Portkey Configuration Options\n\n| Argument | Type | Description |\n|----------|------|-------------|\n| `--enable-portkey` | flag | Enable Portkey integration |\n| `--portkey-api-key` | string | API key for Portkey |\n| `--portkey-strategy` | choice | Routing strategy: `fallback` or `loadbalance` |\n\n### Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `ENABLE_PORTKEY` | Enable/disable Portkey |\n| `PORTKEY_API_KEY` | Portkey API key |\n| `PORTKEY_STRATEGY` | Routing strategy |\n| `PORTKEY_CACHE_ENABLED` | Enable response caching |\n| `PORTKEY_TARGETS` | Target models for routing |\n| `PORTKEY_GUARDRAILS` | Enable safety guardrails |\n| `PORTKEY_RETRY_COUNT` | Number of retries on failure |\n\n资料来源：[testzeus_hercules/config.py:50-80]()\n\n## Model Parameter Adaptation\n\nThe `model_utils` module provides intelligent parameter adaptation based on the model family being used.\n\n### adapt_llm_params_for_model\n\n```python\ndef adapt_llm_params_for_model(model_name: str, llm_config_params: Dict) -> Dict\n```\n\nThis function automatically adjusts LLM parameters based on the detected model family:\n\n| Model Family | Adaptation Behavior |\n|--------------|---------------------|\n| o1-series | Removes temperature, adjusts max_tokens handling |\n| GPT-4o | Standard parameters |\n| Claude | Adjusts for Anthropic API format |\n| Ollama | Configures for local inference |\n\n### Applied to All Agents\n\n```python\n# In SimpleHercules initialization\nplanner_model = self.planner_agent_config[\"model_config_params\"].get(\"model\") or \\\n self.planner_agent_config[\"model_config_params\"].get(\"model_name\")\n\nself.planner_agent_config[\"llm_config_params\"] = adapt_llm_params_for_model(\n planner_model, \n self.planner_agent_config[\"llm_config_params\"]\n)\n```\n\n资料来源：[testzeus_hercules/core/simple_hercules.py:100-130]()\n\n## LLM Helper Utilities\n\nThe `llm_helper` module provides utility functions for LLM interactions:\n\n| Function | Purpose |\n|----------|---------|\n| `convert_model_config_to_autogen_format()` | Convert config to AutoGen format |\n| `create_multimodal_agent()` | Create agents with vision capabilities |\n| `extract_target_helper()` | Extract target information from responses |\n| `format_plan_steps()` | Format planning step outputs |\n| `parse_agent_response()` | Parse agent response structure |\n| `process_chat_message_content()` | Process chat message content |\n| `parse_response()` | General response parsing |\n\n资料来源：[testzeus_hercules/utils/llm_helper.py:1-30]()\n\n## Environment Variable Configuration\n\n### Full Configuration Matrix\n\n| Environment Variable | Type | Default | Purpose |\n|---------------------|------|---------|---------|\n| `LLM_MODEL_PRICING` | dict | - | Model pricing information |\n| `LLM_MODEL_TEMPERATURE` | float | 0.0 | Default sampling temperature |\n| `LLM_MODEL_CACHE_SEED` | int | null | Caching seed |\n| `LLM_MODEL_SEED` | int | - | Random seed |\n| `LLM_MODEL_MAX_TOKENS` | int | 4096 | Max response tokens |\n| `LLM_MODEL_PRESENCE_PENALTY` | float | 0.0 | Presence penalty |\n| `LLM_MODEL_FREQUENCY_PENALTY` | float | 0.0 | Frequency penalty |\n| `LLM_MODEL_STOP` | list | [] | Stop sequences |\n| `TOKEN_VERBOSE` | bool | false | Enable token verbose logging |\n| `HF_HOME` | path | - | HuggingFace cache location |\n| `TOKENIZERS_PARALLELISM` | bool | false | Parallel tokenizer config |\n\n资料来源：[testzeus_hercules/config.py:100-150]()\n\n## Multi-Provider Configuration\n\n### Provider Switching\n\nThe system supports runtime provider switching through the configuration file:\n\n```mermaid\ngraph LR\n A[Config File] --> B[\"provider: openai\"]\n A --> C[\"provider: anthropic\"]\n B --> D[\"planner_agent: GPT-4\"]\n B --> E[\"nav_agent: GPT-4o-mini\"]\n C --> F[\"planner_agent: Claude-3\"]\n C --> G[\"nav_agent: Claude-3-Haiku\"]\n```\n\n### Selecting Active Provider\n\n```bash\npython -m testzeus_hercules \\\n --agents-llm-config-file ./config.json \\\n --agents-llm-config-file-ref-key \"anthropic\"\n```\n\n资料来源：[testzeus_hercules/core/agents_llm_config.py:60-80]()\n\n## Integration with SimpleHercules\n\nThe `SimpleHercules` class integrates all LLM configurations:\n\n```python\nclass SimpleHercules:\n def __init__(\n self,\n planner_agent_config: Dict[str, Any],\n nav_agent_config: Dict[str, Any],\n mem_agent_config: Dict[str, Any],\n helper_agent_config: Dict[str, Any],\n planner_max_chat_round: int = 50,\n browser_nav_max_chat_round: int = 100,\n ):\n # Configuration processing\n self.planner_agent_config = planner_agent_config\n self.nav_agent_config = nav_agent_config\n self.mem_agent_config = mem_agent_config\n self.helper_agent_config = helper_agent_config\n \n # Parameter adaptation per agent\n from testzeus_hercules.utils.model_utils import adapt_llm_params_for_model\n \n self.planner_agent_config[\"llm_config_params\"] = adapt_llm_params_for_model(\n planner_model, \n self.planner_agent_config[\"llm_config_params\"]\n )\n```\n\n资料来源：[testzeus_hercules/core/simple_hercules.py:50-100]()\n\n## Best Practices\n\n### 1. Configuration File Organization\n\n- Group configurations by provider (openai, anthropic, etc.)\n- Use environment variables for sensitive API keys\n- Maintain consistent agent naming across providers\n\n### 2. Model Selection Guidelines\n\n| Use Case | Recommended Models |\n|----------|-------------------|\n| Complex planning | GPT-4, Claude-3-Opus |\n| Fast navigation | GPT-4o-mini, Claude-3-Haiku |\n| Vision tasks | GPT-4o, Claude-3-Sonnet |\n| Local inference | Ollama models |\n\n### 3. Parameter Tuning\n\n- Use `temperature: 0.0` for deterministic outputs\n- Set appropriate `max_tokens` based on expected response length\n- Enable `model_native_tool_calls` for better function calling\n\n### 4. Cost Optimization\n\n- Use `LLM_MODEL_PRICING` for tracking\n- Enable Portkey caching with `PORTKEY_CACHE_ENABLED`\n- Consider fallback strategies for reliability\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| Model not recognized | Check `model_name` matches provider format |\n| Temperature ignored | Some models (o1-series) ignore temperature parameter |\n| API key errors | Ensure `${ENV_VAR}` syntax or actual key in config |\n| Provider not found | Verify provider key matches config file structure |\n\n### Debug Configuration\n\n```bash\nexport TOKEN_VERBOSE=true\nexport ENABLE_BROWSER_LOGS=true\npython -m testzeus_hercules --llm-model gpt-4o --llm-temperature 0.7\n```\n\n## See Also\n\n- [GPT-5 Usage Guide](../docs/GPT5_USAGE.md)\n- [Browser Configuration](./browser-configuration.md)\n- [Agent Architecture](./agent-architecture.md)\n\n---\n\n\n\n## Memory Management\n\n### 相关页面\n\n相关主题：[Agent System](#agent-system), [LLM Configuration](#llm-configuration)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [testzeus_hercules/core/memory/state_handler.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/state_handler.py)\n- [testzeus_hercules/core/memory/dynamic_ltm.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/dynamic_ltm.py)\n- [testzeus_hercules/core/memory/static_ltm.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/memory/static_ltm.py)\n\n\n# Memory Management\n\n## Overview\n\nThe Memory Management system in testzeus-hercules provides persistent and contextual memory capabilities for AI agents executing browser automation tests. The system consists of three primary components: **Static LTM** (Long Term Memory), **Dynamic LTM**, and **State Handler**, each serving distinct purposes in managing test execution context and data persistence.\n\nThe architecture follows a multi-layered approach where Static LTM loads pre-configured test data, Dynamic LTM manages vector-based retrieval augmented memory, and State Handler provides runtime state tracking for agent coordination.\n\n```mermaid\ngraph TD\n A[Testzeus-Hercules] --> B[Static LTM]\n A --> C[Dynamic LTM]\n A --> D[State Handler]\n \n B --> E[Test Data Files]\n B --> F[Stored Data]\n B --> G[Run Data]\n \n C --> H[Vector Store]\n C --> I[RetrieveUserProxyAgent]\n \n D --> J[_state_string]\n D --> K[_state_dict]\n \n L[Agents] --> M[Memory Access]\n M --> B\n M --> C\n M --> D\n```\n\n## Static LTM (Long Term Memory)\n\n### Purpose and Scope\n\nStatic LTM is responsible for loading and consolidating pre-configured test data at application initialization. It operates as a singleton pattern, ensuring that all test data is loaded once and made available throughout the test execution lifecycle.\n\n资料来源：[testzeus_hercules/core/memory/static_ltm.py:1-47]()\n\n### Implementation\n\nThe `StaticLTM` class extends the singleton pattern to ensure only one instance exists:\n\n```python\nclass StaticLTM:\n _instance = None\n\n def __new__(cls) -> \"StaticLTM\":\n if cls._instance is None:\n cls._instance = super().__new__(cls)\n cls._instance._initialize()\n return cls._instance\n```\n\n资料来源：[testzeus_hercules/core/memory/static_ltm.py:17-22]()\n\n### Data Consolidation\n\nDuring initialization, Static LTM consolidates three types of data sources:\n\n| Data Source | Description | Method |\n|-------------|-------------|--------|\n| Base Test Data | Loaded from `test_data.txt` via `load_data()` | `StaticDataLoader` |\n| Stored Data | User-defined test artifacts | `get_stored_data()` |\n| Run Data | Previous test execution context | `get_run_data()` |\n\n资料来源：[testzeus_hercules/core/memory/static_ltm.py:26-34]()\n\nThe consolidated data is stored in `self.consolidated_data` and accessed via `get_user_ltm()`:\n\n```python\ndef get_user_ltm(self) -> Optional[str]:\n return self.consolidated_data\n```\n\n资料来源：[testzeus_hercules/core/memory/static_ltm.py:40-47]()\n\n### Usage Pattern\n\nAgents access Static LTM through a module-level function:\n\n```python\ndef get_user_ltm() -> Optional[str]:\n return StaticLTM().get_user_ltm()\n```\n\n资料来源：[testzeus_hercules/core/memory/static_ltm.py:50-54]()\n\n## Dynamic LTM\n\n### Purpose and Scope\n\nDynamic LTM provides runtime memory management with vector-based retrieval capabilities. It enables agents to store, retrieve, and utilize contextual information during test execution using a `RetrieveUserProxyAgent` backed by ChromaDB for vector storage.\n\n资料来源：[testzeus_hercules/core/memory/dynamic_ltm.py:1-40]()\n\n### Core Components\n\n#### SilentRetrieveUserProxyAgent\n\nA specialized agent that extends `RetrieveUserProxyAgent` with suppressed output to prevent console noise during agent conversations:\n\n```python\nclass SilentRetrieveUserProxyAgent(RetrieveUserProxyAgent):\n @suppress_prints\n def initiate_chat(self, *args: Any, **kwargs: Any) -> Any:\n return super().initiate_chat(*args, **kwargs)\n\n @suppress_prints\n async def a_initiate_chat(self, *args: Any, **kwargs: Any) -> Any:\n return await super().a_initiate_chat(*args, **kwargs)\n```\n\n资料来源：[testzeus_hercules/core/memory/dynamic_ltm.py:37-46]()\n\n#### Print Suppression Decorator\n\nThe `@suppress_prints` decorator redirects stdout to a `StringIO` buffer during function execution:\n\n```python\ndef suppress_prints(func):\n @functools.wraps(func)\n def wrapper(*args, **kwargs):\n silent_stdout = io.StringIO()\n original_stdout, sys.stdout = sys.stdout, silent_stdout\n try:\n return func(*args, **kwargs)\n finally:\n sys.stdout = original_stdout\n return wrapper\n```\n\n资料来源：[testzeus_hercules/core/memory/dynamic_ltm.py:17-29]()\n\n### Integration with Configuration\n\nDynamic LTM respects global configuration to enable or disable its functionality:\n\n```python\nfrom testzeus_hercules.config import get_global_conf\n\ndef save_content(self, content: str) -> None:\n config = get_global_conf()\n if not config.should_use_dynamic_ltm():\n return # Skip when disabled\n```\n\n资料来源：[testzeus_hercules/core/simple_hercules.py:89-94]()\n\n### External Dependencies\n\nDynamic LTM utilizes the `unstructured` library for document parsing:\n\n```python\nfrom unstructured.documents.elements import NarrativeText, Text, Title\nfrom unstructured.partition.auto import partition\n```\n\n资料来源：[testzeus_hercules/core/memory/dynamic_ltm.py:13-14]()\n\n## State Handler\n\n### Purpose and Scope\n\nState Handler provides lightweight runtime state management for coordinating data between agents during test execution. It maintains module-level dictionaries for storing string-based state and structured data.\n\n资料来源：[testzeus_hercules/core/memory/state_handler.py:1-70]()\n\n### Module-Level State Storage\n\n```python\n# Module-level state string\n_state_string: Dict[str, str] = defaultdict(str)\n_state_dict: Dict[str, Any] = defaultdict(deque)\n```\n\n资料来源：[testzeus_hercules/core/memory/state_handler.py:13-14]()\n\n### store_data Tool\n\nThe `store_data` function is registered as a tool for browser, API, and SQL navigation agents to persist information:\n\n```python\n@tool(\n agent_names=[\"browser_nav_agent\", \"api_nav_agent\", \"sql_nav_agent\"],\n description=\"Tool to store information.\",\n name=\"store_data\",\n)\ndef store_data(\n text: Annotated[str, \"The confirmation of stored value.\"],\n) -> Annotated[Dict[str, Union[str, None]], \"A dictionary containing a 'message' key...\"]:\n global _state_string\n try:\n DynamicLTM().save_content(text)\n _state_string[get_global_conf().get_default_test_id()] += text\n return {\"message\": \"Text appended successfully.\"}\n except Exception as e:\n return {\"error\": str(e)}\n```\n\n资料来源：[testzeus_hercules/core/memory/state_handler.py:23-47]()\n\n### Key Behaviors\n\n| Behavior | Description |\n|----------|-------------|\n| Test ID Isolation | State is keyed by `get_global_conf().get_default_test_id()` |\n| Dual Storage | Data propagates to both `_state_string` and Dynamic LTM |\n| Error Resilience | Returns error dictionary instead of raising exceptions |\n\n资料来源：[testzeus_hercules/core/memory/state_handler.py:30-46]()\n\n## Memory Architecture Diagram\n\n```mermaid\ngraph LR\n subgraph \"Initialization Phase\"\n A[Load Config] --> B[StaticLTM Singleton]\n B --> C[Load test_data.txt]\n C --> D[Consolidate Data]\n end\n \n subgraph \"Runtime Phase\"\n E[Agents Execute Tests]\n E --> F[store_data Tool Call]\n F --> G[State Handler]\n G --> H[DynamicLTM.save_content]\n H --> I[Vector Store Update]\n \n J[Test Query] --> K[RetrieveUserProxyAgent]\n K --> L[Vector Similarity Search]\n L --> M[Context Injection]\n M --> E\n end\n```\n\n## Integration with SimpleHercules\n\nThe `SimpleHercules` class coordinates all memory components:\n\n```python\nclass SimpleHercules:\n def _save_to_memory(self, content: str) -> None:\n \"\"\"Helper method to save content to memory.\"\"\"\n config = get_global_conf()\n if not config.should_use_dynamic_ltm():\n return\n\n if self.memory:\n self.memory.save_content(content)\n else:\n logger.warning(\"Memory system not initialized\")\n```\n\n资料来源：[testzeus_hercules/core/simple_hercules.py:85-97]()\n\n### Memory Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant SH as SimpleHercules\n participant DLT as DynamicLTM\n participant CFG as Config\n participant LOG as Logger\n\n SH->>CFG: should_use_dynamic_ltm()\n CFG-->>SH: boolean\n SH->>DLT: save_content(content)\n alt LTM Enabled\n DLT->>DLT: Vector store update\n DLT-->>SH: success\n else LTM Disabled\n DLT-->>SH: skipped\n end\n```\n\n## Configuration\n\n### Global Configuration Methods\n\n| Method | Purpose |\n|--------|---------|\n| `should_use_dynamic_ltm()` | Check if Dynamic LTM is enabled |\n| `get_hf_home()` | Get HuggingFace cache directory for vector store |\n| `get_default_test_id()` | Get current test execution identifier |\n\n### Related Configuration File\n\nThe configuration is managed through `testzeus_hercules/config.py`, which provides command-line arguments for memory-related settings including:\n\n- `--reuse-vector-db`: Reuse existing vector DB instead of creating fresh one\n- `--sandbox-tenant-id`: Python sandbox tenant configuration\n\n资料来源：[testzeus_hercules/config.py:45-58]()\n\n## Data Flow Summary\n\n| Layer | Storage Type | Access Pattern | Persistence |\n|-------|--------------|----------------|-------------|\n| Static LTM | In-memory string | Singleton `get_user_ltm()` | Session-scoped |\n| Dynamic LTM | Vector (ChromaDB) | RetrieveUserProxyAgent | Persistent |\n| State Handler | In-memory dict | Module-level `_state_string` | Test execution-scoped |\n\n## Error Handling\n\nAll memory components implement robust error handling:\n\n```python\ntry:\n DynamicLTM().save_content(text)\n _state_string[get_global_conf().get_default_test_id()] += text\n return {\"message\": \"Text appended successfully.\"}\nexcept Exception as e:\n traceback.print_exc()\n logger.error(f\"An error occurred while appending to state: {e}\")\n return {\"error\": str(e)}\n```\n\n资料来源：[testzeus_hercules/core/memory/state_handler.py:30-42]()\n\n## Related Components\n\n| Component | File Path | Role |\n|-----------|-----------|------|\n| PlannerAgent | `core/agents/high_level_planner_agent.py` | Consumes memory for test planning |\n| ExecutorNavAgent | `core/agents/executor_nav_agent.py` | Executes test steps with memory context |\n| BaseNavAgent | `core/agents/base_nav_agent.py` | Agent base class with memory integration |\n\n## Summary\n\nThe Memory Management system in testzeus-hercules implements a comprehensive multi-tier approach:\n\n1. **Static LTM** provides pre-loaded test data consolidation via singleton pattern\n2. **Dynamic LTM** offers vector-based retrieval augmented memory for contextual queries\n3. **State Handler** enables runtime state sharing between agents through the `store_data` tool\n\nThis architecture ensures agents have access to both static test fixtures and dynamic execution context, enabling sophisticated AI-driven browser automation testing.\n\n---\n\n\n\n## API Testing\n\n### 相关页面\n\n相关主题：[Security Testing](#security-testing), [Tool System](#tool-system)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [testzeus_hercules/core/tools/api_calls.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/api_calls.py)\n- [testzeus_hercules/core/tools/sql_calls.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/sql_calls.py)\n- [testzeus_hercules/core/agents/api_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/api_nav_agent.py)\n- [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)\n- [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)\n- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)\n- [testzeus_hercules/utils/response_parser.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/response_parser.py)\n\n\n# API Testing\n\n## Overview\n\nAPI Testing in testzeus-hercules enables automated end-to-end testing of REST APIs through AI-driven agents. The system leverages LLM-powered agents to parse OpenAPI specifications, generate Gherkin test scenarios, execute API calls, and validate responses against expected outcomes. This module integrates with the broader Hercules testing framework to provide comprehensive API validation capabilities alongside browser-based UI testing.\n\nThe API Testing feature accepts OpenAPI specification files (YAML or JSON format) and automatically generates executable Gherkin test cases that can be run against live API endpoints. The generated tests follow behavior-driven development (BDD) conventions, making them readable for both technical and non-technical stakeholders.\n\n## Architecture\n\nThe API Testing module consists of several interconnected components that work together to provide end-to-end API testing capabilities.\n\n### Component Overview\n\n```mermaid\ngraph TD\n A[OpenAPI Specification] --> B[generate_api_functional_gherkin_test.py]\n B --> C[Gherkin Test Cases]\n C --> D[API Navigation Agent]\n D --> E[API Calls Tool]\n E --> F[SQL Calls Tool]\n E --> G[Python Sandbox Executor]\n F --> H[Database Validation]\n G --> I[Custom Logic Validation]\n D --> J[Response Parser]\n J --> K[Test Results]\n```\n\n### Core Components\n\n| Component | File Path | Purpose |\n|-----------|-----------|---------|\n| API Navigation Agent | `testzeus_hercules/core/agents/api_nav_agent.py` | Orchestrates API test execution using LLM-driven decision making |\n| API Calls Tool | `testzeus_hercules/core/tools/api_calls.py` | Executes HTTP requests to API endpoints |\n| SQL Calls Tool | `testzeus_hercules/core/tools/sql_calls.py` | Validates API data against database state |\n| Python Sandbox | `testzeus_hercules/core/tools/execute_python_sandbox.py` | Executes custom validation logic |\n| Gherkin Generator | `helper_scripts/generate_api_functional_gherkin_test.py` | Generates test cases from OpenAPI specs |\n| Response Parser | `testzeus_hercules/utils/response_parser.py` | Parses and validates API responses |\n\n资料来源：[helper_scripts/generate_api_functional_gherkin_test.py:1-80]()\n\n## Test Generation Workflow\n\n### OpenAPI Specification Processing\n\nThe test generation process begins with parsing OpenAPI specification files. The system accepts both YAML and JSON formatted OpenAPI specs through the `generate_api_functional_gherkin_test.py` helper script.\n\n```python\nparser.add_argument(\n \"input_files\",\n metavar=\"input_files\",\n type=str,\n nargs=\"+\",\n help=\"One or more OpenAPI spec files (YAML or JSON).\",\n)\n```\n\n资料来源：[helper_scripts/generate_api_functional_gherkin_test.py:15-22]()\n\n### Gherkin Test Case Generation\n\nThe LLM generates test cases based on the OpenAPI specification content. The generation uses a specialized prompt that instructs the model to produce Gherkin-format scenarios covering functional test cases.\n\n```python\ndef generate_test_cases(prompt: str, model: str) -> str:\n \"\"\"Generates test cases using the OpenAI API.\"\"\"\n client = OpenAI()\n completion = client.chat.completions.create(\n model=model,\n messages=[{\"role\": \"user\", \"content\": prompt}],\n temperature=0.7,\n )\n return completion.choices[0].message.content\n```\n\n资料来源：[helper_scripts/generate_api_functional_gherkin_test.py:82-90]()\n\n### Generation Parameters\n\n| Parameter | CLI Flag | Default | Description |\n|-----------|----------|---------|-------------|\n| Model | `--model` | o1-preview | LLM model for test generation |\n| Output Folder | `--output` | (required) | Destination for generated feature files |\n| Number of Test Cases | `--number_of_testcase` | 100 | Maximum test cases to generate per endpoint |\n\n## API Navigation Agent\n\nThe API Navigation Agent (`api_nav_agent.py`) serves as the orchestrator for executing API tests. It receives parsed test scenarios and coordinates execution across multiple tools to validate API behavior.\n\n```mermaid\nsequenceDiagram\n participant Test as Test Scenario\n participant Agent as API Nav Agent\n participant API as API Calls Tool\n participant SQL as SQL Calls Tool\n participant Sandbox as Python Sandbox\n \n Test->>Agent: Execute scenario\n Agent->>API: Send HTTP request\n API-->>Agent: Response data\n Agent->>SQL: Validate database state\n SQL-->>Agent: Validation result\n Agent->>Sandbox: Run custom assertions\n Sandbox-->>Agent: Assertion results\n Agent->>Test: Pass/Fail outcome\n```\n\n资料来源：[testzeus_hercules/core/agents/api_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/api_nav_agent.py)\n\n## Execution Environment\n\n### Python Sandbox\n\nAPI tests execute within a secured Python sandbox environment that provides controlled access to necessary resources while maintaining isolation.\n\n```python\ndef _get_config_driven_injections(config: Any) -> Dict[str, Any]:\n \"\"\"\n Get injections defined in configuration.\n Allows dynamic configuration of available modules.\n \"\"\"\n injections = {}\n \n # Read from config: SANDBOX_PACKAGES=\"requests,pandas,numpy\"\n sandbox_packages = config.get_config().get(\"SANDBOX_PACKAGES\", \"\").split(\",\")\n \n for package_name in sandbox_packages:\n package_name = package_name.strip()\n if package_name:\n try:\n injections[package_name] = __import__(package_name)\n except ImportError:\n logger.warning(f\"Could not import configured package: {package_name}\")\n \n return injections\n```\n\n资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py:80-100]()\n\n### Sandbox Access Variables\n\nScripts executing within the sandbox have automatic access to the following variables:\n\n| Variable | Type | Description |\n|----------|------|-------------|\n| `page` | Playwright Page | Current browser page context |\n| `browser` | Browser instance | Active browser session |\n| `context` | Browser Context | Isolated browsing context |\n| `playwright_manager` | PlaywrightManager | Manages Playwright lifecycle |\n| `logger` | Logger | Logging utility |\n| `config` | Configuration | Global configuration object |\n\nAdditional tenant-specific modules can be injected based on the `SANDBOX_TENANT_ID` environment variable, and custom injections are available via the `SANDBOX_CUSTOM_INJECTIONS` environment variable.\n\n资料来源：[testzeus_hercules/core/tools/execute_python_sandbox.py:40-55]()\n\n## Response Handling\n\n### JSON Response Parsing\n\nThe response parser handles API responses with multiple fallback strategies for extracting structured data:\n\n```python\ndef parse_response(message: str) -> dict[str, Any]:\n # Check if message is wrapped in ```json ``` blocks\n if \"```json\" in message:\n start_idx = message.find(\"```json\") + 7\n end_idx = message.find(\"```\", start_idx + 7)\n message = message[start_idx:end_idx]\n else:\n if message.startswith(\"```\"):\n message = message[3:]\n if message.endswith(\"```):\n message = message[:-3]\n if message.startswith(\"json\"):\n message = message[4:]\n\n message = message.strip()\n message = message.replace(\"\\\\n\", \"\\n\")\n \n json_response: dict[str, Any] = json.loads(message)\n```\n\n资料来源：[testzeus_hercules/utils/response_parser.py:9-35]()\n\n### Error Recovery\n\nWhen JSON parsing fails, the response parser attempts to extract plan and next_step fields from unstructured responses, ensuring graceful degradation when APIs return non-standard response formats.\n\n## Configuration\n\n### LLM Configuration\n\nAPI Testing relies on LLM configuration for test generation and agent decision-making. Configuration can be provided via command-line arguments or through a dedicated configuration file.\n\n```python\nparser.add_argument(\n \"--llm-model\",\n type=str,\n help=\"Name of the LLM model.\",\n required=False,\n)\nparser.add_argument(\n \"--llm-temperature\",\n type=float,\n help=\"Temperature for LLM sampling (0.0-1.0).\",\n required=False,\n)\n```\n\n资料来源：[testzeus_hercules/config.py:35-45]()\n\n### Agents LLM Config File\n\nFor multi-agent configurations, specify the configuration file path:\n\n```bash\n--agents-llm-config-file /path/to/agents_llm_config.json\n--agents-llm-config-file-ref-key \n```\n\n### Portkey Integration\n\nEnable Portkey for LLM routing with fallback or load balancing strategies:\n\n```bash\n--enable-portkey\n--portkey-api-key \n--portkey-strategy fallback|loadbalance\n```\n\n资料来源：[testzeus_hercules/config.py:60-75]()\n\n## Usage Examples\n\n### Generate Gherkin Tests from OpenAPI Spec\n\n```bash\npython helper_scripts/generate_api_functional_gherkin_test.py \\\n spec/openapi.yaml \\\n --output tests/api/ \\\n --model gpt-4 \\\n --number_of_testcase 50\n```\n\n### Run API Tests\n\nTests can be executed through the main Hercules CLI or integrated into CI/CD pipelines. The agent configuration file supports specifying different models for different agents:\n\n```json\n{\n \"openai\": {\n \"planner_agent\": {\n \"model_name\": \"gpt-4\",\n \"model_api_type\": \"openai\"\n }\n }\n}\n```\n\n资料来源：[agents_llm_config-example.json](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/agents_llm_config-example.json)\n\n## Integration with Browser Testing\n\nThe API Testing module integrates seamlessly with browser-based testing capabilities. The API Navigation Agent can coordinate with the Browser Navigation Agent to perform scenarios that span both API validation and UI verification.\n\nWhen executing multi-step workflows, the system can:\n1. Call API endpoints to set up test data\n2. Launch browsers to verify UI state reflects API changes\n3. Execute SQL queries to validate data persistence\n4. Run custom Python assertions for complex business logic\n\n## Security Considerations\n\n### API Key Management\n\nAPI keys should be provided through environment variables or secure configuration management, never hardcoded in test files:\n\n```bash\nexport OPENAI_API_KEY=\nexport PORTKEY_API_KEY=\n```\n\n### Sandbox Isolation\n\nThe Python sandbox provides execution isolation for custom test logic. Configure allowed packages through the `SANDBOX_PACKAGES` configuration parameter to limit access to only required libraries.\n\n## Best Practices\n\n1. **Organize OpenAPI specs by version** - Maintain separate specification files for different API versions\n2. **Use meaningful test case names** - Generated tests should clearly describe the scenario being validated\n3. **Combine with database validation** - Use SQL Calls Tool to verify data consistency\n4. **Leverage response parsing** - Use the response parser for handling complex API response formats\n5. **Configure appropriate LLM models** - Use faster models for generation and more capable models for complex validation logic\n\n## Related Documentation\n\n- [CONTRIBUTING.md](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/CONTRIBUTING.md) - Contribution guidelines for the project\n- [Makefile](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/Makefile) - Build and test automation targets\n- [Browser Testing](https://github.com/test-zeus-ai/testzeus-hercules) - Companion documentation for UI testing\n\n---\n\n\n\n## Security Testing\n\n### 相关页面\n\n相关主题：[API Testing](#api-testing), [Tool System](#tool-system)\n\n\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [testzeus_hercules/core/agents/sec_nav_agent.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/sec_nav_agent.py)\n- [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)\n\n\n# Security Testing\n\nSecurity Testing in TestZeus Hercules is an automated framework designed to validate API security by generating and executing Gherkin-based test scenarios. The system leverages LLM-powered agents to analyze OpenAPI specifications and produce comprehensive security validation tests that check for vulnerabilities, configuration weaknesses, and proper handling of sensitive data.\n\n## Overview\n\nThe Security Testing module provides an end-to-end solution for validating API security without requiring manual test case authoring. It integrates with the broader Hercules testing framework to execute security validation scenarios alongside functional and navigation tests.\n\n### Core Components\n\n| Component | File Path | Purpose |\n|-----------|-----------|---------|\n| Security Navigation Agent | `testzeus_hercules/core/agents/sec_nav_agent.py` | Orchestrates security test execution using LLM-driven agents |\n| API Security Calls | `testzeus_hercules/core/tools/api_sec_calls.py` | Provides low-level HTTP client operations for security validation |\n| Gherkin Test Generator | `helper_scripts/generate_api_security_gherkin_test.py` | Generates security-focused Gherkin test cases from OpenAPI specs |\n\n## Architecture\n\n```mermaid\ngraph TD\n A[OpenAPI Spec Files] --> B[generate_api_security_gherkin_test.py]\n B --> C[LLM API - OpenAI]\n C --> D[Security Gherkin Test Cases]\n D --> E[Hercules Test Executor]\n E --> F[sec_nav_agent.py]\n F --> G[api_sec_calls.py]\n G --> H[Target API Endpoints]\n H --> I[Security Validation Results]\n \n J[Configuration] --> F\n K[LLM Config] --> B\n```\n\n## Security Navigation Agent\n\nThe `sec_nav_agent.py` module implements the `BrowserNavAgent` pattern specialized for security testing scenarios. It follows the same agent architecture used by the browser navigation agent but focuses on API security validation.\n\n### Agent Configuration\n\nThe security agent inherits the core agent configuration structure from the Hercules framework, utilizing the same LLM integration patterns as the main navigation agent defined in `simple_hercules.py`. 资料来源：[testzeus_hercules/core/agents/sec_nav_agent.py:1-50]()\n\n### Execution Flow\n\n```mermaid\nsequenceDiagram\n participant TestRunner\n participant SecNavAgent\n participant APISecCalls\n participant TargetAPI\n participant ResponseParser\n \n TestRunner->>SecNavAgent: Execute security test scenario\n SecNavAgent->>APISecCalls: Send HTTP request with security payload\n APISecCalls->>TargetAPI: Validated HTTP request\n TargetAPI->>APISecCalls: Response with headers/body\n APISecCalls->>ResponseParser: Parse response data\n ResponseParser->>SecNavAgent: Structured security results\n SecNavAgent->>TestRunner: Security validation report\n```\n\n## API Security Calls Module\n\nThe `api_sec_calls.py` module provides the foundational HTTP client capabilities for executing security tests. It supports various HTTP methods and authentication schemes required for comprehensive API security testing.\n\n### Supported Security Test Operations\n\n| Operation | Description | Authentication Support |\n|-----------|-------------|----------------------|\n| GET Security Headers | Validate presence and correctness of security headers | Bearer, API Key, Basic |\n| POST Injection Tests | Execute payload injection for XSS, SQLi validation | Bearer, API Key |\n| Authentication Bypass | Test unauthorized access to protected endpoints | Token validation |\n| Rate Limiting | Verify rate limiting mechanisms | None required |\n| CORS Validation | Check cross-origin resource sharing policies | None required |\n\n资料来源：[testzeus_hercules/core/tools/api_sec_calls.py:1-100]()\n\n### Request Configuration\n\n```python\n# Security test request structure\n{\n \"method\": \"GET|POST|PUT|DELETE|PATCH\",\n \"url\": \"https://api.target.com/endpoint\",\n \"headers\": {\n \"Authorization\": \"Bearer {token}\",\n \"Content-Type\": \"application/json\"\n },\n \"params\": {}, # Query parameters\n \"data\": {}, # Request body for POST/PUT/PATCH\n \"timeout\": 30,\n \"verify_ssl\": true\n}\n```\n\n## Gherkin Test Generation\n\nThe `generate_api_security_gherkin_test.py` helper script uses LLM to automatically generate security-focused Gherkin test cases from OpenAPI specification files.\n\n### Input Processing\n\nThe generator accepts OpenAPI specifications in both YAML and JSON formats, parsing the specification to identify:\n\n- Endpoints and their HTTP methods\n- Security schemes defined in the spec\n- Request/response schemas\n- Authentication requirements\n\n资料来源：[helper_scripts/generate_api_security_gherkin_test.py:1-60]()\n\n### Generation Prompt Strategy\n\nThe LLM prompt instructs the model to focus on generating tests that validate:\n\n1. **Vulnerability Detection**: Tests that check for common vulnerabilities\n2. **Configuration Weaknesses**: Validation of security configurations\n3. **Sensitive Data Handling**: Verification of proper data protection\n4. **Authentication/Authorization**: Access control testing\n5. **Input Validation**: Sanitization and validation checks\n\n### Output Format\n\nGenerated test cases follow this structure:\n\n```gherkin\nFeature: API Security Validation - {Endpoint_Name}\n Scenario: Validate security headers on {method} {path}\n Given the API endpoint \"{path}\" requires authentication\n When I send a {method} request without authorization\n Then the response should have status code 401\n And the response should include \"WWW-Authenticate\" header\n \n Scenario: Test for SQL injection vulnerability on {path}\n Given the API endpoint \"{path}\" accepts query parameters\n When I send a GET request with malicious payload in parameter \"id\"\n Then the response should have status code 400 or 422\n And no SQL error should be present in response body\n```\n\n资料来源：[helper_scripts/generate_api_security_gherkin_test.py:80-120]()\n\n## Command Line Interface\n\n### Running Security Tests\n\n```bash\n# Generate security tests from OpenAPI spec\npython -m helper_scripts.generate_api_security_gherkin_test \\\n --input spec.yaml \\\n --output ./tests/security \\\n --model gpt-4o \\\n --number_of_testcase 50\n\n# Execute security tests with Hercules\ntestzeus-hercules --input-file ./tests/security/api_security.feature\n```\n\n### Generation Script Arguments\n\n| Argument | Type | Default | Description |\n|----------|------|---------|-------------|\n| `input_files` | list[str] | required | One or more OpenAPI spec files (YAML or JSON) |\n| `--output` | str | required | Output folder for generated feature files |\n| `--model` | str | o1-preview | OpenAI model for test generation |\n| `--number_of_testcase` | int | 100 | Number of test cases to generate |\n\n资料来源：[helper_scripts/generate_api_security_gherkin_test.py:30-55]()\n\n## Integration with Hercules Framework\n\n### Agent Initialization\n\nThe security agent is initialized through the same mechanism as other Hercules agents, using configuration from the LLM configuration file specified via CLI:\n\n```bash\ntestzeus-hercules \\\n --input-file security_tests.feature \\\n --agents-llm-config-file ./config/security_agent.yaml \\\n --llm-model gpt-4o\n```\n\n### Execution Context\n\nSecurity tests execute within the same context as functional tests, providing:\n\n- Shared browser/playwright session management\n- Consistent logging and telemetry\n- Unified reporting and result aggregation\n- Access to shared utilities and helpers\n\n## Security Test Scenarios\n\n### Common Test Categories\n\n| Category | Test Focus | Example Validation |\n|----------|------------|-------------------|\n| Authentication | Token validation, session management | Invalid token returns 401 |\n| Authorization | Access control, privilege escalation | User cannot access admin endpoints |\n| Input Validation | Payload sanitization, type checking | Malformed input returns 400 |\n| Headers | Security header presence | X-Frame-Options, CSP headers present |\n| Rate Limiting | Request throttling | Excessive requests return 429 |\n| CORS | Cross-origin policy | Invalid origins rejected |\n\n## Best Practices\n\n### Test Data Management\n\n- Use dedicated security test environments\n- Isolate security tests from production data\n- Implement proper cleanup for test artifacts\n- Rotate API keys/tokens used in tests\n\n### Test Coverage\n\n- Aim for comprehensive endpoint coverage\n- Include both positive and negative test cases\n- Validate all security headers defined in your policy\n- Test authentication bypass scenarios\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Purpose |\n|----------|---------|\n| `OPENAI_API_KEY` | Required for LLM-powered test generation |\n| `SECURITY_TEST_API_KEY` | API key for testing authenticated endpoints |\n| `SECURITY_TEST_BASE_URL` | Override target API base URL |\n\n### LLM Configuration\n\nThe security agent uses the same LLM configuration structure as other agents, specified through:\n\n```yaml\n# security_agent_config.yaml\nllm_config:\n model: gpt-4o\n temperature: 0.7\n max_tokens: 4096\n\nother_settings:\n system_prompt: \"You are a security testing expert...\"\n max_consecutive_auto_reply: 10\n```\n\n## Reporting\n\nSecurity test results are integrated into the standard Hercules reporting format:\n\n- Test pass/fail status per scenario\n- Detailed assertion results\n- HTTP request/response logging\n- Security-specific metrics (headers present, vulnerabilities detected)\n\n## Related Documentation\n\n- [Browser Navigation Agent](testzeus_hercules/core/agents/executor_nav_agent.py) - Core navigation patterns\n- [Simple Hercules](testzeus_hercules/core/simple_hercules.py) - Main framework architecture\n- [API Functional Testing](helper_scripts/generate_api_functional_gherkin_test.py) - Functional test generation\n\n---\n\n\n\n## MCP Integration\n\n### 相关页面\n\n相关主题：[Agent System](#agent-system), [Tool System](#tool-system)\n\n\nRelated Source Files\n\n以下源码文件用于生成本页说明：\n\n- [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)\n- [testzeus_hercules/core/tools/mcp_tools.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/tools/mcp_tools.py)\n- [testzeus_hercules/utils/mcp_helper.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/mcp_helper.py)\n- [mcp_servers.example.json](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/mcp_servers.example.json)\n- [testzeus_hercules/config.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/config.py)\n\n\n# MCP Integration\n\n## Overview\n\nThe MCP (Model Context Protocol) Integration in TestZeus Hercules enables the testing agent to discover, catalog, and execute tools exposed by external MCP servers. This integration allows Hercules to extend its capabilities by leveraging tools from multiple Model Context Protocol-compliant servers during end-to-end testing workflows.\n\nMCP serves as a standardized communication layer that allows the testing framework to:\n\n- Enumerate and connect to configured MCP servers\n- List available tools and resource namespaces from each connected server\n- Execute remote tool calls with correct parameters\n- Retrieve resources by URI when required for test execution\n\n资料来源：[testzeus_hercules/core/agents/mcp_nav_agent.py:1-10]()\n\n## Architecture\n\n### System Components\n\nThe MCP integration is built on three primary components:\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| McpNavAgent | `core/agents/mcp_nav_agent.py` | Main navigation agent that orchestrates MCP server interactions |\n| MCPHelper | `utils/mcp_helper.py` | Utility class providing MCP client functionality |\n| MCP Tools | `core/tools/mcp_tools.py` | Tool implementations for MCP operations |\n\n### Component Relationship\n\n```mermaid\ngraph TD\n A[TestZeus Hercules Core] --> B[McpNavAgent]\n B --> C[MCPHelper]\n C --> D[MCP Servers]\n \n B --> E[get_configured_mcp_servers]\n B --> F[check_mcp_server_connection]\n B --> G[execute_mcp_tool]\n B --> H[read_mcp_resource]\n \n E --> I[Server Discovery]\n F --> J[Connection Status]\n G --> K[Tool Execution]\n H --> L[Resource Retrieval]\n```\n\n## McpNavAgent\n\nThe `McpNavAgent` is the central agent responsible for all MCP-related operations. It inherits from `BaseNavAgent` and implements the Model Context Protocol interaction patterns.\n\n资料来源：[testzeus_hercules/core/agents/mcp_nav_agent.py:6-9]()\n\n### Agent Configuration\n\n| Property | Value | Description |\n|----------|-------|-------------|\n| `agent_name` | `mcp_nav_agent` | Unique identifier for the agent |\n| Inherits | `BaseNavAgent` | Base navigation agent functionality |\n\n### Core Functions\n\nThe MCP Navigation Agent implements the following core functions:\n\n1. **Server Discovery** - Enumerate configured MCP servers and their connection status\n2. **Capability Cataloging** - List tools and resource namespaces for each connected server\n3. **Tool Execution** - Call tools with correct parameters and handle responses\n4. **Resource Retrieval** - Read resources by URI when required\n5. **Result Summarization** - Capture server, tool, arguments, outputs; include timings and status\n\n资料来源：[testzeus_hercules/core/agents/mcp_nav_agent.py:14-28]()\n\n### Operational Rules\n\n#### Rule 1: Previous Step Validation\n\nBefore any new action, explicitly review the previous step and its outcome. Do not proceed if the prior critical step failed; address it first.\n\n```mermaid\ngraph TD\n A[Execute Action] --> B{Previous Step Succeeded?}\n B -->|No| C[Address Failure First]\n B -->|Yes| D[Continue to Next Action]\n C --> D\n```\n\n#### Rule 2: Server Scan First\n\nThe agent must call `get_configured_mcp_servers` and for each server, call `check_mcp_server_connection` before taking any other action.\n\n资料来源：[testzeus_hercules/core/agents/mcp_nav_agent.py:31-35]()\n\n### Agent Prompt\n\nThe agent uses a specialized system prompt that defines its role and behavioral guidelines:\n\n```\n### MCP Navigation Agent\n\nYou are an MCP (Model Context Protocol) Navigation Agent that assists the Testing Agent by discovering MCP servers, cataloging their exposed tools/resources, and executing the right tool calls to complete the task. Always begin by scanning all configured servers before taking any action.\n```\n\n资料来源：[testzeus_hercules/core/agents/mcp_nav_agent.py:11-21]()\n\n## MCPHelper Utility\n\nThe `MCPHelper` class provides the underlying functionality for MCP server interactions. It is exported through the `mcp_helper.py` module and integrates with the agent system through `set_mcp_agents`.\n\n资料来源：[testzeus_hercules/utils/mcp_helper.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/utils/mcp_helper.py)\n\n### Key Functions\n\n| Function | Purpose |\n|----------|---------|\n| `MCPHelper` | Main helper class for MCP operations |\n| `set_mcp_agents` | Configures MCP agents within the testing framework |\n\n## Configuration\n\n### Configuration File Format\n\nMCP servers are configured using a JSON file. The example file `mcp_servers.example.json` demonstrates the expected format:\n\n```json\n{\n \"mcpServers\": {\n \"server_name\": {\n \"command\": \"command_to_run\",\n \"args\": [\"arg1\", \"arg2\"],\n \"env\": {\n \"KEY\": \"value\"\n }\n }\n }\n}\n```\n\n### Command Line Arguments\n\nThe MCP integration can be configured through command line arguments:\n\n| Argument | Type | Description |\n|----------|------|-------------|\n| `--agents-llm-config-file` | string | Path to the agents LLM configuration file |\n| `--agents-llm-config-file-ref-key` | string | Reference key for the agents LLM configuration file |\n\n资料来源：[testzeus_hercules/config.py:27-39]()\n\n## Workflow\n\n### Standard MCP Interaction Flow\n\n```mermaid\ngraph TD\n A[Start Test Execution] --> B[Initialize McpNavAgent]\n B --> C[Call get_configured_mcp_servers]\n C --> D[For Each Server]\n D --> E[Call check_mcp_server_connection]\n E --> F{Server Connected?}\n F -->|No| G[Log Error / Skip Server]\n F -->|Yes| H[Catalog Tools & Resources]\n H --> I[Task Requires MCP Tool?]\n I -->|Yes| J[Call execute_mcp_tool]\n I -->|No| K[Continue with Other Tasks]\n J --> L[Process Tool Response]\n L --> M[Return Results to Testing Agent]\n G --> D\n K --> N[Complete Test]\n M --> N\n```\n\n### Tool Execution Workflow\n\nWhen executing MCP tools, the agent follows this sequence:\n\n1. Identify the target MCP server\n2. Verify server connection status\n3. Determine the correct tool and parameters\n4. Execute the tool call via MCP protocol\n5. Capture response including timing and status\n6. Return formatted results to the testing agent\n\n## Integration with Testing Framework\n\n### Agent Hierarchy\n\n```mermaid\ngraph BT\n A[BrowserNavAgent] --> B[BaseNavAgent]\n C[ApiNavAgent] --> B\n D[SqlNavAgent] --> B\n E[McpNavAgent] --> B\n F[SecNavAgent] --> B\n \n B --> G[TestZeus Hercules Core]\n```\n\nAll navigation agents, including `McpNavAgent`, inherit from `BaseNavAgent`, ensuring consistent behavior and integration with the core testing framework.\n\n资料来源：[testzeus_hercules/core/agents/__init__.py](https://github.com/test-zeus-ai/testzeus-hercules/blob/main/testzeus_hercules/core/agents/__init__.py)\n\n### Available Navigation Agents\n\n| Agent | Purpose |\n|-------|---------|\n| `BrowserNavAgent` | Web browser interaction and navigation |\n| `ApiNavAgent` | API testing and validation |\n| `SqlNavAgent` | Database query execution |\n| `McpNavAgent` | MCP server tool execution |\n| `SecNavAgent` | Security testing operations |\n\n## Best Practices\n\n### Initialization\n\n1. Always ensure MCP servers are properly configured before test execution\n2. Verify server connectivity before attempting tool calls\n3. Use the configured servers list as the authoritative source of available MCP servers\n\n### Error Handling\n\n1. Check previous step outcomes before proceeding\n2. Log connection failures with server identification\n3. Handle tool execution errors with proper parameter validation\n4. Provide clear error messages when MCP operations fail\n\n### Task Focus\n\n- Execute only actions required by the primary testing task\n- Use extra information from MCP responses cautiously\n- Avoid unnecessary server scans after initial discovery\n\n## Security Considerations\n\nThe MCP integration supports sensitive operations requiring careful configuration:\n\n- API keys should be provided through secure environment variables\n- Server configurations should be validated before use\n- Tool execution permissions should be properly scoped\n- Resource access should follow least-privilege principles\n\n## Summary\n\nThe MCP Integration module provides TestZeus Hercules with the ability to extend its testing capabilities through external MCP servers. By implementing a dedicated `McpNavAgent` that follows standardized MCP protocols, the framework can seamlessly discover servers, catalog their capabilities, and execute tools as needed during end-to-end testing scenarios.\n\nKey benefits include:\n\n- **Extensibility**: Add new testing capabilities without modifying core framework code\n- **Standardization**: Uses the Model Context Protocol for consistent server communication\n- **Resource Management**: Access remote resources via standardized URI-based retrieval\n- **Comprehensive Logging**: Captures server status, tool execution times, and results\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：test-zeus-ai/testzeus-hercules\n\n摘要：发现 13 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 来源证据：0.1.1。\n\n## 1. 配置坑 · 来源证据：0.1.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：0.1.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_87e563b6a81f4a529799ac528ee21610 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 来源证据：0.0.40\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.0.40\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_02c1945d063b4151a3df1526b85e9d50 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.0.40 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 维护坑 · 来源证据：0.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1d1eb9ae89f04ff9b339c73cc932f2f7 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 维护坑 · 来源证据：0.1.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e0e02b07ea6845eaac8c4f18871aaa32 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 维护坑 · 来源证据：0.1.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.6\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_41cf6e34c47b4f929a67426b258b8fd8 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.6 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | last_activity_observed missing\n\n## 8. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | no_demo; severity=medium\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 来源证据：0.1.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.1.4\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d6aeb053b3a541778b07c0bca68c5c82 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 安全/权限坑 · 来源证据：0.2.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.2.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_963ec16ebc32452a8ca13e8ebc1aed96 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.2.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | issue_or_pr_quality=unknown\n\n## 13. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：test-zeus-ai/testzeus-hercules\n\n摘要：发现 13 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 来源证据：0.1.1。\n\n## 1. 配置坑 · 来源证据：0.1.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：0.1.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_87e563b6a81f4a529799ac528ee21610 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 来源证据：0.0.40\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.0.40\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_02c1945d063b4151a3df1526b85e9d50 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.0.40 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 4. 维护坑 · 来源证据：0.1.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1d1eb9ae89f04ff9b339c73cc932f2f7 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 维护坑 · 来源证据：0.1.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e0e02b07ea6845eaac8c4f18871aaa32 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 6. 维护坑 · 来源证据：0.1.6\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：0.1.6\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_41cf6e34c47b4f929a67426b258b8fd8 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.6 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | last_activity_observed missing\n\n## 8. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | no_demo; severity=medium\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | no_demo; severity=medium\n\n## 10. 安全/权限坑 · 来源证据：0.1.4\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.1.4\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d6aeb053b3a541778b07c0bca68c5c82 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.1.4 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 安全/权限坑 · 来源证据：0.2.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：0.2.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_963ec16ebc32452a8ca13e8ebc1aed96 | https://github.com/test-zeus-ai/testzeus-hercules/releases/tag/0.2.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | issue_or_pr_quality=unknown\n\n## 13. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:888701643 | https://github.com/test-zeus-ai/testzeus-hercules | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# testzeus-hercules - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for test-zeus-ai/testzeus-hercules.\n\nProject:\n- Name: testzeus-hercules\n- Repository: https://github.com/test-zeus-ai/testzeus-hercules\n- Summary: Hercules is the world’s first open-source testing agent, enabling UI, API, Security, Accessibility, and Visual validations – all without code or maintenance. Automate testing effortlessly and let Hercules handle the heavy lifting! ⚡\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Hercules is the world’s first open-source testing agent, enabling UI, API, Security, Accessibility, and Visual validations – all without code or maintenance. Automate testing effortlessly and let Hercules handle the heavy lifting! ⚡\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Hercules is the world’s first open-source testing agent, enabling UI, API, Security, Accessibility, and Visual validations – all without code or maintenance. Automate testing effortlessly and let Hercules handle the heavy lifting! ⚡\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. getting-started: Getting Started with TestZeus Hercules. Produce one small intermediate artifact and wait for confirmation.\n2. system-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. agent-system: Agent System. Produce one small intermediate artifact and wait for confirmation.\n4. browser-automation: Browser Automation. Produce one small intermediate artifact and wait for confirmation.\n5. tool-system: Tool System. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/test-zeus-ai/testzeus-hercules\n- https://github.com/test-zeus-ai/testzeus-hercules#readme\n- README.md\n- pyproject.toml\n- Dockerfile\n- helper_scripts/hercules_setup.sh\n- docs/run_guide.md\n- testzeus_hercules/core/runner.py\n- testzeus_hercules/core/simple_hercules.py\n- testzeus_hercules/core/__init__.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：test-zeus-ai/testzeus-hercules\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install testzeus-hercules\n```\n\n来源：https://github.com/test-zeus-ai/testzeus-hercules#readme\n\n## 来源\n\n- repo: https://github.com/test-zeus-ai/testzeus-hercules\n- docs: https://github.com/test-zeus-ai/testzeus-hercules#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_9c77890b81fa43109bad142f3501b30e"
}