feat: 钉钉群机器人推送工具

tools/dingrobot/README.md

@@ -0,0 +1,129 @@
+# 钉钉群机器人推送工具
+
+基于钉钉群机器人 Webhook API 封装的 Python 消息推送工具函数，支持文本消息发送、安全签名认证、@成员提醒、全员通知等功能，适用于告警通知、日报推送、自动化运维等场景。
+
+## 一、项目介绍
+
+### 1.1 核心功能
+
+- **文本消息推送**：向钉钉群发送自定义文本消息，支持多行文本、特殊字符等内容。
+- **安全签名机制**：支持 HMAC-SHA256 签名验证，防止 Webhook 地址被恶意调用，确保消息来源可信。
+- **@成员提醒**：支持 @指定成员（通过手机号）或 @全体成员，确保重要消息及时触达。
+- **智能错误处理**：对 API 错误（如 token 无效、签名错误）、网络异常等进行分类捕获，返回清晰的错误信息。
+- **会话管理优化**：使用 `requests.Session` 复用连接，提升批量推送性能。
+- **灵活参数设计**：自动处理空参数（如 `at_mobiles=""`），降低调用复杂度。
+
+### 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 被滥用
+    - **IP 地址（段）**：只允许指定 IP 地址访问
+
+   **本工具支持"加签"方式**，勾选后系统会生成密钥（Secret）。
+
+3. **获取凭证**：
+    - **Webhook 地址**：
+      ```
+      https://oapi.dingtalk.com/robot/send?access_token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+      ```
+    - **access_token**：URL 中 `access_token=` 后面的部分
+    - **secret**：如果选择"加签"方式，复制生成的密钥（如 `SECxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`）
+
+> **注意**：每个机器人每分钟最多发送 **20 条消息**，超限后会被限流 10 分钟。
+
+---
+
+### 3.2 函数定义
+
+```python
+def dingrobot(push_message, access_token, secret, is_at_all, at_mobiles):
+    """
+    钉钉群机器人推送文本消息
+
+    参数:
+        push_message (str): 要推送的文本消息内容
+        access_token (str): 钉钉机器人的 Access Token
+        secret (str): 钉钉机器人的密钥（使用加签安全设置时必填）
+        is_at_all (bool): 是否 @所有人
+        at_mobiles (str): 要 @的成员手机号列表""
+
+    返回:
+        str: 推送结果信息
+            - 成功: "信息：钉钉机器人推送成功。"
+            - 失败: "错误：钉钉机器人推送失败：{错误原因}"
+            - 异常: "错误：发送钉钉机器人消息时发生网络错误: {异常详情}"
+    """
+```
+
+---
+
+### 3.3 参数说明
+
+#### 必需参数
+
+| 参数名         | 类型  | 说明                  | 示例                    |
+| :------------- |:----|:--------------------|:----------------------|
+| `push_message` | str | 要推送的文本消息内容          | `'服务器 CPU 使用率超过 80%'` |
+| `access_token` | str | 钉钉机器人的 Access Token | `'xxxxxx'`            |
+| `secret`       | str | 钉钉机器人的密钥（加签方式必填）    | `'xxxxxx'`            |
+| `is_at_all`    | int | 是否 @所有人（1 表示 @all）  | `1` 或 `0`             |
+
+#### 可选参数
+
+| 参数名         | 类型       | 说明                                       | 示例                                       |
+| :------------- |:---------| :----------------------------------------- |:-----------------------------------------|
+| `at_mobiles`   | str      | 要 @的成员手机号列表  | `"13800138000, 13900139000"`      |
+
+
+#### 参数组合说明
+
+| 场景                 | `is_at_all` | `at_mobiles`                 | 效果                           |
+| :------------------- |:------------|:-----------------------------| :----------------------------- |
+| 普通消息             | `0`         | `""`                         | 仅发送消息，不 @任何人         |
+| @全体成员            | `1`         | `""`                         | 消息会 @所有人                 |
+| @指定成员            | `0`         | `"13800138000, 13900139000"` | 消息会 @这两个手机号对应的成员 |
+| @全体 + @指定成员    | `1`         | `"13800138000"`               | 消息会 @所有人 |
+
+---

tools/dingrobot/data.yaml

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