跳转至

拒绝码与事件类型

English

这一页写给需要看懂一次拒绝、一个阶段事件或一个动作状态的操作员和开发者。它列出全部拒绝码、全部阶段事件类型和全部动作状态,并说明各自从哪里来。

这些条件是从代码和测试里读出来的,而测试只在模拟的 AC5 上运行,见状态与已知限制。

拒绝码

一次拒绝就是 ports.py 里的异常 Denied(code, message)。Denied 的文档字符串列了 38 个拒绝码,代码里抛出的也正好是这 38 个。工作台把拒绝转成 HTTP 响应:state、lock_taken 和 greenhouse_busy 是 409,session 是 401,locked 是 429,其余都是 403,见 HTTP、工作台与 MCP 接口。

拒绝码 含义 由谁抛出 调用方该怎么做
host_unregistered 本机不是这台设备登记的写入主机,或者已经登记了另一台主机。 控制服务(control/service.py);runtime.py 的 register_write_host 从已登记的主机上写入。growbridge host register 可以登记本机;已经登记了别的主机时会被拒绝。
controls_disabled 配置文件里 controls_enabled 是 false。 控制服务 设置 controls_enabled = true 并重启守护进程。
right_invalid 写入权不存在、已撤销,或属于更早的恢复编号;人工写入权没有绑定操作员;灌溉请求用的不是人工写入权;或者排队中的动作在发送前被作废。 控制服务、control/rights.py 不要重复同一个请求。通过工作流重新取得写入权(启动、恢复或接管阶段),再发新的请求。
right_held 这台设备的阶段写入权已被持有,此时又申请阶段写入权或人工写入权。 控制服务 先把持有写入权的阶段暂停、停止或接管。
scope 请求超出了写入权或调用方的范围:不是这台设备,通道或档位不在写入权列出的范围里,阶段、实验或操作员对不上,灌溉时间过长或不是"开泵"。对模型工具来说:任务编号不是这次运行所对应的任务,在调度运行之外发起调用,任务、阶段、轮次、实验、数据快照、产物或计算作业属于其他项目或其他角色,实验被两个项目同时占用,或者快照里含有留出数据的结果。对工作流来说:运行单的 experiment_id 属于另一个项目。对人工测量来说:experiment_id 没有任何阶段拥有(POST /wb/measurements)。 控制服务、control/rights.py、计算服务、工作流服务(WorkflowService.submit_run_sheet)、模型工具的处理函数(agents/) 修改请求。原样重发还会被拒绝。
pump_on_forbidden 一次普通写入试图开泵。 control/rights.py;workbench/api.py 的 POST /wb/manual/{channel} 在局域网入口上使用 POST /wb/irrigation。
interlock 关泵联锁生效:关泵没有得到确认。普通写入被拒绝,阶段也不能启动或恢复。 控制服务;工作流服务(workflow/service.py) 到现场检查水泵,然后用 POST /wb/stages/{stage_id}/onsite-check 记录现场核对。执行 Agent 会持续尝试关泵。
not_connected 没有有效的 BLE 连接,或者读不到设备状态。 控制服务 等连接恢复后重新发送请求。
stale 最新样本比 stale_seconds 更旧。阶段写入和人工写入都要求数据新鲜。 控制服务 等到有新样本(GET /health 里可以看到 stale),再重新发送请求。
request_id_reused 这个 request_id 已经用于另一组参数。 控制服务 新动作用新的 request_id。只有重发完全相同的请求时才复用 ID。
not_operator 调用方既不是操作员也不是模型角色,或者操作员名字为空。 workflow/permissions.py;控制服务(onsite_check);AlertBook.mark_read 以已登录的操作员身份重做这个操作。
model_role 模型角色请求了阶段、审批或控制类操作;给角色配置了不属于它的工具;该角色不是模型角色;或者没有为它配置模型。 workflow/permissions.py;agents/tools.py;agents/dispatch.py 模型角色对此无能为力,需要操作员来做。如果是配置文件里的 tools 引起的,去掉那个工具名。
reauth_required 这个操作要求最近 300 秒内重新认证过。 workflow/permissions.py 调用 POST /wb/reauth,然后重发请求。
entry 请求不是从已登记的入口进来的,没有通过 Origin 和 X-GrowBridge-UI 检查,进来的入口和会话所属的入口不一致,或者该操作只在局域网入口提供。 workbench/api.py 使用 lan_hosts 或 overlay_hosts 里的地址和对应的端口,并带上这两个请求头。灌溉要从局域网入口发起。
approval_invalid 阶段没有有效审批;审批已经对不上(运行单内容或版本、阶段、实验、设备、能力版本或恢复编号变了);运行单有阻断性问题;或者安全配置没有审批人,或给设备没有的传感器设了冻结读数门槛。 工作流服务;控制服务(approve_safety) 解决校验发现的问题,再重新审批这个阶段;安全配置则改正后重新批准。
state 对象不存在,当前状态不允许这个操作,或者在请求处理期间发生了变化。对证据来说:核实一张不存在的卡。对分析来说:协议版本下已有阶段启动之后还要冻结脚本,没有冻结脚本就要运行,或者运行一份被后来的更正作废的快照。对报告来说:脚本已冻结,而引用的某份快照的运行还没有结束。对留出集来说:项目里已经记录了留出批次的结局,那些数据可能已经被看过。对计算尝试来说:结算一个已经是终态或不存在的尝试(POST /wb/compute/attempts/{attempt_id}/settle),重试一个没有失败的尝试,或者下载一个已由操作员了结(包括在下载过程中被了结)的尝试的输出。另外:冻结脚本时已经有快照或测量,或者快照背后的阶段或测量早于冻结。对安全配置来说:版本不高于这台设备以前批准过的最高版本,不论那个版本是否仍然生效(safety_version_not_above)。 工作流服务、workflow/store.py、workflow/tasks.py、workbench/api.py、workbench/analysis.py、计算服务、留出数据登记、AlertBook、模型工具的处理函数、控制服务(approve_safety) 先读取当前状态,例如 GET /wb/stages/{stage_id},再决定怎么做。
safety_conflict 已批准的安全配置里有保护规则要动某个通道,而运行单没有把这个通道设为主机控制。 工作流服务,依据 ControlService.safety_conflicts 修改运行单(生成新版本)或安全配置,然后重新审批。
budget 项目的调用预算或费用预算用完了,或者从未设置;或者任务超过了修订次数上限或委派深度上限。 agents/budget.py;workflow/tasks.py 停下来。这个任务需要人来决定。操作员用 POST /wb/projects/PROJECT_ID/budget 设置或提高项目的预算;已经进入 needs_attention 的任务不会因此恢复。
session 没有会话,或者会话无效、已过期、早于当前恢复编号;名字或密码不对;或者角色令牌不匹配。 workbench/api.py、workbench/auth.py 用 POST /wb/login 重新登录。
member 提交者没有对应到 CSC 项目成员。 计算服务(compute/service.py) 只在配置了计算服务时才会出现,见下面的说明。
quota 没有登记任务预算或项目余额;作业会超出任务预算、服务上限或项目余额;或者达到了模板的重试上限。对模型工具来说:一个计划任务已经提议了 20 张证据卡。 计算服务、agents/handlers_evidence.py 计算相关的情况只在配置了计算服务时才会出现:请通过工作台录入余额和任务预算(启用 DiAGRI第 5 步)。提议数量的上限:请操作员自己录入这张卡。
param 计算作业的模板或模板版本不存在,参数未知或缺失,取值的类型或范围不对(浮点数不是有限的、文本太长、含控制字符,或者不匹配模板里的 pattern),结算请求没有写原因,或者输入不是它所在快照里可用的文件或文件夹(或没有输入根目录或输入检查:带输入的作业此时一律被拒绝)。对证据来说:模型提议 local 卡(只有操作员才能记录本地测量)。对报告来说:同一个实验被列进两个轮次,处理不存在,或者测量数据和分配对不上。对冻结的分析脚本来说:脚本为空,或者编译不过(语法错误或含 NUL 字节)。对报告来说:引用的快照来自不止一个协议版本,或者来自别的协议。 计算服务;agents/handlers_report.py、agents/handlers_evidence.py 改正输入后重新发送。
clock_unsynced 时钟没有同步,数据不能冻结。 archive/snapshot.py 等时钟同步后再冻结。
script_hash 分析脚本和研究协议里的哈希不一致,或者和这个协议版本已经冻结的脚本不一致(路由 POST /wb/protocols/{protocol_id}/analysis)。 research/analysis.py 使用已冻结的脚本。
snapshot_incomplete 数据快照被标记为不完整,或者它的文件和清单对不上。 research/analysis.py;agents/handlers_researcher.py;agents/handlers_report.py 重新冻结一个快照,改用新的。
already_run 这个快照上已经跑过确认性分析,或者正在跑(路由 POST /wb/analysis/runs)。 research/analysis.py 不要再跑;确认性分析只运行一次。
batches 登记留出数据时,开发批次少于 2 个,没有留出批次,同一个批次同时在两边,或者批次名为空或重复(路由 POST /wb/holdouts)。 research/holdout.py 登记时至少提供 2 个开发批次和 1 个留出批次。
model_unregistered 评估之前,模型没有在这份留出数据上登记,或者给出的模型哈希不是登记过的那个。 research/holdout.py 先登记模型、特征和预处理方式。
sandbox_unavailable 当前平台没有隔离后端,所以不会运行任何分析脚本。 research/sandbox.py 换到有沙箱的平台上运行分析(这份代码里是 macOS)。
unsettled 控制服务还没有启动完;旧传输停止还没有得到确认;或者之前有动作结果未知。 控制服务 等启动完成。其他情况下,要先通过回读或现场核对把结果确定下来,普通写入才能继续。
cooldown 有一次灌溉正在进行,或者距上一次开始还不到 pump_cooldown_seconds。 控制服务 等一等,再重新发送灌溉请求。
unavailable 某个可选后端没有配置:搜索、计算服务、沙箱或留出数据登记。 agents/handlers_common.py 调用方无法解决;守护进程构建时就没有这个后端。
locked 15 分钟内登录失败次数过多:同一名字从同一地址失败 5 次,或者同一名字从所有地址累计失败 25 次。 workbench/auth.py 等到这些失败记录超过 15 分钟。
lock_taken 要锁定的温室里有已被别人锁定的,这次一个也没锁上(多用户)。 workflow/locks.py 去掉被占用的温室后重新锁定。
greenhouse_busy 温室上还有没结束的阶段,不能释放(多用户)。 workflow/locks.py 先停止或结束阶段(或中止轮次),再释放。
not_owner 管理员试图操作别人的项目;管理员对别人的阶段只能暂停和停止(多用户)。 workflow/access.py 请所有者操作,或先停用其账号再把项目转出。
not_lock_holder 项目所有者没有锁定阶段或运行单用到的温室(多用户)。 workflow/access.py、workbench/api.py 先锁定这个温室。
admin_only 只有管理员能做(多用户)。 workflow/access.py 请联系管理员。

