feishu-bot-ops — 飞书机器人运维（Feishu Bot Ops）

飞书 Bot 运维大全 让 Hermes Agent 的飞书 bot 稳定运行，覆盖从部署到深度调试的完整知识。

目录 快速诊断 — 一键诊断 + 一键修复 环境变量速查 消息与 @mention 机制 Bot 间通信 会话上下文串线 故障场景速查表 — 10+ 场景的现象→根因→修复 安全运维 飞书 API 调试手段 交互卡片回调 排查纪律

快速诊断 用户说「飞书不能用了 / 没反应」时，跳过信息搜集，直接跑诊断： 一键诊断命令 # 0. lark-oapi 是否安装（最常见的新装遗漏） /bin/python -c "import lark_oapi" 2>&1 || echo " lark-oapi 未安装" # 1. Gateway 进程状态 ps aux | grep '[h]ermes.gateway' | grep -v grep # 2. 锁文件 ls -la ~/.local/state/hermes/gateway-locks/ 2>/dev/null # 3. 最近日志错误 grep -iE 'error|unauthorized|feishu.(connected|disconnected|dropping|lock)|panic' \ ~/.hermes/logs/gateway.log | tail -20

快速定位：lark-oapi 缺失→安装；锁文件残留→清理后重启；Unauthorized→GATEWAY_ALLOW_ALL_USERS=true；进程不在→启动 gateway；connected 正常但没回复→检查 _admit 拒绝原因。

一键修复命令 # 场景A：多实例/锁文件冲突 pkill -9 -f 'hermes gateway run' 2>/dev/null; sleep 2 rm -f ~/.local/state/hermes/gateway-locks/feishu-app-id-*.lock hermes gateway run 2>&1 & sleep 5 && grep ' feishu connected' ~/.hermes/logs/gateway.log | tail -1 # 场景B：鉴权拦截 grep 'Unauthorized' ~/.hermes/logs/gateway.log | tail -3 # 如有输出 → .env 加 GATEWAY_ALLOW_ALL_USERS=true，重启 # 场景C：lark-oapi 未安装 /bin/python -m ensurepip 2>/dev/null /bin/python -m pip install lark-oapi # 国内用户可用镜像：-i https://mirrors.aliyun.com/pypi/simple/ # 装完重启 gateway

关键原则 先诊断，后解释—不要先说「让我加载技能看看」，用户会觉得你卡死了 诊断结果出来后，一句话报告现状+下一步，不要长篇解释

环境变量速查 所有变量在 ~/.hermes/.env 中设置，修改后需重启 gateway 生效。 变量 默认值 作用 FEISHU_GROUP_POLICY allowlist 群消息准入策略：open/allowlist/blacklist/disabled FEISHU_REQUIRE_MENTION true 是否要求群消息必须 @ bot 才处理。设 false 可接收所有群消息 FEISHU_ALLOW_BOTS none 是否接收其他 bot 的消息：none/mentions/all FEISHU_AT_MAP (空) @mention 映射表：显示名=open_id,...，让出站 @mention 转为真正的 标签 GATEWAY_ALLOW_ALL_USERS — 设为 true 跳过 gateway 层面用户白名单，解决「消息到达但被拦截」问题

消息与 @mention 机制 @mention 不是纯文本 飞书的 @用户名 需要带上 open_id 才能触发通知。Markdown 里 @某人 只是纯文本。 真正生效的 @mention 格式（飞书富文本消息）： 名字 影响： Bot 通过 Markdown 回复的 @某人 只是装饰性文本，不产生通知 用户端用飞书客户端原生 @ 可以正常生效 Bot 之间的 @ 互叫需要构造 post 消息含 标签

