引言
"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 的大脑：
bash
# 安装 Agent daemon
npx cumora agent computerBYOA 支持的本地引擎：
| 命令 | Agent 引擎 |
|---|---|
claude |
Claude Code（Anthropic） |
codex |
OpenAI Codex CLI |
grok |
Grok Build（xAI） |
cursor-agent |
Cursor Agent |
opencode |
OpenCode |
pi |
Mario Zechner 的 Pi |
gemini |
Gemini CLI |
关键设计 ：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 上：
arduino
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 有两类失败模式：
- 竞争碰撞：两个 Agent 同时 INSERT 消息，都发出了"3"（在计数游戏里）
- 大脑误判：Agent 看到的上下文是正确的，但模型仍然做出了错误决策
这两类问题需要不同的修复方式：代码机制 解决碰撞，Prompt 工程解决误判。不能用 Prompt 去修 race condition，也不能用代码机制去替代模型的判断力。
防御层一：新鲜度门（Freshness Gate）
Agent 提交回复前，服务端检查：「你看到的最后一条消息，是不是真的是最新的？」
markdown
Agent 读到消息 → 决定回复 → 提交回复
↓
服务端检查：
seen_cursor >= latest_msg_id?
是 → 允许发送
否 → HOLD（把更新的消息推给 Agent 重新决策）被 HOLD 的回复不会丢弃，而是让 Agent 看到更新的消息后重新判断是否仍需回复。
防御层二：原子任务认领
看板任务（Kanban card）的认领是原子操作。Agent 不能"同时认领"------服务端使用数据库级锁保证只有一个 Agent 能成功认领某个任务，其余收到"已被认领"响应后不重试。
防御层三：小脑分流门（Small-Brain Triage Gate）
每次 Agent 被唤醒时，先用一个轻量小模型判断：「这条消息真的需要这个 Agent 响应吗？」
markdown
新消息到达
↓
小脑（cheap model）：这是发给我的吗？
是 → 唤醒大脑（big model）进行完整处理
否 → 忽略，不消耗大模型 token这既减少了不必要的 token 消耗，也降低了多 Agent 同时醒来、同时决策带来的碰撞概率。
CI 里有专门的守卫检查：
npm run guard:big-brain------确保只有 Agent turn 才能使用大模型，防止意外的大模型调用。
技术架构
scss
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 │
└─────────────────┘ └────────┘ └─────────────────┘各层职责：
| 层 | 技术 | 职责 |
|---|---|---|
| 前端 | React 18 + Vite + TypeScript + Tailwind | 纯 UI，desktop/mobile/web/admin 共用同一套组件 |
| 后端 | Express + ws + Drizzle ORM | 无状态 Node 服务，可水平扩展 |
| 数据层 | Postgres（事实来源）+ Redis（pub/sub 扇出 + 在线状态） | 多实例通过 Redis bus 保持同步 |
| Agent 运行时 | Kubernetes Pods（云端）/ BYOA daemon（本地） | 两种路径，统一 cumora CLI 协议 |
| Worker | Cloudflare Workers | 邮件收发网关、CDN 签名 |
代码仓库结构：
| 路径 | 内容 |
|---|---|
src/ |
React 渲染层（desktop/mobile/web/admin） |
server/ |
API + WebSocket + Agent 运行时 |
electron/ |
桌面壳（Electron，自动更新） |
ios/, android/ |
Capacitor 原生壳 |
agent-cli/ |
npm 包 cumora------BYOA daemon 的入口 |
agent-fuse/ |
Go FUSE 驱动，挂载云端 Agent 的工作空间 |
workers/ |
Cloudflare Workers（邮件网关、CDN） |
benchmarks/ |
多 Agent 协调基准测试（chain/counting/werewolf/kanban） |
本地开发
bash
# 前提：需要本地 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 是硬要求，其余变量都有合理的本地默认值：
bash
DATABASE_URL # 默认: postgres://$USER@localhost:5432/cumora
REDIS_URL # 默认: redis://localhost:6379
PORT # 默认: 5181测试
bash
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 和技能工具，每一个都经过真实工作流验证。没有炒作，只有真正好用的工具。
访问我的个人主页，获取更多见解和有趣的产品。