Complete Docker compatibility fix with enhanced documentation

Co-authored-by: Soulter <37870767+Soulter@users.noreply.github.com>

.dockerignore

@@ -17,4 +17,8 @@ ENV/
 .conda/
 README*.md
 dashboard/
-data/
+data/
+changelogs/
+tests/
+.ruff_cache/
+.astrbot

.github/FUNDING.yml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: astrbot
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
+thanks_dev: # Replace with a single thanks.dev username
+custom: ['https://afdian.com/a/astrbot_team']

.github/ISSUE_TEMPLATE/PLUGIN_PUBLISH.yml

@@ -1,39 +1,56 @@
-name: '🥳 发布插件'
-title: "[Plugin] 插件名"
+name: 🥳 发布插件
 description: 提交插件到插件市场
-labels: [ "plugin-publish" ]
+title: "[Plugin] 插件名"
+labels: ["plugin-publish"]
+assignees: []
 body:
   - type: markdown
     attributes:
       value: |
         欢迎发布插件到插件市场！
-  
-  - type: textarea
-    attributes:
-      label: 插件仓库
-      description: 插件的 GitHub 仓库链接
-      placeholder: >
-        如 https://github.com/Soulter/astrbot-github-cards
-
-  - type: textarea
-    attributes:
-      label: 描述
-      value: |
-        插件名: 
-        插件作者: 
-        插件简介: 
-        标签: (可选)
-        社交链接: (可选, 将会在插件市场作者名称上作为可点击的链接)
-      description: 必填。请以列表的字段按顺序将插件名、插件作者、插件简介放在这里。
-
-  - type: checkboxes
-    attributes:
-      label: Code of Conduct
-      options:
-        - label: >
-            我已阅读并同意遵守该项目的 [行为准则](https://docs.github.com/zh/site-policy/github-terms/github-community-code-of-conduct)。
-          required: true
 
   - type: markdown
     attributes:
-      value: "❤️"
+      value: |
+        ## 插件基本信息
+
+        请将插件信息填写到下方的 JSON 代码块中。其中 `tags`（插件标签）和 `social_link`（社交链接）选填。
+
+        不熟悉 JSON ？现在可以从 [这里](https://plugins.astrbot.app/#/submit) 获取你的 JSON 啦！获取到了记得复制粘贴过来哦！
+
+  - type: textarea
+    id: plugin-info
+    attributes:
+      label: 插件信息
+      description: 请在下方代码块中填写您的插件信息，确保反引号包裹了JSON
+      value: |
+        ```json
+        {
+          "name": "插件名",
+          "desc": "插件介绍",
+          "author": "作者名",
+          "repo": "插件仓库链接",
+          "tags": [],
+          "social_link": ""
+        }
+        ```
+    validations:
+      required: true
+
+  - type: markdown
+    attributes:
+      value: |
+        ## 检查
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: 插件检查清单
+      description: 请确认以下所有项目
+      options:
+        - label: 我的插件经过完整的测试
+          required: true
+        - label: 我的插件不包含恶意代码
+          required: true
+        - label: 我已阅读并同意遵守该项目的 [行为准则](https://docs.github.com/zh/site-policy/github-terms/github-community-code-of-conduct)。
+          required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,5 +1,5 @@
 <!-- 如果有的话，指定这个 PR 要解决的 ISSUE -->
-修复了 #XYZ
+解决了 #XYZ
 
 ### Motivation
 
@@ -8,3 +8,12 @@
 ### Modifications
 
 <!--简单解释你的改动-->
+
+### Check
+
+<!--如果分支被合并，您的代码将服务于数万名用户！在提交前，请核查一下几点内容-->
+
+- [ ] 😊 我的 Commit Message 符合良好的[规范](https://www.conventionalcommits.org/en/v1.0.0/#summary)
+- [ ] 👀 我的更改经过良好的测试
+- [ ] 🤓 我确保没有引入新依赖库，或者引入了新依赖库的同时将其添加到了 `requirements.txt` 和 `pyproject.toml` 文件相应位置。
+- [ ] 😮 我的更改没有引入恶意代码

.github/copilot-instructions.md

@@ -0,0 +1,63 @@
+# AstrBot Development Instructions
+
+AstrBot is a multi-platform LLM chatbot and development framework written in Python with a Vue.js dashboard. It supports multiple messaging platforms (QQ, Telegram, Discord, etc.) and various LLM providers (OpenAI, Anthropic, Google Gemini, etc.).
+
+Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+## Working Effectively
+
+### Bootstrap and Install Dependencies
+- **Python 3.10+ required** - Check `.python-version` file
+- Install UV package manager: `pip install uv`
+- Install project dependencies: `uv sync` -- takes 6-7 minutes. NEVER CANCEL. Set timeout to 10+ minutes.
+- Create required directories: `mkdir -p data/plugins data/config data/temp`
+
+### Running the Application
+- Run main application: `uv run main.py` -- starts in ~3 seconds
+- Application creates WebUI on http://localhost:6185 (default credentials: `astrbot`/`astrbot`)
+- Application loads plugins automatically from `packages/` and `data/plugins/` directories
+
+### Dashboard Build (Vue.js/Node.js)
+- **Prerequisites**: Node.js 20+ and npm 10+ required
+- Navigate to dashboard: `cd dashboard`
+- Install dashboard dependencies: `npm install` -- takes 2-3 minutes. NEVER CANCEL. Set timeout to 5+ minutes.
+- Build dashboard: `npm run build` -- takes 25-30 seconds. NEVER CANCEL.
+- Dashboard creates optimized production build in `dashboard/dist/`
+
+### Testing
+- Do not generate test files for now.
+
+### Code Quality and Linting
+- Install ruff linter: `uv add --dev ruff`
+- Check code style: `uv run ruff check .` -- takes <1 second
+- Check formatting: `uv run ruff format --check .` -- takes <1 second
+- Fix formatting: `uv run ruff format .`
+- **ALWAYS** run `uv run ruff check .` and `uv run ruff format .` before committing changes
+
+### Plugin Development
+- Plugins load from `packages/` (built-in) and `data/plugins/` (user-installed)
+- Plugin system supports function tools and message handlers
+- Key plugins: python_interpreter, web_searcher, astrbot, reminder, session_controller
+
+### Common Issues and Workarounds
+- **Dashboard download fails**: Known issue with "division by zero" error - application still works
+- **Import errors in tests**: Ensure `uv run` is used to run tests in proper environment
+=- **Build timeouts**: Always set appropriate timeouts (10+ minutes for uv sync, 5+ minutes for npm install)
+
+## CI/CD Integration
+- GitHub Actions workflows in `.github/workflows/`
+- Docker builds supported via `Dockerfile`
+- Pre-commit hooks enforce ruff formatting and linting
+
+## Docker Support
+- Primary deployment method: `docker run soulter/astrbot:latest`
+- Compose file available: `compose.yml`
+- Exposes ports: 6185 (WebUI), 6195 (WeChat), 6199 (QQ), etc.
+- Volume mount required: `./data:/AstrBot/data`
+
+## Multi-language Support
+- Documentation in Chinese (README.md), English (README_en.md), Japanese (README_ja.md)
+- UI supports internationalization
+- Default language is Chinese
+
+Remember: This is a production chatbot framework with real users. Always test thoroughly and ensure changes don't break existing functionality.

.github/dependabot.yml

@@ -0,0 +1,13 @@
+# Keep GitHub Actions up to date with GitHub's Dependabot...
+# https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot
+# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#package-ecosystem
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    groups:
+      github-actions:
+        patterns:
+          - "*"  # Group all Actions updates into a single larger pull request
+    schedule:
+      interval: weekly

.github/workflows/auto_release.yml

@@ -7,13 +7,13 @@ on:
 name: Auto Release
 
 jobs:
-  build:
+  build-and-publish-to-github-release:
     runs-on: ubuntu-latest
     permissions:
       contents: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Dashboard Build
         run: |
@@ -23,13 +23,70 @@ jobs:
           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 Release
+      - name: Create GitHub Release
         uses: ncipollo/release-action@v1
         with:
           bodyFile: ${{ env.changelog }}
-          artifacts: "dashboard/dist.zip"
+          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@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        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/codeql.yml

@@ -56,7 +56,7 @@ jobs:
         # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL

.github/workflows/coverage_test.yml

@@ -1,6 +1,6 @@
 name: Run tests and upload coverage
 
-on: 
+on:
   push:
     branches:
       - master
@@ -8,6 +8,7 @@ on:
       - 'README.md'
       - 'changelogs/**'
       - 'dashboard/**'
+  pull_request:
   workflow_dispatch:
 
 jobs:
@@ -16,30 +17,29 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
       
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install -r requirements.txt
-          pip install pytest pytest-cov pytest-asyncio
+          pip install pytest pytest-asyncio pytest-cov
+          pip install --editable .
 
       - name: Run tests
         run: |
-          mkdir data
-          mkdir data/plugins
-          mkdir data/config
-          mkdir data/temp
+          mkdir -p data/plugins
+          mkdir -p data/config
+          mkdir -p data/temp
           export TESTING=true
           export ZHIPU_API_KEY=${{ secrets.OPENAI_API_KEY }}
-          PYTHONPATH=./ pytest --cov=. tests/ -v -o log_cli=true -o log_level=DEBUG
+          pytest --cov=. -v -o log_cli=true -o log_level=DEBUG
 
       - name: Upload results to Codecov
-        uses: codecov/codecov-action@v4
+        uses: codecov/codecov-action@v5
         with:
-          token: ${{ secrets.CODECOV_TOKEN }}
+          token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/dashboard_ci.yml

@@ -0,0 +1,35 @@
+name: AstrBot Dashboard CI
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: npm install, build
+        run: |
+          cd dashboard
+          npm install
+          npm run build
+
+      - name: Inject Commit SHA
+        id: get_sha
+        run: |
+          echo "COMMIT_SHA=$(git rev-parse HEAD)" >> $GITHUB_ENV
+          mkdir -p dashboard/dist/assets
+          echo $COMMIT_SHA > dashboard/dist/assets/version
+
+      - name: Archive production artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-without-markdown
+          path: |
+            dashboard/dist
+            !dist/**/*.md

.github/workflows/docker-image.yml

@@ -11,24 +11,42 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - name: 拉取源码
-        uses: actions/checkout@v3
+      - name: Pull The Codes
+        uses: actions/checkout@v5
         with:
-          fetch-depth: 1
+          fetch-depth: 0  # Must be 0 so we can fetch tags
 
-      - name: 设置 QEMU
+      - name: Get latest tag (only on manual trigger)
+        id: get-latest-tag
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          tag=$(git describe --tags --abbrev=0)
+          echo "latest_tag=$tag" >> $GITHUB_OUTPUT
+
+      - name: Checkout to latest tag (only on manual trigger)
+        if: github.event_name == 'workflow_dispatch'
+        run: git checkout ${{ steps.get-latest-tag.outputs.latest_tag }}
+
+      - name: Set QEMU
         uses: docker/setup-qemu-action@v3
 
-      - name: 设置 Docker Buildx
+      - name: Set Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: 登录到 DockerHub
+      - name: Log in to DockerHub
         uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKER_HUB_USERNAME }}
           password: ${{ secrets.DOCKER_HUB_PASSWORD }}
 
-      - name: 构建和推送 Docker hub
+      - name: Login to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: Soulter
+          password: ${{ secrets.GHCR_GITHUB_TOKEN }}
+
+      - name: Build and Push Docker to DockerHub and Github GHCR
         uses: docker/build-push-action@v6
         with:
           context: .
@@ -36,8 +54,9 @@ jobs:
           push: true
           tags: |
             ${{ secrets.DOCKER_HUB_USERNAME }}/astrbot:latest
-            ${{ secrets.DOCKER_HUB_USERNAME }}/astrbot:${{ github.ref_name }}
+            ${{ secrets.DOCKER_HUB_USERNAME }}/astrbot:${{ github.event_name == 'workflow_dispatch' && steps.get-latest-tag.outputs.latest_tag || github.ref_name }}
+            ghcr.io/soulter/astrbot:latest
+            ghcr.io/soulter/astrbot:${{ github.event_name == 'workflow_dispatch' && steps.get-latest-tag.outputs.latest_tag || github.ref_name }}
 
       - name: Post build notifications
         run: echo "Docker image has been built and pushed successfully"
-

.github/workflows/stale.yml

@@ -18,7 +18,7 @@ jobs:
       pull-requests: write
 
     steps:
-    - uses: actions/stale@v5
+    - uses: actions/stale@v9
       with:
         repo-token: ${{ secrets.GITHUB_TOKEN }}
         stale-issue-message: 'Stale issue message'

.gitignore

@@ -1,6 +1,8 @@
 __pycache__
 botpy.log
 .vscode
+.venv*
+.idea
 data_v2.db
 data_v3.db
 configs/session
@@ -26,3 +28,6 @@ venv/*
 packages/python_interpreter/workplace
 .venv/*
 .conda/
+.idea
+pytest.ini
+.astrbot

.pre-commit-config.yaml

@@ -7,7 +7,7 @@ ci:
   autoupdate_commit_msg: ":balloon: pre-commit autoupdate"
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.9.9
+    rev: v0.11.2
     hooks:
       - id: ruff
       - id: ruff-format

.python-version

@@ -0,0 +1 @@
+3.10

Dockerfile

@@ -1,22 +1,35 @@
-FROM python:3.10-slim
+FROM python:3.11-slim
 WORKDIR /AstrBot
 
 COPY . /AstrBot/
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
+    nodejs \
+    npm \
     gcc \
     build-essential \
     python3-dev \
     libffi-dev \
     libssl-dev \
+    ca-certificates \
+    bash \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 
-RUN python -m pip install -r requirements.txt --no-cache-dir
+RUN python -m pip install uv
+RUN uv pip install -r requirements.txt --no-cache-dir --system
+RUN uv pip install socksio uv pyffmpeg pilk --no-cache-dir --system
 
-RUN python -m pip install socksio wechatpy cryptography --no-cache-dir
+# 释出 ffmpeg
+RUN python -c "from pyffmpeg import FFmpeg; ff = FFmpeg();"
+
+# add /root/.pyffmpeg/bin/ffmpeg to PATH, inorder to use ffmpeg
+RUN echo 'export PATH=$PATH:/root/.pyffmpeg/bin' >> ~/.bashrc
 
 EXPOSE 6185 
 EXPOSE 6186
 
 CMD [ "python", "main.py" ]
+
+
+

Dockerfile_with_node

@@ -0,0 +1,35 @@
+FROM python:3.10-slim
+
+WORKDIR /AstrBot
+
+COPY . /AstrBot/
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    build-essential \
+    python3-dev \
+    libffi-dev \
+    libssl-dev \
+    curl \
+    unzip \
+    ca-certificates \
+    bash \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# Installation of Node.js
+ENV NVM_DIR="/root/.nvm"
+RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash && \
+    . "$NVM_DIR/nvm.sh" && \
+    nvm install 22 && \
+    nvm use 22
+RUN /bin/bash -c ". \"$NVM_DIR/nvm.sh\" && node -v && npm -v"
+
+RUN python -m pip install uv
+RUN uv pip install -r requirements.txt --no-cache-dir --system
+RUN uv pip install socksio uv pyffmpeg --no-cache-dir --system
+
+EXPOSE 6185
+EXPOSE 6186
+
+CMD ["python", "main.py"]

README.md

@@ -1,6 +1,6 @@
 <p align="center">
-    
-![6e1279651f16d7fdf4727558b72bbaf1](https://github.com/user-attachments/assets/ead4c551-fc3c-48f7-a6f7-afbfdb820512)
+ 
+![AstrBot-Logo-Simplified](https://github.com/user-attachments/assets/ffd99b6b-3272-4682-beaa-6fe74250f7d9)
 
 </p>
 
@@ -10,14 +10,14 @@ _✨ 易上手的多平台 LLM 聊天机器人及开发框架 ✨_
 
 <a href="https://trendshift.io/repositories/12875" target="_blank"><img src="https://trendshift.io/api/badge/repositories/12875" alt="Soulter%2FAstrBot | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 
-[![GitHub release (latest by date)](https://img.shields.io/github/v/release/Soulter/AstrBot)](https://github.com/Soulter/AstrBot/releases/latest)
-<img src="https://img.shields.io/badge/python-3.10+-blue.svg" 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"/></a>
-<a  href="https://qm.qq.com/cgi-bin/qm/qr?k=wtbaNx7EioxeaqS9z7RQWVXPIxg2zYr7&jump_from=webapi&authKey=vlqnv/AV2DbJEvGIcxdlNSpfxVy+8vVqijgreRdnVKOaydpc+YSw4MctmEbr0k5"><img alt="Static Badge" src="https://img.shields.io/badge/QQ群-630166526-purple"></a>
-[![wakatime](https://wakatime.com/badge/user/915e5316-99c6-4563-a483-ef186cf000c9/project/018e705a-a1a7-409a-a849-3013485e6c8e.svg)](https://wakatime.com/badge/user/915e5316-99c6-4563-a483-ef186cf000c9/project/018e705a-a1a7-409a-a849-3013485e6c8e)
-![Dynamic JSON Badge](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fstats&query=v&label=7%E6%97%A5%E6%B6%88%E6%81%AF%E4%B8%8A%E8%A1%8C%E9%87%8F&cacheSeconds=3600)
-[![codecov](https://codecov.io/gh/Soulter/AstrBot/graph/badge.svg?token=FF3P5967B8)](https://codecov.io/gh/Soulter/AstrBot)
-[![star](https://gitcode.com/Soulter/AstrBot/star/badge.svg)](https://gitcode.com/Soulter/AstrBot)
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/Soulter/AstrBot?style=for-the-badge&color=76bad9)](https://github.com/Soulter/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>
+[![wakatime](https://wakatime.com/badge/user/915e5316-99c6-4563-a483-ef186cf000c9/project/018e705a-a1a7-409a-a849-3013485e6c8e.svg?style=for-the-badge&color=76bad9)](https://wakatime.com/badge/user/915e5316-99c6-4563-a483-ef186cf000c9/project/018e705a-a1a7-409a-a849-3013485e6c8e)
+![Dynamic JSON Badge](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fstats&query=v&label=7日消息量&cacheSeconds=3600&style=for-the-badge&color=3b618e)
+![Dynamic JSON Badge](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fplugin-num&query=%24.result&suffix=%E4%B8%AA&style=for-the-badge&label=%E6%8F%92%E4%BB%B6%E5%B8%82%E5%9C%BA&cacheSeconds=3600)
 
 <a href="https://github.com/Soulter/AstrBot/blob/master/README_en.md">English</a> ｜
 <a href="https://github.com/Soulter/AstrBot/blob/master/README_ja.md">日本語</a> ｜
@@ -29,84 +29,120 @@ AstrBot 是一个松耦合、异步、支持多消息平台部署、具有易用
 
 ## ✨ 主要功能
 
-1. **大语言模型对话**。支持各种大语言模型，包括 OpenAI API、Google Gemini、Llama、Deepseek、ChatGLM 等，支持接入本地部署的大模型，通过 Ollama、LLMTuner。具有多轮对话、人格情境、多模态能力，支持图片理解、语音转文字（Whisper）。
-2. **多消息平台接入**。支持接入 QQ（OneBot）、QQ 频道、微信（Gewechat）、飞书、Telegram。后续将支持钉钉、Discord、WhatsApp、小爱音响。支持速率限制、白名单、关键词过滤、百度内容审核。
-3. **Agent**。原生支持部分 Agent 能力，如代码执行器、自然语言待办、网页搜索。对接 [Dify 平台](https://astrbot.app/others/dify.html)，便捷接入 Dify 智能助手、知识库和 Dify 工作流。
-4. **插件扩展**。深度优化的插件机制，支持[开发插件](https://astrbot.app/dev/plugin.html)扩展功能，极简开发。已支持安装多个插件。
-5. **可视化管理面板**。支持可视化修改配置、插件管理、日志查看等功能，降低配置难度。集成 WebChat，可在面板上与大模型对话。
-6. **高稳定性、高模块化**。基于事件总线和流水线的架构设计，高度模块化，低耦合。
-
-> [!TIP]
-> 管理面板在线体验 Demo: [https://demo.astrbot.app/](https://demo.astrbot.app/)
-> 
-> 用户名: `astrbot`, 密码: `astrbot`。未配置 LLM，无法在聊天页使用大模型。（不要再修改 demo 的登录密码了 😭）
+1. **大模型对话**。支持接入多种大模型服务。支持多模态、工具调用、MCP、原生知识库、人设等功能。
+2. **多消息平台支持**。支持接入 QQ、企业微信、微信公众号、飞书、Telegram、钉钉、Discord、KOOK 等平台。支持速率限制、白名单、百度内容审核。
+3. **Agent**。完善适配的 Agentic 能力。支持多轮工具调用、内置沙盒代码执行器、网页搜索等功能。
+4. **插件扩展**。深度优化的插件机制，支持[开发插件](https://astrbot.app/dev/plugin.html)扩展功能，社区插件生态丰富。
+5. **WebUI**。可视化配置和管理机器人，功能齐全。
 
 ## ✨ 使用方式
 
 #### Docker 部署
 
+推荐使用 Docker / Docker Compose 方式部署 AstrBot。
+
 请参阅官方文档 [使用 Docker 部署 AstrBot](https://astrbot.app/deploy/astrbot/docker.html#%E4%BD%BF%E7%94%A8-docker-%E9%83%A8%E7%BD%B2-astrbot) 。
 
+#### 宝塔面板部署
+
+AstrBot 与宝塔面板合作，已上架至宝塔面板。
+
+请参阅官方文档 [宝塔面板部署](https://astrbot.app/deploy/astrbot/btpanel.html) 。
+
+#### 1Panel 部署
+
+AstrBot 已由 1Panel 官方上架至 1Panel 面板。
+
+请参阅官方文档 [1Panel 部署](https://astrbot.app/deploy/astrbot/1panel.html) 。
+
+#### 在 雨云 上部署
+
+AstrBot 已由雨云官方上架至云应用平台，可一键部署。
+
+[![Deploy on RainYun](https://rainyun-apps.cn-nb1.rains3.com/materials/deploy-on-rainyun-en.svg)](https://app.rainyun.com/apps/rca/store/5994?ref=NjU1ODg0)
+
+#### 在 Replit 上部署
+
+社区贡献的部署方式。
+
+[![Run on Repl.it](https://repl.it/badge/github/Soulter/AstrBot)](https://repl.it/github/Soulter/AstrBot)
+
 #### Windows 一键安装器部署
 
-需要电脑上安装有 Python（>3.10）。请参阅官方文档 [使用 Windows 一键安装器部署 AstrBot](https://astrbot.app/deploy/astrbot/windows.html) 。
-
-#### Replit 部署
-
-[![Run on Repl.it](https://repl.it/badge/github/Soulter/AstrBot)](https://repl.it/github/Soulter/AstrBot)
+请参阅官方文档 [使用 Windows 一键安装器部署 AstrBot](https://astrbot.app/deploy/astrbot/windows.html) 。
 
 #### CasaOS 部署
 
 社区贡献的部署方式。
 
-请参阅官方文档 [通过源码部署 AstrBot](https://astrbot.app/deploy/astrbot/casaos.html) 。
+请参阅官方文档 [CasaOS 部署](https://astrbot.app/deploy/astrbot/casaos.html) 。
 
 #### 手动部署
 
-请参阅官方文档 [通过源码部署 AstrBot](https://astrbot.app/deploy/astrbot/cli.html) 。
+> 推荐使用 `uv`。
 
-## 🚀 路线图
+首先，安装 uv：
 
-### 垂类功能
+```bash
+pip install uv
+```
 
-1. 更好的上下文管理：限制 token 总数、对话上下文总结
-3. AstrBot in Minecraft
+通过 Git Clone 安装 AstrBot：
 
-### 横功能
+```bash
+git clone https://github.com/AstrBotDevs/AstrBot && cd AstrBot
+uv run main.py
+```
+
+或者请参阅官方文档 [通过源码部署 AstrBot](https://astrbot.app/deploy/astrbot/cli.html) 。
 
 ## ⚡ 消息平台支持情况
 
-| 平台    | 支持性 | 详情 | 消息类型 |
-| -------- | ------- | ------- | ------ |
-| QQ(官方机器人接口) | ✔    | 私聊、群聊，QQ 频道私聊、群聊 | 文字、图片 |
-| QQ(OneBot)      | ✔    | 私聊、群聊 | 文字、图片、语音 |
-| 微信(个人号)    | ✔    | 微信个人号私聊、群聊 | 文字、图片、语音 |
-| [Telegram](https://github.com/Soulter/astrbot_plugin_telegram)   | ✔    | 私聊、群聊 | 文字、图片 |
-| [微信(企业微信)](https://github.com/Soulter/astrbot_plugin_wecom)    | ✔    | 私聊 | 文字、图片、语音 |
-| 飞书   | ✔    | 群聊 | 文字、图片 |
-| 微信对话开放平台 | 🚧    | 计划内 | - |
-| Discord   | 🚧    | 计划内 | - |
-| WhatsApp   | 🚧    | 计划内 | - |
-| 小爱音响   | 🚧    | 计划内 | - |
+| 平台    | 支持性 |
+| -------- | ------- |
+| QQ(官方机器人接口) | ✔    |
+| QQ(OneBot)      | ✔    |
+| Telegram   | ✔    |
+| 企业微信    | ✔    |
+| 微信客服    | ✔    |
+| 微信公众号    | ✔    |
+| 飞书   | ✔    |
+| 钉钉   | ✔    |
+| Slack   | ✔    |
+| Discord   | ✔    |
+| [KOOK](https://github.com/wuyan1003/astrbot_plugin_kook_adapter)   | ✔    |
+| [VoceChat](https://github.com/HikariFroya/astrbot_plugin_vocechat)   | ✔    |
+| 微信对话开放平台 | 🚧    |
+| WhatsApp   | 🚧    |
+| 小爱音响   | 🚧    |
 
 ## ⚡ 提供商支持情况
 
 | 名称    | 支持性 | 类型 | 备注 |
 | -------- | ------- | ------- | ------- |
-| OpenAI API | ✔    | 文本生成 | 同时也支持 DeepSeek、Google Gemini、GLM（智谱）、Moonshot（月之暗面）、阿里云百炼、硅基流动、xAI 等所有兼容 OpenAI API 的服务 |
+| OpenAI API | ✔    | 文本生成 | 也支持 DeepSeek、Gemini、Kimi、xAI 等兼容 OpenAI API 的服务 |
 | Claude API | ✔    | 文本生成 |  |
 | Google Gemini API | ✔    | 文本生成 |  |
 | Dify | ✔    | LLMOps |  |
-| DashScope(阿里云百炼应用) | ✔    | LLMOps |  |
+| 阿里云百炼应用 | ✔    | LLMOps |  |
 | Ollama | ✔    | 模型加载器 | 本地部署 DeepSeek、Llama 等开源语言模型 |
 | LM Studio | ✔    | 模型加载器 | 本地部署 DeepSeek、Llama 等开源语言模型 |
 | LLMTuner | ✔    | 模型加载器 | 本地加载 lora 等微调模型 |
+| [优云智算](https://www.compshare.cn/?ytag=GPU_YY-gh_astrbot&referral_code=FV7DcGowN4hB5UuXKgpE74) | ✔    | 模型 API 及算力服务平台 |  |
+| [302.AI](https://share.302.ai/rr1M3l) | ✔    | 模型 API 服务平台 |  |
+| 硅基流动 | ✔    | 模型 API 服务平台 |  |
+| PPIO 派欧云 | ✔    | 模型 API 服务平台 |  |
 | OneAPI | ✔    | LLM 分发系统 |  |
 | Whisper | ✔    | 语音转文本 | 支持 API、本地部署 |
 | SenseVoice | ✔    | 语音转文本 | 本地部署 |
 | OpenAI TTS API | ✔    | 文本转语音 |  |
-| Fishaudio | ✔    | 文本转语音 | GPT-Sovits 作者参与的项目 |
-| Edge-TTS | ✔    | 文本转语音 | Edge 浏览器的免费 TTS |
+| GSVI | ✔    | 文本转语音 | GPT-Sovits-Inference |
+| GPT-SoVITs | ✔    | 文本转语音 | GPT-Sovits-Inference |
+| FishAudio | ✔    | 文本转语音 | GPT-Sovits 作者参与的项目 |
+| Edge TTS | ✔    | 文本转语音 | Edge 浏览器的免费 TTS |
+| 阿里云百炼 TTS | ✔    | 文本转语音 |  |
+| Azure TTS | ✔    | 文本转语音 | Microsoft Azure TTS |
+
 
 ## ❤️ 贡献
 
@@ -130,42 +166,48 @@ pre-commit install
 
 - Star 这个项目！
 - 在[爱发电](https://afdian.com/a/soulter)支持我！
-- 在[微信](https://drive.soulter.top/f/pYfA/d903f4fa49a496fda3f16d2be9e023b5.png)支持我~
 
 ## ✨ Demo
 
-> [!NOTE]
-> 代码执行器的文件输入/输出目前仅测试了 Napcat(QQ), Lagrange(QQ)
+<details><summary>👉 点击展开多张 Demo 截图 👈</summary>
 
 <div align='center'>
 
 <img src="https://github.com/user-attachments/assets/4ee688d9-467d-45c8-99d6-368f9a8a92d8" width="600">
 
-_✨基于 Docker 的沙箱化代码执行器（Beta 测试中）✨_
+_✨基于 Docker 的沙箱化代码执行器（Beta 测试）✨_
 
 <img src="https://github.com/user-attachments/assets/0378f407-6079-4f64-ae4c-e97ab20611d2" height=500>
 
 _✨ 多模态、网页搜索、长文本转图片（可配置） ✨_
 
-<img src="https://github.com/user-attachments/assets/8ec12797-e70f-460a-959e-48eca39ca2bb" height=100>
-
-_✨ 自然语言待办事项 ✨_
-
 <img src="https://github.com/user-attachments/assets/e137a9e1-340a-4bf2-bb2b-771132780735" height=150>
 <img src="https://github.com/user-attachments/assets/480f5e82-cf6a-4955-a869-0d73137aa6e1" height=150>
 
 _✨ 插件系统——部分插件展示 ✨_
 
-<img src="https://github.com/user-attachments/assets/592a8630-14c7-4e06-b496-9c0386e4f36c" width=600>
+<img src="https://github.com/user-attachments/assets/0cdbf564-2f59-4da5-b524-ce0e7ef3d978" width=600>
 
-_✨ 管理面板 ✨_
-
-![webchat](https://drive.soulter.top/f/vlsA/ezgif-5-fb044b2542.gif)
-
-_✨ 内置 Web Chat，在线与机器人交互 ✨_
+_✨ WebUI ✨_
 
 </div>
 
+</details>
+
+
+## ❤️ Special Thanks
+
+特别感谢所有 Contributors 和插件开发者对 AstrBot 的贡献 ❤️
+
+<a href="https://github.com/AstrBotDevs/AstrBot/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=AstrBotDevs/AstrBot" />
+</a>
+
+此外，本项目的诞生离不开以下开源项目：
+
+- [NapNeko/NapCatQQ](https://github.com/NapNeko/NapCatQQ) - 伟大的猫猫框架
+- [wechatpy/wechatpy](https://github.com/wechatpy/wechatpy)
+
 ## ⭐ Star History
 
 > [!TIP] 
@@ -177,21 +219,7 @@ _✨ 内置 Web Chat，在线与机器人交互 ✨_
 
 </div>
 
-## Disclaimer
-
-1. The project is protected under the `AGPL-v3` opensource license.
-2. The deployment of WeChat (personal account) utilizes [Gewechat](https://github.com/Devo919/Gewechat) service. AstrBot only guarantees connectivity with Gewechat and recommends using a WeChat account that is not frequently used. In the event of account risk control, the author of this project shall not bear any responsibility.
-3. Please ensure compliance with local laws and regulations when using this project.
-
-<!-- ## ✨ ATRI [Beta 测试]
-
-该功能作为插件载入。插件仓库地址：[astrbot_plugin_atri](https://github.com/Soulter/astrbot_plugin_atri)
-
-1. 基于《ATRI ~ My Dear Moments》主角 ATRI 角色台词作为微调数据集的 `Qwen1.5-7B-Chat Lora` 微调模型。
-2. 长期记忆
-3. 表情包理解与回复
-4. TTS
-    -->
+![10k-star-banner-credit-by-kevin](https://github.com/user-attachments/assets/c97fc5fb-20b9-4bc8-9998-c20b930ab097)
 
 
 _私は、高性能ですから!_

README_en.md

@@ -28,7 +28,7 @@ AstrBot is a loosely coupled, asynchronous chatbot and development framework tha
 
 1. **LLM Conversations** - Supports various LLMs including OpenAI API, Google Gemini, Llama, Deepseek, ChatGLM, etc. Enables local model deployment via Ollama/LLMTuner. Features multi-turn dialogues, personality contexts, multimodal capabilities (image understanding), and speech-to-text (Whisper).
 2. **Multi-platform Integration** - Supports QQ (OneBot), QQ Channels, WeChat (Gewechat), Feishu, and Telegram. Planned support for DingTalk, Discord, WhatsApp, and Xiaomi Smart Speakers. Includes rate limiting, whitelisting, keyword filtering, and Baidu content moderation.
-3. **Agent Capabilities** - Native support for code execution, natural language TODO lists, web search. Integrates with [Dify Platform](https://astrbot.app/others/dify.html) for easy access to Dify assistants/knowledge bases/workflows.
+3. **Agent Capabilities** - Native support for code execution, natural language TODO lists, web search. Integrates with [Dify Platform](https://dify.ai/) for easy access to Dify assistants/knowledge bases/workflows.
 4. **Plugin System** - Optimized plugin mechanism with minimal development effort. Supports multiple installed plugins.
 5. **Web Dashboard** - Visual configuration management, plugin controls, logging, and WebChat interface for direct LLM interaction.
 6. **High Stability & Modularity** - Event bus and pipeline architecture ensures high modularization and loose coupling.

README_ja.md

@@ -1,5 +1,5 @@
 <p align="center">
-    
+
 ![6e1279651f16d7fdf4727558b72bbaf1](https://github.com/user-attachments/assets/ead4c551-fc3c-48f7-a6f7-afbfdb820512)
 
 </p>
@@ -27,15 +27,15 @@ AstrBot は、疎結合、非同期、複数のメッセージプラットフォ
 ## ✨ 主な機能
 
 1. **大規模言語モデルの対話**。OpenAI API、Google Gemini、Llama、Deepseek、ChatGLM など、さまざまな大規模言語モデルをサポートし、Ollama、LLMTuner を介してローカルにデプロイされた大規模モデルをサポートします。多輪対話、人格シナリオ、多モーダル機能を備え、画像理解、音声からテキストへの変換（Whisper）をサポートします。
-2. **複数のメッセージプラットフォームの接続**。QQ（OneBot）、QQ チャンネル、WeChat（Gewechat）、Feishu、Telegram への接続をサポートします。今後、DingTalk、Discord、WhatsApp、Xiaoai 音響をサポートする予定です。レート制限、ホワイトリスト、キーワードフィルタリング、Baidu コンテンツ監査をサポートします。
-3. **エージェント**。一部のエージェント機能をネイティブにサポートし、コードエグゼキューター、自然言語タスク、ウェブ検索などを提供します。[Dify プラットフォーム](https://astrbot.app/others/dify.html)と連携し、Dify スマートアシスタント、ナレッジベース、Dify ワークフローを簡単に接続できます。
+2. **複数のメッセージプラットフォームの接続**。QQ（OneBot）、QQ チャンネル、Feishu、Telegram への接続をサポートします。今後、DingTalk、Discord、WhatsApp、Xiaoai 音響をサポートする予定です。レート制限、ホワイトリスト、キーワードフィルタリング、Baidu コンテンツ監査をサポートします。
+3. **エージェント**。一部のエージェント機能をネイティブにサポートし、コードエグゼキューター、自然言語タスク、ウェブ検索などを提供します。[Dify プラットフォーム](https://dify.ai/)と連携し、Dify スマートアシスタント、ナレッジベース、Dify ワークフローを簡単に接続できます。
 4. **プラグインの拡張**。深く最適化されたプラグインメカニズムを備え、[プラグインの開発](https://astrbot.app/dev/plugin.html)をサポートし、機能を拡張できます。複数のプラグインのインストールをサポートします。
 5. **ビジュアル管理パネル**。設定の視覚的な変更、プラグイン管理、ログの表示などをサポートし、設定の難易度を低減します。WebChat を統合し、パネル上で大規模モデルと対話できます。
 6. **高い安定性と高いモジュール性**。イベントバスとパイプラインに基づくアーキテクチャ設計により、高度にモジュール化され、低結合です。
 
 > [!TIP]
 > 管理パネルのオンラインデモを体験する: [https://demo.astrbot.app/](https://demo.astrbot.app/)
-> 
+>
 > ユーザー名: `astrbot`, パスワード: `astrbot`。LLM が設定されていないため、チャットページで大規模モデルを使用することはできません。（デモのログインパスワードを変更しないでください 😭）
 
 ## ✨ 使用方法
@@ -136,11 +136,11 @@ _✨ 内蔵 Web Chat、オンラインでボットと対話 ✨_
 
 ## ⭐ Star History
 
-> [!TIP] 
+> [!TIP]
 > このプロジェクトがあなたの生活や仕事に役立った場合、またはこのプロジェクトの将来の発展に関心がある場合は、プロジェクトに Star を付けてください。これはこのオープンソースプロジェクトを維持するためのモチベーションです <3
 
 <div align="center">
-    
+
 [![Star History Chart](https://api.star-history.com/svg?repos=soulter/astrbot&type=Date)](https://star-history.com/#soulter/astrbot&Date)
 
 </div>
@@ -152,8 +152,7 @@ _✨ 内蔵 Web Chat、オンラインでボットと対話 ✨_
 ## 免責事項
 
 1. このプロジェクトは `AGPL-v3` オープンソースライセンスの下で保護されています。
-2. WeChat（個人アカウント）のデプロイメントには [Gewechat](https://github.com/Devo919/Gewechat) サービスを利用しています。AstrBot は Gewechat との接続を保証するだけであり、アカウントのリスク管理に関しては、このプロジェクトの著者は一切の責任を負いません。
-3. このプロジェクトを使用する際は、現地の法律および規制を遵守してください。
+2. このプロジェクトを使用する際は、現地の法律および規制を遵守してください。
 
 <!-- ## ✨ ATRI [ベータテスト]
 
@@ -165,6 +164,4 @@ _✨ 内蔵 Web Chat、オンラインでボットと対話 ✨_
 4. TTS
     -->
 
-
 _私は、高性能ですから!_
-

astrbot/api/platform/__init__.py

@@ -5,6 +5,7 @@ from astrbot.core.platform import (
     MessageMember,
     MessageType,
     PlatformMetadata,
+    Group,
 )
 
 from astrbot.core.platform.register import register_platform_adapter
@@ -18,4 +19,5 @@ __all__ = [
     "MessageType",
     "PlatformMetadata",
     "register_platform_adapter",
+    "Group",
 ]

astrbot/api/provider/__init__.py

@@ -1,5 +1,5 @@
 from astrbot.core.provider import Provider, STTProvider, Personality
-from astrbot.core.provider.entites import (
+from astrbot.core.provider.entities import (
     ProviderRequest,
     ProviderType,
     ProviderMetaData,

astrbot/api/star/__init__.py

@@ -2,11 +2,7 @@ from astrbot.core.star.register import (
     register_star as register,  # 注册插件（Star）
 )
 
-from astrbot.core.star import Context, Star
+from astrbot.core.star import Context, Star, StarTools
 from astrbot.core.star.config import *
 
-__all__ = [
-    "register",
-    "Context",
-    "Star",
-]
+__all__ = ["register", "Context", "Star", "StarTools"]

astrbot/cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "3.5.23"

astrbot/cli/__main__.py

@@ -0,0 +1,59 @@
+"""
+AstrBot CLI入口
+"""
+
+import click
+import sys
+from . import __version__
+from .commands import init, run, plug, conf
+
+logo_tmpl = r"""
+     ___           _______.___________..______      .______     ______   .___________.
+    /   \         /       |           ||   _  \     |   _  \   /  __  \  |           |
+   /  ^  \       |   (----`---|  |----`|  |_)  |    |  |_)  | |  |  |  | `---|  |----`
+  /  /_\  \       \   \       |  |     |      /     |   _  <  |  |  |  |     |  |
+ /  _____  \  .----)   |      |  |     |  |\  \----.|  |_)  | |  `--'  |     |  |
+/__/     \__\ |_______/       |__|     | _| `._____||______/   \______/      |__|
+"""
+
+
+@click.group()
+@click.version_option(__version__, prog_name="AstrBot")
+def cli() -> None:
+    """The AstrBot CLI"""
+    click.echo(logo_tmpl)
+    click.echo("Welcome to AstrBot CLI!")
+    click.echo(f"AstrBot CLI version: {__version__}")
+
+
+@click.command()
+@click.argument("command_name", required=False, type=str)
+def help(command_name: str | None) -> None:
+    """显示命令的帮助信息
+
+    如果提供了 COMMAND_NAME，则显示该命令的详细帮助信息。
+    否则，显示通用帮助信息。
+    """
+    ctx = click.get_current_context()
+    if command_name:
+        # 查找指定命令
+        command = cli.get_command(ctx, command_name)
+        if command:
+            # 显示特定命令的帮助信息
+            click.echo(command.get_help(ctx))
+        else:
+            click.echo(f"Unknown command: {command_name}")
+            sys.exit(1)
+    else:
+        # 显示通用帮助信息
+        click.echo(cli.get_help(ctx))
+
+
+cli.add_command(init)
+cli.add_command(run)
+cli.add_command(help)
+cli.add_command(plug)
+cli.add_command(conf)
+
+if __name__ == "__main__":
+    cli()

astrbot/cli/commands/__init__.py

@@ -0,0 +1,6 @@
+from .cmd_init import init
+from .cmd_run import run
+from .cmd_plug import plug
+from .cmd_conf import conf
+
+__all__ = ["init", "run", "plug", "conf"]

astrbot/cli/commands/cmd_conf.py

@@ -0,0 +1,255 @@
+import json
+import click
+import hashlib
+import zoneinfo
+from typing import Any, Callable
+from ..utils import get_astrbot_root, check_astrbot_root
+
+
+def _validate_log_level(value: str) -> str:
+    """验证日志级别"""
+    value = value.upper()
+    if value not in ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]:
+        raise click.ClickException(
+            "日志级别必须是 DEBUG/INFO/WARNING/ERROR/CRITICAL 之一"
+        )
+    return value
+
+
+def _validate_dashboard_port(value: str) -> int:
+    """验证 Dashboard 端口"""
+    try:
+        port = int(value)
+        if port < 1 or port > 65535:
+            raise click.ClickException("端口必须在 1-65535 范围内")
+        return port
+    except ValueError:
+        raise click.ClickException("端口必须是数字")
+
+
+def _validate_dashboard_username(value: str) -> str:
+    """验证 Dashboard 用户名"""
+    if not value:
+        raise click.ClickException("用户名不能为空")
+    return value
+
+
+def _validate_dashboard_password(value: str) -> str:
+    """验证 Dashboard 密码"""
+    if not value:
+        raise click.ClickException("密码不能为空")
+    return hashlib.md5(value.encode()).hexdigest()
+
+
+def _validate_timezone(value: str) -> str:
+    """验证时区"""
+    try:
+        zoneinfo.ZoneInfo(value)
+    except Exception:
+        raise click.ClickException(f"无效的时区: {value}，请使用有效的IANA时区名称")
+    return value
+
+
+def _validate_callback_api_base(value: str) -> str:
+    """验证回调接口基址"""
+    if not value.startswith("http://") and not value.startswith("https://"):
+        raise click.ClickException("回调接口基址必须以 http:// 或 https:// 开头")
+    return value
+
+
+# 可通过CLI设置的配置项，配置键到验证器函数的映射
+CONFIG_VALIDATORS: dict[str, Callable[[str], Any]] = {
+    "timezone": _validate_timezone,
+    "log_level": _validate_log_level,
+    "dashboard.port": _validate_dashboard_port,
+    "dashboard.username": _validate_dashboard_username,
+    "dashboard.password": _validate_dashboard_password,
+    "callback_api_base": _validate_callback_api_base,
+}
+
+
+def _load_config() -> dict[str, Any]:
+    """加载或初始化配置文件"""
+    root = get_astrbot_root()
+    if not check_astrbot_root(root):
+        raise click.ClickException(
+            f"{root}不是有效的 AstrBot 根目录，如需初始化请使用 astrbot init"
+        )
+
+    config_path = root / "data" / "cmd_config.json"
+    if not config_path.exists():
+        from astrbot.core.config.default import DEFAULT_CONFIG
+
+        config_path.write_text(
+            json.dumps(DEFAULT_CONFIG, ensure_ascii=False, indent=2),
+            encoding="utf-8-sig",
+        )
+
+    try:
+        return json.loads(config_path.read_text(encoding="utf-8-sig"))
+    except json.JSONDecodeError as e:
+        raise click.ClickException(f"配置文件解析失败: {str(e)}")
+
+
+def _save_config(config: dict[str, Any]) -> None:
+    """保存配置文件"""
+    config_path = get_astrbot_root() / "data" / "cmd_config.json"
+
+    config_path.write_text(
+        json.dumps(config, ensure_ascii=False, indent=2), encoding="utf-8-sig"
+    )
+
+
+def _set_nested_item(obj: dict[str, Any], path: str, value: Any) -> None:
+    """设置嵌套字典中的值"""
+    parts = path.split(".")
+    for part in parts[:-1]:
+        if part not in obj:
+            obj[part] = {}
+        elif not isinstance(obj[part], dict):
+            raise click.ClickException(
+                f"配置路径冲突: {'.'.join(parts[: parts.index(part) + 1])} 不是字典"
+            )
+        obj = obj[part]
+    obj[parts[-1]] = value
+
+
+def _get_nested_item(obj: dict[str, Any], path: str) -> Any:
+    """获取嵌套字典中的值"""
+    parts = path.split(".")
+    for part in parts:
+        obj = obj[part]
+    return obj
+
+
+@click.group(name="conf")
+def conf():
+    """配置管理命令
+
+    支持的配置项:
+
+    - timezone: 时区设置 (例如: Asia/Shanghai)
+
+    - log_level: 日志级别 (DEBUG/INFO/WARNING/ERROR/CRITICAL)
+
+    - dashboard.port: Dashboard 端口
+
+    - dashboard.username: Dashboard 用户名
+
+    - dashboard.password: Dashboard 密码
+
+    - callback_api_base: 回调接口基址
+
+    可用子命令:
+
+    - set: 设置配置项值
+
+    - get: 获取配置项值
+
+    - login-info: 显示 Web 管理面板登录信息
+    """
+    pass
+
+
+@conf.command(name="set")
+@click.argument("key")
+@click.argument("value")
+def set_config(key: str, value: str):
+    """设置配置项的值"""
+    if key not in CONFIG_VALIDATORS.keys():
+        raise click.ClickException(f"不支持的配置项: {key}")
+
+    config = _load_config()
+
+    try:
+        old_value = _get_nested_item(config, key)
+        validated_value = CONFIG_VALIDATORS[key](value)
+        _set_nested_item(config, key, validated_value)
+        _save_config(config)
+
+        click.echo(f"配置已更新: {key}")
+        if key == "dashboard.password":
+            click.echo("  原值: ********")
+            click.echo("  新值: ********")
+        else:
+            click.echo(f"  原值: {old_value}")
+            click.echo(f"  新值: {validated_value}")
+
+    except KeyError:
+        raise click.ClickException(f"未知的配置项: {key}")
+    except Exception as e:
+        raise click.UsageError(f"设置配置失败: {str(e)}")
+
+
+@conf.command(name="get")
+@click.argument("key", required=False)
+def get_config(key: str = None):
+    """获取配置项的值，不提供key则显示所有可配置项"""
+    config = _load_config()
+
+    if key:
+        if key not in CONFIG_VALIDATORS.keys():
+            raise click.ClickException(f"不支持的配置项: {key}")
+
+        try:
+            value = _get_nested_item(config, key)
+            if key == "dashboard.password":
+                value = "********"
+            click.echo(f"{key}: {value}")
+        except KeyError:
+            raise click.ClickException(f"未知的配置项: {key}")
+        except Exception as e:
+            raise click.UsageError(f"获取配置失败: {str(e)}")
+    else:
+        click.echo("当前配置:")
+        for key in CONFIG_VALIDATORS.keys():
+            try:
+                value = (
+                    "********"
+                    if key == "dashboard.password"
+                    else _get_nested_item(config, key)
+                )
+                click.echo(f"  {key}: {value}")
+            except (KeyError, TypeError):
+                pass
+
+
+@conf.command(name="login-info")
+def get_login_info():
+    """显示 Web 管理面板的登录信息
+
+    在 Docker 环境中使用示例:
+    docker exec -e ASTRBOT_ROOT=/AstrBot astrbot-container astrbot conf login-info
+    """
+    config = _load_config()
+
+    try:
+        username = _get_nested_item(config, "dashboard.username")
+        # 注意：我们不显示实际的MD5哈希密码，而是提示用户如何重置
+        click.echo("🔐 Web 管理面板登录信息:")
+        click.echo(f"  用户名: {username}")
+        click.echo("  密码: [已加密存储]")
+        click.echo()
+        click.echo("💡 如需重置密码，请使用以下命令:")
+        click.echo("  astrbot conf set dashboard.password <新密码>")
+        click.echo()
+        click.echo("🌐 访问地址:")
+
+        # 尝试获取端口信息
+        try:
+            port = _get_nested_item(config, "dashboard.port")
+            click.echo(f"  http://localhost:{port}")
+            click.echo(f"  http://your-server-ip:{port}")
+        except (KeyError, TypeError):
+            click.echo("  http://localhost:6185 (默认端口)")
+            click.echo("  http://your-server-ip:6185 (默认端口)")
+
+        click.echo()
+        click.echo("📋 Docker 环境使用说明:")
+        click.echo("  如果在 Docker 中运行，请使用以下命令格式:")
+        click.echo("  docker exec -e ASTRBOT_ROOT=/AstrBot <容器名> astrbot conf login-info")
+
+    except KeyError:
+        click.echo("❌ 无法找到登录配置，请先运行 'astrbot init' 初始化")
+    except Exception as e:
+        raise click.UsageError(f"获取登录信息失败: {str(e)}")

astrbot/cli/commands/cmd_init.py

@@ -0,0 +1,55 @@
+import asyncio
+
+import click
+from filelock import FileLock, Timeout
+
+from ..utils import check_dashboard, get_astrbot_root
+
+
+async def initialize_astrbot(astrbot_root) -> None:
+    """执行 AstrBot 初始化逻辑"""
+    dot_astrbot = astrbot_root / ".astrbot"
+
+    if not dot_astrbot.exists():
+        click.echo(f"Current Directory: {astrbot_root}")
+        click.echo(
+            "如果你确认这是 Astrbot root directory, 你需要在当前目录下创建一个 .astrbot 文件标记该目录为 AstrBot 的数据目录。"
+        )
+        if click.confirm(
+            f"请检查当前目录是否正确，确认正确请回车: {astrbot_root}",
+            default=True,
+            abort=True,
+        ):
+            dot_astrbot.touch()
+            click.echo(f"Created {dot_astrbot}")
+
+    paths = {
+        "data": astrbot_root / "data",
+        "config": astrbot_root / "data" / "config",
+        "plugins": astrbot_root / "data" / "plugins",
+        "temp": astrbot_root / "data" / "temp",
+    }
+
+    for name, path in paths.items():
+        path.mkdir(parents=True, exist_ok=True)
+        click.echo(f"{'Created' if not path.exists() else 'Directory exists'}: {path}")
+
+    await check_dashboard(astrbot_root / "data")
+
+
+@click.command()
+def init() -> None:
+    """初始化 AstrBot"""
+    click.echo("Initializing AstrBot...")
+    astrbot_root = get_astrbot_root()
+    lock_file = astrbot_root / "astrbot.lock"
+    lock = FileLock(lock_file, timeout=5)
+
+    try:
+        with lock.acquire():
+            asyncio.run(initialize_astrbot(astrbot_root))
+    except Timeout:
+        raise click.ClickException("无法获取锁文件，请检查是否有其他实例正在运行")
+
+    except Exception as e:
+        raise click.ClickException(f"初始化失败: {e!s}")

astrbot/cli/commands/cmd_plug.py

@@ -0,0 +1,247 @@
+import re
+from pathlib import Path
+
+import click
+import shutil
+
+
+from ..utils import (
+    get_git_repo,
+    build_plug_list,
+    manage_plugin,
+    PluginStatus,
+    check_astrbot_root,
+    get_astrbot_root,
+)
+
+
+@click.group()
+def plug():
+    """插件管理"""
+    pass
+
+
+def _get_data_path() -> Path:
+    base = get_astrbot_root()
+    if not check_astrbot_root(base):
+        raise click.ClickException(
+            f"{base}不是有效的 AstrBot 根目录，如需初始化请使用 astrbot init"
+        )
+    return (base / "data").resolve()
+
+
+def display_plugins(plugins, title=None, color=None):
+    if title:
+        click.echo(click.style(title, fg=color, bold=True))
+
+    click.echo(f"{'名称':<20} {'版本':<10} {'状态':<10} {'作者':<15} {'描述':<30}")
+    click.echo("-" * 85)
+
+    for p in plugins:
+        desc = p["desc"][:30] + ("..." if len(p["desc"]) > 30 else "")
+        click.echo(
+            f"{p['name']:<20} {p['version']:<10} {p['status']:<10} "
+            f"{p['author']:<15} {desc:<30}"
+        )
+
+
+@plug.command()
+@click.argument("name")
+def new(name: str):
+    """创建新插件"""
+    base_path = _get_data_path()
+    plug_path = base_path / "plugins" / name
+
+    if plug_path.exists():
+        raise click.ClickException(f"插件 {name} 已存在")
+
+    author = click.prompt("请输入插件作者", type=str)
+    desc = click.prompt("请输入插件描述", type=str)
+    version = click.prompt("请输入插件版本", type=str)
+    if not re.match(r"^\d+\.\d+(\.\d+)?$", version.lower().lstrip("v")):
+        raise click.ClickException("版本号必须为 x.y 或 x.y.z 格式")
+    repo = click.prompt("请输入插件仓库：", type=str)
+    if not repo.startswith("http"):
+        raise click.ClickException("仓库地址必须以 http 开头")
+
+    click.echo("下载插件模板...")
+    get_git_repo(
+        "https://github.com/Soulter/helloworld",
+        plug_path,
+    )
+
+    click.echo("重写插件信息...")
+    # 重写 metadata.yaml
+    with open(plug_path / "metadata.yaml", "w", encoding="utf-8") as f:
+        f.write(
+            f"name: {name}\n"
+            f"desc: {desc}\n"
+            f"version: {version}\n"
+            f"author: {author}\n"
+            f"repo: {repo}\n"
+        )
+
+    # 重写 README.md
+    with open(plug_path / "README.md", "w", encoding="utf-8") as f:
+        f.write(f"# {name}\n\n{desc}\n\n# 支持\n\n[帮助文档](https://astrbot.app)\n")
+
+    # 重写 main.py
+    with open(plug_path / "main.py", "r", encoding="utf-8") as f:
+        content = f.read()
+
+    new_content = content.replace(
+        '@register("helloworld", "YourName", "一个简单的 Hello World 插件", "1.0.0")',
+        f'@register("{name}", "{author}", "{desc}", "{version}")',
+    )
+
+    with open(plug_path / "main.py", "w", encoding="utf-8") as f:
+        f.write(new_content)
+
+    click.echo(f"插件 {name} 创建成功")
+
+
+@plug.command()
+@click.option("--all", "-a", is_flag=True, help="列出未安装的插件")
+def list(all: bool):
+    """列出插件"""
+    base_path = _get_data_path()
+    plugins = build_plug_list(base_path / "plugins")
+
+    # 未发布的插件
+    not_published_plugins = [
+        p for p in plugins if p["status"] == PluginStatus.NOT_PUBLISHED
+    ]
+    if not_published_plugins:
+        display_plugins(not_published_plugins, "未发布的插件", "red")
+
+    # 需要更新的插件
+    need_update_plugins = [
+        p for p in plugins if p["status"] == PluginStatus.NEED_UPDATE
+    ]
+    if need_update_plugins:
+        display_plugins(need_update_plugins, "需要更新的插件", "yellow")
+
+    # 已安装的插件
+    installed_plugins = [p for p in plugins if p["status"] == PluginStatus.INSTALLED]
+    if installed_plugins:
+        display_plugins(installed_plugins, "已安装的插件", "green")
+
+    # 未安装的插件
+    not_installed_plugins = [
+        p for p in plugins if p["status"] == PluginStatus.NOT_INSTALLED
+    ]
+    if not_installed_plugins and all:
+        display_plugins(not_installed_plugins, "未安装的插件", "blue")
+
+    if (
+        not any([not_published_plugins, need_update_plugins, installed_plugins])
+        and not all
+    ):
+        click.echo("未安装任何插件")
+
+
+@plug.command()
+@click.argument("name")
+@click.option("--proxy", help="代理服务器地址")
+def install(name: str, proxy: str | None):
+    """安装插件"""
+    base_path = _get_data_path()
+    plug_path = base_path / "plugins"
+    plugins = build_plug_list(base_path / "plugins")
+
+    plugin = next(
+        (
+            p
+            for p in plugins
+            if p["name"] == name and p["status"] == PluginStatus.NOT_INSTALLED
+        ),
+        None,
+    )
+
+    if not plugin:
+        raise click.ClickException(f"未找到可安装的插件 {name}，可能是不存在或已安装")
+
+    manage_plugin(plugin, plug_path, is_update=False, proxy=proxy)
+
+
+@plug.command()
+@click.argument("name")
+def remove(name: str):
+    """卸载插件"""
+    base_path = _get_data_path()
+    plugins = build_plug_list(base_path / "plugins")
+    plugin = next((p for p in plugins if p["name"] == name), None)
+
+    if not plugin or not plugin.get("local_path"):
+        raise click.ClickException(f"插件 {name} 不存在或未安装")
+
+    plugin_path = plugin["local_path"]
+
+    click.confirm(f"确定要卸载插件 {name} 吗?", default=False, abort=True)
+
+    try:
+        shutil.rmtree(plugin_path)
+        click.echo(f"插件 {name} 已卸载")
+    except Exception as e:
+        raise click.ClickException(f"卸载插件 {name} 失败: {e}")
+
+
+@plug.command()
+@click.argument("name", required=False)
+@click.option("--proxy", help="Github代理地址")
+def update(name: str, proxy: str | None):
+    """更新插件"""
+    base_path = _get_data_path()
+    plug_path = base_path / "plugins"
+    plugins = build_plug_list(base_path / "plugins")
+
+    if name:
+        plugin = next(
+            (
+                p
+                for p in plugins
+                if p["name"] == name and p["status"] == PluginStatus.NEED_UPDATE
+            ),
+            None,
+        )
+
+        if not plugin:
+            raise click.ClickException(f"插件 {name} 不需要更新或无法更新")
+
+        manage_plugin(plugin, plug_path, is_update=True, proxy=proxy)
+    else:
+        need_update_plugins = [
+            p for p in plugins if p["status"] == PluginStatus.NEED_UPDATE
+        ]
+
+        if not need_update_plugins:
+            click.echo("没有需要更新的插件")
+            return
+
+        click.echo(f"发现 {len(need_update_plugins)} 个插件需要更新")
+        for plugin in need_update_plugins:
+            plugin_name = plugin["name"]
+            click.echo(f"正在更新插件 {plugin_name}...")
+            manage_plugin(plugin, plug_path, is_update=True, proxy=proxy)
+
+
+@plug.command()
+@click.argument("query")
+def search(query: str):
+    """搜索插件"""
+    base_path = _get_data_path()
+    plugins = build_plug_list(base_path / "plugins")
+
+    matched_plugins = [
+        p
+        for p in plugins
+        if query.lower() in p["name"].lower()
+        or query.lower() in p["desc"].lower()
+        or query.lower() in p["author"].lower()
+    ]
+
+    if not matched_plugins:
+        click.echo(f"未找到匹配 '{query}' 的插件")
+        return
+
+    display_plugins(matched_plugins, f"搜索结果: '{query}'", "cyan")

astrbot/cli/commands/cmd_run.py

@@ -0,0 +1,63 @@
+import os
+import sys
+from pathlib import Path
+
+import click
+import asyncio
+import traceback
+
+from filelock import FileLock, Timeout
+
+from ..utils import check_dashboard, check_astrbot_root, get_astrbot_root
+
+
+async def run_astrbot(astrbot_root: Path):
+    """运行 AstrBot"""
+    from astrbot.core import logger, LogManager, LogBroker, db_helper
+    from astrbot.core.initial_loader import InitialLoader
+
+    await check_dashboard(astrbot_root / "data")
+
+    log_broker = LogBroker()
+    LogManager.set_queue_handler(logger, log_broker)
+    db = db_helper
+
+    core_lifecycle = InitialLoader(db, log_broker)
+
+    await core_lifecycle.start()
+
+
+@click.option("--reload", "-r", is_flag=True, help="插件自动重载")
+@click.option("--port", "-p", help="Astrbot Dashboard端口", required=False, type=str)
+@click.command()
+def run(reload: bool, port: str) -> None:
+    """运行 AstrBot"""
+    try:
+        os.environ["ASTRBOT_CLI"] = "1"
+        astrbot_root = get_astrbot_root()
+
+        if not check_astrbot_root(astrbot_root):
+            raise click.ClickException(
+                f"{astrbot_root}不是有效的 AstrBot 根目录，如需初始化请使用 astrbot init"
+            )
+
+        os.environ["ASTRBOT_ROOT"] = str(astrbot_root)
+        sys.path.insert(0, str(astrbot_root))
+
+        if port:
+            os.environ["DASHBOARD_PORT"] = port
+
+        if reload:
+            click.echo("启用插件自动重载")
+            os.environ["ASTRBOT_RELOAD"] = "1"
+
+        lock_file = astrbot_root / "astrbot.lock"
+        lock = FileLock(lock_file, timeout=5)
+        with lock.acquire():
+            asyncio.run(run_astrbot(astrbot_root))
+    except KeyboardInterrupt:
+        click.echo("AstrBot 已关闭...")
+    except Timeout:
+        raise click.ClickException("无法获取锁文件，请检查是否有其他实例正在运行")
+    except Exception as e:
+        raise click.ClickException(f"运行时出现错误: {e}\n{traceback.format_exc()}")

astrbot/cli/utils/__init__.py

@@ -0,0 +1,18 @@
+from .basic import (
+    get_astrbot_root,
+    check_astrbot_root,
+    check_dashboard,
+)
+from .plugin import get_git_repo, manage_plugin, build_plug_list, PluginStatus
+from .version_comparator import VersionComparator
+
+__all__ = [
+    "get_astrbot_root",
+    "check_astrbot_root",
+    "check_dashboard",
+    "get_git_repo",
+    "manage_plugin",
+    "build_plug_list",
+    "VersionComparator",
+    "PluginStatus",
+]

astrbot/cli/utils/basic.py

@@ -0,0 +1,73 @@
+from pathlib import Path
+
+import click
+
+
+def check_astrbot_root(path: str | Path) -> bool:
+    """检查路径是否为 AstrBot 根目录"""
+    if not isinstance(path, Path):
+        path = Path(path)
+    if not path.exists() or not path.is_dir():
+        return False
+    if not (path / ".astrbot").exists():
+        return False
+    return True
+
+
+def get_astrbot_root() -> Path:
+    """获取Astrbot根目录路径"""
+    import os
+
+    # 使用与core应用相同的路径解析逻辑，优先使用ASTRBOT_ROOT环境变量
+    if path := os.environ.get("ASTRBOT_ROOT"):
+        return Path(path)
+    else:
+        return Path.cwd()
+
+
+async def check_dashboard(astrbot_root: Path) -> None:
+    """检查是否安装了dashboard"""
+    from astrbot.core.utils.io import get_dashboard_version, download_dashboard
+    from astrbot.core.config.default import VERSION
+    from .version_comparator import VersionComparator
+
+    try:
+        dashboard_version = await get_dashboard_version()
+        match dashboard_version:
+            case None:
+                click.echo("未安装管理面板")
+                if click.confirm(
+                    "是否安装管理面板？",
+                    default=True,
+                    abort=True,
+                ):
+                    click.echo("正在安装管理面板...")
+                    await download_dashboard(
+                        path="data/dashboard.zip", extract_path=str(astrbot_root)
+                    )
+                    click.echo("管理面板安装完成")
+
+            case str():
+                if VersionComparator.compare_version(VERSION, dashboard_version) <= 0:
+                    click.echo("管理面板已是最新版本")
+                    return
+                else:
+                    try:
+                        version = dashboard_version.split("v")[1]
+                        click.echo(f"管理面板版本: {version}")
+                        await download_dashboard(
+                            path="data/dashboard.zip", extract_path=str(astrbot_root)
+                        )
+                    except Exception as e:
+                        click.echo(f"下载管理面板失败: {e}")
+                        return
+    except FileNotFoundError:
+        click.echo("初始化管理面板目录...")
+        try:
+            await download_dashboard(
+                path=str(astrbot_root / "dashboard.zip"), extract_path=str(astrbot_root)
+            )
+            click.echo("管理面板初始化完成")
+        except Exception as e:
+            click.echo(f"下载管理面板失败: {e}")
+            return

astrbot/cli/utils/plugin.py

@@ -0,0 +1,237 @@
+import shutil
+import tempfile
+
+import httpx
+import yaml
+from enum import Enum
+from io import BytesIO
+from pathlib import Path
+from zipfile import ZipFile
+
+import click
+from .version_comparator import VersionComparator
+
+
+class PluginStatus(str, Enum):
+    INSTALLED = "已安装"
+    NEED_UPDATE = "需更新"
+    NOT_INSTALLED = "未安装"
+    NOT_PUBLISHED = "未发布"
+
+
+def get_git_repo(url: str, target_path: Path, proxy: str | None = None):
+    """从 Git 仓库下载代码并解压到指定路径"""
+    temp_dir = Path(tempfile.mkdtemp())
+    try:
+        # 解析仓库信息
+        repo_namespace = url.split("/")[-2:]
+        author = repo_namespace[0]
+        repo = repo_namespace[1]
+
+        # 尝试获取最新的 release
+        release_url = f"https://api.github.com/repos/{author}/{repo}/releases"
+        try:
+            with httpx.Client(
+                proxy=proxy if proxy else None, follow_redirects=True
+            ) as client:
+                resp = client.get(release_url)
+                resp.raise_for_status()
+                releases = resp.json()
+
+                if releases:
+                    # 使用最新的 release
+                    download_url = releases[0]["zipball_url"]
+                else:
+                    # 没有 release，使用默认分支
+                    click.echo(f"正在从默认分支下载 {author}/{repo}")
+                    download_url = f"https://github.com/{author}/{repo}/archive/refs/heads/master.zip"
+        except Exception as e:
+            click.echo(f"获取 release 信息失败: {e}，将直接使用提供的 URL")
+            download_url = url
+
+        # 应用代理
+        if proxy:
+            download_url = f"{proxy}/{download_url}"
+
+        # 下载并解压
+        with httpx.Client(
+            proxy=proxy if proxy else None, follow_redirects=True
+        ) as client:
+            resp = client.get(download_url)
+            if (
+                resp.status_code == 404
+                and "archive/refs/heads/master.zip" in download_url
+            ):
+                alt_url = download_url.replace("master.zip", "main.zip")
+                click.echo("master 分支不存在，尝试下载 main 分支")
+                resp = client.get(alt_url)
+                resp.raise_for_status()
+            else:
+                resp.raise_for_status()
+            zip_content = BytesIO(resp.content)
+        with ZipFile(zip_content) as z:
+            z.extractall(temp_dir)
+            namelist = z.namelist()
+            root_dir = Path(namelist[0]).parts[0] if namelist else ""
+            if target_path.exists():
+                shutil.rmtree(target_path)
+            shutil.move(temp_dir / root_dir, target_path)
+    finally:
+        if temp_dir.exists():
+            shutil.rmtree(temp_dir, ignore_errors=True)
+
+
+def load_yaml_metadata(plugin_dir: Path) -> dict:
+    """从 metadata.yaml 文件加载插件元数据
+
+    Args:
+        plugin_dir: 插件目录路径
+
+    Returns:
+        dict: 包含元数据的字典，如果读取失败则返回空字典
+    """
+    yaml_path = plugin_dir / "metadata.yaml"
+    if yaml_path.exists():
+        try:
+            return yaml.safe_load(yaml_path.read_text(encoding="utf-8")) or {}
+        except Exception as e:
+            click.echo(f"读取 {yaml_path} 失败: {e}", err=True)
+    return {}
+
+
+def build_plug_list(plugins_dir: Path) -> list:
+    """构建插件列表，包含本地和在线插件信息
+
+    Args:
+        plugins_dir (Path): 插件目录路径
+
+    Returns:
+        list: 包含插件信息的字典列表
+    """
+    # 获取本地插件信息
+    result = []
+    if plugins_dir.exists():
+        for plugin_name in [d.name for d in plugins_dir.glob("*") if d.is_dir()]:
+            plugin_dir = plugins_dir / plugin_name
+
+            # 从 metadata.yaml 加载元数据
+            metadata = load_yaml_metadata(plugin_dir)
+
+            if "desc" not in metadata and "description" in metadata:
+                metadata["desc"] = metadata["description"]
+
+            # 如果成功加载元数据，添加到结果列表
+            if metadata and all(
+                k in metadata for k in ["name", "desc", "version", "author", "repo"]
+            ):
+                result.append(
+                    {
+                        "name": str(metadata.get("name", "")),
+                        "desc": str(metadata.get("desc", "")),
+                        "version": str(metadata.get("version", "")),
+                        "author": str(metadata.get("author", "")),
+                        "repo": str(metadata.get("repo", "")),
+                        "status": PluginStatus.INSTALLED,
+                        "local_path": str(plugin_dir),
+                    }
+                )
+
+    # 获取在线插件列表
+    online_plugins = []
+    try:
+        with httpx.Client() as client:
+            resp = client.get("https://api.soulter.top/astrbot/plugins")
+            resp.raise_for_status()
+            data = resp.json()
+            for plugin_id, plugin_info in data.items():
+                online_plugins.append(
+                    {
+                        "name": str(plugin_id),
+                        "desc": str(plugin_info.get("desc", "")),
+                        "version": str(plugin_info.get("version", "")),
+                        "author": str(plugin_info.get("author", "")),
+                        "repo": str(plugin_info.get("repo", "")),
+                        "status": PluginStatus.NOT_INSTALLED,
+                        "local_path": None,
+                    }
+                )
+    except Exception as e:
+        click.echo(f"获取在线插件列表失败: {e}", err=True)
+
+    # 与在线插件比对，更新状态
+    online_plugin_names = {plugin["name"] for plugin in online_plugins}
+    for local_plugin in result:
+        if local_plugin["name"] in online_plugin_names:
+            # 查找对应的在线插件
+            online_plugin = next(
+                p for p in online_plugins if p["name"] == local_plugin["name"]
+            )
+            if (
+                VersionComparator.compare_version(
+                    local_plugin["version"], online_plugin["version"]
+                )
+                < 0
+            ):
+                local_plugin["status"] = PluginStatus.NEED_UPDATE
+        else:
+            # 本地插件未在线上发布
+            local_plugin["status"] = PluginStatus.NOT_PUBLISHED
+
+    # 添加未安装的在线插件
+    for online_plugin in online_plugins:
+        if not any(plugin["name"] == online_plugin["name"] for plugin in result):
+            result.append(online_plugin)
+
+    return result
+
+
+def manage_plugin(
+    plugin: dict, plugins_dir: Path, is_update: bool = False, proxy: str | None = None
+) -> None:
+    """安装或更新插件
+
+    Args:
+        plugin (dict): 插件信息字典
+        plugins_dir (Path): 插件目录
+        is_update (bool, optional): 是否为更新操作. 默认为 False
+        proxy (str, optional): 代理服务器地址
+    """
+    plugin_name = plugin["name"]
+    repo_url = plugin["repo"]
+
+    # 如果是更新且有本地路径，直接使用本地路径
+    if is_update and plugin.get("local_path"):
+        target_path = Path(plugin["local_path"])
+    else:
+        target_path = plugins_dir / plugin_name
+
+    backup_path = Path(f"{target_path}_backup") if is_update else None
+
+    # 检查插件是否存在
+    if is_update and not target_path.exists():
+        raise click.ClickException(f"插件 {plugin_name} 未安装，无法更新")
+
+    # 备份现有插件
+    if is_update and backup_path.exists():
+        shutil.rmtree(backup_path)
+    if is_update:
+        shutil.copytree(target_path, backup_path)
+
+    try:
+        click.echo(
+            f"正在从 {repo_url} {'更新' if is_update else '下载'}插件 {plugin_name}..."
+        )
+        get_git_repo(repo_url, target_path, proxy)
+
+        # 更新成功，删除备份
+        if is_update and backup_path.exists():
+            shutil.rmtree(backup_path)
+        click.echo(f"插件 {plugin_name} {'更新' if is_update else '安装'}成功")
+    except Exception as e:
+        if target_path.exists():
+            shutil.rmtree(target_path, ignore_errors=True)
+        if is_update and backup_path.exists():
+            shutil.move(backup_path, target_path)
+        raise click.ClickException(
+            f"{'更新' if is_update else '安装'}插件 {plugin_name} 时出错: {e}"
+        )

astrbot/cli/utils/version_comparator.py

@@ -0,0 +1,92 @@
+"""
+拷贝自 astrbot.core.utils.version_comparator
+"""
+
+import re
+
+
+class VersionComparator:
+    @staticmethod
+    def compare_version(v1: str, v2: str) -> int:
+        """根据 Semver 语义版本规范来比较版本号的大小。支持不仅局限于 3 个数字的版本号，并处理预发布标签。
+
+        参考: https://semver.org/lang/zh-CN/
+
+        返回 1 表示 v1 > v2，返回 -1 表示 v1 < v2，返回 0 表示 v1 = v2。
+        """
+        v1 = v1.lower().replace("v", "")
+        v2 = v2.lower().replace("v", "")
+
+        def split_version(version):
+            match = re.match(
+                r"^([0-9]+(?:\.[0-9]+)*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+(.+))?$",
+                version,
+            )
+            if not match:
+                return [], None
+            major_minor_patch = match.group(1).split(".")
+            prerelease = match.group(2)
+            # buildmetadata = match.group(3) # 构建元数据在比较时忽略
+            parts = [int(x) for x in major_minor_patch]
+            prerelease = VersionComparator._split_prerelease(prerelease)
+            return parts, prerelease
+
+        v1_parts, v1_prerelease = split_version(v1)
+        v2_parts, v2_prerelease = split_version(v2)
+
+        # 比较数字部分
+        length = max(len(v1_parts), len(v2_parts))
+        v1_parts.extend([0] * (length - len(v1_parts)))
+        v2_parts.extend([0] * (length - len(v2_parts)))
+
+        for i in range(length):
+            if v1_parts[i] > v2_parts[i]:
+                return 1
+            elif v1_parts[i] < v2_parts[i]:
+                return -1
+
+        # 比较预发布标签
+        if v1_prerelease is None and v2_prerelease is not None:
+            return 1  # 没有预发布标签的版本高于有预发布标签的版本
+        elif v1_prerelease is not None and v2_prerelease is None:
+            return -1  # 有预发布标签的版本低于没有预发布标签的版本
+        elif v1_prerelease is not None and v2_prerelease is not None:
+            len_pre = max(len(v1_prerelease), len(v2_prerelease))
+            for i in range(len_pre):
+                p1 = v1_prerelease[i] if i < len(v1_prerelease) else None
+                p2 = v2_prerelease[i] if i < len(v2_prerelease) else None
+
+                if p1 is None and p2 is not None:
+                    return -1
+                elif p1 is not None and p2 is None:
+                    return 1
+                elif isinstance(p1, int) and isinstance(p2, str):
+                    return -1
+                elif isinstance(p1, str) and isinstance(p2, int):
+                    return 1
+                elif isinstance(p1, int) and isinstance(p2, int):
+                    if p1 > p2:
+                        return 1
+                    elif p1 < p2:
+                        return -1
+                elif isinstance(p1, str) and isinstance(p2, str):
+                    if p1 > p2:
+                        return 1
+                    elif p1 < p2:
+                        return -1
+            return 0  # 预发布标签完全相同
+
+        return 0  # 数字部分和预发布标签都相同
+
+    @staticmethod
+    def _split_prerelease(prerelease):
+        if not prerelease:
+            return None
+        parts = prerelease.split(".")
+        result = []
+        for part in parts:
+            if part.isdigit():
+                result.append(int(part))
+            else:
+                result.append(part)
+        return result

astrbot/core/__init__.py

@@ -7,20 +7,24 @@ from astrbot.core.utils.pip_installer import PipInstaller
 from astrbot.core.db.sqlite import SQLiteDatabase
 from astrbot.core.config.default import DB_PATH
 from astrbot.core.config import AstrBotConfig
+from astrbot.core.file_token_service import FileTokenService
+from .utils.astrbot_path import get_astrbot_data_path
 
-os.makedirs("data", exist_ok=True)
+# 初始化数据存储文件夹
+os.makedirs(get_astrbot_data_path(), exist_ok=True)
+
+DEMO_MODE = os.getenv("DEMO_MODE", False)
 
 astrbot_config = AstrBotConfig()
 t2i_base_url = astrbot_config.get("t2i_endpoint", "https://t2i.soulter.top/text2img")
 html_renderer = HtmlRenderer(t2i_base_url)
 logger = LogManager.GetLogger(log_name="astrbot")
-
-if os.environ.get("TESTING", ""):
-    logger.setLevel("DEBUG")
-
 db_helper = SQLiteDatabase(DB_PATH)
-sp = SharedPreferences()  # 简单的偏好设置存储
-pip_installer = PipInstaller(astrbot_config.get("pip_install_arg", ""))
-web_chat_queue = asyncio.Queue(maxsize=32)
-web_chat_back_queue = asyncio.Queue(maxsize=32)
-WEBUI_SK = "Advanced_System_for_Text_Response_and_Bot_Operations_Tool"
+# 简单的偏好设置存储, 这里后续应该存储到数据库中, 一些部分可以存储到配置中
+sp = SharedPreferences()
+# 文件令牌服务
+file_token_service = FileTokenService()
+pip_installer = PipInstaller(
+    astrbot_config.get("pip_install_arg", ""),
+    astrbot_config.get("pypi_index_url", None),
+)

astrbot/core/config/astrbot_config.py

@@ -4,8 +4,9 @@ import logging
 import enum
 from .default import DEFAULT_CONFIG, DEFAULT_VALUE_MAP
 from typing import Dict
+from astrbot.core.utils.astrbot_path import get_astrbot_data_path
 
-ASTRBOT_CONFIG_PATH = "data/cmd_config.json"
+ASTRBOT_CONFIG_PATH = os.path.join(get_astrbot_data_path(), "cmd_config.json")
 logger = logging.getLogger("astrbot")
 
 
@@ -42,11 +43,10 @@ class AstrBotConfig(dict):
             """不存在时载入默认配置"""
             with open(config_path, "w", encoding="utf-8-sig") as f:
                 json.dump(default_config, f, indent=4, ensure_ascii=False)
+                object.__setattr__(self, "first_deploy", True)  # 标记第一次部署
 
         with open(config_path, "r", encoding="utf-8-sig") as f:
             conf_str = f.read()
-            if conf_str.startswith("/ufeff"):  # remove BOM
-                conf_str = conf_str.encode("utf8")[3:].decode("utf8")
             conf = json.loads(conf_str)
 
         # 检查配置完整性，并插入
@@ -83,23 +83,61 @@ class AstrBotConfig(dict):
         return conf
 
     def check_config_integrity(self, refer_conf: Dict, conf: Dict, path=""):
-        """检查配置完整性，如果有新的配置项则返回 True"""
+        """检查配置完整性，如果有新的配置项或顺序不一致则返回 True"""
         has_new = False
+
+        # 创建一个新的有序字典以保持参考配置的顺序
+        new_conf = {}
+
+        # 先按照参考配置的顺序添加配置项
         for key, value in refer_conf.items():
             if key not in conf:
-                # logger.info(f"检查到配置项 {path + "." + key if path else key} 不存在，已插入默认值 {value}")
+                # 配置项不存在，插入默认值
                 path_ = path + "." + key if path else key
                 logger.info(f"检查到配置项 {path_} 不存在，已插入默认值 {value}")
-                conf[key] = value
+                new_conf[key] = value
                 has_new = True
             else:
                 if conf[key] is None:
-                    conf[key] = value
+                    # 配置项为 None，使用默认值
+                    new_conf[key] = value
                     has_new = True
                 elif isinstance(value, dict):
-                    has_new |= self.check_config_integrity(
-                        value, conf[key], path + "." + key if path else key
-                    )
+                    # 递归检查子配置项
+                    if not isinstance(conf[key], dict):
+                        # 类型不匹配，使用默认值
+                        new_conf[key] = value
+                        has_new = True
+                    else:
+                        # 递归检查并同步顺序
+                        child_has_new = self.check_config_integrity(
+                            value, conf[key], path + "." + key if path else key
+                        )
+                        new_conf[key] = conf[key]
+                        has_new |= child_has_new
+                else:
+                    # 直接使用现有配置
+                    new_conf[key] = conf[key]
+
+        # 检查是否存在参考配置中没有的配置项
+        for key in list(conf.keys()):
+            if key not in refer_conf:
+                path_ = path + "." + key if path else key
+                logger.info(f"检查到配置项 {path_} 不存在，将从当前配置中删除")
+                has_new = True
+
+        # 顺序不一致也算作变更
+        if list(conf.keys()) != list(new_conf.keys()):
+            if path:
+                logger.info(f"检查到配置项 {path} 的子项顺序不一致，已重新排序")
+            else:
+                logger.info("检查到配置项顺序不一致，已重新排序")
+            has_new = True
+
+        # 更新原始配置
+        conf.clear()
+        conf.update(new_conf)
+
         return has_new
 
     def save_config(self, replace_config: Dict = None):

astrbot/core/conversation_mgr.py

@@ -1,3 +1,10 @@
+"""
+AstrBot 会话-对话管理器, 维护两个本地存储, 其中一个是 json 格式的shared_preferences, 另外一个是数据库
+
+在 AstrBot 中, 会话和对话是独立的, 会话用于标记对话窗口, 例如群聊"123456789"可以建立一个会话,
+在一个会话中可以建立多个对话, 并且支持对话的切换和删除
+"""
+
 import uuid
 import json
 import asyncio
@@ -11,24 +18,34 @@ class ConversationManager:
     """负责管理会话与 LLM 的对话，某个会话当前正在用哪个对话。"""
 
     def __init__(self, db_helper: BaseDatabase):
+        # session_conversations 字典记录会话ID-对话ID 映射关系
         self.session_conversations: Dict[str, str] = sp.get("session_conversation", {})
         self.db = db_helper
         self.save_interval = 60  # 每 60 秒保存一次
         self._start_periodic_save()
 
     def _start_periodic_save(self):
+        """启动定时保存任务"""
         asyncio.create_task(self._periodic_save())
 
     async def _periodic_save(self):
+        """定时保存会话对话映射关系到存储中"""
         while True:
             await asyncio.sleep(self.save_interval)
             self._save_to_storage()
 
     def _save_to_storage(self):
+        """保存会话对话映射关系到存储中"""
         sp.put("session_conversation", self.session_conversations)
 
     async def new_conversation(self, unified_msg_origin: str) -> str:
-        """新建对话，并将当前会话的对话转移到新对话"""
+        """新建对话，并将当前会话的对话转移到新对话
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+        Returns:
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+        """
         conversation_id = str(uuid.uuid4())
         self.db.new_conversation(user_id=unified_msg_origin, cid=conversation_id)
         self.session_conversations[unified_msg_origin] = conversation_id
@@ -36,14 +53,24 @@ class ConversationManager:
         return conversation_id
 
     async def switch_conversation(self, unified_msg_origin: str, conversation_id: str):
-        """切换会话的对话"""
+        """切换会话的对话
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+        """
         self.session_conversations[unified_msg_origin] = conversation_id
         sp.put("session_conversation", self.session_conversations)
 
     async def delete_conversation(
         self, unified_msg_origin: str, conversation_id: str = None
     ):
-        """删除会话的对话，当 conversation_id 为 None 时删除会话当前的对话"""
+        """删除会话的对话，当 conversation_id 为 None 时删除会话当前的对话
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+        """
         conversation_id = self.session_conversations.get(unified_msg_origin)
         if conversation_id:
             self.db.delete_conversation(user_id=unified_msg_origin, cid=conversation_id)
@@ -51,23 +78,58 @@ class ConversationManager:
             sp.put("session_conversation", self.session_conversations)
 
     async def get_curr_conversation_id(self, unified_msg_origin: str) -> str:
-        """获取会话当前的对话 ID"""
+        """获取会话当前的对话 ID
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+        Returns:
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+        """
         return self.session_conversations.get(unified_msg_origin, None)
 
     async def get_conversation(
-        self, unified_msg_origin: str, conversation_id: str
+        self,
+        unified_msg_origin: str,
+        conversation_id: str,
+        create_if_not_exists: bool = False,
     ) -> Conversation:
-        """获取会话的对话"""
+        """获取会话的对话
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+        Returns:
+            conversation (Conversation): 对话对象
+        """
+        conv = self.db.get_conversation_by_user_id(unified_msg_origin, conversation_id)
+        if not conv and create_if_not_exists:
+            # 如果对话不存在且需要创建，则新建一个对话
+            conversation_id = await self.new_conversation(unified_msg_origin)
+            return self.db.get_conversation_by_user_id(
+                unified_msg_origin, conversation_id
+            )
         return self.db.get_conversation_by_user_id(unified_msg_origin, conversation_id)
 
     async def get_conversations(self, unified_msg_origin: str) -> List[Conversation]:
-        """获取会话的所有对话"""
+        """获取会话的所有对话
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+        Returns:
+            conversations (List[Conversation]): 对话对象列表
+        """
         return self.db.get_conversations(unified_msg_origin)
 
     async def update_conversation(
         self, unified_msg_origin: str, conversation_id: str, history: List[Dict]
     ):
-        """更新会话的对话"""
+        """更新会话的对话
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+            history (List[Dict]): 对话历史记录, 是一个字典列表, 每个字典包含 role 和 content 字段
+        """
         if conversation_id:
             self.db.update_conversation(
                 user_id=unified_msg_origin,
@@ -76,7 +138,12 @@ class ConversationManager:
             )
 
     async def update_conversation_title(self, unified_msg_origin: str, title: str):
-        """更新会话的对话标题"""
+        """更新会话的对话标题
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            title (str): 对话标题
+        """
         conversation_id = self.session_conversations.get(unified_msg_origin)
         if conversation_id:
             self.db.update_conversation_title(
@@ -86,7 +153,12 @@ class ConversationManager:
     async def update_conversation_persona_id(
         self, unified_msg_origin: str, persona_id: str
     ):
-        """更新会话的对话 Persona ID"""
+        """更新会话的对话 Persona ID
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            persona_id (str): 对话 Persona ID
+        """
         conversation_id = self.session_conversations.get(unified_msg_origin)
         if conversation_id:
             self.db.update_conversation_persona_id(
@@ -96,6 +168,14 @@ class ConversationManager:
     async def get_human_readable_context(
         self, unified_msg_origin, conversation_id, page=1, page_size=10
     ):
+        """获取人类可读的上下文
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+            page (int): 页码
+            page_size (int): 每页大小
+        """
         conversation = await self.get_conversation(unified_msg_origin, conversation_id)
         history = json.loads(conversation.history)
 
@@ -105,7 +185,15 @@ class ConversationManager:
             if record["role"] == "user":
                 temp_contexts.append(f"User: {record['content']}")
             elif record["role"] == "assistant":
-                temp_contexts.append(f"Assistant: {record['content']}")
+                if "content" in record and record["content"]:
+                    temp_contexts.append(f"Assistant: {record['content']}")
+                elif "tool_calls" in record:
+                    tool_calls_str = json.dumps(
+                        record["tool_calls"], ensure_ascii=False
+                    )
+                    temp_contexts.append(f"Assistant: [函数调用] {tool_calls_str}")
+                else:
+                    temp_contexts.append("Assistant: [未知的内容]")
                 contexts.insert(0, temp_contexts)
                 temp_contexts = []
 

astrbot/core/core_lifecycle.py

@@ -1,3 +1,14 @@
+"""
+Astrbot 核心生命周期管理类, 负责管理 AstrBot 的启动、停止、重启等操作。
+该类负责初始化各个组件, 包括 ProviderManager、PlatformManager、ConversationManager、PluginManager、PipelineScheduler、EventBus等。
+该类还负责加载和执行插件, 以及处理事件总线的分发。
+
+工作流程:
+1. 初始化所有组件
+2. 启动事件总线和任务, 所有任务都在这里运行
+3. 执行启动完成事件钩子
+"""
+
 import traceback
 import asyncio
 import time
@@ -17,39 +28,57 @@ from astrbot.core.db import BaseDatabase
 from astrbot.core.updator import AstrBotUpdator
 from astrbot.core import logger
 from astrbot.core.config.default import VERSION
-from astrbot.core.rag.knowledge_db_mgr import KnowledgeDBManager
 from astrbot.core.conversation_mgr import ConversationManager
 from astrbot.core.star.star_handler import star_handlers_registry, EventType
 from astrbot.core.star.star_handler import star_map
 
 
 class AstrBotCoreLifecycle:
-    def __init__(self, log_broker: LogBroker, db: BaseDatabase):
-        self.log_broker = log_broker
-        self.astrbot_config = astrbot_config
-        self.db = db
+    """
+    AstrBot 核心生命周期管理类, 负责管理 AstrBot 的启动、停止、重启等操作。
+    该类负责初始化各个组件, 包括 ProviderManager、PlatformManager、ConversationManager、PluginManager、PipelineScheduler、
+    EventBus 等。
+    该类还负责加载和执行插件, 以及处理事件总线的分发。
+    """
 
-        os.environ["https_proxy"] = self.astrbot_config["http_proxy"]
-        os.environ["http_proxy"] = self.astrbot_config["http_proxy"]
+    def __init__(self, log_broker: LogBroker, db: BaseDatabase):
+        self.log_broker = log_broker  # 初始化日志代理
+        self.astrbot_config = astrbot_config  # 初始化配置
+        self.db = db  # 初始化数据库
+
+        # 设置代理
+        if self.astrbot_config.get("http_proxy", ""):
+            os.environ["https_proxy"] = self.astrbot_config["http_proxy"]
+            os.environ["http_proxy"] = self.astrbot_config["http_proxy"]
+        if proxy := os.environ.get("https_proxy"):
+            logger.debug(f"Using proxy: {proxy}")
         os.environ["no_proxy"] = "localhost"
 
     async def initialize(self):
+        """
+        初始化 AstrBot 核心生命周期管理类, 负责初始化各个组件, 包括 ProviderManager、PlatformManager、ConversationManager、PluginManager、PipelineScheduler、EventBus、AstrBotUpdator等。
+        """
+
+        # 初始化日志代理
         logger.info("AstrBot v" + VERSION)
         if os.environ.get("TESTING", ""):
-            logger.setLevel("DEBUG")
+            logger.setLevel("DEBUG")  # 测试模式下设置日志级别为 DEBUG
         else:
-            logger.setLevel(self.astrbot_config["log_level"])
-        self.event_queue = Queue()
-        self.event_queue.closed = False
+            logger.setLevel(self.astrbot_config["log_level"])  # 设置日志级别
 
+        # 初始化事件队列
+        self.event_queue = Queue()
+
+        # 初始化供应商管理器
         self.provider_manager = ProviderManager(self.astrbot_config, self.db)
 
+        # 初始化平台管理器
         self.platform_manager = PlatformManager(self.astrbot_config, self.event_queue)
 
-        self.knowledge_db_manager = KnowledgeDBManager(self.astrbot_config)
-
+        # 初始化对话管理器
         self.conversation_manager = ConversationManager(self.db)
 
+        # 初始化提供给插件的上下文
         self.star_context = Context(
             self.event_queue,
             self.astrbot_config,
@@ -57,35 +86,51 @@ class AstrBotCoreLifecycle:
             self.provider_manager,
             self.platform_manager,
             self.conversation_manager,
-            self.knowledge_db_manager,
         )
+
+        # 初始化插件管理器
         self.plugin_manager = PluginManager(self.star_context, self.astrbot_config)
 
+        # 扫描、注册插件、实例化插件类
         await self.plugin_manager.reload()
-        """扫描、注册插件、实例化插件类"""
 
+        # 根据配置实例化各个 Provider
         await self.provider_manager.initialize()
-        """根据配置实例化各个 Provider"""
 
+        # 初始化消息事件流水线调度器
         self.pipeline_scheduler = PipelineScheduler(
             PipelineContext(self.astrbot_config, self.plugin_manager)
         )
         await self.pipeline_scheduler.initialize()
-        """初始化消息事件流水线调度器"""
 
-        self.astrbot_updator = AstrBotUpdator(self.astrbot_config["plugin_repo_mirror"])
+        # 初始化更新器
+        self.astrbot_updator = AstrBotUpdator()
+
+        # 初始化事件总线
         self.event_bus = EventBus(self.event_queue, self.pipeline_scheduler)
+
+        # 记录启动时间
         self.start_time = int(time.time())
+
+        # 初始化当前任务列表
         self.curr_tasks: List[asyncio.Task] = []
 
+        # 根据配置实例化各个平台适配器
         await self.platform_manager.initialize()
-        """根据配置实例化各个平台适配器"""
+
+        # 初始化关闭控制面板的事件
+        self.dashboard_shutdown_event = asyncio.Event()
 
     def _load(self):
+        """加载事件总线和任务并初始化"""
+
+        # 创建一个异步任务来执行事件总线的 dispatch() 方法
+        # dispatch是一个无限循环的协程, 从事件队列中获取事件并处理
         event_bus_task = asyncio.create_task(
             self.event_bus.dispatch(), name="event_bus"
         )
 
+        # 把插件中注册的所有协程函数注册到事件总线中并执行
         extra_tasks = []
         for task in self.star_context._register_tasks:
             extra_tasks.append(asyncio.create_task(task, name=task.__name__))
@@ -99,17 +144,24 @@ class AstrBotCoreLifecycle:
         self.start_time = int(time.time())
 
     async def _task_wrapper(self, task: asyncio.Task):
+        """异步任务包装器, 用于处理异步任务执行中出现的各种异常
+
+        Args:
+            task (asyncio.Task): 要执行的异步任务
+        """
         try:
             await task
         except asyncio.CancelledError:
-            pass
+            pass  # 任务被取消, 静默处理
         except Exception as e:
+            # 获取完整的异常堆栈信息, 按行分割并记录到日志中
             logger.error(f"------- 任务 {task.get_name()} 发生错误: {e}")
             for line in traceback.format_exc().split("\n"):
                 logger.error(f"|    {line}")
             logger.error("-------")
 
     async def start(self):
+        """启动 AstrBot 核心生命周期管理类, 用load加载事件总线和任务并初始化, 执行启动完成事件钩子"""
         self._load()
         logger.info("AstrBot 启动完成。")
 
@@ -126,15 +178,29 @@ class AstrBotCoreLifecycle:
             except BaseException:
                 logger.error(traceback.format_exc())
 
+        # 同时运行curr_tasks中的所有任务
         await asyncio.gather(*self.curr_tasks, return_exceptions=True)
 
     async def stop(self):
-        self.event_queue.closed = True
+        """停止 AstrBot 核心生命周期管理类, 取消所有当前任务并终止各个管理器"""
+        # 请求停止所有正在运行的异步任务
         for task in self.curr_tasks:
             task.cancel()
 
-        await self.provider_manager.terminate()
+        for plugin in self.plugin_manager.context.get_all_stars():
+            try:
+                await self.plugin_manager._terminate_plugin(plugin)
+            except Exception as e:
+                logger.warning(traceback.format_exc())
+                logger.warning(
+                    f"插件 {plugin.name} 未被正常终止 {e!s}, 可能会导致资源泄露等问题。"
+                )
 
+        await self.provider_manager.terminate()
+        await self.platform_manager.terminate()
+        self.dashboard_shutdown_event.set()
+
+        # 再次遍历curr_tasks等待每个任务真正结束
         for task in self.curr_tasks:
             try:
                 await task
@@ -143,13 +209,17 @@ class AstrBotCoreLifecycle:
             except Exception as e:
                 logger.error(f"任务 {task.get_name()} 发生错误: {e}")
 
-    def restart(self):
-        self.event_queue.closed = True
+    async def restart(self):
+        """重启 AstrBot 核心生命周期管理类, 终止各个管理器并重新加载平台实例"""
+        await self.provider_manager.terminate()
+        await self.platform_manager.terminate()
+        self.dashboard_shutdown_event.set()
         threading.Thread(
             target=self.astrbot_updator._reboot, name="restart", daemon=True
         ).start()
 
     def load_platform(self) -> List[asyncio.Task]:
+        """加载平台实例并返回所有平台实例的异步任务列表"""
         tasks = []
         platform_insts = self.platform_manager.get_insts()
         for platform_inst in platform_insts:

astrbot/core/db/__init__.py

@@ -1,6 +1,6 @@
 import abc
 from dataclasses import dataclass
-from typing import List
+from typing import List, Dict, Any, Tuple
 from astrbot.core.db.po import Stats, LLMHistory, ATRIVision, Conversation
 
 
@@ -117,3 +117,45 @@ class BaseDatabase(abc.ABC):
     def update_conversation_persona_id(self, user_id: str, cid: str, persona_id: str):
         """更新 Conversation Persona ID"""
         raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_all_conversations(
+        self, page: int = 1, page_size: int = 20
+    ) -> Tuple[List[Dict[str, Any]], int]:
+        """获取所有对话，支持分页
+
+        Args:
+            page: 页码，从1开始
+            page_size: 每页数量
+
+        Returns:
+            Tuple[List[Dict[str, Any]], int]: 返回一个元组，包含对话列表和总对话数
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_filtered_conversations(
+        self,
+        page: int = 1,
+        page_size: int = 20,
+        platforms: List[str] = None,
+        message_types: List[str] = None,
+        search_query: str = None,
+        exclude_ids: List[str] = None,
+        exclude_platforms: List[str] = None,
+    ) -> Tuple[List[Dict[str, Any]], int]:
+        """获取筛选后的对话列表
+
+        Args:
+            page: 页码
+            page_size: 每页数量
+            platforms: 平台筛选列表
+            message_types: 消息类型筛选列表
+            search_query: 搜索关键词
+            exclude_ids: 排除的用户ID列表
+            exclude_platforms: 排除的平台列表
+
+        Returns:
+            Tuple[List[Dict[str, Any]], int]: 返回一个元组，包含对话列表和总对话数
+        """
+        raise NotImplementedError

astrbot/core/db/po.py

@@ -6,6 +6,8 @@ from typing import List
 
 @dataclass
 class Platform:
+    """平台使用统计数据"""
+
     name: str
     count: int
     timestamp: int
@@ -13,6 +15,8 @@ class Platform:
 
 @dataclass
 class Provider:
+    """供应商使用统计数据"""
+
     name: str
     count: int
     timestamp: int
@@ -20,6 +24,8 @@ class Provider:
 
 @dataclass
 class Plugin:
+    """插件使用统计数据"""
+
     name: str
     count: int
     timestamp: int
@@ -27,6 +33,8 @@ class Plugin:
 
 @dataclass
 class Command:
+    """命令使用统计数据"""
+
     name: str
     count: int
     timestamp: int

astrbot/core/db/sqlite.py

@@ -3,7 +3,7 @@ import os
 import time
 from astrbot.core.db.po import Platform, Stats, LLMHistory, ATRIVision, Conversation
 from . import BaseDatabase
-from typing import Tuple
+from typing import Tuple, List, Dict, Any
 
 
 class SQLiteDatabase(BaseDatabase):
@@ -11,7 +11,9 @@ class SQLiteDatabase(BaseDatabase):
         super().__init__()
         self.db_path = db_path
 
-        with open(os.path.dirname(__file__) + "/sqlite_init.sql", "r") as f:
+        with open(
+            os.path.dirname(__file__) + "/sqlite_init.sql", "r", encoding="utf-8"
+        ) as f:
             sql = f.read()
 
         # 初始化数据库
@@ -128,24 +130,23 @@ class SQLiteDatabase(BaseDatabase):
         except sqlite3.ProgrammingError:
             c = self._get_conn(self.db_path).cursor()
 
-        where_clause = ""
-        if session_id or provider_type:
-            where_clause += " WHERE "
-            has = False
-            if session_id:
-                where_clause += f"session_id = '{session_id}'"
-                has = True
-            if provider_type:
-                if has:
-                    where_clause += " AND "
-                where_clause += f"provider_type = '{provider_type}'"
+        conditions = []
+        params = []
+
+        if session_id:
+            conditions.append("session_id = ?")
+            params.append(session_id)
+
+        if provider_type:
+            conditions.append("provider_type = ?")
+            params.append(provider_type)
+
+        sql = "SELECT * FROM llm_history"
+        if conditions:
+            sql += " WHERE " + " AND ".join(conditions)
+
+        c.execute(sql, params)
 
-        c.execute(
-            """
-            SELECT * FROM llm_history
-            """
-            + where_clause
-        )
         res = c.fetchall()
         histories = []
         for row in res:
@@ -389,3 +390,178 @@ class SQLiteDatabase(BaseDatabase):
         if res:
             return ATRIVision(*res)
         return None
+
+    def get_all_conversations(
+        self, page: int = 1, page_size: int = 20
+    ) -> Tuple[List[Dict[str, Any]], int]:
+        """获取所有对话，支持分页，按更新时间降序排序"""
+        try:
+            c = self.conn.cursor()
+        except sqlite3.ProgrammingError:
+            c = self._get_conn(self.db_path).cursor()
+
+        try:
+            # 获取总记录数
+            c.execute("""
+                SELECT COUNT(*) FROM webchat_conversation
+            """)
+            total_count = c.fetchone()[0]
+
+            # 计算偏移量
+            offset = (page - 1) * page_size
+
+            # 获取分页数据，按更新时间降序排序
+            c.execute(
+                """
+                SELECT user_id, cid, created_at, updated_at, title, persona_id
+                FROM webchat_conversation
+                ORDER BY updated_at DESC
+                LIMIT ? OFFSET ?
+            """,
+                (page_size, offset),
+            )
+
+            rows = c.fetchall()
+
+            conversations = []
+
+            for row in rows:
+                user_id, cid, created_at, updated_at, title, persona_id = row
+                # 确保 cid 是字符串类型且至少有8个字符，否则使用一个默认值
+                safe_cid = str(cid) if cid else "unknown"
+                display_cid = safe_cid[:8] if len(safe_cid) >= 8 else safe_cid
+
+                conversations.append(
+                    {
+                        "user_id": user_id or "",
+                        "cid": safe_cid,
+                        "title": title or f"对话 {display_cid}",
+                        "persona_id": persona_id or "",
+                        "created_at": created_at or 0,
+                        "updated_at": updated_at or 0,
+                    }
+                )
+
+            return conversations, total_count
+
+        except Exception as _:
+            # 返回空列表和0，确保即使出错也有有效的返回值
+            return [], 0
+        finally:
+            c.close()
+
+    def get_filtered_conversations(
+        self,
+        page: int = 1,
+        page_size: int = 20,
+        platforms: List[str] = None,
+        message_types: List[str] = None,
+        search_query: str = None,
+        exclude_ids: List[str] = None,
+        exclude_platforms: List[str] = None,
+    ) -> Tuple[List[Dict[str, Any]], int]:
+        """获取筛选后的对话列表"""
+        try:
+            c = self.conn.cursor()
+        except sqlite3.ProgrammingError:
+            c = self._get_conn(self.db_path).cursor()
+
+        try:
+            # 构建查询条件
+            where_clauses = []
+            params = []
+
+            # 平台筛选
+            if platforms and len(platforms) > 0:
+                platform_conditions = []
+                for platform in platforms:
+                    platform_conditions.append("user_id LIKE ?")
+                    params.append(f"{platform}:%")
+
+                if platform_conditions:
+                    where_clauses.append(f"({' OR '.join(platform_conditions)})")
+
+            # 消息类型筛选
+            if message_types and len(message_types) > 0:
+                message_type_conditions = []
+                for msg_type in message_types:
+                    message_type_conditions.append("user_id LIKE ?")
+                    params.append(f"%:{msg_type}:%")
+
+                if message_type_conditions:
+                    where_clauses.append(f"({' OR '.join(message_type_conditions)})")
+
+            # 搜索关键词
+            if search_query:
+                search_query = search_query.encode("unicode_escape").decode("utf-8")
+                where_clauses.append(
+                    "(title LIKE ? OR user_id LIKE ? OR cid LIKE ? OR history LIKE ?)"
+                )
+                search_param = f"%{search_query}%"
+                params.extend([search_param, search_param, search_param, search_param])
+
+            # 排除特定用户ID
+            if exclude_ids and len(exclude_ids) > 0:
+                for exclude_id in exclude_ids:
+                    where_clauses.append("user_id NOT LIKE ?")
+                    params.append(f"{exclude_id}%")
+
+            # 排除特定平台
+            if exclude_platforms and len(exclude_platforms) > 0:
+                for exclude_platform in exclude_platforms:
+                    where_clauses.append("user_id NOT LIKE ?")
+                    params.append(f"{exclude_platform}:%")
+
+            # 构建完整的 WHERE 子句
+            where_sql = " WHERE " + " AND ".join(where_clauses) if where_clauses else ""
+
+            # 构建计数查询
+            count_sql = f"SELECT COUNT(*) FROM webchat_conversation{where_sql}"
+
+            # 获取总记录数
+            c.execute(count_sql, params)
+            total_count = c.fetchone()[0]
+
+            # 计算偏移量
+            offset = (page - 1) * page_size
+
+            # 构建分页数据查询
+            data_sql = f"""
+                SELECT user_id, cid, created_at, updated_at, title, persona_id
+                FROM webchat_conversation
+                {where_sql}
+                ORDER BY updated_at DESC
+                LIMIT ? OFFSET ?
+            """
+            query_params = params + [page_size, offset]
+
+            # 获取分页数据
+            c.execute(data_sql, query_params)
+            rows = c.fetchall()
+
+            conversations = []
+
+            for row in rows:
+                user_id, cid, created_at, updated_at, title, persona_id = row
+                # 确保 cid 是字符串类型，否则使用一个默认值
+                safe_cid = str(cid) if cid else "unknown"
+                display_cid = safe_cid[:8] if len(safe_cid) >= 8 else safe_cid
+
+                conversations.append(
+                    {
+                        "user_id": user_id or "",
+                        "cid": safe_cid,
+                        "title": title or f"对话 {display_cid}",
+                        "persona_id": persona_id or "",
+                        "created_at": created_at or 0,
+                        "updated_at": updated_at or 0,
+                    }
+                )
+
+            return conversations, total_count
+
+        except Exception as _:
+            # 返回空列表和0，确保即使出错也有有效的返回值
+            return [], 0
+        finally:
+            c.close()

astrbot/core/db/sqlite_init.sql

@@ -38,11 +38,13 @@ CREATE TABLE IF NOT EXISTS atri_vision(
 );
 
 CREATE TABLE IF NOT EXISTS webchat_conversation(
-    user_id TEXT,
-    cid TEXT,
+    user_id TEXT, -- 会话 id
+    cid TEXT, -- 对话 id
     history TEXT,
     created_at INTEGER,
     updated_at INTEGER,
     title TEXT,
     persona_id TEXT
-);
+);
+
+PRAGMA encoding = 'UTF-8';

astrbot/core/db/vec_db/base.py

@@ -0,0 +1,46 @@
+import abc
+from dataclasses import dataclass
+
+
+@dataclass
+class Result:
+    similarity: float
+    data: dict
+
+
+class BaseVecDB:
+    async def initialize(self):
+        """
+        初始化向量数据库
+        """
+        pass
+
+    @abc.abstractmethod
+    async def insert(self, content: str, metadata: dict = None, id: str = None) -> int:
+        """
+        插入一条文本和其对应向量，自动生成 ID 并保持一致性。
+        """
+        ...
+
+    @abc.abstractmethod
+    async def retrieve(self, query: str, top_k: int = 5) -> list[Result]:
+        """
+        搜索最相似的文档。
+        Args:
+            query (str): 查询文本
+            top_k (int): 返回的最相似文档的数量
+        Returns:
+            List[Result]: 查询结果
+        """
+        ...
+
+    @abc.abstractmethod
+    async def delete(self, doc_id: str) -> bool:
+        """
+        删除指定文档。
+        Args:
+            doc_id (str): 要删除的文档 ID
+        Returns:
+            bool: 删除是否成功
+        """
+        ...

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

@@ -0,0 +1,3 @@
+from .vec_db import FaissVecDB
+
+__all__ = ["FaissVecDB"]

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

@@ -0,0 +1,121 @@
+import aiosqlite
+import os
+
+
+class DocumentStorage:
+    def __init__(self, db_path: str):
+        self.db_path = db_path
+        self.connection = None
+        self.sqlite_init_path = os.path.join(
+            os.path.dirname(__file__), "sqlite_init.sql"
+        )
+
+    async def initialize(self):
+        """Initialize the SQLite database and create the documents table if it doesn't exist."""
+        if not os.path.exists(self.db_path):
+            await self.connect()
+            async with self.connection.cursor() as cursor:
+                with open(self.sqlite_init_path, "r", encoding="utf-8") as f:
+                    sql_script = f.read()
+                await cursor.executescript(sql_script)
+            await self.connection.commit()
+        else:
+            await self.connect()
+
+    async def connect(self):
+        """Connect to the SQLite database."""
+        self.connection = await aiosqlite.connect(self.db_path)
+
+    async def get_documents(self, metadata_filters: dict, ids: list = None):
+        """Retrieve documents by metadata filters and ids.
+
+        Args:
+            metadata_filters (dict): The metadata filters to apply.
+
+        Returns:
+            list: The list of document IDs(primary key, not doc_id) that match the filters.
+        """
+        # metadata filter -> SQL WHERE clause
+        where_clauses = []
+        values = []
+        for key, val in metadata_filters.items():
+            where_clauses.append(f"json_extract(metadata, '$.{key}') = ?")
+            values.append(val)
+        if ids is not None and len(ids) > 0:
+            ids = [str(i) for i in ids if i != -1]
+            where_clauses.append("id IN ({})".format(",".join("?" * len(ids))))
+            values.extend(ids)
+        where_sql = " AND ".join(where_clauses) or "1=1"
+
+        result = []
+        async with self.connection.cursor() as cursor:
+            sql = "SELECT * FROM documents WHERE " + where_sql
+            await cursor.execute(sql, values)
+            for row in await cursor.fetchall():
+                result.append(await self.tuple_to_dict(row))
+        return result
+
+    async def get_document_by_doc_id(self, doc_id: str):
+        """Retrieve a document by its doc_id.
+
+        Args:
+            doc_id (str): The doc_id of the document to retrieve.
+
+        Returns:
+            dict: The document data.
+        """
+        async with self.connection.cursor() as cursor:
+            await cursor.execute("SELECT * FROM documents WHERE doc_id = ?", (doc_id,))
+            row = await cursor.fetchone()
+            if row:
+                return await self.tuple_to_dict(row)
+            else:
+                return None
+
+    async def update_document_by_doc_id(self, doc_id: str, new_text: str):
+        """Retrieve a document by its doc_id.
+
+        Args:
+            doc_id (str): The doc_id.
+            new_text (str): The new text to update the document with.
+        """
+        async with self.connection.cursor() as cursor:
+            await cursor.execute(
+                "UPDATE documents SET text = ? WHERE doc_id = ?", (new_text, doc_id)
+            )
+            await self.connection.commit()
+
+    async def get_user_ids(self) -> list[str]:
+        """Retrieve all user IDs from the documents table.
+
+        Returns:
+            list: A list of user IDs.
+        """
+        async with self.connection.cursor() as cursor:
+            await cursor.execute("SELECT DISTINCT user_id FROM documents")
+            rows = await cursor.fetchall()
+            return [row[0] for row in rows]
+
+    async def tuple_to_dict(self, row):
+        """Convert a tuple to a dictionary.
+
+        Args:
+            row (tuple): The row to convert.
+
+        Returns:
+            dict: The converted dictionary.
+        """
+        return {
+            "id": row[0],
+            "doc_id": row[1],
+            "text": row[2],
+            "metadata": row[3],
+            "created_at": row[4],
+            "updated_at": row[5],
+        }
+
+    async def close(self):
+        """Close the connection to the SQLite database."""
+        if self.connection:
+            await self.connection.close()
+            self.connection = None

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

@@ -0,0 +1,59 @@
+try:
+    import faiss
+except ModuleNotFoundError:
+    raise ImportError(
+        "faiss 未安装。请使用 'pip install faiss-cpu' 或 'pip install faiss-gpu' 安装。"
+    )
+import os
+import numpy as np
+
+
+class EmbeddingStorage:
+    def __init__(self, dimension: int, path: str = None):
+        self.dimension = dimension
+        self.path = path
+        self.index = None
+        if path and os.path.exists(path):
+            self.index = faiss.read_index(path)
+        else:
+            base_index = faiss.IndexFlatL2(dimension)
+            self.index = faiss.IndexIDMap(base_index)
+        self.storage = {}
+
+    async def insert(self, vector: np.ndarray, id: int):
+        """插入向量
+
+        Args:
+            vector (np.ndarray): 要插入的向量
+            id (int): 向量的ID
+        Raises:
+            ValueError: 如果向量的维度与存储的维度不匹配
+        """
+        if vector.shape[0] != self.dimension:
+            raise ValueError(
+                f"向量维度不匹配, 期望: {self.dimension}, 实际: {vector.shape[0]}"
+            )
+        self.index.add_with_ids(vector.reshape(1, -1), np.array([id]))
+        self.storage[id] = vector
+        await self.save_index()
+
+    async def search(self, vector: np.ndarray, k: int) -> tuple:
+        """搜索最相似的向量
+
+        Args:
+            vector (np.ndarray): 查询向量
+            k (int): 返回的最相似向量的数量
+        Returns:
+            tuple: (距离, 索引)
+        """
+        faiss.normalize_L2(vector)
+        distances, indices = self.index.search(vector, k)
+        return distances, indices
+
+    async def save_index(self):
+        """保存索引
+
+        Args:
+            path (str): 保存索引的路径
+        """
+        faiss.write_index(self.index, self.path)

astrbot/core/db/vec_db/faiss_impl/sqlite_init.sql

@@ -0,0 +1,17 @@
+-- 创建文档存储表，包含 faiss 中文档的 id，文档文本，create_at，updated_at
+CREATE TABLE documents (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    doc_id TEXT NOT NULL,
+    text TEXT NOT NULL,
+    metadata TEXT,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+ALTER TABLE documents
+ADD COLUMN group_id TEXT GENERATED ALWAYS AS (json_extract(metadata, '$.group_id')) STORED;
+ALTER TABLE documents
+ADD COLUMN user_id TEXT GENERATED ALWAYS AS (json_extract(metadata, '$.user_id')) STORED;
+
+CREATE INDEX idx_documents_user_id ON documents(user_id);
+CREATE INDEX idx_documents_group_id ON documents(group_id);

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

@@ -0,0 +1,117 @@
+import uuid
+import json
+import numpy as np
+from .document_storage import DocumentStorage
+from .embedding_storage import EmbeddingStorage
+from ..base import Result, BaseVecDB
+from astrbot.core.provider.provider import EmbeddingProvider
+
+
+class FaissVecDB(BaseVecDB):
+    """
+    A class to represent a vector database.
+    """
+
+    def __init__(
+        self,
+        doc_store_path: str,
+        index_store_path: str,
+        embedding_provider: EmbeddingProvider,
+    ):
+        self.doc_store_path = doc_store_path
+        self.index_store_path = index_store_path
+        self.embedding_provider = embedding_provider
+        self.document_storage = DocumentStorage(doc_store_path)
+        self.embedding_storage = EmbeddingStorage(
+            embedding_provider.get_dim(), index_store_path
+        )
+        self.embedding_provider = embedding_provider
+
+    async def initialize(self):
+        await self.document_storage.initialize()
+
+    async def insert(self, content: str, metadata: dict = None, id: str = None) -> int:
+        """
+        插入一条文本和其对应向量，自动生成 ID 并保持一致性。
+        """
+        metadata = metadata or {}
+        str_id = id or str(uuid.uuid4())  # 使用 UUID 作为原始 ID
+
+        vector = await self.embedding_provider.get_embedding(content)
+        vector = np.array(vector, dtype=np.float32)
+        async with self.document_storage.connection.cursor() as cursor:
+            await cursor.execute(
+                "INSERT INTO documents (doc_id, text, metadata) VALUES (?, ?, ?)",
+                (str_id, content, json.dumps(metadata)),
+            )
+            await self.document_storage.connection.commit()
+            result = await self.document_storage.get_document_by_doc_id(str_id)
+            int_id = result["id"]
+
+            # 插入向量到 FAISS
+            await self.embedding_storage.insert(vector, int_id)
+            return int_id
+
+    async def retrieve(
+        self, query: str, k: int = 5, fetch_k: int = 20, metadata_filters: dict = None
+    ) -> list[Result]:
+        """
+        搜索最相似的文档。
+
+        Args:
+            query (str): 查询文本
+            k (int): 返回的最相似文档的数量
+            fetch_k (int): 在根据 metadata 过滤前从 FAISS 中获取的数量
+            metadata_filters (dict): 元数据过滤器
+
+        Returns:
+            List[Result]: 查询结果
+        """
+        embedding = await self.embedding_provider.get_embedding(query)
+        scores, indices = await self.embedding_storage.search(
+            vector=np.array([embedding]).astype("float32"),
+            k=fetch_k if metadata_filters else k,
+        )
+        # TODO: rerank
+        if len(indices[0]) == 0 or indices[0][0] == -1:
+            return []
+        # normalize scores
+        scores[0] = 1.0 - (scores[0] / 2.0)
+        # NOTE: maybe the size is less than k.
+        fetched_docs = await self.document_storage.get_documents(
+            metadata_filters=metadata_filters or {}, ids=indices[0]
+        )
+        if not fetched_docs:
+            return []
+        result_docs = []
+
+        idx_pos = {fetch_doc["id"]: idx for idx, fetch_doc in enumerate(fetched_docs)}
+        for i, indice_idx in enumerate(indices[0]):
+            pos = idx_pos.get(indice_idx)
+            if pos is None:
+                continue
+            fetch_doc = fetched_docs[pos]
+            score = scores[0][i]
+            result_docs.append(Result(similarity=float(score), data=fetch_doc))
+        return result_docs[:k]
+
+    async def delete(self, doc_id: int):
+        """
+        删除一条文档
+        """
+        await self.document_storage.connection.execute(
+            "DELETE FROM documents WHERE doc_id = ?", (doc_id,)
+        )
+        await self.document_storage.connection.commit()
+
+    async def close(self):
+        await self.document_storage.close()
+
+    async def count_documents(self) -> int:
+        """
+        计算文档数量
+        """
+        async with self.document_storage.connection.cursor() as cursor:
+            await cursor.execute("SELECT COUNT(*) FROM documents")
+            count = await cursor.fetchone()
+            return count[0] if count else 0

astrbot/core/event_bus.py

@@ -1,3 +1,16 @@
+"""
+事件总线, 用于处理事件的分发和处理
+事件总线是一个异步队列, 用于接收各种消息事件, 并将其发送到Scheduler调度器进行处理
+其中包含了一个无限循环的调度函数, 用于从事件队列中获取新的事件, 并创建一个新的异步任务来执行管道调度器的处理逻辑
+
+class:
+    EventBus: 事件总线, 用于处理事件的分发和处理
+
+工作流程:
+1. 维护一个异步队列, 来接受各种消息事件
+2. 无限循环的调度函数, 从事件队列中获取新的事件, 打印日志并创建一个新的异步任务来执行管道调度器的处理逻辑
+"""
+
 import asyncio
 from asyncio import Queue
 from astrbot.core.pipeline.scheduler import PipelineScheduler
@@ -6,21 +19,38 @@ from .platform import AstrMessageEvent
 
 
 class EventBus:
+    """事件总线: 用于处理事件的分发和处理
+
+    维护一个异步队列, 来接受各种消息事件
+    """
+
     def __init__(self, event_queue: Queue, pipeline_scheduler: PipelineScheduler):
-        self.event_queue = event_queue
-        self.pipeline_scheduler = pipeline_scheduler
+        self.event_queue = event_queue  # 事件队列
+        self.pipeline_scheduler = pipeline_scheduler  # 管道调度器
 
     async def dispatch(self):
+        """无限循环的调度函数, 从事件队列中获取新的事件, 打印日志并创建一个新的异步任务来执行管道调度器的处理逻辑"""
         while True:
-            event: AstrMessageEvent = await self.event_queue.get()
-            self._print_event(event)
-            asyncio.create_task(self.pipeline_scheduler.execute(event))
+            event: AstrMessageEvent = (
+                await self.event_queue.get()
+            )  # 从事件队列中获取新的事件
+            self._print_event(event)  # 打印日志
+            asyncio.create_task(
+                self.pipeline_scheduler.execute(event)
+            )  # 创建新的异步任务来执行管道调度器的处理逻辑
 
     def _print_event(self, event: AstrMessageEvent):
+        """用于记录事件信息
+
+        Args:
+            event (AstrMessageEvent): 事件对象
+        """
+        # 如果有发送者名称: [平台名] 发送者名称/发送者ID: 消息概要
         if event.get_sender_name():
             logger.info(
                 f"[{event.get_platform_name()}] {event.get_sender_name()}/{event.get_sender_id()}: {event.get_message_outline()}"
             )
+        # 没有发送者名称: [平台名] 发送者ID: 消息概要
         else:
             logger.info(
                 f"[{event.get_platform_name()}] {event.get_sender_id()}: {event.get_message_outline()}"

astrbot/core/file_token_service.py

@@ -0,0 +1,92 @@
+import asyncio
+import os
+import uuid
+import time
+from urllib.parse import urlparse, unquote
+import platform
+
+
+class FileTokenService:
+    """维护一个简单的基于令牌的文件下载服务，支持超时和懒清除。"""
+
+    def __init__(self, default_timeout: float = 300):
+        self.lock = asyncio.Lock()
+        self.staged_files = {}  # token: (file_path, expire_time)
+        self.default_timeout = default_timeout
+
+    async def _cleanup_expired_tokens(self):
+        """清理过期的令牌"""
+        now = time.time()
+        expired_tokens = [
+            token for token, (_, expire) in self.staged_files.items() if expire < now
+        ]
+        for token in expired_tokens:
+            self.staged_files.pop(token, None)
+
+    async def register_file(self, file_path: str, timeout: float = None) -> str:
+        """向令牌服务注册一个文件。
+
+        Args:
+            file_path(str): 文件路径
+            timeout(float): 超时时间，单位秒（可选）
+
+        Returns:
+            str: 一个单次令牌
+
+        Raises:
+            FileNotFoundError: 当路径不存在时抛出
+        """
+
+        # 处理 file:///
+        try:
+            parsed_uri = urlparse(file_path)
+            if parsed_uri.scheme == "file":
+                local_path = unquote(parsed_uri.path)
+                if platform.system() == "Windows" and local_path.startswith("/"):
+                    local_path = local_path[1:]
+            else:
+                # 如果没有 file:/// 前缀，则认为是普通路径
+                local_path = file_path
+        except Exception:
+            # 解析失败时，按原路径处理
+            local_path = file_path
+
+        async with self.lock:
+            await self._cleanup_expired_tokens()
+
+            if not os.path.exists(local_path):
+                raise FileNotFoundError(
+                    f"文件不存在: {local_path} (原始输入: {file_path})"
+                )
+
+            file_token = str(uuid.uuid4())
+            expire_time = time.time() + (
+                timeout if timeout is not None else self.default_timeout
+            )
+            # 存储转换后的真实路径
+            self.staged_files[file_token] = (local_path, expire_time)
+            return file_token
+
+    async def handle_file(self, file_token: str) -> str:
+        """根据令牌获取文件路径，使用后令牌失效。
+
+        Args:
+            file_token(str): 注册时返回的令牌
+
+        Returns:
+            str: 文件路径
+
+        Raises:
+            KeyError: 当令牌不存在或已过期时抛出
+            FileNotFoundError: 当文件本身已被删除时抛出
+        """
+        async with self.lock:
+            await self._cleanup_expired_tokens()
+
+            if file_token not in self.staged_files:
+                raise KeyError(f"无效或过期的文件 token: {file_token}")
+
+            file_path, _ = self.staged_files.pop(file_token)
+            if not os.path.exists(file_path):
+                raise FileNotFoundError(f"文件不存在: {file_path}")
+            return file_path

astrbot/core/initial_loader.py

@@ -1,35 +1,49 @@
+"""
+AstrBot 启动器，负责初始化和启动核心组件和仪表板服务器。
+
+工作流程:
+1. 初始化核心生命周期, 传递数据库和日志代理实例到核心生命周期
+2. 运行核心生命周期任务和仪表板服务器
+"""
+
 import asyncio
 import traceback
 from astrbot.core import logger
 from astrbot.core.core_lifecycle import AstrBotCoreLifecycle
-from .server import AstrBotDashboard
 from astrbot.core.db import BaseDatabase
 from astrbot.core import LogBroker
+from astrbot.dashboard.server import AstrBotDashboard
 
 
-class AstrBotDashBoardLifecycle:
+class InitialLoader:
+    """AstrBot 启动器，负责初始化和启动核心组件和仪表板服务器。"""
+
     def __init__(self, db: BaseDatabase, log_broker: LogBroker):
         self.db = db
         self.logger = logger
         self.log_broker = log_broker
-        self.dashboard_server = None
 
     async def start(self):
         core_lifecycle = AstrBotCoreLifecycle(self.log_broker, self.db)
 
-        core_task = []
         try:
             await core_lifecycle.initialize()
-            core_task = core_lifecycle.start()
         except Exception as e:
             logger.critical(traceback.format_exc())
             logger.critical(f"😭 初始化 AstrBot 失败：{e} !!!")
+            return
 
-        self.dashboard_server = AstrBotDashboard(core_lifecycle, self.db)
-        task = asyncio.gather(core_task, self.dashboard_server.run())
+        core_task = core_lifecycle.start()
+
+        self.dashboard_server = AstrBotDashboard(
+            core_lifecycle, self.db, core_lifecycle.dashboard_shutdown_event
+        )
+        task = asyncio.gather(
+            core_task, self.dashboard_server.run()
+        )  # 启动核心任务和仪表板服务器
 
         try:
-            await task
+            await task  # 整个AstrBot在这里运行
         except asyncio.CancelledError:
             logger.info("🌈 正在关闭 AstrBot...")
             await core_lifecycle.stop()

astrbot/core/log.py

@@ -1,12 +1,38 @@
+"""
+日志系统, 用于支持核心组件和插件的日志记录, 提供了日志订阅功能
+
+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, 订阅日志流
+"""
+
 import logging
 import colorlog
 import asyncio
 import os
+import sys
 from collections import deque
 from asyncio import Queue
 from typing import List
 
+# 日志缓存大小
 CACHED_SIZE = 200
+# 日志颜色配置
 log_color_config = {
     "DEBUG": "green",
     "INFO": "bold_cyan",
@@ -19,8 +45,13 @@ log_color_config = {
 
 
 def is_plugin_path(pathname):
-    """
-    检查文件路径是否来自插件目录
+    """检查文件路径是否来自插件目录
+
+    Args:
+        pathname (str): 文件路径
+
+    Returns:
+        bool: 如果路径来自插件目录，则返回 True，否则返回 False
     """
     if not pathname:
         return False
@@ -30,8 +61,13 @@ def is_plugin_path(pathname):
 
 
 def get_short_level_name(level_name):
-    """
-    将日志级别名称转换为四个字母的缩写
+    """将日志级别名称转换为四个字母的缩写
+
+    Args:
+        level_name (str): 日志级别名称, 如 "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
+
+    Returns:
+        str: 四个字母的日志级别缩写
     """
     level_map = {
         "DEBUG": "DBUG",
@@ -44,24 +80,40 @@ def get_short_level_name(level_name):
 
 
 class LogBroker:
+    """日志代理类, 用于缓存和分发日志消息
+
+    发布-订阅模式
+    """
+
     def __init__(self):
-        self.log_cache = deque(maxlen=CACHED_SIZE)
-        self.subscribers: List[Queue] = []
+        self.log_cache = deque(maxlen=CACHED_SIZE)  # 环形缓冲区, 保存最近的日志
+        self.subscribers: List[Queue] = []  # 订阅者列表
 
     def register(self) -> Queue:
-        """给每个订阅者返回一个带有日志缓存的队列"""
+        """注册新的订阅者, 并给每个订阅者返回一个带有日志缓存的队列
+
+        Returns:
+            Queue: 订阅者的队列, 可用于接收日志消息
+        """
         q = Queue(maxsize=CACHED_SIZE + 10)
-        for log in self.log_cache:
-            q.put_nowait(log)
         self.subscribers.append(q)
         return q
 
     def unregister(self, q: Queue):
-        """取消订阅"""
+        """取消订阅
+
+        Args:
+            q (Queue): 需要取消订阅的队列
+        """
         self.subscribers.remove(q)
 
-    def publish(self, log_entry: str):
-        """发布消息"""
+    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"}
+        """
         self.log_cache.append(log_entry)
         for q in self.subscribers:
             try:
@@ -71,24 +123,61 @@ class LogBroker:
 
 
 class LogQueueHandler(logging.Handler):
+    """日志处理器, 用于将日志消息发送到 LogBroker
+
+    继承自 logging.Handler
+    """
+
     def __init__(self, log_broker: LogBroker):
         super().__init__()
         self.log_broker = log_broker
 
     def emit(self, record):
+        """日志处理的入口方法, 接受一个日志记录, 转换为字符串后由 LogBroker 发布
+        这个方法会在每次日志记录时被调用
+
+        Args:
+            record (logging.LogRecord): 日志记录对象, 包含日志信息
+        """
         log_entry = self.format(record)
-        self.log_broker.publish(log_entry)
+        self.log_broker.publish(
+            {
+                "level": record.levelname,
+                "time": record.asctime,
+                "data": log_entry,
+            }
+        )
 
 
 class LogManager:
+    """日志管理器, 用于创建和配置日志记录器
+
+    提供了获取默认日志记录器logger和设置队列处理器的方法
+    """
+
     @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
-        console_handler = logging.StreamHandler()
-        console_handler.setLevel(logging.DEBUG)
+        # 如果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] [%(filename)s:%(lineno)d]: %(message)s %(reset)s",
             datefmt="%H:%M:%S",
@@ -96,6 +185,8 @@ class LogManager:
         )
 
         class PluginFilter(logging.Filter):
+            """插件过滤器类, 用于标记日志来源是插件还是核心组件"""
+
             def filter(self, record):
                 record.plugin_tag = (
                     "[Plug]" if is_plugin_path(record.pathname) else "[Core]"
@@ -103,6 +194,9 @@ class LogManager:
                 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)
@@ -114,22 +208,30 @@ class LogManager:
                 return True
 
         class LevelNameFilter(logging.Filter):
+            """短日志级别名称过滤器类, 用于将日志级别名称转换为四个字母的缩写"""
+
             # 添加短日志级别名称
             def filter(self, record):
                 record.short_levelname = get_short_level_name(record.levelname)
                 return True
 
-        console_handler.setFormatter(console_formatter)
-        logger.addFilter(PluginFilter())
-        logger.addFilter(FileNameFilter())
+        console_handler.setFormatter(console_formatter)  # 设置处理器的格式化器
+        logger.addFilter(PluginFilter())  # 添加插件过滤器
+        logger.addFilter(FileNameFilter())  # 添加文件名过滤器
         logger.addFilter(LevelNameFilter())  # 添加级别名称过滤器
-        logger.setLevel(logging.DEBUG)
-        logger.addHandler(console_handler)
+        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:

astrbot/core/message/components.py

@@ -22,13 +22,20 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 """
 
+import asyncio
 import base64
 import json
 import os
 import typing as T
+import uuid
 from enum import Enum
+
 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.io import download_file, download_image_by_url, file_to_base64
+
 
 class ComponentType(Enum):
     Plain = "Plain"  # 纯文本消息
@@ -59,6 +66,8 @@ class ComponentType(Enum):
     TTS = "TTS"
     Unknown = "Unknown"
 
+    WechatEmoji = "WechatEmoji"  # Wechat 下的 emoji 表情包
+
 
 class BaseMessageComponent(BaseModel):
     type: ComponentType
@@ -93,6 +102,10 @@ class BaseMessageComponent(BaseModel):
             data[k] = v
         return {"type": self.type.lower(), "data": data}
 
+    async def to_dict(self) -> dict:
+        # 默认情况下，回退到旧的同步 toDict()
+        return self.toDict()
+
 
 class Plain(BaseMessageComponent):
     type: ComponentType = "Plain"
@@ -109,6 +122,12 @@ class Plain(BaseMessageComponent):
             self.text.replace("&", "&").replace("[", "[").replace("]", "]")
         )
 
+    def toDict(self):
+        return {"type": "text", "data": {"text": self.text.strip()}}
+
+    async def to_dict(self):
+        return {"type": "text", "data": {"text": self.text}}
+
 
 class Face(BaseMessageComponent):
     type: ComponentType = "Face"
@@ -146,6 +165,76 @@ class Record(BaseMessageComponent):
             return Record(file=url, **_)
         raise Exception("not a valid url")
 
+    async def convert_to_file_path(self) -> str:
+        """将这个语音统一转换为本地文件路径。这个方法避免了手动判断语音数据类型，直接返回语音数据的本地路径（如果是网络 URL, 则会自动进行下载）。
+
+        Returns:
+            str: 语音的本地路径，以绝对路径表示。
+        """
+        if self.file and self.file.startswith("file:///"):
+            file_path = self.file[8:]
+            return file_path
+        elif self.file and self.file.startswith("http"):
+            file_path = await download_image_by_url(self.file)
+            return os.path.abspath(file_path)
+        elif self.file and 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")
+            with open(file_path, "wb") as f:
+                f.write(image_bytes)
+            return os.path.abspath(file_path)
+        elif os.path.exists(self.file):
+            file_path = self.file
+            return os.path.abspath(file_path)
+        else:
+            raise Exception(f"not a valid file: {self.file}")
+
+    async def convert_to_base64(self) -> str:
+        """将语音统一转换为 base64 编码。这个方法避免了手动判断语音数据类型，直接返回语音数据的 base64 编码。
+
+        Returns:
+            str: 语音的 base64 编码，不以 base64:// 或者 data:image/jpeg;base64, 开头。
+        """
+        # convert to base64
+        if self.file and self.file.startswith("file:///"):
+            bs64_data = file_to_base64(self.file[8:])
+        elif self.file and self.file.startswith("http"):
+            file_path = await download_image_by_url(self.file)
+            bs64_data = file_to_base64(file_path)
+        elif self.file and self.file.startswith("base64://"):
+            bs64_data = self.file
+        elif os.path.exists(self.file):
+            bs64_data = file_to_base64(self.file)
+        else:
+            raise Exception(f"not a valid file: {self.file}")
+        bs64_data = bs64_data.removeprefix("base64://")
+        return bs64_data
+
+    async def register_to_file_service(self) -> str:
+        """
+        将语音注册到文件服务。
+
+        Returns:
+            str: 注册后的URL
+
+        Raises:
+            Exception: 如果未配置 callback_api_base
+        """
+        callback_host = astrbot_config.get("callback_api_base")
+
+        if not callback_host:
+            raise Exception("未配置 callback_api_base，文件服务不可用")
+
+        file_path = await self.convert_to_file_path()
+
+        token = await file_token_service.register_file(file_path)
+
+        logger.debug(f"已注册：{callback_host}/api/file/{token}")
+
+        return f"{callback_host}/api/file/{token}"
+
 
 class Video(BaseMessageComponent):
     type: ComponentType = "Video"
@@ -156,9 +245,6 @@ class Video(BaseMessageComponent):
     path: T.Optional[str] = ""
 
     def __init__(self, file: str, **_):
-        # for k in _.keys():
-        #     if k == "c" and _[k] not in [2, 3]:
-        #         logger.warn(f"Protocol: {k}={_[k]} doesn't match values")
         super().__init__(file=file, **_)
 
     @staticmethod
@@ -171,6 +257,70 @@ class Video(BaseMessageComponent):
             return Video(file=url, **_)
         raise Exception("not a valid url")
 
+    async def convert_to_file_path(self) -> str:
+        """将这个视频统一转换为本地文件路径。这个方法避免了手动判断视频数据类型，直接返回视频数据的本地路径（如果是网络 URL，则会自动进行下载）。
+
+        Returns:
+            str: 视频的本地路径，以绝对路径表示。
+        """
+        url = self.file
+        if url and url.startswith("file:///"):
+            return url[8:]
+        elif 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}")
+            await download_file(url, video_file_path)
+            if os.path.exists(video_file_path):
+                return os.path.abspath(video_file_path)
+            else:
+                raise Exception(f"download failed: {url}")
+        elif os.path.exists(url):
+            return os.path.abspath(url)
+        else:
+            raise Exception(f"not a valid file: {url}")
+
+    async def register_to_file_service(self):
+        """
+        将视频注册到文件服务。
+
+        Returns:
+            str: 注册后的URL
+
+        Raises:
+            Exception: 如果未配置 callback_api_base
+        """
+        callback_host = astrbot_config.get("callback_api_base")
+
+        if not callback_host:
+            raise Exception("未配置 callback_api_base，文件服务不可用")
+
+        file_path = await self.convert_to_file_path()
+
+        token = await file_token_service.register_file(file_path)
+
+        logger.debug(f"已注册：{callback_host}/api/file/{token}")
+
+        return f"{callback_host}/api/file/{token}"
+
+    async def to_dict(self):
+        """需要和 toDict 区分开，toDict 是同步方法"""
+        url_or_path = self.file
+        if url_or_path.startswith("http"):
+            payload_file = url_or_path
+        elif callback_host := astrbot_config.get("callback_api_base"):
+            callback_host = str(callback_host).removesuffix("/")
+            token = await file_token_service.register_file(url_or_path)
+            payload_file = f"{callback_host}/api/file/{token}"
+            logger.debug(f"Generated video file callback link: {payload_file}")
+        else:
+            payload_file = url_or_path
+        return {
+            "type": "video",
+            "data": {
+                "file": payload_file,
+            },
+        }
+
 
 class At(BaseMessageComponent):
     type: ComponentType = "At"
@@ -180,6 +330,12 @@ class At(BaseMessageComponent):
     def __init__(self, **_):
         super().__init__(**_)
 
+    def toDict(self):
+        return {
+            "type": "at",
+            "data": {"qq": str(self.qq)},
+        }
+
 
 class AtAll(At):
     qq: str = "all"
@@ -279,10 +435,6 @@ class Image(BaseMessageComponent):
     file_unique: T.Optional[str] = ""  # 某些平台可能有图片缓存的唯一标识
 
     def __init__(self, file: T.Optional[str], **_):
-        # for k in _.keys():
-        #     if (k == "_type" and _[k] not in ["flash", "show", None]) or \
-        #             (k == "c" and _[k] not in [2, 3]):
-        #         logger.warn(f"Protocol: {k}={_[k]} doesn't match values")
         super().__init__(file=file, **_)
 
     @staticmethod
@@ -307,14 +459,100 @@ class Image(BaseMessageComponent):
     def fromIO(IO):
         return Image.fromBytes(IO.read())
 
+    async def convert_to_file_path(self) -> str:
+        """将这个图片统一转换为本地文件路径。这个方法避免了手动判断图片数据类型，直接返回图片数据的本地路径（如果是网络 URL, 则会自动进行下载）。
+
+        Returns:
+            str: 图片的本地路径，以绝对路径表示。
+        """
+        url = self.url if self.url else self.file
+        if url and url.startswith("file:///"):
+            image_file_path = url[8:]
+            return image_file_path
+        elif url and url.startswith("http"):
+            image_file_path = await download_image_by_url(url)
+            return os.path.abspath(image_file_path)
+        elif url and 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")
+            with open(image_file_path, "wb") as f:
+                f.write(image_bytes)
+            return os.path.abspath(image_file_path)
+        elif os.path.exists(url):
+            image_file_path = url
+            return os.path.abspath(image_file_path)
+        else:
+            raise Exception(f"not a valid file: {url}")
+
+    async def convert_to_base64(self) -> str:
+        """将这个图片统一转换为 base64 编码。这个方法避免了手动判断图片数据类型，直接返回图片数据的 base64 编码。
+
+        Returns:
+            str: 图片的 base64 编码，不以 base64:// 或者 data:image/jpeg;base64, 开头。
+        """
+        # convert to base64
+        url = self.url if self.url else self.file
+        if url and url.startswith("file:///"):
+            bs64_data = file_to_base64(url[8:])
+        elif url and url.startswith("http"):
+            image_file_path = await download_image_by_url(url)
+            bs64_data = file_to_base64(image_file_path)
+        elif url and url.startswith("base64://"):
+            bs64_data = url
+        elif os.path.exists(url):
+            bs64_data = file_to_base64(url)
+        else:
+            raise Exception(f"not a valid file: {url}")
+        bs64_data = bs64_data.removeprefix("base64://")
+        return bs64_data
+
+    async def register_to_file_service(self) -> str:
+        """
+        将图片注册到文件服务。
+
+        Returns:
+            str: 注册后的URL
+
+        Raises:
+            Exception: 如果未配置 callback_api_base
+        """
+        callback_host = astrbot_config.get("callback_api_base")
+
+        if not callback_host:
+            raise Exception("未配置 callback_api_base，文件服务不可用")
+
+        file_path = await self.convert_to_file_path()
+
+        token = await file_token_service.register_file(file_path)
+
+        logger.debug(f"已注册：{callback_host}/api/file/{token}")
+
+        return f"{callback_host}/api/file/{token}"
+
 
 class Reply(BaseMessageComponent):
     type: ComponentType = "Reply"
     id: T.Union[str, int]
-    text: T.Optional[str] = ""
-    qq: T.Optional[int] = 0
+    """所引用的消息 ID"""
+    chain: T.Optional[T.List["BaseMessageComponent"]] = []
+    """被引用的消息段列表"""
+    sender_id: T.Optional[int] | T.Optional[str] = 0
+    """被引用的消息对应的发送者的 ID"""
+    sender_nickname: T.Optional[str] = ""
+    """被引用的消息对应的发送者的昵称"""
     time: T.Optional[int] = 0
+    """被引用的消息发送时间"""
+    message_str: T.Optional[str] = ""
+    """被引用的消息解析后的纯文本消息字符串"""
+
+    text: T.Optional[str] = ""
+    """deprecated"""
+    qq: T.Optional[int] = 0
+    """deprecated"""
     seq: T.Optional[int] = 0
+    """deprecated"""
 
     def __init__(self, **_):
         super().__init__(**_)
@@ -352,22 +590,52 @@ class Node(BaseMessageComponent):
     type: ComponentType = "Node"
     id: T.Optional[int] = 0  # 忽略
     name: T.Optional[str] = ""  # qq昵称
-    uin: T.Optional[int] = 0  # qq号
-    content: T.Optional[T.Union[str, list]] = ""  # 子消息段列表
+    uin: T.Optional[str] = "0"  # qq号
+    content: T.Optional[list[BaseMessageComponent]] = []
     seq: T.Optional[T.Union[str, list]] = ""  # 忽略
-    time: T.Optional[int] = 0
+    time: T.Optional[int] = 0  # 忽略
 
-    def __init__(self, content: T.Union[str, list], **_):
-        if isinstance(content, list):
-            _content = ""
-            for chain in content:
-                _content += chain.toString()
-            content = _content
+    def __init__(self, content: list[BaseMessageComponent], **_):
+        if isinstance(content, Node):
+            # back
+            content = [content]
         super().__init__(content=content, **_)
 
-    def toString(self):
-        # logger.warn("Protocol: node doesn't support stringify")
-        return ""
+    async def to_dict(self):
+        data_content = []
+        for comp in self.content:
+            if isinstance(comp, (Image, Record)):
+                # For Image and Record segments, we convert them to base64
+                bs64 = await comp.convert_to_base64()
+                data_content.append(
+                    {
+                        "type": comp.type.lower(),
+                        "data": {"file": f"base64://{bs64}"},
+                    }
+                )
+            elif isinstance(comp, Plain):
+                # For Plain segments, we need to handle the plain differently
+                d = await comp.to_dict()
+                data_content.append(d)
+            elif isinstance(comp, File):
+                # For File segments, we need to handle the file differently
+                d = await comp.to_dict()
+                data_content.append(d)
+            elif isinstance(comp, (Node, Nodes)):
+                # For Node segments, we recursively convert them to dict
+                d = await comp.to_dict()
+                data_content.append(d)
+            else:
+                d = comp.toDict()
+                data_content.append(d)
+        return {
+            "type": "node",
+            "data": {
+                "user_id": str(self.uin),
+                "nickname": self.name,
+                "content": data_content,
+            },
+        }
 
 
 class Nodes(BaseMessageComponent):
@@ -378,7 +646,22 @@ class Nodes(BaseMessageComponent):
         super().__init__(nodes=nodes, **_)
 
     def toDict(self):
-        return {"messages": [node.toDict() for node in self.nodes]}
+        """Deprecated. Use to_dict instead"""
+        ret = {
+            "messages": [],
+        }
+        for node in self.nodes:
+            d = node.toDict()
+            ret["messages"].append(d)
+        return ret
+
+    async def to_dict(self):
+        """将 Nodes 转换为字典格式，适用于 OneBot JSON 格式"""
+        ret = {"messages": []}
+        for node in self.nodes:
+            d = await node.to_dict()
+            ret["messages"].append(d)
+        return ret
 
 
 class Xml(BaseMessageComponent):
@@ -438,15 +721,146 @@ class Unknown(BaseMessageComponent):
 
 class File(BaseMessageComponent):
     """
-    目前此消息段只适配了 Napcat。
+    文件消息段
     """
 
     type: ComponentType = "File"
     name: T.Optional[str] = ""  # 名字
-    file: T.Optional[str] = ""  # url（本地路径）
+    file_: T.Optional[str] = ""  # 本地路径
+    url: T.Optional[str] = ""  # url
 
-    def __init__(self, name: str, file: str):
-        super().__init__(name=name, file=file)
+    def __init__(self, name: str, file: str = "", url: str = ""):
+        """文件消息段。"""
+        super().__init__(name=name, file_=file, url=url)
+
+    @property
+    def file(self) -> str:
+        """
+        获取文件路径，如果文件不存在但有URL，则同步下载文件
+
+        Returns:
+            str: 文件路径
+        """
+        if self.file_ and os.path.exists(self.file_):
+            return os.path.abspath(self.file_)
+
+        if self.url:
+            try:
+                loop = asyncio.get_event_loop()
+                if loop.is_running():
+                    logger.warning(
+                        (
+                            "不可以在异步上下文中同步等待下载! "
+                            "这个警告通常发生于某些逻辑试图通过 <File>.file 获取文件消息段的文件内容。"
+                            "请使用 await get_file() 代替直接获取 <File>.file 字段"
+                        )
+                    )
+                    return ""
+                else:
+                    # 等待下载完成
+                    loop.run_until_complete(self._download_file())
+
+                    if self.file_ and os.path.exists(self.file_):
+                        return os.path.abspath(self.file_)
+            except Exception as e:
+                logger.error(f"文件下载失败: {e}")
+
+        return ""
+
+    @file.setter
+    def file(self, value: str):
+        """
+        向前兼容, 设置file属性, 传入的参数可能是文件路径或URL
+
+        Args:
+            value (str): 文件路径或URL
+        """
+        if value.startswith("http://") or value.startswith("https://"):
+            self.url = value
+        else:
+            self.file_ = value
+
+    async def get_file(self, allow_return_url: bool = False) -> str:
+        """异步获取文件。请注意在使用后清理下载的文件, 以免占用过多空间
+
+        Args:
+            allow_return_url: 是否允许以文件 http 下载链接的形式返回，这允许您自行控制是否需要下载文件。
+            注意，如果为 True，也可能返回文件路径。
+        Returns:
+            str: 文件路径或者 http 下载链接
+        """
+        if allow_return_url and self.url:
+            return self.url
+
+        if self.file_ and os.path.exists(self.file_):
+            return os.path.abspath(self.file_)
+
+        if self.url:
+            await self._download_file()
+            return os.path.abspath(self.file_)
+
+        return ""
+
+    async def _download_file(self):
+        """下载文件"""
+        download_dir = os.path.join(get_astrbot_data_path(), "temp")
+        os.makedirs(download_dir, exist_ok=True)
+        file_path = os.path.join(download_dir, f"{uuid.uuid4().hex}")
+        await download_file(self.url, file_path)
+        self.file_ = os.path.abspath(file_path)
+
+    async def register_to_file_service(self):
+        """
+        将文件注册到文件服务。
+
+        Returns:
+            str: 注册后的URL
+
+        Raises:
+            Exception: 如果未配置 callback_api_base
+        """
+        callback_host = astrbot_config.get("callback_api_base")
+
+        if not callback_host:
+            raise Exception("未配置 callback_api_base，文件服务不可用")
+
+        file_path = await self.get_file()
+
+        token = await file_token_service.register_file(file_path)
+
+        logger.debug(f"已注册：{callback_host}/api/file/{token}")
+
+        return f"{callback_host}/api/file/{token}"
+
+    async def to_dict(self):
+        """需要和 toDict 区分开，toDict 是同步方法"""
+        url_or_path = await self.get_file(allow_return_url=True)
+        if url_or_path.startswith("http"):
+            payload_file = url_or_path
+        elif callback_host := astrbot_config.get("callback_api_base"):
+            callback_host = str(callback_host).removesuffix("/")
+            token = await file_token_service.register_file(url_or_path)
+            payload_file = f"{callback_host}/api/file/{token}"
+            logger.debug(f"Generated file callback link: {payload_file}")
+        else:
+            payload_file = url_or_path
+        return {
+            "type": "file",
+            "data": {
+                "name": self.name,
+                "file": payload_file,
+            },
+        }
+
+
+class WechatEmoji(BaseMessageComponent):
+    type: ComponentType = "WechatEmoji"
+    md5: T.Optional[str] = ""
+    md5_len: T.Optional[int] = 0
+    cdnurl: T.Optional[str] = ""
+
+    def __init__(self, **_):
+        super().__init__(**_)
 
 
 ComponentTypes = {
@@ -477,4 +891,5 @@ ComponentTypes = {
     "tts": TTS,
     "unknown": Unknown,
     "file": File,
+    "WechatEmoji": WechatEmoji,
 }

astrbot/core/message/message_event_result.py

@@ -1,8 +1,14 @@
 import enum
 
-from typing import List, Optional
+from typing import List, Optional, Union, AsyncGenerator
 from dataclasses import dataclass, field
-from astrbot.core.message.components import BaseMessageComponent, Plain, Image
+from astrbot.core.message.components import (
+    BaseMessageComponent,
+    Plain,
+    Image,
+    At,
+    AtAll,
+)
 from typing_extensions import deprecated
 
 
@@ -18,6 +24,8 @@ class MessageChain:
 
     chain: List[BaseMessageComponent] = field(default_factory=list)
     use_t2i_: Optional[bool] = None  # None 为跟随用户设置
+    type: Optional[str] = None
+    """消息链承载的消息的类型。可选，用于让消息平台区分不同业务场景的消息链。"""
 
     def message(self, message: str):
         """添加一条文本消息到消息链 `chain` 中。
@@ -31,6 +39,30 @@ class MessageChain:
         self.chain.append(Plain(message))
         return self
 
+    def at(self, name: str, qq: Union[str, int]):
+        """添加一条 At 消息到消息链 `chain` 中。
+
+        Example:
+
+            CommandResult().at("张三", "12345678910")
+            # 输出 @张三
+
+        """
+        self.chain.append(At(name=name, qq=qq))
+        return self
+
+    def at_all(self):
+        """添加一条 AtAll 消息到消息链 `chain` 中。
+
+        Example:
+
+            CommandResult().at_all()
+            # 输出 @所有人
+
+        """
+        self.chain.append(AtAll())
+        return self
+
     @deprecated("请使用 message 方法代替。")
     def error(self, message: str):
         """添加一条错误消息到消息链 `chain` 中
@@ -68,6 +100,15 @@ class MessageChain:
         self.chain.append(Image.fromFileSystem(path))
         return self
 
+    def base64_image(self, base64_str: str):
+        """添加一条图片消息（base64 编码字符串）到消息链 `chain` 中。
+        Example:
+
+            CommandResult().base64_image("iVBORw0KGgoAAAANSUhEUgAAAAUA...")
+        """
+        self.chain.append(Image.fromBase64(base64_str))
+        return self
+
     def use_t2i(self, use_t2i: bool):
         """设置是否使用文本转图片服务。
 
@@ -77,6 +118,34 @@ class MessageChain:
         self.use_t2i_ = use_t2i
         return self
 
+    def get_plain_text(self) -> str:
+        """获取纯文本消息。这个方法将获取 chain 中所有 Plain 组件的文本并拼接成一条消息。空格分隔。"""
+        return " ".join([comp.text for comp in self.chain if isinstance(comp, Plain)])
+
+    def squash_plain(self):
+        """将消息链中的所有 Plain 消息段聚合到第一个 Plain 消息段中。"""
+        if not self.chain:
+            return
+
+        new_chain = []
+        first_plain = None
+        plain_texts = []
+
+        for comp in self.chain:
+            if isinstance(comp, Plain):
+                if first_plain is None:
+                    first_plain = comp
+                    new_chain.append(comp)
+                plain_texts.append(comp.text)
+            else:
+                new_chain.append(comp)
+
+        if first_plain is not None:
+            first_plain.text = "".join(plain_texts)
+
+        self.chain = new_chain
+        return self
+
 
 class EventResultType(enum.Enum):
     """用于描述事件处理的结果类型。
@@ -97,6 +166,10 @@ class ResultContentType(enum.Enum):
     """调用 LLM 产生的结果"""
     GENERAL_RESULT = enum.auto()
     """普通的消息结果"""
+    STREAMING_RESULT = enum.auto()
+    """调用 LLM 产生的流式结果"""
+    STREAMING_FINISH = enum.auto()
+    """流式输出完成"""
 
 
 @dataclass
@@ -118,6 +191,9 @@ class MessageEventResult(MessageChain):
         default_factory=lambda: ResultContentType.GENERAL_RESULT
     )
 
+    async_stream: Optional[AsyncGenerator] = None
+    """异步流"""
+
     def stop_event(self) -> "MessageEventResult":
         """终止事件传播。"""
         self.result_type = EventResultType.STOP
@@ -134,6 +210,11 @@ class MessageEventResult(MessageChain):
         """
         return self.result_type == EventResultType.STOP
 
+    def set_async_stream(self, stream: AsyncGenerator) -> "MessageEventResult":
+        """设置异步流。"""
+        self.async_stream = stream
+        return self
+
     def set_result_content_type(self, typ: ResultContentType) -> "MessageEventResult":
         """设置事件处理的结果类型。
 
@@ -147,9 +228,6 @@ class MessageEventResult(MessageChain):
         """是否为 LLM 结果。"""
         return self.result_content_type == ResultContentType.LLM_RESULT
 
-    def get_plain_text(self) -> str:
-        """获取纯文本消息。这个方法将获取所有 Plain 组件的文本并拼接成一条消息。空格分隔。"""
-        return " ".join([comp.text for comp in self.chain if isinstance(comp, Plain)])
-
 
+# 为了兼容旧版代码，保留 CommandResult 的别名
 CommandResult = MessageEventResult

astrbot/core/pipeline/__init__.py

@@ -1,22 +1,27 @@
 from astrbot.core.message.message_event_result import (
-    MessageEventResult,
     EventResultType,
+    MessageEventResult,
 )
 
-from .waking_check.stage import WakingCheckStage
-from .whitelist_check.stage import WhitelistCheckStage
-from .rate_limit_check.stage import RateLimitStage
 from .content_safety_check.stage import ContentSafetyCheckStage
+from .platform_compatibility.stage import PlatformCompatibilityStage
 from .preprocess_stage.stage import PreProcessStage
 from .process_stage.stage import ProcessStage
-from .result_decorate.stage import ResultDecorateStage
+from .rate_limit_check.stage import RateLimitStage
 from .respond.stage import RespondStage
+from .result_decorate.stage import ResultDecorateStage
+from .session_status_check.stage import SessionStatusCheckStage
+from .waking_check.stage import WakingCheckStage
+from .whitelist_check.stage import WhitelistCheckStage
 
+# 管道阶段顺序
 STAGES_ORDER = [
     "WakingCheckStage",  # 检查是否需要唤醒
     "WhitelistCheckStage",  # 检查是否在群聊/私聊白名单
+    "SessionStatusCheckStage",  # 检查会话是否整体启用
     "RateLimitStage",  # 检查会话是否超过频率限制
     "ContentSafetyCheckStage",  # 检查内容安全
+    "PlatformCompatibilityStage",  # 检查所有处理器的平台兼容性
     "PreProcessStage",  # 预处理
     "ProcessStage",  # 交由 Stars 处理（a.k.a 插件），或者 LLM 调用
     "ResultDecorateStage",  # 处理结果，比如添加回复前缀、t2i、转换为语音 等
@@ -26,8 +31,10 @@ STAGES_ORDER = [
 __all__ = [
     "WakingCheckStage",
     "WhitelistCheckStage",
+    "SessionStatusCheckStage",
     "RateLimitStage",
     "ContentSafetyCheckStage",
+    "PlatformCompatibilityStage",
     "PreProcessStage",
     "ProcessStage",
     "ResultDecorateStage",

astrbot/core/pipeline/context.py

@@ -1,9 +1,113 @@
+import inspect
+import traceback
+import typing as T
 from dataclasses import dataclass
 from astrbot.core.config.astrbot_config import AstrBotConfig
+from astrbot.core.platform.astr_message_event import AstrMessageEvent
 from astrbot.core.star import PluginManager
+from astrbot.api import logger
+from astrbot.core.star.star_handler import star_handlers_registry, EventType
+from astrbot.core.star.star import star_map
+from astrbot.core.message.message_event_result import MessageEventResult, CommandResult
 
 
 @dataclass
 class PipelineContext:
-    astrbot_config: AstrBotConfig
-    plugin_manager: PluginManager
+    """上下文对象，包含管道执行所需的上下文信息"""
+
+    astrbot_config: AstrBotConfig  # AstrBot 配置对象
+    plugin_manager: PluginManager  # 插件管理器对象
+
+    async def call_event_hook(
+        self,
+        event: AstrMessageEvent,
+        hook_type: EventType,
+        *args,
+    ) -> bool:
+        """调用事件钩子函数
+
+        Returns:
+            bool: 如果事件被终止，返回 True
+        """
+        platform_id = event.get_platform_id()
+        handlers = star_handlers_registry.get_handlers_by_event_type(
+            hook_type, platform_id=platform_id
+        )
+        for handler in handlers:
+            try:
+                logger.debug(
+                    f"hook(on_llm_request) -> {star_map[handler.handler_module_path].name} - {handler.handler_name}"
+                )
+                await handler.handler(event, *args)
+            except BaseException:
+                logger.error(traceback.format_exc())
+
+            if event.is_stopped():
+                logger.info(
+                    f"{star_map[handler.handler_module_path].name} - {handler.handler_name} 终止了事件传播。"
+                )
+
+        return event.is_stopped()
+
+    async def call_handler(
+        self,
+        event: AstrMessageEvent,
+        handler: T.Awaitable,
+        *args,
+        **kwargs,
+    ) -> T.AsyncGenerator[None, None]:
+        """执行事件处理函数并处理其返回结果
+
+        该方法负责调用处理函数并处理不同类型的返回值。它支持两种类型的处理函数:
+        1. 异步生成器: 实现洋葱模型，每次 yield 都会将控制权交回上层
+        2. 协程: 执行一次并处理返回值
+
+        Args:
+            ctx (PipelineContext): 消息管道上下文对象
+            event (AstrMessageEvent): 事件对象
+            handler (Awaitable): 事件处理函数
+
+        Returns:
+            AsyncGenerator[None, None]: 异步生成器，用于在管道中传递控制流
+        """
+        ready_to_call = None  # 一个协程或者异步生成器
+
+        trace_ = None
+
+        try:
+            ready_to_call = handler(event, *args, **kwargs)
+        except TypeError as _:
+            # 向下兼容
+            trace_ = traceback.format_exc()
+            # 以前的 handler 会额外传入一个参数, 但是 context 对象实际上在插件实例中有一份
+            ready_to_call = handler(event, self.plugin_manager.context, *args, **kwargs)
+
+        if inspect.isasyncgen(ready_to_call):
+            _has_yielded = False
+            try:
+                async for ret in ready_to_call:
+                    # 这里逐步执行异步生成器, 对于每个 yield 返回的 ret, 执行下面的代码
+                    # 返回值只能是 MessageEventResult 或者 None（无返回值）
+                    _has_yielded = True
+                    if isinstance(ret, (MessageEventResult, CommandResult)):
+                        # 如果返回值是 MessageEventResult, 设置结果并继续
+                        event.set_result(ret)
+                        yield
+                    else:
+                        # 如果返回值是 None, 则不设置结果并继续
+                        # 继续执行后续阶段
+                        yield ret
+                if not _has_yielded:
+                    # 如果这个异步生成器没有执行到 yield 分支
+                    yield
+            except Exception as e:
+                logger.error(f"Previous Error: {trace_}")
+                raise e
+        elif inspect.iscoroutine(ready_to_call):
+            # 如果只是一个协程, 直接执行
+            ret = await ready_to_call
+            if isinstance(ret, (MessageEventResult, CommandResult)):
+                event.set_result(ret)
+                yield
+            else:
+                yield ret

astrbot/core/pipeline/platform_compatibility/stage.py

@@ -0,0 +1,56 @@
+from ..stage import Stage, register_stage
+from ..context import PipelineContext
+from typing import Union, AsyncGenerator
+from astrbot.core.platform.astr_message_event import AstrMessageEvent
+from astrbot.core.star.star import star_map
+from astrbot.core.star.star_handler import StarHandlerMetadata
+from astrbot.core import logger
+
+
+@register_stage
+class PlatformCompatibilityStage(Stage):
+    """检查所有处理器的平台兼容性。
+
+    这个阶段会检查所有处理器是否在当前平台启用，如果未启用则设置platform_compatible属性为False。
+    """
+
+    async def initialize(self, ctx: PipelineContext) -> None:
+        """初始化平台兼容性检查阶段
+
+        Args:
+            ctx (PipelineContext): 消息管道上下文对象, 包括配置和插件管理器
+        """
+        self.ctx = ctx
+
+    async def process(
+        self, event: AstrMessageEvent
+    ) -> Union[None, AsyncGenerator[None, None]]:
+        # 获取当前平台ID
+        platform_id = event.get_platform_id()
+
+        # 获取已激活的处理器
+        activated_handlers = event.get_extra("activated_handlers")
+        if activated_handlers is None:
+            activated_handlers = []
+
+        # 标记不兼容的处理器
+        for handler in activated_handlers:
+            if not isinstance(handler, StarHandlerMetadata):
+                continue
+            # 检查处理器是否在当前平台启用
+            enabled = handler.is_enabled_for_platform(platform_id)
+            if not enabled:
+                if handler.handler_module_path in star_map:
+                    plugin_name = star_map[handler.handler_module_path].name
+                logger.debug(
+                    f"[PlatformCompatibilityStage] 插件 {plugin_name} 在平台 {platform_id} 未启用，标记处理器 {handler.handler_name} 为平台不兼容"
+                )
+                # 设置处理器为平台不兼容状态
+                # TODO: 更好的标记方式
+                handler.platform_compatible = False
+            else:
+                # 确保处理器为平台兼容状态
+                handler.platform_compatible = True
+
+        # 更新已激活的处理器列表
+        event.set_extra("activated_handlers", activated_handlers)

astrbot/core/pipeline/preprocess_stage/stage.py

@@ -43,31 +43,31 @@ class PreProcessStage(Stage):
         # STT
         if self.stt_settings.get("enable", False):
             # TODO: 独立
-            stt_provider = (
-                self.plugin_manager.context.provider_manager.curr_stt_provider_inst
-            )
-            if stt_provider:
-                message_chain = event.get_messages()
-                for idx, component in enumerate(message_chain):
-                    if isinstance(component, Record) and component.url:
-                        path = component.url.removeprefix("file://")
-                        retry = 5
-                        for i in range(retry):
-                            try:
-                                result = await stt_provider.get_text(audio_url=path)
-                                if result:
-                                    logger.info("语音转文本结果: " + result)
-                                    message_chain[idx] = Plain(result)
-                                    event.message_str += result
-                                    event.message_obj.message_str += result
-                                break
-                            except FileNotFoundError as e:
-                                # napcat workaround
-                                logger.warning(e)
-                                logger.warning(f"重试中: {i + 1}/{retry}")
-                                await asyncio.sleep(0.5)
-                                continue
-                            except BaseException as e:
-                                logger.error(traceback.format_exc())
-                                logger.error(f"语音转文本失败: {e}")
-                                break
+            ctx = self.plugin_manager.context
+            stt_provider = ctx.get_using_stt_provider(event.unified_msg_origin)
+            if not stt_provider:
+                return
+            message_chain = event.get_messages()
+            for idx, component in enumerate(message_chain):
+                if isinstance(component, Record) and component.url:
+                    path = component.url.removeprefix("file://")
+                    retry = 5
+                    for i in range(retry):
+                        try:
+                            result = await stt_provider.get_text(audio_url=path)
+                            if result:
+                                logger.info("语音转文本结果: " + result)
+                                message_chain[idx] = Plain(result)
+                                event.message_str += result
+                                event.message_obj.message_str += result
+                            break
+                        except FileNotFoundError as e:
+                            # napcat workaround
+                            logger.warning(e)
+                            logger.warning(f"重试中: {i + 1}/{retry}")
+                            await asyncio.sleep(0.5)
+                            continue
+                        except BaseException as e:
+                            logger.error(traceback.format_exc())
+                            logger.error(f"语音转文本失败: {e}")
+                            break

astrbot/core/pipeline/process_stage/agent_runner/base.py

@@ -0,0 +1,58 @@
+import abc
+import typing as T
+from dataclasses import dataclass
+from astrbot.core.provider.entities import LLMResponse
+from ....message.message_event_result import MessageChain
+from enum import Enum, auto
+
+
+class AgentState(Enum):
+    """Agent 状态枚举"""
+
+    IDLE = auto()  # 初始状态
+    RUNNING = auto()  # 运行中
+    DONE = auto()  # 完成
+    ERROR = auto()  # 错误状态
+
+
+class AgentResponseData(T.TypedDict):
+    chain: MessageChain
+
+
+@dataclass
+class AgentResponse:
+    type: str
+    data: AgentResponseData
+
+
+class BaseAgentRunner:
+    @abc.abstractmethod
+    async def reset(self) -> None:
+        """
+        Reset the agent to its initial state.
+        This method should be called before starting a new run.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def step(self) -> T.AsyncGenerator[AgentResponse, None]:
+        """
+        Process a single step of the agent.
+        """
+        ...
+
+    @abc.abstractmethod
+    def done(self) -> bool:
+        """
+        Check if the agent has completed its task.
+        Returns True if the agent is done, False otherwise.
+        """
+        ...
+
+    @abc.abstractmethod
+    def get_final_llm_resp(self) -> LLMResponse | None:
+        """
+        Get the final observation from the agent.
+        This method should be called after the agent is done.
+        """
+        ...

astrbot/core/pipeline/process_stage/agent_runner/tool_loop_agent.py

@@ -0,0 +1,306 @@
+import sys
+import traceback
+import typing as T
+from .base import BaseAgentRunner, AgentResponse, AgentResponseData, AgentState
+from ...context import PipelineContext
+from astrbot.core.provider.provider import Provider
+from astrbot.core.platform.astr_message_event import AstrMessageEvent
+from astrbot.core.message.message_event_result import (
+    MessageChain,
+)
+from astrbot.core.provider.entities import (
+    ProviderRequest,
+    LLMResponse,
+    ToolCallMessageSegment,
+    AssistantMessageSegment,
+    ToolCallsResult,
+)
+from mcp.types import (
+    TextContent,
+    ImageContent,
+    EmbeddedResource,
+    TextResourceContents,
+    BlobResourceContents,
+)
+from astrbot.core.star.star_handler import EventType
+from astrbot import logger
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+
+# TODO:
+# 1. 处理平台不兼容的处理器
+
+
+class ToolLoopAgent(BaseAgentRunner):
+    def __init__(
+        self, provider: Provider, event: AstrMessageEvent, pipeline_ctx: PipelineContext
+    ) -> None:
+        self.provider = provider
+        self.req = None
+        self.event = event
+        self.pipeline_ctx = pipeline_ctx
+        self._state = AgentState.IDLE
+        self.final_llm_resp = None
+        self.streaming = False
+
+    @override
+    async def reset(self, req: ProviderRequest, streaming: bool) -> None:
+        self.req = req
+        self.streaming = streaming
+        self.final_llm_resp = None
+        self._state = AgentState.IDLE
+
+    def _transition_state(self, new_state: AgentState) -> None:
+        """转换 Agent 状态"""
+        if self._state != new_state:
+            logger.debug(f"Agent state transition: {self._state} -> {new_state}")
+            self._state = new_state
+
+    async def _iter_llm_responses(self) -> T.AsyncGenerator[LLMResponse, None]:
+        """Yields chunks *and* a final LLMResponse."""
+        if self.streaming:
+            stream = self.provider.text_chat_stream(**self.req.__dict__)
+            async for resp in stream:  # type: ignore
+                yield resp
+        else:
+            yield await self.provider.text_chat(**self.req.__dict__)
+
+    @override
+    async def step(self):
+        """
+        Process a single step of the agent.
+        This method should return the result of the step.
+        """
+        if not self.req:
+            raise ValueError("Request is not set. Please call reset() first.")
+
+        # 开始处理，转换到运行状态
+        self._transition_state(AgentState.RUNNING)
+        llm_resp_result = None
+
+        async for llm_response in self._iter_llm_responses():
+            assert isinstance(llm_response, LLMResponse)
+            if llm_response.is_chunk:
+                if llm_response.result_chain:
+                    yield AgentResponse(
+                        type="streaming_delta",
+                        data=AgentResponseData(chain=llm_response.result_chain),
+                    )
+                else:
+                    yield AgentResponse(
+                        type="streaming_delta",
+                        data=AgentResponseData(
+                            chain=MessageChain().message(llm_response.completion_text)
+                        ),
+                    )
+                continue
+            llm_resp_result = llm_response
+            break  # got final response
+
+        if not llm_resp_result:
+            return
+
+        # 处理 LLM 响应
+        llm_resp = llm_resp_result
+
+        if llm_resp.role == "err":
+            # 如果 LLM 响应错误，转换到错误状态
+            self.final_llm_resp = llm_resp
+            self._transition_state(AgentState.ERROR)
+            yield AgentResponse(
+                type="err",
+                data=AgentResponseData(
+                    chain=MessageChain().message(
+                        f"LLM 响应错误: {llm_resp.completion_text or '未知错误'}"
+                    )
+                ),
+            )
+
+        if not llm_resp.tools_call_name:
+            # 如果没有工具调用，转换到完成状态
+            self.final_llm_resp = llm_resp
+            self._transition_state(AgentState.DONE)
+
+            # 执行事件钩子
+            if await self.pipeline_ctx.call_event_hook(
+                self.event, EventType.OnLLMResponseEvent, llm_resp
+            ):
+                return
+
+        # 返回 LLM 结果
+        if llm_resp.result_chain:
+            yield AgentResponse(
+                type="llm_result",
+                data=AgentResponseData(chain=llm_resp.result_chain),
+            )
+        elif llm_resp.completion_text:
+            yield AgentResponse(
+                type="llm_result",
+                data=AgentResponseData(
+                    chain=MessageChain().message(llm_resp.completion_text)
+                ),
+            )
+
+        # 如果有工具调用，还需处理工具调用
+        if llm_resp.tools_call_name:
+            tool_call_result_blocks = []
+            for tool_call_name in llm_resp.tools_call_name:
+                yield AgentResponse(
+                    type="tool_call",
+                    data=AgentResponseData(
+                        chain=MessageChain().message(f"🔨 调用工具: {tool_call_name}")
+                    ),
+                )
+            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):
+                    yield AgentResponse(
+                        type="tool_call_result",
+                        data=AgentResponseData(chain=result),
+                    )
+            # 将结果添加到上下文中
+            tool_calls_result = ToolCallsResult(
+                tool_calls_info=AssistantMessageSegment(
+                    role="assistant",
+                    tool_calls=llm_resp.to_openai_tool_calls(),
+                    content=llm_resp.completion_text,
+                ),
+                tool_calls_result=tool_call_result_blocks,
+            )
+            self.req.append_tool_calls_result(tool_calls_result)
+
+    async def _handle_function_tools(
+        self,
+        req: ProviderRequest,
+        llm_response: LLMResponse,
+    ) -> T.AsyncGenerator[MessageChain | list[ToolCallMessageSegment], None]:
+        """处理函数工具调用。"""
+        tool_call_result_blocks: list[ToolCallMessageSegment] = []
+        logger.info(f"Agent 使用工具: {llm_response.tools_call_name}")
+
+        # 执行函数调用
+        for func_tool_name, func_tool_args, func_tool_id in zip(
+            llm_response.tools_call_name,
+            llm_response.tools_call_args,
+            llm_response.tools_call_ids,
+        ):
+            try:
+                if not req.func_tool:
+                    return
+                func_tool = req.func_tool.get_func(func_tool_name)
+                if func_tool.origin == "mcp":
+                    logger.info(
+                        f"从 MCP 服务 {func_tool.mcp_server_name} 调用工具函数：{func_tool.name}，参数：{func_tool_args}"
+                    )
+                    client = req.func_tool.mcp_client_dict[func_tool.mcp_server_name]
+                    res = await client.session.call_tool(func_tool.name, func_tool_args)
+                    if not res:
+                        continue
+                    if isinstance(res.content[0], TextContent):
+                        tool_call_result_blocks.append(
+                            ToolCallMessageSegment(
+                                role="tool",
+                                tool_call_id=func_tool_id,
+                                content=res.content[0].text,
+                            )
+                        )
+                        yield MessageChain().message(res.content[0].text)
+                    elif isinstance(res.content[0], ImageContent):
+                        tool_call_result_blocks.append(
+                            ToolCallMessageSegment(
+                                role="tool",
+                                tool_call_id=func_tool_id,
+                                content="返回了图片(已直接发送给用户)",
+                            )
+                        )
+                        yield MessageChain(type="tool_direct_result").base64_image(
+                            res.content[0].data
+                        )
+                    elif isinstance(res.content[0], EmbeddedResource):
+                        resource = res.content[0].resource
+                        if isinstance(resource, TextResourceContents):
+                            tool_call_result_blocks.append(
+                                ToolCallMessageSegment(
+                                    role="tool",
+                                    tool_call_id=func_tool_id,
+                                    content=resource.text,
+                                )
+                            )
+                            yield MessageChain().message(resource.text)
+                        elif (
+                            isinstance(resource, BlobResourceContents)
+                            and resource.mimeType
+                            and resource.mimeType.startswith("image/")
+                        ):
+                            tool_call_result_blocks.append(
+                                ToolCallMessageSegment(
+                                    role="tool",
+                                    tool_call_id=func_tool_id,
+                                    content="返回了图片(已直接发送给用户)",
+                                )
+                            )
+                            yield MessageChain(type="tool_direct_result").base64_image(
+                                res.content[0].data
+                            )
+                        else:
+                            tool_call_result_blocks.append(
+                                ToolCallMessageSegment(
+                                    role="tool",
+                                    tool_call_id=func_tool_id,
+                                    content="返回的数据类型不受支持",
+                                )
+                            )
+                            yield MessageChain().message("返回的数据类型不受支持。")
+                else:
+                    logger.info(f"使用工具：{func_tool_name}，参数：{func_tool_args}")
+                    # 尝试调用工具函数
+                    wrapper = self.pipeline_ctx.call_handler(
+                        self.event, func_tool.handler, **func_tool_args
+                    )
+                    async for resp in wrapper:
+                        if resp is not None:
+                            # Tool 返回结果
+                            tool_call_result_blocks.append(
+                                ToolCallMessageSegment(
+                                    role="tool",
+                                    tool_call_id=func_tool_id,
+                                    content=resp,
+                                )
+                            )
+                            yield MessageChain().message(resp)
+                        else:
+                            # Tool 直接请求发送消息给用户
+                            # 这里我们将直接结束 Agent Loop。
+                            self._transition_state(AgentState.DONE)
+                            if res := self.event.get_result():
+                                if res.chain:
+                                    yield MessageChain(
+                                        chain=res.chain, type="tool_direct_result"
+                                    )
+
+                self.event.clear_result()
+            except Exception as e:
+                logger.warning(traceback.format_exc())
+                tool_call_result_blocks.append(
+                    ToolCallMessageSegment(
+                        role="tool",
+                        tool_call_id=func_tool_id,
+                        content=f"error: {str(e)}",
+                    )
+                )
+
+        # 处理函数调用响应
+        if tool_call_result_blocks:
+            yield tool_call_result_blocks
+
+    def done(self) -> bool:
+        """检查 Agent 是否已完成工作"""
+        return self._state in (AgentState.DONE, AgentState.ERROR)
+
+    def get_final_llm_resp(self) -> LLMResponse | None:
+        return self.final_llm_resp

astrbot/core/pipeline/process_stage/method/llm_request.py

@@ -2,32 +2,47 @@
 本地 Agent 模式的 LLM 调用 Stage
 """
 
-import traceback
 import asyncio
+import copy
 import json
-from typing import Union, AsyncGenerator
-from ...context import PipelineContext
-from ..stage import Stage
-from astrbot.core.platform.astr_message_event import AstrMessageEvent
+import traceback
+from typing import AsyncGenerator, Union
+from astrbot.core import logger
+from astrbot.core.message.components import Image
 from astrbot.core.message.message_event_result import (
+    MessageChain,
     MessageEventResult,
     ResultContentType,
 )
-from astrbot.core.message.components import Image
-from astrbot.core import logger
+from astrbot.core.platform.astr_message_event import AstrMessageEvent
+from astrbot.core.provider import Provider
+from astrbot.core.provider.entities import (
+    LLMResponse,
+    ProviderRequest,
+)
+from astrbot.core.star.session_llm_manager import SessionServiceManager
+from astrbot.core.star.star_handler import EventType
 from astrbot.core.utils.metrics import Metric
-from astrbot.core.provider.entites import ProviderRequest, LLMResponse
-from astrbot.core.star.star_handler import star_handlers_registry, EventType
-from astrbot.core.star.star import star_map
+from ...context import PipelineContext
+from ..agent_runner.tool_loop_agent import ToolLoopAgent
+from ..stage import Stage
 
 
 class LLMRequestSubStage(Stage):
     async def initialize(self, ctx: PipelineContext) -> None:
         self.ctx = ctx
-        self.bot_wake_prefixs = ctx.astrbot_config["wake_prefix"]  # list
-        self.provider_wake_prefix = ctx.astrbot_config["provider_settings"][
-            "wake_prefix"
-        ]  # str
+        conf = ctx.astrbot_config
+        settings = conf["provider_settings"]
+        self.bot_wake_prefixs: list[str] = conf["wake_prefix"]  # list
+        self.provider_wake_prefix: str = settings["wake_prefix"]  # str
+        self.max_context_length = settings["max_context_length"]  # int
+        self.dequeue_context_length: int = min(
+            max(1, settings["dequeue_context_length"]),
+            self.max_context_length - 1,
+        )
+        self.streaming_response: bool = settings["streaming_response"]
+        self.max_step: int = settings.get("max_agent_step", 10)
+        self.show_tool_use: bool = settings.get("show_tool_use_status", True)
 
         for bwp in self.bot_wake_prefixs:
             if self.provider_wake_prefix.startswith(bwp):
@@ -38,12 +53,33 @@ class LLMRequestSubStage(Stage):
 
         self.conv_manager = ctx.plugin_manager.context.conversation_manager
 
+    def _select_provider(self, event: AstrMessageEvent) -> Provider | None:
+        """选择使用的 LLM 提供商"""
+        sel_provider = event.get_extra("selected_provider")
+        _ctx = self.ctx.plugin_manager.context
+        if sel_provider and isinstance(sel_provider, str):
+            provider = _ctx.get_provider_by_id(sel_provider)
+            if not provider:
+                logger.error(f"未找到指定的提供商: {sel_provider}。")
+            return provider
+
+        return _ctx.get_using_provider(umo=event.unified_msg_origin)
+
     async def process(
         self, event: AstrMessageEvent, _nested: bool = False
     ) -> Union[None, AsyncGenerator[None, None]]:
-        req: ProviderRequest = None
+        req: ProviderRequest | None = None
 
-        provider = self.ctx.plugin_manager.context.get_using_provider()
+        if not self.ctx.astrbot_config["provider_settings"]["enable"]:
+            logger.debug("未启用 LLM 能力，跳过处理。")
+            return
+
+        # 检查会话级别的LLM启停状态
+        if not SessionServiceManager.should_process_llm_request(event):
+            logger.debug(f"会话 {event.unified_msg_origin} 禁用了 LLM，跳过处理。")
+            return
+
+        provider = self._select_provider(event)
         if provider is None:
             return
 
@@ -55,8 +91,11 @@ class LLMRequestSubStage(Stage):
 
             if req.conversation:
                 req.contexts = json.loads(req.conversation.history)
+
         else:
             req = ProviderRequest(prompt="", image_urls=[])
+            if sel_model := event.get_extra("selected_model"):
+                req.model = sel_model
             if self.provider_wake_prefix:
                 if not event.message_str.startswith(self.provider_wake_prefix):
                     return
@@ -64,8 +103,8 @@ class LLMRequestSubStage(Stage):
             req.func_tool = self.ctx.plugin_manager.context.get_llm_tool_manager()
             for comp in event.message_obj.message:
                 if isinstance(comp, Image):
-                    image_url = comp.url if comp.url else comp.file
-                    req.image_urls.append(image_url)
+                    image_path = await comp.convert_to_file_path()
+                    req.image_urls.append(image_path)
 
             # 获取对话上下文
             conversation_id = await self.conv_manager.get_curr_conversation_id(
@@ -75,10 +114,16 @@ class LLMRequestSubStage(Stage):
                 conversation_id = await self.conv_manager.new_conversation(
                     event.unified_msg_origin
                 )
-            req.session_id = event.unified_msg_origin
             conversation = await self.conv_manager.get_conversation(
                 event.unified_msg_origin, conversation_id
             )
+            if not conversation:
+                conversation_id = await self.conv_manager.new_conversation(
+                    event.unified_msg_origin
+                )
+                conversation = await self.conv_manager.get_conversation(
+                    event.unified_msg_origin, conversation_id
+                )
             req.conversation = conversation
             req.contexts = json.loads(conversation.history)
 
@@ -88,150 +133,237 @@ class LLMRequestSubStage(Stage):
             return
 
         # 执行请求 LLM 前事件钩子。
-        # 装饰 system_prompt 等功能
-        handlers = star_handlers_registry.get_handlers_by_event_type(
-            EventType.OnLLMRequestEvent
-        )
-        for handler in handlers:
-            try:
-                logger.debug(
-                    f"hook(on_llm_request) -> {star_map[handler.handler_module_path].name} - {handler.handler_name}"
-                )
-                await handler.handler(event, req)
-            except BaseException:
-                logger.error(traceback.format_exc())
-
-            if event.is_stopped():
-                logger.info(
-                    f"{star_map[handler.handler_module_path].name} - {handler.handler_name} 终止了事件传播。"
-                )
-                return
+        if await self.ctx.call_event_hook(event, EventType.OnLLMRequestEvent, req):
+            return
 
         if isinstance(req.contexts, str):
             req.contexts = json.loads(req.contexts)
 
-        try:
-            logger.debug(f"提供商请求 Payload: {req}")
-            if _nested:
-                req.func_tool = None  # 暂时不支持递归工具调用
-            llm_response = await provider.text_chat(**req.__dict__)  # 请求 LLM
-
-            # 执行 LLM 响应后的事件钩子。
-            handlers = star_handlers_registry.get_handlers_by_event_type(
-                EventType.OnLLMResponseEvent
+        # max context length
+        if (
+            self.max_context_length != -1  # -1 为不限制
+            and len(req.contexts) // 2 > self.max_context_length
+        ):
+            logger.debug("上下文长度超过限制，将截断。")
+            req.contexts = req.contexts[
+                -(self.max_context_length - self.dequeue_context_length + 1) * 2 :
+            ]
+            # 找到第一个role 为 user 的索引，确保上下文格式正确
+            index = next(
+                (
+                    i
+                    for i, item in enumerate(req.contexts)
+                    if item.get("role") == "user"
+                ),
+                None,
             )
-            for handler in handlers:
-                try:
-                    logger.debug(
-                        f"hook(on_llm_response) -> {star_map[handler.handler_module_path].name} - {handler.handler_name}"
-                    )
-                    await handler.handler(event, llm_response)
-                except BaseException:
-                    logger.error(traceback.format_exc())
+            if index is not None and index > 0:
+                req.contexts = req.contexts[index:]
 
-                if event.is_stopped():
-                    logger.info(
-                        f"{star_map[handler.handler_module_path].name} - {handler.handler_name} 终止了事件传播。"
+        # session_id
+        if not req.session_id:
+            req.session_id = event.unified_msg_origin
+
+        # fix messages
+        req.contexts = self.fix_messages(req.contexts)
+
+        # Call Agent
+        tool_loop_agent = ToolLoopAgent(
+            provider=provider,
+            event=event,
+            pipeline_ctx=self.ctx,
+        )
+        logger.debug(
+            f"handle provider[id: {provider.provider_config['id']}] request: {req}"
+        )
+        await tool_loop_agent.reset(req=req, streaming=self.streaming_response)
+
+        async def requesting():
+            step_idx = 0
+            while step_idx < self.max_step:
+                step_idx += 1
+                try:
+                    async for resp in tool_loop_agent.step():
+                        if event.is_stopped():
+                            return
+                        if resp.type == "tool_call_result":
+                            msg_chain = resp.data["chain"]
+                            if msg_chain.type == "tool_direct_result":
+                                # tool_direct_result 用于标记 llm tool 需要直接发送给用户的内容
+                                resp.data["chain"].type = "tool_call_result"
+                                await event.send(resp.data["chain"])
+                                continue
+                            # 对于其他情况，暂时先不处理
+                            continue
+                        elif resp.type == "tool_call":
+                            if self.streaming_response:
+                                # 用来标记流式响应需要分节
+                                yield MessageChain(chain=[], type="break")
+                            if (
+                                self.show_tool_use
+                                or event.get_platform_name() == "webchat"
+                            ):
+                                resp.data["chain"].type = "tool_call"
+                                await event.send(resp.data["chain"])
+                            continue
+
+                        if not self.streaming_response:
+                            content_typ = (
+                                ResultContentType.LLM_RESULT
+                                if resp.type == "llm_result"
+                                else ResultContentType.GENERAL_RESULT
+                            )
+                            event.set_result(
+                                MessageEventResult(
+                                    chain=resp.data["chain"].chain,
+                                    result_content_type=content_typ,
+                                )
+                            )
+                            yield
+                            event.clear_result()
+                        else:
+                            if resp.type == "streaming_delta":
+                                yield resp.data["chain"]  # MessageChain
+                    if tool_loop_agent.done():
+                        break
+
+                except Exception as e:
+                    logger.error(traceback.format_exc())
+                    event.set_result(
+                        MessageEventResult().message(
+                            f"AstrBot 请求失败。\n错误类型: {type(e).__name__}\n错误信息: {str(e)}\n\n请在控制台查看和分享错误详情。\n"
+                        )
                     )
                     return
-
-            # 保存到历史记录
-            await self._save_to_history(event, req, llm_response)
-
-            asyncio.create_task(
-                Metric.upload(
-                    llm_tick=1,
-                    model_name=provider.get_model(),
-                    provider_type=provider.meta().type,
-                )
-            )
-
-            if llm_response.role == "assistant":
-                # text completion
-                event.set_result(
-                    MessageEventResult()
-                    .message(llm_response.completion_text)
-                    .set_result_content_type(ResultContentType.LLM_RESULT)
-                )
-            elif llm_response.role == "err":
-                event.set_result(
-                    MessageEventResult().message(
-                        f"AstrBot 请求失败。\n错误信息: {llm_response.completion_text}"
+                asyncio.create_task(
+                    Metric.upload(
+                        llm_tick=1,
+                        model_name=provider.get_model(),
+                        provider_type=provider.meta().type,
                     )
                 )
-            elif llm_response.role == "tool":
-                # function calling
-                function_calling_result = {}
-                logger.info(
-                    f"触发 {len(llm_response.tools_call_name)} 个函数调用: {llm_response.tools_call_name}"
-                )
-                for func_tool_name, func_tool_args in zip(
-                    llm_response.tools_call_name, llm_response.tools_call_args
-                ):
-                    func_tool = req.func_tool.get_func(func_tool_name)
-                    logger.info(
-                        f"调用工具函数：{func_tool_name}，参数：{func_tool_args}"
-                    )
-                    try:
-                        # 尝试调用工具函数
-                        wrapper = self._call_handler(
-                            self.ctx, event, func_tool.handler, **func_tool_args
-                        )
-                        async for resp in wrapper:
-                            if resp is not None:  # 有 return 返回
-                                function_calling_result[func_tool_name] = resp
-                            else:
-                                yield  # 有生成器返回
-                        event.clear_result()  # 清除上一个 handler 的结果
-                    except BaseException as e:
-                        logger.warning(traceback.format_exc())
-                        function_calling_result[func_tool_name] = (
-                            "When calling the function, an error occurred: " + str(e)
-                        )
-                if function_calling_result:
-                    # 工具返回 LLM 资源。比如 RAG、网页 得到的相关结果等。
-                    # 我们重新执行一遍这个 stage
-                    req.func_tool = None  # 暂时不支持递归工具调用
-                    extra_prompt = "\n\nSystem executed some external tools for this task and here are the results:\n"
-                    for tool_name, tool_result in function_calling_result.items():
-                        extra_prompt += (
-                            f"Tool: {tool_name}\nTool Result: {tool_result}\n"
-                        )
-                    req.prompt += extra_prompt
-                    async for _ in self.process(event, _nested=True):
-                        yield
-                else:
-                    if llm_response.completion_text:
-                        event.set_result(
-                            MessageEventResult().message(llm_response.completion_text)
-                        )
 
-        except BaseException as e:
-            logger.error(traceback.format_exc())
+        if self.streaming_response:
+            # 流式响应
             event.set_result(
-                MessageEventResult().message(
-                    f"AstrBot 请求失败。\n错误类型: {type(e).__name__}\n错误信息: {str(e)}"
-                )
+                MessageEventResult()
+                .set_result_content_type(ResultContentType.STREAMING_RESULT)
+                .set_async_stream(requesting())
             )
-            return
+            yield
+            if tool_loop_agent.done():
+                if final_llm_resp := tool_loop_agent.get_final_llm_resp():
+                    if final_llm_resp.completion_text:
+                        chain = (
+                            MessageChain().message(final_llm_resp.completion_text).chain
+                        )
+                    else:
+                        chain = final_llm_resp.result_chain.chain
+                    event.set_result(
+                        MessageEventResult(
+                            chain=chain,
+                            result_content_type=ResultContentType.STREAMING_FINISH,
+                        )
+                    )
+        else:
+            async for _ in requesting():
+                yield
+
+        # 异步处理 WebChat 特殊情况
+        if event.get_platform_name() == "webchat":
+            asyncio.create_task(self._handle_webchat(event, req, provider))
+
+        await self._save_to_history(event, req, tool_loop_agent.get_final_llm_resp())
+
+    async def _handle_webchat(
+        self, event: AstrMessageEvent, req: ProviderRequest, prov: Provider
+    ):
+        """处理 WebChat 平台的特殊情况，包括第一次 LLM 对话时总结对话内容生成 title"""
+        conversation = await self.conv_manager.get_conversation(
+            event.unified_msg_origin, req.conversation.cid
+        )
+        if conversation and not req.conversation.title:
+            messages = json.loads(conversation.history)
+            latest_pair = messages[-2:]
+            if not latest_pair:
+                return
+            cleaned_text = "User: " + latest_pair[0].get("content", "").strip()
+            logger.debug(f"WebChat 对话标题生成请求，清理后的文本: {cleaned_text}")
+            llm_resp = await prov.text_chat(
+                system_prompt="You are expert in summarizing user's query.",
+                prompt=(
+                    f"Please summarize the following query of user:\n"
+                    f"{cleaned_text}\n"
+                    "Only output the summary within 10 words, DO NOT INCLUDE any other text."
+                    "You must use the same language as the user."
+                    "If you think the dialog is too short to summarize, only output a special mark: `<None>`"
+                ),
+            )
+            if llm_resp and llm_resp.completion_text:
+                logger.debug(
+                    f"WebChat 对话标题生成响应: {llm_resp.completion_text.strip()}"
+                )
+                title = llm_resp.completion_text.strip()
+                if not title or "<None>" in title:
+                    return
+                await self.conv_manager.update_conversation_title(
+                    event.unified_msg_origin, title=title
+                )
+                # 由于 WebChat 平台特殊性，其有两个对话，因此我们要更新两个对话的标题
+                # webchat adapter 中，session_id 的格式是 f"webchat!{username}!{cid}"
+                # TODO: 优化 WebChat 适配器的对话管理
+                if event.session_id:
+                    username, cid = event.session_id.split("!")[1:3]
+                    db_helper = self.ctx.plugin_manager.context._db
+                    db_helper.update_conversation_title(
+                        user_id=username,
+                        cid=cid,
+                        title=title,
+                    )
 
     async def _save_to_history(
-        self, event: AstrMessageEvent, req: ProviderRequest, llm_response: LLMResponse
+        self,
+        event: AstrMessageEvent,
+        req: ProviderRequest,
+        llm_response: LLMResponse | None,
     ):
-        if not req or not req.conversation or not llm_response:
+        if (
+            not req
+            or not req.conversation
+            or not llm_response
+            or llm_response.role != "assistant"
+        ):
             return
 
-        if llm_response.role == "assistant":
-            # 文本回复
-            contexts = req.contexts
-            new_record = {"role": "user", "content": req.prompt}
-            contexts.append(new_record)
-            contexts.append(
-                {"role": "assistant", "content": llm_response.completion_text}
-            )
-            contexts_to_save = list(
-                filter(lambda item: "_no_save" not in item, contexts)
-            )
-            await self.conv_manager.update_conversation(
-                event.unified_msg_origin, req.conversation.cid, history=contexts_to_save
-            )
+        # 历史上下文
+        messages = copy.deepcopy(req.contexts)
+        # 这一轮对话请求的用户输入
+        messages.append(await req.assemble_context())
+        # 这一轮对话的 LLM 响应
+        if req.tool_calls_result:
+            if not isinstance(req.tool_calls_result, list):
+                messages.extend(req.tool_calls_result.to_openai_messages())
+            elif isinstance(req.tool_calls_result, list):
+                for tcr in req.tool_calls_result:
+                    messages.extend(tcr.to_openai_messages())
+        messages.append({"role": "assistant", "content": llm_response.completion_text})
+        messages = list(filter(lambda item: "_no_save" not in item, messages))
+        await self.conv_manager.update_conversation(
+            event.unified_msg_origin, req.conversation.cid, history=messages
+        )
+
+    def fix_messages(self, messages: list[dict]) -> list[dict]:
+        """验证并且修复上下文"""
+        fixed_messages = []
+        for message in messages:
+            if message.get("role") == "tool":
+                # tool block 前面必须要有 user 和 assistant block
+                if len(fixed_messages) < 2:
+                    # 这种情况可能是上下文被截断导致的
+                    # 我们直接将之前的上下文都清空
+                    fixed_messages = []
+                else:
+                    fixed_messages.append(message)
+            else:
+                fixed_messages.append(message)
+        return fixed_messages

astrbot/core/pipeline/process_stage/method/star_request.py

@@ -31,7 +31,18 @@ class StarRequestSubStage(Stage):
         )
         if not handlers_parsed_params:
             handlers_parsed_params = {}
+
         for handler in activated_handlers:
+            # 检查处理器是否在当前平台兼容
+            if (
+                hasattr(handler, "platform_compatible")
+                and handler.platform_compatible is False
+            ):
+                logger.debug(
+                    f"处理器 {handler.handler_name} 在当前平台不兼容，跳过执行"
+                )
+                continue
+
             params = handlers_parsed_params.get(handler.handler_full_name, {})
             try:
                 if handler.handler_module_path not in star_map:
@@ -39,7 +50,7 @@ class StarRequestSubStage(Stage):
                 logger.debug(
                     f"plugin -> {star_map.get(handler.handler_module_path).name} - {handler.handler_name}"
                 )
-                wrapper = self._call_handler(self.ctx, event, handler.handler, **params)
+                wrapper = self.ctx.call_handler(event, handler.handler, **params)
                 async for ret in wrapper:
                     yield ret
                 event.clear_result()  # 清除上一个 handler 的结果

astrbot/core/pipeline/process_stage/stage.py

@@ -5,7 +5,7 @@ from .method.llm_request import LLMRequestSubStage
 from .method.star_request import StarRequestSubStage
 from astrbot.core.platform.astr_message_event import AstrMessageEvent
 from astrbot.core.star.star_handler import StarHandlerMetadata
-from astrbot.core.provider.entites import ProviderRequest
+from astrbot.core.provider.entities import ProviderRequest
 from astrbot.core import logger
 
 

astrbot/core/pipeline/rate_limit_check/stage.py

@@ -58,33 +58,30 @@ class RateLimitStage(Stage):
         now = datetime.now()
 
         async with self.locks[session_id]:  # 确保同一会话不会并发修改队列
-            timestamps = self.event_timestamps[session_id]
+            # 检查并处理限流，可能需要多次检查直到满足条件
+            while True:
+                timestamps = self.event_timestamps[session_id]
+                self._remove_expired_timestamps(timestamps, now)
 
-            self._remove_expired_timestamps(timestamps, now)
+                if len(timestamps) < self.rate_limit_count:
+                    timestamps.append(now)
+                    break
+                else:
+                    next_window_time = timestamps[0] + self.rate_limit_time
+                    stall_duration = (next_window_time - now).total_seconds() + 0.3
 
-            if len(timestamps) >= self.rate_limit_count:
-                # 达到限流阈值，计算下一个窗口的时间
-                next_window_time = timestamps[0] + self.rate_limit_time
-                stall_duration = (next_window_time - now).total_seconds()
-
-                match self.rl_strategy:
-                    case RateLimitStrategy.STALL.value:
-                        logger.info(
-                            f"会话 {session_id} 被限流。根据限流策略，此会话处理将被暂停 {stall_duration:.2f} 秒。"
-                        )
-                        await asyncio.sleep(stall_duration)
-                    case RateLimitStrategy.DISCARD.value:
-                        # event.set_result(MessageEventResult().message(f"会话 {session_id} 被限流。根据限流策略，此请求已被丢弃，直到您的限额于 {stall_duration:.2f} 秒后重置。"))
-                        logger.info(
-                            f"会话 {session_id} 被限流。根据限流策略，此请求已被丢弃，直到限额于 {stall_duration:.2f} 秒后重置。"
-                        )
-                        return event.stop_event()
-
-                self._remove_expired_timestamps(
-                    timestamps, now + timedelta(seconds=stall_duration)
-                )
-
-            timestamps.append(now)
+                    match self.rl_strategy:
+                        case RateLimitStrategy.STALL.value:
+                            logger.info(
+                                f"会话 {session_id} 被限流。根据限流策略，此会话处理将被暂停 {stall_duration:.2f} 秒。"
+                            )
+                            await asyncio.sleep(stall_duration)
+                            now = datetime.now()
+                        case RateLimitStrategy.DISCARD.value:
+                            logger.info(
+                                f"会话 {session_id} 被限流。根据限流策略，此请求已被丢弃，直到限额于 {stall_duration:.2f} 秒后重置。"
+                            )
+                            return event.stop_event()
 
     def _remove_expired_timestamps(
         self, timestamps: Deque[datetime], now: datetime

astrbot/core/pipeline/respond/stage.py

@@ -2,22 +2,44 @@ import random
 import asyncio
 import math
 import traceback
+import astrbot.core.message.components as Comp
 from typing import Union, AsyncGenerator
 from ..stage import register_stage, Stage
 from ..context import PipelineContext
 from astrbot.core.platform.astr_message_event import AstrMessageEvent
-from astrbot.core.message.message_event_result import MessageChain
+from astrbot.core.message.message_event_result import MessageChain, ResultContentType
 from astrbot.core import logger
 from astrbot.core.message.message_event_result import BaseMessageComponent
 from astrbot.core.star.star_handler import star_handlers_registry, EventType
 from astrbot.core.star.star import star_map
-from astrbot.core.message.components import Plain, Reply, At
+from astrbot.core.utils.path_util import path_Mapping
+from astrbot.core.utils.session_lock import session_lock_manager
 
 
 @register_stage
 class RespondStage(Stage):
+    # 组件类型到其非空判断函数的映射
+    _component_validators = {
+        Comp.Plain: lambda comp: bool(
+            comp.text and comp.text.strip()
+        ),  # 纯文本消息需要strip
+        Comp.Face: lambda comp: comp.id is not None,  # QQ表情
+        Comp.Record: lambda comp: bool(comp.file),  # 语音
+        Comp.Video: lambda comp: bool(comp.file),  # 视频
+        Comp.At: lambda comp: bool(comp.qq) or bool(comp.name),  # @
+        Comp.Image: lambda comp: bool(comp.file),  # 图片
+        Comp.Reply: lambda comp: bool(comp.id) and comp.sender_id is not None,  # 回复
+        Comp.Poke: lambda comp: comp.id != 0 and comp.qq != 0,  # 戳一戳
+        Comp.Node: lambda comp: bool(comp.content),  # 转发节点
+        Comp.Nodes: lambda comp: bool(comp.nodes),  # 多个转发节点
+        Comp.File: lambda comp: bool(comp.file_ or comp.url),
+        Comp.WechatEmoji: lambda comp: comp.md5 is not None,  # 微信表情
+    }
+
     async def initialize(self, ctx: PipelineContext):
         self.ctx = ctx
+        self.config = ctx.astrbot_config
+        self.platform_settings: dict = self.config.get("platform_settings", {})
 
         self.reply_with_mention = ctx.astrbot_config["platform_settings"][
             "reply_with_mention"
@@ -62,7 +84,7 @@ class RespondStage(Stage):
     async def _calc_comp_interval(self, comp: BaseMessageComponent) -> float:
         """分段回复 计算间隔时间"""
         if self.interval_method == "log":
-            if isinstance(comp, Plain):
+            if isinstance(comp, Comp.Plain):
                 wc = await self._word_cnt(comp.text)
                 i = math.log(wc + 1, self.log_base)
                 return random.uniform(i, i + 0.5)
@@ -72,47 +94,129 @@ class RespondStage(Stage):
             # random
             return random.uniform(self.interval[0], self.interval[1])
 
+    async def _is_empty_message_chain(self, chain: list[BaseMessageComponent]):
+        """检查消息链是否为空
+
+        Args:
+            chain (list[BaseMessageComponent]): 包含消息对象的列表
+        """
+        if not chain:
+            return True
+
+        for comp in chain:
+            comp_type = type(comp)
+
+            # 检查组件类型是否在字典中
+            if comp_type in self._component_validators:
+                if self._component_validators[comp_type](comp):
+                    return False
+
+        # 如果所有组件都为空
+        return True
+
     async def process(
         self, event: AstrMessageEvent
     ) -> Union[None, AsyncGenerator[None, None]]:
         result = event.get_result()
         if result is None:
             return
+        if result.result_content_type == ResultContentType.STREAMING_FINISH:
+            return
 
-        if len(result.chain) > 0:
-            await event._pre_send()
+        if result.result_content_type == ResultContentType.STREAMING_RESULT:
+            # 流式结果直接交付平台适配器处理
+            use_fallback = self.config.get("provider_settings", {}).get(
+                "streaming_segmented", False
+            )
+            logger.info(f"应用流式输出({event.get_platform_name()})")
+            await event.send_streaming(result.async_stream, use_fallback)
+            return
+        elif len(result.chain) > 0:
+            # 检查路径映射
+            if mappings := self.platform_settings.get("path_mapping", []):
+                for idx, component in enumerate(result.chain):
+                    if isinstance(component, Comp.File) and component.file:
+                        # 支持 File 消息段的路径映射。
+                        component.file = path_Mapping(mappings, component.file)
+                        event.get_result().chain[idx] = component
 
-            if self.enable_seg and (
-                (self.only_llm_result and result.is_llm_result())
-                or not self.only_llm_result
+            # 检查消息链是否为空
+            try:
+                if await self._is_empty_message_chain(result.chain):
+                    logger.info("消息为空，跳过发送阶段")
+                    event.clear_result()
+                    event.stop_event()
+                    return
+            except Exception as e:
+                logger.warning(f"空内容检查异常: {e}")
+
+            record_comps = [c for c in result.chain if isinstance(c, Comp.Record)]
+            non_record_comps = [
+                c for c in result.chain if not isinstance(c, Comp.Record)
+            ]
+
+            if (
+                self.enable_seg
+                and (
+                    (self.only_llm_result and result.is_llm_result())
+                    or not self.only_llm_result
+                )
+                and event.get_platform_name()
+                not in ["qq_official", "weixin_official_account", "dingtalk"]
             ):
                 decorated_comps = []
                 if self.reply_with_mention:
                     for comp in result.chain:
-                        if isinstance(comp, At):
+                        if isinstance(comp, Comp.At):
                             decorated_comps.append(comp)
                             result.chain.remove(comp)
                             break
                 if self.reply_with_quote:
                     for comp in result.chain:
-                        if isinstance(comp, Reply):
+                        if isinstance(comp, Comp.Reply):
                             decorated_comps.append(comp)
                             result.chain.remove(comp)
                             break
-                # 分段回复
-                for comp in result.chain:
-                    i = await self._calc_comp_interval(comp)
-                    await asyncio.sleep(i)
-                    await event.send(MessageChain([*decorated_comps, comp]))
+
+                # leverage lock to guarentee the order of message sending among different events
+                async with session_lock_manager.acquire_lock(event.unified_msg_origin):
+                    for rcomp in record_comps:
+                        i = await self._calc_comp_interval(rcomp)
+                        await asyncio.sleep(i)
+                        try:
+                            await event.send(MessageChain([rcomp]))
+                        except Exception as e:
+                            logger.error(f"发送消息失败: {e} chain: {result.chain}")
+                            break
+                    # 分段回复
+                    for comp in non_record_comps:
+                        i = await self._calc_comp_interval(comp)
+                        await asyncio.sleep(i)
+                        try:
+                            await event.send(MessageChain([*decorated_comps, comp]))
+                            decorated_comps = []  # 清空已发送的装饰组件
+                        except Exception as e:
+                            logger.error(f"发送消息失败: {e} chain: {result.chain}")
+                            break
             else:
-                await event.send(result)
-            await event._post_send()
+                for rcomp in record_comps:
+                    try:
+                        await event.send(MessageChain([rcomp]))
+                    except Exception as e:
+                        logger.error(f"发送消息失败: {e} chain: {result.chain}")
+
+                try:
+                    await event.send(MessageChain(non_record_comps))
+                except Exception as e:
+                    logger.error(traceback.format_exc())
+                    logger.error(f"发送消息失败: {e} chain: {result.chain}")
+
             logger.info(
                 f"AstrBot -> {event.get_sender_name()}/{event.get_sender_id()}: {event._outline_chain(result.chain)}"
             )
 
         handlers = star_handlers_registry.get_handlers_by_event_type(
-            EventType.OnAfterMessageSentEvent
+            EventType.OnAfterMessageSentEvent, platform_id=event.get_platform_id()
         )
         for handler in handlers:
             try:

astrbot/core/pipeline/result_decorate/stage.py

@@ -1,16 +1,19 @@
-import time
 import re
+import time
 import traceback
-from typing import Union, AsyncGenerator
-from ..stage import Stage, register_stage, registered_stages
-from ..context import PipelineContext
+from typing import AsyncGenerator, Union
+
+from astrbot.core import file_token_service, html_renderer, logger
+from astrbot.core.message.components import At, File, Image, Node, Plain, Record, Reply
+from astrbot.core.message.message_event_result import ResultContentType
 from astrbot.core.platform.astr_message_event import AstrMessageEvent
 from astrbot.core.platform.message_type import MessageType
-from astrbot.core import logger
-from astrbot.core.message.components import Plain, Image, At, Reply, Record, File, Node
-from astrbot.core import html_renderer
-from astrbot.core.star.star_handler import star_handlers_registry, EventType
+from astrbot.core.star.session_llm_manager import SessionServiceManager
 from astrbot.core.star.star import star_map
+from astrbot.core.star.star_handler import EventType, star_handlers_registry
+
+from ..context import PipelineContext
+from ..stage import Stage, register_stage, registered_stages
 
 
 @register_stage
@@ -31,6 +34,8 @@ class ResultDecorateStage(Stage):
                 self.t2i_word_threshold = 50
         except BaseException:
             self.t2i_word_threshold = 150
+        self.t2i_strategy = ctx.astrbot_config["t2i_strategy"]
+        self.t2i_use_network = self.t2i_strategy == "remote"
 
         self.forward_threshold = ctx.astrbot_config["platform_settings"][
             "forward_threshold"
@@ -70,11 +75,17 @@ class ResultDecorateStage(Stage):
         if result is None or not result.chain:
             return
 
+        if result.result_content_type == ResultContentType.STREAMING_RESULT:
+            return
+
+        is_stream = result.result_content_type == ResultContentType.STREAMING_FINISH
+
         # 回复时检查内容安全
         if (
             self.content_safe_check_reply
             and self.content_safe_check_stage
             and result.is_llm_result()
+            and not is_stream  # 流式输出不检查内容安全
         ):
             text = ""
             for comp in result.chain:
@@ -87,13 +98,17 @@ class ResultDecorateStage(Stage):
 
         # 发送消息前事件钩子
         handlers = star_handlers_registry.get_handlers_by_event_type(
-            EventType.OnDecoratingResultEvent
+            EventType.OnDecoratingResultEvent, platform_id=event.get_platform_id()
         )
         for handler in handlers:
             try:
                 logger.debug(
                     f"hook(on_decorating_result) -> {star_map[handler.handler_module_path].name} - {handler.handler_name}"
                 )
+                if is_stream:
+                    logger.warning(
+                        "启用流式输出时，依赖发送消息前事件钩子的插件可能无法正常工作"
+                    )
                 await handler.handler(event)
                 if event.get_result() is None or not event.get_result().chain:
                     logger.debug(
@@ -108,6 +123,11 @@ class ResultDecorateStage(Stage):
                 )
                 return
 
+        # 流式输出不执行下面的逻辑
+        if is_stream:
+            logger.info("流式输出已启用，跳过结果装饰阶段")
+            return
+
         # 需要再获取一次。插件可能直接对 chain 进行了替换。
         result = event.get_result()
         if result is None:
@@ -122,7 +142,11 @@ class ResultDecorateStage(Stage):
                         break
 
             # 分段回复
-            if self.enable_segmented_reply:
+            if self.enable_segmented_reply and event.get_platform_name() not in [
+                "qq_official",
+                "weixin_official_account",
+                "dingtalk",
+            ]:
                 if (
                     self.only_llm_result and result.is_llm_result()
                 ) or not self.only_llm_result:
@@ -133,9 +157,9 @@ class ResultDecorateStage(Stage):
                                 # 不分段回复
                                 new_chain.append(comp)
                                 continue
-                            split_response = []
-                            for line in comp.text.split("\n"):
-                                split_response.extend(re.findall(self.regex, line))
+                            split_response = re.findall(
+                                self.regex, comp.text, re.DOTALL | re.MULTILINE
+                            )
                             if not split_response:
                                 new_chain.append(comp)
                                 continue
@@ -150,28 +174,57 @@ class ResultDecorateStage(Stage):
                     result.chain = new_chain
 
             # TTS
+            tts_provider = self.ctx.plugin_manager.context.get_using_tts_provider(
+                event.unified_msg_origin
+            )
+
             if (
                 self.ctx.astrbot_config["provider_tts_settings"]["enable"]
                 and result.is_llm_result()
+                and tts_provider
+                and SessionServiceManager.should_process_tts_request(event)
             ):
-                tts_provider = self.ctx.plugin_manager.context.provider_manager.curr_tts_provider_inst
                 new_chain = []
                 for comp in result.chain:
                     if isinstance(comp, Plain) and len(comp.text) > 1:
                         try:
-                            logger.info("TTS 请求: " + comp.text)
+                            logger.info(f"TTS 请求: {comp.text}")
                             audio_path = await tts_provider.get_audio(comp.text)
-                            logger.info("TTS 结果: " + audio_path)
-                            if audio_path:
-                                new_chain.append(
-                                    Record(file=audio_path, url=audio_path)
-                                )
-                            else:
+                            logger.info(f"TTS 结果: {audio_path}")
+                            if not audio_path:
                                 logger.error(
-                                    f"由于 TTS 音频文件没找到，消息段转语音失败: {comp.text}"
+                                    f"由于 TTS 音频文件未找到，消息段转语音失败: {comp.text}"
                                 )
                                 new_chain.append(comp)
-                        except BaseException:
+                                continue
+
+                            use_file_service = self.ctx.astrbot_config[
+                                "provider_tts_settings"
+                            ]["use_file_service"]
+                            callback_api_base = self.ctx.astrbot_config[
+                                "callback_api_base"
+                            ]
+                            dual_output = self.ctx.astrbot_config[
+                                "provider_tts_settings"
+                            ]["dual_output"]
+
+                            url = None
+                            if use_file_service and callback_api_base:
+                                token = await file_token_service.register_file(
+                                    audio_path
+                                )
+                                url = f"{callback_api_base}/api/file/{token}"
+                                logger.debug(f"已注册：{url}")
+
+                            new_chain.append(
+                                Record(
+                                    file=url or audio_path,
+                                    url=url or audio_path,
+                                )
+                            )
+                            if dual_output:
+                                new_chain.append(comp)
+                        except Exception:
                             logger.error(traceback.format_exc())
                             logger.error("TTS 失败，使用文本发送。")
                             new_chain.append(comp)
@@ -192,7 +245,9 @@ class ResultDecorateStage(Stage):
                 if plain_str and len(plain_str) > self.t2i_word_threshold:
                     render_start = time.time()
                     try:
-                        url = await html_renderer.render_t2i(plain_str, return_url=True)
+                        url = await html_renderer.render_t2i(
+                            plain_str, return_url=True, use_network=self.t2i_use_network
+                        )
                     except BaseException:
                         logger.error("文本转图片失败，使用文本发送。")
                         return
@@ -201,7 +256,18 @@ class ResultDecorateStage(Stage):
                             "文本转图片耗时超过了 3 秒，如果觉得很慢可以使用 /t2i 关闭文本转图片模式。"
                         )
                     if url:
-                        result.chain = [Image.fromURL(url)]
+                        if url.startswith("http"):
+                            result.chain = [Image.fromURL(url)]
+                        elif (
+                            self.ctx.astrbot_config["t2i_use_file_service"]
+                            and self.ctx.astrbot_config["callback_api_base"]
+                        ):
+                            token = await file_token_service.register_file(url)
+                            url = f"{self.ctx.astrbot_config['callback_api_base']}/api/file/{token}"
+                            logger.debug(f"已注册：{url}")
+                            result.chain = [Image.fromURL(url)]
+                        else:
+                            result.chain = [Image.fromFileSystem(url)]
 
             # 触发转发消息
             has_forwarded = False

astrbot/core/pipeline/scheduler.py

@@ -7,50 +7,73 @@ from astrbot.core import logger
 
 
 class PipelineScheduler:
+    """管道调度器，负责调度各个阶段的执行"""
+
     def __init__(self, context: PipelineContext):
-        registered_stages.sort(key=lambda x: STAGES_ORDER.index(x.__class__.__name__))
-        self.ctx = context
+        registered_stages.sort(
+            key=lambda x: STAGES_ORDER.index(x.__class__.__name__)
+        )  # 按照顺序排序
+        self.ctx = context  # 上下文对象
 
     async def initialize(self):
+        """初始化管道调度器时, 初始化所有阶段"""
         for stage in registered_stages:
             # logger.debug(f"初始化阶段 {stage.__class__ .__name__}")
 
             await stage.initialize(self.ctx)
 
     async def _process_stages(self, event: AstrMessageEvent, from_stage=0):
+        """依次执行各个阶段
+
+        Args:
+            event (AstrMessageEvent): 事件对象
+            from_stage (int): 从第几个阶段开始执行, 默认从0开始
+        """
         for i in range(from_stage, len(registered_stages)):
-            stage = registered_stages[i]
+            stage = registered_stages[i]  # 获取当前要执行的阶段
             # logger.debug(f"执行阶段 {stage.__class__ .__name__}")
-            coro = stage.process(event)
-            if isinstance(coro, AsyncGenerator):
-                async for _ in coro:
+            coroutine = stage.process(
+                event
+            )  # 调用阶段的process方法, 返回协程或者异步生成器
+
+            if isinstance(coroutine, AsyncGenerator):
+                # 如果返回的是异步生成器, 实现洋葱模型的核心
+                async for _ in coroutine:
+                    # 此处是前置处理完成后的暂停点(yield), 下面开始执行后续阶段
                     if event.is_stopped():
                         logger.debug(
                             f"阶段 {stage.__class__.__name__} 已终止事件传播。"
                         )
                         break
+
+                    # 递归调用, 处理所有后续阶段
                     await self._process_stages(event, i + 1)
+
+                    # 此处是后续所有阶段处理完毕后返回的点, 执行后置处理
                     if event.is_stopped():
                         logger.debug(
                             f"阶段 {stage.__class__.__name__} 已终止事件传播。"
                         )
                         break
             else:
-                await coro
+                # 如果返回的是普通协程(不含yield的async函数), 则不进入下一层(基线条件)
+                # 简单地等待它执行完成, 然后继续执行下一个阶段
+                await coroutine
 
                 if event.is_stopped():
                     logger.debug(f"阶段 {stage.__class__.__name__} 已终止事件传播。")
                     break
 
-            if event.is_stopped():
-                logger.debug(f"阶段 {stage.__class__.__name__} 已终止事件传播。")
-                break
-
     async def execute(self, event: AstrMessageEvent):
-        """执行 pipeline"""
+        """执行 pipeline
+
+        Args:
+            event (AstrMessageEvent): 事件对象
+        """
         await self._process_stages(event)
 
-        if not event._has_send_oper and event.get_platform_name() == "webchat":
+        # 如果没有发送操作, 则发送一个空消息, 以便于后续的处理
+        if event.get_platform_name() == "webchat":
             await event.send(None)
 
         logger.debug("pipeline 执行完毕。")

astrbot/core/pipeline/session_status_check/stage.py

@@ -0,0 +1,22 @@
+from ..stage import Stage, register_stage
+from ..context import PipelineContext
+from typing import AsyncGenerator, Union
+from astrbot.core.platform.astr_message_event import AstrMessageEvent
+from astrbot.core.star.session_llm_manager import SessionServiceManager
+from astrbot.core import logger
+
+
+@register_stage
+class SessionStatusCheckStage(Stage):
+    """检查会话是否整体启用"""
+
+    async def initialize(self, ctx: PipelineContext) -> None:
+        pass
+
+    async def process(
+        self, event: AstrMessageEvent
+    ) -> Union[None, AsyncGenerator[None, None]]:
+        # 检查会话是否整体启用
+        if not SessionServiceManager.is_session_enabled(event.unified_msg_origin):
+            logger.debug(f"会话 {event.unified_msg_origin} 已被关闭，已终止事件传播。")
+            event.stop_event()

astrbot/core/pipeline/stage.py

@@ -1,14 +1,10 @@
 from __future__ import annotations
 import abc
-import inspect
-from astrbot.api import logger
-from typing import List, AsyncGenerator, Union, Awaitable
+from typing import List, AsyncGenerator, Union
 from astrbot.core.platform.astr_message_event import AstrMessageEvent
 from .context import PipelineContext
-from astrbot.core.message.message_event_result import MessageEventResult, CommandResult
 
-registered_stages: List[Stage] = []
-"""维护了所有已注册的 Stage 实现类"""
+registered_stages: List[Stage] = []  # 维护了所有已注册的 Stage 实现类
 
 
 def register_stage(cls):
@@ -22,51 +18,22 @@ class Stage(abc.ABC):
 
     @abc.abstractmethod
     async def initialize(self, ctx: PipelineContext) -> None:
-        """初始化阶段"""
+        """初始化阶段
+
+        Args:
+            ctx (PipelineContext): 消息管道上下文对象, 包括配置和插件管理器
+        """
         raise NotImplementedError
 
     @abc.abstractmethod
     async def process(
         self, event: AstrMessageEvent
     ) -> Union[None, AsyncGenerator[None, None]]:
-        """处理事件"""
+        """处理事件
+
+        Args:
+            event (AstrMessageEvent): 事件对象，包含事件的相关信息
+        Returns:
+            Union[None, AsyncGenerator[None, None]]: 处理结果，可能是 None 或者异步生成器, 如果为 None 则表示不需要继续处理, 如果为异步生成器则表示需要继续处理(进入下一个阶段)
+        """
         raise NotImplementedError
-
-    async def _call_handler(
-        self,
-        ctx: PipelineContext,
-        event: AstrMessageEvent,
-        handler: Awaitable,
-        *args,
-        **kwargs,
-    ) -> AsyncGenerator[None, None]:
-        """调用 Handler。"""
-        # 判断 handler 是否是类方法（通过装饰器注册的没有 __self__ 属性）
-        ready_to_call = None
-        try:
-            ready_to_call = handler(event, *args, **kwargs)
-        except TypeError as e:
-            # 向下兼容
-            logger.debug(str(e))
-            ready_to_call = handler(event, ctx.plugin_manager.context, *args, **kwargs)
-
-        if isinstance(ready_to_call, AsyncGenerator):
-            _has_yielded = False
-            async for ret in ready_to_call:
-                # 如果处理函数是生成器，返回值只能是 MessageEventResult 或者 None（无返回值）
-                _has_yielded = True
-                if isinstance(ret, (MessageEventResult, CommandResult)):
-                    event.set_result(ret)
-                    yield
-                else:
-                    yield ret
-            if not _has_yielded:
-                yield
-        elif inspect.iscoroutine(ready_to_call):
-            # 如果只是一个 coroutine
-            ret = await ready_to_call
-            if isinstance(ret, (MessageEventResult, CommandResult)):
-                event.set_result(ret)
-                yield
-            else:
-                yield ret

astrbot/core/pipeline/waking_check/stage.py

@@ -1,12 +1,16 @@
-from ..stage import Stage, register_stage
-from ..context import PipelineContext
-from typing import Union, AsyncGenerator
+from typing import AsyncGenerator, Union
+
+from astrbot import logger
+from astrbot.core.message.components import At, AtAll, Reply
+from astrbot.core.message.message_event_result import MessageChain, MessageEventResult
 from astrbot.core.platform.astr_message_event import AstrMessageEvent
-from astrbot.core.message.message_event_result import MessageEventResult, MessageChain
-from astrbot.core.message.components import At
-from astrbot.core.star.star_handler import star_handlers_registry, EventType
-from astrbot.core.star.star import star_map
 from astrbot.core.star.filter.permission import PermissionTypeFilter
+from astrbot.core.star.session_plugin_manager import SessionPluginManager
+from astrbot.core.star.star import star_map
+from astrbot.core.star.star_handler import EventType, star_handlers_registry
+
+from ..context import PipelineContext
+from ..stage import Stage, register_stage
 
 
 @register_stage
@@ -21,18 +25,41 @@ class WakingCheckStage(Stage):
     """
 
     async def initialize(self, ctx: PipelineContext) -> None:
+        """初始化唤醒检查阶段
+
+        Args:
+            ctx (PipelineContext): 消息管道上下文对象, 包括配置和插件管理器
+        """
         self.ctx = ctx
         self.no_permission_reply = self.ctx.astrbot_config["platform_settings"].get(
             "no_permission_reply", True
         )
+        # 私聊是否需要 wake_prefix 才能唤醒机器人
+        self.friend_message_needs_wake_prefix = self.ctx.astrbot_config[
+            "platform_settings"
+        ].get("friend_message_needs_wake_prefix", False)
+        # 是否忽略机器人自己发送的消息
+        self.ignore_bot_self_message = self.ctx.astrbot_config["platform_settings"].get(
+            "ignore_bot_self_message", False
+        )
+        self.ignore_at_all = self.ctx.astrbot_config["platform_settings"].get(
+            "ignore_at_all", False
+        )
 
     async def process(
         self, event: AstrMessageEvent
     ) -> Union[None, AsyncGenerator[None, None]]:
+        if (
+            self.ignore_bot_self_message
+            and event.get_self_id() == event.get_sender_id()
+        ):
+            # 忽略机器人自己发送的消息
+            event.stop_event()
+            return
         # 设置 sender 身份
         event.message_str = event.message_str.strip()
         for admin_id in self.ctx.astrbot_config["admins_id"]:
-            if event.get_sender_id() == admin_id:
+            if str(event.get_sender_id()) == admin_id:
                 event.role = "admin"
                 break
 
@@ -56,11 +83,18 @@ class WakingCheckStage(Stage):
                 event.message_str = event.message_str[len(wake_prefix) :].strip()
                 break
         if not is_wake:
-            # 检查是否有 at 消息
+            # 检查是否有at消息 / at全体成员消息 / 引用了bot的消息
             for message in messages:
-                if isinstance(message, At) and (
-                    str(message.qq) == str(event.get_self_id())
-                    or str(message.qq) == "all"
+                if (
+                    (
+                        isinstance(message, At)
+                        and (str(message.qq) == str(event.get_self_id()))
+                    )
+                    or (isinstance(message, AtAll) and not self.ignore_at_all)
+                    or (
+                        isinstance(message, Reply)
+                        and str(message.sender_id) == str(event.get_self_id())
+                    )
                 ):
                     is_wake = True
                     event.is_wake = True
@@ -68,7 +102,7 @@ class WakingCheckStage(Stage):
                     event.is_at_or_wake_command = True
                     break
             # 检查是否是私聊
-            if event.is_private_chat():
+            if event.is_private_chat() and not self.friend_message_needs_wake_prefix:
                 is_wake = True
                 event.is_wake = True
                 event.is_at_or_wake_command = True
@@ -84,6 +118,7 @@ class WakingCheckStage(Stage):
             # filter 需满足 AND 逻辑关系
             passed = True
             permission_not_pass = False
+            permission_filter_raise_error = False
             if len(handler.event_filters) == 0:
                 continue
 
@@ -92,6 +127,7 @@ class WakingCheckStage(Stage):
                     if isinstance(filter, PermissionTypeFilter):
                         if not filter.filter(event, self.ctx.astrbot_config):
                             permission_not_pass = True
+                            permission_filter_raise_error = filter.raise_error
                     else:
                         if not filter.filter(event, self.ctx.astrbot_config):
                             passed = False
@@ -107,12 +143,18 @@ class WakingCheckStage(Stage):
                     break
             if passed:
                 if permission_not_pass:
+                    if not permission_filter_raise_error:
+                        # 跳过
+                        continue
                     if self.no_permission_reply:
                         await event.send(
                             MessageChain().message(
-                                f"ID {event.get_sender_id()} 权限不足。通过 /sid 获取 ID 并请管理员添加。"
+                                f"您(ID: {event.get_sender_id()})的权限不足以使用此指令。通过 /sid 获取 ID 并请管理员添加。"
                             )
                         )
+                    logger.info(
+                        f"触发 {star_map[handler.handler_module_path].name} 时, 用户(ID={event.get_sender_id()}) 权限不足。"
+                    )
                     event.stop_event()
                     return
 
@@ -125,7 +167,12 @@ class WakingCheckStage(Stage):
                         "parsed_params"
                     )
 
-            event.clear_extra()
+            event._extras.pop("parsed_params", None)
+
+        # 根据会话配置过滤插件处理器
+        activated_handlers = SessionPluginManager.filter_handlers_by_session(
+            event, activated_handlers
+        )
 
         event.set_extra("activated_handlers", activated_handlers)
         event.set_extra("handlers_parsed_params", handlers_parsed_params)

astrbot/core/pipeline/whitelist_check/stage.py

@@ -15,6 +15,9 @@ class WhitelistCheckStage(Stage):
             "enable_id_white_list"
         ]
         self.whitelist = ctx.astrbot_config["platform_settings"]["id_whitelist"]
+        self.whitelist = [
+            str(i).strip() for i in self.whitelist if str(i).strip() != ""
+        ]
         self.wl_ignore_admin_on_group = ctx.astrbot_config["platform_settings"][
             "wl_ignore_admin_on_group"
         ]
@@ -51,7 +54,10 @@ class WhitelistCheckStage(Stage):
                 and event.get_message_type() == MessageType.FRIEND_MESSAGE
             ):
                 return
-        if event.unified_msg_origin not in self.whitelist:
+        if (
+            event.unified_msg_origin not in self.whitelist
+            and str(event.get_group_id()).strip() not in self.whitelist
+        ):
             if self.wl_log:
                 logger.info(
                     f"会话 ID {event.unified_msg_origin} 不在会话白名单中，已终止事件传播。请在配置文件中添加该会话 ID 到白名单。"

astrbot/core/platform/__init__.py

@@ -1,7 +1,7 @@
 from .platform import Platform
 from .astr_message_event import AstrMessageEvent
 from .platform_metadata import PlatformMetadata
-from .astrbot_message import AstrBotMessage, MessageMember, MessageType
+from .astrbot_message import AstrBotMessage, MessageMember, MessageType, Group
 
 __all__ = [
     "Platform",
@@ -10,4 +10,5 @@ __all__ = [
     "AstrBotMessage",
     "MessageMember",
     "MessageType",
+    "Group",
 ]

astrbot/core/platform/astr_message_event.py

@@ -1,11 +1,12 @@
 import abc
 import asyncio
+import re
+import hashlib
+import uuid
 from dataclasses import dataclass
-from .astrbot_message import AstrBotMessage
-from .platform_metadata import PlatformMetadata
-from astrbot.core.message.message_event_result import MessageEventResult, MessageChain
-from astrbot.core.platform.message_type import MessageType
-from typing import List, Union
+from typing import List, Union, Optional, AsyncGenerator
+
+from astrbot.core.db.po import Conversation
 from astrbot.core.message.components import (
     Plain,
     Image,
@@ -14,10 +15,14 @@ from astrbot.core.message.components import (
     At,
     AtAll,
     Forward,
+    Reply,
 )
+from astrbot.core.message.message_event_result import MessageEventResult, MessageChain
+from astrbot.core.platform.message_type import MessageType
+from astrbot.core.provider.entities import ProviderRequest
 from astrbot.core.utils.metrics import Metric
-from astrbot.core.provider.entites import ProviderRequest
-from astrbot.core.db.po import Conversation
+from .astrbot_message import AstrBotMessage, Group
+from .platform_metadata import PlatformMetadata
 
 
 @dataclass
@@ -79,6 +84,9 @@ class AstrMessageEvent(abc.ABC):
     def get_platform_name(self):
         return self.platform_meta.name
 
+    def get_platform_id(self):
+        return self.platform_meta.id
+
     def get_message_str(self) -> str:
         """
         获取消息字符串。
@@ -101,8 +109,15 @@ class AstrMessageEvent(abc.ABC):
             elif isinstance(i, Forward):
                 # 转发消息
                 outline += "[转发消息]"
+            elif isinstance(i, Reply):
+                # 引用回复
+                if i.message_str:
+                    outline += f"[引用消息({i.sender_nickname}: {i.message_str})]"
+                else:
+                    outline += "[引用消息]"
             else:
                 outline += f"[{i.type}]"
+            outline += " "
         return outline
 
     def get_message_outline(self) -> str:
@@ -193,9 +208,26 @@ class AstrMessageEvent(abc.ABC):
         """
         return self.role == "admin"
 
-    async def send(self, message: MessageChain):
+    async def process_buffer(self, buffer: str, pattern: re.Pattern) -> str:
         """
-        发送消息到消息平台。
+        将消息缓冲区中的文本按指定正则表达式分割后发送至消息平台，作为不支持流式输出平台的Fallback。
+        """
+        while True:
+            match = re.search(pattern, buffer)
+            if not match:
+                break
+            matched_text = match.group()
+            await self.send(MessageChain([Plain(matched_text)]))
+            buffer = buffer[match.end() :]
+            await asyncio.sleep(1.5)  # 限速
+        return buffer
+
+    async def send_streaming(
+        self, generator: AsyncGenerator[MessageChain, None], use_fallback: bool = False
+    ):
+        """发送流式消息到消息平台，使用异步生成器。
+        目前仅支持: telegram，qq official 私聊。
+        Fallback仅支持 aiocqhttp。
         """
         asyncio.create_task(
             Metric.upload(msg_event_tick=1, adapter_name=self.platform_meta.name)
@@ -203,10 +235,10 @@ class AstrMessageEvent(abc.ABC):
         self._has_send_oper = True
 
     async def _pre_send(self):
-        """调度器会在执行 send() 前调用该方法"""
+        """调度器会在执行 send() 前调用该方法 deprecated in v3.5.18"""
 
     async def _post_send(self):
-        """调度器会在执行 send() 后调用该方法"""
+        """调度器会在执行 send() 后调用该方法 deprecated in v3.5.18"""
 
     def set_result(self, result: Union[MessageEventResult, str]):
         """设置消息事件的结果。
@@ -363,3 +395,30 @@ class AstrMessageEvent(abc.ABC):
             system_prompt=system_prompt,
             conversation=conversation,
         )
+
+    """平台适配器"""
+
+    async def send(self, message: MessageChain):
+        """发送消息到消息平台。
+
+        Args:
+            message (MessageChain): 消息链，具体使用方式请参考文档。
+        """
+        # Leverage BLAKE2 hash function to generate a non-reversible hash of the sender ID for privacy.
+        hash_obj = hashlib.blake2b(self.get_sender_id().encode("utf-8"), digest_size=16)
+        sid = str(uuid.UUID(bytes=hash_obj.digest()))
+        asyncio.create_task(
+            Metric.upload(
+                msg_event_tick=1, adapter_name=self.platform_meta.name, sid=sid
+            )
+        )
+        self._has_send_oper = True
+
+    async def get_group(self, group_id: str = None, **kwargs) -> Optional[Group]:
+        """获取一个群聊的数据, 如果不填写 group_id: 如果是私聊消息，返回 None。如果是群聊消息，返回当前群聊的数据。
+
+        适配情况:
+
+        - aiocqhttp(OneBotv11)
+        """
+        ...

astrbot/core/platform/astrbot_message.py

@@ -10,6 +10,41 @@ class MessageMember:
     user_id: str  # 发送者id
     nickname: str = None
 
+    def __str__(self):
+        # 使用 f-string 来构建返回的字符串表示形式
+        return (
+            f"User ID: {self.user_id},"
+            f"Nickname: {self.nickname if self.nickname else 'N/A'}"
+        )
+
+
+@dataclass
+class Group:
+    group_id: str
+    """群号"""
+    group_name: str = None
+    """群名称"""
+    group_avatar: str = None
+    """群头像"""
+    group_owner: str = None
+    """群主 id"""
+    group_admins: List[str] = None
+    """群管理员 id"""
+    members: List[MessageMember] = None
+    """所有群成员"""
+
+    def __str__(self):
+        # 使用 f-string 来构建返回的字符串表示形式
+        return (
+            f"Group ID: {self.group_id}\n"
+            f"Name: {self.group_name if self.group_name else 'N/A'}\n"
+            f"Avatar: {self.group_avatar if self.group_avatar else 'N/A'}\n"
+            f"Owner ID: {self.group_owner if self.group_owner else 'N/A'}\n"
+            f"Admin IDs: {self.group_admins if self.group_admins else 'N/A'}\n"
+            f"Members Len: {len(self.members) if self.members else 0}\n"
+            f"First Member: {self.members[0] if self.members else 'N/A'}\n"
+        )
+
 
 class AstrBotMessage:
     """

astrbot/core/platform/manager.py

@@ -58,16 +58,30 @@ class PlatformManager:
                     from .sources.qqofficial_webhook.qo_webhook_adapter import (
                         QQOfficialWebhookPlatformAdapter,  # noqa: F401
                     )
-                case "gewechat":
-                    from .sources.gewechat.gewechat_platform_adapter import (
-                        GewechatPlatformAdapter,  # noqa: F401
+                case "wechatpadpro":
+                    from .sources.wechatpadpro.wechatpadpro_adapter import (
+                        WeChatPadProAdapter,  # noqa: F401
                     )
                 case "lark":
                     from .sources.lark.lark_adapter import LarkPlatformAdapter  # noqa: F401
+                case "dingtalk":
+                    from .sources.dingtalk.dingtalk_adapter import (
+                        DingtalkPlatformAdapter,  # noqa: F401
+                    )
                 case "telegram":
                     from .sources.telegram.tg_adapter import TelegramPlatformAdapter  # noqa: F401
                 case "wecom":
                     from .sources.wecom.wecom_adapter import WecomPlatformAdapter  # noqa: F401
+                case "weixin_official_account":
+                    from .sources.weixin_official_account.weixin_offacc_adapter import (
+                        WeixinOfficialAccountPlatformAdapter,  # noqa
+                    )
+                case "discord":
+                    from .sources.discord.discord_platform_adapter import (
+                        DiscordPlatformAdapter,  # noqa: F401
+                    )
+                case "slack":
+                    from .sources.slack.slack_adapter import SlackAdapter  # noqa: F401
         except (ImportError, ModuleNotFoundError) as e:
             logger.error(
                 f"加载平台适配器 {platform_config['type']} 失败，原因：{e}。请检查依赖库是否安装。提示：可以在 管理面板->控制台->安装Pip库 中安装依赖库。"
@@ -81,14 +95,18 @@ class PlatformManager:
             )
             return
         cls_type = platform_cls_map[platform_config["type"]]
-        inst = cls_type(platform_config, self.settings, self.event_queue)
-        self._inst_map[platform_config["id"]] = inst
+        inst: Platform = cls_type(platform_config, self.settings, self.event_queue)
+        self._inst_map[platform_config["id"]] = {
+            "inst": inst,
+            "client_id": inst.client_self_id,
+        }
         self.platform_insts.append(inst)
 
         asyncio.create_task(
             self._task_wrapper(
                 asyncio.create_task(
-                    inst.run(), name=platform_config["id"] + "_platform"
+                    inst.run(),
+                    name=f"platform_{platform_config['type']}_{platform_config['id']}",
                 )
             )
         )
@@ -105,38 +123,42 @@ class PlatformManager:
             logger.error("-------")
 
     async def reload(self, platform_config: dict):
-        # 还未实现完成，不要调用此方法
-
-        if platform_config["id"] in self._inst_map:
-            # 正在运行
-            if getattr(self._inst_map[platform_config["id"]], "terminate", None):
-                logger.info(f"正在尝试终止 {platform_config['id']} 平台适配器 ...")
-                await self._inst_map[platform_config["id"]].terminate()
-                logger.info(f"{platform_config['id']} 平台适配器已终止。")
-                del self._inst_map[platform_config["id"]]
-                self.platform_insts.remove(self._inst_map[platform_config["id"]])
-            else:
-                logger.warning(f"可能无法正常终止 {platform_config['id']} 平台适配器。")
-
-            # 再启动新的实例
+        await self.terminate_platform(platform_config["id"])
+        if platform_config["enable"]:
             await self.load_platform(platform_config)
 
-        else:
-            # 先将 _inst_map 中在 platform_config 中不存在的实例删除
-            config_ids = [platform["id"] for platform in self.platforms_config]
-            for key in list(self._inst_map.keys()):
-                if key not in config_ids:
-                    if getattr(self._inst_map[key], "terminate", None):
-                        logger.info(f"正在尝试终止 {key} 平台适配器 ...")
-                        await self._inst_map[key].terminate()
-                        logger.info(f"{key} 平台适配器已终止。")
-                        del self._inst_map[key]
-                        self.platform_insts.remove(self._inst_map[key])
-                    else:
-                        logger.warning(f"可能无法正常终止 {key} 平台适配器。")
+        # 和配置文件保持同步
+        config_ids = [provider["id"] for provider in self.platforms_config]
+        for key in list(self._inst_map.keys()):
+            if key not in config_ids:
+                await self.terminate_platform(key)
 
-            # 再启动新的实例
-            await self.load_platform(platform_config)
+    async def terminate_platform(self, platform_id: str):
+        if platform_id in self._inst_map:
+            logger.info(f"正在尝试终止 {platform_id} 平台适配器 ...")
+
+            # client_id = self._inst_map.pop(platform_id, None)
+            info = self._inst_map.pop(platform_id, None)
+            client_id = info["client_id"]
+            inst = info["inst"]
+            try:
+                self.platform_insts.remove(
+                    next(
+                        inst
+                        for inst in self.platform_insts
+                        if inst.client_self_id == client_id
+                    )
+                )
+            except Exception:
+                logger.warning(f"可能未完全移除 {platform_id} 平台适配器")
+
+            if getattr(inst, "terminate", None):
+                await inst.terminate()
+
+    async def terminate(self):
+        for inst in self.platform_insts:
+            if getattr(inst, "terminate", None):
+                await inst.terminate()
 
     def get_insts(self):
         return self.platform_insts

astrbot/core/platform/platform.py

@@ -1,4 +1,5 @@
 import abc
+import uuid
 from typing import Awaitable, Any
 from asyncio import Queue
 from .platform_metadata import PlatformMetadata
@@ -13,6 +14,7 @@ class Platform(abc.ABC):
         super().__init__()
         # 维护了消息平台的事件队列，EventBus 会从这里取出事件并处理。
         self._event_queue = event_queue
+        self.client_self_id = uuid.uuid4().hex
 
     @abc.abstractmethod
     def run(self) -> Awaitable[Any]:
@@ -25,7 +27,7 @@ class Platform(abc.ABC):
         """
         终止一个平台的运行实例。
         """
-        pass
+        ...
 
     @abc.abstractmethod
     def meta(self) -> PlatformMetadata:

astrbot/core/platform/platform_metadata.py

@@ -7,6 +7,8 @@ class PlatformMetadata:
     """平台的名称"""
     description: str
     """平台的描述"""
+    id: str = None
+    """平台的唯一标识符，用于配置中识别特定平台"""
 
     default_config_tmpl: dict = None
     """平台的默认配置模板"""

astrbot/core/platform/sources/aiocqhttp/aiocqhttp_message_event.py

@@ -1,9 +1,19 @@
 import asyncio
-
+import re
+from typing import AsyncGenerator, Dict, List
+from aiocqhttp import CQHttp, Event
 from astrbot.api.event import AstrMessageEvent, MessageChain
-from astrbot.api.message_components import Plain, Image, Record, At, Node, Nodes
-from aiocqhttp import CQHttp
-from astrbot.core.utils.io import file_to_base64, download_image_by_url
+from astrbot.api.message_components import (
+    Image,
+    Node,
+    Nodes,
+    Plain,
+    Record,
+    Video,
+    File,
+    BaseMessageComponent,
+)
+from astrbot.api.platform import Group, MessageMember
 
 
 class AiocqhttpMessageEvent(AstrMessageEvent):
@@ -13,68 +23,195 @@ class AiocqhttpMessageEvent(AstrMessageEvent):
         super().__init__(message_str, message_obj, platform_meta, session_id)
         self.bot = bot
 
+    @staticmethod
+    async def _from_segment_to_dict(segment: BaseMessageComponent) -> dict:
+        """修复部分字段"""
+        if isinstance(segment, (Image, Record)):
+            # For Image and Record segments, we convert them to base64
+            bs64 = await segment.convert_to_base64()
+            return {
+                "type": segment.type.lower(),
+                "data": {
+                    "file": f"base64://{bs64}",
+                },
+            }
+        elif isinstance(segment, File):
+            # For File segments, we need to handle the file differently
+            d = await segment.to_dict()
+            return d
+        elif isinstance(segment, Video):
+            d = await segment.to_dict()
+            return d
+        else:
+            # For other segments, we simply convert them to a dict by calling toDict
+            return segment.toDict()
+
     @staticmethod
     async def _parse_onebot_json(message_chain: MessageChain):
         """解析成 OneBot json 格式"""
         ret = []
         for segment in message_chain.chain:
-            d = segment.toDict()
             if isinstance(segment, Plain):
-                d["type"] = "text"
-            elif isinstance(segment, (Image, Record)):
-                # convert to base64
-                if segment.file and segment.file.startswith("file:///"):
-                    bs64_data = file_to_base64(segment.file[8:])
-                    image_file_path = segment.file[8:]
-                elif segment.file and segment.file.startswith("http"):
-                    image_file_path = await download_image_by_url(segment.file)
-                    bs64_data = file_to_base64(image_file_path)
-                elif segment.file and segment.file.startswith("base64://"):
-                    bs64_data = segment.file
-                else:
-                    bs64_data = file_to_base64(segment.file)
-                d["data"] = {
-                    "file": bs64_data,
-                }
-            elif isinstance(segment, At):
-                d["data"] = {
-                    "qq": str(segment.qq)  # 转换为字符串
-                }
+                if not segment.text.strip():
+                    continue
+            d = await AiocqhttpMessageEvent._from_segment_to_dict(segment)
             ret.append(d)
         return ret
 
-    async def send(self, message: MessageChain):
-        ret = await AiocqhttpMessageEvent._parse_onebot_json(message)
-
-        send_one_by_one = False
-        for seg in message.chain:
-            if isinstance(seg, (Node, Nodes)):
-                # 转发消息不能和普通消息混在一起发送
-                send_one_by_one = True
-                break
-
-        if send_one_by_one:
-            for seg in message.chain:
-                if isinstance(seg, Nodes):
-                    # 带有多个节点的合并转发消息
-                    payload = seg.toDict()
-                    if self.get_group_id():
-                        payload["group_id"] = self.get_group_id()
-                        await self.bot.call_action("send_group_forward_msg", **payload)
-                    else:
-                        payload["user_id"] = self.get_sender_id()
-                        await self.bot.call_action(
-                            "send_private_forward_msg", **payload
-                        )
-                else:
-                    await self.bot.send(
-                        self.message_obj.raw_message,
-                        await AiocqhttpMessageEvent._parse_onebot_json(
-                            MessageChain([seg])
-                        ),
-                    )
-                    await asyncio.sleep(0.5)
+    @classmethod
+    async def _dispatch_send(
+        cls,
+        bot: CQHttp,
+        event: Event | None,
+        is_group: bool,
+        session_id: str,
+        messages: list[dict],
+    ):
+        if event:
+            await bot.send(event=event, message=messages)
+        elif is_group:
+            await bot.send_group_msg(group_id=session_id, message=messages)
         else:
-            await self.bot.send(self.message_obj.raw_message, ret)
+            await bot.send_private_msg(user_id=session_id, message=messages)
 
+    @classmethod
+    async def send_message(
+        cls,
+        bot: CQHttp,
+        message_chain: MessageChain,
+        event: Event | None = None,
+        is_group: bool = False,
+        session_id: str = None,
+    ):
+        """发送消息"""
+
+        # 转发消息、文件消息不能和普通消息混在一起发送
+        send_one_by_one = any(
+            isinstance(seg, (Node, Nodes, File)) for seg in message_chain.chain
+        )
+        if not send_one_by_one:
+            ret = await cls._parse_onebot_json(message_chain)
+            if not ret:
+                return
+            await cls._dispatch_send(bot, event, is_group, session_id, ret)
+            return
+        for seg in message_chain.chain:
+            if isinstance(seg, (Node, Nodes)):
+                # 合并转发消息
+                if isinstance(seg, Node):
+                    nodes = Nodes([seg])
+                    seg = nodes
+
+                payload = await seg.to_dict()
+
+                if is_group:
+                    payload["group_id"] = session_id
+                    await bot.call_action("send_group_forward_msg", **payload)
+                else:
+                    payload["user_id"] = session_id
+                    await bot.call_action("send_private_forward_msg", **payload)
+            elif isinstance(seg, File):
+                d = await cls._from_segment_to_dict(seg)
+                await cls._dispatch_send(bot, event, is_group, session_id, [d])
+            else:
+                messages = await cls._parse_onebot_json(MessageChain([seg]))
+                if not messages:
+                    continue
+                await cls._dispatch_send(bot, event, is_group, session_id, messages)
+                await asyncio.sleep(0.5)
+
+    async def send(self, message: MessageChain):
+        """发送消息"""
+        event = self.message_obj.raw_message
+        assert isinstance(event, Event), "Event must be an instance of aiocqhttp.Event"
+        is_group = False
+        if self.get_group_id():
+            is_group = True
+            session_id = self.get_group_id()
+        else:
+            session_id = self.get_sender_id()
+        await self.send_message(
+            bot=self.bot,
+            message_chain=message,
+            event=event,
+            is_group=is_group,
+            session_id=session_id,
+        )
         await super().send(message)
+
+    async def send_streaming(
+        self, generator: AsyncGenerator, use_fallback: bool = False
+    ):
+        if not use_fallback:
+            buffer = None
+            async for chain in generator:
+                if not buffer:
+                    buffer = chain
+                else:
+                    buffer.chain.extend(chain.chain)
+            if not buffer:
+                return
+            buffer.squash_plain()
+            await self.send(buffer)
+            return await super().send_streaming(generator, use_fallback)
+
+        buffer = ""
+        pattern = re.compile(r"[^。？！~…]+[。？！~…]+")
+
+        async for chain in generator:
+            if isinstance(chain, MessageChain):
+                for comp in chain.chain:
+                    if isinstance(comp, Plain):
+                        buffer += comp.text
+                        if any(p in buffer for p in "。？！~…"):
+                            buffer = await self.process_buffer(buffer, pattern)
+                    else:
+                        await self.send(MessageChain(chain=[comp]))
+                        await asyncio.sleep(1.5)  # 限速
+
+        if buffer.strip():
+            await self.send(MessageChain([Plain(buffer)]))
+        return await super().send_streaming(generator, use_fallback)
+
+    async def get_group(self, group_id=None, **kwargs):
+        if isinstance(group_id, str) and group_id.isdigit():
+            group_id = int(group_id)
+        elif self.get_group_id():
+            group_id = int(self.get_group_id())
+        else:
+            return None
+
+        info: dict = await self.bot.call_action(
+            "get_group_info",
+            group_id=group_id,
+        )
+
+        members: List[Dict] = await self.bot.call_action(
+            "get_group_member_list",
+            group_id=group_id,
+        )
+
+        owner_id = None
+        admin_ids = []
+        for member in members:
+            if member["role"] == "owner":
+                owner_id = member["user_id"]
+            if member["role"] == "admin":
+                admin_ids.append(member["user_id"])
+
+        group = Group(
+            group_id=str(group_id),
+            group_name=info.get("group_name"),
+            group_avatar="",
+            group_admins=admin_ids,
+            group_owner=str(owner_id),
+            members=[
+                MessageMember(
+                    user_id=member["user_id"],
+                    nickname=member.get("nickname") or member.get("card"),
+                )
+                for member in members
+            ],
+        )
+
+        return group

astrbot/core/platform/sources/aiocqhttp/aiocqhttp_platform_adapter.py

@@ -1,8 +1,8 @@
-import os
 import time
 import asyncio
 import logging
 import uuid
+import itertools
 from typing import Awaitable, Any
 from aiocqhttp import CQHttp, Event
 from astrbot.api.platform import (
@@ -20,7 +20,6 @@ from .aiocqhttp_message_event import AiocqhttpMessageEvent
 from astrbot.core.platform.astr_message_event import MessageSesion
 from ...register import register_platform_adapter
 from aiocqhttp.exceptions import ActionFailed
-from astrbot.core.utils.io import download_file
 
 
 @register_platform_adapter(
@@ -39,14 +38,18 @@ class AiocqhttpAdapter(Platform):
         self.port = platform_config["ws_reverse_port"]
 
         self.metadata = PlatformMetadata(
-            "aiocqhttp",
-            "适用于 OneBot 标准的消息平台适配器，支持反向 WebSockets。",
+            name="aiocqhttp",
+            description="适用于 OneBot 标准的消息平台适配器，支持反向 WebSockets。",
+            id=self.config.get("id"),
         )
 
-        self.stop = False
-
         self.bot = CQHttp(
-            use_ws_reverse=True, import_name="aiocqhttp", api_timeout_sec=180
+            use_ws_reverse=True,
+            import_name="aiocqhttp",
+            api_timeout_sec=180,
+            access_token=platform_config.get(
+                "ws_reverse_token"
+            ),  # 以防旧版本配置不存在
         )
 
         @self.bot.on_request()
@@ -80,19 +83,18 @@ class AiocqhttpAdapter(Platform):
     async def send_by_session(
         self, session: MessageSesion, message_chain: MessageChain
     ):
-        ret = await AiocqhttpMessageEvent._parse_onebot_json(message_chain)
-        match session.message_type.value:
-            case MessageType.GROUP_MESSAGE.value:
-                if "_" in session.session_id:
-                    # 独立会话
-                    _, group_id = session.session_id.split("_")
-                    await self.bot.send_group_msg(group_id=group_id, message=ret)
-                else:
-                    await self.bot.send_group_msg(
-                        group_id=session.session_id, message=ret
-                    )
-            case MessageType.FRIEND_MESSAGE.value:
-                await self.bot.send_private_msg(user_id=session.session_id, message=ret)
+        is_group = session.message_type == MessageType.GROUP_MESSAGE
+        if is_group:
+            session_id = session.session_id.split("_")[-1]
+        else:
+            session_id = session.session_id
+        await AiocqhttpMessageEvent.send_message(
+            bot=self.bot,
+            message_chain=message_chain,
+            event=None,  # 这里不需要 event，因为是通过 session 发送的
+            is_group=is_group,
+            session_id=session_id,
+        )
         await super().send_by_session(session, message_chain)
 
     async def convert_message(self, event: Event) -> AstrBotMessage:
@@ -100,6 +102,9 @@ class AiocqhttpAdapter(Platform):
 
         if event["post_type"] == "message":
             abm = await self._convert_handle_message_event(event)
+            if abm.sender.user_id == "2854196310":
+                # 屏蔽 QQ 管家的消息
+                return
         elif event["post_type"] == "notice":
             abm = await self._convert_handle_notice_event(event)
         elif event["post_type"] == "request":
@@ -111,7 +116,7 @@ class AiocqhttpAdapter(Platform):
         """OneBot V11 请求类事件"""
         abm = AstrBotMessage()
         abm.self_id = str(event.self_id)
-        abm.sender = MessageMember(user_id=event.user_id, nickname=event.user_id)
+        abm.sender = MessageMember(user_id=str(event.user_id), nickname=event.user_id)
         abm.type = MessageType.OTHER_MESSAGE
         if "group_id" in event and event["group_id"]:
             abm.type = MessageType.GROUP_MESSAGE
@@ -120,6 +125,12 @@ class AiocqhttpAdapter(Platform):
             abm.type = MessageType.FRIEND_MESSAGE
         if self.unique_session and abm.type == MessageType.GROUP_MESSAGE:
             abm.session_id = str(abm.sender.user_id) + "_" + str(event.group_id)
+        else:
+            abm.session_id = (
+                str(event.group_id)
+                if abm.type == MessageType.GROUP_MESSAGE
+                else abm.sender.user_id
+            )
         abm.message_str = ""
         abm.message = []
         abm.timestamp = int(time.time())
@@ -131,7 +142,7 @@ class AiocqhttpAdapter(Platform):
         """OneBot V11 通知类事件"""
         abm = AstrBotMessage()
         abm.self_id = str(event.self_id)
-        abm.sender = MessageMember(user_id=event.user_id, nickname=event.user_id)
+        abm.sender = MessageMember(user_id=str(event.user_id), nickname=event.user_id)
         abm.type = MessageType.OTHER_MESSAGE
         if "group_id" in event and event["group_id"]:
             abm.group_id = str(event.group_id)
@@ -140,7 +151,7 @@ class AiocqhttpAdapter(Platform):
             abm.type = MessageType.FRIEND_MESSAGE
         if self.unique_session and abm.type == MessageType.GROUP_MESSAGE:
             abm.session_id = (
-                abm.sender.user_id + "_" + str(event.group_id)
+                str(abm.sender.user_id) + "_" + str(event.group_id)
             )  # 也保留群组 id
         else:
             abm.session_id = (
@@ -160,8 +171,14 @@ class AiocqhttpAdapter(Platform):
 
         return abm
 
-    async def _convert_handle_message_event(self, event: Event) -> AstrBotMessage:
-        """OneBot V11 消息类事件"""
+    async def _convert_handle_message_event(
+        self, event: Event, get_reply=True
+    ) -> AstrBotMessage:
+        """OneBot V11 消息类事件
+
+        @param event: 事件对象
+        @param get_reply: 是否获取回复消息。这个参数是为了防止多个回复嵌套。
+        """
         abm = AstrBotMessage()
         abm.self_id = str(event.self_id)
         abm.sender = MessageMember(
@@ -197,52 +214,132 @@ class AiocqhttpAdapter(Platform):
             return
 
         # 按消息段类型类型适配
-        for m in event.message:
-            t = m["type"]
+        for t, m_group in itertools.groupby(event.message, key=lambda x: x["type"]):
             a = None
             if t == "text":
-                message_str += m["data"]["text"].strip()
-                a = ComponentTypes[t](**m["data"])  # noqa: F405
+                current_text = "".join(m["data"]["text"] for m in m_group).strip()
+                if not current_text:
+                    # 如果文本段为空，则跳过
+                    continue
+                message_str += current_text
+                a = ComponentTypes[t](text=current_text)  # noqa: F405
                 abm.message.append(a)
 
             elif t == "file":
-                if m["data"].get("url") and m["data"].get("url").startswith("http"):
-                    # Lagrange
-                    logger.info("guessing lagrange")
+                for m in m_group:
+                    if m["data"].get("url") and m["data"].get("url").startswith("http"):
+                        # Lagrange
+                        logger.info("guessing lagrange")
+                        file_name = m["data"].get("file_name", "file")
+                        abm.message.append(File(name=file_name, url=m["data"]["url"]))
+                    else:
+                        try:
+                            # Napcat
+                            ret = None
+                            if abm.type == MessageType.GROUP_MESSAGE:
+                                ret = await self.bot.call_action(
+                                    action="get_group_file_url",
+                                    file_id=event.message[0]["data"]["file_id"],
+                                    group_id=event.group_id,
+                                )
+                            elif abm.type == MessageType.FRIEND_MESSAGE:
+                                ret = await self.bot.call_action(
+                                    action="get_private_file_url",
+                                    file_id=event.message[0]["data"]["file_id"],
+                                )
+                            if ret and "url" in ret:
+                                file_url = ret["url"]  # https
+                                a = File(name="", url=file_url)
+                                abm.message.append(a)
+                            else:
+                                logger.error(f"获取文件失败: {ret}")
 
-                    file_name = m["data"].get("file_name", "file")
-                    path = os.path.join("data/temp", file_name)
-                    await download_file(m["data"]["url"], path)
+                        except ActionFailed as e:
+                            logger.error(f"获取文件失败: {e}，此消息段将被忽略。")
+                        except BaseException as e:
+                            logger.error(f"获取文件失败: {e}，此消息段将被忽略。")
 
-                    m["data"] = {"file": path, "name": file_name}
-                    a = ComponentTypes[t](**m["data"])  # noqa: F405
-                    abm.message.append(a)
-
-                else:
-                    try:
-                        # Napcat, LLBot
-                        ret = await self.bot.call_action(
-                            action="get_file",
-                            file_id=event.message[0]["data"]["file_id"],
-                        )
-                        if not ret.get("file", None):
-                            raise ValueError(f"无法解析文件响应: {ret}")
-                        if not os.path.exists(ret["file"]):
-                            raise FileNotFoundError(
-                                f"文件不存在或者权限问题: {ret['file']}。如果您使用 Docker 部署了 AstrBot 或者消息协议端(Napcat等),请先映射路径。如果路径在 /root 目录下，请用 sudo 打开 AstrBot"
-                            )
-
-                        m["data"] = {"file": ret["file"], "name": ret["file_name"]}
+            elif t == "reply":
+                for m in m_group:
+                    if not get_reply:
                         a = ComponentTypes[t](**m["data"])  # noqa: F405
                         abm.message.append(a)
-                    except ActionFailed as e:
-                        logger.error(f"获取文件失败: {e}，此消息段将被忽略。")
-                    except BaseException as e:
-                        logger.error(f"获取文件失败: {e}，此消息段将被忽略。")
+                    else:
+                        try:
+                            reply_event_data = await self.bot.call_action(
+                                action="get_msg",
+                                message_id=int(m["data"]["id"]),
+                            )
+                            # 添加必要的 post_type 字段，防止 Event.from_payload 报错
+                            reply_event_data["post_type"] = "message"
+                            new_event = Event.from_payload(reply_event_data)
+                            if not new_event:
+                                logger.error(
+                                    f"无法从回复消息数据构造 Event 对象: {reply_event_data}"
+                                )
+                                continue
+                            abm_reply = await self._convert_handle_message_event(
+                                new_event, get_reply=False
+                            )
 
+                            reply_seg = Reply(
+                                id=abm_reply.message_id,
+                                chain=abm_reply.message,
+                                sender_id=abm_reply.sender.user_id,
+                                sender_nickname=abm_reply.sender.nickname,
+                                time=abm_reply.timestamp,
+                                message_str=abm_reply.message_str,
+                                text=abm_reply.message_str,  # for compatibility
+                                qq=abm_reply.sender.user_id,  # for compatibility
+                            )
+
+                            abm.message.append(reply_seg)
+                        except BaseException as e:
+                            logger.error(f"获取引用消息失败: {e}。")
+                            a = ComponentTypes[t](**m["data"])  # noqa: F405
+                            abm.message.append(a)
+            elif t == "at":
+                first_at_self_processed = False
+
+                for m in m_group:
+                    try:
+                        if m["data"]["qq"] == "all":
+                            abm.message.append(At(qq="all", name="全体成员"))
+                            continue
+
+                        at_info = await self.bot.call_action(
+                            action="get_stranger_info",
+                            user_id=int(m["data"]["qq"]),
+                        )
+                        if at_info:
+                            nickname = at_info.get("nick", "") or at_info.get(
+                                "nickname", ""
+                            )
+                            is_at_self = str(m["data"]["qq"]) in {abm.self_id, "all"}
+
+                            abm.message.append(
+                                At(
+                                    qq=m["data"]["qq"],
+                                    name=nickname,
+                                )
+                            )
+
+                            if is_at_self and not first_at_self_processed:
+                                # 第一个@是机器人，不添加到message_str
+                                first_at_self_processed = True
+                            else:
+                                # 非第一个@机器人或@其他用户，添加到message_str
+                                message_str += f" @{nickname}({m['data']['qq']}) "
+                        else:
+                            abm.message.append(At(qq=str(m["data"]["qq"]), name=""))
+                    except ActionFailed as e:
+                        logger.error(f"获取 @ 用户信息失败: {e}，此消息段将被忽略。")
+                    except BaseException as e:
+                        logger.error(f"获取 @ 用户信息失败: {e}，此消息段将被忽略。")
             else:
-                a = ComponentTypes[t](**m["data"])  # noqa: F405
-                abm.message.append(a)
+                for m in m_group:
+                    a = ComponentTypes[t](**m["data"])  # noqa: F405
+                    abm.message.append(a)
 
         abm.timestamp = int(time.time())
         abm.message_str = message_str
@@ -267,22 +364,19 @@ class AiocqhttpAdapter(Platform):
         for handler in logging.root.handlers[:]:
             logging.root.removeHandler(handler)
         logging.getLogger("aiocqhttp").setLevel(logging.ERROR)
-
+        self.shutdown_event = asyncio.Event()
         return coro
 
     async def terminate(self):
-        self.stop = True
-        await asyncio.sleep(1)
+        self.shutdown_event.set()
+
+    async def shutdown_trigger_placeholder(self):
+        await self.shutdown_event.wait()
+        logger.info("aiocqhttp 适配器已被优雅地关闭")
 
     def meta(self) -> PlatformMetadata:
         return self.metadata
 
-    async def shutdown_trigger_placeholder(self):
-        # TODO: use asyncio.Event
-        while not self._event_queue.closed and not self.stop:  # noqa: ASYNC110
-            await asyncio.sleep(1)
-        logger.info("aiocqhttp 适配器已关闭。")
-
     async def handle_msg(self, message: AstrBotMessage):
         message_event = AiocqhttpMessageEvent(
             message_str=message.message_str,

astrbot/core/platform/sources/dingtalk/dingtalk_adapter.py

@@ -0,0 +1,231 @@
+import asyncio
+import os
+import uuid
+import aiohttp
+import dingtalk_stream
+import threading
+
+from astrbot.api.platform import (
+    Platform,
+    AstrBotMessage,
+    MessageMember,
+    MessageType,
+    PlatformMetadata,
+)
+from astrbot.api.event import MessageChain
+from astrbot.api.message_components import Image, Plain, At
+from astrbot.core.platform.astr_message_event import MessageSesion
+from .dingtalk_event import DingtalkMessageEvent
+from ...register import register_platform_adapter
+from astrbot import logger
+from dingtalk_stream import AckMessage
+from astrbot.core.utils.io import download_file
+from astrbot.core.utils.astrbot_path import get_astrbot_data_path
+
+
+class MyEventHandler(dingtalk_stream.EventHandler):
+    async def process(self, event: dingtalk_stream.EventMessage):
+        print(
+            "2",
+            event.headers.event_type,
+            event.headers.event_id,
+            event.headers.event_born_time,
+            event.data,
+        )
+        return AckMessage.STATUS_OK, "OK"
+
+
+@register_platform_adapter("dingtalk", "钉钉机器人官方 API 适配器")
+class DingtalkPlatformAdapter(Platform):
+    def __init__(
+        self, platform_config: dict, platform_settings: dict, event_queue: asyncio.Queue
+    ) -> None:
+        super().__init__(event_queue)
+
+        self.config = platform_config
+
+        self.unique_session = platform_settings["unique_session"]
+
+        self.client_id = platform_config["client_id"]
+        self.client_secret = platform_config["client_secret"]
+
+        class AstrCallbackClient(dingtalk_stream.ChatbotHandler):
+            async def process(self_, message: dingtalk_stream.CallbackMessage):
+                logger.debug(f"dingtalk: {message.data}")
+                im = dingtalk_stream.ChatbotMessage.from_dict(message.data)
+                abm = await self.convert_msg(im)
+                await self.handle_msg(abm)
+
+                return AckMessage.STATUS_OK, "OK"
+
+        self.client = AstrCallbackClient()
+
+        credential = dingtalk_stream.Credential(self.client_id, self.client_secret)
+        client = dingtalk_stream.DingTalkStreamClient(credential, logger=logger)
+        client.register_all_event_handler(MyEventHandler())
+        client.register_callback_handler(
+            dingtalk_stream.ChatbotMessage.TOPIC, self.client
+        )
+        self.client_ = client  # 用于 websockets 的 client
+
+    async def send_by_session(
+        self, session: MessageSesion, message_chain: MessageChain
+    ):
+        raise NotImplementedError("钉钉机器人适配器不支持 send_by_session")
+
+    def meta(self) -> PlatformMetadata:
+        return PlatformMetadata(
+            name="dingtalk",
+            description="钉钉机器人官方 API 适配器",
+            id=self.config.get("id"),
+        )
+
+    async def convert_msg(
+        self, message: dingtalk_stream.ChatbotMessage
+    ) -> AstrBotMessage:
+        abm = AstrBotMessage()
+        abm.message = []
+        abm.message_str = ""
+        abm.timestamp = int(message.create_at / 1000)
+        abm.type = (
+            MessageType.GROUP_MESSAGE
+            if message.conversation_type == "2"
+            else MessageType.FRIEND_MESSAGE
+        )
+        abm.sender = MessageMember(
+            user_id=message.sender_id, nickname=message.sender_nick
+        )
+        abm.self_id = message.chatbot_user_id
+        abm.message_id = message.message_id
+        abm.raw_message = message
+
+        if abm.type == MessageType.GROUP_MESSAGE:
+            if message.is_in_at_list:
+                abm.message.append(At(qq=abm.self_id))
+            abm.group_id = message.conversation_id
+            if self.unique_session:
+                abm.session_id = abm.sender.user_id
+            else:
+                abm.session_id = abm.group_id
+        else:
+            abm.session_id = abm.sender.user_id
+
+        message_type: str = message.message_type
+        match message_type:
+            case "text":
+                abm.message_str = message.text.content.strip()
+                abm.message.append(Plain(abm.message_str))
+            case "richText":
+                rtc: dingtalk_stream.RichTextContent = message.rich_text_content
+                contents: list[dict] = rtc.rich_text_list
+                for content in contents:
+                    plains = ""
+                    if "text" in content:
+                        plains += content["text"]
+                        abm.message.append(Plain(plains))
+                    elif "type" in content and content["type"] == "picture":
+                        f_path = await self.download_ding_file(
+                            content["downloadCode"],
+                            message.robot_code,
+                            "jpg",
+                        )
+                        abm.message.append(Image.fromFileSystem(f_path))
+            case "audio":
+                pass
+
+        return abm  # 别忘了返回转换后的消息对象
+
+    async def download_ding_file(
+        self, download_code: str, robot_code: str, ext: str
+    ) -> str:
+        """下载钉钉文件
+
+        :param access_token: 钉钉机器人的 access_token
+        :param download_code: 下载码
+        :param robot_code: 机器人码
+        :param ext: 文件后缀
+        :return: 文件路径
+        """
+        access_token = await self.get_access_token()
+        headers = {
+            "x-acs-dingtalk-access-token": access_token,
+        }
+        payload = {
+            "downloadCode": download_code,
+            "robotCode": robot_code,
+        }
+        temp_dir = os.path.join(get_astrbot_data_path(), "temp")
+        f_path = os.path.join(temp_dir, f"dingtalk_file_{uuid.uuid4()}.{ext}")
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                "https://api.dingtalk.com/v1.0/robot/messageFiles/download",
+                headers=headers,
+                json=payload,
+            ) as resp:
+                if resp.status != 200:
+                    logger.error(
+                        f"下载钉钉文件失败: {resp.status}, {await resp.text()}"
+                    )
+                    return None
+                resp_data = await resp.json()
+                download_url = resp_data["data"]["downloadUrl"]
+                await download_file(download_url, f_path)
+        return f_path
+
+    async def get_access_token(self) -> str:
+        payload = {
+            "appKey": self.client_id,
+            "appSecret": self.client_secret,
+        }
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                "https://api.dingtalk.com/v1.0/oauth2/accessToken",
+                json=payload,
+            ) as resp:
+                if resp.status != 200:
+                    logger.error(
+                        f"获取钉钉机器人 access_token 失败: {resp.status}, {await resp.text()}"
+                    )
+                    return None
+                return (await resp.json())["data"]["accessToken"]
+
+    async def handle_msg(self, abm: AstrBotMessage):
+        event = DingtalkMessageEvent(
+            message_str=abm.message_str,
+            message_obj=abm,
+            platform_meta=self.meta(),
+            session_id=abm.session_id,
+            client=self.client,
+        )
+
+        self._event_queue.put_nowait(event)
+
+    async def run(self):
+        # await self.client_.start()
+        # 钉钉的 SDK 并没有实现真正的异步，start() 里面有堵塞方法。
+        def start_client(loop: asyncio.AbstractEventLoop):
+            try:
+                self._shutdown_event = threading.Event()
+                task = loop.create_task(self.client_.start())
+                self._shutdown_event.wait()
+                if task.done():
+                    task.result()
+            except Exception as e:
+                if "Graceful shutdown" in str(e):
+                    logger.info("钉钉适配器已被优雅地关闭")
+                    return
+                logger.error(f"钉钉机器人启动失败: {e}")
+
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, start_client, loop)
+
+    async def terminate(self):
+        def monkey_patch_close():
+            raise Exception("Graceful shutdown")
+
+        self.client_.open_connection = monkey_patch_close
+        await self.client_.websocket.close(code=1000, reason="Graceful shutdown")
+        self._shutdown_event.set()
+
+    def get_client(self):
+        return self.client

astrbot/core/platform/sources/dingtalk/dingtalk_event.py

@@ -0,0 +1,76 @@
+import asyncio
+import dingtalk_stream
+import astrbot.api.message_components as Comp
+from astrbot.api.event import AstrMessageEvent, MessageChain
+from astrbot import logger
+
+
+class DingtalkMessageEvent(AstrMessageEvent):
+    def __init__(
+        self,
+        message_str,
+        message_obj,
+        platform_meta,
+        session_id,
+        client: dingtalk_stream.ChatbotHandler,
+    ):
+        super().__init__(message_str, message_obj, platform_meta, session_id)
+        self.client = client
+
+    async def send_with_client(
+        self, client: dingtalk_stream.ChatbotHandler, message: MessageChain
+    ):
+        for segment in message.chain:
+            if isinstance(segment, Comp.Plain):
+                segment.text = segment.text.strip()
+                await asyncio.get_event_loop().run_in_executor(
+                    None,
+                    client.reply_markdown,
+                    "AstrBot",
+                    segment.text,
+                    self.message_obj.raw_message,
+                )
+            elif isinstance(segment, Comp.Image):
+                markdown_str = ""
+
+                try:
+                    if not segment.file:
+                        logger.warning("钉钉图片 segment 缺少 file 字段，跳过")
+                        continue
+                    if segment.file.startswith(("http://", "https://")):
+                        image_url = segment.file
+                    else:
+                        image_url = await segment.register_to_file_service()
+
+                    markdown_str = f"![image]({image_url})\n\n"
+
+                    ret = await asyncio.get_event_loop().run_in_executor(
+                        None,
+                        client.reply_markdown,
+                        "😄",
+                        markdown_str,
+                        self.message_obj.raw_message,
+                    )
+                    logger.debug(f"send image: {ret}")
+
+                except Exception as e:
+                    logger.error(f"钉钉图片处理失败: {e}")
+                    logger.warning(f"跳过图片发送: {image_path}")
+                    continue
+
+    async def send(self, message: MessageChain):
+        await self.send_with_client(self.client, message)
+        await super().send(message)
+
+    async def send_streaming(self, generator, use_fallback: bool = False):
+        buffer = None
+        async for chain in generator:
+            if not buffer:
+                buffer = chain
+            else:
+                buffer.chain.extend(chain.chain)
+        if not buffer:
+            return
+        buffer.squash_plain()
+        await self.send(buffer)
+        return await super().send_streaming(generator, use_fallback)

astrbot/core/platform/sources/discord/client.py

@@ -0,0 +1,126 @@
+import discord
+from astrbot import logger
+import sys
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+
+# Discord Bot客户端
+class DiscordBotClient(discord.Bot):
+    """Discord客户端封装"""
+
+    def __init__(self, token: str, proxy: str = None):
+        self.token = token
+        self.proxy = proxy
+
+        # 设置Intent权限，遵循权限最小化原则
+        intents = discord.Intents.default()
+        intents.message_content = True  # 订阅消息内容事件 (Privileged)
+        intents.members = True  # 订阅成员事件 (Privileged)
+
+        # 初始化Bot
+        super().__init__(intents=intents, proxy=proxy)
+
+        # 回调函数
+        self.on_message_received = None
+        self.on_ready_once_callback = None
+        self._ready_once_fired = False
+
+    @override
+    async def on_ready(self):
+        """当机器人成功连接并准备就绪时触发"""
+        logger.info(f"[Discord] 已作为 {self.user} (ID: {self.user.id}) 登录")
+        logger.info("[Discord] 客户端已准备就绪。")
+
+        if self.on_ready_once_callback and not self._ready_once_fired:
+            self._ready_once_fired = True
+            try:
+                await self.on_ready_once_callback()
+            except Exception as e:
+                logger.error(
+                    f"[Discord] on_ready_once_callback 执行失败: {e}", exc_info=True
+                )
+
+    def _create_message_data(self, message: discord.Message) -> dict:
+        """从 discord.Message 创建数据字典"""
+        is_mentioned = self.user in message.mentions
+        return {
+            "message": message,
+            "bot_id": str(self.user.id),
+            "content": message.content,
+            "username": message.author.display_name,
+            "userid": str(message.author.id),
+            "message_id": str(message.id),
+            "channel_id": str(message.channel.id),
+            "guild_id": str(message.guild.id) if message.guild else None,
+            "type": "message",
+            "is_mentioned": is_mentioned,
+            "clean_content": message.clean_content,
+        }
+
+    def _create_interaction_data(self, interaction: discord.Interaction) -> dict:
+        """从 discord.Interaction 创建数据字典"""
+        return {
+            "interaction": interaction,
+            "bot_id": str(self.user.id),
+            "content": self._extract_interaction_content(interaction),
+            "username": interaction.user.display_name,
+            "userid": str(interaction.user.id),
+            "message_id": str(interaction.id),
+            "channel_id": str(interaction.channel_id)
+            if interaction.channel_id
+            else None,
+            "guild_id": str(interaction.guild_id) if interaction.guild_id else None,
+            "type": "interaction",
+        }
+
+    @override
+    async def on_message(self, message: discord.Message):
+        """当接收到消息时触发"""
+        if message.author.bot:
+            return
+
+        logger.debug(
+            f"[Discord] 收到原始消息 from {message.author.name}: {message.content}"
+        )
+
+        if self.on_message_received:
+            message_data = self._create_message_data(message)
+            await self.on_message_received(message_data)
+
+    def _extract_interaction_content(self, interaction: discord.Interaction) -> str:
+        """从交互中提取内容"""
+        interaction_type = interaction.type
+        interaction_data = getattr(interaction, "data", {})
+
+        if not interaction_data:
+            return ""
+
+        if interaction_type == discord.InteractionType.application_command:
+            command_name = interaction_data.get("name", "")
+            if options := interaction_data.get("options", []):
+                params = " ".join(
+                    [f"{opt['name']}:{opt.get('value', '')}" for opt in options]
+                )
+                return f"/{command_name} {params}"
+            return f"/{command_name}"
+
+        elif interaction_type == discord.InteractionType.component:
+            custom_id = interaction_data.get("custom_id", "")
+            component_type = interaction_data.get("component_type", "")
+            return f"component:{custom_id}:{component_type}"
+
+        return str(interaction_data)
+
+    async def start_polling(self):
+        """开始轮询消息，这是个阻塞方法"""
+        await self.start(self.token)
+
+    @override
+    async def close(self):
+        """关闭客户端"""
+        if not self.is_closed():
+            await super().close()

astrbot/core/platform/sources/discord/components.py

@@ -0,0 +1,135 @@
+import discord
+from typing import List
+from astrbot.api.message_components import BaseMessageComponent
+
+
+# Discord专用组件
+class DiscordEmbed(BaseMessageComponent):
+    """Discord Embed消息组件"""
+
+    type: str = "discord_embed"
+
+    def __init__(
+        self,
+        title: str = None,
+        description: str = None,
+        color: int = None,
+        url: str = None,
+        thumbnail: str = None,
+        image: str = None,
+        footer: str = None,
+        fields: List[dict] = None,
+    ):
+        self.title = title
+        self.description = description
+        self.color = color
+        self.url = url
+        self.thumbnail = thumbnail
+        self.image = image
+        self.footer = footer
+        self.fields = fields or []
+
+    def to_discord_embed(self) -> discord.Embed:
+        """转换为Discord Embed对象"""
+        embed = discord.Embed()
+
+        if self.title:
+            embed.title = self.title
+        if self.description:
+            embed.description = self.description
+        if self.color:
+            embed.color = self.color
+        if self.url:
+            embed.url = self.url
+        if self.thumbnail:
+            embed.set_thumbnail(url=self.thumbnail)
+        if self.image:
+            embed.set_image(url=self.image)
+        if self.footer:
+            embed.set_footer(text=self.footer)
+
+        for field in self.fields:
+            embed.add_field(
+                name=field.get("name", ""),
+                value=field.get("value", ""),
+                inline=field.get("inline", False),
+            )
+
+        return embed
+
+
+class DiscordButton(BaseMessageComponent):
+    """Discord按钮组件"""
+
+    type: str = "discord_button"
+
+    def __init__(
+        self,
+        label: str,
+        custom_id: str = None,
+        style: str = "primary",
+        emoji: str = None,
+        url: str = None,
+        disabled: bool = False,
+    ):
+        self.label = label
+        self.custom_id = custom_id
+        self.style = style
+        self.emoji = emoji
+        self.url = url
+        self.disabled = disabled
+
+
+class DiscordReference(BaseMessageComponent):
+    """Discord引用组件"""
+
+    type: str = "discord_reference"
+
+    def __init__(self, message_id: str, channel_id: str):
+        self.message_id = message_id
+        self.channel_id = channel_id
+
+
+class DiscordView(BaseMessageComponent):
+    """Discord视图组件，包含按钮和选择菜单"""
+
+    type: str = "discord_view"
+
+    def __init__(
+        self, components: List[BaseMessageComponent] = None, timeout: float = None
+    ):
+        self.components = components or []
+        self.timeout = timeout
+
+    def to_discord_view(self) -> discord.ui.View:
+        """转换为Discord View对象"""
+        view = discord.ui.View(timeout=self.timeout)
+
+        for component in self.components:
+            if isinstance(component, DiscordButton):
+                button_style = getattr(
+                    discord.ButtonStyle, component.style, discord.ButtonStyle.primary
+                )
+
+                if component.url:
+                    # URL按钮
+                    button = discord.ui.Button(
+                        label=component.label,
+                        style=discord.ButtonStyle.link,
+                        url=component.url,
+                        emoji=component.emoji,
+                        disabled=component.disabled,
+                    )
+                else:
+                    # 普通按钮
+                    button = discord.ui.Button(
+                        label=component.label,
+                        style=button_style,
+                        custom_id=component.custom_id,
+                        emoji=component.emoji,
+                        disabled=component.disabled,
+                    )
+
+                view.add_item(button)
+
+        return view

astrbot/core/platform/sources/discord/discord_platform_adapter.py

@@ -0,0 +1,455 @@
+import asyncio
+import discord
+import sys
+import re
+from discord.abc import Messageable
+from discord.channel import DMChannel
+from astrbot.api.platform import (
+    Platform,
+    AstrBotMessage,
+    MessageMember,
+    PlatformMetadata,
+    MessageType,
+)
+from astrbot.api.event import MessageChain
+from astrbot.api.message_components import Plain, Image, File
+from astrbot.core.platform.astr_message_event import MessageSesion
+from astrbot.api.platform import register_platform_adapter
+from astrbot import logger
+from .client import DiscordBotClient
+from .discord_platform_event import DiscordPlatformEvent
+
+from typing import Any, Tuple
+from astrbot.core.star.filter.command import CommandFilter
+from astrbot.core.star.filter.command_group import CommandGroupFilter
+from astrbot.core.star.star import star_map
+from astrbot.core.star.star_handler import StarHandlerMetadata, star_handlers_registry
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+
+# 注册平台适配器
+@register_platform_adapter("discord", "Discord 适配器 (基于 Pycord)")
+class DiscordPlatformAdapter(Platform):
+    def __init__(
+        self, platform_config: dict, platform_settings: dict, event_queue: asyncio.Queue
+    ) -> None:
+        super().__init__(event_queue)
+        self.config = platform_config
+        self.settings = platform_settings
+        self.client_self_id = None
+        self.registered_handlers = []
+        # 指令注册相关
+        self.enable_command_register = self.config.get("discord_command_register", True)
+        self.guild_id = self.config.get("discord_guild_id_for_debug", None)
+        self.activity_name = self.config.get("discord_activity_name", None)
+        self.shutdown_event = asyncio.Event()
+        self._polling_task = None
+
+    @override
+    async def send_by_session(
+        self, session: MessageSesion, message_chain: MessageChain
+    ):
+        """通过会话发送消息"""
+        # 创建一个 message_obj 以便在 event 中使用
+        message_obj = AstrBotMessage()
+        if "_" in session.session_id:
+            session.session_id = session.session_id.split("_")[1]
+        channel_id_str = session.session_id
+        channel = None
+        try:
+            channel_id = int(channel_id_str)
+            channel = self.client.get_channel(channel_id)
+        except (ValueError, TypeError):
+            logger.warning(f"[Discord] Invalid channel ID format: {channel_id_str}")
+
+        if channel:
+            message_obj.type = self._get_message_type(channel)
+            message_obj.group_id = self._get_channel_id(channel)
+        else:
+            logger.warning(
+                f"[Discord] Can't get channel info for {channel_id_str}, will guess message type."
+            )
+            message_obj.type = MessageType.GROUP_MESSAGE
+            message_obj.group_id = session.session_id
+
+        message_obj.message_str = message_chain.get_plain_text()
+        message_obj.sender = MessageMember(
+            user_id=str(self.client_self_id), nickname=self.client.user.display_name
+        )
+        message_obj.self_id = self.client_self_id
+        message_obj.session_id = session.session_id
+        message_obj.message = message_chain
+
+        # 创建临时事件对象来发送消息
+        temp_event = DiscordPlatformEvent(
+            message_str=message_chain.get_plain_text(),
+            message_obj=message_obj,
+            platform_meta=self.meta(),
+            session_id=session.session_id,
+            client=self.client,
+        )
+        await temp_event.send(message_chain)
+        await super().send_by_session(session, message_chain)
+
+    @override
+    def meta(self) -> PlatformMetadata:
+        """返回平台元数据"""
+        return PlatformMetadata(
+            "discord",
+            "Discord 适配器",
+            id=self.config.get("id"),
+            default_config_tmpl=self.config,
+        )
+
+    @override
+    async def run(self):
+        """主要运行逻辑"""
+
+        # 初始化回调函数
+        async def on_received(message_data):
+            logger.debug(f"[Discord] 收到消息: {message_data}")
+            if self.client_self_id is None:
+                self.client_self_id = message_data.get("bot_id")
+            abm = await self.convert_message(data=message_data)
+            await self.handle_msg(abm)
+
+        # 初始化 Discord 客户端
+        token = str(self.config.get("discord_token"))
+        if not token:
+            logger.error("[Discord] Bot Token 未配置。请在配置文件中正确设置 token。")
+            return
+
+        proxy = self.config.get("discord_proxy") or None
+        self.client = DiscordBotClient(token, proxy)
+        self.client.on_message_received = on_received
+
+        async def callback():
+            if self.enable_command_register:
+                await self._collect_and_register_commands()
+            if self.activity_name:
+                await self.client.change_presence(
+                    status=discord.Status.online,
+                    activity=discord.CustomActivity(name=self.activity_name),
+                )
+
+        self.client.on_ready_once_callback = callback
+
+        try:
+            self._polling_task = asyncio.create_task(self.client.start_polling())
+            await self.shutdown_event.wait()
+        except discord.errors.LoginFailure:
+            logger.error("[Discord] 登录失败。请检查你的 Bot Token 是否正确。")
+        except discord.errors.ConnectionClosed:
+            logger.warning("[Discord] 与 Discord 的连接已关闭。")
+        except Exception as e:
+            logger.error(f"[Discord] 适配器运行时发生意外错误: {e}", exc_info=True)
+
+    def _get_message_type(
+        self, channel: Messageable, guild_id: int | None = None
+    ) -> MessageType:
+        """根据 channel 对象和 guild_id 判断消息类型"""
+        if guild_id is not None:
+            return MessageType.GROUP_MESSAGE
+        if isinstance(channel, DMChannel) or getattr(channel, "guild", None) is None:
+            return MessageType.FRIEND_MESSAGE
+        return MessageType.GROUP_MESSAGE
+
+    def _get_channel_id(self, channel: Messageable) -> str:
+        """根据 channel 对象获取ID"""
+        return str(getattr(channel, "id", None))
+
+    def _convert_message_to_abm(self, data: dict) -> AstrBotMessage:
+        """将普通消息转换为 AstrBotMessage"""
+        message: discord.Message = data["message"]
+
+        content = message.content
+
+        # 如果机器人被@，移除@部分
+        # 剥离 User Mention (<@id>, <@!id>)
+        if self.client and self.client.user:
+            mention_str = f"<@{self.client.user.id}>"
+            mention_str_nickname = f"<@!{self.client.user.id}>"
+            if content.startswith(mention_str):
+                content = content[len(mention_str) :].lstrip()
+            elif content.startswith(mention_str_nickname):
+                content = content[len(mention_str_nickname) :].lstrip()
+
+        # 剥离 Role Mention（bot 拥有的任一角色被提及，<@&role_id>）
+        if (
+            hasattr(message, "role_mentions")
+            and hasattr(message, "guild")
+            and message.guild
+        ):
+            bot_member = (
+                message.guild.get_member(self.client.user.id)
+                if self.client and self.client.user
+                else None
+            )
+            if bot_member and hasattr(bot_member, "roles"):
+                for role in bot_member.roles:
+                    role_mention_str = f"<@&{role.id}>"
+                    if content.startswith(role_mention_str):
+                        content = content[len(role_mention_str) :].lstrip()
+                        break  # 只剥离第一个匹配的角色 mention
+
+        abm = AstrBotMessage()
+        abm.type = self._get_message_type(message.channel)
+        abm.group_id = self._get_channel_id(message.channel)
+        abm.message_str = content
+        abm.sender = MessageMember(
+            user_id=str(message.author.id), nickname=message.author.display_name
+        )
+        message_chain = []
+        if abm.message_str:
+            message_chain.append(Plain(text=abm.message_str))
+        if message.attachments:
+            for attachment in message.attachments:
+                if attachment.content_type and attachment.content_type.startswith(
+                    "image/"
+                ):
+                    message_chain.append(
+                        Image(file=attachment.url, filename=attachment.filename)
+                    )
+                else:
+                    message_chain.append(
+                        File(name=attachment.filename, url=attachment.url)
+                    )
+        abm.message = message_chain
+        abm.raw_message = message
+        abm.self_id = self.client_self_id
+        abm.session_id = str(message.channel.id)
+        abm.message_id = str(message.id)
+        return abm
+
+    async def convert_message(self, data: dict) -> AstrBotMessage:
+        """将平台消息转换成 AstrBotMessage"""
+        # 由于 on_interaction 已被禁用，我们只处理普通消息
+        return self._convert_message_to_abm(data)
+
+    async def handle_msg(self, message: AstrBotMessage, followup_webhook=None):
+        """处理消息"""
+        message_event = DiscordPlatformEvent(
+            message_str=message.message_str,
+            message_obj=message,
+            platform_meta=self.meta(),
+            session_id=message.session_id,
+            client=self.client,
+            interaction_followup_webhook=followup_webhook,
+        )
+
+        # 检查是否为斜杠指令
+        is_slash_command = message_event.interaction_followup_webhook is not None
+
+        # 检查是否被@（User Mention 或 Bot 拥有的 Role Mention）
+        is_mention = False
+        # User Mention
+        if (
+            self.client
+            and self.client.user
+            and hasattr(message.raw_message, "mentions")
+        ):
+            if self.client.user in message.raw_message.mentions:
+                is_mention = True
+        # Role Mention（Bot 拥有的角色被提及）
+        if not is_mention and hasattr(message.raw_message, "role_mentions"):
+            bot_member = None
+            if hasattr(message.raw_message, "guild") and message.raw_message.guild:
+                try:
+                    bot_member = message.raw_message.guild.get_member(
+                        self.client.user.id
+                    )
+                except Exception:
+                    bot_member = None
+            if bot_member and hasattr(bot_member, "roles"):
+                bot_roles = set(bot_member.roles)
+                mentioned_roles = set(message.raw_message.role_mentions)
+                if (
+                    bot_roles
+                    and mentioned_roles
+                    and bot_roles.intersection(mentioned_roles)
+                ):
+                    is_mention = True
+
+        # 如果是斜杠指令或被@的消息，设置为唤醒状态
+        if is_slash_command or is_mention:
+            message_event.is_wake = True
+            message_event.is_at_or_wake_command = True
+
+        self.commit_event(message_event)
+
+    @override
+    async def terminate(self):
+        """终止适配器"""
+        logger.info("[Discord] 正在终止适配器... (step 1: cancel polling task)")
+        self.shutdown_event.set()
+        # 优先 cancel polling_task
+        if self._polling_task:
+            self._polling_task.cancel()
+            try:
+                await asyncio.wait_for(self._polling_task, timeout=10)
+            except asyncio.CancelledError:
+                logger.info("[Discord] polling_task 已取消。")
+            except Exception as e:
+                logger.warning(f"[Discord] polling_task 取消异常: {e}")
+        logger.info("[Discord] 正在清理已注册的斜杠指令... (step 2)")
+        # 清理指令
+        if self.enable_command_register and self.client:
+            try:
+                await asyncio.wait_for(
+                    self.client.sync_commands(
+                        commands=[],
+                        guild_ids=[self.guild_id] if self.guild_id else None,
+                    ),
+                    timeout=10,
+                )
+                logger.info("[Discord] 指令清理完成。")
+            except Exception as e:
+                logger.error(f"[Discord] 清理指令时发生错误: {e}", exc_info=True)
+        logger.info("[Discord] 正在关闭 Discord 客户端... (step 3)")
+        if self.client and hasattr(self.client, "close"):
+            try:
+                await asyncio.wait_for(self.client.close(), timeout=10)
+            except Exception as e:
+                logger.warning(f"[Discord] 客户端关闭异常: {e}")
+        logger.info("[Discord] 适配器已终止。")
+
+    def register_handler(self, handler_info):
+        """注册处理器信息"""
+        self.registered_handlers.append(handler_info)
+
+    async def _collect_and_register_commands(self):
+        """收集所有指令并注册到Discord"""
+        logger.info("[Discord] 开始收集并注册斜杠指令...")
+        registered_commands = []
+
+        for handler_md in star_handlers_registry:
+            if not star_map[handler_md.handler_module_path].activated:
+                continue
+            for event_filter in handler_md.event_filters:
+                cmd_info = self._extract_command_info(event_filter, handler_md)
+                if not cmd_info:
+                    continue
+
+                cmd_name, description, cmd_filter_instance = cmd_info
+
+                # 创建动态回调
+                callback = self._create_dynamic_callback(cmd_name)
+
+                # 创建一个通用的参数选项来接收所有文本输入
+                options = [
+                    discord.Option(
+                        name="params",
+                        description="指令的所有参数",
+                        type=discord.SlashCommandOptionType.string,
+                        required=False,
+                    )
+                ]
+
+                # 创建SlashCommand
+                slash_command = discord.SlashCommand(
+                    name=cmd_name,
+                    description=description,
+                    func=callback,
+                    options=options,
+                    guild_ids=[self.guild_id] if self.guild_id else None,
+                )
+                self.client.add_application_command(slash_command)
+                registered_commands.append(cmd_name)
+
+        if registered_commands:
+            logger.info(
+                f"[Discord] 准备同步 {len(registered_commands)} 个指令: {', '.join(registered_commands)}"
+            )
+        else:
+            logger.info("[Discord] 没有发现可注册的指令。")
+
+        # 使用 Pycord 的方法同步指令
+        # 注意：这可能需要一些时间，并且有频率限制
+        await self.client.sync_commands()
+        logger.info("[Discord] 指令同步完成。")
+
+    def _create_dynamic_callback(self, cmd_name: str):
+        """为每个指令动态创建一个异步回调函数"""
+
+        async def dynamic_callback(ctx: discord.ApplicationContext, params: str = None):
+            # 将平台特定的前缀'/'剥离，以适配通用的CommandFilter
+            logger.debug(f"[Discord] 回调函数触发: {cmd_name}")
+            logger.debug(f"[Discord] 回调函数参数: {ctx}")
+            logger.debug(f"[Discord] 回调函数参数: {params}")
+            message_str_for_filter = cmd_name
+            if params:
+                message_str_for_filter += f" {params}"
+
+            logger.debug(
+                f"[Discord] 斜杠指令 '{cmd_name}' 被触发。 "
+                f"原始参数: '{params}'. "
+                f"构建的指令字符串: '{message_str_for_filter}'"
+            )
+
+            # 尝试立即响应，防止超时
+            followup_webhook = None
+            try:
+                await ctx.defer()
+                followup_webhook = ctx.followup
+            except Exception as e:
+                logger.warning(f"[Discord] 指令 '{cmd_name}' defer 失败: {e}")
+
+            # 2. 构建 AstrBotMessage
+            abm = AstrBotMessage()
+            abm.type = self._get_message_type(ctx.channel, ctx.guild_id)
+            abm.group_id = self._get_channel_id(ctx.channel)
+            abm.message_str = message_str_for_filter
+            abm.sender = MessageMember(
+                user_id=str(ctx.author.id), nickname=ctx.author.display_name
+            )
+            abm.message = [Plain(text=message_str_for_filter)]
+            abm.raw_message = ctx.interaction
+            abm.self_id = self.client_self_id
+            abm.session_id = str(ctx.channel_id)
+            abm.message_id = str(ctx.interaction.id)
+
+            # 3. 将消息和 webhook 分别交给 handle_msg 处理
+            await self.handle_msg(abm, followup_webhook)
+
+        return dynamic_callback
+
+    @staticmethod
+    def _extract_command_info(
+        event_filter: Any, handler_metadata: StarHandlerMetadata
+    ) -> Tuple[str, str, CommandFilter] | None:
+        """从事件过滤器中提取指令信息"""
+        cmd_name = None
+        # is_group = False
+        cmd_filter_instance = None
+
+        if isinstance(event_filter, CommandFilter):
+            # 暂不支持子指令注册为斜杠指令
+            if (
+                event_filter.parent_command_names
+                and event_filter.parent_command_names != [""]
+            ):
+                return None
+            cmd_name = event_filter.command_name
+            cmd_filter_instance = event_filter
+
+        elif isinstance(event_filter, CommandGroupFilter):
+            # 暂不支持指令组直接注册为斜杠指令，因为它们没有 handle 方法
+            return None
+
+        if not cmd_name:
+            return None
+
+        # Discord 斜杠指令名称规范
+        if not re.match(r"^[a-z0-9_-]{1,32}$", cmd_name):
+            logger.debug(f"[Discord] 跳过不符合规范的指令: {cmd_name}")
+            return None
+
+        description = handler_metadata.desc or f"指令: {cmd_name}"
+        if len(description) > 100:
+            description = f"{description[:97]}..."
+
+        return cmd_name, description, cmd_filter_instance

astrbot/core/platform/sources/discord/discord_platform_event.py

@@ -0,0 +1,296 @@
+import asyncio
+import discord
+import base64
+from io import BytesIO
+from pathlib import Path
+from typing import Optional
+import sys
+
+from astrbot.api.event import AstrMessageEvent, MessageChain
+from astrbot.api.platform import AstrBotMessage, PlatformMetadata, At
+from astrbot.api.message_components import (
+    Plain,
+    Image,
+    File,
+    BaseMessageComponent,
+    Reply,
+)
+from astrbot import logger
+from .client import DiscordBotClient
+from .components import DiscordEmbed, DiscordView
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+
+# 自定义Discord视图组件（兼容旧版本）
+class DiscordViewComponent(BaseMessageComponent):
+    type: str = "discord_view"
+
+    def __init__(self, view: discord.ui.View):
+        self.view = view
+
+
+class DiscordPlatformEvent(AstrMessageEvent):
+    def __init__(
+        self,
+        message_str: str,
+        message_obj: AstrBotMessage,
+        platform_meta: PlatformMetadata,
+        session_id: str,
+        client: DiscordBotClient,
+        interaction_followup_webhook: Optional[discord.Webhook] = None,
+    ):
+        super().__init__(message_str, message_obj, platform_meta, session_id)
+        self.client = client
+        self.interaction_followup_webhook = interaction_followup_webhook
+
+    @override
+    async def send(self, message: MessageChain):
+        """发送消息到Discord平台"""
+
+        # 解析消息链为 Discord 所需的对象
+        try:
+            (
+                content,
+                files,
+                view,
+                embeds,
+                reference_message_id,
+            ) = await self._parse_to_discord(message)
+        except Exception as e:
+            logger.error(f"[Discord] 解析消息链时失败: {e}", exc_info=True)
+            return
+
+        kwargs = {}
+        if content:
+            kwargs["content"] = content
+        if files:
+            kwargs["files"] = files
+        if view:
+            kwargs["view"] = view
+        if embeds:
+            kwargs["embeds"] = embeds
+        if reference_message_id and not self.interaction_followup_webhook:
+            kwargs["reference"] = self.client.get_message(int(reference_message_id))
+        if not kwargs:
+            logger.debug("[Discord] 尝试发送空消息，已忽略。")
+            return
+
+        # 根据上下文执行发送/回复操作
+        try:
+            # -- 斜杠指令/交互上下文 --
+            if self.interaction_followup_webhook:
+                await self.interaction_followup_webhook.send(**kwargs)
+
+            # -- 常规消息上下文 --
+            else:
+                channel = await self._get_channel()
+                if not channel:
+                    return
+                else:
+                    await channel.send(**kwargs)
+
+        except Exception as e:
+            logger.error(f"[Discord] 发送消息时发生未知错误: {e}", exc_info=True)
+
+        await super().send(message)
+
+    async def _get_channel(self) -> Optional[discord.abc.Messageable]:
+        """获取当前事件对应的频道对象"""
+        try:
+            channel_id = int(self.session_id)
+            return self.client.get_channel(
+                channel_id
+            ) or await self.client.fetch_channel(channel_id)
+        except (ValueError, discord.errors.NotFound, discord.errors.Forbidden):
+            logger.error(f"[Discord] 无法获取频道 {self.session_id}")
+            return None
+
+    async def _parse_to_discord(
+        self,
+        message: MessageChain,
+    ) -> tuple[str, list[discord.File], Optional[discord.ui.View], list[discord.Embed]]:
+        """将 MessageChain 解析为 Discord 发送所需的内容"""
+        content = ""
+        files = []
+        view = None
+        embeds = []
+        reference_message_id = None
+        for i in message.chain:  # 遍历消息链
+            if isinstance(i, Plain):  # 如果是文字类型的
+                content += i.text
+            elif isinstance(i, Reply):
+                reference_message_id = i.id
+            elif isinstance(i, At):
+                content += f"<@{i.qq}>"
+            elif isinstance(i, Image):
+                logger.debug(f"[Discord] 开始处理 Image 组件: {i}")
+                try:
+                    filename = getattr(i, "filename", None)
+                    file_content = getattr(i, "file", None)
+
+                    if not file_content:
+                        logger.warning(f"[Discord] Image 组件没有 file 属性: {i}")
+                        continue
+
+                    discord_file = None
+
+                    # 1. URL
+                    if file_content.startswith("http"):
+                        logger.debug(f"[Discord] 处理 URL 图片: {file_content}")
+                        embed = discord.Embed().set_image(url=file_content)
+                        embeds.append(embed)
+                        continue
+
+                    # 2. File URI
+                    elif file_content.startswith("file:///"):
+                        logger.debug(f"[Discord] 处理 File URI: {file_content}")
+                        path = Path(file_content[8:])
+                        if await asyncio.to_thread(path.exists):
+                            file_bytes = await asyncio.to_thread(path.read_bytes)
+                            discord_file = discord.File(
+                                BytesIO(file_bytes), filename=filename or path.name
+                            )
+                        else:
+                            logger.warning(f"[Discord] 图片文件不存在: {path}")
+
+                    # 3. Base64 URI
+                    elif file_content.startswith("base64://"):
+                        logger.debug("[Discord] 处理 Base64 URI")
+                        b64_data = file_content.split("base64://", 1)[1]
+                        missing_padding = len(b64_data) % 4
+                        if missing_padding:
+                            b64_data += "=" * (4 - missing_padding)
+                        img_bytes = base64.b64decode(b64_data)
+                        discord_file = discord.File(
+                            BytesIO(img_bytes), filename=filename or "image.png"
+                        )
+
+                    # 4. 裸 Base64 或本地路径
+                    else:
+                        try:
+                            logger.debug("[Discord] 尝试作为裸 Base64 处理")
+                            b64_data = file_content
+                            missing_padding = len(b64_data) % 4
+                            if missing_padding:
+                                b64_data += "=" * (4 - missing_padding)
+                            img_bytes = base64.b64decode(b64_data)
+                            discord_file = discord.File(
+                                BytesIO(img_bytes), filename=filename or "image.png"
+                            )
+                        except (ValueError, TypeError, base64.binascii.Error):
+                            logger.debug(
+                                f"[Discord] 裸 Base64 解码失败，作为本地路径处理: {file_content}"
+                            )
+                            path = Path(file_content)
+                            if await asyncio.to_thread(path.exists):
+                                file_bytes = await asyncio.to_thread(path.read_bytes)
+                                discord_file = discord.File(
+                                    BytesIO(file_bytes), filename=filename or path.name
+                                )
+                            else:
+                                logger.warning(f"[Discord] 图片文件不存在: {path}")
+
+                    if discord_file:
+                        files.append(discord_file)
+
+                except Exception:
+                    # 使用 getattr 来安全地访问 i.file，以防 i 本身就是问题
+                    file_info = getattr(i, "file", "未知")
+                    logger.error(
+                        f"[Discord] 处理图片时发生未知严重错误: {file_info}",
+                        exc_info=True,
+                    )
+            elif isinstance(i, File):
+                try:
+                    file_path_str = await i.get_file()
+                    if file_path_str:
+                        path = Path(file_path_str)
+                        if await asyncio.to_thread(path.exists):
+                            file_bytes = await asyncio.to_thread(path.read_bytes)
+                            files.append(
+                                discord.File(BytesIO(file_bytes), filename=i.name)
+                            )
+                        else:
+                            logger.warning(
+                                f"[Discord] 获取文件失败，路径不存在: {file_path_str}"
+                            )
+                    else:
+                        logger.warning(f"[Discord] 获取文件失败: {i.name}")
+                except Exception as e:
+                    logger.warning(f"[Discord] 处理文件失败: {i.name}, 错误: {e}")
+            elif isinstance(i, DiscordEmbed):
+                # Discord Embed消息
+                embeds.append(i.to_discord_embed())
+            elif isinstance(i, DiscordView):
+                # Discord视图组件（按钮、选择菜单等）
+                view = i.to_discord_view()
+            elif isinstance(i, DiscordViewComponent):
+                # 如果消息链中包含Discord视图组件（兼容旧版本）
+                if isinstance(i.view, discord.ui.View):
+                    view = i.view
+            else:
+                logger.debug(f"[Discord] 忽略了不支持的消息组件: {i.type}")
+
+        if len(content) > 2000:
+            logger.warning("[Discord] 消息内容超过2000字符，将被截断。")
+            content = content[:2000]
+        return content, files, view, embeds, reference_message_id
+
+    async def react(self, emoji: str):
+        """对原消息添加反应"""
+        try:
+            if hasattr(self.message_obj, "raw_message") and hasattr(
+                self.message_obj.raw_message, "add_reaction"
+            ):
+                await self.message_obj.raw_message.add_reaction(emoji)
+        except Exception as e:
+            logger.error(f"[Discord] 添加反应失败: {e}")
+
+    def is_slash_command(self) -> bool:
+        """判断是否为斜杠命令"""
+        return (
+            hasattr(self.message_obj, "raw_message")
+            and hasattr(self.message_obj.raw_message, "type")
+            and self.message_obj.raw_message.type
+            == discord.InteractionType.application_command
+        )
+
+    def is_button_interaction(self) -> bool:
+        """判断是否为按钮交互"""
+        return (
+            hasattr(self.message_obj, "raw_message")
+            and hasattr(self.message_obj.raw_message, "type")
+            and self.message_obj.raw_message.type == discord.InteractionType.component
+        )
+
+    def get_interaction_custom_id(self) -> str:
+        """获取交互组件的custom_id"""
+        if self.is_button_interaction():
+            try:
+                return self.message_obj.raw_message.data.get("custom_id", "")
+            except Exception:
+                pass
+        return ""
+
+    def is_mentioned(self) -> bool:
+        """判断机器人是否被@"""
+        if hasattr(self.message_obj, "raw_message") and hasattr(
+            self.message_obj.raw_message, "mentions"
+        ):
+            return any(
+                mention.id == int(self.message_obj.self_id)
+                for mention in self.message_obj.raw_message.mentions
+            )
+        return False
+
+    def get_mention_clean_content(self) -> str:
+        """获取去除@后的清洁内容"""
+        if hasattr(self.message_obj, "raw_message") and hasattr(
+            self.message_obj.raw_message, "clean_content"
+        ):
+            return self.message_obj.raw_message.clean_content
+        return self.message_str

astrbot/core/platform/sources/gewechat/client.py

@@ -1,467 +0,0 @@
-import threading
-import asyncio
-import aiohttp
-import quart
-import base64
-import datetime
-import re
-import os
-import anyio
-from astrbot.api.platform import AstrBotMessage, MessageMember, MessageType
-from astrbot.api.message_components import Plain, Image, At, Record
-from astrbot.api import logger, sp
-from .downloader import GeweDownloader
-from astrbot.core.utils.io import download_image_by_url
-
-
-class SimpleGewechatClient:
-    """针对 Gewechat 的简单实现。
-
-    @author: Soulter
-    @website: https://github.com/Soulter
-    """
-
-    def __init__(
-        self,
-        base_url: str,
-        nickname: str,
-        host: str,
-        port: int,
-        event_queue: asyncio.Queue,
-    ):
-        self.base_url = base_url
-        if self.base_url.endswith("/"):
-            self.base_url = self.base_url[:-1]
-
-        self.download_base_url = self.base_url.split(":")[:-1]  # 去掉端口
-        self.download_base_url = ":".join(self.download_base_url) + ":2532/download/"
-
-        self.base_url += "/v2/api"
-
-        logger.info(f"Gewechat API: {self.base_url}")
-        logger.info(f"Gewechat 下载 API: {self.download_base_url}")
-
-        if isinstance(port, str):
-            port = int(port)
-
-        self.token = None
-        self.headers = {}
-        self.nickname = nickname
-        self.appid = sp.get(f"gewechat-appid-{nickname}", "")
-
-        self.server = quart.Quart(__name__)
-        self.server.add_url_rule(
-            "/astrbot-gewechat/callback", view_func=self.callback, methods=["POST"]
-        )
-        self.server.add_url_rule(
-            "/astrbot-gewechat/file/<file_id>",
-            view_func=self.handle_file,
-            methods=["GET"],
-        )
-
-        self.host = host
-        self.port = port
-        self.callback_url = f"http://{self.host}:{self.port}/astrbot-gewechat/callback"
-        self.file_server_url = f"http://{self.host}:{self.port}/astrbot-gewechat/file"
-
-        self.event_queue = event_queue
-
-        self.multimedia_downloader = None
-
-        self.userrealnames = {}
-
-        self.stop = False
-
-    async def get_token_id(self):
-        async with aiohttp.ClientSession() as session:
-            async with session.post(f"{self.base_url}/tools/getTokenId") as resp:
-                json_blob = await resp.json()
-                self.token = json_blob["data"]
-                logger.info(f"获取到 Gewechat Token: {self.token}")
-                self.headers = {"X-GEWE-TOKEN": self.token}
-
-    async def _convert(self, data: dict) -> AstrBotMessage:
-        if "TypeName" in data:
-            type_name = data["TypeName"]
-        elif "type_name" in data:
-            type_name = data["type_name"]
-        else:
-            raise Exception("无法识别的消息类型")
-        if type_name == "Offline":
-            logger.critical("收到 gewechat 下线通知。")
-            return
-
-        d = None
-        if "Data" in data:
-            d = data["Data"]
-        elif "data" in data:
-            d = data["data"]
-
-        if not d:
-            logger.warning(f"消息不含 data 字段: {data}")
-            return
-
-        if "CreateTime" in d:
-            # 得到系统 UTF+8 的 ts
-            tz_offset = datetime.timedelta(hours=8)
-            tz = datetime.timezone(tz_offset)
-            ts = datetime.datetime.now(tz).timestamp()
-            create_time = d["CreateTime"]
-            if create_time < ts - 30:
-                logger.warning(f"消息时间戳过旧: {create_time}，当前时间戳: {ts}")
-                return
-
-        abm = AstrBotMessage()
-
-        from_user_name = d["FromUserName"]["string"]  # 消息来源
-        d["to_wxid"] = from_user_name  # 用于发信息
-
-        abm.message_id = str(d.get("MsgId"))
-        abm.session_id = from_user_name
-        abm.self_id = data["Wxid"]  # 机器人的 wxid
-
-        user_id = ""  # 发送人 wxid
-        content = d["Content"]["string"]  # 消息内容
-
-        at_me = False
-        if "@chatroom" in from_user_name:
-            abm.type = MessageType.GROUP_MESSAGE
-            _t = content.split(":\n")
-            user_id = _t[0]
-            content = _t[1]
-            if "\u2005" in content:
-                # at
-                # content = content.split('\u2005')[1]
-                content = re.sub(r"@[^\u2005]*\u2005", "", content)
-            abm.group_id = from_user_name
-            # at
-            msg_source = d["MsgSource"]
-            if (
-                f"<atuserlist><![CDATA[,{abm.self_id}]]>" in msg_source
-                or f"<atuserlist><![CDATA[{abm.self_id}]]>" in msg_source
-            ):
-                at_me = True
-            if "在群聊中@了你" in d.get("PushContent", ""):
-                at_me = True
-        else:
-            abm.type = MessageType.FRIEND_MESSAGE
-            user_id = from_user_name
-
-        abm.message = []
-        if at_me:
-            abm.message.insert(0, At(qq=abm.self_id))
-
-        # 解析用户真实名字
-        user_real_name = "unknown"
-        if abm.group_id:
-            if (
-                abm.group_id not in self.userrealnames
-                or user_id not in self.userrealnames[abm.group_id]
-            ):
-                # 获取群成员列表，并且缓存
-                if abm.group_id not in self.userrealnames:
-                    self.userrealnames[abm.group_id] = {}
-                member_list = await self.get_chatroom_member_list(abm.group_id)
-                logger.debug(f"获取到 {abm.group_id} 的群成员列表。")
-                if member_list and "memberList" in member_list:
-                    for member in member_list["memberList"]:
-                        self.userrealnames[abm.group_id][member["wxid"]] = member[
-                            "nickName"
-                        ]
-                if user_id in self.userrealnames[abm.group_id]:
-                    user_real_name = self.userrealnames[abm.group_id][user_id]
-            else:
-                user_real_name = self.userrealnames[abm.group_id][user_id]
-        else:
-            user_real_name = d.get("PushContent", "unknown : ").split(" : ")[0]
-
-        abm.sender = MessageMember(user_id, user_real_name)
-        abm.raw_message = d
-        abm.message_str = ""
-        # 不同消息类型
-        match d["MsgType"]:
-            case 1:
-                # 文本消息
-                abm.message.append(Plain(content))
-                abm.message_str = content
-            case 3:
-                # 图片消息
-                file_url = await self.multimedia_downloader.download_image(
-                    self.appid, content
-                )
-                logger.debug(f"下载图片: {file_url}")
-                file_path = await download_image_by_url(file_url)
-                abm.message.append(Image(file=file_path, url=file_path))
-
-            case 34:
-                # 语音消息
-                # data = await self.multimedia_downloader.download_voice(
-                #     self.appid,
-                #     content,
-                #     abm.message_id
-                # )
-                # print(data)
-                if "ImgBuf" in d and "buffer" in d["ImgBuf"]:
-                    voice_data = base64.b64decode(d["ImgBuf"]["buffer"])
-                    file_path = f"data/temp/gewe_voice_{abm.message_id}.silk"
-                    async with await anyio.open_file(file_path, "wb") as f:
-                        await f.write(voice_data)
-                    abm.message.append(Record(file=file_path, url=file_path))
-            case _:
-                logger.info(f"未实现的消息类型: {d['MsgType']}")
-                abm.raw_message = d
-
-        logger.debug(f"abm: {abm}")
-        return abm
-
-    async def callback(self):
-        data = await quart.request.json
-        logger.debug(f"收到 gewechat 回调: {data}")
-
-        if data.get("testMsg", None):
-            return quart.jsonify({"r": "AstrBot ACK"})
-
-        abm = None
-        try:
-            abm = await self._convert(data)
-        except BaseException as e:
-            logger.warning(
-                f"尝试解析 GeweChat 下发的消息时遇到问题: {e}。下发消息内容: {data}。"
-            )
-
-        if abm:
-            coro = getattr(self, "on_event_received")
-            if coro:
-                await coro(abm)
-
-        return quart.jsonify({"r": "AstrBot ACK"})
-
-    async def handle_file(self, file_id):
-        file_path = f"data/temp/{file_id}"
-        return await quart.send_file(file_path)
-
-    async def _set_callback_url(self):
-        logger.info("设置回调，请等待...")
-        await asyncio.sleep(3)
-        async with aiohttp.ClientSession() as session:
-            async with session.post(
-                f"{self.base_url}/tools/setCallback",
-                headers=self.headers,
-                json={"token": self.token, "callbackUrl": self.callback_url},
-            ) as resp:
-                json_blob = await resp.json()
-                logger.info(f"设置回调结果: {json_blob}")
-                if json_blob["ret"] != 200:
-                    raise Exception(f"设置回调失败: {json_blob}")
-                logger.info(
-                    f"将在 {self.callback_url} 上接收 gewechat 下发的消息。如果一直没收到消息请先尝试重启 AstrBot。如果仍没收到请到管理面板聊天页输入 /gewe_logout 重新登录。"
-                )
-
-    async def start_polling(self):
-        threading.Thread(target=asyncio.run, args=(self._set_callback_url(),)).start()
-        await self.server.run_task(
-            host="0.0.0.0",
-            port=self.port,
-            shutdown_trigger=self.shutdown_trigger_placeholder,
-        )
-
-    async def shutdown_trigger_placeholder(self):
-        # TODO: use asyncio.Event
-        while not self.event_queue.closed and not self.stop:  # noqa: ASYNC110
-            await asyncio.sleep(1)
-        logger.info("gewechat 适配器已关闭。")
-
-    async def check_online(self, appid: str):
-        # /login/checkOnline
-        async with aiohttp.ClientSession() as session:
-            async with session.post(
-                f"{self.base_url}/login/checkOnline",
-                headers=self.headers,
-                json={"appId": appid},
-            ) as resp:
-                json_blob = await resp.json()
-                return json_blob["data"]
-
-    async def logout(self):
-        if self.appid:
-            online = await self.check_online(self.appid)
-            if online:
-                async with aiohttp.ClientSession() as session:
-                    async with session.post(
-                        f"{self.base_url}/login/logout",
-                        headers=self.headers,
-                        json={"appId": self.appid},
-                    ) as resp:
-                        json_blob = await resp.json()
-                        logger.info(f"登出结果: {json_blob}")
-
-    async def login(self):
-        if self.token is None:
-            await self.get_token_id()
-
-        self.multimedia_downloader = GeweDownloader(
-            self.base_url, self.download_base_url, self.token
-        )
-
-        if self.appid:
-            online = await self.check_online(self.appid)
-            if online:
-                logger.info(f"APPID: {self.appid} 已在线")
-                return
-
-        payload = {"appId": self.appid}
-
-        if self.appid:
-            logger.info(f"使用 APPID: {self.appid}, {self.nickname}")
-
-        async with aiohttp.ClientSession() as session:
-            async with session.post(
-                f"{self.base_url}/login/getLoginQrCode",
-                headers=self.headers,
-                json=payload,
-            ) as resp:
-                json_blob = await resp.json()
-                if json_blob["ret"] != 200:
-                    raise Exception(f"获取二维码失败: {json_blob}")
-                qr_data = json_blob["data"]["qrData"]
-                qr_uuid = json_blob["data"]["uuid"]
-                appid = json_blob["data"]["appId"]
-                logger.info(f"APPID: {appid}")
-                logger.warning(
-                    f"请打开该网址，然后使用微信扫描二维码登录: https://api.cl2wm.cn/api/qrcode/code?text={qr_data}"
-                )
-
-        # 执行登录
-        retry_cnt = 64
-        payload.update({"uuid": qr_uuid, "appId": appid})
-        while retry_cnt > 0:
-            retry_cnt -= 1
-
-            # 需要验证码
-            if os.path.exists("data/temp/gewe_code"):
-                with open("data/temp/gewe_code", "r") as f:
-                    code = f.read().strip()
-                    if not code:
-                        logger.warning(
-                            "未找到验证码，请在管理面板聊天页输入 /gewe_code 验证码 来验证，如 /gewe_code 123456"
-                        )
-                        await asyncio.sleep(5)
-                        continue
-                    payload["captchCode"] = code
-                    logger.info(f"使用验证码: {code}")
-                    try:
-                        os.remove("data/temp/gewe_code")
-                    except Exception:
-                        logger.warning("删除验证码文件 data/temp/gewe_code 失败。")
-
-            async with aiohttp.ClientSession() as session:
-                async with session.post(
-                    f"{self.base_url}/login/checkLogin",
-                    headers=self.headers,
-                    json=payload,
-                ) as resp:
-                    json_blob = await resp.json()
-                    logger.info(f"检查登录状态: {json_blob}")
-
-                    ret = json_blob["ret"]
-                    msg = ""
-                    if json_blob["data"] and "msg" in json_blob["data"]:
-                        msg = json_blob["data"]["msg"]
-                    if ret == 500 and "安全验证码" in msg:
-                        logger.warning(
-                            "此次登录需要安全验证码，请在管理面板聊天页输入 /gewe_code 验证码 来验证，如 /gewe_code 123456"
-                        )
-                    else:
-                        status = json_blob["data"]["status"]
-                        nickname = json_blob["data"].get("nickName", "")
-                        if status == 1:
-                            logger.info(f"等待确认...{nickname}")
-                        elif status == 2:
-                            logger.info(f"绿泡泡平台登录成功: {nickname}")
-                            break
-                        elif status == 0:
-                            logger.info("等待扫码...")
-                        else:
-                            logger.warning(f"未知状态: {status}")
-            await asyncio.sleep(5)
-
-        if appid:
-            sp.put(f"gewechat-appid-{self.nickname}", appid)
-            self.appid = appid
-            logger.info(f"已保存 APPID: {appid}")
-
-    """API"""
-
-    async def get_chatroom_member_list(self, chatroom_wxid: str):
-        payload = {"appId": self.appid, "chatroomId": chatroom_wxid}
-
-        async with aiohttp.ClientSession() as session:
-            async with session.post(
-                f"{self.base_url}/group/getChatroomMemberList",
-                headers=self.headers,
-                json=payload,
-            ) as resp:
-                json_blob = await resp.json()
-                return json_blob["data"]
-
-    async def post_text(self, to_wxid, content: str, ats: str = ""):
-        payload = {
-            "appId": self.appid,
-            "toWxid": to_wxid,
-            "content": content,
-        }
-        if ats:
-            payload["ats"] = ats
-
-        async with aiohttp.ClientSession() as session:
-            async with session.post(
-                f"{self.base_url}/message/postText", headers=self.headers, json=payload
-            ) as resp:
-                json_blob = await resp.json()
-                logger.debug(f"发送消息结果: {json_blob}")
-
-    async def post_image(self, to_wxid, image_url: str):
-        payload = {
-            "appId": self.appid,
-            "toWxid": to_wxid,
-            "imgUrl": image_url,
-        }
-
-        async with aiohttp.ClientSession() as session:
-            async with session.post(
-                f"{self.base_url}/message/postImage", headers=self.headers, json=payload
-            ) as resp:
-                json_blob = await resp.json()
-                logger.debug(f"发送图片结果: {json_blob}")
-
-    async def post_voice(self, to_wxid, voice_url: str, voice_duration: int):
-        payload = {
-            "appId": self.appid,
-            "toWxid": to_wxid,
-            "voiceUrl": voice_url,
-            "voiceDuration": voice_duration,
-        }
-
-        logger.debug(f"发送语音: {payload}")
-
-        async with aiohttp.ClientSession() as session:
-            async with session.post(
-                f"{self.base_url}/message/postVoice", headers=self.headers, json=payload
-            ) as resp:
-                json_blob = await resp.json()
-                logger.debug(f"发送语音结果: {json_blob}")
-
-    async def post_file(self, to_wxid, file_url: str, file_name: str):
-        payload = {
-            "appId": self.appid,
-            "toWxid": to_wxid,
-            "fileUrl": file_url,
-            "fileName": file_name,
-        }
-
-        async with aiohttp.ClientSession() as session:
-            async with session.post(
-                f"{self.base_url}/message/postFile", headers=self.headers, json=payload
-            ) as resp:
-                json_blob = await resp.json()
-                logger.debug(f"发送文件结果: {json_blob}")

astrbot/core/platform/sources/gewechat/downloader.py

@@ -1,41 +0,0 @@
-from astrbot import logger
-import aiohttp
-import json
-
-
-class GeweDownloader:
-    def __init__(self, base_url: str, download_base_url: str, token: str):
-        self.base_url = base_url
-        self.download_base_url = download_base_url
-        self.headers = {"Content-Type": "application/json", "X-GEWE-TOKEN": token}
-
-    async def _post_json(self, baseurl: str, route: str, payload: dict):
-        async with aiohttp.ClientSession() as session:
-            async with session.post(
-                f"{baseurl}{route}", headers=self.headers, json=payload
-            ) as resp:
-                return await resp.read()
-
-    async def download_voice(self, appid: str, xml: str, msg_id: str):
-        payload = {"appId": appid, "xml": xml, "msgId": msg_id}
-        return await self._post_json(self.base_url, "/message/downloadVoice", payload)
-
-    async def download_image(self, appid: str, xml: str) -> str:
-        """返回一个可下载的 URL"""
-        choices = [2, 3]  #  2:常规图片 3:缩略图
-
-        for choice in choices:
-            try:
-                payload = {"appId": appid, "xml": xml, "type": choice}
-                data = await self._post_json(
-                    self.base_url, "/message/downloadImage", payload
-                )
-                json_blob = json.loads(data)
-                if "fileUrl" in json_blob["data"]:
-                    return self.download_base_url + json_blob["data"]["fileUrl"]
-
-            except BaseException as e:
-                logger.error(f"gewe download image: {e}")
-                continue
-
-        raise Exception("无法下载图片")

astrbot/core/platform/sources/gewechat/gewechat_event.py

@@ -1,140 +0,0 @@
-import wave
-import uuid
-import traceback
-import os
-from astrbot.core.utils.io import save_temp_img, download_image_by_url, download_file
-from astrbot.core.utils.tencent_record_helper import wav_to_tencent_silk
-from astrbot.api import logger
-from astrbot.api.event import AstrMessageEvent, MessageChain
-from astrbot.api.platform import AstrBotMessage, PlatformMetadata
-from astrbot.api.message_components import Plain, Image, Record, At, File
-from .client import SimpleGewechatClient
-
-
-def get_wav_duration(file_path):
-    with wave.open(file_path, "rb") as wav_file:
-        file_size = os.path.getsize(file_path)
-        n_channels, sampwidth, framerate, n_frames = wav_file.getparams()[:4]
-        if n_frames == 2147483647:
-            duration = (file_size - 44) / (n_channels * sampwidth * framerate)
-        elif n_frames == 0:
-            duration = (file_size - 44) / (n_channels * sampwidth * framerate)
-        else:
-            duration = n_frames / float(framerate)
-        return duration
-
-
-class GewechatPlatformEvent(AstrMessageEvent):
-    def __init__(
-        self,
-        message_str: str,
-        message_obj: AstrBotMessage,
-        platform_meta: PlatformMetadata,
-        session_id: str,
-        client: SimpleGewechatClient,
-    ):
-        super().__init__(message_str, message_obj, platform_meta, session_id)
-        self.client = client
-
-    @staticmethod
-    async def send_with_client(
-        message: MessageChain, to_wxid: str, client: SimpleGewechatClient
-    ):
-        if not to_wxid:
-            logger.error("无法获取到 to_wxid。")
-            return
-
-        #  检查@
-        ats = []
-        ats_names = []
-        for comp in message.chain:
-            if isinstance(comp, At):
-                ats.append(comp.qq)
-                ats_names.append(comp.name)
-        has_at = False
-
-        for comp in message.chain:
-            if isinstance(comp, Plain):
-                text = comp.text
-                payload = {
-                    "to_wxid": to_wxid,
-                    "content": text,
-                }
-                if not has_at and ats:
-                    ats = f"{','.join(ats)}"
-                    ats_names = f"@{' @'.join(ats_names)}"
-                    text = f"{ats_names} {text}"
-                    payload["content"] = text
-                    payload["ats"] = ats
-                    has_at = True
-                await client.post_text(**payload)
-
-            elif isinstance(comp, Image):
-                img_url = comp.file
-                img_path = ""
-                if img_url.startswith("file:///"):
-                    img_path = img_url[8:]
-                elif comp.file and comp.file.startswith("http"):
-                    img_path = await download_image_by_url(comp.file)
-                else:
-                    img_path = img_url
-
-                # 检查 record_path 是否在 data/temp 目录中, record_path 可能是绝对路径
-                temp_directory = os.path.abspath("data/temp")
-                img_path = os.path.abspath(img_path)
-                if os.path.commonpath([temp_directory, img_path]) != temp_directory:
-                    with open(img_path, "rb") as f:
-                        img_path = save_temp_img(f.read())
-
-                file_id = os.path.basename(img_path)
-                img_url = f"{client.file_server_url}/{file_id}"
-                logger.debug(f"gewe callback img url: {img_url}")
-                await client.post_image(to_wxid, img_url)
-            elif isinstance(comp, Record):
-                # 默认已经存在 data/temp 中
-                record_url = comp.file
-                record_path = ""
-
-                if record_url.startswith("file:///"):
-                    record_path = record_url[8:]
-                elif record_url.startswith("http"):
-                    await download_file(record_url, f"data/temp/{uuid.uuid4()}.wav")
-                else:
-                    record_path = record_url
-
-                silk_path = f"data/temp/{uuid.uuid4()}.silk"
-                try:
-                    duration = await wav_to_tencent_silk(record_path, silk_path)
-                except Exception as e:
-                    logger.error(traceback.format_exc())
-                    await client.post_text(to_wxid, f"语音文件转换失败。{str(e)}")
-                logger.info("Silk 语音文件格式转换至: " + record_path)
-                if duration == 0:
-                    duration = get_wav_duration(record_path)
-                file_id = os.path.basename(silk_path)
-                record_url = f"{client.file_server_url}/{file_id}"
-                logger.debug(f"gewe callback record url: {record_url}")
-                await client.post_voice(to_wxid, record_url, duration * 1000)
-            elif isinstance(comp, File):
-                file_path = comp.file
-                file_name = comp.name
-                if file_path.startswith("file:///"):
-                    file_path = file_path[8:]
-                elif file_path.startswith("http"):
-                    await download_file(file_path, f"data/temp/{file_name}")
-                else:
-                    file_path = file_path
-
-                file_id = os.path.basename(file_path)
-                file_url = f"{client.file_server_url}/{file_id}"
-                logger.debug(f"gewe callback file url: {file_url}")
-                await client.post_file(to_wxid, file_url, file_id)
-            elif isinstance(comp, At):
-                pass
-            else:
-                logger.debug(f"gewechat 忽略: {comp.type}")
-
-    async def send(self, message: MessageChain):
-        to_wxid = self.message_obj.raw_message.get("to_wxid", None)
-        await GewechatPlatformEvent.send_with_client(message, to_wxid, self.client)
-        await super().send(message)

astrbot/core/platform/sources/gewechat/gewechat_platform_adapter.py

@@ -1,97 +0,0 @@
-import sys
-import asyncio
-import os
-
-from astrbot.api.platform import Platform, AstrBotMessage, MessageType, PlatformMetadata
-from astrbot.api.event import MessageChain
-from astrbot.core.platform.astr_message_event import MessageSesion
-from ...register import register_platform_adapter
-from .gewechat_event import GewechatPlatformEvent
-from .client import SimpleGewechatClient
-
-if sys.version_info >= (3, 12):
-    from typing import override
-else:
-    from typing_extensions import override
-
-
-@register_platform_adapter("gewechat", "基于 gewechat 的 Wechat 适配器")
-class GewechatPlatformAdapter(Platform):
-    def __init__(
-        self, platform_config: dict, platform_settings: dict, event_queue: asyncio.Queue
-    ) -> None:
-        super().__init__(event_queue)
-        self.config = platform_config
-        self.settingss = platform_settings
-        self.test_mode = os.environ.get("TEST_MODE", "off") == "on"
-        self.client = None
-
-        self.client = SimpleGewechatClient(
-            self.config["base_url"],
-            self.config["nickname"],
-            self.config["host"],
-            self.config["port"],
-            self._event_queue,
-        )
-
-        async def on_event_received(abm: AstrBotMessage):
-            await self.handle_msg(abm)
-
-        self.client.on_event_received = on_event_received
-
-    @override
-    async def send_by_session(
-        self, session: MessageSesion, message_chain: MessageChain
-    ):
-        session_id = session.session_id
-        if "#" in session_id:
-            # unique session
-            to_wxid = session_id.split("#")[1]
-        else:
-            to_wxid = session_id
-
-        await GewechatPlatformEvent.send_with_client(
-            message_chain, to_wxid, self.client
-        )
-
-        await super().send_by_session(session, message_chain)
-
-    @override
-    def meta(self) -> PlatformMetadata:
-        return PlatformMetadata(
-            "gewechat",
-            "基于 gewechat 的 Wechat 适配器",
-        )
-
-    async def terminate(self):
-        self.client.stop = True
-        await asyncio.sleep(1)
-
-    async def logout(self):
-        await self.client.logout()
-
-    @override
-    def run(self):
-        return self._run()
-
-    async def _run(self):
-        await self.client.login()
-        await self.client.start_polling()
-
-    async def handle_msg(self, message: AstrBotMessage):
-        if message.type == MessageType.GROUP_MESSAGE:
-            if self.settingss["unique_session"]:
-                message.session_id = message.sender.user_id + "#" + message.group_id
-
-        message_event = GewechatPlatformEvent(
-            message_str=message.message_str,
-            message_obj=message,
-            platform_meta=self.meta(),
-            session_id=message.session_id,
-            client=self.client,
-        )
-
-        self.commit_event(message_event)
-
-    def get_client(self) -> SimpleGewechatClient:
-        return self.client

astrbot/core/platform/sources/lark/lark_adapter.py

@@ -2,6 +2,8 @@ import base64
 import asyncio
 import json
 import re
+import uuid
+import astrbot.api.message_components as Comp
 
 from astrbot.api.platform import (
     Platform,
@@ -11,7 +13,6 @@ from astrbot.api.platform import (
     PlatformMetadata,
 )
 from astrbot.api.event import MessageChain
-from astrbot.api.message_components import Image, Plain, At
 from astrbot.core.platform.astr_message_event import MessageSesion
 from .lark_event import LarkMessageEvent
 from ...register import register_platform_adapter
@@ -66,12 +67,47 @@ class LarkPlatformAdapter(Platform):
     async def send_by_session(
         self, session: MessageSesion, message_chain: MessageChain
     ):
-        raise NotImplementedError("QQ 机器人官方 API 适配器不支持 send_by_session")
+        res = await LarkMessageEvent._convert_to_lark(message_chain, self.lark_api)
+        wrapped = {
+            "zh_cn": {
+                "title": "",
+                "content": res,
+            }
+        }
+
+        if session.message_type == MessageType.GROUP_MESSAGE:
+            id_type = "chat_id"
+            if "%" in session.session_id:
+                session.session_id = session.session_id.split("%")[1]
+        else:
+            id_type = "open_id"
+
+        request = (
+            CreateMessageRequest.builder()
+            .receive_id_type(id_type)
+            .request_body(
+                CreateMessageRequestBody.builder()
+                .receive_id(session.session_id)
+                .content(json.dumps(wrapped))
+                .msg_type("post")
+                .uuid(str(uuid.uuid4()))
+                .build()
+            )
+            .build()
+        )
+
+        response = await self.lark_api.im.v1.message.acreate(request)
+
+        if not response.success():
+            logger.error(f"发送飞书消息失败({response.code}): {response.msg}")
+
+        await super().send_by_session(session, message_chain)
 
     def meta(self) -> PlatformMetadata:
         return PlatformMetadata(
-            "lark",
-            "飞书机器人官方 API 适配器",
+            name="lark",
+            description="飞书机器人官方 API 适配器",
+            id=self.config.get("id"),
         )
 
     async def convert_msg(self, event: lark.im.v1.P2ImMessageReceiveV1):
@@ -92,7 +128,7 @@ class LarkPlatformAdapter(Platform):
         at_list = {}
         if message.mentions:
             for m in message.mentions:
-                at_list[m.key] = At(qq=m.id.open_id, name=m.name)
+                at_list[m.key] = Comp.At(qq=m.id.open_id, name=m.name)
                 if m.name == self.bot_name:
                     abm.self_id = m.id.open_id
 
@@ -111,7 +147,7 @@ class LarkPlatformAdapter(Platform):
                 if s in at_list:
                     abm.message.append(at_list[s])
                 else:
-                    abm.message.append(Plain(parts[i].strip()))
+                    abm.message.append(Comp.Plain(parts[i].strip()))
         elif message.message_type == "post":
             _ls = []
 
@@ -132,7 +168,7 @@ class LarkPlatformAdapter(Platform):
                 if comp["tag"] == "at":
                     abm.message.append(at_list[comp["user_id"]])
                 elif comp["tag"] == "text" and comp["text"].strip():
-                    abm.message.append(Plain(comp["text"].strip()))
+                    abm.message.append(Comp.Plain(comp["text"].strip()))
                 elif comp["tag"] == "img":
                     image_key = comp["image_key"]
                     request = (
@@ -147,10 +183,10 @@ class LarkPlatformAdapter(Platform):
                         logger.error(f"无法下载飞书图片: {image_key}")
                     image_bytes = response.file.read()
                     image_base64 = base64.b64encode(image_bytes).decode()
-                    abm.message.append(Image.fromBase64(image_base64))
+                    abm.message.append(Comp.Image.fromBase64(image_base64))
 
         for comp in abm.message:
-            if isinstance(comp, Plain):
+            if isinstance(comp, Comp.Plain):
                 abm.message_str += comp.text
         abm.message_id = message.message_id
         abm.raw_message = message
@@ -165,7 +201,10 @@ class LarkPlatformAdapter(Platform):
             else:
                 abm.session_id = abm.sender.user_id
         else:
-            abm.session_id = abm.sender.user_id
+            if abm.type == MessageType.GROUP_MESSAGE:
+                abm.session_id = f"{abm.sender.user_id}%{abm.group_id}"  # 也保留群组id
+            else:
+                abm.session_id = abm.sender.user_id
 
         logger.debug(abm)
         await self.handle_msg(abm)
@@ -185,5 +224,9 @@ class LarkPlatformAdapter(Platform):
         # self.client.start()
         await self.client._connect()
 
+    async def terminate(self):
+        await self.client._disconnect()
+        logger.info("飞书(Lark) 适配器已被优雅地关闭")
+
     def get_client(self) -> lark.Client:
         return self.client

astrbot/core/platform/sources/lark/lark_event.py

@@ -1,12 +1,16 @@
 import json
+import os
 import uuid
+import base64
 import lark_oapi as lark
+from io import BytesIO
 from typing import List
 from astrbot.api.event import AstrMessageEvent, MessageChain
 from astrbot.api.message_components import Plain, Image as AstrBotImage, At
 from astrbot.core.utils.io import download_image_by_url
 from lark_oapi.api.im.v1 import *
 from astrbot import logger
+from astrbot.core.utils.astrbot_path import get_astrbot_data_path
 
 
 class LarkMessageEvent(AstrMessageEvent):
@@ -27,22 +31,33 @@ class LarkMessageEvent(AstrMessageEvent):
                 _stage.append({"tag": "at", "user_id": comp.qq, "style": []})
             elif isinstance(comp, AstrBotImage):
                 file_path = ""
+                image_file = None
+
                 if comp.file and comp.file.startswith("file:///"):
                     file_path = comp.file.replace("file:///", "")
                 elif comp.file and comp.file.startswith("http"):
                     image_file_path = await download_image_by_url(comp.file)
                     file_path = image_file_path
                 elif comp.file and comp.file.startswith("base64://"):
-                    pass
+                    base64_str = comp.file.removeprefix("base64://")
+                    image_data = base64.b64decode(base64_str)
+                    # save as temp file
+                    temp_dir = os.path.join(get_astrbot_data_path(), "temp")
+                    file_path = os.path.join(temp_dir, f"{uuid.uuid4()}_test.jpg")
+                    with open(file_path, "wb") as f:
+                        f.write(BytesIO(image_data).getvalue())
                 else:
                     file_path = comp.file
 
+                if image_file is None:
+                    image_file = open(file_path, "rb")
+
                 request = (
                     CreateImageRequest.builder()
                     .request_body(
                         CreateImageRequestBody.builder()
                         .image_type("message")
-                        .image(open(file_path, "rb"))
+                        .image(image_file)
                         .build()
                     )
                     .build()
@@ -51,7 +66,7 @@ class LarkMessageEvent(AstrMessageEvent):
                 if not response.success():
                     logger.error(f"无法上传飞书图片({response.code}): {response.msg}")
                 image_key = response.data.image_key
-                print(image_key)
+                logger.debug(image_key)
                 ret.append(_stage)
                 ret.append([{"tag": "img", "image_key": image_key}])
                 _stage.clear()
@@ -91,3 +106,16 @@ class LarkMessageEvent(AstrMessageEvent):
             logger.error(f"回复飞书消息失败({response.code}): {response.msg}")
 
         await super().send(message)
+
+    async def send_streaming(self, generator, use_fallback: bool = False):
+        buffer = None
+        async for chain in generator:
+            if not buffer:
+                buffer = chain
+            else:
+                buffer.chain.extend(chain.chain)
+        if not buffer:
+            return
+        buffer.squash_plain()
+        await self.send(buffer)
+        return await super().send_streaming(generator, use_fallback)

astrbot/core/platform/sources/qqofficial/qqofficial_message_event.py

@@ -2,6 +2,7 @@ import botpy
 import botpy.message
 import botpy.types
 import botpy.types.message
+import asyncio
 from astrbot.core.utils.io import file_to_base64, download_image_by_url
 from astrbot.api.event import AstrMessageEvent, MessageChain
 from astrbot.api.platform import AstrBotMessage, PlatformMetadata
@@ -9,6 +10,8 @@ from astrbot.api.message_components import Plain, Image
 from botpy import Client
 from botpy.http import Route
 from astrbot.api import logger
+from botpy.types import message
+import random
 
 
 class QQOfficialMessageEvent(AstrMessageEvent):
@@ -25,13 +28,48 @@ class QQOfficialMessageEvent(AstrMessageEvent):
         self.send_buffer = None
 
     async def send(self, message: MessageChain):
-        if not self.send_buffer:
-            self.send_buffer = message
-        else:
-            self.send_buffer.chain.extend(message.chain)
+        self.send_buffer = message
+        await self._post_send()
+
+    async def send_streaming(self, generator, use_fallback: bool = False):
+        """流式输出仅支持消息列表私聊"""
+        stream_payload = {"state": 1, "id": None, "index": 0, "reset": False}
+        last_edit_time = 0  # 上次编辑消息的时间
+        throttle_interval = 1  # 编辑消息的间隔时间 (秒)
+        try:
+            async for chain in generator:
+                source = self.message_obj.raw_message
+                if not self.send_buffer:
+                    self.send_buffer = chain
+                else:
+                    self.send_buffer.chain.extend(chain.chain)
+
+                if isinstance(source, botpy.message.C2CMessage):
+                    # 真流式传输
+                    current_time = asyncio.get_event_loop().time()
+                    time_since_last_edit = current_time - last_edit_time
+
+                    if time_since_last_edit >= throttle_interval:
+                        ret = await self._post_send(stream=stream_payload)
+                        stream_payload["index"] += 1
+                        stream_payload["id"] = ret["id"]
+                        last_edit_time = asyncio.get_event_loop().time()
+
+            if isinstance(source, botpy.message.C2CMessage):
+                # 结束流式对话，并且传输 buffer 中剩余的消息
+                stream_payload["state"] = 10
+                ret = await self._post_send(stream=stream_payload)
+
+        except Exception as e:
+            logger.error(f"发送流式消息时出错: {e}", exc_info=True)
+            self.send_buffer = None
+
+        return await super().send_streaming(generator, use_fallback)
+
+    async def _post_send(self, stream: dict = None):
+        if not self.send_buffer:
+            return
 
-    async def _post_send(self):
-        """QQ 官方 API 仅支持回复一次"""
         source = self.message_obj.raw_message
         assert isinstance(
             source,
@@ -57,6 +95,9 @@ class QQOfficialMessageEvent(AstrMessageEvent):
             "msg_id": self.message_obj.message_id,
         }
 
+        if not isinstance(source, (botpy.message.Message, botpy.message.DirectMessage)):
+            payload["msg_seq"] = random.randint(1, 10000)
+
         match type(source):
             case botpy.message.GroupMessage:
                 if image_base64:
@@ -65,7 +106,7 @@ class QQOfficialMessageEvent(AstrMessageEvent):
                     )
                     payload["media"] = media
                     payload["msg_type"] = 7
-                await self.bot.api.post_group_message(
+                ret = await self.bot.api.post_group_message(
                     group_openid=source.group_openid, **payload
                 )
             case botpy.message.C2CMessage:
@@ -75,22 +116,34 @@ class QQOfficialMessageEvent(AstrMessageEvent):
                     )
                     payload["media"] = media
                     payload["msg_type"] = 7
-                await self.bot.api.post_c2c_message(
-                    openid=source.author.user_openid, **payload
-                )
+                if stream:
+                    ret = await self.post_c2c_message(
+                        openid=source.author.user_openid,
+                        **payload,
+                        stream=stream,
+                    )
+                else:
+                    ret = await self.post_c2c_message(
+                        openid=source.author.user_openid, **payload
+                    )
+                logger.debug(f"Message sent to C2C: {ret}")
             case botpy.message.Message:
                 if image_path:
                     payload["file_image"] = image_path
-                await self.bot.api.post_message(channel_id=source.channel_id, **payload)
+                ret = await self.bot.api.post_message(
+                    channel_id=source.channel_id, **payload
+                )
             case botpy.message.DirectMessage:
                 if image_path:
                     payload["file_image"] = image_path
-                await self.bot.api.post_dms(guild_id=source.guild_id, **payload)
+                ret = await self.bot.api.post_dms(guild_id=source.guild_id, **payload)
 
         await super().send(self.send_buffer)
 
         self.send_buffer = None
 
+        return ret
+
     async def upload_group_and_c2c_image(
         self, image_base64: str, file_type: int, **kwargs
     ) -> botpy.types.message.Media:
@@ -112,6 +165,27 @@ class QQOfficialMessageEvent(AstrMessageEvent):
             )
             return await self.bot.api._http.request(route, json=payload)
 
+    async def post_c2c_message(
+        self,
+        openid: str,
+        msg_type: int = 0,
+        content: str = None,
+        embed: message.Embed = None,
+        ark: message.Ark = None,
+        message_reference: message.Reference = None,
+        media: message.Media = None,
+        msg_id: str = None,
+        msg_seq: str = 1,
+        event_id: str = None,
+        markdown: message.MarkdownPayload = None,
+        keyboard: message.Keyboard = None,
+        stream: dict = None,
+    ) -> message.Message:
+        payload = locals()
+        payload.pop("self", None)
+        route = Route("POST", "/v2/users/{openid}/messages", openid=openid)
+        return await self.bot.api._http.request(route, json=payload)
+
     @staticmethod
     async def _parse_to_qqofficial(message: MessageChain):
         plain_text = ""
@@ -122,16 +196,16 @@ class QQOfficialMessageEvent(AstrMessageEvent):
                 plain_text += i.text
             elif isinstance(i, Image) and not image_base64:
                 if i.file and i.file.startswith("file:///"):
-                    image_base64 = file_to_base64(i.file[8:]).replace("base64://", "")
+                    image_base64 = file_to_base64(i.file[8:])
                     image_file_path = i.file[8:]
                 elif i.file and i.file.startswith("http"):
                     image_file_path = await download_image_by_url(i.file)
-                    image_base64 = file_to_base64(image_file_path).replace(
-                        "base64://", ""
-                    )
+                    image_base64 = file_to_base64(image_file_path)
+                elif i.file and i.file.startswith("base64://"):
+                    image_base64 = i.file
                 else:
-                    image_base64 = file_to_base64(i.file).replace("base64://", "")
-                    image_file_path = i.file
+                    image_base64 = file_to_base64(i.file)
+                image_base64 = image_base64.removeprefix("base64://")
             else:
                 logger.debug(f"qq_official 忽略 {i.type}")
         return plain_text, image_base64, image_file_path

astrbot/core/platform/sources/qqofficial/qqofficial_platform_adapter.py

@@ -17,6 +17,7 @@ from astrbot.api.platform import (
     MessageType,
     PlatformMetadata,
 )
+from astrbot import logger
 from astrbot.api.event import MessageChain
 from typing import Union, List
 from astrbot.api.message_components import Image, Plain, At
@@ -125,8 +126,9 @@ class QQOfficialPlatformAdapter(Platform):
 
     def meta(self) -> PlatformMetadata:
         return PlatformMetadata(
-            "qq_official",
-            "QQ 机器人官方 API 适配器",
+            name="qq_official",
+            description="QQ 机器人官方 API 适配器",
+            id=self.config.get("id"),
         )
 
     @staticmethod
@@ -204,3 +206,7 @@ class QQOfficialPlatformAdapter(Platform):
 
     def get_client(self) -> botClient:
         return self.client
+
+    async def terminate(self):
+        await self.client.close()
+        logger.info("QQ 官方机器人接口 适配器已被优雅地关闭")

astrbot/core/platform/sources/qqofficial_webhook/qo_webhook_adapter.py

@@ -13,6 +13,7 @@ from .qo_webhook_event import QQOfficialWebhookMessageEvent
 from ...register import register_platform_adapter
 from .qo_webhook_server import QQOfficialWebhook
 from ..qqofficial.qqofficial_platform_adapter import QQOfficialPlatformAdapter
+from astrbot import logger
 
 # remove logger handler
 for handler in logging.root.handlers[:]:
@@ -98,8 +99,9 @@ class QQOfficialWebhookPlatformAdapter(Platform):
 
     def meta(self) -> PlatformMetadata:
         return PlatformMetadata(
-            "qq_official_webhook",
-            "QQ 机器人官方 API 适配器",
+            name="qq_official_webhook",
+            description="QQ 机器人官方 API 适配器",
+            id=self.config.get("id"),
         )
 
     async def run(self):
@@ -111,3 +113,12 @@ class QQOfficialWebhookPlatformAdapter(Platform):
 
     def get_client(self) -> botClient:
         return self.client
+
+    async def terminate(self):
+        self.webhook_helper.shutdown_event.set()
+        await self.client.close()
+        try:
+            await self.webhook_helper.server.shutdown()
+        except Exception as _:
+            pass
+        logger.info("QQ 机器人官方 API 适配器已经被优雅地关闭")

astrbot/core/platform/sources/qqofficial_webhook/qo_webhook_server.py

@@ -15,6 +15,7 @@ class QQOfficialWebhook:
         self.appid = config["appid"]
         self.secret = config["secret"]
         self.port = config.get("port", 6196)
+        self.callback_server_host = config.get("callback_server_host", "0.0.0.0")
 
         if isinstance(self.port, str):
             self.port = int(self.port)
@@ -29,6 +30,7 @@ class QQOfficialWebhook:
         )
         self.client = botpy_client
         self.event_queue = event_queue
+        self.shutdown_event = asyncio.Event()
 
     async def initialize(self):
         logger.info("正在登录到 QQ 官方机器人...")
@@ -95,13 +97,14 @@ class QQOfficialWebhook:
         return {"opcode": 12}
 
     async def start_polling(self):
+        logger.info(
+            f"将在 {self.callback_server_host}:{self.port} 端口启动 QQ 官方机器人 webhook 适配器。"
+        )
         await self.server.run_task(
-            host="0.0.0.0",
+            host=self.callback_server_host,
             port=self.port,
-            shutdown_trigger=self.shutdown_trigger_placeholder,
+            shutdown_trigger=self.shutdown_trigger,
         )
 
-    async def shutdown_trigger_placeholder(self):
-        while not self.event_queue.closed:  # noqa: ASYNC110
-            await asyncio.sleep(1)
-        logger.info("qq_official_webhook 适配器已关闭。")
+    async def shutdown_trigger(self):
+        await self.shutdown_event.wait()

astrbot/core/platform/sources/slack/client.py

@@ -0,0 +1,162 @@
+import json
+import hmac
+import hashlib
+import asyncio
+import logging
+from typing import Callable, Optional
+from quart import Quart, request, Response
+from slack_sdk.web.async_client import AsyncWebClient
+from slack_sdk.socket_mode.aiohttp import SocketModeClient
+from slack_sdk.socket_mode.request import SocketModeRequest
+from slack_sdk.socket_mode.response import SocketModeResponse
+from astrbot.api import logger
+
+
+class SlackWebhookClient:
+    """Slack Webhook 模式客户端，使用 Quart 作为 Web 服务器"""
+
+    def __init__(
+        self,
+        web_client: AsyncWebClient,
+        signing_secret: str,
+        host: str = "0.0.0.0",
+        port: int = 3000,
+        path: str = "/slack/events",
+        event_handler: Optional[Callable] = None,
+    ):
+        self.web_client = web_client
+        self.signing_secret = signing_secret
+        self.host = host
+        self.port = port
+        self.path = path
+        self.event_handler = event_handler
+
+        self.app = Quart(__name__)
+        self._setup_routes()
+
+        # 禁用 Quart 的默认日志输出
+        logging.getLogger("quart.app").setLevel(logging.WARNING)
+        logging.getLogger("quart.serving").setLevel(logging.WARNING)
+
+        self.shutdown_event = asyncio.Event()
+
+    def _setup_routes(self):
+        """设置路由"""
+
+        @self.app.route(self.path, methods=["POST"])
+        async def slack_events():
+            """处理 Slack 事件"""
+            try:
+                # 获取请求体和头部
+                body = await request.get_data()
+                event_data = json.loads(body.decode("utf-8"))
+
+                # Verify Slack request signature
+                timestamp = request.headers.get("X-Slack-Request-Timestamp")
+                signature = request.headers.get("X-Slack-Signature")
+                if not timestamp or not signature:
+                    return Response("Missing headers", status=400)
+                # Calculate the HMAC signature
+                sig_basestring = f"v0:{timestamp}:{body.decode('utf-8')}"
+                my_signature = (
+                    "v0="
+                    + hmac.new(
+                        self.signing_secret.encode("utf-8"),
+                        sig_basestring.encode("utf-8"),
+                        hashlib.sha256,
+                    ).hexdigest()
+                )
+                # Verify the signature
+                if not hmac.compare_digest(my_signature, signature):
+                    logger.warning("Slack request signature verification failed")
+                    return Response("Invalid signature", status=400)
+                logger.info(f"Received Slack event: {event_data}")
+
+                # 处理 URL 验证事件
+                if event_data.get("type") == "url_verification":
+                    return {"challenge": event_data.get("challenge")}
+                # 处理事件
+                if self.event_handler and event_data.get("type") == "event_callback":
+                    await self.event_handler(event_data)
+
+                return Response("", status=200)
+
+            except Exception as e:
+                logger.error(f"处理 Slack 事件时出错: {e}")
+                return Response("Internal Server Error", status=500)
+
+        @self.app.route("/health", methods=["GET"])
+        async def health_check():
+            """健康检查端点"""
+            return {"status": "ok", "service": "slack-webhook"}
+
+    async def start(self):
+        """启动 Webhook 服务器"""
+        logger.info(
+            f"Slack Webhook 服务器启动中，监听 {self.host}:{self.port}{self.path}..."
+        )
+
+        await self.app.run_task(
+            host=self.host,
+            port=self.port,
+            debug=False,
+            shutdown_trigger=self.shutdown_trigger,
+        )
+
+    async def shutdown_trigger(self):
+        await self.shutdown_event.wait()
+
+    async def stop(self):
+        """停止 Webhook 服务器"""
+        self.shutdown_event.set()
+        logger.info("Slack Webhook 服务器已停止")
+
+
+class SlackSocketClient:
+    """Slack Socket 模式客户端"""
+
+    def __init__(
+        self,
+        web_client: AsyncWebClient,
+        app_token: str,
+        event_handler: Optional[Callable] = None,
+    ):
+        self.web_client = web_client
+        self.app_token = app_token
+        self.event_handler = event_handler
+        self.socket_client = None
+
+    async def _handle_events(self, _: SocketModeClient, req: SocketModeRequest):
+        """处理 Socket Mode 事件"""
+        try:
+            # 确认收到事件
+            response = SocketModeResponse(envelope_id=req.envelope_id)
+            await self.socket_client.send_socket_mode_response(response)
+
+            # 处理事件
+            if self.event_handler:
+                await self.event_handler(req)
+
+        except Exception as e:
+            logger.error(f"处理 Socket Mode 事件时出错: {e}")
+
+    async def start(self):
+        """启动 Socket Mode 连接"""
+        self.socket_client = SocketModeClient(
+            app_token=self.app_token,
+            logger=logger,
+            web_client=self.web_client,
+        )
+
+        # 注册事件处理器
+        self.socket_client.socket_mode_request_listeners.append(self._handle_events)
+
+        logger.info("Slack Socket Mode 客户端启动中...")
+        await self.socket_client.connect()
+
+    async def stop(self):
+        """停止 Socket Mode 连接"""
+        if self.socket_client:
+            await self.socket_client.disconnect()
+            await self.socket_client.close()
+        logger.info("Slack Socket Mode 客户端已停止")

astrbot/core/platform/sources/slack/slack_adapter.py

@@ -0,0 +1,398 @@
+import time
+import asyncio
+import uuid
+import aiohttp
+import re
+import base64
+from typing import Awaitable, Any
+from slack_sdk.web.async_client import AsyncWebClient
+from slack_sdk.socket_mode.request import SocketModeRequest
+from astrbot.api.platform import (
+    Platform,
+    AstrBotMessage,
+    MessageMember,
+    MessageType,
+    PlatformMetadata,
+)
+from astrbot.api.event import MessageChain
+from .slack_event import SlackMessageEvent
+from .client import SlackWebhookClient, SlackSocketClient
+from astrbot.api.message_components import *  # noqa: F403
+from astrbot.api import logger
+from astrbot.core.platform.astr_message_event import MessageSesion
+from ...register import register_platform_adapter
+
+
+@register_platform_adapter(
+    "slack", "适用于 Slack 的消息平台适配器，支持 Socket Mode 和 Webhook Mode。"
+)
+class SlackAdapter(Platform):
+    def __init__(
+        self, platform_config: dict, platform_settings: dict, event_queue: asyncio.Queue
+    ) -> None:
+        super().__init__(event_queue)
+
+        self.config = platform_config
+        self.settings = platform_settings
+        self.unique_session = platform_settings.get("unique_session", False)
+
+        self.bot_token = platform_config.get("bot_token")
+        self.app_token = platform_config.get("app_token")
+        self.signing_secret = platform_config.get("signing_secret")
+        self.connection_mode = platform_config.get("slack_connection_mode", "socket")
+        self.webhook_host = platform_config.get("slack_webhook_host", "0.0.0.0")
+        self.webhook_port = platform_config.get("slack_webhook_port", 3000)
+        self.webhook_path = platform_config.get(
+            "slack_webhook_path", "/astrbot-slack-webhook/callback"
+        )
+
+        if not self.bot_token:
+            raise ValueError("Slack bot_token 是必需的")
+
+        if self.connection_mode == "socket" and not self.app_token:
+            raise ValueError("Socket Mode 需要 app_token")
+
+        if self.connection_mode == "webhook" and not self.signing_secret:
+            raise ValueError("Webhook Mode 需要 signing_secret")
+
+        self.metadata = PlatformMetadata(
+            name="slack",
+            description="适用于 Slack 的消息平台适配器，支持 Socket Mode 和 Webhook Mode。",
+            id=self.config.get("id"),
+        )
+
+        # 初始化 Slack Web Client
+        self.web_client = AsyncWebClient(token=self.bot_token, logger=logger)
+        self.socket_client = None
+        self.webhook_client = None
+
+        self.bot_self_id = None
+
+    async def send_by_session(
+        self, session: MessageSesion, message_chain: MessageChain
+    ):
+        blocks, text = SlackMessageEvent._parse_slack_blocks(
+            message_chain=message_chain, web_client=self.web_client
+        )
+
+        try:
+            if session.message_type == MessageType.GROUP_MESSAGE:
+                # 发送到频道
+                channel_id = (
+                    session.session_id.split("_")[-1]
+                    if "_" in session.session_id
+                    else session.session_id
+                )
+                await self.web_client.chat_postMessage(
+                    channel=channel_id,
+                    text=text,
+                    blocks=blocks if blocks else None,
+                )
+            else:
+                # 发送私信
+                await self.web_client.chat_postMessage(
+                    channel=session.session_id,
+                    text=text,
+                    blocks=blocks if blocks else None,
+                )
+        except Exception as e:
+            logger.error(f"Slack 发送消息失败: {e}")
+
+        await super().send_by_session(session, message_chain)
+
+    async def convert_message(self, event: dict) -> AstrBotMessage:
+        logger.debug(f"[slack] RawMessage {event}")
+
+        abm = AstrBotMessage()
+        abm.self_id = self.bot_self_id
+
+        # 获取用户信息
+        user_id = event.get("user", "")
+        try:
+            user_info = await self.web_client.users_info(user=user_id)
+            user_data = user_info["user"]
+            user_name = user_data.get("real_name") or user_data.get("name", user_id)
+        except Exception:
+            user_name = user_id
+
+        abm.sender = MessageMember(user_id=user_id, nickname=user_name)
+
+        # 判断消息类型
+        channel_id = event.get("channel", "")
+        try:
+            channel_info = await self.web_client.conversations_info(channel=channel_id)
+            is_im = channel_info["channel"]["is_im"]
+
+            if is_im:
+                abm.type = MessageType.FRIEND_MESSAGE
+            else:
+                abm.type = MessageType.GROUP_MESSAGE
+                abm.group_id = channel_id
+        except Exception:
+            # 默认作为群组消息处理
+            abm.type = MessageType.GROUP_MESSAGE
+            abm.group_id = channel_id
+
+        # 设置会话ID
+        if self.unique_session and abm.type == MessageType.GROUP_MESSAGE:
+            abm.session_id = f"{user_id}_{channel_id}"
+        else:
+            abm.session_id = (
+                channel_id if abm.type == MessageType.GROUP_MESSAGE else user_id
+            )
+
+        abm.message_id = event.get("client_msg_id", uuid.uuid4().hex)
+        abm.timestamp = int(float(event.get("ts", time.time())))
+
+        # 处理消息内容
+        message_text = event.get("text", "")
+        abm.message_str = message_text
+        abm.message = []
+
+        # 优先使用 blocks 字段解析消息
+        if "blocks" in event and event["blocks"]:
+            abm.message = self._parse_blocks(event["blocks"])
+            # 更新 message_str
+            abm.message_str = ""
+            for component in abm.message:
+                if isinstance(component, Plain):
+                    abm.message_str += component.text
+        elif message_text:
+            # 处理传统的文本消息
+            if "<@" in message_text:
+                mentions = re.findall(r"<@([^>]+)>", message_text)
+                for mention in mentions:
+                    try:
+                        mentioned_user = await self.web_client.users_info(user=mention)
+                        user_data = mentioned_user["user"]
+                        user_name = user_data.get("real_name") or user_data.get(
+                            "name", mention
+                        )
+                        abm.message.append(At(qq=mention, name=user_name))
+                    except Exception:
+                        abm.message.append(At(qq=mention, name=""))
+
+                # 清理消息文本中的@标记
+                if clean_text := re.sub(r"<@[^>]+>", "", message_text).strip():
+                    abm.message.append(Plain(text=clean_text))
+            else:
+                abm.message.append(Plain(text=message_text))
+
+        # 处理文件附件
+        if "files" in event:
+            for file_info in event["files"]:
+                file_name = file_info.get("name", "unknown")
+                file_url = file_info.get("url_private", "")
+                if file_info.get("mimetype", "").startswith("image/"):
+                    file_url = await self.get_file_base64(file_url)
+                    abm.message.append(Image.fromBase64(base64=file_url))
+                else:
+                    # TODO: 下载鉴权
+                    abm.message.append(
+                        File(name=file_name, file=file_url, url=file_url)
+                    )
+
+        abm.raw_message = event
+        return abm
+
+    def _parse_blocks(self, blocks: list) -> list:
+        """解析 Slack blocks 格式的消息内容"""
+        message_components = []
+
+        for block in blocks:
+            block_type = block.get("type", "")
+
+            if block_type == "rich_text":
+                # 处理富文本块
+                elements = block.get("elements", [])
+                for element in elements:
+                    if element.get("type") == "rich_text_section":
+                        # 处理富文本段落
+                        section_elements = element.get("elements", [])
+                        text_content = ""
+
+                        for section_element in section_elements:
+                            element_type = section_element.get("type", "")
+
+                            if element_type == "text":
+                                # 普通文本
+                                text_content += section_element.get("text", "")
+                            elif element_type == "user":
+                                # @用户提及
+                                user_id = section_element.get("user_id", "")
+                                if user_id:
+                                    # 将之前的文本内容先添加到组件中
+                                    if text_content.strip():
+                                        message_components.append(
+                                            Plain(text=text_content)
+                                        )
+                                        text_content = ""
+                                    # 添加@提及组件
+                                    message_components.append(At(qq=user_id, name=""))
+                            elif element_type == "channel":
+                                # #频道提及
+                                channel_id = section_element.get("channel_id", "")
+                                text_content += f"#{channel_id}"
+                            elif element_type == "link":
+                                # 链接
+                                url = section_element.get("url", "")
+                                link_text = section_element.get("text", url)
+                                text_content += f"[{link_text}]({url})"
+                            elif element_type == "emoji":
+                                # 表情符号
+                                emoji_name = section_element.get("name", "")
+                                text_content += f":{emoji_name}:"
+
+                        if text_content.strip():
+                            message_components.append(Plain(text=text_content))
+
+                    elif element.get("type") == "rich_text_list":
+                        # 处理列表
+                        list_items = element.get("elements", [])
+                        list_text = ""
+                        for item in list_items:
+                            if item.get("type") == "rich_text_section":
+                                item_elements = item.get("elements", [])
+                                item_text = ""
+                                for item_element in item_elements:
+                                    if item_element.get("type") == "text":
+                                        item_text += item_element.get("text", "")
+                                list_text += f"• {item_text}\n"
+
+                        if list_text.strip():
+                            message_components.append(Plain(text=list_text.strip()))
+
+            elif block_type == "section":
+                # 处理段落块
+                if "text" in block:
+                    text_obj = block["text"]
+                    if text_obj.get("type") == "mrkdwn":
+                        text_content = text_obj.get("text", "")
+                        message_components.append(Plain(text=text_content))
+
+        return message_components
+
+    async def _handle_socket_event(self, req: SocketModeRequest):
+        """处理 Socket Mode 事件"""
+        if req.type == "events_api":
+            # 事件 API
+            event = req.payload.get("event", {})
+
+            # 忽略机器人自己的消息和消息编辑
+            if event.get("subtype") in [
+                "bot_message",
+                "message_changed",
+                "message_deleted",
+            ]:
+                return
+
+            if event.get("bot_id"):
+                return
+
+            if event.get("type") in ["message", "app_mention"]:
+                abm = await self.convert_message(event)
+                if abm:
+                    await self.handle_msg(abm)
+
+    async def get_bot_user_id(self):
+        auth_info = await self.web_client.auth_test()
+        return auth_info.get("user_id")
+
+    async def get_file_base64(self, url: str) -> str:
+        """下载 Slack 文件并返回 Base64 编码的内容"""
+        headers = {"Authorization": f"Bearer {self.bot_token}"}
+        async with aiohttp.ClientSession() as session:
+            async with session.get(url, headers=headers) as resp:
+                if resp.status == 200:
+                    content = await resp.read()
+                    base64_content = base64.b64encode(content).decode("utf-8")
+                    return base64_content
+                else:
+                    logger.error(
+                        f"Failed to download slack file: {resp.status} {await resp.text()}"
+                    )
+                    raise Exception(f"下载文件失败: {resp.status}")
+
+    async def run(self) -> Awaitable[Any]:
+        self.bot_self_id = await self.get_bot_user_id()
+        logger.info(f"Slack auth test OK. Bot ID: {self.bot_self_id}")
+
+        if self.connection_mode == "socket":
+            if not self.app_token:
+                raise ValueError("Socket Mode 需要 app_token")
+
+            # 创建 Socket 客户端
+            self.socket_client = SlackSocketClient(
+                self.web_client, self.app_token, self._handle_socket_event
+            )
+
+            logger.info("Slack 适配器 (Socket Mode) 启动中...")
+            await self.socket_client.start()
+
+        elif self.connection_mode == "webhook":
+            if not self.signing_secret:
+                raise ValueError("Webhook Mode 需要 signing_secret")
+
+            # 创建 Webhook 客户端
+            self.webhook_client = SlackWebhookClient(
+                self.web_client,
+                self.signing_secret,
+                self.webhook_host,
+                self.webhook_port,
+                self.webhook_path,
+                self._handle_webhook_event,
+            )
+
+            logger.info(
+                f"Slack 适配器 (Webhook Mode) 启动中，监听 {self.webhook_host}:{self.webhook_port}{self.webhook_path}..."
+            )
+            await self.webhook_client.start()
+
+        else:
+            raise ValueError(
+                f"不支持的连接模式: {self.connection_mode}，请使用 'socket' 或 'webhook'"
+            )
+
+    async def _handle_webhook_event(self, event_data: dict):
+        """处理 Webhook 事件"""
+        event = event_data.get("event", {})
+
+        # 忽略机器人自己的消息和消息编辑
+        if event.get("subtype") in [
+            "bot_message",
+            "message_changed",
+            "message_deleted",
+        ]:
+            return
+
+        if event.get("bot_id"):
+            return
+
+        if event.get("type") in ["message", "app_mention"]:
+            abm = await self.convert_message(event)
+            if abm:
+                await self.handle_msg(abm)
+
+    async def terminate(self):
+        if self.socket_client:
+            await self.socket_client.stop()
+        if self.webhook_client:
+            await self.webhook_client.stop()
+        logger.info("Slack 适配器已被优雅地关闭")
+
+    def meta(self) -> PlatformMetadata:
+        return self.metadata
+
+    async def handle_msg(self, message: AstrBotMessage):
+        message_event = SlackMessageEvent(
+            message_str=message.message_str,
+            message_obj=message,
+            platform_meta=self.meta(),
+            session_id=message.session_id,
+            web_client=self.web_client,
+        )
+
+        self.commit_event(message_event)
+
+    def get_client(self):
+        return self.web_client

astrbot/core/platform/sources/slack/slack_event.py

@@ -0,0 +1,243 @@
+import asyncio
+import re
+from typing import AsyncGenerator
+from slack_sdk.web.async_client import AsyncWebClient
+from astrbot.api.event import AstrMessageEvent, MessageChain
+from astrbot.api.message_components import (
+    Image,
+    Plain,
+    File,
+    BaseMessageComponent,
+)
+from astrbot.api.platform import Group, MessageMember
+from astrbot.api import logger
+
+
+class SlackMessageEvent(AstrMessageEvent):
+    def __init__(
+        self,
+        message_str,
+        message_obj,
+        platform_meta,
+        session_id,
+        web_client: AsyncWebClient,
+    ):
+        super().__init__(message_str, message_obj, platform_meta, session_id)
+        self.web_client = web_client
+
+    @staticmethod
+    async def _from_segment_to_slack_block(
+        segment: BaseMessageComponent, web_client: AsyncWebClient
+    ) -> dict:
+        """将消息段转换为 Slack 块格式"""
+        if isinstance(segment, Plain):
+            return {"type": "section", "text": {"type": "mrkdwn", "text": segment.text}}
+        elif isinstance(segment, Image):
+            # upload file
+            url = segment.url or segment.file
+            if url.startswith("http"):
+                return {
+                    "type": "image",
+                    "image_url": url,
+                    "alt_text": "图片",
+                }
+            path = await segment.convert_to_file_path()
+            response = await web_client.files_upload_v2(
+                file=path,
+                filename="image.jpg",
+            )
+            if not response["ok"]:
+                logger.error(f"Slack file upload failed: {response['error']}")
+                return {
+                    "type": "section",
+                    "text": {"type": "mrkdwn", "text": "图片上传失败"},
+                }
+            image_url = response["files"][0]["url_private"]
+            logger.debug(f"Slack file upload response: {response}")
+            return {
+                "type": "image",
+                "slack_file": {
+                    "url": image_url,
+                },
+                "alt_text": "图片",
+            }
+        elif isinstance(segment, File):
+            # upload file
+            url = segment.url or segment.file
+            response = await web_client.files_upload_v2(
+                file=url,
+                filename=segment.name or "file",
+            )
+            if not response["ok"]:
+                logger.error(f"Slack file upload failed: {response['error']}")
+                return {
+                    "type": "section",
+                    "text": {"type": "mrkdwn", "text": "文件上传失败"},
+                }
+            file_url = response["files"][0]["permalink"]
+            return {
+                "type": "section",
+                "text": {
+                    "type": "mrkdwn",
+                    "text": f"文件: <{file_url}|{segment.name or '文件'}>",
+                },
+            }
+        else:
+            return {"type": "section", "text": {"type": "mrkdwn", "text": str(segment)}}
+
+    @staticmethod
+    async def _parse_slack_blocks(
+        message_chain: MessageChain, web_client: AsyncWebClient
+    ):
+        """解析成 Slack 块格式"""
+        blocks = []
+        text_content = ""
+
+        for segment in message_chain.chain:
+            if isinstance(segment, Plain):
+                text_content += segment.text
+            else:
+                # 如果有文本内容，先添加文本块
+                if text_content.strip():
+                    blocks.append(
+                        {
+                            "type": "section",
+                            "text": {"type": "mrkdwn", "text": text_content},
+                        }
+                    )
+                    text_content = ""
+
+                # 添加其他类型的块
+                block = await SlackMessageEvent._from_segment_to_slack_block(
+                    segment, web_client
+                )
+                blocks.append(block)
+
+        # 如果最后还有文本内容
+        if text_content.strip():
+            blocks.append(
+                {"type": "section", "text": {"type": "mrkdwn", "text": text_content}}
+            )
+
+        return blocks, "" if blocks else text_content
+
+    async def send(self, message: MessageChain):
+        blocks, text = await SlackMessageEvent._parse_slack_blocks(
+            message, self.web_client
+        )
+
+        try:
+            if self.get_group_id():
+                # 发送到频道
+                await self.web_client.chat_postMessage(
+                    channel=self.get_group_id(),
+                    text=text,
+                    blocks=blocks or None,
+                )
+            else:
+                # 发送私信
+                await self.web_client.chat_postMessage(
+                    channel=self.get_sender_id(),
+                    text=text,
+                    blocks=blocks or None,
+                )
+        except Exception:
+            # 如果块发送失败，尝试只发送文本
+            fallback_text = ""
+            for segment in message.chain:
+                if isinstance(segment, Plain):
+                    fallback_text += segment.text
+                elif isinstance(segment, File):
+                    fallback_text += f" [文件: {segment.name}] "
+                elif isinstance(segment, Image):
+                    fallback_text += " [图片] "
+
+            if self.get_group_id():
+                await self.web_client.chat_postMessage(
+                    channel=self.get_group_id(), text=fallback_text
+                )
+            else:
+                await self.web_client.chat_postMessage(
+                    channel=self.get_sender_id(), text=fallback_text
+                )
+
+        await super().send(message)
+
+    async def send_streaming(
+        self, generator: AsyncGenerator, use_fallback: bool = False
+    ):
+        if not use_fallback:
+            buffer = None
+            async for chain in generator:
+                if not buffer:
+                    buffer = chain
+                else:
+                    buffer.chain.extend(chain.chain)
+            if not buffer:
+                return
+            buffer.squash_plain()
+            await self.send(buffer)
+            return await super().send_streaming(generator, use_fallback)
+
+        buffer = ""
+        pattern = re.compile(r"[^。？！~…]+[。？！~…]+")
+
+        async for chain in generator:
+            if isinstance(chain, MessageChain):
+                for comp in chain.chain:
+                    if isinstance(comp, Plain):
+                        buffer += comp.text
+                        if any(p in buffer for p in "。？！~…"):
+                            buffer = await self.process_buffer(buffer, pattern)
+                    else:
+                        await self.send(MessageChain(chain=[comp]))
+                        await asyncio.sleep(1.5)  # 限速
+
+        if buffer.strip():
+            await self.send(MessageChain([Plain(buffer)]))
+        return await super().send_streaming(generator, use_fallback)
+
+    async def get_group(self, group_id=None, **kwargs):
+        if group_id:
+            channel_id = group_id
+        elif self.get_group_id():
+            channel_id = self.get_group_id()
+        else:
+            return None
+
+        try:
+            # 获取频道信息
+            channel_info = await self.web_client.conversations_info(channel=channel_id)
+
+            # 获取频道成员
+            members_response = await self.web_client.conversations_members(
+                channel=channel_id
+            )
+
+            members = []
+            for member_id in members_response["members"]:
+                try:
+                    user_info = await self.web_client.users_info(user=member_id)
+                    user_data = user_info["user"]
+                    members.append(
+                        MessageMember(
+                            user_id=member_id,
+                            nickname=user_data.get("real_name")
+                            or user_data.get("name", member_id),
+                        )
+                    )
+                except Exception:
+                    # 如果获取用户信息失败，使用默认信息
+                    members.append(MessageMember(user_id=member_id, nickname=member_id))
+
+            channel_data = channel_info["channel"]
+            return Group(
+                group_id=channel_id,
+                group_name=channel_data.get("name", ""),
+                group_avatar="",
+                group_admins=[],  # Slack 的管理员信息需要特殊权限获取
+                group_owner=channel_data.get("creator", ""),
+                members=members,
+            )
+        except Exception:
+            return None