Wecom Group Bot

---
name: wecom-group-bot
description: "企微机器人——企业微信群机器人 webhook 推送日报、告警、提醒：text/markdown、@手机号、先预览再发、错误码解读、key 泄露处置。当用户说「企微机器人怎么发消息」「告警推到企业微信群」「errcode 什么意思」时使用。"
author: Captain
version: 0.1.0
display_name: "企微机器人"
display_name_en: "WeCom Group Bot"
description_zh: "企业微信群机器人（webhook）推送：日报、告警、提醒三类模板；text 与 markdown 写法要点；@手机号；默认只预览、确认后才发送的 Python 标准库脚本（超时、最多 2 次重试、errcode 中文解释，附本机假接收端自测）；频率控制建议与 key 泄露处置步骤。"
description_en: "Push daily reports, alerts and reminders to a WeCom group through its group-bot webhook, with a preview-first Python sender, errcode explanations, rate-control advice and key-leak handling."
tags:
  - "企微机器人"
  - "企业微信"
  - "群机器人"
  - "webhook"
  - "消息推送"
  - "告警通知"
  - "日报推送"
  - "WeCom"
  - "WeCom bot"
  - "markdown"
examples_zh:
  - "用企微机器人每天把日报推到部门群，帮我写个脚本"
  - "监控告警想自动发到企业微信群里，还要 @值班的人"
  - "企微机器人发消息返回 errcode 93000 是什么意思"
examples_en:
  - "Send our daily report to a WeCom group through the group bot webhook"
  - "My WeCom bot returns errcode 45009, what should I do?"
---

# 企微机器人

定位一句话：**先预览、再确认、最后才发；key 只放环境变量，任何输出只露后 4 位。** 用企业微信群机器人的 webhook 把日报、告警、提醒推到群里——本技能给写法、模板，和一个只用 Python 标准库的发送脚本。

## 何时使用

- 「帮我把每天的发布日报自动推到企业微信群」
- 「监控告警想推到值班群，还要 @ 当班的人」
- 「企微机器人的 markdown 怎么写颜色、链接」
- 「webhook 返回 errcode 45009 / 93000 是什么意思」
- 「机器人 key 不小心提交到仓库了，怎么办」

不适用（遇到时这样处理）：
- 个人微信、微信群的自动发消息：不做，说明原因（见「边界」）。
- 要收消息、按钮交互、单独发给某个人：这是企业微信「应用」开发，需要管理员建应用；只说明区别，请用户查企业微信开发者中心的应用消息相关文档。
- 钉钉、飞书等其他 IM 的机器人：协议不同，本技能不覆盖，直接说明。

## 流程

1. 在群里添加机器人，拿到 webhook 地址。
2. 把 key（或完整地址）放进环境变量 `WECOM_BOT_KEY`。
3. 选消息类型、套模板写内容。
4. 跑脚本预览（默认 dry-run），把预览给用户确认。
5. 用户明确说「发」之后，加 `--send` 发送，读返回的 errcode。
6. 接入定时任务或监控时，加合并、去重、分级。

**第 1 步 添加机器人**（通用步骤，以企业微信客户端当前界面为准）：打开目标群 → 群设置或群信息页 → 找「群机器人 / 添加机器人」相关入口 → 新建并命名（写清用途，如「订单告警」）→ 复制 webhook 地址，`key=` 后面就是 key。找不到入口：客户端版本、群类型或企业设置都可能限制，问企业微信管理员。完整步骤与排查见 [references/setup-and-security.md](references/setup-and-security.md)。

**第 2 步 放 key**（只在用户自己的终端执行，不要贴到对话里）：

```bash
export WECOM_BOT_KEY='<从群机器人复制的 key 或完整 webhook 地址>'
```

CI 用平台的密钥变量；`.env` 必须进 `.gitignore`；多个群一个群一个变量，发送时用 `--key-env WECOM_BOT_KEY_OPS`。

**第 3 步 选类型**：

| | text | markdown |
|---|---|---|
| @ 人 | `--at-mobile` 传手机号（据官方文档 `@all` 表示所有人，慎用） | 据官方文档只能在正文写 `<@userid>`，不支持 @ 手机号 |
| 格式 | 纯文本 | 标题、加粗、链接、引用、行内代码、三种字体颜色 |
| 参考上限（据公开文档，以官方文档为准） | 2048 字节 | 4096 字节 |
| 适合 | 要 @ 人的告警、提醒 | 日报、带链接的通知 |

markdown 写法要点、日报/告警/提醒模板、拆条与合并方法见 [references/markdown-and-templates.md](references/markdown-and-templates.md)。

**第 4–5 步 预览与发送**（路径相对本技能目录）：

```bash
python3 scripts/wecom_bot_send.py --type text --content "【提醒】今晚 22:00 发布，值班同学请在线" --at-mobile 13800000000
python3 scripts/wecom_bot_send.py --type markdown --file daily.md            # 只预览
python3 scripts/wecom_bot_send.py --type markdown --file daily.md --send     # 用户确认后
python3 scripts/wecom_bot_send.py --selftest                                 # 本机假接收端自测，不访问外网
```

