puda-protocol

制約

プロトコルファイルを作成または更新したら、直ちに puda-memory スキルを呼び出す必要があります。 このスキルは project.md を信頼できる唯一の情報源として維持し、新しいプロトコルへのリンクと履歴エントリを追記します。

---

プロトコルの構造

1 つのプロトコルには、複数のマシン向けのコマンドを含められます。各コマンドでは、独自の machine_id を指定します。ステップ番号は、すべてのコマンドを通じて順番に実行されるグループを表します。コマンドを並列実行する場合は、同じ step_number を指定します。ただし、同じ並列コマンドグループ内で machine_id を重複させることはできません。

トップレベルのフィールド：

• project_id：プロジェクトルートにある project.md の UUID
• protocol_id：プロトコルごとに新しい UUID（例：python -c "import uuid; print(uuid.uuid4())"）
• description：このプロトコルが行う処理の簡潔な説明
• timestamp：ISO 8601 形式の UTC 時刻（例：datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")）
• commands：コマンドオブジェクトの配列（以下を参照）

各コマンド：

• step_number：1 から始まる連番。同じ値のコマンドは並列実行されます
• name：指定したマシンで有効なコマンド名、または特殊コマンド（wait）
• machine_id：対象のマシン ID。wait の場合は省略するとプロトコル全体を一時停止し、指定すると同じステップのほかのマシンを実行しながら、そのマシンだけを一時停止します
• params：コマンドに必須のパラメーターと任意のパラメーター
• safety：ライブコマンドカタログに安全性メタデータが表示される場合に必須です。構造化メタデータを変更せずコマンドにコピーします。特殊コマンドでは省略します

特殊コマンド

特殊コマンドは puda protocol run の実行中に CLI が処理します。マシンには送信されず、ライブコマンドカタログや safety も必要ありません。

wait

CLI のみで実行する遅延です。params.seconds は必須です（>= 0、小数も可。0.5 は 500ms）。wait をマシンに送信してはいけません。

{"step_number": 2, "name": "wait", "machine_id": "first", "params": {"seconds": 5}}

すべてのマシンを一時停止するには、machine_id を省略し、専用のステップを割り当てます。一部のマシンだけを一時停止するには、machine_id を指定し（停止するマシンごとに 1 つの wait を指定し、作業を続けるマシンと同じ step_number にします）、それらのマシンだけを一時停止します。そのステップでは、一時停止中のマシンに別のコマンドを割り当ててはいけません。

コマンドの安全性

puda machine commands <machine_id> の後に表示される safety: ブロックは、必須の計画・実行コンテキストとして扱います。コマンドに安全性メタデータが表示される場合は、それを protocol.json 内の該当コマンドにコピーします。安全性フィールドを創作、要約、弱体化、または省略してはいけません。ライブカタログを信頼できる唯一の情報源とし、プロトコルを更新するたびにコピーしたメタデータを更新してください。

標準的なコマンドの形式：

{
  "step_number": 1,
  "machine_id": "machine-001",
  "name": "move_to",
  "params": {
    "x": 1,
    "y": 1,
    "z": 1
  },
  "safety": {
    "summary": "Confirm the workspace is clear before moving.",
    "hazards": [
      "collision"
    ],
    "requires": "Machine must just have been homed and the workspace clear.",
    "forbidden_when": "Do not move if the workspace is occupied, human movement is detected",
    "confirm": true
  }
}

安全性フィールドの型は固定です。

• summary：文字列

• hazards：文字列の配列

• requires：文字列

• forbidden_when：文字列

• confirm：ブール値

• safety: ブロックの requires は文章として指示に従ってください。先行するステップを追加するか、コマンドを使用する前にユーザーに確認してください。

• forbidden_when は文章として指示に従ってください。その状況に該当する場合は、コマンドを使用してはいけません。

• confirm が true の場合、puda protocol run は現在のステップのコマンド全体と安全性オブジェクトを表示し、yes が入力されるまで停止します。AI エージェントはその出力を正確にオペレーターに提示し、明示的な承認を待つ必要があります。先に yes を送信してから確認を求めてはいけません。

• カタログに confirm: true と明示されている場合にのみ確認を求めてください。@safety では confirm の既定値は false です。

• エージェント主導で実行する場合は、terminal(background=true, pty=true, watch_patterns=["Type yes to continue step"]) を指定して puda protocol run を開始します。プロンプトが表示されたら、プロセスの出力を確認し、コマンド全体と安全性のコンテキストをオペレーターに提示して、返答を待ちます。明示的な承認を得た後、process(action="submit", data="yes") で続行します。許可されなかった場合は、yes 以外の値を送信するか、プロセスを終了します。同じステップの並列コマンドはまとめて表示され、そのステップ内の安全性タグ付きコマンドとマシンすべてに対して、確認は 1 回だけ行われます。

