Merge pull request #9 from MaekBlack/wecomrobot

feat: 企业微信机器人推送文本消息

Author: hao65103940

tools/wecomrobot/1.0.0/企业微信机器人消息推送.tool

@@ -0,0 +1,121 @@
+# 企业微信机器人推送工具
+
+基于企业微信群机器人 Webhook API 封装的 Python 消息推送工具函数，支持文本消息发送、@成员提醒、全员通知等功能，适用于告警通知、日报推送、自动化运维等场景。
+
+## 一、项目介绍
+
+### 1.1 核心功能
+
+- **文本消息推送**：向企业微信群发送自定义文本消息，支持多行文本、特殊字符等内容。
+- **@成员提醒**：支持 @指定成员（通过手机号）或 @全体成员，确保重要消息及时触达。
+- **智能错误处理**：对 API 错误（如 key 无效、消息格式错误）、网络异常等进行分类捕获，输出清晰的错误提示。
+- **会话管理优化**：使用 `requests.Session` 复用连接，提升批量推送性能。
+- **简洁接口设计**：仅需 4 个参数即可完成消息推送，降低集成成本。
+
+### 1.2 适用场景
+
+- **系统告警通知**：服务器异常、接口报错、磁盘空间不足等告警信息实时推送到运维群。
+- **自动化运维**：定时任务执行结果、脚本运行日志、数据备份状态等通知。
+- **业务消息提醒**：订单状态变更、用户注册通知、数据统计报表等业务消息推送。
+- **CI/CD 集成**：构建成功/失败通知、部署进度提醒、代码审查消息等。
+- **日报周报推送**：定时推送团队工作总结、数据分析报告等。
+
+---
+
+## 二、环境准备
+
+### 2.1 依赖库
+
+该工具基于 Python 标准库与 `requests` 库构建，依赖列表如下：
+
+| 依赖库     | 版本要求  | 用途说明               |
+| ---------- | --------- | ---------------------- |
+| `requests` | ≥ 2.20.0  | 发送 HTTP POST 请求    |
+
+### 2.2 安装依赖
+
+通过 `pip` 安装 `requests` 库：
+
+```bash
+pip install requests
+```
+
+---
+
+## 三、使用说明
+
+### 3.1 获取机器人 Webhook 地址
+
+使用前需在企业微信群中添加机器人并获取 Webhook 地址：
+
+1. **创建群聊机器人**：
+    - 在企业微信 PC 端或移动端打开目标群聊
+    - 点击右上角 `...` → `群机器人` → `添加群机器人`
+    - 为机器人命名（如"告警机器人"）并点击 `添加`
+
+2. **获取 Webhook Key**：
+    - 添加成功后，系统会生成 Webhook 地址：
+      ```
+      https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+      ```
+    - 其中 `key=` 后面的部分即为 `accessKey`（如 `693a91f6-7xxx-4bc4-97a0-0ec2sifa5aaa`）
+
+3. **安全配置**（可选）：
+    - 可设置 IP 白名单、消息加密等安全策略
+    - 详见 [企业微信机器人配置指引](https://developer.work.weixin.qq.com/document/path/91770)
+
+> **注意**：每个机器人每分钟最多发送 **20 条消息**，超限后会被限流。
+
+---
+
+### 3.2 函数定义
+
+```python
+def wecomrobot(push_message, accessKey, is_at_all, at_mobiles):
+    """
+    企业微信机器人推送文本消息
+    
+    参数:
+        push_message (str): 要推送的文本消息内容
+        accessKey (str): 企业微信机器人的 Webhook Key
+        is_at_all (bool): 是否 @所有人
+        at_mobiles (list): 要 @的成员手机号列表，默认为空列表
+    
+    返回:
+        无返回值，通过 print 输出推送结果
+    
+    功能说明:
+        - 成功：打印 "信息：企业微信机器人推送成功。"
+        - 失败：打印错误码和错误原因
+        - 异常：打印网络错误或响应解析错误
+    """
+```
+
+---
+
+### 3.3 参数说明
+
+#### 必需参数
+
+| 参数名         | 类型  | 说明                   | 示例                    |
+| :------------- |:----|:---------------------|:----------------------|
+| `push_message` | str | 要推送的文本消息内容           | `'服务器 CPU 使用率超过 80%'` |
+| `accessKey`    | str | 企业微信机器人的 Webhook Key | `'xxxxxx'`            |
+| `is_at_all`    | int | 是否 @所有人（1 表示 @all）   | `1` 或 `0`             |
+
+#### 可选参数
+
+| 参数名       | 类型 | 默认值  | 说明                                                   |
+| :----------- | :--- |:-----| :----------------------------------------------------- |
+| `at_mobiles` | list | `""`   | 要 @的成员手机号列表（需与企业微信绑定的手机号一致）   |
+
+#### 参数组合说明
+
+| 场景                 | `is_at_all` | `at_mobiles`                 | 效果                           |
+| :------------------- |:------------|:-----------------------------| :----------------------------- |
+| 普通消息             | `0`         | `""`                         | 仅发送消息，不 @任何人         |
+| @全体成员            | `1`         | `""`                         | 消息会 @所有人                 |
+| @指定成员            | `0`         | `"13800138000, 13900139000"` | 消息会 @这两个手机号对应的成员 |
+| @全体 + @指定成员    | `1`         | `"13800138000"`               | 消息会 @所有人，并额外 @指定成员 |
+
+---

tools/wecomrobot/README.md

@@ -0,0 +1,5 @@
+name: 企业微信群聊机器人消息推送
+tags:
+  - 消息推送
+title: 企业微信群聊机器人消息推送
+description: 基于企业微信群机器人 Webhook API 封装的 Python 消息推送工具函数，支持文本消息发送、@成员提醒、全员通知等功能，适用于告警通知、日报推送、自动化运维等场景。