跳转至

CLI 参考

English

这一页写给使用 growbridge 命令的人。它列出每个子命令和选项、各自做什么、打印什么,以及怎样退出。

解析器是 cli.py 里的 main()。下面的表格已对照 growbridge --help 和每个子命令的 --help 核对过,版本 0.2.0。本页说的"仅桥接模式"指 auto_research = false。

用法

growbridge [-h] [--version] [--config CONFIG]
           {init,scan,serve,mcp,status,dashboard,operator,host,recovery,export-dataset,simulate} ...

全局选项

全局选项写在子命令前面,例如 growbridge --config /absolute/path/to/config.toml status。

选项 参数 默认值 作用
-h, --help 无 打印帮助并以 0 退出。每个子命令也接受它。
--version 无 打印版本号并以 0 退出。
--config CONFIG,一个路径 ~/.config/spiderfarmer-growbridge/config.toml 要读取的配置文件。对 init 来说是要创建的文件。

子命令

共 11 个子命令。operator、host 和 recovery 各带一个必填的二级子命令。

命令 参数和选项 是否读取配置文件 是否需要守护进程在运行 DiAGRI 模式
init --device DEVICE(必填)、--enable-controls 否,它负责创建 否 不需要
scan 无 否 否 不需要
serve 无 是 它就是守护进程 两种模式都能用
mcp 无 是 是,每个工具都要调用它 两种模式都能用,工具不同
status 无 是 是 两种模式都能用
dashboard --no-open 是 是 两种模式都能用;DiAGRI 模式下控制台不能写入
operator add name(位置参数,必填)、--admin(设为管理员;多用户) 是 否 为它准备;命令本身不检查 auto_research
host register 无 是 否 为它准备;命令本身不检查 auto_research
recovery bump --reason REASON(必填) 是 否,而且必须先停掉 为它准备;命令本身不检查 auto_research
export-dataset --snapshot SNAPSHOT、--out OUT、--licence LICENCE、--creator CREATOR(都必填)、--url URL 是 否,守护进程运行时也能执行 读取 DiAGRI 已记录的数据;命令本身不检查 auto_research
simulate 无 否 否 在临时目录里自建一个 DiAGRI 运行时

没有任何命令可以创建项目、研究协议或研究轮次,也没有命令可以设置项目的调用预算或创建编排 Agent 的第一个任务。这些事由操作员通过工作台路由来做,见运行一轮研究。命令里只有 simulate 会做这些调用,位置在 runtime.py 的 _design_and_start。

每个命令做什么

命令 做什么 打印什么
init 通过 initialize 创建配置文件:上级目录权限 0700,文件权限 0600,共 11 个键。见配置参考。 Configuration created: <path>
scan 扫描 8 秒,找出名字以 SF- 开头的蓝牙设备。它会先以 0700 权限创建 ~/.local/share/spiderfarmer-growbridge。在 macOS 上会编译并运行一个原生辅助程序,其他系统使用 BleakScanner。 一个 JSON 列表,每项包含 name、address 和 rssi
serve 以 0700 权限创建 data_dir,对其中的 daemon.lock 加独占锁,把日志级别设为 INFO,然后一直提供服务直到被停止。仅桥接模式:在 127.0.0.1:<port> 上提供桥接 HTTP API。DiAGRI 模式:见下一张表。 日志
mcp 通过标准输入输出运行 MCP 服务,直到客户端关闭。每个工具都用配置文件里的令牌调用 127.0.0.1:<port> 上的守护进程。仅桥接模式有 8 个工具,DiAGRI 模式有 3 个。见接口参考。 标准输出上的 MCP 协议消息
status 向守护进程发送 GET /status。 返回的 JSON,包含 health、data 和 system 三个键
dashboard 向守护进程发送 POST /ui/session,拼出链接 http://127.0.0.1:<port>/#session=<code>。这个 code 只能用一次,60 秒后过期。不带 --no-open 时会用浏览器打开链接。 不带 --no-open:Dashboard opened. Connection link expires in 60 seconds. 带 --no-open:链接本身
operator add 两次提示输入密码且不回显(Operator secret:、Repeat secret:),然后把操作员存进 data_dir 下的 workflow.sqlite3。密码以加盐的 scrypt 哈希保存。名字长度 1 到 64 个字符,密码 12 到 256 个字符。 Operator added: <name>
host register 读取或创建 data_dir 下的 host_id(权限 0600),并在 control.sqlite3 里把本机登记为 device 的写入主机。它不打开蓝牙连接。在已登记的主机上再次运行也会成功。 Write host registered: <host id>
recovery bump 拿到守护进程锁,构建运行时但不启动,把恢复编号加一,撤销所有写入权,作废排队中的动作,把每个未结束的阶段转入 recovery_check 并作废它的审批。REASON 会随事件一起记录。 Recovery number is now <n>; confirm the safety config and review live stages
export-dataset 把一个冻结快照的训练数据集写进新建的目录 OUT:11 张 CSV 表和 croissant.json。只读取数据库和快照,除假名密钥外不向 data_dir 写任何东西。--licence 和 --creator 记进元数据(创作者记为组织);--url 是数据集发布的地址(如果有)。--licence、--creator 和 --url 两端的空白会被去掉;只有空白的 --url 视为没有。见训练数据集导出。 一个 JSON 对象,包含 out、rows(每个文件的数据行数)和 counts(元数据里的十项计数)
simulate 在临时目录里,用模拟的 AC5 和模拟时钟跑一个很短的阶段:批准安全配置,创建项目、协议和轮次,提交并批准运行单,启动阶段,一直 tick 到阶段结束。不用无线电,也不联网。 一个 JSON 对象,包含 stage、round、beats、samples 和 writes

DiAGRI 模式下的 serve

