用 Common Ground 打造看得见的 AI 团队：从安装到上手的完整指南

Common Ground 到底是什么？
为什么值得花时间了解它？
它的“合伙人-总监-专员”架构如何工作？
如何 15 分钟跑起来（Docker 模式）
开发模式：本地源码的 3 个命令
不敲代码也能改行为：YAML 配置速成
常见疑问 FAQ
下一步可以做什么？

1. Common Ground 到底是什么？

一句话：
它是一个开源的多智能体协作平台，把“一群 AI 像咨询公司团队一样组织起来”，并让你随时看清它们每一步在做什么。

用更生活化的比喻：

你像客户，提出一个大问题（例如“帮我调研 2025 年固态电池供应链风险”）。
Partner（合伙人）先和你聊天，把问题拆成可交付的“工作包”。
Principal（项目总监）把这些工作包排期、分配给不同 Associate（执行专员）。
每个专员完成自己的搜索、分析、写作任务，把结果回传。
总监汇总成最终报告，合伙人再向你汇报。
整个过程中，你能实时看到谁在干什么、用了哪些工具、中间结论如何变化——就像在 Trello 里看任务卡一样直观。

2. 为什么值得花时间了解它？

你现在的痛点	Common Ground 的解法
单一大模型一次性给出答案，难以追溯依据	多步流程拆成任务卡，每一步都有日志与引用
调整 prompt 成本高	行为写在 YAML，改一行即可重跑
工具/搜索/数据库接口各写各的	统一用 MCP 协议，新增工具只需一个 Python 装饰器
团队协作时需要共享上下文	内置 RAG，自动索引项目文件，所有 Agent 共享
不清楚内部到底怎么推理	提供 Flow、Kanban、Timeline 三种实时视图

3. “合伙人-总监-专员”架构拆解

官方用一张 Mermaid 图描述了数据流，我们把它翻译成日常对话：

步骤	谁	做什么	你看到的界面
1	你	输入大问题	浏览器聊天框
2	Partner	确认需求、写任务大纲	实时聊天流
3	Principal	把大纲拆成可并行的模块	Kanban 看板新增任务卡
4	Associate	并行执行：搜索、分析、写段落	看板卡片状态从“待办”到“进行中”
5	Principal	收结果、审阅、整合	Timeline 视图展示合并过程
6	Partner	生成最终报告，回答你	聊天框返回完整 Markdown 报告

实时通信靠 WebSocket，所有中间思考、工具调用、返回结果都会以卡片或消息的形式推送给你。

4. 如何 15 分钟跑起来（Docker 模式）

这是官方最推荐的入门路径，步骤全部来自 README，不删不减。

4.1 准备

一台能跑 Docker 和 Docker Compose 的电脑（Win/Mac/Linux 均可）。
一个 Google 账号（Gemini 免费额度即可）。

4.2 五步启动

克隆仓库

git clone https://github.com/Intelligent-Internet/CommonGround
cd CommonGround

拉取子模块（桥接器代码）

git submodule update --init --recursive

进入部署目录
```
cd deployment
```
首次登录（只需做一次）
```
docker compose run --rm --service-ports login
```
按提示用浏览器完成 Google 授权，完成后 Ctrl+C 退出即可。
- 如果遇到 GOOGLE_CLOUD_PROJECT 报错，按 README 指示在 docker-compose.yaml 里把 your_google_cloud_project_id_here 换成你的真实项目 ID，再重跑同一条命令。
启动所有服务
```
docker compose up --build -d
```
看到容器状态都为 healthy 后，打开浏览器访问
http://localhost:8000

4.3 验证

首页会出现一个示例项目，点击“Run”即可看到 Kanban 看板动起来。
左侧聊天窗口会自动出现 Partner 的问候语，说明链路已通。

5. 开发模式：本地源码的 3 个命令

如果你想改核心逻辑或换 LLM，可切到本地开发模式。

5.1 后端

cd core
uv venv              # 创建虚拟环境
uv sync              # 装依赖
cp env.sample .env   # 可选：改 LLM 配置
uv run run_server.py # 默认 http://localhost:8000

5.2 前端

另开终端

cd frontend
cp .env.example .env.local
npm install
npm run dev          # 默认 http://localhost:3000

浏览器打开前端地址即可，所有 API 自动指到后端 8000 端口。

6. 不敲代码也能改行为：YAML 配置速成

Common Ground 把“Agent 人设”拆成三类文件，全部用 YAML 描述，改完立即生效。

文件位置	作用	快速示例
`core/agent_profiles/profiles/*.yaml`	定义角色、系统提示、可用工具	把 Associate 的模型从 Gemini 换成 GPT-4，只需改一行 `model: gpt-4`
`core/agent_profiles/llm_configs/*.yaml`	统一管理 API key、base_url、温度	新增一个本地 Ollama 配置，复制粘贴即可
`core/agent_profiles/handover_protocols/*.yaml`	定义任务在 Agent 之间如何传递	让 Principal 把代码类任务交给“Coder” Associate，把写作任务交给“Writer” Associate

无需重启容器，YAML 保存后系统自动热加载。

7. 常见疑问 FAQ

以下问题全部整理自 README 及用户最可能的困惑。

Q1：一定要用 Google Gemini 吗？

A：不是。系统用 LiteLLM 做路由，只要 YAML 里写好 API key，就能用 OpenAI、Anthropic、本地 Ollama 等任何支持端点。

Q2：Docker 镜像多大？老电脑能跑吗？

A：主镜像大约 2 GB，第一次拉取需耐心。8 GB 内存的机器即可流畅运行。

Q3：我的 `.gemini` 目录在别的路径怎么办？

A：在 docker-compose.yaml 把 volumes 映射改成你真实路径即可。

Q4：如何添加自定义搜索工具？

A：

新建 core/agent_core/nodes/custom_nodes/my_search.py。
继承 BaseToolNode，用 @tool_registry 装饰。
在 YAML 的 tool_access_policy 里把新工具名字加进去。
无需重启，系统会自动发现。

Q5：项目文件太多会拖慢 RAG 吗？

A：官方已内置增量索引，只对新文件或改动文件做向量化，10 万级文件仍可秒级响应。

8. 下一步可以做什么？

实验不同团队配置：把“合伙人”换成法律专家提示，把“专员”拆成“法规研究员+财务分析师”，对比输出差异。
接入内部 API：用 MCP 协议把公司内网数据库暴露成工具，实现“私域知识”问答。
写技术博客：把你跑通的 YAML 配置、踩坑记录分享到社区，官方 Discord 频道会置顶优秀案例。
贡献代码：README 里的 CONTRIBUTING.md 已给出 Pull Request 规范，从文档 typo 修起也是一种贡献。

小结

Common Ground 把“黑盒 AI”变成了“透明团队”。
今天你就可以用 Docker 命令把整套系统跑起来，用 YAML 文件像调 Excel 表一样改 Agent 行为，用看板视图像盯项目一样盯 AI 进度。
剩下的，就是不断试验、记录、分享——让 AI 真正成为你工作中看得见、改得了、信得过的同事。

– END –

15分钟部署透明AI团队！Common Ground多智能体协作实战指南