🍻 publish plugin 拍屏检测 (#3997 )

📝 Update changelog
🍻 publish plugin Permission (#4021 )
2026-05-31 08:02:36 +00:00 · 2026-05-28 00:04:14 +08:00 · 2026-05-25 15:17:59 +00:00 · 2026-05-25 15:16:51 +00:00 · 2026-05-24 06:21:02 +00:00 · 2026-05-24 06:19:51 +00:00
359 changed files with 18308 additions and 11936 deletions
@@ -3,10 +3,10 @@
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/jsburckhardt/devcontainer-features/uv:1": {},
-    "ghcr.io/devcontainers/features/node:1": {},
+    "ghcr.io/devcontainers/features/node:2": {},
    "ghcr.io/meaningful-ooo/devcontainer-features/fish:2": {}
  },
-  "postCreateCommand": "./scripts/setup-envs.sh",
+  "postCreateCommand": "corepack enable && COREPACK_ENABLE_DOWNLOAD_PROMPT=0 ./scripts/setup-envs.sh",
  "customizations": {
    "vscode": {
      "settings": {
@@ -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"
-        cache: "yarn"
+        node-version: lts/*
+        cache: yarn

    - run: yarn install --frozen-lockfile
      shell: bash
@@ -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 }}
@@ -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
@@ -56,7 +56,7 @@ jobs:
          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

      - name: Upload coverage report
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
        with:
          env_vars: OS,PYTHON_VERSION,PYDANTIC_VERSION
          files: ./tests/coverage.xml
@@ -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/*
@@ -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
@@ -2,17 +2,14 @@ name: Release Drafter

 on:
  push:
-    tags:
-      - v*
-  pull_request_target:
    branches:
      - master
-    types:
-      - closed
+    tags:
+      - v*

 jobs:
  update-release-draft:
-    if: github.event_name == 'pull_request_target'
+    if: github.ref == 'refs/heads/master'
    runs-on: ubuntu-latest
    concurrency:
      group: pull-request-changelog
@@ -25,7 +22,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 +67,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
@@ -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 }}

@@ -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
@@ -13,7 +13,7 @@ jobs:
      cancel-in-progress: true

    steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

@@ -24,7 +24,7 @@ jobs:

    steps:
      - name: Set Commit Status
-        uses: actions/github-script@v7
+        uses: actions/github-script@v9
        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@v9
        if: always()
        with:
          script: |
@@ -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: |
@@ -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.12
    hooks:
      - id: ruff-check
        args: [--fix]
@@ -1 +1,3 @@
 .github/**/*.md
+website/docs/tutorial/application.mdx
+website/versioned_docs/*/tutorial/application.mdx
@@ -21,7 +21,7 @@ _✨ 跨平台 Python 异步机器人框架 ✨_
  <a href="https://pypi.python.org/pypi/nonebot2">
    <img src="https://img.shields.io/pypi/v/nonebot2?logo=python&logoColor=edb641" alt="pypi">
  </a>
-  <img src="https://img.shields.io/badge/python-3.9+-blue?logo=python&logoColor=edb641" alt="python">
+  <img src="https://img.shields.io/badge/python-3.10+-blue?logo=python&logoColor=edb641" alt="python">
  <a href="https://github.com/psf/black">
    <img src="https://img.shields.io/badge/code%20style-black-000000.svg?logo=python&logoColor=edb641" alt="black">
  </a>
@@ -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 框架，可自定义替换、组合

@@ -313,4 +313,59 @@
    ],
    "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": "nonebot.adapters.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
+  },
+  {
+    "module_name": "nonebot.adapters.wxclaw",
+    "project_link": "nonebot-adapter-wxclaw",
+    "name": "WxClaw",
+    "desc": "基于 openclaw-weixin 协议的 NoneBot2 微信智能体适配器",
+    "author_id": 51957264,
+    "homepage": "https://github.com/shoucandanghehe/nonebot-adapter-wxclaw",
+    "tags": [
+      {
+        "label": "微信",
+        "color": "#1aad19"
+      }
+    ],
+    "is_official": false
+  },
 ]
@@ -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
+  },
 ]
@@ -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 文件配置。
@@ -9,29 +9,31 @@ 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,
+    TypeAlias,
    TypeVar,
-    Union,
+    cast,
+    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

@@ -44,18 +46,28 @@ if TYPE_CHECKING:
    CVC = TypeVar("CVC", bound=_CustomValidationClass)


+ModelDumpIncEx: TypeAlias = (
+    set[int]
+    | set[str]
+    | dict[int, "ModelDumpIncEx"]
+    | dict[str, "ModelDumpIncEx"]
+    | None
+)
+"""Common include/exclude shape accepted by all supported pydantic versions."""
+
+
 __all__ = (
    "DEFAULT_CONFIG",
    "PYDANTIC_V2",
    "ConfigDict",
    "FieldInfo",
+    "LegacyUnionField",
    "ModelField",
    "PydanticUndefined",
    "PydanticUndefinedType",
    "Required",
    "TypeAdapter",
    "custom_validation",
-    "extract_field_info",
    "field_validator",
    "model_config",
    "model_dump",
@@ -72,7 +84,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 +107,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 +138,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 +169,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 +224,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 +231,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,16 +242,17 @@ if PYDANTIC_V2:  # pragma: pydantic-v2

    def model_dump(
        model: BaseModel,
-        include: Optional[set[str]] = None,
-        exclude: Optional[set[str]] = None,
+        include: ModelDumpIncEx = None,
+        exclude: ModelDumpIncEx = None,
        by_alias: bool = False,
        exclude_unset: bool = False,
        exclude_defaults: bool = False,
        exclude_none: bool = False,
    ) -> dict[str, Any]:
        return model.model_dump(
-            include=include,
-            exclude=exclude,
+            # Nested types cannot be inferred correctly
+            include=cast(Any, include),
+            exclude=cast(Any, exclude),
            by_alias=by_alias,
            exclude_unset=exclude_unset,
            exclude_defaults=exclude_defaults,
@@ -232,7 +263,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 +317,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 +327,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 +362,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 +387,7 @@ else:  # pragma: pydantic-v1
            self,
            type: type[T],
            *,
-            config: Optional[ConfigDict] = ...,
+            config: ConfigDict | None = ...,
        ) -> None: ...

        @overload
@@ -346,14 +395,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 +410,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 +428,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 +436,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 +459,7 @@ else:  # pragma: pydantic-v1
            ModelField._construct(
                name=model_field.name,
                annotation=model_field.annotation,
-                field_info=FieldInfo(
-                    **extract_field_info(model_field.field_info),
-                ),
+                field_info=FieldInfo._inherit_construct(model_field.field_info),
            )
            for model_field in model.__fields__.values()
        ]
@@ -432,16 +470,16 @@ else:  # pragma: pydantic-v1

    def model_dump(
        model: BaseModel,
-        include: Optional[set[str]] = None,
-        exclude: Optional[set[str]] = None,
+        include: ModelDumpIncEx = None,
+        exclude: ModelDumpIncEx = None,
        by_alias: bool = False,
        exclude_unset: bool = False,
        exclude_defaults: bool = False,
        exclude_none: bool = False,
    ) -> dict[str, Any]:
        return model.dict(
-            include=include,
-            exclude=exclude,
+            include=cast(Any, include),
+            exclude=cast(Any, exclude),
            by_alias=by_alias,
            exclude_unset=exclude_unset,
            exclude_defaults=exclude_defaults,
@@ -464,7 +502,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)

@@ -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_extensions import TypeAlias, get_args, get_origin
+from typing import TYPE_CHECKING, Any, 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[
-    Path, str, list[Union[Path, str]], tuple[Union[Path, str], ...]
-]
+DOTENV_TYPE: TypeAlias = Path | str | list[Path | str] | tuple[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"],
-        env_file: Optional[DOTENV_TYPE] = ENV_FILE_SENTINEL,
-        env_file_encoding: Optional[str] = None,
-        case_sensitive: Optional[bool] = None,
-        env_nested_delimiter: Optional[str] = None,
+        settings_cls: type[BaseModel],
+        env_file: DOTENV_TYPE | None,
+        env_file_encoding: str,
+        case_sensitive: bool | None = False,
+        env_nested_delimiter: str | None = None,
    ) -> None:
        super().__init__(settings_cls)
-        self.env_file = (
-            env_file
-            if env_file is not ENV_FILE_SENTINEL
-            else self.config.get("env_file", (".env",))
-        )
-        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)
-        )
+        self.env_file = env_file
+        self.env_file_encoding = env_file_encoding
+        self.case_sensitive = case_sensitive
+        self.env_nested_delimiter = env_nested_delimiter

    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]]
-    ) -> dict[str, Optional[str]]:
+        self, env_vars: Mapping[str, str | None]
+    ) -> 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(
-        self, field: Optional[ModelField], key: str
-    ) -> Optional[ModelField]:
+    def _next_field(self, field: ModelField | None, key: str) -> ModelField | None:
        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_file_vars: dict[str, Optional[str]],
+        env_vars: dict[str, str | None],
+        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_encoding: Optional[str] = None,
-        _env_nested_delimiter: Optional[str] = None,
+        _env_file: DOTENV_TYPE | None = ENV_FILE_SENTINEL,
+        _env_file_encoding: str | None = 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_encoding=_env_file_encoding,
-                env_nested_delimiter=_env_nested_delimiter,
+                env_file=env_file,
+                env_file_encoding=env_file_encoding,
+                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_encoding: Optional[str] = None,
-        env_nested_delimiter: Optional[str] = None,
+        env_file: DOTENV_TYPE | None,
+        env_file_encoding: str,
+        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
@@ -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)
@@ -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
@@ -9,6 +9,7 @@ FrontMatter:
    description: nonebot.drivers 模块
 """

+from nonebot.internal.driver import DEFAULT_TIMEOUT as DEFAULT_TIMEOUT
 from nonebot.internal.driver import URL as URL
 from nonebot.internal.driver import ASGIMixin as ASGIMixin
 from nonebot.internal.driver import Cookies as Cookies
@@ -31,6 +32,7 @@ from nonebot.internal.driver import WebSocketServerSetup as WebSocketServerSetup
 from nonebot.internal.driver import combine_driver as combine_driver

 __autodoc__ = {
+    "DEFAULT_TIMEOUT": True,
    "URL": True,
    "Cookies": True,
    "Request": True,
@@ -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
@@ -38,6 +38,7 @@ from nonebot.drivers import WebSocket as BaseWebSocket
 from nonebot.drivers.none import Driver as NoneDriver
 from nonebot.exception import WebSocketClosed
 from nonebot.internal.driver import (
+    DEFAULT_TIMEOUT,
    Cookies,
    CookieTypes,
    HeaderTypes,
@@ -45,6 +46,8 @@ from nonebot.internal.driver import (
    Timeout,
    TimeoutTypes,
 )
+from nonebot.log import logger
+from nonebot.utils import UNSET, UnsetType, exclude_unset

 try:
    import aiohttp
@@ -62,11 +65,11 @@ class Session(HTTPClientSession):
        params: QueryTypes = None,
        headers: HeaderTypes = None,
        cookies: CookieTypes = None,
-        version: Union[str, HTTPVersion] = HTTPVersion.H11,
-        timeout: TimeoutTypes = None,
-        proxy: Optional[str] = None,
+        version: str | HTTPVersion = HTTPVersion.H11,
+        timeout: TimeoutTypes | UnsetType = UNSET,
+        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

@@ -85,15 +88,32 @@ class Session(HTTPClientSession):
        else:
            raise RuntimeError(f"Unsupported HTTP version: {version}")

+        _timeout = None
        if isinstance(timeout, Timeout):
-            self._timeout = aiohttp.ClientTimeout(
-                total=timeout.total,
-                connect=timeout.connect,
-                sock_read=timeout.read,
+            timeout_kwargs: dict[str, float | None] = exclude_unset(
+                {
+                    "total": timeout.total,
+                    "connect": timeout.connect,
+                    "sock_read": timeout.read,
+                }
            )
-        else:
-            self._timeout = aiohttp.ClientTimeout(timeout)
+            if timeout_kwargs:
+                _timeout = aiohttp.ClientTimeout(**timeout_kwargs)  # type: ignore
+        elif timeout is not UNSET:
+            _timeout = aiohttp.ClientTimeout(connect=timeout, sock_read=timeout)

+        if _timeout is None:
+            _timeout = aiohttp.ClientTimeout(
+                **exclude_unset(
+                    {
+                        "total": DEFAULT_TIMEOUT.total,
+                        "connect": DEFAULT_TIMEOUT.connect,
+                        "sock_read": DEFAULT_TIMEOUT.read,
+                    }
+                )
+            )
+
+        self._timeout = _timeout
        self._proxy = proxy

    @property
@@ -102,6 +122,25 @@ class Session(HTTPClientSession):
            raise RuntimeError("Session is not initialized")
        return self._client

+    def _get_timeout(self, timeout: TimeoutTypes | UnsetType) -> aiohttp.ClientTimeout:
+        _timeout = None
+        if isinstance(timeout, Timeout):
+            timeout_kwargs: dict[str, float | None] = exclude_unset(
+                {
+                    "total": timeout.total,
+                    "connect": timeout.connect,
+                    "sock_read": timeout.read,
+                }
+            )
+            if timeout_kwargs:
+                _timeout = aiohttp.ClientTimeout(**timeout_kwargs)  # type: ignore
+        elif timeout is not UNSET:
+            _timeout = aiohttp.ClientTimeout(connect=timeout, sock_read=timeout)
+
+        if _timeout is None:
+            return self._timeout
+        return _timeout
+
    @override
    async def request(self, setup: Request) -> Response:
        if self._params:
@@ -121,15 +160,6 @@ class Session(HTTPClientSession):
            if cookie.value is not None
        )

-        if isinstance(setup.timeout, Timeout):
-            timeout = aiohttp.ClientTimeout(
-                total=setup.timeout.total,
-                connect=setup.timeout.connect,
-                sock_read=setup.timeout.read,
-            )
-        else:
-            timeout = aiohttp.ClientTimeout(setup.timeout)
-
        async with await self.client.request(
            setup.method,
            url,
@@ -138,7 +168,7 @@ class Session(HTTPClientSession):
            cookies=cookies,
            headers=setup.headers,
            proxy=setup.proxy or self._proxy,
-            timeout=timeout,
+            timeout=self._get_timeout(setup.timeout),
        ) as response:
            return Response(
                response.status,
@@ -171,15 +201,6 @@ class Session(HTTPClientSession):
            if cookie.value is not None
        )

-        if isinstance(setup.timeout, Timeout):
-            timeout = aiohttp.ClientTimeout(
-                total=setup.timeout.total,
-                connect=setup.timeout.connect,
-                sock_read=setup.timeout.read,
-            )
-        else:
-            timeout = aiohttp.ClientTimeout(setup.timeout)
-
        async with self.client.request(
            setup.method,
            url,
@@ -188,14 +209,29 @@ class Session(HTTPClientSession):
            cookies=cookies,
            headers=setup.headers,
            proxy=setup.proxy or self._proxy,
-            timeout=timeout,
+            timeout=self._get_timeout(setup.timeout),
        ) as response:
            response_headers = response.headers.copy()
+            # aiohttp does not guarantee fixed-size chunks; re-chunk to exact size
+            buffer = bytearray()
            async for chunk in response.content.iter_chunked(chunk_size):
+                if not chunk:
+                    continue
+                buffer.extend(chunk)
+                while len(buffer) >= chunk_size:
+                    out = bytes(buffer[:chunk_size])
+                    del buffer[:chunk_size]
                    yield Response(
                        response.status,
                        headers=response_headers,
-                    content=chunk,
+                        content=out,
+                        request=setup,
+                    )
+            if buffer:
+                yield Response(
+                    response.status,
+                    headers=response_headers,
+                    content=bytes(buffer),
                    request=setup,
                )

@@ -255,13 +291,49 @@ class Mixin(HTTPClientMixin, WebSocketClientMixin):
        else:
            raise RuntimeError(f"Unsupported HTTP version: {setup.version}")

+        timeout = None
        if isinstance(setup.timeout, Timeout):
-            timeout = aiohttp.ClientWSTimeout(
-                ws_receive=setup.timeout.read,  # type: ignore
-                ws_close=setup.timeout.total,  # type: ignore
+            timeout_kwargs: dict[str, float | None] = exclude_unset(
+                {
+                    "ws_receive": setup.timeout.read,
+                    "ws_close": (
+                        setup.timeout.total
+                        if setup.timeout.close is UNSET
+                        else setup.timeout.close
+                    ),
+                }
+            )
+            if timeout_kwargs:
+                timeout = aiohttp.ClientWSTimeout(**timeout_kwargs)
+        elif setup.timeout is not UNSET:
+            timeout = aiohttp.ClientWSTimeout(
+                ws_receive=setup.timeout,  # type: ignore
+                ws_close=setup.timeout,  # type: ignore
+            )
+
+        if timeout is None:
+            timeout = aiohttp.ClientWSTimeout(
+                **exclude_unset(
+                    {
+                        "ws_receive": DEFAULT_TIMEOUT.read,
+                        "ws_close": (
+                            DEFAULT_TIMEOUT.total
+                            if DEFAULT_TIMEOUT.close is UNSET
+                            else DEFAULT_TIMEOUT.close
+                        ),
+                    }
+                )
+            )
+
+        heartbeat = None
+        if setup.ping_interval is not UNSET:
+            heartbeat = setup.ping_interval
+
+        if isinstance(setup.timeout, Timeout) and setup.timeout.ping is not UNSET:
+            logger.warning(
+                "aiohttp driver does not expose a separate ping timeout; "
+                "the configured ping timeout will be ignored."
            )
-        else:
-            timeout = aiohttp.ClientWSTimeout(ws_close=setup.timeout or 10.0)  # type: ignore

        async with aiohttp.ClientSession(version=version, trust_env=True) as session:
            async with session.ws_connect(
@@ -270,6 +342,8 @@ class Mixin(HTTPClientMixin, WebSocketClientMixin):
                timeout=timeout,
                headers=setup.headers,
                proxy=setup.proxy,
+                autoping=heartbeat is not None,
+                heartbeat=heartbeat,
            ) as ws:
                yield WebSocket(request=setup, session=session, websocket=ws)

@@ -279,9 +353,9 @@ class Mixin(HTTPClientMixin, WebSocketClientMixin):
        params: QueryTypes = None,
        headers: HeaderTypes = None,
        cookies: CookieTypes = None,
-        version: Union[str, HTTPVersion] = HTTPVersion.H11,
-        timeout: TimeoutTypes = None,
-        proxy: Optional[str] = None,
+        version: str | HTTPVersion = HTTPVersion.H11,
+        timeout: TimeoutTypes | UnsetType = UNSET,
+        proxy: str | None = None,
    ) -> Session:
        return Session(
            params=params,
@@ -323,7 +397,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

@@ -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,
-        port: Optional[int] = None,
+        host: str | None = 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
-        files: Optional[list[tuple[str, FileTypes]]] = None
+        data: dict | None = 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":
@@ -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
@@ -34,6 +34,7 @@ from nonebot.drivers import (
 )
 from nonebot.drivers.none import Driver as NoneDriver
 from nonebot.internal.driver import (
+    DEFAULT_TIMEOUT,
    Cookies,
    CookieTypes,
    HeaderTypes,
@@ -41,6 +42,7 @@ from nonebot.internal.driver import (
    Timeout,
    TimeoutTypes,
 )
+from nonebot.utils import UNSET, UnsetType, exclude_unset

 try:
    import httpx
@@ -58,11 +60,11 @@ class Session(HTTPClientSession):
        params: QueryTypes = None,
        headers: HeaderTypes = None,
        cookies: CookieTypes = None,
-        version: Union[str, HTTPVersion] = HTTPVersion.H11,
-        timeout: TimeoutTypes = None,
-        proxy: Optional[str] = None,
+        version: str | HTTPVersion = HTTPVersion.H11,
+        timeout: TimeoutTypes | UnsetType = UNSET,
+        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
@@ -73,15 +75,34 @@ class Session(HTTPClientSession):
        self._cookies = Cookies(cookies)
        self._version = HTTPVersion(version)

+        _timeout = None
        if isinstance(timeout, Timeout):
-            self._timeout = httpx.Timeout(
-                timeout=timeout.total,
-                connect=timeout.connect,
-                read=timeout.read,
+            avg_timeout = timeout.total and timeout.total / 4
+            timeout_kwargs: dict[str, float | None] = exclude_unset(
+                {
+                    "timeout": avg_timeout,
+                    "connect": timeout.connect,
+                    "read": timeout.read,
+                }
            )
-        else:
-            self._timeout = httpx.Timeout(timeout)
+            if timeout_kwargs:
+                _timeout = httpx.Timeout(**timeout_kwargs)
+        elif timeout is not UNSET:
+            _timeout = httpx.Timeout(timeout)

+        if _timeout is None:
+            avg_timeout = DEFAULT_TIMEOUT.total and DEFAULT_TIMEOUT.total / 4
+            _timeout = httpx.Timeout(
+                **exclude_unset(
+                    {
+                        "timeout": avg_timeout,
+                        "connect": DEFAULT_TIMEOUT.connect,
+                        "read": DEFAULT_TIMEOUT.read,
+                    }
+                )
+            )
+
+        self._timeout = _timeout
        self._proxy = proxy

    @property
@@ -90,17 +111,28 @@ class Session(HTTPClientSession):
            raise RuntimeError("Session is not initialized")
        return self._client

+    def _get_timeout(self, timeout: TimeoutTypes | UnsetType) -> httpx.Timeout:
+        _timeout = None
+        if isinstance(timeout, Timeout):
+            avg_timeout = timeout.total and timeout.total / 4
+            timeout_kwargs: dict[str, float | None] = exclude_unset(
+                {
+                    "timeout": avg_timeout,
+                    "connect": timeout.connect,
+                    "read": timeout.read,
+                }
+            )
+            if timeout_kwargs:
+                _timeout = httpx.Timeout(**timeout_kwargs)
+        elif timeout is not UNSET:
+            _timeout = httpx.Timeout(timeout)
+
+        if _timeout is None:
+            return self._timeout
+        return _timeout
+
    @override
    async def request(self, setup: Request) -> Response:
-        if isinstance(setup.timeout, Timeout):
-            timeout = httpx.Timeout(
-                timeout=setup.timeout.total,
-                connect=setup.timeout.connect,
-                read=setup.timeout.read,
-            )
-        else:
-            timeout = httpx.Timeout(setup.timeout)
-
        response = await self.client.request(
            setup.method,
            str(setup.url),
@@ -112,7 +144,7 @@ class Session(HTTPClientSession):
            params=setup.url.raw_query_string,
            headers=tuple(setup.headers.items()),
            cookies=setup.cookies.jar,
-            timeout=timeout,
+            timeout=self._get_timeout(setup.timeout),
        )
        return Response(
            response.status_code,
@@ -128,15 +160,6 @@ class Session(HTTPClientSession):
        *,
        chunk_size: int = 1024,
    ) -> AsyncGenerator[Response, None]:
-        if isinstance(setup.timeout, Timeout):
-            timeout = httpx.Timeout(
-                timeout=setup.timeout.total,
-                connect=setup.timeout.connect,
-                read=setup.timeout.read,
-            )
-        else:
-            timeout = httpx.Timeout(setup.timeout)
-
        async with self.client.stream(
            setup.method,
            str(setup.url),
@@ -148,7 +171,7 @@ class Session(HTTPClientSession):
            params=setup.url.raw_query_string,
            headers=tuple(setup.headers.items()),
            cookies=setup.cookies.jar,
-            timeout=timeout,
+            timeout=self._get_timeout(setup.timeout),
        ) as response:
            response_headers = response.headers.multi_items()
            async for chunk in response.aiter_bytes(chunk_size=chunk_size):
@@ -216,9 +239,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,
@@ -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:
@@ -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,
-        port: Optional[int] = None,
+        host: str | None = 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
@@ -17,19 +17,26 @@ 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
+from nonebot.drivers import (
+    DEFAULT_TIMEOUT,
+    Request,
+    Timeout,
+    WebSocketClientMixin,
+    combine_driver,
+)
 from nonebot.drivers import WebSocket as BaseWebSocket
 from nonebot.drivers.none import Driver as NoneDriver
 from nonebot.exception import WebSocketClosed
 from nonebot.log import LoguruHandler
+from nonebot.utils import UNSET, UnsetType, exclude_unset

 try:
    from websockets import ClientConnection, ConnectionClosed, connect
@@ -70,16 +77,45 @@ class Mixin(WebSocketClientMixin):
    @override
    @asynccontextmanager
    async def websocket(self, setup: Request) -> AsyncGenerator["WebSocket", None]:
+        timeout_kwargs: dict[str, float | None | UnsetType] = {}
        if isinstance(setup.timeout, Timeout):
-            timeout = setup.timeout.total or setup.timeout.connect or setup.timeout.read
-        else:
-            timeout = setup.timeout
+            open_timeout = (
+                setup.timeout.connect or setup.timeout.read or setup.timeout.total
+            )
+            timeout_kwargs = {
+                "open_timeout": open_timeout,
+                "close_timeout": setup.timeout.close,
+                "ping_timeout": setup.timeout.ping,
+            }
+
+        elif setup.timeout is not UNSET:
+            timeout_kwargs = {
+                "open_timeout": setup.timeout,
+                "close_timeout": setup.timeout,
+            }
+
+        if not timeout_kwargs:
+            open_timeout = (
+                DEFAULT_TIMEOUT.connect or DEFAULT_TIMEOUT.read or DEFAULT_TIMEOUT.total
+            )
+            timeout_kwargs = {
+                "open_timeout": open_timeout,
+                "close_timeout": DEFAULT_TIMEOUT.close,
+                "ping_timeout": DEFAULT_TIMEOUT.ping,
+            }
+
+        kwargs = exclude_unset(
+            {
+                **timeout_kwargs,
+                "ping_interval": setup.ping_interval,
+            }
+        )

        connection = connect(
            str(setup.url),
            additional_headers={**setup.headers, **setup.cookies.as_header(setup)},
            proxy=setup.proxy if setup.proxy is not None else True,
-            open_timeout=timeout,
+            **kwargs,  # type: ignore
        )
        async with connection as ws:
            yield WebSocket(request=setup, websocket=ws)
@@ -108,7 +144,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
@@ -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

@@ -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:
        """调用机器人基础发送消息接口
@@ -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[
-            str,
-            tuple[str, int],
-            tuple[str, slice],
-            int,
-            slice,
-        ],
-    ) -> Union[TMS, Self]:
+        args: str | tuple[str, int] | tuple[str, slice] | int | slice,
+    ) -> 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:
        """将多个消息连接并将自身作为分割

        参数:
@@ -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],
-        factory: Union[type[str], type[TM]] = str,
+        template: str | TM,
+        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)
@@ -9,6 +9,7 @@ from .abstract import ReverseDriver as ReverseDriver
 from .abstract import ReverseMixin as ReverseMixin
 from .abstract import WebSocketClientMixin as WebSocketClientMixin
 from .combine import combine_driver as combine_driver
+from .model import DEFAULT_TIMEOUT as DEFAULT_TIMEOUT
 from .model import URL as URL
 from .model import ContentTypes as ContentTypes
 from .model import Cookies as Cookies
@@ -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_extensions import TypeAlias
+from typing import Any, TypeAlias, cast

 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_val: Optional[BaseException] = None,
-        exc_tb: Optional[TracebackType] = None,
+        exc_type: type[BaseException] | None = None,
+        exc_val: BaseException | None = 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_val: Optional[BaseException],
-        exc_tb: Optional[TracebackType],
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
    ) -> None:
        await self.shutdown(exc_type=exc_type, exc_val=exc_val, exc_tb=exc_tb)
@@ -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_extensions import Self, TypeAlias
+from typing import TYPE_CHECKING, Any, ClassVar, TypeAlias
+from typing_extensions import Self

 from anyio import CancelScope, create_task_group
 from anyio.abc import TaskGroup
@@ -19,7 +19,13 @@ from nonebot.typing import (
    T_BotDisconnectionHook,
    T_DependencyCache,
 )
-from nonebot.utils import escape_tag, flatten_exception_group, run_coro_with_catch
+from nonebot.utils import (
+    UNSET,
+    UnsetType,
+    escape_tag,
+    flatten_exception_group,
+    run_coro_with_catch,
+)

 from ._lifespan import LIFESPAN_FUNC, Lifespan
 from .model import (
@@ -245,9 +251,9 @@ class HTTPClientSession(abc.ABC):
        params: QueryTypes = None,
        headers: HeaderTypes = None,
        cookies: CookieTypes = None,
-        version: Union[str, HTTPVersion] = HTTPVersion.H11,
-        timeout: TimeoutTypes = None,
-        proxy: Optional[str] = None,
+        version: str | HTTPVersion = HTTPVersion.H11,
+        timeout: TimeoutTypes | UnsetType = UNSET,
+        proxy: str | None = None,
    ):
        raise NotImplementedError

@@ -283,9 +289,9 @@ class HTTPClientSession(abc.ABC):

    async def __aexit__(
        self,
-        exc_type: Optional[type[BaseException]],
-        exc: Optional[BaseException],
-        tb: Optional[TracebackType],
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
    ) -> None:
        await self.close()

@@ -315,9 +321,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
@@ -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):
@@ -1,48 +1,59 @@
 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_extensions import TypeAlias
+from typing import IO, Any, TypeAlias
 import urllib.request

 from multidict import CIMultiDict
 from yarl import URL as URL

-RawURL: TypeAlias = tuple[bytes, bytes, Optional[int], bytes]
+from nonebot.utils import UNSET, UnsetType

-SimpleQuery: TypeAlias = Union[str, int, float]
-QueryVariable: TypeAlias = Union[SimpleQuery, list[SimpleQuery]]
-QueryTypes: TypeAlias = Union[
-    None, str, Mapping[str, QueryVariable], list[tuple[str, SimpleQuery]]
-]

-HeaderTypes: TypeAlias = Union[
-    None,
-    CIMultiDict[str],
-    dict[str, str],
-    list[tuple[str, str]],
-]
+@dataclass
+class Timeout:
+    """Request 超时配置。"""

-CookieTypes: TypeAlias = Union[
-    None, "Cookies", CookieJar, dict[str, str], list[tuple[str, str]]
-]
+    total: float | None | UnsetType = UNSET
+    connect: float | None | UnsetType = UNSET
+    read: float | None | UnsetType = UNSET
+    close: float | None | UnsetType = UNSET
+    ping: float | None | UnsetType = UNSET

-ContentTypes: TypeAlias = Union[str, bytes, None]
-DataTypes: TypeAlias = Union[dict, None]
-FileContent: TypeAlias = Union[IO[bytes], bytes]
-FileType: TypeAlias = tuple[Optional[str], FileContent, Optional[str]]
-FileTypes: TypeAlias = Union[
-    # file (or bytes)
-    FileContent,
-    # (filename, file (or bytes))
-    tuple[Optional[str], FileContent],
-    # (filename, file (or bytes), content_type)
-    FileType,
-]
-FilesTypes: TypeAlias = Union[dict[str, FileTypes], list[tuple[str, FileTypes]], None]
-TimeoutTypes: TypeAlias = Union[float, "Timeout", None]
+
+DEFAULT_TIMEOUT = Timeout(total=None, connect=5.0, read=30.0, close=10.0, ping=20.0)
+
+
+RawURL: TypeAlias = tuple[bytes, bytes, int | None, bytes]
+
+SimpleQuery: TypeAlias = str | int | float
+QueryVariable: TypeAlias = SimpleQuery | list[SimpleQuery]
+QueryTypes: TypeAlias = (
+    None | str | Mapping[str, QueryVariable] | list[tuple[str, SimpleQuery]]
+)
+
+HeaderTypes: TypeAlias = (
+    None | CIMultiDict[str] | dict[str, str] | list[tuple[str, str]]
+)
+
+CookieTypes: TypeAlias = (
+    "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
+PingIntervalTypes: TypeAlias = float | None


 class HTTPVersion(Enum):
@@ -51,20 +62,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],
-        url: Union["URL", str, RawURL],
+        method: str | bytes,
+        url: "URL | str | RawURL",
        *,
        params: QueryTypes = None,
        headers: HeaderTypes = None,
@@ -73,9 +75,10 @@ class Request:
        data: DataTypes = None,
        json: Any = None,
        files: FilesTypes = None,
-        version: Union[str, HTTPVersion] = HTTPVersion.H11,
-        timeout: TimeoutTypes = None,
-        proxy: Optional[str] = None,
+        version: str | HTTPVersion = HTTPVersion.H11,
+        timeout: TimeoutTypes | UnsetType = UNSET,
+        proxy: str | None = None,
+        ping_interval: PingIntervalTypes | UnsetType = UNSET,
    ):
        # method
        self.method: str = (
@@ -86,9 +89,11 @@ class Request:
        # http version
        self.version: HTTPVersion = HTTPVersion(version)
        # timeout
-        self.timeout: TimeoutTypes = timeout
+        self.timeout: TimeoutTypes | UnsetType = timeout
        # proxy
-        self.proxy: Optional[str] = proxy
+        self.proxy: str | None = proxy
+        # ping interval
+        self.ping_interval: PingIntervalTypes | UnsetType = ping_interval

        # url
        if isinstance(url, tuple):
@@ -117,7 +122,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 +145,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 +158,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 +188,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 +202,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 +263,11 @@ class Cookies(MutableMapping):
    def get(  # pyright: ignore[reportIncompatibleMethodOverride]
        self,
        name: str,
-        default: Optional[str] = None,
-        domain: Optional[str] = None,
-        path: Optional[str] = None,
-    ) -> Optional[str]:
-        value: Optional[str] = None
+        default: str | None = None,
+        domain: str | None = None,
+        path: str | None = None,
+    ) -> str | None:
+        value: str | None = None
        for cookie in self.jar:
            if (
                cookie.name == name
@@ -277,7 +282,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 +298,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]
@@ -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
-    ) -> Optional[Union[list[type["Matcher"]], T]]:
+        self, key: int, default: T | None = None
+    ) -> list[type["Matcher"]] | T | None:
        return self.provider.get(key, default)

    def pop(  # pyright: ignore[reportIncompatibleMethodOverride]
@@ -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]
-        module_name: Optional[str]
+        _source: MatcherSource | None
+        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,
-        permission: Optional[Permission] = None,
-        handlers: Optional[list[Union[T_Handler, Dependent[Any]]]] = None,
+        rule: Rule | None = None,
+        permission: Permission | None = None,
+        handlers: list[T_Handler | Dependent[Any]] | None = None,
        temp: bool = False,
        priority: int = 1,
        block: bool = False,
        *,
-        plugin: Optional["Plugin"] = None,
-        module: Optional[ModuleType] = None,
-        source: Optional[MatcherSource] = None,
-        expire_time: Optional[Union[datetime, timedelta]] = None,
-        default_state: Optional[T_State] = None,
-        default_type_updater: Optional[Union[T_TypeUpdater, Dependent[str]]] = None,
-        default_permission_updater: Optional[
-            Union[T_PermissionUpdater, Dependent[Permission]]
-        ] = None,
+        plugin: "Plugin | None" = None,
+        module: ModuleType | None = None,
+        source: MatcherSource | None = None,
+        expire_time: datetime | timedelta | None = None,
+        default_state: T_State | None = None,
+        default_type_updater: T_TypeUpdater | Dependent[str] | None = None,
+        default_permission_updater: T_PermissionUpdater
+        | Dependent[Permission]
+        | 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,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        stack: AsyncExitStack | None = 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,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        stack: AsyncExitStack | None = 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,
-        parameterless: Optional[Iterable[Any]] = None,
+        prompt: str | Message | MessageSegment | MessageTemplate | None = 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(
-        self, id: str, default: Optional[T] = None
-    ) -> Optional[Union[Event, T]]:
+    def get_receive(self, id: str, default: T | None = None) -> Event | T | None:
        """获取一个 `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(
-        self, default: Optional[T] = None
-    ) -> Optional[Union[Event, T]]:
+    def get_last_receive(self, default: T | None = None) -> Event | T | None:
        """获取最近一次 `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(
-        self, key: str, default: Optional[T] = None
-    ) -> Optional[Union[Message, T]]:
+    def get_arg(self, key: str, default: T | None = None) -> Message | T | None:
        """获取一个 `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,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        stack: AsyncExitStack | None = 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,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        stack: AsyncExitStack | None = 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,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        stack: AsyncExitStack | None = 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,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        stack: AsyncExitStack | None = None,
+        dependency_cache: T_DependencyCache | None = None,
    ):
-        exc: Optional[Union[FinishedException, RejectedException, PausedException]] = (
-            None
-        )
+        exc: FinishedException | RejectedException | PausedException | None = None

        def _handle_special_exception(
            exc_group: BaseExceptionGroup[
-                Union[FinishedException, RejectedException, PausedException]
+                FinishedException | RejectedException | PausedException
            ],
        ):
            nonlocal exc
@@ -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 = {}
-        if isinstance(validate, PydanticFieldInfo):
-            kwargs.update(extract_field_info(validate))
-
-        kwargs["validate"] = bool(validate)
-        kwargs["dependent"] = sub_dependent
-        kwargs["use_cache"] = use_cache
-
-        return cls(**kwargs)
+        return cls._inherit_construct(
+            validate if isinstance(validate, PydanticFieldInfo) else None,
+            dependent=sub_dependent,
+            use_cache=use_cache,
+            validate=bool(validate),
+        )

    @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,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        stack: AsyncExitStack | None = 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__(
-        self, *args, checker: Optional[ModelField] = None, **kwargs: Any
-    ) -> None:
+    def __init__(self, *args, checker: ModelField | None = 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__(
-        self, *args, checker: Optional[ModelField] = None, **kwargs: Any
-    ) -> None:
+    def __init__(self, *args, checker: ModelField | None = 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__(
-        self, *args, checker: Optional[ModelField] = None, **kwargs: Any
-    ) -> None:
+    def __init__(self, *args, checker: ModelField | None = 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)

@@ -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,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        stack: AsyncExitStack | None = 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__(
-        self, other: Optional[Union["Permission", T_PermissionChecker]]
-    ) -> "Permission":
+    def __or__(self, other: "Permission | T_PermissionChecker | None") -> "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__(
-        self, other: Optional[Union["Permission", T_PermissionChecker]]
-    ) -> "Permission":
+    def __ror__(self, other: "Permission | T_PermissionChecker | None") -> "Permission":
        if other is None:
            return self
        elif isinstance(other, Permission):
@@ -126,9 +122,7 @@ class User:

    __slots__ = ("perm", "users")

-    def __init__(
-        self, users: tuple[str, ...], perm: Optional[Permission] = None
-    ) -> None:
+    def __init__(self, users: tuple[str, ...], perm: Permission | None = 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 限制。
@@ -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,
-        dependency_cache: Optional[T_DependencyCache] = None,
+        stack: AsyncExitStack | None = 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):
@@ -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,
-    dependency_cache: Optional[T_DependencyCache] = None,
+    stack: AsyncExitStack | None = 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,
-    dependency_cache: Optional[T_DependencyCache] = None,
+    stack: AsyncExitStack | None = 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,
-    dependency_cache: Optional[T_DependencyCache] = None,
+    stack: AsyncExitStack | None = 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,
-    stack: Optional[AsyncExitStack] = None,
-    dependency_cache: Optional[T_DependencyCache] = None,
+    exception: Exception | None = None,
+    stack: AsyncExitStack | None = 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,
-    dependency_cache: Optional[T_DependencyCache] = None,
+    stack: AsyncExitStack | None = 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,
-    dependency_cache: Optional[T_DependencyCache] = None,
+    stack: AsyncExitStack | None = 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,
-    dependency_cache: Optional[T_DependencyCache] = None,
+    stack: AsyncExitStack | None = None,
+    dependency_cache: T_DependencyCache | None = None,
 ) -> None:
    """检查并运行事件响应器。

@@ -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], ...],
-) -> Callable[[T_State], Union[str, tuple[Union[str, Any], ...], Any]]:
+    groups: tuple[str | int, ...],
+) -> 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]
-) -> tuple[Union[str, Any], ...]: ...
+    group1: str | int, group2: str | int, /, *groups: str | int
+) -> 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:
@@ -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
-) -> Optional[str]:
+    module_name: str, controlled_modules: dict[str, str] | None = None
+) -> 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
@@ -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))
@@ -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,
-        search_path: Optional[Iterable[str]] = None,
+        plugins: Iterable[str] | None = 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]],
-        target: Optional[ModuleType] = None,
+        path: Sequence[str] | 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
@@ -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
@@ -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,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = None,
+    rule: Rule | T_RuleChecker | None = 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, ...]],
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    msg: str | tuple[str, ...],
+    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, ...]],
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    msg: str | tuple[str, ...],
+    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, ...]],
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    msg: str | tuple[str, ...],
+    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, ...]],
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
-    aliases: Optional[set[Union[str, tuple[str, ...]]]] = None,
-    force_whitespace: Optional[Union[str, bool]] = None,
+    cmd: str | tuple[str, ...],
+    rule: Rule | T_RuleChecker | None = None,
+    aliases: set[str | tuple[str, ...]] | None = 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, ...]],
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
-    aliases: Optional[set[Union[str, tuple[str, ...]]]] = None,
-    parser: Optional[ArgumentParser] = None,
+    cmd: str | tuple[str, ...],
+    rule: Rule | T_RuleChecker | None = None,
+    aliases: set[str | tuple[str, ...]] | None = 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,
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    flags: int | re.RegexFlag = 0,
+    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], ...]],
-    rule: Optional[Union[Rule, T_RuleChecker]] = None,
+    types: type[Event] | tuple[type[Event], ...],
+    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(
-        self, cmd: Union[str, tuple[str, ...]], **kwargs
-    ) -> type[Matcher]:
+    def shell_command(self, cmd: str | tuple[str, ...], **kwargs) -> type[Matcher]:
        """注册一个新的 `shell_like` 命令。新参数将会覆盖命令组默认值

        参数:
@@ -641,9 +639,7 @@ class MatcherGroup(_Group):
        self.matchers.append(matcher)
        return matcher

-    def on_startswith(
-        self, msg: Union[str, tuple[str, ...]], **kwargs
-    ) -> type[Matcher]:
+    def on_startswith(self, msg: 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, ...]],
-        aliases: Optional[set[Union[str, tuple[str, ...]]]] = None,
-        force_whitespace: Optional[Union[str, bool]] = None,
+        cmd: str | tuple[str, ...],
+        aliases: set[str | tuple[str, ...]] | None = 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, ...]],
-        aliases: Optional[set[Union[str, tuple[str, ...]]]] = None,
-        parser: Optional[ArgumentParser] = None,
+        cmd: str | tuple[str, ...],
+        aliases: set[str | tuple[str, ...]] | None = 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]:
        """注册一个事件响应器，并且当事件为指定类型时响应。

@@ -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, ...]]
-    raw_command: Optional[str]
-    command_arg: Optional[Message]
-    command_start: Optional[str]
-    command_whitespace: Optional[str]
+    command: tuple[str, ...] | None
+    raw_command: str | None
+    command_arg: Message | None
+    command_start: str | None
+    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_arg: Optional[Message] = CommandArg(),
-        cmd_whitespace: Optional[str] = CommandWhitespace(),
+        cmd: tuple[str, ...] | None = Command(),
+        cmd_arg: Message | None = CommandArg(),
+        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, ...]],
-    force_whitespace: Optional[Union[str, bool]] = None,
+    *cmds: str | tuple[str, ...],
+    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
-        ) -> tuple[T, list[Union[str, MessageSegment]]]: ...
+            self, args: Sequence[str | MessageSegment] | None, namespace: T
+        ) -> 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,
-            namespace: Optional[T] = None,
-        ) -> tuple[Union[Namespace, T], list[Union[str, MessageSegment]]]: ...
+            args: Sequence[str | MessageSegment] | None = None,
+            namespace: T | None = None,
+        ) -> 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,
-        namespace: Optional[T] = None,
-    ) -> Union[Namespace, T]:
+        args: Sequence[str | MessageSegment] | None = None,
+        namespace: T | None = None,
+    ) -> 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]
-    ) -> Optional[tuple[Optional[Action], str, Optional[str]]]:
+        self, arg_string: str | MessageSegment
+    ) -> 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(),
-        msg: Optional[Message] = CommandArg(),
+        cmd: tuple[str, ...] | None = Command(),
+        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` 获取匹配成功的字符串，
@@ -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:
+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: t.Optional[type[t.Any]]) -> bool:
-        """判断是否是 Union 类型"""
-        return origin is t.Union
-
-else:
-
-    def origin_is_union(origin: t.Optional[type[t.Any]]) -> bool:
+def origin_is_union(origin: type[t.Any] | None) -> 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]}
-if sys.version_info >= (3, 10):
-    NONE_TYPES.add(types.NoneType)
+NONE_TYPES = {None, type(None), t.Literal[None], t_ext.Literal[None], types.NoneType}  # noqa: PYI061


 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[
-    t.Callable[..., T], t.Callable[..., t.Awaitable[T]]
-]
+_DependentCallable: TypeAlias = 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"""

@@ -8,18 +8,37 @@ 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
+from enum import Enum
 from functools import partial, wraps
 import importlib
 import inspect
 import json
 from pathlib import Path
 import re
-from typing import Any, Callable, Generic, Optional, TypeVar, Union, overload
-from typing_extensions import ParamSpec, get_args, get_origin, override
+from typing import (
+    Any,
+    Final,
+    Generic,
+    Literal,
+    TypeAlias,
+    TypeVar,
+    final,
+    get_args,
+    get_origin,
+    overload,
+)
+from typing_extensions import ParamSpec, override

 import anyio
 import anyio.to_thread
@@ -35,6 +54,8 @@ from nonebot.typing import (
    type_has_args,
 )

+from .compat import custom_validation
+
 P = ParamSpec("P")
 R = TypeVar("R")
 T = TypeVar("T")
@@ -43,6 +64,54 @@ V = TypeVar("V")
 E = TypeVar("E", bound=BaseException)


+@final
+@custom_validation
+class Unset(Enum):
+    _UNSET = "<UNSET>"
+
+    def __repr__(self) -> str:
+        return "<UNSET>"
+
+    def __str__(self) -> str:
+        return self.__repr__()
+
+    def __bool__(self) -> Literal[False]:
+        return False
+
+    def __copy__(self):
+        return self._UNSET
+
+    def __deepcopy__(self, memo: dict[int, Any]):
+        return self._UNSET
+
+    @classmethod
+    def __get_validators__(cls):
+        yield cls._validate
+
+    @classmethod
+    def _validate(cls, value: Any):
+        if value is not cls._UNSET:
+            raise ValueError(f"{value!r} is not UNSET")
+        return value
+
+
+UnsetType: TypeAlias = Literal[Unset._UNSET]
+
+UNSET: Final[UnsetType] = Unset._UNSET
+
+
+def exclude_unset(data: Any) -> Any:
+    if isinstance(data, dict):
+        return data.__class__(
+            (k, exclude_unset(v)) for k, v in data.items() if v is not UNSET
+        )
+    elif isinstance(data, list):
+        return data.__class__(exclude_unset(i) for i in data if i is not UNSET)
+    elif data is UNSET:
+        return None
+    return data
+
+
 def escape_tag(s: str) -> str:
    """用于记录带颜色日志时转义 `<tag>` 类型特殊标签

@@ -73,7 +142,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 +152,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 +210,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 +281,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 +289,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,
-) -> Optional[Union[T, R]]:
+    return_on_err: R | None = None,
+) -> T | R | None:
    """运行协程并当遇到指定异常时返回指定值。

    参数:
@@ -288,7 +357,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 +378,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 +408,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}"
        )
@@ -1,6 +1,6 @@
 [project]
 name = "nonebot2"
-version = "2.4.3"
+version = "2.5.0"
 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.15.0, <0.16.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.4, <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"
@@ -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
@@ -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)
@@ -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()}


@@ -0,0 +1,3 @@
+[tool.nonebot]
+plugins = []
+plugin_dirs = []
@@ -1,3 +1,5 @@
 [tool.nonebot]
-plugins = []
 plugin_dirs = []
+
+[tool.nonebot.plugins]
+"@local" = []
@@ -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): ...
@@ -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:
@@ -1,7 +1,4 @@
-from typing import Union
-
-
-async def exc(e: Exception, x: Union[ValueError, TypeError]) -> Exception:
+async def exc(e: Exception, x: ValueError | TypeError) -> Exception:
    assert e == x
    return e

@@ -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],
-) -> Union[FooMatcher, BarMatcher]:
+    m: 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:
@@ -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,
-    event: Optional[Event] = None,
+    bot: Bot | None = 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,
 ): ...
@@ -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_disconnect_bot: Optional[Bot] = None
+    last_connect_bot: Bot | None = 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_ws_setup: Optional[WebSocketServerSetup] = None
+    last_http_setup: HTTPServerSetup | None = 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):
@@ -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,
@@ -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,
        ):
@@ -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
@@ -73,12 +73,41 @@ def test_type_adapter():


 def test_model_dump():
+    class NestedModel(BaseModel):
+        hidden: int
+        shown: int
+
    class TestModel(BaseModel):
        test1: int
        test2: int
+        nested: NestedModel
+        items: list[NestedModel]

-    assert model_dump(TestModel(test1=1, test2=2), include={"test1"}) == {"test1": 1}
-    assert model_dump(TestModel(test1=1, test2=2), exclude={"test1"}) == {"test2": 2}
+    model = TestModel(
+        test1=1,
+        test2=2,
+        nested=NestedModel(hidden=3, shown=4),
+        items=[NestedModel(hidden=5, shown=6)],
+    )
+
+    assert model_dump(model, include={"test1"}) == {"test1": 1}
+    assert model_dump(model, exclude={"test1"}) == {
+        "test2": 2,
+        "nested": {"hidden": 3, "shown": 4},
+        "items": [{"hidden": 5, "shown": 6}],
+    }
+    assert model_dump(model, exclude={"nested": {"hidden"}}) == {
+        "test1": 1,
+        "test2": 2,
+        "nested": {"shown": 4},
+        "items": [{"hidden": 5, "shown": 6}],
+    }
+    assert model_dump(model, exclude={"items": {"__all__": {"hidden"}}}) == {
+        "test1": 1,
+        "test2": 2,
+        "nested": {"hidden": 3, "shown": 4},
+        "items": [{"shown": 6}],
+    }


 def test_model_validator():
@@ -144,7 +173,7 @@ def test_validate_json():
        test3: bool
        test4: dict
        test5: list
-        test6: Optional[int]
+        test6: int | None

    assert type_validate_json(
        TestModel,
@@ -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_nested_delimiter: Optional[str] = "__"
+        _env_file: DOTENV_TYPE | None = ".env", ".env.example"
+        _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_union: Union[int, list[int]] = 1
+    complex_none: list[int] | None = None
+    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"
@@ -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,8 +22,11 @@ from nonebot.drivers import (
    WebSocketClientMixin,
    WebSocketServerSetup,
 )
+from nonebot.drivers.aiohttp import Session as AiohttpSession
+from nonebot.drivers.aiohttp import WebSocket as AiohttpWebSocket
 from nonebot.exception import WebSocketClosed
 from nonebot.params import Depends
+from nonebot.utils import UNSET
 from utils import FakeAdapter


@@ -171,7 +175,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()

@@ -594,6 +598,46 @@ async def test_http_client_session(driver: Driver, server_url: URL):
    await anyio.sleep(1)


+@pytest.mark.anyio
+async def test_aiohttp_stream_request_skip_empty_chunk() -> None:
+    class _FakeContent:
+        async def iter_chunked(self, _: int):
+            for chunk in (b"ab", b"", b"cd", b"e"):
+                yield chunk
+
+    class _FakeResponse:
+        def __init__(self) -> None:
+            self.status = 200
+            self.headers = {"x-test": "1"}
+            self.content = _FakeContent()
+
+    class _FakeRequestContext:
+        async def __aenter__(self) -> _FakeResponse:
+            return _FakeResponse()
+
+        async def __aexit__(self, *args: object) -> bool:
+            return False
+
+    class _FakeClient:
+        def request(self, *args: object, **kwargs: object) -> _FakeRequestContext:
+            return _FakeRequestContext()
+
+    session = AiohttpSession()
+    session._client = _FakeClient()  # type: ignore[assignment]
+
+    chunks = []
+    async for resp in session.stream_request(
+        Request("GET", "https://example.com"), chunk_size=2
+    ):
+        assert resp.status_code == 200
+        assert resp.content
+        chunks.append(resp.content)
+
+    assert chunks == [b"ab", b"cd", b"e"]
+    assert b"".join(chunks) == b"abcde"
+    assert all(len(chunk) == 2 for chunk in chunks[:-1])
+
+
@pytest.mark.anyio
@pytest.mark.parametrize(
    "driver",
@@ -627,6 +671,299 @@ 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()
+
+
+def test_timeout_unset_vs_none():
+    # default: all fields are UNSET
+    t = Timeout()
+    assert t.total is UNSET
+    assert t.connect is UNSET
+    assert t.read is UNSET
+    assert t.close is UNSET
+
+    # explicitly set to None
+    t = Timeout(close=None)
+    assert t.close is None
+    assert t.close is not UNSET
+
+    # explicitly set to a value
+    t = Timeout(total=5.0, close=None)
+    assert t.total == 5.0
+    assert t.close is None
+    assert t.connect is UNSET
+    assert t.read is UNSET
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize(
+    "driver",
+    [
+        pytest.param("nonebot.drivers.httpx:Driver", id="httpx"),
+        pytest.param("nonebot.drivers.aiohttp:Driver", id="aiohttp"),
+    ],
+    indirect=True,
+)
+async def test_http_client_timeout(driver: Driver, server_url: URL):
+    """HTTP requests work with fully unset, partial, and None timeout fields."""
+    assert isinstance(driver, HTTPClientMixin)
+
+    # timeout not set, default timeout should apply
+    request = Request("POST", server_url, content="test")
+    response = await driver.request(request)
+    assert response.status_code == 200
+    async for resp in driver.stream_request(request, chunk_size=1024):
+        assert resp.status_code == 200
+
+    # timeout is float or none
+    request = Request("POST", server_url, content="test", timeout=10.0)
+    response = await driver.request(request)
+    assert response.status_code == 200
+    async for resp in driver.stream_request(request, chunk_size=1024):
+        assert resp.status_code == 200
+
+    # all fields unset, default timeout should apply
+    request = Request("POST", server_url, content="test", timeout=Timeout())
+    response = await driver.request(request)
+    assert response.status_code == 200
+    async for resp in driver.stream_request(request, chunk_size=1024):
+        assert resp.status_code == 200
+
+    # only total set
+    request = Request("POST", server_url, content="test", timeout=Timeout(total=10.0))
+    response = await driver.request(request)
+    assert response.status_code == 200
+    async for resp in driver.stream_request(request, chunk_size=1024):
+        assert resp.status_code == 200
+
+    # explicit None (no timeout)
+    request = Request(
+        "POST",
+        server_url,
+        content="test",
+        timeout=Timeout(total=None, connect=None, read=None),
+    )
+    response = await driver.request(request)
+    assert response.status_code == 200
+    async for resp in driver.stream_request(request, chunk_size=1024):
+        assert resp.status_code == 200
+
+    # session with timeout not set
+    session = driver.get_session()
+    async with session:
+        request = Request("POST", server_url, content="test")
+        response = await session.request(request)
+        assert response.status_code == 200
+
+    # session with float or none timeout
+    session = driver.get_session(timeout=10.0)
+    async with session:
+        request = Request("POST", server_url, content="test")
+        response = await session.request(request)
+        assert response.status_code == 200
+
+    # session with fully unset timeout
+    session = driver.get_session(timeout=Timeout())
+    async with session:
+        request = Request("POST", server_url, content="test")
+        response = await session.request(request)
+        assert response.status_code == 200
+
+    # session with timeout
+    session = driver.get_session(timeout=Timeout(total=10.0, connect=5.0, read=5.0))
+    async with session:
+        request = Request("POST", server_url, content="test")
+        response = await session.request(request)
+        assert response.status_code == 200
+
+    # session with timeout override
+    session = driver.get_session(timeout=Timeout(total=10.0))
+    async with session:
+        request = Request(
+            "POST", server_url, content="test", timeout=Timeout(total=20.0)
+        )
+        response = await session.request(request)
+        assert response.status_code == 200
+
+    # session with timeout float override
+    session = driver.get_session(timeout=Timeout(total=10.0))
+    async with session:
+        request = Request("POST", server_url, content="test", timeout=20.0)
+        response = await session.request(request)
+        assert response.status_code == 200
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize(
+    "driver",
+    [
+        pytest.param("nonebot.drivers.websockets:Driver", id="websockets"),
+        pytest.param("nonebot.drivers.aiohttp:Driver", id="aiohttp"),
+    ],
+    indirect=True,
+)
+async def test_websocket_client_timeout(driver: Driver, server_url: URL):
+    """WebSocket connections work with fully unset, partial, and None timeout fields."""
+    assert isinstance(driver, WebSocketClientMixin)
+
+    ws_url = server_url.with_scheme("ws")
+
+    # timeout not set, default timeout should apply
+    request = Request("GET", ws_url)
+    async with driver.websocket(request) as ws:
+        await ws.send("quit")
+        with pytest.raises(WebSocketClosed):
+            await ws.receive()
+
+    await anyio.sleep(1)
+
+    # timeout is float or none
+    request = Request("GET", ws_url, timeout=10.0)
+    async with driver.websocket(request) as ws:
+        await ws.send("quit")
+        with pytest.raises(WebSocketClosed):
+            await ws.receive()
+
+    await anyio.sleep(1)
+
+    # all fields unset, default timeout should apply
+    request = Request("GET", ws_url, timeout=Timeout())
+    async with driver.websocket(request) as ws:
+        await ws.send("quit")
+        with pytest.raises(WebSocketClosed):
+            await ws.receive()
+
+    await anyio.sleep(1)
+
+    # close explicitly set to None (no close timeout)
+    request = Request("GET", ws_url, timeout=Timeout(close=None))
+    async with driver.websocket(request) as ws:
+        await ws.send("quit")
+        with pytest.raises(WebSocketClosed):
+            await ws.receive()
+
+    await anyio.sleep(1)
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize(
+    "driver",
+    [
+        pytest.param("nonebot.drivers.websockets:Driver", id="websockets"),
+        pytest.param("nonebot.drivers.aiohttp:Driver", id="aiohttp"),
+    ],
+    indirect=True,
+)
+async def test_websocket_client_ping_timeout(driver: Driver, server_url: URL):
+    """WebSocket connections work with different ping_timeout settings."""
+    assert isinstance(driver, WebSocketClientMixin)
+
+    ws_url = server_url.with_scheme("ws")
+
+    # ping timeout not set (UNSET), falls back to DEFAULT_TIMEOUT.ping
+    request = Request("GET", ws_url, timeout=Timeout())
+    async with driver.websocket(request) as ws:
+        await ws.send("quit")
+        with pytest.raises(WebSocketClosed):
+            await ws.receive()
+
+    await anyio.sleep(1)
+
+    # ping timeout explicitly set to None (disable ping timeout)
+    request = Request("GET", ws_url, timeout=Timeout(ping=None))
+    async with driver.websocket(request) as ws:
+        await ws.send("quit")
+        with pytest.raises(WebSocketClosed):
+            await ws.receive()
+
+    await anyio.sleep(1)
+
+    # ping timeout set to a float value
+    request = Request("GET", ws_url, timeout=Timeout(ping=20.0))
+    async with driver.websocket(request) as ws:
+        await ws.send("quit")
+        with pytest.raises(WebSocketClosed):
+            await ws.receive()
+
+    await anyio.sleep(1)
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize(
+    "driver",
+    [
+        pytest.param("nonebot.drivers.websockets:Driver", id="websockets"),
+        pytest.param("nonebot.drivers.aiohttp:Driver", id="aiohttp"),
+    ],
+    indirect=True,
+)
+async def test_websocket_client_ping_interval(driver: Driver, server_url: URL):
+    """WebSocket connections work with different ping_interval settings."""
+    assert isinstance(driver, WebSocketClientMixin)
+
+    ws_url = server_url.with_scheme("ws")
+
+    # ping_interval not set (UNSET), default behavior
+    request = Request("GET", ws_url)
+    async with driver.websocket(request) as ws:
+        await ws.send("quit")
+        with pytest.raises(WebSocketClosed):
+            await ws.receive()
+
+    await anyio.sleep(1)
+
+    # ping_interval explicitly set to None (disable ping)
+    request = Request("GET", ws_url, ping_interval=None)
+    async with driver.websocket(request) as ws:
+        await ws.send("quit")
+        with pytest.raises(WebSocketClosed):
+            await ws.receive()
+
+    await anyio.sleep(1)
+
+    # ping_interval set to a float value
+    request = Request("GET", ws_url, ping_interval=20.0)
+    async with driver.websocket(request) as ws:
+        await ws.send("quit")
+        with pytest.raises(WebSocketClosed):
+            await ws.receive()
+
+    await anyio.sleep(1)
+
+
@pytest.mark.parametrize(
    ("driver", "driver_type"),
    [
@@ -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,
@@ -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
@@ -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"
@@ -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"):
@@ -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
@@ -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],
-    arg_text: Optional[str],
+    whitespace: str | None,
+    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:
@@ -1,9 +1,19 @@
+import copy
 import json
+import pickle
 from typing import ClassVar, Dict, List, Literal, TypeVar, Union  # noqa: UP035

+from pydantic import ValidationError
+import pytest
+
+from nonebot.compat import type_validate_python
 from nonebot.utils import (
+    UNSET,
    DataclassEncoder,
+    Unset,
+    UnsetType,
    escape_tag,
+    exclude_unset,
    generic_check_issubclass,
    is_async_gen_callable,
    is_coroutine_callable,
@@ -12,6 +22,29 @@ from nonebot.utils import (
 from utils import FakeMessage, FakeMessageSegment


+def test_unset():
+    assert isinstance(UNSET, Unset)
+    assert bool(UNSET) is False
+    assert copy.copy(UNSET) is UNSET
+    assert copy.deepcopy(UNSET) is UNSET
+    assert pickle.loads(pickle.dumps(UNSET)) is UNSET
+    assert type_validate_python(UnsetType, UNSET) is UNSET
+
+    with pytest.raises(ValidationError):
+        type_validate_python(UnsetType, 123)
+
+
+def test_exclude_unset():
+    assert exclude_unset({"a": 1, "b": UNSET, "c": None, "d": {"x": UNSET}}) == {
+        "a": 1,
+        "c": None,
+        "d": {},
+    }
+    assert exclude_unset([1, UNSET, None, {"x": UNSET}]) == [1, None, {}]
+    assert exclude_unset(UNSET) is None
+    assert exclude_unset(123) == 123
+
+
 def test_loguru_escape_tag():
    assert escape_tag("<red>red</red>") == r"\<red>red\</red>"
    assert escape_tag("<fg #fff>white</fg #fff>") == r"\<fg #fff>white\</fg #fff>"
@@ -23,7 +56,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
@@ -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__(
-        self, other: Union[str, FakeMessageSegment, Iterable[FakeMessageSegment]]
-    ):
+    def __add__(self, other: 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",
-    _session_id: Optional[str] = "test",
-    _message: Optional[Message] = None,
+    _user_id: str | None = "test",
+    _session_id: str | None = "test",
+    _message: Message | None = None,
    _to_me: bool = True,
    **fields,
 ) -> type[Event]:
@@ -0,0 +1,3 @@
+version = 1
+revision = 3
+requires-python = ">=3.12"
@@ -46,15 +46,15 @@ __plugin_meta__ = PluginMetadata(
 )
 ```

-我们可以看到，插件元数据 `PluginMetadata` 有三个基本属性：插件名称、插件描述、插件使用方法。除此之外，还有几个可选的属性（具体填写见[发布插件](../developer/plugin-publishing.mdx#填写插件元数据)章节）：
+我们可以看到，插件元数据 `PluginMetadata` 有三个基本属性：插件名称、插件描述、插件使用方法。除此之外，还有几个可选的属性（具体填写见[发布插件](../developer/plugin-publishing.mdx#插件元数据)章节）：

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

-请注意，这里的**插件名称**是供使用者或机器人用户查看的，与插件索引名称无关。**插件索引名称（插件模块名称）**仅用于 NoneBot 插件系统**内部索引**。
+请注意，这里的**插件名称**是供使用者或机器人用户查看的人类可读名称，与插件索引名称无关。**插件索引名称（插件模块名称）**仅用于 NoneBot 插件系统**内部索引**。

 ## 获取插件信息

@@ -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
@@ -289,7 +289,6 @@ opt2 = Option("--foo", default=OptionResult(value=False, args={"bar": 1}))
 `Arparma` 有如下属性：

 - 调试类
-
  - matched: 是否匹配成功
  - error_data: 解析失败时剩余的数据
  - error_info: 解析失败时的异常内容
@@ -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`
@@ -159,7 +159,7 @@ async def _(target: MsgTarget):

 事实上，构造 `Target` 对象时，`self_id`, `scope`, `adapter` 和 `platform` 都会参与到 `selector` 的构造中。

-::tip
+:::tip

 你其实可以使用 `Target` 来帮你筛选 `Bot` 对象：

@@ -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
@@ -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)` 读取字体缓存。
@@ -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>
@@ -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 的返回值，将会返回给插件。
@@ -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 V12](https://github.com/nonebot/adapter-onebot/blob/master/nonebot/adapters/onebot/v12/adapter.py#L162)
+- [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/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)
- [Telegram](https://github.com/nonebot/adapter-telegram/blob/beta/nonebot/adapters/telegram/adapter.py#L145)
- [飞书](https://github.com/nonebot/adapter-feishu/blob/master/nonebot/adapters/feishu/adapter.py#L158)
+- [OneBot V11](https://github.com/nonebot/adapter-onebot/blob/54270edbbdb2a71332d744f90b1a3d7f4bf6463a/nonebot/adapters/onebot/v11/adapter.py#L179-L215)
+- [OneBot V12](https://github.com/nonebot/adapter-onebot/blob/54270edbbdb2a71332d744f90b1a3d7f4bf6463a/nonebot/adapters/onebot/v12/adapter.py#L220-L266)
+- [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)
- [QQGuild](https://github.com/nonebot/adapter-qqguild/blob/master/nonebot/adapters/qqguild/message.py#L22-L150)
- [Telegram](https://github.com/nonebot/adapter-telegram/blob/beta/nonebot/adapters/telegram/message.py#L43-L250)
+- [OneBot V11](https://github.com/nonebot/adapter-onebot/blob/54270edbbdb2a71332d744f90b1a3d7f4bf6463a/nonebot/adapters/onebot/v11/message.py#L25-L259)
+- [QQ](https://github.com/nonebot/adapter-qq/blob/dc5d437e101f0e3db542de3300758a035ed7036e/nonebot/adapters/qq/message.py#L30-L520)
+- [Telegram](https://github.com/nonebot/adapter-telegram/blob/4a8633627e619245516767f5503dec2f58fe2193/nonebot/adapters/telegram/message.py#L13-L414)

 ## 适配器测试

@@ -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` 依赖；
-3. 由于 `nonebot` 是指 `nonebot1` **而非** `nonebot2`，因此要注意**不要**将 `nonebot` 添加为插件的依赖，以免造成冲突；
-4. 尽可能避免使用 `==` 锁定单一版本，增强与其它插件的兼容性。
+# 安装项目依赖（自动创建虚拟环境）
+pdm sync

-:::
-
-### 填写插件元数据
-
-请注意，插件发布要求**必须**填写元数据才能通过审核。
-
-下面是一个示例：
-
-```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.`，其余适配器亦按此格式填写。
-    # 若插件可以保证兼容所有适配器（即仅使用基本适配器功能）可不填写，否则应该列出插件支持的适配器。
-)
+# 添加新依赖（如 httpx）
+pdm add httpx
 ```

-:::caution 注意
-`__plugin_meta__` 变量**必须**处于插件最外层（如 `__init__.py` 中），否则无法正常识别。
+</TabItem>

-一般做法是在 `__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
+```

- 插件功能介绍
- 安装方法（建议至少有 `nb-cli` 方式安装，**不要**使用旧式的 `bot.py` 配置）
- 插件配置项（若无可跳过）
- 插件设置的触发规则（若无可跳过）
- 插件的其它用法（按需编写）
+</TabItem>

-:::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)的一员。
@@ -5,7 +5,62 @@ description: 配置编辑器以获得最佳体验

 # 编辑器支持

-框架基于 [PEP484](https://www.python.org/dev/peps/pep-0484/)、[PEP 561](https://www.python.org/dev/peps/pep-0561/)、[PEP8](https://www.python.org/dev/peps/pep-0008/) 等规范进行开发并且**拥有完整类型注解**。框架使用 Pyright（Pylance）工具进行类型检查，确保代码可以被编辑器正确解析。
+框架基于 [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
+会自动弹出提示，建议您安装这些推荐的扩展，一键即可完成开发环境的初始化，让您可以立即开始编写代码，无需手动搜索和安装插件。

 ## 编辑器推荐配置

@@ -81,8 +81,9 @@ nb create
   请注意，多选项使用**空格**选中或取消，**回车**确认。

   ```bash
-   [?] 要使用哪些驱动器? FastAPI (FastAPI 驱动器)
   [?] 要使用哪些适配器? Console (基于终端的交互式适配器)
+   [?] 要使用哪些驱动器? FastAPI (FastAPI 驱动器)
+   [?] 要使用什么本地存储策略? 用户全局 (默认，适用于单用户下单实例)
   [?] 立即安装依赖? (Y/n) Yes
   [?] 创建虚拟环境? (Y/n) Yes
   ```
@@ -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` 来自动检测代码的更改并自动重新运行入口文件。
@@ -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
@@ -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)

@@ -24,6 +24,9 @@ NoneBot 提供了一个[商店](/store/plugins)，商店内容均由社区开发

 商店中每个内容的卡片都包含了其名称和简介等信息，点击**卡片右上角**链接图标即可跳转到其主页。

+与此同时，NB-CLI 也提供了一个 TUI 版本的商店界面，可通过 `nb adapter store`、`nb plugin store`、`nb driver store` 命令或 CLI
+交互式界面进入。其提供了接近网页商店的体验，同时允许快捷安装到当前项目。
+
 ## 安装插件

 <Asciinema
@@ -300,6 +300,7 @@ export default async function createConfigAsync() {

    future: {
      experimental_faster: true,
+      v4: true,
    },

    plugins: [
@@ -5,6 +5,223 @@ toc_max_heading_level: 2

 # 更新日志

+## 最近更新
+
+### 🚀 新功能
+
+- Feature: WS 支持 ping interval/timeout 配置 [@StarHeartHunt](https://github.com/StarHeartHunt) ([#3964](https://github.com/nonebot/nonebot2/pull/3964))
+
+### 💫 杂项
+
+- CI: 移除 Pull Request Target 触发器 [@StarHeartHunt](https://github.com/StarHeartHunt) ([#3946](https://github.com/nonebot/nonebot2/pull/3946))
+
+### 🍻 插件发布
+
+- Plugin: Permission [@noneflow](https://github.com/noneflow) ([#4022](https://github.com/nonebot/nonebot2/pull/4022))
+- Plugin: 舞萌排行榜 [@noneflow](https://github.com/noneflow) ([#4013](https://github.com/nonebot/nonebot2/pull/4013))
+- Plugin: 精华消息管理 [@noneflow](https://github.com/noneflow) ([#4015](https://github.com/nonebot/nonebot2/pull/4015))
+- Plugin: nonebot-plugin-onebot2tg [@noneflow](https://github.com/noneflow) ([#4020](https://github.com/nonebot/nonebot2/pull/4020))
+- Plugin: 猫猫糕公开版 [@noneflow](https://github.com/noneflow) ([#4011](https://github.com/nonebot/nonebot2/pull/4011))
+- Plugin: PicStatus-ng [@noneflow](https://github.com/noneflow) ([#4004](https://github.com/nonebot/nonebot2/pull/4004))
+- Plugin: B50分析 [@noneflow](https://github.com/noneflow) ([#4002](https://github.com/nonebot/nonebot2/pull/4002))
+- Plugin: BiliLive [@noneflow](https://github.com/noneflow) ([#3970](https://github.com/nonebot/nonebot2/pull/3970))
+- Plugin: dot-skill 角色扮演 [@noneflow](https://github.com/noneflow) ([#3996](https://github.com/nonebot/nonebot2/pull/3996))
+- Plugin: 编程命名风格转换 [@noneflow](https://github.com/noneflow) ([#3990](https://github.com/nonebot/nonebot2/pull/3990))
+- Plugin: 赛马娘插件 [@noneflow](https://github.com/noneflow) ([#3983](https://github.com/nonebot/nonebot2/pull/3983))
+- Plugin: Hermes Agent [@noneflow](https://github.com/noneflow) ([#3988](https://github.com/nonebot/nonebot2/pull/3988))
+- Plugin: 酷我音乐 [@noneflow](https://github.com/noneflow) ([#3975](https://github.com/nonebot/nonebot2/pull/3975))
+- Plugin: osu!mania 工具箱 [@noneflow](https://github.com/noneflow) ([#3977](https://github.com/nonebot/nonebot2/pull/3977))
+- Plugin: LibAmritaCore [@noneflow](https://github.com/noneflow) ([#3942](https://github.com/nonebot/nonebot2/pull/3942))
+- Plugin: 苏大电费查询 [@noneflow](https://github.com/noneflow) ([#3966](https://github.com/nonebot/nonebot2/pull/3966))
+- Plugin: 舞立方插件 [@noneflow](https://github.com/noneflow) ([#3956](https://github.com/nonebot/nonebot2/pull/3956))
+- Plugin: 语录插件 [@noneflow](https://github.com/noneflow) ([#3963](https://github.com/nonebot/nonebot2/pull/3963))
+- Plugin: 明日方舟猜干员游戏 [@noneflow](https://github.com/noneflow) ([#3939](https://github.com/nonebot/nonebot2/pull/3939))
+- Plugin: 错误日志转发钉钉机器人 [@noneflow](https://github.com/noneflow) ([#3952](https://github.com/nonebot/nonebot2/pull/3952))
+- Plugin: Bot状态监控 [@noneflow](https://github.com/noneflow) ([#3968](https://github.com/nonebot/nonebot2/pull/3968))
+- Plugin: tg-stickers-downloads [@noneflow](https://github.com/noneflow) ([#3954](https://github.com/nonebot/nonebot2/pull/3954))
+- Plugin: 12306车票查询 [@noneflow](https://github.com/noneflow) ([#3948](https://github.com/nonebot/nonebot2/pull/3948))
+- Plugin: 会话配置 [@noneflow](https://github.com/noneflow) ([#3938](https://github.com/nonebot/nonebot2/pull/3938))
+
+### 🍻 适配器发布
+
+- Adapter: WxClaw [@noneflow](https://github.com/noneflow) ([#3944](https://github.com/nonebot/nonebot2/pull/3944))
+
+## v2.5.0
+
+### 💥 破坏性变更
+
+- Remove: 移除 Python 3.9 支持 [@shoucandanghehe](https://github.com/shoucandanghehe) ([#3860](https://github.com/nonebot/nonebot2/pull/3860))
+
+### 🚀 新功能
+
+- Feature: 放宽 pydantic compat model dump 类型 [@shoucandanghehe](https://github.com/shoucandanghehe) ([#3898](https://github.com/nonebot/nonebot2/pull/3898))
+
+### 🐛 Bug 修复
+
+- Fix: 修正 http/websocket client timeout [@StarHeartHunt](https://github.com/StarHeartHunt) ([#3923](https://github.com/nonebot/nonebot2/pull/3923))
+- Fix: 修复 aiohttp 流式响应分块大小不固定问题 [@KeepingRunning](https://github.com/KeepingRunning) ([#3919](https://github.com/nonebot/nonebot2/pull/3919))
+- Fix: aiohttp 驱动未处理 WSMsgType.CLOSED 类型 [@shoucandanghehe](https://github.com/shoucandanghehe) ([#3862](https://github.com/nonebot/nonebot2/pull/3862))
+
+### 📝 文档
+
+- Docs: 升级 Docusaurus 3.9.2 [@StarHeartHunt](https://github.com/StarHeartHunt) ([#3861](https://github.com/nonebot/nonebot2/pull/3861))
+- Docs: 修复插件元数据链接错误 [@yanyongyu](https://github.com/yanyongyu) ([#3894](https://github.com/nonebot/nonebot2/pull/3894))
+- 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: 删除旧插件 group-config [@USTC-XeF2](https://github.com/USTC-XeF2) ([#3934](https://github.com/nonebot/nonebot2/pull/3934))
+- Fix: 修正云湖适配器的 module_name [@he0119](https://github.com/he0119) ([#3937](https://github.com/nonebot/nonebot2/pull/3937))
+- Dev: 修复 devcontainer corepack 安装 yarn 卡死 [@yanyongyu](https://github.com/yanyongyu) ([#3893](https://github.com/nonebot/nonebot2/pull/3893))
+- 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: TS3 Tracker [@noneflow](https://github.com/noneflow) ([#3902](https://github.com/nonebot/nonebot2/pull/3902))
+- Plugin: CS2 Radar [@noneflow](https://github.com/noneflow) ([#3908](https://github.com/nonebot/nonebot2/pull/3908))
+- Plugin: 舞萌服务器监控 [@noneflow](https://github.com/noneflow) ([#3910](https://github.com/nonebot/nonebot2/pull/3910))
+- Plugin: Endfield [@noneflow](https://github.com/noneflow) ([#3884](https://github.com/nonebot/nonebot2/pull/3884))
+- Plugin: AppStore游戏榜单 [@noneflow](https://github.com/noneflow) ([#3896](https://github.com/nonebot/nonebot2/pull/3896))
+- Plugin: 全自动膜拜机 [@noneflow](https://github.com/noneflow) ([#3906](https://github.com/nonebot/nonebot2/pull/3906))
+- Plugin: 计算器：游戏 [@noneflow](https://github.com/noneflow) ([#3904](https://github.com/nonebot/nonebot2/pull/3904))
+- Plugin: nonebot-plugin-sentry-transaction [@noneflow](https://github.com/noneflow) ([#3912](https://github.com/nonebot/nonebot2/pull/3912))
+- Plugin: Codex [@noneflow](https://github.com/noneflow) ([#3889](https://github.com/nonebot/nonebot2/pull/3889))
+- Plugin: nonebot-plugin-nbnhhsh [@noneflow](https://github.com/noneflow) ([#3887](https://github.com/nonebot/nonebot2/pull/3887))
+- 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

 ### 🚀 新功能
--- a/Show More
+++ b/Show More