> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用飞书连接器查询日程并整理当天安排

> 连接飞书账号，为智能体配置日历查询能力，按日期和时区整理会议安排并识别时间冲突。

开始一天的工作前，你可能需要确认今天有哪些会议、什么时候开始，以及是否存在时间冲突。通过飞书连接器，可以让 Xpert 中的智能体读取已授权日历，将日程整理成时间表，并指出已查询事件之间的重叠时段。

本教程以“查询一天的会议安排”为例，带你完成飞书授权、智能体配置和一次实际查询，再用几条测试日程核对结果。

## 完成本教程后，你可以

* 让智能体查询已授权飞书账号可访问的指定日历。
* 按日期和时区列出会议名称、开始时间和结束时间。
* 找出已查询日程之间的时间重叠。
* 在同一个工作区中，让其他已配置相应能力的智能体复用现有连接。

本教程中的任务只读取日程并整理结果，不要求创建、修改或取消会议。

## 开始前的准备

| 准备事项          | 如何确认                                              |
| ------------- | ------------------------------------------------- |
| 正确的 Xpert 工作区 | 进入本次使用智能体所在的工作区，并具备连接器管理权限                        |
| 可运行的智能体       | 已配置可用模型，能够在 Xpert 中正常对话；可以是 ClawXpert，也可以是其他业务智能体 |
| 飞书连接器         | 工作区的连接器目录中可以看到“飞书”                                |
| 用于授权的飞书账号     | 该账号能够在飞书中查看目标日历和需要查询的事件                           |
| 日历读取权限        | 应用和用户授权包含本次日历查询所需的权限                              |
| 智能体运行环境       | 已准备可用沙箱和“沙箱命令行工具”，能够运行飞书配套工具并访问飞书服务               |

运行环境通常由管理员配置。日常使用者只需在智能体对话中提出查询需求。

> 本教程使用工作区中的团队连接。查询使用的是连接器已授权的飞书账号，不会因提问者不同而自动切换为各自的个人账号。首次查询前，请先确认要使用谁的账号、查询哪一个日历。

## 第一步：连接飞书账号

进入目标 **工作区 → 连接器**，找到 **飞书**卡片并点击 **连接**。首次连接需要完成应用授权和用户授权两个阶段。

### 完成应用授权

1. 在打开的飞书授权页面中扫码或登录。
2. 按平台页面完成应用相关设置和授权确认。
3. 返回 Xpert 查看连接状态。

完成应用授权后，连接器可能仍显示 **待处理**，此时需要继续完成用户授权。

### 完成用户授权

1. 如果授权页面没有进入下一阶段，返回飞书连接器卡片，点击 **继续授权**。
2. 使用本次要用于查询日历的账号，完成用户授权确认。
3. 等待 Xpert 中的连接状态变为 **已连接**。
4. 打开连接详情，核对已连接账号。

“已连接”说明连接器授权已经完成。目标日历是否可访问、事件是否可以读取，还需要通过后面的查询进行验证。

如果浏览器没有打开授权页，检查是否拦截了弹窗，允许当前站点打开授权窗口后重试。

## 第二步：为智能体配置飞书连接器

连接账号后，需要让实际执行任务的智能体加载飞书能力。如果管理员已经完成这部分配置，可以直接进行下一步。

1. 打开目标智能体的 **Studio／编排页面**。
2. 在画布添加菜单中选择 **添加中间件 → 连接器**。
3. 在中间件的 **连接器**字段中选择 **飞书**。
4. 将该中间件关联到实际执行任务的智能体节点。
5. 为同一个智能体配置可用沙箱和 **沙箱命令行工具**。
6. 保存并发布智能体，然后打开它的对话页面。

管理员还应确认沙箱能够运行 Node，并完成飞书配套命令工具和相关能力的准备。日常使用者无需手动输入命令或粘贴访问令牌。

连接器授权本身不要求重新发布智能体；本步骤修改了智能体的能力配置，因此需要保存并发布。

## 第三步：明确日期、时区和日历范围

为了得到可核对的结果，查询前应明确三项信息：

| 信息   | 示例                 | 为什么需要                  |
| ---- | ------------------ | ---------------------- |
| 查询日期 | 2026 年 9 月 25 日    | 避免“今天”“明天”在不同时间执行时产生歧义 |
| 时区   | 北京时间，Asia/Shanghai | 确保查询范围和展示时间使用同一时区      |
| 日历范围 | “连接器测试日历”          | 避免把单个日历的结果当成账号全部日程     |

下面的操作使用 **2026 年 9 月 25 日**作为示例。实际使用时，请替换为你要查询的日期和日历名称。

如果日历名称重复，可以请管理员提供准确的日历标识；智能体无法确定目标时，应先确认范围，再执行查询。

## 第四步：查询日程并整理时间表

在配置好的智能体对话中发送：

```text theme={null}
请使用飞书连接器，查询已授权账号可访问的“连接器测试日历”。

查询日期：2026 年 9 月 25 日。
时区：Asia/Shanghai（北京时间）。
范围：当天 00:00 至次日 00:00，包含与该时间范围相交的有效日程。

请完成以下事项：
1. 在结果开头说明实际查询的日期、时区和日历。
2. 按开始时间排列，列出会议名称、开始时间和结束时间。
3. 标明跨日或全天事件；重复日程以当天实际发生的安排为准。
4. 指出已查询日程中的时间冲突，列出冲突事件及重叠时段。
5. 若无权限、查询失败或未能读取完整结果，请明确说明。

此次只查询，不创建、修改、取消日程，也不发送会议邀请。
```

