跳转至

配置参考

English

这一页写给安装和运维 DiAGRI 的人。它列出配置文件的每个字段、加载时做的检查,以及哪些值只从环境变量读取、从不写进文件。

字段定义在 config.py 的 Settings 和 RoleModel 里。本页说的"仅桥接模式"指 auto_research = false,也就是默认值。

配置文件

项目 值
格式 TOML
默认路径 ~/.config/spiderfarmer-growbridge/config.toml,由 default_config() 给出
指定其他路径 growbridge --config /absolute/path/to/config.toml <command>
谁会读它 除 init、scan、simulate 以外的所有命令(见 CLI 参考)
未知的键 拒绝加载:Settings 和 RoleModel 都设置了 extra="forbid"

Settings 字段

共 27 个字段。"必填"表示没有默认值。最后一列说明该字段是否只在 DiAGRI 模式下起作用。

字段 类型 默认值 允许的取值 作用 仅 DiAGRI
device 字符串 必填 任意字符串 AC5 的地址或 UUID,取 growbridge scan 在本机打印的值。 否
token 字符串 必填 至少 24 个字符 桥接 HTTP API 的 Bearer 令牌。CLI 和 MCP 服务从这个文件读取它。在 DiAGRI 模式下它只能读、不能写。 否
data_dir 路径 必填 任意路径;~ 会展开 存放数据库、daemon.lock 和 host_id 的目录。 否
port 整数 8766 1024 到 65535 127.0.0.1 上监听的端口。在 DiAGRI 模式下,只有从这个端口进来的请求才可能属于覆盖网络入口。 否
controls_enabled 布尔 false true、false 是否允许写设备。为 false 时,桥接 API 返回 409,控制服务以 controls_disabled 拒绝。 否
stale_seconds 数值 20 5 到 120 最新样本超过多少秒算过期(health.stale)。普通写入要求数据新鲜。 否
max_pump_seconds 数值 5 大于 0,不超过 60 水泵单次运行的最长秒数。仅桥接模式下约束 POST /pump,DiAGRI 模式下约束 POST /wb/irrigation。 否
pump_cooldown_seconds 数值 60 不小于 0 两次开泵之间的最短间隔,单位秒。 否
pump_outlet 整数 4 1 到 5 水泵接在哪个插座。 否
light_outlet 整数 1 1 到 5 灯接在哪个插座。 否
exhaust_outlet 整数 2 1 到 5 排风扇接在哪个插座。 否
fan_outlet 整数 3 1 到 5 循环风扇接在哪个插座。 否
retention_days 整数 30 1 到 365 守护进程的样本库保留多少天的样本。在 DiAGRI 模式下,只删除已经复制到项目档案的样本。 否
auto_research 布尔 false true、false 把守护进程切换到 DiAGRI 模式:启动运行时和工作台路由,三个桥接写入路由返回 403,MCP 服务只提供读取工具。 它就是开关
multi_user 布尔 false true、false 与 auto_research 一起打开工作台的多用户:带角色的账号、温室锁定、项目所有者、每人只看自己的(见多用户)。关闭时工作台与以前一样。 是
greenhouses 表的列表 [] 每项 {id, name, device_id};id 形如 [a-z0-9][a-z0-9-]{0,31};编号与设备各不重复;device 必须在其中 操作员可以锁定的温室。为空时只有一个温室 gh-01,对应 device。 是
lan_hosts 字符串列表 [] 主机名或地址;端口部分会被忽略 局域网入口的地址。它们会加入受信任主机和允许的浏览器来源。 是
overlay_hosts 字符串列表 [] 主机名或地址;端口部分会被忽略 覆盖网络入口的地址。它们会加入受信任主机和允许的浏览器来源(按 https://)。 是
lan_bind 字符串 "" 本机的一个地址 局域网监听绑定的地址。只有 lan_bind 和 lan_port 都设置了,这个监听才会启动。 是
lan_port 整数或不设置 不设置 1024 到 65535 局域网监听的端口。请求必须从这个端口进来,并且 Host 在 lan_hosts 里,才属于局域网入口。不设置就没有局域网入口。 是
report_time 字符串 "08:00" 24 小时制 HH:MM,00:00 到 23:59 每天从这个本地时间起生成前一天的日报。只有存在活动阶段时才生成日报。 是
report_timezone 字符串 "UTC" 主机认识的 IANA 时区名 report_time 和日报日期所用的时区。操作员控制台显示和录入时间也用这个时区(由 GET /wb/me 的 timezone 给出)。未知的时区名在加载时被拒绝。 是
roles RoleModel 表 {} 键是角色名 每个模型角色的模型配置。为空时,serve 不创建模型客户端,模型角色都不运行。 是
backup_dir 路径或不设置 不设置 任意路径;~ 会展开 SQLite 在线备份的目录。不设置就没有备份,运行时启动时会发出一条 backup_unconfigured 警告级告警。 是
backup_interval_seconds 数值 21600 不小于 60 两次备份之间的秒数。 是
compute_templates_dir 路径或未设置 未设置 一个存放 *.json 文件的目录;~ 会被展开 每个 JSON 文件是一个审核过的作业模板(JobTemplate)。与 compute_member 和七个 FIRECREST_* 变量一起启用计算服务。启动时逐个校验;有坏文件时 serve 启动失败,错误信息指出文件名。 是
compute_member 字符串或未设置 未设置 至少 1 个字符 研究 Agent 的作业以哪个 CSC 账户名提交。 是

report_time 的准确模式是:

^([01]\d|2[0-3]):[0-5]\d$

同时出现在 lan_hosts 和 overlay_hosts 里的主机,不属于任何入口(见 workbench/auth.py 的 entry_for)。

RoleModel 字段

共 9 个字段。roles 的每个键对应一个 RoleModel,写成 [roles.<role>] 表。这些字段都只在 DiAGRI 模式下起作用。

字段 类型 默认值 允许的取值 作用
provider 字符串 "anthropic" "anthropic" 模型提供方。代码里只有 AnthropicClient 这一个客户端。
model 字符串 "claude-opus-5-5" 任意字符串 该角色每次请求使用的模型名。只有默认模型有内置单价(agents/llm.py 的 DEFAULT_PRICE);换成其他模型时必须同时设置 input_per_mtok 和 output_per_mtok,否则加载时被拒绝。
effort 字符串 "medium" low、medium、high、xhigh、max 每次请求以 output_config.effort 发送。
max_tokens 整数 16000 256 到 64000 每次请求的 max_tokens。
max_calls 整数 20 不小于 1 该角色一次运行最多调用模型的次数(agents/loop.py 里 run_agent 的 max_turns)。达到上限时运行以 max_turns 结束,任务转为 needs_attention。项目调用预算(agents/budget.py)同时生效。
tools 字符串列表 [] 该角色的工具名(见接口参考) 收窄该角色可用的工具。为空表示角色允许的全部工具。写入控制类工具或其他角色的工具,角色运行时会以 model_role 被拒绝,任务转为 needs_attention。
data 字符串列表 [] 任意字符串 加载时会校验,但没有代码读取它:它不限制角色能读到什么。
input_per_mtok 数字或不设置 不设置 不小于 0 model 每百万输入 token 的价格(美元),用于费用预算。要和 output_per_mtok 一起设置。model 不是默认模型时必填。
output_per_mtok 数字或不设置 不设置 不小于 0 model 每百万输出 token 的价格(美元)。要和 input_per_mtok 一起设置。

会被读取的角色名是 orchestrator、planner、researcher 和 auditor(agents/tools.py 的 ROLE_TOOLS)。其他键能通过校验,但会被忽略。只要 roles 里有一个键,没有列出的角色就按上表的默认值运行,监察 Agent 除外:它的默认值是默认模型,每次监察最多 8 次模型调用(AUDIT_MAX_CALLS);配置了 [roles.auditor] 就会替换这个默认值,所以不想要 8 次时要在那里设置 max_calls(runtime_agents.py 的 make_dispatcher)。

作业模板文件

compute_templates_dir 里的每个 *.json 文件是一个 JobTemplate(compute/backend.py)。serve 启动时逐个校验,第一个有错的文件会让它停下,并指出文件名。规则如下:

字段 规则
id、version 这一对在所有文件里必须唯一。同一个 id 的最新版本是实际运行的版本;被重试的尝试所用的版本已被取代时,重试会被拒绝。
script Slurm 批处理脚本。必须以 #! 开头,必须设置运行时限(#SBATCH --time=... 或 -t),让作业有界,且不能自己设置作业名(服务会加上 gb-<尝试编号>)。参数只以 DIAGRI_PARAM_<NAME> 传入,输入以 DIAGRI_INPUT_<NAME> 传入;结果写进 DIAGRI_OUTPUT_DIR。
parameters 名字必须能用作环境变量名。kind 是 int、float、str 或 bool。数值可以有 minimum 和 maximum,浮点数必须是有限的。str 必须列出 choices,或者声明 pattern:整个取值都要匹配的正则表达式。max_length 可以进一步限制长度;任何文本都不超过 1000 个字符,含控制字符的值一律被拒绝。default 本身也要通过这些规则。没有 default 的参数是必填的。
max_cpu_hours、max_storage_gb 有限的数,0 或更大。这是一次尝试预留的量;接口不报告用量时,也按它计账。max_storage_gb(十进制 GB)同时是一次取回产物的上限:一个作业的产物合计最多这么多字节、最多 1000 个文件,否则在下载任何东西之前就拒绝取回;每次下载都被看着,文件一超过剩余额度就取消传输,已下载的文件会被删除(磁盘上可能短暂地多出一点,最多是链路在 0.25 秒内传送的量)。每个产物在 FirecREST 的列表里都必须带有大小,否则拒绝取回。
result_changing 参数名的列表,每个都必须存在。重试时改了其中之一,就开始新的分析版本。
max_retries 默认 2。

load 做哪些检查

每个需要读配置的命令都会调用 load。CLI 不捕获这些错误,命令会带着回溯信息退出。

顺序 检查 不通过时的错误
1 指定路径或默认路径上有这个文件(~ 会展开)。 FileNotFoundError
2 文件是合法的 TOML。 tomllib.TOMLDecodeError
3 有 data_dir。 KeyError
4 每个字段符合上面两张表的类型、范围和模式,并且没有未知的键。report_timezone 是已知时区。使用非默认模型的角色写明了两个单价。 pydantic.ValidationError
5 pump_outlet、light_outlet、exhaust_outlet、fan_outlet 是四个不同的编号。 ValueError: Each device must have a separate outlet

load 不读取模板文件,serve 在启动时检查它们。load 不检查这些:data_dir、backup_dir 和 compute_templates_dir 是否存在,lan_bind 和 lan_port 是否成对设置,roles 里的角色名,以及 tools 里的工具名。

initialize 写入什么

growbridge init --device DEVICE 调用 initialize。它以 0700 权限创建上级目录,以 0600 权限创建文件。它从不覆盖:文件已存在就失败。它写入下面 11 个键,不写任何 DiAGRI 字段。

键 写入的值
device --device 参数
token 由 secrets.token_urlsafe(32) 新生成的随机值
data_dir ~/.local/share/spiderfarmer-growbridge,写成绝对路径
controls_enabled false;带 --enable-controls 时为 true
port 8766
max_pump_seconds 5
pump_cooldown_seconds 60
light_outlet 1
exhaust_outlet 2
fan_outlet 3
pump_outlet 4

从不写进文件的值

凭据从 growbridge serve 进程的环境变量读取,全部只在 DiAGRI 模式下起作用。向真实的 Telegram 和 SMTP 服务投递尚未验证,见状态与已知限制。

变量 在哪里读取 是什么 规则
代码里没有写出变量名 agents/llm.py 的 AnthropicClient 模型凭据 客户端用不带参数的 anthropic.AsyncAnthropic() 创建,凭据由 SDK 从它自己的环境变量解析。测试里设置的是 ANTHROPIC_API_KEY。SDK 属于可选依赖 agents。客户端创建不了时,serve 记一条警告日志,发出 model_client 告警,然后在没有模型角色的情况下继续运行。
GROWBRIDGE_ROLE_TOKEN_<ROLE> cli.py 的 role_tokens_from_env 模型角色调用工作台路由时用的 Bearer 令牌。角色 ID 是后缀的小写形式。 至少 32 个字符,否则 serve 在启动任何东西之前就退出。空值会被忽略。
GROWBRIDGE_TELEGRAM_TOKEN runtime.py 的 default_channels,observer/channels.py 的 TelegramChannel Telegram 机器人令牌 只有它和 GROWBRIDGE_TELEGRAM_CHAT_IDS 都设置了,才有 telegram 渠道。
GROWBRIDGE_TELEGRAM_CHAT_IDS default_channels 接收通知的 chat ID 用逗号分隔。
GROWBRIDGE_EMAIL_TO default_channels 邮件通知的收件人 用逗号分隔。只有它和 GROWBRIDGE_SMTP_HOST 都设置了,才有 email 渠道。
GROWBRIDGE_SMTP_HOST default_channels,observer/channels.py 的 _smtp_send SMTP 服务器 连接总是使用 STARTTLS。
GROWBRIDGE_SMTP_PORT _smtp_send SMTP 端口 默认 587。
GROWBRIDGE_SMTP_USER _smtp_send SMTP 登录名 不设置就不登录。
GROWBRIDGE_SMTP_PASSWORD _smtp_send SMTP 密码 默认为空。
GROWBRIDGE_SMTP_FROM _smtp_send 发件人地址(From) 默认是 SMTP 登录名;没有登录名时是 growbridge@localhost。
FIRECREST_URL compute/firecrest.py 里的 FirecrestBackend FirecREST API 的基础地址,例如 https://api.roihu.csc.fi/v1(FirecREST v2)。 属于"要么全配、要么都不配"的计算服务设置:这九项(这七个变量加 compute_templates_dir、compute_member)缺任何一项,计算服务都不会启动,日志只写缺了哪些名字,不写取值。
FIRECREST_TOKEN_URL compute/firecrest.py 里的 FirecrestBackend 机器人账户的 OAuth 令牌地址,例如 https://user-auth.csc.fi/idp/profile/oidc/token。 属于"要么全配、要么都不配"的计算服务设置:这九项(这七个变量加 compute_templates_dir、compute_member)缺任何一项,计算服务都不会启动,日志只写缺了哪些名字,不写取值。
FIRECREST_CLIENT_ID compute/firecrest.py 里的 FirecrestBackend CSC 机器人账户的客户端 ID(即账户名)。 属于"要么全配、要么都不配"的计算服务设置:这九项(这七个变量加 compute_templates_dir、compute_member)缺任何一项,计算服务都不会启动,日志只写缺了哪些名字,不写取值。
FIRECREST_CLIENT_SECRET compute/firecrest.py 里的 FirecrestBackend 机器人账户的客户端密钥(即它的密码)。不写日志,不进错误信息,不出现在 repr 里。 属于"要么全配、要么都不配"的计算服务设置:这九项(这七个变量加 compute_templates_dir、compute_member)缺任何一项,计算服务都不会启动,日志只写缺了哪些名字,不写取值。
FIRECREST_SYSTEM compute/firecrest.py 里的 FirecrestBackend Roihu 的子系统:只接受 cpu 或 gpu。 属于"要么全配、要么都不配"的计算服务设置:这九项(这七个变量加 compute_templates_dir、compute_member)缺任何一项,计算服务都不会启动,日志只写缺了哪些名字,不写取值。
FIRECREST_ACCOUNT compute/firecrest.py 里的 FirecrestBackend 作业计费的 CSC 项目,例如 project_2001234。只允许字母、数字和 _。 属于"要么全配、要么都不配"的计算服务设置:这九项(这七个变量加 compute_templates_dir、compute_member)缺任何一项,计算服务都不会启动,日志只写缺了哪些名字,不写取值。
FIRECREST_WORKDIR compute/firecrest.py 里的 FirecrestBackend 远端工作目录的绝对路径,每个作业在其下有自己的 gb-<尝试编号> 目录,例如 /scratch/project_2001234/diagri。不能含 ..。 属于"要么全配、要么都不配"的计算服务设置:这九项(这七个变量加 compute_templates_dir、compute_member)缺任何一项,计算服务都不会启动,日志只写缺了哪些名字,不写取值。

两个渠道都没有配置时,不会有任何通知入队。告警照常记录,GET /wb/alerts 可以看到,运行时启动时还会发出一条 notify_unconfigured 警告级告警(runtime.py 的 build_runtime 和 Runtime.start)。

冻结读数门槛(SafetyConfig.frozen)

它不在配置文件里:门槛是已批准安全配置的一个字段 SafetyConfig.frozen,类型是 archive/models.py 里的 FrozenCheck。它和其余安全限值一起由人批准(POST /wb/safety/approve),工作台的安全页会显示。观察者会标出读数持续完全不变、超过门槛的传感器。

字段 类型 默认值 校验 作用
minutes 传感器名到数字的字典 {"temp": 120, "humi": 60, "co2": 60, "tempSoil": 240}(DEFAULT_FROZEN_MINUTES,每份配置各拿一份副本) 每个值必须大于 0 且不超过 1440(0、负数、NaN、无穷大和超过 1440 的值都会被拒绝)。允许空字典,意思是不检查任何传感器。批准时,设备没有的传感器名会被拒绝(approval_invalid);AC5 有 temp、humi、vpd、co2、ppfd 和 tempSoil。拼错的名字因此不会悄悄关掉某项检查。 传感器读数保持不变多少分钟后算冻结。没有写在里面的传感器不检查。
max_gap_seconds 数字 600 大于 0 且不超过 3600(NaN、无穷大和更大的值会被拒绝)。 两次读数之间最长多少秒的空档,仍算同一段不间断的相同读数。

没有批准过安全配置时,门槛用上面的默认值。这个字段出现之前存下来的安全配置没有 frozen,读出来时用默认值。

没有对应配置项的功能

功能 代码里的现状
外部心跳(ExternalMonitor、HeartbeatChannel) Settings 里没有字段,由环境变量 GROWBRIDGE_HEARTBEAT_HOST_URL 和 GROWBRIDGE_HEARTBEAT_RUN_URL 设置。两个都设或者都不设:只设一个,serve 拒绝启动;都不设,发出警告 monitor_unconfigured。URL 是机密,不会写进日志。见通知、日报与备份。
计算服务(ComputeService) 由 compute_templates_dir、compute_member 和七个 FIRECREST_* 环境变量设置,要么全配、要么都不配。全配:serve 在 FirecrestBackend 上创建计算服务。都不配:没有计算服务。配了一部分:没有计算服务,日志里警告缺了哪些名字。模板有错、没装 pyfirecrest,或 FIRECREST_SYSTEM、FIRECREST_ACCOUNT、FIRECREST_WORKDIR 无效,都会让 serve 启动失败。没有对真实的 CSC 服务验证过;见状态与已知限制。
告警规则 Settings 里没有字段。runtime.py 的 DEFAULT_ALERT_RULES 是空的。
操作员账号 由 growbridge operator add 存进 data_dir,不在配置文件里。

多用户

multi_user = true(且 auto_research = true)时,每个操作员有一个角色:user 或 admin(第一个管理员用 growbridge operator add --admin 创建)。操作员在控制台的「温室」页锁定温室;项目归创建它的人;动一个阶段既要是项目所有者,又要锁着这个阶段的温室。操作员只看到自己的项目、阶段、告警和回执;管理员看到全部,紧急时可以暂停或停止任何阶段,管理账号、强制释放温室,并把无人负责的项目转给别人。释放温室时交还养护规则,设备保持当前设置。设计见 docs/superpowers/specs/2026-11-16-multi-user-locks-design.md。

在已有部署上打开。 先用 growbridge operator add --admin <名字> 创建第一个管理员。打开之前建的项目都没有所有者:只有管理员能看到,任何人都不能操作,直到管理员把它转出(「管理」页,或 POST /wb/admin/projects/{project_id}/owner);转移要求项目没有未结束的阶段。升级时还开着的告警也没有归属:只给管理员看,其中一部分会带着归属再出现一次,所以会收到一轮重复通知。

multi_user = true

[[greenhouses]]
id = "gh-01"
name = "温室 1"
device_id = "SF-GGS-PS5"

示例

最小的仅桥接模式配置。控制保持关闭。

device = "YOUR_SCANNED_ADDRESS"
token = "REPLACE_WITH_AT_LEAST_24_CHARACTERS"
data_dir = "/absolute/path/to/data"

最小的 DiAGRI 配置:两个入口、备份,以及四个都用默认值的模型角色。

device = "YOUR_SCANNED_ADDRESS"
token = "REPLACE_WITH_AT_LEAST_24_CHARACTERS"
data_dir = "/absolute/path/to/data"
controls_enabled = true
auto_research = true
lan_hosts = ["YOUR_PI_LAN_ADDRESS"]
lan_bind = "YOUR_PI_LAN_ADDRESS"
lan_port = 8767
overlay_hosts = ["YOUR_PI_OVERLAY_NAME"]
backup_dir = "/absolute/path/to/backup"

[roles.orchestrator]

[roles.planner]

[roles.researcher]

另见


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