From 2fe6d731b85f60ee5216e5e6416729a48a7c848d Mon Sep 17 00:00:00 2001
From: RockChinQ <1010553892@qq.com>
Date: Sun, 3 Mar 2024 16:34:59 +0800
Subject: [PATCH] =?UTF-8?q?doc:=20=E8=A1=A5=E5=85=A8=E9=83=A8=E5=88=86?=
 =?UTF-8?q?=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 pkg/audit/center/apigroup.py                  |  3 +++
 pkg/audit/identifier.py                       |  2 ++
 pkg/command/cmdmgr.py                         |  8 ++++++--
 pkg/command/entities.py                       |  4 ++++
 pkg/command/operator.py                       |  3 ++-
 pkg/core/app.py                               | 11 +++--------
 pkg/core/boot.py                              |  3 +++
 pkg/core/entities.py                          |  6 ++++--
 pkg/core/stage.py                             |  1 +
 pkg/core/stages/build_app.py                  |  2 +-
 pkg/pipeline/bansess/bansess.py               |  1 +
 pkg/pipeline/cntfilter/cntfilter.py           |  1 +
 pkg/pipeline/controller.py                    |  2 +-
 pkg/pipeline/longtext/longtext.py             |  2 ++
 pkg/pipeline/pool.py                          |  1 +
 pkg/pipeline/preproc/preproc.py               |  2 +-
 pkg/pipeline/process/process.py               |  1 +
 pkg/pipeline/ratelimit/ratelimit.py           |  1 +
 pkg/pipeline/stagemgr.py                      |  1 +
 pkg/plugin/installer.py                       |  1 +
 pkg/plugin/installers/github.py               |  2 ++
 pkg/plugin/loader.py                          |  2 +-
 pkg/plugin/manager.py                         |  1 +
 pkg/plugin/setting.py                         |  1 +
 pkg/provider/entities.py                      |  2 ++
 pkg/provider/requester/apis/chatcmpl.py       |  2 ++
 pkg/provider/requester/modelmgr.py            |  1 +
 pkg/provider/requester/token.py               |  2 ++
 pkg/provider/requester/tokenizer.py           |  1 +
 pkg/provider/requester/tokenizers/tiktoken.py |  2 ++
 pkg/provider/session/sessionmgr.py            |  4 ++++
 pkg/provider/sysprompt/sysprompt.py           |  2 ++
 pkg/utils/proxy.py                            |  3 +++
 pkg/utils/version.py                          |  2 ++
 34 files changed, 66 insertions(+), 17 deletions(-)

diff --git a/pkg/audit/center/apigroup.py b/pkg/audit/center/apigroup.py
index 10b6d8d..26eac7a 100644
--- a/pkg/audit/center/apigroup.py
+++ b/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
diff --git a/pkg/audit/identifier.py b/pkg/audit/identifier.py
index 334b7e3..7c197c1 100644
--- a/pkg/audit/identifier.py
+++ b/pkg/audit/identifier.py
@@ -1,3 +1,5 @@
+# 实例 识别码 控制
+
 import os
 import uuid
 import json
diff --git a/pkg/command/cmdmgr.py b/pkg/command/cmdmgr.py
index 1e622b9..93ed8f8 100644
--- a/pkg/command/cmdmgr.py
+++ b/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])
diff --git a/pkg/command/entities.py b/pkg/command/entities.py
index f5f8bef..ee698b2 100644
--- a/pkg/command/entities.py
+++ b/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
 
diff --git a/pkg/command/operator.py b/pkg/command/operator.py
index 1247aa0..a666f2c 100644
--- a/pkg/command/operator.py
+++ b/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
diff --git a/pkg/core/app.py b/pkg/core/app.py
index 80f6cc3..ed035e5 100644
--- a/pkg/core/app.py
+++ b/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
 
diff --git a/pkg/core/boot.py b/pkg/core/boot.py
index c579030..46f0676 100644
--- a/pkg/core/boot.py
+++ b/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()
diff --git a/pkg/core/entities.py b/pkg/core/entities.py
index dacb64e..78bcf1f 100644
--- a/pkg/core/entities.py
+++ b/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
diff --git a/pkg/core/stage.py b/pkg/core/stage.py
index cb8e90e..a4ff7af 100644
--- a/pkg/core/stage.py
+++ b/pkg/core/stage.py
@@ -7,6 +7,7 @@ from . import app
 
 
 preregistered_stages: dict[str, typing.Type[BootingStage]] = {}
