Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

SOP の実行方法

ランタイム契約

  • SOP 定義は、<shared>/sops/<sop_name>/SOP.toml と任意の SOP.md から読み込まれます。
  • CLI zeroclaw sop でオフラインの定義を管理します: list、validate、show、graph、rename、delete。
  • SOP の実行は、ライブイベントのファンイン（認証済みWebhook、MQTT、ファイルシステム、または AMQP）によって、cron トリガー用のデーモンの定期的なSOPメンテナンスタックによって、またはエージェント内ツール sop_execute によって開始されます。残りのトリガータイプ（peripheral と calendar）は定義・照合されますが、ライブイベントソースにはまだ接続されていません（SOPファンインを参照）。
  • 実行の進行は、ツールsop_status、sop_approve、sop_advanceを使用します。
  • 実行状態は、デフォルトではプロセスローカルです。sop.persist_runs = true を指定すると、デフォルトの SQLite バックエンドの初期化に成功した場合、実行状態が <data_dir>/sop/runs.db に保存され、再起動後にアクティブな実行が復元されます。初期化に失敗した場合は警告がログに記録され、プロセスローカルメモリにフォールバックします。
  • SOP監査レコードは、設定されたメモリバックエンドのカテゴリsop下に永続化されます。

実行状態と監査履歴は独立したサーフェスです。ライフサイクルの所有権、キャンセル、および再起動のセマンティクスについては、Background work lifecycle を参照してください。

イベントフロー

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 は、SOP 作成者が書き込むのと同じディレクトリである <install>/shared/sops になります。絶対値または ~-プレフィックス付きの値はそのまま使用されます。"" に戻す（または削除する）と、実行時の SOP の読み込みは再び無効になります。CLI はオフライン検査のために引き続き <install>/shared/sops にフォールバックします。

    以前のビルドから移行しますか？ 相対 sops_dir 値は、skill-bundles ディレクトリと同じ方法で、インストールルートを基準に解決されるようになりました。以前のビルドでは、同じ設定に対して 2 つ の異なるルートが存在していたため、アップグレードする前に両方を確認してください:

    以前のビルドで表面化するRoot はそれを使用しましたsops_dir = "shared/sops" の配置先
    ランタイムでの読み込みとローカルの zeroclaw sop CLIdata_dir<data_dir>/shared/sops
    Web および RPC SOP の作成<install>/shared<install>/shared/shared/sops（重複したセグメント）

    現在はどちらも、単一の正規の <install>/shared/sops に解決されます。両方の古い場所を調べ、見つかった定義を <install>/shared/sops に移動してください。いずれかのツリーに残された定義は、アップグレード後に見えなくなります。古い Web または RPC サーフェス経由で作成された定義は、ドキュメントで説明されていた場所ではなく、二重化された writer パスに置かれているため、最も見落としやすいものです。

    その他の相対値も同様に移動します。sops_dir = "my-sops" は、ランタイムおよび CLI では <data_dir>/my-sops から、Web および RPC での作成では <install>/shared/my-sops から、<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の名前を変更する

SOPの名前はそのアドレスです。定義は <sops>/<name>/ に置かれ、どの作成インターフェースも、SOPを渡された名前のまま保存します。編集したSOPを別の名前で保存すると、2つ目のコピーが書き込まれ、元のSOPが残ってしまいます。そのため、編集保存では名前の変更を一律に拒否します。名前の変更は独立した操作として行います。

sh

zeroclaw sop rename deploy-prod deploy-production

デーモンは、同じ操作を sops/rename RPC メソッドとして公開しており、{"from": "...", "to": "..."} を受け取ります。また、{"to": "..."} ボディを伴う POST /api/sops/{name}/rename としても公開されています。変更先の名前が既に使われている場合は競合（409、RPC コード -32020）として返され、変更元の SOP が存在しない場合は未検出（404、RPC コード -32021）として返されます。

