🍻 publish plugin CS2 Bridge (#3890)

Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.github/actions/setup-node/action.yml

@@ -4,10 +4,10 @@ description: Setup Node
 runs:
   using: "composite"
   steps:
-    - uses: actions/setup-node@v4
+    - uses: actions/setup-node@v6
       with:
-        node-version: "18"
+        node-version: lts/*
-        cache: "yarn"
+        cache: yarn
 
     - run: yarn install --frozen-lockfile
       shell: bash

.github/actions/setup-python/action.yml

@@ -14,7 +14,7 @@ inputs:
 runs:
   using: "composite"
   steps:
-    - uses: astral-sh/setup-uv@v6
+    - uses: astral-sh/setup-uv@v7
       with:
         python-version: ${{ inputs.python-version }}
         cache-suffix: ${{ inputs.env-group }}

.github/workflows/codecov.yml

@@ -25,7 +25,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
         os: [ubuntu-latest, windows-latest, macos-latest]
         env: [pydantic-v1, pydantic-v2]
     env:
@@ -34,7 +34,7 @@ jobs:
       PYDANTIC_VERSION: ${{ matrix.env }}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Setup Python environment
         uses: ./.github/actions/setup-python

.github/workflows/noneflow.yml

@@ -45,7 +45,7 @@ jobs:
           private_key: ${{ secrets.APP_KEY }}
 
       - name: Checkout Code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           token: ${{ steps.generate-token.outputs.token }}
 
@@ -66,7 +66,7 @@ jobs:
           PRIVATE_KEY: ${{ secrets.APP_KEY }}
 
       - name: Upload Artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: noneflow
           path: artifact/*

.github/workflows/pyright.yml

@@ -28,7 +28,7 @@ jobs:
       fail-fast: false
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Setup Python environment
         uses: ./.github/actions/setup-python
@@ -43,6 +43,6 @@ jobs:
         shell: bash
 
       - name: Run Pyright
-        uses: jakebailey/pyright-action@v2
+        uses: jakebailey/pyright-action@v3
         with:
           pylance-version: latest-release

.github/workflows/release-drafter.yml

@@ -25,7 +25,7 @@ jobs:
           app_id: ${{ secrets.APP_ID }}
           private_key: ${{ secrets.APP_KEY }}
 
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           token: ${{ steps.generate-token.outputs.token }}
 
@@ -70,7 +70,7 @@ jobs:
           app_id: ${{ secrets.APP_ID }}
           private_key: ${{ secrets.APP_KEY }}
 
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Setup Python Environment
         uses: ./.github/actions/setup-python

.github/workflows/release.yml

@@ -14,7 +14,7 @@ jobs:
           app_id: ${{ secrets.APP_ID }}
           private_key: ${{ secrets.APP_KEY }}
 
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           token: ${{ steps.generate-token.outputs.token }}
 

.github/workflows/ruff.yml

@@ -24,7 +24,7 @@ jobs:
       cancel-in-progress: true
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Run Ruff Lint
         uses: astral-sh/ruff-action@v3

.github/workflows/website-deploy.yml

@@ -13,7 +13,7 @@ jobs:
       cancel-in-progress: true
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 

.github/workflows/website-preview-cd.yml

@@ -24,7 +24,7 @@ jobs:
 
     steps:
       - name: Set Commit Status
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         with:
           script: |
             github.rest.repos.createCommitStatus({
@@ -37,7 +37,7 @@ jobs:
             })
 
       - name: Download Artifact
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@v8
         with:
           name: website-preview
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -70,7 +70,7 @@ jobs:
 
       # action netlify has no pull request context, so we need to comment by ourselves
       - name: Comment on Pull Request
-        uses: marocchino/sticky-pull-request-comment@v2
+        uses: marocchino/sticky-pull-request-comment@v3
         with:
           header: website
           number: ${{ env.PR_NUMBER }}
@@ -78,7 +78,7 @@ jobs:
             :rocket: Deployed to ${{ steps.deploy.outputs.deploy-url }}
 
       - name: Set Commit Status
-        uses: actions/github-script@v7
+        uses: actions/github-script@v8
         if: always()
         with:
           script: |

.github/workflows/website-preview-ci.yml

@@ -11,7 +11,7 @@ jobs:
       cancel-in-progress: true
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           ref: ${{ github.event.pull_request.head.sha }}
           fetch-depth: 0
@@ -33,7 +33,7 @@ jobs:
           echo "${{ github.event.pull_request.number }}" > ./pr-number
 
       - name: Upload Artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: website-preview
           path: |

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ ci:
   autoupdate_commit_msg: ":arrow_up: auto update by pre-commit hooks"
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.7
+    rev: v0.15.4
     hooks:
       - id: ruff-check
         args: [--fix]

.prettierignore

@@ -1 +1,3 @@
 .github/**/*.md
+website/docs/tutorial/application.mdx
+website/versioned_docs/*/tutorial/application.mdx

README.md

@@ -129,7 +129,6 @@ NoneBot2 是一个现代、跨平台、可扩展的 Python 聊天机器人框架
   |     开黑啦（[仓库](https://github.com/Tian-que/nonebot-adapter-kaiheila)，[协议](https://developer.kookapp.cn/)）     |  ↗️  |                                由社区贡献                                 |
   |                          Ntchat（[仓库](https://github.com/JustUndertaker/adapter-ntchat)）                           |  ↗️  |                           微信协议，由社区贡献                            |
   |                      MineCraft（[仓库](https://github.com/17TheWord/nonebot-adapter-minecraft)）                      |  ↗️  |                                由社区贡献                                 |
-  |                          BiliBili Live（[仓库](https://github.com/wwweww/adapter-bilibili)）                          |  ↗️  |                                由社区贡献                                 |
   |                       Walle-Q（[仓库](https://github.com/onebot-walle/nonebot_adapter_walleq)）                       |  ↗️  |                            QQ 协议，由社区贡献                            |
   |                       Villa（[仓库](https://github.com/CMHopeSunshine/nonebot-adapter-villa)）                        |  ❌  |                     米游社大别野 Bot 协议，官方已下线                     |
   | Rocket.Chat（[仓库](https://github.com/IUnlimit/nonebot-adapter-rocketchat)，[协议](https://developer.rocket.chat/)） |  ↗️  |                     Rocket.Chat Bot 协议，由社区贡献                      |
@@ -139,6 +138,8 @@ NoneBot2 是一个现代、跨平台、可扩展的 Python 聊天机器人框架
   | 微信公众平台（[仓库](https://github.com/YangRucheng/nonebot-adapter-wxmp)，[协议](https://developers.weixin.qq.com/doc/)）|  ↗️  |                       微信公众平台协议，由社区贡献                             |
   | Gewechat（[仓库](https://github.com/Shine-Light/nonebot-adapter-gewechat)，[协议](https://github.com/Devo919/Gewechat)）|  ❌  |                      Gewechat 微信协议，Gewechat不再维护及可用                            |
   |  EFChat（[仓库](https://github.com/molanp/nonebot_adapter_efchat)，[协议](https://irinu-live.melon.fish/efc-help/)）   |  ↗️  |                            恒五聊平台协议，由社区贡献                          |
+  |  VoceChat （[仓库](https://github.com/5656565566/nonebot-adapter-vocechat)，[协议](https://doc.voce.chat/zh-cn/bot/bot-and-webhook)）   |  ↗️  |                            VoceChat 平台协议，由社区贡献                          |
+  |  B站直播间（[仓库](https://github.com/MingxuanGame/nonebot-adapter-bilibili-live)，[Web API 协议](https://github.com/SocialSisterYi/bilibili-API-collect/blob/master/docs/live)，[开放平台协议](https://open-live.bilibili.com/document)）   |  ↗️  |                            B站直播间（Web API/开放平台）协议，由社区贡献                          |
 
 - 坚实后盾：支持多种 web 框架，可自定义替换、组合
 

assets/adapters.json5

@@ -313,4 +313,44 @@
     ],
     "is_official": false
   },
+  {
+    "module_name": "nonebot.adapters.vocechat",
+    "project_link": "nonebot-adapter-vocechat",
+    "name": "nonebot-adapter-vocechat",
+    "desc": "Vocechat 协议适配器",
+    "author_id": 56059687,
+    "homepage": "https://github.com/5656565566/nonebot-adapter-vocechat",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "module_name": "nonebot.adapters.bilibili_live",
+    "project_link": "nonebot-adapter-bilibili-live",
+    "name": "B站直播间",
+    "desc": "B 站直播间协议（Web API/开放平台）支持",
+    "author_id": 68982190,
+    "homepage": "https://github.com/MingxuanGame/nonebot-adapter-bilibili-live",
+    "tags": [
+      {
+        "label": "bilibili",
+        "color": "#ff6699"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "module_name": "yunhu",
+    "project_link": "nonebot-adapter-yunhu",
+    "name": "云湖适配器",
+    "desc": "云湖的NoneBot适配器",
+    "author_id": 104612722,
+    "homepage": "https://github.com/molanp/nonebot-adapter-yunhu",
+    "tags": [
+      {
+        "label": "云湖",
+        "color": "#8a74eb"
+      }
+    ],
+    "is_official": false
+  },
 ]

assets/bots.json5

@@ -743,4 +743,38 @@
     "tags": [],
     "is_official": false
   },
+  {
+    "name": "Amrita",
+    "desc": "LLM聊天机器人框架",
+    "author_id": 67693593,
+    "homepage": "https://github.com/LiteSuggarDEV/Amrita",
+    "tags": [
+      {
+        "label": "聊天",
+        "color": "#ea5252"
+      },
+      {
+        "label": "LLM",
+        "color": "#5c86db"
+      },
+      {
+        "label": "快捷部署",
+        "color": "#eebe0b"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "Rosmontis.io",
+    "desc": "简单的机器人",
+    "author_id": 225668725,
+    "homepage": "https://github.com/com-wuqi/Rosmontis.io",
+    "tags": [
+      {
+        "label": "可爱",
+        "color": "#ea5252"
+      }
+    ],
+    "is_official": false
+  },
 ]

nonebot/__init__.py

@@ -47,7 +47,7 @@ FrontMatter:
 
 from importlib.metadata import version
 import os
-from typing import Any, Optional, TypeVar, Union, overload
+from typing import Any, TypeVar, overload
 
 import loguru
 
@@ -65,7 +65,7 @@ except Exception:  # pragma: no cover
 
 A = TypeVar("A", bound=Adapter)
 
-_driver: Optional[Driver] = None
+_driver: Driver | None = None
 
 
 def get_driver() -> Driver:
@@ -112,7 +112,7 @@ def get_adapter(name: type[A]) -> A:
     """
 
 
-def get_adapter(name: Union[str, type[Adapter]]) -> Adapter:
+def get_adapter(name: str | type[Adapter]) -> Adapter:
     """获取已注册的 {ref}`nonebot.adapters.Adapter` 实例。
 
     异常:
@@ -196,7 +196,7 @@ def get_asgi() -> Any:
     return driver.asgi
 
 
-def get_bot(self_id: Optional[str] = None) -> Bot:
+def get_bot(self_id: str | None = None) -> Bot:
     """获取一个连接到 NoneBot 的 {ref}`nonebot.adapters.Bot` 对象。
 
     当提供 `self_id` 时，此函数是 `get_bots()[self_id]` 的简写；
@@ -277,7 +277,7 @@ def _log_patcher(record: "loguru.Record"):
     )
 
 
-def init(*, _env_file: Optional[DOTENV_TYPE] = None, **kwargs: Any) -> None:
+def init(*, _env_file: DOTENV_TYPE | None = None, **kwargs: Any) -> None:
     """初始化 NoneBot 以及 全局 {ref}`nonebot.drivers.Driver` 对象。
 
     NoneBot 将会从 .env 文件中读取环境信息，并使用相应的 env 文件配置。

nonebot/compat.py

@@ -9,29 +9,29 @@ FrontMatter:
     description: nonebot.compat 模块
 """
 
-from collections.abc import Generator
+from collections.abc import Callable, Generator
 from dataclasses import dataclass, is_dataclass
-from functools import cached_property
+from functools import cached_property, wraps
 from typing import (
     TYPE_CHECKING,
     Annotated,
     Any,
-    Callable,
     Generic,
     Literal,
-    Optional,
     Protocol,
     TypeVar,
-    Union,
+    get_args,
+    get_origin,
     overload,
 )
-from typing_extensions import Self, get_args, get_origin, is_typeddict
+from typing_extensions import ParamSpec, Self, is_typeddict
 
 from pydantic import VERSION, BaseModel
 
 from nonebot.typing import origin_is_annotated
 
 T = TypeVar("T")
+P = ParamSpec("P")
 
 PYDANTIC_V2 = int(VERSION.split(".", 1)[0]) == 2
 
@@ -49,13 +49,13 @@ __all__ = (
     "PYDANTIC_V2",
     "ConfigDict",
     "FieldInfo",
+    "LegacyUnionField",
     "ModelField",
     "PydanticUndefined",
     "PydanticUndefinedType",
     "Required",
     "TypeAdapter",
     "custom_validation",
-    "extract_field_info",
     "field_validator",
     "model_config",
     "model_dump",
@@ -72,7 +72,7 @@ __autodoc__ = {
 
 
 if PYDANTIC_V2:  # pragma: pydantic-v2
-    from pydantic import GetCoreSchemaHandler
+    from pydantic import Field, GetCoreSchemaHandler
     from pydantic import TypeAdapter as TypeAdapter
     from pydantic import field_validator as field_validator
     from pydantic import model_validator as model_validator
@@ -95,7 +95,18 @@ if PYDANTIC_V2:  # pragma: pydantic-v2
     DEFAULT_CONFIG = ConfigDict(extra="allow", arbitrary_types_allowed=True)
     """Default config for validations"""
 
-    class FieldInfo(BaseFieldInfo):
+    def _get_legacy_union_field(func: Callable[P, T]) -> Callable[P, T]:
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            kwargs["union_mode"] = "left_to_right"
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    LegacyUnionField = _get_legacy_union_field(Field)
+    LegacyUnionField.__doc__ = "Mark field to use legacy left to right union mode"
+
+    class FieldInfo(BaseFieldInfo):  # pyright: ignore[reportGeneralTypeIssues]
         """FieldInfo class with extra property for compatibility with pydantic v1"""
 
         # make default can be positional argument
@@ -115,6 +126,20 @@ if PYDANTIC_V2:  # pragma: pydantic-v2
             slots = super().__slots__
             return {k: v for k, v in self._attributes_set.items() if k not in slots}
 
+        @classmethod
+        def _inherit_construct(
+            cls, field_info: BaseFieldInfo | None = None, **kwargs: Any
+        ) -> Self:
+            init_kwargs = {}
+            if field_info:
+                init_kwargs.update(field_info._attributes_set)
+            init_kwargs.update(kwargs)
+
+            instance = cls(**init_kwargs)
+            if field_info:
+                instance.metadata = field_info.metadata
+            return instance
+
     @dataclass
     class ModelField:
         """ModelField class for compatibility with pydantic v1"""
@@ -132,7 +157,7 @@ if PYDANTIC_V2:  # pragma: pydantic-v2
 
         @classmethod
         def construct(
-            cls, name: str, annotation: Any, field_info: Optional[FieldInfo] = None
+            cls, name: str, annotation: Any, field_info: FieldInfo | None = None
         ) -> Self:
             """Construct a ModelField from given infos."""
             return cls._construct(name, annotation, field_info or FieldInfo())
@@ -187,13 +212,6 @@ if PYDANTIC_V2:  # pragma: pydantic-v2
             """Validate the value pass to the field."""
             return self.type_adapter.validate_python(value)
 
-    def extract_field_info(field_info: BaseFieldInfo) -> dict[str, Any]:
-        """Get FieldInfo init kwargs from a FieldInfo instance."""
-
-        kwargs = field_info._attributes_set.copy()
-        kwargs["annotation"] = field_info.rebuild_annotation()
-        return kwargs
-
     def model_fields(model: type[BaseModel]) -> list[ModelField]:
         """Get field list of a model."""
 
@@ -201,7 +219,7 @@ if PYDANTIC_V2:  # pragma: pydantic-v2
             ModelField._construct(
                 name=name,
                 annotation=field_info.rebuild_annotation(),
-                field_info=FieldInfo(**extract_field_info(field_info)),
+                field_info=FieldInfo._inherit_construct(field_info),
             )
             for name, field_info in model.model_fields.items()
         ]
@@ -212,8 +230,8 @@ if PYDANTIC_V2:  # pragma: pydantic-v2
 
     def model_dump(
         model: BaseModel,
-        include: Optional[set[str]] = None,
+        include: set[str] | None = None,
-        exclude: Optional[set[str]] = None,
+        exclude: set[str] | None = None,
         by_alias: bool = False,
         exclude_unset: bool = False,
         exclude_defaults: bool = False,
@@ -232,7 +250,7 @@ if PYDANTIC_V2:  # pragma: pydantic-v2
         """Validate data with given type."""
         return TypeAdapter(type_).validate_python(data)
 
-    def type_validate_json(type_: type[T], data: Union[str, bytes]) -> T:
+    def type_validate_json(type_: type[T], data: str | bytes) -> T:
         """Validate JSON with given type."""
         return TypeAdapter(type_).validate_json(data)
 
@@ -286,6 +304,8 @@ else:  # pragma: pydantic-v1
         extra = Extra.allow
         arbitrary_types_allowed = True
 
+    from pydantic.fields import Field as LegacyUnionField
+
     class FieldInfo(BaseFieldInfo):
         def __init__(self, default: Any = PydanticUndefined, **kwargs: Any):
             # preprocess default value to make it compatible with pydantic v2
@@ -294,6 +314,22 @@ else:  # pragma: pydantic-v1
                 default = PydanticUndefined
             super().__init__(default, **kwargs)
 
+        @classmethod
+        def _inherit_construct(
+            cls, field_info: BaseFieldInfo | None = None, **kwargs: Any
+        ):
+            if field_info:
+                init_kwargs = {
+                    s: getattr(field_info, s)
+                    for s in field_info.__slots__
+                    if s != "extra"
+                }
+                init_kwargs.update(field_info.extra)
+            else:
+                init_kwargs = {}
+            init_kwargs.update(kwargs)
+            return cls(**init_kwargs)
+
     class ModelField(BaseModelField):
         @classmethod
         def _construct(cls, name: str, annotation: Any, field_info: FieldInfo) -> Self:
@@ -313,7 +349,7 @@ else:  # pragma: pydantic-v1
 
         @classmethod
         def construct(
-            cls, name: str, annotation: Any, field_info: Optional[FieldInfo] = None
+            cls, name: str, annotation: Any, field_info: FieldInfo | None = None
         ) -> Self:
             """Construct a ModelField from given infos.
 
@@ -338,7 +374,7 @@ else:  # pragma: pydantic-v1
             self,
             type: type[T],
             *,
-            config: Optional[ConfigDict] = ...,
+            config: ConfigDict | None = ...,
         ) -> None: ...
 
         @overload
@@ -346,14 +382,14 @@ else:  # pragma: pydantic-v1
             self,
             type: Any,
             *,
-            config: Optional[ConfigDict] = ...,
+            config: ConfigDict | None = ...,
         ) -> None: ...
 
         def __init__(
             self,
             type: Any,
             *,
-            config: Optional[ConfigDict] = None,
+            config: ConfigDict | None = None,
         ) -> None:
             self.type = type
             self.config = config
@@ -361,25 +397,16 @@ else:  # pragma: pydantic-v1
         def validate_python(self, value: Any) -> T:
             return type_validate_python(self.type, value)
 
-        def validate_json(self, value: Union[str, bytes]) -> T:
+        def validate_json(self, value: str | bytes) -> T:
             return type_validate_json(self.type, value)
 
-    def extract_field_info(field_info: BaseFieldInfo) -> dict[str, Any]:
-        """Get FieldInfo init kwargs from a FieldInfo instance."""
-
-        kwargs = {
-            s: getattr(field_info, s) for s in field_info.__slots__ if s != "extra"
-        }
-        kwargs.update(field_info.extra)
-        return kwargs
-
     @overload
     def field_validator(
         field: str,
         /,
         *fields: str,
         mode: Literal["before"],
-        check_fields: Optional[bool] = None,
+        check_fields: bool | None = None,
     ): ...
 
     @overload
@@ -388,7 +415,7 @@ else:  # pragma: pydantic-v1
         /,
         *fields: str,
         mode: Literal["after"] = ...,
-        check_fields: Optional[bool] = None,
+        check_fields: bool | None = None,
     ): ...
 
     def field_validator(
@@ -396,7 +423,7 @@ else:  # pragma: pydantic-v1
         /,
         *fields: str,
         mode: Literal["before", "after"] = "after",
-        check_fields: Optional[bool] = None,
+        check_fields: bool | None = None,
     ):
         if mode == "before":
             return validator(
@@ -419,9 +446,7 @@ else:  # pragma: pydantic-v1
             ModelField._construct(
                 name=model_field.name,
                 annotation=model_field.annotation,
-                field_info=FieldInfo(
+                field_info=FieldInfo._inherit_construct(model_field.field_info),
-                    **extract_field_info(model_field.field_info),
-                ),
             )
             for model_field in model.__fields__.values()
         ]
@@ -432,8 +457,8 @@ else:  # pragma: pydantic-v1
 
     def model_dump(
         model: BaseModel,
-        include: Optional[set[str]] = None,
+        include: set[str] | None = None,
-        exclude: Optional[set[str]] = None,
+        exclude: set[str] | None = None,
         by_alias: bool = False,
         exclude_unset: bool = False,
         exclude_defaults: bool = False,
@@ -464,7 +489,7 @@ else:  # pragma: pydantic-v1
         """Validate data with given type."""
         return parse_obj_as(type_, data)
 
-    def type_validate_json(type_: type[T], data: Union[str, bytes]) -> T:
+    def type_validate_json(type_: type[T], data: str | bytes) -> T:
         """Validate JSON with given type."""
         return parse_raw_as(type_, data)
 

nonebot/config.py

@@ -20,8 +20,7 @@ from ipaddress import IPv4Address
 import json
 import os
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Optional, Union
+from typing import TYPE_CHECKING, Any, TypeAlias, get_args, get_origin
-from typing_extensions import TypeAlias, get_args, get_origin
 
 from dotenv import dotenv_values
 from pydantic import BaseModel, Field
@@ -30,6 +29,7 @@ from pydantic.networks import IPvAnyAddress
 from nonebot.compat import (
     PYDANTIC_V2,
     ConfigDict,
+    LegacyUnionField,
     ModelField,
     PydanticUndefined,
     PydanticUndefinedType,
@@ -40,9 +40,7 @@ from nonebot.log import logger
 from nonebot.typing import origin_is_union
 from nonebot.utils import deep_update, lenient_issubclass, type_is_complex
 
-DOTENV_TYPE: TypeAlias = Union[
+DOTENV_TYPE: TypeAlias = Path | str | list[Path | str] | tuple[Path | str, ...]
-    Path, str, list[Union[Path, str]], tuple[Union[Path, str], ...]
-]
 
 ENV_FILE_SENTINEL = Path("")
 
@@ -51,7 +49,7 @@ class SettingsError(ValueError): ...
 
 
 class BaseSettingsSource(abc.ABC):
-    def __init__(self, settings_cls: type["BaseSettings"]) -> None:
+    def __init__(self, settings_cls: type[BaseModel]) -> None:
         self.settings_cls = settings_cls
 
     @property
@@ -67,7 +65,7 @@ class InitSettingsSource(BaseSettingsSource):
     __slots__ = ("init_kwargs",)
 
     def __init__(
-        self, settings_cls: type["BaseSettings"], init_kwargs: dict[str, Any]
+        self, settings_cls: type[BaseModel], init_kwargs: dict[str, Any]
     ) -> None:
         self.init_kwargs = init_kwargs
         super().__init__(settings_cls)
@@ -82,33 +80,17 @@ class InitSettingsSource(BaseSettingsSource):
 class DotEnvSettingsSource(BaseSettingsSource):
     def __init__(
         self,
-        settings_cls: type["BaseSettings"],
+        settings_cls: type[BaseModel],
-        env_file: Optional[DOTENV_TYPE] = ENV_FILE_SENTINEL,
+        env_file: DOTENV_TYPE | None,
-        env_file_encoding: Optional[str] = None,
+        env_file_encoding: str,
-        case_sensitive: Optional[bool] = None,
+        case_sensitive: bool | None = False,
-        env_nested_delimiter: Optional[str] = None,
+        env_nested_delimiter: str | None = None,
     ) -> None:
         super().__init__(settings_cls)
-        self.env_file = (
+        self.env_file = env_file
-            env_file
+        self.env_file_encoding = env_file_encoding
-            if env_file is not ENV_FILE_SENTINEL
+        self.case_sensitive = case_sensitive
-            else self.config.get("env_file", (".env",))
+        self.env_nested_delimiter = env_nested_delimiter
-        )
-        self.env_file_encoding = (
-            env_file_encoding
-            if env_file_encoding is not None
-            else self.config.get("env_file_encoding", "utf-8")
-        )
-        self.case_sensitive = (
-            case_sensitive
-            if case_sensitive is not None
-            else self.config.get("case_sensitive", False)
-        )
-        self.env_nested_delimiter = (
-            env_nested_delimiter
-            if env_nested_delimiter is not None
-            else self.config.get("env_nested_delimiter", None)
-        )
 
     def _apply_case_sensitive(self, var_name: str) -> str:
         return var_name if self.case_sensitive else var_name.lower()
@@ -123,17 +105,17 @@ class DotEnvSettingsSource(BaseSettingsSource):
         return False, False
 
     def _parse_env_vars(
-        self, env_vars: Mapping[str, Optional[str]]
+        self, env_vars: Mapping[str, str | None]
-    ) -> dict[str, Optional[str]]:
+    ) -> dict[str, str | None]:
         return {
             self._apply_case_sensitive(key): value for key, value in env_vars.items()
         }
 
-    def _read_env_file(self, file_path: Path) -> dict[str, Optional[str]]:
+    def _read_env_file(self, file_path: Path) -> dict[str, str | None]:
         file_vars = dotenv_values(file_path, encoding=self.env_file_encoding)
         return self._parse_env_vars(file_vars)
 
-    def _read_env_files(self) -> dict[str, Optional[str]]:
+    def _read_env_files(self) -> dict[str, str | None]:
         env_files = self.env_file
         if env_files is None:
             return {}
@@ -141,16 +123,14 @@ class DotEnvSettingsSource(BaseSettingsSource):
         if isinstance(env_files, (str, os.PathLike)):
             env_files = [env_files]
 
-        dotenv_vars: dict[str, Optional[str]] = {}
+        dotenv_vars: dict[str, str | None] = {}
         for env_file in env_files:
             env_path = Path(env_file).expanduser()
             if env_path.is_file():
                 dotenv_vars.update(self._read_env_file(env_path))
         return dotenv_vars
 
-    def _next_field(
+    def _next_field(self, field: ModelField | None, key: str) -> ModelField | None:
-        self, field: Optional[ModelField], key: str
-    ) -> Optional[ModelField]:
         if not field or origin_is_union(get_origin(field.annotation)):
             return None
         elif field.annotation and lenient_issubclass(field.annotation, BaseModel):
@@ -162,8 +142,8 @@ class DotEnvSettingsSource(BaseSettingsSource):
     def _explode_env_vars(
         self,
         field: ModelField,
-        env_vars: dict[str, Optional[str]],
+        env_vars: dict[str, str | None],
-        env_file_vars: dict[str, Optional[str]],
+        env_file_vars: dict[str, str | None],
     ) -> dict[str, Any]:
         if self.env_nested_delimiter is None:
             return {}
@@ -179,7 +159,7 @@ class DotEnvSettingsSource(BaseSettingsSource):
 
             _, *keys, last_key = env_name.split(self.env_nested_delimiter)
             env_var = result
-            target_field: Optional[ModelField] = field
+            target_field: ModelField | None = field
             for key in keys:
                 target_field = self._next_field(target_field, key)
                 env_var = env_var.setdefault(key, {})
@@ -212,12 +192,33 @@ class DotEnvSettingsSource(BaseSettingsSource):
         for field in model_fields(self.settings_cls):
             field_name = field.name
             env_name = self._apply_case_sensitive(field_name)
+            alias_name = field.field_info.alias
+            alias_env_name = (
+                None if alias_name is None else self._apply_case_sensitive(alias_name)
+            )
+
+            # pydantic use alias name to validate if exist
+            if alias_name is not None:
+                field_name = alias_name
 
             # try get values from env vars
             env_val = env_vars.get(env_name, PydanticUndefined)
+            alias_env_val = (
+                PydanticUndefined
+                if alias_env_name is None
+                else env_vars.get(alias_env_name, PydanticUndefined)
+            )
+            # alias env value has higher priority
+            env_val = (
+                env_val
+                if isinstance(alias_env_val, PydanticUndefinedType)
+                else alias_env_val
+            )
             # delete from file vars when used
             if env_name in env_file_vars:
                 del env_file_vars[env_name]
+            if alias_env_name is not None and alias_env_name in env_file_vars:
+                del env_file_vars[alias_env_name]
 
             is_complex, allow_parse_failure = self._field_is_complex(field)
             if is_complex:
@@ -287,18 +288,18 @@ class DotEnvSettingsSource(BaseSettingsSource):
 if PYDANTIC_V2:  # pragma: pydantic-v2
 
     class SettingsConfig(ConfigDict, total=False):
-        env_file: Optional[DOTENV_TYPE]
+        env_file: DOTENV_TYPE | None
         env_file_encoding: str
         case_sensitive: bool
-        env_nested_delimiter: Optional[str]
+        env_nested_delimiter: str | None
 
 else:  # pragma: pydantic-v1
 
     class SettingsConfig(ConfigDict):
-        env_file: Optional[DOTENV_TYPE]
+        env_file: DOTENV_TYPE | None
         env_file_encoding: str
         case_sensitive: bool
-        env_nested_delimiter: Optional[str]
+        env_nested_delimiter: str | None
 
 
 class BaseSettings(BaseModel):
@@ -326,30 +327,53 @@ class BaseSettings(BaseModel):
 
     def __init__(
         __settings_self__,  # pyright: ignore[reportSelfClsParameterName]
-        _env_file: Optional[DOTENV_TYPE] = ENV_FILE_SENTINEL,
+        _env_file: DOTENV_TYPE | None = ENV_FILE_SENTINEL,
-        _env_file_encoding: Optional[str] = None,
+        _env_file_encoding: str | None = None,
-        _env_nested_delimiter: Optional[str] = None,
+        _env_nested_delimiter: str | None = None,
         **values: Any,
     ) -> None:
+        settings_config = model_config(__settings_self__.__class__)
+        env_file = (
+            _env_file
+            if _env_file is not ENV_FILE_SENTINEL
+            else settings_config.get("env_file", (".env",))
+        )
+        env_file_encoding = (
+            _env_file_encoding
+            if _env_file_encoding is not None
+            else settings_config.get("env_file_encoding", "utf-8")
+        )
+        env_nested_delimiter = (
+            _env_nested_delimiter
+            if _env_nested_delimiter is not None
+            else settings_config.get("env_nested_delimiter", None)
+        )
+
         super().__init__(
             **__settings_self__._settings_build_values(
+                __settings_self__.__class__,
                 values,
-                env_file=_env_file,
+                env_file=env_file,
-                env_file_encoding=_env_file_encoding,
+                env_file_encoding=env_file_encoding,
-                env_nested_delimiter=_env_nested_delimiter,
+                env_nested_delimiter=env_nested_delimiter,
             )
         )
 
+        __settings_self__._env_file = env_file
+        __settings_self__._env_file_encoding = env_file_encoding
+        __settings_self__._env_nested_delimiter = env_nested_delimiter
+
+    @staticmethod
     def _settings_build_values(
-        self,
+        settings_cls: type[BaseModel],
         init_kwargs: dict[str, Any],
-        env_file: Optional[DOTENV_TYPE] = None,
+        env_file: DOTENV_TYPE | None,
-        env_file_encoding: Optional[str] = None,
+        env_file_encoding: str,
-        env_nested_delimiter: Optional[str] = None,
+        env_nested_delimiter: str | None,
     ) -> dict[str, Any]:
-        init_settings = InitSettingsSource(self.__class__, init_kwargs=init_kwargs)
+        init_settings = InitSettingsSource(settings_cls, init_kwargs=init_kwargs)
         env_settings = DotEnvSettingsSource(
-            self.__class__,
+            settings_cls,
             env_file=env_file,
             env_file_encoding=env_file_encoding,
             env_nested_delimiter=env_nested_delimiter,
@@ -380,7 +404,7 @@ class Config(BaseSettings):
     """
 
     if TYPE_CHECKING:
-        _env_file: Optional[DOTENV_TYPE] = ".env", ".env.prod"
+        _env_file: DOTENV_TYPE | None = ".env", ".env.prod"
 
     # nonebot configs
     driver: str = "~fastapi"
@@ -396,7 +420,7 @@ class Config(BaseSettings):
     """NoneBot {ref}`nonebot.drivers.ReverseDriver` 服务端监听的 IP/主机名。"""
     port: int = Field(default=8080, ge=1, le=65535)
     """NoneBot {ref}`nonebot.drivers.ReverseDriver` 服务端监听的端口。"""
-    log_level: Union[int, str] = "INFO"
+    log_level: int | str = LegacyUnionField(default="INFO")
     """NoneBot 日志输出等级，可以为 `int` 类型等级或等级名称。
 
     参考 [记录日志](https://nonebot.dev/docs/appendices/log)，[loguru 日志等级](https://loguru.readthedocs.io/en/stable/api/logger.html#levels)。
@@ -413,7 +437,7 @@ class Config(BaseSettings):
     """
 
     # bot connection configs
-    api_timeout: Optional[float] = 30.0
+    api_timeout: float | None = 30.0
     """API 请求超时时间，单位: 秒。"""
 
     # bot runtime configs

nonebot/dependencies/__init__.py

@@ -8,11 +8,11 @@ FrontMatter:
 """
 
 import abc
-from collections.abc import Awaitable, Iterable
+from collections.abc import Awaitable, Callable, Iterable
 from dataclasses import dataclass, field
 from functools import partial
 import inspect
-from typing import Any, Callable, Generic, Optional, TypeVar, cast
+from typing import Any, Generic, TypeVar, cast
 
 import anyio
 from exceptiongroup import BaseExceptionGroup, catch
@@ -47,13 +47,13 @@ class Param(abc.ABC, FieldInfo):
     @classmethod
     def _check_param(
         cls, param: inspect.Parameter, allow_types: tuple[type["Param"], ...]
-    ) -> Optional["Param"]:
+    ) -> "Param | None":
         return
 
     @classmethod
     def _check_parameterless(
         cls, value: Any, allow_types: tuple[type["Param"], ...]
-    ) -> Optional["Param"]:
+    ) -> "Param | None":
         return
 
     @abc.abstractmethod
@@ -92,7 +92,7 @@ class Dependent(Generic[R]):
         )
 
     async def __call__(self, **kwargs: Any) -> R:
-        exception: Optional[BaseExceptionGroup[SkippedException]] = None
+        exception: BaseExceptionGroup[SkippedException] | None = None
 
         def _handle_skipped(exc_group: BaseExceptionGroup[SkippedException]):
             nonlocal exception
@@ -167,7 +167,7 @@ class Dependent(Generic[R]):
         cls,
         *,
         call: _DependentCallable[R],
-        parameterless: Optional[Iterable[Any]] = None,
+        parameterless: Iterable[Any] | None = None,
         allow_types: Iterable[type[Param]],
     ) -> "Dependent[R]":
         allow_types = tuple(allow_types)

nonebot/dependencies/utils.py

@@ -6,8 +6,9 @@ FrontMatter:
     description: nonebot.dependencies.utils 模块
 """
 
+from collections.abc import Callable
 import inspect
-from typing import Any, Callable, ForwardRef, cast
+from typing import Any, ForwardRef, cast
 from typing_extensions import TypeAliasType
 
 from loguru import logger

nonebot/drivers/aiohttp.py

@@ -19,7 +19,7 @@ FrontMatter:
 
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
-from typing import TYPE_CHECKING, Optional, Union
+from typing import TYPE_CHECKING
 from typing_extensions import override
 
 from multidict import CIMultiDict
@@ -62,11 +62,11 @@ class Session(HTTPClientSession):
         params: QueryTypes = None,
         headers: HeaderTypes = None,
         cookies: CookieTypes = None,
-        version: Union[str, HTTPVersion] = HTTPVersion.H11,
+        version: str | HTTPVersion = HTTPVersion.H11,
         timeout: TimeoutTypes = None,
-        proxy: Optional[str] = None,
+        proxy: str | None = None,
     ):
-        self._client: Optional[aiohttp.ClientSession] = None
+        self._client: aiohttp.ClientSession | None = None
 
         self._params = URL.build(query=params).query if params is not None else None
 
@@ -279,9 +279,9 @@ class Mixin(HTTPClientMixin, WebSocketClientMixin):
         params: QueryTypes = None,
         headers: HeaderTypes = None,
         cookies: CookieTypes = None,
-        version: Union[str, HTTPVersion] = HTTPVersion.H11,
+        version: str | HTTPVersion = HTTPVersion.H11,
         timeout: TimeoutTypes = None,
-        proxy: Optional[str] = None,
+        proxy: str | None = None,
     ) -> Session:
         return Session(
             params=params,
@@ -323,7 +323,11 @@ class WebSocket(BaseWebSocket):
 
     async def _receive(self) -> aiohttp.WSMessage:
         msg = await self.websocket.receive()
-        if msg.type in (aiohttp.WSMsgType.CLOSE, aiohttp.WSMsgType.CLOSING):
+        if msg.type in (
+            aiohttp.WSMsgType.CLOSE,
+            aiohttp.WSMsgType.CLOSING,
+            aiohttp.WSMsgType.CLOSED,
+        ):
             raise WebSocketClosed(self.websocket.close_code or 1006)
         return msg
 

nonebot/drivers/fastapi.py

@@ -20,7 +20,7 @@ FrontMatter:
 import contextlib
 from functools import wraps
 import logging
-from typing import Any, Optional, Union
+from typing import Any
 from typing_extensions import override
 
 from pydantic import BaseModel
@@ -63,23 +63,23 @@ def catch_closed(func):
 class Config(BaseModel):
     """FastAPI 驱动框架设置，详情参考 FastAPI 文档"""
 
-    fastapi_openapi_url: Optional[str] = None
+    fastapi_openapi_url: str | None = None
     """`openapi.json` 地址，默认为 `None` 即关闭"""
-    fastapi_docs_url: Optional[str] = None
+    fastapi_docs_url: str | None = None
     """`swagger` 地址，默认为 `None` 即关闭"""
-    fastapi_redoc_url: Optional[str] = None
+    fastapi_redoc_url: str | None = None
     """`redoc` 地址，默认为 `None` 即关闭"""
     fastapi_include_adapter_schema: bool = True
     """是否包含适配器路由的 schema，默认为 `True`"""
     fastapi_reload: bool = False
     """开启/关闭冷重载"""
-    fastapi_reload_dirs: Optional[list[str]] = None
+    fastapi_reload_dirs: list[str] | None = None
     """重载监控文件夹列表，默认为 uvicorn 默认值"""
     fastapi_reload_delay: float = 0.25
     """重载延迟，默认为 uvicorn 默认值"""
-    fastapi_reload_includes: Optional[list[str]] = None
+    fastapi_reload_includes: list[str] | None = None
     """要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值"""
-    fastapi_reload_excludes: Optional[list[str]] = None
+    fastapi_reload_excludes: list[str] | None = None
     """不要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值"""
     fastapi_extra: dict[str, Any] = {}
     """传递给 `FastAPI` 的其他参数。"""
@@ -160,10 +160,10 @@ class Driver(BaseDriver, ASGIMixin):
     @override
     def run(
         self,
-        host: Optional[str] = None,
+        host: str | None = None,
-        port: Optional[int] = None,
+        port: int | None = None,
         *args,
-        app: Optional[str] = None,
+        app: str | None = None,
         **kwargs,
     ):
         """使用 `uvicorn` 启动 FastAPI"""
@@ -206,8 +206,8 @@ class Driver(BaseDriver, ASGIMixin):
         with contextlib.suppress(Exception):
             json = await request.json()
 
-        data: Optional[dict] = None
+        data: dict | None = None
-        files: Optional[list[tuple[str, FileTypes]]] = None
+        files: list[tuple[str, FileTypes]] | None = None
         with contextlib.suppress(Exception):
             form = await request.form()
             data = {}
@@ -280,7 +280,7 @@ class FastAPIWebSocket(BaseWebSocket):
         await self.websocket.close(code, reason)
 
     @override
-    async def receive(self) -> Union[str, bytes]:
+    async def receive(self) -> str | bytes:
         # assert self.websocket.application_state == WebSocketState.CONNECTED
         msg = await self.websocket.receive()
         if msg["type"] == "websocket.disconnect":

nonebot/drivers/httpx.py

@@ -18,7 +18,7 @@ FrontMatter:
 """
 
 from collections.abc import AsyncGenerator
-from typing import TYPE_CHECKING, Optional, Union
+from typing import TYPE_CHECKING
 from typing_extensions import override
 
 from multidict import CIMultiDict
@@ -58,11 +58,11 @@ class Session(HTTPClientSession):
         params: QueryTypes = None,
         headers: HeaderTypes = None,
         cookies: CookieTypes = None,
-        version: Union[str, HTTPVersion] = HTTPVersion.H11,
+        version: str | HTTPVersion = HTTPVersion.H11,
         timeout: TimeoutTypes = None,
-        proxy: Optional[str] = None,
+        proxy: str | None = None,
     ):
-        self._client: Optional[httpx.AsyncClient] = None
+        self._client: httpx.AsyncClient | None = None
 
         self._params = (
             tuple(URL.build(query=params).query.items()) if params is not None else None
@@ -216,9 +216,9 @@ class Mixin(HTTPClientMixin):
         params: QueryTypes = None,
         headers: HeaderTypes = None,
         cookies: CookieTypes = None,
-        version: Union[str, HTTPVersion] = HTTPVersion.H11,
+        version: str | HTTPVersion = HTTPVersion.H11,
         timeout: TimeoutTypes = None,
-        proxy: Optional[str] = None,
+        proxy: str | None = None,
     ) -> Session:
         return Session(
             params=params,

nonebot/drivers/none.py

@@ -12,7 +12,6 @@ FrontMatter:
 """
 
 import signal
-from typing import Optional
 from typing_extensions import override
 
 import anyio
@@ -112,7 +111,7 @@ class Driver(BaseDriver):
         if not self.should_exit.is_set():
             logger.info("Application startup completed.")
 
-    async def _listen_exit(self, tg: Optional[TaskGroup] = None):
+    async def _listen_exit(self, tg: TaskGroup | None = None):
         await self.should_exit.wait()
 
         if tg is not None:

nonebot/drivers/quart.py

@@ -19,7 +19,7 @@ FrontMatter:
 
 import asyncio
 from functools import wraps
-from typing import Any, Optional, Union, cast
+from typing import Any, cast
 from typing_extensions import override
 
 from pydantic import BaseModel
@@ -65,13 +65,13 @@ class Config(BaseModel):
 
     quart_reload: bool = False
     """开启/关闭冷重载"""
-    quart_reload_dirs: Optional[list[str]] = None
+    quart_reload_dirs: list[str] | None = None
     """重载监控文件夹列表，默认为 uvicorn 默认值"""
     quart_reload_delay: float = 0.25
     """重载延迟，默认为 uvicorn 默认值"""
-    quart_reload_includes: Optional[list[str]] = None
+    quart_reload_includes: list[str] | None = None
     """要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值"""
-    quart_reload_excludes: Optional[list[str]] = None
+    quart_reload_excludes: list[str] | None = None
     """不要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值"""
     quart_extra: dict[str, Any] = {}
     """传递给 `Quart` 的其他参数。"""
@@ -141,10 +141,10 @@ class Driver(BaseDriver, ASGIMixin):
     @override
     def run(
         self,
-        host: Optional[str] = None,
+        host: str | None = None,
-        port: Optional[int] = None,
+        port: int | None = None,
         *args,
-        app: Optional[str] = None,
+        app: str | None = None,
         **kwargs,
     ):
         """使用 `uvicorn` 启动 Quart"""
@@ -257,7 +257,7 @@ class WebSocket(BaseWebSocket):
 
     @override
     @catch_closed
-    async def receive(self) -> Union[str, bytes]:
+    async def receive(self) -> str | bytes:
         return await self.websocket.receive()
 
     @override

nonebot/drivers/websockets.py

@@ -17,12 +17,12 @@ FrontMatter:
     description: nonebot.drivers.websockets 模块
 """
 
-from collections.abc import AsyncGenerator
+from collections.abc import AsyncGenerator, Callable
 from contextlib import asynccontextmanager
 from functools import wraps
 import logging
 from types import CoroutineType
-from typing import TYPE_CHECKING, Any, Callable, TypeVar, Union
+from typing import TYPE_CHECKING, Any, TypeVar
 from typing_extensions import ParamSpec, override
 
 from nonebot.drivers import Request, Timeout, WebSocketClientMixin, combine_driver
@@ -108,7 +108,7 @@ class WebSocket(BaseWebSocket):
 
     @override
     @catch_closed
-    async def receive(self) -> Union[str, bytes]:
+    async def receive(self) -> str | bytes:
         return await self.websocket.recv()
 
     @override

nonebot/exception.py

@@ -31,7 +31,7 @@ FrontMatter:
     description: nonebot.exception 模块
 """
 
-from typing import Any, Optional
+from typing import Any
 
 from nonebot.compat import ModelField
 
@@ -47,7 +47,7 @@ class NoneBotException(Exception):
 class ParserExit(NoneBotException):
     """{ref}`nonebot.rule.shell_command` 处理消息失败时返回的异常。"""
 
-    def __init__(self, status: int = 0, message: Optional[str] = None) -> None:
+    def __init__(self, status: int = 0, message: str | None = None) -> None:
         self.status = status
         self.message = message
 
@@ -232,7 +232,7 @@ class DriverException(NoneBotException):
 class WebSocketClosed(DriverException):
     """WebSocket 连接已关闭。"""
 
-    def __init__(self, code: int, reason: Optional[str] = None) -> None:
+    def __init__(self, code: int, reason: str | None = None) -> None:
         self.code = code
         self.reason = reason
 

nonebot/internal/adapter/bot.py

@@ -1,6 +1,6 @@
 import abc
 from functools import partial
-from typing import TYPE_CHECKING, Any, ClassVar, Optional, Protocol, Union
+from typing import TYPE_CHECKING, Any, ClassVar, Protocol
 
 import anyio
 from exceptiongroup import BaseExceptionGroup, catch
@@ -77,7 +77,7 @@ class Bot(abc.ABC):
 
         result: Any = None
         skip_calling_api: bool = False
-        exception: Optional[Exception] = None
+        exception: Exception | None = None
 
         if self._calling_api_hook:
             logger.debug("Running CallingAPI hooks...")
@@ -180,7 +180,7 @@ class Bot(abc.ABC):
     async def send(
         self,
         event: "Event",
-        message: Union[str, "Message", "MessageSegment"],
+        message: "str | Message | MessageSegment",
         **kwargs: Any,
     ) -> Any:
         """调用机器人基础发送消息接口

nonebot/internal/adapter/message.py

@@ -5,11 +5,9 @@ from dataclasses import asdict, dataclass, field
 from typing import (  # noqa: UP035
     Any,
     Generic,
-    Optional,
     SupportsIndex,
     Type,
     TypeVar,
-    Union,
     overload,
 )
 from typing_extensions import Self
@@ -51,10 +49,10 @@ class MessageSegment(abc.ABC, Generic[TM]):
     ) -> bool:
         return not self == other
 
-    def __add__(self, other: Union[str, Self, Iterable[Self]]) -> TM:
+    def __add__(self, other: str | Self | Iterable[Self]) -> TM:
         return self.get_message_class()(self) + other
 
-    def __radd__(self, other: Union[str, Self, Iterable[Self]]) -> TM:
+    def __radd__(self, other: str | Self | Iterable[Self]) -> TM:
         return self.get_message_class()(other) + self
 
     @classmethod
@@ -87,7 +85,7 @@ class MessageSegment(abc.ABC, Generic[TM]):
     def items(self):
         return asdict(self).items()
 
-    def join(self, iterable: Iterable[Union[Self, TM]]) -> TM:
+    def join(self, iterable: Iterable[Self | TM]) -> TM:
         return self.get_message_class()(self).join(iterable)
 
     def copy(self) -> Self:
@@ -109,7 +107,7 @@ class Message(list[TMS], abc.ABC):
 
     def __init__(
         self,
-        message: Union[str, None, Iterable[TMS], TMS] = None,
+        message: str | None | Iterable[TMS] | TMS = None,
     ):
         super().__init__()
         if message is None:
@@ -124,7 +122,7 @@ class Message(list[TMS], abc.ABC):
             self.extend(self._construct(message))  # pragma: no cover
 
     @classmethod
-    def template(cls, format_string: Union[str, TM]) -> MessageTemplate[Self]:
+    def template(cls, format_string: str | TM) -> MessageTemplate[Self]:
         """创建消息模板。
 
         用法和 `str.format` 大致相同，支持以 `Message` 对象作为消息模板并输出消息对象。
@@ -177,17 +175,17 @@ class Message(list[TMS], abc.ABC):
         raise NotImplementedError
 
     def __add__(  # pyright: ignore[reportIncompatibleMethodOverride]
-        self, other: Union[str, TMS, Iterable[TMS]]
+        self, other: str | TMS | Iterable[TMS]
     ) -> Self:
         result = self.copy()
         result += other
         return result
 
-    def __radd__(self, other: Union[str, TMS, Iterable[TMS]]) -> Self:
+    def __radd__(self, other: str | TMS | Iterable[TMS]) -> Self:
         result = self.__class__(other)
         return result + self
 
-    def __iadd__(self, other: Union[str, TMS, Iterable[TMS]]) -> Self:
+    def __iadd__(self, other: str | TMS | Iterable[TMS]) -> Self:
         if isinstance(other, str):
             self.extend(self._construct(other))
         elif isinstance(other, MessageSegment):
@@ -255,14 +253,8 @@ class Message(list[TMS], abc.ABC):
 
     def __getitem__(  # pyright: ignore[reportIncompatibleMethodOverride]
         self,
-        args: Union[
+        args: str | tuple[str, int] | tuple[str, slice] | int | slice,
-            str,
+    ) -> TMS | Self:
-            tuple[str, int],
-            tuple[str, slice],
-            int,
-            slice,
-        ],
-    ) -> Union[TMS, Self]:
         arg1, arg2 = args if isinstance(args, tuple) else (args, None)
         if isinstance(arg1, int) and arg2 is None:
             return super().__getitem__(arg1)
@@ -278,7 +270,7 @@ class Message(list[TMS], abc.ABC):
             raise ValueError("Incorrect arguments to slice")  # pragma: no cover
 
     def __contains__(  # pyright: ignore[reportIncompatibleMethodOverride]
-        self, value: Union[TMS, str]
+        self, value: TMS | str
     ) -> bool:
         """检查消息段是否存在
 
@@ -291,11 +283,11 @@ class Message(list[TMS], abc.ABC):
             return next((seg for seg in self if seg.type == value), None) is not None
         return super().__contains__(value)
 
-    def has(self, value: Union[TMS, str]) -> bool:
+    def has(self, value: TMS | str) -> bool:
         """与 {ref}``__contains__` <nonebot.adapters.Message.__contains__>` 相同"""
         return value in self
 
-    def index(self, value: Union[TMS, str], *args: SupportsIndex) -> int:
+    def index(self, value: TMS | str, *args: SupportsIndex) -> int:
         """索引消息段
 
         参数:
@@ -315,7 +307,7 @@ class Message(list[TMS], abc.ABC):
             return super().index(first_segment, *args)
         return super().index(value, *args)
 
-    def get(self, type_: str, count: Optional[int] = None) -> Self:
+    def get(self, type_: str, count: int | None = None) -> Self:
         """获取指定类型的消息段
 
         参数:
@@ -339,7 +331,7 @@ class Message(list[TMS], abc.ABC):
             filtered.append(seg)
         return filtered
 
-    def count(self, value: Union[TMS, str]) -> int:
+    def count(self, value: TMS | str) -> int:
         """计算指定消息段的个数
 
         参数:
@@ -350,7 +342,7 @@ class Message(list[TMS], abc.ABC):
         """
         return len(self[value]) if isinstance(value, str) else super().count(value)
 
-    def only(self, value: Union[TMS, str]) -> bool:
+    def only(self, value: TMS | str) -> bool:
         """检查消息中是否仅包含指定消息段
 
         参数:
@@ -364,7 +356,7 @@ class Message(list[TMS], abc.ABC):
         return all(seg == value for seg in self)
 
     def append(  # pyright: ignore[reportIncompatibleMethodOverride]
-        self, obj: Union[str, TMS]
+        self, obj: str | TMS
     ) -> Self:
         """添加一个消息段到消息数组末尾。
 
@@ -380,7 +372,7 @@ class Message(list[TMS], abc.ABC):
         return self
 
     def extend(  # pyright: ignore[reportIncompatibleMethodOverride]
-        self, obj: Union[Self, Iterable[TMS]]
+        self, obj: Self | Iterable[TMS]
     ) -> Self:
         """拼接一个消息数组或多个消息段到消息数组末尾。
 
@@ -391,7 +383,7 @@ class Message(list[TMS], abc.ABC):
             self.append(segment)
         return self
 
-    def join(self, iterable: Iterable[Union[TMS, Self]]) -> Self:
+    def join(self, iterable: Iterable[TMS | Self]) -> Self:
         """将多个消息连接并将自身作为分割
 
         参数:

nonebot/internal/adapter/template.py

@@ -1,19 +1,16 @@
 from _string import formatter_field_name_split  # type: ignore
-from collections.abc import Mapping, Sequence
+from collections.abc import Callable, Mapping, Sequence
 import functools
 from string import Formatter
 from typing import (
     TYPE_CHECKING,
     Any,
-    Callable,
     Generic,
-    Optional,
+    TypeAlias,
     TypeVar,
-    Union,
     cast,
     overload,
 )
-from typing_extensions import TypeAlias
 
 if TYPE_CHECKING:
     from .message import Message, MessageSegment
@@ -50,15 +47,15 @@ class MessageTemplate(Formatter, Generic[TF]):
     @overload
     def __init__(
         self: "MessageTemplate[TM]",
-        template: Union[str, TM],
+        template: str | TM,
         factory: type[TM],
         private_getattr: bool = False,
     ) -> None: ...
 
     def __init__(
         self,
-        template: Union[str, TM],
+        template: str | TM,
-        factory: Union[type[str], type[TM]] = str,
+        factory: type[str] | type[TM] = str,
         private_getattr: bool = False,
     ) -> None:
         self.template: TF = template  # type: ignore
@@ -70,7 +67,7 @@ class MessageTemplate(Formatter, Generic[TF]):
         return f"MessageTemplate({self.template!r}, factory={self.factory!r})"
 
     def add_format_spec(
-        self, spec: FormatSpecFunc_T, name: Optional[str] = None
+        self, spec: FormatSpecFunc_T, name: str | None = None
     ) -> FormatSpecFunc_T:
         name = name or spec.__name__
         if name in self.format_specs:
@@ -126,7 +123,7 @@ class MessageTemplate(Formatter, Generic[TF]):
         format_string: str,
         args: Sequence[Any],
         kwargs: Mapping[str, Any],
-        used_args: set[Union[int, str]],
+        used_args: set[int | str],
         auto_arg_index: int = 0,
     ) -> tuple[TF, int]:
         results: list[Any] = [self.factory()]
@@ -180,7 +177,7 @@ class MessageTemplate(Formatter, Generic[TF]):
 
     def get_field(
         self, field_name: str, args: Sequence[Any], kwargs: Mapping[str, Any]
-    ) -> tuple[Any, Union[int, str]]:
+    ) -> tuple[Any, int | str]:
         first, rest = formatter_field_name_split(field_name)
         obj = self.get_value(first, args, kwargs)
 
@@ -192,7 +189,7 @@ class MessageTemplate(Formatter, Generic[TF]):
         return obj, first
 
     def format_field(self, value: Any, format_spec: str) -> Any:
-        formatter: Optional[FormatSpecFunc] = self.format_specs.get(format_spec)
+        formatter: FormatSpecFunc | None = self.format_specs.get(format_spec)
         if formatter is None and not issubclass(self.factory, str):
             segment_class: type["MessageSegment"] = self.factory.get_segment_class()
             method = getattr(segment_class, format_spec, None)

nonebot/internal/driver/_lifespan.py

@@ -1,7 +1,6 @@
-from collections.abc import Awaitable, Iterable
+from collections.abc import Awaitable, Callable, Iterable
 from types import TracebackType
-from typing import Any, Callable, Optional, Union, cast
+from typing import Any, TypeAlias, cast
-from typing_extensions import TypeAlias
 
 import anyio
 from anyio.abc import TaskGroup
@@ -11,12 +10,12 @@ from nonebot.utils import is_coroutine_callable, run_sync
 
 SYNC_LIFESPAN_FUNC: TypeAlias = Callable[[], Any]
 ASYNC_LIFESPAN_FUNC: TypeAlias = Callable[[], Awaitable[Any]]
-LIFESPAN_FUNC: TypeAlias = Union[SYNC_LIFESPAN_FUNC, ASYNC_LIFESPAN_FUNC]
+LIFESPAN_FUNC: TypeAlias = SYNC_LIFESPAN_FUNC | ASYNC_LIFESPAN_FUNC
 
 
 class Lifespan:
     def __init__(self) -> None:
-        self._task_group: Optional[TaskGroup] = None
+        self._task_group: TaskGroup | None = None
 
         self._startup_funcs: list[LIFESPAN_FUNC] = []
         self._ready_funcs: list[LIFESPAN_FUNC] = []
@@ -72,9 +71,9 @@ class Lifespan:
     async def shutdown(
         self,
         *,
-        exc_type: Optional[type[BaseException]] = None,
+        exc_type: type[BaseException] | None = None,
-        exc_val: Optional[BaseException] = None,
+        exc_val: BaseException | None = None,
-        exc_tb: Optional[TracebackType] = None,
+        exc_tb: TracebackType | None = None,
     ) -> None:
         if self._shutdown_funcs:
             # reverse shutdown funcs to ensure stack order
@@ -93,8 +92,8 @@ class Lifespan:
 
     async def __aexit__(
         self,
-        exc_type: Optional[type[BaseException]],
+        exc_type: type[BaseException] | None,
-        exc_val: Optional[BaseException],
+        exc_val: BaseException | None,
-        exc_tb: Optional[TracebackType],
+        exc_tb: TracebackType | None,
     ) -> None:
         await self.shutdown(exc_type=exc_type, exc_val=exc_val, exc_tb=exc_tb)

nonebot/internal/driver/abstract.py

@@ -2,8 +2,8 @@ import abc
 from collections.abc import AsyncGenerator
 from contextlib import AsyncExitStack, asynccontextmanager
 from types import TracebackType
-from typing import TYPE_CHECKING, Any, ClassVar, Optional, Union
+from typing import TYPE_CHECKING, Any, ClassVar, TypeAlias
-from typing_extensions import Self, TypeAlias
+from typing_extensions import Self
 
 from anyio import CancelScope, create_task_group
 from anyio.abc import TaskGroup
@@ -245,9 +245,9 @@ class HTTPClientSession(abc.ABC):
         params: QueryTypes = None,
         headers: HeaderTypes = None,
         cookies: CookieTypes = None,
-        version: Union[str, HTTPVersion] = HTTPVersion.H11,
+        version: str | HTTPVersion = HTTPVersion.H11,
         timeout: TimeoutTypes = None,
-        proxy: Optional[str] = None,
+        proxy: str | None = None,
     ):
         raise NotImplementedError
 
@@ -283,9 +283,9 @@ class HTTPClientSession(abc.ABC):
 
     async def __aexit__(
         self,
-        exc_type: Optional[type[BaseException]],
+        exc_type: type[BaseException] | None,
-        exc: Optional[BaseException],
+        exc: BaseException | None,
-        tb: Optional[TracebackType],
+        tb: TracebackType | None,
     ) -> None:
         await self.close()
 
@@ -315,9 +315,9 @@ class HTTPClientMixin(ForwardMixin):
         params: QueryTypes = None,
         headers: HeaderTypes = None,
         cookies: CookieTypes = None,
-        version: Union[str, HTTPVersion] = HTTPVersion.H11,
+        version: str | HTTPVersion = HTTPVersion.H11,
         timeout: TimeoutTypes = None,
-        proxy: Optional[str] = None,
+        proxy: str | None = None,
     ) -> HTTPClientSession:
         """获取一个 HTTP 会话"""
         raise NotImplementedError

nonebot/internal/driver/combine.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING, TypeVar, Union, overload
+from typing import TYPE_CHECKING, TypeVar, overload
 
 from .abstract import Driver, Mixin
 
@@ -21,7 +21,7 @@ def combine_driver(
 
 def combine_driver(
     driver: type[D], *mixins: type[Mixin]
-) -> Union[type[D], type["CombinedDriver"]]:
+) -> type[D] | type["CombinedDriver"]:
     """将一个驱动器和多个混入类合并。"""
     # check first
     if not issubclass(driver, Driver):

nonebot/internal/driver/model.py

@@ -1,48 +1,51 @@
 import abc
-from collections.abc import Awaitable, Iterator, Mapping, MutableMapping
+from collections.abc import Awaitable, Callable, Iterator, Mapping, MutableMapping
 from dataclasses import dataclass
 from enum import Enum
 from http.cookiejar import Cookie, CookieJar
-from typing import IO, Any, Callable, Optional, Union
+from typing import IO, Any, TypeAlias
-from typing_extensions import TypeAlias
 import urllib.request
 
 from multidict import CIMultiDict
 from yarl import URL as URL
 
-RawURL: TypeAlias = tuple[bytes, bytes, Optional[int], bytes]
 
-SimpleQuery: TypeAlias = Union[str, int, float]
+@dataclass
-QueryVariable: TypeAlias = Union[SimpleQuery, list[SimpleQuery]]
+class Timeout:
-QueryTypes: TypeAlias = Union[
+    """Request 超时配置。"""
-    None, str, Mapping[str, QueryVariable], list[tuple[str, SimpleQuery]]
-]
 
-HeaderTypes: TypeAlias = Union[
+    total: float | None = None
-    None,
+    connect: float | None = None
-    CIMultiDict[str],
+    read: float | None = None
-    dict[str, str],
-    list[tuple[str, str]],
-]
 
-CookieTypes: TypeAlias = Union[
-    None, "Cookies", CookieJar, dict[str, str], list[tuple[str, str]]
-]
 
-ContentTypes: TypeAlias = Union[str, bytes, None]
+RawURL: TypeAlias = tuple[bytes, bytes, int | None, bytes]
-DataTypes: TypeAlias = Union[dict, None]
+
-FileContent: TypeAlias = Union[IO[bytes], bytes]
+SimpleQuery: TypeAlias = str | int | float
-FileType: TypeAlias = tuple[Optional[str], FileContent, Optional[str]]
+QueryVariable: TypeAlias = SimpleQuery | list[SimpleQuery]
-FileTypes: TypeAlias = Union[
+QueryTypes: TypeAlias = (
-    # file (or bytes)
+    None | str | Mapping[str, QueryVariable] | list[tuple[str, SimpleQuery]]
-    FileContent,
+)
-    # (filename, file (or bytes))
+
-    tuple[Optional[str], FileContent],
+HeaderTypes: TypeAlias = (
-    # (filename, file (or bytes), content_type)
+    None | CIMultiDict[str] | dict[str, str] | list[tuple[str, str]]
-    FileType,
+)
-]
+
-FilesTypes: TypeAlias = Union[dict[str, FileTypes], list[tuple[str, FileTypes]], None]
+CookieTypes: TypeAlias = (
-TimeoutTypes: TypeAlias = Union[float, "Timeout", None]
+    "None | Cookies | CookieJar | dict[str, str] | list[tuple[str, str]]"
+)
+
+ContentTypes: TypeAlias = str | bytes | None
+DataTypes: TypeAlias = dict | None
+FileContent: TypeAlias = IO[bytes] | bytes
+FileType: TypeAlias = tuple[str | None, FileContent, str | None]
+FileTypes: TypeAlias = (
+    FileContent  # file (or bytes)
+    | tuple[str | None, FileContent]  # (filename, file (or bytes))
+    | FileType  # (filename, file (or bytes), content_type)
+)
+FilesTypes: TypeAlias = dict[str, FileTypes] | list[tuple[str, FileTypes]] | None
+TimeoutTypes: TypeAlias = float | Timeout | None
 
 
 class HTTPVersion(Enum):
@@ -51,20 +54,11 @@ class HTTPVersion(Enum):
     H2 = "2"
 
 
-@dataclass
-class Timeout:
-    """Request 超时配置。"""
-
-    total: Optional[float] = None
-    connect: Optional[float] = None
-    read: Optional[float] = None
-
-
 class Request:
     def __init__(
         self,
-        method: Union[str, bytes],
+        method: str | bytes,
-        url: Union["URL", str, RawURL],
+        url: "URL | str | RawURL",
         *,
         params: QueryTypes = None,
         headers: HeaderTypes = None,
@@ -73,9 +67,9 @@ class Request:
         data: DataTypes = None,
         json: Any = None,
         files: FilesTypes = None,
-        version: Union[str, HTTPVersion] = HTTPVersion.H11,
+        version: str | HTTPVersion = HTTPVersion.H11,
         timeout: TimeoutTypes = None,
-        proxy: Optional[str] = None,
+        proxy: str | None = None,
     ):
         # method
         self.method: str = (
@@ -88,7 +82,7 @@ class Request:
         # timeout
         self.timeout: TimeoutTypes = timeout
         # proxy
-        self.proxy: Optional[str] = proxy
+        self.proxy: str | None = proxy
 
         # url
         if isinstance(url, tuple):
@@ -117,7 +111,7 @@ class Request:
         self.content: ContentTypes = content
         self.data: DataTypes = data
         self.json: Any = json
-        self.files: Optional[list[tuple[str, FileType]]] = None
+        self.files: list[tuple[str, FileType]] | None = None
         if files:
             self.files = []
             files_ = files.items() if isinstance(files, dict) else files
@@ -140,7 +134,7 @@ class Response:
         *,
         headers: HeaderTypes = None,
         content: ContentTypes = None,
-        request: Optional[Request] = None,
+        request: Request | None = None,
     ):
         # status code
         self.status_code: int = status_code
@@ -153,7 +147,7 @@ class Response:
         self.content: ContentTypes = content
 
         # request
-        self.request: Optional[Request] = request
+        self.request: Request | None = request
 
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(status_code={self.status_code!r})"
@@ -183,7 +177,7 @@ class WebSocket(abc.ABC):
         raise NotImplementedError
 
     @abc.abstractmethod
-    async def receive(self) -> Union[str, bytes]:
+    async def receive(self) -> str | bytes:
         """接收一条 WebSocket text/bytes 信息"""
         raise NotImplementedError
 
@@ -197,7 +191,7 @@ class WebSocket(abc.ABC):
         """接收一条 WebSocket binary 信息"""
         raise NotImplementedError
 
-    async def send(self, data: Union[str, bytes]) -> None:
+    async def send(self, data: str | bytes) -> None:
         """发送一条 WebSocket text/bytes 信息"""
         if isinstance(data, str):
             await self.send_text(data)
@@ -258,11 +252,11 @@ class Cookies(MutableMapping):
     def get(  # pyright: ignore[reportIncompatibleMethodOverride]
         self,
         name: str,
-        default: Optional[str] = None,
+        default: str | None = None,
-        domain: Optional[str] = None,
+        domain: str | None = None,
-        path: Optional[str] = None,
+        path: str | None = None,
-    ) -> Optional[str]:
+    ) -> str | None:
-        value: Optional[str] = None
+        value: str | None = None
         for cookie in self.jar:
             if (
                 cookie.name == name
@@ -277,7 +271,7 @@ class Cookies(MutableMapping):
         return default if value is None else value
 
     def delete(
-        self, name: str, domain: Optional[str] = None, path: Optional[str] = None
+        self, name: str, domain: str | None = None, path: str | None = None
     ) -> None:
         if domain is not None and path is not None:
             return self.jar.clear(domain, path, name)
@@ -293,7 +287,7 @@ class Cookies(MutableMapping):
         for cookie in remove:
             self.jar.clear(cookie.domain, cookie.path, cookie.name)
 
-    def clear(self, domain: Optional[str] = None, path: Optional[str] = None) -> None:
+    def clear(self, domain: str | None = None, path: str | None = None) -> None:
         self.jar.clear(domain, path)
 
     def update(  # pyright: ignore[reportIncompatibleMethodOverride]

nonebot/internal/matcher/manager.py

@@ -1,5 +1,5 @@
 from collections.abc import ItemsView, Iterator, KeysView, MutableMapping, ValuesView
-from typing import TYPE_CHECKING, Optional, TypeVar, Union, overload
+from typing import TYPE_CHECKING, TypeVar, overload
 
 from .provider import DEFAULT_PROVIDER_CLASS, MatcherProvider
 
@@ -52,7 +52,7 @@ class MatcherManager(MutableMapping[int, list[type["Matcher"]]]):
         return self.provider.items()
 
     @overload
-    def get(self, key: int) -> Optional[list[type["Matcher"]]]: ...
+    def get(self, key: int) -> list[type["Matcher"]] | None: ...
 
     @overload
     def get(
@@ -60,11 +60,11 @@ class MatcherManager(MutableMapping[int, list[type["Matcher"]]]):
     ) -> list[type["Matcher"]]: ...
 
     @overload
-    def get(self, key: int, default: T) -> Union[list[type["Matcher"]], T]: ...
+    def get(self, key: int, default: T) -> list[type["Matcher"]] | T: ...
 
     def get(
-        self, key: int, default: Optional[T] = None
+        self, key: int, default: T | None = None
-    ) -> Optional[Union[list[type["Matcher"]], T]]:
+    ) -> list[type["Matcher"]] | T | None:
         return self.provider.get(key, default)
 
     def pop(  # pyright: ignore[reportIncompatibleMethodOverride]

nonebot/internal/matcher/matcher.py

@@ -13,10 +13,8 @@ from typing import (  # noqa: UP035
     Callable,
     ClassVar,
     NoReturn,
-    Optional,
     Type,
     TypeVar,
-    Union,
     overload,
 )
 from typing_extensions import Self
@@ -87,15 +85,15 @@ current_handler: ContextVar[Dependent[Any]] = ContextVar("current_handler")
 class MatcherSource:
     """Matcher 源代码上下文信息"""
 
-    plugin_id: Optional[str] = None
+    plugin_id: str | None = None
     """事件响应器所在插件标识符"""
-    module_name: Optional[str] = None
+    module_name: str | None = None
     """事件响应器所在插件模块的路径名"""
-    lineno: Optional[int] = None
+    lineno: int | None = None
     """事件响应器所在行号"""
 
     @property
-    def plugin(self) -> Optional["Plugin"]:
+    def plugin(self) -> "Plugin | None":
         """事件响应器所在插件"""
         from nonebot.plugin import get_plugin
 
@@ -103,17 +101,17 @@ class MatcherSource:
             return get_plugin(self.plugin_id)
 
     @property
-    def plugin_name(self) -> Optional[str]:
+    def plugin_name(self) -> str | None:
         """事件响应器所在插件名"""
         return self.plugin and self.plugin.name
 
     @property
-    def module(self) -> Optional[ModuleType]:
+    def module(self) -> ModuleType | None:
         if self.module_name is not None:
             return sys.modules.get(self.module_name)
 
     @property
-    def file(self) -> Optional[Path]:
+    def file(self) -> Path | None:
         if self.module is not None and (file := inspect.getsourcefile(self.module)):
             return Path(file).absolute()
 
@@ -121,8 +119,8 @@ class MatcherSource:
 class MatcherMeta(type):
     if TYPE_CHECKING:
         type: str
-        _source: Optional[MatcherSource]
+        _source: MatcherSource | None
-        module_name: Optional[str]
+        module_name: str | None
 
     def __repr__(self) -> str:
         return (
@@ -140,7 +138,7 @@ class MatcherMeta(type):
 class Matcher(metaclass=MatcherMeta):
     """事件响应器类"""
 
-    _source: ClassVar[Optional[MatcherSource]] = None
+    _source: ClassVar[MatcherSource | None] = None
 
     type: ClassVar[str] = ""
     """事件响应器类型"""
@@ -156,15 +154,15 @@ class Matcher(metaclass=MatcherMeta):
     """事件响应器是否阻止事件传播"""
     temp: ClassVar[bool] = False
     """事件响应器是否为临时"""
-    expire_time: ClassVar[Optional[datetime]] = None
+    expire_time: ClassVar[datetime | None] = None
     """事件响应器过期时间点"""
 
     _default_state: ClassVar[T_State] = {}
     """事件响应器默认状态"""
 
-    _default_type_updater: ClassVar[Optional[Dependent[str]]] = None
+    _default_type_updater: ClassVar[Dependent[str] | None] = None
     """事件响应器类型更新函数"""
-    _default_permission_updater: ClassVar[Optional[Dependent[Permission]]] = None
+    _default_permission_updater: ClassVar[Dependent[Permission] | None] = None
     """事件响应器权限更新函数"""
 
     HANDLER_PARAM_TYPES: ClassVar[tuple[Type[Param], ...]] = (  # noqa: UP006
@@ -197,22 +195,22 @@ class Matcher(metaclass=MatcherMeta):
     def new(
         cls,
         type_: str = "",
-        rule: Optional[Rule] = None,
+        rule: Rule | None = None,
-        permission: Optional[Permission] = None,
+        permission: Permission | None = None,
-        handlers: Optional[list[Union[T_Handler, Dependent[Any]]]] = None,
+        handlers: list[T_Handler | Dependent[Any]] | None = None,
         temp: bool = False,
         priority: int = 1,
         block: bool = False,
         *,
-        plugin: Optional["Plugin"] = None,
+        plugin: "Plugin | None" = None,
-        module: Optional[ModuleType] = None,
+        module: ModuleType | None = None,
-        source: Optional[MatcherSource] = None,
+        source: MatcherSource | None = None,
-        expire_time: Optional[Union[datetime, timedelta]] = None,
+        expire_time: datetime | timedelta | None = None,
-        default_state: Optional[T_State] = None,
+        default_state: T_State | None = None,
-        default_type_updater: Optional[Union[T_TypeUpdater, Dependent[str]]] = None,
+        default_type_updater: T_TypeUpdater | Dependent[str] | None = None,
-        default_permission_updater: Optional[
+        default_permission_updater: T_PermissionUpdater
-            Union[T_PermissionUpdater, Dependent[Permission]]
+        | Dependent[Permission]
-        ] = None,
+        | None = None,
     ) -> Type[Self]:  # noqa: UP006
         """
         创建一个新的事件响应器，并存储至 `matchers <#matchers>`_
@@ -332,27 +330,27 @@ class Matcher(metaclass=MatcherMeta):
         matchers[cls.priority].remove(cls)
 
     @classproperty
-    def plugin(cls) -> Optional["Plugin"]:
+    def plugin(cls) -> "Plugin | None":
         """事件响应器所在插件"""
         return cls._source and cls._source.plugin
 
     @classproperty
-    def plugin_id(cls) -> Optional[str]:
+    def plugin_id(cls) -> str | None:
         """事件响应器所在插件标识符"""
         return cls._source and cls._source.plugin_id
 
     @classproperty
-    def plugin_name(cls) -> Optional[str]:
+    def plugin_name(cls) -> str | None:
         """事件响应器所在插件名"""
         return cls._source and cls._source.plugin_name
 
     @classproperty
-    def module(cls) -> Optional[ModuleType]:
+    def module(cls) -> ModuleType | None:
         """事件响应器所在插件模块"""
         return cls._source and cls._source.module
 
     @classproperty
-    def module_name(cls) -> Optional[str]:
+    def module_name(cls) -> str | None:
         """事件响应器所在插件模块路径"""
         return cls._source and cls._source.module_name
 
@@ -361,8 +359,8 @@ class Matcher(metaclass=MatcherMeta):
         cls,
         bot: Bot,
         event: Event,
-        stack: Optional[AsyncExitStack] = None,
+        stack: AsyncExitStack | None = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        dependency_cache: T_DependencyCache | None = None,
     ) -> bool:
         """检查是否满足触发权限
 
@@ -386,8 +384,8 @@ class Matcher(metaclass=MatcherMeta):
         bot: Bot,
         event: Event,
         state: T_State,
-        stack: Optional[AsyncExitStack] = None,
+        stack: AsyncExitStack | None = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        dependency_cache: T_DependencyCache | None = None,
     ) -> bool:
         """检查是否满足匹配规则
 
@@ -432,7 +430,7 @@ class Matcher(metaclass=MatcherMeta):
 
     @classmethod
     def append_handler(
-        cls, handler: T_Handler, parameterless: Optional[Iterable[Any]] = None
+        cls, handler: T_Handler, parameterless: Iterable[Any] | None = None
     ) -> Dependent[Any]:
         handler_ = Dependent[Any].parse(
             call=handler,
@@ -444,7 +442,7 @@ class Matcher(metaclass=MatcherMeta):
 
     @classmethod
     def handle(
-        cls, parameterless: Optional[Iterable[Any]] = None
+        cls, parameterless: Iterable[Any] | None = None
     ) -> Callable[[T_Handler], T_Handler]:
         """装饰一个函数来向事件响应器直接添加一个处理函数
 
@@ -460,7 +458,7 @@ class Matcher(metaclass=MatcherMeta):
 
     @classmethod
     def receive(
-        cls, id: str = "", parameterless: Optional[Iterable[Any]] = None
+        cls, id: str = "", parameterless: Iterable[Any] | None = None
     ) -> Callable[[T_Handler], T_Handler]:
         """装饰一个函数来指示 NoneBot 在接收用户新的一条消息后继续运行该函数
 
@@ -503,8 +501,8 @@ class Matcher(metaclass=MatcherMeta):
     def got(
         cls,
         key: str,
-        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
+        prompt: str | Message | MessageSegment | MessageTemplate | None = None,
-        parameterless: Optional[Iterable[Any]] = None,
+        parameterless: Iterable[Any] | None = None,
     ) -> Callable[[T_Handler], T_Handler]:
         """装饰一个函数来指示 NoneBot 获取一个参数 `key`
 
@@ -550,7 +548,7 @@ class Matcher(metaclass=MatcherMeta):
     @classmethod
     async def send(
         cls,
-        message: Union[str, Message, MessageSegment, MessageTemplate],
+        message: str | Message | MessageSegment | MessageTemplate,
         **kwargs: Any,
     ) -> Any:
         """发送一条消息给当前交互用户
@@ -572,7 +570,7 @@ class Matcher(metaclass=MatcherMeta):
     @classmethod
     async def finish(
         cls,
-        message: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
+        message: str | Message | MessageSegment | MessageTemplate | None = None,
         **kwargs,
     ) -> NoReturn:
         """发送一条消息给当前交互用户并结束当前事件响应器
@@ -589,7 +587,7 @@ class Matcher(metaclass=MatcherMeta):
     @classmethod
     async def pause(
         cls,
-        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
+        prompt: str | Message | MessageSegment | MessageTemplate | None = None,
         **kwargs,
     ) -> NoReturn:
         """发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后继续下一个处理函数
@@ -613,7 +611,7 @@ class Matcher(metaclass=MatcherMeta):
     @classmethod
     async def reject(
         cls,
-        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
+        prompt: str | Message | MessageSegment | MessageTemplate | None = None,
         **kwargs,
     ) -> NoReturn:
         """最近使用 `got` / `receive` 接收的消息不符合预期，
@@ -643,7 +641,7 @@ class Matcher(metaclass=MatcherMeta):
     async def reject_arg(
         cls,
         key: str,
-        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
+        prompt: str | Message | MessageSegment | MessageTemplate | None = None,
         **kwargs,
     ) -> NoReturn:
         """最近使用 `got` 接收的消息不符合预期，
@@ -668,7 +666,7 @@ class Matcher(metaclass=MatcherMeta):
     async def reject_receive(
         cls,
         id: str = "",
-        prompt: Optional[Union[str, Message, MessageSegment, MessageTemplate]] = None,
+        prompt: str | Message | MessageSegment | MessageTemplate | None = None,
         **kwargs,
     ) -> NoReturn:
         """最近使用 `receive` 接收的消息不符合预期，
@@ -698,14 +696,12 @@ class Matcher(metaclass=MatcherMeta):
         raise SkippedException
 
     @overload
-    def get_receive(self, id: str) -> Union[Event, None]: ...
+    def get_receive(self, id: str) -> Event | None: ...
 
     @overload
-    def get_receive(self, id: str, default: T) -> Union[Event, T]: ...
+    def get_receive(self, id: str, default: T) -> Event | T: ...
 
-    def get_receive(
+    def get_receive(self, id: str, default: T | None = None) -> Event | T | None:
-        self, id: str, default: Optional[T] = None
-    ) -> Optional[Union[Event, T]]:
         """获取一个 `receive` 事件
 
         如果没有找到对应的事件，返回 `default` 值
@@ -718,14 +714,12 @@ class Matcher(metaclass=MatcherMeta):
         self.state[LAST_RECEIVE_KEY] = event
 
     @overload
-    def get_last_receive(self) -> Union[Event, None]: ...
+    def get_last_receive(self) -> Event | None: ...
 
     @overload
-    def get_last_receive(self, default: T) -> Union[Event, T]: ...
+    def get_last_receive(self, default: T) -> Event | T: ...
 
-    def get_last_receive(
+    def get_last_receive(self, default: T | None = None) -> Event | T | None:
-        self, default: Optional[T] = None
-    ) -> Optional[Union[Event, T]]:
         """获取最近一次 `receive` 事件
 
         如果没有事件，返回 `default` 值
@@ -733,14 +727,12 @@ class Matcher(metaclass=MatcherMeta):
         return self.state.get(LAST_RECEIVE_KEY, default)
 
     @overload
-    def get_arg(self, key: str) -> Union[Message, None]: ...
+    def get_arg(self, key: str) -> Message | None: ...
 
     @overload
-    def get_arg(self, key: str, default: T) -> Union[Message, T]: ...
+    def get_arg(self, key: str, default: T) -> Message | T: ...
 
-    def get_arg(
+    def get_arg(self, key: str, default: T | None = None) -> Message | T | None:
-        self, key: str, default: Optional[T] = None
-    ) -> Optional[Union[Message, T]]:
         """获取一个 `got` 消息
 
         如果没有找到对应的消息，返回 `default` 值
@@ -758,12 +750,12 @@ class Matcher(metaclass=MatcherMeta):
             self.state[REJECT_TARGET] = target
 
     @overload
-    def get_target(self) -> Union[str, None]: ...
+    def get_target(self) -> str | None: ...
 
     @overload
-    def get_target(self, default: T) -> Union[str, T]: ...
+    def get_target(self, default: T) -> str | T: ...
 
-    def get_target(self, default: Optional[T] = None) -> Optional[Union[str, T]]:
+    def get_target(self, default: T | None = None) -> str | T | None:
         return self.state.get(REJECT_TARGET, default)
 
     def stop_propagation(self):
@@ -774,8 +766,8 @@ class Matcher(metaclass=MatcherMeta):
         self,
         bot: Bot,
         event: Event,
-        stack: Optional[AsyncExitStack] = None,
+        stack: AsyncExitStack | None = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        dependency_cache: T_DependencyCache | None = None,
     ) -> str:
         updater = self.__class__._default_type_updater
         return (
@@ -795,8 +787,8 @@ class Matcher(metaclass=MatcherMeta):
         self,
         bot: Bot,
         event: Event,
-        stack: Optional[AsyncExitStack] = None,
+        stack: AsyncExitStack | None = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        dependency_cache: T_DependencyCache | None = None,
     ) -> Permission:
         if updater := self.__class__._default_permission_updater:
             return await updater(
@@ -832,8 +824,8 @@ class Matcher(metaclass=MatcherMeta):
         bot: Bot,
         event: Event,
         state: T_State,
-        stack: Optional[AsyncExitStack] = None,
+        stack: AsyncExitStack | None = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        dependency_cache: T_DependencyCache | None = None,
     ):
         logger.trace(
             f"{self} run with incoming args: "
@@ -877,16 +869,14 @@ class Matcher(metaclass=MatcherMeta):
         bot: Bot,
         event: Event,
         state: T_State,
-        stack: Optional[AsyncExitStack] = None,
+        stack: AsyncExitStack | None = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        dependency_cache: T_DependencyCache | None = None,
     ):
-        exc: Optional[Union[FinishedException, RejectedException, PausedException]] = (
+        exc: FinishedException | RejectedException | PausedException | None = None
-            None
-        )
 
         def _handle_special_exception(
             exc_group: BaseExceptionGroup[
-                Union[FinishedException, RejectedException, PausedException]
+                FinishedException | RejectedException | PausedException
             ],
         ):
             nonlocal exc

nonebot/internal/params.py

@@ -1,3 +1,4 @@
+from collections.abc import Callable
 from contextlib import AsyncExitStack, asynccontextmanager, contextmanager
 from enum import Enum
 import inspect
@@ -5,19 +6,18 @@ from typing import (
     TYPE_CHECKING,
     Annotated,
     Any,
-    Callable,
     Literal,
-    Optional,
-    Union,
     cast,
+    get_args,
+    get_origin,
 )
-from typing_extensions import Self, get_args, get_origin, override
+from typing_extensions import Self, override
 
 import anyio
 from exceptiongroup import BaseExceptionGroup, catch
 from pydantic.fields import FieldInfo as PydanticFieldInfo
 
-from nonebot.compat import FieldInfo, ModelField, PydanticUndefined, extract_field_info
+from nonebot.compat import FieldInfo, ModelField, PydanticUndefined
 from nonebot.consts import ARG_KEY, REJECT_PROMPT_RESULT_KEY
 from nonebot.dependencies import Dependent, Param
 from nonebot.dependencies.utils import check_field_type
@@ -47,10 +47,10 @@ if TYPE_CHECKING:
 class DependsInner:
     def __init__(
         self,
-        dependency: Optional[T_Handler] = None,
+        dependency: T_Handler | None = None,
         *,
         use_cache: bool = True,
-        validate: Union[bool, PydanticFieldInfo] = False,
+        validate: bool | PydanticFieldInfo = False,
     ) -> None:
         self.dependency = dependency
         self.use_cache = use_cache
@@ -64,10 +64,10 @@ class DependsInner:
 
 
 def Depends(
-    dependency: Optional[T_Handler] = None,
+    dependency: T_Handler | None = None,
     *,
     use_cache: bool = True,
-    validate: Union[bool, PydanticFieldInfo] = False,
+    validate: bool | PydanticFieldInfo = False,
 ) -> Any:
     """子依赖装饰器
 
@@ -113,7 +113,7 @@ class DependencyCache:
     def __init__(self):
         self._state = CacheState.PENDING
         self._result: Any = None
-        self._exception: Optional[BaseException] = None
+        self._exception: BaseException | None = None
         self._waiter = anyio.Event()
 
     def done(self) -> bool:
@@ -129,7 +129,7 @@ class DependencyCache:
             raise self._exception
         return self._result
 
-    def exception(self) -> Optional[BaseException]:
+    def exception(self) -> BaseException | None:
         """获取子依赖异常"""
 
         if self._state != CacheState.FINISHED:
@@ -192,23 +192,20 @@ class DependParam(Param):
         cls,
         sub_dependent: Dependent[Any],
         use_cache: bool,
-        validate: Union[bool, PydanticFieldInfo],
+        validate: bool | PydanticFieldInfo,
     ) -> Self:
-        kwargs = {}
+        return cls._inherit_construct(
-        if isinstance(validate, PydanticFieldInfo):
+            validate if isinstance(validate, PydanticFieldInfo) else None,
-            kwargs.update(extract_field_info(validate))
+            dependent=sub_dependent,
-
+            use_cache=use_cache,
-        kwargs["validate"] = bool(validate)
+            validate=bool(validate),
-        kwargs["dependent"] = sub_dependent
+        )
-        kwargs["use_cache"] = use_cache
-
-        return cls(**kwargs)
 
     @classmethod
     @override
     def _check_param(
         cls, param: inspect.Parameter, allow_types: tuple[type[Param], ...]
-    ) -> Optional[Self]:
+    ) -> Self | None:
         type_annotation, depends_inner = param.annotation, None
         # extract type annotation and dependency from Annotated
         if get_origin(param.annotation) is Annotated:
@@ -248,7 +245,7 @@ class DependParam(Param):
     @override
     def _check_parameterless(
         cls, value: Any, allow_types: tuple[type[Param], ...]
-    ) -> Optional["Param"]:
+    ) -> "Param | None":
         if isinstance(value, DependsInner):
             assert value.dependency, "Dependency cannot be empty"
             dependent = Dependent[Any].parse(
@@ -259,8 +256,8 @@ class DependParam(Param):
     @override
     async def _solve(
         self,
-        stack: Optional[AsyncExitStack] = None,
+        stack: AsyncExitStack | None = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        dependency_cache: T_DependencyCache | None = None,
         **kwargs: Any,
     ) -> Any:
         use_cache: bool = self.use_cache
@@ -270,7 +267,7 @@ class DependParam(Param):
         call = cast(Callable[..., Any], sub_dependent.call)
 
         # solve sub dependency with current cache
-        exc: Optional[BaseExceptionGroup[SkippedException]] = None
+        exc: BaseExceptionGroup[SkippedException] | None = None
 
         def _handle_skipped(exc_group: BaseExceptionGroup[SkippedException]):
             nonlocal exc
@@ -335,9 +332,7 @@ class BotParam(Param):
     为保证兼容性，本注入还会解析名为 `bot` 且没有类型注解的参数。
     """
 
-    def __init__(
+    def __init__(self, *args, checker: ModelField | None = None, **kwargs: Any) -> None:
-        self, *args, checker: Optional[ModelField] = None, **kwargs: Any
-    ) -> None:
         super().__init__(*args, **kwargs)
         self.checker = checker
 
@@ -352,12 +347,12 @@ class BotParam(Param):
     @override
     def _check_param(
         cls, param: inspect.Parameter, allow_types: tuple[type[Param], ...]
-    ) -> Optional[Self]:
+    ) -> Self | None:
         from nonebot.adapters import Bot
 
         # param type is Bot(s) or subclass(es) of Bot or None
         if generic_check_issubclass(param.annotation, Bot):
-            checker: Optional[ModelField] = None
+            checker: ModelField | None = None
             if param.annotation is not Bot:
                 checker = ModelField.construct(
                     name=param.name, annotation=param.annotation, field_info=FieldInfo()
@@ -389,9 +384,7 @@ class EventParam(Param):
     为保证兼容性，本注入还会解析名为 `event` 且没有类型注解的参数。
     """
 
-    def __init__(
+    def __init__(self, *args, checker: ModelField | None = None, **kwargs: Any) -> None:
-        self, *args, checker: Optional[ModelField] = None, **kwargs: Any
-    ) -> None:
         super().__init__(*args, **kwargs)
         self.checker = checker
 
@@ -406,12 +399,12 @@ class EventParam(Param):
     @override
     def _check_param(
         cls, param: inspect.Parameter, allow_types: tuple[type[Param], ...]
-    ) -> Optional[Self]:
+    ) -> Self | None:
         from nonebot.adapters import Event
 
         # param type is Event(s) or subclass(es) of Event or None
         if generic_check_issubclass(param.annotation, Event):
-            checker: Optional[ModelField] = None
+            checker: ModelField | None = None
             if param.annotation is not Event:
                 checker = ModelField.construct(
                     name=param.name, annotation=param.annotation, field_info=FieldInfo()
@@ -450,7 +443,7 @@ class StateParam(Param):
     @override
     def _check_param(
         cls, param: inspect.Parameter, allow_types: tuple[type[Param], ...]
-    ) -> Optional[Self]:
+    ) -> Self | None:
         # param type is T_State
         if origin_is_annotated(
             get_origin(param.annotation)
@@ -475,9 +468,7 @@ class MatcherParam(Param):
     为保证兼容性，本注入还会解析名为 `matcher` 且没有类型注解的参数。
     """
 
-    def __init__(
+    def __init__(self, *args, checker: ModelField | None = None, **kwargs: Any) -> None:
-        self, *args, checker: Optional[ModelField] = None, **kwargs: Any
-    ) -> None:
         super().__init__(*args, **kwargs)
         self.checker = checker
 
@@ -492,12 +483,12 @@ class MatcherParam(Param):
     @override
     def _check_param(
         cls, param: inspect.Parameter, allow_types: tuple[type[Param], ...]
-    ) -> Optional[Self]:
+    ) -> Self | None:
         from nonebot.matcher import Matcher
 
         # param type is Matcher(s) or subclass(es) of Matcher or None
         if generic_check_issubclass(param.annotation, Matcher):
-            checker: Optional[ModelField] = None
+            checker: ModelField | None = None
             if param.annotation is not Matcher:
                 checker = ModelField.construct(
                     name=param.name, annotation=param.annotation, field_info=FieldInfo()
@@ -523,31 +514,31 @@ class MatcherParam(Param):
 
 class ArgInner:
     def __init__(
-        self, key: Optional[str], type: Literal["message", "str", "plaintext", "prompt"]
+        self, key: str | None, type: Literal["message", "str", "plaintext", "prompt"]
     ) -> None:
-        self.key: Optional[str] = key
+        self.key: str | None = key
         self.type: Literal["message", "str", "plaintext", "prompt"] = type
 
     def __repr__(self) -> str:
         return f"ArgInner(key={self.key!r}, type={self.type!r})"
 
 
-def Arg(key: Optional[str] = None) -> Any:
+def Arg(key: str | None = None) -> Any:
     """Arg 参数消息"""
     return ArgInner(key, "message")
 
 
-def ArgStr(key: Optional[str] = None) -> str:
+def ArgStr(key: str | None = None) -> str:
     """Arg 参数消息文本"""
     return ArgInner(key, "str")  # type: ignore
 
 
-def ArgPlainText(key: Optional[str] = None) -> str:
+def ArgPlainText(key: str | None = None) -> str:
     """Arg 参数消息纯文本"""
     return ArgInner(key, "plaintext")  # type: ignore
 
 
-def ArgPromptResult(key: Optional[str] = None) -> Any:
+def ArgPromptResult(key: str | None = None) -> Any:
     """`arg` prompt 发送结果"""
     return ArgInner(key, "prompt")
 
@@ -579,7 +570,7 @@ class ArgParam(Param):
     @override
     def _check_param(
         cls, param: inspect.Parameter, allow_types: tuple[type[Param], ...]
-    ) -> Optional[Self]:
+    ) -> Self | None:
         if isinstance(param.default, ArgInner):
             return cls(key=param.default.key or param.name, type=param.default.type)
         elif get_origin(param.annotation) is Annotated:
@@ -601,18 +592,18 @@ class ArgParam(Param):
         else:
             raise ValueError(f"Unknown Arg type: {self.type}")
 
-    def _solve_message(self, matcher: "Matcher") -> Optional["Message"]:
+    def _solve_message(self, matcher: "Matcher") -> "Message | None":
         return matcher.get_arg(self.key)
 
-    def _solve_str(self, matcher: "Matcher") -> Optional[str]:
+    def _solve_str(self, matcher: "Matcher") -> str | None:
         message = matcher.get_arg(self.key)
         return str(message) if message is not None else None
 
-    def _solve_plaintext(self, matcher: "Matcher") -> Optional[str]:
+    def _solve_plaintext(self, matcher: "Matcher") -> str | None:
         message = matcher.get_arg(self.key)
         return message.extract_plain_text() if message is not None else None
 
-    def _solve_prompt(self, matcher: "Matcher") -> Optional[Any]:
+    def _solve_prompt(self, matcher: "Matcher") -> Any | None:
         return matcher.state.get(
             REJECT_PROMPT_RESULT_KEY.format(key=ARG_KEY.format(key=self.key))
         )
@@ -633,7 +624,7 @@ class ExceptionParam(Param):
     @override
     def _check_param(
         cls, param: inspect.Parameter, allow_types: tuple[type[Param], ...]
-    ) -> Optional[Self]:
+    ) -> Self | None:
         # param type is Exception(s) or subclass(es) of Exception or None
         if generic_check_issubclass(param.annotation, Exception):
             return cls()
@@ -642,7 +633,7 @@ class ExceptionParam(Param):
             return cls()
 
     @override
-    async def _solve(self, exception: Optional[Exception] = None, **kwargs: Any) -> Any:
+    async def _solve(self, exception: Exception | None = None, **kwargs: Any) -> Any:
         return exception
 
 
@@ -661,7 +652,7 @@ class DefaultParam(Param):
     @override
     def _check_param(
         cls, param: inspect.Parameter, allow_types: tuple[type[Param], ...]
-    ) -> Optional[Self]:
+    ) -> Self | None:
         if param.default != param.empty:
             return cls(default=param.default)
 

nonebot/internal/permission.py

@@ -1,5 +1,5 @@
 from contextlib import AsyncExitStack
-from typing import ClassVar, NoReturn, Optional, Union
+from typing import ClassVar, NoReturn
 from typing_extensions import Self
 
 import anyio
@@ -38,7 +38,7 @@ class Permission:
         DefaultParam,
     ]
 
-    def __init__(self, *checkers: Union[T_PermissionChecker, Dependent[bool]]) -> None:
+    def __init__(self, *checkers: T_PermissionChecker | Dependent[bool]) -> None:
         self.checkers: set[Dependent[bool]] = {
             (
                 checker
@@ -58,8 +58,8 @@ class Permission:
         self,
         bot: Bot,
         event: Event,
-        stack: Optional[AsyncExitStack] = None,
+        stack: AsyncExitStack | None = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        dependency_cache: T_DependencyCache | None = None,
     ) -> bool:
         """检查是否满足某个权限。
 
@@ -95,9 +95,7 @@ class Permission:
     def __and__(self, other: object) -> NoReturn:
         raise RuntimeError("And operation between Permissions is not allowed.")
 
-    def __or__(
+    def __or__(self, other: "Permission | T_PermissionChecker | None") -> "Permission":
-        self, other: Optional[Union["Permission", T_PermissionChecker]]
-    ) -> "Permission":
         if other is None:
             return self
         elif isinstance(other, Permission):
@@ -105,9 +103,7 @@ class Permission:
         else:
             return Permission(*self.checkers, other)
 
-    def __ror__(
+    def __ror__(self, other: "Permission | T_PermissionChecker | None") -> "Permission":
-        self, other: Optional[Union["Permission", T_PermissionChecker]]
-    ) -> "Permission":
         if other is None:
             return self
         elif isinstance(other, Permission):
@@ -126,9 +122,7 @@ class User:
 
     __slots__ = ("perm", "users")
 
-    def __init__(
+    def __init__(self, users: tuple[str, ...], perm: Permission | None = None) -> None:
-        self, users: tuple[str, ...], perm: Optional[Permission] = None
-    ) -> None:
         self.users = users
         self.perm = perm
 
@@ -149,7 +143,7 @@ class User:
         )
 
     @classmethod
-    def _clean_permission(cls, perm: Permission) -> Optional[Permission]:
+    def _clean_permission(cls, perm: Permission) -> Permission | None:
         if len(perm.checkers) == 1 and isinstance(
             user_perm := next(iter(perm.checkers)).call, cls
         ):
@@ -157,7 +151,7 @@ class User:
         return perm
 
     @classmethod
-    def from_event(cls, event: Event, perm: Optional[Permission] = None) -> Self:
+    def from_event(cls, event: Event, perm: Permission | None = None) -> Self:
         """从事件中获取会话 ID。
 
         如果 `perm` 中仅有 `User` 类型的权限检查函数，则会去除原有的会话 ID 限制。
@@ -169,7 +163,7 @@ class User:
         return cls((event.get_session_id(),), perm=perm and cls._clean_permission(perm))
 
     @classmethod
-    def from_permission(cls, *users: str, perm: Optional[Permission] = None) -> Self:
+    def from_permission(cls, *users: str, perm: Permission | None = None) -> Self:
         """指定会话与权限。
 
         如果 `perm` 中仅有 `User` 类型的权限检查函数，则会去除原有的会话 ID 限制。
@@ -181,7 +175,7 @@ class User:
         return cls(users, perm=perm and cls._clean_permission(perm))
 
 
-def USER(*users: str, perm: Optional[Permission] = None):
+def USER(*users: str, perm: Permission | None = None):
     """匹配当前事件属于指定会话。
 
     如果 `perm` 中仅有 `User` 类型的权限检查函数，则会去除原有检查函数的会话 ID 限制。

nonebot/internal/rule.py

@@ -1,5 +1,5 @@
 from contextlib import AsyncExitStack
-from typing import ClassVar, NoReturn, Optional, Union
+from typing import ClassVar, NoReturn
 
 import anyio
 from exceptiongroup import BaseExceptionGroup, catch
@@ -38,7 +38,7 @@ class Rule:
         DefaultParam,
     ]
 
-    def __init__(self, *checkers: Union[T_RuleChecker, Dependent[bool]]) -> None:
+    def __init__(self, *checkers: T_RuleChecker | Dependent[bool]) -> None:
         self.checkers: set[Dependent[bool]] = {
             (
                 checker
@@ -59,8 +59,8 @@ class Rule:
         bot: Bot,
         event: Event,
         state: T_State,
-        stack: Optional[AsyncExitStack] = None,
+        stack: AsyncExitStack | None = None,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        dependency_cache: T_DependencyCache | None = None,
     ) -> bool:
         """检查是否符合所有规则
 
@@ -101,7 +101,7 @@ class Rule:
 
         return result
 
-    def __and__(self, other: Optional[Union["Rule", T_RuleChecker]]) -> "Rule":
+    def __and__(self, other: "Rule | T_RuleChecker | None") -> "Rule":
         if other is None:
             return self
         elif isinstance(other, Rule):
@@ -109,7 +109,7 @@ class Rule:
         else:
             return Rule(*self.checkers, other)
 
-    def __rand__(self, other: Optional[Union["Rule", T_RuleChecker]]) -> "Rule":
+    def __rand__(self, other: "Rule | T_RuleChecker | None") -> "Rule":
         if other is None:
             return self
         elif isinstance(other, Rule):

nonebot/message.py

@@ -9,10 +9,11 @@ FrontMatter:
     description: nonebot.message 模块
 """
 
+from collections.abc import Callable
 import contextlib
 from contextlib import AsyncExitStack
 from datetime import datetime
-from typing import TYPE_CHECKING, Any, Callable, Optional
+from typing import TYPE_CHECKING, Any
 
 import anyio
 from exceptiongroup import BaseExceptionGroup, catch
@@ -153,8 +154,8 @@ async def _apply_event_preprocessors(
     bot: "Bot",
     event: "Event",
     state: T_State,
-    stack: Optional[AsyncExitStack] = None,
+    stack: AsyncExitStack | None = None,
-    dependency_cache: Optional[T_DependencyCache] = None,
+    dependency_cache: T_DependencyCache | None = None,
     show_log: bool = True,
 ) -> bool:
     """运行事件预处理。
@@ -210,8 +211,8 @@ async def _apply_event_postprocessors(
     bot: "Bot",
     event: "Event",
     state: T_State,
-    stack: Optional[AsyncExitStack] = None,
+    stack: AsyncExitStack | None = None,
-    dependency_cache: Optional[T_DependencyCache] = None,
+    dependency_cache: T_DependencyCache | None = None,
     show_log: bool = True,
 ) -> None:
     """运行事件后处理。
@@ -257,8 +258,8 @@ async def _apply_run_preprocessors(
     event: "Event",
     state: T_State,
     matcher: Matcher,
-    stack: Optional[AsyncExitStack] = None,
+    stack: AsyncExitStack | None = None,
-    dependency_cache: Optional[T_DependencyCache] = None,
+    dependency_cache: T_DependencyCache | None = None,
 ) -> bool:
     """运行事件响应器运行前处理。
 
@@ -315,9 +316,9 @@ async def _apply_run_postprocessors(
     bot: "Bot",
     event: "Event",
     matcher: Matcher,
-    exception: Optional[Exception] = None,
+    exception: Exception | None = None,
-    stack: Optional[AsyncExitStack] = None,
+    stack: AsyncExitStack | None = None,
-    dependency_cache: Optional[T_DependencyCache] = None,
+    dependency_cache: T_DependencyCache | None = None,
 ) -> None:
     """运行事件响应器运行后处理。
 
@@ -365,8 +366,8 @@ async def _check_matcher(
     bot: "Bot",
     event: "Event",
     state: T_State,
-    stack: Optional[AsyncExitStack] = None,
+    stack: AsyncExitStack | None = None,
-    dependency_cache: Optional[T_DependencyCache] = None,
+    dependency_cache: T_DependencyCache | None = None,
 ) -> bool:
     """检查事件响应器是否符合运行条件。
 
@@ -416,8 +417,8 @@ async def _run_matcher(
     bot: "Bot",
     event: "Event",
     state: T_State,
-    stack: Optional[AsyncExitStack] = None,
+    stack: AsyncExitStack | None = None,
-    dependency_cache: Optional[T_DependencyCache] = None,
+    dependency_cache: T_DependencyCache | None = None,
 ) -> None:
     """运行事件响应器。
 
@@ -482,8 +483,8 @@ async def check_and_run_matcher(
     bot: "Bot",
     event: "Event",
     state: T_State,
-    stack: Optional[AsyncExitStack] = None,
+    stack: AsyncExitStack | None = None,
-    dependency_cache: Optional[T_DependencyCache] = None,
+    dependency_cache: T_DependencyCache | None = None,
 ) -> None:
     """检查并运行事件响应器。
 

nonebot/params.py

@@ -7,8 +7,9 @@ FrontMatter:
     description: nonebot.params 模块
 """
 
+from collections.abc import Callable
 from re import Match
-from typing import Any, Callable, Literal, Optional, Union, overload
+from typing import Any, Literal, overload
 
 from nonebot.adapters import Event, Message, MessageSegment
 from nonebot.consts import (
@@ -136,7 +137,7 @@ def ShellCommandArgs() -> Any:
     return Depends(_shell_command_args, use_cache=False)
 
 
-def _shell_command_argv(state: T_State) -> list[Union[str, MessageSegment]]:
+def _shell_command_argv(state: T_State) -> list[str | MessageSegment]:
     return state[SHELL_ARGV]
 
 
@@ -155,11 +156,11 @@ def RegexMatched() -> Match[str]:
 
 
 def _regex_str(
-    groups: tuple[Union[str, int], ...],
+    groups: tuple[str | int, ...],
-) -> Callable[[T_State], Union[str, tuple[Union[str, Any], ...], Any]]:
+) -> Callable[[T_State], str | tuple[str | Any, ...] | Any]:
     def _regex_str_dependency(
         state: T_State,
-    ) -> Union[str, tuple[Union[str, Any], ...], Any]:
+    ) -> str | tuple[str | Any, ...] | Any:
         return _regex_matched(state).group(*groups)
 
     return _regex_str_dependency
@@ -170,16 +171,16 @@ def RegexStr(group: Literal[0] = 0, /) -> str: ...
 
 
 @overload
-def RegexStr(group: Union[str, int], /) -> Union[str, Any]: ...
+def RegexStr(group: str | int, /) -> str | Any: ...
 
 
 @overload
 def RegexStr(
-    group1: Union[str, int], group2: Union[str, int], /, *groups: Union[str, int]
+    group1: str | int, group2: str | int, /, *groups: str | int
-) -> tuple[Union[str, Any], ...]: ...
+) -> tuple[str | Any, ...]: ...
 
 
-def RegexStr(*groups: Union[str, int]) -> Union[str, tuple[Union[str, Any], ...], Any]:
+def RegexStr(*groups: str | int) -> str | tuple[str | Any, ...] | Any:
     """正则匹配结果文本"""
     return Depends(_regex_str(groups), use_cache=False)
 
@@ -238,7 +239,7 @@ def Keyword() -> str:
     return Depends(_keyword, use_cache=False)
 
 
-def Received(id: Optional[str] = None, default: Any = None) -> Any:
+def Received(id: str | None = None, default: Any = None) -> Any:
     """`receive` 事件参数"""
 
     def _received(matcher: "Matcher") -> Any:
@@ -256,7 +257,7 @@ def LastReceived(default: Any = None) -> Any:
     return Depends(_last_received, use_cache=False)
 
 
-def ReceivePromptResult(id: Optional[str] = None) -> Any:
+def ReceivePromptResult(id: str | None = None) -> Any:
     """`receive` prompt 发送结果"""
 
     def _receive_prompt_result(matcher: "Matcher") -> Any:

nonebot/plugin/__init__.py

@@ -41,18 +41,19 @@ FrontMatter:
 from contextvars import ContextVar
 from itertools import chain
 from types import ModuleType
-from typing import Optional, TypeVar
+from typing import TypeVar
 
 from pydantic import BaseModel
 
 from nonebot import get_driver
 from nonebot.compat import model_dump, type_validate_python
+from nonebot.config import BaseSettings
 
 C = TypeVar("C", bound=BaseModel)
 
 _plugins: dict[str, "Plugin"] = {}
 _managers: list["PluginManager"] = []
-_current_plugin: ContextVar[Optional["Plugin"]] = ContextVar(
+_current_plugin: ContextVar["Plugin | None"] = ContextVar(
     "_current_plugin", default=None
 )
 
@@ -70,8 +71,8 @@ def _controlled_modules() -> dict[str, str]:
 
 
 def _find_parent_plugin_id(
-    module_name: str, controlled_modules: Optional[dict[str, str]] = None
+    module_name: str, controlled_modules: dict[str, str] | None = None
-) -> Optional[str]:
+) -> str | None:
     if controlled_modules is None:
         controlled_modules = _controlled_modules()
     available = {
@@ -84,7 +85,7 @@ def _find_parent_plugin_id(
 
 
 def _module_name_to_plugin_id(
-    module_name: str, controlled_modules: Optional[dict[str, str]] = None
+    module_name: str, controlled_modules: dict[str, str] | None = None
 ) -> str:
     plugin_name = _module_name_to_plugin_name(module_name)
     if parent_plugin_id := _find_parent_plugin_id(module_name, controlled_modules):
@@ -131,7 +132,7 @@ def _revert_plugin(plugin: "Plugin") -> None:
         parent_plugin.sub_plugins.discard(plugin)
 
 
-def get_plugin(plugin_id: str) -> Optional["Plugin"]:
+def get_plugin(plugin_id: str) -> "Plugin | None":
     """获取已经导入的某个插件。
 
     如果为 `load_plugins` 文件夹导入的插件，则为文件(夹)名。
@@ -144,7 +145,7 @@ def get_plugin(plugin_id: str) -> Optional["Plugin"]:
     return _plugins.get(plugin_id)
 
 
-def get_plugin_by_module_name(module_name: str) -> Optional["Plugin"]:
+def get_plugin_by_module_name(module_name: str) -> "Plugin | None":
     """通过模块名获取已经导入的某个插件。
 
     如果提供的模块名为某个插件的子模块，同样会返回该插件。
@@ -172,7 +173,17 @@ def get_available_plugin_names() -> set[str]:
 
 def get_plugin_config(config: type[C]) -> C:
     """从全局配置获取当前插件需要的配置项。"""
-    return type_validate_python(config, model_dump(get_driver().config))
+    global_config = get_driver().config
+    return type_validate_python(
+        config,
+        BaseSettings._settings_build_values(
+            config,
+            model_dump(global_config),
+            env_file=global_config._env_file,
+            env_file_encoding=global_config._env_file_encoding,
+            env_nested_delimiter=global_config._env_nested_delimiter,
+        ),
+    )
 
 
 from .load import inherit_supported_adapters as inherit_supported_adapters

nonebot/plugin/load.py

@@ -8,11 +8,12 @@ FrontMatter:
 """
 
 from collections.abc import Iterable
+from itertools import chain
 import json
 from pathlib import Path
 from types import ModuleType
-from typing import Optional, Union
 
+from nonebot.log import logger
 from nonebot.utils import path_to_module_name
 
 from . import _managers, _module_name_to_plugin_id, get_plugin
@@ -25,7 +26,7 @@ except ModuleNotFoundError:  # pragma: py-lt-311
     import tomli as tomllib  # pyright: ignore[reportMissingImports]
 
 
-def load_plugin(module_path: Union[str, Path]) -> Optional[Plugin]:
+def load_plugin(module_path: str | Path) -> Plugin | None:
     """加载单个插件，可以是本地插件或是通过 `pip` 安装的插件。
 
     参数:
@@ -108,6 +109,19 @@ def load_from_toml(file_path: str, encoding: str = "utf-8") -> set[Plugin]:
         encoding: 指定 toml 文件编码
 
     用法:
+        新格式:
+
+        ```toml title=pyproject.toml
+        [tool.nonebot]
+        plugin_dirs = ["some_dir"]
+
+        [tool.nonebot.plugins]
+        some-store-plugin = ["some_store_plugin"]
+        "@local" = ["some_local_plugin"]
+        ```
+
+        旧格式:
+
         ```toml title=pyproject.toml
         [tool.nonebot]
         plugins = ["some_plugin"]
@@ -126,14 +140,25 @@ def load_from_toml(file_path: str, encoding: str = "utf-8") -> set[Plugin]:
         raise ValueError("Cannot find '[tool.nonebot]' in given toml file!")
     if not isinstance(nonebot_data, dict):
         raise TypeError("'[tool.nonebot]' must be a Table!")
-    plugins = nonebot_data.get("plugins", [])
+    plugins = nonebot_data.get("plugins", {})
     plugin_dirs = nonebot_data.get("plugin_dirs", [])
-    assert isinstance(plugins, list), "plugins must be a list of plugin name"
+    assert isinstance(plugins, (list, dict)), (
+        "plugins must be a list or a dict of plugin name"
+    )
     assert isinstance(plugin_dirs, list), "plugin_dirs must be a list of directories"
-    return load_all_plugins(plugins, plugin_dirs)
+    if isinstance(plugins, list):
+        logger.warning("Legacy project format found! Upgrade with `nb upgrade-format`.")
+    return load_all_plugins(
+        set(
+            chain.from_iterable(plugins.values())
+            if isinstance(plugins, dict)
+            else plugins
+        ),
+        plugin_dirs,
+    )
 
 
-def load_builtin_plugin(name: str) -> Optional[Plugin]:
+def load_builtin_plugin(name: str) -> Plugin | None:
     """导入 NoneBot 内置插件。
 
     参数:
@@ -151,7 +176,7 @@ def load_builtin_plugins(*plugins: str) -> set[Plugin]:
     return load_all_plugins([f"nonebot.plugins.{p}" for p in plugins], [])
 
 
-def _find_manager_by_name(name: str) -> Optional[PluginManager]:
+def _find_manager_by_name(name: str) -> PluginManager | None:
     for manager in reversed(_managers):
         if (
             name in manager.controlled_modules
@@ -191,7 +216,7 @@ def require(name: str) -> ModuleType:
     return plugin.module
 
 
-def inherit_supported_adapters(*names: str) -> Optional[set[str]]:
+def inherit_supported_adapters(*names: str) -> set[str] | None:
     """获取已加载插件的适配器支持状态集合。
 
     如果传入了多个插件名称，返回值会自动取交集。
@@ -203,7 +228,7 @@ def inherit_supported_adapters(*names: str) -> Optional[set[str]]:
         RuntimeError: 插件未加载
         ValueError: 插件缺少元数据
     """
-    final_supported: Optional[set[str]] = None
+    final_supported: set[str] | None = None
 
     for name in names:
         plugin = get_plugin(_module_name_to_plugin_id(name))

nonebot/plugin/manager.py

@@ -18,7 +18,6 @@ from pathlib import Path
 import pkgutil
 import sys
 from types import ModuleType
-from typing import Optional
 
 from nonebot.log import logger
 from nonebot.utils import escape_tag, path_to_module_name
@@ -43,8 +42,8 @@ class PluginManager:
 
     def __init__(
         self,
-        plugins: Optional[Iterable[str]] = None,
+        plugins: Iterable[str] | None = None,
-        search_path: Optional[Iterable[str]] = None,
+        search_path: Iterable[str] | None = None,
     ):
         # simple plugin not in search path
         self.plugins: set[str] = set(plugins or [])
@@ -154,7 +153,7 @@ class PluginManager:
 
         return self.available_plugins
 
-    def load_plugin(self, name: str) -> Optional[Plugin]:
+    def load_plugin(self, name: str) -> Plugin | None:
         """加载指定插件。
 
         可以使用完整插件模块名或者插件标识符加载。
@@ -211,8 +210,8 @@ class PluginFinder(MetaPathFinder):
     def find_spec(
         self,
         fullname: str,
-        path: Optional[Sequence[str]],
+        path: Sequence[str] | None,
-        target: Optional[ModuleType] = None,
+        target: ModuleType | None = None,
     ):
         if _managers:
             module_spec = PathFinder.find_spec(fullname, path, target)
@@ -235,7 +234,7 @@ class PluginLoader(SourceFileLoader):
         self.loaded = False
         super().__init__(fullname, path)
 
-    def create_module(self, spec) -> Optional[ModuleType]:
+    def create_module(self, spec) -> ModuleType | None:
         if self.name in sys.modules:
             self.loaded = True
             return sys.modules[self.name]
@@ -263,7 +262,7 @@ class PluginLoader(SourceFileLoader):
             _current_plugin.reset(_plugin_token)
 
         # get plugin metadata
-        metadata: Optional[PluginMetadata] = getattr(module, "__plugin_meta__", None)
+        metadata: PluginMetadata | None = getattr(module, "__plugin_meta__", None)
         plugin.metadata = metadata
 
         return

nonebot/plugin/model.py

@@ -10,7 +10,7 @@ FrontMatter:
 import contextlib
 from dataclasses import dataclass, field
 from types import ModuleType
-from typing import TYPE_CHECKING, Any, Optional, Type  # noqa: UP035
+from typing import TYPE_CHECKING, Any, Type  # noqa: UP035
 
 from pydantic import BaseModel
 
@@ -33,13 +33,13 @@ class PluginMetadata:
     """插件功能介绍"""
     usage: str
     """插件使用方法"""
-    type: Optional[str] = None
+    type: str | None = None
     """插件类型，用于商店分类"""
-    homepage: Optional[str] = None
+    homepage: str | None = None
     """插件主页"""
-    config: Optional[Type[BaseModel]] = None  # noqa: UP006
+    config: Type[BaseModel] | None = None  # noqa: UP006
     """插件配置项"""
-    supported_adapters: Optional[set[str]] = None
+    supported_adapters: set[str] | None = None
     """插件支持的适配器模块路径
 
     格式为 `<module>[:<Adapter>]`，`~` 为 `nonebot.adapters.` 的缩写。
@@ -49,7 +49,7 @@ class PluginMetadata:
     extra: dict[Any, Any] = field(default_factory=dict)
     """插件额外信息，可由插件编写者自由扩展定义"""
 
-    def get_supported_adapters(self) -> Optional[set[Type["Adapter"]]]:  # noqa: UP006
+    def get_supported_adapters(self) -> set[Type["Adapter"]] | None:  # noqa: UP006
         """获取当前已安装的插件支持适配器类列表"""
         if self.supported_adapters is None:
             return None
@@ -77,11 +77,11 @@ class Plugin:
     """导入该插件的插件管理器"""
     matcher: set[type[Matcher]] = field(default_factory=set)
     """插件加载时定义的 `Matcher`"""
-    parent_plugin: Optional["Plugin"] = None
+    parent_plugin: "Plugin | None" = None
     """父插件"""
     sub_plugins: set["Plugin"] = field(default_factory=set)
     """子插件集合"""
-    metadata: Optional[PluginMetadata] = None
+    metadata: PluginMetadata | None = None
     """插件元信息"""
 
     @property

nonebot/plugin/on.py

@@ -11,7 +11,7 @@ from datetime import datetime, timedelta
 import inspect
 import re
 from types import ModuleType
-from typing import Any, Optional, Union
+from typing import Any
 import warnings
 
 from nonebot.adapters import Event
@@ -48,7 +48,7 @@ def store_matcher(matcher: type[Matcher]) -> None:
         plugin.matcher.add(matcher)
 
 
-def get_matcher_plugin(depth: int = 1) -> Optional[Plugin]:  # pragma: no cover
+def get_matcher_plugin(depth: int = 1) -> Plugin | None:  # pragma: no cover
     """获取事件响应器定义所在插件。
 
     **Deprecated**, 请使用 {ref}`nonebot.plugin.on.get_matcher_source` 获取信息。
@@ -63,7 +63,7 @@ def get_matcher_plugin(depth: int = 1) -> Optional[Plugin]:  # pragma: no cover
     return (source := get_matcher_source(depth + 1)) and source.plugin
 
 
-def get_matcher_module(depth: int = 1) -> Optional[ModuleType]:  # pragma: no cover
+def get_matcher_module(depth: int = 1) -> ModuleType | None:  # pragma: no cover
     """获取事件响应器定义所在模块。
 
     **Deprecated**, 请使用 {ref}`nonebot.plugin.on.get_matcher_source` 获取信息。
@@ -78,7 +78,7 @@ def get_matcher_module(depth: int = 1) -> Optional[ModuleType]:  # pragma: no co
     return (source := get_matcher_source(depth + 1)) and source.module
 
 
-def get_matcher_source(depth: int = 0) -> Optional[MatcherSource]:
+def get_matcher_source(depth: int = 0) -> MatcherSource | None:
     """获取事件响应器定义所在源码信息。
 
     参数:
@@ -99,7 +99,7 @@ def get_matcher_source(depth: int = 0) -> Optional[MatcherSource]:
     module_name = (module := inspect.getmodule(frame)) and module.__name__
 
     # matcher defined when plugin loading
-    plugin: Optional["Plugin"] = _current_plugin.get()
+    plugin: Plugin | None = _current_plugin.get()
     # matcher defined when plugin running
     if plugin is None and module_name:
         plugin = get_plugin_by_module_name(module_name)
@@ -113,15 +113,15 @@ def get_matcher_source(depth: int = 0) -> Optional[MatcherSource]:
 
 def on(
     type: str = "",
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    rule: Rule | T_RuleChecker | None = None,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = None,
+    permission: Permission | T_PermissionChecker | None = None,
     *,
-    handlers: Optional[list[Union[T_Handler, Dependent[Any]]]] = None,
+    handlers: list[T_Handler | Dependent[Any]] | None = None,
     temp: bool = False,
-    expire_time: Optional[Union[datetime, timedelta]] = None,
+    expire_time: datetime | timedelta | None = None,
     priority: int = 1,
     block: bool = False,
-    state: Optional[T_State] = None,
+    state: T_State | None = None,
     _depth: int = 0,
 ) -> type[Matcher]:
     """注册一个基础事件响应器，可自定义类型。
@@ -219,8 +219,8 @@ def on_request(*args, _depth: int = 0, **kwargs) -> type[Matcher]:
 
 
 def on_startswith(
-    msg: Union[str, tuple[str, ...]],
+    msg: str | tuple[str, ...],
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    rule: Rule | T_RuleChecker | None = None,
     ignorecase: bool = False,
     _depth: int = 0,
     **kwargs,
@@ -243,8 +243,8 @@ def on_startswith(
 
 
 def on_endswith(
-    msg: Union[str, tuple[str, ...]],
+    msg: str | tuple[str, ...],
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    rule: Rule | T_RuleChecker | None = None,
     ignorecase: bool = False,
     _depth: int = 0,
     **kwargs,
@@ -267,8 +267,8 @@ def on_endswith(
 
 
 def on_fullmatch(
-    msg: Union[str, tuple[str, ...]],
+    msg: str | tuple[str, ...],
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    rule: Rule | T_RuleChecker | None = None,
     ignorecase: bool = False,
     _depth: int = 0,
     **kwargs,
@@ -292,7 +292,7 @@ def on_fullmatch(
 
 def on_keyword(
     keywords: set[str],
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    rule: Rule | T_RuleChecker | None = None,
     _depth: int = 0,
     **kwargs,
 ) -> type[Matcher]:
@@ -313,10 +313,10 @@ def on_keyword(
 
 
 def on_command(
-    cmd: Union[str, tuple[str, ...]],
+    cmd: str | tuple[str, ...],
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    rule: Rule | T_RuleChecker | None = None,
-    aliases: Optional[set[Union[str, tuple[str, ...]]]] = None,
+    aliases: set[str | tuple[str, ...]] | None = None,
-    force_whitespace: Optional[Union[str, bool]] = None,
+    force_whitespace: str | bool | None = None,
     _depth: int = 0,
     **kwargs,
 ) -> type[Matcher]:
@@ -348,10 +348,10 @@ def on_command(
 
 
 def on_shell_command(
-    cmd: Union[str, tuple[str, ...]],
+    cmd: str | tuple[str, ...],
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    rule: Rule | T_RuleChecker | None = None,
-    aliases: Optional[set[Union[str, tuple[str, ...]]]] = None,
+    aliases: set[str | tuple[str, ...]] | None = None,
-    parser: Optional[ArgumentParser] = None,
+    parser: ArgumentParser | None = None,
     _depth: int = 0,
     **kwargs,
 ) -> type[Matcher]:
@@ -386,8 +386,8 @@ def on_shell_command(
 
 def on_regex(
     pattern: str,
-    flags: Union[int, re.RegexFlag] = 0,
+    flags: int | re.RegexFlag = 0,
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    rule: Rule | T_RuleChecker | None = None,
     _depth: int = 0,
     **kwargs,
 ) -> type[Matcher]:
@@ -411,8 +411,8 @@ def on_regex(
 
 
 def on_type(
-    types: Union[type[Event], tuple[type[Event], ...]],
+    types: type[Event] | tuple[type[Event], ...],
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    rule: Rule | T_RuleChecker | None = None,
     *,
     _depth: int = 0,
     **kwargs,
@@ -443,7 +443,7 @@ class _Group:
         """其他传递给 `on` 的参数默认值"""
 
     def _get_final_kwargs(
-        self, update: dict[str, Any], *, exclude: Optional[set[str]] = None
+        self, update: dict[str, Any], *, exclude: set[str] | None = None
     ) -> dict[str, Any]:
         """获取最终传递给 `on` 的参数
 
@@ -477,7 +477,7 @@ class CommandGroup(_Group):
     """
 
     def __init__(
-        self, cmd: Union[str, tuple[str, ...]], prefix_aliases: bool = False, **kwargs
+        self, cmd: str | tuple[str, ...], prefix_aliases: bool = False, **kwargs
     ):
         """命令前缀"""
         super().__init__(**kwargs)
@@ -488,7 +488,7 @@ class CommandGroup(_Group):
     def __repr__(self) -> str:
         return f"CommandGroup(cmd={self.basecmd}, matchers={len(self.matchers)})"
 
-    def command(self, cmd: Union[str, tuple[str, ...]], **kwargs) -> type[Matcher]:
+    def command(self, cmd: str | tuple[str, ...], **kwargs) -> type[Matcher]:
         """注册一个新的命令。新参数将会覆盖命令组默认值
 
         参数:
@@ -515,9 +515,7 @@ class CommandGroup(_Group):
         self.matchers.append(matcher)
         return matcher
 
-    def shell_command(
+    def shell_command(self, cmd: str | tuple[str, ...], **kwargs) -> type[Matcher]:
-        self, cmd: Union[str, tuple[str, ...]], **kwargs
-    ) -> type[Matcher]:
         """注册一个新的 `shell_like` 命令。新参数将会覆盖命令组默认值
 
         参数:
@@ -641,9 +639,7 @@ class MatcherGroup(_Group):
         self.matchers.append(matcher)
         return matcher
 
-    def on_startswith(
+    def on_startswith(self, msg: str | tuple[str, ...], **kwargs) -> type[Matcher]:
-        self, msg: Union[str, tuple[str, ...]], **kwargs
-    ) -> type[Matcher]:
         """注册一个消息事件响应器，并且当消息的**文本部分**以指定内容开头时响应。
 
         参数:
@@ -663,7 +659,7 @@ class MatcherGroup(_Group):
         self.matchers.append(matcher)
         return matcher
 
-    def on_endswith(self, msg: Union[str, tuple[str, ...]], **kwargs) -> type[Matcher]:
+    def on_endswith(self, msg: str | tuple[str, ...], **kwargs) -> type[Matcher]:
         """注册一个消息事件响应器，并且当消息的**文本部分**以指定内容结尾时响应。
 
         参数:
@@ -683,7 +679,7 @@ class MatcherGroup(_Group):
         self.matchers.append(matcher)
         return matcher
 
-    def on_fullmatch(self, msg: Union[str, tuple[str, ...]], **kwargs) -> type[Matcher]:
+    def on_fullmatch(self, msg: str | tuple[str, ...], **kwargs) -> type[Matcher]:
         """注册一个消息事件响应器，并且当消息的**文本部分**与指定内容完全一致时响应。
 
         参数:
@@ -724,9 +720,9 @@ class MatcherGroup(_Group):
 
     def on_command(
         self,
-        cmd: Union[str, tuple[str, ...]],
+        cmd: str | tuple[str, ...],
-        aliases: Optional[set[Union[str, tuple[str, ...]]]] = None,
+        aliases: set[str | tuple[str, ...]] | None = None,
-        force_whitespace: Optional[Union[str, bool]] = None,
+        force_whitespace: str | bool | None = None,
         **kwargs,
     ) -> type[Matcher]:
         """注册一个消息事件响应器，并且当消息以指定命令开头时响应。
@@ -755,9 +751,9 @@ class MatcherGroup(_Group):
 
     def on_shell_command(
         self,
-        cmd: Union[str, tuple[str, ...]],
+        cmd: str | tuple[str, ...],
-        aliases: Optional[set[Union[str, tuple[str, ...]]]] = None,
+        aliases: set[str | tuple[str, ...]] | None = None,
-        parser: Optional[ArgumentParser] = None,
+        parser: ArgumentParser | None = None,
         **kwargs,
     ) -> type[Matcher]:
         """注册一个支持 `shell_like` 解析参数的命令消息事件响应器。
@@ -786,7 +782,7 @@ class MatcherGroup(_Group):
         return matcher
 
     def on_regex(
-        self, pattern: str, flags: Union[int, re.RegexFlag] = 0, **kwargs
+        self, pattern: str, flags: int | re.RegexFlag = 0, **kwargs
     ) -> type[Matcher]:
         """注册一个消息事件响应器，并且当消息匹配正则表达式时响应。
 
@@ -810,7 +806,7 @@ class MatcherGroup(_Group):
         return matcher
 
     def on_type(
-        self, types: Union[type[Event], tuple[type[Event]]], **kwargs
+        self, types: type[Event] | tuple[type[Event]], **kwargs
     ) -> type[Matcher]:
         """注册一个事件响应器，并且当事件为指定类型时响应。
 

nonebot/rule.py

@@ -24,10 +24,8 @@ from typing import (
     IO,
     TYPE_CHECKING,
     NamedTuple,
-    Optional,
     TypedDict,
     TypeVar,
-    Union,
     cast,
     overload,
 )
@@ -61,11 +59,11 @@ T = TypeVar("T")
 
 
 class CMD_RESULT(TypedDict):
-    command: Optional[tuple[str, ...]]
+    command: tuple[str, ...] | None
-    raw_command: Optional[str]
+    raw_command: str | None
-    command_arg: Optional[Message]
+    command_arg: Message | None
-    command_start: Optional[str]
+    command_start: str | None
-    command_whitespace: Optional[str]
+    command_whitespace: str | None
 
 
 class TRIE_VALUE(NamedTuple):
@@ -179,7 +177,7 @@ class StartswithRule:
         return False
 
 
-def startswith(msg: Union[str, tuple[str, ...]], ignorecase: bool = False) -> Rule:
+def startswith(msg: str | tuple[str, ...], ignorecase: bool = False) -> Rule:
     """匹配消息纯文本开头。
 
     参数:
@@ -234,7 +232,7 @@ class EndswithRule:
         return False
 
 
-def endswith(msg: Union[str, tuple[str, ...]], ignorecase: bool = False) -> Rule:
+def endswith(msg: str | tuple[str, ...], ignorecase: bool = False) -> Rule:
     """匹配消息纯文本结尾。
 
     参数:
@@ -288,7 +286,7 @@ class FullmatchRule:
         return False
 
 
-def fullmatch(msg: Union[str, tuple[str, ...]], ignorecase: bool = False) -> Rule:
+def fullmatch(msg: str | tuple[str, ...], ignorecase: bool = False) -> Rule:
     """完全匹配消息。
 
     参数:
@@ -360,7 +358,7 @@ class CommandRule:
     def __init__(
         self,
         cmds: list[tuple[str, ...]],
-        force_whitespace: Optional[Union[str, bool]] = None,
+        force_whitespace: str | bool | None = None,
     ):
         self.cmds = tuple(cmds)
         self.force_whitespace = force_whitespace
@@ -378,9 +376,9 @@ class CommandRule:
 
     async def __call__(
         self,
-        cmd: Optional[tuple[str, ...]] = Command(),
+        cmd: tuple[str, ...] | None = Command(),
-        cmd_arg: Optional[Message] = CommandArg(),
+        cmd_arg: Message | None = CommandArg(),
-        cmd_whitespace: Optional[str] = CommandWhitespace(),
+        cmd_whitespace: str | None = CommandWhitespace(),
     ) -> bool:
         if cmd not in self.cmds:
             return False
@@ -392,8 +390,8 @@ class CommandRule:
 
 
 def command(
-    *cmds: Union[str, tuple[str, ...]],
+    *cmds: str | tuple[str, ...],
-    force_whitespace: Optional[Union[str, bool]] = None,
+    force_whitespace: str | bool | None = None,
 ) -> Rule:
     """匹配消息命令。
 
@@ -456,36 +454,36 @@ class ArgumentParser(ArgParser):
         @overload
         def parse_known_args(
             self,
-            args: Optional[Sequence[Union[str, MessageSegment]]] = None,
+            args: Sequence[str | MessageSegment] | None = None,
             namespace: None = None,
-        ) -> tuple[Namespace, list[Union[str, MessageSegment]]]: ...
+        ) -> tuple[Namespace, list[str | MessageSegment]]: ...
 
         @overload
         def parse_known_args(
-            self, args: Optional[Sequence[Union[str, MessageSegment]]], namespace: T
+            self, args: Sequence[str | MessageSegment] | None, namespace: T
-        ) -> tuple[T, list[Union[str, MessageSegment]]]: ...
+        ) -> tuple[T, list[str | MessageSegment]]: ...
 
         @overload
         def parse_known_args(
             self, *, namespace: T
-        ) -> tuple[T, list[Union[str, MessageSegment]]]: ...
+        ) -> tuple[T, list[str | MessageSegment]]: ...
 
         def parse_known_args(  # pyright: ignore[reportIncompatibleMethodOverride]
             self,
-            args: Optional[Sequence[Union[str, MessageSegment]]] = None,
+            args: Sequence[str | MessageSegment] | None = None,
-            namespace: Optional[T] = None,
+            namespace: T | None = None,
-        ) -> tuple[Union[Namespace, T], list[Union[str, MessageSegment]]]: ...
+        ) -> tuple[Namespace | T, list[str | MessageSegment]]: ...
 
     @overload
     def parse_args(
         self,
-        args: Optional[Sequence[Union[str, MessageSegment]]] = None,
+        args: Sequence[str | MessageSegment] | None = None,
         namespace: None = None,
     ) -> Namespace: ...
 
     @overload
     def parse_args(
-        self, args: Optional[Sequence[Union[str, MessageSegment]]], namespace: T
+        self, args: Sequence[str | MessageSegment] | None, namespace: T
     ) -> T: ...
 
     @overload
@@ -493,29 +491,29 @@ class ArgumentParser(ArgParser):
 
     def parse_args(
         self,
-        args: Optional[Sequence[Union[str, MessageSegment]]] = None,
+        args: Sequence[str | MessageSegment] | None = None,
-        namespace: Optional[T] = None,
+        namespace: T | None = None,
-    ) -> Union[Namespace, T]:
+    ) -> Namespace | T:
         result, argv = self.parse_known_args(args, namespace)
         if argv:
             msg = gettext("unrecognized arguments: %s")
             self.error(msg % " ".join(map(str, argv)))
-        return cast(Union[Namespace, T], result)
+        return cast(Namespace | T, result)
 
     def _parse_optional(
-        self, arg_string: Union[str, MessageSegment]
+        self, arg_string: str | MessageSegment
-    ) -> Optional[tuple[Optional[Action], str, Optional[str]]]:
+    ) -> tuple[Action | None, str, str | None] | None:
         return (
             super()._parse_optional(arg_string) if isinstance(arg_string, str) else None
         )
 
-    def _print_message(self, message: str, file: Optional[IO[str]] = None):  # type: ignore
+    def _print_message(self, message: str, file: IO[str] | None = None):  # type: ignore
         if (msg := parser_message.get(None)) is not None:
             parser_message.set(msg + message)
         else:
             super()._print_message(message, file)
 
-    def exit(self, status: int = 0, message: Optional[str] = None):
+    def exit(self, status: int = 0, message: str | None = None):
         if message:
             self._print_message(message)
         raise ParserExit(status=status, message=parser_message.get(None))
@@ -531,7 +529,7 @@ class ShellCommandRule:
 
     __slots__ = ("cmds", "parser")
 
-    def __init__(self, cmds: list[tuple[str, ...]], parser: Optional[ArgumentParser]):
+    def __init__(self, cmds: list[tuple[str, ...]], parser: ArgumentParser | None):
         self.cmds = tuple(cmds)
         self.parser = parser
 
@@ -551,8 +549,8 @@ class ShellCommandRule:
     async def __call__(
         self,
         state: T_State,
-        cmd: Optional[tuple[str, ...]] = Command(),
+        cmd: tuple[str, ...] | None = Command(),
-        msg: Optional[Message] = CommandArg(),
+        msg: Message | None = CommandArg(),
     ) -> bool:
         if cmd not in self.cmds or msg is None:
             return False
@@ -589,7 +587,7 @@ class ShellCommandRule:
 
 
 def shell_command(
-    *cmds: Union[str, tuple[str, ...]], parser: Optional[ArgumentParser] = None
+    *cmds: str | tuple[str, ...], parser: ArgumentParser | None = None
 ) -> Rule:
     """匹配 `shell_like` 形式的消息命令。
 
@@ -695,7 +693,7 @@ class RegexRule:
             return False
 
 
-def regex(regex: str, flags: Union[int, re.RegexFlag] = 0) -> Rule:
+def regex(regex: str, flags: int | re.RegexFlag = 0) -> Rule:
     """匹配符合正则表达式的消息字符串。
 
     可以通过 {ref}`nonebot.params.RegexStr` 获取匹配成功的字符串，

nonebot/typing.py

@@ -15,9 +15,9 @@ FrontMatter:
 import sys
 import types
 import typing as t
-from typing import TYPE_CHECKING, TypeVar
+from typing import TYPE_CHECKING, TypeAlias, TypeVar, get_args, get_origin
 import typing_extensions as t_ext
-from typing_extensions import ParamSpec, TypeAlias, get_args, get_origin, override
+from typing_extensions import ParamSpec, override
 import warnings
 
 if TYPE_CHECKING:
@@ -43,31 +43,15 @@ def overrides(InterfaceClass: object):
     return override
 
 
-if sys.version_info < (3, 10):
-
-    def type_has_args(type_: type[t.Any]) -> bool:
-        """判断类型是否有参数"""
-        return isinstance(type_, (t._GenericAlias, types.GenericAlias))  # type: ignore
-
-else:
-
 def type_has_args(type_: type[t.Any]) -> bool:
     return isinstance(type_, (t._GenericAlias, types.GenericAlias, types.UnionType))  # type: ignore
 
 
-if sys.version_info < (3, 10):
+def origin_is_union(origin: type[t.Any] | None) -> bool:
-
-    def origin_is_union(origin: t.Optional[type[t.Any]]) -> bool:
-        """判断是否是 Union 类型"""
-        return origin is t.Union
-
-else:
-
-    def origin_is_union(origin: t.Optional[type[t.Any]]) -> bool:
     return origin is t.Union or origin is types.UnionType
 
 
-def origin_is_literal(origin: t.Optional[type[t.Any]]) -> bool:
+def origin_is_literal(origin: type[t.Any] | None) -> bool:
     """判断是否是 Literal 类型"""
     return origin is t.Literal or origin is t_ext.Literal
 
@@ -84,14 +68,12 @@ def all_literal_values(type_: type[t.Any]) -> list[t.Any]:
     return [x for value in _literal_values(type_) for x in all_literal_values(value)]
 
 
-def origin_is_annotated(origin: t.Optional[type[t.Any]]) -> bool:
+def origin_is_annotated(origin: type[t.Any] | None) -> bool:
     """判断是否是 Annotated 类型"""
     return origin is t_ext.Annotated
 
 
-NONE_TYPES = {None, type(None), t.Literal[None], t_ext.Literal[None]}
+NONE_TYPES = {None, type(None), t.Literal[None], t_ext.Literal[None], types.NoneType}  # noqa: PYI061
-if sys.version_info >= (3, 10):
-    NONE_TYPES.add(types.NoneType)
 
 
 def is_none_type(type_: type[t.Any]) -> bool:
@@ -104,6 +86,7 @@ if sys.version_info < (3, 12):
     def is_type_alias_type(type_: type[t.Any]) -> bool:
         """判断是否是 TypeAliasType 类型"""
         return isinstance(type_, t_ext.TypeAliasType)
+
 else:
 
     def is_type_alias_type(type_: type[t.Any]) -> bool:
@@ -132,9 +115,7 @@ _STATE_FLAG = StateFlag()
 T_State: TypeAlias = t.Annotated[dict[t.Any, t.Any], _STATE_FLAG]
 """事件处理状态 State 类型"""
 
-_DependentCallable: TypeAlias = t.Union[
+_DependentCallable: TypeAlias = t.Callable[..., T] | t.Callable[..., t.Awaitable[T]]
-    t.Callable[..., T], t.Callable[..., t.Awaitable[T]]
-]
 
 # driver hooks
 T_BotConnectionHook: TypeAlias = _DependentCallable[t.Any]
@@ -162,7 +143,7 @@ T_CallingAPIHook: TypeAlias = t.Callable[
 ]
 """`bot.call_api` 钩子函数"""
 T_CalledAPIHook: TypeAlias = t.Callable[
-    ["Bot", t.Optional[Exception], str, dict[str, t.Any], t.Any], t.Awaitable[t.Any]
+    ["Bot", Exception | None, str, dict[str, t.Any], t.Any], t.Awaitable[t.Any]
 ]
 """`bot.call_api` 后执行的函数，参数分别为 bot, exception, api, data, result"""
 

nonebot/utils.py

@@ -8,7 +8,14 @@ FrontMatter:
 """
 
 from collections import deque
-from collections.abc import AsyncGenerator, Coroutine, Generator, Mapping, Sequence
+from collections.abc import (
+    AsyncGenerator,
+    Callable,
+    Coroutine,
+    Generator,
+    Mapping,
+    Sequence,
+)
 import contextlib
 from contextlib import AbstractContextManager, asynccontextmanager
 import dataclasses
@@ -18,8 +25,15 @@ import inspect
 import json
 from pathlib import Path
 import re
-from typing import Any, Callable, Generic, Optional, TypeVar, Union, overload
+from typing import (
-from typing_extensions import ParamSpec, get_args, get_origin, override
+    Any,
+    Generic,
+    TypeVar,
+    get_args,
+    get_origin,
+    overload,
+)
+from typing_extensions import ParamSpec, override
 
 import anyio
 import anyio.to_thread
@@ -73,7 +87,7 @@ def deep_update(
 
 
 def lenient_issubclass(
-    cls: Any, class_or_tuple: Union[type[Any], tuple[type[Any], ...]]
+    cls: Any, class_or_tuple: type[Any] | tuple[type[Any], ...]
 ) -> bool:
     """检查 cls 是否是 class_or_tuple 中的一个类型子类并忽略类型错误。"""
     try:
@@ -83,7 +97,7 @@ def lenient_issubclass(
 
 
 def generic_check_issubclass(
-    cls: Any, class_or_tuple: Union[type[Any], tuple[type[Any], ...]]
+    cls: Any, class_or_tuple: type[Any] | tuple[type[Any], ...]
 ) -> bool:
     """检查 cls 是否是 class_or_tuple 中的一个类型子类。
 
@@ -141,7 +155,7 @@ def type_is_complex(type_: type[Any]) -> bool:
     return _type_is_complex_inner(type_) or _type_is_complex_inner(origin)
 
 
-def _type_is_complex_inner(type_: Optional[type[Any]]) -> bool:
+def _type_is_complex_inner(type_: type[Any] | None) -> bool:
     if lenient_issubclass(type_, (str, bytes)):
         return False
 
@@ -212,7 +226,7 @@ async def run_coro_with_catch(
     coro: Coroutine[Any, Any, T],
     exc: tuple[type[Exception], ...],
     return_on_err: None = None,
-) -> Union[T, None]: ...
+) -> T | None: ...
 
 
 @overload
@@ -220,14 +234,14 @@ async def run_coro_with_catch(
     coro: Coroutine[Any, Any, T],
     exc: tuple[type[Exception], ...],
     return_on_err: R,
-) -> Union[T, R]: ...
+) -> T | R: ...
 
 
 async def run_coro_with_catch(
     coro: Coroutine[Any, Any, T],
     exc: tuple[type[Exception], ...],
-    return_on_err: Optional[R] = None,
+    return_on_err: R | None = None,
-) -> Optional[Union[T, R]]:
+) -> T | R | None:
     """运行协程并当遇到指定异常时返回指定值。
 
     参数:
@@ -288,7 +302,7 @@ def path_to_module_name(path: Path) -> str:
 
 
 def resolve_dot_notation(
-    obj_str: str, default_attr: str, default_prefix: Optional[str] = None
+    obj_str: str, default_attr: str, default_prefix: str | None = None
 ) -> Any:
     """解析并导入点分表示法的对象"""
     modulename, _, cls = obj_str.partition(":")
@@ -309,7 +323,7 @@ class classproperty(Generic[T]):
     def __init__(self, func: Callable[[Any], T]) -> None:
         self.func = func
 
-    def __get__(self, instance: Any, owner: Optional[type[Any]] = None) -> T:
+    def __get__(self, instance: Any, owner: type[Any] | None = None) -> T:
         return self.func(type(instance) if owner is None else owner)
 
 
@@ -339,7 +353,7 @@ def logger_wrapper(logger_name: str):
         - exception: 异常信息
     """
 
-    def log(level: str, message: str, exception: Optional[Exception] = None):
+    def log(level: str, message: str, exception: Exception | None = None):
         logger.opt(colors=True, exception=exception).log(
             level, f"<m>{escape_tag(logger_name)}</m> | {message}"
         )

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nonebot2"
-version = "2.4.3"
+version = "2.4.4"
 description = "An asynchronous python bot framework."
 authors = [{ name = "yanyongyu", email = "yyy@nonebot.dev" }]
 license = "MIT"
@@ -13,7 +13,7 @@ classifiers = [
   "Operating System :: OS Independent",
   "Programming Language :: Python :: 3",
 ]
-requires-python = ">=3.9, <4.0"
+requires-python = ">=3.10, <4.0"
 dependencies = [
   "yarl >=1.7.2, <2.0.0",
   "anyio >=4.4.0, <5.0.0",
@@ -42,7 +42,9 @@ all = [
 
 [dependency-groups]
 dev = [
-  "ruff >=0.12.0, <0.13.0",
+  { include-group = "test" },
+  { include-group = "docs" },
+  "ruff >=0.14.0, <0.15.0",
   "nonemoji >=0.1.2, <0.2.0",
   "pre-commit >=4.0.0, <5.0.0",
 ]
@@ -51,11 +53,11 @@ test = [
   "nonebug >=0.4.1, <0.5.0",
   "wsproto >=1.2.0, <2.0.0",
   "werkzeug >=2.3.6, <4.0.0",
-  "pytest-cov >=6.0.0, <7.0.0",
+  "pytest-cov >=7.0.0, <8.0.0",
   "pytest-xdist >=3.0.2, <4.0.0",
   "coverage-conditional-plugin >=0.9.0, <0.10.0",
 ]
-docs = ["nb-autodoc >=1.0.0a5, <2.0.0"]
+docs = ["nb-autodoc >=1.0.3, <2.0.0"]
 pydantic-v1 = ["pydantic >=1.10.0, <2.0.0"]
 pydantic-v2 = ["pydantic >=2.0.0, <3.0.0"]
 
@@ -69,7 +71,6 @@ Funding = "https://afdian.com/@nonebot"
 
 [tool.uv]
 required-version = ">=0.8.0"
-default-groups = ["dev", "test", "docs"]
 conflicts = [[{ group = "pydantic-v1" }, { group = "pydantic-v2" }]]
 
 [tool.uv.build-backend]
@@ -82,7 +83,6 @@ filterwarnings = ["error", "ignore::DeprecationWarning"]
 
 [tool.ruff]
 line-length = 88
-target-version = "py39"
 
 [tool.ruff.format]
 line-ending = "lf"
@@ -125,7 +125,7 @@ mark-parentheses = false
 keep-runtime-typing = true
 
 [tool.pyright]
-pythonVersion = "3.9"
+pythonVersion = "3.10"
 pythonPlatform = "All"
 defineConstant = { PYDANTIC_V2 = true }
 executionEnvironments = [
@@ -143,5 +143,5 @@ reportShadowedImports = false
 disableBytesTypePromotions = true
 
 [build-system]
-requires = ["uv_build >=0.8.3, <0.9.0"]
+requires = ["uv_build >=0.8.3, <0.10.0"]
 build-backend = "uv_build"

tests/.env.example

@@ -1,4 +1,5 @@
 SIMPLE=simple
+int_str=123
 COMPLEX='
 [1, 2, 3]
 '
@@ -10,6 +11,7 @@ NESTED__C__C=3
 NESTED__COMPLEX=[1, 2, 3]
 NESTED_INNER__A=1
 NESTED_INNER__B=2
+ALIAS_SIMPLE=aliased_simple
 OTHER_SIMPLE=simple
 OTHER_NESTED={"a": 1}
 OTHER_NESTED__B=2

tests/conftest.py

@@ -1,10 +1,11 @@
-from collections.abc import Generator
+from collections.abc import Callable, Generator
 from functools import wraps
 import os
 from pathlib import Path
 import sys
 import threading
-from typing import TYPE_CHECKING, Callable, TypeVar
+from types import EllipsisType
+from typing import TYPE_CHECKING, TypeVar
 from typing_extensions import ParamSpec
 
 from nonebug import NONEBOT_INIT_KWARGS
@@ -50,12 +51,12 @@ def anyio_backend(request: pytest.FixtureRequest):
 
 
 def run_once(func: Callable[P, R]) -> Callable[P, R]:
-    result = ...
+    result: R | EllipsisType = ...
 
     @wraps(func)
     def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
         nonlocal result
-        if result is not Ellipsis:
+        if result is not ...:
             return result
 
         result = func(*args, **kwargs)

tests/fake_server.py

@@ -1,7 +1,7 @@
 import base64
 import json
 import socket
-from typing import TypeVar, Union
+from typing import TypeVar
 
 from werkzeug import Request, Response
 from werkzeug.datastructures import MultiDict
@@ -36,7 +36,7 @@ def json_safe(string, content_type="application/octet-stream") -> str:
         ).decode("utf-8")
 
 
-def flattern(d: "MultiDict[K, V]") -> dict[K, Union[V, list[V]]]:
+def flattern(d: "MultiDict[K, V]") -> dict[K, V | list[V]]:
     return {k: v[0] if len(v) == 1 else v for k, v in d.to_dict(flat=False).items()}
 
 

tests/plugins.legacy.toml

@@ -0,0 +1,3 @@
+[tool.nonebot]
+plugins = []
+plugin_dirs = []

tests/plugins.toml

@@ -1,3 +1,5 @@
 [tool.nonebot]
-plugins = []
 plugin_dirs = []
+
+[tool.nonebot.plugins]
+"@local" = []

tests/plugins/param/param_bot.py

@@ -1,4 +1,4 @@
-from typing import TypeVar, Union
+from typing import TypeVar
 
 from nonebot.adapters import Bot
 
@@ -28,7 +28,7 @@ async def sub_bot(b: FooBot) -> FooBot:
 class BarBot(Bot): ...
 
 
-async def union_bot(b: Union[FooBot, BarBot]) -> Union[FooBot, BarBot]:
+async def union_bot(b: FooBot | BarBot) -> FooBot | BarBot:
     return b
 
 
@@ -46,4 +46,4 @@ async def generic_bot_none(b: CB) -> CB:
     return b
 
 
-async def not_bot(b: Union[int, Bot]): ...
+async def not_bot(b: int | Bot): ...

tests/plugins/param/param_event.py

@@ -1,4 +1,4 @@
-from typing import TypeVar, Union
+from typing import TypeVar
 
 from nonebot.adapters import Event, Message
 from nonebot.params import EventMessage, EventPlainText, EventToMe, EventType
@@ -29,7 +29,7 @@ async def sub_event(e: FooEvent) -> FooEvent:
 class BarEvent(Event): ...
 
 
-async def union_event(e: Union[FooEvent, BarEvent]) -> Union[FooEvent, BarEvent]:
+async def union_event(e: FooEvent | BarEvent) -> FooEvent | BarEvent:
     return e
 
 
@@ -47,7 +47,7 @@ async def generic_event_none(e: CE) -> CE:
     return e
 
 
-async def not_event(e: Union[int, Event]): ...
+async def not_event(e: int | Event): ...
 
 
 async def event_type(t: str = EventType()) -> str:

tests/plugins/param/param_exception.py

@@ -1,7 +1,4 @@
-from typing import Union
+async def exc(e: Exception, x: ValueError | TypeError) -> Exception:
-
-
-async def exc(e: Exception, x: Union[ValueError, TypeError]) -> Exception:
     assert e == x
     return e
 

tests/plugins/param/param_matcher.py

@@ -1,4 +1,4 @@
-from typing import Any, TypeVar, Union
+from typing import Any, TypeVar
 
 from nonebot.adapters import Event
 from nonebot.matcher import Matcher
@@ -36,8 +36,8 @@ class BarMatcher(Matcher): ...
 
 
 async def union_matcher(
-    m: Union[FooMatcher, BarMatcher],
+    m: FooMatcher | BarMatcher,
-) -> Union[FooMatcher, BarMatcher]:
+) -> FooMatcher | BarMatcher:
     return m
 
 
@@ -55,7 +55,7 @@ async def generic_matcher_none(m: CM) -> CM:
     return m
 
 
-async def not_matcher(m: Union[int, Matcher]): ...
+async def not_matcher(m: int | Matcher): ...
 
 
 async def receive(e: Event = Received("test")) -> Event:

tests/plugins/param/priority.py

@@ -1,5 +1,3 @@
-from typing import Optional
-
 from nonebot.adapters import Bot, Event, Message
 from nonebot.matcher import Matcher
 from nonebot.params import Arg, Depends
@@ -12,11 +10,11 @@ def dependency():
 
 async def complex_priority(
     sub: int = Depends(dependency),
-    bot: Optional[Bot] = None,
+    bot: Bot | None = None,
-    event: Optional[Event] = None,
+    event: Event | None = None,
     state: T_State = {},
-    matcher: Optional[Matcher] = None,
+    matcher: Matcher | None = None,
     arg: Message = Arg(),
-    exception: Optional[Exception] = None,
+    exception: Exception | None = None,
     default: int = 1,
 ): ...

tests/test_adapters/test_adapter.py

@@ -1,5 +1,4 @@
 from contextlib import asynccontextmanager
-from typing import Optional
 
 from nonebug import App
 import pytest
@@ -19,8 +18,8 @@ from utils import FakeAdapter
 
 @pytest.mark.anyio
 async def test_adapter_connect(app: App, driver: Driver):
-    last_connect_bot: Optional[Bot] = None
+    last_connect_bot: Bot | None = None
-    last_disconnect_bot: Optional[Bot] = None
+    last_disconnect_bot: Bot | None = None
 
     def _fake_bot_connect(bot: Bot):
         nonlocal last_connect_bot
@@ -75,8 +74,8 @@ async def test_adapter_connect(app: App, driver: Driver):
     indirect=True,
 )
 def test_adapter_server(driver: Driver):
-    last_http_setup: Optional[HTTPServerSetup] = None
+    last_http_setup: HTTPServerSetup | None = None
-    last_ws_setup: Optional[WebSocketServerSetup] = None
+    last_ws_setup: WebSocketServerSetup | None = None
 
     def _fake_setup_http_server(setup: HTTPServerSetup):
         nonlocal last_http_setup
@@ -142,7 +141,7 @@ def test_adapter_server(driver: Driver):
     indirect=True,
 )
 async def test_adapter_http_client(driver: Driver):
-    last_request: Optional[Request] = None
+    last_request: Request | None = None
 
     async def _fake_request(request: Request):
         nonlocal last_request
@@ -190,7 +189,7 @@ async def test_adapter_http_client(driver: Driver):
 )
 async def test_adapter_websocket_client(driver: Driver):
     _fake_ws = object()
-    _last_request: Optional[Request] = None
+    _last_request: Request | None = None
 
     @asynccontextmanager
     async def _fake_websocket(setup: Request):

tests/test_adapters/test_bot.py

@@ -1,4 +1,4 @@
-from typing import Any, Optional
+from typing import Any
 
 import anyio
 from nonebug import App
@@ -123,7 +123,7 @@ async def test_bot_called_api_hook_simple(app: App):
 
     async def called_api_hook(
         bot: Bot,
-        exception: Optional[Exception],
+        exception: Exception | None,
         api: str,
         data: dict[str, Any],
         result: Any,
@@ -155,7 +155,7 @@ async def test_bot_called_api_hook_mock(app: App):
 
     async def called_api_hook(
         bot: Bot,
-        exception: Optional[Exception],
+        exception: Exception | None,
         api: str,
         data: dict[str, Any],
         result: Any,
@@ -201,7 +201,7 @@ async def test_bot_called_api_hook_multi_mock(app: App):
 
     async def called_api_hook1(
         bot: Bot,
-        exception: Optional[Exception],
+        exception: Exception | None,
         api: str,
         data: dict[str, Any],
         result: Any,
@@ -214,7 +214,7 @@ async def test_bot_called_api_hook_multi_mock(app: App):
 
     async def called_api_hook2(
         bot: Bot,
-        exception: Optional[Exception],
+        exception: Exception | None,
         api: str,
         data: dict[str, Any],
         result: Any,

tests/test_broadcast.py

@@ -1,5 +1,4 @@
 import sys
-from typing import Optional
 
 from nonebug import App
 import pytest
@@ -326,7 +325,7 @@ async def test_run_postprocessor(app: App, monkeypatch: pytest.MonkeyPatch):
             event: Event,
             state: T_State,
             matcher: Matcher,
-            exception: Optional[Exception],
+            exception: Exception | None,
             sub: int = Depends(_dependency),
             default: int = 1,
         ):

tests/test_compat.py

@@ -1,5 +1,5 @@
 from dataclasses import dataclass
-from typing import Annotated, Any, Optional
+from typing import Annotated, Any
 
 from pydantic import BaseModel, ValidationError
 import pytest
@@ -144,7 +144,7 @@ def test_validate_json():
         test3: bool
         test4: dict
         test5: list
-        test6: Optional[int]
+        test6: int | None
 
     assert type_validate_json(
         TestModel,

tests/test_config.py

@@ -1,9 +1,9 @@
-from typing import TYPE_CHECKING, Optional, Union
+from typing import TYPE_CHECKING
 
 from pydantic import BaseModel, Field
 import pytest
 
-from nonebot.compat import PYDANTIC_V2
+from nonebot.compat import PYDANTIC_V2, LegacyUnionField
 from nonebot.config import DOTENV_TYPE, BaseSettings, SettingsConfig, SettingsError
 
 
@@ -16,8 +16,8 @@ class Simple(BaseModel):
 
 class Example(BaseSettings):
     if TYPE_CHECKING:
-        _env_file: Optional[DOTENV_TYPE] = ".env", ".env.example"
+        _env_file: DOTENV_TYPE | None = ".env", ".env.example"
-        _env_nested_delimiter: Optional[str] = "__"
+        _env_nested_delimiter: str | None = "__"
 
     if PYDANTIC_V2:
         model_config = SettingsConfig(
@@ -32,11 +32,13 @@ class Example(BaseSettings):
             env_nested_delimiter = "__"
 
     simple: str = ""
+    int_str: int | str = LegacyUnionField(default="")
     complex: list[int] = Field(default=[1])
-    complex_none: Optional[list[int]] = None
+    complex_none: list[int] | None = None
-    complex_union: Union[int, list[int]] = 1
+    complex_union: int | list[int] = 1
     nested: Simple = Simple()
     nested_inner: Simple = Simple()
+    aliased_simple: str = Field(default="", alias="alias_simple")
 
 
 class ExampleWithoutDelimiter(Example):
@@ -61,6 +63,8 @@ def test_config_with_env():
     config = Example(_env_file=(".env", ".env.example"))
     assert config.simple == "simple"
 
+    assert config.int_str == 123
+
     assert config.complex == [1, 2, 3]
 
     assert config.complex_none is None
@@ -85,6 +89,8 @@ def test_config_with_env():
     with pytest.raises(AttributeError):
         config.nested_inner__b
 
+    assert config.aliased_simple == "aliased_simple"
+
     assert config.common_config == "common"
 
     assert config.other_simple == "simple"

tests/test_driver.py

@@ -1,7 +1,8 @@
 from http.cookies import SimpleCookie
 import json
-from typing import Any, Optional
+from typing import Any
 
+from aiohttp import ClientSession, ClientWebSocketResponse, WSMessage, WSMsgType
 import anyio
 from nonebug import App
 import pytest
@@ -21,6 +22,7 @@ from nonebot.drivers import (
     WebSocketClientMixin,
     WebSocketServerSetup,
 )
+from nonebot.drivers.aiohttp import WebSocket as AiohttpWebSocket
 from nonebot.exception import WebSocketClosed
 from nonebot.params import Depends
 from utils import FakeAdapter
@@ -171,7 +173,7 @@ async def test_websocket_server(app: App, driver: Driver):
 async def test_cross_context(app: App, driver: Driver):
     assert isinstance(driver, ASGIMixin)
 
-    ws: Optional[WebSocket] = None
+    ws: WebSocket | None = None
     ws_ready = anyio.Event()
     ws_should_close = anyio.Event()
 
@@ -627,6 +629,42 @@ async def test_websocket_client(driver: Driver, server_url: URL):
     await anyio.sleep(1)
 
 
+@pytest.mark.anyio
+@pytest.mark.parametrize(
+    ("msg_type"),
+    [
+        pytest.param("CLOSE", id="aiohttp-close"),
+        pytest.param("CLOSING", id="aiohttp-closing"),
+        pytest.param("CLOSED", id="aiohttp-closed"),
+    ],
+)
+async def test_aiohttp_websocket_close_frame(msg_type: str) -> None:
+    class DummyWS(ClientWebSocketResponse):
+        def __init__(self) -> None:
+            pass
+
+        @property
+        def close_code(self) -> None:
+            return None
+
+        @property
+        def closed(self) -> bool:
+            return True
+
+        async def receive(self, timeout: float | None = None) -> WSMessage:  # noqa: ASYNC109
+            return WSMessage(type=WSMsgType[msg_type], data=None, extra=None)
+
+    async with ClientSession() as session:
+        ws = AiohttpWebSocket(
+            request=Request("GET", "ws://example.com"),
+            session=session,
+            websocket=DummyWS(),
+        )
+
+        with pytest.raises(WebSocketClosed, match=r"code=1006"):
+            await ws.receive()
+
+
 @pytest.mark.parametrize(
     ("driver", "driver_type"),
     [

tests/test_param.py

@@ -42,6 +42,11 @@ UNKNOWN_PARAM = "Unknown parameter"
 
 
 @pytest.mark.anyio
+@pytest.mark.xfail(
+    ((3, 13) <= sys.version_info < (3, 13, 8))
+    or ((3, 14) <= sys.version_info < (3, 14, 1)),
+    reason="CPython Bug, see python/cpython#137317, python/cpython#137862",
+)
 async def test_depend(app: App):
     from plugins.param.param_depend import (
         ClassDependency,

tests/test_permission.py

@@ -1,5 +1,3 @@
-from typing import Optional
-
 from nonebug import App
 import pytest
 
@@ -138,7 +136,7 @@ async def test_superuser(app: App, type: str, user_id: str, expected: bool):
     ],
 )
 async def test_user(
-    app: App, session_ids: tuple[str, ...], session_id: Optional[str], expected: bool
+    app: App, session_ids: tuple[str, ...], session_id: str | None, expected: bool
 ):
     dependent = next(iter(USER(*session_ids).checkers))
     checker = dependent.call

tests/test_plugin/test_get.py

@@ -1,4 +1,5 @@
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
+import pytest
 
 import nonebot
 from nonebot.plugin import PluginManager, _managers
@@ -67,3 +68,27 @@ def test_get_plugin_config():
     config = nonebot.get_plugin_config(Config)
     assert isinstance(config, Config)
     assert config.plugin_config == 1
+
+
+def test_get_plugin_config_with_env(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("PLUGIN_CONFIG_ONE", "no_dummy_val")
+    monkeypatch.setenv("PLUGIN_SUB_CONFIG__TWO", "two")
+    monkeypatch.setenv("PLUGIN_CFG_THREE", "33")
+    monkeypatch.setenv("CONFIG_FROM_INIT", "impossible")
+
+    class SubConfig(BaseModel):
+        two: str = "dummy_val"
+
+    class Config(BaseModel):
+        plugin_config: int
+        plugin_config_one: str = "dummy_val"
+        plugin_sub_config: SubConfig = Field(default_factory=SubConfig)
+        plugin_config_three: int = Field(default=3, alias="plugin_cfg_three")
+        config_from_init: str = "dummy_val"
+
+    config = nonebot.get_plugin_config(Config)
+    assert config.plugin_config == 1
+    assert config.plugin_config_one == "no_dummy_val"
+    assert config.plugin_sub_config.two == "two"
+    assert config.plugin_config_three == 33
+    assert config.config_from_init == "init"

tests/test_plugin/test_load.py

@@ -1,8 +1,9 @@
+from collections.abc import Callable
 from dataclasses import asdict
 from functools import wraps
 from pathlib import Path
 import sys
-from typing import Callable, TypeVar
+from typing import TypeVar
 from typing_extensions import ParamSpec
 
 import pytest
@@ -93,6 +94,8 @@ def test_load_json():
 
 @_recover
 def test_load_toml():
+    nonebot.load_from_toml("./plugins.legacy.toml")
+
     nonebot.load_from_toml("./plugins.toml")
 
     with pytest.raises(ValueError, match="Cannot find"):

tests/test_plugin/test_on.py

@@ -1,4 +1,4 @@
-from typing import Callable, Optional
+from collections.abc import Callable
 
 import pytest
 
@@ -103,7 +103,7 @@ from nonebot.typing import T_RuleChecker
 )
 def test_on(
     matcher_name: str,
-    pre_rule_factory: Optional[Callable[[type[Event]], T_RuleChecker]],
+    pre_rule_factory: Callable[[type[Event]], T_RuleChecker] | None,
     has_permission: bool,
 ):
     import plugins.plugin.matchers as module

tests/test_rule.py

@@ -1,6 +1,5 @@
 import re
 from re import Match
-from typing import Optional, Union
 
 from nonebug import App
 import pytest
@@ -163,10 +162,10 @@ async def test_trie(app: App):
     ],
 )
 async def test_startswith(
-    msg: Union[str, tuple[str, ...]],
+    msg: str | tuple[str, ...],
     ignorecase: bool,
     type: str,
-    text: Optional[str],
+    text: str | None,
     expected: bool,
 ):
     test_startswith = startswith(msg, ignorecase)
@@ -203,10 +202,10 @@ async def test_startswith(
     ],
 )
 async def test_endswith(
-    msg: Union[str, tuple[str, ...]],
+    msg: str | tuple[str, ...],
     ignorecase: bool,
     type: str,
-    text: Optional[str],
+    text: str | None,
     expected: bool,
 ):
     test_endswith = endswith(msg, ignorecase)
@@ -243,10 +242,10 @@ async def test_endswith(
     ],
 )
 async def test_fullmatch(
-    msg: Union[str, tuple[str, ...]],
+    msg: str | tuple[str, ...],
     ignorecase: bool,
     type: str,
-    text: Optional[str],
+    text: str | None,
     expected: bool,
 ):
     test_fullmatch = fullmatch(msg, ignorecase)
@@ -281,7 +280,7 @@ async def test_fullmatch(
 async def test_keyword(
     kws: tuple[str, ...],
     type: str,
-    text: Optional[str],
+    text: str | None,
     expected: bool,
 ):
     test_keyword = keyword(*kws)
@@ -324,10 +323,10 @@ async def test_keyword(
 )
 async def test_command(
     cmds: tuple[tuple[str, ...]],
-    force_whitespace: Optional[Union[str, bool]],
+    force_whitespace: str | bool | None,
     cmd: tuple[str, ...],
-    whitespace: Optional[str],
+    whitespace: str | None,
-    arg_text: Optional[str],
+    arg_text: str | None,
     expected: bool,
 ):
     test_command = command(*cmds, force_whitespace=force_whitespace)
@@ -492,9 +491,9 @@ async def test_shell_command():
 async def test_regex(
     pattern: str,
     type: str,
-    text: Optional[str],
+    text: str | None,
     expected: bool,
-    matched: Optional[Match[str]],
+    matched: Match[str] | None,
 ):
     test_regex = regex(pattern)
     dependent = next(iter(test_regex.checkers))
@@ -507,7 +506,7 @@ async def test_regex(
     event = make_fake_event(_type=type, _message=message)()
     state = {}
     assert await dependent(event=event, state=state) == expected
-    result: Optional[Match[str]] = state.get(REGEX_MATCHED)
+    result: Match[str] | None = state.get(REGEX_MATCHED)
     if matched is None:
         assert result is None
     else:

tests/test_utils.py

@@ -23,7 +23,8 @@ def test_loguru_escape_tag():
 def test_generic_check_issubclass():
     assert generic_check_issubclass(int, (int, float))
     assert not generic_check_issubclass(str, (int, float))
-    assert generic_check_issubclass(Union[int, float, None], (int, float))
+    assert generic_check_issubclass(Union[int, float, None], (int, float))  # noqa: UP007
+    assert generic_check_issubclass(int | float | None, (int, float))
     assert generic_check_issubclass(Literal[1, 2, 3], int)
     assert not generic_check_issubclass(Literal[1, 2, "3"], int)
     assert generic_check_issubclass(List[int], list)  # noqa: UP006

tests/utils.py

@@ -1,5 +1,4 @@
 from collections.abc import Iterable, Mapping
-from typing import Optional, Union
 from typing_extensions import override
 
 from pydantic import create_model
@@ -60,7 +59,7 @@ class FakeMessage(Message[FakeMessageSegment]):
 
     @staticmethod
     @override
-    def _construct(msg: Union[str, Iterable[Mapping]]):
+    def _construct(msg: str | Iterable[Mapping]):
         if isinstance(msg, str):
             yield FakeMessageSegment.text(msg)
         else:
@@ -69,21 +68,19 @@ class FakeMessage(Message[FakeMessageSegment]):
         return
 
     @override
-    def __add__(
+    def __add__(self, other: str | FakeMessageSegment | Iterable[FakeMessageSegment]):
-        self, other: Union[str, FakeMessageSegment, Iterable[FakeMessageSegment]]
-    ):
         other = escape_text(other) if isinstance(other, str) else other
         return super().__add__(other)
 
 
 def make_fake_event(
-    _base: Optional[type[Event]] = None,
+    _base: type[Event] | None = None,
     _type: str = "message",
     _name: str = "test",
     _description: str = "test",
-    _user_id: Optional[str] = "test",
+    _user_id: str | None = "test",
-    _session_id: Optional[str] = "test",
+    _session_id: str | None = "test",
-    _message: Optional[Message] = None,
+    _message: Message | None = None,
     _to_me: bool = True,
     **fields,
 ) -> type[Event]:

tests/uv.lock

@@ -0,0 +1,3 @@
+version = 1
+revision = 3
+requires-python = ">=3.12"

website/docs/advanced/plugin-info.md

@@ -50,11 +50,11 @@ __plugin_meta__ = PluginMetadata(
 
 - `type`：插件类别，发布插件必填。当前有效类别有：`library`（为其他插件编写提供功能），`application`（向机器人用户提供功能）；
 - `homepage`：插件项目主页，发布插件必填；
-- `config`：插件的[配置类](../appendices/config.mdx#插件配置)，如无配置类可不填；
+- `config`：插件的[配置类](../appendices/config.mdx#插件配置)，发布插件时如有配置类则必须填写；
-- `supported_adapters`：支持的适配器模块名集合，若插件可以保证兼容所有适配器（即仅使用基本适配器功能）可不填写；
+- `supported_adapters`：支持的适配器模块名集合，若插件只使用了 NoneBot 基本抽象，应显式填写 `None`；
 - `extra`：一个字典，可以用于存储任意信息。其他插件可以通过约定 `extra` 字典的键名来达成收集某些特殊信息的目的。
 
-请注意，这里的**插件名称**是供使用者或机器人用户查看的，与插件索引名称无关。**插件索引名称（插件模块名称）**仅用于 NoneBot 插件系统**内部索引**。
+请注意，这里的**插件名称**是供使用者或机器人用户查看的人类可读名称，与插件索引名称无关。**插件索引名称（插件模块名称）**仅用于 NoneBot 插件系统**内部索引**。
 
 ## 获取插件信息
 

website/docs/appendices/config.mdx

@@ -84,7 +84,7 @@ export CUSTOM_CONFIG='config in environment variables'
 那最终 NoneBot 所读取的内容为环境变量中的内容，即 `config in environment variables`。
 
 :::caution 注意
-NoneBot 不会自发读取未被定义的配置项的环境变量，如果需要读取某一环境变量需要在 dotenv 配置文件中进行声明。
+如果一个环境变量既不是 NoneBot 的[**内置配置项**](#内置配置项)，也不是任何插件所定义的[**插件配置**](#插件配置)，那么 NoneBot 不会自发读取该环境变量，需要在 dotenv 配置文件中先行声明。
 :::
 
 ### dotenv 配置文件
@@ -242,11 +242,17 @@ weather = on_command(
 
 这种方式可以简洁、高效地读取配置项，同时也可以设置默认值或者在运行时对配置项进行合法性检查，防止由于配置项导致的插件出错等情况出现。
 
-:::tip 提示
+:::tip 可配置的事件响应优先级
 发布插件应该为自身的事件响应器提供可配置的优先级，以便插件使用者可以自定义多个插件间的响应顺序。
 :::
 
-由于插件配置项是从全局配置中读取的，通常我们需要在配置项名称前面添加前缀名，以防止配置项冲突。例如在上方的示例中，我们就添加了配置项前缀 `weather_`。但是这样会导致在使用配置项时过长的变量名，因此我们可以使用 `pydantic` 的 `alias` 或者通过配置 scope 来简化配置项名称。这里我们以 scope 配置为例：
+:::tip 插件配置获取逻辑
+无论是否在 dotenv 文件中声明了插件配置项，使用 `get_plugin_config` 获取插件配置模型中定义的配置项时都遵循[**配置项的加载**](#配置项的加载)一节中的优先级顺序进行读取。
+:::
+
+### 避免插件配置名称冲突
+
+由于插件配置项是从全局配置和环境变量中读取的，通常我们需要在配置项名称前面添加前缀名，以防止配置项冲突。例如在上方的示例中，我们就添加了配置项前缀 `weather_`。但是这样会导致使用配置项时变量名过长，此时我们可以使用 `pydantic` 的 `alias` 或者通过配置 scope 来简化配置项名称。这里我们以 scope 配置为例：
 
 ```python title=weather/config.py
 from pydantic import BaseModel

website/docs/best-practice/alconna/command.md

@@ -289,7 +289,6 @@ opt2 = Option("--foo", default=OptionResult(value=False, args={"bar": 1}))
 `Arparma` 有如下属性：
 
 - 调试类
-
   - matched: 是否匹配成功
   - error_data: 解析失败时剩余的数据
   - error_info: 解析失败时的异常内容

website/docs/best-practice/alconna/matcher.mdx

@@ -150,7 +150,7 @@ async def handle(
 
 - `xxx: CommandResult`
 - `xxx: Arparma`：命令的[解析结果](./command.md#解析结果)
-- `xxx: Duplication`：命令的解析结果的 [`Duplication`](./command.md#Duplication)
+- `xxx: Duplication`：命令的解析结果的 [`Duplication`](./command.md#duplication)
 - `xxx: Alconna`：命令的源命令
 - `<key>: Match[<type>]`：上述的匹配项，使用 `key` 作为查询路径
 - `xxx: Query[<type>] = Query(<path>, default)`：上述的查询项，必需声明默认值以设置查询路径 `path`

website/docs/best-practice/alconna/uniseg/utils.mdx

@@ -159,7 +159,7 @@ async def _(target: MsgTarget):
 
 事实上，构造 `Target` 对象时，`self_id`, `scope`, `adapter` 和 `platform` 都会参与到 `selector` 的构造中。
 
-::tip
+:::tip
 
 你其实可以使用 `Target` 来帮你筛选 `Bot` 对象：
 

website/docs/best-practice/deployment.mdx

@@ -219,6 +219,7 @@ jobs:
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
             type=sha
+            type=raw,value=latest
 
       - name: Build and Publish
         uses: docker/build-push-action@v4

website/docs/best-practice/htmlkit-render.md

@@ -0,0 +1,229 @@
+---
+sidebar_position: 8
+description: 轻量化 HTML 绘图
+---
+
+# 轻量化 HTML 绘图
+
+图片是机器人交互中不可或缺的一部分，对于信息展示的直观性、美观性有很大的作用。
+基于 PIL 直接绘制图片具有良好的性能和存储开销，但是难以调试、维护过程式的绘图代码。
+使用浏览器渲染类插件可以方便地绘制网页，且能够直接通过 JS 对网页效果进行编程，但是它占用的存储和内存空间相对可观。
+
+NoneBot 提供的 `nonebot-plugin-htmlkit` 提供了另一种基于 HTML 和 CSS 语法的轻量化绘图选择：它基于 `litehtml` 解析库，无须安装额外的依赖即可使用，没有进程间通信带来的额外开销，且在支持 `webp` `avif` 等丰富图片格式的前提下，安装用的 wheel 文件大小仅有约 10 MB。
+
+作为粗略的性能参考，在一台 Ryzen 7 9700X 的 Windows 电脑上，渲染 [PEP 7](https://peps.python.org/pep-0007/) 的 HTML 页面（分辨率为 800x5788，大小约 1.4MB，从本地文件系统读取 CSS）大约需要 100ms，每个渲染任务内存最高占用约为 40MB.
+
+## 安装插件
+
+在使用前请先安装 `nonebot-plugin-htmlkit` 插件至项目环境中，可参考[获取商店插件](../tutorial/store.mdx#安装插件)来了解并选择安装插件的方式。如：
+
+在**项目目录**下执行以下命令：
+
+```bash
+nb plugin install nonebot-plugin-htmlkit
+```
+
+`nonebot-plugin-htmlkit` 插件目前兼容以下系统架构：
+
+- Windows x64
+- macOS arm64（M-系列芯片）
+- Linux x64 （非 Alpine 等 musl 系发行版）
+- Linux arm64 （非 Alpine 等 musl 系发行版）
+
+:::caution 访问网络内容
+
+如果需要访问网络资源（如 http(s) 网页内容），NoneBot 需要客户端型驱动器（Forward）。内置的驱动器有 `~httpx` 与 `~aiohttp`。
+
+详见[选择驱动器](../advanced/driver.md)。
+
+:::
+
+## 使用插件
+
+### 加载插件
+
+在使用本插件前同样需要使用 `require` 方法进行**加载**并**导入**需要使用的方法，可参考 [跨插件访问](../advanced/requiring.md) 一节进行了解，如：
+
+```python
+from nonebot import require
+
+require("nonebot_plugin_htmlkit")
+
+from nonebot_plugin_htmlkit import html_to_pic, md_to_pic, template_to_pic, text_to_pic
+```
+
+插件会自动使用[配置中的参数](#配置-fontconfig)初始化 `fontconfig` 以提供字体查找功能。
+
+### 渲染 API
+
+`nonebot-plugin-htmlkit` 主要提供以下**异步**渲染函数：
+
+#### html_to_pic
+
+```python
+async def html_to_pic(
+    html: str,
+    *,
+    base_url: str = "",
+    dpi: float = 144.0,
+    max_width: float = 800.0,
+    device_height: float = 600.0,
+    default_font_size: float = 12.0,
+    font_name: str = "sans-serif",
+    allow_refit: bool = True,
+    image_format: Literal["png", "jpeg"] = "png",
+    jpeg_quality: int = 100,
+    lang: str = "zh",
+    culture: str = "CN",
+    img_fetch_fn: ImgFetchFn = combined_img_fetcher,
+    css_fetch_fn: CSSFetchFn = combined_css_fetcher,
+    urljoin_fn: Callable[[str, str], str] = urllib3.parse.urljoin,
+) -> bytes:
+    ...
+```
+
+最核心的渲染函数。
+
+`base_url` 和 `urljoin_fn` 控制着传入 `image_fetch_fn` 和 `css_fetch_fn` 回调的 url 内容。
+
+`allow_refit` 如果为真，渲染时会自动缩小产出图片的宽度到最适合的宽度，否则必定产出 `max_width` 宽度的图片。
+
+`max_width` 与 `device_height` 会在 `@media` 判断中被使用。
+
+`img_fetch_fn` 预期为一个异步可调用对象（函数），接收图片 url 并返回对应 url 的 jpeg 或 png 二进制数据（`bytes`），可在拒绝加载时返回 `None`.
+
+`css_fetch_fn` 预期为一个异步可调用对象（函数），接收目标 CSS url 并返回对应 url 的 CSS 文本（`str`），可在拒绝加载时返回 `None`.
+
+以下为辅助的封装函数，关键字参数若未特殊说明均与 `html_to_pic` 含义相同。
+
+#### text_to_pic
+
+```python
+async def text_to_pic(
+    text: str,
+    css_path: str = "",
+    *,
+    max_width: int = 500,
+    allow_refit: bool = True,
+    image_format: Literal["png", "jpeg"] = "png",
+    jpeg_quality: int = 100,
+) -> bytes:
+    ...
+```
+
+可用于渲染多行文本。
+
+`text` 会被放置于 `<div id="main" class="main-box"> <div class="text">` 中，可据此编写 CSS 来改变文本表现。
+
+#### md_to_pic
+
+```python
+async def md_to_pic(
+    md: str = "",
+    md_path: str = "",
+    css_path: str = "",
+    *,
+    max_width: int = 500,
+    img_fetch_fn: ImgFetchFn = combined_img_fetcher,
+    allow_refit: bool = True,
+    image_format: Literal["png", "jpeg"] = "png",
+    jpeg_quality: int = 100,
+) -> bytes:
+    ...
+```
+
+可用于渲染 Markdown 文本。默认为 GitHub Markdown Light 风格，支持基于 `pygments` 的代码高亮。
+
+`md` 和 `md_path` 二选一，前者设置时应为 Markdown 的文本，后者设置时应为指向 Markdown 文本文件的路径。
+
+#### template_to_pic
+
+```python
+async def template_to_pic(
+    template_path: str | PathLike[str] | Sequence[str | PathLike[str]],
+    template_name: str,
+    templates: Mapping[Any, Any],
+    filters: None | Mapping[str, Any] = None,
+    *,
+    max_width: int = 500,
+    device_height: int = 600,
+    base_url: str | None = None,
+    img_fetch_fn: ImgFetchFn = combined_img_fetcher,
+    css_fetch_fn: CSSFetchFn = combined_css_fetcher,
+    allow_refit: bool = True,
+    image_format: Literal["png", "jpeg"] = "png",
+    jpeg_quality: int = 100,
+) -> bytes:
+    ...
+```
+
+渲染 jinja2 模板。
+
+`template_path` 为 jinja2 环境的路径，`template_name` 是环境中要加载模板的名字，`templates` 为传入模板的参数，`filters` 为过滤器名 -> 自定义过滤器的映射。
+
+### 控制外部资源获取
+
+通过传入 `img_fetch_fn` 与 `css_fetch_fn`，我们可以在实际访问资源前进行审查，修改资源的来源，或是对 IO 操作进行缓存。
+
+`img_fetch_fn` 预期为一个异步可调用对象（函数），接收图片 url 并返回对应 url 的 jpeg 或 png 二进制数据（`bytes`），可在拒绝加载时返回 `None`.
+
+`css_fetch_fn` 预期为一个异步可调用对象（函数），接收目标 CSS url 并返回对应 url 的 CSS 文本（`str`），可在拒绝加载时返回 `None`.
+
+如果你想要禁用外部资源加载/只从文件系统加载/只从网络加载，可以使用 `none_fetcher` `filesystem_***_fetcher` `network_***_fetcher`。
+
+默认的 fetcher 行为（对于 `file://` 从文件系统加载，其余从网络加载）位于 `combined_***_fetcher`，可以通过对其封装实现缓存等操作。
+
+## 配置项
+
+### 配置 fontconfig
+
+`htmlkit` 使用 `fontconfig` 查找字体，请参阅 [`fontconfig 用户手册`](https://fontconfig.pages.freedesktop.org/fontconfig/fontconfig-user) 了解环境变量的具体含义、如何通过编写配置文件修改字体配置等。
+
+#### fontconfig_file
+
+- **类型**: `str | None`
+- **默认值**: `None`
+
+覆盖默认的配置文件路径。
+
+#### fontconfig_path
+
+- **类型**: `str | None`
+- **默认值**: `None`
+
+覆盖默认的配置目录。
+
+#### fontconfig_sysroot
+
+- **类型**: `str | None`
+- **默认值**: `None`
+
+覆盖默认的 sysroot。
+
+#### fc_debug
+
+- **类型**: `str | None`
+- **默认值**: `None`
+
+设置 Fontconfig 的 debug 级别。
+
+#### fc_dbg_match_filter
+
+- **类型**: `str | None`
+- **默认值**: `None`
+
+当 `FC_DEBUG` 设置为 `MATCH2` 时，过滤 debug 输出。
+
+#### fc_lang
+
+- **类型**: `str | None`
+- **默认值**: `None`
+
+设置默认语言，否则从 `LOCALE` 环境变量获取。
+
+#### fontconfig_use_mmap
+
+- **类型**: `str | None`
+- **默认值**: `None`
+
+是否使用 `mmap(2)` 读取字体缓存。

website/docs/best-practice/multi-adapter.mdx

@@ -42,7 +42,7 @@ async def handle_function():
 
 #### 处理近似事件
 
-对于一系列**差异不大**的事件，我们往往具有相同的处理逻辑。这时，我们不希望将相同的逻辑编写两遍，而应该复用代码，以实现在同一个事件处理函数中处理多个近似事件。我们可以使用[事件重载](../advanced/dependency.mdx#Event)的特性来实现这一功能。例如：
+对于一系列**差异不大**的事件，我们往往具有相同的处理逻辑。这时，我们不希望将相同的逻辑编写两遍，而应该复用代码，以实现在同一个事件处理函数中处理多个近似事件。我们可以使用[事件重载](../advanced/dependency.mdx#event)的特性来实现这一功能。例如：
 
 <Tabs groupId="python">
   <TabItem value="3.10" label="Python 3.10+" default>

website/docs/best-practice/testing/behavior.mdx

@@ -155,7 +155,6 @@ async def test_example(app: App):
 1. `should_call_send`
 
    定义事件响应器预期发送的消息，即通过[事件响应器操作 send](../../appendices/session-control.mdx#send)进行的操作。`should_call_send` 有四个参数：
-
    - `event`：回复的目标事件。
    - `message`：预期的消息对象，可以是 `str`、`Message` 或 `MessageSegment`。
    - `result`：send 的返回值，将会返回给插件。
@@ -163,8 +162,7 @@ async def test_example(app: App):
    - `**kwargs`：send 方法的额外参数。
 
 2. `should_call_api`
-   定义事件响应器预期调用的平台 API 接口，即通过[调用平台 API](../../appendices/api-calling.mdx#调用平台-API)进行的操作。`should_call_api` 有四个参数：
+   定义事件响应器预期调用的平台 API 接口，即通过[调用平台 API](../../appendices/api-calling.mdx#调用平台-api)进行的操作。`should_call_api` 有四个参数：
-
    - `api`：API 名称。
    - `data`：预期的请求数据。
    - `result`：call_api 的返回值，将会返回给插件。

website/docs/developer/adapter-writing.md

@@ -260,7 +260,7 @@ class Adapter(BaseAdapter):
 更多通信交互方式可以参考以下适配器：
 
 - [OneBot](https://github.com/nonebot/adapter-onebot/blob/master/nonebot/adapters/onebot/v11/adapter.py) - `WebSocket 客户端`、`WebSocket 服务端`、`HTTP WEBHOOK`、`HTTP POST`
-- [QQGuild](https://github.com/nonebot/adapter-qqguild/blob/master/nonebot/adapters/qqguild/adapter.py) - `WebSocket 服务端`
+- [QQ](https://github.com/nonebot/adapter-qq/blob/master/nonebot/adapters/qq/adapter.py) - `WebSocket 服务端`、`HTTP WEBHOOK`
 - [Telegram](https://github.com/nonebot/adapter-telegram/blob/beta/nonebot/adapters/telegram/adapter.py) - `HTTP WEBHOOK`
 
 #### 建立 Bot 连接
@@ -375,14 +375,16 @@ class Adapter(BaseAdapter):
 
 Websocket:
 
-- [OneBot V11](https://github.com/nonebot/adapter-onebot/blob/master/nonebot/adapters/onebot/v11/adapter.py#L127)
+- [OneBot V11](https://github.com/nonebot/adapter-onebot/blob/54270edbbdb2a71332d744f90b1a3d7f4bf6463a/nonebot/adapters/onebot/v11/adapter.py#L167-L177)
-- [OneBot V12](https://github.com/nonebot/adapter-onebot/blob/master/nonebot/adapters/onebot/v12/adapter.py#L162)
+- [OneBot V12](https://github.com/nonebot/adapter-onebot/blob/54270edbbdb2a71332d744f90b1a3d7f4bf6463a/nonebot/adapters/onebot/v12/adapter.py#L204-L218)
 
 HTTP:
 
-- [QQ 频道](https://github.com/nonebot/adapter-qqguild/blob/master/nonebot/adapters/qqguild/adapter.py#L354)
+- [OneBot V11](https://github.com/nonebot/adapter-onebot/blob/54270edbbdb2a71332d744f90b1a3d7f4bf6463a/nonebot/adapters/onebot/v11/adapter.py#L179-L215)
-- [Telegram](https://github.com/nonebot/adapter-telegram/blob/beta/nonebot/adapters/telegram/adapter.py#L145)
+- [OneBot V12](https://github.com/nonebot/adapter-onebot/blob/54270edbbdb2a71332d744f90b1a3d7f4bf6463a/nonebot/adapters/onebot/v12/adapter.py#L220-L266)
-- [飞书](https://github.com/nonebot/adapter-feishu/blob/master/nonebot/adapters/feishu/adapter.py#L158)
+- [QQ](https://github.com/nonebot/adapter-qq/blob/dc5d437e101f0e3db542de3300758a035ed7036e/nonebot/adapters/qq/adapter.py#L599-L605)
+- [Telegram](https://github.com/nonebot/adapter-telegram/blob/4a8633627e619245516767f5503dec2f58fe2193/nonebot/adapters/telegram/adapter.py#L148-L253)
+- [飞书](https://github.com/nonebot/adapter-feishu/blob/f8ab05e6d57a5e9013b944b0d019ca777725dfb0/nonebot/adapters/feishu/adapter.py#L201-L218)
 
 ### Bot
 
@@ -576,9 +578,9 @@ class Message(BaseMessage[MessageSegment]):
 
 然后根据平台具体的消息类型，来实现各种 `MessageSegment` 消息段，具体可以参考以下适配器：
 
-- [OneBot](https://github.com/nonebot/adapter-onebot/blob/master/nonebot/adapters/onebot/v11/message.py#L77-L261)
+- [OneBot V11](https://github.com/nonebot/adapter-onebot/blob/54270edbbdb2a71332d744f90b1a3d7f4bf6463a/nonebot/adapters/onebot/v11/message.py#L25-L259)
-- [QQGuild](https://github.com/nonebot/adapter-qqguild/blob/master/nonebot/adapters/qqguild/message.py#L22-L150)
+- [QQ](https://github.com/nonebot/adapter-qq/blob/dc5d437e101f0e3db542de3300758a035ed7036e/nonebot/adapters/qq/message.py#L30-L520)
-- [Telegram](https://github.com/nonebot/adapter-telegram/blob/beta/nonebot/adapters/telegram/message.py#L43-L250)
+- [Telegram](https://github.com/nonebot/adapter-telegram/blob/4a8633627e619245516767f5503dec2f58fe2193/nonebot/adapters/telegram/message.py#L13-L414)
 
 ## 适配器测试
 

website/docs/developer/plugin-publishing.mdx

@@ -8,7 +8,13 @@ description: 在商店发布自己的插件
 import Tabs from "@theme/Tabs";
 import TabItem from "@theme/TabItem";
 
-NoneBot 为开发者提供了分享插件给大家使用的方式——商店。本章节将会介绍如何将我们写好的插件发布到商店。
+NoneBot 为开发者提供了分享插件的官方商店。本指南囊括**从创建项目到发布到 PyPI，最终提交商店审核**的全过程。
+
+:::warning 警告
+如果你的插件只是满足自用需求，则完全可以选择**不发布插件**。发布插件**不是**使用插件的必要条件。
+
+NoneBot 社区对于插件有一定质量要求，对于不符合要求的插件，社区成员将会要求修改，直至符合要求后才能通过审核；如果长期未更新修改，社区将会关闭当前请求，之后如需发布请重新提交发布插件请求。相应的要求会在本章节以下部分介绍。
+:::
 
 :::tip 提示
 本章节仅包含插件发布流程指导，插件开发请查阅前述章节。
@@ -30,7 +36,7 @@ NoneBot 插件使用下述命名规范：
 ### 项目结构
 
 :::tip 提示
-本段所述的项目结构仅作推荐，不做强制要求，保证实际可用性即可。
+本段所述的项目结构仅作推荐，不做强制要求。
 :::
 
 插件程序本身结构可参考[插件结构](../tutorial/create-plugin.md#插件结构)一节，唯一区别在于，插件包可以直接处于项目顶层。
@@ -46,98 +52,267 @@ NoneBot 插件使用下述命名规范：
 └── 📜 README.md
 ```
 
-#### 第三方项目模板
+功能开发可以在 `__init__.py` 中进行或在包内部创建其他模块并在 `__init__.py` 中导入。
 
-一些社区用户可能会分享自己制作的项目模板方便大家使用，如：
+### 从项目模板开始
+
+为降低新手门槛，我们提供三条清晰、完整、可复制的发布路径。
+
+:::tip 提示
+你只需选择一条与你习惯一致的路径，**完整跟随即可成功发布**。无需在不同工具间切换或猜测配置。
+:::
+
+NoneBot 生态目前有如下插件项目模板：
 
-- [A-kirami/nonebot-plugin-template](https://github.com/A-kirami/nonebot-plugin-template)
 - [RF-Tar-Railt/nonebot-plugin-template](https://github.com/RF-Tar-Railt/nonebot-plugin-template)
+
+  此路径使用 **PDM** 项目管理器，符合 PEP 621 标准，自动化程度高。
+
 - [fllesser/nonebot-plugin-template](https://github.com/fllesser/nonebot-plugin-template)
 
+  此路径使用 **uv** 项目管理器和 **PoeThePoet** 任务运行器，构建速度快，适合追求效率的开发者。
+
+- [A-kirami/nonebot-plugin-template](https://github.com/A-kirami/nonebot-plugin-template)
+
+  此路径使用 **Poetry** 项目管理器，适合熟悉传统 Python 生态的开发者。
+
+#### 1. 创建项目
+
+1. 访问上述三个模板之一。
+2. 点击 **“Use this template”** → **“Create a new repository”**。
+3. 仓库名称填写：`nonebot-plugin-{your-plugin-name}`（此部分以 `nonebot-plugin-weather` 为例）。
+4. 点击 **“Create repository from template”**。
+
+#### 2. 配置发布权限
+
+1. 进入新仓库 → **Settings** → **Actions** → **General**。
+2. 在 **Workflow permissions** 下，勾选 **“Read and write permissions”** → 点击 **Save**。
+
+#### 3. 全局替换项目信息
+
+在仓库中点击 **“Add file”** → **“Create new file”**，创建一个空文件 `LICENSE`，选择开源协议并提交（此操作会触发工作流）。
+
+然后在本地克隆仓库，使用编辑器对以下内容进行**全局替换**：
+
 :::tip 提示
-本文档**不保证**第三方模板的适用性。
+此部分以“天气插件”为例，实际的替换内容应该根据你所创建的插件名称等相应调整。
-
-根据项目模板提供的使用指导补全/修改相应内容后上传到 GitHub 即可。
 :::
 
-### 插件依赖
+| 原内容                         | 替换为                             |
+| ------------------------------ | ---------------------------------- |
+| `nonebot-plugin-template`      | `nonebot-plugin-weather`           |
+| `nonebot_plugin_template`      | `nonebot_plugin_weather`           |
+| `<your_plugin_humanized_name>` | `天气查询`                         |
+| `<your_plugin_description>`    | `查询指定城市的实时天气与未来预报` |
+| `<your_github>`                | `你的GitHub用户名`                 |
+| `<your_email>`                 | `你的邮箱`                         |
 
-本段指导填写插件依赖，避免不正确的依赖信息导致插件无法正常工作。
+#### 4. 安装依赖与开发
 
-依赖填写的基本原则：程序直接导入了什么第三方库，就添加什么第三方包依赖；能用哪些第三方库的特性，就根据使用的特性锁定第三方包版本。
+<Tabs groupId="publish-path" defaultValue="pdm" values={[
+  {label: 'PDM + RF-Tar-Railt 模板', value: 'pdm'},
+  {label: 'uv + fllesser 模板', value: 'uv'},
+  {label: 'Poetry + A-kirami 模板', value: 'poetry'},
+]}>
+  <TabItem value="pdm" label="PDM + RF-Tar-Railt 模板">
 
-:::caution 注意
+```bash
+# 安装 PDM（若未安装）
+curl -sSL https://pdm-project.org/install-pdm.py | python3 -
 
-1. 插件需要添加 `nonebot2` 为依赖以避免“幽灵依赖”；
+# 安装项目依赖（自动创建虚拟环境）
-2. 插件需要将使用的适配器加入依赖列表，如：使用 OneBot 适配器的插件应添加 `nonebot-adapter-onebot` 依赖；
+pdm sync
-3. 由于 `nonebot` 是指 `nonebot1` **而非** `nonebot2`，因此要注意**不要**将 `nonebot` 添加为插件的依赖，以免造成冲突；
-4. 尽可能避免使用 `==` 锁定单一版本，增强与其它插件的兼容性。
 
-:::
+# 添加新依赖（如 httpx）
-
+pdm add httpx
-### 填写插件元数据
-
-请注意，插件发布要求**必须**填写元数据才能通过审核。
-
-下面是一个示例：
-
-```python title=nonebot_plugin_{your_plugin_name}/__init__.py
-from nonebot.plugin import PluginMetadata
-
-from .config import Config
-
-__plugin_meta__ = PluginMetadata(
-    name="{插件名称}",
-    description="{插件介绍}",
-    usage="{插件用法}",
-
-    type="{插件分类}",
-    # 发布必填，当前有效类型有：`library`（为其他插件编写提供功能），`application`（向机器人用户提供功能）。
-
-    homepage="{项目主页}",
-    # 发布必填。
-
-    config=Config,
-    # 插件配置项类，如无需配置可不填写。
-
-    supported_adapters={"~onebot.v11", "~telegram"},
-    # 支持的适配器集合，其中 `~` 在此处代表前缀 `nonebot.adapters.`，其余适配器亦按此格式填写。
-    # 若插件可以保证兼容所有适配器（即仅使用基本适配器功能）可不填写，否则应该列出插件支持的适配器。
-)
 ```
 
-:::caution 注意
+</TabItem>
-`__plugin_meta__` 变量**必须**处于插件最外层（如 `__init__.py` 中），否则无法正常识别。
 
-一般做法是在 `__init__.py` 中定义 `__plugin_meta__`。
+  <TabItem value="uv" label="uv + fllesser 模板">
-:::
 
-:::tip 提示
+```bash
-带花括号 `{}` 的内容需要自行替换，注意**一定要把原有的花括号去掉**。
+# 安装 uv（Windows）
-:::
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 
-### 准备项目主页
+# 安装 uv（macOS/Linux）
+curl -LsSf https://astral.sh/uv/install.sh | sh
 
-通常可以使用 GitHub 项目页面作为项目主页，在 `README.md` 文件中编写插件介绍等内容。
+# 安装所有依赖（含 dev）
+uv sync --all-groups -p 3.12
 
-内容大致包括：
+# 添加新依赖
+uv add httpx
+```
 
-- 插件功能介绍
+</TabItem>
-- 安装方法（建议至少有 `nb-cli` 方式安装，**不要**使用旧式的 `bot.py` 配置）
-- 插件配置项（若无可跳过）
-- 插件设置的触发规则（若无可跳过）
-- 插件的其它用法（按需编写）
 
-:::tip 提示
+  <TabItem value="poetry" label="Poetry + A-kirami 模板">
-可以参考[第三方项目模板](#第三方项目模板)。
-:::
 
-### 发布至 [PyPI](https://pypi.org)
+```bash
+# 安装 Poetry（推荐方式）
+curl -sSL https://install.python-poetry.org | python3 -
 
+# 安装项目依赖
+poetry install
+
+# 添加新依赖
+poetry add httpx
+```
+
+</TabItem>
+</Tabs>
+
+#### 5. 更新版本并发布
+
+<Tabs
+  groupId="publish-path-bump"
+  defaultValue="bump-my-version"
+  values={[
+    { label: "使用 bump-my-version", value: "bump-my-version" },
+    { label: "使用项目管理器", value: "bump-manager" },
+    { label: "手动更新版本", value: "bump-manual" },
+  ]}
+>
+  <TabItem value="bump-my-version" label="使用 bump-my-version">
+
+[bump-my-version](https://github.com/callowayproject/bump-my-version) 是一个功能强大、可配置的 Python 项目版本更新工具，支持自动提交到 Git 等 VCS。
+
+<Tabs groupId="publish-path" defaultValue="pdm" values={[
+  {label: 'PDM + RF-Tar-Railt 模板', value: 'pdm'},
+  {label: 'uv + fllesser 模板', value: 'uv'},
+  {label: 'Poetry + A-kirami 模板', value: 'poetry'},
+]}>
+  <TabItem value="pdm" label="PDM + RF-Tar-Railt 模板">
+
+```bash
+# 安装 bump-my-version
+pdm add --dev bump-my-version
+
+# 更新 patch 版本
+pdm run bump patch
+
+# 推送 tag 触发发布
+git push origin --tags
+```
+
+</TabItem>
+
+  <TabItem value="uv" label="uv + fllesser 模板">
+
+```bash
+# 更新 patch 版本
+uv run poe bump patch
+
+# 推送 tag 触发发布
+git push origin --tags
+```
+
+</TabItem>
+
+  <TabItem value="poetry" label="Poetry + A-kirami 模板">
+
+```bash
+# 安装 bump-my-version
+poetry add --dev bump-my-version
+
+# 更新 patch 版本
+poetry run bump patch
+
+# 推送 tag 触发发布
+git push origin --tags
+```
+
+</TabItem>
+</Tabs>
+
+</TabItem>
+  <TabItem value="bump-manager" label="使用项目管理器">
+
+<Tabs groupId="publish-path" defaultValue="pdm" values={[
+  {label: 'PDM + RF-Tar-Railt 模板', value: 'pdm'},
+  {label: 'uv + fllesser 模板', value: 'uv'},
+  {label: 'Poetry + A-kirami 模板', value: 'poetry'},
+]}>
+  <TabItem value="pdm" label="PDM + RF-Tar-Railt 模板">
+
+需要安装 PDM 插件 [pdm-bump](https://github.com/carstencodes/pdm-bump)。
+
+```bash
+# 安装 pdm-bump
+pdm self add pdm-bump
+
+# 更新 patch 版本
+pdm bump patch
+
+# 推送 tag 触发发布
+git push origin --tags
+```
+
+</TabItem>
+
+  <TabItem value="uv" label="uv + fllesser 模板">
+
+```bash
+# 更新 patch 版本
+uv version --bump patch
+
+# 创建相应提交与标签
+git add pyproject.toml
+git commit -m "chore: release v0.1.1"  # 替换为实际的版本号
+git tag v0.1.1  # 替换为实际的版本号
+
+# 推送 tag 触发发布
+git push origin --tags
+```
+
+</TabItem>
+
+  <TabItem value="poetry" label="Poetry + A-kirami 模板">
+
+```bash
+# 更新版本（自动提交并打标签）
+poetry version patch
+
+# 推送 tag 触发发布
+git push origin --tags
+```
+
+</TabItem>
+</Tabs>
+
+</TabItem>
+  <TabItem value="bump-manual" label="手动更新版本">
+
+手动更新 `pyproject.toml` 中的 `version` 字段，然后推送 tag 触发发布工作流
+
+```bash
+git add pyproject.toml
+git commit -m "chore: release v0.1.1"  # 替换为实际的版本号
+git tag v0.1.1  # 替换为实际的版本号
+git push origin --tags
+```
+
+</TabItem>
+</Tabs>
+
+推送 `v*` 标签后，模板提供的 GitHub Actions 工作流将自动构建并发布到 PyPI。
+
+#### 6. 发布到 [PyPI](https://pypi.org)
+
+<Tabs groupId="publish-method" defaultValue="template" values={[
+  {label: '使用模板的自动发布工作流', value: 'template'},
+  {label: '手动发布', value: 'manual'},
+]}>
+  <TabItem value="template" label="使用模板的自动发布工作流">
+不同模板使用的发布方式可能不同，具体配置流程参考对应模板的详细使用指南。
+</TabItem>
+
+  <TabItem value="manual" label="手动发布">
 根据选用的构建系统，在项目的 `pyproject.toml` 中填入必要信息后进行构建与发布。
 
 :::tip 提示
-不同构建工具的使用可能存在差别。本文仅以 [`pdm`](https://pdm.fming.dev/latest/),
+不同构建工具的使用可能存在差别。本文仅以 [`pdm`](https://pdm-project.org/zh/latest/),
 [`poetry`](https://python-poetry.org/docs/), [`setuptools`](https://setuptools.pypa.io/en/latest/)
 构建系统**本地构建与发布**为示例讲解，其余构建/管理工具等和自动化构建的用法请读者自行探索。
 :::
@@ -179,10 +354,187 @@ twine upload dist/*                 # 只发布先前的构建
   </TabItem>
 </Tabs>
 
+</TabItem>
+</Tabs>
+
 :::tip 提示
 发布前建议自行测试构建包是否可用，避免遗漏代码文件或资源文件等问题。
 :::
 
+## 基本要求
+
+无论你选择哪条路径，以下内容**必须**完成，否则无法通过商店自动检查：
+
+### 能够正确加载
+
+插件包必须能够被 NoneBot 正确加载，在商店审核中会通过 **NoneFlow** 自动化加载测试进行。
+
+#### 依赖其他插件
+
+如果插件依赖其他插件提供的功能，则**必须**在代码中使用 `require()` 来引入该插件，然后才能 `import` 该插件提供的功能。具体细节参阅[跨插件访问](../advanced/requiring.md)。
+
+使用示例如下：
+
+```python title=nonebot_plugin_weather/__init__.py
+from nonebot import require
+
+require("nonebot_plugin_apscheduler")
+
+from nonebot_plugin_apscheduler import scheduler
+```
+
+#### 不能零配置加载的插件
+
+如果插件需要必要配置项才能正常导入，则**必须**在商店提交表单中填写必要的配置项内容。
+
+但一种更好的做法是，**将插件设计为零配置即可加载**（允许缺少必要配置项时插件仍能正常导入，但不执行需要相应配置项的功能），尤其是对于一些必要配置含有敏感信息（如密钥、Token、API Key 等）的插件。这样可以避免在商店提交表单时填写敏感信息的风险。
+
+### 插件元数据
+
+插件包**必须**填写元数据才能通过 **NoneFlow** 自动化检查。
+
+下面是一个示例：
+
+```python title=nonebot_plugin_weather/__init__.py
+from nonebot.plugin import PluginMetadata
+
+from .config import Config
+
+__plugin_meta__ = PluginMetadata(
+    # 基本信息（必填）
+    name="天气查询",  # 插件名称
+    description="查询指定城市的实时天气与未来预报",  # 插件介绍
+    usage="发送【天气 城市名】获取天气信息",  # 插件用法
+
+    # 发布额外信息
+    type="application",  # 插件分类
+    # 发布必填，当前有效类型有：`library`（为其他插件编写提供功能），`application`（向机器人用户提供功能）。
+
+    homepage="https://github.com/你的用户名/nonebot-plugin-weather",
+    # 发布必填。
+
+    config=Config,
+    # 插件配置项类，如果有配置类则必须填写。
+
+    supported_adapters={"~onebot.v11"},
+    # 支持的适配器集合，其中 `~` 在此处代表前缀 `nonebot.adapters.`，其余适配器亦按此格式填写。
+    # 若插件只使用了 NoneBot 基本抽象，应显式填写 None，否则应该列出插件支持的适配器。
+)
+```
+
+:::caution 注意
+`__plugin_meta__` 变量**必须**处于插件最外层（如 `__init__.py` 中），否则无法正常识别。
+
+一般做法是在 `__init__.py` 中定义 `__plugin_meta__`。
+:::
+
+#### 继承其他插件支持的适配器
+
+如果你的插件依赖于其他插件提供的支持功能，而其他插件可能支持更少的适配器，这时就应该使用
+[inherit_supported_adapters()](../api/plugin/load#inherit-supported-adapters) 函数来继承其他插件支持的适配器。
+
+示例用法如下：
+
+```python title=nonebot_plugin_weather/__init__.py
+from nonebot import require
+from nonebot.plugin import PluginMetadata, inherit_supported_adapters
+
+from .config import Config
+
+require("nonebot_plugin_alconna")  # 必须先 require 才能被 inherit_supported_adapters 处理
+
+__plugin_meta__ = PluginMetadata(
+    name="天气查询",
+    description="查询指定城市的实时天气与未来预报",
+    usage="发送【天气 城市名】获取天气信息",
+    type="application",
+    homepage="https://github.com/你的用户名/nonebot-plugin-weather",
+    config=Config,
+
+    supported_adapters=inherit_supported_adapters("nonebot_plugin_alconna"),
+    # 继承 nonebot_plugin_alconna 插件的适配器支持列表
+)
+```
+
+### 准备项目主页
+
+通常可以使用 GitHub 项目页面作为项目主页，在 `README.md` 文件中编写插件介绍等内容。
+
+内容大致包括：
+
+- 插件功能介绍；
+- 安装方法
+  - **必须**有 NB-CLI 方式安装
+  - 可选依赖可以给出其他安装方式
+  - **不得**使用旧式的 `bot.py` 配置
+- 插件配置项（如 `Config` 类字段，若无可跳过）
+- 插件设置的触发规则（若无可跳过）
+- 插件的其它用法（按需编写）
+- 效果图、权限说明（按需编写）
+
+## 质量要求
+
+以下内容**强烈建议**完成，否则社区成员将会要求修改：
+
+### 依赖管理原则
+
+- **必须**包含 `nonebot2`。
+- **必须**将插件直接使用的适配器加入依赖列表，如：使用 OneBot 适配器的插件应添加 `nonebot-adapter-onebot` 依赖；
+- **禁止**使用 `==` 锁定单一版本，使用 `>=` 或 `~=`。
+- **禁止**添加 `nonebot`（V1）作为依赖。
+- 所有在代码中 `import` 的第三方库，必须在 `pyproject.toml` 的 `dependencies` 中列出。
+
+### 避免误用同步操作
+
+NoneBot 是一个异步框架，插件中**禁止**使用任何可能阻塞事件循环的同步操作，例如：
+
+- 同步 HTTP 请求（如 `requests` 库）；
+
+  **推荐**操作（以 `httpx` 为例）：
+
+  ```python
+  import httpx
+
+  async with httpx.AsyncClient() as client:
+      response = await client.get("https://api.example.com/data")  # 异步操作，不阻塞机器人
+  ```
+
+  **禁止**操作：
+
+  ```python
+  import requests
+
+  requests.get("https://api.example.com/data")  # 同步操作，会阻塞机器人
+  ```
+
+- 其他可能长时间运行阻塞事件循环的操作。
+
+### 本地文件存储
+
+如果插件需要在本地存储数据、配置或缓存文件，**必须**使用 [`nonebot-plugin-localstore`](https://github.com/nonebot/plugin-localstore) 管理，具体细节参阅[本地存储](../best-practice/data-storing.md)章节。
+
+参考示例：
+
+```python title=nonebot_plugin_weather/__init__.py
+from pathlib import Path
+from nonebot import require
+require("nonebot_plugin_localstore")
+
+import nonebot_plugin_localstore as store
+
+# 获取插件缓存文件（夹）路径
+weather_cache_dir: Path = store.get_plugin_cache_dir()
+weather_cache_file: Path = store.get_plugin_cache_file("cache.json")
+
+# 获取插件配置文件（夹）路径
+weather_config_dir: Path = store.get_plugin_config_dir()
+weather_config_file: Path = store.get_plugin_config_file("config.toml")
+
+# 获取插件数据文件（夹）路径
+weather_data_dir: Path = store.get_plugin_data_dir()
+weather_data_file: Path = store.get_plugin_data_file("resource-index.json")
+```
+
 ## 商店审核
 
 ### 提交申请
@@ -201,6 +553,6 @@ twine upload dist/*                 # 只发布先前的构建
 若插件检查未通过或信息有误，**不必**关闭当前 Issue。只需更新插件并上传到 PyPI/修改信息后勾选插件测试勾选框即可重新触发插件检查。
 :::
 
-之后，NoneBot 的维护者和一些插件开发者会初步检查插件代码，帮助减少该插件的问题。
+之后，NoneBot 的维护者和一些志愿者会初步检查插件代码，帮助减少该插件的问题。
 
 完成这些步骤后，您的插件将会被自动合并到[商店](/store/plugins)，而您也将成为 [**NoneBot 贡献者**](https://github.com/nonebot/nonebot2/graphs/contributors)的一员。

website/docs/editor-support.md

@@ -7,6 +7,61 @@ description: 配置编辑器以获得最佳体验
 
 框架基于 [PEP 484](https://www.python.org/dev/peps/pep-0484/)、[PEP 561](https://www.python.org/dev/peps/pep-0561/)、[PEP 8](https://www.python.org/dev/peps/pep-0008/) 等规范进行开发并且**拥有完整类型注解**。框架使用 Pyright（Pylance）工具进行类型检查，确保代码可以被编辑器正确解析。
 
+## CLI 脚手架提供的编辑器工具支持
+
+在使用 NB-CLI [创建项目](./quick-start.mdx#创建项目)时，如果选择了用于插件开发的 `simple` 模板，其会根据选择的开发工具，**自动配置项目根目录下的 `.vscode/extensions.json` 文件**，以推荐最匹配的 VS Code 插件，同时自动将相应的预设配置项写入 `pyproject.toml` 作为“开箱即用”配置，从而提升开发体验。
+
+```bash
+[?] 选择一个要使用的模板: simple (插件开发者)
+...
+[?] 要使用哪些开发工具?
+```
+
+### 支持的开发工具
+
+1. Pyright (Pylance)
+
+   [VS Code 插件](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance) | [项目](https://github.com/microsoft/pyright) | [文档](https://microsoft.github.io/pyright/)
+
+   由微软开发的 Python 静态类型检查器和语言服务器，提供智能感知、跳转定义、查找引用、实时错误检查等强大功能。
+
+   作为 VS Code 官方推荐的 Python 语言服务器，与 Pylance 扩展配合使用，能提供最流畅、最准确的代码补全和类型推断体验，是绝大多数开发者的首选。
+
+2. Ruff
+
+   [VS Code 插件](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff) | [项目](https://github.com/astral-sh/ruff) | [文档](https://docs.astral.sh/ruff/)
+
+   一个用 Rust 编写的超快 Python 代码格式化和 lint 工具，完全兼容 `black`、`isort`、`flake8` 等主流工具的规则。
+
+   速度极快（比 `black` 和 `flake8` 快 100 倍以上），配置简单，能自动格式化代码并检测潜在错误、代码风格问题（尤其是误用同步网络请求库），是提升代码质量和开发效率的必备利器。
+
+3. MyPy
+
+   [VS Code 插件](https://marketplace.visualstudio.com/items?itemName=matangover.mypy) | [项目](https://github.com/python/mypy) | [文档](https://mypy.readthedocs.io/en/stable/index.html)
+
+   一个官方实现的 Python 静态类型检查器，通过分析代码中的类型注解来发现类型错误。
+
+4. BasedPyright
+
+   [VS Code 插件](https://marketplace.visualstudio.com/items?itemName=detachhead.basedpyright) | [项目](https://github.com/DetachHead/basedpyright) | [文档](https://docs.basedpyright.com/)
+
+   一个基于 Pyright 的、由社区维护的替代性 Python 语言服务器，旨在提供更优的类型检查支持与接近 Pylance 的更好的使用体验。
+
+   相较于 Pylance，BasedPyright 允许配合 VS Code 之外的其他编辑器使用，同时也复刻了部分 Pylance 限定的功能。
+
+   如果您是高级用户，希望尝试 Pylance 的替代方案，或遇到 Pylance 在特定环境下的兼容性问题，可以考虑使用 BasedPyright。
+
+:::caution 提示
+为避免 `Pylance` 和 `BasedPyright` 相互冲突导致配置混乱甚至异常，脚手架默认不允许在创建项目时同时配置这两者。
+
+如果确实需要同时使用，请在创建项目时选择 Pylance/Pyright 并根据[相关文档](https://docs.basedpyright.com/latest/installation/ides/#vscode-vscodium)进行手动配置。
+:::
+
+### 配置效果
+
+选择上述工具后，NB-CLI 会在您的项目根目录下生成一个 `.vscode/extensions.json` 文件并在 `pyproject.toml` 文件中写入相应的配置项。当您在 VS Code 中打开此项目时，IDE
+会自动弹出提示，建议您安装这些推荐的扩展，一键即可完成开发环境的初始化，让您可以立即开始编写代码，无需手动搜索和安装插件。
+
 ## 编辑器推荐配置
 
 ### Visual Studio Code

website/docs/quick-start.mdx

@@ -81,8 +81,9 @@ nb create
    请注意，多选项使用**空格**选中或取消，**回车**确认。
 
    ```bash
-   [?] 要使用哪些驱动器? FastAPI (FastAPI 驱动器)
    [?] 要使用哪些适配器? Console (基于终端的交互式适配器)
+   [?] 要使用哪些驱动器? FastAPI (FastAPI 驱动器)
+   [?] 要使用什么本地存储策略? 用户全局 (默认，适用于单用户下单实例)
    [?] 立即安装依赖? (Y/n) Yes
    [?] 创建虚拟环境? (Y/n) Yes
    ```

website/docs/tutorial/application.mdx

@@ -10,6 +10,9 @@ options:
 
 # 手动创建项目
 
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
 在[快速上手](../quick-start.mdx)中，我们已经介绍了如何安装和使用 `nb-cli` 创建一个项目。在本章节中，我们将简要介绍如何在不使用 `nb-cli` 的方式创建一个机器人项目的**最小实例**并启动。如果你想要了解 NoneBot 的启动流程，也可以阅读本章节。
 
 :::caution 警告
@@ -30,23 +33,51 @@ options:
 
 1. （可选）创建虚拟环境，以 venv 为例
 
+   <Tabs groupId="platform">
+   <TabItem value="windows" label="Windows" default>
+
    ```bash
+   # 创建虚拟环境
    python -m venv .venv --prompt nonebot2
-   # windows
+   # 激活虚拟环境
    .venv\Scripts\activate
-   # linux/macOS
+   ```
+
+   </TabItem>
+   <TabItem value="linux/macos" label="Linux/macOS">
+
+   ```bash
+   # 创建虚拟环境
+   python -m venv .venv --prompt nonebot2
+   # 激活虚拟环境
    source .venv/bin/activate
    ```
 
-2. 安装 nonebot2 以及驱动器
+   </TabItem>
+   </Tabs>
+
+2. 安装 nonebot2 以及驱动器，以 Fastapi 驱动器为例
+
+   <Tabs groupId="platform">
+   <TabItem value="windows" label="Windows" default>
 
    ```bash
-   pip install 'nonebot2[fastapi]'
+   pip install "nonebot2[fastapi]"
    ```
 
-   驱动器包名可以在 [驱动器商店](/store/drivers) 中找到。
+   </TabItem>
+   <TabItem value="linux/macos" label="Linux/macOS">
 
-3. 安装适配器
+   ```bash
+   pip install "nonebot2[fastapi]"
+   ```
+
+   </TabItem>
+   </Tabs>
+
+   驱动器包名可以在 [驱动器商店](/store/drivers) 中找到，请替换上文方括号中的内容。
+
+3. 安装适配器，以 Console 适配器为例
 
    ```bash
    pip install nonebot-adapter-console
@@ -58,7 +89,7 @@ options:
 
 配置文件用于存放 NoneBot 运行所需要的配置项，使用 [`pydantic`](https://docs.pydantic.dev/) 以及 [`python-dotenv`](https://saurabh-kumar.com/python-dotenv/) 来读取配置。配置项需符合 dotenv 格式，复杂类型数据需使用 JSON 格式填写。具体可选配置方式以及配置项详情参考[配置](../appendices/config.mdx)。
 
-在**项目文件夹**中创建一个 `.env` 文本文件，并写入以下内容:
+在**项目文件夹**中创建一个名为 `.env` 的文件，并写入以下内容:
 
 ```bash title=.env
 HOST=0.0.0.0  # 配置 NoneBot 监听的 IP / 主机名
@@ -101,10 +132,29 @@ if __name__ == "__main__":
 
 ## 运行机器人
 
-在**项目文件夹**中，使用配置好环境的 Python 解释器运行入口文件（如果使用虚拟环境，请先激活虚拟环境）:
+在**项目文件夹**中，使用配置好环境的 Python 解释器运行入口文件:
+
+<Tabs groupId="platform">
+  <TabItem value="windows" label="Windows" default>
 
 ```bash
+# 激活虚拟环境（未使用虚拟环境时跳过此行）
+.venv\Scripts\activate
+# 运行机器人
 python bot.py
 ```
 
+  </TabItem>
+  <TabItem value="linux/macos" label="Linux/macOS">
+
+```bash
+# 激活虚拟环境（未使用虚拟环境时跳过此行）
+source .venv/bin/activate
+# 运行机器人
+python bot.py
+```
+
+  </TabItem>
+</Tabs>
+
 如果你后续使用了 `nb-cli` ，你仍可以使用 `nb run` 命令来运行机器人，`nb-cli` 会自动检测入口文件 `bot.py` 是否存在并运行。同时，你也可以使用 `nb run --reload` 来自动检测代码的更改并自动重新运行入口文件。

website/docs/tutorial/create-plugin.md

@@ -48,8 +48,10 @@ options:
 
    ```tree title=Project
    📦 awesome-bot
+   ├── 📂 .venv
    ├── 📂 awesome_bot
    │   └── 📂 plugins
+   ├── 📜 .env.prod
    ├── 📜 pyproject.toml
    └── 📜 README.md
    ```
@@ -64,7 +66,7 @@ options:
 :::
 
 :::caution 注意
-如果在之前的[创建项目](./application.md)章节中手动创建了相关文件，那么你需要做出如下修改：
+如果在之前的[创建项目](./application.mdx)章节中手动创建了相关文件，那么你需要做出如下修改：
 
 1. 在项目目录中创建一个两层文件夹 `awesome_bot/plugins`
 
@@ -91,18 +93,20 @@ options:
 $ nb plugin create
 [?] 插件名称: weather
 [?] 使用嵌套插件? (y/N) N
-[?] 输出目录: awesome_bot/plugins
+[?] 请输入插件存储位置: awesome_bot/plugins
 ```
 
 `nb-cli` 会在 `awesome_bot/plugins` 目录下创建一个名为 `weather` 的文件夹，其中包含的文件将在稍后章节中用到。
 
 ```tree title=Project
 📦 awesome-bot
+├── 📂 .venv
 ├── 📂 awesome_bot
 │   └── 📂 plugins
-|       └── 📂 foo
+|       └── 📂 weather
 |           ├── 📜 __init__.py
 |           └── 📜 config.py
+├── 📜 .env.prod
 ├── 📜 pyproject.toml
 └── 📜 README.md
 ```
@@ -189,12 +193,16 @@ nonebot.load_from_json("plugin_config.json", encoding="utf-8")
 
 ### `load_from_toml`
 
-通过 TOML 文件加载插件，是 [`load_all_plugins`](#load_all_plugins) 的 TOML 变种。通过读取 TOML 文件中的 `[tool.nonebot]` Table 中的 `plugins` 和 `plugin_dirs` Array 进行加载。例如：
+通过 TOML 文件加载插件，是 [`load_all_plugins`](#load_all_plugins) 的 TOML 变种。通过读取 TOML 文件中的 `[tool.nonebot]` Table 中的 `plugin_dirs` Array 与
+`[tool.nonebot.plugins]` Table 中的多个 Array 进行加载。例如：
 
 ```toml title=plugin_config.toml
 [tool.nonebot]
-plugins = ["path.to.your.plugin"]
 plugin_dirs = ["path/to/your/plugins"]
+
+[tool.nonebot.plugins]
+"@local" = ["path.to.your.plugin"]  # 本地插件等非插件商店来源的插件
+"nonebot-plugin-someplugin" = ["nonebot_plugin_someplugin"]  # 插件商店来源的插件
 ```
 
 ```python

website/docs/tutorial/handler.mdx

@@ -27,8 +27,8 @@ import Messenger from "@site/src/components/Messenger";
 顾名思义，“事件处理函数装饰器”是一个[装饰器（decorator）](https://docs.python.org/zh-cn/3/glossary.html#term-decorator)，那么它的使用方法也同[函数定义](https://docs.python.org/zh-cn/3/reference/compound_stmts.html#function-definitions)中所展示的包装用法相同。例如：
 
 ```python {6-8} title=weather/__init__.py
+from nonebot import on_command
 from nonebot.rule import to_me
-from nonebot.plugin import on_command
 
 weather = on_command("天气", rule=to_me(), aliases={"weather", "查天气"}, priority=10, block=True)
 
@@ -46,8 +46,8 @@ async def handle_function():
 事件响应器操作与事件处理函数装饰器类似，通常作为事件响应器 `Matcher` 的[类方法](https://docs.python.org/zh-cn/3/library/functions.html#classmethod)存在，因此事件响应器操作的调用方法也是 `Matcher.func()` 的形式。不过不同的是，事件响应器操作并不是装饰器，因此并不需要@进行标注。
 
 ```python {8,9} title=weather/__init__.py
+from nonebot import on_command
 from nonebot.rule import to_me
-from nonebot.plugin import on_command
 
 weather = on_command("天气", rule=to_me(), aliases={"weather", "查天气"}, priority=10, block=True)
 

website/docs/tutorial/store.mdx

@@ -24,6 +24,9 @@ NoneBot 提供了一个[商店](/store/plugins)，商店内容均由社区开发
 
 商店中每个内容的卡片都包含了其名称和简介等信息，点击**卡片右上角**链接图标即可跳转到其主页。
 
+与此同时，NB-CLI 也提供了一个 TUI 版本的商店界面，可通过 `nb adapter store`、`nb plugin store`、`nb driver store` 命令或 CLI
+交互式界面进入。其提供了接近网页商店的体验，同时允许快捷安装到当前项目。
+
 ## 安装插件
 
 <Asciinema

website/docusaurus.config.ts

@@ -300,6 +300,7 @@ export default async function createConfigAsync() {
 
     future: {
       experimental_faster: true,
+      v4: true,
     },
 
     plugins: [

website/src/changelog/changelog.md

@@ -5,6 +5,161 @@ toc_max_heading_level: 2
 
 # 更新日志
 
+## 最近更新
+
+### 💥 破坏性变更
+
+- Remove: 移除 Python 3.9 支持 [@shoucandanghehe](https://github.com/shoucandanghehe) ([#3860](https://github.com/nonebot/nonebot2/pull/3860))
+
+### 🐛 Bug 修复
+
+- Fix: aiohttp 驱动未处理 WSMsgType.CLOSED 类型 [@shoucandanghehe](https://github.com/shoucandanghehe) ([#3862](https://github.com/nonebot/nonebot2/pull/3862))
+
+### 📝 文档
+
+- Docs: 完善对「发布插件」章节的文档描述 [@NCBM](https://github.com/NCBM) ([#3865](https://github.com/nonebot/nonebot2/pull/3865))
+- Docs: Docker 部署镜像添加 latest tag [@AhsokaTano26](https://github.com/AhsokaTano26) ([#3787](https://github.com/nonebot/nonebot2/pull/3787))
+- Docs: 调整文档 `on_command` import 路径 [@Xfjie314](https://github.com/Xfjie314) ([#3747](https://github.com/nonebot/nonebot2/pull/3747))
+- Docs: 修复插件编写准备文档中的文本错误 [@Xfjie314](https://github.com/Xfjie314) ([#3746](https://github.com/nonebot/nonebot2/pull/3746))
+- Docs: 修复格式化导致的语法错误 [@yanyongyu](https://github.com/yanyongyu) ([#3737](https://github.com/nonebot/nonebot2/pull/3737))
+
+### 💫 杂项
+
+- Plugin: skland 插件添加标签 [@FrostN0v0](https://github.com/FrostN0v0) ([#3853](https://github.com/nonebot/nonebot2/pull/3853))
+- CI: 修改 `test_depend` cpython 版本范围 [@yanyongyu](https://github.com/yanyongyu) ([#3828](https://github.com/nonebot/nonebot2/pull/3828))
+- Plugin: 删除插件 nonebot_plugin_acmd [@hlfzsi](https://github.com/hlfzsi) ([#3750](https://github.com/nonebot/nonebot2/pull/3750))
+
+### 🍻 插件发布
+
+- Plugin: mc服务器白名单管理工具 [@noneflow](https://github.com/noneflow) ([#3813](https://github.com/nonebot/nonebot2/pull/3813))
+- Plugin: 特朗普社媒监控 [@noneflow](https://github.com/noneflow) ([#3882](https://github.com/nonebot/nonebot2/pull/3882))
+- Plugin: The Betterest Mute Cat [@noneflow](https://github.com/noneflow) ([#3869](https://github.com/nonebot/nonebot2/pull/3869))
+- Plugin: nonebot-plugin-cardimg [@noneflow](https://github.com/noneflow) ([#3857](https://github.com/nonebot/nonebot2/pull/3857))
+- Plugin: Nonebot-Plugin-Rikka [@noneflow](https://github.com/noneflow) ([#3875](https://github.com/nonebot/nonebot2/pull/3875))
+- Plugin: nonebot-plugin-peek [@noneflow](https://github.com/noneflow) ([#3859](https://github.com/nonebot/nonebot2/pull/3859))
+- Plugin: 自动合成emoji [@noneflow](https://github.com/noneflow) ([#3867](https://github.com/nonebot/nonebot2/pull/3867))
+- Plugin: 今日doro结局 [@noneflow](https://github.com/noneflow) ([#3852](https://github.com/nonebot/nonebot2/pull/3852))
+- Plugin: Phira Server Manager [@noneflow](https://github.com/noneflow) ([#3855](https://github.com/nonebot/nonebot2/pull/3855))
+- Plugin: Shiro Web Console [@noneflow](https://github.com/noneflow) ([#3832](https://github.com/nonebot/nonebot2/pull/3832))
+- Plugin: 群聊拟人 [@noneflow](https://github.com/noneflow) ([#3820](https://github.com/nonebot/nonebot2/pull/3820))
+- Plugin: BitTorrent磁力搜索 [@noneflow](https://github.com/noneflow) ([#3844](https://github.com/nonebot/nonebot2/pull/3844))
+- Plugin: MCP Client [@noneflow](https://github.com/noneflow) ([#3842](https://github.com/nonebot/nonebot2/pull/3842))
+- Plugin: Dice Helper [@noneflow](https://github.com/noneflow) ([#3840](https://github.com/nonebot/nonebot2/pull/3840))
+- Plugin: Uniconfig-配置文件管理器 [@noneflow](https://github.com/noneflow) ([#3849](https://github.com/nonebot/nonebot2/pull/3849))
+- Plugin: osugreek [@noneflow](https://github.com/noneflow) ([#3836](https://github.com/nonebot/nonebot2/pull/3836))
+- Plugin: 基于QQ音乐歌单的音乐推荐 [@noneflow](https://github.com/noneflow) ([#3838](https://github.com/nonebot/nonebot2/pull/3838))
+- Plugin: nonebot-plugin-bili2mp4 [@noneflow](https://github.com/noneflow) ([#3792](https://github.com/nonebot/nonebot2/pull/3792))
+- Plugin: 战地6战绩查询 [@noneflow](https://github.com/noneflow) ([#3815](https://github.com/nonebot/nonebot2/pull/3815))
+- Plugin: Tavily Search [@noneflow](https://github.com/noneflow) ([#3834](https://github.com/nonebot/nonebot2/pull/3834))
+- Plugin: 群消息中继 [@noneflow](https://github.com/noneflow) ([#3804](https://github.com/nonebot/nonebot2/pull/3804))
+- Plugin: 互联网异常事件监测 [@noneflow](https://github.com/noneflow) ([#3831](https://github.com/nonebot/nonebot2/pull/3831))
+- Plugin: 词汇黑名单审查 [@noneflow](https://github.com/noneflow) ([#3817](https://github.com/nonebot/nonebot2/pull/3817))
+- Plugin: 汉化进度记录 [@noneflow](https://github.com/noneflow) ([#3807](https://github.com/nonebot/nonebot2/pull/3807))
+- Plugin: nonebot-plugin-ai-groupmate [@noneflow](https://github.com/noneflow) ([#3766](https://github.com/nonebot/nonebot2/pull/3766))
+- Plugin: nonebot_plugin_boardgamehelper [@noneflow](https://github.com/noneflow) ([#3800](https://github.com/nonebot/nonebot2/pull/3800))
+- Plugin: 即梦绘画 [@noneflow](https://github.com/noneflow) ([#3797](https://github.com/nonebot/nonebot2/pull/3797))
+- Plugin: 快捷回复 [@noneflow](https://github.com/noneflow) ([#3795](https://github.com/nonebot/nonebot2/pull/3795))
+- Plugin: pErithacus [@noneflow](https://github.com/noneflow) ([#3767](https://github.com/nonebot/nonebot2/pull/3767))
+- Plugin: MC服务器状态查询 [@noneflow](https://github.com/noneflow) ([#3781](https://github.com/nonebot/nonebot2/pull/3781))
+- Plugin: Instagram RapidAPI 解析 [@noneflow](https://github.com/noneflow) ([#3784](https://github.com/nonebot/nonebot2/pull/3784))
+- Plugin: 今天是什么小猪 [@noneflow](https://github.com/noneflow) ([#3773](https://github.com/nonebot/nonebot2/pull/3773))
+- Plugin: 御神签 [@noneflow](https://github.com/noneflow) ([#3777](https://github.com/nonebot/nonebot2/pull/3777))
+- Plugin: 火车迷铁路工具箱 [@noneflow](https://github.com/noneflow) ([#3770](https://github.com/nonebot/nonebot2/pull/3770))
+- Plugin: TerraLink [@noneflow](https://github.com/noneflow) ([#3775](https://github.com/nonebot/nonebot2/pull/3775))
+- Plugin: 安安说 [@noneflow](https://github.com/noneflow) ([#3726](https://github.com/nonebot/nonebot2/pull/3726))
+- Plugin: 安安的素描本聊天框 [@noneflow](https://github.com/noneflow) ([#3762](https://github.com/nonebot/nonebot2/pull/3762))
+- Plugin: manosoba-reply-generator [@noneflow](https://github.com/noneflow) ([#3753](https://github.com/nonebot/nonebot2/pull/3753))
+- Plugin: 模板绘图 [@noneflow](https://github.com/noneflow) ([#3752](https://github.com/nonebot/nonebot2/pull/3752))
+- Plugin: iPinfo [@noneflow](https://github.com/noneflow) ([#3759](https://github.com/nonebot/nonebot2/pull/3759))
+- Plugin: 电子课程表 [@noneflow](https://github.com/noneflow) ([#3743](https://github.com/nonebot/nonebot2/pull/3743))
+- Plugin: 魔裁 Memes [@noneflow](https://github.com/noneflow) ([#3755](https://github.com/nonebot/nonebot2/pull/3755))
+- Plugin: 图像对称处理 [@noneflow](https://github.com/noneflow) ([#3748](https://github.com/nonebot/nonebot2/pull/3748))
+- Plugin: 每日人品 [@noneflow](https://github.com/noneflow) ([#3735](https://github.com/nonebot/nonebot2/pull/3735))
+- Plugin: nonebot_plugin_markdown2img [@noneflow](https://github.com/noneflow) ([#3730](https://github.com/nonebot/nonebot2/pull/3730))
+- Plugin: B站解析助手 [@noneflow](https://github.com/noneflow) ([#3728](https://github.com/nonebot/nonebot2/pull/3728))
+
+### 🍻 机器人发布
+
+- Bot: Rosmontis.io [@noneflow](https://github.com/noneflow) ([#3878](https://github.com/nonebot/nonebot2/pull/3878))
+
+### 🍻 适配器发布
+
+- Adapter: 云湖适配器 [@noneflow](https://github.com/noneflow) ([#3741](https://github.com/nonebot/nonebot2/pull/3741))
+
+## v2.4.4
+
+### 🚀 新功能
+
+- Feature: 允许插件从环境变量中读取配置项并支持 alias [@AzideCupric](https://github.com/AzideCupric) ([#3673](https://github.com/nonebot/nonebot2/pull/3673))
+- Feature: 更新 NB-CLI 新版插件加载格式与文档 [@NCBM](https://github.com/NCBM) ([#3614](https://github.com/nonebot/nonebot2/pull/3614))
+
+### 🐛 Bug 修复
+
+- Fix: log level 配置项无法使用 int 类型配置 [@yanyongyu](https://github.com/yanyongyu) ([#3732](https://github.com/nonebot/nonebot2/pull/3732))
+- Fix: 兼容 pydantic v2.12 `FieldInfo` 改动 [@yanyongyu](https://github.com/yanyongyu) ([#3722](https://github.com/nonebot/nonebot2/pull/3722))
+
+### 📝 文档
+
+- Docs: 更新适配器编写指南中的链接 [@xjh2009](https://github.com/xjh2009) ([#3731](https://github.com/nonebot/nonebot2/pull/3731))
+- Feature: 更新 NB-CLI 新版插件加载格式与文档 [@NCBM](https://github.com/NCBM) ([#3614](https://github.com/nonebot/nonebot2/pull/3614))
+- Docs: 添加 htmlkit 文档至最佳实践 [@BlueGlassBlock](https://github.com/BlueGlassBlock) ([#3682](https://github.com/nonebot/nonebot2/pull/3682))
+- Docs: 修复 userinfo 插件链接 [@XieXiLin2](https://github.com/XieXiLin2) ([#3660](https://github.com/nonebot/nonebot2/pull/3660))
+- Docs: 升级 docusaurus 3.8.1 [@StarHeartHunt](https://github.com/StarHeartHunt) ([#3649](https://github.com/nonebot/nonebot2/pull/3649))
+- Docs: 更新文档《手动创建项目》 [@Chen-Luan](https://github.com/Chen-Luan) ([#3623](https://github.com/nonebot/nonebot2/pull/3623))
+- Docs: 增加 B站直播间 适配器说明 [@MingxuanGame](https://github.com/MingxuanGame) ([#3636](https://github.com/nonebot/nonebot2/pull/3636))
+- Docs: 增加 VoceChat 适配器说明 [@5656565566](https://github.com/5656565566) ([#3627](https://github.com/nonebot/nonebot2/pull/3627))
+
+### 💫 杂项
+
+- CI: 严格约束 `test_depend` CPython 版本范围 [@StarHeartHunt](https://github.com/StarHeartHunt) ([#3713](https://github.com/nonebot/nonebot2/pull/3713))
+- CI: 升级文档构建 node 版本 [@StarHeartHunt](https://github.com/StarHeartHunt) ([#3668](https://github.com/nonebot/nonebot2/pull/3668))
+- CI: 测试矩阵加入 Python 3.13 [@StarHeartHunt](https://github.com/StarHeartHunt) ([#3605](https://github.com/nonebot/nonebot2/pull/3605))
+
+### 🍻 插件发布
+
+- Plugin: 海龟汤游戏 [@noneflow](https://github.com/noneflow) ([#3697](https://github.com/nonebot/nonebot2/pull/3697))
+- Plugin: 每日必应壁纸 [@noneflow](https://github.com/noneflow) ([#3721](https://github.com/nonebot/nonebot2/pull/3721))
+- Plugin: pxchat [@noneflow](https://github.com/noneflow) ([#3712](https://github.com/nonebot/nonebot2/pull/3712))
+- Plugin: nonebot-plugin-memory [@noneflow](https://github.com/noneflow) ([#3701](https://github.com/nonebot/nonebot2/pull/3701))
+- Plugin: 远程文件打开 [@noneflow](https://github.com/noneflow) ([#3717](https://github.com/nonebot/nonebot2/pull/3717))
+- Plugin: MC新闻更新检测 [@noneflow](https://github.com/noneflow) ([#3699](https://github.com/nonebot/nonebot2/pull/3699))
+- Plugin: kook卡片消息编写适配插件 [@noneflow](https://github.com/noneflow) ([#3708](https://github.com/nonebot/nonebot2/pull/3708))
+- Plugin: 链接分享自动解析 [@noneflow](https://github.com/noneflow) ([#3706](https://github.com/nonebot/nonebot2/pull/3706))
+- Plugin: 怪物猎人集会码插件 [@noneflow](https://github.com/noneflow) ([#3684](https://github.com/nonebot/nonebot2/pull/3684))
+- Plugin: nonebot-plugin-htmlkit [@noneflow](https://github.com/noneflow) ([#3695](https://github.com/nonebot/nonebot2/pull/3695))
+- Plugin: 言令 [@noneflow](https://github.com/noneflow) ([#3675](https://github.com/nonebot/nonebot2/pull/3675))
+- Plugin: 算法比赛助手 [@noneflow](https://github.com/noneflow) ([#3672](https://github.com/nonebot/nonebot2/pull/3672))
+- Plugin: 复盘打卡 [@noneflow](https://github.com/noneflow) ([#3681](https://github.com/nonebot/nonebot2/pull/3681))
+- Plugin: DMP 饥荒管理平台机器人 [@noneflow](https://github.com/noneflow) ([#3616](https://github.com/nonebot/nonebot2/pull/3616))
+- Plugin: 谁是卧底小游戏 [@noneflow](https://github.com/noneflow) ([#3629](https://github.com/nonebot/nonebot2/pull/3629))
+- Plugin: 夸克自动转存 [@noneflow](https://github.com/noneflow) ([#3671](https://github.com/nonebot/nonebot2/pull/3671))
+- Plugin: 禁止复读 [@noneflow](https://github.com/noneflow) ([#3644](https://github.com/nonebot/nonebot2/pull/3644))
+- Plugin: 蔚蓝档案今日运势 [@noneflow](https://github.com/noneflow) ([#3653](https://github.com/nonebot/nonebot2/pull/3653))
+- Plugin: 分布式黑名单插件 [@noneflow](https://github.com/noneflow) ([#3655](https://github.com/nonebot/nonebot2/pull/3655))
+- Plugin: 图片手办化 [@noneflow](https://github.com/noneflow) ([#3662](https://github.com/nonebot/nonebot2/pull/3662))
+- Plugin: Akash Image Generator [@noneflow](https://github.com/noneflow) ([#3651](https://github.com/nonebot/nonebot2/pull/3651))
+- Plugin: 让我看看！！ [@noneflow](https://github.com/noneflow) ([#3648](https://github.com/nonebot/nonebot2/pull/3648))
+- Plugin: ImageLibrary [@noneflow](https://github.com/noneflow) ([#3620](https://github.com/nonebot/nonebot2/pull/3620))
+- Plugin: 抽象 [@noneflow](https://github.com/noneflow) ([#3638](https://github.com/nonebot/nonebot2/pull/3638))
+- Plugin: 卖若插件 [@noneflow](https://github.com/noneflow) ([#3631](https://github.com/nonebot/nonebot2/pull/3631))
+- Plugin: HuaEr聊天bot [@noneflow](https://github.com/noneflow) ([#3564](https://github.com/nonebot/nonebot2/pull/3564))
+- Plugin: Remove nonebot_plugin_cnrail [@noneflow](https://github.com/noneflow) ([#3645](https://github.com/nonebot/nonebot2/pull/3645))
+- Plugin: Remove nonebot_plugin_pingti [@noneflow](https://github.com/noneflow) ([#3646](https://github.com/nonebot/nonebot2/pull/3646))
+- Plugin: Anipusher推送机 [@noneflow](https://github.com/noneflow) ([#3582](https://github.com/nonebot/nonebot2/pull/3582))
+- Plugin: nonebot-plugin-simple-setu [@noneflow](https://github.com/noneflow) ([#3594](https://github.com/nonebot/nonebot2/pull/3594))
+- Plugin: Alisten [@noneflow](https://github.com/noneflow) ([#3635](https://github.com/nonebot/nonebot2/pull/3635))
+- Plugin: MC玩家皮肤渲染 [@noneflow](https://github.com/noneflow) ([#3613](https://github.com/nonebot/nonebot2/pull/3613))
+- Plugin: EconomyValue [@noneflow](https://github.com/noneflow) ([#3566](https://github.com/nonebot/nonebot2/pull/3566))
+
+### 🍻 机器人发布
+
+- Bot: Amrita [@noneflow](https://github.com/noneflow) ([#3641](https://github.com/nonebot/nonebot2/pull/3641))
+
+### 🍻 适配器发布
+
+- Adapter: B站直播间 [@noneflow](https://github.com/noneflow) ([#3592](https://github.com/nonebot/nonebot2/pull/3592))
+- Adapter: nonebot-adapter-vocechat [@noneflow](https://github.com/noneflow) ([#3536](https://github.com/nonebot/nonebot2/pull/3536))
+
 ## v2.4.3
 
 ### 🚀 新功能

website/versioned_docs/version-2.4.1/best-practice/alconna/README.mdx

@@ -1,141 +0,0 @@
----
-sidebar_position: 1
-description: Alconna 命令解析拓展
-
-slug: /best-practice/alconna/
----
-
-import Tabs from "@theme/Tabs";
-import TabItem from "@theme/TabItem";
-
-# Alconna 插件
-
-[`nonebot-plugin-alconna`](https://github.com/nonebot/plugin-alconna) 是一类提供了拓展响应规则的插件。
-该插件使用 [Alconna](https://github.com/ArcletProject/Alconna) 作为命令解析器，
-是一个简单、灵活、高效的命令参数解析器，并且不局限于解析命令式字符串。
-
-该插件提供了一类新的事件响应器辅助函数 `on_alconna`，以及 `AlconnaResult` 等依赖注入函数。
-
-该插件声明了一个 `Matcher` 的子类 `AlconnaMatcher`，并在 `AlconnaMatcher` 中添加了一些新的方法，例如：
-
-- `assign`：基于 `Alconna` 解析结果，执行满足目标路径的处理函数
-- `dispatch`：类似 `CommandGroup`，对目标路径创建一个新的 `AlconnaMatcher`，并将解析结果分配给该 `AlconnaMatcher`
-- `got_path`：类似 `got`，但是可以指定目标路径，并且能够验证解析结果是否可用
-- ...
-
-基于 `Alconna` 的特性，该插件同时提供了一系列便捷的消息段标注。
-标注可用于在 `Alconna` 中匹配消息中除 text 外的其他消息段，也可用于快速创建各适配器下的消息段。所有标注位于 `nonebot_plugin_alconna.adapters` 中。
-
-该插件同时通过提供 `UniMessage` (通用消息模型) 实现了**跨平台接收和发送消息**的功能。
-
-## 安装插件
-
-在使用前请先安装 `nonebot-plugin-alconna` 插件至项目环境中，可参考[获取商店插件](../../tutorial/store.mdx#安装插件)来了解并选择安装插件的方式。如：
-
-在**项目目录**下执行以下命令：
-
-<Tabs groupId="install">
-<TabItem value="cli" label="使用 nb-cli">
-
-```shell
-nb plugin install nonebot-plugin-alconna
-```
-
-</TabItem>
-<TabItem value="pip" label="使用 pip">
-
-```shell
-pip install nonebot-plugin-alconna
-```
-
-</TabItem>
-
-<TabItem value="pdm" label="使用 pdm">
-
-```shell
-pdm add nonebot-plugin-alconna
-```
-
-</TabItem>
-</Tabs>
-
-## 导入插件
-
-由于 `nonebot-plugin-alconna` 作为插件，因此需要在使用前对其进行**加载**并**导入**其中的 `on_alconna` 来使用命令拓展。使用 `require` 方法可轻松完成这一过程，可参考 [跨插件访问](../../advanced/requiring.md) 一节进行了解。
-
-```python
-from nonebot import require
-
-require("nonebot_plugin_alconna")
-
-from nonebot_plugin_alconna import on_alconna
-```
-
-## 使用插件
-
-在前面的[深入指南](../../appendices/session-control.mdx)中，我们已经得到了一个天气插件。
-现在我们将使用 `Alconna` 来改写这个插件。
-
-<details>
-  <summary>插件示例</summary>
-
-```python title=weather/__init__.py
-from nonebot import on_command
-from nonebot.rule import to_me
-from nonebot.matcher import Matcher
-from nonebot.adapters import Message
-from nonebot.params import CommandArg, ArgPlainText
-
-weather = on_command("天气", rule=to_me(), aliases={"weather", "天气预报"})
-
-@weather.handle()
-async def handle_function(matcher: Matcher, args: Message = CommandArg()):
-    if args.extract_plain_text():
-        matcher.set_arg("location", args)
-
-@weather.got("location", prompt="请输入地名")
-async def got_location(location: str = ArgPlainText()):
-    if location not in ["北京", "上海", "广州", "深圳"]:
-        await weather.reject(f"你想查询的城市 {location} 暂不支持，请重新输入！")
-    await weather.finish(f"今天{location}的天气是...")
-```
-
-</details>
-
-```python {5-9,13-15,17-18}
-from nonebot.rule import to_me
-from arclet.alconna import Alconna, Args
-from nonebot_plugin_alconna import Match, on_alconna
-
-weather = on_alconna(
-    Alconna("天气", Args["location?", str]),
-    aliases={"weather", "天气预报"},
-    rule=to_me(),
-)
-
-
-@weather.handle()
-async def handle_function(location: Match[str]):
-    if location.available:
-        weather.set_path_arg("location", location.result)
-
-@weather.got_path("location", prompt="请输入地名")
-async def got_location(location: str):
-    if location not in ["北京", "上海", "广州", "深圳"]:
-        await weather.reject(f"你想查询的城市 {location} 暂不支持，请重新输入！")
-    await weather.finish(f"今天{location}的天气是...")
-```
-
-在上面的代码中，我们使用 `Alconna` 来解析命令，`on_alconna` 用来创建响应器，使用 `Match` 来获取解析结果。
-
-关于更多 `Alconna` 的使用方法，可参考 [Alconna 文档](https://arclet.top/docs/tutorial/alconna)，
-或阅读 [Alconna 基本介绍](./command.md) 一节。
-
-关于更多 `on_alconna` 的使用方法，可参考 [插件文档](https://github.com/nonebot/plugin-alconna/blob/master/docs.md)，
-或阅读 [响应规则的使用](./matcher.mdx) 一节。
-
-## 交流与反馈
-
-QQ 交流群: [🔗 链接](https://jq.qq.com/?_wv=1027&k=PUPOnCSH)
-
-友链: [📚 文档](https://graiax.cn/guide/message_parser/alconna.html)

website/versioned_docs/version-2.4.1/best-practice/alconna/_category_.json

@@ -1,4 +0,0 @@
-{
-  "label": "Alconna 命令解析拓展",
-  "position": 6
-}

website/versioned_docs/version-2.4.1/best-practice/alconna/matcher.mdx

@@ -1,607 +0,0 @@
----
-sidebar_position: 3
-description: 响应规则的使用
----
-
-import Messenger from "@site/src/components/Messenger";
-
-# Alconna 插件
-
-展示：
-
-```python
-from nonebot_plugin_alconna import At, Image, on_alconna
-from arclet.alconna import Args, Option, Alconna, Arparma, MultiVar, Subcommand
-
-
-alc = Alconna(
-    ["/", "!"],
-    "role-group",
-    Subcommand(
-        "add",
-        Args["name", str],
-        Option("member", Args["target", MultiVar(At)]),
-    ),
-    Option("list"),
-    Option("icon", Args["icon", Image])
-)
-rg = on_alconna(alc, auto_send_output=True)
-
-
-@rg.handle()
-async def _(result: Arparma):
-    if result.find("list"):
-        img: bytes = await gen_role_group_list_image()
-        await rg.finish(Image(raw=img))
-    if result.find("add"):
-        group = await create_role_group(result.query[str]("add.name"))
-        if result.find("add.member"):
-            ats = result.query[tuple[At, ...]]("add.member.target")
-            group.extend(member.target for member in ats)
-        await rg.finish("添加成功")
-```
-
-## 响应器使用
-
-本插件基于 **Alconna**，为 **Nonebot** 提供了一类新的事件响应器辅助函数 `on_alconna`：
-
-```python
-def on_alconna(
-    command: Alconna | str,
-    skip_for_unmatch: bool = True,
-    auto_send_output: bool = False,
-    aliases: set[str | tuple[str, ...]] | None = None,
-    comp_config: CompConfig | None = None,
-    extensions: list[type[Extension] | Extension] | None = None,
-    exclude_ext: list[type[Extension] | str] | None = None,
-    use_origin: bool = False,
-    use_cmd_start: bool = False,
-    use_cmd_sep: bool = False,
-    **kwargs,
-    ...,
-):
-```
-
-- `command`: Alconna 命令或字符串，字符串将通过 `AlconnaFormat` 转换为 Alconna 命令
-- `skip_for_unmatch`: 是否在命令不匹配时跳过该响应
-- `auto_send_output`: 是否自动发送输出信息并跳过响应
-- `aliases`: 命令别名， 作用类似于 `on_command` 中的 aliases
-- `comp_config`: 补全会话配置， 不传入则不启用补全会话
-- `extensions`: 需要加载的匹配扩展, 可以是扩展类或扩展实例
-- `exclude_ext`: 需要排除的匹配扩展, 可以是扩展类或扩展的id
-- `use_origin`: 是否使用未经 to_me 等处理过的消息
-- `use_cmd_start`: 是否使用 COMMAND_START 作为命令前缀
-- `use_cmd_sep`: 是否使用 COMMAND_SEP 作为命令分隔符
-
-`on_alconna` 返回的是 `Matcher` 的子类 `AlconnaMatcher` ，其拓展了如下方法：
-
-- `.assign(path, value, or_not)`: 用于对包含多个选项/子命令的命令的分派处理（具体请看[条件控制](./matcher.mdx#条件控制)）
-- `.got_path(path, prompt, middleware)`: 在 `got` 方法的基础上，会以 path 对应的参数为准，读取传入 message 的最后一个消息段并验证转换
-- `.set_path_arg(key, value)`, `.get_path_arg(key)`: 类似 `set_arg` 和 `got_arg`，为 `got_path` 的特化版本
-- `.reject_path(path[, prompt, fallback])`: 类似于 `reject_arg`，对应 `got_path`
-- `.dispatch`: 同样的分派处理，但是是类似 `CommandGroup` 一样返回新的 `AlconnaMatcher`
-- `.got`, `send`, `reject`, ... : 拓展了 prompt 类型，即支持使用 `UniMessage` 作为 prompt
-
-实例：
-
-```python
-from nonebot import require
-require("nonebot_plugin_alconna")
-
-from arclet.alconna import Alconna, Option, Args
-from nonebot_plugin_alconna import on_alconna, Match, UniMessage
-
-
-login = on_alconna(Alconna(["/"], "login", Args["password?", str], Option("-r|--recall"))) # 这里["/"]指命令前缀必须是/
-
-# /login -r 触发
-@login.assign("recall")
-async def login_exit():
-    await login.finish("已退出")
-
-# /login xxx 触发
-@login.assign("password")
-async def login_handle(pw: Match[str]):
-    if pw.available:
-        login.set_path_arg("password", pw.result)
-
-# /login 触发
-@login.got_path("password", prompt=UniMessage.template("{:At(user, $event.get_user_id())} 请输入密码"))
-async def login_got(password: str):
-	assert password
-	await login.send("登录成功")
-```
-
-## 依赖注入
-
-本插件提供了一系列依赖注入函数，便于在响应函数中获取解析结果：
-
-- `AlconnaResult`: `CommandResult` 类型的依赖注入函数
-- `AlconnaMatches`: `Arparma` 类型的依赖注入函数
-- `AlconnaDuplication`: `Duplication` 类型的依赖注入函数
-- `AlconnaMatch`: `Match` 类型的依赖注入函数
-- `AlconnaQuery`: `Query` 类型的依赖注入函数
-
-同时，基于 [`Annotated` 支持](https://github.com/nonebot/nonebot2/pull/1832)，添加了两类注解：
-
-- `AlcMatches`：同 `AlconnaMatches`
-- `AlcResult`：同 `AlconnaResult`
-
-可以看到，本插件提供了几类额外的模型：
-
-- `CommandResult`: 解析结果，包括了源命令 `source: Alconna` ，解析结果 `result: Arparma`，以及可能的输出信息 `output: str | None` 字段
-- `Match`: 匹配项，表示参数是否存在于 `all_matched_args` 内，可用 `Match.available` 判断是否匹配，`Match.result` 获取匹配的值
-- `Query`: 查询项，表示参数是否可由 `Arparma.query` 查询并获得结果，可用 `Query.available` 判断是否查询成功，`Query.result` 获取查询结果
-
-**Alconna** 默认依赖注入的目标参数皆不需要使用依赖注入函数， 该效果对于 `AlconnaMatcher.got_path` 下的 Arg 同样有效：
-
-```python
-async def handle(
-    result: CommandResult,
-    arp: Arparma,
-    dup: Duplication,
-    source: Alconna,
-    abc: str,  # 类似 Match, 但是若匹配结果不存在对应字段则跳过该 handler
-    foo: Match[str],
-    bar: Query[int] = Query("ttt.bar", 0)  # Query 仍然需要一个默认值来传递 path 参数
-):
-    ...
-```
-
-:::note
-
-如果你更喜欢 Depends 式的依赖注入，`nonebot_plugin_alconna` 同时提供了一系列的依赖注入函数，他们包括：
-
-- `AlconnaResult`: `CommandResult` 类型的依赖注入函数
-- `AlconnaMatches`: `Arparma` 类型的依赖注入函数
-- `AlconnaDuplication`: `Duplication` 类型的依赖注入函数
-- `AlconnaMatch`: `Match` 类型的依赖注入函数，其能够额外传入一个 middleware 函数来处理得到的参数
-- `AlconnaQuery`: `Query` 类型的依赖注入函数，其能够额外传入一个 middleware 函数来处理得到的参数
-- `AlconnaExecResult`: 提供挂载在命令上的 callback 的返回结果 (`Dict[str, Any]`) 的依赖注入函数
-- `AlconnaExtension`: 提供指定类型的 `Extension` 的依赖注入函数
-
-:::
-
-实例:
-
-```python
-from nonebot import require
-require("nonebot_plugin_alconna")
-
-from nonebot_plugin_alconna import (
-    on_alconna,
-    Match,
-    Query,
-    AlconnaMatch,
-    AlcResult
-)
-from arclet.alconna import Alconna, Args, Option, Arparma
-
-
-test = on_alconna(
-    Alconna(
-        "test",
-        Option("foo", Args["bar", int]),
-        Option("baz", Args["qux", bool, False])
-    ),
-    auto_send_output=True
-)
-
-@test.handle()
-async def handle_test1(result: AlcResult):
-    await test.send(f"matched: {result.matched}")
-    await test.send(f"maybe output: {result.output}")
-
-@test.handle()
-async def handle_test2(result: Arparma):
-    await test.send(f"head result: {result.header_result}")
-    await test.send(f"args: {result.all_matched_args}")
-
-@test.handle()
-async def handle_test3(bar: Match[int] = AlconnaMatch("bar")):
-    if bar.available:
-        await test.send(f"foo={bar.result}")
-
-@test.handle()
-async def handle_test4(qux: Query[bool] = Query("baz.qux", False)):
-    if qux.available:
-        await test.send(f"baz.qux={qux.result}")
-```
-
-## 多平台适配
-
-本插件提供了通用消息段标注， 通用消息段序列， 使插件使用者可以忽略平台之间字段的差异
-
-响应器使用示例中使用了消息段标注，其中 `At` 属于通用标注，而 `Image` 属于 `onebot12` 适配器下的标注。
-
-具体介绍和使用请查看 [通用信息组件](./uniseg.mdx#通用消息段)
-
-本插件为以下适配器提供了专门的适配器标注：
-
-| 协议名称                                                            | 路径                                 |
-| ------------------------------------------------------------------- | ------------------------------------ |
-| [OneBot 协议](https://github.com/nonebot/adapter-onebot)            | adapters.onebot11, adapters.onebot12 |
-| [Telegram](https://github.com/nonebot/adapter-telegram)             | adapters.telegram                    |
-| [飞书](https://github.com/nonebot/adapter-feishu)                   | adapters.feishu                      |
-| [GitHub](https://github.com/nonebot/adapter-github)                 | adapters.github                      |
-| [QQ bot](https://github.com/nonebot/adapter-qq)                     | adapters.qq                          |
-| [钉钉](https://github.com/nonebot/adapter-ding)                     | adapters.ding                        |
-| [Dodo](https://github.com/nonebot/adapter-dodo)                     | adapters.dodo                        |
-| [Console](https://github.com/nonebot/adapter-console)               | adapters.console                     |
-| [开黑啦](https://github.com/Tian-que/nonebot-adapter-kaiheila)      | adapters.kook                        |
-| [Mirai](https://github.com/ieew/nonebot_adapter_mirai2)             | adapters.mirai                       |
-| [Ntchat](https://github.com/JustUndertaker/adapter-ntchat)          | adapters.ntchat                      |
-| [MineCraft](https://github.com/17TheWord/nonebot-adapter-minecraft) | adapters.minecraft                   |
-| [BiliBili Live](https://github.com/wwweww/adapter-bilibili)         | adapters.bilibili                    |
-| [Walle-Q](https://github.com/onebot-walle/nonebot_adapter_walleq)   | adapters.onebot12                    |
-| [Discord](https://github.com/nonebot/adapter-discord)               | adapters.discord                     |
-| [Red 协议](https://github.com/nonebot/adapter-red)                  | adapters.red                         |
-| [Satori 协议](https://github.com/nonebot/adapter-satori)            | adapters.satori                      |
-
-## 条件控制
-
-本插件可以通过 `assign` 来控制一个具体的响应函数是否在不满足条件时跳过响应。
-
-```python
-...
-from nonebot import require
-require("nonebot_plugin_alconna")
-...
-
-from arclet.alconna import Alconna, Subcommand, Option, Args
-from nonebot_plugin_alconna import on_alconna, CommandResult
-
-
-pip = Alconna(
-    "pip",
-    Subcommand(
-        "install", Args["pak", str],
-        Option("--upgrade"),
-        Option("--force-reinstall")
-    ),
-    Subcommand("list", Option("--out-dated"))
-)
-
-pip_cmd = on_alconna(pip)
-
-# 仅在命令为 `pip install pip` 时响应
-@pip_cmd.assign("install.pak", "pip")
-async def update(res: CommandResult):
-    ...
-
-# 仅在命令为 `pip list` 时响应
-@pip_cmd.assign("list")
-async def list_(res: CommandResult):
-    ...
-
-# 在命令为 `pip install xxx` 时响应
-@pip_cmd.assign("install")
-async def install(res: CommandResult):
-    ...
-```
-
-此外，使用 `AlconnaMatcher.dispatch` 还能像 `CommandGroup` 一样为每个分发设置独立的 matcher：
-
-```python
-update_cmd = pip_cmd.dispatch("install.pak", "pip")
-
-@update_cmd.handle()
-async def update(arp: CommandResult):
-    ...
-```
-
-另外，`AlconnaMatcher` 有类似于 `got` 的 `got_path`：
-
-```python
-from nonebot_plugin_alconna import At, Match, UniMessage, on_alconna
-
-
-test_cmd = on_alconna(Alconna("test", Args["target?", Union[str, At]]))
-
-@test_cmd.handle()
-async def tt_h(target: Match[Union[str, At]]):
-    if target.available:
-        test_cmd.set_path_arg("target", target.result)
-
-@test_cmd.got_path("target", prompt="请输入目标")
-async def tt(target: Union[str, At]):
-    await test_cmd.send(UniMessage(["ok\n", target]))
-```
-
-`got_path` 与 `assign`，`Match`，`Query` 等地方一样，都需要指明 `path` 参数 (即对应 Arg 验证的路径)
-
-`got_path` 会获取消息的最后一个消息段并转为 path 对应的类型，例如示例中 `target` 对应的 Arg 里要求 str 或 At，则 got 后用户输入的消息只有为 text 或 at 才能进入处理函数。
-
-:::tip
-
-`path` 支持 ~XXX 语法，其会把 ~ 替换为可能的父级路径：
-
-```python
- pip = Alconna(
-     "pip",
-     Subcommand(
-         "install",
-         Args["pak", str],
-         Option("--upgrade|-U"),
-         Option("--force-reinstall"),
-     ),
-     Subcommand("list", Option("--out-dated")),
- )
-
- pipcmd = on_alconna(pip)
- pip_install_cmd = pipcmd.dispatch("install")
-
-
- @pip_install_cmd.assign("~upgrade")
- async def pip1_u(pak: Query[str] = Query("~pak")):
-     await pip_install_cmd.finish(f"pip upgrading {pak.result}...")
-```
-
-:::
-
-## 响应器创建装饰
-
-本插件提供了一个 `funcommand` 装饰器, 其用于将一个接受任意参数， 返回 `str` 或 `Message` 或 `MessageSegment` 的函数转换为命令响应器：
-
-```python
-from nonebot_plugin_alconna import funcommand
-
-
-@funcommand()
-async def echo(msg: str):
-    return msg
-```
-
-其等同于：
-
-```python
-from arclet.alconna import Alconna, Args
-from nonebot_plugin_alconna import on_alconna, AlconnaMatch, Match
-
-
-echo = on_alconna(Alconna("echo", Args["msg", str]))
-
-@echo.handle()
-async def echo_exit(msg: Match[str] = AlconnaMatch("msg")):
-    await echo.finish(msg.result)
-
-```
-
-## 类Koishi构造器
-
-本插件提供了一个 `Command` 构造器，其基于 `arclet.alconna.tools` 中的 `AlconnaString`， 以类似 `Koishi` 中注册命令的方式来构建一个 **AlconnaMatcher** ：
-
-```python
-from nonebot_plugin_alconna import Command, Arparma
-
-
-book = (
-    Command("book", "测试")
-    .option("writer", "-w <id:int>")
-    .option("writer", "--anonymous", {"id": 0})
-    .usage("book [-w <id:int> | --anonymous]")
-    .shortcut("测试", {"args": ["--anonymous"]})
-    .build()
-)
-
-@book.handle()
-async def _(arp: Arparma):
-    await book.send(str(arp.options))
-```
-
-甚至，你可以设置 `action` 来设定响应行为：
-
-```python
-book = (
-    Command("book", "测试")
-    .option("writer", "-w <id:int>")
-    .option("writer", "--anonymous", {"id": 0})
-    .usage("book [-w <id:int> | --anonymous]")
-    .shortcut("测试", {"args": ["--anonymous"]})
-    .action(lambda options: str(options))  # 会自动通过 bot.send 发送
-    .build()
-)
-```
-
-## 返回值中间件
-
-在 `AlconnaMatch`，`AlconnaQuery` 或 `got_path` 中，你可以使用 `middleware` 参数来传入一个对返回值进行处理的函数：
-
-```python
-from nonebot_plugin_alconna import image_fetch
-
-
-mask_cmd = on_alconna(
-    Alconna("search", Args["img?", Image]),
-)
-
-
-@mask_cmd.handle()
-async def mask_h(matcher: AlconnaMatcher, img: Match[bytes] = AlconnaMatch("img", image_fetch)):
-    result = await search_img(img.result)
-    await matcher.send(result.content)
-```
-
-其中，`image_fetch` 是一个中间件，其接受一个 `Image` 对象，并提取图片的二进制数据返回。
-
-## 匹配拓展
-
-本插件提供了一个 `Extension` 类，其用于自定义 AlconnaMatcher 的部分行为
-
-例如一个 `LLMExtension` 可以如下实现 (仅举例)：
-
-```python
-from nonebot_plugin_alconna import Extension, Alconna, on_alconna, Interface
-
-
-class LLMExtension(Extension):
-    @property
-    def priority(self) -> int:
-        return 10
-
-    @property
-    def id(self) -> str:
-        return "LLMExtension"
-
-    def __init__(self, llm):
-      self.llm = llm
-
-    def post_init(self, alc: Alconna) -> None:
-        self.llm.add_context(alc.command, alc.meta.description)
-
-    async def receive_wrapper(self, bot, event, receive):
-        resp = await self.llm.input(str(receive))
-        return receive.__class__(resp.content)
-
-    def before_catch(self, name, annotation, default):
-        return name == "llm"
-
-    def catch(self, interface: Interface):
-        if interface.name == "llm":
-            return self.llm
-
-matcher = on_alconna(
-    Alconna(...),
-    extensions=[LLMExtension(LLM)]
-)
-...
-```
-
-那么添加了 `LLMExtension` 的响应器便能接受任何能通过 llm 翻译为具体命令的自然语言消息，同时可以在响应器中为所有 `llm` 参数注入模型变量。
-
-目前 `Extension` 的功能有：
-
-- `validate`: 对于事件的来源适配器或 bot 选择是否接受响应
-- `output_converter`: 输出信息的自定义转换方法
-- `message_provider`: 从传入事件中自定义提取消息的方法
-- `receive_provider`: 对传入的消息 (Message 或 UniMessage) 的额外处理
-- `context_provider`: 对命令上下文的额外处理
-- `permission_check`: 命令对消息解析并确认头部匹配（即确认选择响应）时对发送者的权限判断
-- `parse_wrapper`: 对命令解析结果的额外处理
-- `send_wrapper`: 对发送的消息 (Message 或 UniMessage) 的额外处理
-- `before_catch`: 自定义依赖注入的绑定确认函数
-- `catch`: 自定义依赖注入处理函数
-- `post_init`: 响应器创建后对命令对象的额外处理
-
-例如内置的 `DiscordSlashExtension`，其可自动将 Alconna 对象翻译成 slash 指令并注册，且将收到的指令交互事件转为指令供命令解析：
-
-```python
-from nonebot_plugin_alconna import Match, on_alconna
-from nonebot_plugin_alconna.builtins.extensions.discord import DiscordSlashExtension
-
-
-alc = Alconna(
-    ["/"],
-    "permission",
-    Subcommand("add", Args["plugin", str]["priority?", int]),
-    Option("remove", Args["plugin", str]["time?", int]),
-    meta=CommandMeta(description="权限管理"),
-)
-
-matcher = on_alconna(alc, extensions=[DiscordSlashExtension()])
-
-@matcher.assign("add")
-async def add(plugin: Match[str], priority: Match[int]):
-    await matcher.finish(f"added {plugin.result} with {priority.result if priority.available else 0}")
-
-@matcher.assign("remove")
-async def remove(plugin: Match[str], time: Match[int]):
-    await matcher.finish(f"removed {plugin.result} with {time.result if time.available else -1}")
-```
-
-目前插件提供了 4 个内置的 `Extension`，它们在 `nonebot_plugin_alconna.builtins.extensions` 下：
-
-- `ReplyRecordExtension`: 将消息事件中的回复暂存在 extension 中，使得解析用的消息不带回复信息，同时可以在后续的处理中获取回复信息。
-- `DiscordSlashExtension`: 将 Alconna 的命令自动转换为 Discord 的 Slash Command，并将 Slash Command 的交互事件转换为消息交给 Alconna 处理。
-- `MarkdownOutputExtension`: 将 Alconna 的自动输出转换为 Markdown 格式
-- `TelegramSlashExtension`: 将 Alconna 的命令注册在 Telegram 上以获得提示。
-
-:::tip
-
-全局的 Extension 可延迟加载 (即若有全局拓展加载于部分 AlconnaMatcher 之后，这部分响应器会被追加拓展)
-
-:::
-
-## 补全会话
-
-补全会话基于 [`半自动补全`](./command.md#半自动补全)，用于指令参数缺失或参数错误时给予交互式提示，类似于 `got-reject`：
-
-```python
-from nonebot_plugin_alconna import Alconna, Args, Field, At, on_alconna
-
-alc = Alconna(
-    "添加教师",
-    Args["name", str, Field(completion=lambda: "请输入姓名")],
-    Args["phone", int, Field(completion=lambda: "请输入手机号")],
-    Args["at", [str, At], Field(completion=lambda: "请输入教师号")],
-)
-
-cmd = on_alconna(alc, comp_config={"lite": True}, skip_for_unmatch=False)
-
-@cmd.handle()
-async def handle(result: Arparma):
-    cmd.finish("添加成功")
-```
-
-此时，当用户输入 `添加教师` 时，会自动提示用户输入姓名，手机号和教师号，用户输入后会自动进入下一个提示：
-
-<Messenger
-  msgs={[
-    { position: "right", msg: "添加教师" },
-    { position: "left", msg: "以下是建议的输入： \n- name: 请输入姓名" },
-    { position: "right", msg: "foo" },
-    { position: "left", msg: "以下是建议的输入： \n- phone: 请输入手机号" },
-    { position: "right", msg: "12345" },
-    { position: "left", msg: "以下是建议的输入： \n- at: 请输入教师号" },
-    { position: "right", msg: "@me" },
-    { position: "left", msg: "添加成功" },
-  ]}
-/>
-
-补全会话配置如下：
-
-```python
-class CompConfig(TypedDict):
-    tab: NotRequired[str]
-    """用于切换提示的指令的名称"""
-    enter: NotRequired[str]
-    """用于输入提示的指令的名称"""
-    exit: NotRequired[str]
-    """用于退出会话的指令的名称"""
-    timeout: NotRequired[int]
-    """超时时间"""
-    hide_tabs: NotRequired[bool]
-    """是否隐藏所有提示"""
-    hides: NotRequired[Set[Literal["tab", "enter", "exit"]]]
-    """隐藏的指令"""
-    disables: NotRequired[Set[Literal["tab", "enter", "exit"]]]
-    """禁用的指令"""
-    lite: NotRequired[bool]
-    """是否使用简洁版本的补全会话（相当于同时配置 disables、hides、hide_tabs）"""
-```
-
-## 内置插件
-
-类似于 Nonebot 本身提供的内置插件，`nonebot_plugin_alconna` 提供了两个内置插件：`echo` 和 `help`。
-
-你可以用本插件的 `load_builtin_plugin(s)` 来加载它们：
-
-```python
-from nonebot_plugin_alconna import load_builtin_plugins
-
-load_builtin_plugins("echo", "help")
-```
-
-其中 `help` 仅能列出所有 Alconna 指令。
-
-<Messenger
-  msgs={[
-    { position: "right", msg: "/帮助" },
-    {
-      position: "left",
-      msg: "# 当前可用的命令有:\n 0 /echo : echo 指令\n 1 /help : 显示所有命令帮助\n# 输入'命令名 -h|--help' 查看特定命令的语法",
-    },
-    { position: "right", msg: "/echo [图片]" },
-    { position: "left", msg: "[图片]" },
-  ]}
-/>