Agent Test Range

一个最小成本的 AI Agent 测试靶场：它是一个有前后端的 admin portal，同时把页面、元素、动作和断言暴露成机器可读 manifest，方便后续接入自然语言 Agent。

启动

npm run dev

默认地址：

• Web: http://localhost:4173
• API: http://localhost:4173/api

登录账号：

• Email: admin@example.com
• Password: admin123

验证

npm test

End User Portal

面向测试人员和业务用户的入口：

http://localhost:4173/portal

Portal 支持从自然语言创建 Requirement Session、在页面里查看 BDD/strategy/session detail、提交人类反馈、确认后直接启动 Execution Session，也支持从 URL 开始创建 Exploration Session，输出页面 inventory、schema draft、test opportunities 和 Playwright draft，并能把探索出来的测试机会转成待确认的 Requirement Session。

重新生成 HTML 文档：

npm run docs:html

Docker

构建并启动标靶网站：

docker compose up -d automation-test-target

本机访问：

• Web: http://127.0.0.1:4173
• Health: http://127.0.0.1:4173/api/health
• Manifest: http://127.0.0.1:4173/agent/page-manifest.json

同一个 Docker network 内的 Agent 访问：

• Target URL: http://automation-test-target:4173
• Manifest URL: http://automation-test-target:4173/agent/page-manifest.json

docker-compose.yml 会创建一个名为 agent-lab 的网络。如果 Hermes Agent 在另一个 compose 项目里运行，需要把 Hermes 容器也接到这个网络，或者在它的 compose 文件里声明同名 external network。

示例：

networks:
  agent-lab:
    external: true

然后 Hermes 任务里不要使用 127.0.0.1:4173。在 Hermes 容器里，127.0.0.1 指向 Hermes 自己，应该使用服务名：

http://automation-test-target:4173

LangFuse

本项目的 Agent workflow 可以把 trace 写入 LangFuse。宿主机本地运行时：

LANGFUSE_ENABLED=true
LANGFUSE_HOST=http://localhost:3000
LANGFUSE_PUBLIC_KEY=<your-langfuse-public-key>
LANGFUSE_SECRET_KEY=<your-langfuse-secret-key>
LANGFUSE_CAPTURE_MODE=redacted

如果 workflow 从另一个 Docker 容器里访问宿主机上的 LangFuse，使用：

LANGFUSE_HOST=http://host.docker.internal:3000

如果该容器由 Docker Compose 启动，service 通常需要：

extra_hosts:
  - "host.docker.internal:host-gateway"
environment:
  LANGFUSE_ENABLED: "true"
  LANGFUSE_HOST: "http://host.docker.internal:3000"
  LANGFUSE_PUBLIC_KEY: "<your-langfuse-public-key>"
  LANGFUSE_SECRET_KEY: "<your-langfuse-secret-key>"
  LANGFUSE_CAPTURE_MODE: "redacted"

运行完成后，summary.json 会包含 observability.traceUrl 和 observability.traceId。也可以运行 console 查看最近 workflow：

npm run agent-console

需要查看某个 run 的 owner、状态、下一步、summary 路径和 LangFuse trace 时，使用交互模式：

npm run agent-console -- --interactive

交互模式会在推荐命令可以安全确定时询问是否立即执行；需要人类反馈或选择 scenario 的命令只会显示，不会自动运行。

最小 Agent 测试闭环

第一条任务从登录页开始：

npm run agent-test:prepare -- agent-tests/test-cases/login-basic.json

这个命令会：

• 重置标靶数据
• 检查 health 和 manifest
• 输出一段可以发给 Hermes 的自然语言任务
• 写入 agent-tests/reports/login-basic-prepare.json

把输出的 prompt 发给 Hermes。Hermes 完成后，运行：

npm run agent-test:judge -- agent-tests/test-cases/login-basic.json

judge 不依赖 Hermes 自己报告成功，而是读取标靶系统状态，检查是否出现 ADMIN_LOGIN audit log。

当前边界

• 不依赖 React、Express、SQLite，先用原生 Node HTTP + 内存 seed 数据降低搭建成本。
• 页面元素用 data-testid 和 public/agent/page-manifest.json 描述。
• agent/cases/*.json 是自然语言任务到页面操作 case 的目标格式。
• 后续可以把执行层换成 Playwright，或者把 goal 交给 AI Agent 生成 case。