跳转至

严格模式错误排查参考指南 (Strict Mode Reference)

有关何时以及如何将算子库置于 Worker 子进程进行物理隔离的系统指引，请参阅 基于 Worker 子进程的算子物理隔离。本篇文档是专门用于排查与修正隔离不兼容缺陷的全量规则速查字典。

在本文中，“aprocess”指代 Griptape Nodes 底层对开发者手写的 process 方法进行协程包裹后的执行阶段。规则描述中所指的“在 aprocess 期间”，即等价于“在算子执行计算期间，包括在你自己编写的 process 方法体内”。

严格模式 (Strict Mode) 是一套在主编排进程 (Orchestrator) 与 Worker 子进程之间严格生效的运行时契约。当算子违反契约时，框架会记录带有唯一命名标识的违规项，并将其直接注入到节点的执行结果中。开发者可在图形编辑器中直观看到清晰的错误标识与整改建议，而不会遭遇让人一头雾水的心智负担、静默失效或系统级死锁。

严格模式永远处于强制开启状态，不提供任何关闭开关或环境变量。规则严格划分为两大类别： 1. 正确性规则 (Correctness rules)：直接导致节点计算中断失败； 2. 人体工程学契约规则 (Ergonomics rules)：抛出明确的控制台告警，在 Worker 端视情况升级为致命失败。

违规呈现与告警机制 (How it surfaces)

违规项会自动附加在节点返回的 ResultPayload 结果载荷中。在编辑器中，选中报错节点的输出详情面板即可看到违规规则 ID、严重程度以及修复引导。

在后台终端中，所有违规行为均通过 griptape_nodes.strict_mode 标准日志器输出。建议在本地开发阶段将日志级别设置为 WARNING 或更低，以便在控制台中近乎实时地发现问题。

全量规则目录字典 (Rule Catalog)

一、正确性规则（直接阻断执行并报错 ❌）

1. reentrant-bus-in-init

  • 违规行为：算子在自身的构造函数 __init__ 内部向引擎事件总线发起了请求（例如查询配置、请求密钥等）。
  • 底层原因：Worker 子进程在算子库加载阶段会预先执行一次无参 Schema 预检以探测端口，在预检阶段再次重入事件总线会直接引发致命死锁。
  • 整改修复指引：将一切请求逻辑移出 __init__，改放入 process() 或在对象构造完成之后才触发的生命周期钩子中。

二、人体工程学与契约规则（告警/升级失败 ⚠️）

1. parameter-behaviors-dropped-in-schema

  • 违规行为：参数上挂载的自定义数据转换器 (converters)、校验器 (validators) 或控件特征 (traits) 未能在 Worker 导出的静态 Schema 中被主进程捕获。
  • 底层原因：主编排进程持有的只是该算子类的轻量哑桩 (Stub)，无法直接执行自定义 Python 校验函数，导致前端编辑时无法即时触发校验。
  • 整改修复指引：在 process() 内部手动再次执行核心转换或校验逻辑，确保 Worker 在使用真实数值时能严格把关；或者接受此差异（仅作为纯界面的视觉语法糖）。

2. parameter-mutation-during-aprocess

  • 违规行为：算子在 process / aprocess 执行计算中途直接调用了 self.add_parameter(...) 或 self.remove_parameter_element(...)。
  • 底层原因：在 Worker 模式下，此类原生属性修改仅作用于 Worker 本地即将被垃圾回收的临时对象，主编排器绝对无法同步感知。
  • 整改修复指引：通过派发官方解耦请求 AddParameterToNodeRequest 或 RemoveParameterFromNodeRequest，将动态加减端口的动作通过总线持久化同步回主编排器。

3. connection-hooks-inert-on-worker

  • 违规行为：运行在 Worker 隔离模式下的算子类重写了一个或多个拓扑连线生命周期钩子（如 allow_incoming_connection、after_incoming_connection 等）。
  • 底层原因：连线拓扑属于主编排进程独占持有的资产，连线建立时回调的是主进程的哑桩类，你在子进程里重写的 Python 钩子永远不会被触发。
  • 整改修复指引：强依赖连线回调以动态增删端口的复杂自适应算子，不支持在 Worker 隔离模式下运行；请将算子库改在 Shared（主进程共享）模式下启动，或移除对连线钩子的重写。

4. value-hooks-execute-only-on-worker

  • 违规行为：运行在 Worker 隔离模式下的算子类重写了 before_value_set 或 after_value_set。
  • 底层原因：在隔离模式下，这些数值钩子仅在节点计算输入注入时被触发；当用户在前端属性面板手动修改下拉菜单或数值时，主进程由于缺少代码实体，完全无法触发这些钩子来实现实时联动显隐。
  • 整改修复指引：将这些数值钩子仅用于纯粹的输入值预处理转义；若必须实现依赖前端用户输入实时改变界面布局的联动交互，请将该库置于 Shared 共享模式运行。