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