Slack集成设置指南

Slack 集成设置指南

本指南提供了与 LEANN 进行 Slack 集成的逐步说明。

概述

LEANN 的 Slack 集成使用 MCP（模型上下文协议）服务器来获取并索引您的 Slack 消息，以便进行 RAG（检索增强生成）。这使您能够通过自然语言查询搜索您的 Slack 对话。

先决条件

1. Slack 工作区访问权限：您需要在 Slack 工作区中拥有管理员或所有者权限，以创建应用并配置 OAuth 令牌。

2. Slack MCP 服务器：安装一个 Slack MCP 服务器（例如，通过 npm 安装 slack-mcp-server）

3. LEANN：确保您已安装并正常运行 LEANN

步骤 1：创建 Slack 应用程序

1.1 访问 Slack API 控制台

1. 访问 https://api.slack.com/apps
2. 点击“创建新应用”
3. 选择“从头开始”
4. 输入您的应用名称（例如，“LEANN Slack 集成”）
5. 选择您的工作区
6. 点击“创建应用”

1.2 配置应用权限

令牌范围

1. 在您的应用控制台中，转到左侧边栏的“OAuth 和权限”
2. 向下滚动到“范围”部分
3. 在“机器人令牌范围和 OAuth 范围”下，点击“添加 OAuth 范围”
4. 添加以下范围：
   • channels:read - 读取公共频道信息
   • channels:history - 读取公共频道中的消息
   • groups:read - 读取私有频道信息
   • groups:history - 读取私有频道中的消息
   • im:read - 读取直接消息信息
   • im:history - 读取直接消息
   • mpim:read - 读取群组直接消息信息
   • mpim:history - 读取群组直接消息
   • users:read - 读取用户信息
   • team:read - 读取工作区信息

应用级令牌（可选）

一些 MCP 服务器可能需要应用级令牌：

1. 转到左侧边栏的“基本信息”
2. 向下滚动到“应用级令牌”
3. 点击“生成令牌和范围”
4. 输入名称（例如，“LEANN 集成”）
5. 添加 connections:write 范围
6. 点击“生成”
7. 复制令牌（以 xapp- 开头）

1.3 将应用安装到工作区

1. 转到左侧边栏的“OAuth 和权限”
2. 点击“安装到工作区”
3. 查看权限并点击“允许”
4. 复制“机器人用户 OAuth 令牌”（以 xoxb- 开头）
5. 复制“用户 OAuth 令牌”（以 xoxp- 开头）

步骤 2：安装 Slack MCP 服务器

选项 A：使用 npm（推荐）

# Install globally
npm install -g slack-mcp-server

# Or install locally
npm install slack-mcp-server
​

选项 B：使用 npx（无需安装）

# Use directly without installation
npx slack-mcp-server
​

步骤 3：安装并配置 Ollama（用于真实 LLM 响应）

3.1 安装 Ollama

# Install Ollama using Homebrew (macOS)
brew install ollama

# Or download from https://ollama.ai/
​

3.2 启动 Ollama 服务

# Start Ollama as a service
brew services start ollama

# Or start manually
ollama serve
​

3.3 拉取模型

# Pull a lightweight model for testing
ollama pull llama3.2:1b

# Verify the model is available
ollama list
​

步骤 4：配置环境变量

创建一个 .env 文件或设置环境变量：

# Required: User OAuth Token
SLACK_OAUTH_TOKEN=xoxp-your-user-oauth-token-here

# Optional: App-Level Token (if your MCP server requires it)
SLACK_APP_TOKEN=xapp-your-app-token-here

# Optional: Workspace-specific settings
SLACK_WORKSPACE_ID=T1234567890  # Your workspace ID (optional)
​

步骤 5：测试设置

5.1 测试 MCP 服务器连接

python -m apps.slack_rag \
  --mcp-server "slack-mcp-server" \
  --test-connection \
  --workspace-name "Your Workspace Name"
​