智能体应调用飞书能力读取实际日程，再根据返回内容整理结果。仅回复“我可以帮你查询”还没有完成任务。

### 预期结果示例

假设测试日历中存在以下三条日程，结果可以整理为：

\*\*查询范围：\*\*2026 年 9 月 25 日，Asia/Shanghai，“连接器测试日历”。

| 会议     | 开始时间  | 结束时间  | 时间关系       |
| ------ | ----- | ----- | ---------- |
| 产品例会   | 09:00 | 10:00 | 与客户方案沟通重叠  |
| 客户方案沟通 | 09:30 | 10:30 | 与产品例会重叠    |
| 项目进度同步 | 14:00 | 15:00 | 与表内其他事件无重叠 |

\*\*冲突说明：\*\*产品例会与客户方案沟通在 **09:30—10:00** 重叠，共 30 分钟。

以上为示例数据，用于说明输出形式，不代表已经读取了你的日历。

### 如何理解冲突结果

时间冲突由已读取事件的起止时间判断。例如，09:00—10:00 与 09:30—10:30 存在重叠；09:00—10:00 与 10:00—11:00 仅首尾相接，不属于时间重叠。

全天事件和跨日事件应单独标明，结合事件性质判断是否影响安排。若某个事件只允许查看忙闲状态，结果应保留这一限制，不推测会议标题和详情。

“没有发现冲突”只针对本次已成功读取的日历和事件，不代表其他未查询日历、不可见事件中也没有冲突。

## 第五步：结合结果整理当天安排

收到时间表后，可以继续提出整理要求：

```text theme={null}
请根据刚才已经查到的日程，整理一份简短的当天安排：
先列出需要处理的时间冲突，再按上午、下午列出会议。
只给出文字建议，不修改原日程。
```

智能体可以根据已查询的结果组织建议，例如提醒你先协调上午两场重叠会议，再列出下午的安排。

如果查询后日历内容发生变化，可以明确要求重新查询：

```text theme={null}
日程刚有调整，请重新查询同一个日期和日历，并更新冲突判断。
```

读取连接器不会自动开启持续同步或定时提醒。再次查询时，应让智能体重新读取需要更新的数据。

## 验证查询是否正确

建议先选择一个测试日历，由有权限的人员在飞书中手动准备三条测试日程，再执行查询。准备测试数据与智能体的查询任务是两个独立步骤。

| 测试日程   | 示例时间        | 用途           |
| ------ | ----------- | ------------ |
| 产品例会   | 09:00—10:00 | 验证基础事件读取     |
| 客户方案沟通 | 09:30—10:30 | 验证 30 分钟重叠识别 |
| 项目进度同步 | 14:00—15:00 | 验证独立日程及排序    |

核对以下结果：

* 实际查询的账号和日历与准备的测试对象一致。
* 日期和时区正确，起止时间与飞书中看到的一致。
* 三条日程均出现在结果中，没有遗漏或重复。
* 两场上午会议的重叠时段为 09:30—10:00。
* 下午会议没有被误判为与上午会议冲突。
* 飞书中的日程内容保持不变，没有新增邀请或修改操作。

如果实际业务需要查询全天事件、跨日事件、重复日程或多个日历，应分别补充对应测试。数据较多时，还要确认查询覆盖完整范围，而不是只读取了部分结果。

## 在其他智能体中复用

同一工作区已经连接飞书后，可以为“日程助理”“项目助理”等其他智能体添加飞书连接器能力，配置运行环境并发布，再使用现有授权执行查询。

复用时仍需满足工作区成员权限和外部日历权限。切换为另一个智能体，不会自动切换连接器授权账号。

如果从项目中运行智能体，需要在该项目中配置相应连接器；项目任务不会自动借用工作区的同名连接。

## 常见问题

### 飞书扫码完成后，为什么仍显示待处理

可能只完成了应用授权。返回连接器卡片，点击 **继续授权**完成用户授权，直到显示“已连接”。

### 已连接，但智能体提示无法使用飞书

检查目标智能体是否添加了飞书连接器中间件，是否关联到实际执行节点，以及修改后是否发布。再检查沙箱、沙箱命令行工具、配套工具准备和网络连接。

### 查询到的不是我自己的日程

查看连接详情中的已授权账号。本教程采用团队连接，获准使用者共用当前授权，并不会自动使用每个人自己的飞书身份。同时检查是否指定了正确的日历。

### 飞书中有会议，查询结果却为空

先核对日期、时区、账号和日历，再检查应用与用户权限、目标日历的共享范围。还应区分“查询成功且没有事件”和“请求失败或无权访问”，不能把失败结果解释为当天没有安排。

### 能看到忙闲，为什么没有会议名称

当前账号可能只有忙闲可见权限。请有权限的管理员确认日历共享范围和所需授权，再进行查询。已有忙闲信息不能用于推测受限会议的标题或内容。

### 为什么会议时间与飞书界面不同

检查智能体输出、查询参数和飞书界面使用的时区是否一致。建议明确使用 **Asia/Shanghai**，并在结果中显示具体日期；跨日事件还需要同时显示开始与结束日期。

### 提示授权过期或权限不足

由连接器管理员检查授权状态，按提示重新连接或补齐需要的权限。完成后重新执行一项已知可访问的日程查询，确认实际读取已经恢复。

## 相关文档

* [智能体中间件](/zh-Hans/ai/middleware/index)
* [沙箱](/zh-Hans/ai/agent/sandbox/index)
* [发布版本](/zh-Hans/ai/agent/release-version)