007sanju/CrisisLoop

# Slack 入门 Agent（Bolt for Python 和 OpenAI Agents SDK） 一个极简的入门模板，用于结合 [Bolt for Python](https://docs.slack.dev/tools/bolt-python/) 和 [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/)，并使用 [OpenAI](https://openai.com) 的模型来构建 AI 驱动的 Slack agent。与 [Slack MCP Server](https://github.com/slackapi/slack-mcp-server) 配合使用，可以直接在你的 agent 内部搜索消息、读取频道、发送消息以及管理画布。 ## 应用概述 入门 agent 通过四个入口点与用户进行交互： * **App Home** — 显示欢迎消息以及交互说明。 * **直接消息** — 用户直接向 agent 发送消息。它会在会话线索内回复，并在后续交流中保持上下文。 * **频道 @提及** — 在任意频道中提及 agent，无需离开当前对话即可获得回复。 * **助手面板** — 用户在 Slack 中点击 _添加 Agent_，选择该 agent，然后从建议的提示词中选择或输入消息。 该模板还包含一个示例工具（表情符号回应）。你可以添加自己的工具，以针对你的使用场景进行自定义。 ### Slack MCP Server 当连接到 [Slack MCP Server](https://github.com/slackapi/slack-mcp-server) 时，agent 可以搜索消息和文件、读取频道历史记录和会话线索、发送和定时发送消息，以及创建和更新画布。当使用 OAuth（HTTP 模式）部署时，agent 会使用用户的 token 自动连接到 Slack MCP Server。 ## 设置 在开始之前，请确保你拥有一个具有安装应用权限的开发工作区。 ### 开发者计划 加入 [Slack 开发者计划](https://api.slack.com/developer-program)，独家获取用于构建和测试应用的沙箱环境、工具以及旨在帮助你构建和成长的资源。 ### 创建 Slack 应用

使用 Slack CLI

