doc: 为可扩展组件添加注释

pkg/pipeline/cntfilter/entities.py

@@ -31,15 +31,24 @@ class EnableStage(enum.Enum):
 
 class FilterResult(pydantic.BaseModel):
     level: ResultLevel
+    """结果等级
+
+    对于前置处理阶段，只要有任意一个返回 非PASS 的内容过滤器结果，就会中断处理。
+    对于后置处理阶段，当且内容过滤器返回 BLOCK 时，会中断处理。
+    """
 
     replacement: str
-    """替换后的消息"""
+    """替换后的消息
+    
+    内容过滤器可以进行一些遮掩处理，然后把遮掩后的消息返回。
+    若没有修改内容，也需要返回原消息。
+    """
 
     user_notice: str
-    """不通过时，用户提示消息"""
+    """不通过时，若此值不为空，将对用户提示消息"""
 
     console_notice: str
-    """不通过时，控制台提示消息"""
+    """不通过时，若此值不为空，将在控制台提示消息"""
 
 
 class ManagerResultLevel(enum.Enum):

pkg/pipeline/cntfilter/filter.py

@@ -46,6 +46,11 @@ class ContentFilter(metaclass=abc.ABCMeta):
     @property
     def enable_stages(self):
         """启用的阶段
+
+        默认为消息请求AI前后的两个阶段。
+
+        entity.EnableStage.PRE: 消息请求AI前，此时需要检查的内容是用户的输入消息。
+        entity.EnableStage.POST: 消息请求AI后，此时需要检查的内容是AI的回复消息。
         """
         return [
             entities.EnableStage.PRE,
@@ -60,5 +65,14 @@ class ContentFilter(metaclass=abc.ABCMeta):
     @abc.abstractmethod
     async def process(self, message: str) -> entities.FilterResult:
         """处理消息
+
+        分为前后阶段，具体取决于 enable_stages 的值。
+        对于内容过滤器来说，不需要考虑消息所处的阶段，只需要检查消息内容即可。
+        
+        Args:
+            message (str): 需要检查的内容
+
+        Returns:
+            entities.FilterResult: 过滤结果，具体内容请查看 entities.FilterResult 类的文档
         """
         raise NotImplementedError

pkg/pipeline/longtext/strategy.py

@@ -15,6 +15,15 @@ preregistered_strategies: list[typing.Type[LongTextStrategy]] = []
 def strategy_class(
     name: str
 ) -> typing.Callable[[typing.Type[LongTextStrategy]], typing.Type[LongTextStrategy]]:
+    """长文本处理策略类装饰器
+
+    Args:
+        name (str): 策略名称
+
+    Returns:
+        typing.Callable[[typing.Type[LongTextStrategy]], typing.Type[LongTextStrategy]]: 装饰器
+    """
+
     def decorator(cls: typing.Type[LongTextStrategy]) -> typing.Type[LongTextStrategy]:
         assert issubclass(cls, LongTextStrategy)
 
@@ -43,4 +52,15 @@ class LongTextStrategy(metaclass=abc.ABCMeta):
     
     @abc.abstractmethod
     async def process(self, message: str, query: core_entities.Query) -> list[MessageComponent]:
+        """处理长文本
+
+        在 platform.json 中配置 long-text-process 字段，只要 文本长度超过了 threshold 就会调用此方法
+
+        Args:
+            message (str): 消息
+            query (core_entities.Query): 此次请求的上下文对象
+
+        Returns:
+            list[mirai.models.messages.MessageComponent]: 转换后的 YiriMirai 消息组件列表
+        """
         return []

pkg/pipeline/ratelimit/algo.py

@@ -18,6 +18,7 @@ def algo_class(name: str):
 
 
 class ReteLimitAlgo(metaclass=abc.ABCMeta):
+    """限流算法抽象类"""
     
     name: str = None
 
@@ -31,9 +32,27 @@ class ReteLimitAlgo(metaclass=abc.ABCMeta):
 
     @abc.abstractmethod
     async def require_access(self, launcher_type: str, launcher_id: int) -> bool:
+        """进入处理流程
+
+        这个方法对等待是友好的，意味着算法可以实现在这里等待一段时间以控制速率。
+        
+        Args:
+            launcher_type (str): 请求者类型 群聊为 group 私聊为 person
+            launcher_id (int): 请求者ID
+
+        Returns:
+            bool: 是否允许进入处理流程，若返回false，则直接丢弃该请求
+        """
         raise NotImplementedError
     
     @abc.abstractmethod
     async def release_access(self, launcher_type: str, launcher_id: int):
+        """退出处理流程
+
+        Args:
+            launcher_type (str): 请求者类型 群聊为 group 私聊为 person
+            launcher_id (int): 请求者ID
+        """
+        
         raise NotImplementedError