Cómo se ejecutan los SOPs

Contrato de tiempo de ejecución

• Las definiciones de SOP se cargan desde <shared>/sops/<sop_name>/SOP.toml y el archivo opcional SOP.md.
• La CLI zeroclaw sop actualmente solo gestiona definiciones: list, validate, show.
• Las ejecuciones de SOP se inician mediante un agregador de eventos en vivo (webhook autenticado, MQTT, sistema de archivos o AMQP), mediante el ciclo periódico de mantenimiento de SOP del daemon para los desencadenadores cron, o mediante la herramienta del agente sop_execute. Los tipos de desencadenador restantes (periférico y calendario) están definidos y se pueden asociar, pero todavía no están conectados a una fuente de eventos en vivo (consulta Fan-in de SOP).
• La ejecución de la progresión utiliza las herramientas: sop_status, sop_approve, sop_advance.
• El estado de ejecución es local al proceso por defecto. Con sop.persist_runs = true, una inicialización exitosa del backend SQLite predeterminado lo almacena en <data_dir>/sop/runs.db y restaura las ejecuciones activas tras el reinicio. Un fallo en la inicialización registra una advertencia y recurre a la memoria local del proceso.
• Los registros de auditoría de SOP se almacenan en el backend de memoria configurado bajo la categoría sop.

El estado de ejecución y el historial de auditoría son superficies independientes. Consulta Background work lifecycle para conocer la propiedad del ciclo de vida, la cancelación y la semántica de reinicio.

Flujo de eventos

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

Primeros pasos

1. sops_dir no está establecido de forma predeterminada, por lo que la carga de SOP en tiempo de ejecución está desactivada de fábrica. Actívela estableciendo sops_dir a través de la puerta de enlace, zerocode o zeroclaw config set. Un valor relativo se resuelve respecto a la raíz de la instalación (el directorio que contiene config.toml), por lo que el valor documentado shared/sops da como resultado <install>/shared/sops, el mismo directorio en el que escribe el autor de la SOP. Un valor absoluto o con prefijo ~- se utiliza tal cual. Establecerlo de nuevo en "" (o eliminarlo) vuelve a desactivar la carga de SOP en tiempo de ejecución; la CLI sigue recurriendo a <install>/shared/sops para la inspección sin conexión.

   ¿Estás migrando desde una compilación anterior? Los valores relativos de sops_dir ahora se resuelven en relación con la raíz de instalación, de forma coherente con cómo se resuelven los directorios de skill-bundles. Las compilaciones anteriores tenían dos raíces diferentes para la misma configuración, así que comprueba ambas antes de actualizar:

   Mostrar en compilaciones anteriores	Root lo usó	Dónde terminó sops_dir = "shared/sops"
   Carga en tiempo de ejecución y CLI local de zeroclaw sop	data_dir	<data_dir>/shared/sops
   Redacción de SOP para web y RPC	<install>/shared	<install>/shared/shared/sops (doubled segment)

   Ambas ahora apuntan a la única ubicación canónica <install>/shared/sops. Inspecciona ambas ubicaciones antiguas y mueve las definiciones que encuentres allí a <install>/shared/sops; las definiciones que queden en cualquiera de los dos árboles dejarán de ser visibles después de la actualización. Las definiciones creadas a través de la antigua interfaz web o RPC son las más fáciles de pasar por alto, porque se encuentran en la ruta de escritura duplicada en lugar de la ubicación descrita en la documentación.

   Cualquier otro valor relativo se desplaza de la misma manera: sops_dir = "my-sops" pasa de <data_dir>/my-sops (tiempo de ejecución y CLI) o <install>/shared/my-sops (creación web y mediante RPC) a <install>/my-sops. Los valores absolutos y los valores con prefijo ~- no se ven afectados.

   El caso no establecido también cambia: la alternativa de la CLI sin conexión antes exploraba <data_dir>/sops y ahora explora <install>/shared/sops.

   zeroclaw sop list lee la nueva ubicación, por lo que un listado vacío después de la actualización significa que las definiciones todavía se encuentran en uno de los árboles antiguos.

2. Crea un directorio de SOP, por ejemplo:

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

3. Validar e inspeccionar definiciones:

   sh

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

4. El desencadenante se ejecuta a través de las fuentes de eventos configuradas o manualmente desde un turno de agente con sop_execute.

Para detalles de enrutamiento de disparadores y autenticación, consulta SOP Fan-In.