+"""预注册的请求处理阶段。在初始化时，所有请求处理阶段类会被注册到此字典中。"""
 
 def stage_class(
     name: str
diff --git a/pkg/core/stages/build_app.py b/pkg/core/stages/build_app.py
index 7a840b8..a6c0fe3 100644
--- a/pkg/core/stages/build_app.py
+++ b/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)
diff --git a/pkg/pipeline/bansess/bansess.py b/pkg/pipeline/bansess/bansess.py
index f56babe..3add6f1 100644
--- a/pkg/pipeline/bansess/bansess.py
+++ b/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
diff --git a/pkg/pipeline/cntfilter/cntfilter.py b/pkg/pipeline/cntfilter/cntfilter.py
index 9982a51..92157bd 100644
--- a/pkg/pipeline/cntfilter/cntfilter.py
+++ b/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]
 
diff --git a/pkg/pipeline/controller.py b/pkg/pipeline/controller.py
index a48c664..645014d 100644
--- a/pkg/pipeline/controller.py
+++ b/pkg/pipeline/controller.py
@@ -85,7 +85,7 @@ class Controller:
         stage_index: int,
         query: entities.Query,
     ):
-        """从指定阶段开始执行
+        """从指定阶段开始执行，实现了责任链模式和基于生成器的阶段分叉功能。
 
         如何看懂这里为什么这么写？
         去问 GPT-4:
diff --git a/pkg/pipeline/longtext/longtext.py b/pkg/pipeline/longtext/longtext.py
index ab70732..2962ae2 100644
--- a/pkg/pipeline/longtext/longtext.py
+++ b/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
 
diff --git a/pkg/pipeline/pool.py b/pkg/pipeline/pool.py
index 1514929..bd48c48 100644
--- a/pkg/pipeline/pool.py
+++ b/pkg/pipeline/pool.py
@@ -9,6 +9,7 @@ from ..platform import adapter as msadapter
 
 
 class QueryPool:
+    """请求池，请求获得调度进入pipeline之前，保存在这里"""
 
     query_id_counter: int = 0
 
diff --git a/pkg/pipeline/preproc/preproc.py b/pkg/pipeline/preproc/preproc.py
index ad0d7ff..c0eb92d 100644
--- a/pkg/pipeline/preproc/preproc.py
+++ b/pkg/pipeline/preproc/preproc.py
@@ -8,7 +8,7 @@ from ...plugin import events
 
 @stage.stage_class("PreProcessor")
 class PreProcessor(stage.PipelineStage):
-    """预处理器
+    """请求预处理阶段
     """
 
     async def process(
diff --git a/pkg/pipeline/process/process.py b/pkg/pipeline/process/process.py
index 6dbb700..ddf8809 100644
--- a/pkg/pipeline/process/process.py
+++ b/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
 
diff --git a/pkg/pipeline/ratelimit/ratelimit.py b/pkg/pipeline/ratelimit/ratelimit.py
index cc8e4ac..a9e2979 100644
--- a/pkg/pipeline/ratelimit/ratelimit.py
+++ b/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
 
diff --git a/pkg/pipeline/stagemgr.py b/pkg/pipeline/stagemgr.py
index c855d81..23c7897 100644
--- a/pkg/pipeline/stagemgr.py
+++ b/pkg/pipeline/stagemgr.py
@@ -15,6 +15,7 @@ from .preproc import preproc
 from .ratelimit import ratelimit
 
 
+# 请求处理阶段顺序
 stage_order = [
     "GroupRespondRuleCheckStage",
     "BanSessionCheckStage",
diff --git a/pkg/plugin/installer.py b/pkg/plugin/installer.py
index 6a08943..13501c0 100644
--- a/pkg/plugin/installer.py
+++ b/pkg/plugin/installer.py
@@ -7,6 +7,7 @@ from ..core import app
 
 
 class PluginInstaller(metaclass=abc.ABCMeta):
+    """插件安装器抽象类"""
 
     ap: app.Application
 
diff --git a/pkg/plugin/installers/github.py b/pkg/plugin/installers/github.py
index 8908f18..93505ae 100644
--- a/pkg/plugin/installers/github.py
+++ b/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"""
diff --git a/pkg/plugin/loader.py b/pkg/plugin/loader.py
index d74bcde..d5f4a20 100644
--- a/pkg/plugin/loader.py
+++ b/pkg/plugin/loader.py
@@ -9,7 +9,7 @@ from . import context, events
 
 
 class PluginLoader(metaclass=abc.ABCMeta):