コマンドの生成

重要：特定のタスクで使用するマシンやコマンドが不明な場合は、先に進む前に必ずユーザーに確認してください。

重要：puda machine list を使用して、オンラインの各マシンが公開している説明を確認してください。有効なマシン、コマンド、パラメーターを把握するには、利用可能なマシン参照と過去のプロトコルを確認してください。シグネチャ、パラメーター、安全性メタデータが必要な場合は、puda machine commands <machine_id> を取得してください。特別なコマンド wait は CLI で処理されるため、マシン上で検索してはいけません。

重要：ユーザーが新しいファイルの生成を明示的に希望している場合を除き、可能な限り過去のプロトコルファイルを活用してください。不要であれば、最初の 3 つの手順は省略してください。

手順

1. ユーザーのログインを確認する：ユーザーが puda cli で認証済みか確認します。未認証の場合は、先にログインするよう依頼してください。
2. プロジェクトの存在を確認する：まだプロジェクトがない場合は、続行する前にプロジェクト名と説明をユーザーに尋ねてから、puda init を使用してプロジェクトフォルダーを作成します。
3. プロトコル ID とタイムスタンプ：UUID と ISO 形式の日時を生成します（例：Python の uuid.uuid4() と datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")）。
4. マシン参照と安全性：puda machine list を使用して、各マシンが公開している説明を確認します。マシンと利用可能なコマンドを把握するには、利用可能なマシン参照と過去のプロトコルを確認してください。使用するマシンコマンドごとに、最新のコマンド定義を取得します。wait などの特別なコマンドはカタログ検索を省略してください。適切なマシンまたはコマンドが不明な場合は、先に進む前にユーザーに確認してください。公開されているすべての安全性オブジェクトを各コマンドにコピーしてください。
5. 生成：プロジェクトの protocols/ ディレクトリに新しい JSON ファイルを作成します。ファイル名は <protocol_id>.json とします。
6. 検証：puda protocol validate -f <file_name> を実行します。成功時の出力は正確に passed でなければなりません。それ以外の場合は、返されたすべてのエラーを修正して、再度検証します。
7. ビジョン検証：該当するマシン用の puda-vision-validation スキルを使用します。
8. プロジェクトメモリーを更新する：ファイルの作成または更新直後に、必ず puda-memory スキルを呼び出して project.md を更新します。
9. 確認ゲートを設けて実行する：プロトコルを対話形式で実行します。Type yes to continue step ... が表示されるたびに、表示されたコマンドと安全性情報を完全な形でオペレーターに伝えてください。明示的な承認を得てから yes を送信してください。承認がない場合は、実行を拒否するか終了します。

出力形式（JSON）

{
  "project_id": "<project_id>",
  "protocol_id": "<protocol_id>",
  "description": "description for this protocol",
  "timestamp": "<ISO 8601>",
  "commands": []
}

各コマンドには、step_number、name、machine_id、params を指定します。最新のコマンドカタログで safety が公開されている場合は、safety も指定してください。特別なコマンド wait の場合は、params.seconds を設定します。すべてのマシンを一時停止するには machine_id を省略します。同じステップで他のマシンを動作させたまま、特定のマシンだけを一時停止するには machine_id を指定します。

トラブルシューティング

• プロトコルファイルの送信時に RUN_ID_MISMATCH が発生した場合は、puda machine reset <machine_id> を実行してマシンをリセットし、その後プロトコルを再送信します。

ベストプラクティス

• 複数マシンの場合：各コマンドに正しい machine_id を指定します。同じ step_number は並列実行するコマンドにのみ使用し、同じステップ内で machine_id を重複させないでください。
• 遅延：特別なコマンド wait を使用し、params.seconds を設定します。プロトコル全体を一時停止するには machine_id を省略します。並列ステップの一部のマシンだけを一時停止するには、machine_id を指定します（マシンごとに wait を 1 つ指定）。wait をマシンに送信してはいけません。
• 安全性情報の忠実性：コピーした安全性メタデータは、最新のカタログと完全に一致している必要があります。フィールドが欠落または変更されている場合は、実行前にコマンドエントリーを再生成してください。
• 確認：オペレーターが表示された安全性コンテキストを明示的に承認するまで、confirm: true のコマンドまたはステップグループを開始してはいけません。
• 作成後は必ず検証してください。エラーがあれば、送信前に修正してください。
• ファイルの書き込み後は、必ず puda-memory を呼び出して project.md を更新してください。