# 飞书机器人接入帮助

本文说明如何把飞书企业自建应用机器人接入 WeCom Proxy。飞书暂不支持像企业微信智能机器人一样由 proxy 扫码自动创建应用并取回 `App ID / App Secret`，因此飞书侧需要先在开放平台手动创建和配置应用。

## 一、整体流程

```text
飞书开放平台创建企业自建应用
  -> 开启机器人能力
  -> 配置事件订阅 URL / Verification Token / Encrypt Key
  -> 申请并发布所需权限
  -> 在 WeCom Proxy UI 中新增飞书机器人配置
  -> Agent 使用 robot_id + secret 订阅南向消息
```

## 二、飞书开放平台配置

### 1. 创建企业自建应用

1. 打开飞书开放平台，进入开发者后台。
2. 创建企业自建应用。
3. 在应用的「凭证与基础信息」页面记录：
   - `App ID`
   - `App Secret`

在 WeCom Proxy 中：

| 飞书字段 | WeCom Proxy 字段 |
| --- | --- |
| `App ID` | `Bot ID` |
| `App Secret` | `Secret` |
| 应用名称 / 机器人名称 | `名称` |
| 渠道 | `飞书` |

### 2. 开启机器人能力

在飞书应用后台开启机器人能力，并设置机器人名称、头像等基础信息。开启后，用户才能在飞书里私聊机器人或把机器人加入群聊。

### 3. 配置事件订阅

在应用后台进入「事件订阅」，配置请求地址：

```text
https://<你的 proxy 域名>/v1/feishu/events
```

如果你通过独立飞书服务暴露事件入口，请使用实际的 feishu-proxy 域名和路径。当前项目中飞书事件由 `feishu-proxy` / proxy 侧对应服务处理，最终消息会写入同一个消息库。

同时记录并配置：

| 飞书字段 | 说明 |
| --- | --- |
| `Verification Token` | 飞书事件回调校验 token。 |
| `Encrypt Key` | 如果飞书事件启用了加密，需要配置该 key 用于解密。 |

这些值通常放在服务 `.env` 中，而不是机器人配置表中。请确保运行飞书接入服务的实例能读取到这些环境变量。

### 4. 订阅事件

至少订阅即时消息接收事件：

```text
im.message.receive_v1
```

该事件用于接收用户私聊机器人、群里 @ 机器人等消息。接入后，proxy 会把飞书入站消息保存为 `feishu_ws` 来源，并按南向统一协议推送给已订阅该机器人的 Agent。

## 三、权限配置建议

飞书权限需要在开放平台申请，并在企业内发布 / 管理员审核后生效。不同飞书后台版本的权限名称可能略有调整，建议按能力搜索「消息」「机器人」「群组」「成员」等关键词。

### 必需权限

| 能力 | 用途 |
| --- | --- |
| 接收消息事件 | 接收私聊、群聊中发送给机器人的消息。 |
| 发送消息 | Agent 回复用户或群聊时，通过飞书 API 发送机器人消息。 |
| 获取 tenant access token | 使用 `App ID + App Secret` 换取应用访问令牌。 |

### 建议权限

| 能力 | 用途 |
| --- | --- |
| 读取群信息 | 在群信息页展示飞书群 ID、群类型等信息。 |
| 读取群成员信息 | 展示群成员、区分成员类型、维护更完整的上下文。 |
| 读取用户基础信息 | 把 open_id / user_id 展示成更友好的用户名称。 |

如果只做最小可用接入，可以先配置「接收消息事件」和「发送消息」相关权限；如果希望 UI 中群信息、成员列表更完整，再补充群和用户读取权限。

## 四、WeCom Proxy UI 中新增飞书机器人

进入「机器人配置」->「增加」：

1. 渠道选择：`飞书`
2. 名称：填写飞书机器人或应用名称。
3. Bot ID：填写飞书 `App ID`，例如 `cli_xxxxx`。
4. Secret：填写飞书 `App Secret`。
5. 心跳秒数：默认 `15` 即可。
6. 启用：保持勾选。
7. 保存。

保存后，南向 Agent 订阅时也必须使用同一组 `robot_id + secret`：

```json
{
  "cmd": "proxy.subscribe",
  "req_id": "sub-feishu-1",
  "body": {
    "robots": [
      {
        "robot_id": "cli_xxxxx",
        "secret": "飞书 App Secret"
      }
    ],
    "sources": ["feishu_ws", "feishu_send"]
  }
}
```

## 五、消息投递规则

飞书消息进入 proxy 后统一转换成南向结构：

| 场景 | 南向表现 |
| --- | --- |
| 用户私聊机器人 | `payload.chat.type = "single"` |
| 群里 @ 机器人 | `payload.chat.type = "group"` 且 `payload.mention.is_mentioned = true` |
| 群内普通消息 | 只有当飞书事件和权限允许收到该消息时才会进入 proxy；Agent 是否响应由业务策略决定。 |

建议 Agent 策略：

- 单聊：默认响应。
- 群聊且 @ 当前机器人：响应。
- 群聊但未 @ 当前机器人：只记录上下文，不主动响应。

## 六、联调检查

1. 在飞书开放平台确认应用已发布，权限已生效。
2. 确认事件订阅请求地址公网可访问，HTTPS 证书有效。
3. 在飞书中私聊机器人发送一条文本消息。
4. 在 WeCom Proxy UI 的「消息列表」中查看是否出现 `feishu_ws` 来源消息。
5. 打开消息详情，检查南向结构中的：
   - `payload.chat.type`
   - `payload.chat.id`
   - `payload.messages[].sender`
   - `payload.messages[].recipient`
   - `payload.mention.is_mentioned`
6. 启动 Agent，使用 `proxy.subscribe` 订阅该飞书机器人。
7. 再发一条消息，确认 Agent 收到南向推送并能回复。

## 七、常见问题

### UI 保存后收不到飞书消息

优先检查飞书开放平台事件订阅是否成功、应用是否发布、事件和权限是否已生效。只在 WeCom Proxy 中新增机器人配置，不会自动打开飞书事件推送。

### 群里 @ 机器人收不到

检查机器人是否已加入该群，以及飞书应用是否订阅了 `im.message.receive_v1`。部分权限或应用状态未生效时，私聊可能正常，但群聊事件不会推送。

### Agent 订阅失败

确认南向订阅使用的是飞书 `App ID`，不是 WeCom Proxy 内部自增 ID；`secret` 必须是对应应用的 `App Secret`。

### Agent 收到群消息但不该回复

Agent 应以南向字段为准判断：

```text
payload.chat.type == "group"
payload.mention.is_mentioned == true
```

推荐只在群聊且 `is_mentioned=true` 时回复，未 @ 时只做上下文记录。

## 八、官方参考

- 飞书开放平台文档：https://open.feishu.cn/document/
- 飞书服务端 API 文档：https://open.feishu.cn/document/server-docs/
- 飞书事件订阅文档：https://open.feishu.cn/document/server-docs/event-subscription-guide/
- 飞书消息事件文档：https://open.feishu.cn/document/server-docs/im-v1/message/events/receive