CLI Agent Orchestrator:从双角色协作到可恢复工作流

📌 适用场景:准备环境 → 安装角色 → 启动服务 → 编写流程 → 人工批准运行 → 检查结果 → 停止与复用

本地cao-server与tmux协调多个编码CLI,复用原生认证与工具,支持MCP、Web UI和保存型Python工作流;包含人工批准、运行标识与受约束的恢复。

8.3 /10 ★★★★☆
🪜 7 个步骤 🛠️ 0 款工具 ⏱️ 首次配置建议预留 1–2 小时,取决于 provider 认证与环境准备,非实测耗时 🎯 进阶 🕒 更新于 2026-11-16

📋 完整步骤

  1. 1

    准备测试环境与 provider

    核对 Python、tmux、uv 和已认证的编码 CLI,隔离测试目录与凭据

  2. 2

    安装 CAO 和角色

    使用官方 uv tool 命令并安装 supervisor、developer 与 reviewer

  3. 3

    启动本地控制面

    保持 cao-server 运行,从测试仓启动 supervisor 并查看 Web UI

  4. 4

    编写双步骤工作流

    用 run_step 串联便笺生成与只读审查,通过 create 校验登记

  5. 5

    经人工批准运行

    预先指定 run-id,按当前审批设置让使用者核对并批准计划

  6. 6

    检查结果与恢复边界

    核对两步真实输出、状态与日志,必要时取消或恢复而非盲目重跑

  7. 7

    停止会话并受控复用

    关闭指定会话,之后再考虑 inputs 参数化和 schedule 定时执行

这是什么?适合谁?

CLI Agent Orchestrator(CAO)由 awslabs/cli-agent-orchestrator 开源维护。 它运行本地 cao-server,把不同编码 CLI 放进独立 tmux 终端,再由 supervisor 协调工作者。 核心协作模式包括 Handoff、Assign 和 Send Message,同时提供 MCP、Web UI、计划任务与持久化工作流。 它不是新的基础模型,也不会赠送各 provider 的账号、模型额度或生产权限。 适合人群:已有编码 CLI,希望把开发、审查和结果汇总拆成可观察角色的开发者。 适合任务:限定范围的代码分析、文档生成、先产出后审查的流水线,以及需要恢复记录的多步骤任务。 不适合人群:不愿维护本地进程和凭据,或误以为多个终端就自动拥有文件系统安全沙箱的人。 官方首页与仓库列出的 provider 信息更新不同步,本文不承诺一个固定支持总数。 核验日期:2026-11-16。 本文基于官方文档和公开资料整理,AI辅助生成,MagicNetWorld 尚未完成独立实测。

前置准备与平台边界

官方 README 要求 Python 3.11+、tmux 3.3+、uv,以及至少一个预先完成认证的受支持 provider CLI。 先在隔离测试目录中练习,不把生产密钥、部署权限和唯一未提交代码交给初次编排。 本文的安装和多终端示例面向能够运行 tmux 的 shell 环境。 Windows 用户需先落实能运行 tmux 和 provider 的兼容环境,例如自行验证过的 WSL;不承诺原生 Windows 终端直接兼容。 默认启动使用 Kiro CLI;如果只安装了 Claude Code,必须按其 provider 文档显式选择。 tmux 窗口隔离的是会话和输入输出,不自动隔离共享目录、网络与系统凭据。 为每个角色写清读写范围、完成条件、允许工具和停止条件。 多工作者同时写同一文件会产生冲突,先串行跑通再考虑并发。

第一步:安装 CAO 与基础角色

本次官方 README 的 main 安装命令为:

uv tool install git+https://github.com/awslabs/cli-agent-orchestrator.git@main --upgrade
cao --help

main 会移动;团队复用时应记录实际安装来源和版本,正式采用前比较变更。 官方也给出 PyPI 标签版本入口与 devcontainer 文档,但不要混用多个安装来源后猜测更新行为。 安装本流程需要的基础角色:

cao install code_supervisor
cao install developer
cao install reviewer

先阅读角色内容,再确认工具授权;安装角色不等于批准其任意执行。 本站未执行这些安装命令,也未改动任何用户的客户端配置。

第二步:启动本地服务与 supervisor

终端 A 保持服务运行:

cao-server

