beever-atlas

 Beever Atlas

自动将团队在 Slack、Discord、Teams 和 Mattermost 上的聊天
转化为可自我维护的 Wiki。

---

Beever Atlas 会获取团队在 Slack、Discord、Microsoft Teams 和 Mattermost 上已有的对话，提取原子事实、去重，并将其整理为带有引用的主题页面。图存储会关联不同频道中提及的人物、决策和项目。你可以用自然语言提问，并获得引用源消息的答案——既可以通过仪表板，也可以通过 MCP 在 Claude Code 和 Cursor 中提问。

如果你想要一个能根据团队现有聊天内容自动扩充的知识库，那就是它了。

---

✨ 功能演示

六段短视频——连接工作区、同步历史记录、查看记忆构建过程、浏览自动生成的 Wiki、提问，以及通过 MCP 接入外部 AI Agent。

多平台 连接 Slack、Discord、Teams、Mattermost，或导入文件。一个机器人，覆盖每个工作区。	消息同步 按需或按计划拉取频道历史记录。支持断点续传，并能应对速率限制。	记忆摄取 6 阶段 ADK 流水线将消息提炼为原子事实、实体和关系。
大模型 Wiki 每个频道都有自动维护的 Wiki，包含概览、主题、人员、决策和引用。	问答 Agent 通过 SSE 流式传输带引用的回答。智能路由器会针对每个问题选择语义检索或图检索。	MCP 服务 将 Claude Code / Cursor 接入你的知识库——28 个工具，按 Agent 进行身份验证。

---

🏗️ 架构

来自任何受支持平台的对话都会进入统一的摄取流水线，并生成两种互补的记忆系统——用于快速混合搜索的三层语义存储（频道 / 主题 / 原子事实），以及用于提取实体及其关系的图存储。这些记忆为两个使用入口提供支持：大模型 Wiki（经提炼并自动维护）和问答 Agent（可直接通过仪表板提供服务，也可通过 MCP 接入 Claude Code / Cursor）。

从聊天平台到 MCP Agent——一条摄取路径、两种记忆系统、两个交付入口。

在底层，三个服务（后端、机器人、前端）由四个数据存储（Weaviate、Neo4j、MongoDB、Redis）提供支持。完整设计请参阅文档网站上的架构概览，了解各组件的职责、双记忆系统的内部结构以及智能查询路由器。

---

💡 为什么选择以 Wiki 为先的 RAG？

大多数 RAG 系统通过检索原始消息片段，并将其直接提供给大模型来回答问题。Beever Atlas 采用了不同的方法：在发起任何查询之前，它会持续将对话提炼成一套结构化、自动维护的 Wiki，其中包含主题页面、实体图谱、决策和引用。提出问题时，检索层会基于干净、去重后的知识进行检索，而非嘈杂的聊天记录。这意味着答案更加一致，引用可追溯到源消息，而且 Wiki 本身也会成为一份实用资料，供团队独立于问答界面浏览。双记忆架构（语义 + 图谱）让查询路由器能针对每个问题选择合适的检索策略，从而降低延迟并确保上下文精准。

实时自动生成的频道 Wiki：概览、概念图、主题、常见问题、术语表——从 246 条 Slack 消息中提炼而成，并非手工编写。

灵感来源：大模型读取 Wiki，而非聊天记录

按频道划分 Wiki 的理念直接受到 Andrej Karpathy 的观点启发：与原始对话记录相比，大模型在经过整理的百科全书式内容（书籍、文档、Wiki）上进行推理的效果要好得多。聊天记录嘈杂、冗余、时间上分散，并且充满只有人类才能理清的隐含上下文。相比之下，Wiki 是这些知识已经提炼完成的形式——内容经过去重、结构化、附有引用，并按主题而非时间戳组织。

Beever Atlas 将这一理念付诸实践：每个同步的频道都有自己的自动生成、持续更新的 Wiki，包含主题、实体、决策、待解决问题和时间线等部分，并在新消息到达时增量重建。QA Agent 会优先从 Wiki 中检索，只有在某条事实尚未提炼时才回退到原始消息。

这在实践中带来的优势

