gherkai

用 Gherkin 写 UI 自动化测试，让 AI 浏览器代理去跑。你写 .feature（自然语言步骤 + 断言），gherkai 把它解析成可并发的执行批次，派给你选的 AI 引擎（Midscene / Nova Act）在 AWS 云端浏览器里真实操作页面、判定断言，最后把每条用例的判定、日志与可点开的报告归集成一份结果。两种跑法：在本机跑（worker 起在你的机器上、结果落本地目录），或整批跑在云端（worker 跑 Fargate 容器、状态与报告落 DynamoDB/S3，提交完就能关掉终端）。

安装

uv tool install gherkai                     # CLI 本体（只提交云端 run 的人装这一条就够）
uv tool install 'gherkai[local]'            # 顺带装上在本机跑 Nova Act 引擎所需的 worker
npm i -g @gherkai/worker-midscene           # 在本机跑 Midscene 引擎的 worker（Node ≥ 22）
uv tool install 'gherkai[deploy-aws]'       # 部署方：要用 gherkai deploy 建/改云端后端（另需 Node ≥ 22 + 容器引擎）
uvx gherkai --version                       # 或者不安装、临时跑一次
pipx install --fetch-python missing gherkai   # 不用 uv 的人：pipx 回落（pipx 默认不下载解释器，本项目要 Python ≥ 3.13；装 extra 写 'gherkai[local]'）

需要 Python ≥ 3.13。两个引擎的 worker 是各自独立的程序：Nova Act 走上面的 [local] extra，Midscene 是 Node 包走 npm；只用 --backend cloud 提交的人两个都不用装（worker 跑在云端）。gherkai list-engines 会告诉你当前哪个引擎可用、缺的那个怎么装。

前置（AWS）

• AWS 凭证（默认 profile 即可）与 region（--region，或 AWS_REGION / AWS_DEFAULT_REGION / profile 配置），当前验证过的 region 是 us-east-1。
• 账号需开通：Bedrock 模型访问（Midscene 用 qwen.qwen3-vl-235b-a22b）、AgentCore Browser（bedrock-agentcore）、Nova Act（nova-act + 模型 nova-act-latest）。
• --backend cloud 还需要有人先跑过 gherkai deploy 把云端后端建好（见下「部署」）；只有用 --expose-local 测本机应用时才需要 ngrok authtoken（免费账号即够，ngrok config add-authtoken <token> 或环境变量 NGROK_AUTHTOKEN）。

上手

