Commonly：让所有 AI Agent 共享「项目记忆」的开源工作区

一、痛点切入：为什么你的 AI 助手总在「失忆」？

想象这样一个场景：你的团队同时用着 Claude Code 写代码、Cursor 做前端、Codex 做代码审查，每个工具都「聪明」，但彼此之间毫无沟通——你在 Claude Code 里定义好的项目规范，到了 Cursor 里又要重新解释一遍；Codex 审查 PR 时，根本不知道三天前你在团队群里达成的技术决策。这就是当前 AI 辅助开发的最大痛点：每个 AI 工具都是一座孤岛，记忆不互通。

Commonly 正是为解决这个痛点而生。它是一个开源的 AI Agent 协作工作区，核心理念是：让多个 AI Agent 和团队成员共享同一个「项目记忆」，而非各自为战。 无论是 Claude Code、Cursor、Codex，还是你自己开发的 Agent，只要接入 Commonly，就能读写同一个项目上下文，彻底告别重复「教 Agent 认识项目」的烦恼。

二、项目背景与起源

Commonly 由 Team-Commonly 团队开发，诞生于 2024 年，定位是「Agent 界的协作平台」。它的目标不是替代某个 AI 编程工具，而是做一个统一的协调层——把各种 Agent 连接到一个共享的工作空间（Pod）里。

项目采用 Apache 2.0 开源协议，支持完全自托管部署，承诺「没有按 Agent 计费」的商业模式。从 GitHub 数据看，仓库已有超过 1230 次提交，版本号来到 1.1.0，进入了相对成熟的阶段。项目首页为 https://commonly.me，支持在线体验。

三、核心功能：Pod、Agent 与共享记忆

3.1 Pod——Agent 的「共享办公室」

Pod 是 Commonly 的核心抽象，可以理解为一个带持久化记忆的工作空间。每个 Pod 包含：

• 共享记忆（Memory）：所有成员（人类 + Agent）都能读取和写入的记忆层，是项目上下文、决策记录、技术债务的存放地。
• 技能（Skills）：可复用的行为模板，以 SKILL.md 文件形式存储，让 Agent 知道如何「像个团队成员一样」行动。
• 看板（Task Board）：Kanban 风格的任务管理，支持拖拽，并且与 GitHub Issues 双向同步——在 Pod 里建任务，GitHub Issues 自动更新，反之亦然。
• 成员列表：混合的人类成员和 Agent 成员，Agent 拥有「可移植的身份」——换运行时（从 Claude Code 切到 Codex）时，记忆和上下文全部保留。

3.2 多运行时支持

Commonly 支持三种 Agent 接入层级：

层级	运行时	配置复杂度	适用场景
原生层	LiteLLM（内置）	零配置	轻量 Agent、快速原型
云沙箱	Anthropic Managed Agents	零配置（按量付费）	重计算、工具密集型 Agent
自带（BYO）	OpenClaw / Codex / Claude Code / Gemini CLI	自行配置	完全自控、API Key 自持

支持的主流 Agent 运行时包括：OpenClaw（默认开发 Agent）、OpenAI Codex（驱动 Cody 编程 Agent）、Claude Code、Google Gemini CLI，以及通过 @commonly/agent-sdk 自定义接入的任意 HTTP Agent。

3.3 内置 Agent 市场

Commonly 内置了多个预配置 Agent，可直接「雇佣」到团队 Pod 中工作：

• Theo：开发项目经理，负责任务分配、PR 审查和进度协调（OpenClaw 驱动）
• Cody：编程工程师，负责克隆代码、编辑、测试和 PR 创建（Codex 驱动）
• Nova：后端研究 Agent，负责后端代码审查和技术调研（OpenClaw 驱动）
• Pixel：前端 Agent，负责 CSS/React 审查和 UI 研究（OpenClaw 驱动）
• Ops：DevOps Agent，负责 CI/CD、Kubernetes 和基础设施维护
• Liz：社区运营 Agent，监控 GitHub Discussions

3.4 MCP 集成（推荐接入方式）

Model Context Protocol（MCP）是 Commonly 推荐的新一代 Agent 接入协议，接入流程非常简洁：

1. 在 Web UI 的 Agents → Bring your own agent 页面
2. 复制生成的 commonly_* kernel tools 配置行
3. 可选：添加 docs/agents/skills/commonly/SKILL.md 技能文件，让 Agent 更好地理解团队协作规范

四、技术架构解析

4.1 前端：React + Material UI + Vite

前端采用 React 18 + Material UI (MUI) + Vite 构建，使用了以下关键库：

• @dnd-kit：拖拽功能，支撑看板的拖拽操作
• react-markdown：渲染 Agent 消息中的 Markdown 内容
• socket.io-client：实时通信，支撑 Pod 内的即时消息和事件推送
• chart.js / d3：数据可视化，展示项目趋势和 Agent 工作指标
• papaparse / xlsx：文件导入导出

前端使用 TypeScript，有完整的 ESLint 配置和 Jest 测试覆盖，通过 Vite 进行热更新开发。

4.2 后端：Node.js + Express + MongoDB/PostgreSQL

后端是 Node.js/Express 应用，使用 TypeScript 编写，主要技术栈：

• MongoDB + Mongoose：存储 Pod、记忆、任务、消息等文档数据
• PostgreSQL + pg：结构化数据存储（如 Agent 配置、用户会话）
• Socket.IO：双向实时通信，推送 Agent 事件和消息通知
• Redis + Socket.IO Redis Adapter：支持多实例部署时的分布式 WebSocket
• OpenAI SDK：集成 GPT 系列模型的 API 调用
• @google/generative-ai：集成 Gemini 模型
• discord.js：与 Discord 平台集成（项目支持 Discord Bot 作为 Agent 载体）
• JWT + bcryptjs：用户认证和密码哈希
• Helmet + express-rate-limit：安全防护（HTTP 头加固 + API 限流）
• @kubernetes/client-node：K8s 运行时支持
• multer：文件上传处理

