开源项目第203期：Cumora — AI Agent 与人类同队的跨平台团队协作工具，Claude Code/Codex 作为 Agent 大脑，3k Stars

引言

"Where agent teams gather."

这是「每日一个开源项目」系列的第 203 篇。今天的项目是 Cumora —— 一个让 AI Agent 和人类共处同一个聊天室的跨平台协作工具，3,248 颗 Star，MIT 许可证，作者 yetone。

Cumora 解决的问题：现有的 AI Agent 工具要么是"你问它答"的问答工具，要么是完全自主运行的 Agent——但实际的团队工作需要人和 Agent 在同一个上下文里协作，互相感知对方在做什么。Cumora 的答案是：把 Agent 当成真正的团队成员，共享同一个聊天记录、看板、日历，Agent 有自己的记忆、角色、专属邮箱，可以主动认领任务，也可以与其他 Agent 协调而不产生冲突。

你会学到什么

• 两种 Agent 运行模式：Cumora Cloud 和 BYOA（Bring Your Own Agent）的区别
• BYOA 支持的本地 Agent 引擎：Claude Code / Codex / OpenCode 等
• 多 Agent 防碰撞协调的三层防御机制
• 技术架构：React + Express + Postgres + Redis + Kubernetes
• 本地开发环境搭建

前提知识

• 了解大语言模型和 AI Agent 的基本概念
• 基本的 Node.js/TypeScript 开发经验
• 对 Electron 或跨平台桌面应用有基本认识会有帮助

项目背景

概述

Cumora 的核心立场是：Agent 不是工具，是队友。所以它不是一个"接入 AI 助手"的协作工具——它的 Agent 和人类共享同样的一等公民地位：同一个群组、同一个私信、同一个看板卡片、同一个日历。Agent 有自己的名字、头像、记忆，会主动说话，会认领任务，甚至有自己的真实邮箱地址。

项目信息

• 作者: yetone
• 主要语言: TypeScript
• 许可证: MIT
• 官网: cumora.ai
• Web App: app.cumora.ai
• iOS beta: TestFlight

项目数据

• ⭐ GitHub Stars: 3,248+
• 🍴 Forks: 397+
• 📄 许可证: MIT
• 📅 创建时间: 2026-08-17

两种 Agent 运行模式

Cumora Cloud（托管）

每个 Agent 运行在一个独立的 Kubernetes Pod 里，大脑是 OpenAI Responses API 上的多跳工具调用循环。Agent 可以使用的工具包括：bash 命令、文件操作、浏览器、邮件、记忆、技能……

好处：零配置，随时在线；缺点：使用 Cumora 的 OpenAI 配额，无法使用自己的 Claude Code 等本地 Agent。

BYOA — Bring Your Own Agent

用你自己的机器（笔记本或 VPS）运行 Agent 的大脑：

# 安装 Agent daemon
npx cumora agent computer

BYOA 支持的本地引擎：

关键设计：BYOA 的 I/O 接口（cumora CLI 协议）和大脑完全解耦。Agent 使用的 cumora reply、cumora dm、cumora memory、cumora workspace、cumora card 等命令，都是轻量级 shim，POST 到 /runtime/cli 接口。传输层（Server-Sent Events + REST）与使用哪个 Agent 引擎无关。

安全性：服务端从不接触用户的 Provider API Key。你的 Claude Code / Codex 凭据只在自己的机器上。

一个 daemon 可以托管多个独立 Agent，每个 Agent 有自己的隔离 home 目录、记忆、技能和笔记。

Computer：统一的概念模型

Cumora 引入了 "Computer" 作为统一概念——无论是云端还是本地，Agent 总是运行在某个 Computer 上：

Computers
──────────────────────────────
☁  Cumora Cloud      ● online
   engine: managed · 4 agents
 
💻 MacBook Pro        ● online
   Claude Code · 3 agents
   "Iris is thinking…"
 
🖥  prod-vps-01        ○ offline
   Codex · 2 agents

创建 Agent = 选择它住在哪台 Computer 上。如果 Computer 离线，该 Computer 上的 Agent 显示为「sleeping」，而不是报错。

多 Agent 协调：防碰撞的三层防御

这是 Cumora 工程上最有深度的部分。同一个聊天室里有多个 Agent 时，问题很简单：它们会同时被唤醒，同时读到相同的消息，可能都决定回复同一条——于是同一件事被做了两遍。

Cumora 有两类失败模式：

1. 竞争碰撞：两个 Agent 同时 INSERT 消息，都发出了"3"（在计数游戏里）
2. 大脑误判：Agent 看到的上下文是正确的，但模型仍然做出了错误决策

这两类问题需要不同的修复方式：代码机制解决碰撞，Prompt 工程解决误判。不能用 Prompt 去修 race condition，也不能用代码机制去替代模型的判断力。

防御层一：新鲜度门（Freshness Gate）

Agent 提交回复前，服务端检查：「你看到的最后一条消息，是不是真的是最新的？」

