Agent Orchestrator 云沙箱编排实战：ao spawn / list / send / report / kill 五命令详解与源码解析

Agent Orchestrator 云沙箱编排实战ao spawn / list / send / report / kill 五命令详解与源码解析【免费下载链接】agent-orchestratorRun and supervise teams of coding agents from planning to merge. Any harness (Claude code, codex, 25 more). Desktop, web, mobile, and cloud agents.项目地址: https://gitcode.com/gh_mirrors/ag/agent-orchestrator本篇技术指南以 Agent Orchestrator 开源仓库中随云 Worker 内置的 using-ao skill 文档cloud/internal/skillassets/using-ao/commands/orchestration.md为骨架系统讲解云沙箱内aoCLI 的五个核心编排命令spawn、list、send、report、kill。你将掌握它们各自的参数语义、权限模型worker:orchestrate/worker:report、常见错误处理以及控制面源码层面的实现依据从而能够在 AO Cloud 中像管理一支编码 Agent 团队一样安全、高效地调度 worker。一、云沙箱里的ao面向控制面的瘦客户端在 AO Cloud 的沙箱中ao是一套比桌面版更小、职责更单一的 CLI。桌面版ao拥有的ao session、ao project、ao status、ao preview、ao browser在这里统统不存在云沙箱版只保留编排相关的命令完整命令表以ao help输出的权威清单为准。据 SKILL.md 的目录命令作用谁可以运行详情spawn在独立新沙箱中创建 worker 会话仅 orchestratorcommands/orchestration.mdlist别名ls、status列出本 orchestrator 派生的 worker含分支、状态与 PR 事实仅 orchestrator同上send向 worker 会话注入消息仅 orchestrator同上kill别名delete、rm终止 worker 会话并销毁其沙箱仅 orchestrator同上report向派生本会话的 orchestrator 发送消息具有 orchestrator 父级的 worker同上claim-pr把既有 PR 挂接到本会话任意会话commands/pull-requests.md这份 skill 随ao-worker二进制启动时被嵌入安装到dataDir/skills/using-ao见 skillassets.go 的Install逻辑每次 Worker 启动都会用二进制内嵌副本覆盖磁盘副本因此文档与二进制版本永不漂移。1.1 凭证与权限worker:orchestrate与worker:report五个命令全部通过本会话的轮换 worker 凭证与 AO 控制面通信。凭证与 scope 的颁发逻辑在 worker_handlers.go 的issuedWorkerScopes中体现得十分清晰只有Kind orchestrator的会话才保留worker:orchestratescope只有ParentSessionID ! 即被 orchestrator 派生的会话才保留worker:reportscope心跳续期只会重新签发已授予的 claims所以一旦被剥离该 worker 整个生命周期都无法再获得对应权限。控制面在 HTTP 层强制校验requireOrchestratorScope检查worker:orchestrate缺失时返回403 SCOPE_REQUIREDreportToParent检查worker:report同样返回SCOPE_REQUIRED见 worker_orchestration_handlers.go。因此spawn/list/send/kill只对 orchestrator 会话开放report只对有 orchestrator 父级的 worker 开放权限不足的命令一律以SCOPE_REQUIRED失败。1.2 会话间隔离约定每个会话都运行在独立隔离的沙箱中。不要尝试直接访问其他会话的沙箱无 ssh、无共享文件系统ao上述命令是会话之间的唯一通道。此外spawn与send在服务端是幂等的命令打印出成功行即代表已被持久化接受即使效果尚未可见。二、ao spawn — 创建 worker 会话ao spawn --name label --prompt clear worker task [--agent claude-code] [--mode standard|trusted]2.1 参数详解参数必填说明--name是人类在侧边栏看到的标签。保持简短、具体理想 ≤ 20 字符硬上限 80 字符。运行前先数好长度——过长的标签会浪费一个回合在拒绝上--prompt是worker 的完整任务。像给一位无上下文的资深工程师写 brief目标、约束、预期产出通常是一个 PR。在提到具体文件/类/路径前先确认它在已检出的仓库里存在ls、find、grep--agent/--harness否claude-code默认、codex或cursor--agent是--harness的别名--mode否trusted默认或standard从 CLI 实现看ao-cloud-agent/main.go--harness与--agent绑定到同一变量--mode只接受standard或trusted否则直接报错此外还支持隐藏参数--sandbox-provider-connection显式指定沙箱 provider 连接。2.2 harness 的解析优先级服务端规则不要以为传了--agent就万事大吉控制面处理程序createWorkerChildworker_orchestration_handlers.go会优先读取父项目配置的 worker agentconfig.worker.agent并强制覆盖请求中的 harness——这是为了防止 Codex 等 Agent 在派生子代时自报 harness 而覆盖项目选型。只有当项目未配置 worker agent 时才回退到请求值最后兜底claude-code。换言之CLI 侧空默认值让控制面填充与服务端项目配置优先是配套设计的。2.3 输出与启动行为成功后打印spawned session-id (status)。worker 会自行申请沙箱、在全新分支上检出项目仓库并开始执行 prompt通常约 10 秒内就绪。你无需等待在它就绪前发出的send会被排队并在 worker 启动时送达。2.4 常见错误agent_provider_required该组织没有为该 harness 验证过的凭据。换一个--agent或把这个阻碍上报给人类。SANDBOX_QUOTA_EXCEEDED组织达到了沙箱配额上限。先 kill 掉已完成任务的 worker 再重试。配额常量与错误路径见 server.go 与 transport.go。值得一提子 worker 的沙箱 provider 会继承 orchestrator 的 providerNodeOps orchestrator 派生 NodeOps workerCoder 派生 Coder而不是控制面默认值见orchestratorProviderStore及其注释worker_orchestration_handlers.go。三、ao list — 查看你的 workerao list [--json] [--all]列出本 orchestrator 派生的 workerid、名称、harness、分支、状态、worker 运行时是否已连接runtimeConnected以及 PR 存在后的编号与 CI 状态。已终止的 worker 默认隐藏用--all查看历史。CLI 实现ao-cloud-agent/main.go以制表符对齐输出表头ID / NAME / HARNESS / BRANCH / STATUS / CONNECTED / PRPR 列格式形如#12 ci:failingpullRequestSummary多个 PR 时追加(N)无 PR 显示-。--json输出机器可读的完整结构包含每 PR 明细字段字段说明prs[].url/numberPR 地址与编号prs[].state/ci/reviewPR 状态、CI 状态、review 状态prs[].mergeability可合并性prs[].sourceBranch/targetBranch源/目标分支activityState活动状态isTerminated是否已终止runtimeConnectedworker 运行时是否已上线底层接口GET /worker/children支持游标分页CLI 端listChildren按每页 100 条翻页直到翻完或达到 5 页500 条兜底ao-cloud-agent/main.go控制面侧listWorkerChildren通过includeTerminatedtrue参数控制是否包含已终止会话worker_orchestration_handlers.go。状态词汇表working、idle、needs_input、pr_open、draft、ci_failed、review_pending、changes_requested、approved、mergeable、merged、exited、terminated。其中activityState来源于各 harness 的活动事件推导如 Claude 的agent_needs_input对应ActivityWaitingInputstop对应ActivityIdle见 activity.go 的deriveClaudeActivity。四、ao send — 向 worker 发消息ao send session-id message... ao send --session session-id --message message消息会像人类亲手输入一样注入 worker 的对话流用于传达 CI 失败、review 反馈、澄清问题与方向纠偏。两种语法等价位置参数或显式 flag--session/--message缺省时自动从位置参数取ao-cloud-agent/main.go。消息是持久排队的仍在 provisioning 的 worker 会在其 Agent 启动后收到。服务端sendWorkerChildMessage校验sessionId必须是 UUID、消息文本长度在 1 到 65536 字节之间并携带幂等键写入会话事件worker_orchestration_handlers.go。CLI 成功打印message queued (delivered when the child agent is ready)。五、ao report — 向 orchestrator 汇报仅 workerao report message...把消息发送给派生本会话的 orchestrator。用途有二任务完成时说明交付了什么 PR 编号或阻塞在只有 orchestrator/人类能拍板的决策上时。保持在一两句话内结果 PR 编号或唯一的阻塞原因。绝不粘贴 diff、日志或文件内容——冗长的报告在 orchestrator 的对话里读起来像一条被注入的 prompt消息会以本会话 id 为前缀出现。权限方面非 orchestrator 派生的会话执行report会得到SCOPE_REQUIRED服务端reportToParent依赖worker:reportscope且 store 层会再次校验父级链接确保 worker 永远只能联系自己的 orchestratorworker_orchestration_handlers.go。CLI 成功后打印reported to orchestrator。六、ao kill — 终止 workerao kill session-id终止 worker 会话并销毁其沙箱。适合两类场景任务已完成PR 已合并或已交接或重定向尝试后仍永久卡死。kill走DELETE /worker/children/sessionId服务端把目标会话的desiredState置为deleted对应领域常量SandboxDesiredDeleted见 sandbox.go 与 worker_orchestration_handlers.go。终止不可逆分支与任何已打开的 PR 会保留在 GitHub 上但会话与沙箱无法恢复。CLI 打印session deletion requested表示删除已被接受。七、错误处理与实战约定SCOPE_REQUIRED命令所需 scope 缺失orchestrator 命令在非 orchestrator 会话上运行、report在无父级会话上运行。权限模型见 worker_handlers_test.go 的 scope 剥离用例。agent_provider_requiredspawn 时指定 harness 缺少已验证的组织凭据。SANDBOX_QUOTA_EXCEEDEDspawn 时组织沙箱配额耗尽先 kill 完成任务的 worker。幂等性CLI 对 spawn/send/report 类写操作自动生成Idempotency-Key头newIdempotencyKey见 ao-cloud-agent/main.go配合服务端idempotencyKey(r)保证重试安全——命令打印成功行即代表已被持久接受无需因响应延迟而重复执行。命名与 prompt 纪律--name先数长度再提交--prompt中引用的任何文件路径先用ls/find/grep验证存在避免浪费整个 worker。八、延伸阅读SKILL.md云沙箱ao命令总览、别名与通用约定--agent别名、UUID 会话 id、runtimeConnected判断 worker 是否在线。commands/pull-requests.mdworker 通过 unix socket helper$AO_PULL_REQUEST_HELP/$AO_REVIEW_HELP开 PR、ao claim-pr挂接既有 PR、提交approved/changes_requestedreview 裁决。cloud/cmd/ao-cloud-agent/main.go云aoCLI 的完整实现命令分发、参数解析、游标分页、幂等键、凭证读取。cloud/internal/httpapi/worker_orchestration_handlers.go控制面五个编排端点的 HTTP 实现与 scope 校验。cloud/internal/httpapi/worker_orchestration_handlers_test.go编排端点的行为测试覆盖 scope 拒绝、消息校验、父子消息路由等场景。【免费下载链接】agent-orchestratorRun and supervise teams of coding agents from planning to merge. Any harness (Claude code, codex, 25 more). Desktop, web, mobile, and cloud agents.项目地址: https://gitcode.com/gh_mirrors/ag/agent-orchestrator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考