Merge pull request #709 from RockChinQ/doc/comments

Doc: 补全部分注释

pkg/audit/center/apigroup.py

@@ -34,6 +34,9 @@ class APIGroup(metaclass=abc.ABCMeta):
         headers: dict = {},
         **kwargs
     ):
+        """
+        执行请求
+        """
         self._runtime_info['account_id'] = "-1"
         
         url = self.prefix + path

pkg/audit/identifier.py

@@ -1,3 +1,5 @@
+# 实例 识别码 控制
+
 import os
 import uuid
 import json

pkg/command/cmdmgr.py

@@ -7,6 +7,7 @@ from ..provider import entities as llm_entities
 from . import entities, operator, errors
 from ..config import manager as cfg_mgr
 
+# 引入所有算子以便注册
 from .operators import func, plugin, default, reset, list as list_cmd, last, next, delc, resend, prompt, cmd, help, version, update
 
 
@@ -17,6 +18,9 @@ class CommandManager:
     ap: app.Application
 
     cmd_list: list[operator.CommandOperator]
+    """
+    运行时命令列表，扁平存储，各个对象包含对应的子节点引用
+    """
 
     def __init__(self, ap: app.Application):
         self.ap = ap
@@ -60,7 +64,7 @@ class CommandManager:
         """
 
         found = False
-        if len(context.crt_params) > 0:
+        if len(context.crt_params) > 0:  # 查找下一个参数是否对应此节点的某个子节点名
             for oper in operator_list:
                 if (context.crt_params[0] == oper.name \
                     or context.crt_params[0] in oper.alias) \
@@ -78,7 +82,7 @@ class CommandManager:
                         yield ret
                     break
 
-        if not found:
+        if not found:  # 如果下一个参数未在此节点的子节点中找到，则执行此节点或者报错
             if operator is None:
                 yield entities.CommandReturn(
                     error=errors.CommandNotFoundError(context.crt_params[0])

pkg/command/entities.py

@@ -10,6 +10,8 @@ from . import errors, operator
 
 
 class CommandReturn(pydantic.BaseModel):
+    """命令返回值
+    """
 
     text: typing.Optional[str]
     """文本
@@ -24,6 +26,8 @@ class CommandReturn(pydantic.BaseModel):
 
 
 class ExecuteContext(pydantic.BaseModel):
+    """单次命令执行上下文
+    """
 
     query: core_entities.Query
 

pkg/command/operator.py

@@ -8,6 +8,7 @@ from . import entities
 
 
 preregistered_operators: list[typing.Type[CommandOperator]] = []
