# 飞书智能体入会旁听

> 把这篇文档链接发给你的 AI Agent，它会按步骤帮你把接入跑通。

# 一、功能说明

开启旁听模式后，你的 Agent 可以以 **你的身份** 实时获取会议内容 —— 字幕和会中聊天同步可见，你在会里听到什么，它就听到什么。

**会议里不会出现任何机器人**，其他参会者感知不到 Agent 的存在。

**可以做** | 实时获取字幕、会中聊天、参会人进出情况
---|---
**不支持** | 实时推送（需轮询拉取）；在会上发声
**适合场景** | 会议纪要、议程追踪、实时问答助手、背后支援型 Agent

# 二、准备工作

1. **创建飞书应用**
进入[飞书开放平台](https://open.feishu.cn/)，创建企业自建应用，获取 `App ID` / `App Secret`。

3. **申请权限并完成用户授权**：

需要的权限：`vc:meeting.meetingevent:read`（用户身份权限）。
    申请时 **数据权限范围** 选「按条件筛选」→ 会议的归属者 → 包含 → 选择 「与应用可用范围一致」，权限变更后重新发布。

> **[Agent 操作]**
    > 
    > **第一阶段**（立即返回授权链接，发给用户）：
    > 
    > ```bash
    > lark-cli auth login --scope "vc:meeting.meetingevent:read" --no-wait --json
    > ```
    > 
    > 从输出拿到 `verification_url` 和 `device_code`，把 `verification_url` 用代码块原样发给用户，等用户点击完成授权。
    > 
    > **第二阶段**（用户完成授权后执行）：
    > 
    > ```bash
    > lark-cli auth login --device-code <device_code_from_step1>
    > ```

4. **版本要求**：
    - 飞书客户端升级到 **7.68+**（飞书 → 头像 → 关于飞书 → 检查更新）

- lark-cli 升级到 **v1.0.55+**：`npm install -g @larksuite/cli@latest`

5. **会议开启「允许智能体入会」**：

- 每场会议由 **owner** 在 **安全设置** 里打开该开关。
    - 若找不到该选项，**先打开「AI 总结」**，再返回查看。
    - 该开关仅对灰度范围内账号可见。

![image.png](//sf3-cn.feishucdn.com/obj/open-platform-opendoc/4f79a52ecd33a55787a177d1eb9dceaf_LN3z7Flzq7.png?height=1638&lazyload=true&maxWidth=500&width=2240)

# 三、接入流程

```
用户本人在飞书会议中
    ↓
Agent 调用 GetUserActiveMeeting → 拿到 meeting_id
    ↓
Agent 调用 ListMeetingEvents 拉取会中事件（字幕、聊天等）
    ↓
Agent 通过飞书 IM 将分析结果发给用户
```

**lark\-cli 示例：**

```bash
# 查询用户当前所在会议
lark-cli vc +meeting-list-active --as user

# 拉取会中事件（首次全量，后续用 page_token 增量）
lark-cli vc +meeting-events --as user --meeting-id <meeting_id> --page-all
```

> **关键约束**：
> - UAT 场景无实时推送，需要轮询拉取。
> - 用户必须本人在会中，且会议已开「允许智能体入会」。

# 四、API 参考

## GetUserActiveMeeting — 获取用户活跃会议

`GET /open-apis/vc/v1/bots/user_active_meeting`

返回用户当前所在的会议列表，每项含 `meeting_id`、`meeting_no`、`meeting_title`。有多个会议时让用户选一个。详情参考 [获取用户活跃会议](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/vc-v1/bot/user_active_meeting)。

## ListMeetingEvents —  获取会议事件

`GET /open-apis/vc/v1/bots/events`

获取会议中的事件列表，包括参会人加入或离开、发言、聊天、共享等事件。详情参考[获取会议事件](https://open.larkoffice.com/document/uAjLw4CM/ukTMukTMukTM/reference/vc-v1/bot/events)。

# 五、事件数据结构

通过 ListMeetingEvents 返回的事件，按 `activity_event_type` 区分类型。

## 字幕 transcript_received_items

```json
{
  "speaker": { "id": "xxx", "user_type": 1, "user_name": "张三" },
  "text": "今天来讨论一下这个方案",
  "language": "zh-CN",
  "start_time_ms": "1716699012000",
  "end_time_ms": "1716699014000",
  "sentence_id": "100001"
}
```

`user_type` 可能为声纹检测类型（100/101/102），需兼容处理。

## 聊天消息 chat_received_items

```json
{
  "operator": { "id": "xxx", "user_name": "张三" },
  "message_id": "om_xxx",
  "message_type": 1,
  "content": "大家好",
  "send_time": "1716699030000"
}
```

`message_type`：1=文本，2=系统，3=表情，4=加密。

## 参会人进入 participant_joined_items

```json
{
  "participant": { "id": "xxx", "user_type": 1, "user_role": 1, "user_name": "张三" },
  "join_time": "1716699010000"
}
```

## 参会人离开 `participant_left_items`

```json
{
  "participant": { "id": "xxx", "user_name": "张三" },
  "leave_reason": 1,
  "leave_time": "1716700000000"
}
```

`leave_reason`：1=主动离会，2=会议结束，3=被踢出。

# 六、排查清单

|问题|原因|解决方案|
|---|---|---|
|拉事件报无权限|用户不在会，或会议未开「允许智能体入会」|确认用户在会中且开关已开|
|meeting\_id 用错|用了 9 位会议号|用 GetUserActiveMeeting 查到的长 ID|
|拿不到实时字幕|旁听模式无推送|正常，需轮询调 ListMeetingEvents|