docs(avilla): resource-basic

GraiaProject · Jul 26, 2023 · 54b7ac6 · 54b7ac6
1 parent 50c4fcc
commit 54b7ac6
Show file tree

Hide file tree

Showing 4 changed files with 32 additions and 2 deletions.
diff --git a/docs/avilla/NAV.md b/docs/avilla/NAV.md
@@ -23,7 +23,6 @@
         - [消息链与元素](basic/message/chain-and-element.md)
         - [消息解析与匹配器](basic/message/matcher.md)
         - [消息链方法](basic/message/methods.md)
-    - [选择器概述与基本操作](basic/selector-further.md)
     - [过滤器 (Filter)](basic/filter.md)
     - [查询 (Query)](basic/query.md)
     - [资源 (Resource)](basic/resource.md)
@@ -46,6 +45,7 @@
     - Ryanvk 体系
         - [Fn 的初等使用](advance/ryanvk/fn-basic.md)
         - [核心职权 (CoreCapability)](advance/ryanvk/core-capability.md)
+        - [手杖 (Staff)](advance/ryanvk/staff.md)
         - [深入调查：实现](advance/ryanvk/isolate-perform-access.md)
         - [指导：如何选择 Collector](advance/ryanvk/howto-choice-collector.md)
         - [自定义 Fn](advance/ryanvk/fn-further.md)

diff --git a/docs/avilla/basic/selector-further.md → docs/avilla/advance/ryanvk/staff.md b/docs/avilla/basic/selector-further.md → docs/avilla/advance/ryanvk/staff.md
diff --git a/docs/avilla/basic/hello-avilla/element-picture.md b/docs/avilla/basic/hello-avilla/element-picture.md
@@ -26,7 +26,7 @@ Picture 元素需要一个提供类型为 `bytes` 的资源 (Resource)，
     Picture(RawResource(b'...'))
     ```
 
-而对于协议实现，情况有所不同。不同的协议实现，根据其对接对象所需的与给出的信息，
+而对于协议实现，情况有所不同。不同的协议实现，根据其对接平台所需的与给出的信息，
 协议实现会自行声明各种的资源类。如 OneBot/v11 协议实现就派生了 `OneBot11ImageResource`，`OneBot11FileResource` 等资源类。
 在实际情况中，如果需要获取资源本身的详细信息，你有两种方法：一是使用[元信息 (Metadata) 机制](/avilla/basic/metadata-basic.md)，如果资源类型本身支持，也是我们所推荐的方法；二是通过 `isinstance` 类型自省。
 

diff --git a/docs/avilla/basic/hello-avilla/resource-basic.md b/docs/avilla/basic/hello-avilla/resource-basic.md
@@ -0,0 +1,30 @@
+资源 (Resource) 是 Avilla 对于提供某种类型的资源的抽象，
+其只关心特定类型资源的提供，而不关心其背后的细节。
+
+通常，我们使用 `Context.fetch` 方法来拉取资源内容。
+
+得益于 typing，你可以在这方面得到更优秀的自动补全。
+
+```python
+a = await cx.fetch(LocalFileResource(...))
+
+# LocalFileResource <: Resource[bytes]
+reveal_type(a) # => bytes
+```
+
+## 元信息
+
+对于 Resource，如果其实现了 `to_selector` 方法，则可以通过 `Context.pull` 或是 `Staff.pull_metadata` 方法获取一个资源类实例的 Metadata。
+
+你可以在以下文档中找到更详细的信息：
+
+- [元信息 (Metadata) 基本操作](/avilla/basic/metadata-basic.md)
+- [手杖 (Staff)](/avilla/advance/ryanvk/staff.md)
+
+!!! warning
+    对于不同的协议实现，根据其对接平台所需的与给出的信息，
+    协议实现会自行声明各种的资源类。如 OneBot/v11 协议实现就派生了 `OneBot11ImageResource`，`OneBot11FileResource` 等资源类。
+    在实际情况中，如果需要获取资源本身的详细信息，你有两种方法：
+    一是使用[元信息 (Metadata) 机制](/avilla/basic/metadata-basic.md)，
+    如果资源类型本身支持，也是我们所推荐的方法；
+    二是使用 `isinstance` 类型自省。