chore: bump version to 4.3.5

* feat: 支持配置工具调用超时时间并适配 ModelScope 的 MCP Server 配置。

closes: #2939

* fix: Remove unnecessary blank lines in _quick_test_mcp_connection function

.github/ISSUE_TEMPLATE/PLUGIN_PUBLISH.md

@@ -1,31 +0,0 @@
----
-name: '🥳 发布插件'
-title: "[Plugin] 插件名"
-about: 提交插件到插件市场
-labels: [ "plugin-publish" ]
-assignees: ''
-
----
-
-欢迎发布插件到插件市场！
-
-## 插件基本信息
-
-请将插件信息填写到下方的 Json 代码块中。`tags`（插件标签）和 `social_link`（社交链接）选填。
-
-```json
-{
-  "name": "插件名",
-  "desc": "插件介绍",
-  "author": "作者名",
-  "repo": "插件仓库链接",
-  "tags": [],
-  "social_link": ""
-}
-```
-
-## 检查
-
-- [ ] 我的插件经过完整的测试
-- [ ] 我的插件不包含恶意代码
-- [ ] 我已阅读并同意遵守该项目的 [行为准则](https://docs.github.com/zh/site-policy/github-terms/github-community-code-of-conduct)。

.github/ISSUE_TEMPLATE/PLUGIN_PUBLISH.yml

@@ -0,0 +1,56 @@
+name: 🥳 发布插件
+description: 提交插件到插件市场
+title: "[Plugin] 插件名"
+labels: ["plugin-publish"]
+assignees: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        欢迎发布插件到插件市场！
+
+  - type: markdown
+    attributes:
+      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,19 +1,46 @@
-<!-- 如果有的话，指定这个 PR 要解决的 ISSUE -->
-解决了 #XYZ
+<!-- 如果有的话，请指定此 PR 旨在解决的 ISSUE 编号。 -->
+<!-- If applicable, please specify the ISSUE number this PR aims to resolve. -->
 
-### Motivation
+fixes #XYZ
 
-<!--解释为什么要改动-->
+---
 
-### Modifications
+### Motivation / 动机
 
-<!--简单解释你的改动-->
+<!--请描述此项更改的动机：它解决了什么问题？（例如：修复了 XX 错误，添加了 YY 功能）-->
+<!--Please describe the motivation for this change: What problem does it solve? (e.g., Fixes XX bug, adds YY feature)-->
 
-### Check
+### Modifications / 改动点
 
-<!--如果分支被合并，您的代码将服务于数万名用户！在提交前，请核查一下几点内容-->
+<!--请总结你的改动：哪些核心文件被修改了？实现了什么功能？-->
+<!--Please summarize your changes: What core files were modified? What functionality was implemented?-->
 
-- [ ] 😊 我的 Commit Message 符合良好的[规范](https://www.conventionalcommits.org/en/v1.0.0/#summary)
-- [ ] 👀 我的更改经过良好的测试
-- [ ] 🤓 我确保没有引入新依赖库，或者引入了新依赖库的同时将其添加到了 `requirements.txt` 和 `pyproject.toml` 文件相应位置。
-- [ ] 😮 我的更改没有引入恶意代码
+### Verification Steps / 验证步骤
+
+<!--请为审查者 (Reviewer) 提供清晰、可复现的验证步骤（例如：1. 导航到... 2. 点击...）。-->
+<!--Please provide clear and reproducible verification steps for the Reviewer (e.g., 1. Navigate to... 2. Click...).-->
+
+### Screenshots or Test Results / 运行截图或测试结果
+
+<!--请粘贴截图、GIF 或测试日志，作为执行“验证步骤”的证据，证明此改动有效。-->
+<!--Please paste screenshots, GIFs, or test logs here as evidence of executing the "Verification Steps" to prove this change is effective.-->
+
+### Compatibility & Breaking Changes / 兼容性与破坏性变更
+
+<!--请说明此变更的兼容性：哪些是破坏性变更？哪些地方做了向后兼容处理？是否提供了数据迁移方法？-->
+<!--Please explain the compatibility of this change: What are the breaking changes? What backward-compatible measures were taken? Are data migration paths provided?-->
+
+- [ ] 这是一个破坏性变更 (Breaking Change)。/ This is a breaking change.
+- [ ] 这不是一个破坏性变更。/ This is NOT a breaking change.
+
+---
+
+### Checklist / 检查清单
+
+<!--如果分支被合并，您的代码将服务于数万名用户！在提交前，请核查一下几点内容。-->
+<!--If merged, your code will serve tens of thousands of users! Please double-check the following items before submitting.-->
+
+- [ ] 😊 如果 PR 中有新加入的功能，已经通过 Issue / 邮件等方式和作者讨论过。/ If there are new features added in the PR, I have discussed it with the authors through issues/emails, etc.
+- [ ] 👀 我的更改经过了良好的测试，**并已在上方提供了“验证步骤”和“运行截图”**。/ My changes have been well-tested, **and "Verification Steps" and "Screenshots" have been provided above**.
+- [ ] 🤓 我确保没有引入新依赖库，或者引入了新依赖库的同时将其添加到了 `requirements.txt` 和 `pyproject.toml` 文件相应位置。/ I have ensured that no new dependencies are introduced, OR if new dependencies are introduced, they have been added to the appropriate locations in `requirements.txt` and `pyproject.toml`.
+- [ ] 😮 我的更改没有引入恶意代码。/ My changes do not introduce malicious code.

.github/auto_assign.yml

@@ -0,0 +1,38 @@
+# Set to true to add reviewers to pull requests
+addReviewers: true
+
+# Set to true to add assignees to pull requests
+addAssignees: false
+
+# A list of reviewers to be added to pull requests (GitHub user name)
+reviewers:
+  - Soulter
+  - Raven95676
+  - Larch-C
+  - anka-afk
+  - advent259141
+  - Fridemn
+  - LIghtJUNction
+  # - zouyonghe
+
+# A number of reviewers added to the pull request
+# Set 0 to add all the reviewers (default: 0)
+numberOfReviewers: 2
+
+# A list of assignees, overrides reviewers if set
+# assignees:
+#   - assigneeA
+
+# A number of assignees to add to the pull request
+# Set to 0 to add all of the assignees.
+# Uses numberOfReviewers if unset.
+# numberOfAssignees: 2
+
+# A list of keywords to be skipped the process that add reviewers if pull requests include it
+skipKeywords:
+  - wip
+  - draft
+
+# A list of users to be skipped by both the add reviewers and add assignees processes
+# skipUsers:
+#   - dependabot[bot]

.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/workflows/auto_release.yml

@@ -13,7 +13,7 @@ jobs:
       contents: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Dashboard Build
         run: |
@@ -70,10 +70,10 @@ jobs:
     needs: build-and-publish-to-github-release
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.10'
 

.github/workflows/code-format.yml

@@ -0,0 +1,34 @@
+name: Code Format Check
+
+on:
+  pull_request:
+    branches: [ master ]
+  push:
+    branches: [ master ]
+
+jobs:
+  format-check:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v5
+      
+    - name: Set up Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: '3.10'
+        
+    - name: Install UV
+      run: pip install uv
+      
+    - name: Install dependencies
+      run: uv sync
+      
+    - name: Check code formatting with ruff
+      run: |
+        uv run ruff format --check .
+        
+    - name: Check code style with ruff
+      run: |
+        uv run ruff check .

.github/workflows/codeql.yml

@@ -56,11 +56,11 @@ 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
-      uses: github/codeql-action/init@v3
+      uses: github/codeql-action/init@v4
       with:
         languages: ${{ matrix.language }}
         build-mode: ${{ matrix.build-mode }}
@@ -88,6 +88,6 @@ jobs:
         exit 1
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v3
+      uses: github/codeql-action/analyze@v4
       with:
         category: "/language:${{matrix.language}}"

.github/workflows/coverage_test.yml

@@ -17,12 +17,12 @@ 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@v5
+        uses: actions/setup-python@v6
       
       - name: Install dependencies
         run: |

.github/workflows/dashboard_ci.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: npm install, build
         run: |
@@ -25,6 +25,8 @@ jobs:
           echo "COMMIT_SHA=$(git rev-parse HEAD)" >> $GITHUB_ENV
           mkdir -p dashboard/dist/assets
           echo $COMMIT_SHA > dashboard/dist/assets/version
+          cd dashboard
+          zip -r dist.zip dist
 
       - name: Archive production artifacts
         uses: actions/upload-artifact@v4
@@ -33,3 +35,14 @@ jobs:
           path: |
             dashboard/dist
             !dist/**/*.md
+
+      - name: Create GitHub Release
+        if: github.event_name == 'push'
+        uses: ncipollo/release-action@v1
+        with:
+          tag: release-${{ github.sha }}
+          owner: AstrBotDevs
+          repo: astrbot-release-harbour
+          body: "Automated release from commit ${{ github.sha }}"
+          token: ${{ secrets.ASTRBOT_HARBOUR_TOKEN }}
+          artifacts: "dashboard/dist.zip"

.github/workflows/docker-image.yml

@@ -12,7 +12,7 @@ jobs:
 
     steps:
       - name: Pull The Codes
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0  # Must be 0 so we can fetch tags
 
@@ -27,6 +27,33 @@ jobs:
         if: github.event_name == 'workflow_dispatch'
         run: git checkout ${{ steps.get-latest-tag.outputs.latest_tag }}
 
+      - name: Check if version is pre-release
+        id: check-prerelease
+        run: |
+          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
+            version="${{ steps.get-latest-tag.outputs.latest_tag }}"
+          else
+            version="${{ github.ref_name }}"
+          fi
+          if [[ "$version" == *"beta"* ]] || [[ "$version" == *"alpha"* ]]; then
+            echo "is_prerelease=true" >> $GITHUB_OUTPUT
+            echo "Version $version is a pre-release, will not push latest tag"
+          else
+            echo "is_prerelease=false" >> $GITHUB_OUTPUT
+            echo "Version $version is a stable release, will push latest tag"
+          fi
+
+      - name: Build Dashboard
+        run: |
+          cd dashboard
+          npm install
+          npm run build
+          mkdir -p dist/assets
+          echo $(git rev-parse HEAD) > dist/assets/version
+          cd ..
+          mkdir -p data
+          cp -r dashboard/dist data/
+
       - name: Set QEMU
         uses: docker/setup-qemu-action@v3
 
@@ -53,9 +80,9 @@ jobs:
           platforms: linux/amd64,linux/arm64
           push: true
           tags: |
-            ${{ secrets.DOCKER_HUB_USERNAME }}/astrbot:latest
+            ${{ steps.check-prerelease.outputs.is_prerelease == 'false' && format('{0}/astrbot:latest', secrets.DOCKER_HUB_USERNAME) || '' }}
             ${{ 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
+            ${{ steps.check-prerelease.outputs.is_prerelease == 'false' && '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

.github/workflows/stale.yml

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

.gitignore

@@ -30,4 +30,6 @@ packages/python_interpreter/workplace
 .conda/
 .idea
 pytest.ini
-.astrbot
+.astrbot
+
+uv.lock

Dockerfile

@@ -4,8 +4,6 @@ WORKDIR /AstrBot
 COPY . /AstrBot/
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    nodejs \
-    npm \
     gcc \
     build-essential \
     python3-dev \
@@ -13,23 +11,20 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libssl-dev \
     ca-certificates \
     bash \
+    ffmpeg \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 
+RUN apt-get update && apt-get install -y curl gnupg && \
+    curl -fsSL https://deb.nodesource.com/setup_lts.x | bash - && \
+    apt-get install -y nodejs && \
+    rm -rf /var/lib/apt/lists/*
+
 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 uv pip install socksio uv pilk --no-cache-dir --system
 
-# 释出 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 6185
 EXPOSE 6186
 
 CMD [ "python", "main.py" ]
-
-
-

README.md

@@ -1,13 +1,9 @@
-<p align="center">
- 
 ![AstrBot-Logo-Simplified](https://github.com/user-attachments/assets/ffd99b6b-3272-4682-beaa-6fe74250f7d9)
 
 </p>
 
 <div align="center">
 
-_✨ 易上手的多平台 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?style=for-the-badge&color=76bad9)](https://github.com/Soulter/AstrBot/releases/latest)
@@ -15,69 +11,62 @@ _✨ 易上手的多平台 LLM 聊天机器人及开发框架 ✨_
 <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> ｜
-<a href="https://astrbot.app/">查看文档</a> ｜
+<a href="https://astrbot.app/">文档</a> ｜
+<a href="https://blog.astrbot.app/">Blog</a> ｜
+<a href="https://astrbot.featurebase.app/roadmap">路线图</a> ｜
 <a href="https://github.com/Soulter/AstrBot/issues">问题提交</a>
 </div>
 
-AstrBot 是一个松耦合、异步、支持多消息平台部署、具有易用的插件系统和完善的大语言模型（LLM）接入功能的聊天机器人及开发框架。
+AstrBot 是一个开源的一站式 Agent 聊天机器人平台及开发框架。
 
+## 主要功能
 
-<!-- [![codecov](https://img.shields.io/codecov/c/github/soulter/astrbot?style=for-the-badge)](https://codecov.io/gh/Soulter/AstrBot)
- -->
+1. **大模型对话**。支持接入多种大模型服务。支持多模态、工具调用、MCP、原生知识库、人设等功能。
+2. **多消息平台支持**。支持接入 QQ、企业微信、微信公众号、飞书、Telegram、钉钉、Discord、KOOK 等平台。支持速率限制、白名单、百度内容审核。
+3. **Agent**。完善适配的 Agentic 能力。支持多轮工具调用、内置沙盒代码执行器、网页搜索等功能。
+4. **插件扩展**。深度优化的插件机制，支持[开发插件](https://astrbot.app/dev/plugin.html)扩展功能，社区插件生态丰富。
+5. **WebUI**。可视化配置和管理机器人，功能齐全。
 
-> [!WARNING]
-> 
-> 请务必修改默认密码以及保证 AstrBot 版本 >= 3.5.13。
+## 部署方式
 
-## ✨ 近期更新
+#### Docker 部署(推荐 🥳)
 
-<details><summary>1. AstrBot 现已自带知识库能力</summary>
-
- 📚 详见[文档](https://astrbot.app/use/knowledge-base.html)
-
- ![image](https://github.com/user-attachments/assets/28b639b0-bb5c-4958-8e94-92ae8cfd1ab4)
-
-</details>
-
-2. AstrBot 现已支持接入 [MCP](https://modelcontextprotocol.io/) 服务器！
-
-## ✨ 主要功能
-
-> [!NOTE]
-> 🪧 我们正基于前沿科研成果，设计并实现适用于角色扮演和情感陪伴的长短期记忆模型及情绪控制模型，旨在提升对话的真实性与情感表达能力。敬请期待 `v3.6.0` 版本！
-
-1. **大语言模型对话**。支持各种大语言模型，包括 OpenAI API、Google Gemini、Llama、Deepseek、ChatGLM 等，支持接入本地部署的大模型，通过 Ollama、LLMTuner。具有多轮对话、人格情境、多模态能力，支持图片理解、语音转文字（Whisper）。
-2. **多消息平台接入**。支持接入 QQ（OneBot、QQ 官方机器人平台）、QQ 频道、企业微信、微信公众号、飞书、Telegram、钉钉、Discord、KOOK、VoceChat。支持速率限制、白名单、关键词过滤、百度内容审核。
-3. **Agent**。原生支持部分 Agent 能力，如代码执行器、自然语言待办、网页搜索。对接 [Dify 平台](https://dify.ai/)，便捷接入 Dify 智能助手、知识库和 Dify 工作流。
-4. **插件扩展**。深度优化的插件机制，支持[开发插件](https://astrbot.app/dev/plugin.html)扩展功能，极简开发。已支持安装多个插件。
-5. **可视化管理面板**。支持可视化修改配置、插件管理、日志查看等功能，降低配置难度。集成 WebChat，可在面板上与大模型对话。
-6. **高稳定性、高模块化**。基于事件总线和流水线的架构设计，高度模块化，低耦合。
-
-> [!TIP]
-> WebUI 在线体验 Demo: [https://demo.astrbot.app/](https://demo.astrbot.app/)
-> 
-> 用户名: `astrbot`, 密码: `astrbot`。
-
-## ✨ 使用方式
-
-#### 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 一键安装器部署
 
 请参阅官方文档 [使用 Windows 一键安装器部署 AstrBot](https://astrbot.app/deploy/astrbot/windows.html) 。
 
-#### 宝塔面板部署
-
-请参阅官方文档 [宝塔面板部署](https://astrbot.app/deploy/astrbot/btpanel.html) 。
-
 #### CasaOS 部署
 
 社区贡献的部署方式。
@@ -86,9 +75,7 @@ AstrBot 是一个松耦合、异步、支持多消息平台部署、具有易用
 
 #### 手动部署
 
-> 推荐使用 `uv`。
-
-首先，安装 uv：
+首先安装 uv：
 
 ```bash
 pip install uv
@@ -101,71 +88,102 @@ git clone https://github.com/AstrBotDevs/AstrBot && cd AstrBot
 uv run main.py
 ```
 
-或者，直接通过 uvx 安装 AstrBot：
-
-```bash
-mkdir astrbot && cd astrbot
-uvx astrbot init
-# uvx astrbot run
-```
-
 或者请参阅官方文档 [通过源码部署 AstrBot](https://astrbot.app/deploy/astrbot/cli.html) 。
 
-#### 在 Replit 上部署
+## 🌍 社区
 
-[![Run on Repl.it](https://repl.it/badge/github/Soulter/AstrBot)](https://repl.it/github/Soulter/AstrBot)
+### QQ 群组
 
-#### 在 雨云 上部署
+- 1 群：322154837
+- 3 群：630166526
+- 5 群：822130018
+- 6 群：753075035
+- 开发者群：975206796
 
-[![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)
+### Telegram 群组
+
+<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>
+
+### Discord 群组
+
+<a href="https://discord.gg/hAVk6tgV36"><img alt="Discord_community" src="https://img.shields.io/badge/Discord-AstrBot-purple?style=for-the-badge&color=76bad9"></a>
 
 ## ⚡ 消息平台支持情况
 
+**官方维护**
+
 | 平台    | 支持性 |
 | -------- | ------- |
-| QQ(官方机器人接口) | ✔    |
+| QQ(官方平台) | ✔    |
 | QQ(OneBot)      | ✔    |
 | Telegram   | ✔    |
-| 企业微信    | ✔    |
+| 企微应用    | ✔    |
 | 微信客服    | ✔    |
 | 微信公众号    | ✔    |
 | 飞书   | ✔    |
 | 钉钉   | ✔    |
 | Slack   | ✔    |
 | Discord   | ✔    |
+| Satori   | ✔    |
+| Misskey   | ✔    |
+| 企微智能机器人 | 将支持 |
+| Whatsapp | 将支持 |
+| LINE | 将支持 |
+
+**社区维护**
+
+| 平台    | 支持性 |
+| -------- | ------- |
 | [KOOK](https://github.com/wuyan1003/astrbot_plugin_kook_adapter)   | ✔    |
 | [VoceChat](https://github.com/HikariFroya/astrbot_plugin_vocechat)   | ✔    |
-| 微信对话开放平台 | 🚧    |
-| WhatsApp   | 🚧    |
-| 小爱音响   | 🚧    |
+| [Bilibili 私信](https://github.com/Hina-Chat/astrbot_plugin_bilibili_adapter)   | ✔    |
 
 ## ⚡ 提供商支持情况
 
-| 名称    | 支持性 | 类型 | 备注 |
-| -------- | ------- | ------- | ------- |
-| OpenAI API | ✔    | 文本生成 | 也支持 DeepSeek、Gemini、Kimi、xAI 等兼容 OpenAI API 的服务 |
-| Claude API | ✔    | 文本生成 |  |
-| Google Gemini API | ✔    | 文本生成 |  |
-| Dify | ✔    | 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 | ✔    | 文本转语音 |  |
-| GSVI | ✔    | 文本转语音 | GPT-Sovits-Inference |
-| GPT-SoVITs | ✔    | 文本转语音 | GPT-Sovits-Inference |
-| FishAudio | ✔    | 文本转语音 | GPT-Sovits 作者参与的项目 |
-| Edge TTS | ✔    | 文本转语音 | Edge 浏览器的免费 TTS |
-| 阿里云百炼 TTS | ✔    | 文本转语音 |  |
-| Azure TTS | ✔    | 文本转语音 | Microsoft Azure TTS |
+**大模型服务**
 
+| 名称  | 支持性 | 备注 |
+| -------- | ------- | ------- |
+| OpenAI | ✔    | 支持任何兼容 OpenAI API 的服务 |
+| Anthropic | ✔    |  |
+| Google Gemini | ✔   |  |
+| Moonshot AI | ✔   |  |
+| 智谱 AI | ✔   |  |
+| DeepSeek | ✔   |  |
+| Ollama | ✔     | 本地部署 DeepSeek 等开源语言模型 |
+| LM Studio | ✔    | 本地部署 DeepSeek 等开源语言模型 |
+| [优云智算](https://www.compshare.cn/?ytag=GPU_YY-gh_astrbot&referral_code=FV7DcGowN4hB5UuXKgpE74) | ✔  |  |
+| [302.AI](https://share.302.ai/rr1M3l) | ✔   |  |
+| [小马算力](https://www.tokenpony.cn/3YPyf) | ✔   |  |
+| 硅基流动 | ✔    |  |
+| PPIO 派欧云 | ✔    |  |
+| ModelScope | ✔    |  |
+| OneAPI | ✔    |  |
+| Dify | ✔    |  |
+| 阿里云百炼应用 | ✔    |  |
+| Coze | ✔    |  |
+
+**语音转文本服务**
+
+| 名称  | 支持性 | 备注 |
+| -------- | ------- | ------- |
+| Whisper | ✔    | 支持 API、本地部署 |
+| SenseVoice | ✔   | 本地部署 |
+
+**文本转语音服务**
+
+| 名称  | 支持性 | 备注 |
+| -------- | ------- | ------- |
+| OpenAI TTS | ✔    |  |
+| Gemini TTS | ✔    |  |
+| GSVI | ✔    | GPT-Sovits-Inference |
+| GPT-SoVITs | ✔     | GPT-Sovits |
+| FishAudio | ✔    | |
+| Edge TTS | ✔    | Edge 浏览器的免费 TTS |
+| 阿里云百炼 TTS | ✔    |  |
+| Azure TTS | ✔   | |
+| Minimax TTS | ✔   | |
+| 火山引擎 TTS | ✔   | |
 
 ## ❤️ 贡献
 
@@ -185,39 +203,6 @@ pip install pre-commit
 pre-commit install
 ```
 
-## 🌟 支持
-
-- Star 这个项目！
-- 在[爱发电](https://afdian.com/a/soulter)支持我！
-
-## ✨ Demo
-
-<details><summary>👉 点击展开多张 Demo 截图 👈</summary>
-
-<div align='center'>
-
-<img src="https://github.com/user-attachments/assets/4ee688d9-467d-45c8-99d6-368f9a8a92d8" width="600">
-
-_✨基于 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/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/0cdbf564-2f59-4da5-b524-ce0e7ef3d978" width=600>
-
-_✨ WebUI ✨_
-
-</div>
-
-</details>
-
-
 ## ❤️ Special Thanks
 
 特别感谢所有 Contributors 和插件开发者对 AstrBot 的贡献 ❤️
@@ -226,24 +211,21 @@ _✨ WebUI ✨_
   <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] 
-> 如果本项目对您的生活 / 工作产生了帮助，或者您关注本项目的未来发展，请给项目 Star，这是我维护这个开源项目的动力 <3
+> 如果本项目对您的生活 / 工作产生了帮助，或者您关注本项目的未来发展，请给项目 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>
 
-![10k-star-banner-credit-by-kevin](https://github.com/user-attachments/assets/c97fc5fb-20b9-4bc8-9998-c20b930ab097)
-
+</details>
 
 _私は、高性能ですから!_
-

astrbot/api/__init__.py

@@ -3,5 +3,18 @@ from astrbot import logger
 from astrbot.core import html_renderer
 from astrbot.core import sp
 from astrbot.core.star.register import register_llm_tool as llm_tool
+from astrbot.core.star.register import register_agent as agent
+from astrbot.core.agent.tool import ToolSet, FunctionTool
+from astrbot.core.agent.tool_executor import BaseFunctionToolExecutor
 
-__all__ = ["AstrBotConfig", "logger", "html_renderer", "llm_tool", "sp"]
+__all__ = [
+    "AstrBotConfig",
+    "logger",
+    "html_renderer",
+    "llm_tool",
+    "agent",
+    "sp",
+    "ToolSet",
+    "FunctionTool",
+    "BaseFunctionToolExecutor",
+]

astrbot/api/event/filter/__init__.py

@@ -7,6 +7,7 @@ from astrbot.core.star.register import (
     register_permission_type as permission_type,
     register_custom_filter as custom_filter,
     register_on_astrbot_loaded as on_astrbot_loaded,
+    register_on_platform_loaded as on_platform_loaded,
     register_on_llm_request as on_llm_request,
     register_on_llm_response as on_llm_response,
     register_llm_tool as llm_tool,
@@ -41,6 +42,7 @@ __all__ = [
     "custom_filter",
     "PermissionType",
     "on_astrbot_loaded",
+    "on_platform_loaded",
     "on_llm_request",
     "llm_tool",
     "on_decorating_result",

astrbot/cli/utils/basic.py

@@ -37,7 +37,10 @@ async def check_dashboard(astrbot_root: Path) -> None:
                 ):
                     click.echo("正在安装管理面板...")
                     await download_dashboard(
-                        path="data/dashboard.zip", extract_path=str(astrbot_root)
+                        path="data/dashboard.zip",
+                        extract_path=str(astrbot_root),
+                        version=f"v{VERSION}",
+                        latest=False,
                     )
                     click.echo("管理面板安装完成")
 
@@ -50,7 +53,10 @@ async def check_dashboard(astrbot_root: Path) -> None:
                         version = dashboard_version.split("v")[1]
                         click.echo(f"管理面板版本: {version}")
                         await download_dashboard(
-                            path="data/dashboard.zip", extract_path=str(astrbot_root)
+                            path="data/dashboard.zip",
+                            extract_path=str(astrbot_root),
+                            version=f"v{VERSION}",
+                            latest=False,
                         )
                     except Exception as e:
                         click.echo(f"下载管理面板失败: {e}")
@@ -59,7 +65,10 @@ async def check_dashboard(astrbot_root: Path) -> None:
         click.echo("初始化管理面板目录...")
         try:
             await download_dashboard(
-                path=str(astrbot_root / "dashboard.zip"), extract_path=str(astrbot_root)
+                path=str(astrbot_root / "dashboard.zip"),
+                extract_path=str(astrbot_root),
+                version=f"v{VERSION}",
+                latest=False,
             )
             click.echo("管理面板初始化完成")
         except Exception as e:

astrbot/cli/utils/plugin.py

@@ -117,19 +117,24 @@ def build_plug_list(plugins_dir: Path) -> list:
             # 从 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),
-                })
+                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 = []
@@ -139,15 +144,17 @@ def build_plug_list(plugins_dir: Path) -> list:
             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,
-                })
+                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)
 

astrbot/core/__init__.py

@@ -1,5 +1,4 @@
 import os
-import asyncio
 from .log import LogManager, LogBroker  # noqa
 from astrbot.core.utils.t2i.renderer import HtmlRenderer
 from astrbot.core.utils.shared_preferences import SharedPreferences
@@ -21,7 +20,7 @@ html_renderer = HtmlRenderer(t2i_base_url)
 logger = LogManager.GetLogger(log_name="astrbot")
 db_helper = SQLiteDatabase(DB_PATH)
 # 简单的偏好设置存储, 这里后续应该存储到数据库中, 一些部分可以存储到配置中
-sp = SharedPreferences()
+sp = SharedPreferences(db_helper=db_helper)
 # 文件令牌服务
 file_token_service = FileTokenService()
 pip_installer = PipInstaller(

astrbot/core/agent/agent.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass
+from .tool import FunctionTool
+from typing import Generic
+from .run_context import TContext
+from .hooks import BaseAgentRunHooks
+
+
+@dataclass
+class Agent(Generic[TContext]):
+    name: str
+    instructions: str | None = None
+    tools: list[str | FunctionTool] | None = None
+    run_hooks: BaseAgentRunHooks[TContext] | None = None

astrbot/core/agent/handoff.py

@@ -0,0 +1,34 @@
+from typing import Generic
+from .tool import FunctionTool
+from .agent import Agent
+from .run_context import TContext
+
+
+class HandoffTool(FunctionTool, Generic[TContext]):
+    """Handoff tool for delegating tasks to another agent."""
+
+    def __init__(
+        self, agent: Agent[TContext], parameters: dict | None = None, **kwargs
+    ):
+        self.agent = agent
+        super().__init__(
+            name=f"transfer_to_{agent.name}",
+            parameters=parameters or self.default_parameters(),
+            description=agent.instructions or self.default_description(agent.name),
+            **kwargs,
+        )
+
+    def default_parameters(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "input": {
+                    "type": "string",
+                    "description": "The input to be handed off to another agent. This should be a clear and concise request or task.",
+                },
+            },
+        }
+
+    def default_description(self, agent_name: str | None) -> str:
+        agent_name = agent_name or "another"
+        return f"Delegate tasks to {self.name} agent to handle the request."

astrbot/core/agent/hooks.py

@@ -0,0 +1,27 @@
+import mcp
+from dataclasses import dataclass
+from .run_context import ContextWrapper, TContext
+from typing import Generic
+from astrbot.core.provider.entities import LLMResponse
+from astrbot.core.agent.tool import FunctionTool
+
+
+@dataclass
+class BaseAgentRunHooks(Generic[TContext]):
+    async def on_agent_begin(self, run_context: ContextWrapper[TContext]): ...
+    async def on_tool_start(
+        self,
+        run_context: ContextWrapper[TContext],
+        tool: FunctionTool,
+        tool_args: dict | None,
+    ): ...
+    async def on_tool_end(
+        self,
+        run_context: ContextWrapper[TContext],
+        tool: FunctionTool,
+        tool_args: dict | None,
+        tool_result: mcp.types.CallToolResult | None,
+    ): ...
+    async def on_agent_done(
+        self, run_context: ContextWrapper[TContext], llm_response: LLMResponse
+    ): ...

astrbot/core/agent/mcp_client.py

@@ -0,0 +1,224 @@
+import asyncio
+import logging
+from datetime import timedelta
+from typing import Optional
+from contextlib import AsyncExitStack
+from astrbot import logger
+from astrbot.core.utils.log_pipe import LogPipe
+
+try:
+    import mcp
+    from mcp.client.sse import sse_client
+except (ModuleNotFoundError, ImportError):
+    logger.warning("警告: 缺少依赖库 'mcp'，将无法使用 MCP 服务。")
+
+try:
+    from mcp.client.streamable_http import streamablehttp_client
+except (ModuleNotFoundError, ImportError):
+    logger.warning(
+        "警告: 缺少依赖库 'mcp' 或者 mcp 库版本过低，无法使用 Streamable HTTP 连接方式。"
+    )
+
+
+def _prepare_config(config: dict) -> dict:
+    """准备配置，处理嵌套格式"""
+    if "mcpServers" in config and config["mcpServers"]:
+        first_key = next(iter(config["mcpServers"]))
+        config = config["mcpServers"][first_key]
+    config.pop("active", None)
+    return config
+
+
+async def _quick_test_mcp_connection(config: dict) -> tuple[bool, str]:
+    """快速测试 MCP 服务器可达性"""
+    import aiohttp
+
+    cfg = _prepare_config(config.copy())
+
+    url = cfg["url"]
+    headers = cfg.get("headers", {})
+    timeout = cfg.get("timeout", 10)
+
+    try:
+        if "transport" in cfg:
+            transport_type = cfg["transport"]
+        elif "type" in cfg:
+            transport_type = cfg["type"]
+        else:
+            raise Exception("MCP 连接配置缺少 transport 或 type 字段")
+
+        async with aiohttp.ClientSession() as session:
+            if transport_type == "streamable_http":
+                test_payload = {
+                    "jsonrpc": "2.0",
+                    "method": "initialize",
+                    "id": 0,
+                    "params": {
+                        "protocolVersion": "2024-11-05",
+                        "capabilities": {},
+                        "clientInfo": {"name": "test-client", "version": "1.2.3"},
+                    },
+                }
+                async with session.post(
+                    url,
+                    headers={
+                        **headers,
+                        "Content-Type": "application/json",
+                        "Accept": "application/json, text/event-stream",
+                    },
+                    json=test_payload,
+                    timeout=aiohttp.ClientTimeout(total=timeout),
+                ) as response:
+                    if response.status == 200:
+                        return True, ""
+                    else:
+                        return False, f"HTTP {response.status}: {response.reason}"
+            else:
+                async with session.get(
+                    url,
+                    headers={
+                        **headers,
+                        "Accept": "application/json, text/event-stream",
+                    },
+                    timeout=aiohttp.ClientTimeout(total=timeout),
+                ) as response:
+                    if response.status == 200:
+                        return True, ""
+                    else:
+                        return False, f"HTTP {response.status}: {response.reason}"
+
+    except asyncio.TimeoutError:
+        return False, f"连接超时: {timeout}秒"
+    except Exception as e:
+        return False, f"{e!s}"
+
+
+class MCPClient:
+    def __init__(self):
+        # Initialize session and client objects
+        self.session: Optional[mcp.ClientSession] = None
+        self.exit_stack = AsyncExitStack()
+
+        self.name: str | None = None
+        self.active: bool = True
+        self.tools: list[mcp.Tool] = []
+        self.server_errlogs: list[str] = []
+        self.running_event = asyncio.Event()
+
+    async def connect_to_server(self, mcp_server_config: dict, name: str):
+        """连接到 MCP 服务器
+
+        如果 `url` 参数存在：
+            1. 当 transport 指定为 `streamable_http` 时，使用 Streamable HTTP 连接方式。
+            1. 当 transport 指定为 `sse` 时，使用 SSE 连接方式。
+            2. 如果没有指定，默认使用 SSE 的方式连接到 MCP 服务。
+
+        Args:
+            mcp_server_config (dict): Configuration for the MCP server. See https://modelcontextprotocol.io/quickstart/server
+        """
+        cfg = _prepare_config(mcp_server_config.copy())
+
+        def logging_callback(msg: str):
+            # 处理 MCP 服务的错误日志
+            print(f"MCP Server {name} Error: {msg}")
+            self.server_errlogs.append(msg)
+
+        if "url" in cfg:
+            success, error_msg = await _quick_test_mcp_connection(cfg)
+            if not success:
+                raise Exception(error_msg)
+
+            if "transport" in cfg:
+                transport_type = cfg["transport"]
+            elif "type" in cfg:
+                transport_type = cfg["type"]
+            else:
+                raise Exception("MCP 连接配置缺少 transport 或 type 字段")
+
+            if transport_type != "streamable_http":
+                # SSE transport method
+                self._streams_context = sse_client(
+                    url=cfg["url"],
+                    headers=cfg.get("headers", {}),
+                    timeout=cfg.get("timeout", 5),
+                    sse_read_timeout=cfg.get("sse_read_timeout", 60 * 5),
+                )
+                streams = await self.exit_stack.enter_async_context(
+                    self._streams_context
+                )
+
+                # Create a new client session
+                read_timeout = timedelta(seconds=cfg.get("session_read_timeout", 60))
+                self.session = await self.exit_stack.enter_async_context(
+                    mcp.ClientSession(
+                        *streams,
+                        read_timeout_seconds=read_timeout,
+                        logging_callback=logging_callback,  # type: ignore
+                    )
+                )
+            else:
+                timeout = timedelta(seconds=cfg.get("timeout", 30))
+                sse_read_timeout = timedelta(
+                    seconds=cfg.get("sse_read_timeout", 60 * 5)
+                )
+                self._streams_context = streamablehttp_client(
+                    url=cfg["url"],
+                    headers=cfg.get("headers", {}),
+                    timeout=timeout,
+                    sse_read_timeout=sse_read_timeout,
+                    terminate_on_close=cfg.get("terminate_on_close", True),
+                )
+                read_s, write_s, _ = await self.exit_stack.enter_async_context(
+                    self._streams_context
+                )
+
+                # Create a new client session
+                read_timeout = timedelta(seconds=cfg.get("session_read_timeout", 60))
+                self.session = await self.exit_stack.enter_async_context(
+                    mcp.ClientSession(
+                        read_stream=read_s,
+                        write_stream=write_s,
+                        read_timeout_seconds=read_timeout,
+                        logging_callback=logging_callback,  # type: ignore
+                    )
+                )
+
+        else:
+            server_params = mcp.StdioServerParameters(
+                **cfg,
+            )
+
+            def callback(msg: str):
+                # 处理 MCP 服务的错误日志
+                self.server_errlogs.append(msg)
+
+            stdio_transport = await self.exit_stack.enter_async_context(
+                mcp.stdio_client(
+                    server_params,
+                    errlog=LogPipe(
+                        level=logging.ERROR,
+                        logger=logger,
+                        identifier=f"MCPServer-{name}",
+                        callback=callback,
+                    ),  # type: ignore
+                ),
+            )
+
+            # Create a new client session
+            self.session = await self.exit_stack.enter_async_context(
+                mcp.ClientSession(*stdio_transport)
+            )
+        await self.session.initialize()
+
+    async def list_tools_and_save(self) -> mcp.ListToolsResult:
+        """List all tools from the server and save them to self.tools"""
+        if not self.session:
+            raise Exception("MCP Client is not initialized")
+        response = await self.session.list_tools()
+        self.tools = response.tools
+        return response
+
+    async def cleanup(self):
+        """Clean up resources"""
+        await self.exit_stack.aclose()
+        self.running_event.set()  # Set the running event to indicate cleanup is done

astrbot/core/agent/response.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass
+import typing as T
+from astrbot.core.message.message_event_result import MessageChain
+
+
+class AgentResponseData(T.TypedDict):
+    chain: MessageChain
+
+
+@dataclass
+class AgentResponse:
+    type: str
+    data: AgentResponseData

astrbot/core/agent/run_context.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+from typing import Any, Generic
+from typing_extensions import TypeVar
+
+from astrbot.core.platform.astr_message_event import AstrMessageEvent
+
+TContext = TypeVar("TContext", default=Any)
+
+
+@dataclass
+class ContextWrapper(Generic[TContext]):
+    """A context for running an agent, which can be used to pass additional data or state."""
+
+    context: TContext
+    event: AstrMessageEvent
+
+
+NoContext = ContextWrapper[None]

astrbot/core/agent/runners/__init__.py

@@ -0,0 +1,3 @@
+from .base import BaseAgentRunner
+
+__all__ = ["BaseAgentRunner"]

astrbot/core/agent/runners/base.py

@@ -1,32 +1,33 @@
 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
+from ..run_context import ContextWrapper, TContext
+from ..response import AgentResponse
+from ..hooks import BaseAgentRunHooks
+from ..tool_executor import BaseFunctionToolExecutor
+from astrbot.core.provider import Provider
+from astrbot.core.provider.entities import LLMResponse
 
 
 class AgentState(Enum):
-    """Agent 状态枚举"""
-    IDLE = auto()          # 初始状态
-    RUNNING = auto()       # 运行中
-    DONE = auto()          # 完成
-    ERROR = auto()         # 错误状态
+    """Defines the state of the agent."""
+
+    IDLE = auto()  # Initial state
+    RUNNING = auto()  # Currently processing
+    DONE = auto()  # Completed
+    ERROR = auto()  # Error state
 
 
-class AgentResponseData(T.TypedDict):
-    chain: MessageChain
-
-
-@dataclass
-class AgentResponse:
-    type: str
-    data: AgentResponseData
-
-
-class BaseAgentRunner:
+class BaseAgentRunner(T.Generic[TContext]):
     @abc.abstractmethod
-    async def reset(self) -> None:
+    async def reset(
+        self,
+        provider: Provider,
+        run_context: ContextWrapper[TContext],
+        tool_executor: BaseFunctionToolExecutor[TContext],
+        agent_hooks: BaseAgentRunHooks[TContext],
+        **kwargs: T.Any,
+    ) -> None:
         """
         Reset the agent to its initial state.
         This method should be called before starting a new run.

astrbot/core/agent/runners/tool_loop_agent_runner.py

@@ -1,10 +1,12 @@
 import sys
 import traceback
 import typing as T
-from .base import BaseAgentRunner, AgentResponse, AgentResponseData, AgentState
-from ...context import PipelineContext
+from .base import BaseAgentRunner, AgentResponse, AgentState
+from ..hooks import BaseAgentRunHooks
+from ..tool_executor import BaseFunctionToolExecutor
+from ..run_context import ContextWrapper, TContext
+from ..response import AgentResponseData
 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,
 )
@@ -21,8 +23,8 @@ from mcp.types import (
     EmbeddedResource,
     TextResourceContents,
     BlobResourceContents,
+    CallToolResult,
 )
-from astrbot.core.star.star_handler import EventType
 from astrbot import logger
 
 if sys.version_info >= (3, 12):
@@ -31,28 +33,25 @@ 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
-
+class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
     @override
-    async def reset(self, req: ProviderRequest, streaming: bool) -> None:
-        self.req = req
-        self.streaming = streaming
+    async def reset(
+        self,
+        provider: Provider,
+        request: ProviderRequest,
+        run_context: ContextWrapper[TContext],
+        tool_executor: BaseFunctionToolExecutor[TContext],
+        agent_hooks: BaseAgentRunHooks[TContext],
+        **kwargs: T.Any,
+    ) -> None:
+        self.req = request
+        self.streaming = kwargs.get("streaming", False)
+        self.provider = provider
         self.final_llm_resp = None
         self._state = AgentState.IDLE
+        self.tool_executor = tool_executor
+        self.agent_hooks = agent_hooks
+        self.run_context = run_context
 
     def _transition_state(self, new_state: AgentState) -> None:
         """转换 Agent 状态"""
@@ -78,6 +77,12 @@ class ToolLoopAgent(BaseAgentRunner):
         if not self.req:
             raise ValueError("Request is not set. Please call reset() first.")
 
+        if self._state == AgentState.IDLE:
+            try:
+                await self.agent_hooks.on_agent_begin(self.run_context)
+            except Exception as e:
+                logger.error(f"Error in on_agent_begin hook: {e}", exc_info=True)
+
         # 开始处理，转换到运行状态
         self._transition_state(AgentState.RUNNING)
         llm_resp_result = None
@@ -124,12 +129,10 @@ class ToolLoopAgent(BaseAgentRunner):
             # 如果没有工具调用，转换到完成状态
             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
+            try:
+                await self.agent_hooks.on_agent_done(self.run_context, llm_resp)
+            except Exception as e:
+                logger.error(f"Error in on_agent_done hook: {e}", exc_info=True)
 
         # 返回 LLM 结果
         if llm_resp.result_chain:
@@ -193,50 +196,47 @@ class ToolLoopAgent(BaseAgentRunner):
                 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}"
+                logger.info(f"使用工具：{func_tool_name}，参数：{func_tool_args}")
+
+                if not func_tool:
+                    logger.warning(f"未找到指定的工具: {func_tool_name}，将跳过。")
+                    tool_call_result_blocks.append(
+                        ToolCallMessageSegment(
+                            role="tool",
+                            tool_call_id=func_tool_id,
+                            content=f"error: 未找到工具 {func_tool_name}",
+                        )
                     )
-                    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):
+                    continue
+
+                try:
+                    await self.agent_hooks.on_tool_start(
+                        self.run_context, func_tool, func_tool_args
+                    )
+                except Exception as e:
+                    logger.error(f"Error in on_tool_start hook: {e}", exc_info=True)
+
+                executor = self.tool_executor.execute(
+                    tool=func_tool,
+                    run_context=self.run_context,
+                    **func_tool_args,
+                )
+
+                _final_resp: CallToolResult | None = None
+                async for resp in executor:  # type: ignore
+                    if isinstance(resp, CallToolResult):
+                        res = resp
+                        _final_resp = resp
+                        if isinstance(res.content[0], TextContent):
                             tool_call_result_blocks.append(
                                 ToolCallMessageSegment(
                                     role="tool",
                                     tool_call_id=func_tool_id,
-                                    content=resource.text,
+                                    content=res.content[0].text,
                                 )
                             )
-                            yield MessageChain().message(resource.text)
-                        elif (
-                            isinstance(resource, BlobResourceContents)
-                            and resource.mimeType
-                            and resource.mimeType.startswith("image/")
-                        ):
+                            yield MessageChain().message(res.content[0].text)
+                        elif isinstance(res.content[0], ImageContent):
                             tool_call_result_blocks.append(
                                 ToolCallMessageSegment(
                                     role="tool",
@@ -247,43 +247,65 @@ class ToolLoopAgent(BaseAgentRunner):
                             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"
+                        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(resource.blob)
+                            else:
+                                tool_call_result_blocks.append(
+                                    ToolCallMessageSegment(
+                                        role="tool",
+                                        tool_call_id=func_tool_id,
+                                        content="返回的数据类型不受支持",
+                                    )
+                                )
+                                yield MessageChain().message("返回的数据类型不受支持。")
 
-                self.event.clear_result()
+                    elif resp is None:
+                        # Tool 直接请求发送消息给用户
+                        # 这里我们将直接结束 Agent Loop。
+                        self._transition_state(AgentState.DONE)
+                        if res := self.run_context.event.get_result():
+                            if res.chain:
+                                yield MessageChain(
+                                    chain=res.chain, type="tool_direct_result"
+                                )
+                    else:
+                        # 不应该出现其他类型
+                        logger.warning(
+                            f"Tool 返回了不支持的类型: {type(resp)}，将忽略。"
+                        )
+
+                try:
+                    await self.agent_hooks.on_tool_end(
+                        self.run_context, func_tool, func_tool_args, _final_resp
+                    )
+                except Exception as e:
+                    logger.error(f"Error in on_tool_end hook: {e}", exc_info=True)
+
+                self.run_context.event.clear_result()
             except Exception as e:
                 logger.warning(traceback.format_exc())
                 tool_call_result_blocks.append(

astrbot/core/agent/tool.py

@@ -0,0 +1,267 @@
+from dataclasses import dataclass
+from deprecated import deprecated
+from typing import Awaitable, Callable, Literal, Any, Optional
+from .mcp_client import MCPClient
+
+
+@dataclass
+class FunctionTool:
+    """A class representing a function tool that can be used in function calling."""
+
+    name: str
+    parameters: dict | None = None
+    description: str | None = None
+    handler: Callable[..., Awaitable[Any]] | None = None
+    """处理函数, 当 origin 为 mcp 时，这个为空"""
+    handler_module_path: str | None = None
+    """处理函数的模块路径，当 origin 为 mcp 时，这个为空
+
+    必须要保留这个字段, handler 在初始化会被 functools.partial 包装，导致 handler 的 __module__ 为 functools
+    """
+    active: bool = True
+    """是否激活"""
+
+    origin: Literal["local", "mcp"] = "local"
+    """函数工具的来源, local 为本地函数工具, mcp 为 MCP 服务"""
+
+    # MCP 相关字段
+    mcp_server_name: str | None = None
+    """MCP 服务名称，当 origin 为 mcp 时有效"""
+    mcp_client: MCPClient | None = None
+    """MCP 客户端，当 origin 为 mcp 时有效"""
+
+    def __repr__(self):
+        return f"FuncTool(name={self.name}, parameters={self.parameters}, description={self.description}, active={self.active}, origin={self.origin})"
+
+    def __dict__(self) -> dict[str, Any]:
+        """将 FunctionTool 转换为字典格式"""
+        return {
+            "name": self.name,
+            "parameters": self.parameters,
+            "description": self.description,
+            "active": self.active,
+            "origin": self.origin,
+            "mcp_server_name": self.mcp_server_name,
+        }
+
+
+class ToolSet:
+    """A set of function tools that can be used in function calling.
+
+    This class provides methods to add, remove, and retrieve tools, as well as
+    convert the tools to different API formats (OpenAI, Anthropic, Google GenAI)."""
+
+    def __init__(self, tools: list[FunctionTool] | None = None):
+        self.tools: list[FunctionTool] = tools or []
+
+    def empty(self) -> bool:
+        """Check if the tool set is empty."""
+        return len(self.tools) == 0
+
+    def add_tool(self, tool: FunctionTool):
+        """Add a tool to the set."""
+        # 检查是否已存在同名工具
+        for i, existing_tool in enumerate(self.tools):
+            if existing_tool.name == tool.name:
+                self.tools[i] = tool
+                return
+        self.tools.append(tool)
+
+    def remove_tool(self, name: str):
+        """Remove a tool by its name."""
+        self.tools = [tool for tool in self.tools if tool.name != name]
+
+    def get_tool(self, name: str) -> Optional[FunctionTool]:
+        """Get a tool by its name."""
+        for tool in self.tools:
+            if tool.name == name:
+                return tool
+        return None
+
+    @deprecated(reason="Use add_tool() instead", version="4.0.0")
+    def add_func(
+        self,
+        name: str,
+        func_args: list,
+        desc: str,
+        handler: Callable[..., Awaitable[Any]],
+    ):
+        """Add a function tool to the set."""
+        params = {
+            "type": "object",  # hard-coded here
+            "properties": {},
+        }
+        for param in func_args:
+            params["properties"][param["name"]] = {
+                "type": param["type"],
+                "description": param["description"],
+            }
+        _func = FunctionTool(
+            name=name,
+            parameters=params,
+            description=desc,
+            handler=handler,
+        )
+        self.add_tool(_func)
+
+    @deprecated(reason="Use remove_tool() instead", version="4.0.0")
+    def remove_func(self, name: str):
+        """Remove a function tool by its name."""
+        self.remove_tool(name)
+
+    @deprecated(reason="Use get_tool() instead", version="4.0.0")
+    def get_func(self, name: str) -> FunctionTool | None:
+        """Get all function tools."""
+        return self.get_tool(name)
+
+    @property
+    def func_list(self) -> list[FunctionTool]:
+        """Get the list of function tools."""
+        return self.tools
+
+    def openai_schema(self, omit_empty_parameter_field: bool = False) -> list[dict]:
+        """Convert tools to OpenAI API function calling schema format."""
+        result = []
+        for tool in self.tools:
+            func_def = {
+                "type": "function",
+                "function": {
+                    "name": tool.name,
+                    "description": tool.description,
+                },
+            }
+
+            if (
+                tool.parameters
+                and tool.parameters.get("properties")
+                or not omit_empty_parameter_field
+            ):
+                func_def["function"]["parameters"] = tool.parameters
+
+            result.append(func_def)
+        return result
+
+    def anthropic_schema(self) -> list[dict]:
+        """Convert tools to Anthropic API format."""
+        result = []
+        for tool in self.tools:
+            input_schema = {"type": "object"}
+            if tool.parameters:
+                input_schema["properties"] = tool.parameters.get("properties", {})
+                input_schema["required"] = tool.parameters.get("required", [])
+            tool_def = {
+                "name": tool.name,
+                "description": tool.description,
+                "input_schema": input_schema,
+            }
+            result.append(tool_def)
+        return result
+
+    def google_schema(self) -> dict:
+        """Convert tools to Google GenAI API format."""
+
+        def convert_schema(schema: dict) -> dict:
+            """Convert schema to Gemini API format."""
+            supported_types = {
+                "string",
+                "number",
+                "integer",
+                "boolean",
+                "array",
+                "object",
+                "null",
+            }
+            supported_formats = {
+                "string": {"enum", "date-time"},
+                "integer": {"int32", "int64"},
+                "number": {"float", "double"},
+            }
+
+            if "anyOf" in schema:
+                return {"anyOf": [convert_schema(s) for s in schema["anyOf"]]}
+
+            result = {}
+
+            if "type" in schema and schema["type"] in supported_types:
+                result["type"] = schema["type"]
+                if "format" in schema and schema["format"] in supported_formats.get(
+                    result["type"], set()
+                ):
+                    result["format"] = schema["format"]
+            else:
+                result["type"] = "null"
+
+            support_fields = {
+                "title",
+                "description",
+                "enum",
+                "minimum",
+                "maximum",
+                "maxItems",
+                "minItems",
+                "nullable",
+                "required",
+            }
+            result.update({k: schema[k] for k in support_fields if k in schema})
+
+            if "properties" in schema:
+                properties = {}
+                for key, value in schema["properties"].items():
+                    prop_value = convert_schema(value)
+                    if "default" in prop_value:
+                        del prop_value["default"]
+                    properties[key] = prop_value
+
+                if properties:
+                    result["properties"] = properties
+
+            if "items" in schema:
+                result["items"] = convert_schema(schema["items"])
+
+            return result
+
+        tools = []
+        for tool in self.tools:
+            d = {
+                "name": tool.name,
+                "description": tool.description,
+            }
+            if tool.parameters:
+                d["parameters"] = convert_schema(tool.parameters)
+            tools.append(d)
+
+        declarations = {}
+        if tools:
+            declarations["function_declarations"] = tools
+        return declarations
+
+    @deprecated(reason="Use openai_schema() instead", version="4.0.0")
+    def get_func_desc_openai_style(self, omit_empty_parameter_field: bool = False):
+        return self.openai_schema(omit_empty_parameter_field)
+
+    @deprecated(reason="Use anthropic_schema() instead", version="4.0.0")
+    def get_func_desc_anthropic_style(self):
+        return self.anthropic_schema()
+
+    @deprecated(reason="Use google_schema() instead", version="4.0.0")
+    def get_func_desc_google_genai_style(self):
+        return self.google_schema()
+
+    def names(self) -> list[str]:
+        """获取所有工具的名称列表"""
+        return [tool.name for tool in self.tools]
+
+    def __len__(self):
+        return len(self.tools)
+
+    def __bool__(self):
+        return len(self.tools) > 0
+
+    def __iter__(self):
+        return iter(self.tools)
+
+    def __repr__(self):
+        return f"ToolSet(tools={self.tools})"
+
+    def __str__(self):
+        return f"ToolSet(tools={self.tools})"

astrbot/core/agent/tool_executor.py

@@ -0,0 +1,11 @@
+import mcp
+from typing import Any, Generic, AsyncGenerator
+from .run_context import TContext, ContextWrapper
+from .tool import FunctionTool
+
+
+class BaseFunctionToolExecutor(Generic[TContext]):
+    @classmethod
+    async def execute(
+        cls, tool: FunctionTool, run_context: ContextWrapper[TContext], **tool_args
+    ) -> AsyncGenerator[Any | mcp.types.CallToolResult, None]: ...

astrbot/core/astr_agent_context.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+from astrbot.core.provider import Provider
+from astrbot.core.provider.entities import ProviderRequest
+
+
+@dataclass
+class AstrAgentContext:
+    provider: Provider
+    first_provider_request: ProviderRequest
+    curr_provider_request: ProviderRequest
+    streaming: bool
+    tool_call_timeout: int = 60  # Default tool call timeout in seconds

astrbot/core/astrbot_config_mgr.py

@@ -0,0 +1,283 @@
+import os
+import uuid
+from astrbot.core import AstrBotConfig, logger
+from astrbot.core.utils.shared_preferences import SharedPreferences
+from astrbot.core.config.astrbot_config import ASTRBOT_CONFIG_PATH
+from astrbot.core.config.default import DEFAULT_CONFIG
+from astrbot.core.platform.message_session import MessageSession
+from astrbot.core.utils.astrbot_path import get_astrbot_config_path
+from typing import TypeVar, TypedDict
+
+_VT = TypeVar("_VT")
+
+
+class ConfInfo(TypedDict):
+    """Configuration information for a specific session or platform."""
+
+    id: str  # UUID of the configuration or "default"
+    umop: list[str]  # Unified Message Origin Pattern
+    name: str
+    path: str  # File name to the configuration file
+
+
+DEFAULT_CONFIG_CONF_INFO = ConfInfo(
+    id="default",
+    umop=["::"],
+    name="default",
+    path=ASTRBOT_CONFIG_PATH,
+)
+
+
+class AstrBotConfigManager:
+    """A class to manage the system configuration of AstrBot, aka ACM"""
+
+    def __init__(self, default_config: AstrBotConfig, sp: SharedPreferences):
+        self.sp = sp
+        self.confs: dict[str, AstrBotConfig] = {}
+        """uuid / "default" -> AstrBotConfig"""
+        self.confs["default"] = default_config
+        self.abconf_data = None
+        self._load_all_configs()
+
+    def _get_abconf_data(self) -> dict:
+        """获取所有的 abconf 数据"""
+        if self.abconf_data is None:
+            self.abconf_data = self.sp.get(
+                "abconf_mapping", {}, scope="global", scope_id="global"
+            )
+        return self.abconf_data
+
+    def _load_all_configs(self):
+        """Load all configurations from the shared preferences."""
+        abconf_data = self._get_abconf_data()
+        self.abconf_data = abconf_data
+        for uuid_, meta in abconf_data.items():
+            filename = meta["path"]
+            conf_path = os.path.join(get_astrbot_config_path(), filename)
+            if os.path.exists(conf_path):
+                conf = AstrBotConfig(config_path=conf_path)
+                self.confs[uuid_] = conf
+            else:
+                logger.warning(
+                    f"Config file {conf_path} for UUID {uuid_} does not exist, skipping."
+                )
+                continue
+
+    def _is_umo_match(self, p1: str, p2: str) -> bool:
+        """判断 p2 umo 是否逻辑包含于 p1 umo"""
+        p1_ls = p1.split(":")
+        p2_ls = p2.split(":")
+
+        if len(p1_ls) != 3 or len(p2_ls) != 3:
+            return False  # 非法格式
+
+        return all(p == "" or p == "*" or p == t for p, t in zip(p1_ls, p2_ls))
+
+    def _load_conf_mapping(self, umo: str | MessageSession) -> ConfInfo:
+        """获取指定 umo 的配置文件 uuid, 如果不存在则返回默认配置(返回 "default")
+
+        Returns:
+            ConfInfo: 包含配置文件的 uuid, 路径和名称等信息, 是一个 dict 类型
+        """
+        # uuid -> { "umop": list, "path": str, "name": str }
+        abconf_data = self._get_abconf_data()
+        if isinstance(umo, MessageSession):
+            umo = str(umo)
+        else:
+            try:
+                umo = str(MessageSession.from_str(umo))  # validate
+            except Exception:
+                return DEFAULT_CONFIG_CONF_INFO
+
+        for uuid_, meta in abconf_data.items():
+            for pattern in meta["umop"]:
+                if self._is_umo_match(pattern, umo):
+                    return ConfInfo(**meta, id=uuid_)
+
+        return DEFAULT_CONFIG_CONF_INFO
+
+    def _save_conf_mapping(
+        self,
+        abconf_path: str,
+        abconf_id: str,
+        umo_parts: list[str] | list[MessageSession],
+        abconf_name: str | None = None,
+    ) -> None:
+        """保存配置文件的映射关系"""
+        for part in umo_parts:
+            if isinstance(part, MessageSession):
+                part = str(part)
+            elif not isinstance(part, str):
+                raise ValueError(
+                    "umo_parts must be a list of strings or MessageSession instances"
+                )
+        abconf_data = self.sp.get(
+            "abconf_mapping", {}, scope="global", scope_id="global"
+        )
+        random_word = abconf_name or uuid.uuid4().hex[:8]
+        abconf_data[abconf_id] = {
+            "umop": umo_parts,
+            "path": abconf_path,
+            "name": random_word,
+        }
+        self.sp.put("abconf_mapping", abconf_data, scope="global", scope_id="global")
+        self.abconf_data = abconf_data
+
+    def get_conf(self, umo: str | MessageSession | None) -> AstrBotConfig:
+        """获取指定 umo 的配置文件。如果不存在，则 fallback 到默认配置文件。"""
+        if not umo:
+            return self.confs["default"]
+        if isinstance(umo, MessageSession):
+            umo = f"{umo.platform_id}:{umo.message_type}:{umo.session_id}"
+
+        uuid_ = self._load_conf_mapping(umo)["id"]
+
+        conf = self.confs.get(uuid_)
+        if not conf:
+            conf = self.confs["default"]  # default MUST exists
+
+        return conf
+
+    @property
+    def default_conf(self) -> AstrBotConfig:
+        """获取默认配置文件"""
+        return self.confs["default"]
+
+    def get_conf_info(self, umo: str | MessageSession) -> ConfInfo:
+        """获取指定 umo 的配置文件元数据"""
+        if isinstance(umo, MessageSession):
+            umo = f"{umo.platform_id}:{umo.message_type}:{umo.session_id}"
+
+        return self._load_conf_mapping(umo)
+
+    def get_conf_list(self) -> list[ConfInfo]:
+        """获取所有配置文件的元数据列表"""
+        conf_list = []
+        conf_list.append(DEFAULT_CONFIG_CONF_INFO)
+        abconf_mapping = self._get_abconf_data()
+        for uuid_, meta in abconf_mapping.items():
+            conf_list.append(ConfInfo(**meta, id=uuid_))
+        return conf_list
+
+    def create_conf(
+        self,
+        umo_parts: list[str] | list[MessageSession],
+        config: dict = DEFAULT_CONFIG,
+        name: str | None = None,
+    ) -> str:
+        """
+        umo 由三个部分组成 [platform_id]:[message_type]:[session_id]。
+
+        umo_parts 可以是 "::" (代表所有), 可以是 "[platform_id]::" (代表指定平台下的所有类型消息和会话)。
+        """
+        conf_uuid = str(uuid.uuid4())
+        conf_file_name = f"abconf_{conf_uuid}.json"
+        conf_path = os.path.join(get_astrbot_config_path(), conf_file_name)
+        conf = AstrBotConfig(config_path=conf_path, default_config=config)
+        conf.save_config()
+        self._save_conf_mapping(conf_file_name, conf_uuid, umo_parts, abconf_name=name)
+        self.confs[conf_uuid] = conf
+        return conf_uuid
+
+    def delete_conf(self, conf_id: str) -> bool:
+        """删除指定配置文件
+
+        Args:
+            conf_id: 配置文件的 UUID
+
+        Returns:
+            bool: 删除是否成功
+
+        Raises:
+            ValueError: 如果试图删除默认配置文件
+        """
+        if conf_id == "default":
+            raise ValueError("不能删除默认配置文件")
+
+        # 从映射中移除
+        abconf_data = self.sp.get(
+            "abconf_mapping", {}, scope="global", scope_id="global"
+        )
+        if conf_id not in abconf_data:
+            logger.warning(f"配置文件 {conf_id} 不存在于映射中")
+            return False
+
+        # 获取配置文件路径
+        conf_path = os.path.join(
+            get_astrbot_config_path(), abconf_data[conf_id]["path"]
+        )
+
+        # 删除配置文件
+        try:
+            if os.path.exists(conf_path):
+                os.remove(conf_path)
+                logger.info(f"已删除配置文件: {conf_path}")
+        except Exception as e:
+            logger.error(f"删除配置文件 {conf_path} 失败: {e}")
+            return False
+
+        # 从内存中移除
+        if conf_id in self.confs:
+            del self.confs[conf_id]
+
+        # 从映射中移除
+        del abconf_data[conf_id]
+        self.sp.put("abconf_mapping", abconf_data, scope="global", scope_id="global")
+        self.abconf_data = abconf_data
+
+        logger.info(f"成功删除配置文件 {conf_id}")
+        return True
+
+    def update_conf_info(
+        self, conf_id: str, name: str | None = None, umo_parts: list[str] | None = None
+    ) -> bool:
+        """更新配置文件信息
+
+        Args:
+            conf_id: 配置文件的 UUID
+            name: 新的配置文件名称 (可选)
+            umo_parts: 新的 UMO 部分列表 (可选)
+
+        Returns:
+            bool: 更新是否成功
+        """
+        if conf_id == "default":
+            raise ValueError("不能更新默认配置文件的信息")
+
+        abconf_data = self.sp.get(
+            "abconf_mapping", {}, scope="global", scope_id="global"
+        )
+        if conf_id not in abconf_data:
+            logger.warning(f"配置文件 {conf_id} 不存在于映射中")
+            return False
+
+        # 更新名称
+        if name is not None:
+            abconf_data[conf_id]["name"] = name
+
+        # 更新 UMO 部分
+        if umo_parts is not None:
+            # 验证 UMO 部分格式
+            for part in umo_parts:
+                if isinstance(part, MessageSession):
+                    part = str(part)
+                elif not isinstance(part, str):
+                    raise ValueError(
+                        "umo_parts must be a list of strings or MessageSession instances"
+                    )
+            abconf_data[conf_id]["umop"] = umo_parts
+
+        # 保存更新
+        self.sp.put("abconf_mapping", abconf_data, scope="global", scope_id="global")
+        self.abconf_data = abconf_data
+        logger.info(f"成功更新配置文件 {conf_id} 的信息")
+        return True
+
+    def g(
+        self, umo: str | None = None, key: str | None = None, default: _VT = None
+    ) -> _VT:
+        """获取配置项。umo 为 None 时使用默认配置"""
+        if umo is None:
+            return self.confs["default"].get(key, default)
+        conf = self.get_conf(umo)
+        return conf.get(key, default)

astrbot/core/conversation_mgr.py

@@ -5,40 +5,44 @@ AstrBot 会话-对话管理器, 维护两个本地存储, 其中一个是 json
 在一个会话中可以建立多个对话, 并且支持对话的切换和删除
 """
 
-import uuid
 import json
-import asyncio
 from astrbot.core import sp
 from typing import Dict, List
 from astrbot.core.db import BaseDatabase
-from astrbot.core.db.po import Conversation
+from astrbot.core.db.po import Conversation, ConversationV2
 
 
 class ConversationManager:
     """负责管理会话与 LLM 的对话，某个会话当前正在用哪个对话。"""
 
     def __init__(self, db_helper: BaseDatabase):
-        # session_conversations 字典记录会话ID-对话ID 映射关系
-        self.session_conversations: Dict[str, str] = sp.get("session_conversation", {})
+        self.session_conversations: Dict[str, str] = {}
         self.db = db_helper
         self.save_interval = 60  # 每 60 秒保存一次
-        self._start_periodic_save()
 
-    def _start_periodic_save(self):
-        """启动定时保存任务"""
-        asyncio.create_task(self._periodic_save())
+    def _convert_conv_from_v2_to_v1(self, conv_v2: ConversationV2) -> Conversation:
+        """将 ConversationV2 对象转换为 Conversation 对象"""
+        created_at = int(conv_v2.created_at.timestamp())
+        updated_at = int(conv_v2.updated_at.timestamp())
+        return Conversation(
+            platform_id=conv_v2.platform_id,
+            user_id=conv_v2.user_id,
+            cid=conv_v2.conversation_id,
+            history=json.dumps(conv_v2.content or []),
+            title=conv_v2.title,
+            persona_id=conv_v2.persona_id,
+            created_at=created_at,
+            updated_at=updated_at,
+        )
 
-    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:
+    async def new_conversation(
+        self,
+        unified_msg_origin: str,
+        platform_id: str | None = None,
+        content: list[dict] | None = None,
+        title: str | None = None,
+        persona_id: str | None = None,
+    ) -> str:
         """新建对话，并将当前会话的对话转移到新对话
 
         Args:
@@ -46,11 +50,23 @@ class ConversationManager:
         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
-        sp.put("session_conversation", self.session_conversations)
-        return conversation_id
+        if not platform_id:
+            # 如果没有提供 platform_id，则从 unified_msg_origin 中解析
+            parts = unified_msg_origin.split(":")
+            if len(parts) >= 3:
+                platform_id = parts[0]
+        if not platform_id:
+            platform_id = "unknown"
+        conv = await self.db.create_conversation(
+            user_id=unified_msg_origin,
+            platform_id=platform_id,
+            content=content,
+            title=title,
+            persona_id=persona_id,
+        )
+        self.session_conversations[unified_msg_origin] = conv.conversation_id
+        await sp.session_put(unified_msg_origin, "sel_conv_id", conv.conversation_id)
+        return conv.conversation_id
 
     async def switch_conversation(self, unified_msg_origin: str, conversation_id: str):
         """切换会话的对话
@@ -60,10 +76,10 @@ class ConversationManager:
             conversation_id (str): 对话 ID, 是 uuid 格式的字符串
         """
         self.session_conversations[unified_msg_origin] = conversation_id
-        sp.put("session_conversation", self.session_conversations)
+        await sp.session_put(unified_msg_origin, "sel_conv_id", conversation_id)
 
     async def delete_conversation(
-        self, unified_msg_origin: str, conversation_id: str = None
+        self, unified_msg_origin: str, conversation_id: str | None = None
     ):
         """删除会话的对话，当 conversation_id 为 None 时删除会话当前的对话
 
@@ -71,13 +87,26 @@ class ConversationManager:
             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 not conversation_id:
+            conversation_id = self.session_conversations.get(unified_msg_origin)
         if conversation_id:
-            self.db.delete_conversation(user_id=unified_msg_origin, cid=conversation_id)
-            del self.session_conversations[unified_msg_origin]
-            sp.put("session_conversation", self.session_conversations)
+            await self.db.delete_conversation(cid=conversation_id)
+            curr_cid = await self.get_curr_conversation_id(unified_msg_origin)
+            if curr_cid == conversation_id:
+                self.session_conversations.pop(unified_msg_origin, None)
+                await sp.session_remove(unified_msg_origin, "sel_conv_id")
 
-    async def get_curr_conversation_id(self, unified_msg_origin: str) -> str:
+    async def delete_conversations_by_user_id(self, unified_msg_origin: str):
+        """删除会话的所有对话
+
+        Args:
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+        """
+        await self.db.delete_conversations_by_user_id(user_id=unified_msg_origin)
+        self.session_conversations.pop(unified_msg_origin, None)
+        await sp.session_remove(unified_msg_origin, "sel_conv_id")
+
+    async def get_curr_conversation_id(self, unified_msg_origin: str) -> str | None:
         """获取会话当前的对话 ID
 
         Args:
@@ -85,14 +114,19 @@ class ConversationManager:
         Returns:
             conversation_id (str): 对话 ID, 是 uuid 格式的字符串
         """
-        return self.session_conversations.get(unified_msg_origin, None)
+        ret = self.session_conversations.get(unified_msg_origin, None)
+        if not ret:
+            ret = await sp.session_get(unified_msg_origin, "sel_conv_id", None)
+            if ret:
+                self.session_conversations[unified_msg_origin] = ret
+        return ret
 
     async def get_conversation(
         self,
         unified_msg_origin: str,
         conversation_id: str,
         create_if_not_exists: bool = False,
-    ) -> Conversation:
+    ) -> Conversation | None:
         """获取会话的对话
 
         Args:
@@ -101,27 +135,74 @@ class ConversationManager:
         Returns:
             conversation (Conversation): 对话对象
         """
-        conv = self.db.get_conversation_by_user_id(unified_msg_origin, conversation_id)
+        conv = await self.db.get_conversation_by_id(cid=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)
+            conv = await self.db.get_conversation_by_id(cid=conversation_id)
+        conv_res = None
+        if conv:
+            conv_res = self._convert_conv_from_v2_to_v1(conv)
+        return conv_res
 
-    async def get_conversations(self, unified_msg_origin: str) -> List[Conversation]:
-        """获取会话的所有对话
+    async def get_conversations(
+        self, unified_msg_origin: str | None = None, platform_id: str | None = None
+    ) -> List[Conversation]:
+        """获取对话列表
 
         Args:
-            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
+            unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id，可选
+            platform_id (str): 平台 ID, 可选参数, 用于过滤对话
         Returns:
             conversations (List[Conversation]): 对话对象列表
         """
-        return self.db.get_conversations(unified_msg_origin)
+        convs = await self.db.get_conversations(
+            user_id=unified_msg_origin, platform_id=platform_id
+        )
+        convs_res = []
+        for conv in convs:
+            conv_res = self._convert_conv_from_v2_to_v1(conv)
+            convs_res.append(conv_res)
+        return convs_res
+
+    async def get_filtered_conversations(
+        self,
+        page: int = 1,
+        page_size: int = 20,
+        platform_ids: list[str] | None = None,
+        search_query: str = "",
+        **kwargs,
+    ) -> tuple[list[Conversation], int]:
+        """获取过滤后的对话列表
+
+        Args:
+            page (int): 页码, 默认为 1
+            page_size (int): 每页大小, 默认为 20
+            platform_ids (list[str]): 平台 ID 列表, 可选
+            search_query (str): 搜索查询字符串, 可选
+        Returns:
+            conversations (list[Conversation]): 对话对象列表
+        """
+        convs, cnt = await self.db.get_filtered_conversations(
+            page=page,
+            page_size=page_size,
+            platform_ids=platform_ids,
+            search_query=search_query,
+            **kwargs,
+        )
+        convs_res = []
+        for conv in convs:
+            conv_res = self._convert_conv_from_v2_to_v1(conv)
+            convs_res.append(conv_res)
+        return convs_res, cnt
 
     async def update_conversation(
-        self, unified_msg_origin: str, conversation_id: str, history: List[Dict]
+        self,
+        unified_msg_origin: str,
+        conversation_id: str | None = None,
+        history: list[dict] | None = None,
+        title: str | None = None,
+        persona_id: str | None = None,
     ):
         """更新会话的对话
 
@@ -130,40 +211,55 @@ class ConversationManager:
             conversation_id (str): 对话 ID, 是 uuid 格式的字符串
             history (List[Dict]): 对话历史记录, 是一个字典列表, 每个字典包含 role 和 content 字段
         """
+        if not conversation_id:
+            # 如果没有提供 conversation_id，则获取当前的
+            conversation_id = await self.get_curr_conversation_id(unified_msg_origin)
         if conversation_id:
-            self.db.update_conversation(
-                user_id=unified_msg_origin,
+            await self.db.update_conversation(
                 cid=conversation_id,
-                history=json.dumps(history),
+                title=title,
+                persona_id=persona_id,
+                content=history,
             )
 
-    async def update_conversation_title(self, unified_msg_origin: str, title: str):
+    async def update_conversation_title(
+        self, unified_msg_origin: str, title: str, conversation_id: str | None = None
+    ):
         """更新会话的对话标题
 
         Args:
             unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
             title (str): 对话标题
+
+        Deprecated:
+            Use `update_conversation` with `title` parameter instead.
         """
-        conversation_id = self.session_conversations.get(unified_msg_origin)
-        if conversation_id:
-            self.db.update_conversation_title(
-                user_id=unified_msg_origin, cid=conversation_id, title=title
-            )
+        await self.update_conversation(
+            unified_msg_origin=unified_msg_origin,
+            conversation_id=conversation_id,
+            title=title,
+        )
 
     async def update_conversation_persona_id(
-        self, unified_msg_origin: str, persona_id: str
+        self,
+        unified_msg_origin: str,
+        persona_id: str,
+        conversation_id: str | None = None,
     ):
         """更新会话的对话 Persona ID
 
         Args:
             unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
             persona_id (str): 对话 Persona ID
+
+        Deprecated:
+            Use `update_conversation` with `persona_id` parameter instead.
         """
-        conversation_id = self.session_conversations.get(unified_msg_origin)
-        if conversation_id:
-            self.db.update_conversation_persona_id(
-                user_id=unified_msg_origin, cid=conversation_id, persona_id=persona_id
-            )
+        await self.update_conversation(
+            unified_msg_origin=unified_msg_origin,
+            conversation_id=conversation_id,
+            persona_id=persona_id,
+        )
 
     async def get_human_readable_context(
         self, unified_msg_origin, conversation_id, page=1, page_size=10

astrbot/core/core_lifecycle.py

@@ -15,20 +15,23 @@ import time
 import threading
 import os
 from .event_bus import EventBus
-from . import astrbot_config
+from . import astrbot_config, html_renderer
 from asyncio import Queue
 from typing import List
 from astrbot.core.pipeline.scheduler import PipelineScheduler, PipelineContext
 from astrbot.core.star import PluginManager
 from astrbot.core.platform.manager import PlatformManager
 from astrbot.core.star.context import Context
+from astrbot.core.persona_mgr import PersonaManager
 from astrbot.core.provider.manager import ProviderManager
 from astrbot.core import LogBroker
 from astrbot.core.db import BaseDatabase
 from astrbot.core.updator import AstrBotUpdator
-from astrbot.core import logger
+from astrbot.core import logger, sp
 from astrbot.core.config.default import VERSION
 from astrbot.core.conversation_mgr import ConversationManager
+from astrbot.core.platform_message_history_mgr import PlatformMessageHistoryManager
+from astrbot.core.astrbot_config_mgr import AstrBotConfigManager
 from astrbot.core.star.star_handler import star_handlers_registry, EventType
 from astrbot.core.star.star_handler import star_map
 
@@ -47,12 +50,23 @@ class AstrBotCoreLifecycle:
         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"
+        proxy_config = self.astrbot_config.get("http_proxy", "")
+        if proxy_config != "":
+            os.environ["https_proxy"] = proxy_config
+            os.environ["http_proxy"] = proxy_config
+            logger.debug(f"Using proxy: {proxy_config}")
+            # 设置 no_proxy
+            no_proxy_list = self.astrbot_config.get("no_proxy", [])
+            os.environ["no_proxy"] = ",".join(no_proxy_list)
+        else:
+            # 清空代理环境变量
+            if "https_proxy" in os.environ:
+                del os.environ["https_proxy"]
+            if "http_proxy" in os.environ:
+                del os.environ["http_proxy"]
+            if "no_proxy" in os.environ:
+                del os.environ["no_proxy"]
+            logger.debug("HTTP proxy cleared")
 
     async def initialize(self):
         """
@@ -66,11 +80,26 @@ class AstrBotCoreLifecycle:
         else:
             logger.setLevel(self.astrbot_config["log_level"])  # 设置日志级别
 
+        await self.db.initialize()
+
+        await html_renderer.initialize()
+
+        # 初始化 AstrBot 配置管理器
+        self.astrbot_config_mgr = AstrBotConfigManager(
+            default_config=self.astrbot_config, sp=sp
+        )
+
         # 初始化事件队列
         self.event_queue = Queue()
 
+        # 初始化人格管理器
+        self.persona_mgr = PersonaManager(self.db, self.astrbot_config_mgr)
+        await self.persona_mgr.initialize()
+
         # 初始化供应商管理器
-        self.provider_manager = ProviderManager(self.astrbot_config, self.db)
+        self.provider_manager = ProviderManager(
+            self.astrbot_config_mgr, self.db, self.persona_mgr
+        )
 
         # 初始化平台管理器
         self.platform_manager = PlatformManager(self.astrbot_config, self.event_queue)
@@ -78,6 +107,9 @@ class AstrBotCoreLifecycle:
         # 初始化对话管理器
         self.conversation_manager = ConversationManager(self.db)
 
+        # 初始化平台消息历史管理器
+        self.platform_message_history_manager = PlatformMessageHistoryManager(self.db)
+
         # 初始化提供给插件的上下文
         self.star_context = Context(
             self.event_queue,
@@ -86,6 +118,9 @@ class AstrBotCoreLifecycle:
             self.provider_manager,
             self.platform_manager,
             self.conversation_manager,
+            self.platform_message_history_manager,
+            self.persona_mgr,
+            self.astrbot_config_mgr,
         )
 
         # 初始化插件管理器
@@ -98,16 +133,16 @@ class AstrBotCoreLifecycle:
         await self.provider_manager.initialize()
 
         # 初始化消息事件流水线调度器
-        self.pipeline_scheduler = PipelineScheduler(
-            PipelineContext(self.astrbot_config, self.plugin_manager)
-        )
-        await self.pipeline_scheduler.initialize()
+
+        self.pipeline_scheduler_mapping = await self.load_pipeline_scheduler()
 
         # 初始化更新器
         self.astrbot_updator = AstrBotUpdator()
 
         # 初始化事件总线
-        self.event_bus = EventBus(self.event_queue, self.pipeline_scheduler)
+        self.event_bus = EventBus(
+            self.event_queue, self.pipeline_scheduler_mapping, self.astrbot_config_mgr
+        )
 
         # 记录启动时间
         self.start_time = int(time.time())
@@ -224,6 +259,39 @@ class AstrBotCoreLifecycle:
         platform_insts = self.platform_manager.get_insts()
         for platform_inst in platform_insts:
             tasks.append(
-                asyncio.create_task(platform_inst.run(), name=platform_inst.meta().name)
+                asyncio.create_task(
+                    platform_inst.run(),
+                    name=f"{platform_inst.meta().id}({platform_inst.meta().name})",
+                )
             )
         return tasks
+
+    async def load_pipeline_scheduler(self) -> dict[str, PipelineScheduler]:
+        """加载消息事件流水线调度器
+
+        Returns:
+            dict[str, PipelineScheduler]: 平台 ID 到流水线调度器的映射
+        """
+        mapping = {}
+        for conf_id, ab_config in self.astrbot_config_mgr.confs.items():
+            scheduler = PipelineScheduler(
+                PipelineContext(ab_config, self.plugin_manager, conf_id)
+            )
+            await scheduler.initialize()
+            mapping[conf_id] = scheduler
+        return mapping
+
+    async def reload_pipeline_scheduler(self, conf_id: str):
+        """重新加载消息事件流水线调度器
+
+        Returns:
+            dict[str, PipelineScheduler]: 平台 ID 到流水线调度器的映射
+        """
+        ab_config = self.astrbot_config_mgr.confs.get(conf_id)
+        if not ab_config:
+            raise ValueError(f"配置文件 {conf_id} 不存在")
+        scheduler = PipelineScheduler(
+            PipelineContext(ab_config, self.plugin_manager, conf_id)
+        )
+        await scheduler.initialize()
+        self.pipeline_scheduler_mapping[conf_id] = scheduler

astrbot/core/db/__init__.py

@@ -1,7 +1,20 @@
 import abc
+import datetime
+import typing as T
+from deprecated import deprecated
 from dataclasses import dataclass
-from typing import List, Dict, Any, Tuple
-from astrbot.core.db.po import Stats, LLMHistory, ATRIVision, Conversation
+from astrbot.core.db.po import (
+    Stats,
+    PlatformStat,
+    ConversationV2,
+    PlatformMessageHistory,
+    Attachment,
+    Persona,
+    Preference,
+)
+from contextlib import asynccontextmanager
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from sqlalchemy.orm import sessionmaker
 
 
 @dataclass
@@ -10,152 +23,278 @@ class BaseDatabase(abc.ABC):
     数据库基类
     """
 
+    DATABASE_URL = ""
+
     def __init__(self) -> None:
+        self.engine = create_async_engine(
+            self.DATABASE_URL,
+            echo=False,
+            future=True,
+        )
+        self.AsyncSessionLocal = sessionmaker(
+            self.engine, class_=AsyncSession, expire_on_commit=False
+        )
+
+    async def initialize(self):
+        """初始化数据库连接"""
         pass
 
-    def insert_base_metrics(self, metrics: dict):
-        """插入基础指标数据"""
-        self.insert_platform_metrics(metrics["platform_stats"])
-        self.insert_plugin_metrics(metrics["plugin_stats"])
-        self.insert_command_metrics(metrics["command_stats"])
-        self.insert_llm_metrics(metrics["llm_stats"])
-
-    @abc.abstractmethod
-    def insert_platform_metrics(self, metrics: dict):
-        """插入平台指标数据"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def insert_plugin_metrics(self, metrics: dict):
-        """插入插件指标数据"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def insert_command_metrics(self, metrics: dict):
-        """插入指令指标数据"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def insert_llm_metrics(self, metrics: dict):
-        """插入 LLM 指标数据"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def update_llm_history(self, session_id: str, content: str, provider_type: str):
-        """更新 LLM 历史记录。当不存在 session_id 时插入"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def get_llm_history(
-        self, session_id: str = None, provider_type: str = None
-    ) -> List[LLMHistory]:
-        """获取 LLM 历史记录, 如果 session_id 为 None, 返回所有"""
-        raise NotImplementedError
+    @asynccontextmanager
+    async def get_db(self) -> T.AsyncGenerator[AsyncSession, None]:
+        """Get a database session."""
+        if not self.inited:
+            await self.initialize()
+            self.inited = True
+        async with self.AsyncSessionLocal() as session:
+            yield session
 
+    @deprecated(version="4.0.0", reason="Use get_platform_stats instead")
     @abc.abstractmethod
     def get_base_stats(self, offset_sec: int = 86400) -> Stats:
         """获取基础统计数据"""
         raise NotImplementedError
 
+    @deprecated(version="4.0.0", reason="Use get_platform_stats instead")
     @abc.abstractmethod
     def get_total_message_count(self) -> int:
         """获取总消息数"""
         raise NotImplementedError
 
+    @deprecated(version="4.0.0", reason="Use get_platform_stats instead")
     @abc.abstractmethod
     def get_grouped_base_stats(self, offset_sec: int = 86400) -> Stats:
         """获取基础统计数据(合并)"""
         raise NotImplementedError
 
-    @abc.abstractmethod
-    def insert_atri_vision_data(self, vision_data: ATRIVision):
-        """插入 ATRI 视觉数据"""
-        raise NotImplementedError
+    # New methods in v4.0.0
 
     @abc.abstractmethod
-    def get_atri_vision_data(self) -> List[ATRIVision]:
-        """获取 ATRI 视觉数据"""
-        raise NotImplementedError
+    async def insert_platform_stats(
+        self,
+        platform_id: str,
+        platform_type: str,
+        count: int = 1,
+        timestamp: datetime.datetime | None = None,
+    ) -> None:
+        """Insert a new platform statistic record."""
+        ...
 
     @abc.abstractmethod
-    def get_atri_vision_data_by_path_or_id(
-        self, url_or_path: str, id: str
-    ) -> ATRIVision:
-        """通过 url 或 path 获取 ATRI 视觉数据"""
-        raise NotImplementedError
+    async def count_platform_stats(self) -> int:
+        """Count the number of platform statistics records."""
+        ...
 
     @abc.abstractmethod
-    def get_conversation_by_user_id(self, user_id: str, cid: str) -> Conversation:
-        """通过 user_id 和 cid 获取 Conversation"""
-        raise NotImplementedError
+    async def get_platform_stats(self, offset_sec: int = 86400) -> list[PlatformStat]:
+        """Get platform statistics within the specified offset in seconds and group by platform_id."""
+        ...
 
     @abc.abstractmethod
-    def new_conversation(self, user_id: str, cid: str):
-        """新建 Conversation"""
-        raise NotImplementedError
+    async def get_conversations(
+        self, user_id: str | None = None, platform_id: str | None = None
+    ) -> list[ConversationV2]:
+        """Get all conversations for a specific user and platform_id(optional).
 
-    @abc.abstractmethod
-    def get_conversations(self, user_id: str) -> List[Conversation]:
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def update_conversation(self, user_id: str, cid: str, history: str):
-        """更新 Conversation"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def delete_conversation(self, user_id: str, cid: str):
-        """删除 Conversation"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    def update_conversation_title(self, user_id: str, cid: str, title: str):
-        """更新 Conversation 标题"""
-        raise NotImplementedError
-
-    @abc.abstractmethod
-    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]: 返回一个元组，包含对话列表和总对话数
+        content is not included in the result.
         """
-        raise NotImplementedError
+        ...
 
     @abc.abstractmethod
-    def get_filtered_conversations(
+    async def get_conversation_by_id(self, cid: str) -> ConversationV2:
+        """Get a specific conversation by its ID."""
+        ...
+
+    @abc.abstractmethod
+    async def get_all_conversations(
+        self, page: int = 1, page_size: int = 20
+    ) -> list[ConversationV2]:
+        """Get all conversations with pagination."""
+        ...
+
+    @abc.abstractmethod
+    async 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]:
-        """获取筛选后的对话列表
+        platform_ids: list[str] | None = None,
+        search_query: str = "",
+        **kwargs,
+    ) -> tuple[list[ConversationV2], int]:
+        """Get conversations filtered by platform IDs and search query."""
+        ...
 
-        Args:
-            page: 页码
-            page_size: 每页数量
-            platforms: 平台筛选列表
-            message_types: 消息类型筛选列表
-            search_query: 搜索关键词
-            exclude_ids: 排除的用户ID列表
-            exclude_platforms: 排除的平台列表
+    @abc.abstractmethod
+    async def create_conversation(
+        self,
+        user_id: str,
+        platform_id: str,
+        content: list[dict] | None = None,
+        title: str | None = None,
+        persona_id: str | None = None,
+        cid: str | None = None,
+        created_at: datetime.datetime | None = None,
+        updated_at: datetime.datetime | None = None,
+    ) -> ConversationV2:
+        """Create a new conversation."""
+        ...
 
-        Returns:
-            Tuple[List[Dict[str, Any]], int]: 返回一个元组，包含对话列表和总对话数
-        """
-        raise NotImplementedError
+    @abc.abstractmethod
+    async def update_conversation(
+        self,
+        cid: str,
+        title: str | None = None,
+        persona_id: str | None = None,
+        content: list[dict] | None = None,
+    ) -> None:
+        """Update a conversation's history."""
+        ...
+
+    @abc.abstractmethod
+    async def delete_conversation(self, cid: str) -> None:
+        """Delete a conversation by its ID."""
+        ...
+
+    @abc.abstractmethod
+    async def delete_conversations_by_user_id(self, user_id: str) -> None:
+        """Delete all conversations for a specific user."""
+        ...
+
+    @abc.abstractmethod
+    async def insert_platform_message_history(
+        self,
+        platform_id: str,
+        user_id: str,
+        content: dict,
+        sender_id: str | None = None,
+        sender_name: str | None = None,
+    ) -> None:
+        """Insert a new platform message history record."""
+        ...
+
+    @abc.abstractmethod
+    async def delete_platform_message_offset(
+        self, platform_id: str, user_id: str, offset_sec: int = 86400
+    ) -> None:
+        """Delete platform message history records older than the specified offset."""
+        ...
+
+    @abc.abstractmethod
+    async def get_platform_message_history(
+        self,
+        platform_id: str,
+        user_id: str,
+        page: int = 1,
+        page_size: int = 20,
+    ) -> list[PlatformMessageHistory]:
+        """Get platform message history for a specific user."""
+        ...
+
+    @abc.abstractmethod
+    async def insert_attachment(
+        self,
+        path: str,
+        type: str,
+        mime_type: str,
+    ):
+        """Insert a new attachment record."""
+        ...
+
+    @abc.abstractmethod
+    async def get_attachment_by_id(self, attachment_id: str) -> Attachment:
+        """Get an attachment by its ID."""
+        ...
+
+    @abc.abstractmethod
+    async def insert_persona(
+        self,
+        persona_id: str,
+        system_prompt: str,
+        begin_dialogs: list[str] | None = None,
+        tools: list[str] | None = None,
+    ) -> Persona:
+        """Insert a new persona record."""
+        ...
+
+    @abc.abstractmethod
+    async def get_persona_by_id(self, persona_id: str) -> Persona:
+        """Get a persona by its ID."""
+        ...
+
+    @abc.abstractmethod
+    async def get_personas(self) -> list[Persona]:
+        """Get all personas for a specific bot."""
+        ...
+
+    @abc.abstractmethod
+    async def update_persona(
+        self,
+        persona_id: str,
+        system_prompt: str | None = None,
+        begin_dialogs: list[str] | None = None,
+        tools: list[str] | None = None,
+    ) -> Persona | None:
+        """Update a persona's system prompt or begin dialogs."""
+        ...
+
+    @abc.abstractmethod
+    async def delete_persona(self, persona_id: str) -> None:
+        """Delete a persona by its ID."""
+        ...
+
+    @abc.abstractmethod
+    async def insert_preference_or_update(
+        self, scope: str, scope_id: str, key: str, value: dict
+    ) -> Preference:
+        """Insert a new preference record."""
+        ...
+
+    @abc.abstractmethod
+    async def get_preference(self, scope: str, scope_id: str, key: str) -> Preference:
+        """Get a preference by scope ID and key."""
+        ...
+
+    @abc.abstractmethod
+    async def get_preferences(
+        self, scope: str, scope_id: str | None = None, key: str | None = None
+    ) -> list[Preference]:
+        """Get all preferences for a specific scope ID or key."""
+        ...
+
+    @abc.abstractmethod
+    async def remove_preference(self, scope: str, scope_id: str, key: str) -> None:
+        """Remove a preference by scope ID and key."""
+        ...
+
+    @abc.abstractmethod
+    async def clear_preferences(self, scope: str, scope_id: str) -> None:
+        """Clear all preferences for a specific scope ID."""
+        ...
+
+    # @abc.abstractmethod
+    # async def insert_llm_message(
+    #     self,
+    #     cid: str,
+    #     role: str,
+    #     content: list,
+    #     tool_calls: list = None,
+    #     tool_call_id: str = None,
+    #     parent_id: str = None,
+    # ) -> LLMMessage:
+    #     """Insert a new LLM message into the conversation."""
+    #     ...
+
+    # @abc.abstractmethod
+    # async def get_llm_messages(self, cid: str) -> list[LLMMessage]:
+    #     """Get all LLM messages for a specific conversation."""
+    #     ...
+
+    @abc.abstractmethod
+    async def get_session_conversations(
+        self,
+        page: int = 1,
+        page_size: int = 20,
+        search_query: str | None = None,
+        platform: str | None = None,
+    ) -> tuple[list[dict], int]:
+        """Get paginated session conversations with joined conversation and persona details, support search and platform filter."""
+        ...

astrbot/core/db/migration/helper.py

@@ -0,0 +1,64 @@
+import os
+from astrbot.core.utils.astrbot_path import get_astrbot_data_path
+from astrbot.core.db import BaseDatabase
+from astrbot.core.config import AstrBotConfig
+from astrbot.api import logger, sp
+from .migra_3_to_4 import (
+    migration_conversation_table,
+    migration_platform_table,
+    migration_webchat_data,
+    migration_persona_data,
+    migration_preferences,
+)
+
+
+async def check_migration_needed_v4(db_helper: BaseDatabase) -> bool:
+    """
+    检查是否需要进行数据库迁移
+    如果存在 data_v3.db 并且 preference 中没有 migration_done_v4，则需要进行迁移。
+    """
+    data_v3_exists = os.path.exists(get_astrbot_data_path())
+    if not data_v3_exists:
+        return False
+    migration_done = await db_helper.get_preference(
+        "global", "global", "migration_done_v4"
+    )
+    if migration_done:
+        return False
+    return True
+
+
+async def do_migration_v4(
+    db_helper: BaseDatabase,
+    platform_id_map: dict[str, dict[str, str]],
+    astrbot_config: AstrBotConfig,
+):
+    """
+    执行数据库迁移
+    迁移旧的 webchat_conversation 表到新的 conversation 表。
+    迁移旧的 platform 到新的 platform_stats 表。
+    """
+    if not await check_migration_needed_v4(db_helper):
+        return
+
+    logger.info("开始执行数据库迁移...")
+
+    # 执行会话表迁移
+    await migration_conversation_table(db_helper, platform_id_map)
+
+    # 执行人格数据迁移
+    await migration_persona_data(db_helper, astrbot_config)
+
+    # 执行 WebChat 数据迁移
+    await migration_webchat_data(db_helper, platform_id_map)
+
+    # 执行偏好设置迁移
+    await migration_preferences(db_helper, platform_id_map)
+
+    # 执行平台统计表迁移
+    await migration_platform_table(db_helper, platform_id_map)
+
+    # 标记迁移完成
+    await sp.put_async("global", "global", "migration_done_v4", True)
+
+    logger.info("数据库迁移完成。")

astrbot/core/db/migration/migra_3_to_4.py

@@ -0,0 +1,338 @@
+import json
+import datetime
+from .. import BaseDatabase
+from .sqlite_v3 import SQLiteDatabase as SQLiteV3DatabaseV3
+from .shared_preferences_v3 import sp as sp_v3
+from astrbot.core.config.default import DB_PATH
+from astrbot.api import logger, sp
+from astrbot.core.config import AstrBotConfig
+from astrbot.core.platform.astr_message_event import MessageSesion
+from sqlalchemy.ext.asyncio import AsyncSession
+from astrbot.core.db.po import ConversationV2, PlatformMessageHistory
+from sqlalchemy import text
+
+"""
+1. 迁移旧的 webchat_conversation 表到新的 conversation 表。
+2. 迁移旧的 platform 到新的 platform_stats 表。
+"""
+
+
+def get_platform_id(
+    platform_id_map: dict[str, dict[str, str]], old_platform_name: str
+) -> str:
+    return platform_id_map.get(
+        old_platform_name,
+        {"platform_id": old_platform_name, "platform_type": old_platform_name},
+    ).get("platform_id", old_platform_name)
+
+
+def get_platform_type(
+    platform_id_map: dict[str, dict[str, str]], old_platform_name: str
+) -> str:
+    return platform_id_map.get(
+        old_platform_name,
+        {"platform_id": old_platform_name, "platform_type": old_platform_name},
+    ).get("platform_type", old_platform_name)
+
+
+async def migration_conversation_table(
+    db_helper: BaseDatabase, platform_id_map: dict[str, dict[str, str]]
+):
+    db_helper_v3 = SQLiteV3DatabaseV3(
+        db_path=DB_PATH.replace("data_v4.db", "data_v3.db")
+    )
+    conversations, total_cnt = db_helper_v3.get_all_conversations(
+        page=1, page_size=10000000
+    )
+    logger.info(f"迁移 {total_cnt} 条旧的会话数据到新的表中...")
+
+    async with db_helper.get_db() as dbsession:
+        dbsession: AsyncSession
+        async with dbsession.begin():
+            for idx, conversation in enumerate(conversations):
+                if total_cnt > 0 and (idx + 1) % max(1, total_cnt // 10) == 0:
+                    progress = int((idx + 1) / total_cnt * 100)
+                    if progress % 10 == 0:
+                        logger.info(f"进度: {progress}% ({idx + 1}/{total_cnt})")
+                try:
+                    conv = db_helper_v3.get_conversation_by_user_id(
+                        user_id=conversation.get("user_id", "unknown"),
+                        cid=conversation.get("cid", "unknown"),
+                    )
+                    if not conv:
+                        logger.info(
+                            f"未找到该条旧会话对应的具体数据: {conversation}, 跳过。"
+                        )
+                    if ":" not in conv.user_id:
+                        continue
+                    session = MessageSesion.from_str(session_str=conv.user_id)
+                    platform_id = get_platform_id(
+                        platform_id_map, session.platform_name
+                    )
+                    session.platform_id = platform_id  # 更新平台名称为新的 ID
+                    conv_v2 = ConversationV2(
+                        user_id=str(session),
+                        content=json.loads(conv.history) if conv.history else [],
+                        platform_id=platform_id,
+                        title=conv.title,
+                        persona_id=conv.persona_id,
+                        conversation_id=conv.cid,
+                        created_at=datetime.datetime.fromtimestamp(conv.created_at),
+                        updated_at=datetime.datetime.fromtimestamp(conv.updated_at),
+                    )
+                    dbsession.add(conv_v2)
+                except Exception as e:
+                    logger.error(
+                        f"迁移旧会话 {conversation.get('cid', 'unknown')} 失败: {e}",
+                        exc_info=True,
+                    )
+    logger.info(f"成功迁移 {total_cnt} 条旧的会话数据到新表。")
+
+
+async def migration_platform_table(
+    db_helper: BaseDatabase, platform_id_map: dict[str, dict[str, str]]
+):
+    db_helper_v3 = SQLiteV3DatabaseV3(
+        db_path=DB_PATH.replace("data_v4.db", "data_v3.db")
+    )
+    secs_from_2023_4_10_to_now = (
+        datetime.datetime.now(datetime.timezone.utc)
+        - datetime.datetime(2023, 4, 10, tzinfo=datetime.timezone.utc)
+    ).total_seconds()
+    offset_sec = int(secs_from_2023_4_10_to_now)
+    logger.info(f"迁移旧平台数据，offset_sec: {offset_sec} 秒。")
+    stats = db_helper_v3.get_base_stats(offset_sec=offset_sec)
+    logger.info(f"迁移 {len(stats.platform)} 条旧的平台数据到新的表中...")
+    platform_stats_v3 = stats.platform
+
+    if not platform_stats_v3:
+        logger.info("没有找到旧平台数据，跳过迁移。")
+        return
+
+    first_time_stamp = platform_stats_v3[0].timestamp
+    end_time_stamp = platform_stats_v3[-1].timestamp
+    start_time = first_time_stamp - (first_time_stamp % 3600)  # 向下取整到小时
+    end_time = end_time_stamp + (3600 - (end_time_stamp % 3600))  # 向上取整到小时
+
+    idx = 0
+
+    async with db_helper.get_db() as dbsession:
+        dbsession: AsyncSession
+        async with dbsession.begin():
+            total_buckets = (end_time - start_time) // 3600
+            for bucket_idx, bucket_end in enumerate(range(start_time, end_time, 3600)):
+                if bucket_idx % 500 == 0:
+                    progress = int((bucket_idx + 1) / total_buckets * 100)
+                    logger.info(f"进度: {progress}% ({bucket_idx + 1}/{total_buckets})")
+                cnt = 0
+                while (
+                    idx < len(platform_stats_v3)
+                    and platform_stats_v3[idx].timestamp < bucket_end
+                ):
+                    cnt += platform_stats_v3[idx].count
+                    idx += 1
+                if cnt == 0:
+                    continue
+                platform_id = get_platform_id(
+                    platform_id_map, platform_stats_v3[idx].name
+                )
+                platform_type = get_platform_type(
+                    platform_id_map, platform_stats_v3[idx].name
+                )
+                try:
+                    await dbsession.execute(
+                        text("""
+                        INSERT INTO platform_stats (timestamp, platform_id, platform_type, count)
+                        VALUES (:timestamp, :platform_id, :platform_type, :count)
+                        ON CONFLICT(timestamp, platform_id, platform_type) DO UPDATE SET
+                            count = platform_stats.count + EXCLUDED.count
+                        """),
+                        {
+                            "timestamp": datetime.datetime.fromtimestamp(
+                                bucket_end, tz=datetime.timezone.utc
+                            ),
+                            "platform_id": platform_id,
+                            "platform_type": platform_type,
+                            "count": cnt,
+                        },
+                    )
+                except Exception:
+                    logger.error(
+                        f"迁移平台统计数据失败: {platform_id}, {platform_type}, 时间戳: {bucket_end}",
+                        exc_info=True,
+                    )
+    logger.info(f"成功迁移 {len(platform_stats_v3)} 条旧的平台数据到新表。")
+
+
+async def migration_webchat_data(
+    db_helper: BaseDatabase, platform_id_map: dict[str, dict[str, str]]
+):
+    """迁移 WebChat 的历史记录到新的 PlatformMessageHistory 表中"""
+    db_helper_v3 = SQLiteV3DatabaseV3(
+        db_path=DB_PATH.replace("data_v4.db", "data_v3.db")
+    )
+    conversations, total_cnt = db_helper_v3.get_all_conversations(
+        page=1, page_size=10000000
+    )
+    logger.info(f"迁移 {total_cnt} 条旧的 WebChat 会话数据到新的表中...")
+
+    async with db_helper.get_db() as dbsession:
+        dbsession: AsyncSession
+        async with dbsession.begin():
+            for idx, conversation in enumerate(conversations):
+                if total_cnt > 0 and (idx + 1) % max(1, total_cnt // 10) == 0:
+                    progress = int((idx + 1) / total_cnt * 100)
+                    if progress % 10 == 0:
+                        logger.info(f"进度: {progress}% ({idx + 1}/{total_cnt})")
+                try:
+                    conv = db_helper_v3.get_conversation_by_user_id(
+                        user_id=conversation.get("user_id", "unknown"),
+                        cid=conversation.get("cid", "unknown"),
+                    )
+                    if not conv:
+                        logger.info(
+                            f"未找到该条旧会话对应的具体数据: {conversation}, 跳过。"
+                        )
+                    if ":" in conv.user_id:
+                        continue
+                    platform_id = "webchat"
+                    history = json.loads(conv.history) if conv.history else []
+                    for msg in history:
+                        type_ = msg.get("type")  # user type, "bot" or "user"
+                        new_history = PlatformMessageHistory(
+                            platform_id=platform_id,
+                            user_id=conv.cid,  # we use conv.cid as user_id for webchat
+                            content=msg,
+                            sender_id=type_,
+                            sender_name=type_,
+                        )
+                        dbsession.add(new_history)
+
+                except Exception:
+                    logger.error(
+                        f"迁移旧 WebChat 会话 {conversation.get('cid', 'unknown')} 失败",
+                        exc_info=True,
+                    )
+
+    logger.info(f"成功迁移 {total_cnt} 条旧的 WebChat 会话数据到新表。")
+
+
+async def migration_persona_data(
+    db_helper: BaseDatabase, astrbot_config: AstrBotConfig
+):
+    """
+    迁移 Persona 数据到新的表中。
+    旧的 Persona 数据存储在 preference 中，新的 Persona 数据存储在 persona 表中。
+    """
+    v3_persona_config: list[dict] = astrbot_config.get("persona", [])
+    total_personas = len(v3_persona_config)
+    logger.info(f"迁移 {total_personas} 个 Persona 配置到新表中...")
+
+    for idx, persona in enumerate(v3_persona_config):
+        if total_personas > 0 and (idx + 1) % max(1, total_personas // 10) == 0:
+            progress = int((idx + 1) / total_personas * 100)
+            if progress % 10 == 0:
+                logger.info(f"进度: {progress}% ({idx + 1}/{total_personas})")
+        try:
+            begin_dialogs = persona.get("begin_dialogs", [])
+            mood_imitation_dialogs = persona.get("mood_imitation_dialogs", [])
+            mood_prompt = ""
+            user_turn = True
+            for mood_dialog in mood_imitation_dialogs:
+                if user_turn:
+                    mood_prompt += f"A: {mood_dialog}\n"
+                else:
+                    mood_prompt += f"B: {mood_dialog}\n"
+                user_turn = not user_turn
+            system_prompt = persona.get("prompt", "")
+            if mood_prompt:
+                system_prompt += f"Here are few shots of dialogs, you need to imitate the tone of 'B' in the following dialogs to respond:\n {mood_prompt}"
+            persona_new = await db_helper.insert_persona(
+                persona_id=persona["name"],
+                system_prompt=system_prompt,
+                begin_dialogs=begin_dialogs,
+            )
+            logger.info(
+                f"迁移 Persona {persona['name']}({persona_new.system_prompt[:30]}...) 到新表成功。"
+            )
+        except Exception as e:
+            logger.error(f"解析 Persona 配置失败：{e}")
+
+
+async def migration_preferences(
+    db_helper: BaseDatabase, platform_id_map: dict[str, dict[str, str]]
+):
+    # 1. global scope migration
+    keys = [
+        "inactivated_llm_tools",
+        "inactivated_plugins",
+        "curr_provider",
+        "curr_provider_tts",
+        "curr_provider_stt",
+        "alter_cmd",
+    ]
+    for key in keys:
+        value = sp_v3.get(key)
+        if value is not None:
+            await sp.put_async("global", "global", key, value)
+            logger.info(f"迁移全局偏好设置 {key} 成功，值: {value}")
+
+    # 2. umo scope migration
+    session_conversation = sp_v3.get("session_conversation", default={})
+    for umo, conversation_id in session_conversation.items():
+        if not umo or not conversation_id:
+            continue
+        try:
+            session = MessageSesion.from_str(session_str=umo)
+            platform_id = get_platform_id(platform_id_map, session.platform_name)
+            session.platform_id = platform_id
+            await sp.put_async("umo", str(session), "sel_conv_id", conversation_id)
+            logger.info(f"迁移会话 {umo} 的对话数据到新表成功，平台 ID: {platform_id}")
+        except Exception as e:
+            logger.error(f"迁移会话 {umo} 的对话数据失败: {e}", exc_info=True)
+
+    session_service_config = sp_v3.get("session_service_config", default={})
+    for umo, config in session_service_config.items():
+        if not umo or not config:
+            continue
+        try:
+            session = MessageSesion.from_str(session_str=umo)
+            platform_id = get_platform_id(platform_id_map, session.platform_name)
+            session.platform_id = platform_id
+
+            await sp.put_async("umo", str(session), "session_service_config", config)
+
+            logger.info(f"迁移会话 {umo} 的服务配置到新表成功，平台 ID: {platform_id}")
+        except Exception as e:
+            logger.error(f"迁移会话 {umo} 的服务配置失败: {e}", exc_info=True)
+
+    session_variables = sp_v3.get("session_variables", default={})
+    for umo, variables in session_variables.items():
+        if not umo or not variables:
+            continue
+        try:
+            session = MessageSesion.from_str(session_str=umo)
+            platform_id = get_platform_id(platform_id_map, session.platform_name)
+            session.platform_id = platform_id
+            await sp.put_async("umo", str(session), "session_variables", variables)
+        except Exception as e:
+            logger.error(f"迁移会话 {umo} 的变量失败: {e}", exc_info=True)
+
+    session_provider_perf = sp_v3.get("session_provider_perf", default={})
+    for umo, perf in session_provider_perf.items():
+        if not umo or not perf:
+            continue
+        try:
+            session = MessageSesion.from_str(session_str=umo)
+            platform_id = get_platform_id(platform_id_map, session.platform_name)
+            session.platform_id = platform_id
+
+            for provider_type, provider_id in perf.items():
+                await sp.put_async(
+                    "umo", str(session), f"provider_perf_{provider_type}", provider_id
+                )
+            logger.info(
+                f"迁移会话 {umo} 的提供商偏好到新表成功，平台 ID: {platform_id}"
+            )
+        except Exception as e:
+            logger.error(f"迁移会话 {umo} 的提供商偏好失败: {e}", exc_info=True)

astrbot/core/db/migration/shared_preferences_v3.py

@@ -0,0 +1,47 @@
+import json
+import os
+from typing import TypeVar
+from astrbot.core.utils.astrbot_path import get_astrbot_data_path
+
+_VT = TypeVar("_VT")
+
+
+class SharedPreferences:
+    def __init__(self, path=None):
+        if path is None:
+            path = os.path.join(get_astrbot_data_path(), "shared_preferences.json")
+        self.path = path
+        self._data = self._load_preferences()
+
+    def _load_preferences(self):
+        if os.path.exists(self.path):
+            try:
+                with open(self.path, "r") as f:
+                    return json.load(f)
+            except json.JSONDecodeError:
+                os.remove(self.path)
+        return {}
+
+    def _save_preferences(self):
+        with open(self.path, "w") as f:
+            json.dump(self._data, f, indent=4, ensure_ascii=False)
+            f.flush()
+
+    def get(self, key, default: _VT = None) -> _VT:
+        return self._data.get(key, default)
+
+    def put(self, key, value):
+        self._data[key] = value
+        self._save_preferences()
+
+    def remove(self, key):
+        if key in self._data:
+            del self._data[key]
+            self._save_preferences()
+
+    def clear(self):
+        self._data.clear()
+        self._save_preferences()
+
+
+sp = SharedPreferences()

astrbot/core/db/migration/sqlite_v3.py

@@ -0,0 +1,494 @@
+import sqlite3
+import time
+from astrbot.core.db.po import Platform, Stats
+from typing import Tuple, List, Dict, Any
+from dataclasses import dataclass
+
+
+@dataclass
+class Conversation:
+    """LLM 对话存储
+
+    对于网页聊天，history 存储了包括指令、回复、图片等在内的所有消息。
+    对于其他平台的聊天，不存储非 LLM 的回复（因为考虑到已经存储在各自的平台上）。
+    """
+
+    user_id: str
+    cid: str
+    history: str = ""
+    """字符串格式的列表。"""
+    created_at: int = 0
+    updated_at: int = 0
+    title: str = ""
+    persona_id: str = ""
+
+
+INIT_SQL = """
+CREATE TABLE IF NOT EXISTS platform(
+    name VARCHAR(32),
+    count INTEGER,
+    timestamp INTEGER
+);
+CREATE TABLE IF NOT EXISTS llm(
+    name VARCHAR(32),
+    count INTEGER,
+    timestamp INTEGER
+);
+CREATE TABLE IF NOT EXISTS plugin(
+    name VARCHAR(32),
+    count INTEGER,
+    timestamp INTEGER
+);
+CREATE TABLE IF NOT EXISTS command(
+    name VARCHAR(32),
+    count INTEGER,
+    timestamp INTEGER
+);
+CREATE TABLE IF NOT EXISTS llm_history(
+    provider_type VARCHAR(32),
+    session_id VARCHAR(32),
+    content TEXT
+);
+
+-- ATRI
+CREATE TABLE IF NOT EXISTS atri_vision(
+    id TEXT,
+    url_or_path TEXT,
+    caption TEXT,
+    is_meme BOOLEAN,
+    keywords TEXT,
+    platform_name VARCHAR(32),
+    session_id VARCHAR(32),
+    sender_nickname VARCHAR(32),
+    timestamp INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS webchat_conversation(
+    user_id TEXT, -- 会话 id
+    cid TEXT, -- 对话 id
+    history TEXT,
+    created_at INTEGER,
+    updated_at INTEGER,
+    title TEXT,
+    persona_id TEXT
+);
+
+PRAGMA encoding = 'UTF-8';
+"""
+
+
+class SQLiteDatabase:
+    def __init__(self, db_path: str) -> None:
+        super().__init__()
+        self.db_path = db_path
+
+        sql = INIT_SQL
+
+        # 初始化数据库
+        self.conn = self._get_conn(self.db_path)
+        c = self.conn.cursor()
+        c.executescript(sql)
+        self.conn.commit()
+
+        # 检查 webchat_conversation 的 title 字段是否存在
+        c.execute(
+            """
+            PRAGMA table_info(webchat_conversation)
+            """
+        )
+        res = c.fetchall()
+        has_title = False
+        has_persona_id = False
+        for row in res:
+            if row[1] == "title":
+                has_title = True
+            if row[1] == "persona_id":
+                has_persona_id = True
+        if not has_title:
+            c.execute(
+                """
+                ALTER TABLE webchat_conversation ADD COLUMN title TEXT;
+                """
+            )
+            self.conn.commit()
+        if not has_persona_id:
+            c.execute(
+                """
+                ALTER TABLE webchat_conversation ADD COLUMN persona_id TEXT;
+                """
+            )
+            self.conn.commit()
+
+        c.close()
+
+    def _get_conn(self, db_path: str) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.db_path)
+        conn.text_factory = str
+        return conn
+
+    def _exec_sql(self, sql: str, params: Tuple = None):
+        conn = self.conn
+        try:
+            c = self.conn.cursor()
+        except sqlite3.ProgrammingError:
+            conn = self._get_conn(self.db_path)
+            c = conn.cursor()
+
+        if params:
+            c.execute(sql, params)
+            c.close()
+        else:
+            c.execute(sql)
+            c.close()
+
+        conn.commit()
+
+    def insert_platform_metrics(self, metrics: dict):
+        for k, v in metrics.items():
+            self._exec_sql(
+                """
+                INSERT INTO platform(name, count, timestamp) VALUES (?, ?, ?)
+                """,
+                (k, v, int(time.time())),
+            )
+
+    def insert_llm_metrics(self, metrics: dict):
+        for k, v in metrics.items():
+            self._exec_sql(
+                """
+                INSERT INTO llm(name, count, timestamp) VALUES (?, ?, ?)
+                """,
+                (k, v, int(time.time())),
+            )
+
+    def get_base_stats(self, offset_sec: int = 86400) -> Stats:
+        """获取 offset_sec 秒前到现在的基础统计数据"""
+        where_clause = f" WHERE timestamp >= {int(time.time()) - offset_sec}"
+
+        try:
+            c = self.conn.cursor()
+        except sqlite3.ProgrammingError:
+            c = self._get_conn(self.db_path).cursor()
+
+        c.execute(
+            """
+            SELECT * FROM platform
+            """
+            + where_clause
+        )
+
+        platform = []
+        for row in c.fetchall():
+            platform.append(Platform(*row))
+
+        c.close()
+
+        return Stats(platform=platform)
+
+    def get_total_message_count(self) -> int:
+        try:
+            c = self.conn.cursor()
+        except sqlite3.ProgrammingError:
+            c = self._get_conn(self.db_path).cursor()
+
+        c.execute(
+            """
+            SELECT SUM(count) FROM platform
+            """
+        )
+        res = c.fetchone()
+        c.close()
+        return res[0]
+
+    def get_grouped_base_stats(self, offset_sec: int = 86400) -> Stats:
+        """获取 offset_sec 秒前到现在的基础统计数据(合并)"""
+        where_clause = f" WHERE timestamp >= {int(time.time()) - offset_sec}"
+
+        try:
+            c = self.conn.cursor()
+        except sqlite3.ProgrammingError:
+            c = self._get_conn(self.db_path).cursor()
+
+        c.execute(
+            """
+            SELECT name, SUM(count), timestamp FROM platform
+            """
+            + where_clause
+            + " GROUP BY name"
+        )
+
+        platform = []
+        for row in c.fetchall():
+            platform.append(Platform(*row))
+
+        c.close()
+
+        return Stats(platform, [], [])
+
+    def get_conversation_by_user_id(self, user_id: str, cid: str) -> Conversation:
+        try:
+            c = self.conn.cursor()
+        except sqlite3.ProgrammingError:
+            c = self._get_conn(self.db_path).cursor()
+
+        c.execute(
+            """
+            SELECT * FROM webchat_conversation WHERE user_id = ? AND cid = ?
+            """,
+            (user_id, cid),
+        )
+
+        res = c.fetchone()
+        c.close()
+
+        if not res:
+            return
+
+        return Conversation(*res)
+
+    def new_conversation(self, user_id: str, cid: str):
+        history = "[]"
+        updated_at = int(time.time())
+        created_at = updated_at
+        self._exec_sql(
+            """
+            INSERT INTO webchat_conversation(user_id, cid, history, updated_at, created_at) VALUES (?, ?, ?, ?, ?)
+            """,
+            (user_id, cid, history, updated_at, created_at),
+        )
+
+    def get_conversations(self, user_id: str) -> Tuple:
+        try:
+            c = self.conn.cursor()
+        except sqlite3.ProgrammingError:
+            c = self._get_conn(self.db_path).cursor()
+
+        c.execute(
+            """
+            SELECT cid, created_at, updated_at, title, persona_id FROM webchat_conversation WHERE user_id = ? ORDER BY updated_at DESC
+            """,
+            (user_id,),
+        )
+
+        res = c.fetchall()
+        c.close()
+        conversations = []
+        for row in res:
+            cid = row[0]
+            created_at = row[1]
+            updated_at = row[2]
+            title = row[3]
+            persona_id = row[4]
+            conversations.append(
+                Conversation("", cid, "[]", created_at, updated_at, title, persona_id)
+            )
+        return conversations
+
+    def update_conversation(self, user_id: str, cid: str, history: str):
+        """更新对话，并且同时更新时间"""
+        updated_at = int(time.time())
+        self._exec_sql(
+            """
+            UPDATE webchat_conversation SET history = ?, updated_at = ? WHERE user_id = ? AND cid = ?
+            """,
+            (history, updated_at, user_id, cid),
+        )
+
+    def update_conversation_title(self, user_id: str, cid: str, title: str):
+        self._exec_sql(
+            """
+            UPDATE webchat_conversation SET title = ? WHERE user_id = ? AND cid = ?
+            """,
+            (title, user_id, cid),
+        )
+
+    def update_conversation_persona_id(self, user_id: str, cid: str, persona_id: str):
+        self._exec_sql(
+            """
+            UPDATE webchat_conversation SET persona_id = ? WHERE user_id = ? AND cid = ?
+            """,
+            (persona_id, user_id, cid),
+        )
+
+    def delete_conversation(self, user_id: str, cid: str):
+        self._exec_sql(
+            """
+            DELETE FROM webchat_conversation WHERE user_id = ? AND cid = ?
+            """,
+            (user_id, cid),
+        )
+
+    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/po.py

@@ -1,7 +1,237 @@
-"""指标数据"""
+import uuid
 
+from datetime import datetime, timezone
 from dataclasses import dataclass, field
-from typing import List
+from sqlmodel import (
+    SQLModel,
+    Text,
+    JSON,
+    UniqueConstraint,
+    Field,
+)
+from typing import Optional, TypedDict
+
+
+class PlatformStat(SQLModel, table=True):
+    """This class represents the statistics of bot usage across different platforms.
+
+    Note: In astrbot v4, we moved `platform` table to here.
+    """
+
+    __tablename__ = "platform_stats"
+
+    id: int = Field(primary_key=True, sa_column_kwargs={"autoincrement": True})
+    timestamp: datetime = Field(nullable=False)
+    platform_id: str = Field(nullable=False)
+    platform_type: str = Field(nullable=False)  # such as "aiocqhttp", "slack", etc.
+    count: int = Field(default=0, nullable=False)
+
+    __table_args__ = (
+        UniqueConstraint(
+            "timestamp",
+            "platform_id",
+            "platform_type",
+            name="uix_platform_stats",
+        ),
+    )
+
+
+class ConversationV2(SQLModel, table=True):
+    __tablename__ = "conversations"
+
+    inner_conversation_id: int = Field(
+        primary_key=True, sa_column_kwargs={"autoincrement": True}
+    )
+    conversation_id: str = Field(
+        max_length=36,
+        nullable=False,
+        unique=True,
+        default_factory=lambda: str(uuid.uuid4()),
+    )
+    platform_id: str = Field(nullable=False)
+    user_id: str = Field(nullable=False)
+    content: Optional[list] = Field(default=None, sa_type=JSON)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        sa_column_kwargs={"onupdate": datetime.now(timezone.utc)},
+    )
+    title: Optional[str] = Field(default=None, max_length=255)
+    persona_id: Optional[str] = Field(default=None)
+
+    __table_args__ = (
+        UniqueConstraint(
+            "conversation_id",
+            name="uix_conversation_id",
+        ),
+    )
+
+
+class Persona(SQLModel, table=True):
+    """Persona is a set of instructions for LLMs to follow.
+
+    It can be used to customize the behavior of LLMs.
+    """
+
+    __tablename__ = "personas"
+
+    id: int | None = Field(
+        primary_key=True, sa_column_kwargs={"autoincrement": True}, default=None
+    )
+    persona_id: str = Field(max_length=255, nullable=False)
+    system_prompt: str = Field(sa_type=Text, nullable=False)
+    begin_dialogs: Optional[list] = Field(default=None, sa_type=JSON)
+    """a list of strings, each representing a dialog to start with"""
+    tools: Optional[list] = Field(default=None, sa_type=JSON)
+    """None means use ALL tools for default, empty list means no tools, otherwise a list of tool names."""
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        sa_column_kwargs={"onupdate": datetime.now(timezone.utc)},
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "persona_id",
+            name="uix_persona_id",
+        ),
+    )
+
+
+class Preference(SQLModel, table=True):
+    """This class represents preferences for bots."""
+
+    __tablename__ = "preferences"
+
+    id: int | None = Field(
+        default=None, primary_key=True, sa_column_kwargs={"autoincrement": True}
+    )
+    scope: str = Field(nullable=False)
+    """Scope of the preference, such as 'global', 'umo', 'plugin'."""
+    scope_id: str = Field(nullable=False)
+    """ID of the scope, such as 'global', 'umo', 'plugin_name'."""
+    key: str = Field(nullable=False)
+    value: dict = Field(sa_type=JSON, nullable=False)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        sa_column_kwargs={"onupdate": datetime.now(timezone.utc)},
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "scope",
+            "scope_id",
+            "key",
+            name="uix_preference_scope_scope_id_key",
+        ),
+    )
+
+
+class PlatformMessageHistory(SQLModel, table=True):
+    """This class represents the message history for a specific platform.
+
+    It is used to store messages that are not LLM-generated, such as user messages
+    or platform-specific messages.
+    """
+
+    __tablename__ = "platform_message_history"
+
+    id: int | None = Field(
+        primary_key=True, sa_column_kwargs={"autoincrement": True}, default=None
+    )
+    platform_id: str = Field(nullable=False)
+    user_id: str = Field(nullable=False)  # An id of group, user in platform
+    sender_id: Optional[str] = Field(default=None)  # ID of the sender in the platform
+    sender_name: Optional[str] = Field(
+        default=None
+    )  # Name of the sender in the platform
+    content: dict = Field(sa_type=JSON, nullable=False)  # a message chain list
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        sa_column_kwargs={"onupdate": datetime.now(timezone.utc)},
+    )
+
+
+class Attachment(SQLModel, table=True):
+    """This class represents attachments for messages in AstrBot.
+
+    Attachments can be images, files, or other media types.
+    """
+
+    __tablename__ = "attachments"
+
+    inner_attachment_id: int | None = Field(
+        primary_key=True, sa_column_kwargs={"autoincrement": True}, default=None
+    )
+    attachment_id: str = Field(
+        max_length=36,
+        nullable=False,
+        unique=True,
+        default_factory=lambda: str(uuid.uuid4()),
+    )
+    path: str = Field(nullable=False)  # Path to the file on disk
+    type: str = Field(nullable=False)  # Type of the file (e.g., 'image', 'file')
+    mime_type: str = Field(nullable=False)  # MIME type of the file
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    updated_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc),
+        sa_column_kwargs={"onupdate": datetime.now(timezone.utc)},
+    )
+
+    __table_args__ = (
+        UniqueConstraint(
+            "attachment_id",
+            name="uix_attachment_id",
+        ),
+    )
+
+
+@dataclass
+class Conversation:
+    """LLM 对话类
+
+    对于 WebChat，history 存储了包括指令、回复、图片等在内的所有消息。
+    对于其他平台的聊天，不存储非 LLM 的回复（因为考虑到已经存储在各自的平台上）。
+
+    在 v4.0.0 版本及之后，WebChat 的历史记录被迁移至 `PlatformMessageHistory` 表中，
+    """
+
+    platform_id: str
+    user_id: str
+    cid: str
+    """对话 ID, 是 uuid 格式的字符串"""
+    history: str = ""
+    """字符串格式的对话列表。"""
+    title: str | None = ""
+    persona_id: str | None = ""
+    created_at: int = 0
+    updated_at: int = 0
+
+
+class Personality(TypedDict):
+    """LLM 人格类。
+
+    在 v4.0.0 版本及之后，推荐使用上面的 Persona 类。并且， mood_imitation_dialogs 字段已被废弃。
+    """
+
+    prompt: str = ""
+    name: str = ""
+    begin_dialogs: list[str] = []
+    mood_imitation_dialogs: list[str] = []
+    """情感模拟对话预设。在 v4.0.0 版本及之后，已被废弃。"""
+    tools: list[str] | None = None
+    """工具列表。None 表示使用所有工具，空列表表示不使用任何工具"""
+
+    # cache
+    _begin_dialogs_processed: list[dict] = []
+    _mood_imitation_dialogs_processed: str = ""
+
+
+# ====
+# Deprecated, and will be removed in future versions.
+# ====
 
 
 @dataclass
@@ -13,77 +243,6 @@ class Platform:
     timestamp: int
 
 
-@dataclass
-class Provider:
-    """供应商使用统计数据"""
-
-    name: str
-    count: int
-    timestamp: int
-
-
-@dataclass
-class Plugin:
-    """插件使用统计数据"""
-
-    name: str
-    count: int
-    timestamp: int
-
-
-@dataclass
-class Command:
-    """命令使用统计数据"""
-
-    name: str
-    count: int
-    timestamp: int
-
-
 @dataclass
 class Stats:
-    platform: List[Platform] = field(default_factory=list)
-    command: List[Command] = field(default_factory=list)
-    llm: List[Provider] = field(default_factory=list)
-
-
-@dataclass
-class LLMHistory:
-    """LLM 聊天时持久化的信息"""
-
-    provider_type: str
-    session_id: str
-    content: str
-
-
-@dataclass
-class ATRIVision:
-    """Deprecated"""
-
-    id: str
-    url_or_path: str
-    caption: str
-    is_meme: bool
-    keywords: List[str]
-    platform_name: str
-    session_id: str
-    sender_nickname: str
-    timestamp: int = -1
-
-
-@dataclass
-class Conversation:
-    """LLM 对话存储
-
-    对于网页聊天，history 存储了包括指令、回复、图片等在内的所有消息。
-    对于其他平台的聊天，不存储非 LLM 的回复（因为考虑到已经存储在各自的平台上）。
-    """
-
-    user_id: str
-    cid: str
-    history: str = ""
-    """字符串格式的列表。"""
-    created_at: int = 0
-    updated_at: int = 0
-    title: str = ""
-    persona_id: str = ""
+    platform: list[Platform] = field(default_factory=list)

astrbot/core/db/sqlite_init.sql

@@ -1,50 +0,0 @@
-CREATE TABLE IF NOT EXISTS platform(
-    name VARCHAR(32),
-    count INTEGER,
-    timestamp INTEGER
-);
-CREATE TABLE IF NOT EXISTS llm(
-    name VARCHAR(32),
-    count INTEGER,
-    timestamp INTEGER
-);
-CREATE TABLE IF NOT EXISTS plugin(
-    name VARCHAR(32),
-    count INTEGER,
-    timestamp INTEGER
-);
-CREATE TABLE IF NOT EXISTS command(
-    name VARCHAR(32),
-    count INTEGER,
-    timestamp INTEGER
-);
-CREATE TABLE IF NOT EXISTS llm_history(
-    provider_type VARCHAR(32),
-    session_id VARCHAR(32),
-    content TEXT
-);
-
--- ATRI
-CREATE TABLE IF NOT EXISTS atri_vision(
-    id TEXT,
-    url_or_path TEXT,
-    caption TEXT,
-    is_meme BOOLEAN,
-    keywords TEXT,
-    platform_name VARCHAR(32),
-    session_id VARCHAR(32),
-    sender_nickname VARCHAR(32),
-    timestamp INTEGER
-);
-
-CREATE TABLE IF NOT EXISTS webchat_conversation(
-    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/faiss_impl/__init__.py

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

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

@@ -5,6 +5,7 @@ from .document_storage import DocumentStorage
 from .embedding_storage import EmbeddingStorage
 from ..base import Result, BaseVecDB
 from astrbot.core.provider.provider import EmbeddingProvider
+from astrbot.core.provider.provider import RerankProvider
 
 
 class FaissVecDB(BaseVecDB):
@@ -17,6 +18,7 @@ class FaissVecDB(BaseVecDB):
         doc_store_path: str,
         index_store_path: str,
         embedding_provider: EmbeddingProvider,
+        rerank_provider: RerankProvider | None = None,
     ):
         self.doc_store_path = doc_store_path
         self.index_store_path = index_store_path
@@ -26,11 +28,14 @@ class FaissVecDB(BaseVecDB):
             embedding_provider.get_dim(), index_store_path
         )
         self.embedding_provider = embedding_provider
+        self.rerank_provider = rerank_provider
 
     async def initialize(self):
         await self.document_storage.initialize()
 
-    async def insert(self, content: str, metadata: dict = None, id: str = None) -> int:
+    async def insert(
+        self, content: str, metadata: dict | None = None, id: str | None = None
+    ) -> int:
         """
         插入一条文本和其对应向量，自动生成 ID 并保持一致性。
         """
@@ -53,7 +58,12 @@ class FaissVecDB(BaseVecDB):
             return int_id
 
     async def retrieve(
-        self, query: str, k: int = 5, fetch_k: int = 20, metadata_filters: dict = None
+        self,
+        query: str,
+        k: int = 5,
+        fetch_k: int = 20,
+        rerank: bool = False,
+        metadata_filters: dict | None = None,
     ) -> list[Result]:
         """
         搜索最相似的文档。
@@ -62,6 +72,7 @@ class FaissVecDB(BaseVecDB):
             query (str): 查询文本
             k (int): 返回的最相似文档的数量
             fetch_k (int): 在根据 metadata 过滤前从 FAISS 中获取的数量
+            rerank (bool): 是否使用重排序。这需要在实例化时提供 rerank_provider, 如果未提供并且 rerank 为 True, 不会抛出异常。
             metadata_filters (dict): 元数据过滤器
 
         Returns:
@@ -72,7 +83,6 @@ class FaissVecDB(BaseVecDB):
             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
@@ -83,7 +93,7 @@ class FaissVecDB(BaseVecDB):
         )
         if not fetched_docs:
             return []
-        result_docs = []
+        result_docs: list[Result] = []
 
         idx_pos = {fetch_doc["id"]: idx for idx, fetch_doc in enumerate(fetched_docs)}
         for i, indice_idx in enumerate(indices[0]):
@@ -93,7 +103,21 @@ class FaissVecDB(BaseVecDB):
             fetch_doc = fetched_docs[pos]
             score = scores[0][i]
             result_docs.append(Result(similarity=float(score), data=fetch_doc))
-        return result_docs[:k]
+
+        top_k_results = result_docs[:k]
+
+        if rerank and self.rerank_provider:
+            documents = [doc.data["text"] for doc in top_k_results]
+            reranked_results = await self.rerank_provider.rerank(query, documents)
+            reranked_results = sorted(
+                reranked_results, key=lambda x: x.relevance_score, reverse=True
+            )
+            top_k_results = [
+                top_k_results[reranked_result.index]
+                for reranked_result in reranked_results
+            ]
+
+        return top_k_results
 
     async def delete(self, doc_id: int):
         """

astrbot/core/event_bus.py

@@ -16,30 +16,32 @@ from asyncio import Queue
 from astrbot.core.pipeline.scheduler import PipelineScheduler
 from astrbot.core import logger
 from .platform import AstrMessageEvent
+from astrbot.core.astrbot_config_mgr import AstrBotConfigManager
 
 
 class EventBus:
-    """事件总线: 用于处理事件的分发和处理
+    """用于处理事件的分发和处理"""
 
-    维护一个异步队列, 来接受各种消息事件
-    """
-
-    def __init__(self, event_queue: Queue, pipeline_scheduler: PipelineScheduler):
+    def __init__(
+        self,
+        event_queue: Queue,
+        pipeline_scheduler_mapping: dict[str, PipelineScheduler],
+        astrbot_config_mgr: AstrBotConfigManager = None,
+    ):
         self.event_queue = event_queue  # 事件队列
-        self.pipeline_scheduler = pipeline_scheduler  # 管道调度器
+        # abconf uuid -> scheduler
+        self.pipeline_scheduler_mapping = pipeline_scheduler_mapping
+        self.astrbot_config_mgr = astrbot_config_mgr
 
     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()
+            conf_info = self.astrbot_config_mgr.get_conf_info(event.unified_msg_origin)
+            self._print_event(event, conf_info["name"])
+            scheduler = self.pipeline_scheduler_mapping.get(conf_info["id"])
+            asyncio.create_task(scheduler.execute(event))
 
-    def _print_event(self, event: AstrMessageEvent):
+    def _print_event(self, event: AstrMessageEvent, conf_name: str):
         """用于记录事件信息
 
         Args:
@@ -48,10 +50,10 @@ class EventBus:
         # 如果有发送者名称: [平台名] 发送者名称/发送者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()}"
+                f"[{conf_name}] [{event.get_platform_id()}({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()}"
+                f"[{conf_name}] [{event.get_platform_id()}({event.get_platform_name()})] {event.get_sender_id()}: {event.get_message_outline()}"
             )

astrbot/core/file_token_service.py

@@ -2,6 +2,8 @@ import asyncio
 import os
 import uuid
 import time
+from urllib.parse import urlparse, unquote
+import platform
 
 
 class FileTokenService:
@@ -15,7 +17,9 @@ class FileTokenService:
     async def _cleanup_expired_tokens(self):
         """清理过期的令牌"""
         now = time.time()
-        expired_tokens = [token for token, (_, expire) in self.staged_files.items() if expire < now]
+        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)
 
@@ -32,15 +36,35 @@ class FileTokenService:
         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(file_path):
-                raise FileNotFoundError(f"文件不存在: {file_path}")
+            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] = (file_path, expire_time)
+            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:

astrbot/core/initial_loader.py

@@ -22,6 +22,7 @@ class InitialLoader:
         self.db = db
         self.logger = logger
         self.log_broker = log_broker
+        self.webui_dir: str | None = None
 
     async def start(self):
         core_lifecycle = AstrBotCoreLifecycle(self.log_broker, self.db)
@@ -35,8 +36,10 @@ class InitialLoader:
 
         core_task = core_lifecycle.start()
 
+        webui_dir = self.webui_dir
+
         self.dashboard_server = AstrBotDashboard(
-            core_lifecycle, self.db, core_lifecycle.dashboard_shutdown_event
+            core_lifecycle, self.db, core_lifecycle.dashboard_shutdown_event, webui_dir
         )
         task = asyncio.gather(
             core_task, self.dashboard_server.run()

astrbot/core/message/components.py

@@ -37,7 +37,7 @@ 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):
+class ComponentType(str, Enum):
     Plain = "Plain"  # 纯文本消息
     Face = "Face"  # QQ表情
     Record = "Record"  # 语音
@@ -108,7 +108,7 @@ class BaseMessageComponent(BaseModel):
 
 
 class Plain(BaseMessageComponent):
-    type: ComponentType = "Plain"
+    type = ComponentType.Plain
     text: str
     convert: T.Optional[bool] = True  # 若为 False 则直接发送未转换 CQ 码的消息
 
@@ -128,8 +128,9 @@ class Plain(BaseMessageComponent):
     async def to_dict(self):
         return {"type": "text", "data": {"text": self.text}}
 
+
 class Face(BaseMessageComponent):
-    type: ComponentType = "Face"
+    type = ComponentType.Face
     id: int
 
     def __init__(self, **_):
@@ -137,7 +138,7 @@ class Face(BaseMessageComponent):
 
 
 class Record(BaseMessageComponent):
-    type: ComponentType = "Record"
+    type = ComponentType.Record
     file: T.Optional[str] = ""
     magic: T.Optional[bool] = False
     url: T.Optional[str] = ""
@@ -164,19 +165,24 @@ class Record(BaseMessageComponent):
             return Record(file=url, **_)
         raise Exception("not a valid url")
 
+    @staticmethod
+    def fromBase64(bs64_data: str, **_):
+        return Record(file=f"base64://{bs64_data}", **_)
+
     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"):
+        if not self.file:
+            raise Exception(f"not a valid file: {self.file}")
+        if self.file.startswith("file:///"):
+            return self.file[8:]
+        elif 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://"):
+        elif 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")
@@ -185,8 +191,7 @@ class Record(BaseMessageComponent):
                 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)
+            return os.path.abspath(self.file)
         else:
             raise Exception(f"not a valid file: {self.file}")
 
@@ -197,12 +202,14 @@ class Record(BaseMessageComponent):
             str: 语音的 base64 编码，不以 base64:// 或者 data:image/jpeg;base64, 开头。
         """
         # convert to base64
-        if self.file and self.file.startswith("file:///"):
+        if not self.file:
+            raise Exception(f"not a valid file: {self.file}")
+        if self.file.startswith("file:///"):
             bs64_data = file_to_base64(self.file[8:])
-        elif self.file and self.file.startswith("http"):
+        elif 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://"):
+        elif self.file.startswith("base64://"):
             bs64_data = self.file
         elif os.path.exists(self.file):
             bs64_data = file_to_base64(self.file)
@@ -236,7 +243,7 @@ class Record(BaseMessageComponent):
 
 
 class Video(BaseMessageComponent):
-    type: ComponentType = "Video"
+    type = ComponentType.Video
     file: str
     cover: T.Optional[str] = ""
     c: T.Optional[int] = 2
@@ -322,7 +329,7 @@ class Video(BaseMessageComponent):
 
 
 class At(BaseMessageComponent):
-    type: ComponentType = "At"
+    type = ComponentType.At
     qq: T.Union[int, str]  # 此处str为all时代表所有人
     name: T.Optional[str] = ""
 
@@ -344,28 +351,28 @@ class AtAll(At):
 
 
 class RPS(BaseMessageComponent):  # TODO
-    type: ComponentType = "RPS"
+    type = ComponentType.RPS
 
     def __init__(self, **_):
         super().__init__(**_)
 
 
 class Dice(BaseMessageComponent):  # TODO
-    type: ComponentType = "Dice"
+    type = ComponentType.Dice
 
     def __init__(self, **_):
         super().__init__(**_)
 
 
 class Shake(BaseMessageComponent):  # TODO
-    type: ComponentType = "Shake"
+    type = ComponentType.Shake
 
     def __init__(self, **_):
         super().__init__(**_)
 
 
 class Anonymous(BaseMessageComponent):  # TODO
-    type: ComponentType = "Anonymous"
+    type = ComponentType.Anonymous
     ignore: T.Optional[bool] = False
 
     def __init__(self, **_):
@@ -373,7 +380,7 @@ class Anonymous(BaseMessageComponent):  # TODO
 
 
 class Share(BaseMessageComponent):
-    type: ComponentType = "Share"
+    type = ComponentType.Share
     url: str
     title: str
     content: T.Optional[str] = ""
@@ -384,7 +391,7 @@ class Share(BaseMessageComponent):
 
 
 class Contact(BaseMessageComponent):  # TODO
-    type: ComponentType = "Contact"
+    type = ComponentType.Contact
     _type: str  # type 字段冲突
     id: T.Optional[int] = 0
 
@@ -393,7 +400,7 @@ class Contact(BaseMessageComponent):  # TODO
 
 
 class Location(BaseMessageComponent):  # TODO
-    type: ComponentType = "Location"
+    type = ComponentType.Location
     lat: float
     lon: float
     title: T.Optional[str] = ""
@@ -404,7 +411,7 @@ class Location(BaseMessageComponent):  # TODO
 
 
 class Music(BaseMessageComponent):
-    type: ComponentType = "Music"
+    type = ComponentType.Music
     _type: str
     id: T.Optional[int] = 0
     url: T.Optional[str] = ""
@@ -421,7 +428,7 @@ class Music(BaseMessageComponent):
 
 
 class Image(BaseMessageComponent):
-    type: ComponentType = "Image"
+    type = ComponentType.Image
     file: T.Optional[str] = ""
     _type: T.Optional[str] = ""
     subType: T.Optional[int] = 0
@@ -464,14 +471,15 @@ class Image(BaseMessageComponent):
         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"):
+        url = self.url or self.file
+        if not url:
+            raise ValueError("No valid file or URL provided")
+        if url.startswith("file:///"):
+            return url[8:]
+        elif 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://"):
+        elif url.startswith("base64://"):
             bs64_data = url.removeprefix("base64://")
             image_bytes = base64.b64decode(bs64_data)
             temp_dir = os.path.join(get_astrbot_data_path(), "temp")
@@ -480,8 +488,7 @@ class Image(BaseMessageComponent):
                 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)
+            return os.path.abspath(url)
         else:
             raise Exception(f"not a valid file: {url}")
 
@@ -492,13 +499,15 @@ class Image(BaseMessageComponent):
             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:///"):
+        url = self.url or self.file
+        if not url:
+            raise ValueError("No valid file or URL provided")
+        if url.startswith("file:///"):
             bs64_data = file_to_base64(url[8:])
-        elif url and url.startswith("http"):
+        elif 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://"):
+        elif url.startswith("base64://"):
             bs64_data = url
         elif os.path.exists(url):
             bs64_data = file_to_base64(url)
@@ -532,7 +541,7 @@ class Image(BaseMessageComponent):
 
 
 class Reply(BaseMessageComponent):
-    type: ComponentType = "Reply"
+    type = ComponentType.Reply
     id: T.Union[str, int]
     """所引用的消息 ID"""
     chain: T.Optional[T.List["BaseMessageComponent"]] = []
@@ -558,7 +567,7 @@ class Reply(BaseMessageComponent):
 
 
 class RedBag(BaseMessageComponent):
-    type: ComponentType = "RedBag"
+    type = ComponentType.RedBag
     title: str
 
     def __init__(self, **_):
@@ -566,7 +575,7 @@ class RedBag(BaseMessageComponent):
 
 
 class Poke(BaseMessageComponent):
-    type: str = ""
+    type: str = ComponentType.Poke
     id: T.Optional[int] = 0
     qq: T.Optional[int] = 0
 
@@ -576,7 +585,7 @@ class Poke(BaseMessageComponent):
 
 
 class Forward(BaseMessageComponent):
-    type: ComponentType = "Forward"
+    type = ComponentType.Forward
     id: str
 
     def __init__(self, **_):
@@ -586,7 +595,7 @@ class Forward(BaseMessageComponent):
 class Node(BaseMessageComponent):
     """群合并转发消息"""
 
-    type: ComponentType = "Node"
+    type = ComponentType.Node
     id: T.Optional[int] = 0  # 忽略
     name: T.Optional[str] = ""  # qq昵称
     uin: T.Optional[str] = "0"  # qq号
@@ -638,7 +647,7 @@ class Node(BaseMessageComponent):
 
 
 class Nodes(BaseMessageComponent):
-    type: ComponentType = "Nodes"
+    type = ComponentType.Nodes
     nodes: T.List[Node]
 
     def __init__(self, nodes: T.List[Node], **_):
@@ -664,7 +673,7 @@ class Nodes(BaseMessageComponent):
 
 
 class Xml(BaseMessageComponent):
-    type: ComponentType = "Xml"
+    type = ComponentType.Xml
     data: str
     resid: T.Optional[int] = 0
 
@@ -673,7 +682,7 @@ class Xml(BaseMessageComponent):
 
 
 class Json(BaseMessageComponent):
-    type: ComponentType = "Json"
+    type = ComponentType.Json
     data: T.Union[str, dict]
     resid: T.Optional[int] = 0
 
@@ -684,7 +693,7 @@ class Json(BaseMessageComponent):
 
 
 class CardImage(BaseMessageComponent):
-    type: ComponentType = "CardImage"
+    type = ComponentType.CardImage
     file: str
     cache: T.Optional[bool] = True
     minwidth: T.Optional[int] = 400
@@ -703,7 +712,7 @@ class CardImage(BaseMessageComponent):
 
 
 class TTS(BaseMessageComponent):
-    type: ComponentType = "TTS"
+    type = ComponentType.TTS
     text: str
 
     def __init__(self, **_):
@@ -711,7 +720,7 @@ class TTS(BaseMessageComponent):
 
 
 class Unknown(BaseMessageComponent):
-    type: ComponentType = "Unknown"
+    type = ComponentType.Unknown
     text: str
 
     def toString(self):
@@ -723,7 +732,7 @@ class File(BaseMessageComponent):
     文件消息段
     """
 
-    type: ComponentType = "File"
+    type = ComponentType.File
     name: T.Optional[str] = ""  # 名字
     file_: T.Optional[str] = ""  # 本地路径
     url: T.Optional[str] = ""  # url
@@ -853,7 +862,7 @@ class File(BaseMessageComponent):
 
 
 class WechatEmoji(BaseMessageComponent):
-    type: ComponentType = "WechatEmoji"
+    type = ComponentType.WechatEmoji
     md5: T.Optional[str] = ""
     md5_len: T.Optional[int] = 0
     cdnurl: T.Optional[str] = ""

astrbot/core/persona_mgr.py

@@ -0,0 +1,183 @@
+from astrbot.core.db import BaseDatabase
+from astrbot.core.db.po import Persona, Personality
+from astrbot.core.astrbot_config_mgr import AstrBotConfigManager
+from astrbot.core.platform.message_session import MessageSession
+from astrbot import logger
+
+DEFAULT_PERSONALITY = Personality(
+    prompt="You are a helpful and friendly assistant.",
+    name="default",
+    begin_dialogs=[],
+    mood_imitation_dialogs=[],
+    tools=None,
+    _begin_dialogs_processed=[],
+    _mood_imitation_dialogs_processed="",
+)
+
+
+class PersonaManager:
+    def __init__(self, db_helper: BaseDatabase, acm: AstrBotConfigManager):
+        self.db = db_helper
+        self.acm = acm
+        default_ps = acm.default_conf.get("provider_settings", {})
+        self.default_persona: str = default_ps.get("default_personality", "default")
+        self.personas: list[Persona] = []
+        self.selected_default_persona: Persona | None = None
+
+        self.personas_v3: list[Personality] = []
+        self.selected_default_persona_v3: Personality | None = None
+        self.persona_v3_config: list[dict] = []
+
+    async def initialize(self):
+        self.personas = await self.get_all_personas()
+        self.get_v3_persona_data()
+        logger.info(f"已加载 {len(self.personas)} 个人格。")
+
+    async def get_persona(self, persona_id: str):
+        """获取指定 persona 的信息"""
+        persona = await self.db.get_persona_by_id(persona_id)
+        if not persona:
+            raise ValueError(f"Persona with ID {persona_id} does not exist.")
+        return persona
+
+    async def get_default_persona_v3(
+        self, umo: str | MessageSession | None = None
+    ) -> Personality:
+        """获取默认 persona"""
+        cfg = self.acm.get_conf(umo)
+        default_persona_id = cfg.get("provider_settings", {}).get(
+            "default_personality", "default"
+        )
+        if not default_persona_id or default_persona_id == "default":
+            return DEFAULT_PERSONALITY
+        try:
+            return next(p for p in self.personas_v3 if p["name"] == default_persona_id)
+        except Exception:
+            return DEFAULT_PERSONALITY
+
+    async def delete_persona(self, persona_id: str):
+        """删除指定 persona"""
+        if not await self.db.get_persona_by_id(persona_id):
+            raise ValueError(f"Persona with ID {persona_id} does not exist.")
+        await self.db.delete_persona(persona_id)
+        self.personas = [p for p in self.personas if p.persona_id != persona_id]
+        self.get_v3_persona_data()
+
+    async def update_persona(
+        self,
+        persona_id: str,
+        system_prompt: str = None,
+        begin_dialogs: list[str] = None,
+        tools: list[str] = None,
+    ):
+        """更新指定 persona 的信息。tools 参数为 None 时表示使用所有工具，空列表表示不使用任何工具"""
+        existing_persona = await self.db.get_persona_by_id(persona_id)
+        if not existing_persona:
+            raise ValueError(f"Persona with ID {persona_id} does not exist.")
+        persona = await self.db.update_persona(
+            persona_id, system_prompt, begin_dialogs, tools=tools
+        )
+        if persona:
+            for i, p in enumerate(self.personas):
+                if p.persona_id == persona_id:
+                    self.personas[i] = persona
+                    break
+        self.get_v3_persona_data()
+        return persona
+
+    async def get_all_personas(self) -> list[Persona]:
+        """获取所有 personas"""
+        return await self.db.get_personas()
+
+    async def create_persona(
+        self,
+        persona_id: str,
+        system_prompt: str,
+        begin_dialogs: list[str] = None,
+        tools: list[str] = None,
+    ) -> Persona:
+        """创建新的 persona。tools 参数为 None 时表示使用所有工具，空列表表示不使用任何工具"""
+        if await self.db.get_persona_by_id(persona_id):
+            raise ValueError(f"Persona with ID {persona_id} already exists.")
+        new_persona = await self.db.insert_persona(
+            persona_id, system_prompt, begin_dialogs, tools=tools
+        )
+        self.personas.append(new_persona)
+        self.get_v3_persona_data()
+        return new_persona
+
+    def get_v3_persona_data(
+        self,
+    ) -> tuple[list[dict], list[Personality], Personality]:
+        """获取 AstrBot <4.0.0 版本的 persona 数据。
+
+        Returns:
+            - list[dict]: 包含 persona 配置的字典列表。
+            - list[Personality]: 包含 Personality 对象的列表。
+            - Personality: 默认选择的 Personality 对象。
+        """
+        v3_persona_config = [
+            {
+                "prompt": persona.system_prompt,
+                "name": persona.persona_id,
+                "begin_dialogs": persona.begin_dialogs or [],
+                "mood_imitation_dialogs": [],  # deprecated
+                "tools": persona.tools,
+            }
+            for persona in self.personas
+        ]
+
+        personas_v3: list[Personality] = []
+        selected_default_persona: Personality | None = None
+
+        for persona_cfg in v3_persona_config:
+            begin_dialogs = persona_cfg.get("begin_dialogs", [])
+            bd_processed = []
+            if begin_dialogs:
+                if len(begin_dialogs) % 2 != 0:
+                    logger.error(
+                        f"{persona_cfg['name']} 人格情景预设对话格式不对，条数应该为偶数。"
+                    )
+                    begin_dialogs = []
+                user_turn = True
+                for dialog in begin_dialogs:
+                    bd_processed.append(
+                        {
+                            "role": "user" if user_turn else "assistant",
+                            "content": dialog,
+                            "_no_save": None,  # 不持久化到 db
+                        }
+                    )
+                    user_turn = not user_turn
+
+            try:
+                persona = Personality(
+                    **persona_cfg,
+                    _begin_dialogs_processed=bd_processed,
+                    _mood_imitation_dialogs_processed="",  # deprecated
+                )
+                if persona["name"] == self.default_persona:
+                    selected_default_persona = persona
+                personas_v3.append(persona)
+            except Exception as e:
+                logger.error(f"解析 Persona 配置失败：{e}")
+
+        if not selected_default_persona and len(personas_v3) > 0:
+            # 默认选择第一个
+            selected_default_persona = personas_v3[0]
+
+        if not selected_default_persona:
+            selected_default_persona = DEFAULT_PERSONALITY
+            personas_v3.append(selected_default_persona)
+
+        self.personas_v3 = personas_v3
+        self.selected_default_persona_v3 = selected_default_persona
+        self.persona_v3_config = v3_persona_config
+        self.selected_default_persona = Persona(
+            persona_id=selected_default_persona["name"],
+            system_prompt=selected_default_persona["prompt"],
+            begin_dialogs=selected_default_persona["begin_dialogs"],
+            tools=selected_default_persona["tools"] or None,
+        )
+
+        return v3_persona_config, personas_v3, selected_default_persona

astrbot/core/pipeline/__init__.py

@@ -4,7 +4,6 @@ from astrbot.core.message.message_event_result import (
 )
 
 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 .rate_limit_check.stage import RateLimitStage
@@ -21,7 +20,6 @@ STAGES_ORDER = [
     "SessionStatusCheckStage",  # 检查会话是否整体启用
     "RateLimitStage",  # 检查会话是否超过频率限制
     "ContentSafetyCheckStage",  # 检查内容安全
-    "PlatformCompatibilityStage",  # 检查所有处理器的平台兼容性
     "PreProcessStage",  # 预处理
     "ProcessStage",  # 交由 Stars 处理（a.k.a 插件），或者 LLM 调用
     "ResultDecorateStage",  # 处理结果，比如添加回复前缀、t2i、转换为语音 等
@@ -34,7 +32,6 @@ __all__ = [
     "SessionStatusCheckStage",
     "RateLimitStage",
     "ContentSafetyCheckStage",
-    "PlatformCompatibilityStage",
     "PreProcessStage",
     "ProcessStage",
     "ResultDecorateStage",

astrbot/core/pipeline/content_safety_check/stage.py

@@ -19,7 +19,7 @@ class ContentSafetyCheckStage(Stage):
         self.strategy_selector = StrategySelector(config)
 
     async def process(
-        self, event: AstrMessageEvent, check_text: str = None
+        self, event: AstrMessageEvent, check_text: str | None = None
     ) -> Union[None, AsyncGenerator[None, None]]:
         """检查内容安全"""
         text = check_text if check_text else event.get_message_str()

astrbot/core/pipeline/content_safety_check/strategies/baidu_aip.py

@@ -13,7 +13,7 @@ class BaiduAipStrategy(ContentSafetyStrategy):
         self.secret_key = sk
         self.client = AipContentCensor(self.app_id, self.api_key, self.secret_key)
 
-    def check(self, content: str):
+    def check(self, content: str) -> tuple[bool, str]:
         res = self.client.textCensorUserDefined(content)
         if "conclusionType" not in res:
             return False, ""

astrbot/core/pipeline/content_safety_check/strategies/keywords.py

@@ -16,7 +16,7 @@ class KeywordsStrategy(ContentSafetyStrategy):
         #             json.loads(base64.b64decode(f.read()).decode("utf-8"))["keywords"]
         #         )
 
-    def check(self, content: str) -> bool:
+    def check(self, content: str) -> tuple[bool, str]:
         for keyword in self.keywords:
             if re.search(keyword, content):
                 return False, "内容安全检查不通过，匹配到敏感词。"

astrbot/core/pipeline/context.py

@@ -1,14 +1,7 @@
-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.config import AstrBotConfig
 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
+from .context_utils import call_handler, call_event_hook
 
 
 @dataclass
@@ -17,97 +10,6 @@ class PipelineContext:
 
     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_config_id: str
+    call_handler = call_handler
+    call_event_hook = call_event_hook

astrbot/core/pipeline/context_utils.py

@@ -0,0 +1,102 @@
+import inspect
+import traceback
+import typing as T
+from astrbot 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
+from astrbot.core.platform.astr_message_event import AstrMessageEvent
+
+
+async def call_handler(
+    event: AstrMessageEvent,
+    handler: T.Callable[..., T.Awaitable[T.Any]],
+    *args,
+    **kwargs,
+) -> T.AsyncGenerator[T.Any, None]:
+    """执行事件处理函数并处理其返回结果
+
+    该方法负责调用处理函数并处理不同类型的返回值。它支持两种类型的处理函数:
+    1. 异步生成器: 实现洋葱模型，每次 yield 都会将控制权交回上层
+    2. 协程: 执行一次并处理返回值
+
+    Args:
+        event (AstrMessageEvent): 事件对象
+        handler (Awaitable): 事件处理函数
+
+    Returns:
+        AsyncGenerator[None, None]: 异步生成器，用于在管道中传递控制流
+    """
+    ready_to_call = None  # 一个协程或者异步生成器
+
+    trace_ = None
+
+    try:
+        ready_to_call = handler(event, *args, **kwargs)
+    except TypeError:
+        logger.error("处理函数参数不匹配，请检查 handler 的定义。", exc_info=True)
+
+    if not ready_to_call:
+        return
+
+    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
+
+
+async def call_event_hook(
+    event: AstrMessageEvent,
+    hook_type: EventType,
+    *args,
+    **kwargs,
+) -> bool:
+    """调用事件钩子函数
+
+    Returns:
+        bool: 如果事件被终止，返回 True
+    #"""
+    handlers = star_handlers_registry.get_handlers_by_event_type(
+        hook_type, plugins_name=event.plugins_name
+    )
+    for handler in handlers:
+        try:
+            logger.debug(
+                f"hook({hook_type.name}) -> {star_map[handler.handler_module_path].name} - {handler.handler_name}"
+            )
+            await handler.handler(event, *args, **kwargs)
+        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 True
+
+    return event.is_stopped()

astrbot/core/pipeline/platform_compatibility/stage.py

@@ -1,56 +0,0 @@
-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

@@ -1,5 +1,6 @@
 import traceback
 import asyncio
+import random
 from typing import Union, AsyncGenerator
 from ..stage import Stage, register_stage
 from ..context import PipelineContext
@@ -22,6 +23,26 @@ class PreProcessStage(Stage):
         self, event: AstrMessageEvent
     ) -> Union[None, AsyncGenerator[None, None]]:
         """在处理事件之前的预处理"""
+        # 平台特异配置：platform_specific.<platform>.pre_ack_emoji
+        supported = {"telegram", "lark"}
+        platform = event.get_platform_name()
+        cfg = (
+            self.config.get("platform_specific", {})
+            .get(platform, {})
+            .get("pre_ack_emoji", {})
+        ) or {}
+        emojis = cfg.get("emojis") or []
+        if (
+            cfg.get("enable", False)
+            and platform in supported
+            and emojis
+            and event.is_at_or_wake_command
+        ):
+            try:
+                await event.react(random.choice(emojis))
+            except Exception as e:
+                logger.warning(f"{platform} 预回应表情发送失败: {e}")
+
         # 路径映射
         if mappings := self.platform_settings.get("path_mapping", []):
             # 支持 Record，Image 消息段的路径映射。
@@ -46,6 +67,9 @@ class PreProcessStage(Stage):
             ctx = self.plugin_manager.context
             stt_provider = ctx.get_using_stt_provider(event.unified_msg_origin)
             if not stt_provider:
+                logger.warning(
+                    f"会话 {event.unified_msg_origin} 未配置语音转文本模型。"
+                )
                 return
             message_chain = event.get_messages()
             for idx, component in enumerate(message_chain):

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

@@ -6,7 +6,9 @@ import asyncio
 import copy
 import json
 import traceback
+from datetime import timedelta
 from typing import AsyncGenerator, Union
+from astrbot.core.conversation_mgr import Conversation
 from astrbot.core import logger
 from astrbot.core.message.components import Image
 from astrbot.core.message.message_event_result import (
@@ -20,12 +22,291 @@ from astrbot.core.provider.entities import (
     LLMResponse,
     ProviderRequest,
 )
+from astrbot.core.agent.hooks import BaseAgentRunHooks
+from astrbot.core.agent.runners.tool_loop_agent_runner import ToolLoopAgentRunner
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.agent.tool import ToolSet, FunctionTool
+from astrbot.core.agent.tool_executor import BaseFunctionToolExecutor
+from astrbot.core.agent.handoff import HandoffTool
 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 ...context import PipelineContext
-from ..agent_runner.tool_loop_agent import ToolLoopAgent
+from ...context import PipelineContext, call_event_hook, call_handler
 from ..stage import Stage
+from astrbot.core.provider.register import llm_tools
+from astrbot.core.star.star_handler import star_map
+from astrbot.core.astr_agent_context import AstrAgentContext
+
+try:
+    import mcp
+except (ModuleNotFoundError, ImportError):
+    logger.warning("警告: 缺少依赖库 'mcp'，将无法使用 MCP 服务。")
+
+
+AgentContextWrapper = ContextWrapper[AstrAgentContext]
+AgentRunner = ToolLoopAgentRunner[AgentContextWrapper]
+
+
+class FunctionToolExecutor(BaseFunctionToolExecutor[AstrAgentContext]):
+    @classmethod
+    async def execute(cls, tool, run_context, **tool_args):
+        """执行函数调用。
+
+        Args:
+            event (AstrMessageEvent): 事件对象, 当 origin 为 local 时必须提供。
+            **kwargs: 函数调用的参数。
+
+        Returns:
+            AsyncGenerator[None | mcp.types.CallToolResult, None]
+        """
+        if isinstance(tool, HandoffTool):
+            async for r in cls._execute_handoff(tool, run_context, **tool_args):
+                yield r
+            return
+
+        if tool.origin == "local":
+            async for r in cls._execute_local(tool, run_context, **tool_args):
+                yield r
+            return
+
+        elif tool.origin == "mcp":
+            async for r in cls._execute_mcp(tool, run_context, **tool_args):
+                yield r
+            return
+
+        raise Exception(f"Unknown function origin: {tool.origin}")
+
+    @classmethod
+    async def _execute_handoff(
+        cls,
+        tool: HandoffTool,
+        run_context: ContextWrapper[AstrAgentContext],
+        **tool_args,
+    ):
+        input_ = tool_args.get("input", "agent")
+        agent_runner = AgentRunner()
+
+        # make toolset for the agent
+        tools = tool.agent.tools
+        if tools:
+            toolset = ToolSet()
+            for t in tools:
+                if isinstance(t, str):
+                    _t = llm_tools.get_func(t)
+                    if _t:
+                        toolset.add_tool(_t)
+                elif isinstance(t, FunctionTool):
+                    toolset.add_tool(t)
+        else:
+            toolset = None
+
+        request = ProviderRequest(
+            prompt=input_,
+            system_prompt=tool.description,
+            image_urls=[],  # 暂时不传递原始 agent 的上下文
+            contexts=[],  # 暂时不传递原始 agent 的上下文
+            func_tool=toolset,
+        )
+        astr_agent_ctx = AstrAgentContext(
+            provider=run_context.context.provider,
+            first_provider_request=run_context.context.first_provider_request,
+            curr_provider_request=request,
+            streaming=run_context.context.streaming,
+        )
+
+        logger.debug(f"正在将任务委托给 Agent: {tool.agent.name}, input: {input_}")
+        await run_context.event.send(
+            MessageChain().message("✨ 正在将任务委托给 Agent: " + tool.agent.name)
+        )
+
+        await agent_runner.reset(
+            provider=run_context.context.provider,
+            request=request,
+            run_context=AgentContextWrapper(
+                context=astr_agent_ctx, event=run_context.event
+            ),
+            tool_executor=FunctionToolExecutor(),
+            agent_hooks=tool.agent.run_hooks or BaseAgentRunHooks[AstrAgentContext](),
+            streaming=run_context.context.streaming,
+        )
+
+        async for _ in run_agent(agent_runner, 15, True):
+            pass
+
+        if agent_runner.done():
+            llm_response = agent_runner.get_final_llm_resp()
+
+            if not llm_response:
+                text_content = mcp.types.TextContent(
+                    type="text",
+                    text=f"error when deligate task to {tool.agent.name}",
+                )
+                yield mcp.types.CallToolResult(content=[text_content])
+                return
+
+            logger.debug(
+                f"Agent  {tool.agent.name} 任务完成, response: {llm_response.completion_text}"
+            )
+
+            result = (
+                f"Agent {tool.agent.name} respond with: {llm_response.completion_text}\n\n"
+                "Note: If the result is error or need user provide more information, please provide more information to the agent(you can ask user for more information first)."
+            )
+
+            text_content = mcp.types.TextContent(
+                type="text",
+                text=result,
+            )
+            yield mcp.types.CallToolResult(content=[text_content])
+        else:
+            text_content = mcp.types.TextContent(
+                type="text",
+                text=f"error when deligate task to {tool.agent.name}",
+            )
+            yield mcp.types.CallToolResult(content=[text_content])
+        return
+
+    @classmethod
+    async def _execute_local(
+        cls,
+        tool: FunctionTool,
+        run_context: ContextWrapper[AstrAgentContext],
+        **tool_args,
+    ):
+        if not run_context.event:
+            raise ValueError("Event must be provided for local function tools.")
+
+        # 检查 tool 下有没有 run 方法
+        if not tool.handler and not hasattr(tool, "run"):
+            raise ValueError("Tool must have a valid handler or 'run' method.")
+        awaitable = tool.handler or getattr(tool, "run")
+
+        wrapper = call_handler(
+            event=run_context.event,
+            handler=awaitable,
+            **tool_args,
+        )
+        # async for resp in wrapper:
+        while True:
+            try:
+                resp = await asyncio.wait_for(
+                    anext(wrapper),
+                    timeout=run_context.context.tool_call_timeout,
+                )
+                if resp is not None:
+                    if isinstance(resp, mcp.types.CallToolResult):
+                        yield resp
+                    else:
+                        text_content = mcp.types.TextContent(
+                            type="text",
+                            text=str(resp),
+                        )
+                        yield mcp.types.CallToolResult(content=[text_content])
+                else:
+                    # NOTE: Tool 在这里直接请求发送消息给用户
+                    # TODO: 是否需要判断 event.get_result() 是否为空?
+                    # 如果为空,则说明没有发送消息给用户,并且返回值为空,将返回一个特殊的 TextContent,其内容如"工具没有返回内容"
+                    yield None
+            except asyncio.TimeoutError:
+                raise Exception(
+                    f"tool {tool.name} execution timeout after {run_context.context.tool_call_timeout} seconds."
+                )
+            except StopAsyncIteration:
+                break
+
+    @classmethod
+    async def _execute_mcp(
+        cls,
+        tool: FunctionTool,
+        run_context: ContextWrapper[AstrAgentContext],
+        **tool_args,
+    ):
+        if not tool.mcp_client:
+            raise ValueError("MCP client is not available for MCP function tools.")
+
+        session = tool.mcp_client.session
+        if not session:
+            raise ValueError("MCP session is not available for MCP function tools.")
+        res = await session.call_tool(
+            name=tool.name,
+            arguments=tool_args,
+            read_timeout_seconds=timedelta(
+                seconds=run_context.context.tool_call_timeout
+            ),
+        )
+        if not res:
+            return
+        yield res
+
+
+class MainAgentHooks(BaseAgentRunHooks[AgentContextWrapper]):
+    async def on_agent_done(self, run_context, llm_response):
+        # 执行事件钩子
+        await call_event_hook(
+            run_context.event, EventType.OnLLMResponseEvent, llm_response
+        )
+
+
+MAIN_AGENT_HOOKS = MainAgentHooks()
+
+
+async def run_agent(
+    agent_runner: AgentRunner, max_step: int = 30, show_tool_use: bool = True
+) -> AsyncGenerator[MessageChain, None]:
+    step_idx = 0
+    astr_event = agent_runner.run_context.event
+    while step_idx < max_step:
+        step_idx += 1
+        try:
+            async for resp in agent_runner.step():
+                if astr_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 astr_event.send(resp.data["chain"])
+                        continue
+                    # 对于其他情况，暂时先不处理
+                    continue
+                elif resp.type == "tool_call":
+                    if agent_runner.streaming:
+                        # 用来标记流式响应需要分节
+                        yield MessageChain(chain=[], type="break")
+                    if show_tool_use or astr_event.get_platform_name() == "webchat":
+                        resp.data["chain"].type = "tool_call"
+                        await astr_event.send(resp.data["chain"])
+                    continue
+
+                if not agent_runner.streaming:
+                    content_typ = (
+                        ResultContentType.LLM_RESULT
+                        if resp.type == "llm_result"
+                        else ResultContentType.GENERAL_RESULT
+                    )
+                    astr_event.set_result(
+                        MessageEventResult(
+                            chain=resp.data["chain"].chain,
+                            result_content_type=content_typ,
+                        )
+                    )
+                    yield
+                    astr_event.clear_result()
+                else:
+                    if resp.type == "streaming_delta":
+                        yield resp.data["chain"]  # MessageChain
+            if agent_runner.done():
+                break
+
+        except Exception as e:
+            logger.error(traceback.format_exc())
+            err_msg = f"\n\nAstrBot 请求失败。\n错误类型: {type(e).__name__}\n错误信息: {str(e)}\n\n请在控制台查看和分享错误详情。\n"
+            if agent_runner.streaming:
+                yield MessageChain().message(err_msg)
+            else:
+                astr_event.set_result(MessageEventResult().message(err_msg))
+            return
 
 
 class LLMRequestSubStage(Stage):
@@ -41,7 +322,10 @@ class LLMRequestSubStage(Stage):
             self.max_context_length - 1,
         )
         self.streaming_response: bool = settings["streaming_response"]
-        self.max_step: int = settings.get("max_agent_step", 10)
+        self.max_step: int = settings.get("max_agent_step", 30)
+        self.tool_call_timeout: int = settings.get("tool_call_timeout", 60)
+        if isinstance(self.max_step, bool):  # workaround: #2622
+            self.max_step = 30
         self.show_tool_use: bool = settings.get("show_tool_use_status", True)
 
         for bwp in self.bot_wake_prefixs:
@@ -65,6 +349,22 @@ class LLMRequestSubStage(Stage):
 
         return _ctx.get_using_provider(umo=event.unified_msg_origin)
 
+    async def _get_session_conv(self, event: AstrMessageEvent) -> Conversation:
+        umo = event.unified_msg_origin
+        conv_mgr = self.conv_manager
+
+        # 获取对话上下文
+        cid = await conv_mgr.get_curr_conversation_id(umo)
+        if not cid:
+            cid = await conv_mgr.new_conversation(umo, event.get_platform_id())
+        conversation = await conv_mgr.get_conversation(umo, cid)
+        if not conversation:
+            cid = await conv_mgr.new_conversation(umo, event.get_platform_id())
+            conversation = await conv_mgr.get_conversation(umo, cid)
+        if not conversation:
+            raise RuntimeError("无法创建新的对话。")
+        return conversation
+
     async def process(
         self, event: AstrMessageEvent, _nested: bool = False
     ) -> Union[None, AsyncGenerator[None, None]]:
@@ -100,30 +400,14 @@ class LLMRequestSubStage(Stage):
                 if not event.message_str.startswith(self.provider_wake_prefix):
                     return
             req.prompt = event.message_str[len(self.provider_wake_prefix) :]
-            req.func_tool = self.ctx.plugin_manager.context.get_llm_tool_manager()
+            # func_tool selection 现在已经转移到 packages/astrbot 插件中进行选择。
+            # req.func_tool = self.ctx.plugin_manager.context.get_llm_tool_manager()
             for comp in event.message_obj.message:
                 if isinstance(comp, Image):
                     image_path = await comp.convert_to_file_path()
                     req.image_urls.append(image_path)
 
-            # 获取对话上下文
-            conversation_id = await self.conv_manager.get_curr_conversation_id(
-                event.unified_msg_origin
-            )
-            if not conversation_id:
-                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
-            )
-            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
-                )
+            conversation = await self._get_session_conv(event)
             req.conversation = conversation
             req.contexts = json.loads(conversation.history)
 
@@ -133,7 +417,7 @@ class LLMRequestSubStage(Stage):
             return
 
         # 执行请求 LLM 前事件钩子。
-        if await self.ctx.call_event_hook(event, EventType.OnLLMRequestEvent, req):
+        if await call_event_hook(event, EventType.OnLLMRequestEvent, req):
             return
 
         if isinstance(req.contexts, str):
@@ -167,92 +451,68 @@ class LLMRequestSubStage(Stage):
         # fix messages
         req.contexts = self.fix_messages(req.contexts)
 
-        # Call Agent
-        tool_loop_agent = ToolLoopAgent(
-            provider=provider,
-            event=event,
-            pipeline_ctx=self.ctx,
-        )
+        # check provider modalities
+        # 如果提供商不支持图像/工具使用，但请求中包含图像/工具列表，则清空。图片转述等的检测和调用发生在这之前，因此这里可以这样处理。
+        if req.image_urls:
+            provider_cfg = provider.provider_config.get("modalities", ["image"])
+            if "image" not in provider_cfg:
+                logger.debug(f"用户设置提供商 {provider} 不支持图像，清空图像列表。")
+                req.image_urls = []
+        if req.func_tool:
+            provider_cfg = provider.provider_config.get("modalities", ["tool_use"])
+            # 如果模型不支持工具使用，但请求中包含工具列表，则清空。
+            if "tool_use" not in provider_cfg:
+                logger.debug(
+                    f"用户设置提供商 {provider} 不支持工具使用，清空工具列表。"
+                )
+                req.func_tool = None
+        # 插件可用性设置
+        if event.plugins_name is not None and req.func_tool:
+            new_tool_set = ToolSet()
+            for tool in req.func_tool.tools:
+                mp = tool.handler_module_path
+                if not mp:
+                    continue
+                plugin = star_map.get(mp)
+                if not plugin:
+                    continue
+                if plugin.name in event.plugins_name or plugin.reserved:
+                    new_tool_set.add_tool(tool)
+            req.func_tool = new_tool_set
+
+        # run agent
+        agent_runner = AgentRunner()
         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
-                asyncio.create_task(
-                    Metric.upload(
-                        llm_tick=1,
-                        model_name=provider.get_model(),
-                        provider_type=provider.meta().type,
-                    )
-                )
+        astr_agent_ctx = AstrAgentContext(
+            provider=provider,
+            first_provider_request=req,
+            curr_provider_request=req,
+            streaming=self.streaming_response,
+            tool_call_timeout=self.tool_call_timeout,
+        )
+        await agent_runner.reset(
+            provider=provider,
+            request=req,
+            run_context=AgentContextWrapper(context=astr_agent_ctx, event=event),
+            tool_executor=FunctionToolExecutor(),
+            agent_hooks=MAIN_AGENT_HOOKS,
+            streaming=self.streaming_response,
+        )
 
         if self.streaming_response:
             # 流式响应
             event.set_result(
                 MessageEventResult()
                 .set_result_content_type(ResultContentType.STREAMING_RESULT)
-                .set_async_stream(requesting())
+                .set_async_stream(
+                    run_agent(agent_runner, self.max_step, self.show_tool_use)
+                )
             )
             yield
-            if tool_loop_agent.done():
-                if final_llm_resp := tool_loop_agent.get_final_llm_resp():
+            if agent_runner.done():
+                if final_llm_resp := agent_runner.get_final_llm_resp():
                     if final_llm_resp.completion_text:
                         chain = (
                             MessageChain().message(final_llm_resp.completion_text).chain
@@ -266,14 +526,22 @@ class LLMRequestSubStage(Stage):
                         )
                     )
         else:
-            async for _ in requesting():
+            async for _ in run_agent(agent_runner, self.max_step, self.show_tool_use):
                 yield
 
+        await self._save_to_history(event, req, agent_runner.get_final_llm_resp())
+
         # 异步处理 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())
+        asyncio.create_task(
+            Metric.upload(
+                llm_tick=1,
+                model_name=agent_runner.provider.get_model(),
+                provider_type=agent_runner.provider.meta().type,
+            )
+        )
 
     async def _handle_webchat(
         self, event: AstrMessageEvent, req: ProviderRequest, prov: Provider
@@ -287,7 +555,23 @@ class LLMRequestSubStage(Stage):
             latest_pair = messages[-2:]
             if not latest_pair:
                 return
-            cleaned_text = "User: " + latest_pair[0].get("content", "").strip()
+            content = latest_pair[0].get("content", "")
+            if isinstance(content, list):
+                # 多模态
+                text_parts = []
+                for item in content:
+                    if isinstance(item, dict):
+                        if item.get("type") == "text":
+                            text_parts.append(item.get("text", ""))
+                        elif item.get("type") == "image":
+                            text_parts.append("[图片]")
+                    elif isinstance(item, str):
+                        text_parts.append(item)
+                cleaned_text = "User: " + " ".join(text_parts).strip()
+            elif isinstance(content, str):
+                cleaned_text = "User: " + content.strip()
+            else:
+                return
             logger.debug(f"WebChat 对话标题生成请求，清理后的文本: {cleaned_text}")
             llm_resp = await prov.text_chat(
                 system_prompt="You are expert in summarizing user's query.",
@@ -307,19 +591,10 @@ class LLMRequestSubStage(Stage):
                 if not title or "<None>" in title:
                     return
                 await self.conv_manager.update_conversation_title(
-                    event.unified_msg_origin, title=title
+                    unified_msg_origin=event.unified_msg_origin,
+                    title=title,
+                    conversation_id=req.conversation.cid,
                 )
-                # 由于 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,
@@ -335,6 +610,10 @@ class LLMRequestSubStage(Stage):
         ):
             return
 
+        if not llm_response.completion_text and not req.tool_calls_result:
+            logger.debug("LLM 响应为空，不保存记录。")
+            return
+
         # 历史上下文
         messages = copy.deepcopy(req.contexts)
         # 这一轮对话请求的用户输入

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

@@ -2,7 +2,7 @@
 本地 Agent 模式的 AstrBot 插件调用 Stage
 """
 
-from ...context import PipelineContext
+from ...context import PipelineContext, call_handler
 from ..stage import Stage
 from typing import Dict, Any, List, AsyncGenerator, Union
 from astrbot.core.platform.astr_message_event import AstrMessageEvent
@@ -33,24 +33,16 @@ class StarRequestSubStage(Stage):
             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} 在当前平台不兼容，跳过执行"
+            params = handlers_parsed_params.get(handler.handler_full_name, {})
+            md = star_map.get(handler.handler_module_path)
+            if not md:
+                logger.warning(
+                    f"Cannot find plugin for given handler module path: {handler.handler_module_path}"
                 )
                 continue
-
-            params = handlers_parsed_params.get(handler.handler_full_name, {})
+            logger.debug(f"plugin -> {md.name} - {handler.handler_name}")
             try:
-                if handler.handler_module_path not in star_map:
-                    continue
-                logger.debug(
-                    f"plugin -> {star_map.get(handler.handler_module_path).name} - {handler.handler_name}"
-                )
-                wrapper = self.ctx.call_handler(event, handler.handler, **params)
+                wrapper = call_handler(event, handler.handler, **params)
                 async for ret in wrapper:
                     yield ret
                 event.clear_result()  # 清除上一个 handler 的结果
@@ -59,7 +51,7 @@ class StarRequestSubStage(Stage):
                 logger.error(f"Star {handler.handler_full_name} handle error: {e}")
 
                 if event.is_at_or_wake_command:
-                    ret = f":(\n\n在调用插件 {star_map.get(handler.handler_module_path).name} 的处理函数 {handler.handler_name} 时出现异常：{e}"
+                    ret = f":(\n\n在调用插件 {md.name} 的处理函数 {handler.handler_name} 时出现异常：{e}"
                     event.set_result(MessageEventResult().message(ret))
                     yield
                     event.clear_result()

astrbot/core/pipeline/respond/stage.py

@@ -1,17 +1,15 @@
 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 ..context import PipelineContext, call_event_hook
 from astrbot.core.platform.astr_message_event import AstrMessageEvent
 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 BaseMessageComponent, ComponentType
+from astrbot.core.star.star_handler import EventType
 from astrbot.core.utils.path_util import path_Mapping
 from astrbot.core.utils.session_lock import session_lock_manager
 
@@ -114,6 +112,43 @@ class RespondStage(Stage):
         # 如果所有组件都为空
         return True
 
+    def is_seg_reply_required(self, event: AstrMessageEvent) -> bool:
+        """检查是否需要分段回复"""
+        if not self.enable_seg:
+            return False
+
+        if self.only_llm_result and not event.get_result().is_llm_result():
+            return False
+
+        if event.get_platform_name() in [
+            "qq_official",
+            "weixin_official_account",
+            "dingtalk",
+        ]:
+            return False
+
+        return True
+
+    def _extract_comp(
+        self,
+        raw_chain: list[BaseMessageComponent],
+        extract_types: set[ComponentType],
+        modify_raw_chain: bool = True,
+    ):
+        extracted = []
+        if modify_raw_chain:
+            remaining = []
+            for comp in raw_chain:
+                if comp.type in extract_types:
+                    extracted.append(comp)
+                else:
+                    remaining.append(comp)
+            raw_chain[:] = remaining
+        else:
+            extracted = [comp for comp in raw_chain if comp.type in extract_types]
+
+        return extracted
+
     async def process(
         self, event: AstrMessageEvent
     ) -> Union[None, AsyncGenerator[None, None]]:
@@ -123,12 +158,19 @@ class RespondStage(Stage):
         if result.result_content_type == ResultContentType.STREAMING_FINISH:
             return
 
+        logger.info(
+            f"Prepare to send - {event.get_sender_name()}/{event.get_sender_id()}: {event._outline_chain(result.chain)}"
+        )
+
         if result.result_content_type == ResultContentType.STREAMING_RESULT:
+            if result.async_stream is None:
+                logger.warning("async_stream 为空，跳过发送。")
+                return
             # 流式结果直接交付平台适配器处理
             use_fallback = self.config.get("provider_settings", {}).get(
                 "streaming_segmented", False
             )
-            logger.info(f"应用流式输出({event.get_platform_name()})")
+            logger.info(f"应用流式输出({event.get_platform_id()})")
             await event.send_streaming(result.async_stream, use_fallback)
             return
         elif len(result.chain) > 0:
@@ -144,93 +186,85 @@ class RespondStage(Stage):
             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)
+            # 将 Plain 为空的消息段移除
+            result.chain = [
+                comp
+                for comp in result.chain
+                if not (
+                    isinstance(comp, Comp.Plain)
+                    and (not comp.text or not comp.text.strip())
+                )
             ]
 
-            if (
-                self.enable_seg
-                and (
-                    (self.only_llm_result and result.is_llm_result())
-                    or not self.only_llm_result
+            # 发送消息链
+            # Record 需要强制单独发送
+            need_separately = {ComponentType.Record}
+            if self.is_seg_reply_required(event):
+                header_comps = self._extract_comp(
+                    result.chain,
+                    {ComponentType.Reply, ComponentType.At},
+                    modify_raw_chain=True,
                 )
-                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, Comp.At):
-                            decorated_comps.append(comp)
-                            result.chain.remove(comp)
-                            break
-                if self.reply_with_quote:
-                    for comp in result.chain:
-                        if isinstance(comp, Comp.Reply):
-                            decorated_comps.append(comp)
-                            result.chain.remove(comp)
-                            break
-
-                # leverage lock to guarentee the order of message sending among different events
+                if not result.chain or len(result.chain) == 0:
+                    # may fix #2670
+                    logger.warning(
+                        f"实际消息链为空, 跳过发送阶段。header_chain: {header_comps}, actual_chain: {result.chain}"
+                    )
+                    return
                 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:
+                    for comp in result.chain:
                         i = await self._calc_comp_interval(comp)
                         await asyncio.sleep(i)
                         try:
-                            await event.send(MessageChain([*decorated_comps, comp]))
-                            decorated_comps = []  # 清空已发送的装饰组件
+                            if comp.type in need_separately:
+                                await event.send(MessageChain([comp]))
+                            else:
+                                await event.send(MessageChain([*header_comps, comp]))
+                                header_comps.clear()
                         except Exception as e:
-                            logger.error(f"发送消息失败: {e} chain: {result.chain}")
-                            break
+                            logger.error(
+                                f"发送消息链失败: chain = {MessageChain([comp])}, error = {e}",
+                                exc_info=True,
+                            )
             else:
-                for rcomp in record_comps:
+                if all(
+                    comp.type in {ComponentType.Reply, ComponentType.At}
+                    for comp in result.chain
+                ):
+                    # may fix #2670
+                    logger.warning(
+                        f"消息链全为 Reply 和 At 消息段, 跳过发送阶段。chain: {result.chain}"
+                    )
+                    return
+                sep_comps = self._extract_comp(
+                    result.chain,
+                    need_separately,
+                    modify_raw_chain=True,
+                )
+                for comp in sep_comps:
+                    chain = MessageChain([comp])
                     try:
-                        await event.send(MessageChain([rcomp]))
+                        await event.send(chain)
                     except Exception as e:
-                        logger.error(f"发送消息失败: {e} chain: {result.chain}")
+                        logger.error(
+                            f"发送消息链失败: chain = {chain}, error = {e}",
+                            exc_info=True,
+                        )
+                chain = MessageChain(result.chain)
+                if result.chain and len(result.chain) > 0:
+                    try:
+                        await event.send(chain)
+                    except Exception as e:
+                        logger.error(
+                            f"发送消息链失败: chain = {chain}, error = {e}",
+                            exc_info=True,
+                        )
 
-                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, platform_id=event.get_platform_id()
-        )
-        for handler in handlers:
-            try:
-                logger.debug(
-                    f"hook(on_after_message_sent) -> {star_map[handler.handler_module_path].name} - {handler.handler_name}"
-                )
-                await handler.handler(event)
-            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 call_event_hook(event, EventType.OnAfterMessageSentEvent):
+            return
 
         event.clear_result()

astrbot/core/pipeline/result_decorate/stage.py

@@ -36,6 +36,7 @@ class ResultDecorateStage(Stage):
             self.t2i_word_threshold = 150
         self.t2i_strategy = ctx.astrbot_config["t2i_strategy"]
         self.t2i_use_network = self.t2i_strategy == "remote"
+        self.t2i_active_template = ctx.astrbot_config["t2i_active_template"]
 
         self.forward_threshold = ctx.astrbot_config["platform_settings"][
             "forward_threshold"
@@ -64,9 +65,10 @@ class ResultDecorateStage(Stage):
         ]
         self.content_safe_check_stage = None
         if self.content_safe_check_reply:
-            for stage in registered_stages:
-                if stage.__class__.__name__ == "ContentSafetyCheckStage":
-                    self.content_safe_check_stage = stage
+            for stage_cls in registered_stages:
+                if stage_cls.__name__ == "ContentSafetyCheckStage":
+                    self.content_safe_check_stage = stage_cls()
+                    await self.content_safe_check_stage.initialize(ctx)
 
     async def process(
         self, event: AstrMessageEvent
@@ -98,7 +100,7 @@ class ResultDecorateStage(Stage):
 
         # 发送消息前事件钩子
         handlers = star_handlers_registry.get_handlers_by_event_type(
-            EventType.OnDecoratingResultEvent, platform_id=event.get_platform_id()
+            EventType.OnDecoratingResultEvent, plugins_name=event.plugins_name
         )
         for handler in handlers:
             try:
@@ -181,56 +183,60 @@ class ResultDecorateStage(Stage):
             if (
                 self.ctx.astrbot_config["provider_tts_settings"]["enable"]
                 and result.is_llm_result()
-                and tts_provider
                 and SessionServiceManager.should_process_tts_request(event)
             ):
-                new_chain = []
-                for comp in result.chain:
-                    if isinstance(comp, Plain) and len(comp.text) > 1:
-                        try:
-                            logger.info(f"TTS 请求: {comp.text}")
-                            audio_path = await tts_provider.get_audio(comp.text)
-                            logger.info(f"TTS 结果: {audio_path}")
-                            if not audio_path:
-                                logger.error(
-                                    f"由于 TTS 音频文件未找到，消息段转语音失败: {comp.text}"
+                if not tts_provider:
+                    logger.warning(
+                        f"会话 {event.unified_msg_origin} 未配置文本转语音模型。"
+                    )
+                else:
+                    new_chain = []
+                    for comp in result.chain:
+                        if isinstance(comp, Plain) and len(comp.text) > 1:
+                            try:
+                                logger.info(f"TTS 请求: {comp.text}")
+                                audio_path = await tts_provider.get_audio(comp.text)
+                                logger.info(f"TTS 结果: {audio_path}")
+                                if not audio_path:
+                                    logger.error(
+                                        f"由于 TTS 音频文件未找到，消息段转语音失败: {comp.text}"
+                                    )
+                                    new_chain.append(comp)
+                                    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)
-                                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 失败，使用文本发送。")
+                        else:
                             new_chain.append(comp)
-                    else:
-                        new_chain.append(comp)
-                result.chain = new_chain
+                    result.chain = new_chain
 
             # 文本转图片
             elif (
@@ -246,7 +252,10 @@ class ResultDecorateStage(Stage):
                     render_start = time.time()
                     try:
                         url = await html_renderer.render_t2i(
-                            plain_str, return_url=True, use_network=self.t2i_use_network
+                            plain_str,
+                            return_url=True,
+                            use_network=self.t2i_use_network,
+                            template_name=self.t2i_active_template,
                         )
                     except BaseException:
                         logger.error("文本转图片失败，使用文本发送。")
@@ -270,7 +279,6 @@ class ResultDecorateStage(Stage):
                             result.chain = [Image.fromFileSystem(url)]
 
             # 触发转发消息
-            has_forwarded = False
             if event.get_platform_name() == "aiocqhttp":
                 word_cnt = 0
                 for comp in result.chain:
@@ -281,9 +289,9 @@ class ResultDecorateStage(Stage):
                         uin=event.get_self_id(), name="AstrBot", content=[*result.chain]
                     )
                     result.chain = [node]
-                    has_forwarded = True
 
-            if not has_forwarded:
+            has_plain = any(isinstance(item, Plain) for item in result.chain)
+            if has_plain:
                 # at 回复
                 if (
                     self.reply_with_mention

astrbot/core/pipeline/scheduler.py

@@ -11,16 +11,17 @@ class PipelineScheduler:
 
     def __init__(self, context: PipelineContext):
         registered_stages.sort(
-            key=lambda x: STAGES_ORDER.index(x.__class__.__name__)
+            key=lambda x: STAGES_ORDER.index(x.__name__)
         )  # 按照顺序排序
         self.ctx = context  # 上下文对象
+        self.stages = []  # 存储阶段实例
 
     async def initialize(self):
         """初始化管道调度器时, 初始化所有阶段"""
-        for stage in registered_stages:
-            # logger.debug(f"初始化阶段 {stage.__class__ .__name__}")
-
-            await stage.initialize(self.ctx)
+        for stage_cls in registered_stages:
+            stage_instance = stage_cls()  # 创建实例
+            await stage_instance.initialize(self.ctx)
+            self.stages.append(stage_instance)
 
     async def _process_stages(self, event: AstrMessageEvent, from_stage=0):
         """依次执行各个阶段
@@ -29,9 +30,9 @@ class PipelineScheduler:
             event (AstrMessageEvent): 事件对象
             from_stage (int): 从第几个阶段开始执行, 默认从0开始
         """
-        for i in range(from_stage, len(registered_stages)):
-            stage = registered_stages[i]  # 获取当前要执行的阶段
-            # logger.debug(f"执行阶段 {stage.__class__ .__name__}")
+        for i in range(from_stage, len(self.stages)):
+            stage = self.stages[i]  # 获取当前要执行的阶段
+            # logger.debug(f"执行阶段 {stage.__class__.__name__}")
             coroutine = stage.process(
                 event
             )  # 调用阶段的process方法, 返回协程或者异步生成器
@@ -73,7 +74,7 @@ class PipelineScheduler:
         await self._process_stages(event)
 
         # 如果没有发送操作, 则发送一个空消息, 以便于后续的处理
-        if event.get_platform_name() == "webchat":
+        if event.get_platform_name() in ["webchat", "wecom_ai_bot"]:
             await event.send(None)
 
         logger.debug("pipeline 执行完毕。")

astrbot/core/pipeline/session_status_check/stage.py

@@ -11,7 +11,8 @@ class SessionStatusCheckStage(Stage):
     """检查会话是否整体启用"""
 
     async def initialize(self, ctx: PipelineContext) -> None:
-        pass
+        self.ctx = ctx
+        self.conv_mgr = ctx.plugin_manager.context.conversation_manager
 
     async def process(
         self, event: AstrMessageEvent
@@ -19,4 +20,14 @@ class SessionStatusCheckStage(Stage):
         # 检查会话是否整体启用
         if not SessionServiceManager.is_session_enabled(event.unified_msg_origin):
             logger.debug(f"会话 {event.unified_msg_origin} 已被关闭，已终止事件传播。")
+
+            # workaround for #2309
+            conv_id = await self.conv_mgr.get_curr_conversation_id(
+                event.unified_msg_origin
+            )
+            if not conv_id:
+                await self.conv_mgr.new_conversation(
+                    event.unified_msg_origin, platform_id=event.get_platform_id()
+                )
+
             event.stop_event()

astrbot/core/pipeline/stage.py

@@ -1,15 +1,15 @@
 from __future__ import annotations
 import abc
-from typing import List, AsyncGenerator, Union
+from typing import List, AsyncGenerator, Union, Type
 from astrbot.core.platform.astr_message_event import AstrMessageEvent
 from .context import PipelineContext
 
-registered_stages: List[Stage] = []  # 维护了所有已注册的 Stage 实现类
+registered_stages: List[Type[Stage]] = []  # 维护了所有已注册的 Stage 实现类类型
 
 
 def register_stage(cls):
     """一个简单的装饰器，用于注册 pipeline 包下的 Stage 实现类"""
-    registered_stages.append(cls())
+    registered_stages.append(cls)
     return cls
 
 

astrbot/core/pipeline/waking_check/stage.py

@@ -5,6 +5,7 @@ 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.star.filter.permission import PermissionTypeFilter
+from astrbot.core.star.filter.command_group import CommandGroupFilter
 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
@@ -112,8 +113,17 @@ class WakingCheckStage(Stage):
         activated_handlers = []
         handlers_parsed_params = {}  # 注册了指令的 handler
 
+        # 将 plugins_name 设置到 event 中
+        enabled_plugins_name = self.ctx.astrbot_config.get("plugin_set", ["*"])
+        if enabled_plugins_name == ["*"]:
+            # 如果是 *，则表示所有插件都启用
+            event.plugins_name = None
+        else:
+            event.plugins_name = enabled_plugins_name
+        logger.debug(f"enabled_plugins_name: {enabled_plugins_name}")
+
         for handler in star_handlers_registry.get_handlers_by_event_type(
-            EventType.AdapterMessageEvent
+            EventType.AdapterMessageEvent, plugins_name=event.plugins_name
         ):
             # filter 需满足 AND 逻辑关系
             passed = True
@@ -161,11 +171,15 @@ class WakingCheckStage(Stage):
                 is_wake = True
                 event.is_wake = True
 
-                activated_handlers.append(handler)
-                if "parsed_params" in event.get_extra():
-                    handlers_parsed_params[handler.handler_full_name] = event.get_extra(
-                        "parsed_params"
-                    )
+                is_group_cmd_handler = any(
+                    isinstance(f, CommandGroupFilter) for f in handler.event_filters
+                )
+                if not is_group_cmd_handler:
+                    activated_handlers.append(handler)
+                    if "parsed_params" in event.get_extra(default={}):
+                        handlers_parsed_params[handler.handler_full_name] = (
+                            event.get_extra("parsed_params")
+                        )
 
             event._extras.pop("parsed_params", None)
 

astrbot/core/platform/astr_message_event.py

@@ -3,9 +3,10 @@ import asyncio
 import re
 import hashlib
 import uuid
-from dataclasses import dataclass
-from typing import List, Union, Optional, AsyncGenerator
 
+from typing import List, Union, Optional, AsyncGenerator, TypeVar, Any
+
+from astrbot import logger
 from astrbot.core.db.po import Conversation
 from astrbot.core.message.components import (
     Plain,
@@ -23,21 +24,9 @@ from astrbot.core.provider.entities import ProviderRequest
 from astrbot.core.utils.metrics import Metric
 from .astrbot_message import AstrBotMessage, Group
 from .platform_metadata import PlatformMetadata
+from .message_session import MessageSession, MessageSesion  # noqa
 
-
-@dataclass
-class MessageSesion:
-    platform_name: str
-    message_type: MessageType
-    session_id: str
-
-    def __str__(self):
-        return f"{self.platform_name}:{self.message_type.value}:{self.session_id}"
-
-    @staticmethod
-    def from_str(session_str: str):
-        platform_name, message_type, session_id = session_str.split(":")
-        return MessageSesion(platform_name, MessageType(message_type), session_id)
+_VT = TypeVar("_VT")
 
 
 class AstrMessageEvent(abc.ABC):
@@ -62,15 +51,15 @@ class AstrMessageEvent(abc.ABC):
         """是否唤醒(是否通过 WakingStage)"""
         self.is_at_or_wake_command = False
         """是否是 At 机器人或者带有唤醒词或者是私聊(插件注册的事件监听器会让 is_wake 设为 True, 但是不会让这个属性置为 True)"""
-        self._extras = {}
+        self._extras: dict[str, Any] = {}
         self.session = MessageSesion(
-            platform_name=platform_meta.name,
+            platform_name=platform_meta.id,
             message_type=message_obj.type,
             session_id=session_id,
         )
         self.unified_msg_origin = str(self.session)
         """统一的消息来源字符串。格式为 platform_name:message_type:session_id"""
-        self._result: MessageEventResult = None
+        self._result: MessageEventResult | None = None
         """消息事件的结果"""
 
         self._has_send_oper = False
@@ -78,13 +67,23 @@ class AstrMessageEvent(abc.ABC):
         self.call_llm = False
         """是否在此消息事件中禁止默认的 LLM 请求"""
 
+        self.plugins_name: list[str] | None = None
+        """该事件启用的插件名称列表。None 表示所有插件都启用。空列表表示没有启用任何插件。"""
+
         # back_compability
         self.platform = platform_meta
 
     def get_platform_name(self):
+        """获取这个事件所属的平台的类型（如 aiocqhttp, slack, discord 等）。
+
+        NOTE: 用户可能会同时运行多个相同类型的平台适配器。"""
         return self.platform_meta.name
 
     def get_platform_id(self):
+        """获取这个事件所属的平台的 ID。
+
+        NOTE: 用户可能会同时运行多个相同类型的平台适配器，但能确定的是 ID 是唯一的。
+        """
         return self.platform_meta.id
 
     def get_message_str(self) -> str:
@@ -176,18 +175,21 @@ class AstrMessageEvent(abc.ABC):
         """
         self._extras[key] = value
 
-    def get_extra(self, key=None):
+    def get_extra(
+        self, key: str | None = None, default: _VT = None
+    ) -> dict[str, Any] | _VT:
         """
         获取额外的信息。
         """
         if key is None:
             return self._extras
-        return self._extras.get(key, None)
+        return self._extras.get(key, default)
 
     def clear_extra(self):
         """
         清除额外的信息。
         """
+        logger.info(f"清除 {self.get_platform_name()} 的额外信息: {self._extras}")
         self._extras.clear()
 
     def is_private_chat(self) -> bool:
@@ -414,6 +416,16 @@ class AstrMessageEvent(abc.ABC):
         )
         self._has_send_oper = True
 
+    async def react(self, emoji: str):
+        """
+        对消息添加表情回应。
+
+        默认实现为发送一条包含该表情的消息。
+        注意：此实现并不一定符合所有平台的原生“表情回应”行为。
+        如需支持平台原生的消息反应功能，请在对应平台的子类中重写本方法。
+        """
+        await self.send(MessageChain([Plain(emoji)]))
+
     async def get_group(self, group_id: str = None, **kwargs) -> Optional[Group]:
         """获取一个群聊的数据, 如果不填写 group_id: 如果是私聊消息，返回 None。如果是群聊消息，返回当前群聊的数据。
 

astrbot/core/platform/astrbot_message.py

@@ -55,7 +55,7 @@ class AstrBotMessage:
     self_id: str  # 机器人的识别id
     session_id: str  # 会话id。取决于 unique_session 的设置。
     message_id: str  # 消息id
-    group_id: str = ""  # 群组id，如果为私聊，则为空
+    group: Group  # 群组
     sender: MessageMember  # 发送者
     message: List[BaseMessageComponent]  # 消息链使用 Nakuru 的消息链格式
     message_str: str  # 最直观的纯文本消息字符串
@@ -64,6 +64,28 @@ class AstrBotMessage:
 
     def __init__(self) -> None:
         self.timestamp = int(time.time())
+        self.group = None
 
     def __str__(self) -> str:
         return str(self.__dict__)
+
+    @property
+    def group_id(self) -> str:
+        """
+        向后兼容的 group_id 属性
+        群组id，如果为私聊，则为空
+        """
+        if self.group:
+            return self.group.group_id
+        return ""
+
+    @group_id.setter
+    def group_id(self, value: str):
+        """设置 group_id"""
+        if value:
+            if self.group:
+                self.group.group_id = value
+            else:
+                self.group = Group(group_id=value)
+        else:
+            self.group = None

astrbot/core/platform/manager.py

@@ -6,6 +6,7 @@ from typing import List
 from asyncio import Queue
 from .register import platform_cls_map
 from astrbot.core import logger
+from astrbot.core.star.star_handler import star_handlers_registry, star_map, EventType
 from .sources.webchat.webchat_adapter import WebChatAdapter
 
 
@@ -18,6 +19,9 @@ class PlatformManager:
 
         self.platforms_config = config["platform"]
         self.settings = config["platform_settings"]
+        """NOTE: 这里是 default 的配置文件，以保证最大的兼容性；
+        这个配置中的 unique_session 需要特殊处理，
+        约定整个项目中对 unique_session 的引用都从 default 的配置中获取"""
         self.event_queue = event_queue
 
     async def initialize(self):
@@ -63,25 +67,43 @@ class PlatformManager:
                         WeChatPadProAdapter,  # noqa: F401
                     )
                 case "lark":
-                    from .sources.lark.lark_adapter import LarkPlatformAdapter  # noqa: F401
+                    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
+                    from .sources.telegram.tg_adapter import (
+                        TelegramPlatformAdapter,  # noqa: F401
+                    )
                 case "wecom":
-                    from .sources.wecom.wecom_adapter import WecomPlatformAdapter  # noqa: F401
+                    from .sources.wecom.wecom_adapter import (
+                        WecomPlatformAdapter,  # noqa: F401
+                    )
+                case "wecom_ai_bot":
+                    from .sources.wecom_ai_bot.wecomai_adapter import (
+                        WecomAIBotAdapter,  # noqa: F401
+                    )
                 case "weixin_official_account":
                     from .sources.weixin_official_account.weixin_offacc_adapter import (
-                        WeixinOfficialAccountPlatformAdapter,  # noqa
+                        WeixinOfficialAccountPlatformAdapter,  # noqa: F401
                     )
                 case "discord":
                     from .sources.discord.discord_platform_adapter import (
                         DiscordPlatformAdapter,  # noqa: F401
                     )
+                case "misskey":
+                    from .sources.misskey.misskey_adapter import (
+                        MisskeyPlatformAdapter,  # noqa: F401
+                    )
                 case "slack":
                     from .sources.slack.slack_adapter import SlackAdapter  # noqa: F401
+                case "satori":
+                    from .sources.satori.satori_adapter import (
+                        SatoriPlatformAdapter,  # noqa: F401
+                    )
         except (ImportError, ModuleNotFoundError) as e:
             logger.error(
                 f"加载平台适配器 {platform_config['type']} 失败，原因：{e}。请检查依赖库是否安装。提示：可以在 管理面板->控制台->安装Pip库 中安装依赖库。"
@@ -110,6 +132,17 @@ class PlatformManager:
                 )
             )
         )
+        handlers = star_handlers_registry.get_handlers_by_event_type(
+            EventType.OnPlatformLoadedEvent
+        )
+        for handler in handlers:
+            try:
+                logger.info(
+                    f"hook(on_platform_loaded) -> {star_map[handler.handler_module_path].name} - {handler.handler_name}"
+                )
+                await handler.handler()
+            except Exception:
+                logger.error(traceback.format_exc())
 
     async def _task_wrapper(self, task: asyncio.Task):
         try:

astrbot/core/platform/message_session.py

@@ -0,0 +1,28 @@
+from astrbot.core.platform.message_type import MessageType
+from dataclasses import dataclass
+
+
+@dataclass
+class MessageSession:
+    """描述一条消息在 AstrBot 中对应的会话的唯一标识。
+    如果您需要实例化 MessageSession，请不要给 platform_id 赋值（或者同时给 platform_name 和 platform_id 赋值相同值）。它会在 __post_init__ 中自动设置为 platform_name 的值。"""
+
+    platform_name: str
+    """平台适配器实例的唯一标识符。自 AstrBot v4.0.0 起，该字段实际为 platform_id。"""
+    message_type: MessageType
+    session_id: str
+    platform_id: str = None
+
+    def __str__(self):
+        return f"{self.platform_id}:{self.message_type.value}:{self.session_id}"
+
+    def __post_init__(self):
+        self.platform_id = self.platform_name
+
+    @staticmethod
+    def from_str(session_str: str):
+        platform_id, message_type, session_id = session_str.split(":")
+        return MessageSession(platform_id, MessageType(message_type), session_id)
+
+
+MessageSesion = MessageSession  # back compatibility

astrbot/core/platform/platform.py

@@ -5,7 +5,7 @@ from asyncio import Queue
 from .platform_metadata import PlatformMetadata
 from .astr_message_event import AstrMessageEvent
 from astrbot.core.message.message_event_result import MessageChain
-from .astr_message_event import MessageSesion
+from .message_session import MessageSesion
 from astrbot.core.utils.metrics import Metric
 
 

astrbot/core/platform/platform_metadata.py

@@ -4,7 +4,7 @@ from dataclasses import dataclass
 @dataclass
 class PlatformMetadata:
     name: str
-    """平台的名称"""
+    """平台的名称，即平台的类型，如 aiocqhttp, discord, slack"""
     description: str
     """平台的描述"""
     id: str = None
@@ -14,3 +14,5 @@ class PlatformMetadata:
     """平台的默认配置模板"""
     adapter_display_name: str = None
     """显示在 WebUI 配置页中的平台名称，如空则是 name"""
+    logo_path: str = None
+    """平台适配器的 logo 文件路径（相对于插件目录）"""

astrbot/core/platform/register.py

@@ -13,10 +13,12 @@ def register_platform_adapter(
     desc: str,
     default_config_tmpl: dict = None,
     adapter_display_name: str = None,
+    logo_path: str = None,
 ):
     """用于注册平台适配器的带参装饰器。
 
     default_config_tmpl 指定了平台适配器的默认配置模板。用户填写好后将会作为 platform_config 传入你的 Platform 类的实现类。
+    logo_path 指定了平台适配器的 logo 文件路径，是相对于插件目录的路径。
     """
 
     def decorator(cls):
@@ -39,6 +41,7 @@ def register_platform_adapter(
             description=desc,
             default_config_tmpl=default_config_tmpl,
             adapter_display_name=adapter_display_name,
+            logo_path=logo_path,
         )
         platform_registry.append(pm)
         platform_cls_map[adapter_name] = cls

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

@@ -67,12 +67,19 @@ class AiocqhttpMessageEvent(AstrMessageEvent):
         session_id: str,
         messages: list[dict],
     ):
-        if event:
-            await bot.send(event=event, message=messages)
-        elif is_group:
+        # session_id 必须是纯数字字符串
+        session_id = int(session_id) if session_id.isdigit() else None
+
+        if is_group and isinstance(session_id, int):
             await bot.send_group_msg(group_id=session_id, message=messages)
-        else:
+        elif not is_group and isinstance(session_id, int):
             await bot.send_private_msg(user_id=session_id, message=messages)
+        elif isinstance(event, Event):  # 最后兜底
+            await bot.send(event=event, message=messages)
+        else:
+            raise ValueError(
+                f"无法发送消息：缺少有效的数字 session_id({session_id}) 或 event({event})"
+            )
 
     @classmethod
     async def send_message(
@@ -83,7 +90,15 @@ class AiocqhttpMessageEvent(AstrMessageEvent):
         is_group: bool = False,
         session_id: str = None,
     ):
-        """发送消息"""
+        """发送消息至 QQ 协议端（aiocqhttp）。
+
+        Args:
+            bot (CQHttp): aiocqhttp 机器人实例
+            message_chain (MessageChain): 要发送的消息链
+            event (Event | None, optional): aiocqhttp 事件对象.
+            is_group (bool, optional): 是否为群消息.
+            session_id (str | None, optional): 会话 ID（群号或 QQ 号
+        """
 
         # 转发消息、文件消息不能和普通消息混在一起发送
         send_one_by_one = any(
@@ -122,18 +137,15 @@ class AiocqhttpMessageEvent(AstrMessageEvent):
 
     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()
+        event = getattr(self.message_obj, "raw_message", None)
+
+        is_group = bool(self.get_group_id())
+        session_id = self.get_group_id() if is_group else self.get_sender_id()
+
         await self.send_message(
             bot=self.bot,
             message_chain=message,
-            event=event,
+            event=event,  # 不强制要求一定是 Event
             is_group=is_group,
             session_id=session_id,
         )

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

@@ -182,11 +182,13 @@ class AiocqhttpAdapter(Platform):
         abm = AstrBotMessage()
         abm.self_id = str(event.self_id)
         abm.sender = MessageMember(
-            str(event.sender["user_id"]), event.sender["nickname"]
+            str(event.sender["user_id"]),
+            event.sender.get("card") or event.sender.get("nickname", "N/A"),
         )
         if event["message_type"] == "group":
             abm.type = MessageType.GROUP_MESSAGE
             abm.group_id = str(event.group_id)
+            abm.group.group_name = event.get("group_name", "N/A")
         elif event["message_type"] == "private":
             abm.type = MessageType.FRIEND_MESSAGE
         if self.unique_session and abm.type == MessageType.GROUP_MESSAGE:
@@ -308,13 +310,22 @@ class AiocqhttpAdapter(Platform):
                             continue
 
                         at_info = await self.bot.call_action(
-                            action="get_stranger_info",
+                            action="get_group_member_info",
+                            group_id=event.group_id,
                             user_id=int(m["data"]["qq"]),
+                            no_cache=False,
                         )
                         if at_info:
-                            nickname = at_info.get("nick", "") or at_info.get(
-                                "nickname", ""
-                            )
+                            nickname = at_info.get("card", "")
+                            if nickname == "":
+                                at_info = await self.bot.call_action(
+                                    action="get_stranger_info",
+                                    user_id=int(m["data"]["qq"]),
+                                    no_cache=False,
+                                )
+                                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(

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

@@ -26,7 +26,7 @@ class DingtalkMessageEvent(AstrMessageEvent):
                 await asyncio.get_event_loop().run_in_executor(
                     None,
                     client.reply_markdown,
-                    "AstrBot",
+                    segment.text,
                     segment.text,
                     self.message_obj.raw_message,
                 )
@@ -54,9 +54,9 @@ class DingtalkMessageEvent(AstrMessageEvent):
                     logger.debug(f"send image: {ret}")
 
                 except Exception as e:
-                    logger.error(f"钉钉图片处理失败: {e}")
-                    logger.warning(f"跳过图片发送: {image_path}")
+                    logger.warning(f"钉钉图片处理失败: {e}, 跳过图片发送")
                     continue
+
     async def send(self, message: MessageChain):
         await self.send_with_client(self.client, message)
         await super().send(message)

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

@@ -41,7 +41,8 @@ class DiscordBotClient(discord.Bot):
                 await self.on_ready_once_callback()
             except Exception as e:
                 logger.error(
-                    f"[Discord] on_ready_once_callback 执行失败: {e}", exc_info=True)
+                    f"[Discord] on_ready_once_callback 执行失败: {e}", exc_info=True
+                )
 
     def _create_message_data(self, message: discord.Message) -> dict:
         """从 discord.Message 创建数据字典"""
@@ -90,7 +91,6 @@ class DiscordBotClient(discord.Bot):
             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

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

@@ -79,9 +79,12 @@ class DiscordButton(BaseMessageComponent):
         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
@@ -98,7 +101,6 @@ class DiscordView(BaseMessageComponent):
         self.components = components or []
         self.timeout = timeout
 
-
     def to_discord_view(self) -> discord.ui.View:
         """转换为Discord View对象"""
         view = discord.ui.View(timeout=self.timeout)

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

@@ -53,7 +53,13 @@ class DiscordPlatformEvent(AstrMessageEvent):
 
         # 解析消息链为 Discord 所需的对象
         try:
-            content, files, view, embeds, reference_message_id = await self._parse_to_discord(message)
+            (
+                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
@@ -206,8 +212,7 @@ class DiscordPlatformEvent(AstrMessageEvent):
                         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)
+                                discord.File(BytesIO(file_bytes), filename=i.name)
                             )
                         else:
                             logger.warning(

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

@@ -107,6 +107,22 @@ class LarkMessageEvent(AstrMessageEvent):
 
         await super().send(message)
 
+    async def react(self, emoji: str):
+        request = (
+            CreateMessageReactionRequest.builder()
+            .message_id(self.message_obj.message_id)
+            .request_body(
+                CreateMessageReactionRequestBody.builder()
+                .reaction_type(Emoji.builder().emoji_type(emoji).build())
+                .build()
+            )
+            .build()
+        )
+        response = await self.bot.im.v1.message_reaction.acreate(request)
+        if not response.success():
+            logger.error(f"发送飞书表情回应失败({response.code}): {response.msg}")
+            return None
+
     async def send_streaming(self, generator, use_fallback: bool = False):
         buffer = None
         async for chain in generator:

astrbot/core/platform/sources/misskey/misskey_adapter.py

@@ -0,0 +1,391 @@
+import asyncio
+import json
+from typing import Dict, Any, Optional, Awaitable
+
+from astrbot.api import logger
+from astrbot.api.event import MessageChain
+from astrbot.api.platform import (
+    AstrBotMessage,
+    Platform,
+    PlatformMetadata,
+    register_platform_adapter,
+)
+from astrbot.core.platform.astr_message_event import MessageSession
+import astrbot.api.message_components as Comp
+
+from .misskey_api import MisskeyAPI
+from .misskey_event import MisskeyPlatformEvent
+from .misskey_utils import (
+    serialize_message_chain,
+    resolve_message_visibility,
+    is_valid_user_session_id,
+    is_valid_room_session_id,
+    add_at_mention_if_needed,
+    process_files,
+    extract_sender_info,
+    create_base_message,
+    process_at_mention,
+    cache_user_info,
+    cache_room_info,
+)
+
+
+@register_platform_adapter("misskey", "Misskey 平台适配器")
+class MisskeyPlatformAdapter(Platform):
+    def __init__(
+        self, platform_config: dict, platform_settings: dict, event_queue: asyncio.Queue
+    ) -> None:
+        super().__init__(event_queue)
+        self.config = platform_config or {}
+        self.settings = platform_settings or {}
+        self.instance_url = self.config.get("misskey_instance_url", "")
+        self.access_token = self.config.get("misskey_token", "")
+        self.max_message_length = self.config.get("max_message_length", 3000)
+        self.default_visibility = self.config.get(
+            "misskey_default_visibility", "public"
+        )
+        self.local_only = self.config.get("misskey_local_only", False)
+        self.enable_chat = self.config.get("misskey_enable_chat", True)
+
+        self.unique_session = platform_settings["unique_session"]
+
+        self.api: Optional[MisskeyAPI] = None
+        self._running = False
+        self.client_self_id = ""
+        self._bot_username = ""
+        self._user_cache = {}
+
+    def meta(self) -> PlatformMetadata:
+        default_config = {
+            "misskey_instance_url": "",
+            "misskey_token": "",
+            "max_message_length": 3000,
+            "misskey_default_visibility": "public",
+            "misskey_local_only": False,
+            "misskey_enable_chat": True,
+        }
+        default_config.update(self.config)
+
+        return PlatformMetadata(
+            name="misskey",
+            description="Misskey 平台适配器",
+            id=self.config.get("id", "misskey"),
+            default_config_tmpl=default_config,
+        )
+
+    async def run(self):
+        if not self.instance_url or not self.access_token:
+            logger.error("[Misskey] 配置不完整，无法启动")
+            return
+
+        self.api = MisskeyAPI(self.instance_url, self.access_token)
+        self._running = True
+
+        try:
+            user_info = await self.api.get_current_user()
+            self.client_self_id = str(user_info.get("id", ""))
+            self._bot_username = user_info.get("username", "")
+            logger.info(
+                f"[Misskey] 已连接用户: {self._bot_username} (ID: {self.client_self_id})"
+            )
+        except Exception as e:
+            logger.error(f"[Misskey] 获取用户信息失败: {e}")
+            self._running = False
+            return
+
+        await self._start_websocket_connection()
+
+    async def _start_websocket_connection(self):
+        backoff_delay = 1.0
+        max_backoff = 300.0
+        backoff_multiplier = 1.5
+        connection_attempts = 0
+
+        while self._running:
+            try:
+                connection_attempts += 1
+                if not self.api:
+                    logger.error("[Misskey] API 客户端未初始化")
+                    break
+
+                streaming = self.api.get_streaming_client()
+                streaming.add_message_handler("notification", self._handle_notification)
+                if self.enable_chat:
+                    streaming.add_message_handler(
+                        "newChatMessage", self._handle_chat_message
+                    )
+                    streaming.add_message_handler("_debug", self._debug_handler)
+
+                if await streaming.connect():
+                    logger.info(
+                        f"[Misskey] WebSocket 已连接 (尝试 #{connection_attempts})"
+                    )
+                    connection_attempts = 0  # 重置计数器
+                    await streaming.subscribe_channel("main")
+                    if self.enable_chat:
+                        await streaming.subscribe_channel("messaging")
+                        await streaming.subscribe_channel("messagingIndex")
+                        logger.info("[Misskey] 聊天频道已订阅")
+
+                    backoff_delay = 1.0  # 重置延迟
+                    await streaming.listen()
+                else:
+                    logger.error(
+                        f"[Misskey] WebSocket 连接失败 (尝试 #{connection_attempts})"
+                    )
+
+            except Exception as e:
+                logger.error(
+                    f"[Misskey] WebSocket 异常 (尝试 #{connection_attempts}): {e}"
+                )
+
+            if self._running:
+                logger.info(
+                    f"[Misskey] {backoff_delay:.1f}秒后重连 (下次尝试 #{connection_attempts + 1})"
+                )
+                await asyncio.sleep(backoff_delay)
+                backoff_delay = min(backoff_delay * backoff_multiplier, max_backoff)
+
+    async def _handle_notification(self, data: Dict[str, Any]):
+        try:
+            logger.debug(
+                f"[Misskey] 收到通知事件:\n{json.dumps(data, indent=2, ensure_ascii=False)}"
+            )
+            notification_type = data.get("type")
+            if notification_type in ["mention", "reply", "quote"]:
+                note = data.get("note")
+                if note and self._is_bot_mentioned(note):
+                    logger.info(
+                        f"[Misskey] 处理贴文提及: {note.get('text', '')[:50]}..."
+                    )
+                    message = await self.convert_message(note)
+                    event = MisskeyPlatformEvent(
+                        message_str=message.message_str,
+                        message_obj=message,
+                        platform_meta=self.meta(),
+                        session_id=message.session_id,
+                        client=self.api,
+                    )
+                    self.commit_event(event)
+        except Exception as e:
+            logger.error(f"[Misskey] 处理通知失败: {e}")
+
+    async def _handle_chat_message(self, data: Dict[str, Any]):
+        try:
+            logger.debug(
+                f"[Misskey] 收到聊天事件数据:\n{json.dumps(data, indent=2, ensure_ascii=False)}"
+            )
+
+            sender_id = str(
+                data.get("fromUserId", "") or data.get("fromUser", {}).get("id", "")
+            )
+            if sender_id == self.client_self_id:
+                return
+
+            room_id = data.get("toRoomId")
+            if room_id:
+                raw_text = data.get("text", "")
+                logger.debug(
+                    f"[Misskey] 检查群聊消息: '{raw_text}', 机器人用户名: '{self._bot_username}'"
+                )
+
+                message = await self.convert_room_message(data)
+                logger.info(f"[Misskey] 处理群聊消息: {message.message_str[:50]}...")
+            else:
+                message = await self.convert_chat_message(data)
+                logger.info(f"[Misskey] 处理私聊消息: {message.message_str[:50]}...")
+
+            event = MisskeyPlatformEvent(
+                message_str=message.message_str,
+                message_obj=message,
+                platform_meta=self.meta(),
+                session_id=message.session_id,
+                client=self.api,
+            )
+            self.commit_event(event)
+        except Exception as e:
+            logger.error(f"[Misskey] 处理聊天消息失败: {e}")
+
+    async def _debug_handler(self, data: Dict[str, Any]):
+        logger.debug(
+            f"[Misskey] 收到未处理事件:\n{json.dumps(data, indent=2, ensure_ascii=False)}"
+        )
+
+    def _is_bot_mentioned(self, note: Dict[str, Any]) -> bool:
+        text = note.get("text", "")
+        if not text:
+            return False
+
+        mentions = note.get("mentions", [])
+        if self._bot_username and f"@{self._bot_username}" in text:
+            return True
+        if self.client_self_id in [str(uid) for uid in mentions]:
+            return True
+
+        reply = note.get("reply")
+        if reply and isinstance(reply, dict):
+            reply_user_id = str(reply.get("user", {}).get("id", ""))
+            if reply_user_id == self.client_self_id:
+                return bool(self._bot_username and f"@{self._bot_username}" in text)
+
+        return False
+
+    async def send_by_session(
+        self, session: MessageSession, message_chain: MessageChain
+    ) -> Awaitable[Any]:
+        if not self.api:
+            logger.error("[Misskey] API 客户端未初始化")
+            return await super().send_by_session(session, message_chain)
+
+        try:
+            session_id = session.session_id
+            text, has_at_user = serialize_message_chain(message_chain.chain)
+
+            if not has_at_user and session_id:
+                user_info = self._user_cache.get(session_id)
+                text = add_at_mention_if_needed(text, user_info, has_at_user)
+
+            if not text or not text.strip():
+                logger.warning("[Misskey] 消息内容为空，跳过发送")
+                return await super().send_by_session(session, message_chain)
+
+            if len(text) > self.max_message_length:
+                text = text[: self.max_message_length] + "..."
+
+            if session_id and is_valid_user_session_id(session_id):
+                from .misskey_utils import extract_user_id_from_session_id
+
+                user_id = extract_user_id_from_session_id(session_id)
+                await self.api.send_message(user_id, text)
+            elif session_id and is_valid_room_session_id(session_id):
+                from .misskey_utils import extract_room_id_from_session_id
+
+                room_id = extract_room_id_from_session_id(session_id)
+                await self.api.send_room_message(room_id, text)
+            else:
+                visibility, visible_user_ids = resolve_message_visibility(
+                    user_id=session_id,
+                    user_cache=self._user_cache,
+                    self_id=self.client_self_id,
+                    default_visibility=self.default_visibility,
+                )
+
+                await self.api.create_note(
+                    text,
+                    visibility=visibility,
+                    visible_user_ids=visible_user_ids,
+                    local_only=self.local_only,
+                )
+
+        except Exception as e:
+            logger.error(f"[Misskey] 发送消息失败: {e}")
+
+        return await super().send_by_session(session, message_chain)
+
+    async def convert_message(self, raw_data: Dict[str, Any]) -> AstrBotMessage:
+        """将 Misskey 贴文数据转换为 AstrBotMessage 对象"""
+        sender_info = extract_sender_info(raw_data, is_chat=False)
+        message = create_base_message(
+            raw_data,
+            sender_info,
+            self.client_self_id,
+            is_chat=False,
+            unique_session=self.unique_session,
+        )
+        cache_user_info(
+            self._user_cache, sender_info, raw_data, self.client_self_id, is_chat=False
+        )
+
+        message_parts = []
+        raw_text = raw_data.get("text", "")
+
+        if raw_text:
+            text_parts, processed_text = process_at_mention(
+                message, raw_text, self._bot_username, self.client_self_id
+            )
+            message_parts.extend(text_parts)
+
+        files = raw_data.get("files", [])
+        file_parts = process_files(message, files)
+        message_parts.extend(file_parts)
+
+        message.message_str = (
+            " ".join(part for part in message_parts if part.strip())
+            if message_parts
+            else ""
+        )
+        return message
+
+    async def convert_chat_message(self, raw_data: Dict[str, Any]) -> AstrBotMessage:
+        """将 Misskey 聊天消息数据转换为 AstrBotMessage 对象"""
+        sender_info = extract_sender_info(raw_data, is_chat=True)
+        message = create_base_message(
+            raw_data,
+            sender_info,
+            self.client_self_id,
+            is_chat=True,
+            unique_session=self.unique_session,
+        )
+        cache_user_info(
+            self._user_cache, sender_info, raw_data, self.client_self_id, is_chat=True
+        )
+
+        raw_text = raw_data.get("text", "")
+        if raw_text:
+            message.message.append(Comp.Plain(raw_text))
+
+        files = raw_data.get("files", [])
+        process_files(message, files, include_text_parts=False)
+
+        message.message_str = raw_text if raw_text else ""
+        return message
+
+    async def convert_room_message(self, raw_data: Dict[str, Any]) -> AstrBotMessage:
+        """将 Misskey 群聊消息数据转换为 AstrBotMessage 对象"""
+        sender_info = extract_sender_info(raw_data, is_chat=True)
+        room_id = raw_data.get("toRoomId", "")
+        message = create_base_message(
+            raw_data,
+            sender_info,
+            self.client_self_id,
+            is_chat=False,
+            room_id=room_id,
+            unique_session=self.unique_session,
+        )
+
+        cache_user_info(
+            self._user_cache, sender_info, raw_data, self.client_self_id, is_chat=False
+        )
+        cache_room_info(self._user_cache, raw_data, self.client_self_id)
+
+        raw_text = raw_data.get("text", "")
+        message_parts = []
+
+        if raw_text:
+            if self._bot_username and f"@{self._bot_username}" in raw_text:
+                text_parts, processed_text = process_at_mention(
+                    message, raw_text, self._bot_username, self.client_self_id
+                )
+                message_parts.extend(text_parts)
+            else:
+                message.message.append(Comp.Plain(raw_text))
+                message_parts.append(raw_text)
+
+        files = raw_data.get("files", [])
+        file_parts = process_files(message, files)
+        message_parts.extend(file_parts)
+
+        message.message_str = (
+            " ".join(part for part in message_parts if part.strip())
+            if message_parts
+            else ""
+        )
+        return message
+
+    async def terminate(self):
+        self._running = False
+        if self.api:
+            await self.api.close()
+
+    def get_client(self) -> Any:
+        return self.api

astrbot/core/platform/sources/misskey/misskey_api.py

@@ -0,0 +1,404 @@
+import json
+from typing import Any, Optional, Dict, List, Callable, Awaitable
+import uuid
+
+try:
+    import aiohttp
+    import websockets
+except ImportError as e:
+    raise ImportError(
+        "aiohttp and websockets are required for Misskey API. Please install them with: pip install aiohttp websockets"
+    ) from e
+
+from astrbot.api import logger
+
+# Constants
+API_MAX_RETRIES = 3
+HTTP_OK = 200
+
+
+class APIError(Exception):
+    """Misskey API 基础异常"""
+
+    pass
+
+
+class APIConnectionError(APIError):
+    """网络连接异常"""
+
+    pass
+
+
+class APIRateLimitError(APIError):
+    """API 频率限制异常"""
+
+    pass
+
+
+class AuthenticationError(APIError):
+    """认证失败异常"""
+
+    pass
+
+
+class WebSocketError(APIError):
+    """WebSocket 连接异常"""
+
+    pass
+
+
+class StreamingClient:
+    def __init__(self, instance_url: str, access_token: str):
+        self.instance_url = instance_url.rstrip("/")
+        self.access_token = access_token
+        self.websocket: Optional[Any] = None
+        self.is_connected = False
+        self.message_handlers: Dict[str, Callable] = {}
+        self.channels: Dict[str, str] = {}
+        self._running = False
+        self._last_pong = None
+
+    async def connect(self) -> bool:
+        try:
+            ws_url = self.instance_url.replace("https://", "wss://").replace(
+                "http://", "ws://"
+            )
+            ws_url += f"/streaming?i={self.access_token}"
+
+            self.websocket = await websockets.connect(
+                ws_url, ping_interval=30, ping_timeout=10
+            )
+            self.is_connected = True
+            self._running = True
+
+            logger.info("[Misskey WebSocket] 已连接")
+            return True
+
+        except Exception as e:
+            logger.error(f"[Misskey WebSocket] 连接失败: {e}")
+            self.is_connected = False
+            return False
+
+    async def disconnect(self):
+        self._running = False
+        if self.websocket:
+            await self.websocket.close()
+            self.websocket = None
+        self.is_connected = False
+        logger.info("[Misskey WebSocket] 连接已断开")
+
+    async def subscribe_channel(
+        self, channel_type: str, params: Optional[Dict] = None
+    ) -> str:
+        if not self.is_connected or not self.websocket:
+            raise WebSocketError("WebSocket 未连接")
+
+        channel_id = str(uuid.uuid4())
+        message = {
+            "type": "connect",
+            "body": {"channel": channel_type, "id": channel_id, "params": params or {}},
+        }
+
+        await self.websocket.send(json.dumps(message))
+        self.channels[channel_id] = channel_type
+        return channel_id
+
+    async def unsubscribe_channel(self, channel_id: str):
+        if (
+            not self.is_connected
+            or not self.websocket
+            or channel_id not in self.channels
+        ):
+            return
+
+        message = {"type": "disconnect", "body": {"id": channel_id}}
+
+        await self.websocket.send(json.dumps(message))
+        del self.channels[channel_id]
+
+    def add_message_handler(
+        self, event_type: str, handler: Callable[[Dict], Awaitable[None]]
+    ):
+        self.message_handlers[event_type] = handler
+
+    async def listen(self):
+        if not self.is_connected or not self.websocket:
+            raise WebSocketError("WebSocket 未连接")
+
+        try:
+            async for message in self.websocket:
+                if not self._running:
+                    break
+
+                try:
+                    data = json.loads(message)
+                    await self._handle_message(data)
+                except json.JSONDecodeError as e:
+                    logger.warning(f"[Misskey WebSocket] 无法解析消息: {e}")
+                except Exception as e:
+                    logger.error(f"[Misskey WebSocket] 处理消息失败: {e}")
+
+        except websockets.exceptions.ConnectionClosedError as e:
+            logger.warning(f"[Misskey WebSocket] 连接意外关闭: {e}")
+            self.is_connected = False
+        except websockets.exceptions.ConnectionClosed as e:
+            logger.warning(
+                f"[Misskey WebSocket] 连接已关闭 (代码: {e.code}, 原因: {e.reason})"
+            )
+            self.is_connected = False
+        except websockets.exceptions.InvalidHandshake as e:
+            logger.error(f"[Misskey WebSocket] 握手失败: {e}")
+            self.is_connected = False
+        except Exception as e:
+            logger.error(f"[Misskey WebSocket] 监听消息失败: {e}")
+            self.is_connected = False
+
+    async def _handle_message(self, data: Dict[str, Any]):
+        message_type = data.get("type")
+        body = data.get("body", {})
+
+        logger.debug(
+            f"[Misskey WebSocket] 收到消息类型: {message_type}\n数据: {json.dumps(data, indent=2, ensure_ascii=False)}"
+        )
+
+        if message_type == "channel":
+            channel_id = body.get("id")
+            event_type = body.get("type")
+            event_body = body.get("body", {})
+
+            logger.debug(
+                f"[Misskey WebSocket] 频道消息: {channel_id}, 事件类型: {event_type}"
+            )
+
+            if channel_id in self.channels:
+                channel_type = self.channels[channel_id]
+                handler_key = f"{channel_type}:{event_type}"
+
+                if handler_key in self.message_handlers:
+                    logger.debug(f"[Misskey WebSocket] 使用处理器: {handler_key}")
+                    await self.message_handlers[handler_key](event_body)
+                elif event_type in self.message_handlers:
+                    logger.debug(f"[Misskey WebSocket] 使用事件处理器: {event_type}")
+                    await self.message_handlers[event_type](event_body)
+                else:
+                    logger.debug(
+                        f"[Misskey WebSocket] 未找到处理器: {handler_key} 或 {event_type}"
+                    )
+                    if "_debug" in self.message_handlers:
+                        await self.message_handlers["_debug"](
+                            {
+                                "type": event_type,
+                                "body": event_body,
+                                "channel": channel_type,
+                            }
+                        )
+
+        elif message_type in self.message_handlers:
+            logger.debug(f"[Misskey WebSocket] 直接消息处理器: {message_type}")
+            await self.message_handlers[message_type](body)
+        else:
+            logger.debug(f"[Misskey WebSocket] 未处理的消息类型: {message_type}")
+            if "_debug" in self.message_handlers:
+                await self.message_handlers["_debug"](data)
+
+
+def retry_async(max_retries: int = 3, retryable_exceptions: tuple = ()):
+    def decorator(func):
+        async def wrapper(*args, **kwargs):
+            last_exc = None
+            for _ in range(max_retries):
+                try:
+                    return await func(*args, **kwargs)
+                except retryable_exceptions as e:
+                    last_exc = e
+                    continue
+            if last_exc:
+                raise last_exc
+
+        return wrapper
+
+    return decorator
+
+
+class MisskeyAPI:
+    def __init__(self, instance_url: str, access_token: str):
+        self.instance_url = instance_url.rstrip("/")
+        self.access_token = access_token
+        self._session: Optional[aiohttp.ClientSession] = None
+        self.streaming: Optional[StreamingClient] = None
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+        return False
+
+    async def close(self) -> None:
+        if self.streaming:
+            await self.streaming.disconnect()
+            self.streaming = None
+        if self._session:
+            await self._session.close()
+            self._session = None
+        logger.debug("[Misskey API] 客户端已关闭")
+
+    def get_streaming_client(self) -> StreamingClient:
+        if not self.streaming:
+            self.streaming = StreamingClient(self.instance_url, self.access_token)
+        return self.streaming
+
+    @property
+    def session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            headers = {"Authorization": f"Bearer {self.access_token}"}
+            self._session = aiohttp.ClientSession(headers=headers)
+        return self._session
+
+    def _handle_response_status(self, status: int, endpoint: str):
+        """处理 HTTP 响应状态码"""
+        if status == 400:
+            logger.error(f"API 请求错误: {endpoint} (状态码: {status})")
+            raise APIError(f"Bad request for {endpoint}")
+        elif status in (401, 403):
+            logger.error(f"API 认证失败: {endpoint} (状态码: {status})")
+            raise AuthenticationError(f"Authentication failed for {endpoint}")
+        elif status == 429:
+            logger.warning(f"API 频率限制: {endpoint} (状态码: {status})")
+            raise APIRateLimitError(f"Rate limit exceeded for {endpoint}")
+        else:
+            logger.error(f"API 请求失败: {endpoint} (状态码: {status})")
+            raise APIConnectionError(f"HTTP {status} for {endpoint}")
+
+    async def _process_response(
+        self, response: aiohttp.ClientResponse, endpoint: str
+    ) -> Any:
+        """处理 API 响应"""
+        if response.status == HTTP_OK:
+            try:
+                result = await response.json()
+                if endpoint == "i/notifications":
+                    notifications_data = (
+                        result
+                        if isinstance(result, list)
+                        else result.get("notifications", [])
+                        if isinstance(result, dict)
+                        else []
+                    )
+                    if notifications_data:
+                        logger.debug(f"获取到 {len(notifications_data)} 条新通知")
+                else:
+                    logger.debug(f"API 请求成功: {endpoint}")
+                return result
+            except json.JSONDecodeError as e:
+                logger.error(f"响应不是有效的 JSON 格式: {e}")
+                raise APIConnectionError("Invalid JSON response") from e
+        else:
+            try:
+                error_text = await response.text()
+                logger.error(
+                    f"API 请求失败: {endpoint} - 状态码: {response.status}, 响应: {error_text}"
+                )
+            except Exception:
+                logger.error(f"API 请求失败: {endpoint} - 状态码: {response.status}")
+
+            self._handle_response_status(response.status, endpoint)
+            raise APIConnectionError(f"Request failed for {endpoint}")
+
+    @retry_async(
+        max_retries=API_MAX_RETRIES,
+        retryable_exceptions=(APIConnectionError, APIRateLimitError),
+    )
+    async def _make_request(
+        self, endpoint: str, data: Optional[Dict[str, Any]] = None
+    ) -> Any:
+        url = f"{self.instance_url}/api/{endpoint}"
+        payload = {"i": self.access_token}
+        if data:
+            payload.update(data)
+
+        try:
+            async with self.session.post(url, json=payload) as response:
+                return await self._process_response(response, endpoint)
+        except aiohttp.ClientError as e:
+            logger.error(f"HTTP 请求错误: {e}")
+            raise APIConnectionError(f"HTTP request failed: {e}") from e
+
+    async def create_note(
+        self,
+        text: str,
+        visibility: str = "public",
+        reply_id: Optional[str] = None,
+        visible_user_ids: Optional[List[str]] = None,
+        local_only: bool = False,
+    ) -> Dict[str, Any]:
+        """创建新贴文"""
+        data: Dict[str, Any] = {
+            "text": text,
+            "visibility": visibility,
+            "localOnly": local_only,
+        }
+        if reply_id:
+            data["replyId"] = reply_id
+        if visible_user_ids and visibility == "specified":
+            data["visibleUserIds"] = visible_user_ids
+
+        result = await self._make_request("notes/create", data)
+        note_id = result.get("createdNote", {}).get("id", "unknown")
+        logger.debug(f"发帖成功，note_id: {note_id}")
+        return result
+
+    async def get_current_user(self) -> Dict[str, Any]:
+        """获取当前用户信息"""
+        return await self._make_request("i", {})
+
+    async def send_message(self, user_id: str, text: str) -> Dict[str, Any]:
+        """发送聊天消息"""
+        result = await self._make_request(
+            "chat/messages/create-to-user", {"toUserId": user_id, "text": text}
+        )
+        message_id = result.get("id", "unknown")
+        logger.debug(f"聊天发送成功，message_id: {message_id}")
+        return result
+
+    async def send_room_message(self, room_id: str, text: str) -> Dict[str, Any]:
+        """发送房间消息"""
+        result = await self._make_request(
+            "chat/messages/create-to-room", {"toRoomId": room_id, "text": text}
+        )
+        message_id = result.get("id", "unknown")
+        logger.debug(f"房间消息发送成功，message_id: {message_id}")
+        return result
+
+    async def get_messages(
+        self, user_id: str, limit: int = 10, since_id: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """获取聊天消息历史"""
+        data: Dict[str, Any] = {"userId": user_id, "limit": limit}
+        if since_id:
+            data["sinceId"] = since_id
+
+        result = await self._make_request("chat/messages/user-timeline", data)
+        if isinstance(result, list):
+            return result
+        else:
+            logger.warning(f"获取聊天消息响应格式异常: {type(result)}")
+            return []
+
+    async def get_mentions(
+        self, limit: int = 10, since_id: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """获取提及通知"""
+        data: Dict[str, Any] = {"limit": limit}
+        if since_id:
+            data["sinceId"] = since_id
+        data["includeTypes"] = ["mention", "reply", "quote"]
+
+        result = await self._make_request("i/notifications", data)
+        if isinstance(result, list):
+            return result
+        elif isinstance(result, dict) and "notifications" in result:
+            return result["notifications"]
+        else:
+            logger.warning(f"获取提及通知响应格式异常: {type(result)}")
+            return []

astrbot/core/platform/sources/misskey/misskey_event.py

@@ -0,0 +1,123 @@
+import asyncio
+import re
+from typing import AsyncGenerator
+from astrbot.api import logger
+from astrbot.api.event import AstrMessageEvent, MessageChain
+from astrbot.api.platform import PlatformMetadata, AstrBotMessage
+from astrbot.api.message_components import Plain
+
+from .misskey_utils import (
+    serialize_message_chain,
+    resolve_visibility_from_raw_message,
+    is_valid_user_session_id,
+    is_valid_room_session_id,
+    add_at_mention_if_needed,
+    extract_user_id_from_session_id,
+    extract_room_id_from_session_id,
+)
+
+
+class MisskeyPlatformEvent(AstrMessageEvent):
+    def __init__(
+        self,
+        message_str: str,
+        message_obj: AstrBotMessage,
+        platform_meta: PlatformMetadata,
+        session_id: str,
+        client,
+    ):
+        super().__init__(message_str, message_obj, platform_meta, session_id)
+        self.client = client
+
+    def _is_system_command(self, message_str: str) -> bool:
+        """检测是否为系统指令"""
+        if not message_str or not message_str.strip():
+            return False
+
+        system_prefixes = ["/", "!", "#", ".", "^"]
+        message_trimmed = message_str.strip()
+
+        return any(message_trimmed.startswith(prefix) for prefix in system_prefixes)
+
+    async def send(self, message: MessageChain):
+        content, has_at = serialize_message_chain(message.chain)
+
+        if not content:
+            logger.debug("[MisskeyEvent] 内容为空，跳过发送")
+            return
+
+        try:
+            original_message_id = getattr(self.message_obj, "message_id", None)
+            raw_message = getattr(self.message_obj, "raw_message", {})
+
+            if raw_message and not has_at:
+                user_data = raw_message.get("user", {})
+                user_info = {
+                    "username": user_data.get("username", ""),
+                    "nickname": user_data.get("name", user_data.get("username", "")),
+                }
+                content = add_at_mention_if_needed(content, user_info, has_at)
+
+            # 根据会话类型选择发送方式
+            if hasattr(self.client, "send_message") and is_valid_user_session_id(
+                self.session_id
+            ):
+                user_id = extract_user_id_from_session_id(self.session_id)
+                await self.client.send_message(user_id, content)
+            elif hasattr(self.client, "send_room_message") and is_valid_room_session_id(
+                self.session_id
+            ):
+                room_id = extract_room_id_from_session_id(self.session_id)
+                await self.client.send_room_message(room_id, content)
+            elif original_message_id and hasattr(self.client, "create_note"):
+                visibility, visible_user_ids = resolve_visibility_from_raw_message(
+                    raw_message
+                )
+                await self.client.create_note(
+                    content,
+                    reply_id=original_message_id,
+                    visibility=visibility,
+                    visible_user_ids=visible_user_ids,
+                )
+            elif hasattr(self.client, "create_note"):
+                logger.debug("[MisskeyEvent] 创建新帖子")
+                await self.client.create_note(content)
+
+            await super().send(message)
+
+        except Exception as e:
+            logger.error(f"[MisskeyEvent] 发送失败: {e}")
+
+    async def send_streaming(
+        self, generator: AsyncGenerator[MessageChain, None], 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)

astrbot/core/platform/sources/misskey/misskey_utils.py

@@ -0,0 +1,327 @@
+"""Misskey 平台适配器通用工具函数"""
+
+from typing import Dict, Any, List, Tuple, Optional, Union
+import astrbot.api.message_components as Comp
+from astrbot.api.platform import AstrBotMessage, MessageMember, MessageType
+
+
+def serialize_message_chain(chain: List[Any]) -> Tuple[str, bool]:
+    """将消息链序列化为文本字符串"""
+    text_parts = []
+    has_at = False
+
+    def process_component(component):
+        nonlocal has_at
+        if isinstance(component, Comp.Plain):
+            return component.text
+        elif isinstance(component, Comp.File):
+            file_name = getattr(component, "name", "文件")
+            return f"[文件: {file_name}]"
+        elif isinstance(component, Comp.At):
+            has_at = True
+            return f"@{component.qq}"
+        elif hasattr(component, "text"):
+            text = getattr(component, "text", "")
+            if "@" in text:
+                has_at = True
+            return text
+        else:
+            return str(component)
+
+    for component in chain:
+        if isinstance(component, Comp.Node) and component.content:
+            for node_comp in component.content:
+                result = process_component(node_comp)
+                if result:
+                    text_parts.append(result)
+        else:
+            result = process_component(component)
+            if result:
+                text_parts.append(result)
+
+    return "".join(text_parts), has_at
+
+
+def resolve_message_visibility(
+    user_id: Optional[str],
+    user_cache: Dict[str, Any],
+    self_id: Optional[str],
+    default_visibility: str = "public",
+) -> Tuple[str, Optional[List[str]]]:
+    """解析 Misskey 消息的可见性设置"""
+    visibility = default_visibility
+    visible_user_ids = None
+
+    if user_id and user_cache:
+        user_info = user_cache.get(user_id)
+        if user_info:
+            original_visibility = user_info.get("visibility", default_visibility)
+            if original_visibility == "specified":
+                visibility = "specified"
+                original_visible_users = user_info.get("visible_user_ids", [])
+                users_to_include = [user_id]
+                if self_id:
+                    users_to_include.append(self_id)
+                visible_user_ids = list(set(original_visible_users + users_to_include))
+                visible_user_ids = [uid for uid in visible_user_ids if uid]
+            else:
+                visibility = original_visibility
+
+    return visibility, visible_user_ids
+
+
+def resolve_visibility_from_raw_message(
+    raw_message: Dict[str, Any], self_id: Optional[str] = None
+) -> Tuple[str, Optional[List[str]]]:
+    """从原始消息数据中解析可见性设置"""
+    visibility = "public"
+    visible_user_ids = None
+
+    if not raw_message:
+        return visibility, visible_user_ids
+
+    original_visibility = raw_message.get("visibility", "public")
+    if original_visibility == "specified":
+        visibility = "specified"
+        original_visible_users = raw_message.get("visibleUserIds", [])
+        sender_id = raw_message.get("userId", "")
+
+        users_to_include = []
+        if sender_id:
+            users_to_include.append(sender_id)
+        if self_id:
+            users_to_include.append(self_id)
+
+        visible_user_ids = list(set(original_visible_users + users_to_include))
+        visible_user_ids = [uid for uid in visible_user_ids if uid]
+    else:
+        visibility = original_visibility
+
+    return visibility, visible_user_ids
+
+
+def is_valid_user_session_id(session_id: Union[str, Any]) -> bool:
+    """检查 session_id 是否是有效的聊天用户 session_id (仅限chat%前缀)"""
+    if not isinstance(session_id, str) or "%" not in session_id:
+        return False
+
+    parts = session_id.split("%")
+    return (
+        len(parts) == 2
+        and parts[0] == "chat"
+        and bool(parts[1])
+        and parts[1] != "unknown"
+    )
+
+
+def is_valid_room_session_id(session_id: Union[str, Any]) -> bool:
+    """检查 session_id 是否是有效的房间 session_id (仅限room%前缀)"""
+    if not isinstance(session_id, str) or "%" not in session_id:
+        return False
+
+    parts = session_id.split("%")
+    return (
+        len(parts) == 2
+        and parts[0] == "room"
+        and bool(parts[1])
+        and parts[1] != "unknown"
+    )
+
+
+def extract_user_id_from_session_id(session_id: str) -> str:
+    """从 session_id 中提取用户 ID"""
+    if "%" in session_id:
+        parts = session_id.split("%")
+        if len(parts) >= 2:
+            return parts[1]
+    return session_id
+
+
+def extract_room_id_from_session_id(session_id: str) -> str:
+    """从 session_id 中提取房间 ID"""
+    if "%" in session_id:
+        parts = session_id.split("%")
+        if len(parts) >= 2 and parts[0] == "room":
+            return parts[1]
+    return session_id
+
+
+def add_at_mention_if_needed(
+    text: str, user_info: Optional[Dict[str, Any]], has_at: bool = False
+) -> str:
+    """如果需要且没有@用户，则添加@用户"""
+    if has_at or not user_info:
+        return text
+
+    username = user_info.get("username")
+    nickname = user_info.get("nickname")
+
+    if username:
+        mention = f"@{username}"
+        if not text.startswith(mention):
+            text = f"{mention}\n{text}".strip()
+    elif nickname:
+        mention = f"@{nickname}"
+        if not text.startswith(mention):
+            text = f"{mention}\n{text}".strip()
+
+    return text
+
+
+def create_file_component(file_info: Dict[str, Any]) -> Tuple[Any, str]:
+    """创建文件组件和描述文本"""
+    file_url = file_info.get("url", "")
+    file_name = file_info.get("name", "未知文件")
+    file_type = file_info.get("type", "")
+
+    if file_type.startswith("image/"):
+        return Comp.Image(url=file_url, file=file_name), f"图片[{file_name}]"
+    elif file_type.startswith("audio/"):
+        return Comp.Record(url=file_url, file=file_name), f"音频[{file_name}]"
+    elif file_type.startswith("video/"):
+        return Comp.Video(url=file_url, file=file_name), f"视频[{file_name}]"
+    else:
+        return Comp.File(name=file_name, url=file_url), f"文件[{file_name}]"
+
+
+def process_files(
+    message: AstrBotMessage, files: list, include_text_parts: bool = True
+) -> list:
+    """处理文件列表，添加到消息组件中并返回文本描述"""
+    file_parts = []
+    for file_info in files:
+        component, part_text = create_file_component(file_info)
+        message.message.append(component)
+        if include_text_parts:
+            file_parts.append(part_text)
+    return file_parts
+
+
+def extract_sender_info(
+    raw_data: Dict[str, Any], is_chat: bool = False
+) -> Dict[str, Any]:
+    """提取发送者信息"""
+    if is_chat:
+        sender = raw_data.get("fromUser", {})
+        sender_id = str(sender.get("id", "") or raw_data.get("fromUserId", ""))
+    else:
+        sender = raw_data.get("user", {})
+        sender_id = str(sender.get("id", ""))
+
+    return {
+        "sender": sender,
+        "sender_id": sender_id,
+        "nickname": sender.get("name", sender.get("username", "")),
+        "username": sender.get("username", ""),
+    }
+
+
+def create_base_message(
+    raw_data: Dict[str, Any],
+    sender_info: Dict[str, Any],
+    client_self_id: str,
+    is_chat: bool = False,
+    room_id: Optional[str] = None,
+    unique_session: bool = False,
+) -> AstrBotMessage:
+    """创建基础消息对象"""
+    message = AstrBotMessage()
+    message.raw_message = raw_data
+    message.message = []
+
+    message.sender = MessageMember(
+        user_id=sender_info["sender_id"],
+        nickname=sender_info["nickname"],
+    )
+
+    if room_id:
+        session_prefix = "room"
+        session_id = f"{session_prefix}%{room_id}"
+        if unique_session:
+            session_id += f"_{sender_info['sender_id']}"
+        message.type = MessageType.GROUP_MESSAGE
+        message.group_id = room_id
+    elif is_chat:
+        session_prefix = "chat"
+        session_id = f"{session_prefix}%{sender_info['sender_id']}"
+        message.type = MessageType.FRIEND_MESSAGE
+    else:
+        session_prefix = "note"
+        session_id = f"{session_prefix}%{sender_info['sender_id']}"
+        message.type = MessageType.FRIEND_MESSAGE
+
+    message.session_id = (
+        session_id if sender_info["sender_id"] else f"{session_prefix}%unknown"
+    )
+    message.message_id = str(raw_data.get("id", ""))
+    message.self_id = client_self_id
+
+    return message
+
+
+def process_at_mention(
+    message: AstrBotMessage, raw_text: str, bot_username: str, client_self_id: str
+) -> Tuple[List[str], str]:
+    """处理@提及逻辑，返回消息部分列表和处理后的文本"""
+    message_parts = []
+
+    if not raw_text:
+        return message_parts, ""
+
+    if bot_username and raw_text.startswith(f"@{bot_username}"):
+        at_mention = f"@{bot_username}"
+        message.message.append(Comp.At(qq=client_self_id))
+        remaining_text = raw_text[len(at_mention) :].strip()
+        if remaining_text:
+            message.message.append(Comp.Plain(remaining_text))
+            message_parts.append(remaining_text)
+        return message_parts, remaining_text
+    else:
+        message.message.append(Comp.Plain(raw_text))
+        message_parts.append(raw_text)
+        return message_parts, raw_text
+
+
+def cache_user_info(
+    user_cache: Dict[str, Any],
+    sender_info: Dict[str, Any],
+    raw_data: Dict[str, Any],
+    client_self_id: str,
+    is_chat: bool = False,
+):
+    """缓存用户信息"""
+    if is_chat:
+        user_cache_data = {
+            "username": sender_info["username"],
+            "nickname": sender_info["nickname"],
+            "visibility": "specified",
+            "visible_user_ids": [client_self_id, sender_info["sender_id"]],
+        }
+    else:
+        user_cache_data = {
+            "username": sender_info["username"],
+            "nickname": sender_info["nickname"],
+            "visibility": raw_data.get("visibility", "public"),
+            "visible_user_ids": raw_data.get("visibleUserIds", []),
+        }
+
+    user_cache[sender_info["sender_id"]] = user_cache_data
+
+
+def cache_room_info(
+    user_cache: Dict[str, Any], raw_data: Dict[str, Any], client_self_id: str
+):
+    """缓存房间信息"""
+    room_data = raw_data.get("toRoom")
+    room_id = raw_data.get("toRoomId")
+
+    if room_data and room_id:
+        room_cache_key = f"room:{room_id}"
+        user_cache[room_cache_key] = {
+            "room_id": room_id,
+            "room_name": room_data.get("name", ""),
+            "room_description": room_data.get("description", ""),
+            "owner_id": room_data.get("ownerId", ""),
+            "visibility": "specified",
+            "visible_user_ids": [client_self_id],
+        }

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

@@ -3,15 +3,23 @@ import botpy.message
 import botpy.types
 import botpy.types.message
 import asyncio
+import base64
+import aiofiles
 from astrbot.core.utils.io import file_to_base64, download_image_by_url
+from astrbot.core.utils.tencent_record_helper import wav_to_tencent_silk
+from astrbot.core.utils.astrbot_path import get_astrbot_data_path
 from astrbot.api.event import AstrMessageEvent, MessageChain
 from astrbot.api.platform import AstrBotMessage, PlatformMetadata
-from astrbot.api.message_components import Plain, Image
+from astrbot.api.message_components import Plain, Image, Record
 from botpy import Client
 from botpy.http import Route
 from astrbot.api import logger
+from botpy.types.message import Media
 from botpy.types import message
+from typing import Optional
 import random
+import uuid
+import os
 
 
 class QQOfficialMessageEvent(AstrMessageEvent):
@@ -36,6 +44,7 @@ class QQOfficialMessageEvent(AstrMessageEvent):
         stream_payload = {"state": 1, "id": None, "index": 0, "reset": False}
         last_edit_time = 0  # 上次编辑消息的时间
         throttle_interval = 1  # 编辑消息的间隔时间 (秒)
+        ret = None
         try:
             async for chain in generator:
                 source = self.message_obj.raw_message
@@ -85,9 +94,15 @@ class QQOfficialMessageEvent(AstrMessageEvent):
             plain_text,
             image_base64,
             image_path,
+            record_file_path,
         ) = await QQOfficialMessageEvent._parse_to_qqofficial(self.send_buffer)
 
-        if not plain_text and not image_base64 and not image_path:
+        if (
+            not plain_text
+            and not image_base64
+            and not image_path
+            and not record_file_path
+        ):
             return
 
         payload = {
@@ -98,6 +113,8 @@ class QQOfficialMessageEvent(AstrMessageEvent):
         if not isinstance(source, (botpy.message.Message, botpy.message.DirectMessage)):
             payload["msg_seq"] = random.randint(1, 10000)
 
+        ret = None
+
         match type(source):
             case botpy.message.GroupMessage:
                 if image_base64:
@@ -106,6 +123,12 @@ class QQOfficialMessageEvent(AstrMessageEvent):
                     )
                     payload["media"] = media
                     payload["msg_type"] = 7
+                if record_file_path:  # group record msg
+                    media = await self.upload_group_and_c2c_record(
+                        record_file_path, 3, group_openid=source.group_openid
+                    )
+                    payload["media"] = media
+                    payload["msg_type"] = 7
                 ret = await self.bot.api.post_group_message(
                     group_openid=source.group_openid, **payload
                 )
@@ -116,6 +139,12 @@ class QQOfficialMessageEvent(AstrMessageEvent):
                     )
                     payload["media"] = media
                     payload["msg_type"] = 7
+                if record_file_path:  # c2c record
+                    media = await self.upload_group_and_c2c_record(
+                        record_file_path, 3, openid=source.author.user_openid
+                    )
+                    payload["media"] = media
+                    payload["msg_type"] = 7
                 if stream:
                     ret = await self.post_c2c_message(
                         openid=source.author.user_openid,
@@ -165,6 +194,56 @@ class QQOfficialMessageEvent(AstrMessageEvent):
             )
             return await self.bot.api._http.request(route, json=payload)
 
+    async def upload_group_and_c2c_record(
+        self, file_source: str, file_type: int, srv_send_msg: bool = False, **kwargs
+    ) -> Optional[Media]:
+        """
+        上传媒体文件
+        """
+        # 构建基础payload
+        payload = {"file_type": file_type, "srv_send_msg": srv_send_msg}
+
+        # 处理文件数据
+        if os.path.exists(file_source):
+            # 读取本地文件
+            async with aiofiles.open(file_source, "rb") as f:
+                file_content = await f.read()
+                # use base64 encode
+                payload["file_data"] = base64.b64encode(file_content).decode("utf-8")
+        else:
+            # 使用URL
+            payload["url"] = file_source
+
+        # 添加接收者信息和确定路由
+        if "openid" in kwargs:
+            payload["openid"] = kwargs["openid"]
+            route = Route("POST", "/v2/users/{openid}/files", openid=kwargs["openid"])
+        elif "group_openid" in kwargs:
+            payload["group_openid"] = kwargs["group_openid"]
+            route = Route(
+                "POST",
+                "/v2/groups/{group_openid}/files",
+                group_openid=kwargs["group_openid"],
+            )
+        else:
+            return None
+
+        try:
+            # 使用底层HTTP请求
+            result = await self.bot.api._http.request(route, json=payload)
+
+            if result:
+                return Media(
+                    file_uuid=result.get("file_uuid"),
+                    file_info=result.get("file_info"),
+                    ttl=result.get("ttl", 0),
+                    file_id=result.get("id", ""),
+                )
+        except Exception as e:
+            logger.error(f"上传请求错误: {e}")
+
+        return None
+
     async def post_c2c_message(
         self,
         openid: str,
@@ -191,6 +270,7 @@ class QQOfficialMessageEvent(AstrMessageEvent):
         plain_text = ""
         image_base64 = None  # only one img supported
         image_file_path = None
+        record_file_path = None
         for i in message.chain:
             if isinstance(i, Plain):
                 plain_text += i.text
@@ -206,6 +286,25 @@ class QQOfficialMessageEvent(AstrMessageEvent):
                 else:
                     image_base64 = file_to_base64(i.file)
                 image_base64 = image_base64.removeprefix("base64://")
+            elif isinstance(i, Record):
+                if i.file:
+                    record_wav_path = await i.convert_to_file_path()  # wav 路径
+                    temp_dir = os.path.join(get_astrbot_data_path(), "temp")
+                    record_tecent_silk_path = os.path.join(
+                        temp_dir, f"{uuid.uuid4()}.silk"
+                    )
+                    try:
+                        duration = await wav_to_tencent_silk(
+                            record_wav_path, record_tecent_silk_path
+                        )
+                        if duration > 0:
+                            record_file_path = record_tecent_silk_path
+                        else:
+                            record_file_path = None
+                            logger.error("转换音频格式时出错：音频时长不大于0")
+                    except Exception as e:
+                        logger.error(f"处理语音时出错: {e}")
+                        record_file_path = None
             else:
                 logger.debug(f"qq_official 忽略 {i.type}")
-        return plain_text, image_base64, image_file_path
+        return plain_text, image_base64, image_file_path, record_file_path

astrbot/core/platform/sources/satori/satori_adapter.py

@@ -0,0 +1,748 @@
+import asyncio
+import json
+import time
+import websockets
+from websockets.asyncio.client import connect
+from typing import Optional
+from aiohttp import ClientSession, ClientTimeout
+from websockets.asyncio.client import ClientConnection
+from astrbot.api import logger
+from astrbot.api.event import MessageChain
+from astrbot.api.platform import (
+    AstrBotMessage,
+    MessageMember,
+    MessageType,
+    Platform,
+    PlatformMetadata,
+    register_platform_adapter,
+)
+from astrbot.core.platform.astr_message_event import MessageSession
+from astrbot.api.message_components import (
+    Plain,
+    Image,
+    At,
+    File,
+    Record,
+    Reply,
+)
+from xml.etree import ElementTree as ET
+
+
+@register_platform_adapter(
+    "satori",
+    "Satori 协议适配器",
+)
+class SatoriPlatformAdapter(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.api_base_url = self.config.get(
+            "satori_api_base_url", "http://localhost:5140/satori/v1"
+        )
+        self.token = self.config.get("satori_token", "")
+        self.endpoint = self.config.get(
+            "satori_endpoint", "ws://localhost:5140/satori/v1/events"
+        )
+        self.auto_reconnect = self.config.get("satori_auto_reconnect", True)
+        self.heartbeat_interval = self.config.get("satori_heartbeat_interval", 10)
+        self.reconnect_delay = self.config.get("satori_reconnect_delay", 5)
+
+        self.metadata = PlatformMetadata(
+            name="satori",
+            description="Satori 通用协议适配器",
+            id=self.config["id"],
+        )
+
+        self.ws: Optional[ClientConnection] = None
+        self.session: Optional[ClientSession] = None
+        self.sequence = 0
+        self.logins = []
+        self.running = False
+        self.heartbeat_task: Optional[asyncio.Task] = None
+        self.ready_received = False
+
+    async def send_by_session(
+        self, session: MessageSession, message_chain: MessageChain
+    ):
+        from .satori_event import SatoriPlatformEvent
+
+        await SatoriPlatformEvent.send_with_adapter(
+            self, message_chain, session.session_id
+        )
+        await super().send_by_session(session, message_chain)
+
+    def meta(self) -> PlatformMetadata:
+        return self.metadata
+
+    def _is_websocket_closed(self, ws) -> bool:
+        """检查WebSocket连接是否已关闭"""
+        if not ws:
+            return True
+        try:
+            if hasattr(ws, "closed"):
+                return ws.closed
+            elif hasattr(ws, "close_code"):
+                return ws.close_code is not None
+            else:
+                return False
+        except AttributeError:
+            return False
+
+    async def run(self):
+        self.running = True
+        self.session = ClientSession(timeout=ClientTimeout(total=30))
+
+        retry_count = 0
+        max_retries = 10
+
+        while self.running:
+            try:
+                await self.connect_websocket()
+                retry_count = 0
+            except websockets.exceptions.ConnectionClosed as e:
+                logger.warning(f"Satori WebSocket 连接关闭: {e}")
+                retry_count += 1
+            except Exception as e:
+                logger.error(f"Satori WebSocket 连接失败: {e}")
+                retry_count += 1
+
+            if not self.running:
+                break
+
+            if retry_count >= max_retries:
+                logger.error(f"达到最大重试次数 ({max_retries})，停止重试")
+                break
+
+            if not self.auto_reconnect:
+                break
+
+            delay = min(self.reconnect_delay * (2 ** (retry_count - 1)), 60)
+            await asyncio.sleep(delay)
+
+        if self.session:
+            await self.session.close()
+
+    async def connect_websocket(self):
+        logger.info(f"Satori 适配器正在连接到 WebSocket: {self.endpoint}")
+        logger.info(f"Satori 适配器 HTTP API 地址: {self.api_base_url}")
+
+        if not self.endpoint.startswith(("ws://", "wss://")):
+            logger.error(f"无效的WebSocket URL: {self.endpoint}")
+            raise ValueError(f"WebSocket URL必须以ws://或wss://开头: {self.endpoint}")
+
+        try:
+            websocket = await connect(self.endpoint, additional_headers={})
+            self.ws = websocket
+
+            await asyncio.sleep(0.1)
+
+            await self.send_identify()
+
+            self.heartbeat_task = asyncio.create_task(self.heartbeat_loop())
+
+            async for message in websocket:
+                try:
+                    await self.handle_message(message)  # type: ignore
+                except Exception as e:
+                    logger.error(f"Satori 处理消息异常: {e}")
+
+        except websockets.exceptions.ConnectionClosed as e:
+            logger.warning(f"Satori WebSocket 连接关闭: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Satori WebSocket 连接异常: {e}")
+            raise
+        finally:
+            if self.heartbeat_task:
+                self.heartbeat_task.cancel()
+                try:
+                    await self.heartbeat_task
+                except asyncio.CancelledError:
+                    pass
+            if self.ws:
+                try:
+                    await self.ws.close()
+                except Exception as e:
+                    logger.error(f"Satori WebSocket 关闭异常: {e}")
+
+    async def send_identify(self):
+        if not self.ws:
+            raise Exception("WebSocket连接未建立")
+
+        if self._is_websocket_closed(self.ws):
+            raise Exception("WebSocket连接已关闭")
+
+        identify_payload = {
+            "op": 3,  # IDENTIFY
+            "body": {
+                "token": str(self.token) if self.token else "",  # 字符串
+            },
+        }
+
+        # 只有在有序列号时才添加sn字段
+        if self.sequence > 0:
+            identify_payload["body"]["sn"] = self.sequence
+
+        try:
+            message_str = json.dumps(identify_payload, ensure_ascii=False)
+            await self.ws.send(message_str)
+        except websockets.exceptions.ConnectionClosed as e:
+            logger.error(f"发送 IDENTIFY 信令时连接关闭: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"发送 IDENTIFY 信令失败: {e}")
+            raise
+
+    async def heartbeat_loop(self):
+        try:
+            while self.running and self.ws:
+                await asyncio.sleep(self.heartbeat_interval)
+
+                if self.ws and not self._is_websocket_closed(self.ws):
+                    try:
+                        ping_payload = {
+                            "op": 1,  # PING
+                            "body": {},
+                        }
+                        await self.ws.send(json.dumps(ping_payload, ensure_ascii=False))
+                    except websockets.exceptions.ConnectionClosed as e:
+                        logger.error(f"Satori WebSocket 连接关闭: {e}")
+                        break
+                    except Exception as e:
+                        logger.error(f"Satori WebSocket 发送心跳失败: {e}")
+                        break
+                else:
+                    break
+        except asyncio.CancelledError:
+            pass
+        except Exception as e:
+            logger.error(f"心跳任务异常: {e}")
+
+    async def handle_message(self, message: str):
+        try:
+            data = json.loads(message)
+            op = data.get("op")
+            body = data.get("body", {})
+
+            if op == 4:  # READY
+                self.logins = body.get("logins", [])
+                self.ready_received = True
+
+                # 输出连接成功的bot信息
+                if self.logins:
+                    for i, login in enumerate(self.logins):
+                        platform = login.get("platform", "")
+                        user = login.get("user", {})
+                        user_id = user.get("id", "")
+                        user_name = user.get("name", "")
+                        logger.info(
+                            f"Satori 连接成功 - Bot {i + 1}: platform={platform}, user_id={user_id}, user_name={user_name}"
+                        )
+
+                if "sn" in body:
+                    self.sequence = body["sn"]
+
+            elif op == 2:  # PONG
+                pass
+
+            elif op == 0:  # EVENT
+                await self.handle_event(body)
+                if "sn" in body:
+                    self.sequence = body["sn"]
+
+            elif op == 5:  # META
+                if "sn" in body:
+                    self.sequence = body["sn"]
+
+        except json.JSONDecodeError as e:
+            logger.error(f"解析 WebSocket 消息失败: {e}, 消息内容: {message}")
+        except Exception as e:
+            logger.error(f"处理 WebSocket 消息异常: {e}")
+
+    async def handle_event(self, event_data: dict):
+        try:
+            event_type = event_data.get("type")
+            sn = event_data.get("sn")
+            if sn:
+                self.sequence = sn
+
+            if event_type == "message-created":
+                message = event_data.get("message", {})
+                user = event_data.get("user", {})
+                channel = event_data.get("channel", {})
+                guild = event_data.get("guild")
+                login = event_data.get("login", {})
+                timestamp = event_data.get("timestamp")
+
+                if user.get("id") == login.get("user", {}).get("id"):
+                    return
+
+                abm = await self.convert_satori_message(
+                    message, user, channel, guild, login, timestamp
+                )
+                if abm:
+                    await self.handle_msg(abm)
+
+        except Exception as e:
+            logger.error(f"处理事件失败: {e}")
+
+    async def convert_satori_message(
+        self,
+        message: dict,
+        user: dict,
+        channel: dict,
+        guild: Optional[dict],
+        login: dict,
+        timestamp: Optional[int] = None,
+    ) -> Optional[AstrBotMessage]:
+        try:
+            abm = AstrBotMessage()
+            abm.message_id = message.get("id", "")
+            abm.raw_message = {
+                "message": message,
+                "user": user,
+                "channel": channel,
+                "guild": guild,
+                "login": login,
+            }
+
+            if guild and guild.get("id"):
+                abm.type = MessageType.GROUP_MESSAGE
+                abm.group_id = guild.get("id", "")
+                abm.session_id = channel.get("id", "")
+            else:
+                abm.type = MessageType.FRIEND_MESSAGE
+                abm.session_id = channel.get("id", "")
+
+            abm.sender = MessageMember(
+                user_id=user.get("id", ""),
+                nickname=user.get("nick", user.get("name", "")),
+            )
+
+            abm.self_id = login.get("user", {}).get("id", "")
+
+            # 消息链
+            abm.message = []
+
+            content = message.get("content", "")
+
+            quote = message.get("quote")
+            content_for_parsing = content  # 副本
+
+            # 提取<quote>标签
+            if "<quote" in content:
+                try:
+                    quote_info = await self._extract_quote_element(content)
+                    if quote_info:
+                        quote = quote_info["quote"]
+                        content_for_parsing = quote_info["content_without_quote"]
+                except Exception as e:
+                    logger.error(f"解析<quote>标签时发生错误: {e}, 错误内容: {content}")
+
+            if quote:
+                # 引用消息
+                quote_abm = await self._convert_quote_message(quote)
+                if quote_abm:
+                    sender_id = quote_abm.sender.user_id
+                    if isinstance(sender_id, str) and sender_id.isdigit():
+                        sender_id = int(sender_id)
+                    elif not isinstance(sender_id, int):
+                        sender_id = 0  # 默认值
+
+                    reply_component = Reply(
+                        id=quote_abm.message_id,
+                        chain=quote_abm.message,
+                        sender_id=quote_abm.sender.user_id,
+                        sender_nickname=quote_abm.sender.nickname,
+                        time=quote_abm.timestamp,
+                        message_str=quote_abm.message_str,
+                        text=quote_abm.message_str,
+                        qq=sender_id,
+                    )
+                    abm.message.append(reply_component)
+
+            # 解析消息内容
+            content_elements = await self.parse_satori_elements(content_for_parsing)
+            abm.message.extend(content_elements)
+
+            abm.message_str = ""
+            for comp in content_elements:
+                if isinstance(comp, Plain):
+                    abm.message_str += comp.text
+
+            # 优先使用Satori事件中的时间戳
+            if timestamp is not None:
+                abm.timestamp = timestamp
+            else:
+                abm.timestamp = int(time.time())
+
+            return abm
+
+        except Exception as e:
+            logger.error(f"转换 Satori 消息失败: {e}")
+            return None
+
+    def _extract_namespace_prefixes(self, content: str) -> set:
+        """提取XML内容中的命名空间前缀"""
+        prefixes = set()
+
+        # 查找所有标签
+        i = 0
+        while i < len(content):
+            # 查找开始标签
+            if content[i] == "<" and i + 1 < len(content) and content[i + 1] != "/":
+                # 找到标签结束位置
+                tag_end = content.find(">", i)
+                if tag_end != -1:
+                    # 提取标签内容
+                    tag_content = content[i + 1 : tag_end]
+                    # 检查是否有命名空间前缀
+                    if ":" in tag_content and "xmlns:" not in tag_content:
+                        # 分割标签名
+                        parts = tag_content.split()
+                        if parts:
+                            tag_name = parts[0]
+                            if ":" in tag_name:
+                                prefix = tag_name.split(":")[0]
+                                # 确保是有效的命名空间前缀
+                                if (
+                                    prefix.isalnum()
+                                    or prefix.replace("_", "").isalnum()
+                                ):
+                                    prefixes.add(prefix)
+                    i = tag_end + 1
+                else:
+                    i += 1
+            # 查找结束标签
+            elif content[i] == "<" and i + 1 < len(content) and content[i + 1] == "/":
+                # 找到标签结束位置
+                tag_end = content.find(">", i)
+                if tag_end != -1:
+                    # 提取标签内容
+                    tag_content = content[i + 2 : tag_end]
+                    # 检查是否有命名空间前缀
+                    if ":" in tag_content:
+                        prefix = tag_content.split(":")[0]
+                        # 确保是有效的命名空间前缀
+                        if prefix.isalnum() or prefix.replace("_", "").isalnum():
+                            prefixes.add(prefix)
+                    i = tag_end + 1
+                else:
+                    i += 1
+            else:
+                i += 1
+
+        return prefixes
+
+    async def _extract_quote_element(self, content: str) -> Optional[dict]:
+        """提取<quote>标签信息"""
+        try:
+            # 处理命名空间前缀问题
+            processed_content = content
+            if ":" in content and not content.startswith("<root"):
+                prefixes = self._extract_namespace_prefixes(content)
+
+                # 构建命名空间声明
+                ns_declarations = " ".join(
+                    [
+                        f'xmlns:{prefix}="http://temp.uri/{prefix}"'
+                        for prefix in prefixes
+                    ]
+                )
+
+                # 包装内容
+                processed_content = f"<root {ns_declarations}>{content}</root>"
+            elif not content.startswith("<root"):
+                processed_content = f"<root>{content}</root>"
+            else:
+                processed_content = content
+
+            root = ET.fromstring(processed_content)
+
+            # 查找<quote>标签
+            quote_element = None
+            for elem in root.iter():
+                tag_name = elem.tag
+                if "}" in tag_name:
+                    tag_name = tag_name.split("}")[1]
+                if tag_name.lower() == "quote":
+                    quote_element = elem
+                    break
+
+            if quote_element is not None:
+                # 提取quote标签的属性
+                quote_id = quote_element.get("id", "")
+
+                # 提取<quote>标签内部的内容
+                inner_content = ""
+                if quote_element.text:
+                    inner_content += quote_element.text
+                for child in quote_element:
+                    inner_content += ET.tostring(
+                        child, encoding="unicode", method="xml"
+                    )
+                    if child.tail:
+                        inner_content += child.tail
+
+                # 构造移除了<quote>标签的内容
+                content_without_quote = content.replace(
+                    ET.tostring(quote_element, encoding="unicode", method="xml"), ""
+                )
+
+                return {
+                    "quote": {"id": quote_id, "content": inner_content},
+                    "content_without_quote": content_without_quote,
+                }
+
+            return None
+        except Exception as e:
+            logger.error(f"提取<quote>标签时发生错误: {e}")
+            return None
+
+    async def _convert_quote_message(self, quote: dict) -> Optional[AstrBotMessage]:
+        """转换引用消息"""
+        try:
+            quote_abm = AstrBotMessage()
+            quote_abm.message_id = quote.get("id", "")
+
+            # 解析引用消息的发送者
+            quote_author = quote.get("author", {})
+            if quote_author:
+                quote_abm.sender = MessageMember(
+                    user_id=quote_author.get("id", ""),
+                    nickname=quote_author.get("nick", quote_author.get("name", "")),
+                )
+            else:
+                # 如果没有作者信息，使用默认值
+                quote_abm.sender = MessageMember(
+                    user_id=quote.get("user_id", ""),
+                    nickname="内容",
+                )
+
+            # 解析引用消息内容
+            quote_content = quote.get("content", "")
+            quote_abm.message = await self.parse_satori_elements(quote_content)
+
+            quote_abm.message_str = ""
+            for comp in quote_abm.message:
+                if isinstance(comp, Plain):
+                    quote_abm.message_str += comp.text
+
+            quote_abm.timestamp = int(quote.get("timestamp", time.time()))
+
+            # 如果没有任何内容，使用默认文本
+            if not quote_abm.message_str.strip():
+                quote_abm.message_str = "[引用消息]"
+
+            return quote_abm
+        except Exception as e:
+            logger.error(f"转换引用消息失败: {e}")
+            return None
+
+    async def parse_satori_elements(self, content: str) -> list:
+        """解析 Satori 消息元素"""
+        elements = []
+
+        if not content:
+            return elements
+
+        try:
+            # 处理命名空间前缀问题
+            processed_content = content
+            if ":" in content and not content.startswith("<root"):
+                prefixes = self._extract_namespace_prefixes(content)
+
+                # 构建命名空间声明
+                ns_declarations = " ".join(
+                    [
+                        f'xmlns:{prefix}="http://temp.uri/{prefix}"'
+                        for prefix in prefixes
+                    ]
+                )
+
+                # 包装内容
+                processed_content = f"<root {ns_declarations}>{content}</root>"
+            elif not content.startswith("<root"):
+                processed_content = f"<root>{content}</root>"
+            else:
+                processed_content = content
+
+            root = ET.fromstring(processed_content)
+            await self._parse_xml_node(root, elements)
+        except ET.ParseError as e:
+            logger.error(f"解析 Satori 元素时发生解析错误: {e}, 错误内容: {content}")
+            # 如果解析失败，将整个内容当作纯文本
+            if content.strip():
+                elements.append(Plain(text=content))
+        except Exception as e:
+            logger.error(f"解析 Satori 元素时发生未知错误: {e}")
+            raise e
+
+        # 如果没有解析到任何元素，将整个内容当作纯文本
+        if not elements and content.strip():
+            elements.append(Plain(text=content))
+
+        return elements
+
+    async def _parse_xml_node(self, node: ET.Element, elements: list) -> None:
+        """递归解析 XML 节点"""
+        if node.text and node.text.strip():
+            elements.append(Plain(text=node.text))
+
+        for child in node:
+            # 获取标签名，去除命名空间前缀
+            tag_name = child.tag
+            if "}" in tag_name:
+                tag_name = tag_name.split("}")[1]
+            tag_name = tag_name.lower()
+
+            attrs = child.attrib
+
+            if tag_name == "at":
+                user_id = attrs.get("id") or attrs.get("name", "")
+                elements.append(At(qq=user_id, name=user_id))
+
+            elif tag_name in ("img", "image"):
+                src = attrs.get("src", "")
+                if not src:
+                    continue
+                elements.append(Image(file=src))
+
+            elif tag_name == "file":
+                src = attrs.get("src", "")
+                name = attrs.get("name", "文件")
+                if src:
+                    elements.append(File(name=name, file=src))
+
+            elif tag_name in ("audio", "record"):
+                src = attrs.get("src", "")
+                if not src:
+                    continue
+                elements.append(Record(file=src))
+
+            elif tag_name == "quote":
+                # quote标签已经被特殊处理
+                pass
+
+            elif tag_name == "face":
+                face_id = attrs.get("id", "")
+                face_name = attrs.get("name", "")
+                face_type = attrs.get("type", "")
+
+                if face_name:
+                    elements.append(Plain(text=f"[表情:{face_name}]"))
+                elif face_id and face_type:
+                    elements.append(Plain(text=f"[表情ID:{face_id},类型:{face_type}]"))
+                elif face_id:
+                    elements.append(Plain(text=f"[表情ID:{face_id}]"))
+                else:
+                    elements.append(Plain(text="[表情]"))
+
+            elif tag_name == "ark":
+                # 作为纯文本添加到消息链中
+                data = attrs.get("data", "")
+                if data:
+                    import html
+
+                    decoded_data = html.unescape(data)
+                    elements.append(Plain(text=f"[ARK卡片数据: {decoded_data}]"))
+                else:
+                    elements.append(Plain(text="[ARK卡片]"))
+
+            elif tag_name == "json":
+                # JSON标签 视为ARK卡片消息
+                data = attrs.get("data", "")
+                if data:
+                    import html
+
+                    decoded_data = html.unescape(data)
+                    elements.append(Plain(text=f"[ARK卡片数据: {decoded_data}]"))
+                else:
+                    elements.append(Plain(text="[JSON卡片]"))
+
+            else:
+                # 未知标签，递归处理其内容
+                if child.text and child.text.strip():
+                    elements.append(Plain(text=child.text))
+                await self._parse_xml_node(child, elements)
+
+            # 处理标签后的文本
+            if child.tail and child.tail.strip():
+                elements.append(Plain(text=child.tail))
+
+    async def handle_msg(self, message: AstrBotMessage):
+        from .satori_event import SatoriPlatformEvent
+
+        message_event = SatoriPlatformEvent(
+            message_str=message.message_str,
+            message_obj=message,
+            platform_meta=self.meta(),
+            session_id=message.session_id,
+            adapter=self,
+        )
+        self.commit_event(message_event)
+
+    async def send_http_request(
+        self,
+        method: str,
+        path: str,
+        data: dict | None = None,
+        platform: str | None = None,
+        user_id: str | None = None,
+    ) -> dict:
+        if not self.session:
+            raise Exception("HTTP session 未初始化")
+
+        headers = {
+            "Content-Type": "application/json",
+        }
+
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        if platform and user_id:
+            headers["satori-platform"] = platform
+            headers["satori-user-id"] = user_id
+        elif self.logins:
+            current_login = self.logins[0]
+            headers["satori-platform"] = current_login.get("platform", "")
+            user = current_login.get("user", {})
+            headers["satori-user-id"] = user.get("id", "") if user else ""
+
+        if not path.startswith("/"):
+            path = "/" + path
+
+        # 使用新的API地址配置
+        url = f"{self.api_base_url.rstrip('/')}{path}"
+
+        try:
+            async with self.session.request(
+                method, url, json=data, headers=headers
+            ) as response:
+                if response.status == 200:
+                    result = await response.json()
+                    return result
+                else:
+                    return {}
+        except Exception as e:
+            logger.error(f"Satori HTTP 请求异常: {e}")
+            return {}
+
+    async def terminate(self):
+        self.running = False
+
+        if self.heartbeat_task:
+            self.heartbeat_task.cancel()
+
+        if self.ws:
+            try:
+                await self.ws.close()
+            except Exception as e:
+                logger.error(f"Satori WebSocket 关闭异常: {e}")
+
+        if self.session:
+            await self.session.close()

astrbot/core/platform/sources/satori/satori_event.py

@@ -0,0 +1,252 @@
+from typing import TYPE_CHECKING
+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, At, File, Record, Video, Reply
+
+if TYPE_CHECKING:
+    from .satori_adapter import SatoriPlatformAdapter
+
+
+class SatoriPlatformEvent(AstrMessageEvent):
+    def __init__(
+        self,
+        message_str: str,
+        message_obj: AstrBotMessage,
+        platform_meta: PlatformMetadata,
+        session_id: str,
+        adapter: "SatoriPlatformAdapter",
+    ):
+        # 更新平台元数据
+        if adapter and hasattr(adapter, "logins") and adapter.logins:
+            current_login = adapter.logins[0]
+            platform_name = current_login.get("platform", "satori")
+            user = current_login.get("user", {})
+            user_id = user.get("id", "") if user else ""
+            if not platform_meta.id and user_id:
+                platform_meta.id = f"{platform_name}({user_id})"
+
+        super().__init__(message_str, message_obj, platform_meta, session_id)
+        self.adapter = adapter
+        self.platform = None
+        self.user_id = None
+        if (
+            hasattr(message_obj, "raw_message")
+            and message_obj.raw_message
+            and isinstance(message_obj.raw_message, dict)
+        ):
+            login = message_obj.raw_message.get("login", {})
+            self.platform = login.get("platform")
+            user = login.get("user", {})
+            self.user_id = user.get("id") if user else None
+
+    @classmethod
+    async def send_with_adapter(
+        cls, adapter: "SatoriPlatformAdapter", message: MessageChain, session_id: str
+    ):
+        try:
+            content_parts = []
+
+            for component in message.chain:
+                if isinstance(component, Plain):
+                    text = (
+                        component.text.replace("&", "&")
+                        .replace("<", "&lt;")
+                        .replace(">", "&gt;")
+                    )
+                    content_parts.append(text)
+
+                elif isinstance(component, At):
+                    if component.qq:
+                        content_parts.append(f'<at id="{component.qq}"/>')
+                    elif component.name:
+                        content_parts.append(f'<at name="{component.name}"/>')
+
+                elif isinstance(component, Image):
+                    try:
+                        image_base64 = await component.convert_to_base64()
+                        if image_base64:
+                            content_parts.append(
+                                f'<img src="data:image/jpeg;base64,{image_base64}"/>'
+                            )
+                    except Exception as e:
+                        logger.error(f"图片转换为base64失败: {e}")
+
+                elif isinstance(component, File):
+                    content_parts.append(
+                        f'<file src="{component.file}" name="{component.name or "文件"}"/>'
+                    )
+
+                elif isinstance(component, Record):
+                    try:
+                        record_base64 = await component.convert_to_base64()
+                        if record_base64:
+                            content_parts.append(
+                                f'<audio src="data:audio/wav;base64,{record_base64}"/>'
+                            )
+                    except Exception as e:
+                        logger.error(f"语音转换为base64失败: {e}")
+
+                elif isinstance(component, Reply):
+                    content_parts.append(f'<reply id="{component.id}"/>')
+
+                elif isinstance(component, Video):
+                    try:
+                        video_path_url = await component.convert_to_file_path()
+                        if video_path_url:
+                            content_parts.append(f'<video src="{video_path_url}"/>')
+                    except Exception as e:
+                        logger.error(f"视频文件转换失败: {e}")
+
+            content = "".join(content_parts)
+            channel_id = session_id
+            data = {"channel_id": channel_id, "content": content}
+
+            platform = None
+            user_id = None
+
+            if hasattr(adapter, "logins") and adapter.logins:
+                current_login = adapter.logins[0]
+                platform = current_login.get("platform", "")
+                user = current_login.get("user", {})
+                user_id = user.get("id", "") if user else ""
+
+            result = await adapter.send_http_request(
+                "POST", "/message.create", data, platform, user_id
+            )
+            if result:
+                return result
+            else:
+                return None
+
+        except Exception as e:
+            logger.error(f"Satori 消息发送异常: {e}")
+            return None
+
+    async def send(self, message: MessageChain):
+        platform = getattr(self, "platform", None)
+        user_id = getattr(self, "user_id", None)
+
+        if not platform or not user_id:
+            if hasattr(self.adapter, "logins") and self.adapter.logins:
+                current_login = self.adapter.logins[0]
+                platform = current_login.get("platform", "")
+                user = current_login.get("user", {})
+                user_id = user.get("id", "") if user else ""
+
+        try:
+            content_parts = []
+
+            for component in message.chain:
+                if isinstance(component, Plain):
+                    text = (
+                        component.text.replace("&", "&amp;")
+                        .replace("<", "&lt;")
+                        .replace(">", "&gt;")
+                    )
+                    content_parts.append(text)
+
+                elif isinstance(component, At):
+                    if component.qq:
+                        content_parts.append(f'<at id="{component.qq}"/>')
+                    elif component.name:
+                        content_parts.append(f'<at name="{component.name}"/>')
+
+                elif isinstance(component, Image):
+                    try:
+                        image_base64 = await component.convert_to_base64()
+                        if image_base64:
+                            content_parts.append(
+                                f'<img src="data:image/jpeg;base64,{image_base64}"/>'
+                            )
+                    except Exception as e:
+                        logger.error(f"图片转换为base64失败: {e}")
+
+                elif isinstance(component, File):
+                    content_parts.append(
+                        f'<file src="{component.file}" name="{component.name or "文件"}"/>'
+                    )
+
+                elif isinstance(component, Record):
+                    try:
+                        record_base64 = await component.convert_to_base64()
+                        if record_base64:
+                            content_parts.append(
+                                f'<audio src="data:audio/wav;base64,{record_base64}"/>'
+                            )
+                    except Exception as e:
+                        logger.error(f"语音转换为base64失败: {e}")
+
+                elif isinstance(component, Reply):
+                    content_parts.append(f'<reply id="{component.id}"/>')
+
+                elif isinstance(component, Video):
+                    try:
+                        video_path_url = await component.convert_to_file_path()
+                        if video_path_url:
+                            content_parts.append(f'<video src="{video_path_url}"/>')
+                    except Exception as e:
+                        logger.error(f"视频文件转换失败: {e}")
+
+            content = "".join(content_parts)
+            channel_id = self.session_id
+            data = {"channel_id": channel_id, "content": content}
+
+            result = await self.adapter.send_http_request(
+                "POST", "/message.create", data, platform, user_id
+            )
+            if not result:
+                logger.error("Satori 消息发送失败")
+        except Exception as e:
+            logger.error(f"Satori 消息发送异常: {e}")
+
+        await super().send(message)
+
+    async def send_streaming(self, generator, use_fallback: bool = False):
+        try:
+            content_parts = []
+
+            async for chain in generator:
+                if isinstance(chain, MessageChain):
+                    if chain.type == "break":
+                        if content_parts:
+                            content = "".join(content_parts)
+                            temp_chain = MessageChain([Plain(text=content)])
+                            await self.send(temp_chain)
+                            content_parts = []
+                        continue
+
+                    for component in chain.chain:
+                        if isinstance(component, Plain):
+                            content_parts.append(component.text)
+                        elif isinstance(component, Image):
+                            if content_parts:
+                                content = "".join(content_parts)
+                                temp_chain = MessageChain([Plain(text=content)])
+                                await self.send(temp_chain)
+                                content_parts = []
+                            try:
+                                image_base64 = await component.convert_to_base64()
+                                if image_base64:
+                                    img_chain = MessageChain(
+                                        [
+                                            Plain(
+                                                text=f'<img src="data:image/jpeg;base64,{image_base64}"/>'
+                                            )
+                                        ]
+                                    )
+                                    await self.send(img_chain)
+                            except Exception as e:
+                                logger.error(f"图片转换为base64失败: {e}")
+                        else:
+                            content_parts.append(str(component))
+
+            if content_parts:
+                content = "".join(content_parts)
+                temp_chain = MessageChain([Plain(text=content)])
+                await self.send(temp_chain)
+
+        except Exception as e:
+            logger.error(f"Satori 流式消息发送异常: {e}")
+
+        return await super().send_streaming(generator, use_fallback)

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

@@ -308,7 +308,9 @@ class SlackAdapter(Platform):
                     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()}")
+                    logger.error(
+                        f"Failed to download slack file: {resp.status} {await resp.text()}"
+                    )
                     raise Exception(f"下载文件失败: {resp.status}")
 
     async def run(self) -> Awaitable[Any]:

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

@@ -75,7 +75,13 @@ class SlackMessageEvent(AstrMessageEvent):
                     "text": {"type": "mrkdwn", "text": "文件上传失败"},
                 }
             file_url = response["files"][0]["permalink"]
-            return {"type": "section", "text": {"type": "mrkdwn", "text": f"文件: <{file_url}|{segment.name or '文件'}>"}}
+            return {
+                "type": "section",
+                "text": {
+                    "type": "mrkdwn",
+                    "text": f"文件: <{file_url}|{segment.name or '文件'}>",
+                },
+            }
         else:
             return {"type": "section", "text": {"type": "mrkdwn", "text": str(segment)}}
 

astrbot/core/platform/sources/telegram/tg_adapter.py

@@ -95,9 +95,8 @@ class TelegramPlatformAdapter(Platform):
 
     @override
     def meta(self) -> PlatformMetadata:
-        return PlatformMetadata(
-            name="telegram", description="telegram 适配器", id=self.config.get("id")
-        )
+        id_ = self.config.get("id") or "telegram"
+        return PlatformMetadata(name="telegram", description="telegram 适配器", id=id_)
 
     @override
     async def run(self):
@@ -117,6 +116,10 @@ class TelegramPlatformAdapter(Platform):
             )
             self.scheduler.start()
 
+        if not self.application.updater:
+            logger.error("Telegram Updater is not initialized. Cannot start polling.")
+            return
+
         queue = self.application.updater.start_polling()
         logger.info("Telegram Platform Adapter is running.")
         await queue
@@ -183,7 +186,6 @@ class TelegramPlatformAdapter(Platform):
             return None
 
         if not re.match(r"^[a-z0-9_]+$", cmd_name) or len(cmd_name) > 32:
-            logger.debug(f"跳过无法注册的命令: {cmd_name}")
             return None
 
         # Build description.
@@ -195,6 +197,11 @@ class TelegramPlatformAdapter(Platform):
         return cmd_name, description
 
     async def start(self, update: Update, context: ContextTypes.DEFAULT_TYPE):
+        if not update.effective_chat:
+            logger.warning(
+                "Received a start command without an effective chat, skipping /start reply."
+            )
+            return
         await context.bot.send_message(
             chat_id=update.effective_chat.id, text=self.config["start_message"]
         )
@@ -207,15 +214,20 @@ class TelegramPlatformAdapter(Platform):
 
     async def convert_message(
         self, update: Update, context: ContextTypes.DEFAULT_TYPE, get_reply=True
-    ) -> AstrBotMessage:
+    ) -> AstrBotMessage | None:
         """转换 Telegram 的消息对象为 AstrBotMessage 对象。
 
         @param update: Telegram 的 Update 对象。
         @param context: Telegram 的 Context 对象。
         @param get_reply: 是否获取回复消息。这个参数是为了防止多个回复嵌套。
         """
+        if not update.message:
+            logger.warning("Received an update without a message.")
+            return None
+
         message = AstrBotMessage()
         message.session_id = str(update.message.chat.id)
+
         # 获得是群聊还是私聊
         if update.message.chat.type == ChatType.PRIVATE:
             message.type = MessageType.FRIEND_MESSAGE
@@ -226,10 +238,13 @@ class TelegramPlatformAdapter(Platform):
                 # Topic Group
                 message.group_id += "#" + str(update.message.message_thread_id)
                 message.session_id = message.group_id
-
         message.message_id = str(update.message.message_id)
+        _from_user = update.message.from_user
+        if not _from_user:
+            logger.warning("[Telegram] Received a message without a from_user.")
+            return None
         message.sender = MessageMember(
-            str(update.message.from_user.id), update.message.from_user.username
+            str(_from_user.id), _from_user.username or "Unknown"
         )
         message.self_id = str(context.bot.username)
         message.raw_message = update
@@ -248,22 +263,32 @@ class TelegramPlatformAdapter(Platform):
             )
             reply_abm = await self.convert_message(reply_update, context, False)
 
-            message.message.append(
-                Comp.Reply(
-                    id=reply_abm.message_id,
-                    chain=reply_abm.message,
-                    sender_id=reply_abm.sender.user_id,
-                    sender_nickname=reply_abm.sender.nickname,
-                    time=reply_abm.timestamp,
-                    message_str=reply_abm.message_str,
-                    text=reply_abm.message_str,
-                    qq=reply_abm.sender.user_id,
+            if reply_abm:
+                message.message.append(
+                    Comp.Reply(
+                        id=reply_abm.message_id,
+                        chain=reply_abm.message,
+                        sender_id=reply_abm.sender.user_id,
+                        sender_nickname=reply_abm.sender.nickname,
+                        time=reply_abm.timestamp,
+                        message_str=reply_abm.message_str,
+                        text=reply_abm.message_str,
+                        qq=reply_abm.sender.user_id,
+                    )
                 )
-            )
 
         if update.message.text:
             # 处理文本消息
             plain_text = update.message.text
+            if (
+                message.type == MessageType.GROUP_MESSAGE
+                and update.message
+                and update.message.reply_to_message
+                and update.message.reply_to_message.from_user
+                and update.message.reply_to_message.from_user.id == context.bot.id
+            ):
+                plain_text2 = f"/@{context.bot.username} " + plain_text
+                plain_text = plain_text2
 
             # 群聊场景命令特殊处理
             if plain_text.startswith("/"):
@@ -329,15 +354,25 @@ class TelegramPlatformAdapter(Platform):
 
         elif update.message.document:
             file = await update.message.document.get_file()
-            message.message = [
-                Comp.File(file=file.file_path, name=update.message.document.file_name),
-            ]
+            file_name = update.message.document.file_name or uuid.uuid4().hex
+            file_path = file.file_path
+            if file_path is None:
+                logger.warning(
+                    f"Telegram document file_path is None, cannot save the file {file_name}."
+                )
+            else:
+                message.message.append(Comp.File(file=file_path, name=file_name))
 
         elif update.message.video:
             file = await update.message.video.get_file()
-            message.message = [
-                Comp.Video(file=file.file_path, path=file.file_path),
-            ]
+            file_name = update.message.video.file_name or uuid.uuid4().hex
+            file_path = file.file_path
+            if file_path is None:
+                logger.warning(
+                    f"Telegram video file_path is None, cannot save the file {file_name}."
+                )
+            else:
+                message.message.append(Comp.Video(file=file_path, path=file.file_path))
 
         return message
 

astrbot/core/platform/sources/telegram/tg_event.py

@@ -16,6 +16,7 @@ from telegram.ext import ExtBot
 from astrbot.core.utils.io import download_file
 from astrbot import logger
 from astrbot.core.utils.astrbot_path import get_astrbot_data_path
+from telegram import ReactionTypeEmoji, ReactionTypeCustomEmoji
 
 
 class TelegramPlatformEvent(AstrMessageEvent):
@@ -66,7 +67,9 @@ class TelegramPlatformEvent(AstrMessageEvent):
         return chunks
 
     @classmethod
-    async def send_with_client(cls, client: ExtBot, message: MessageChain, user_name: str):
+    async def send_with_client(
+        cls, client: ExtBot, message: MessageChain, user_name: str
+    ):
         image_path = None
 
         has_reply = False
@@ -133,6 +136,39 @@ class TelegramPlatformEvent(AstrMessageEvent):
             await self.send_with_client(self.client, message, self.get_sender_id())
         await super().send(message)
 
+    async def react(self, emoji: str | None, big: bool = False):
+        """
+        给原消息添加 Telegram 反应：
+        - 普通 emoji：传入 '👍'、'😂' 等
+        - 自定义表情：传入其 custom_emoji_id（纯数字字符串）
+        - 取消本机器人的反应：传入 None 或空字符串
+        """
+        try:
+            # 解析 chat_id（去掉超级群的 "#<thread_id>" 片段）
+            if self.get_message_type() == MessageType.GROUP_MESSAGE:
+                chat_id = (self.message_obj.group_id or "").split("#")[0]
+            else:
+                chat_id = self.get_sender_id()
+
+            message_id = int(self.message_obj.message_id)
+
+            # 组装 reaction 参数（必须是 ReactionType 的列表）
+            if not emoji:  # 清空本 bot 的反应
+                reaction_param = []  # 空列表表示移除本 bot 的反应
+            elif emoji.isdigit():  # 自定义表情：传 custom_emoji_id
+                reaction_param = [ReactionTypeCustomEmoji(emoji)]
+            else:  # 普通 emoji
+                reaction_param = [ReactionTypeEmoji(emoji)]
+
+            await self.client.set_message_reaction(
+                chat_id=chat_id,
+                message_id=message_id,
+                reaction=reaction_param,  # 注意是列表
+                is_big=big,  # 可选：大动画
+            )
+        except Exception as e:
+            logger.error(f"[Telegram] 添加反应失败: {e}")
+
     async def send_streaming(self, generator, use_fallback: bool = False):
         message_thread_id = None
 
@@ -216,7 +252,6 @@ class TelegramPlatformEvent(AstrMessageEvent):
                     try:
                         msg = await self.client.send_message(text=delta, **payload)
                         current_content = delta
-                        delta = ""
                     except Exception as e:
                         logger.warning(f"发送消息失败(streaming): {e!s}")
                     message_id = msg.message_id

astrbot/core/platform/sources/webchat/webchat_adapter.py

@@ -77,7 +77,7 @@ class WebChatAdapter(Platform):
         os.makedirs(self.imgs_dir, exist_ok=True)
 
         self.metadata = PlatformMetadata(
-            name="webchat", description="webchat", id=self.config.get("id", "")
+            name="webchat", description="webchat", id="webchat"
         )
 
     async def send_by_session(
@@ -91,7 +91,6 @@ class WebChatAdapter(Platform):
 
         abm = AstrBotMessage()
         abm.self_id = "webchat"
-        abm.tag = "webchat"
         abm.sender = MessageMember(username, username)
 
         abm.type = MessageType.FRIEND_MESSAGE

astrbot/core/platform/sources/webchat/webchat_queue_mgr.py

@@ -1,5 +1,6 @@
 import asyncio
 
+
 class WebChatQueueMgr:
     def __init__(self) -> None:
         self.queues = {}
@@ -30,4 +31,5 @@ class WebChatQueueMgr:
         """Check if a queue exists for the given conversation ID"""
         return conversation_id in self.queues
 
+
 webchat_queue_mgr = WebChatQueueMgr()

astrbot/core/platform/sources/wechatpadpro/wechatpadpro_adapter.py

@@ -213,10 +213,10 @@ class WeChatPadProAdapter(Platform):
     def _extract_auth_key(self, data):
         """Helper method to extract auth_key from response data."""
         if isinstance(data, dict):
-            auth_keys = data.get("authKeys") # 新接口
+            auth_keys = data.get("authKeys")  # 新接口
             if isinstance(auth_keys, list) and auth_keys:
                 return auth_keys[0]
-        elif isinstance(data, list) and data: # 旧接口
+        elif isinstance(data, list) and data:  # 旧接口
             return data[0]
         return None
 
@@ -234,7 +234,9 @@ class WeChatPadProAdapter(Platform):
             try:
                 async with session.post(url, params=params, json=payload) as response:
                     if response.status != 200:
-                        logger.error(f"生成授权码失败: {response.status}, {await response.text()}")
+                        logger.error(
+                            f"生成授权码失败: {response.status}, {await response.text()}"
+                        )
                         return
 
                     response_data = await response.json()
@@ -245,7 +247,9 @@ class WeChatPadProAdapter(Platform):
                         if self.auth_key:
                             logger.info("成功获取授权码")
                         else:
-                            logger.error(f"生成授权码成功但未找到授权码: {response_data}")
+                            logger.error(
+                                f"生成授权码成功但未找到授权码: {response_data}"
+                            )
                     else:
                         logger.error(f"生成授权码失败: {response_data}")
             except aiohttp.ClientConnectorError as e:

astrbot/core/platform/sources/wecom/wecom_adapter.py

@@ -185,6 +185,7 @@ class WecomPlatformAdapter(Platform):
         return PlatformMetadata(
             "wecom",
             "wecom 适配器",
+            id=self.config.get("id", "wecom"),
         )
 
     @override

astrbot/core/platform/sources/wecom/wecom_kf.py

@@ -48,7 +48,12 @@ class WeChatKF(BaseWeChatAPI):
         注意：可能会出现返回条数少于limit的情况，需结合返回的has_more字段判断是否继续请求。
         :return: 接口调用结果
         """
-        data = {"token": token, "cursor": cursor, "limit": limit, "open_kfid": open_kfid}
+        data = {
+            "token": token,
+            "cursor": cursor,
+            "limit": limit,
+            "open_kfid": open_kfid,
+        }
         return self._post("kf/sync_msg", data=data)
 
     def get_service_state(self, open_kfid, external_userid):
@@ -72,7 +77,9 @@ class WeChatKF(BaseWeChatAPI):
         }
         return self._post("kf/service_state/get", data=data)
 
-    def trans_service_state(self, open_kfid, external_userid, service_state, servicer_userid=""):
+    def trans_service_state(
+        self, open_kfid, external_userid, service_state, servicer_userid=""
+    ):
         """
         变更会话状态
 
@@ -180,7 +187,9 @@ class WeChatKF(BaseWeChatAPI):
         """
         return self._get("kf/customer/get_upgrade_service_config")
 
-    def upgrade_service(self, open_kfid, external_userid, service_type, member=None, groupchat=None):
+    def upgrade_service(
+        self, open_kfid, external_userid, service_type, member=None, groupchat=None
+    ):
         """
         为客户升级为专员或客户群服务
 
@@ -246,7 +255,9 @@ class WeChatKF(BaseWeChatAPI):
         data = {"open_kfid": open_kfid, "start_time": start_time, "end_time": end_time}
         return self._post("kf/get_corp_statistic", data=data)
 
-    def get_servicer_statistic(self, start_time, end_time, open_kfid=None, servicer_userid=None):
+    def get_servicer_statistic(
+        self, start_time, end_time, open_kfid=None, servicer_userid=None
+    ):
         """
         获取「客户数据统计」接待人员明细数据
 

astrbot/core/platform/sources/wecom/wecom_kf_message.py

@@ -26,6 +26,7 @@ from optionaldict import optionaldict
 
 from wechatpy.client.api.base import BaseWeChatAPI
 
+
 class WeChatKFMessage(BaseWeChatAPI):
     """
     发送微信客服消息
@@ -125,35 +126,55 @@ class WeChatKFMessage(BaseWeChatAPI):
             msg={"msgtype": "news", "link": {"link": articles_data}},
         )
 
-    def send_msgmenu(self, user_id, open_kfid, head_content, menu_list, tail_content, msgid=""):
+    def send_msgmenu(
+        self, user_id, open_kfid, head_content, menu_list, tail_content, msgid=""
+    ):
         return self.send(
             user_id,
             open_kfid,
             msgid,
             msg={
                 "msgtype": "msgmenu",
-                "msgmenu": {"head_content": head_content, "list": menu_list, "tail_content": tail_content},
+                "msgmenu": {
+                    "head_content": head_content,
+                    "list": menu_list,
+                    "tail_content": tail_content,
+                },
             },
         )
 
-    def send_location(self, user_id, open_kfid, name, address, latitude, longitude, msgid=""):
+    def send_location(
+        self, user_id, open_kfid, name, address, latitude, longitude, msgid=""
+    ):
         return self.send(
             user_id,
             open_kfid,
             msgid,
             msg={
                 "msgtype": "location",
-                "msgmenu": {"name": name, "address": address, "latitude": latitude, "longitude": longitude},
+                "msgmenu": {
+                    "name": name,
+                    "address": address,
+                    "latitude": latitude,
+                    "longitude": longitude,
+                },
             },
         )
 
-    def send_miniprogram(self, user_id, open_kfid, appid, title, thumb_media_id, pagepath, msgid=""):
+    def send_miniprogram(
+        self, user_id, open_kfid, appid, title, thumb_media_id, pagepath, msgid=""
+    ):
         return self.send(
             user_id,
             open_kfid,
             msgid,
             msg={
                 "msgtype": "miniprogram",
-                "msgmenu": {"appid": appid, "title": title, "thumb_media_id": thumb_media_id, "pagepath": pagepath},
+                "msgmenu": {
+                    "appid": appid,
+                    "title": title,
+                    "thumb_media_id": thumb_media_id,
+                    "pagepath": pagepath,
+                },
             },
         )

astrbot/core/platform/sources/wecom_ai_bot/WXBizJsonMsgCrypt.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python
+# -*- encoding:utf-8 -*-
+
+"""对企业微信发送给企业后台的消息加解密示例代码.
+@copyright: Copyright (c) 1998-2020 Tencent Inc.
+
+"""
+# ------------------------------------------------------------------------
+
+import logging
+import base64
+import random
+import hashlib
+import time
+import struct
+from Crypto.Cipher import AES
+import socket
+import json
+
+from . import ierror
+
+"""
+关于Crypto.Cipher模块，ImportError: No module named 'Crypto'解决方案
+请到官方网站 https://www.dlitz.net/software/pycrypto/ 下载pycrypto。
+下载后，按照README中的“Installation”小节的提示进行pycrypto安装。
+"""
+
+
+class FormatException(Exception):
+    pass
+
+
+def throw_exception(message, exception_class=FormatException):
+    """my define raise exception function"""
+    raise exception_class(message)
+
+
+class SHA1:
+    """计算企业微信的消息签名接口"""
+
+    def getSHA1(self, token, timestamp, nonce, encrypt):
+        """用SHA1算法生成安全签名
+        @param token:  票据
+        @param timestamp: 时间戳
+        @param encrypt: 密文
+        @param nonce: 随机字符串
+        @return: 安全签名
+        """
+        try:
+            # 确保所有输入都是字符串类型
+            if isinstance(encrypt, bytes):
+                encrypt = encrypt.decode("utf-8")
+
+            sortlist = [str(token), str(timestamp), str(nonce), str(encrypt)]
+            sortlist.sort()
+            sha = hashlib.sha1()
+            sha.update("".join(sortlist).encode("utf-8"))
+            return ierror.WXBizMsgCrypt_OK, sha.hexdigest()
+
+        except Exception as e:
+            print(e)
+            return ierror.WXBizMsgCrypt_ComputeSignature_Error, None
+
+
+class JsonParse:
+    """提供提取消息格式中的密文及生成回复消息格式的接口"""
+
+    # json消息模板
+    AES_TEXT_RESPONSE_TEMPLATE = """{
+        "encrypt": "%(msg_encrypt)s",
+        "msgsignature": "%(msg_signaturet)s",
+        "timestamp": "%(timestamp)s",
+        "nonce": "%(nonce)s"
+    }"""
+
+    def extract(self, jsontext):
+        """提取出json数据包中的加密消息
+        @param jsontext: 待提取的json字符串
+        @return: 提取出的加密消息字符串
+        """
+        try:
+            json_dict = json.loads(jsontext)
+            return ierror.WXBizMsgCrypt_OK, json_dict["encrypt"]
+        except Exception as e:
+            print(e)
+            return ierror.WXBizMsgCrypt_ParseJson_Error, None
+
+    def generate(self, encrypt, signature, timestamp, nonce):
+        """生成json消息
+        @param encrypt: 加密后的消息密文
+        @param signature: 安全签名
+        @param timestamp: 时间戳
+        @param nonce: 随机字符串
+        @return: 生成的json字符串
+        """
+        resp_dict = {
+            "msg_encrypt": encrypt,
+            "msg_signaturet": signature,
+            "timestamp": timestamp,
+            "nonce": nonce,
+        }
+        resp_json = self.AES_TEXT_RESPONSE_TEMPLATE % resp_dict
+        return resp_json
+
+
+class PKCS7Encoder:
+    """提供基于PKCS7算法的加解密接口"""
+
+    block_size = 32
+
+    def encode(self, text):
+        """对需要加密的明文进行填充补位
+        @param text: 需要进行填充补位操作的明文(bytes类型)
+        @return: 补齐明文字符串(bytes类型)
+        """
+        text_length = len(text)
+        # 计算需要填充的位数
+        amount_to_pad = self.block_size - (text_length % self.block_size)
+        if amount_to_pad == 0:
+            amount_to_pad = self.block_size
+        # 获得补位所用的字符
+        pad = bytes([amount_to_pad])
+        # 确保text是bytes类型
+        if isinstance(text, str):
+            text = text.encode("utf-8")
+        return text + pad * amount_to_pad
+
+    def decode(self, decrypted):
+        """删除解密后明文的补位字符
+        @param decrypted: 解密后的明文
+        @return: 删除补位字符后的明文
+        """
+        pad = ord(decrypted[-1])
+        if pad < 1 or pad > 32:
+            pad = 0
+        return decrypted[:-pad]
+
+
+class Prpcrypt(object):
+    """提供接收和推送给企业微信消息的加解密接口"""
+
+    def __init__(self, key):
+        # self.key = base64.b64decode(key+"=")
+        self.key = key
+        # 设置加解密模式为AES的CBC模式
+        self.mode = AES.MODE_CBC
+
+    def encrypt(self, text, receiveid):
+        """对明文进行加密
+        @param text: 需要加密的明文
+        @return: 加密得到的字符串
+        """
+        # 16位随机字符串添加到明文开头
+        text = text.encode()
+        text = (
+            self.get_random_str()
+            + struct.pack("I", socket.htonl(len(text)))
+            + text
+            + receiveid.encode()
+        )
+
+        # 使用自定义的填充方式对明文进行补位填充
+        pkcs7 = PKCS7Encoder()
+        text = pkcs7.encode(text)
+        # 加密
+        cryptor = AES.new(self.key, self.mode, self.key[:16])  # type: ignore
+        try:
+            ciphertext = cryptor.encrypt(text)
+            # 使用BASE64对加密后的字符串进行编码
+            return ierror.WXBizMsgCrypt_OK, base64.b64encode(ciphertext)
+        except Exception as e:
+            logger = logging.getLogger("astrbot")
+            logger.error(e)
+            return ierror.WXBizMsgCrypt_EncryptAES_Error, None
+
+    def decrypt(self, text, receiveid):
+        """对解密后的明文进行补位删除
+        @param text: 密文
+        @return: 删除填充补位后的明文
+        """
+        try:
+            cryptor = AES.new(self.key, self.mode, self.key[:16])  # type: ignore
+            # 使用BASE64对密文进行解码，然后AES-CBC解密
+            plain_text = cryptor.decrypt(base64.b64decode(text))
+        except Exception as e:
+            print(e)
+            return ierror.WXBizMsgCrypt_DecryptAES_Error, None
+        try:
+            pad = plain_text[-1]
+            # 去掉补位字符串
+            # pkcs7 = PKCS7Encoder()
+            # plain_text = pkcs7.encode(plain_text)
+            # 去除16位随机字符串
+            content = plain_text[16:-pad]
+            json_len = socket.ntohl(struct.unpack("I", content[:4])[0])
+            json_content = content[4 : json_len + 4].decode("utf-8")
+            from_receiveid = content[json_len + 4 :].decode("utf-8")
+        except Exception as e:
+            print(e)
+            return ierror.WXBizMsgCrypt_IllegalBuffer, None
+        if from_receiveid != receiveid:
+            print("receiveid not match", receiveid, from_receiveid)
+            return ierror.WXBizMsgCrypt_ValidateCorpid_Error, None
+        return 0, json_content
+
+    def get_random_str(self):
+        """随机生成16位字符串
+        @return: 16位字符串
+        """
+        return str(random.randint(1000000000000000, 9999999999999999)).encode()
+
+
+class WXBizJsonMsgCrypt(object):
+    # 构造函数
+    def __init__(self, sToken, sEncodingAESKey, sReceiveId):
+        try:
+            self.key = base64.b64decode(sEncodingAESKey + "=")
+            assert len(self.key) == 32
+        except Exception as e:
+            throw_exception(f"[error]: EncodingAESKey invalid: {e}", FormatException)
+            # return ierror.WXBizMsgCrypt_IllegalAesKey,None
+        self.m_sToken = sToken
+        self.m_sReceiveId = sReceiveId
+
+    # 验证URL
+    # @param sMsgSignature: 签名串，对应URL参数的msg_signature
+    # @param sTimeStamp: 时间戳，对应URL参数的timestamp
+    # @param sNonce: 随机串，对应URL参数的nonce
+    # @param sEchoStr: 随机串，对应URL参数的echostr
+    # @param sReplyEchoStr: 解密之后的echostr，当return返回0时有效
+    # @return：成功0，失败返回对应的错误码
+
+    def VerifyURL(self, sMsgSignature, sTimeStamp, sNonce, sEchoStr):
+        sha1 = SHA1()
+        ret, signature = sha1.getSHA1(self.m_sToken, sTimeStamp, sNonce, sEchoStr)
+        if ret != 0:
+            return ret, None
+        if not signature == sMsgSignature:
+            return ierror.WXBizMsgCrypt_ValidateSignature_Error, None
+        pc = Prpcrypt(self.key)
+        ret, sReplyEchoStr = pc.decrypt(sEchoStr, self.m_sReceiveId)
+        return ret, sReplyEchoStr
+
+    def EncryptMsg(self, sReplyMsg, sNonce, timestamp=None):
+        # 将企业回复用户的消息加密打包
+        # @param sReplyMsg: 企业号待回复用户的消息，json格式的字符串
+        # @param sTimeStamp: 时间戳，可以自己生成，也可以用URL参数的timestamp,如为None则自动用当前时间
+        # @param sNonce: 随机串，可以自己生成，也可以用URL参数的nonce
+        # sEncryptMsg: 加密后的可以直接回复用户的密文，包括msg_signature, timestamp, nonce, encrypt的json格式的字符串,
+        # return：成功0，sEncryptMsg,失败返回对应的错误码None
+        pc = Prpcrypt(self.key)
+        ret, encrypt = pc.encrypt(sReplyMsg, self.m_sReceiveId)
+        encrypt = encrypt.decode("utf-8")  # type: ignore
+        if ret != 0:
+            return ret, None
+        if timestamp is None:
+            timestamp = str(int(time.time()))
+        # 生成安全签名
+        sha1 = SHA1()
+        ret, signature = sha1.getSHA1(self.m_sToken, timestamp, sNonce, encrypt)
+        if ret != 0:
+            return ret, None
+        jsonParse = JsonParse()
+        return ret, jsonParse.generate(encrypt, signature, timestamp, sNonce)
+
+    def DecryptMsg(self, sPostData, sMsgSignature, sTimeStamp, sNonce):
+        # 检验消息的真实性，并且获取解密后的明文
+        # @param sMsgSignature: 签名串，对应URL参数的msg_signature
+        # @param sTimeStamp: 时间戳，对应URL参数的timestamp
+        # @param sNonce: 随机串，对应URL参数的nonce
+        # @param sPostData: 密文，对应POST请求的数据
+        #  json_content: 解密后的原文，当return返回0时有效
+        # @return: 成功0，失败返回对应的错误码
+        # 验证安全签名
+        jsonParse = JsonParse()
+        ret, encrypt = jsonParse.extract(sPostData)
+        if ret != 0:
+            return ret, None
+        sha1 = SHA1()
+        ret, signature = sha1.getSHA1(self.m_sToken, sTimeStamp, sNonce, encrypt)
+        if ret != 0:
+            return ret, None
+        if not signature == sMsgSignature:
+            print("signature not match")
+            print(signature)
+            return ierror.WXBizMsgCrypt_ValidateSignature_Error, None
+        pc = Prpcrypt(self.key)
+        ret, json_content = pc.decrypt(encrypt, self.m_sReceiveId)
+        return ret, json_content

astrbot/core/platform/sources/wecom_ai_bot/__init__.py

@@ -0,0 +1,17 @@
+"""
+企业微信智能机器人平台适配器包
+"""
+
+from .wecomai_adapter import WecomAIBotAdapter
+from .wecomai_api import WecomAIBotAPIClient
+from .wecomai_event import WecomAIBotMessageEvent
+from .wecomai_server import WecomAIBotServer
+from .wecomai_utils import WecomAIBotConstants
+
+__all__ = [
+    "WecomAIBotAdapter",
+    "WecomAIBotAPIClient",
+    "WecomAIBotMessageEvent",
+    "WecomAIBotServer",
+    "WecomAIBotConstants",
+]