• 答案更好，幻觉更少——检索基于事实密集、明确呈现实体关系的文本，而非零散的逐轮聊天记录。
• 引用可追溯——每条 Wiki 声明都链接回生成它的源消息，因此答案可以一路审计到原始 Slack/Discord/Teams 线程。
• 可供浏览的资料，而非只有问答框——Wiki 本身就很实用。加入频道的新队友可以阅读提炼后的 Wiki，而不必翻阅三个月的历史记录。
• 降低查询时的推理成本——成本高昂的提炼工作在摄取时只需执行一次。查询会命中精简、预先消化的上下文，而不是每次请求都重新总结原始日志。
• 具备图谱感知能力的推理——与 Wiki 一同构建的实体图谱，让查询路由器能够回答纯向量 RAG 难以处理的关系类问题（“谁和 Y 一起参与了 X？”）。

如需与其他大模型知识工具进行详细比较，请参阅文档站点上的比较页面。

---

🚀 快速开始

Beever Atlas 以 Docker Compose 栈形式提供（后端 + bot + Web + 4 个数据存储）。你可以在 30 秒内体验预置数据的演示，无需任何密钥，然后从三种部署选项中选择一种进行正式安装。

1. 获取代码

git clone https://github.com/beever-ai/beever-atlas.git
cd beever-atlas

2. 先试用演示（可选，预置数据无需密钥）

make demo

make demo 会启动完整的栈，并预加载公开的 Wikipedia 语料（Ada Lovelace + Python 历史）。预置数据使用预先计算好的固定数据，无需 API 密钥。通过 /api/ask 提问需要免费的 GOOGLE_API_KEY，因为 QA Agent 会调用 Gemini。curl 示例请参阅 demo/README.md。

如果你已准备好正式安装，可跳过此步骤。

3. 开始之前：获取 API 密钥

安装前需要准备两个免费密钥。两者都提供充足的免费额度，足以用于测试同步小型团队的频道。

密钥	用途	获取地址
GOOGLE_API_KEY	Gemini — 提取、实体图谱、答案	aistudio.google.com/apikey
JINA_API_KEY	用于语义搜索的 Jina v4 嵌入（2048 维）	jina.ai/api-dashboard

可选（除非确定需要，否则跳过）：

密钥	用途
TAVILY_API_KEY	QA 检索置信度较低时进行外部网页搜索 — tavily.com
OLOSTEP_API_KEY	Olostep 网页搜索（Tavily 的替代方案）。在 .env 中设置 WEB_SEARCH_PROVIDER=olostep — olostep.com/dashboard
Slack / Discord / Teams 机器人令牌	设置完成后通过 Web UI 配置，而非 .env — 机器人会将平台凭据加密后存储在 MongoDB 中

提示： 开始之前，请准备好两个必需的密钥。选项 1 会交互式提示输入；选项 2 和 3 则需要将密钥粘贴到 .env 中。

4. 选择部署选项

选项	适用场景	启动所需时间
1. 一行命令安装（推荐）	想要以最快方式启动整套服务。	首次运行约 2 分钟
2. 手动使用 Docker	CI/CD、运维环境，或希望明确控制每个步骤。	首次运行约 3 分钟
3. 本地开发	需要对后端和前端进行热重载的活跃贡献者。	时间不定

选项 1 — 一行命令安装（推荐）

./atlas

atlas 安装程序会引导你完成 5 步清单：

1. 嵌入模型 — 选择提供商（Jina / OpenAI / Cohere / Voyage / Gemini / Mistral / Ollama），然后输入其 API 密钥。
2. Agent 大模型提供商 — 为 16 个 ADK Agent 选择提供商（Google Gemini / OpenAI / Anthropic / Mistral / DeepSeek / Groq / MiniMax / Ollama / Custom）；混合配置可选第二个提供商。
3. 图谱后端 — 选择 Neo4j（默认），或跳过。
4. 可选集成 — Tavily 网页搜索、用于 Claude Code / Cursor 的 MCP 服务。
5. 身份验证令牌 — 保留开发环境默认值，或立即轮换。

在后台，它会验证 docker + docker compose，将 .env.example 复制为 .env（重新运行时保留现有值，并执行 chmod 600），自动生成 CREDENTIAL_MASTER_KEY（64 位十六进制）和 WEAVIATE_API_KEY（32 位十六进制），运行端口冲突预检，通过 docker compose up -d --build --force-recreate --remove-orphans 启动整套服务，并轮询 /api/health，之后显示就绪卡片。

