# Slack 与频道

将 Slack 连接到项目，并从频道控制会话。

Canonical page: https://beeuni.ai/docs/zh/connect/slack

频道用于将聊天平台连接到项目。在已连接的频道中发送消息会启动一个[会话](/docs/zh/work/sessions)。智能体会在同一话题串中回复。

<a id="live-channels"></a>

## 目前支持的频道

Beeuni 目前支持四种频道平台：

- **Slack** — 通过 Beeuni 管理的应用一键连接，或使用你自己的机器人令牌。
- **Microsoft Teams** — 通过组织管理员同意的 OAuth 连接，或使用你自己的 Azure Bot（实验性功能；可在[Settings → Feature flags](/docs/zh/feature-flags)中启用）。
- **电子邮件** — 由 AgentMail 提供支持的频道（实验性功能；可在[Settings → Feature flags](/docs/zh/feature-flags)中启用）。
- **语音** — 实时语音频道（实验性功能；可在[Settings → Feature flags](/docs/zh/feature-flags)中启用）。与 Agent 进行实时语音对话。

只有 Slack 和 Microsoft Teams 可通过 CLI 和控制面板连接。电子邮件和语音需在控制面板中管理。本页介绍 Slack。Teams 遵循相同的会话、身份关联和凭据规则。

<a id="how-a-channel-starts-a-session"></a>

## 频道如何启动会话

Slack 话题串或 Teams 对话中的第一条消息会创建一个会话。即使沙盒停止后又恢复，该话题串仍会保留此会话。

在 Slack 频道中，之后的消息只有在提及机器人时才会发送给会话。未标记机器人的回复是给话题串中其他人的。下次有人提及机器人时，智能体会读取这些回复。在私信中，每条消息都会发送给会话。

一个 Slack 工作区连接到多个项目时，首次提及时会显示项目选择器。

<a id="identity-linking"></a>

## 身份关联

在智能体为聊天发送者运行之前，Beeuni 会先将每位发送者关联到一个 Beeuni 账户。在 Slack 中运行 `/beeuni login`，然后通过链接登录。Teams 也有同样的要求。未关联的发送者会收到关联提示，而不会启动会话。

登录链接只能使用一次，并会在 10 分钟后过期。已连接到一个 Beeuni 账户的 Slack 账户无法再连接到其他账户：请先运行 `/beeuni logout`。如果你的组织要求双重身份验证，Beeuni 会在连接你之前要求你提供第二重验证信息，聊天操作也会以你用于连接的验证方式运行。

每项操作都以执行者所关联的账户身份运行，并遵循该账户的项目角色。账户所有者和管理员视为项目管理员。

| 操作 | 谁有权执行 |
|---|---|
| 在新消息或其话题串中提及机器人 | 有权访问该项目的已关联账户，且须遵守频道策略 |
| 停止一次运行 | 发送了当前回复所针对消息的人，或已获准加入该会话且仍可使用此项目的任何人 |
| 更改频道的项目、智能体、模型或策略 | 项目管理员；在与机器人的私信中，任何项目成员均可 |
| 处理审核项 | 项目管理员 |
| 批准或拒绝连接器调用 | 项目管理员，或启动会话的人 |
| 批准某人加入 `owner_approval` 话题串 | 会话所有者 |
| `link-bot` | 项目管理员 |

<a id="where-credentials-live"></a>

## 凭据存放位置

已连接频道的机器人令牌是连接器范围的[密钥](/docs/zh/project/secrets)。它不会显示在项目的 Secrets 页面中。Beeuni 绝不会将它注入沙盒。智能体发送或读取聊天消息时，Beeuni 会在服务器端解析该令牌。

<a id="connect-slack"></a>

## 连接 Slack

### 开始连接
在 CLI 中运行：

```
beeuni channels connect
```

在配置了共享 Slack 应用的主机上（例如 Beeuni Cloud），此命令会显示一键安装链接。打开链接并选择工作区。点击 **Allow**。添加 `--wait`，让命令持续轮询，直到安装完成。

也可以在控制面板中打开项目的 Channels 页面，然后在那里连接 Slack。使用的是相同的安装流程。

<a id="use-your-own-slack-app"></a>

### 使用自己的 Slack 应用

若要使用自己的 Slack 应用，请运行 `beeuni channels manifest` 以输出应用清单。根据该清单，在 `api.slack.com/apps` 创建应用。将应用安装到工作区。然后运行：

```
beeuni channels connect --manual --bot-token xoxb-... --signing-secret ...
```

### 检查连接
```
beeuni channels status
```

运行 `beeuni channels disconnect` 以移除连接。所有标志请参阅 [CLI 参考](/docs/zh/cli)。

