SOP 的运行方式

运行时协定

• SOP 定义会从 <shared>/sops/<sop_name>/SOP.toml 以及可选的 SOP.md 中加载。
• CLI zeroclaw sop 目前仅管理定义：list、validate、show。
• SOP 运行由实时事件汇入（经身份验证的 webhook、MQTT、文件系统或 AMQP）启动，也可由守护进程针对 cron 触发器定期执行的 SOP 维护周期，或代理内工具 sop_execute 启动。其余触发器类型（外围设备和日历）已定义并完成匹配，但尚未接入实时事件源（参见 SOP Fan-In）。
• 运行进度使用以下工具：sop_status、sop_approve、sop_advance。
• 运行状态默认是进程本地的。使用 sop.persist_runs = true 时，默认 SQLite 后端成功初始化后，会将其存储在 <data_dir>/sop/runs.db 下，并在重启后恢复活跃运行。初始化失败会记录警告，并回退到进程本地内存。
• SOP 审计记录以 sop 类别存储在配置的 Memory 后端中。

运行状态和审计历史属于不同界面。有关生命周期归属、取消和重启语义，请参阅后台工作生命周期。

事件流

graph LR
    MQTT[MQTT listener] -->|topic match| Dispatch
    TOOL[sop_execute tool] -->|manual| Dispatch
    WH[Webhook request] -->|authenticated HTTP fan-in| Dispatch
    CRON[Cron trigger] -->|daemon maintenance tick| Dispatch
    GPIO[Peripheral trigger] -.->|defined, unwired| Dispatch

    Dispatch --> Engine[SOP Engine]
    Engine --> Run[SOP Run]
    Run --> Action{Action}
    Action -->|ExecuteStep| Agent[Agent Loop]
    Action -->|WaitApproval| Human[Operator]
    Human -->|sop_approve| Run

开始使用

1. sops_dir 默认未设置，因此默认情况下不会加载运行时 SOP。通过网关、zerocode 或 zeroclaw config set 设置 sops_dir 即可启用。相对值会根据安装根目录（即存放 config.toml 的目录）解析，因此文档中所述的 shared/sops 会解析为 <install>/shared/sops，也就是 SOP 作者写入的同一目录。绝对值或以 ~-前缀的值将按原样使用。将其重新设置为 ""（或移除）会再次禁用运行时 SOP 加载；CLI 在离线检查时仍会回退到 <install>/shared/sops。

   正在从较早的构建版本迁移？ 相对 sops_dir 值现在会相对于安装根目录进行解析，与 skill-bundles 目录的解析方式一致。较早的构建版本对同一设置使用了两个不同的根目录，因此请在升级前检查这两个根目录：

   在较早的构建版本中显示	它使用的根目录	sops_dir = "shared/sops" 最终位于何处
   运行时加载和本地 zeroclaw sop CLI	data_dir	<data_dir>/shared/sops
   Web 和 RPC SOP 编写	<install>/shared	<install>/shared/shared/sops（重复的片段）

   现在两者都解析为唯一的规范路径 <install>/shared/sops。检查两个旧位置，并将其中找到的所有定义移入 <install>/shared/sops；升级后，留在任一目录树中的定义都将不可见。通过旧 Web 或 RPC 界面创建的定义最容易遗漏，因为它们位于重复的写入路径中，而不是文档所述的位置。

   任何其他相对值也会以相同方式移动：sops_dir = "my-sops" 会从 <data_dir>/my-sops（运行时和 CLI）或 <install>/shared/my-sops（Web 和 RPC 编写）移动到 <install>/my-sops。绝对值和以 ~- 开头的值不受影响。

   未设置的情况也随之改变：离线 CLI 回退机制之前会扫描 <data_dir>/sops，现在则扫描 <install>/shared/sops。

   zeroclaw sop list读取新位置，因此升级后如果列表为空，说明定义仍位于旧目录树之一中。

2. 创建一个 SOP 目录，例如：

   ~/.zeroclaw/shared/sops/deploy-prod/SOP.toml
   ~/.zeroclaw/shared/sops/deploy-prod/SOP.md
   

3. 验证和检查定义：

   sh

   zeroclaw sop list
   zeroclaw sop validate
   zeroclaw sop show deploy-prod
   

4. 触发器通过配置的事件源运行，或通过代理轮次中的 sop_execute 手动触发。

有关触发器路由和身份验证详情，请参见 SOP Fan-In。