# 接入飞书机器人

在飞书私聊或群聊中使用数据智能体查询数据。

接上飞书后，同事不用登录 AskTable，在私聊里直接提问、或在群里 `@` 机器人，就能收到数据答案。机器人使用所绑定智能体的数据源、技能和能力配置。

AskTable 支持飞书和 [Slack](https://docs.asktable.com/integrations/slack)。一个智能体可以分别保存两种平台的配置，但同时只启用一个；切换平台或选择「不启用」都会保留已有配置，之后可以切回。

## 开始前

- AskTable 项目角色需要是「项目负责人」或「项目管理员」，并已有配好数据源的[数据智能体](https://docs.asktable.com/agent/overview)。
- 需要在飞书开放平台创建、配置和发布企业自建应用；应用须按企业要求完成审核。
- 先决定谁可以问数。频道白名单默认关闭，能联系机器人的用户都可提问；按人限制数据范围见[飞书用户权限](https://docs.asktable.com/permissions/feishu)。
- 私有部署需要运行频道网关，见[部署消息网关](https://docs.asktable.com/deploy/feishu-gateway)。SaaS 用户无需自行部署。

## 创建并发布飞书应用

**创建应用并启用机器人**

在[飞书开放平台](https://open.feishu.cn/)的开发者后台创建企业自建应用，填写名称、图标和描述。在「添加应用能力」里开启「机器人」，然后从「凭证与基础信息」记下 App ID 和 App Secret。

**设置长连接和事件订阅**

在「事件与回调」中选择长连接，订阅「接收消息 v2.0」（`im.message.receive_v1`）。AskTable 通过长连接收消息，不需要填写公网 Webhook 回调地址。

如果应用配置了 Encrypt Key 或 Verification Token，也记下对应值，接入 AskTable 时保持一致。

**开通消息和人员权限**

在「权限管理」中开通以下消息权限：

| 权限                                 | 用途               |
| ---------------------------------- | ---------------- |
| `im:message`                       | 接收与发送消息          |
| `im:message.group_at_msg:readonly` | 接收群组中 `@` 机器人的消息 |

按人限制数据范围时，还需要 `contact:user.employee_id:readonly`，让 AskTable 能取得用于人员匹配的飞书 user\_id。缺少这一权限时，开启白名单的频道会拒绝用户，且不能将其加入待审批。人员资料的其他权限要求见[飞书用户权限](https://docs.asktable.com/permissions/feishu)。

群内每次提问和追问都需要 `@` 机器人，无需开通读取全部群消息的权限。

**发布应用**

在「版本管理与发布」创建版本并按企业流程提交审核。发布后，把应用加入测试群，先完成一次提问验证。

## 在 AskTable 启用飞书

左侧主导航 →「更多」→ 打开目标智能体 →「频道」。在「平台」下拉框选择「飞书」。首次配置时会打开凭证弹窗：

| 字段                 | 要求                   |
| ------------------ | -------------------- |
| App ID             | 必填，形如 `cli_xxxxxxxx` |
| App Secret         | 必填，飞书应用密钥            |
| Encrypt Key        | 选填，与飞书后台配置一致         |
| Verification Token | 选填，与飞书后台配置一致         |

点「保存」后，飞书才成为当前生效的平台；取消弹窗会保留原来的平台选择。已有配置时，选择飞书会直接启用保存的配置。之后用「凭证配置」旁的「修改配置」更新凭证，编辑时会回填已有凭证，只需替换要更新的值；必填字段不能清空。不要把密钥放入截图或代码仓库。

### 调整回答方式

「通用配置」提供三个设置：

| 设置     | 飞书默认值        | 作用                                |
| ------ | ------------ | --------------------------------- |
| 在话题中回复 | 关闭           | 开启后，对群内的新提问在提问消息下开话题回复；关闭时直接回复在群里 |
| 深度推理   | 关闭           | 开启后给复杂分析更多推理时间                    |
| 渠道偏好   | 空，最多 1024 字符 | 例如“先给结论，使用简洁中文回答”                 |

两个开关修改后即时保存，渠道偏好在输入框失焦时保存。深度推理和渠道偏好对下一条消息生效，不需要用户重新开始对话。私聊始终直接回复，不另开话题。

### 设置人员权限

启用平台后，下方会出现「人员权限」。打开白名单并添加已授权人员，便可按人员绑定的角色限定数据范围。飞书和 Slack 的白名单开关分别保存。完整配置和待审批处理见[飞书用户权限](https://docs.asktable.com/permissions/feishu)。

## 检查连接，再发一条真实问题

「连接状态」每 5 秒自动刷新，也可以点「刷新」立即读取状态；刷新按钮本身不会重建连接。

| 状态  | 含义                 |
| --- | ------------------ |
| 已连接 | 当前频道的长连接处于正常状态     |
| 连接中 | 正在建立或恢复连接          |
| 未连接 | 当前没有可用连接           |
| 错误  | 建连或运行发生错误，查看状态旁的说明 |

网关心跳正常、状态显示已连接，都不能替代一次真实提问验证。向机器人发送问题后，看「最近消息」是否更新，再点「详情」分别检查处理状态与回复状态：处理完成表示分析环节完成，回复成功表示结果已投递到飞书。

建议依次验证：私聊提问、测试群内 `@` 提问、不同角色的人员提问。既要看到回复，也要确认结果处于各自授权的数据范围内。

## 在私聊、群和话题里提问

| 位置    | 操作                      |
| ----- | ----------------------- |
| 私聊    | 直接发送问题，例如“上个月各门店销售额是多少” |
| 群里    | `@机器人 上个月各门店销售额是多少`     |
| 话题内追问 | 仍要 `@机器人 按商品类别拆分`       |

一个话题的分析上下文属于最初提问者。其他人要继续自己的分析，应在群里另发一条提问；在别人的话题中 `@` 机器人时，会收到另起提问的提示。私聊和群内非话题问答按同一人复用会话，连续 24 小时没有新消息后重新开始；话题内的会话不会按这个 24 小时窗口过期。

群和话题中的回答对能查看该位置的成员可见。需要私下查看的结果，应通过私聊获取。

## 切换平台或停用

在「平台」下拉框选择 Slack 会切换生效平台；选择「不启用」会停止该智能体的频道连接。两种操作都保留凭证、偏好和权限设置，切回时可以继续使用。删除频道配置是另一项独立操作，不会因停用而自动发生。

## 出问题怎么判断

| 现象                                       | 检查什么                      | 处理                                        |
| ---------------------------------------- | ------------------------- | ----------------------------------------- |
| 一直连接中，或显示错误                              | 连接状态旁的错误说明                | 核对 App ID、App Secret、应用发布状态；私有部署确认频道网关已运行 |
| 保存提示必填项为空                                | 首次配置的 App ID 或 App Secret | 补齐凭证再保存                                   |
| 已连接但没有回复，最近消息也没变化                        | 机器人是否在群里、问题是否 `@`、事件是否订阅  | 核对机器人能力、应用发布和消息权限；先用私聊测试                  |
| 最近消息显示处理失败                               | 「详情」里的处理状态与原因             | 核对智能体数据源是否可用、用户是否有权限，再重试问题                |
| 最近消息显示回复失败                               | 「详情」里的回复状态与原因             | 核对机器人仍在目标群、发送消息权限有效；按具体平台错误处理             |
| 最近消息显示已忽略                                | 「详情」里的处理说明                | 核对消息是否属于当前机器人可受理的提问                       |
| 提示信息已提交待审批或未被授权                          | 人员绑定和智能体授权                | 到「人员」处理待审批，再在当前频道的「人员权限」中添加授权             |
| 提示缺少 `contact:user.employee_id:readonly` | 飞书应用未提供 user\_id          | 补权限并重新发布应用，再让用户提问                         |
| 提示智能体已删除或不可用                             | 频道绑定的智能体                  | 使用有效智能体重新配置接入，或选择「不启用」                    |
| 关闭白名单后其他人也能问数                            | 当前平台的白名单开关                | 如需限制人员，重新开启并补齐人员授权                        |

## 下一步

- 决定谁能问、谁能看到哪些数据：[飞书用户权限](https://docs.asktable.com/permissions/feishu)
- 按计划推送分析结论：[定时分析报告](https://docs.asktable.com/integrations/scheduled-reports)
- 另一种消息平台：[接入 Slack 机器人](https://docs.asktable.com/integrations/slack)