关于哪些拒绝码实际会出现。member、quota,以及 param、scope、state 和 snapshot_incomplete 里和计算有关的情况,只在守护进程配置了计算服务时才会出现。后三者来自对计算输入的检查:别的项目的快照或含有留出结果的快照(scope)、已被作废的快照(state)、校验不通过的快照(snapshot_incomplete)。batches 只由 HoldoutRegistry.register 抛出,而 src/ 里没有任何地方调用它。script_hash 和 already_run 来自 ConfirmatoryRunner.freeze_analysis 和 run_frozen,经由工作台的两个分析路由出现。另外,工作台在 HTTP 422 的响应体里也用了 param 这个词作为 code,那不是 Denied。

请求在刚提交时被拒绝,动作账本里不会留下记录,所以同一个 request_id 可以再发一次。如果是在发送前的复核环节被拒绝,这个动作会以 void 状态存下来;之后用同一个 request_id 只会拿回这条记录,所以需要换一个新的 ID。

谁收到这次拒绝 它看到什么
工作台的 HTTP 客户端 上面说的状态码,以及响应体 {"detail": {"code": "<code>", "message": "<text>"}}。
操作员控制台(/workbench) 38 个拒绝码各有一条中文或英文的白话提示,并说明下一步该做什么。控制台自己还有三个服务器不会发出的码:validation(表单没通过自己的检查,或服务器返回 422)、network(连不上服务器)和 reauth_failed(重新认证对话框里的口令不对)。见 web/workbench/ 里的 denials.js。
模型角色(在工具调用里) 一条错误的工具结果 Error: denied (<code>): <message>,最多 500 个字符。
调度器(工具调用之外,例如 budget) 任务转为 needs_attention,原因是 <code>: <message>。
执行 Agent 这一拍跳过这次写入,并把 <request_id>: <code> 记入 TickReport.denied。之后的 tick 会再试。
工作流服务(处理阶段事件时) state 表示阶段已经往前走了,事件被忽略。其他拒绝码会抛回给上报方。
growbridge host register 提示信息,退出码 2。

