人工接管、灌溉与交还¶
这一页写给需要接管一个进行中的阶段、手动写设备、灌溉,再把控制权交还的操作员。每一步都给出请求、返回内容,以及请求被拒绝时怎么办。
只在模拟的 AC5 上测试过。这里的内容没有在真实水泵或真实设备上跑过。见状态与已知限制。
开始之前¶
- 已经登录工作台,并且知道怎么给它发请求:见运行一轮研究里的“工作台是什么”。
/workbench的控制台用按钮完成同样的步骤。 - 阶段处于
running或paused。用GET /wb/stages/STAGE_ID确认。 - 要灌溉的话,人在现场,并且是从局域网入口(
http://YOUR_LAN_HOST:LAN_PORT)登录的。覆盖网络入口的会话不能灌溉。 - 人工写入只能动运行单里标为主机控制的通道。要灌溉,
pump必须是其中之一。
这些规则背后的理由见控制与安全模型。
1. 重新认证¶
接管要求最近 300 秒内重新认证过。登录本身算一次。超过了就先发:
应该得到 {"reauth_seconds": 300}。
2. 接管¶
应该得到 "state": "manual" 和一个 manual_right 编号,right_number 和 care_right 都是 null。
到这时系统已经做了这些事(workflow/service.py 的 takeover):
- 回读设备,把之前结果未知的写入尽量核对清楚。
- 撤销阶段写入权和养护写入权。定时动作、反馈规则和养护规则停止,这两个写入权下排队的写入作废。
- 授予一个绑定到你这个操作员名字的人工写入权。别的操作员发的人工写入会被拒绝,拒绝码
scope。 - 为这个实验记录一条
takeover人工干预。
接管期间保护规则照常执行,采样也继续。
3. 手动写入¶
POST /wb/manual/light
{"stage_id": "STAGE_ID", "request_id": "manual-0001", "level": 40, "note": "dim the lamp"}
| 字段 | 规则 |
|---|---|
| 通道(写在路径里) | light、exhaust、fan 或 pump |
level |
light 和 exhaust 为 0 到 100,fan 为 0 到 10,pump 只能是 0 |
request_id |
8 到 100 个字符,只能用字母、数字、_ 和 -。每次写入用一个新的。 |
note |
可选,最多 200 个字符。它会作为这次动作的触发依据保存下来。 |
返回的是动作记录,看其中的 state:
state |
含义 |
|---|---|
confirmed |
已回读设备,档位和写入的一致。 |
failed |
写入没有发出、被设备拒绝,或者回读到的是别的档位。没有遗留问题,可以换一个 request_id 再写。 |
unknown |
写入可能生效了,也可能没有。之后的人工写入会被拒绝,拒绝码 unsettled。见故障处理手册里的“写入结果未知”。 |
用同一个 request_id 和同样的请求体再发一次,返回的是第一次的记录,不会再写设备。GET /wb/receipts/REQUEST_ID 随时可以取回这条记录。人工写入在两个入口都能用。
4. 灌溉¶
灌溉只有操作员能做,而且只在局域网入口提供。它是唯一能开泵的途径:执行 Agent 从不开泵,POST /wb/manual/pump 也只接受 0。
运行单计划好的浇水不需要接管。 运行单里有带
seconds的浇水任务时,在阶段页的人工任务里启动(POST /wb/stages/STAGE_ID/manual-tasks/irrigate,同样只在局域网入口),阶段继续运行。接管会被记为干预,在报告里算作方案偏离;计划内浇水则记为该任务已完成(被截断或没有得到确认时记为部分完成)。见运行一轮研究。
POST /wb/irrigation
{"stage_id": "STAGE_ID", "request_id": "water-0001", "seconds": 2, "note": "tray 3"}
限制来自 workbench/api.py 和 control/service.py:
| 限制 | 取值 | 超出时 |
|---|---|---|
请求里的 seconds |
大于 0,不超过 60 | 422 |
seconds 对照配置 |
不超过 max_pump_seconds(默认 5) |
scope |
| 距离上一次灌溉开始的时间 | 不少于 pump_cooldown_seconds(默认 60) |
cooldown |
| 同时进行的灌溉 | 一次 | cooldown |
控制服务开泵,等待 seconds 秒,关泵,再回读关闭状态,最多尝试两次。这些都做完请求才返回,所以请求耗时大致等于 seconds。等待期间如果发生交还、停止或保护规则写入,等待会提前结束,水泵随即关闭。
返回的 state |
含义 |
|---|---|
confirmed |
水泵运行过,并且关泵已确认。 |
failed |
开泵失败:指令没有发出、被拒绝,或者回读没有显示水泵已开。关泵指令仍然发出并得到确认。 |
unknown |
要么开泵无法确认,要么关泵无法确认;后一种情况下 error 是 pump off unconfirmed; interlock set。到设备跟前去,并查看故障处理手册里的“关泵未确认”。 |
5. 交还¶
请求体可以不带,默认是 false。交还不需要重新认证。
应该得到 {"stage": {...}, "differences": [...]},阶段处于 running。每条差异包含 channel、field(level 或 mode)、expected 和 actual:比较的是设备此刻的状态和运行单在当前时点的目标。
系统做的事(workflow/service.py 的 handback):
- 先读设备。读不到时请求被拒绝,拒绝码
not_connected,阶段保留人工写入权。 - 撤销人工写入权,授予新的阶段写入权和养护写入权。
accept_as_intervention为true并且至少有一条差异时,把这些差异记成一条accepted人工干预。为false时不再多记什么。- 阶段进入
running。接管之前是paused的阶段也一样。
两种情况下,执行 Agent 都会在下一次评估时把每个主机控制的通道调回运行单规定的档位。accept_as_intervention 决定的是记录什么,不是设备接下来怎么动。
任何操作员都可以交还,不限于发起接管的那一位。
接管期间守护进程重启了¶
阶段进入 recovery_check,人工写入权作废。各项核对通过后,阶段回到 manual,并给原来那位操作员发一个新的人工写入权。见故障处理手册里的“进程重启”。
拒绝码与处理办法¶
被拒绝时响应体是 {"detail": {"code": "...", "message": "..."}}。
| 拒绝码 | 原因 | 怎么办 |
|---|---|---|
entry |
灌溉请求是从覆盖网络入口发的,会话属于另一个入口,或者缺少 Origin 或 x-growbridge-ui 请求头。 |
到现场,从局域网地址登录。 |
reauth_required |
接管前没有近期的重新认证。 | 做第 1 步,再重发。 |
state |
阶段不是 running 或 paused(接管时),或者不是 manual(写入、灌溉、交还时),或者请求处理期间阶段变了。 |
读一下阶段,再重发,或者先接管。 |
pump_on_forbidden |
POST /wb/manual/pump 的档位不是 0。 |
改用 POST /wb/irrigation。 |
cooldown |
上一次灌溉开始还不到 pump_cooldown_seconds 秒,或者有一次灌溉正在进行。 |
等一等,换一个 request_id 再发。 |
scope |
seconds 超过了 max_pump_seconds,通道在运行单里不是主机控制的,或者人工写入权在另一位操作员手里。 |
缩短时长,或者让发起接管的操作员来发请求。 |
interlock |
关泵未确认,普通写入被阻止。 | 到现场检查水泵。见手册。 |
unsettled |
之前有一次写入结果未知,旧的写入通路还没确认停止,或者控制服务还没启动完。 | 见手册里的“写入结果未知”。 |
stale |
stale_seconds(默认 20)秒内没有新的设备遥测。 |
等遥测恢复。一直不恢复就按 BLE 中断处理。 |
not_connected |
BLE 没连上,或者读不到设备状态。 | 等重连,然后重发。 |
right_invalid |
人工写入权已被撤销:阶段已经离开 manual,或者守护进程重启过。 |
读一下阶段。不是 manual 就重新接管。 |
right_held |
设备上还有一个有效的阶段写入权。接管会先撤销本阶段自己的阶段写入权,所以经工作台操作时不应该遇到。 | 读一下阶段,重发一次。还是这样就上报。 |
request_id_reused |
这个 request_id 以前用过,参数不一样。 |
换一个 request_id。 |
controls_disabled |
controls_enabled 是 false。 |
改成 true,重启 serve。 |
host_unregistered |
这台机器不是登记的写入主机。 | 见启用 DiAGRI第 3 步。 |
session |
会话过期,或者恢复编号变了。 | 重新登录。 |
422 表示请求体不合格:通道不存在、档位超出范围、seconds 不在 0 到 60 之间,或者 request_id 格式不对。全部拒绝码见拒绝码与事件类型。
另见¶
页面最近一次对照代码核对是在 2026-11-11。DiAGRI 模式目前只在模拟的 AC5 上测试过,见状态与已知限制。修改页面之前,请先读编写约定。