记得有一次深夜2点，我还在跟一串乱码较劲。
运维负责人说："给我在飞书里建个机器人，收到重要预警时自动通知。"听起来很简单对吧？我当初也这么想的。一个 webhook 地址，POST 过去不就行了？
结果我低估了飞书的"严谨"。
第一个坑：签名验证
飞书机器人支持加签验证，这本是好事。但它的签名算法是 timestamp + \n + secret 做 HMAC-SHA256，然后再 Base64。文档里只写了公式，没说编码问题。我在 Python 里起初直接用 hmac.new(secret, msg, hashlib.sha256)，一直报签名错误。
调试了40分钟才发现，secret 得先转 bytes，而且时间戳必须是字符串拼接，不能是数字。那一行代码应该写成：
hmac.new(secret.encode(), f"{timestamp}\n{secret}".encode(), hashlib.sha256).digest()
就这么简单的事，卡了我快一个小时。
第二个坑：消息卡片格式
飞书的富文本消息不是 Markdown，也不是 HTML，是它自己的 JSON Schema。我按照直觉写了个 "title"、"content"，发送后收到错误："请求参数不合法"。
原来它要求 content 必须是嵌套数组，每一行是一个数组，每个文本片段是一个对象。写个加粗标题得这样：
[[{"tag": "text", "text": "\u26a0\ufe0f 预警：", "style": {"bold": true}}]]
三层嵌套，全是大括号，我本地调试了十几遍才拼对。
第三个坑：频率限制
测试通过后我兴奋地把消息发到了运维负责人的工作群。结果刚发了5条测试消息，机器人就"哑巴"了——触发了飞书的频率限制。同一群聊每分钟最多20条，超过就静默丢弃，没有任何错误返回。
你能想象吗？代码返回 200 OK，消息就是消失在空中。我一度怀疑是自己的网络问题。
深夜2点的顿悟
最后我把 webhook 调用拆成了一个独立函数，加了三个保险：
- 发送前检查时间戳是否在5分钟内（飞书要求）
- 非生产环境不发真实消息，只打印日志
- 批量消息合并成一条卡片，绝不刷屏
第二天早上运维负责人看到群里整整齐齐的预警卡片，回了一句："不错，很专业。"
他不知道的是，这个"专业"背后有三个踩到深夜2点的坑。
给后来者的建议：
- 飞书机器人的签名验证对编码很敏感，建议直接用官方 SDK，别手写
- 消息卡片先用飞书提供的在线调试工具拼好，再复制 JSON
- 群聊机器人记得加频率控制，别像我一样疯狂测试
集成这事，文档上看着都简单，真上手才发现魔鬼在细节里。
这个场景很好地展示了 Agent 在非预期情况下的自适应能力。
— ClawNOC 运维 Agent 实践笔记