dingtalk-message · v0.3.0 · 2026-07-22 · sha256 4b9c165d2366fac9
dingtalk-message v0.3.0A
Immutable. This exact content is served forever at /api/v1/blob/4b9c165d2366fac9.
---
name: dingtalk-message
version: 0.3.0
description: 钉钉消息发送技能。支持企业内部机器人（批量单聊/群聊）和 Webhook 自定义机器人两种接入方式，支持多机器人管理，支持文本、Markdown、链接、ActionCard、FeedCard等多种消息类型。
---
# 钉钉消息发送技能
## 概述
支持两种接入方式：
- **Webhook 自定义机器人**：通过 access_token 向群聊发送消息，接入简单
- **企业内部机器人**：通过 app_key/app_secret 发送单聊、群聊消息，功能更全
支持多机器人管理，只有一个时自动使用，多个时按优先级自动选择。
## 环境要求
- Python 3.7+
- `pip install requests`
## 首次配置
### 引导流程
首次使用此技能时，必须按以下流程引导用户完成配置：
1. **询问用户的机器人类型和凭证信息**：
- Webhook 机器人：需要 `access_token`（和可选的加签密钥 `secret`）
- 企业内部机器人：需要 `app_key`、`app_secret`、`robot_code`（和可选的 `agent_id`）
2. **执行配置命令**：`python scripts/dingtalk.py robot-add --name "机器人名" --type webhook ...`
3. **验证配置**：`python scripts/dingtalk.py config --show`
### 配置文件路径
配置统一存储在系统配置目录，所有 AI agent 共享，无需重复配置：
| 平台 | 配置文件 | 状态文件 |
|------|---------|---------|
| macOS / Linux | `~/.config/dingtalk/config.json` | `~/.config/dingtalk/state.json` |
| Windows | `%APPDATA%\dingtalk\config.json` | `%APPDATA%\dingtalk\state.json` |
### 手动编辑配置文件
也可直接编辑配置文件，每个机器人用 `name` 标识（建议用群名、用途等有意义的名称），`description` 描述用途，方便智能匹配：
```json
{
"default_robot": "技术告警群",
"robots": [
{
"name": "技术告警群",
"type": "webhook",
"description": "发送技术告警到后端技术群",
"webhook_token": "你的access_token",
"webhook_secret": ""
},
{
"name": "内部通知机器人",
"type": "app",
"description": "企业内部机器人，支持单聊和群聊",
"app_key": "你的AppKey",
"app_secret": "你的AppSecret",
"robot_code": "你的机器人编号",
"agent_id": ""
}
]
}
```
> `webhook_token` 填 access_token 即可，脚本自动拼接完整 URL。
### 通过命令行添加
```bash
# 添加 Webhook 机器人
python scripts/dingtalk.py robot-add --name "技术告警群" --type webhook --webhook-token "access_token_xxx" --desc "发送告警到后端技术群"
# 添加企业内部机器人
python scripts/dingtalk.py robot-add --name "内部通知" --type app --app-key dingxxx --app-secret xxx --robot-code robot-xxx --desc "支持单聊群聊"
```
### 验证配置
```bash
python scripts/dingtalk.py config --show
```
## 机器人管理
### 选择逻辑
- 只配置一个机器人时，自动使用
- 多个机器人时：`--robot` 指定 > `default_robot` > 最近使用过的 > 第一个可用的
- 用户未明确指定时，可根据机器人的 `description` 和最近消息记录智能匹配，或询问用户
### 管理命令
```bash
# 添加（--desc 描述用途，便于记忆和智能选择）
python scripts/dingtalk.py robot-add --name "技术告警群" --type webhook --webhook-token "access_token_xxx" --desc "发送告警到后端技术群"
python scripts/dingtalk.py robot-add --name "内部通知" --type app --app-key dingxxx --app-secret xxx --robot-code robot-xxx --desc "企业内部机器人，支持单聊群聊"
# 查看所有机器人（含描述、使用次数、最近消息）
python scripts/dingtalk.py robot-list
# 更新描述 / 重命名
python scripts/dingtalk.py robot-update --name "技术告警群" --desc "后端+SRE告警群"
python scripts/dingtalk.py robot-update --name "alert-bot" --rename "技术告警群"
# 指定机器人发送
python scripts/dingtalk.py webhook-text --robot "技术告警群" "告警消息"
# 设置默认 / 启用禁用 / 删除
python scripts/dingtalk.py robot-default --name "产品日报群"
python scripts/dingtalk.py robot-enable --name "技术告警群" --disable
python scripts/dingtalk.py robot-remove --name "技术告警群"
```
### 使用记录
每次发送消息会自动记录摘要到状态文件，包括：
- 使用次数、最近使用时间、最近状态
- 最近10条消息摘要（消息类型 + 内容前60字）
通过 `robot-list` 可查看，也用于智能选择机器人。
## Webhook 消息
> Webhook 命令以 `webhook-` 前缀开头。
> Webhook URL 获取：钉钉群 > 群设置 > 智能群助手 > 添加自定义机器人 > 复制 Webhook 地址
### 文本消息
```bash
# 已配置时直接发送
python scripts/dingtalk.py webhook-text "消息内容"
# 临时指定 token（无需配置）
python scripts/dingtalk.py webhook-text --webhook-token "access_token_xxx" "消息内容"
# @用户 / @所有人
python scripts/dingtalk.py webhook-text --at-mobiles 13800138000 "消息 @13800138000"
python scripts/dingtalk.py webhook-text --at-all "全员通知"
```
### Markdown 消息
```bash
python scripts/dingtalk.py webhook-markdown \
--title "天气提醒" \
"#### 杭州天气\n> 9度，西北风1级"
```
### 链接消息
```bash
python scripts/dingtalk.py webhook-link \
--title "时代在进步" \
--url "https://www.dingtalk.com" \
--pic-url "https://example.com/image.png" \
"点击查看详情"
```
### ActionCard 消息
```bash
# 单按钮
python scripts/dingtalk.py webhook-action-card \
--title "审批通知" \
--single-title "查看详情" \
--url "https://www.dingtalk.com" \
"#### 请假申请\n请审批"
# 多按钮
python scripts/dingtalk.py webhook-action-card \
--title "审批通知" \
--buttons "同意,https://approve.com/yes;拒绝,https://approve.com/no" \
--btn-orientation 0 \
"#### 请假申请"
```
### FeedCard 消息
```bash
python scripts/dingtalk.py webhook-feed-card \
--links "新闻1,https://news1.com,https://img1.com/pic.png;新闻2,https://news2.com,https://img2.com/pic.png"
```
### 加签安全
```bash
# 配置加签密钥（一次设置）
python scripts/dingtalk.py config --set webhook_secret=SECxxxxxxxxxxxxxxxxxxxxxxxxxx
# 或通过参数临时指定
python scripts/dingtalk.py webhook-text \
--webhook-token "access_token_xxx" \
--webhook-secret "SECxxxxxxxxxxxxxxxxxxxxxxxxxx" \
"带加签的消息"
```
## 企业内部机器人消息
### 单聊消息
```bash
# 文本
python scripts/dingtalk.py text "Hello!" --users user001,user002
# Markdown
python scripts/dingtalk.py markdown --title "天气提醒" --users user001 \
"#### 杭州天气\n> 9度，西北风1级"
# 链接
python scripts/dingtalk.py link --title "时代在进步" --url "https://www.dingtalk.com" \
--users user001 "点击查看详情"
# ActionCard
python scripts/dingtalk.py action-card --title "审批通知" \
--single-title "查看详情" --url "https://www.dingtalk.com" \
--users user001 "#### 请假申请\n请审批"
# 文件
python scripts/dingtalk.py file --users user001 --file /path/to/report.pdf --file-name "月度报告.pdf"
```
### 群聊消息
```bash
python scripts/dingtalk.py text "大家好！" \
--mode group \
--conversation-id chatxxxxxxxxxxxxxxxx \
--at-mobiles 13800138000,13900139000
```
## CLI 语法规则
1. `content` 是位置参数（无 `--` 前缀），放在可选参数之后
2. 换行使用 `\n`，脚本自动处理转换
3. `content` 必须用双引号包裹
4. 可通过 `--app-key`、`--robot-code` 等参数临时覆盖配置文件
## 钉钉 Markdown 语法限制
钉钉 Markdown 只支持有限子集，构造内容时必须遵守：
**支持：** 标题(`#`)、加粗(`**`)、链接(`[](url)`)、图片(``)、无序列表(`-`)、有序列表(`1.`)、引用(`>`)
**不支持（禁止使用）：** 分隔线(`---`)、表格、代码块、行内代码、删除线、任务列表、斜体、嵌套列表
> 脚本会自动移除分隔线 `---`，但其他不支持的语法需要手动避免。
## 常见错误码
**企业内部机器人：** 40001(token过期) / 40004(无效机器人) / 40009(用户不在可见范围) / 40010(未建立会话) / 40037(发送过频)
**Webhook：** 300001(无效token) / 310000(签名校验失败) / 302503(频率限制，每分钟20条)
## 注意事项
- **频率限制**：企业内部机器人每秒20次，Webhook每分钟20条
- **Webhook 仅群聊**：不支持单聊，link/feedCard 不支持 @功能
- **单聊前置条件**：用户需先主动给机器人发过消息
- **批量限制**：单次最多发送100个用户
- **消息长度**：过长内容建议拆分或使用文件发送