ZeroClaw SOP Fan-In 实战:用 MQTT 消息触发自动化 SOP 运行
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):
eventloop.poll()收到Packet::Publish;- payload 经
String::from_utf8_lossy转成字符串(注意:非 UTF-8 字节会被替换,二进制负载不适用于文本化条件求值); - 通过
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模式与之互补