wechaty-puppet-dingding

Wechaty Puppet 实现，基于钉钉 Stream 模式接入钉钉机器人。

功能

• 接收私聊和群聊文本消息
• 接收图片、音频、视频、文件消息并下载
• 发送文本消息（支持 Markdown 自动检测）
• 发送图片和文件
• 发送链接卡片
• 群消息 @ 用户
• 基于 sessionWebhook 快速回复，超时自动降级到 HTTP API

前置条件

1. 在钉钉开放平台创建一个应用
2. 应用类型选择企业内部应用
3. 在「应用功能」中开启机器人
4. 在「消息接收模式」中选择 Stream 模式
5. 记录应用的 ClientID（即 AppKey）和 ClientSecret（即 AppSecret）

安装

npm install wechaty-puppet-dingding

快速开始

import { PuppetDingTalk } from 'wechaty-puppet-dingding'
import { WechatyBuilder } from '@juzi/wechaty'

const puppet = new PuppetDingTalk({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  robotCode: 'your_robot_code', // 通常与 clientId 相同
})

const bot = WechatyBuilder.build({ puppet })

bot.on('message', async (message) => {
  if (message.text() === 'ping') {
    await message.say('pong')
  }
})

await bot.start()

配置项

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | clientId | string | 是 | 钉钉应用的 AppKey | | clientSecret | string | 是 | 钉钉应用的 AppSecret | | robotCode | string | 是 | 机器人标识，通常与 clientId 相同 |

运行示例

# 设置环境变量
export DINGTALK_CLIENT_ID=your_client_id
export DINGTALK_CLIENT_SECRET=your_client_secret
export DINGTALK_ROBOT_CODE=your_robot_code

# 运行完整示例（支持图片/文件/Markdown/群发等测试指令）
npm run example

# 运行简单示例
npm run example:simple

示例支持的测试指令

在钉钉中 @ 机器人发送以下文字：

| 指令 | 效果 | |------|------| | ping | 回复 pong | | help | 显示命令列表（Markdown） | | info | 显示机器人信息（Markdown） | | 图片 | 机器人发送一张图片 | | 文件 | 机器人发送一个 PDF | | 文字 | 机器人发送 Markdown 格式文本 | | 群发 | 向指定群发文本（需设置 TEST_ROOM_TOPIC） | | 群图片 | 向指定群发图片（需设置 TEST_ROOM_TOPIC） |

发送消息

文本 / Markdown

发送内容中包含 Markdown 语法时（如 ## 、**、>、| 等）会自动识别并以 Markdown 格式发送：

// 普通文本
await message.say('你好')

// Markdown（自动检测）
await message.say('## 标题\n- 列表项\n> 引用')

图片 / 文件

import { FileBox } from '@juzi/file-box'

// 从 URL 发送图片
const image = FileBox.fromUrl('https://example.com/image.jpg', { name: 'image.jpg' })
await message.say(image)

// 从本地文件发送
const file = FileBox.fromFile('/path/to/document.pdf')
await message.say(file)

群消息 @ 用户

bot.on('message', async (message) => {
  const room = message.room()
  const sender = message.talker()

  if (room) {
    // 回复并 @ 发送者
    await room.say('收到！', [sender])
  }
})

接收文件

收到图片/音频/视频/文件消息时，通过 toFileBox() 下载：

import * as PUPPET from '@juzi/wechaty-puppet'

bot.on('message', async (message) => {
  const fileTypes = [
    PUPPET.types.Message.Image,
    PUPPET.types.Message.Audio,
    PUPPET.types.Message.Video,
    PUPPET.types.Message.Attachment,
  ]

  if (fileTypes.includes(message.type())) {
    const fileBox = await message.toFileBox()
    await fileBox.toFile('./' + fileBox.name)
  }
})

下载后的文件命名规则：

• 图片：钉钉图片_{时间戳}.jpg
• 语音：钉钉语音_{时间戳}.amr
• 视频：钉钉视频_{时间戳}.mp4
• 文件：原文件名_{时间戳}.扩展名

注意事项

• Stream 模式限制：机器人只能收到群内 @ 自己的消息，无法收到群内所有消息
• 私聊回复：必须先收到对方发来的消息，才能通过 API 主动发私聊（需要 senderStaffId）
• sessionWebhook 有效期：约 1 小时，超时后自动改用 HTTP API 发送
• 联系人列表：钉钉没有拉取通讯录的简单接口，联系人通过消息事件动态收集

开发

# 安装依赖
npm install

# 编译
npm run dist

# 监听模式编译
npm run dev

相关文档

• doc/wechaty-puppet-development-notes.md — Wechaty Puppet 框架开发经验（平台无关，可复用）
• doc/dingtalk-integration-notes.md — 钉钉平台接入经验
• 钉钉开放平台文档
• Wechaty 官网

License

MIT