doc: 添加插件英文文档

plugins/README.md

@@ -0,0 +1,153 @@
+# Plugin System
+
+> The plugin system is still under development, and the functions may change, but the documentation will be updated as much as possible.
+
+
+# What is a plugin system?
+
+A plugin system is a system that allows users to customize functions. Users can add new functions through the plugin system. The definition of a plugin is a JSON file, and users can call the plugin by binding the corresponding command.
+
+
+## Plugin structure
+
+```typescript
+
+// TemplateInputType represents the parsing method of user input
+// 1. json represents that the input is a JSON object
+// 2. space-separated represents that the input is a string separated by spaces
+// 3. comma-separated represents that the input is a string separated by commas
+// 4. text represents that the input is a string (default value)
+export type TemplateInputType = 'json' | 'space-separated' | 'comma-separated' | 'text';
+
+// TemplateBodyType represents the parsing method of the request body.
+// 1. json represents that the request body is a JSON object. In this case, the corresponding body.content is a JSON object, and all JSON values can be injected with data through interpolation templates.
+// 2. form represents that the request body is a form. In this case, the corresponding body.content is a JSON object, and all JSON values can be injected with data through interpolation templates.
+// 3. text represents that the request body is a string. In this case, the corresponding body.content is a string (default value), and body.content can be injected with data through interpolation templates.
+export type TemplateBodyType = 'json' | 'form' | 'text';
+
+// TemplateResponseType represents the parsing method of the response body.
+// 1. json represents that the response body is a JSON object (default value). At this time, the response body will be parsed into a JSON object and then passed as input to the response template data.
+// 2. text represents that the response body is a string, and the response body string is directly passed as data to the response template.
+export type TemplateResponseType = 'json' | 'text';
+
+// TemplateOutputType represents the type of data sent to the user
+// 1. text represents that the data sent to the user is a string (default value)
+// 2. image represents that the data sent to the user is an image
+// 3. html represents that the data sent to the user is an html
+// 4. markdown represents that the data sent to the user is a markdown
+export type TemplateOutputType = 'text' | 'image' | 'html' | 'markdown';
+
+export interface RequestTemplate {
+  url: string; // Support interpolation, inserted values will be automatically encoded.
+  method: string;
+  headers: {[key: string]: string}; // Value supports interpolation.
+  input: {
+    type: TemplateInputType;
+  };
+  query: {[key: string]: string}; // Value supports interpolation, and inserted values will be automatically encoded.
+  body: {
+    type: TemplateBodyType;
+    content: {[key: string]: string} | string; // When the content is an object, the value supports interpolation. When the content is a string, it supports interpolation.
+  };
+  response: {
+    content: {
+      input_type: TemplateResponseType;
+      output_type: TemplateOutputType;
+      output: string; // Support interpolation, insert the data of the response body as the inserted value, and the inserted value will be automatically encoded according to the input_type.
+    };
+    error: { //Use the error template when response.ok is false.
+      input_type: TemplateResponseType;
+      output_type: TemplateOutputType;
+      output: string; // Support interpolation, insert the data of the response body as the inserted value, and the inserted value will be automatically encoded according to the input_type.
+    };
+  };
+}
+```
+
+
+## Plugin Usage
+
+For example, define the following variables in the environment variables:
+
+```toml
+PLUGIN_COMMAND_dns = "https://raw.githubusercontent.com/TBXark/ChatGPT-Telegram-Workers/dev/plugins/dns.json"
+PLUGIN_COMMAND_DESCRIPTION_dns = "DNS query /dns <type> <domain>"
+```
+
+Then enter `/dns A www.baidu.com` in the command line to call the plugin.
+Where `PLUGIN_COMMAND_dns` is the address of the plugin's json file, and `PLUGIN_COMMAND_DESCRIPTION_dns` is the description of the plugin.
+`PLUGIN_COMMAND_dns` can be a complete json or a url of a json.
+
+
+## Interpolation Template
+
+Example
+
+```html
+  <b>{{title}}</b>
+  <b>
+  {{#each item in items}}
+    {{#each:item i in item}}
+      {{ i.value }}
+      {{#if i.enable}}
+        {{#if:sub i.subEnable}}
+          sub enable
+        {{#else:sub}}
+          sub disable
+        {{/if:sub}}
+      {{#else}}
+        disable
+      {{/if}}
+    {{/each:item}}
+  {{/each}}
+  </b>
+```
+
+1. `{{title}}` represents the variable of interpolation template, supporting key path and array subscript.
+2. `{{#each item in items}}` represents traversing the array items, item is each element of the array, and must include the ending `{{/each}}`.
+3. `{{#each:item i in item}}` Nested traversal operations need to add aliases to the traversal, and the ending also needs to correspond to the alias `{{/each:item}}`.
+4. `{{#if i.enable}}` represents conditional judgment. The judgment condition does not support expressions and can only judge non-empty and non-zero. It must include the ending `{{/if}}`.
+5. `{{#else}}` represents the negative branch of conditional judgment.
+6. `{{#if:sub i.subEnable}}` Nested conditional judgment needs to add aliases to the condition, and the ending also needs to correspond to the alias `{{/if:sub}}`.
+7. There should be no spaces in the interpolation or expression in `{{}}`, otherwise it will be parsed as a string. For example, this is an incorrect interpolation `{{ title }}`.
+8. `{{.}}` represents the current data, which can be used in `#each` or globally.
+
+
+## Interpolation Variables
+
+The default data structure passed into interpolation is as follows:
+
+```json
+{
+  "DATA": [],
+  "ENV": {}
+}
+```
+
+1. Among them, `DATA` is the data input by the user, and the data structure of DATA varies according to different `TemplateInputType`.
+2. `ENV` is an environment variable that users can use to pass in data. The plugin's environment variables are isolated from the global environment variables and require different syntax to pass in.
+
+
+## Plugin Environment Variables
+
+You can save the token required for the request in the plugin environment variables. The plugin environment variables must start with `PLUGIN_ENV_`, for example:
+```toml
+PLUGIN_ENV_access_token = "xxxx"
+```
+
+It will be parsed as.
+
+```json
+{
+    "DATA": [],
+    "ENV": {
+      "access_token": "xxxx"
+    }
+}
+```
+
+
+## Plugin Examples
+
+1. [DNS Query Plugin Example](dns.json)
+2. [Dictionary Query Plugin Example](dicten.json)

