基于开放 API 封装 Wechaty 接口下的钉钉聊天机器人

[rickyyin98]

此次活动

开源软件供应链点亮计划

“开源软件供应链点亮计划-暑期2020”（以下简称 暑期2020）是由中科院软件所与 openEuler 社区共同举办的一项面向高校学生的暑期活动，旨在鼓励在校学生积极参与开源软件的开发维护，促进国内优秀开源软件社区的蓬勃发展。
根据项目的难易程度和完成情况，参与者还可获取“开源软件供应链点亮计划-暑期2020”活动奖金和奖杯。
官网：https://isrc.iscas.ac.cn/summer2020 官方新闻：http://www.iscas.ac.cn/xshd2016/xshy2016/202004/t20200426_5563484.html

Wechaty

Wechaty 是一个开源聊天机器人框架SDK，具有高度封装、高可用的特性，支持NodeJs, Python, Go 和Java 等多语言版本。在过去的4年中，服务了数万名开发者，收获了 Github 的 8000 Star。同时配置了完整的DevOps体系并持续按照Apache 的方式管理技术社区。

基于开放 API 封装 Wechaty 接口下的钉钉聊天机器人

需求介绍

钉钉提供开放的API接口，有基于开放API开发聊天机器人的需求

钉钉（DingTalk）是阿里巴巴集团专为中国企业打造的免费沟通和协同的多端平台，提供PC版、Web版和手机版。它开放了丰富的服务端接口能力，如企业通讯录管理、发送企业会话消息等功能。开发者可以借助这些接口能力，实现与钉钉集成打通的Chatbot。
钉钉的群机器人支持收发消息，且搭建了比较完善的Chatbot市场。

Wechaty是全球最大的开源聊天机器人框架，希望实现基于同一套应用层代码实现不同软件的聊天机器人

Wechaty 作为全球最大的聊天机器人开发者社区之一，提供了非常简单的接口实现，让开发者能够用6行代码就实现自己的一个聊天机器人，如果能把钉钉的聊天机器人封装到 Wechaty 里来，则可以大大简化企业内开发者的开发流程。
因为 Wechaty 是建立在 puppet 系统之上的，puppet 是 Wechaty 依赖的一层抽象层，它定义了底层各个 IM 接入方案需要实现的接口，也正是因为 puppet 抽象层的存在，让很多 Wechaty 开发者可以仅仅通过一个变量，就能够随意切换不同的底层 IM 接入。

项目难度

高（奖金：12000元）

导师联系方式

• 高原：句子互动CTO、前亚马逊工程师（gaoyuan@juzi.bot）
• 李佳芮：句子互动CEO、专注微信生态近10年（rui@juzi.bot）

项目产出目标

核心目标

钉钉 puppet

• 通过钉钉outgoing机制接收群聊消息
• 通过钉钉消息接口实现各类消息的发送
• 对接钉钉通讯录管理接口，获取企业通讯录信息
• 设计配置参数和流程
• 钉钉 puppet 的使用文档

项目技术栈

• 了解 javascript 语言
• 有 typescript 语言的使用经验优先
• 熟练使用 Github 的优先
• 如果你的学习能力超强，可以无视上面的技术要求

相关资料

• https://ding-doc.dingtalk.com/doc#/serverapi2/krgddi
• https://ding-doc.dingtalk.com/doc#/serverapi2/cqfmel
• https://wechaty.js.org/v/zh/

Link to #3 (Wechaty 社区暑期2020项目单)

[jihuayu]

你好，我是福州大学的一名大三的学生，希望能参加这个项目。
我研究了一下这个项目的要求，钉钉的 API 与 wechaty-puppet 这个模板库的 API 差异很大，比如钉钉的消息类型与微信的消息类型完全不一样，这是不是代表我们需要自己制作一个与 wechaty-puppet 平级的库来实现这个 API。
但是这个想法感觉与任务： 基于开放 API 封装 Wechaty 接口下的钉钉聊天机器人，大相径庭，如果我们设计了一个与 wechaty-puppet 平级的库，那么这不就与 Wechaty 接口不兼容了吗？所以我想问一下这个任务要怎么实现？
谢谢。

[windmemory]

@jihuayu 欢迎参与到这个项目中

我研究了一下这个项目的要求，钉钉的 API 与 wechaty-puppet 这个模板库的 API 差异很大，比如钉钉的消息类型与微信的消息类型完全不一样