脚本行为：不加 `--send` 只打印目标地址（key 打码）、字节数、正文和请求体；超时默认 10 秒，网络错误、超时、HTTP 5xx、errcode -1 最多重试 2 次；45009 不自动重试；`--endpoint` 只允许官方地址或本机地址，防止 key 被发到别处。想看请求体长什么样，另开终端起 `python3 scripts/fake_webhook_server.py --port 8765`，再把 `--endpoint` 指向 `http://127.0.0.1:8765/cgi-bin/webhook/send`。

**errcode 怎么读**（只列含义确定的；官方说明见企业微信开发者中心「全局错误码」，章节名以文档站为准）：

| errcode | 含义 | 处理 |
|---|---|---|
| 0 | 成功 | — |
| -1 | 系统繁忙（通用含义） | 脚本自动重试；持续出现就暂停 |
| 45009 | 调用频率超限 | 合并、降频，等一个限流窗口再发 |
| 93000 | webhook 地址无效 | 核对 key 是否抄全；机器人被移除就重新添加 |
| 其他 | 以官方文档为准 | 原样给出 errmsg，查「全局错误码」 |

**频率控制**：官方有频率限制，具体以文档为准。发送方自己合并同窗口告警、按「服务 + 指标 + 级别」去重、只有最高级别才 @ 人、多个任务共用一个发送进程排队。不要多建机器人轮流发来绕限额。

**key 泄露**：先在群里移除机器人并重新添加拿新 key（止血），再更新所有使用方，最后清理聊天记录与 git 历史——顺序不能反。完整步骤见 [references/setup-and-security.md](references/setup-and-security.md)。

## 信息不全或出错时

| 情况 | 怎么处理 | 对用户说的话（模板） |
|---|---|---|
| 缺关键信息 | 只问 3 个：发到哪个群（机器人加好没）、发什么（日报/告警/提醒）、要不要 @ 人；其余按默认（text、不 @、dry-run），交付物里标 [待确认] | 「先确认三件事：群、内容类型、要不要 @ 人；其他我先按默认写，标了 [待确认]。」 |
| 用户把 key 或完整地址贴进对话 | 不复述、不写进任何文件或命令；建议立即换 key | 「key 已经出现在对话里，建议移除这个机器人重新添加拿新 key，之后只放环境变量，不要再贴出来。」 |
| 要求自相矛盾：markdown 又要 @ 手机号 | 指出矛盾，给两个方案 | 「markdown 不支持 @ 手机号。二选一：①改 text 并 @；②先发 markdown，再补一条 text 只做 @。」 |
| 内容超过参考上限 | 拆成摘要 + 链接，或精简 | 「正文 5100 字节，超过参考上限，我改成 5 行摘要 + 详情链接。」 |
| 时间紧，只要最小可用版 | 给三条命令 + 一个模板：`export`、dry-run 预览、确认后 `--send`，加一条 text 提醒模板 | 「先给最小版：三条命令一个模板，合并去重等跑通再加。」 |
| 超出范围：收消息、按钮、发给个人、个人微信 | 企业微信应用开发转官方开发者中心；个人微信自动化不做 | 「群机器人只能往它所在的群单向发。发给个人要走企业微信应用，需要管理员配置。」 |
| 用户坚持「别给我看，直接发」 | 仍先给一屏预览，确认后再发；定时任务只在第一条确认过的模板上自动发 | 「发出去撤不回，我先给你看一屏预览，你回『发』我就执行。」 |

脚本退出码：

| 退出码 / 报错 | 原因 | 修正办法 |
|---|---|---|
| 0 | 发送成功，或预览完成 | — |
| 1「没有找到环境变量」 | 没设 key | 在自己终端 `export WECOM_BOT_KEY=...` |
| 1「key 格式不对」 | 复制时带了空格、引号或中文 | 重新复制 key 或完整地址 |
| 1「markdown…不支持 @手机号」 | 类型与 @ 冲突 | 改 `--type text`，或拆两条 |
| 1「--endpoint 只允许…」 | 防止 key 外发 | 用默认官方地址，测试时用本机地址 |
| 2 | 文件找不到或不是 UTF-8 | 检查路径；另存为 UTF-8 |
| 3 | 网络错误、超时、HTTP 非 200（已重试） | 查网络和代理；超时可能已送达，先看群里再决定重发 |
| 4 | errcode≠0 或返回非 JSON | 按上面的 errcode 表处理 |
| 5 | `--selftest` 未通过 | 把输出原样贴出来排查 |
| 130 | Ctrl+C 中断 | 中断后不会继续发送 |

## 输出契约

交付物按这个顺序，缺哪块写「不适用」，不跳号：
1. 结论一句话：发什么、发到哪个群、什么时候发。
2. 环境变量设置或检查命令（只出现变量名，不出现值）。
3. 消息正文（套好模板）。
4. 预览命令 + 预览输出摘要。
5. 发送命令，标注「等你确认后再运行」。
6. 定时或频率控制方案（适用时）。
7. 待确认项与风险。

