ZeroClaw SOP Fan-In 实战:用 MQTT 消息触发自动化 SOP 运行

原创2026-09-19 12:29:541,692 阅读
文章标签:AI AgentAgent 框架交互助手人工智能大模型本地部署Agent 工作流工具调用MCP 服务RAG多模态插件系统CLI桌面应用嵌入式物联网

ZeroClaw SOP Fan-In 实战:用 MQTT 消息触发自动化 SOP 运行

ZeroClaw 的 SOP(Standard Operating Procedure)引擎支持多种"扇入"(fan-in)事件源,MQTT 是其中一类活的事件源:MQTT 监听器订阅 broker 上的主题,为每条到达的消息构建一个 SOP 事件,再派发给引擎,凡是主题模式匹配、条件表达式成立的已加载 SOP 都会自动启动一次运行。本文以 docs/book/src/sop/fan-in/mqtt.md 为主线,结合 crates/zeroclaw-channels/src/orchestrator/mqtt.rs、crates/zeroclaw-runtime/src/sop/dispatch.rs、crates/zeroclaw-config/src/schema.rs 等源码,讲透"如何用一条 MQTT 消息拉起一段 SOP 流程",读完你可以独立完成从频道配置、SOP 触发器编写到消息发布验证、审批观察的完整闭环。

一、MQTT 在 SOP 体系中的定位

在 ZeroClaw 中,fan-in 指一切能启动 SOP 运行的外部事件源。每个事件源把事件交给 SOP 引擎的 dispatch_sop_event,引擎用同一条匹配路径把每个事件与所有已加载 SOP 的触发器做匹配,命中的 SOP 就启动运行(见 docs/book/src/sop/fan-in/overview.md)。MQTT 正是这样的活事件源之一,它与 Webhook、Filesystem、AMQP 并列,同属当前可用的实时来源。

MQTT 路径有两条明确的分工边界:

  • 传输侧(broker URL、凭据、TLS、QoS、订阅主题列表)由 MQTT 频道 配置负责,对应配置节 [channels.mqtt];
  • 触发侧(topic 模式、condition 条件表达式)由本文对应的 SOP 触发器负责,即 SopTrigger::Mqtt。

整条链路由 channel-mqtt 构建特性(build feature)门控:只有在编译时启用了该特性,MQTT 监听器才会被接入运行时。

从源码结构看,MQTT 到 SOP 的接线是独立于聊天频道体系的:crates/zeroclaw-channels/src/orchestrator/mqtt.rs 文件开头的注释明确指出——"This is NOT a Channel trait implementor——it routes MQTT messages to the SOP engine via dispatch_untrusted_fan_in, not to the chat loop"。也就是说,MQTT 消息不会进入 agent 对话循环,而是专职喂养 SOP 引擎。

二、触发器构成:topic + 可选 condition

MQTT 触发器的结构定义在 crates/zeroclaw-runtime/src/sop/types.rs:

/// MQTT message arrival. Live: delivered by the MQTT listener.
Mqtt {
    /// Topic filter. `+` matches one level, `#` matches the remaining levels.
    topic: String,
    /// Optional expression evaluated against the message payload; the run
    /// starts only when it holds.
    #[serde(default)]
    condition: Option<String>,
},

一个 MQTT 触发器只有两个字段:

字段 必填 作用
topic 是 订阅过滤器,支持 + 与 # 通配符
condition 否 可选条件表达式,对消息 payload 求值,成立才启动运行

在 SOP 定义(<sops_dir>/<sop_name>/SOP.toml)中,一个 MQTT 触发器形如:

[[triggers]]
type = "mqtt"
topic = "plant/+/pressure"
condition = '$.value > 85'

配合 zeroclaw sop validate <name> 可在运行前校验定义是否合法(SOP 文件完整格式见 SOP 语法参考)。

三、主题匹配:+ 与 # 通配符

MQTT 触发器使用 MQTT 协议自身的主题通配符语义:

  • +:匹配恰好一级;
  • #:匹配剩余所有级(必须位于过滤器末尾)。

消息到达时,监听器把消息的发布主题作为事件 topic 参与匹配。以下匹配行为在 crates/zeroclaw-runtime/src/sop/engine.rs 的单元测试中被逐一钉死,可以直接作为语义参考:

