# Mew 飞书打卡与消息指南

适用版本：Mew V3.0.1。

这份指南用于把管理员维护的一套飞书企业自建应用机器人连接到多个 Mew 用户。每位用户只需在网页生成一次性绑定码，再在飞书私聊机器人发送该码；之后的聊天、任务、打卡和提醒都会进入各自独立的数据空间。

## 开始前

管理员需要一个可公开访问的 HTTPS 网站地址，以及已创建的飞书企业自建应用。应用应开启机器人能力和「允许外部用户与机器人单聊」，并在权限管理中申请接收消息、发送消息、更新消息、上传图片等所需权限。每次新增权限都要创建并发布新的应用版本。

不要把 App Secret、Verification Token、模型密钥或登录口令发送到群聊或截图中。

## 在 Mew 中保存机器人配置

1. 用管理员账号登录 Mew 网页。
2. 打开「控制中心 → 消息渠道 → 飞书主动提醒」。
3. 填入飞书 App ID、App Secret 与 Verification Token，启用共享飞书机器人并保存。
4. 复制页面生成的事件回调地址。

凭证只保存在服务器；网页重新打开时只会显示是否已配置，不会回显明文。

如果希望飞书内的站内链接正确打开，在服务器 `/opt/mew/.env` 中配置：

```text
MEW_PUBLIC_URL=https://你的域名或公网IP
```

保存后运行 `sudo systemctl restart mew`。

## 在飞书开放平台配置回调

1. 打开当前应用的「事件与回调」。
2. 选择将事件发送到开发者服务器，粘贴 Mew 的回调地址，并填入相同的 Verification Token。
3. 添加事件 `im.message.receive_v1`。
4. 在「回调配置」中同样选择发送至开发者服务器，并添加 `card.action.trigger`，用于处理提醒卡片的完成按钮。
5. 保存并发布版本；如企业要求审核，等待审核完成。

若飞书提示切换为长连接方式，请取消。当前部署使用 HTTPS 回调地址；切换后消息与卡片按钮不会送到服务器。

## 用户绑定与使用

1. 用户登录自己的 Mew 网页账号，在「控制中心 → 昵称与头像 → 绑定飞书账号」生成绑定码。
2. 在飞书中打开机器人，先开启单聊，再单独发送完整绑定码。
3. 收到绑定成功后，即可正常聊天、建立任务、完成任务或发送「喝水打卡」。

绑定码只能使用一次。随机码有效 10 分钟；自定义码有效 24 小时。一个飞书账号只会绑定到一个 Mew 用户；重新绑定会解除旧关联。

## 排查

- 飞书回调校验失败：确认 HTTPS 地址可从公网访问、回调地址完整、Verification Token 一致，且 Nginx 把 `/api/` 转发到 Mew。
- 能收到事件但没有正式回复：在服务器运行 `sudo journalctl -u mew -n 100 --no-pager`，检查飞书消息和模型调用是否报错。
- 卡片按钮无效：确认已发布 `card.action.trigger` 回调配置，并重新发送一条新的提醒卡片测试。