飞书集成

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

配置Copy Anchor Link

支持接收语音消息（audio），使用消息中的 file_key 按文件资源下载并保存为附件，不会自动转录语音。接口说明见飞书资源下载文档。

1. 配置 MopheusCopy Anchor Link

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

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

2. 注册安装记录Copy Anchor Link

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

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

群聊信息权限Copy Anchor Link

当前集成在应用拥有 im:chat:read 权限时可以读取群聊名称，但暂时不能主动查看群聊消息或上下文。若需要读取群聊消息或群聊上下文，请为飞书应用增加 im:message.group_msg 权限：

1. 打开飞书开放平台，进入对应的自建应用。
2. 打开 权限管理，搜索 im:message.group_msg 或“获取群聊中所有消息”。
3. 添加并保存该权限。
4. 在应用版本中发布权限变更；如果应用已经安装，请重新完成应用授权或更新应用配置。
5. 回到 Mopheus，确认飞书集成使用的是更新后的应用授权。

没有该权限时，Mopheus 仍可处理正常推送到 Bot 的消息，但不能主动查询群聊中的其他消息。

3. 绑定飞书账号Copy Anchor Link

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

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

飞书扫码登录（OAuth SSO）Copy Anchor Link

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

前提条件Copy Anchor Link

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

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

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. 配置 MopheusCopy Anchor Link

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

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

账号匹配规则Copy Anchor Link

Lark CLI 的平台存储Copy Anchor Link

Lark CLI 的应用配置与用户凭据分开保存。下面将 Mopheus 个人运行时配置模板中的两个条目合并列出：

用户授权凭据和 App Secret 存储在 keychain，不在 config.json 中：

macOS 和 Windows 上，仅复制 config.json 不会迁移用户登录状态。目标设备配置好应用后，需要重新运行 lark-cli auth login。

工作原理Copy Anchor Link

入站：飞书 → MopheusCopy Anchor Link

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

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

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

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

出站：Mopheus → 飞书Copy Anchor Link

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

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

消息格式Copy Anchor Link

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

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

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

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

常见问题Copy Anchor Link