阶段事件

ports.py 的 StageEventKind 有 12 个成员。其中 11 个由执行 Agent(executor/engine.py)上报,alert_pause 由观察与通知 Agent(observer/service.py)上报。两者都调用 WorkflowService.report。

类型 由谁上报 条件 detail 字段 工作流服务怎么处理
disconnect_affects 执行 Agent 在发现连接恢复的那一拍,阶段处于 running,并且至少有一条原因成立:due_action、device_differs、unknown_result、gap_too_long。 reasons、seconds、state_unreadable 暂停阶段
readings_stale 执行 Agent 阶段处于 running,连接正常,但在运行单的 sampling.max_gap_seconds 之内没有收到有效读数。 无 暂停阶段
readings_stale 执行 Agent 阶段处于 running,读数是新鲜的,但回读设备状态持续失败,时间超过了 sampling.max_gap_seconds。 reason = "state_unreadable"、seconds 暂停阶段
external_change 执行 Agent 阶段处于 running,设备状态和执行 Agent 在本时段最后确认的值不一致。 differences:由 channel、field、expected、actual 组成的列表 暂停阶段
external_change 执行 Agent 阶段处于 running,同一个通道上连续 3 次写入以 failed 告终。 channel、level、failed 暂停阶段
clock_anomaly 执行 Agent 阶段处于 running,而墙上时钟不可信:主机时间没有同步,或者时钟跳变超过 5 秒。 无 暂停阶段
result_unknown 执行 Agent 阶段处于 running,控制服务里有结果未知且尚未确定的动作。 request_ids 暂停阶段
pump_off_unconfirmed 执行 Agent 关泵联锁生效,有活动阶段,并且这一拍的关泵没有得到确认。 无 把阶段转入 recovery_check
transport_unconfirmed 执行 Agent 阶段处于 running、paused 或 manual,而旧传输停止还没有得到确认。 无 把阶段转入 recovery_check
end_condition_met 执行 Agent 阶段处于 running,end_pending 为 false,并且从 started_at 起已经过了 duration_seconds。 无 保持 running,并设置 end_pending
end_actions 执行 Agent end_pending 为 true,并且主机控制通道上的每个结束动作都已发出。水泵不在其中。 confirmed confirmed 为 true:结束阶段。confirmed 为 false:把阶段转入 recovery_check。
alert_pause 观察与通知 Agent 一条带 pause_stage 的告警规则触发且有活动阶段;或者运行中的阶段所依赖的传感器读数冻结(这时 rule 是 frozen:<传感器>,period 是冻结时段)。 rule、alert(冻结引起的暂停还有 period;只有存在未解决的告警时才有 alert) 暂停阶段
rule_pause 执行 Agent 阶段处于 running,一条 on_missing = "pause" 的反馈规则拿不到它那个传感器的有效读数。 rules 暂停阶段
max_wait_expired 执行 Agent 阶段处于 paused 的时间超过了运行单的 max_wait_seconds。 无 on_expiry = "stop":停止阶段。否则保持 paused,并把到期这件事写入历史。

