puda-protocol

约束

**创建或更新协议文件后，必须立即调用 puda-memory 技能。**该技能会将 project.md 作为事实来源；它会追加新的协议链接和历史记录。

---

协议结构

单个协议可以包含面向多台机器的命令。每条命令都指定自己的 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：当实时命令目录中提供安全元数据时，此字段为必需；将结构化元数据原样复制到命令中。特殊命令不需要此字段

特殊命令

特殊命令由 CLI 在执行 puda protocol run 时处理。它们不会发送到机器，也不需要实时命令目录或 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（每台暂停的机器对应一条 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 Agent 必须将该原样输出展示给操作人员，并等待明确批准。不要先提交 yes，再询问是否批准。

• 仅当目录明确显示 confirm: true 时才提示。@safety 默认将 confirm 设为 false。

• 对于由 Agent 驱动的执行，启动 puda protocol run 时使用 terminal(background=true, pty=true, watch_patterns=["Type yes to continue step"])。出现提示时，检查进程输出，将完整命令和安全上下文展示给操作人员，并等待其明确批准。获得明确批准后，继续执行 process(action="submit", data="yes")。如果权限被拒绝，请提交任何非 yes 的值，或终止进程。同一步的并行命令会一并显示，并使用一次确认来涵盖该步骤中所有带安全标记的命令和机器。

命令生成

重要：如果不确定某项任务应使用哪台机器或哪条命令，请务必先询问用户或与用户确认，再继续操作。

重要：使用 puda machine list 查看每台在线机器公布的描述。参考可用的机器信息和以往的协议，了解有效的机器、命令和参数。需要命令签名、参数或安全元数据时，运行 puda machine commands <machine_id> 获取。特殊命令 wait 由 CLI 处理，不应在机器上查询。

重要：尽可能使用以往的协议文件，除非用户明确要求生成新文件。如果无需执行前三条说明，则跳过

说明

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（如有）。对于特殊命令 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 命令）。不要将 wait 命令发送给机器。
• 安全信息准确性：复制的安全元数据必须与实时目录完全一致。任何字段缺失或被更改，都必须在执行前重新生成命令条目。
• 确认：在操作员明确批准所显示的安全上下文之前，绝不要启动 confirm: true 命令或步骤组。
• 创建文件后务必验证；发送前修复所有错误。
• 写入文件后，务必调用 puda-memory 更新 project.md。