Common Ground

2025-07-20AI专业工具 / 智能体开发101 次浏览

综合介绍

Common Ground 是一个开源应用程序，专门用于构建、观察并与一组AI智能体团队进行协作。它旨在解决当前日益复杂的AI智能体开发中所缺失的关键环节：实现真正有效的人机协作。该项目通过一个强大的多智能体架构和实时的网页用户界面，将复杂的AI工作流程变得透明、可管理和可协作。其核心理念是为人类的直觉与AI的计算能力创造一个可以交汇的“共同基础”（Common Ground），让用户从一个被动的指令发出者，转变为一个能够主动驾驶和引导AI团队的“驾驶舱里的飞行员”。该框架适合用于处理需要多个步骤、涉及大量研究的复杂任务，帮助开发者构建能够进行策略性、协作性工作的智能体系统，而不仅仅是简单的命令响应链。

功能列表

高级多智能体架构: 模拟真实世界中的咨询团队，其架构包含一个用于用户交互的“合伙人”智能体（Partner）、一个用于规划和任务拆解的“项目主管”智能体（Principal），以及多个用于执行具体任务的“助理”智能体（Associate）。
声明式智能体设计: 无需编写代码或只需少量代码即可定制智能体。用户可以通过简单且人类可读的YAML文件来定义智能体的复杂行为、提示、工具权限以及上下文传递协议。
全套的可观测性工具: 提供了超越传统print()调试的工具。用户可以通过动态的流程图、看板和时间线视图，实时可视化智能体团队的执行过程，理解每一个决策、工具调用和状态变化。
可扩展的统一工具集: 可以轻松地通过模型上下文协议（MCP）集成自定义的Python工具或外部API。所有功能都被视为标准化的工具，任何智能体都可以调用。
模型无关性: 由LiteLLM驱动，该框架支持所有主流的大语言模型提供商。默认的Docker配置中包含了一个预设的桥接，可以无缝集成Google的Gemini模型。
内置项目与知识管理: 运行的任务可以被组织到项目中进行管理。系统内置一个能自动更新的检索增强生成（RAG）系统，它会索引工作区内的文件，为智能体提供最相关、最新的上下文信息。

使用帮助

Common Ground 设计了两种主要的使用模式，一种是推荐给大多数用户的Docker部署模式，另一种是面向希望修改核心代码的开发者的本地设置模式。

模式一：推荐部署方式 (使用Docker)

这是运行完整系统的最简单方法，包含了所有预设配置，尤其是用于多智能体模式的gemini-cli-bridge。

前提条件:

已安装 Docker 和 Docker Compose
已安装 Git

操作步骤:

克隆代码仓库:打开终端，运行以下命令将项目代码克隆到本地。
```
git clone https://github.com/Intelligent-Internet/CommonGround
cd CommonGround
```
初始化Git子模块:这一步至关重要，它会拉取项目依赖的gemini-cli-mcp-openai-bridge等重要模块。
```
git submodule update --init --recursive
```
进入部署目录:所有的docker compose命令都必须在此目录下运行。
```
cd deployment
```
使用Google账户进行首次认证 (可选但推荐):如果您之前没有在您的电脑上使用过Gemini CLI，请运行此命令来进行交互式登录。它会保存您的凭证供后续使用。
```
docker compose run --rm --service-ports login
```
根据屏幕提示操作，选择认证方式并点击授权链接。完成后，您可以用ctrl+c退出。
启动所有服务:此命令会构建镜像并启动所有服务。
```
docker compose up
```
如果您希望在后台运行，可以添加-d参数：
```
docker compose up -d
```
如果需要重新构建镜像，可以添加--build参数：
```
docker compose up --build
```
访问应用:打开您的网络浏览器，访问 http://localhost:8000 即可开始使用。

模式二：开发者模式 (本地设置)

此模式适用于希望修改后端或前端代码，或使用不同LLM提供商的开发者。

前提条件:

Python 3.12+
Node.js 和 npm/yarn
uv (一个快速的Python包管理工具, 可通过 pip install uv 安装)

操作步骤:

启动后端服务:
- 进入core目录: cd core
- 创建Python虚拟环境: uv venv
- 安装依赖: uv sync
- 创建本地环境配置文件: cp env.sample .env
- 编辑.env文件，配置您自己的大语言模型API密钥或其他设置。
- 启动服务器: uv run run_server.py
- 后端服务将在http://localhost:8000上运行。
启动前端服务:
- 打开一个新的终端窗口。
- 进入frontend目录: cd frontend
- 创建本地环境配置文件: cp .env.example .env.local
- 安装依赖: npm install
- 启动开发服务器: npm run dev
- 前端界面将在http://localhost:3000上运行，您可以直接通过此地址访问。

应用场景

复杂的课题研究与分析用户可以提出一个复杂的研究问题，例如“分析2024年全球半导体市场的趋势并预测2025年的主要增长点”。Common Ground的智能体团队会自动协同工作：“合伙人”智能体与用户沟通确认需求，“项目主管”智能体将任务分解为市场数据搜集、竞争对手分析、技术前沿追踪等多个子任务，然后分配给不同的“助理”智能体并行执行。整个过程用户都可以实时观察，甚至介入调整。
自动化内容创作可以利用该框架生成深度报告、技术文档或系列博客文章。用户只需设定主题和基本要求，AI团队就能自动进行资料搜集、内容组织、草稿撰写和校对，最终整合成一份完整的报告。
模拟决策与方案评估企业或个人可以利用该平台模拟不同的业务场景。例如，可以设定一个辩论场景，让两个分别代表“支持”和“反对”观点的智能体就“公司是否应该进入某个新市场”展开辩论，它们会各自搜集论据，进行逻辑严密的攻防，为人类决策者提供更全面的视角。
教育与培训在教育领域，可以构建一个虚拟导师团队，针对学生的提问提供多角度的解答。例如，一个学生提问关于“黑洞”的问题，系统可以派出一个物理学家智能体、一个历史学家智能体和一个科幻作家智能体，分别从科学原理、发现历史和文化影响等不同层面进行解答。

QA

Common Ground支持哪些大语言模型？该框架通过LiteLLM实现模型无关性，理论上支持任何主流的大语言模型提供商，包括但不限于OpenAI的GPT系列、Google的Gemini系列、Anthropic的Claude系列以及各种开源模型。默认配置为Google Gemini做了优化，但用户可以通过修改core/agent_profiles/llm_configs/目录下的YAML配置文件来添加和切换模型。
如何为智能体添加一个新工具？为智能体添加新工具非常简单。您只需要在core/agent_core/nodes/custom_nodes/目录下创建一个新的Python文件，定义一个继承自BaseToolNode的类，并使用@tool_registry装饰器进行标记。框架会自动发现这个新工具，并可以授权给指定的智能体使用。
我可以自定义智能体之间的协作方式吗？可以。智能体之间的交互逻辑和数据传递规则可以在core/agent_profiles/handover_protocols/目录中定义。通过编辑这些YAML文件，您可以设计复杂的协作流程，例如定义“项目主管”智能体如何将任务和所需材料准确地“交接”给“助理”智能体。
如果我遇到Docker安装问题怎么办？如果在运行docker compose run ... login时遇到关于GOOGLE_CLOUD_PROJECT的环境变量错误，您需要编辑deployment/docker-compose.yaml文件，在bridge服务的部分，取消对GOOGLE_CLOUD_PROJECT环境变量的注释，并填入您自己的Google Cloud项目ID。更多细节可以参考项目README中的故障排除部分或在官方Discord社区中寻求帮助。