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

pkg/command/entities.py

@@ -20,6 +20,8 @@ class CommandReturn(pydantic.BaseModel):
     image: typing.Optional[mirai.Image]
 
     error: typing.Optional[errors.CommandError]= None
+    """错误
+    """
 
     class Config:
         arbitrary_types_allowed = True
@@ -30,17 +32,40 @@ class ExecuteContext(pydantic.BaseModel):
     """
 
     query: core_entities.Query
+    """本次消息的请求对象"""
 
     session: core_entities.Session
+    """本次消息所属的会话对象"""
 
     command_text: str
+    """命令完整文本"""
 
     command: str
+    """命令名称"""
 
     crt_command: str
+    """当前命令
+    
+    多级命令中crt_command为当前命令，command为根命令。
+    例如：!plugin on Webwlkr
+    处理到plugin时，command为plugin，crt_command为plugin
+    处理到on时，command为plugin，crt_command为on
+    """
 
     params: list[str]
+    """命令参数
+    
+    整个命令以空格分割后的参数列表
+    """
 
     crt_params: list[str]
+    """当前命令参数
+
+    多级命令中crt_params为当前命令参数，params为根命令参数。
+    例如：!plugin on Webwlkr
+    处理到plugin时，params为['on', 'Webwlkr']，crt_params为['on', 'Webwlkr']
+    处理到on时，params为['on', 'Webwlkr']，crt_params为['Webwlkr']
+    """
 
     privilege: int
+    """发起人权限"""

pkg/command/operator.py

@@ -52,6 +52,11 @@ def operator_class(
 
 class CommandOperator(metaclass=abc.ABCMeta):
     """命令算子抽象类
+
+    以下的参数均不需要在子类中设置，只需要在使用装饰器注册类时作为参数传递即可。
+    命令支持级联，即一个命令可以有多个子命令，子命令可以有子命令，以此类推。
+    处理命令时，若有子命令，会以当前参数列表的第一个参数去匹配子命令，若匹配成功，则转移到子命令中执行。
+    若没有匹配成功或没有子命令，则执行当前命令。
     """
 
     ap: app.Application
@@ -60,7 +65,8 @@ class CommandOperator(metaclass=abc.ABCMeta):
     """名称，搜索到时若符合则使用"""
 
     path: str
-    """路径，所有父节点的name的连接，用于定义命令权限"""
+    """路径，所有父节点的name的连接，用于定义命令权限，由管理器在初始化时自动设置。
+    """
 
     alias: list[str]
     """同name"""
@@ -69,6 +75,7 @@ class CommandOperator(metaclass=abc.ABCMeta):
     """此节点的帮助信息"""
 
     usage: str = None
+    """用法"""
 
     parent_class: typing.Union[typing.Type[CommandOperator], None] = None
     """父节点类。标记以供管理器在初始化时编织父子关系。"""
@@ -92,4 +99,15 @@ class CommandOperator(metaclass=abc.ABCMeta):
         self,
         context: entities.ExecuteContext
     ) -> typing.AsyncGenerator[entities.CommandReturn, None]:
+        """实现此方法以执行命令
+
+        支持多次yield以返回多个结果。
+        例如：一个安装插件的命令，可能会有下载、解压、安装等多个步骤，每个步骤都可以返回一个结果。
+        
+        Args:
+            context (entities.ExecuteContext): 命令执行上下文
+
+        Yields:
+            entities.CommandReturn: 命令返回封装
+        """
         pass

pkg/config/migration.py

@@ -7,6 +7,7 @@ from ..core import app
 
 
 preregistered_migrations: list[typing.Type[Migration]] = []
+"""当前阶段暂不支持扩展"""
 
 def migration_class(name: str, number: int):
     """注册一个迁移

pkg/core/stage.py

@@ -7,7 +7,10 @@ from . import app
 
 
 preregistered_stages: dict[str, typing.Type[BootingStage]] = {}
-"""预注册的请求处理阶段。在初始化时，所有请求处理阶段类会被注册到此字典中。"""
+"""预注册的请求处理阶段。在初始化时，所有请求处理阶段类会被注册到此字典中。
+
+当前阶段暂不支持扩展
+"""
 
 def stage_class(
     name: str

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
  

pkg/platform/adapter.py

@@ -14,6 +14,14 @@ preregistered_adapters: list[typing.Type[MessageSourceAdapter]] = []
 def adapter_class(
     name: str
 ):
+    """消息平台适配器类装饰器
+
+    Args:
+        name (str): 适配器名称
+
+    Returns:
+        typing.Callable[[typing.Type[MessageSourceAdapter]], typing.Type[MessageSourceAdapter]]: 装饰器
+    """
     def decorator(cls: typing.Type[MessageSourceAdapter]) -> typing.Type[MessageSourceAdapter]:
         cls.name = name
         preregistered_adapters.append(cls)
@@ -27,12 +35,19 @@ class MessageSourceAdapter(metaclass=abc.ABCMeta):
     name: str
 
     bot_account_id: int
+    """机器人账号ID，需要在初始化时设置"""
     
     config: dict
 
     ap: app.Application
 
     def __init__(self, config: dict, ap: app.Application):
+        """初始化适配器
+
+        Args:
+            config (dict): 对应的配置
+            ap (app.Application): 应用上下文
+        """
         self.config = config
         self.ap = ap
 

pkg/provider/entities.py

@@ -23,14 +23,19 @@ class Message(pydantic.BaseModel):
     """消息"""
 
     role: str  # user, system, assistant, tool, command, plugin
+    """消息的角色"""
 
     name: typing.Optional[str] = None
+    """名称，仅函数调用返回时设置"""
 
     content: typing.Optional[str] = None
+    """内容"""
 
     function_call: typing.Optional[FunctionCall] = None
+    """函数调用，不再受支持，请使用tool_calls"""
 
     tool_calls: typing.Optional[list[ToolCall]] = None
+    """工具调用"""
 
     tool_call_id: typing.Optional[str] = None
 

pkg/provider/modelmgr/api.py

@@ -38,6 +38,15 @@ class LLMAPIRequester(metaclass=abc.ABCMeta):
         self,
         query: core_entities.Query,
     ) -> typing.AsyncGenerator[llm_entities.Message, None]:
-        """请求
+        """请求API
+
+        对话前文可以从 query 对象中获取。
+        可以多次yield消息对象。
+
+        Args:
+            query (core_entities.Query): 本次请求的上下文对象
+
+        Yields:
+            pkg.provider.entities.Message: 返回消息对象
         """
         raise NotImplementedError

pkg/provider/sysprompt/entities.py

@@ -10,5 +10,7 @@ class Prompt(pydantic.BaseModel):
     """供AI使用的Prompt"""
 
     name: str
+    """名称"""
 
     messages: list[entities.Message]
+    """消息列表"""

pkg/provider/sysprompt/loader.py

@@ -36,7 +36,7 @@ class PromptLoader(metaclass=abc.ABCMeta):
 
     @abc.abstractmethod
     async def load(self):
-        """加载Prompt
+        """加载Prompt，存放到prompts列表中
         """
         raise NotImplementedError