-    """插件加载器"""
+    """插件加载器抽象类"""
 
     ap: app.Application
 
diff --git a/pkg/plugin/manager.py b/pkg/plugin/manager.py
index 243d442..65646f4 100644
--- a/pkg/plugin/manager.py
+++ b/pkg/plugin/manager.py
@@ -10,6 +10,7 @@ from .installers import github
 
 
 class PluginManager:
+    """插件管理器"""
 
     ap: app.Application
 
diff --git a/pkg/plugin/setting.py b/pkg/plugin/setting.py
index 1ffc000..c193493 100644
--- a/pkg/plugin/setting.py
+++ b/pkg/plugin/setting.py
@@ -6,6 +6,7 @@ from . import context
 
 
 class SettingManager:
+    """插件设置管理器"""
 
     ap: app.Application
 
diff --git a/pkg/provider/entities.py b/pkg/provider/entities.py
index 2db29d1..2a55531 100644
--- a/pkg/provider/entities.py
+++ b/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
diff --git a/pkg/provider/requester/apis/chatcmpl.py b/pkg/provider/requester/apis/chatcmpl.py
index c41b50d..2d52001 100644
--- a/pkg/provider/requester/apis/chatcmpl.py
+++ b/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):
diff --git a/pkg/provider/requester/modelmgr.py b/pkg/provider/requester/modelmgr.py
index b197c9c..e1a48bc 100644
--- a/pkg/provider/requester/modelmgr.py
+++ b/pkg/provider/requester/modelmgr.py
@@ -9,6 +9,7 @@ from .tokenizers import tiktoken
 
 
 class ModelManager:
+    """模型管理器"""
 
     ap: app.Application
 
diff --git a/pkg/provider/requester/token.py b/pkg/provider/requester/token.py
index 9277c1a..b9ec7e0 100644
--- a/pkg/provider/requester/token.py
+++ b/pkg/provider/requester/token.py
@@ -6,6 +6,8 @@ import pydantic
 
 
 class TokenManager():
+    """鉴权 Token 管理器
+    """
 
     provider: str
 
diff --git a/pkg/provider/requester/tokenizer.py b/pkg/provider/requester/tokenizer.py
index 5af8a73..cdd9147 100644
--- a/pkg/provider/requester/tokenizer.py
+++ b/pkg/provider/requester/tokenizer.py
@@ -9,6 +9,7 @@ from . import entities
 
 
 class LLMTokenizer(metaclass=abc.ABCMeta):
+    """LLM分词器抽象类"""
 
     ap: app.Application
 
diff --git a/pkg/provider/requester/tokenizers/tiktoken.py b/pkg/provider/requester/tokenizers/tiktoken.py
index 0bf97b1..24d2d8b 100644
--- a/pkg/provider/requester/tokenizers/tiktoken.py
+++ b/pkg/provider/requester/tokenizers/tiktoken.py
@@ -8,6 +8,8 @@ from .. import entities
 
 
 class Tiktoken(tokenizer.LLMTokenizer):
+    """TikToken分词器
+    """
 
     async def count_token(
         self,
diff --git a/pkg/provider/session/sessionmgr.py b/pkg/provider/session/sessionmgr.py
index a781250..4ffec02 100644
--- a/pkg/provider/session/sessionmgr.py
+++ b/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 = []
 
diff --git a/pkg/provider/sysprompt/sysprompt.py b/pkg/provider/sysprompt/sysprompt.py
index 5500bb1..eb89e8a 100644
--- a/pkg/provider/sysprompt/sysprompt.py
+++ b/pkg/provider/sysprompt/sysprompt.py
@@ -6,6 +6,8 @@ from .loaders import single, scenario
 
 
 class PromptManager:
+    """Prompt管理器
+    """
 
     ap: app.Application
 
diff --git a/pkg/utils/proxy.py b/pkg/utils/proxy.py
index 7ebd317..3091bdd 100644
--- a/pkg/utils/proxy.py
+++ b/pkg/utils/proxy.py
@@ -7,6 +7,9 @@ from ..core import app
 
 
 class ProxyManager:
+    """代理管理器
+    """
+
     ap: app.Application
 
     forward_proxies: dict[str, str]
diff --git a/pkg/utils/version.py b/pkg/utils/version.py
index cf410c9..cba575b 100644
--- a/pkg/utils/version.py
+++ b/pkg/utils/version.py
@@ -10,6 +10,8 @@ from . import constants
 
 
 class VersionManager:
+    """版本管理器
+    """
 
     ap: app.Application