飞书集成

飞书集成通过 WebSocket 长连接 Hub 将飞书工作空间与 Mopheus 连通。配置完成后，智能体可实时响应飞书消息，所有从飞书聊天发起的工单也会在原聊天中接收状态变更和评论通知。

配置

1. 配置 Mopheus

在 设置 → 系统配置 中设置以下配置项：

配置并保存飞书应用凭据后，请勿修改飞书密钥。当前密钥用于解密已有凭据，修改后已有飞书安装将无法连接。 | 飞书域名 (lark_domain) | feishu.cn（默认，国内）或 larksuite.com（国际版 Lark） |

2. 注册安装记录

在工作区的 设置 → 集成 → 飞书 中，点击添加飞书集成，用飞书移动端扫描二维码授权安装。Mopheus 将加密存储 App 凭证，并启动与飞书事件推送服务的 WebSocket 长连接。

扫码授权安装不代表所有飞书用户都自动获得 Bot 使用权限。请在飞书开放平台发布应用，并配置应用的可用范围或租户授权范围，将需要使用 Bot 的用户加入其中。范围外用户可能会在飞书侧直接收到“Bot 对该用户不可用”等错误，消息不会到达 Mopheus。

3. 绑定飞书账号

每位需要与智能体聊天的飞书用户，须将飞书账号与 Mopheus 账号绑定。首次向 Bot 发消息时，Mopheus 会发送一次性绑定链接。点击链接，登录 Mopheus 即可完成绑定。绑定后，在飞书中发送的所有消息将以你的身份派发给分配的智能体。

飞书应用可用范围和 Mopheus 账号绑定是两个独立条件：用户需要先获得飞书应用的使用权限，再完成一次性 Mopheus 账号绑定。

飞书扫码登录（OAuth SSO）

除了 Bot 消息集成，Mopheus 还支持用飞书账号直接登录。启用后，登录页会显示飞书 / Lark 登录按钮。

前提条件

需要一个独立的飞书应用，专门用于 OAuth 登录（可与 Bot 应用分开，也可复用同一个应用）。

1. 在飞书开放平台创建应用

1. 前往 飞书开放平台 → 开发者后台 → 创建自建应用

2. 在应用的权限管理页面，开启以下权限：

   • contact:user.id:readonly（获取用户 open_id，必须）
   • contact:user.email:readonly（获取邮箱，用于与现有账号匹配，可选但推荐）

3. 在应用的安全设置页面，添加重定向 URL：

   • 生产环境：https://app.example.com/auth/lark/callback
   • 本地开发：http://localhost:3000/auth/lark/callback（飞书允许 localhost）

   填写前端地址（对应 app_url 配置项）。前端回调页面会通过 POST API 调用后端完成 code 换取。

4. 发布应用（自建应用通常可立即生效）

2. 配置 Mopheus

在 设置 → 系统配置 中设置：

配置完成后，登录页会自动显示"飞书 / Lark 登录"按钮，无需重启。

账号匹配规则

工作原理

入站：飞书 → Mopheus

飞书用户发送消息
        │
        ▼
飞书事件推送（im.message.receive_v1）
        │
        ▼
Mopheus WebSocket Hub（按安装记录独立维护）
        │
        ▼
Dispatcher：查找聊天会话和智能体
        │
        ├─ 未绑定 → 向用户发送绑定链接
        │
        └─ 已绑定 → 将任务加入智能体队列
                │
                ▼
           智能体运行，生成回复
                │
                ▼
           Patcher 将回复发回飞书聊天

聊天会话命名规则（会话标题始终为中文）

• 单聊（P2P）：与 {发送者名称} 的对话（发送者名称为空时回退为 飞书对话）
• 群聊：使用群组名称（如有），否则使用 飞书群聊

会话按（安装记录 ID、Chat ID）去重。若找到绑定行但会话已不存在，则自动创建新会话和绑定。

出站：Mopheus → 飞书

Patcher 组件负责所有出站消息，仅在 lark_enabled = true 时启用。

{前缀} 是从工作区 slug 自动派生的工单标识前缀（大写，最多 10 个字符；例如 slug 为 dba-team 时前缀为 DT）。评论会发送完整内容，不做截断。系统评论（如状态变更记录）不会推送——只推送普通评论。

工单通知

智能体在处理飞书聊天消息过程中创建工单时，Mopheus 会将发起聊天的 Session 和不可变的来源消息记录在工单 Metadata 中（channel_chat_session_id、channel_chat_message_id）。此后该工单的每次状态变更和普通评论都会引用创建该工单的原始飞书消息，而不会引用会话最后一条消息。早于该来源消息锚点的工单会降级为聊天级通知。普通消息的建单结果只由智能体完成回复发送；/ticket 还会先发送即时的命令确认。

当 /ticket 命令包含附件时，Mopheus 会先等待附件完成存储，再派发该工单任务。附件下载失败时，工单会新增一条说明失败原因的普通评论并回传到原飞书消息，随后取消该任务。纯文本 /ticket 命令会立即派发。

智能体任务（ChatSessionID 已设置）
        │
        ▼
智能体调用 POST /tickets（携带 X-Quick-Create-Agent-Task-ID 请求头）
        │
        ▼
服务端将 channel_chat_session_id 和 channel_chat_message_id 写入 ticket.metadata
        │
        ▼
工单状态变更或新增评论
        │
        ▼
Patcher 引用创建工单的原始飞书消息发送通知

该流程适用于以下两种场景：

• 快速创建任务：智能体的直接输出就是工单
• 普通聊天任务：智能体在处理过程中按需创建工单

消息格式

纯文本回复（未检测到 Markdown 语法）：以 msg_type=text 发送，在飞书中显示为普通 IM 消息。

Markdown 回复（包含加粗、代码块、标题、链接等）：以 msg_type=interactive 的互动卡片发送，卡片中包含 markdown 元素，由飞书客户端渲染格式。它不是飞书的 msg_type=markdown 消息。

错误卡片：以红色互动卡片呈现，标题显示智能体名称，正文显示错误详情。

流式输出：当前不会持续更新同一张互动卡片。系统会在任务完成后一次性发送最终回复；处理期间只显示处理中提示。

常见问题