COTAL actions (cotal.ai)

什么是 Cotal

Cotal 让 AI Agent 和软件服务在共享空间中协同工作，跨越不同的应用和设备。Agent 可以发现同伴、向频道发送消息、寻求审查者的帮助，或调用服务。由你决定谁委派任务给谁。

可将它用于同伴团队、带有工作 Agent 的主管模式，或包含人工检查点的工作流。Agent 可以从笔记本电脑、工作站或远程主机加入。不同的空间会隔离项目及其权限。

这项开放标准定义了身份、消息传递、在线状态和端点控制。TypeScript 实现运行于 NATS + JetStream，并包含 CLI、应用连接器、进程管理器、持久化工作流和观测工具。阅读概述。

快速入门

curl -fsSL https://get.cotal.ai | sh

安装程序会在无需 sudo 的情况下写入你的主目录，并启动引导式设置。你可以先阅读脚本，也可以通过 | sh -s -- --dry-run 预览。

在 Windows 上，或已有 Node 22+ 安装时：

npm install -g cotal-ai
cotal setup

设置过程会准备一个空间、配置你选择的应用，并创建一个 default 人格。它会单独询问是否启动。若只想进行准备，请使用 cotal setup --configure-only。如果稍后再启动，请在项目文件夹中运行：

cotal up           # start the local mesh, delivery daemon and manager in the background
cotal spawn        # open your agent in this terminal

在另一个终端中，运行 cotal console 可查看团队及其消息。按 Ctrl-P 打开命令面板并启动另一个 Agent。你也可以直接运行 cotal spawn --detach 来启动 Agent。请任意一个 Agent 向同伴介绍自己。

cotal down 会停止本地堆栈。快速入门指南介绍了要求、非交互式设置和故障排除。想让编码 Agent 帮你完成设置？将 https://docs.cotal.ai/prompt.md 提供给它。

CLI 默认会发送使用情况遥测。运行 cotal telemetry off 可将其关闭。查看发送的内容。

选择工作方式

您想要	从这里开始
在本地或另一台计算机上运行 Agent	启动模式和管理器选择
连接个人 Claude Code 会话	现有会话连接与审批
加入托管空间	登录并选择空间
声明团队及其频道权限	团队清单
协调需要等待、分支或恢复的工作	Cotal Lang 工作流
连接服务或自动化 Cotal	API 参考

个人会话连接需要已登录的空间，并使用受支持的审批流程。 审批会说明权限和活动共享情况。对于本地静态身份验证空间或开放空间， 请改用 cotal spawn 启动。

支持的 Agent

Claude Code 插件 + 原生钩子

OpenCode 进程内插件

Codex app-server + TUI

Hermes 网关 + 插件

Jcode Harness API + TUI

pi 原生扩展

连接器通过各应用自身的机制提供网状工具并传递对等消息。Codex、Jcode 和 pi 支持在实时轮次中发送定向消息； 个人原生 Claude Code 会话则会在受支持的忙碌间隙收到消息。 各应用对恢复、事件和工具共享的支持有所不同。 连接器对照表列出了具体信息和成熟度级别。

托管 Agent 可在 PTY 或受支持的终端运行时中运行： tmux、cmux、Orca 或 Herdr。有关安装和可用性，请参阅运行时。

您可以通过编写连接器接入其他应用，也可以 为下一个应用投票。

工作原理

每个参与者都有身份，并会报告自己的在线状态。消息有三种投递目标：

• 多播会将消息发送给频道（例如 #review）的订阅者。
• 单播会将消息直接发送给一个对等参与者。
• 任播会将消息发送给某个角色（例如 reviewer），由一个可用实例接手工作。

在经过身份验证的网状网络中，持久后备机制会根据配置的保留期限和生命周期限制，为忙碌或离线的 Agent 保留消息。在线状态会告知对等参与者有哪些成员；注意力模式则让 Agent 控制哪些频道流量可以打断自己。心跳报告的是存活状态，而非任务正在取得进展的证明。

管理器负责启动和停止进程，不会介入 Agent 之间的消息，也不会替它们选择工作。在授权允许的情况下，Agent 可以通过 cotal_spawn 请求队友。清单可预先组建团队；Cotal Lang 会协调团队执行。

架构 · 投递 · 频道权限

工作流运行

Cotal Lang 是 JavaScript 的一个小型子集，用于通过步骤日志协调工作。程序可以启动 Agent、等待回复，并暂停以等待人员介入。受支持的主机可以根据记录的进度恢复中断的运行。

例如，在管理器上定义了 planner 和 builder 人设后：

const planner = await spawn("planner")
const builder = await spawn("builder")

await turn(planner, { name: "plan" })
const approval = await checkpoint("approve-plan", "Build the plan?", { timeout: "4h" })
if (approval.value === "yes") {
  await turn(builder, { name: "build", deadline: "30m" })
}

将程序保存为 build.cotal.js，并在经过身份验证且具有运行权限的网状网络上启动：

cotal run start --file build.cotal.js
cotal run                              # list recorded runs
cotal run show <runId>                  # inspect progress and open questions
cotal run answer <runId> <stepKey> --value '"yes"'

运行时还支持并发分支、带键的提交和经过身份验证的协作取消。取消记录不能证明每个外部进程都已停止。有关恢复方式和主机限制，请参阅工作流运行；有关完整约定，请参阅语言参考。

服务与集成

服务会发布命令约定，供经过授权的调用方发现和调用。管理器和 Linear 等集成都使用相同的端点接口。如果连接器和授权允许，Agent 可使用 cotal_describe 和 cotal_invoke；脚本则可使用 CLI 的端点命令和结构化输出。