执行 Agent 为处于 running 的阶段上报的每个事件,还会带上 detail.right_number,也就是观察到该事件时所持阶段写入权的编号。被采纳的事件,其 detail 会随阶段历史一起保存(wf_history.detail)。事件让阶段暂停或进入 recovery_check 时,运行时会产生告警 stage_waiting,写明事件名和这份 detail;见故障处理手册。runtime.py 的 DEFAULT_ALERT_RULES 是空的,所以守护进程里没有能上报 alert_pause 的告警规则。

工作流服务里的结果 什么情况 效果
忽略 阶段不存在,或者这个事件 ID 已经处理过。 无
丢弃 detail.right_number 不是阶段现在持有的阶段写入权;或者阶段当前的状态不适用这个事件。 事件记录为 dropped。
暂停阶段 事件属于七种暂停类型之一,并且阶段处于 running。 状态变为 paused,阶段写入权被撤销,记下 paused_at。
把阶段转入 recovery_check 阶段处于 running、paused 或 manual;对 end_actions 来说,是处于 running 且 end_pending。 状态变为 recovery_check;阶段、人工和养护写入权都被撤销;prior_state 保留之前的状态。
结束阶段 end_actions 且 confirmed 为 true,阶段处于 running 且 end_pending。 状态变为 ended,阶段写入权被撤销。还有阶段没跑时,轮次转到 stage_review,否则转到 data_verification。
停止阶段 max_wait_expired,阶段处于 paused,且运行单写的是 on_expiry = "stop"。 状态变为 stopped。轮次随后等待一个选择(awaiting_choice)。