终端 B 进入自己的测试仓库,启动 Claude Code supervisor 的官方 provider 组合:

cd /path/to/your/test-project
cao launch --agents code_supervisor --provider claude_code

/path/to/your/test-project 要替换为实际目录,不是一个可直接使用的固定路径。 若选择默认 Kiro,可按 README 省略 provider;不要在未装 Kiro 时照抄默认路径。 用浏览器查看本地 Web UI:http://localhost:9889。 先观察 supervisor 是否真正进入可交互状态,而不是只看到服务进程存在。 向 supervisor 给一个只读任务,要求列出测试目录顶层结构,不提交修改。 确认真实终端输出和角色状态之后,再进入保存型 workflow。

第三步:编写最小双步骤流程

官方推荐 Python script tier;YAML 的 parallel、pipeline、loop 模式当前保留但不可执行。 不要因为 YAML 校验显示 pass_reserved 就宣称并行流程已经运行。 创建一个普通草稿文件 hello.py,使用官方 workflow 文档示例:

from cao_workflow import run_step, emit_output

note = run_step(
    "claude_code", "developer",
    "Write a one-line hello note. Return it only."
)
review = run_step(
    "claude_code", "reviewer",
    f"Critique this note in one line: {note.output}"
)
emit_output({"note": note.output, "review": review.output})

这段由 CAO 的 workflow 运行环境提供 shim,不是建议单独 python hello.py。 不要导入服务内部包 cli_agent_orchestrator,官方校验明确阻止这种跨边界依赖。 草稿可以位于你自己的测试目录,不应手工写进 CAO 的受管 workflows 目录。 通过受控入口校验并登记:

cao workflow create hello --from-file ./hello.py

保存返回的 content_hash,后续 update 需要它来避免覆盖他人的修改。

第四步:由使用者批准并运行首个任务

先公布固定运行标识,再由使用者决定执行:

cao workflow run hello --run-id hello-1

官方 quick start 展示了开启计划审批后返回 403 approval_required 与 plan_id 的情况。 遇到该拒绝应停止,由人核对计划、权限、输入和费用,不让工作者自己批准自己。 使用者在自己的终端输入实际返回的完整标识:

cao workflow approve plan-v1:<digest-from-the-refusal>
cao workflow run hello --run-id hello-1

尖括号部分是待替换值,不能原样执行,也不能猜一个 digest。 审批行为受当前 workflow.require_approval 设置影响;应先核对安装版本的配置,不把文档示例当所有环境默认值。 即使配置没有强制拒绝,自动化执行者仍应遵守“用户先批准每次运行”的工作流规则。

第五步:核对成功判据与清理

查看状态:

cao workflow status hello-1

成功判据:运行完成,结果包含真实 note 与 review,后者确实针对前一步的文本,而不是两个独立回答。 同时核对开发与审查步骤的 provider、角色与终端状态,没有遗留等待用户的阻塞。 失败时先读具体错误,不将“服务 HTTP 可访问”当“任务完成”。 需要中止时使用:

cao workflow cancel hello-1

只有理解日志、输入和恢复策略后,才考虑 cao workflow resume hello-1。 恢复会重执行脚本并重放已记录结果;它不代表任意外部副作用都能安全重做。 结束后用真实会话名停止:

cao shutdown --session <session-name>

不要为关闭本次测试习惯性使用 --all,否则会停止其他仍需要的 CAO 会话。

初级用法

串行开发与审查:先让 developer 产出一个小结果,再让 reviewer 只读检查,最后由人决定是否接受。 只读仓库导览:限定文件范围和输出字段,不让导览角色顺带安装依赖或改格式。 任务交接:Handoff 适合等待专门结果,Assign 适合可独立推进的任务,消息用于补充上下文;按实际完成条件选模式。 人工追踪:从 Web UI 与 tmux 观察状态,区分 processing、等待确认和完成,不以沉默判断成功。

高级玩法

1. 用 inputs 参数化保存型流程

官方 Python tier 支持模块级 INPUTS 与 get_inputs(),可以声明 string、int、bool、path。 把目标文件和输出条数变成参数,比每次改脚本常量更利于复用。 输入验证、计划身份和恢复日志存在关联,改变输入后不要复用旧批准当万能授权。 需要示例时先读workflows 文档的 Parameterized workflows。