plugins/README_CN.md

@@ -1,79 +1,89 @@
 # 插件系统
+
 > 插件系统还在开发中，功能可能会有变动但是文档会尽量保持更新
 
+
 ## 插件系统是什么？
+
 插件系统是一种允许用户自定义功能的系统。用户可以通过插件系统添加新的功能，插件的定义是一个json文件，用户通过绑定对应的命令来调用插件。
 
+
 ## 插件的结构
+
 ```typescript
 
-export type TemplateInputType = 'json' | 'space-separated' | 'comma-separated' | 'text';
 // TemplateInputType 代表用户输入的解析方式
 // 1. json代表输入是一个json对象
 // 2. space-separated代表输入是以空格分隔的字符串
 // 3. comma-separated代表输入是以逗号分隔的字符串
 // 4. text代表输入是一个字符串(默认值)
+export type TemplateInputType = 'json' | 'space-separated' | 'comma-separated' | 'text';
 
-export type TemplateBodyType = 'json' | 'form' | 'text';
 // TemplateBodyType 代表请求体的解析方式
 // 1. json代表请求体是一个json对象, 这时对应的body.content是一个json对象,所有的json的value都可以通过插值模板注入数据
 // 2. form代表请求体是一个表单, 这时对应的body.content是一个json对象,所有的json的value都可以通过插值模板注入数据
 // 3. text代表请求体是一个字符串, 这时对应的body.content是一个字符串(默认值),body.content可以通过插值模板注入数据
+export type TemplateBodyType = 'json' | 'form' | 'text';
 
-export type TemplateResponseType = 'json' | 'text';
 // TemplateResponseType 代表响应体的解析方式
-// 1. json代表响应体是一个json对象,这时会将响应体解析为json对象然后在作为输入传给响应模板的数据
-// 2. text代表响应体是一个字符串(默认值),响应体的字符串直接作为数据传给响应模板的数据
+// 1. json代表响应体是一个json对象(默认值),这时会将响应体解析为json对象然后在作为输入传给响应模板的数据
+// 2. text代表响应体是一个字符串,响应体的字符串直接作为数据传给响应模板的数据
+export type TemplateResponseType = 'json' | 'text';
 
-export type TemplateOutputType = 'text' | 'image' | 'html' | 'markdown';
 // TemplateOutputType 代表发送给用户的数据的类型
-// 1. text代表发送给用户的数据是一个字符串
+// 1. text代表发送给用户的数据是一个字符串(默认值)
 // 2. image代表发送给用户的数据是一个图片
 // 3. html代表发送给用户的数据是一个html
 // 4. markdown代表发送给用户的数据是一个markdown
+export type TemplateOutputType = 'text' | 'image' | 'html' | 'markdown';
+
 
-// 定义接口
 export interface RequestTemplate {
-  url: string;
+  url: string; // 支持插值,插入值会自动编码
   method: string;
-  headers: {[key: string]: string};
+  headers: {[key: string]: string}; // value 支持插值
   input: {
     type: TemplateInputType;
   };
-  query: {[key: string]: string};
+  query: {[key: string]: string}; // value 支持插值,插入值会自动编码
   body: {
     type: TemplateBodyType;
-    content: {[key: string]: string} | string;
+    content: {[key: string]: string} | string; // 当content为对象时 value 支持插值, 当content为字符串时支持插值
   };
   response: {
     content: {
       input_type: TemplateResponseType;
       output_type: TemplateOutputType;
-      output: string;
+      output: string; // 支持插值,插入值为响应体的数据,插入值会自动根input_type据编码
     };
-    error: {
+    error: { //当 response.ok 为 false 使用错误模板
       input_type: TemplateResponseType;
       output_type: TemplateOutputType;
-      output: string;
+      output: string; // 支持插值,插入值为响应体的数据,插入值会自动根input_type据编码
     };
   };
 }
 ```
 
 ## 插件的使用
