wechaty--wechaty/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Wechaty

Ship.Fail PreAngel

电梯演讲

Wechaty 是一款对话式 RPA（Robotic Process Automation，机器人流程自动化）SDK，可简化聊天机器人（chatbot）的构建流程。它就像聊天机器人开发中的瑞士军刀，为 WhatsApp、WeChat 等众多消息平台提供统一接口。使用 Wechaty，你只需编写一次机器人代码，即可在任意受支持平台上运行。这意味着你可以专注于打造引人入胜的对话体验，而无需操心各平台 API 的底层复杂性。它是开源的、易于使用的，并有活跃社区支持，随时帮助你把聊天机器人想法变为现实。

连接聊天机器人

Wechaty 是一款面向 Chatbot 开发者的 RPA（Robotic Process Automation）SDK，可帮助你用 6 行 JavaScript, Python, Go, 和 Java, 编写机器人，并支持跨平台运行，包括 Linux、Windows、MacOS, 和 Docker.

🕸️ https://wechaty.js.org
:octocat: https://github.com/Wechaty/wechaty
🪲 https://github.com/Wechaty/wechaty/issues
📖 https://github.com/Wechaty/wechaty-getting-started
🐳 https://hub.docker.com/r/wechaty/wechaty

突发新闻

• 重磅：绕过登录限制，wechaty免费版web协议重放荣光, @gengchen528, Apr 13, 2021

开发者之声

"Wechaty 是一个很棒的解决方案；我相信会有更多用户认可它。" link
— @Gcaufy，腾讯工程师，WePY 作者

"太好用，好用的想哭"
— @xinbenlv，Google 工程师，HaoShiYou.org 创始人

”好用到哭“——你们对得起这个评价！ link
— @bigbrother666sh, 《社长不见了》剧本杀 NPC DM 创作者

"最好的微信开发库" link
— @Jarvis，百度工程师

"Wechaty 让运营人员有更多时间思考如何进行活动策划、留存用户和商业变现" link
— @lijiarui，Juzi.BOT 创始人兼 CEO。

"如果你会 js……那就试试 Wechaty。它很容易上手。"
— @Urinx Uri Lee，WeixinBot(Python) 作者

"Wechaty 是一个好项目；我希望它能继续下去！因此，我成为了 open collective 的贡献者。"
— @Simple

更多内容见 Wiki:Voice Of Developer

在 Discord 加入我们

Wechaty 已被数千名开发者用于众多 ChatBot 项目。要与其他开发者交流，请扫描下方二维码，加入我们的 Wechaty 开发者社区。

立即扫码，因为其他 Wechaty 开发者也想和你交流！

资源

过去几年，Wechaty 已举办大量分享并收获诸多博客文章；以下是全部 Wechaty 资源：

• 📹 Youtube Playlist：观看所有与 Wechaty 相关的演讲视频
• 📃 完整文档
• 💡 博客：看看开发者如何用 wechaty 打造精彩项目！
• 🔰 Wechaty-Getting-Started：开箱即用的 Wechaty 入门项目模板
• 🎉 Wechaty 贡献者名单：感谢他们的贡献！
• 🎁 Juzibot Support Wechaty：了解关于 Wechaty 的一切

🚀 全球最短的 ChatBot 代码：6 行 JavaScript

import { WechatyBuilder } from 'wechaty'

const wechaty = WechatyBuilder.build() // get a Wechaty instance
wechaty
  .on('scan', (qrcode, status) => console.log(`Scan QR Code to login: ${status}\nhttps://wechaty.js.org/qrcode/${encodeURIComponent(qrcode)}`))
  .on('login',            user => console.log(`User ${user} logged in`))
  .on('message',       message => console.log(`Message: ${message}`))
wechaty.start()

注意：Wechaty 需要 Node.js 版本 >= 16

扫码登录后，该机器人可将所有消息记录到控制台。

你可以在 examples/ding-dong-bot.ts 找到 Wechaty 官方示例，更多示例见我们的 示例目录.

🏁 环境要求

1. Node.js 版本 16+
2. NPM 版本 7+
3. TypeScript 版本 4.4+

快速入门

• Wechaty 入门仓库（Starter Repository）- https://github.com/wechaty/wechaty-getting-started

