dingtalk-message

钉钉消息发送技能

概述

支持两种接入方式：

• 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 描述用途，方便智能匹配：

{
    "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。

通过命令行添加

# 添加 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 "支持单聊群聊"

验证配置

python scripts/dingtalk.py config --show

机器人管理

选择逻辑

• 只配置一个机器人时，自动使用
• 多个机器人时：--robot 指定 > default_robot > 最近使用过的 > 第一个可用的
• 用户未明确指定时，可根据机器人的 description 和最近消息记录智能匹配，或询问用户

管理命令

# 添加（--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 地址

文本消息

# 已配置时直接发送
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 消息

python scripts/dingtalk.py webhook-markdown \
    --title "天气提醒" \
    "#### 杭州天气\n> 9度，西北风1级"

链接消息

python scripts/dingtalk.py webhook-link \
    --title "时代在进步" \
    --url "https://www.dingtalk.com" \
    --pic-url "https://example.com/image.png" \
    "点击查看详情"

ActionCard 消息

# 单按钮
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 消息

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"

加签安全

# 配置加签密钥（一次设置）
python scripts/dingtalk.py config --set webhook_secret=SECxxxxxxxxxxxxxxxxxxxxxxxxxx

# 或通过参数临时指定
python scripts/dingtalk.py webhook-text \
    --webhook-token "access_token_xxx" \
    --webhook-secret "SECxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    "带加签的消息"

企业内部机器人消息

单聊消息

# 文本
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"

群聊消息

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))、图片(![](url))、无序列表(-)、有序列表(1.)、引用(>)

不支持（禁止使用）： 分隔线(---)、表格、代码块、行内代码、删除线、任务列表、斜体、嵌套列表

脚本会自动移除分隔线 ---，但其他不支持的语法需要手动避免。

常见错误码

企业内部机器人： 40001(token过期) / 40004(无效机器人) / 40009(用户不在可见范围) / 40010(未建立会话) / 40037(发送过频)

Webhook： 300001(无效token) / 310000(签名校验失败) / 302503(频率限制，每分钟20条)

注意事项

• 频率限制：企业内部机器人每秒20次，Webhook每分钟20条
• Webhook 仅群聊：不支持单聊，link/feedCard 不支持 @功能
• 单聊前置条件：用户需先主动给机器人发过消息
• 批量限制：单次最多发送100个用户
• 消息长度：过长内容建议拆分或使用文件发送