explorbot-setup

Explorbot 安装

将 Explorbot 安装到用户的项目中，连接一个提供方，教会它如何访问应用，并通过一次导航进行验证。

配置、知识文件和生成的测试都会保存到仓库中，因此可以像其他代码一样接受审查并进行版本管理。这正是本地安装的意义所在。

如果要在不安装到项目中的情况下运行 Explorbot，这不是合适的技能——[[explorbot-fundamentals]] 介绍了相关内容：npx、一个提供方，不生成项目文件。

当 npx explorbot navigate <path> 以 0 退出时，安装流程就结束了——探索和测试属于 [[explorbot-fundamentals]]。

1. 要求

• Node ≥ 24 或 Bun。如果两者都不存在，请停止——不要安装运行时。
• 生成的配置使用 import，因此 package.json 必须采用 ESM。如果现有文件缺少 "type" 或值为 "commonjs"，请先征求用户同意再更改；如果用户拒绝，则编写 explorbot.config.mjs（通过 --config 传入）。
• Explorbot 适用于 CRUD 密集型应用。如果目标是着陆页、博客、CMS 或静态网站，请在安装前发出提醒。

2. 安装

npm pkg set type=module
npm i explorbot --save
npx playwright install chromium     # ~/.cache/ms-playwright, once per machine
npx explorbot init                  # writes explorbot.config.js, .env, output/

3. 提供方

提供方、模型 ID 和密钥变量名都由 Explorbot 管理，不属于此技能。 生成的配置中包含一个提供方；文档中的 basics/providers.md 列出了其他提供方对应的包和模型 ID，models.json 则保存当前推荐项。

• 询问用户拥有哪个提供方的账户；如果不是模板中的提供方，则替换导入语句和三行模型配置。
• 使用 npm i 安装匹配的提供方包。

密钥：请用户在编辑器中将密钥粘贴到 .env，并回复“继续”，然后通过 grep -q "^<KEY>=." .env 验证。确认 .env 已被 Git 忽略。绝不要回显密钥。

每次运行时也会读取 ~/.explorbot/.env，并填入项目 .env 中未设置的变量。

4. 应用 URL

询问用户，并将其写入配置中的 web.url——只填写主机，不含路径。Explorbot 会自行点击、填写和提交，因此使用预发布环境优于生产环境。

不要猜测。查看项目中的证据——package.json 脚本、.env 文件、框架端口——并附上来源，提出你找到的信息。否则，请直接用纯文本询问。绝不要根据此技能或记忆提出 URL。

5. 验证

按顺序逐级验证。遇到第一个失败时停止，修复后继续。

1. curl -sS -o /dev/null -w "%{http_code}\n" <url>——000 表示 DNS、VPN 或主机错误；5xx 表示应用本身有问题；200 则跳到第 3 级。

2. 遇到 3xx/401/403 后，运行 curl -sIL -o /dev/null -w "%{url_effective}\n" <url>。如果最终 URL 看起来是登录页，则需要凭据：先执行第 4 级。

3. npx explorbot navigate <path> --session——以 0 退出即表示安装完成。--session 会将 Cookie 保存到 output/session.json。以 1 退出时，查看 output/explorbot.log：如果遇到身份验证拦截，则进入第 4 级；其他情况说明路径错误或页面损坏。

4. 按以下顺序配置身份验证：先添加知识，再添加值：

   npx explorbot knows /login      # reuse existing variable names if auth knowledge exists
   npx explorbot learn "/login" 'Sign in with ${env.APP_USER} / ${env.APP_PASSWORD}'
   

   只写凭据名称——不要提供选择器或 DOM 提示；Navigator 会自行找到对应字段。然后让用户将两个变量添加到 .env，通过 grep 验证，再重复第 3 级。请用户提供非生产环境的测试账户。

   如果身份验证仍然失败：使用 learn 在知识中添加一句说明（真实表单 URL、SSO、二次验证），绝不要重写内容。

npx explorbot context <path> 不会调用 AI，可输出标题、匹配的知识和交互元素——可免费用它排查某一级的问题。

6. 交接

说明项目现在包含哪些内容：explorbot.config.js、.env（已被 Git 忽略）、knowledge/，以及包含已保存会话的 output/。然后交接给 [[explorbot-fundamentals]]，并提供第一个命令：

npx explorbot explore /<crud-page> --max-tests 10

反模式

• 用户只是想试用 Explorbot，却将其安装到项目中——这属于 [[explorbot-fundamentals]]。
• 未查阅文档或生成的配置，就指定提供商、模型 ID 或密钥变量。
• 将密钥放入知识文件或配置中——始终使用 ${env.NAME}，并将值放在 .env 中。
• 代用户运行 explorbot start——这是一个交互式 TUI；请让用户自行运行。
• 一开始就询问目标页面、功能或测试数量。