Cotal-AI/Cotal · 上手攻略
- 仓库：
Cotal-AI/Cotal - 链接：https://github.com/Cotal-AI/Cotal
- 分类：skill / 多 Agent 协议 / Agent 协调标准
- 作者：spark
- 更新：2026-09-24
⚠️ 本文基于仓库 README 与官网文档站（GitHub 已验 · 200 OK · 抓取于 2026-09-23）撰写，未 clone 源码、未跑通 quickstart。版本、命令均按 README 声明，未独立交叉验证。
1. 这是什么
Cotal-AI/Cotal 是给 AI Agent 用的开放 pub/sub 标准，口号 "The open pub/sub standard for AI agents"。它的核心抽象是：
- Space（共享空间）：一个 mesh 里所有 agent 共享同一片存在空间，每个 agent 都能看到「谁在、状态如何」
- Topology-free：谁管谁、谁是 worker、谁是 manager，都是配置而不是协议强加——同一份标准能跑扁平 peer 群、manager + worker 树、命令链、或任意混合
- 三种寻址（multicast / unicast / anycast）+ presence：pub/sub 的全部工具箱
底层传输是 NATS + JetStream（生产验证多年的消息基础设施）；参考实现是 TypeScript。协议本身与语言无关——任何带 NATS 客户端的语言都可以实现。
⚠️ 立标候选位：skill / 多 Agent 协议（主）+ Agent 协调标准 / MCP 互补层（副）。
2. 解决什么问题
主流 agent 协作工具被两类硬约束困住：
- 树状结构锁定：一个 controller 发活儿，worker 永远互不见面 → 没有横向协调。
- 一对一裸消息：没有共享空间，agent 间发现 / 状态同步全靠上层硬塞。
Cotal 把「结构」从协议层提到配置层。同一个 mesh 既能跑 flat team of peers、manager + workers、chain of command、也能混着来。配套还有：
- 多 space 并行：一台机器上同时跑多个 mesh（
cotal meshes列出，cotal use <space>切换，每条命令都接受--space <name>）。一个客户端项目、一个研究团队跑在同一个 broker 上但完全互不可见。 - 跨机器 mesh：broker 可以跑在你 internet 可达的服务器上，笔记本、工作站、云容器加入同一个 space。
- 与 MCP / A2A 互补而非取代：
- MCP = 工具连接
- A2A = 两个 agent 的点对点 request/response
- Cotal = 多个 agent 的实时 pub/sub（presence、channel、durable delivery、三种寻址统一模型）
- 数据形状复用 A2A：identity 用 A2A 的
AgentCard（role是 anycast 寻址的 service），wire message 复用 A2AMessage/Part。不复用 A2A 的 HTTP/JSON-RPC transport、Task RPC、request/response server model——只复用形状。
3. 快速安装
3.1 macOS / Linux（主路径 · curl 安装脚本）
curl -fsSL https://get.cotal.ai | sh
⚠️ 这个脚本安装到 home 目录，不需 sudo，然后跑引导式 setup。先在 https://get.cotal.ai 看一遍源码，或用 | sh -s -- --dry-run 预览。
3.2 Windows / Node 22+
如果已有 Node 22+：
npm install -g cotal-ai
cotal setup
3.3 让 agent 帮你装
把 https://docs.cotal.ai/prompt.md 指给 coding agent。
3.4 最小运行（quickstart）
cotal up --detach # 启动 mesh（后台）
cotal spawn # 把你的 agent 放上去，开始聊（Ctrl-C 退出）
cotal web # 在浏览器里看
cotal down # 停掉一切
⚠️ 默认 cotal up 是 JWT 鉴权（sender authenticity + per-agent ACL + server-side delivery daemon 的 durable delivery）。cotal up --open 是 loopback-only、live-only、不鉴权 的松散模式，仅适合本地实验。
3.5 引导式三人 demo
cotal setup --demo # 加 david (engineer) / sven (guide) / me（你驾驶）
cotal spawn david
cotal console # 在终端里实时看
3.6 一键团队
可以用一个 cotal.yaml manifest 描述整个团队；agent 可以跑在 cmux / tmux / Orca 终端里，或者换成 Codex / OpenCode / Hermes 跑。安装 flag、依赖、卸载见 docs/getting-started.md。
4. 核心用法
4.1 三种寻址 + presence
| 寻址 | 用途 | 例子 |
|---|---|---|
| Multicast（广播到 channel） | #general / #review → 所有订阅者收到 |
群组同步 |
| Unicast（点对点单播） | 发到具体 instance，对端忙时消息在 durable inbox 里等 | 给 bob 发私信 |
| Anycast（按角色找任一） | 发给「reviewer」服务，恰好一个空闲 reviewer 接 | 委派 / 负载均衡，不用点名 |
所有寻址之下都跑 presence：每个 agent 发布实时状态（idle / waiting / working / offline）+ A2A AgentCard。任何在 space 里的 agent 都能读 roster，看到谁在干啥——这是没有中心调度器还能横向协调的根。
4.2 Coding Agent 当 manager
cotal up 自带一个 manager endpoint，你自己的 agent 可以按需拉队友：
用 coding agent 时：
cotal up起一个 manager，agent 通过cotal_spawn按需拉队友。例：「给我拉一个 reviewer」→ manager 在 mesh 上 spawn。详见docs/connect-claude.md。
4.3 已支持的 Agent（connector）
| Agent | 接入方式 |
|---|---|
| Claude Code | installed plugin + hooks |
| OpenCode | native in-process plugin |
| Codex | app-server + 它自己的 TUI |
| Hermes | gateway daemon + plugin |
| Jcode | Harness API + 它自己的 TUI |
| pi | pi extension + live steer |
⚠️ 它们接入方式不同但暴露同一套 cotal_* 工具，且全部 push——peer 消息到达时立刻唤醒空闲 agent。Codex 和 pi 还会「live turn」：用 steer() 把到达消息折进正在进行的那一轮。想加新 connector？去 discussion #80 投票。
4.4 Web Dashboard（cotal web）
在浏览器里开一个「god-view」面板：
- Graph view：整个 mesh 画成一幅 live force-directed 星图，channel membership 是边、消息流过时边会发光
- Monitor & channels：roster（状态用形状+颜色表示）、每个 channel 的消息列表、golden-signal tiles（working / waiting / idle / offline / oldest-unattended）
- Agent detail：点任一节点下钻——role、harness / model、live status、当前活动、tags
⚠️ 只读 + 最小权限：dashboard 自签发窄权限 cred 然后丢弃签名 seed。终端版 cotal console 看同一个 space。
4.5 复用 A2A 数据形状
Cotal 不用 A2A 的 HTTP/JSON-RPC transport、Task RPC、request/response server model——只复用 形状（AgentCard / Message / Part）。底层是 NATS + JetStream（生产验证多年的部分，Cotal 不重造轮子）。
5. 典型适用场景
- 多 agent 横向协调：一个 coding agent 拉一个 reviewer，reviewer 在 mesh 上被 anycast 唤醒；不需要中心 orchestrator 死板派发。
- 多项目隔离：同一台机器跑多个 mesh（client 项目 + research 团队），互不可见。
- 跨机器 mesh：笔记本 + 工作站 + 云容器进同一个 space；broker 跑在 internet 可达服务器。
- Coding agent 即 manager：agent 本身能拉队友（reviewer / tester / debugger），按需 spawn。
- 多人可视化监控：浏览器 dashboard 看整个团队的工作分布、NEEDS-YOU 队列、idle / waiting / working tiles。
不适用：
- 只要 1 个 agent（overhead 大材小用）
- 要 HTTP/JSON-RPC 兼容 A2A 全套（Cotal 只复用形状，不复用 transport）
- 要非 NATS 消息基础设施（协议强绑 NATS，参见 FAQ）
6. 坑与注意
- 官方实现只有 TypeScript（FAQ 自陈）：其他语言的 client 是 planned。如果你的主力栈是 Python / Rust / Go，目前只能等或自己写。
- NATS 是协议层强约束：Cotal 是 NATS 上面的 contract（subjects + schemas + presence / ack-on-surface / sender authenticity 等 client 行为）。换底层不现实。
cotal up默认 JWT 鉴权：peer 接入需要配 cred；本地实验要用--open，但那是 live-only、loopback-only。- curl 安装脚本依赖网络：被网络隔离的环境要先在能上网的机器审
get.cotal.ai脚本。 - dashboard 是只读：要做控制还是要走 CLI 或 connector。
- 码群 demo 演示性强、生产参考弱：仓库自带的 examples（01 lateral coordination / 02 swarm 重建 console / 04 Frontier Tower faces）偏 demo；要在生产场景用，需要自己结合
cotal.yamlmanifest 做配置治理。 - A2A 兼容是单向 + 形状级：你用 A2A 的工具人想接入 Cotal，需要写 connector；Cotal 反向不会变回 A2A transport。
- agent impersonation 由 NATS 拦截：sender 跟 NATS subject 绑定，server 用 agent JWT 校验，伪造 sender 直接拒。DM 用 bind-only durable per-identity inbox，agent 不能 re-target。
7. 与同类对比
| 维度 | Cotal | A2A | MCP | LangGraph / CrewAI / AutoGen |
|---|---|---|---|---|
| 层 | 多 agent pub/sub | 两 agent request/response | agent ↔ 工具 | 应用层 agent 编排框架 |
| 结构 | topology-free 配置 | 一对一 | 不涉及 | 通常强结构（graph / crew） |
| 基础设施 | NATS + JetStream | HTTP/JSON-RPC | JSON-RPC | 进程内 / 自带状态 |
| 跨机器 | ✅ mesh | 弱（HTTP） | 弱（stdio/HTTP） | ❌ 进程内 |
| presence | ✅ | ❌ | ❌ | ❌ |
| durable delivery | ✅（JetStream） | ❌ | ❌ | 看实现 |
| anycast（角色负载均衡） | ✅ | ❌ | ❌ | 自己造 |
⚠️ Cotal 的定位是「在 MCP 和 A2A 之上补多 agent live 协调」，不是要取代它们。如果你只是要工具调用，去 MCP；只要 1-to-1，去 A2A；要做横向 pub/sub + presence + durable delivery，Cotal。
8. 一句话推荐结论
要做「多 agent 真·横向协作 + 跨机器 mesh + presence」时，Cotal 是目前少有的开源标准选择；前提是接受 NATS 强依赖 + TypeScript-only 官方实现。