连接 Slack 后，Beeuni 会为你在 `beeuni.yaml` 添加一条 `channel` [连接器](/docs/zh/connect/connectors)条目。你无需手动编写此条目。

<a id="use-slack"></a>

## 使用 Slack

在机器人已加入的任意频道中提及机器人并附上任务，或打开一条私信。话题串会按上述说明保留会话。在频道话题串中再次提及机器人即可继续对话。若只提及机器人但未提供任务，它会提醒你补充任务，而不会启动会话。

<a id="what-the-agent-can-read"></a>

## 智能体可以读取的内容

智能体通过项目的 Slack [连接器](/docs/zh/connect/connectors)读取 Slack（`beeuni_slack`，或沙盒中的 `slack` 命令）。连接到同一 Slack 工作区的每个项目都使用同一个机器人，因此 Beeuni 会将每次读取限制在各项目自己的对话中：

| 对话 | 读取权限 |
|---|---|
| 连接到此项目的频道或私信 | 允许 |
| 此项目的会话在任意频道中启动或加入的话题串 | 允许 |
| 其他项目的频道、私信或话题串 | 拒绝 |
| 未连接到任何项目的对话 | 仅当工作区尚未连接其他项目时允许 |

读取被拒绝时，`403` 会返回原因 `conversation_not_in_project`，并显示包含对话名称的消息。若要读取尚未连接到任何项目的对话，请先连接：在其中运行 `/beeuni switch`，然后选择此项目。

- 频道历史记录不会包含其他项目话题串中的消息。
- `get_history` 和 `get_thread` 会为每条作者身份可由 Slack 确认的消息添加 `user_name`，并显示在 `user` ID 旁边。每次读取最多标注 25 人；Slack 在 2 秒内未返回姓名的用户会被略过。
- `list_channels` 会列出所有公开频道，以及智能体可读取的私密频道和私信。
- `channel_info` 会对任何公开频道作答。私密频道或私信遵循上表规则。
- 当文件分享在智能体可读取的对话或此项目的话题串中时，`file_info` 会作答。`slack download` 遵循相同规则：如果文件只分享在其他项目的对话中，则会对 `403` 作答。下载大小上限为 50 MB，超出时会对 `413` 作答。
- `search_messages` 只会在工作区未连接其他项目时运行，因为搜索无法限制在某个项目的对话范围内。
- `list_users`、`user_info` 和 `auth_test` 会读取工作区目录，不受限制。

写入操作遵循下文的独立规则。

<a id="what-the-agent-can-post"></a>

## 智能体可以发布的内容

发布消息、发送文件、编辑、删除、添加反应、加入频道和绑定话题串都遵循同一规则：智能体绝不会在其他项目的频道或话题串中操作。

| 目标 | 写入权限 |
|---|---|
| 此项目的频道，或其会话启动或加入的话题串 | 允许 |
| 未连接到任何项目的频道 | 允许。新消息会在此项目中启动一个话题串，因此提及机器人的回复会回到该会话 |
| 与某人的私信 | 允许，即使该人与机器人的私信正在运行其他项目也允许 |
| 其他项目的频道或群组私信 | 拒绝 |
| 任意对话中属于其他项目的话题串 | 拒绝：无法回复、编辑、删除或添加反应 |

写入被拒绝时，`403` 会返回原因 `conversation_not_in_project`，并显示包含对话名称的消息。`slack send --file` 和 `slack bind-thread` 遵循相同规则。

`channel` 必须是对话 ID 或用户 ID，例如 `C0123ABCD` 或 `U0123ABCD`，而不是频道名称。Slack 会按名称发布消息，而名称无法通过规则检查。如果 Slack 最终将消息发布到已检查的对话以外的位置，Beeuni 会删除该消息并拒绝发布。

若要在由其他项目运行的频道中发布消息，请在其中运行 `/beeuni switch` 并选择此项目，或从那个项目发布。

<a id="control-a-session-with-slash-commands"></a>

## 使用斜杠命令控制会话

在 Slack 中将这些命令作为 `/beeuni <command>` 输入，或在私信中作为纯文本输入。斜杠命令无法在 Assistant 私信面板中运行，因此 Beeuni 会在其中解析相同的纯文本内容。