+"""预注册算子列表。在初始化时，所有算子类会被注册到此列表中。"""
 
 
 def operator_class(
@@ -34,7 +35,7 @@ def operator_class(
 
 
 class CommandOperator(metaclass=abc.ABCMeta):
-    """命令算子
+    """命令算子抽象类
     """
 
     ap: app.Application

pkg/core/app.py

@@ -19,6 +19,8 @@ from ..utils import version as version_mgr, proxy as proxy_mgr
 
 
 class Application:
+    """运行时应用对象和上下文"""
+
     im_mgr: im_mgr.PlatformManager = None
 
     cmd_mgr: cmdmgr.CommandManager = None
@@ -77,14 +79,7 @@ class Application:
                 asyncio.create_task(self.ctrl.run())
             ]
 
-            # async def interrupt(tasks):
-            #     await asyncio.sleep(1.5)
-            #     while await aioconsole.ainput("使用 ctrl+c 或 'exit' 退出程序 > ") != 'exit':
-            #         pass
-            #     for task in tasks:
-            #         task.cancel()
-            
-            # await interrupt(tasks)
+            # 挂信号处理
 
             import signal
 

pkg/core/boot.py

@@ -3,6 +3,8 @@ from __future__ import print_function
 from . import app
 from ..audit import identifier
 from . import stage
+
+# 引入启动阶段实现以便注册
 from .stages import load_config, setup_logger, build_app
 
 
@@ -20,6 +22,7 @@ async def make_app() -> app.Application:
 
     ap = app.Application()
 
+    # 执行启动阶段
     for stage_name in stage_order:
         stage_cls = stage.preregistered_stages[stage_name]
         stage_inst = stage_cls()

pkg/core/entities.py

@@ -16,6 +16,7 @@ from ..platform import adapter as msadapter
 
 
 class LauncherTypes(enum.Enum):
+    """一个请求的发起者类型"""
 
     PERSON = 'person'
     """私聊"""
@@ -77,7 +78,7 @@ class Query(pydantic.BaseModel):
 
 
 class Conversation(pydantic.BaseModel):
-    """对话"""
+    """对话，包含于 Session 中，一个 Session 可以有多个历史 Conversation，但只有一个当前使用的 Conversation""" 
 
     prompt: sysprompt_entities.Prompt
 
@@ -93,7 +94,7 @@ class Conversation(pydantic.BaseModel):
 
 
 class Session(pydantic.BaseModel):
-    """会话"""
+    """会话，一个 Session 对应一个 {launcher_type}_{launcher_id}"""
     launcher_type: LauncherTypes
 
     launcher_id: int
@@ -111,6 +112,7 @@ class Session(pydantic.BaseModel):
     update_time: typing.Optional[datetime.datetime] = pydantic.Field(default_factory=datetime.datetime.now)
 
     semaphore: typing.Optional[asyncio.Semaphore] = None
+    """当前会话的信号量，用于限制并发"""
 
     class Config:
         arbitrary_types_allowed = True

pkg/core/stage.py

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

pkg/core/stages/build_app.py

@@ -22,7 +22,7 @@ class BuildAppStage(stage.BootingStage):
     """
 
     async def run(self, ap: app.Application):
-        """启动
+        """构建app对象的各个组件对象并初始化
         """
 
         proxy_mgr = proxy.ProxyManager(ap)

pkg/pipeline/bansess/bansess.py

@@ -8,6 +8,7 @@ from ...config import manager as cfg_mgr
 
 @stage.stage_class('BanSessionCheckStage')
 class BanSessionCheckStage(stage.PipelineStage):
+    """访问控制处理阶段"""
 
     async def initialize(self):
         pass

pkg/pipeline/cntfilter/cntfilter.py

@@ -14,6 +14,7 @@ from .filters import cntignore, banwords, baiduexamine
 @stage.stage_class('PostContentFilterStage')
 @stage.stage_class('PreContentFilterStage')
 class ContentFilterStage(stage.PipelineStage):
+    """内容过滤阶段"""
 
     filter_chain: list[filter.ContentFilter]
 

pkg/pipeline/controller.py

@@ -85,7 +85,7 @@ class Controller:
         stage_index: int,
         query: entities.Query,
     ):
-        """从指定阶段开始执行
+        """从指定阶段开始执行，实现了责任链模式和基于生成器的阶段分叉功能。
 
         如何看懂这里为什么这么写？
         去问 GPT-4:

pkg/pipeline/longtext/longtext.py

@@ -15,6 +15,8 @@ from ...config import manager as cfg_mgr
 
 @stage.stage_class("LongTextProcessStage")
 class LongTextProcessStage(stage.PipelineStage):
+    """长消息处理阶段
+    """
 
     strategy_impl: strategy.LongTextStrategy
 

pkg/pipeline/pool.py

@@ -9,6 +9,7 @@ from ..platform import adapter as msadapter
 
 
 class QueryPool:
+    """请求池，请求获得调度进入pipeline之前，保存在这里"""
 
     query_id_counter: int = 0
 

pkg/pipeline/preproc/preproc.py

@@ -8,7 +8,7 @@ from ...plugin import events
 
 @stage.stage_class("PreProcessor")
 class PreProcessor(stage.PipelineStage):
-    """预处理器
+    """请求预处理阶段
     """
 
     async def process(

pkg/pipeline/process/process.py

@@ -11,6 +11,7 @@ from ...config import manager as cfg_mgr
 
 @stage.stage_class("MessageProcessor")
 class Processor(stage.PipelineStage):
+    """请求实际处理阶段"""
 
     cmd_handler: handler.MessageHandler
 

pkg/pipeline/ratelimit/ratelimit.py

@@ -11,6 +11,7 @@ from ...core import entities as core_entities
 @stage.stage_class("RequireRateLimitOccupancy")
 @stage.stage_class("ReleaseRateLimitOccupancy")
 class RateLimit(stage.PipelineStage):
+    """限速器控制阶段"""
 
     algo: algo.ReteLimitAlgo
 

pkg/pipeline/stagemgr.py

@@ -15,6 +15,7 @@ from .preproc import preproc
 from .ratelimit import ratelimit
 
 
+# 请求处理阶段顺序
 stage_order = [
     "GroupRespondRuleCheckStage",
     "BanSessionCheckStage",

pkg/plugin/installer.py

@@ -7,6 +7,7 @@ from ..core import app
 
 
 class PluginInstaller(metaclass=abc.ABCMeta):
+    """插件安装器抽象类"""
 
     ap: app.Application
 

pkg/plugin/installers/github.py

@@ -12,6 +12,8 @@ from ...utils import pkgmgr
 
 
 class GitHubRepoInstaller(installer.PluginInstaller):
+    """GitHub仓库插件安装器
+    """
 
     def get_github_plugin_repo_label(self, repo_url: str) -> list[str]:
         """获取username, repo"""

pkg/plugin/loader.py

@@ -9,7 +9,7 @@ from . import context, events
 
 
 class PluginLoader(metaclass=abc.ABCMeta):
-    """插件加载器"""
+    """插件加载器抽象类"""
 
     ap: app.Application
 

pkg/plugin/manager.py

@@ -10,6 +10,7 @@ from .installers import github
 
 
 class PluginManager:
+    """插件管理器"""
 
     ap: app.Application
 

pkg/plugin/setting.py

@@ -6,6 +6,7 @@ from . import context
 
 
 class SettingManager:
+    """插件设置管理器"""
 
     ap: app.Application
 

pkg/provider/entities.py

@@ -20,6 +20,8 @@ class ToolCall(pydantic.BaseModel):
 
 
 class Message(pydantic.BaseModel):
+    """消息"""
+
     role: str  # user, system, assistant, tool, command
 
     name: typing.Optional[str] = None

pkg/provider/requester/apis/chatcmpl.py

@@ -18,6 +18,8 @@ from ...tools import entities as tools_entities
 
 
 class OpenAIChatCompletion(api.LLMAPIRequester):
+    """OpenAI ChatCompletion API 请求器"""
+
     client: openai.AsyncClient
 
     async def initialize(self):

pkg/provider/requester/modelmgr.py

@@ -9,6 +9,7 @@ from .tokenizers import tiktoken
 
 
 class ModelManager:
+    """模型管理器"""
 
     ap: app.Application
 

pkg/provider/requester/token.py

@@ -6,6 +6,8 @@ import pydantic
 
 
 class TokenManager():
+    """鉴权 Token 管理器
+    """
 
     provider: str
 

pkg/provider/requester/tokenizer.py

@@ -9,6 +9,7 @@ from . import entities
 
 
 class LLMTokenizer(metaclass=abc.ABCMeta):
+    """LLM分词器抽象类"""
 
     ap: app.Application
 

pkg/provider/requester/tokenizers/tiktoken.py

@@ -8,6 +8,8 @@ from .. import entities
 
 
 class Tiktoken(tokenizer.LLMTokenizer):
+    """TikToken分词器
+    """
 
     async def count_token(
         self,

pkg/provider/session/sessionmgr.py

@@ -6,6 +6,8 @@ from ...core import app, entities as core_entities
 
 
 class SessionManager:
+    """会话管理器
+    """
 
     ap: app.Application
 
@@ -39,6 +41,8 @@ class SessionManager:
         return session
 
     async def get_conversation(self, session: core_entities.Session) -> core_entities.Conversation:
+        """获取对话或创建对话"""
+
         if not session.conversations:
             session.conversations = []
 

pkg/provider/sysprompt/sysprompt.py

@@ -6,6 +6,8 @@ from .loaders import single, scenario
 
 
 class PromptManager:
+    """Prompt管理器
+    """
 
     ap: app.Application
 

pkg/utils/proxy.py

@@ -7,6 +7,9 @@ from ..core import app
 
 
 class ProxyManager:
+    """代理管理器
+    """
+
     ap: app.Application
 
     forward_proxies: dict[str, str]

pkg/utils/version.py

@@ -10,6 +10,8 @@ from . import constants
 
 
 class VersionManager:
+    """版本管理器
+    """
 
     ap: app.Application