gherkai plan features/checkout.feature                  # 预检：看分组、校验写法与配置，不连云、不花钱
gherkai run  features/checkout.feature                  # 前台真跑（会产生模型调用与浏览器会话费用）
RUN_ID=$(gherkai submit features/*.feature --max-concurrency 2)   # 提交完就走
gherkai status "$RUN_ID" --wait --json                  # 事后轮询到跑完，输出机器可读结果

plan 不花钱，run 每次都花真钱——先 plan 后 run 能提前暴露写法冲突、把钱省在真跑之前。plan 还会逐步骤标注派发预期（哪些步骤会命中你写的确定性步骤、哪些交给 AI 判定）。

两个旋钮决定一次 run 长什么样：跑在哪 / 落在哪 由 --backend 定（local = worker 跑本机、结果落 --report-dir；cloud = worker 跑 Fargate 容器、状态落 DynamoDB、判定与报告落 S3）；用哪个引擎 在 feature 里逐 scope 标 @engine:midscene / @engine:novaact，没标的用 --default-engine（默认 novaact，标了 tag 的不受它影响）。

命令

run 要求 CLI 全程在线（网断、关机即中止）。submit 把「提交」和「收结果」拆开：local 档在本机起一个脱离 CLI 的后台进程推进，cloud 档交给云端推进（提交完真关机也能跑完）。status --wait 既是查询也是接力——后台进程崩了或卡住，来查的这条命令会把它续到底。

status 的 --backend / --report-dir / --prefix（cloud）必须与 submit 时一致，否则查不到这个 run（--report-dir 在 cloud 档是后端的报告前缀，默认 reports，同样用来拼终态时打出的 S3 位置）。explain 用同一套定位参数。

explain 答的是「为什么这么判」：它按用例的书写顺序列出每一步，失败/出错/被跳过的步展开成「问了 AI 什么 → AI 每一步看见与想了什么 → 截图在哪」。文本形态是摘要（每次 AI 调用默认只打最后一段推理，--full 打全），--json 带完整证据。哪一步没有机读证据（确定性步本就不产，或抽取当时失败了），它会明说，并给出该步其它产物的链接。

steps/ 目录：你自己的确定性步骤

URL、DOM 这类不容 AI 抖动的检查，可以由你自己写成确定性步骤：在项目里建一个 steps/ 目录，Nova Act 引擎放 .py、Midscene 引擎放 .mts（或 .mjs），命中的步骤走你的精确实现、不进 AI 判定。目录按 --steps-dir > 环境变量 GHERKAI_STEPS_DIR > ./steps 解析。

目录里任何一个文件加载失败就整批拒跑（plan / run / submit 都在起第一个 job 之前拒，并转述具体错误），显式给的 --steps-dir 不存在也直接退 2——静默跳过等于把这些步骤悄悄换回 AI 判定。--backend cloud 下这个 flag 不生效（只警告、不拦）：云端 worker 的步骤是烙进镜像的，见下。

云端跑哪套步骤：worker 镜像 variant

一个 variant = 一套具名的确定性步骤集 = 一个定制 worker 镜像（名字自取，如 base / login / checkout-v2；须合镜像 tag 字符集——字母/数字/下划线开头，其后可含 . -——不合法在开跑前就报错）。提交时用 --worker-variant <名> 选，不给就用后端的默认指针（部署时初始化为 base = 零步骤的基底）。提交侧会把这个名字定成本次 run 用的确切镜像，所以 run 期间别人重推同名 variant 不影响正在跑的 run；多人共用一个后端时各推各的、互不覆盖。某个引擎缺这个 variant 会直接退 2 并给出修复命令，不会悄悄回落到默认（那等于替你换掉一套步骤集）。镜像怎么 build 和推送见 部署方页面。

常用选项（run / submit）

云端专用（--backend cloud）：--prefix（默认 gherkai-，须与部署时一致；环境变量 AWS_RESOURCE_PREFIX）一把决定表/桶/集群等资源名；要单独覆盖就用 --ddb-table（AWS_DDB_TABLE）/ --s3-bucket（AWS_S3_BUCKET）；--worker-variant 见上；run 还可用 --events-table / --cluster 覆盖资源名、--subnet / --security-group 覆盖网络（不给则读部署时写下的值）。submit 只按 --prefix 推事件表与集群名（那两个名字对提交无影响，给了会退 2）。

输出与报告

stdout 只放该命令的核心产出（--json 的 JSON、人看的文本汇总、列表），进度与诊断全走 stderr——所以 gherkai run … --json > r.json 拿到的是纯净 JSON，进度仍在终端可见。每次 run 默认在 reports/<run_id>/ 留一份报告：index.html 是可点开的入口（判定明细 + 每条报告产物一行链接：引擎自己的报告产物与每个 AI 步骤的证据各一行），manifest.json 是给 CI/工具消费的清单。

退出码

分界线是「有没有真的开跑」：开跑前的配置与可达性问题退 2，跑到一半的故障退 1。submit 与 status 各答不同的问题——submit 的退出码只说「提交成功了吗」（判定此刻还没出），status 的退出码只在读到终态时才表判定（通过 0 / 其余终态 1 / 查不到这个 run 2）；CI 想拿 run 那样的 0/1 判定码，用 status --wait。explain 只说「证据读出来了吗」、从不表判定：用例失败它照样退 0（判定看 run / status --wait），只有参数写错（如 --step 没同时给 --scenario）、run 或 scope 查不到、云端读不到才退 2。

CLI 要和后端同版本

部署时后端记下自己的版本，--backend cloud 的每条命令在动任何资源之前先比对：

• CLI 比后端新 → 直接拒绝（退 2），没有强行放行的开关。 两条出路：① 部署方跑 gherkai deploy 把后端升上来；② 用与后端同版本的 CLI 临时跑，不动本机安装：uvx --from 'gherkai==<后端版本>' gherkai …。
• CLI 比后端旧 → 只警告不拦，uv tool upgrade gherkai 跟上即可。升级就是三步：① 部署方 uv tool upgrade gherkai（安装时带的 extras 会沿用）；② 立刻 gherkai deploy；③ 其他人再升自己的 CLI（中间窗口里提交会被拒，这是预期）。

部署（只有部署方需要）

云端那套后端（DynamoDB 表、S3 桶、ECS 集群与任务定义、推进用的 Lambda、VPC 与安全组）由 gherkai deploy 建。它装在单独的 extra 里，团队里只提交 run 的人不必装：

uv tool install 'gherkai[deploy-aws]'                       # 另需 Node ≥ 22 在 PATH
gherkai deploy --bootstrap                                  # 每个账户 + region 一次性初始化
gherkai deploy --diff --vpc default --prefix gherkai-       # 先看清这次会改什么（不改账户）
gherkai deploy --vpc default --prefix gherkai-              # 真部署
gherkai deploy --synth-only ./out --vpc default             # 只导模板给自己的审批流水线，不让本工具碰账户
gherkai destroy --vpc default --prefix gherkai- --yes       # 拆掉（表/桶/镜像仓库保留、不随之删；--yes 是给脚本/非交互用的）

• --vpc 必给、没有隐式默认（只有 --bootstrap 不需要，那是账户级动作）：default（账户默认 VPC）/ new（本次新建，2 个可用区、零 NAT）/ vpc-<id>（复用现有）。这是真踩过的坑：漏掉它会合成出「新建整套 VPC + 换掉 worker 安全组」这种危险变更。生效的档记在后端，第二次敲错档会被拒（退 2）；确认这确实是你要的网络变更后加 --allow-vpc-change 放行一次（本机制之前部署的环境第一次也需要它，先 --diff 核对）。
• --prefix（默认 gherkai-）是全部云资源的命名空间，须与 run/submit/status 的 --prefix 一致；换 prefix 就是换一套独立环境（prod- / stage-），闲置成本近零。
• 其他 flag：--require-approval never|any-change|broadening（权限变更要不要人过目）、--stop-timeout（容器关闭宽限秒，标定 --grace 用）、--refresh-context（丢弃本机缓存的网络查询结果重查）、--region / --profile。--diff / --synth-only DIR / --bootstrap 三者互斥，都不给就是真部署。
• worker 镜像的推送与管理（gherkai deploy push-worker / list-workers）、资源清单与费用见 部署方页面。

遇到问题

gherkai --help / gherkai <命令> --help 有全部选项，报错都带「怎么办」。项目主页 https://github.com/zhiyanliu/gherkai#readme ，问题反馈 https://github.com/zhiyanliu/gherkai/issues 。

设计文档（架构决策记录）见 https://github.com/zhiyanliu/gherkai/tree/HEAD/docs/adr