我们为初学者提供了一个配置最简单的 Wechaty 入门仓库。在你完成 clone & npm install & npm start 后，它将开箱即用（work）。

如果你是 Wechaty 新手并想首次尝试，我们强烈建议你从这个仓库开始，并将其作为你项目的入门模板。

否则，请先将上述 世界上最短的聊天机器人代码：6 行 JavaScript 示例保存到名为 bot.js 的文件中，然后才能使用 NPM 或 Docker 运行。

1. Npm

npm init
npm install wechaty

# create your first bot.js file, you can copy/paste from the above "The World's Shortest ChatBot Code: 6 lines of JavaScript"
# then:
node bot.js

2. Docker

• Wechaty Docker 入门仓库 - https://github.com/wechaty/docker-wechaty-getting-started

Wechaty Docker 同时支持 JavaScript 和 TypeScript。要使用 TypeScript，只需用 TypeScript 编写并以扩展名 .ts 保存，无需编译，因为我们使用 ts-node 来运行。

2.1. 运行 JavaScript

# for JavaScript
docker run -ti --rm --volume="$(pwd)":/bot wechaty/wechaty bot.js

2.2. 运行 TypeScript

# for TypeScript
docker run -ti --rm --volume="$(pwd)":/bot wechaty/wechaty bot.ts

在 Wiki:Docker. 了解更多 Wechaty Docker 信息

3. 切换协议（Puppet）

Wechaty 功能强大，可在不同协议上运行。你可以通过将环境变量 WECHATY_PUPPET 设置为不同的 puppet 提供商（puppet provider）来指定协议。

如果你无法使用 Web 协议，可以按照此处的说明申请其他协议：https://github.com/wechaty/wechaty/wiki/Support-Developers 我们提供免费 token，以支持开发者构建有价值的微信聊天机器人。

目前我们支持以下 puppet 提供商 ：

协议	Puppet 提供商	环境变量
Web	PuppetPuppeteer	export WECHATY_PUPPET=wechaty-puppet-puppeteer
Windows	PuppetWorkPro	export WECHATY_PUPPET=wechaty-puppet-service
Mock	PuppetMock	export WECHATY_PUPPET=wechaty-puppet-mock
Web	PuppetWechat4u	export WECHATY_PUPPET=wechaty-puppet-wechat4u
iPad	PuppetRock	export WECHATY_PUPPET=wechaty-puppet-service
iPad	PuppetPadLocal	export WECHATY_PUPPET=wechaty-puppet-service
Windows	PuppetDonut	export WECHATY_PUPPET=wechaty-puppet-service
iPad	PuppetPadpro DEPRECATED	export WECHATY_PUPPET=wechaty-puppet-padpro
iPad	PuppetPadchat DEPRECATED	export WECHATY_PUPPET=wechaty-puppet-padchat
iPad	PuppetPadplus DEPRECATED	export WECHATY_PUPPET=wechaty-puppet-padplus
Mac	PuppetMacpro DEPRECATED	export WECHATY_PUPPET=wechaty-puppet-macpro
Windows	PuppetWxwork DEPRECATED	export WECHATY_PUPPET=wechaty-puppet-service

在 Puppet Wiki 中了解更多 Wechaty Puppet 信息：

1. Puppet 目录：https://github.com/Wechaty/wechaty-puppet/wiki/Directory
2. Puppet 兼容性：https://github.com/Wechaty/wechaty-puppet/wiki/Compatibility

🎸 API

阅读完整文档：Wechaty 官方 API 参考

1 Class Wechaty

主机器人类。

Bot 是一个 Wechaty 实例，用于控制特定的 wechaty-puppet.

• new Wechaty(options?: WechatyOptions)
  1. options.name?: string 该机器人的名称（可选）
  2. options.puppet?: string 选择要使用的 puppet 提供商，必须是以下之一：
     1. wechaty-puppet-wechat - Web 微信的 Angular Hook
     2. wechaty-puppet-wechat4u - Web 微信的 HTTP API
     3. wechaty-puppet-padpro - iPad 应用协议
     4. wechaty-puppet-ioscat - iPhone 应用 Hook
     5. wechaty-puppet-mock - 用于测试的 Mock
  3. options.puppetOptions?: PuppetOptions puppet 提供商的选项。