后端代码有完整的 Dockerfile（多阶段构建），支持 TypeScript 编译和 ESLint 检查。

4.3 共享包：commonly-marketplace

项目包含一个 commonly-marketplace 包（作为 commonly-marketplace/marketplace.json 挂载到后端容器），定义了所有内置 Agent 的元数据描述，实现 Agent 的自动注册机制——后端启动时扫描 marketplace 清单，自动将 Agent 配置注入 Pod。

4.4 MCP Server：commonly-mcp

项目包含一个独立的 MCP 服务器包 commonly-mcp，遵循 Model Context Protocol 规范，负责 Agent 与平台之间的上下文同步和工具调用。

五、部署体验：一键启动的实际感受

Commonly 提供了三套部署方案，覆盖从快速尝鲜到生产上线的全场景：

5.1 开发环境一键启动（最推荐）

git clone https://github.com/Team-Commonly/commonly.git
cd commonly
./install.sh

install.sh 脚本会依次检查 Docker 和 Docker Compose 是否安装，然后使用 docker-compose.local.yml 启动完整技术栈：

• MongoDB：持久化存储 Pod 记忆和消息
• PostgreSQL：存储结构化配置和用户数据
• Backend：Node.js API 服务（端口 5000）
• Frontend：React 应用（端口 3000）

首次启动后访问 http://localhost:3000 即可进入 Web UI，全程零手动配置。

5.2 开发模式热更新

./dev.sh up           # 启动完整服务
./dev.sh logs         # 查看日志
./dev.sh test         # 单元测试（内存模式，无需服务）
./dev.sh test:integration  # 集成测试（需要服务运行）

5.3 生产级 Kubernetes 部署

项目内置了 k8s/ 目录，包含 Helm Chart 配置，支持：

• GKE（Google Kubernetes Engine）云构建部署（cloudbuild.frontend.yaml）
• 多副本高可用配置
• 使用 Google Secret Manager 管理密钥
• 通过 ./dev.sh cluster 本地模拟 K8s 环境（需要 kind）

5.4 硬件需求

Commonly 整体偏向 CPU 密集型（Agent 推理发生在外部运行时），本地部署硬件需求：

资源	最低配置	推荐配置
内存	4GB	8GB
磁盘	10GB	20GB
GPU	不需要	不需要

Commonly 本身不运行 AI 模型推理，所有 LLM 调用都通过 API 发送到外部服务（OpenAI、Anthropic、Google），因此对 GPU 完全无需求，一台普通开发机即可流畅运行。

六、争议与局限

6.1 Agent 记忆的「一致性」难题

共享记忆听起来美好，但多个 Agent 同时读写同一个记忆池时，如何避免写冲突和上下文过期？Commonly 使用消息队列（Socket.IO + Redis）来处理实时事件，但高并发场景下记忆的一致性保证尚未有详尽文档。

6.2 隐私与数据安全

Agent 在 Pod 中产生的所有对话和决策记录都会持久化到 MongoDB/PostgreSQL 中。如果处理的是敏感项目代码，必须严格评估数据本地化风险——Commonly 支持全自托管，理论上数据不出本地网络，但内部 Agent SDK 的 API 调用（OpenAI/Anthropic）仍然会发送数据到第三方。

6.3 活跃度与社区成熟度

项目 Stars 超过 1160，但 Issues 有 38 个开放状态，Commit 频率虽高，但作为 2024 年的新项目，其长期维护和社区生态的可持续性仍需观察。

七、行业意义与趋势

Commonly 代表的趋势是 「AI Agent 编排层」（Agent Orchestration Layer） 的崛起。随着 Claude Code、Cursor、Codex 等工具普及，团队中同时运行多个 Agent 的场景越来越常见，对「协调层」的需求应运而生。类似的竞品包括 Raft（已被 Cognition 收购），而 Commonly 的差异化在于：

• 完全开源：代码透明，可自审计
• 运行时无关：不绑定任何特定 Agent 工具
• 没有按 Agent 计费：真正做到一次部署、无限 Agent 接入

增长潜力：随着 AI 编程工具的继续渗透，更多团队会面临「多 Agent 协作」问题，Commonly 这类中间层平台的价值会持续放大。

八、总结评价

维度	评分	简评
部署体验	⭐⭐⭐⭐⭐	一键 Docker Compose，零配置启动
架构完整性	⭐⭐⭐⭐	前后端分离，数据库选型合理，Socket.IO 实时架构扎实
功能覆盖	⭐⭐⭐⭐⭐	Pod + 记忆 + 看板 + MCP + 多运行时，核心功能完整
文档质量	⭐⭐⭐⭐	文档丰富，多场景指南，但部分架构决策记录（ADR）较深
代码质量	⭐⭐⭐⭐	TypeScript 全覆盖，ESLint + Jest 测试，有 CI/CD
AI/ML 集成	⭐⭐⭐⭐	多 Agent 运行时支持，MCP 协议，Agent SDK

适合人群：已经使用或计划使用多个 AI 编程工具的团队，希望建立统一的 Agent 协作规范和数据管理。

不适合：寻求直接 AI 编程能力的用户（Commonly 本身不写代码，是协调层）；对数据隐私有极高要求且无法接受任何外部 API 调用的场景。