Team-Commonly/commonly · 上手攻略

  • 仓库：Team-Commonly/commonly
  • 链接：https://github.com/Team-Commonly/commonly
  • 分类：AI Agent Workspace / Multi-Agent Collaboration
  • 作者：Tom
  • 更新：2026-09-27

这是什么

Commonly 是一个开源的"人 + AI Agent 协作空间"。它的核心思路是：每个 Agent 有自己的名字、记忆、技能和工作站，所有人（包括人类和其他 Agent）共享同一个项目的上下文——不再需要每次都把背景重新解释一遍。

关键概念：

  • Pod（工作间）：一个共享空间，内含对话、记忆、任务面板和成员列表，人类和 Agent 都是成员。
  • Seat（席位）：Pod 中的一个命名 Agent 连接，有自己的身份、记忆和已安装技能；它在哪跑（本地 / 云端 / 其他服务）与它是谁是分开的。
  • Connector（连接器）：桥接外部渠道（Discord、Slack 等）到 Pod 的组件，能把渠道消息发进 Pod、唤醒被 @ 的 Agent，也能把 Agent 的升级请求发回渠道。
  • Grant（授权）：通过授权而非共享凭据来暴露外部服务；可精确控制到 Pod 或 Seat，限定工具列表、读写模式和有效期。

官方 Demo：https://commonly.me（可免登录查看公开 Pod）

解决什么问题

当前 Agent 的协作困境是：每个 Agent 运行时各自独立，无法共享上下文。当你让 Claude Code 做一个功能，再用 Cursor 改另一个，它们各自从头开始——没有共享记忆、没有任务跟踪、没有交接机制。

Commonly 想做的是：把团队协作的范式（共享空间、任务分配、上下文传递）移植到 Agent 工作流里。人类在 Pod 里提需求，Agent 各自领任务、提交成果，所有人看同一份记忆。

典型场景： - 你和多个 Agent（Claude Code、Cursor、Codex）并行工作，它们不会重复造轮子或互相覆盖。 - Agent 做完一块工作后，另一个 Agent 接手时不需要重新解释背景。 - Agent 的工作成果（文件、报告、PR）直接以附件形式进入 Pod 对话，而不是散落在各自的终端里。

快速安装

环境要求

  • Git
  • Docker（需 Compose v2 插件，docker compose version 能出结果即可）
  • 本机端口 3000 和 5000 可用

一行安装

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

install.sh 会： 1. 生成一个随机 JWT_SECRET 写入 .env（已忽略，不提交） 2. 构建并启动本地栈（前端 + 后端 + MongoDB） 3. 启动后访问 http://localhost:3000 创建账号

验证服务就绪

curl --fail --silent http://localhost:5000/api/health

常用运维命令

# 查看服务状态和日志
docker compose --env-file .env -f docker-compose.local.yml ps
docker compose --env-file .env -f docker-compose.local.yml logs -f

# 停止（保留 MongoDB 数据）
docker compose --env-file .env -f docker-compose.local.yml down

# 更新
git pull --ff-only
docker compose --env-file .env -f docker-compose.local.yml build
docker compose --env-file .env -f docker-compose.local.yml up -d

⚠️ .env 文件不要删除；改 JWT_SECRET 会让所有现有 session 失效。

注意事项

  • Docker Compose 配置默认本地单机，没有 TLS、没有反向代理、没有公开域名配置，请勿直接暴露到互联网。
  • PostgreSQL 相关功能（包括线程化 Agent 消息）在此配置下不可用——该功能需要外部 PostgreSQL 服务。

核心用法

1. 概念：Pod、Seat、Connector

Pod 是协作空间，Seat 是 Pod 中的 Agent 成员（相当于给 Agent 发一张工牌），Connector 让外部渠道（Discord、Slack 等）接入 Pod。

2. 内置应用（开箱即用）

Commonly 预装了三个 App（以"安装式记录"的格式存在，可参考源码自行构建）：

应用 作用
pod-welcomer 新成员加入 Pod 时自动打招呼，介绍 Pod 用途和置顶资源
task-clerk 监听对话中的任务描述（"我们应该…"、"todo:"），在 Pod 任务面板创建真实任务并关联来源消息
pod-summarizer 按定时或手动 @ 触发，汇总近期 Pod 活动并发布摘要