占位符：用户没给的写 [待补]；推断出来的写 [待确认]；手机号只用用户给的，不编。

交付前自检（逐条判是/否）：
- [ ] 全文没有真实 key 或完整 webhook 地址，只有 `$WECOM_BOT_KEY` 这类变量名。
- [ ] 默认命令不带 `--send`；带 `--send` 的命令都标了「确认后」。
- [ ] markdown 消息没有配 `--at-mobile`。
- [ ] 正文在参考字节上限内，或已拆条并说明。
- [ ] errcode 只解释表里 4 个，其余写了「以官方文档为准」。
- [ ] 界面操作都注明「以企业微信客户端当前界面为准」。

## 示例

> 示例对话，人名、手机号、链接均为虚构。

**用户**：每天下班前想把发布情况推到研发群，内容我自己写。

**助手**：先确认两件事：①机器人加好了吗？key 请你自己放进环境变量 `WECOM_BOT_KEY`，不要贴给我；②要不要 @ 人？要 @ 就得用 text 类型。

**用户**：加好了，变量也设了，不用 @。

**助手（交付物）**：

1. 结论：用 markdown 发日报到研发群，每天由你写好 `daily.md` 后运行命令；不 @ 人。
2. 检查变量：`python3 -c "import os;print('已设置' if os.environ.get('WECOM_BOT_KEY') else '未设置')"`
3. 正文 `daily.md`：

```
## 【日报】支付服务 2026-09-26
> 整体：<font color="info">正常</font>
**今日完成**
1. 灰度 20% → 50%
2. 修复退款对账差异
**风险**：<font color="warning">周五前需确认压测资源</font>
[查看详情](https://example.com/report/0926)
```

4. 预览：`python3 scripts/wecom_bot_send.py --type markdown --file daily.md`，输出里应看到「消息类型：markdown」「内容字节：270 / 参考上限 4096」「DRY-RUN：没有发送任何请求」。
5. 确认后发送：同一条命令末尾加 `--send`，看到「结果：errcode=0（成功）」即完成。
6. 定时：先手动发一周，格式稳定后再挂定时任务（写法见 [references/setup-and-security.md](references/setup-and-security.md)）。
7. 待确认：[待确认] 日报发送时间是否固定在 18:00。

更完整的示例（告警 + @ 值班人 + 去重 + 本机假接收端的真实输出）见 [examples/alert-push.md](examples/alert-push.md)。

## 常见问题（FAQ）

**能不能直接帮我发？** 可以替你运行发送命令，但一定先给预览、你回复确认后才加 `--send`；key 由你放进环境变量，我不在对话里接收。

**text 和 markdown 选哪个？** 要 @ 手机号就用 text；要标题、颜色、链接就用 markdown；两样都要就发两条。

**怎么 @ 所有人？** text 类型的手机号列表写 `@all`（据官方文档，以文档为准），脚本里是 `--at-mobile @all`。只在真正需要全员处理时用。

**能发图片、文件吗？** 官方文档还列有图片、图文、文件等类型（以文档为准）；本脚本只实现 text 和 markdown，需要时按文档扩展，同样先预览。

**超时了要不要重发？** 超时的请求可能已经送达。先看群里有没有收到；重要通知用 `--retries 0`，避免重复。

**和企业微信「应用消息」有什么区别？** 群机器人只能往它所在的群单向发；应用消息能发给个人或部门、能接收回调，但要管理员创建应用。

**没有真实群，怎么先试？** 运行 `--selftest`，或起 `fake_webhook_server.py` 后把 `--endpoint` 指到本机，全程不访问外网。

## 常见错误（反模式）

- 把完整 webhook 地址写进代码、截图或工单 → 任何拿到的人都能往群里发 → 只放环境变量，输出打码。
- 一条告警发一次、不合并 → 触发频率限制，群里刷屏没人看 → 合并、去重、分级。
- 被限流后立刻重试，或多建机器人轮流发 → 越试越限，还绕了平台规则 → 等一个窗口，降低频率。
- 在 markdown 里写 @手机号 → 不会生效 → 用 text，或正文写 `<@userid>`。
- 不预览直接 `--send` → 发错群、发错内容 → 先 dry-run，确认后再发。
- 日报塞全文 → 超过上限被拒、没人读完 → 3–5 行摘要 + 链接。
- 超时就重发 → 群里出现重复消息 → 先看群里，再决定。

## 边界与不做什么

- 不做个人微信、微信群的自动化（外挂、模拟点击、协议破解），不刷量，不批量拉群或加好友，不爬取他人数据。
- 不在对话里接收、保存或复述 key；不把 key 写进文件、命令行参数或日志。
- 不帮用户绕过频率限制。
- 不发送用户没确认过的内容；定时任务只用确认过的模板。
- 告警和日报里不放密码、令牌、身份证号、客户个人信息。
- 界面按钮、配额、字段以企业微信官方文档与客户端为准，本技能不编造。