根据你的操作系统安装最新版本的 Slack CLI： - [macOS 和 Linux 版 Slack CLI](https://docs.slack.dev/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux/) - [Windows 版 Slack CLI](https://docs.slack.dev/tools/slack-cli/guides/installing-the-slack-cli-for-windows/) 如果是首次使用 Slack CLI，你还需要进行登录。 ``` slack login ``` #### 初始化项目 ``` slack create my-starter-agent --template slack-samples/bolt-python-starter-agent --subdir openai-agents-sdk cd my-starter-agent ```

使用应用设置

#### 创建你的 Slack 应用 1. 打开 [https://api.slack.com/apps/new](https://api.slack.com/apps/new) 并选择“From an app manifest” 2. 选择你要安装应用的工作区 3. 将 [manifest.json](./manifest.json) 的内容复制到显示 `*Paste your manifest code here*` 的文本框中（在 JSON 标签页下），然后点击 _Next_ 4. 检查配置并点击 _Create_ 5. 点击 _Install to Workspace_，并在接下来的页面中点击 _Allow_。随后你将被重定向到应用配置仪表板。 #### 环境变量 在运行应用之前，你需要存储一些环境变量。 1. 将 `.env.sample` 重命名为 `.env`。 2. 从[此列表](https://api.slack.com/apps)打开你的应用设置页面，在左侧菜单中点击 _OAuth & Permissions_，然后复制 _Bot User OAuth Token_ 并将其粘贴到 `.env` 文件中的 `SLACK_BOT_TOKEN` 下方。 ``` SLACK_BOT_TOKEN=YOUR_SLACK_BOT_TOKEN ``` 3. 从左侧菜单点击 _Basic Information_，按照 _App-Level Tokens_ 部分中的步骤创建一个具有 `connections:write` scope 的应用级 token。将该 token 复制到 `.env` 中作为 `SLACK_APP_TOKEN`。 ``` SLACK_APP_TOKEN=YOUR_SLACK_APP_TOKEN ``` #### 初始化项目 ``` git clone https://github.com/slack-samples/bolt-python-starter-agent.git my-starter-agent cd my-starter-agent ```

### 设置你的 Python 虚拟环境 ``` python3 -m venv .venv source .venv/bin/activate # for Windows OS, .\.venv\Scripts\Activate instead should work ``` #### 安装依赖 ``` pip install -r requirements.txt ``` ## 提供商 ### OpenAI 设置 此应用通过 OpenAI Agents SDK 使用 OpenAI 的 `gpt-4.1-mini` 模型。 1. 从你的 [OpenAI dashboard](https://platform.openai.com/api-keys) 创建 API 密钥。 2. 将 `.env.sample` 重命名为 `.env`。 3. 将 OpenAI API 密钥保存到 `.env`： ``` OPENAI_API_KEY=YOUR_OPENAI_API_KEY ``` ## 开发 ### 启动应用

使用 Slack CLI

#### Slack CLI ``` slack run ```

使用终端

#### 终端 ``` python3 app.py ```

使用 OAuth HTTP 服务器（配合 ngrok）

#### OAuth HTTP 服务器 此模式使用 HTTP 服务器代替 Socket Mode，这是基于 OAuth 的分发所必需的。 1. 安装 [ngrok](https://ngrok.com/download) 并启动隧道： ``` ngrok http 3000 ``` 2. 从 ngrok 输出中复制 `https://*.ngrok-free.app` URL。

使用 Slack CLI

#### Slack CLI 3. 为 HTTP 模式更新 `manifest.json`： - 将 `socket_mode_enabled` 设置为 `false` - 将 `ngrok-free.app` 替换为你的 ngrok 域名（例如 `YOUR_NGROK_SUBDOMAIN.ngrok-free.app`） 4. 创建一个新的本地开发应用： ``` slack install -E local ``` 5. _（仅限 Slack CLI < v4.1.0）_ 为你的应用启用 MCP： - 运行 `slack app settings` 打开应用设置 - 在左侧导航中找到 **Agents & AI Apps** - 开启 **Model Context Protocol** 6. 更新 `.env` 中的 OAuth 环境变量： - 运行 `slack app settings` 打开应用设置 - 复制 **Client ID**、**Client Secret** 和 **Signing Secret** - 使用你的 ngrok 域名更新 `.env` 中的 `SLACK_REDIRECT_URI` ``` SLACK_CLIENT_ID=YOUR_CLIENT_ID SLACK_CLIENT_SECRET=YOUR_CLIENT_SECRET SLACK_SIGNING_SECRET=YOUR_SIGNING_SECRET SLACK_REDIRECT_URI=https://YOUR_NGROK_SUBDOMAIN.ngrok-free.app/slack/oauth_redirect ``` 7. 启动应用： ``` slack run app_oauth.py ``` 8. 点击终端中打印的安装 URL，通过 OAuth 将应用安装到你的工作区。

使用终端

#### 终端 3. 使用 [`manifest.json`](./manifest.json) 在 [api.slack.com/apps/new](https://api.slack.com/apps/new) 创建你的 Slack 应用。在粘贴清单之前，将 `socket_mode_enabled` 设置为 `false`，并将 `ngrok-free.app` 替换为你的 ngrok 域名。 4. 将应用安装到你的工作区，并将以下值复制到你的 `.env` 中： - **Signing Secret** — 来自 _Basic Information_ - **Bot User OAuth Token** — 来自 _OAuth & Permissions_ - **Client ID** 和 **Client Secret** — 来自 _Basic Information_ ``` SLACK_BOT_TOKEN=xoxb-YOUR_BOT_TOKEN SLACK_CLIENT_ID=YOUR_CLIENT_ID SLACK_CLIENT_SECRET=YOUR_CLIENT_SECRET SLACK_SIGNING_SECRET=YOUR_SIGNING_SECRET SLACK_REDIRECT_URI=https://YOUR_NGROK_SUBDOMAIN.ngrok-free.app/slack/oauth_redirect ``` 将 `SLACK_REDIRECT_URI` 中的 `your-subdomain` 替换为你的 ngrok 子域名。 5. 启动应用： ``` python3 app_oauth.py ``` 6. 点击终端中打印的安装 URL，通过 OAuth 将应用安装到你的工作区。

### 使用应用 agent 运行后，有多种交互方式： **App Home** — 在 Slack 中打开 agent 并点击 _Home_ 标签。你会看到一条包含交互说明的欢迎消息。 **直接消息** — 与 agent 打开一个 DM。你会看到诸如 _写一条消息_、_总结_ 和 _头脑风暴_ 等建议提示词——选择其中一个或输入你自己的消息。agent 会在会话线索中回复。在同一会话线索中发送后续消息，agent 将保持完整的对话上下文。 **频道 @提及** — 通过在消息框中输入 `/invite @agent-name` 将 agent 邀请到频道，然后 @提及它并附上你的消息。agent 会在会话线索中回复，从而保持频道整洁。 **助手面板** — 在 Slack 右上角点击 _添加 Agent_，从列表中选择该 agent，然后选择一个建议的提示词或输入消息。 ### Linting ``` # 在根目录运行 ruff check 进行 linting ruff check # 在根目录运行 ruff format 进行代码格式化 ruff format ``` ## 项目结构 ### `manifest.json` `manifest.json` 是 Slack 应用的配置文件。通过 manifest，你可以使用预定义的配置创建应用，或者调整现有应用的配置。 ### `app.py` `app.py` 是应用程序的入口点，也是你运行以启动服务器的文件。本项目旨在让此文件尽可能轻量，主要将其作为路由入站请求的一种方式。 ### `app_oauth.py` `app_oauth.py` 是一个替代入口点，它以 HTTP 模式而不是 Socket Mode 运行应用。这适用于使用 OAuth 进行应用分发的部署。有关设置说明，请参阅开发部分下的 HTTP 模式部分。 ### `/listeners` 每个传入的请求都会被路由到一个“监听器”。此目录根据所使用的 Slack Platform 功能对每个监听器进行分组。 **`/listeners/events`** — 处理传入事件： - `app_home_opened.py` — 发布带有欢迎消息和 MCP 状态的 App Home 视图。 - `app_mentioned.py` — 回复频道中的 @提及。 - `message.py` — 回复来自用户的直接消息。 **`/listeners/actions`** — 处理交互组件： - `feedback_buttons.py` — 处理对 agent 回复的赞成/反对反馈。 **`/listeners/views`** — 构建 Block Kit 视图： - `app_home_builder.py` — 构建 App Home 的 Block Kit 视图。 - `feedback_builder.py` — 创建附加到回复的反馈按钮块。 ### `/agent` `agent.py` 文件定义了 OpenAI Agents SDK Agent 及其系统提示词、个性和工具配置。 `deps.py` 文件定义了在运行时传递给 agent 的 `AgentDeps` 数据类，提供对 Slack client 和对话上下文的访问。 `tools` 目录包含一个示例工具（表情符号回应），agent 可以在对话期间调用它。 ### `/thread_context` `store.py` 文件实现了一个线程安全的内存对话历史记录存储，以频道和会话线索为键。这使得多轮对话成为可能，agent 能够记住会话线索中之前的上下文。 ## 故障排除 ### MCP Server 连接错误：`HTTP error 400 (Bad Request)` 如果你看到如下错误： ``` Failed to connect to MCP server 'streamable_http: https://mcp.slack.com/mcp': HTTP error 400 (Bad Request) ``` 这意味着你的应用尚未启用 Slack MCP 功能。目前还没有用于此设置的 manifest 属性，因此必须手动开启： 1. 运行 `slack app settings` 打开你的应用设置页面（或访问 [api.slack.com/apps](https://api.slack.com/apps) 并选择你的应用） 2. 在左侧导航中找到 **Agents & AI Apps** 3. 开启 **Slack Model Context Protocol**

标签：Bolt框架, OpenAI, Slack机器人, 内存规避, 协同工具, 运维, 逆向工具