名前の変更:

  • 移動先の名前がすでに使用されている場合は拒否されるため、2つのSOPを統合することは決してできません;
  • 単一のパスコンポーネントではない対象を拒否します。他の名前を受け取るすべての SOP 操作に適用されるものと同じチェックです；
  • SOPルート直下にある実在するディレクトリではないソースは拒否します。そこにあるシンボリックリンクは名前チェックを通過したうえで、すべての読み取りと書き込みをリンク先に向けてしまいます。そのため、リンクをたどらずに名前を確認し、何かを読み取る前に、ソースがルート内に解決されることを確認します;
  • re-runs strict save validation、そのため、オーサリング画面が書き込みを拒否していたはずの定義をディスクに書き戻すことはできません;
  • この変更は、SOP.toml の [sop] name の値のみを変更し、その行自体のコメントと空白は維持します。手順、トリガー、その他のコメント、および SOP.md は元のまま残ります。唯一の見た目の変更として、シングルクォートで囲まれた名前はダブルクォートに戻されます。

ディレクトリの移動は単一のファイルシステム上のリネームであり、最後に実行されます。そのため、SOP はどの時点でも必ずちょうど1か所にのみ存在します。リネームが中断されても、複製が2つ残ったり、まったく残らなかったりすることはありません。マニフェストの書き換えと移動の間でリネームが中断された場合、SOP は古いディレクトリに残ったままですが、マニフェストにはすでに新しい名前が記録されているため、zeroclaw sop list は新しい名前を表示します。同じリネームを再実行すると、処理が完了します。

リネームは、1つの定義を保存または削除する場合と同様に、ディスク上の定義を書き換えます。すでに古い定義を読み込んでいるデーモンは、SOPを再読み込みするまで古い定義で動作し続けます。また、実行履歴、監査レコード、その他旧名を記録しているものは、旧名のまま保持されます。

書き込み操作は直列化されています。作成、保存、削除、名前変更のいずれも、何かに触れる前に SOP のルートにある .sop-authoring.lock ファイルに対してアドバイザリロックを取得します。そのため、プロセスをまたいでも 2 つの書き込み操作が互いに干渉することはありません。実行中のデーモンが同じルートに対して作成を行っている場合、CLI による書き込みは競合する代わりに順番を待ちます。10 秒以内にロックを取得できなかった作成操作は、無期限にキューに入るのではなく失敗します。読み取りは直列化されません。作成操作が書き込む各ファイルは、アトミックなリネームによって置き換えられるため、読み取り側が切り詰められた、または書き込みが途中のファイルを見ることはありません。保存では SOP.toml と SOP.md の 2 つのファイルを順に書き込むため、保存中に実行された読み取りは、短時間ではあるもののマニフェストとステップが異なるリビジョンのものである状態を見る可能性があります。また、新しい SOP の最初の保存と競合する読み取りは、ステップがまだ存在しない状態のマニフェストを見る可能性があります。保存後の次の読み取りでは、両方のファイルが新しいリビジョンの状態で返されます。

各ステップは rename によって確定するため、通常の読み取り側にも、強制終了されたプロセスにも、ステップが中途半端な状態で見えることはありません。renamed されたエントリを保持するディレクトリは、その後に flush されるため、Unix では machine crash が起きた場合でも順序保証が維持されます。rename が完了した後にこの flush が失敗した場合でも、操作は完了し、その失敗はログに記録されます。変更は完了して可視化されており、失われるのはそのエントリ 1 件分のクラッシュ保証だけです。macOS では、flush は順序保証のために尊重されますが、デバイスキャッシュを強制的に排出することはありません。Windows にはディレクトリ同期のためのプリミティブが存在しないため、これらのプラットフォームでは保証の最後のステップはファイルシステムに委ねられ、ZeroClaw が強制できるものではありません。

トリガーのルーティングと認証の詳細については、SOP Fan-Inを参照してください。