步骤见 _serve_auto_research 和 _serve_listeners。

顺序 步骤
1 读取 GROWBRIDGE_HEARTBEAT_HOST_URL 和 GROWBRIDGE_HEARTBEAT_RUN_URL:只设一个,命令在这里停下;都不设,就不发心跳并留下常驻警告。然后用 build_runtime(settings, heartbeats=...) 构建运行时。同时读取计算服务的设置(compute_templates_dir、compute_member 和七个 FIRECREST_* 变量),全部齐了才传入计算服务;只配了一部分时,日志里写出缺了哪些,模板有错则命令在这里停下。
2 从 GROWBRIDGE_ROLE_TOKEN_<ROLE> 读取模型角色令牌,并构建工作台路由。有令牌短于 32 个字符时,命令在这一步退出。
3 启动运行时。如果本机不是已登记的写入主机,蓝牙连接保持关闭,并发出一条告警。
4 启动 tick 循环:每秒调用一次 Runtime.tick()(TICK_SECONDS)。
5 如果 roles 不为空并且模型客户端能创建,就启动模型角色:每 30 秒调用一次 Runtime.run_agents()(AGENT_SECONDS)。否则模型角色都不运行。
6 在 127.0.0.1:<port> 上提供桥接路由和工作台路由;lan_bind 和 lan_port 都设置时,同时在 <lan_bind>:<lan_port> 上提供。

export-dataset

步骤在 dataset/command.py 的 export_dataset 里。命令遇到第一个问题就停下,此时除假名密钥外什么都没有写(密钥已经创建后才出现的拒绝,不会把它删掉)。拒绝时在标准错误打印 export refused: <message>,退出码 1。每条消息都说明发现了什么:

拒绝 什么时候
<OUT> already exists; name a directory that does not. --out 已经存在。
The parent of <OUT> does not exist. --out 的上级目录不存在。
<OUT> lies inside the data directory ...; write it elsewhere. --out 就是 data_dir,或在它里面。
<name>.sqlite3 is missing from <data_dir>; this is not a daemon data directory ... archive、workflow 或 agents 缺少数据库文件。导出不会替你建一个空的。
The schema of <name>.sqlite3 is older than this growbridge (...). Start the daemon once with this version, then export. 某个数据库还没有被已安装的版本升级;导出不会去升级它。
The data directory is busy (...); try again. 某个数据库被写入方锁住。
SQLite could not read the data directory: <error>. 读取数据库时出现其他 SQLite 错误,例如文件不是数据库、文件损坏,或这个 growbridge 读不了的数据库结构。<error> 是 SQLite 的报错。
Snapshot <ID> does not exist. 快照不存在。
Snapshot <ID> failed verification: ... 某个快照文件和记录的摘要不再一致。
Snapshot <ID> has no catalog.json; ... 快照冻结时还没有记录目录。
Snapshot file <name> cannot be read、... holds an invalid record 或 ... is not an object 快照文件损坏。
Experiment <ID> must run under exactly one project、protocol version 或 round; found ... 实验的各阶段跑在两个协议版本下或两个轮次里,或者没有项目。导出会说出它发现了什么,不替你挑一个。
Protocol <ID> version <n> is not saved. 协议记录不存在。
Protocol <ID> version <n> cannot describe the dataset: ... crop_taxon 为空或不是 NCBITaxon:<数字>,或 cultivar 超过 200 个字符。
Name the licence ... 或 Name the creator ... --licence 或 --creator 为空。
Measurement <ID> records '<name>', which the variable catalog does not define ... 人工测量的名称不是目录里的变量。
Measurement <ID> is in '<unit>', but <variable> is measured in '<unit>'. 测量的单位和目录不一致。
Variable <ID> is in neither the snapshot's catalog nor the current one. 数据行用到的变量不在任何一个目录里。

成功时退出码 0,并打印 JSON 摘要。不属于上面这些拒绝的失败都以 Python 回溯结束(退出码 1),例如假名密钥不是 32 字节,或写文件时磁盘满了。配置缺失或无效、用法错误的表现和下表一致。

退出行为

情况 涉及的命令 提示信息 退出码
成功 全部 见上表 0
缺少子命令、未知选项、缺少必填参数 全部 用法说明和 growbridge: error: ... 2
配置文件不存在,或没有通过 load 的检查 所有读取配置的命令 Python 回溯(FileNotFoundError、ValidationError、ValueError 等) 1
配置文件已经存在 init 以 FileExistsError 结尾的回溯 1
导出无法进行 export-dataset export refused: <message>,见 export-dataset 1
另一个守护进程持有 data_dir 上的锁 serve A daemon already owns this data directory 2
有模型角色令牌短于 32 个字符 DiAGRI 模式下的 serve growbridge: the token of role '<role>' is shorter than 32 characters 1
守护进程没有应答,或返回了错误 status、dashboard 回溯;返回错误时是带有守护进程 detail 的 RuntimeError 1
密码短于 12 个字符 operator add the secret needs at least 12 characters 2
两次输入的密码不一致 operator add the two entries differ 2
名字为空或过长、密码过长,或操作员已存在 operator add Operators.add 抛出的 ValueError 文本 2
设备已经登记了另一台主机 host register another host is registered for this device 2
data_dir 上有守护进程在运行 recovery bump a daemon is running on this data directory; stop it first 2

每个命令在解析完参数后都把进程的 umask 设为 0o077,所以它创建的文件只有当前用户能访问。

编写本页时没有运行 scan,也没有对真实的 AC5 运行 serve。真机上的行为尚未验证,见状态与已知限制。

另见


页面最近一次对照代码核对是在 2026-11-11。DiAGRI 模式目前只在模拟的 AC5 上测试过,见状态与已知限制。修改页面之前,请先读编写约定。