办公聊天软件接入 Hermes Agent 实录二飞书权限矩阵 长连接事件订阅一次跑通基于 Hermes Agentv0.20.0 Dify1.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 助手」的方案另一篇文章这次把同样的能力接到飞书。飞书接入的完整度要求比一般平台高——权限、事件订阅、版本发布三个环节环环相扣任何一个不完整表现都是「连接正常但消息静默丢弃」极难排查。这篇文章把完整路线和三个坑讲透。二、飞书接入的复杂度认知先看这个飞书开放平台有「三件套」全部正确才收得到消息① 权限矩阵 → 应用能读什么、发什么私聊读取权限是关键 ② 事件订阅 → 飞书把消息推给谁长连接模式 ③ 版本发布 → 配置真正上线保存 ≠ 生效最反直觉的一点三件套缺任何一件应用状态看起来都是正常的——连接成功、日志无报错、飞书后台「验证连接状态」也通过但消息就是到不了你的服务器。这是飞书接入最大的坑。三、架构总览WebSocket 长连接wss://msg-frontier.feishu.cn/ws/v2调 MCP 工具 dify_askHTTP POST /v1/chat-messages返回 answer 带引用原样转发回推飞书客户端员工发消息Hermes Gateway云服务器 systemd 托管Hermes Agent模型编排Dify 应用知识库问答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_IDcli_xxx FEISHU_APP_SECRETxxx FEISHU_DOMAINfeishu FEISHU_ALLOW_ALL_USERStrue # 开发期生产改白名单# 重启 gatewayhermes gateway restart连接成功的标志看~/.hermes/logs/agent.log不是 journalctlgateway.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 typetext message_idom_x100... [Feishu] Inbound dm message received: textX-Office有哪些功能 gateway.run: inbound message: platformfeishu msgX-Office有哪些功能 agent.turn_context: conversation turn: platformfeishu agent.tool_executor: tool mcp__dify_bridge__dify_ask completed gateway.run: response ready: platformfeishu time11.7s response163 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 助手」的企业。十、常见问题 FAQQ1连接成功但消息静默丢弃最可能的原因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飞书开放平台「开发回声机器人」FAQhttps://open.feishu.cn/document/develop-an-echo-bot/faqDify Service API 文档https://docs.dify.ai/zh-hans/api-reference/application-service-apis本系列其他篇系列零序言为什么做、怎么选、三篇地图系列一企业微信极简路线 多 Dify 应用系列三钉钉Stream 模式长连接一次跑通本文由 AI 协作完成接入、排障、优化均为实测过程数据取自真实运行日志。有问题欢迎评论区交流。