2. 用 schedule 触发稳定流程

当前命令为 cao schedule,旧 cao flow 只是弃用别名。 先手动跑通再定时,新增计划不等于完成运行批准或获得生产修改权限。 服务必须保持运行;用 cao schedule list 核对状态,用 disable/remove 控制停用。 不要把每次自动唤醒都变成自动写生产系统,先采用只读或 dry-run 任务。

3. 将多 provider 协作与权限分开设计

CAO 可以混用不同 provider,但各自认证、工具名和限制执行方式并不相同。 先核对 role、allowedTools 与委派上限,再考虑工作者间分工。 Claude Code 的 provider 文档说明默认可能绕过原生权限提示,敏感任务应先评估 permissionMode。 “本地编排”不等于模型请求都留在本地,也不等于各 provider 都提供同等硬隔离。

4. 用恢复日志而不是重复启动排障

固定 run-id,先查询 status,再决定 cancel 或 resume。 不要在模块顶层用当前时间、随机数或 UUID 生成恢复关键标识,避免重放分歧。 对会产生外部副作用的步骤先设计幂等与恢复策略;日志不能替你撤销已经发出的请求。

小技巧

  1. 首轮只跑 note → review,确认协作链后再让智能体写真实项目。
  2. 始终显式选择自己已安装并认证的 provider,别误用默认 Kiro。
  3. 记录 create 的 content_hash,更新草稿时先比较当前版本。
  4. 将运行标识写进任务说明,方便定位、取消和核对结果。
  5. 多工作者写不同路径;同文件修改采用串行合并。
  6. 不要为快速通过信任提示添加 --yolo,先核对实际工具授权。
  7. Web UI 截图和 tmux 日志可能含密钥或源码,分享前脱敏。
  8. 安装更新后先复跑最小流程,再恢复定时任务。

踩坑记录

踩坑 1:只安装 Claude Code,默认启动却找 Kiro。 症状:supervisor 无法启动。原因:未限定 provider 的命令默认使用 Kiro。 解决:按照实际客户端指定 --provider claude_code,先在 CAO 外确认认证有效。来源:README、Claude Code provider。

踩坑 2:YAML 并行模式校验通过但没有执行。 症状:出现 pass_reserved,却无预期多步骤运行。原因:这些控制流仍属于保留模式。 解决:使用 Python tier 编写真正分支或并发,别删门槛伪装成功。来源:workflows。

踩坑 3:运行返回 approval_required。 症状:收到 403 和计划标识。原因:当前运行需要人工计划批准。 解决:把实际 plan_id 交给使用者核对批准,不让智能体自批,也不关闭审批来消错。来源:Plan approval。

踩坑 4:服务可见但定时流程不再运行。 症状:计划没有新的执行记录。原因可能是服务未持续运行、计划停用或执行仍在等待授权。 解决:核对 cao-server、schedule list 和具体运行状态,再看日志,不盲目重复添加计划。来源:flows。

踩坑 5:恢复出现 ReplayDivergenceError。 症状:恢复与原始执行不一致。原因可能是模块顶层时钟或随机状态改变了关键值。 解决:用输入派生标识,核对 journal 与恢复策略,不直接重放有副作用的步骤。来源:workflows。

踩坑 6:误以为独立 tmux 就无法碰生产文件。 症状:工作者仍能访问同机目录。原因:终端隔离不是 OS 沙箱,工具权限也因 provider 而异。 解决:用隔离测试目录、最小凭据与限制角色,并核对 provider 的实际强制措施。来源:安全政策、tool restrictions。

常见问题 FAQ

Q1:是否必须使用 AWS 云资源?

A:README 的基础路径是本地 server 与 tmux,不要求先部署 AWS;可选云部署与模型 provider 自己仍有资源和认证要求。

Q2:可以把现有模型订阅拿来用吗?

A:provider CLI 保持自己的原生认证,具体能否使用订阅以及限额由相应供应商决定,不由 CAO 赠送或统一结算。

Q3:它与直接写一个 Python 多 Agent 库有何不同?

A:CAO 保留完整 CLI 进程、tmux 交互和原生工具,Python workflow 是协调层;不是要求把每个 CLI 重写成 SDK 调用。

Q4:角色提示词是不是安全隔离?

