📝 Update changelog

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

.devcontainer/devcontainer.json

@@ -0,0 +1,54 @@
+{
+  "name": "Ubuntu",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+  "features": {
+    "ghcr.io/jsburckhardt/devcontainer-features/uv:1": {},
+    "ghcr.io/devcontainers/features/node:1": {},
+    "ghcr.io/meaningful-ooo/devcontainer-features/fish:2": {}
+  },
+  "postCreateCommand": "./scripts/setup-envs.sh",
+  "customizations": {
+    "vscode": {
+      "settings": {
+        "python.analysis.diagnosticMode": "workspace",
+        "[python]": {
+          "editor.defaultFormatter": "charliermarsh.ruff",
+          "editor.codeActionsOnSave": {
+            "source.fixAll.ruff": "explicit",
+            "source.organizeImports": "explicit"
+          }
+        },
+        "[javascript]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode"
+        },
+        "[html]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode"
+        },
+        "[typescript]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode"
+        },
+        "[javascriptreact]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode"
+        },
+        "[typescriptreact]": {
+          "editor.defaultFormatter": "esbenp.prettier-vscode"
+        },
+        "files.exclude": {
+          "**/__pycache__": true
+        },
+        "files.watcherExclude": {
+          "**/target/**": true,
+          "**/__pycache__": true
+        }
+      },
+      "extensions": [
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "charliermarsh.ruff",
+        "EditorConfig.EditorConfig",
+        "esbenp.prettier-vscode",
+        "bradlc.vscode-tailwindcss"
+      ]
+    }
+  }
+}

.eslintignore

@@ -0,0 +1,6 @@
+dist
+node_modules
+.yarn
+.history
+build
+lib

.eslintrc.js

@@ -0,0 +1,403 @@
+const OFF = 0;
+const WARNING = 1;
+const ERROR = 2;
+
+// Prevent importing lodash, usually for browser bundle size reasons
+const LodashImportPatterns = ["lodash", "lodash.**", "lodash/**"];
+
+module.exports = {
+  root: true,
+  env: {
+    browser: true,
+    commonjs: true,
+    node: true,
+  },
+  parser: "@typescript-eslint/parser",
+  parserOptions: {},
+  globals: {
+    JSX: true,
+  },
+  extends: [
+    "eslint:recommended",
+    "plugin:react-hooks/recommended",
+    "airbnb",
+    "plugin:@typescript-eslint/recommended",
+    // 'plugin:@typescript-eslint/recommended-requiring-type-checking',
+    // 'plugin:@typescript-eslint/strict',
+    "plugin:regexp/recommended",
+    "prettier",
+    "plugin:@docusaurus/all",
+  ],
+  settings: {
+    "import/resolver": {
+      node: {
+        extensions: [".js", ".jsx", ".ts", ".tsx"],
+      },
+    },
+  },
+  reportUnusedDisableDirectives: true,
+  plugins: ["react-hooks", "@typescript-eslint", "regexp", "@docusaurus"],
+  rules: {
+    "react/jsx-uses-react": OFF, // JSX runtime: automatic
+    "react/react-in-jsx-scope": OFF, // JSX runtime: automatic
+    "array-callback-return": WARNING,
+    camelcase: WARNING,
+    "class-methods-use-this": OFF, // It's a way of allowing private variables.
+    curly: [WARNING, "all"],
+    "global-require": WARNING,
+    "lines-between-class-members": OFF,
+    "max-classes-per-file": OFF,
+    "max-len": [
+      WARNING,
+      {
+        code: Infinity, // Code width is already enforced by Prettier
+        tabWidth: 2,
+        comments: 80,
+        ignoreUrls: true,
+        ignorePattern: "(eslint-disable|@)",
+      },
+    ],
+    "arrow-body-style": OFF,
+    "no-await-in-loop": OFF,
+    "no-case-declarations": WARNING,
+    "no-console": OFF,
+    "no-constant-binary-expression": ERROR,
+    "no-continue": OFF,
+    "no-control-regex": WARNING,
+    "no-else-return": OFF,
+    "no-empty": [WARNING, { allowEmptyCatch: true }],
+    "no-lonely-if": WARNING,
+    "no-nested-ternary": WARNING,
+    "no-param-reassign": [WARNING, { props: false }],
+    "no-prototype-builtins": WARNING,
+    "no-restricted-exports": OFF,
+    "no-restricted-properties": [
+      ERROR,
+      .../** @type {[string, string][]} */ ([
+        // TODO: TS doesn't make Boolean a narrowing function yet,
+        // so filter(Boolean) is problematic type-wise
+        // ['compact', 'Array#filter(Boolean)'],
+        ["concat", "Array#concat"],
+        ["drop", "Array#slice(n)"],
+        ["dropRight", "Array#slice(0, -n)"],
+        ["fill", "Array#fill"],
+        ["filter", "Array#filter"],
+        ["find", "Array#find"],
+        ["findIndex", "Array#findIndex"],
+        ["first", "foo[0]"],
+        ["flatten", "Array#flat"],
+        ["flattenDeep", "Array#flat(Infinity)"],
+        ["flatMap", "Array#flatMap"],
+        ["fromPairs", "Object.fromEntries"],
+        ["head", "foo[0]"],
+        ["indexOf", "Array#indexOf"],
+        ["initial", "Array#slice(0, -1)"],
+        ["join", "Array#join"],
+        // Unfortunately there's no great alternative to _.last yet
+        // Candidates: foo.slice(-1)[0]; foo[foo.length - 1]
+        // Array#at is ES2022; could replace _.nth as well
+        // ['last'],
+        ["map", "Array#map"],
+        ["reduce", "Array#reduce"],
+        ["reverse", "Array#reverse"],
+        ["slice", "Array#slice"],
+        ["take", "Array#slice(0, n)"],
+        ["takeRight", "Array#slice(-n)"],
+        ["tail", "Array#slice(1)"],
+      ]).map(([property, alternative]) => ({
+        object: "_",
+        property,
+        message: `Use ${alternative} instead.`,
+      })),
+      ...[
+        "readdirSync",
+        "readFileSync",
+        "statSync",
+        "lstatSync",
+        "existsSync",
+        "pathExistsSync",
+        "realpathSync",
+        "mkdirSync",
+        "mkdirpSync",
+        "mkdirsSync",
+        "writeFileSync",
+        "writeJsonSync",
+        "outputFileSync",
+        "outputJsonSync",
+        "moveSync",
+        "copySync",
+        "copyFileSync",
+        "ensureFileSync",
+        "ensureDirSync",
+        "ensureLinkSync",
+        "ensureSymlinkSync",
+        "unlinkSync",
+        "removeSync",
+        "emptyDirSync",
+      ].map((property) => ({
+        object: "fs",
+        property,
+        message: "Do not use sync fs methods.",
+      })),
+    ],
+    "no-restricted-syntax": [
+      WARNING,
+      // Copied from airbnb, removed for...of statement, added export all
+      {
+        selector: "ForInStatement",
+        message:
+          "for..in loops iterate over the entire prototype chain, which is virtually never what you want. Use Object.{keys,values,entries}, and iterate over the resulting array.",
+      },
+      {
+        selector: "LabeledStatement",
+        message:
+          "Labels are a form of GOTO; using them makes code confusing and hard to maintain and understand.",
+      },
+      {
+        selector: "WithStatement",
+        message:
+          "`with` is disallowed in strict mode because it makes code impossible to predict and optimize.",
+      },
+      {
+        selector: "ExportAllDeclaration",
+        message:
+          "Export all does't work well if imported in ESM due to how they are transpiled, and they can also lead to unexpected exposure of internal methods.",
+      },
+      // TODO make an internal plugin to ensure this
+      // {
+      //   selector:
+      // @   'ExportDefaultDeclaration > Identifier, ExportNamedDeclaration[source=null] > ExportSpecifier',
+      //   message: 'Export in one statement'
+      // },
+      ...["path", "fs-extra", "webpack", "lodash"].map((m) => ({
+        selector: `ImportDeclaration[importKind=value]:has(Literal[value=${m}]) > ImportSpecifier[importKind=value]`,
+        message:
+          "Default-import this, both for readability and interoperability with ESM",
+      })),
+    ],
+    "no-template-curly-in-string": WARNING,
+    "no-unused-expressions": [
+      WARNING,
+      { allowTaggedTemplates: true, allowShortCircuit: true },
+    ],
+    "no-useless-escape": WARNING,
+    "no-void": [ERROR, { allowAsStatement: true }],
+    "prefer-destructuring": WARNING,
+    "prefer-named-capture-group": WARNING,
+    "prefer-template": WARNING,
+    yoda: WARNING,
+
+    "import/extensions": OFF,
+    // This rule doesn't yet support resolving .js imports when the actual file
+    // is .ts. Plus it's not all that useful when our code is fully TS-covered.
+    "import/no-unresolved": [
+      OFF,
+      {
+        // Ignore certain webpack aliases because they can't be resolved
+        ignore: [
+          "^@theme",
+          "^@docusaurus",
+          "^@generated",
+          "^@site",
+          "^@testing-utils",
+        ],
+      },
+    ],
+    "import/order": [
+      WARNING,
+      {
+        groups: [
+          "builtin",
+          "external",
+          "internal",
+          ["parent", "sibling", "index"],
+          "type",
+        ],
+        "newlines-between": "always",
+        pathGroups: [
+          // always put css import to the last, ref:
+          // https://github.com/import-js/eslint-plugin-import/issues/1239
+          {
+            pattern: "*.+(css|sass|less|scss|pcss|styl)",
+            group: "unknown",
+            patternOptions: { matchBase: true },
+            position: "after",
+          },
+          { pattern: "react", group: "builtin", position: "before" },
+          { pattern: "react-dom", group: "builtin", position: "before" },
+          { pattern: "react-dom/**", group: "builtin", position: "before" },
+          { pattern: "stream", group: "builtin", position: "before" },
+          { pattern: "fs-extra", group: "builtin" },
+          { pattern: "lodash", group: "external", position: "before" },
+          { pattern: "clsx", group: "external", position: "before" },
+          // 'Bit weird to not use the `import/internal-regex` option, but this
+          // way, we can make `import type { Props } from "@theme/*"` appear
+          // before `import styles from "styles.module.css"`, which is what we
+          // always did. This should be removable once we stop using ambient
+          // module declarations for theme aliases.
+          { pattern: "@theme/**", group: "internal" },
+          { pattern: "@site/**", group: "internal" },
+          { pattern: "@theme-init/**", group: "internal" },
+          { pattern: "@theme-original/**", group: "internal" },
+          { pattern: "@/components/**", group: "internal" },
+          { pattern: "@/libs/**", group: "internal" },
+          { pattern: "@/types/**", group: "type" },
+        ],
+        pathGroupsExcludedImportTypes: [],
+        // example: let `import './nprogress.css';` after importing others
+        // in `packages/docusaurus-theme-classic/src/nprogress.ts`
+        // see more: https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/order.md#warnonunassignedimports-truefalse
+        warnOnUnassignedImports: true,
+      },
+    ],
+    "import/prefer-default-export": OFF,
+
+    "jsx-a11y/click-events-have-key-events": WARNING,
+    "jsx-a11y/no-noninteractive-element-interactions": WARNING,
+    "jsx-a11y/html-has-lang": OFF,
+
+    "react-hooks/rules-of-hooks": ERROR,
+    "react-hooks/exhaustive-deps": ERROR,
+
+    // Sometimes we do need the props as a whole, e.g. when spreading
+    "react/destructuring-assignment": OFF,
+    "react/function-component-definition": [
+      WARNING,
+      {
+        namedComponents: "function-declaration",
+        unnamedComponents: "arrow-function",
+      },
+    ],
+    "react/jsx-filename-extension": OFF,
+    "react/jsx-key": [ERROR, { checkFragmentShorthand: true }],
+    "react/jsx-no-useless-fragment": [ERROR, { allowExpressions: true }],
+    "react/jsx-props-no-spreading": OFF,
+    "react/no-array-index-key": OFF, // We build a static site, and nearly all components don't change.
+    "react/no-unstable-nested-components": [WARNING, { allowAsProps: true }],
+    "react/prefer-stateless-function": WARNING,
+    "react/prop-types": OFF,
+    "react/require-default-props": [
+      ERROR,
+      { ignoreFunctionalComponents: true },
+    ],
+
+    "@typescript-eslint/consistent-type-definitions": OFF,
+    "@typescript-eslint/require-await": OFF,
+
+    "@typescript-eslint/ban-ts-comment": [
+      ERROR,
+      { "ts-expect-error": "allow-with-description" },
+    ],
+    "@typescript-eslint/consistent-indexed-object-style": OFF,
+    "@typescript-eslint/consistent-type-imports": [
+      WARNING,
+      { disallowTypeAnnotations: false },
+    ],
+    "@typescript-eslint/explicit-module-boundary-types": WARNING,
+    "@typescript-eslint/method-signature-style": ERROR,
+    "@typescript-eslint/no-empty-function": OFF,
+    "@typescript-eslint/no-empty-interface": [
+      ERROR,
+      {
+        allowSingleExtends: true,
+      },
+    ],
+    "@typescript-eslint/no-inferrable-types": OFF,
+    "@typescript-eslint/no-namespace": [WARNING, { allowDeclarations: true }],
+    "no-use-before-define": OFF,
+    "@typescript-eslint/no-use-before-define": [
+      ERROR,
+      { functions: false, classes: false, variables: true },
+    ],
+    "@typescript-eslint/no-non-null-assertion": OFF,
+    "no-redeclare": OFF,
+    "@typescript-eslint/no-redeclare": ERROR,
+    "no-shadow": OFF,
+    "@typescript-eslint/no-shadow": ERROR,
+    "no-unused-vars": OFF,
+    // We don't provide any escape hatches for this rule. Rest siblings and
+    // function placeholder params are always ignored, and any other unused
+    // locals must be justified with a disable comment.
+    "@typescript-eslint/no-unused-vars": [ERROR, { ignoreRestSiblings: true }],
+    "@typescript-eslint/prefer-optional-chain": ERROR,
+    "@docusaurus/no-html-links": ERROR,
+    "@docusaurus/prefer-docusaurus-heading": ERROR,
+    "@docusaurus/no-untranslated-text": [
+      WARNING,
+      {
+        ignoredStrings: [
+          "·",
+          "-",
+          "—",
+          "×",
+          "​", // zwj: ​
+          "@",
+          "WebContainers",
+          "Twitter",
+          "GitHub",
+          "Dev.to",
+          "1.x",
+        ],
+      },
+    ],
+  },
+  overrides: [
+    {
+      files: ["packages/*/src/theme/**/*.{js,ts,tsx}"],
+      excludedFiles: "*.test.{js,ts,tsx}",
+      rules: {
+        "no-restricted-imports": [
+          "error",
+          {
+            patterns: LodashImportPatterns.concat(
+              // Prevents relative imports between React theme components
+              [
+                "../**",
+                "./**",
+                // Allows relative styles module import with consistent filename
+                "!./styles.module.css",
+                // Allows relative tailwind css import with consistent filename
+                "!./styles.css",
+              ]
+            ),
+          },
+        ],
+      },
+    },
+    {
+      files: ["packages/*/src/theme/**/*.{js,ts,tsx}"],
+      rules: {
+        "import/no-named-export": ERROR,
+      },
+    },
+    {
+      files: ["*.d.ts"],
+      rules: {
+        "import/no-duplicates": OFF,
+      },
+    },
+    {
+      files: ["*.{ts,tsx}"],
+      rules: {
+        "no-undef": OFF,
+        "import/no-import-module-exports": OFF,
+      },
+    },
+    {
+      files: ["*.{js,mjs,cjs}"],
+      rules: {
+        // Make JS code directly runnable in Node.
+        "@typescript-eslint/no-var-requires": OFF,
+        "@typescript-eslint/explicit-module-boundary-types": OFF,
+      },
+    },
+    {
+      // Internal files where extraneous deps don't matter much at long as
+      // they run
+      files: ["website/**"],
+      rules: {
+        "import/no-extraneous-dependencies": OFF,
+      },
+    },
+  ],
+};

.gitattributes

@@ -0,0 +1 @@
+website/versioned_*/** linguist-documentation

.github/FUNDING.yml

@@ -1,2 +1,2 @@
 open_collective: nonebot
-custom: ["https://afdian.net/@nonebot"]
+custom: ["https://afdian.com/@nonebot"]

.github/ISSUE_TEMPLATE/adapter_publish.yml

@@ -0,0 +1,64 @@
+name: 发布适配器
+title: "Adapter: {name}"
+description: 发布适配器到 NoneBot 官方商店
+labels: ["Adapter", "Publish"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        # 发布须知
+
+        非特殊情况下，请通过 [NoneBot 适配器商店](https://nonebot.dev/store/adapters) 的发布表单进行插件发布信息填写。
+
+  - 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,44 @@
+name: 发布机器人
+title: "Bot: {name}"
+description: 发布机器人到 NoneBot 官方商店
+labels: ["Bot", "Publish"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        # 发布须知
+
+        非特殊情况下，请通过 [NoneBot 机器人商店](https://nonebot.dev/store/bots) 的发布表单进行插件发布信息填写。
+
+  - 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.html
-    about: Publish your plugin to nonebot homepage and nb-cli
-  - name: Adapter Publish
-    url: https://v2.nonebot.dev/store.html
-    about: Publish your adapter to nonebot homepage and nb-cli
-  - name: Bot Publish
-    url: https://v2.nonebot.dev/store.html
-    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,51 @@
+name: 发布插件
+title: "Plugin: {name}"
+description: 发布插件到 NoneBot 官方商店
+labels: ["Plugin", "Publish"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        # 发布须知
+
+        非特殊情况下，请通过 [NoneBot 插件商店](https://nonebot.dev/store/plugins) 的发布表单进行插件发布信息填写。
+        在发布前请阅读 [NoneBot 插件发布流程指导](https://nonebot.dev/docs/developer/plugin-publishing) 并确保满足其中所述条件。
+
+  - type: input
+    id: pypi
+    attributes:
+      label: PyPI 项目名
+      description: PyPI 项目名
+      placeholder: e.g. nonebot-plugin-xxx
+    validations:
+      required: true
+
+  - type: input
+    id: module
+    attributes:
+      label: 插件模块名
+      description: 加载插件时所使用的模块名称
+      placeholder: e.g. nonebot_plugin_apscheduler
+    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/build-api-doc/action.yml

@@ -0,0 +1,9 @@
+name: Build API Doc
+description: Build API Doc
+
+runs:
+  using: "composite"
+  steps:
+    - run: |
+        uv run --no-sync bash ./scripts/build-api-docs.sh
+      shell: bash

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

@@ -0,0 +1,13 @@
+name: Setup Node
+description: Setup Node
+
+runs:
+  using: "composite"
+  steps:
+    - uses: actions/setup-node@v5
+      with:
+        node-version: lts/*
+        cache: yarn
+
+    - run: yarn install --frozen-lockfile
+      shell: bash

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

@@ -0,0 +1,24 @@
+name: Setup Python
+description: Setup Python
+
+inputs:
+  python-version:
+    description: Python version
+    required: false
+    default: "3.12"
+  env-group:
+    description: Environment group
+    required: false
+    default: "pydantic-v2"
+
+runs:
+  using: "composite"
+  steps:
+    - uses: astral-sh/setup-uv@v6
+      with:
+        python-version: ${{ inputs.python-version }}
+        cache-suffix: ${{ inputs.env-group }}
+
+    - run: |
+        uv sync --all-extras --locked --group ${{ inputs.env-group }}
+      shell: bash

.github/dependabot.yml

@@ -0,0 +1,46 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: daily
+    groups:
+      actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: github-actions
+    directory: "/.github/actions/build-api-doc"
+    schedule:
+      interval: daily
+    groups:
+      actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: github-actions
+    directory: "/.github/actions/setup-node"
+    schedule:
+      interval: daily
+    groups:
+      actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: github-actions
+    directory: "/.github/actions/setup-python"
+    schedule:
+      interval: daily
+    groups:
+      actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: devcontainers
+    directory: "/"
+    schedule:
+      interval: daily
+    groups:
+      devcontainers:
+        patterns:
+          - "*"

.github/release-drafter.yml

@@ -1,42 +1,43 @@
-name-template: 'Release v$RESOLVED_VERSION 🌈'
-tag-template: 'v$RESOLVED_VERSION'
+template: $CHANGES
+category-template: "### $TITLE"
+name-template: "Release v$RESOLVED_VERSION 🌈"
+tag-template: "v$RESOLVED_VERSION"
+change-template: "- $TITLE [@$AUTHOR](https://github.com/$AUTHOR) ([#$NUMBER]($URL))"
+change-title-escapes: '\<&'
+exclude-labels:
+  - "dependencies"
+  - "skip-changelog"
 categories:
-  - title: '💥 Breaking Changes'
+  - title: "💥 破坏性变更"
     labels:
-      - 'Breaking'
-  - title: '🚀 Features'
+      - "Breaking"
+  - title: "🚀 新功能"
     labels:
-      - 'feature'
-      - 'enhancement'
-  - title: '🐛 Bug Fixes'
+      - "feature"
+      - "enhancement"
+  - title: "🐛 Bug 修复"
     labels:
-      - 'fix'
-      - 'bugfix'
-      - 'bug'
-  - title: '🍻 Plugin Publish'
-    label: 'Plugin'
-  - title: '🍻 Bot Publish'
-    label: 'Bot'
-  - title: '🍻 Adapter Publish'
-    label: 'Adapter'
-change-template: '- $TITLE @$AUTHOR (#$NUMBER)'
-change-title-escapes: '\<*_&' # You can add # and @ to disable mentions, and add ` to disable code blocks.
+      - "fix"
+      - "bugfix"
+      - "bug"
+  - title: "📝 文档"
+    labels:
+      - "documentation"
+  - title: "💫 杂项"
+  - title: "🍻 插件发布"
+    label: "Plugin"
+  - title: "🍻 机器人发布"
+    label: "Bot"
+  - title: "🍻 适配器发布"
+    label: "Adapter"
 version-resolver:
   major:
     labels:
-      - 'major'
+      - "major"
   minor:
     labels:
-      - 'minor'
+      - "minor"
   patch:
     labels:
-      - 'patch'
+      - "patch"
   default: patch
-template: |
-  ## Documentation
-
-  See: https://v2.nonebot.dev
-
-  ## 💫 Changes
-
-  $CHANGES

.github/workflows/codecov.yml

@@ -2,38 +2,65 @@ name: Code Coverage
 
 on:
   push:
+    branches:
+      - master
   pull_request:
+    paths:
+      - "envs/**"
+      - "nonebot/**"
+      - "packages/**"
+      - "tests/**"
+      - ".github/actions/setup-python/**"
+      - ".github/workflows/codecov.yml"
+      - "pyproject.toml"
+      - "uv.lock"
 
 jobs:
   test:
-    runs-on: ubuntu-latest
-    name: Run Pytest and Upload Coverage
+    name: Test Coverage
+    runs-on: ${{ matrix.os }}
+    concurrency:
+      group: test-coverage-${{ github.ref }}-${{ matrix.os }}-${{ matrix.python-version }}-${{ matrix.env }}
+      cancel-in-progress: true
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        env: [pydantic-v1, pydantic-v2]
+    env:
+      OS: ${{ matrix.os }}
+      PYTHON_VERSION: ${{ matrix.python-version }}
+      PYDANTIC_VERSION: ${{ matrix.env }}
+
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v5
 
-      - name: Set up Python environment
-        uses: actions/setup-python@v2
+      - name: Setup Python environment
+        uses: ./.github/actions/setup-python
         with:
-          python-version: "3.9"
-          architecture: "x64"
-
-      - uses: Gr1N/setup-poetry@v7
-
-      - uses: actions/cache@v2
-        with:
-          path: ~/.cache/pypoetry/virtualenvs
-          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
-
-      - name: Install dependencies
-        run: poetry install -E all
+          python-version: ${{ matrix.python-version }}
+          env-group: ${{ matrix.env }}
 
       - name: Run Pytest
         run: |
-          cd tests/
-          poetry run pytest --cov-report xml
+          uv run --no-sync bash ./scripts/run-tests.sh
+
+      - name: Upload test results
+        uses: codecov/test-results-action@v1
+        with:
+          env_vars: OS,PYTHON_VERSION,PYDANTIC_VERSION
+          files: ./tests/junit.xml
+          flags: unittests
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
       - name: Upload coverage report
-        uses: codecov/codecov-action@v2
+        uses: codecov/codecov-action@v5
         with:
+          env_vars: OS,PYTHON_VERSION,PYDANTIC_VERSION
           files: ./tests/coverage.xml
           flags: unittests
+          fail_ci_if_error: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/noneflow.yml

@@ -0,0 +1,73 @@
+name: NoneFlow
+
+on:
+  issues:
+    types: [opened, reopened, edited]
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [closed]
+  pull_request_review:
+    types: [submitted]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.issue.number && format('publish/issue{0}', github.event.issue.number) || github.head_ref || github.run_id }}
+  cancel-in-progress: ${{ startsWith(github.head_ref, 'publish/issue')}}
+
+jobs:
+  noneflow:
+    runs-on: ubuntu-latest
+    name: noneflow
+    # do not run on forked PRs, do not run on not related issues, do not run on pr comments
+    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
+        )
+      )
+    steps:
+      - name: Generate token
+        id: generate-token
+        uses: tibdex/github-app-token@v2
+        with:
+          app_id: ${{ secrets.APP_ID }}
+          private_key: ${{ secrets.APP_KEY }}
+
+      - name: Checkout Code
+        uses: actions/checkout@v5
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+
+      - name: NoneFlow
+        uses: docker://ghcr.io/nonebot/noneflow:latest
+        with:
+          config: >
+            {
+              "base": "master",
+              "plugin_path": "assets/plugins.json5",
+              "bot_path": "assets/bots.json5",
+              "adapter_path": "assets/adapters.json5",
+              "registry_repository": "nonebot/registry",
+              "artifact_path": "artifact"
+            }
+        env:
+          APP_ID: ${{ secrets.APP_ID }}
+          PRIVATE_KEY: ${{ secrets.APP_KEY }}
+
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: noneflow
+          path: artifact/*
+          if-no-files-found: ignore

.github/workflows/publish-bot.yml

@@ -1,30 +0,0 @@
-name: NoneBot2 Publish Bot
-
-on:
-  push:
-    branches:
-      - master
-  issues:
-    types: [opened, reopened, edited]
-  pull_request:
-    types: [closed]
-
-jobs:
-  publish_bot:
-    runs-on: ubuntu-latest
-    name: nonebot2 publish bot
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v2
-
-      - name: NoneBot2 Publish Bot
-        uses: nonebot/nonebot2-publish-bot@main
-        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"
-            }

.github/workflows/pyright.yml

@@ -0,0 +1,48 @@
+name: Pyright Lint
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    paths:
+      - "envs/**"
+      - "nonebot/**"
+      - "packages/**"
+      - "tests/**"
+      - ".github/actions/setup-python/**"
+      - ".github/workflows/pyright.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+
+jobs:
+  pyright:
+    name: Pyright Lint
+    runs-on: ubuntu-latest
+    concurrency:
+      group: pyright-${{ github.ref }}-${{ matrix.env }}
+      cancel-in-progress: true
+    strategy:
+      matrix:
+        env: [pydantic-v1, pydantic-v2]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Python environment
+        uses: ./.github/actions/setup-python
+        with:
+          env-group: ${{ matrix.env }}
+
+      - run: |
+          echo "$(dirname $(uv python find))" >> $GITHUB_PATH
+          if [ "${{ matrix.env }}" = "pydantic-v1" ]; then
+            sed -i 's/PYDANTIC_V2 = true/PYDANTIC_V2 = false/g' ./pyproject.toml
+          fi
+        shell: bash
+
+      - name: Run Pyright
+        uses: jakebailey/pyright-action@v2
+        with:
+          pylance-version: latest-release

.github/workflows/release-drafter.yml

@@ -0,0 +1,127 @@
+name: Release Drafter
+
+on:
+  push:
+    tags:
+      - v*
+  pull_request_target:
+    branches:
+      - master
+    types:
+      - closed
+
+jobs:
+  update-release-draft:
+    if: github.event_name == 'pull_request_target'
+    runs-on: ubuntu-latest
+    concurrency:
+      group: pull-request-changelog
+      cancel-in-progress: true
+    steps:
+      - name: Generate token
+        id: generate-token
+        uses: tibdex/github-app-token@v2
+        with:
+          app_id: ${{ secrets.APP_ID }}
+          private_key: ${{ secrets.APP_KEY }}
+
+      - uses: actions/checkout@v5
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+
+      - name: Setup Node Environment
+        uses: ./.github/actions/setup-node
+
+      - uses: release-drafter/release-drafter@v6.0.0
+        id: release-drafter
+        env:
+          GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
+
+      - name: Update Changelog
+        uses: docker://ghcr.io/nonebot/auto-changelog:master
+        with:
+          changelog_file: website/src/changelog/changelog.md
+          latest_changes_position: '# 更新日志\n\n'
+          latest_changes_title: "## 最近更新"
+          replace_regex: '(?<=## 最近更新\n)[\s\S]*?(?=\n## )'
+          changelog_body: ${{ steps.release-drafter.outputs.body }}
+          commit_and_push: false
+
+      - name: Commit and Push
+        run: |
+          yarn prettier
+          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
+
+  release:
+    if: startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - name: Generate token
+        id: generate-token
+        uses: tibdex/github-app-token@v2
+        with:
+          app_id: ${{ secrets.APP_ID }}
+          private_key: ${{ secrets.APP_KEY }}
+
+      - uses: actions/checkout@v5
+
+      - name: Setup Python Environment
+        uses: ./.github/actions/setup-python
+
+      - name: Setup Node Environment
+        uses: ./.github/actions/setup-node
+
+      - name: Build API Doc
+        uses: ./.github/actions/build-api-doc
+
+      - name: Get Version
+        id: version
+        run: |
+          echo "VERSION=$(uv version --short)" >> $GITHUB_OUTPUT
+          echo "TAG_VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+          echo "TAG_NAME=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+
+      - name: Check Version
+        if: steps.version.outputs.VERSION != steps.version.outputs.TAG_VERSION
+        run: exit 1
+
+      - uses: release-drafter/release-drafter@v6.0.0
+        with:
+          name: Release ${{ steps.version.outputs.TAG_NAME }} 🌈
+          tag: ${{ steps.version.outputs.TAG_NAME }}
+          publish: true
+        env:
+          GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
+
+      - name: Build Package
+        run: |
+          uv build
+          uv publish
+
+      - name: Publish package to GitHub
+        run: |
+          gh release upload --clobber ${{ steps.version.outputs.TAG_NAME }} dist/*.tar.gz dist/*.whl
+        env:
+          GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}
+
+      - name: Build and Publish Doc Package
+        run: |
+          yarn build:plugin --out-dir ../packages/nonebot-plugin-docs/nonebot_plugin_docs/dist
+          cd packages/nonebot-plugin-docs/
+          uv version ${{ steps.version.outputs.VERSION }}
+          uv build
+          uv publish
+
+      - name: Publish Doc Package to GitHub
+        run: |
+          cd packages/nonebot-plugin-docs/
+          gh release upload --clobber ${{ steps.version.outputs.TAG_NAME }} dist/*.tar.gz dist/*.whl
+        env:
+          GITHUB_TOKEN: ${{ steps.generate-token.outputs.token }}

.github/workflows/release-github.yml

@@ -1,36 +0,0 @@
-name: Release Drafter
-
-on:
-  push:
-    branches:
-      - master
-    tags:
-      - v*
-
-jobs:
-  update-release-draft:
-    if: github.ref == 'refs/heads/master'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-
-      - uses: release-drafter/release-drafter@v5
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-  release:
-    if: startsWith(github.ref, 'refs/tags/')
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-
-      - run: |
-          echo "TAG_NAME=${GITHUB_REF#refs/tags/}" >> $GITHUB_ENV
-
-      - uses: release-drafter/release-drafter@v5
-        with:
-          name: Release ${{ env.TAG_NAME }} 🌈
-          tag: ${{ env.TAG_NAME }}
-          publish: true
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release-plugin-docs.yml

@@ -1,58 +0,0 @@
-name: Release Nonebot Plugin Docs
-
-on:
-  push:
-    tags:
-      - v*
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v2
-
-      - name: Set up Python
-        uses: actions/setup-python@v2
-        with:
-          python-version: "3.9"
-          architecture: "x64"
-
-      - uses: Gr1N/setup-poetry@v7
-
-      - uses: actions/cache@v2
-        with:
-          path: ~/.cache/pypoetry/virtualenvs
-          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
-
-      - name: Setup Node
-        uses: actions/setup-node@v2
-        with:
-          node-version: "16"
-
-      - name: Get yarn cache directory path
-        id: yarn-cache-dir-path
-        run: echo "::set-output name=dir::$(yarn cache dir)"
-
-      - name: Cache Packages
-        uses: actions/cache@v2
-        with:
-          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-
-      - name: Install and build
-        run: |
-          poetry install -E all
-          poetry run sphinx-build -M markdown ./docs_build ./build
-          cp -r ./build/markdown/* ./website/docs/api/
-          yarn install
-          yarn prettier
-          yarn build:plugin --out-dir ../packages/nonebot-plugin-docs/nonebot_plugin_docs/dist
-
-      - name: Publish Package
-        run: |
-          export NONEBOT_VERSION=`poetry version -s`
-          cd packages/nonebot-plugin-docs/
-          poetry version $NONEBOT_VERSION
-          poetry build
-          poetry publish -u ${{secrets.PYPI_USERNAME}} -p ${{secrets.PYPI_PASSWORD}}

.github/workflows/release.yml

@@ -6,64 +6,47 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
-
     steps:
-      - uses: actions/checkout@v2
+      - name: Generate token
+        id: generate-token
+        uses: tibdex/github-app-token@v2
         with:
-          ref: master
-          token: ${{ secrets.GH_TOKEN }}
+          app_id: ${{ secrets.APP_ID }}
+          private_key: ${{ secrets.APP_KEY }}
 
-      - name: Set up Python
-        uses: actions/setup-python@v2
+      - uses: actions/checkout@v5
         with:
-          python-version: "3.9"
-          architecture: "x64"
+          token: ${{ steps.generate-token.outputs.token }}
 
-      - uses: Gr1N/setup-poetry@v7
+      - name: Setup Python Environment
+        uses: ./.github/actions/setup-python
 
-      - uses: actions/cache@v2
+      - name: Setup Node Environment
+        uses: ./.github/actions/setup-node
+
+      - name: Build API Doc
+        uses: ./.github/actions/build-api-doc
+
+      - run: echo "TAG_NAME=v$(uv version --short)" >> $GITHUB_ENV
+
+      - name: Archive Changelog
+        uses: docker://ghcr.io/nonebot/auto-changelog:master
         with:
-          path: ~/.cache/pypoetry/virtualenvs
-          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
-
-      - name: Setup Node
-        uses: actions/setup-node@v2
-        with:
-          node-version: "16"
-
-      - name: Get yarn cache directory path
-        id: yarn-cache-dir-path
-        run: echo "::set-output name=dir::$(yarn cache dir)"
-
-      - name: Cache Packages
-        uses: actions/cache@v2
-        with:
-          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-
-      - name: Set up dependencies
-        run: |
-          poetry install -E all
-
-      - name: Build Doc
-        run: poetry run sphinx-build -M markdown ./docs_build ./build
-
-      - name: Copy Files
-        run: cp -r ./build/markdown/* ./website/docs/api/
+          changelog_file: website/src/changelog/changelog.md
+          archive_regex: '(?<=## )最近更新(?=\n)'
+          archive_title: ${{ env.TAG_NAME }}
+          commit_and_push: false
 
       - name: Archive Files
         run: |
-          yarn install
+          yarn archive $(uv version --short)
           yarn prettier
-          yarn archive $(poetry version -s)
 
-      - name: Push Tag and Release to PyPI
+      - name: Push Tag
         run: |
-          git config user.name github-actions
-          git config user.email github-actions@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 v$(poetry version -s)
+          git commit -m ":bookmark: Release $(uv version --short)"
+          git tag ${{ env.TAG_NAME }}
           git push && git push --tags
-          poetry build
-          poetry publish -u ${{secrets.PYPI_USERNAME}} -p ${{secrets.PYPI_PASSWORD}}

.github/workflows/ruff.yml

@@ -0,0 +1,30 @@
+name: Ruff Lint
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    paths:
+      - "envs/**"
+      - "nonebot/**"
+      - "packages/**"
+      - "tests/**"
+      - ".github/actions/setup-python/**"
+      - ".github/workflows/ruff.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+
+jobs:
+  ruff:
+    name: Ruff Lint
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ruff-${{ github.ref }}
+      cancel-in-progress: true
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Run Ruff Lint
+        uses: astral-sh/ruff-action@v3

.github/workflows/website-deploy.yml

@@ -1,83 +1,46 @@
-name: Build Upload Site
+name: Site Deploy
 
 on:
   push:
-  pull_request_target:
+    branches:
+      - master
 
 jobs:
   publish:
     runs-on: ubuntu-latest
+    concurrency:
+      group: website-deploy-${{ github.ref }}
+      cancel-in-progress: true
 
     steps:
-      - uses: actions/checkout@v2
-        if: github.event_name == 'push'
-
-      - uses: actions/checkout@v2
-        if: github.event_name != 'push'
+      - uses: actions/checkout@v5
         with:
-          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
 
-      - name: Set up Python
-        uses: actions/setup-python@v2
-        with:
-          python-version: 3.8
-          architecture: "x64"
+      - name: Setup Python Environment
+        uses: ./.github/actions/setup-python
 
-      - uses: Gr1N/setup-poetry@v7
+      - name: Setup Node Environment
+        uses: ./.github/actions/setup-node
 
-      - uses: actions/cache@v2
-        with:
-          path: ~/.cache/pypoetry/virtualenvs
-          key: ${{ runner.os }}-poetry-${{ hashFiles('**/poetry.lock') }}
+      - name: Build API Doc
+        uses: ./.github/actions/build-api-doc
 
-      - name: Setup Node
-        uses: actions/setup-node@v2
-        with:
-          node-version: "16"
-
-      - name: Get yarn cache directory path
-        id: yarn-cache-dir-path
-        run: echo "::set-output name=dir::$(yarn cache dir)"
-
-      - name: Cache Packages
-        uses: actions/cache@v2
-        with:
-          path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
-          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-
-      - name: Install and build
-        run: |
-          poetry install -E all
-          poetry run sphinx-build -M markdown ./docs_build ./build
-          cp -r ./build/markdown/* ./website/docs/api/
-          yarn install
-          yarn prettier
-          yarn build
+      - name: Build Doc
+        run: yarn build
 
       - name: Get Branch Name
         run: echo "BRANCH_NAME=$(echo ${GITHUB_REF#refs/heads/})" >> $GITHUB_ENV
 
-      - name: Get Deploy Name
-        if: github.event_name == 'push'
-        run: |
-          echo "DEPLOY_NAME=${{ env.BRANCH_NAME }}" >> $GITHUB_ENV
-          echo "PRODUCTION=${{ env.BRANCH_NAME == 'master' }}" >> $GITHUB_ENV
-
-      - name: Get Deploy Name
-        if: github.event_name != 'push'
-        run: |
-          echo "DEPLOY_NAME=deploy-preview-${{ github.event.number }}" >> $GITHUB_ENV
-          echo "PRODUCTION=false" >> $GITHUB_ENV
-
       - name: Deploy to Netlify
-        uses: nwtgck/actions-netlify@v1
+        uses: nwtgck/actions-netlify@v3
         with:
-          publish-dir: './website/build'
-          production-deploy: ${{ env.PRODUCTION }}
+          publish-dir: "./website/build"
+          production-deploy: true
           github-token: ${{ secrets.GITHUB_TOKEN }}
-          deploy-message: 'Deploy ${{ env.DEPLOY_NAME }}@${{ github.sha }}'
+          deploy-message: "Deploy ${{ env.BRANCH_NAME }}@${{ github.sha }}"
           enable-commit-comment: false
-          alias: ${{ env.DEPLOY_NAME }}
+          alias: ${{ env.BRANCH_NAME }}
         env:
           NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
           NETLIFY_SITE_ID: ${{ secrets.SITE_ID }}

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

@@ -0,0 +1,104 @@
+name: Site Deploy (Preview CD)
+
+on:
+  workflow_run:
+    workflows: ["Site Deploy (Preview CI)"]
+    types:
+      - completed
+
+jobs:
+  preview-cd:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: pull-request-preview-${{ github.event.workflow_run.head_repository.full_name }}-${{ github.event.workflow_run.head_branch }}
+      cancel-in-progress: true
+
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+
+    environment: pull request
+
+    permissions:
+      actions: read
+      statuses: write
+      pull-requests: write
+
+    steps:
+      - name: Set Commit Status
+        uses: actions/github-script@v8
+        with:
+          script: |
+            github.rest.repos.createCommitStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              sha: context.payload.workflow_run.head_sha,
+              context: 'Website Preview',
+              description: 'Deploying...',
+              state: 'pending',
+            })
+
+      - name: Download Artifact
+        uses: actions/download-artifact@v5
+        with:
+          name: website-preview
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          run-id: ${{ github.event.workflow_run.id }}
+
+      - name: Restore Context
+        run: |
+          PR_NUMBER=$(cat ./pr-number)
+          if ! [[ "${PR_NUMBER}" =~ ^[0-9]+$ ]]; then
+            echo "Invalid PR number: ${PR_NUMBER}"
+            exit 1
+          fi
+          echo "PR_NUMBER=${PR_NUMBER}" >> "${GITHUB_ENV}"
+
+      - name: Set Deploy Name
+        run: |
+          echo "DEPLOY_NAME=deploy-preview-${PR_NUMBER}" >> "${GITHUB_ENV}"
+
+      - name: Deploy to Netlify
+        id: deploy
+        uses: nwtgck/actions-netlify@v3
+        with:
+          publish-dir: ./website/build
+          production-deploy: false
+          deploy-message: "Deploy ${{ env.DEPLOY_NAME }}@${{ github.event.workflow_run.head_sha }}"
+          alias: ${{ env.DEPLOY_NAME }}
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+          NETLIFY_SITE_ID: ${{ secrets.SITE_ID }}
+
+      # action netlify has no pull request context, so we need to comment by ourselves
+      - name: Comment on Pull Request
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: website
+          number: ${{ env.PR_NUMBER }}
+          message: |
+            :rocket: Deployed to ${{ steps.deploy.outputs.deploy-url }}
+
+      - name: Set Commit Status
+        uses: actions/github-script@v8
+        if: always()
+        with:
+          script: |
+            if (`${{ job.status }}` === 'success') {
+              github.rest.repos.createCommitStatus({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                sha: context.payload.workflow_run.head_sha,
+                context: 'Website Preview',
+                description: `Deployed to ${{ steps.deploy.outputs.deploy-url }}`,
+                state: 'success',
+                target_url: `${{ steps.deploy.outputs.deploy-url }}`,
+              })
+            } else {
+              github.rest.repos.createCommitStatus({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                sha: context.payload.workflow_run.head_sha,
+                context: 'Website Preview',
+                description: `Deploy ${{ job.status }}`,
+                state: 'failure',
+              })
+            }

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

@@ -0,0 +1,42 @@
+name: Site Deploy (Preview CI)
+
+on:
+  pull_request:
+
+jobs:
+  preview-ci:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: pull-request-preview-${{ github.event.number }}
+      cancel-in-progress: true
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+
+      - name: Setup Python Environment
+        uses: ./.github/actions/setup-python
+
+      - name: Setup Node Environment
+        uses: ./.github/actions/setup-node
+
+      - name: Build API Doc
+        uses: ./.github/actions/build-api-doc
+
+      - name: Build Doc
+        run: yarn build
+
+      - name: Export Context
+        run: |
+          echo "${{ github.event.pull_request.number }}" > ./pr-number
+
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: website-preview
+          path: |
+            ./website/build
+            ./pr-number
+          retention-days: 1

.gitignore

@@ -7,6 +7,7 @@ docs_build/_build
 !tests/.env
 .docusaurus
 website/docs/api/**/*.md
+website/src/pages/changelog/**/*
 
 # Created by https://www.toptal.com/developers/gitignore/api/python,node,visualstudiocode,jetbrains,macos,windows,linux
 # Edit at https://www.toptal.com/developers/gitignore?templates=python,node,visualstudiocode,jetbrains,macos,windows,linux
@@ -139,7 +140,7 @@ fabric.properties
 .LSOverride
 
 # Icon must end with two \r
-Icon
+# Icon
 
 # Thumbnails
 ._*

.markdownlint.yaml

@@ -0,0 +1,4 @@
+MD013: false
+MD024: # 重复标题
+  siblings_only: true
+MD033: false # 允许 html

.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+default_install_hook_types: [pre-commit, prepare-commit-msg]
+ci:
+  autofix_commit_msg: ":rotating_light: auto fix by pre-commit hooks"
+  autofix_prs: true
+  autoupdate_branch: master
+  autoupdate_schedule: monthly
+  autoupdate_commit_msg: ":arrow_up: auto update by pre-commit hooks"
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.11
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+        stages: [pre-commit]
+      - id: ruff-format
+        stages: [pre-commit]
+
+  - repo: https://github.com/nonebot/nonemoji
+    rev: v0.1.4
+    hooks:
+      - id: nonemoji
+        stages: [prepare-commit-msg]

.prettierignore

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

.prettierrc

@@ -5,5 +5,17 @@
   "arrowParens": "always",
   "singleQuote": false,
   "trailingComma": "es5",
-  "semi": true
+  "semi": true,
+  "overrides": [
+    {
+      "files": [
+        "**/devcontainer.json",
+        "**/tsconfig.json",
+        "**/tsconfig.*.json"
+      ],
+      "options": {
+        "parser": "json"
+      }
+    }
+  ]
 }

.stylelintrc.js

@@ -0,0 +1,31 @@
+module.exports = {
+  extends: ["stylelint-config-standard", "stylelint-prettier/recommended"],
+  overrides: [
+    {
+      files: ["*.css"],
+      rules: {
+        "function-no-unknown": [true, { ignoreFunctions: ["theme"] }],
+        "selector-class-pattern": [
+          "^([a-z][a-z0-9]*)(-[a-z0-9]+)*$",
+          {
+            resolveNestedSelectors: true,
+            message: (selector) =>
+              `Expected class selector "${selector}" to be kebab-case`,
+          },
+        ],
+      },
+    },
+    {
+      files: ["*.module.css"],
+      rules: {
+        "selector-class-pattern": [
+          "^[a-z][a-zA-Z0-9]+$",
+          {
+            message: (selector) =>
+              `Expected class selector "${selector}" to be lowerCamelCase`,
+          },
+        ],
+      },
+    },
+  ],
+};

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/changelog/changelog.md) or <https://nonebot.dev/changelog>

CITATION.cff

@@ -0,0 +1,26 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: NoneBot
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - given-names: Yongyu
+    family-names: Yan
+    email: yyy@nonebot.dev
+  - name: NoneBot Team
+    email: contact@nonebot.dev
+    website: 'https://github.com/nonebot'
+repository-code: 'https://github.com/nonebot/nonebot2'
+url: 'https://nonebot.dev/'
+abstract: >-
+  NoneBot, an asynchronous multi-platform chatbot framework
+  written in Python
+keywords:
+  - nonebot
+  - chatbot
+  - pydantic
+license: MIT

CODE_OF_CONDUCT.md

@@ -0,0 +1,86 @@
+# NoneBot2 贡献者公约
+
+## 我们的承诺
+
+身为项目成员、贡献者、负责人，我们保证参与此社区的每个人都不受骚扰，不论其年龄、体型、身体条件、民族、性征、性别认同与表现、经验水平、教育程度、社会地位、国籍、相貌、种族、宗教信仰及性取向如何。
+
+我们承诺致力于建设开放、友善、多元、包容、健康的社区环境。
+
+## 我们的准则
+
+有助于促进本社区积极环境的行为包括但不限于：
+
+- 与人为善、推己及人
+- 尊重不同的主张、观点和经历
+- 积极提出、耐心接受有益批评
+- 面对过失，承担责任、认真道歉、从中学习
+- 关注社区共同诉求，而非一己私利
+
+不当行为包括但不限于：
+
+- 发布与性有关的言论或图像，以及任何形式的献殷勤或勾引
+- 挑衅行为、侮辱或贬损的言论、人身及政治攻击
+- 公开或私下骚扰
+- 未获明确授权擅自发布他人的资料，如地址、电子邮箱等
+- 其他有理由认定为违反职业操守的不当行为
+
+## 落实之义务
+
+社区负责人有责任诠释什么是“妥当行为”，并据此准则，妥善公正地认定与处置不当、威胁、冒犯及有害的行为。
+
+社区负责人有权利和义务删除、编辑、拒绝违背本公约的评论（comment）、提交（commit）、代码、维基（wiki）编辑、问题（issue）等贡献。如有必要，需告知采取措施的理由。
+
+## 适用范围
+
+此行为标准适用于本社区全部场合，以及在其他场合代表本社区的个人。
+
+代表本社区的情形包括但不限于：使用官方电子邮件与社交平台、作为指定代表参与在线或线下活动。
+
+## 贯彻落实
+
+如遇滥用、骚扰等不当行为，请通过 contact@nonebot.dev 向我们举报。我们将迅速审议并调查全部投诉。
+
+社区全体负责人有义务保密举报者信息。
+
+## 指导方针
+
+社区负责人将依据下列方案判断并处置违纪行为：
+
+### 一、督促
+
+**社区影响**：用语不当、举止不符合道德或不受社区欢迎。
+
+**处理意见**：由社区负责人予以非公开的书面警告，阐明违纪事由、解释举止如何不妥。或要求公开道歉。
+
+### 二、警告
+
+**社区影响**：一起或多起事件中的违纪行为。
+
+**处理意见**：警告继续违纪的后果、违纪者在特定时间内禁止与当事人往来、不得擅自与社区执法者往来，禁令涵盖社区内外、社交网络在内的一切联络。如有违反，可致封禁乃至开除。
+
+### 三、封禁
+
+**社区影响**：严重违纪行为，包括屡教不改。
+
+**处理意见**：违纪者在特定时间内禁止与社区的任何往来或公开联络，禁止任何与当事人公开或私下往来，不得擅自与社区管理者往来。如有违反，可导致开除。
+
+### 四、开除
+
+**社区影响**：典型违纪行为，例如屡教不改、骚扰某个人、敌对或贬低某个群体。
+
+**处理意见**：无限期禁止违纪者与项目社区的一切公开往来。
+
+## 来源
+
+本行为标准改编自[参与者公约][homepage]2.0 版，可在此查阅：[https://www.contributor-covenant.org/zh-cn/version/2/0/code_of_conduct.html][v2.0]
+
+指导方针借鉴自[Mozilla 纪检分级][mozilla coc]。
+
+此行为标准常见问题请洽：[https://www.contributor-covenant.org/faq][faq]。
+另有诸译本：[https://www.contributor-covenant.org/translations][translations]。
+
+[homepage]: https://www.contributor-covenant.org
+[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html
+[mozilla coc]: https://github.com/mozilla/diversity
+[faq]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# NoneBot2 贡献指南
+
+首先，感谢你愿意为 NoneBot2 贡献自己的一份力量！
+
+本指南旨在引导你更规范地向 NoneBot2 提交贡献，请务必认真阅读。
+
+## 提交 Issue
+
+在提交 Issue 前，我们建议你先查看 [FAQ](https://github.com/nonebot/discussions/discussions/13) 与 [已有的 Issues](https://github.com/nonebot/nonebot2/issues)，以防重复提交。
+
+### 报告问题、故障与漏洞
+
+如果你在使用过程中发现问题并确信是由 NoneBot2 引起的，欢迎提交 Issue。
+
+### 建议功能
+
+为了让开发者更好地理解你的意图，请认真描述你所需要的特性，可能的话可以提出你认为可行的解决方案。
+
+## Pull Request
+
+NoneBot 使用 [uv](https://docs.astral.sh/uv/) 管理项目依赖，由于 pre-commit 也经其管理，所以在此一并说明。
+
+下面的命令能在已安装 uv 和 yarn 的情况下帮你快速配置开发环境。
+
+```bash
+# 安装 python 依赖
+uv sync --all-extras
+# 安装 pre-commit git hook
+uv run pre-commit install
+```
+
+### 使用 GitHub Codespaces（Dev Container）
+
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=master&repo=289605524)
+
+### Commit 规范
+
+请确保你的每一个 commit 都能清晰地描述其意图，一个 commit 尽量只有一个意图。
+
+NoneBot 的 commit message 格式遵循 [gitmoji](https://gitmoji.dev/) 规范，在创建 commit 时请牢记这一点。
+
+或者使用 [nonemoji](https://github.com/nonebot/nonemoji) 代替 git 进行 commit，nonemoji 已默认作为项目开发依赖安装。
+
+```bash
+nonemoji commit [-e EMOJI] [-m MESSAGE] [-- ...]
+```
+
+### 工作流概述
+
+`master` 分支为 NoneBot 的开发分支，在任何情况下都请不要直接修改 `master` 分支，而是创建一个目标分支为 `nonebot:master` 的 Pull Request 来提交修改。Pull Request 标题请尽量更改成中文，以便自动生成更新日志。
+
+如果你不是 NoneBot 团队的成员，可在 fork 本仓库后，向本仓库的 `master` 分支发起 Pull Request，注意遵循先前提到的 commit message 规范创建 commit。我们将在 code review 通过后通过 squash merge 方式将您的贡献合并到主分支。
+
+### 撰写文档
+
+NoneBot2 的文档使用 [docusaurus](https://docusaurus.io/)，它有一些 [Markdown 特性](https://docusaurus.io/zh-CN/docs/markdown-features) 可能会帮助到你。
+
+如果你需要在本地预览修改后的文档，可以使用 yarn 安装文档依赖后启动 dev server，如下所示：
+
+```bash
+yarn install
+yarn start
+```
+
+NoneBot2 文档并没有具体的行文风格规范，但我们建议你尽量写得简单易懂。
+
+以下是比较重要的编写与排版规范。目前 NoneBot2 文档中仍有部分文档不完全遵守此规范，如果在阅读时发现欢迎提交 PR。
+
+1. 中文与英文、数字、半角符号之间需要有空格。例：`NoneBot2 是一个可扩展的 Python 异步机器人框架。`
+2. 若非英文整句，使用全角标点符号。例：`现在你可以看到机器人回复你：“Hello, World !”。`
+3. 直引号`「」`和弯引号`“”`都可接受，但同一份文件里应使用同种引号。
+4. **不要使用斜体**，你不需要一种与粗体不同的强调。除此之外，你也可以考虑使用 docusaurus 提供的[告示](https://docusaurus.io/zh-CN/docs/markdown-features/admonitions)功能。
+5. 文档中应以“我们”指代机器人开发者，以“机器人用户”指代机器人的使用者。
+
+以上由[社区创始人 richardchien 的中文排版规范](https://stdrc.cc/style-guides/chinese)补充修改得到。
+
+如果你需要编辑器检查 Markdown 规范，可以在 VSCode 中安装 markdownlint 扩展。
+
+### 参与开发
+
+NoneBot2 的代码风格遵循 [PEP 8](https://www.python.org/dev/peps/pep-0008/) 与 [PEP 484](https://www.python.org/dev/peps/pep-0484/) 规范，请确保你的代码风格和项目已有的代码保持一致，变量命名清晰，有适当的注释与测试代码。
+
+## 为社区做贡献
+
+你可以在 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,34 +19,62 @@ _✨ 跨平台 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.7.3+-blue" alt="python">
+  <img src="https://img.shields.io/badge/python-3.9+-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"/>
+    <img src="https://codecov.io/gh/nonebot/nonebot2/branch/master/graph/badge.svg?token=2P0G0VS7N4" alt="codecov"/>
+  </a>
+  <a href="https://github.com/nonebot/nonebot2/actions/workflows/website-deploy.yml">
+    <img src="https://github.com/nonebot/nonebot2/actions/workflows/website-deploy.yml/badge.svg?branch=master&event=push" alt="site"/>
+  </a>
+  <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="cqhttp">
+    <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">
   </a>
-  <a href="http://github.com/mamoe/mirai">
-    <img src="https://img.shields.io/badge/mirai-HTTP-lightgrey?style=social">
-  </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="ding">
-  </a>
-  <a href="https://core.telegram.org/bots/api">
-    <img src="https://img.shields.io/badge/telegram-Bot-lightgrey?style=social&logo=telegram">
-  </a>
-  <a href="https://open.feishu.cn/document/home/index">
-    <img src="https://img.shields.io/badge/%E9%A3%9E%E4%B9%A6-Bot-lightgrey?style=social&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAMAAACahl6sAAAAk1BMVEX///8zMzNJSUlSUlJcXFxtbW0zMzNLS0szMzMzMzNBQUGVlZUzMzM1NTU0NDQzMzMzMzM0NDQ0NDQ0NDQ3NzdDQ0M0NDQ2NjY4ODg9PT0zMzM0NDQ5OTk7OzszMzM0NDQ3NzczMzM0NDQ0NDQ0NDQ0NDQ3Nzc2NjY4ODg2NjY7Ozs0NDQ6Ojo6Ojo3Nzc4ODgzMzNGdMWJAAAAMHRSTlMD6h0TDgr8GNf0KQbvhLT45KKTmm4jwHVJLdLFQzbcjFTgzsq7rl58T2kyqD46Y1riMDRhAAAFr0lEQVR42uzZWXKiUACF4YMyqKAQhyjOc7STmLP/1bVlLukESIJ3sLGKbwFU/Q8HuIBKpVKpVCqVSqVSqVQqlUqlUvmNM10Mcfda/U6TPdw3e9lb8ayLO+bPniYu+amjNcPd8U7PFhML0RE5uCvnaY/5SVt0WFvckcu0vxjiYmDxbu5cl2mn9UVHRMa4B2LaP3RYKD1vL6adccRFLSLL/izxxbRz7UXHimdLlFdq2mlvnztYRznZh96cP3G/dkxQRrOnR5c/c5eiQ+S2UTbe/sHir9zD1w6+okz8aXvMItyRqE46ApSHmHYRYdLRoPCMcrAP3TkLC6fpDp5QAn/EtItqij3UG/zgQZH5aWc7ZqJjzA9jKFGf9ppXC3I6uMB/Mzh2mpQQ/Mnp4BSy1Kctx4pFx5qfhA4kqE87pCyrldfBDm6sLqat2mGnttXHDfkvYtryooHo2PCrFm5lcNw1qWr1XUeEm7BH3QYVRJNGcOmoietNmNKDWeKFnCo6b3Wc1drW/NsOLpFRqmmT4xgfPFw42Q7XhkFi2kq2DtKcR2Y8wpTacRdQ3aZYB59ggiOmrS6sFevgDNr9GW6pzRAZdsQsC3rV3x4i6uQha8+sB2h9am9c6rVBDj9ixr5k007rIs+CGV65pl3wXjRi2hrKYjFtM/rI02JaW3XaPYtGtZHHY9qL0lN7QuO2yBMzpenLTvtkZNos+AY1ZcpObtoLtWmrj6TNlCOuJqZ9M3PkaDBlIBHCmwpHyHpjSgMS2ryhcIqsmsWULmR0eTPhK7LsMdMOKHdJM+nw8E+8ZoYDOT3eRDDDuz6HNt7VeszaQtYDJch+38WRZ51TDO+0Y54hylzy0XHib2JI83c0zIoLd1hAeUus1jenQe2HQ79Dg6wB3i1d/uoNpS2JrulgHWqcRxqySjoObrFjfUlLVrVrOtiGMmdCA+ZJx8hlEa9QZ2+oXcNLOkIWEUAHe22sYxqykGdoUV//5w6eoKlkTI3Gdbx7CVmQB10lDWqzSTpemyyoAW28ubYO++oOLqBPbUUtJknHrMnCRihdyaOTdAQsLHSgtSTS2BEHLK4DvQYWFW2lOtiHZi3Fko6fXCjgNVooV0nHl7tMBP1aAaXtJDvYgwGxdMmzLzu1JUyYNSU7IAwiiZ8OJrxKlTzI38QnMORFoqSn8Fh9gikvIa/UVejgDMZMQ9mOOa8WwKCRyysslF6hn2HSwZX4+ew1KGEPCSZKhoqHMw9mLd1rO8aUMYZpexbRV/2AsYBxy7/t3NtuglAQheFR6wEPVEQtaq1WxQNqnfd/urY08QJFYHZS15D9vcHckMzOz/QWA9/3jqHrbmbr1bT10a90ncQcoiclgKY/Vq81q6P2JJqfI+NHPqdDSMRzsEtIXmYGcQcQk2fwKgHxTCIVJGMWwTu6sWGxPSFx+QpkOfz3QcYEJWQhtGsbR5aKCIrHInjXNsSDeITFZ6ELYZEMAnltY8AyawKz4KJAr21IBzkRmB6LOIRGOEhIaHYsciA0uxIshwa/DLQIzrAEy2HswBIBwck9yNOvbWT4YgHEU4zbEiyHsQsXhnmKccmxp2cbxvb8CyDbMBXwD4hsw1BQguUw9s4Mk20YOTFQtmHiDJVtGJhjZRtyEVi2ITbhnLBOMd5qOvqXwz9RFy3bkJpU0LINeTCsJdvIztHVZhsJo77SbOPG6FNltpFQqMxsE7hmS+9ymJxE7XKYUGupyzZS1Kbaso00tbWybONBTadyObyjPlaVbTycRFO28Uh9oyjbEJ/E2JImnVDXy1y6zpHvW5E2npJsI5unI9vIwVe3HKYZaMg2clkoyDby6Wl5mcv0Bp9t5DVEzzZyG4JnG/kdsLONArbQ2UYRlwZwtlHIsoGbbRSdRNtymGbf0LYcpgleQbMNwdUCbcthmrP2j++VjqdSy7Isy7Isy4LxDTcBnqEPd5jdAAAAAElFTkSuQmCC" alt="feishu">
+  <a href="https://onebot.dev/">
+    <img src="https://img.shields.io/badge/OneBot-v12-black?style=social&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABABAMAAABYR2ztAAAAIVBMVEUAAAAAAAADAwMHBwceHh4UFBQNDQ0ZGRkoKCgvLy8iIiLWSdWYAAAAAXRSTlMAQObYZgAAAQVJREFUSMftlM0RgjAQhV+0ATYK6i1Xb+iMd0qgBEqgBEuwBOxU2QDKsjvojQPvkJ/ZL5sXkgWrFirK4MibYUdE3OR2nEpuKz1/q8CdNxNQgthZCXYVLjyoDQftaKuniHHWRnPh2GCUetR2/9HsMAXyUT4/3UHwtQT2AggSCGKeSAsFnxBIOuAggdh3AKTL7pDuCyABcMb0aQP7aM4AnAbc/wHwA5D2wDHTTe56gIIOUA/4YYV2e1sg713PXdZJAuncdZMAGkAukU9OAn40O849+0ornPwT93rphWF0mgAbauUrEOthlX8Zu7P5A6kZyKCJy75hhw1Mgr9RAUvX7A3csGqZegEdniCx30c3agAAAABJRU5ErkJggg==" alt="onebot">
   </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/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAMAAACdt4HsAAAC+lBMVEUAAAApRHRAbvYyVI4dMlsNGjcvTH5anN0/a5xdo+Vdpvpms/dMfvdcoPZjr/hJfu5krvA9Z+8/a+M9adxQjNdYmdVAbdU4XtRRjcxFd8wyVbM+aZowUJwpRJlZneRIevU5YORWl+1fqOZVle9ZnOpEdOk/aelepus/a+NQiuVKgeQ6YeRQi905X91EdtxAbthZnNlRjdk5YdpQjuhLgehhquc7Y+c6Y8k3XctWlcs0V8tJfMMzVsM9aMJVksdHebVKgLQyVJknP5REdKD///9irv9Ccf5EdP9GfP9jsf7+/f5SkP9mtf9GeP/+/vxJfv5Ukv9Ng/9boP9Gef1ls/9Ulf9Wl//+//5KgP9Nhv9dpP9Oiv9Tk/5Abv9Lg/9Fdv9NiP7///5Qj/7+/fxfpv9Nh/xhq/9QjP9Wm/79//1co/9ir/5fqf5bov9Qi//8/f1XmP1Wl/1ksv/7/v38/vv9/vlgqv9Znf9IfPzZ5fdeqP9nt/5anv5Xmf9Uk/1anvxpuf73/P34+/tot/9hrf1anvpMhvpSjv1pt/9ZnP1aofxTkfxNivza5/dOhPf+//1Ri/z+//vz+fvw9/tIf/v6/fpdofrI2PlYmfnF3Pe0y/Pm7/jW4/e0zvRapPxXlfpTkvpGevri7ffS3vVMiP5XnvxXnPtQivn3/Ph0r/dgpPZ1qfXi6/S9z/NYmf/z+v5Yn/7L2vlfmflUk/hXi/dRgvSw0fGnu+1dqP3t9Pthq/vA1vjc6vfU4vd4sfdepPdsn/dam/fU5fawzfRjjfRhi/NJhP0/a/y80fhTjfhrrfeXvvZuk/WyyPR9rvSqz/OcwfOmv/OSuPO0yfKguPCWr/BPi+9MheRKgv1gsPzq9PpgpvpVjvrN2/jG1vdonvbA0PSrx/OtxPCkxPDp8PvN4ftnuPuCufloqPiex/a3z/WPuvWQqvR2mfRplvReivSOqvOKufKGufKCrPKBoPJzlfFjr+88Ze6ftux8nOxxq/SGr/CFr/Cvx+3R19+QAAAARHRSTlMAEP4ZEwUEvC3S/v7+/Pv08PDXvJqampqSgEtJLS3f/Pz4+O/n5+bl4tTU1Lq6ure2trGdnZ2dlI6Afl5eXldMS0lJLRAR2gcAAAewSURBVFjDlZcFfBJRHMdvdnd3d3cn1qk3h4Et7EQ965h3KKgTQUGdOgYMHII6a5vO2d3d3d3d3X4+/t974A51xvfDu7vfP348HsdxR6VAulaN6lUu8SHVgQOpPpSoXK9Rq3TUf5CmSdWcB/oFcCBn1SZp/rG9aP6c/X5LzvxF/6W9Vqq2KZKq1t8sgvKT9pQt8gf9qb9QOVLWjux+K8oVSrE9bYNU7f6BVA3SpjD93O3+kdy//Ripcw34QefOnaViwM8iV+rf9Ffo7Kdr166du87vSgQGZGcIJocq/OIQlAv1EbAHDL/0hXzOhFxBP61f7vbJdJ0PFfN1RBB0MIPAUO7Alazvz+l0WY4+Pbthw4az66QG63Do6dEsuh+W9QO+//moVRet071L8phomUzBGPcGBwe3hxdmn5FVyGS0yZP0TodpHzy/kGQBygYjonUvbtpFraDwGUjYZ2JRVNSKK26+0EXjWNnkZciH26OjPy3gOZ5nVVCq+p0BzfK8wC/4FB2MLfL5+4sU7wkER7/dhN6aYxia0zKmvT0l7DUxHE1zHMcoVLJNb6ODUbB4EYpQHddcPHpXK5OpWNHp8CxbtmzmPqnBvpnLAIeTQdPT3j16EUer+yaQpT8i8pqAVi9h4cu1kZGR69bt7y9h/7p1EFz7cmEC+iTiwkgczUKmkC8ECkIs54wiI4j2j5EXQwj9QyCBNgCRIZbIj3ZRYET+nCVkP4TwKqTJHoJTXlbFscZzlv6WXr1CkpGKXhb0PozVynoj1SiTHV3lmvYC1JZnCQzNOG9a1BY1aAlKqbBYLEm8jWYSnpGypmBQTQ0sUp9iVCqr/bl60SK1UqlchIIzYCABB/BCIRR/breqVMwp9SIlUA2u39mVCPUWBlZQHz8DiT591t5euPD2WiUR6rXfiAKhnBHvhXVkrs9AGWX2dFTLGX0AZfxCTiaTHYwChTjl1LL8HZ+YccvJa52nfCL+IHyT3Lb4kVi1pAqOBPqMjPfSYHBmZBQSI6Nm0TTDXicCFCsy9HWfiDqGDPTxIzEFqTqDMVF6BTIYHEXUKhDMrMGEKddstIr2qajQYzT6sIeIrENVCsVc1VuRQeiU0FAYU4gBEkhfY5CBT4TCDJABkZWoCx0xxGB26BSspqyiFSowwAKUSNvoWUQQA1p/NRTLC9R5El+jZ5BBR9Qzffr0VbTICrNiQSC9yskKrN9g+hkoVOljp2N5njrUBdExlhj07UI4qGVZ7ePpREw/KLJa5xxfqu9sBRjMjCXJQ5SvaI3ehg0mELlz94oVu3ei3IQJE2J3eu0rdt/AAvAZoEMwp2L7Iias0aOlAYO+hHmrV89De5KVqAndicEaUhlLremOCJuHDeZ0D+v+V4jBPFK5hjrfA+E3CAvr8RfCwvwGWJ6nLmgQYTF6Gr4cZACCELN6Z+Kbr1/eJO5cHaOBBAyNpkeYZg86kWbGgAAuUBXDw8OXh4fH6BlkoNGgY43mxumkbR6HySiIomBKcHi2JZ2+odHELIdSzR5YbevMmHBMRar2EEyMXgXxOcvD4Viza88mnuNYhmNpDMMwIr9pzy4NJMOXIwMGDHBfbaog3k+LQzNgHscNmTZkSNwut0mgaQH6OK0NtmDG8yb3rrghY8YMiZuD5jozbhoSQwpShaeNAaYt3obWYIt58TQkzKe3JYisKCoUNKegwUFI8J7257agSi8SIAtT6UqPRxjc+De2axocLzYbzObjSVtX8Dyj1TICv2Jr0nEzsHLMmPFxZvS75d2GMSDGl4bbxypyuXy8wXBLUMloe6JBvtJgGB8BjitdiUfmuO/dc885kuhaaRg/fiVUwUi00zKVcAuqoLEKRVGN5UCE4bhJRdPiFrPZJZcQESEPwOUybxFpWmU6bsCZxuiyXnKEfIQ8wjWTZxSs6WRExNwRfiCByn4IOSRPwr+kit/qikChkvjmNc/Qob2HznWd5G1WgXbc2TF36A9GkI0fqLrj4AWrjT/pmju0d++heShEhqy9EUt3CwKso9F75OHSHTuWLp3bW8LcpSj28IjXCCsoCLuv4GjWDBSm5sCBSG6/zMNJDldjh2fBggVbEwdicOXAz1sh5HHwrBbON3bTdpKoCc1kCrg00xMHzICzwanD0VrTkoESlpi06L/dZuMUMoXjSaaNKIgmQMgzFti48corj1aEk88KJwpjXDJWwhIjSysUVi0HJ4bn1ZWNG1EwT/ItTpnhhCVuO8sKCjDgjNuHSwAD9M8lsJzdvcQXKyO502ueaTQwaNDmza/dl50+g9EStsMMwMB52f168+bho4dDKFNzSkKBQX4mH37w6MT69etPHCaacBiHHj04PHnQoNGkrkDgjWb6NslMJrSRhjZPHhQYSp+WCiCoWHJu2LBhl2BIDSASGMoY9MvNdjFfKUA2RCRHpQbFfne7nrHDqA4dOozCG/Qie6mAQURG6P+VoPS4DED7wONAkT4ohUeeAtm6/QPZCqSlUqJF+U6dOnVDA23Q/ldRvsUfH/vyZuv0R7LlDaL+TOsamSdNmjTuBwEic43W1N/JkDfH1EmIqT78xznyZvjXh+9m6XNM/Ikc6Zulof6DdIUb1s1Y6n3m+/czvy+VsW7Dwik9/n8HzjZEy9x05tIAAAAASUVORK5CYII=" alt="QQ频道">
+    <img src="https://img.shields.io/badge/QQ-Bot-lightgrey?style=social&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMTIuODIgMTMwLjg5Ij48ZyBkYXRhLW5hbWU9IuWbvuWxgiAyIj48ZyBkYXRhLW5hbWU9IuWbvuWxgiAxIj48cGF0aCBkPSJNNTUuNjMgMTMwLjhjLTcgMC0xMy45LjA4LTIwLjg2IDAtMTkuMTUtLjI1LTMxLjcxLTExLjQtMzQuMjItMzAuMy00LjA3LTMwLjY2IDE0LjkzLTU5LjIgNDQuODMtNjYuNjQgMi0uNTEgNS4yMS0uMzEgNS4yMS0xLjYzIDAtMi4xMy4xNC0yLjEzLjE0LTUuNTcgMC0uODktMS4zLTEuNDYtMi4yMi0yLjMxLTYuNzMtNi4yMy03LjY3LTEzLjQxLTEtMjAuMTggNS40LTUuNTIgMTEuODctNS40IDE3LjgtLjU5IDYuNDkgNS4yNiA2LjMxIDEzLjA4LS44NiAyMS0uNjguNzQtMS43OCAxLjYtMS43OCAyLjY3djQuMjFjMCAxLjM1IDIuMiAxLjYyIDQuNzkgMi4zNSAzMS4wOSA4LjY1IDQ4LjE3IDM0LjEzIDQ1IDY2LjM3LTEuNzYgMTguMTUtMTQuNTYgMzAuMjMtMzIuNyAzMC42My04LjAyLjE5LTE2LjA3LS4wMS0yNC4xMy0uMDF6IiBmaWxsPSIjMDI5OWZlIi8+PHBhdGggZD0iTTMxLjQ2IDExOC4zOGMtMTAuNS0uNjktMTYuOC02Ljg2LTE4LjM4LTE3LjI3LTMtMTkuNDIgMi43OC0zNS44NiAxOC40Ni00Ny44MyAxNC4xNi0xMC44IDI5Ljg3LTEyIDQ1LjM4LTMuMTkgMTcuMjUgOS44NCAyNC41OSAyNS44MSAyNCA0NS4yOS0uNDkgMTUuOS04LjQyIDIzLjE0LTI0LjM4IDIzLjUtNi41OS4xNC0xMy4xOSAwLTE5Ljc5IDAiIGZpbGw9IiNmZWZlZmUiLz48cGF0aCBkPSJNNDYuMDUgNzkuNThjLjA5IDUgLjIzIDkuODItNyA5Ljc3LTcuODItLjA2LTYuMS01LjY5LTYuMjQtMTAuMTktLjE1LTQuODItLjczLTEwIDYuNzMtOS44NHM2LjM3IDUuNTUgNi41MSAxMC4yNnoiIGZpbGw9IiMxMDlmZmUiLz48cGF0aCBkPSJNODAuMjcgNzkuMjdjLS41MyAzLjkxIDEuNzUgOS42NC01Ljg4IDEwLTcuNDcuMzctNi44MS00LjgyLTYuNjEtOS41LjItNC4zMi0xLjgzLTEwIDUuNzgtMTAuNDJzNi41OSA0Ljg5IDYuNzEgOS45MnoiIGZpbGw9IiMwODljZmUiLz48L2c+PC9nPjwvc3ZnPg==" alt="QQ">
+  </a>
+  <a href="https://core.telegram.org/bots/api">
+    <img src="https://img.shields.io/badge/telegram-Bot-lightgrey?style=social&logo=telegram" alt="telegram">
+  </a>
+  <a href="https://open.feishu.cn/document/home/index">
+    <img src="https://img.shields.io/badge/%E9%A3%9E%E4%B9%A6-Bot-lightgrey?style=social&logo=data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48c3ZnIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDQ4IDQ4IiBmaWxsPSJub25lIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0xNyAyOUMyMSAyOSAyNSAyNi45MzM5IDI4IDIzLjQwNjVDMzYgMTQgNDEuNDI0MiAxNi44MTY2IDQ0IDE3Ljk5OThDMzguNSAyMC45OTk4IDQwLjUgMjkuNjIzMyAzMyAzNS45OTk4QzI4LjM4MiAzOS45MjU5IDIzLjQ5NDUgNDEuMDE0IDE5IDQxQzEyLjUyMzEgNDAuOTc5OSA2Ljg2MjI2IDM3Ljc2MzcgNCAzNS40MDYzVjE2Ljk5OTgiIHN0cm9rZT0iIzMzMyIgc3Ryb2tlLXdpZHRoPSI0IiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiLz48cGF0aCBkPSJNNS42NDgwOCAxNS44NjY5QzUuMDIyMzEgMTQuOTU2NyAzLjc3NzE1IDE0LjcyNjEgMi44NjY5NCAxNS4zNTE5QzEuOTU2NzMgMTUuOTc3NyAxLjcyNjE1IDE3LjIyMjggMi4zNTE5MiAxOC4xMzMxTDUuNjQ4MDggMTUuODY2OVpNMzYuMDAyMSAzNS43MzA5QzM2Ljk1OCAzNS4xNzc0IDM3LjI4NDMgMzMuOTUzOSAzNi43MzA5IDMyLjk5NzlDMzYuMTc3NCAzMi4wNDIgMzQuOTUzOSAzMS43MTU3IDMzLjk5NzkgMzIuMjY5MUwzNi4wMDIxIDM1LjczMDlaTTIuMzUxOTIgMTguMTMzMUM1LjI0MzUgMjIuMzM5IDEwLjc5OTIgMjguMTQ0IDE2Ljg4NjUgMzIuMjIzOUMxOS45MzQ1IDM0LjI2NjcgMjMuMjE3IDM1Ljk0NiAyNi40NDkgMzYuNzMyNEMyOS42OTQ2IDM3LjUyMiAzMy4wNDUxIDM3LjQ0MjggMzYuMDAyMSAzNS43MzA5TDMzLjk5NzkgMzIuMjY5MUMzMi4yMDQ5IDMzLjMwNzIgMjkuOTkyOSAzMy40NzggMjcuMzk0NyAzMi44NDU4QzI0Ljc4MyAzMi4yMTAzIDIxLjk0MDUgMzAuNzk1OCAxOS4xMTM1IDI4LjkwMTFDMTMuNDUwOCAyNS4xMDYgOC4yNTY1IDE5LjY2MSA1LjY0ODA4IDE1Ljg2NjlMMi4zNTE5MiAxOC4xMzMxWiIgZmlsbD0iIzMzMyIvPjxwYXRoIGQ9Ik0zMy41OTQ1IDE3QzMyLjgzOTggMTQuNzAyNyAzMC44NTQ5IDkuOTQwNTQgMjcuNTk0NSA3SDExLjU5NDVDMTUuMjE3MSAxMC42NzU3IDIzIDE2IDI3IDI0IiBzdHJva2U9IiMzMzMiIHN0cm9rZS13aWR0aD0iNCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIi8+PC9zdmc+" alt="feishu">
+  </a>
+  <a href="https://docs.github.com/en/developers/apps">
+    <img src="https://img.shields.io/badge/GitHub-Bot-181717?style=social&logo=github" alt="github"/>
+  </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">
-    <img src="https://img.shields.io/badge/qq%E7%BE%A4-768887710-orange?style=flat-square" alt="QQ Chat">
+    <img src="https://img.shields.io/badge/QQ%E7%BE%A4-768887710-orange?style=flat-square" alt="QQ Chat Group">
+  </a>
+  <a href="https://qun.qq.com/qqweb/qunpro/share?_wv=3&_wwv=128&appChannel=share&inviteCode=7b4a3&appChannel=share&businessType=9&from=246610&biz=ka">
+    <img src="https://img.shields.io/badge/QQ%E9%A2%91%E9%81%93-NoneBot-5492ff?style=flat-square" alt="QQ Channel">
   </a>
   <a href="https://t.me/botuniverse">
     <img src="https://img.shields.io/badge/telegram-botuniverse-blue?style=flat-square" alt="Telegram Channel">
@@ -57,16 +85,18 @@ _✨ 跨平台 Python 异步机器人框架 ✨_
 </p>
 
 <p align="center">
-  <a href="https://v2.nonebot.dev/">文档</a>
+  <a href="https://nonebot.dev/">文档</a>
   ·
-  <a href="https://v2.nonebot.dev/guide/installation.html">安装</a>
-  ·
-  <a href="https://v2.nonebot.dev/guide/getting-started.html">开始使用</a>
+  <a href="https://nonebot.dev/docs/quick-start">快速上手</a>
   ·
   <a href="#插件">文档打不开？</a>
 </p>
 
-<!-- TODO: asciinema for install -->
+<p align="center">
+  <a href="https://asciinema.org/a/569440">
+    <img src="https://nonebot.dev/img/setup.svg" alt="setup" >
+  </a>
+</p>
 
 ## 简介
 
@@ -76,23 +106,52 @@ NoneBot2 是一个现代、跨平台、可扩展的 Python 聊天机器人框架
 
 - 异步优先：基于 Python 的异步特性，即使是~~非常~~大量的消息，也能吞吐自如
 - 易于开发：配合 NB-CLI 脚手架，代码编写上手简单，没有过多的冗余代码，可以让开发者专注于业务逻辑
-- 生而可靠：100% 类型注解覆盖，配合编辑器的类型推导功能，能将绝大多数的 Bug 杜绝在编辑器中 ([编辑器支持](https://v2.nonebot.dev/docs/start/editor-support))
+- 生而可靠：100% 类型注解覆盖，配合编辑器的类型推导功能，能将绝大多数的 Bug 杜绝在编辑器中 ([编辑器支持](https://nonebot.dev/docs/editor-support))
 - 社区丰富：社区用户众多，直接和间接用户超过十万人，每天都有大量的活跃用户 ([社区资源](#社区资源))
 - 海纳百川：一个框架，支持多个聊天软件平台，可自定义通信协议
-  - [OneBot 协议](https://onebot.dev/) (QQ 等)
-  - [Mirai-API-HTTP 协议](https://github.com/project-mirai/mirai-api-http)
-  - [钉钉](https://ding-doc.dingtalk.com/document#/org-dev-guide/elzz1p)
-  - [Telegram](https://core.telegram.org/bots/api)
-  - [飞书](https://open.feishu.cn/document/home/index)
-  - [QQ 频道](https://bot.q.qq.com/wiki/)
-- 坚实后盾：支持多种 web 框架，可自定义替换
-  - [FastAPI](https://fastapi.tiangolo.com/)
-  - [Quart](https://pgjones.gitlab.io/quart/) (异步 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/)
+  |                                                       协议名称                                                        | 状态 |                                   注释                                    |
+  | :-------------------------------------------------------------------------------------------------------------------: | :--: | :-----------------------------------------------------------------------: |
+  |               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-qq)，[协议](https://bot.q.qq.com/wiki/)）                |  ✅  |                            QQ 官方接口调整较多                            |
+  |                             Console（[仓库](https://github.com/nonebot/adapter-console)）                             |  ✅  |                                控制台交互                                 |
+  |     Red（[仓库](https://github.com/nonebot/adapter-red)，[协议](https://chrononeko.github.io/QQNTRedProtocol/)）      |  ✅  |                                 QQNT 协议                                  |
+  |           Satori（[仓库](https://github.com/nonebot/adapter-satori)，[协议](https://satori.js.org/zh-CN)）            |  ✅  |               支持 Onebot、TG、飞书、微信公众号、Koishi 等                |
+  |   Discord（[仓库](https://github.com/nonebot/adapter-discord)，[协议](https://discord.com/developers/docs/intro)）    |  ✅  |                             Discord Bot 协议                              |
+  |               DoDo（[仓库](https://github.com/nonebot/adapter-dodo)，[协议](https://open.imdodo.com/)）               |  ✅  |                               DoDo Bot 协议                               |
+  |        Kritor（[仓库](https://github.com/nonebot/adapter-kritor)，[协议](https://github.com/KarinJS/kritor)）         |  ✅  |                Kritor (OnebotX) 协议，QQNT 机器人接口标准                  |
+  |    Mirai（[仓库](https://github.com/nonebot/adapter-mirai)，[协议](https://docs.mirai.mamoe.net/mirai-api-http/)）    |  ✅  |                                  QQ 协议                                  |
+  |    Milky（[仓库](https://github.com/nonebot/adapter-milky)，[协议](https://milky.ntqqrev.org/)）                      |  ✅  |                           QQNT 机器人应用接口标准                          |
+  |         钉钉（[仓库](https://github.com/nonebot/adapter-ding)，[协议](https://open.dingtalk.com/document/)）          |  🤗  |                        寻找 Maintainer（暂不可用）                        |
+  |     开黑啦（[仓库](https://github.com/Tian-que/nonebot-adapter-kaiheila)，[协议](https://developer.kookapp.cn/)）     |  ↗️  |                                由社区贡献                                 |
+  |                          Ntchat（[仓库](https://github.com/JustUndertaker/adapter-ntchat)）                           |  ↗️  |                           微信协议，由社区贡献                            |
+  |                      MineCraft（[仓库](https://github.com/17TheWord/nonebot-adapter-minecraft)）                      |  ↗️  |                                由社区贡献                                 |
+  |                       Walle-Q（[仓库](https://github.com/onebot-walle/nonebot_adapter_walleq)）                       |  ↗️  |                            QQ 协议，由社区贡献                            |
+  |                       Villa（[仓库](https://github.com/CMHopeSunshine/nonebot-adapter-villa)）                        |  ❌  |                     米游社大别野 Bot 协议，官方已下线                     |
+  | Rocket.Chat（[仓库](https://github.com/IUnlimit/nonebot-adapter-rocketchat)，[协议](https://developer.rocket.chat/)） |  ↗️  |                     Rocket.Chat Bot 协议，由社区贡献                      |
+  |     Tailchat（[仓库](https://github.com/eya46/nonebot-adapter-tailchat)，[协议](https://tailchat.msgbyte.com/)）      |  ↗️  |                  Tailchat 开放平台 Bot 协议，由社区贡献                   |
+  |                             Mail（[仓库](https://github.com/mobyw/nonebot-adapter-mail)）                             |  ↗️  |                         邮件收发协议，由社区贡献                          |
+  |     黑盒语音（[仓库](https://github.com/lclbm/adapter-heybox)，[协议](https://github.com/QingFengOpen/HeychatDoc)）     |  ↗️  |                       黑盒语音机器人协议，由社区贡献                             |
+  | 微信公众平台（[仓库](https://github.com/YangRucheng/nonebot-adapter-wxmp)，[协议](https://developers.weixin.qq.com/doc/)）|  ↗️  |                       微信公众平台协议，由社区贡献                             |
+  | Gewechat（[仓库](https://github.com/Shine-Light/nonebot-adapter-gewechat)，[协议](https://github.com/Devo919/Gewechat)）|  ❌  |                      Gewechat 微信协议，Gewechat不再维护及可用                            |
+  |  EFChat（[仓库](https://github.com/molanp/nonebot_adapter_efchat)，[协议](https://irinu-live.melon.fish/efc-help/)）   |  ↗️  |                            恒五聊平台协议，由社区贡献                          |
+  |  VoceChat （[仓库](https://github.com/5656565566/nonebot-adapter-vocechat)，[协议](https://doc.voce.chat/zh-cn/bot/bot-and-webhook)）   |  ↗️  |                            VoceChat 平台协议，由社区贡献                          |
+  |  B站直播间（[仓库](https://github.com/MingxuanGame/nonebot-adapter-bilibili-live)，[Web API 协议](https://github.com/SocialSisterYi/bilibili-API-collect/blob/master/docs/live)，[开放平台协议](https://open-live.bilibili.com/document)）   |  ↗️  |                            B站直播间（Web API/开放平台）协议，由社区贡献                          |
+
+- 坚实后盾：支持多种 web 框架，可自定义替换、组合
+
+  |                              驱动框架                               |  类型  |
+  | :-----------------------------------------------------------------: | :----: |
+  |              [FastAPI](https://fastapi.tiangolo.com/)               | 服务端 |
+  | [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://nonebot.dev/docs/)
 
 ## 什么不是 NoneBot2
 
@@ -104,16 +163,21 @@ NoneBot2 不是 NoneBot1 的替代品。事实上，它们都在被积极的维
 
 ## 即刻开始
 
-~~完整~~文档可以在 [这里](https://v2.nonebot.dev/) 查看。
+~~完整~~文档可以在 [这里](https://nonebot.dev/) 查看。
 
 懒得看文档？下面是快速安装指南：
 
-1. (**强烈建议**)使用你喜欢的 Python 环境管理工具创建新的虚拟环境。
-
-2. 使用 `pip` (或其他) 安装 NoneBot 脚手架。
+1. 安装 [pipx](https://pypa.github.io/pipx/)
 
    ```bash
-   pip install nb-cli
+   python -m pip install --user pipx
+   python -m pipx ensurepath
+   ```
+
+2. 安装脚手架
+
+   ```bash
+   pipx install nb-cli
    ```
 
 3. 使用脚手架创建项目
@@ -122,6 +186,12 @@ NoneBot2 不是 NoneBot1 的替代品。事实上，它们都在被积极的维
    nb create
    ```
 
+4. 运行项目
+
+   ```bash
+   nb run
+   ```
+
 ## 社区资源
 
 ### 常见问题
@@ -148,33 +218,82 @@ NoneBot2 不是 NoneBot1 的替代品。事实上，它们都在被积极的维
   或者尝试以下镜像：
 
   - [文档镜像(中国境内)](https://nb2.baka.icu)
-  - [文档镜像(Vercel)](https://nonebot2-vercel-mirror.vercel.app)
 
-- 其他插件请查看 [商店](https://v2.nonebot.dev/store.html)
+- 其他插件请查看 [商店](https://nonebot.dev/store/plugins)
 
 ## 许可证
 
 `NoneBot` 采用 `MIT` 许可证进行开源
 
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-    FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-    COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-    IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-    CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```text
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
 
 ## 贡献
 
-如果你在使用过程中发现任何问题，可以 [提交 Issue](https://github.com/nonebot/nonebot2/issues/new) 或自行 Fork 修改后提交 Pull Request。
+请参考 [贡献指南](./CONTRIBUTING.md)
 
-如果你要提交 Pull Request，请确保你的代码风格和项目已有的代码保持一致，遵循 [PEP 8](https://www.python.org/dev/peps/pep-0008/) 与 [PEP 484](https://www.python.org/dev/peps/pep-0484/)，变量命名清晰，有适当的注释与测试代码，**并且请以 `dev` 分支作为 Pull Request 目标分支**。
+## 鸣谢
 
-<!--TODO: Add a CONTRIBUTING.md-->
+### 赞助者
 
-### 鸣谢
+感谢以下产品对 NoneBot 项目提供的赞助：
+
+<p align="center">
+  <a href="https://github.com/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://assets.nonebot.dev/github-dark.png">
+      <img src="https://assets.nonebot.dev/github-light.png" height="50" alt="GitHub">
+    </picture>
+  </a>&nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://www.netlify.com/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://assets.nonebot.dev/netlify-dark.svg">
+      <img src="https://assets.nonebot.dev/netlify-light.svg" height="50" alt="netlify">
+    </picture>
+  </a>&nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://sentry.io/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://assets.nonebot.dev/sentry-dark.svg">
+      <img src="https://assets.nonebot.dev/sentry-light.svg" height="50" alt="sentry">
+    </picture>
+  </a>
+</p>
+<p align="center">
+  <a href="https://www.docker.com/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://assets.nonebot.dev/docker-dark.svg">
+      <img src="https://assets.nonebot.dev/docker-light.svg" height="50" alt="docker">
+    </picture>
+  </a>&nbsp;&nbsp;&nbsp;&nbsp;
+  <a href="https://www.algolia.com/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://assets.nonebot.dev/algolia-dark.svg">
+      <img src="https://assets.nonebot.dev/algolia-light.svg" height="50" alt="algolia">
+    </picture>
+  </a>
+</p>
+<p align="center">
+  <a href="https://www.jetbrains.com/">
+    <img src="https://resources.jetbrains.com/storage/products/company/brand/logos/jb_beam.svg" height="80" alt="JetBrains" >
+  </a>
+</p>
+
+感谢以下赞助者对 NoneBot 项目提供的资金支持：
+
+<a href="https://assets.nonebot.dev/sponsors.svg">
+  <img src="https://assets.nonebot.dev/sponsors.svg" alt="sponsors" />
+</a>
+
+### 开发者
 
 感谢以下开发者对 NoneBot2 作出的贡献：
 
 <a href="https://github.com/nonebot/nonebot2/graphs/contributors">
-  <img src="https://contrib.rocks/image?repo=nonebot/nonebot2" />
+  <img src="https://contrib.rocks/image?repo=nonebot/nonebot2&max=1000" alt="contributors" />
 </a>

assets/adapters.json5

@@ -0,0 +1,341 @@
+[
+  {
+    "module_name": "nonebot.adapters.onebot.v11",
+    "project_link": "nonebot-adapter-onebot",
+    "name": "OneBot V11",
+    "desc": "OneBot V11 协议",
+    "author_id": 42488585,
+    "homepage": "https://onebot.adapters.nonebot.dev/",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot.adapters.ding",
+    "project_link": "nonebot-adapter-ding",
+    "name": "钉钉",
+    "desc": "钉钉协议",
+    "author_id": 1184028,
+    "homepage": "https://github.com/nonebot/adapter-ding",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot.adapters.feishu",
+    "project_link": "nonebot-adapter-feishu",
+    "name": "飞书",
+    "desc": "飞书协议",
+    "author_id": 14922941,
+    "homepage": "https://github.com/nonebot/adapter-feishu",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot.adapters.telegram",
+    "project_link": "nonebot-adapter-telegram",
+    "name": "Telegram",
+    "desc": "Telegram 协议",
+    "author_id": 50312681,
+    "homepage": "https://github.com/nonebot/adapter-telegram",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot.adapters.qq",
+    "project_link": "nonebot-adapter-qq",
+    "name": "QQ",
+    "desc": "QQ 官方机器人",
+    "author_id": 42488585,
+    "homepage": "https://github.com/nonebot/adapter-qq",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot.adapters.kaiheila",
+    "project_link": "nonebot-adapter-kaiheila",
+    "name": "开黑啦",
+    "desc": "开黑啦协议适配",
+    "author_id": 37477320,
+    "homepage": "https://github.com/Tian-que/nonebot-adapter-kaiheila",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "module_name": "nonebot.adapters.mirai",
+    "project_link": "nonebot-adapter-mirai",
+    "name": "Mirai",
+    "desc": "mirai-api-http v2 协议适配",
+    "author_id": 42648639,
+    "homepage": "https://github.com/nonebot/adapter-mirai",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot.adapters.onebot.v12",
+    "project_link": "nonebot-adapter-onebot",
+    "name": "OneBot V12",
+    "desc": "OneBot V12 协议",
+    "author_id": 42488585,
+    "homepage": "https://onebot.adapters.nonebot.dev/",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot.adapters.console",
+    "project_link": "nonebot-adapter-console",
+    "name": "Console",
+    "desc": "基于终端的交互式适配器",
+    "author_id": 50488999,
+    "homepage": "https://github.com/nonebot/adapter-console",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot.adapters.github",
+    "project_link": "nonebot-adapter-github",
+    "name": "GitHub",
+    "desc": "GitHub APP & OAuth APP integration",
+    "author_id": 42488585,
+    "homepage": "https://github.com/nonebot/adapter-github",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot.adapters.ntchat",
+    "project_link": "nonebot-adapter-ntchat",
+    "name": "Ntchat",
+    "desc": "pc hook的微信客户端适配",
+    "author_id": 37363867,
+    "homepage": "https://github.com/JustUndertaker/adapter-ntchat",
+    "tags": [
+      {
+        "label": "微信",
+        "color": "#ea5252"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "module_name": "nonebot.adapters.minecraft",
+    "project_link": "nonebot-adapter-minecraft",
+    "name": "Minecraft",
+    "desc": "MineCraft通信适配，支持Rcon",
+    "author_id": 54731914,
+    "homepage": "https://github.com/17TheWord/nonebot-adapter-minecraft",
+    "tags": [
+      {
+        "label": "Minecraft",
+        "color": "#4ef0ea"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "module_name": "nonebot.adapters.bilibili",
+    "project_link": "nonebot-adapter-bilibili",
+    "name": "BilibiliLive",
+    "desc": "b站直播间ws协议",
+    "author_id": 39620657,
+    "homepage": "https://github.com/wwweww/adapter-bilibili",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "module_name": "nonebot_adapter_walleq",
+    "project_link": "nonebot-adapter-walleq",
+    "name": "Walle-Q",
+    "desc": "内置 QQ 协议实现",
+    "author_id": 18395948,
+    "homepage": "https://github.com/onebot-walle/nonebot_adapter_walleq",
+    "tags": [
+      {
+        "label": "QQ",
+        "color": "#34a9cc"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "module_name": "nonebot.adapters.villa",
+    "project_link": "nonebot-adapter-villa",
+    "name": "大别野",
+    "desc": "米游社大别野官方Bot适配",
+    "author_id": 63870437,
+    "homepage": "https://github.com/CMHopeSunshine/nonebot-adapter-villa",
+    "tags": [
+      {
+        "label": "米哈游",
+        "color": "#e10909"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "module_name": "nonebot.adapters.red",
+    "project_link": "nonebot-adapter-red",
+    "name": "RedProtocol",
+    "desc": "QQNT RedProtocol 适配",
+    "author_id": 55650833,
+    "homepage": "https://github.com/nonebot/adapter-red",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot.adapters.discord",
+    "project_link": "nonebot-adapter-discord",
+    "name": "Discord",
+    "desc": "Discord 官方 Bot 协议适配",
+    "author_id": 63870437,
+    "homepage": "https://github.com/nonebot/adapter-discord",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot.adapters.satori",
+    "project_link": "nonebot-adapter-satori",
+    "name": "Satori",
+    "desc": "Satori 协议适配器",
+    "author_id": 42648639,
+    "homepage": "https://github.com/nonebot/adapter-satori",
+    "tags": [
+      {
+        "label": "跨平台",
+        "color": "#bf40bf"
+      }
+    ],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot.adapters.dodo",
+    "project_link": "nonebot-adapter-dodo",
+    "name": "DoDo",
+    "desc": "DoDo Bot 协议适配器",
+    "author_id": 63870437,
+    "homepage": "https://github.com/nonebot/adapter-dodo",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot.adapters.rocketchat",
+    "project_link": "nonebot-adapter-rocketchat",
+    "name": "RocketChat",
+    "desc": "RocketChat adapter for nonebot2",
+    "author_id": 78360471,
+    "homepage": "https://github.com/IUnlimit/nonebot-adapter-rocketchat",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "module_name": "nonebot.adapters.kritor",
+    "project_link": "nonebot-adapter-kritor",
+    "name": "Kritor",
+    "desc": "Kritor 协议适配",
+    "author_id": 42648639,
+    "homepage": "https://github.com/nonebot/adapter-kritor",
+    "tags": [
+      {
+        "label": "QQNT",
+        "color": "#35a7c9"
+      }
+    ],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot_adapter_tailchat",
+    "project_link": "nonebot-adapter-tailchat",
+    "name": "Tailchat",
+    "desc": "Tailchat 适配器",
+    "author_id": 61458340,
+    "homepage": "https://github.com/eya46/nonebot-adapter-tailchat",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "module_name": "nonebot.adapters.mail",
+    "project_link": "nonebot-adapter-mail",
+    "name": "Mail",
+    "desc": "邮件收发协议",
+    "author_id": 44370805,
+    "homepage": "https://github.com/mobyw/nonebot-adapter-mail",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "module_name": "nonebot.adapters.heybox",
+    "project_link": "nonebot-adapter-heybox",
+    "name": "黑盒语音",
+    "desc": "黑盒语音机器人适配",
+    "author_id": 54730982,
+    "homepage": "https://github.com/lclbm/adapter-heybox",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "module_name": "nonebot.adapters.wxmp",
+    "project_link": "nonebot-adapter-wxmp",
+    "name": "WXMP",
+    "desc": "微信公众平台 客服适配器",
+    "author_id": 60175467,
+    "homepage": "https://github.com/YangRucheng/nonebot-adapter-wxmp",
+    "tags": [
+      {
+        "label": "微信公众平台",
+        "color": "#843dbc"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "module_name": "nonebot.adapters.milky",
+    "project_link": "nonebot-adapter-milky",
+    "name": "nonebot-adapter-milky",
+    "desc": "Milky 协议适配器",
+    "author_id": 42648639,
+    "homepage": "https://github.com/nonebot/adapter-milky",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "nonebot.adapters.efchat",
+    "project_link": "nonebot-adapter-efchat",
+    "name": "nonebot-adapter-efchat",
+    "desc": "适用于EFChat(恒五聊)聊天室的nonebot适配器",
+    "author_id": 104612722,
+    "homepage": "https://github.com/molanp/nonebot_adapter_efchat",
+    "tags": [
+      {
+        "label": "EFChat",
+        "color": "#ac6161"
+      },
+      {
+        "label": "恒五聊",
+        "color": "#cc99ff"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "module_name": "nonebot.adapters.vocechat",
+    "project_link": "nonebot-adapter-vocechat",
+    "name": "nonebot-adapter-vocechat",
+    "desc": "Vocechat 协议适配器",
+    "author_id": 56059687,
+    "homepage": "https://github.com/5656565566/nonebot-adapter-vocechat",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "module_name": "nonebot.adapters.bilibili_live",
+    "project_link": "nonebot-adapter-bilibili-live",
+    "name": "B站直播间",
+    "desc": "B 站直播间协议（Web API/开放平台）支持",
+    "author_id": 68982190,
+    "homepage": "https://github.com/MingxuanGame/nonebot-adapter-bilibili-live",
+    "tags": [
+      {
+        "label": "bilibili",
+        "color": "#ff6699"
+      }
+    ],
+    "is_official": false
+  },
+]

assets/bots.json5

@@ -0,0 +1,767 @@
+[
+  {
+    "name": "HarukaBot",
+    "desc": "将B站UP主的动态和直播信息推送至QQ",
+    "author_id": 36433929,
+    "homepage": "https://github.com/SK-415/HarukaBot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "Omega Miya",
+    "desc": "B站推送Pixiv搜图识番求签抽卡表情包还有其他杂七杂八的功能",
+    "author_id": 41713304,
+    "homepage": "https://github.com/Ailitonia/omega-miya",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "Github Bot",
+    "desc": "在QQ获取/处理Github repo/pr/issue",
+    "author_id": 42488585,
+    "homepage": "https://github.com/cscs181/QQ-GitHub-Bot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "YanXiBot",
+    "desc": "动漫资源查找与娱乐机器人",
+    "author_id": 50488999,
+    "homepage": "https://github.com/Melodyknit/YanXiBot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "绪山真寻bot",
+    "desc": "含有不少的娱乐功能同时稍稍有一些实用的功能 :P",
+    "author_id": 45528451,
+    "homepage": "https://github.com/HibiKier/zhenxun_bot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "ATRI",
+    "desc": "高性能文爱萝卜子，糅杂了各类有趣小功能",
+    "author_id": 37587870,
+    "homepage": "https://github.com/Kyomotoi/ATRI",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "dumbot傻瓜机器人",
+    "desc": "猜一猜游戏、新闻一览、英文每日一词一短语等等，含一键启动及docker容器部署就绪",
+    "author_id": 52522252,
+    "homepage": "https://github.com/ffreemt/koyeb-nb2",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "DicePP",
+    "desc": "TRPG骰娘, 带先攻, 查询等功能, 主要面向DND5E. 面对骰主推出的船新版本, 内置Windows/Linux详细部署指南以及方便的自定义骰娘方法, 从回复文本到查询资料库都可轻松配置~",
+    "author_id": 88259371,
+    "homepage": "https://github.com/pear-studio/nonebot-dicepp",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "SetuBot",
+    "desc": "每个群配置文件独立,可以控制频率,socks http代理,R18开关,支持多tag,自建API lolicon Pixiv热度榜",
+    "author_id": 39484884,
+    "homepage": "https://github.com/yuban10703/setu-nonebot2",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "剑网三bot",
+    "desc": "网络游戏《剑侠情缘三》的群聊机器人，数据使用：www.jx3api.com",
+    "author_id": 37363867,
+    "homepage": "https://github.com/JustUndertaker/mini_jx3_bot",
+    "tags": [
+      {
+        "label": "剑网三",
+        "color": "#5393ec"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "PixivBot",
+    "desc": "顾名思义是Pixiv的bot（随机推荐插画、随机指定关键词插画、随机书签、查看排行榜、查看指定id插画）",
+    "author_id": 17331698,
+    "homepage": "https://github.com/ssttkkl/PixivBot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "SeaBot_QQ",
+    "desc": "一个能够获取新闻资讯并推送至QQ的群聊机器人。",
+    "author_id": 31682561,
+    "homepage": "https://github.com/B1ue1nWh1te/SeaBot_QQ",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "琪露诺Bot",
+    "desc": "用QQ机器人控制Minecraft服务器！服务器状态查询/服务器白名单/插件列表/玩家查询/转发服务器消息/执行指令...   其他实用娱乐功能，三步即可成功部署的QQ bot",
+    "author_id": 56951617,
+    "homepage": "https://github.com/summerkirakira/CirnoBot",
+    "tags": [
+      {
+        "label": "Minecraft",
+        "color": "#5393ec"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "Inkar Suki",
+    "desc": "一个十分方便的Bot，支持包括Webhook、群管、剑网3等一系列功能，持续更新中……",
+    "author_id": 68726147,
+    "homepage": "https://github.com/HornCopper/Inkar-Suki",
+    "tags": [
+      {
+        "label": "Minecraft",
+        "color": "#d03790"
+      },
+      {
+        "label": "GitHub",
+        "color": "#374fd0"
+      },
+      {
+        "label": "剑网3",
+        "color": "#ff0033"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "屑岛风Bot",
+    "desc": "自家用屑Bot",
+    "author_id": 71873002,
+    "homepage": "https://github.com/kexue-z/Dao-bot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "LiteyukiBot-轻雪机器人",
+    "desc": "一个有各种琐事功能的bot，有AI接口，能陪聊",
+    "author_id": 79104275,
+    "homepage": "https://github.com/snowyfirefly/Liteyuki",
+    "tags": [
+      {
+        "label": "可爱",
+        "color": "#ffc0cb"
+      },
+      {
+        "label": "AI",
+        "color": "#ea5252"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "nya_bot",
+    "desc": "喵服——战魂铭人联机服务器兼机器人",
+    "author_id": 31379266,
+    "homepage": "https://github.com/nikissXI/nya_bot",
+    "tags": [
+      {
+        "label": "战魂铭人",
+        "color": "#25aaf4"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "真宵Bot",
+    "desc": "专注群聊的QQ机器人",
+    "author_id": 71173418,
+    "homepage": "https://github.com/Shine-Light/Nonebot_Bot_MayaFey",
+    "tags": [
+      {
+        "label": "QQ",
+        "color": "#ea5252"
+      },
+      {
+        "label": "娱乐",
+        "color": "#a46e49"
+      },
+      {
+        "label": "群管",
+        "color": "#41aecb"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "SkadiBot",
+    "desc": "明日方舟主题机器人—斯卡蒂",
+    "author_id": 101615359,
+    "homepage": "https://github.com/yuyuziYYZ/skadi_bot",
+    "tags": [
+      {
+        "label": "明日方舟",
+        "color": "#a48888"
+      },
+      {
+        "label": "斯卡蒂",
+        "color": "#a48888"
+      },
+      {
+        "label": "arknights",
+        "color": "#a48888"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "小白机器人",
+    "desc": "一个高度依赖数据库的群管理机器人",
+    "author_id": 69745333,
+    "homepage": "https://github.com/SDIJF1521/qqai",
+    "tags": [
+      {
+        "label": "群管理",
+        "color": "#ea5252"
+      },
+      {
+        "label": "新人作品",
+        "color": "#ea5252"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "LittlePaimon",
+    "desc": "小派蒙，多功能原神机器人。",
+    "author_id": 63870437,
+    "homepage": "https://github.com/CMHopeSunshine/LittlePaimon",
+    "tags": [
+      {
+        "label": "原神",
+        "color": "#7a52ea"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "IdhagnBot",
+    "desc": "🐱🤖 一个以娱乐功能为主的缝合怪（划掉）QQ机器人，包含一定Furry要素但是不会卖萌（就是逊啦！）",
+    "author_id": 17371317,
+    "homepage": "https://github.com/su226/IdhagnBot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "hsbot",
+    "desc": "服务于《炉石传说》玩家的机器人，上线至今已有加入十余个个炉石相关群聊，上千名用户使用，响应请求数万次。 数据使用：HSreplay, Fbigame, Hearthstone API",
+    "author_id": 67055520,
+    "homepage": "https://github.com/gzy02/hsbot",
+    "tags": [
+      {
+        "label": "炉石传说",
+        "color": "#526fea"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "Bread Dog Bot",
+    "desc": "Terraria TShock QQ 机器人",
+    "author_id": 160252668,
+    "homepage": "https://github.com/Qianyiovo/bread_dog_bot",
+    "tags": [
+      {
+        "label": "TShock",
+        "color": "#ea5252"
+      },
+      {
+        "label": "泰拉瑞亚",
+        "color": "#5dea52"
+      },
+      {
+        "label": "Terraria",
+        "color": "#5dea52"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "RanBot",
+    "desc": "不@会很安静的Bot",
+    "author_id": 88923783,
+    "homepage": "https://github.com/Hecatia-Hell-Workshop/RanBot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "辞辞(cici)Bot",
+    "desc": "一个集成娱乐和群管为一体的机器人",
+    "author_id": 90902259,
+    "homepage": "https://github.com/mengxinyuan638/cici-bot",
+    "tags": [
+      {
+        "label": "辞辞Bot",
+        "color": "#04de4d"
+      },
+      {
+        "label": "萌新源",
+        "color": "#fd1c06"
+      },
+      {
+        "label": "群管",
+        "color": "#06b8fd"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "SuzunoBot",
+    "desc": "多功能音游bot，主要服务maimaiDX、Arcaea",
+    "author_id": 29980586,
+    "homepage": "https://github.com/Rinfair-CSP-A016/SuzunoBot-AGLAS",
+    "tags": [
+      {
+        "label": "maimaiDX",
+        "color": "#189ede"
+      },
+      {
+        "label": "Arcaea",
+        "color": "#d551ef"
+      },
+      {
+        "label": "coc",
+        "color": "#7fe4d0"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "青岚",
+    "desc": "基于NoneBot的与Minecraft Server互通消息的机器人",
+    "author_id": 54731914,
+    "homepage": "https://github.com/17TheWord/qinglan_bot",
+    "tags": [
+      {
+        "label": "MineCraft",
+        "color": "#4ef0ea"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "ChensQBOTv2",
+    "desc": "多功能QQ群机器人，权限管理/联ban/社工等等等等，以及拥有一个强大的开发者",
+    "author_id": 116929900,
+    "homepage": "https://github.com/cnchens/ChensQBOTv2",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "koishi",
+    "desc": "支持爬取 codeforces, atcoder, 牛客上程序设计赛事的 bot。",
+    "author_id": 71639222,
+    "homepage": "https://github.com/CupidsBow/koishi",
+    "tags": [
+      {
+        "label": "acm",
+        "color": "#f71d1d"
+      },
+      {
+        "label": "codeforces",
+        "color": "#1df721"
+      },
+      {
+        "label": "atcoder",
+        "color": "#aa1df7"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "脑积水",
+    "desc": "一个超级缝合怪...",
+    "author_id": 66541860,
+    "homepage": "https://github.com/zhulinyv/NJS",
+    "tags": [
+      {
+        "label": "脑积水",
+        "color": "#ff00ac"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "LOVE酱",
+    "desc": "为铁锈战争游戏群服务的虚拟少女,内置了爬取铁锈房间列表功能,以及游戏内单位查询功能,并制作了教学系统以及铁锈相关游戏群的收集功能。",
+    "author_id": 106828088,
+    "homepage": "https://github.com/allureluoli/LOVE-",
+    "tags": [
+      {
+        "label": "铁锈战争",
+        "color": "#19e229"
+      },
+      {
+        "label": "RW",
+        "color": "#19e229"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "fubot",
+    "desc": "基于nonebot与go-cqhttp的QQ娱乐bot，提供群日常娱乐功能与舞萌DX游戏相关的信息查询功能。",
+    "author_id": 54059896,
+    "homepage": "https://github.com/HCskia/fu-Bot",
+    "tags": [
+      {
+        "label": "maimai",
+        "color": "#52eaa5"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "桃桃酱",
+    "desc": "一个会拆家的高性能缝合萝卜子",
+    "author_id": 107618388,
+    "homepage": "https://github.com/tkgs0/Momoko",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "CoolQBot",
+    "desc": "基于 NoneBot2 的聊天机器人",
+    "author_id": 5219550,
+    "homepage": "https://github.com/he0119/CoolQBot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "XDbot2",
+    "desc": "简单的QQ功能型机器人",
+    "author_id": 104149371,
+    "homepage": "https://github.com/ITCraftDevelopmentTeam/XDbot2",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "March7th",
+    "desc": "三月七 - 崩坏：星穹铁道机器人",
+    "author_id": 44370805,
+    "homepage": "https://github.com/Mar-7th/March7th",
+    "tags": [
+      {
+        "label": "StarRail",
+        "color": "#5a8ccc"
+      },
+      {
+        "label": "星穹铁道",
+        "color": "#6faec6"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "ay机器人",
+    "desc": "codeforces和洛谷卷王监视、股票监控、ai聊天",
+    "author_id": 77315378,
+    "homepage": "https://github.com/863109569/qqbot",
+    "tags": [
+      {
+        "label": "acm",
+        "color": "#ea5252"
+      },
+      {
+        "label": "洛谷",
+        "color": "#81ea52"
+      },
+      {
+        "label": "codeforces",
+        "color": "#5261ea"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "狐尾",
+    "desc": "一个整合了兽云祭api的机器人，支持账号令牌操作，以及上传兽图",
+    "author_id": 99388013,
+    "homepage": "https://github.com/bingqiu456/shouyun",
+    "tags": [
+      {
+        "label": "shouyun",
+        "color": "#52ea7a"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "ReimeiBot-黎明机器人",
+    "desc": "流星飞逝，黎明终将到来。",
+    "author_id": 65395090,
+    "homepage": "https://github.com/3rdBit/ReimeiBot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "web_bot",
+    "desc": "把机器人搬到网络上",
+    "author_id": 63489103,
+    "homepage": "https://github.com/wsdtl/web_bot",
+    "tags": [
+      {
+        "label": "xiaonan",
+        "color": "#775151"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "林汐",
+    "desc": "多平台功能型Bot",
+    "author_id": 110453675,
+    "homepage": "https://github.com/netsora/SoraBot",
+    "tags": [
+      {
+        "label": "QQ频道",
+        "color": "#f47070"
+      },
+      {
+        "label": "OneBot v11",
+        "color": "#212121"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "米缸",
+    "desc": "基于nonebot2的米缸Bot",
+    "author_id": 13503375,
+    "homepage": "https://github.com/LambdaYH/MigangBot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "不正经的妹妹",
+    "desc": "一款功能丰富、简单易用、自定义性强、扩展性强的可爱的QQ娱乐机器人",
+    "author_id": 104713034,
+    "homepage": "https://github.com/itsevin/sister_bot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "星见Kirami",
+    "desc": "🌟 读作 Kirami，写作星见，简明轻快的聊天机器人应用。",
+    "author_id": 66513481,
+    "homepage": "https://kiramibot.dev/",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "OCNbot",
+    "desc": "OI Contest Notifier bot，一个可以推送洛谷、cf、atcoder、牛客比赛通知的bot",
+    "author_id": 91535478,
+    "homepage": "https://github.com/ACnoway/OCNbot",
+    "tags": [
+      {
+        "label": "OI",
+        "color": "#2fccff"
+      },
+      {
+        "label": "ACM",
+        "color": "#ff0004"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "妃爱",
+    "desc": "超可爱的妃爱QQ群聊机器人",
+    "author_id": 52267304,
+    "homepage": "https://github.com/jiangyuxiaoxiao/Hiyori",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "芙芙",
+    "desc": "供 Mooncell Wiki 协作使用的跨平台机器人",
+    "author_id": 14922941,
+    "homepage": "https://github.com/MooncellWiki/BotFooChan",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "Sakiko",
+    "desc": "基于 LiteLoaderBDS 的 Minecraft 基岩版 Bot",
+    "author_id": 55650833,
+    "homepage": "https://github.com/zhaomaoniu/Sakiko",
+    "tags": [
+      {
+        "label": "Minecraft",
+        "color": "#6cc349"
+      },
+      {
+        "label": "BanGDream",
+        "color": "#e70050"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "Minecraft_QQBot",
+    "desc": "基于 NoneBot2 的 Minecraft 群服互联 QQ 机器人，支持多服务器多种方式连接。",
+    "author_id": 90964775,
+    "homepage": "https://github.com/Minecraft-QQBot/BotServer",
+    "tags": [
+      {
+        "label": "Minecraft",
+        "color": "#ea5252"
+      },
+      {
+        "label": "娱乐",
+        "color": "#37a7e7"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "小安提Bot",
+    "desc": "服务于音游 舞萌DX 的多功能Bot",
+    "author_id": 186144551,
+    "homepage": "https://github.com/Ant1816/Ant1Bot",
+    "tags": [
+      {
+        "label": "maimaiDX",
+        "color": "#52ea9a"
+      },
+      {
+        "label": "音游",
+        "color": "#f74b18"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "CanrotBot",
+    "desc": "有很多实用功能的bot，也有很多没什么用的娱乐功能；接入了大模型，并且有一部分功能可以被大模型调用。主打一个全都有（",
+    "author_id": 18070676,
+    "homepage": "https://github.com/wangyw15/CanrotBot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "Mio澪",
+    "desc": "超可爱多功能Qbot",
+    "author_id": 50508678,
+    "homepage": "https://github.com/EienSakura/mio",
+    "tags": [
+      {
+        "label": "娱乐",
+        "color": "#ea5252"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "AntiFraudBot",
+    "desc": "反诈机器人",
+    "author_id": 104713034,
+    "homepage": "https://github.com/itsevin/AntiFraudBot",
+    "tags": [
+      {
+        "label": "反诈",
+        "color": "#ea5252"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "Nekro Agent Bot",
+    "desc": "基于生成式人工智能与沙盒技术的 Nekro Agent 代理执行 AI 机器人，支持聊天、识图、通用文件处理等扩展能力，提供了 WebUI 维护界面、一键部署脚本",
+    "author_id": 57167362,
+    "homepage": "https://github.com/KroMiose/nekro-agent",
+    "tags": [
+      {
+        "label": "聊天",
+        "color": "#c65856"
+      },
+      {
+        "label": "大模型",
+        "color": "#46a34c"
+      },
+      {
+        "label": "WebUI",
+        "color": "#4a96c6"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "PickStarsBot",
+    "desc": "欢迎使用PickStarsBot！这是一款基于NoneBot2构建的智能QQ机器人，提供丰富的功能，包括一言、历史上的今天、60秒早报等，快来试试吧！",
+    "author_id": 183461085,
+    "homepage": "https://github.com/PickStars308/PickStarsBot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "LiteBot",
+    "desc": "Web功能/MC/数据功能Bot",
+    "author_id": 67693593,
+    "homepage": "https://github.com/LiteSuggarDEV/LiteBot-NEO/",
+    "tags": [
+      {
+        "label": "Minecraft",
+        "color": "#ea5252"
+      },
+      {
+        "label": "Web",
+        "color": "#ea5252"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "Muicebot",
+    "desc": "Muice-Chatbot 的 Nonebot2 实现，支持调用主流大模型，支持 Function Call 和内置 MCP Host 实现",
+    "author_id": 72406624,
+    "homepage": "https://github.com/Moemu/MuiceBot",
+    "tags": [
+      {
+        "label": "LLM",
+        "color": "#3e97ff"
+      }
+    ],
+    "is_official": false
+  },
+  {
+    "name": "nsybot",
+    "desc": "定时获取推特/bilibili等平台用户文章并推送到QQ群",
+    "author_id": 148176849,
+    "homepage": "https://github.com/AhsokaTano26/nsybot",
+    "tags": [],
+    "is_official": false
+  },
+  {
+    "name": "Amrita",
+    "desc": "LLM聊天机器人框架",
+    "author_id": 67693593,
+    "homepage": "https://github.com/LiteSuggarDEV/Amrita",
+    "tags": [
+      {
+        "label": "聊天",
+        "color": "#ea5252"
+      },
+      {
+        "label": "LLM",
+        "color": "#5c86db"
+      },
+      {
+        "label": "快捷部署",
+        "color": "#eebe0b"
+      }
+    ],
+    "is_official": false
+  },
+]

assets/drivers.json5

@@ -0,0 +1,62 @@
+[
+  {
+    "module_name": "~none",
+    "project_link": "",
+    "name": "None",
+    "desc": "None 驱动器",
+    "author_id": 42488585,
+    "homepage": "/docs/advanced/driver",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "~fastapi",
+    "project_link": "nonebot2[fastapi]",
+    "name": "FastAPI",
+    "desc": "FastAPI 驱动器",
+    "author_id": 42488585,
+    "homepage": "/docs/advanced/driver",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "~quart",
+    "project_link": "nonebot2[quart]",
+    "name": "Quart",
+    "desc": "Quart 驱动器",
+    "author_id": 42488585,
+    "homepage": "/docs/advanced/driver",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "~httpx",
+    "project_link": "nonebot2[httpx]",
+    "name": "HTTPX",
+    "desc": "HTTPX 驱动器",
+    "author_id": 42488585,
+    "homepage": "/docs/advanced/driver",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "~websockets",
+    "project_link": "nonebot2[websockets]",
+    "name": "websockets",
+    "desc": "websockets 驱动器",
+    "author_id": 42488585,
+    "homepage": "/docs/advanced/driver",
+    "tags": [],
+    "is_official": true
+  },
+  {
+    "module_name": "~aiohttp",
+    "project_link": "nonebot2[aiohttp]",
+    "name": "AIOHTTP",
+    "desc": "AIOHTTP 驱动器",
+    "author_id": 42488585,
+    "homepage": "/docs/advanced/driver",
+    "tags": [],
+    "is_official": true
+  },
+]

docs_build/Makefile

@@ -1,20 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SOURCEDIR     = .
-BUILDDIR      = _build
-
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs_build/README.rst

@@ -1,12 +0,0 @@
-\-\-\-
-sidebar_position: 1
-id: index
-slug: /api
-\-\-\-
-
-NoneBot 模块
-===============
-
-.. automodule:: nonebot
-   :members:
-   :show-inheritance:

docs_build/adapters/README.rst

@@ -1,43 +0,0 @@
-\-\-\-
-id: index
-slug: /api/adapters/
-\-\-\-
-
-NoneBot.adapters 模块
-=====================
-
-.. automodule:: nonebot.adapters
-   :members:
-   :private-members:
-   :special-members: __init__
-   :show-inheritance:
-
-.. automodule:: nonebot.adapters._adapter
-   :members:
-   :private-members:
-   :special-members: __init__
-   :show-inheritance:
-
-.. automodule:: nonebot.adapters._bot
-   :members:
-   :private-members:
-   :special-members: __init__
-   :show-inheritance:
-
-.. automodule:: nonebot.adapters._message
-   :members:
-   :private-members:
-   :special-members: __init__
-   :show-inheritance:
-
-.. automodule:: nonebot.adapters._event
-   :members:
-   :private-members:
-   :special-members: __init__
-   :show-inheritance:
-
-.. automodule:: nonebot.adapters._template
-   :members:
-   :private-members:
-   :special-members: __init__
-   :show-inheritance:

docs_build/conf.py

@@ -1,82 +0,0 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-import os
-import sys
-
-sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))
-
-# -- Project information -----------------------------------------------------
-
-project = 'nonebot'
-copyright = '2020, richardchien'
-author = 'richardchien'
-
-# The short X.Y version
-version = '2.0.0'
-
-# The full version, including alpha/beta/rc tags
-release = '2.0.0'
-
-# -- General configuration ---------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
-    'sphinx.ext.autodoc',
-    'sphinx.ext.viewcode',
-    'sphinx.ext.todo',
-]
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#
-# This is also used if you do content translation via gettext catalogs.
-# Usually you set "language" from the command line for these cases.
-language = 'zh_CN'
-
-master_doc = "README"
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-
-# -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = 'alabaster'
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-# html_baseurl = '/api/'
-
-# -- Extension configuration -------------------------------------------------
-
-# -- Options for autodoc extension ----------------------------------------------
-autodoc_default_options = {'member-order': 'bysource'}
-autodoc_inherit_docstrings = False
-autodoc_typehints = 'none'
-
-# -- Options for todo extension ----------------------------------------------
-
-# If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = True

docs_build/config.rst

@@ -1,10 +0,0 @@
-\-\-\-
-sidebar_position: 2
-\-\-\-
-
-NoneBot.config 模块
-===================
-
-.. automodule:: nonebot.config
-   :members: Env, Config
-   :show-inheritance:

docs_build/dependencies.rst

@@ -1,11 +0,0 @@
-\-\-\-
-sidebar_position: 8
-\-\-\-
-
-NoneBot.dependencies 模块
-====================
-
-.. automodule:: nonebot.dependencies
-   :members:
-   :private-members:
-   :show-inheritance:

docs_build/drivers/README.rst

@@ -1,13 +0,0 @@
-\-\-\-
-id: index
-slug: /api/drivers/
-\-\-\-
-
-NoneBot.drivers 模块
-=====================
-
-.. automodule:: nonebot.drivers
-   :members:
-   :private-members:
-   :special-members: __init__
-   :show-inheritance:

docs_build/drivers/aiohttp.rst

@@ -1,9 +0,0 @@
-
-
-NoneBot.drivers.aiohttp 模块
-=============================
-
-.. automodule:: nonebot.drivers.aiohttp
-   :members:
-   :private-members:
-   :show-inheritance:

docs_build/drivers/fastapi.rst

@@ -1,9 +0,0 @@
-
-
-NoneBot.drivers.fastapi 模块
-=============================
-
-.. automodule:: nonebot.drivers.fastapi
-   :members:
-   :private-members:
-   :show-inheritance:

docs_build/drivers/httpx.rst

@@ -1,9 +0,0 @@
-
-
-NoneBot.drivers.httpx 模块
-=============================
-
-.. automodule:: nonebot.drivers.httpx
-   :members:
-   :private-members:
-   :show-inheritance:

docs_build/drivers/quart.rst

@@ -1,9 +0,0 @@
-
-
-NoneBot.drivers.quart 模块
-==========================
-
-.. automodule:: nonebot.drivers.quart
-   :members:
-   :private-members:
-   :show-inheritance:

docs_build/drivers/websockets.rst

@@ -1,9 +0,0 @@
-
-
-NoneBot.drivers.websockets 模块
-=============================
-
-.. automodule:: nonebot.drivers.websockets
-   :members:
-   :private-members:
-   :show-inheritance:

docs_build/exception.rst

@@ -1,10 +0,0 @@
-\-\-\-
-sidebar_position: 12
-\-\-\-
-
-NoneBot.exception 模块
-======================
-
-.. automodule:: nonebot.exception
-   :members:
-   :show-inheritance:

docs_build/log.rst

@@ -1,10 +0,0 @@
-\-\-\-
-sidebar_position: 9
-\-\-\-
-
-NoneBot.log 模块
-=================
-
-.. automodule:: nonebot.log
-   :members:
-   :show-inheritance:

docs_build/make.bat

@@ -1,35 +0,0 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=.
-set BUILDDIR=_build
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd

docs_build/matcher.rst

@@ -1,12 +0,0 @@
-\-\-\-
-sidebar_position: 5
-\-\-\-
-
-NoneBot.matcher 模块
-====================
-
-.. automodule:: nonebot.matcher
-   :members:
-   :private-members:
-   :special-members: __init__
-   :show-inheritance:

docs_build/message.rst

@@ -1,10 +0,0 @@
-\-\-\-
-sidebar_position: 4
-\-\-\-
-
-NoneBot.message 模块
-======================
-
-.. automodule:: nonebot.message
-   :members:
-   :show-inheritance:

docs_build/permission.rst

@@ -1,11 +0,0 @@
-\-\-\-
-sidebar_position: 7
-\-\-\-
-
-NoneBot.permission 模块
-=======================
-
-.. automodule:: nonebot.permission
-   :members:
-   :show-inheritance:
-   :special-members:

docs_build/plugin.rst

@@ -1,31 +0,0 @@
-\-\-\-
-sidebar_position: 3
-\-\-\-
-
-NoneBot.plugin 模块
-====================
-
-.. automodule:: nonebot.plugin
-   :members:
-   :show-inheritance:
-   :special-members: __init__
-
-.. automodule:: nonebot.plugin.plugin
-   :members:
-   :show-inheritance:
-   :special-members: __init__
-
-.. automodule:: nonebot.plugin.on
-   :members:
-   :show-inheritance:
-   :special-members: __init__
-
-.. automodule:: nonebot.plugin.load
-   :members:
-   :show-inheritance:
-   :special-members: __init__
-
-.. automodule:: nonebot.plugin.export
-   :members:
-   :show-inheritance:
-   :special-members: __init__

docs_build/rule.rst

@@ -1,11 +0,0 @@
-\-\-\-
-sidebar_position: 6
-\-\-\-
-
-NoneBot.rule 模块
-====================
-
-.. automodule:: nonebot.rule
-   :members:
-   :special-members:
-   :show-inheritance:

docs_build/typing.rst

@@ -1,10 +0,0 @@
-\-\-\-
-sidebar_position: 11
-\-\-\-
-
-NoneBot.typing 模块
-===================
-
-.. automodule:: nonebot.typing
-   :members:
-   :show-inheritance:

docs_build/utils.rst

@@ -1,10 +0,0 @@
-\-\-\-
-sidebar_position: 10
-\-\-\-
-
-NoneBot.utils 模块
-==================
-
-.. automodule:: nonebot.utils
-   :members:
-   :show-inheritance:

nonebot/__init__.py

@@ -1,164 +1,226 @@
-"""
-快捷导入
-========
+"""本模块主要定义了 NoneBot 启动所需函数，供 bot 入口文件调用。
 
-为方便使用，``nonebot`` 模块从子模块导入了部分内容
+## 快捷导入
 
-- ``on_message`` => ``nonebot.plugin.on_message``
-- ``on_notice`` => ``nonebot.plugin.on_notice``
-- ``on_request`` => ``nonebot.plugin.on_request``
-- ``on_metaevent`` => ``nonebot.plugin.on_metaevent``
-- ``on_startswith`` => ``nonebot.plugin.on_startswith``
-- ``on_endswith`` => ``nonebot.plugin.on_endswith``
-- ``on_keyword`` => ``nonebot.plugin.on_keyword``
-- ``on_command`` => ``nonebot.plugin.on_command``
-- ``on_shell_command`` => ``nonebot.plugin.on_shell_command``
-- ``on_regex`` => ``nonebot.plugin.on_regex``
-- ``CommandGroup`` => ``nonebot.plugin.CommandGroup``
-- ``Matchergroup`` => ``nonebot.plugin.MatcherGroup``
-- ``load_plugin`` => ``nonebot.plugin.load_plugin``
-- ``load_plugins`` => ``nonebot.plugin.load_plugins``
-- ``load_all_plugins`` => ``nonebot.plugin.load_all_plugins``
-- ``load_from_json`` => ``nonebot.plugin.load_from_json``
-- ``load_from_toml`` => ``nonebot.plugin.load_from_toml``
-- ``load_builtin_plugins`` => ``nonebot.plugin.load_builtin_plugins``
-- ``get_plugin`` => ``nonebot.plugin.get_plugin``
-- ``get_loaded_plugins`` => ``nonebot.plugin.get_loaded_plugins``
-- ``export`` => ``nonebot.plugin.export``
-- ``require`` => ``nonebot.plugin.require``
+为方便使用，本模块从子模块导入了部分内容，以下内容可以直接通过本模块导入:
+
+- `on` => {ref}``on` <nonebot.plugin.on.on>`
+- `on_metaevent` => {ref}``on_metaevent` <nonebot.plugin.on.on_metaevent>`
+- `on_message` => {ref}``on_message` <nonebot.plugin.on.on_message>`
+- `on_notice` => {ref}``on_notice` <nonebot.plugin.on.on_notice>`
+- `on_request` => {ref}``on_request` <nonebot.plugin.on.on_request>`
+- `on_startswith` => {ref}``on_startswith` <nonebot.plugin.on.on_startswith>`
+- `on_endswith` => {ref}``on_endswith` <nonebot.plugin.on.on_endswith>`
+- `on_fullmatch` => {ref}``on_fullmatch` <nonebot.plugin.on.on_fullmatch>`
+- `on_keyword` => {ref}``on_keyword` <nonebot.plugin.on.on_keyword>`
+- `on_command` => {ref}``on_command` <nonebot.plugin.on.on_command>`
+- `on_shell_command` => {ref}``on_shell_command` <nonebot.plugin.on.on_shell_command>`
+- `on_regex` => {ref}``on_regex` <nonebot.plugin.on.on_regex>`
+- `on_type` => {ref}``on_type` <nonebot.plugin.on.on_type>`
+- `CommandGroup` => {ref}``CommandGroup` <nonebot.plugin.on.CommandGroup>`
+- `Matchergroup` => {ref}``MatcherGroup` <nonebot.plugin.on.MatcherGroup>`
+- `load_plugin` => {ref}``load_plugin` <nonebot.plugin.load.load_plugin>`
+- `load_plugins` => {ref}``load_plugins` <nonebot.plugin.load.load_plugins>`
+- `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>`
+- `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_config` => {ref}``get_plugin_config` <nonebot.plugin.get_plugin_config>`
+- `require` => {ref}``require` <nonebot.plugin.load.require>`
+
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 0
+    description: nonebot 模块
 """
 
-import importlib
-from typing import Any, Dict, Type, Optional
+from importlib.metadata import version
+import os
+from typing import Any, Optional, TypeVar, Union, overload
 
-import pkg_resources
+import loguru
 
-from nonebot.adapters import Bot
-from nonebot.utils import escape_tag
-from nonebot.config import Env, Config
-from nonebot.log import logger, default_filter
-from nonebot.drivers import Driver, ReverseDriver, combine_driver
+from nonebot.adapters import Adapter, Bot
+from nonebot.compat import model_dump
+from nonebot.config import DOTENV_TYPE, Config, Env
+from nonebot.drivers import ASGIMixin, Driver, combine_driver
+from nonebot.log import logger as logger
+from nonebot.utils import escape_tag, resolve_dot_notation
 
 try:
-    _dist: pkg_resources.Distribution = pkg_resources.get_distribution("nonebot2")
-    __version__ = _dist.version
-    VERSION = _dist.parsed_version
-except pkg_resources.DistributionNotFound:  # pragma: no cover
+    __version__ = version("nonebot2")
+except Exception:  # pragma: no cover
     __version__ = None
-    VERSION = None
+
+A = TypeVar("A", bound=Adapter)
 
 _driver: Optional[Driver] = None
 
 
 def get_driver() -> Driver:
-    """
-    :说明:
+    """获取全局 {ref}`nonebot.drivers.Driver` 实例。
 
-      获取全局 Driver 对象。可用于在计划任务的回调中获取当前 Driver 对象。
+    可用于在计划任务的回调等情形中获取当前 {ref}`nonebot.drivers.Driver` 实例。
 
-    :返回:
+    返回:
+        全局 {ref}`nonebot.drivers.Driver` 对象
 
-      * ``Driver``: 全局 Driver 对象
-
-    :异常:
-
-      * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
-
-    :用法:
-
-    .. code-block:: python
+    异常:
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化
+            ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
+    用法:
+        ```python
         driver = nonebot.get_driver()
-
+        ```
     """
     if _driver is None:
         raise ValueError("NoneBot has not been initialized.")
     return _driver
 
 
-def get_app() -> Any:
+@overload
+def get_adapter(name: str) -> Adapter:
     """
-    :说明:
+    参数:
+        name: 适配器名称
 
-      获取全局 Driver 对应 Server App 对象。
+    返回:
+        指定名称的 {ref}`nonebot.adapters.Adapter` 对象
+    """
 
-    :返回:
 
-      * ``Any``: Server App 对象
+@overload
+def get_adapter(name: type[A]) -> A:
+    """
+    参数:
+        name: 适配器类型
 
-    :异常:
+    返回:
+        指定类型的 {ref}`nonebot.adapters.Adapter` 对象
+    """
 
-      * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
 
-    :用法:
+def get_adapter(name: Union[str, type[Adapter]]) -> Adapter:
+    """获取已注册的 {ref}`nonebot.adapters.Adapter` 实例。
 
-    .. code-block:: python
+    异常:
+        ValueError: 指定的 {ref}`nonebot.adapters.Adapter` 未注册
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化
+            ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
+    用法:
+        ```python
+        from nonebot.adapters.console import Adapter
+        adapter = nonebot.get_adapter(Adapter)
+        ```
+    """
+    adapters = get_adapters()
+    target = name if isinstance(name, str) else name.get_name()
+    if target not in adapters:
+        raise ValueError(f"Adapter {target} not registered.")
+    return adapters[target]
+
+
+def get_adapters() -> dict[str, Adapter]:
+    """获取所有已注册的 {ref}`nonebot.adapters.Adapter` 实例。
+
+    返回:
+        所有 {ref}`nonebot.adapters.Adapter` 实例字典
+
+    异常:
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化
+            ({ref}`nonebot.init <nonebot.init>` 尚未调用)
+
+    用法:
+        ```python
+        adapters = nonebot.get_adapters()
+        ```
+    """
+    return get_driver()._adapters.copy()
+
+
+def get_app() -> Any:
+    """获取全局 {ref}`nonebot.drivers.ASGIMixin` 对应的 Server App 对象。
+
+    返回:
+        Server App 对象
+
+    异常:
+        AssertionError: 全局 Driver 对象不是 {ref}`nonebot.drivers.ASGIMixin` 类型
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化
+            ({ref}`nonebot.init <nonebot.init>` 尚未调用)
+
+    用法:
+        ```python
         app = nonebot.get_app()
-
+        ```
     """
     driver = get_driver()
-    assert isinstance(
-        driver, ReverseDriver
-    ), "app object is only available for reverse driver"
+    assert isinstance(driver, ASGIMixin), "app object is only available for asgi driver"
     return driver.server_app
 
 
 def get_asgi() -> Any:
-    """
-    :说明:
+    """获取全局 {ref}`nonebot.drivers.ASGIMixin` 对应的
+    [ASGI](https://asgi.readthedocs.io/) 对象。
 
-      获取全局 Driver 对应 Asgi 对象。
+    返回:
+        ASGI 对象
 
-    :返回:
-
-      * ``Any``: Asgi 对象
-
-    :异常:
-
-      * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
-
-    :用法:
-
-    .. code-block:: python
+    异常:
+        AssertionError: 全局 Driver 对象不是 {ref}`nonebot.drivers.ASGIMixin` 类型
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化
+            ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
+    用法:
+        ```python
         asgi = nonebot.get_asgi()
-
+        ```
     """
     driver = get_driver()
-    assert isinstance(
-        driver, ReverseDriver
-    ), "asgi object is only available for reverse driver"
+    assert isinstance(driver, ASGIMixin), (
+        "asgi object is only available for asgi driver"
+    )
     return driver.asgi
 
 
 def get_bot(self_id: Optional[str] = None) -> Bot:
-    """
-    :说明:
+    """获取一个连接到 NoneBot 的 {ref}`nonebot.adapters.Bot` 对象。
 
-      当提供 self_id 时，此函数是 get_bots()[self_id] 的简写；当不提供时，返回一个 Bot。
+    当提供 `self_id` 时，此函数是 `get_bots()[self_id]` 的简写；
+    当不提供时，返回一个 {ref}`nonebot.adapters.Bot`。
 
-    :参数:
+    参数:
+        self_id: 用来识别 {ref}`nonebot.adapters.Bot` 的
+            {ref}`nonebot.adapters.Bot.self_id` 属性
 
-      * ``self_id: Optional[str]``: 用来识别 Bot 的 ID
+    返回:
+        {ref}`nonebot.adapters.Bot` 对象
 
-    :返回:
+    异常:
+        KeyError: 对应 self_id 的 Bot 不存在
+        ValueError: 没有传入 self_id 且没有 Bot 可用
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化
+            ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
-      * ``Bot``: Bot 对象
-
-    :异常:
-
-      * ``KeyError``: 对应 ID 的 Bot 不存在
-      * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
-      * ``ValueError``: 没有传入 ID 且没有 Bot 可用
-
-    :用法:
-
-    .. code-block:: python
-
-        assert nonebot.get_bot('12345') == nonebot.get_bots()['12345']
+    用法:
+        ```python
+        assert nonebot.get_bot("12345") == nonebot.get_bots()["12345"]
 
         another_unspecified_bot = nonebot.get_bot()
+        ```
     """
     bots = get_bots()
     if self_id is not None:
@@ -170,156 +232,136 @@ def get_bot(self_id: Optional[str] = None) -> Bot:
     raise ValueError("There are no bots to get.")
 
 
-def get_bots() -> Dict[str, Bot]:
-    """
-    :说明:
+def get_bots() -> dict[str, Bot]:
+    """获取所有连接到 NoneBot 的 {ref}`nonebot.adapters.Bot` 对象。
 
-      获取所有通过 ws 连接 NoneBot 的 Bot 对象。
+    返回:
+        一个以 {ref}`nonebot.adapters.Bot.self_id` 为键
+        {ref}`nonebot.adapters.Bot` 对象为值的字典
 
-    :返回:
-
-      * ``Dict[str, Bot]``: 一个以字符串 ID 为键，Bot 对象为值的字典
-
-    :异常:
-
-      * ``ValueError``: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用)
-
-    :用法:
-
-    .. code-block:: python
+    异常:
+        ValueError: 全局 {ref}`nonebot.drivers.Driver` 对象尚未初始化
+            ({ref}`nonebot.init <nonebot.init>` 尚未调用)
 
+    用法:
+        ```python
         bots = nonebot.get_bots()
-
+        ```
     """
-    driver = get_driver()
-    return driver.bots
+    return get_driver().bots
 
 
-def _resolve_dot_notation(
-    obj_str: str, default_attr: str, default_prefix: Optional[str] = None
-) -> Any:
-    modulename, _, cls = obj_str.partition(":")
-    if default_prefix is not None and modulename.startswith("~"):
-        modulename = default_prefix + modulename[1:]
-    module = importlib.import_module(modulename)
-    if not cls:
-        return getattr(module, default_attr)
-    instance = module
-    for attr_str in cls.split("."):
-        instance = getattr(instance, attr_str)
-    return instance
-
-
-def _resolve_combine_expr(obj_str: str) -> Type[Driver]:
+def _resolve_combine_expr(obj_str: str) -> type[Driver]:
     drivers = obj_str.split("+")
-    DriverClass = _resolve_dot_notation(
+    DriverClass = resolve_dot_notation(
         drivers[0], "Driver", default_prefix="nonebot.drivers."
     )
     if len(drivers) == 1:
         logger.trace(f"Detected driver {DriverClass} with no mixins.")
         return DriverClass
     mixins = [
-        _resolve_dot_notation(mixin, "Mixin", default_prefix="nonebot.drivers.")
+        resolve_dot_notation(mixin, "Mixin", default_prefix="nonebot.drivers.")
         for mixin in drivers[1:]
     ]
     logger.trace(f"Detected driver {DriverClass} with mixins {mixins}.")
     return combine_driver(DriverClass, *mixins)
 
 
-def init(*, _env_file: Optional[str] = None, **kwargs):
-    """
-    :说明:
+def _log_patcher(record: "loguru.Record"):
+    """使用插件标识优化日志展示"""
+    record["name"] = (
+        plugin.id_
+        if (module_name := record["name"])
+        and (plugin := get_plugin_by_module_name(module_name))
+        else (module_name and module_name.split(".", maxsplit=1)[0])
+    )
 
-      初始化 NoneBot 以及 全局 Driver 对象。
 
-      NoneBot 将会从 .env 文件中读取环境信息，并使用相应的 env 文件配置。
+def init(*, _env_file: Optional[DOTENV_TYPE] = None, **kwargs: Any) -> None:
+    """初始化 NoneBot 以及 全局 {ref}`nonebot.drivers.Driver` 对象。
 
-      你也可以传入自定义的 _env_file 来指定 NoneBot 从该文件读取配置。
+    NoneBot 将会从 .env 文件中读取环境信息，并使用相应的 env 文件配置。
 
-    :参数:
+    也可以传入自定义的 `_env_file` 来指定 NoneBot 从该文件读取配置。
 
-      * ``_env_file: Optional[str]``: 配置文件名，默认从 .env.{env_name} 中读取配置
-      * ``**kwargs``: 任意变量，将会存储到 Config 对象里
-
-    :返回:
-
-      - ``None``
-
-    :用法:
-
-    .. code-block:: python
+    参数:
+        _env_file: 配置文件名，默认从 `.env.{env_name}` 中读取配置
+        kwargs: 任意变量，将会存储到 {ref}`nonebot.drivers.Driver.config` 对象里
 
+    用法:
+        ```python
         nonebot.init(database=Database(...))
-
+        ```
     """
     global _driver
     if not _driver:
         logger.success("NoneBot is initializing...")
         env = Env()
+        _env_file = _env_file or f".env.{env.environment}"
         config = Config(
             **kwargs,
-            _common_config=env.dict(),
-            _env_file=_env_file or f".env.{env.environment}",
+            _env_file=(
+                (".env", _env_file)
+                if isinstance(_env_file, (str, os.PathLike))
+                else _env_file
+            ),
         )
 
-        default_filter.level = config.log_level
+        logger.configure(
+            extra={"nonebot_log_level": config.log_level}, patcher=_log_patcher
+        )
         logger.opt(colors=True).info(
             f"Current <y><b>Env: {escape_tag(env.environment)}</b></y>"
         )
         logger.opt(colors=True).debug(
-            f"Loaded <y><b>Config</b></y>: {escape_tag(str(config.dict()))}"
+            f"Loaded <y><b>Config</b></y>: {escape_tag(str(model_dump(config)))}"
         )
 
-        DriverClass: Type[Driver] = _resolve_combine_expr(config.driver)
+        DriverClass = _resolve_combine_expr(config.driver)
         _driver = DriverClass(env, config)
 
 
 def run(*args: Any, **kwargs: Any) -> None:
-    """
-    :说明:
+    """启动 NoneBot，即运行全局 {ref}`nonebot.drivers.Driver` 对象。
 
-      启动 NoneBot，即运行全局 Driver 对象。
-
-    :参数:
-
-      * ``*args``: 传入 Driver.run 的位置参数
-      * ``**kwargs``: 传入 Driver.run 的命名参数
-
-    :返回:
-
-      - ``None``
-
-    :用法:
-
-    .. code-block:: python
+    参数:
+        args: 传入 {ref}`nonebot.drivers.Driver.run` 的位置参数
+        kwargs: 传入 {ref}`nonebot.drivers.Driver.run` 的命名参数
 
+    用法:
+        ```python
         nonebot.run(host="127.0.0.1", port=8080)
-
+        ```
     """
     logger.success("Running NoneBot...")
     get_driver().run(*args, **kwargs)
 
 
-import nonebot.params as params
-from nonebot.plugin import export as export
-from nonebot.plugin import require as require
-from nonebot.plugin import on_regex as on_regex
-from nonebot.plugin import on_notice as on_notice
-from nonebot.plugin import get_plugin as get_plugin
-from nonebot.plugin import on_command as on_command
-from nonebot.plugin import on_keyword as on_keyword
-from nonebot.plugin import on_message as on_message
-from nonebot.plugin import on_request as on_request
-from nonebot.plugin import load_plugin as load_plugin
-from nonebot.plugin import on_endswith as on_endswith
 from nonebot.plugin import CommandGroup as CommandGroup
 from nonebot.plugin import MatcherGroup as MatcherGroup
-from nonebot.plugin import load_plugins as load_plugins
-from nonebot.plugin import on_metaevent as on_metaevent
-from nonebot.plugin import on_startswith as on_startswith
+from nonebot.plugin import get_available_plugin_names as get_available_plugin_names
+from nonebot.plugin import get_loaded_plugins as get_loaded_plugins
+from nonebot.plugin import get_plugin as get_plugin
+from nonebot.plugin import get_plugin_by_module_name as get_plugin_by_module_name
+from nonebot.plugin import get_plugin_config as get_plugin_config
+from nonebot.plugin import load_all_plugins as load_all_plugins
+from nonebot.plugin import load_builtin_plugin as load_builtin_plugin
+from nonebot.plugin import load_builtin_plugins as load_builtin_plugins
 from nonebot.plugin import load_from_json as load_from_json
 from nonebot.plugin import load_from_toml as load_from_toml
-from nonebot.plugin import load_all_plugins as load_all_plugins
+from nonebot.plugin import load_plugin as load_plugin
+from nonebot.plugin import load_plugins as load_plugins
+from nonebot.plugin import on as on
+from nonebot.plugin import on_command as on_command
+from nonebot.plugin import on_endswith as on_endswith
+from nonebot.plugin import on_fullmatch as on_fullmatch
+from nonebot.plugin import on_keyword as on_keyword
+from nonebot.plugin import on_message as on_message
+from nonebot.plugin import on_metaevent as on_metaevent
+from nonebot.plugin import on_notice as on_notice
+from nonebot.plugin import on_regex as on_regex
+from nonebot.plugin import on_request as on_request
 from nonebot.plugin import on_shell_command as on_shell_command
-from nonebot.plugin import get_loaded_plugins as get_loaded_plugins
-from nonebot.plugin import load_builtin_plugins as load_builtin_plugins
+from nonebot.plugin import on_startswith as on_startswith
+from nonebot.plugin import on_type as on_type
+from nonebot.plugin import require as require

nonebot/adapters/__init__.py

@@ -1,28 +1,31 @@
-"""
-协议适配基类
-============
+"""本模块定义了协议适配基类，各协议请继承以下基类。
 
-各协议请继承以下基类，并使用 ``driver.register_adapter`` 注册适配器
+使用 {ref}`nonebot.drivers.Driver.register_adapter` 注册适配器。
+
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 0
+    description: nonebot.adapters 模块
 """
 
-from typing import Iterable
+from nonebot.internal.adapter import Adapter as Adapter
+from nonebot.internal.adapter import Bot as Bot
+from nonebot.internal.adapter import Event as Event
+from nonebot.internal.adapter import Message as Message
+from nonebot.internal.adapter import MessageSegment as MessageSegment
+from nonebot.internal.adapter import MessageTemplate as MessageTemplate
 
-try:
-    import pkg_resources
-
-    pkg_resources.declare_namespace(__name__)
-    del pkg_resources
-except ImportError:
-    import pkgutil
-
-    __path__: Iterable[str] = pkgutil.extend_path(__path__, __name__)  # type: ignore
-    del pkgutil
-except Exception:
-    pass
-
-from ._bot import Bot as Bot
-from ._event import Event as Event
-from ._adapter import Adapter as Adapter
-from ._message import Message as Message
-from ._message import MessageSegment as MessageSegment
-from ._template import MessageTemplate as MessageTemplate
+__autodoc__ = {
+    "Bot": True,
+    "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/adapters/_adapter.py

@@ -1,75 +0,0 @@
-import abc
-from contextlib import asynccontextmanager
-from typing import Any, Dict, AsyncGenerator
-
-from ._bot import Bot
-from nonebot.config import Config
-from nonebot.drivers import (
-    Driver,
-    Request,
-    Response,
-    WebSocket,
-    ForwardDriver,
-    ReverseDriver,
-    HTTPServerSetup,
-    WebSocketServerSetup,
-)
-
-
-class Adapter(abc.ABC):
-    def __init__(self, driver: Driver, **kwargs: Any):
-        self.driver: Driver = driver
-        self.bots: Dict[str, Bot] = {}
-
-    @classmethod
-    @abc.abstractmethod
-    def get_name(cls) -> str:
-        raise NotImplementedError
-
-    @property
-    def config(self) -> Config:
-        return self.driver.config
-
-    def bot_connect(self, bot: Bot) -> None:
-        self.driver._bot_connect(bot)
-        self.bots[bot.self_id] = bot
-
-    def bot_disconnect(self, bot: Bot) -> None:
-        self.driver._bot_disconnect(bot)
-        self.bots.pop(bot.self_id, None)
-
-    def setup_http_server(self, setup: HTTPServerSetup):
-        if not isinstance(self.driver, ReverseDriver):
-            raise TypeError("Current driver does not support http server")
-        self.driver.setup_http_server(setup)
-
-    def setup_websocket_server(self, setup: WebSocketServerSetup):
-        if not isinstance(self.driver, ReverseDriver):
-            raise TypeError("Current driver does not support websocket server")
-        self.driver.setup_websocket_server(setup)
-
-    async def request(self, setup: Request) -> Response:
-        if not isinstance(self.driver, ForwardDriver):
-            raise TypeError("Current driver does not support http client")
-        return await self.driver.request(setup)
-
-    @asynccontextmanager
-    async def websocket(self, setup: Request) -> AsyncGenerator[WebSocket, None]:
-        if not isinstance(self.driver, ForwardDriver):
-            raise TypeError("Current driver does not support websocket client")
-        async with self.driver.websocket(setup) as ws:
-            yield ws
-
-    @abc.abstractmethod
-    async def _call_api(self, bot: Bot, api: str, **data) -> Any:
-        """
-        :说明:
-
-          ``adapter`` 实际调用 api 的逻辑实现函数，实现该方法以调用 api。
-
-        :参数:
-
-          * ``api: str``: API 名称
-          * ``**data``: API 数据
-        """
-        raise NotImplementedError

nonebot/adapters/_bot.py

@@ -1,178 +0,0 @@
-import abc
-import asyncio
-from functools import partial
-from typing_extensions import Protocol
-from typing import TYPE_CHECKING, Any, Set, Union, Optional
-
-from nonebot.log import logger
-from nonebot.config import Config
-from nonebot.exception import MockApiException
-from nonebot.typing import T_CalledAPIHook, T_CallingAPIHook
-
-if TYPE_CHECKING:
-    from ._event import Event
-    from ._adapter import Adapter
-    from ._message import Message, MessageSegment
-
-
-class _ApiCall(Protocol):
-    async def __call__(self, **kwargs: Any) -> Any:
-        ...
-
-
-class Bot(abc.ABC):
-    """
-    Bot 基类。用于处理上报消息，并提供 API 调用接口。
-    """
-
-    _calling_api_hook: Set[T_CallingAPIHook] = set()
-    """
-    :类型: ``Set[T_CallingAPIHook]``
-    :说明: call_api 时执行的函数
-    """
-    _called_api_hook: Set[T_CalledAPIHook] = set()
-    """
-    :类型: ``Set[T_CalledAPIHook]``
-    :说明: call_api 后执行的函数
-    """
-
-    def __init__(self, adapter: "Adapter", self_id: str):
-        """
-        :参数:
-
-          * ``self_id: str``: 机器人 ID
-          * ``request: HTTPConnection``: request 连接对象
-        """
-        self.adapter: "Adapter" = adapter
-        self.self_id: str = self_id
-        """机器人 ID"""
-
-    def __getattr__(self, name: str) -> _ApiCall:
-        return partial(self.call_api, name)
-
-    @property
-    def type(self) -> str:
-        return self.adapter.get_name()
-
-    @property
-    def config(self) -> Config:
-        return self.adapter.config
-
-    async def call_api(self, api: str, **data: Any) -> Any:
-        """
-        :说明:
-
-          调用机器人 API 接口，可以通过该函数或直接通过 bot 属性进行调用
-
-        :参数:
-
-          * ``api: str``: API 名称
-          * ``**data``: API 数据
-
-        :示例:
-
-        .. code-block:: python
-
-            await bot.call_api("send_msg", message="hello world")
-            await bot.send_msg(message="hello world")
-        """
-
-        result: Any = None
-        skip_calling_api: bool = False
-        exception: Optional[Exception] = None
-
-        coros = list(map(lambda x: x(self, api, data), self._calling_api_hook))
-        if coros:
-            try:
-                logger.debug("Running CallingAPI hooks...")
-                await asyncio.gather(*coros)
-            except MockApiException as e:
-                skip_calling_api = True
-                result = e.result
-                logger.debug(
-                    f"Calling API {api} is cancelled. Return {result} instead."
-                )
-            except Exception as e:
-                logger.opt(colors=True, exception=e).error(
-                    "<r><bg #f8bbd0>Error when running CallingAPI hook. "
-                    "Running cancelled!</bg #f8bbd0></r>"
-                )
-
-        if not skip_calling_api:
-            try:
-                result = await self.adapter._call_api(self, api, **data)
-            except Exception as e:
-                exception = e
-
-        coros = list(
-            map(lambda x: x(self, exception, api, data, result), self._called_api_hook)
-        )
-        if coros:
-            try:
-                logger.debug("Running CalledAPI hooks...")
-                await asyncio.gather(*coros)
-            except MockApiException as e:
-                result = e.result
-                logger.debug(
-                    f"Calling API {api} result is mocked. Return {result} instead."
-                )
-            except Exception as e:
-                logger.opt(colors=True, exception=e).error(
-                    "<r><bg #f8bbd0>Error when running CalledAPI hook. "
-                    "Running cancelled!</bg #f8bbd0></r>"
-                )
-
-        if exception:
-            raise exception
-        return result
-
-    @abc.abstractmethod
-    async def send(
-        self, event: "Event", message: Union[str, "Message", "MessageSegment"], **kwargs
-    ) -> Any:
-        """
-        :说明:
-
-          调用机器人基础发送消息接口
-
-        :参数:
-
-          * ``event: Event``: 上报事件
-          * ``message: Union[str, Message, MessageSegment]``: 要发送的消息
-          * ``**kwargs``
-        """
-        raise NotImplementedError
-
-    @classmethod
-    def on_calling_api(cls, func: T_CallingAPIHook) -> T_CallingAPIHook:
-        """
-        :说明:
-
-          调用 api 预处理。
-
-        :参数:
-
-          * ``bot: Bot``: 当前 bot 对象
-          * ``api: str``: 调用的 api 名称
-          * ``data: Dict[str, Any]``: api 调用的参数字典
-        """
-        cls._calling_api_hook.add(func)
-        return func
-
-    @classmethod
-    def on_called_api(cls, func: T_CalledAPIHook) -> T_CalledAPIHook:
-        """
-        :说明:
-
-          调用 api 后处理。
-
-        :参数:
-
-          * ``bot: Bot``: 当前 bot 对象
-          * ``exception: Optional[Exception]``: 调用 api 时发生的错误
-          * ``api: str``: 调用的 api 名称
-          * ``data: Dict[str, Any]``: api 调用的参数字典
-          * ``result: Any``: api 调用的返回
-        """
-        cls._called_api_hook.add(func)
-        return func

nonebot/adapters/_event.py

@@ -1,137 +0,0 @@
-import abc
-
-from pydantic import BaseModel
-
-from ._message import Message
-from nonebot.utils import DataclassEncoder
-
-
-class Event(abc.ABC, BaseModel):
-    """Event 基类。提供获取关键信息的方法，其余信息可直接获取。"""
-
-    class Config:
-        extra = "allow"
-        json_encoders = {Message: DataclassEncoder}
-
-    @abc.abstractmethod
-    def get_type(self) -> str:
-        """
-        :说明:
-
-          获取事件类型的方法，类型通常为 NoneBot 内置的四种类型。
-
-        :返回:
-
-          * ``Literal["message", "notice", "request", "meta_event"]``
-          * 其他自定义 ``str``
-        """
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def get_event_name(self) -> str:
-        """
-        :说明:
-
-          获取事件名称的方法。
-
-        :返回:
-
-          * ``str``
-        """
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def get_event_description(self) -> str:
-        """
-        :说明:
-
-          获取事件描述的方法，通常为事件具体内容。
-
-        :返回:
-
-          * ``str``
-        """
-        raise NotImplementedError
-
-    def __str__(self) -> str:
-        return f"[{self.get_event_name()}]: {self.get_event_description()}"
-
-    def get_log_string(self) -> str:
-        """
-        :说明:
-
-          获取事件日志信息的方法，通常你不需要修改这个方法，只有当希望 NoneBot 隐藏该事件日志时，可以抛出 ``NoLogException`` 异常。
-
-        :返回:
-
-          * ``str``
-
-        :异常:
-
-          - ``NoLogException``
-        """
-        return f"[{self.get_event_name()}]: {self.get_event_description()}"
-
-    @abc.abstractmethod
-    def get_user_id(self) -> str:
-        """
-        :说明:
-
-          获取事件主体 id 的方法，通常是用户 id 。
-
-        :返回:
-
-          * ``str``
-        """
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def get_session_id(self) -> str:
-        """
-        :说明:
-
-          获取会话 id 的方法，用于判断当前事件属于哪一个会话，通常是用户 id、群组 id 组合。
-
-        :返回:
-
-          * ``str``
-        """
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def get_message(self) -> "Message":
-        """
-        :说明:
-
-          获取事件消息内容的方法。
-
-        :返回:
-
-          * ``Message``
-        """
-        raise NotImplementedError
-
-    def get_plaintext(self) -> str:
-        """
-        :说明:
-
-          获取消息纯文本的方法，通常不需要修改，默认通过 ``get_message().extract_plain_text`` 获取。
-
-        :返回:
-
-          * ``str``
-        """
-        return self.get_message().extract_plain_text()
-
-    @abc.abstractmethod
-    def is_tome(self) -> bool:
-        """
-        :说明:
-
-          获取事件是否与机器人有关的方法。
-
-        :返回:
-
-          * ``bool``
-        """
-        raise NotImplementedError

nonebot/adapters/_message.py

@@ -1,232 +0,0 @@
-import abc
-from copy import deepcopy
-from dataclasses import field, asdict, dataclass
-from typing import (
-    Any,
-    Dict,
-    List,
-    Type,
-    Union,
-    Generic,
-    Mapping,
-    TypeVar,
-    Iterable,
-)
-
-from ._template import MessageTemplate
-
-T = TypeVar("T")
-TMS = TypeVar("TMS", covariant=True)
-TM = TypeVar("TM", bound="Message")
-
-
-@dataclass
-class MessageSegment(Mapping, abc.ABC, Generic[TM]):
-    """消息段基类"""
-
-    type: str
-    """
-    - 类型: ``str``
-    - 说明: 消息段类型
-    """
-    data: Dict[str, Any] = field(default_factory=lambda: {})
-    """
-    - 类型: ``Dict[str, Union[str, list]]``
-    - 说明: 消息段数据
-    """
-
-    @classmethod
-    @abc.abstractmethod
-    def get_message_class(cls) -> Type[TM]:
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def __str__(self) -> str:
-        """该消息段所代表的 str，在命令匹配部分使用"""
-        raise NotImplementedError
-
-    def __len__(self) -> int:
-        return len(str(self))
-
-    def __ne__(self: T, other: T) -> bool:
-        return not self == other
-
-    def __add__(self, other: Union[str, Mapping, Iterable[Mapping]]) -> TM:
-        return self.get_message_class()(self) + other  # type: ignore
-
-    def __radd__(self, other: Union[str, Mapping, Iterable[Mapping]]) -> TM:
-        return self.get_message_class()(other) + self  # type: ignore
-
-    def __getitem__(self, key: str):
-        return getattr(self, key)
-
-    def __setitem__(self, key: str, value: Any):
-        return setattr(self, key, value)
-
-    def __iter__(self):
-        yield from asdict(self).keys()
-
-    def __contains__(self, key: Any) -> bool:
-        return key in asdict(self).keys()
-
-    def get(self, key: str, default: Any = None):
-        return getattr(self, key, default)
-
-    def keys(self):
-        return asdict(self).keys()
-
-    def values(self):
-        return asdict(self).values()
-
-    def items(self):
-        return asdict(self).items()
-
-    def copy(self: T) -> T:
-        return deepcopy(self)
-
-    @abc.abstractmethod
-    def is_text(self) -> bool:
-        raise NotImplementedError
-
-
-class Message(List[TMS], abc.ABC):
-    """消息数组"""
-
-    def __init__(
-        self: TM,
-        message: Union[str, None, Mapping, Iterable[Mapping], TMS, TM, Any] = None,
-        *args,
-        **kwargs,
-    ):
-        """
-        :参数:
-
-          * ``message: Union[str, list, dict, MessageSegment, Message, Any]``: 消息内容
-        """
-        super().__init__(*args, **kwargs)
-        if message is None:
-            return
-        elif isinstance(message, Message):
-            self.extend(message)
-        elif isinstance(message, MessageSegment):
-            self.append(message)
-        else:
-            self.extend(self._construct(message))
-
-    @classmethod
-    def template(cls: Type[TM], format_string: Union[str, TM]) -> MessageTemplate[TM]:
-        """
-        :说明:
-
-          根据创建消息模板, 用法和 ``str.format`` 大致相同, 但是可以输出消息对象, 并且支持以 ``Message`` 对象作为消息模板
-          并且提供了拓展的格式化控制符, 可以用适用于该消息类型的 ``MessageSegment`` 的工厂方法创建消息
-
-        :示例:
-
-        .. code-block:: python
-
-            >>> Message.template("{} {}").format("hello", "world") # 基础演示
-            Message(MessageSegment(type='text', data={'text': 'hello world'}))
-            >>> Message.template("{} {}").format(MessageSegment.image("file///..."), "world") # 支持消息段等对象
-            Message(MessageSegment(type='image', data={'file': 'file///...'}), MessageSegment(type='text', data={'text': 'world'}))
-            >>> Message.template( # 支持以Message对象作为消息模板
-            ...       MessageSegment.text('test {event.user_id}') + MessageSegment.face(233) +
-            ...       MessageSegment.text('test {event.message}')).format(event={'user_id':123456, 'message':'hello world'})
-            Message(MessageSegment(type='text', data={'text': 'test 123456'}),
-                    MessageSegment(type='face', data={'face': 233}),
-                    MessageSegment(type='text', data={'text': 'test hello world'}))
-            >>> Message.template("{link:image}").format(link='https://...') # 支持拓展格式化控制符
-            Message(MessageSegment(type='image', data={'file': 'https://...'}))
-
-        :参数:
-
-          * ``format_string: str``: 格式化字符串
-
-        :返回:
-
-          - ``MessageFormatter[TM]``: 消息格式化器
-        """
-        return MessageTemplate(format_string, cls)
-
-    @classmethod
-    @abc.abstractmethod
-    def get_segment_class(cls) -> Type[TMS]:
-        raise NotImplementedError
-
-    def __str__(self):
-        return "".join(str(seg) for seg in self)
-
-    @classmethod
-    def __get_validators__(cls):
-        yield cls._validate
-
-    @classmethod
-    def _validate(cls, value):
-        return cls(value)
-
-    @staticmethod
-    @abc.abstractmethod
-    def _construct(msg: Union[str, Mapping, Iterable[Mapping], Any]) -> Iterable[TMS]:
-        raise NotImplementedError
-
-    def __add__(self: TM, other: Union[str, Mapping, Iterable[Mapping]]) -> TM:
-        result = self.copy()
-        result += other
-        return result
-
-    def __radd__(self: TM, other: Union[str, Mapping, Iterable[Mapping]]) -> TM:
-        result = self.__class__(other)  # type: ignore
-        return result + self
-
-    def __iadd__(self: TM, other: Union[str, Mapping, Iterable[Mapping]]) -> TM:
-        if isinstance(other, MessageSegment):
-            self.append(other)
-        elif isinstance(other, Message):
-            self.extend(other)
-        else:
-            self.extend(self._construct(other))
-        return self
-
-    def append(self: TM, obj: Union[str, TMS]) -> TM:
-        """
-        :说明:
-
-          添加一个消息段到消息数组末尾
-
-        :参数:
-
-          * ``obj: Union[str, MessageSegment]``: 要添加的消息段
-        """
-        if isinstance(obj, MessageSegment):
-            super(Message, self).append(obj)
-        elif isinstance(obj, str):
-            self.extend(self._construct(obj))
-        else:
-            raise ValueError(f"Unexpected type: {type(obj)} {obj}")
-        return self
-
-    def extend(self: TM, obj: Union[TM, Iterable[TMS]]) -> TM:
-        """
-        :说明:
-
-          拼接一个消息数组或多个消息段到消息数组末尾
-
-        :参数:
-
-          * ``obj: Union[Message, Iterable[MessageSegment]]``: 要添加的消息数组
-        """
-        for segment in obj:
-            self.append(segment)
-        return self
-
-    def copy(self: TM) -> TM:
-        return deepcopy(self)
-
-    def extract_plain_text(self: "Message[MessageSegment]") -> str:
-        """
-        :说明:
-
-          提取消息内纯文本消息
-        """
-
-        return "".join(str(seg) for seg in self if seg.is_text())

nonebot/adapters/_template.py

@@ -1,190 +0,0 @@
-import inspect
-import functools
-from string import Formatter
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Set,
-    Dict,
-    List,
-    Type,
-    Tuple,
-    Union,
-    Generic,
-    Mapping,
-    TypeVar,
-    Callable,
-    Optional,
-    Sequence,
-    cast,
-    overload,
-)
-
-if TYPE_CHECKING:
-    from . import Message, MessageSegment
-
-TM = TypeVar("TM", bound="Message")
-TF = TypeVar("TF", str, "Message")
-
-FormatSpecFunc = Callable[[Any], str]
-FormatSpecFunc_T = TypeVar("FormatSpecFunc_T", bound=FormatSpecFunc)
-
-
-class MessageTemplate(Formatter, Generic[TF]):
-    """消息模板格式化实现类"""
-
-    @overload
-    def __init__(
-        self: "MessageTemplate[str]", template: str, factory: Type[str] = str
-    ) -> None:
-        ...
-
-    @overload
-    def __init__(
-        self: "MessageTemplate[TM]", template: Union[str, TM], factory: Type[TM]
-    ) -> None:
-        ...
-
-    def __init__(self, template, factory=str) -> None:
-        """
-        :说明:
-
-          创建一个模板
-
-        :参数:
-
-          * ``template: Union[str, Message]``: 模板
-          * ``factory: Union[str, Message]``: 消息构造类型，默认为 `str`
-        """
-        self.template: TF = template
-        self.factory: Type[TF] = factory
-        self.format_specs: Dict[str, FormatSpecFunc] = {}
-
-    def add_format_spec(
-        self, spec: FormatSpecFunc_T, name: Optional[str] = None
-    ) -> FormatSpecFunc_T:
-        name = name or spec.__name__
-        if name in self.format_specs:
-            raise ValueError(f"Format spec {name} already exists!")
-        self.format_specs[name] = spec
-        return spec
-
-    def format(self, *args: Any, **kwargs: Any) -> TF:
-        """
-        :说明:
-
-          根据模板和参数生成消息对象
-        """
-        msg = self.factory()
-        if isinstance(self.template, str):
-            msg += self.vformat(self.template, args, kwargs)
-        elif isinstance(self.template, self.factory):
-            template = cast("Message[MessageSegment]", self.template)
-            for seg in template:
-                msg += self.vformat(str(seg), args, kwargs) if seg.is_text() else seg
-        else:
-            raise TypeError("template must be a string or instance of Message!")
-
-        return msg  # type:ignore
-
-    def vformat(
-        self, format_string: str, args: Sequence[Any], kwargs: Mapping[str, Any]
-    ) -> TF:
-        used_args = set()
-        result, _ = self._vformat(format_string, args, kwargs, used_args, 2)
-        self.check_unused_args(list(used_args), args, kwargs)
-        return result
-
-    def _vformat(
-        self,
-        format_string: str,
-        args: Sequence[Any],
-        kwargs: Mapping[str, Any],
-        used_args: Set[Union[int, str]],
-        recursion_depth: int,
-        auto_arg_index: int = 0,
-    ) -> Tuple[TF, int]:
-        if recursion_depth < 0:
-            raise ValueError("Max string recursion exceeded")
-
-        results: List[Any] = []
-
-        for (literal_text, field_name, format_spec, conversion) in self.parse(
-            format_string
-        ):
-
-            # output the literal text
-            if literal_text:
-                results.append(literal_text)
-
-            # if there's a field, output it
-            if field_name is not None:
-                # this is some markup, find the object and do
-                #  the formatting
-
-                # handle arg indexing when empty field_names are given.
-                if field_name == "":
-                    if auto_arg_index is False:
-                        raise ValueError(
-                            "cannot switch from manual field specification to "
-                            "automatic field numbering"
-                        )
-                    field_name = str(auto_arg_index)
-                    auto_arg_index += 1
-                elif field_name.isdigit():
-                    if auto_arg_index:
-                        raise ValueError(
-                            "cannot switch from manual field specification to "
-                            "automatic field numbering"
-                        )
-                    # disable auto arg incrementing, if it gets
-                    # used later on, then an exception will be raised
-                    auto_arg_index = False
-
-                # given the field_name, find the object it references
-                #  and the argument it came from
-                obj, arg_used = self.get_field(field_name, args, kwargs)
-                used_args.add(arg_used)
-
-                assert format_spec is not None
-
-                # do any conversion on the resulting object
-                obj = self.convert_field(obj, conversion) if conversion else obj
-
-                # expand the format spec, if needed
-                format_control, auto_arg_index = self._vformat(
-                    format_spec,
-                    args,
-                    kwargs,
-                    used_args,
-                    recursion_depth - 1,
-                    auto_arg_index,
-                )
-
-                # format the object and append to the result
-                formatted_text = self.format_field(obj, str(format_control))
-                results.append(formatted_text)
-
-        return (
-            self.factory(functools.reduce(self._add, results or [""])),
-            auto_arg_index,
-        )
-
-    def format_field(self, value: Any, format_spec: str) -> Any:
-        formatter: Optional[FormatSpecFunc] = self.format_specs.get(format_spec)
-        if formatter is None and not issubclass(self.factory, str):
-            segment_class: Type["MessageSegment"] = self.factory.get_segment_class()
-            method = getattr(segment_class, format_spec, None)
-            if inspect.ismethod(method):
-                formatter = getattr(segment_class, format_spec)
-        return (
-            super().format_field(value, format_spec)
-            if formatter is None
-            else formatter(value)
-        )
-
-    def _add(self, a: Any, b: Any) -> Any:
-        try:
-            return a + b
-        except TypeError:
-            return a + str(b)

nonebot/compat.py

@@ -0,0 +1,473 @@
+"""本模块为 Pydantic 版本兼容层模块
+
+为兼容 Pydantic V1 与 V2 版本，定义了一系列兼容函数与类供使用。
+
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 16
+    description: nonebot.compat 模块
+"""
+
+from collections.abc import Generator
+from dataclasses import dataclass, is_dataclass
+from functools import cached_property
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    Any,
+    Callable,
+    Generic,
+    Literal,
+    Optional,
+    Protocol,
+    TypeVar,
+    Union,
+    overload,
+)
+from typing_extensions import Self, get_args, get_origin, is_typeddict
+
+from pydantic import VERSION, BaseModel
+
+from nonebot.typing import origin_is_annotated
+
+T = TypeVar("T")
+
+PYDANTIC_V2 = int(VERSION.split(".", 1)[0]) == 2
+
+if TYPE_CHECKING:
+
+    class _CustomValidationClass(Protocol):
+        @classmethod
+        def __get_validators__(cls) -> Generator[Callable[..., Any], None, None]: ...
+
+    CVC = TypeVar("CVC", bound=_CustomValidationClass)
+
+
+__all__ = (
+    "DEFAULT_CONFIG",
+    "PYDANTIC_V2",
+    "ConfigDict",
+    "FieldInfo",
+    "ModelField",
+    "PydanticUndefined",
+    "PydanticUndefinedType",
+    "Required",
+    "TypeAdapter",
+    "custom_validation",
+    "extract_field_info",
+    "field_validator",
+    "model_config",
+    "model_dump",
+    "model_fields",
+    "model_validator",
+    "type_validate_json",
+    "type_validate_python",
+)
+
+__autodoc__ = {
+    "PydanticUndefined": "Pydantic Undefined object",
+    "PydanticUndefinedType": "Pydantic Undefined type",
+}
+
+
+if PYDANTIC_V2:  # pragma: pydantic-v2
+    from pydantic import GetCoreSchemaHandler
+    from pydantic import TypeAdapter as TypeAdapter
+    from pydantic import field_validator as field_validator
+    from pydantic import model_validator as model_validator
+    from pydantic._internal._repr import display_as_type
+    from pydantic.fields import FieldInfo as BaseFieldInfo
+    from pydantic_core import CoreSchema, core_schema
+
+    Required = Ellipsis
+    """Alias of Ellipsis for compatibility with pydantic v1"""
+
+    # Export undefined type
+    from pydantic_core import PydanticUndefined as PydanticUndefined
+    from pydantic_core import PydanticUndefinedType as PydanticUndefinedType
+
+    # isort: split
+
+    # Export model config dict
+    from pydantic import ConfigDict as ConfigDict
+
+    DEFAULT_CONFIG = ConfigDict(extra="allow", arbitrary_types_allowed=True)
+    """Default config for validations"""
+
+    class FieldInfo(BaseFieldInfo):
+        """FieldInfo class with extra property for compatibility with pydantic v1"""
+
+        # make default can be positional argument
+        def __init__(self, default: Any = PydanticUndefined, **kwargs: Any) -> None:
+            super().__init__(default=default, **kwargs)
+
+        @property
+        def extra(self) -> dict[str, Any]:
+            """Extra data that is not part of the standard pydantic fields.
+
+            For compatibility with pydantic v1.
+            """
+            # extract extra data from attributes set except used slots
+            # we need to call super in advance due to
+            # comprehension not inlined in cpython < 3.12
+            # https://peps.python.org/pep-0709/
+            slots = super().__slots__
+            return {k: v for k, v in self._attributes_set.items() if k not in slots}
+
+    @dataclass
+    class ModelField:
+        """ModelField class for compatibility with pydantic v1"""
+
+        name: str
+        """The name of the field."""
+        annotation: Any
+        """The annotation of the field."""
+        field_info: FieldInfo
+        """The FieldInfo of the field."""
+
+        @classmethod
+        def _construct(cls, name: str, annotation: Any, field_info: FieldInfo) -> Self:
+            return cls(name, annotation, field_info)
+
+        @classmethod
+        def construct(
+            cls, name: str, annotation: Any, field_info: Optional[FieldInfo] = None
+        ) -> Self:
+            """Construct a ModelField from given infos."""
+            return cls._construct(name, annotation, field_info or FieldInfo())
+
+        def __hash__(self) -> int:
+            # Each ModelField is unique for our purposes,
+            # to allow store them in a set.
+            return id(self)
+
+        @cached_property
+        def type_adapter(self) -> TypeAdapter:
+            """TypeAdapter of the field.
+
+            Cache the TypeAdapter to avoid creating it multiple times.
+            Pydantic v2 uses too much cpu time to create TypeAdapter.
+
+            See: https://github.com/pydantic/pydantic/issues/9834
+            """
+            return TypeAdapter(
+                Annotated[self.annotation, self.field_info],
+                config=None if self._annotation_has_config() else DEFAULT_CONFIG,
+            )
+
+        def _annotation_has_config(self) -> bool:
+            """Check if the annotation has config.
+
+            TypeAdapter raise error when annotation has config
+            and given config is not None.
+            """
+            type_is_annotated = origin_is_annotated(get_origin(self.annotation))
+            inner_type = (
+                get_args(self.annotation)[0] if type_is_annotated else self.annotation
+            )
+            try:
+                return (
+                    issubclass(inner_type, BaseModel)
+                    or is_dataclass(inner_type)
+                    or is_typeddict(inner_type)
+                )
+            except TypeError:
+                return False
+
+        def get_default(self) -> Any:
+            """Get the default value of the field."""
+            return self.field_info.get_default(call_default_factory=True)
+
+        def _type_display(self):
+            """Get the display of the type of the field."""
+            return display_as_type(self.annotation)
+
+        def validate_value(self, value: Any) -> Any:
+            """Validate the value pass to the field."""
+            return self.type_adapter.validate_python(value)
+
+    def extract_field_info(field_info: BaseFieldInfo) -> dict[str, Any]:
+        """Get FieldInfo init kwargs from a FieldInfo instance."""
+
+        kwargs = field_info._attributes_set.copy()
+        kwargs["annotation"] = field_info.rebuild_annotation()
+        return kwargs
+
+    def model_fields(model: type[BaseModel]) -> list[ModelField]:
+        """Get field list of a model."""
+
+        return [
+            ModelField._construct(
+                name=name,
+                annotation=field_info.rebuild_annotation(),
+                field_info=FieldInfo(**extract_field_info(field_info)),
+            )
+            for name, field_info in model.model_fields.items()
+        ]
+
+    def model_config(model: type[BaseModel]) -> Any:
+        """Get config of a model."""
+        return model.model_config
+
+    def model_dump(
+        model: BaseModel,
+        include: Optional[set[str]] = None,
+        exclude: Optional[set[str]] = None,
+        by_alias: bool = False,
+        exclude_unset: bool = False,
+        exclude_defaults: bool = False,
+        exclude_none: bool = False,
+    ) -> dict[str, Any]:
+        return model.model_dump(
+            include=include,
+            exclude=exclude,
+            by_alias=by_alias,
+            exclude_unset=exclude_unset,
+            exclude_defaults=exclude_defaults,
+            exclude_none=exclude_none,
+        )
+
+    def type_validate_python(type_: type[T], data: Any) -> T:
+        """Validate data with given type."""
+        return TypeAdapter(type_).validate_python(data)
+
+    def type_validate_json(type_: type[T], data: Union[str, bytes]) -> T:
+        """Validate JSON with given type."""
+        return TypeAdapter(type_).validate_json(data)
+
+    def __get_pydantic_core_schema__(
+        cls: type["_CustomValidationClass"],
+        source_type: Any,
+        handler: GetCoreSchemaHandler,
+    ) -> CoreSchema:
+        validators = list(cls.__get_validators__())
+        if len(validators) == 1:
+            return core_schema.no_info_plain_validator_function(validators[0])
+        return core_schema.chain_schema(
+            [core_schema.no_info_plain_validator_function(func) for func in validators]
+        )
+
+    def custom_validation(class_: type["CVC"]) -> type["CVC"]:
+        """Use pydantic v1 like validator generator in pydantic v2"""
+
+        setattr(
+            class_,
+            "__get_pydantic_core_schema__",
+            classmethod(__get_pydantic_core_schema__),
+        )
+        return class_
+
+else:  # pragma: pydantic-v1
+    from pydantic import BaseConfig as PydanticConfig
+    from pydantic import Extra, parse_obj_as, parse_raw_as, root_validator, validator
+    from pydantic.fields import FieldInfo as BaseFieldInfo
+    from pydantic.fields import ModelField as BaseModelField
+    from pydantic.schema import get_annotation_from_field_info
+
+    # isort: split
+
+    from pydantic.fields import Required as Required
+
+    # isort: split
+
+    from pydantic.fields import Undefined as PydanticUndefined
+    from pydantic.fields import UndefinedType as PydanticUndefinedType
+
+    class ConfigDict(PydanticConfig):
+        """Config class that allow get value with default value."""
+
+        @classmethod
+        def get(cls, field: str, default: Any = None) -> Any:
+            """Get a config value."""
+            return getattr(cls, field, default)
+
+    class DEFAULT_CONFIG(ConfigDict):
+        extra = Extra.allow
+        arbitrary_types_allowed = True
+
+    class FieldInfo(BaseFieldInfo):
+        def __init__(self, default: Any = PydanticUndefined, **kwargs: Any):
+            # preprocess default value to make it compatible with pydantic v2
+            # when default is Required, set it to PydanticUndefined
+            if default is Required:
+                default = PydanticUndefined
+            super().__init__(default, **kwargs)
+
+    class ModelField(BaseModelField):
+        @classmethod
+        def _construct(cls, name: str, annotation: Any, field_info: FieldInfo) -> Self:
+            return cls(
+                name=name,
+                type_=annotation,
+                class_validators=None,
+                model_config=DEFAULT_CONFIG,
+                default=field_info.default,
+                default_factory=field_info.default_factory,
+                required=(
+                    field_info.default is PydanticUndefined
+                    and field_info.default_factory is None
+                ),
+                field_info=field_info,
+            )
+
+        @classmethod
+        def construct(
+            cls, name: str, annotation: Any, field_info: Optional[FieldInfo] = None
+        ) -> Self:
+            """Construct a ModelField from given infos.
+
+            Field annotation is preprocessed with field_info.
+            """
+            if field_info is not None:
+                annotation = get_annotation_from_field_info(
+                    annotation, field_info, name
+                )
+            return cls._construct(name, annotation, field_info or FieldInfo())
+
+        def validate_value(self, value: Any) -> Any:
+            """Validate the value pass to the field."""
+            v, errs_ = self.validate(value, {}, loc=())
+            if errs_:
+                raise ValueError(value, self)
+            return v
+
+    class TypeAdapter(Generic[T]):
+        @overload
+        def __init__(
+            self,
+            type: type[T],
+            *,
+            config: Optional[ConfigDict] = ...,
+        ) -> None: ...
+
+        @overload
+        def __init__(
+            self,
+            type: Any,
+            *,
+            config: Optional[ConfigDict] = ...,
+        ) -> None: ...
+
+        def __init__(
+            self,
+            type: Any,
+            *,
+            config: Optional[ConfigDict] = None,
+        ) -> None:
+            self.type = type
+            self.config = config
+
+        def validate_python(self, value: Any) -> T:
+            return type_validate_python(self.type, value)
+
+        def validate_json(self, value: Union[str, bytes]) -> T:
+            return type_validate_json(self.type, value)
+
+    def extract_field_info(field_info: BaseFieldInfo) -> dict[str, Any]:
+        """Get FieldInfo init kwargs from a FieldInfo instance."""
+
+        kwargs = {
+            s: getattr(field_info, s) for s in field_info.__slots__ if s != "extra"
+        }
+        kwargs.update(field_info.extra)
+        return kwargs
+
+    @overload
+    def field_validator(
+        field: str,
+        /,
+        *fields: str,
+        mode: Literal["before"],
+        check_fields: Optional[bool] = None,
+    ): ...
+
+    @overload
+    def field_validator(
+        field: str,
+        /,
+        *fields: str,
+        mode: Literal["after"] = ...,
+        check_fields: Optional[bool] = None,
+    ): ...
+
+    def field_validator(
+        field: str,
+        /,
+        *fields: str,
+        mode: Literal["before", "after"] = "after",
+        check_fields: Optional[bool] = None,
+    ):
+        if mode == "before":
+            return validator(
+                field,
+                *fields,
+                pre=True,
+                check_fields=check_fields or True,
+                allow_reuse=True,
+            )
+        else:
+            return validator(
+                field, *fields, check_fields=check_fields or True, allow_reuse=True
+            )
+
+    def model_fields(model: type[BaseModel]) -> list[ModelField]:
+        """Get field list of a model."""
+
+        # construct the model field without preprocess to avoid error
+        return [
+            ModelField._construct(
+                name=model_field.name,
+                annotation=model_field.annotation,
+                field_info=FieldInfo(
+                    **extract_field_info(model_field.field_info),
+                ),
+            )
+            for model_field in model.__fields__.values()
+        ]
+
+    def model_config(model: type[BaseModel]) -> Any:
+        """Get config of a model."""
+        return model.__config__
+
+    def model_dump(
+        model: BaseModel,
+        include: Optional[set[str]] = None,
+        exclude: Optional[set[str]] = None,
+        by_alias: bool = False,
+        exclude_unset: bool = False,
+        exclude_defaults: bool = False,
+        exclude_none: bool = False,
+    ) -> dict[str, Any]:
+        return model.dict(
+            include=include,
+            exclude=exclude,
+            by_alias=by_alias,
+            exclude_unset=exclude_unset,
+            exclude_defaults=exclude_defaults,
+            exclude_none=exclude_none,
+        )
+
+    @overload
+    def model_validator(*, mode: Literal["before"]): ...
+
+    @overload
+    def model_validator(*, mode: Literal["after"]): ...
+
+    def model_validator(*, mode: Literal["before", "after"]):
+        if mode == "before":
+            return root_validator(pre=True, allow_reuse=True)
+        else:
+            return root_validator(skip_on_failure=True, allow_reuse=True)
+
+    def type_validate_python(type_: type[T], data: Any) -> T:
+        """Validate data with given type."""
+        return parse_obj_as(type_, data)
+
+    def type_validate_json(type_: type[T], data: Union[str, bytes]) -> T:
+        """Validate JSON with given type."""
+        return parse_raw_as(type_, data)
+
+    def custom_validation(class_: type["CVC"]) -> type["CVC"]:
+        """Do nothing in pydantic v1"""
+        return class_

nonebot/config.py

@@ -1,287 +1,460 @@
+"""本模块定义了 NoneBot 本身运行所需的配置项。
+
+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/) 文档。
+
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 1
+    description: nonebot.config 模块
 """
-配置
-====
 
-NoneBot 使用 `pydantic`_ 以及 `python-dotenv`_ 来读取配置。
-
-配置项需符合特殊格式或 json 序列化格式。详情见 `pydantic Field Type`_ 文档。
-
-.. _pydantic:
-    https://pydantic-docs.helpmanual.io/
-.. _python-dotenv:
-    https://saurabh-kumar.com/python-dotenv/
-.. _pydantic Field Type:
-    https://pydantic-docs.helpmanual.io/usage/types/
-"""
-import os
-from pathlib import Path
+import abc
+from collections.abc import Mapping
 from datetime import timedelta
 from ipaddress import IPv4Address
-from typing import Any, Set, Dict, Tuple, Union, Mapping, Optional
+import json
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Optional, Union
+from typing_extensions import TypeAlias, get_args, get_origin
 
-from pydantic import BaseSettings, IPvAnyAddress
-from pydantic.env_settings import (
-    SettingsError,
-    EnvSettingsSource,
-    InitSettingsSource,
-    SettingsSourceCallable,
-    read_env_file,
-    env_file_sentinel,
+from dotenv import dotenv_values
+from pydantic import BaseModel, Field
+from pydantic.networks import IPvAnyAddress
+
+from nonebot.compat import (
+    PYDANTIC_V2,
+    ConfigDict,
+    ModelField,
+    PydanticUndefined,
+    PydanticUndefinedType,
+    model_config,
+    model_fields,
 )
-
 from nonebot.log import logger
-from nonebot.utils import escape_tag
+from nonebot.typing import origin_is_union
+from nonebot.utils import deep_update, lenient_issubclass, type_is_complex
+
+DOTENV_TYPE: TypeAlias = Union[
+    Path, str, list[Union[Path, str]], tuple[Union[Path, str], ...]
+]
+
+ENV_FILE_SENTINEL = Path("")
 
 
-class CustomEnvSettings(EnvSettingsSource):
-    def __call__(self, settings: BaseSettings) -> Dict[str, Any]:
-        """
-        Build environment variables suitable for passing to the Model.
-        """
-        d: Dict[str, Optional[str]] = {}
+class SettingsError(ValueError): ...
 
-        if settings.__config__.case_sensitive:
-            env_vars: Mapping[str, Optional[str]] = os.environ  # pragma: no cover
-        else:
-            env_vars = {k.lower(): v for k, v in os.environ.items()}
 
-        env_file_vars: Dict[str, Optional[str]] = {}
-        env_file = (
-            self.env_file
-            if self.env_file != env_file_sentinel
-            else settings.__config__.env_file
+class BaseSettingsSource(abc.ABC):
+    def __init__(self, settings_cls: type["BaseSettings"]) -> None:
+        self.settings_cls = settings_cls
+
+    @property
+    def config(self) -> "SettingsConfig":
+        return model_config(self.settings_cls)
+
+    @abc.abstractmethod
+    def __call__(self) -> dict[str, Any]:
+        raise NotImplementedError
+
+
+class InitSettingsSource(BaseSettingsSource):
+    __slots__ = ("init_kwargs",)
+
+    def __init__(
+        self, settings_cls: type["BaseSettings"], init_kwargs: dict[str, Any]
+    ) -> None:
+        self.init_kwargs = init_kwargs
+        super().__init__(settings_cls)
+
+    def __call__(self) -> dict[str, Any]:
+        return self.init_kwargs
+
+    def __repr__(self) -> str:
+        return f"InitSettingsSource(init_kwargs={self.init_kwargs!r})"
+
+
+class DotEnvSettingsSource(BaseSettingsSource):
+    def __init__(
+        self,
+        settings_cls: type["BaseSettings"],
+        env_file: Optional[DOTENV_TYPE] = ENV_FILE_SENTINEL,
+        env_file_encoding: Optional[str] = None,
+        case_sensitive: Optional[bool] = None,
+        env_nested_delimiter: Optional[str] = None,
+    ) -> None:
+        super().__init__(settings_cls)
+        self.env_file = (
+            env_file
+            if env_file is not ENV_FILE_SENTINEL
+            else self.config.get("env_file", (".env",))
         )
-        env_file_encoding = (
-            self.env_file_encoding
-            if self.env_file_encoding is not None
-            else settings.__config__.env_file_encoding
+        self.env_file_encoding = (
+            env_file_encoding
+            if env_file_encoding is not None
+            else self.config.get("env_file_encoding", "utf-8")
         )
-        if env_file is not None:
-            env_path = Path(env_file)
+        self.case_sensitive = (
+            case_sensitive
+            if case_sensitive is not None
+            else self.config.get("case_sensitive", False)
+        )
+        self.env_nested_delimiter = (
+            env_nested_delimiter
+            if env_nested_delimiter is not None
+            else self.config.get("env_nested_delimiter", None)
+        )
+
+    def _apply_case_sensitive(self, var_name: str) -> str:
+        return var_name if self.case_sensitive else var_name.lower()
+
+    def _field_is_complex(self, field: ModelField) -> tuple[bool, bool]:
+        if type_is_complex(field.annotation):
+            return True, False
+        elif origin_is_union(get_origin(field.annotation)) and any(
+            type_is_complex(arg) for arg in get_args(field.annotation)
+        ):
+            return True, True
+        return False, False
+
+    def _parse_env_vars(
+        self, env_vars: Mapping[str, Optional[str]]
+    ) -> dict[str, Optional[str]]:
+        return {
+            self._apply_case_sensitive(key): value for key, value in env_vars.items()
+        }
+
+    def _read_env_file(self, file_path: Path) -> dict[str, Optional[str]]:
+        file_vars = dotenv_values(file_path, encoding=self.env_file_encoding)
+        return self._parse_env_vars(file_vars)
+
+    def _read_env_files(self) -> dict[str, Optional[str]]:
+        env_files = self.env_file
+        if env_files is None:
+            return {}
+
+        if isinstance(env_files, (str, os.PathLike)):
+            env_files = [env_files]
+
+        dotenv_vars: dict[str, Optional[str]] = {}
+        for env_file in env_files:
+            env_path = Path(env_file).expanduser()
             if env_path.is_file():
-                env_file_vars = read_env_file(
-                    env_path,
-                    encoding=env_file_encoding,
-                    case_sensitive=settings.__config__.case_sensitive,
-                )
-                env_vars = {**env_file_vars, **env_vars}
+                dotenv_vars.update(self._read_env_file(env_path))
+        return dotenv_vars
 
-        for field in settings.__fields__.values():
-            env_val: Optional[str] = None
-            for env_name in field.field_info.extra["env_names"]:
-                env_val = env_vars.get(env_name)
-                if env_name in env_file_vars:
-                    del env_file_vars[env_name]
-                if env_val is not None:
-                    break
+    def _next_field(
+        self, field: Optional[ModelField], key: str
+    ) -> Optional[ModelField]:
+        if not field or origin_is_union(get_origin(field.annotation)):
+            return None
+        elif field.annotation and lenient_issubclass(field.annotation, BaseModel):
+            for field in model_fields(field.annotation):
+                if field.name == key:
+                    return field
+        return None
 
-            if env_val is None:
+    def _explode_env_vars(
+        self,
+        field: ModelField,
+        env_vars: dict[str, Optional[str]],
+        env_file_vars: dict[str, Optional[str]],
+    ) -> dict[str, Any]:
+        if self.env_nested_delimiter is None:
+            return {}
+
+        prefix = f"{field.name}{self.env_nested_delimiter}"
+        result: dict[str, Any] = {}
+        for env_name, env_val in env_vars.items():
+            if not env_name.startswith(prefix):
                 continue
 
-            if field.is_complex():
-                try:
-                    env_val = settings.__config__.json_loads(env_val)
-                except ValueError as e:  # pragma: no cover
-                    raise SettingsError(
-                        f'error parsing JSON for "{env_name}"'  # type: ignore
-                    ) from e
-            d[field.alias] = env_val
+            # delete from file vars when used
+            env_file_vars.pop(env_name, None)
 
-        if env_file_vars:
-            for env_name, env_val in env_file_vars.items():
-                if (env_val is None or len(env_val) == 0) and env_name in env_vars:
-                    env_val = env_vars[env_name]
+            _, *keys, last_key = env_name.split(self.env_nested_delimiter)
+            env_var = result
+            target_field: Optional[ModelField] = field
+            for key in keys:
+                target_field = self._next_field(target_field, key)
+                env_var = env_var.setdefault(key, {})
+
+            target_field = self._next_field(target_field, last_key)
+            if target_field and env_val:
+                is_complex, allow_parse_failure = self._field_is_complex(target_field)
+                if is_complex:
+                    try:
+                        env_val = json.loads(env_val)
+                    except ValueError as e:
+                        if not allow_parse_failure:
+                            raise SettingsError(
+                                f'error parsing env var "{env_name}"'
+                            ) from e
+
+            env_var[last_key] = env_val
+
+        return result
+
+    def __call__(self) -> dict[str, Any]:
+        """从环境变量和 dotenv 配置文件中读取配置项。"""
+
+        d: dict[str, Any] = {}
+
+        env_vars = self._parse_env_vars(os.environ)
+        env_file_vars = self._read_env_files()
+        env_vars = {**env_file_vars, **env_vars}
+
+        for field in model_fields(self.settings_cls):
+            field_name = field.name
+            env_name = self._apply_case_sensitive(field_name)
+
+            # try get values from env vars
+            env_val = env_vars.get(env_name, PydanticUndefined)
+            # delete from file vars when used
+            if env_name in env_file_vars:
+                del env_file_vars[env_name]
+
+            is_complex, allow_parse_failure = self._field_is_complex(field)
+            if is_complex:
+                if isinstance(env_val, PydanticUndefinedType):
+                    # field is complex but no value found so far, try explode_env_vars
+                    if env_val_built := self._explode_env_vars(
+                        field, env_vars, env_file_vars
+                    ):
+                        d[field_name] = env_val_built
+                elif env_val is None:
+                    d[field_name] = env_val
+                else:
+                    # field is complex and there's a value
+                    # decode that as JSON, then add explode_env_vars
+                    try:
+                        env_val = json.loads(env_val)
+                    except ValueError as e:
+                        if not allow_parse_failure:
+                            raise SettingsError(
+                                f'error parsing env var "{env_name}"'
+                            ) from e
+
+                    if isinstance(env_val, dict):
+                        # field value is a dict
+                        # try explode_env_vars to find more sub-values
+                        d[field_name] = deep_update(
+                            env_val,
+                            self._explode_env_vars(field, env_vars, env_file_vars),
+                        )
+                    else:
+                        d[field_name] = env_val
+            elif env_val is not PydanticUndefined:
+                # simplest case, field is not complex
+                # we only need to add the value if it was found
+                d[field_name] = env_val
+
+        # remain user custom config
+        for env_name in env_file_vars:
+            env_val = env_vars[env_name]
+            if env_val and (val_striped := env_val.strip()):
+                # there's a value, decode that as JSON
                 try:
-                    if env_val:
-                        env_val = settings.__config__.json_loads(env_val.strip())
-                except ValueError as e:
-                    logger.opt(colors=True, exception=e).trace(
-                        f"Error while parsing JSON for {escape_tag(env_name)}. Assumed as string."
+                    env_val = json.loads(val_striped)
+                except ValueError:
+                    logger.trace(
+                        "Error while parsing JSON for "
+                        f"{env_name!r}={val_striped!r}. "
+                        "Assumed as string."
                     )
 
+            # explode value when it's a nested dict
+            env_name, *nested_keys = env_name.split(self.env_nested_delimiter)
+            if nested_keys and (env_name not in d or isinstance(d[env_name], dict)):
+                result = {}
+                *keys, last_key = nested_keys
+                _tmp = result
+                for key in keys:
+                    _tmp = _tmp.setdefault(key, {})
+                _tmp[last_key] = env_val
+                d[env_name] = deep_update(d.get(env_name, {}), result)
+            elif not nested_keys:
                 d[env_name] = env_val
 
         return d
 
 
-class BaseConfig(BaseSettings):
-    # dummy getattr for pylance checking, actually not used
-    def __getattr__(self, name: str) -> Any:  # pragma: no cover
-        return self.__dict__.get(name)
+if PYDANTIC_V2:  # pragma: pydantic-v2
 
-    class Config:
-        @classmethod
-        def customise_sources(
-            cls,
-            init_settings: InitSettingsSource,
-            env_settings: EnvSettingsSource,
-            file_secret_settings: SettingsSourceCallable,
-        ) -> Tuple[SettingsSourceCallable, ...]:
-            common_config = init_settings.init_kwargs.pop("_common_config", {})
-            return (
-                init_settings,
-                CustomEnvSettings(
-                    env_settings.env_file, env_settings.env_file_encoding
-                ),
-                InitSettingsSource(common_config),
-                file_secret_settings,
+    class SettingsConfig(ConfigDict, total=False):
+        env_file: Optional[DOTENV_TYPE]
+        env_file_encoding: str
+        case_sensitive: bool
+        env_nested_delimiter: Optional[str]
+
+else:  # pragma: pydantic-v1
+
+    class SettingsConfig(ConfigDict):
+        env_file: Optional[DOTENV_TYPE]
+        env_file_encoding: str
+        case_sensitive: bool
+        env_nested_delimiter: Optional[str]
+
+
+class BaseSettings(BaseModel):
+    if TYPE_CHECKING:
+        # dummy getattr for pylance checking, actually not used
+        def __getattr__(self, name: str) -> Any:  # pragma: no cover
+            return self.__dict__.get(name)
+
+    if PYDANTIC_V2:  # pragma: pydantic-v2
+        model_config = SettingsConfig(
+            extra="allow",
+            env_file=".env",
+            env_file_encoding="utf-8",
+            case_sensitive=False,
+            env_nested_delimiter="__",
+        )
+    else:  # pragma: pydantic-v1
+
+        class Config(SettingsConfig):
+            extra = "allow"  # type: ignore
+            env_file = ".env"
+            env_file_encoding = "utf-8"
+            case_sensitive = False
+            env_nested_delimiter = "__"
+
+    def __init__(
+        __settings_self__,  # pyright: ignore[reportSelfClsParameterName]
+        _env_file: Optional[DOTENV_TYPE] = ENV_FILE_SENTINEL,
+        _env_file_encoding: Optional[str] = None,
+        _env_nested_delimiter: Optional[str] = None,
+        **values: Any,
+    ) -> None:
+        super().__init__(
+            **__settings_self__._settings_build_values(
+                values,
+                env_file=_env_file,
+                env_file_encoding=_env_file_encoding,
+                env_nested_delimiter=_env_nested_delimiter,
             )
+        )
+
+    def _settings_build_values(
+        self,
+        init_kwargs: dict[str, Any],
+        env_file: Optional[DOTENV_TYPE] = None,
+        env_file_encoding: Optional[str] = None,
+        env_nested_delimiter: Optional[str] = None,
+    ) -> dict[str, Any]:
+        init_settings = InitSettingsSource(self.__class__, init_kwargs=init_kwargs)
+        env_settings = DotEnvSettingsSource(
+            self.__class__,
+            env_file=env_file,
+            env_file_encoding=env_file_encoding,
+            env_nested_delimiter=env_nested_delimiter,
+        )
+        return deep_update(env_settings(), init_settings())
 
 
-class Env(BaseConfig):
-    """
-    运行环境配置。大小写不敏感。
+class Env(BaseSettings):
+    """运行环境配置。大小写不敏感。
 
-    将会从 ``nonebot.init 参数`` > ``环境变量`` > ``.env 环境配置文件`` 的优先级读取配置。
+    将会从 **环境变量** > **dotenv 配置文件** 的优先级读取环境信息。
     """
 
     environment: str = "prod"
-    """
-    - **类型**: ``str``
-    - **默认值**: ``"prod"``
+    """当前环境名。
 
-    :说明:
-      当前环境名。 NoneBot 将从 ``.env.{environment}`` 文件中加载配置。
+    NoneBot 将从 `.env.{environment}` 文件中加载配置。
     """
 
-    class Config:
-        extra = "allow"
-        env_file = ".env"
 
+class Config(BaseSettings):
+    """NoneBot 主要配置。大小写不敏感。
 
-class Config(BaseConfig):
-    """
-    NoneBot 主要配置。大小写不敏感。
+    除了 NoneBot 的配置项外，还可以自行添加配置项到 `.env.{environment}` 文件中。
+    这些配置将会在 json 反序列化后一起带入 `Config` 类中。
 
-    除了 NoneBot 的配置项外，还可以自行添加配置项到 ``.env.{environment}`` 文件中。
-    这些配置将会在 json 反序列化后一起带入 ``Config`` 类中。
+    配置方法参考: [配置](https://nonebot.dev/docs/appendices/config)
     """
 
-    _common_config: dict
-    _env_file: str
+    if TYPE_CHECKING:
+        _env_file: Optional[DOTENV_TYPE] = ".env", ".env.prod"
 
     # nonebot configs
     driver: str = "~fastapi"
-    """
-    - **类型**: ``str``
-    - **默认值**: ``"~fastapi"``
+    """NoneBot 运行所使用的 `Driver` 。继承自 {ref}`nonebot.drivers.Driver` 。
 
-    :说明:
+    配置格式为 `<module>[:<Driver>][+<module>[:<Mixin>]]*`。
 
-      NoneBot 运行所使用的 ``Driver`` 。继承自 ``nonebot.drivers.Driver`` 。
+    `~` 为 `nonebot.drivers.` 的缩写。
 
-      配置格式为 ``<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
-    """
-    - **类型**: ``IPvAnyAddress``
-    - **默认值**: ``127.0.0.1``
-
-    :说明:
-
-      NoneBot 的 HTTP 和 WebSocket 服务端监听的 IP/主机名。
-    """
-    port: int = 8080
-    """
-    - **类型**: ``int``
-    - **默认值**: ``8080``
-
-    :说明:
-
-      NoneBot 的 HTTP 和 WebSocket 服务端监听的端口。
-    """
+    """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"
-    """
-    - **类型**: ``Union[int, str]``
-    - **默认值**: ``INFO``
+    """NoneBot 日志输出等级，可以为 `int` 类型等级或等级名称。
 
-    :说明:
+    参考 [记录日志](https://nonebot.dev/docs/appendices/log)，[loguru 日志等级](https://loguru.readthedocs.io/en/stable/api/logger.html#levels)。
 
-      配置 NoneBot 日志输出等级，可以为 ``int`` 类型等级或等级名称，参考 `loguru 日志等级`_。
-
-    :示例:
-
-    .. code-block:: default
+    :::tip 提示
+    日志等级名称应为大写，如 `INFO`。
+    :::
 
+    用法:
+        ```conf
         LOG_LEVEL=25
         LOG_LEVEL=INFO
-
-    .. _loguru 日志等级:
-        https://loguru.readthedocs.io/en/stable/api/logger.html#levels
+        ```
     """
 
     # bot connection configs
     api_timeout: Optional[float] = 30.0
-    """
-    - **类型**: ``Optional[float]``
-    - **默认值**: ``30.``
-
-    :说明:
-
-      API 请求超时时间，单位: 秒。
-    """
+    """API 请求超时时间，单位: 秒。"""
 
     # bot runtime configs
-    superusers: Set[str] = set()
-    """
-    - **类型**: ``Set[str]``
-    - **默认值**: ``set()``
-
-    :说明:
-
-      机器人超级用户。
-
-    :示例:
-
-    .. code-block:: default
+    superusers: set[str] = set()
+    """机器人超级用户。
 
+    用法:
+        ```conf
         SUPERUSERS=["12345789"]
+        ```
     """
-    nickname: Set[str] = set()
+    nickname: set[str] = set()
+    """机器人昵称。"""
+    command_start: set[str] = {"/"}
+    """命令的起始标记，用于判断一条消息是不是命令。
+
+    参考[命令响应规则](https://nonebot.dev/docs/advanced/matcher#command)。
+
+    用法:
+        ```conf
+        COMMAND_START=["/", ""]
+        ```
     """
-    - **类型**: ``Set[str]``
-    - **默认值**: ``set()``
+    command_sep: set[str] = {"."}
+    """命令的分隔标记，用于将文本形式的命令切分为元组（实际的命令名）。
 
-    :说明:
+    参考[命令响应规则](https://nonebot.dev/docs/advanced/matcher#command)。
 
-      机器人昵称。
-    """
-    command_start: Set[str] = {"/"}
-    """
-    - **类型**: ``Set[str]``
-    - **默认值**: ``{"/"}``
-
-    :说明:
-
-      命令的起始标记，用于判断一条消息是不是命令。
-    """
-    command_sep: Set[str] = {"."}
-    """
-    - **类型**: ``Set[str]``
-    - **默认值**: ``{"."}``
-
-    :说明:
-
-      命令的分隔标记，用于将文本形式的命令切分为元组（实际的命令名）。
+    用法:
+        ```conf
+        COMMAND_SEP=["."]
+        ```
     """
     session_expire_timeout: timedelta = timedelta(minutes=2)
-    """
-    - **类型**: ``timedelta``
-    - **默认值**: ``timedelta(minutes=2)``
+    """等待用户回复的超时时间。
 
-    :说明:
-
-      等待用户回复的超时时间。
-
-    :示例:
-
-    .. code-block:: default
-
-        SESSION_EXPIRE_TIMEOUT=120  # 单位: 秒
-        SESSION_EXPIRE_TIMEOUT=[DD ][HH:MM]SS[.ffffff]
-        SESSION_EXPIRE_TIMEOUT=P[DD]DT[HH]H[MM]M[SS]S  # ISO 8601
+    用法:
+        ```conf
+        SESSION_EXPIRE_TIMEOUT=[-][DD]D[,][HH:MM:]SS[.ffffff]
+        SESSION_EXPIRE_TIMEOUT=[±]P[DD]DT[HH]H[MM]M[SS]S  # ISO 8601
+        ```
     """
 
     # adapter configs
@@ -291,6 +464,21 @@ class Config(BaseConfig):
     # custom configs can be assigned during nonebot.init
     # or from env file using json loads
 
-    class Config:
-        extra = "allow"
-        env_file = ".env.prod"
+    if PYDANTIC_V2:  # pragma: pydantic-v2
+        model_config = SettingsConfig(env_file=(".env", ".env.prod"))
+    else:  # pragma: pydantic-v1
+
+        class Config(  # pyright: ignore[reportIncompatibleVariableOverride]
+            SettingsConfig
+        ):
+            env_file = ".env", ".env.prod"
+
+
+__autodoc__ = {
+    "SettingsError": False,
+    "BaseSettingsSource": False,
+    "InitSettingsSource": False,
+    "DotEnvSettingsSource": False,
+    "SettingsConfig": False,
+    "BaseSettings": False,
+}

nonebot/consts.py

@@ -1,20 +1,61 @@
+"""本模块包含了 NoneBot 事件处理过程中使用到的常量。
+
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 9
+    description: nonebot.consts 模块
+"""
+
+import os
+import sys
+from typing import Literal
+
 # used by Matcher
-RECEIVE_KEY = "_receive_{id}"
-LAST_RECEIVE_KEY = "_last_receive"
-ARG_KEY = "{key}"
-REJECT_TARGET = "_current_target"
-REJECT_CACHE_TARGET = "_next_target"
+RECEIVE_KEY: Literal["_receive_{id}"] = "_receive_{id}"
+"""`receive` 存储 key"""
+LAST_RECEIVE_KEY: Literal["_last_receive"] = "_last_receive"
+"""`last_receive` 存储 key"""
+ARG_KEY: Literal["{key}"] = "{key}"
+"""`arg` 存储 key"""
+REJECT_TARGET: Literal["_current_target"] = "_current_target"
+"""当前 `reject` 目标存储 key"""
+REJECT_CACHE_TARGET: Literal["_next_target"] = "_next_target"
+"""下一个 `reject` 目标存储 key"""
+PAUSE_PROMPT_RESULT_KEY: Literal["_pause_result"] = "_pause_result"
+"""`pause` prompt 发送结果存储 key"""
+REJECT_PROMPT_RESULT_KEY: Literal["_reject_{key}_result"] = "_reject_{key}_result"
+"""`reject` prompt 发送结果存储 key"""
 
 # used by Rule
-PREFIX_KEY = "_prefix"
+PREFIX_KEY: Literal["_prefix"] = "_prefix"
+"""命令前缀存储 key"""
 
-CMD_KEY = "command"
-RAW_CMD_KEY = "raw_command"
-CMD_ARG_KEY = "command_arg"
+CMD_KEY: Literal["command"] = "command"
+"""命令元组存储 key"""
+RAW_CMD_KEY: Literal["raw_command"] = "raw_command"
+"""命令文本存储 key"""
+CMD_ARG_KEY: Literal["command_arg"] = "command_arg"
+"""命令参数存储 key"""
+CMD_START_KEY: Literal["command_start"] = "command_start"
+"""命令开头存储 key"""
+CMD_WHITESPACE_KEY: Literal["command_whitespace"] = "command_whitespace"
+"""命令与参数间空白符存储 key"""
 
-SHELL_ARGS = "_args"
-SHELL_ARGV = "_argv"
+SHELL_ARGS: Literal["_args"] = "_args"
+"""shell 命令 parse 后参数字典存储 key"""
+SHELL_ARGV: Literal["_argv"] = "_argv"
+"""shell 命令原始参数列表存储 key"""
 
-REGEX_MATCHED = "_matched"
-REGEX_GROUP = "_matched_groups"
-REGEX_DICT = "_matched_dict"
+REGEX_MATCHED: Literal["_matched"] = "_matched"
+"""正则匹配结果存储 key"""
+STARTSWITH_KEY: Literal["_startswith"] = "_startswith"
+"""响应触发前缀 key"""
+ENDSWITH_KEY: Literal["_endswith"] = "_endswith"
+"""响应触发后缀 key"""
+FULLMATCH_KEY: Literal["_fullmatch"] = "_fullmatch"
+"""响应触发完整消息 key"""
+KEYWORD_KEY: Literal["_keyword"] = "_keyword"
+"""响应触发关键字 key"""
+
+WINDOWS = sys.platform.startswith("win") or (sys.platform == "cli" and os.name == "nt")

nonebot/dependencies/__init__.py

@@ -1,194 +1,229 @@
-"""
-依赖注入处理模块
-================
+"""本模块模块实现了依赖注入的定义与处理。
 
-该模块实现了依赖注入的定义与处理。
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 0
+    description: nonebot.dependencies 模块
 """
 
 import abc
+from collections.abc import Awaitable, Iterable
+from dataclasses import dataclass, field
+from functools import partial
 import inspect
-from typing import Any, Dict, List, Type, Generic, TypeVar, Callable, Optional
+from typing import Any, Callable, Generic, Optional, TypeVar, cast
 
-from pydantic import BaseConfig
-from pydantic.schema import get_annotation_from_field_info
-from pydantic.fields import Required, FieldInfo, Undefined, ModelField
+import anyio
+from exceptiongroup import BaseExceptionGroup, catch
 
+from nonebot.compat import FieldInfo, ModelField, PydanticUndefined
+from nonebot.exception import SkippedException
 from nonebot.log import logger
-from .utils import get_typed_signature
-from nonebot.exception import TypeMisMatch
-from nonebot.utils import run_sync, is_coroutine_callable
+from nonebot.typing import _DependentCallable
+from nonebot.utils import (
+    flatten_exception_group,
+    is_coroutine_callable,
+    run_coro_with_shield,
+    run_sync,
+)
+
+from .utils import check_field_type, get_typed_signature
 
-T = TypeVar("T", bound="Dependent")
 R = TypeVar("R")
+T = TypeVar("T", bound="Dependent")
 
 
 class Param(abc.ABC, FieldInfo):
+    """依赖注入的基本单元 —— 参数。
+
+    继承自 `pydantic.fields.FieldInfo`，用于描述参数信息（不包括参数名）。
+    """
+
+    def __init__(self, *args, validate: bool = False, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.validate = validate
+
     @classmethod
     def _check_param(
-        cls, dependent: "Dependent", name: str, param: inspect.Parameter
+        cls, param: inspect.Parameter, allow_types: tuple[type["Param"], ...]
     ) -> Optional["Param"]:
-        return None
+        return
 
     @classmethod
     def _check_parameterless(
-        cls, dependent: "Dependent", value: Any
+        cls, value: Any, allow_types: tuple[type["Param"], ...]
     ) -> Optional["Param"]:
-        return None
+        return
 
     @abc.abstractmethod
     async def _solve(self, **kwargs: Any) -> Any:
         raise NotImplementedError
 
-
-class CustomConfig(BaseConfig):
-    arbitrary_types_allowed = True
+    async def _check(self, **kwargs: Any) -> None:
+        return
 
 
+@dataclass(frozen=True)
 class Dependent(Generic[R]):
-    def __init__(
-        self,
-        *,
-        call: Callable[..., Any],
-        pre_checkers: Optional[List[Param]] = None,
-        params: Optional[List[ModelField]] = None,
-        parameterless: Optional[List[Param]] = None,
-        allow_types: Optional[List[Type[Param]]] = None,
-    ) -> None:
-        self.call = call
-        self.pre_checkers = pre_checkers or []
-        self.params = params or []
-        self.parameterless = parameterless or []
-        self.allow_types = allow_types or []
+    """依赖注入容器
+
+    参数:
+        call: 依赖注入的可调用对象，可以是任何 Callable 对象
+        pre_checkers: 依赖注入解析前的参数检查
+        params: 具名参数列表
+        parameterless: 匿名参数列表
+        allow_types: 允许的参数类型
+    """
+
+    call: _DependentCallable[R]
+    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):
+            call_str = self.call.__name__
+        else:
+            call_str = repr(self.call)
         return (
-            f"<Dependent call={self.call}, params={self.params},"
-            f" parameterless={self.parameterless}>"
+            f"Dependent(call={call_str}"
+            + (f", parameterless={self.parameterless}" if self.parameterless else "")
+            + ")"
         )
 
-    def __str__(self) -> str:
-        return self.__repr__()
-
     async def __call__(self, **kwargs: Any) -> R:
-        values = await self.solve(**kwargs)
+        exception: Optional[BaseExceptionGroup[SkippedException]] = None
 
-        if is_coroutine_callable(self.call):
-            return await self.call(**values)
-        else:
-            return await run_sync(self.call)(**values)
+        def _handle_skipped(exc_group: BaseExceptionGroup[SkippedException]):
+            nonlocal exception
+            exception = exc_group
+            # raise one of the exceptions instead
+            excs = list(flatten_exception_group(exc_group))
+            logger.trace(f"{self} skipped due to {excs}")
 
-    def parse_param(self, name: str, param: inspect.Parameter) -> Param:
-        for allow_type in self.allow_types:
-            field_info = allow_type._check_param(self, name, param)
-            if field_info:
-                return field_info
-        else:
-            raise ValueError(
-                f"Unknown parameter {name} for function {self.call} with type {param.annotation}"
+        with catch({SkippedException: _handle_skipped}):
+            # do pre-check
+            await self.check(**kwargs)
+
+            # solve param values
+            values = await self.solve(**kwargs)
+
+            # call function
+            if is_coroutine_callable(self.call):
+                return await cast(Callable[..., Awaitable[R]], self.call)(**values)
+            else:
+                return await run_sync(cast(Callable[..., R], self.call))(**values)
+
+        raise exception
+
+    @staticmethod
+    def parse_params(
+        call: _DependentCallable[R], allow_types: tuple[type[Param], ...]
+    ) -> tuple[ModelField, ...]:
+        fields: list[ModelField] = []
+        params = get_typed_signature(call).parameters.values()
+
+        for param in params:
+            if isinstance(param.default, Param):
+                field_info = param.default
+            else:
+                for allow_type in allow_types:
+                    if field_info := allow_type._check_param(param, allow_types):
+                        break
+                else:
+                    raise ValueError(
+                        f"Unknown parameter {param.name} "
+                        f"for function {call} with type {param.annotation}"
+                    )
+
+            annotation: Any = Any
+            if param.annotation is not param.empty:
+                annotation = param.annotation
+
+            fields.append(
+                ModelField.construct(
+                    name=param.name, annotation=annotation, field_info=field_info
+                )
             )
 
-    def parse_parameterless(self, value: Any) -> Param:
-        for allow_type in self.allow_types:
-            field_info = allow_type._check_parameterless(self, value)
-            if field_info:
-                return field_info
-        else:
-            raise ValueError(
-                f"Unknown parameterless {value} for function {self.call} with type {type(value)}"
-            )
+        return tuple(fields)
 
-    def prepend_parameterless(self, value: Any) -> None:
-        self.parameterless.insert(0, self.parse_parameterless(value))
-
-    def append_parameterless(self, value: Any) -> None:
-        self.parameterless.append(self.parse_parameterless(value))
+    @staticmethod
+    def parse_parameterless(
+        parameterless: tuple[Any, ...], allow_types: tuple[type[Param], ...]
+    ) -> tuple[Param, ...]:
+        parameterless_params: list[Param] = []
+        for value in parameterless:
+            for allow_type in allow_types:
+                if param := allow_type._check_parameterless(value, allow_types):
+                    break
+            else:
+                raise ValueError(f"Unknown parameterless {value}")
+            parameterless_params.append(param)
+        return tuple(parameterless_params)
 
     @classmethod
     def parse(
-        cls: Type[T],
+        cls,
         *,
-        call: Callable[..., Any],
-        parameterless: Optional[List[Any]] = None,
-        allow_types: Optional[List[Type[Param]]] = None,
-    ) -> T:
-        signature = get_typed_signature(call)
-        params = signature.parameters
-        dependent = cls(
-            call=call,
-            allow_types=allow_types,
+        call: _DependentCallable[R],
+        parameterless: Optional[Iterable[Any]] = None,
+        allow_types: Iterable[type[Param]],
+    ) -> "Dependent[R]":
+        allow_types = tuple(allow_types)
+
+        params = cls.parse_params(call, allow_types)
+        parameterless_params = (
+            ()
+            if parameterless is None
+            else cls.parse_parameterless(tuple(parameterless), allow_types)
         )
 
-        for param_name, param in params.items():
-            default_value = Required
-            if param.default != param.empty:
-                default_value = param.default
+        return cls(call, params, parameterless_params)
 
-            if isinstance(default_value, Param):
-                field_info = default_value
-                default_value = field_info.default
-            else:
-                field_info = dependent.parse_param(param_name, param)
-                default_value = field_info.default
+    async def check(self, **params: Any) -> None:
+        if self.parameterless:
+            async with anyio.create_task_group() as tg:
+                for param in self.parameterless:
+                    tg.start_soon(partial(param._check, **params))
 
-            annotation: Any = Any
-            required = default_value == Required
-            if param.annotation != param.empty:
-                annotation = param.annotation
-            annotation = get_annotation_from_field_info(
-                annotation, field_info, param_name
-            )
-            dependent.params.append(
-                ModelField(
-                    name=param_name,
-                    type_=annotation,
-                    class_validators=None,
-                    model_config=CustomConfig,
-                    default=None if required else default_value,
-                    required=required,
-                    field_info=field_info,
-                )
-            )
+        if self.params:
+            async with anyio.create_task_group() as tg:
+                for param in self.params:
+                    tg.start_soon(
+                        partial(cast(Param, param.field_info)._check, **params)
+                    )
 
-        parameterless_params = [
-            dependent.parse_parameterless(param) for param in (parameterless or [])
-        ]
-        dependent.parameterless.extend(parameterless_params)
-
-        logger.trace(
-            f"Parsed dependent with call={call}, "
-            f"params={[param.field_info for param in dependent.params]}, "
-            f"parameterless={dependent.parameterless}"
-        )
-
-        return dependent
-
-    async def solve(
-        self,
-        **params: Any,
-    ) -> Dict[str, Any]:
-        values: Dict[str, Any] = {}
-
-        for checker in self.pre_checkers:
-            await checker._solve(**params)
+    async def _solve_field(self, field: ModelField, params: dict[str, Any]) -> Any:
+        param = cast(Param, field.field_info)
+        value = await param._solve(**params)
+        if value is PydanticUndefined:
+            value = field.get_default()
+        v = check_field_type(field, value)
+        return v if param.validate else value
 
+    async def solve(self, **params: Any) -> dict[str, Any]:
+        # solve parameterless
         for param in self.parameterless:
             await param._solve(**params)
 
-        for field in self.params:
-            field_info = field.field_info
-            assert isinstance(field_info, Param), "Params must be subclasses of Param"
-            value = await field_info._solve(**params)
-            if value == Undefined:
-                value = field.get_default()
-            _, errs_ = field.validate(value, values, loc=(str(field_info), field.alias))
-            if errs_:
-                logger.debug(
-                    f"{field_info} "
-                    f"type {type(value)} not match depends {self.call} "
-                    f"annotation {field._type_display()}, ignored"
-                )
-                raise TypeMisMatch(field, value)
-            else:
-                values[field.name] = value
+        # solve param values
+        result: dict[str, Any] = {}
+        if not self.params:
+            return result
 
-        return values
+        async def _solve_field(field: ModelField, params: dict[str, Any]) -> None:
+            value = await self._solve_field(field, params)
+            result[field.name] = value
+
+        async with anyio.create_task_group() as tg:
+            for field in self.params:
+                # shield the task to prevent cancellation
+                # when one of the tasks raises an exception
+                # this will improve the dependency cache reusability
+                tg.start_soon(run_coro_with_shield, _solve_field(field, params))
+
+        return result
+
+
+__autodoc__ = {"CustomConfig": False}

nonebot/dependencies/utils.py

@@ -1,11 +1,25 @@
+"""
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 1
+    description: nonebot.dependencies.utils 模块
+"""
+
 import inspect
-from typing import Any, Dict, Callable
+from typing import Any, Callable, ForwardRef, cast
+from typing_extensions import TypeAliasType
 
 from loguru import logger
-from pydantic.typing import ForwardRef, evaluate_forwardref
+
+from nonebot.compat import ModelField
+from nonebot.exception import TypeMisMatch
+from nonebot.typing import evaluate_forwardref, is_type_alias_type
 
 
 def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature:
+    """获取可调用对象签名"""
+
     signature = inspect.signature(call)
     globalns = getattr(call, "__globals__", {})
     typed_params = [
@@ -17,11 +31,12 @@ def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature:
         )
         for param in signature.parameters.values()
     ]
-    typed_signature = inspect.Signature(typed_params)
-    return typed_signature
+    return inspect.Signature(typed_params)
 
 
-def get_typed_annotation(param: inspect.Parameter, globalns: Dict[str, Any]) -> Any:
+def get_typed_annotation(param: inspect.Parameter, globalns: dict[str, Any]) -> Any:
+    """获取参数的类型注解"""
+
     annotation = param.annotation
     if isinstance(annotation, str):
         annotation = ForwardRef(annotation)
@@ -32,4 +47,16 @@ def get_typed_annotation(param: inspect.Parameter, globalns: Dict[str, Any]) ->
                 f'Unknown ForwardRef["{param.annotation}"] for parameter {param.name}'
             )
             return inspect.Parameter.empty
+    if is_type_alias_type(annotation):
+        # Python 3.12+ supports PEP 695 TypeAliasType
+        annotation = cast(TypeAliasType, annotation).__value__
     return annotation
+
+
+def check_field_type(field: ModelField, value: Any) -> Any:
+    """检查字段类型是否匹配"""
+
+    try:
+        return field.validate_value(value)
+    except ValueError:
+        raise TypeMisMatch(field, value)

nonebot/drivers/__init__.py

@@ -1,297 +1,53 @@
-"""
-后端驱动适配基类
-=================
+"""本模块定义了驱动适配器基类。
 
-各驱动请继承以下基类
+各驱动请继承以下基类。
+
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 0
+    description: nonebot.drivers 模块
 """
 
-import abc
-import asyncio
-from dataclasses import dataclass
-from contextlib import asynccontextmanager
-from typing import (
-    TYPE_CHECKING,
-    Any,
-    Set,
-    Dict,
-    Type,
-    Callable,
-    Awaitable,
-    AsyncGenerator,
-)
+from nonebot.internal.driver import URL as URL
+from nonebot.internal.driver import ASGIMixin as ASGIMixin
+from nonebot.internal.driver import Cookies as Cookies
+from nonebot.internal.driver import Driver as Driver
+from nonebot.internal.driver import ForwardDriver as ForwardDriver
+from nonebot.internal.driver import ForwardMixin as ForwardMixin
+from nonebot.internal.driver import HTTPClientMixin as HTTPClientMixin
+from nonebot.internal.driver import HTTPClientSession as HTTPClientSession
+from nonebot.internal.driver import HTTPServerSetup as HTTPServerSetup
+from nonebot.internal.driver import HTTPVersion as HTTPVersion
+from nonebot.internal.driver import Mixin as Mixin
+from nonebot.internal.driver import Request as Request
+from nonebot.internal.driver import Response as Response
+from nonebot.internal.driver import ReverseDriver as ReverseDriver
+from nonebot.internal.driver import ReverseMixin as ReverseMixin
+from nonebot.internal.driver import Timeout as Timeout
+from nonebot.internal.driver import WebSocket as WebSocket
+from nonebot.internal.driver import WebSocketClientMixin as WebSocketClientMixin
+from nonebot.internal.driver import WebSocketServerSetup as WebSocketServerSetup
+from nonebot.internal.driver import combine_driver as combine_driver
 
-from ._model import URL as URL
-from nonebot.log import logger
-from nonebot.utils import escape_tag
-from ._model import Request as Request
-from nonebot.config import Env, Config
-from ._model import Response as Response
-from ._model import WebSocket as WebSocket
-from ._model import HTTPVersion as HTTPVersion
-from nonebot.typing import T_BotConnectionHook, T_BotDisconnectionHook
-
-if TYPE_CHECKING:
-    from nonebot.adapters import Bot, Adapter
-
-
-class Driver(abc.ABC):
-    """
-    Driver 基类。
-    """
-
-    _adapters: Dict[str, "Adapter"] = {}
-    """
-    :类型: ``Dict[str, Adapter]``
-    :说明: 已注册的适配器列表
-    """
-    _bot_connection_hook: Set[T_BotConnectionHook] = set()
-    """
-    :类型: ``Set[T_BotConnectionHook]``
-    :说明: Bot 连接建立时执行的函数
-    """
-    _bot_disconnection_hook: Set[T_BotDisconnectionHook] = set()
-    """
-    :类型: ``Set[T_BotDisconnectionHook]``
-    :说明: Bot 连接断开时执行的函数
-    """
-
-    def __init__(self, env: Env, config: Config):
-        """
-        :参数:
-
-          * ``env: Env``: 包含环境信息的 Env 对象
-          * ``config: Config``: 包含配置信息的 Config 对象
-        """
-        self.env: str = env.environment
-        """
-        :类型: ``str``
-        :说明: 环境名称
-        """
-        self.config: Config = config
-        """
-        :类型: ``Config``
-        :说明: 配置对象
-        """
-        self._clients: Dict[str, "Bot"] = {}
-        """
-        :类型: ``Dict[str, Bot]``
-        :说明: 已连接的 Bot
-        """
-
-    @property
-    def bots(self) -> Dict[str, "Bot"]:
-        """
-        :类型:
-
-          ``Dict[str, Bot]``
-        :说明:
-
-          获取当前所有已连接的 Bot
-        """
-        return self._clients
-
-    def register_adapter(self, adapter: Type["Adapter"], **kwargs) -> None:
-        """
-        :说明:
-
-          注册一个协议适配器
-
-        :参数:
-
-          * ``name: str``: 适配器名称，用于在连接时进行识别
-          * ``adapter: Type[Bot]``: 适配器 Class
-          * ``**kwargs``: 其他传递给适配器的参数
-        """
-        name = adapter.get_name()
-        if name in self._adapters:
-            logger.opt(colors=True).debug(
-                f'Adapter "<y>{escape_tag(name)}</y>" already exists'
-            )
-            return
-        self._adapters[name] = adapter(self, **kwargs)
-        logger.opt(colors=True).debug(
-            f'Succeeded to load adapter "<y>{escape_tag(name)}</y>"'
-        )
-
-    @property
-    @abc.abstractmethod
-    def type(self) -> str:
-        """驱动类型名称"""
-        raise NotImplementedError
-
-    @property
-    @abc.abstractmethod
-    def logger(self):
-        """驱动专属 logger 日志记录器"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def run(self, *args, **kwargs):
-        """
-        :说明:
-
-          启动驱动框架
-
-        :参数:
-          * ``*args``
-          * ``**kwargs``
-        """
-        logger.opt(colors=True).debug(
-            f"<g>Loaded adapters: {escape_tag(', '.join(self._adapters))}</g>"
-        )
-
-    @abc.abstractmethod
-    def on_startup(self, func: Callable) -> Callable:
-        """注册一个在驱动启动时运行的函数"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def on_shutdown(self, func: Callable) -> Callable:
-        """注册一个在驱动停止时运行的函数"""
-        raise NotImplementedError
-
-    def on_bot_connect(self, func: T_BotConnectionHook) -> T_BotConnectionHook:
-        """
-        :说明:
-
-          装饰一个函数使他在 bot 通过 WebSocket 连接成功时执行。
-
-        :函数参数:
-
-          * ``bot: Bot``: 当前连接上的 Bot 对象
-        """
-        self._bot_connection_hook.add(func)
-        return func
-
-    def on_bot_disconnect(self, func: T_BotDisconnectionHook) -> T_BotDisconnectionHook:
-        """
-        :说明:
-
-          装饰一个函数使他在 bot 通过 WebSocket 连接断开时执行。
-
-        :函数参数:
-
-          * ``bot: Bot``: 当前连接上的 Bot 对象
-        """
-        self._bot_disconnection_hook.add(func)
-        return func
-
-    def _bot_connect(self, bot: "Bot") -> None:
-        """在 WebSocket 连接成功后，调用该函数来注册 bot 对象"""
-        if bot.self_id in self._clients:
-            raise RuntimeError(f"Duplicate bot connection with id {bot.self_id}")
-        self._clients[bot.self_id] = bot
-
-        async def _run_hook(bot: "Bot") -> None:
-            coros = list(map(lambda x: x(bot), self._bot_connection_hook))
-            if coros:
-                try:
-                    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>"
-                    )
-
-        asyncio.create_task(_run_hook(bot))
-
-    def _bot_disconnect(self, bot: "Bot") -> None:
-        """在 WebSocket 连接断开后，调用该函数来注销 bot 对象"""
-        if bot.self_id in self._clients:
-            del self._clients[bot.self_id]
-
-        async def _run_hook(bot: "Bot") -> None:
-            coros = list(map(lambda x: x(bot), self._bot_disconnection_hook))
-            if coros:
-                try:
-                    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>"
-                    )
-
-        asyncio.create_task(_run_hook(bot))
-
-
-class ForwardMixin(abc.ABC):
-    @property
-    @abc.abstractmethod
-    def type(self) -> str:
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    async def request(self, setup: Request) -> Response:
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    @asynccontextmanager
-    async def websocket(self, setup: Request) -> AsyncGenerator[WebSocket, None]:
-        raise NotImplementedError
-        yield  # used for static type checking's generator detection
-
-
-class ForwardDriver(Driver, ForwardMixin):
-    """
-    Forward Driver 基类。将客户端框架封装，以满足适配器使用。
-    """
-
-
-class ReverseDriver(Driver):
-    """
-    Reverse Driver 基类。将后端框架封装，以满足适配器使用。
-    """
-
-    @property
-    @abc.abstractmethod
-    def server_app(self) -> Any:
-        """驱动 APP 对象"""
-        raise NotImplementedError
-
-    @property
-    @abc.abstractmethod
-    def asgi(self) -> Any:
-        """驱动 ASGI 对象"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def setup_http_server(self, setup: "HTTPServerSetup") -> None:
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def setup_websocket_server(self, setup: "WebSocketServerSetup") -> None:
-        raise NotImplementedError
-
-
-def combine_driver(driver: Type[Driver], *mixins: Type[ForwardMixin]) -> Type[Driver]:
-    # check first
-    assert issubclass(driver, Driver), "`driver` must be subclass of Driver"
-    assert all(
-        map(lambda m: issubclass(m, ForwardMixin), mixins)
-    ), "`mixins` must be subclass of ForwardMixin"
-
-    class CombinedDriver(*mixins, driver, ForwardDriver):  # type: ignore
-        @property
-        def type(self) -> str:
-            return (
-                driver.type.__get__(self)
-                + "+"
-                + "+".join(map(lambda x: x.type.__get__(self), mixins))
-            )
-
-    return CombinedDriver
-
-
-@dataclass
-class HTTPServerSetup:
-    path: URL  # path should not be absolute, check it by URL.is_absolute() == False
-    method: str
-    name: str
-    handle_func: Callable[[Request], Awaitable[Response]]
-
-
-@dataclass
-class WebSocketServerSetup:
-    path: URL  # path should not be absolute, check it by URL.is_absolute() == False
-    name: str
-    handle_func: Callable[[WebSocket], Awaitable[Any]]
+__autodoc__ = {
+    "URL": True,
+    "Cookies": True,
+    "Request": True,
+    "Response": True,
+    "Timeout": True,
+    "WebSocket": True,
+    "HTTPVersion": True,
+    "Driver": True,
+    "Mixin": True,
+    "ForwardMixin": True,
+    "ForwardDriver": True,
+    "HTTPClientMixin": True,
+    "WebSocketClientMixin": True,
+    "ReverseMixin": True,
+    "ReverseDriver": True,
+    "ASGIMixin": True,
+    "combine_driver": True,
+    "HTTPServerSetup": True,
+    "WebSocketServerSetup": True,
+}

nonebot/drivers/_block_driver.py

@@ -1,154 +0,0 @@
-import signal
-import asyncio
-import threading
-from typing import Set, Callable, Awaitable
-
-from nonebot.log import logger
-from nonebot.drivers import Driver
-from nonebot.typing import overrides
-from nonebot.config import Env, Config
-
-STARTUP_FUNC = Callable[[], Awaitable[None]]
-SHUTDOWN_FUNC = Callable[[], Awaitable[None]]
-HANDLED_SIGNALS = (
-    signal.SIGINT,  # Unix signal 2. Sent by Ctrl+C.
-    signal.SIGTERM,  # Unix signal 15. Sent by `kill <pid>`.
-)
-
-
-class BlockDriver(Driver):
-    def __init__(self, env: Env, config: Config):
-        super().__init__(env, config)
-        self.startup_funcs: Set[STARTUP_FUNC] = set()
-        self.shutdown_funcs: Set[SHUTDOWN_FUNC] = set()
-        self.should_exit: asyncio.Event = asyncio.Event()
-        self.force_exit: bool = False
-
-    @property
-    @overrides(Driver)
-    def type(self) -> str:
-        """驱动名称: ``block_driver``"""
-        return "block_driver"
-
-    @property
-    @overrides(Driver)
-    def logger(self):
-        """block driver 使用的 logger"""
-        return logger
-
-    @overrides(Driver)
-    def on_startup(self, func: STARTUP_FUNC) -> STARTUP_FUNC:
-        """
-        :说明:
-
-          注册一个启动时执行的函数
-
-        :参数:
-
-          * ``func: Callable[[], Awaitable[None]]``
-        """
-        self.startup_funcs.add(func)
-        return func
-
-    @overrides(Driver)
-    def on_shutdown(self, func: SHUTDOWN_FUNC) -> SHUTDOWN_FUNC:
-        """
-        :说明:
-
-          注册一个停止时执行的函数
-
-        :参数:
-
-          * ``func: Callable[[], Awaitable[None]]``
-        """
-        self.shutdown_funcs.add(func)
-        return func
-
-    @overrides(Driver)
-    def run(self, *args, **kwargs):
-        """启动 block driver"""
-        super().run(*args, **kwargs)
-        loop = asyncio.get_event_loop()
-        loop.run_until_complete(self.serve())
-
-    async def serve(self):
-        self.install_signal_handlers()
-        await self.startup()
-        if self.should_exit.is_set():
-            return
-        await self.main_loop()
-        await self.shutdown()
-
-    async def startup(self):
-        # run startup
-        cors = [startup() for startup in self.startup_funcs]
-        if cors:
-            try:
-                await asyncio.gather(*cors)
-            except Exception as e:
-                logger.opt(colors=True, exception=e).error(
-                    "<r><bg #f8bbd0>Error when running startup function. "
-                    "Ignored!</bg #f8bbd0></r>"
-                )
-
-        logger.info("Application startup completed.")
-
-    async def main_loop(self):
-        await self.should_exit.wait()
-
-    async def shutdown(self):
-        logger.info("Shutting down")
-
-        logger.info("Waiting for application shutdown.")
-        # run shutdown
-        cors = [shutdown() for shutdown in self.shutdown_funcs]
-        if cors:
-            try:
-                await asyncio.gather(*cors)
-            except Exception as e:
-                logger.opt(colors=True, exception=e).error(
-                    "<r><bg #f8bbd0>Error when running shutdown function. "
-                    "Ignored!</bg #f8bbd0></r>"
-                )
-
-        for task in asyncio.all_tasks():
-            if task is not asyncio.current_task() and not task.done():
-                task.cancel()
-        await asyncio.sleep(0.1)
-
-        tasks = [t for t in asyncio.all_tasks() if t is not asyncio.current_task()]
-        if tasks and not self.force_exit:
-            logger.info("Waiting for tasks to finish. (CTRL+C to force quit)")
-        while tasks and not self.force_exit:
-            await asyncio.sleep(0.1)
-            tasks = [t for t in asyncio.all_tasks() if t is not asyncio.current_task()]
-
-        for task in tasks:
-            task.cancel()
-
-        await asyncio.gather(*tasks, return_exceptions=True)
-
-        logger.info("Application shutdown complete.")
-        loop = asyncio.get_event_loop()
-        loop.stop()
-
-    def install_signal_handlers(self) -> None:
-        if threading.current_thread() is not threading.main_thread():
-            # Signals can only be listened to from the main thread.
-            return
-
-        loop = asyncio.get_event_loop()
-
-        try:
-            for sig in HANDLED_SIGNALS:
-                loop.add_signal_handler(sig, self.handle_exit, sig, None)
-        except NotImplementedError:
-            # Windows
-            for sig in HANDLED_SIGNALS:
-                signal.signal(sig, self.handle_exit)
-
-    def handle_exit(self, sig, frame):
-        if self.should_exit.is_set():
-            self.force_exit = True
-        else:
-            self.should_exit.set()

nonebot/drivers/aiohttp.py

@@ -1,68 +1,251 @@
-"""
-AIOHTTP 驱动适配
-================
+"""[AIOHTTP](https://aiohttp.readthedocs.io/en/stable/) 驱动适配器。
 
+```bash
+nb driver install aiohttp
+# 或者
+pip install nonebot2[aiohttp]
+```
+
+:::tip 提示
 本驱动仅支持客户端连接
+:::
+
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 2
+    description: nonebot.drivers.aiohttp 模块
 """
 
-from typing import AsyncGenerator
+from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Optional, Union
+from typing_extensions import override
 
-from nonebot.typing import overrides
-from nonebot.drivers import Request, Response
-from nonebot.exception import WebSocketClosed
-from nonebot.drivers._block_driver import BlockDriver
+from multidict import CIMultiDict
+
+from nonebot.drivers import (
+    URL,
+    HTTPClientMixin,
+    HTTPClientSession,
+    HTTPVersion,
+    Request,
+    Response,
+    WebSocketClientMixin,
+    combine_driver,
+)
 from nonebot.drivers import WebSocket as BaseWebSocket
-from nonebot.drivers import HTTPVersion, ForwardMixin, combine_driver
+from nonebot.drivers.none import Driver as NoneDriver
+from nonebot.exception import WebSocketClosed
+from nonebot.internal.driver import (
+    Cookies,
+    CookieTypes,
+    HeaderTypes,
+    QueryTypes,
+    Timeout,
+    TimeoutTypes,
+)
 
 try:
     import aiohttp
-except ImportError:
+except ModuleNotFoundError as e:  # pragma: no cover
     raise ImportError(
-        "Please install aiohttp first to use this driver. `pip install nonebot2[aiohttp]`"
-    ) from None
+        "Please install aiohttp first to use this driver. "
+        "Install with pip: `pip install nonebot2[aiohttp]`"
+    ) from e
 
 
-class Mixin(ForwardMixin):
+class Session(HTTPClientSession):
+    @override
+    def __init__(
+        self,
+        params: QueryTypes = None,
+        headers: HeaderTypes = None,
+        cookies: CookieTypes = None,
+        version: Union[str, HTTPVersion] = HTTPVersion.H11,
+        timeout: TimeoutTypes = None,
+        proxy: Optional[str] = None,
+    ):
+        self._client: Optional[aiohttp.ClientSession] = None
+
+        self._params = URL.build(query=params).query if params is not None else None
+
+        self._headers = CIMultiDict(headers) if headers is not None else None
+        self._cookies = tuple(
+            (cookie.name, cookie.value)
+            for cookie in Cookies(cookies)
+            if cookie.value is not None
+        )
+
+        version = HTTPVersion(version)
+        if version == HTTPVersion.H10:
+            self._version = aiohttp.HttpVersion10
+        elif version == HTTPVersion.H11:
+            self._version = aiohttp.HttpVersion11
+        else:
+            raise RuntimeError(f"Unsupported HTTP version: {version}")
+
+        if isinstance(timeout, Timeout):
+            self._timeout = aiohttp.ClientTimeout(
+                total=timeout.total,
+                connect=timeout.connect,
+                sock_read=timeout.read,
+            )
+        else:
+            self._timeout = aiohttp.ClientTimeout(timeout)
+
+        self._proxy = proxy
+
     @property
-    @overrides(ForwardMixin)
+    def client(self) -> aiohttp.ClientSession:
+        if self._client is None:
+            raise RuntimeError("Session is not initialized")
+        return self._client
+
+    @override
+    async def request(self, setup: Request) -> Response:
+        if self._params:
+            url = setup.url.with_query({**self._params, **setup.url.query})
+        else:
+            url = setup.url
+
+        data = setup.data
+        if setup.files:
+            data = aiohttp.FormData(data or {}, quote_fields=False)
+            for name, file in setup.files:
+                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 is not None
+        )
+
+        if isinstance(setup.timeout, Timeout):
+            timeout = aiohttp.ClientTimeout(
+                total=setup.timeout.total,
+                connect=setup.timeout.connect,
+                sock_read=setup.timeout.read,
+            )
+        else:
+            timeout = aiohttp.ClientTimeout(setup.timeout)
+
+        async with await self.client.request(
+            setup.method,
+            url,
+            data=setup.content or data,
+            json=setup.json,
+            cookies=cookies,
+            headers=setup.headers,
+            proxy=setup.proxy or self._proxy,
+            timeout=timeout,
+        ) as response:
+            return Response(
+                response.status,
+                headers=response.headers.copy(),
+                content=await response.read(),
+                request=setup,
+            )
+
+    @override
+    async def stream_request(
+        self,
+        setup: Request,
+        *,
+        chunk_size: int = 1024,
+    ) -> AsyncGenerator[Response, None]:
+        if self._params:
+            url = setup.url.with_query({**self._params, **setup.url.query})
+        else:
+            url = setup.url
+
+        data = setup.data
+        if setup.files:
+            data = aiohttp.FormData(data or {}, quote_fields=False)
+            for name, file in setup.files:
+                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 is not None
+        )
+
+        if isinstance(setup.timeout, Timeout):
+            timeout = aiohttp.ClientTimeout(
+                total=setup.timeout.total,
+                connect=setup.timeout.connect,
+                sock_read=setup.timeout.read,
+            )
+        else:
+            timeout = aiohttp.ClientTimeout(setup.timeout)
+
+        async with self.client.request(
+            setup.method,
+            url,
+            data=setup.content or data,
+            json=setup.json,
+            cookies=cookies,
+            headers=setup.headers,
+            proxy=setup.proxy or self._proxy,
+            timeout=timeout,
+        ) as response:
+            response_headers = response.headers.copy()
+            async for chunk in response.content.iter_chunked(chunk_size):
+                yield Response(
+                    response.status,
+                    headers=response_headers,
+                    content=chunk,
+                    request=setup,
+                )
+
+    @override
+    async def setup(self) -> None:
+        if self._client is not None:
+            raise RuntimeError("Session has already been initialized")
+        self._client = aiohttp.ClientSession(
+            cookies=self._cookies,
+            headers=self._headers,
+            version=self._version,
+            timeout=self._timeout,
+            trust_env=True,
+        )
+        await self._client.__aenter__()
+
+    @override
+    async def close(self) -> None:
+        try:
+            if self._client is not None:
+                await self._client.close()
+        finally:
+            self._client = None
+
+
+class Mixin(HTTPClientMixin, WebSocketClientMixin):
+    """AIOHTTP Mixin"""
+
+    @property
+    @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
-        elif setup.version == HTTPVersion.H11:
-            version = aiohttp.HttpVersion11
-        else:
-            raise RuntimeError(f"Unsupported HTTP version: {setup.version}")
+        async with self.get_session() as session:
+            return await session.request(setup)
 
-        timeout = aiohttp.ClientTimeout(setup.timeout)
-        files = None
-        if setup.files:
-            files = aiohttp.FormData()
-            for name, file in setup.files:
-                files.add_field(name, file[1], content_type=file[2], filename=file[0])
-        async with aiohttp.ClientSession(version=version, trust_env=True) as session:
-            async with session.request(
-                setup.method,
-                setup.url,
-                data=setup.content or setup.data or files,
-                json=setup.json,
-                headers=setup.headers,
-                timeout=timeout,
-                proxy=setup.proxy,
-            ) as response:
-                res = Response(
-                    response.status,
-                    headers=response.headers.copy(),
-                    content=await response.read(),
-                    request=setup,
-                )
-                return res
+    @override
+    async def stream_request(
+        self,
+        setup: Request,
+        *,
+        chunk_size: int = 1024,
+    ) -> AsyncGenerator[Response, None]:
+        async with self.get_session() as session:
+            async for response in session.stream_request(setup, chunk_size=chunk_size):
+                yield response
 
-    @overrides(ForwardMixin)
+    @override
     @asynccontextmanager
     async def websocket(self, setup: Request) -> AsyncGenerator["WebSocket", None]:
         if setup.version == HTTPVersion.H10:
@@ -72,19 +255,47 @@ class Mixin(ForwardMixin):
         else:
             raise RuntimeError(f"Unsupported HTTP version: {setup.version}")
 
+        if isinstance(setup.timeout, Timeout):
+            timeout = aiohttp.ClientWSTimeout(
+                ws_receive=setup.timeout.read,  # type: ignore
+                ws_close=setup.timeout.total,  # type: ignore
+            )
+        else:
+            timeout = aiohttp.ClientWSTimeout(ws_close=setup.timeout or 10.0)  # type: ignore
+
         async with aiohttp.ClientSession(version=version, trust_env=True) as session:
             async with session.ws_connect(
                 setup.url,
                 method=setup.method,
-                timeout=setup.timeout or 10,
+                timeout=timeout,
                 headers=setup.headers,
                 proxy=setup.proxy,
             ) as ws:
-                websocket = WebSocket(request=setup, session=session, websocket=ws)
-                yield websocket
+                yield WebSocket(request=setup, session=session, websocket=ws)
+
+    @override
+    def get_session(
+        self,
+        params: QueryTypes = None,
+        headers: HeaderTypes = None,
+        cookies: CookieTypes = None,
+        version: Union[str, HTTPVersion] = HTTPVersion.H11,
+        timeout: TimeoutTypes = None,
+        proxy: Optional[str] = None,
+    ) -> Session:
+        return Session(
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            version=version,
+            timeout=timeout,
+            proxy=proxy,
+        )
 
 
 class WebSocket(BaseWebSocket):
+    """AIOHTTP Websocket Wrapper"""
+
     def __init__(
         self,
         *,
@@ -97,17 +308,17 @@ 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)
-    async def close(self, code: int = 1000):
-        await self.websocket.close(code=code)
+    @override
+    async def close(self, code: int = 1000, reason: str = ""):
+        await self.websocket.close(code=code, message=reason.encode("utf-8"))
         await self.session.close()
 
     async def _receive(self) -> aiohttp.WSMessage:
@@ -116,27 +327,46 @@ 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 != aiohttp.WSMsgType.TEXT:
-            raise TypeError(f"WebSocket received unexpected frame type: {msg.type}")
+        if msg.type not in (aiohttp.WSMsgType.TEXT, aiohttp.WSMsgType.BINARY):
+            raise TypeError(
+                f"WebSocket received unexpected frame type: {msg.type}, {msg.data!r}"
+            )
         return msg.data
 
-    @overrides(BaseWebSocket)
-    async def receive_bytes(self) -> bytes:
+    @override
+    async def receive_text(self) -> str:
         msg = await self._receive()
         if msg.type != aiohttp.WSMsgType.TEXT:
-            raise TypeError(f"WebSocket received unexpected frame type: {msg.type}")
+            raise TypeError(
+                f"WebSocket received unexpected frame type: {msg.type}, {msg.data!r}"
+            )
         return msg.data
 
-    @overrides(BaseWebSocket)
-    async def send(self, data: str) -> None:
+    @override
+    async def receive_bytes(self) -> bytes:
+        msg = await self._receive()
+        if msg.type != aiohttp.WSMsgType.BINARY:
+            raise TypeError(
+                f"WebSocket received unexpected frame type: {msg.type}, {msg.data!r}"
+            )
+        return msg.data
+
+    @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)
 
 
-Driver = combine_driver(BlockDriver, Mixin)
+if TYPE_CHECKING:
+
+    class Driver(Mixin, NoneDriver): ...
+
+else:
+    Driver = combine_driver(NoneDriver, Mixin)
+    """AIOHTTP Driver"""

nonebot/drivers/fastapi.py

@@ -1,33 +1,50 @@
-"""
-FastAPI 驱动适配
-================
+"""[FastAPI](https://fastapi.tiangolo.com/) 驱动适配
 
-本驱动同时支持服务端以及客户端连接
+```bash
+nb driver install fastapi
+# 或者
+pip install nonebot2[fastapi]
+```
 
-后端使用方法请参考: `FastAPI 文档`_
+:::tip 提示
+本驱动仅支持服务端连接
+:::
 
-.. _FastAPI 文档:
-    https://fastapi.tiangolo.com/
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 1
+    description: nonebot.drivers.fastapi 模块
 """
 
-import logging
+import contextlib
 from functools import wraps
-from typing import Any, List, Tuple, Callable, Optional
+import logging
+from typing import Any, Optional, Union
+from typing_extensions import override
 
-import uvicorn
-from pydantic import BaseSettings
-from fastapi.responses import Response
-from fastapi import FastAPI, Request, UploadFile, status
-from starlette.websockets import WebSocket, WebSocketState, WebSocketDisconnect
+from pydantic import BaseModel
 
-from ._model import FileTypes
-from nonebot.config import Env
-from nonebot.typing import overrides
-from nonebot.exception import WebSocketClosed
+from nonebot.compat import model_dump, type_validate_python
 from nonebot.config import Config as NoneBotConfig
+from nonebot.config import Env
+from nonebot.drivers import ASGIMixin, HTTPServerSetup, WebSocketServerSetup
+from nonebot.drivers import Driver as BaseDriver
 from nonebot.drivers import Request as BaseRequest
 from nonebot.drivers import WebSocket as BaseWebSocket
-from nonebot.drivers import ReverseDriver, HTTPServerSetup, WebSocketServerSetup
+from nonebot.exception import WebSocketClosed
+from nonebot.internal.driver import FileTypes
+
+try:
+    from fastapi import FastAPI, Request, UploadFile, status
+    from fastapi.responses import Response
+    from starlette.websockets import WebSocket, WebSocketDisconnect, WebSocketState
+    import uvicorn
+except ModuleNotFoundError as e:  # pragma: no cover
+    raise ImportError(
+        "Please install FastAPI first to use this driver. "
+        "Install with pip: `pip install nonebot2[fastapi]`"
+    ) from e
 
 
 def catch_closed(func):
@@ -37,139 +54,78 @@ def catch_closed(func):
             return await func(*args, **kwargs)
         except WebSocketDisconnect as e:
             raise WebSocketClosed(e.code)
+        except KeyError:
+            raise TypeError("WebSocket received unexpected frame type")
 
     return decorator
 
 
-class Config(BaseSettings):
-    """
-    FastAPI 驱动框架设置，详情参考 FastAPI 文档
-    """
+class Config(BaseModel):
+    """FastAPI 驱动框架设置，详情参考 FastAPI 文档"""
 
     fastapi_openapi_url: Optional[str] = None
-    """
-    :类型:
-
-      ``Optional[str]``
-
-    :说明:
-
-      ``openapi.json`` 地址，默认为 ``None`` 即关闭
-    """
+    """`openapi.json` 地址，默认为 `None` 即关闭"""
     fastapi_docs_url: Optional[str] = None
-    """
-    :类型:
-
-      ``Optional[str]``
-
-    :说明:
-
-      ``swagger`` 地址，默认为 ``None`` 即关闭
-    """
+    """`swagger` 地址，默认为 `None` 即关闭"""
     fastapi_redoc_url: Optional[str] = None
-    """
-    :类型:
-
-      ``Optional[str]``
-
-    :说明:
-
-      ``redoc`` 地址，默认为 ``None`` 即关闭
-    """
+    """`redoc` 地址，默认为 `None` 即关闭"""
+    fastapi_include_adapter_schema: bool = True
+    """是否包含适配器路由的 schema，默认为 `True`"""
     fastapi_reload: bool = False
-    """
-    :类型:
-
-      ``bool``
-
-    :说明:
-
-      开启/关闭冷重载
-    """
-    fastapi_reload_dirs: Optional[List[str]] = None
-    """
-    :类型:
-
-      ``Optional[List[str]]``
-
-    :说明:
-
-      重载监控文件夹列表，默认为 uvicorn 默认值
-    """
-    fastapi_reload_delay: Optional[float] = None
-    """
-    :类型:
-
-      ``Optional[float]``
-
-    :说明:
-
-      重载延迟，默认为 uvicorn 默认值
-    """
-    fastapi_reload_includes: Optional[List[str]] = None
-    """
-    :类型:
-
-      ``Optional[List[str]]``
-
-    :说明:
-
-      要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
-    """
-    fastapi_reload_excludes: Optional[List[str]] = None
-    """
-    :类型:
-
-      ``Optional[List[str]]``
-
-    :说明:
-
-      不要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
-    """
-
-    class Config:
-        extra = "ignore"
+    """开启/关闭冷重载"""
+    fastapi_reload_dirs: Optional[list[str]] = None
+    """重载监控文件夹列表，默认为 uvicorn 默认值"""
+    fastapi_reload_delay: float = 0.25
+    """重载延迟，默认为 uvicorn 默认值"""
+    fastapi_reload_includes: Optional[list[str]] = None
+    """要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值"""
+    fastapi_reload_excludes: Optional[list[str]] = None
+    """不要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值"""
+    fastapi_extra: dict[str, Any] = {}
+    """传递给 `FastAPI` 的其他参数。"""
 
 
-class Driver(ReverseDriver):
-    """FastAPI 驱动框架。包含反向 Server 功能。"""
+class Driver(BaseDriver, ASGIMixin):
+    """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())
+        self.fastapi_config: Config = type_validate_python(Config, model_dump(config))
 
         self._server_app = FastAPI(
+            lifespan=self._lifespan_manager,
             openapi_url=self.fastapi_config.fastapi_openapi_url,
             docs_url=self.fastapi_config.fastapi_docs_url,
             redoc_url=self.fastapi_config.fastapi_redoc_url,
+            **self.fastapi_config.fastapi_extra,
         )
 
     @property
-    @overrides(ReverseDriver)
+    @override
     def type(self) -> str:
-        """驱动名称: ``fastapi``"""
+        """驱动名称: `fastapi`"""
         return "fastapi"
 
     @property
-    @overrides(ReverseDriver)
+    @override
     def server_app(self) -> FastAPI:
-        """``FastAPI APP`` 对象"""
+        """`FastAPI APP` 对象"""
         return self._server_app
 
     @property
-    @overrides(ReverseDriver)
+    @override
     def asgi(self) -> FastAPI:
-        """``FastAPI APP`` 对象"""
+        """`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)
@@ -179,9 +135,10 @@ class Driver(ReverseDriver):
             _handle,
             name=setup.name,
             methods=[setup.method],
+            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)
@@ -192,27 +149,25 @@ class Driver(ReverseDriver):
             name=setup.name,
         )
 
-    @overrides(ReverseDriver)
-    def on_startup(self, func: Callable) -> Callable:
-        """参考文档: `Events <https://fastapi.tiangolo.com/advanced/events/#startup-event>`_"""
-        return self.server_app.on_event("startup")(func)
+    @contextlib.asynccontextmanager
+    async def _lifespan_manager(self, app: FastAPI):
+        await self._lifespan.startup()
+        try:
+            yield
+        finally:
+            await self._lifespan.shutdown()
 
-    @overrides(ReverseDriver)
-    def on_shutdown(self, func: Callable) -> Callable:
-        """参考文档: `Events <https://fastapi.tiangolo.com/advanced/events/#startup-event>`_"""
-        return self.server_app.on_event("shutdown")(func)
-
-    @overrides(ReverseDriver)
+    @override
     def run(
         self,
         host: Optional[str] = None,
         port: Optional[int] = None,
-        *,
+        *args,
         app: Optional[str] = None,
         **kwargs,
     ):
-        """使用 ``uvicorn`` 启动 FastAPI"""
-        super().run(host, port, app, **kwargs)
+        """使用 `uvicorn` 启动 FastAPI"""
+        super().run(host, port, app=app, **kwargs)
         LOGGING_CONFIG = {
             "version": 1,
             "disable_existing_loggers": False,
@@ -248,14 +203,12 @@ class Driver(ReverseDriver):
         setup: HTTPServerSetup,
     ) -> Response:
         json: Any = None
-        try:
+        with contextlib.suppress(Exception):
             json = await request.json()
-        except Exception:
-            pass
 
         data: Optional[dict] = None
-        files: Optional[List[Tuple[str, FileTypes]]] = None
-        try:
+        files: Optional[list[tuple[str, FileTypes]]] = None
+        with contextlib.suppress(Exception):
             form = await request.form()
             data = {}
             files = []
@@ -266,8 +219,7 @@ class Driver(ReverseDriver):
                     )
                 else:
                     data[key] = value
-        except Exception:
-            pass
+
         http_request = BaseRequest(
             request.method,
             str(request.url),
@@ -281,7 +233,9 @@ class Driver(ReverseDriver):
         )
 
         response = await setup.handle_func(http_request)
-        return Response(response.content, response.status_code, dict(response.headers))
+        return Response(
+            response.content, response.status_code, dict(response.headers.items())
+        )
 
     async def _handle_ws(self, websocket: WebSocket, setup: WebSocketServerSetup):
         request = BaseRequest(
@@ -300,43 +254,56 @@ class Driver(ReverseDriver):
 
 
 class FastAPIWebSocket(BaseWebSocket):
-    @overrides(BaseWebSocket)
+    """FastAPI WebSocket Wrapper"""
+
+    @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)
+        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()
+        if msg["type"] == "websocket.disconnect":
+            raise WebSocketClosed(msg["code"])
+        return msg["text"] if "text" in msg else msg["bytes"]
+
+    @override
     @catch_closed
-    async def receive(self) -> str:
+    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)
-    async def send(self, data: str) -> None:
+    @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})
+
+
+__autodoc__ = {"catch_closed": False}

nonebot/drivers/httpx.py

@@ -1,60 +1,239 @@
-from typing import AsyncGenerator
-from contextlib import asynccontextmanager
+"""[HTTPX](https://www.python-httpx.org/) 驱动适配
+
+```bash
+nb driver install httpx
+# 或者
+pip install nonebot2[httpx]
+```
+
+:::tip 提示
+本驱动仅支持客户端 HTTP 连接
+:::
+
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 3
+    description: nonebot.drivers.httpx 模块
+"""
+
+from collections.abc import AsyncGenerator
+from typing import TYPE_CHECKING, Optional, Union
+from typing_extensions import override
+
+from multidict import CIMultiDict
 
-from nonebot.typing import overrides
-from nonebot.drivers._block_driver import BlockDriver
 from nonebot.drivers import (
+    URL,
+    HTTPClientMixin,
+    HTTPClientSession,
+    HTTPVersion,
     Request,
     Response,
-    WebSocket,
-    HTTPVersion,
-    ForwardMixin,
     combine_driver,
 )
+from nonebot.drivers.none import Driver as NoneDriver
+from nonebot.internal.driver import (
+    Cookies,
+    CookieTypes,
+    HeaderTypes,
+    QueryTypes,
+    Timeout,
+    TimeoutTypes,
+)
 
 try:
     import httpx
-except ImportError:
+except ModuleNotFoundError as e:  # pragma: no cover
     raise ImportError(
-        "Please install httpx by using `pip install nonebot2[httpx]`"
-    ) from None
+        "Please install httpx first to use this driver. "
+        "Install with pip: `pip install nonebot2[httpx]`"
+    ) from e
 
 
-class Mixin(ForwardMixin):
+class Session(HTTPClientSession):
+    @override
+    def __init__(
+        self,
+        params: QueryTypes = None,
+        headers: HeaderTypes = None,
+        cookies: CookieTypes = None,
+        version: Union[str, HTTPVersion] = HTTPVersion.H11,
+        timeout: TimeoutTypes = None,
+        proxy: Optional[str] = None,
+    ):
+        self._client: Optional[httpx.AsyncClient] = None
+
+        self._params = (
+            tuple(URL.build(query=params).query.items()) if params is not None else None
+        )
+        self._headers = (
+            tuple(CIMultiDict(headers).items()) if headers is not None else None
+        )
+        self._cookies = Cookies(cookies)
+        self._version = HTTPVersion(version)
+
+        if isinstance(timeout, Timeout):
+            self._timeout = httpx.Timeout(
+                timeout=timeout.total,
+                connect=timeout.connect,
+                read=timeout.read,
+            )
+        else:
+            self._timeout = httpx.Timeout(timeout)
+
+        self._proxy = proxy
+
     @property
-    @overrides(ForwardMixin)
+    def client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            raise RuntimeError("Session is not initialized")
+        return self._client
+
+    @override
+    async def request(self, setup: Request) -> Response:
+        if isinstance(setup.timeout, Timeout):
+            timeout = httpx.Timeout(
+                timeout=setup.timeout.total,
+                connect=setup.timeout.connect,
+                read=setup.timeout.read,
+            )
+        else:
+            timeout = httpx.Timeout(setup.timeout)
+
+        response = await self.client.request(
+            setup.method,
+            str(setup.url),
+            content=setup.content,
+            data=setup.data,
+            files=setup.files,
+            json=setup.json,
+            # ensure the params priority
+            params=setup.url.raw_query_string,
+            headers=tuple(setup.headers.items()),
+            cookies=setup.cookies.jar,
+            timeout=timeout,
+        )
+        return Response(
+            response.status_code,
+            headers=response.headers.multi_items(),
+            content=response.content,
+            request=setup,
+        )
+
+    @override
+    async def stream_request(
+        self,
+        setup: Request,
+        *,
+        chunk_size: int = 1024,
+    ) -> AsyncGenerator[Response, None]:
+        if isinstance(setup.timeout, Timeout):
+            timeout = httpx.Timeout(
+                timeout=setup.timeout.total,
+                connect=setup.timeout.connect,
+                read=setup.timeout.read,
+            )
+        else:
+            timeout = httpx.Timeout(setup.timeout)
+
+        async with self.client.stream(
+            setup.method,
+            str(setup.url),
+            content=setup.content,
+            data=setup.data,
+            files=setup.files,
+            json=setup.json,
+            # ensure the params priority
+            params=setup.url.raw_query_string,
+            headers=tuple(setup.headers.items()),
+            cookies=setup.cookies.jar,
+            timeout=timeout,
+        ) as response:
+            response_headers = response.headers.multi_items()
+            async for chunk in response.aiter_bytes(chunk_size=chunk_size):
+                yield Response(
+                    response.status_code,
+                    headers=response_headers,
+                    content=chunk,
+                    request=setup,
+                )
+
+    @override
+    async def setup(self) -> None:
+        if self._client is not None:
+            raise RuntimeError("Session has already been initialized")
+        self._client = httpx.AsyncClient(
+            params=self._params,
+            headers=self._headers,
+            cookies=self._cookies.jar,
+            http2=self._version == HTTPVersion.H2,
+            proxy=self._proxy,
+            follow_redirects=True,
+        )
+        await self._client.__aenter__()
+
+    @override
+    async def close(self) -> None:
+        try:
+            if self._client is not None:
+                await self._client.aclose()
+        finally:
+            self._client = None
+
+
+class Mixin(HTTPClientMixin):
+    """HTTPX Mixin"""
+
+    @property
+    @override
     def type(self) -> str:
         return "httpx"
 
-    @overrides(ForwardMixin)
+    @override
     async def request(self, setup: Request) -> Response:
-        async with httpx.AsyncClient(
-            http2=setup.version == HTTPVersion.H2,
-            proxies=setup.proxy,
-            follow_redirects=True,
-        ) as client:
-            response = await client.request(
-                setup.method,
-                str(setup.url),
-                content=setup.content,
-                data=setup.data,
-                json=setup.json,
-                files=setup.files,
-                headers=tuple(setup.headers.items()),
-                timeout=setup.timeout,
-            )
-            return Response(
-                response.status_code,
-                headers=response.headers,
-                content=response.content,
-                request=setup,
-            )
+        async with self.get_session(
+            version=setup.version, proxy=setup.proxy
+        ) as session:
+            return await session.request(setup)
 
-    @overrides(ForwardMixin)
-    @asynccontextmanager
-    async def websocket(self, setup: Request) -> AsyncGenerator[WebSocket, None]:
-        async with super(Mixin, self).websocket(setup) as ws:
-            yield ws
+    @override
+    async def stream_request(
+        self,
+        setup: Request,
+        *,
+        chunk_size: int = 1024,
+    ) -> AsyncGenerator[Response, None]:
+        async with self.get_session(
+            version=setup.version, proxy=setup.proxy
+        ) as session:
+            async for response in session.stream_request(setup, chunk_size=chunk_size):
+                yield response
+
+    @override
+    def get_session(
+        self,
+        params: QueryTypes = None,
+        headers: HeaderTypes = None,
+        cookies: CookieTypes = None,
+        version: Union[str, HTTPVersion] = HTTPVersion.H11,
+        timeout: TimeoutTypes = None,
+        proxy: Optional[str] = None,
+    ) -> Session:
+        return Session(
+            params=params,
+            headers=headers,
+            cookies=cookies,
+            version=version,
+            timeout=timeout,
+            proxy=proxy,
+        )
 
 
-Driver = combine_driver(BlockDriver, Mixin)
+if TYPE_CHECKING:
+
+    class Driver(Mixin, NoneDriver): ...
+
+else:
+    Driver = combine_driver(NoneDriver, Mixin)
+    """HTTPX Driver"""

nonebot/drivers/none.py

@@ -0,0 +1,160 @@
+"""None 驱动适配
+
+:::tip 提示
+本驱动不支持任何服务器或客户端连接
+:::
+
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 6
+    description: nonebot.drivers.none 模块
+"""
+
+import signal
+from typing import Optional
+from typing_extensions import override
+
+import anyio
+from anyio.abc import TaskGroup
+from exceptiongroup import BaseExceptionGroup, catch
+
+from nonebot.config import Config, Env
+from nonebot.consts import WINDOWS
+from nonebot.drivers import Driver as BaseDriver
+from nonebot.log import logger
+from nonebot.utils import flatten_exception_group
+
+HANDLED_SIGNALS = (
+    signal.SIGINT,  # Unix signal 2. Sent by Ctrl+C.
+    signal.SIGTERM,  # Unix signal 15. Sent by `kill <pid>`.
+)
+if WINDOWS:  # pragma: py-win32
+    HANDLED_SIGNALS += (signal.SIGBREAK,)  # Windows signal 21. Sent by Ctrl+Break.
+
+
+class Driver(BaseDriver):
+    """None 驱动框架"""
+
+    def __init__(self, env: Env, config: Config):
+        super().__init__(env, config)
+
+        self.should_exit: anyio.Event = anyio.Event()
+        self.force_exit: anyio.Event = anyio.Event()
+
+    @property
+    @override
+    def type(self) -> str:
+        """驱动名称: `none`"""
+        return "none"
+
+    @property
+    @override
+    def logger(self):
+        """none driver 使用的 logger"""
+        return logger
+
+    @override
+    def run(self, *args, **kwargs):
+        """启动 none driver"""
+        super().run(*args, **kwargs)
+        anyio.run(self._serve)
+
+    async def _serve(self):
+        async with anyio.create_task_group() as driver_tg:
+            driver_tg.start_soon(self._handle_signals)
+            driver_tg.start_soon(self._listen_force_exit, driver_tg)
+            driver_tg.start_soon(self._handle_lifespan, driver_tg)
+
+    async def _handle_signals(self):
+        try:
+            with anyio.open_signal_receiver(*HANDLED_SIGNALS) as signal_receiver:
+                async for sig in signal_receiver:
+                    self.exit(force=self.should_exit.is_set())
+        except NotImplementedError:
+            # Windows
+            for sig in HANDLED_SIGNALS:
+                signal.signal(sig, self._handle_legacy_signal)
+
+    # backport for Windows signal handling
+    def _handle_legacy_signal(self, sig, frame):
+        self.exit(force=self.should_exit.is_set())
+
+    async def _handle_lifespan(self, tg: TaskGroup):
+        try:
+            await self._startup()
+
+            if self.should_exit.is_set():
+                return
+
+            await self._listen_exit()
+
+            await self._shutdown()
+        finally:
+            tg.cancel_scope.cancel()
+
+    async def _startup(self):
+        def handle_exception(exc_group: BaseExceptionGroup[Exception]) -> None:
+            self.should_exit.set()
+
+            for exc in flatten_exception_group(exc_group):
+                logger.opt(colors=True, exception=exc).error(
+                    "<r><bg #f8bbd0>Error occurred while running startup hook."
+                    "</bg #f8bbd0></r>"
+                )
+            logger.error(
+                "<r><bg #f8bbd0>Application startup failed. Exiting.</bg #f8bbd0></r>"
+            )
+
+        with catch({Exception: handle_exception}):
+            await self._lifespan.startup()
+
+        if not self.should_exit.is_set():
+            logger.info("Application startup completed.")
+
+    async def _listen_exit(self, tg: Optional[TaskGroup] = None):
+        await self.should_exit.wait()
+
+        if tg is not None:
+            tg.cancel_scope.cancel()
+
+    async def _shutdown(self):
+        logger.info("Shutting down")
+        logger.info("Waiting for application shutdown. (CTRL+C to force quit)")
+
+        error_occurred: bool = False
+
+        def handle_exception(exc_group: BaseExceptionGroup[Exception]) -> None:
+            nonlocal error_occurred
+
+            error_occurred = True
+
+            for exc in flatten_exception_group(exc_group):
+                logger.opt(colors=True, exception=exc).error(
+                    "<r><bg #f8bbd0>Error occurred while running shutdown hook."
+                    "</bg #f8bbd0></r>"
+                )
+            logger.error(
+                "<r><bg #f8bbd0>Application shutdown failed. Exiting.</bg #f8bbd0></r>"
+            )
+
+        with catch({Exception: handle_exception}):
+            await self._lifespan.shutdown()
+
+        if not error_occurred:
+            logger.info("Application shutdown complete.")
+
+    async def _listen_force_exit(self, tg: TaskGroup):
+        await self.force_exit.wait()
+        tg.cancel_scope.cancel()
+
+    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.set()

nonebot/drivers/quart.py

@@ -1,41 +1,52 @@
-"""
-Quart 驱动适配
-================
+"""[Quart](https://pgjones.gitlab.io/quart/index.html) 驱动适配
 
-后端使用方法请参考: `Quart 文档`_
+```bash
+nb driver install quart
+# 或者
+pip install nonebot2[quart]
+```
 
-.. _Quart 文档:
-    https://pgjones.gitlab.io/quart/index.html
+:::tip 提示
+本驱动仅支持服务端连接
+:::
+
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 5
+    description: nonebot.drivers.quart 模块
 """
 
 import asyncio
 from functools import wraps
-from typing import List, Tuple, TypeVar, Callable, Optional, Coroutine
+from typing import Any, Optional, Union, cast
+from typing_extensions import override
 
-import uvicorn
-from pydantic import BaseSettings
+from pydantic import BaseModel
 
-from ._model import FileTypes
-from nonebot.config import Env
-from nonebot.typing import overrides
-from nonebot.exception import WebSocketClosed
+from nonebot.compat import model_dump, type_validate_python
 from nonebot.config import Config as NoneBotConfig
+from nonebot.config import Env
+from nonebot.drivers import ASGIMixin, HTTPServerSetup, WebSocketServerSetup
+from nonebot.drivers import Driver as BaseDriver
 from nonebot.drivers import Request as BaseRequest
 from nonebot.drivers import WebSocket as BaseWebSocket
-from nonebot.drivers import ReverseDriver, HTTPServerSetup, WebSocketServerSetup
+from nonebot.exception import WebSocketClosed
+from nonebot.internal.driver import FileTypes
 
 try:
-    from quart import request as _request
-    from quart import websocket as _websocket
     from quart import Quart, Request, Response
-    from quart.datastructures import FileStorage
     from quart import Websocket as QuartWebSocket
-except ImportError:
-    raise ValueError(
-        "Please install Quart by using `pip install nonebot2[quart]`"
-    ) from None
-
-_AsyncCallable = TypeVar("_AsyncCallable", bound=Callable[..., Coroutine])
+    from quart import request as _request
+    from quart.ctx import WebsocketContext
+    from quart.datastructures import FileStorage
+    from quart.globals import websocket_ctx
+    import uvicorn
+except ModuleNotFoundError as e:  # pragma: no cover
+    raise ImportError(
+        "Please install Quart first to use this driver. "
+        "Install with pip: `pip install nonebot2[quart]`"
+    ) from e
 
 
 def catch_closed(func):
@@ -49,103 +60,62 @@ def catch_closed(func):
     return decorator
 
 
-class Config(BaseSettings):
-    """
-    Quart 驱动框架设置
-    """
+class Config(BaseModel):
+    """Quart 驱动框架设置"""
 
     quart_reload: bool = False
-    """
-    :类型:
-
-      ``bool``
-
-    :说明:
-
-      开启/关闭冷重载
-    """
-    quart_reload_dirs: Optional[List[str]] = None
-    """
-    :类型:
-
-      ``Optional[List[str]]``
-
-    :说明:
-
-      重载监控文件夹列表，默认为 uvicorn 默认值
-    """
-    quart_reload_delay: Optional[float] = None
-    """
-    :类型:
-
-      ``Optional[float]``
-
-    :说明:
-
-      重载延迟，默认为 uvicorn 默认值
-    """
-    quart_reload_includes: Optional[List[str]] = None
-    """
-    :类型:
-
-      ``Optional[List[str]]``
-
-    :说明:
-
-      要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
-    """
-    quart_reload_excludes: Optional[List[str]] = None
-    """
-    :类型:
-
-      ``Optional[List[str]]``
-
-    :说明:
-
-      不要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值
-    """
-
-    class Config:
-        extra = "ignore"
+    """开启/关闭冷重载"""
+    quart_reload_dirs: Optional[list[str]] = None
+    """重载监控文件夹列表，默认为 uvicorn 默认值"""
+    quart_reload_delay: float = 0.25
+    """重载延迟，默认为 uvicorn 默认值"""
+    quart_reload_includes: Optional[list[str]] = None
+    """要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值"""
+    quart_reload_excludes: Optional[list[str]] = None
+    """不要监听的文件列表，支持 glob pattern，默认为 uvicorn 默认值"""
+    quart_extra: dict[str, Any] = {}
+    """传递给 `Quart` 的其他参数。"""
 
 
-class Driver(ReverseDriver):
-    """
-    Quart 驱动框架
-    """
+class Driver(BaseDriver, ASGIMixin):
+    """Quart 驱动框架"""
 
     def __init__(self, env: Env, config: NoneBotConfig):
         super().__init__(env, config)
 
-        self.quart_config = Config(**config.dict())
+        self.quart_config = type_validate_python(Config, model_dump(config))
 
-        self._server_app = Quart(self.__class__.__qualname__)
+        self._server_app = Quart(
+            self.__class__.__qualname__, **self.quart_config.quart_extra
+        )
+        self._server_app.before_serving(self._lifespan.startup)
+        self._server_app.after_serving(self._lifespan.shutdown)
 
     @property
-    @overrides(ReverseDriver)
+    @override
     def type(self) -> str:
-        """驱动名称: ``quart``"""
+        """驱动名称: `quart`"""
         return "quart"
 
     @property
-    @overrides(ReverseDriver)
+    @override
     def server_app(self) -> Quart:
-        """``Quart`` 对象"""
+        """`Quart` 对象"""
         return self._server_app
 
     @property
-    @overrides(ReverseDriver)
+    @override
     def asgi(self):
-        """``Quart`` 对象"""
+        """`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)
@@ -157,7 +127,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)
@@ -168,30 +138,16 @@ class Driver(ReverseDriver):
             view_func=_handle,
         )
 
-    @overrides(ReverseDriver)
-    def on_startup(self, func: _AsyncCallable) -> _AsyncCallable:
-        """参考文档: `Startup and Shutdown`_
-
-        .. _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)
-    def on_shutdown(self, func: _AsyncCallable) -> _AsyncCallable:
-        """参考文档: `Startup and Shutdown`_"""
-        return self.server_app.after_serving(func)  # type: ignore
-
-    @overrides(ReverseDriver)
+    @override
     def run(
         self,
         host: Optional[str] = None,
         port: Optional[int] = None,
-        *,
+        *args,
         app: Optional[str] = None,
         **kwargs,
     ):
-        """使用 ``uvicorn`` 启动 Quart"""
+        """使用 `uvicorn` 启动 Quart"""
         super().run(host, port, app, **kwargs)
         LOGGING_CONFIG = {
             "version": 1,
@@ -225,13 +181,11 @@ 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
-        files: List[Tuple[str, FileTypes]] = []
+        files: list[tuple[str, FileTypes]] = []
         key: str
         value: FileStorage
         for key, value in files_dict.items():
@@ -240,7 +194,7 @@ class Driver(ReverseDriver):
         http_request = BaseRequest(
             request.method,
             request.url,
-            headers=request.headers.items(),
+            headers=list(request.headers.items()),
             cookies=list(request.cookies.items()),
             content=await request.get_data(
                 cache=False, as_text=False, parse_form_data=False
@@ -260,49 +214,61 @@ 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,
             websocket.url,
-            headers=websocket.headers.items(),
+            headers=list(websocket.headers.items()),
             cookies=list(websocket.cookies.items()),
             version=websocket.http_version,
         )
 
-        ws = WebSocket(request=http_request, websocket=websocket)
+        ws = WebSocket(request=http_request, websocket_ctx=ctx)
 
         await setup.handle_func(ws)
 
 
 class WebSocket(BaseWebSocket):
-    def __init__(self, *, request: BaseRequest, websocket: QuartWebSocket):
+    """Quart WebSocket Wrapper"""
+
+    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) -> str:
+    async def receive(self) -> Union[str, bytes]:
+        return await self.websocket.receive()
+
+    @override
+    @catch_closed
+    async def receive_text(self) -> str:
         msg = await self.websocket.receive()
         if isinstance(msg, bytes):
             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()
@@ -310,10 +276,13 @@ class WebSocket(BaseWebSocket):
             raise TypeError("WebSocket received unexpected frame type: str")
         return msg
 
-    @overrides(BaseWebSocket)
-    async def send(self, data: str):
+    @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)
+
+
+__autodoc__ = {"catch_closed": False}

nonebot/drivers/websockets.py

@@ -1,92 +1,125 @@
-import logging
-from functools import wraps
-from typing import AsyncGenerator
-from contextlib import asynccontextmanager
+"""[websockets](https://websockets.readthedocs.io/) 驱动适配
 
-from nonebot.typing import overrides
-from nonebot.log import LoguruHandler
-from nonebot.drivers import Request, Response
-from nonebot.exception import WebSocketClosed
-from nonebot.drivers._block_driver import BlockDriver
+```bash
+nb driver install websockets
+# 或者
+pip install nonebot2[websockets]
+```
+
+:::tip 提示
+本驱动仅支持客户端 WebSocket 连接
+:::
+
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 4
+    description: nonebot.drivers.websockets 模块
+"""
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from functools import wraps
+import logging
+from types import CoroutineType
+from typing import TYPE_CHECKING, Any, Callable, TypeVar, Union
+from typing_extensions import ParamSpec, override
+
+from nonebot.drivers import Request, Timeout, WebSocketClientMixin, combine_driver
 from nonebot.drivers import WebSocket as BaseWebSocket
-from nonebot.drivers import ForwardMixin, combine_driver
+from nonebot.drivers.none import Driver as NoneDriver
+from nonebot.exception import WebSocketClosed
+from nonebot.log import LoguruHandler
 
 try:
-    from websockets.exceptions import ConnectionClosed
-    from websockets.legacy.client import Connect, WebSocketClientProtocol
-except ImportError:
+    from websockets import ClientConnection, ConnectionClosed, connect
+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, "CoroutineType[Any, Any, T]"],
+) -> Callable[P, "CoroutineType[Any, Any, 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:
-            if e.rcvd_then_sent:
-                raise WebSocketClosed(e.rcvd.code, e.rcvd.reason)
-            else:
-                raise WebSocketClosed(e.sent.code, e.sent.reason)
+            raise WebSocketClosed(e.code, e.reason)
 
     return decorator
 
 
-class Mixin(ForwardMixin):
+class Mixin(WebSocketClientMixin):
+    """Websockets Mixin"""
+
     @property
-    @overrides(ForwardMixin)
+    @override
     def type(self) -> str:
         return "websockets"
 
-    @overrides(ForwardMixin)
-    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(
+        if isinstance(setup.timeout, Timeout):
+            timeout = setup.timeout.total or setup.timeout.connect or setup.timeout.read
+        else:
+            timeout = setup.timeout
+
+        connection = connect(
             str(setup.url),
-            extra_headers=setup.headers.items(),
-            open_timeout=setup.timeout,
+            additional_headers={**setup.headers, **setup.cookies.as_header(setup)},
+            proxy=setup.proxy if setup.proxy is not None else True,
+            open_timeout=timeout,
         )
         async with connection as ws:
             yield WebSocket(request=setup, websocket=ws)
 
 
 class WebSocket(BaseWebSocket):
-    @overrides(BaseWebSocket)
-    def __init__(self, *, request: Request, websocket: WebSocketClientProtocol):
+    """Websockets WebSocket Wrapper"""
+
+    @override
+    def __init__(self, *, request: Request, websocket: ClientConnection):
         super().__init__(request=request)
         self.websocket = websocket
 
     @property
-    @overrides(BaseWebSocket)
+    @override
     def closed(self) -> bool:
-        return self.websocket.closed
+        return self.websocket.close_code is not None
 
-    @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) -> str:
+    async def receive(self) -> Union[str, bytes]:
+        return await self.websocket.recv()
+
+    @override
+    @catch_closed
+    async def receive_text(self) -> str:
         msg = await self.websocket.recv()
         if isinstance(msg, bytes):
             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()
@@ -94,13 +127,19 @@ class WebSocket(BaseWebSocket):
             raise TypeError("WebSocket received unexpected frame type: str")
         return msg
 
-    @overrides(BaseWebSocket)
-    async def send(self, data: str) -> None:
+    @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)
 
 
-Driver = combine_driver(BlockDriver, Mixin)
+if TYPE_CHECKING:
+
+    class Driver(Mixin, NoneDriver): ...
+
+else:
+    Driver = combine_driver(NoneDriver, Mixin)
+    """Websockets Driver"""

nonebot/exception.py

@@ -1,264 +1,244 @@
-"""
-异常
-====
+"""本模块包含了所有 NoneBot 运行时可能会抛出的异常。
 
-下列文档中的异常是所有 NoneBot 运行时可能会抛出的。
 这些异常并非所有需要用户处理，在 NoneBot 内部运行时被捕获，并进行对应操作。
+
+```bash
+NoneBotException
+├── ParserExit
+├── ProcessException
+|   ├── IgnoredException
+|   ├── SkippedException
+|   |   └── TypeMisMatch
+|   ├── MockApiException
+|   └── StopPropagation
+├── MatcherException
+|   ├── PausedException
+|   ├── RejectedException
+|   └── FinishedException
+├── AdapterException
+|   ├── NoLogException
+|   ├── ApiNotAvailable
+|   ├── NetworkError
+|   └── ActionFailed
+└── DriverException
+    └── WebSocketClosed
+```
+
+FrontMatter:
+    mdx:
+        format: md
+    sidebar_position: 10
+    description: nonebot.exception 模块
 """
 
 from typing import Any, Optional
 
-from pydantic.fields import ModelField
+from nonebot.compat import ModelField
 
 
 class NoneBotException(Exception):
-    """
-    :说明:
+    """所有 NoneBot 发生的异常基类。"""
 
-      所有 NoneBot 发生的异常基类。
-    """
+    def __str__(self) -> str:
+        return self.__repr__()
 
 
 # Rule Exception
 class ParserExit(NoneBotException):
-    """
-    :说明:
+    """{ref}`nonebot.rule.shell_command` 处理消息失败时返回的异常。"""
 
-      ``shell command`` 处理消息失败时返回的异常
-
-    :参数:
-
-      * ``status``
-      * ``message``
-    """
-
-    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
 
-    def __repr__(self):
-        return f"<ParserExit status={self.status} message={self.message}>"
-
-    def __str__(self):
-        return self.__repr__()
+    def __repr__(self) -> str:
+        return (
+            f"ParserExit(status={self.status}"
+            + (f", message={self.message!r}" if self.message else "")
+            + ")"
+        )
 
 
 # Processor Exception
 class ProcessException(NoneBotException):
-    """
-    :说明:
-
-      事件处理过程中发生的异常基类。
-    """
+    """事件处理过程中发生的异常基类。"""
 
 
 class IgnoredException(ProcessException):
-    """
-    :说明:
+    """指示 NoneBot 应该忽略该事件。可由 PreProcessor 抛出。
 
-      指示 NoneBot 应该忽略该事件。可由 PreProcessor 抛出。
-
-    :参数:
-
-      * ``reason``: 忽略事件的原因
+    参数:
+        reason: 忽略事件的原因
     """
 
-    def __init__(self, reason):
-        self.reason = reason
+    def __init__(self, reason: Any) -> None:
+        self.reason: Any = reason
 
-    def __repr__(self):
-        return f"<IgnoredException, reason={self.reason}>"
+    def __repr__(self) -> str:
+        return f"IgnoredException(reason={self.reason!r})"
 
-    def __str__(self):
-        return self.__repr__()
+
+class SkippedException(ProcessException):
+    """指示 NoneBot 立即结束当前 `Dependent` 的运行。
+
+    例如，可以在 `Handler` 中通过 {ref}`nonebot.matcher.Matcher.skip` 抛出。
+
+    用法:
+        ```python
+        def always_skip():
+            Matcher.skip()
+
+        @matcher.handle()
+        async def handler(dependency = Depends(always_skip)):
+            # never run
+        ```
+    """
+
+
+class TypeMisMatch(SkippedException):
+    """当前 `Handler` 的参数类型不匹配。"""
+
+    def __init__(self, param: ModelField, value: Any) -> None:
+        self.param: ModelField = param
+        self.value: Any = value
+
+    def __repr__(self) -> str:
+        return (
+            f"TypeMisMatch(param={self.param.name}, "
+            f"type={self.param._type_display()}, value={self.value!r}>"
+        )
 
 
 class MockApiException(ProcessException):
-    """
-    :说明:
+    """指示 NoneBot 阻止本次 API 调用或修改本次调用返回值，并返回自定义内容。
+    可由 api hook 抛出。
 
-      指示 NoneBot 阻止本次 API 调用或修改本次调用返回值，并返回自定义内容。可由 api hook 抛出。
-
-    :参数:
-
-      * ``result``: 返回的内容
+    参数:
+        result: 返回的内容
     """
 
     def __init__(self, result: Any):
         self.result = result
 
-    def __repr__(self):
-        return f"<ApiCancelledException, result={self.result}>"
-
-    def __str__(self):
-        return self.__repr__()
+    def __repr__(self) -> str:
+        return f"MockApiException(result={self.result!r})"
 
 
 class StopPropagation(ProcessException):
-    """
-    :说明:
+    """指示 NoneBot 终止事件向下层传播。
 
-      指示 NoneBot 终止事件向下层传播。
+    在 {ref}`nonebot.matcher.Matcher.block` 为 `True`
+    或使用 {ref}`nonebot.matcher.Matcher.stop_propagation` 方法时抛出。
 
-    :用法:
-
-      在 ``Matcher.block == True`` 时抛出。
+    用法:
+        ```python
+        matcher = on_notice(block=True)
+        # 或者
+        @matcher.handle()
+        async def handler(matcher: Matcher):
+            matcher.stop_propagation()
+        ```
     """
 
 
 # Matcher Exceptions
 class MatcherException(NoneBotException):
-    """
-    :说明:
-
-      所有 Matcher 发生的异常基类。
-    """
-
-
-class SkippedException(MatcherException):
-    """
-    :说明:
-
-      指示 NoneBot 立即结束当前 ``Handler`` 的处理，继续处理下一个 ``Handler``。
-
-    :用法:
-
-      可以在 ``Handler`` 中通过 ``Matcher.skip()`` 抛出。
-    """
-
-
-class TypeMisMatch(SkippedException):
-    """
-    :说明:
-
-      当前 ``Handler`` 的参数类型不匹配。
-    """
-
-    def __init__(self, param: ModelField, value: Any):
-        self.param: ModelField = param
-        self.value: Any = value
-
-    def __repr__(self):
-        return f"<TypeMisMatch, param={self.param}, value={self.value}>"
-
-    def __str__(self):
-        self.__repr__()
+    """所有 Matcher 发生的异常基类。"""
 
 
 class PausedException(MatcherException):
-    """
-    :说明:
+    """指示 NoneBot 结束当前 `Handler` 并等待下一条消息后继续下一个 `Handler`。
+    可用于用户输入新信息。
 
-      指示 NoneBot 结束当前 ``Handler`` 并等待下一条消息后继续下一个 ``Handler``。
-      可用于用户输入新信息。
+    可以在 `Handler` 中通过 {ref}`nonebot.matcher.Matcher.pause` 抛出。
 
-    :用法:
-
-      可以在 ``Handler`` 中通过 ``Matcher.pause()`` 抛出。
+    用法:
+        ```python
+        @matcher.handle()
+        async def handler():
+            await matcher.pause("some message")
+        ```
     """
 
 
 class RejectedException(MatcherException):
-    """
-    :说明:
+    """指示 NoneBot 结束当前 `Handler` 并等待下一条消息后重新运行当前 `Handler`。
+    可用于用户重新输入。
 
-      指示 NoneBot 结束当前 ``Handler`` 并等待下一条消息后重新运行当前 ``Handler``。
-      可用于用户重新输入。
+    可以在 `Handler` 中通过 {ref}`nonebot.matcher.Matcher.reject` 抛出。
 
-    :用法:
-
-      可以在 ``Handler`` 中通过 ``Matcher.reject()`` 抛出。
+    用法:
+        ```python
+        @matcher.handle()
+        async def handler():
+            await matcher.reject("some message")
+        ```
     """
 
 
 class FinishedException(MatcherException):
-    """
-    :说明:
+    """指示 NoneBot 结束当前 `Handler` 且后续 `Handler` 不再被运行。可用于结束用户会话。
 
-      指示 NoneBot 结束当前 ``Handler`` 且后续 ``Handler`` 不再被运行。
-      可用于结束用户会话。
+    可以在 `Handler` 中通过 {ref}`nonebot.matcher.Matcher.finish` 抛出。
 
-    :用法:
-
-      可以在 ``Handler`` 中通过 ``Matcher.finish()`` 抛出。
+    用法:
+        ```python
+        @matcher.handle()
+        async def handler():
+            await matcher.finish("some message")
+        ```
     """
 
 
 # Adapter Exceptions
 class AdapterException(NoneBotException):
-    """
-    :说明:
+    """代表 `Adapter` 抛出的异常，所有的 `Adapter` 都要在内部继承自这个 `Exception`。
 
-      代表 ``Adapter`` 抛出的异常，所有的 ``Adapter`` 都要在内部继承自这个 ``Exception``
-
-    :参数:
-
-      * ``adapter_name: str``: 标识 adapter
+    参数:
+        adapter_name: 标识 adapter
     """
 
-    def __init__(self, adapter_name: str) -> None:
-        self.adapter_name = adapter_name
+    def __init__(self, adapter_name: str, *args: object) -> None:
+        super().__init__(*args)
+        self.adapter_name: str = adapter_name
 
 
 class NoLogException(AdapterException):
-    """
-    :说明:
+    """指示 NoneBot 对当前 `Event` 进行处理但不显示 Log 信息。
 
-      指示 NoneBot 对当前 ``Event`` 进行处理但不显示 Log 信息，可在 ``get_log_string`` 时抛出
+    可在 {ref}`nonebot.adapters.Event.get_log_string` 时抛出
     """
 
-    pass
-
 
 class ApiNotAvailable(AdapterException):
-    """
-    :说明:
-
-      在 API 连接不可用时抛出。
-    """
-
-    pass
+    """在 API 连接不可用时抛出。"""
 
 
 class NetworkError(AdapterException):
+    """在网络出现问题时抛出，
+    如: API 请求地址不正确, API 请求无返回或返回状态非正常等。
     """
-    :说明:
-
-      在网络出现问题时抛出，如: API 请求地址不正确, API 请求无返回或返回状态非正常等。
-    """
-
-    pass
 
 
 class ActionFailed(AdapterException):
-    """
-    :说明:
-
-      API 请求成功返回数据，但 API 操作失败。
-    """
-
-    pass
+    """API 请求成功返回数据，但 API 操作失败。"""
 
 
 # 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
 
     def __repr__(self) -> str:
-        return f"<WebSocketClosed code={self.code} reason={self.reason}>"
+        return (
+            f"WebSocketClosed(code={self.code}"
+            + (f", reason={self.reason!r}" if self.reason else "")
+            + ")"
+        )

nonebot/internal/adapter/__init__.py

@@ -0,0 +1,6 @@
+from .adapter import Adapter as Adapter
+from .bot import Bot as Bot
+from .event import Event as Event
+from .message import Message as Message
+from .message import MessageSegment as MessageSegment
+from .template import MessageTemplate as MessageTemplate

nonebot/internal/adapter/adapter.py

@@ -0,0 +1,116 @@
+import abc
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Any
+
+from nonebot.config import Config
+from nonebot.internal.driver import (
+    ASGIMixin,
+    Driver,
+    HTTPClientMixin,
+    HTTPServerSetup,
+    Request,
+    Response,
+    WebSocket,
+    WebSocketClientMixin,
+    WebSocketServerSetup,
+)
+from nonebot.internal.driver._lifespan import LIFESPAN_FUNC
+
+from .bot import Bot
+
+
+class Adapter(abc.ABC):
+    """协议适配器基类。
+
+    通常，在 Adapter 中编写协议通信相关代码，如: 建立通信连接、处理接收与发送 data 等。
+
+    参数:
+        driver: {ref}`nonebot.drivers.Driver` 实例
+        kwargs: 其他由 {ref}`nonebot.drivers.Driver.register_adapter` 传入的额外参数
+    """
+
+    def __init__(self, driver: Driver, **kwargs: Any):
+        self.driver: Driver = driver
+        """{ref}`nonebot.drivers.Driver` 实例"""
+        self.bots: dict[str, Bot] = {}
+        """本协议适配器已建立连接的 {ref}`nonebot.adapters.Bot` 实例"""
+
+    def __repr__(self) -> str:
+        return f"Adapter(name={self.get_name()!r})"
+
+    @classmethod
+    @abc.abstractmethod
+    def get_name(cls) -> str:
+        """当前协议适配器的名称"""
+        raise NotImplementedError
+
+    @property
+    def config(self) -> Config:
+        """全局 NoneBot 配置"""
+        return self.driver.config
+
+    def bot_connect(self, bot: Bot) -> None:
+        """告知 NoneBot 建立了一个新的 {ref}`nonebot.adapters.Bot` 连接。
+
+        当有新的 {ref}`nonebot.adapters.Bot` 实例连接建立成功时调用。
+
+        参数:
+            bot: {ref}`nonebot.adapters.Bot` 实例
+        """
+        self.driver._bot_connect(bot)
+        self.bots[bot.self_id] = bot
+
+    def bot_disconnect(self, bot: Bot) -> None:
+        """告知 NoneBot {ref}`nonebot.adapters.Bot` 连接已断开。
+
+        当有 {ref}`nonebot.adapters.Bot` 实例连接断开时调用。
+
+        参数:
+            bot: {ref}`nonebot.adapters.Bot` 实例
+        """
+        if self.bots.pop(bot.self_id, None) is None:
+            raise RuntimeError(f"{bot} not found in adapter {self.get_name()}")
+        self.driver._bot_disconnect(bot)
+
+    def setup_http_server(self, setup: HTTPServerSetup):
+        """设置一个 HTTP 服务器路由配置"""
+        if not isinstance(self.driver, ASGIMixin):
+            raise TypeError("Current driver does not support http server")
+        self.driver.setup_http_server(setup)
+
+    def setup_websocket_server(self, setup: WebSocketServerSetup):
+        """设置一个 WebSocket 服务器路由配置"""
+        if not isinstance(self.driver, ASGIMixin):
+            raise TypeError("Current driver does not support websocket server")
+        self.driver.setup_websocket_server(setup)
+
+    async def request(self, setup: Request) -> Response:
+        """进行一个 HTTP 客户端请求"""
+        if not isinstance(self.driver, HTTPClientMixin):
+            raise TypeError("Current driver does not support http client")
+        return await self.driver.request(setup)
+
+    @asynccontextmanager
+    async def websocket(self, setup: Request) -> AsyncGenerator[WebSocket, None]:
+        """建立一个 WebSocket 客户端连接请求"""
+        if not isinstance(self.driver, WebSocketClientMixin):
+            raise TypeError("Current driver does not support websocket client")
+        async with self.driver.websocket(setup) as ws:
+            yield ws
+
+    def on_ready(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
+        return self.driver._lifespan.on_ready(func)
+
+    @abc.abstractmethod
+    async def _call_api(self, bot: Bot, api: str, **data: Any) -> Any:
+        """`Adapter` 实际调用 api 的逻辑实现函数，实现该方法以调用 api。
+
+        参数:
+            api: API 名称
+            data: API 数据
+        """
+        raise NotImplementedError
+
+
+__autodoc__ = {"Adapter._call_api": True}

nonebot/internal/adapter/bot.py

@@ -0,0 +1,221 @@
+import abc
+from functools import partial
+from typing import TYPE_CHECKING, Any, ClassVar, Optional, Protocol, Union
+
+import anyio
+from exceptiongroup import BaseExceptionGroup, catch
+
+from nonebot.config import Config
+from nonebot.exception import MockApiException
+from nonebot.log import logger
+from nonebot.typing import T_CalledAPIHook, T_CallingAPIHook
+from nonebot.utils import flatten_exception_group
+
+if TYPE_CHECKING:
+    from .adapter import Adapter
+    from .event import Event
+    from .message import Message, MessageSegment
+
+    class _ApiCall(Protocol):
+        async def __call__(self, **kwargs: Any) -> Any: ...
+
+
+class Bot(abc.ABC):
+    """Bot 基类。
+
+    用于处理上报消息，并提供 API 调用接口。
+
+    参数:
+        adapter: 协议适配器实例
+        self_id: 机器人 ID
+    """
+
+    _calling_api_hook: ClassVar[set[T_CallingAPIHook]] = set()
+    """call_api 时执行的函数"""
+    _called_api_hook: ClassVar[set[T_CalledAPIHook]] = set()
+    """call_api 后执行的函数"""
+
+    def __init__(self, adapter: "Adapter", self_id: str):
+        self.adapter: "Adapter" = adapter
+        """协议适配器实例"""
+        self.self_id: str = self_id
+        """机器人 ID"""
+
+    def __repr__(self) -> str:
+        return f"Bot(type={self.type!r}, self_id={self.self_id!r})"
+
+    def __getattr__(self, name: str) -> "_ApiCall":
+        if name.startswith("__") and name.endswith("__"):
+            raise AttributeError(
+                f"'{self.__class__.__name__}' object has no attribute '{name}'"
+            )
+        return partial(self.call_api, name)
+
+    @property
+    def type(self) -> str:
+        """协议适配器名称"""
+        return self.adapter.get_name()
+
+    @property
+    def config(self) -> Config:
+        """全局 NoneBot 配置"""
+        return self.adapter.config
+
+    async def call_api(self, api: str, **data: Any) -> Any:
+        """调用机器人 API 接口，可以通过该函数或直接通过 bot 属性进行调用
+
+        参数:
+            api: API 名称
+            data: API 数据
+
+        用法:
+            ```python
+            await bot.call_api("send_msg", message="hello world")
+            await bot.send_msg(message="hello world")
+            ```
+        """
+
+        result: Any = None
+        skip_calling_api: bool = False
+        exception: Optional[Exception] = None
+
+        if self._calling_api_hook:
+            logger.debug("Running CallingAPI hooks...")
+
+            def _handle_mock_api_exception(
+                exc_group: BaseExceptionGroup[MockApiException],
+            ) -> None:
+                nonlocal skip_calling_api, result
+
+                excs = [
+                    exc
+                    for exc in flatten_exception_group(exc_group)
+                    if isinstance(exc, MockApiException)
+                ]
+                if not excs:
+                    return
+                elif len(excs) > 1:
+                    logger.warning(
+                        "Multiple hooks want to mock API result. Use the first one."
+                    )
+
+                skip_calling_api = True
+                result = excs[0].result
+
+                logger.debug(
+                    f"Calling API {api} is cancelled. Return {result!r} instead."
+                )
+
+            def _handle_exception(exc_group: BaseExceptionGroup[Exception]) -> None:
+                for exc in flatten_exception_group(exc_group):
+                    logger.opt(colors=True, exception=exc).error(
+                        "<r><bg #f8bbd0>Error when running CallingAPI hook. "
+                        "Running cancelled!</bg #f8bbd0></r>"
+                    )
+
+            with catch(
+                {
+                    MockApiException: _handle_mock_api_exception,
+                    Exception: _handle_exception,
+                }
+            ):
+                async with anyio.create_task_group() as tg:
+                    for hook in self._calling_api_hook:
+                        tg.start_soon(hook, self, api, data)
+
+        if not skip_calling_api:
+            try:
+                result = await self.adapter._call_api(self, api, **data)
+            except Exception as e:
+                exception = e
+
+        if self._called_api_hook:
+            logger.debug("Running CalledAPI hooks...")
+
+            def _handle_mock_api_exception(
+                exc_group: BaseExceptionGroup[MockApiException],
+            ) -> None:
+                nonlocal result, exception
+
+                excs = [
+                    exc
+                    for exc in flatten_exception_group(exc_group)
+                    if isinstance(exc, MockApiException)
+                ]
+                if not excs:
+                    return
+                elif len(excs) > 1:
+                    logger.warning(
+                        "Multiple hooks want to mock API result. Use the first one."
+                    )
+
+                result = excs[0].result
+                exception = None
+                logger.debug(
+                    f"Calling API {api} result is mocked. Return {result} instead."
+                )
+
+            def _handle_exception(exc_group: BaseExceptionGroup[Exception]) -> None:
+                for exc in flatten_exception_group(exc_group):
+                    logger.opt(colors=True, exception=exc).error(
+                        "<r><bg #f8bbd0>Error when running CalledAPI hook. "
+                        "Running cancelled!</bg #f8bbd0></r>"
+                    )
+
+            with catch(
+                {
+                    MockApiException: _handle_mock_api_exception,
+                    Exception: _handle_exception,
+                }
+            ):
+                async with anyio.create_task_group() as tg:
+                    for hook in self._called_api_hook:
+                        tg.start_soon(hook, self, exception, api, data, result)
+
+        if exception:
+            raise exception
+        return result
+
+    @abc.abstractmethod
+    async def send(
+        self,
+        event: "Event",
+        message: Union[str, "Message", "MessageSegment"],
+        **kwargs: Any,
+    ) -> Any:
+        """调用机器人基础发送消息接口
+
+        参数:
+            event: 上报事件
+            message: 要发送的消息
+            kwargs: 任意额外参数
+        """
+        raise NotImplementedError
+
+    @classmethod
+    def on_calling_api(cls, func: T_CallingAPIHook) -> T_CallingAPIHook:
+        """调用 api 预处理。
+
+        钩子函数参数:
+
+        - bot: 当前 bot 对象
+        - api: 调用的 api 名称
+        - data: api 调用的参数字典
+        """
+        cls._calling_api_hook.add(func)
+        return func
+
+    @classmethod
+    def on_called_api(cls, func: T_CalledAPIHook) -> T_CalledAPIHook:
+        """调用 api 后处理。
+
+        钩子函数参数:
+
+        - bot: 当前 bot 对象
+        - exception: 调用 api 时发生的错误
+        - api: 调用的 api 名称
+        - data: api 调用的参数字典
+        - result: api 调用的返回
+        """
+        cls._called_api_hook.add(func)
+        return func

nonebot/internal/adapter/event.py

@@ -0,0 +1,89 @@
+import abc
+from typing import Any, TypeVar
+
+from pydantic import BaseModel
+
+from nonebot.compat import PYDANTIC_V2, ConfigDict
+from nonebot.utils import DataclassEncoder
+
+from .message import Message
+
+E = TypeVar("E", bound="Event")
+
+
+class Event(abc.ABC, BaseModel):
+    """Event 基类。提供获取关键信息的方法，其余信息可直接获取。"""
+
+    if PYDANTIC_V2:  # pragma: pydantic-v2
+        model_config = ConfigDict(extra="allow")
+    else:  # pragma: pydantic-v1
+
+        class Config(ConfigDict):
+            extra = "allow"  # type: ignore
+            json_encoders = {Message: DataclassEncoder}  # noqa: RUF012
+
+    if not PYDANTIC_V2:  # pragma: pydantic-v1
+
+        @classmethod
+        def validate(cls: type["E"], value: Any) -> "E":
+            if isinstance(value, Event) and not isinstance(value, cls):
+                raise TypeError(f"{value} is incompatible with Event type {cls}")
+            return super().validate(value)
+
+    @abc.abstractmethod
+    def get_type(self) -> str:
+        """获取事件类型的方法，类型通常为 NoneBot 内置的四种类型。"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_event_name(self) -> str:
+        """获取事件名称的方法。"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_event_description(self) -> str:
+        """获取事件描述的方法，通常为事件具体内容。"""
+        raise NotImplementedError
+
+    def __str__(self) -> str:
+        return f"[{self.get_event_name()}]: {self.get_event_description()}"
+
+    def get_log_string(self) -> str:
+        """获取事件日志信息的方法。
+
+        通常你不需要修改这个方法，只有当希望 NoneBot 隐藏该事件日志时，
+        可以抛出 `NoLogException` 异常。
+
+        异常:
+            NoLogException: 希望 NoneBot 隐藏该事件日志
+        """
+        return f"[{self.get_event_name()}]: {self.get_event_description()}"
+
+    @abc.abstractmethod
+    def get_user_id(self) -> str:
+        """获取事件主体 id 的方法，通常是用户 id 。"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_session_id(self) -> str:
+        """获取会话 id 的方法，用于判断当前事件属于哪一个会话，
+        通常是用户 id、群组 id 组合。
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_message(self) -> "Message":
+        """获取事件消息内容的方法。"""
+        raise NotImplementedError
+
+    def get_plaintext(self) -> str:
+        """获取消息纯文本的方法。
+
+        通常不需要修改，默认通过 `get_message().extract_plain_text` 获取。
+        """
+        return self.get_message().extract_plain_text()
+
+    @abc.abstractmethod
+    def is_tome(self) -> bool:
+        """获取事件是否与机器人有关的方法。"""
+        raise NotImplementedError

nonebot/internal/adapter/message.py

@@ -0,0 +1,442 @@
+import abc
+from collections.abc import Iterable
+from copy import deepcopy
+from dataclasses import asdict, dataclass, field
+from typing import (  # noqa: UP035
+    Any,
+    Generic,
+    Optional,
+    SupportsIndex,
+    Type,
+    TypeVar,
+    Union,
+    overload,
+)
+from typing_extensions import Self
+
+from nonebot.compat import custom_validation, type_validate_python
+
+from .template import MessageTemplate
+
+TMS = TypeVar("TMS", bound="MessageSegment")
+TM = TypeVar("TM", bound="Message")
+
+
+@custom_validation
+@dataclass
+class MessageSegment(abc.ABC, Generic[TM]):
+    """消息段基类"""
+
+    type: str
+    """消息段类型"""
+    data: dict[str, Any] = field(default_factory=dict)
+    """消息段数据"""
+
+    @classmethod
+    @abc.abstractmethod
+    def get_message_class(cls) -> Type[TM]:  # noqa: UP006
+        """获取消息数组类型"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __str__(self) -> str:
+        """该消息段所代表的 str，在命令匹配部分使用"""
+        raise NotImplementedError
+
+    def __len__(self) -> int:
+        return len(str(self))
+
+    def __ne__(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self, other: Self
+    ) -> bool:
+        return not self == other
+
+    def __add__(self, other: Union[str, Self, Iterable[Self]]) -> TM:
+        return self.get_message_class()(self) + other
+
+    def __radd__(self, other: Union[str, Self, Iterable[Self]]) -> TM:
+        return self.get_message_class()(other) + self
+
+    @classmethod
+    def __get_validators__(cls):
+        yield cls._validate
+
+    @classmethod
+    def _validate(cls, value) -> Self:
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, MessageSegment):
+            raise ValueError(f"Type {type(value)} can not be converted to {cls}")
+        if not isinstance(value, dict):
+            raise ValueError(f"Expected dict for MessageSegment, got {type(value)}")
+        if "type" not in value:
+            raise ValueError(
+                f"Expected dict with 'type' for MessageSegment, got {value}"
+            )
+        return cls(type=value["type"], data=value.get("data", {}))
+
+    def get(self, key: str, default: Any = None):
+        return asdict(self).get(key, default)
+
+    def keys(self):
+        return asdict(self).keys()
+
+    def values(self):
+        return asdict(self).values()
+
+    def items(self):
+        return asdict(self).items()
+
+    def join(self, iterable: Iterable[Union[Self, TM]]) -> TM:
+        return self.get_message_class()(self).join(iterable)
+
+    def copy(self) -> Self:
+        return deepcopy(self)
+
+    @abc.abstractmethod
+    def is_text(self) -> bool:
+        """当前消息段是否为纯文本"""
+        raise NotImplementedError
+
+
+@custom_validation
+class Message(list[TMS], abc.ABC):
+    """消息序列
+
+    参数:
+        message: 消息内容
+    """
+
+    def __init__(
+        self,
+        message: Union[str, None, Iterable[TMS], TMS] = None,
+    ):
+        super().__init__()
+        if message is None:
+            return
+        elif isinstance(message, str):
+            self.extend(self._construct(message))
+        elif isinstance(message, MessageSegment):
+            self.append(message)
+        elif isinstance(message, Iterable):
+            self.extend(message)
+        else:
+            self.extend(self._construct(message))  # pragma: no cover
+
+    @classmethod
+    def template(cls, format_string: Union[str, TM]) -> MessageTemplate[Self]:
+        """创建消息模板。
+
+        用法和 `str.format` 大致相同，支持以 `Message` 对象作为消息模板并输出消息对象。
+        并且提供了拓展的格式化控制符，
+        可以通过该消息类型的 `MessageSegment` 工厂方法创建消息。
+
+        参数:
+            format_string: 格式化模板
+
+        返回:
+            消息格式化器
+        """
+        return MessageTemplate(format_string, cls)
+
+    @classmethod
+    @abc.abstractmethod
+    def get_segment_class(cls) -> type[TMS]:
+        """获取消息段类型"""
+        raise NotImplementedError
+
+    def __str__(self) -> str:
+        return "".join(str(seg) for seg in self)
+
+    @classmethod
+    def __get_validators__(cls):
+        yield cls._validate
+
+    @classmethod
+    def _validate(cls, value) -> Self:
+        if isinstance(value, cls):
+            return value
+        elif isinstance(value, Message):
+            raise ValueError(f"Type {type(value)} can not be converted to {cls}")
+        elif isinstance(value, str):
+            pass
+        elif isinstance(value, dict):
+            value = type_validate_python(cls.get_segment_class(), value)
+        elif isinstance(value, Iterable):
+            value = [type_validate_python(cls.get_segment_class(), v) for v in value]
+        else:
+            raise ValueError(
+                f"Expected str, dict or iterable for Message, got {type(value)}"
+            )
+        return cls(value)
+
+    @staticmethod
+    @abc.abstractmethod
+    def _construct(msg: str) -> Iterable[TMS]:
+        """构造消息数组"""
+        raise NotImplementedError
+
+    def __add__(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self, other: Union[str, TMS, Iterable[TMS]]
+    ) -> Self:
+        result = self.copy()
+        result += other
+        return result
+
+    def __radd__(self, other: Union[str, TMS, Iterable[TMS]]) -> Self:
+        result = self.__class__(other)
+        return result + self
+
+    def __iadd__(self, other: Union[str, TMS, Iterable[TMS]]) -> Self:
+        if isinstance(other, str):
+            self.extend(self._construct(other))
+        elif isinstance(other, MessageSegment):
+            self.append(other)
+        elif isinstance(other, Iterable):
+            self.extend(other)
+        else:
+            raise TypeError(f"Unsupported type {type(other)!r}")
+        return self
+
+    @overload
+    def __getitem__(self, args: str) -> Self:
+        """获取仅包含指定消息段类型的消息
+
+        参数:
+            args: 消息段类型
+
+        返回:
+            所有类型为 `args` 的消息段
+        """
+
+    @overload
+    def __getitem__(self, args: tuple[str, int]) -> TMS:
+        """索引指定类型的消息段
+
+        参数:
+            args: 消息段类型和索引
+
+        返回:
+            类型为 `args[0]` 的消息段第 `args[1]` 个
+        """
+
+    @overload
+    def __getitem__(self, args: tuple[str, slice]) -> Self:
+        """切片指定类型的消息段
+
+        参数:
+            args: 消息段类型和切片
+
+        返回:
+            类型为 `args[0]` 的消息段切片 `args[1]`
+        """
+
+    @overload
+    def __getitem__(self, args: int) -> TMS:
+        """索引消息段
+
+        参数:
+            args: 索引
+
+        返回:
+            第 `args` 个消息段
+        """
+
+    @overload
+    def __getitem__(self, args: slice) -> Self:
+        """切片消息段
+
+        参数:
+            args: 切片
+
+        返回:
+            消息切片 `args`
+        """
+
+    def __getitem__(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self,
+        args: Union[
+            str,
+            tuple[str, int],
+            tuple[str, slice],
+            int,
+            slice,
+        ],
+    ) -> Union[TMS, Self]:
+        arg1, arg2 = args if isinstance(args, tuple) else (args, None)
+        if isinstance(arg1, int) and arg2 is None:
+            return super().__getitem__(arg1)
+        elif isinstance(arg1, slice) and arg2 is None:
+            return self.__class__(super().__getitem__(arg1))
+        elif isinstance(arg1, str) and arg2 is None:
+            return self.__class__(seg for seg in self if seg.type == arg1)
+        elif isinstance(arg1, str) and isinstance(arg2, int):
+            return [seg for seg in self if seg.type == arg1][arg2]
+        elif isinstance(arg1, str) and isinstance(arg2, slice):
+            return self.__class__([seg for seg in self if seg.type == arg1][arg2])
+        else:
+            raise ValueError("Incorrect arguments to slice")  # pragma: no cover
+
+    def __contains__(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self, value: Union[TMS, str]
+    ) -> bool:
+        """检查消息段是否存在
+
+        参数:
+            value: 消息段或消息段类型
+        返回:
+            消息内是否存在给定消息段或给定类型的消息段
+        """
+        if isinstance(value, str):
+            return next((seg for seg in self if seg.type == value), None) is not None
+        return super().__contains__(value)
+
+    def has(self, value: Union[TMS, str]) -> bool:
+        """与 {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!r} is not in message")
+            return super().index(first_segment, *args)
+        return super().index(value, *args)
+
+    def get(self, type_: str, count: Optional[int] = None) -> Self:
+        """获取指定类型的消息段
+
+        参数:
+            type_: 消息段类型
+            count: 获取个数
+
+        返回:
+            构建的新消息
+        """
+        if count is None:
+            return self[type_]
+
+        iterator, filtered = (
+            (seg for seg in self if seg.type == type_),
+            self.__class__(),
+        )
+        for _ in range(count):
+            seg = next(iterator, None)
+            if seg is None:
+                break
+            filtered.append(seg)
+        return filtered
+
+    def count(self, value: Union[TMS, str]) -> int:
+        """计算指定消息段的个数
+
+        参数:
+            value: 消息段或消息段类型
+
+        返回:
+            个数
+        """
+        return len(self[value]) if isinstance(value, str) else super().count(value)
+
+    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(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self, obj: Union[str, TMS]
+    ) -> Self:
+        """添加一个消息段到消息数组末尾。
+
+        参数:
+            obj: 要添加的消息段
+        """
+        if isinstance(obj, MessageSegment):
+            super().append(obj)
+        elif isinstance(obj, str):
+            self.extend(self._construct(obj))
+        else:
+            raise ValueError(f"Unexpected type: {type(obj)} {obj}")  # pragma: no cover
+        return self
+
+    def extend(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self, obj: Union[Self, Iterable[TMS]]
+    ) -> Self:
+        """拼接一个消息数组或多个消息段到消息数组末尾。
+
+        参数:
+            obj: 要添加的消息数组
+        """
+        for segment in obj:
+            self.append(segment)
+        return self
+
+    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())

nonebot/internal/adapter/template.py

@@ -0,0 +1,211 @@
+from _string import formatter_field_name_split  # type: ignore
+from collections.abc import Mapping, Sequence
+import functools
+from string import Formatter
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Generic,
+    Optional,
+    TypeVar,
+    Union,
+    cast,
+    overload,
+)
+from typing_extensions import TypeAlias
+
+if TYPE_CHECKING:
+    from .message import Message, MessageSegment
+
+    def formatter_field_name_split(
+        field_name: str,
+    ) -> tuple[str, list[tuple[bool, str]]]: ...
+
+
+TM = TypeVar("TM", bound="Message")
+TF = TypeVar("TF", str, "Message")
+
+FormatSpecFunc: TypeAlias = Callable[[Any], str]
+FormatSpecFunc_T = TypeVar("FormatSpecFunc_T", bound=FormatSpecFunc)
+
+
+class MessageTemplate(Formatter, Generic[TF]):
+    """消息模板格式化实现类。
+
+    参数:
+        template: 模板
+        factory: 消息类型工厂，默认为 `str`
+        private_getattr: 是否允许在模板中访问私有属性，默认为 `False`
+    """
+
+    @overload
+    def __init__(
+        self: "MessageTemplate[str]",
+        template: str,
+        factory: type[str] = str,
+        private_getattr: bool = False,
+    ) -> None: ...
+
+    @overload
+    def __init__(
+        self: "MessageTemplate[TM]",
+        template: Union[str, TM],
+        factory: type[TM],
+        private_getattr: bool = False,
+    ) -> None: ...
+
+    def __init__(
+        self,
+        template: Union[str, TM],
+        factory: Union[type[str], type[TM]] = str,
+        private_getattr: bool = False,
+    ) -> None:
+        self.template: TF = template  # type: ignore
+        self.factory: type[TF] = factory  # type: ignore
+        self.format_specs: dict[str, FormatSpecFunc] = {}
+        self.private_getattr = private_getattr
+
+    def __repr__(self) -> str:
+        return f"MessageTemplate({self.template!r}, factory={self.factory!r})"
+
+    def add_format_spec(
+        self, spec: FormatSpecFunc_T, name: Optional[str] = None
+    ) -> FormatSpecFunc_T:
+        name = name or spec.__name__
+        if name in self.format_specs:
+            raise ValueError(f"Format spec {name} already exists!")
+        self.format_specs[name] = spec
+        return spec
+
+    def format(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self, *args, **kwargs
+    ) -> TF:
+        """根据传入参数和模板生成消息对象"""
+        return self._format(args, kwargs)
+
+    def format_map(self, mapping: Mapping[str, Any]) -> TF:
+        """根据传入字典和模板生成消息对象, 在传入字段名不是有效标识符时有用"""
+        return self._format([], mapping)
+
+    def _format(self, args: Sequence[Any], kwargs: Mapping[str, Any]) -> TF:
+        full_message = self.factory()
+        used_args, arg_index = set(), 0
+
+        if isinstance(self.template, str):
+            msg, arg_index = self._vformat(
+                self.template, args, kwargs, used_args, arg_index
+            )
+            full_message += msg
+        elif isinstance(self.template, self.factory):
+            template = cast("Message[MessageSegment]", self.template)
+            for seg in template:
+                if not seg.is_text():
+                    full_message += seg
+                else:
+                    msg, arg_index = self._vformat(
+                        str(seg), args, kwargs, used_args, arg_index
+                    )
+                    full_message += msg
+        else:
+            raise TypeError("template must be a string or instance of Message!")
+
+        self.check_unused_args(used_args, args, kwargs)
+        return cast(TF, full_message)
+
+    def vformat(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self,
+        format_string: str,
+        args: Sequence[Any],
+        kwargs: Mapping[str, Any],
+    ) -> TF:
+        raise NotImplementedError("`vformat` has merged into `_format`")
+
+    def _vformat(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self,
+        format_string: str,
+        args: Sequence[Any],
+        kwargs: Mapping[str, Any],
+        used_args: set[Union[int, str]],
+        auto_arg_index: int = 0,
+    ) -> tuple[TF, int]:
+        results: list[Any] = [self.factory()]
+
+        for literal_text, field_name, format_spec, conversion in self.parse(
+            format_string
+        ):
+            # output the literal text
+            if literal_text:
+                results.append(literal_text)
+
+            # if there's a field, output it
+            if field_name is not None:
+                # this is some markup, find the object and do
+                #  the formatting
+
+                # handle arg indexing when empty field_names are given.
+                if field_name == "":
+                    if auto_arg_index is False:
+                        raise ValueError(
+                            "cannot switch from manual field specification to "
+                            "automatic field numbering"
+                        )
+                    field_name = str(auto_arg_index)
+                    auto_arg_index += 1
+                elif field_name.isdigit():
+                    if auto_arg_index:
+                        raise ValueError(
+                            "cannot switch from manual field specification to "
+                            "automatic field numbering"
+                        )
+                    # disable auto arg incrementing, if it gets
+                    # used later on, then an exception will be raised
+                    auto_arg_index = False
+
+                # given the field_name, find the object it references
+                #  and the argument it came from
+                obj, arg_used = self.get_field(field_name, args, kwargs)
+                used_args.add(arg_used)
+
+                # do any conversion on the resulting object
+                obj = self.convert_field(obj, conversion) if conversion else obj
+
+                # format the object and append to the result
+                formatted_text = (
+                    self.format_field(obj, format_spec) if format_spec else obj
+                )
+                results.append(formatted_text)
+
+        return functools.reduce(self._add, results), auto_arg_index
+
+    def get_field(
+        self, field_name: str, args: Sequence[Any], kwargs: Mapping[str, Any]
+    ) -> tuple[Any, Union[int, str]]:
+        first, rest = formatter_field_name_split(field_name)
+        obj = self.get_value(first, args, kwargs)
+
+        for is_attr, value in rest:
+            if not self.private_getattr and value.startswith("_"):
+                raise ValueError("Cannot access private attribute")
+            obj = getattr(obj, value) if is_attr else obj[value]
+
+        return obj, first
+
+    def format_field(self, value: Any, format_spec: str) -> Any:
+        formatter: Optional[FormatSpecFunc] = self.format_specs.get(format_spec)
+        if formatter is None and not issubclass(self.factory, str):
+            segment_class: type["MessageSegment"] = self.factory.get_segment_class()
+            method = getattr(segment_class, format_spec, None)
+            if callable(method) and not cast(str, method.__name__).startswith("_"):
+                formatter = getattr(segment_class, format_spec)
+        return (
+            super().format_field(value, format_spec)
+            if formatter is None
+            else formatter(value)
+        )
+
+    def _add(self, a: Any, b: Any) -> Any:
+        try:
+            return a + b
+        except TypeError:
+            return a + str(b)

nonebot/internal/driver/__init__.py

@@ -0,0 +1,33 @@
+from .abstract import ASGIMixin as ASGIMixin
+from .abstract import Driver as Driver
+from .abstract import ForwardDriver as ForwardDriver
+from .abstract import ForwardMixin as ForwardMixin
+from .abstract import HTTPClientMixin as HTTPClientMixin
+from .abstract import HTTPClientSession as HTTPClientSession
+from .abstract import Mixin as Mixin
+from .abstract import ReverseDriver as ReverseDriver
+from .abstract import ReverseMixin as ReverseMixin
+from .abstract import WebSocketClientMixin as WebSocketClientMixin
+from .combine import combine_driver as combine_driver
+from .model import URL as URL
+from .model import ContentTypes as ContentTypes
+from .model import Cookies as Cookies
+from .model import CookieTypes as CookieTypes
+from .model import DataTypes as DataTypes
+from .model import FileContent as FileContent
+from .model import FilesTypes as FilesTypes
+from .model import FileType as FileType
+from .model import FileTypes as FileTypes
+from .model import HeaderTypes as HeaderTypes
+from .model import HTTPServerSetup as HTTPServerSetup
+from .model import HTTPVersion as HTTPVersion
+from .model import QueryTypes as QueryTypes
+from .model import QueryVariable as QueryVariable
+from .model import RawURL as RawURL
+from .model import Request as Request
+from .model import Response as Response
+from .model import SimpleQuery as SimpleQuery
+from .model import Timeout as Timeout
+from .model import TimeoutTypes as TimeoutTypes
+from .model import WebSocket as WebSocket
+from .model import WebSocketServerSetup as WebSocketServerSetup

nonebot/internal/driver/_lifespan.py

@@ -0,0 +1,100 @@
+from collections.abc import Awaitable, Iterable
+from types import TracebackType
+from typing import Any, Callable, Optional, Union, cast
+from typing_extensions import TypeAlias
+
+import anyio
+from anyio.abc import TaskGroup
+from exceptiongroup import suppress
+
+from nonebot.utils import is_coroutine_callable, run_sync
+
+SYNC_LIFESPAN_FUNC: TypeAlias = Callable[[], Any]
+ASYNC_LIFESPAN_FUNC: TypeAlias = Callable[[], Awaitable[Any]]
+LIFESPAN_FUNC: TypeAlias = Union[SYNC_LIFESPAN_FUNC, ASYNC_LIFESPAN_FUNC]
+
+
+class Lifespan:
+    def __init__(self) -> None:
+        self._task_group: Optional[TaskGroup] = None
+
+        self._startup_funcs: list[LIFESPAN_FUNC] = []
+        self._ready_funcs: list[LIFESPAN_FUNC] = []
+        self._shutdown_funcs: list[LIFESPAN_FUNC] = []
+
+    @property
+    def task_group(self) -> TaskGroup:
+        if self._task_group is None:
+            raise RuntimeError("Lifespan not started")
+        return self._task_group
+
+    @task_group.setter
+    def task_group(self, task_group: TaskGroup) -> None:
+        if self._task_group is not None:
+            raise RuntimeError("Lifespan already started")
+        self._task_group = task_group
+
+    def on_startup(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
+        self._startup_funcs.append(func)
+        return func
+
+    def on_shutdown(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
+        self._shutdown_funcs.append(func)
+        return func
+
+    def on_ready(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
+        self._ready_funcs.append(func)
+        return func
+
+    @staticmethod
+    async def _run_lifespan_func(
+        funcs: Iterable[LIFESPAN_FUNC],
+    ) -> None:
+        for func in funcs:
+            if is_coroutine_callable(func):
+                await cast(ASYNC_LIFESPAN_FUNC, func)()
+            else:
+                await run_sync(cast(SYNC_LIFESPAN_FUNC, func))()
+
+    async def startup(self) -> None:
+        # create background task group
+        self.task_group = anyio.create_task_group()
+        await self.task_group.__aenter__()
+
+        # run startup funcs
+        if self._startup_funcs:
+            await self._run_lifespan_func(self._startup_funcs)
+
+        # run ready funcs
+        if self._ready_funcs:
+            await self._run_lifespan_func(self._ready_funcs)
+
+    async def shutdown(
+        self,
+        *,
+        exc_type: Optional[type[BaseException]] = None,
+        exc_val: Optional[BaseException] = None,
+        exc_tb: Optional[TracebackType] = None,
+    ) -> None:
+        if self._shutdown_funcs:
+            # reverse shutdown funcs to ensure stack order
+            await self._run_lifespan_func(reversed(self._shutdown_funcs))
+
+        # shutdown background task group
+        self.task_group.cancel_scope.cancel()
+
+        with suppress(Exception):
+            await self.task_group.__aexit__(exc_type, exc_val, exc_tb)
+
+        self._task_group = None
+
+    async def __aenter__(self) -> None:
+        await self.startup()
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        await self.shutdown(exc_type=exc_type, exc_val=exc_val, exc_tb=exc_tb)

nonebot/internal/driver/abstract.py

@@ -0,0 +1,376 @@
+import abc
+from collections.abc import AsyncGenerator
+from contextlib import AsyncExitStack, asynccontextmanager
+from types import TracebackType
+from typing import TYPE_CHECKING, Any, ClassVar, Optional, Union
+from typing_extensions import Self, TypeAlias
+
+from anyio import CancelScope, create_task_group
+from anyio.abc import TaskGroup
+from exceptiongroup import BaseExceptionGroup, catch
+
+from nonebot.config import Config, Env
+from nonebot.dependencies import Dependent
+from nonebot.exception import SkippedException
+from nonebot.internal.params import BotParam, DefaultParam, DependParam
+from nonebot.log import logger
+from nonebot.typing import (
+    T_BotConnectionHook,
+    T_BotDisconnectionHook,
+    T_DependencyCache,
+)
+from nonebot.utils import escape_tag, flatten_exception_group, run_coro_with_catch
+
+from ._lifespan import LIFESPAN_FUNC, Lifespan
+from .model import (
+    CookieTypes,
+    HeaderTypes,
+    HTTPServerSetup,
+    HTTPVersion,
+    QueryTypes,
+    Request,
+    Response,
+    TimeoutTypes,
+    WebSocket,
+    WebSocketServerSetup,
+)
+
+if TYPE_CHECKING:
+    from nonebot.internal.adapter import Adapter, Bot
+
+
+BOT_HOOK_PARAMS = [DependParam, BotParam, DefaultParam]
+
+
+class Driver(abc.ABC):
+    """驱动器基类。
+
+    驱动器控制框架的启动和停止，适配器的注册，以及机器人生命周期管理。
+
+    参数:
+        env: 包含环境信息的 Env 对象
+        config: 包含配置信息的 Config 对象
+    """
+
+    _adapters: ClassVar[dict[str, "Adapter"]] = {}
+    """已注册的适配器列表"""
+    _bot_connection_hook: ClassVar[set[Dependent[Any]]] = set()
+    """Bot 连接建立时执行的函数"""
+    _bot_disconnection_hook: ClassVar[set[Dependent[Any]]] = set()
+    """Bot 连接断开时执行的函数"""
+
+    def __init__(self, env: Env, config: Config):
+        self.env: str = env.environment
+        """环境名称"""
+        self.config: Config = config
+        """全局配置对象"""
+        self._bots: dict[str, "Bot"] = {}
+        self._lifespan = Lifespan()
+
+    def __repr__(self) -> str:
+        return (
+            f"Driver(type={self.type!r}, "
+            f"adapters={len(self._adapters)}, bots={len(self._bots)})"
+        )
+
+    @property
+    def bots(self) -> dict[str, "Bot"]:
+        """获取当前所有已连接的 Bot"""
+        return self._bots
+
+    @property
+    def task_group(self) -> TaskGroup:
+        return self._lifespan.task_group
+
+    def register_adapter(self, adapter: type["Adapter"], **kwargs) -> None:
+        """注册一个协议适配器
+
+        参数:
+            adapter: 适配器类
+            kwargs: 其他传递给适配器的参数
+        """
+        name = adapter.get_name()
+        if name in self._adapters:
+            logger.opt(colors=True).debug(
+                f'Adapter "<y>{escape_tag(name)}</y>" already exists'
+            )
+            return
+        self._adapters[name] = adapter(self, **kwargs)
+        logger.opt(colors=True).debug(
+            f'Succeeded to load adapter "<y>{escape_tag(name)}</y>"'
+        )
+
+    @property
+    @abc.abstractmethod
+    def type(self) -> str:
+        """驱动类型名称"""
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def logger(self):
+        """驱动专属 logger 日志记录器"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def run(self, *args, **kwargs):
+        """启动驱动框架"""
+        logger.opt(colors=True).success(
+            f"<g>Loaded adapters: {escape_tag(', '.join(self._adapters))}</g>"
+        )
+
+    def on_startup(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
+        """注册一个启动时执行的函数"""
+        return self._lifespan.on_startup(func)
+
+    def on_shutdown(self, func: LIFESPAN_FUNC) -> LIFESPAN_FUNC:
+        """注册一个停止时执行的函数"""
+        return self._lifespan.on_shutdown(func)
+
+    @classmethod
+    def on_bot_connect(cls, func: T_BotConnectionHook) -> T_BotConnectionHook:
+        """装饰一个函数使他在 bot 连接成功时执行。
+
+        钩子函数参数:
+
+        - bot: 当前连接上的 Bot 对象
+        """
+        cls._bot_connection_hook.add(
+            Dependent[Any].parse(call=func, allow_types=BOT_HOOK_PARAMS)
+        )
+        return func
+
+    @classmethod
+    def on_bot_disconnect(cls, func: T_BotDisconnectionHook) -> T_BotDisconnectionHook:
+        """装饰一个函数使他在 bot 连接断开时执行。
+
+        钩子函数参数:
+
+        - bot: 当前连接上的 Bot 对象
+        """
+        cls._bot_disconnection_hook.add(
+            Dependent[Any].parse(call=func, allow_types=BOT_HOOK_PARAMS)
+        )
+        return func
+
+    def _bot_connect(self, bot: "Bot") -> None:
+        """在连接成功后，调用该函数来注册 bot 对象"""
+        if bot.self_id in self._bots:
+            raise RuntimeError(f"Duplicate bot connection with id {bot.self_id}")
+        self._bots[bot.self_id] = bot
+
+        if not self._bot_connection_hook:
+            return
+
+        def handle_exception(exc_group: BaseExceptionGroup) -> None:
+            for exc in flatten_exception_group(exc_group):
+                logger.opt(colors=True, exception=exc).error(
+                    "<r><bg #f8bbd0>"
+                    "Error when running WebSocketConnection hook:"
+                    "</bg #f8bbd0></r>"
+                )
+
+        async def _run_hook(bot: "Bot") -> None:
+            dependency_cache: T_DependencyCache = {}
+            with CancelScope(shield=True), catch({Exception: handle_exception}):
+                async with AsyncExitStack() as stack, create_task_group() as tg:
+                    for hook in self._bot_connection_hook:
+                        tg.start_soon(
+                            run_coro_with_catch,
+                            hook(
+                                bot=bot, stack=stack, dependency_cache=dependency_cache
+                            ),
+                            (SkippedException,),
+                        )
+
+        self.task_group.start_soon(_run_hook, bot)
+
+    def _bot_disconnect(self, bot: "Bot") -> None:
+        """在连接断开后，调用该函数来注销 bot 对象"""
+        if bot.self_id in self._bots:
+            del self._bots[bot.self_id]
+
+        if not self._bot_disconnection_hook:
+            return
+
+        def handle_exception(exc_group: BaseExceptionGroup) -> None:
+            for exc in flatten_exception_group(exc_group):
+                logger.opt(colors=True, exception=exc).error(
+                    "<r><bg #f8bbd0>"
+                    "Error when running WebSocketDisConnection hook:"
+                    "</bg #f8bbd0></r>"
+                )
+
+        async def _run_hook(bot: "Bot") -> None:
+            dependency_cache: T_DependencyCache = {}
+            # shield cancellation to ensure bot disconnect hooks are always run
+            with CancelScope(shield=True), catch({Exception: handle_exception}):
+                async with create_task_group() as tg, AsyncExitStack() as stack:
+                    for hook in self._bot_disconnection_hook:
+                        tg.start_soon(
+                            run_coro_with_catch,
+                            hook(
+                                bot=bot, stack=stack, dependency_cache=dependency_cache
+                            ),
+                            (SkippedException,),
+                        )
+
+        self.task_group.start_soon(_run_hook, bot)
+
+
+class Mixin(abc.ABC):
+    """可与其他驱动器共用的混入基类。"""
+
+    @property
+    @abc.abstractmethod
+    def type(self) -> str:
+        """混入驱动类型名称"""
+        raise NotImplementedError
+
+
+class ForwardMixin(Mixin):
+    """客户端混入基类。"""
+
+
+class ReverseMixin(Mixin):
+    """服务端混入基类。"""
+
+
+class HTTPClientSession(abc.ABC):
+    """HTTP 客户端会话基类。"""
+
+    @abc.abstractmethod
+    def __init__(
+        self,
+        params: QueryTypes = None,
+        headers: HeaderTypes = None,
+        cookies: CookieTypes = None,
+        version: Union[str, HTTPVersion] = HTTPVersion.H11,
+        timeout: TimeoutTypes = None,
+        proxy: Optional[str] = None,
+    ):
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def request(self, setup: Request) -> Response:
+        """发送一个 HTTP 请求"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def stream_request(
+        self,
+        setup: Request,
+        *,
+        chunk_size: int = 1024,
+    ) -> AsyncGenerator[Response, None]:
+        """发送一个 HTTP 流式请求"""
+        raise NotImplementedError
+        yield  # used for static type checking's generator detection
+
+    @abc.abstractmethod
+    async def setup(self) -> None:
+        """初始化会话"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def close(self) -> None:
+        """关闭会话"""
+        raise NotImplementedError
+
+    async def __aenter__(self) -> Self:
+        await self.setup()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        await self.close()
+
+
+class HTTPClientMixin(ForwardMixin):
+    """HTTP 客户端混入基类。"""
+
+    @abc.abstractmethod
+    async def request(self, setup: Request) -> Response:
+        """发送一个 HTTP 请求"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def stream_request(
+        self,
+        setup: Request,
+        *,
+        chunk_size: int = 1024,
+    ) -> AsyncGenerator[Response, None]:
+        """发送一个 HTTP 流式请求"""
+        raise NotImplementedError
+        yield  # used for static type checking's generator detection
+
+    @abc.abstractmethod
+    def get_session(
+        self,
+        params: QueryTypes = None,
+        headers: HeaderTypes = None,
+        cookies: CookieTypes = None,
+        version: Union[str, HTTPVersion] = HTTPVersion.H11,
+        timeout: TimeoutTypes = None,
+        proxy: Optional[str] = None,
+    ) -> HTTPClientSession:
+        """获取一个 HTTP 会话"""
+        raise NotImplementedError
+
+
+class WebSocketClientMixin(ForwardMixin):
+    """WebSocket 客户端混入基类。"""
+
+    @abc.abstractmethod
+    @asynccontextmanager
+    async def websocket(self, setup: Request) -> AsyncGenerator[WebSocket, None]:
+        """发起一个 WebSocket 连接"""
+        raise NotImplementedError
+        yield  # used for static type checking's generator detection
+
+
+class ASGIMixin(ReverseMixin):
+    """ASGI 服务端基类。
+
+    将后端框架封装，以满足适配器使用。
+    """
+
+    @property
+    @abc.abstractmethod
+    def server_app(self) -> Any:
+        """驱动 APP 对象"""
+        raise NotImplementedError
+
+    @property
+    @abc.abstractmethod
+    def asgi(self) -> Any:
+        """驱动 ASGI 对象"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def setup_http_server(self, setup: "HTTPServerSetup") -> None:
+        """设置一个 HTTP 服务器路由配置"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def setup_websocket_server(self, setup: "WebSocketServerSetup") -> None:
+        """设置一个 WebSocket 服务器路由配置"""
+        raise NotImplementedError
+
+
+ForwardDriver: TypeAlias = ForwardMixin
+"""支持客户端请求的驱动器。
+
+**Deprecated**，请使用 {ref}`nonebot.drivers.ForwardMixin` 或其子类代替。
+"""
+
+ReverseDriver: TypeAlias = ReverseMixin
+"""支持服务端请求的驱动器。
+
+**Deprecated**，请使用 {ref}`nonebot.drivers.ReverseMixin` 或其子类代替。
+"""