看到 "Beever Atlas is ready" 后，打开 http://localhost:3000 — 然后前往 Settings → AI Setup 管理提供商、为每个 Agent 分配大模型、运行 Test Connection，或发现模型。对于 CI / Docker / GitOps，可通过声明式方式配置：BEEVER_LLM_API_KEY=...（单提供商快捷配置）、BEEVER_ENDPOINTS='[...]' + BEEVER_PRESET=...，或提交 atlas.yaml 并运行 atlas apply — 参见 docs/runbooks/ai-setup.md 和 docs/runbooks/atlas-yaml.md。

对于 CI 或无人值守安装 — 跳过提示，通过 Shell 环境变量预先设置密钥：

GOOGLE_API_KEY=... JINA_API_KEY=... ./atlas --non-interactive

在现有服务栈上重新运行 ./atlas 是幂等的。

选项 2 — 手动使用 Docker

完全掌控，逐步操作。

cp .env.example .env

打开 .env 并填写两个必需的密钥：

GOOGLE_API_KEY=your_gemini_key
JINA_API_KEY=your_jina_key

生成两个必需的密钥，并将它们粘贴到 .env 中：

# CREDENTIAL_MASTER_KEY — AES-256-GCM key for stored platform credentials (64 hex chars)
python -c "import secrets; print(secrets.token_hex(32))"

# WEAVIATE_API_KEY — auth between backend and Weaviate (required by docker-compose)
python -c "import secrets; print(secrets.token_hex(16))"

启动：

docker compose up -d --build

打开 http://localhost:3000。

已启动的服务：

服务	端口	描述
Web（nginx）	:3000	React 控制面板
后端	:8000	FastAPI + ADK Agent
Bot	:3001	平台桥接器（Slack / Discord / Teams）
Weaviate	:8080	语义记忆
Neo4j	:7474 / :7687	图记忆
MongoDB	:27017	状态 + wiki 缓存
Redis	:6380	会话（内部端口 :6379）

首次运行需要 2–3 分钟，用于构建镜像和初始化数据库。之后启动只需几秒钟。

选项 3 — 本地开发

数据库运行在 Docker 中，应用服务原生运行，以支持热重载。

先决条件： Python 3.12+ 和 uv，Node.js 20+

cp .env.example .env
# Fill in GOOGLE_API_KEY, JINA_API_KEY, CREDENTIAL_MASTER_KEY, WEAVIATE_API_KEY (same as Option 2)

# Start just the databases
docker compose up -d weaviate neo4j mongodb redis

# Backend (terminal 1)
uv sync
uv run uvicorn beever_atlas.server.app:app --reload --port 8000

# Bot (terminal 2)
cd bot && npm install && npm run dev

# Web (terminal 3) — Vite dev server with HMR
cd web && npm install && npm run dev

打开 http://localhost:5173（Vite 开发端口，不是 :3000）。

