explorbot-fundamentals

Explorbot 基础知识

Explorbot 是一款自主式 AI 网页测试命令行工具。它通过“研究 → 规划 → 测试”的循环驱动自己的浏览器，Agent 则像使用 git 或 npm 一样驱动它。

关于命令和标志的问题，请以已安装的 CLI 为准，切勿凭记忆回答。

npx explorbot --help                  # commands, and the EXPLORBOT_* variables
npx explorbot <command> --help        # flags for one command

无需安装即可运行

Explorbot 无需安装到项目中：只需 npx 和一个提供商即可，且不会向工作目录写入任何内容。用户想试用 Explorbot，或要将它用于此处没有对应仓库的应用时，可以采用这种方式。

npx explorbot init --global --provider <name>          # once per machine, key in ~/.explorbot/.env
npx explorbot explore https://app.example.com/login --max-tests 3

详细信息（包括供 CI 使用的各命令对应的 EXPLORBOT_* 形式）：references/no-install.md。

若要将 Explorbot 安装到项目中，使配置、知识和生成的测试都保存在仓库中，请参阅 [[explorbot-setup]]。

运行所需条件

Explorbot 不会自行提供以下内容。在任何新机器上运行第一条命令前，请先确认：

• 浏览器。 运行 npx playwright install --with-deps chromium。没有浏览器时，所有需要打开页面的命令都会失败。
• 环境中有提供商密钥，并通过配置或 EXPLORBOT_AI_PROVIDER 选择了提供商。
• 如果需要收集报告，必须指定已知的输出文件夹。设置 EXPLORBOT_OUTPUT；没有项目配置时，默认路径是 ~/.explorbot/sites/<host>/，而不是工作目录。

单次运行的知识

登录信息和一次性事实应放入单次运行的知识中，不会保存到仓库。可选择以下两种方式之一：

• --knowledge '<markdown>' — 可重复使用。纯文本会应用于每个页面。若要指定作用范围，请在文本开头添加有效的 frontmatter 块：

  ---
  url: /users/sign_in
  ---
  Sign in as ${env.LOGIN_EMAIL} / ${env.LOGIN_PASSWORD}
  

• EXPLORBOT_KNOWLEDGE — 仅支持纯文本，始终应用于每个页面。不会读取其中的 frontmatter。若要从环境变量提供有作用范围的知识，请使用 EXPLORBOT_KNOWLEDGE_FILE。

规则：

• 没有 --- 分隔符的 url: 行会被视为正文，而不是作用范围。
• 作用范围键包括用于页面的 url:，以及用于 API 船只的 endpoint:。
• ${env.NAME} 由 Explorbot 解析，因此机密不会出现在文本中。
• 切勿同时设置变量并通过标志传入相同文本，否则会应用两次。

格式和 URL 模式：docs/workflow/knowledge.md。

文档

本地安装后查看 node_modules/explorbot/docs/；在 Explorbot 仓库内工作时查看仓库的 docs/；否则访问 https://raw.githubusercontent.com/testomatio/explorbot/main/docs/<path>。docs/index.json 列出了每个页面及其说明 — 先阅读它以选择页面，再打开该页面。

结果保存位置

如果运行时使用了项目中的 explorbot.config.js，Explorbot 会将内容写入项目目录；否则会写入 ~/.explorbot/sites/<host>/。在该根目录下：

路径	内容
output/reports/	会话报告：覆盖率、缺陷、执行问题
output/plans/	生成或执行的计划
output/states/	每个状态对应的 HTML、ARIA 快照和截图
output/research/	Researcher 生成的 UI 地图
output/tests/	生成的 Playwright / CodeceptJS 文件
output/explorbot.log	运行日志 — 失败时从这里开始排查
knowledge/、experience/	你教给它的内容，以及它学到的内容

报告功能由 @testomatio/reporter 提供。 Explorbot 会在内部运行它，并向其传入所有 reporter 变量。因此，TESTOMATIO 会将运行结果发送到对应的 Testomat.io 项目，而 reporter 的 PR 令牌会将结果发布到已打开的拉取请求或合并请求中。无需进行其他配置。变量说明：testomatio-reporter 技能，或 docs/workflow/reporting.md。

退出代码不代表通过或失败。 explore 和 test 在会话完成时都会以 0 退出；场景失败是运行结果，而不是程序崩溃。请阅读报告。例外是 navigate — 1 表示无法访问，可将其用作预检。

为站点命名

目标要么是绝对 URL——以 http:// 或 https:// 开头；要么是以 / 开头的相对路径。其他形式都存在歧义，不是有效目标。

相对路径需要一个站点作为解析依据：项目配置中的 web.url，或 EXPLORBOT_URL。如果两者都没有，请传入绝对 URL。不需要任何目标的命令——test、learn、knows、experience、compact——会读取相同的两个来源。npx explorbot sites 会列出目前已探索的站点。

先做成本低的操作

• npx explorbot context <url> — 标题、匹配的知识、交互元素。不会调用 AI。
• npx explorbot shell <url> '<codecept command>' — 运行一条命令后退出。
• npx explorbot knows <url> — 查看哪些知识与页面匹配。
• npx explorbot navigate <url> --session — 检查可访问性，并保存会话。

规则

• explorbot start 是交互式 TUI，Agent 无法操作。请让用户运行它。其他命令均以无头模式运行并退出。
• 如果 --help 中没有显示某个命令或标志，该命令或标志就不存在。
• Explorbot 需要 CRUD 功能；落地页、博客或 CMS 不在适用范围内。

相关技能

• [[explorbot-setup]] — 安装到项目中：配置、提供方、登录知识、已验证的导航。
• [[explorbot-plan]] — 手动编写测试计划，并使用 explorbot test 运行。