工作示例：StageX 自动更新机器人
stagehand 是一个生产环境的 ZeroClaw 机器人。它会监听上游发布源，更新 StageX 软件包，进行构建，通过摘要验证其可复现性，推送变更，创建一个草稿拉取请求，并公布结果。在 PR 创建之前，全程无需人工干预。
这是参考的 SOP 部署方式：流水线是一个确定性的 SOP，发布源通过 AMQP 通道到达，代理使用 sop_execute 工具触发 SOP。AMQP 也可以直接驱动 SOP 引擎，作为实时的 fan-in；此示例有意采用代理触发模式，其中通道将每个发布项提升到代理循环中，由代理启动运行。正是这种分离使该模式具有可复用性。
以下每个命令、配置键、工具名称、状态值和审计键都对应代码库中的一个具体定义。
1. 构建
stagehand 需要编译进 AMQP 和 Matrix 通道。两者均通过 feature 进行门控，且默认关闭。
sh
cargo build --release --features channel-amqp,channel-matrix
该结果是一个 zeroclaw 二进制文件，它会加载 amqp 和 matrix 通道类型。未启用 channel-amqp 构建的二进制文件会在启动时拒绝 amqp 通道块，并记录一条警告而不是加载它。
2. 制品
ZeroClaw 安装根目录下有三项内容：
| 工件 | 位置 | 角色 |
|---|---|---|
| ZeroClaw 配置 | ~/.zeroclaw/ | 代理、AMQP + Matrix 通道以及 sop 设置。 |
sops/stagex-update/ | <install>/shared/sops/stagex-update/ | 流水线：SOP.toml（元数据）+ SOP.md（八个步骤）。 |
skills/stagex-update/ | <install>/shared/skills/stagex-update/ | 将 SOP 绑定到发布事件触发的纽带。 |
该配置将代理连接到两个通道（amqp.anitya、matrix.announce），以完全自主模式运行，使其在无需关卡的情况下提交、推送并发起 PR，并在 deterministic 执行模式下将 [sop] 指向 shared/sops。代理从不执行合并；由维护者接管该分支并通过签名提交完成合并。
AMQP 通道
amqp.anitya 通道消费 Fedora Messaging 的公共订阅源。它在 amq.topic 交换机上绑定 Anitya 版本更新路由键，并通过 amqps:// 使用客户端双向 TLS 进行连接；Fedora 的代理要求提供客户端证书，因此该通道会出示所配置的 client_cert 和 client_key。该通道在加载时会校验其配置：amqp_url 必须使用 amqp:// 或 amqps://，amqps:// URL 需要 ca_cert，client_cert 和 client_key 必须同时提供，交换机不能为空，且至少要绑定一个路由键。
每次投递的 JSON 主体都会通过 content_template 映射为 agent 的入站消息，其中的 {dotted.path} 占位符会根据主体内容进行解析，从而将一次发布投递转换为 “New release: bzip2 1.0.9 (was 1.0.8). Bump the StageX package for bzip2.”。thread_id_field 点分路径将回复关联回原始事件。默认情况下投递为至少一次（durable_ack = true）：通道只有在发布被持久化交付给 agent 循环之后才会进行确认，因此在运行开始前发生崩溃会重新投递该事件，而不会悄无声息地丢弃它。对于一个无人值守且具有副作用的流水线来说，这一点至关重要；丢失一次发布会导致某个软件包被悄然遗漏。凭据和证书在部署时提供，且绝不提交到代码库：Codeberg 推送令牌是 agent 的 shell 读取的环境变量，Matrix 访问令牌设置在运行实例上，而 Fedora CA 和客户端证书则放置在主机上。
3. 验证
zeroclaw sop 接口包含三个子命令。没有 run 子命令；运行通过触发器或 sop_execute 工具启动。
sh
zeroclaw sop list
zeroclaw sop validate stagex-update
zeroclaw sop show stagex-update
验证会针对以下情况显示警告：名称或描述为空、没有触发器、没有步骤（缺少或为空的 SOP.md），以及步骤编号存在缺口。缺少步骤的警告意味着运行将在执行时失败。在迭代时，可通过 zerocode 终端界面执行相同的检查；CLI 是可复现的部署时检查。
4. 部署
该机器人作为长期运行的守护进程运行，因此它会保持与 broker 和 Matrix 房间的连接。
sh
zeroclaw daemon
在常驻主机上，它作为受管服务运行，会随机器一起重启（参见 Service & daemon）：
sh
zeroclaw service install
zeroclaw service start
AMQP 通道连接到 broker，绑定其路由键并消费投递的消息。在上游发布新版本之前，该 bot 会保持空闲状态。
5. 发布流程贯穿其中
Anitya 发布一条版本更新推送。AMQP 通道接收该推送，应用 content_template，并将一条入站消息交给代理，消息中标明软件包、新版本和旧版本。代理随即触发流水线：
// 工具：sop_execute
// 参数：{ "name": "stagex-update", "payload": "{\"project\":{\"name\":\"bzip2\"},\"version\":\"1.0.9\",\"old_version\":\"1.0.8\"}" }
sop_execute 使用手动触发器启动一个 SopRun，并将 payload 转发到运行上下文中。从此处开始的生命周期与其他任何运行完全相同；唯一不同的是触发器来源。
6. 运行
由于 [sop] 以 deterministic 模式运行，各步骤依次执行，彼此之间没有 LLM 往返调用。每一步的输出会管道传递给下一步，只有补丁获取步骤会调用模型，而该模型在本地运行，因此软件包源代码绝不会离开主机。检查点步骤会暂停以等待人工批准；本流水线则会一路执行直至生成 PR 草稿。
running → completed
从 SOP 的 ## Steps 部分解析出的八个步骤：
| # | 步骤 | 它的作用 | 工具 |
|---|---|---|---|
| 1 | 解析 | 将上游项目映射到真实的 StageX 包；读取当前版本；如果不是严格更新的版本则停止。 | shell、file_read |
| 2 | 版本升级 + 哈希 | 设置新版本，运行 make fetch，写入正确的源哈希值，重新获取直到无误。 | shell、file_write |
| 3 | 构建 | 仅构建此软件包；哈希校验失败时重试一次。 | shell |
| 4 | 修补损坏内容 | 构建中断时，使用本地模型刷新或修复补丁；标记真正的 API 中断。 | shell、file_read、file_write、http_request |
| 5 | 摘要复现 | make digests，再次构建，确认摘要未发生变化。 | shell |
| 6 | 提交 + 推送 | 在按包、按版本的分支上提交；推送到该 fork。 | shell、git_operations |
| 7 | 打开草稿 PR | 填写 PR 模板，附上摘要信息，仅在干净且可复现的构建通过后才标记为就绪。 | http_request |
| 8 | 发布 | 将结果发布到 Matrix 房间：软件包、版本差异、复现状态、摘要、PR URL。 | shell |
智能体在每个步骤结束时通过 sop_advance 调用报告结果：
// 工具: sop_advance
// 参数: { "run_id": "<run-id>", "status": "completed", "output": "Bumped bzip2 1.0.8 → 1.0.9; source hash re-derived and verified." }
status 为 completed、failed 或 skipped 之一。当最后一个步骤完成时，运行将转换为 completed 状态，并设置其 completed_at 时间戳。
进度在 agent 回合的任意时刻都可见：
// tool: sop_status
// args: { "sop_name": "stagex-update", "include_metrics": true }
无头安全
当交付到达时，如果没有活动的智能体循环来驱动这些步骤，运行时会记录该运行并记录每个待处理的操作，而不是默默丢弃工作。该运行会等待智能体回合来推动其继续执行。
7. 审计跟踪
SopAuditLogger 会将每次转换都持久化到配置的 Memory 后端中 sop 类别下。一次更新运行会留下这些键：
| 键 | 目录 |
|---|---|
sop_run_<run-id> | 完整运行快照，在开始时写入并在完成时更新。 |
sop_step_<run-id>_1 … _8 | 单个步骤的执行结果：状态、输出、时间戳。 |
sop_approval_<run-id>_<step> | 操作员审批记录，当检查点步骤需要审批时使用。 |
sop_timeout_approve_<run-id>_<step> | 检查点审批超时时的超时自动批准记录。 |
在 sop_status 上设置 include_metrics: true 会添加 SOP 专属的聚合数据；include_gate_status: true 会添加信任阶段和门控评估器状态。这些数据通过 sop_status 提供，而非 Prometheus。当可观测性后端为 prometheus 时，/metrics 端点仅暴露通用的 zeroclaw_* 系列指标。
8. 保证
每项保证都可追溯至该流水线：
- 源代码绝不离开主机。 补丁获取步骤针对本地模型运行，因此软件包源代码永远不会到达远程提供方。
- 构建过程会自我验证。 第 5 步会构建两次并比较摘要；只有当两者匹配时，PR 才会被标记为就绪。
- 由人来完成合并。 机器人在“草稿 PR 已打开”这一步停止；由维护者接手该分支，并通过签名提交进行合并。它绝不会自动合并。
- 此运行可重建。 运行快照和每个步骤结果都以运行 ID 为键，持久化存储在
sop类别下。
9. 模式
入站通道接收一个事件，代理通过 sop_execute 触发 SOP，确定性流水线完成实际工作。将 AMQP 馈送替换为任意通道，将步骤替换为任意流程，其生命周期、审批关卡和审计键都保持一致。当某个步骤需要人工判断时，将其标记为检查点，运行会暂停以等待审批后再继续；与无人值守路径的唯一区别在于由谁来推进这次运行。