gherkai-runtime

gherkai 的运行时层：「这个产品有哪两个 AI 引擎、怎么把它们拉起来、云资源叫什么名字、一次 run 怎么组装与推进」 这些知识全收在这里，让任何前端（命令行、Web 界面、云函数）只需写自己的界面与交互。命令行工具 gherkai 就是建在它上面的第一个前端；本包是给要做另一个前端 （Web 界面、自建调度服务、把执行嵌进现有平台）的人。执行模型本身在 gherkai-core，本包负责把引擎、存储、云资源这些对象组装好交给它。

安装

uv add gherkai-runtime            # 或 pip install gherkai-runtime
uv add 'gherkai-runtime[aws]'     # 用到云端（DynamoDB / S3 / Fargate）时需要（拉 boto3）

需要 Python ≥ 3.13。装了 gherkai 命令行的人不用单独装它。

最小用法：在本机跑完一批

from pathlib import Path

from gherkai_core.model import RunMeta
from gherkai_core.schedule import ScheduleOpts, schedule
from gherkai_core.scope import PlanConfig, plan
from gherkai_runtime import compose

features = [compose.load_feature(Path("features/checkout.feature"))]
jobs = plan(features, PlanConfig(default_engine="novaact", default_job_timeout_s=300))

engines = compose.build_engines(region="us-east-1")          # 本机 worker 子进程
meta = RunMeta(run_id=compose.new_run_id(), created_at=compose.now_iso(),
               jobs=tuple(jobs), max_concurrency=2)
result = schedule(meta, compose.make_resolver(engines), print, ScheduleOpts(max_concurrency=2))

要落库就把 store 一起装上：compose.build_local_stores(report_dir=...)（文件）或 compose.build_cloud_stores(...)（DynamoDB + S3），交给核心库的实时写编排即可，两条路复用同一套写序。

主要入口

引擎名是 novaact / midscene（names.ENGINES）。worker 是独立安装的程序，compose.resolve_worker_cmd 负责按顺序找它（环境变量覆写 > 同环境模块 > PATH 上的可执行 > 临时拉起兜底——最后一级仅 novaact 有，且要求 CLI 是正式发行版本、机器上有 uvx；midscene 必须真装），全都找不到时抛 WorkerNotFoundError，报错里自带该引擎的安装命令——你的前端把它原样转述给用户即可。

注意

• 本包会 spawn 子进程、读环境变量、连 AWS（这些正是它替你担的脏活）。纯本机路径不会 import boto3。
• 云端那套资源要先有人用 gherkai deploy 建好；调用方与已部署后端必须同版本，check_backend_skew 就是给你的前端做这个体检的，请在动任何资源之前调它。
• names 里的命名规则与部署侧共用一份实现：别在自己的前端里另拼一套表名/桶名，换 prefix 就会错开。

相关

主页与问题反馈：https://github.com/zhiyanliu/gherkai#readme ｜ https://github.com/zhiyanliu/gherkai/issues

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