Fonctionnement des SOP

Contrat d’exécution

• Les définitions des SOP sont chargées depuis <shared>/sops/<sop_name>/SOP.toml, avec un fichier SOP.md facultatif.
• La commande CLI zeroclaw sop gère actuellement uniquement les définitions : list, validate, show.
• Les exécutions SOP sont lancées par un fan-in d’événements en direct (webhook authentifié, MQTT, système de fichiers ou AMQP), par le tick périodique de maintenance SOP du daemon pour les déclencheurs cron, ou par l’outil intégré à l’agent sop_execute. Les autres types de déclencheurs (périphérique et calendrier) sont définis et mis en correspondance, mais ne sont pas encore reliés à une source d’événements en direct (voir SOP Fan-In).
• La progression des tâches utilise les outils : sop_status, sop_approve, sop_advance.
• Par défaut, l’état d’exécution est local au processus. Avec sop.persist_runs = true, une initialisation réussie du backend SQLite par défaut le stocke sous <data_dir>/sop/runs.db et restaure les exécutions actives après un redémarrage. En cas d’échec de l’initialisation, un avertissement est consigné et le système bascule sur la mémoire locale au processus.
• Les journaux d’audit des SOP sont persistés dans le backend Memory configuré sous la catégorie sop.

L’état d’exécution et l’historique d’audit sont des surfaces distinctes. Consultez Cycle de vie des travaux en arrière-plan pour la gestion du cycle de vie, l’annulation et la sémantique du redémarrage.

Flux d’événements

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

Prise en main

1. Par défaut, sops_dir n’est pas défini ; le chargement des SOP à l’exécution est donc désactivé. Activez-le en définissant sops_dir via la passerelle, zerocode ou zeroclaw config set. Une valeur relative est résolue par rapport à la racine de l’installation (le répertoire contenant config.toml) ; ainsi, la valeur documentée shared/sops donne <install>/shared/sops, le même répertoire que celui dans lequel l’auteur de la SOP écrit. Une valeur absolue ou préfixée par ~- est utilisée telle quelle. Redéfinir sops_dir sur "" (ou le supprimer) désactive à nouveau le chargement des SOP à l’exécution ; la CLI utilise néanmoins <install>/shared/sops comme solution de repli pour l’inspection hors ligne.

   Vous migrez depuis une version antérieure ? Les valeurs relatives de sops_dir sont désormais résolues par rapport à la racine d’installation, comme les répertoires skill-bundles. Les versions antérieures utilisaient deux racines différentes pour le même paramètre ; vérifiez-les toutes les deux avant la mise à niveau :

   Faire apparaître dans les versions antérieures	Racine utilisée	Où sops_dir = "shared/sops" a atterri
   Chargement à l’exécution et CLI locale zeroclaw sop	data_dir	<data_dir>/shared/sops
   Rédaction de SOP Web et RPC	<install>/shared	<install>/shared/shared/sops (segment dupliqué)

   Les deux pointent désormais vers l’unique emplacement canonique <install>/shared/sops. Inspectez les deux anciens emplacements et déplacez toutes les définitions que vous y trouvez vers <install>/shared/sops ; les définitions laissées dans l’une ou l’autre arborescence deviennent invisibles après la mise à niveau. Les définitions créées via l’ancienne interface web ou RPC sont les plus faciles à manquer, car elles se trouvent dans le chemin d’écriture doublé plutôt qu’à l’emplacement décrit dans la documentation.

   Toute autre valeur relative est déplacée de la même manière : sops_dir = "my-sops" passe de <data_dir>/my-sops (à l’exécution et via la CLI) ou de <install>/shared/my-sops (pour la création via le web et RPC) à <install>/my-sops. Les valeurs absolues et celles préfixées par ~-restent inchangées.

   Le cas non défini évolue lui aussi : la solution de repli de la CLI hors ligne analysait auparavant <data_dir>/sops et analyse désormais <install>/shared/sops.

   zeroclaw sop list lit le nouvel emplacement, donc une liste vide après la mise à niveau signifie que les définitions se trouvent encore dans l’une des anciennes arborescences.

2. Créez un répertoire de procédures opérationnelles standard (SOP), par exemple :

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

3. Valider et inspecter les définitions :

   sh

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

4. Le déclencheur s’exécute via des sources d’événements configurées, ou manuellement depuis un tour d’agent avec sop_execute.

Pour les détails sur le routage des déclencheurs et l’authentification, consultez SOP Fan-In.