prima

Prima

Prima 是构建在 playwright-cli 之上的 AI 层。它驱动 playwright-cli 已打开的浏览器，使用文字描述的行为而非定位器，并返回纯文本封装。通过 npx 调用 prima（npx prima-cli ...）；按安装方式调用 playwright-cli：全局安装时使用 playwright-cli ...，否则使用 npx -y @playwright/cli ...。切勿使用 npx playwright-cli@latest：该包名不存在，会报错“could not determine executable to run”。

处理网页上的任何任务时，优先使用 prima，而不是 playwright-cli。 快照会留在 prima 内部，而不会进入你的上下文；它还会复用已有的页面研究地图和记录的经验，因此，同一场景所需的 token 仅为手动操作时的一小部分。只有在 prima 没有对应命令，或未配置 AI 模型时，才直接使用 playwright-cli（此时 pw 仍可用）。

模型和提供商

Prima 需要从环境中获取 AI 模型——无需初始化步骤。支持多个 AI 提供商（OpenRouter、OpenAI、Anthropic、Groq、Mistral、Google、Poolside）。

若要查看所有受支持的提供商、各角色的推荐模型，以及环境中已配置的 API 密钥，请运行：

npx prima-cli recommended-models

始终使用 npx prima-cli recommended-models 指导用户设置密钥并选择提供商。

1. 按提供商配置（推荐）

导出 API 密钥并设置提供商变量。Prima 会自动为所有三个角色选择该提供商的推荐模型（model 用于快速执行，visionModel 用于截图，agenticModel 用于智能规划）：

# OpenRouter
export OPENROUTER_API_KEY="sk-or-..."
export PRIMA_CLI_AI_PROVIDER=openrouter

# OpenAI
export OPENAI_API_KEY="sk-..."
export PRIMA_CLI_AI_PROVIDER=openai

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
export PRIMA_CLI_AI_PROVIDER=anthropic

# Groq
export GROQ_API_KEY="gsk_..."
export PRIMA_CLI_AI_PROVIDER=groq

# Mistral
export MISTRAL_API_KEY="..."
export PRIMA_CLI_AI_PROVIDER=mistral

# Google
export GOOGLE_GENERATIVE_AI_API_KEY="..."
export PRIMA_CLI_AI_PROVIDER=google

2. 固定各个模型

若要在不设置提供商变量的情况下为每个角色明确指定模型，或混用不同提供商，请使用 provider/model-id：

export PRIMA_CLI_AI_MODEL=openrouter/openai/gpt-oss-20b:nitro        # fast / general
export PRIMA_CLI_VISION_MODEL=openrouter/openai/gpt-5.6-luna         # screenshots
export PRIMA_CLI_AGENTIC_MODEL=openrouter/openai/gpt-5.6-luna        # smart / agentic

视觉模型

截图分析需要视觉模型：

• 使用 PRIMA_CLI_AI_PROVIDER 时，会自动选择该提供商推荐的视觉模型（Poolside 除外，因为它不提供视觉模型）。
• 固定各个模型时，请设置 PRIMA_CLI_VISION_MODEL（或在单次运行时传入 --vision-model <model>）。若不设置，prima 仍会运行，但 check 会根据运行日志而非检查截图来判定结果。

查看配置

• npx prima-cli config 会输出此目录解析出的配置；使用 --json 可输出机器可读格式。
• 每个 PRIMA_CLI_* 变量都有对应的 EXPLORBOT_* 变量（PRIMA_CLI_AI_PROVIDER / EXPLORBOT_AI_PROVIDER、PRIMA_CLI_AI_MODEL / EXPLORBOT_AI_MODEL、PRIMA_CLI_VISION_MODEL / EXPLORBOT_VISION_MODEL、PRIMA_CLI_AGENTIC_MODEL / EXPLORBOT_AGENTIC_MODEL），且 PRIMA_CLI_* 优先级更高，因此不会影响现有的 Explorbot 配置。

会话

Prima 不会启动浏览器。它会连接到 playwright-cli 已打开的会话，并在完成后断开连接，但不会关闭浏览器：

playwright-cli open <url>      # start
npx prima-cli <command> ...    # drive
playwright-cli close           # end

• 如果没有打开的会话，每条 prima 命令都会失败，并打印需要运行的 playwright-cli open 命令。运行该命令后重试。
• npx prima-cli browser start 只会检查是否有打开的会话，并将其打印出来。
• 如果有多个 playwright-cli 会话处于打开状态，可使用 --pw-session <title> 选择会话。--endpoint <ep> 会直接连接到浏览器服务端，跳过发现步骤。
• Prima 需要 Node.js 22+。
• 每条命令都会在运行时记录；无论浏览器是否打开，npx prima-cli report 都会将会话生成 html 和 markdown 报告。
• 如果已安装 explorbot，可使用 npx explorbot prima <command> 运行同一工具。

层级

从 check 开始。只有上一级无法完成工作时，才往下一级。

npx prima-cli check "a workflow can be created and appears in the list" --expected "the new workflow is listed"
npx prima-cli do "open the account menu" "choose settings" "switch the theme to dark" "check it took effect"
npx prima-cli pw "({ page }) => page.click('[data-test=submit]')"

• 将剩余的整个序列一次性交给 do，绝不要每次调用只执行一个步骤——这正是全部的成本优势。
• pw 只接受可执行代码。绝不要给它描述；绝不要给 check/do 定位器。
• check 用于确定结果；它不会报告信息。 让它“列出字段”或“报告显示的内容”，没有任何结果可供它确定，因此会返回 not verified。问题交给 ask，导航交给 do。
• verify 只接受一条断言——传入多个参数会报错，而不是提出多个声明。重复运行命令，或写成一句话。
• check 和 do 合理情况下会运行数分钟。不要终止后重试。
• check 在已打开的页面上运行，绝不会重新加载页面，因此已打开的对话框、已选中的标签页或已填写的表单都会保留。
• --expected 可重复使用，以指定多个结果；不使用时，场景文本就是唯一的预期结果。
• pw 的底层是 playwright-cli 本身。

