aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/docs
diff options
context:
space:
mode:
author简律纯 <i@jyunko.cn>2023-12-26 03:18:27 +0800
committer简律纯 <i@jyunko.cn>2023-12-26 03:18:27 +0800
commit434aa42c8b880f5b0e43ff8a3169443609bd3da4 (patch)
tree604531cae557f725eebb512f0acf33b0f9fe9c11 /docs
parent85fc0eb4cc7e7af8f5d02369603694d76b12d05e (diff)
downloadecho-434aa42c8b880f5b0e43ff8a3169443609bd3da4.tar.gz
echo-434aa42c8b880f5b0e43ff8a3169443609bd3da4.zip
refactor(docs): add site theme
Diffstat (limited to 'docs')
-rw-r--r--docs/API.md10
-rw-r--r--docs/Element.md8
-rw-r--r--docs/Event.md16
-rw-r--r--docs/Term.md32
-rw-r--r--docs/index.md20
5 files changed, 51 insertions, 35 deletions
diff --git a/docs/API.md b/docs/API.md
index 180d6c8..9022bc2 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -1,8 +1,12 @@
-# ES 1.0
+---
+title: API Reference
+---
-## API
+## ES 1.0
-### 1. `get_version`
+### API
+
+#### 1. `get_version`
| Method | field | type | notes |
| :-: | :-: | :--: | :----: |
diff --git a/docs/Element.md b/docs/Element.md
index de30025..21e3f8d 100644
--- a/docs/Element.md
+++ b/docs/Element.md
@@ -1,5 +1,9 @@
-# ES 1.0
+---
+title: Element
+---
-## Element
+## ES 1.0
+
+### Element
..
diff --git a/docs/Event.md b/docs/Event.md
index 2e74a45..ae7fb01 100644
--- a/docs/Event.md
+++ b/docs/Event.md
@@ -1,17 +1,21 @@
-# ES 1.0
+---
+title: Event
+---
-## Event
+## ES 1.0
+### Event
-### 1. Workflow
+#### 1. Workflow
-### 2. Message
+#### 2. Message
-### 3. Notice
+#### 3. Notice
-### 4. Callback
+
+#### 4. Callback
diff --git a/docs/Term.md b/docs/Term.md
index 82490fa..08a1d2f 100644
--- a/docs/Term.md
+++ b/docs/Term.md
@@ -1,18 +1,22 @@
-# ES 1.0
+---
+title: Term
+---
-## Term
+## ES 1.0
+
+### Term
> [!IMPORTANT]
>
> Echo 标准只作用于多人聊天窗口(Window)。
-### Window
+#### Window
窗口(Window),一个能呼出水系骰子并能与之交互且能提供消息显示与聊天输入功能的窗体被称为聊天窗口,简称窗口。
-### World
+#### World
广义上,一个包含多个(至少两个)用户的聊天窗口即为一个 World(世界)。你可以将此类比为 QQ 平台的群聊(Group)或者 KOOK/Discord 平台的频道(Channel)——但是在(水系)这里,它们都统一被称为 World。
@@ -21,51 +25,51 @@
> 单人群聊不能算作一个世界,即使此群聊有一个骰子且一个用户,也不能成为一个世界,只有用户量 >= 2 且能够与水系骰子交互时才算是一个世界。
-### Sub-world/Main-world
+#### Sub-world/Main-world
狭义上讲,一个 World 应该在一段时间内只保持(也必须保持)一个规则包的绑定,因此类似于秘密团那样临时创建的分群或分频道并不能说是一个标准的 World,这类窗口我们称为 Sub-world(子世界),因此当涉及到 Sub-world 时,我们不能称主群/主频道 为World,而至少应该说是 Main-world(主世界)。
-### Node
+#### Node
Node(节点) 描述 ES 的实现端,这是它们的统一称谓。同时,通过 ES 所规定的 Events 传递的方向,可以扩展称为 1号节点(Node-1)、2号节点(Node-2) 甚至 3号节点(Node-3)...但是一般来说,两个节点已经足够使用了,Events 的传递方向总是由数字小的节点传递到数字大的节点,若 Events 能在节点间的传递过程中完成给定的任务,则这样的节点传递过程被成为一套完整的 pipeline。
-### Pipeline
+#### Pipeline
管线(Pipeline),或称“流水线”。这个概念可能比较抽象,因此在这里给出一个生动的形容——Pipeline,你土味一点,可翻译成“一条龙服务”;专业一点,叫它“综合解决方案”。
总之,一个 pipeline,一定是完整的,但不一定是闭合的。
-### Event
+#### Event
Event(事件)只存在于节点之间。事件划分为 Specific-events(具体事件,例如消息事件、世界人数增减事件等) 与 Abstract-events(抽象事件,例如工作流事件、回调事件等)。具体可翻阅事件一览表 [Events.md](./Event.md) 查看所有 ES 1.0 所支持的事件。
-### Element
+#### Element
Element(元素)尤其指代包含在 Events 中的各类可以被抽象出来的概念,比如文本(Text)、图片(Image)、富文本(RichText)、音频(Audio)、视频(Vedio)等。具体可翻阅元素列表 [Elements.md](./Element.md) 查看所有 ES 1.0 定义的元素。
-### API
+#### API
是指节点(尤其是 Node-2)需要实现的一些网络接口规范。具体参阅 ES 1.0 API列表 [API.md](./API.md)。
-### Without bells and whistles
+#### Without bells and whistles
没有花里胡哨的方法(不添加不必要,冗余的东西)。
-### Off-the-shelf
+#### Off-the-shelf
已有的,现成的。
-### end to end
+#### end to end
端到端(e2e),给定一个输入,再给出一个输出,不管其中的过程多么复杂,但只要给了一个输入,那么对应一个输出。
-### Priority
+#### Priority
优先级(priority),作用在 Events 中,尤其是 [Workflow Events]()。
diff --git a/docs/index.md b/docs/index.md
index b172dc8..ca107b3 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,8 +1,8 @@
-# 一、Echo 规范
+## 一、Echo 规范
ES 1.0.0 是 Echo 规范的第一个投入生产环境的版本,而 Echo 是水系规定 HydroRoll 与 infini 之间事件传参类型的一个内部标准,全称 Event Communication and Harmonization across Online platforms。
-## 1.1 版本 1.0.0
+### 1.1 版本 1.0.0
文档里的关键词 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" 都遵循 [BCP 14]、[RFC2119]、[RFC8174] 里的解释说明。
@@ -11,18 +11,18 @@ ES 1.0.0 是 Echo 规范的第一个投入生产环境的版本,而 Echo 是
[RFC8174]: https://datatracker.ietf.org/doc/html/rfc8174
-# 二、介绍
+## 二、介绍
Echo 规范(ES),是定义一个标准的、与具体编程语言无关的 RESTful API 与 Event Defined 规范。文字跑团(TRPG)游戏是一种基于文字描述和角色扮演的桌上游戏,通常由一个游戏主持人(KP)和多个玩家(PC)组成,通过网络平台进行交流和互动。不同的平台可能有不同的功能和限制,比如群聊、频道、图片、音频甚至视频等,这些都会影响到游戏的体验和效果。为了让水系的文字跑团游戏能够跨平台运行,ES 规定了游戏的数据结构、接口定义、错误处理等。这样,水系用户的 TRPG 游戏就可以在不同的平台上实现相同或相似的功能,同时也可以方便模型或规则包或插件开发者进行扩展和定制。
-# 三、术语定义
+## 三、术语定义
-## 3.1 ES 文档
+### 3.1 ES 文档
一(或多)份用来定义或描述一个 Event 以及 API 的文档。
-## 3.2 Media Types
+### 3.2 Media Types
媒体类型定义分散于多处。 媒体类型定义应当符合RFC6838。
@@ -41,21 +41,21 @@ text/plain; charset=utf-8
application/vnd.github.v3.patch
```
-## 3.3 HTTP状态码
+### 3.3 HTTP状态码
HTTP状态码被用来表示一次请求的被执行状态。[RFC7231] 定义了有效的状态码,可以在 [IANA Status Code Registry] 找到已经被注册的状态码的列表。
[RFC7231]: http://tools.ietf.org/html/rfc7231#section-6
[IANA Status Code Registry]: http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
-## 3.4 其他术语
+### 3.4 其他术语
包含 Window、World、Event、Element等词条,详见 [Term.md](./Term.md)。
-# 四、规范
+## 四、规范
-## 版本
+### 版本
开放 API 规范使用符合[语义化版本 2.0.0](http://semver.org/spec/v2.0.0.html)(semver)规范的版本号。版本号由三部分组成:主版本号.次版本号.修订号。每次更新文档时,根据以下规则递增版本号:
* 主版本号:当 API 有不兼容的修改时,递增主版本号,例如从 1.0.0 变为 2.0.0。