这将测试连接并列出可用工具，而不会索引任何数据。

5.2 索引特定频道

python -m apps.slack_rag \
  --mcp-server "slack-mcp-server" \
  --workspace-name "Your Workspace Name" \
  --channels general \
  --query "What did we discuss about the project?"
​

5.3 真实 RAG 查询示例

本节展示了针对 Sky Lab Computing 工作区“random”频道的成功 Slack RAG 集成查询。系统成功检索了实际对话消息，并进行了语义搜索，获得了高相关性得分，包括找到特定的研究论文公告和技术讨论。

示例 1：顾问模型查询

查询：“训练黑盒模型以适应您的个人数据”

此查询展示了系统查找关于训练黑盒模型以适应个人数据的具体研究公告的能力。

示例 2：蛮族来袭查询

查询：“AI驱动的研究系统 ADRS”

此查询展示了系统查找关于 AI 驱动的研究系统和算法发现的具体研究公告的能力。

先决条件

• 机器人已安装在 Sky Lab Computing 工作区，并被邀请加入目标频道（如果需要，在频道中运行 /invite @YourBotName）
• 机器人令牌可用并在同一终端会话中导出

命令

1. 设置此 shell 的工作区令牌

export SLACK_MCP_XOXP_TOKEN="xoxp-***-redacted-***"
​

2. 根据频道 ID（C0GN5BX0F）对“random”频道执行查询

顾问模型查询：

python -m apps.slack_rag \
  --mcp-server "slack-mcp-server" \
  --workspace-name "Sky Lab Computing" \
  --channels C0GN5BX0F \
  --max-messages-per-channel 100000 \
  --query "train black-box models to adopt to your personal data" \
  --llm ollama \
  --llm-model "llama3.2:1b" \
  --llm-host "http://localhost:11434" \
  --no-concatenate-conversations
​

蛮族来袭查询：

python -m apps.slack_rag \
  --mcp-server "slack-mcp-server" \
  --workspace-name "Sky Lab Computing" \
  --channels C0GN5BX0F \
  --max-messages-per-channel 100000 \
  --query "AI-driven research systems ADRS" \
  --llm ollama \
  --llm-model "llama3.2:1b" \
  --llm-host "http://localhost:11434" \
  --no-concatenate-conversations
​

这些示例展示了系统从对话历史中查找和检索具体研究公告和技术讨论的能力，彰显了 Slack 数据中语义搜索的强大功能。

3. 可选：提出更广泛的问题

python test_channel_by_id_or_name.py \
  --channel-id C0GN5BX0F \
  --workspace-name "Sky Lab Computing" \
  --query "What is LEANN about?"
​

注意：

• 如果看到 not_in_channel, invite the bot to the channel and re-run.
• If you see channel_not_found，请确认频道 ID 和工作区。
• 通过服务器端“搜索”工具进行深度搜索可能需要额外的 Slack 范围；上述示例是在客户端对检索到的历史记录进行过滤。

常见问题及解决方案

问题 1：“users cache is not ready yet” 错误

问题：您看到此警告：

WARNING - Failed to fetch messages from channel random: Failed to fetch messages: {'code': -32603, 'message': 'users cache is not ready yet, sync process is still running... please wait'}
​

解决方案：这是一个常见的时序问题。LEANN 集成现在包含自动重试逻辑：

1. 等待并重试：系统会自动以指数退避方式重试（2s、4s、8s 等）
2. 增加重试参数：如果需要，您可以自定义重试行为：

   python -m apps.slack_rag \
     --mcp-server "slack-mcp-server" \
     --max-retries 10 \
     --retry-delay 3.0 \
     --channels general \
     --query "Your query here"
   ​

3. 保持 MCP 服务器运行：单独启动 MCP 服务器并保持运行：

   # Terminal 1: Start MCP server
   slack-mcp-server
   
   # Terminal 2: Run LEANN (it will connect to the running server)
   python -m apps.slack_rag --mcp-server "slack-mcp-server" --channels general --query "test"
   ​