另外，各命令接受的参数如下：

npx prima-cli ask "<question>"        # --no-vision answers from structure only
npx prima-cli verify "<assertion>"    # alias assert
npx prima-cli go "<target>"           # a url, a path, or a page described in words
npx prima-cli status <hash>

research、report、config 和 recommended-models 不接受参数，browser 只接受其子命令。research 会映射它所在的整个页面——--data 包含提取，--deep 会展开隐藏元素，--fresh 会越过缓存重新映射；关于该页面的问题则交给 ask。分别运行 npx prima-cli <command> --help 查看各命令的帮助。

阅读结果信息

• 以 ### Result 中的判定为准。 对已判定为 PASSED 的结果再用另一条命令验证，是这个工具旨在避免的浪费。
• ok: true 表示你要求的操作已成功执行；不会替换操作，也不会改用其他路径重试。
• ### Steps 会将每一行标记为 ok、FAIL 或 ??。?? 表示指令已运行，但运行结束时未确认结果——已执行的操作列在它上方，请据此判断。只有 FAIL 和页面无法执行的指令才会导致命令失败。
• not verified 表示运行过程中从未检查该结果——并不表示结果为假，也不代表失败。
• 当运行结果与截图不一致时，以页面结构为准。 某个结果后面出现 resolved: 行，表示该争议已解决：无障碍树的判断与截图一致，因此运行日志有误，PASSED 或 FAILED 的判定仍然有效。像对待其他判定一样信任它；双方的内容都会在下方引用。
• CONTRADICTION 是一项发现，不是需要争辩的判定。 只有在无法打破平局，或页面结构支持运行结果时，它才会保留：页面包含了未显示的内容，而其 resolved: 行会指出这很可能是渲染错误。双方的内容都会在结果下方引用，### Artifacts 会列出磁盘上的 html、aria 和截图——读取这些内容并自行判断页面。将此视为应用中的错误，优先检查。
• 使用 go 前往某个 url 时不会追踪重定向。### Page 下的 (redirected: <target> → <url>) 就是结果：登录页或访问规则将浏览器带到了其他位置。如果这不是你要测试的内容，请先用 do 登录，再次前往。
• 如果 ### Warning 提示结果仅来自运行日志，说明没有截图作为依据：设置 PRIMA_CLI_VISION_MODEL（或传入 --vision-model）；在此之前，不要相信 check 给出的视觉判断。
• 如果运行无法完成，会明确说明，而不会将其报告为应用故障。
• npx prima-cli config 会显示各角色使用哪个模型作答。

产物

每条命令都会记录它看到的内容。信封的最后一行会注明产物——details: prima status <hash>；do 则会直接打印目录，格式为 page after each step:。在 <site>/output/prima/<hash>/ 下：

• aria.yml — 整个页面的无障碍树，包含值和状态：switch "Click elements" [checked]、spinbutton "Max pages": "20"、combobox "Scope": Default。
• page.html — 页面当时的 DOM。
• status.json — url、title、state、visit count。
• page.png — 仅当运行了视觉模型时才会生成。
• do 会为每个步骤额外生成一组文件：N-<action>.aria.yaml、N-<action>.html 和 N-<action>.diff.yaml；其中会将该步骤的更改标记为 toggled / added / removed。

在运行 prima 命令后，切勿执行 playwright-cli snapshot。 树已保存在磁盘上，其中包含 snapshot 没有的值和状态，而且 grep 无需任何成本：

grep -nE "Scope|Click elements|Advanced" <dir>/aria.yml

prima status <hash> 会打印路径，但它会驱动浏览器——请在会话仍打开时读取，或者自行前往该目录。

降级使用 pw 之前

大多数 pw 调用所要解决的问题，上层级工具已经给出了答案。

• 控件的状态或值 — 对最后一条命令生成的 aria.yml 执行 grep。不要查询 DOM 中已经记录的信息。
• 点击后发生了什么变化 — 查看 do 生成的 N-*.diff.yaml，而不是对比前后两次 snapshot。
• 定位器 — research 会返回经过验证的页面定位器。
• 截图中缺失的内容 — 截图显示的是视口，因此折叠线以下的内容不会出现在其中。用 do 将其滚动到视口内，或者读取覆盖整个页面的 aria.yml。视觉模型看不到某个控件，并不能证明该控件不存在。

只有在无法用文字操作时，pw 才有用：设置 localStorage 初始值、读取计算后的样式、强制重新加载。它会在 ### Value 下返回结果。定位器未匹配到任何内容会耗时 3000ms 并导致命令失败，因此请通过 page.evaluate 读取，并通过定位器执行操作。

视觉问题

布局、位置、颜色、重叠、是否被截断——这些信息既不包含在无障碍树中，也无法从通过的断言中得知。

• check 会根据最终页面的截图判定结果。用户能看到的内容才是证据；运行日志只会说明执行了什么。
• ask "<question>" — 读取截图并以文字作答。用于任何关于外观的开放式问题。
• verify 通过断言验证主张；每条结果都会以其 Playwright 格式返回 PASSED 或 FAILED，不会给出总体结论——请阅读各行并自行判断。FAILED 行下方会附带错误：缺失文本或元素可确定该主张为假，但语法或定位器错误意味着断言并未运行，因此该主张仍未定论。如果没有断言能够表达某个主张，它会报告 "none ran"，而不是判定失败。