消息类型确实是和微信是不同的，但是，本身 Wechaty 并不是局限于只做微信上的机器人，同时也希望能支持更多的平台来做机器人，并且希望能提供给用户一个轻松迁移自己机器人到各个平台上的能力。
所以这个地方，对于普通类型的消息，比如文字，所有的 IM 里面都是一样的，只是一段文字罢了，我们是可以统一成同样的结构的。除此之外，actionCard类型的消息其实和微信里的图文链接是很类似的格式。对于这两种消息，是可以统一起来的。至于其他的集中卡片类，或者feed类的消息，我们可以额外增加消息类型到 Wechaty 里面。
如果你了解过企业微信接口，你会发现，钉钉的 bot 接口和企业微信的接口很类似，如果我们将一些钉钉里面的，现在还不存在的消息类型增加到 Wechaty 里面，也可以方便后续企业微信接入的时候，复用同类型的消息。

这是不是代表我们需要自己制作一个与 wechaty-puppet 平级的库来实现这个 API。

这并不代表我们需要只做一个与 wechaty-puppet 平级的库，我们会扩展 wechaty-puppet 这个库来支持不同的平台。

而且本质上，chatbot 最主要的内容还是文字，而且现在很多 Wechaty 的开发者开发的 chatbot 也大多是基于文字消息的，如果能够有这个钉钉机器人，可以很方便的让其他的开发者把自己做好的 Wechaty 机器人迁移到钉钉上了。

[jihuayu]

@windmemory 谢谢您的回答。
我大致明白了，是不是说我们需要扩充 wechaty-puppet 这个库，然后我们的钉钉或其他的 puppet 并不需要实现所有的 API ，而是实现其中一部分合适的。

[windmemory]

@jihuayu 是的。对于不支持的接口，可以在用户调用的时候抛出异常，表示此接口不支持即可。只要基础的文字消息收发能够支持，就可以给很多开发者带来帮助了

[jihuayu]

好的谢谢，我现在去申请这个项目。

[jihuayu]

[基于开放 API 封装 Wechaty 接口下的钉钉聊天机器人] 进度报告

日期：07-18

本周完成的成果

• 一个简单的 ping-pong 机器人，见下图

本周遇到的困难和需要配合的地方

• this 指针乱飞导致找不到函数（通过打断点解决了）。
• eslint 运行出错（已经解决）。
• 10 次请求有多次请求处理一半就中断了（已解决，发现是 res.end() 调用位置有问题）。
• 需要实现太多的函数，全部写空实现在那里又占地方，目前是用 @ts-ignore 注释解决了。
• WebStrome 能否根据 eslint 规范自动格式化。

下周的开发计划和预计成果

• 完成钉钉机器人的接口，优化一下代码。

其他需要说明和同步的事项

• 申请钉钉开发者时，千万不要把项目名字叫做测试，test 等具有这种意思的名字，否则会导致一辈子都申请失败。
• 项目地址

[windmemory]

@jihuayu 很棒的进展，继续加油

---

需要实现太多的函数，全部写空实现在那里又占地方，目前是用 @ts-ignore 注释解决了。

这个也可以用函数内抛异常的方式暂时处理一下，如下：

public async someFunctionThatIsNotImplemented (arg1: number, arg2: string) {
  throw new Error(`someFunctionThatIsNotImplemented() not implemented. Args: ${arg1}, ${arg2}`)
}

这样可以避免一些typescript编译和eslint 检测的报错问题

---

WebStrome 能否根据 eslint 规范自动格式化。

我这边没用过WebStom（不是WebStome，没有最后面的e），之前用过Intellij，应该都差不多，你可以搜搜看应用市场吧，如果没有的话，估计就是没有了。
另外，wechaty社区里面很多人用VS Code 你可以考虑下，目前我就在用VS Code。如果VS Code想要自动根据eslint格式化，好像是有一个叫做preitter的插件可以用。

除此之外，可以在命令行通过如下指令让eslint帮你自动格式化：

eslint --fix --ignore-pattern node_modules/ "src/**/*.ts"

如果你的eslint没有安装在global环境里的话，可能你需要这个指令（这个要求你在本地开发目录里面安装了eslint）：

ts-node ./node_modules/.bin/eslint --fix --ignore-pattern node_modules/ "src/**/*.ts"

[jihuayu]

@windmemory
好的谢谢，主要是 vscode 不太习惯。我试试看 eslint --fix 。
函数内抛异常的方式我考虑一下，就是函数有点多，哈哈。

[windmemory]

空实现的一个小问题就是，当之后你的puppet已经逐渐成型，开始对接wechaty联调测试的时候，如果wechaty因为puppet某些接口没实现而导致了一些bug，空函数没办法很好的帮你定位到是哪个函数没实现而导致的，但是抛异常可以直接的告诉你是哪个函数，这个是写异常的优势~

