飞书接入

将旗鱼接入飞书后，你可以在飞书中直接与 AI Agent 对话。飞书支持卡片消息格式，回复的排版效果是所有 IM 平台中最好的。

前置条件

• 飞书账号（个人版或企业版均可）
• 飞书开放平台的应用创建权限

配置步骤

第 1 步：创建飞书应用

1. 打开 飞书开放平台
2. 点击「创建企业自建应用」
3. 填写以下信息：
   • 应用名称：如「旗鱼助手」
   • 应用描述：如「AI 智能助手，帮你管理服务器和处理日常任务」
   • 应用图标：上传一个图标
4. 点击创建

第 2 步：获取凭证

在应用的「凭证与基础信息」页面，记录下：

请妥善保管这些凭证。

第 3 步：配置事件订阅

这是最关键的步骤，必须选择长连接方式：

1. 进入「事件与回调」→「事件配置」
2. 加密策略选择开启
3. 在「订阅方式」中选择 「使用长连接接收事件」

⚠️ 必须选择长连接方式。如果选择了回调 URL 方式，需要公网可访问的地址，配置更复杂。长连接方式由旗鱼主动连接飞书服务器，无需公网 IP。

第 4 步：添加权限与事件

添加权限（在「权限管理」中）：

添加事件（在「事件与回调」中）：

第 5 步：先连接旗鱼（关键顺序）

⚠️ 飞书要求应用在发布前必须先建立长连接。所以要先在旗鱼中配置好凭证并成功连接，然后再去飞书平台提交发布。

1. 打开旗鱼 → 设置 → 即时通讯
2. 展开「飞书」卡片
3. 填入 App ID 和 App Secret
4. 点击「连接」
5. 等待状态变为 ✅「已连接」

如果状态长时间显示「连接中」，检查 App ID 和 App Secret 是否正确，以及事件订阅是否选择了长连接方式。

第 6 步：发布应用

1. 回到飞书开放平台
2. 进入「应用发布」→「版本管理与发布」
3. 创建一个新版本
4. 设置可用范围（可选全员或指定部门/人员）
5. 提交审核

个人版飞书通常会自动通过审核。企业版可能需要管理员审批。

第 7 步：启用机器人

1. 在「应用能力」→「机器人」中开启机器人功能
2. 填写机器人名称和描述

开始使用

私聊

在飞书中搜索你的机器人名称（如「旗鱼助手」），点击打开对话，直接发送文字消息。

群聊

1. 将机器人添加到飞书群组中
2. 在群里 @旗鱼助手 后输入消息
3. 机器人会在群内回复

消息格式

飞书的回复使用交互卡片格式，这是所有 IM 平台中排版效果最好的：

• 标题、正文、代码块都有良好的排版
• 表格能正确渲染
• 链接可点击
• 代码块有语法高亮

Agent 也可以直接发送文件到聊天中（30MB 以内），在所有 IM 平台中文件大小限制也是较宽松的。

使用示例

你: 检查一下 Web 服务器的运行状况
Agent: [飞书交互卡片]
       🖥 服务器状态报告
       ─────────────────
       CPU: 32.1% | 内存: 8.5GB/16GB
       磁盘: /data 67% | 网络: 正常
       nginx: ✅ 运行中 | MySQL: ✅ 运行中
       
       最近 1 小时无错误日志

常见问题

连接状态一直是”连接中”

• 确认 App ID 和 App Secret 正确无误
• 确认事件订阅选择了「使用长连接接收事件」（不是回调 URL）
• 检查网络是否能访问飞书服务器

应用审核不通过

• 确认已添加所有必需权限（第 4 步）
• 确认应用已先成功建立长连接再提交审核（第 5 步必须在第 6 步之前）
• 检查审核拒绝原因，补充对应信息

机器人不回复

• 确认应用已发布且审核通过
• 确认旗鱼连接状态为「已连接」
• 群聊中需要 @机器人
• 检查旗鱼的 AI 模型配置是否正常

消息格式显示不正常

• 确认使用的是最新版本的飞书客户端
• 卡片消息在旧版本客户端上可能降级为纯文本显示