📝 Add more readme for packages

README.md

@@ -22,7 +22,7 @@ npm i @sisyphus.js/cli typescript --save-dev
 
 ### 2. 生成代码
 
-将需要编译的 .proto 文件放入项目下的 proto 文件夹中（也可以通过 `package.json` 的 `directories` 属性自动定义 ）
+将需要编译的 .proto 文件放入项目下的 proto 文件夹中（也可以通过 `package.json` 的 `directories` 属性自定义 ）
 
 ```json
 {

packages/sisyphus-cli/README.md

@@ -2,7 +2,12 @@
 
 [![](https://img.shields.io/npm/v/@sisyphus.js/cli)](https://www.npmjs.com/package/@sisyphus.js/cli)
 
-sisyphus.js 命令行界面，提供一个 sisygen 命令用于为 sisyphus.js 工程生成代码。
+sisyphus.js 命令行界面，提供一个 `sisygen` 命令用于为 sisyphus.js 工程生成代码。
+
+## Sisygen
+
+`sisygen` 是为了工程化与自动化代码生产而定制的命令，`sisygen` 只有一个参数需要指定，使用 `-O` 或者 `--output` 指定 ts 文件的生成目录，其他大部分的配置都集中在 `package.json` 中，所以
+sisygen 命令需要在某个包的根目录下执行。
 
 ## 配置 sisyphus.js 工程
 
@@ -44,7 +49,7 @@ sisyphus.js 命令行界面，提供一个 sisygen 命令用于为 sisyphus.js 
 sisyphus info cli Protoc plugins found in @sisyphus.js/compiler: core, proto, aip
 ```
 
-将插件名加入到 `package.json` 的 `protobuf.plugins` 字段中。
+将要使用的插件名加入到 `package.json` 的 `protobuf.plugins` 字段中，`sisygen` 就会在编译过程中调用这些插件。
 
 ```json
 {
@@ -65,9 +70,9 @@ sisyphus info cli Protoc plugins found in @sisyphus.js/compiler: core, proto, ai
 
 proto 之间的依赖是非常常见的，多数的 TypeScript/JavaScript 实现都编译将所有 proto 文件整合在一起，并生成所有文件。
 
-sisygen 采用 sisyphus-dist.json 文件来编排依赖与依赖中已经生成好的代码，这意味着可以将生成的代码推送到 npm 仓库中，并在后续复用这些代码。
+`sisygen` 采用 `sisyphus-dist.json` 文件来编排依赖与依赖中已经生成好的代码，这意味着可以将生成的代码推送到 npm 仓库中，并在后续复用这些代码。
 
-sisygen 会发现所有 dependencies 中符合 sisyphus.js 工程结构的包，并将 proto 文件加入编译时依赖，另外如果包还包含默认导入（package.json 中拥有 man 字段），sisygen
+`sisygen` 会发现所有 dependencies 中符合 sisyphus.js 工程结构的包，并将 proto 文件加入编译时依赖，另外如果包还包含默认导入（`package.json` 中拥有 man 字段），sisygen
 会自动导入此包，这一般用于有拓展字段定义的包，可以将拓展定义导出到 index.js 中，并被 sisyphus.js 编译器使用。
 
 ```json
@@ -78,13 +83,13 @@ sisygen 会发现所有 dependencies 中符合 sisyphus.js 工程结构的包，
 }
 ```
 
-上面的配置导致 sisygen 会自动将 @sisyphus.js/runtime 中 proto 文件加入编译时依赖中。
+上面的配置导致 `sisygen` 会自动将 `@sisyphus.js/runtime` 中 proto 文件加入编译时依赖中。
 
 ### sisyphus-dist.json 模块映射
 
-sisygen 会读取 proto 依赖包下面的 sisyphus-dist.json 文件，获取已经编译好的文件，并在生成代码时从该依赖包中导入。
+`sisygen` 会读取 proto 依赖包下面的 `sisyphus-dist.json` 文件，获取已经编译好的文件，并在生成代码时从该依赖包中导入。
 
-当没有 sisyphus-dist.json 时，sisygen 认为所有生成的 ts 文件都在同一个根目录下，并通过 proto 文件的结构导入相应的依赖。
+当没有 `sisyphus-dist.json` 时，`sisygen` 认为所有生成的 ts 文件都在同一个根目录下，并通过 proto 文件的结构导入相应的依赖。
 
 ```typescript
 // 当前文件 /google/showcase/v1beta1/echo.ts
