{"id":26506193,"url":"https://github.com/wechaty/puppet-walnut","last_synced_at":"2025-03-20T22:26:21.205Z","repository":{"id":38311429,"uuid":"399799285","full_name":"wechaty/puppet-walnut","owner":"wechaty","description":"Wechaty Puppet Walnut - 硬核桃5G消息","archived":false,"fork":false,"pushed_at":"2022-06-07T10:45:45.000Z","size":1268,"stargazers_count":11,"open_issues_count":9,"forks_count":4,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-02-19T18:41:04.257Z","etag":null,"topics":["5g","chatbot","puppet","rcs","sms","wechaty"],"latest_commit_sha":null,"homepage":"https://www.5g-msg.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wechaty.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-08-25T11:49:47.000Z","updated_at":"2024-12-27T13:47:49.000Z","dependencies_parsed_at":"2022-08-17T15:55:35.433Z","dependency_job_id":null,"html_url":"https://github.com/wechaty/puppet-walnut","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"wechaty/puppet-mock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wechaty%2Fpuppet-walnut","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wechaty%2Fpuppet-walnut/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wechaty%2Fpuppet-walnut/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wechaty%2Fpuppet-walnut/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wechaty","download_url":"https://codeload.github.com/wechaty/puppet-walnut/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244595850,"owners_count":20478545,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["5g","chatbot","puppet","rcs","sms","wechaty"],"created_at":"2025-03-20T22:26:20.581Z","updated_at":"2025-03-20T22:26:21.190Z","avatar_url":"https://github.com/wechaty.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PUPPET-WALNUT\n\n![PUPPET-WALNUT](https://github.com/wechaty/puppet-walnut/blob/main/docs/images/puppet-walnut.webp)\n\n[![NPM Version](https://badge.fury.io/js/wechaty-puppet-walnut.svg)](https://badge.fury.io/js/wechaty-puppet-walnut)\n[![npm (tag)](https://img.shields.io/npm/v/wechaty-puppet-walnut/next.svg)](https://www.npmjs.com/package/wechaty-puppet-walnut?activeTab=versions)\n[![NPM](https://github.com/wechaty/wechaty-puppet-walnut/workflows/NPM/badge.svg)](https://github.com/wechaty/wechaty-puppet-walnut/actions?query=workflow%3ANPM)\n\n[![Powered by Wechaty](https://img.shields.io/badge/Powered%20By-Wechaty-brightgreen.svg)](https://github.com/wechaty/wechaty)\n[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-blue.svg)](https://www.typescriptlang.org/)\n\n## 前提环境\n\n1. 申请 5G 开发者权限。\n\n   👉 [5G消息开发者社区平台](https://www.5g-msg.com)\n\n2. 配置系统环境变量。\n\n   - `WECHATY_PUPPET_WALNUT_APPID`: Chatbot的AppId。\n   - `WECHATY_PUPPET_WALNUT_APPKEY`：Chatbot的AppKey。\n   - `WECHATY_PUPPET_WALNUT_SIPID`: Chatbot的sipId。\n   - `WECHATY_PUPPET`：wechaty-puppet-walnut\n\n3. 配置公网环境。\n\n   \u003e 如果是本地调试，则需要将在申请 5G 开发者时填入的公网地址，映射到本地才可以监听到`chatbot`接收到的消息\n\n   这里推荐使用 [Frp](https://github.com/fatedier/frp)，来进行端口的映射。Walnut本身集成的 sever 端口默认为 **3000**，将公网地址映射到本地即可\n\n## 安装本地调试环境\n\n1. 下载安装调试客户端。\n\n   \u003e 需要一部非 IOS 系统的手机\n\n   下载并且安装 👉 [终端测试消息APP](https://www.5g-msg.com/#/kaifataojian) 。\n\n2. 打开 app ，将其设置为系统的默认信息应用。\n3. 关闭wifi，确保使用手机流量上网。\n4. 右上角 -\u003e 设置 -\u003e 常规 -\u003e 融合通信登录。\n5. 联系硬核桃社区申请账号密码。\n6. 登录成功之后就可以收到我们 chatbot 发送的消息了🎉。\n\n\u003e 小白如何从0到1上手puppet-walnut 👉 \u003chttps://wechaty.js.org/2022/04/22/how-to-start-puppet-walnut/\u003e\n\n## 运行方法\n\n### 安装依赖\n\n~~~shell\nnpm install wechaty\nnpm install wechaty-puppet-walnut\n~~~\n\n### 编写代码\n\n~~~typescript\nimport { WechatyBuilder } from 'wechaty'\n\nWechatyBuilder.build()  // get a Wechaty instance\n  .on('message',       message =\u003e console.log(`Message: ${message}`))\n  .start()\n~~~\n\n\u003e Learn more for building your first Wechaty bot at \u003chttps://github.com/wechaty/\u003e, \u003chttps://github.com/wechaty/getting-started\u003e\n\n## 消息种类支持\n\n| 消息类型 | 从属(根据接口返回) | api                    | 接收 | 发送 | 群聊 |\n| -------- | ------------------ | ---------------------- | ---- | ---- | ---- |\n| 文本     | `text`             | `message.text`         | ✅    | ✅    | ❌    |\n| 图片     | `image`            | `message.toImage()`    | ✅    | ✅    | ❌    |\n| 视频     | `video`            | `message.toFilebox()`  | ✅    | ❌    | ❌    |\n| 音频     | `audio`            | `message.toFilebox()`  | ✅    | ❌    | ❌    |\n| 位置     | `location`         | `message.toLocation()` | ❌    | ❌    | ❌    |\n| 文件     | `other`            | `message.toFilebox()`  | ✅    | ❌    | ❌    |\n| 联系人   | `other`            | `message.toContact()`  | ✅    | ❌    | ❌    |\n| 富文本卡片   | `post`            | `message.toPost()`  | ❌   | ✅     | ❌    |\n\n## Wechaty API 支持\n\n### Contact\n\n- #### [Properties](https://wechaty.js.org/docs/api/contact#properties)\n\n  | Name | Type     | Description                                                  | Support | Details      |\n  | ---- | -------- | ------------------------------------------------------------ | ------- | ------------ |\n  | id   | `string` | Get Contact id. This function is depending on the Puppet Implementation, see [puppet-compatible-table](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table) | ✅       | Phone number |\n\n- #### [Instance Methods](https://wechaty.js.org/docs/api/contact#instance-methods)\n\n  | Instance Methods                    | Return type                                                  | Support | Details               |\n  | ----------------------------------- | ------------------------------------------------------------ | ------- | --------------------- |\n  | say(text Or Contact Or File) | `Promise`                                                    | ✅       | ⚠Contact not Support |\n  | name()                              | `String`                                                     | ✅       | Phone number          |\n  | alias(newAlias)                     | `Promise`                                                    | ✅       |                     |\n  | friend()                            | `Boolean or null`                                            | ✅       | True           |\n  | type()                              | `ContactType.Unknown or ContactType.Personal or ContactType.Official` | ✅       | ContactType.Personal  |\n  | gender()                            | `ContactGender.Unknown or ContactGender.Male or ContactGender.Female` | ✅       | ContactGender.Unknown |\n  | province()                          | `String or null`                                             | ❌       |                       |\n  | city()                              | `String or null`                                             | ❌       |                       |\n  | avatar()                            | `Promise`                                                    | ✅       | Default avatar        |\n  | sync()                              | `Promise`                                                    | ✅       |                     |\n  | self()                              | `Boolean`                                                    | ✅       |                       |\n\n  \u003e Default avatar 👉 \u003chttps://raw.githubusercontent.com/wechaty/puppet-walnut/main/docs/images/avatar.webp\u003e\n\n- #### [Static Methods](https://wechaty.js.org/docs/api/contact#static-methods)\n\n  | Static Methods            | Return Type                 | Support | Detail |\n  | ------------------------- | --------------------------- | ------- | ------ |\n  | find(query)               | `Promise \u003cContact \\| null\u003e` | ✅       |        |\n  | findAll(Query Arguements) | `Promise \u003cContact []\u003e`      | ✅       |        |\n\n### Message\n\n- #### [Instance Methods](https://wechaty.js.org/docs/api/message#instance-methods)\n\n  | Instance methods             | Return type         | Support | Detail               |\n  | ---------------------------- | ------------------- | ------- | -------------------- |\n  | talker()                       | `Contact` or `null` | ✅       |                      |\n  | to()                         | `Contact` or `null` | ✅       |                      |\n  | room()                       | `Room` or `null`    | ✅       | null                 |\n  | text()                       | `string`            | ✅       |                      |\n  | say(text Or Contact Or File) | `Promise`           | ✅       | ⚠Contact not Support |\n  | type()                       | `MessageType`       | ✅       | Message.Text         |\n  | self()                       | `boolean`           | ✅       |                      |\n  | mention()                    | `Promise`           | ❌       |                      |\n  | mentionSelf()                | `Promise`           | ❌       |                      |\n  | forward(to)                  | `Promise`           | ✅       |                      |\n  | date()                       | `Date`              | ✅       |                      |\n  | age()                        | `Number`            | ✅       |                      |\n  | toFileBox()                  | `Promise`           | ✅       |                      |\n  | toContact()                  | `Promise`           | ✅       |                      |\n  | toUrlLink()                  | `Promise`           | ✅       |                      |\n\n- #### [Static Method](https://wechaty.js.org/docs/api/message#static-method)\n\n  | Static Methods | Return type | Support | Detail |\n  | -------------- | ----------- | ------- | ------ |\n  | find()         | `Promise`   | ✅       |        |\n  | findAll()      | `Promise`   | ✅       |        |\n\n## 使用示例\n\n### 1. 可配置参数\n\n- `sipId`、`appId`和`appKey`可以通过环境变量或者此处传入。\n- `port`和`notifyUrlPrefix`可以指定 koa 服务监听的端口和路由前缀。\n\n\u003e 比如 bot 申请的回调地址为： \u003chttp://123.123.123.123:8080/sms/\u003e\n\u003e\n\u003e 此时`port`设为 8080, `notifyUrlPrefix`为 '/sms'\n\u003e\n\u003e `port`默认为 3000, `notifyUrlPrefix` 默认为空\n\n~~~ts\nnew PuppetWalnut({\n  sipId: xxxxxxx,\n  appId: xxxxxxx,\n  appKey: xxxxxxx,\n  port: 3000,\n  notifyUrlPrefix: '/sms'\n})\n~~~\n\n### 2. 创建实例\n\n~~~ts\nconst bot = WechatyBuilder.build({\n  puppet: new PuppetWalnut(),\n})  // get a Wechaty instance\n  .on('login', (user: any) =\u003e log.info(`User ${user} logged in`))\n  .on('message', async (message: Message) =\u003e {\n    log.info(`Message: ${message}`)\n  })\n\nawait bot.start()\n\nconst contact = await bot.Contact.find({ id: 'xxxxxxxxxxx' })\n~~~\n\n### 3. 文本消息\n\n~~~ts\nawait contact.say('This is a simple text message.')\n~~~\n\n![text-message](https://user-images.githubusercontent.com/60428924/163546259-67dfa5a1-521a-4d87-bfbf-af4e09dabf7e.jpg)\n\n### 4. 图片消息\n\n~~~ts\ncontact.say(FileBox.fromFile('C:\\\\Users\\\\Desktop\\\\1.png'))\n~~~\n\n![image-message](https://user-images.githubusercontent.com/60428924/163546352-1d573b86-65ee-474e-baf3-008ffe608a8d.jpg)\n\n### 5. 富文本消息\n\n~~~ts\nconst post = await bot.Post.builder()\n  .add('This is a single rich card.')\n  .add('This is the description of the rich card. It\\'s the first field that will be truncated if it exceeds the maximum width or height of a card.')\n  .add(FileBox.fromFile('C:\\\\Users\\\\Desktop\\\\1.png'))\n  .type(PUPPET.types.Post.Unspecified)\n  .build()\n\nawait contact.say(post)\n~~~\n\n![post-message](https://user-images.githubusercontent.com/60428924/163787857-fcde1562-c021-4e80-8a10-238e9615e3c7.jpg)\n\n## 项目介绍\n\n“开源软件供应链点亮计划-暑期2021”（以下简称 暑期2021）是由中科院软件所与 openEuler 社区共同举办的一项面向高校学生的暑期活动，旨在鼓励在校学生积极参与开源软件的开发维护，促进国内优秀开源软件社区的蓬勃发展。\n\n根据项目的难易程度和完成情况，参与者还可获取“开源软件供应链点亮计划-暑期2021”活动奖金和奖杯。\n\n官网：\u003chttps://summer.iscas.ac.cn\u003e\n\n## Wechaty\n\n[Wechaty](https://wechaty.js.org) 是一个开源聊天机器人框架SDK，具有高度封装、高可用的特性，支持NodeJs, Python, Go 和Java 等多语言版本。在过去的5年中，服务了数万名开发者，收获了 Github 的 9600 Star。同时配置了完整的DevOps体系并持续按照Apache 的方式管理技术社区。\n\n## 项目名称\n\n开发支持电信运营商 5G Chatbot / RCS 的 Wechaty 接入 Puppet 模块  \n\n## 背景介绍\n\nWechaty 社区目前已经支持微信、Whatsapp、企业微信、飞书等常见流行即时通讯工具，并且能够通过多语言 SDK （比如 Python Wechaty） 进行调用。\n\n5G Chatbot (RCS) 是近期中国电信运营商基于 5G 的消息战略落地平台，未来的 5G 手机将会内置 RCS 消息的处理能力。我们在本次 Summer 2021 的项目中，Wechaty 希望可以实现对RCS Chatbot 的支持。可以将 RCS 协议封装成为 `wechaty-puppet-walnut` 供 Wechaty 开发者方便接入 RCS 平台，使其成为 Wechaty 可以使用的社区生态模块。\n\n## 需求介绍\n\n使用 \u003chttps://github.com/wechaty/wechaty-puppet-official-account\u003e 项目作为模版，将核心代码文件 \u003chttps://github.com/wechaty/wechaty-puppet-official-account/blob/master/src/puppet-oa.ts\u003e 中的微信公众平台调用，全部替换（封装）为 RCS 模块的调用。\n\n这里有一个专门讲解如何开发 Wechaty Puppet Provider 的 workshop 视频，它以 `wechaty-puppet-official-account` 作为例子，做了从0到1的入门讲解：[Wechaty Workshop for Puppet Makers: How to make a Puppet for Wechaty](https://wechaty.js.org/2020/08/05/wechaty-puppet-maker/)。通过观看这一个小时的视频，应该可以系统性的了解如何完成构建一个 Wechaty Puppet Provider 模块。\n\n在初期开发中，能够实现文本消息的接收和发送，即可完成原型验证 POC 。\n\n还可以参考以下链接：\n\n1. TypeScript Puppet Official Documentation: \u003chttps://wechaty.github.io/wechaty-puppet/typedoc/classes/puppet.html\u003e\n2. Wechaty Puppet Specification: \u003chttps://wechaty.js.org/docs/specs/puppet\u003e\n3. \u003chttps://github.com/wechaty/wechaty-puppet-mock\u003e\n\n## 开发计划\n\n## 导师联系方式\n\n1. [李佳芮](https://wechaty.js.org/contributors/lijiarui/): Wechaty co-creator, Founder \u0026 CEO of Juzi.BOT (rui@chatie.io)\n2. 康嘉: 硬核桃社区\u003chttps://www.5g-msg.com/\u003e PM\n3. [李卓桓](https://wechaty.js.org/contributors/huan)：Wechaty creator, Tencent TVP of Chatbot (huan@chatie.io)\n\n## 项目技术栈\n\n1. TypeScript programming language\n2. Git\n3. REST Api\n4. 5G Chatbot / Rich Communication Service\n5. 硬核桃社区 5G Chatbot SDK \u003chttps://www.5g-msg.com/#/bussinessInformation\u003e\n\n## Links\n\n- 开源软件供应链点亮计划-暑期2021 - 支持电信运营商 5G Chatbot / RCS 项目\n  - [开源软件供应链点亮计划 - 暑期2021](https://summer.iscas.ac.cn/)\n  - [项目说明：开发支持电信运营商 5G Chatbot / RCS 的 Wechaty 接入 Puppet 模块](https://github.com/wechaty/summer/issues/74)\n  - [OSPP 2021-期初报告-开发支持电信运营商5G Chatbot/RCS的 Wechaty接入Puppet模块](https://wechaty.js.org/2021/07/15/ospp-plan-5g-chatbot-puppet/)\n  - [OSPP 2021-期中报告-开发支持电信运营商 5G Chatbot / RCS 的 Wechaty 接入 Puppet 模块](https://wechaty.js.org/2021/08/30/ospp-mid-term-5g-chatbot-puppet/)\n  - [OSPP 2021-结项报告-开发支持电信运营商 5G Chatbot / RCS 的 Wechaty 接入 Puppet 模块](https://wechaty.js.org/2021/10/07/ospp-final-term-5g-chatbot-puppet/)\n- [支持5G消息的 puppet-walnut 接入介绍](https://wechaty.js.org/2021/11/07/how-to-develop-wechaty-puppet-module-supporting-5g-messages/)\n- [中国电信-中国联通 5G 消息业务平台行业客户接入接口技术规范 V1.0.4](https://github.com/wechaty/puppet-walnut/blob/main/docs/5g-message-service-platform-industry-customer-access-interface-specification.pdf)\n\n## 相关链接\n\n- [Wechaty](https://wechaty.js.org/v/zh/)\n- [Koa](https://koa.bootcss.com/)\n- [TypeScripts中文手册](https://www.tslang.cn/docs/handbook/basic-types.html)\n\n## History\n\n### main v1.11 (Nov 29, 2021)\n\n1. Adapt to Wechaty v1.11\n\n### v0.0.1 (Jun 27, 2018)\n\nInitial version.\n\n## Maintainer\n\n- [Huan LI](https://github.com/huan) ([李卓桓](http://linkedin.com/in/zixia)), Tencent TVP of Chatbot, \\\u003czixia@zixia.net\\\u003e\n- [Fabian Bao](https://github.com/fabian4) ([鲍耀龙](https://fabian4.site/)), \\\u003cbaoyaolong@gmail.com\\\u003e\n\n## COPYRIGHT \u0026 LICENSE\n\n- Code \u0026 Docs © 2018 Huan LI \\\u003czixia@zixia.net\\\u003e\n- Code released under the Apache-2.0 License\n- Docs released under Creative Commons\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwechaty%2Fpuppet-walnut","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwechaty%2Fpuppet-walnut","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwechaty%2Fpuppet-walnut/lists"}