Linear 适配器可通过静态身份验证网状网络，或通过经批准的用户身份验证服务注册，连接上游账户。托管部署仍需配置其授权、端点绑定和调用方授权。安装适配器不会自动授予账户访问权限，也不会让服务在所有空间中都可用。

如需构建自己的集成，请从 TypeScript 库、Agent 工具和 HTTP 参考中选择。

查看团队

cotal console 提供交互式终端视图，用于查看对等节点、频道和消息。 它的命令面板可启动 Agent，并执行已授权的操作员操作。 cotal watch 会持续输出观测信息；who、ps 和 status 等命令可回答有关对等节点、受管理 Agent 和本地计算机的特定问题。

浏览器仪表板是单独配置的只读服务。它使用专门为已注册的静态身份验证空间设置的受保护凭据，并且只显示该凭据有权读取的内容。它不会自行签发访问权限。启动前，请先按照仪表板设置进行配置。

身份与访问

默认情况下，cotal up 会进行身份验证。代理会检查每条消息主题中的发送者身份，并强制执行各 Agent 的权限。不同空间使用单独的 NATS 账户。采用用户身份验证的部署会让用户登录，并根据其当前授权签发访问权限。

代理、操作员和管理员凭据均受信任。私信受到保护，不会被未经授权的对等节点读取，但不会针对这些受信任方进行端到端加密。cotal up --open 是一种仅限本地回环、仅在运行期间有效且无需身份验证的模式，适用于本地实验。阅读安全模型。

个人会话活动共享、网状网络权限和 CLI 遥测是彼此独立的设置。共享对话活动前，请先查看连接授权；有关 CLI 使用情况报告，请参阅遥测。

示例

无需安装任何内容，即可尝试浏览器演示。其中的四个脚本化场景涵盖混合 Agent 团队、交付模式、拓扑变更，以及在另一台机器上恢复的工作流。

	横向协作 同一空间中各司其职的同级 Agent：在线状态、三种寻址模式、实时状态、优雅离开和后加入，每个 Agent 都在各自的终端中运行。 原始协议 · 纯终端
Agent 群组重建 Cotal 控制台 四个 Claude Code Agent 在同一个网格中协作，同时由编排器在 cmux 标签页中启动工作 Agent。他们构建了一个 Ink/React 控制台，用于查看团队情况。 四个编码 Agent · cmux 标签页
	Frontier Tower Faces 十个嘉宾角色化身为动画像素风格的 OpenCode Agent：每个 Agent 都会思考、对口型呈现流式回复，并控制自己的 32×32 表情；在网格中，它们作为同一空间里的同级 Agent 协作。 十个 OpenCode 形象 · OpenCode · tmux 墙 + 浏览器

所有示例，包括各自的设置说明和限制。

文档

文档位于 docs.cotal.ai。页面也提供面向 Agent 的 Markdown 版本，已安装的连接器还会提供带版本号的 cotal_docs 套件。

• 选择工作流：本地团队、托管空间、个人会话和集成。
• CLI 参考：按任务分组的命令，以及标志和输出约定。
• API 参考：库、端点命令、Agent 工具和 HTTP。
• 规范：规范性的线缆协议约定。
• 升级：针对各软件包的迁移步骤。

常见问题

Cotal 与 MCP 和 A2A 有什么关系？

MCP 将应用连接到工具。A2A 使用自己的请求/响应和任务模型定义 Agent 通信。Cotal 提供共享的发布/订阅空间，支持在线状态、频道、持久化投递和基于角色的寻址。它复用 A2A 的 AgentCard 和 Message/Part 结构，但使用 NATS 绑定，而不是 A2A 的 HTTP 传输方式。复用这些结构并不意味着 Cotal 是 A2A 传输桥接器。

Cotal 只能使用 TypeScript 吗？

TypeScript 是参考实现。该标准是一份线路协议契约，因此其他语言也可以使用 NATS 客户端实现，只要满足所需的身份、投递和在线状态行为。构建客户端介绍了实现顺序。

Agent 可以运行在不同的机器上吗？

可以。它们通过可访问的代理连接到同一空间。笔记本电脑、工作站和远程主机可以一起参与。远程启动需要经过授权的管理器；主机控制哪些 Agent 和服务可以在其上运行。请参阅远程监管。

浏览器仪表板就是托管版 Cotal 产品吗？

此仓库中的仪表板是一个使用静态凭据配置的只读观察器。托管版 Cotal 有自己的部署和账户流程。某个库或适配器提供支持，并不意味着所有托管部署都已启用该功能。

赞助方与合作伙伴

构建 Web-A，即 Agent 的网络。我们是其中的一员，并认同这一愿景。	旧金山前沿技术中心。
为托管版 Cotal 背后的沙箱提供支持。	Cotal 是 Cloudflare® for Startups 计划的一员。

我们正在寻找更多构建多 Agent 系统的设计合作伙伴。 联系我们。

欢迎贡献：使用你的语言实现该契约、构建连接器，或提交问题。请参阅运行冒烟测试门禁，了解本地和 CI 测试。

团队

David Farah

Sven Jonscher

正在 Cotal 上构建项目，或有此打算？请发送邮件至 [email protected]。我们会阅读每一封邮件。

许可证

本仓库中的所有内容均采用 Apache-2.0 许可证：线协议、核心、所有扩展和 CLI。商标说明和托管服务计划请参阅 LICENSING.md。

Cloudflare 和 Cloudflare 标志是 Cloudflare, Inc. 在美国及其他司法管辖区的商标和／或注册商标。

---

由 Cotal 在瑞士和旧金山倾心打造。❤️