feat: enhance BaseFolderItemSelector dialog for mobile responsiveness and improved styling

fix: #5159

.github/workflows/auto_release.yml

@@ -1,92 +0,0 @@
-on:
-  push:
-    tags:
-      - 'v*'
-  workflow_dispatch:
-
-name: Auto Release
-
-jobs:
-  build-and-publish-to-github-release:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v6
-
-      - name: Dashboard Build
-        run: |
-          cd dashboard
-          npm install
-          npm run build
-          echo "COMMIT_SHA=$(git rev-parse HEAD)" >> $GITHUB_ENV
-          echo ${{ github.ref_name }} > dist/assets/version
-          zip -r dist.zip dist
-      
-      - name: Upload to Cloudflare R2
-        env:
-          R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }}
-          R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
-          R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
-          R2_BUCKET_NAME: "astrbot"
-          R2_OBJECT_NAME: "astrbot-webui-latest.zip"
-          VERSION_TAG: ${{ github.ref_name }}
-        run: |
-          echo "Installing rclone..."
-          curl https://rclone.org/install.sh | sudo bash
-
-          echo "Configuring rclone remote..."
-          mkdir -p ~/.config/rclone
-          cat <<EOF > ~/.config/rclone/rclone.conf
-          [r2]
-          type = s3
-          provider = Cloudflare
-          access_key_id = $R2_ACCESS_KEY_ID
-          secret_access_key = $R2_SECRET_ACCESS_KEY
-          endpoint = https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com
-          EOF
-
-          echo "Uploading dist.zip to R2 bucket: $R2_BUCKET_NAME/$R2_OBJECT_NAME"
-          mv dashboard/dist.zip dashboard/$R2_OBJECT_NAME
-          rclone copy dashboard/$R2_OBJECT_NAME r2:$R2_BUCKET_NAME --progress
-          mv dashboard/$R2_OBJECT_NAME dashboard/astrbot-webui-${VERSION_TAG}.zip
-          rclone copy dashboard/astrbot-webui-${VERSION_TAG}.zip r2:$R2_BUCKET_NAME --progress
-          mv dashboard/astrbot-webui-${VERSION_TAG}.zip dashboard/dist.zip
-
-      - name: Fetch Changelog
-        run: |
-          echo "changelog=changelogs/${{github.ref_name}}.md" >> "$GITHUB_ENV"
-
-      - name: Create GitHub Release
-        uses: ncipollo/release-action@v1
-        with:
-          bodyFile: ${{ env.changelog }}
-          artifacts: "dashboard/dist.zip"
-      
-  build-and-publish-to-pypi:
-    # 构建并发布到 PyPI
-    runs-on: ubuntu-latest
-    needs: build-and-publish-to-github-release
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v6
-
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: '3.10'
-
-      - name: Install uv
-        run: |
-          python -m pip install uv
-
-      - name: Build package
-        run: |
-          uv build
-
-      - name: Publish to PyPI
-        env:
-          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
-        run: |
-          uv publish

.github/workflows/code-format.yml

@@ -17,7 +17,7 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v6
       with:
-        python-version: '3.10'
+        python-version: '3.12'
         
     - name: Install UV
       run: pip install uv

.github/workflows/dashboard_ci.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 'latest'
+          node-version: '24.13.0'
 
       - name: npm install, build
         run: |
@@ -52,4 +52,4 @@ jobs:
           repo: astrbot-release-harbour
           body: "Automated release from commit ${{ github.sha }}"
           token: ${{ secrets.ASTRBOT_HARBOUR_TOKEN }}
-          artifacts: "dashboard/dist.zip"
+          artifacts: "dashboard/dist.zip"

.github/workflows/docker-image.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       DOCKER_HUB_USERNAME: ${{ secrets.DOCKER_HUB_USERNAME }}
-      GHCR_OWNER: soulter
+      GHCR_OWNER: astrbotdevs
       HAS_GHCR_TOKEN: ${{ secrets.GHCR_GITHUB_TOKEN != '' }}
 
     steps:
@@ -113,7 +113,7 @@ jobs:
     runs-on: ubuntu-latest
     env:
       DOCKER_HUB_USERNAME: ${{ secrets.DOCKER_HUB_USERNAME }}
-      GHCR_OWNER: soulter
+      GHCR_OWNER: astrbotdevs
       HAS_GHCR_TOKEN: ${{ secrets.GHCR_GITHUB_TOKEN != '' }}
 
     steps:

.github/workflows/release.yml