@@ -93,6 +98,45 @@ sisygen 会读取 proto 依赖包下面的 sisyphus-dist.json 文件，获取已
 import {Duration} from '../../protobuf/duration'
 ```
 
-当有 @sisyphus.js/runtime 中拥有 sisyphus-dist.json 并包含 `google/protobuf/duration.ts`。
+当有 `@sisyphus.js/runtime` 中拥有 `sisyphus-dist.json` 并包含 `google/protobuf/duration.ts`。
+
+`sisygen` 会自动将 `/google/protobuf/duration` 映射为 `@sisyphus.js/runtime/lib/google/protobuf/duration`。
+
+```typescript
+// 当前文件 /google/showcase/v1beta1/echo.ts
+
+// 目标导入依赖 /google/protobuf/duration.ts
+import {Duration} from '@sisyphus.js/runtime/lib/google/protobuf/duration'
+```
+
+映射规则为`包名 + lib 文件夹 + 依赖模块`，例如上述例子中，就由 `@sisyphus.js/runtime`，`lib`，`google/protobuf/duration` 三部分构成。
+
+其中 lib 文件夹的值由 `package.json` 的 `directories.lib` 值决定，默认值为 `lib`。
+
+## package.json 属性
 
-sisygen 会自动将 `/google/protobuf/duration.ts` 映射为 `@sisyphus.js/runtime/lib/google/protobuf/duration`。
+由 sisyphus.js 拓展的 `package.json` 增加了以下属性来配置 sisyphus.js 工程。
+
+```json5
+{
+  "sisyphus": {
+    // 注册 sisygen 的编译器插件
+    "plugins": {
+      "core": "lib/core/index.js",
+      "proto": "lib/proto/index.js",
+      "aip": "lib/aip/index.js"
+    }
+  },
+  "protobuf": {
+    // 将指定名字的插件加入编译过程
+    "plugins": [
+      "core",
+      "aip"
+    ],
+    // 将指定的包加入编译源
+    "packages": [
+      "@sisyphus.js/google"
+    ]
+  }
+}
+```

packages/sisyphus-compiler/README.md

@@ -0,0 +1,101 @@
+# @sisyphus.js/compiler
+
+[![](https://img.shields.io/npm/v/@sisyphus.js/compiler)](https://www.npmjs.com/package/@sisyphus.js/compiler)
+
+sisyphus.js 编辑器，包含了三个基础插件的实现，分别是用于生成核心模块的 `core` 插件，用于生成支持 protobuf 二进制格式代码的 `proto` 插件与用于支持 aip 标准的 `aip` 插件。
+
+## 插件原理
+
+插件采用消息与订阅者模型来实现编译插件，将状态（State）作为消息，发放给能够处理此状态的生成器（Generator）。
+
+```typescript
+export interface GeneratingState<TKind extends string, TParent, TDesc, TTarget> {
+    readonly parent: TParent
+
+    readonly kind: TKind
+
+    readonly descriptor: TDesc
+
+    readonly target: TTarget
+
+    generatedElements: number
+
+    continue: boolean
+}
+```
+
+每个状态包含一个用于匹配订阅者的 `kind` 字段，`kind` 字段一致状态和生成器会匹配，并执行生成器的生成过程。
+
+`parent` 字段则表示状态的父状态，`descriptor` 表示当前状态的上下文，一般是 `MessageDescriptor` 之类的各种 `Descriptor`。
+
+`target` 字段表示这次状态生成的结果，一般为 `CodeBuilder`。
+
+`generatedElements` 是用于判断此次生成是否是空结果，当子状态进行了有效的生成时，将此字段递增 1。
+
+`continue` 则表示这次生成后还需不需要继续传递到下一个同 `kind` 的生成器。
+
+```typescript
+export type MessageGeneratingState = GeneratingState<'message', FileGeneratingState | MessageGeneratingState, MessageDescriptor, CodeBuilder>
+
+export type FieldGeneratingState = GeneratingState<'field', MessageGeneratingState, FieldDescriptor, CodeBuilder>
+```
+
+使用 `generate` 函数用于注册一个生成器，只需要提供 kind 与生成过程就可以注册一个生成器。
+
+```typescript
+generate<FieldGeneratingState>('field', it => {
+    // 生成器过程
+})
+```
+
+## 子状态
+
+调用 `advance` 方法既可将子状态广播给其他的生成器。
+
+```typescript
+for (let service of it.descriptor.services) {
+    advance<ServiceGeneratingState>({
+        kind: 'service', parent: it, descriptor: service, target: builder
+    })
+}
+```
+
+`advance` 方法会自动匹配 kind，将状态交付给对应的生成器，并在结束生成的时候，将子状态的 `generatedElements` 加到父状态中。
+
+## 插件入口点
+
+使用一个单 js 文件 import 所有的 生成器代码，就可以将这个 js 文件当作插件的入口点。
+
+```typescript
+import './enum'
+import './extension'
+import './field'
+import './file'
+import './message'
+import './service'
+import '../wellknown/core'
+```
+
+将入口点文件注册在 `package.json` 的 `sisyphus.plugins` 字段就可以被 `sisygen` 发现。
+
+## 插件覆盖
+
+使用 `state.continue` 字段可以控制是否将状态交由下一个生成器处理，将字段设置为 `false` 就可以就此中断此 state 的生成过程。
+
+值得注意的的是生成器的优先顺序是倒序，即最后注册的生成器最先收到 state。
+
+## CodeBuilder 与 ImportManager
+
+CodeBuilder 是一个用于生成 ts 代码的工具类，用于托管 CodeBlock 状态，代码缩进，换行等等。
+
+```typescript
+builder.beginBlock(`export namespace ${it.descriptor.interfaceName()}`)
+builder.normalize().appendLn(`export const name = '${it.descriptor.fullname()}'`)
+builder.endBlock()
+```
+
+ImportManager 则可以管理 ts 代码的模块导入关系，并自动生成 import 语句，支持 import 冲突检测，自动别名等等。
+
+```typescript
+const importedName = builder.importManager.import('@sisyphus.js/runtime', 'long')
+```

packages/sisyphus-google-aip/README.md

@@ -0,0 +1,5 @@
+# @sisyphus.js/google.aip
+
+[![](https://img.shields.io/npm/v/@sisyphus.js/google.aip)](https://www.npmjs.com/package/@sisyphus.js/google.aip)
+
+预编译的由 google 定义的特殊 protos 的 AIP 标准客户端，目前只包含 long running operation 客户端。  

packages/sisyphus-google-proto/README.md

@@ -0,0 +1,6 @@
+# @sisyphus.js/google.proto
+
+[![](https://img.shields.io/npm/v/@sisyphus.js/google.proto)](https://www.npmjs.com/package/@sisyphus.js/google.proto)
+
+预编译的由 google 定义的特殊 protos，包含二进制序列化/反序列化支持。  
+如果采用 `@sisyphus.js/transport-aip`，需要将此包加入 devDependencies 中，这样才能将拓展定义注册到编译过程中。

packages/sisyphus-google/README.md

@@ -0,0 +1,6 @@
+# @sisyphus.js/google
+
+[![](https://img.shields.io/npm/v/@sisyphus.js/google)](https://www.npmjs.com/package/@sisyphus.js/google)
+
+预编译的由 google 定义的特殊 protos，仅包含 Json 接口，定义了 Http/gRPC 转码标准。
+如果采用 `@sisyphus.js/transport-aip`，需要将此包加入 dependencies 中。