🔖 Release 2.0.1

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Ju4tCode <42488585+yanyongyu@users.noreply.github.com>

.devcontainer/devcontainer.json

@@ -10,9 +10,11 @@
       "settings": {
         "python.analysis.diagnosticMode": "workspace",
         "python.analysis.typeCheckingMode": "basic",
+        "ruff.organizeImports": false,
         "[python]": {
           "editor.defaultFormatter": "ms-python.black-formatter",
           "editor.codeActionsOnSave": {
+            "source.fixAll.ruff": true,
             "source.organizeImports": true
           }
         },
@@ -44,6 +46,7 @@
         "ms-python.vscode-pylance",
         "ms-python.isort",
         "ms-python.black-formatter",
+        "charliermarsh.ruff",
         "EditorConfig.EditorConfig",
         "esbenp.prettier-vscode",
         "bradlc.vscode-tailwindcss"

.github/ISSUE_TEMPLATE/adapter_publish.yml

@@ -0,0 +1,57 @@
+name: 发布适配器
+title: "Adapter: {name}"
+description: 发布适配器到 NoneBot 官方商店
+labels: ["Adapter"]
+body:
+  - type: input
+    id: name
+    attributes:
+      label: 适配器名称
+      description: 适配器名称
+    validations:
+      required: true
+
+  - type: input
+    id: description
+    attributes:
+      label: 适配器描述
+      description: 适配器描述
+    validations:
+      required: true
+
+  - type: input
+    id: pypi
+    attributes:
+      label: PyPI 项目名
+      description: PyPI 项目名
+      placeholder: e.g. nonebot-adapter-xxx
+    validations:
+      required: true
+
+  - type: input
+    id: module
+    attributes:
+      label: 适配器 import 包名
+      description: 适配器 import 包名
+      placeholder: e.g. nonebot_adapter_xxx
+    validations:
+      required: true
+
+  - type: input
+    id: homepage
+    attributes:
+      label: 适配器项目仓库/主页链接
+      description: 适配器项目仓库/主页链接
+      placeholder: e.g. https://github.com/xxx/xxx
+    validations:
+      required: true
+
+  - type: input
+    id: tags
+    attributes:
+      label: 标签
+      description: 标签
+      placeholder: 'e.g. [{"label": "标签名", "color": "#ea5252"}]'
+      value: "[]"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/bot_publish.yml

@@ -0,0 +1,37 @@
+name: 发布机器人
+title: "Bot: {name}"
+description: 发布机器人到 NoneBot 官方商店
+labels: ["Bot"]
+body:
+  - type: input
+    id: name
+    attributes:
+      label: 机器人名称
+      description: 机器人名称
+    validations:
+      required: true
+
+  - type: input
+    id: description
+    attributes:
+      label: 机器人描述
+      description: 机器人描述
+    validations:
+      required: true
+
+  - type: input
+    id: homepage
+    attributes:
+      label: 机器人项目仓库/主页链接
+      description: 机器人项目仓库/主页链接
+      placeholder: e.g. https://github.com/xxx/xxx
+
+  - type: input
+    id: tags
+    attributes:
+      label: 标签
+      description: 标签
+      placeholder: 'e.g. [{"label": "标签名", "color": "#ea5252"}]'
+      value: "[]"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/bug-report.md

@@ -1,38 +0,0 @@
----
-name: Bug report
-about: Create a bug report to help us improve
-title: 'Bug: Something went wrong'
-labels: bug
-assignees: ''
-
----
-
-**描述问题：**
-
-A clear and concise description of what the bug is.
-
-**如何复现？**
-
-1. Go to '...'
-2. Click on '....'
-3. Scroll down to '....'
-4. See error
-
-**期望的结果**
-
-A clear and concise description of what you expected to happen.
-
-**环境信息：**
-
- - OS: [e.g. Linux]
- - Python Version: [e.g. 3.8]
- - Nonebot Version: [e.g. 2.0.0]
-
-**协议端信息：**
-
- - 协议端: [e.g. go-cqhttp]
- - 协议端版本: [e.g. 1.0.0]
-
-**截图或日志**
-
-If applicable, add screenshots to help explain your problem.

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,85 @@
+name: Bug 反馈
+title: "Bug: 出现异常"
+description: 提交 Bug 反馈以帮助我们改进代码
+labels: ["bug"]
+body:
+  - type: dropdown
+    id: env-os
+    attributes:
+      label: 操作系统
+      description: 选择运行 NoneBot 的系统
+      options:
+        - Windows
+        - MacOS
+        - Linux
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: env-python-ver
+    attributes:
+      label: Python 版本
+      description: 填写运行 NoneBot 的 Python 版本
+      placeholder: e.g. 3.11.0
+    validations:
+      required: true
+
+  - type: input
+    id: env-nb-ver
+    attributes:
+      label: NoneBot 版本
+      description: 填写 NoneBot 版本
+      placeholder: e.g. 2.0.0
+    validations:
+      required: true
+
+  - type: input
+    id: env-adapter
+    attributes:
+      label: 适配器
+      description: 填写使用的适配器以及版本
+      placeholder: e.g. OneBot v11 2.2.2
+    validations:
+      required: true
+
+  - type: input
+    id: env-protocol
+    attributes:
+      label: 协议端
+      description: 填写连接 NoneBot 的协议端及版本
+      placeholder: e.g. go-cqhttp 1.0.0
+    validations:
+      required: true
+
+  - type: textarea
+    id: describe
+    attributes:
+      label: 描述问题
+      description: 清晰简洁地说明问题是什么
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: 复现步骤
+      description: 提供能复现此问题的详细操作步骤
+      placeholder: |
+        1. 首先……
+        2. 然后……
+        3. 发生……
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: 期望的结果
+      description: 清晰简洁地描述你期望发生的事情
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: 截图或日志
+      description: 提供有助于诊断问题的任何日志和截图

.github/ISSUE_TEMPLATE/config.yml

@@ -1,14 +1,5 @@
 blank_issues_enabled: false
 contact_links:
-  - name: Question
+  - name: NoneBot 论坛
     url: https://discussions.nonebot.dev/
-    about: Ask questions about nonebot
-  - name: Plugin Publish
-    url: https://v2.nonebot.dev/store
-    about: Publish your plugin to nonebot homepage and nb-cli
-  - name: Adapter Publish
-    url: https://v2.nonebot.dev/store
-    about: Publish your adapter to nonebot homepage and nb-cli
-  - name: Bot Publish
-    url: https://v2.nonebot.dev/store
-    about: Publish your bot to nonebot homepage and nb-cli
+    about: 前往 NoneBot 论坛提问

.github/ISSUE_TEMPLATE/document.md

@@ -1,17 +0,0 @@
----
-name: Document improvement
-about: Feedback on documentation, including errors and ideas
-title: 'Docs: some description'
-labels: documentation
-assignees: ''
-
----
-
-**描述问题或主题：**
-
-
-**需做出的修改：**
-
-* [ ]  一些修改
-* [ ]  一些修改
-* [ ]  一些修改

.github/ISSUE_TEMPLATE/document.yml

@@ -0,0 +1,18 @@
+name: 文档改进
+title: "Docs: 描述"
+description: 文档错误及改进意见反馈
+labels: ["documentation"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: 描述问题或主题
+    validations:
+      required: true
+
+  - type: textarea
+    id: improve
+    attributes:
+      label: 需做出的修改
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,16 +0,0 @@
----
-name: Feature request
-about: Suggest an idea for this project
-title: 'Feature: Something you want'
-labels: enhancement
-assignees: ''
-
----
-
-**是否在使用中遇到某些问题而需要新的特性？请描述：**
-
-A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
-
-**描述你所需要的特性：**
-
-A clear and concise description of what you want to happen.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,20 @@
+name: 功能建议
+title: "Feature: 功能描述"
+description: 提出关于项目新功能的想法
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: 希望能解决的问题
+      description: 在使用中遇到什么问题而需要新的功能？
+    validations:
+      required: true
+
+  - type: textarea
+    id: feature
+    attributes:
+      label: 描述所需要的功能
+      description: 请说明需要的功能或解决方法
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/plugin_publish.yml

@@ -0,0 +1,43 @@
+name: 发布插件
+title: "Plugin: {name}"
+description: 发布插件到 NoneBot 官方商店
+labels: ["Plugin"]
+body:
+  - type: input
+    id: pypi
+    attributes:
+      label: PyPI 项目名
+      description: PyPI 项目名
+      placeholder: e.g. nonebot-plugin-xxx
+    validations:
+      required: true
+
+  - type: input
+    id: module
+    attributes:
+      label: 插件 import 包名
+      description: 插件 import 包名
+      placeholder: e.g. nonebot_plugin_xxx
+    validations:
+      required: true
+
+  - type: input
+    id: tags
+    attributes:
+      label: 标签
+      description: 标签
+      placeholder: 'e.g. [{"label": "标签名", "color": "#ea5252"}]'
+      value: "[]"
+    validations:
+      required: true
+
+  - type: textarea
+    id: config
+    attributes:
+      label: 插件配置项
+      description: 插件配置项
+      render: dotenv
+      placeholder: |
+        # e.g.
+        # KEY=VALUE
+        # KEY2=VALUE2

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

@@ -11,7 +11,7 @@ runs:
   using: "composite"
   steps:
     - name: Install poetry
-      run: pipx install poetry==1.3.2
+      run: pipx install poetry
       shell: bash
 
     - uses: actions/setup-python@v4

.github/workflows/noneflow.yml

@@ -0,0 +1,100 @@
+name: NoneFlow
+
+on:
+  issues:
+    types: [opened, reopened, edited]
+  pull_request_target:
+    types: [closed]
+  issue_comment:
+    types: [created]
+  pull_request_review:
+    types: [submitted]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.issue.number || github.run_id }}
+  cancel-in-progress: false
+
+jobs:
+  plugin_test:
+    runs-on: ubuntu-latest
+    name: nonebot2 plugin test
+    if: |
+      !(
+        (
+          github.event.pull_request &&
+          (
+            github.event.pull_request.head.repo.fork ||
+            !(
+              contains(github.event.pull_request.labels.*.name, 'Plugin') ||
+              contains(github.event.pull_request.labels.*.name, 'Adapter') ||
+              contains(github.event.pull_request.labels.*.name, 'Bot')
+            )
+          )
+        ) ||
+        (
+          github.event_name == 'issue_comment' && github.event.issue.pull_request
+        )
+      )
+    permissions:
+      issues: read
+    outputs:
+      result: ${{ steps.plugin-test.outputs.RESULT }}
+      output: ${{ steps.plugin-test.outputs.OUTPUT }}
+      metadata: ${{ steps.plugin-test.outputs.METADATA }}
+    steps:
+      - name: Install Poetry
+        if: ${{ !startsWith(github.event_name, 'pull_request') }}
+        run: pipx install poetry
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Test Plugin
+        id: plugin-test
+        run: |
+          curl -sSL https://github.com/nonebot/noneflow/releases/latest/download/plugin_test.py | python -
+  noneflow:
+    runs-on: ubuntu-latest
+    name: noneflow
+    needs: plugin_test
+    steps:
+      - name: Generate token
+        id: generate-token
+        uses: tibdex/github-app-token@v1
+        with:
+          app_id: ${{ secrets.APP_ID }}
+          private_key: ${{ secrets.APP_KEY }}
+
+      - name: Checkout Code
+        uses: actions/checkout@v3
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+
+      - name: Cache pre-commit hooks
+        uses: actions/cache@v3
+        with:
+          path: .cache/.pre-commit
+          key: noneflow-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: NoneFlow
+        uses: docker://ghcr.io/nonebot/noneflow:latest
+        with:
+          config: >
+            {
+              "base": "master",
+              "plugin_path": "website/static/plugins.json",
+              "bot_path": "website/static/bots.json",
+              "adapter_path": "website/static/adapters.json"
+            }
+        env:
+          PLUGIN_TEST_RESULT: ${{ needs.plugin_test.outputs.result }}
+          PLUGIN_TEST_OUTPUT: ${{ needs.plugin_test.outputs.output }}
+          PLUGIN_TEST_METADATA: ${{ needs.plugin_test.outputs.metadata }}
+          APP_ID: ${{ secrets.APP_ID }}
+          PRIVATE_KEY: ${{ secrets.APP_KEY }}
+          PRE_COMMIT_HOME: /github/workspace/.cache/.pre-commit
+
+      - name: Fix permission
+        run: sudo chown -R $(whoami):$(id -ng) .cache/.pre-commit

.github/workflows/publish-bot.yml

@@ -1,60 +0,0 @@
-name: NoneBot2 Publish Bot
-
-on:
-  issues:
-    types: [opened, reopened, edited]
-  pull_request_target:
-    types: [closed]
-  issue_comment:
-    types: [created]
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.event.issue.number || github.run_id }}
-  cancel-in-progress: true
-
-jobs:
-  plugin_test:
-    runs-on: ubuntu-latest
-    name: nonebot2 plugin test
-    if: github.event_name != 'issue_comment' || !github.event.issue.pull_request
-    permissions:
-      issues: read
-    outputs:
-      result: ${{ steps.plugin-test.outputs.RESULT }}
-      output: ${{ steps.plugin-test.outputs.OUTPUT }}
-    steps:
-      - name: Install Poetry
-        if: ${{ !startsWith(github.event_name, 'pull_request') }}
-        run: pipx install poetry
-      - name: Setup Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.10"
-      - name: Test Plugin
-        id: plugin-test
-        run: |
-          curl -sSL https://github.com/nonebot/nonebot2-publish-bot/releases/latest/download/plugin_test.py -o plugin_test.py
-          python plugin_test.py
-  publish_bot:
-    runs-on: ubuntu-latest
-    name: nonebot2 publish bot
-    needs: plugin_test
-    steps:
-      - name: Checkout Code
-        uses: actions/checkout@v3
-        with:
-          token: ${{ secrets.GH_TOKEN }}
-      - name: NoneBot2 Publish Bot
-        uses: docker://ghcr.io/nonebot/nonebot2-publish-bot:latest
-        with:
-          token: ${{ secrets.GH_TOKEN }}
-          config: >
-            {
-              "base": "master",
-              "plugin_path": "website/static/plugins.json",
-              "bot_path": "website/static/bots.json",
-              "adapter_path": "website/static/adapters.json"
-            }
-        env:
-          PLUGIN_TEST_RESULT: ${{ needs.plugin_test.outputs.result }}
-          PLUGIN_TEST_OUTPUT: ${{ needs.plugin_test.outputs.output }}

.github/workflows/pyright.yml

@@ -0,0 +1,26 @@
+name: Pyright Lint
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    paths:
+      - "nonebot/**"
+      - "packages/**"
+      - "tests/**"
+
+jobs:
+  pyright:
+    name: Pyright Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup Python environment
+        uses: ./.github/actions/setup-python
+
+      - run: echo "$(poetry env info --path)/bin" >> $GITHUB_PATH
+
+      - name: Run Pyright
+        uses: jakebailey/pyright-action@v1

.github/workflows/release-drafter.yml

@@ -18,9 +18,16 @@ jobs:
       group: pull-request-changelog
       cancel-in-progress: true
     steps:
+      - name: Generate token
+        id: generate-token
+        uses: tibdex/github-app-token@v1
+        with:
+          app_id: ${{ secrets.APP_ID }}
+          private_key: ${{ secrets.APP_KEY }}
+
       - uses: actions/checkout@v3
         with:
-          token: ${{ secrets.GH_TOKEN }}
+          token: ${{ steps.generate-token.outputs.token }}
 
       - name: Setup Node Environment
         uses: ./.github/actions/setup-node
@@ -43,8 +50,8 @@ jobs:
       - name: Commit and Push
         run: |
           yarn prettier
-          git config user.name github-actions[bot]
-          git config user.email github-actions[bot]@users.noreply.github.com
+          git config user.name noneflow[bot]
+          git config user.email 129742071+noneflow[bot]@users.noreply.github.com
           git add .
           git diff-index --quiet HEAD || git commit -m ":memo: Update changelog"
           git push

.github/workflows/release.yml

@@ -6,12 +6,17 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
-
     steps:
+      - name: Generate token
+        id: generate-token
+        uses: tibdex/github-app-token@v1
+        with:
+          app_id: ${{ secrets.APP_ID }}
+          private_key: ${{ secrets.APP_KEY }}
+
       - uses: actions/checkout@v3
         with:
-          ref: master
-          token: ${{ secrets.GH_TOKEN }}
+          token: ${{ steps.generate-token.outputs.token }}
 
       - name: Setup Python Environment
         uses: ./.github/actions/setup-python
@@ -39,8 +44,8 @@ jobs:
 
       - name: Push Tag
         run: |
-          git config user.name github-actions[bot]
-          git config user.email github-actions[bot]@users.noreply.github.com
+          git config user.name noneflow[bot]
+          git config user.email 129742071+noneflow[bot]@users.noreply.github.com
           git add .
           git commit -m ":bookmark: Release $(poetry version -s)"
           git tag ${{ env.TAG_NAME }}

.github/workflows/ruff.yml

@@ -0,0 +1,21 @@
+name: Ruff Lint
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    paths:
+      - "nonebot/**"
+      - "packages/**"
+      - "tests/**"
+
+jobs:
+  ruff:
+    name: Ruff Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Run Ruff Lint
+        uses: chartboost/ruff-action@v1

.pre-commit-config.yaml

@@ -6,11 +6,12 @@ ci:
   autoupdate_schedule: monthly
   autoupdate_commit_msg: ":arrow_up: auto update by pre-commit hooks"
 repos:
-  - repo: https://github.com/hadialqattan/pycln
-    rev: v2.1.3
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.0.276
     hooks:
-      - id: pycln
-        args: [--config, pyproject.toml]
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+        stages: [commit]
 
   - repo: https://github.com/pycqa/isort
     rev: 5.12.0
@@ -19,20 +20,20 @@ repos:
         stages: [commit]
 
   - repo: https://github.com/psf/black
-    rev: 23.1.0
+    rev: 23.3.0
     hooks:
       - id: black
         stages: [commit]
 
   - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: v3.0.0-alpha.6
+    rev: v3.0.0-alpha.9-for-vscode
     hooks:
       - id: prettier
         types_or: [javascript, jsx, ts, tsx, markdown, yaml, json]
         stages: [commit]
 
   - repo: https://github.com/nonebot/nonemoji
-    rev: v0.1.3
+    rev: v0.1.4
     hooks:
       - id: nonemoji
         stages: [prepare-commit-msg]

CHANGELOG.md

@@ -1,3 +1,3 @@
 # Changelog
 
-See [changelog.md](./website/src/pages/changelog.md) or <https://v2.nonebot.dev/changelog>
+See [changelog.md](./website/src/pages/changelog.md) or <https://nonebot.dev/changelog>

CONTRIBUTING.md

