@serverless-devs/s 2.0.92 → 2.0.93-beta.4

package/docs/zh/install.md

@@ -0,0 +1,52 @@
+# 工具安装与升级
+
+- [工具安装](#工具安装)
+    - [通过命令行工具安装](#通过命令行工具安装)
+    - [通过脚本安装](#通过脚本安装)
+- [工具升级](#工具升级)
+
+
+## 工具安装
+### 通过命令行工具安装
+
+通过 [npm](https://www.npmjs.com/) 包管理安装：适用于已经预装了 npm 的 Windows、Mac、Linux 平台。在 Windows、Mac、Linux 平台执行以下命令安装 Serverless Devs Tool工具。
+
+```shell script
+$ npm install @serverless-devs/s -g
+```
+或者 通过 [yarn](https://yarnpkg.com/) 进行安装
+
+```shell script
+$ yarn global add @serverless-devs/s
+```
+
+> **说明**:   
+> - 如果在 Linux 或 MacOS 下执行该命令报错且报错信息为 `未找到命令`，请执行命令 `ln -s serverless-devs安装位置 /usr/bin`，serverless-devs安装位置可以通过`find / -name s` 查找。   
+> - 如果在 Linxu 下执行该命令报错且报错信息为 `Error: EACCES: permission denied`，请执行命令 `sudo npm install @serverless-devs/s -g`。   
+> - 如果安装过程较慢，可以考虑使用淘宝 npm 源，安装命令为 `npm --registry=https://registry.npm.taobao.org install @serverless-devs/s -g`。
+
+
+### 通过脚本安装
+
+针对 Mac/Linux 用户
+
+```shell script
+$ curl -o- -L http://cli.so/install.sh | bash
+```
+
+## 工具升级
+
+Serverless Devs 开发者工具会不定期的进行更新升级。开发者在使用 Serverless Devs 开发者工具时，可以根据系统提醒进行进行最新版本的感知。
+
+当客户端感知到系统升级之后，开发者可以通过命令`npm i -g @serverless-devs/s`进行更新操作，也可以通过 [Release](https://github.com/Serverless-Devs/Serverless-Devs/releases) 信息查看升级的具体内容，以决定是否进行本次升级。
+
+> 例如：我当前的 Serverless Devs 的版本是`2.0.89`，当系统升级之后，我再使用Serverless Devs开发者工具，工具将会给出相对应的提醒：
+> ```shell script
+>    ╭───────────────────────────────────────────────╮
+>    │                                               │
+>    │       Update available 2.0.89 → 2.0.90        │
+>    │   Run npm i -g @serverless-devs/s to update   │
+>    │                                               │
+>    ╰───────────────────────────────────────────────╯
+> ```
+> 此时，只需要按照提醒进行工具更新升级即可。

package/docs/zh/package_dev.md

@@ -0,0 +1,142 @@
+# Package开发文档
+
+
+- [组件开发说明](#组件开发说明)
+- [应用开发说明](#应用开发说明)
+
+> 注意：
+> - Serverless Devs的组件开发和应用开发模版都已经被默认的集成到了Serverless Devs的开发者工具中，Package开发者可以直接使用；
+> - Package的开发，需要遵循[Serverless Package Model](../../spec/zh/0.0.1/serverless_registry_model/readme.md)以及相关规范，只有这样Serverless Registry和Serverless Devs开发者工具才能正确识别和使用；
+> - 关于应用和组件开发的最佳实践可以参考[社区讨论 #62](https://github.com/Serverless-Devs/Serverless-Devs/discussions/62);
+
+
+## 组件开发说明
+
+> Serverless Devs 组件开发需要严格遵守 [Serverless Package Model](../../spec/zh/0.0.1/serverless_registry_model/readme.md) 中的 [组件模型规范](../../spec/zh/0.0.1/serverless_registry_model/3.registry_model.md#组件模型规范)。在[组件模型规范](../../spec/zh/0.0.1/serverless_registry_model/3.registry_model.md#组件模型规范)中有关于[组件模型元数据](../../spec/zh/0.0.1/serverless_registry_model/3.registry_model.md#组件模型元数据)和[组件模型代码规范](../../spec/zh/0.0.1/serverless_registry_model/3.registry_model.md#组件模型代码规范)的说明。
+
+> 🐵 温馨提示，在进行 Serverless Devs 的组件开发时，可能会遇到很多相对来说更为通用的能力，包括不限于：
+> - 获取用户的密钥信息
+> - 进行更规范的格式化输出
+> - 对用户的输入参数进行解析   
+> ......   
+> 这些内容都可以通过 Serverless Devs 所提供的 [Core包](https://github.com/Serverless-Devs/core) 进行提供，更多 [Core包](https://github.com/Serverless-Devs/core) 信息，可以参考 [Core包的开发文档](https://github.com/Serverless-Devs/core)
+
+Serverless Devs的组件开发案例已经被集成到Serverless Devs命令行工具中，通过对Serverless Devs的命令行工具，可以进行空白组件项目的初始化，开发者只需要执行`s init`即可看到：
+
+```shell script
+
+🚀 Serverless Awesome: https://github.com/Serverless-Devs/package-awesome
+
+? Hello Serverless for Cloud Vendors (Use arrow keys or type to search)
+❯ Alibaba Cloud Serverless 
+  AWS Cloud Serverless 
+  Tencent Cloud Serverless 
+  Baidu Cloud Serverless 
+  Dev Template for Serverless Devs 
+```
+
+此时，选择最后的`Dev Template for Serverless Devs`，并按回车：
+
+```shell script
+$ s init
+
+🚀 Serverless Awesome: https://github.com/Serverless-Devs/package-awesome
+
+? Hello Serverless for Cloud Vendors Dev Template for Serverless Devs
+? Please select an Serverless-Devs Application (Use arrow keys or type to search)
+❯ Application Scaffolding 
+  Component Scaffolding 
+```
+
+此时，选择`Component Scaffolding`，并按回车，即可完成一个完整的Serverless Devs的Component项目的初始化，可以通过命令查看文件树：
+
+```shell script
+$ find . -print | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
+.
+|____LICENSE
+|____.signore
+|____example
+| |____s.yaml
+|____readme.md
+|____publish.yaml
+|____.gitignore
+|____package.json
+|____tsconfig.json
+|____src
+| |____common
+| | |____entity.ts
+| | |____logger.ts
+| |____index.ts
+```
+
+这其中：
+
+| 目录 | 含义 |
+| --- | --- | 
+| LICENSE | 项目默认的LICENSE，默认的LICENSE是遵循MIT开源协议的（推荐） | 
+| .signore | 项目发布时，可以选择的忽略文件，类似于npm发布是的`.npmignore`文件 | 
+| example | 该组件对应的测试应用 | 
+| publish.yaml | 项目所必须的文件，Serverless Devs Package的开发识别文档 |
+| .gitignore| 推送到Github的忽略文件 | 
+| package.json| Node.js的package.json，需要描述清楚组件的入口文件位置 |
+| tsconfig.json| Typescript的tsconfig.json，用来对TS项目进行描述等 |
+| src| 用户的代码目录 |
+| readme.md| 版本的描述，例如当前版本的更新内容等 |
+
+此时，开发者可以在src下完成业务代码的开发，由于默认的初始化项目是Typescript，所以开发完成业务代码还需要编译成Javascript（可以通过`npm run build`进行编译），在完成项目编译之后，还需要对项目进行`publish.yaml`文件的编写。完成之后，即可将项目发不到不同的源，以Github Registry为例，可以在Github创建一个`Public`的仓库，并将编译后的代码放到仓库，并发布一个版本。此时，就可以通过客户端获取到该应用。
+
+## 应用开发说明
+
+> Serverless Devs 应用开发需要严格遵守 [Serverless Package Model](../../spec/zh/0.0.1/serverless_registry_model/readme.md) 中的 [应用模型规范](../../spec/zh/0.0.1/serverless_registry_model/3.registry_model.md#应用模型规范)。在[应用模型规范](../../spec/zh/0.0.1/serverless_registry_model/3.registry_model.md#应用模型规范)中有关于[应用模型元数据](../../spec/zh/0.0.1/serverless_registry_model/3.registry_model.md#应用模型元数据)的说明。
+
+Serverless Devs的组件开发案例已经被集成到Serverless Devs命令行工具中，通过对Serverless Devs的命令行工具，可以进行空白组件项目的初始化，开发者只需要执行`s init`即可看到：
+
+```shell script
+
+🚀 Serverless Awesome: https://github.com/Serverless-Devs/package-awesome
+
+? Hello Serverless for Cloud Vendors (Use arrow keys or type to search)
+❯ Alibaba Cloud Serverless 
+  AWS Cloud Serverless 
+  Tencent Cloud Serverless 
+  Baidu Cloud Serverless 
+  Dev Template for Serverless Devs 
+```
+
+此时，选择最后的`Dev Template for Serverless Devs`，并按回车：
+
+```shell script
+$ s init
+
+🚀 Serverless Awesome: https://github.com/Serverless-Devs/package-awesome
+
+? Hello Serverless for Cloud Vendors Dev Template for Serverless Devs
+? Please select an Serverless-Devs Application (Use arrow keys or type to search)
+❯ Application Scaffolding 
+  Component Scaffolding 
+```
+
+此时，选择`Component Scaffolding`，并按回车，即可完成一个完整的Serverless Devs的Component项目的初始化，可以通过命令查看文件树：
+
+```shell script
+$ find . -print | sed -e 's;[^/]*/;|____;g;s;____|; |;g'
+.
+|____readme.md
+|____version.md
+|____publish.yaml
+|____src
+| |____s.yaml
+| |____index.js
+```
+
+这其中：
+
+| 目录 | 含义 |
+| --- | --- | 
+| readme.md | 对该组件的描述，或帮助文档信息 | 
+| version.md | 版本的描述，例如当前版本的更新内容等 |  
+| publish.yaml | 项目所必须的文件，Serverless Devs Package的开发识别文档 |
+| src | 应用所在目录，需要包括`s.yaml`和相关的应用代码等 | 
+
+
+此时，开发者可以在src下完成应用的开发，并对项目进行`publish.yaml`文件的编写。完成之后，即可将项目发不到不同的源，以Github Registry为例，可以在Github创建一个`Public`的仓库，并将编译后的代码放到仓库，并发布一个版本。此时，就可以通过客户端获取到该应用。

package/docs/zh/quick_start.md

@@ -0,0 +1,297 @@
+# 快速上手
+
+本快速上手案例以 [阿里云函数计算](https://www.aliyun.com/product/fc) 为例（当然，Serverless Devs 还支持 [AWS Lambda](../../components/lambda/readme.md)，[百度智能云函数计算](../../components/cfc/readme.md)，[华为云函数工作流](../../components/fg/readme.md)，[腾讯云云函数](../../components/scf/readme.md)等多个云厂商的 FaaS 平台，具体可以参考[默认FaaS产品支持](../../components/readme_zh.md)），快速上手 Serverless Devs
+
+- [工具安装](#工具安装)
+- [密钥配置](#密钥配置)
+- [上手体验](#上手体验)
+    - [Serverless：Hello World](#serverlesshello-world)
+    - [人工智能：目标检测](#人工智能目标检测)
+    - [传统框架：基于Django的博客项目](#传统框架基于django的博客项目)
+
+## 工具安装
+- 第一步：安装 Node.js(>=10.8.0) 与 NPM 包管理工具；  
+- 第二步：安装 Serverless Devs 开发者工具；   
+    ```shell script
+    $ npm install @serverless-devs/s -g
+    ```
+- 第三步：可以通过`s -v`判断工具是否安装成功，如果安装成功可以看到相对应的版本信息，例如：
+    ```shell script
+    @serverless-devs/s: 2.0.89, @serverless-devs/core: 0.1.7, darwin-x64, node-v12.15.0
+    ```
+
+## 密钥配置
+
+> 由于本快速上手文档，将会以 [阿里云函数计算](https://www.aliyun.com/product/fc) 为例，所以此处的密钥配置也是以阿里云密钥配置为例： 
+> - AccountId获取页面：https://account.console.aliyun.com/#/secure  
+> - 获取密钥页面：https://usercenter.console.aliyun.com/#/manage/ak
+
+- 打开 [AccountId获取页面](https://account.console.aliyun.com/#/secure) 获取AccountId ：
+  ![AccountId获取页面](https://images.devsapp.cn/access/aliyun-accountid.jpg)
+
+- 打开 [获取密钥页面](https://usercenter.console.aliyun.com/#/manage/ak) 获取密钥信息 ：
+  ![获取密钥页面](https://images.devsapp.cn/access/aliyun-access.jpg)
+ 
+- 执行`s config add`，并选择`Alibaba Cloud (alibaba)`：
+    ```shell script
+    $ s config add 
+    ? Please select a template: Alibaba Cloud (alibaba)
+    🧭 Refer to the document for alibaba key:  http://config.devsapp.net/account/alibaba
+    ? AccountID () 
+    ```
+- 此时，可以按照引导，进行密钥的配置：
+    ```shell script
+    ? Please select a template: Alibaba Cloud (alibaba)
+    🧭 Refer to the document for alibaba key:  http://config.devsapp.net/account/alibaba
+    ? AccountID 此处填写AccountID
+    ? AccessKeyID 此处填写AccessKeyID
+    ? AccessKeySecret 此处填写AccessKeySecret
+    ? Please create alias for key pair. If not, please enter to skip alibaba-access
+    
+        Alias: alibaba-access
+        AccountID: 此处填写AccountID
+        AccessKeyID: 此处填写AccessKeyID
+        AccessKeySecret: 此处填写AccessKeySecret
+    
+    Configuration successful
+    ```
+- 为了验证密钥是否正确配置，可以通过`s config get -a alibaba-access`进行指定密钥的查看：
+    ```shell script
+    $ s config get -a alibaba-access
+    [2021-10-27T17:39:39.881] [INFO ] [S-CLI] - 
+    
+    alibaba-access:
+      AccountID: 此处填*******tID
+      AccessKeyID: 此处填*********yID
+      AccessKeySecret: 此处填*************ret
+    ```
+  
+  
+> 云账号 AccessKey 是您访问阿里云 API 的密钥，具有该账户完全的权限，请您务必妥善保管！不要通过任何方式（e.g. Github）将 AccessKey 公开到外部渠道，以避免被他人利用而造成 [安全威胁](https://help.aliyun.com/knowledge_detail/54059.html?spm=5176.2020520153.0.0.57f1336a8PQ1KR) 。    
+> 强烈建议您遵循 [阿里云安全最佳实践](https://help.aliyun.com/document_detail/102600.html?spm=5176.2020520153.0.0.57f1336a8PQ1KR) ，使用 RAM 子用户 AccessKey 来进行 API 调用。
+
+
+## 上手体验
+
+### Serverless：Hello World
+
+- 执行`s`命令：
+    ```shell script
+    $ s
+    ? Serverless Devs project is not detected. Do you want to create a new project? (Y/n) 
+    ```  
+- 填写`y`，并按回车，可以进入到创建引导部分：
+    ```shell script
+    🚀 Serverless Awesome: https://github.com/Serverless-Devs/package-awesome
+    
+    ? Hello Serverless for Cloud Vendors (Use arrow keys or type to search)
+    ❯ Alibaba Cloud Serverless 
+      AWS Cloud Serverless 
+      Baidu Cloud Serverless 
+      Huawei Cloud Serverless 
+      Tencent Cloud Serverless 
+      Dev Template for Serverless Devs 
+    ```
+
+- 此时只需要选择对应的选项，按照引导进行操作，即可。例如选择`Alibaba Cloud Serverless`，就可以看到阿里云Serverless产品下的应用模板分类:
+
+    ```shell script
+    ? Please select an Serverless-Devs Application (Use arrow keys or type to search)
+    ❯ fc-runtime-starter - 快速部署一个 FC 函数 
+      fc-custom-container-stater - 快速部署一个 custom-container 应用 
+      web-framework-stater - 快速部署一个 Web 框架 
+      static-website-stater - 快速部署一个静态网站 
+      serverless-best-practice - 快速体验 Serverless 最佳实践 
+    ```
+
+- 此时可以继续选择某分类下的具体应用进行初始化，例如选择`fc-runtime-starter`之后，可以看到该分类下的具体模板应用：
+
+    ```shell script
+    ? Please select an templete (Use arrow keys or type to search)
+    ❯ fc-http-nodejs - 快速部署一个 nodejs12 http函数 
+      fc-http-python - 快速部署一个 python3 http函数 
+      fc-http-php - 快速部署一个 php http函数 
+      fc-http-java - 快速部署一个 java8 http函数 
+      fc-event-nodejs - 快速部署一个 nodejs12 event函数 
+      fc-event-python - 快速部署一个 python3 event函数 
+      fc-event-php - 快速部署一个 php event函数 
+    ```
+
+    选择`fc-http-nodejs`即可完成创建，在引导的过程中，可能会出现填写项目名称以及选择密钥的过程：
+    - 项目名称可以是：`start-fc-http-nodejs12`
+    - 密钥可以选择我们上文中创建过的：`alibaba-access`    
+    
+    例如：
+    ```shell script 
+    🚀 Serverless Awesome: https://github.com/Serverless-Devs/package-awesome
+    
+    ? Hello Serverless for Cloud Vendors Alibaba Cloud Serverless
+    ? Please select an Serverless-Devs Application fc-runtime-starter - 快速部署一个 FC 函数
+    ? Please select an templete fc-http-nodejs - 快速部署一个 nodejs12 http函数
+    
+    😋 Create application command: [s init devsapp/start-fc-http-nodejs12]
+
+    ? Please input your project name (init dir) start-fc-http-nodejs12
+    ✔ file decompression completed
+    ? please select credential alias alibaba-access
+    
+    ... ...
+    
+    🏄‍ Thanks for using Serverless-Devs
+    👉 You could [cd /Users/jiangyu/start-application/start-fc-http-nodejs12] and enjoy your serverless journey!
+    🧭️ If you need help for this example, you can use [s -h] after you enter folder.
+    💞 Document ❤ Star：https://github.com/Serverless-Devs/Serverless-Devs
+    
+    ? 是否立即部署该项目？ (Y/n) 
+    ```
+- 可以看到，系统在最后有一个提醒，是否要部署该项目，此时可以输入`y`，直接进行项目的部署，稍等片刻，可以看到部署结果：
+    ```shell script
+    fc-deploy-test: 
+      region:   cn-hangzhou
+      service: 
+        name: fc-deploy-service
+      function: 
+        name:       http-trigger-nodejs12
+        runtime:    nodejs12
+        handler:    index.handler
+        memorySize: 128
+        timeout:    60
+      url: 
+        system_url:    https://1583208943291465.cn-hangzhou.fc.aliyuncs.com/2016-08-15/proxy/fc-deploy-service/http-trigger-nodejs12/
+        custom_domain: 
+          - 
+            domain: http://http-trigger-nodejs12.fc-deploy-service.1583208943291465.cn-hangzhou.fc.devsapp.net
+      triggers: 
+        - 
+          type: http
+          name: httpTrigger
+    ```
+    此时可以打开`domain`返回给我们的域名，进行测试。
+
+### 人工智能：目标检测
+
+- 初始化一个已有的人工智能目标检测项目：`s init devsapp/image-prediction-app`，初始化过程中可能会出现填写项目名称以及选择密钥的过程：
+    - 项目名称可以是：`image-prediction-app`
+    - 密钥可以选择我们上文中创建过的：`alibaba-access`    
+    
+    例如：
+    ```shell script
+    $ s init devsapp/image-prediction-app
+    
+    🚀 Serverless Awesome: https://github.com/Serverless-Devs/package-awesome
+    
+    ? Please input your project name (init dir) image-prediction-app
+    ✔ file decompression completed
+    ? please select credential alias alibaba-access
+    
+         ___   __   __  _______  _______  _______ 
+        |   | |  |_|  ||   _   ||       ||       |
+        |   | |       ||  |_|  ||    ___||    ___|
+        |   | |       ||       ||   | __ |   |___ 
+        |   | |       ||       ||   ||  ||    ___|
+        |   | | ||_|| ||   _   ||   |_| ||   |___ 
+        |___| |_|   |_||__| |__||_______||_______|
+                                            
+    
+        Welcome to the image-prediction-app application
+         This application requires to open these services: 
+             FC : https://fc.console.aliyun.com/
+         This application can help you quickly deploy the image-prediction-app project.
+         The application uses FC component：https://github.com/devsapp/fc
+         The application homepage: https://github.com/devsapp/image-prediction-app
+    
+    
+    🏄‍ Thanks for using Serverless-Devs
+    👉 You could [cd /Users/jiangyu/start-application/image-prediction-app] and enjoy your serverless journey!
+    🧭️ If you need help for this example, you can use [s -h] after you enter folder.
+    💞 Document ❤ Star：https://github.com/Serverless-Devs/Serverless-Devs
+    ```
+- 进入项目目录：`cd image-prediction-app`
+- 通过`deploy`命令进行项目的部署：
+    ```shell script
+    Tips for next step
+    ======================
+    * Display information of the deployed resource: s info
+    * Display metrics: s metrics
+    * Display logs: s logs
+    * Invoke remote function: s invoke
+    * Remove Service: s remove service
+    * Remove Function: s remove function
+    * Remove Trigger: s remove trigger
+    * Remove CustomDomain: s remove domain
+    
+    
+    
+    imageAi: 
+      region: cn-hangzhou
+      url: 
+        custom_domain: 
+          - 
+            domain: http://server.ai-cv-image-prediction.1583208943291465.cn-hangzhou.fc.devsapp.net
+    ```
+- 此时可以打开系统分配的测试域名，并上传一张图片进行测试：
+    ![图片alt](https://serverless-article-picture.oss-cn-hangzhou.aliyuncs.com/1635390067198_20211028030108110359.png)
+
+### 传统框架：基于Django的博客项目
+
+- 初始化一个已有的基于Django的博客项目：`s init django-blog`，初始化过程中可能会出现填写项目名称以及选择密钥的过程：
+    - 项目名称可以是：`django-blog`
+    - 密钥可以选择我们上文中创建过的：`alibaba-access`    
+    
+    例如：
+    ```shell script
+    $ s init django-blog
+
+    🚀 Serverless Awesome: https://github.com/Serverless-Devs/package-awesome
+    
+    ? Please input your project name (init dir) django-blog
+    ✔ file decompression completed
+    ? please select credential alias alibaba-access
+    
+         ______       ___  _______  __    _  _______  _______  _______  ___      _______  _______ 
+        |      |     |   ||   _   ||  |  | ||       ||       ||  _    ||   |    |       ||       |
+        |  _    |    |   ||  |_|  ||   |_| ||    ___||   _   || |_|   ||   |    |   _   ||    ___|
+        | | |   |    |   ||       ||       ||   | __ |  | |  ||       ||   |    |  | |  ||   | __ 
+        | |_|   | ___|   ||       ||  _    ||   ||  ||  |_|  ||  _   | |   |___ |  |_|  ||   ||  |
+        |       ||       ||   _   || | |   ||   |_| ||       || |_|   ||       ||       ||   |_| |
+        |______| |_______||__| |__||_|  |__||_______||_______||_______||_______||_______||_______|
+                                            
+    
+        Welcome to the django-blog application
+         This application requires to open these services: 
+             FC : https://fc.console.aliyun.com/
+         This application can help you quickly deploy the django-blog project.
+         The application uses Django component：https://github.com/devsapp/django
+         The application homepage: https://github.com/devsapp/django-blog
+         
+         * Python 3.7 is recommended;
+         * If the version is greater than Python 3.7: 
+            * Operation error: ImportError: cannot import name 'metadata' from 'importlib', you can refer to: https://stackoverflow.com/questions/59216175/importerror-cannot-import-name-metadata-from-importlib
+         * Default information:
+            * Admin：/admin
+            * Default Admin Username: blog
+            * Default Admin Password: myblog12345!     
+         
+    
+    
+    🏄‍ Thanks for using Serverless-Devs
+    👉 You could [cd /Users/jiangyu/django-blog] and enjoy your serverless journey!
+    🧭️ If you need help for this example, you can use [s -h] after you enter folder.
+    💞 Document ❤ Star：https://github.com/Serverless-Devs/Serverless-Devs
+    ```
+- 进入项目目录：`cd django-blog`
+- 通过`deploy`命令进行项目的部署：
+    ```shell script
+    Tips for next step
+    ======================
+    * Invoke remote function: s invoke
+    ✔ Try container acceleration
+    djangoBlog: 
+      region:        cn-shenzhen
+      serviceName:   serverless-devs-django
+      functionName:  django
+      customDomains: 
+        - http://django.serverless-devs-django.1583208943291465.cn-shenzhen.fc.devsapp.net
+    ```
+- 此时可以打开系统分配的测试域名，并上传一张图片进行测试：
+    ![图片alt](https://serverless-article-picture.oss-cn-hangzhou.aliyuncs.com/1635390266827_20211028030427642356.png)

package/docs/zh/readme.md

@@ -0,0 +1,90 @@
+# Serverless Devs 项目介绍
+
+![图片alt](https://serverless-article-picture.oss-cn-hangzhou.aliyuncs.com/1635390357469_20211028030558116850.png)
+
+
+<p align="center">
+<a href="./install.md">安装文档</a> |  <a href="./command/readme.md">命令行操作</a> | <a href="./yaml.md">Yaml规范</a> | <a href="./cicd.md">CI/CD平台集成</a> | <a href="./package_dev.md">Package开发文档</a>
+</p>
+
+
+
+**Serverless Devs** 是一个开源开放的 Serverless 开发者平台，致力于为开发者提供强大的工具链体系。通过该平台，开发者不仅可以一键体验多云 Serverless 产品，极速部署 Serverless 项目，还可以在 Serverless 应用全生命周期进行项目的管理，并且非常简单快速的将 Serverless Devs 与其他工具/平台进行结合，进一步提升研发、运维效能。
+
+
+- [6大优势](#6大优势)
+- [设计哲学](#设计哲学)
+- [成长历史](#成长历史)
+- [未来展望](#未来展望)
+- [交流社群](#交流社群)
+
+## 6大优势
+
+![图片alt](https://serverless-article-picture.oss-cn-hangzhou.aliyuncs.com/1635319587379_20211027072627561648.png)
+
+- **无厂商锁定**：得益于功能的可插拔特性，可以非常简单的支持不同云厂商的项目部署，或者一键部署到不同云平台。目前 Serverless Devs 已经支持了[阿里云函数计算](https://github.com/devsapp/fc) 、[AWS Lambda](https://github.com/devscomp/lambda) 、[百度智能云函数计算](https://github.com/xinwuyun/cfc) 、[华为云函数工作流](https://github.com/xinwuyun/fg) 、[腾讯云云函数](https://github.com/devscomp/scf) 等多云的 FaaS 产品；
+- **开源形式建设**：项目通过开源代码，开放生态进行建设的，开发者可以随时查看和参与 Serverless Devs 开发者工具的贡献，也可以随时随地进行相关组件和应用的贡献。当然，除了这种开源开放的形态，我们也鼓励一些企业级团队，通过 [Serverless Registry Model](./../../spec/zh/0.0.1/serverless_registry_model/readme.md) 建设自己的私有 Registry 以定制化某些不便公开的自定义组件；
+- **功能灵活可插拔**：Serverless Devs 开发者工具本身，不具备任何业务能力，所有的业务能力均是通过组件化的形式，进行可插拔式使用，并且每个组件可以根据需要，自定义相对应的命令和功能；开发者可以在一个应用中，选择不同的组件完成对应的业务能力，以满足对不同模块的诉求；
+- **简单快速上手**：通过开放 Serverless Registry 的模型/规范，该项目可以通过应用的模式，为开发者提供多种形式，多种领域以及[多种场景的上手案例](./awesome.md)，帮助开发者快速了解、学习、深入、上手 Serverless 架构，例如[新手引导](./quick_start.md)中的[**Serverless：Hello World**](./quick_start.md#serverlesshello-world)、[**人工智能：目标检测**](./quick_start.md#人工智能目标检测)、[**传统框架：基于Django的博客项目**](./quick_start.md#传统框架基于django的博客项目)等项目；
+- **应用全生命周期管理**：通过组件化的支持，Serverless Devs 可以在应用的全生命周期发挥重要的作用，以 [阿里云函数计算的FC组件](https://github.com/devsapp/fc) 为例，开发者可以在项目创建、项目的开发、调试、可观测性等多个层面进行项目的建设和管理；
+- **良好的集成与被集成性**：项目具有非常好的集成性与被集成性，可以通过组件化的支持，非常简单的与传统的生态进行有机结合。同时，Serverless Devs 开发者工具也可以非常简单的被集成到海量的自动化流程中，例如 [CI/CD文档](./cicd.md) 中，就举例了[**与 Github Action 的集成**](./cicd.md#与-github-action-的集成)、[**与 Gitee Go 的集成**](./cicd.md#与-gitee-go-的集成)[**与 Jenkins 的集成**](./cicd.md#与-jenkins-的集成) 等平台集成的案例；
+
+## 设计哲学
+
+Serverless Devs 是一个开源开发的 Serverless 领域的工具链项目，他不仅仅表示单纯的某个命令行工具，在一定程度上指的是一个完整的工具链体系。
+
+![](https://example-static.oss-cn-beijing.aliyuncs.com/github-static/01.png)
+
+在 Serverless Devs 中，拥有两个角色：
+
+- **开源贡献者**：开源贡献者将按照 [Serverless Package Model](./../../spec/zh/0.0.1/serverless_pacakge_model/readme.md) 进行[组件/应用的开发](./package_dev.md) ，并将内容发布到Serverless Hub中，既可以被更多人所使用；
+- **Serverless开发者**：通过开发者工具（包括[命令行工具](./install.md)以及桌面端等工具），进行[应用的初始化](./quick_start.md)，以及组件的使用；通过开发者工具，将业务按照预期部署到线上；
+
+在这样一个 Serverless Devs 的应用框架上，我们不难发现可以和其他任何一种模式/生态，具有相似的命名以及模块：
+
+- **Serverless Hub**：类似于一种组件、应用、案例中心；类似于 Docker Hub 等；
+- **Serverless Registry**：类似于一种组件、应用的管理工具或者规范模型；类似于 Python 生态中的 Pypi，类似于 Node.js 生态中的 NPM；
+
+当然，细心的你应该已经发现了，在 Serverless Hub 中，有两种形态的 Package（组件和应用）：
+
+同时通过上图也可以看到两个比较明显的词汇：Component和Application：
+- **Component**：指的是组件；是由 Package developer 开发并发布的符合 Serverless Package Model 规范的一段代码，通常这段代码会在应用中被引用，并在 Serverless Devs 开发者工具 中被加载，并按照预定的规则进行执行某些动作。例如，将用户的代码部署到 Serverless 平台；将 Serverless 应用进行构建和打包；对 Serverless 应用进行调试等；
+- **Application**：指的是应用；可以由 Package developer 公开发布到 Registry，以供更多人学习和使用，例如某位贡献者贡献了一个猫狗识别的案例到Registry；也可以由 Serverless developer 开发，例如某人开发了一个 人脸识别的应用；通常情况下一个应用可以引用一个或者多个组件，并通过 Serverless Devs 开发者工具 工具部署到 Serverless 平台，例如我开发了一个猫狗识别的应用，在这个应用中引用了 Lambda 组件帮助我将部分业务逻辑部署到 FaaS 平台，同时我也引用了 Website 组件帮助我把前端业务代码部署到对象存储中；
+
+Serverless Devs 的模型设计原则，是希望可以通过更加简单、科学、规范的 Serverless 工具链体系，让开发者更专注于业务逻辑，提升 Serverless 应用开发、部署、运维效率，通过该模型，开发者可以通过一种更灵活、更通用的方法使用不同云厂商以及开源的 Serverless 产品，进而更高效、更简洁、更便利的实现 Serverless 应用管理。
+
+## 成长历史
+
+![](https://example-static.oss-cn-beijing.aliyuncs.com/github-static/02.png)
+
+如果说 Serverless 提升了传统应用的开发效能，那么 Serverless Devs 开发者工具就是提升了 Serverless 应用开发的效能。随着时间的发展，Serverless Devs 也从 1.0 版本 到了 2.0 版本，更是从简单的单纯的效能提升，变成了更加规范、更加科学的效能提升。我们真切希望可以通过 Serverless Devs 的工具链模式和思路，为应用的开发，传统项目上 Serverless 架构提供巨大的便利和更科学的管理。
+
+- 2020年 10月23日，Serverless 开发者平台 Serverless Devs 正式开源
+- 2020 年11月，Serverless Devs 被 CNCF Landsacpe 收录, 成为国内首个进驻的 Serverless 工具
+- 2020 年11月，Serverless Developer Meetup 首召开，成 Serverless 开发者技术新渠道
+- 2020 年 11月，入围 InfoQ 评选 2020 年度十大开源新锐项目
+- 2020 年12月，Serverless Devs 下载次数突破 5000，组件&应用累计使用次数突破 10000
+- 2021年4月，Serverless Developer Meetup 在上海召开，并正式发布 Serverless Devs 2.0
+- 2021年6月，Serverless Devs 下载次数突破 10000
+- 2021年7月，Serverless Developer Meetup 在杭州召开，阿里云函数计算团队在会上正式发布端云联调、桌面客户端等功能
+- 2021年8月，Serverless Devs 下载次数突破 20000
+- 2021年10月，在***2021 OpenInfra Days China***会议上，Serverless Devs 带来了《Serverless Devs：Serverless全生命周期的工具链建设》的主题演讲
+
+## 未来展望
+
+Serverless Devs 将会在未来支持：
+- 支持更多的云厂商，云产品；
+- 将会开发和上线 Serverless Devs IDE Plugin；
+- 将会持续推动 Serverless 生态尤其是 Serverless 工具链生态的前进；
+
+关于我们的 Roadmap，可以参考 [Github Projects](#https://github.com/Serverless-Devs/Serverless-Devs/projects) 。
+
+## 交流社群
+
+<p align="center">
+
+| <img src="https://serverless-article-picture.oss-cn-hangzhou.aliyuncs.com/1635407298906_20211028074819117230.png" width="200px" > | <img src="https://serverless-article-picture.oss-cn-hangzhou.aliyuncs.com/1635407044136_20211028074404326599.png" width="200px" > | <img src="https://serverless-article-picture.oss-cn-hangzhou.aliyuncs.com/1635407252200_20211028074732517533.png" width="200px" > |
+|--- | --- | --- |
+| <center>关注微信公众号：`serverless`</center> | <center>联系微信小助手：`xiaojiangwh`</center> | <center>加入钉钉交流群：`33947367`</center> | 
+
+</p>

package/docs/zh/tool.md

@@ -0,0 +1,80 @@
+# 开发者工具设计文档
+
+- [Exit Code 定义](#exit-code-定义)
+- [命令行设计规范](#命令行设计规范)
+- [优先级定义](#优先级定义)
+    - [Yaml 文件优先级规范](#yaml-文件优先级规范)
+    - [应用内服务部署顺序](#应用内服务部署顺序)
+    - [密钥使用顺序与规范](#密钥使用顺序与规范)
+
+## Exit Code 定义
+
+| code | 含义 |
+| --- | --- |
+| 0 | 正常退出 |
+| 100 | Serverless Devs 工具本身错误退出 |
+| 101 | Serverless Devs 工具组件执行时，组件错误引起的退出 |
+
+## 命令行设计规范
+
+Serverless Devs 作为 Serverless 领域的开发者工具，其输出的标准化和规范化会在一定程度上对用户体验有比较明显的影响。
+
+关于 Serverless Devs 命令行设计规范，可以参考 [cli_design.md](./cli_design.md) 
+
+## 优先级定义
+
+在使用 Serverless Devs 开发者工具时，会遇到一些带有默认值的参数/变量，这一部分将会针对这些参数/变量，进行优先级划分，在每个类别下面的列表中，上面的情况优先级高于下面的情况，例如`Yaml 文件优先级规范`为案例，描述为：
+
+- 通过`-t/--template`参数指定的 Yaml 文件
+- 默认的 Yaml 文件（`s.yaml`/`s.yml`，且`s.yaml`的优先级大于`s.yml`）
+
+则 Serverless Devs 开发者工具在进行资源描述文件使用时，会优先选择`通过 -t/--template 参数指定的 Yaml 文件`，其次才会采用`默认的 Yaml 文件（ s.yaml/s.yml，且 s.yaml 的优先级大于 s.yml ）`
+
+
+### Yaml 文件优先级规范
+
+- 通过`-t/--template`参数指定的 Yaml 文件
+- 默认的 Yaml 文件（`s.yaml`/`s.yml`，且`s.yaml`的优先级大于`s.yml`）
+
+### 应用内服务部署顺序
+
+- 被依赖的 `service` 优先部署；
+- 从上到下的顺序，按顺序进行部署；
+
+> 例如，某资源描述 Yaml 可以缩写成：
+> ```yaml
+> edition: 1.0.0        #  命令行YAML规范版本，遵循语义化版本（Semantic Versioning）规范
+> name: FullStack       #  项目名称
+> access: xxx-account1  #  秘钥别名
+> 
+> services:
+>   nextjs-portal: #  服务名称
+>     component: vue-component  # 组件名称
+>     props: #  组件的属性值
+>       src: ./frontend_src
+>       url: url
+> 
+>   assets:
+>     component: static
+>     props:
+>       www: "./public"
+> 
+>   gateway:
+>     component: serverless-gateway # 路由组件：HTTP URL和服务之间的映射规则
+>     props:
+>       routes:
+>         - url: ${assets.output.url}
+> ```
+> 此时，可先进性依赖关系分析，服务`nextjs-portal`、`assets`没有额外依赖，服务`gateway`通过魔法变量`${assets.output.url}`依赖了`assets`服务；此时部署顺序则为：`gateway`优先部署，然后`nextjs-portal`、`assets`按照上下顺序部署，即：`gateway`->`nextjs-portal`->`assets`
+
+
+### 密钥使用顺序与规范
+
+- 通过`-a/--access`参数指定的密钥信息
+- 默认使用`default`密钥信息
+- 不实用密钥信息 / 进入密钥信息配置引导
+
+具体的流程图为：
+
+![图片alt](https://serverless-article-picture.oss-cn-hangzhou.aliyuncs.com/1635841483040_20211102082444588067.png)
+