办公聊天软件接入 Hermes Agent 实录（二）：飞书权限矩阵 + 长连接事件订阅一次跑通
办公聊天软件接入 Hermes Agent 实录（二）：飞书权限矩阵 + 长连接事件订阅一次跑通
基于 Hermes Agent（v0.20.0）+ Dify（1.16.1）实测。文中所有命令、日志片段、配置项均来自真实运行，未做美化。
目标读者：企业 IT 管理员、AI 应用交付工程师、用飞书办公想把 AI 助手接进去的开发者。
环境版本：Hermes Agent v0.20.0 + Dify 1.16.1 + 飞书企业自建应用（长连接模式）。
前置条件：已有可运行的 Hermes Gateway + Dify 知识库应用（接入方法见系列（一）企业微信篇）。
读完你将获得：① 飞书接入完整四步法 ② p2p_msg:readonly 缺失导致消息静默丢弃的根因 ③ 11.7s 响应带引用回复的验证日志 ④ 回复噪音净化的配置方案。
一、为什么做这件事
很多企业用飞书办公——通讯、会议、文档都在飞书里。把企业的 AI 能力（知识库问答、业务流程工作流）接进飞书，员工在聊天窗口里直接问「产品手册里 XX 怎么用」「帮我查一下订单状态」，机器人秒回带引用，是比打开网页查文档自然得多的体验。本文以知识库问答为例。
我们已经在企业微信上跑通了「聊天软件 + AI 助手」的方案（另一篇文章），这次把同样的能力接到飞书。飞书接入的完整度要求比一般平台高——权限、事件订阅、版本发布三个环节环环相扣，任何一个不完整，表现都是「连接正常但消息静默丢弃」，极难排查。这篇文章把完整路线和三个坑讲透。
二、飞书接入的复杂度认知（先看这个）
飞书开放平台有「三件套」，全部正确才收得到消息：
① 权限矩阵 → 应用能读什么、发什么（私聊读取权限是关键） ② 事件订阅 → 飞书把消息推给谁（长连接模式） ③ 版本发布 → 配置真正上线（保存 ≠ 生效）最反直觉的一点：三件套缺任何一件，应用状态看起来都是正常的——连接成功、日志无报错、飞书后台「验证连接状态」也通过，但消息就是到不了你的服务器。这是飞书接入最大的坑。
三、架构总览
Hermes 管「连接与编排」，Dify 管「知识库与回答」——和企微方案同一套架构，只是前端平台换成了飞书。
四、飞书侧配置（五步）
4.1 创建应用
open.feishu.cn → 开发者后台 → 创建企业自建应用 → 添加「机器人」能力 → 拿到 App ID / App Secret。
4.2 权限矩阵（按飞书官方 FAQ 校准）
飞书官方 FAQ 把下面三项列为「申请应用身份权限」的必选项——私聊可用性的硬门槛：
| 权限 | 作用 | 必配 |
|---|---|---|
| im:message.p2p_msg:readonly | 读私聊消息——私聊收消息的硬门槛 | ✅✅ |
| im:message:send_as_bot | 以机器人身份发消息 | ✅ |
| im:message | 获取与发送单聊、群组消息 | ✅ |
| im:message.group_at_msg:readonly | 接收群 @ 消息 | 群聊用 |
| im:message.group_at_msg.include_bot:readonly | 接收群里机器人 @ 消息 | 群聊高级场景 |
| contact:user.id:readonly | 读取用户 ID | 建议 |
| im:chat / im:chat:readonly | 会话信息 | 场景可选 |
⚠️ p2p_msg:readonly 是最大隐藏坑：im:message（获取与发送消息）≠im:message.p2p_msg:readonly（读单聊）——私聊必须单独授权后者，否则消息静默丢弃。权限授权有直达链接：https://open.feishu.cn/app/<APP_ID>/auth?q=<权限名>（飞书报错信息里会自带）。
4.3 事件订阅
事件与回调 → 订阅方式选「使用长连接接收事件」（无需公网域名/加密策略）→ 添加事件「接收消息 im.message.receive_v1」→ 保存。
配置后点「验证连接状态」应显示「连接成功」——这是飞书官方的连通性确认。
4.4 版本发布（飞书铁律）
任何配置变更（权限/事件订阅/可用范围）都必须「保存 + 创建版本 → 发布」才生效。只保存不发布 = 白改。发布后建议重启 gateway 重连（新连接才带最新订阅）。
4.5 健康状态对照（配置完后自检）
| 检查点 | 健康表现 | 异常表现 → 处理 |
|---|---|---|
| 长连接 | 日志✓ feishu connected | 无此行 → App ID/Secret 错或网络不通 |
| 权限 | 私聊能收到消息 | 连接正常但日志空白 → p2p_msg:readonly 缺失 |
| 事件订阅 | 日志出现Received raw message | 无此行 → 事件未订阅或未发布 |
| 版本发布 | 消息链路通 | 配置改了不生效 → 只保存没发布 |
五、Hermes 侧接入
# ~/.hermes/.env FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=xxx FEISHU_DOMAIN=feishu FEISHU_ALLOW_ALL_USERS=true # 开发期；生产改白名单# 重启 gatewayhermes gateway restart连接成功的标志（看~/.hermes/logs/agent.log，不是 journalctl！）：
gateway.run: Connecting to feishu... [Feishu] Connected in websocket mode (feishu) gateway.run: ✓ feishu connected gateway.run: Gateway running with 2 platform(s)六、两个真实踩坑
| 坑 | 现象 | 根因 | 修复 |
|---|---|---|---|
| p2p_msg:readonly 缺失 | 连接正常、日志空白、消息静默丢弃 | 私聊读取权限没单独授权 | 授权 p2p_msg:readonly + 发布版本 |
| 配置改了不发布 | 权限勾了、事件加了，就是不生效 | 只保存没发布，线上还是旧配置 | 保存 → 创建版本 → 发布 |
七、验证链路（真实日志）
飞书发「X-Office有哪些功能」后，消息完整走通：
[Feishu] Received raw message type=text message_id=om_x100... [Feishu] Inbound dm message received: text='X-Office有哪些功能' gateway.run: inbound message: platform=feishu msg='X-Office有哪些功能' agent.turn_context: conversation turn: platform=feishu agent.tool_executor: tool mcp__dify_bridge__dify_ask completed gateway.run: response ready: platform=feishu time=11.7s response=163 chars [Feishu] Sending response (163 chars)飞书收到回答：「根据知识库内容，X-Office 提供会议纪要、任务管理、周报生成三大核心能力，并支持与主流办公系统集成 [1]。」——干净、准确、带引用。
八、回复噪音净化（实测配置）
接入初期，飞书回复会混入三类噪音：⚙️ tool_describe:（工具进度显示）、「Dify 查询遇到临时错误，我重试一次」（模型自述过程）、💾 Self-improvement review（后台维护通知）。全部可配置清除：
# config.yaml 的 display 节display:memory_notifications:'off'# 关后台维护通知tool_progress:'off'# 关工具进度显示show_commentary:false# 关思考过程消息再在~/.hermes/SOUL.md加「回复纯净规则」：
## 回复纯净规则（重要） - 工具调用过程、重试、错误说明等内部信息绝不写入给用户的回复。 - 调用工具遇到临时错误时静默重试（最多 2 次），不要向用户解释「遇到错误/重试中」。 - 回复只包含最终答案本身，不加任何过程性前缀。改完重启 gateway——回复只剩答案本身，带 [1] 引用。
另外：首次接入会收到一条「No home channel is set…」提示（定时任务结果的投递目标引导），发/sethome一次即可，不影响问答。
⚠️ 本文基于 Hermes Agentv0.20.0、Dify1.16.1实测。飞书开放平台的权限名、事件订阅界面可能随版本调整，请以官方最新文档为准。
九、总结
飞书接入一句话：权限（p2p_msg:readonly 不能漏）+ 事件订阅（长连接 + receive_v1）+ 发布（保存必须发布）三件套齐全，消息链路自然通。
与企业微信方案的关系：这篇文章里的 Hermes 侧接入（gateway + MCP 桥接 + Dify 知识库）和另一篇企业微信实录完全一致——同一套后端，只是前端聊天软件不同。而且实测两者可以同时在线：一个 Hermes 大脑，飞书和企微两个入口，会话按平台天然隔离互不干扰——员工在飞书问、在企微问，两边各自独立对话。企业用哪款办公软件，都能接。
方案边界：本方案适用于企业已有飞书办公体系、需要把知识库问答嵌入聊天窗口的场景。三平台（飞书/企微/钉钉）可同时接入且互不干扰；但同平台多机器人在 v0.20.0 有会话隔离限制（详见系列（一）企业微信篇第九节），生产环境建议单机器人。
这套方案适合：已有飞书/企微办公体系、想把知识库变成「聊天窗口里随叫随到的 AI 助手」的企业。
十、常见问题 FAQ
Q1：连接成功但消息静默丢弃，最可能的原因？
A：绝大多数是im:message.p2p_msg:readonly权限缺失，或权限/事件改了没发布版本。
Q2：为什么hermes gateway restart后还是旧配置？
A：飞书配置必须「创建版本 → 发布」才生效，且建议重启 gateway 建立新连接——只重启 gateway 不会让未发布的配置生效。
Q3：群聊里 @ 机器人没反应？
A：需要im:message.group_at_msg:readonly权限 + 发布版本 + 群聊里 @ 机器人触发。
Q4：飞书和企微能同时用吗？
A：能。一个 Hermes 实例可同时连接飞书 + 企微 + 钉钉（实测三平台在线），会话按平台天然隔离，互不干扰。
十一、参考资料
- Hermes Agent 飞书接入文档：https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/messaging/feishu
- 飞书开放平台「接收消息」事件文档：https://open.feishu.cn/document/server-docs/im-v1/message/events/receive
- 飞书开放平台「开发回声机器人」FAQ：https://open.feishu.cn/document/develop-an-echo-bot/faq
- Dify Service API 文档：https://docs.dify.ai/zh-hans/api-reference/application-service-apis
本系列其他篇：
- 系列（零）序言：为什么做、怎么选、三篇地图
- 系列（一）企业微信：极简路线 + 多 Dify 应用
- 系列（三）钉钉：Stream 模式长连接一次跑通
本文由 AI 协作完成：接入、排障、优化均为实测过程，数据取自真实运行日志。有问题欢迎评论区交流。