Vite 开发服务器会将 /api/* 代理到 http://localhost:8000（通过 VITE_API_URL 配置）。

上线前准备

.env.example 中的默认值适用于本地测试。任何正式部署前，请轮换使用占位值的密钥，并切换环境标志：

需要更改的内容	原因	方法
BEEVER_API_KEYS、BEEVER_ADMIN_TOKEN	默认值为 dev-key-change-me / dev-admin-change-me，属于公开占位值	每个令牌运行一次 python -c "import secrets; print(secrets.token_hex(24))"
BRIDGE_API_KEY	后端与 Bot 之间的共享密钥；默认为空，在本地开发环境之外必须设置	使用相同的 secrets.token_hex(24)
VITE_BEEVER_API_KEY、VITE_BEEVER_ADMIN_TOKEN	Vite 会在构建时将它们嵌入 Web 包中，必须与上方轮换后的后端值一致	复制轮换后的 BEEVER_API_KEYS / BEEVER_ADMIN_TOKEN 值
NEO4J_PASSWORD + NEO4J_AUTH 中的密码部分	此仓库中公开了开发密码	设置强密码；两个值必须一致
BEEVER_ENV=production	启用快速失败启动，并拒绝上述所有开发默认值	在 .env 中切换该值

选项 1（./atlas）会在检查清单第 4 步的 “Rotate auth tokens” 提示中处理所有这些操作——回答 Y，安装程序就会生成随机令牌，并为你同步 VITE_* 值。如果使用选项 2 或 3，可以在现有 .env 上重新运行 ./atlas，其他提示均按 Enter 跳过，只接受令牌轮换提示。

5. 打开控制面板

前往所选选项对应的网址：

• 选项 1 和 2 → http://localhost:3000
• 选项 3 → http://localhost:5173

然后：

• 真实模式（默认，ADAPTER_MOCK=false）：在 Settings → Connections 中连接工作区——通过界面输入 Slack / Discord / Teams 令牌，而不是写入 .env。
• 模拟模式（ADAPTER_MOCK=true）：使用固定样例数据，可选择启用，以便在没有平台凭据的情况下迭代本地界面。

6. 同步频道

在控制面板中：Connections → Add Workspace → Select channels → Sync。

或通过 API 操作（会从 .env 自动提取 bearer 令牌）：

curl -X POST http://localhost:8000/api/channels/C12345/sync \
  -H "Authorization: Bearer $(grep -E '^BEEVER_API_KEYS=' .env | cut -d= -f2 | cut -d, -f1)"

同步频道中分享的媒体（图片、PDF、视频）会持久保存，因此即使平台 CDN 链接过期后仍可正常显示。默认存储在数据库中，无需额外基础设施；大规模使用时也可选择 MinIO/S3。有关其机制、CHANNEL_MEDIA_* 配置、MinIO/S3 后端以及现有频道的回填，请参阅 docs/media-persistence.md。

MCP 服务（面向外部 AI Agent）

Beever Atlas 在 /mcp 提供精选的 MCP（Model Context Protocol）服务，供 Claude Code 和 Cursor 等 AI Agent 使用。外部编码助手无需使用仪表板，即可查询团队的知识库。

请参阅 docs/mcp-server.md，了解：

• 工具目录 — 28 个工具，涵盖发现、检索、Wiki 阅读、图遍历和长时间运行的操作
• 身份验证设置 — 生成和管理 BEEVER_MCP_API_KEYS
• 客户端配置 — 可直接使用的 Claude Code 和 Cursor .mcp.json 模板
• 速率限制 — 按主体密钥设定限制，防止某个 Agent 限制其他 Agent 的使用

它还提供独立的 stdio 模式（python -m beever_atlas.api.mcp_server / beever-atlas-mcp），无需 HTTP 服务或后端存储，即可提供相同的工具目录，适用于 MCP 注册表（Glama.ai）和本地检查。请参阅 docs/mcp-server.md。

快速示例（Claude Code）：

{
  "mcpServers": {
    "beever-atlas": {
      "url": "https://atlas.example.com/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer ${BEEVER_MCP_KEY}"
      }
    }
  }
}

常用命令

docker compose up -d                     # Start in background
docker compose logs -f beever-atlas      # Tail backend logs
docker compose down                      # Stop (keeps data)
docker compose down -v                   # Stop and DELETE all indexed data
make demo                                # Full stack + seeded demo corpus
make docker-up                           # Shortcut for `docker compose up -d`

---

🔒 隐私与遥测

Beever Atlas 不会收集任何遥测数据。默认情况下，不会向任何地方发送使用数据、错误报告或分析数据。所有大模型调用都通过你在自己的 .env 中配置的 API 密钥进行，所有数据都保留在你所控制的数据库中。

---

📐 API 稳定性

在 0.1.0 版本中，所有 /api/* 端点均为不稳定。v0.2.0 将引入 /api/v1/* 前缀；固定使用当前路径的客户端将无法继续使用。请参阅 SECURITY.md。

---

💬 社区与联系

• Discord：discord.gg/VshBCUUX — 获取帮助、分享你正在构建的项目，与团队交流
• X / Twitter：@Beever_AI — 发布说明、帖子和公告
• 网站：beever.ai — 了解公司和其他项目
• GitHub 讨论区：github.com/Beever-AI/beever-atlas/discussions — 进行较深入的问题交流和创意讨论

商务支持、合作或媒体联系：[email protected]。

---

📜 许可证

Apache License 2.0 © 2026 Beever Atlas 贡献者。第三方归属信息见 NOTICE。

安全政策：SECURITY.md | 社区准则：CODE_OF_CONDUCT.md