当然，前期工作量的话，挨个函数写异常确实会有点麻烦

[huan]

@jihuayu Congratulations! It's a huge step that your puppet can run with Wechaty and passed our ding-dong-bot testing!

I'm looking forward to seeing your alpha version, and can not wait for testing your DingTalk puppet by myself!

[jihuayu]

[基于开放 API 封装 Wechaty 接口下的钉钉聊天机器人] 进度报告

日期：07-26

本周完成的成果

• 使用 webhook 机制发送消息
• 完成消息类型的 API 编写

现在支持使用更优雅的方式发送消息了。

import { PuppetDing } from '../src/mod'

const puppet = new PuppetDing({ robot:{ port:3000 } })
puppet.on('message', async i => {
  const mes = await puppet.messagePayload(i.messageId)
  if (/ping/gi.test(mes.text as string)) {
    for (let i = 0; i < 30; i++) {
      await puppet.messageSendText(mes.roomId as string, 'dong' + i)
    }
  }
})

本周遇到的困难和需要配合的地方

• 由于钉钉和原本 wechaty 的接口不一致，导致发送消息的函数不太一样。现在有两种可以解决的方式：
  • 定义更多的 Send 种类，如 messageSendMarkDown，messageSendSimpleAction 等等。
  • 只使用 messageSendText 接口，在调用前使用 JSON 格式化这个文本，如：puppet.messageSendText(roomId, new MarkDownMessage('# 111').toString())

下周的开发计划和预计成果

• 完成获取通讯录成员的功能

其他需要说明和同步的事项

• 项目地址

[windmemory]

本周遇到的困难和需要配合的地方

• 由于钉钉和原本 wechaty 的接口不一致，导致发送消息的函数不太一样。现在有两种可以解决的方式：

  • 定义更多的 Send 种类，如 messageSendMarkDown，messageSendSimpleAction 等等。
  • 只使用 messageSendText 接口，在调用前使用 JSON 格式化这个文本，如：puppet.messageSendText(roomId, new MarkDownMessage('# 111').toString())

I think it's time for you to join us discussing more message type support, here is the issue

[jihuayu]

[基于开放 API 封装 Wechaty 接口下的钉钉聊天机器人] 进度报告

日期：08-02

本周完成的成果

• 了解 access_token 与用户列表的获取
• 完成 access_token 与用户列表获取的 api

本周遇到的困难和需要配合的地方

• 最大的问题是，钉钉通讯录获取的 user id 和聊天中返回的 user id 不一致。聊天中返回的 id 是经过加密的，无法根据这个 id 判断是哪个用户。

下周的开发计划和预计成果

• 把通讯录集成到 bot 上

其他需要说明和同步的事项

• 项目地址

[jihuayu]

[基于开放 API 封装 Wechaty 接口下的钉钉聊天机器人] 进度报告

日期：08-09

本周完成的成果

• 无

本周遇到的困难和需要配合的地方

• 正在准备期末考试

下周的开发计划和预计成果

• 下周考完把通讯录加上去

其他需要说明和同步的事项

• 项目地址
• 学校期末考了，正在备考，先搁置两周。

[jihuayu]

[基于开放 API 封装 Wechaty 接口下的钉钉聊天机器人] 进度报告

日期：08-24

本周完成的成果

• 完成了期末考，终于回来了
• 完成了，一整套的通过请求 token，获取部门名单，获取所有成员的流程。

本周遇到的困难和需要配合的地方

• 最大的问题是，钉钉通讯录获取的 user id 和聊天中返回的 user id 不一致。聊天中返回的 id 是经过加密的，无法根据这个 id 判断是哪个用户。

下周的开发计划和预计成果

• 研究一下怎么用通讯录在聊天中定位用户。

其他需要说明和同步的事项

• 项目地址
• 由于测试代码设计 secret，还在进行脱敏（其实是还在测试），尚未上传。

[jihuayu]

[基于开放 API 封装 Wechaty 接口下的钉钉聊天机器人] 进度报告

日期：09-01

本周完成的成果

• 研究出了at Contact 成员机制

本周遇到的困难和需要配合的地方

• 无

下周的开发计划和预计成果

• 把 Contact 的 AT 功能解决。
• 开始和 WeChaty 联调。

其他需要说明和同步的事项

• 项目地址

[huan]

@jihuayu I have read your code today and may I ask you to write a good README so that the developers who are interested in this project cloud read more docs of this repo?

[huan]

@rickyyin98 Thanks for the mentoring!

@jihuayu Thank you very much for joining the Wechaty open source project and finished Summer 2020 successfully!