black-yt Feishu Bot
文件导航
| 序号 | 文件内容概览 | 关键词 | 触发时机 | 文件路径 |
|---|---|---|---|---|
| 1 | 说明飞书自定义机器人 webhook 的创建、发送、签名、安全设置、消息类型、Markdown 表格渲染、报告型卡片排版/长度/表格数量限制、官方文档入口和常见错误码；它只适合往某个群里单向推送告警、日报、CI/CD 通知或临时消息。 | 飞书、Lark、custom bot、webhook、群机器人、text、post、interactive card、schema 2.0、CardKit、tag markdown、Markdown 表格、card table number over limit、ErrCode 11310、报告卡片、长度截断、lark_md、sign、HMAC、关键词、IP 白名单、错误码、单向通知 | 只需要给群推送通知前；已有 webhook 需要发文本/富文本/卡片/Markdown 表格前；需要查官方文档或 CardKit 验证卡片 JSON 前；报告卡片出现表格不渲染、内容拥挤、表格数量超限或正文过长时；排查 9499、19021、19022、19024、11310 前；配置签名校验或安全策略前必须读取 |
references/custom-webhook.md |
| 2 | 说明飞书应用机器人的正式开发链路，覆盖自建应用、机器人能力、权限、tenant_access_token、消息 API、事件订阅、回复/编辑/撤回、资源上传、群管理和卡片回调边界。 |
飞书开放平台、应用机器人、自建应用、tenant_access_token、im:message、send_as_bot、chat_id、open_id、事件订阅、reply、update、delete、upload image、upload file、card callback | 需要收消息、自动回复、查用户 ID、发单聊、撤回/编辑消息、上传图片/文件、群管理、按钮点击回调或 AI Bot 前；自定义机器人能力不够时必须读取 | references/app-bot.md |
路线选择
- 只做“往某个群里推送告警、日报、CI/CD 结果、临时通知”：优先用自定义机器人 webhook。
- 需要“收用户消息、自动回复、查 open_id/user_id、发单聊、撤回/编辑消息、上传文件、管理群、处理卡片按钮回调”：用应用机器人。
- 需要“AI 对话、工单流转、审批通知后可交互处理”：用应用机器人 + 事件订阅 + 飞书卡片。
安全规则
- 不要把 webhook、签名密钥、
app_secret、tenant_access_token写入仓库、日志、截图或最终回复。 - 示例统一使用
[HOOK_URL]、[BOT_SECRET]、[TENANT_ACCESS_TOKEN]、[CHAT_ID]、[OPEN_ID]、[IMAGE_KEY]、[MESSAGE_ID]等占位符。 - webhook 等同于“发消息密钥”。正式使用时至少开启一种安全策略，推荐签名校验；如果 webhook 曾公开暴露，重置 webhook 或重新配置签名密钥。
- 自定义机器人不能查用户 ID、不能响应用户消息、不能撤回消息；不要把它包装成正式交互机器人。
- 应用机器人需要权限申请、版本发布和管理员审核；不要在没确认权限的情况下盲目排查代码。
快速判断
curl "[HOOK_URL]"这种请求是自定义机器人 webhook。Authorization: Bearer [TENANT_ACCESS_TOKEN]+/open-apis/im/v1/messages是应用机器人消息 API。- 自定义机器人发卡片通常是顶层
card。 - 应用机器人发卡片时，
content通常是 JSON 字符串，需要转义。 @单人需要open_id或user_id，并且目标用户必须在群里；外部群通常只支持 Open ID。
验证清单
- 发送前确认机器人类型，不要把自定义 webhook 和应用机器人 API 的请求体混用。
- 先发最小 text 消息，再尝试富文本、图片或卡片。
- 如果开启签名，确认
timestamp是秒级时间戳，且请求在 1 小时有效期内。 - 如果开启关键词安全策略，确认消息文本或 title 包含配置关键词。
- 如果开启 IP 白名单，确认调用出口 IP 在白名单里。
- 对应用机器人，先确认权限、
tenant_access_token、receive_id_type、receive_id和content转义格式。