Wechaty	API	说明
event	login	机器人完全登录成功后触发
event	logout	机器人登出后触发
event	friendship	有人向机器人发送好友请求时触发
event	message	有新消息时触发
event	room-join	有人加入任何群聊时触发
event	room-topic	有人修改群聊主题时触发
event	room-leave	有人离开群聊时触发
event	room-invite	收到群聊邀请时触发
event	scan	机器人需要显示供扫描的二维码时触发
method	start(): Promise<void>	启动机器人
method	stop(): Promise<void>	停止机器人
method	logonoff(): boolean	机器人登录状态
method	logout(): Promise<void>	登出机器人
method	currentUser(): ContactSelf	获取已登录的机器人联系人
method	say(text: string): Promise<void>	让机器人向自己发送 text

2 Class Contact

所有微信联系人（好友/非好友）都将封装为 Contact。

Contact	API	说明
static	find(query: string): Promise<null | Contact>	按名称或备注查找联系人，若结果多于一个则返回第一个。
static	findAll(query: string): Promise<Contact[]>	通过 name 或 alias 查找联系人
static	load(query: string): Contact	通过 id 获取联系人
property	id: readonly string	获取联系人 id
method	sync(): Promise<void>	强制重新加载联系人数据，再次从底层 API 同步数据
method	say(text: string): Promise<void | Message>	向联系人发送文本、Contact 或文件，返回机器人发送的消息（仅支持 puppet-padplus）。
method	self(): boolean	检查联系人是否为自身
method	name(): string	获取联系人姓名
method	alias(): Promise<string>	获取联系人备注
method	alias(newAlias: string): Promise<void>	设置或删除联系人备注
method	friend(): boolean	检查联系人是否为好友
method	type(): ContactType	返回 Contact 的类型
method	province(): string	从联系人获取地区「省份」
method	city(): string	从联系人获取地区「城市」
method	avatar(): Promise<FileBox>	获取头像图片文件流
method	gender(): ContactGender	获取联系人性别

2.1 类 ContactSelf

类 ContactSelf 继承自 Contact。

ContactSelf	API	描述
method	avatar(file: FileBox): Promise<void>	为机器人设置头像
method	qrcode(): Promise<string>	获取机器人的二维码
method	signature(text: string): Promise<void>	为机器人设置个性签名

2.2 类 Friendship

发送、接收好友请求及好友确认相关事件。

Friendship	API	描述
static	add(contact: Contact, hello?: string): Promise<void>	向联系人发送好友邀请
method	accept(): Promise<void>	接受好友请求
method	hello(): string	从好友邀请中获取问候语字符串
method	contact(): Contact	从好友关系中获取联系人
method	type(): FriendshipType	返回好友类型（unknown、confirm、receive、verify）

3 类 Message

所有微信消息都将封装为 Message。

Message	API	描述
static	find(query: string): Promise<null | Message>	在缓存中查找消息并返回第一条
static	findAll(query: string): Promise<Message[]>	在缓存中查找消息，返回消息列表
method	from(): Contact	从消息中获取发送者
method	to(): Contact	获取消息的目标对象
method	room(): null | Room	从消息中获取群聊。（如果消息不在群聊中，则返回 null）
method	text(): string	获取消息的文本内容
method	say(text: string): Promise<void | Message>	向发送者回复文本、媒体文件或联系人消息，返回机器人发送的消息（仅支持 puppet-padplus）。
method	type(): MessageType	从消息中获取类型
method	self(): boolean	检查消息是否由自己发送
method	mention(): Contact[]	获取消息中 @ 提及的联系人列表。
method	mentionSelf(): boolean	检查消息是否 @ 提及自己
method	forward(to: Contact): Promise<void>	转发收到的消息
method	age(): number	自创建以来经过的秒数
method	date(): Date	创建时间
method	toFileBox(): Promise<FileBox>	从 Message 中提取媒体文件，并放入 FileBox。
method	toContact(): Promise<Contact>	获取消息的分享卡片

4 类 Room

所有微信群聊（群组）都将封装为 Room。

