企业微信二次开发里，最容易被高估的是发送接口，最容易被低估的是发送治理。POST 一次 doApi、method 填 /msg/sendText，半天能调通；但企业微信外部群一上量——工单突发、关键词连环、多设备并行——故障会从「偶发」变成日常。

外部群没有官方机器人可推（官方做不到），发言观感就是「这个员工在说话」。因此发送层要按真人节奏 + 可审计来设计，而不是按吞吐量竞赛。

直调接口为什么不够

「事件来了就 POST」常见后果：

• 同一 guid 上多 Worker 并发，乱序、交错、偶发失败难复现

• 重试把瞬时尖峰放大成雪崩

• 主动推和自动回抢同一通道，客服应答被运营群发堵住

• 过时消息半夜补发，体验比不发更差

再包一层 SDK / Client，只是把 HTTP 细节藏起来；不解决串行、幂等、优先级和过期。治理不在 Client 里，在任务模型里。

最小发送任务长什么样

每条待发任务至少带齐：

字段	作用
guid	哪个登录实例执行；多设备时禁止写死
toId	外部群填 roomId；填个人 ID 会「成功但群不可见」
method / 内容	如 /msg/sendText；图片文件走对应上传+发送链路
biz_id	幂等键
source	webhook / ticket / campaign…
created_at	过期可丢弃
priority	接管提示 > 客户自动回 > 工单通知 > 运营群发

业务事件 / Webhook 决策
        │
        ▼
   发送任务入队（带齐上表）
        │
        ▼
  per-guid 串行 Worker（间隔留余量）
        │
        ▼
     doApi → 落库 code / 凭证

同一账号串行，多账号并行。文档侧常见建议是队列化、避免无脑并发，单条间隔按真人节奏配置（具体数值以文档为准）。积压飙升时，先砍低优先级运营任务，而不是加并发硬打。

幂等：两套账本，不要共用一把锁

自动回：幂等跟「设备 + 消息唯一标识」走（回调字段名以文档为准）。
主动推：幂等跟「业务单号 + 状态版本」走。

接口主动发出的消息通常不再进企微 Webhook，所以不能靠回调自证已发送；必须在当次响应里判断 code 及发送成功相关字段（以文档为准），并写入发送凭证。客户说「群里没收到」时，你要能回答：当时 toId 是什么、guid 是否仍在群、响应是什么——而不是翻应用日志碰运气。

def enqueue_send(job):
    # ticket: "ticket:{id}:{status_ver}"；webhook: "msg:{guid}:{msg_uid}"
    if not redis.setnx(job.biz_id, 1):
        return "deduped"
    redis.expire(job.biz_id, 86400)
    queue.push(job.guid, job)  # 按 guid 分片
    return "queued"

短时间工单状态 A→B→C 连跳，合并成「当前是 C」再入队；否则外部群会被刷成流水，投诉来了还以为是「机器人太勤快」。

guid 隔离比 Token 口号更落地

Token 决定鉴权与回调绑定；guid 决定谁在群里说话。同 Token 多设备时，回调会汇总到同一地址——发送必须带回事件里的 guid，Worker 按 guid 分片。写死一个设备 ID，是发错群的第一嫌疑。

掉线优先走恢复，而不是新建 guid：新建会让 biz → guid → roomId 映射整表失效，表现为「突然所有主动发都失败或发错人」。创建设备时的省份、扫码时限等接入约束，漏了也会装成「发送接口不稳」，排障时先看设备层。

多业务若要硬隔离，用多 Token 分回调更干净；单 Token 多系统消费时，在自有服务扇出，扇出层自己保证回调快响，再慢慢分发给下游。

失败要分类，重试才有意义

类型	例子	策略
可重试	超时、短暂网络	有限次退避，仍走同 guid 队列
需人工	掉线、顶号、授权不足	告警 + 暂停该 guid 出队
参数错	toId 错误、不在群	失败落库，禁止盲重试刷频
已过期	客户五分钟前问进度，堵了半小时	丢弃并记 expired，避免半夜补发

媒体类消息先等上传/异步就绪（异步事件 cmd 等以文档为准），再进发送队列；否则重试只会反复打到「媒体未就绪」。

观测：发送层的四块看板

1. 按 guid 的队列积压与平均等待

2. 成功率 / 失败码分布

3. source 占比（自动回是否被群发挤压）

4. 去重命中与过期丢弃量

没有这四块，讨论「要不要上 AI」没有工程意义——你甚至不知道现在是没收着、没发出去，还是发出去了但发错会话。

小结

企微 API 的发送能力很好接；企业微信外部群能不能长期跑，取决于队列分片、幂等账本、guid 生命周期和失败分类。少写一层「万能 Client」，多设计一张可审计的发送任务表，主动发和自动回才会从 Demo 变成可值班的生产链路。