被采纳的事件会和状态变化在同一个事务里记录为 applied。同一个事件 ID 最多推进阶段一次。执行 Agent 生成的 ID 形如 <kind>:<stage_id>:<key>:<phase start>,每个 ID 在一个时段里只上报一次;一个时段指阶段、阶段状态和阶段写入权三者的一种组合。

动作状态

archive/models.py 的 ActionState 有 6 个成员。动作账本里的每条记录都处于其中一种状态。中文标签见术语表。

状态 含义 什么时候进入
pending 动作已记入账本,还什么都没有发送。 控制服务受理请求时。
maybe_sent 写入正在发往设备。 写入发出之前的那一刻。
confirmed 回读显示设备处于计划的档位,并且是手动模式。此时会记下 confirmed_at 和 confirmed_level。 写入之后的回读对上了。
unknown 结果未知:无法确定这次写入有没有生效。在它被确定下来(settled_at)之前,普通写入会以 unsettled 被拒绝。 没有收到回执,发送时连接断开,无法回读,进程在动作处于 maybe_sent 时停止,或者灌溉后的关泵没有得到确认。
failed 写入没有生效。 写入发不出去,设备拒绝,回读的档位不一致,或者回读的模式不是手动。
void 动作排了队,但从未发送。 启动时,它的写入权被交接时,恢复编号变化时,同一通道上的保护写入作废了它,或者发送前的复核拒绝了它。

unknown 的动作通过三种方式确定下来:回读设备状态(水泵除外),关泵得到确认(针对水泵),或者现场核对。对 failed 或 void 的动作,执行 Agent 会发一个新请求来替代,并在 supersedes 里写上旧请求的 ID。

另见


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