Room	API	描述
static	create(contactList: Contact[], topic?: string): Promise<Room>	创建新群聊
static	find(query: string): Promise<null | Room>	尝试通过筛选条件查找群聊。若找到多个，则返回第一个。
static	findAll(query: string): Promise<Room[]>	查找群聊中的所有联系人
static	load(query: string): Room	通过群聊 ID 加载群聊
property	id: readonly string
event	join	当有人加入任意群聊时触发
event	topic	当有人修改群聊名称时触发
event	leave	当有人离开群聊时触发
event	invite	当收到群聊邀请时触发
method	sync(): <Promise<void>	强制重新加载群聊数据，再次从底层 API 同步数据。
method	say(text: string): Promise<void | Message>	在 Room 内发送文本、媒体文件、联系人名片，或带 @ 提及联系人的文本，返回机器人发送的消息（仅支持 puppet-padplus）。
method	add(contact: Contact): Promise<void>	向群聊中添加联系人
method	del(contact: Contact): Promise<void>	从群聊中删除联系人
method	quit(): Promise<void>	机器人自行退出群聊
method	topic(): Promise<string>	从群聊获取群名称
method	topic(newTopic: string): Promise<void>	设置群聊的群名称
method	announce(text: string): Promise<void>	设置/获取群聊公告
method	qrcode(): Promise<string>	从群聊获取群二维码，可用于扫码加入群聊。
method	alias(contact: Contact): Promise<string>	返回联系人在群聊中的群昵称（roomAlias）
method	roomAlias(contact: Contact): Promise<string | null>	与 alias 函数相同
method	has(contact: Contact): Promise<boolean>	检查群聊是否包含成员 contact
method	memberAll(query?: string): Promise<Contact[]>	查找群聊中的所有联系人，或按特定名称查找
method	member(query: string): Promise<null | Contact>	查找群聊中的联系人，若找到多个，则返回第一个。
method	memberList():Promise<Contact[]>	从群聊获取所有群成员
method	owner(): null | Contact	从群聊获取群主。

4.1 类 RoomInvitation

接受群聊邀请

RoomInvitation	API	描述
method	accept(): Promise<void>	接受群聊邀请
method	inviter(): Contact	从群聊邀请中获取邀请人
method	roomTopic(): Promise<string>	从群聊邀请中获取群名称
method	date(): Promise<Date>	创建时间
method	age(): Promise<number>	自创建以来经过的秒数

TEST

Wechaty 通过单元测试和集成测试实现了全自动测试，并借助 Travis、Shippable、Appveyor 等 CI 提供持续集成与持续交付（Continuous Integration & Continuous Delivery，CI/CD）支持。

要测试 Wechaty，请运行：

npm test

更多测试信息请参阅 Wiki:Tests

创建 WECHATY 插件

创建并发布 Wechaty 插件（Plugin）非常简单。只需将模块导出为一个接受 1 个参数 wechaty 的函数。当你的插件被 Wechaty 导入时，它会将自身作为参数传入，因此你可以自由添加 Wechaty 支持的任何配置。

import { WechatyPlugin } from 'wechaty'

export default const MyPlugin: WechatyPlugin = (wechaty: Wechaty) => {
  // ...
}

config 的存在是为了让用户可以向你的插件传入自定义配置。在编写 Wechaty 插件文档时，你应为用户列出所支持的配置项。

参见：

1. Wechaty Plugin Support with KickOut Example #1939
2. Wechaty Plugins Contrib

📝 发布说明

• Latest Release(All 的版本发布见此处)
• Changelog

🎷 自 2019 年 2 月 15 日起的访问量

💖 POWERED BY WECHATY

✨ Wechaty 徽章

