HTTP、工作台与 MCP 接口¶
这一页写给用程序调用 DiAGRI 的开发者和操作员。它列出桥接 HTTP 路由、工作台路由、两种模式下的 MCP 工具,以及每个模型角色的工具。
本页说的"仅桥接模式"指 auto_research = false。拒绝码的含义见拒绝码与事件类型。这些表格是对照代码和测试核对的,而测试只在模拟的 AC5 上运行,见状态与已知限制。
操作员通过下面的工作台路由创建项目、研究协议和研究轮次,设置项目的调用预算,并创建编排 Agent 的第一个任务;运行一轮研究按顺序演示了这些请求。CLI 命令和模型工具都做不了这些事。growbridge simulate 直接做同样的服务调用,位置在 runtime.py 的 _design_and_start。WorkflowService 还有 switch_run_sheet 和 revoke_approval 两个方法,没有任何路由、命令或工具调用它们。
监听¶
| 监听 | 地址 | 模式 | 提供什么 |
|---|---|---|---|
| 回环 | 127.0.0.1:<port> |
两种模式 | 桥接路由;DiAGRI 模式下还有工作台路由。从这个端口进来、Host 在 overlay_hosts 里的请求属于覆盖网络入口。 |
| 局域网 | <lan_bind>:<lan_port> |
DiAGRI 模式,且两个字段都已设置 | 同一个应用。从这个端口进来、Host 在 lan_hosts 里的请求属于局域网入口。 |
请求的 Host 必须是 localhost、127.0.0.1、testserver(供测试客户端使用),或者在 DiAGRI 模式下是 lan_hosts、overlay_hosts 里的地址;否则在进入任何路由之前就返回 400。
桥接 HTTP API¶
来源:api.py 的 create_app。共 14 个路由和一个静态挂载。
| 认证方式 | 含义 |
|---|---|
| 无 | 不需要凭据。 |
| 令牌 | 请求头 Authorization: Bearer <token>,token 取自配置文件。 |
| 令牌或会话 | 带上面的令牌请求头;没有 Authorization 请求头时,用 Cookie growbridge_session,这时除 GET 和 HEAD 以外的方法还需要允许的 Origin 和请求头 X-GrowBridge-UI: 1。 |
| 方法 | 路径 | 认证方式 | 输入 | 返回 | DiAGRI 模式下 |
|---|---|---|---|---|---|
GET |
/ |
无 | 无 | 控制台页面 index.html。 |
不变 |
| 挂载 | /assets |
无 | 文件路径 | web/ 下的静态文件。 |
不变 |
POST |
/ui/session |
令牌 | 无 | code 和 expires_in(60)。code 只能用一次。 |
不变 |
POST |
/ui/session/redeem |
无;但 Origin 必须在允许范围内 |
请求体 code(20 到 100 个字符) |
{"connected": true},并设置 Cookie growbridge_session(HttpOnly、SameSite=Strict、12 小时)。 |
不变;入口地址也算允许的来源 |
POST |
/ui/logout |
令牌或会话 | 无 | {"connected": false}。撤销会话并删除 Cookie。 |
不变 |
GET |
/ui/settings |
令牌或会话 | 无 | stale_seconds、max_pump_seconds、pump_cooldown_seconds、pump_ready_at、retention_days。 |
不变 |
GET |
/health |
令牌或会话 | 无 | connected、protocol_version、controls_enabled、pump_off_unconfirmed、last_sample_at、age_seconds、stale、last_error、outlet_mapping。 |
不变 |
GET |
/status |
令牌或会话 | 查询参数 refresh(布尔,默认 false) |
health、data、system。带 refresh 时先向设备查询一次。 |
不变 |
GET |
/history |
令牌或会话 | 查询参数 hours(大于 0,不超过 168,默认 24)、limit(1 到 2000,默认 500) |
samples:由 timestamp 和 data 组成的列表。 |
不变 |
GET |
/history/series |
令牌或会话 | 查询参数 hours(同上)、points(2 到 2000,默认 600) |
samples、window、total_samples、downsampled。 |
不变 |
GET |
/activity |
令牌或会话 | 查询参数 limit(1 到 100,默认 20) |
operations:由 request_id、action、params、state、requested_at 组成的列表。 |
不变 |
GET |
/history/export.csv |
令牌或会话 | 查询参数 hours(同上) |
文件 growbridge-history.csv:timestamp_utc、六个传感器列、outlet_1_on 到 outlet_5_on、light_level、exhaust_level、fan_level。 |
不变 |
POST |
/control/{device} |
令牌或会话 | 路径参数 device:light、exhaust 或 fan;请求体 request_id、level(整数 0 到 100;风扇是 0 到 10) |
一张回执:request_id、action、completed_at 和确认后的状态。 |
拒绝:403 |
POST |
/outlet |
令牌或会话 | 请求体 request_id、number(1 到 5)、on(布尔) |
同上的回执。 | 拒绝:403 |
POST |
/pump |
令牌或会话 | 请求体 request_id、seconds(大于 0,不超过 60,且不超过 max_pump_seconds) |
同上的回执。 | 拒绝:403 |
request_id 长度 8 到 100 个字符,只能用字母、数字、_ 和 -。请求体里有未知字段会被拒绝。DiAGRI 模式下,三个写入路由在检查请求体之前就被拒绝,detail 是 Device writes go through the workbench。
| 状态码 | 什么情况 |
|---|---|
| 401 | 没带令牌或令牌不对(Authentication required);没有有效会话(Open the dashboard with growbridge dashboard to connect);code 已用过或已过期。 |
| 403 | Origin 不在允许范围内;缺少请求头 X-GrowBridge-UI;在 DiAGRI 模式下调用写入路由。 |
| 404 | device 不是 light、exhaust 或 fan。 |
| 409 | 请求被桥接层拒绝或执行失败(BridgeError),例如控制未开启、数据过期、水泵冷却未结束,或 request_id 被用于不同的参数。响应体是 {"detail": "<message>", "code": <代码或 null>, "reason": <原因或 null>, "params": {}};detail 仍是字符串,code、reason 和 params 见工作台错误表后面对错误体字段的说明(PumpOffUnconfirmed 错误是 interlock / pump_unconfirmed,params 为 {"device_id": null},因为桥接层在这里不知道设备;其余的 code、reason 为 null,params 为 {})。 |
| 422 | 请求体或查询参数没有通过校验。请求里的 NaN 或无穷大会以文本形式回显,例如 "nan"。 |
| 429 | 已有 64 个 code 在等待,或已有 64 个会话。 |
工作台路由¶
工作台是 DiAGRI 模式下操作员使用的 HTTP 接口:/wb 下的一组 JSON 路由,由 workbench/api.py 的 create_workbench 构建,只在 auto_research = true 时挂载。发起和掌控一轮研究的路由在 workbench/rounds.py 里。操作员控制台是 /workbench 下的一个网页,只调用这些路由(见启用 DiAGRI);web/workbench/ 之外的 web/ 文件是桥接控制台。共 59 个路由;打开 multi_user 时再多 10 个(见多用户路由)。workbench/reads.py 和 workbench/environment.py 里的九个读取路由(/wb/safety、/wb/inbox、/wb/projects、/wb/projects/{project_id}、阶段的读数、测量和历史,以及 /wb/environment 和 /wb/capabilities)总是挂载:没有传入的服务,workbench/reads.py 在待办里直接略过。其中两个告警路由只在传入告警簿时才存在,预算和目标两个路由只在传入任务板和调用预算时才存在,三个分析路由(workbench/analysis.py)只在传入确认性分析运行器时才存在,两个留出集路由(workbench/holdouts.py)只在传入留出数据登记时才存在。运行时总是全部都传。
| 调用方 | 凭据 | 检查 |
|---|---|---|
| 操作员 | Cookie growbridge_operator,由 POST /wb/login 设置:HttpOnly、SameSite=Strict、路径 /wb、8 小时,在覆盖网络入口上带 Secure。 |
请求必须从已登记的入口进来,并且是会话建立时的那个入口。除 GET、HEAD、OPTIONS 以外的方法,还需要一个在允许范围内、并且和请求的 Host 一致的 Origin,以及请求头 X-GrowBridge-UI: 1。恢复编号一变,会话就失效。 |
| 模型角色 | 请求头 Authorization: Bearer <role token>。令牌来自 GROWBRIDGE_ROLE_TOKEN_<ROLE>。 |
不要求入口,也不检查 Origin。只要带了这个请求头,就不再看 Cookie。仅桥接模式的 token 在这里不被接受。 |
表中的"重新认证"指近期重新认证:操作员在最近 300 秒内登录过,或调用过 POST /wb/reauth(workflow/permissions.py 的 REAUTH_SECONDS)。请求体里下文没有列出的字段会被丢弃,所以请求体无法声明身份、权限或入口。
凡是需要操作员的路由,都可能返回 session、entry 和 model_role。最后一列列出该路由另外可能返回的拒绝码。"授予类拒绝码"指 host_unregistered、right_held 和 scope,在控制服务授予写入权时产生。"写入类拒绝码"指 controls_disabled、host_unregistered、right_invalid、scope、unsettled、interlock、not_connected、stale 和 request_id_reused,在控制服务受理动作时产生。
| 方法 | 路径 | 谁可以调用 | 入口 | 重新认证 | 其他拒绝码 |
|---|---|---|---|---|---|
POST |
/wb/login |
持有操作员名字和密码的任何人 | 局域网、覆盖网络 | 否 | 只有 entry、session、locked |
POST |
/wb/logout |
操作员 | 局域网、覆盖网络 | 否 | 无 |
POST |
/wb/reauth |
操作员 | 局域网、覆盖网络 | 否 | locked |
GET |
/wb/me |
操作员、角色令牌 | 局域网、覆盖网络 | 否 | 只有 session、entry |
POST |
/wb/stages/{stage_id}/approve |
操作员 | 局域网、覆盖网络 | 是 | reauth_required、state、approval_invalid |
POST |
/wb/stages/{stage_id}/start |
操作员 | 局域网、覆盖网络 | 否 | state、approval_invalid、safety_conflict、interlock、授予类拒绝码 |
POST |
/wb/stages/{stage_id}/pause |
操作员 | 局域网、覆盖网络 | 否 | state |
POST |
/wb/stages/{stage_id}/resume |
操作员 | 局域网、覆盖网络 | 是 | reauth_required、state、approval_invalid、interlock、not_connected、授予类拒绝码 |
POST |
/wb/stages/{stage_id}/stop |
操作员 | 局域网、覆盖网络 | 否 | state、授予类拒绝码 |
POST |
/wb/stages/{stage_id}/takeover |
操作员 | 局域网、覆盖网络 | 是 | reauth_required、state、授予类拒绝码 |
POST |
/wb/stages/{stage_id}/handback |
操作员 | 局域网、覆盖网络 | 否 | state、not_connected、授予类拒绝码 |
POST |
/wb/stages/{stage_id}/onsite-check |
操作员 | 局域网、覆盖网络 | 否 | state、授予类拒绝码 |
POST |
/wb/drafts/run-sheet |
操作员、planner 的角色令牌 | 局域网、覆盖网络 | 否 | 只有 session、entry、state,其他角色的令牌得到 model_role |
POST |
/wb/manual/{channel} |
操作员 | 局域网、覆盖网络 | 否 | pump_on_forbidden、state、写入类拒绝码 |
POST |
/wb/irrigation |
操作员 | 仅局域网 | 否 | entry(不在局域网入口上)、state、cooldown、写入类拒绝码 |
POST |
/wb/stages/{stage_id}/manual-tasks |
操作员 | 局域网、覆盖网络 | 否 | scope(没有这次任务)、state(阶段未开始,或离到期还有一小时以上)、param(done_at) |
POST |
/wb/stages/{stage_id}/manual-tasks/irrigate |
操作员 | 仅局域网 | 否 | entry(不在局域网入口上)、scope(不是计划内浇水)、state(阶段不在 running、未到期、已过截止时间、已完成,或这次任务已经开过泵)、cooldown、写入类拒绝码 |
POST |
/wb/measurements |
操作员 | 局域网、覆盖网络 | 否 | scope、param |
POST |
/wb/safety/approve |
操作员 | 局域网、覆盖网络 | 是 | reauth_required、host_unregistered、state |
GET |
/wb/stages/{stage_id} |
操作员、角色令牌 | 局域网、覆盖网络 | 否 | 只有 session、entry、state |
GET |
/wb/experiments/{experiment_id}/variables |
操作员、角色令牌 | 局域网、覆盖网络 | 否 | 只有 session、entry、scope |
GET |
/wb/receipts/{request_id:path} |
操作员、角色令牌 | 局域网、覆盖网络 | 否 | 只有 session、entry |
GET |
/wb/alerts |
操作员、角色令牌 | 局域网、覆盖网络 | 否 | 只有 session、entry |
POST |
/wb/alerts/{event_id}/read |
操作员 | 局域网、覆盖网络 | 否 | state |
GET |
/wb/devices/{device_id}/notes |
操作员 | 局域网、覆盖网络 | 否 | state(不是本机设备)、not_lock_holder |
POST |
/wb/devices/{device_id}/notes |
操作员 | 局域网、覆盖网络 | 否 | state(不是本机设备)、not_lock_holder |
POST |
/wb/projects |
操作员 | 局域网、覆盖网络 | 否 | state |
POST |
/wb/protocols |
操作员 | 局域网、覆盖网络 | 否 | state、param |
POST |
/wb/rounds |
操作员 | 局域网、覆盖网络 | 否 | state |
GET |
/wb/rounds/{round_id} |
操作员 | 局域网、覆盖网络 | 否 | state |
GET |
/wb/rounds/{round_id}/report |
操作员 | 局域网、覆盖网络 | 否 | state |
POST |
/wb/rounds/{round_id}/choice |
操作员 | 局域网、覆盖网络 | 否 | state |
POST |
/wb/rounds/{round_id}/abort |
操作员 | 局域网、覆盖网络 | 否 | state |
GET |
/wb/stages/{stage_id}/run-sheet |
操作员 | 局域网、覆盖网络 | 否 | state |
POST |
/wb/projects/{project_id}/budget |
操作员 | 局域网、覆盖网络 | 是 | reauth_required、state |
POST |
/wb/goals |
操作员 | 局域网、覆盖网络 | 否 | budget、state |
GET |
/wb/projects/{project_id}/conversation |
操作员 | 局域网、覆盖网络 | 否 | state |
POST |
/wb/protocols/{protocol_id}/analysis |
操作员 | 局域网、覆盖网络 | 是 | reauth_required、state、script_hash、param |
GET |
/wb/protocols/{protocol_id}/analysis |
操作员 | 局域网、覆盖网络 | 否 | state |
POST |
/wb/analysis/runs |
操作员 | 局域网、覆盖网络 | 是 | reauth_required、state、scope、snapshot_incomplete、already_run、sandbox_unavailable |
POST |
/wb/holdouts |
操作员 | 局域网、覆盖网络 | 是 | reauth_required、scope、state、batches、param |
GET |
/wb/holdouts |
操作员 | 局域网、覆盖网络 | 否 | scope |
POST |
/wb/evidence |
操作员 | 局域网、覆盖网络 | 否 | 无 |
POST |
/wb/evidence/{card_id}/verify |
操作员 | 局域网、覆盖网络 | 否 | state |
GET |
/wb/evidence |
操作员 | 局域网、覆盖网络 | 否 | 无 |
POST |
/wb/compute/balance |
操作员 | 局域网、覆盖网络 | 是 | reauth_required |
POST |
/wb/compute/tasks/{task_id}/budget |
操作员 | 局域网、覆盖网络 | 是 | reauth_required、scope |
POST |
/wb/compute/attempts/{attempt_id}/settle |
操作员 | 局域网、覆盖网络 | 是 | reauth_required、state |
GET |
/wb/compute |
操作员 | 局域网、覆盖网络 | 否 | 无 |
GET |
/wb/inbox |
操作员 | 局域网、覆盖网络 | 否 | 无 |
GET |
/wb/projects |
操作员 | 局域网、覆盖网络 | 否 | 无 |
GET |
/wb/projects/{project_id} |
操作员 | 局域网、覆盖网络 | 否 | state |
GET |
/wb/stages/{stage_id}/readings |
操作员 | 局域网、覆盖网络 | 否 | state |
GET |
/wb/environment |
操作员 | 局域网、覆盖网络 | 否 | — |
GET |
/wb/stages/{stage_id}/measurements |
操作员 | 局域网、覆盖网络 | 否 | state |
GET |
/wb/stages/{stage_id}/history |
操作员 | 局域网、覆盖网络 | 否 | state |
GET |
/wb/stages/{stage_id}/manual-tasks |
操作员 | 局域网、覆盖网络 | 否 | state |
GET |
/wb/safety |
操作员 | 局域网、覆盖网络 | 否 | 无 |
GET |
/wb/capabilities |
操作员 | 局域网、覆盖网络 | 否 | 无 |
最后二十九个路由只给操作员用,其中的十七个读取路由也一样:角色令牌会以 model_role 被拒绝。
下表里的"阶段运行信息"指去掉运行单的 StageRuntime:stage_id、experiment_id、project_id、state、prior_state、right_number、care_right、manual_right、started_at、paused_at、end_pending。RunSheet、ResearchProtocol、SafetyConfig、Approval 和 ActionRecord 定义在 archive/models.py。RunSheet 和 SafetyConfig 里的任何数都不能是 NaN 或无穷大(写成文本也不行),不管它们从哪里来:路由回答 422,模型工具返回错误结果,什么都不保存,也不批准。输入时它们还拒绝控制台表单拒绝的内容:SafetyConfig 里与前面某条规则重复的 id,以及负的 validity_seconds 或 duration_seconds(0 可以);RunSheet 里在 timed_actions、manual_tasks、feedback_rules 或 care_rules 内重复的 id,同一条养护规则的 schedule 内重复的步骤 id(落在 ["body", "run_sheet", "care_rules", 0, "schedule", 1, "id"];执行器写入养护步骤时用的原因是 care:<养护 id>/<步骤 id>,所以两条养护规则可以用同一个步骤 id;在此之前写下的动作记录里是 care:<步骤 id>),与前面某个结束动作同一通道的结束动作(结束动作没有 id,动作记录里用通道称呼它,即 end:<channel>),以及超出该通道范围的 retained_level(范围是 archive/models.py 里的 LEVEL_RANGES,也就是 GET /wb/capabilities 给出的范围)。每一种都是落在出错字段上的 422 校验错误,例如 ["body", "run_sheet", "timed_actions", 2, "id"],类型是 duplicate(ctx.value 是重复的值)或 greater_than_equal / less_than_equal(ctx.ge / ctx.le 是界限);模型工具返回错误结果,什么都不保存,也不批准。这些检查之前存下的安全配置和运行单照常原样读出:存储读取时带校验上下文 STORED,它只免去这些输入检查。
| 方法 | 路径 | 请求体 | 返回 |
|---|---|---|---|
POST |
/wb/login |
name(1 到 64 个字符)、secret(1 到 256) |
operator、entry、reauth_seconds,以及会话 Cookie |
POST |
/wb/logout |
无 | {"operator": null};Cookie 被删除 |
POST |
/wb/reauth |
secret(1 到 256) |
reauth_seconds |
GET |
/wb/me |
无 | kind、id、operator、entry、reauth_at、timezone(即设置 report_timezone,控制台显示时间用的时区) |
POST |
/wb/stages/{stage_id}/approve |
expected_digest(必填,1 到 128 个字符,不接受其他字段):审阅过的运行单的摘要。当前运行单与它不同时,路由以 state 拒绝;缺少请求体或该字段、或带了其他字段时,以 422 拒绝 |
这次的 Approval |
POST |
/wb/stages/{stage_id}/start |
无 | 阶段运行信息 |
POST |
/wb/stages/{stage_id}/pause |
可选 reason(最长 200,默认 operator request) |
阶段运行信息 |
POST |
/wb/stages/{stage_id}/resume |
无 | 阶段运行信息 |
POST |
/wb/stages/{stage_id}/stop |
无 | 阶段运行信息 |
POST |
/wb/stages/{stage_id}/takeover |
无 | 阶段运行信息 |
POST |
/wb/stages/{stage_id}/handback |
可选 accept_as_intervention(布尔,默认 false) |
stage(阶段运行信息)和 differences(由 channel、field、expected、actual 组成的列表) |
POST |
/wb/stages/{stage_id}/onsite-check |
note(1 到 500) |
阶段运行信息 |
POST |
/wb/drafts/run-sheet |
round_id(1 到 100)、run_sheet(一个 RunSheet) |
stage_id 和 findings(由 code、variant、params、message、blocking 组成的列表) |
POST |
/wb/manual/{channel} |
路径参数 channel:light、exhaust、fan 或 pump;请求体 stage_id、request_id、level(整数:灯和排风 0 到 100,风扇 0 到 10,水泵只能是 0)、可选 note(最长 200) |
对应的 ActionRecord |
POST |
/wb/stages/{stage_id}/manual-tasks |
task_id、due_at(指明哪一次任务,用列表给出的值)、outcome(done 或 skipped)、可选 done_at(UTC 秒,默认现在;只用于 done,不能晚于现在,也不能早于 due_at 一小时以上)、可选 note(最长 200)。追加一条记录,以最新的为准。 |
这次任务,格式同列表 |
POST |
/wb/stages/{stage_id}/manual-tasks/irrigate |
task_id、due_at、可选 note;请求号由这次任务推导(请求体里的 request_id 会被忽略),所以重试只返回第一次运行,不会再开一次泵。在阶段写入权下让水泵运行该任务的 seconds,阶段继续运行(见控制与安全模型);完整且得到确认的运行记为已完成,被截断或没有得到确认的运行记为 partial,带 ran_seconds 和 ended_early。 |
action(ActionRecord,带 ran_seconds 和 ended_early)和 task(这次任务;运行没有到达设备时为 null) |
POST |
/wb/irrigation |
stage_id、request_id、seconds(大于 0,不超过 60,且不超过 max_pump_seconds)、可选 note(最长 200) |
对应的 ActionRecord |
POST |
/wb/measurements |
experiment_id、batch、plant_id、layout_version、measured_at、position、method、metric、value、unit;可选 id、corrects;experiment_id 必须属于某个已存在的阶段,否则路由以 scope 拒绝 |
id |
POST |
/wb/safety/approve |
config(一个 SafetyConfig,含 frozen 门槛;不写则用默认值)。config.version 必须高于这台设备以前批准过的每一个版本,不论是否仍然生效(即 GET /wb/safety 的 highest_version;第一次至少为 1),否则路由以 state 拒绝(409,原因 safety_version_not_above,参数 version 和 current_version),什么都不保存 |
protection_right |
GET |
/wb/stages/{stage_id} |
无 | 阶段运行信息;操作员另外得到已存阶段的 round_id、project_id 和 state_at(角色令牌得到的运行信息和以前一样,没有 round_id)。操作员还得到 project_name、round_number、stage_index 和 phase,含义同轮次;找不到时各为 null |
GET |
/wb/receipts/{request_id:path} |
无 | 对应的 ActionRecord。ID 里可以有 /(原样或写成 %2F 都行):执行器写入的请求 ID 里含有它的原因,而养护步骤的原因是 care:<养护 id>/<步骤 id>。失败、作废或结果不明的写入在英文 error 之外还有 error_code 和 error_params(receipt 族的代码);提前结束的浇水在 ended_early 之外还有 ended_early_code 和 ended_early_params(task_end 族)。有代码之前写下的记录两者都没有。 |
GET |
/wb/alerts |
无 | alerts:未解决的告警。每条在英文 message 之外还有 code(alert 族的消息码;有代码之前存下的告警为 null)和 params(对象,代码没有参数时为空)。 |
POST |
/wb/alerts/{event_id}/read |
可选 note(最多 500 字):原因或处理。每次已读带的非空原因都保留;模型把它当作背景,附在对应的读数卡住经历上 |
event_id |
GET |
/wb/devices/{device_id}/notes |
无 | notes:这台设备最新的 10 条日志(id、device_id、at、actor、sensor、text),最新在前。日志写的是设备本身,不属于某个实验,之后持有这个温室的人也能看到 |
POST |
/wb/devices/{device_id}/notes |
text(1 到 500 字)、可选 sensor(最多 40 字) |
新写入的日志 |
POST |
/wb/projects |
name(1 到 200) |
project_id |
POST |
/wb/protocols |
protocol(一个 ResearchProtocol;id 和 project_id 为 1 到 100,version 为 1 到 1000000,不能有 NaN 或无穷大) |
protocol_id、version、digest |
POST |
/wb/rounds |
project_id、protocol_id(各 1 到 100) |
round_id、state |
GET |
/wb/rounds/{round_id} |
无 | round_id、project_id、protocol_id、protocol_version、state、stages_done、stage_total、awaiting_choice、snapshot_id、report_artifact_id,project_name 和 round_number(轮次在项目里同一协议的轮次中的序号,从 1 起),以及 stages(由 stage_id、state、stage_index(按创建顺序的序号,从 1 起)和 phase(协议版本给这个序号的生长期)组成的列表)。服务器找不到的名字(项目或协议已不存在、协议的生长期比阶段少)为 null |
GET |
/wb/rounds/{round_id}/report |
无 | 轮次已发布的报告:round_id、artifact_id、label、sha256,以及 report(报告文件内容:label、reasons、conclusion、estimate、limitations、unresolved、next_round、evidence_chain、snapshot_id;其中 estimate 在 note 之外还有 note_code 和 note_params,精确估计的 note_code 为空)和 primary_endpoint(轮次的协议所定的主要终点指标,协议已不存在时为 null)。只有文件和档案记录的摘要一致时才读出;不一致或轮次没有报告时返回 state。 |
POST |
/wb/rounds/{round_id}/choice |
choice:redo、next、verify 或 abort |
round_id、state |
POST |
/wb/rounds/{round_id}/abort |
无 | round_id、state |
GET |
/wb/stages/{stage_id}/run-sheet |
无 | stage_id、state、run_sheet_version、run_sheet_digest、run_sheet(即 RunSheet)、findings(由 code、variant、params、message、blocking 组成的列表:variant 为空,或把 code 细分到某一句话,params 是那句话要写出的值;先是校验器的发现,再是每个设定值的证据提示 no_evidence、unverified_source、uncalibrated,这些提示不阻塞)、blocking、approval(阶段没有 start 会接受的批准时为 null,否则是 approved_at 和 run_sheet_version;它用的检查和 start 完全相同,所以控制台在它为 null 时让“开始”保持关闭) |
POST |
/wb/projects/{project_id}/budget |
max_calls(整数,0 到 1000000)、max_cost(美元,0 到 1000000) |
project_id、max_calls、max_cost、remaining_calls、remaining_cost |
POST |
/wb/goals |
project_id、goal(去掉首尾空白后 1 到 2000);可选 round_id、constraints(最多 20 条,每条 1 到 500)、request_id、language(en 或 zh;控制台发送页面语言,缺省时任务用 zh 写) |
task_id、state、reused。新目标同时写进项目对话。目标的 language 存在它的任务上(ResearchTask.language,记录语言之前创建的任务为 null),模型从这个目标创建或处理的每个任务都沿用它:模型用这种语言写给操作员看的文字 |
GET |
/wb/projects/{project_id}/conversation |
查询参数 after(一个 seq,默认 0) |
entries,从旧到新,最多 500 条:seq、task_id、role(user 或某个模型角色)、kind(message、reply、tool、status)、text、detail(工具调用时有 input、is_error、result,都会截短;status 条目有 reason,以及说明任务为何结束的 code 和 params,有代码之前写下的条目没有这两项)、at |
POST |
/wb/protocols/{protocol_id}/analysis |
project_id(1 到 100)、script(文本,1 到 20000 个字符,只编译、从不运行) |
protocol_id、version、script_sha256、frozen_at、note(冻结的脚本不能更正) |
GET |
/wb/protocols/{protocol_id}/analysis |
查询参数 project_id(1 到 100) |
protocol_id、version、started、frozen(null,或 script_sha256、frozen_at、frozen_by、script)、snapshots(一组 snapshot_id、experiment_id、complete、run_status、created_at) |
POST |
/wb/analysis/runs |
project_id、protocol_id、snapshot_id(各 1 到 100) |
run_id、status、exit_code、timed_out、stdout、stderr(后两个截到 4000 个字符) |
POST |
/wb/holdouts |
project_id、batch_ids、development_batch_ids、outcome_fields(各 1 到 50 个名字,每个 1 到 100 个字符,不重复;两个批次列表不重叠,开发批次至少 2 个) |
holdout_id(由服务端生成)、project_id、batch_ids、outcome_fields、development_batch_ids、registered_at、registered_by(会话中的操作员) |
POST |
/wb/evidence |
source_class(handbook、paper 或 local)、citation(去掉首尾空白后 1 到 500 个字符)、claim(1 到 1000);可选 value(有限数)、unit(最多 40)、calibrated(默认为真) |
id(由服务器生成)、verified(恒为真:录入的操作员当场核实)、source(operator:<姓名>) |
POST |
/wb/evidence/{card_id}/verify |
可选 note(最多 500 个字符),可选 calibrated(默认为假:操作员证明这个数值已用本地测量校准过) |
card_id、verified、verified_by、verified_at、note、calibrated。重复核实返回第一条记录(含证明),不再写入;对已核实的卡再传 calibrated: true 不会改变任何东西。卡不存在以 state 拒绝 |
GET |
/wb/evidence |
无 | cards:每张卡,另有 source(operator:<姓名> 或 model:planner)、task_id、added_at、verified、verified_by、verified_at、note |
GET |
/wb/holdouts |
查询参数 project_id |
holdouts:每个登记如上,另有 reads,一组 reader、at、label、model_sha |
POST |
/wb/compute/balance |
cpu_hours(有限的数,0 或更大;字符串和布尔值会被拒绝),可选 note(最多 500 个字符) |
这条录入:cpu_hours、entered_by(会话里的操作员;请求体里的姓名会被丢弃)、note、recorded_at |
POST |
/wb/compute/tasks/{task_id}/budget |
cpu_hours、storage_gb(有限的数,0 或更大) |
该任务的一行:task_id、cpu_hours_budget、storage_gb_budget、cpu_hours_used、storage_gb_used、cpu_hours_reserved、storage_gb_reserved。任务不存在时以 scope 拒绝。 |
POST |
/wb/compute/attempts/{attempt_id}/settle |
reason(去掉首尾空白后 1 到 500 个字符) |
attempt_id、phase(failed)、task_state、used_cpu、used_storage、settled_by(会话里的操作员)、settle_reason、error、error_code、error_params。仍在进行的尝试按全额预留计账;用量已经计过账的,保持原来的账。已经是终态的或不存在的尝试以 state 拒绝。 |
GET |
/wb/compute |
无 | balance(最近一条录入,或 null)、tasks(如上的行)、service(cpu_hours_cap、storage_gb_cap、cpu_hours_committed、storage_gb_committed)、jobs(进行中的尝试:attempt_id、task_id、template_id、phase、task_state、remote_job_id、created_at)、stuck(需要人处理的尝试:attempt_id、task_id、phase、reason、reason_code、reason_params、since;原因是尝试自己的错误时还有 error_code 和 error_params;有代码之前存下的行没有代码) |
GET |
/wb/inbox |
无 | items 和 truncated。每个条目有 kind(stage_review、stage_manual、stage_recovery、stage_paused、alert、compute_stuck、round_choice 或 task)、id、project_id、round_id、since 和 detail,以及名字 project_name、round_number、stage_index 和 phase(找不到或该类型没有时为 null:stage_* 条目四个都有,round_choice 条目有 project_name 和 round_number,task 条目有 project_name)。每一类最多保留 50 条:告警先按严重程度,同一严重程度内从未被读过的排在再次询问的之前,再按最近一次触发的时间取舍,其他类型取最早的。alert 条目的 detail 有 alert_kind、severity、message、count、last_at 和 never_read(没有操作员读过它、或读的时候没有记录严重程度时为 true)。alert 条目的 detail 还有告警的 code 和 params;compute_stuck 条目的 detail 就是 /wb/compute 给出的那一行。round_choice 条目的 detail 有 awaiting_choice 和 since_from:stage_stopped 表示 since 是 awaiting_choice 所指阶段停止的时间,round_created 表示那个阶段已不存在或没有停止,since 是轮次的创建时间。保留下来的条目按最早的在前排列,truncated 给出每一类被截掉的条数。 |
GET |
/wb/projects |
无 | projects:每个项目的摘要,最多 200 个;其中的 latest_round 还有 round_number |
GET |
/wb/projects/{project_id} |
无 | 项目的 project_id、name、created_at、rounds(新的在前,每个带 round_number)和 protocols(每个协议的最新版本,每行有 protocol_id、version、created_at,以及取自协议 analysis 的 primary_endpoint 和 method,协议没写时为 null)、budget(calls_left、cost_left、used_calls、used_cost、max_calls 和 max_cost,没有设置预算时为 null;used_cost 可以超过 max_cost,照实显示)和 tasks(最多 100 条)。项目不存在时以 state 拒绝。 |
GET |
/wb/stages/{stage_id}/readings |
查询参数 points(2 到 2000,默认 600) |
samples(由 timestamp、data、quality、clock_synced、flagged 组成的列表)、window(start、end、bucket_seconds,阶段尚未开始时为 null)、total_samples、flagged_total 和 downsampled。每个时间桶保留最新的一条样本;flagged 是该桶里质量不是 ok 或时钟未同步的样本数。points 超出范围时返回 422。 |
GET |
/wb/environment |
查询参数 window(秒,300 到 604800,默认 21600)、points(2 到 1000,默认 360) |
实时环境页的数据,取自档案,不向设备发请求:now、device_id(本机设备,用于设备日志)、clock_synced;latest 是最新一条样本(timestamp、age_seconds、quality、clock_synced、experiment_id、sensors,以及 channels 里每个通道记录的 level 和 on),没有样本时为 null;stage 是当前阶段,包括它的 project_name、round_number、stage_index 和 phase(找不到时各为 null)、它的 state、每个通道的 ownership,以及仅在阶段处于 running 时运行单此刻要求的档位 expected(其他状态为 null)和 planned(时间窗内的计划:light、exhaust、fan 各一个 [时间, 档位] 点的列表,窗口起点一个、每次计划变化一个;阶段不在运行时为 {};温度和湿度没有计划值);没有当前阶段时 stage 为 null;sensors 和 level_ranges 取自设备能力;alerts 是按严重程度计数的未处理告警;readings 是时间窗内的全部样本(不论是否属于阶段),格式和阶段读数相同。 |
GET |
/wb/stages/{stage_id}/measurements |
无 | measurements:该阶段所属实验的测量,包含已被更正的 |
GET |
/wb/stages/{stage_id}/manual-tasks |
无 | stage_id、stage_state、timezone、on_time_seconds、early_seconds、now,以及 occurrences:运行单的人工任务在阶段时间窗内的每一次(task_id、kind、due_at、make_up_allowed、seconds),带 status(upcoming、open、done、late、skipped、missed)和起作用的那条 record(没有时为 null);阶段开始前为空 |
GET |
/wb/stages/{stage_id}/history |
无 | history(阶段的状态变化)和 interventions(该实验中属于本阶段的干预) |
GET |
/wb/safety |
无 | safety:已批准的 SafetyConfig(含 frozen:每个传感器的 minutes 和 max_gap_seconds),没有批准过时为 null;highest_version:这台设备批准过的最高版本,没有生效的配置时(例如恢复之后)也照样给出,第一次批准之前为 null。新的批准必须高于它 |
GET |
/wb/capabilities |
无 | level_ranges(light、exhaust、fan、pump 各一个 [最小, 最大])、sensors(设备上报的每个传感器名及其单位)和 max_pump_seconds(水泵一次最长运行时间)。取自设备能力和桥接自己的上限;控制台用它们给表单标出范围,读取失败时从不自己填值 |
GET /wb/experiments/{experiment_id}/variables 返回该实验的测量可以使用的变量,也就是已声明的人工变量(已声明的 sensor 或 factor 变量不在其中):{"experiment_id": "...", "variables": [{"id", "label_en", "label_zh", "unit", "method", "min", "max", "deprecated"}]},按 id 排序。操作员和角色令牌都可以读取。没有任何阶段运行的实验以 scope 拒绝。POST /wb/measurements 在以下情况以 422 param 拒绝并列出每一个问题:实验没有声明变量、指标未声明(列出已声明的 ID)、变量种类不对、单位不对(给出正确单位)、数值超出 min 和 max(闭区间)。POST /wb/protocols 在以下情况以 422 param 拒绝并列出每一个问题:variables 为空或有重复、某个 ID 未知、是别名、或已弃用而更早的版本没有声明过、主要终点未声明或不是人工变量、处理的因子键不是目录里的因子 ID。见变量目录。
已保存的协议版本不会被覆盖:id 和 version 相同而内容不同,会以 state 被拒绝。POST /wb/rounds 使用最新保存的版本。读取路由给出的 run_sheet_digest 就是审批记录里的那个摘要。再设一次预算只改上限,已记录的用量保留。POST /wb/goals 创建一个归编排 Agent 所有的研究任务;项目还没有预算,或者预算已经用完时,它以 budget 被拒绝。带 request_id 时,同一个操作员对同一个项目把同样的请求再发一次,得到的是第一次建的任务,并带 "reused": true;同一个 ID 下换了目标文本、轮次或约束条件,会以 state 被拒绝。不带 request_id 时,每次请求都新建一个任务。这些路由路径里的 ID 为 1 到 100 个字符。分析路由冻结协议最新版本的分析脚本(这个版本下一旦有阶段启动,冻结就以 state 被拒绝),并在一份数据快照上把它运行一次;它们的检查顺序见开展一轮研究。
request_id 的规则和桥接 API 相同。POST /wb/manual/{channel} 和 POST /wb/irrigation 要求阶段处于 manual 状态。对 POST /wb/manual/pump,level 为 1 会以 pump_on_forbidden 被拒绝。
控制台显示的文字由代码拼出,不取英文句子。一个代码属于某一族(alert、finding、receipt、task_end、compute_error、compute_stuck、chat_end、estimate),params 放句子要写出的值,控制台按页面语言写出文字。各族代码的完整清单在 tests/web/fixtures/message-codes.json,由 scripts/export_message_codes.py 从 src/growbridge/codes.py 导出。message、error、reason 和 note 保持英文、内容不变,供日志、旧客户端和通知使用。有代码之前存下的记录没有代码,控制台显示一句通用的话。
人起的名字显示出来,id 只进技术详情。处理相关的发现 treatment_not_applied、no_replication 和 missing_control.unallocated 在 treatment、treatments 或 control 里写处理的名字,在 treatment_id、treatment_ids 或 control_id 里写 id。unknown_treatment 和 missing_control.undefined 没有名字可写,仍写 id。计划浇水时没能确认水泵已关,任务记录以 task_end 族的 pump_off_unconfirmed 结束(无参数),它优先于这次运行自己的提前结束代码。因输出文件太多而被拒绝的取回带 compute_error 族的 too_many_files,参数是 file_count 和 limit_count;其余输出上限仍是 output_limit。
| 状态码 | 什么情况 | 响应体 |
|---|---|---|
| 401 | 拒绝码 session |
{"detail": {"code": "<code>", "message": "<text>"}} |
| 403 | 本表没有单独列出的其他所有拒绝码 | 同样的结构 |
| 409 | 拒绝码 state;打开 multi_user 时还有 lock_taken 和 greenhouse_busy |
同样的结构 |
| 429 | 拒绝码 locked |
同样的结构 |
| 503 | 拒绝码 unavailable:构建工作台时没有传入设备日志存储(运行时总会传入) |
同样的结构 |
| 404 | GET /wb/receipts/{request_id:path} 的 ID 不存在 |
{"detail": {"code": "state", "message": "Unknown request id", "reason": "unknown_request", "params": {"request_id": "<id>"}}} |
| 422 | level 超出该通道的范围,测量记录没有被接受,或者协议的 ID 或版本超出范围、含有非有限的数 |
{"detail": {"code": "param", "message": "<text>"}} |
| 422 | 请求体没有通过校验,包括运行单里有非有限的数,以及安全配置或运行单里有重复的 id 或超出范围的值(见上面关于模型的一段) | 校验错误列表;请求里的 NaN 或无穷大以文本形式回显 |
多用户路由¶
打开 multi_user 时挂载(workbench/greenhouses.py、workbench/admin.py)。此时其余每个路由也检查调用者:操作员只看到并操作自己拥有的项目,动阶段还要锁着它的温室;别人的对象按"不存在的编号"回答。GET /wb/me 增加 multi_user、role、greenhouses。POST /wb/drafts/run-sheet 拒绝角色令牌(model_role):模型只能通过绑定任务的工具起草运行单。每个读取路由遵循哪条规则,列在 workbench/visibility.py。
| 方法与路径 | 谁可以 | 请求体 | 回答 | 拒绝码 |
|---|---|---|---|---|
GET /wb/greenhouses |
操作员 | greenhouses:id、name、state(free、mine、taken)、locked_at;管理员另有 holder |
||
POST /wb/greenhouses/lock |
操作员,需重新认证 | greenhouse_ids(1 到 64 个) |
locked |
lock_taken、state |
POST /wb/greenhouses/{greenhouse_id}/release |
锁定它的操作员 | released |
not_lock_holder、greenhouse_busy、state |
|
GET /wb/admin/operators |
管理员 | operators:name、role、created_at、disabled_at、unfinished_stages;events(最近 200 条,新的在前):name、action(add、disable、reset_secret)、actor(null 表示命令行)、detail(添加账号时的角色)、at |
admin_only |
|
POST /wb/admin/operators |
管理员,需重新认证 | name、secret、role |
name、role |
admin_only、param |
POST /wb/admin/operators/disable |
管理员,需重新认证 | name |
disabled |
admin_only、param |
POST /wb/admin/operators/secret |
管理员,需重新认证 | name、secret |
reset |
admin_only、param |
GET /wb/admin/locks |
管理员 | locks、events |
admin_only |
|
POST /wb/admin/greenhouses/{greenhouse_id}/release |
管理员,需重新认证 | note(1 到 500 字) |
released |
admin_only、greenhouse_busy |
POST /wb/admin/projects/{project_id}/owner |
管理员,需重新认证 | owner、note |
project_id、owner |
admin_only、state(原所有者仍可操作、有未结束阶段,或新所有者不可用) |
每个拒绝都会说明原因。工作台路由的 detail 对象多出 reason(denial 族的一个代码,没有原因的拒绝为 null)和 params(对象,原因不带参数时为空):{"detail": {"code": "<code>", "message": "<text>", "reason": "<reason>", "params": {}}}。桥接路由的 detail 仍是字符串,响应体多出顶层的 code、reason 和 params。粗码和状态码不变,message 仍是英文文本。一个原因属于一个粗码(它的 of);控制台按页面语言写出该原因的句子,旧客户端或没有原因时退回到粗码。tests/web/fixtures/message-codes.json 的 denial 族列出每个原因及其 params、action(控制台给出的下一步)和 of。表单字段在发出请求之前显示的文字由控制台自己给出(msg.validation.*),不属于这个 API。模型看到的仍是 Error: denied (<code>): <message>,看不到原因。
MCP 工具¶
来源:mcp_server.py。growbridge mcp 通过标准输入输出运行名为 spiderfarmer-growbridge 的服务。每个工具都带着令牌调用桥接 HTTP API。仅桥接模式有 8 个工具,DiAGRI 模式只有 3 个读取工具。
| 工具 | 仅桥接模式 | DiAGRI 模式 | 输入 | 调用 |
|---|---|---|---|---|
get_health |
有 | 有 | 无 | GET /health |
get_status |
有 | 有 | 无 | GET /status |
get_history |
有 | 有 | 可选 hours(默认 24)、limit(默认 500) |
GET /history |
set_light |
有 | 无 | brightness_percent、request_id |
POST /control/light |
set_exhaust |
有 | 无 | speed_percent、request_id |
POST /control/exhaust |
set_fan |
有 | 无 | level、request_id |
POST /control/fan |
set_outlet |
有 | 无 | number、on、request_id |
POST /outlet |
run_pump |
有 | 无 | seconds、request_id |
POST /pump |
模型角色的工具¶
来源:agents/tools.py 的 ROLE_TOOLS,以及 handlers_orchestrator.py、handlers_planner.py、handlers_researcher.py、handlers_report.py、handlers_auditor.py 和 handlers_common.py 里的处理函数。编排 Agent 有 7 个工具,计划 Agent 有 11 个,研究 Agent 有 9 个,监察 Agent 有 6 个。这些工具由守护进程内部的模型调用,既不是 HTTP 路由,也不是 MCP 工具。
"类别"取值为 read、write、web(结果是不可信的网页内容)或 sandbox。一个角色在一次运行里调用过 web 工具之后,它的 write 和 sandbox 工具在这次运行的剩余部分都会被拒绝。输入里有未知字段时校验失败。被拒绝时,模型收到的是一条错误结果,格式为 Error: denied (<code>): <message>。
| 角色 | 工具 | 类别 | 必填输入 | 作用 |
|---|---|---|---|---|
| orchestrator | get_project_state |
read | project_id |
读取项目的任务和当前活动阶段;带 round_id 时还读取轮次状态和它的各个阶段。 |
| orchestrator | get_run_status |
read | stage_id |
读取一个阶段的状态和近期历史。 |
| orchestrator | create_research_task |
write | project_id、owner_role、question、trigger_event_id、correlation_id |
给计划 Agent 或研究 Agent 创建一个研究任务。 |
| orchestrator | delegate_task |
write | project_id、to_role、goal、budget、trigger_event_id、correlation_id |
带完整交接信息,给计划 Agent 或研究 Agent 创建一个研究任务。 |
| orchestrator | get_task_status |
read | task_id |
读取正在运行的任务或它下面委派出去的任务的状态,以及它的产物 ID。 |
| orchestrator | read_artifact |
read | artifact_id |
核对摘要后读取一个已登记的文本产物。 |
| orchestrator | read_round_history |
read | round_id |
读取本项目以前某一轮的完整记录:报告(或它为什么不能用:invalid、held_out、unavailable)、人做的决定,以及该轮运行期间设备上的经历。别的项目的轮次按不存在处理。只作背景。 |
| planner | get_device_capabilities |
read | 无 | 读取设备的传感器、通道和档位范围。 |
| planner | find_prior_runs |
read | experiment_id |
列出一个实验的数据快照和测量条数。 |
| planner | lookup_crop_conditions |
web | crop |
搜索某种作物的生长条件。 |
| planner | search_and_verify_sources |
web | query |
搜索资料来源。 |
| planner | check_experimental_design |
read | project_id、protocol_id |
检查一份已保存的研究协议的设计。 |
| planner | estimate_sample_size |
read | effect、sd |
估算需要多少个区组或实验单位。 |
| planner | validate_run_sheet |
read | run_sheet |
校验运行单,但不保存。带 round_id 时,还会像 save_plan_draft 一样检查运行单是否执行了本轮分配的处理。 |
| planner | query_evidence |
read | 无 | 在档案里搜索证据卡;每张卡都标明操作员是否已核实。 |
| planner | propose_evidence_card |
write | task_id、source_class、citation、claim |
把计划 Agent 读到的一条来源存成“未核实”的证据卡,返回 card_id,供运行单引用。它不能核实证据卡。 |
| planner | save_plan_draft |
write | round_id、run_sheet |
提交运行单草稿,等操作员审阅。它不做审批。没有执行本轮分配处理的运行单(treatment_not_applied)不会保存。 |
| planner | read_round_history |
read | round_id |
与编排 Agent 相同。 |
| researcher | inspect_stage_data |
read | task_id、stage_id |
按冻结会用的时间窗汇总一个已启动阶段的数据(覆盖率、缺口、样本数、各通道取值范围、各指标的人工测量、人工任务是否按时完成、已有快照),不写入任何东西。留出批次的测量只给条数。 |
| researcher | freeze_dataset |
write | task_id、stage_id |
把一个阶段的数据冻结成经过校验的数据快照;带 round_id 且快照完整时,还会推进轮次。 |
| researcher | query_evidence |
read | 无 | 在项目档案里搜索证据卡。 |
| researcher | run_local_analysis |
sandbox | task_id、snapshot_id、script |
在沙箱里对一个数据快照运行探索性脚本。 |
| researcher | submit_compute_job |
write | task_id、template_id |
按已登记的模板提交一个计算作业。 |
| researcher | get_compute_job |
read | attempt_id |
读取计算作业的状态。 |
| researcher | fetch_compute_artifacts |
write | attempt_id |
取回并校验计算作业的输出。 |
| researcher | publish_research_report |
write | task_id、protocol_id、treatment_id、snapshots |
发布本轮的报告;带 round_id 且报告为最终版时,还会交付轮次。返回 treatment_check:设备记录的档位和分配处理不符的轮次(按方案偏离计算),以及样本里没有档位、无法核对的轮次;manual_task_check:每轮计划的人工任务数和没有按时完成的次数;server_notes:服务器加进报告的每条说明,含中英文。 |
| researcher | read_round_history |
read | round_id |
与编排 Agent 相同。 |
| auditor | get_project_state |
read | project_id |
与编排 Agent 相同。 |
| auditor | get_run_status |
read | stage_id |
与编排 Agent 相同。 |
| auditor | inspect_stage_data |
read | task_id、stage_id |
与研究 Agent 相同:在冻结会用的时间窗口内汇总一个已开始阶段的数据,不写入任何东西。 |
| auditor | get_stage_records |
read | task_id、stage_id |
读取一个已开始阶段的计划和记录:运行单、人工任务及其状态和记录、测量值,以及该阶段未处理的告警。 |
| auditor | read_round_history |
read | round_id |
与编排 Agent 相同。 |
| auditor | raise_audit_finding |
write | task_id、stage_id、severity、summary |
发出一条建议性的 audit_finding 告警(info 或 warning),可附若干行 evidence。它不暂停任何东西,也不改动别的东西。 |
证据卡。propose_evidence_card 需要调度器正在运行的任务,而且这个任务必须是计划任务。不管输入怎么写,卡片都以“未核实”保存,来源记为 model:planner 和任务 ID:输入里没有核实字段,多余的字段会被拒绝。输入里也没有 calibrated 字段:模型不能声称已校准,所以提议的卡以“未校准”保存,即使操作员核实之后,uncalibrated 提示仍然保留,直到操作员核实时用 calibrated: true 证明校准过(这个证明随核实记录一起保存;第一次核实为准)。操作员自己录入的卡,保留操作员录入的 calibrated 值。模型不能提议 local 卡:source_class 为 local 会以 param 拒绝,因为只有操作员才能把本地测量记成证据。任何类别的未核实卡,包括 local,在运行单的审阅里一律带 unverified_source 提示,直到操作员核实。卡 ID 由服务器生成,一个任务最多提议 20 张卡(quota);读过网页内容的计划 Agent 在这次运行的剩余时间里就没有这个写入工具了,所以要先提议、再搜索。只有操作员能核实一张卡,经 POST /wb/evidence/{card_id}/verify;那会追加一条记录,卡片原文永不改动。
研究 Agent 的工具只要涉及快照、阶段、轮次或计算提交,就必须带 task_id。这个编号要和调度器正在运行的任务比对,而不是照单全收:任何其他编号、别的角色的任务、以及在调度运行之外发起的调用,都会以 scope 被拒绝;其他项目的阶段、轮次或快照同样以 scope 被拒绝。
另外两个角色以同样的方式绑定。编排和计划 Agent 调用里的每个 project_id、round_id、stage_id 和 experiment_id,都必须属于正在运行的任务所在的项目,而且该实验必须只有一个所属项目。get_task_status 只回答正在运行的任务和它下面委派出去的任务;read_artifact 只回答本项目任务的产物;delegate_task 只接受正在运行的任务作为 parent_task_id。以上情况都以 scope 拒绝。
growbridge serve 构建的守护进程没有传入搜索后端,所以 lookup_crop_conditions 和 search_and_verify_sources 返回 denied (unavailable)。submit_compute_job、get_compute_job 和 fetch_compute_artifacts 只在配置了计算服务时才可用(见启用 DiAGRI第 5 步),否则同样返回 denied (unavailable)。计算输入的 ref 是 <快照 id> 或 <快照 id>/<文件>,服务只接受任务所属项目的、已通过校验且不含留出结果的快照;其他一律在任何字节离开本机之前被拒绝。工作台的四个计算路由只在有计算服务时存在。沙箱只在 macOS 上存在;在其他系统上,run_local_analysis 返回 denied (sandbox_unavailable)。
agents/tools.py 的 CONTROL_TOOLS 列出了 14 个阶段和设备控制类的工具名,任何模型角色都拿不到它们。这些名字都没有对应的处理函数。
另见¶
页面最近一次对照代码核对是在 2026-11-11。DiAGRI 模式目前只在模拟的 AC5 上测试过,见状态与已知限制。修改页面之前,请先读编写约定。