assert!(mqtt_topic_matches("a/b/c", "a/b/c"));   // 精确匹配
assert!(!mqtt_topic_matches("a/b/c", "a/b/d"));
assert!(!mqtt_topic_matches("a/b/c", "a/b"));     // 级数不足,不匹配
assert!(!mqtt_topic_matches("a/b", "a/b/c"));     // 级数溢出,不匹配
assert!(mqtt_topic_matches("+/+/+", "a/b/c"));    // 三个 + 各占一级
assert!(!mqtt_topic_matches("+/+", "a/b/c"));     // + 只匹配一级
assert!(mqtt_topic_matches("#", "a/b/c"));        // # 匹配剩余所有级
assert!(mqtt_topic_matches("a/#", "a/b/c"));      // a/# 匹配 a 之下的所有层级
assert!(!mqtt_topic_matches("b/#", "a/b/c"));     // 首级不同,不匹配

通配符测试还验证了组合场景:plant/+/pressure 能命中 plant/pump_3/pressure 但不会命中 plant/pump_3/temperature;plant/# 既能命中 plant/pump/pressure 也能命中 plant/a/b/c/d。注意:+ 只占一级,plant/+ 无法匹配 plant/a/b,这一点与 AMQP 的 */# 语义不同,容易踩坑。

四、条件匹配:condition 对 payload 求值

MQTT 消息的 payload 原文会被原样转发进 SOP 事件负载(event payload),供可选的触发器 condition 使用。步骤上下文(step context)收到的则是经过**截断、净化、提示词守卫(prompt-guard)筛查、框架化(framed)**之后的形式——外部不可信文本永远不会被直接拼进模型上下文(详见 SOP 语法参考 中的 untrusted input 配置,如 untrusted_payload_max_bytes、untrusted_input_guard)。

condition 使用与步骤 when: 守卫相同的表达式语法(完整表格见 SOP 语法参考),支持两种形式:

JSON Path 形式(以 $ 开头,payload 必须是 JSON):

表达式 Payload 匹配
$.value > 85 {"value":90} 是
$.value >= 85 {"value":85} 是
$.temp < 25 {"temp":20} 是
$.status == "critical" {"status":"critical"} 是
$.data.sensor.value > 85 {"data":{"sensor":{"value":87.3}}} 是
$.readings.1 == 20 {"readings":[10,20,30]} 是
$.nonexistent > 0 {"value":90} 否

路径规则:点号分段,数组元素用数字段(如 $.readings.1),不支持括号语法、通配符、过滤器、递归下降。缺失键、越界索引、非法 JSON、空 payload 一律 fail-closed(判定不匹配)。

直接数字形式(无前导 $,payload 整体当作标量数字比较):如 > 0 匹配 1、!= 0 匹配 1,而 > 0 对 not a number 不匹配。

操作符共六种:==、!=、>、>=、<、<=。解析器按最长优先匹配操作符 token;JSON Path 比较先尝试数值比较,两侧都能解析为数字则按数值比较,否则按字符串比较;比较符两侧的双引号会被剥离,因此字符串字面量要加引号($.status == "critical"),JSON 布尔值会被转换为字符串 true/false 再比较($.active == "true")。条件只支持单个比较,不支持 AND/OR/NOT 组合。空条件无条件匹配。

从触发器注册表(crates/zeroclaw-runtime/src/sop/trigger_registry.rs)的投影可以看出,MQTT 与 AMQP 的 payload 契约被标记为 open(任意用户 JSON),因此创作界面会提供"引导式 path/操作符/值 构建器 + 样例 payload 探测"而不是固定字段列表。

五、传输侧配置:[channels.mqtt]