A:不是。必须看实际工具授权、provider 强制方式与主机权限;提示词和角色名本身不足以阻止越权。

Q5:所有新插件界面都默认能用吗?

A:不是。当前 README 明确 Agent Plugins 一组入口默认门控,可能返回 404;首次任务无需开启它们,不要将门控误诊为全部服务失败。

Q6:本站实际跑过这个流程吗?

A:没有。本站未安装 CAO、启动 server、认证 provider 或运行模型步骤,成功判据是读者执行后的检查目标,不是本站运行报告。

具体子模块学习路径

先读 docs/agent-profile.md,理解 role、provider、allowedTools 与委派边界。 再用 code_supervisor、developer、reviewer 完成最小串行协作。 随后读 docs/workflows.md 的 create、inputs、approval 与 resume,掌握保存型流程生命周期。 只有人工运行稳定后才读 docs/flows.md 的 cao schedule;多客户端操作再看 Web UI 和 control planes。 最后回到 docs/tool-restrictions.md 与 SECURITY.md,逐 provider 检查限制是否真正强制。

权限、安全、成本与平台限制

本地服务默认面向 localhost;对外暴露必须补齐认证、TLS 和网络访问控制,不能直接把控制面公开。 智能体可以通过工具读写文件、执行命令和访问网络,避免给予不必要的主机或云账户权限。 审查来源不明的 profiles;不要把密钥放进共享提示、仓库、终端截图或日志。 安全政策明确不建议生产使用 yolo;Claude provider 的权限模式必须按部署实际核对。 成本由模型订阅或 API、并发任务、主机资源和外部工具共同决定,开源不等于零费用。 恢复、定时和多 Agent 叠加后尤其需要总体预算、截止时间与人工停止机制。 本站未独立验证安装、恢复、权限隔离、输出质量、并发性能与实际账单。

参考链接

📊 评分与标签

核验口径:已按现行口径通过,待按新证据契约复核 · 证据状态:仅公开资料 · 核验日期:

评分说明

总分 8.3/10 · P_优选 核验日期:2026-11-16。评分依据可追溯至 awslabs 官方仓库、文档站、workflows、flows、角色、provider、安全与权限文档,不从初评分换算。 MagicNetWorld 未安装 CAO、启动 tmux/server、配置认证、运行 workflow 或测试恢复与权限强制,因此证据等级为 doc-only。

可观测社区指标

采集日期:2026-11-16。GitHub API 记录 ★1,561、forks 323、pushed_at 2026-11-15T22:24:15Z,创建于 2025-07-29,未归档,默认 main,Apache-2.0。 来源:仓库 API。fork 与 star 关系不能直接说明真实部署规模,本站未统计贡献者、发布质量或问题响应。 文档站与 README 在 provider 列表和宣传总数上不同步,本文只列有专项文档的示例,不发布固定总数。

🔄 流程完整性 2.5/3.0

README 覆盖依赖、uv 安装、角色、server、supervisor、Web UI 与停止;workflows 进一步给出 Python author/create、校验、批准、run-id、状态、取消与恢复,形成从启动到收尾的完整链路。

  • 竞品对比 1(CrewAI):CrewAI 以 Python Crews/Flows 构建角色协作与事件控制;CAO 保留完整编码 CLI 进程与终端,适合已有 CLI 工具链,但初始化与终端状态处理更复杂。
  • 竞品对比 2(LangGraph):LangGraph 面向长期有状态 agent 图与持久执行;CAO 在 CLI 会话之上提供工作流与 journal,复用终端生态而不是替代低层图框架。
  • 扣分点:YAML parallel/pipeline/loop 当前保留不可执行,审批默认行为须核对配置;多终端与外部副作用并不因 journal 自动变成安全恢复。来源:workflows。

🔁 可复用性 2.1/2.5

保存型 Python workflow 可声明 INPUTS、运行时 get_inputs、使用固定 run-id,并通过 create/update 的内容哈希维护版本;schedule 可定时触发既定流程。

  • 竞品对比 1(CrewAI):CrewAI 的角色、任务和事件流程同样可复用;CAO 的优势在复用现有 CLI 的认证与能力,代价是 provider 升级可能影响终端行为。
  • 竞品对比 2(LangGraph):LangGraph 有长期状态和中断恢复抽象;CAO 的 journal 与 resume 服务于脚本重执行和终端步骤,使用者必须理解其确定性与副作用限制。
  • 扣分点:模块顶层时钟/随机值可能导致重放分歧,输入与计划身份变化会影响批准;跨主机迁移和真实恢复未由本站验证。来源:workflows、flows。

