📝Add some documentation details (#372)

* 📝Add documentation details

* 📝Fix some documentation link

Author: seng1e

docs/how-to/how-to_add_friendship.md

@@ -1 +1 @@
-## TODO
+> TODO: how to add friend

docs/how-to/how-to_introduction.md

@@ -1,11 +1,11 @@
-## 这里主要放一系列具体的教程，给出一个list，以及跳转链接
+## 这一节内容为wechaty的进阶使用
 
-- 如何添加好友
-- 如何关键字入群
-- 如何完成自动回复 
-- 如何检索群聊联系人 
-- 如何完成任务调度 
-- 如何完成群消息同步 
-- 如何使用Rasa Sever 
-- 如何使用Github Webhook插件 
-- 如何使用Gitlab Webhook插件
+- [如何添加好友](./how-to_add_friendship.md)
+- [如何关键字入群](./how-to_room_inviter.md)
+- [如何完成自动回复](./how-to_auto_reply.md)
+- [如何检索群聊联系人](./how-to_finder.md)
+- [如何完成任务调度](./how-to_scheduler.md)
+- [如何完成群消息同步](./how-to_message_forward.md)
+- [如何使用Rasa Sever](./how-to_rasa.md)
+- [如何使用Github Webhook插件](./how-to_github_webhook.md)
+- [如何使用Gitlab Webhook插件](./how-to_gitlab_webhook.md)

docs/how-to/how-to_scheduler.md

@@ -1 +1 @@
-TODO: 任务调度框架
+> TODO: 任务调度框架

docs/how-to/how-to_use_plugin.md

@@ -7,10 +7,10 @@
 ### 一、插件列表
 > 以下只是列表，具体的使用方法以及在前几篇文章中进行了说明，此处只是声明可能存在的插件，以及插件的调用方式。
 
-- [关键字入群插件](/plugins/keywords/)
-- [自动回复插件](/plugins/auto-reply)
-- [任务调度插件](/plugins/auto-reply)
-- [群消息同步插件](/plugins/message-forward.md)
-- [Rasa Rest Connector](/plugins/rasa)
-- [Github Webhook插件](/plugins/github-webhook)
-- [Gitlab Webhook插件](/plugins/gitlab-webhook)
+- [关键字入群插件](./how-to_room_inviter.md)
+- [自动回复插件](./how-to_auto_reply.md)
+- [任务调度插件](./how-to_scheduler.md)
+- [群消息同步插件](./how-to_message_forward.md)
+- [Rasa Rest Connector](./how-to_rasa.md)
+- [Github Webhook插件](./how-to_github_webhook.md)
+- [Gitlab Webhook插件](./how-to_gitlab_webhook.md)

docs/tutorials/index.md

@@ -1,18 +1,22 @@
-## 快速开始一个简单的应用
-### 本节内容中 将手把手快速指导你开始运行一个消息机器人。
-### 暂时还只有微信机器人相关的教程，后面可以补足: 微信公众号，钉钉，飞书，Whatsapp，Gitter这几种
+## 快速开始一个简单的机器人应用
+- 在本节内容中 将手把手快速指导你开始运行一个消息机器人。
 
 ### 运行一个微信机器人
-运行微信机器人有多种协议可以使用，有以下三种不同的协议方式, 每个协议都有不用的特点，如果你不知道选什么，就从Padlocal协议开始吧。
-> 此处最好放上几种协议的对比，以及具体的各自如何快速上手的的跳转链接
-- 使用Padlocal协议(推荐使用)
+运行微信机器人有多种协议可以使用，有以下三种不同的协议方式, 每个协议都有不用的特点，如果你不知道选什么，建议使用Padlocal协议来运行你的第一个微信机器人。
+
+- [使用Padlocal协议(推荐使用)](./use_padlocal_getting_started.md)
 - 使用Paimon协议
-- 使用免费Web协议
+- 使用免费Web协议(目前已不可用)
+- 使用puppet-xp协议（仅windows下可用）
 
 ### 运行一个微信公众号机器人
+- TODO
 
 ### 运行一个钉钉机器人
+- TODO
 
 ### 运行一个Whatsapp机器人
+- TODO
 
-### 运行一个Gitter机器人
+### 运行一个Gitter机器人
+- TODO

docs/tutorials/use_padlocal_getting_started.md

@@ -2,11 +2,10 @@
 
 底层的对接实现是基于TypeScript语言，故无法直接在python-wechaty中使用该服务。可是Wechaty社区能够直接将其转化成对应的服务让多语言调用，从而实现：底层复用的特性。
 
-整体步骤分为三步：
+整体步骤分为两步：
 
 * 申请一个TOKEN
-* 使用Docker启动Padlocal网关服务
-* 使用python-wechaty连接服务并启动启动微信机器人
+* 部署模板机器人
 
 
 ## 一、申请一个TOKEN
@@ -15,145 +14,78 @@
 - 那如何获取长期Token呢？详细请看：[Everything-about-Wechaty](https://github.com/juzibot/Welcome/wiki/Everything-about-Wech aty)
 
 
-## 二、使用Docker启动Padlocal网关服务
-- 这一步可以在本机运行也可以在服务器上运行。
-- 如果在服务器端运行，则须注意服务器相应端口防火墙规则需要打开
-- 如果是在本地测试运行，则需要在启动机器人时指定环境变量SERVICE_ENDPOINT
 
-### 2.1 脚本
+## 二、 部署模板机器人
 
-```shell
-# 设置环境变量
-
-export WECHATY_LOG="verbose"
-export WECHATY_PUPPET="wechaty-puppet-padlocal"
-export WECHATY_PUPPET_PADLOCAL_TOKEN="puppet_padlocal_XXXXXX"
-
-export WECHATY_PUPPET_SERVER_PORT="9001"
-# 可使用代码随机生成UUID：import uuid;print(uuid.uuid4());
-export WECHATY_TOKEN="1fe5f846-3cfb-401d-b20c-XXXXX"
-
-docker run -ti \
-  --name wechaty_puppet_service_token_gateway \
-  --rm \
-  -e WECHATY_LOG \
-  -e WECHATY_PUPPET \
-  -e WECHATY_PUPPET_PADLOCAL_TOKEN \
-  -e WECHATY_PUPPET_SERVER_PORT \
-  -e WECHATY_TOKEN \
-  -p "$WECHATY_PUPPET_SERVER_PORT:$WECHATY_PUPPET_SERVER_PORT" \
-  wechaty/wechaty:0.65
-```
+- 现在的你已经拥有了一个Padlocal Token. 接下来则需要使用它启动我们的第一个机器人了。
+- 在这里，我们直接使用[python-wechaty-template](https://github.com/wechaty/python-wechaty-template)项目来快速的部署我们的第一个机器人。
+- **在此之前请确保你的机器上已经安装并运行了[docker](https://www.docker.com/get-started)服务**
 
-> 在此我默认所有的人都对[Docker](https://www.docker.com)的基本使用已经有了一定的了解，否则可以花几分钟去看看其[文档](https://www.docker.com/get-started)熟悉一下。
+### 1. clone 模板机器人项目
 
-### 2.2 参数说明
+```she
+git clone https://github.com/wechaty/python-wechaty-template && cd python-wechaty-template
+```
 
-* **WECHATY_PUPPET**: **标识**使用的哪个协议，一般和`token`类型的一一对应。比如当使用`padlocal`协议的话，那这个就是`wechaty-puppet-padlocal`，如果使用`web`协议的话，那这个就是`wechaty-puppet-wechat`。
-* **WECHATY_PUPPET_PADLOCAL_TOKEN**: 这个协议是用来连接Padlocal的服务，目前是付费的。也就是在第一步中申请的。
-* **WECHATY_PUPPET_SERVER_PORT**: 网关服务的接口，提供给`python-wechaty`来连接调用，如果服务部署在云服务器上，则需要保证该端口的可访问性。
-* **WECHATY_TOKEN**: 当开发者在自己机器上启动一个网关服务时，需要通过`TOEKN`来做身份验证，避免服务被他人窃取。
+### 2. 启动padlocal网关
 
-以上代码只需要修改三个参数：`WECHATY_PUPPET_PADLOCAL_TOKEN`, `WECHATY_PUPPET_SERVER_PORT`, `WECHATY_TOKEN` 即可成功启动Token网关服务。
+- 参数为申请的token，下面示例中token不可用，请换上你申请的token
 
-那网关服务启动成功之后，只需要编写`python-wechaty`的代码来连接即可。
+```shel
+./start_gateway_docker.sh puppet_padlocal_d764cc8d231747b18b9ee5540dadd55c
+```
 
+### 3. 启动机器人
 
+- 上一步会启动一个docker，并运行Gateway服务，会有持续输出，建议运行在tmux中。
+- 开起一个新的terminal，并在模板机器人项目路径下运行以下命令
 
-## 三、使用python-wechaty连接服
+```shell
+make bot
+```
 
-### 3.1 本地测试和远端部署
+- 初次登陆时，可能需要扫码多次。
 
-当启动网关服务时，`Padlocal`会根据`WECHATY_TOKEN`来在[Wechaty服务接口](https://api.chatie.io/v0/hosties/__TOKEN__)上注册部署机器的`IP`和`端口`，然后python-wechaty会根据`WECHATY_TOKEN`在[Wechaty服务接口](https://api.chatie.io/v0/hosties/__TOKEN__)上获取对应的IP和端口。
+### 4. 验证机器人启动成功
 
-可是很多小伙伴在实际开发的过程中，通常会出现`endpoint is not invalid`等错误信息，那是因为开发者有可能在本地启动网关服务或者服务器端口没有开放。
+- 机器人发送消息`ding`来测试，如果启动成功，则机器人自动回复`dong`，至此你的第一个微信机器人就启动成功了。
 
-网关服务的部署通常是分为本地测试和远端部署，前者通常只是为了初学测试，后者是为了生产部署。如果是在生产部署时，只需要设置环境变量:
 
-```shell
-export WECHATY_PUPPET_SERVICE_TOKEN=1fe5f846-3cfb-401d-b20c-XXXXX
-# or
-export TOKEN=1fe5f846-3cfb-401d-b20c-XXXXX
-# or
-export token=1fe5f846-3cfb-401d-b20c-XXXXX
-```
 
-可是如果是在本地测试时，则通过ENDPOINT来找到启动的网关服务。
 
-```shell
-export WECHATY_PUPPET_SERVICE_TOKEN=1fe5f846-3cfb-401d-b20c-XXXXX
-# or
-export TOKEN=1fe5f846-3cfb-401d-b20c-XXXXX
-# or
-export token=1fe5f846-3cfb-401d-b20c-XXXXX
-
-export WECHATY_PUPPET_SERVICE_ENDPOINT=127.0.0.1:9001
-# or
-export ENDPOINT=127.0.0.1:9001
-# or
-export endpoint=127.0.0.1:9001
-```
 
-### 3.2 TOKEN的作用
+##  三、自定义配置
 
-总而言之:
 
-* 如果是公网环境下，可只需要设置`TOKEN`即可（因为你的token已经注册在chatie server上，故可以获取到目标资源服务器的ip和port）
-* 如果是内网环境下，可只需要使用`ENDPOINT`(`localhost:port`)来让python-wechaty连接目标资源服务器。
 
-> 如果是token是padlocal类型，则在python-wechaty程序内部可直接设置`export endpoint=localhost:port`来连接Gateway Server。
+### 3.1 使用docker启动的padlocal网关参数说明
 
-当然，以上的写法是使用Bash的方式来设置环境变量，也是可以通过python代码来设置环境变量，详细可看：
+- 这些参数在模板机器人项目中的`start_gateway_docker.sh`脚本中配置
 
-```python
-import os
-os.environ['token'] = "1fe5f846-3cfb-401d-b20c-XXXXX"
-os.environ['endpoint'] = "127.0.0.1:9001"
-```
+* **WECHATY_PUPPET**: **标识**使用的哪个协议，一般和`token`类型的一一对应。比如当使用`padlocal`协议的话，那这个就是`wechaty-puppet-padlocal`，如果使用`web`协议的话，那这个就是`wechaty-puppet-wechat`。
+* **WECHATY_PUPPET_PADLOCAL_TOKEN**: 这个协议是用来连接Padlocal的服务，目前是付费的。也就是在第一步中申请的。
+* **WECHATY_PUPPET_SERVER_PORT**: 网关服务的接口，提供给`python-wechaty`来连接调用，如果服务部署在云服务器上，则需要保证该端口的可访问性。（默认8080）
+* **WECHATY_TOKEN**: 当开发者在自己机器上启动一个网关服务时，需要通过`TOEKN`来做身份验证，避免服务被他人窃取。脚本中使用uuid自动生成。具体值可在`.env`文件中查看
 
-### 3.3 机器人启动代码
+网关服务启动成功之后，只需要编写`python-wechaty`的代码来连接即可。
 
-> talke is cheep, show you the code
 
-```python
-import asyncio, os
-from typing import List, Optional, Union
 
-from wechaty_puppet import FileBox  # type: ignore
+## 四、使用python-wechaty连接远程网关服务
 
-from wechaty import Wechaty, Contact
-from wechaty.user import Message, Room
+### 4.1 本地测试和远端部署
 
+当启动网关服务时，`Padlocal`会根据`WECHATY_TOKEN`来在[Wechaty服务接口](https://api.chatie.io/v0/hosties/__TOKEN__)上注册部署机器的`IP`和`端口`，然后python-wechaty会根据`WECHATY_TOKEN`在[Wechaty服务接口](https://api.chatie.io/v0/hosties/__TOKEN__)上获取对应的IP和端口。
 
-class MyBot(Wechaty):
+可是很多小伙伴在实际开发的过程中，通常会出现`endpoint is not invalid`等错误信息，那是因为开发者有可能在本地启动网关服务或者服务器端口没有开放。
 
-    async def on_message(self, msg: Message):
-        """
-        listen for message event
-        """
-        from_contact: Optional[Contact] = msg.talker()
-        text = msg.text()
-        room: Optional[Room] = msg.room()
-        if text == 'ding':
-            conversation: Union[
-                Room, Contact] = from_contact if room is None else room
-            await conversation.ready()
-            await conversation.say('dong')
-            file_box = FileBox.from_url(
-                'https://ss3.bdstatic.com/70cFv8Sh_Q1YnxGkpoWK1HF6hhy/it/'
-                'u=1116676390,2305043183&fm=26&gp=0.jpg',
-                name='ding-dong.jpg')
-            await conversation.say(file_box)
+网关服务的部署通常是分为本地测试和远端部署，前者通常只是为了初学测试，后者是为了生产部署。如果是在生产部署时，只需要将模板机器人项目下的.env文件内容在本地保持一致即可。即使用gateway启动时生成的token即可在本地访问远程网关服务。
 
-os.environ['TOKEN'] = "1fe5f846-3cfb-401d-b20c-XXXXX"
-os.environ['WECHATY_PUPPET_SERVICE_ENDPOINT'] = "127.0.0.1:9001"
-asyncio.run(MyBot().start())
-```
-### 运行代码
+### 4.2 TOKEN的作用
 
+总而言之:
 
-欢迎各位品尝以上代码 🥳 
+* 如果是公网环境下，可只需要设置`TOKEN`即可（因为你的token已经注册在chatie server上，故可以获取到目标资源服务器的ip和port）
+* 如果是内网环境下，可只需要使用`ENDPOINT`(`localhost:port`)来让python-wechaty连接目标资源服务器。
 
-* **相关链接**
-  * [python-wechaty](https://github.com/wechaty/python-wechaty)
-  * [python-wechaty-getting-started](https://github.com/wechaty/python-wechaty-getting-started)
+> 如果是token是padlocal类型，则在python-wechaty程序内部可直接设置`export endpoint=localhost:port`来连接Gateway Server。