@@ -0,0 +1,377 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: "Git ref to build (branch/tag/SHA)"
+        required: false
+        default: "master"
+      tag:
+        description: "Release tag to publish assets to (for example: v4.14.6)"
+        required: false
+
+permissions:
+  contents: write
+
+jobs:
+  build-dashboard:
+    name: Build Dashboard
+    runs-on: ubuntu-24.04
+    env:
+      R2_ACCOUNT_ID: ${{ secrets.R2_ACCOUNT_ID }}
+      R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
+      R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.ref || github.ref }}
+
+      - name: Resolve tag
+        id: tag
+        shell: bash
+        run: |
+          if [ "${{ github.event_name }}" = "push" ]; then
+            tag="${GITHUB_REF_NAME}"
+          elif [ -n "${{ inputs.tag }}" ]; then
+            tag="${{ inputs.tag }}"
+          else
+            tag="$(git describe --tags --abbrev=0)"
+          fi
+          if [ -z "$tag" ]; then
+            echo "Failed to resolve tag." >&2
+            exit 1
+          fi
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.28.2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24.13.0'
+          cache: "pnpm"
+          cache-dependency-path: dashboard/pnpm-lock.yaml
+
+      - name: Build dashboard dist
+        shell: bash
+        run: |
+          pnpm --dir dashboard install --frozen-lockfile
+          pnpm --dir dashboard run build
+          echo "${{ steps.tag.outputs.tag }}" > dashboard/dist/assets/version
+          cd dashboard
+          zip -r "AstrBot-${{ steps.tag.outputs.tag }}-dashboard.zip" dist
+
+      - name: Upload dashboard artifact
+        uses: actions/upload-artifact@v6
+        with:
+          name: Dashboard-${{ steps.tag.outputs.tag }}
+          if-no-files-found: error
+          path: dashboard/AstrBot-${{ steps.tag.outputs.tag }}-dashboard.zip
+
+      - name: Upload dashboard package to Cloudflare R2
+        if: ${{ env.R2_ACCOUNT_ID != '' && env.R2_ACCESS_KEY_ID != '' && env.R2_SECRET_ACCESS_KEY != '' }}
+        env:
+          R2_BUCKET_NAME: "astrbot"
+          R2_OBJECT_NAME: "astrbot-webui-latest.zip"
+          VERSION_TAG: ${{ steps.tag.outputs.tag }}
+        shell: bash
+        run: |
+          curl https://rclone.org/install.sh | sudo bash
+
+          mkdir -p ~/.config/rclone
+          cat <<EOF > ~/.config/rclone/rclone.conf
+          [r2]
+          type = s3
+          provider = Cloudflare
+          access_key_id = $R2_ACCESS_KEY_ID
+          secret_access_key = $R2_SECRET_ACCESS_KEY
+          endpoint = https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com
+          EOF
+
+          cp "dashboard/AstrBot-${VERSION_TAG}-dashboard.zip" "dashboard/${R2_OBJECT_NAME}"
+          rclone copy "dashboard/${R2_OBJECT_NAME}" "r2:${R2_BUCKET_NAME}" --progress
+          cp "dashboard/AstrBot-${VERSION_TAG}-dashboard.zip" "dashboard/astrbot-webui-${VERSION_TAG}.zip"
+          rclone copy "dashboard/astrbot-webui-${VERSION_TAG}.zip" "r2:${R2_BUCKET_NAME}" --progress
+
+  build-desktop:
+    name: Build ${{ matrix.name }}
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: linux-x64
+            runner: ubuntu-24.04
+            os: linux
+            arch: amd64
+          - name: linux-arm64
+            runner: ubuntu-24.04-arm
+            os: linux
+            arch: arm64
+          - name: windows-x64
+            runner: windows-2022
+            os: win
+            arch: amd64
+          - name: windows-arm64
+            runner: windows-11-arm
+            os: win
+            arch: arm64
+          - name: macos-x64
+            runner: macos-15-intel
+            os: mac
+            arch: amd64
+          - name: macos-arm64
+            runner: macos-15
+            os: mac
+            arch: arm64
+    env:
+      CSC_IDENTITY_AUTO_DISCOVERY: "false"
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.ref || github.ref }}
+
+      - name: Resolve tag
+        id: tag
+        shell: bash
+        run: |
+          if [ "${{ github.event_name }}" = "push" ]; then
+            tag="${GITHUB_REF_NAME}"
+          elif [ -n "${{ inputs.tag }}" ]; then
+            tag="${{ inputs.tag }}"
+          else
+            tag="$(git describe --tags --abbrev=0)"
+          fi
+          if [ -z "$tag" ]; then
+            echo "Failed to resolve tag." >&2
+            exit 1
+          fi
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.28.2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24.13.0'
+          cache: "pnpm"
+          cache-dependency-path: |
+            dashboard/pnpm-lock.yaml
+            desktop/pnpm-lock.yaml
+
+      - name: Prepare OpenSSL for Windows ARM64
+        if: ${{ matrix.os == 'win' && matrix.arch == 'arm64' }}
+        shell: pwsh
+        run: |
+          git clone https://github.com/microsoft/vcpkg.git C:\vcpkg
+          & C:\vcpkg\bootstrap-vcpkg.bat -disableMetrics
+          & C:\vcpkg\vcpkg.exe install openssl:arm64-windows
+
+          "VCPKG_ROOT=C:\vcpkg" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+          "VCPKGRS_TRIPLET=arm64-windows" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+          "OPENSSL_DIR=C:\vcpkg\installed\arm64-windows" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+          "OPENSSL_ROOT_DIR=C:\vcpkg\installed\arm64-windows" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+          "OPENSSL_LIB_DIR=C:\vcpkg\installed\arm64-windows\lib" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+          "OPENSSL_INCLUDE_DIR=C:\vcpkg\installed\arm64-windows\include" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
+
+      - name: Install dependencies
+        shell: bash
+        run: |
+          uv sync
+          pnpm --dir dashboard install --frozen-lockfile
+          pnpm --dir desktop install --frozen-lockfile
+
+      - name: Build desktop package
+        shell: bash
+        run: |
+          pnpm --dir dashboard run build
+          pnpm --dir desktop run build:webui
+          pnpm --dir desktop run build:backend
+          pnpm --dir desktop run sync:version
+          pnpm --dir desktop exec electron-builder --publish never
+
+      - name: Normalize artifact names
+        shell: bash
+        env:
+          NAME_PREFIX: AstrBot-${{ steps.tag.outputs.tag }}-${{ matrix.arch }}-${{ matrix.os }}
+        run: |
+          shopt -s nullglob
+          out_dir="desktop/dist/release"
+          mkdir -p "$out_dir"
+          files=(
+            desktop/dist/*.AppImage
+            desktop/dist/*.dmg
+            desktop/dist/*.zip
+            desktop/dist/*.exe
+          )
+          if [ ${#files[@]} -eq 0 ]; then
+            echo "No desktop artifacts found to rename." >&2
+            exit 1
+          fi
+          for src in "${files[@]}"; do
+            file="$(basename "$src")"
+            case "$file" in
+              *.AppImage)
+                dest="$out_dir/${NAME_PREFIX}.AppImage"
+                ;;
+              *.dmg)
+                dest="$out_dir/${NAME_PREFIX}.dmg"
+                ;;
+              *.exe)
+                dest="$out_dir/${NAME_PREFIX}.exe"
+                ;;
+              *.zip)
+                dest="$out_dir/${NAME_PREFIX}.zip"
+                ;;
+              *)
+                continue
+                ;;
+            esac
+            cp "$src" "$dest"
+          done
+          ls -la "$out_dir"
+
+      - name: Upload desktop artifacts
+        uses: actions/upload-artifact@v6
+        with:
+          name: AstrBot-${{ steps.tag.outputs.tag }}-${{ matrix.arch }}-${{ matrix.os }}
+          if-no-files-found: error
+          path: desktop/dist/release/*
+
+  publish-release:
+    name: Publish GitHub Release
+    runs-on: ubuntu-24.04
+    needs:
+      - build-dashboard
+      - build-desktop
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.ref || github.ref }}
+
+      - name: Resolve tag
+        id: tag
+        shell: bash
+        run: |
+          if [ "${{ github.event_name }}" = "push" ]; then
+            tag="${GITHUB_REF_NAME}"
+          elif [ -n "${{ inputs.tag }}" ]; then
+            tag="${{ inputs.tag }}"
+          else
+            tag="$(git describe --tags --abbrev=0)"
+          fi
+          if [ -z "$tag" ]; then
+            echo "Failed to resolve tag." >&2
+            exit 1
+          fi
+          echo "tag=$tag" >> "$GITHUB_OUTPUT"
+
+      - name: Download dashboard artifact
+        uses: actions/download-artifact@v7
+        with:
+          name: Dashboard-${{ steps.tag.outputs.tag }}
+          path: release-assets
+
+      - name: Download desktop artifacts
+        uses: actions/download-artifact@v7
+        with:
+          pattern: AstrBot-${{ steps.tag.outputs.tag }}-*
+          path: release-assets
+          merge-multiple: true
+
+      - name: Resolve release notes
+        id: notes
+        shell: bash
+        run: |
+          note_file="changelogs/${{ steps.tag.outputs.tag }}.md"
+          if [ ! -f "$note_file" ]; then
+            note_file="$(mktemp)"
+            echo "Release ${{ steps.tag.outputs.tag }}" > "$note_file"
+          fi
+          echo "file=$note_file" >> "$GITHUB_OUTPUT"
+
+      - name: Ensure release exists
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          tag="${{ steps.tag.outputs.tag }}"
+          if ! gh release view "$tag" >/dev/null 2>&1; then
+            gh release create "$tag" --title "$tag" --notes-file "${{ steps.notes.outputs.file }}"
+          fi
+
+      - name: Remove stale assets from release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          tag="${{ steps.tag.outputs.tag }}"
+          while IFS= read -r asset; do
+            case "$asset" in
+              *.AppImage|*.dmg|*.zip|*.exe|*.blockmap)
+                gh release delete-asset "$tag" "$asset" -y || true
+                ;;
+            esac
+          done < <(gh release view "$tag" --json assets --jq '.assets[].name')
+
+      - name: Upload assets to release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        shell: bash
+        run: |
+          tag="${{ steps.tag.outputs.tag }}"
+          gh release upload "$tag" release-assets/* --clobber
+
+  publish-pypi:
+    name: Publish PyPI
+    runs-on: ubuntu-24.04
+    needs: publish-release
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ inputs.ref || github.ref }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.10"
+
+      - name: Install uv
+        shell: bash
+        run: python -m pip install uv
+
+      - name: Build package
+        shell: bash
+        run: uv build
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        shell: bash
+        run: uv publish

.gitignore

@@ -32,8 +32,15 @@ tests/astrbot_plugin_openai
 # Dashboard
 dashboard/node_modules/
 dashboard/dist/
+.pnpm-store/
+desktop/node_modules/
+desktop/dist/
+desktop/out/
+desktop/resources/backend/astrbot-backend*
+desktop/resources/backend/*.exe
+desktop/resources/webui/*
+desktop/resources/.pyinstaller/
 package-lock.json
-package.json
 yarn.lock
 
 # Operating System
@@ -53,4 +60,4 @@ IFLOW.md
 
 # genie_tts data
 CharacterModels/
-GenieData/
+GenieData/

.python-version

@@ -1 +1 @@
-3.10
+3.12

AGENTS.md

@@ -26,6 +26,7 @@ Runs on `http://localhost:3000` by default.
 3. After finishing, use `ruff format .` and `ruff check .` to format and check the code.
 4. When committing, ensure to use conventional commits messages, such as `feat: add new agent for data analysis` or `fix: resolve bug in provider manager`.
 5. Use English for all new comments.
+6. For path handling, use `pathlib.Path` instead of string paths, and use `astrbot.core.utils.path_utils` to get the AstrBot data and temp directory.
 
 ## PR instructions
 

Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.11-slim
+FROM python:3.12-slim
 WORKDIR /AstrBot
 
 COPY . /AstrBot/
@@ -15,17 +15,17 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     curl \
     gnupg \
     git \
+    && curl -fsSL https://deb.nodesource.com/setup_lts.x | bash - \
+    && apt-get install -y --no-install-recommends nodejs \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
-RUN apt-get update && apt-get install -y curl gnupg \
-    && curl -fsSL https://deb.nodesource.com/setup_lts.x | bash - \
-    && apt-get install -y nodejs
-
 RUN python -m pip install uv \
-    && echo "3.11" > .python-version
-RUN uv pip install -r requirements.txt --no-cache-dir --system
-RUN uv pip install socksio uv pilk --no-cache-dir --system
+    && echo "3.12" > .python-version \
+    && uv lock \
+    && uv export --format requirements.txt --output-file requirements.txt --frozen \
+    && uv pip install -r requirements.txt --no-cache-dir --system \
+    && uv pip install socksio uv pilk --no-cache-dir --system
 
 EXPOSE 6185
 

FIRST_NOTICE.en-US.md

@@ -0,0 +1,14 @@
+## Welcome to AstrBot
+
+🌟 Thank you for using AstrBot!
+
+AstrBot is an Agentic AI assistant for personal and group chats, with support for multiple IM platforms and a wide range of built-in features. We hope it brings you an efficient and enjoyable experience. ❤️
+
+Important notice:
+
+AstrBot is a **free and open-source software project** protected by the AGPLv3 license. You can find the full source code and related resources on our [**official website**](https://astrbot.app) and [**GitHub**](https://github.com/astrbotdevs/astrbot).
+As of now, AstrBot has **no commercial services of any kind**, and the official team **will never charge users any fees** under any name.
+
+If anyone asks you to pay while using AstrBot, **you are likely being scammed**. Please request a refund immediately and report it to us by email.
+
+📮 Official email: [community@astrbot.app](mailto:community@astrbot.app)

FIRST_NOTICE.md

@@ -0,0 +1,14 @@
+## 欢迎使用 AstrBot
+
+🌟 感谢您使用 AstrBot！
+
+AstrBot 是一款可接入多种 IM 平台的 Agentic AI 个人 / 群聊助手，内置多项强大功能，希望能为您带来高效、愉快的使用体验。❤️
+
+我们想特别说明：
+
+AstrBot 是受 AGPLv3 开源协议保护的**免费开源软件项目**，您可以在[**官方网站**](https://astrbot.app)、[**GitHub**](https://github.com/astrbotdevs/astrbot) 上找到 AstrBot 的全部源代码及相关资源。
+截至目前，AstrBot 项目**未开展任何形式的商业化服务**，官方**不会以任何名义向用户收取费用**。
+
+如果您在使用 AstrBot 的过程中被要求付费，**表明您已经遭遇诈骗行为**。请立即向相关方申请退款，并及时通过邮件向我们反馈。
+
+📮 官方邮箱：[community@astrbot.app](mailto:community@astrbot.app)

README.md

@@ -2,7 +2,6 @@
 
 <div align="center">
 
-
 <a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_en.md">English</a> ｜
 <a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ja.md">日本語</a> ｜
 <a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_zh-TW.md">繁體中文</a> ｜
@@ -41,14 +40,14 @@ AstrBot 是一个开源的一站式 Agentic 个人和群聊助手，可在 QQ、
 ## 主要功能
 
 1. 💯 免费 & 开源。
-1. ✨ AI 大模型对话，多模态，Agent，MCP，Skills，知识库，人格设定，自动压缩对话。
-2. 🤖 支持接入 Dify、阿里云百炼、Coze 等智能体平台。
-2. 🌐 多平台，支持 QQ、企业微信、飞书、钉钉、微信公众号、Telegram、Slack 以及[更多](#支持的消息平台)。
-3. 📦 插件扩展，已有近 800 个插件可一键安装。
-5. 🛡️ [Agent Sandbox](https://docs.astrbot.app/use/astrbot-agent-sandbox.html) 隔离化环境，安全地执行任何代码、调用 Shell、会话级资源复用。
-6. 💻 WebUI 支持。
-7. 🌈 Web ChatUI 支持，ChatUI 内置代理沙盒、网页搜索等。
-8. 🌐 国际化（i18n）支持。
+2. ✨ AI 大模型对话，多模态，Agent，MCP，Skills，知识库，人格设定，自动压缩对话。
+3. 🤖 支持接入 Dify、阿里云百炼、Coze 等智能体平台。
+4. 🌐 多平台，支持 QQ、企业微信、飞书、钉钉、微信公众号、Telegram、Slack 以及[更多](#支持的消息平台)。
+5. 📦 插件扩展，已有近 800 个插件可一键安装。
+6. 🛡️ [Agent Sandbox](https://docs.astrbot.app/use/astrbot-agent-sandbox.html) 隔离化环境，安全地执行任何代码、调用 Shell、会话级资源复用。
+7. 💻 WebUI 支持。
+8. 🌈 Web ChatUI 支持，ChatUI 内置代理沙盒、网页搜索等。
+9. 🌐 国际化（i18n）支持。
 
 <br>
 
@@ -78,9 +77,14 @@ AstrBot 是一个开源的一站式 Agentic 个人和群聊助手，可在 QQ、
 #### uv 部署
 
 ```bash
-uvx astrbot
+uv tool install astrbot
+astrbot
 ```
 
+#### 启动器一键部署（AstrBot Launcher）
+
+进入 [AstrBot Launcher](https://github.com/Raven95676/astrbot-launcher) 仓库，在 Releases 页最新版本下找到对应的系统安装包安装即可。
+
 #### 宝塔面板部署
 
 AstrBot 与宝塔面板合作，已上架至宝塔面板。
@@ -132,6 +136,20 @@ uv run main.py
 
 或者请参阅官方文档 [通过源码部署 AstrBot](https://astrbot.app/deploy/astrbot/cli.html) 。
 
+#### 系统包管理器安装
+
+##### Arch Linux
+
+```bash
+yay -S astrbot-git
+# 或者使用 paru
+paru -S astrbot-git
+```
+
+#### 桌面端 Electron 打包
+
+桌面端（Electron 打包，`pnpm` 工作流）构建流程请参阅：[`desktop/README.md`](desktop/README.md)。
+
 ## 支持的消息平台
 
 **官方维护**
@@ -260,8 +278,6 @@ pre-commit install
 
 </div>
 
-</details>
-
 <div align="center">
 
 _陪伴与能力从来不应该是对立面。我们希望创造的是一个既能理解情绪、给予陪伴，也能可靠完成工作的机器人。_
@@ -270,3 +286,4 @@ _私は、高性能ですから!_
 
 <img src="https://files.astrbot.app/watashiwa-koseino-desukara.gif" width="100"/>
 
+</div>

README_en.md

@@ -3,7 +3,6 @@
 <div align="center">
 
 <a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README.md">中文</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_en.md">English</a> ｜
 <a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ja.md">日本語</a> ｜
 <a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_zh-TW.md">繁體中文</a> ｜
 <a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_fr.md">Français</a> ｜
@@ -52,6 +51,23 @@ AstrBot is an open-source all-in-one Agent chatbot platform that integrates with
 8. 🌈 Web ChatUI Support with built-in agent sandbox and web search.
 9. 🌐 Internationalization (i18n) Support.
 
+<br>
+
+<table align="center">
+  <tr align="center">
+    <th>💙 Role-playing & Emotional Companionship</th>
+    <th>✨ Proactive Agent</th>
+    <th>🚀 General Agentic Capabilities</th>
+    <th>🧩 900+ Community Plugins</th>
+  </tr>
+  <tr>
+    <td align="center"><p align="center"><img width="984" height="1746" alt="99b587c5d35eea09d84f33e6cf6cfd4f" src="https://github.com/user-attachments/assets/89196061-3290-458d-b51f-afa178049f84" /></p></td>
+    <td align="center"><p align="center"><img width="976" height="1612" alt="c449acd838c41d0915cc08a3824025b1" src="https://github.com/user-attachments/assets/f75368b4-e022-41dc-a9e0-131c3e73e32e" /></p></td>
+    <td align="center"><p align="center"><img width="974" height="1732" alt="image" src="https://github.com/user-attachments/assets/e22a3968-87d7-4708-a7cd-e7f198c7c32e" /></p></td>
+    <td align="center"><p align="center"><img width="976" height="1734" alt="image" src="https://github.com/user-attachments/assets/0952b395-6b4a-432a-8a50-c294b7f89750" /></p></td>
+  </tr>
+</table>
+
 ## Quick Start
 
 #### Docker Deployment (Recommended 🥳)
@@ -63,7 +79,18 @@ Please refer to the official documentation: [Deploy AstrBot with Docker](https:/
 #### uv Deployment
 
 ```bash
-uvx astrbot
+uv tool install astrbot
+astrbot
+```
+
+#### System Package Manager Installation
+
+##### Arch Linux
+
+```bash
+yay -S astrbot-git
+# or use paru
+paru -S astrbot-git
 ```
 
 #### BT-Panel Deployment
@@ -117,6 +144,20 @@ uv run main.py
 
 Or refer to the official documentation: [Deploy AstrBot from Source](https://astrbot.app/deploy/astrbot/cli.html).
 
+#### System Package Manager Installation 
+
+##### Arch Linux
+
+```bash
+yay -S astrbot-git
+# or use paru
+paru -S astrbot-git
+```
+
+#### Desktop Electron Build
+
+For desktop build steps (Electron packaging, `pnpm` workflow), see [`desktop/README.md`](desktop/README.md).
+
 ## Supported Messaging Platforms
 
 **Officially Maintained**
@@ -155,7 +196,7 @@ Or refer to the official documentation: [Deploy AstrBot from Source](https://ast
 - [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_astrbot&referral_code=FV7DcGowN4hB5UuXKgpE74)
 - [302.AI](https://share.302.ai/rr1M3l)
 - [TokenPony](https://www.tokenpony.cn/3YPyf)
-- [SiliconFlow](https://docs.siliconflow.cn/cn/usecases/use-siliconcloud-in-astrbot)
+- [SiliconFlow](https://docs.siliconflow.cn/cn/usercases/use-siliconcloud-in-astrbot)
 - [PPIO Cloud](https://ppio.com/user/register?invited_by=AIOONE)
 - ModelScope
 - OneAPI
@@ -245,10 +286,10 @@ Additionally, the birth of this project would not have been possible without the
 
 </div>
 
-</details>
-
 <div align="center">
 
+_Companionship and capability should never be at odds. What we aim to create is a robot that can understand emotions, provide genuine companionship, and reliably accomplish tasks._
+
 _私は、高性能ですから!_
 
 <img src="https://files.astrbot.app/watashiwa-koseino-desukara.gif" width="100"/>

README_fr.md

@@ -1,9 +1,13 @@
 ![AstrBot-Logo-Simplified](https://github.com/user-attachments/assets/ffd99b6b-3272-4682-beaa-6fe74250f7d9)
 
-</p>
-
 <div align="center">
 
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README.md">中文</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_en.md">English</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ja.md">日本語</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_zh-TW.md">繁體中文</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ru.md">Русский</a>
+
 <br>
 
 <div>
@@ -14,22 +18,17 @@
 <br>
 
 <div>
-<img src="https://img.shields.io/github/v/release/AstrBotDevs/AstrBot?style=for-the-badge&color=76bad9" href="https://github.com/AstrBotDevs/AstrBot/releases/latest">
-<img src="https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge&color=76bad9" alt="python">
-<a href="https://hub.docker.com/r/soulter/astrbot"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/soulter/astrbot.svg?style=for-the-badge&color=76bad9"/></a>
-<a href="https://qm.qq.com/cgi-bin/qm/qr?k=wtbaNx7EioxeaqS9z7RQWVXPIxg2zYr7&jump_from=webapi&authKey=vlqnv/AV2DbJEvGIcxdlNSpfxVy+8vVqijgreRdnVKOaydpc+YSw4MctmEbr0k5"><img alt="QQ_community" src="https://img.shields.io/badge/QQ群-775869627-purple?style=for-the-badge&color=76bad9"></a>
-<a href="https://t.me/+hAsD2Ebl5as3NmY1"><img alt="Telegram_community" src="https://img.shields.io/badge/Telegram-AstrBot-purple?style=for-the-badge&color=76bad9"></a>
-<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fplugin-num&query=%24.result&suffix=%20plugins&style=for-the-badge&label=Marketplace&cacheSeconds=3600">
+<img src="https://img.shields.io/github/v/release/AstrBotDevs/AstrBot?color=76bad9" href="https://github.com/AstrBotDevs/AstrBot/releases/latest">
+<img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="python">
+<img src="https://deepwiki.com/badge.svg" href="https://deepwiki.com/AstrBotDevs/AstrBot">
+<a href="https://zread.ai/AstrBotDevs/AstrBot" target="_blank"><img src="https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff" alt="zread"/></a>
+<a href="https://hub.docker.com/r/soulter/astrbot"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/soulter/astrbot.svg?color=76bad9"/></a>
+<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fplugin-num&query=%24.result&suffix=%E4%B8%AA&label=%E6%8F%92%E4%BB%B6%E5%B8%82%E5%9C%BA&cacheSeconds=3600">
+<img src="https://gitcode.com/Soulter/AstrBot/star/badge.svg" href="https://gitcode.com/Soulter/AstrBot">
 </div>
 
 <br>
 
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README.md">中文</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_en.md">English</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ja.md">日本語</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_zh-TW.md">繁體中文</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ru.md">Русский</a>
-
 <a href="https://astrbot.app/">Documentation</a> ｜
 <a href="https://blog.astrbot.app/">Blog</a> ｜
 <a href="https://astrbot.featurebase.app/roadmap">Feuille de route</a> ｜
@@ -43,12 +42,31 @@ AstrBot est une plateforme de chatbot Agent tout-en-un open source qui s'intègr
 ## Fonctionnalités principales
 
 1. 💯 Gratuit & Open Source.
-2. ✨ Conversations avec LLM IA, Multimodal, Agent, MCP, Base de connaissances, Paramètres de personnalité.
-3. 🤖 Prise en charge de l'intégration avec Dify, Alibaba Cloud Bailian, Coze et autres plateformes d'agents.
-4. 🌐 Multi-plateforme : QQ, WeChat Work, Feishu, DingTalk, Comptes officiels WeChat, Telegram, Slack, et [plus encore](#plateformes-de-messagerie-prises-en-charge).
-5. 📦 Extensions de plugins avec près de 800 plugins disponibles pour une installation en un clic.
-6. 💻 Support WebUI.
-7. 🌐 Support de l'internationalisation (i18n).
+2. ✨ Dialogue avec de grands modèles d'IA, multimodal, Agent, MCP, Skills, Base de connaissances, Paramétrage de personnalité, compression automatique des dialogues.
+3. 🤖 Prise en charge de l'accès aux plateformes d'Agents telles que Dify, Alibaba Cloud Bailian, Coze, etc.
+4. 🌐 Multiplateforme : supporte QQ, WeChat Enterprise, Feishu, DingTalk, Comptes officiels WeChat, Telegram, Slack et [plus encore](#plateformes-de-messagerie-prises-en-charge).
+5. 📦 Extension par plugins, avec près de 800 plugins déjà disponibles pour une installation en un clic.
+6. 🛡️  Environnement isolé [Agent Sandbox](https://docs.astrbot.app/use/astrbot-agent-sandbox.html) : exécution sécurisée de code, appels Shell et réutilisation des ressources au niveau de la session.
+7. 💻 Support WebUI.
+8. 🌈 Support Web ChatUI, avec sandbox d'agent intégrée, recherche web, etc.
+9. 🌐 Support de l'internationalisation (i18n).
+
+<br>
+
+<table align="center">
+  <tr align="center">
+    <th>💙 Jeux de rôle & Accompagnement émotionnel</th>
+    <th>✨ Agent proactif</th>
+    <th>🚀 Capacités agentiques générales</th>
+    <th>🧩 900+ Plugins de communauté</th>
+  </tr>
+  <tr>
+    <td align="center"><p align="center"><img width="984" height="1746" alt="99b587c5d35eea09d84f33e6cf6cfd4f" src="https://github.com/user-attachments/assets/89196061-3290-458d-b51f-afa178049f84" /></p></td>
+    <td align="center"><p align="center"><img width="976" height="1612" alt="c449acd838c41d0915cc08a3824025b1" src="https://github.com/user-attachments/assets/f75368b4-e022-41dc-a9e0-131c3e73e32e" /></p></td>
+    <td align="center"><p align="center"><img width="974" height="1732" alt="image" src="https://github.com/user-attachments/assets/e22a3968-87d7-4708-a7cd-e7f198c7c32e" /></p></td>
+    <td align="center"><p align="center"><img width="976" height="1734" alt="image" src="https://github.com/user-attachments/assets/0952b395-6b4a-432a-8a50-c294b7f89750" /></p></td>
+  </tr>
+</table>
 
 ## Démarrage rapide
 
@@ -61,7 +79,18 @@ Veuillez consulter la documentation officielle : [Déployer AstrBot avec Docker]
 #### Déploiement uv
 
 ```bash
-uvx astrbot
+uv tool install astrbot
+astrbot
+```
+
+#### Installation via le gestionnaire de paquets du système
+
+##### Arch Linux
+
+```bash
+yay -S astrbot-git
+# ou utiliser paru
+paru -S astrbot-git
 ```
 
 #### Déploiement BT-Panel
@@ -115,6 +144,16 @@ uv run main.py
 
 Ou consultez la documentation officielle : [Déployer AstrBot depuis les sources](https://astrbot.app/deploy/astrbot/cli.html).
 
+#### Установка через системный пакетный менеджер
+
+##### Arch Linux
+
+```bash
+yay -S astrbot-git
+# или используйте paru
+paru -S astrbot-git
+```
+
 ## Plateformes de messagerie prises en charge
 
 **Maintenues officiellement**
@@ -153,7 +192,7 @@ Ou consultez la documentation officielle : [Déployer AstrBot depuis les sources
 - [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_astrbot&referral_code=FV7DcGowN4hB5UuXKgpE74)
 - [302.AI](https://share.302.ai/rr1M3l)
 - [TokenPony](https://www.tokenpony.cn/3YPyf)
-- [SiliconFlow](https://docs.siliconflow.cn/cn/usecases/use-siliconcloud-in-astrbot)
+- [SiliconFlow](https://docs.siliconflow.cn/cn/usercases/use-siliconcloud-in-astrbot)
 - [PPIO Cloud](https://ppio.com/user/register?invited_by=AIOONE)
 - ModelScope
 - OneAPI
@@ -241,7 +280,12 @@ De plus, la naissance de ce projet n'aurait pas été possible sans l'aide des p
 
 </div>
 
-</details>
+<div align="center">
+
+_La compagnie et la capacité ne devraient jamais être des opposés. Nous souhaitons créer un robot capable à la fois de comprendre les émotions, d'offrir de la présence, et d'accomplir des tâches de manière fiable._
 
 _私は、高性能ですから!_
 
+<img src="https://files.astrbot.app/watashiwa-koseino-desukara.gif" width="100"/>
+
+</div>

README_ja.md

@@ -1,9 +1,13 @@
 ![AstrBot-Logo-Simplified](https://github.com/user-attachments/assets/ffd99b6b-3272-4682-beaa-6fe74250f7d9)
 
-</p>
-
 <div align="center">
 
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README.md">中文</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_en.md">English</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_zh-TW.md">繁體中文</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_fr.md">Français</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ru.md">Русский</a>
+
 <br>
 
 <div>
@@ -14,22 +18,17 @@
 <br>
 
 <div>
-<img src="https://img.shields.io/github/v/release/AstrBotDevs/AstrBot?style=for-the-badge&color=76bad9" href="https://github.com/AstrBotDevs/AstrBot/releases/latest">
-<img src="https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge&color=76bad9" alt="python">
-<a href="https://hub.docker.com/r/soulter/astrbot"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/soulter/astrbot.svg?style=for-the-badge&color=76bad9"/></a>
-<a href="https://qm.qq.com/cgi-bin/qm/qr?k=wtbaNx7EioxeaqS9z7RQWVXPIxg2zYr7&jump_from=webapi&authKey=vlqnv/AV2DbJEvGIcxdlNSpfxVy+8vVqijgreRdnVKOaydpc+YSw4MctmEbr0k5"><img alt="QQ_community" src="https://img.shields.io/badge/QQ群-775869627-purple?style=for-the-badge&color=76bad9"></a>
-<a href="https://t.me/+hAsD2Ebl5as3NmY1"><img alt="Telegram_community" src="https://img.shields.io/badge/Telegram-AstrBot-purple?style=for-the-badge&color=76bad9"></a>
-<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fplugin-num&query=%24.result&suffix=%E5%80%8B&style=for-the-badge&label=%E3%83%97%E3%83%A9%E3%82%B0%E3%82%A4%E3%83%B3&cacheSeconds=3600">
+<img src="https://img.shields.io/github/v/release/AstrBotDevs/AstrBot?color=76bad9" href="https://github.com/AstrBotDevs/AstrBot/releases/latest">
+<img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="python">
+<img src="https://deepwiki.com/badge.svg" href="https://deepwiki.com/AstrBotDevs/AstrBot">
+<a href="https://zread.ai/AstrBotDevs/AstrBot" target="_blank"><img src="https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff" alt="zread"/></a>
+<a href="https://hub.docker.com/r/soulter/astrbot"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/soulter/astrbot.svg?color=76bad9"/></a>
+<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fplugin-num&query=%24.result&suffix=%E4%B8%AA&label=%E6%8F%92%E4%BB%B6%E5%B8%82%E5%9C%BA&cacheSeconds=3600">
+<img src="https://gitcode.com/Soulter/AstrBot/star/badge.svg" href="https://gitcode.com/Soulter/AstrBot">
 </div>
 
 <br>
 
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README.md">中文</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_en.md">English</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_zh-TW.md">繁體中文</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_fr.md">Français</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ru.md">Русский</a>
-
 <a href="https://astrbot.app/">ドキュメント</a> ｜
 <a href="https://blog.astrbot.app/">Blog</a> ｜
 <a href="https://astrbot.featurebase.app/roadmap">ロードマップ</a> ｜
@@ -43,12 +42,31 @@ AstrBot は、主要なインスタントメッセージングアプリと統合
 ## 主な機能
 
 1. 💯 無料 & オープンソース。
-2. ✨ AI 大規模言語モデル対話、マルチモーダル、Agent、MCP、ナレッジベース、ペルソナ設定。
-3. 🤖 Dify、Alibaba Cloud 百炼、Coze などの Agent プラットフォームとの統合をサポート。
-4. 🌐 マルチプラットフォーム：QQ、WeChat Work、Feishu、DingTalk、WeChat 公式アカウント、Telegram、Slack、[その他](#サポートされているメッセージプラットフォーム)。
-5. 📦 約800個のプラグインをワンクリックでインストール可能なプラグイン拡張機能。
-6. 💻 WebUI サポート。
-7. 🌐 国際化（i18n）サポート。
+2. ✨ AI大規模言語モデル対話、マルチモーダル、Agent、MCP、Skills、ナレッジベース、ペルソナ設定、対話の自動圧縮。
+3. 🤖 Dify、Alibaba Cloud Bailian（百煉）、Coze などのAgentプラットフォームへの接続をサポート。
+4. 🌐 マルチプラットフォーム：QQ、企業微信（WeCom）、飛書（Lark）、釘釘（DingTalk）、WeChat公式アカウント、Telegram、Slack、[その他](#サポートされているメッセージプラットフォーム)に対応。
+5. 📦 プラグイン拡張：800近い既存プラグインをワンクリックでインストール可能。
+6. 🛡️  隔離環境[Agent Sandbox](https://docs.astrbot.app/use/astrbot-agent-sandbox.html)：コードの安全な実行、Shell呼び出し、セッションレベルのリソース再利用。
+7. 💻 WebUI 対応。
+8. 🌈 Web ChatUI 対応：ChatUI内にAgent Sandboxやウェブ検索などを内蔵。
+9. 🌐 多言語対応（i18n）。
+
+<br>
+
+<table align="center">
+  <tr align="center">
+    <th>💙 ロールプレイ & 感情的な対話</th>
+    <th>✨ プロアクティブ・エージェント (Proactive Agent)</th>
+    <th>🚀 汎用 エージェント的能力</th>
+    <th>🧩 900+ コミュニティプラグイン</th>
+  </tr>
+  <tr>
+    <td align="center"><p align="center"><img width="984" height="1746" alt="99b587c5d35eea09d84f33e6cf6cfd4f" src="https://github.com/user-attachments/assets/89196061-3290-458d-b51f-afa178049f84" /></p></td>
+    <td align="center"><p align="center"><img width="976" height="1612" alt="c449acd838c41d0915cc08a3824025b1" src="https://github.com/user-attachments/assets/f75368b4-e022-41dc-a9e0-131c3e73e32e" /></p></td>
+    <td align="center"><p align="center"><img width="974" height="1732" alt="image" src="https://github.com/user-attachments/assets/e22a3968-87d7-4708-a7cd-e7f198c7c32e" /></p></td>
+    <td align="center"><p align="center"><img width="976" height="1734" alt="image" src="https://github.com/user-attachments/assets/0952b395-6b4a-432a-8a50-c294b7f89750" /></p></td>
+  </tr>
+</table>
 
 ## クイックスタート
 
@@ -61,7 +79,18 @@ Docker / Docker Compose を使用した AstrBot のデプロイを推奨しま
 #### uv デプロイ
 
 ```bash
-uvx astrbot
+uv tool install astrbot
+astrbot
+```
+
+#### システムパッケージマネージャーでのインストール
+
+##### Arch Linux
+
+```bash
+yay -S astrbot-git
+# または paru を使用
+paru -S astrbot-git
 ```
 
 #### 宝塔パネルデプロイ
@@ -115,6 +144,16 @@ uv run main.py
 
 または、公式ドキュメント [ソースコードから AstrBot をデプロイ](https://astrbot.app/deploy/astrbot/cli.html) をご参照ください。
 
+#### Установка через системный пакетный менеджер
+
+##### Arch Linux
+
+```bash
+yay -S astrbot-git
+# или используйте paru
+paru -S astrbot-git
+```
+
 ## サポートされているメッセージプラットフォーム
 
 **公式メンテナンス**
@@ -242,6 +281,12 @@ AstrBot への貢献をしていただいたすべてのコントリビュータ
 
 </div>
 
-</details>
+<div align="center">
+
+_共感力と能力は決して対立するものではありません。私たちが目指すのは、感情を理解し、心の支えとなるだけでなく、確実に仕事をこなせるロボットの創造です。_
 
 _私は、高性能ですから!_
+
+<img src="https://files.astrbot.app/watashiwa-koseino-desukara.gif" width="100"/>
+
+</div>

README_ru.md

@@ -1,9 +1,13 @@
 ![AstrBot-Logo-Simplified](https://github.com/user-attachments/assets/ffd99b6b-3272-4682-beaa-6fe74250f7d9)
 
-</p>
-
 <div align="center">
 
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README.md">中文</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_en.md">English</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ja.md">日本語</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_zh-TW.md">繁體中文</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_fr.md">Français</a>
+
 <br>
 
 <div>
@@ -14,22 +18,17 @@
 <br>
 
 <div>
-<img src="https://img.shields.io/github/v/release/AstrBotDevs/AstrBot?style=for-the-badge&color=76bad9" href="https://github.com/AstrBotDevs/AstrBot/releases/latest">
-<img src="https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge&color=76bad9" alt="python">
-<a href="https://hub.docker.com/r/soulter/astrbot"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/soulter/astrbot.svg?style=for-the-badge&color=76bad9"/></a>
-<a href="https://qm.qq.com/cgi-bin/qm/qr?k=wtbaNx7EioxeaqS9z7RQWVXPIxg2zYr7&jump_from=webapi&authKey=vlqnv/AV2DbJEvGIcxdlNSpfxVy+8vVqijgreRdnVKOaydpc+YSw4MctmEbr0k5"><img alt="QQ_community" src="https://img.shields.io/badge/QQ群-775869627-purple?style=for-the-badge&color=76bad9"></a>
-<a href="https://t.me/+hAsD2Ebl5as3NmY1"><img alt="Telegram_community" src="https://img.shields.io/badge/Telegram-AstrBot-purple?style=for-the-badge&color=76bad9"></a>
-<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fplugin-num&query=%24.result&suffix=%20%D0%BF%D0%BB%D0%B0%D0%B3%D0%B8%D0%BD%D0%BE%D0%B2&style=for-the-badge&label=%D0%9C%D0%B0%D0%B3%D0%B0%D0%B7%D0%B8%D0%BD&cacheSeconds=3600">
+<img src="https://img.shields.io/github/v/release/AstrBotDevs/AstrBot?color=76bad9" href="https://github.com/AstrBotDevs/AstrBot/releases/latest">
+<img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="python">
+<img src="https://deepwiki.com/badge.svg" href="https://deepwiki.com/AstrBotDevs/AstrBot">
+<a href="https://zread.ai/AstrBotDevs/AstrBot" target="_blank"><img src="https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff" alt="zread"/></a>
+<a href="https://hub.docker.com/r/soulter/astrbot"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/soulter/astrbot.svg?color=76bad9"/></a>
+<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fplugin-num&query=%24.result&suffix=%E4%B8%AA&label=%E6%8F%92%E4%BB%B6%E5%B8%82%E5%9C%BA&cacheSeconds=3600">
+<img src="https://gitcode.com/Soulter/AstrBot/star/badge.svg" href="https://gitcode.com/Soulter/AstrBot">
 </div>
 
 <br>
 
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README.md">中文</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_en.md">English</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ja.md">日本語</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_zh-TW.md">繁體中文</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_fr.md">Français</a>
-
 <a href="https://astrbot.app/">Документация</a> ｜
 <a href="https://blog.astrbot.app/">Блог</a> ｜
 <a href="https://astrbot.featurebase.app/roadmap">Дорожная карта</a> ｜
@@ -42,13 +41,32 @@ AstrBot — это универсальная платформа Agent-чатб
 
 ## Основные возможности
 
-1. 💯 Бесплатно и с открытым исходным кодом.
-2. ✨ ИИ-диалоги с LLM, мультимодальность, Agent, MCP, база знаний, настройки личности.
-3. 🤖 Поддержка интеграции с Dify, Alibaba Cloud Bailian, Coze и другими платформами агентов.
-4. 🌐 Мультиплатформенность: QQ, WeChat Work, Feishu, DingTalk, официальные аккаунты WeChat, Telegram, Slack и [другие](#поддерживаемые-платформы-обмена-сообщениями).
-5. 📦 Расширения плагинов с почти 800 плагинами, доступными для установки в один клик.
-6. 💻 Поддержка WebUI.
-7. 🌐 Поддержка интернационализации (i18n).
+1. 💯 Бесплатно & Открытый исходный код.
+2. ✨ Диалоги с ИИ-моделями, мультимодальность, Agent, MCP, Skills, База знаний, Настройка личности, автоматическое сжатие диалогов.
+3. 🤖 Поддержка интеграции с платформами Agents, такими как Dify, Alibaba Cloud Bailian, Coze и др.
+4. 🌐 Мультиплатформенность: поддержка QQ, WeChat для предприятий, Feishu, DingTalk, публичных аккаунтов WeChat, Telegram, Slack и [других](#Поддерживаемые-платформы-обмена-сообщениями).
+5. 📦 Расширение плагинами: доступно почти 800 плагинов для установки в один клик.
+6. 🛡️  Изолированная среда[Agent Sandbox](https://docs.astrbot.app/use/astrbot-agent-sandbox.html): безопасное выполнение любого кода, вызов Shell, повторное использование ресурсов на уровне сессии.
+7. 💻 Поддержка WebUI.
+8. 🌈 Поддержка Web ChatUI: встроенная песочница агента, веб-поиск и др.
+9. 🌐 Поддержка интернационализации (i18n).
+
+<br>
+
+<table align="center">
+  <tr align="center">
+    <th>💙 Ролевые игры & Эмоциональная поддержка</th>
+    <th>✨ Проактивный Агент(Agent)</th>
+    <th>🚀 Универсальные Агентные возможности</th>
+    <th>🧩 Универсальные Агентные (Agentic) возможности</th>
+  </tr>
+  <tr>
+    <td align="center"><p align="center"><img width="984" height="1746" alt="99b587c5d35eea09d84f33e6cf6cfd4f" src="https://github.com/user-attachments/assets/89196061-3290-458d-b51f-afa178049f84" /></p></td>
+    <td align="center"><p align="center"><img width="976" height="1612" alt="c449acd838c41d0915cc08a3824025b1" src="https://github.com/user-attachments/assets/f75368b4-e022-41dc-a9e0-131c3e73e32e" /></p></td>
+    <td align="center"><p align="center"><img width="974" height="1732" alt="image" src="https://github.com/user-attachments/assets/e22a3968-87d7-4708-a7cd-e7f198c7c32e" /></p></td>
+    <td align="center"><p align="center"><img width="976" height="1734" alt="image" src="https://github.com/user-attachments/assets/0952b395-6b4a-432a-8a50-c294b7f89750" /></p></td>
+  </tr>
+</table>
 
 ## Быстрый старт
 
@@ -61,7 +79,8 @@ AstrBot — это универсальная платформа Agent-чатб
 #### Развёртывание uv
 
 ```bash
-uvx astrbot
+uv tool install astrbot
+astrbot
 ```
 
 #### Развёртывание BT-Panel
@@ -115,6 +134,16 @@ uv run main.py
 
 Или см. официальную документацию: [Развёртывание AstrBot из исходного кода](https://astrbot.app/deploy/astrbot/cli.html).
 
+#### Установка через системный пакетный менеджер
+
+##### Arch Linux
+
+```bash
+yay -S astrbot-git
+# или используйте paru
+paru -S astrbot-git
+```
+
 ## Поддерживаемые платформы обмена сообщениями
 
 **Официально поддерживаемые**
@@ -153,7 +182,7 @@ uv run main.py
 - [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_astrbot&referral_code=FV7DcGowN4hB5UuXKgpE74)
 - [302.AI](https://share.302.ai/rr1M3l)
 - [TokenPony](https://www.tokenpony.cn/3YPyf)
-- [SiliconFlow](https://docs.siliconflow.cn/cn/usecases/use-siliconcloud-in-astrbot)
+- [SiliconFlow](https://docs.siliconflow.cn/cn/usercases/use-siliconcloud-in-astrbot)
 - [PPIO Cloud](https://ppio.com/user/register?invited_by=AIOONE)
 - ModelScope
 - OneAPI
@@ -235,13 +264,19 @@ pre-commit install
 > [!TIP]
 > Если этот проект помог вам в жизни или работе, или если вас интересует его будущее развитие, пожалуйста, поставьте проекту звезду. Это движущая сила поддержки этого проекта с открытым исходным кодом <3
 
+
 <div align="center">
 
 [![Star History Chart](https://api.star-history.com/svg?repos=astrbotdevs/astrbot&type=Date)](https://star-history.com/#astrbotdevs/astrbot&Date)
 
 </div>
 
-</details>
+<div align="center">
+
+_Сопровождение и способности никогда не должны быть противоположностями. Мы стремимся создать робота, который сможет как понимать эмоции, оказывать душевную поддержку, так и надёжно выполнять работу._
 
 _私は、高性能ですから!_
 
+<img src="https://files.astrbot.app/watashiwa-koseino-desukara.gif" width="100"/>
+
+</div>

README_zh-TW.md

@@ -1,9 +1,13 @@
 ![AstrBot-Logo-Simplified](https://github.com/user-attachments/assets/ffd99b6b-3272-4682-beaa-6fe74250f7d9)
 
-</p>
-
 <div align="center">
 
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README.md">简体中文</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_en.md">English</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ja.md">日本語</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_fr.md">Français</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ru.md">Русский</a>
+
 <br>
 
 <div>
@@ -14,22 +18,17 @@
 <br>
 
 <div>
-<img src="https://img.shields.io/github/v/release/AstrBotDevs/AstrBot?style=for-the-badge&color=76bad9" href="https://github.com/AstrBotDevs/AstrBot/releases/latest">
-<img src="https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge&color=76bad9" alt="python">
-<a href="https://hub.docker.com/r/soulter/astrbot"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/soulter/astrbot.svg?style=for-the-badge&color=76bad9"/></a>
-<a href="https://qm.qq.com/cgi-bin/qm/qr?k=wtbaNx7EioxeaqS9z7RQWVXPIxg2zYr7&jump_from=webapi&authKey=vlqnv/AV2DbJEvGIcxdlNSpfxVy+8vVqijgreRdnVKOaydpc+YSw4MctmEbr0k5"><img alt="QQ_community" src="https://img.shields.io/badge/QQ群-775869627-purple?style=for-the-badge&color=76bad9"></a>
-<a href="https://t.me/+hAsD2Ebl5as3NmY1"><img alt="Telegram_community" src="https://img.shields.io/badge/Telegram-AstrBot-purple?style=for-the-badge&color=76bad9"></a>
-<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fplugin-num&query=%24.result&suffix=%E5%80%8B&style=for-the-badge&label=%E6%8F%92%E4%BB%B6%E5%B8%82%E5%A0%B4&cacheSeconds=3600">
+<img src="https://img.shields.io/github/v/release/AstrBotDevs/AstrBot?color=76bad9" href="https://github.com/AstrBotDevs/AstrBot/releases/latest">
+<img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="python">
+<img src="https://deepwiki.com/badge.svg" href="https://deepwiki.com/AstrBotDevs/AstrBot">
+<a href="https://zread.ai/AstrBotDevs/AstrBot" target="_blank"><img src="https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff" alt="zread"/></a>
+<a href="https://hub.docker.com/r/soulter/astrbot"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/soulter/astrbot.svg?color=76bad9"/></a>
+<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fplugin-num&query=%24.result&suffix=%E5%80%8B&label=%E6%8F%92%E4%BB%B6%E5%B8%82%E5%A0%B4&cacheSeconds=3600">
+<img src="https://gitcode.com/Soulter/AstrBot/star/badge.svg" href="https://gitcode.com/Soulter/AstrBot">
 </div>
 
 <br>
 
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README.md">简体中文</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_en.md">English</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ja.md">日本語</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_fr.md">Français</a> ｜
-<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ru.md">Русский</a>
-
 <a href="https://astrbot.app/">文件</a> ｜
 <a href="https://blog.astrbot.app/">Blog</a> ｜
 <a href="https://astrbot.featurebase.app/roadmap">路線圖</a> ｜
@@ -43,12 +42,31 @@ AstrBot 是一個開源的一站式 Agent 聊天機器人平台，可接入主
 ## 主要功能
 
 1. 💯 免費 & 開源。
-2. ✨ AI 大型模型對話，多模態，Agent，MCP，知識庫，人格設定。
-3. 🤖 支援接入 Dify、阿里雲百煉、Coze 等智慧體平台。
-4. 🌐 多平台：QQ、企業微信、飛書、釘釘、微信公眾號、Telegram、Slack 以及[更多](#支援的訊息平台)。
-5. 📦 外掛擴充，已有近 800 個外掛可一鍵安裝。
-6. 💻 WebUI 支援。
-7. 🌐 國際化（i18n）支援。
+2. ✨ AI 大模型對話，多模態，Agent，MCP，Skills，知識庫，人格設定，自動壓縮對話。
+3. 🤖 支援接入 Dify、阿里雲百煉、Coze 等智慧體 (Agent) 平台。
+4. 🌐 多平台，支援 QQ、企業微信、飛書、釘釘、微信公眾號、Telegram、Slack 以及[更多](#支援的訊息平台)。
+5. 📦 插件擴展，已有近 800 個插件可一鍵安裝。
+6. 🛡️ [Agent Sandbox](https://docs.astrbot.app/use/astrbot-agent-sandbox.html) 隔離化環境，安全地執行任何代碼、調用 Shell、會話級資源複用。
+7. 💻 WebUI 支援。
+8. 🌈 Web ChatUI 支援，ChatUI 內置代理沙盒 (Agent Sandbox)、網頁搜尋等。
+9. 🌐 國際化（i18n）支援。
+
+<br>
+
+<table align="center">
+  <tr align="center">
+    <th>💙 角色扮演 & 情感陪伴</th>
+    <th>✨ 主動式 Agent</th>
+    <th>🚀 通用 Agentic 能力</th>
+    <th>🧩 900+ 社區外掛程式</th>
+  </tr>
+  <tr>
+    <td align="center"><p align="center"><img width="984" height="1746" alt="99b587c5d35eea09d84f33e6cf6cfd4f" src="https://github.com/user-attachments/assets/89196061-3290-458d-b51f-afa178049f84" /></p></td>
+    <td align="center"><p align="center"><img width="976" height="1612" alt="c449acd838c41d0915cc08a3824025b1" src="https://github.com/user-attachments/assets/f75368b4-e022-41dc-a9e0-131c3e73e32e" /></p></td>
+    <td align="center"><p align="center"><img width="974" height="1732" alt="image" src="https://github.com/user-attachments/assets/e22a3968-87d7-4708-a7cd-e7f198c7c32e" /></p></td>
+    <td align="center"><p align="center"><img width="976" height="1734" alt="image" src="https://github.com/user-attachments/assets/0952b395-6b4a-432a-8a50-c294b7f89750" /></p></td>
+  </tr>
+</table>
 
 ## 快速開始
 
@@ -61,7 +79,8 @@ AstrBot 是一個開源的一站式 Agent 聊天機器人平台，可接入主
 #### uv 部署
 
 ```bash
-uvx astrbot
+uv tool install astrbot
+astrbot
 ```
 
 #### 寶塔面板部署
@@ -115,6 +134,16 @@ uv run main.py
 
 或者請參閱官方文件 [透過原始碼部署 AstrBot](https://astrbot.app/deploy/astrbot/cli.html)。
 
+#### 系統套件管理員安裝
+
+##### Arch Linux
+
+```bash
+yay -S astrbot-git
+# 或者使用 paru
+paru -S astrbot-git
+```
+
 ## 支援的訊息平台
 
 **官方維護**
@@ -241,7 +270,12 @@ pre-commit install
 
 </div>
 
-</details>
+<div align="center">
+
+_陪伴與能力從來不應該是對立面。我們希望創造的是一個既能理解情緒、給予陪伴，也能可靠完成工作的機器人。_
 
 _私は、高性能ですから!_
 
+<img src="https://files.astrbot.app/watashiwa-koseino-desukara.gif" width="100"/>
+
+</div>

astrbot/builtin_stars/astrbot/long_term_memory.py

@@ -17,7 +17,7 @@ from astrbot.core.astrbot_config_mgr import AstrBotConfigManager
 
 
 class LongTermMemory:
-    def __init__(self, acm: AstrBotConfigManager, context: star.Context):
+    def __init__(self, acm: AstrBotConfigManager, context: star.Context) -> None:
         self.acm = acm
         self.context = context
         self.session_chats = defaultdict(list)
@@ -111,7 +111,7 @@ class LongTermMemory:
 
         return False
 
-    async def handle_message(self, event: AstrMessageEvent):
+    async def handle_message(self, event: AstrMessageEvent) -> None:
         """仅支持群聊"""
         if event.get_message_type() == MessageType.GROUP_MESSAGE:
             datetime_str = datetime.datetime.now().strftime("%H:%M:%S")
@@ -148,7 +148,7 @@ class LongTermMemory:
             if len(self.session_chats[event.unified_msg_origin]) > cfg["max_cnt"]:
                 self.session_chats[event.unified_msg_origin].pop(0)
 
-    async def on_req_llm(self, event: AstrMessageEvent, req: ProviderRequest):
+    async def on_req_llm(self, event: AstrMessageEvent, req: ProviderRequest) -> None:
         """当触发 LLM 请求前，调用此方法修改 req"""
         if event.unified_msg_origin not in self.session_chats:
             return
@@ -171,7 +171,9 @@ class LongTermMemory:
             )
             req.system_prompt += chats_str
 
-    async def after_req_llm(self, event: AstrMessageEvent, llm_resp: LLMResponse):
+    async def after_req_llm(
+        self, event: AstrMessageEvent, llm_resp: LLMResponse
+    ) -> None:
         if event.unified_msg_origin not in self.session_chats:
             return
 

astrbot/builtin_stars/astrbot/main.py

@@ -85,7 +85,9 @@ class Main(star.Star):
                     logger.error(f"主动回复失败: {e}")
 
     @filter.on_llm_request()
-    async def decorate_llm_req(self, event: AstrMessageEvent, req: ProviderRequest):
+    async def decorate_llm_req(
+        self, event: AstrMessageEvent, req: ProviderRequest
+    ) -> None:
         """在请求 LLM 前注入人格信息、Identifier、时间、回复内容等 System Prompt"""
         if self.ltm and self.ltm_enabled(event):
             try:
@@ -94,7 +96,9 @@ class Main(star.Star):
                 logger.error(f"ltm: {e}")
 
     @filter.on_llm_response()
-    async def record_llm_resp_to_ltm(self, event: AstrMessageEvent, resp: LLMResponse):
+    async def record_llm_resp_to_ltm(
+        self, event: AstrMessageEvent, resp: LLMResponse
+    ) -> None:
         """在 LLM 响应后记录对话"""
         if self.ltm and self.ltm_enabled(event):
             try:
@@ -103,7 +107,7 @@ class Main(star.Star):
                 logger.error(f"ltm: {e}")
 
     @filter.after_message_sent()
-    async def after_message_sent(self, event: AstrMessageEvent):
+    async def after_message_sent(self, event: AstrMessageEvent) -> None:
         """消息发送后处理"""
         if self.ltm and self.ltm_enabled(event):
             try:

astrbot/builtin_stars/builtin_commands/commands/admin.py

@@ -5,10 +5,10 @@ from astrbot.core.utils.io import download_dashboard
 
 
 class AdminCommands:
-    def __init__(self, context: star.Context):
+    def __init__(self, context: star.Context) -> None:
         self.context = context
 
-    async def op(self, event: AstrMessageEvent, admin_id: str = ""):
+    async def op(self, event: AstrMessageEvent, admin_id: str = "") -> None:
         """授权管理员。op <admin_id>"""
         if not admin_id:
             event.set_result(
@@ -21,7 +21,7 @@ class AdminCommands:
         self.context.get_config().save_config()
         event.set_result(MessageEventResult().message("授权成功。"))
 
-    async def deop(self, event: AstrMessageEvent, admin_id: str = ""):
+    async def deop(self, event: AstrMessageEvent, admin_id: str = "") -> None:
         """取消授权管理员。deop <admin_id>"""
         if not admin_id:
             event.set_result(
@@ -39,7 +39,7 @@ class AdminCommands:
                 MessageEventResult().message("此用户 ID 不在管理员名单内。"),
             )
 
-    async def wl(self, event: AstrMessageEvent, sid: str = ""):
+    async def wl(self, event: AstrMessageEvent, sid: str = "") -> None:
         """添加白名单。wl <sid>"""
         if not sid:
             event.set_result(
@@ -53,7 +53,7 @@ class AdminCommands:
         cfg.save_config()
         event.set_result(MessageEventResult().message("添加白名单成功。"))
 
-    async def dwl(self, event: AstrMessageEvent, sid: str = ""):
+    async def dwl(self, event: AstrMessageEvent, sid: str = "") -> None:
         """删除白名单。dwl <sid>"""
         if not sid:
             event.set_result(
@@ -70,7 +70,7 @@ class AdminCommands:
         except ValueError:
             event.set_result(MessageEventResult().message("此 SID 不在白名单内。"))
 
-    async def update_dashboard(self, event: AstrMessageEvent):
+    async def update_dashboard(self, event: AstrMessageEvent) -> None:
         """更新管理面板"""
         await event.send(MessageChain().message("正在尝试更新管理面板..."))
         await download_dashboard(version=f"v{VERSION}", latest=False)

astrbot/builtin_stars/builtin_commands/commands/alter_cmd.py

@@ -11,10 +11,10 @@ from .utils.rst_scene import RstScene
 
 
 class AlterCmdCommands(CommandParserMixin):
-    def __init__(self, context: star.Context):
+    def __init__(self, context: star.Context) -> None:
         self.context = context
 
-    async def update_reset_permission(self, scene_key: str, perm_type: str):
+    async def update_reset_permission(self, scene_key: str, perm_type: str) -> None:
         """更新reset命令在特定场景下的权限设置"""
         from astrbot.api import sp
 
@@ -26,7 +26,7 @@ class AlterCmdCommands(CommandParserMixin):
         alter_cmd_cfg["astrbot"] = plugin_cfg
         await sp.global_put("alter_cmd", alter_cmd_cfg)
 
-    async def alter_cmd(self, event: AstrMessageEvent):
+    async def alter_cmd(self, event: AstrMessageEvent) -> None:
         token = self.parse_commands(event.message_str)
         if token.len < 3:
             await event.send(

astrbot/builtin_stars/builtin_commands/commands/conversation.py

@@ -16,7 +16,7 @@ THIRD_PARTY_AGENT_RUNNER_STR = ", ".join(THIRD_PARTY_AGENT_RUNNER_KEY.keys())
 
 
 class ConversationCommands:
-    def __init__(self, context: star.Context):
+    def __init__(self, context: star.Context) -> None:
         self.context = context
 
     async def _get_current_persona_id(self, session_id):
@@ -33,7 +33,7 @@ class ConversationCommands:
             return None
         return conv.persona_id
 
-    async def reset(self, message: AstrMessageEvent):
+    async def reset(self, message: AstrMessageEvent) -> None:
         """重置 LLM 会话"""
         umo = message.unified_msg_origin
         cfg = self.context.get_config(umo=message.unified_msg_origin)
@@ -98,7 +98,7 @@ class ConversationCommands:
 
         message.set_result(MessageEventResult().message(ret))
 
-    async def his(self, message: AstrMessageEvent, page: int = 1):
+    async def his(self, message: AstrMessageEvent, page: int = 1) -> None:
         """查看对话记录"""
         if not self.context.get_using_provider(message.unified_msg_origin):
             message.set_result(
@@ -141,7 +141,7 @@ class ConversationCommands:
 
         message.set_result(MessageEventResult().message(ret).use_t2i(False))
 
-    async def convs(self, message: AstrMessageEvent, page: int = 1):
+    async def convs(self, message: AstrMessageEvent, page: int = 1) -> None:
         """查看对话列表"""
         cfg = self.context.get_config(umo=message.unified_msg_origin)
         agent_runner_type = cfg["provider_settings"]["agent_runner_type"]
@@ -216,7 +216,7 @@ class ConversationCommands:
         message.set_result(MessageEventResult().message(ret).use_t2i(False))
         return
 
-    async def new_conv(self, message: AstrMessageEvent):
+    async def new_conv(self, message: AstrMessageEvent) -> None:
         """创建新对话"""
         cfg = self.context.get_config(umo=message.unified_msg_origin)
         agent_runner_type = cfg["provider_settings"]["agent_runner_type"]
@@ -242,7 +242,7 @@ class ConversationCommands:
             MessageEventResult().message(f"切换到新对话: 新对话({cid[:4]})。"),
         )
 
-    async def groupnew_conv(self, message: AstrMessageEvent, sid: str = ""):
+    async def groupnew_conv(self, message: AstrMessageEvent, sid: str = "") -> None:
         """创建新群聊对话"""
         if sid:
             session = str(
@@ -273,7 +273,7 @@ class ConversationCommands:
         self,
         message: AstrMessageEvent,
         index: int | None = None,
-    ):
+    ) -> None:
         """通过 /ls 前面的序号切换对话"""
         if not isinstance(index, int):
             message.set_result(
@@ -308,7 +308,7 @@ class ConversationCommands:
                 ),
             )
 
-    async def rename_conv(self, message: AstrMessageEvent, new_name: str = ""):
+    async def rename_conv(self, message: AstrMessageEvent, new_name: str = "") -> None:
         """重命名对话"""
         if not new_name:
             message.set_result(MessageEventResult().message("请输入新的对话名称。"))
@@ -319,7 +319,7 @@ class ConversationCommands:
         )
         message.set_result(MessageEventResult().message("重命名对话成功。"))
 
-    async def del_conv(self, message: AstrMessageEvent):
+    async def del_conv(self, message: AstrMessageEvent) -> None:
         """删除当前对话"""
         cfg = self.context.get_config(umo=message.unified_msg_origin)
         is_unique_session = cfg["platform_settings"]["unique_session"]

astrbot/builtin_stars/builtin_commands/commands/help.py

@@ -8,7 +8,7 @@ from astrbot.core.utils.io import get_dashboard_version
 
 
 class HelpCommand:
-    def __init__(self, context: star.Context):
+    def __init__(self, context: star.Context) -> None:
         self.context = context
 
     async def _query_astrbot_notice(self):
@@ -34,7 +34,7 @@ class HelpCommand:
         lines: list[str] = []
         hidden_commands = {"set", "unset", "websearch"}
 
-        def walk(items: list[dict], indent: int = 0):
+        def walk(items: list[dict], indent: int = 0) -> None:
             for item in items:
                 if not item.get("reserved") or not item.get("enabled"):
                     continue
@@ -62,7 +62,7 @@ class HelpCommand:
         walk(commands)
         return lines
 
-    async def help(self, event: AstrMessageEvent):
+    async def help(self, event: AstrMessageEvent) -> None:
         """查看帮助"""
         notice = ""
         try:

astrbot/builtin_stars/builtin_commands/commands/llm.py

@@ -3,10 +3,10 @@ from astrbot.api.event import AstrMessageEvent, MessageChain
 
 
 class LLMCommands:
-    def __init__(self, context: star.Context):
+    def __init__(self, context: star.Context) -> None:
         self.context = context
 
-    async def llm(self, event: AstrMessageEvent):
+    async def llm(self, event: AstrMessageEvent) -> None:
         """开启/关闭 LLM"""
         cfg = self.context.get_config(umo=event.unified_msg_origin)
         enable = cfg["provider_settings"].get("enable", True)

astrbot/builtin_stars/builtin_commands/commands/persona.py

@@ -9,7 +9,7 @@ if TYPE_CHECKING:
 
 
 class PersonaCommands:
-    def __init__(self, context: star.Context):
+    def __init__(self, context: star.Context) -> None:
         self.context = context
 
     def _build_tree_output(
@@ -50,7 +50,7 @@ class PersonaCommands:
 
         return lines
 
-    async def persona(self, message: AstrMessageEvent):
+    async def persona(self, message: AstrMessageEvent) -> None:
         l = message.message_str.split(" ")  # noqa: E741
         umo = message.unified_msg_origin
 

astrbot/builtin_stars/builtin_commands/commands/plugin.py

@@ -8,10 +8,10 @@ from astrbot.core.star.star_manager import PluginManager
 
 
 class PluginCommands:
-    def __init__(self, context: star.Context):
+    def __init__(self, context: star.Context) -> None:
         self.context = context
 
-    async def plugin_ls(self, event: AstrMessageEvent):
+    async def plugin_ls(self, event: AstrMessageEvent) -> None:
         """获取已经安装的插件列表。"""
         parts = ["已加载的插件：\n"]
         for plugin in self.context.get_all_stars():
@@ -30,7 +30,7 @@ class PluginCommands:
             MessageEventResult().message(f"{plugin_list_info}").use_t2i(False),
         )
 
-    async def plugin_off(self, event: AstrMessageEvent, plugin_name: str = ""):
+    async def plugin_off(self, event: AstrMessageEvent, plugin_name: str = "") -> None:
         """禁用插件"""
         if DEMO_MODE:
             event.set_result(MessageEventResult().message("演示模式下无法禁用插件。"))
@@ -43,7 +43,7 @@ class PluginCommands:
         await self.context._star_manager.turn_off_plugin(plugin_name)  # type: ignore
         event.set_result(MessageEventResult().message(f"插件 {plugin_name} 已禁用。"))
 
-    async def plugin_on(self, event: AstrMessageEvent, plugin_name: str = ""):
+    async def plugin_on(self, event: AstrMessageEvent, plugin_name: str = "") -> None:
         """启用插件"""
         if DEMO_MODE:
             event.set_result(MessageEventResult().message("演示模式下无法启用插件。"))
@@ -56,7 +56,7 @@ class PluginCommands:
         await self.context._star_manager.turn_on_plugin(plugin_name)  # type: ignore
         event.set_result(MessageEventResult().message(f"插件 {plugin_name} 已启用。"))
 
-    async def plugin_get(self, event: AstrMessageEvent, plugin_repo: str = ""):
+    async def plugin_get(self, event: AstrMessageEvent, plugin_repo: str = "") -> None:
         """安装插件"""
         if DEMO_MODE:
             event.set_result(MessageEventResult().message("演示模式下无法安装插件。"))
@@ -77,7 +77,7 @@ class PluginCommands:
                 event.set_result(MessageEventResult().message(f"安装插件失败: {e}"))
                 return
 
-    async def plugin_help(self, event: AstrMessageEvent, plugin_name: str = ""):
+    async def plugin_help(self, event: AstrMessageEvent, plugin_name: str = "") -> None:
         """获取插件帮助"""
         if not plugin_name:
             event.set_result(

astrbot/builtin_stars/builtin_commands/commands/provider.py

@@ -8,7 +8,7 @@ from astrbot.core.provider.entities import ProviderType
 
 
 class ProviderCommands:
-    def __init__(self, context: star.Context):
+    def __init__(self, context: star.Context) -> None:
         self.context = context
 
     def _log_reachability_failure(
@@ -17,7 +17,7 @@ class ProviderCommands:
         provider_capability_type: ProviderType | None,
         err_code: str,
         err_reason: str,
-    ):
+    ) -> None:
         """记录不可达原因到日志。"""
         meta = provider.meta()
         logger.warning(
@@ -49,7 +49,7 @@ class ProviderCommands:
         event: AstrMessageEvent,
         idx: str | int | None = None,
         idx2: int | None = None,
-    ):
+    ) -> None:
         """查看或者切换 LLM Provider"""
         umo = event.unified_msg_origin
         cfg = self.context.get_config(umo).get("provider_settings", {})
@@ -228,7 +228,7 @@ class ProviderCommands:
         self,
         message: AstrMessageEvent,
         idx_or_name: int | str | None = None,
-    ):
+    ) -> None:
         """查看或者切换模型"""
         prov = self.context.get_using_provider(message.unified_msg_origin)
         if not prov:
@@ -293,7 +293,7 @@ class ProviderCommands:
                 MessageEventResult().message(f"切换模型到 {prov.get_model()}。"),
             )
 
-    async def key(self, message: AstrMessageEvent, index: int | None = None):
+    async def key(self, message: AstrMessageEvent, index: int | None = None) -> None:
         prov = self.context.get_using_provider(message.unified_msg_origin)
         if not prov:
             message.set_result(

astrbot/builtin_stars/builtin_commands/commands/setunset.py

@@ -3,10 +3,10 @@ from astrbot.api.event import AstrMessageEvent, MessageEventResult
 
 
 class SetUnsetCommands:
-    def __init__(self, context: star.Context):
+    def __init__(self, context: star.Context) -> None:
         self.context = context
 
-    async def set_variable(self, event: AstrMessageEvent, key: str, value: str):
+    async def set_variable(self, event: AstrMessageEvent, key: str, value: str) -> None:
         """设置会话变量"""
         uid = event.unified_msg_origin
         session_var = await sp.session_get(uid, "session_variables", {})
@@ -19,7 +19,7 @@ class SetUnsetCommands:
             ),
         )
 
-    async def unset_variable(self, event: AstrMessageEvent, key: str):
+    async def unset_variable(self, event: AstrMessageEvent, key: str) -> None:
         """移除会话变量"""
         uid = event.unified_msg_origin
         session_var = await sp.session_get(uid, "session_variables", {})

astrbot/builtin_stars/builtin_commands/commands/sid.py

@@ -7,10 +7,10 @@ from astrbot.api.event import AstrMessageEvent, MessageEventResult
 class SIDCommand:
     """会话ID命令类"""
 
-    def __init__(self, context: star.Context):
+    def __init__(self, context: star.Context) -> None:
         self.context = context
 
-    async def sid(self, event: AstrMessageEvent):
+    async def sid(self, event: AstrMessageEvent) -> None:
         """获取消息来源信息"""
         sid = event.unified_msg_origin
         user_id = str(event.get_sender_id())

astrbot/builtin_stars/builtin_commands/commands/t2i.py

@@ -7,10 +7,10 @@ from astrbot.api.event import AstrMessageEvent, MessageEventResult
 class T2ICommand:
     """文本转图片命令类"""
 
-    def __init__(self, context: star.Context):
+    def __init__(self, context: star.Context) -> None:
         self.context = context
 
-    async def t2i(self, event: AstrMessageEvent):
+    async def t2i(self, event: AstrMessageEvent) -> None:
         """开关文本转图片"""
         config = self.context.get_config(umo=event.unified_msg_origin)
         if config["t2i"]:

astrbot/builtin_stars/builtin_commands/commands/tts.py

@@ -8,10 +8,10 @@ from astrbot.core.star.session_llm_manager import SessionServiceManager
 class TTSCommand:
     """文本转语音命令类"""
 
-    def __init__(self, context: star.Context):
+    def __init__(self, context: star.Context) -> None:
         self.context = context
 
-    async def tts(self, event: AstrMessageEvent):
+    async def tts(self, event: AstrMessageEvent) -> None:
         """开关文本转语音（会话级别）"""
         umo = event.unified_msg_origin
         ses_tts = await SessionServiceManager.is_tts_enabled_for_session(umo)

astrbot/builtin_stars/builtin_commands/main.py

@@ -35,84 +35,84 @@ class Main(star.Star):
         self.sid_c = SIDCommand(self.context)
 
     @filter.command("help")
-    async def help(self, event: AstrMessageEvent):
+    async def help(self, event: AstrMessageEvent) -> None:
         """查看帮助"""
         await self.help_c.help(event)
 
     @filter.permission_type(filter.PermissionType.ADMIN)
     @filter.command("llm")
-    async def llm(self, event: AstrMessageEvent):
+    async def llm(self, event: AstrMessageEvent) -> None:
         """开启/关闭 LLM"""
         await self.llm_c.llm(event)
 
     @filter.command_group("plugin")
-    def plugin(self):
+    def plugin(self) -> None:
         """插件管理"""
 
     @plugin.command("ls")
-    async def plugin_ls(self, event: AstrMessageEvent):
+    async def plugin_ls(self, event: AstrMessageEvent) -> None:
         """获取已经安装的插件列表。"""
         await self.plugin_c.plugin_ls(event)
 
     @filter.permission_type(filter.PermissionType.ADMIN)
     @plugin.command("off")
-    async def plugin_off(self, event: AstrMessageEvent, plugin_name: str = ""):
+    async def plugin_off(self, event: AstrMessageEvent, plugin_name: str = "") -> None:
         """禁用插件"""
         await self.plugin_c.plugin_off(event, plugin_name)
 
     @filter.permission_type(filter.PermissionType.ADMIN)
     @plugin.command("on")
-    async def plugin_on(self, event: AstrMessageEvent, plugin_name: str = ""):
+    async def plugin_on(self, event: AstrMessageEvent, plugin_name: str = "") -> None:
         """启用插件"""
         await self.plugin_c.plugin_on(event, plugin_name)
 
     @filter.permission_type(filter.PermissionType.ADMIN)
     @plugin.command("get")
-    async def plugin_get(self, event: AstrMessageEvent, plugin_repo: str = ""):
+    async def plugin_get(self, event: AstrMessageEvent, plugin_repo: str = "") -> None:
         """安装插件"""
         await self.plugin_c.plugin_get(event, plugin_repo)
 
     @plugin.command("help")
-    async def plugin_help(self, event: AstrMessageEvent, plugin_name: str = ""):
+    async def plugin_help(self, event: AstrMessageEvent, plugin_name: str = "") -> None:
         """获取插件帮助"""
         await self.plugin_c.plugin_help(event, plugin_name)
 
     @filter.command("t2i")
-    async def t2i(self, event: AstrMessageEvent):
+    async def t2i(self, event: AstrMessageEvent) -> None:
         """开关文本转图片"""
         await self.t2i_c.t2i(event)
 
     @filter.command("tts")
-    async def tts(self, event: AstrMessageEvent):
+    async def tts(self, event: AstrMessageEvent) -> None:
         """开关文本转语音（会话级别）"""
         await self.tts_c.tts(event)
 
     @filter.command("sid")
-    async def sid(self, event: AstrMessageEvent):
+    async def sid(self, event: AstrMessageEvent) -> None:
         """获取会话 ID 和 管理员 ID"""
         await self.sid_c.sid(event)
 
     @filter.permission_type(filter.PermissionType.ADMIN)
     @filter.command("op")
-    async def op(self, event: AstrMessageEvent, admin_id: str = ""):
+    async def op(self, event: AstrMessageEvent, admin_id: str = "") -> None:
         """授权管理员。op <admin_id>"""
         await self.admin_c.op(event, admin_id)
 
     @filter.permission_type(filter.PermissionType.ADMIN)
     @filter.command("deop")
-    async def deop(self, event: AstrMessageEvent, admin_id: str):
+    async def deop(self, event: AstrMessageEvent, admin_id: str) -> None:
         """取消授权管理员。deop <admin_id>"""
         await self.admin_c.deop(event, admin_id)
 
     @filter.permission_type(filter.PermissionType.ADMIN)
     @filter.command("wl")
-    async def wl(self, event: AstrMessageEvent, sid: str = ""):
+    async def wl(self, event: AstrMessageEvent, sid: str = "") -> None:
         """添加白名单。wl <sid>"""
         await self.admin_c.wl(event, sid)
 
     @filter.permission_type(filter.PermissionType.ADMIN)
     @filter.command("dwl")
-    async def dwl(self, event: AstrMessageEvent, sid: str):
+    async def dwl(self, event: AstrMessageEvent, sid: str) -> None:
         """删除白名单。dwl <sid>"""
         await self.admin_c.dwl(event, sid)
 
@@ -123,12 +123,12 @@ class Main(star.Star):
         event: AstrMessageEvent,
         idx: str | int | None = None,
         idx2: int | None = None,
-    ):
+    ) -> None:
         """查看或者切换 LLM Provider"""
         await self.provider_c.provider(event, idx, idx2)
 
     @filter.command("reset")
-    async def reset(self, message: AstrMessageEvent):
+    async def reset(self, message: AstrMessageEvent) -> None:
         """重置 LLM 会话"""
         await self.conversation_c.reset(message)
 
@@ -138,74 +138,76 @@ class Main(star.Star):
         self,
         message: AstrMessageEvent,
         idx_or_name: int | str | None = None,
-    ):
+    ) -> None:
         """查看或者切换模型"""
         await self.provider_c.model_ls(message, idx_or_name)
 
     @filter.command("history")
-    async def his(self, message: AstrMessageEvent, page: int = 1):
+    async def his(self, message: AstrMessageEvent, page: int = 1) -> None:
         """查看对话记录"""
         await self.conversation_c.his(message, page)
 
     @filter.command("ls")
-    async def convs(self, message: AstrMessageEvent, page: int = 1):
+    async def convs(self, message: AstrMessageEvent, page: int = 1) -> None:
         """查看对话列表"""
         await self.conversation_c.convs(message, page)
 
     @filter.command("new")
-    async def new_conv(self, message: AstrMessageEvent):
+    async def new_conv(self, message: AstrMessageEvent) -> None:
         """创建新对话"""
         await self.conversation_c.new_conv(message)
 
     @filter.permission_type(filter.PermissionType.ADMIN)
     @filter.command("groupnew")
-    async def groupnew_conv(self, message: AstrMessageEvent, sid: str):
+    async def groupnew_conv(self, message: AstrMessageEvent, sid: str) -> None:
         """创建新群聊对话"""
         await self.conversation_c.groupnew_conv(message, sid)
 
     @filter.command("switch")
-    async def switch_conv(self, message: AstrMessageEvent, index: int | None = None):
+    async def switch_conv(
+        self, message: AstrMessageEvent, index: int | None = None
+    ) -> None:
         """通过 /ls 前面的序号切换对话"""
         await self.conversation_c.switch_conv(message, index)
 
     @filter.command("rename")
-    async def rename_conv(self, message: AstrMessageEvent, new_name: str):
+    async def rename_conv(self, message: AstrMessageEvent, new_name: str) -> None:
         """重命名对话"""
         await self.conversation_c.rename_conv(message, new_name)
 
     @filter.command("del")
-    async def del_conv(self, message: AstrMessageEvent):
+    async def del_conv(self, message: AstrMessageEvent) -> None:
         """删除当前对话"""
         await self.conversation_c.del_conv(message)
 
     @filter.permission_type(filter.PermissionType.ADMIN)
     @filter.command("key")
-    async def key(self, message: AstrMessageEvent, index: int | None = None):
+    async def key(self, message: AstrMessageEvent, index: int | None = None) -> None:
         """查看或者切换 Key"""
         await self.provider_c.key(message, index)
 
     @filter.permission_type(filter.PermissionType.ADMIN)
     @filter.command("persona")
-    async def persona(self, message: AstrMessageEvent):
+    async def persona(self, message: AstrMessageEvent) -> None:
         """查看或者切换 Persona"""
         await self.persona_c.persona(message)
 
     @filter.permission_type(filter.PermissionType.ADMIN)
     @filter.command("dashboard_update")
-    async def update_dashboard(self, event: AstrMessageEvent):
+    async def update_dashboard(self, event: AstrMessageEvent) -> None:
         """更新管理面板"""
         await self.admin_c.update_dashboard(event)
 
     @filter.command("set")
-    async def set_variable(self, event: AstrMessageEvent, key: str, value: str):
+    async def set_variable(self, event: AstrMessageEvent, key: str, value: str) -> None:
         await self.setunset_c.set_variable(event, key, value)
 
     @filter.command("unset")
-    async def unset_variable(self, event: AstrMessageEvent, key: str):
+    async def unset_variable(self, event: AstrMessageEvent, key: str) -> None:
         await self.setunset_c.unset_variable(event, key)
 
     @filter.permission_type(filter.PermissionType.ADMIN)
     @filter.command("alter_cmd", alias={"alter"})
-    async def alter_cmd(self, event: AstrMessageEvent):
+    async def alter_cmd(self, event: AstrMessageEvent) -> None:
         """修改命令权限"""
         await self.alter_cmd_c.alter_cmd(event)

astrbot/builtin_stars/session_controller/main.py

@@ -17,11 +17,11 @@ from astrbot.core.utils.session_waiter import (
 class Main(Star):
     """会话控制"""
 
-    def __init__(self, context: Context):
+    def __init__(self, context: Context) -> None:
         super().__init__(context)
 
     @filter.event_message_type(filter.EventMessageType.ALL, priority=maxsize)
-    async def handle_session_control_agent(self, event: AstrMessageEvent):
+    async def handle_session_control_agent(self, event: AstrMessageEvent) -> None:
         """会话控制代理"""
         for session_filter in FILTERS:
             session_id = session_filter.filter(event)
@@ -90,7 +90,7 @@ class Main(Star):
                     async def empty_mention_waiter(
                         controller: SessionController,
                         event: AstrMessageEvent,
-                    ):
+                    ) -> None:
                         event.message_obj.message.insert(
                             0,
                             Comp.At(qq=event.get_self_id(), name=event.get_self_id()),

astrbot/builtin_stars/web_searcher/engines/__init__.py

@@ -49,7 +49,7 @@ class SearchEngine:
     def _set_selector(self, selector: str) -> str:
         raise NotImplementedError
 
-    def _get_next_page(self, query: str):
+    async def _get_next_page(self, query: str) -> str:
         raise NotImplementedError
 
     async def _get_html(self, url: str, data: dict | None = None) -> str:

astrbot/builtin_stars/web_searcher/main.py

@@ -23,6 +23,7 @@ class Main(star.Star):
         "fetch_url",
         "web_search_tavily",
         "tavily_extract_web_page",
+        "web_search_bocha",
     ]
 
     def __init__(self, context: star.Context) -> None:
@@ -30,6 +31,9 @@ class Main(star.Star):
         self.tavily_key_index = 0
         self.tavily_key_lock = asyncio.Lock()
 
+        self.bocha_key_index = 0
+        self.bocha_key_lock = asyncio.Lock()
+
         # 将 str 类型的 key 迁移至 list[str]，并保存
         cfg = self.context.get_config()
         provider_settings = cfg.get("provider_settings")
@@ -45,6 +49,14 @@ class Main(star.Star):
                     provider_settings["websearch_tavily_key"] = []
                 cfg.save_config()
 
+            bocha_key = provider_settings.get("websearch_bocha_key")
+            if isinstance(bocha_key, str):
+                if bocha_key:
+                    provider_settings["websearch_bocha_key"] = [bocha_key]
+                else:
+                    provider_settings["websearch_bocha_key"] = []
+                cfg.save_config()
+
         self.bing_search = Bing()
         self.sogo_search = Sogo()
         self.baidu_initialized = False
@@ -187,7 +199,7 @@ class Main(star.Star):
                 return results
 
     @filter.command("websearch")
-    async def websearch(self, event: AstrMessageEvent, oper: str | None = None):
+    async def websearch(self, event: AstrMessageEvent, oper: str | None = None) -> None:
         """网页搜索指令（已废弃）"""
         event.set_result(
             MessageEventResult().message(
@@ -234,7 +246,7 @@ class Main(star.Star):
 
         return ret
 
-    async def ensure_baidu_ai_search_mcp(self, umo: str | None = None):
+    async def ensure_baidu_ai_search_mcp(self, umo: str | None = None) -> None:
         if self.baidu_initialized:
             return
         cfg = self.context.get_config(umo=umo)
@@ -341,7 +353,7 @@ class Main(star.Star):
                 }
             )
             if result.favicon:
-                sp.temorary_cache["_ws_favicon"][result.url] = result.favicon
+                sp.temporary_cache["_ws_favicon"][result.url] = result.favicon
         # ret = "\n".join(ret_ls)
         ret = json.dumps({"results": ret_ls}, ensure_ascii=False)
         return ret
@@ -382,12 +394,166 @@ class Main(star.Star):
             return "Error: Tavily web searcher does not return any results."
         return ret
 
+    async def _get_bocha_key(self, cfg: AstrBotConfig) -> str:
+        """并发安全的从列表中获取并轮换BoCha API密钥。"""
+        bocha_keys = cfg.get("provider_settings", {}).get("websearch_bocha_key", [])
+        if not bocha_keys:
+            raise ValueError("错误：BoCha API密钥未在AstrBot中配置。")
+
+        async with self.bocha_key_lock:
+            key = bocha_keys[self.bocha_key_index]
+            self.bocha_key_index = (self.bocha_key_index + 1) % len(bocha_keys)
+            return key
+
+    async def _web_search_bocha(
+        self,
+        cfg: AstrBotConfig,
+        payload: dict,
+    ) -> list[SearchResult]:
+        """使用 BoCha 搜索引擎进行搜索"""
+        bocha_key = await self._get_bocha_key(cfg)
+        url = "https://api.bochaai.com/v1/web-search"
+        header = {
+            "Authorization": f"Bearer {bocha_key}",
+            "Content-Type": "application/json",
+        }
+        async with aiohttp.ClientSession(trust_env=True) as session:
+            async with session.post(
+                url,
+                json=payload,
+                headers=header,
+            ) as response:
+                if response.status != 200:
+                    reason = await response.text()
+                    raise Exception(
+                        f"BoCha web search failed: {reason}, status: {response.status}",
+                    )
+                data = await response.json()
+                data = data["data"]["webPages"]["value"]
+                results = []
+                for item in data:
+                    result = SearchResult(
+                        title=item.get("name"),
+                        url=item.get("url"),
+                        snippet=item.get("snippet"),
+                        favicon=item.get("siteIcon"),
+                    )
+                    results.append(result)
+                return results
+
+    @llm_tool("web_search_bocha")
+    async def search_from_bocha(
+        self,
+        event: AstrMessageEvent,
+        query: str,
+        freshness: str = "noLimit",
+        summary: bool = False,
+        include: str = "",
+        exclude: str = "",
+        count: int = 10,
+    ) -> str:
+        """
+        A web search tool based on Bocha Search API, used to retrieve web pages
+        related to the user's query.
+
+        Args:
+            query (string): Required. User's search query.
+
+            freshness (string): Optional. Specifies the time range of the search.
+                Supported values:
+                - "noLimit": No time limit (default, recommended).
+                - "oneDay": Within one day.
+                - "oneWeek": Within one week.
+                - "oneMonth": Within one month.
+                - "oneYear": Within one year.
+                - "YYYY-MM-DD..YYYY-MM-DD": Search within a specific date range.
+                  Example: "2025-01-01..2025-04-06".
+                - "YYYY-MM-DD": Search on a specific date.
+                  Example: "2025-04-06".
+                It is recommended to use "noLimit", as the search algorithm will
+                automatically optimize time relevance. Manually restricting the
+                time range may result in no search results.
+
+            summary (boolean): Optional. Whether to include a text summary
+                for each search result.
+                - True: Include summary.
+                - False: Do not include summary (default).
+
+            include (string): Optional. Specifies the domains to include in
+                the search. Multiple domains can be separated by "|" or ",".
+                A maximum of 100 domains is allowed.
+                Examples:
+                - "qq.com"
+                - "qq.com|m.163.com"
+
+            exclude (string): Optional. Specifies the domains to exclude from
+                the search. Multiple domains can be separated by "|" or ",".
+                A maximum of 100 domains is allowed.
+                Examples:
+                - "qq.com"
+                - "qq.com|m.163.com"
+
+            count (number): Optional. Number of search results to return.
+                - Range: 1–50
+                - Default: 10
+                The actual number of returned results may be less than the
+                specified count.
+        """
+        logger.info(f"web_searcher - search_from_bocha: {query}")
+        cfg = self.context.get_config(umo=event.unified_msg_origin)
+        # websearch_link = cfg["provider_settings"].get("web_search_link", False)
+        if not cfg.get("provider_settings", {}).get("websearch_bocha_key", []):
+            raise ValueError("Error: BoCha API key is not configured in AstrBot.")
+
+        # build payload
+        payload = {
+            "query": query,
+            "count": count,
+        }
+
+        # freshness：时间范围
+        if freshness:
+            payload["freshness"] = freshness
+
+        # 是否返回摘要
+        payload["summary"] = summary
+
+        # include：限制搜索域
+        if include:
+            payload["include"] = include
+
+        # exclude：排除搜索域
+        if exclude:
+            payload["exclude"] = exclude
+
+        results = await self._web_search_bocha(cfg, payload)
+        if not results:
+            return "Error: BoCha web searcher does not return any results."
+
+        ret_ls = []
+        ref_uuid = str(uuid.uuid4())[:4]
+        for idx, result in enumerate(results, 1):
+            index = f"{ref_uuid}.{idx}"
+            ret_ls.append(
+                {
+                    "title": f"{result.title}",
+                    "url": f"{result.url}",
+                    "snippet": f"{result.snippet}",
+                    "index": index,
+                }
+            )
+            if result.favicon:
+                sp.temporary_cache["_ws_favicon"][result.url] = result.favicon
+        # ret = "\n".join(ret_ls)
+        ret = json.dumps({"results": ret_ls}, ensure_ascii=False)
+        return ret
+
     @filter.on_llm_request(priority=-10000)
     async def edit_web_search_tools(
         self,
         event: AstrMessageEvent,
         req: ProviderRequest,
-    ):
+    ) -> None:
         """Get the session conversation for the given event."""
         cfg = self.context.get_config(umo=event.unified_msg_origin)
         prov_settings = cfg.get("provider_settings", {})
@@ -419,6 +585,7 @@ class Main(star.Star):
             tool_set.remove_tool("web_search_tavily")
             tool_set.remove_tool("tavily_extract_web_page")
             tool_set.remove_tool("AIsearch")
+            tool_set.remove_tool("web_search_bocha")
         elif provider == "tavily":
             web_search_tavily = func_tool_mgr.get_func("web_search_tavily")
             tavily_extract_web_page = func_tool_mgr.get_func("tavily_extract_web_page")
@@ -429,6 +596,7 @@ class Main(star.Star):
             tool_set.remove_tool("web_search")
             tool_set.remove_tool("fetch_url")
             tool_set.remove_tool("AIsearch")
+            tool_set.remove_tool("web_search_bocha")
         elif provider == "baidu_ai_search":
             try:
                 await self.ensure_baidu_ai_search_mcp(event.unified_msg_origin)
@@ -440,5 +608,15 @@ class Main(star.Star):
                 tool_set.remove_tool("fetch_url")
                 tool_set.remove_tool("web_search_tavily")
                 tool_set.remove_tool("tavily_extract_web_page")
+                tool_set.remove_tool("web_search_bocha")
             except Exception as e:
                 logger.error(f"Cannot Initialize Baidu AI Search MCP Server: {e}")
+        elif provider == "bocha":
+            web_search_bocha = func_tool_mgr.get_func("web_search_bocha")
+            if web_search_bocha:
+                tool_set.add_tool(web_search_bocha)
+            tool_set.remove_tool("web_search")
+            tool_set.remove_tool("fetch_url")
+            tool_set.remove_tool("AIsearch")
+            tool_set.remove_tool("web_search_tavily")
+            tool_set.remove_tool("tavily_extract_web_page")

astrbot/cli/__init__.py

@@ -1 +1 @@
-__version__ = "4.14.4"
+__version__ = "4.17.3"

astrbot/cli/commands/cmd_conf.py

@@ -127,7 +127,7 @@ def _get_nested_item(obj: dict[str, Any], path: str) -> Any:
 
 
 @click.group(name="conf")
-def conf():
+def conf() -> None:
     """配置管理命令
 
     支持的配置项:
@@ -149,7 +149,7 @@ def conf():
 @conf.command(name="set")
 @click.argument("key")
 @click.argument("value")
-def set_config(key: str, value: str):
+def set_config(key: str, value: str) -> None:
     """设置配置项的值"""
     if key not in CONFIG_VALIDATORS:
         raise click.ClickException(f"不支持的配置项: {key}")
@@ -178,7 +178,7 @@ def set_config(key: str, value: str):
 
 @conf.command(name="get")
 @click.argument("key", required=False)
-def get_config(key: str | None = None):
+def get_config(key: str | None = None) -> None:
     """获取配置项的值，不提供key则显示所有可配置项"""
     config = _load_config()
 

astrbot/cli/commands/cmd_plug.py

@@ -15,7 +15,7 @@ from ..utils import (
 
 
 @click.group()
-def plug():
+def plug() -> None:
     """插件管理"""
 
 
@@ -28,7 +28,7 @@ def _get_data_path() -> Path:
     return (base / "data").resolve()
 
 
-def display_plugins(plugins, title=None, color=None):
+def display_plugins(plugins, title=None, color=None) -> None:
     if title:
         click.echo(click.style(title, fg=color, bold=True))
 
@@ -45,7 +45,7 @@ def display_plugins(plugins, title=None, color=None):
 
 @plug.command()
 @click.argument("name")
-def new(name: str):
+def new(name: str) -> None:
     """创建新插件"""
     base_path = _get_data_path()
     plug_path = base_path / "plugins" / name
@@ -100,7 +100,7 @@ def new(name: str):
 
 @plug.command()
 @click.option("--all", "-a", is_flag=True, help="列出未安装的插件")
-def list(all: bool):
+def list(all: bool) -> None:
     """列出插件"""
     base_path = _get_data_path()
     plugins = build_plug_list(base_path / "plugins")
@@ -141,7 +141,7 @@ def list(all: bool):
 @plug.command()
 @click.argument("name")
 @click.option("--proxy", help="代理服务器地址")
-def install(name: str, proxy: str | None):
+def install(name: str, proxy: str | None) -> None:
     """安装插件"""
     base_path = _get_data_path()
     plug_path = base_path / "plugins"
@@ -164,7 +164,7 @@ def install(name: str, proxy: str | None):
 
 @plug.command()
 @click.argument("name")
-def remove(name: str):
+def remove(name: str) -> None:
     """卸载插件"""
     base_path = _get_data_path()
     plugins = build_plug_list(base_path / "plugins")
@@ -187,7 +187,7 @@ def remove(name: str):
 @plug.command()
 @click.argument("name", required=False)
 @click.option("--proxy", help="Github代理地址")
-def update(name: str, proxy: str | None):
+def update(name: str, proxy: str | None) -> None:
     """更新插件"""
     base_path = _get_data_path()
     plug_path = base_path / "plugins"
@@ -225,7 +225,7 @@ def update(name: str, proxy: str | None):
 
 @plug.command()
 @click.argument("query")
-def search(query: str):
+def search(query: str) -> None:
     """搜索插件"""
     base_path = _get_data_path()
     plugins = build_plug_list(base_path / "plugins")

astrbot/cli/commands/cmd_run.py

@@ -10,7 +10,7 @@ from filelock import FileLock, Timeout
 from ..utils import check_astrbot_root, check_dashboard, get_astrbot_root
 
 
-async def run_astrbot(astrbot_root: Path):
+async def run_astrbot(astrbot_root: Path) -> None:
     """运行 AstrBot"""
     from astrbot.core import LogBroker, LogManager, db_helper, logger
     from astrbot.core.initial_loader import InitialLoader

astrbot/cli/utils/plugin.py

@@ -19,7 +19,7 @@ class PluginStatus(str, Enum):
     NOT_PUBLISHED = "未发布"
 
 
-def get_git_repo(url: str, target_path: Path, proxy: str | None = None):
+def get_git_repo(url: str, target_path: Path, proxy: str | None = None) -> None:
     """从 Git 仓库下载代码并解压到指定路径"""
     temp_dir = Path(tempfile.mkdtemp())
     try:

astrbot/core/agent/context/compressor.py

@@ -57,7 +57,9 @@ class TruncateByTurnsCompressor:
     Truncates the message list by removing older turns.
     """
 
-    def __init__(self, truncate_turns: int = 1, compression_threshold: float = 0.82):
+    def __init__(
+        self, truncate_turns: int = 1, compression_threshold: float = 0.82
+    ) -> None:
         """Initialize the truncate by turns compressor.
 
         Args:
@@ -152,7 +154,7 @@ class LLMSummaryCompressor:
         keep_recent: int = 4,
         instruction_text: str | None = None,
         compression_threshold: float = 0.82,
-    ):
+    ) -> None:
         """Initialize the LLM summary compressor.
 
         Args:

astrbot/core/agent/context/manager.py

@@ -13,7 +13,7 @@ class ContextManager:
     def __init__(
         self,
         config: ContextConfig,
-    ):
+    ) -> None:
         """Initialize the context manager.
 
         There are two strategies to handle context limit reached:

astrbot/core/agent/handoff.py

@@ -14,8 +14,7 @@ class HandoffTool(FunctionTool, Generic[TContext]):
         parameters: dict | None = None,
         tool_description: str | None = None,
         **kwargs,
-    ):
-        self.agent = agent
+    ) -> None:
 
         # Avoid passing duplicate `description` to the FunctionTool dataclass.
         # Some call sites (e.g. SubAgentOrchestrator) pass `description` via kwargs
@@ -34,6 +33,8 @@ class HandoffTool(FunctionTool, Generic[TContext]):
         # Optional provider override for this subagent. When set, the handoff
         # execution will use this chat provider id instead of the global/default.
         self.provider_id: str | None = None
+        # Note: Must assign after super().__init__() to prevent parent class from overriding this attribute
+        self.agent = agent
 
     def default_parameters(self) -> dict:
         return {

astrbot/core/agent/hooks.py

@@ -9,22 +9,22 @@ from .run_context import ContextWrapper, TContext
 
 
 class BaseAgentRunHooks(Generic[TContext]):
-    async def on_agent_begin(self, run_context: ContextWrapper[TContext]): ...
+    async def on_agent_begin(self, run_context: ContextWrapper[TContext]) -> None: ...
     async def on_tool_start(
         self,
         run_context: ContextWrapper[TContext],
         tool: FunctionTool,
         tool_args: dict | None,
-    ): ...
+    ) -> None: ...
     async def on_tool_end(
         self,
         run_context: ContextWrapper[TContext],
         tool: FunctionTool,
         tool_args: dict | None,
         tool_result: mcp.types.CallToolResult | None,
-    ): ...
+    ) -> None: ...
     async def on_agent_done(
         self,
         run_context: ContextWrapper[TContext],
         llm_response: LLMResponse,
-    ): ...
+    ) -> None: ...

astrbot/core/agent/mcp_client.py

@@ -108,7 +108,7 @@ async def _quick_test_mcp_connection(config: dict) -> tuple[bool, str]:
 
 
 class MCPClient:
-    def __init__(self):
+    def __init__(self) -> None:
         # Initialize session and client objects
         self.session: mcp.ClientSession | None = None
         self.exit_stack = AsyncExitStack()
@@ -126,7 +126,7 @@ class MCPClient:
         self._reconnect_lock = asyncio.Lock()  # Lock for thread-safe reconnection
         self._reconnecting: bool = False  # For logging and debugging
 
-    async def connect_to_server(self, mcp_server_config: dict, name: str):
+    async def connect_to_server(self, mcp_server_config: dict, name: str) -> None:
         """Connect to MCP server
 
         If `url` parameter exists:
@@ -144,7 +144,7 @@ class MCPClient:
 
         cfg = _prepare_config(mcp_server_config.copy())
 
-        def logging_callback(msg: str):
+        def logging_callback(msg: str) -> None:
             # Handle MCP service error logs
             print(f"MCP Server {name} Error: {msg}")
             self.server_errlogs.append(msg)
@@ -214,7 +214,7 @@ class MCPClient:
                 **cfg,
             )
 
-            def callback(msg: str):
+            def callback(msg: str) -> None:
                 # Handle MCP service error logs
                 self.server_errlogs.append(msg)
 
@@ -343,7 +343,7 @@ class MCPClient:
 
         return await _call_with_retry()
 
-    async def cleanup(self):
+    async def cleanup(self) -> None:
         """Clean up resources including old exit stacks from reconnections"""
         # Close current exit stack
         try:
@@ -365,7 +365,7 @@ class MCPTool(FunctionTool, Generic[TContext]):
 
     def __init__(
         self, mcp_tool: mcp.Tool, mcp_client: MCPClient, mcp_server_name: str, **kwargs
-    ):
+    ) -> None:
         super().__init__(
             name=mcp_tool.name,
             description=mcp_tool.description or "",

astrbot/core/agent/message.py

@@ -3,7 +3,13 @@
 
 from typing import Any, ClassVar, Literal, cast
 
-from pydantic import BaseModel, GetCoreSchemaHandler, model_serializer, model_validator
+from pydantic import (
+    BaseModel,
+    GetCoreSchemaHandler,
+    PrivateAttr,
+    model_serializer,
+    model_validator,
+)
 from pydantic_core import core_schema
 
 
@@ -178,6 +184,8 @@ class Message(BaseModel):
     tool_call_id: str | None = None
     """The ID of the tool call."""
 
+    _no_save: bool = PrivateAttr(default=False)
+
     @model_validator(mode="after")
     def check_content_required(self):
         # assistant + tool_calls is not None: allow content to be None

astrbot/core/agent/runners/coze/coze_api_client.py

@@ -10,7 +10,7 @@ from astrbot.core import logger
 
 
 class CozeAPIClient:
-    def __init__(self, api_key: str, api_base: str = "https://api.coze.cn"):
+    def __init__(self, api_key: str, api_base: str = "https://api.coze.cn") -> None:
         self.api_key = api_key
         self.api_base = api_base
         self.session = None
@@ -277,7 +277,7 @@ class CozeAPIClient:
             logger.error(f"获取Coze消息列表失败: {e!s}")
             raise Exception(f"获取Coze消息列表失败: {e!s}")
 
-    async def close(self):
+    async def close(self) -> None:
         """关闭会话"""
         if self.session:
             await self.session.close()
@@ -288,7 +288,7 @@ if __name__ == "__main__":
     import asyncio
     import os
 
-    async def test_coze_api_client():
+    async def test_coze_api_client() -> None:
         api_key = os.getenv("COZE_API_KEY", "")
         bot_id = os.getenv("COZE_BOT_ID", "")
         client = CozeAPIClient(api_key=api_key)

astrbot/core/agent/runners/dashscope/dashscope_agent_runner.py

@@ -67,7 +67,7 @@ class DashscopeAgentRunner(BaseAgentRunner[TContext]):
         if isinstance(self.timeout, str):
             self.timeout = int(self.timeout)
 
-    def has_rag_options(self):
+    def has_rag_options(self) -> bool:
         """判断是否有 RAG 选项
 
         Returns:

astrbot/core/agent/runners/dify/dify_agent_runner.py

@@ -10,7 +10,7 @@ from astrbot.core.provider.entities import (
     LLMResponse,
     ProviderRequest,
 )
-from astrbot.core.utils.astrbot_path import get_astrbot_data_path
+from astrbot.core.utils.astrbot_path import get_astrbot_temp_path
 from astrbot.core.utils.io import download_file
 
 from ...hooks import BaseAgentRunHooks
@@ -291,8 +291,8 @@ class DifyAgentRunner(BaseAgentRunner[TContext]):
                     return Comp.Image(file=item["url"], url=item["url"])
                 case "audio":
                     # 仅支持 wav
-                    temp_dir = os.path.join(get_astrbot_data_path(), "temp")
-                    path = os.path.join(temp_dir, f"{item['filename']}.wav")
+                    temp_dir = get_astrbot_temp_path()
+                    path = os.path.join(temp_dir, f"dify_{item['filename']}.wav")
                     await download_file(item["url"], path)
                     return Comp.Image(file=item["url"], url=item["url"])
                 case "video":

astrbot/core/agent/runners/dify/dify_api_client.py

@@ -31,7 +31,7 @@ async def _stream_sse(resp: ClientResponse) -> AsyncGenerator[dict, None]:
 
 
 class DifyAPIClient:
-    def __init__(self, api_key: str, api_base: str = "https://api.dify.ai/v1"):
+    def __init__(self, api_key: str, api_base: str = "https://api.dify.ai/v1") -> None:
         self.api_key = api_key
         self.api_base = api_base
         self.session = ClientSession(trust_env=True)
@@ -155,7 +155,7 @@ class DifyAPIClient:
                 raise Exception(f"Dify 文件上传失败：{resp.status}. {text}")
             return await resp.json()  # {"id": "xxx", ...}
 
-    async def close(self):
+    async def close(self) -> None:
         await self.session.close()
 
     async def get_chat_convs(self, user: str, limit: int = 20):

astrbot/core/agent/runners/tool_loop_agent_runner.py

@@ -3,6 +3,7 @@ import sys
 import time
 import traceback
 import typing as T
+from dataclasses import dataclass
 
 from mcp.types import (
     BlobResourceContents,
@@ -14,8 +15,9 @@ from mcp.types import (
 )
 
 from astrbot import logger
-from astrbot.core.agent.message import TextPart, ThinkPart
+from astrbot.core.agent.message import ImageURLPart, TextPart, ThinkPart
 from astrbot.core.agent.tool import ToolSet
+from astrbot.core.agent.tool_image_cache import tool_image_cache
 from astrbot.core.message.components import Json
 from astrbot.core.message.message_event_result import (
     MessageChain,
@@ -44,6 +46,28 @@ else:
     from typing_extensions import override
 
 
+@dataclass(slots=True)
+class _HandleFunctionToolsResult:
+    kind: T.Literal["message_chain", "tool_call_result_blocks", "cached_image"]
+    message_chain: MessageChain | None = None
+    tool_call_result_blocks: list[ToolCallMessageSegment] | None = None
+    cached_image: T.Any = None
+
+    @classmethod
+    def from_message_chain(cls, chain: MessageChain) -> "_HandleFunctionToolsResult":
+        return cls(kind="message_chain", message_chain=chain)
+
+    @classmethod
+    def from_tool_call_result_blocks(
+        cls, blocks: list[ToolCallMessageSegment]
+    ) -> "_HandleFunctionToolsResult":
+        return cls(kind="tool_call_result_blocks", tool_call_result_blocks=blocks)
+
+    @classmethod
+    def from_cached_image(cls, image: T.Any) -> "_HandleFunctionToolsResult":
+        return cls(kind="cached_image", cached_image=image)
+
+
 class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
     @override
     async def reset(
@@ -67,6 +91,7 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
         custom_token_counter: TokenCounter | None = None,
         custom_compressor: ContextCompressor | None = None,
         tool_schema_mode: str | None = "full",
+        fallback_providers: list[Provider] | None = None,
         **kwargs: T.Any,
     ) -> None:
         self.req = request
@@ -96,6 +121,17 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
         self.context_manager = ContextManager(self.context_config)
 
         self.provider = provider
+        self.fallback_providers: list[Provider] = []
+        seen_provider_ids: set[str] = {str(provider.provider_config.get("id", ""))}
+        for fallback_provider in fallback_providers or []:
+            fallback_id = str(fallback_provider.provider_config.get("id", ""))
+            if fallback_provider is provider:
+                continue
+            if fallback_id and fallback_id in seen_provider_ids:
+                continue
+            self.fallback_providers.append(fallback_provider)
+            if fallback_id:
+                seen_provider_ids.add(fallback_id)
         self.final_llm_resp = None
         self._state = AgentState.IDLE
         self.tool_executor = tool_executor
@@ -125,7 +161,10 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
         messages = []
         # append existing messages in the run context
         for msg in request.contexts:
-            messages.append(Message.model_validate(msg))
+            m = Message.model_validate(msg)
+            if isinstance(msg, dict) and msg.get("_no_save"):
+                m._no_save = True
+            messages.append(m)
         if request.prompt is not None:
             m = await request.assemble_context()
             messages.append(Message.model_validate(m))
@@ -139,16 +178,19 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
         self.stats = AgentStats()
         self.stats.start_time = time.time()
 
-    async def _iter_llm_responses(self) -> T.AsyncGenerator[LLMResponse, None]:
+    async def _iter_llm_responses(
+        self, *, include_model: bool = True
+    ) -> T.AsyncGenerator[LLMResponse, None]:
         """Yields chunks *and* a final LLMResponse."""
         payload = {
             "contexts": self.run_context.messages,  # list[Message]
             "func_tool": self.req.func_tool,
-            "model": self.req.model,  # NOTE: in fact, this arg is None in most cases
             "session_id": self.req.session_id,
             "extra_user_content_parts": self.req.extra_user_content_parts,  # list[ContentPart]
         }
-
+        if include_model:
+            # For primary provider we keep explicit model selection if provided.
+            payload["model"] = self.req.model
         if self.streaming:
             stream = self.provider.text_chat_stream(**payload)
             async for resp in stream:  # type: ignore
@@ -156,6 +198,83 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
         else:
             yield await self.provider.text_chat(**payload)
 
+    async def _iter_llm_responses_with_fallback(
+        self,
+    ) -> T.AsyncGenerator[LLMResponse, None]:
+        """Wrap _iter_llm_responses with provider fallback handling."""
+        candidates = [self.provider, *self.fallback_providers]
+        total_candidates = len(candidates)
+        last_exception: Exception | None = None
+        last_err_response: LLMResponse | None = None
+
+        for idx, candidate in enumerate(candidates):
+            candidate_id = candidate.provider_config.get("id", "<unknown>")
+            is_last_candidate = idx == total_candidates - 1
+            if idx > 0:
+                logger.warning(
+                    "Switched from %s to fallback chat provider: %s",
+                    self.provider.provider_config.get("id", "<unknown>"),
+                    candidate_id,
+                )
+            self.provider = candidate
+            has_stream_output = False
+            try:
+                async for resp in self._iter_llm_responses(include_model=idx == 0):
+                    if resp.is_chunk:
+                        has_stream_output = True
+                        yield resp
+                        continue
+
+                    if (
+                        resp.role == "err"
+                        and not has_stream_output
+                        and (not is_last_candidate)
+                    ):
+                        last_err_response = resp
+                        logger.warning(
+                            "Chat Model %s returns error response, trying fallback to next provider.",
+                            candidate_id,
+                        )
+                        break
+
+                    yield resp
+                    return
+
+                if has_stream_output:
+                    return
+            except Exception as exc:  # noqa: BLE001
+                last_exception = exc
+                logger.warning(
+                    "Chat Model %s request error: %s",
+                    candidate_id,
+                    exc,
+                    exc_info=True,
+                )
+                continue
+
+        if last_err_response:
+            yield last_err_response
+            return
+        if last_exception:
+            yield LLMResponse(
+                role="err",
+                completion_text=(
+                    "All chat models failed: "
+                    f"{type(last_exception).__name__}: {last_exception}"
+                ),
+            )
+            return
+        yield LLMResponse(
+            role="err",
+            completion_text="All available chat models are unavailable.",
+        )
+
+    def _simple_print_message_role(self, tag: str = ""):
+        roles = []
+        for message in self.run_context.messages:
+            roles.append(message.role)
+        logger.debug(f"{tag} RunCtx.messages -> [{len(roles)}] {','.join(roles)}")
+
     @override
     async def step(self):
         """Process a single step of the agent.
@@ -176,11 +295,13 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
 
         # do truncate and compress
         token_usage = self.req.conversation.token_usage if self.req.conversation else 0
+        self._simple_print_message_role("[BefCompact]")
         self.run_context.messages = await self.context_manager.process(
             self.run_context.messages, trusted_token_usage=token_usage
         )
+        self._simple_print_message_role("[AftCompact]")
 
-        async for llm_response in self._iter_llm_responses():
+        async for llm_response in self._iter_llm_responses_with_fallback():
             if llm_response.is_chunk:
                 # update ttft
                 if self.stats.time_to_first_token == 0:
@@ -254,6 +375,10 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
                 )
             if llm_resp.completion_text:
                 parts.append(TextPart(text=llm_resp.completion_text))
+            if len(parts) == 0:
+                logger.warning(
+                    "LLM returned empty assistant message with no tool calls."
+                )
             self.run_context.messages.append(Message(role="assistant", content=parts))
 
             # call the on_agent_done hook
@@ -282,20 +407,27 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
                 llm_resp, _ = await self._resolve_tool_exec(llm_resp)
 
             tool_call_result_blocks = []
+            cached_images = []  # Collect cached images for LLM visibility
             async for result in self._handle_function_tools(self.req, llm_resp):
-                if isinstance(result, list):
-                    tool_call_result_blocks = result
-                elif isinstance(result, MessageChain):
-                    if result.type is None:
+                if result.kind == "tool_call_result_blocks":
+                    if result.tool_call_result_blocks is not None:
+                        tool_call_result_blocks = result.tool_call_result_blocks
+                elif result.kind == "cached_image":
+                    if result.cached_image is not None:
+                        # Collect cached image info
+                        cached_images.append(result.cached_image)
+                elif result.kind == "message_chain":
+                    chain = result.message_chain
+                    if chain is None or chain.type is None:
                         # should not happen
                         continue
-                    if result.type == "tool_direct_result":
+                    if chain.type == "tool_direct_result":
                         ar_type = "tool_call_result"
                     else:
-                        ar_type = result.type
+                        ar_type = chain.type
                     yield AgentResponse(
                         type=ar_type,
-                        data=AgentResponseData(chain=result),
+                        data=AgentResponseData(chain=chain),
                     )
 
             # 将结果添加到上下文中
@@ -309,6 +441,8 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
                 )
             if llm_resp.completion_text:
                 parts.append(TextPart(text=llm_resp.completion_text))
+            if len(parts) == 0:
+                parts = None
             tool_calls_result = ToolCallsResult(
                 tool_calls_info=AssistantMessageSegment(
                     tool_calls=llm_resp.to_openai_to_calls_model(),
@@ -321,6 +455,41 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
                 tool_calls_result.to_openai_messages_model()
             )
 
+            # If there are cached images and the model supports image input,
+            # append a user message with images so LLM can see them
+            if cached_images:
+                modalities = self.provider.provider_config.get("modalities", [])
+                supports_image = "image" in modalities
+                if supports_image:
+                    # Build user message with images for LLM to review
+                    image_parts = []
+                    for cached_img in cached_images:
+                        img_data = tool_image_cache.get_image_base64_by_path(
+                            cached_img.file_path, cached_img.mime_type
+                        )
+                        if img_data:
+                            base64_data, mime_type = img_data
+                            image_parts.append(
+                                TextPart(
+                                    text=f"[Image from tool '{cached_img.tool_name}', path='{cached_img.file_path}']"
+                                )
+                            )
+                            image_parts.append(
+                                ImageURLPart(
+                                    image_url=ImageURLPart.ImageURL(
+                                        url=f"data:{mime_type};base64,{base64_data}",
+                                        id=cached_img.file_path,
+                                    )
+                                )
+                            )
+                    if image_parts:
+                        self.run_context.messages.append(
+                            Message(role="user", content=image_parts)
+                        )
+                        logger.debug(
+                            f"Appended {len(cached_images)} cached image(s) to context for LLM review"
+                        )
+
             self.req.append_tool_calls_result(tool_calls_result)
 
     async def step_until_done(
@@ -356,7 +525,7 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
         self,
         req: ProviderRequest,
         llm_response: LLMResponse,
-    ) -> T.AsyncGenerator[MessageChain | list[ToolCallMessageSegment], None]:
+    ) -> T.AsyncGenerator[_HandleFunctionToolsResult, None]:
         """处理函数工具调用。"""
         tool_call_result_blocks: list[ToolCallMessageSegment] = []
         logger.info(f"Agent 使用工具: {llm_response.tools_call_name}")
@@ -367,18 +536,20 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
             llm_response.tools_call_args,
             llm_response.tools_call_ids,
         ):
-            yield MessageChain(
-                type="tool_call",
-                chain=[
-                    Json(
-                        data={
-                            "id": func_tool_id,
-                            "name": func_tool_name,
-                            "args": func_tool_args,
-                            "ts": time.time(),
-                        }
-                    )
-                ],
+            yield _HandleFunctionToolsResult.from_message_chain(
+                MessageChain(
+                    type="tool_call",
+                    chain=[
+                        Json(
+                            data={
+                                "id": func_tool_id,
+                                "name": func_tool_name,
+                                "args": func_tool_args,
+                                "ts": time.time(),
+                            }
+                        )
+                    ],
+                )
             )
             try:
                 if not req.func_tool:
@@ -464,15 +635,28 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
                                 ),
                             )
                         elif isinstance(res.content[0], ImageContent):
+                            # Cache the image instead of sending directly
+                            cached_img = tool_image_cache.save_image(
+                                base64_data=res.content[0].data,
+                                tool_call_id=func_tool_id,
+                                tool_name=func_tool_name,
+                                index=0,
+                                mime_type=res.content[0].mimeType or "image/png",
+                            )
                             tool_call_result_blocks.append(
                                 ToolCallMessageSegment(
                                     role="tool",
                                     tool_call_id=func_tool_id,
-                                    content="The tool has successfully returned an image and sent directly to the user. You can describe it in your next response.",
+                                    content=(
+                                        f"Image returned and cached at path='{cached_img.file_path}'. "
+                                        f"Review the image below. Use send_message_to_user to send it to the user if satisfied, "
+                                        f"with type='image' and path='{cached_img.file_path}'."
+                                    ),
                                 ),
                             )
-                            yield MessageChain(type="tool_direct_result").base64_image(
-                                res.content[0].data,
+                            # Yield image info for LLM visibility (will be handled in step())
+                            yield _HandleFunctionToolsResult.from_cached_image(
+                                cached_img
                             )
                         elif isinstance(res.content[0], EmbeddedResource):
                             resource = res.content[0].resource
@@ -489,16 +673,29 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
                                 and resource.mimeType
                                 and resource.mimeType.startswith("image/")
                             ):
+                                # Cache the image instead of sending directly
+                                cached_img = tool_image_cache.save_image(
+                                    base64_data=resource.blob,
+                                    tool_call_id=func_tool_id,
+                                    tool_name=func_tool_name,
+                                    index=0,
+                                    mime_type=resource.mimeType,
+                                )
                                 tool_call_result_blocks.append(
                                     ToolCallMessageSegment(
                                         role="tool",
                                         tool_call_id=func_tool_id,
-                                        content="The tool has successfully returned an image and sent directly to the user. You can describe it in your next response.",
+                                        content=(
+                                            f"Image returned and cached at path='{cached_img.file_path}'. "
+                                            f"Review the image below. Use send_message_to_user to send it to the user if satisfied, "
+                                            f"with type='image' and path='{cached_img.file_path}'."
+                                        ),
                                     ),
                                 )
-                                yield MessageChain(
-                                    type="tool_direct_result",
-                                ).base64_image(resource.blob)
+                                # Yield image info for LLM visibility
+                                yield _HandleFunctionToolsResult.from_cached_image(
+                                    cached_img
+                                )
                             else:
                                 tool_call_result_blocks.append(
                                     ToolCallMessageSegment(
@@ -559,23 +756,27 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
         # yield the last tool call result
         if tool_call_result_blocks:
             last_tcr_content = str(tool_call_result_blocks[-1].content)
-            yield MessageChain(
-                type="tool_call_result",
-                chain=[
-                    Json(
-                        data={
-                            "id": func_tool_id,
-                            "ts": time.time(),
-                            "result": last_tcr_content,
-                        }
-                    )
-                ],
+            yield _HandleFunctionToolsResult.from_message_chain(
+                MessageChain(
+                    type="tool_call_result",
+                    chain=[
+                        Json(
+                            data={
+                                "id": func_tool_id,
+                                "ts": time.time(),
+                                "result": last_tcr_content,
+                            }
+                        )
+                    ],
+                )
             )
             logger.info(f"Tool `{func_tool_name}` Result: {last_tcr_content}")
 
         # 处理函数调用响应
         if tool_call_result_blocks:
-            yield tool_call_result_blocks
+            yield _HandleFunctionToolsResult.from_tool_call_result_blocks(
+                tool_call_result_blocks
+            )
 
     def _build_tool_requery_context(
         self, tool_names: list[str]

astrbot/core/agent/tool.py

@@ -64,7 +64,7 @@ class FunctionTool(ToolSchema, Generic[TContext]):
     with a task identifier while the real work continues asynchronously.
     """
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"FuncTool(name={self.name}, parameters={self.parameters}, description={self.description})"
 
     async def call(self, context: ContextWrapper[TContext], **kwargs) -> ToolExecResult:
@@ -88,7 +88,7 @@ class ToolSet:
         """Check if the tool set is empty."""
         return len(self.tools) == 0
 
-    def add_tool(self, tool: FunctionTool):
+    def add_tool(self, tool: FunctionTool) -> None:
         """Add a tool to the set."""
         # 检查是否已存在同名工具
         for i, existing_tool in enumerate(self.tools):
@@ -97,7 +97,7 @@ class ToolSet:
                 return
         self.tools.append(tool)
 
-    def remove_tool(self, name: str):
+    def remove_tool(self, name: str) -> None:
         """Remove a tool by its name."""
         self.tools = [tool for tool in self.tools if tool.name != name]
 
@@ -156,7 +156,7 @@ class ToolSet:
         func_args: list,
         desc: str,
         handler: Callable[..., Awaitable[Any]],
-    ):
+    ) -> None:
         """Add a function tool to the set."""
         params = {
             "type": "object",  # hard-coded here
@@ -176,7 +176,7 @@ class ToolSet:
         self.add_tool(_func)
 
     @deprecated(reason="Use remove_tool() instead", version="4.0.0")
-    def remove_func(self, name: str):
+    def remove_func(self, name: str) -> None:
         """Remove a function tool by its name."""
         self.remove_tool(name)
 
@@ -325,22 +325,22 @@ class ToolSet:
         """获取所有工具的名称列表"""
         return [tool.name for tool in self.tools]
 
-    def merge(self, other: "ToolSet"):
+    def merge(self, other: "ToolSet") -> None:
         """Merge another ToolSet into this one."""
         for tool in other.tools:
             self.add_tool(tool)
 
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self.tools)
 
-    def __bool__(self):
+    def __bool__(self) -> bool:
         return len(self.tools) > 0
 
     def __iter__(self):
         return iter(self.tools)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"ToolSet(tools={self.tools})"
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"ToolSet(tools={self.tools})"

astrbot/core/agent/tool_image_cache.py

@@ -0,0 +1,162 @@
+"""Tool image cache module for storing and retrieving images returned by tools.
+
+This module allows LLM to review images before deciding whether to send them to users.
+"""
+
+import base64
+import os
+import time
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+from astrbot import logger
+from astrbot.core.utils.astrbot_path import get_astrbot_temp_path
+
+
+@dataclass
+class CachedImage:
+    """Represents a cached image from a tool call."""
+
+    tool_call_id: str
+    """The tool call ID that produced this image."""
+    tool_name: str
+    """The name of the tool that produced this image."""
+    file_path: str
+    """The file path where the image is stored."""
+    mime_type: str
+    """The MIME type of the image."""
+    created_at: float = field(default_factory=time.time)
+    """Timestamp when the image was cached."""
+
+
+class ToolImageCache:
+    """Manages cached images from tool calls.
+
+    Images are stored in data/temp/tool_images/ and can be retrieved by file path.
+    """
+
+    _instance: ClassVar["ToolImageCache | None"] = None
+    CACHE_DIR_NAME: ClassVar[str] = "tool_images"
+    # Cache expiry time in seconds (1 hour)
+    CACHE_EXPIRY: ClassVar[int] = 3600
+
+    def __new__(cls) -> "ToolImageCache":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._initialized = False
+        return cls._instance
+
+    def __init__(self) -> None:
+        if self._initialized:
+            return
+        self._initialized = True
+        self._cache_dir = os.path.join(get_astrbot_temp_path(), self.CACHE_DIR_NAME)
+        os.makedirs(self._cache_dir, exist_ok=True)
+        logger.debug(f"ToolImageCache initialized, cache dir: {self._cache_dir}")
+
+    def _get_file_extension(self, mime_type: str) -> str:
+        """Get file extension from MIME type."""
+        mime_to_ext = {
+            "image/png": ".png",
+            "image/jpeg": ".jpg",
+            "image/jpg": ".jpg",
+            "image/gif": ".gif",
+            "image/webp": ".webp",
+            "image/bmp": ".bmp",
+            "image/svg+xml": ".svg",
+        }
+        return mime_to_ext.get(mime_type.lower(), ".png")
+
+    def save_image(
+        self,
+        base64_data: str,
+        tool_call_id: str,
+        tool_name: str,
+        index: int = 0,
+        mime_type: str = "image/png",
+    ) -> CachedImage:
+        """Save an image to cache and return the cached image info.
+
+        Args:
+            base64_data: Base64 encoded image data.
+            tool_call_id: The tool call ID that produced this image.
+            tool_name: The name of the tool that produced this image.
+            index: The index of the image (for multiple images from same tool call).
+            mime_type: The MIME type of the image.
+
+        Returns:
+            CachedImage object with file path.
+        """
+        ext = self._get_file_extension(mime_type)
+        file_name = f"{tool_call_id}_{index}{ext}"
+        file_path = os.path.join(self._cache_dir, file_name)
+
+        # Decode and save the image
+        try:
+            image_bytes = base64.b64decode(base64_data)
+            with open(file_path, "wb") as f:
+                f.write(image_bytes)
+            logger.debug(f"Saved tool image to: {file_path}")
+        except Exception as e:
+            logger.error(f"Failed to save tool image: {e}")
+            raise
+
+        return CachedImage(
+            tool_call_id=tool_call_id,
+            tool_name=tool_name,
+            file_path=file_path,
+            mime_type=mime_type,
+        )
+
+    def get_image_base64_by_path(
+        self, file_path: str, mime_type: str = "image/png"
+    ) -> tuple[str, str] | None:
+        """Read an image file and return its base64 encoded data.
+
+        Args:
+            file_path: The file path of the cached image.
+            mime_type: The MIME type of the image.
+
+        Returns:
+            Tuple of (base64_data, mime_type) if found, None otherwise.
+        """
+        if not os.path.exists(file_path):
+            return None
+
+        try:
+            with open(file_path, "rb") as f:
+                image_bytes = f.read()
+            base64_data = base64.b64encode(image_bytes).decode("utf-8")
+            return base64_data, mime_type
+        except Exception as e:
+            logger.error(f"Failed to read cached image {file_path}: {e}")
+            return None
+
+    def cleanup_expired(self) -> int:
+        """Clean up expired cached images.
+
+        Returns:
+            Number of images cleaned up.
+        """
+        now = time.time()
+        cleaned = 0
+
+        try:
+            for file_name in os.listdir(self._cache_dir):
+                file_path = os.path.join(self._cache_dir, file_name)
+                if os.path.isfile(file_path):
+                    file_age = now - os.path.getmtime(file_path)
+                    if file_age > self.CACHE_EXPIRY:
+                        os.remove(file_path)
+                        cleaned += 1
+        except Exception as e:
+            logger.warning(f"Error during cache cleanup: {e}")
+
+        if cleaned:
+            logger.info(f"Cleaned up {cleaned} expired cached images")
+
+        return cleaned
+
+
+# Global singleton instance
+tool_image_cache = ToolImageCache()

astrbot/core/astr_agent_hooks.py

@@ -12,7 +12,7 @@ from astrbot.core.star.star_handler import EventType
 
 
 class MainAgentHooks(BaseAgentRunHooks[AstrAgentContext]):
-    async def on_agent_done(self, run_context, llm_response):
+    async def on_agent_done(self, run_context, llm_response) -> None:
         # 执行事件钩子
         if llm_response and llm_response.reasoning_content:
             # we will use this in result_decorate stage to inject reasoning content to chain
@@ -31,7 +31,7 @@ class MainAgentHooks(BaseAgentRunHooks[AstrAgentContext]):
         run_context: ContextWrapper[AstrAgentContext],
         tool: FunctionTool[Any],
         tool_args: dict | None,
-    ):
+    ) -> None:
         await call_event_hook(
             run_context.context.event,
             EventType.OnUsingLLMToolEvent,
@@ -45,7 +45,7 @@ class MainAgentHooks(BaseAgentRunHooks[AstrAgentContext]):
         tool: FunctionTool[Any],
         tool_args: dict | None,
         tool_result: CallToolResult | None,
-    ):
+    ) -> None:
         run_context.context.event.clear_result()
         await call_event_hook(
             run_context.context.event,
@@ -59,7 +59,7 @@ class MainAgentHooks(BaseAgentRunHooks[AstrAgentContext]):
         platform_name = run_context.context.event.get_platform_name()
         if (
             platform_name == "webchat"
-            and tool.name == "web_search_tavily"
+            and tool.name in ["web_search_tavily", "web_search_bocha"]
             and len(run_context.messages) > 0
             and tool_result
             and len(tool_result.content)

astrbot/core/astr_agent_run_util.py

@@ -295,7 +295,7 @@ async def _run_agent_feeder(
     max_step: int,
     show_tool_use: bool,
     show_reasoning: bool,
-):
+) -> None:
     """运行 Agent 并将文本输出分句放入队列"""
     buffer = ""
     try:
@@ -352,7 +352,7 @@ async def _safe_tts_stream_wrapper(
     tts_provider: TTSProvider,
     text_queue: asyncio.Queue[str | None],
     audio_queue: "asyncio.Queue[bytes | tuple[str, bytes] | None]",
-):
+) -> None:
     """包装原生流式 TTS 确保异常处理和队列关闭"""
     try:
         await tts_provider.get_audio_stream(text_queue, audio_queue)
@@ -366,7 +366,7 @@ async def _simulated_stream_tts(
     tts_provider: TTSProvider,
     text_queue: asyncio.Queue[str | None],
     audio_queue: "asyncio.Queue[bytes | tuple[str, bytes] | None]",
-):
+) -> None:
     """模拟流式 TTS 分句生成音频"""
     try:
         while True:

astrbot/core/astr_agent_tool_exec.py

@@ -57,7 +57,7 @@ class FunctionToolExecutor(BaseFunctionToolExecutor[AstrAgentContext]):
         elif tool.is_background_task:
             task_id = uuid.uuid4().hex
 
-            async def _run_in_background():
+            async def _run_in_background() -> None:
                 try:
                     await cls._execute_background(
                         tool=tool,
@@ -153,7 +153,7 @@ class FunctionToolExecutor(BaseFunctionToolExecutor[AstrAgentContext]):
         run_context: ContextWrapper[AstrAgentContext],
         task_id: str,
         **tool_args,
-    ):
+    ) -> None:
         from astrbot.core.astr_main_agent import (
             MainAgentBuildConfig,
             _get_session_conv,

astrbot/core/astr_main_agent.py

@@ -42,6 +42,7 @@ from astrbot.core.message.components import File, Image, Reply
 from astrbot.core.platform.astr_message_event import AstrMessageEvent
 from astrbot.core.provider import Provider
 from astrbot.core.provider.entities import ProviderRequest
+from astrbot.core.provider.manager import llm_tools
 from astrbot.core.skills.skill_manager import SkillManager, build_skills_prompt
 from astrbot.core.star.context import Context
 from astrbot.core.star.star_handler import star_map
@@ -52,6 +53,17 @@ from astrbot.core.tools.cron_tools import (
 )
 from astrbot.core.utils.file_extract import extract_file_moonshotai
 from astrbot.core.utils.llm_metadata import LLM_METADATAS
+from astrbot.core.utils.quoted_message.settings import (
+    SETTINGS as DEFAULT_QUOTED_MESSAGE_SETTINGS,
+)
+from astrbot.core.utils.quoted_message.settings import (
+    QuotedMessageParserSettings,
+)
+from astrbot.core.utils.quoted_message_parser import (
+    extract_quoted_message_images,
+    extract_quoted_message_text,
+)
+from astrbot.core.utils.string_utils import normalize_and_dedupe_strings
 
 
 @dataclass(slots=True)
@@ -108,6 +120,8 @@ class MainAgentBuildConfig:
     provider_settings: dict = field(default_factory=dict)
     subagent_orchestrator: dict = field(default_factory=dict)
     timezone: str | None = None
+    max_quoted_fallback_images: int = 20
+    """Maximum number of images injected from quoted-message fallback extraction."""
 
 
 @dataclass(slots=True)
@@ -326,6 +340,24 @@ async def _ensure_persona_and_skills(
                 )
     tmgr = plugin_context.get_llm_tool_manager()
 
+    # inject toolset in the persona
+    if (persona and persona.get("tools") is None) or not persona:
+        persona_toolset = tmgr.get_full_tool_set()
+        for tool in list(persona_toolset):
+            if not tool.active:
+                persona_toolset.remove_tool(tool.name)
+    else:
+        persona_toolset = ToolSet()
+        if persona["tools"]:
+            for tool_name in persona["tools"]:
+                tool = tmgr.get_func(tool_name)
+                if tool and tool.active:
+                    persona_toolset.add_tool(tool)
+    if not req.func_tool:
+        req.func_tool = persona_toolset
+    else:
+        req.func_tool.merge(persona_toolset)
+
     # sub agents integration
     orch_cfg = plugin_context.get_config().get("subagent_orchestrator", {})
     so = plugin_context.subagent_orchestrator
@@ -371,22 +403,19 @@ async def _ensure_persona_and_skills(
                         assigned_tools.add(name)
 
         if req.func_tool is None:
-            toolset = ToolSet()
-        else:
-            toolset = req.func_tool
+            req.func_tool = ToolSet()
 
         # add subagent handoff tools
         for tool in so.handoffs:
-            toolset.add_tool(tool)
+            req.func_tool.add_tool(tool)
 
         # check duplicates
         if remove_dup:
-            names = toolset.names()
+            handoff_names = {tool.name for tool in so.handoffs}
             for tool_name in assigned_tools:
-                if tool_name in names:
-                    toolset.remove_tool(tool_name)
-
-        req.func_tool = toolset
+                if tool_name in handoff_names:
+                    continue
+                req.func_tool.remove_tool(tool_name)
 
         router_prompt = (
             plugin_context.get_config()
@@ -395,32 +424,14 @@ async def _ensure_persona_and_skills(
         ).strip()
         if router_prompt:
             req.system_prompt += f"\n{router_prompt}\n"
-        return
-
-    # inject toolset in the persona
-    if (persona and persona.get("tools") is None) or not persona:
-        toolset = tmgr.get_full_tool_set()
-        for tool in list(toolset):
-            if not tool.active:
-                toolset.remove_tool(tool.name)
-    else:
-        toolset = ToolSet()
-        if persona["tools"]:
-            for tool_name in persona["tools"]:
-                tool = tmgr.get_func(tool_name)
-                if tool and tool.active:
-                    toolset.add_tool(tool)
-    if not req.func_tool:
-        req.func_tool = toolset
-    else:
-        req.func_tool.merge(toolset)
     try:
         event.trace.record(
-            "sel_persona", persona_id=persona_id, persona_toolset=toolset.names()
+            "sel_persona",
+            persona_id=persona_id,
+            persona_toolset=persona_toolset.names(),
         )
     except Exception:
         pass
-    logger.debug("Tool set for persona %s: %s", persona_id, toolset.names())
 
 
 async def _request_img_caption(
@@ -473,11 +484,29 @@ async def _ensure_img_caption(
         logger.error("处理图片描述失败: %s", exc)
 
 
+def _append_quoted_image_attachment(req: ProviderRequest, image_path: str) -> None:
+    req.extra_user_content_parts.append(
+        TextPart(text=f"[Image Attachment in quoted message: path {image_path}]")
+    )
+
+
+def _get_quoted_message_parser_settings(
+    provider_settings: dict[str, object] | None,
+) -> QuotedMessageParserSettings:
+    if not isinstance(provider_settings, dict):
+        return DEFAULT_QUOTED_MESSAGE_SETTINGS
+    overrides = provider_settings.get("quoted_message_parser")
+    if not isinstance(overrides, dict):
+        return DEFAULT_QUOTED_MESSAGE_SETTINGS
+    return DEFAULT_QUOTED_MESSAGE_SETTINGS.with_overrides(overrides)
+
+
 async def _process_quote_message(
     event: AstrMessageEvent,
     req: ProviderRequest,
     img_cap_prov_id: str,
     plugin_context: Context,
+    quoted_message_settings: QuotedMessageParserSettings = DEFAULT_QUOTED_MESSAGE_SETTINGS,
 ) -> None:
     quote = None
     for comp in event.message_obj.message:
@@ -489,7 +518,15 @@ async def _process_quote_message(
 
     content_parts = []
     sender_info = f"({quote.sender_nickname}): " if quote.sender_nickname else ""
-    message_str = quote.message_str or "[Empty Text]"
+    message_str = (
+        await extract_quoted_message_text(
+            event,
+            quote,
+            settings=quoted_message_settings,
+        )
+        or quote.message_str
+        or "[Empty Text]"
+    )
     content_parts.append(f"{sender_info}{message_str}")
 
     image_seg = None
@@ -595,11 +632,13 @@ async def _decorate_llm_request(
             )
 
     img_cap_prov_id = cfg.get("default_image_caption_provider_id") or ""
+    quoted_message_settings = _get_quoted_message_parser_settings(cfg)
     await _process_quote_message(
         event,
         req,
         img_cap_prov_id,
         plugin_context,
+        quoted_message_settings,
     )
 
     tz = config.timezone
@@ -731,6 +770,14 @@ def _plugin_tool_fix(event: AstrMessageEvent, req: ProviderRequest) -> None:
             if plugin.name in event.plugins_name or plugin.reserved:
                 new_tool_set.add_tool(tool)
         req.func_tool = new_tool_set
+    else:
+        # mcp tools
+        tool_set = req.func_tool
+        if not tool_set:
+            tool_set = ToolSet()
+        for tool in llm_tools.func_list:
+            if isinstance(tool, MCPTool):
+                tool_set.add_tool(tool)
 
 
 async def _handle_webchat(
@@ -832,6 +879,41 @@ def _get_compress_provider(
     return provider
 
 
+def _get_fallback_chat_providers(
+    provider: Provider, plugin_context: Context, provider_settings: dict
+) -> list[Provider]:
+    fallback_ids = provider_settings.get("fallback_chat_models", [])
+    if not isinstance(fallback_ids, list):
+        logger.warning(
+            "fallback_chat_models setting is not a list, skip fallback providers."
+        )
+        return []
+
+    provider_id = str(provider.provider_config.get("id", ""))
+    seen_provider_ids: set[str] = {provider_id} if provider_id else set()
+    fallbacks: list[Provider] = []
+
+    for fallback_id in fallback_ids:
+        if not isinstance(fallback_id, str) or not fallback_id:
+            continue
+        if fallback_id in seen_provider_ids:
+            continue
+        fallback_provider = plugin_context.get_provider_by_id(fallback_id)
+        if fallback_provider is None:
+            logger.warning("Fallback chat provider `%s` not found, skip.", fallback_id)
+            continue
+        if not isinstance(fallback_provider, Provider):
+            logger.warning(
+                "Fallback chat provider `%s` is invalid type: %s, skip.",
+                fallback_id,
+                type(fallback_provider),
+            )
+            continue
+        fallbacks.append(fallback_provider)
+        seen_provider_ids.add(fallback_id)
+    return fallbacks
+
+
 async def build_main_agent(
     *,
     event: AstrMessageEvent,
@@ -870,6 +952,8 @@ async def build_main_agent(
                 return None
 
             req.prompt = event.message_str[len(config.provider_wake_prefix) :]
+
+            # media files attachments
             for comp in event.message_obj.message:
                 if isinstance(comp, Image):
                     image_path = await comp.convert_to_file_path()
@@ -885,6 +969,81 @@ async def build_main_agent(
                             text=f"[File Attachment: name {file_name}, path {file_path}]"
                         )
                     )
+            # quoted message attachments
+            reply_comps = [
+                comp for comp in event.message_obj.message if isinstance(comp, Reply)
+            ]
+            quoted_message_settings = _get_quoted_message_parser_settings(
+                config.provider_settings
+            )
+            fallback_quoted_image_count = 0
+            for comp in reply_comps:
+                has_embedded_image = False
+                if comp.chain:
+                    for reply_comp in comp.chain:
+                        if isinstance(reply_comp, Image):
+                            has_embedded_image = True
+                            image_path = await reply_comp.convert_to_file_path()
+                            req.image_urls.append(image_path)
+                            _append_quoted_image_attachment(req, image_path)
+                        elif isinstance(reply_comp, File):
+                            file_path = await reply_comp.get_file()
+                            file_name = reply_comp.name or os.path.basename(file_path)
+                            req.extra_user_content_parts.append(
+                                TextPart(
+                                    text=(
+                                        f"[File Attachment in quoted message: "
+                                        f"name {file_name}, path {file_path}]"
+                                    )
+                                )
+                            )
+
+                # Fallback quoted image extraction for reply-id-only payloads, or when
+                # embedded reply chain only contains placeholders (e.g. [Forward Message], [Image]).
+                if not has_embedded_image:
+                    try:
+                        fallback_images = normalize_and_dedupe_strings(
+                            await extract_quoted_message_images(
+                                event,
+                                comp,
+                                settings=quoted_message_settings,
+                            )
+                        )
+                        remaining_limit = max(
+                            config.max_quoted_fallback_images
+                            - fallback_quoted_image_count,
+                            0,
+                        )
+                        if remaining_limit <= 0 and fallback_images:
+                            logger.warning(
+                                "Skip quoted fallback images due to limit=%d for umo=%s",
+                                config.max_quoted_fallback_images,
+                                event.unified_msg_origin,
+                            )
+                            continue
+                        if len(fallback_images) > remaining_limit:
+                            logger.warning(
+                                "Truncate quoted fallback images for umo=%s, reply_id=%s from %d to %d",
+                                event.unified_msg_origin,
+                                getattr(comp, "id", None),
+                                len(fallback_images),
+                                remaining_limit,
+                            )
+                            fallback_images = fallback_images[:remaining_limit]
+                        for image_ref in fallback_images:
+                            if image_ref in req.image_urls:
+                                continue
+                            req.image_urls.append(image_ref)
+                            fallback_quoted_image_count += 1
+                            _append_quoted_image_attachment(req, image_ref)
+                    except Exception as exc:  # noqa: BLE001
+                        logger.warning(
+                            "Failed to resolve fallback quoted images for umo=%s, reply_id=%s: %s",
+                            event.unified_msg_origin,
+                            getattr(comp, "id", None),
+                            exc,
+                            exc_info=True,
+                        )
 
             conversation = await _get_session_conv(event, plugin_context)
             req.conversation = conversation
@@ -893,6 +1052,7 @@ async def build_main_agent(
 
     if isinstance(req.contexts, str):
         req.contexts = json.loads(req.contexts)
+    req.image_urls = normalize_and_dedupe_strings(req.image_urls)
 
     if config.file_extract_enabled:
         try:
@@ -977,6 +1137,9 @@ async def build_main_agent(
         truncate_turns=config.dequeue_context_length,
         enforce_max_turns=config.max_context_length,
         tool_schema_mode=config.tool_schema_mode,
+        fallback_providers=_get_fallback_chat_providers(
+            provider, plugin_context, config.provider_settings
+        ),
     )
 
     if apply_reset:

astrbot/core/astr_main_agent_resources.py

@@ -1,6 +1,7 @@
 import base64
 import json
 import os
+import uuid
 
 from pydantic import Field
 from pydantic.dataclasses import dataclass
@@ -240,7 +241,9 @@ class SendMessageToUserTool(FunctionTool[AstrAgentContext]):
             if "_&exists_" in json.dumps(result):
                 # Download the file from sandbox
                 name = os.path.basename(path)
-                local_path = os.path.join(get_astrbot_temp_path(), name)
+                local_path = os.path.join(
+                    get_astrbot_temp_path(), f"sandbox_{uuid.uuid4().hex[:4]}_{name}"
+                )
                 await sb.download_file(path, local_path)
                 logger.info(f"Downloaded file from sandbox: {path} -> {local_path}")
                 return local_path, True
@@ -352,11 +355,11 @@ class SendMessageToUserTool(FunctionTool[AstrAgentContext]):
             MessageChain(chain=components),
         )
 
-        if file_from_sandbox:
-            try:
-                os.remove(local_path)
-            except Exception as e:
-                logger.error(f"Error removing temp file {local_path}: {e}")
+        # if file_from_sandbox:
+        #     try:
+        #         os.remove(local_path)
+        #     except Exception as e:
+        #         logger.error(f"Error removing temp file {local_path}: {e}")
 
         return f"Message sent to session {target_session}"
 

astrbot/core/astrbot_config_mgr.py

@@ -36,7 +36,7 @@ class AstrBotConfigManager:
         default_config: AstrBotConfig,
         ucr: UmopConfigRouter,
         sp: SharedPreferences,
-    ):
+    ) -> None:
         self.sp = sp
         self.ucr = ucr
         self.confs: dict[str, AstrBotConfig] = {}
@@ -56,7 +56,7 @@ class AstrBotConfigManager:
             )
         return self.abconf_data
 
-    def _load_all_configs(self):
+    def _load_all_configs(self) -> None:
         """Load all configurations from the shared preferences."""
         abconf_data = self._get_abconf_data()
         self.abconf_data = abconf_data

astrbot/core/backup/constants.py

@@ -11,6 +11,7 @@ from astrbot.core.db.po import (
     CommandConflict,
     ConversationV2,
     Persona,
+    PersonaFolder,
     PlatformMessageHistory,
     PlatformSession,
     PlatformStat,
@@ -39,6 +40,7 @@ MAIN_DB_MODELS: dict[str, type[SQLModel]] = {
     "platform_stats": PlatformStat,
     "conversations": ConversationV2,
     "personas": Persona,
+    "persona_folders": PersonaFolder,
     "preferences": Preference,
     "platform_message_history": PlatformMessageHistory,
     "platform_sessions": PlatformSession,

astrbot/core/backup/exporter.py

@@ -59,7 +59,7 @@ class AstrBotExporter:
         main_db: BaseDatabase,
         kb_manager: "KnowledgeBaseManager | None" = None,
         config_path: str = CMD_CONFIG_FILE_PATH,
-    ):
+    ) -> None:
         self.main_db = main_db
         self.kb_manager = kb_manager
         self.config_path = config_path

astrbot/core/backup/importer.py

@@ -110,7 +110,7 @@ class ImportPreCheckResult:
 class ImportResult:
     """导入结果"""
 
-    def __init__(self):
+    def __init__(self) -> None:
         self.success = True
         self.imported_tables: dict[str, int] = {}
         self.imported_files: dict[str, int] = {}
@@ -161,7 +161,7 @@ class AstrBotImporter:
         kb_manager: "KnowledgeBaseManager | None" = None,
         config_path: str = CMD_CONFIG_FILE_PATH,
         kb_root_dir: str = KB_PATH,
-    ):
+    ) -> None:
         self.main_db = main_db
         self.kb_manager = kb_manager
         self.config_path = config_path

astrbot/core/computer/booters/base.py

@@ -22,7 +22,7 @@ class ComputerBooter:
         """
         ...
 
-    async def download_file(self, remote_path: str, local_path: str):
+    async def download_file(self, remote_path: str, local_path: str) -> None:
         """Download file from the computer."""
         ...
 

astrbot/core/computer/booters/local.py

@@ -225,7 +225,7 @@ class LocalBooter(ComputerBooter):
             "LocalBooter does not support upload_file operation. Use shell instead."
         )
 
-    async def download_file(self, remote_path: str, local_path: str):
+    async def download_file(self, remote_path: str, local_path: str) -> None:
         raise NotImplementedError(
             "LocalBooter does not support download_file operation. Use shell instead."
         )

astrbot/core/computer/tools/fs.py

@@ -1,4 +1,5 @@
 import os
+import uuid
 from dataclasses import dataclass, field
 
 from astrbot.api import FunctionTool, logger
@@ -100,7 +101,7 @@ class FileUploadTool(FunctionTool):
         self,
         context: ContextWrapper[AstrAgentContext],
         local_path: str,
-    ):
+    ) -> str | None:
         sb = await get_booter(
             context.context.context,
             context.context.event.unified_msg_origin,
@@ -167,7 +168,9 @@ class FileDownloadTool(FunctionTool):
         try:
             name = os.path.basename(remote_path)
 
-            local_path = os.path.join(get_astrbot_temp_path(), name)
+            local_path = os.path.join(
+                get_astrbot_temp_path(), f"sandbox_{uuid.uuid4().hex[:4]}_{name}"
+            )
 
             # Download file from sandbox
             await sb.download_file(remote_path, local_path)
@@ -183,12 +186,12 @@ class FileDownloadTool(FunctionTool):
                     logger.error(f"Error sending file message: {e}")
 
                 # remove
-                try:
-                    os.remove(local_path)
-                except Exception as e:
-                    logger.error(f"Error removing temp file {local_path}: {e}")
+                # try:
+                #     os.remove(local_path)
+                # except Exception as e:
+                #     logger.error(f"Error removing temp file {local_path}: {e}")
 
-                return f"File downloaded successfully to {local_path} and sent to user. The file has been removed from local storage."
+                return f"File downloaded successfully to {local_path} and sent to user."
 
             return f"File downloaded successfully to {local_path}"
         except Exception as e:

astrbot/core/computer/tools/python.py

@@ -5,8 +5,9 @@ import mcp
 from astrbot.api import FunctionTool
 from astrbot.core.agent.run_context import ContextWrapper
 from astrbot.core.agent.tool import ToolExecResult
-from astrbot.core.astr_agent_context import AstrAgentContext
+from astrbot.core.astr_agent_context import AstrAgentContext, AstrMessageEvent
 from astrbot.core.computer.computer_client import get_booter, get_local_booter
+from astrbot.core.message.message_event_result import MessageChain
 
 param_schema = {
     "type": "object",
@@ -25,7 +26,7 @@ param_schema = {
 }
 
 
-def handle_result(result: dict) -> ToolExecResult:
+async def handle_result(result: dict, event: AstrMessageEvent) -> ToolExecResult:
     data = result.get("data", {})
     output = data.get("output", {})
     error = data.get("error", "")
@@ -44,6 +45,9 @@ def handle_result(result: dict) -> ToolExecResult:
                     type="image", data=img["image/png"], mimeType="image/png"
                 )
             )
+
+            if event.get_platform_name() == "webchat":
+                await event.send(message=MessageChain().base64_image(img["image/png"]))
     if text:
         resp.content.append(mcp.types.TextContent(type="text", text=text))
 
@@ -68,7 +72,7 @@ class PythonTool(FunctionTool):
         )
         try:
             result = await sb.python.exec(code, silent=silent)
-            return handle_result(result)
+            return await handle_result(result, context.context.event)
         except Exception as e:
             return f"Error executing code: {str(e)}"
 
@@ -84,11 +88,14 @@ class LocalPythonTool(FunctionTool):
         self, context: ContextWrapper[AstrAgentContext], code: str, silent: bool = False
     ) -> ToolExecResult:
         if context.context.event.role != "admin":
-            return "error: Permission denied. Local Python execution is only allowed for admin users. Tell user to set admins in AstrBot WebUI."
-
+            return (
+                "error: Permission denied. Local Python execution is only allowed for admin users. "
+                "Tell user to set admins in AstrBot WebUI by adding their user ID to the admins list if they need this feature."
+                f"User's ID is: {context.context.event.get_sender_id()}. User's ID can be found by using /sid command."
+            )
         sb = get_local_booter()
         try:
             result = await sb.python.exec(code, silent=silent)
-            return handle_result(result)
+            return await handle_result(result, context.context.event)
         except Exception as e:
             return f"Error executing code: {str(e)}"

astrbot/core/computer/tools/shell.py

@@ -47,7 +47,11 @@ class ExecuteShellTool(FunctionTool):
         env: dict = {},
     ) -> ToolExecResult:
         if context.context.event.role != "admin":
-            return "error: Permission denied. Shell execution is only allowed for admin users. Tell user to Set admins in AstrBot WebUI."
+            return (
+                "error: Permission denied. Local shell execution is only allowed for admin users. "
+                "Tell user to set admins in AstrBot WebUI by adding their user ID to the admins list if they need this feature."
+                f"User's ID is: {context.context.event.get_sender_id()}. User's ID can be found by using /sid command."
+            )
 
         if self.is_local:
             sb = get_local_booter()

astrbot/core/config/astrbot_config.py

@@ -33,7 +33,7 @@ class AstrBotConfig(dict):
         config_path: str = ASTRBOT_CONFIG_PATH,
         default_config: dict = DEFAULT_CONFIG,
         schema: dict | None = None,
-    ):
+    ) -> None:
         super().__init__()
 
         # 调用父类的 __setattr__ 方法，防止保存配置时将此属性写入配置文件
@@ -66,7 +66,7 @@ class AstrBotConfig(dict):
         """将 Schema 转换成 Config"""
         conf = {}
 
-        def _parse_schema(schema: dict, conf: dict):
+        def _parse_schema(schema: dict, conf: dict) -> None:
             for k, v in schema.items():
                 if v["type"] not in DEFAULT_VALUE_MAP:
                     raise TypeError(
@@ -148,7 +148,7 @@ class AstrBotConfig(dict):
 
         return has_new
 
-    def save_config(self, replace_config: dict | None = None):
+    def save_config(self, replace_config: dict | None = None) -> None:
         """将配置写入文件
 
         如果传入 replace_config，则将配置替换为 replace_config
@@ -164,14 +164,14 @@ class AstrBotConfig(dict):
         except KeyError:
             return None
 
-    def __delattr__(self, key):
+    def __delattr__(self, key) -> None:
         try:
             del self[key]
             self.save_config()
         except KeyError:
             raise AttributeError(f"没有找到 Key: '{key}'")
 
-    def __setattr__(self, key, value):
+    def __setattr__(self, key, value) -> None:
         self[key] = value
 
     def check_exist(self) -> bool:

astrbot/core/config/default.py

@@ -5,7 +5,7 @@ from typing import Any, TypedDict
 
 from astrbot.core.utils.astrbot_path import get_astrbot_data_path
 
-VERSION = "4.14.4"
+VERSION = "4.17.3"
 DB_PATH = os.path.join(get_astrbot_data_path(), "data_v4.db")
 
 WEBHOOK_SUPPORTED_PLATFORMS = [
@@ -15,6 +15,7 @@ WEBHOOK_SUPPORTED_PLATFORMS = [
     "wecom_ai_bot",
     "slack",
     "lark",
+    "line",
 ]
 
 # 默认配置
@@ -67,6 +68,7 @@ DEFAULT_CONFIG = {
     "provider_settings": {
         "enable": True,
         "default_provider_id": "",
+        "fallback_chat_models": [],
         "default_image_caption_provider_id": "",
         "image_caption_prompt": "Please describe the image using Chinese.",
         "provider_pool": ["*"],  # "*" 表示使用所有可用的提供者
@@ -74,6 +76,7 @@ DEFAULT_CONFIG = {
         "web_search": False,
         "websearch_provider": "default",
         "websearch_tavily_key": [],
+        "websearch_bocha_key": [],
         "websearch_baidu_app_builder_key": "",
         "web_search_link": False,
         "display_reasoning_text": False,
@@ -98,6 +101,13 @@ DEFAULT_CONFIG = {
         "streaming_response": False,
         "show_tool_use_status": False,
         "sanitize_context_by_modalities": False,
+        "max_quoted_fallback_images": 20,
+        "quoted_message_parser": {
+            "max_component_chain_depth": 4,
+            "max_forward_node_depth": 6,
+            "max_forward_fetch": 32,
+            "warn_on_action_failure": False,
+        },
         "agent_runner_type": "local",
         "dify_agent_runner_provider_id": "",
         "coze_agent_runner_provider_id": "",
@@ -128,8 +138,9 @@ DEFAULT_CONFIG = {
     },
     # SubAgent orchestrator mode:
     # - main_enable = False: disabled; main LLM mounts tools normally (persona selection).
-    # - main_enable = True: enabled; main LLM will include handoff tools and can optionally
-    #   remove tools that are duplicated on subagents via remove_main_duplicate_tools.
+    # - main_enable = True: enabled; main LLM keeps its own tools and includes handoff
+    #   tools (transfer_to_*). remove_main_duplicate_tools can remove tools that are
+    #   duplicated on subagents from the main LLM toolset.
     "subagent_orchestrator": {
         "main_enable": False,
         "remove_main_duplicate_tools": False,
@@ -176,7 +187,7 @@ DEFAULT_CONFIG = {
     "t2i_use_file_service": False,
     "t2i_active_template": "base",
     "http_proxy": "",
-    "no_proxy": ["localhost", "127.0.0.1", "::1"],
+    "no_proxy": ["localhost", "127.0.0.1", "::1", "10.*", "192.168.*"],
     "dashboard": {
         "enable": True,
         "username": "astrbot",
@@ -185,6 +196,12 @@ DEFAULT_CONFIG = {
         "host": "0.0.0.0",
         "port": 6185,
         "disable_access_log": True,
+        "ssl": {
+            "enable": False,
+            "cert_file": "",
+            "key_file": "",
+            "ca_certs": "",
+        },
     },
     "platform": [],
     "platform_specific": {
@@ -201,6 +218,7 @@ DEFAULT_CONFIG = {
     "log_file_enable": False,
     "log_file_path": "logs/astrbot.log",
     "log_file_max_mb": 20,
+    "temp_dir_max_size": 1024,
     "trace_enable": False,
     "trace_log_enable": False,
     "trace_log_path": "logs/astrbot.trace.log",
@@ -318,9 +336,11 @@ CONFIG_METADATA_2 = {
                         "id": "wecom_ai_bot",
                         "type": "wecom_ai_bot",
                         "enable": True,
-                        "wecomaibot_init_respond_text": "💭 思考中...",
+                        "wecomaibot_init_respond_text": "",
                         "wecomaibot_friend_message_welcome_text": "",
                         "wecom_ai_bot_name": "",
+                        "msg_push_webhook_url": "",
+                        "only_use_webhook_url_to_send": False,
                         "token": "",
                         "encoding_aes_key": "",
                         "unified_webhook_mode": True,
@@ -403,6 +423,7 @@ CONFIG_METADATA_2 = {
                         "slack_webhook_port": 6197,
                         "slack_webhook_path": "/astrbot-slack-webhook/callback",
                     },
+                    # LINE's config is located in line_adapter.py
                     "Satori": {
                         "id": "satori",
                         "type": "satori",
@@ -686,13 +707,23 @@ CONFIG_METADATA_2 = {
                     "wecomaibot_init_respond_text": {
                         "description": "企业微信智能机器人初始响应文本",
                         "type": "string",
-                        "hint": "当机器人收到消息时，首先回复的文本内容。留空则使用默认值。",
+                        "hint": "当机器人收到消息时，首先回复的文本内容。留空则不设置。",
                     },
                     "wecomaibot_friend_message_welcome_text": {
                         "description": "企业微信智能机器人私聊欢迎语",
                         "type": "string",
                         "hint": "当用户当天进入智能机器人单聊会话，回复欢迎语，留空则不回复。",
                     },
+                    "msg_push_webhook_url": {
+                        "description": "企业微信消息推送 Webhook URL",
+                        "type": "string",
+                        "hint": "用于 send_by_session 主动消息推送。格式示例: https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx",
+                    },
+                    "only_use_webhook_url_to_send": {
+                        "description": "仅使用 Webhook 发送消息",
+                        "type": "bool",
+                        "hint": "启用后，企业微信智能机器人的所有回复都改为通过消息推送 Webhook 发送。消息推送 Webhook 支持更多的消息类型（如图片、文件等）。",
+                    },
                     "lark_bot_name": {
                         "description": "飞书机器人的名字",
                         "type": "string",
@@ -912,6 +943,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "api_base": "https://api.openai.com/v1",
                         "timeout": 120,
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "Google Gemini": {
@@ -934,6 +966,7 @@ CONFIG_METADATA_2 = {
                             "dangerous_content": "BLOCK_MEDIUM_AND_ABOVE",
                         },
                         "gm_thinking_config": {"budget": 0, "level": "HIGH"},
+                        "proxy": "",
                     },
                     "Anthropic": {
                         "id": "anthropic",
@@ -944,6 +977,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "api_base": "https://api.anthropic.com/v1",
                         "timeout": 120,
+                        "proxy": "",
                         "anth_thinking_config": {"budget": 0},
                     },
                     "Moonshot": {
@@ -955,6 +989,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "timeout": 120,
                         "api_base": "https://api.moonshot.cn/v1",
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "xAI": {
@@ -966,6 +1001,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "api_base": "https://api.x.ai/v1",
                         "timeout": 120,
+                        "proxy": "",
                         "custom_headers": {},
                         "xai_native_search": False,
                     },
@@ -978,6 +1014,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "api_base": "https://api.deepseek.com/v1",
                         "timeout": 120,
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "Zhipu": {
@@ -989,6 +1026,19 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "timeout": 120,
                         "api_base": "https://open.bigmodel.cn/api/paas/v4/",
+                        "proxy": "",
+                        "custom_headers": {},
+                    },
+                    "NVIDIA": {
+                        "id": "nvidia",
+                        "provider": "nvidia",
+                        "type": "openai_chat_completion",
+                        "provider_type": "chat_completion",
+                        "enable": True,
+                        "key": [],
+                        "api_base": "https://integrate.api.nvidia.com/v1",
+                        "timeout": 120,
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "Azure OpenAI": {
@@ -1001,6 +1051,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "api_base": "",
                         "timeout": 120,
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "Ollama": {
@@ -1011,6 +1062,7 @@ CONFIG_METADATA_2 = {
                         "enable": True,
                         "key": ["ollama"],  # ollama 的 key 默认是 ollama
                         "api_base": "http://127.0.0.1:11434/v1",
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "LM Studio": {
@@ -1021,6 +1073,7 @@ CONFIG_METADATA_2 = {
                         "enable": True,
                         "key": ["lmstudio"],
                         "api_base": "http://127.0.0.1:1234/v1",
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "Gemini_OpenAI_API": {
@@ -1032,6 +1085,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "api_base": "https://generativelanguage.googleapis.com/v1beta/openai/",
                         "timeout": 120,
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "Groq": {
@@ -1043,6 +1097,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "api_base": "https://api.groq.com/openai/v1",
                         "timeout": 120,
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "302.AI": {
@@ -1054,6 +1109,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "api_base": "https://api.302.ai/v1",
                         "timeout": 120,
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "SiliconFlow": {
@@ -1065,6 +1121,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "timeout": 120,
                         "api_base": "https://api.siliconflow.cn/v1",
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "PPIO": {
@@ -1076,6 +1133,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "api_base": "https://api.ppinfra.com/v3/openai",
                         "timeout": 120,
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "TokenPony": {
@@ -1087,6 +1145,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "api_base": "https://api.tokenpony.cn/v1",
                         "timeout": 120,
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "Compshare": {
@@ -1098,6 +1157,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "api_base": "https://api.modelverse.cn/v1",
                         "timeout": 120,
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "ModelScope": {
@@ -1109,6 +1169,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "timeout": 120,
                         "api_base": "https://api-inference.modelscope.cn/v1",
+                        "proxy": "",
                         "custom_headers": {},
                     },
                     "Dify": {
@@ -1124,6 +1185,7 @@ CONFIG_METADATA_2 = {
                         "dify_query_input_key": "astrbot_text_query",
                         "variables": {},
                         "timeout": 60,
+                        "proxy": "",
                     },
                     "Coze": {
                         "id": "coze",
@@ -1135,6 +1197,7 @@ CONFIG_METADATA_2 = {
                         "bot_id": "",
                         "coze_api_base": "https://api.coze.cn",
                         "timeout": 60,
+                        "proxy": "",
                         # "auto_save_history": True,
                     },
                     "阿里云百炼应用": {
@@ -1153,6 +1216,7 @@ CONFIG_METADATA_2 = {
                         },
                         "variables": {},
                         "timeout": 60,
+                        "proxy": "",
                     },
                     "FastGPT": {
                         "id": "fastgpt",
@@ -1163,6 +1227,7 @@ CONFIG_METADATA_2 = {
                         "key": [],
                         "api_base": "https://api.fastgpt.in/api/v1",
                         "timeout": 60,
+                        "proxy": "",
                         "custom_headers": {},
                         "custom_extra_body": {},
                     },
@@ -1175,6 +1240,7 @@ CONFIG_METADATA_2 = {
                         "api_key": "",
                         "api_base": "",
                         "model": "whisper-1",
+                        "proxy": "",
                     },
                     "Whisper(Local)": {
                         "provider": "openai",
@@ -1204,6 +1270,7 @@ CONFIG_METADATA_2 = {
                         "model": "tts-1",
                         "openai-tts-voice": "alloy",
                         "timeout": "20",
+                        "proxy": "",
                     },
                     "Genie TTS": {
                         "id": "genie_tts",
@@ -1284,6 +1351,7 @@ CONFIG_METADATA_2 = {
                         "fishaudio-tts-character": "可莉",
                         "fishaudio-tts-reference-id": "",
                         "timeout": "20",
+                        "proxy": "",
                     },
                     "阿里云百炼 TTS(API)": {
                         "hint": "API Key 从 https://bailian.console.aliyun.com/?tab=model#/api-key 获取。模型和音色的选择文档请参考: 阿里云百炼语音合成音色名称。具体可参考 https://help.aliyun.com/zh/model-studio/speech-synthesis-and-speech-recognition",
@@ -1310,6 +1378,7 @@ CONFIG_METADATA_2 = {
                         "azure_tts_volume": "100",
                         "azure_tts_subscription_key": "",
                         "azure_tts_region": "eastus",
+                        "proxy": "",
                     },
                     "MiniMax TTS(API)": {
                         "id": "minimax_tts",
@@ -1332,6 +1401,7 @@ CONFIG_METADATA_2 = {
                         "minimax-voice-latex": False,
                         "minimax-voice-english-normalization": False,
                         "timeout": 20,
+                        "proxy": "",
                     },
                     "火山引擎_TTS(API)": {
                         "id": "volcengine_tts",
@@ -1346,6 +1416,7 @@ CONFIG_METADATA_2 = {
                         "volcengine_speed_ratio": 1.0,
                         "api_base": "https://openspeech.bytedance.com/api/v1/tts",
                         "timeout": 20,
+                        "proxy": "",
                     },
                     "Gemini TTS": {
                         "id": "gemini_tts",
@@ -1359,6 +1430,7 @@ CONFIG_METADATA_2 = {
                         "gemini_tts_model": "gemini-2.5-flash-preview-tts",
                         "gemini_tts_prefix": "",
                         "gemini_tts_voice_name": "Leda",
+                        "proxy": "",
                     },
                     "OpenAI Embedding": {
                         "id": "openai_embedding",
@@ -1371,6 +1443,7 @@ CONFIG_METADATA_2 = {
                         "embedding_model": "",
                         "embedding_dimensions": 1024,
                         "timeout": 20,
+                        "proxy": "",
                     },
                     "Gemini Embedding": {
                         "id": "gemini_embedding",
@@ -1383,6 +1456,7 @@ CONFIG_METADATA_2 = {
                         "embedding_model": "gemini-embedding-exp-03-07",
                         "embedding_dimensions": 768,
                         "timeout": 20,
+                        "proxy": "",
                     },
                     "vLLM Rerank": {
                         "id": "vllm_rerank",
@@ -2079,6 +2153,11 @@ CONFIG_METADATA_2 = {
                         "description": "API Base URL",
                         "type": "string",
                     },
+                    "proxy": {
+                        "description": "代理地址",
+                        "type": "string",
+                        "hint": "HTTP/HTTPS 代理地址，格式如 http://127.0.0.1:7890。仅对该提供商的 API 请求生效，不影响 Docker 内网通信。",
+                    },
                     "model": {
                         "description": "模型 ID",
                         "type": "string",
@@ -2147,6 +2226,10 @@ CONFIG_METADATA_2 = {
                     "default_provider_id": {
                         "type": "string",
                     },
+                    "fallback_chat_models": {
+                        "type": "list",
+                        "items": {"type": "string"},
+                    },
                     "wake_prefix": {
                         "type": "string",
                     },
@@ -2341,9 +2424,23 @@ CONFIG_METADATA_2 = {
                 "type": "string",
                 "options": ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
             },
+            "dashboard.ssl.enable": {"type": "bool"},
+            "dashboard.ssl.cert_file": {
+                "type": "string",
+                "condition": {"dashboard.ssl.enable": True},
+            },
+            "dashboard.ssl.key_file": {
+                "type": "string",
+                "condition": {"dashboard.ssl.enable": True},
+            },
+            "dashboard.ssl.ca_certs": {
+                "type": "string",
+                "condition": {"dashboard.ssl.enable": True},
+            },
             "log_file_enable": {"type": "bool"},
             "log_file_path": {"type": "string", "condition": {"log_file_enable": True}},
             "log_file_max_mb": {"type": "int", "condition": {"log_file_enable": True}},
+            "temp_dir_max_size": {"type": "int"},
             "trace_log_enable": {"type": "bool"},
             "trace_log_path": {
                 "type": "string",
@@ -2443,15 +2540,22 @@ CONFIG_METADATA_3 = {
             },
             "ai": {
                 "description": "模型",
-                "hint": "当使用非内置 Agent 执行器时，默认聊天模型和默认图片转述模型可能会无效，但某些插件会依赖此配置项来调用 AI 能力。",
+                "hint": "当使用非内置 Agent 执行器时，默认对话模型和默认图片转述模型可能会无效，但某些插件会依赖此配置项来调用 AI 能力。",
                 "type": "object",
                 "items": {
                     "provider_settings.default_provider_id": {
-                        "description": "默认聊天模型",
+                        "description": "默认对话模型",
                         "type": "string",
                         "_special": "select_provider",
                         "hint": "留空时使用第一个模型",
                     },
+                    "provider_settings.fallback_chat_models": {
+                        "description": "回退对话模型列表",
+                        "type": "list",
+                        "items": {"type": "string"},
+                        "_special": "select_providers",
+                        "hint": "主聊天模型请求失败时，按顺序切换到这些模型。",
+                    },
                     "provider_settings.default_image_caption_provider_id": {
                         "description": "默认图片转述模型",
                         "type": "string",
@@ -2563,7 +2667,7 @@ CONFIG_METADATA_3 = {
                     "provider_settings.websearch_provider": {
                         "description": "网页搜索提供商",
                         "type": "string",
-                        "options": ["default", "tavily", "baidu_ai_search"],
+                        "options": ["default", "tavily", "baidu_ai_search", "bocha"],
                         "condition": {
                             "provider_settings.web_search": True,
                         },
@@ -2578,6 +2682,16 @@ CONFIG_METADATA_3 = {
                             "provider_settings.web_search": True,
                         },
                     },
+                    "provider_settings.websearch_bocha_key": {
+                        "description": "BoCha API Key",
+                        "type": "list",
+                        "items": {"type": "string"},
+                        "hint": "可添加多个 Key 进行轮询。",
+                        "condition": {
+                            "provider_settings.websearch_provider": "bocha",
+                            "provider_settings.web_search": True,
+                        },
+                    },
                     "provider_settings.websearch_baidu_app_builder_key": {
                         "description": "百度千帆智能云 APP Builder API Key",
                         "type": "string",
@@ -2846,6 +2960,46 @@ CONFIG_METADATA_3 = {
                             "provider_settings.agent_runner_type": "local",
                         },
                     },
+                    "provider_settings.max_quoted_fallback_images": {
+                        "description": "引用图片回退解析上限",
+                        "type": "int",
+                        "hint": "引用/转发消息回退解析图片时的最大注入数量，超出会截断。",
+                        "condition": {
+                            "provider_settings.agent_runner_type": "local",
+                        },
+                    },
+                    "provider_settings.quoted_message_parser.max_component_chain_depth": {
+                        "description": "引用解析组件链深度",
+                        "type": "int",
+                        "hint": "解析 Reply 组件链时允许的最大递归深度。",
+                        "condition": {
+                            "provider_settings.agent_runner_type": "local",
+                        },
+                    },
+                    "provider_settings.quoted_message_parser.max_forward_node_depth": {
+                        "description": "引用解析转发节点深度",
+                        "type": "int",
+                        "hint": "解析合并转发节点时允许的最大递归深度。",
+                        "condition": {
+                            "provider_settings.agent_runner_type": "local",
+                        },
+                    },
+                    "provider_settings.quoted_message_parser.max_forward_fetch": {
+                        "description": "引用解析转发拉取上限",
+                        "type": "int",
+                        "hint": "递归拉取 get_forward_msg 的最大次数。",
+                        "condition": {
+                            "provider_settings.agent_runner_type": "local",
+                        },
+                    },
+                    "provider_settings.quoted_message_parser.warn_on_action_failure": {
+                        "description": "引用解析 action 失败告警",
+                        "type": "bool",
+                        "hint": "开启后，get_msg/get_forward_msg 全部尝试失败时输出 warning 日志。",
+                        "condition": {
+                            "provider_settings.agent_runner_type": "local",
+                        },
+                    },
                     "provider_settings.max_agent_step": {
                         "description": "工具调用轮数上限",
                         "type": "int",
@@ -3297,6 +3451,29 @@ CONFIG_METADATA_3_SYSTEM = {
                         "hint": "控制台输出日志的级别。",
                         "options": ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
                     },
+                    "dashboard.ssl.enable": {
+                        "description": "启用 WebUI HTTPS",
+                        "type": "bool",
+                        "hint": "启用后，WebUI 将直接使用 HTTPS 提供服务。",
+                    },
+                    "dashboard.ssl.cert_file": {
+                        "description": "SSL 证书文件路径",
+                        "type": "string",
+                        "hint": "证书文件路径（PEM）。支持绝对路径和相对路径（相对于当前工作目录）。",
+                        "condition": {"dashboard.ssl.enable": True},
+                    },
+                    "dashboard.ssl.key_file": {
+                        "description": "SSL 私钥文件路径",
+                        "type": "string",
+                        "hint": "私钥文件路径（PEM）。支持绝对路径和相对路径（相对于当前工作目录）。",
+                        "condition": {"dashboard.ssl.enable": True},
+                    },
+                    "dashboard.ssl.ca_certs": {
+                        "description": "SSL CA 证书文件路径",
+                        "type": "string",
+                        "hint": "可选。用于指定 CA 证书文件路径。",
+                        "condition": {"dashboard.ssl.enable": True},
+                    },
                     "log_file_enable": {
                         "description": "启用文件日志",
                         "type": "bool",
@@ -3312,6 +3489,11 @@ CONFIG_METADATA_3_SYSTEM = {
                         "type": "int",
                         "hint": "超过大小后自动轮转，默认 20MB。",
                     },
+                    "temp_dir_max_size": {
+                        "description": "临时目录大小上限 (MB)",
+                        "type": "int",
+                        "hint": "用于限制 data/temp 目录总大小，单位为 MB。系统每 10 分钟检查一次，超限时按文件修改时间从旧到新删除，释放约 30% 当前体积。",
+                    },
                     "trace_log_enable": {
                         "description": "启用 Trace 文件日志",
                         "type": "bool",

astrbot/core/config/i18n_utils.py

@@ -42,6 +42,55 @@ class ConfigMetadataI18n:
         """
         result = {}
 
+        def convert_items(
+            group: str, section: str, items: dict[str, Any], prefix: str = ""
+        ) -> dict[str, Any]:
+            items_result: dict[str, Any] = {}
+
+            for field_key, field_data in items.items():
+                if not isinstance(field_data, dict):
+                    items_result[field_key] = field_data
+                    continue
+
+                field_name = field_key
+                field_path = f"{prefix}.{field_name}" if prefix else field_name
+
+                field_result = {
+                    key: value
+                    for key, value in field_data.items()
+                    if key not in {"description", "hint", "labels", "name"}
+                }
+
+                if "description" in field_data:
+                    field_result["description"] = (
+                        f"{group}.{section}.{field_path}.description"
+                    )
+                if "hint" in field_data:
+                    field_result["hint"] = f"{group}.{section}.{field_path}.hint"
+                if "labels" in field_data:
+                    field_result["labels"] = f"{group}.{section}.{field_path}.labels"
+                if "name" in field_data:
+                    field_result["name"] = f"{group}.{section}.{field_path}.name"
+
+                if "items" in field_data and isinstance(field_data["items"], dict):
+                    field_result["items"] = convert_items(
+                        group, section, field_data["items"], field_path
+                    )
+
+                if "template_schema" in field_data and isinstance(
+                    field_data["template_schema"], dict
+                ):
+                    field_result["template_schema"] = convert_items(
+                        group,
+                        section,
+                        field_data["template_schema"],
+                        f"{field_path}.template_schema",
+                    )
+
+                items_result[field_key] = field_result
+
+            return items_result
+
         for group_key, group_data in metadata.items():
             group_result = {
                 "name": f"{group_key}.name",
@@ -50,59 +99,19 @@ class ConfigMetadataI18n:
 
             for section_key, section_data in group_data.get("metadata", {}).items():
                 section_result = {
-                    "description": f"{group_key}.{section_key}.description",
-                    "type": section_data.get("type"),
+                    key: value
+                    for key, value in section_data.items()
+                    if key not in {"description", "hint", "labels", "name"}
                 }
+                section_result["description"] = f"{group_key}.{section_key}.description"
 
-                # 复制其他属性
-                for key in ["items", "condition", "_special", "invisible"]:
-                    if key in section_data:
-                        section_result[key] = section_data[key]
-
-                # 处理 hint
                 if "hint" in section_data:
                     section_result["hint"] = f"{group_key}.{section_key}.hint"
 
-                # 处理 items 中的字段
                 if "items" in section_data and isinstance(section_data["items"], dict):
-                    items_result = {}
-                    for field_key, field_data in section_data["items"].items():
-                        # 处理嵌套的点号字段名（如 provider_settings.enable）
-                        field_name = field_key
-
-                        field_result = {}
-
-                        # 复制基本属性
-                        for attr in [
-                            "type",
-                            "condition",
-                            "_special",
-                            "invisible",
-                            "options",
-                            "slider",
-                        ]:
-                            if attr in field_data:
-                                field_result[attr] = field_data[attr]
-
-                        # 转换文本属性为国际化键
-                        if "description" in field_data:
-                            field_result["description"] = (
-                                f"{group_key}.{section_key}.{field_name}.description"
-                            )
-
-                        if "hint" in field_data:
-                            field_result["hint"] = (
-                                f"{group_key}.{section_key}.{field_name}.hint"
-                            )
-
-                        if "labels" in field_data:
-                            field_result["labels"] = (
-                                f"{group_key}.{section_key}.{field_name}.labels"
-                            )
-
-                        items_result[field_key] = field_result
-
-                    section_result["items"] = items_result
+                    section_result["items"] = convert_items(
+                        group_key, section_key, section_data["items"]
+                    )
 
                 group_result["metadata"][section_key] = section_result
 

astrbot/core/conversation_mgr.py

@@ -16,7 +16,7 @@ from astrbot.core.db.po import Conversation, ConversationV2
 class ConversationManager:
     """负责管理会话与 LLM 的对话，某个会话当前正在用哪个对话。"""
 
-    def __init__(self, db_helper: BaseDatabase):
+    def __init__(self, db_helper: BaseDatabase) -> None:
         self.session_conversations: dict[str, str] = {}
         self.db = db_helper
         self.save_interval = 60  # 每 60 秒保存一次
@@ -106,7 +106,9 @@ class ConversationManager:
         await sp.session_put(unified_msg_origin, "sel_conv_id", conv.conversation_id)
         return conv.conversation_id
 
-    async def switch_conversation(self, unified_msg_origin: str, conversation_id: str):
+    async def switch_conversation(
+        self, unified_msg_origin: str, conversation_id: str
+    ) -> None:
         """切换会话的对话
 
         Args:
@@ -121,7 +123,7 @@ class ConversationManager:
         self,
         unified_msg_origin: str,
         conversation_id: str | None = None,
-    ):
+    ) -> None:
         """删除会话的对话，当 conversation_id 为 None 时删除会话当前的对话
 
         Args:
@@ -138,7 +140,7 @@ class ConversationManager:
                 self.session_conversations.pop(unified_msg_origin, None)
                 await sp.session_remove(unified_msg_origin, "sel_conv_id")
 
-    async def delete_conversations_by_user_id(self, unified_msg_origin: str):
+    async def delete_conversations_by_user_id(self, unified_msg_origin: str) -> None:
         """删除会话的所有对话
 
         Args:

astrbot/core/core_lifecycle.py

@@ -37,6 +37,7 @@ from astrbot.core.umop_config_router import UmopConfigRouter
 from astrbot.core.updator import AstrBotUpdator
 from astrbot.core.utils.llm_metadata import update_llm_metadata
 from astrbot.core.utils.migra_helper import migra
+from astrbot.core.utils.temp_dir_cleaner import TempDirCleaner
 
 from . import astrbot_config, html_renderer
 from .event_bus import EventBus
@@ -57,6 +58,7 @@ class AstrBotCoreLifecycle:
 
         self.subagent_orchestrator: SubAgentOrchestrator | None = None
         self.cron_manager: CronJobManager | None = None
+        self.temp_dir_cleaner: TempDirCleaner | None = None
 
         # 设置代理
         proxy_config = self.astrbot_config.get("http_proxy", "")
@@ -125,6 +127,12 @@ class AstrBotCoreLifecycle:
             ucr=self.umop_config_router,
             sp=sp,
         )
+        self.temp_dir_cleaner = TempDirCleaner(
+            max_size_getter=lambda: self.astrbot_config_mgr.default_conf.get(
+                TempDirCleaner.CONFIG_KEY,
+                TempDirCleaner.DEFAULT_MAX_SIZE,
+            ),
+        )
 
         # apply migration
         try:
@@ -238,6 +246,12 @@ class AstrBotCoreLifecycle:
                 self.cron_manager.start(self.star_context),
                 name="cron_manager",
             )
+        temp_dir_cleaner_task = None
+        if self.temp_dir_cleaner:
+            temp_dir_cleaner_task = asyncio.create_task(
+                self.temp_dir_cleaner.run(),
+                name="temp_dir_cleaner",
+            )
 
         # 把插件中注册的所有协程函数注册到事件总线中并执行
         extra_tasks = []
@@ -247,6 +261,8 @@ class AstrBotCoreLifecycle:
         tasks_ = [event_bus_task, *(extra_tasks if extra_tasks else [])]
         if cron_task:
             tasks_.append(cron_task)
+        if temp_dir_cleaner_task:
+            tasks_.append(temp_dir_cleaner_task)
         for task in tasks_:
             self.curr_tasks.append(
                 asyncio.create_task(self._task_wrapper(task), name=task.get_name()),
@@ -298,6 +314,9 @@ class AstrBotCoreLifecycle:
 
     async def stop(self) -> None:
         """停止 AstrBot 核心生命周期管理类, 取消所有当前任务并终止各个管理器."""
+        if self.temp_dir_cleaner:
+            await self.temp_dir_cleaner.stop()
+
         # 请求停止所有正在运行的异步任务
         for task in self.curr_tasks:
             task.cancel()

astrbot/core/cron/events.py

@@ -24,7 +24,7 @@ class CronMessageEvent(AstrMessageEvent):
         sender_name: str = "Scheduler",
         extras: dict[str, Any] | None = None,
         message_type: MessageType = MessageType.FRIEND_MESSAGE,
-    ):
+    ) -> None:
         platform_meta = PlatformMetadata(
             name="cron",
             description="CronJob",
@@ -53,13 +53,13 @@ class CronMessageEvent(AstrMessageEvent):
         if extras:
             self._extras.update(extras)
 
-    async def send(self, message: MessageChain):
+    async def send(self, message: MessageChain) -> None:
         if message is None:
             return
         await self.context_obj.send_message(self.session, message)
         await super().send(message)
 
-    async def send_streaming(self, generator, use_fallback: bool = False):
+    async def send_streaming(self, generator, use_fallback: bool = False) -> None:
         async for chain in generator:
             await self.send(chain)
 

astrbot/core/cron/manager.py

@@ -25,14 +25,14 @@ if TYPE_CHECKING:
 class CronJobManager:
     """Central scheduler for BasicCronJob and ActiveAgentCronJob."""
 
-    def __init__(self, db: BaseDatabase):
+    def __init__(self, db: BaseDatabase) -> None:
         self.db = db
         self.scheduler = AsyncIOScheduler()
         self._basic_handlers: dict[str, Callable[..., Any]] = {}
         self._lock = asyncio.Lock()
         self._started = False
 
-    async def start(self, ctx: "Context"):
+    async def start(self, ctx: "Context") -> None:
         self.ctx: Context = ctx  # star context
         async with self._lock:
             if self._started:
@@ -41,14 +41,14 @@ class CronJobManager:
             self._started = True
             await self.sync_from_db()
 
-    async def shutdown(self):
+    async def shutdown(self) -> None:
         async with self._lock:
             if not self._started:
                 return
             self.scheduler.shutdown(wait=False)
             self._started = False
 
-    async def sync_from_db(self):
+    async def sync_from_db(self) -> None:
         jobs = await self.db.list_cron_jobs()
         for job in jobs:
             if not job.enabled or not job.persistent:
@@ -136,11 +136,11 @@ class CronJobManager:
     async def list_jobs(self, job_type: str | None = None) -> list[CronJob]:
         return await self.db.list_cron_jobs(job_type)
 
-    def _remove_scheduled(self, job_id: str):
+    def _remove_scheduled(self, job_id: str) -> None:
         if self.scheduler.get_job(job_id):
             self.scheduler.remove_job(job_id)
 
-    def _schedule_job(self, job: CronJob):
+    def _schedule_job(self, job: CronJob) -> None:
         if not self._started:
             self.scheduler.start()
             self._started = True
@@ -188,7 +188,7 @@ class CronJobManager:
         aps_job = self.scheduler.get_job(job_id)
         return aps_job.next_run_time if aps_job else None
 
-    async def _run_job(self, job_id: str):
+    async def _run_job(self, job_id: str) -> None:
         job = await self.db.get_cron_job(job_id)
         if not job or not job.enabled:
             return
@@ -222,7 +222,7 @@ class CronJobManager:
                 # one-shot: remove after execution regardless of success
                 await self.delete_job(job_id)
 
-    async def _run_basic_job(self, job: CronJob):
+    async def _run_basic_job(self, job: CronJob) -> None:
         handler = self._basic_handlers.get(job.job_id)
         if not handler:
             raise RuntimeError(f"Basic cron job handler not found for {job.job_id}")
@@ -231,7 +231,7 @@ class CronJobManager:
         if asyncio.iscoroutine(result):
             await result
 
-    async def _run_active_agent_job(self, job: CronJob, start_time: datetime):
+    async def _run_active_agent_job(self, job: CronJob, start_time: datetime) -> None:
         payload = job.payload or {}
         session_str = payload.get("session")
         if not session_str:
@@ -266,7 +266,7 @@ class CronJobManager:
         message: str,
         session_str: str,
         extras: dict,
-    ):
+    ) -> None:
         """Woke the main agent to handle the cron job message."""
         from astrbot.core.astr_main_agent import (
             MainAgentBuildConfig,

astrbot/core/db/__init__.py

@@ -43,7 +43,7 @@ class BaseDatabase(abc.ABC):
             expire_on_commit=False,
         )
 
-    async def initialize(self):
+    async def initialize(self) -> None:
         """初始化数据库连接"""
 
     @asynccontextmanager

astrbot/core/db/migration/migra_3_to_4.py

@@ -43,7 +43,7 @@ def get_platform_type(
 async def migration_conversation_table(
     db_helper: BaseDatabase,
     platform_id_map: dict[str, dict[str, str]],
-):
+) -> None:
     db_helper_v3 = SQLiteV3DatabaseV3(
         db_path=DB_PATH.replace("data_v4.db", "data_v3.db"),
     )
@@ -101,7 +101,7 @@ async def migration_conversation_table(
 async def migration_platform_table(
     db_helper: BaseDatabase,
     platform_id_map: dict[str, dict[str, str]],
-):
+) -> None:
     db_helper_v3 = SQLiteV3DatabaseV3(
         db_path=DB_PATH.replace("data_v4.db", "data_v3.db"),
     )
@@ -180,7 +180,7 @@ async def migration_platform_table(
 async def migration_webchat_data(
     db_helper: BaseDatabase,
     platform_id_map: dict[str, dict[str, str]],
-):
+) -> None:
     """迁移 WebChat 的历史记录到新的 PlatformMessageHistory 表中"""
     db_helper_v3 = SQLiteV3DatabaseV3(
         db_path=DB_PATH.replace("data_v4.db", "data_v3.db"),
@@ -236,7 +236,7 @@ async def migration_webchat_data(
 async def migration_persona_data(
     db_helper: BaseDatabase,
     astrbot_config: AstrBotConfig,
-):
+) -> None:
     """迁移 Persona 数据到新的表中。
     旧的 Persona 数据存储在 preference 中，新的 Persona 数据存储在 persona 表中。
     """
@@ -279,7 +279,7 @@ async def migration_persona_data(
 async def migration_preferences(
     db_helper: BaseDatabase,
     platform_id_map: dict[str, dict[str, str]],
-):
+) -> None:
     # 1. global scope migration
     keys = [
         "inactivated_llm_tools",

astrbot/core/db/migration/migra_45_to_46.py

@@ -3,7 +3,7 @@ from astrbot.core.astrbot_config_mgr import AstrBotConfigManager
 from astrbot.core.umop_config_router import UmopConfigRouter
 
 
-async def migrate_45_to_46(acm: AstrBotConfigManager, ucr: UmopConfigRouter):
+async def migrate_45_to_46(acm: AstrBotConfigManager, ucr: UmopConfigRouter) -> None:
     abconf_data = acm.abconf_data
 
     if not isinstance(abconf_data, dict):

astrbot/core/db/migration/migra_token_usage.py

@@ -12,7 +12,7 @@ from astrbot.api import logger, sp
 from astrbot.core.db import BaseDatabase
 
 
-async def migrate_token_usage(db_helper: BaseDatabase):
+async def migrate_token_usage(db_helper: BaseDatabase) -> None:
     """Add token_usage column to conversations table.
 
     This migration adds a new column to track token consumption in conversations.

astrbot/core/db/migration/migra_webchat_session.py

@@ -17,7 +17,7 @@ from astrbot.core.db import BaseDatabase
 from astrbot.core.db.po import ConversationV2, PlatformMessageHistory, PlatformSession
 
 
-async def migrate_webchat_session(db_helper: BaseDatabase):
+async def migrate_webchat_session(db_helper: BaseDatabase) -> None:
     """Create PlatformSession records from platform_message_history.
 
     This migration extracts all unique user_ids from platform_message_history

astrbot/core/db/migration/shared_preferences_v3.py

@@ -8,7 +8,7 @@ _VT = TypeVar("_VT")
 
 
 class SharedPreferences:
-    def __init__(self, path=None):
+    def __init__(self, path=None) -> None:
         if path is None:
             path = os.path.join(get_astrbot_data_path(), "shared_preferences.json")
         self.path = path
@@ -23,7 +23,7 @@ class SharedPreferences:
                 os.remove(self.path)
         return {}
 
-    def _save_preferences(self):
+    def _save_preferences(self) -> None:
         with open(self.path, "w") as f:
             json.dump(self._data, f, indent=4, ensure_ascii=False)
             f.flush()
@@ -31,16 +31,16 @@ class SharedPreferences:
     def get(self, key, default: _VT = None) -> _VT:
         return self._data.get(key, default)
 
-    def put(self, key, value):
+    def put(self, key, value) -> None:
         self._data[key] = value
         self._save_preferences()
 
-    def remove(self, key):
+    def remove(self, key) -> None:
         if key in self._data:
             del self._data[key]
             self._save_preferences()
 
-    def clear(self):
+    def clear(self) -> None:
         self._data.clear()
         self._save_preferences()
 

astrbot/core/db/migration/sqlite_v3.py

@@ -127,7 +127,7 @@ class SQLiteDatabase:
         conn.text_factory = str
         return conn
 
-    def _exec_sql(self, sql: str, params: tuple | None = None):
+    def _exec_sql(self, sql: str, params: tuple | None = None) -> None:
         conn = self.conn
         try:
             c = self.conn.cursor()
@@ -144,7 +144,7 @@ class SQLiteDatabase:
 
         conn.commit()
 
-    def insert_platform_metrics(self, metrics: dict):
+    def insert_platform_metrics(self, metrics: dict) -> None:
         for k, v in metrics.items():
             self._exec_sql(
                 """
@@ -153,7 +153,7 @@ class SQLiteDatabase:
                 (k, v, int(time.time())),
             )
 
-    def insert_llm_metrics(self, metrics: dict):
+    def insert_llm_metrics(self, metrics: dict) -> None:
         for k, v in metrics.items():
             self._exec_sql(
                 """
@@ -249,7 +249,7 @@ class SQLiteDatabase:
 
         return Conversation(*res)
 
-    def new_conversation(self, user_id: str, cid: str):
+    def new_conversation(self, user_id: str, cid: str) -> None:
         history = "[]"
         updated_at = int(time.time())
         created_at = updated_at
@@ -287,7 +287,7 @@ class SQLiteDatabase:
             )
         return conversations
 
-    def update_conversation(self, user_id: str, cid: str, history: str):
+    def update_conversation(self, user_id: str, cid: str, history: str) -> None:
         """更新对话，并且同时更新时间"""
         updated_at = int(time.time())
         self._exec_sql(
@@ -297,7 +297,7 @@ class SQLiteDatabase:
             (history, updated_at, user_id, cid),
         )
 
-    def update_conversation_title(self, user_id: str, cid: str, title: str):
+    def update_conversation_title(self, user_id: str, cid: str, title: str) -> None:
         self._exec_sql(
             """
             UPDATE webchat_conversation SET title = ? WHERE user_id = ? AND cid = ?
@@ -305,7 +305,9 @@ class SQLiteDatabase:
             (title, user_id, cid),
         )
 
-    def update_conversation_persona_id(self, user_id: str, cid: str, persona_id: str):
+    def update_conversation_persona_id(
+        self, user_id: str, cid: str, persona_id: str
+    ) -> None:
         self._exec_sql(
             """
             UPDATE webchat_conversation SET persona_id = ? WHERE user_id = ? AND cid = ?
@@ -313,7 +315,7 @@ class SQLiteDatabase:
             (persona_id, user_id, cid),
         )
 
-    def delete_conversation(self, user_id: str, cid: str):
+    def delete_conversation(self, user_id: str, cid: str) -> None:
         self._exec_sql(
             """
             DELETE FROM webchat_conversation WHERE user_id = ? AND cid = ?

astrbot/core/db/sqlite.py

@@ -305,7 +305,7 @@ class SQLiteDatabase(BaseDatabase):
                 await session.execute(query)
         return await self.get_conversation_by_id(cid)
 
-    async def delete_conversation(self, cid):
+    async def delete_conversation(self, cid) -> None:
         async with self.get_db() as session:
             session: AsyncSession
             async with session.begin():
@@ -461,7 +461,7 @@ class SQLiteDatabase(BaseDatabase):
         platform_id,
         user_id,
         offset_sec=86400,
-    ):
+    ) -> None:
         """Delete platform message history records newer than the specified offset."""
         async with self.get_db() as session:
             session: AsyncSession
@@ -645,7 +645,7 @@ class SQLiteDatabase(BaseDatabase):
                 await session.execute(query)
         return await self.get_persona_by_id(persona_id)
 
-    async def delete_persona(self, persona_id):
+    async def delete_persona(self, persona_id) -> None:
         """Delete a persona by its ID."""
         async with self.get_db() as session:
             session: AsyncSession
@@ -903,7 +903,7 @@ class SQLiteDatabase(BaseDatabase):
             result = await session.execute(query)
             return result.scalars().all()
 
-    async def remove_preference(self, scope, scope_id, key):
+    async def remove_preference(self, scope, scope_id, key) -> None:
         """Remove a preference by scope ID and key."""
         async with self.get_db() as session:
             session: AsyncSession
@@ -917,7 +917,7 @@ class SQLiteDatabase(BaseDatabase):
                 )
             await session.commit()
 
-    async def clear_preferences(self, scope, scope_id):
+    async def clear_preferences(self, scope, scope_id) -> None:
         """Clear all preferences for a specific scope ID."""
         async with self.get_db() as session:
             session: AsyncSession
@@ -1195,7 +1195,7 @@ class SQLiteDatabase(BaseDatabase):
 
         result = None
 
-        def runner():
+        def runner() -> None:
             nonlocal result
             result = asyncio.run(_inner())
 
@@ -1218,7 +1218,7 @@ class SQLiteDatabase(BaseDatabase):
 
         result = None
 
-        def runner():
+        def runner() -> None:
             nonlocal result
             result = asyncio.run(_inner())
 
@@ -1253,7 +1253,7 @@ class SQLiteDatabase(BaseDatabase):
 
         result = None
 
-        def runner():
+        def runner() -> None:
             nonlocal result
             result = asyncio.run(_inner())
 

astrbot/core/db/vec_db/base.py

@@ -9,7 +9,7 @@ class Result:
 
 
 class BaseVecDB:
-    async def initialize(self):
+    async def initialize(self) -> None:
         """初始化向量数据库"""
 
     @abc.abstractmethod

astrbot/core/db/vec_db/faiss_impl/document_storage.py

@@ -33,7 +33,7 @@ class Document(BaseDocModel, table=True):
 
 
 class DocumentStorage:
-    def __init__(self, db_path: str):
+    def __init__(self, db_path: str) -> None:
         self.db_path = db_path
         self.DATABASE_URL = f"sqlite+aiosqlite:///{db_path}"
         self.engine: AsyncEngine | None = None
@@ -43,7 +43,7 @@ class DocumentStorage:
             "sqlite_init.sql",
         )
 
-    async def initialize(self):
+    async def initialize(self) -> None:
         """Initialize the SQLite database and create the documents table if it doesn't exist."""
         await self.connect()
         async with self.engine.begin() as conn:  # type: ignore
@@ -80,7 +80,7 @@ class DocumentStorage:
 
             await conn.commit()
 
-    async def connect(self):
+    async def connect(self) -> None:
         """Connect to the SQLite database."""
         if self.engine is None:
             self.engine = create_async_engine(
@@ -211,7 +211,7 @@ class DocumentStorage:
             await session.flush()  # Flush to get all IDs
             return [doc.id for doc in documents]  # type: ignore
 
-    async def delete_document_by_doc_id(self, doc_id: str):
+    async def delete_document_by_doc_id(self, doc_id: str) -> None:
         """Delete a document by its doc_id.
 
         Args:
@@ -249,7 +249,7 @@ class DocumentStorage:
                 return self._document_to_dict(document)
             return None
 
-    async def update_document_by_doc_id(self, doc_id: str, new_text: str):
+    async def update_document_by_doc_id(self, doc_id: str, new_text: str) -> None:
         """Update a document by its doc_id.
 
         Args:
@@ -269,7 +269,7 @@ class DocumentStorage:
                 document.updated_at = datetime.now()
                 session.add(document)
 
-    async def delete_documents(self, metadata_filters: dict):
+    async def delete_documents(self, metadata_filters: dict) -> None:
         """Delete documents by their metadata filters.
 
         Args:
@@ -384,7 +384,7 @@ class DocumentStorage:
             "updated_at": row[5],
         }
 
-    async def close(self):
+    async def close(self) -> None:
         """Close the connection to the SQLite database."""
         if self.engine:
             await self.engine.dispose()

astrbot/core/db/vec_db/faiss_impl/embedding_storage.py

@@ -10,7 +10,7 @@ import numpy as np
 
 
 class EmbeddingStorage:
-    def __init__(self, dimension: int, path: str | None = None):
+    def __init__(self, dimension: int, path: str | None = None) -> None:
         self.dimension = dimension
         self.path = path
         self.index = None
@@ -20,7 +20,7 @@ class EmbeddingStorage:
             base_index = faiss.IndexFlatL2(dimension)
             self.index = faiss.IndexIDMap(base_index)
 
-    async def insert(self, vector: np.ndarray, id: int):
+    async def insert(self, vector: np.ndarray, id: int) -> None:
         """插入向量
 
         Args:
@@ -38,7 +38,7 @@ class EmbeddingStorage:
         self.index.add_with_ids(vector.reshape(1, -1), np.array([id]))
         await self.save_index()
 
-    async def insert_batch(self, vectors: np.ndarray, ids: list[int]):
+    async def insert_batch(self, vectors: np.ndarray, ids: list[int]) -> None:
         """批量插入向量
 
         Args:
@@ -71,7 +71,7 @@ class EmbeddingStorage:
         distances, indices = self.index.search(vector, k)
         return distances, indices
 
-    async def delete(self, ids: list[int]):
+    async def delete(self, ids: list[int]) -> None:
         """删除向量
 
         Args:
@@ -83,7 +83,7 @@ class EmbeddingStorage:
         self.index.remove_ids(id_array)
         await self.save_index()
 
-    async def save_index(self):
+    async def save_index(self) -> None:
         """保存索引
 
         Args:

astrbot/core/db/vec_db/faiss_impl/vec_db.py

@@ -20,7 +20,7 @@ class FaissVecDB(BaseVecDB):
         index_store_path: str,
         embedding_provider: EmbeddingProvider,
         rerank_provider: RerankProvider | None = None,
-    ):
+    ) -> None:
         self.doc_store_path = doc_store_path
         self.index_store_path = index_store_path
         self.embedding_provider = embedding_provider
@@ -32,7 +32,7 @@ class FaissVecDB(BaseVecDB):
         self.embedding_provider = embedding_provider
         self.rerank_provider = rerank_provider
 
-    async def initialize(self):
+    async def initialize(self) -> None:
         await self.document_storage.initialize()
 
     async def insert(
@@ -165,7 +165,7 @@ class FaissVecDB(BaseVecDB):
 
         return top_k_results
 
-    async def delete(self, doc_id: str):
+    async def delete(self, doc_id: str) -> None:
         """删除一条文档块（chunk）"""
         # 获得对应的 int id
         result = await self.document_storage.get_document_by_doc_id(doc_id)
@@ -177,7 +177,7 @@ class FaissVecDB(BaseVecDB):
         await self.document_storage.delete_document_by_doc_id(doc_id)
         await self.embedding_storage.delete([int_id])
 
-    async def close(self):
+    async def close(self) -> None:
         await self.document_storage.close()
 
     async def count_documents(self, metadata_filter: dict | None = None) -> int:
@@ -192,7 +192,7 @@ class FaissVecDB(BaseVecDB):
         )
         return count
 
-    async def delete_documents(self, metadata_filters: dict):
+    async def delete_documents(self, metadata_filters: dict) -> None:
         """根据元数据过滤器删除文档"""
         docs = await self.document_storage.get_documents(
             metadata_filters=metadata_filters,

astrbot/core/event_bus.py

@@ -28,13 +28,13 @@ class EventBus:
         event_queue: Queue,
         pipeline_scheduler_mapping: dict[str, PipelineScheduler],
         astrbot_config_mgr: AstrBotConfigManager,
-    ):
+    ) -> None:
         self.event_queue = event_queue  # 事件队列
         # abconf uuid -> scheduler
         self.pipeline_scheduler_mapping = pipeline_scheduler_mapping
         self.astrbot_config_mgr = astrbot_config_mgr
 
-    async def dispatch(self):
+    async def dispatch(self) -> None:
         while True:
             event: AstrMessageEvent = await self.event_queue.get()
             conf_info = self.astrbot_config_mgr.get_conf_info(event.unified_msg_origin)
@@ -47,7 +47,7 @@ class EventBus:
                 continue
             asyncio.create_task(scheduler.execute(event))
 
-    def _print_event(self, event: AstrMessageEvent, conf_name: str):
+    def _print_event(self, event: AstrMessageEvent, conf_name: str) -> None:
         """用于记录事件信息
 
         Args:

astrbot/core/file_token_service.py

@@ -9,12 +9,12 @@ from urllib.parse import unquote, urlparse
 class FileTokenService:
     """维护一个简单的基于令牌的文件下载服务，支持超时和懒清除。"""
 
-    def __init__(self, default_timeout: float = 300):
+    def __init__(self, default_timeout: float = 300) -> None:
         self.lock = asyncio.Lock()
         self.staged_files = {}  # token: (file_path, expire_time)
         self.default_timeout = default_timeout
 
-    async def _cleanup_expired_tokens(self):
+    async def _cleanup_expired_tokens(self) -> None:
         """清理过期的令牌"""
         now = time.time()
         expired_tokens = [

astrbot/core/initial_loader.py

@@ -17,13 +17,13 @@ from astrbot.dashboard.server import AstrBotDashboard
 class InitialLoader:
     """AstrBot 启动器，负责初始化和启动核心组件和仪表板服务器。"""
 
-    def __init__(self, db: BaseDatabase, log_broker: LogBroker):
+    def __init__(self, db: BaseDatabase, log_broker: LogBroker) -> None:
         self.db = db
         self.logger = logger
         self.log_broker = log_broker
         self.webui_dir: str | None = None
 
-    async def start(self):
+    async def start(self) -> None:
         core_lifecycle = AstrBotCoreLifecycle(self.log_broker, self.db)
 
         try:

astrbot/core/knowledge_base/chunking/fixed_size.py

@@ -12,7 +12,7 @@ class FixedSizeChunker(BaseChunker):
     按照固定的字符数分块,并支持块之间的重叠。
     """
 
-    def __init__(self, chunk_size: int = 512, chunk_overlap: int = 50):
+    def __init__(self, chunk_size: int = 512, chunk_overlap: int = 50) -> None:
         """初始化分块器
 
         Args:

astrbot/core/knowledge_base/chunking/recursive.py

@@ -11,7 +11,7 @@ class RecursiveCharacterChunker(BaseChunker):
         length_function: Callable[[str], int] = len,
         is_separator_regex: bool = False,
         separators: list[str] | None = None,
-    ):
+    ) -> None:
         """初始化递归字符文本分割器
 
         Args:

astrbot/core/knowledge_base/kb_db_sqlite.py

@@ -253,7 +253,7 @@ class KBSQLiteDatabase:
                 "knowledge_base": row[1],
             }
 
-    async def delete_document_by_id(self, doc_id: str, vec_db: FaissVecDB):
+    async def delete_document_by_id(self, doc_id: str, vec_db: FaissVecDB) -> None:
         """删除单个文档及其相关数据"""
         # 在知识库表中删除
         async with self.get_db() as session, session.begin():

astrbot/core/knowledge_base/kb_helper.py

@@ -31,7 +31,7 @@ from .prompts import TEXT_REPAIR_SYSTEM_PROMPT
 class RateLimiter:
     """一个简单的速率限制器"""
 
-    def __init__(self, max_rpm: int):
+    def __init__(self, max_rpm: int) -> None:
         self.max_per_minute = max_rpm
         self.interval = 60.0 / max_rpm if max_rpm > 0 else 0
         self.last_call_time = 0
@@ -116,7 +116,7 @@ class KBHelper:
         provider_manager: ProviderManager,
         kb_root_dir: str,
         chunker: BaseChunker,
-    ):
+    ) -> None:
         self.kb_db = kb_db
         self.kb = kb
         self.prov_mgr = provider_manager
@@ -130,7 +130,7 @@ class KBHelper:
         self.kb_medias_dir.mkdir(parents=True, exist_ok=True)
         self.kb_files_dir.mkdir(parents=True, exist_ok=True)
 
-    async def initialize(self):
+    async def initialize(self) -> None:
         await self._ensure_vec_db()
 
     async def get_ep(self) -> EmbeddingProvider:
@@ -174,7 +174,7 @@ class KBHelper:
         self.vec_db = vec_db
         return vec_db
 
-    async def delete_vec_db(self):
+    async def delete_vec_db(self) -> None:
         """删除知识库的向量数据库和所有相关文件"""
         import shutil
 
@@ -182,7 +182,7 @@ class KBHelper:
         if self.kb_dir.exists():
             shutil.rmtree(self.kb_dir)
 
-    async def terminate(self):
+    async def terminate(self) -> None:
         if self.vec_db:
             await self.vec_db.close()
 
@@ -293,7 +293,7 @@ class KBHelper:
                 await progress_callback("chunking", 100, 100)
 
             # 阶段3: 生成向量（带进度回调）
-            async def embedding_progress_callback(current, total):
+            async def embedding_progress_callback(current, total) -> None:
                 if progress_callback:
                     await progress_callback("embedding", current, total)
 
@@ -360,7 +360,7 @@ class KBHelper:
         doc = await self.kb_db.get_document_by_id(doc_id)
         return doc
 
-    async def delete_document(self, doc_id: str):
+    async def delete_document(self, doc_id: str) -> None:
         """删除单个文档及其相关数据"""
         await self.kb_db.delete_document_by_id(
             doc_id=doc_id,
@@ -372,7 +372,7 @@ class KBHelper:
         )
         await self.refresh_kb()
 
-    async def delete_chunk(self, chunk_id: str, doc_id: str):
+    async def delete_chunk(self, chunk_id: str, doc_id: str) -> None:
         """删除单个文本块及其相关数据"""
         vec_db: FaissVecDB = self.vec_db  # type: ignore
         await vec_db.delete(chunk_id)
@@ -383,7 +383,7 @@ class KBHelper:
         await self.refresh_kb()
         await self.refresh_document(doc_id)
 
-    async def refresh_kb(self):
+    async def refresh_kb(self) -> None:
         if self.kb:
             kb = await self.kb_db.get_kb_by_id(self.kb.kb_id)
             if kb:

astrbot/core/knowledge_base/kb_mgr.py

@@ -26,14 +26,14 @@ class KnowledgeBaseManager:
     def __init__(
         self,
         provider_manager: ProviderManager,
-    ):
+    ) -> None:
         Path(DB_PATH).parent.mkdir(parents=True, exist_ok=True)
         self.provider_manager = provider_manager
         self._session_deleted_callback_registered = False
 
         self.kb_insts: dict[str, KBHelper] = {}
 
-    async def initialize(self):
+    async def initialize(self) -> None:
         """初始化知识库模块"""
         try:
             logger.info("正在初始化知识库模块...")
@@ -58,13 +58,13 @@ class KnowledgeBaseManager:
             logger.error(f"知识库模块初始化失败: {e}")
             logger.error(traceback.format_exc())
 
-    async def _init_kb_database(self):
+    async def _init_kb_database(self) -> None:
         self.kb_db = KBSQLiteDatabase(DB_PATH.as_posix())
         await self.kb_db.initialize()
         await self.kb_db.migrate_to_v1()
         logger.info(f"KnowledgeBase database initialized: {DB_PATH}")
 
-    async def load_kbs(self):
+    async def load_kbs(self) -> None:
         """加载所有知识库实例"""
         kb_records = await self.kb_db.list_kbs()
         for record in kb_records:
@@ -275,7 +275,7 @@ class KnowledgeBaseManager:
 
         return "\n".join(lines)
 
-    async def terminate(self):
+    async def terminate(self) -> None:
         """终止所有知识库实例,关闭数据库连接"""
         for kb_id, kb_helper in self.kb_insts.items():
             try:

astrbot/core/knowledge_base/parsers/url_parser.py

@@ -6,7 +6,7 @@ import aiohttp
 class URLExtractor:
     """URL 内容提取器，封装了 Tavily API 调用和密钥管理"""
 
-    def __init__(self, tavily_keys: list[str]):
+    def __init__(self, tavily_keys: list[str]) -> None:
         """
         初始化 URL 提取器
 

astrbot/core/knowledge_base/retrieval/manager.py

@@ -44,7 +44,7 @@ class RetrievalManager:
         sparse_retriever: SparseRetriever,
         rank_fusion: RankFusion,
         kb_db: KBSQLiteDatabase,
-    ):
+    ) -> None:
         """初始化检索管理器
 
         Args:

astrbot/core/knowledge_base/retrieval/rank_fusion.py

@@ -31,7 +31,7 @@ class RankFusion:
     - 使用 Reciprocal Rank Fusion (RRF) 算法
     """
 
-    def __init__(self, kb_db: KBSQLiteDatabase, k: int = 60):
+    def __init__(self, kb_db: KBSQLiteDatabase, k: int = 60) -> None:
         """初始化结果融合器
 
         Args:

astrbot/core/knowledge_base/retrieval/sparse_retriever.py

@@ -34,7 +34,7 @@ class SparseRetriever:
     - 使用 BM25 算法计算相关度
     """
 
-    def __init__(self, kb_db: KBSQLiteDatabase):
+    def __init__(self, kb_db: KBSQLiteDatabase) -> None:
         """初始化稀疏检索器
 
         Args:

astrbot/core/log.py

@@ -1,24 +1,4 @@
-"""日志系统, 用于支持核心组件和插件的日志记录, 提供了日志订阅功能
-
-const:
-    CACHED_SIZE: 日志缓存大小, 用于限制缓存的日志数量
-    log_color_config: 日志颜色配置, 定义了不同日志级别的颜色
-
-class:
-    LogBroker: 日志代理类, 用于缓存和分发日志消息
-    LogQueueHandler: 日志处理器, 用于将日志消息发送到 LogBroker
-    LogManager: 日志管理器, 用于创建和配置日志记录器
-
-function:
-    is_plugin_path: 检查文件路径是否来自插件目录
-    get_short_level_name: 将日志级别名称转换为四个字母的缩写
-
-工作流程:
-1. 通过 LogManager.GetLogger() 获取日志器, 配置了控制台输出和多个格式化过滤器
-2. 通过 set_queue_handler() 设置日志处理器, 将日志消息发送到 LogBroker
-3. logBroker 维护一个订阅者列表, 负责将日志分发给所有订阅者
-4. 订阅者可以使用 register() 方法注册到 LogBroker, 订阅日志流
-"""
+"""日志系统，统一将标准 logging 输出转发到 loguru。"""
 
 import asyncio
 import logging
@@ -27,54 +7,59 @@ import sys
 import time
 from asyncio import Queue
 from collections import deque
-from logging.handlers import RotatingFileHandler
+from typing import TYPE_CHECKING
 
-import colorlog
+from loguru import logger as _raw_loguru_logger
 
 from astrbot.core.config.default import VERSION
 from astrbot.core.utils.astrbot_path import get_astrbot_data_path
 
-# 日志缓存大小
 CACHED_SIZE = 500
-# 日志颜色配置
-log_color_config = {
-    "DEBUG": "green",
-    "INFO": "bold_cyan",
-    "WARNING": "bold_yellow",
-    "ERROR": "red",
-    "CRITICAL": "bold_red",
-    "RESET": "reset",
-    "asctime": "green",
-}
+
+if TYPE_CHECKING:
+    from loguru import Record
 
 
-def is_plugin_path(pathname):
-    """检查文件路径是否来自插件目录
+class _RecordEnricherFilter(logging.Filter):
+    """为 logging.LogRecord 注入 AstrBot 日志字段。"""
 
-    Args:
-        pathname (str): 文件路径
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.plugin_tag = "[Plug]" if _is_plugin_path(record.pathname) else "[Core]"
+        record.short_levelname = _get_short_level_name(record.levelname)
+        record.astrbot_version_tag = (
+            f" [v{VERSION}]" if record.levelno >= logging.WARNING else ""
+        )
+        record.source_file = _build_source_file(record.pathname)
+        record.source_line = record.lineno
+        record.is_trace = record.name == "astrbot.trace"
+        return True
 
-    Returns:
-        bool: 如果路径来自插件目录，则返回 True，否则返回 False
 
-    """
+class _QueueAnsiColorFilter(logging.Filter):
+    """Attach ANSI color prefix for WebUI console rendering."""
+
+    _LEVEL_COLOR = {
+        "DEBUG": "\u001b[1;34m",
+        "INFO": "\u001b[1;36m",
+        "WARNING": "\u001b[1;33m",
+        "ERROR": "\u001b[31m",
+        "CRITICAL": "\u001b[1;31m",
+    }
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.ansi_prefix = self._LEVEL_COLOR.get(record.levelname, "\u001b[0m")
+        record.ansi_reset = "\u001b[0m"
+        return True
+
+
+def _is_plugin_path(pathname: str | None) -> bool:
     if not pathname:
         return False
-
     norm_path = os.path.normpath(pathname)
     return ("data/plugins" in norm_path) or ("astrbot/builtin_stars/" in norm_path)
 
 
-def get_short_level_name(level_name):
-    """将日志级别名称转换为四个字母的缩写
-
-    Args:
-        level_name (str): 日志级别名称, 如 "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
-
-    Returns:
-        str: 四个字母的日志级别缩写
-
-    """
+def _get_short_level_name(level_name: str) -> str:
     level_map = {
         "DEBUG": "DBUG",
         "INFO": "INFO",
@@ -85,44 +70,75 @@ def get_short_level_name(level_name):
     return level_map.get(level_name, level_name[:4].upper())
 
 
+def _build_source_file(pathname: str | None) -> str:
+    if not pathname:
+        return "unknown"
+    dirname = os.path.dirname(pathname)
+    return (
+        os.path.basename(dirname) + "." + os.path.basename(pathname).replace(".py", "")
+    )
+
+
+def _patch_record(record: "Record") -> None:
+    extra = record["extra"]
+    extra.setdefault("plugin_tag", "[Core]")
+    extra.setdefault("short_levelname", _get_short_level_name(record["level"].name))
+    level_no = record["level"].no
+    extra.setdefault("astrbot_version_tag", f" [v{VERSION}]" if level_no >= 30 else "")
+    extra.setdefault("source_file", _build_source_file(record["file"].path))
+    extra.setdefault("source_line", record["line"])
+    extra.setdefault("is_trace", False)
+
+
+_loguru = _raw_loguru_logger.patch(_patch_record)
+
+
+class _LoguruInterceptHandler(logging.Handler):
+    """将 logging 记录转发到 loguru。"""
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            level: str | int = _loguru.level(record.levelname).name
+        except ValueError:
+            level = record.levelno
+
+        payload = {
+            "plugin_tag": getattr(record, "plugin_tag", "[Core]"),
+            "short_levelname": getattr(
+                record,
+                "short_levelname",
+                _get_short_level_name(record.levelname),
+            ),
+            "astrbot_version_tag": getattr(record, "astrbot_version_tag", ""),
+            "source_file": getattr(
+                record, "source_file", _build_source_file(record.pathname)
+            ),
+            "source_line": getattr(record, "source_line", record.lineno),
+            "is_trace": getattr(record, "is_trace", record.name == "astrbot.trace"),
+        }
+
+        _loguru.bind(**payload).opt(exception=record.exc_info).log(
+            level,
+            record.getMessage(),
+        )
+
+
 class LogBroker:
-    """日志代理类, 用于缓存和分发日志消息
+    """日志代理类，用于缓存和分发日志消息。"""
 
-    发布-订阅模式
-    """
-
-    def __init__(self):
-        self.log_cache = deque(maxlen=CACHED_SIZE)  # 环形缓冲区, 保存最近的日志
-        self.subscribers: list[Queue] = []  # 订阅者列表
+    def __init__(self) -> None:
+        self.log_cache = deque(maxlen=CACHED_SIZE)
+        self.subscribers: list[Queue] = []
 
     def register(self) -> Queue:
-        """注册新的订阅者, 并给每个订阅者返回一个带有日志缓存的队列
-
-        Returns:
-            Queue: 订阅者的队列, 可用于接收日志消息
-
-        """
         q = Queue(maxsize=CACHED_SIZE + 10)
         self.subscribers.append(q)
         return q
 
-    def unregister(self, q: Queue):
-        """取消订阅
-
-        Args:
-            q (Queue): 需要取消订阅的队列
-
-        """
+    def unregister(self, q: Queue) -> None:
         self.subscribers.remove(q)
 
-    def publish(self, log_entry: dict):
-        """发布新日志到所有订阅者, 使用非阻塞方式投递, 避免一个订阅者阻塞整个系统
-
-        Args:
-            log_entry (dict): 日志消息, 包含日志级别和日志内容.
-                example: {"level": "INFO", "data": "This is a log message.", "time": "2023-10-01 12:00:00"}
-
-        """
+    def publish(self, log_entry: dict) -> None:
         self.log_cache.append(log_entry)
         for q in self.subscribers:
             try:
@@ -132,23 +148,13 @@ class LogBroker:
 
 
 class LogQueueHandler(logging.Handler):
-    """日志处理器, 用于将日志消息发送到 LogBroker
+    """日志处理器，用于将日志消息发送到 LogBroker。"""
 
-    继承自 logging.Handler
-    """
-
-    def __init__(self, log_broker: LogBroker):
+    def __init__(self, log_broker: LogBroker) -> None:
         super().__init__()
         self.log_broker = log_broker
 
-    def emit(self, record):
-        """日志处理的入口方法, 接受一个日志记录, 转换为字符串后由 LogBroker 发布
-        这个方法会在每次日志记录时被调用
-
-        Args:
-            record (logging.LogRecord): 日志记录对象, 包含日志信息
-
-        """
+    def emit(self, record: logging.LogRecord) -> None:
         log_entry = self.format(record)
         self.log_broker.publish(
             {
@@ -160,117 +166,16 @@ class LogQueueHandler(logging.Handler):
 
 
 class LogManager:
-    """日志管理器, 用于创建和配置日志记录器
+    _LOGGER_HANDLER_FLAG = "_astrbot_loguru_handler"
+    _ENRICH_FILTER_FLAG = "_astrbot_enrich_filter"
 
-    提供了获取默认日志记录器logger和设置队列处理器的方法
-    """
-
-    _FILE_HANDLER_FLAG = "_astrbot_file_handler"
-    _TRACE_FILE_HANDLER_FLAG = "_astrbot_trace_file_handler"
-
-    @classmethod
-    def GetLogger(cls, log_name: str = "default"):
-        """获取指定名称的日志记录器logger
-
-        Args:
-            log_name (str): 日志记录器的名称, 默认为 "default"
-
-        Returns:
-            logging.Logger: 返回配置好的日志记录器
-
-        """
-        logger = logging.getLogger(log_name)
-        # 检查该logger或父级logger是否已经有处理器, 如果已经有处理器, 直接返回该logger, 避免重复配置
-        if logger.hasHandlers():
-            return logger
-        # 如果logger没有处理器
-        console_handler = logging.StreamHandler(
-            sys.stdout,
-        )  # 创建一个StreamHandler用于控制台输出
-        console_handler.setLevel(
-            logging.DEBUG,
-        )  # 将日志级别设置为DEBUG(最低级别, 显示所有日志), *如果插件没有设置级别, 默认为DEBUG
-
-        # 创建彩色日志格式化器, 输出日志格式为: [时间] [插件标签] [日志级别] [文件名:行号]: 日志消息
-        console_formatter = colorlog.ColoredFormatter(
-            fmt="%(log_color)s [%(asctime)s] %(plugin_tag)s [%(short_levelname)-4s]%(astrbot_version_tag)s [%(filename)s:%(lineno)d]: %(message)s %(reset)s",
-            datefmt="%H:%M:%S",
-            log_colors=log_color_config,
-        )
-
-        class PluginFilter(logging.Filter):
-            """插件过滤器类, 用于标记日志来源是插件还是核心组件"""
-
-            def filter(self, record):
-                record.plugin_tag = (
-                    "[Plug]" if is_plugin_path(record.pathname) else "[Core]"
-                )
-                return True
-
-        class FileNameFilter(logging.Filter):
-            """文件名过滤器类, 用于修改日志记录的文件名格式
-            例如: 将文件路径 /path/to/file.py 转换为 file.<file> 格式
-            """
-
-            # 获取这个文件和父文件夹的名字：<folder>.<file> 并且去除 .py
-            def filter(self, record):
-                dirname = os.path.dirname(record.pathname)
-                record.filename = (
-                    os.path.basename(dirname)
-                    + "."
-                    + os.path.basename(record.pathname).replace(".py", "")
-                )
-                return True
-
-        class LevelNameFilter(logging.Filter):
-            """短日志级别名称过滤器类, 用于将日志级别名称转换为四个字母的缩写"""
-
-            # 添加短日志级别名称
-            def filter(self, record):
-                record.short_levelname = get_short_level_name(record.levelname)
-                return True
-
-        class AstrBotVersionTagFilter(logging.Filter):
-            """在 WARNING 及以上级别日志后追加当前 AstrBot 版本号。"""
-
-            def filter(self, record):
-                if record.levelno >= logging.WARNING:
-                    record.astrbot_version_tag = f" [v{VERSION}]"
-                else:
-                    record.astrbot_version_tag = ""
-                return True
-
-        console_handler.setFormatter(console_formatter)  # 设置处理器的格式化器
-        logger.addFilter(PluginFilter())  # 添加插件过滤器
-        logger.addFilter(FileNameFilter())  # 添加文件名过滤器
-        logger.addFilter(LevelNameFilter())  # 添加级别名称过滤器
-        logger.addFilter(AstrBotVersionTagFilter())  # 追加版本号（WARNING 及以上）
-        logger.setLevel(logging.DEBUG)  # 设置日志级别为DEBUG
-        logger.addHandler(console_handler)  # 添加处理器到logger
-
-        return logger
-
-    @classmethod
-    def set_queue_handler(cls, logger: logging.Logger, log_broker: LogBroker):
-        """设置队列处理器, 用于将日志消息发送到 LogBroker
-
-        Args:
-            logger (logging.Logger): 日志记录器
-            log_broker (LogBroker): 日志代理类, 用于缓存和分发日志消息
-
-        """
-        handler = LogQueueHandler(log_broker)
-        handler.setLevel(logging.DEBUG)
-        if logger.handlers:
-            handler.setFormatter(logger.handlers[0].formatter)
-        else:
-            # 为队列处理器设置相同格式的formatter
-            handler.setFormatter(
-                logging.Formatter(
-                    "[%(asctime)s] [%(short_levelname)s] %(plugin_tag)s[%(filename)s:%(lineno)d]: %(message)s",
-                ),
-            )
-        logger.addHandler(handler)
+    _configured = False
+    _console_sink_id: int | None = None
+    _file_sink_id: int | None = None
+    _trace_sink_id: int | None = None
+    _NOISY_LOGGER_LEVELS: dict[str, int] = {
+        "aiosqlite": logging.WARNING,
+    }
 
     @classmethod
     def _default_log_path(cls) -> str:
@@ -285,79 +190,147 @@ class LogManager:
         return os.path.join(get_astrbot_data_path(), configured_path)
 
     @classmethod
-    def _get_file_handlers(cls, logger: logging.Logger) -> list[logging.Handler]:
-        return [
-            handler
-            for handler in logger.handlers
-            if getattr(handler, cls._FILE_HANDLER_FLAG, False)
-        ]
+    def _setup_loguru(cls) -> None:
+        if cls._configured:
+            return
 
-    @classmethod
-    def _get_trace_file_handlers(cls, logger: logging.Logger) -> list[logging.Handler]:
-        return [
-            handler
-            for handler in logger.handlers
-            if getattr(handler, cls._TRACE_FILE_HANDLER_FLAG, False)
-        ]
-
-    @classmethod
-    def _remove_file_handlers(cls, logger: logging.Logger):
-        for handler in cls._get_file_handlers(logger):
-            logger.removeHandler(handler)
-            try:
-                handler.close()
-            except Exception:
-                pass
-
-    @classmethod
-    def _remove_trace_file_handlers(cls, logger: logging.Logger):
-        for handler in cls._get_trace_file_handlers(logger):
-            logger.removeHandler(handler)
-            try:
-                handler.close()
-            except Exception:
-                pass
-
-    @classmethod
-    def _add_file_handler(
-        cls,
-        logger: logging.Logger,
-        file_path: str,
-        max_mb: int | None = None,
-        backup_count: int = 3,
-        trace: bool = False,
-    ):
-        os.makedirs(os.path.dirname(file_path) or ".", exist_ok=True)
-        max_bytes = 0
-        if max_mb and max_mb > 0:
-            max_bytes = max_mb * 1024 * 1024
-        if max_bytes > 0:
-            file_handler = RotatingFileHandler(
-                file_path,
-                maxBytes=max_bytes,
-                backupCount=backup_count,
-                encoding="utf-8",
-            )
-        else:
-            file_handler = logging.FileHandler(file_path, encoding="utf-8")
-        file_handler.setLevel(logger.level)
-        if trace:
-            formatter = logging.Formatter(
-                "[%(asctime)s] %(message)s",
-                datefmt="%Y-%m-%d %H:%M:%S",
-            )
-        else:
-            formatter = logging.Formatter(
-                "[%(asctime)s] %(plugin_tag)s [%(short_levelname)s]%(astrbot_version_tag)s [%(filename)s:%(lineno)d]: %(message)s",
-                datefmt="%Y-%m-%d %H:%M:%S",
-            )
-        file_handler.setFormatter(formatter)
-        setattr(
-            file_handler,
-            cls._TRACE_FILE_HANDLER_FLAG if trace else cls._FILE_HANDLER_FLAG,
-            True,
+        _loguru.remove()
+        cls._console_sink_id = _loguru.add(
+            sys.stdout,
+            level="DEBUG",
+            colorize=True,
+            filter=lambda record: not record["extra"].get("is_trace", False),
+            format=(
+                "<green>[{time:HH:mm:ss.SSS}]</green> {extra[plugin_tag]} "
+                "<level>[{extra[short_levelname]}]</level>{extra[astrbot_version_tag]} "
+                "[{extra[source_file]}:{extra[source_line]}]: <level>{message}</level>"
+            ),
+        )
+        cls._configured = True
+
+    @classmethod
+    def _setup_root_bridge(cls) -> None:
+        root_logger = logging.getLogger()
+
+        has_handler = any(
+            getattr(handler, cls._LOGGER_HANDLER_FLAG, False)
+            for handler in root_logger.handlers
+        )
+        if not has_handler:
+            handler = _LoguruInterceptHandler()
+            setattr(handler, cls._LOGGER_HANDLER_FLAG, True)
+            root_logger.addHandler(handler)
+        root_logger.setLevel(logging.DEBUG)
+        for name, level in cls._NOISY_LOGGER_LEVELS.items():
+            logging.getLogger(name).setLevel(level)
+
+    @classmethod
+    def _ensure_logger_enricher_filter(cls, logger: logging.Logger) -> None:
+        has_filter = any(
+            getattr(existing_filter, cls._ENRICH_FILTER_FLAG, False)
+            for existing_filter in logger.filters
+        )
+        if not has_filter:
+            enrich_filter = _RecordEnricherFilter()
+            setattr(enrich_filter, cls._ENRICH_FILTER_FLAG, True)
+            logger.addFilter(enrich_filter)
+
+    @classmethod
+    def _ensure_logger_intercept_handler(cls, logger: logging.Logger) -> None:
+        has_handler = any(
+            getattr(handler, cls._LOGGER_HANDLER_FLAG, False)
+            for handler in logger.handlers
+        )
+        if not has_handler:
+            handler = _LoguruInterceptHandler()
+            setattr(handler, cls._LOGGER_HANDLER_FLAG, True)
+            logger.addHandler(handler)
+
+    @classmethod
+    def GetLogger(cls, log_name: str = "default") -> logging.Logger:
+        cls._setup_loguru()
+        cls._setup_root_bridge()
+
+        logger = logging.getLogger(log_name)
+        cls._ensure_logger_enricher_filter(logger)
+        cls._ensure_logger_intercept_handler(logger)
+        logger.setLevel(logging.DEBUG)
+        logger.propagate = False
+        return logger
+
+    @classmethod
+    def set_queue_handler(cls, logger: logging.Logger, log_broker: LogBroker) -> None:
+        cls._ensure_logger_enricher_filter(logger)
+
+        for handler in logger.handlers:
+            if isinstance(handler, LogQueueHandler):
+                return
+
+        handler = LogQueueHandler(log_broker)
+        handler.setLevel(logging.DEBUG)
+        handler.addFilter(_QueueAnsiColorFilter())
+        handler.setFormatter(
+            logging.Formatter(
+                "%(ansi_prefix)s[%(asctime)s.%(msecs)03d] %(plugin_tag)s [%(short_levelname)s]%(astrbot_version_tag)s "
+                "[%(source_file)s:%(source_line)d]: %(message)s%(ansi_reset)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            ),
+        )
+        logger.addHandler(handler)
+
+    @classmethod
+    def _remove_sink(cls, sink_id: int | None) -> None:
+        if sink_id is None:
+            return
+        try:
+            _loguru.remove(sink_id)
+        except ValueError:
+            pass
+
+    @classmethod
+    def _add_file_sink(
+        cls,
+        *,
+        file_path: str,
+        level: int,
+        max_mb: int | None,
+        backup_count: int,
+        trace: bool,
+    ) -> int:
+        os.makedirs(os.path.dirname(file_path) or ".", exist_ok=True)
+        rotation = f"{max_mb} MB" if max_mb and max_mb > 0 else None
+        retention = (
+            backup_count if rotation and backup_count and backup_count > 0 else None
+        )
+        if trace:
+            return _loguru.add(
+                file_path,
+                level="INFO",
+                format="[{time:YYYY-MM-DD HH:mm:ss.SSS}] {message}",
+                encoding="utf-8",
+                rotation=rotation,
+                retention=retention,
+                enqueue=True,
+                filter=lambda record: record["extra"].get("is_trace", False),
+            )
+
+        logging_level_name = logging.getLevelName(level)
+        if isinstance(logging_level_name, int):
+            logging_level_name = "INFO"
+        return _loguru.add(
+            file_path,
+            level=logging_level_name,
+            format=(
+                "[{time:YYYY-MM-DD HH:mm:ss.SSS}] {extra[plugin_tag]} "
+                "[{extra[short_levelname]}]{extra[astrbot_version_tag]} "
+                "[{extra[source_file]}:{extra[source_line]}]: {message}"
+            ),
+            encoding="utf-8",
+            rotation=rotation,
+            retention=retention,
+            enqueue=True,
+            filter=lambda record: not record["extra"].get("is_trace", False),
         )
-        logger.addHandler(file_handler)
 
     @classmethod
     def configure_logger(
@@ -365,14 +338,7 @@ class LogManager:
         logger: logging.Logger,
         config: dict | None,
         override_level: str | None = None,
-    ):
-        """根据配置设置日志级别和文件日志。
-
-        Args:
-            logger: 需要配置的 logger
-            config: 配置字典
-            override_level: 若提供，将覆盖配置中的日志级别
-        """
+    ) -> None:
         if not config:
             return
 
@@ -383,7 +349,6 @@ class LogManager:
             except Exception:
                 logger.setLevel(logging.INFO)
 
-        # 兼容旧版嵌套配置
         if "log_file" in config:
             file_conf = config.get("log_file") or {}
             enable_file = bool(file_conf.get("enable", False))
@@ -394,27 +359,25 @@ class LogManager:
             file_path = config.get("log_file_path")
             max_mb = config.get("log_file_max_mb")
 
-        file_path = cls._resolve_log_path(file_path)
+        cls._remove_sink(cls._file_sink_id)
+        cls._file_sink_id = None
 
-        existing = cls._get_file_handlers(logger)
         if not enable_file:
-            cls._remove_file_handlers(logger)
             return
 
-        # 如果已有文件处理器且路径一致，则仅同步级别
-        if existing:
-            handler = existing[0]
-            base = getattr(handler, "baseFilename", "")
-            if base and os.path.abspath(base) == os.path.abspath(file_path):
-                handler.setLevel(logger.level)
-                return
-            cls._remove_file_handlers(logger)
-
-        cls._add_file_handler(logger, file_path, max_mb=max_mb)
+        try:
+            cls._file_sink_id = cls._add_file_sink(
+                file_path=cls._resolve_log_path(file_path),
+                level=logger.level,
+                max_mb=max_mb,
+                backup_count=3,
+                trace=False,
+            )
+        except Exception as e:
+            logger.error(f"Failed to add file sink: {e}")
 
     @classmethod
-    def configure_trace_logger(cls, config: dict | None):
-        """为 trace 事件配置独立的文件日志，不向控制台输出。"""
+    def configure_trace_logger(cls, config: dict | None) -> None:
         if not config:
             return
 
@@ -429,28 +392,22 @@ class LogManager:
             path = path or legacy.get("trace_path")
             max_mb = max_mb or legacy.get("trace_max_mb")
 
-        if not enable:
-            trace_logger = logging.getLogger("astrbot.trace")
-            cls._remove_trace_file_handlers(trace_logger)
-            return
-
-        file_path = cls._resolve_log_path(path or "logs/astrbot.trace.log")
         trace_logger = logging.getLogger("astrbot.trace")
+        cls._ensure_logger_enricher_filter(trace_logger)
+        cls._ensure_logger_intercept_handler(trace_logger)
         trace_logger.setLevel(logging.INFO)
         trace_logger.propagate = False
 
-        existing = cls._get_trace_file_handlers(trace_logger)
-        if existing:
-            handler = existing[0]
-            base = getattr(handler, "baseFilename", "")
-            if base and os.path.abspath(base) == os.path.abspath(file_path):
-                handler.setLevel(trace_logger.level)
-                return
-            cls._remove_trace_file_handlers(trace_logger)
+        cls._remove_sink(cls._trace_sink_id)
+        cls._trace_sink_id = None
 
-        cls._add_file_handler(
-            trace_logger,
-            file_path,
+        if not enable:
+            return
+
+        cls._trace_sink_id = cls._add_file_sink(
+            file_path=cls._resolve_log_path(path or "logs/astrbot.trace.log"),
+            level=logging.INFO,
             max_mb=max_mb,
+            backup_count=3,
             trace=True,
         )

astrbot/core/message/components.py

@@ -25,13 +25,17 @@ import asyncio
 import base64
 import json
 import os
+import sys
 import uuid
 from enum import Enum
 
-from pydantic.v1 import BaseModel
+if sys.version_info >= (3, 14):
+    from pydantic import BaseModel
+else:
+    from pydantic.v1 import BaseModel
 
 from astrbot.core import astrbot_config, file_token_service, logger
-from astrbot.core.utils.astrbot_path import get_astrbot_data_path
+from astrbot.core.utils.astrbot_path import get_astrbot_temp_path
 from astrbot.core.utils.io import download_file, download_image_by_url, file_to_base64
 
 
@@ -66,7 +70,7 @@ class ComponentType(str, Enum):
 class BaseMessageComponent(BaseModel):
     type: ComponentType
 
-    def __init__(self, **kwargs):
+    def __init__(self, **kwargs) -> None:
         super().__init__(**kwargs)
 
     def toDict(self):
@@ -85,11 +89,11 @@ class BaseMessageComponent(BaseModel):
 
 
 class Plain(BaseMessageComponent):
-    type = ComponentType.Plain
+    type: ComponentType = ComponentType.Plain
     text: str
     convert: bool | None = True
 
-    def __init__(self, text: str, convert: bool = True, **_):
+    def __init__(self, text: str, convert: bool = True, **_) -> None:
         super().__init__(text=text, convert=convert, **_)
 
     def toDict(self):
@@ -100,15 +104,15 @@ class Plain(BaseMessageComponent):
 
 
 class Face(BaseMessageComponent):
-    type = ComponentType.Face
+    type: ComponentType = ComponentType.Face
     id: int
 
-    def __init__(self, **_):
+    def __init__(self, **_) -> None:
         super().__init__(**_)
 
 
 class Record(BaseMessageComponent):
-    type = ComponentType.Record
+    type: ComponentType = ComponentType.Record
     file: str | None = ""
     magic: bool | None = False
     url: str | None = ""
@@ -118,7 +122,7 @@ class Record(BaseMessageComponent):
     # 额外
     path: str | None
 
-    def __init__(self, file: str | None, **_):
+    def __init__(self, file: str | None, **_) -> None:
         for k in _:
             if k == "url":
                 pass
@@ -156,8 +160,9 @@ class Record(BaseMessageComponent):
         if self.file.startswith("base64://"):
             bs64_data = self.file.removeprefix("base64://")
             image_bytes = base64.b64decode(bs64_data)
-            temp_dir = os.path.join(get_astrbot_data_path(), "temp")
-            file_path = os.path.join(temp_dir, f"{uuid.uuid4()}.jpg")
+            file_path = os.path.join(
+                get_astrbot_temp_path(), f"recordseg_{uuid.uuid4()}.jpg"
+            )
             with open(file_path, "wb") as f:
                 f.write(image_bytes)
             return os.path.abspath(file_path)
@@ -214,14 +219,14 @@ class Record(BaseMessageComponent):
 
 
 class Video(BaseMessageComponent):
-    type = ComponentType.Video
+    type: ComponentType = ComponentType.Video
     file: str
     cover: str | None = ""
     c: int | None = 2
     # 额外
     path: str | None = ""
 
-    def __init__(self, file: str, **_):
+    def __init__(self, file: str, **_) -> None:
         super().__init__(file=file, **_)
 
     @staticmethod
@@ -245,8 +250,9 @@ class Video(BaseMessageComponent):
         if url and url.startswith("file:///"):
             return url[8:]
         if url and url.startswith("http"):
-            download_dir = os.path.join(get_astrbot_data_path(), "temp")
-            video_file_path = os.path.join(download_dir, f"{uuid.uuid4().hex}")
+            video_file_path = os.path.join(
+                get_astrbot_temp_path(), f"videoseg_{uuid.uuid4().hex}"
+            )
             await download_file(url, video_file_path)
             if os.path.exists(video_file_path):
                 return os.path.abspath(video_file_path)
@@ -255,7 +261,7 @@ class Video(BaseMessageComponent):
             return os.path.abspath(url)
         raise Exception(f"not a valid file: {url}")
 
-    async def register_to_file_service(self):
+    async def register_to_file_service(self) -> str:
         """将视频注册到文件服务。
 
         Returns:
@@ -299,11 +305,11 @@ class Video(BaseMessageComponent):
 
 
 class At(BaseMessageComponent):
-    type = ComponentType.At
+    type: ComponentType = ComponentType.At
     qq: int | str  # 此处str为all时代表所有人
     name: str | None = ""
 
-    def __init__(self, **_):
+    def __init__(self, **_) -> None:
         super().__init__(**_)
 
     def toDict(self):
@@ -316,64 +322,64 @@ class At(BaseMessageComponent):
 class AtAll(At):
     qq: str = "all"
 
-    def __init__(self, **_):
+    def __init__(self, **_) -> None:
         super().__init__(**_)
 
 
 class RPS(BaseMessageComponent):  # TODO
-    type = ComponentType.RPS
+    type: ComponentType = ComponentType.RPS
 
-    def __init__(self, **_):
+    def __init__(self, **_) -> None:
         super().__init__(**_)
 
 
 class Dice(BaseMessageComponent):  # TODO
-    type = ComponentType.Dice
+    type: ComponentType = ComponentType.Dice
 
-    def __init__(self, **_):
+    def __init__(self, **_) -> None:
         super().__init__(**_)
 
 
 class Shake(BaseMessageComponent):  # TODO
-    type = ComponentType.Shake
+    type: ComponentType = ComponentType.Shake
 
-    def __init__(self, **_):
+    def __init__(self, **_) -> None:
         super().__init__(**_)
 
 
 class Share(BaseMessageComponent):
-    type = ComponentType.Share
+    type: ComponentType = ComponentType.Share
     url: str
     title: str
     content: str | None = ""
     image: str | None = ""
 
-    def __init__(self, **_):
+    def __init__(self, **_) -> None:
         super().__init__(**_)
 
 
 class Contact(BaseMessageComponent):  # TODO
-    type = ComponentType.Contact
+    type: ComponentType = ComponentType.Contact
     _type: str  # type 字段冲突
     id: int | None = 0
 
-    def __init__(self, **_):
+    def __init__(self, **_) -> None:
         super().__init__(**_)
 
 
 class Location(BaseMessageComponent):  # TODO
-    type = ComponentType.Location
+    type: ComponentType = ComponentType.Location
     lat: float
     lon: float
     title: str | None = ""
     content: str | None = ""
 
-    def __init__(self, **_):
+    def __init__(self, **_) -> None:
         super().__init__(**_)
 
 
 class Music(BaseMessageComponent):
-    type = ComponentType.Music
+    type: ComponentType = ComponentType.Music
     _type: str
     id: int | None = 0
     url: str | None = ""
@@ -382,7 +388,7 @@ class Music(BaseMessageComponent):
     content: str | None = ""
     image: str | None = ""
 
-    def __init__(self, **_):
+    def __init__(self, **_) -> None:
         # for k in _.keys():
         #     if k == "_type" and _[k] not in ["qq", "163", "xm", "custom"]:
         #         logger.warn(f"Protocol: {k}={_[k]} doesn't match values")
@@ -390,7 +396,7 @@ class Music(BaseMessageComponent):
 
 
 class Image(BaseMessageComponent):
-    type = ComponentType.Image
+    type: ComponentType = ComponentType.Image
     file: str | None = ""
     _type: str | None = ""
     subType: int | None = 0
@@ -402,7 +408,7 @@ class Image(BaseMessageComponent):
     path: str | None = ""
     file_unique: str | None = ""  # 某些平台可能有图片缓存的唯一标识
 
-    def __init__(self, file: str | None, **_):
+    def __init__(self, file: str | None, **_) -> None:
         super().__init__(file=file, **_)
 
     @staticmethod
@@ -445,8 +451,9 @@ class Image(BaseMessageComponent):
         if url.startswith("base64://"):
             bs64_data = url.removeprefix("base64://")
             image_bytes = base64.b64decode(bs64_data)
-            temp_dir = os.path.join(get_astrbot_data_path(), "temp")
-            image_file_path = os.path.join(temp_dir, f"{uuid.uuid4()}.jpg")
+            image_file_path = os.path.join(
+                get_astrbot_temp_path(), f"imgseg_{uuid.uuid4()}.jpg"
+            )
             with open(image_file_path, "wb") as f:
                 f.write(image_bytes)
             return os.path.abspath(image_file_path)
@@ -504,7 +511,7 @@ class Image(BaseMessageComponent):
 
 
 class Reply(BaseMessageComponent):
-    type = ComponentType.Reply
+    type: ComponentType = ComponentType.Reply
     id: str | int
     """所引用的消息 ID"""
     chain: list["BaseMessageComponent"] | None = []
@@ -525,7 +532,7 @@ class Reply(BaseMessageComponent):
     seq: int | None = 0
     """deprecated"""
 
-    def __init__(self, **_):
+    def __init__(self, **_) -> None:
         super().__init__(**_)
 
 
@@ -534,23 +541,23 @@ class Poke(BaseMessageComponent):
     id: int | None = 0
     qq: int | None = 0
 
-    def __init__(self, type: str, **_):
+    def __init__(self, type: str, **_) -> None:
         type = f"Poke:{type}"
         super().__init__(type=type, **_)
 
 
 class Forward(BaseMessageComponent):
-    type = ComponentType.Forward
+    type: ComponentType = ComponentType.Forward
     id: str
 
-    def __init__(self, **_):
+    def __init__(self, **_) -> None:
         super().__init__(**_)
 
 
 class Node(BaseMessageComponent):
     """群合并转发消息"""
 
-    type = ComponentType.Node
+    type: ComponentType = ComponentType.Node
     id: int | None = 0  # 忽略
     name: str | None = ""  # qq昵称
     uin: str | None = "0"  # qq号
@@ -558,7 +565,7 @@ class Node(BaseMessageComponent):
     seq: str | list | None = ""  # 忽略
     time: int | None = 0  # 忽略
 
-    def __init__(self, content: list[BaseMessageComponent], **_):
+    def __init__(self, content: list[BaseMessageComponent], **_) -> None:
         if isinstance(content, Node):
             # back
             content = [content]
@@ -602,10 +609,10 @@ class Node(BaseMessageComponent):
 
 
 class Nodes(BaseMessageComponent):
-    type = ComponentType.Nodes
+    type: ComponentType = ComponentType.Nodes
     nodes: list[Node]
 
-    def __init__(self, nodes: list[Node], **_):
+    def __init__(self, nodes: list[Node], **_) -> None:
         super().__init__(nodes=nodes, **_)
 
     def toDict(self):
@@ -628,29 +635,29 @@ class Nodes(BaseMessageComponent):
 
 
 class Json(BaseMessageComponent):
-    type = ComponentType.Json
+    type: ComponentType = ComponentType.Json
     data: dict
 
-    def __init__(self, data: str | dict, **_):
+    def __init__(self, data: str | dict, **_) -> None:
         if isinstance(data, str):
             data = json.loads(data)
         super().__init__(data=data, **_)
 
 
 class Unknown(BaseMessageComponent):
-    type = ComponentType.Unknown
+    type: ComponentType = ComponentType.Unknown
     text: str
 
 
 class File(BaseMessageComponent):
     """文件消息段"""
 
-    type = ComponentType.File
+    type: ComponentType = ComponentType.File
     name: str | None = ""  # 名字
     file_: str | None = ""  # 本地路径
     url: str | None = ""  # url
 
-    def __init__(self, name: str, file: str = "", url: str = ""):
+    def __init__(self, name: str, file: str = "", url: str = "") -> None:
         """文件消息段。"""
         super().__init__(name=name, file_=file, url=url)
 
@@ -686,7 +693,7 @@ class File(BaseMessageComponent):
         return ""
 
     @file.setter
-    def file(self, value: str):
+    def file(self, value: str) -> None:
         """向前兼容, 设置file属性, 传入的参数可能是文件路径或URL
 
         Args:
@@ -721,22 +728,21 @@ class File(BaseMessageComponent):
 
         return ""
 
-    async def _download_file(self):
+    async def _download_file(self) -> None:
         """下载文件"""
         if not self.url:
             raise ValueError("Download failed: No URL provided in File component.")
-        download_dir = os.path.join(get_astrbot_data_path(), "temp")
-        os.makedirs(download_dir, exist_ok=True)
+        download_dir = get_astrbot_temp_path()
         if self.name:
             name, ext = os.path.splitext(self.name)
-            filename = f"{name}_{uuid.uuid4().hex[:8]}{ext}"
+            filename = f"fileseg_{name}_{uuid.uuid4().hex[:8]}{ext}"
         else:
-            filename = f"{uuid.uuid4().hex}"
+            filename = f"fileseg_{uuid.uuid4().hex}"
         file_path = os.path.join(download_dir, filename)
         await download_file(self.url, file_path)
         self.file_ = os.path.abspath(file_path)
 
-    async def register_to_file_service(self):
+    async def register_to_file_service(self) -> str:
         """将文件注册到文件服务。
 
         Returns:
@@ -781,12 +787,12 @@ class File(BaseMessageComponent):
 
 
 class WechatEmoji(BaseMessageComponent):
-    type = ComponentType.WechatEmoji
+    type: ComponentType = ComponentType.WechatEmoji
     md5: str | None = ""
     md5_len: int | None = 0
     cdnurl: str | None = ""
 
-    def __init__(self, **_):
+    def __init__(self, **_) -> None:
         super().__init__(**_)