+
 例如在环境变量中定义如下变量
+
 ```toml
 PLUGIN_COMMAND_dns = "https://raw.githubusercontent.com/TBXark/ChatGPT-Telegram-Workers/dev/plugins/dns.json"
 PLUGIN_COMMAND_DESCRIPTION_dns = "DNS查询 /dns <类型> <域名>"
 ```
+
 然后在命令行中输入`/dns A www.baidu.com`即可调用插件
 
 其中`PLUGIN_COMMAND_dns`是插件的json文件地址，`PLUGIN_COMMAND_DESCRIPTION_dns`是插件的描述。
 `PLUGIN_COMMAND_dns`可以是完整的json也可以是一个json的url
 
 
 ## 插值模板
+
 示例
+
 ```html
   <b>{{title}}</b>
   <b>
@@ -93,6 +103,7 @@ PLUGIN_COMMAND_DESCRIPTION_dns = "DNS查询 /dns <类型> <域名>"
   {{/each}}
   </b>
 ```
+
 1. `{{title}}` 代表插值模板的变量,支持键路径和数组下标
 2. `{{#each item in items}}` 代表遍历数组items, item是数组的每一个元素，必须包含结尾 `{{/each}}`
 3. `{{#each:item i in item}}` 嵌套遍历操作需要给遍历添加别名，结尾也需要对应的别名 `{{/each:item}}`
@@ -102,7 +113,9 @@ PLUGIN_COMMAND_DESCRIPTION_dns = "DNS查询 /dns <类型> <域名>"
 7. 所有`{{}}`中的插值或者表达式不能有空格，否则会被解析为字符串，比如这个就是一个错误的插值 `{{ title }}`
 8. `{{.}}` 代表当前的数据, 可以在`#each`中使用或者全局使用
 
+
 ## 插值的变量
+
 默认传入插值的数据结构如下
 
 ```json
@@ -111,15 +124,21 @@ PLUGIN_COMMAND_DESCRIPTION_dns = "DNS查询 /dns <类型> <域名>"
   "ENV": {}
 }
 ```
+
 1. 其中`DATA`为用户输入的数据，根据`TemplateInputType`的不同，DATA的数据结构也不同
 2. `ENV`为环境变量，用户可以通过环境变量传入数据,插件的环境变量与全局的环境变量隔离，需要不同的语法传入
 
+
 ## 插件环境变量
+
 你可以在插件环境变量中保存请求所需的token，插件环境变量必须以`PLUGIN_ENV_`开头，例如
+
 ```toml
 PLUGIN_ENV_access_token = "xxxx"
 ```
+
 就会被解析成
+
 ```json
 {
     "DATA": [],
@@ -129,3 +148,7 @@ PLUGIN_ENV_access_token = "xxxx"
 }
 ```
 
+## 插件示例
+
+1. [DNS查询插件示例](dns.json)
+2. [字典查询插件示例](dicten.json)