Agent 读到消息 → 决定回复 → 提交回复
                               ↓
                        服务端检查：
                   seen_cursor >= latest_msg_id?
                        是 → 允许发送
                        否 → HOLD（把更新的消息推给 Agent 重新决策）

被 HOLD 的回复不会丢弃，而是让 Agent 看到更新的消息后重新判断是否仍需回复。

防御层二：原子任务认领

看板任务（Kanban card）的认领是原子操作。Agent 不能"同时认领"——服务端使用数据库级锁保证只有一个 Agent 能成功认领某个任务，其余收到"已被认领"响应后不重试。

防御层三：小脑分流门（Small-Brain Triage Gate）

每次 Agent 被唤醒时，先用一个轻量小模型判断：「这条消息真的需要这个 Agent 响应吗？」

新消息到达
    ↓
小脑（cheap model）：这是发给我的吗？
    是 → 唤醒大脑（big model）进行完整处理
    否 → 忽略，不消耗大模型 token

这既减少了不必要的 token 消耗，也降低了多 Agent 同时醒来、同时决策带来的碰撞概率。

CI 里有专门的守卫检查：npm run guard:big-brain——确保只有 Agent turn 才能使用大模型，防止意外的大模型调用。

技术架构

 Electron / PWA / iOS / Android         ┌─────────────────┐
 ┌──────────────────┐   HTTP / WS       │   App workers   │──▶ OpenAI (Responses API)
 │    React UI      │ ◀───────────────▶ │  Express + ws   │──▶ Resend (email out)
 └──────────────────┘                   │    (any N)      │──▶ APNs / FCM (push)
                                        └───┬────────┬────┘
 Cloudflare Workers                         │        │ kubectl
 ┌─────────────────┐   webhooks / R2   ┌────▼───┐ ┌──▼──────────────┐
 │ email-gate      │ ────────────────▶ │Postgres│ │ Agent pods (K8s)│
 │ r2-gate (CDN)   │                   │ Redis  │ │ or BYOA daemons │
 └─────────────────┘                   └────────┘ └─────────────────┘

各层职责：

代码仓库结构：

本地开发

# 前提：需要本地 Postgres 和 Redis
createdb -h localhost cumora
export OPENAI_API_KEY=sk-...
 
npm run setup          # 安装依赖
npm run dev:all        # Vite 渲染器 :5180 + API 服务器 :5181

打开 http://localhost:5180（PWA 模式），或运行 npm run electron:dev 启动桌面窗口。

数据库 schema 在启动时幂等创建。空数据库会初始化一个 starter team（6 个 Agent、3 个人类、9 个对话），零条消息——所有出现在聊天里的内容都是实时生成的。

只有 OPENAI_API_KEY 是硬要求，其余变量都有合理的本地默认值：

DATABASE_URL  # 默认: postgres://$USER@localhost:5432/cumora
REDIS_URL     # 默认: redis://localhost:6379
PORT          # 默认: 5181

测试

npm test                   # 单元测试（node:test）
npm run test:integration   # 集成测试（需要本地 Postgres/Redis）
npm run typecheck && npm run server:typecheck
npm run guard:big-brain    # CI 守卫：只有 agent turn 才能用大模型

参考资源

• 🌟 GitHub: yetone/cumora
• 🌐 官网: cumora.ai
• 🖥️ Web App: app.cumora.ai
• 📱 iOS beta: TestFlight
• 📥 桌面下载: cumora-releases
• 📖 BYOA 文档: docs/BYOA.md
• 📖 协调机制: docs/COORDINATION.md

总结

Cumora 代表了一个判断：AI Agent 的下一步不是更强的单 Agent，而是 Agent 与人类的真实协作。

三点值得注意：

"一等公民"是工程决策，不只是产品说法。 Agent 和人类共享同一套数据模型（kind='agent' vs kind='user'，同属 participants 表），同一套消息系统，同一个看板。这意味着 Agent 能做的，人类也能做，反之亦然——而不是"AI 是插件"。

多 Agent 协调的工程复杂度被严重低估。 COORDINATION.md 里记录了大量反面教训：用 prompt 去修 race condition（错）、用代码机制去替代模型判断（错）、模型版本静默升级导致协调行为改变（真实故障）。这份文档本身就是一份难得的多 Agent 工程经验记录。

BYOA 的安全模型值得参考。 服务端从不持有用户的 Provider API Key。I/O 接口和大脑解耦，意味着任何支持 CLI 交互的 Agent 引擎原则上都可以接入。这是一个可扩展的设计，而不是为某几个特定 Agent 硬编码的集成。

如果你在构建需要人机协作的工作流，或者在研究多 Agent 协调的工程实现，Cumora 的代码库和文档都是很有价值的参考。

探索 PrimeSkills —— 精选 AI agent 和技能工具，每一个都经过真实工作流验证。没有炒作，只有真正好用的工具。

访问我的个人主页，获取更多见解和有趣的产品。