feishu-agent-groups

name	feishu-agent-groups
description	批量把飞书外部群里的客户逐个拉进"1客户+1能力Bot"的专属外部群,并让 OpenClaw agent 本体进群主动 @客户 打招呼。用户说"批量拉群""给客户建专属群""外部群邀约/分流""一人一群""让机器人进群自我介绍"时使用。

飞书专属群批量邀约 + agent 本体迎客

业务背景

多个单能力飞书 Bot(文案/图片/视频助手…),客户先聚在一个外部大群等邀约。要把每位客户 拉进「客户 + 能力Bot + 运营者」的专属外部群,进群时由该 Bot 的 agent 本体用自己人设 @客户 欢迎。人工逐个拉极耗时,本 skill 用官方 API + OpenClaw 自动化。

原理(为什么 UI/普通脚本做不到)

• 建外部群、@ 跨租户外部人:必须用户身份 token(bot 看不到你的会话、不能替你建外部群)。
• 建群 API 的 external:true:UI 和 lark-cli 封装命令都没有,只能走原生 API。
• 进群主动打招呼:OpenClaw 进群事件只写日志,靠外部触发 openclaw agent --deliver。

前置条件(逐项检查,缺一不可)

1. lark-cli 已装 + 用户身份授权(auth login --domain im,contact,设备码:--no-wait --json 拿链接给用户→授权后 --device-code 收令牌,别在同一步阻塞)。
2. 操作人是源群成员(脚本会校验)。
3. 能力 Bot 的 App 可用范围含操作账号(否则 232043),改动发布新版本才生效。
4. 用 --agent-greet:OpenClaw 服务器 openclaw agent 可用 + 从操作机 ssh <host> 免密。

标准流程(严格按顺序,每步之间等用户确认)

# ① 找源群
lark-cli im +chat-search --query "群名关键词" --as user
# ② DRY-RUN(不加 --execute 只打印名单/群名)
python3 batch_groups.py <源群oc_id> --bot <cli_能力botID> --name-template "【文案助手】{name} 专属群"
# ③ 试点 3 人 + agent 本体欢迎(agent-profile/id/account 查你的 fleet 映射表)
python3 batch_groups.py <源群oc_id> --bot <cli_xxx> --name-template "…" --agent-greet \
  --agent-profile <inst> --agent-id <id> --agent-account <acct> --role-hint "你是…助手,能…" \
  --execute --limit 3
# ④ 确认后全量
python3 batch_groups.py <源群oc_id> --bot <cli_xxx> --name-template "…" --agent-greet \
  --agent-profile <inst> --agent-id <id> --agent-account <acct> --role-hint "…" --execute

铁律

• ②③④ 每步之间必须停下等用户确认;全量前报:人数、群名样例、欢迎话术。
• 默认只处理外部租户成员(跳过本公司同事和自己);含内部需 --include-internal。
• 状态文件(feishu_groups_state.*.jsonl)是断点/防重唯一依据,不要删;重跑自动跳过成功者、重试失败者。
• 限频(99991400)就停下加大 --interval,别硬撞;客户"禁止被拉群"记为 blocked,交人工邀请。
• 凭据只进本机 600 文件/环境变量,绝不进 git、不发外部渠道。

详细运维锦囊(错误码、克隆身份修复、bot_greeter 用法)见同目录 README.md。