wechaty · huan · Sep 6, 2021 · Jul 8, 2021 · Jul 8, 2021 · Jul 9, 2021
diff --git a/README.md b/README.md
@@ -1,56 +1,93 @@
-# Wechaty GRPC
-
-[![Node.js](https://github.com/Chatie/grpc/workflows/Node.js/badge.svg)](https://github.com/Chatie/grpc/actions?query=workflow%3ANode.js)
-[![NPM](https://github.com/Chatie/grpc/workflows/NPM/badge.svg)](https://github.com/Chatie/grpc/actions?query=workflow%3ANPM)
-[![PyPI](https://github.com/Chatie/grpc/workflows/PyPI/badge.svg)](https://github.com/Chatie/grpc/actions?query=workflow%3APyPI)
-[![Maven](https://github.com/Chatie/grpc/workflows/Maven/badge.svg)](https://github.com/Chatie/grpc/actions?query=workflow%3A%22Maven%22)
-[![PHP](https://github.com/Chatie/grpc/workflows/PHP/badge.svg)](https://github.com/Chatie/grpc/actions?query=workflow%3APHP)
-[![Go](https://github.com/chatie/grpc/workflows/Go/badge.svg)](https://github.com/chatie/grpc/actions?query=workflow%3AGo)
-
-![Wechaty gRPC](docs/images/grpc.png)
-
-[![NPM Version](https://img.shields.io/npm/v/wechaty-grpc?color=brightgreen&label=NPM)](https://www.npmjs.com/package/wechaty-grpc)
-[![PyPI Version](https://img.shields.io/pypi/v/chatie-grpc?color=blue&label=PyPI)](https://pypi.org/project/chatie-grpc/)
-[![Java Version](https://img.shields.io/maven-central/v/io.github.wechaty/grpc?label=Java)](https://mvnrepository.com/artifact/io.github.wechaty/grpc)
-[![PHP Version](https://img.shields.io/packagist/v/wechaty/php-grpc)](https://packagist.org/packages/wechaty/php-grpc)
-
-[![node](https://img.shields.io/node/v/wechaty.svg?maxAge=604800&label=Node.js)](https://nodejs.org/)
-[![Python 3.7](https://img.shields.io/badge/python-3.7+-blue.svg?label=Python)](https://www.python.org/downloads/release/python-370/)
-![Go Version](https://img.shields.io/github/go-mod/go-version/wechaty/go-wechaty)
-
-gRPC for Wechaty Puppet Service
-
-## USAGE
+<div align="center">
+<img src="assets/images/wechaty-grpc-logo.svg" width="400" />
+<br />
+<h1>Wechaty gRPC</h1>
+<p>
+gRPC Service & Protocol Buffers for Wechaty Puppet
+</p>
+<a href="https://github.com/wechaty/grpc/issues
+"><img src="https://img.shields.io/github/issues/wechaty/grpc?style=flat-square" /></a>
+<a href="https://github.com/wechaty/grpc/network/members"><img src="https://img.shields.io/github/forks/wechaty/grpc?style=flat-square" /></a>
+<a href="https://github.com/wechaty/grpc/stargazers"><img src="https://img.shields.io/github/stars/wechaty/grpc?style=flat-square" /></a>
+<a href="https://github.com/wechaty/grpc/blob/master/LICENSE"><img src="https://img.shields.io/github/license/wechaty/grpc?style=flat-square" /></a>
+</div>
+
+<div align="center">
+
+[![Node.js](https://github.com/Chatie/grpc/workflows/Node.js/badge.svg)](https://github.com/Chatie/grpc/actions?query=workflow%3ANode.js) [![NPM](https://github.com/Chatie/grpc/workflows/NPM/badge.svg)](https://github.com/Chatie/grpc/actions?query=workflow%3ANPM) [![PyPI](https://github.com/Chatie/grpc/workflows/PyPI/badge.svg)](https://github.com/Chatie/grpc/actions?query=workflow%3APyPI) [![Maven](https://github.com/Chatie/grpc/workflows/Maven/badge.svg)](https://github.com/Chatie/grpc/actions?query=workflow%3A%22Maven%22) [![PHP](https://github.com/Chatie/grpc/workflows/PHP/badge.svg)](https://github.com/Chatie/grpc/actions?query=workflow%3APHP) [![Go](https://github.com/chatie/grpc/workflows/Go/badge.svg)](https://github.com/chatie/grpc/actions?query=workflow%3AGo)
+
+[![NPM Version](https://img.shields.io/npm/v/wechaty-grpc?color=brightgreen&label=NPM&style=flat-square)](https://www.npmjs.com/package/wechaty-grpc) [![PyPI Version](https://img.shields.io/pypi/v/chatie-grpc?color=blue&label=PyPI&style=flat-square)](https://pypi.org/project/chatie-grpc/) [![Java Version](https://img.shields.io/maven-central/v/io.github.wechaty/grpc?label=Java&style=flat-square)](https://mvnrepository.com/artifact/io.github.wechaty/grpc) [![PHP Version](https://img.shields.io/packagist/v/wechaty/php-grpc?style=flat-square)](https://packagist.org/packages/wechaty/php-grpc) [![node](https://img.shields.io/node/v/wechaty.svg?maxAge=604800&label=Node.js&style=flat-square)](https://nodejs.org/) [![Python 3.7](https://img.shields.io/badge/python-3.7+-blue.svg?label=Python&style=flat-square)](https://www.python.org/downloads/release/python-370/) [![Go Version](https://img.shields.io/github/go-mod/go-version/wechaty/go-wechaty?style=flat-square)](https://pkg.go.dev/github.com/chatie/grpc/go/wechaty)
+
+</div>
+
+<details open="open">
+<summary>Table of Contents</summary>
+<ol>
+<li>
+<a href="#About">About</a>
+</li>
+<li>
+<a href="#Usage">Usage</a>
+<ul>
+<li><a href="#Nodejs">Node.js</a></li>
+<li><a href="#Python">Python</a></li>
+<li><a href="#Go">Go</a></li>
+<li><a href="#Java">Java</a></li>
+<li><a href="#PHP">PHP</a></li>
+<li><a href="#CSharp">CSharp</a></li>
+</ul>
+</li>
+<li>
+<a href="#Development">Development</a>
+<ul>
+<li><a href="#Debug">Debug</a></li>
+<li><a href="#Build">Build</a></li>
+<li><a href="#Generate-Stubs">Generate Stubs</a></li>
+</ul>
+</li>
+<li><a href="#OpenAPI">OpenAPI</a></li>
+<li><a href="#gRPC-Web">gRPC Web</a></li>
+<li><a href="#Resources">Resources</a></li>
+<li><a href="#Contributing">Contributing</a></li>
+<li><a href="#Maintainer">Maintainer</a></li>
+<li><a href="#Copyright--License">Copyright & License</a></li>
+</ol>
+
+## About
+
+gRPC is a modern open-source high-performance Remote Procedure Call (RPC) framework that can run in any environment. It can efficiently connect services in and across data centers with pluggable support for load balancing, tracing, health checking, and authentication. It is also applicable in the last mile of distributed computing to connect devices, mobile applications, and browsers to backend services.
+
+## Usage
 
 ### Node.js
 
 [wechaty-grpc@NPM](https://www.npmjs.com/package/wechaty-grpc)
 
-Maintainer:
+**Maintainer:**
 
 - [@huan](https://github.com/huan) - Huan LI (李卓桓)
 
 ### Python
 
 [chatie-grpc@PyPI](https://pypi.org/project/chatie-grpc)
 
-Maintainer:
+**Maintainer:**
 
 - [@wj-Mcat](https://github.com/wj-Mcat) - Jingjing WU (吴京京)
 
 ### Go
 
 [github.com/wechaty/go-grpc](https://github.com/wechaty/go-grpc)
 
-Maintainer:
+**Maintainer:**
 
 - [@dchaofei](https://github.com/dchaofei) - Chaofei DING (丁超飞)
 
 ### Java
 
 [https://mvnrepository.com/artifact/io.github.wechaty/grpc](https://mvnrepository.com/artifact/io.github.wechaty/grpc)
 
-Maven:
+**Maven:**
 
 ```xml
 <dependency>
@@ -60,42 +97,42 @@ Maven:
 </dependency>
 ```
 
-Gradle:
+**Gradle:**
 
 ```groovy
 compile 'io.github.wechaty:grpc:0.11.25'
 ```
 
-Maintainer:
+**Maintainer:**
 
 - [@diaozxin007](https://github.com/diaozxin007) - Zhengxin DIAO (刁政欣)
 
 ### PHP
 
 [github.com/wechaty/php-grpc](https://github.comwechaty/php-grpc)
 
-Maintainer:
+**Maintainer:**
 
 - [@zhangchunsheng](https://github.com/zhangchunsheng) - Chunsheng ZHANG (张春生)
 
-### Csharp
+### CSharp
 
 [Wechaty.Grpc @ Nuget](https://www.nuget.org/packages/Wechaty.Grpc)
 
-Maintainer:
+**Maintainer:**
 
-- [@Darren](https://github.com/jesn)  - Darren (郑波)
+- [@Darren](https://github.com/jesn) - Darren (郑波)
 
-## DEVELOPMENT
+## Development
 
 ### Debug
 
-- [GUI Client for GRPC Services](https://github.com/uw-labs/bloomrpc) - BloomRPC aim to give the simplest and efficient developer experience for exploring and querying your GRPC services.(Inspired by Postman and GraphQL Playground)
+- [GUI Client for GRPC Services](https://github.com/uw-labs/bloomrpc) - BloomRPC aims to give the simplest and efficient developer experience for exploring and querying your GRPC services. (Inspired by Postman and GraphQL Playground)
 - [A gRPC CLI interface for easy testing against gRPC servers with Node.js REPL](https://github.com/njpatel/grpcc)
 
-    ```sh
-    grpcc --proto ./service/myservice.proto --address 127.0.0.1:3466
-    ```
+```shell
+grpcc --proto ./service/myservice.proto --address 127.0.0.1:3466
+```
 
 ### Build
 
@@ -153,13 +190,13 @@ protoc \
 
 ## OpenAPI
 
-Thanks for the ecosystem of gRPC, we can generate OpenAPI Specification from our gRPC proto definitions automatically.
+Thanks to the ecosystem of gRPC, we can generate OpenAPI Specification from our gRPC proto definitions automatically.
 
-We are using [gRPC to JSON proxy generator following the gRPC HTTP spec](https://github.com/grpc-ecosystem/grpc-gateway) as the OpenAPI Specification generator ([protoc-gen-openapiv2](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/protoc-gen-openapiv2)), and using [Like grpc-gateway, but written in node and dynamic](https://github.com/konsumer/grpc-dynamic-gateway) project to serve a HTTP RESTful API to gRPC proxy.
+We are using [gRPC to JSON proxy generator following the gRPC HTTP spec](https://github.com/grpc-ecosystem/grpc-gateway) as the OpenAPI Specification generator ([protoc-gen-openapiv2](https://github.com/grpc-ecosystem/grpc-gateway/tree/master/protoc-gen-openapiv2)), and using [Like grpc-gateway, but written in node and dynamic](https://github.com/konsumer/grpc-dynamic-gateway) project to serve an HTTP RESTful API to gRPC proxy.
 
-[![gRPC Gateway](docs/images/grpc-gateway-architecture.svg)](https://github.com/wechaty/openapi)
+<div align="center"><a link="https://github.com/wechaty/openapi"><img src="https://raw.githubusercontent.com/wechaty/grpc/master/docs/images/grpc-gateway-architecture.svg" width="400" /><a></div>
 
-> Image credit: [grpc-gateway](https://grpc-ecosystem.github.io/grpc-gateway/)
+> Image credit: [gRPC Gateway](https://grpc-ecosystem.github.io/grpc-gateway/)
 
 Learn more about the RESTful API service for Wechaty from [Wechaty OpenAPI](https://github.com/wechaty/openapi).
 
@@ -169,128 +206,34 @@ See also: [AIP-4222 - Routing headers](https://google.aip.dev/client-libraries/4
 
 - [gRPC-Web ReactJS client, Golang Server](https://github.com/longfellowone/grpcwebtest)
 
-## RESOURCES
-
-### Documentation
-
-- [Protocol Buffers Language Guide (proto3)](https://developers.google.com/protocol-buffers/docs/proto3)
-- [Google Protocol Buffers Style Guide](https://developers.google.com/protocol-buffers/docs/style)
-- [Protocol Buffers for TypeScript with Decorators](https://github.com/protobufjs/protobuf.js#using-decorators)
-- [Troubleshooting gRPC](https://github.com/grpc/grpc/blob/master/TROUBLESHOOTING.md)
-- [gRPC environment variables](https://github.com/grpc/grpc/blob/master/doc/environment_variables.md)
-- [How to Interact With and Debug a gRPC Server](https://medium.com/@EdgePress/how-to-interact-with-and-debug-a-grpc-server-c4bc30ddeb0b)
-
-### Links
-
-- [探讨gRPC的Node技术生态及实现工具](https://xenojoshua.com/2018/02/grpc-node-ecosystem/)
-- [gRPC Basics - Node.js](https://grpc.io/docs/tutorials/basic/node.html)
-- [Building a gRPC service with Node.js](https://codelabs.developers.google.com/codelabs/cloud-grpc/)
-- [gRPC in 3 minutes (Node.js)](https://github.com/grpc/grpc/tree/master/examples/node)
-- [Listen gRPC and HTTP requests on the same port](https://medium.com/@drgarcia1986/listen-grpc-and-http-requests-on-the-same-port-263c40cb45ff)
-- [gRPC to JSON proxy generator following the gRPC HTTP spec](https://github.com/grpc-ecosystem/grpc-gateway)
-- [如何在 Node.js 中更优雅地使用 gRPC：grpc-helper](https://github.com/xizhibei/blog/issues/86)
-
-#### Protocol Buffer
-
-- [Protocol Buffers for JavaScript (& TypeScript)](https://github.com/dcodeIO/protobuf.js)
-- [Missing value/null support for scalar value types in proto 3](https://github.com/protocolbuffers/protobuf/issues/1606)
-- [How to Make a Nullable Field in Proto3 for a HTTP Response?](https://stackoverflow.com/questions/57908389/how-to-make-a-nullable-field-in-proto3-for-a-http-response)
-
-#### gRPC Web
-
-- [gRPC-Web: Moving past REST+JSON towards type-safe Web APIs](https://improbable.io/blog/grpc-web-moving-past-restjson-towards-type-safe-web-apis)
-- [Library for making gRPC-Web requests intended for TypeScript from either a browser or Node.js.](https://github.com/improbable-eng/grpc-web/tree/master/ts)
-
-#### TypeScript Generator
-
-- [A Typescript definition file generator for gRPC services](https://github.com/anfema/grpc-code-generator)
-- [gRPC Web TypeScript Code Generation](https://github.com/improbable-eng/grpc-web/blob/master/ts/docs/code-generation.md)
-- [Protocol Buffers Compiler (protoc) plugin for TypeScript and gRPC-Web.](https://github.com/improbable-eng/ts-protoc-gen)
-
-#### Zoo Keeper
-
-- [ZooKeeper - The King of Coordination](https://www.elastic.co/blog/found-zookeeper-king-of-coordination)
-
-#### STUN
-
-- [How To TCP NAT Traversal using Node.js and a STUN Server](http://sogilis.com/blog/tcp-nat-traversal-nodejs-stun/)
-- [chownat, allows two peers behind two separate NATs to directly communicate with each other.](https://samy.pl/chownat/)
-- [What is STUN & TURN Server](https://stackoverflow.com/a/23307588/1123955)
-- [NPM Search for: NAT Traversal](https://www.npmjs.com/search?q=nat+traversal)
-- [NAT traversal by way of UPnP or NAT-PMP](https://github.com/tintfoundation/nat-traverse)
-- [How To TCP NAT Traversal using Node.js and a STUN Server](https://gist.github.com/mildred/b803e48801f9cdd8a4a8)
-- [STUN, TURN, and ICE - AnyConnect pioneered the STUN, TURN, and ICE NAT Traversal protocols](https://anyconnect.com/stun-turn-ice/)
-- [What are STUN, TURN, and ICE?](https://www.twilio.com/docs/stun-turn/faq#faq-what-is-nat)
-- [Set Phasers to STUN/TURN: Getting Started with WebRTC using Node.js, Socket.io and Twilio’s NAT Traversal Service](https://www.twilio.com/blog/2014/12/set-phasers-to-stunturn-getting-started-with-webrtc-using-node-js-socket-io-and-twilios-nat-traversal-service.html)
-
-TCP hole punching
-
-#### Reverse Engineering
-
-- [A toolset for reverse engineering and fuzzing Protobuf-based apps](https://github.com/marin-m/pbtk)
-
-#### Python Stub
-
-- [gRPC typing stubs for Python](https://github.com/shabbyrobe/grpc-stubs)
-
-#### CSharp grpc
-
-- [An introduction to NuGet  (microsoft)](https://docs.microsoft.com/en-us/nuget/what-is-nuget)
-- [Create a gRPC client and server in ASP.NET Core (microsoft)](https://docs.microsoft.com/en-us/aspnet/core/tutorials/grpc/grpc-start?view=aspnetcore-3.1&tabs=visual-studio)
-- [ASP.NET Core 3.0 使用gRPC (晓晨Master)](https://www.cnblogs.com/stulzq/p/11581967.html)
-
-## HISTORY
-
-### master
-
-### v0.20 (Feb 21, 2021)
-
-1. Rename NPM module name from `@chatie/grpc` to `wechaty-grpc`
-1. Add OpenAPI annotations & generators for supporting <https://github.com/wechaty/openapi>
-1. Code clean.
-
-### v0.18 (Oct 15, 2020)
-
-- Add new `MessageFileStream` and `MessageImageStream` to replace the `MessageFile` and `MessageImage` method to avoid blocking nodejs event loop when sending large files ([#88](https://github.com/Chatie/grpc/pull/88)) by [@windmemory](https://github.com/windmemory)
-- Add new `MessageSendFileStream` to replace the `MessageSendFile` method to avoid blocking nodejs event loop when sending large files ([#89](https://github.com/Chatie/grpc/pull/89)) by [@windmemory](https://github.com/windmemory)
-
-### v0.17 (Aug 5, 2020)
-
-- Add PHPH Support ([#76](https://github.com/Chatie/grpc/pull/76) [#78](https://github.com/Chatie/grpc/pull/78)) by [@zhangchunsheng](https://github.com/zhangchunsheng)
-- Publish PHP Module at <https://github.com/wechaty/php-grpc>
-
-### v0.13 (Apr 19, 2020)
-
-- Add Java Support ([#52](https://github.com/Chatie/grpc/issues/52) [#53](https://github.com/Chatie/grpc/issues/53) by [@diaozxin007](https://github.com/diaozxin007))
-- Publish Java Module at [Open Source Project Repository HostingOSSRH-56843 - Release the Chatie/grpc Java Client](https://issues.sonatype.org/browse/OSSRH-56843)
+## Resources
 
-### v0.11 (Apr 10, 2020)
+Check out [RESOURCES.md](RESOURCES.md) file for learning resources.
 
-- Add Go Support ([#50](https://github.com/Chatie/grpc/issues/50) by [@dchaofei](https://github.com/dchaofei))
-- Publish Go Module at <github.com/wechaty/go-grpc>
+## Contributing
 
-### v0.6 (Feb 2020)
+Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
 
-- Align gRPC Services with Wechaty Puppet Abstraction
-- Add Unit Tests
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
 
-### v0.2 (Jul 2018)
+See [CONTRIBUTING.md](http://github.com/wechaty/grpc/blob/master/CONTRIBUTING.md) for more details.
 
-- Automatic Generating gRPC Stubs
-- Publish to NPM
+## Releases
 
-### v0.0.1 (May 2018)
+Since its creation in 2016, a number of Wechaty versions have been released. For more information about the release history and the current stable version, you can read the [Wechaty release notes](https://github.com/Wechaty/wechaty/releases) on Github.
 
-Initial commiit
+## Maintainer
 
-## MAINTAINER
+Wechaty is maintained by [Huan](https://github.com/huan), [Rui](https://github.com/lijiarui), and a community of Open Source Contributors. We are always looking for people to join the Wechaty community to maintain the Wechaty codebase and documentation. You necessarily don't have to be a programmer to contribute to Wechaty. To get started contributing, you can read the [CONTRIBUTING.md](http://github.com/wechaty/grpc/blob/master/CONTRIBUTING.md).
 
-[Huan LI](https://github.com/huan) ([李卓桓](http://linkedin.com/in/zixia)), Google Developer Expert in Machine Learning (ML GDE), <[email protected]>
+## Getting help
 
-[![Profile of Huan LI (李卓桓) on StackOverflow](https://stackexchange.com/users/flair/265499.png)](https://stackexchange.com/users/265499)
+Wechaty has a community of very helpful contributors on different platforms you can join to get help from. Before joining any of the communities, we recommend that you read our Code of conduct]o that you adhere to our community guidelines. A full list of the different Wechaty communities can be accessed from the [Wechaty community](https://wechaty.js.org/docs/community/) section of this documentation.
 
-## COPYRIGHT & LICENSE
+## Copyright & License
 
-- Code & Docs © 2018-now Huan LI \<[email protected]\>
-- Code released under the Apache-2.0 License
-- Docs released under Creative Commons
+Wechaty is an [Open Source Project](https://opensource.com/resources/what-open-source). It is released under [Apache-2.0 license](https://github.com/wechaty/wechaty/blob/master/LICENSE) and the corresponding documentation is released under the [Creative Commons license](https://creativecommons.org/licenses/).