@@ -84,7 +84,7 @@ NoneBot2 的代码风格遵循 [PEP 8](https://www.python.org/dev/peps/pep-0008/
 
 ## 为社区做贡献
 
-你可以在 NoneBot 商店上架自己的适配器、插件、机器人，具体步骤可参考 [发布插件](https://v2.nonebot.dev/docs/developer/plugin-publishing) 一节。
+你可以在 NoneBot 商店上架自己的适配器、插件、机器人，具体步骤可参考 [发布插件](https://nonebot.dev/docs/developer/plugin-publishing) 一节。
 
 我们仅对插件的兼容性进行简单测试，并会在下一个版本发布前对与该版本不兼容的插件作出处理。
 

README.md

@@ -1,6 +1,6 @@
 <!-- markdownlint-disable MD033 MD041 -->
 <p align="center">
-  <a href="https://v2.nonebot.dev/"><img src="https://v2.nonebot.dev/logo.png" width="200" height="200" alt="nonebot"></a>
+  <a href="https://nonebot.dev/"><img src="https://nonebot.dev/logo.png" width="200" height="200" alt="nonebot"></a>
 </p>
 
 <div align="center">
@@ -19,9 +19,19 @@ _✨ 跨平台 Python 异步机器人框架 ✨_
     <img src="https://img.shields.io/github/license/nonebot/nonebot2" alt="license">
   </a>
   <a href="https://pypi.python.org/pypi/nonebot2">
-    <img src="https://img.shields.io/pypi/v/nonebot2" alt="pypi">
+    <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.8+-blue" alt="python">
+  <img src="https://img.shields.io/badge/python-3.8+-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>
+  <a href="https://github.com/Microsoft/pyright">
+    <img src="https://img.shields.io/badge/types-pyright-797952.svg?logo=python&logoColor=edb641" alt="pyright">
+  </a>
+  <a href="https://github.com/astral-sh/ruff">
+    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json" alt="ruff">
+  </a>
+  <br />
   <a href="https://codecov.io/gh/nonebot/nonebot2">
     <img src="https://codecov.io/gh/nonebot/nonebot2/branch/master/graph/badge.svg?token=2P0G0VS7N4" alt="codecov"/>
   </a>
@@ -31,6 +41,12 @@ _✨ 跨平台 Python 异步机器人框架 ✨_
   <a href="https://results.pre-commit.ci/latest/github/nonebot/nonebot2/master">
     <img src="https://results.pre-commit.ci/badge/github/nonebot/nonebot2/master.svg" alt="pre-commit" />
   </a>
+  <a href="https://github.com/nonebot/nonebot2/actions/workflows/pyright.yml">
+    <img src="https://github.com/nonebot/nonebot2/actions/workflows/pyright.yml/badge.svg?branch=master&event=push" alt="pyright">
+  </a>
+  <a href="https://github.com/nonebot/nonebot2/actions/workflows/ruff.yml">
+    <img src="https://github.com/nonebot/nonebot2/actions/workflows/ruff.yml/badge.svg?branch=master&event=push" alt="ruff">
+  </a>
   <br />
   <a href="https://onebot.dev/">
     <img src="https://img.shields.io/badge/OneBot-v11-black?style=social&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABABAMAAABYR2ztAAAAIVBMVEUAAAAAAAADAwMHBwceHh4UFBQNDQ0ZGRkoKCgvLy8iIiLWSdWYAAAAAXRSTlMAQObYZgAAAQVJREFUSMftlM0RgjAQhV+0ATYK6i1Xb+iMd0qgBEqgBEuwBOxU2QDKsjvojQPvkJ/ZL5sXkgWrFirK4MibYUdE3OR2nEpuKz1/q8CdNxNQgthZCXYVLjyoDQftaKuniHHWRnPh2GCUetR2/9HsMAXyUT4/3UHwtQT2AggSCGKeSAsFnxBIOuAggdh3AKTL7pDuCyABcMb0aQP7aM4AnAbc/wHwA5D2wDHTTe56gIIOUA/4YYV2e1sg713PXdZJAuncdZMAGkAukU9OAn40O849+0ornPwT93rphWF0mgAbauUrEOthlX8Zu7P5A6kZyKCJy75hhw1Mgr9RAUvX7A3csGqZegEdniCx30c3agAAAABJRU5ErkJggg==" alt="onebot">
@@ -49,9 +65,9 @@ _✨ 跨平台 Python 异步机器人框架 ✨_
   </a>
   <a href="https://bot.q.qq.com/wiki/">
     <img src="https://img.shields.io/badge/QQ%E9%A2%91%E9%81%93-Bot-lightgrey?style=social&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMTIuODIgMTMwLjg5Ij48ZyBkYXRhLW5hbWU9IuWbvuWxgiAyIj48ZyBkYXRhLW5hbWU9IuWbvuWxgiAxIj48cGF0aCBkPSJNNTUuNjMgMTMwLjhjLTcgMC0xMy45LjA4LTIwLjg2IDAtMTkuMTUtLjI1LTMxLjcxLTExLjQtMzQuMjItMzAuMy00LjA3LTMwLjY2IDE0LjkzLTU5LjIgNDQuODMtNjYuNjQgMi0uNTEgNS4yMS0uMzEgNS4yMS0xLjYzIDAtMi4xMy4xNC0yLjEzLjE0LTUuNTcgMC0uODktMS4zLTEuNDYtMi4yMi0yLjMxLTYuNzMtNi4yMy03LjY3LTEzLjQxLTEtMjAuMTggNS40LTUuNTIgMTEuODctNS40IDE3LjgtLjU5IDYuNDkgNS4yNiA2LjMxIDEzLjA4LS44NiAyMS0uNjguNzQtMS43OCAxLjYtMS43OCAyLjY3djQuMjFjMCAxLjM1IDIuMiAxLjYyIDQuNzkgMi4zNSAzMS4wOSA4LjY1IDQ4LjE3IDM0LjEzIDQ1IDY2LjM3LTEuNzYgMTguMTUtMTQuNTYgMzAuMjMtMzIuNyAzMC42My04LjAyLjE5LTE2LjA3LS4wMS0yNC4xMy0uMDF6IiBmaWxsPSIjMDI5OWZlIi8+PHBhdGggZD0iTTMxLjQ2IDExOC4zOGMtMTAuNS0uNjktMTYuOC02Ljg2LTE4LjM4LTE3LjI3LTMtMTkuNDIgMi43OC0zNS44NiAxOC40Ni00Ny44MyAxNC4xNi0xMC44IDI5Ljg3LTEyIDQ1LjM4LTMuMTkgMTcuMjUgOS44NCAyNC41OSAyNS44MSAyNCA0NS4yOS0uNDkgMTUuOS04LjQyIDIzLjE0LTI0LjM4IDIzLjUtNi41OS4xNC0xMy4xOSAwLTE5Ljc5IDAiIGZpbGw9IiNmZWZlZmUiLz48cGF0aCBkPSJNNDYuMDUgNzkuNThjLjA5IDUgLjIzIDkuODItNyA5Ljc3LTcuODItLjA2LTYuMS01LjY5LTYuMjQtMTAuMTktLjE1LTQuODItLjczLTEwIDYuNzMtOS44NHM2LjM3IDUuNTUgNi41MSAxMC4yNnoiIGZpbGw9IiMxMDlmZmUiLz48cGF0aCBkPSJNODAuMjcgNzkuMjdjLS41MyAzLjkxIDEuNzUgOS42NC01Ljg4IDEwLTcuNDcuMzctNi44MS00LjgyLTYuNjEtOS41LjItNC4zMi0xLjgzLTEwIDUuNzgtMTAuNDJzNi41OSA0Ljg5IDYuNzEgOS45MnoiIGZpbGw9IiMwODljZmUiLz48L2c+PC9nPjwvc3ZnPg==" alt="QQ频道">
-  <a href="https://ding-doc.dingtalk.com/document#/org-dev-guide/elzz1p">
-    <img src="https://img.shields.io/badge/%E9%92%89%E9%92%89-Bot-lightgrey?style=social&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAMAAACdt4HsAAAAnFBMVEUAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD4jUzeAAAAM3RSTlMAQKSRaA+/f0YyFevh29R3cyklIfrlyrGsn41tVUs48c/HqJm9uZdhX1otGwkF9IN8V1CX0Q+IAAABY0lEQVRYw+3V2W7CMBAF0JuNQAhhX9OEfYdu9///rUVWpagE27Ef2gfO+0zGozsKnv6bMGzAhkNytIe5gDdzrwtTCwrbI8x4/NF668NAxgI3Q3UtFi3TyPwNQtPLUUmDd8YfqGLNe4v22XwEYb5zoOuF5baHq2UHtsKe5ivWfGAwrWu2mC34QM0PoCAuqZdOmiwV+5BLyMRtZ7dTSEcs48rzWfzwptMLyzpApka1SJ5FtR4kfCqNIBPEVDmqoqgwUYY5plQOlf6UEjNoOPnuKB6wzDyCrks///TDza8+PnR109WQdxLo8RKWq0PPnuXG0OXKQ6wWLFnCg75uYYbhmMIVVdQ709q33aHbGIj6Duz+2k1HQFX9VwqmY8xYsEJll2ahvhWgsjYLHFRXvIi2Qb0jzMQCzC3FAoydxCma88UCzE3JCWwkjCNYyMUCzHX4DiuTMawEwwhW6hnshPhjZzzJfAH0YacpbmRd7QAAAABJRU5ErkJggg==" alt="dingtalk">
   </a>
+  <!-- <a href="https://ding-doc.dingtalk.com/document#/org-dev-guide/elzz1p">
+    <img src="https://img.shields.io/badge/%E9%92%89%E9%92%89-Bot-lightgrey?style=social&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAMAAACdt4HsAAAAnFBMVEUAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD4jUzeAAAAM3RSTlMAQKSRaA+/f0YyFevh29R3cyklIfrlyrGsn41tVUs48c/HqJm9uZdhX1otGwkF9IN8V1CX0Q+IAAABY0lEQVRYw+3V2W7CMBAF0JuNQAhhX9OEfYdu9///rUVWpagE27Ef2gfO+0zGozsKnv6bMGzAhkNytIe5gDdzrwtTCwrbI8x4/NF668NAxgI3Q3UtFi3TyPwNQtPLUUmDd8YfqGLNe4v22XwEYb5zoOuF5baHq2UHtsKe5ivWfGAwrWu2mC34QM0PoCAuqZdOmiwV+5BLyMRtZ7dTSEcs48rzWfzwptMLyzpApka1SJ5FtR4kfCqNIBPEVDmqoqgwUYY5plQOlf6UEjNoOPnuKB6wzDyCrks///TDza8+PnR109WQdxLo8RKWq0PPnuXG0OXKQ6wWLFnCg75uYYbhmMIVVdQ709q33aHbGIj6Duz+2k1HQFX9VwqmY8xYsEJll2ahvhWgsjYLHFRXvIi2Qb0jzMQCzC3FAoydxCma88UCzE3JCWwkjCNYyMUCzHX4DiuTMawEwwhW6hnshPhjZzzJfAH0YacpbmRd7QAAAABJRU5ErkJggg==" alt="dingtalk"> -->
   </a>
   <br />
   <a href="https://jq.qq.com/?_wv=1027&k=5OFifDh">
@@ -69,16 +85,16 @@ _✨ 跨平台 Python 异步机器人框架 ✨_
 </p>
 
 <p align="center">
-  <a href="https://v2.nonebot.dev/">文档</a>
+  <a href="https://nonebot.dev/">文档</a>
   ·
-  <a href="https://v2.nonebot.dev/docs/quick-start">快速上手</a>
+  <a href="https://nonebot.dev/docs/quick-start">快速上手</a>
   ·
   <a href="#插件">文档打不开？</a>
 </p>
 
 <p align="center">
   <a href="https://asciinema.org/a/569440">
-    <img src="https://v2.nonebot.dev/img/setup.svg">
+    <img src="https://nonebot.dev/img/setup.svg">
   </a>
 </p>
 
@@ -90,36 +106,38 @@ NoneBot2 是一个现代、跨平台、可扩展的 Python 聊天机器人框架
 
 - 异步优先：基于 Python 的异步特性，即使是~~非常~~大量的消息，也能吞吐自如
 - 易于开发：配合 NB-CLI 脚手架，代码编写上手简单，没有过多的冗余代码，可以让开发者专注于业务逻辑
-- 生而可靠：100% 类型注解覆盖，配合编辑器的类型推导功能，能将绝大多数的 Bug 杜绝在编辑器中 ([编辑器支持](https://v2.nonebot.dev/docs/editor-support))
+- 生而可靠：100% 类型注解覆盖，配合编辑器的类型推导功能，能将绝大多数的 Bug 杜绝在编辑器中 ([编辑器支持](https://nonebot.dev/docs/editor-support))
 - 社区丰富：社区用户众多，直接和间接用户超过十万人，每天都有大量的活跃用户 ([社区资源](#社区资源))
 - 海纳百川：一个框架，支持多个聊天软件平台，可自定义通信协议
 
   |                                                       协议名称                                                        | 状态 |                                   注释                                    |
-  | :-----------------------------------------------------------------------: | :--: | :----------------------------------------------------------------: |
-  |                    [OneBot 协议](https://onebot.dev/)                     |  ✅  | 支持 QQ、TG、微信公众号等[平台](https://onebot.dev/ecosystem.html) |
-  |              [Telegram](https://core.telegram.org/bots/api)               |  ✅  |                                                                    |
-  |            [飞书](https://open.feishu.cn/document/home/index)             |  ✅  |                                                                    |
-  |           [GitHub](https://docs.github.com/en/developers/apps)            |  ✅  |                       GitHub APP & OAuth APP                       |
-  |                   [QQ 频道](https://bot.q.qq.com/wiki/)                   |  ✅  |                          官方接口调整较多                          |
-  |                [钉钉](https://open.dingtalk.com/document/)                |  🤗  |                          寻找 Maintainer                           |
-  |                                  Console                                  |  ✅  |                             控制台交互                             |
-  |                  [开黑啦](https://developer.kookapp.cn/)                  |  ↗️  |                             由社区贡献                             |
-  |           [Mirai](https://docs.mirai.mamoe.net/mirai-api-http/)           |  ↗️  |                             由社区贡献                             |
-  |        [Ntchat](https://github.com/JustUndertaker/adapter-ntchat)         |  ↗️  |                             由社区贡献                             |
-  | [MineCraft (Spigot)](https://github.com/17TheWord/nonebot-adapter-spigot) |  ↗️  |                             由社区贡献                             |
-  |        [BiliBili Live](https://github.com/wwweww/adapter-bilibili)        |  ↗️  |                             由社区贡献                             |
+  | :-------------------------------------------------------------------------------------------------------------------: | :--: | :-----------------------------------------------------------------------: |
+  |               OneBot（[仓库](https://github.com/nonebot/adapter-onebot)，[协议](https://onebot.dev/)）                |  ✅  | 支持 QQ、TG、微信公众号、KOOK 等[平台](https://onebot.dev/ecosystem.html) |
+  |      Telegram（[仓库](https://github.com/nonebot/adapter-telegram)，[协议](https://core.telegram.org/bots/api)）      |  ✅  |                                                                           |
+  |     飞书（[仓库](https://github.com/nonebot/adapter-feishu)，[协议](https://open.feishu.cn/document/home/index)）     |  ✅  |                                                                           |
+  |         GitHub（[仓库](https://github.com/nonebot/adapter-github)，[协议](https://docs.github.com/en/apps)）          |  ✅  |                          GitHub APP & OAuth APP                           |
+  |           QQ 频道（[仓库](https://github.com/nonebot/adapter-qqguild)，[协议](https://bot.q.qq.com/wiki/)）           |  ✅  |                             官方接口调整较多                              |
+  |         钉钉（[仓库](https://github.com/nonebot/adapter-ding)，[协议](https://open.dingtalk.com/document/)）          |  🤗  |                        寻找 Maintainer（暂不可用）                        |
+  |                             Console（[仓库](https://github.com/nonebot/adapter-console)）                             |  ✅  |                                控制台交互                                 |
+  |     开黑啦（[仓库](https://github.com/Tian-que/nonebot-adapter-kaiheila)，[协议](https://developer.kookapp.cn/)）     |  ↗️  |                                由社区贡献                                 |
+  | Mirai（[仓库](https://github.com/ieew/nonebot_adapter_mirai2)，[协议](https://docs.mirai.mamoe.net/mirai-api-http/)） |  ↗️  |                            QQ 协议，由社区贡献                            |
+  |                          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 协议，由社区贡献                     |
 
 - 坚实后盾：支持多种 web 框架，可自定义替换、组合
 
   |                              驱动框架                               |  类型  |
-  | :--------------------------------------------------------: | :----: |
+  | :-----------------------------------------------------------------: | :----: |
   |              [FastAPI](https://fastapi.tiangolo.com/)               | 服务端 |
-  |   [Quart](https://pgjones.gitlab.io/quart/) (异步 Flask)   | 服务端 |
+  | [Quart](https://quart.palletsprojects.com/en/latest/)（异步 Flask） | 服务端 |
   |           [aiohttp](https://docs.aiohttp.org/en/stable/)            | 客户端 |
   |               [httpx](https://www.python-httpx.org/)                | 客户端 |
   |     [websockets](https://websockets.readthedocs.io/en/stable/)      | 客户端 |
 
-更多：[概览](https://v2.nonebot.dev/docs/)
+更多：[概览](https://nonebot.dev/docs/)
 
 ## 什么不是 NoneBot2
 
@@ -131,7 +149,7 @@ NoneBot2 不是 NoneBot1 的替代品。事实上，它们都在被积极的维
 
 ## 即刻开始
 
-~~完整~~文档可以在 [这里](https://v2.nonebot.dev/) 查看。
+~~完整~~文档可以在 [这里](https://nonebot.dev/) 查看。
 
 懒得看文档？下面是快速安装指南：
 
@@ -188,7 +206,7 @@ NoneBot2 不是 NoneBot1 的替代品。事实上，它们都在被积极的维
   - [文档镜像(中国境内)](https://nb2.baka.icu)
   - [文档镜像(Vercel)](https://nonebot2-vercel-mirror.vercel.app)
 
-- 其他插件请查看 [商店](https://v2.nonebot.dev/store)
+- 其他插件请查看 [商店](https://nonebot.dev/store)
 
 ## 许可证
 

nonebot/__init__.py

@@ -24,12 +24,17 @@
 - `load_all_plugins` => {ref}``load_all_plugins` <nonebot.plugin.load.load_all_plugins>`
 - `load_from_json` => {ref}``load_from_json` <nonebot.plugin.load.load_from_json>`
 - `load_from_toml` => {ref}``load_from_toml` <nonebot.plugin.load.load_from_toml>`
-- `load_builtin_plugin` => {ref}``load_builtin_plugin` <nonebot.plugin.load.load_builtin_plugin>`
-- `load_builtin_plugins` => {ref}``load_builtin_plugins` <nonebot.plugin.load.load_builtin_plugins>`
+- `load_builtin_plugin` =>
+  {ref}``load_builtin_plugin` <nonebot.plugin.load.load_builtin_plugin>`
+- `load_builtin_plugins` =>
+  {ref}``load_builtin_plugins` <nonebot.plugin.load.load_builtin_plugins>`
 - `get_plugin` => {ref}``get_plugin` <nonebot.plugin.get_plugin>`
-- `get_plugin_by_module_name` => {ref}``get_plugin_by_module_name` <nonebot.plugin.get_plugin_by_module_name>`
-- `get_loaded_plugins` => {ref}``get_loaded_plugins` <nonebot.plugin.get_loaded_plugins>`
-- `get_available_plugin_names` => {ref}``get_available_plugin_names` <nonebot.plugin.get_available_plugin_names>`
+- `get_plugin_by_module_name` =>
+  {ref}``get_plugin_by_module_name` <nonebot.plugin.get_plugin_by_module_name>`
+- `get_loaded_plugins` =>
+  {ref}``get_loaded_plugins` <nonebot.plugin.get_loaded_plugins>`
+- `get_available_plugin_names` =>
+  {ref}``get_available_plugin_names` <nonebot.plugin.get_available_plugin_names>`
 - `require` => {ref}``require` <nonebot.plugin.load.require>`
 
 FrontMatter:
@@ -69,7 +74,8 @@ def get_driver() -> Driver:
         全局 {ref}`nonebot.drivers.Driver` 对象
 
     异常:
-        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init <nonebot.init>` 尚未调用)
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化
+            ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
     用法:
         ```python
@@ -83,23 +89,33 @@ def get_driver() -> Driver:
 
 @overload
 def get_adapter(name: str) -> Adapter:
-    ...
+    """
+    参数:
+        name: 适配器名称
+
+    返回:
+        指定名称的 {ref}`nonebot.adapters.Adapter` 对象
+    """
 
 
 @overload
 def get_adapter(name: Type[A]) -> A:
-    ...
+    """
+    参数:
+        name: 适配器类型
+
+    返回:
+        指定类型的 {ref}`nonebot.adapters.Adapter` 对象
+    """
 
 
 def get_adapter(name: Union[str, Type[Adapter]]) -> Adapter:
     """获取已注册的 {ref}`nonebot.adapters.Adapter` 实例。
 
-    返回:
-        指定名称或类型的 {ref}`nonebot.adapters.Adapter` 对象
-
     异常:
         ValueError: 指定的 {ref}`nonebot.adapters.Adapter` 未注册
-        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init <nonebot.init>` 尚未调用)
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化
+            ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
     用法:
         ```python
@@ -121,7 +137,8 @@ def get_adapters() -> Dict[str, Adapter]:
         所有 {ref}`nonebot.adapters.Adapter` 实例字典
 
     异常:
-        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init <nonebot.init>` 尚未调用)
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化
+            ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
     用法:
         ```python
@@ -139,7 +156,8 @@ def get_app() -> Any:
 
     异常:
         AssertionError: 全局 Driver 对象不是 {ref}`nonebot.drivers.ReverseDriver` 类型
-        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init <nonebot.init>` 尚未调用)
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化
+            ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
     用法:
         ```python
@@ -154,14 +172,16 @@ def get_app() -> Any:
 
 
 def get_asgi() -> Any:
-    """获取全局 {ref}`nonebot.drivers.ReverseDriver` 对应 [ASGI](https://asgi.readthedocs.io/) 对象。
+    """获取全局 {ref}`nonebot.drivers.ReverseDriver` 对应
+    [ASGI](https://asgi.readthedocs.io/) 对象。
 
     返回:
         ASGI 对象
 
     异常:
         AssertionError: 全局 Driver 对象不是 {ref}`nonebot.drivers.ReverseDriver` 类型
-        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init <nonebot.init>` 尚未调用)
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化
+            ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
     用法:
         ```python
@@ -182,7 +202,8 @@ def get_bot(self_id: Optional[str] = None) -> Bot:
     当不提供时，返回一个 {ref}`nonebot.adapters.Bot`。
 
     参数:
-        self_id: 用来识别 {ref}`nonebot.adapters.Bot` 的 {ref}`nonebot.adapters.Bot.self_id` 属性
+        self_id: 用来识别 {ref}`nonebot.adapters.Bot` 的
+            {ref}`nonebot.adapters.Bot.self_id` 属性
 
     返回:
         {ref}`nonebot.adapters.Bot` 对象
@@ -190,7 +211,8 @@ def get_bot(self_id: Optional[str] = None) -> Bot:
     异常:
         KeyError: 对应 self_id 的 Bot 不存在
         ValueError: 没有传入 self_id 且没有 Bot 可用
-        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init <nonebot.init>` 尚未调用)
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化
+            ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
     用法:
         ```python
@@ -213,10 +235,12 @@ def get_bots() -> Dict[str, Bot]:
     """获取所有连接到 NoneBot 的 {ref}`nonebot.adapters.Bot` 对象。
 
     返回:
-        一个以 {ref}`nonebot.adapters.Bot.self_id` 为键，{ref}`nonebot.adapters.Bot` 对象为值的字典
+        一个以 {ref}`nonebot.adapters.Bot.self_id` 为键
+        {ref}`nonebot.adapters.Bot` 对象为值的字典
 
     异常:
-        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化 ({ref}`nonebot.init <nonebot.init>` 尚未调用)
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化
+            ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
     用法:
         ```python

nonebot/adapters/__init__.py

@@ -19,6 +19,11 @@ __autodoc__ = {
     "Event": True,
     "Adapter": True,
     "Message": True,
+    "Message.__getitem__": True,
+    "Message.__contains__": True,
+    "Message._construct": True,
     "MessageSegment": True,
+    "MessageSegment.__str__": True,
+    "MessageSegment.__add__": True,
     "MessageTemplate": True,
 }

nonebot/config.py

@@ -1,19 +1,23 @@
 """本模块定义了 NoneBot 本身运行所需的配置项。
 
-NoneBot 使用 [`pydantic`](https://pydantic-docs.helpmanual.io/) 以及 [`python-dotenv`](https://saurabh-kumar.com/python-dotenv/) 来读取配置。
+NoneBot 使用 [`pydantic`](https://pydantic-docs.helpmanual.io/) 以及
+[`python-dotenv`](https://saurabh-kumar.com/python-dotenv/) 来读取配置。
 
-配置项需符合特殊格式或 json 序列化格式。详情见 [`pydantic Field Type`](https://pydantic-docs.helpmanual.io/usage/types/) 文档。
+配置项需符合特殊格式或 json 序列化格式
+详情见 [`pydantic Field Type`](https://pydantic-docs.helpmanual.io/usage/types/) 文档。
 
 FrontMatter:
     sidebar_position: 1
     description: nonebot.config 模块
 """
+
 import os
 from datetime import timedelta
 from ipaddress import IPv4Address
 from typing import TYPE_CHECKING, Any, Set, Dict, Tuple, Union, Mapping, Optional
 
 from pydantic.utils import deep_update
+from pydantic.fields import Undefined, UndefinedType
 from pydantic import Extra, Field, BaseSettings, IPvAnyAddress
 from pydantic.env_settings import (
     DotenvType,
@@ -28,9 +32,8 @@ from nonebot.log import logger
 
 class CustomEnvSettings(EnvSettingsSource):
     def __call__(self, settings: BaseSettings) -> Dict[str, Any]:
-        """
-        Build environment variables suitable for passing to the Model.
-        """
+        """从环境变量和 dotenv 配置文件中读取配置项。"""
+
         d: Dict[str, Any] = {}
 
         if settings.__config__.case_sensitive:
@@ -42,21 +45,25 @@ class CustomEnvSettings(EnvSettingsSource):
         env_vars = {**env_file_vars, **env_vars}
 
         for field in settings.__fields__.values():
-            env_val: Optional[str] = None
+            env_val: Union[str, None, UndefinedType] = Undefined
             for env_name in field.field_info.extra["env_names"]:
-                env_val = env_vars.get(env_name)
+                env_val = env_vars.get(env_name, Undefined)
                 if env_name in env_file_vars:
                     del env_file_vars[env_name]
-                if env_val is not None:
+                if env_val is not Undefined:
                     break
 
             is_complex, allow_parse_failure = self.field_is_complex(field)
             if is_complex:
-                if env_val is None:
+                if isinstance(env_val, UndefinedType):
+                    # field is complex but no value found so far, try explode_env_vars
                     if env_val_built := self.explode_env_vars(field, env_vars):
                         d[field.alias] = env_val_built
+                elif env_val is None:
+                    d[field.alias] = env_val
                 else:
-                    # field is complex and there's a value, decode that as JSON, then add explode_env_vars
+                    # field is complex and there's a value
+                    # decode that as JSON, then add explode_env_vars
                     try:
                         env_val = settings.__config__.parse_env_var(field.name, env_val)
                     except ValueError as e:
@@ -71,8 +78,9 @@ class CustomEnvSettings(EnvSettingsSource):
                         )
                     else:
                         d[field.alias] = env_val
-            elif env_val is not None:
-                # simplest case, field is not complex, we only need to add the value if it was found
+            elif not isinstance(env_val, UndefinedType):
+                # simplest case, field is not complex
+                # we only need to add the value if it was found
                 d[field.alias] = env_val
 
         # remain user custom config
@@ -82,7 +90,7 @@ class CustomEnvSettings(EnvSettingsSource):
                 # there's a value, decode that as JSON
                 try:
                     env_val = settings.__config__.parse_env_var(env_name, val_striped)
-                except ValueError as e:
+                except ValueError:
                     logger.trace(
                         "Error while parsing JSON for "
                         f"{env_name!r}={val_striped!r}. "
@@ -139,7 +147,7 @@ class BaseConfig(BaseSettings):
 class Env(BaseConfig):
     """运行环境配置。大小写不敏感。
 
-    将会从 `环境变量` > `.env 环境配置文件` 的优先级读取环境信息。
+    将会从 **环境变量** > **dotenv 配置文件** 的优先级读取环境信息。
     """
 
     environment: str = "prod"
@@ -158,7 +166,7 @@ class Config(BaseConfig):
     除了 NoneBot 的配置项外，还可以自行添加配置项到 `.env.{environment}` 文件中。
     这些配置将会在 json 反序列化后一起带入 `Config` 类中。
 
-    配置方法参考: [配置](https://v2.nonebot.dev/docs/appendices/config)
+    配置方法参考: [配置](https://nonebot.dev/docs/appendices/config)
     """
 
     _env_file: DotenvType = ".env", ".env.prod"
@@ -170,15 +178,17 @@ class Config(BaseConfig):
     配置格式为 `<module>[:<Driver>][+<module>[:<Mixin>]]*`。
 
     `~` 为 `nonebot.drivers.` 的缩写。
+
+    配置方法参考: [配置驱动器](https://nonebot.dev/docs/advanced/driver#%E9%85%8D%E7%BD%AE%E9%A9%B1%E5%8A%A8%E5%99%A8)
     """
     host: IPvAnyAddress = IPv4Address("127.0.0.1")  # type: ignore
     """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"
-    """NoneBot 日志输出等级，可以为 `int` 类型等级或等级名称
+    """NoneBot 日志输出等级，可以为 `int` 类型等级或等级名称。
 
-    参考 [`loguru 日志等级`](https://loguru.readthedocs.io/en/stable/api/logger.html#levels)。
+    参考 [记录日志](https://nonebot.dev/docs/appendices/log)，[loguru 日志等级](https://loguru.readthedocs.io/en/stable/api/logger.html#levels)。
 
     :::tip 提示
     日志等级名称应为大写，如 `INFO`。
@@ -209,6 +219,8 @@ class Config(BaseConfig):
     command_start: Set[str] = {"/"}
     """命令的起始标记，用于判断一条消息是不是命令。
 
+    参考[命令响应规则](https://nonebot.dev/docs/advanced/matcher#command)。
+
     用法:
         ```conf
         COMMAND_START=["/", ""]
@@ -217,6 +229,8 @@ class Config(BaseConfig):
     command_sep: Set[str] = {"."}
     """命令的分隔标记，用于将文本形式的命令切分为元组（实际的命令名）。
 
+    参考[命令响应规则](https://nonebot.dev/docs/advanced/matcher#command)。
+
     用法:
         ```conf
         COMMAND_SEP=["."]

nonebot/consts.py

@@ -4,6 +4,7 @@ FrontMatter:
     sidebar_position: 9
     description: nonebot.consts 模块
 """
+
 import os
 import sys
 from typing import Literal
@@ -42,12 +43,6 @@ SHELL_ARGV: Literal["_argv"] = "_argv"
 
 REGEX_MATCHED: Literal["_matched"] = "_matched"
 """正则匹配结果存储 key"""
-REGEX_STR: Literal["_matched_str"] = "_matched_str"
-"""正则匹配文本存储 key"""
-REGEX_GROUP: Literal["_matched_groups"] = "_matched_groups"
-"""正则匹配 group 元组存储 key"""
-REGEX_DICT: Literal["_matched_dict"] = "_matched_dict"
-"""正则匹配 group 字典存储 key"""
 STARTSWITH_KEY: Literal["_startswith"] = "_startswith"
 """响应触发前缀 key"""
 ENDSWITH_KEY: Literal["_endswith"] = "_endswith"

nonebot/dependencies/__init__.py

@@ -82,8 +82,8 @@ class Dependent(Generic[R]):
     """
 
     call: _DependentCallable[R]
-    params: Tuple[ModelField] = field(default_factory=tuple)
-    parameterless: Tuple[Param] = field(default_factory=tuple)
+    params: Tuple[ModelField, ...] = field(default_factory=tuple)
+    parameterless: Tuple[Param, ...] = field(default_factory=tuple)
 
     def __repr__(self) -> str:
         if inspect.isfunction(self.call) or inspect.isclass(self.call):
@@ -129,7 +129,8 @@ class Dependent(Generic[R]):
                         break
                 else:
                     raise ValueError(
-                        f"Unknown parameter {param.name} for function {call} with type {param.annotation}"
+                        f"Unknown parameter {param.name} "
+                        f"for function {call} with type {param.annotation}"
                     )
 
             default_value = field_info.default
@@ -182,7 +183,7 @@ class Dependent(Generic[R]):
 
         params = cls.parse_params(call, allow_types)
         parameterless_params = (
-            tuple()
+            ()
             if parameterless is None
             else cls.parse_parameterless(tuple(parameterless), allow_types)
         )

nonebot/dependencies/utils.py

@@ -3,6 +3,7 @@ FrontMatter:
     sidebar_position: 1
     description: nonebot.dependencies.utils 模块
 """
+
 import inspect
 from typing import Any, Dict, TypeVar, Callable, ForwardRef
 
@@ -17,6 +18,7 @@ V = TypeVar("V")
 
 def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature:
     """获取可调用对象签名"""
+
     signature = inspect.signature(call)
     globalns = getattr(call, "__globals__", {})
     typed_params = [
@@ -33,6 +35,7 @@ def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature:
 
 def get_typed_annotation(param: inspect.Parameter, globalns: Dict[str, Any]) -> Any:
     """获取参数的类型注解"""
+
     annotation = param.annotation
     if isinstance(annotation, str):
         annotation = ForwardRef(annotation)
@@ -47,6 +50,8 @@ def get_typed_annotation(param: inspect.Parameter, globalns: Dict[str, Any]) ->
 
 
 def check_field_type(field: ModelField, value: V) -> V:
+    """检查字段类型是否匹配"""
+
     _, errs_ = field.validate(value, {}, loc=())
     if errs_:
         raise TypeMisMatch(field, value)

nonebot/drivers/_lifespan.py

@@ -1,10 +1,11 @@
+from typing_extensions import TypeAlias
 from typing import Any, List, Union, Callable, Awaitable, cast
 
 from nonebot.utils import run_sync, is_coroutine_callable
 
-SYNC_LIFESPAN_FUNC = Callable[[], Any]
-ASYNC_LIFESPAN_FUNC = Callable[[], Awaitable[Any]]
-LIFESPAN_FUNC = Union[SYNC_LIFESPAN_FUNC, ASYNC_LIFESPAN_FUNC]
+SYNC_LIFESPAN_FUNC: TypeAlias = Callable[[], Any]
+ASYNC_LIFESPAN_FUNC: TypeAlias = Callable[[], Awaitable[Any]]
+LIFESPAN_FUNC: TypeAlias = Union[SYNC_LIFESPAN_FUNC, ASYNC_LIFESPAN_FUNC]
 
 
 class Lifespan:

nonebot/drivers/aiohttp.py

@@ -15,10 +15,10 @@ FrontMatter:
     description: nonebot.drivers.aiohttp 模块
 """
 
+from typing_extensions import override
 from typing import Type, AsyncGenerator
 from contextlib import asynccontextmanager
 
-from nonebot.typing import overrides
 from nonebot.drivers import Request, Response
 from nonebot.exception import WebSocketClosed
 from nonebot.drivers.none import Driver as NoneDriver
@@ -29,7 +29,8 @@ try:
     import aiohttp
 except ModuleNotFoundError as e:  # pragma: no cover
     raise ImportError(
-        "Please install aiohttp first to use this driver. `pip install nonebot2[aiohttp]`"
+        "Please install aiohttp first to use this driver. "
+        "Install with pip: `pip install nonebot2[aiohttp]`"
     ) from e
 
 
@@ -37,11 +38,11 @@ class Mixin(ForwardMixin):
     """AIOHTTP Mixin"""
 
     @property
-    @overrides(ForwardMixin)
+    @override
     def type(self) -> str:
         return "aiohttp"
 
-    @overrides(ForwardMixin)
+    @override
     async def request(self, setup: Request) -> Response:
         if setup.version == HTTPVersion.H10:
             version = aiohttp.HttpVersion10
@@ -51,11 +52,12 @@ class Mixin(ForwardMixin):
             raise RuntimeError(f"Unsupported HTTP version: {setup.version}")
 
         timeout = aiohttp.ClientTimeout(setup.timeout)
-        files = None
+
+        data = setup.data
         if setup.files:
-            files = aiohttp.FormData()
+            data = aiohttp.FormData(data or {})
             for name, file in setup.files:
-                files.add_field(name, file[1], content_type=file[2], filename=file[0])
+                data.add_field(name, file[1], content_type=file[2], filename=file[0])
 
         cookies = {
             cookie.name: cookie.value for cookie in setup.cookies if cookie.value
@@ -66,7 +68,7 @@ class Mixin(ForwardMixin):
             async with session.request(
                 setup.method,
                 setup.url,
-                data=setup.content or setup.data or files,
+                data=setup.content or data,
                 json=setup.json,
                 headers=setup.headers,
                 timeout=timeout,
@@ -79,7 +81,7 @@ class Mixin(ForwardMixin):
                     request=setup,
                 )
 
-    @overrides(ForwardMixin)
+    @override
     @asynccontextmanager
     async def websocket(self, setup: Request) -> AsyncGenerator["WebSocket", None]:
         if setup.version == HTTPVersion.H10:
@@ -115,15 +117,15 @@ class WebSocket(BaseWebSocket):
         self.websocket = websocket
 
     @property
-    @overrides(BaseWebSocket)
+    @override
     def closed(self):
         return self.websocket.closed
 
-    @overrides(BaseWebSocket)
+    @override
     async def accept(self):
         raise NotImplementedError
 
-    @overrides(BaseWebSocket)
+    @override
     async def close(self, code: int = 1000):
         await self.websocket.close(code=code)
         await self.session.close()
@@ -134,7 +136,7 @@ class WebSocket(BaseWebSocket):
             raise WebSocketClosed(self.websocket.close_code or 1006)
         return msg
 
-    @overrides(BaseWebSocket)
+    @override
     async def receive(self) -> str:
         msg = await self._receive()
         if msg.type not in (aiohttp.WSMsgType.TEXT, aiohttp.WSMsgType.BINARY):
@@ -143,7 +145,7 @@ class WebSocket(BaseWebSocket):
             )
         return msg.data
 
-    @overrides(BaseWebSocket)
+    @override
     async def receive_text(self) -> str:
         msg = await self._receive()
         if msg.type != aiohttp.WSMsgType.TEXT:
@@ -152,7 +154,7 @@ class WebSocket(BaseWebSocket):
             )
         return msg.data
 
-    @overrides(BaseWebSocket)
+    @override
     async def receive_bytes(self) -> bytes:
         msg = await self._receive()
         if msg.type != aiohttp.WSMsgType.BINARY:
@@ -161,11 +163,11 @@ class WebSocket(BaseWebSocket):
             )
         return msg.data
 
-    @overrides(BaseWebSocket)
+    @override
     async def send_text(self, data: str) -> None:
         await self.websocket.send_str(data)
 
-    @overrides(BaseWebSocket)
+    @override
     async def send_bytes(self, data: bytes) -> None:
         await self.websocket.send_bytes(data)
 

nonebot/drivers/fastapi.py

@@ -19,12 +19,12 @@ FrontMatter:
 import logging
 import contextlib
 from functools import wraps
+from typing_extensions import override
 from typing import Any, Dict, List, Tuple, Union, Optional
 
 from pydantic import BaseSettings
 
 from nonebot.config import Env
-from nonebot.typing import overrides
 from nonebot.exception import WebSocketClosed
 from nonebot.internal.driver import FileTypes
 from nonebot.config import Config as NoneBotConfig
@@ -41,7 +41,8 @@ try:
     from starlette.websockets import WebSocket, WebSocketState, WebSocketDisconnect
 except ModuleNotFoundError as e:  # pragma: no cover
     raise ImportError(
-        "Please install FastAPI by using `pip install nonebot2[fastapi]`"
+        "Please install FastAPI first to use this driver. "
+        "Install with pip: `pip install nonebot2[fastapi]`"
     ) from e
 
 
@@ -90,7 +91,7 @@ class Driver(ReverseDriver):
     """FastAPI 驱动框架。"""
 
     def __init__(self, env: Env, config: NoneBotConfig):
-        super(Driver, self).__init__(env, config)
+        super().__init__(env, config)
 
         self.fastapi_config: Config = Config(**config.dict())
 
@@ -105,30 +106,30 @@ class Driver(ReverseDriver):
         )
 
     @property
-    @overrides(ReverseDriver)
+    @override
     def type(self) -> str:
         """驱动名称: `fastapi`"""
         return "fastapi"
 
     @property
-    @overrides(ReverseDriver)
+    @override
     def server_app(self) -> FastAPI:
         """`FastAPI APP` 对象"""
         return self._server_app
 
     @property
-    @overrides(ReverseDriver)
+    @override
     def asgi(self) -> FastAPI:
         """`FastAPI APP` 对象"""
         return self._server_app
 
     @property
-    @overrides(ReverseDriver)
+    @override
     def logger(self) -> logging.Logger:
         """fastapi 使用的 logger"""
         return logging.getLogger("fastapi")
 
-    @overrides(ReverseDriver)
+    @override
     def setup_http_server(self, setup: HTTPServerSetup):
         async def _handle(request: Request) -> Response:
             return await self._handle_http(request, setup)
@@ -141,7 +142,7 @@ class Driver(ReverseDriver):
             include_in_schema=self.fastapi_config.fastapi_include_adapter_schema,
         )
 
-    @overrides(ReverseDriver)
+    @override
     def setup_websocket_server(self, setup: WebSocketServerSetup) -> None:
         async def _handle(websocket: WebSocket) -> None:
             await self._handle_ws(websocket, setup)
@@ -152,11 +153,11 @@ class Driver(ReverseDriver):
             name=setup.name,
         )
 
-    @overrides(ReverseDriver)
+    @override
     def on_startup(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
         return self._lifespan.on_startup(func)
 
-    @overrides(ReverseDriver)
+    @override
     def on_shutdown(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
         return self._lifespan.on_shutdown(func)
 
@@ -168,7 +169,7 @@ class Driver(ReverseDriver):
         finally:
             await self._lifespan.shutdown()
 
-    @overrides(ReverseDriver)
+    @override
     def run(
         self,
         host: Optional[str] = None,
@@ -267,30 +268,30 @@ class Driver(ReverseDriver):
 class FastAPIWebSocket(BaseWebSocket):
     """FastAPI WebSocket Wrapper"""
 
-    @overrides(BaseWebSocket)
+    @override
     def __init__(self, *, request: BaseRequest, websocket: WebSocket):
         super().__init__(request=request)
         self.websocket = websocket
 
     @property
-    @overrides(BaseWebSocket)
+    @override
     def closed(self) -> bool:
         return (
             self.websocket.client_state == WebSocketState.DISCONNECTED
             or self.websocket.application_state == WebSocketState.DISCONNECTED
         )
 
-    @overrides(BaseWebSocket)
+    @override
     async def accept(self) -> None:
         await self.websocket.accept()
 
-    @overrides(BaseWebSocket)
+    @override
     async def close(
         self, code: int = status.WS_1000_NORMAL_CLOSURE, reason: str = ""
     ) -> None:
         await self.websocket.close(code, reason)
 
-    @overrides(BaseWebSocket)
+    @override
     async def receive(self) -> Union[str, bytes]:
         # assert self.websocket.application_state == WebSocketState.CONNECTED
         msg = await self.websocket.receive()
@@ -298,21 +299,21 @@ class FastAPIWebSocket(BaseWebSocket):
             raise WebSocketClosed(msg["code"])
         return msg["text"] if "text" in msg else msg["bytes"]
 
-    @overrides(BaseWebSocket)
+    @override
     @catch_closed
     async def receive_text(self) -> str:
         return await self.websocket.receive_text()
 
-    @overrides(BaseWebSocket)
+    @override
     @catch_closed
     async def receive_bytes(self) -> bytes:
         return await self.websocket.receive_bytes()
 
-    @overrides(BaseWebSocket)
+    @override
     async def send_text(self, data: str) -> None:
         await self.websocket.send({"type": "websocket.send", "text": data})
 
-    @overrides(BaseWebSocket)
+    @override
     async def send_bytes(self, data: bytes) -> None:
         await self.websocket.send({"type": "websocket.send", "bytes": data})
 

nonebot/drivers/httpx.py

@@ -14,10 +14,11 @@ FrontMatter:
     sidebar_position: 3
     description: nonebot.drivers.httpx 模块
 """
+
+from typing_extensions import override
 from typing import Type, AsyncGenerator
 from contextlib import asynccontextmanager
 
-from nonebot.typing import overrides
 from nonebot.drivers.none import Driver as NoneDriver
 from nonebot.drivers import (
     Request,
@@ -33,7 +34,8 @@ try:
     import httpx
 except ModuleNotFoundError as e:  # pragma: no cover
     raise ImportError(
-        "Please install httpx by using `pip install nonebot2[httpx]`"
+        "Please install httpx first to use this driver. "
+        "Install with pip: `pip install nonebot2[httpx]`"
     ) from e
 
 
@@ -41,11 +43,11 @@ class Mixin(ForwardMixin):
     """HTTPX Mixin"""
 
     @property
-    @overrides(ForwardMixin)
+    @override
     def type(self) -> str:
         return "httpx"
 
-    @overrides(ForwardMixin)
+    @override
     async def request(self, setup: Request) -> Response:
         async with httpx.AsyncClient(
             cookies=setup.cookies.jar,
@@ -70,7 +72,7 @@ class Mixin(ForwardMixin):
                 request=setup,
             )
 
-    @overrides(ForwardMixin)
+    @override
     @asynccontextmanager
     async def websocket(self, setup: Request) -> AsyncGenerator[WebSocket, None]:
         async with super(Mixin, self).websocket(setup) as ws:

nonebot/drivers/none.py

@@ -9,14 +9,13 @@ FrontMatter:
     description: nonebot.drivers.none 模块
 """
 
-
 import signal
 import asyncio
 import threading
+from typing_extensions import override
 
 from nonebot.log import logger
 from nonebot.consts import WINDOWS
-from nonebot.typing import overrides
 from nonebot.config import Env, Config
 from nonebot.drivers import Driver as BaseDriver
 
@@ -42,32 +41,28 @@ class Driver(BaseDriver):
         self.force_exit: bool = False
 
     @property
-    @overrides(BaseDriver)
+    @override
     def type(self) -> str:
         """驱动名称: `none`"""
         return "none"
 
     @property
-    @overrides(BaseDriver)
+    @override
     def logger(self):
         """none driver 使用的 logger"""
         return logger
 
-    @overrides(BaseDriver)
+    @override
     def on_startup(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
-        """
-        注册一个启动时执行的函数
-        """
+        """注册一个启动时执行的函数"""
         return self._lifespan.on_startup(func)
 
-    @overrides(BaseDriver)
+    @override
     def on_shutdown(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
-        """
-        注册一个停止时执行的函数
-        """
+        """注册一个停止时执行的函数"""
         return self._lifespan.on_shutdown(func)
 
-    @overrides(BaseDriver)
+    @override
     def run(self, *args, **kwargs):
         """启动 none driver"""
         super().run(*args, **kwargs)
@@ -146,7 +141,15 @@ class Driver(BaseDriver):
                 signal.signal(sig, self._handle_exit)
 
     def _handle_exit(self, sig, frame):
-        if self.should_exit.is_set():
-            self.force_exit = True
-        else:
+        self.exit(force=self.should_exit.is_set())
+
+    def exit(self, force: bool = False):
+        """退出 none driver
+
+        参数:
+            force: 强制退出
+        """
+        if not self.should_exit.is_set():
             self.should_exit.set()
+        if force:
+            self.force_exit = True

nonebot/drivers/quart.py

@@ -17,12 +17,23 @@ FrontMatter:
 
 import asyncio
 from functools import wraps
-from typing import Any, Dict, List, Tuple, Union, TypeVar, Callable, Optional, Coroutine
+from typing_extensions import override
+from typing import (
+    Any,
+    Dict,
+    List,
+    Tuple,
+    Union,
+    TypeVar,
+    Callable,
+    Optional,
+    Coroutine,
+    cast,
+)
 
 from pydantic import BaseSettings
 
 from nonebot.config import Env
-from nonebot.typing import overrides
 from nonebot.exception import WebSocketClosed
 from nonebot.internal.driver import FileTypes
 from nonebot.config import Config as NoneBotConfig
@@ -33,13 +44,15 @@ from nonebot.drivers import ReverseDriver, HTTPServerSetup, WebSocketServerSetup
 try:
     import uvicorn
     from quart import request as _request
-    from quart import websocket as _websocket
+    from quart.ctx import WebsocketContext
+    from quart.globals import websocket_ctx
     from quart import Quart, Request, Response
     from quart.datastructures import FileStorage
     from quart import Websocket as QuartWebSocket
 except ModuleNotFoundError as e:  # pragma: no cover
     raise ImportError(
-        "Please install Quart by using `pip install nonebot2[quart]`"
+        "Please install Quart first to use this driver. "
+        "Install with pip: `pip install nonebot2[quart]`"
     ) from e
 
 _AsyncCallable = TypeVar("_AsyncCallable", bound=Callable[..., Coroutine])
@@ -89,30 +102,30 @@ class Driver(ReverseDriver):
         )
 
     @property
-    @overrides(ReverseDriver)
+    @override
     def type(self) -> str:
         """驱动名称: `quart`"""
         return "quart"
 
     @property
-    @overrides(ReverseDriver)
+    @override
     def server_app(self) -> Quart:
         """`Quart` 对象"""
         return self._server_app
 
     @property
-    @overrides(ReverseDriver)
+    @override
     def asgi(self):
         """`Quart` 对象"""
         return self._server_app
 
     @property
-    @overrides(ReverseDriver)
+    @override
     def logger(self):
         """Quart 使用的 logger"""
         return self._server_app.logger
 
-    @overrides(ReverseDriver)
+    @override
     def setup_http_server(self, setup: HTTPServerSetup):
         async def _handle() -> Response:
             return await self._handle_http(setup)
@@ -124,7 +137,7 @@ class Driver(ReverseDriver):
             view_func=_handle,
         )
 
-    @overrides(ReverseDriver)
+    @override
     def setup_websocket_server(self, setup: WebSocketServerSetup) -> None:
         async def _handle() -> None:
             return await self._handle_ws(setup)
@@ -135,17 +148,17 @@ class Driver(ReverseDriver):
             view_func=_handle,
         )
 
-    @overrides(ReverseDriver)
+    @override
     def on_startup(self, func: _AsyncCallable) -> _AsyncCallable:
         """参考文档: [`Startup and Shutdown`](https://pgjones.gitlab.io/quart/how_to_guides/startup_shutdown.html)"""
         return self.server_app.before_serving(func)  # type: ignore
 
-    @overrides(ReverseDriver)
+    @override
     def on_shutdown(self, func: _AsyncCallable) -> _AsyncCallable:
         """参考文档: [`Startup and Shutdown`](https://pgjones.gitlab.io/quart/how_to_guides/startup_shutdown.html)"""
         return self.server_app.after_serving(func)  # type: ignore
 
-    @overrides(ReverseDriver)
+    @override
     def run(
         self,
         host: Optional[str] = None,
@@ -188,9 +201,7 @@ class Driver(ReverseDriver):
     async def _handle_http(self, setup: HTTPServerSetup) -> Response:
         request: Request = _request
 
-        json = None
-        if request.is_json:
-            json = await request.get_json()
+        json = await request.get_json() if request.is_json else None
 
         data = await request.form
         files_dict = await request.files
@@ -223,7 +234,8 @@ class Driver(ReverseDriver):
         )
 
     async def _handle_ws(self, setup: WebSocketServerSetup) -> None:
-        websocket: QuartWebSocket = _websocket
+        ctx = cast(WebsocketContext, websocket_ctx.copy())
+        websocket = websocket_ctx.websocket
 
         http_request = BaseRequest(
             websocket.method,
@@ -233,7 +245,7 @@ class Driver(ReverseDriver):
             version=websocket.http_version,
         )
 
-        ws = WebSocket(request=http_request, websocket=websocket)
+        ws = WebSocket(request=http_request, websocket_ctx=ctx)
 
         await setup.handle_func(ws)
 
@@ -241,30 +253,34 @@ class Driver(ReverseDriver):
 class WebSocket(BaseWebSocket):
     """Quart WebSocket Wrapper"""
 
-    def __init__(self, *, request: BaseRequest, websocket: QuartWebSocket):
+    def __init__(self, *, request: BaseRequest, websocket_ctx: WebsocketContext):
         super().__init__(request=request)
-        self.websocket = websocket
+        self.websocket_ctx = websocket_ctx
 
     @property
-    @overrides(BaseWebSocket)
+    def websocket(self) -> QuartWebSocket:
+        return self.websocket_ctx.websocket
+
+    @property
+    @override
     def closed(self):
         # FIXME
         return True
 
-    @overrides(BaseWebSocket)
+    @override
     async def accept(self):
         await self.websocket.accept()
 
-    @overrides(BaseWebSocket)
+    @override
     async def close(self, code: int = 1000, reason: str = ""):
         await self.websocket.close(code, reason)
 
-    @overrides(BaseWebSocket)
+    @override
     @catch_closed
     async def receive(self) -> Union[str, bytes]:
         return await self.websocket.receive()
 
-    @overrides(BaseWebSocket)
+    @override
     @catch_closed
     async def receive_text(self) -> str:
         msg = await self.websocket.receive()
@@ -272,7 +288,7 @@ class WebSocket(BaseWebSocket):
             raise TypeError("WebSocket received unexpected frame type: bytes")
         return msg
 
-    @overrides(BaseWebSocket)
+    @override
     @catch_closed
     async def receive_bytes(self) -> bytes:
         msg = await self.websocket.receive()
@@ -280,11 +296,11 @@ class WebSocket(BaseWebSocket):
             raise TypeError("WebSocket received unexpected frame type: str")
         return msg
 
-    @overrides(BaseWebSocket)
+    @override
     async def send_text(self, data: str):
         await self.websocket.send(data)
 
-    @overrides(BaseWebSocket)
+    @override
     async def send_bytes(self, data: bytes):
         await self.websocket.send(data)
 

nonebot/drivers/websockets.py

@@ -14,12 +14,13 @@ FrontMatter:
     sidebar_position: 4
     description: nonebot.drivers.websockets 模块
 """
+
 import logging
 from functools import wraps
 from contextlib import asynccontextmanager
-from typing import Type, Union, AsyncGenerator
+from typing_extensions import ParamSpec, override
+from typing import Type, Union, TypeVar, Callable, Awaitable, AsyncGenerator
 
-from nonebot.typing import overrides
 from nonebot.log import LoguruHandler
 from nonebot.drivers import Request, Response
 from nonebot.exception import WebSocketClosed
@@ -32,16 +33,20 @@ try:
     from websockets.legacy.client import Connect, WebSocketClientProtocol
 except ModuleNotFoundError as e:  # pragma: no cover
     raise ImportError(
-        "Please install websockets by using `pip install nonebot2[websockets]`"
+        "Please install websockets first to use this driver. "
+        "Install with pip: `pip install nonebot2[websockets]`"
     ) from e
 
+T = TypeVar("T")
+P = ParamSpec("P")
+
 logger = logging.Logger("websockets.client", "INFO")
 logger.addHandler(LoguruHandler())
 
 
-def catch_closed(func):
+def catch_closed(func: Callable[P, Awaitable[T]]) -> Callable[P, Awaitable[T]]:
     @wraps(func)
-    async def decorator(*args, **kwargs):
+    async def decorator(*args: P.args, **kwargs: P.kwargs) -> T:
         try:
             return await func(*args, **kwargs)
         except ConnectionClosed as e:
@@ -57,15 +62,15 @@ class Mixin(ForwardMixin):
     """Websockets Mixin"""
 
     @property
-    @overrides(ForwardMixin)
+    @override
     def type(self) -> str:
         return "websockets"
 
-    @overrides(ForwardMixin)
+    @override
     async def request(self, setup: Request) -> Response:
         return await super(Mixin, self).request(setup)
 
-    @overrides(ForwardMixin)
+    @override
     @asynccontextmanager
     async def websocket(self, setup: Request) -> AsyncGenerator["WebSocket", None]:
         connection = Connect(
@@ -80,30 +85,30 @@ class Mixin(ForwardMixin):
 class WebSocket(BaseWebSocket):
     """Websockets WebSocket Wrapper"""
 
-    @overrides(BaseWebSocket)
+    @override
     def __init__(self, *, request: Request, websocket: WebSocketClientProtocol):
         super().__init__(request=request)
         self.websocket = websocket
 
     @property
-    @overrides(BaseWebSocket)
+    @override
     def closed(self) -> bool:
         return self.websocket.closed
 
-    @overrides(BaseWebSocket)
+    @override
     async def accept(self):
         raise NotImplementedError
 
-    @overrides(BaseWebSocket)
+    @override
     async def close(self, code: int = 1000, reason: str = ""):
         await self.websocket.close(code, reason)
 
-    @overrides(BaseWebSocket)
+    @override
     @catch_closed
     async def receive(self) -> Union[str, bytes]:
         return await self.websocket.recv()
 
-    @overrides(BaseWebSocket)
+    @override
     @catch_closed
     async def receive_text(self) -> str:
         msg = await self.websocket.recv()
@@ -111,7 +116,7 @@ class WebSocket(BaseWebSocket):
             raise TypeError("WebSocket received unexpected frame type: bytes")
         return msg
 
-    @overrides(BaseWebSocket)
+    @override
     @catch_closed
     async def receive_bytes(self) -> bytes:
         msg = await self.websocket.recv()
@@ -119,11 +124,11 @@ class WebSocket(BaseWebSocket):
             raise TypeError("WebSocket received unexpected frame type: str")
         return msg
 
-    @overrides(BaseWebSocket)
+    @override
     async def send_text(self, data: str) -> None:
         await self.websocket.send(data)
 
-    @overrides(BaseWebSocket)
+    @override
     async def send_bytes(self, data: bytes) -> None:
         await self.websocket.send(data)
 

nonebot/exception.py

@@ -43,9 +43,9 @@ class NoneBotException(Exception):
 
 # Rule Exception
 class ParserExit(NoneBotException):
-    """{ref}`nonebot.rule.shell_command` 处理消息失败时返回的异常"""
+    """{ref}`nonebot.rule.shell_command` 处理消息失败时返回的异常。"""
 
-    def __init__(self, status: int = 0, message: Optional[str] = None):
+    def __init__(self, status: int = 0, message: Optional[str] = None) -> None:
         self.status = status
         self.message = message
 
@@ -69,7 +69,7 @@ class IgnoredException(ProcessException):
         reason: 忽略事件的原因
     """
 
-    def __init__(self, reason: Any):
+    def __init__(self, reason: Any) -> None:
         self.reason: Any = reason
 
     def __repr__(self) -> str:
@@ -96,7 +96,7 @@ class SkippedException(ProcessException):
 class TypeMisMatch(SkippedException):
     """当前 `Handler` 的参数类型不匹配。"""
 
-    def __init__(self, param: ModelField, value: Any):
+    def __init__(self, param: ModelField, value: Any) -> None:
         self.param: ModelField = param
         self.value: Any = value
 
@@ -108,7 +108,8 @@ class TypeMisMatch(SkippedException):
 
 
 class MockApiException(ProcessException):
-    """指示 NoneBot 阻止本次 API 调用或修改本次调用返回值，并返回自定义内容。可由 api hook 抛出。
+    """指示 NoneBot 阻止本次 API 调用或修改本次调用返回值，并返回自定义内容。
+    可由 api hook 抛出。
 
     参数:
         result: 返回的内容
@@ -144,7 +145,8 @@ class MatcherException(NoneBotException):
 
 
 class PausedException(MatcherException):
-    """指示 NoneBot 结束当前 `Handler` 并等待下一条消息后继续下一个 `Handler`。可用于用户输入新信息。
+    """指示 NoneBot 结束当前 `Handler` 并等待下一条消息后继续下一个 `Handler`。
+    可用于用户输入新信息。
 
     可以在 `Handler` 中通过 {ref}`nonebot.matcher.Matcher.pause` 抛出。
 
@@ -158,7 +160,8 @@ class PausedException(MatcherException):
 
 
 class RejectedException(MatcherException):
-    """指示 NoneBot 结束当前 `Handler` 并等待下一条消息后重新运行当前 `Handler`。可用于用户重新输入。
+    """指示 NoneBot 结束当前 `Handler` 并等待下一条消息后重新运行当前 `Handler`。
+    可用于用户重新输入。
 
     可以在 `Handler` 中通过 {ref}`nonebot.matcher.Matcher.reject` 抛出。
 
@@ -187,7 +190,7 @@ class FinishedException(MatcherException):
 
 # Adapter Exceptions
 class AdapterException(NoneBotException):
-    """代表 `Adapter` 抛出的异常，所有的 `Adapter` 都要在内部继承自这个 `Exception`
+    """代表 `Adapter` 抛出的异常，所有的 `Adapter` 都要在内部继承自这个 `Exception`。
 
     参数:
         adapter_name: 标识 adapter
@@ -210,7 +213,9 @@ class ApiNotAvailable(AdapterException):
 
 
 class NetworkError(AdapterException):
-    """在网络出现问题时抛出，如: API 请求地址不正确, API 请求无返回或返回状态非正常等。"""
+    """在网络出现问题时抛出，
+    如: API 请求地址不正确, API 请求无返回或返回状态非正常等。
+    """
 
 
 class ActionFailed(AdapterException):
@@ -219,13 +224,13 @@ class ActionFailed(AdapterException):
 
 # Driver Exceptions
 class DriverException(NoneBotException):
-    """`Driver` 抛出的异常基类"""
+    """`Driver` 抛出的异常基类。"""
 
 
 class WebSocketClosed(DriverException):
-    """WebSocket 连接已关闭"""
+    """WebSocket 连接已关闭。"""
 
-    def __init__(self, code: int, reason: Optional[str] = None):
+    def __init__(self, code: int, reason: Optional[str] = None) -> None:
         self.code = code
         self.reason = reason
 

nonebot/internal/adapter/event.py

@@ -44,10 +44,11 @@ class Event(abc.ABC, BaseModel):
     def get_log_string(self) -> str:
         """获取事件日志信息的方法。
 
-        通常你不需要修改这个方法，只有当希望 NoneBot 隐藏该事件日志时，可以抛出 `NoLogException` 异常。
+        通常你不需要修改这个方法，只有当希望 NoneBot 隐藏该事件日志时，
+        可以抛出 `NoLogException` 异常。
 
         异常:
-            NoLogException:
+            NoLogException: 希望 NoneBot 隐藏该事件日志
         """
         return f"[{self.get_event_name()}]: {self.get_event_description()}"
 
@@ -58,7 +59,9 @@ class Event(abc.ABC, BaseModel):
 
     @abc.abstractmethod
     def get_session_id(self) -> str:
-        """获取会话 id 的方法，用于判断当前事件属于哪一个会话，通常是用户 id、群组 id 组合。"""
+        """获取会话 id 的方法，用于判断当前事件属于哪一个会话，
+        通常是用户 id、群组 id 组合。
+        """
         raise NotImplementedError
 
     @abc.abstractmethod

nonebot/internal/adapter/message.py

@@ -1,5 +1,6 @@
 import abc
 from copy import deepcopy
+from typing_extensions import Self
 from dataclasses import field, asdict, dataclass
 from typing import (
     Any,
@@ -12,6 +13,7 @@ from typing import (
     TypeVar,
     Iterable,
     Optional,
+    SupportsIndex,
     overload,
 )
 
@@ -19,7 +21,6 @@ from pydantic import parse_obj_as
 
 from .template import MessageTemplate
 
-T = TypeVar("T")
 TMS = TypeVar("TMS", bound="MessageSegment")
 TM = TypeVar("TM", bound="Message")
 
@@ -47,7 +48,7 @@ class MessageSegment(abc.ABC, Generic[TM]):
     def __len__(self) -> int:
         return len(str(self))
 
-    def __ne__(self: T, other: T) -> bool:
+    def __ne__(self, other: Self) -> bool:
         return not self == other
 
     def __add__(self: TMS, other: Union[str, TMS, Iterable[TMS]]) -> TM:
@@ -61,7 +62,7 @@ class MessageSegment(abc.ABC, Generic[TM]):
         yield cls._validate
 
     @classmethod
-    def _validate(cls, value):
+    def _validate(cls, value) -> Self:
         if isinstance(value, cls):
             return value
         if not isinstance(value, dict):
@@ -84,7 +85,10 @@ class MessageSegment(abc.ABC, Generic[TM]):
     def items(self):
         return asdict(self).items()
 
-    def copy(self: T) -> T:
+    def join(self: TMS, iterable: Iterable[Union[TMS, TM]]) -> TM:
+        return self.get_message_class()(self).join(iterable)
+
+    def copy(self) -> Self:
         return deepcopy(self)
 
     @abc.abstractmethod
@@ -94,7 +98,7 @@ class MessageSegment(abc.ABC, Generic[TM]):
 
 
 class Message(List[TMS], abc.ABC):
-    """消息数组
+    """消息序列
 
     参数:
         message: 消息内容
@@ -117,12 +121,12 @@ class Message(List[TMS], abc.ABC):
             self.extend(self._construct(message))  # pragma: no cover
 
     @classmethod
-    def template(cls: Type[TM], format_string: Union[str, TM]) -> MessageTemplate[TM]:
+    def template(cls, format_string: Union[str, TM]) -> MessageTemplate[Self]:
         """创建消息模板。
 
-        用法和 `str.format` 大致相同, 但是可以输出消息对象, 并且支持以 `Message` 对象作为消息模板
-
-        并且提供了拓展的格式化控制符, 可以用适用于该消息类型的 `MessageSegment` 的工厂方法创建消息
+        用法和 `str.format` 大致相同，支持以 `Message` 对象作为消息模板并输出消息对象。
+        并且提供了拓展的格式化控制符，
+        可以通过该消息类型的 `MessageSegment` 工厂方法创建消息。
 
         参数:
             format_string: 格式化模板
@@ -146,7 +150,7 @@ class Message(List[TMS], abc.ABC):
         yield cls._validate
 
     @classmethod
-    def _validate(cls, value):
+    def _validate(cls, value) -> Self:
         if isinstance(value, cls):
             return value
         elif isinstance(value, Message):
@@ -169,16 +173,16 @@ class Message(List[TMS], abc.ABC):
         """构造消息数组"""
         raise NotImplementedError
 
-    def __add__(self: TM, other: Union[str, TMS, Iterable[TMS]]) -> TM:
+    def __add__(self, other: Union[str, TMS, Iterable[TMS]]) -> Self:
         result = self.copy()
         result += other
         return result
 
-    def __radd__(self: TM, other: Union[str, TMS, Iterable[TMS]]) -> TM:
+    def __radd__(self, other: Union[str, TMS, Iterable[TMS]]) -> Self:
         result = self.__class__(other)
         return result + self
 
-    def __iadd__(self: TM, other: Union[str, TMS, Iterable[TMS]]) -> TM:
+    def __iadd__(self, other: Union[str, TMS, Iterable[TMS]]) -> Self:
         if isinstance(other, str):
             self.extend(self._construct(other))
         elif isinstance(other, MessageSegment):
@@ -190,57 +194,62 @@ class Message(List[TMS], abc.ABC):
         return self
 
     @overload
-    def __getitem__(self: TM, __args: str) -> TM:
-        """
+    def __getitem__(self, args: str) -> Self:
+        """获取仅包含指定消息段类型的消息
+
         参数:
-            __args: 消息段类型
+            args: 消息段类型
 
         返回:
-            所有类型为 `__args` 的消息段
+            所有类型为 `args` 的消息段
         """
 
     @overload
-    def __getitem__(self, __args: Tuple[str, int]) -> TMS:
-        """
+    def __getitem__(self, args: Tuple[str, int]) -> TMS:
+        """索引指定类型的消息段
+
         参数:
-            __args: 消息段类型和索引
+            args: 消息段类型和索引
 
         返回:
-            类型为 `__args[0]` 的消息段第 `__args[1]` 个
+            类型为 `args[0]` 的消息段第 `args[1]` 个
         """
 
     @overload
-    def __getitem__(self: TM, __args: Tuple[str, slice]) -> TM:
-        """
+    def __getitem__(self, args: Tuple[str, slice]) -> Self:
+        """切片指定类型的消息段
+
         参数:
-            __args: 消息段类型和切片
+            args: 消息段类型和切片
 
         返回:
-            类型为 `__args[0]` 的消息段切片 `__args[1]`
+            类型为 `args[0]` 的消息段切片 `args[1]`
         """
 
     @overload
-    def __getitem__(self, __args: int) -> TMS:
-        """
+    def __getitem__(self, args: int) -> TMS:
+        """索引消息段
+
         参数:
-            __args: 索引
+            args: 索引
 
         返回:
-            第 `__args` 个消息段
+            第 `args` 个消息段
         """
 
     @overload
-    def __getitem__(self: TM, __args: slice) -> TM:
-        """
+    def __getitem__(self, args: slice) -> Self:
+        """切片消息段
+
         参数:
-            __args: 切片
+            args: 切片
 
         返回:
-            消息切片 `__args`
+            消息切片 `args`
         """
 
     def __getitem__(
-        self: TM,
+        self,
         args: Union[
             str,
             Tuple[str, int],
@@ -248,7 +257,7 @@ class Message(List[TMS], abc.ABC):
             int,
             slice,
         ],
-    ) -> Union[TMS, TM]:
+    ) -> Union[TMS, Self]:
         arg1, arg2 = args if isinstance(args, tuple) else (args, None)
         if isinstance(arg1, int) and arg2 is None:
             return super().__getitem__(arg1)
@@ -263,15 +272,52 @@ class Message(List[TMS], abc.ABC):
         else:
             raise ValueError("Incorrect arguments to slice")  # pragma: no cover
 
-    def index(self, value: Union[TMS, str], *args) -> int:
+    def __contains__(self, value: Union[TMS, str]) -> bool:
+        """检查消息段是否存在
+
+        参数:
+            value: 消息段或消息段类型
+        返回:
+            消息内是否存在给定消息段或给定类型的消息段
+        """
+        if isinstance(value, str):
+            return bool(next((seg for seg in self if seg.type == value), None))
+        return super().__contains__(value)
+
+    def has(self, value: Union[TMS, str]) -> bool:
+        """与 {ref}``__contains__` <nonebot.adapters.Message.__contains__>` 相同"""
+        return value in self
+
+    def index(self, value: Union[TMS, str], *args: SupportsIndex) -> int:
+        """索引消息段
+
+        参数:
+            value: 消息段或者消息段类型
+            arg: start 与 end
+
+        返回:
+            索引 index
+
+        异常:
+            ValueError: 消息段不存在
+        """
         if isinstance(value, str):
             first_segment = next((seg for seg in self if seg.type == value), None)
             if first_segment is None:
-                raise ValueError(f"Segment with type {value} is not in message")
+                raise ValueError(f"Segment with type {value!r} is not in message")
             return super().index(first_segment, *args)
         return super().index(value, *args)
 
-    def get(self: TM, type_: str, count: Optional[int] = None) -> TM:
+    def get(self, type_: str, count: Optional[int] = None) -> Self:
+        """获取指定类型的消息段
+
+        参数:
+            type_: 消息段类型
+            count: 获取个数
+
+        返回:
+            构建的新消息
+        """
         if count is None:
             return self[type_]
 
@@ -286,9 +332,30 @@ class Message(List[TMS], abc.ABC):
         return filtered
 
     def count(self, value: Union[TMS, str]) -> int:
+        """计算指定消息段的个数
+
+        参数:
+            value: 消息段或消息段类型
+
+        返回:
+            个数
+        """
         return len(self[value]) if isinstance(value, str) else super().count(value)
 
-    def append(self: TM, obj: Union[str, TMS]) -> TM:
+    def only(self, value: Union[TMS, str]) -> bool:
+        """检查消息中是否仅包含指定消息段
+
+        参数:
+            value: 指定消息段或消息段类型
+
+        返回:
+            是否仅包含指定消息段
+        """
+        if isinstance(value, str):
+            return all(seg.type == value for seg in self)
+        return all(seg == value for seg in self)
+
+    def append(self, obj: Union[str, TMS]) -> Self:
         """添加一个消息段到消息数组末尾。
 
         参数:
@@ -302,7 +369,7 @@ class Message(List[TMS], abc.ABC):
             raise ValueError(f"Unexpected type: {type(obj)} {obj}")  # pragma: no cover
         return self
 
-    def extend(self: TM, obj: Union[TM, Iterable[TMS]]) -> TM:
+    def extend(self, obj: Union[Self, Iterable[TMS]]) -> Self:
         """拼接一个消息数组或多个消息段到消息数组末尾。
 
         参数:
@@ -312,18 +379,52 @@ class Message(List[TMS], abc.ABC):
             self.append(segment)
         return self
 
-    def copy(self: TM) -> TM:
+    def join(self, iterable: Iterable[Union[TMS, Self]]) -> Self:
+        """将多个消息连接并将自身作为分割
+
+        参数:
+            iterable: 要连接的消息
+
+        返回:
+            连接后的消息
+        """
+        ret = self.__class__()
+        for index, msg in enumerate(iterable):
+            if index != 0:
+                ret.extend(self)
+            if isinstance(msg, MessageSegment):
+                ret.append(msg.copy())
+            else:
+                ret.extend(msg.copy())
+        return ret
+
+    def copy(self) -> Self:
+        """深拷贝消息"""
         return deepcopy(self)
 
+    def include(self, *types: str) -> Self:
+        """过滤消息
+
+        参数:
+            types: 包含的消息段类型
+
+        返回:
+            新构造的消息
+        """
+        return self.__class__(seg for seg in self if seg.type in types)
+
+    def exclude(self, *types: str) -> Self:
+        """过滤消息
+
+        参数:
+            types: 不包含的消息段类型
+
+        返回:
+            新构造的消息
+        """
+        return self.__class__(seg for seg in self if seg.type not in types)
+
     def extract_plain_text(self) -> str:
         """提取消息内纯文本消息"""
 
         return "".join(str(seg) for seg in self if seg.is_text())
-
-
-__autodoc__ = {
-    "MessageSegment.__str__": True,
-    "MessageSegment.__add__": True,
-    "Message.__getitem__": True,
-    "Message._construct": True,
-}

nonebot/internal/adapter/template.py

@@ -1,5 +1,6 @@
 import functools
 from string import Formatter
+from typing_extensions import TypeAlias
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -25,7 +26,7 @@ if TYPE_CHECKING:
 TM = TypeVar("TM", bound="Message")
 TF = TypeVar("TF", str, "Message")
 
-FormatSpecFunc = Callable[[Any], str]
+FormatSpecFunc: TypeAlias = Callable[[Any], str]
 FormatSpecFunc_T = TypeVar("FormatSpecFunc_T", bound=FormatSpecFunc)
 
 

nonebot/internal/driver/driver.py

@@ -89,9 +89,7 @@ class Driver(abc.ABC):
 
     @abc.abstractmethod
     def run(self, *args, **kwargs):
-        """
-        启动驱动框架
-        """
+        """启动驱动框架"""
         logger.opt(colors=True).debug(
             f"<g>Loaded adapters: {escape_tag(', '.join(self._adapters))}</g>"
         )
@@ -152,8 +150,10 @@ class Driver(abc.ABC):
                         await asyncio.gather(*coros)
                     except Exception as e:
                         logger.opt(colors=True, exception=e).error(
-                            "<r><bg #f8bbd0>Error when running WebSocketConnection hook. "
-                            "Running cancelled!</bg #f8bbd0></r>"
+                            "<r><bg #f8bbd0>"
+                            "Error when running WebSocketConnection hook. "
+                            "Running cancelled!"
+                            "</bg #f8bbd0></r>"
                         )
 
         asyncio.create_task(_run_hook(bot))
@@ -177,8 +177,10 @@ class Driver(abc.ABC):
                         await asyncio.gather(*coros)
                     except Exception as e:
                         logger.opt(colors=True, exception=e).error(
-                            "<r><bg #f8bbd0>Error when running WebSocketDisConnection hook. "
-                            "Running cancelled!</bg #f8bbd0></r>"
+                            "<r><bg #f8bbd0>"
+                            "Error when running WebSocketDisConnection hook. "
+                            "Running cancelled!"
+                            "</bg #f8bbd0></r>"
                         )
 
         asyncio.create_task(_run_hook(bot))
@@ -241,7 +243,7 @@ def combine_driver(driver: Type[Driver], *mixins: Type[ForwardMixin]) -> Type[Dr
     # check first
     assert issubclass(driver, Driver), "`driver` must be subclass of Driver"
     assert all(
-        map(lambda m: issubclass(m, ForwardMixin), mixins)
+        issubclass(m, ForwardMixin) for m in mixins
     ), "`mixins` must be subclass of ForwardMixin"
 
     if not mixins:
@@ -251,7 +253,9 @@ def combine_driver(driver: Type[Driver], *mixins: Type[ForwardMixin]) -> Type[Dr
         return (
             driver.type.__get__(self)
             + "+"
-            + "+".join(map(lambda x: x.type.__get__(self), mixins))
+            + "+".join(x.type.__get__(self) for x in mixins)
         )
 
-    return type("CombinedDriver", (*mixins, driver, ForwardDriver), {"type": property(type_)})  # type: ignore
+    return type(
+        "CombinedDriver", (*mixins, driver, ForwardDriver), {"type": property(type_)}
+    )  # type: ignore

nonebot/internal/driver/model.py

@@ -2,6 +2,7 @@ import abc
 import urllib.request
 from enum import Enum
 from dataclasses import dataclass
+from typing_extensions import TypeAlias
 from http.cookiejar import Cookie, CookieJar
 from typing import (
     IO,
@@ -21,28 +22,30 @@ from typing import (
 from yarl import URL as URL
 from multidict import CIMultiDict
 
-RawURL = Tuple[bytes, bytes, Optional[int], bytes]
+RawURL: TypeAlias = Tuple[bytes, bytes, Optional[int], bytes]
 
-SimpleQuery = Union[str, int, float]
-QueryVariable = Union[SimpleQuery, List[SimpleQuery]]
-QueryTypes = Union[
+SimpleQuery: TypeAlias = Union[str, int, float]
+QueryVariable: TypeAlias = Union[SimpleQuery, List[SimpleQuery]]
+QueryTypes: TypeAlias = Union[
     None, str, Mapping[str, QueryVariable], List[Tuple[str, QueryVariable]]
 ]
 
-HeaderTypes = Union[
+HeaderTypes: TypeAlias = Union[
     None,
     CIMultiDict[str],
     Dict[str, str],
     List[Tuple[str, str]],
 ]
 
-CookieTypes = Union[None, "Cookies", CookieJar, Dict[str, str], List[Tuple[str, str]]]
+CookieTypes: TypeAlias = Union[
+    None, "Cookies", CookieJar, Dict[str, str], List[Tuple[str, str]]
+]
 
-ContentTypes = Union[str, bytes, None]
-DataTypes = Union[dict, None]
-FileContent = Union[IO[bytes], bytes]
-FileType = Tuple[Optional[str], FileContent, Optional[str]]
-FileTypes = Union[
+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))
@@ -50,7 +53,7 @@ FileTypes = Union[
     # (filename, file (or bytes), content_type)
     FileType,
 ]
-FilesTypes = Union[Dict[str, FileTypes], List[Tuple[str, FileTypes]], None]
+FilesTypes: TypeAlias = Union[Dict[str, FileTypes], List[Tuple[str, FileTypes]], None]
 
 
 class HTTPVersion(Enum):
@@ -160,7 +163,6 @@ class Response:
 
 class WebSocket(abc.ABC):
     def __init__(self, *, request: Request):
-        # request
         self.request: Request = request
 
     def __repr__(self) -> str:
@@ -169,9 +171,7 @@ class WebSocket(abc.ABC):
     @property
     @abc.abstractmethod
     def closed(self) -> bool:
-        """
-        连接是否已经关闭
-        """
+        """连接是否已经关闭"""
         raise NotImplementedError
 
     @abc.abstractmethod

nonebot/internal/matcher/matcher.py

@@ -29,6 +29,13 @@ from nonebot.internal.adapter import (
     MessageSegment,
     MessageTemplate,
 )
+from nonebot.typing import (
+    T_State,
+    T_Handler,
+    T_TypeUpdater,
+    T_DependencyCache,
+    T_PermissionUpdater,
+)
 from nonebot.consts import (
     ARG_KEY,
     RECEIVE_KEY,
@@ -36,14 +43,6 @@ from nonebot.consts import (
     LAST_RECEIVE_KEY,
     REJECT_CACHE_TARGET,
 )
-from nonebot.typing import (
-    Any,
-    T_State,
-    T_Handler,
-    T_TypeUpdater,
-    T_DependencyCache,
-    T_PermissionUpdater,
-)
 from nonebot.exception import (
     PausedException,
     StopPropagation,
@@ -376,7 +375,7 @@ class Matcher(metaclass=MatcherMeta):
                 return
             await matcher.reject()
 
-        _parameterless = (Depends(_receive), *(parameterless or tuple()))
+        _parameterless = (Depends(_receive), *(parameterless or ()))
 
         def _decorator(func: T_Handler) -> T_Handler:
             if cls.handlers and cls.handlers[-1].call is func:
@@ -406,7 +405,8 @@ class Matcher(metaclass=MatcherMeta):
     ) -> Callable[[T_Handler], T_Handler]:
         """装饰一个函数来指示 NoneBot 获取一个参数 `key`
 
-        当要获取的 `key` 不存在时接收用户新的一条消息再运行该函数，如果 `key` 已存在则直接继续运行
+        当要获取的 `key` 不存在时接收用户新的一条消息再运行该函数，
+        如果 `key` 已存在则直接继续运行
 
         参数:
             key: 参数名
@@ -423,7 +423,7 @@ class Matcher(metaclass=MatcherMeta):
                 return
             await matcher.reject(prompt)
 
-        _parameterless = (Depends(_key_getter), *(parameterless or tuple()))
+        _parameterless = (Depends(_key_getter), *(parameterless or ()))
 
         def _decorator(func: T_Handler) -> T_Handler:
             if cls.handlers and cls.handlers[-1].call is func:
@@ -454,7 +454,8 @@ class Matcher(metaclass=MatcherMeta):
 
         参数:
             message: 消息内容
-            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
+            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，
+                请参考对应 adapter 的 bot 对象 api
         """
         bot = current_bot.get()
         event = current_event.get()
@@ -475,7 +476,8 @@ class Matcher(metaclass=MatcherMeta):
 
         参数:
             message: 消息内容
-            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
+            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，
+                请参考对应 adapter 的 bot 对象 api
         """
         if message is not None:
             await cls.send(message, **kwargs)
@@ -491,7 +493,8 @@ class Matcher(metaclass=MatcherMeta):
 
         参数:
             prompt: 消息内容
-            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
+            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，
+                请参考对应 adapter 的 bot 对象 api
         """
         if prompt is not None:
             await cls.send(prompt, **kwargs)
@@ -508,7 +511,8 @@ class Matcher(metaclass=MatcherMeta):
 
         参数:
             prompt: 消息内容
-            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
+            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，
+                请参考对应 adapter 的 bot 对象 api
         """
         if prompt is not None:
             await cls.send(prompt, **kwargs)
@@ -527,7 +531,8 @@ class Matcher(metaclass=MatcherMeta):
         参数:
             key: 参数名
             prompt: 消息内容
-            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
+            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，
+                请参考对应 adapter 的 bot 对象 api
         """
         matcher = current_matcher.get()
         matcher.set_target(ARG_KEY.format(key=key))
@@ -548,7 +553,8 @@ class Matcher(metaclass=MatcherMeta):
         参数:
             id: 消息 id
             prompt: 消息内容
-            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，请参考对应 adapter 的 bot 对象 api
+            kwargs: {ref}`nonebot.adapters.Bot.send` 的参数，
+                请参考对应 adapter 的 bot 对象 api
         """
         matcher = current_matcher.get()
         matcher.set_target(RECEIVE_KEY.format(id=id))

nonebot/internal/params.py

@@ -63,7 +63,10 @@ def Depends(
             finally:
                 ...
 
-        async def handler(param_name: Any = Depends(depend_func), gen: Any = Depends(depend_gen_func)):
+        async def handler(
+            param_name: Any = Depends(depend_func),
+            gen: Any = Depends(depend_gen_func),
+        ):
             ...
         ```
     """
@@ -71,7 +74,12 @@ def Depends(
 
 
 class DependParam(Param):
-    """子依赖参数"""
+    """子依赖注入参数。
+
+    本注入解析所有子依赖注入，然后将它们的返回值作为参数值传递给父依赖。
+
+    本注入应该具有最高优先级，因此应该在其他参数之前检查。
+    """
 
     def __repr__(self) -> str:
         return f"Depends({self.extra['dependent']})"
@@ -168,7 +176,12 @@ class DependParam(Param):
 
 
 class BotParam(Param):
-    """{ref}`nonebot.adapters.Bot` 参数"""
+    """{ref}`nonebot.adapters.Bot` 注入参数。
+
+    本注入解析所有类型为且仅为 {ref}`nonebot.adapters.Bot` 及其子类或 `None` 的参数。
+
+    为保证兼容性，本注入还会解析名为 `bot` 且没有类型注解的参数。
+    """
 
     def __repr__(self) -> str:
         return (
@@ -187,7 +200,7 @@ class BotParam(Param):
     ) -> Optional["BotParam"]:
         from nonebot.adapters import Bot
 
-        if param.default == param.empty:
+        # param type is Bot(s) or subclass(es) of Bot or None
         if generic_check_issubclass(param.annotation, Bot):
             checker: Optional[ModelField] = None
             if param.annotation is not Bot:
@@ -200,6 +213,7 @@ class BotParam(Param):
                     required=True,
                 )
             return cls(Required, checker=checker)
+        # legacy: param is named "bot" and has no type annotation
         elif param.annotation == param.empty and param.name == "bot":
             return cls(Required)
 
@@ -212,7 +226,12 @@ class BotParam(Param):
 
 
 class EventParam(Param):
-    """{ref}`nonebot.adapters.Event` 参数"""
+    """{ref}`nonebot.adapters.Event` 注入参数
+
+    本注入解析所有类型为且仅为 {ref}`nonebot.adapters.Event` 及其子类或 `None` 的参数。
+
+    为保证兼容性，本注入还会解析名为 `event` 且没有类型注解的参数。
+    """
 
     def __repr__(self) -> str:
         return (
@@ -231,7 +250,7 @@ class EventParam(Param):
     ) -> Optional["EventParam"]:
         from nonebot.adapters import Event
 
-        if param.default == param.empty:
+        # param type is Event(s) or subclass(es) of Event or None
         if generic_check_issubclass(param.annotation, Event):
             checker: Optional[ModelField] = None
             if param.annotation is not Event:
@@ -244,6 +263,7 @@ class EventParam(Param):
                     required=True,
                 )
             return cls(Required, checker=checker)
+        # legacy: param is named "event" and has no type annotation
         elif param.annotation == param.empty and param.name == "event":
             return cls(Required)
 
@@ -256,7 +276,12 @@ class EventParam(Param):
 
 
 class StateParam(Param):
-    """事件处理状态参数"""
+    """事件处理状态注入参数
+
+    本注入解析所有类型为 `T_State` 的参数。
+
+    为保证兼容性，本注入还会解析名为 `state` 且没有类型注解的参数。
+    """
 
     def __repr__(self) -> str:
         return "StateParam()"
@@ -265,9 +290,10 @@ class StateParam(Param):
     def _check_param(
         cls, param: inspect.Parameter, allow_types: Tuple[Type[Param], ...]
     ) -> Optional["StateParam"]:
-        if param.default == param.empty:
+        # param type is T_State
         if param.annotation is T_State:
             return cls(Required)
+        # legacy: param is named "state" and has no type annotation
         elif param.annotation == param.empty and param.name == "state":
             return cls(Required)
 
@@ -276,7 +302,12 @@ class StateParam(Param):
 
 
 class MatcherParam(Param):
-    """事件响应器实例参数"""
+    """事件响应器实例注入参数
+
+    本注入解析所有类型为且仅为 {ref}`nonebot.matcher.Matcher` 及其子类或 `None` 的参数。
+
+    为保证兼容性，本注入还会解析名为 `matcher` 且没有类型注解的参数。
+    """
 
     def __repr__(self) -> str:
         return "MatcherParam()"
@@ -287,14 +318,30 @@ class MatcherParam(Param):
     ) -> Optional["MatcherParam"]:
         from nonebot.matcher import Matcher
 
-        if generic_check_issubclass(param.annotation, Matcher) or (
-            param.annotation == param.empty and param.name == "matcher"
-        ):
+        # param type is Matcher(s) or subclass(es) of Matcher or None
+        if generic_check_issubclass(param.annotation, Matcher):
+            checker: Optional[ModelField] = None
+            if param.annotation is not Matcher:
+                checker = ModelField(
+                    name=param.name,
+                    type_=param.annotation,
+                    class_validators=None,
+                    model_config=CustomConfig,
+                    default=None,
+                    required=True,
+                )
+            return cls(Required, checker=checker)
+        # legacy: param is named "matcher" and has no type annotation
+        elif param.annotation == param.empty and param.name == "matcher":
             return cls(Required)
 
     async def _solve(self, matcher: "Matcher", **kwargs: Any) -> Any:
         return matcher
 
+    async def _check(self, matcher: "Matcher", **kwargs: Any) -> Any:
+        if checker := self.extra.get("checker", None):
+            check_field_type(checker, matcher)
+
 
 class ArgInner:
     def __init__(
@@ -308,22 +355,28 @@ class ArgInner:
 
 
 def Arg(key: Optional[str] = None) -> Any:
-    """`got` 的 Arg 参数消息"""
+    """Arg 参数消息"""
     return ArgInner(key, "message")
 
 
 def ArgStr(key: Optional[str] = None) -> str:
-    """`got` 的 Arg 参数消息文本"""
+    """Arg 参数消息文本"""
     return ArgInner(key, "str")  # type: ignore
 
 
 def ArgPlainText(key: Optional[str] = None) -> str:
-    """`got` 的 Arg 参数消息纯文本"""
+    """Arg 参数消息纯文本"""
     return ArgInner(key, "plaintext")  # type: ignore
 
 
 class ArgParam(Param):
-    """`got` 的 Arg 参数"""
+    """Arg 注入参数
+
+    本注入解析事件响应器操作 `got` 所获取的参数。
+
+    可以通过 `Arg`、`ArgStr`、`ArgPlainText` 等函数参数 `key` 指定获取的参数，
+    留空则会根据参数名称获取。
+    """
 
     def __repr__(self) -> str:
         return f"ArgParam(key={self.extra['key']!r}, type={self.extra['type']!r})"
@@ -336,9 +389,14 @@ class ArgParam(Param):
             return cls(
                 Required, key=param.default.key or param.name, type=param.default.type
             )
+        elif get_origin(param.annotation) is Annotated:
+            for arg in get_args(param.annotation):
+                if isinstance(arg, ArgInner):
+                    return cls(Required, key=arg.key or param.name, type=arg.type)
 
     async def _solve(self, matcher: "Matcher", **kwargs: Any) -> Any:
-        message = matcher.get_arg(self.extra["key"])
+        key: str = self.extra["key"]
+        message = matcher.get_arg(key)
         if message is None:
             return message
         if self.extra["type"] == "message":
@@ -350,7 +408,12 @@ class ArgParam(Param):
 
 
 class ExceptionParam(Param):
-    """`run_postprocessor` 的异常参数"""
+    """{ref}`nonebot.message.run_postprocessor` 的异常注入参数
+
+    本注入解析所有类型为 `Exception` 或 `None` 的参数。
+
+    为保证兼容性，本注入还会解析名为 `exception` 且没有类型注解的参数。
+    """
 
     def __repr__(self) -> str:
         return "ExceptionParam()"
@@ -359,9 +422,11 @@ class ExceptionParam(Param):
     def _check_param(
         cls, param: inspect.Parameter, allow_types: Tuple[Type[Param], ...]
     ) -> Optional["ExceptionParam"]:
-        if generic_check_issubclass(param.annotation, Exception) or (
-            param.annotation == param.empty and param.name == "exception"
-        ):
+        # param type is Exception(s) or subclass(es) of Exception or None
+        if generic_check_issubclass(param.annotation, Exception):
+            return cls(Required)
+        # legacy: param is named "exception" and has no type annotation
+        elif param.annotation == param.empty and param.name == "exception":
             return cls(Required)
 
     async def _solve(self, exception: Optional[Exception] = None, **kwargs: Any) -> Any:
@@ -369,7 +434,12 @@ class ExceptionParam(Param):
 
 
 class DefaultParam(Param):
-    """默认值参数"""
+    """默认值注入参数
+
+    本注入解析所有剩余未能解析且具有默认值的参数。
+
+    本注入参数应该具有最低优先级，因此应该在所有其他注入参数之后使用。
+    """
 
     def __repr__(self) -> str:
         return f"DefaultParam(default={self.default!r})"

nonebot/log.py

@@ -2,7 +2,7 @@
 
 NoneBot 使用 [`loguru`][loguru] 来记录日志信息。
 
-自定义 logger 请参考 [自定义日志](https://v2.nonebot.dev/docs/appendices/log)
+自定义 logger 请参考 [自定义日志](https://nonebot.dev/docs/appendices/log)
 以及 [`loguru`][loguru] 文档。
 
 [loguru]: https://github.com/Delgan/loguru
@@ -54,7 +54,7 @@ class LoguruHandler(logging.Handler):  # pragma: no cover
         except ValueError:
             level = record.levelno
 
-        frame, depth = logging.currentframe(), 2
+        frame, depth = sys._getframe(6), 6
         while frame and frame.f_code.co_filename == logging.__file__:
             frame = frame.f_back
             depth += 1
@@ -88,5 +88,6 @@ logger_id = logger.add(
     filter=default_filter,
     format=default_format,
 )
+"""默认日志处理器 id"""
 
 __autodoc__ = {"logger_id": False}

nonebot/message.py

@@ -80,7 +80,10 @@ RUN_POSTPCS_PARAMS = (
 
 
 def event_preprocessor(func: T_EventPreProcessor) -> T_EventPreProcessor:
-    """事件预处理。装饰一个函数，使它在每次接收到事件并分发给各响应器之前执行。"""
+    """事件预处理。
+
+    装饰一个函数，使它在每次接收到事件并分发给各响应器之前执行。
+    """
     _event_preprocessors.add(
         Dependent[Any].parse(call=func, allow_types=EVENT_PCS_PARAMS)
     )
@@ -88,7 +91,10 @@ def event_preprocessor(func: T_EventPreProcessor) -> T_EventPreProcessor:
 
 
 def event_postprocessor(func: T_EventPostProcessor) -> T_EventPostProcessor:
-    """事件后处理。装饰一个函数，使它在每次接收到事件并分发给各响应器之后执行。"""
+    """事件后处理。
+
+    装饰一个函数，使它在每次接收到事件并分发给各响应器之后执行。
+    """
     _event_postprocessors.add(
         Dependent[Any].parse(call=func, allow_types=EVENT_PCS_PARAMS)
     )
@@ -96,7 +102,10 @@ def event_postprocessor(func: T_EventPostProcessor) -> T_EventPostProcessor:
 
 
 def run_preprocessor(func: T_RunPreProcessor) -> T_RunPreProcessor:
-    """运行预处理。装饰一个函数，使它在每次事件响应器运行前执行。"""
+    """运行预处理。
+
+    装饰一个函数，使它在每次事件响应器运行前执行。
+    """
     _run_preprocessors.add(
         Dependent[Any].parse(call=func, allow_types=RUN_PREPCS_PARAMS)
     )
@@ -104,55 +113,149 @@ def run_preprocessor(func: T_RunPreProcessor) -> T_RunPreProcessor:
 
 
 def run_postprocessor(func: T_RunPostProcessor) -> T_RunPostProcessor:
-    """运行后处理。装饰一个函数，使它在每次事件响应器运行后执行。"""
+    """运行后处理。
+
+    装饰一个函数，使它在每次事件响应器运行后执行。
+    """
     _run_postprocessors.add(
         Dependent[Any].parse(call=func, allow_types=RUN_POSTPCS_PARAMS)
     )
     return func
 
 
-async def _check_matcher(
-    Matcher: Type[Matcher],
+async def _apply_event_preprocessors(
     bot: "Bot",
     event: "Event",
     state: T_State,
     stack: Optional[AsyncExitStack] = None,
     dependency_cache: Optional[T_DependencyCache] = None,
-) -> None:
-    if Matcher.expire_time and datetime.now() > Matcher.expire_time:
-        with contextlib.suppress(Exception):
-            Matcher.destroy()
-        return
+    show_log: bool = True,
+) -> bool:
+    """运行事件预处理。
+
+    参数:
+        bot: Bot 对象
+        event: Event 对象
+        state: 会话状态
+        stack: 异步上下文栈
+        dependency_cache: 依赖缓存
+        show_log: 是否显示日志
+
+    返回:
+        是否继续处理事件
+    """
+    if not _event_preprocessors:
+        return True
+
+    if show_log:
+        logger.debug("Running PreProcessors...")
 
     try:
-        if not await Matcher.check_perm(
-            bot, event, stack, dependency_cache
-        ) or not await Matcher.check_rule(bot, event, state, stack, dependency_cache):
-            return
+        await asyncio.gather(
+            *(
+                run_coro_with_catch(
+                    proc(
+                        bot=bot,
+                        event=event,
+                        state=state,
+                        stack=stack,
+                        dependency_cache=dependency_cache,
+                    ),
+                    (SkippedException,),
+                )
+                for proc in _event_preprocessors
+            )
+        )
+    except IgnoredException:
+        logger.opt(colors=True).info(
+            f"Event {escape_tag(event.get_event_name())} is <b>ignored</b>"
+        )
+        return False
     except Exception as e:
         logger.opt(colors=True, exception=e).error(
-            f"<r><bg #f8bbd0>Rule check failed for {Matcher}.</bg #f8bbd0></r>"
+            "<r><bg #f8bbd0>Error when running EventPreProcessors. "
+            "Event ignored!</bg #f8bbd0></r>"
         )
-        return
+        return False
 
-    if Matcher.temp:
-        with contextlib.suppress(Exception):
-            Matcher.destroy()
-    await _run_matcher(Matcher, bot, event, state, stack, dependency_cache)
+    return True
 
 
-async def _run_matcher(
-    Matcher: Type[Matcher],
+async def _apply_event_postprocessors(
     bot: "Bot",
     event: "Event",
     state: T_State,
     stack: Optional[AsyncExitStack] = None,
     dependency_cache: Optional[T_DependencyCache] = None,
+    show_log: bool = True,
 ) -> None:
-    logger.info(f"Event will be handled by {Matcher}")
+    """运行事件后处理。
 
-    matcher = Matcher()
-    if coros := [
+    参数:
+        bot: Bot 对象
+        event: Event 对象
+        state: 会话状态
+        stack: 异步上下文栈
+        dependency_cache: 依赖缓存
+        show_log: 是否显示日志
+    """
+    if not _event_postprocessors:
+        return
+
+    if show_log:
+        logger.debug("Running PostProcessors...")
+
+    try:
+        await asyncio.gather(
+            *(
+                run_coro_with_catch(
+                    proc(
+                        bot=bot,
+                        event=event,
+                        state=state,
+                        stack=stack,
+                        dependency_cache=dependency_cache,
+                    ),
+                    (SkippedException,),
+                )
+                for proc in _event_postprocessors
+            )
+        )
+    except Exception as e:
+        logger.opt(colors=True, exception=e).error(
+            "<r><bg #f8bbd0>Error when running EventPostProcessors</bg #f8bbd0></r>"
+        )
+
+
+async def _apply_run_preprocessors(
+    bot: "Bot",
+    event: "Event",
+    state: T_State,
+    matcher: Matcher,
+    stack: Optional[AsyncExitStack] = None,
+    dependency_cache: Optional[T_DependencyCache] = None,
+) -> bool:
+    """运行事件响应器运行前处理。
+
+    参数:
+        bot: Bot 对象
+        event: Event 对象
+        state: 会话状态
+        matcher: 事件响应器
+        stack: 异步上下文栈
+        dependency_cache: 依赖缓存
+
+    返回:
+        是否继续处理事件
+    """
+    if not _run_preprocessors:
+        return True
+
+    # ensure matcher function can be correctly called
+    with matcher.ensure_context(bot, event):
+        try:
+            await asyncio.gather(
+                *(
                     run_coro_with_catch(
                         proc(
                             matcher=matcher,
@@ -165,33 +268,46 @@ async def _run_matcher(
                         (SkippedException,),
                     )
                     for proc in _run_preprocessors
-    ]:
-        # ensure matcher function can be correctly called
-        with matcher.ensure_context(bot, event):
-            try:
-                await asyncio.gather(*coros)
+                )
+            )
         except IgnoredException:
             logger.opt(colors=True).info(f"{matcher} running is <b>cancelled</b>")
-                return
+            return False
         except Exception as e:
             logger.opt(colors=True, exception=e).error(
-                    "<r><bg #f8bbd0>Error when running RunPreProcessors. Running cancelled!</bg #f8bbd0></r>"
+                "<r><bg #f8bbd0>Error when running RunPreProcessors. "
+                "Running cancelled!</bg #f8bbd0></r>"
             )
+            return False
 
+    return True
+
+
+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,
+) -> None:
+    """运行事件响应器运行后处理。
+
+    参数:
+        bot: Bot 对象
+        event: Event 对象
+        matcher: 事件响应器
+        exception: 事件响应器运行异常
+        stack: 异步上下文栈
+        dependency_cache: 依赖缓存
+    """
+    if not _run_postprocessors:
         return
 
-    exception = None
-
+    with matcher.ensure_context(bot, event):
         try:
-        logger.debug(f"Running {matcher}")
-        await matcher.run(bot, event, state, stack, dependency_cache)
-    except Exception as e:
-        logger.opt(colors=True, exception=e).error(
-            f"<r><bg #f8bbd0>Running {matcher} failed.</bg #f8bbd0></r>"
-        )
-        exception = e
-
-    if coros := [
+            await asyncio.gather(
+                *(
                     run_coro_with_catch(
                         proc(
                             matcher=matcher,
@@ -205,20 +321,158 @@ async def _run_matcher(
                         (SkippedException,),
                     )
                     for proc in _run_postprocessors
-    ]:
-        # ensure matcher function can be correctly called
-        with matcher.ensure_context(bot, event):
-            try:
-                await asyncio.gather(*coros)
+                )
+            )
         except Exception as e:
             logger.opt(colors=True, exception=e).error(
                 "<r><bg #f8bbd0>Error when running RunPostProcessors</bg #f8bbd0></r>"
             )
 
+
+async def _check_matcher(
+    Matcher: Type[Matcher],
+    bot: "Bot",
+    event: "Event",
+    state: T_State,
+    stack: Optional[AsyncExitStack] = None,
+    dependency_cache: Optional[T_DependencyCache] = None,
+) -> bool:
+    """检查事件响应器是否符合运行条件。
+
+    请注意，过时的事件响应器将被**销毁**。对于未过时的事件响应器，将会一次检查其响应类型、权限和规则。
+
+    参数:
+        Matcher: 要检查的事件响应器
+        bot: Bot 对象
+        event: Event 对象
+        state: 会话状态
+        stack: 异步上下文栈
+        dependency_cache: 依赖缓存
+
+    返回:
+        bool: 是否符合运行条件
+    """
+    if Matcher.expire_time and datetime.now() > Matcher.expire_time:
+        with contextlib.suppress(Exception):
+            Matcher.destroy()
+        return False
+
+    try:
+        if not await Matcher.check_perm(
+            bot, event, stack, dependency_cache
+        ) or not await Matcher.check_rule(bot, event, state, stack, dependency_cache):
+            return False
+    except Exception as e:
+        logger.opt(colors=True, exception=e).error(
+            f"<r><bg #f8bbd0>Rule check failed for {Matcher}.</bg #f8bbd0></r>"
+        )
+        return False
+
+    return True
+
+
+async def _run_matcher(
+    Matcher: Type[Matcher],
+    bot: "Bot",
+    event: "Event",
+    state: T_State,
+    stack: Optional[AsyncExitStack] = None,
+    dependency_cache: Optional[T_DependencyCache] = None,
+) -> None:
+    """运行事件响应器。
+
+    临时事件响应器将在运行前被**销毁**。
+
+    参数:
+        Matcher: 事件响应器
+        bot: Bot 对象
+        event: Event 对象
+        state: 会话状态
+        stack: 异步上下文栈
+        dependency_cache: 依赖缓存
+
+    异常:
+        StopPropagation: 阻止事件继续传播
+    """
+    logger.info(f"Event will be handled by {Matcher}")
+
+    if Matcher.temp:
+        with contextlib.suppress(Exception):
+            Matcher.destroy()
+
+    matcher = Matcher()
+
+    if not await _apply_run_preprocessors(
+        bot=bot,
+        event=event,
+        state=state,
+        matcher=matcher,
+        stack=stack,
+        dependency_cache=dependency_cache,
+    ):
+        return
+
+    exception = None
+
+    try:
+        logger.debug(f"Running {matcher}")
+        await matcher.run(bot, event, state, stack, dependency_cache)
+    except Exception as e:
+        logger.opt(colors=True, exception=e).error(
+            f"<r><bg #f8bbd0>Running {matcher} failed.</bg #f8bbd0></r>"
+        )
+        exception = e
+
+    await _apply_run_postprocessors(
+        bot=bot,
+        event=event,
+        matcher=matcher,
+        exception=exception,
+        stack=stack,
+        dependency_cache=dependency_cache,
+    )
+
     if matcher.block:
         raise StopPropagation
+
+
+async def check_and_run_matcher(
+    Matcher: Type[Matcher],
+    bot: "Bot",
+    event: "Event",
+    state: T_State,
+    stack: Optional[AsyncExitStack] = None,
+    dependency_cache: Optional[T_DependencyCache] = None,
+) -> None:
+    """检查并运行事件响应器。
+
+    参数:
+        Matcher: 事件响应器
+        bot: Bot 对象
+        event: Event 对象
+        state: 会话状态
+        stack: 异步上下文栈
+        dependency_cache: 依赖缓存
+    """
+    if not await _check_matcher(
+        Matcher=Matcher,
+        bot=bot,
+        event=event,
+        state=state,
+        stack=stack,
+        dependency_cache=dependency_cache,
+    ):
         return
 
+    await _run_matcher(
+        Matcher=Matcher,
+        bot=bot,
+        event=event,
+        state=state,
+        stack=stack,
+        dependency_cache=dependency_cache,
+    )
+
 
 async def handle_event(bot: "Bot", event: "Event") -> None:
     """处理一个事件。调用该函数以实现分发事件。
@@ -245,34 +499,15 @@ async def handle_event(bot: "Bot", event: "Event") -> None:
     state: Dict[Any, Any] = {}
     dependency_cache: T_DependencyCache = {}
 
+    # create event scope context
     async with AsyncExitStack() as stack:
-        if coros := [
-            run_coro_with_catch(
-                proc(
+        if not await _apply_event_preprocessors(
             bot=bot,
             event=event,
             state=state,
             stack=stack,
             dependency_cache=dependency_cache,
-                ),
-                (SkippedException,),
-            )
-            for proc in _event_preprocessors
-        ]:
-            try:
-                if show_log:
-                    logger.debug("Running PreProcessors...")
-                await asyncio.gather(*coros)
-            except IgnoredException as e:
-                logger.opt(colors=True).info(
-                    f"Event {escape_tag(event.get_event_name())} is <b>ignored</b>"
-                )
-                return
-            except Exception as e:
-                logger.opt(colors=True, exception=e).error(
-                    "<r><bg #f8bbd0>Error when running EventPreProcessors. "
-                    "Event ignored!</bg #f8bbd0></r>"
-                )
+        ):
             return
 
         # Trie Match
@@ -284,6 +519,7 @@ async def handle_event(bot: "Bot", event: "Event") -> None:
             )
 
         break_flag = False
+        # iterate through all priority until stop propagation
         for priority in sorted(matchers.keys()):
             if break_flag:
                 break
@@ -292,14 +528,12 @@ async def handle_event(bot: "Bot", event: "Event") -> None:
                 logger.debug(f"Checking for matchers in priority {priority}...")
 
             pending_tasks = [
-                _check_matcher(
+                check_and_run_matcher(
                     matcher, bot, event, state.copy(), stack, dependency_cache
                 )
                 for matcher in matchers[priority]
             ]
-
             results = await asyncio.gather(*pending_tasks, return_exceptions=True)
-
             for result in results:
                 if not isinstance(result, Exception):
                     continue
@@ -314,24 +548,4 @@ async def handle_event(bot: "Bot", event: "Event") -> None:
         if show_log:
             logger.debug("Checking for matchers completed")
 
-        if coros := [
-            run_coro_with_catch(
-                proc(
-                    bot=bot,
-                    event=event,
-                    state=state,
-                    stack=stack,
-                    dependency_cache=dependency_cache,
-                ),
-                (SkippedException,),
-            )
-            for proc in _event_postprocessors
-        ]:
-            try:
-                if show_log:
-                    logger.debug("Running PostProcessors...")
-                await asyncio.gather(*coros)
-            except Exception as e:
-                logger.opt(colors=True, exception=e).error(
-                    "<r><bg #f8bbd0>Error when running EventPostProcessors</bg #f8bbd0></r>"
-                )
+        await _apply_event_postprocessors(bot, event, state, stack, dependency_cache)

nonebot/params.py

@@ -5,8 +5,7 @@ FrontMatter:
     description: nonebot.params 模块
 """
 
-import warnings
-from typing import Any, Dict, List, Tuple, Union, Optional
+from typing import Any, Dict, List, Match, Tuple, Union, Optional
 
 from nonebot.typing import T_State
 from nonebot.matcher import Matcher
@@ -25,15 +24,12 @@ from nonebot.internal.params import MatcherParam as MatcherParam
 from nonebot.internal.params import ExceptionParam as ExceptionParam
 from nonebot.consts import (
     CMD_KEY,
-    REGEX_STR,
     PREFIX_KEY,
-    REGEX_DICT,
     SHELL_ARGS,
     SHELL_ARGV,
     CMD_ARG_KEY,
     KEYWORD_KEY,
     RAW_CMD_KEY,
-    REGEX_GROUP,
     ENDSWITH_KEY,
     CMD_START_KEY,
     FULLMATCH_KEY,
@@ -142,23 +138,17 @@ def ShellCommandArgv() -> Any:
     return Depends(_shell_command_argv, use_cache=False)
 
 
-def _regex_matched(state: T_State) -> str:
+def _regex_matched(state: T_State) -> Match[str]:
     return state[REGEX_MATCHED]
 
 
-def RegexMatched() -> str:
+def RegexMatched() -> Match[str]:
     """正则匹配结果"""
-    warnings.warn(
-        '"RegexMatched()" will be changed to "re.Match" object, '
-        'use "RegexStr()" instead. '
-        "See https://github.com/nonebot/nonebot2/pull/1453 .",
-        DeprecationWarning,
-    )
     return Depends(_regex_matched, use_cache=False)
 
 
 def _regex_str(state: T_State) -> str:
-    return state[REGEX_STR]
+    return _regex_matched(state).group()
 
 
 def RegexStr() -> str:
@@ -167,7 +157,7 @@ def RegexStr() -> str:
 
 
 def _regex_group(state: T_State) -> Tuple[Any, ...]:
-    return state[REGEX_GROUP]
+    return _regex_matched(state).groups()
 
 
 def RegexGroup() -> Tuple[Any, ...]:
@@ -176,7 +166,7 @@ def RegexGroup() -> Tuple[Any, ...]:
 
 
 def _regex_dict(state: T_State) -> Dict[str, Any]:
-    return state[REGEX_DICT]
+    return _regex_matched(state).groupdict()
 
 
 def RegexDict() -> Dict[str, Any]:

nonebot/permission.py

@@ -1,7 +1,8 @@
 """本模块是 {ref}`nonebot.matcher.Matcher.permission` 的类型定义。
 
-每个 {ref}`nonebot.matcher.Matcher` 拥有一个 {ref}`nonebot.permission.Permission` ，
-其中是 `PermissionChecker` 的集合，只要有一个 `PermissionChecker` 检查结果为 `True` 时就会继续运行。
+每个{ref}`事件响应器 <nonebot.matcher.Matcher>`
+拥有一个 {ref}`nonebot.permission.Permission`，其中是 `PermissionChecker` 的集合。
+只要有一个 `PermissionChecker` 检查结果为 `True` 时就会继续运行。
 
 FrontMatter:
     sidebar_position: 6

nonebot/plugin/__init__.py

@@ -24,8 +24,10 @@
 - `load_all_plugins` => {ref}``load_all_plugins` <nonebot.plugin.load.load_all_plugins>`
 - `load_from_json` => {ref}``load_from_json` <nonebot.plugin.load.load_from_json>`
 - `load_from_toml` => {ref}``load_from_toml` <nonebot.plugin.load.load_from_toml>`
-- `load_builtin_plugin` => {ref}``load_builtin_plugin` <nonebot.plugin.load.load_builtin_plugin>`
-- `load_builtin_plugins` => {ref}``load_builtin_plugins` <nonebot.plugin.load.load_builtin_plugins>`
+- `load_builtin_plugin` =>
+  {ref}``load_builtin_plugin` <nonebot.plugin.load.load_builtin_plugin>`
+- `load_builtin_plugins` =>
+  {ref}``load_builtin_plugins` <nonebot.plugin.load.load_builtin_plugins>`
 - `require` => {ref}``require` <nonebot.plugin.load.require>`
 - `PluginMetadata` => {ref}``PluginMetadata` <nonebot.plugin.plugin.PluginMetadata>`
 
@@ -42,7 +44,7 @@ from typing import Set, Dict, List, Tuple, Optional
 _plugins: Dict[str, "Plugin"] = {}
 _managers: List["PluginManager"] = []
 _current_plugin_chain: ContextVar[Tuple["Plugin", ...]] = ContextVar(
-    "_current_plugin_chain", default=tuple()
+    "_current_plugin_chain", default=()
 )
 
 
@@ -132,3 +134,4 @@ from .plugin import PluginMetadata as PluginMetadata
 from .load import load_all_plugins as load_all_plugins
 from .load import load_builtin_plugin as load_builtin_plugin
 from .load import load_builtin_plugins as load_builtin_plugins
+from .load import inherit_supported_adapters as inherit_supported_adapters

nonebot/plugin/load.py

@@ -4,6 +4,7 @@ FrontMatter:
     sidebar_position: 1
     description: nonebot.plugin.load 模块
 """
+
 import json
 from pathlib import Path
 from types import ModuleType
@@ -13,10 +14,10 @@ from nonebot.utils import path_to_module_name
 
 from .plugin import Plugin
 from .manager import PluginManager
-from . import _managers, get_plugin, _module_name_to_plugin_name
+from . import _managers, get_plugin, _current_plugin_chain, _module_name_to_plugin_name
 
 try:  # pragma: py-gte-311
-    import tomllib  # pyright: reportMissingImports=false
+    import tomllib  # pyright: ignore[reportMissingImports]
 except ModuleNotFoundError:  # pragma: py-lt-311
     import tomli as tomllib
 
@@ -25,7 +26,8 @@ def load_plugin(module_path: Union[str, Path]) -> Optional[Plugin]:
     """加载单个插件，可以是本地插件或是通过 `pip` 安装的插件。
 
     参数:
-        module_path: 插件名称 `path.to.your.plugin` 或插件路径 `pathlib.Path(path/to/your/plugin)`
+        module_path: 插件名称 `path.to.your.plugin`
+            或插件路径 `pathlib.Path(path/to/your/plugin)`
     """
     module_path = (
         path_to_module_name(module_path)
@@ -63,7 +65,8 @@ def load_all_plugins(
 
 
 def load_from_json(file_path: str, encoding: str = "utf-8") -> Set[Plugin]:
-    """导入指定 json 文件中的 `plugins` 以及 `plugin_dirs` 下多个插件，以 `_` 开头的插件不会被导入!
+    """导入指定 json 文件中的 `plugins` 以及 `plugin_dirs` 下多个插件。
+    以 `_` 开头的插件不会被导入!
 
     参数:
         file_path: 指定 json 文件路径
@@ -81,7 +84,7 @@ def load_from_json(file_path: str, encoding: str = "utf-8") -> Set[Plugin]:
         nonebot.load_from_json("plugins.json")
         ```
     """
-    with open(file_path, "r", encoding=encoding) as f:
+    with open(file_path, encoding=encoding) as f:
         data = json.load(f)
     if not isinstance(data, dict):
         raise TypeError("json file must contains a dict!")
@@ -93,7 +96,9 @@ def load_from_json(file_path: str, encoding: str = "utf-8") -> Set[Plugin]:
 
 
 def load_from_toml(file_path: str, encoding: str = "utf-8") -> Set[Plugin]:
-    """导入指定 toml 文件 `[tool.nonebot]` 中的 `plugins` 以及 `plugin_dirs` 下多个插件，以 `_` 开头的插件不会被导入!
+    """导入指定 toml 文件 `[tool.nonebot]` 中的
+    `plugins` 以及 `plugin_dirs` 下多个插件。
+    以 `_` 开头的插件不会被导入!
 
     参数:
         file_path: 指定 toml 文件路径
@@ -110,7 +115,7 @@ def load_from_toml(file_path: str, encoding: str = "utf-8") -> Set[Plugin]:
         nonebot.load_from_toml("pyproject.toml")
         ```
     """
-    with open(file_path, "r", encoding=encoding) as f:
+    with open(file_path, encoding=encoding) as f:
         data = tomllib.loads(f.read())
 
     nonebot_data = data.get("tool", {}).get("nonebot")
@@ -161,11 +166,55 @@ def require(name: str) -> ModuleType:
         RuntimeError: 插件无法加载
     """
     plugin = get_plugin(_module_name_to_plugin_name(name))
+    # if plugin not loaded
     if not plugin:
+        # plugin already declared
         if manager := _find_manager_by_name(name):
             plugin = manager.load_plugin(name)
+        # plugin not declared, try to declare and load it
         else:
+            # clear current plugin chain, ensure plugin loaded in a new context
+            _t = _current_plugin_chain.set(())
+            try:
                 plugin = load_plugin(name)
+            finally:
+                _current_plugin_chain.reset(_t)
     if not plugin:
         raise RuntimeError(f'Cannot load plugin "{name}"!')
     return plugin.module
+
+
+def inherit_supported_adapters(*names: str) -> Optional[Set[str]]:
+    """获取已加载插件的适配器支持状态集合。
+
+    如果传入了多个插件名称，返回值会自动取交集。
+
+    参数:
+        names: 插件名称列表。
+
+    异常:
+        RuntimeError: 插件未加载
+        ValueError: 插件缺少元数据
+    """
+    final_supported: Optional[Set[str]] = None
+
+    for name in names:
+        plugin = get_plugin(_module_name_to_plugin_name(name))
+        if plugin is None:
+            raise RuntimeError(f'Plugin "{name}" is not loaded!')
+        meta = plugin.metadata
+        if meta is None:
+            raise ValueError(f'Plugin "{name}" has no metadata!')
+        support = meta.supported_adapters
+        if support is None:
+            continue
+        final_supported = (
+            support if final_supported is None else (final_supported & support)
+        )
+
+    return final_supported and {
+        f"nonebot.adapters.{adapter_name[1:]}"
+        if adapter_name.startswith("~")
+        else adapter_name
+        for adapter_name in final_supported
+    }

nonebot/plugin/manager.py

@@ -6,6 +6,7 @@ FrontMatter:
     sidebar_position: 5
     description: nonebot.plugin.manager 模块
 """
+
 import sys
 import pkgutil
 import importlib
@@ -228,6 +229,7 @@ class PluginLoader(SourceFileLoader):
         # detect parent plugin before entering current plugin context
         parent_plugins = _current_plugin_chain.get()
         for pre_plugin in reversed(parent_plugins):
+            # ensure parent plugin is declared before current plugin
             if _managers.index(pre_plugin.manager) < _managers.index(self.manager):
                 plugin.parent_plugin = pre_plugin
                 pre_plugin.sub_plugins.add(plugin)

nonebot/plugin/on.py

@@ -4,6 +4,7 @@ FrontMatter:
     sidebar_position: 2
     description: nonebot.plugin.on 模块
 """
+
 import re
 import inspect
 from types import ModuleType
@@ -322,7 +323,8 @@ def on_shell_command(
 
     与普通的 `on_command` 不同的是，在添加 `parser` 参数时, 响应器会自动处理消息。
 
-    并将用户输入的原始参数列表保存在 `state["argv"]`, `parser` 处理的参数保存在 `state["args"]` 中
+    可以通过 {ref}`nonebot.params.ShellCommandArgv` 获取原始参数列表，
+    通过 {ref}`nonebot.params.ShellCommandArgs` 获取解析后的参数字典。
 
     参数:
         cmd: 指定命令内容
@@ -427,6 +429,7 @@ class CommandGroup(_Group):
 
     参数:
         cmd: 指定命令内容
+        prefix_aliases: 是否影响命令别名，给命令别名加前缀
         rule: 事件响应规则
         permission: 事件响应权限
         handlers: 事件处理函数列表
@@ -437,11 +440,14 @@ class CommandGroup(_Group):
         state: 默认 state
     """
 
-    def __init__(self, cmd: Union[str, Tuple[str, ...]], **kwargs):
+    def __init__(
+        self, cmd: Union[str, Tuple[str, ...]], prefix_aliases: bool = False, **kwargs
+    ):
         """命令前缀"""
         super().__init__(**kwargs)
         self.basecmd: Tuple[str, ...] = (cmd,) if isinstance(cmd, str) else cmd
         self.base_kwargs.pop("aliases", None)
+        self.prefix_aliases = prefix_aliases
 
     def __repr__(self) -> str:
         return f"CommandGroup(cmd={self.basecmd}, matchers={len(self.matchers)})"
@@ -464,6 +470,11 @@ class CommandGroup(_Group):
         """
         sub_cmd = (cmd,) if isinstance(cmd, str) else cmd
         cmd = self.basecmd + sub_cmd
+        if self.prefix_aliases and (aliases := kwargs.get("aliases")):
+            kwargs["aliases"] = {
+                self.basecmd + ((alias,) if isinstance(alias, str) else alias)
+                for alias in aliases
+            }
         matcher = on_command(cmd, **self._get_final_kwargs(kwargs))
         self.matchers.append(matcher)
         return matcher
@@ -488,6 +499,11 @@ class CommandGroup(_Group):
         """
         sub_cmd = (cmd,) if isinstance(cmd, str) else cmd
         cmd = self.basecmd + sub_cmd
+        if self.prefix_aliases and (aliases := kwargs.get("aliases")):
+            kwargs["aliases"] = {
+                self.basecmd + ((alias,) if isinstance(alias, str) else alias)
+                for alias in aliases
+            }
         matcher = on_shell_command(cmd, **self._get_final_kwargs(kwargs))
         self.matchers.append(matcher)
         return matcher
@@ -712,7 +728,8 @@ class MatcherGroup(_Group):
 
         与普通的 `on_command` 不同的是，在添加 `parser` 参数时, 响应器会自动处理消息。
 
-        并将用户输入的原始参数列表保存在 `state["argv"]`, `parser` 处理的参数保存在 `state["args"]` 中
+        可以通过 {ref}`nonebot.params.ShellCommandArgv` 获取原始参数列表，
+        通过 {ref}`nonebot.params.ShellCommandArgs` 获取解析后的参数字典。
 
         参数:
             cmd: 指定命令内容

nonebot/plugin/on.pyi

@@ -1,7 +1,7 @@
 import re
+from typing import Any
 from types import ModuleType
 from datetime import datetime, timedelta
-from typing import Set, List, Type, Tuple, Union, Optional
 
 from nonebot.adapters import Event
 from nonebot.matcher import Matcher
@@ -12,399 +12,409 @@ from nonebot.typing import T_State, T_Handler, T_RuleChecker, T_PermissionChecke
 
 from .plugin import Plugin
 
-def store_matcher(matcher: Type[Matcher]) -> None: ...
-def get_matcher_plugin(depth: int = ...) -> Optional[Plugin]: ...
-def get_matcher_module(depth: int = ...) -> Optional[ModuleType]: ...
+def store_matcher(matcher: type[Matcher]) -> None: ...
+def get_matcher_plugin(depth: int = ...) -> Plugin | None: ...
+def get_matcher_module(depth: int = ...) -> ModuleType | None: ...
 def on(
     type: str = "",
-    rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
+    rule: Rule | T_RuleChecker | None = ...,
+    permission: Permission | T_PermissionChecker | None = ...,
     *,
-    handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+    handlers: list[T_Handler | Dependent] | None = ...,
     temp: bool = ...,
-    expire_time: Optional[Union[datetime, timedelta]] = ...,
+    expire_time: datetime | timedelta | None = ...,
     priority: int = ...,
     block: bool = ...,
-    state: Optional[T_State] = ...,
-) -> Type[Matcher]: ...
+    state: T_State | None = ...,
+) -> type[Matcher]: ...
 def on_metaevent(
-    rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
+    rule: Rule | T_RuleChecker | None = ...,
+    permission: Permission | T_PermissionChecker | None = ...,
     *,
-    handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+    handlers: list[T_Handler | Dependent] | None = ...,
     temp: bool = ...,
-    expire_time: Optional[Union[datetime, timedelta]] = ...,
+    expire_time: datetime | timedelta | None = ...,
     priority: int = ...,
     block: bool = ...,
-    state: Optional[T_State] = ...,
-) -> Type[Matcher]: ...
+    state: T_State | None = ...,
+) -> type[Matcher]: ...
 def on_message(
-    rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
+    rule: Rule | T_RuleChecker | None = ...,
+    permission: Permission | T_PermissionChecker | None = ...,
     *,
-    handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+    handlers: list[T_Handler | Dependent] | None = ...,
     temp: bool = ...,
-    expire_time: Optional[Union[datetime, timedelta]] = ...,
+    expire_time: datetime | timedelta | None = ...,
     priority: int = ...,
     block: bool = ...,
-    state: Optional[T_State] = ...,
-) -> Type[Matcher]: ...
+    state: T_State | None = ...,
+) -> type[Matcher]: ...
 def on_notice(
-    rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
+    rule: Rule | T_RuleChecker | None = ...,
+    permission: Permission | T_PermissionChecker | None = ...,
     *,
-    handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+    handlers: list[T_Handler | Dependent] | None = ...,
     temp: bool = ...,
-    expire_time: Optional[Union[datetime, timedelta]] = ...,
+    expire_time: datetime | timedelta | None = ...,
     priority: int = ...,
     block: bool = ...,
-    state: Optional[T_State] = ...,
-) -> Type[Matcher]: ...
+    state: T_State | None = ...,
+) -> type[Matcher]: ...
 def on_request(
-    rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
+    rule: Rule | T_RuleChecker | None = ...,
+    permission: Permission | T_PermissionChecker | None = ...,
     *,
-    handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+    handlers: list[T_Handler | Dependent] | None = ...,
     temp: bool = ...,
-    expire_time: Optional[Union[datetime, timedelta]] = ...,
+    expire_time: datetime | timedelta | None = ...,
     priority: int = ...,
     block: bool = ...,
-    state: Optional[T_State] = ...,
-) -> Type[Matcher]: ...
+    state: T_State | None = ...,
+) -> type[Matcher]: ...
 def on_startswith(
-    msg: Union[str, Tuple[str, ...]],
-    rule: Optional[Union[Rule, T_RuleChecker]] = ...,
+    msg: str | tuple[str, ...],
+    rule: Rule | T_RuleChecker | None = ...,
     ignorecase: bool = ...,
     *,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-    handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+    permission: Permission | T_PermissionChecker | None = ...,
+    handlers: list[T_Handler | Dependent] | None = ...,
     temp: bool = ...,
-    expire_time: Optional[Union[datetime, timedelta]] = ...,
+    expire_time: datetime | timedelta | None = ...,
     priority: int = ...,
     block: bool = ...,
-    state: Optional[T_State] = ...,
-) -> Type[Matcher]: ...
+    state: T_State | None = ...,
+) -> type[Matcher]: ...
 def on_endswith(
-    msg: Union[str, Tuple[str, ...]],
-    rule: Optional[Union[Rule, T_RuleChecker]] = ...,
+    msg: str | tuple[str, ...],
+    rule: Rule | T_RuleChecker | None = ...,
     ignorecase: bool = ...,
     *,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-    handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+    permission: Permission | T_PermissionChecker | None = ...,
+    handlers: list[T_Handler | Dependent] | None = ...,
     temp: bool = ...,
-    expire_time: Optional[Union[datetime, timedelta]] = ...,
+    expire_time: datetime | timedelta | None = ...,
     priority: int = ...,
     block: bool = ...,
-    state: Optional[T_State] = ...,
-) -> Type[Matcher]: ...
+    state: T_State | None = ...,
+) -> type[Matcher]: ...
 def on_fullmatch(
-    msg: Union[str, Tuple[str, ...]],
-    rule: Optional[Union[Rule, T_RuleChecker]] = ...,
+    msg: str | tuple[str, ...],
+    rule: Rule | T_RuleChecker | None = ...,
     ignorecase: bool = ...,
     *,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-    handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+    permission: Permission | T_PermissionChecker | None = ...,
+    handlers: list[T_Handler | Dependent] | None = ...,
     temp: bool = ...,
-    expire_time: Optional[Union[datetime, timedelta]] = ...,
+    expire_time: datetime | timedelta | None = ...,
     priority: int = ...,
     block: bool = ...,
-    state: Optional[T_State] = ...,
-) -> Type[Matcher]: ...
+    state: T_State | None = ...,
+) -> type[Matcher]: ...
 def on_keyword(
-    keywords: Set[str],
-    rule: Optional[Union[Rule, T_RuleChecker]] = ...,
+    keywords: set[str],
+    rule: Rule | T_RuleChecker | None = ...,
     *,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-    handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+    permission: Permission | T_PermissionChecker | None = ...,
+    handlers: list[T_Handler | Dependent] | None = ...,
     temp: bool = ...,
-    expire_time: Optional[Union[datetime, timedelta]] = ...,
+    expire_time: datetime | timedelta | None = ...,
     priority: int = ...,
     block: bool = ...,
-    state: Optional[T_State] = ...,
-) -> Type[Matcher]: ...
+    state: T_State | None = ...,
+) -> type[Matcher]: ...
 def on_command(
-    cmd: Union[str, Tuple[str, ...]],
-    rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-    aliases: Optional[Set[Union[str, Tuple[str, ...]]]] = ...,
-    force_whitespace: Optional[Union[str, bool]] = ...,
+    cmd: str | tuple[str, ...],
+    rule: Rule | T_RuleChecker | None = ...,
+    aliases: set[str | tuple[str, ...]] | None = ...,
+    force_whitespace: str | bool | None = ...,
     *,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-    handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+    permission: Permission | T_PermissionChecker | None = ...,
+    handlers: list[T_Handler | Dependent] | None = ...,
     temp: bool = ...,
-    expire_time: Optional[Union[datetime, timedelta]] = ...,
+    expire_time: datetime | timedelta | None = ...,
     priority: int = ...,
     block: bool = ...,
-    state: Optional[T_State] = ...,
-) -> Type[Matcher]: ...
+    state: T_State | None = ...,
+) -> type[Matcher]: ...
 def on_shell_command(
-    cmd: Union[str, Tuple[str, ...]],
-    rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-    aliases: Optional[Set[Union[str, Tuple[str, ...]]]] = ...,
-    parser: Optional[ArgumentParser] = ...,
+    cmd: str | tuple[str, ...],
+    rule: Rule | T_RuleChecker | None = ...,
+    aliases: set[str | tuple[str, ...]] | None = ...,
+    parser: ArgumentParser | None = ...,
     *,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-    handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+    permission: Permission | T_PermissionChecker | None = ...,
+    handlers: list[T_Handler | Dependent] | None = ...,
     temp: bool = ...,
-    expire_time: Optional[Union[datetime, timedelta]] = ...,
+    expire_time: datetime | timedelta | None = ...,
     priority: int = ...,
     block: bool = ...,
-    state: Optional[T_State] = ...,
-) -> Type[Matcher]: ...
+    state: T_State | None = ...,
+) -> type[Matcher]: ...
 def on_regex(
     pattern: str,
-    flags: Union[int, re.RegexFlag] = ...,
-    rule: Optional[Union[Rule, T_RuleChecker]] = ...,
+    flags: int | re.RegexFlag = ...,
+    rule: Rule | T_RuleChecker | None = ...,
     *,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-    handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+    permission: Permission | T_PermissionChecker | None = ...,
+    handlers: list[T_Handler | Dependent] | None = ...,
     temp: bool = ...,
-    expire_time: Optional[Union[datetime, timedelta]] = ...,
+    expire_time: datetime | timedelta | None = ...,
     priority: int = ...,
     block: bool = ...,
-    state: Optional[T_State] = ...,
-) -> Type[Matcher]: ...
+    state: T_State | None = ...,
+) -> type[Matcher]: ...
 def on_type(
-    types: Union[Type[Event], Tuple[Type[Event], ...]],
-    rule: Optional[Union[Rule, T_RuleChecker]] = ...,
+    types: type[Event] | tuple[type[Event], ...],
+    rule: Rule | T_RuleChecker | None = ...,
     *,
-    permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-    handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+    permission: Permission | T_PermissionChecker | None = ...,
+    handlers: list[T_Handler | Dependent] | None = ...,
     temp: bool = ...,
-    expire_time: Optional[Union[datetime, timedelta]] = ...,
+    expire_time: datetime | timedelta | None = ...,
     priority: int = ...,
     block: bool = ...,
-    state: Optional[T_State] = ...,
-) -> Type[Matcher]: ...
+    state: T_State | None = ...,
+) -> type[Matcher]: ...
 
-class CommandGroup:
+class _Group:
+    matchers: list[type[Matcher]] = ...
+    base_kwargs: dict[str, Any] = ...
+    def _get_final_kwargs(
+        self, update: dict[str, Any], *, exclude: set[str] | None = None
+    ) -> dict[str, Any]: ...
+
+class CommandGroup(_Group):
+    basecmd: tuple[str, ...] = ...
+    prefix_aliases: bool = ...
     def __init__(
         self,
-        cmd: Union[str, Tuple[str, ...]],
+        cmd: str | tuple[str, ...],
+        prefix_aliases: bool = ...,
         *,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
+        state: T_State | None = ...,
     ): ...
     def command(
         self,
-        cmd: Union[str, Tuple[str, ...]],
+        cmd: str | tuple[str, ...],
         *,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        aliases: Optional[Set[Union[str, Tuple[str, ...]]]] = ...,
-        force_whitespace: Optional[Union[str, bool]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        aliases: set[str | tuple[str, ...]] | None = ...,
+        force_whitespace: str | bool | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...
     def shell_command(
         self,
-        cmd: Union[str, Tuple[str, ...]],
+        cmd: str | tuple[str, ...],
         *,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        aliases: Optional[Set[Union[str, Tuple[str, ...]]]] = ...,
-        parser: Optional[ArgumentParser] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        aliases: set[str | tuple[str, ...]] | None = ...,
+        parser: ArgumentParser | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...
 
-class MatcherGroup:
+class MatcherGroup(_Group):
     def __init__(
         self,
         *,
         type: str = ...,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
+        state: T_State | None = ...,
     ): ...
     def on(
         self,
         *,
         type: str = ...,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...
     def on_metaevent(
         self,
         *,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...
     def on_message(
         self,
         *,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...
     def on_notice(
         self,
         *,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...
     def on_request(
         self,
         *,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...
     def on_startswith(
         self,
-        msg: Union[str, Tuple[str, ...]],
+        msg: str | tuple[str, ...],
         *,
         ignorecase: bool = ...,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...
     def on_endswith(
         self,
-        msg: Union[str, Tuple[str, ...]],
+        msg: str | tuple[str, ...],
         *,
         ignorecase: bool = ...,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...
     def on_fullmatch(
         self,
-        msg: Union[str, Tuple[str, ...]],
+        msg: str | tuple[str, ...],
         *,
         ignorecase: bool = ...,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...
     def on_keyword(
         self,
-        keywords: Set[str],
+        keywords: set[str],
         *,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...
     def on_command(
         self,
-        cmd: Union[str, Tuple[str, ...]],
-        aliases: Optional[Set[Union[str, Tuple[str, ...]]]] = ...,
-        force_whitespace: Optional[Union[str, bool]] = ...,
+        cmd: str | tuple[str, ...],
+        aliases: set[str | tuple[str, ...]] | None = ...,
+        force_whitespace: str | bool | None = ...,
         *,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...
     def on_shell_command(
         self,
-        cmd: Union[str, Tuple[str, ...]],
-        aliases: Optional[Set[Union[str, Tuple[str, ...]]]] = ...,
-        parser: Optional[ArgumentParser] = ...,
+        cmd: str | tuple[str, ...],
+        aliases: set[str | tuple[str, ...]] | None = ...,
+        parser: ArgumentParser | None = ...,
         *,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...
     def on_regex(
         self,
         pattern: str,
-        flags: Union[int, re.RegexFlag] = ...,
+        flags: int | re.RegexFlag = ...,
         *,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...
     def on_type(
         self,
-        types: Union[Type[Event], Tuple[Type[Event]]],
+        types: type[Event] | tuple[type[Event]],
         *,
-        rule: Optional[Union[Rule, T_RuleChecker]] = ...,
-        permission: Optional[Union[Permission, T_PermissionChecker]] = ...,
-        handlers: Optional[List[Union[T_Handler, Dependent]]] = ...,
+        rule: Rule | T_RuleChecker | None = ...,
+        permission: Permission | T_PermissionChecker | None = ...,
+        handlers: list[T_Handler | Dependent] | None = ...,
         temp: bool = ...,
-        expire_time: Optional[Union[datetime, timedelta]] = ...,
+        expire_time: datetime | timedelta | None = ...,
         priority: int = ...,
         block: bool = ...,
-        state: Optional[T_State] = ...,
-    ) -> Type[Matcher]: ...
+        state: T_State | None = ...,
+    ) -> type[Matcher]: ...

nonebot/plugin/plugin.py

@@ -1,9 +1,11 @@
-"""本模块定义插件对象。
+"""本模块定义插件相关信息。
 
 FrontMatter:
     sidebar_position: 3
     description: nonebot.plugin.plugin 模块
 """
+
+import contextlib
 from types import ModuleType
 from dataclasses import field, dataclass
 from typing import TYPE_CHECKING, Any, Set, Dict, Type, Optional
@@ -11,11 +13,11 @@ from typing import TYPE_CHECKING, Any, Set, Dict, Type, Optional
 from pydantic import BaseModel
 
 from nonebot.matcher import Matcher
-
-# FIXME: backport for nonebug
-from . import _plugins as plugins  # nopycln: import
+from nonebot.utils import resolve_dot_notation
 
 if TYPE_CHECKING:
+    from nonebot.adapters import Adapter
+
     from .manager import PluginManager
 
 
@@ -24,14 +26,39 @@ class PluginMetadata:
     """插件元信息，由插件编写者提供"""
 
     name: str
-    """插件可阅读名称"""
+    """插件名称"""
     description: str
     """插件功能介绍"""
     usage: str
     """插件使用方法"""
+    type: Optional[str] = None
+    """插件类型，用于商店分类"""
+    homepage: Optional[str] = None
+    """插件主页"""
     config: Optional[Type[BaseModel]] = None
     """插件配置项"""
+    supported_adapters: Optional[Set[str]] = None
+    """插件支持的适配器模块路径
+
+    格式为 `<module>[:<Adapter>]`，`~` 为 `nonebot.adapters.` 的缩写。
+
+    `None` 表示支持**所有适配器**。
+    """
     extra: Dict[Any, Any] = field(default_factory=dict)
+    """插件额外信息，可由插件编写者自由扩展定义"""
+
+    def get_supported_adapters(self) -> Optional[Set[Type["Adapter"]]]:
+        """获取当前已安装的插件支持适配器类列表"""
+        if self.supported_adapters is None:
+            return None
+
+        adapters = set()
+        for adapter in self.supported_adapters:
+            with contextlib.suppress(ModuleNotFoundError, AttributeError):
+                adapters.add(
+                    resolve_dot_notation(adapter, "Adapter", "nonebot.adapters.")
+                )
+        return adapters
 
 
 @dataclass(eq=False)

nonebot/plugins/echo.py

@@ -1,7 +1,18 @@
+from nonebot import on_command
 from nonebot.rule import to_me
 from nonebot.adapters import Message
 from nonebot.params import CommandArg
-from nonebot.plugin import on_command
+from nonebot.plugin import PluginMetadata
+
+__plugin_meta__ = PluginMetadata(
+    name="echo",
+    description="重复你说的话",
+    usage="/echo [text]",
+    type="application",
+    homepage="https://github.com/nonebot/nonebot2/blob/master/nonebot/plugins/echo.py",
+    config=None,
+    supported_adapters=None,
+)
 
 echo = on_command("echo", to_me())
 

nonebot/plugins/single_session.py

@@ -2,8 +2,19 @@ from typing import Dict, AsyncGenerator
 
 from nonebot.adapters import Event
 from nonebot.params import Depends
+from nonebot.plugin import PluginMetadata
 from nonebot.message import IgnoredException, event_preprocessor
 
+__plugin_meta__ = PluginMetadata(
+    name="唯一会话",
+    description="限制同一会话内同时只能运行一个响应器",
+    usage="加载插件后自动生效",
+    type="application",
+    homepage="https://github.com/nonebot/nonebot2/blob/master/nonebot/plugins/single_session.py",
+    config=None,
+    supported_adapters=None,
+)
+
 _running_matcher: Dict[str, int] = {}
 
 
@@ -15,7 +26,7 @@ async def matcher_mutex(event: Event) -> AsyncGenerator[bool, None]:
         yield result
     else:
         current_event_id = id(event)
-        if event_id := _running_matcher.get(session_id, None):
+        if event_id := _running_matcher.get(session_id):
             result = event_id != current_event_id
         else:
             _running_matcher[session_id] = current_event_id

nonebot/rule.py

@@ -1,7 +1,8 @@
 """本模块是 {ref}`nonebot.matcher.Matcher.rule` 的类型定义。
 
-每个事件响应器 {ref}`nonebot.matcher.Matcher` 拥有一个匹配规则 {ref}`nonebot.rule.Rule`
-其中是 `RuleChecker` 的集合，只有当所有 `RuleChecker` 检查结果为 `True` 时继续运行。
+每个{ref}`事件响应器 <nonebot.matcher.Matcher>`拥有一个
+{ref}`nonebot.rule.Rule`，其中是 `RuleChecker` 的集合。
+只有当所有 `RuleChecker` 检查结果为 `True` 时继续运行。
 
 FrontMatter:
     sidebar_position: 5
@@ -11,6 +12,7 @@ FrontMatter:
 import re
 import shlex
 from argparse import Action
+from gettext import gettext
 from argparse import ArgumentError
 from contextvars import ContextVar
 from itertools import chain, product
@@ -43,15 +45,12 @@ from nonebot.adapters import Bot, Event, Message, MessageSegment
 from nonebot.params import Command, EventToMe, CommandArg, CommandWhitespace
 from nonebot.consts import (
     CMD_KEY,
-    REGEX_STR,
     PREFIX_KEY,
-    REGEX_DICT,
     SHELL_ARGS,
     SHELL_ARGV,
     CMD_ARG_KEY,
     KEYWORD_KEY,
     RAW_CMD_KEY,
-    REGEX_GROUP,
     ENDSWITH_KEY,
     CMD_START_KEY,
     FULLMATCH_KEY,
@@ -62,20 +61,19 @@ from nonebot.consts import (
 
 T = TypeVar("T")
 
-CMD_RESULT = TypedDict(
-    "CMD_RESULT",
-    {
-        "command": Optional[Tuple[str, ...]],
-        "raw_command": Optional[str],
-        "command_arg": Optional[Message[MessageSegment]],
-        "command_start": Optional[str],
-        "command_whitespace": Optional[str],
-    },
-)
 
-TRIE_VALUE = NamedTuple(
-    "TRIE_VALUE", [("command_start", str), ("command", Tuple[str, ...])]
-)
+class CMD_RESULT(TypedDict):
+    command: Optional[Tuple[str, ...]]
+    raw_command: Optional[str]
+    command_arg: Optional[Message]
+    command_start: Optional[str]
+    command_whitespace: Optional[str]
+
+
+class TRIE_VALUE(NamedTuple):
+    command_start: str
+    command: Tuple[str, ...]
+
 
 parser_message: ContextVar[str] = ContextVar("parser_message")
 
@@ -378,11 +376,12 @@ class CommandRule:
     async def __call__(
         self,
         cmd: Optional[Tuple[str, ...]] = Command(),
+        cmd_arg: Optional[Message] = CommandArg(),
         cmd_whitespace: Optional[str] = CommandWhitespace(),
     ) -> bool:
         if cmd not in self.cmds:
             return False
-        if self.force_whitespace is None:
+        if self.force_whitespace is None or not cmd_arg:
             return True
         if isinstance(self.force_whitespace, str):
             return self.force_whitespace == cmd_whitespace
@@ -407,7 +406,7 @@ def command(
         force_whitespace: 是否强制命令后必须有指定空白符
 
     用法:
-        使用默认 `command_start`, `command_sep` 配置
+        使用默认 `command_start`, `command_sep` 配置情况下：
 
         命令 `("test",)` 可以匹配: `/test` 开头的消息
         命令 `("test", "sub")` 可以匹配: `/test.sub` 开头的消息
@@ -442,6 +441,8 @@ def command(
 class ArgumentParser(ArgParser):
     """`shell_like` 命令参数解析器，解析出错时不会退出程序。
 
+    支持 {ref}`nonebot.adapters.Message` 富文本解析。
+
     用法:
         用法与 `argparse.ArgumentParser` 相同，
         参考文档: [argparse](https://docs.python.org/3/library/argparse.html)
@@ -450,16 +451,39 @@ class ArgumentParser(ArgParser):
     if TYPE_CHECKING:
 
         @overload
-        def parse_args(
-            self, args: Optional[Sequence[Union[str, MessageSegment]]] = ...
-        ) -> Namespace:
+        def parse_known_args(
+            self,
+            args: Optional[Sequence[Union[str, MessageSegment]]] = None,
+            namespace: None = None,
+        ) -> Tuple[Namespace, List[Union[str, MessageSegment]]]:
+            ...
+
+        @overload
+        def parse_known_args(
+            self, args: Optional[Sequence[Union[str, MessageSegment]]], namespace: T
+        ) -> Tuple[T, List[Union[str, MessageSegment]]]:
+            ...
+
+        @overload
+        def parse_known_args(
+            self, *, namespace: T
+        ) -> Tuple[T, List[Union[str, MessageSegment]]]:
+            ...
+
+        def parse_known_args(
+            self,
+            args: Optional[Sequence[Union[str, MessageSegment]]] = None,
+            namespace: Optional[T] = None,
+        ) -> Tuple[Union[Namespace, T], List[Union[str, MessageSegment]]]:
             ...
 
     @overload
     def parse_args(
-            self, args: Optional[Sequence[Union[str, MessageSegment]]], namespace: None
+        self,
+        args: Optional[Sequence[Union[str, MessageSegment]]] = None,
+        namespace: None = None,
     ) -> Namespace:
-            ...  # type: ignore[misc]
+        ...
 
     @overload
     def parse_args(
@@ -467,12 +491,20 @@ class ArgumentParser(ArgParser):
     ) -> T:
         ...
 
+    @overload
+    def parse_args(self, *, namespace: T) -> T:
+        ...
+
     def parse_args(
         self,
         args: Optional[Sequence[Union[str, MessageSegment]]] = None,
         namespace: Optional[T] = None,
     ) -> Union[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)
 
     def _parse_optional(
         self, arg_string: Union[str, MessageSegment]
@@ -558,10 +590,14 @@ def shell_command(
     根据配置里提供的 {ref}``command_start` <nonebot.config.Config.command_start>`,
     {ref}``command_sep` <nonebot.config.Config.command_sep>` 判断消息是否为命令。
 
-    可以通过 {ref}`nonebot.params.Command` 获取匹配成功的命令（例: `("test",)`），
-    通过 {ref}`nonebot.params.RawCommand` 获取匹配成功的原始命令文本（例: `"/test"`），
-    通过 {ref}`nonebot.params.ShellCommandArgv` 获取解析前的参数列表（例: `["arg", "-h"]`），
-    通过 {ref}`nonebot.params.ShellCommandArgs` 获取解析后的参数字典（例: `{"arg": "arg", "h": True}`）。
+    可以通过 {ref}`nonebot.params.Command` 获取匹配成功的命令
+    （例: `("test",)`），
+    通过 {ref}`nonebot.params.RawCommand` 获取匹配成功的原始命令文本
+    （例: `"/test"`），
+    通过 {ref}`nonebot.params.ShellCommandArgv` 获取解析前的参数列表
+    （例: `["arg", "-h"]`），
+    通过 {ref}`nonebot.params.ShellCommandArgs` 获取解析后的参数字典
+    （例: `{"arg": "arg", "h": True}`）。
 
     :::warning 警告
     如果参数解析失败，则通过 {ref}`nonebot.params.ShellCommandArgs`
@@ -573,7 +609,8 @@ def shell_command(
         parser: {ref}`nonebot.rule.ArgumentParser` 对象
 
     用法:
-        使用默认 `command_start`, `command_sep` 配置，更多示例参考 `argparse` 标准库文档。
+        使用默认 `command_start`, `command_sep` 配置，更多示例参考
+        [argparse](https://docs.python.org/3/library/argparse.html) 标准库文档。
 
         ```python
         from nonebot.rule import ArgumentParser
@@ -646,10 +683,7 @@ class RegexRule:
         except Exception:
             return False
         if matched := re.search(self.regex, str(msg), self.flags):
-            state[REGEX_MATCHED] = matched.group()
-            state[REGEX_STR] = matched.group()
-            state[REGEX_GROUP] = matched.groups()
-            state[REGEX_DICT] = matched.groupdict()
+            state[REGEX_MATCHED] = matched
             return True
         else:
             return False
@@ -671,7 +705,8 @@ def regex(regex: str, flags: Union[int, re.RegexFlag] = 0) -> Rule:
     :::
 
     :::tip 提示
-    正则表达式匹配使用 `EventMessage` 的 `str` 字符串，而非 `EventMessage` 的 `PlainText` 纯文本字符串
+    正则表达式匹配使用 `EventMessage` 的 `str` 字符串，
+    而非 `EventMessage` 的 `PlainText` 纯文本字符串
     :::
     """
 

nonebot/typing.py

@@ -1,17 +1,17 @@
 """本模块定义了 NoneBot 模块中共享的一些类型。
 
-下面的文档中，「类型」部分使用 Python 的 Type Hint 语法，
+使用 Python 的 Type Hint 语法，
 参考 [`PEP 484`](https://www.python.org/dev/peps/pep-0484/),
 [`PEP 526`](https://www.python.org/dev/peps/pep-0526/) 和
 [`typing`](https://docs.python.org/3/library/typing.html)。
 
-除了 Python 内置的类型，下面还出现了如下 NoneBot 自定类型，实际上它们是 Python 内置类型的别名。
-
 FrontMatter:
     sidebar_position: 11
     description: nonebot.typing 模块
 """
 
+import warnings
+from typing_extensions import ParamSpec, TypeAlias, override
 from typing import (
     TYPE_CHECKING,
     Any,
@@ -30,28 +30,31 @@ if TYPE_CHECKING:
     from nonebot.permission import Permission
 
 T = TypeVar("T")
+P = ParamSpec("P")
 
-T_Wrapped = TypeVar("T_Wrapped", bound=Callable)
+T_Wrapped: TypeAlias = Callable[P, T]
 
 
-def overrides(InterfaceClass: object) -> Callable[[T_Wrapped], T_Wrapped]:
+def overrides(InterfaceClass: object):
     """标记一个方法为父类 interface 的 implement"""
 
-    def overrider(func: T_Wrapped) -> T_Wrapped:
-        assert func.__name__ in dir(InterfaceClass), f"Error method: {func.__name__}"
-        return func
-
-    return overrider
+    warnings.warn(
+        "overrides is deprecated and will be removed in a future version, "
+        "use @typing_extensions.override instead. "
+        "See [PEP 698](https://peps.python.org/pep-0698/) for more details.",
+        DeprecationWarning,
+    )
+    return override
 
 
 # state
-T_State = Dict[Any, Any]
+T_State: TypeAlias = Dict[Any, Any]
 """事件处理状态 State 类型"""
 
-_DependentCallable = Union[Callable[..., T], Callable[..., Awaitable[T]]]
+_DependentCallable: TypeAlias = Union[Callable[..., T], Callable[..., Awaitable[T]]]
 
 # driver hooks
-T_BotConnectionHook = _DependentCallable[Any]
+T_BotConnectionHook: TypeAlias = _DependentCallable[Any]
 """Bot 连接建立时钩子函数
 
 依赖参数:
@@ -60,7 +63,7 @@ T_BotConnectionHook = _DependentCallable[Any]
 - BotParam: Bot 对象
 - DefaultParam: 带有默认值的参数
 """
-T_BotDisconnectionHook = _DependentCallable[Any]
+T_BotDisconnectionHook: TypeAlias = _DependentCallable[Any]
 """Bot 连接断开时钩子函数
 
 依赖参数:
@@ -71,15 +74,15 @@ T_BotDisconnectionHook = _DependentCallable[Any]
 """
 
 # api hooks
-T_CallingAPIHook = Callable[["Bot", str, Dict[str, Any]], Awaitable[Any]]
+T_CallingAPIHook: TypeAlias = Callable[["Bot", str, Dict[str, Any]], Awaitable[Any]]
 """`bot.call_api` 钩子函数"""
-T_CalledAPIHook = Callable[
+T_CalledAPIHook: TypeAlias = Callable[
     ["Bot", Optional[Exception], str, Dict[str, Any], Any], Awaitable[Any]
 ]
 """`bot.call_api` 后执行的函数，参数分别为 bot, exception, api, data, result"""
 
 # event hooks
-T_EventPreProcessor = _DependentCallable[Any]
+T_EventPreProcessor: TypeAlias = _DependentCallable[Any]
 """事件预处理函数 EventPreProcessor 类型
 
 依赖参数:
@@ -90,7 +93,7 @@ T_EventPreProcessor = _DependentCallable[Any]
 - StateParam: State 对象
 - DefaultParam: 带有默认值的参数
 """
-T_EventPostProcessor = _DependentCallable[Any]
+T_EventPostProcessor: TypeAlias = _DependentCallable[Any]
 """事件预处理函数 EventPostProcessor 类型
 
 依赖参数:
@@ -103,7 +106,7 @@ T_EventPostProcessor = _DependentCallable[Any]
 """
 
 # matcher run hooks
-T_RunPreProcessor = _DependentCallable[Any]
+T_RunPreProcessor: TypeAlias = _DependentCallable[Any]
 """事件响应器运行前预处理函数 RunPreProcessor 类型
 
 依赖参数:
@@ -115,7 +118,7 @@ T_RunPreProcessor = _DependentCallable[Any]
 - MatcherParam: Matcher 对象
 - DefaultParam: 带有默认值的参数
 """
-T_RunPostProcessor = _DependentCallable[Any]
+T_RunPostProcessor: TypeAlias = _DependentCallable[Any]
 """事件响应器运行后后处理函数 RunPostProcessor 类型
 
 依赖参数:
@@ -130,7 +133,7 @@ T_RunPostProcessor = _DependentCallable[Any]
 """
 
 # rule, permission
-T_RuleChecker = _DependentCallable[bool]
+T_RuleChecker: TypeAlias = _DependentCallable[bool]
 """RuleChecker 即判断是否响应事件的处理函数。
 
 依赖参数:
@@ -141,7 +144,7 @@ T_RuleChecker = _DependentCallable[bool]
 - StateParam: State 对象
 - DefaultParam: 带有默认值的参数
 """
-T_PermissionChecker = _DependentCallable[bool]
+T_PermissionChecker: TypeAlias = _DependentCallable[bool]
 """PermissionChecker 即判断事件是否满足权限的处理函数。
 
 依赖参数:
@@ -152,10 +155,11 @@ T_PermissionChecker = _DependentCallable[bool]
 - DefaultParam: 带有默认值的参数
 """
 
-T_Handler = _DependentCallable[Any]
+T_Handler: TypeAlias = _DependentCallable[Any]
 """Handler 处理函数。"""
-T_TypeUpdater = _DependentCallable[str]
-"""TypeUpdater 在 Matcher.pause, Matcher.reject 时被运行，用于更新响应的事件类型。默认会更新为 `message`。
+T_TypeUpdater: TypeAlias = _DependentCallable[str]
+"""TypeUpdater 在 Matcher.pause, Matcher.reject 时被运行，用于更新响应的事件类型。
+默认会更新为 `message`。
 
 依赖参数:
 
@@ -166,8 +170,9 @@ T_TypeUpdater = _DependentCallable[str]
 - MatcherParam: Matcher 对象
 - DefaultParam: 带有默认值的参数
 """
-T_PermissionUpdater = _DependentCallable["Permission"]
-"""PermissionUpdater 在 Matcher.pause, Matcher.reject 时被运行，用于更新会话对象权限。默认会更新为当前事件的触发对象。
+T_PermissionUpdater: TypeAlias = _DependentCallable["Permission"]
+"""PermissionUpdater 在 Matcher.pause, Matcher.reject 时被运行，用于更新会话对象权限。
+默认会更新为当前事件的触发对象。
 
 依赖参数:
 
@@ -178,5 +183,5 @@ T_PermissionUpdater = _DependentCallable["Permission"]
 - MatcherParam: Matcher 对象
 - DefaultParam: 带有默认值的参数
 """
-T_DependencyCache = Dict[_DependentCallable[Any], "Task[Any]"]
+T_DependencyCache: TypeAlias = Dict[_DependentCallable[Any], "Task[Any]"]
 """依赖缓存, 用于存储依赖函数的返回值"""

nonebot/utils.py

@@ -12,9 +12,10 @@ import inspect
 import importlib
 import dataclasses
 from pathlib import Path
+from contextvars import copy_context
 from functools import wraps, partial
 from contextlib import asynccontextmanager
-from typing_extensions import ParamSpec, get_args, get_origin
+from typing_extensions import ParamSpec, get_args, override, get_origin
 from typing import (
     Any,
     Type,
@@ -32,7 +33,6 @@ from typing import (
 from pydantic.typing import is_union, is_none_type
 
 from nonebot.log import logger
-from nonebot.typing import overrides
 
 P = ParamSpec("P")
 R = TypeVar("R")
@@ -57,8 +57,13 @@ def generic_check_issubclass(
 ) -> bool:
     """检查 cls 是否是 class_or_tuple 中的一个类型子类。
 
-    特别的，如果 cls 是 `typing.Union` 或 `types.UnionType` 类型，
-    则会检查其中的类型是否是 class_or_tuple 中的一个类型子类。（None 会被忽略）
+    特别的：
+
+    - 如果 cls 是 `typing.Union` 或 `types.UnionType` 类型，
+      则会检查其中的所有类型是否是 class_or_tuple 中一个类型的子类或 None。
+    - 如果 cls 是 `typing.TypeVar` 类型，
+      则会检查其 `__bound__` 或 `__constraints__`
+      是否是 class_or_tuple 中一个类型的子类或 None。
     """
     try:
         return issubclass(cls, class_or_tuple)
@@ -69,8 +74,18 @@ def generic_check_issubclass(
                 is_none_type(type_) or generic_check_issubclass(type_, class_or_tuple)
                 for type_ in get_args(cls)
             )
+        # ensure generic List, Dict can be checked
         elif origin:
             return issubclass(origin, class_or_tuple)
+        elif isinstance(cls, TypeVar):
+            if cls.__constraints__:
+                return all(
+                    is_none_type(type_)
+                    or generic_check_issubclass(type_, class_or_tuple)
+                    for type_ in cls.__constraints__
+                )
+            elif cls.__bound__:
+                return generic_check_issubclass(cls.__bound__, class_or_tuple)
         return False
 
 
@@ -111,7 +126,8 @@ def run_sync(call: Callable[P, R]) -> Callable[P, Coroutine[None, None, R]]:
     async def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
         loop = asyncio.get_running_loop()
         pfunc = partial(call, *args, **kwargs)
-        result = await loop.run_in_executor(None, pfunc)
+        context = copy_context()
+        result = await loop.run_in_executor(None, partial(context.run, pfunc))
         return result
 
     return _wrapper
@@ -136,6 +152,7 @@ async def run_sync_ctx_manager(
 async def run_coro_with_catch(
     coro: Coroutine[Any, Any, T],
     exc: Tuple[Type[Exception], ...],
+    return_on_err: None = None,
 ) -> Union[T, None]:
     ...
 
@@ -154,6 +171,17 @@ async def run_coro_with_catch(
     exc: Tuple[Type[Exception], ...],
     return_on_err: Optional[R] = None,
 ) -> Optional[Union[T, R]]:
+    """运行协程并当遇到指定异常时返回指定值。
+
+    参数:
+        coro: 要运行的协程
+        exc: 要捕获的异常
+        return_on_err: 当发生异常时返回的值
+
+    返回:
+        协程的返回值或发生异常时的指定值
+    """
+
     try:
         return await coro
     except exc:
@@ -193,9 +221,9 @@ def resolve_dot_notation(
 
 
 class DataclassEncoder(json.JSONEncoder):
-    """在JSON序列化 {re}`nonebot.adapters._message.Message` (List[Dataclass]) 时使用的 `JSONEncoder`"""
+    """可以序列化 {ref}`nonebot.adapters.Message`(List[Dataclass]) 的 `JSONEncoder`"""
 
-    @overrides(json.JSONEncoder)
+    @override
     def default(self, o):
         if dataclasses.is_dataclass(o):
             return {f.name: getattr(o, f.name) for f in dataclasses.fields(o)}
@@ -211,6 +239,8 @@ def logger_wrapper(logger_name: str):
     返回:
         日志记录函数
 
+        日志记录函数的参数:
+
         - level: 日志等级
         - message: 日志信息
         - exception: 异常信息

package.json

@@ -11,10 +11,12 @@
     "start": "yarn workspace nonebot start",
     "serve": "yarn workspace nonebot serve",
     "clear": "yarn workspace nonebot clear",
-    "prettier": "prettier --config ./.prettierrc --write \"./website/\""
+    "prettier": "prettier --config ./.prettierrc --write \"./website/\"",
+    "pyright": "pyright"
   },
   "devDependencies": {
     "cross-env": "^7.0.3",
-    "prettier": "^2.5.0"
+    "prettier": "^2.5.0",
+    "pyright": "^1.1.317"
   }
 }

packages/nonebot-plugin-docs/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="https://v2.nonebot.dev/"><img src="https://raw.githubusercontent.com/nonebot/nonebot2/master/docs/.vuepress/public/logo.png" width="200" height="200" alt="nonebot"></a>
+  <a href="https://nonebot.dev/"><img src="https://nonebot.dev/logo.png" width="200" height="200" alt="nonebot"></a>
 </p>
 
 <div align="center">
@@ -22,6 +22,6 @@ _✨ NoneBot 本地文档插件 ✨_
 
 ## 使用方式
 
-加载插件并启动 Bot ，在浏览器内打开 `http://host:port/docs/`。
+加载插件并启动 Bot ，在浏览器内打开 `http://host:port/website/`。
 
 具体网址会在控制台内输出。

packages/nonebot-plugin-docs/nonebot_plugin_docs/__init__.py

@@ -2,6 +2,17 @@ import importlib
 
 import nonebot
 from nonebot.log import logger
+from nonebot.plugin import PluginMetadata
+
+__plugin_meta__ = PluginMetadata(
+    name="NoneBot 离线文档",
+    description="在本地查看 NoneBot 文档",
+    usage="启动机器人后访问 http://localhost:port/website/ 查看文档",
+    type="application",
+    homepage="https://github.com/nonebot/nonebot2/blob/master/packages/nonebot-plugin-docs",
+    config=None,
+    supported_adapters=None,
+)
 
 
 def init():
@@ -17,7 +28,7 @@ def init():
     register_route(driver)
     host = str(driver.config.host)
     port = driver.config.port
-    if host in ["0.0.0.0", "127.0.0.1"]:
+    if host in {"0.0.0.0", "127.0.0.1"}:
         host = "localhost"
     logger.opt(colors=True).info(
         f"Nonebot docs will be running at: "

packages/nonebot-plugin-docs/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "nonebot-plugin-docs"
-version = "2.0.0-beta.1"
+version = "2.0.0"
 description = "View NoneBot2 Docs Locally"
 authors = ["yanyongyu <yyy@nonebot.dev>"]
 license = "MIT"
@@ -13,7 +13,7 @@ include = ["nonebot_plugin_docs/dist/**/*"]
 
 [tool.poetry.dependencies]
 python = "^3.8"
-nonebot2 = "^2.0.0-beta.1"
+nonebot2 = "^2.0.0"
 
 [tool.poetry.dev-dependencies]
 

pyproject.toml

@@ -1,13 +1,13 @@
 [tool.poetry]
 name = "nonebot2"
-version = "2.0.0rc4"
+version = "2.0.1"
 description = "An asynchronous python bot framework."
 authors = ["yanyongyu <yyy@nonebot.dev>"]
 license = "MIT"
 readme = "README.md"
-homepage = "https://v2.nonebot.dev/"
+homepage = "https://nonebot.dev/"
 repository = "https://github.com/nonebot/nonebot2"
-documentation = "https://v2.nonebot.dev/"
+documentation = "https://nonebot.dev/"
 keywords = ["bot", "qq", "qqbot", "mirai", "coolq"]
 classifiers = [
   "Development Status :: 5 - Production/Stable",
@@ -21,16 +21,21 @@ packages = [
 ]
 include = ["nonebot/py.typed"]
 
+[tool.poetry.urls]
+"Bug Tracker" = "https://github.com/nonebot/nonebot2/issues"
+"Changelog" = "https://nonebot.dev/changelog"
+"Funding" = "https://afdian.net/@nonebot"
+
 [tool.poetry.dependencies]
 python = "^3.8"
 yarl = "^1.7.2"
-loguru = "^0.6.0"
 pygtrie = "^2.4.1"
+loguru = ">=0.6.0,<1.0.0"
 typing-extensions = ">=4.0.0,<5.0.0"
 tomli = { version = "^2.0.1", python = "<3.11" }
 pydantic = { version = "^1.10.0", extras = ["dotenv"] }
 
-websockets = { version = "^10.0", optional = true }
+websockets = { version = ">=10.0", optional = true }
 Quart = { version = ">=0.18.0,<1.0.0", optional = true }
 fastapi = { version = ">=0.93.0,<1.0.0", optional = true }
 aiohttp = { version = "^3.7.4", extras = ["speedups"], optional = true }
@@ -38,18 +43,19 @@ httpx = { version = ">=0.20.0,<1.0.0", extras = ["http2"], optional = true }
 uvicorn = { version = ">=0.20.0,<1.0.0", extras = ["standard"], optional = true }
 
 [tool.poetry.group.dev.dependencies]
-pycln = "^2.1.2"
 isort = "^5.10.1"
 black = "^23.1.0"
 nonemoji = "^0.1.2"
 pre-commit = "^3.0.0"
+ruff = ">=0.0.272,<1.0.0"
 
 [tool.poetry.group.test.dependencies]
 nonebug = "^0.3.0"
+werkzeug = "^2.3.6"
 pytest-cov = "^4.0.0"
 pytest-xdist = "^3.0.2"
 pytest-asyncio = "^0.21.0"
-coverage-conditional-plugin = "^0.8.0"
+coverage-conditional-plugin = "^0.9.0"
 
 [tool.poetry.group.docs.dependencies]
 nb-autodoc = "^1.0.0a5"
@@ -63,7 +69,7 @@ fastapi = ["fastapi", "uvicorn"]
 all = ["fastapi", "quart", "aiohttp", "httpx", "websockets", "uvicorn"]
 
 [tool.pytest.ini_options]
-asyncio_mode = "auto"
+asyncio_mode = "strict"
 addopts = "--cov=nonebot --cov-append --cov-report=term-missing"
 filterwarnings = [
     "error",
@@ -86,12 +92,18 @@ force_sort_within_sections = true
 src_paths = ["nonebot", "tests"]
 extra_standard_library = ["typing_extensions"]
 
-[tool.pycln]
-path = "."
-all = false
+[tool.ruff]
+select = ["E", "W", "F", "UP", "C", "T", "PYI", "PT", "Q"]
+ignore = ["E402", "C901"]
+
+line-length = 88
+target-version = "py38"
+
+[tool.ruff.flake8-pytest-style]
+fixture-parentheses = false
+mark-parentheses = false
 
 [tool.pyright]
-reportShadowedImports = false
 pythonVersion = "3.8"
 pythonPlatform = "All"
 executionEnvironments = [
@@ -99,6 +111,9 @@ executionEnvironments = [
   { root = "./" },
 ]
 
+typeCheckingMode = "basic"
+reportShadowedImports = false
+
 
 [build-system]
 requires = ["poetry_core>=1.0.0"]

tests/.env.test

@@ -1,6 +1,8 @@
 LOG_LEVEL=TRACE
 NICKNAME=["test"]
 SUPERUSERS=["test", "fake:faketest"]
+API_TIMEOUT
+SIMPLE_NONE
 COMMON_OVERRIDE=new
 CONFIG_FROM_ENV=
 CONFIG_OVERRIDE=old

tests/conftest.py

@@ -1,11 +1,15 @@
 import os
+import threading
 from pathlib import Path
-from typing import TYPE_CHECKING, Set
+from typing import TYPE_CHECKING, Set, Generator
 
 import pytest
 from nonebug import NONEBOT_INIT_KWARGS
+from werkzeug.serving import BaseWSGIServer, make_server
 
 import nonebot
+from nonebot.drivers import URL
+from fake_server import request_handler
 
 os.environ["CONFIG_FROM_ENV"] = '{"test": "test"}'
 os.environ["CONFIG_OVERRIDE"] = "new"
@@ -25,6 +29,23 @@ def load_plugin(nonebug_init: None) -> Set["Plugin"]:
 
 
 @pytest.fixture(scope="session", autouse=True)
-def load_example(nonebug_init: None) -> Set["Plugin"]:
-    # preload example plugins
-    return nonebot.load_plugins(str(Path(__file__).parent / "examples"))
+def load_builtin_plugin(nonebug_init: None) -> Set["Plugin"]:
+    # preload builtin plugins
+    return nonebot.load_builtin_plugins("echo", "single_session")
+
+
+@pytest.fixture(scope="session", autouse=True)
+def server() -> Generator[BaseWSGIServer, None, None]:
+    server = make_server("127.0.0.1", 0, app=request_handler)
+    thread = threading.Thread(target=server.serve_forever)
+    thread.start()
+    try:
+        yield server
+    finally:
+        server.shutdown()
+        thread.join()
+
+
+@pytest.fixture(scope="session")
+def server_url(server: BaseWSGIServer) -> URL:
+    return URL(f"http://{server.host}:{server.port}")

tests/examples/weather.py

@@ -1,29 +0,0 @@
-from nonebot import on_command
-from nonebot.rule import to_me
-from nonebot.matcher import Matcher
-from nonebot.adapters import Message
-from nonebot.params import Arg, CommandArg, ArgPlainText
-
-weather = on_command("weather", rule=to_me(), aliases={"天气", "天气预报"}, priority=5)
-
-
-@weather.handle()
-async def handle_first_receive(matcher: Matcher, args: Message = CommandArg()):
-    plain_text = args.extract_plain_text()  # 首次发送命令时跟随的参数，例：/天气 上海，则args为上海
-    if plain_text:
-        matcher.set_arg("city", args)  # 如果用户发送了参数则直接赋值
-
-
-@weather.got("city", prompt="你想查询哪个城市的天气呢？")
-async def handle_city(city: Message = Arg(), city_name: str = ArgPlainText("city")):
-    if city_name not in ["北京", "上海"]:  # 如果参数不符合要求，则提示用户重新输入
-        # 可以使用平台的 Message 类直接构造模板消息
-        await weather.reject(city.template("你想查询的城市 {city} 暂不支持，请重新输入！"))
-
-    city_weather = await get_weather(city_name)
-    await weather.finish(city_weather)
-
-
-# 在这里编写获取天气信息的函数
-async def get_weather(city: str) -> str:
-    return f"{city}的天气是..."

tests/fake_server.py

@@ -0,0 +1,69 @@
+import json
+import base64
+from typing import Dict, List, Union, TypeVar
+
+from werkzeug import Request, Response
+from werkzeug.datastructures import MultiDict
+
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+def json_safe(string, content_type="application/octet-stream") -> str:
+    try:
+        string = string.decode("utf-8")
+        json.dumps(string)
+        return string
+    except (ValueError, TypeError):
+        return b"".join(
+            [
+                b"data:",
+                content_type.encode("utf-8"),
+                b";base64,",
+                base64.b64encode(string),
+            ]
+        ).decode("utf-8")
+
+
+def flattern(d: "MultiDict[K, V]") -> Dict[K, Union[V, List[V]]]:
+    return {k: v[0] if len(v) == 1 else v for k, v in d.to_dict(flat=False).items()}
+
+
+@Request.application
+def request_handler(request: Request) -> Response:
+    try:
+        _json = json.loads(request.data.decode("utf-8"))
+    except (ValueError, TypeError):
+        _json = None
+
+    return Response(
+        json.dumps(
+            {
+                "url": request.url,
+                "method": request.method,
+                "origin": request.headers.get("X-Forwarded-For", request.remote_addr),
+                "headers": flattern(
+                    MultiDict((k, v) for k, v in request.headers.items())
+                ),
+                "args": flattern(request.args),
+                "form": flattern(request.form),
+                "data": json_safe(request.data),
+                "json": _json,
+                "files": flattern(
+                    MultiDict(
+                        (
+                            k,
+                            json_safe(
+                                v.read(),
+                                request.files[k].content_type
+                                or "application/octet-stream",
+                            ),
+                        )
+                        for k, v in request.files.items()
+                    )
+                ),
+            }
+        ),
+        status=200,
+        content_type="application/json",
+    )

tests/plugins/_hidden.py

@@ -1 +1,3 @@
-assert False
+import pytest
+
+pytest.fail("should not be imported")

tests/plugins/matcher/matcher_permission.py

@@ -2,6 +2,7 @@ from nonebot.matcher import Matcher
 from nonebot.permission import USER, Permission
 
 default_permission = Permission()
+new_permission = Permission()
 
 test_permission_updater = Matcher.new(permission=default_permission)
 
@@ -14,4 +15,4 @@ test_custom_updater = Matcher.new(permission=default_permission)
 
 @test_custom_updater.permission_updater
 async def _() -> Permission:
-    return default_permission
+    return new_permission

tests/plugins/metadata.py

@@ -1,5 +1,6 @@
 from pydantic import BaseModel
 
+from nonebot.adapters import Adapter
 from nonebot.plugin import PluginMetadata
 
 
@@ -7,10 +8,17 @@ class Config(BaseModel):
     custom: str = ""
 
 
+class FakeAdapter(Adapter):
+    ...
+
+
 __plugin_meta__ = PluginMetadata(
     name="测试插件",
     description="测试插件元信息",
     usage="无法使用",
+    type="application",
+    homepage="https://nonebot.dev",
     config=Config,
+    supported_adapters={"~onebot.v11", "plugins.metadata:FakeAdapter"},
     extra={"author": "NoneBot"},
 )

tests/plugins/metadata_2.py

@@ -0,0 +1,11 @@
+from nonebot.plugin import PluginMetadata
+
+__plugin_meta__ = PluginMetadata(
+    name="测试插件2",
+    description="测试继承适配器",
+    usage="无法使用",
+    type="application",
+    homepage="https://nonebot.dev",
+    supported_adapters={"~onebot.v11", "~onebot.v12"},
+    extra={"author": "NoneBot"},
+)

tests/plugins/nested/__init__.py

@@ -1,6 +1,5 @@
 from pathlib import Path
 
-import nonebot
 from nonebot.plugin import PluginManager, _managers
 
 manager = PluginManager(

tests/plugins/nested/plugins/nested_subplugin.py

@@ -1 +1 @@
-from .nested_subplugin2 import a  # nopycln: import
+from .nested_subplugin2 import a  # noqa: F401

tests/plugins/param/param_arg.py

@@ -1,4 +1,6 @@
-from nonebot.adapters import Event, Message
+from typing_extensions import Annotated
+
+from nonebot.adapters import Message
 from nonebot.params import Arg, ArgStr, ArgPlainText
 
 
@@ -12,3 +14,15 @@ async def arg_str(key: str = ArgStr()) -> str:
 
 async def arg_plain_text(key: str = ArgPlainText()) -> str:
     return key
+
+
+async def annotated_arg(key: Annotated[Message, Arg()]) -> Message:
+    return key
+
+
+async def annotated_arg_str(key: Annotated[str, ArgStr()]) -> str:
+    return key
+
+
+async def annotated_arg_plain_text(key: Annotated[str, ArgPlainText()]) -> str:
+    return key

tests/plugins/param/param_bot.py

@@ -1,4 +1,4 @@
-from typing import Union
+from typing import Union, TypeVar
 
 from nonebot.adapters import Bot
 
@@ -31,5 +31,19 @@ async def union_bot(b: Union[FooBot, BarBot]) -> Union[FooBot, BarBot]:
     return b
 
 
+B = TypeVar("B", bound=Bot)
+
+
+async def generic_bot(b: B) -> B:
+    return b
+
+
+CB = TypeVar("CB", Bot, None)
+
+
+async def generic_bot_none(b: CB) -> CB:
+    return b
+
+
 async def not_bot(b: Union[int, Bot]):
     ...

tests/plugins/param/param_event.py

@@ -1,4 +1,4 @@
-from typing import Union
+from typing import Union, TypeVar
 
 from nonebot.adapters import Event, Message
 from nonebot.params import EventToMe, EventType, EventMessage, EventPlainText
@@ -32,6 +32,20 @@ async def union_event(e: Union[FooEvent, BarEvent]) -> Union[FooEvent, BarEvent]
     return e
 
 
+E = TypeVar("E", bound=Event)
+
+
+async def generic_event(e: E) -> E:
+    return e
+
+
+CE = TypeVar("CE", Event, None)
+
+
+async def generic_event_none(e: CE) -> CE:
+    return e
+
+
 async def not_event(e: Union[int, Event]):
     ...
 

tests/plugins/param/param_matcher.py

@@ -1,3 +1,5 @@
+from typing import Union, TypeVar
+
 from nonebot.adapters import Event
 from nonebot.matcher import Matcher
 from nonebot.params import Received, LastReceived
@@ -7,6 +9,50 @@ async def matcher(m: Matcher) -> Matcher:
     return m
 
 
+async def legacy_matcher(matcher):
+    return matcher
+
+
+async def not_legacy_matcher(matcher: int):
+    ...
+
+
+class FooMatcher(Matcher):
+    ...
+
+
+async def sub_matcher(m: FooMatcher) -> FooMatcher:
+    return m
+
+
+class BarMatcher(Matcher):
+    ...
+
+
+async def union_matcher(
+    m: Union[FooMatcher, BarMatcher]
+) -> Union[FooMatcher, BarMatcher]:
+    return m
+
+
+M = TypeVar("M", bound=Matcher)
+
+
+async def generic_matcher(m: M) -> M:
+    return m
+
+
+CM = TypeVar("CM", Matcher, None)
+
+
+async def generic_matcher_none(m: CM) -> CM:
+    return m
+
+
+async def not_matcher(m: Union[int, Matcher]):
+    ...
+
+
 async def receive(e: Event = Received("test")) -> Event:
     return e
 

tests/plugins/param/param_state.py

@@ -1,4 +1,4 @@
-from typing import List, Tuple
+from typing import List, Match, Tuple
 
 from nonebot.typing import T_State
 from nonebot.adapters import Message
@@ -73,12 +73,12 @@ async def regex_group(regex_group: Tuple = RegexGroup()) -> Tuple:
     return regex_group
 
 
-async def regex_matched(regex_matched: str = RegexMatched()) -> str:
+async def regex_matched(regex_matched: Match[str] = RegexMatched()) -> Match[str]:
     return regex_matched
 
 
-async def regex_str(regex_matched: str = RegexStr()) -> str:
-    return regex_matched
+async def regex_str(regex_str: str = RegexStr()) -> str:
+    return regex_str
 
 
 async def startswith(startswith: str = Startswith()) -> str:

tests/plugins/param/priority.py

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

tests/plugins/plugin/__init__.py

@@ -1 +1 @@
-from . import matchers
+from . import matchers as matchers

tests/plugins/plugin/matchers.py

@@ -220,7 +220,7 @@ matcher_on_type = on_type(
 
 
 cmd_group = CommandGroup(
-    "test",
+    "prefix",
     rule=rule,
     permission=permission,
     handlers=[handler],
@@ -230,8 +230,30 @@ cmd_group = CommandGroup(
     block=True,
     state=state,
 )
-matcher_sub_cmd = cmd_group.command("sub")
-matcher_sub_shell_cmd = cmd_group.shell_command("sub")
+matcher_prefix_cmd = cmd_group.command("sub", aliases={"help", ("help", "foo")})
+matcher_prefix_shell_cmd = cmd_group.shell_command(
+    "sub", aliases={"help", ("help", "foo")}
+)
+
+
+cmd_group_prefix_aliases = CommandGroup(
+    "prefix",
+    prefix_aliases=True,
+    rule=rule,
+    permission=permission,
+    handlers=[handler],
+    temp=True,
+    expire_time=expire_time,
+    priority=priority,
+    block=True,
+    state=state,
+)
+matcher_prefix_aliases_cmd = cmd_group_prefix_aliases.command(
+    "sub", aliases={"help", ("help", "foo")}
+)
+matcher_prefix_aliases_shell_cmd = cmd_group_prefix_aliases.shell_command(
+    "sub", aliases={"help", ("help", "foo")}
+)
 
 
 matcher_group = MatcherGroup(

tests/plugins/require.py

@@ -4,4 +4,5 @@ test_require = require("export").test
 
 from plugins.export import test
 
-assert test is test_require and test() == "export", "Export Require Error"
+assert test is test_require, "Export Require Error"
+assert test() == "export", "Export Require Error"

tests/test_adapters/test_message.py

@@ -1,115 +1,136 @@
 import pytest
 from pydantic import ValidationError, parse_obj_as
 
-from utils import make_fake_message
+from nonebot.adapters import Message
+from utils import FakeMessage, FakeMessageSegment
 
 
-def test_segment_add():
-    Message = make_fake_message()
-    MessageSegment = Message.get_segment_class()
-
-    assert MessageSegment.text("text") + MessageSegment.text("text") == Message(
-        [MessageSegment.text("text"), MessageSegment.text("text")]
-    )
-
-    assert MessageSegment.text("text") + "text" == Message(
-        [MessageSegment.text("text"), MessageSegment.text("text")]
-    )
-
-    assert (
-        MessageSegment.text("text") + Message([MessageSegment.text("text")])
-    ) == Message([MessageSegment.text("text"), MessageSegment.text("text")])
-
-    assert "text" + MessageSegment.text("text") == Message(
-        [MessageSegment.text("text"), MessageSegment.text("text")]
-    )
-
-
-def test_segment_validate():
-    Message = make_fake_message()
-    MessageSegment = Message.get_segment_class()
-
-    assert parse_obj_as(
-        MessageSegment,
-        {"type": "text", "data": {"text": "text"}, "extra": "should be ignored"},
-    ) == MessageSegment.text("text")
-
-    with pytest.raises(ValidationError):
-        parse_obj_as(MessageSegment, "some str")
-
-    with pytest.raises(ValidationError):
-        parse_obj_as(MessageSegment, {"data": {}})
-
-
-def test_segment():
-    Message = make_fake_message()
-    MessageSegment = Message.get_segment_class()
-
-    assert len(MessageSegment.text("text")) == 4
-    assert MessageSegment.text("text") != MessageSegment.text("other")
-    assert MessageSegment.text("text").get("data") == {"text": "text"}
-    assert list(MessageSegment.text("text").keys()) == ["type", "data"]
-    assert list(MessageSegment.text("text").values()) == ["text", {"text": "text"}]
-    assert list(MessageSegment.text("text").items()) == [
+def test_segment_data():
+    assert len(FakeMessageSegment.text("text")) == 4
+    assert FakeMessageSegment.text("text").get("data") == {"text": "text"}
+    assert list(FakeMessageSegment.text("text").keys()) == ["type", "data"]
+    assert list(FakeMessageSegment.text("text").values()) == ["text", {"text": "text"}]
+    assert list(FakeMessageSegment.text("text").items()) == [
         ("type", "text"),
         ("data", {"text": "text"}),
     ]
 
-    origin = MessageSegment.text("text")
+
+def test_segment_equal():
+    assert FakeMessageSegment("text", {"text": "text"}) == FakeMessageSegment(
+        "text", {"text": "text"}
+    )
+    assert FakeMessageSegment("text", {"text": "text"}) != FakeMessageSegment(
+        "text", {"text": "other"}
+    )
+    assert FakeMessageSegment("text", {"text": "text"}) != FakeMessageSegment(
+        "other", {"text": "text"}
+    )
+
+
+def test_segment_add():
+    assert FakeMessageSegment.text("text") + FakeMessageSegment.text(
+        "text"
+    ) == FakeMessage([FakeMessageSegment.text("text"), FakeMessageSegment.text("text")])
+
+    assert FakeMessageSegment.text("text") + "text" == FakeMessage(
+        [FakeMessageSegment.text("text"), FakeMessageSegment.text("text")]
+    )
+
+    assert (
+        FakeMessageSegment.text("text") + FakeMessage([FakeMessageSegment.text("text")])
+    ) == FakeMessage([FakeMessageSegment.text("text"), FakeMessageSegment.text("text")])
+
+    assert "text" + FakeMessageSegment.text("text") == FakeMessage(
+        [FakeMessageSegment.text("text"), FakeMessageSegment.text("text")]
+    )
+
+
+def test_segment_validate():
+    assert parse_obj_as(
+        FakeMessageSegment,
+        {"type": "text", "data": {"text": "text"}, "extra": "should be ignored"},
+    ) == FakeMessageSegment.text("text")
+
+    with pytest.raises(ValidationError):
+        parse_obj_as(FakeMessageSegment, "some str")
+
+    with pytest.raises(ValidationError):
+        parse_obj_as(FakeMessageSegment, {"data": {}})
+
+
+def test_segment_join():
+    seg = FakeMessageSegment.text("test")
+    iterable = [
+        FakeMessageSegment.text("first"),
+        FakeMessage(
+            [FakeMessageSegment.text("second"), FakeMessageSegment.text("third")]
+        ),
+    ]
+
+    assert seg.join(iterable) == FakeMessage(
+        [
+            FakeMessageSegment.text("first"),
+            FakeMessageSegment.text("test"),
+            FakeMessageSegment.text("second"),
+            FakeMessageSegment.text("third"),
+        ]
+    )
+
+
+def test_segment_copy():
+    origin = FakeMessageSegment.text("text")
     copy = origin.copy()
     assert origin is not copy
     assert origin == copy
 
 
 def test_message_add():
-    Message = make_fake_message()
-    MessageSegment = Message.get_segment_class()
-
     assert (
-        Message([MessageSegment.text("text")]) + MessageSegment.text("text")
-    ) == Message([MessageSegment.text("text"), MessageSegment.text("text")])
+        FakeMessage([FakeMessageSegment.text("text")]) + FakeMessageSegment.text("text")
+    ) == FakeMessage([FakeMessageSegment.text("text"), FakeMessageSegment.text("text")])
 
-    assert Message([MessageSegment.text("text")]) + "text" == Message(
-        [MessageSegment.text("text"), MessageSegment.text("text")]
+    assert FakeMessage([FakeMessageSegment.text("text")]) + "text" == FakeMessage(
+        [FakeMessageSegment.text("text"), FakeMessageSegment.text("text")]
     )
 
     assert (
-        Message([MessageSegment.text("text")]) + Message([MessageSegment.text("text")])
-    ) == Message([MessageSegment.text("text"), MessageSegment.text("text")])
+        FakeMessage([FakeMessageSegment.text("text")])
+        + FakeMessage([FakeMessageSegment.text("text")])
+    ) == FakeMessage([FakeMessageSegment.text("text"), FakeMessageSegment.text("text")])
 
-    assert "text" + Message([MessageSegment.text("text")]) == Message(
-        [MessageSegment.text("text"), MessageSegment.text("text")]
+    assert "text" + FakeMessage([FakeMessageSegment.text("text")]) == FakeMessage(
+        [FakeMessageSegment.text("text"), FakeMessageSegment.text("text")]
     )
 
-    msg = Message([MessageSegment.text("text")])
-    msg += MessageSegment.text("text")
-    assert msg == Message([MessageSegment.text("text"), MessageSegment.text("text")])
+    msg = FakeMessage([FakeMessageSegment.text("text")])
+    msg += FakeMessageSegment.text("text")
+    assert msg == FakeMessage(
+        [FakeMessageSegment.text("text"), FakeMessageSegment.text("text")]
+    )
 
 
 def test_message_getitem():
-    Message = make_fake_message()
-    MessageSegment = Message.get_segment_class()
-
-    message = Message(
+    message = FakeMessage(
         [
-            MessageSegment.text("test"),
-            MessageSegment.image("test2"),
-            MessageSegment.image("test3"),
-            MessageSegment.text("test4"),
+            FakeMessageSegment.text("test"),
+            FakeMessageSegment.image("test2"),
+            FakeMessageSegment.image("test3"),
+            FakeMessageSegment.text("test4"),
         ]
     )
 
-    assert message[0] == MessageSegment.text("test")
+    assert message[0] == FakeMessageSegment.text("test")
 
-    assert message[:2] == Message(
-        [MessageSegment.text("test"), MessageSegment.image("test2")]
+    assert message[:2] == FakeMessage(
+        [FakeMessageSegment.text("test"), FakeMessageSegment.image("test2")]
     )
 
-    assert message["image"] == Message(
-        [MessageSegment.image("test2"), MessageSegment.image("test3")]
+    assert message["image"] == FakeMessage(
+        [FakeMessageSegment.image("test2"), FakeMessageSegment.image("test3")]
     )
 
-    assert message["image", 0] == MessageSegment.image("test2")
+    assert message["image", 0] == FakeMessageSegment.image("test2")
     assert message["image", 0:2] == message["image"]
 
     assert message.index(message[0]) == 0
@@ -117,32 +138,137 @@ def test_message_getitem():
 
     assert message.get("image") == message["image"]
     assert message.get("image", 114514) == message["image"]
-    assert message.get("image", 1) == Message([message["image", 0]])
+    assert message.get("image", 1) == FakeMessage([message["image", 0]])
 
     assert message.count("image") == 2
 
 
 def test_message_validate():
-    Message = make_fake_message()
-    MessageSegment = Message.get_segment_class()
-
-    Message_ = make_fake_message()
-
-    assert parse_obj_as(Message, Message([])) == Message([])
+    assert parse_obj_as(FakeMessage, FakeMessage([])) == FakeMessage([])
 
     with pytest.raises(ValidationError):
-        parse_obj_as(Message, Message_([]))
+        parse_obj_as(type("FakeMessage2", (Message,), {}), FakeMessage([]))
 
-    assert parse_obj_as(Message, "text") == Message([MessageSegment.text("text")])
-
-    assert parse_obj_as(Message, {"type": "text", "data": {"text": "text"}}) == Message(
-        [MessageSegment.text("text")]
+    assert parse_obj_as(FakeMessage, "text") == FakeMessage(
+        [FakeMessageSegment.text("text")]
     )
 
     assert parse_obj_as(
-        Message,
-        [MessageSegment.text("text"), {"type": "text", "data": {"text": "text"}}],
-    ) == Message([MessageSegment.text("text"), MessageSegment.text("text")])
+        FakeMessage, {"type": "text", "data": {"text": "text"}}
+    ) == FakeMessage([FakeMessageSegment.text("text")])
+
+    assert parse_obj_as(
+        FakeMessage,
+        [FakeMessageSegment.text("text"), {"type": "text", "data": {"text": "text"}}],
+    ) == FakeMessage([FakeMessageSegment.text("text"), FakeMessageSegment.text("text")])
 
     with pytest.raises(ValidationError):
-        parse_obj_as(Message, object())
+        parse_obj_as(FakeMessage, object())
+
+
+def test_message_contains():
+    message = FakeMessage(
+        [
+            FakeMessageSegment.text("test"),
+            FakeMessageSegment.image("test2"),
+            FakeMessageSegment.image("test3"),
+            FakeMessageSegment.text("test4"),
+        ]
+    )
+
+    assert message.has(FakeMessageSegment.text("test")) is True
+    assert FakeMessageSegment.text("test") in message
+    assert message.has("image") is True
+    assert "image" in message
+
+    assert message.has(FakeMessageSegment.text("foo")) is False
+    assert FakeMessageSegment.text("foo") not in message
+    assert message.has("foo") is False
+    assert "foo" not in message
+
+
+def test_message_only():
+    message = FakeMessage(
+        [
+            FakeMessageSegment.text("test"),
+            FakeMessageSegment.text("test2"),
+        ]
+    )
+
+    assert message.only("text") is True
+    assert message.only(FakeMessageSegment.text("test")) is False
+
+    message = FakeMessage(
+        [
+            FakeMessageSegment.text("test"),
+            FakeMessageSegment.image("test2"),
+            FakeMessageSegment.image("test3"),
+            FakeMessageSegment.text("test4"),
+        ]
+    )
+
+    assert message.only("text") is False
+
+    message = FakeMessage(
+        [
+            FakeMessageSegment.text("test"),
+            FakeMessageSegment.text("test"),
+        ]
+    )
+
+    assert message.only(FakeMessageSegment.text("test")) is True
+
+
+def test_message_join():
+    msg = FakeMessage([FakeMessageSegment.text("test")])
+    iterable = [
+        FakeMessageSegment.text("first"),
+        FakeMessage(
+            [FakeMessageSegment.text("second"), FakeMessageSegment.text("third")]
+        ),
+    ]
+
+    assert msg.join(iterable) == FakeMessage(
+        [
+            FakeMessageSegment.text("first"),
+            FakeMessageSegment.text("test"),
+            FakeMessageSegment.text("second"),
+            FakeMessageSegment.text("third"),
+        ]
+    )
+
+
+def test_message_include():
+    message = FakeMessage(
+        [
+            FakeMessageSegment.text("test"),
+            FakeMessageSegment.image("test2"),
+            FakeMessageSegment.image("test3"),
+            FakeMessageSegment.text("test4"),
+        ]
+    )
+
+    assert message.include("text") == FakeMessage(
+        [
+            FakeMessageSegment.text("test"),
+            FakeMessageSegment.text("test4"),
+        ]
+    )
+
+
+def test_message_exclude():
+    message = FakeMessage(
+        [
+            FakeMessageSegment.text("test"),
+            FakeMessageSegment.image("test2"),
+            FakeMessageSegment.image("test3"),
+            FakeMessageSegment.text("test4"),
+        ]
+    )
+
+    assert message.exclude("image") == FakeMessage(
+        [
+            FakeMessageSegment.text("test"),
+            FakeMessageSegment.text("test4"),
+        ]
+    )

tests/test_adapters/test_template.py

@@ -1,5 +1,5 @@
 from nonebot.adapters import MessageTemplate
-from utils import escape_text, make_fake_message
+from utils import FakeMessage, FakeMessageSegment, escape_text
 
 
 def test_template_basis():
@@ -9,8 +9,7 @@ def test_template_basis():
 
 
 def test_template_message():
-    Message = make_fake_message()
-    template = Message.template("{a:custom}{b:text}{c:image}/{d}")
+    template = FakeMessage.template("{a:custom}{b:text}{c:image}/{d}")
 
     @template.add_format_spec
     def custom(input: str) -> str:
@@ -37,29 +36,24 @@ def test_template_message():
 
 
 def test_rich_template_message():
-    Message = make_fake_message()
-    MS = Message.get_segment_class()
-
     pic1, pic2, pic3 = (
-        MS.image("file:///pic1.jpg"),
-        MS.image("file:///pic2.jpg"),
-        MS.image("file:///pic3.jpg"),
+        FakeMessageSegment.image("file:///pic1.jpg"),
+        FakeMessageSegment.image("file:///pic2.jpg"),
+        FakeMessageSegment.image("file:///pic3.jpg"),
     )
 
-    template = Message.template("{}{}" + pic2 + "{}")
+    template = FakeMessage.template("{}{}" + pic2 + "{}")
 
     result = template.format(pic1, "[fake:image]", pic3)
 
-    assert result["image"] == Message([pic1, pic2, pic3])
+    assert result["image"] == FakeMessage([pic1, pic2, pic3])
     assert str(result) == (
         "[fake:image]" + escape_text("[fake:image]") + "[fake:image]" + "[fake:image]"
     )
 
 
 def test_message_injection():
-    Message = make_fake_message()
-
-    template = Message.template("{name}Is Bad")
+    template = FakeMessage.template("{name}Is Bad")
     message = template.format(name="[fake:image]")
 
     assert message.extract_plain_text() == escape_text("[fake:image]Is Bad")

tests/test_broadcast.py

@@ -0,0 +1,388 @@
+import sys
+from typing import Optional
+
+import pytest
+from nonebug import App
+
+from nonebot import on_message
+import nonebot.message as message
+from utils import make_fake_event
+from nonebot.params import Depends
+from nonebot.typing import T_State
+from nonebot.matcher import Matcher
+from nonebot.adapters import Bot, Event
+from nonebot.exception import IgnoredException
+from nonebot.log import logger, default_filter, default_format
+from nonebot.message import (
+    run_preprocessor,
+    run_postprocessor,
+    event_preprocessor,
+    event_postprocessor,
+)
+
+
+async def _dependency() -> int:
+    return 1
+
+
+@pytest.mark.asyncio
+async def test_event_preprocessor(app: App, monkeypatch: pytest.MonkeyPatch):
+    with monkeypatch.context() as m:
+        m.setattr(message, "_event_preprocessors", set())
+
+        runned = False
+
+        @event_preprocessor
+        async def test_preprocessor(
+            bot: Bot,
+            event: Event,
+            state: T_State,
+            sub: int = Depends(_dependency),
+            default: int = 1,
+        ):
+            nonlocal runned
+            runned = True
+
+        assert test_preprocessor in {
+            dependent.call for dependent in message._event_preprocessors
+        }
+
+        with app.provider.context({}):
+            matcher = on_message()
+
+            async with app.test_matcher(matcher) as ctx:
+                bot = ctx.create_bot()
+                event = make_fake_event()()
+                ctx.receive_event(bot, event)
+
+        assert runned, "event_preprocessor should runned"
+
+
+@pytest.mark.asyncio
+async def test_event_preprocessor_ignore(app: App, monkeypatch: pytest.MonkeyPatch):
+    with monkeypatch.context() as m:
+        m.setattr(message, "_event_preprocessors", set())
+
+        @event_preprocessor
+        async def test_preprocessor():
+            raise IgnoredException("pass")
+
+        assert test_preprocessor in {
+            dependent.call for dependent in message._event_preprocessors
+        }
+
+        runned = False
+
+        async def handler():
+            nonlocal runned
+            runned = True
+
+        with app.provider.context({}):
+            matcher = on_message(handlers=[handler])
+
+            async with app.test_matcher(matcher) as ctx:
+                bot = ctx.create_bot()
+                event = make_fake_event()()
+                ctx.receive_event(bot, event)
+
+        assert not runned, "matcher should not runned"
+
+
+@pytest.mark.asyncio
+async def test_event_preprocessor_exception(
+    app: App, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+):
+    with monkeypatch.context() as m:
+        m.setattr(message, "_event_preprocessors", set())
+
+        @event_preprocessor
+        async def test_preprocessor():
+            raise RuntimeError("test")
+
+        assert test_preprocessor in {
+            dependent.call for dependent in message._event_preprocessors
+        }
+
+        runned = False
+
+        async def handler():
+            nonlocal runned
+            runned = True
+
+        handler_id = logger.add(
+            sys.stdout,
+            level=0,
+            diagnose=False,
+            filter=default_filter,
+            format=default_format,
+        )
+
+        try:
+            with app.provider.context({}):
+                matcher = on_message(handlers=[handler])
+
+                async with app.test_matcher(matcher) as ctx:
+                    bot = ctx.create_bot()
+                    event = make_fake_event()()
+                    ctx.receive_event(bot, event)
+        finally:
+            logger.remove(handler_id)
+
+        assert not runned, "matcher should not runned"
+        assert "RuntimeError: test" in capsys.readouterr().out
+
+
+@pytest.mark.asyncio
+async def test_event_postprocessor(app: App, monkeypatch: pytest.MonkeyPatch):
+    with monkeypatch.context() as m:
+        m.setattr(message, "_event_postprocessors", set())
+
+        runned = False
+
+        @event_postprocessor
+        async def test_postprocessor(
+            bot: Bot,
+            event: Event,
+            state: T_State,
+            sub: int = Depends(_dependency),
+            default: int = 1,
+        ):
+            nonlocal runned
+            runned = True
+
+        assert test_postprocessor in {
+            dependent.call for dependent in message._event_postprocessors
+        }
+
+        with app.provider.context({}):
+            matcher = on_message()
+
+            async with app.test_matcher(matcher) as ctx:
+                bot = ctx.create_bot()
+                event = make_fake_event()()
+                ctx.receive_event(bot, event)
+
+        assert runned, "event_postprocessor should runned"
+
+
+@pytest.mark.asyncio
+async def test_event_postprocessor_exception(
+    app: App, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+):
+    with monkeypatch.context() as m:
+        m.setattr(message, "_event_postprocessors", set())
+
+        @event_postprocessor
+        async def test_postprocessor():
+            raise RuntimeError("test")
+
+        assert test_postprocessor in {
+            dependent.call for dependent in message._event_postprocessors
+        }
+
+        handler_id = logger.add(
+            sys.stdout,
+            level=0,
+            diagnose=False,
+            filter=default_filter,
+            format=default_format,
+        )
+
+        try:
+            with app.provider.context({}):
+                matcher = on_message()
+
+                async with app.test_matcher(matcher) as ctx:
+                    bot = ctx.create_bot()
+                    event = make_fake_event()()
+                    ctx.receive_event(bot, event)
+        finally:
+            logger.remove(handler_id)
+
+        assert "RuntimeError: test" in capsys.readouterr().out
+
+
+@pytest.mark.asyncio
+async def test_run_preprocessor(app: App, monkeypatch: pytest.MonkeyPatch):
+    with monkeypatch.context() as m:
+        m.setattr(message, "_run_preprocessors", set())
+
+        runned = False
+
+        @run_preprocessor
+        async def test_preprocessor(
+            bot: Bot,
+            event: Event,
+            state: T_State,
+            matcher: Matcher,
+            sub: int = Depends(_dependency),
+            default: int = 1,
+        ):
+            nonlocal runned
+            runned = True
+
+            await matcher.send("test")
+
+        assert test_preprocessor in {
+            dependent.call for dependent in message._run_preprocessors
+        }
+
+        with app.provider.context({}):
+            matcher = on_message()
+
+            async with app.test_matcher(matcher) as ctx:
+                bot = ctx.create_bot()
+                event = make_fake_event()()
+                ctx.receive_event(bot, event)
+                ctx.should_call_send(event, "test", True, bot=bot)
+
+        assert runned, "run_preprocessor should runned"
+
+
+@pytest.mark.asyncio
+async def test_run_preprocessor_ignore(app: App, monkeypatch: pytest.MonkeyPatch):
+    with monkeypatch.context() as m:
+        m.setattr(message, "_run_preprocessors", set())
+
+        @run_preprocessor
+        async def test_preprocessor():
+            raise IgnoredException("pass")
+
+        assert test_preprocessor in {
+            dependent.call for dependent in message._run_preprocessors
+        }
+
+        runned = False
+
+        async def handler():
+            nonlocal runned
+            runned = True
+
+        with app.provider.context({}):
+            matcher = on_message(handlers=[handler])
+
+            async with app.test_matcher(matcher) as ctx:
+                bot = ctx.create_bot()
+                event = make_fake_event()()
+                ctx.receive_event(bot, event)
+
+        assert not runned, "matcher should not runned"
+
+
+@pytest.mark.asyncio
+async def test_run_preprocessor_exception(
+    app: App, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+):
+    with monkeypatch.context() as m:
+        m.setattr(message, "_run_preprocessors", set())
+
+        @run_preprocessor
+        async def test_preprocessor():
+            raise RuntimeError("test")
+
+        assert test_preprocessor in {
+            dependent.call for dependent in message._run_preprocessors
+        }
+
+        runned = False
+
+        async def handler():
+            nonlocal runned
+            runned = True
+
+        handler_id = logger.add(
+            sys.stdout,
+            level=0,
+            diagnose=False,
+            filter=default_filter,
+            format=default_format,
+        )
+
+        try:
+            with app.provider.context({}):
+                matcher = on_message(handlers=[handler])
+
+                async with app.test_matcher(matcher) as ctx:
+                    bot = ctx.create_bot()
+                    event = make_fake_event()()
+                    ctx.receive_event(bot, event)
+        finally:
+            logger.remove(handler_id)
+
+        assert not runned, "matcher should not runned"
+        assert "RuntimeError: test" in capsys.readouterr().out
+
+
+@pytest.mark.asyncio
+async def test_run_postprocessor(app: App, monkeypatch: pytest.MonkeyPatch):
+    with monkeypatch.context() as m:
+        m.setattr(message, "_run_postprocessors", set())
+
+        runned = False
+
+        @run_postprocessor
+        async def test_postprocessor(
+            bot: Bot,
+            event: Event,
+            state: T_State,
+            matcher: Matcher,
+            exception: Optional[Exception],
+            sub: int = Depends(_dependency),
+            default: int = 1,
+        ):
+            nonlocal runned
+            runned = True
+
+            await matcher.send("test")
+
+        assert test_postprocessor in {
+            dependent.call for dependent in message._run_postprocessors
+        }
+
+        with app.provider.context({}):
+            matcher = on_message()
+
+            async with app.test_matcher(matcher) as ctx:
+                bot = ctx.create_bot()
+                event = make_fake_event()()
+                ctx.receive_event(bot, event)
+                ctx.should_call_send(event, "test", True, bot=bot)
+
+        assert runned, "run_postprocessor should runned"
+
+
+@pytest.mark.asyncio
+async def test_run_postprocessor_exception(
+    app: App, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+):
+    with monkeypatch.context() as m:
+        m.setattr(message, "_run_postprocessors", set())
+
+        @run_postprocessor
+        async def test_postprocessor():
+            raise RuntimeError("test")
+
+        assert test_postprocessor in {
+            dependent.call for dependent in message._run_postprocessors
+        }
+
+        handler_id = logger.add(
+            sys.stdout,
+            level=0,
+            diagnose=False,
+            filter=default_filter,
+            format=default_format,
+        )
+
+        try:
+            with app.provider.context({}):
+                matcher = on_message()
+
+                async with app.test_matcher(matcher) as ctx:
+                    bot = ctx.create_bot()
+                    event = make_fake_event()()
+                    ctx.receive_event(bot, event)
+        finally:
+            logger.remove(handler_id)
+
+        assert "RuntimeError: test" in capsys.readouterr().out

tests/test_driver.py

@@ -1,6 +1,6 @@
 import json
 import asyncio
-from typing import Any, Set, cast
+from typing import Any, Set, Optional, cast
 
 import pytest
 from nonebug import App
@@ -79,13 +79,37 @@ async def test_lifespan():
     ],
     indirect=True,
 )
-async def test_reverse_driver(app: App, driver: Driver):
+async def test_http_server(app: App, driver: Driver):
     driver = cast(ReverseDriver, driver)
 
     async def _handle_http(request: Request) -> Response:
         assert request.content in (b"test", "test")
         return Response(200, content="test")
 
+    http_setup = HTTPServerSetup(URL("/http_test"), "POST", "http_test", _handle_http)
+    driver.setup_http_server(http_setup)
+
+    async with app.test_server(driver.asgi) as ctx:
+        client = ctx.get_client()
+        response = await client.post("/http_test", data="test")
+        assert response.status_code == 200
+        assert response.text == "test"
+
+    await asyncio.sleep(1)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "driver",
+    [
+        pytest.param("nonebot.drivers.fastapi:Driver", id="fastapi"),
+        pytest.param("nonebot.drivers.quart:Driver", id="quart"),
+    ],
+    indirect=True,
+)
+async def test_websocket_server(app: App, driver: Driver):
+    driver = cast(ReverseDriver, driver)
+
     async def _handle_ws(ws: WebSocket) -> None:
         await ws.accept()
         data = await ws.receive()
@@ -107,17 +131,11 @@ async def test_reverse_driver(app: App, driver: Driver):
         with pytest.raises(WebSocketClosed):
             await ws.receive()
 
-    http_setup = HTTPServerSetup(URL("/http_test"), "POST", "http_test", _handle_http)
-    driver.setup_http_server(http_setup)
-
     ws_setup = WebSocketServerSetup(URL("/ws_test"), "ws_test", _handle_ws)
     driver.setup_websocket_server(ws_setup)
 
     async with app.test_server(driver.asgi) as ctx:
         client = ctx.get_client()
-        response = await client.post("/http_test", data="test")
-        assert response.status_code == 200
-        assert response.text == "test"
 
         async with client.websocket_connect("/ws_test") as ws:
             await ws.send_text("ping")
@@ -136,6 +154,63 @@ async def test_reverse_driver(app: App, driver: Driver):
     await asyncio.sleep(1)
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "driver",
+    [
+        pytest.param("nonebot.drivers.fastapi:Driver", id="fastapi"),
+        pytest.param("nonebot.drivers.quart:Driver", id="quart"),
+    ],
+    indirect=True,
+)
+async def test_cross_context(app: App, driver: Driver):
+    driver = cast(ReverseDriver, driver)
+
+    ws: Optional[WebSocket] = None
+    ws_ready = asyncio.Event()
+    ws_should_close = asyncio.Event()
+
+    async def background_task():
+        try:
+            await ws_ready.wait()
+            assert ws is not None
+
+            await ws.send("ping")
+            data = await ws.receive()
+            assert data == "pong"
+        finally:
+            ws_should_close.set()
+
+    task = asyncio.create_task(background_task())
+
+    async def _handle_ws(websocket: WebSocket) -> None:
+        nonlocal ws
+        await websocket.accept()
+        ws = websocket
+        ws_ready.set()
+
+        await ws_should_close.wait()
+        await websocket.close()
+
+    ws_setup = WebSocketServerSetup(URL("/ws_test"), "ws_test", _handle_ws)
+    driver.setup_websocket_server(ws_setup)
+
+    async with app.test_server(driver.asgi) as ctx:
+        client = ctx.get_client()
+
+        async with client.websocket_connect("/ws_test") as websocket:
+            try:
+                data = await websocket.receive_text()
+                assert data == "ping"
+                await websocket.send_text("pong")
+            except Exception as e:
+                if not e.args or "websocket.close" not in str(e.args[0]):
+                    raise
+
+    await task
+    await asyncio.sleep(1)
+
+
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
     "driver",
@@ -145,43 +220,59 @@ async def test_reverse_driver(app: App, driver: Driver):
     ],
     indirect=True,
 )
-async def test_http_driver(driver: Driver):
+async def test_http_client(driver: Driver, server_url: URL):
     driver = cast(ForwardDriver, driver)
 
+    # simple post with query, headers, cookies and content
     request = Request(
         "POST",
-        "https://httpbin.org/post",
+        server_url,
         params={"param": "test"},
         headers={"X-Test": "test"},
         cookies={"session": "test"},
         content="test",
     )
     response = await driver.request(request)
-    assert response.status_code == 200 and response.content
+    assert response.status_code == 200
+    assert response.content
     data = json.loads(response.content)
+    assert data["method"] == "POST"
     assert data["args"] == {"param": "test"}
     assert data["headers"].get("X-Test") == "test"
     assert data["headers"].get("Cookie") == "session=test"
     assert data["data"] == "test"
 
-    request = Request("POST", "https://httpbin.org/post", data={"form": "test"})
+    # post with data body
+    request = Request("POST", server_url, data={"form": "test"})
     response = await driver.request(request)
-    assert response.status_code == 200 and response.content
+    assert response.status_code == 200
+    assert response.content
     data = json.loads(response.content)
+    assert data["method"] == "POST"
     assert data["form"] == {"form": "test"}
 
-    request = Request("POST", "https://httpbin.org/post", json={"json": "test"})
+    # post with json body
+    request = Request("POST", server_url, json={"json": "test"})
     response = await driver.request(request)
-    assert response.status_code == 200 and response.content
+    assert response.status_code == 200
+    assert response.content
     data = json.loads(response.content)
+    assert data["method"] == "POST"
     assert data["json"] == {"json": "test"}
 
+    # post with files and form data
     request = Request(
-        "POST", "https://httpbin.org/post", files={"test": ("test.txt", b"test")}
+        "POST",
+        server_url,
+        data={"form": "test"},
+        files={"test": ("test.txt", b"test")},
     )
     response = await driver.request(request)
-    assert response.status_code == 200 and response.content
+    assert response.status_code == 200
+    assert response.content
     data = json.loads(response.content)
+    assert data["method"] == "POST"
+    assert data["form"] == {"form": "test"}
     assert data["files"] == {"test": "test"}
 
     await asyncio.sleep(1)
@@ -189,7 +280,7 @@ async def test_http_driver(driver: Driver):
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    "driver, driver_type",
+    ("driver", "driver_type"),
     [
         pytest.param(
             "nonebot.drivers.fastapi:Driver+nonebot.drivers.aiohttp:Mixin",
@@ -232,7 +323,6 @@ async def test_bot_connect_hook(app: App, driver: Driver):
         @driver.on_bot_connect
         async def conn_hook(foo: Bot, dep: int = Depends(dependency), default: int = 1):
             nonlocal conn_should_be_called
-            conn_should_be_called = True
 
             if foo is not bot:
                 pytest.fail("on_bot_connect hook called with wrong bot")
@@ -241,12 +331,13 @@ async def test_bot_connect_hook(app: App, driver: Driver):
             if default != 1:
                 pytest.fail("on_bot_connect hook called with wrong default value")
 
+            conn_should_be_called = True
+
         @driver.on_bot_disconnect
         async def disconn_hook(
             foo: Bot, dep: int = Depends(dependency), default: int = 1
         ):
             nonlocal disconn_should_be_called
-            disconn_should_be_called = True
 
             if foo is not bot:
                 pytest.fail("on_bot_disconnect hook called with wrong bot")
@@ -255,6 +346,8 @@ async def test_bot_connect_hook(app: App, driver: Driver):
             if default != 1:
                 pytest.fail("on_bot_connect hook called with wrong default value")
 
+            disconn_should_be_called = True
+
         if conn_hook not in {hook.call for hook in conn_hooks}:
             pytest.fail("on_bot_connect hook not registered")
         if disconn_hook not in {hook.call for hook in disconn_hooks}:
@@ -264,6 +357,7 @@ async def test_bot_connect_hook(app: App, driver: Driver):
             bot = ctx.create_bot()
 
         await asyncio.sleep(1)
+
         if not conn_should_be_called:
             pytest.fail("on_bot_connect hook not called")
         if not disconn_should_be_called:

tests/test_examples/test_weather.py

@@ -1,76 +0,0 @@
-import pytest
-from nonebug import App
-
-from utils import make_fake_event, make_fake_message
-
-
-@pytest.mark.asyncio
-async def test_weather(app: App):
-    from examples.weather import weather
-
-    # 将此处的 make_fake_message() 替换为你要发送的平台消息 Message 类型
-    # from nonebot.adapters.console import Message
-    Message = make_fake_message()
-
-    async with app.test_matcher(weather) as ctx:
-        bot = ctx.create_bot()
-
-        msg = Message("/天气 上海")
-        # 将此处的 make_fake_event() 替换为你要发送的平台事件 Event 类型
-        # from nonebot.adapters.console import MessageEvent
-        # event = MessageEvent(message=msg, to_me=True, ...)
-        event = make_fake_event(_message=msg, _to_me=True)()
-
-        ctx.receive_event(bot, event)
-        ctx.should_call_send(event, "上海的天气是...", True)
-        ctx.should_finished()
-
-    async with app.test_matcher(weather) as ctx:
-        bot = ctx.create_bot()
-
-        msg = Message("/天气 南京")
-        # 将此处的 make_fake_event() 替换为你要发送的平台事件 Event 类型
-        event = make_fake_event(_message=msg, _to_me=True)()
-
-        ctx.receive_event(bot, event)
-        ctx.should_call_send(
-            event,
-            Message.template("你想查询的城市 {} 暂不支持，请重新输入！").format("南京"),
-            True,
-        )
-        ctx.should_rejected()
-
-        msg = Message("北京")
-        event = make_fake_event(_message=msg)()
-
-        ctx.receive_event(bot, event)
-        ctx.should_call_send(event, "北京的天气是...", True)
-        ctx.should_finished()
-
-    async with app.test_matcher(weather) as ctx:
-        bot = ctx.create_bot()
-
-        msg = Message("/天气")
-        # 将此处的 make_fake_event() 替换为你要发送的平台事件 Event 类型
-        event = make_fake_event(_message=msg, _to_me=True)()
-
-        ctx.receive_event(bot, event)
-        ctx.should_call_send(event, "你想查询哪个城市的天气呢？", True)
-
-        msg = Message("杭州")
-        event = make_fake_event(_message=msg)()
-
-        ctx.receive_event(bot, event)
-        ctx.should_call_send(
-            event,
-            Message.template("你想查询的城市 {} 暂不支持，请重新输入！").format("杭州"),
-            True,
-        )
-        ctx.should_rejected()
-
-        msg = Message("北京")
-        event = make_fake_event(_message=msg)()
-
-        ctx.receive_event(bot, event)
-        ctx.should_call_send(event, "北京的天气是...", True)
-        ctx.should_finished()

tests/test_init.py

@@ -20,6 +20,11 @@ async def test_init():
     assert env == "test"
 
     config = nonebot.get_driver().config
+    assert config.nickname == {"test"}
+    assert config.superusers == {"test", "fake:faketest"}
+    assert config.api_timeout is None
+
+    assert config.simple_none is None
     assert config.config_from_env == {"test": "test"}
     assert config.config_override == "new"
     assert config.config_from_init == "init"
@@ -31,17 +36,29 @@ async def test_init():
 
 
 @pytest.mark.asyncio
-async def test_get(app: App, monkeypatch: pytest.MonkeyPatch):
+async def test_get_driver(app: App, monkeypatch: pytest.MonkeyPatch):
     with monkeypatch.context() as m:
         m.setattr(nonebot, "_driver", None)
-        with pytest.raises(ValueError):
+        with pytest.raises(ValueError, match="initialized"):
             get_driver()
 
+
+@pytest.mark.asyncio
+async def test_get_asgi(app: App, monkeypatch: pytest.MonkeyPatch):
     driver = get_driver()
     assert isinstance(driver, ReverseDriver)
     assert get_asgi() == driver.asgi
+
+
+@pytest.mark.asyncio
+async def test_get_app(app: App, monkeypatch: pytest.MonkeyPatch):
+    driver = get_driver()
+    assert isinstance(driver, ReverseDriver)
     assert get_app() == driver.server_app
 
+
+@pytest.mark.asyncio
+async def test_get_adapter(app: App, monkeypatch: pytest.MonkeyPatch):
     async with app.test_api() as ctx:
         adapter = ctx.create_adapter()
         adapter_name = adapter.get_name()
@@ -51,24 +68,38 @@ async def test_get(app: App, monkeypatch: pytest.MonkeyPatch):
             assert get_adapters() == {adapter_name: adapter}
             assert get_adapter(adapter_name) is adapter
             assert get_adapter(adapter.__class__) is adapter
-            with pytest.raises(ValueError):
+            with pytest.raises(ValueError, match="registered"):
                 get_adapter("not exist")
 
+
+@pytest.mark.asyncio
+async def test_run(app: App, monkeypatch: pytest.MonkeyPatch):
     runned = False
 
     def mock_run(*args, **kwargs):
         nonlocal runned
         runned = True
-        assert args == ("arg",) and kwargs == {"kwarg": "kwarg"}
+        assert args == ("arg",)
+        assert kwargs == {"kwarg": "kwarg"}
 
-    monkeypatch.setattr(driver, "run", mock_run)
+    driver = get_driver()
+
+    with monkeypatch.context() as m:
+        m.setattr(driver, "run", mock_run)
         nonebot.run("arg", kwarg="kwarg")
+
     assert runned
 
-    with pytest.raises(ValueError):
+
+@pytest.mark.asyncio
+async def test_get_bot(app: App, monkeypatch: pytest.MonkeyPatch):
+    driver = get_driver()
+
+    with pytest.raises(ValueError, match="no bots"):
         get_bot()
 
-    monkeypatch.setattr(driver, "_bots", {"test": "test"})
+    with monkeypatch.context() as m:
+        m.setattr(driver, "_bots", {"test": "test"})
         assert get_bot() == "test"
         assert get_bot("test") == "test"
         assert get_bots() == {"test": "test"}

tests/test_matcher/test_matcher.py

@@ -2,26 +2,17 @@ import pytest
 from nonebug import App
 
 from nonebot.permission import User
-from nonebot.message import _check_matcher
 from nonebot.matcher import Matcher, matchers
-from utils import make_fake_event, make_fake_message
+from utils import FakeMessage, make_fake_event
+from nonebot.message import check_and_run_matcher
 
 
 @pytest.mark.asyncio
-async def test_matcher(app: App):
-    from plugins.matcher.matcher_process import (
-        test_got,
-        test_handle,
-        test_preset,
-        test_combine,
-        test_receive,
-        test_overload,
-    )
+async def test_matcher_handle(app: App):
+    from plugins.matcher.matcher_process import test_handle
 
-    message = make_fake_message()("text")
+    message = FakeMessage("text")
     event = make_fake_event(_message=message)()
-    message_next = make_fake_message()("text_next")
-    event_next = make_fake_event(_message=message_next)()
 
     assert len(test_handle.handlers) == 1
     async with app.test_matcher(test_handle) as ctx:
@@ -30,6 +21,16 @@ async def test_matcher(app: App):
         ctx.should_call_send(event, "send", "result", at_sender=True)
         ctx.should_finished()
 
+
+@pytest.mark.asyncio
+async def test_matcher_got(app: App):
+    from plugins.matcher.matcher_process import test_got
+
+    message = FakeMessage("text")
+    event = make_fake_event(_message=message)()
+    message_next = FakeMessage("text_next")
+    event_next = make_fake_event(_message=message_next)()
+
     assert len(test_got.handlers) == 1
     async with app.test_matcher(test_got) as ctx:
         bot = ctx.create_bot()
@@ -42,6 +43,14 @@ async def test_matcher(app: App):
         ctx.should_rejected()
         ctx.receive_event(bot, event_next)
 
+
+@pytest.mark.asyncio
+async def test_matcher_receive(app: App):
+    from plugins.matcher.matcher_process import test_receive
+
+    message = FakeMessage("text")
+    event = make_fake_event(_message=message)()
+
     assert len(test_receive.handlers) == 1
     async with app.test_matcher(test_receive) as ctx:
         bot = ctx.create_bot()
@@ -51,7 +60,17 @@ async def test_matcher(app: App):
         ctx.should_call_send(event, "pause", "result", at_sender=True)
         ctx.should_paused()
 
-    assert len(test_receive.handlers) == 1
+
+@pytest.mark.asyncio
+async def test_matcher_(app: App):
+    from plugins.matcher.matcher_process import test_combine
+
+    message = FakeMessage("text")
+    event = make_fake_event(_message=message)()
+    message_next = FakeMessage("text_next")
+    event_next = make_fake_event(_message=message_next)()
+
+    assert len(test_combine.handlers) == 1
     async with app.test_matcher(test_combine) as ctx:
         bot = ctx.create_bot()
         ctx.receive_event(bot, event)
@@ -64,6 +83,16 @@ async def test_matcher(app: App):
         ctx.should_rejected()
         ctx.receive_event(bot, event_next)
 
+
+@pytest.mark.asyncio
+async def test_matcher_preset(app: App):
+    from plugins.matcher.matcher_process import test_preset
+
+    message = FakeMessage("text")
+    event = make_fake_event(_message=message)()
+    message_next = FakeMessage("text_next")
+    event_next = make_fake_event(_message=message_next)()
+
     assert len(test_preset.handlers) == 2
     async with app.test_matcher(test_preset) as ctx:
         bot = ctx.create_bot()
@@ -72,6 +101,14 @@ async def test_matcher(app: App):
         ctx.should_rejected()
         ctx.receive_event(bot, event_next)
 
+
+@pytest.mark.asyncio
+async def test_matcher_overload(app: App):
+    from plugins.matcher.matcher_process import test_overload
+
+    message = FakeMessage("text")
+    event = make_fake_event(_message=message)()
+
     assert len(test_overload.handlers) == 2
     async with app.test_matcher(test_overload) as ctx:
         bot = ctx.create_bot()
@@ -83,7 +120,7 @@ async def test_matcher(app: App):
 async def test_matcher_destroy(app: App):
     from plugins.matcher.matcher_process import test_destroy
 
-    async with app.test_matcher(test_destroy) as ctx:
+    async with app.test_matcher(test_destroy):
         assert len(matchers) == 1
         assert len(matchers[test_destroy.priority]) == 1
         assert matchers[test_destroy.priority][0] is test_destroy
@@ -115,12 +152,10 @@ async def test_type_updater(app: App):
 
 
 @pytest.mark.asyncio
-async def test_permission_updater(app: App):
+async def test_default_permission_updater(app: App):
     from plugins.matcher.matcher_permission import (
         default_permission,
-        test_custom_updater,
         test_permission_updater,
-        test_user_permission_updater,
     )
 
     event = make_fake_event(_session_id="test")()
@@ -136,6 +171,15 @@ async def test_permission_updater(app: App):
         assert checker.users == ("test",)
         assert checker.perm is default_permission
 
+
+@pytest.mark.asyncio
+async def test_user_permission_updater(app: App):
+    from plugins.matcher.matcher_permission import (
+        default_permission,
+        test_user_permission_updater,
+    )
+
+    event = make_fake_event(_session_id="test")()
     user_permission = list(test_user_permission_updater.permission.checkers)[0].call
     assert isinstance(user_permission, User)
     assert user_permission.perm is default_permission
@@ -149,12 +193,22 @@ async def test_permission_updater(app: App):
         assert checker.users == ("test",)
         assert checker.perm is default_permission
 
+
+@pytest.mark.asyncio
+async def test_custom_permission_updater(app: App):
+    from plugins.matcher.matcher_permission import (
+        new_permission,
+        default_permission,
+        test_custom_updater,
+    )
+
+    event = make_fake_event(_session_id="test")()
     assert test_custom_updater.permission is default_permission
     async with app.test_api() as ctx:
         bot = ctx.create_bot()
         matcher = test_custom_updater()
         new_perm = await matcher.update_permission(bot, event)
-        assert new_perm is default_permission
+        assert new_perm is new_permission
 
 
 @pytest.mark.asyncio
@@ -189,30 +243,36 @@ async def test_run(app: App):
 
 
 @pytest.mark.asyncio
-async def test_expire(app: App):
-    from plugins.matcher.matcher_expire import (
-        test_temp_matcher,
-        test_datetime_matcher,
-        test_timedelta_matcher,
-    )
+async def test_temp(app: App):
+    from plugins.matcher.matcher_expire import test_temp_matcher
 
     event = make_fake_event(_type="test")()
     async with app.test_api() as ctx:
         bot = ctx.create_bot()
         assert test_temp_matcher in matchers[test_temp_matcher.priority]
-        await _check_matcher(test_temp_matcher, bot, event, {})
+        await check_and_run_matcher(test_temp_matcher, bot, event, {})
         assert test_temp_matcher not in matchers[test_temp_matcher.priority]
 
+
+@pytest.mark.asyncio
+async def test_datetime_expire(app: App):
+    from plugins.matcher.matcher_expire import test_datetime_matcher
+
     event = make_fake_event()()
     async with app.test_api() as ctx:
         bot = ctx.create_bot()
         assert test_datetime_matcher in matchers[test_datetime_matcher.priority]
-        await _check_matcher(test_datetime_matcher, bot, event, {})
+        await check_and_run_matcher(test_datetime_matcher, bot, event, {})
         assert test_datetime_matcher not in matchers[test_datetime_matcher.priority]
 
+
+@pytest.mark.asyncio
+async def test_timedelta_expire(app: App):
+    from plugins.matcher.matcher_expire import test_timedelta_matcher
+
     event = make_fake_event()()
     async with app.test_api() as ctx:
         bot = ctx.create_bot()
         assert test_timedelta_matcher in matchers[test_timedelta_matcher.priority]
-        await _check_matcher(test_timedelta_matcher, bot, event, {})
+        await check_and_run_matcher(test_timedelta_matcher, bot, event, {})
         assert test_timedelta_matcher not in matchers[test_timedelta_matcher.priority]

tests/test_param.py

@@ -1,9 +1,12 @@
+import re
+
 import pytest
 from nonebug import App
 
 from nonebot.matcher import Matcher
+from nonebot.dependencies import Dependent
 from nonebot.exception import TypeMisMatch
-from utils import make_fake_event, make_fake_message
+from utils import FakeMessage, make_fake_event
 from nonebot.params import (
     ArgParam,
     BotParam,
@@ -16,15 +19,12 @@ from nonebot.params import (
 )
 from nonebot.consts import (
     CMD_KEY,
-    REGEX_STR,
     PREFIX_KEY,
-    REGEX_DICT,
     SHELL_ARGS,
     SHELL_ARGV,
     CMD_ARG_KEY,
     KEYWORD_KEY,
     RAW_CMD_KEY,
-    REGEX_GROUP,
     ENDSWITH_KEY,
     CMD_START_KEY,
     FULLMATCH_KEY,
@@ -33,6 +33,8 @@ from nonebot.consts import (
     CMD_WHITESPACE_KEY,
 )
 
+UNKNOWN_PARAM = "Unknown parameter"
+
 
 @pytest.mark.asyncio
 async def test_depend(app: App):
@@ -50,7 +52,8 @@ async def test_depend(app: App):
     async with app.test_dependent(depends, allow_types=[DependParam]) as ctx:
         ctx.should_return(1)
 
-    assert len(runned) == 1 and runned[0] == 1
+    assert len(runned) == 1
+    assert runned[0] == 1
 
     runned.clear()
 
@@ -59,7 +62,8 @@ async def test_depend(app: App):
         event_next = make_fake_event()()
         ctx.receive_event(bot, event_next)
 
-    assert len(runned) == 2 and runned[0] == runned[1] == 1
+    assert len(runned) == 2
+    assert runned[0] == runned[1] == 1
 
     runned.clear()
 
@@ -90,7 +94,9 @@ async def test_bot(app: App):
         sub_bot,
         union_bot,
         legacy_bot,
+        generic_bot,
         not_legacy_bot,
+        generic_bot_none,
     )
 
     async with app.test_dependent(get_bot, allow_types=[BotParam]) as ctx:
@@ -103,16 +109,15 @@ async def test_bot(app: App):
         ctx.pass_params(bot=bot)
         ctx.should_return(bot)
 
-    with pytest.raises(ValueError):
-        async with app.test_dependent(not_legacy_bot, allow_types=[BotParam]) as ctx:
-            ...
+    with pytest.raises(ValueError, match=UNKNOWN_PARAM):
+        app.test_dependent(not_legacy_bot, allow_types=[BotParam])
 
     async with app.test_dependent(sub_bot, allow_types=[BotParam]) as ctx:
         bot = ctx.create_bot(base=FooBot)
         ctx.pass_params(bot=bot)
         ctx.should_return(bot)
 
-    with pytest.raises(TypeMisMatch):
+    with pytest.raises(TypeMisMatch):  # noqa: PT012
         async with app.test_dependent(sub_bot, allow_types=[BotParam]) as ctx:
             bot = ctx.create_bot()
             ctx.pass_params(bot=bot)
@@ -122,9 +127,18 @@ async def test_bot(app: App):
         ctx.pass_params(bot=bot)
         ctx.should_return(bot)
 
-    with pytest.raises(ValueError):
-        async with app.test_dependent(not_bot, allow_types=[BotParam]) as ctx:
-            ...
+    async with app.test_dependent(generic_bot, allow_types=[BotParam]) as ctx:
+        bot = ctx.create_bot()
+        ctx.pass_params(bot=bot)
+        ctx.should_return(bot)
+
+    async with app.test_dependent(generic_bot_none, allow_types=[BotParam]) as ctx:
+        bot = ctx.create_bot()
+        ctx.pass_params(bot=bot)
+        ctx.should_return(bot)
+
+    with pytest.raises(ValueError, match=UNKNOWN_PARAM):
+        app.test_dependent(not_bot, allow_types=[BotParam])
 
 
 @pytest.mark.asyncio
@@ -139,11 +153,13 @@ async def test_event(app: App):
         union_event,
         legacy_event,
         event_message,
+        generic_event,
         event_plain_text,
         not_legacy_event,
+        generic_event_none,
     )
 
-    fake_message = make_fake_message()("text")
+    fake_message = FakeMessage("text")
     fake_event = make_fake_event(_message=fake_message)()
     fake_fooevent = make_fake_event(_base=FooEvent)()
 
@@ -155,17 +171,14 @@ async def test_event(app: App):
         ctx.pass_params(event=fake_event)
         ctx.should_return(fake_event)
 
-    with pytest.raises(ValueError):
-        async with app.test_dependent(
-            not_legacy_event, allow_types=[EventParam]
-        ) as ctx:
-            ...
+    with pytest.raises(ValueError, match=UNKNOWN_PARAM):
+        app.test_dependent(not_legacy_event, allow_types=[EventParam])
 
     async with app.test_dependent(sub_event, allow_types=[EventParam]) as ctx:
         ctx.pass_params(event=fake_fooevent)
         ctx.should_return(fake_fooevent)
 
-    with pytest.raises(TypeMisMatch):
+    with pytest.raises(TypeMisMatch):  # noqa: PT012
         async with app.test_dependent(sub_event, allow_types=[EventParam]) as ctx:
             ctx.pass_params(event=fake_event)
 
@@ -173,9 +186,16 @@ async def test_event(app: App):
         ctx.pass_params(event=fake_fooevent)
         ctx.should_return(fake_event)
 
-    with pytest.raises(ValueError):
-        async with app.test_dependent(not_event, allow_types=[EventParam]) as ctx:
-            ...
+    async with app.test_dependent(generic_event, allow_types=[EventParam]) as ctx:
+        ctx.pass_params(event=fake_event)
+        ctx.should_return(fake_event)
+
+    async with app.test_dependent(generic_event_none, allow_types=[EventParam]) as ctx:
+        ctx.pass_params(event=fake_event)
+        ctx.should_return(fake_event)
+
+    with pytest.raises(ValueError, match=UNKNOWN_PARAM):
+        app.test_dependent(not_event, allow_types=[EventParam])
 
     async with app.test_dependent(
         event_type, allow_types=[EventParam, DependParam]
@@ -225,7 +245,8 @@ async def test_state(app: App):
         shell_command_argv,
     )
 
-    fake_message = make_fake_message()("text")
+    fake_message = FakeMessage("text")
+    fake_matched = re.match(r"\[cq:(?P<type>.*?),(?P<arg>.*?)\]", "[cq:test,arg=value]")
     fake_state = {
         PREFIX_KEY: {
             CMD_KEY: ("cmd",),
@@ -236,10 +257,7 @@ async def test_state(app: App):
         },
         SHELL_ARGV: ["-h"],
         SHELL_ARGS: {"help": True},
-        REGEX_MATCHED: "[cq:test,arg=value]",
-        REGEX_STR: "[cq:test,arg=value]",
-        REGEX_GROUP: ("test", "arg=value"),
-        REGEX_DICT: {"type": "test", "arg": "value"},
+        REGEX_MATCHED: fake_matched,
         STARTSWITH_KEY: "startswith",
         ENDSWITH_KEY: "endswith",
         FULLMATCH_KEY: "fullmatch",
@@ -254,11 +272,8 @@ async def test_state(app: App):
         ctx.pass_params(state=fake_state)
         ctx.should_return(fake_state)
 
-    with pytest.raises(ValueError):
-        async with app.test_dependent(
-            not_legacy_state, allow_types=[StateParam]
-        ) as ctx:
-            ...
+    with pytest.raises(ValueError, match=UNKNOWN_PARAM):
+        app.test_dependent(not_legacy_state, allow_types=[StateParam])
 
     async with app.test_dependent(
         command, allow_types=[StateParam, DependParam]
@@ -312,19 +327,19 @@ async def test_state(app: App):
         regex_str, allow_types=[StateParam, DependParam]
     ) as ctx:
         ctx.pass_params(state=fake_state)
-        ctx.should_return(fake_state[REGEX_STR])
+        ctx.should_return("[cq:test,arg=value]")
 
     async with app.test_dependent(
         regex_group, allow_types=[StateParam, DependParam]
     ) as ctx:
         ctx.pass_params(state=fake_state)
-        ctx.should_return(fake_state[REGEX_GROUP])
+        ctx.should_return(("test", "arg=value"))
 
     async with app.test_dependent(
         regex_dict, allow_types=[StateParam, DependParam]
     ) as ctx:
         ctx.pass_params(state=fake_state)
-        ctx.should_return(fake_state[REGEX_DICT])
+        ctx.should_return({"type": "test", "arg": "arg=value"})
 
     async with app.test_dependent(
         startswith, allow_types=[StateParam, DependParam]
@@ -353,14 +368,59 @@ async def test_state(app: App):
 
 @pytest.mark.asyncio
 async def test_matcher(app: App):
-    from plugins.param.param_matcher import matcher, receive, last_receive
+    from plugins.param.param_matcher import (
+        FooMatcher,
+        matcher,
+        receive,
+        not_matcher,
+        sub_matcher,
+        last_receive,
+        union_matcher,
+        legacy_matcher,
+        generic_matcher,
+        not_legacy_matcher,
+        generic_matcher_none,
+    )
 
     fake_matcher = Matcher()
+    foo_matcher = FooMatcher()
 
     async with app.test_dependent(matcher, allow_types=[MatcherParam]) as ctx:
         ctx.pass_params(matcher=fake_matcher)
         ctx.should_return(fake_matcher)
 
+    async with app.test_dependent(legacy_matcher, allow_types=[MatcherParam]) as ctx:
+        ctx.pass_params(matcher=fake_matcher)
+        ctx.should_return(fake_matcher)
+
+    with pytest.raises(ValueError, match=UNKNOWN_PARAM):
+        app.test_dependent(not_legacy_matcher, allow_types=[MatcherParam])
+
+    async with app.test_dependent(sub_matcher, allow_types=[MatcherParam]) as ctx:
+        ctx.pass_params(matcher=foo_matcher)
+        ctx.should_return(foo_matcher)
+
+    with pytest.raises(TypeMisMatch):  # noqa: PT012
+        async with app.test_dependent(sub_matcher, allow_types=[MatcherParam]) as ctx:
+            ctx.pass_params(matcher=fake_matcher)
+
+    async with app.test_dependent(union_matcher, allow_types=[MatcherParam]) as ctx:
+        ctx.pass_params(matcher=foo_matcher)
+        ctx.should_return(foo_matcher)
+
+    async with app.test_dependent(generic_matcher, allow_types=[MatcherParam]) as ctx:
+        ctx.pass_params(matcher=fake_matcher)
+        ctx.should_return(fake_matcher)
+
+    async with app.test_dependent(
+        generic_matcher_none, allow_types=[MatcherParam]
+    ) as ctx:
+        ctx.pass_params(matcher=fake_matcher)
+        ctx.should_return(fake_matcher)
+
+    with pytest.raises(ValueError, match=UNKNOWN_PARAM):
+        app.test_dependent(not_matcher, allow_types=[MatcherParam])
+
     event = make_fake_event()()
     fake_matcher.set_receive("test", event)
     event_next = make_fake_event()()
@@ -381,10 +441,17 @@ async def test_matcher(app: App):
 
 @pytest.mark.asyncio
 async def test_arg(app: App):
-    from plugins.param.param_arg import arg, arg_str, arg_plain_text
+    from plugins.param.param_arg import (
+        arg,
+        arg_str,
+        annotated_arg,
+        arg_plain_text,
+        annotated_arg_str,
+        annotated_arg_plain_text,
+    )
 
     matcher = Matcher()
-    message = make_fake_message()("text")
+    message = FakeMessage("text")
     matcher.set_arg("key", message)
 
     async with app.test_dependent(arg, allow_types=[ArgParam]) as ctx:
@@ -399,6 +466,20 @@ async def test_arg(app: App):
         ctx.pass_params(matcher=matcher)
         ctx.should_return(message.extract_plain_text())
 
+    async with app.test_dependent(annotated_arg, allow_types=[ArgParam]) as ctx:
+        ctx.pass_params(matcher=matcher)
+        ctx.should_return(message)
+
+    async with app.test_dependent(annotated_arg_str, allow_types=[ArgParam]) as ctx:
+        ctx.pass_params(matcher=matcher)
+        ctx.should_return(str(message))
+
+    async with app.test_dependent(
+        annotated_arg_plain_text, allow_types=[ArgParam]
+    ) as ctx:
+        ctx.pass_params(matcher=matcher)
+        ctx.should_return(message.extract_plain_text())
+
 
 @pytest.mark.asyncio
 async def test_exception(app: App):
@@ -416,3 +497,41 @@ async def test_default(app: App):
 
     async with app.test_dependent(default, allow_types=[DefaultParam]) as ctx:
         ctx.should_return(1)
+
+
+@pytest.mark.asyncio
+async def test_priority():
+    from plugins.param.priority import complex_priority
+
+    dependent = Dependent.parse(
+        call=complex_priority,
+        allow_types=[
+            DependParam,
+            BotParam,
+            EventParam,
+            StateParam,
+            MatcherParam,
+            ArgParam,
+            ExceptionParam,
+            DefaultParam,
+        ],
+    )
+    for param in dependent.params:
+        if param.name == "sub":
+            assert isinstance(param.field_info, DependParam)
+        elif param.name == "bot":
+            assert isinstance(param.field_info, BotParam)
+        elif param.name == "event":
+            assert isinstance(param.field_info, EventParam)
+        elif param.name == "state":
+            assert isinstance(param.field_info, StateParam)
+        elif param.name == "matcher":
+            assert isinstance(param.field_info, MatcherParam)
+        elif param.name == "arg":
+            assert isinstance(param.field_info, ArgParam)
+        elif param.name == "exception":
+            assert isinstance(param.field_info, ExceptionParam)
+        elif param.name == "default":
+            assert isinstance(param.field_info, DefaultParam)
+        else:
+            raise ValueError(f"unknown param {param.name}")

tests/test_permission.py

@@ -47,15 +47,15 @@ async def test_permission(app: App):
 
     async with app.test_api() as ctx:
         bot = ctx.create_bot()
-        assert await Permission(falsy)(bot, event) == False
-        assert await Permission(truthy)(bot, event) == True
-        assert await Permission(skipped)(bot, event) == False
-        assert await Permission(truthy, falsy)(bot, event) == True
-        assert await Permission(truthy, skipped)(bot, event) == True
+        assert await Permission(falsy)(bot, event) is False
+        assert await Permission(truthy)(bot, event) is True
+        assert await Permission(skipped)(bot, event) is False
+        assert await Permission(truthy, falsy)(bot, event) is True
+        assert await Permission(truthy, skipped)(bot, event) is True
 
 
 @pytest.mark.asyncio
-@pytest.mark.parametrize("type, expected", [("message", True), ("notice", False)])
+@pytest.mark.parametrize(("type", "expected"), [("message", True), ("notice", False)])
 async def test_message(type: str, expected: bool):
     dependent = list(MESSAGE.checkers)[0]
     checker = dependent.call
@@ -67,7 +67,7 @@ async def test_message(type: str, expected: bool):
 
 
 @pytest.mark.asyncio
-@pytest.mark.parametrize("type, expected", [("message", False), ("notice", True)])
+@pytest.mark.parametrize(("type", "expected"), [("message", False), ("notice", True)])
 async def test_notice(type: str, expected: bool):
     dependent = list(NOTICE.checkers)[0]
     checker = dependent.call
@@ -79,7 +79,7 @@ async def test_notice(type: str, expected: bool):
 
 
 @pytest.mark.asyncio
-@pytest.mark.parametrize("type, expected", [("message", False), ("request", True)])
+@pytest.mark.parametrize(("type", "expected"), [("message", False), ("request", True)])
 async def test_request(type: str, expected: bool):
     dependent = list(REQUEST.checkers)[0]
     checker = dependent.call
@@ -91,7 +91,9 @@ async def test_request(type: str, expected: bool):
 
 
 @pytest.mark.asyncio
-@pytest.mark.parametrize("type, expected", [("message", False), ("meta_event", True)])
+@pytest.mark.parametrize(
+    ("type", "expected"), [("message", False), ("meta_event", True)]
+)
 async def test_metaevent(type: str, expected: bool):
     dependent = list(METAEVENT.checkers)[0]
     checker = dependent.call
@@ -104,7 +106,7 @@ async def test_metaevent(type: str, expected: bool):
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    "type, user_id, expected",
+    ("type", "user_id", "expected"),
     [
         ("message", "test", True),
         ("message", "foo", False),
@@ -128,7 +130,7 @@ async def test_superuser(app: App, type: str, user_id: str, expected: bool):
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    "session_ids, session_id, expected",
+    ("session_ids", "session_id", "expected"),
     [
         (("user", "foo"), "user", True),
         (("user", "foo"), "bar", False),

tests/test_plugin/test_load.py

@@ -6,7 +6,7 @@ from dataclasses import asdict
 import pytest
 
 import nonebot
-from nonebot.plugin import Plugin, PluginManager, _managers
+from nonebot.plugin import Plugin, PluginManager, _managers, inherit_supported_adapters
 
 
 @pytest.mark.asyncio
@@ -22,11 +22,11 @@ async def test_load_plugin():
 
 
 @pytest.mark.asyncio
-async def test_load_plugins(load_plugin: Set[Plugin], load_example: Set[Plugin]):
+async def test_load_plugins(load_plugin: Set[Plugin], load_builtin_plugin: Set[Plugin]):
     loaded_plugins = {
         plugin for plugin in nonebot.get_loaded_plugins() if not plugin.parent_plugin
     }
-    assert loaded_plugins >= load_plugin | load_example
+    assert loaded_plugins >= load_plugin | load_builtin_plugin
 
     # check simple plugin
     assert "plugins.export" in sys.modules
@@ -49,7 +49,9 @@ async def test_load_nested_plugin():
     parent_plugin = nonebot.get_plugin("nested")
     sub_plugin = nonebot.get_plugin("nested_subplugin")
     sub_plugin2 = nonebot.get_plugin("nested_subplugin2")
-    assert parent_plugin and sub_plugin and sub_plugin2
+    assert parent_plugin
+    assert sub_plugin
+    assert sub_plugin2
     assert sub_plugin.parent_plugin is parent_plugin
     assert sub_plugin2.parent_plugin is parent_plugin
     assert parent_plugin.sub_plugins == {sub_plugin, sub_plugin2}
@@ -67,7 +69,7 @@ async def test_load_json():
 async def test_load_toml():
     nonebot.load_from_toml("./plugins.toml")
 
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match="Cannot find"):
         nonebot.load_from_toml("./plugins.empty.toml")
 
     with pytest.raises(TypeError):
@@ -128,7 +130,7 @@ async def test_require_not_found():
 
 @pytest.mark.asyncio
 async def test_plugin_metadata():
-    from plugins.metadata import Config
+    from plugins.metadata import Config, FakeAdapter
 
     plugin = nonebot.get_plugin("metadata")
     assert plugin
@@ -137,6 +139,43 @@ async def test_plugin_metadata():
         "name": "测试插件",
         "description": "测试插件元信息",
         "usage": "无法使用",
+        "type": "application",
+        "homepage": "https://nonebot.dev",
         "config": Config,
+        "supported_adapters": {"~onebot.v11", "plugins.metadata:FakeAdapter"},
         "extra": {"author": "NoneBot"},
     }
+
+    assert plugin.metadata.get_supported_adapters() == {FakeAdapter}
+
+
+@pytest.mark.asyncio
+async def test_inherit_supported_adapters():
+    with pytest.raises(RuntimeError):
+        inherit_supported_adapters("some_plugin_not_exist")
+
+    with pytest.raises(ValueError, match="has no metadata!"):
+        inherit_supported_adapters("export")
+
+    echo = nonebot.get_plugin("echo")
+    assert echo
+    assert echo.metadata
+    assert inherit_supported_adapters("echo") is None
+
+    plugin_1 = nonebot.get_plugin("metadata")
+    assert plugin_1
+    assert plugin_1.metadata
+    assert inherit_supported_adapters("metadata") == {
+        "nonebot.adapters.onebot.v11",
+        "plugins.metadata:FakeAdapter",
+    }
+
+    plugin_2 = nonebot.get_plugin("metadata_2")
+    assert plugin_2
+    assert plugin_2.metadata
+    assert inherit_supported_adapters("metadata", "metadata_2") == {
+        "nonebot.adapters.onebot.v11"
+    }
+    assert inherit_supported_adapters("metadata", "echo", "metadata_2") == {
+        "nonebot.adapters.onebot.v11"
+    }

tests/test_plugin/test_on.py

@@ -20,7 +20,7 @@ from nonebot.rule import (
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    "matcher_name, pre_rule_factory, has_permission",
+    ("matcher_name", "pre_rule_factory", "has_permission"),
     [
         pytest.param("matcher_on", None, True),
         pytest.param("matcher_on_metaevent", None, False),
@@ -41,10 +41,30 @@ from nonebot.rule import (
         ),
         pytest.param("matcher_on_regex", lambda e: RegexRule("test"), True),
         pytest.param("matcher_on_type", lambda e: IsTypeRule(e), True),
-        pytest.param("matcher_sub_cmd", lambda e: CommandRule([("test", "sub")]), True),
         pytest.param(
-            "matcher_sub_shell_cmd",
-            lambda e: ShellCommandRule([("test", "sub")], None),
+            "matcher_prefix_cmd",
+            lambda e: CommandRule([("prefix", "sub"), ("help",), ("help", "foo")]),
+            True,
+        ),
+        pytest.param(
+            "matcher_prefix_shell_cmd",
+            lambda e: ShellCommandRule(
+                [("prefix", "sub"), ("help",), ("help", "foo")], None
+            ),
+            True,
+        ),
+        pytest.param(
+            "matcher_prefix_aliases_cmd",
+            lambda e: CommandRule(
+                [("prefix", "sub"), ("prefix", "help"), ("prefix", "help", "foo")]
+            ),
+            True,
+        ),
+        pytest.param(
+            "matcher_prefix_aliases_shell_cmd",
+            lambda e: ShellCommandRule(
+                [("prefix", "sub"), ("prefix", "help"), ("prefix", "help", "foo")], None
+            ),
             True,
         ),
         pytest.param("matcher_group_on", None, True),

tests/test_rule.py

@@ -1,22 +1,20 @@
+import re
 import sys
-from typing import Dict, Tuple, Union, Optional
+from typing import Match, Tuple, Union, Optional
 
 import pytest
 from nonebug import App
 
 from nonebot.typing import T_State
-from utils import make_fake_event, make_fake_message
 from nonebot.exception import ParserExit, SkippedException
+from utils import FakeMessage, FakeMessageSegment, make_fake_event
 from nonebot.consts import (
     CMD_KEY,
-    REGEX_STR,
     PREFIX_KEY,
-    REGEX_DICT,
     SHELL_ARGS,
     SHELL_ARGV,
     CMD_ARG_KEY,
     KEYWORD_KEY,
-    REGEX_GROUP,
     ENDSWITH_KEY,
     FULLMATCH_KEY,
     REGEX_MATCHED,
@@ -76,35 +74,32 @@ async def test_rule(app: App):
 
     async with app.test_api() as ctx:
         bot = ctx.create_bot()
-        assert await Rule(falsy)(bot, event, {}) == False
-        assert await Rule(truthy)(bot, event, {}) == True
-        assert await Rule(skipped)(bot, event, {}) == False
-        assert await Rule(truthy, falsy)(bot, event, {}) == False
-        assert await Rule(truthy, skipped)(bot, event, {}) == False
+        assert await Rule(falsy)(bot, event, {}) is False
+        assert await Rule(truthy)(bot, event, {}) is True
+        assert await Rule(skipped)(bot, event, {}) is False
+        assert await Rule(truthy, falsy)(bot, event, {}) is False
+        assert await Rule(truthy, skipped)(bot, event, {}) is False
 
 
 @pytest.mark.asyncio
 async def test_trie(app: App):
     TrieRule.add_prefix("/fake-prefix", TRIE_VALUE("/", ("fake-prefix",)))
 
-    Message = make_fake_message()
-    MessageSegment = Message.get_segment_class()
-
     async with app.test_api() as ctx:
         bot = ctx.create_bot()
-        message = Message("/fake-prefix some args")
+        message = FakeMessage("/fake-prefix some args")
         event = make_fake_event(_message=message)()
         state = {}
         TrieRule.get_value(bot, event, state)
         assert state[PREFIX_KEY] == CMD_RESULT(
             command=("fake-prefix",),
             raw_command="/fake-prefix",
-            command_arg=Message("some args"),
+            command_arg=FakeMessage("some args"),
             command_start="/",
             command_whitespace=" ",
         )
 
-        message = MessageSegment.text("/fake-prefix ") + MessageSegment.image(
+        message = FakeMessageSegment.text("/fake-prefix ") + FakeMessageSegment.image(
             "fake url"
         )
         event = make_fake_event(_message=message)()
@@ -113,7 +108,7 @@ async def test_trie(app: App):
         assert state[PREFIX_KEY] == CMD_RESULT(
             command=("fake-prefix",),
             raw_command="/fake-prefix",
-            command_arg=Message(MessageSegment.image("fake url")),
+            command_arg=FakeMessage(FakeMessageSegment.image("fake url")),
             command_start="/",
             command_whitespace=" ",
         )
@@ -123,7 +118,7 @@ async def test_trie(app: App):
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    "msg, ignorecase, type, text, expected",
+    ("msg", "ignorecase", "type", "text", "expected"),
     [
         ("prefix", False, "message", "prefix_", True),
         ("prefix", False, "message", "Prefix_", False),
@@ -154,7 +149,7 @@ async def test_startswith(
     assert checker.msg == msg
     assert checker.ignorecase == ignorecase
 
-    message = text if text is None else make_fake_message()(text)
+    message = text if text is None else FakeMessage(text)
     event = make_fake_event(_type=type, _message=message)()
     for prefix in msg:
         state = {STARTSWITH_KEY: prefix}
@@ -163,7 +158,7 @@ async def test_startswith(
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    "msg, ignorecase, type, text, expected",
+    ("msg", "ignorecase", "type", "text", "expected"),
     [
         ("suffix", False, "message", "_suffix", True),
         ("suffix", False, "message", "_Suffix", False),
@@ -194,7 +189,7 @@ async def test_endswith(
     assert checker.msg == msg
     assert checker.ignorecase == ignorecase
 
-    message = text if text is None else make_fake_message()(text)
+    message = text if text is None else FakeMessage(text)
     event = make_fake_event(_type=type, _message=message)()
     for suffix in msg:
         state = {ENDSWITH_KEY: suffix}
@@ -203,7 +198,7 @@ async def test_endswith(
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    "msg, ignorecase, type, text, expected",
+    ("msg", "ignorecase", "type", "text", "expected"),
     [
         ("fullmatch", False, "message", "fullmatch", True),
         ("fullmatch", False, "message", "Fullmatch", False),
@@ -234,7 +229,7 @@ async def test_fullmatch(
     assert checker.msg == msg
     assert checker.ignorecase == ignorecase
 
-    message = text if text is None else make_fake_message()(text)
+    message = text if text is None else FakeMessage(text)
     event = make_fake_event(_type=type, _message=message)()
     for full in msg:
         state = {FULLMATCH_KEY: full}
@@ -243,7 +238,7 @@ async def test_fullmatch(
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    "kws, type, text, expected",
+    ("kws", "type", "text", "expected"),
     [
         (("key",), "message", "_key_", True),
         (("key", "foo"), "message", "_foo_", True),
@@ -266,7 +261,7 @@ async def test_keyword(
     assert isinstance(checker, KeywordsRule)
     assert checker.keywords == kws
 
-    message = text if text is None else make_fake_message()(text)
+    message = text if text is None else FakeMessage(text)
     event = make_fake_event(_type=type, _message=message)()
     for kw in kws:
         state = {KEYWORD_KEY: kw}
@@ -275,22 +270,34 @@ async def test_keyword(
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    "cmds, cmd, force_whitespace, whitespace, expected",
+    ("cmds", "force_whitespace", "cmd", "whitespace", "arg_text", "expected"),
     [
-        [(("help",),), ("help",), None, None, True],
-        [(("help",),), ("foo",), None, None, False],
-        [(("help", "foo"),), ("help", "foo"), True, " ", True],
-        [(("help",), ("foo",)), ("help",), " ", " ", True],
-        [(("help",),), ("help",), False, " ", False],
-        [(("help",),), ("help",), True, None, False],
-        [(("help",),), ("help",), "\n", " ", False],
+        # command tests
+        ((("help",),), None, ("help",), None, None, True),
+        ((("help",),), None, ("foo",), None, None, False),
+        ((("help", "foo"),), None, ("help", "foo"), None, None, True),
+        ((("help", "foo"),), None, ("help", "bar"), None, None, False),
+        ((("help",), ("foo",)), None, ("help",), None, None, True),
+        ((("help",), ("foo",)), None, ("bar",), None, None, False),
+        # whitespace tests
+        ((("help",),), True, ("help",), " ", "arg", True),
+        ((("help",),), True, ("help",), None, "arg", False),
+        ((("help",),), True, ("help",), None, None, True),
+        ((("help",),), False, ("help",), " ", "arg", False),
+        ((("help",),), False, ("help",), None, "arg", True),
+        ((("help",),), False, ("help",), None, None, True),
+        ((("help",),), " ", ("help",), " ", "arg", True),
+        ((("help",),), " ", ("help",), "\n", "arg", False),
+        ((("help",),), " ", ("help",), None, "arg", False),
+        ((("help",),), " ", ("help",), None, None, True),
     ],
 )
 async def test_command(
     cmds: Tuple[Tuple[str, ...]],
-    cmd: Tuple[str, ...],
     force_whitespace: Optional[Union[str, bool]],
+    cmd: Tuple[str, ...],
     whitespace: Optional[str],
+    arg_text: Optional[str],
     expected: bool,
 ):
     test_command = command(*cmds, force_whitespace=force_whitespace)
@@ -300,7 +307,10 @@ async def test_command(
     assert isinstance(checker, CommandRule)
     assert checker.cmds == cmds
 
-    state = {PREFIX_KEY: {CMD_KEY: cmd, CMD_WHITESPACE_KEY: whitespace}}
+    arg = arg_text if arg_text is None else FakeMessage(arg_text)
+    state = {
+        PREFIX_KEY: {CMD_KEY: cmd, CMD_WHITESPACE_KEY: whitespace, CMD_ARG_KEY: arg}
+    }
     assert await dependent(state=state) == expected
 
 
@@ -308,7 +318,7 @@ async def test_command(
 async def test_shell_command():
     state: T_State
     CMD = ("test",)
-    Message = make_fake_message()
+    Message = FakeMessage
     MessageSegment = Message.get_segment_class()
 
     test_not_cmd = shell_command(CMD)
@@ -371,6 +381,19 @@ async def test_shell_command():
     assert state[SHELL_ARGS].status != 0
     assert state[SHELL_ARGS].message.startswith(parser.format_usage() + "test: error:")
 
+    test_parser_remain_args = shell_command(CMD, parser=parser)
+    dependent = list(test_parser_remain_args.checkers)[0]
+    checker = dependent.call
+    assert isinstance(checker, ShellCommandRule)
+    message = MessageSegment.text("-a 1 2") + MessageSegment.image("test")
+    event = make_fake_event(_message=message)()
+    state = {PREFIX_KEY: {CMD_KEY: CMD, CMD_ARG_KEY: message}}
+    assert await dependent(event=event, state=state)
+    assert state[SHELL_ARGV] == ["-a", "1", "2", MessageSegment.image("test")]
+    assert isinstance(state[SHELL_ARGS], ParserExit)
+    assert state[SHELL_ARGS].status != 0
+    assert state[SHELL_ARGS].message.startswith(parser.format_usage() + "test: error:")
+
     test_message_parser = shell_command(CMD, parser=parser)
     dependent = list(test_message_parser.checkers)[0]
     checker = dependent.call
@@ -401,21 +424,18 @@ async def test_shell_command():
 
 @pytest.mark.asyncio
 @pytest.mark.parametrize(
-    "pattern, type, text, expected, matched, string, group, dict",
+    ("pattern", "type", "text", "expected", "matched"),
     [
         (
             r"(?P<key>key\d)",
             "message",
             "_key1_",
             True,
-            "key1",
-            "key1",
-            ("key1",),
-            {"key": "key1"},
+            re.search(r"(?P<key>key\d)", "_key1_"),
         ),
-        (r"foo", "message", None, False, None, None, None, None),
-        (r"foo", "notice", "foo", True, "foo", "foo", tuple(), {}),
-        (r"foo", "notice", "bar", False, None, None, None, None),
+        (r"foo", "message", None, False, None),
+        (r"foo", "notice", "foo", True, re.search(r"foo", "foo")),
+        (r"foo", "notice", "bar", False, None),
     ],
 )
 async def test_regex(
@@ -423,10 +443,7 @@ async def test_regex(
     type: str,
     text: Optional[str],
     expected: bool,
-    matched: Optional[str],
-    string: Optional[str],
-    group: Optional[Tuple[str, ...]],
-    dict: Optional[Dict[str, str]],
+    matched: Optional[Match[str]],
 ):
     test_regex = regex(pattern)
     dependent = list(test_regex.checkers)[0]
@@ -435,14 +452,17 @@ async def test_regex(
     assert isinstance(checker, RegexRule)
     assert checker.regex == pattern
 
-    message = text if text is None else make_fake_message()(text)
+    message = text if text is None else FakeMessage(text)
     event = make_fake_event(_type=type, _message=message)()
     state = {}
     assert await dependent(event=event, state=state) == expected
-    assert state.get(REGEX_MATCHED) == matched
-    assert state.get(REGEX_STR) == string
-    assert state.get(REGEX_GROUP) == group
-    assert state.get(REGEX_DICT) == dict
+    result: Optional[Match[str]] = state.get(REGEX_MATCHED)
+    if matched is None:
+        assert result is None
+    else:
+        assert isinstance(result, Match)
+        assert result.group() == matched.group()
+        assert result.span() == matched.span()
 
 
 @pytest.mark.asyncio

tests/test_single_session.py

@@ -16,21 +16,21 @@ async def test_matcher_mutex():
     event_3 = make_fake_event(_session_id=None)()
 
     async with am(event) as ctx:
-        assert ctx == False
+        assert ctx is False
     assert not _running_matcher
 
     async with am(event) as ctx:
         async with am(event_1) as ctx_1:
-            assert ctx == False
-            assert ctx_1 == True
+            assert ctx is False
+            assert ctx_1 is True
     assert not _running_matcher
 
     async with am(event) as ctx:
         async with am(event_2) as ctx_2:
-            assert ctx == False
-            assert ctx_2 == False
+            assert ctx is False
+            assert ctx_2 is False
     assert not _running_matcher
 
     async with am(event_3) as ctx_3:
-        assert ctx_3 == False
+        assert ctx_3 is False
     assert not _running_matcher

tests/test_utils.py

@@ -1,18 +1,126 @@
 import json
+from typing import Dict, List, Union, TypeVar
 
-from utils import make_fake_message
-from nonebot.utils import DataclassEncoder
+from utils import FakeMessage, FakeMessageSegment
+from nonebot.utils import (
+    DataclassEncoder,
+    escape_tag,
+    is_gen_callable,
+    is_async_gen_callable,
+    is_coroutine_callable,
+    generic_check_issubclass,
+)
+
+
+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>"
+    assert escape_tag("<fg\n#fff>white</fg\n#fff>") == "\\<fg\n#fff>white\\</fg\n#fff>"
+    assert escape_tag("<bg #fff>white</bg #fff>") == r"\<bg #fff>white\</bg #fff>"
+    assert escape_tag("<bg\n#fff>white</bg\n#fff>") == "\\<bg\n#fff>white\\</bg\n#fff>"
+
+
+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(List[int], list)
+    assert generic_check_issubclass(Dict[str, int], dict)
+    assert generic_check_issubclass(TypeVar("T", int, float), (int, float))
+    assert generic_check_issubclass(TypeVar("T", bound=int), (int, float))
+
+
+def test_is_coroutine_callable():
+    async def test1():
+        ...
+
+    def test2():
+        ...
+
+    class TestClass1:
+        async def __call__(self):
+            ...
+
+    class TestClass2:
+        def __call__(self):
+            ...
+
+    assert is_coroutine_callable(test1)
+    assert not is_coroutine_callable(test2)
+    assert not is_coroutine_callable(TestClass1)
+    assert is_coroutine_callable(TestClass1())
+    assert not is_coroutine_callable(TestClass2)
+
+
+def test_is_gen_callable():
+    def test1():
+        yield
+
+    async def test2():
+        yield
+
+    def test3():
+        ...
+
+    class TestClass1:
+        def __call__(self):
+            yield
+
+    class TestClass2:
+        async def __call__(self):
+            yield
+
+    class TestClass3:
+        def __call__(self):
+            ...
+
+    assert is_gen_callable(test1)
+    assert not is_gen_callable(test2)
+    assert not is_gen_callable(test3)
+    assert is_gen_callable(TestClass1())
+    assert not is_gen_callable(TestClass2())
+    assert not is_gen_callable(TestClass3())
+
+
+def test_is_async_gen_callable():
+    async def test1():
+        yield
+
+    def test2():
+        yield
+
+    async def test3():
+        ...
+
+    class TestClass1:
+        async def __call__(self):
+            yield
+
+    class TestClass2:
+        def __call__(self):
+            yield
+
+    class TestClass3:
+        async def __call__(self):
+            ...
+
+    assert is_async_gen_callable(test1)
+    assert not is_async_gen_callable(test2)
+    assert not is_async_gen_callable(test3)
+    assert is_async_gen_callable(TestClass1())
+    assert not is_async_gen_callable(TestClass2())
+    assert not is_async_gen_callable(TestClass3())
 
 
 def test_dataclass_encoder():
     simple = json.dumps("123", cls=DataclassEncoder)
     assert simple == '"123"'
 
-    Message = make_fake_message()
-    MessageSegment = Message.get_segment_class()
-    ms = MessageSegment.nested(Message(MessageSegment.text("text")))
+    ms = FakeMessageSegment.nested(FakeMessage(FakeMessageSegment.text("text")))
     s = json.dumps(ms, cls=DataclassEncoder)
-    assert (
-        s
-        == '{"type": "node", "data": {"content": [{"type": "text", "data": {"text": "text"}}]}}'
+    assert s == (
+        "{"
+        '"type": "node", '
+        '"data": {"content": [{"type": "text", "data": {"text": "text"}}]}'
+        "}"
     )

tests/utils.py

@@ -1,6 +1,6 @@
 from typing import Type, Union, Mapping, Iterable, Optional
 
-from pydantic import create_model
+from pydantic import Extra, create_model
 
 from nonebot.adapters import Event, Message, MessageSegment
 
@@ -12,8 +12,7 @@ def escape_text(s: str, *, escape_comma: bool = True) -> str:
     return s
 
 
-def make_fake_message():
-    class FakeMessageSegment(MessageSegment):
+class FakeMessageSegment(MessageSegment["FakeMessage"]):
     @classmethod
     def get_message_class(cls):
         return FakeMessage
@@ -36,7 +35,8 @@ def make_fake_message():
     def is_text(self) -> bool:
         return self.type == "text"
 
-    class FakeMessage(Message):
+
+class FakeMessage(Message[FakeMessageSegment]):
     @classmethod
     def get_segment_class(cls):
         return FakeMessageSegment
@@ -50,12 +50,12 @@ def make_fake_message():
                 yield FakeMessageSegment(**seg)
         return
 
-        def __add__(self, other):
+    def __add__(
+        self, other: Union[str, FakeMessageSegment, Iterable[FakeMessageSegment]]
+    ):
         other = escape_text(other) if isinstance(other, str) else other
         return super().__add__(other)
 
-    return FakeMessage
-
 
 def make_fake_event(
     _base: Optional[Type[Event]] = None,
@@ -68,9 +68,9 @@ def make_fake_event(
     _to_me: bool = True,
     **fields,
 ) -> Type[Event]:
-    _Fake = create_model("_Fake", __base__=_base or Event, **fields)
+    Base = _base or Event
 
-    class FakeEvent(_Fake):
+    class FakeEvent(Base, extra=Extra.forbid):
         def get_type(self) -> str:
             return _type
 
@@ -98,7 +98,4 @@ def make_fake_event(
         def is_tome(self) -> bool:
             return _to_me
 
-        class Config:
-            extra = "forbid"
-
-    return FakeEvent
+    return create_model("FakeEvent", __base__=FakeEvent, **fields)

website/docs/advanced/adapter.md

@@ -35,7 +35,7 @@ driver = nonebot.get_driver()
 driver.register_adapter(Adapter)
 ```
 
-我们首先需要从适配器模块中导入所需要的适配器类，然后通过驱动器的 `register_adapter` 方法将适配器注册到驱动器中即可。
+我们首先需要从适配器模块中导入所需要的适配器类，然后通过驱动器的 `register_adapter` 方法将适配器注册到驱动器中即可。如果我们需要多平台支持，可以多次调用 `register_adapter` 方法来注册多个适配器。
 
 ## 获取已注册的适配器
 

website/docs/advanced/dependency.mdx

@@ -71,7 +71,9 @@ async def _(foo: str = "bar"): ...
 
 获取当前事件的 Bot 对象。
 
-通过标注参数为 `Bot` 类型，或者一系列 `Bot` 类型，即可获取到当前事件的 Bot 对象。为兼容性考虑，如果参数名为 `bot` 且无类型注解，也会视为 `Bot` 依赖注入。
+通过标注参数为 `Bot` 类型，或者一系列 `Bot` 类型，即可获取到当前事件的 Bot 对象。为兼容性考虑，如果参数名为 `bot` 且无类型注解，也会视为 Bot 依赖注入。
+
+Bot 依赖注入支持重载（即：可以标注参数为子类型）且具有[重载优先检查权](../appendices/overload.md#重载)。
 
 <Tabs groupId="python">
   <TabItem value="3.10" label="Python 3.10+" default>
@@ -108,7 +110,9 @@ async def _(bot): ...  # 兼容性处理
 
 获取当前事件。
 
-通过标注参数为 `Event` 类型，或者一系列 `Event` 类型，即可获取到当前事件。为兼容性考虑，如果参数名为 `event` 且无类型注解，也会视为 `Event` 依赖注入。
+通过标注参数为 `Event` 类型，或者一系列 `Event` 类型，即可获取到当前事件。为兼容性考虑，如果参数名为 `event` 且无类型注解，也会视为 Event 依赖注入。
+
+Event 依赖注入支持重载（即：可以标注参数为子类型）且具有[重载优先检查权](../appendices/overload.md#重载)。
 
 <Tabs groupId="python">
   <TabItem value="3.10" label="Python 3.10+" default>
@@ -143,6 +147,8 @@ async def _(event): ...  # 兼容性处理
 
 获取当前[会话状态](../appendices/session-state.md)。
 
+通过标注参数为 `T_State` 类型，即可获取到当前会话状态。为兼容性考虑，如果参数名为 `state` 且无类型注解，也会视为 State 依赖注入。
+
 ```python
 from nonebot.typing import T_State
 
@@ -153,10 +159,15 @@ async def _(foo: T_State): ...
 
 获取当前事件响应器实例。常用于使用[事件响应器操作](../appendices/session-control.mdx)。
 
+通过标注参数为 `Matcher` 类型，或者一系列 `Matcher` 类型，即可获取到当前事件。为兼容性考虑，如果参数名为 `matcher` 且无类型注解，也会视为 Matcher 依赖注入。
+
+Matcher 依赖注入支持重载（即：可以标注参数为子类型）且具有[重载优先检查权](../appendices/overload.md#重载)。
+
 ```python
 from nonebot.matcher import Matcher
 
-async def _(matcher: Matcher): ...
+async def _(foo: Matcher): ...
+async def _(matcher): ...  # 兼容性处理
 ```
 
 ### Exception
@@ -212,19 +223,18 @@ async def _(e: Union[ActionFailed, NetworkError]): ...
 from typing import Annotated
 
 from nonebot import on_command
+from nonebot.adapters import Event
 from nonebot.params import Depends
-from nonebot.matcher import Matcher
-from nonebot.adapters.console import MessageEvent
 
 test = on_command("test")
 
-async def check(event: MessageEvent, matcher: Matcher) -> MessageEvent:
+async def check(event: Event) -> Event:
     if event.get_user_id() in BLACKLIST:
-        await matcher.finish()
+        await test.finish()
     return event
 
 @test.handle()
-async def _(event: Annotated[MessageEvent, Depends(check)]):
+async def _(event: Annotated[Event, Depends(check)]):
     ...
 ```
 
@@ -233,19 +243,18 @@ async def _(event: Annotated[MessageEvent, Depends(check)]):
 
 ```python {2,14}
 from nonebot import on_command
+from nonebot.adapters import Event
 from nonebot.params import Depends
-from nonebot.matcher import Matcher
-from nonebot.adapters.console import MessageEvent
 
 test = on_command("test")
 
-async def check(event: MessageEvent, matcher: Matcher) -> MessageEvent:
+async def check(event: Event) -> Event:
     if event.get_user_id() in BLACKLIST:
-        await matcher.finish()
+        await test.finish()
     return event
 
 @test.handle()
-async def _(event: MessageEvent = Depends(check)):
+async def _(event: Event = Depends(check)):
     ...
 ```
 
@@ -256,6 +265,24 @@ async def _(event: MessageEvent = Depends(check)):
 
 通过将 `Depends` 包裹的子依赖作为参数的默认值，我们就可以在执行事件处理函数之前执行子依赖，并将其返回值作为参数传入事件处理函数。子依赖和普通的事件处理函数并没有区别，同样可以使用依赖注入，并且可以返回任何类型的值。但需要注意的是，如果事件处理函数参数的类型注解与子依赖返回值的类型**不一致**，将会触发[重载](../appendices/overload.md)而跳过当前事件处理函数。
 
+特别的，我们可以为 `Dependent` 对象定义一系列前置子依赖，它们会在参数执行前被顺序执行，且返回值将会被忽略，例如：
+
+```python {2,14}
+from nonebot import on_command
+from nonebot.adapters import Event
+from nonebot.params import Depends
+
+test = on_command("test")
+
+async def check(event: Event):
+    if event.get_user_id() in BLACKLIST:
+        await test.finish()
+
+@test.handle(parameterless=[Depends(check)])
+async def _():
+    ...
+```
+
 ### 依赖缓存
 
 NoneBot 在执行子依赖时，会将其返回值缓存起来。当我们在使用子依赖时，`Depends` 具有一个参数 `use_cache`，默认为 `True`。此时在事件处理流程中，多次使用同一个子依赖时，将会使用缓存中的结果而不会重复执行。这在很多情景中非常有用，例如：
@@ -428,7 +455,7 @@ async def get_client() -> AsyncGenerator[httpx.AsyncClient, None]:
 
 @test.handle()
 async def _(x: Annotated[httpx.AsyncClient, Depends(get_client)]):
-    resp = await x.get("https://v2.nonebot.dev")
+    resp = await x.get("https://nonebot.dev")
 ```
 
   </TabItem>
@@ -450,7 +477,7 @@ async def get_client() -> AsyncGenerator[httpx.AsyncClient, None]:
 
 @test.handle()
 async def _(x: httpx.AsyncClient = Depends(get_client)):
-    resp = await x.get("https://v2.nonebot.dev")
+    resp = await x.get("https://nonebot.dev")
 ```
 
   </TabItem>
@@ -1139,8 +1166,8 @@ from typing import Annotated
 from nonebot.params import ArgStr
 
 @matcher.got("key")
-async def _(key: str = ArgStr()): ...
-async def _(foo: str = ArgStr("key")): ...
+async def _(key: Annotated[str, ArgStr()]): ...
+async def _(foo: Annotated[str, ArgStr("key")]): ...
 ```
 
   </TabItem>
@@ -1150,8 +1177,8 @@ async def _(foo: str = ArgStr("key")): ...
 from nonebot.params import ArgStr
 
 @matcher.got("key")
-async def _(key: Annotated[str, ArgStr()]): ...
-async def _(foo: Annotated[str, ArgStr("key")]): ...
+async def _(key: str = ArgStr()): ...
+async def _(foo: str = ArgStr("key")): ...
 ```
 
   </TabItem>