问题 2：“没有找到消息获取工具”

问题：MCP 服务器没有预期的工具。

解决方案：

1. 检查您的 MCP 服务器是否正确安装并配置
2. 确认您的 Slack 令牌是否正确
3. 尝试不同的 MCP 服务器实现
4. 检查 MCP 服务器文档以了解所需配置

问题 3：权限被拒绝错误

问题：尝试访问频道时出现权限错误。

解决方案：

1. 检查机器人权限：确保您的机器人已被添加到您想要访问的频道
2. 验证令牌范围：确保您已配置所有必需的范围
3. 频道访问：对于私有频道，机器人需要被明确邀请
4. 工作区权限：确保您的 Slack 应用拥有必要的工作区权限

问题 4：空结果

问题：即使频道中有消息，也没有返回任何消息。

解决方案：

1. 检查频道名称：确保频道名称正确（不带 # 符号）
2. 验证机器人访问权限：确保机器人可以访问这些频道
3. 检查日期范围：一些 MCP 服务器对消息历史有限制
4. 增加消息限制：尝试增加消息限制：

   python -m apps.slack_rag \
     --mcp-server "slack-mcp-server" \
     --channels general \
     --max-messages-per-channel 1000 \
     --query "test"
   ​

高级配置

自定义 MCP 服务器命令

如果您需要向 MCP 服务器传递额外参数：

python -m apps.slack_rag \
  --mcp-server "slack-mcp-server --token-file /path/to/tokens.json" \
  --workspace-name "Your Workspace" \
  --channels general \
  --query "Your query"
​

多个工作区

要处理多个 Slack 工作区，您可以：

1. 为每个工作区创建独立的应用
2. 使用不同的环境变量
3. 运行不同配置的独立实例

性能优化

为了在大型工作区中获得更好的性能：

python -m apps.slack_rag \
  --mcp-server "slack-mcp-server" \
  --workspace-name "Your Workspace" \
  --max-messages-per-channel 500 \
  --no-concatenate-conversations \
  --query "Your query"
​

排除故障清单

• Slack 应用已创建并拥有正确权限
• 机器人令牌（xoxb-）复制正确
• 如需，已创建应用级令牌（xapp-）
• MCP 服务器已安装并可访问
• Ollama 已安装并运行（brew services start ollama)
• Ollama model pulled (ollama pull llama3.2:1b)
• Environment variables set correctly
• Bot invited to relevant channels
• Channel names specified without # symbol
• Sufficient retry attempts configured
• Network connectivity to Slack APIs

Getting Help

If you continue to have issues:

1. Check Logs: Look for detailed error messages in the console output
2. Test MCP Server: Use --test-connection to verify the MCP server is working
3. Verify Tokens: Double-check that your Slack tokens are valid and have the right scopes
4. Check Ollama: Ensure Ollama is running (ollama serve) and the model is available (ollama list）
5. 社区支持：联系 LEANN 社区寻求帮助

示例命令

基本用法

# Test connection
python -m apps.slack_rag --mcp-server "slack-mcp-server" --test-connection

# Index specific channels
python -m apps.slack_rag \
  --mcp-server "slack-mcp-server" \
  --workspace-name "My Company" \
  --channels general random \
  --query "What did we decide about the project timeline?"
​

高级用法

# With custom retry settings
python -m apps.slack_rag \
  --mcp-server "slack-mcp-server" \
  --workspace-name "My Company" \
  --channels general \
  --max-retries 10 \
  --retry-delay 5.0 \
  --max-messages-per-channel 2000 \
  --query "Show me all decisions made in the last month"
​

免责声明：
本文档采用基于机器的 AI 翻译服务进行翻译。尽管我们力求准确，但请注意，自动翻译可能存在错误或不准确之处。应以原文语言版本的文档作为权威依据。如需获取关键信息，建议使用专业的人工翻译。对于因使用本翻译而产生的任何误解或误读，我们概不负责。