触发器的"弹药"来自传输侧订阅。<a href="https://link.gitcode.com/i/c2cd724be7244156609a7b6549a7aa39" target="_blank">channels.mqtt] 的完整字段定义在 [crates/zeroclaw-config/src/schema.rs:

字段 默认值 说明
enabled false 频道是否激活;运行时只加载 enabled = true 的频道
broker_url —(必填) broker 地址,如 mqtt://localhost:1883 或 mqtts://broker.example.com:8883
client_id —(必填) MQTT 客户端 ID,broker 内必须唯一
topics [] 订阅主题列表(如 sensors/#、alerts/+/critical),至少一个
qos 1 QoS 级别:0 至多一次、1 至少一次、2 恰好一次
username / password 无 可选认证凭据(password 标记为 secret)
use_tls false 是否启用 TLS,必须与 broker_url 的 scheme 配对
keep_alive_secs 30 保活间隔(秒),防止空闲时被 broker 断开
excluded_tools [] 从该频道工具规格中排除的工具(对话场景使用)

一个最小可用的 MQTT SOP 监听配置示例:

[channels.mqtt.sensors]
enabled = true
broker_url = "mqtt://localhost:1883"
client_id = "zeroclaw-sop"
topics = ["sensors/#"]
qos = 1
username = "zeroclaw"
password = "changeme"
keep_alive_secs = 30

配置校验(MqttConfig::validate,见 crates/zeroclaw-config/src/schema.rs)会检查:

  • qos 只能是 0、1、2;
  • broker_url 必须以 mqtt:// 或 mqtts:// 开头;
  • use_tls 与 scheme 必须一致:mqtt:// + use_tls = true 报错,mqtts:// + use_tls = false 也报错——TLS 标志与 URL 不匹配是最常见的连接失败原因;
  • topics 至少一项;
  • client_id 非空。

监听器的底层实现(crates/zeroclaw-channels/src/orchestrator/mqtt.rs)使用 rumqttc 客户端:按 keep_alive_secs 设置保活、按用户名密码设置凭据、use_tls 时切换为 Transport::tls_with_default_config(),然后把 config.topics 逐条以映射后的 QoS 订阅。端口解析默认 mqtt:// 取 1883、mqtts:// 取 8883;broker 断开后 rumqttc 会自动重连,监听循环持续运行。

需要注意的是:监听器只有在 daemon / channel-start 路径下才会被拉起。从 crates/zeroclaw-runtime/src/daemon/mod.rs 可以看到,daemon 通过 DaemonRegistry::register_mqtt 注入 starter,且仅当某个 enabled agent 的 channels 里引用了 mqtt.<alias> 时才真正启动该监听器(组件级 supervisor 负责拉起与退避重启)。

六、端到端打通:从发布消息到运行启动

在 SOP 已加载、MQTT 频道已订阅的前提下,用任意 broker 客户端向触发器模式命中的主题发布一条消息即可触发。例如:

# 发布 JSON 负载,命中 condition 为 $.value > 85 的触发器
mosquitto_pub -h localhost -t "plant/pump/pressure" -m '{"value": 90}'

消息到达监听器后的处理链路(对应 crates/zeroclaw-channels/src/orchestrator/mqtt.rs):

  1. eventloop.poll() 收到 Packet::Publish;
  2. payload 经 String::from_utf8_lossy 转成字符串(注意:非 UTF-8 字节会被替换,二进制负载不适用于文本化条件求值);
  3. 通过 SopIngress::new(...).dispatch(SopTriggerSource::Mqtt, Some(&msg.topic), Some(&payload_raw), None, None) 派发,topic 与 payload 一并送入统一入口。

SopIngress 是不可信 fan-in 的统一入口适配器(crates/zeroclaw-runtime/src/sop/dispatch.rs),它统一负责:引擎/审计句柄可用性诊断、source-interest 预过滤(wants_source:没有任何已加载 SOP 声明 MQTT 触发器时直接返回 NotInterested,避免无谓开销)、不可信输入截断、事件时间戳、派发结果日志。

通过入口后进入核心派发 dispatch_sop_event_filtered:

  • 安全筛查:基于 ContentSafety 对事件做提示词守卫筛查,untrusted_input_guard = "block" 时直接返回 BlockedUnsafe(可疑内容还会写入 log_suspicious_untrusted 审计);
  • 匹配阶段:engine.match_trigger(&event) 遍历所有已加载 SOP,凡触发器 topic 模式命中事件 topic、condition(如有)对 payload 成立者进入候选(crates/zeroclaw-runtime/src/sop/engine.rs)——注意这里是"每个已加载的匹配 SOP 各启动一次运行",一个事件可以扇出多个运行;
  • 准入阶段:按 SOP 的 max_concurrent / admission_policy / max_pending_approvals 决定 Admit、Defer、Coalesce 或 Drop;
  • 启动阶段:start_run 创建运行,返回首个动作(ExecuteStep / WaitApproval / DeterministicStep 等),并通过 SopAuditLogger 持久化运行启动审计。

派发结果 DispatchResult 有六种形态:Started、Skipped、Deferred、Coalesced、BlockedUnsafe、NoMatch。MQTT 属于 at-most-once 来源:rumqttc 收到消息即 ack,引擎无法回执重投,因此当准入被 Deferred(背压)时,MQTT 只会记录一条响亮的日志而不会重投递——丢失的触发器只能靠下一条到达的消息自然恢复(这是 docs/book/src/sop/syntax.md 中 admission 与背压语义在传输层上的体现)。编排 MQTT 触发器时,应把背压视为"本次事件被记录并跳过",而非"稍后重试"。

七、批准与观察:命中检查点的运行

运行中任何命中 kind: checkpoint(或 requires_confirmation: true)的步骤都会暂停为 WaitingApproval 状态(确定性运行的检查点则为 PausedCheckpoint)。两种方式观察与放行:

方式一:CLI

zeroclaw sop list          # 列出 SOP 定义与运行状态
zeroclaw sop approve       # 放行等待中的审批

方式二:Gateway API(带外审批)

  • GET /admin/sop/pending —— 列出所有等待人工的暂停运行;
  • POST /admin/sop/approve —— 放行指定 run_id;
  • POST /admin/sop/deny —— 拒绝并取消该运行。

这三个端点在 crates/zeroclaw-gateway/src/lib.rs 注册,实现在 crates/zeroclaw-gateway/src/api_sop.rs:pending 响应中每条记录包含 run_id、sop_name、step、total_steps、waiting_since,并用 kind 区分 approval(WaitingApproval)与 checkpoint(PausedCheckpoint)两种暂停形态。审批端点需要认证(配对令牌),且只有在 gateway 实例持有 SOP 引擎句柄时才可用(未启用 SOP 时返回 sop_disabled)。

若需要运行间的失败通知、重试与分支路由,可在 SOP.md 步骤中使用 on_failure: retry:<n> / goto:<step>、switch: 等路由子弹(详见 SOP 语法参考)。

八、故障排查

结合 fan-in 总览的故障排查表 与 MQTT 频道页,MQTT 场景最常见的三类问题与处理办法:

症状 可能原因 处理
启动时连接错误 broker_url 的 scheme 与 use_tls 不一致 让二者配对:mqtt:// 配 use_tls = false,mqtts:// 配 use_tls = true;同时确认 QoS ∈ {0,1,2}、client_id 非空
已订阅但收不到消息 频道 topics 过滤器与发布主题不匹配 核对 [channels.mqtt] 的 topics 及通配符与发布方实际发出的主题
SOP 始终不启动 触发器 topic 模式不匹配、condition 对 payload 不成立,或订阅未生效 核对触发器 topic 与事件主题;用 JSON path 求值验证 condition;确认监听器确实被拉起(enabled agent 引用了 mqtt.<alias> 且 zeroclaw daemon 在运行)

此外,如果运行启动了但某一步没有执行,优先确认是否处于无 agent 循环的 headless 场景——headless 派发只记录 ExecuteStep 为 pending 而不自动执行,需要为 ExecuteStep 运行 agent 循环,或把步骤设计为在审批处暂停。

九、延伸阅读

  • MQTT 频道:broker 连接、TLS、QoS 的传输侧完整说明
  • Fan-in 总览:dispatch_sop_event 匹配路径、安全默认值、全部触发源状态与故障排查总表
  • SOP 语法参考:SOP.toml / SOP.md 完整格式、admission 策略、condition 语法全表、untrusted input 配置
  • SOP 如何运行:含 MQTT listener → Dispatch → Engine 的事件流图与运行时契约
  • AMQP fan-in:同为消息中间件,AMQP 的 */# 路由键语义与 dispatch 模式与之互补
登录后查看全文
zeroclaw