飞书

如果你日常在飞书里办公，MailAgent 提供两个独立的入口：一是可以直接对话的 AI 助手，二是重要邮件与系统异常的推送。两者用两个不同的飞书应用、两套凭据，开一个不影响另一个。

飞书对话

在飞书私聊里，你能跟 MailAgent 桌面上那个 AI 助手继续聊——同一份记忆，同一个人设。它走飞书的长连接，你的电脑不需要公网地址，也不需要内网穿透。

只认私聊，不进群：群消息一律忽略，不回应也不记录。

每个话题是一个独立会话：飞书里的每个新话题对应一次新对话，不会接管你在桌面正开着的那个会话；飞书里的会话也会出现在桌面的会话列表里，标着「来自飞书」。

三个命令：

工具范围收紧了一档——飞书账号被盗不等于你的电脑被盗，所以：

需要审批的操作以按钮卡片发到飞书，点一下就放行；卡片过期或重复点击不会重复执行。

在飞书开发者后台新建一个独立的企业自建应用（不要复用发通知的那个），开启机器人能力，并开通两项权限：im:message.p2p_msg（接收私聊消息，需企业管理员审批）与 im:message（发送 / 更新消息）。
「事件订阅」与「回调订阅」是两个独立标签页，都要选长连接——只配了其中一个，卡片按钮会点了没反应。
保存这份订阅配置时，MailAgent 必须正在运行且已连上飞书，否则飞书会判定探活失败。
打开设置 → AI →「飞书对话」，填入 App ID 与 App Secret，保存后重启后端。

配完凭证还没结束——飞书只认绑定过的那一个账号：

mailagent im pair            # 或在「飞书对话」区点「生成绑定码」

会得到一个 6 位数字，10 分钟内有效。把这串数字单独发给 bot，绑定完成后只有这个飞书账号能进入对话，其他人一律拒绝。换手机或换账号，需要显式「重新绑定」。

发消息没反应？ 先看设置页里的连接状态；如果桌面 App 和后台 pm2 的 mail-sync 同时在跑，两边会抢消息，用 App 时把 pm2 停掉。
卡片按钮点了没反应？ 多半是「回调订阅」那个标签页漏配了长连接。
提示「连不上 AI 引擎」？ AI 服务跑在桌面 App 里，需要 App 正在运行。

除了对话，MailAgent 还能把重要邮件推到飞书，卡片上直接能点按钮处理；服务出问题时，也能发告警提醒你。这条链路用的是另一个飞书应用机器人，跟上面的对话完全独立。

当一封邮件被 AI 判为**紧急（Critical / Urgent）**时，飞书会收到一张交互卡片，上面有邮件主题、发件人、AI 摘要与优先级，以及几个按钮：

按钮	作用
打开 Notion	跳到这封邮件的 Notion 页面（需启用 Notion 镜像）
优化回复	AI 重新检索同线程历史，生成一份更贴合上下文的回复给你确认
创建草稿	基于已有的 AI 建议，直接在邮箱里创建一份回复草稿

「创建草稿」只在这封邮件已经有 AI 建议回复时才出现；「优化回复」生成完之后，通常还会附一个「采纳并创建草稿」的后续按钮。

点击卡片按钮后，飞书把动作回调给 MailAgent 的处理服务，由它完成起草、更新状态等操作，你只需要在飞书里点按钮、看结果。邮件在这个过程中的处理状态会这样流转：

未处理 → AI 已审阅 → 已同步 → 草稿已创建 → 已完成

除了邮件卡片，MailAgent 还能在服务异常时往飞书发告警——同步连续失败、邮件大量进入死信队列等。这是独立的开关，出问题时不用一直盯着日志。

在飞书开发者后台新建另一个企业自建应用（跟上面对话用的那个分开），拿到 App ID、Secret 与 Chat ID，配进 .env：

FEISHU_NOTIFY_ENABLED=true
# 一组 FEISHU_ 开头的应用凭据，具体字段见 .env.example
ALERT_ENABLED=true   # 服务告警，可选

重启后端生效：

pm2 restart mail-sync

深入了解：飞书对话架构 · 通知卡片回调契约