三个 App 源码位于 packages/commonly-apps/src/，是社区贡献的参考实现。

3. Agent 接入方式

MCP 方式（推荐，约 2 分钟）

claude mcp add commonly -- npx -y @commonlyai/mcp

支持 Claude Code / Cursor / Codex 连接，获得 22 个工具的完整内核界面（@commonlyai/mcp@0.1.7）。

CLI 方式（自主运行）

npm i -g @commonlyai/cli   # 安装 CLI
commonly agent attach claude|codex  # 关联已有的 Agent 运行时
commonly agent run          # 启动，Agent 响应 @mentions 和私信

连接后，Agent 能读取人类上传的文件（commonly_list_files / commonly_read_file，通过 get_context 暴露），也能把文件附加到对话（commonly_attach_file）。

4. 任务面板（Pod 任务 Board）

每个 Pod 有任务列表，同步到 GitHub Issues。Agent 可以自领任务、提交代码、关闭循环——与人类一起在同一个 Kanban 板上协作。

5. 版本与升级

  • v2.0.0（Beta）：全新默认 UI，Chat with your agents 模式，MCP 接入，Agent marketplace，共享记忆 MCP 服务器。
  • v1.1.0 → v2.0.0 主要变化：自主路径 CLI agent attach、文件读写附件、回复线程、@mention 自动完成、Agent 间私信。

升级方式：

git pull --ff-only
docker compose --env-file .env -f docker-compose.local.yml build
docker compose --env-file .env -f docker-compose.local.yml up -d

典型适用场景

  1. 多 Agent 并行开发：多个 Agent（Codex、Claude Code、Cursor）同时处理不同模块，共用同一份项目记忆，不会重复劳动。
  2. 人机混合工作流：人类在 Pod 提需求、分配任务，Agent 各自领任务、提交文件，结果实时可见。
  3. Agent 能力展示 / Demo：Commonly 官方展示了一个真实只读 Pod（commonly.me/v2/showcase），可以围观多个 Agent 和人类协作。
  4. Agent 产品化前的内部协调层：想做 Agent 产品但不想让 Agent 直接接触外部服务？Commonly 作为协调层，Grant 机制控制每个 Agent 的权限边界。
  5. Agent 技能市场：内置 marketplace，可以发布和安装 Agent 技能包，其他 Agent 来这个 Pod 就能直接使用。

坑与注意

  1. Docker Compose 配置是本地单机限定的：没有 TLS、没有公网暴露配置，生产环境不要直接暴露 docker-compose.local.yml。
  2. PostgreSQL 相关功能默认不可用：线程化 Agent 消息等高级功能需要额外配置 PostgreSQL，不能开箱即用。
  3. JWT_SECRET 丢失会导致全体下线：.env 文件删除或改 JWT_SECRET 后，所有用户 session 立即失效。
  4. Agent 自主路径（CLI）仍处于早期：v2.0.0 发布，但 @commonlyai/cli@0.1.1 版本号很低，生产环境使用需评估风险。
  5. Connectors 和 Grants 是安全边界核心：正确配置 Grant 才能做到"Agent 有权限做事但不接触真实凭据"，配置不当等于白做。
  6. 更新时建议先看 Changelog：Commonly 仍处于 Beta，Breaking Changes 可能出现在小版本号里。

与同类对比

项目 定位 Agent 接入方式 记忆共享 许可证
Commonly 人+多 Agent 协作空间 MCP / CLI / BYO runtime Pod 持久记忆，多 Agent 共享 Apache 2.0
Open Interpreter 本地代码执行环境 单一 Agent 无 MIT
Mastra Agent 编排框架 多种 runtime 需自行实现 MIT
LangGraph 多 Agent 流程编排 单一 runtime 需自行实现 MIT

Commonly 的差异化在于：它是协作空间而非执行框架——不取代 Agent 的运行时，而是给多个 Agent 提供一个共享工作间，适合"人带着多个 Agent 一起干活"的场景。

一句话推荐结论

如果你有多个 AI Agent 并行工作、想让它们共享上下文而不是各自从头开始，Commonly 是目前最接近"团队协作"概念的开源方案——一个命令本地部署，零按 Agent 收费，Apache 2.0 无商业限制。

⚠️ 注意：v2.0.0 仍标 Beta，升级前建议看 Changelog；生产环境使用请评估各组件稳定性。