人工智能AI Agent交互助手工具调用MCP Clients本地部署Agent 工作流RAG【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址https://gitcode.com/gh_mirrors/ze/zeroclaw点击查看免费下载SOPStandard Operating Procedure标准操作流程是 ZeroClaw 中由SopEngine执行的确定性程序它提供显式的触发器匹配、人工审批门approval gate与可审计的运行状态。本文以docs/book/src/sop/how-it-works.md为骨架结合 ZeroClaw 仓库源码与配套文档系统讲解 SOP 的运行时契约、事件如何从各类事件源扇入fan-in到引擎、运行如何推进与持久化并给出可复制的上手步骤与故障排查清单。读完你不仅能配置并跑通自己的第一个 SOP还能理解其底层调度、并发准入与安全边界的设计逻辑。SOP 是什么在 ZeroClaw 中SOP 是一份确定性流程定义它不像普通 Agent 对话那样自由发挥而是显式声明触发器trigger、步骤step与审批门由引擎按契约逐步推进。一份 SOP 由两个文件组成SOP.toml清单文件承载身份name、description、version、triggers与执行旋钮并发准入、审批策略等SOP.md可选以## Steps小节书写步骤定义包含步骤标题、工具建议、路由与审批指令。两者缺一不可的只有SOP.toml但解析出的步骤为空时校验会失败。完整的文件格式与步骤语法见 SOP 语法参考。运行时契约SOP 的整个运行生命周期受以下运行时契约约束源自 how-it-works.md 与源码 crates/zeroclaw-runtime/src/sop/mod.rs定义加载SOP 定义从shared/sops/sop_name/SOP.toml加载可附带可选的SOP.md。CLI 只管理定义zeroclaw sop目前只提供list、validate、show三个子命令没有run子命令——运行只能由触发器或sop_execute工具启动。运行启动来源已接线的实时事件扇入鉴权 webhook、MQTT、文件系统、AMQP、守护进程daemon周期性 SOP 维护 tickcron触发器、以及 Agent 内工具sop_execute。peripheral外设与 calendar日历两种触发器类型目前已定义并可匹配但尚未接入实时事件源详见 SOP Fan-In 总览。运行推进工具运行通过工具推进即sop_status、sop_approve、sop_advance。运行状态存储默认进程内process-local。当sop.persist_runs true时默认 SQLite 后端初始化成功后把状态存于data_dir/sop/runs.db并在重启后恢复活跃运行初始化失败会记录警告并回退到进程内内存。审计持久化SOP 审计记录持久化到配置的 Memory 后端类别category为sop。运行状态与审计历史是两个独立的表面运行状态描述这个流程现在进行到哪一步审计历史描述发生过什么。两者的生命周期归属、取消与重启语义见 后台工作生命周期。在源码层面引擎的唯一构造点是build_sop_engine它同时构建共享的SopEngine与SopAuditLogger对见 crates/zeroclaw-runtime/src/sop/mod.rs。该函数接收两个关键目录参数二者角色不同、不可混淆data_dir守护进程状态目录锚定持久化运行存储默认落在data_dir/sop/runs.db除非[sop] run_state_dir覆盖install_root安装根目录config_path的父目录锚定SOP 定义的加载——相对路径的[sop] sops_dir文档推荐值shared/sops解析为install/shared/sops。build_sop_engine在构建时依次完成选择运行存储后端默认持久化 SQLite打开失败时以响亮日志回退到InMemoryRunStore→ 装配审批代理ApprovalBroker 路由适配器→ 注册确定性能力内置能力 注入适配器能力→engine.reload(install_root)加载定义 →engine.restore_runs()恢复运行。事件流从事件源到 SOP 引擎以下是 SOP 事件流的整体图景原图来自 how-it-works.md在源码中所有实时事件源最终都汇入统一的调度路径。核心入口是dispatch_sop_event/dispatch_sop_event_filtered见 crates/zeroclaw-runtime/src/sop/dispatch.rs它按两个阶段处理事件匹配阶段engine.match_trigger(event)把事件与每个已加载 SOP 的触发器逐一匹配得到匹配的 SOP 名称列表无匹配则返回NoMatch。启动阶段对每个匹配的 SOP 执行准入评估admission与start_run产出首个SopRunAction。dispatch.rs通过ingress_kind(source)为每种SopTriggerSource分类其入站路径且刻意没有通配分支——新增触发器类型而不在此分类会产生编译错误从而强制开发者显式决定新事件源如何进入调度SharedIngress共享入站走SopIngress适配器负责句柄校验、源兴趣门控、输入截断与事件盖章MQTTorchestrator/mqtt.rs、Webhookgateway 的/sop/*路由与/webhook的 SOP-first 分支、Filesystemchannels/src/filesystem.rs、Channelchannel-orchestrator 两个调用点、AMQPchannels/src/amqp.rsDedicatedInternalDispatch专用内部路径直接持有非可选句柄Cron守护进程维护 tick 直接调用dispatch_sop_event、Manualsop_execute工具直接调用engine.start_run完全绕过触发器匹配NotYetLive已定义可匹配无实时生产者Peripheral、Calendar。调度结果通过DispatchResult枚举精确表达Started、Skipped冷却或drop策略无空位、Deferred背压、需按传输重投、Coalescedcoalesce策略把并发触发器折叠进在途运行、BlockedUnsafe不可信内容被拦截、NoMatch。值得注意的细节是 AMQP 批处理的**全有或全无all-or-nothing**语义多条 SOP 同时匹配一次 AMQP 投递时要么全部可准入并启动、要么整批回滚重投绝不出现部分启动部分丢弃的双重执行风险对应代码中的2a/2b bug修复逻辑。快速开始配置 sops_dir 并跑通第一个 SOPdocs/book/src/sop/how-it-works.md的 Getting started 小节给出了四步上手流程这里逐条展开。第 1 步启用运行时 SOP 加载sops_dir默认未设置因此运行时 SOP 加载默认是关闭的。通过 gateway、zerocode 或zeroclaw config set设置sops_dir即可开启相对路径解析到安装根目录存放config.toml的目录因此文档推荐的shared/sops实际为install/shared/sops——这正是 SOP 作者实际写入的目录绝对路径或~前缀路径按原样使用把它设回或移除即再次禁用运行时 SOP 加载此时 CLI 仍会回退扫描install/shared/sops供离线检查。源码层面resolve_sops_dircrates/zeroclaw-runtime/src/sop/mod.rs实现该解析非空值先做 tilde 展开再install_root.join(...)未设置、空值或纯空白则回退到default_sops_dir即install/shared/sops。SopConfig::runtime_enabled()用同一哨兵值判断运行时是否启用保证 CLI/RPC 的扫描根目录与守护进程是否构建引擎永远一致。从早期版本升级的迁移提示原文强调早期的构建对同一设置使用了两个不同的根目录升级前务必两处都检查早期版本的表面当时使用的根目录sops_dir shared/sops实际落点运行时加载与本地zeroclaw sopCLIdata_dirdata_dir/shared/sopsWeb 与 RPC SOP 编写install/sharedinstall/shared/shared/sops双段现在两者统一解析为唯一的规范路径install/shared/sops。两处旧位置都要检查把找到的定义移入install/shared/sops遗留在任一棵旧树中的定义在升级后都会消失。最容易遗漏的是通过旧 Web/RPC 表面编写的定义因为它们位于双段写入路径而非文档描述的位置。任何其他相对值也按同样方式迁移sops_dir my-sops会从data_dir/my-sops运行时与 CLI或install/shared/my-sopsWeb/RPC 编写移到install/my-sops。绝对路径与~前缀路径不受影响。未设置的情况也变了离线 CLI 回退目录从data_dir/sops改为扫描install/shared/sops。zeroclaw sop list读取的是新位置因此升级后列表为空通常意味着定义还在旧树里。第 2 步创建 SOP 目录以deploy-prod为例~/.zeroclaw/shared/sops/deploy-prod/SOP.toml ~/.zeroclaw/shared/sops/deploy-prod/SOP.md目录发现规则在load_sops_from_directorycrates/zeroclaw-runtime/src/sop/mod.rs中实现遍历sops_dir下每个子目录仅当目录内存在SOP.toml时才加载加载失败的 SOP 记录警告并跳过其余按名称排序返回。这也解释了为什么只有SOP.md没有SOP.toml的目录永远不会被发现。第 3 步校验与检视定义zeroclaw sop list zeroclaw sop validate zeroclaw sop show deploy-prodvalidate可接名称只校验单个 SOP。校验会对空名称/空描述、缺少触发器、缺少步骤缺失或空SOP.md以及步骤编号跳号给出警告其中缺少步骤意味着运行到执行时会失败需要特别留意。zeroclaw sop show name可检视单个定义的完整内容。第 4 步触发运行通过已配置的事件源触发或在 Agent 回合内用sop_execute手动启动。触发路由与鉴权细节见 SOP Fan-In 总览。触发执行sop_execute 与运行推进工具sop_execute是 Agent 内触发的唯一工具定义在 crates/zeroclaw-runtime/src/tools/sop_execute.rs。它接收两个参数name要执行的 SOP 名称必填与可选的payloadJSON 字符串形式的触发器负载。其执行路径调用engine.start_run(sop_name, event)以SopTriggerSource::Manual为触发器源——绕过触发器匹配直接启动运行属于DedicatedInternalDispatch。一旦运行开始其生命周期与任何其他方式启动的运行完全一致差别仅在于触发器源。运行推进依赖三个工具见 可观测性文档 与运行时工具目录sop_status查询活跃/已完成运行可选指标include_gate_status: true时附带信任阶段与门评估器状态include_metrics: true时附带 SOP 聚合指标sop_approve批准等待中的运行步骤对应契约图中的Human --|sop_approve| Runsop_advance提交步骤结果并推动运行前进。这组工具也出现在[sop] step_mandatory_tools的默认值中[sop_advance, sop_approve, sop_status]确保开启工具作用域强制时生命周期工具始终可用。并发准入与背压SOP.toml中的并发准入字段决定了触发器到达时执行槽已满会发生什么完整参数表见 语法参考字段默认值作用max_concurrent1该 SOP正在执行的运行数上限。停在 HITL 审批或确定性检查点checkpoint的运行会释放执行槽不计入此限。admission_policyparallel当前无法准入的触发器如何处理见下。max_pending_approvals0不限该 SOP 同时停在 HITL 审批的运行数上限。超过后触发器被延迟背压绝不静默丢弃drop策略除外。admission_policy取值SopAdmissionPolicysnake_caseparallel默认最多准入max_concurrent个当前无法准入的触发器被延迟在触发器所在传输上体现为背压/重投绝不静默丢弃。最适合相互独立的工作如 PR 审批类 SOP。hold串行化——仅当该 SOP 无活跃或驻留运行时才准入其他触发器被延迟。用于前置审批步骤不得重叠的流水线。coalesce把并发触发器折叠到已在途的运行上在途运行的最新状态已覆盖它。drop遗留的即发即弃fire-and-forget模式无法准入即丢弃。必须显式选择绝不是默认值。被延迟的触发器的恢复是传输相关的——本版本引擎内没有持久化的待处理触发器队列AMQPdurable_ack true、纯 SOP 调度投递被 nackrequeue truebroker 在有空间时重试AMQP 组合sop_and_agent_loopAgent 侧已消费投递因此背压导致的 SOP 溢出会响亮地记录日志并 ACK不重投避免 Agent 侧被重复执行MQTT / cron / filesystem / channel-router以及其他只记录调度结果的无头源没有逐消息重投机制延迟的触发器在响亮日志后丢弃下一次定时/发布/观察到的事件是唯一恢复途径。对应代码在dispatch.rs中体现为DispatchResult::Deferred与SopAdmission枚举Defer是唯一可重试结果将来可能准入Drop/Coalesce是终结性结果重投永远等不到变化因此 AMQP 批处理只在存在Defer时整批重投。运行状态持久化与恢复运行状态是否在守护进程重启后存活由[sop]配置控制字段默认值作用persist_runstrue持久化运行状态——包括停在 HITL 审批或确定性检查点的运行——使其在重启后存活。设为false得到纯内存、非持久化引擎。run_store_backendsqlitepersist_runs为 true 时的持久化后端。sqlite在运行状态目录下写入runs.db。persist_runs true是默认值因此停在 HITL 审批的运行不会因重启而丢失build_sop_engine在后端无法打开时会以响亮日志回退到内存存储InMemoryRunStore所以该默认是安全的。persist_runs false是文档记载的临时引擎显式退出选项。审计与可观测性SOP 审计条目通过SopAuditLogger持久化到配置的 Memory 后端类别为sop。常见的键模式见 可观测性文档sop_run_{run_id}运行快照启动 完成更新sop_step_{run_id}_{step_number}逐步骤结果sop_approval_{run_id}_{step_number}操作员审批记录sop_timeout_approve_{run_id}_{step_number}超时自动审批记录。检视路径分两层定义层用 CLIzeroclaw sop list/validate [name]/show name运行时状态用 Agent 内工具sop_status、sop_approve、sop_advance。指标方面[observability] backend prometheus时/metrics暴露zeroclaw_*家族指标SOP 聚合指标可通过sop_status的include_metrics: true获取。安全默认值SOP 事件扇入有明确的安全默认值详见 Fan-In 总览关注点机制Webhook 鉴权Gateway 配对 bearer 鉴权 可选的gateway.webhook_secret/X-Webhook-Secret/sop/*与/webhook共享同一限流器。SOP 调度至少需要配置一种控制手段且每个已配置的控制都必须通过。独立的[channels.webhook]别名密钥绝不授权这些路由。Webhook 重放防护可选的X-Idempotency-Key按 SOP 路径命名空间隔离且在/sop/*与/webhook之间彼此隔离。密钥在调度前预留含义是至多一次尝试而非此前运行已启动的证明。MQTT 传输TLS 传输使用mqtts://与use_tls true。文件系统根目录宽泛根目录/、/home、/etc、/var、/proc、/sys、/dev、/tmp在配置校验时被拒绝除非设置allow_broad_rootsinclude/exclude glob 限定事件范围。文件系统符号链接默认在读取任何元数据、哈希或内容之前拒绝符号链接事件路径follow_symlinks true可选择加入但仍要求规范目标解析到被监视的根目录内。不可信触发器输入topic 与 payload 文本在进入模型上下文前被截断、归一化、prompt-guard 筛查并加框framed。不安全的触发器块untrusted_input_guard block以BlockedUnsafe拒绝不安全的不可信事件默认warn只审计并放行。Cron 校验非法 cron 表达式在解析与缓存构建期间 fail-closed。无头调度无头调用者记录运行进度而非自动执行ExecuteStep。无头安全headless safety在调度层实现非 Agent 循环上下文中process_headless_results把ExecuteStep动作记录为 pending 而不是静默执行——这是SOP 启动但步骤未执行排查项的根源。故障排查速查表以下是 Fan-In 总览 中的症状—原因—修复对照症状可能原因修复实时源从未启动 SOP触发器模式不匹配或condition求值失败核对触发器模式与投递事件是否一致对照 payload 检查conditionSOP 已启动但某步骤未执行无活跃 Agent 循环的无头触发器为ExecuteStep运行 Agent 循环或设计运行停在审批处Webhook 触发器从不触发触发路径不完全匹配、SOP 子系统不可用或鉴权被拒以配置了sop.sops_dir的zeroclaw daemon运行精确匹配完整请求路径并提供配置的 bearer/secret 请求头peripheral 或 calendar 触发器从不触发事件源未接入调度器使用实时源Webhook、MQTT、Filesystem、AMQP或用sop_execute启动运行Cron 触发器从不触发维护 tick 未运行没有zeroclaw daemon或zeroclaw channel start单独的gateway start不会运行它、sops_dir未设置/为空、或maintenance_interval_secs 0以非空sop.sops_dir文档值shared/sops和非零sop.maintenance_interval_secs默认60运行zeroclaw daemon或zeroclaw channel start参考阅读SOP 语法参考完整的SOP.toml与SOP.md格式、步骤子项目录、条件表达式与校验规则SOP Fan-In 总览各事件源的调度与鉴权细节SOP 可观测性与审计审计键模式、检视路径与指标SOP 菜谱 与 完整示例StageX 自动更新机器人一个生产级确定性 SOP 流水线AMQP 事件源 sop_execute触发 八步骤无头执行通道总览MQTT、filesystem、AMQP 的传输侧后台工作生命周期运行的生命周期归属、取消与重启语义源码引擎构建与加载 crates/zeroclaw-runtime/src/sop/mod.rs、统一调度 crates/zeroclaw-runtime/src/sop/dispatch.rs、sop_execute工具 crates/zeroclaw-runtime/src/tools/sop_execute.rs赞分享人工智能AI Agent交互助手工具调用MCP Clients本地部署Agent 工作流RAG【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址https://gitcode.com/gh_mirrors/ze/zeroclaw点击查看免费下载相关推荐Electric Agents 深度解析基于持久化事件流的长期运行 Agent 运行时Electric Agents 深度解析基于持久化事件流的长期运行 Agent 运行时 Electric Agents 是 Electric 项目The a后端数据同步数据库人工智能AI AgentMCP 服务Halo 插件自定义 FormKit 输入组件formkit.inputs 契约与运行时注册机制深度解析Halo 插件自定义 FormKit 输入组件 formkit.inputs 契约与运行时注册机制深度解析 导读 Halo 管理后台Console与用户中后端前端CMSNacos Agent 存储规范深度解析持久化模型、运行时发布与一致性契约Nacos Agent 存储规范深度解析持久化模型、运行时发布与一致性契约 导读 本文是 Agent Storage Spec https://link.gi后端微服务配置中心服务注册发现云原生创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ZeroClaw SOP 运行机制深度解析：运行时契约、事件扇入与状态持久化
人工智能AI Agent交互助手工具调用MCP Clients本地部署Agent 工作流RAG【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址https://gitcode.com/gh_mirrors/ze/zeroclaw点击查看免费下载SOPStandard Operating Procedure标准操作流程是 ZeroClaw 中由SopEngine执行的确定性程序它提供显式的触发器匹配、人工审批门approval gate与可审计的运行状态。本文以docs/book/src/sop/how-it-works.md为骨架结合 ZeroClaw 仓库源码与配套文档系统讲解 SOP 的运行时契约、事件如何从各类事件源扇入fan-in到引擎、运行如何推进与持久化并给出可复制的上手步骤与故障排查清单。读完你不仅能配置并跑通自己的第一个 SOP还能理解其底层调度、并发准入与安全边界的设计逻辑。SOP 是什么在 ZeroClaw 中SOP 是一份确定性流程定义它不像普通 Agent 对话那样自由发挥而是显式声明触发器trigger、步骤step与审批门由引擎按契约逐步推进。一份 SOP 由两个文件组成SOP.toml清单文件承载身份name、description、version、triggers与执行旋钮并发准入、审批策略等SOP.md可选以## Steps小节书写步骤定义包含步骤标题、工具建议、路由与审批指令。两者缺一不可的只有SOP.toml但解析出的步骤为空时校验会失败。完整的文件格式与步骤语法见 SOP 语法参考。运行时契约SOP 的整个运行生命周期受以下运行时契约约束源自 how-it-works.md 与源码 crates/zeroclaw-runtime/src/sop/mod.rs定义加载SOP 定义从shared/sops/sop_name/SOP.toml加载可附带可选的SOP.md。CLI 只管理定义zeroclaw sop目前只提供list、validate、show三个子命令没有run子命令——运行只能由触发器或sop_execute工具启动。运行启动来源已接线的实时事件扇入鉴权 webhook、MQTT、文件系统、AMQP、守护进程daemon周期性 SOP 维护 tickcron触发器、以及 Agent 内工具sop_execute。peripheral外设与 calendar日历两种触发器类型目前已定义并可匹配但尚未接入实时事件源详见 SOP Fan-In 总览。运行推进工具运行通过工具推进即sop_status、sop_approve、sop_advance。运行状态存储默认进程内process-local。当sop.persist_runs true时默认 SQLite 后端初始化成功后把状态存于data_dir/sop/runs.db并在重启后恢复活跃运行初始化失败会记录警告并回退到进程内内存。审计持久化SOP 审计记录持久化到配置的 Memory 后端类别category为sop。运行状态与审计历史是两个独立的表面运行状态描述这个流程现在进行到哪一步审计历史描述发生过什么。两者的生命周期归属、取消与重启语义见 后台工作生命周期。在源码层面引擎的唯一构造点是build_sop_engine它同时构建共享的SopEngine与SopAuditLogger对见 crates/zeroclaw-runtime/src/sop/mod.rs。该函数接收两个关键目录参数二者角色不同、不可混淆data_dir守护进程状态目录锚定持久化运行存储默认落在data_dir/sop/runs.db除非[sop] run_state_dir覆盖install_root安装根目录config_path的父目录锚定SOP 定义的加载——相对路径的[sop] sops_dir文档推荐值shared/sops解析为install/shared/sops。build_sop_engine在构建时依次完成选择运行存储后端默认持久化 SQLite打开失败时以响亮日志回退到InMemoryRunStore→ 装配审批代理ApprovalBroker 路由适配器→ 注册确定性能力内置能力 注入适配器能力→engine.reload(install_root)加载定义 →engine.restore_runs()恢复运行。事件流从事件源到 SOP 引擎以下是 SOP 事件流的整体图景原图来自 how-it-works.md在源码中所有实时事件源最终都汇入统一的调度路径。核心入口是dispatch_sop_event/dispatch_sop_event_filtered见 crates/zeroclaw-runtime/src/sop/dispatch.rs它按两个阶段处理事件匹配阶段engine.match_trigger(event)把事件与每个已加载 SOP 的触发器逐一匹配得到匹配的 SOP 名称列表无匹配则返回NoMatch。启动阶段对每个匹配的 SOP 执行准入评估admission与start_run产出首个SopRunAction。dispatch.rs通过ingress_kind(source)为每种SopTriggerSource分类其入站路径且刻意没有通配分支——新增触发器类型而不在此分类会产生编译错误从而强制开发者显式决定新事件源如何进入调度SharedIngress共享入站走SopIngress适配器负责句柄校验、源兴趣门控、输入截断与事件盖章MQTTorchestrator/mqtt.rs、Webhookgateway 的/sop/*路由与/webhook的 SOP-first 分支、Filesystemchannels/src/filesystem.rs、Channelchannel-orchestrator 两个调用点、AMQPchannels/src/amqp.rsDedicatedInternalDispatch专用内部路径直接持有非可选句柄Cron守护进程维护 tick 直接调用dispatch_sop_event、Manualsop_execute工具直接调用engine.start_run完全绕过触发器匹配NotYetLive已定义可匹配无实时生产者Peripheral、Calendar。调度结果通过DispatchResult枚举精确表达Started、Skipped冷却或drop策略无空位、Deferred背压、需按传输重投、Coalescedcoalesce策略把并发触发器折叠进在途运行、BlockedUnsafe不可信内容被拦截、NoMatch。值得注意的细节是 AMQP 批处理的**全有或全无all-or-nothing**语义多条 SOP 同时匹配一次 AMQP 投递时要么全部可准入并启动、要么整批回滚重投绝不出现部分启动部分丢弃的双重执行风险对应代码中的2a/2b bug修复逻辑。快速开始配置 sops_dir 并跑通第一个 SOPdocs/book/src/sop/how-it-works.md的 Getting started 小节给出了四步上手流程这里逐条展开。第 1 步启用运行时 SOP 加载sops_dir默认未设置因此运行时 SOP 加载默认是关闭的。通过 gateway、zerocode 或zeroclaw config set设置sops_dir即可开启相对路径解析到安装根目录存放config.toml的目录因此文档推荐的shared/sops实际为install/shared/sops——这正是 SOP 作者实际写入的目录绝对路径或~前缀路径按原样使用把它设回或移除即再次禁用运行时 SOP 加载此时 CLI 仍会回退扫描install/shared/sops供离线检查。源码层面resolve_sops_dircrates/zeroclaw-runtime/src/sop/mod.rs实现该解析非空值先做 tilde 展开再install_root.join(...)未设置、空值或纯空白则回退到default_sops_dir即install/shared/sops。SopConfig::runtime_enabled()用同一哨兵值判断运行时是否启用保证 CLI/RPC 的扫描根目录与守护进程是否构建引擎永远一致。从早期版本升级的迁移提示原文强调早期的构建对同一设置使用了两个不同的根目录升级前务必两处都检查早期版本的表面当时使用的根目录sops_dir shared/sops实际落点运行时加载与本地zeroclaw sopCLIdata_dirdata_dir/shared/sopsWeb 与 RPC SOP 编写install/sharedinstall/shared/shared/sops双段现在两者统一解析为唯一的规范路径install/shared/sops。两处旧位置都要检查把找到的定义移入install/shared/sops遗留在任一棵旧树中的定义在升级后都会消失。最容易遗漏的是通过旧 Web/RPC 表面编写的定义因为它们位于双段写入路径而非文档描述的位置。任何其他相对值也按同样方式迁移sops_dir my-sops会从data_dir/my-sops运行时与 CLI或install/shared/my-sopsWeb/RPC 编写移到install/my-sops。绝对路径与~前缀路径不受影响。未设置的情况也变了离线 CLI 回退目录从data_dir/sops改为扫描install/shared/sops。zeroclaw sop list读取的是新位置因此升级后列表为空通常意味着定义还在旧树里。第 2 步创建 SOP 目录以deploy-prod为例~/.zeroclaw/shared/sops/deploy-prod/SOP.toml ~/.zeroclaw/shared/sops/deploy-prod/SOP.md目录发现规则在load_sops_from_directorycrates/zeroclaw-runtime/src/sop/mod.rs中实现遍历sops_dir下每个子目录仅当目录内存在SOP.toml时才加载加载失败的 SOP 记录警告并跳过其余按名称排序返回。这也解释了为什么只有SOP.md没有SOP.toml的目录永远不会被发现。第 3 步校验与检视定义zeroclaw sop list zeroclaw sop validate zeroclaw sop show deploy-prodvalidate可接名称只校验单个 SOP。校验会对空名称/空描述、缺少触发器、缺少步骤缺失或空SOP.md以及步骤编号跳号给出警告其中缺少步骤意味着运行到执行时会失败需要特别留意。zeroclaw sop show name可检视单个定义的完整内容。第 4 步触发运行通过已配置的事件源触发或在 Agent 回合内用sop_execute手动启动。触发路由与鉴权细节见 SOP Fan-In 总览。触发执行sop_execute 与运行推进工具sop_execute是 Agent 内触发的唯一工具定义在 crates/zeroclaw-runtime/src/tools/sop_execute.rs。它接收两个参数name要执行的 SOP 名称必填与可选的payloadJSON 字符串形式的触发器负载。其执行路径调用engine.start_run(sop_name, event)以SopTriggerSource::Manual为触发器源——绕过触发器匹配直接启动运行属于DedicatedInternalDispatch。一旦运行开始其生命周期与任何其他方式启动的运行完全一致差别仅在于触发器源。运行推进依赖三个工具见 可观测性文档 与运行时工具目录sop_status查询活跃/已完成运行可选指标include_gate_status: true时附带信任阶段与门评估器状态include_metrics: true时附带 SOP 聚合指标sop_approve批准等待中的运行步骤对应契约图中的Human --|sop_approve| Runsop_advance提交步骤结果并推动运行前进。这组工具也出现在[sop] step_mandatory_tools的默认值中[sop_advance, sop_approve, sop_status]确保开启工具作用域强制时生命周期工具始终可用。并发准入与背压SOP.toml中的并发准入字段决定了触发器到达时执行槽已满会发生什么完整参数表见 语法参考字段默认值作用max_concurrent1该 SOP正在执行的运行数上限。停在 HITL 审批或确定性检查点checkpoint的运行会释放执行槽不计入此限。admission_policyparallel当前无法准入的触发器如何处理见下。max_pending_approvals0不限该 SOP 同时停在 HITL 审批的运行数上限。超过后触发器被延迟背压绝不静默丢弃drop策略除外。admission_policy取值SopAdmissionPolicysnake_caseparallel默认最多准入max_concurrent个当前无法准入的触发器被延迟在触发器所在传输上体现为背压/重投绝不静默丢弃。最适合相互独立的工作如 PR 审批类 SOP。hold串行化——仅当该 SOP 无活跃或驻留运行时才准入其他触发器被延迟。用于前置审批步骤不得重叠的流水线。coalesce把并发触发器折叠到已在途的运行上在途运行的最新状态已覆盖它。drop遗留的即发即弃fire-and-forget模式无法准入即丢弃。必须显式选择绝不是默认值。被延迟的触发器的恢复是传输相关的——本版本引擎内没有持久化的待处理触发器队列AMQPdurable_ack true、纯 SOP 调度投递被 nackrequeue truebroker 在有空间时重试AMQP 组合sop_and_agent_loopAgent 侧已消费投递因此背压导致的 SOP 溢出会响亮地记录日志并 ACK不重投避免 Agent 侧被重复执行MQTT / cron / filesystem / channel-router以及其他只记录调度结果的无头源没有逐消息重投机制延迟的触发器在响亮日志后丢弃下一次定时/发布/观察到的事件是唯一恢复途径。对应代码在dispatch.rs中体现为DispatchResult::Deferred与SopAdmission枚举Defer是唯一可重试结果将来可能准入Drop/Coalesce是终结性结果重投永远等不到变化因此 AMQP 批处理只在存在Defer时整批重投。运行状态持久化与恢复运行状态是否在守护进程重启后存活由[sop]配置控制字段默认值作用persist_runstrue持久化运行状态——包括停在 HITL 审批或确定性检查点的运行——使其在重启后存活。设为false得到纯内存、非持久化引擎。run_store_backendsqlitepersist_runs为 true 时的持久化后端。sqlite在运行状态目录下写入runs.db。persist_runs true是默认值因此停在 HITL 审批的运行不会因重启而丢失build_sop_engine在后端无法打开时会以响亮日志回退到内存存储InMemoryRunStore所以该默认是安全的。persist_runs false是文档记载的临时引擎显式退出选项。审计与可观测性SOP 审计条目通过SopAuditLogger持久化到配置的 Memory 后端类别为sop。常见的键模式见 可观测性文档sop_run_{run_id}运行快照启动 完成更新sop_step_{run_id}_{step_number}逐步骤结果sop_approval_{run_id}_{step_number}操作员审批记录sop_timeout_approve_{run_id}_{step_number}超时自动审批记录。检视路径分两层定义层用 CLIzeroclaw sop list/validate [name]/show name运行时状态用 Agent 内工具sop_status、sop_approve、sop_advance。指标方面[observability] backend prometheus时/metrics暴露zeroclaw_*家族指标SOP 聚合指标可通过sop_status的include_metrics: true获取。安全默认值SOP 事件扇入有明确的安全默认值详见 Fan-In 总览关注点机制Webhook 鉴权Gateway 配对 bearer 鉴权 可选的gateway.webhook_secret/X-Webhook-Secret/sop/*与/webhook共享同一限流器。SOP 调度至少需要配置一种控制手段且每个已配置的控制都必须通过。独立的[channels.webhook]别名密钥绝不授权这些路由。Webhook 重放防护可选的X-Idempotency-Key按 SOP 路径命名空间隔离且在/sop/*与/webhook之间彼此隔离。密钥在调度前预留含义是至多一次尝试而非此前运行已启动的证明。MQTT 传输TLS 传输使用mqtts://与use_tls true。文件系统根目录宽泛根目录/、/home、/etc、/var、/proc、/sys、/dev、/tmp在配置校验时被拒绝除非设置allow_broad_rootsinclude/exclude glob 限定事件范围。文件系统符号链接默认在读取任何元数据、哈希或内容之前拒绝符号链接事件路径follow_symlinks true可选择加入但仍要求规范目标解析到被监视的根目录内。不可信触发器输入topic 与 payload 文本在进入模型上下文前被截断、归一化、prompt-guard 筛查并加框framed。不安全的触发器块untrusted_input_guard block以BlockedUnsafe拒绝不安全的不可信事件默认warn只审计并放行。Cron 校验非法 cron 表达式在解析与缓存构建期间 fail-closed。无头调度无头调用者记录运行进度而非自动执行ExecuteStep。无头安全headless safety在调度层实现非 Agent 循环上下文中process_headless_results把ExecuteStep动作记录为 pending 而不是静默执行——这是SOP 启动但步骤未执行排查项的根源。故障排查速查表以下是 Fan-In 总览 中的症状—原因—修复对照症状可能原因修复实时源从未启动 SOP触发器模式不匹配或condition求值失败核对触发器模式与投递事件是否一致对照 payload 检查conditionSOP 已启动但某步骤未执行无活跃 Agent 循环的无头触发器为ExecuteStep运行 Agent 循环或设计运行停在审批处Webhook 触发器从不触发触发路径不完全匹配、SOP 子系统不可用或鉴权被拒以配置了sop.sops_dir的zeroclaw daemon运行精确匹配完整请求路径并提供配置的 bearer/secret 请求头peripheral 或 calendar 触发器从不触发事件源未接入调度器使用实时源Webhook、MQTT、Filesystem、AMQP或用sop_execute启动运行Cron 触发器从不触发维护 tick 未运行没有zeroclaw daemon或zeroclaw channel start单独的gateway start不会运行它、sops_dir未设置/为空、或maintenance_interval_secs 0以非空sop.sops_dir文档值shared/sops和非零sop.maintenance_interval_secs默认60运行zeroclaw daemon或zeroclaw channel start参考阅读SOP 语法参考完整的SOP.toml与SOP.md格式、步骤子项目录、条件表达式与校验规则SOP Fan-In 总览各事件源的调度与鉴权细节SOP 可观测性与审计审计键模式、检视路径与指标SOP 菜谱 与 完整示例StageX 自动更新机器人一个生产级确定性 SOP 流水线AMQP 事件源 sop_execute触发 八步骤无头执行通道总览MQTT、filesystem、AMQP 的传输侧后台工作生命周期运行的生命周期归属、取消与重启语义源码引擎构建与加载 crates/zeroclaw-runtime/src/sop/mod.rs、统一调度 crates/zeroclaw-runtime/src/sop/dispatch.rs、sop_execute工具 crates/zeroclaw-runtime/src/tools/sop_execute.rs赞分享人工智能AI Agent交互助手工具调用MCP Clients本地部署Agent 工作流RAG【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址https://gitcode.com/gh_mirrors/ze/zeroclaw点击查看免费下载相关推荐Electric Agents 深度解析基于持久化事件流的长期运行 Agent 运行时Electric Agents 深度解析基于持久化事件流的长期运行 Agent 运行时 Electric Agents 是 Electric 项目The a后端数据同步数据库人工智能AI AgentMCP 服务Halo 插件自定义 FormKit 输入组件formkit.inputs 契约与运行时注册机制深度解析Halo 插件自定义 FormKit 输入组件 formkit.inputs 契约与运行时注册机制深度解析 导读 Halo 管理后台Console与用户中后端前端CMSNacos Agent 存储规范深度解析持久化模型、运行时发布与一致性契约Nacos Agent 存储规范深度解析持久化模型、运行时发布与一致性契约 导读 本文是 Agent Storage Spec https://link.gi后端微服务配置中心服务注册发现云原生创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