群消息准入逻辑 群消息是否被处理，取决于两层检查（feishu.py _admit()）： Group policy：FEISHU_GROUP_POLICY 控制（open/allowlist/blacklist/disabled） require_mention（默认 True）：即使 group_policy=open，消息也必须 @ 了 bot 才放行 FEISHU_GROUP_POLICY=open 不等于「所有群消息都能收到」— 必须 @ 了 bot 才行。 未 @ bot 的消息静默丢弃（日志可见 dropping inbound event: group_policy_rejected） 设置 FEISHU_REQUIRE_MENTION=false 可让 bot 接收所有群消息（无需 @）

Bot 间通信 两台 bot 互相 @ 需要双方都配好，缺一不可。 发送端配置（@ 别人） # .env 中配置 AT_MAP FEISHU_AT_MAP=对方显示名=对方open_id,别名=对方open_id 重启 gateway 后，bot 发出的 @对方显示名 会自动转为 post 消息含 标签。 接收端配置（被别人 @） # .env 中必须配 FEISHU_ALLOW_BOTS=mentions # 或 all。默认 none 会静默拒绝所有 bot 消息

验证 @ 是否生效（API 反查） 发送后立即用飞书 API 拉取消息确认： # 获取 token TOKEN=$(curl -s -X POST 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal' \ -H 'Content-Type: application/json' \ -d "{\"app_id\":\"$FEISHU_APP_ID\",\"app_secret\":\"$FEISHU_APP_SECRET\"}" | \ grep -oP '"tenant_access_token":"\K[^"]+') # 拉取消息 curl -s -H "Authorization: Bearer $TOKEN" \ "https://open.feishu.cn/open-apis/im/v1/messages/" msg_type mentions 结论 post 有 mentions 正常 text NONE AT_MAP 未触发 post NONE AT_MAP 检测失败（常见：\b 边界不匹配中文） 验证成功的标志： msg_type 为 "post"（非 "text"） mentions[] 数组包含目标用户的 open_id 和 name body.content 中包含 {"tag":"at","user_id":"@_user_1","user_name":"..."}

FEISHU_AT_MAP 代码回归陷阱 现象：.env 里 FEISHU_AT_MAP 配好了，也重启了 gateway，但 @某人 永远是纯文本。 根因：FEISHU_AT_MAP 的 转换逻辑是手动补丁加到 feishu.py 里的，不在 hermes-agent 主线代码中。gateway 更新或 feishu.py 被替换时，补丁代码会被覆盖丢失。 快速检测： # 如果返回空 → 补丁已丢失，AT_MAP 永远不会生效 grep "at_mention_map\|_parse_at_mention" /gateway/platforms/feishu.py 修复：重新应用 AT_MAP 补丁（5 处代码改动，详见 references/at-mention-code-fix.md），改前先备份： cp /gateway/platforms/feishu.py{,.bak.$(date +%Y%m%d_%H%M%S)}

已知 bug：\b 边界对中文名无效 _build_at_mention_post_payload 中用 \b 做边界匹配，但中文字符不是 \w，导致 @中文名 检测失败。修复：去掉 regex 中的 \\b。

排查 bot 间通信不生效 先确认出站方的消息格式是否是 post + （用飞书 API 拉消息验证） 确认接收方 FEISHU_ALLOW_BOTS 不是 none 确认接收方 gateway 未重启（WebSocket 断连会丢消息） 检查对方 bot 消息是否到达：grep "sender=bot:" ~/.hermes/logs/gateway.log | tail -20 如无 dropping 也无入站记录 → 消息未到达（大概率出站方 AT_MAP 未配或配错）

会话上下文串线 现象：群里有多个用户各自跟 bot 对话，bot 在收到用户 A 的新消息时，加载了用户 B 的历史 session 上下文，导致执行错误任务。 根因（三个参数组合）： gateway_auto_continue_freshness: 3600 — 1 小时内活跃过的 session 自动"续杯"而非新建 compression 开启 — 老 session 被压缩，关键上下文丢失但残影仍存在 session_reset.idle_minutes: 1440 — 24 小时空闲才重置，太长

永久修复（config.yaml）： gateway_auto_continue_f