| 命令 | 功能 |
|---|---|
| `login`、`logout` | 关联或取消关联你的 Slack 身份 |
| `switch`、`unbind` | 重新绑定或解除此频道与其项目的绑定 |
| `projects` | 列出你可以绑定到的项目 |
| `sessions` | 列出此工作区中最近启动的会话 |
| `whoami` | 显示频道面板：项目、智能体、模型、策略和你已关联的身份 |
| `models` | 为此频道选择模型 — 请参阅[模型和密钥](#models-and-keys) |
| `agent <name>`、`model <id>` | 设置此频道使用的智能体或模型 |
| `policy <mode>` | 设置谁可以在此处启动会话 |
| `help` | 列出所有命令 |

`policy` 接受 `project_open`（默认值 — 任何提及机器人的项目成员都会启动会话）、`owner_approval` 或 `owner_only`。这是针对单个频道的资源级设置，不是角色。它不会授予角色判定所拒绝的任何权限 — 请参阅[账户与访问权限](/docs/zh/accounts#per-feature-access-settings)。

<a id="models-and-keys"></a>

## 模型和密钥

`/beeuni models` 会列出你可以在此处运行的所有模型，与网页选择器相同：Beeuni 模型，以及通过提供商 API 密钥或 ChatGPT 订阅使用的模型。每个模型都会注明付费方式。列表较长时，你可以在单个选择框中输入搜索。选择一个模型，或输入 `/beeuni model <id>`；`/beeuni model default` 会恢复为项目默认值。

哪些密钥可用取决于对话类型：

- **与机器人的私信** — 你自己的密钥和 ChatGPT 订阅，以及与项目共享的密钥。该会话仅你可见。
- **频道或群组私信** — 仅限与整个项目共享的密钥。若要使用基于个人密钥运行的模型，请改在私信中选择。

基于密钥运行的模型会使用你可使用的该提供商的所有密钥，并在触发速率限制时轮换密钥。频道的模型会用于启动每个新话题串；话题串会继续使用启动时的模型。如果某个话题串无法再运行原模型，则会为该条消息替换模型，而不会直接失败。请参阅[提供商密钥与成员访问权限](/docs/zh/project/models#provider-keys-and-member-access)。

包含图像的后续消息会使用能够读取图像的模型运行。如果可用模型都无法读取图像，提示词中会告知智能体这一点：它会说明自己无法查看图像，并要求提供文字，而不是猜测。

<a id="channel-and-people-names"></a>

## 频道和人员名称

Slack 会发送 ID，例如 `C0123ABCD` 和 `U0123ABCD`。Beeuni 会显示 Slack 用户看到的名称，并在操作时使用 ID。

| 位置 | 显示内容 |
|---|---|
| Channels 页面、`beeuni channels bindings` | 公开或私密频道的 `#channel`、私信的联系人、群组私信的成员 |
| 会话中的 Slack 消息 | 发送者的姓名和 `#channel` |
| 会话中的 `slack send` 回复 | `#channel`，或私信中的联系人 |
| 会话标题 | 按 Slack 显示方式呈现提及：`@Beeuni`，而非 `<@U0123ABCD>` |
| 智能体的提示词 | ID 旁的名称：`Sam Rivera (U0123ABCD)`、`#general (C0123ABCD)` |
| 智能体在 Slack 中的计划步骤 | 人员显示为 `@Sam Rivera`，频道显示为 `#general`。步骤不会通知任何人 |
| Slack 中的审批卡片 | 频道参数显示为频道链接，名称取决于你自己的访问权限。用户参数显示为该用户的姓名 |

Slack 无法找到的频道会显示为 **Unavailable channel**，并保留其 ID。如果频道已被删除或机器人已被移除，就会发生这种情况。Slack 在 2 秒内未返回的名称会从该消息中略去。提示词将只包含 ID，而且该轮处理不会等待。

<a id="approvals"></a>

## 审批

智能体需要人工决定才能继续时，会提交一个审核项。如果会话是从此话题串启动的，决定事项会以卡片形式显示在这里，其中包含标题、摘要、风险等级以及 **Approve**、**Request changes** 和 **Deny**。

**Request changes** 会打开一个输入框，让你填写需要更改的内容。你输入的内容会随决定一并保存并传给智能体，因此智能体无需再次询问。此项可选 — 留空发送后，智能体会被告知需要询问。批准和拒绝仍只需点击一次。

处理审核项需要关联的 Beeuni 账户具有项目写入权限。

<a id="stopping-a-run"></a>

## 停止运行

智能体工作时，其实时消息上会显示 **Stop** 按钮。此按钮会在运行时终止运行，而不只是停止消息显示 — 如果运行仍处于打开状态，它会吞掉话题串中的下一条消息，而不是回复。

发送了当前回复所针对消息的人可以停止运行；已获准加入该会话且仍可使用此项目的人也可以停止。频道中的旁观者无法停止运行；他们会收到一条私密提示，告知其没有权限。

<a id="what-does-not-work"></a>

## 无法使用的功能

- 斜杠命令无法在 Assistant 私信面板中触发。请改为在其中输入纯文本 `/beeuni <command>`。
- 目前不支持 Telegram 等其他聊天平台作为频道。只有 Slack 和 Microsoft Teams 可通过 CLI 和控制面板连接；电子邮件和语音需通过控制面板连接。