📚 文档清晰度 1.7/2.0

README 给出最短可执行路径,provider 文档解释状态、认证和权限,workflows 展示 shim、create 和审批,SECURITY 直接说明主机、工具与凭据边界。

  • 竞品对比 1(CrewAI):CrewAI 文档围绕 Crews/Flows 与 Python 工程;CAO 将本地终端、角色安装与多控制面操作讲得具体,但用户需跨多份文档建立完整理解。
  • 竞品对比 2(LangGraph):LangGraph 提供持久化、人介入和部署的专题文档;CAO 则解释 CLI 状态解析、provider 权限与调度等实际运维细节,两者关注层次不同。
  • 扣分点:首页 provider 宣传与仓库列表不一致,flow 命令已改名 schedule,插件入口还有默认门控;旧指南易误导,需以对应 main 文档逐项核对。来源:官网、README、flows。

🧩 工具集成 1.2/1.5

支持多种 provider CLI、MCP、Web UI、shell 与 Python workflow;角色有 allowedTools 与委派上限,集成面不局限于某一种模型 SDK。

  • 竞品对比 1(CrewAI):CrewAI 以 agent/tool/LLM 组合业务自动化;CAO 更方便保留现成 CLI 的原生工具,却也继承各 CLI 的权限与环境差异。
  • 竞品对比 2(LangGraph):LangGraph 可独立使用并对接 LangChain/LangSmith 生态;CAO 用 MCP 和本地终端作控制桥梁,不是将全部图框架工具直接兼容导入。
  • 扣分点:provider 对硬限制的实施不同,Claude Code 默认可能绕过原生提示;集成列表存在不等于各组合都已验证。来源:tool restrictions、Claude Code provider。

💡 创新性 0.8/1.0

用完整 CLI 进程、tmux、跨 provider 协作、MCP 控制和保存型脚本工作流连接已有编码工具,是清晰的工程组合;无需先把客户端能力重写成统一 SDK。

  • 竞品对比 1(CrewAI):角色协作和事件流程本身并非新概念;CAO 的增量在终端原生协作与复用现有客户端,而非宣称首创多 Agent。
  • 竞品对比 2(LangGraph):长期状态、人工介入和恢复已有框架支持;CAO 将其落到 CLI 操作层,与图式编程互补,不能据此推断恢复更可靠。
  • 扣分点:属于整合创新,缺少独立同任务基准证明其成本或任务成功率优势。来源:README、workflows。

维度求和核对

2.5 + 2.1 + 1.7 + 1.2 + 0.8 = 8.3 = 总分 ✓ 🏷️ 标签说明

  • 多智能体编排:supervisor 通过 handoff、assign、消息协调工作者。来源:官网。
  • CLI:每个 agent 仍是完整编码 CLI 进程,由 tmux 管理终端。来源:README。
  • MCP:内建 MCP 将编排能力暴露给兼容客户端。来源:官网。
  • 持久化工作流:保存型 Python pipeline 使用 journal 支持中断后恢复,受确定性约束。来源:workflows。
  • 开源自托管:Apache-2.0,本地 server/tmux 基础路径可自运维。来源:README。 📋 来源核实
  • 已核实:GitHub API的关注指标、pushed_at、许可和归档状态;原始响应与采集时刻已保留。
  • 已核实:README的 Python 3.11+、tmux 3.3+、uv、默认 Kiro 与安装;Claude Code provider的 provider 选项和 permissionMode。
  • 已核实:workflows的 Python 推荐路径、YAML 保留控制流、create/approval/resume;flows的 schedule 改名及持续运行前提。
  • 已核实:SECURITY与 tool restrictions明确本地控制面和 provider 强制差异;竞品来源为 CrewAI README与 LangGraph README。 局限:未实测部署、初始化、跨 provider 协作、恢复、审批、工具阻断或账单;终端隔离不等于 OS 安全沙箱,本地编排不等于模型数据不出机。Apache-2.0 不豁免模型供应商或外部工具的条款与费用。