[![Powered by Wechaty](https://img.shields.io/badge/Powered%20By-Wechaty-brightgreen.svg)](https://wechaty.js.org)

更多嵌入用的 HTML/Markdown 代码请参阅 Wiki:Badge

🌟 使用 Wechaty 的项目

1. 一个用CNN深度神经网络给图片评分的wechaty项目
2. Telegram 与 WeChat 之间的消息中转
3. 管理 haoshiyou.org 志愿者运营的 HaoShiYou 微信群的聊天机器人
4. 用于管理 TODO 列表的交互式聊天机器人
5. 将微信消息转发到 Telegram
6. koa与wechaty实现的微信小助手，可定时提醒与发消息设定定时任务
7. Wechaty Pay - 让线上没有难做的生意
8. 开源社的微信机器人项目

欢迎提交 Pull Request 添加你的项目！

了解更多使用 Wechaty 的项目，请参阅 Wiki:Projects Using Wechaty

😇 选择合适的服务器

运行 Wechaty Docker/NPM 的最佳实践是使用中国境外的 VPS（Virtual Private Server，虚拟专用服务器），这能为你节省大量时间，因为 npm install 和 docker pull 可以顺利运行，不会遇到任何问题。

以下 VPS 提供商已被 Wechaty 团队使用，并在生产环境中表现完美。你可以通过以下链接在几分钟内完成购买。此外，通过我们的推荐链接购买也能支持 Wechaty 项目。

地区	价格	内存	支付方式	提供商
Singapore	$5	512MB	Paypal	DigitalOcean
Japan	$5	1GB	Paypal	Linode
Korea	$10	1GB	Alipay, Paypal	Netdedi
Singapore	$3.5	512MB	Alipay, Wechat	Vultr

🎶 另请参阅

• RelatedProject

💩 起源故事

2017 年……

Huan 的日常生活/工作极度依赖微信聊天。

• 2014 年 5 月，微信好友接近 14,000 人——当时微信尚未将好友总数限制为 5,000。
• 近 400 个微信群，其中大多数成员超过 400 人。

你能想象吗？他快撑不住了……

因此，迫切需要一台在微信上 24x7 为我工作的不知疲倦的机器人，用于监控/筛选最重要的消息。例如，它会高亮包含他想跟进的关键词（KEYWORDS）的讨论（尤其在嘈杂的群里）。;-)

最终，它是为 Huan 个人学习「自动化测试」（Automatically Testing）的目的而构建的。

随时间变化的 Star 数

💕 贡献者

本项目的存在离不开所有贡献者的付出。[参与贡献]。

---

😎 支持者

感谢所有支持者！🙏 [成为支持者]

😏 赞助者

成为赞助者以支持本项目。你的 Logo 将显示在此处，并附带指向你网站的链接。[成为赞助者]

多语言 Wechaty

• Wechaty - 面向 Chatbot 开发者的 RPA SDK（TypeScript）
• Python Wechaty - 使用 Python 编写的面向 Chatbot 开发者的 RPA SDK
• Go Wechaty - 使用 Go 编写的面向 Chatbot 开发者的 RPA SDK
• Java Wechaty - 使用 Java(Kotlin) 编写的面向 Chatbot 开发者的 RPA SDK
• Scala Wechaty - 使用 Scala 编写的面向 Chatbot 开发者的 RPA SDK
• PHP Wechaty - 使用 PHP 编写的面向 Chatbot 开发者的 RPA SDK
• .Net(C#) Wechaty - 使用 .NET(C#) 编写的面向 Chatbot 开发者的 RPA SDK

历史

main v1.11（2021 年 11 月 22 日）

正在对 Wechaty 生态系统进行 reduxify，以应用 CQRS 模式。

v1.10（2021 年 11 月 21 日）

Wechaty 的第二次 beta 发布，生态系统中所有 npm 模块均为 v1.10 版本（wechaty-puppet、wechaty-puppet-service 等）

v1.0（2021 年 9 月）

• Wechaty v1.0 发布是 Wechaty 的首次 beta 发布。

v0.69

1. v0.69：支持 ES Modules（同时兼容 CJS）(#2232)

v0.68（2021 年 8 月 27 日）

1. 支持 TLS (#2231)
2. 最新的 CommonJS 版本

创建者

1. Huan (LinkedIn), 🐧 腾讯 Chatbot TVP・🤖 Chatie 架构师・⭐️ GitHub Star・🚀 YC W19・🌐 Microsoft RD & AI MVP・🦾 Google ML GDE・🤠 连续创业者・🔥 Burner
2. Rui（李佳芮）, Microsoft AI MVP & RD，Juzi.BOT 联合创始人兼 CEO（YC W19 校友）

引用 Wechaty

在出版物中引用本项目：

@misc{Wechaty,
  author = {Huan Li, Rui Li},
  title = {Wechaty: Conversational SDK for Chatbot Makers},
  year = {2016},
  publisher = {GitHub},
  journal = {GitHub Repository},
  howpublished = {\url{https://github.com/wechaty/wechaty}},
}

版权与许可证

• 代码与文档 © 2016-至今 Huan、Rui 及 Wechaty 社区贡献者
• 代码基于 Apache-2.0 License 发布
• 文档基于 Creative Commons 发布