feishu-external-group-fix：飞书机器人加入外部群 · 排查与修复
适用症状：往群里添加自建应用机器人时报 「添加群成员失败：XXX 不支持加入外部群」；或群机器人列表里搜不到你的应用。
根因速查
| 症状 | 根因 | 修复 |
|---|---|---|
| 报错「不支持加入外部群」 | 群是外部群（含外部联系人），应用「对外共享」未开启 | 走下面的主修复路径 |
| 群里搜不到机器人 | 应用未发布版本 / 可用范围不含你 / 机器人能力未开 / 客户端缓存 | 见「其他排查点」 |
| 报错缺权限 99991672 | 应用缺 scope | 按报错里的直链开通后重发版本 |
第一步：API 自检（2 分钟，先搞清缺什么）
# 1. 换取租户凭证（app_id/app_secret 来自开放平台「凭证与基础信息」页）
curl -s -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
-H 'Content-Type: application/json' \
-d '{"app_id":"cli_xxx","app_secret":"xxx"}'
# → {"code":0, "tenant_access_token":"t-...", "expire":7200}
TOKEN=t-xxxx
# 2. 机器人能力 + 启用状态（失败=没开机器人能力）
curl -s -H "Authorization: Bearer $TOKEN" https://open.feishu.cn/open-apis/bot/v3/info
# 3. 列出机器人在哪些群（code=0 说明有 im:chat 类权限；群数量=0 说明还没进任何群）
curl -s -H "Authorization: Bearer $TOKEN" "https://open.feishu.cn/open-apis/im/v1/chats?page_size=20"
# 4. 发消息权限验证（先建个测试群拿到 chat_id 再发；230001=content 不是 JSON 字符串，用程序 json.dumps 二次编码）
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"test\"}"}' \
"https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id"
经验：错误信息很具体——99991672 Access denied 会直接给出开通 scope 的直链（https://open.feishu.cn/app/{app_id}/auth?q=...）；40004 = 通讯录类权限缺失。
第二步：主修复路径（开放平台网页操作）
入口
https://open.feishu.cn/app/{app_id}/version，登录用二维码（豆包/飞书 App 扫）。
- 创建版本（版本号自动递增，如 1.0.0 → 1.0.1）
- 找到 「对外共享」 区块 → 勾选 「允许机器人被添加到外部群中使用」（按需决定是否勾「允许外部用户与机器人单聊」，一般不勾）
- 勾选后会出现 「申请理由」 必填框——写清用途（如：个人 RSS 推送机器人，需推送到自己所在的外部群）
- 保存 → 弹窗 「申请线上发布」 提交
- ⚠️ 对外共享不免审：必须等 企业管理员 在管理后台/客户端审批通过后才生效（普通修改在可用范围≤5人时免审，开了对外共享就要审）
- 生效后客户端完全退出重开再重试拉群（配置有缓存）
快捷替代：内部群（零审核、立即可用）
如果推送场景不强制要求外部群（RSS 提醒、个人通知类基本都不需要）：
建一个普通群（只拉本组织成员）→ 群设置 → 群机器人 → 添加机器人 → 搜应用名。
内部群只要「已发布 + 可用范围包含你 + 机器人能力已开」就能加，不需要对外共享、不需要审核。
其他排查点（搜不到机器人时逐项过）
- 应用能力 页：是否有「机器人」能力
- 版本管理与发布 页：是否存在状态为「已发布」的版本（光保存不发布=不生效）
- 可用范围：部分成员模式下，你自己要在成员列表里
- 可用范围是空的/被清空：重新编辑成员，保存后重新发布一版
- 客户端缓存：完全退出飞书客户端重开（刚发布的配置几分钟内可能搜不到）
- 想强制刷新配置：原样重发一个新版本（小租户免审秒生效）
浏览器自动化操作开放平台的坑
用 agent 控制浏览器操作 open.feishu.cn 时：
- Playwright locator 点击大量超时（按钮/复选框即使 snapshot 里存在也点不动）→ 改用 截图定位 + CUA 坐标点击，点完截图确认状态
- 创建版本页很长，对外共享区块要往下滚
- 提交发布有两次确认弹窗，第二次弹窗出现时页面状态可能滞后，等 2~3 秒再判断