飞书与邮件转发

Bot 可以使用飞书/Lark 自定义机器人 Webhook 作为消息出口，也可以选配 IMAP 邮箱读取器，把符合条件的通知转发到飞书群。面板内置了一页配置向导；本文说明配置时需要关注的边界。

创建飞书自定义机器人

在目标飞书群的群设置中创建自定义机器人，复制 Webhook URL。若组织策略支持，启用签名校验并保存签名密钥。然后在面板创建一个平台为 Lark Webhook 的 Bot，填写机器人名称、Webhook URL 和签名配置，使用面板的测试消息验证投递。

Webhook URL 和签名密钥都属于凭据。不要把它们贴到群聊、issue 或公共截图；如果泄露，立即在飞书侧删除或轮换机器人。

可选的 IMAP 邮件转发

启用 Email Forwarding 后，服务会通过 IMAP 轮询一个邮箱，把匹配过滤器的邮件发送到飞书群。配置内容包括 IMAP 主机、端口、TLS、邮箱、应用专用密码、轮询间隔、发件人过滤和主题过滤。

常见配置：

Gmail 通常需要先开启 IMAP、启用两步验证，再生成应用专用密码。不要使用主账号密码，也不要把应用专用密码放在文档或聊天里。

过滤器可以按发件人和主题缩小转发范围，例如只接收代码托管平台的拉取请求、CI 或 issue 通知。只匹配需要的邮件，避免把整个个人收件箱转发到群。

首次读取未读邮件快照失败时，监控会先重试建立快照，避免将未读取完成的历史邮件直接作为新邮件转发。连接中断后会尝试恢复轮询；停用邮件监控后，不再发起新的转发请求，但已经发出的 Webhook 请求可能仍会完成。

未读队列会继续向后处理，前面的历史邮件或不匹配过滤条件的邮件不会阻塞后面的新邮件。只有转发成功的邮件才会尝试标记为已读；过滤掉的邮件保持原来的已读状态。

监控只转发建立初始基线后的新邮件，不提供历史补发：将旧邮件重新标为未读不会触发转发。大量历史未读也不会因为缓存清理而被重新发送；邮箱被重建、邮件 UID 标识失效时，监控会重新建立基线。

提及映射

如果邮件正文包含代码托管平台用户名，面板可以配置用户名到飞书 open ID 的映射，用于在群里生成准确的提及。导入映射文件前检查每行的用户名和 open ID，不要把不相关的联系人资料上传到公开环境。

新建 Bot 的映射默认为空，需要由实例管理员手动添加或导入。已保存在 Bot 邮件配置中的映射继续使用；联系人身份资料属于实例数据，不随源码分发。

测试和排错

1. 先从面板发送一条测试消息，确认 Webhook 和签名。
2. 再向邮箱发送一封只包含测试内容的邮件。
3. 检查发件人、主题是否匹配过滤器，以及轮询间隔是否已经经过。
4. 查看 Bot 日志和飞书群的实际消息，区分“邮件未被读取”和“飞书投递失败”。

飞书侧的机器人频率限制、组织安全策略和邮件提供商规则可能随时间变化；实例维护者应以对应平台当前控制台显示为准。面板提供专门配置向导时，优先按面板提示操作。