Merge remote-tracking branch 'origin/master' into feat/memory

- Introduced `ConversationSidebar.vue` for improved conversation management and sidebar functionality.
- Enhanced `MessageList.vue` to handle loading states and improved message rendering.
- Created new composables: `useConversations`, `useMessages`, `useMediaHandling`, `useRecording` for better code organization and reusability.
- Added loading indicators and improved user experience during message processing.
- Ensured backward compatibility and maintained existing functionalities.

.dockerignore

@@ -1,9 +1,9 @@
 # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and WebStorm
 # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
-# github acions
+# github actions
+.git
 .github/
 .*ignore
-.git/
 # User-specific stuff
 .idea/
 # Byte-compiled / optimized / DLL files
@@ -15,6 +15,10 @@ env/
 venv*/
 ENV/
 .conda/
-README*.md
 dashboard/
-data/
+data/
+changelogs/
+tests/
+.ruff_cache/
+.astrbot
+astrbot.lock

.github/FUNDING.yml

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

.github/ISSUE_TEMPLATE/PLUGIN_PUBLISH.yml

@@ -1,40 +1,57 @@
-name: '🥳 发布插件'
+name: 🥳 发布插件
-title: "[Plugin] 插件名"
 description: 提交插件到插件市场
-labels: [ "plugin-publish" ]
+title: "[Plugin] 插件名"
+labels: ["plugin-publish"]
+assignees: []
 body:
   - type: markdown
     attributes:
       value: |
-        欢迎发布插件到插件市场！请确保您的插件经过**完整的**测试。
+        欢迎发布插件到插件市场！
-  
-  - type: textarea
-    attributes:
-      label: 插件仓库
-      description: 插件的 GitHub 仓库链接
-      placeholder: >
-        如 https://github.com/Soulter/astrbot-github-cards
-
-  - type: textarea
-    attributes:
-      label: 描述
-      value: |
-        插件名: 
-        插件作者: 
-        插件简介: 
-        支持的消息平台:(必填，如 QQ、微信、飞书)
-        标签:(可选)
-        社交链接:(可选, 将会在插件市场作者名称上作为可点击的链接)
-      description: 必填。请以列表的字段按顺序将插件名、插件作者、插件简介放在这里。如果您不知道支持哪些消息平台，请填写测试过的消息平台。
-
-  - type: checkboxes
-    attributes:
-      label: Code of Conduct
-      options:
-        - label: >
-            我已阅读并同意遵守该项目的 [行为准则](https://docs.github.com/zh/site-policy/github-terms/github-community-code-of-conduct)。
-          required: true
 
   - type: markdown
     attributes:
-      value: "❤️"
+      value: |
+        ## 插件基本信息
+
+        请将插件信息填写到下方的 JSON 代码块中。其中 `tags`（插件标签）和 `social_link`（社交链接）选填。
+
+        不熟悉 JSON ？可以从 [此站](https://plugins.astrbot.app) 右下角提交。
+
+  - type: textarea
+    id: plugin-info
+    attributes:
+      label: 插件信息
+      description: 请在下方代码块中填写您的插件信息，确保反引号包裹了JSON
+      value: |
+        ```json
+        {
+          "name": "插件名，请以 astrbot_plugin_ 开头",
+          "display_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/ISSUE_TEMPLATE/bug-report.yml

@@ -1,46 +1,44 @@
-name: '🐛 报告 Bug'
+name: '🐛 Report Bug / 报告 Bug'
 title: '[Bug]'
-description: 提交报告帮助我们改进。
+description: Submit bug report to help us improve. / 提交报告帮助我们改进。
 labels: [ 'bug' ]
 body:
   - type: markdown
     attributes:
       value: |
-        感谢您抽出时间报告问题！请准确解释您的问题。如果可能，请提供一个可复现的片段（这有助于更快地解决问题）。
+        Thank you for taking the time to report this issue! Please describe your problem accurately. If possible, please provide a reproducible snippet (this will help resolve the issue more quickly). Please note that issues that are not detailed or have no logs will be closed immediately. Thank you for your understanding. / 感谢您抽出时间报告问题！请准确解释您的问题。如果可能，请提供一个可复现的片段（这有助于更快地解决问题）。请注意，不详细 / 没有日志的 issue 会被直接关闭，谢谢理解。
   - type: textarea
     attributes:
-      label: 发生了什么
+      label: What happened / 发生了什么
-      description: 描述你遇到的异常
+      description: Description
       placeholder: >
-        一个清晰且具体的描述这个异常是什么。
+        Please provide a clear and specific description of what this exception is. Please note that issues that are not detailed or have no logs will be closed immediately. Thank you for your understanding. / 一个清晰且具体的描述这个异常是什么。请注意，不详细 / 没有日志的 issue 会被直接关闭，谢谢理解。
     validations:
       required: true
 
   - type: textarea
     attributes:
-      label: 如何复现？
+      label: Reproduce / 如何复现？
       description: >
-        复现该问题的步骤
+        The steps to reproduce the issue. / 复现该问题的步骤
       placeholder: >
-        如: 1. 打开 '...'
+        Example: 1. Open '...'
     validations:
       required: true
 
   - type: textarea
     attributes:
-      label: AstrBot 版本、部署方式（如 Windows Docker Desktop 部署）、使用的提供商、使用的消息平台适配器
+      label: AstrBot version, deployment method (e.g., Windows Docker Desktop deployment), provider used, and messaging platform used. / AstrBot 版本、部署方式（如 Windows Docker Desktop 部署）、使用的提供商、使用的消息平台适配器
-      description: >
-        请提供您的 AstrBot 版本和部署方式。
       placeholder: >
-        如: 3.1.8 Docker, 3.1.7 Windows启动器
+        Example: 4.5.7 Docker, 3.1.7 Windows Launcher
     validations:
       required: true
 
   - type: dropdown
     attributes:
-      label: 操作系统
+      label: OS
       description: |
-        你在哪个操作系统上遇到了这个问题？
+        On which operating system did you encounter this problem? / 你在哪个操作系统上遇到了这个问题？
       multiple: false
       options:
         - 'Windows'
@@ -53,30 +51,30 @@ body:
 
   - type: textarea
     attributes:
-      label: 报错日志
+      label: Logs / 报错日志
       description: >
-        如报错日志、截图等。请提供完整的 Debug 级别的日志，不要介意它很长！
+        Please provide complete Debug-level logs, such as error logs and screenshots. Don't worry if they're long! Please note that issues with insufficient details or no logs will be closed immediately. Thank you for your understanding. / 如报错日志、截图等。请提供完整的 Debug 级别的日志，不要介意它很长！请注意，不详细 / 没有日志的 issue 会被直接关闭，谢谢理解。
       placeholder: >
-        请提供完整的报错日志或截图。
+        Please provide a complete error log or screenshot. / 请提供完整的报错日志或截图。
     validations:
       required: true
 
   - type: checkboxes
     attributes:
-      label: 你愿意提交 PR 吗？
+      label: Are you willing to submit a PR? / 你愿意提交 PR 吗？
       description: >
-        这不是必需的，但我们很乐意在贡献过程中为您提供指导特别是如果你已经很好地理解了如何实现修复。
+        This is not required, but we would be happy to provide guidance during the contribution process, especially if you already have a good understanding of how to implement the fix. / 这不是必需的，但我们很乐意在贡献过程中为您提供指导特别是如果你已经很好地理解了如何实现修复。
       options:
-        - label: 是的，我愿意提交 PR!
+        - label: Yes!
 
   - type: checkboxes
     attributes:
       label: Code of Conduct
       options:
         - label: >
-            我已阅读并同意遵守该项目的 [行为准则](https://docs.github.com/zh/site-policy/github-terms/github-community-code-of-conduct)。
+            I have read and agree to abide by the project's [Code of Conduct](https://docs.github.com/zh/site-policy/github-terms/github-community-code-of-conduct)。
           required: true
 
   - type: markdown
     attributes:
-      value: "感谢您填写我们的表单！"
+      value: "Thank you for filling out our form! / 感谢您填写我们的表单！"

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,14 +1,27 @@
-<!-- 如果有的话，指定这个 PR 要解决的 ISSUE -->
+<!--Please describe the motivation for this change: What problem does it solve? (e.g., Fixes XX issue, adds YY feature)-->
-修复了 #XYZ
+<!--请描述此项更改的动机：它解决了什么问题？（例如：修复了 XX issue，添加了 YY 功能）-->
 
-### Motivation
+### Modifications / 改动点
 
-<!--解释为什么要改动-->
+<!--请总结你的改动：哪些核心文件被修改了？实现了什么功能？-->
+<!--Please summarize your changes: What core files were modified? What functionality was implemented?-->
 
-### Modifications
+- [x] This is NOT a breaking change. / 这不是一个破坏性变更。
+<!-- If your changes is a breaking change, please uncheck the checkbox above -->
 
-<!--简单解释你的改动-->
+### Screenshots or Test Results / 运行截图或测试结果
 
-### Check
+<!--Please paste screenshots, GIFs, or test logs here as evidence of executing the "Verification Steps" to prove this change is effective.-->
-- [ ] 我的 Commit Message 符合良好的[规范](https://www.conventionalcommits.org/en/v1.0.0/#summary)
+<!--请粘贴截图、GIF 或测试日志，作为执行“验证步骤”的证据，证明此改动有效。-->
-- [ ] 我新增/修复/优化的功能经过良好的测试
+
+---
+
+### 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/dependabot.yml

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

.github/workflows/auto_release.yml

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

.github/workflows/code-format.yml

@@ -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

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

.github/workflows/dashboard_ci.yml

@@ -1,19 +1,30 @@
 name: AstrBot Dashboard CI
 
-on: [push]
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+    branches: [ "master" ]
 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 'latest'
 
       - name: npm install, build
         run: |
           cd dashboard
-          npm install
+          npm install pnpm -g
-          npm run build
+          pnpm install
+          pnpm i --save-dev @types/markdown-it
+          pnpm run build
 
       - name: Inject Commit SHA
         id: get_sha
@@ -21,11 +32,24 @@ 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
+        uses: actions/upload-artifact@v5
         with:
           name: dist-without-markdown
           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

@@ -3,41 +3,196 @@ name: Docker Image CI/CD
 on:
   push:
     tags:
-      - 'v*'
+      - "v*"
+  schedule:
+    # Run at 00:00 UTC every day
+    - cron: "0 0 * * *"
   workflow_dispatch:
 
 jobs:
-  publish-docker:
+  build-nightly-image:
+    if: github.event_name == 'schedule'
     runs-on: ubuntu-latest
+    env:
+      DOCKER_HUB_USERNAME: ${{ secrets.DOCKER_HUB_USERNAME }}
+      GHCR_OWNER: soulter
+      HAS_GHCR_TOKEN: ${{ secrets.GHCR_GITHUB_TOKEN != '' }}
 
     steps:
-      - name: 拉取源码
+      - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v5
         with:
           fetch-depth: 1
+          fetch-tag: true
 
-      - name: 设置 QEMU
+      - name: Check for new commits today
+        if: github.event_name == 'schedule'
+        id: check-commits
+        run: |
+          # Get commits from the last 24 hours
+          commits=$(git log --since="24 hours ago" --oneline)
+          if [ -z "$commits" ]; then
+            echo "No commits in the last 24 hours, skipping build"
+            echo "has_commits=false" >> $GITHUB_OUTPUT
+          else
+            echo "Found commits in the last 24 hours:"
+            echo "$commits"
+            echo "has_commits=true" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Exit if no commits
+        if: github.event_name == 'schedule' && steps.check-commits.outputs.has_commits == 'false'
+        run: exit 0
+
+      - 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: Determine test image tags
+        id: test-meta
+        run: |
+          short_sha=$(echo "${GITHUB_SHA}" | cut -c1-12)
+          build_date=$(date +%Y%m%d)
+          echo "short_sha=$short_sha" >> $GITHUB_OUTPUT
+          echo "build_date=$build_date" >> $GITHUB_OUTPUT
+
+      - name: Set QEMU
         uses: docker/setup-qemu-action@v3
 
-      - name: 设置 Docker Buildx
+      - name: Set Docker Buildx
         uses: docker/setup-buildx-action@v3
 
-      - name: 登录到 DockerHub
+      - name: Log in to DockerHub
         uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKER_HUB_USERNAME }}
           password: ${{ secrets.DOCKER_HUB_PASSWORD }}
 
-      - name: 构建和推送 Docker hub
+      - name: Login to GitHub Container Registry
+        if: env.HAS_GHCR_TOKEN == 'true'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ env.GHCR_OWNER }}
+          password: ${{ secrets.GHCR_GITHUB_TOKEN }}
+
+      - name: Build nightly image tags list
+        id: test-tags
+        run: |
+          TAGS="${{ env.DOCKER_HUB_USERNAME }}/astrbot:nightly-latest
+          ${{ env.DOCKER_HUB_USERNAME }}/astrbot:nightly-${{ steps.test-meta.outputs.build_date }}-${{ steps.test-meta.outputs.short_sha }}"
+          if [ "${{ env.HAS_GHCR_TOKEN }}" = "true" ]; then
+            TAGS="$TAGS
+          ghcr.io/${{ env.GHCR_OWNER }}/astrbot:nightly-latest
+          ghcr.io/${{ env.GHCR_OWNER }}/astrbot:nightly-${{ steps.test-meta.outputs.build_date }}-${{ steps.test-meta.outputs.short_sha }}"
+          fi
+          echo "tags<<EOF" >> $GITHUB_OUTPUT
+          echo "$TAGS" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Build and Push Nightly Image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.test-tags.outputs.tags }}
+
+      - name: Post build notifications
+        run: echo "Test Docker image has been built and pushed successfully"
+
+  build-release-image:
+    if: github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v'))
+    runs-on: ubuntu-latest
+    env:
+      DOCKER_HUB_USERNAME: ${{ secrets.DOCKER_HUB_USERNAME }}
+      GHCR_OWNER: soulter
+      HAS_GHCR_TOKEN: ${{ secrets.GHCR_GITHUB_TOKEN != '' }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+          fetch-tag: true
+
+      - name: Get latest tag (only on manual trigger)
+        id: get-latest-tag
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          tag=$(git describe --tags --abbrev=0)
+          echo "latest_tag=$tag" >> $GITHUB_OUTPUT
+
+      - name: Checkout to latest tag (only on manual trigger)
+        if: github.event_name == 'workflow_dispatch'
+        run: git checkout ${{ steps.get-latest-tag.outputs.latest_tag }}
+
+      - name: Compute release metadata
+        id: release-meta
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            version="${{ steps.get-latest-tag.outputs.latest_tag }}"
+          else
+            version="${GITHUB_REF#refs/tags/}"
+          fi
+          if [[ "$version" == *"beta"* ]] || [[ "$version" == *"alpha"* ]]; then
+            echo "is_prerelease=true" >> $GITHUB_OUTPUT
+            echo "Version $version marked as pre-release"
+          else
+            echo "is_prerelease=false" >> $GITHUB_OUTPUT
+            echo "Version $version marked as stable"
+          fi
+          echo "version=$version" >> $GITHUB_OUTPUT
+
+      - 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
+
+      - name: Set Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to DockerHub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_HUB_USERNAME }}
+          password: ${{ secrets.DOCKER_HUB_PASSWORD }}
+
+      - name: Login to GitHub Container Registry
+        if: env.HAS_GHCR_TOKEN == 'true'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ env.GHCR_OWNER }}
+          password: ${{ secrets.GHCR_GITHUB_TOKEN }}
+
+      - name: Build and Push Release Image
         uses: docker/build-push-action@v6
         with:
           context: .
           platforms: linux/amd64,linux/arm64
           push: true
           tags: |
-            ${{ secrets.DOCKER_HUB_USERNAME }}/astrbot:latest
+            ${{ steps.release-meta.outputs.is_prerelease == 'false' && format('{0}/astrbot:latest', env.DOCKER_HUB_USERNAME) || '' }}
-            ${{ secrets.DOCKER_HUB_USERNAME }}/astrbot:${{ github.ref_name }}
+            ${{ steps.release-meta.outputs.is_prerelease == 'false' && env.HAS_GHCR_TOKEN == 'true' && format('ghcr.io/{0}/astrbot:latest', env.GHCR_OWNER) || '' }}
+            ${{ format('{0}/astrbot:{1}', env.DOCKER_HUB_USERNAME, steps.release-meta.outputs.version) }}
+            ${{ env.HAS_GHCR_TOKEN == 'true' && format('ghcr.io/{0}/astrbot:{1}', env.GHCR_OWNER, steps.release-meta.outputs.version) || '' }}
 
       - name: Post build notifications
-        run: echo "Docker image has been built and pushed successfully"
+        run: echo "Release Docker image has been built and pushed successfully"
-

.github/workflows/stale.yml

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

.gitignore

@@ -1,32 +1,49 @@
+# Python related
 __pycache__
-botpy.log
+.mypy_cache
-.vscode
 .venv*
-.idea
+.conda/
-data_v2.db
+uv.lock
-data_v3.db
-configs/session
-configs/config.yaml
-**/.DS_Store
-temp
-cmd_config.json
-data
-cookies.json
-logs/
-addons/plugins
 .coverage
 
+# IDE and editors
+.vscode
+.idea
 
+# Logs and temporary files
+botpy.log
+logs/
+temp
+cookies.json
+
+# Data files
+data_v2.db
+data_v3.db
+data
+configs/session
+configs/config.yaml
+cmd_config.json
+
+# Plugins and packages
+addons/plugins
+packages/python_interpreter/workplace
 tests/astrbot_plugin_openai
-chroma
+
+# Dashboard
 dashboard/node_modules/
 dashboard/dist/
-.DS_Store
 package-lock.json
 package.json
+
+# Operating System
+**/.DS_Store
+.DS_Store
+
+# AstrBot specific
+.astrbot
+astrbot.lock
+
+# Other
+chroma
 venv/*
-packages/python_interpreter/workplace
-.venv/*
-.conda/
-.idea
 pytest.ini

.pre-commit-config.yaml

@@ -6,8 +6,20 @@ ci:
   autoupdate_schedule: weekly
   autoupdate_commit_msg: ":balloon: pre-commit autoupdate"
 repos:
-  - repo: https://github.com/astral-sh/ruff-pre-commit
+- repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.11.2
+  # Ruff version.
-    hooks:
+  rev: v0.14.1
-      - id: ruff
+  hooks:
-      - id: ruff-format
+    # Run the linter.
+    - id: ruff-check
+      types_or: [ python, pyi ]
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format
+      types_or: [ python, pyi ]
+      
+- repo: https://github.com/asottile/pyupgrade
+  rev: v3.21.0
+  hooks:
+    - id: pyupgrade
+      args: [--py310-plus]

.python-version

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

Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.10-slim
+FROM python:3.11-slim
 WORKDIR /AstrBot
 
 COPY . /AstrBot/
@@ -11,20 +11,22 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     libssl-dev \
     ca-certificates \
     bash \
+    ffmpeg \
+    curl \
+    gnupg \
+    git \
     && apt-get clean \
-    && rm -rf /var/lib/apt/lists/*
+    && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
 
-RUN python -m pip install uv
+RUN apt-get update && apt-get install -y curl gnupg \
+    && curl -fsSL https://deb.nodesource.com/setup_lts.x | bash - \
+    && apt-get install -y nodejs
+
+RUN python -m pip install uv \
+    && echo "3.11" > .python-version
 RUN uv pip install -r requirements.txt --no-cache-dir --system
-RUN uv pip install socksio uv pyffmpeg pilk --no-cache-dir --system
+RUN uv pip install socksio uv pilk --no-cache-dir --system
 
-# 释出 ffmpeg
+EXPOSE 6185
-RUN python -c "from pyffmpeg import FFmpeg; ff = FFmpeg();"
 
-# add /root/.pyffmpeg/bin/ffmpeg to PATH, inorder to use ffmpeg
+CMD ["python", "main.py"]
-RUN echo 'export PATH=$PATH:/root/.pyffmpeg/bin' >> ~/.bashrc
-
-EXPOSE 6185 
-EXPOSE 6186
-
-CMD [ "python", "main.py" ]

Dockerfile_with_node

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

README.md

@@ -1,72 +1,83 @@
-<p align="center">
+![AstrBot-Logo-Simplified](https://github.com/user-attachments/assets/ffd99b6b-3272-4682-beaa-6fe74250f7d9)
-
-![yjtp](https://github.com/user-attachments/assets/dcc74009-c57e-4b66-9ae3-0a81fc001255)
 
 </p>
 
 <div align="center">
 
-_✨ 易上手的多平台 LLM 聊天机器人及开发框架 ✨_
+<br>
 
+<div>
 <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>
-
+<a href="https://hellogithub.com/repository/AstrBotDevs/AstrBot" target="_blank"><img src="https://api.hellogithub.com/v1/widgets/recommend.svg?rid=d127d50cd5e54c5382328acc3bb25483&claim_uid=ZO9by7qCXgSd6Lp&t=2" alt="Featured｜HelloGitHub" style="width: 250px; height: 54px;" width="250" height="54" /></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)
-<img src="https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge&color=76bad9" alt="python">
-<a href="https://hub.docker.com/r/soulter/astrbot"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/soulter/astrbot.svg?style=for-the-badge&color=76bad9"/></a>
-<a  href="https://qm.qq.com/cgi-bin/qm/qr?k=wtbaNx7EioxeaqS9z7RQWVXPIxg2zYr7&jump_from=webapi&authKey=vlqnv/AV2DbJEvGIcxdlNSpfxVy+8vVqijgreRdnVKOaydpc+YSw4MctmEbr0k5"><img alt="Static Badge" src="https://img.shields.io/badge/QQ群-775869627-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%E6%97%A5%E6%B4%BB%E8%B7%83%E9%87%8F&cacheSeconds=10800&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=7200)
-
-
-<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://github.com/Soulter/AstrBot/issues">问题提交</a>
 </div>
 
-AstrBot 是一个松耦合、异步、支持多消息平台部署、具有易用的插件系统和完善的大语言模型（LLM）接入功能的聊天机器人及开发框架。
+<br>
 
-[![star](https://gitcode.com/Soulter/AstrBot/star/badge.svg?style=for-the-badge)](https://gitcode.com/Soulter/AstrBot)
+<div>
+<img src="https://img.shields.io/github/v/release/AstrBotDevs/AstrBot?style=for-the-badge&color=76bad9" href="https://github.com/AstrBotDevs/AstrBot/releases/latest">
+<img src="https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge&color=76bad9" alt="python">
+<a href="https://hub.docker.com/r/soulter/astrbot"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/soulter/astrbot.svg?style=for-the-badge&color=76bad9"/></a>
+<a href="https://qm.qq.com/cgi-bin/qm/qr?k=wtbaNx7EioxeaqS9z7RQWVXPIxg2zYr7&jump_from=webapi&authKey=vlqnv/AV2DbJEvGIcxdlNSpfxVy+8vVqijgreRdnVKOaydpc+YSw4MctmEbr0k5"><img alt="QQ_community" src="https://img.shields.io/badge/QQ群-775869627-purple?style=for-the-badge&color=76bad9"></a>
+<a href="https://t.me/+hAsD2Ebl5as3NmY1"><img alt="Telegram_community" src="https://img.shields.io/badge/Telegram-AstrBot-purple?style=for-the-badge&color=76bad9"></a>
+<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fplugin-num&query=%24.result&suffix=%E4%B8%AA&style=for-the-badge&label=%E6%8F%92%E4%BB%B6%E5%B8%82%E5%9C%BA&cacheSeconds=3600">
+</div>
 
-<!-- [![codecov](https://img.shields.io/codecov/c/github/soulter/astrbot?style=for-the-badge)](https://codecov.io/gh/Soulter/AstrBot)
+<br>
- -->
 
-## ✨ 近期更新
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_en.md">English</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ja.md">日本語</a> ｜
+<a href="https://astrbot.app/">文档</a> ｜
+<a href="https://blog.astrbot.app/">Blog</a> ｜
+<a href="https://astrbot.featurebase.app/roadmap">路线图</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/issues">问题提交</a>
+</div>
 
-1. AstrBot 现已支持接入 [MCP](https://modelcontextprotocol.io/) 服务器！
+AstrBot 是一个开源的一站式 Agent 聊天机器人平台及开发框架。
 
-## ✨ 主要功能
+## 主要功能
 
-> [!NOTE]
+1. **大模型对话**。支持接入多种大模型服务。支持多模态、工具调用、MCP、原生知识库、人设等功能。
-> 🪧 我们正基于前沿科研成果，设计并实现适用于角色扮演和情感陪伴的长短期记忆模型及情绪控制模型，旨在提升对话的真实性与情感表达能力。敬请期待 `v3.6.0` 版本！
+2. **多消息平台支持**。支持接入 QQ、企业微信、微信公众号、飞书、Telegram、钉钉、Discord、KOOK 等平台。支持速率限制、白名单、百度内容审核。
+3. **Agent**。完善适配的 Agentic 能力。支持多轮工具调用、内置沙盒代码执行器、网页搜索等功能。
+4. **插件扩展**。深度优化的插件机制，支持[开发插件](https://astrbot.app/dev/plugin.html)扩展功能，社区插件生态丰富。
+5. **WebUI**。可视化配置和管理机器人，功能齐全。
 
-1. **大语言模型对话**。支持各种大语言模型，包括 OpenAI API、Google Gemini、Llama、Deepseek、ChatGLM 等，支持接入本地部署的大模型，通过 Ollama、LLMTuner。具有多轮对话、人格情境、多模态能力，支持图片理解、语音转文字（Whisper）。
+## 部署方式 
-2. **多消息平台接入**。支持接入 QQ（OneBot）、QQ 频道、微信（Gewechat）、飞书、Telegram。后续将支持钉钉、Discord、WhatsApp、小爱音响。支持速率限制、白名单、关键词过滤、百度内容审核。
-3. **Agent**。原生支持部分 Agent 能力，如代码执行器、自然语言待办、网页搜索。对接 [Dify 平台](https://dify.ai/)，便捷接入 Dify 智能助手、知识库和 Dify 工作流。
-4. **插件扩展**。深度优化的插件机制，支持[开发插件](https://astrbot.app/dev/plugin.html)扩展功能，极简开发。已支持安装多个插件。
-5. **可视化管理面板**。支持可视化修改配置、插件管理、日志查看等功能，降低配置难度。集成 WebChat，可在面板上与大模型对话。
-6. **高稳定性、高模块化**。基于事件总线和流水线的架构设计，高度模块化，低耦合。
 
-> [!TIP]
+#### Docker 部署(推荐 🥳)
-> WebUI 在线体验 Demo: [https://demo.astrbot.app/](https://demo.astrbot.app/)
-> 
-> 用户名: `astrbot`, 密码: `astrbot`。
 
-## ✨ 使用方式
+推荐使用 Docker / Docker Compose 方式部署 AstrBot。
-
-#### Docker 部署
 
 请参阅官方文档 [使用 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/AstrBotDevs/AstrBot)](https://repl.it/github/AstrBotDevs/AstrBot)
+
 #### Windows 一键安装器部署
 
 请参阅官方文档 [使用 Windows 一键安装器部署 AstrBot](https://astrbot.app/deploy/astrbot/windows.html) 。
 
-#### 宝塔面板部署
-
-请参阅官方文档 [宝塔面板部署](https://astrbot.app/deploy/astrbot/btpanel.html) 。
-
 #### CasaOS 部署
 
 社区贡献的部署方式。
@@ -75,55 +86,106 @@ AstrBot 是一个松耦合、异步、支持多消息平台部署、具有易用
 
 #### 手动部署
 
-推荐使用 `uv`。
+首先安装 uv：
+
+```bash
+pip install uv
+```
+
+通过 Git Clone 安装 AstrBot：
 
 ```bash
 git clone https://github.com/AstrBotDevs/AstrBot && cd AstrBot
-pip install uv
 uv run main.py
 ```
 
 或者请参阅官方文档 [通过源码部署 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
 
-| 平台    | 支持性 | 详情 | 消息类型 |
+### Telegram 群组
-| -------- | ------- | ------- | ------ |
-| QQ(官方机器人接口) | ✔    | 私聊、群聊，QQ 频道私聊、群聊 | 文字、图片 |
-| QQ(OneBot)      | ✔    | 私聊、群聊 | 文字、图片、语音 |
-| 微信(个人号)    | ✔    | 微信个人号私聊、群聊 | 文字、图片、语音 |
-| [Telegram](https://github.com/Soulter/astrbot_plugin_telegram)   | ✔    | 私聊、群聊 | 文字、图片 |
-| [微信(企业微信)](https://github.com/Soulter/astrbot_plugin_wecom)    | ✔    | 私聊 | 文字、图片、语音 |
-| 飞书   | ✔    | 私聊、群聊 | 文字、图片 |
-| 钉钉   | ✔    | 私聊、群聊 | 文字、图片 |
-| 微信对话开放平台 | 🚧    | 计划内 | - |
-| Discord   | 🚧    | 计划内 | - |
-| WhatsApp   | 🚧    | 计划内 | - |
-| 小爱音响   | 🚧    | 计划内 | - |
 
-## ⚡ 提供商支持情况
+<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 群组
-| -------- | ------- | ------- | ------- |
+
-| OpenAI API | ✔    | 文本生成 | 也支持 DeepSeek、Google Gemini、GLM、Kimi、硅基流动、xAI 等兼容 OpenAI API 的服务 |
+<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>
-| Claude API | ✔    | 文本生成 |  |
+
-| Google Gemini API | ✔    | 文本生成 |  |
+## 支持的消息平台
-| Dify | ✔    | LLMOps |  |
+
-| DashScope(阿里云百炼应用) | ✔    | LLMOps |  |
+**官方维护**
-| Ollama | ✔    | 模型加载器 | 本地部署 DeepSeek、Llama 等开源语言模型 |
+
-| LM Studio | ✔    | 模型加载器 | 本地部署 DeepSeek、Llama 等开源语言模型 |
+- QQ (官方平台 & OneBot)
-| LLMTuner | ✔    | 模型加载器 | 本地加载 lora 等微调模型 |
+- Telegram
-| OneAPI | ✔    | LLM 分发系统 |  |
+- 企微应用 & 企微智能机器人
-| Whisper | ✔    | 语音转文本 | 支持 API、本地部署 |
+- 微信客服 & 微信公众号
-| SenseVoice | ✔    | 语音转文本 | 本地部署 |
+- 飞书
-| OpenAI TTS API | ✔    | 文本转语音 |  |
+- 钉钉
-| GSVI | ✔    | 文本转语音 | GPT-Sovits-Inference |
+- Slack
-| Fishaudio | ✔    | 文本转语音 | GPT-Sovits 作者参与的项目 |
+- Discord
-| Edge-TTS | ✔    | 文本转语音 | Edge 浏览器的免费 TTS |
+- Satori
+- Misskey
+- Whatsapp (将支持)
+- LINE (将支持)
+
+**社区维护**
+
+- [KOOK](https://github.com/wuyan1003/astrbot_plugin_kook_adapter)
+- [VoceChat](https://github.com/HikariFroya/astrbot_plugin_vocechat)
+- [Bilibili 私信](https://github.com/Hina-Chat/astrbot_plugin_bilibili_adapter)
+- [wxauto](https://github.com/luosheng520qaq/wxauto-repost-onebotv11)
+
+## 支持的模型服务
+
+**大模型服务**
+
+- OpenAI 及兼容服务
+- Anthropic
+- Google Gemini
+- Moonshot AI
+- 智谱 AI
+- DeepSeek
+- Ollama (本地部署)
+- LM Studio (本地部署)
+- [优云智算](https://www.compshare.cn/?ytag=GPU_YY-gh_astrbot&referral_code=FV7DcGowN4hB5UuXKgpE74)
+- [302.AI](https://share.302.ai/rr1M3l)
+- [小马算力](https://www.tokenpony.cn/3YPyf)
+- [硅基流动](https://docs.siliconflow.cn/cn/usercases/use-siliconcloud-in-astrbot)
+- [PPIO 派欧云](https://ppio.com/user/register?invited_by=AIOONE)
+- ModelScope
+- OneAPI
+
+**LLMOps 平台**
+
+- Dify
+- 阿里云百炼应用
+- Coze
+
+**语音转文本服务**
+
+- OpenAI Whisper
+- SenseVoice
+
+**文本转语音服务**
+
+- OpenAI TTS
+- Gemini TTS
+- GPT-Sovits-Inference
+- GPT-Sovits
+- FishAudio
+- Edge TTS
+- 阿里云百炼 TTS
+- Azure TTS
+- Minimax TTS
+- 火山引擎 TTS
 
 ## ❤️ 贡献
 
@@ -138,40 +200,11 @@ uv run main.py
 AstrBot 使用 `ruff` 进行代码格式化和检查。
 
 ```bash
-git clone https://github.com/Soulter/AstrBot
+git clone https://github.com/AstrBotDevs/AstrBot
 pip install pre-commit
 pre-commit install
 ```
 
-## 🌟 支持
-
-- Star 这个项目！
-- 在[爱发电](https://afdian.com/a/soulter)支持我！
-- 在[微信](https://drive.soulter.top/f/pYfA/d903f4fa49a496fda3f16d2be9e023b5.png)支持我~
-
-## ✨ Demo
-
-<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>
-
 ## ❤️ Special Thanks
 
 特别感谢所有 Contributors 和插件开发者对 AstrBot 的贡献 ❤️
@@ -180,23 +213,21 @@ _✨ WebUI ✨_
   <img src="https://contrib.rocks/image?repo=AstrBotDevs/AstrBot" />
 </a>
 
+此外，本项目的诞生离不开以下开源项目的帮助：
+
+- [NapNeko/NapCatQQ](https://github.com/NapNeko/NapCatQQ) - 伟大的猫猫框架
 
 ## ⭐ Star History
 
-> [!TIP] 
+> [!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)
+[![Star History Chart](https://api.star-history.com/svg?repos=astrbotdevs/astrbot&type=Date)](https://star-history.com/#astrbotdevs/astrbot&Date)
 
 </div>
 
-## Disclaimer
+</details>
-
-1. The project is protected under the `AGPL-v3` opensource license.
-2. The deployment of WeChat (personal account) utilizes [Gewechat](https://github.com/Devo919/Gewechat) service. AstrBot only guarantees connectivity with Gewechat and recommends using a WeChat account that is not frequently used. In the event of account risk control, the author of this project shall not bear any responsibility.
-3. Please ensure compliance with local laws and regulations when using this project.
 
 _私は、高性能ですから!_
-

README_en.md

@@ -1,182 +1,233 @@
-<p align="center">
+![AstrBot-Logo-Simplified](https://github.com/user-attachments/assets/ffd99b6b-3272-4682-beaa-6fe74250f7d9)
-    
-![6e1279651f16d7fdf4727558b72bbaf1](https://github.com/user-attachments/assets/ead4c551-fc3c-48f7-a6f7-afbfdb820512)
 
 </p>
 
 <div align="center">
 
-_✨ Easy-to-use Multi-platform LLM Chatbot & Development Framework ✨_
+<br>
 
+<div>
 <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>
-
+<a href="https://hellogithub.com/repository/AstrBotDevs/AstrBot" target="_blank"><img src="https://api.hellogithub.com/v1/widgets/recommend.svg?rid=d127d50cd5e54c5382328acc3bb25483&claim_uid=ZO9by7qCXgSd6Lp&t=2" alt="Featured｜HelloGitHub" style="width: 250px; height: 54px;" width="250" height="54" /></a>
-[![GitHub release (latest by date)](https://img.shields.io/github/v/release/Soulter/AstrBot)](https://github.com/Soulter/AstrBot/releases/latest)
-<img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="python">
-<a href="https://hub.docker.com/r/soulter/astrbot"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/soulter/astrbot.svg"/></a>
-<a  href="https://qm.qq.com/cgi-bin/qm/qr?k=wtbaNx7EioxeaqS9z7RQWVXPIxg2zYr7&jump_from=webapi&authKey=vlqnv/AV2DbJEvGIcxdlNSpfxVy+8vVqijgreRdnVKOaydpc+YSw4MctmEbr0k5"><img alt="Static Badge" src="https://img.shields.io/badge/QQ群-630166526-purple"></a>
-[![wakatime](https://wakatime.com/badge/user/915e5316-99c6-4563-a483-ef186cf000c9/project/018e705a-a1a7-409a-a849-3013485e6c8e.svg)](https://wakatime.com/badge/user/915e5316-99c6-4563-a483-ef186cf000c9/project/018e705a-a1a7-409a-a849-3013485e6c8e)
-![Dynamic JSON Badge](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fstats&query=v&label=7%E6%97%A5%E6%B6%88%E6%81%AF%E4%B8%8A%E8%A1%8C%E9%87%8F&cacheSeconds=3600)
-[![codecov](https://codecov.io/gh/Soulter/AstrBot/graph/badge.svg?token=FF3P5967B8)](https://codecov.io/gh/Soulter/AstrBot)
-
-<a href="https://astrbot.app/">Documentation</a> ｜
-<a href="https://github.com/Soulter/AstrBot/issues">Issue Tracking</a>
 </div>
 
-AstrBot is a loosely coupled, asynchronous chatbot and development framework that supports multi-platform deployment, featuring an easy-to-use plugin system and comprehensive Large Language Model (LLM) integration capabilities.
+<br>
 
-## ✨ Key Features
+<div>
+<img src="https://img.shields.io/github/v/release/AstrBotDevs/AstrBot?style=for-the-badge&color=76bad9" href="https://github.com/AstrBotDevs/AstrBot/releases/latest">
+<img src="https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge&color=76bad9" alt="python">
+<a href="https://hub.docker.com/r/soulter/astrbot"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/soulter/astrbot.svg?style=for-the-badge&color=76bad9"/></a>
+<a href="https://qm.qq.com/cgi-bin/qm/qr?k=wtbaNx7EioxeaqS9z7RQWVXPIxg2zYr7&jump_from=webapi&authKey=vlqnv/AV2DbJEvGIcxdlNSpfxVy+8vVqijgreRdnVKOaydpc+YSw4MctmEbr0k5"><img alt="QQ_community" src="https://img.shields.io/badge/QQ群-775869627-purple?style=for-the-badge&color=76bad9"></a>
+<a href="https://t.me/+hAsD2Ebl5as3NmY1"><img alt="Telegram_community" src="https://img.shields.io/badge/Telegram-AstrBot-purple?style=for-the-badge&color=76bad9"></a>
+<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fplugin-num&query=%24.result&suffix=%E4%B8%AA&style=for-the-badge&label=%E6%8F%92%E4%BB%B6%E5%B8%82%E5%9C%BA&cacheSeconds=3600">
+</div>
 
-1. **LLM Conversations** - Supports various LLMs including OpenAI API, Google Gemini, Llama, Deepseek, ChatGLM, etc. Enables local model deployment via Ollama/LLMTuner. Features multi-turn dialogues, personality contexts, multimodal capabilities (image understanding), and speech-to-text (Whisper).
+<br>
-2. **Multi-platform Integration** - Supports QQ (OneBot), QQ Channels, WeChat (Gewechat), Feishu, and Telegram. Planned support for DingTalk, Discord, WhatsApp, and Xiaomi Smart Speakers. Includes rate limiting, whitelisting, keyword filtering, and Baidu content moderation.
-3. **Agent Capabilities** - Native support for code execution, natural language TODO lists, web search. Integrates with [Dify Platform](https://dify.ai/) for easy access to Dify assistants/knowledge bases/workflows.
-4. **Plugin System** - Optimized plugin mechanism with minimal development effort. Supports multiple installed plugins.
-5. **Web Dashboard** - Visual configuration management, plugin controls, logging, and WebChat interface for direct LLM interaction.
-6. **High Stability & Modularity** - Event bus and pipeline architecture ensures high modularization and loose coupling.
 
-> [!TIP]
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README.md">中文</a> ｜
-> Dashboard Demo: [https://demo.astrbot.app/](https://demo.astrbot.app/)  
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_ja.md">日本語</a> ｜
-> Username: `astrbot`, Password: `astrbot` (LLM not configured for chat page)
+<a href="https://astrbot.app/">Documentation</a> ｜
+<a href="https://blog.astrbot.app/">Blog</a> ｜
+<a href="https://astrbot.featurebase.app/roadmap">Roadmap</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/issues">Issue Tracker</a>
+</div>
 
-## ✨ Deployment
+AstrBot is an open-source all-in-one Agent chatbot platform and development framework.
 
-#### Docker Deployment
+## Key Features
 
-See docs: [Deploy with Docker](https://astrbot.app/deploy/astrbot/docker.html#docker-deployment)
+1. **LLM Conversations**. Supports integration with various large language model services. Features include multimodal capabilities, tool calling, MCP, native knowledge base, character personas, and more.
+2. **Multi-Platform Support**. Integrates with QQ, WeChat Work, WeChat Official Accounts, Feishu, Telegram, DingTalk, Discord, KOOK, and other platforms. Supports rate limiting, whitelisting, and Baidu content moderation.
+3. **Agent Capabilities**. Fully optimized agentic features including multi-turn tool calling, built-in sandboxed code executor, web search, and more.
+4. **Plugin Extensions**. Deeply optimized plugin mechanism supporting [plugin development](https://astrbot.app/dev/plugin.html) to extend functionality, with a rich community plugin ecosystem.
+5. **Web UI**. Visual configuration and management of your bot with comprehensive features.
 
-#### Windows Installer
+## Deployment Methods
 
-Requires Python (>3.10). See docs: [Windows Installer Guide](https://astrbot.app/deploy/astrbot/windows.html)
+#### Docker Deployment (Recommended 🥳)
 
-#### Replit Deployment
+We recommend deploying AstrBot using Docker or Docker Compose.
 
-[![Run on Repl.it](https://repl.it/badge/github/Soulter/AstrBot)](https://repl.it/github/Soulter/AstrBot)
+Please refer to the official documentation: [Deploy AstrBot with Docker](https://astrbot.app/deploy/astrbot/docker.html#%E4%BD%BF%E7%94%A8-docker-%E9%83%A8%E7%BD%B2-astrbot).
+
+#### BT-Panel Deployment
+
+AstrBot has partnered with BT-Panel and is now available in their marketplace.
+
+Please refer to the official documentation: [BT-Panel Deployment](https://astrbot.app/deploy/astrbot/btpanel.html).
+
+#### 1Panel Deployment
+
+AstrBot has been officially listed on the 1Panel marketplace.
+
+Please refer to the official documentation: [1Panel Deployment](https://astrbot.app/deploy/astrbot/1panel.html).
+
+#### Deploy on RainYun
+
+AstrBot has been officially listed on RainYun's cloud application platform with one-click deployment.
+
+[![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)
+
+#### Deploy on Replit
+
+Community-contributed deployment method.
+
+[![Run on Repl.it](https://repl.it/badge/github/AstrBotDevs/AstrBot)](https://repl.it/github/AstrBotDevs/AstrBot)
+
+#### Windows One-Click Installer
+
+Please refer to the official documentation: [Deploy AstrBot with Windows One-Click Installer](https://astrbot.app/deploy/astrbot/windows.html).
 
 #### CasaOS Deployment
 
-Community-contributed method.  
+Community-contributed deployment method.
-See docs: [CasaOS Deployment](https://astrbot.app/deploy/astrbot/casaos.html)
+
+Please refer to the official documentation: [CasaOS Deployment](https://astrbot.app/deploy/astrbot/casaos.html).
 
 #### Manual Deployment
 
-See docs: [Source Code Deployment](https://astrbot.app/deploy/astrbot/cli.html)
+First, install uv:
 
-## ⚡ Platform Support
+```bash
+pip install uv
+```
 
-| Platform                                                       | Status | Details             | Message Types       |
+Install AstrBot via Git Clone:
-| -------------------------------------------------------------- | ------ | ------------------- | ------------------- |
-| QQ (Official Bot)                                              | ✔      | Private/Group chats | Text, Images        |
-| QQ (OneBot)                                                    | ✔      | Private/Group chats | Text, Images, Voice |
-| WeChat (Personal)                                              | ✔      | Private/Group chats | Text, Images, Voice |
-| [Telegram](https://github.com/Soulter/astrbot_plugin_telegram) | ✔      | Private/Group chats | Text, Images        |
-| [WeChat Work](https://github.com/Soulter/astrbot_plugin_wecom) | ✔      | Private chats       | Text, Images, Voice |
-| Feishu                                                         | ✔      | Group chats         | Text, Images        |
-| WeChat Open Platform                                           | 🚧      | Planned             | -                   |
-| Discord                                                        | 🚧      | Planned             | -                   |
-| WhatsApp                                                       | 🚧      | Planned             | -                   |
-| Xiaomi Speakers                                                | 🚧      | Planned             | -                   |
 
-## Provider Support Status
+```bash
+git clone https://github.com/AstrBotDevs/AstrBot && cd AstrBot
+uv run main.py
+```
 
-| Name                      | Support | Type                   | Notes                                                                 |
+Or refer to the official documentation: [Deploy AstrBot from Source](https://astrbot.app/deploy/astrbot/cli.html).
-|---------------------------|---------|------------------------|-----------------------------------------------------------------------|
-| OpenAI API                | ✔       | Text Generation        | Supports all OpenAI API-compatible services including DeepSeek, Google Gemini, GLM, Moonshot, Alibaba Cloud Bailian, Silicon Flow, xAI, etc. |
-| Claude API                | ✔       | Text Generation        |                                                                       |
-| Google Gemini API         | ✔       | Text Generation        |                                                                       |
-| Dify                      | ✔       | LLMOps                 |                                                                       |
-| DashScope (Alibaba Cloud) | ✔       | LLMOps                 |                                                                       |
-| Ollama                    | ✔       | Model Loader           | Local deployment for open-source LLMs (DeepSeek, Llama, etc.)         |
-| LM Studio                 | ✔       | Model Loader           | Local deployment for open-source LLMs (DeepSeek, Llama, etc.)         |
-| LLMTuner                  | ✔       | Model Loader           | Local loading of fine-tuned models (e.g. LoRA)                        |
-| OneAPI                    | ✔       | LLM Distribution       |                                                                       |
-| Whisper                   | ✔       | Speech-to-Text         | Supports API and local deployment                                    |
-| SenseVoice                | ✔       | Speech-to-Text         | Local deployment                                                     |
-| OpenAI TTS API            | ✔       | Text-to-Speech         |                                                                       |
-| Fishaudio                 | ✔       | Text-to-Speech         | Project involving GPT-Sovits author                                  |
 
-# 🦌 Roadmap
+## 🌍 Community
 
-> [!TIP]
+### QQ Groups
-> Suggestions welcome via Issues <3
 
-- [ ] Ensure feature parity across all platform adapters
+- Group 1: 322154837
-- [ ] Optimize plugin APIs
+- Group 3: 630166526
-- [ ] Add default TTS services (e.g., GPT-Sovits)
+- Group 5: 822130018
-- [ ] Enhance chat features with persistent memory
+- Group 6: 753075035
-- [ ] i18n Planning
+- Developer Group: 975206796
 
-## ❤️ Contributions
+### Telegram Group
 
-All Issues/PRs welcome! Simply submit your changes to this project :)
+<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>
 
-For major features, please discuss via Issues first.
+### Discord Server
 
-## 🌟 Support
+<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>
 
-- Star this project!
+## Supported Messaging Platforms
-- Support via [Afdian](https://afdian.com/a/soulter)
-- WeChat support: [QR Code](https://drive.soulter.top/f/pYfA/d903f4fa49a496fda3f16d2be9e023b5.png)
 
-## ✨ Demos
+**Officially Maintained**
 
-> [!NOTE]
+- QQ (Official Platform & OneBot)
-> Code executor file I/O currently tested with Napcat(QQ)/Lagrange(QQ)
+- Telegram
+- WeChat Work Application & WeChat Work Intelligent Bot
+- WeChat Customer Service & WeChat Official Accounts
+- Feishu (Lark)
+- DingTalk
+- Slack
+- Discord
+- Satori
+- Misskey
+- WhatsApp (Coming Soon)
+- LINE (Coming Soon)
 
-<div align='center'>
+**Community Maintained**
 
-<img src="https://github.com/user-attachments/assets/4ee688d9-467d-45c8-99d6-368f9a8a92d8" width="600">
+- [KOOK](https://github.com/wuyan1003/astrbot_plugin_kook_adapter)
+- [VoceChat](https://github.com/HikariFroya/astrbot_plugin_vocechat)
+- [Bilibili Direct Messages](https://github.com/Hina-Chat/astrbot_plugin_bilibili_adapter)
+- [wxauto](https://github.com/luosheng520qaq/wxauto-repost-onebotv11)
 
-_✨ Docker-based Sandboxed Code Executor (Beta) ✨_
+## Supported Model Services
 
-<img src="https://github.com/user-attachments/assets/0378f407-6079-4f64-ae4c-e97ab20611d2" height=500>
+**LLM Services**
 
-_✨ Multimodal Input, Web Search, Text-to-Image ✨_
+- OpenAI and Compatible Services
+- Anthropic
+- Google Gemini
+- Moonshot AI
+- Zhipu AI
+- DeepSeek
+- Ollama (Self-hosted)
+- LM Studio (Self-hosted)
+- [CompShare](https://www.compshare.cn/?ytag=GPU_YY-gh_astrbot&referral_code=FV7DcGowN4hB5UuXKgpE74)
+- [302.AI](https://share.302.ai/rr1M3l)
+- [TokenPony](https://www.tokenpony.cn/3YPyf)
+- [SiliconFlow](https://docs.siliconflow.cn/cn/usecases/use-siliconcloud-in-astrbot)
+- [PPIO Cloud](https://ppio.com/user/register?invited_by=AIOONE)
+- ModelScope
+- OneAPI
 
-<img src="https://github.com/user-attachments/assets/8ec12797-e70f-460a-959e-48eca39ca2bb" height=100>
+**LLMOps Platforms**
 
-_✨ Natural Language TODO Lists ✨_
+- Dify
+- Alibaba Cloud Bailian Applications
+- Coze
 
-<img src="https://github.com/user-attachments/assets/e137a9e1-340a-4bf2-bb2b-771132780735" height=150>
+**Speech-to-Text Services**
-<img src="https://github.com/user-attachments/assets/480f5e82-cf6a-4955-a869-0d73137aa6e1" height=150>
 
-_✨ Plugin System Showcase ✨_
+- OpenAI Whisper
+- SenseVoice
 
-<img src="https://github.com/user-attachments/assets/592a8630-14c7-4e06-b496-9c0386e4f36c" width=600>
+**Text-to-Speech Services**
 
-_✨ Web Dashboard ✨_
+- OpenAI TTS
+- Gemini TTS
+- GPT-Sovits-Inference
+- GPT-Sovits
+- FishAudio
+- Edge TTS
+- Alibaba Cloud Bailian TTS
+- Azure TTS
+- Minimax TTS
+- Volcano Engine TTS
 
-![webchat](https://drive.soulter.top/f/vlsA/ezgif-5-fb044b2542.gif)
+## ❤️ Contributing
 
-_✨ Built-in Web Chat Interface ✨_
+Issues and Pull Requests are always welcome! Feel free to submit your changes to this project :)
 
-</div>
+### How to Contribute
+
+You can contribute by reviewing issues or helping with pull request reviews. Any issues or PRs are welcome to encourage community participation. Of course, these are just suggestions—you can contribute in any way you like. For adding new features, please discuss through an Issue first.
+
+### Development Environment
+
+AstrBot uses `ruff` for code formatting and linting.
+
+```bash
+git clone https://github.com/AstrBotDevs/AstrBot
+pip install pre-commit
+pre-commit install
+```
+
+## ❤️ Special Thanks
+
+Special thanks to all Contributors and plugin developers for their contributions to AstrBot ❤️
+
+<a href="https://github.com/AstrBotDevs/AstrBot/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=AstrBotDevs/AstrBot" />
+</a>
+
+Additionally, the birth of this project would not have been possible without the help of the following open-source projects:
+
+- [NapNeko/NapCatQQ](https://github.com/NapNeko/NapCatQQ) - The amazing cat framework
 
 ## ⭐ Star History
 
-> [!TIP] 
+> [!TIP]
-> If this project helps you, please give it a star <3
+> If this project has helped you in your life or work, or if you're interested in its future development, please give the project a Star. It's the driving force behind maintaining this open-source project <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)
+[![Star History Chart](https://api.star-history.com/svg?repos=astrbotdevs/astrbot&type=Date)](https://star-history.com/#astrbotdevs/astrbot&Date)
 
 </div>
 
-## Disclaimer
+</details>
-
-1. Licensed under `AGPL-v3`.
-2. WeChat integration uses [Gewechat](https://github.com/Devo919/Gewechat). Use at your own risk with non-critical accounts.
-3. Users must comply with local laws and regulations.
-
-<!-- ## ✨ ATRI [Beta]
-
-Available as plugin: [astrbot_plugin_atri](https://github.com/Soulter/astrbot_plugin_atri)
-
-1. Qwen1.5-7B-Chat Lora model fine-tuned with ATRI character data
-2. Long-term memory
-3. Meme understanding & responses
-4. TTS integration
-    -->
-
 
 _私は、高性能ですから!_
-

README_ja.md

@@ -1,170 +1,233 @@
-<p align="center">
+![AstrBot-Logo-Simplified](https://github.com/user-attachments/assets/ffd99b6b-3272-4682-beaa-6fe74250f7d9)
-    
-![6e1279651f16d7fdf4727558b72bbaf1](https://github.com/user-attachments/assets/ead4c551-fc3c-48f7-a6f7-afbfdb820512)
 
 </p>
 
 <div align="center">
 
-_✨ 簡単に使えるマルチプラットフォーム LLM チャットボットおよび開発フレームワーク ✨_
+<br>
 
+<div>
 <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>
-
+<a href="https://hellogithub.com/repository/AstrBotDevs/AstrBot" target="_blank"><img src="https://api.hellogithub.com/v1/widgets/recommend.svg?rid=d127d50cd5e54c5382328acc3bb25483&claim_uid=ZO9by7qCXgSd6Lp&t=2" alt="Featured｜HelloGitHub" style="width: 250px; height: 54px;" width="250" height="54" /></a>
-[![GitHub release (latest by date)](https://img.shields.io/github/v/release/Soulter/AstrBot)](https://github.com/Soulter/AstrBot/releases/latest)
-<img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="python">
-<a href="https://hub.docker.com/r/soulter/astrbot"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/soulter/astrbot.svg"/></a>
-<img alt="Static Badge" src="https://img.shields.io/badge/QQ群-630166526-purple">
-[![wakatime](https://wakatime.com/badge/user/915e5316-99c6-4563-a483-ef186cf000c9/project/018e705a-a1a7-409a-a849-3013485e6c8e.svg)](https://wakatime.com/badge/user/915e5316-99c6-4563-a483-ef186cf000c9/project/018e705a-a1a7-409a-a849-3013485e6c8e)
-![Dynamic JSON Badge](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fstats&query=v&label=7%E6%97%A5%E6%B6%88%E6%81%AF%E4%B8%8A%E8%A1%8C%E9%87%8F&cacheSeconds=3600)
-[![codecov](https://codecov.io/gh/Soulter/AstrBot/graph/badge.svg?token=FF3P5967B8)](https://codecov.io/gh/Soulter/AstrBot)
-
-<a href="https://astrbot.app/">ドキュメントを見る</a> ｜
-<a href="https://github.com/Soulter/AstrBot/issues">問題を報告する</a>
 </div>
 
-AstrBot は、疎結合、非同期、複数のメッセージプラットフォームに対応したデプロイ、使いやすいプラグインシステム、および包括的な大規模言語モデル（LLM）接続機能を備えたチャットボットおよび開発フレームワークです。
+<br>
 
-## ✨ 主な機能
+<div>
+<img src="https://img.shields.io/github/v/release/AstrBotDevs/AstrBot?style=for-the-badge&color=76bad9" href="https://github.com/AstrBotDevs/AstrBot/releases/latest">
+<img src="https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge&color=76bad9" alt="python">
+<a href="https://hub.docker.com/r/soulter/astrbot"><img alt="Docker pull" src="https://img.shields.io/docker/pulls/soulter/astrbot.svg?style=for-the-badge&color=76bad9"/></a>
+<a href="https://qm.qq.com/cgi-bin/qm/qr?k=wtbaNx7EioxeaqS9z7RQWVXPIxg2zYr7&jump_from=webapi&authKey=vlqnv/AV2DbJEvGIcxdlNSpfxVy+8vVqijgreRdnVKOaydpc+YSw4MctmEbr0k5"><img alt="QQ_community" src="https://img.shields.io/badge/QQ群-775869627-purple?style=for-the-badge&color=76bad9"></a>
+<a href="https://t.me/+hAsD2Ebl5as3NmY1"><img alt="Telegram_community" src="https://img.shields.io/badge/Telegram-AstrBot-purple?style=for-the-badge&color=76bad9"></a>
+<img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.soulter.top%2Fastrbot%2Fplugin-num&query=%24.result&suffix=%E4%B8%AA&style=for-the-badge&label=%E6%8F%92%E4%BB%B6%E5%B8%82%E5%9C%BA&cacheSeconds=3600">
+</div>
 
-1. **大規模言語モデルの対話**。OpenAI API、Google Gemini、Llama、Deepseek、ChatGLM など、さまざまな大規模言語モデルをサポートし、Ollama、LLMTuner を介してローカルにデプロイされた大規模モデルをサポートします。多輪対話、人格シナリオ、多モーダル機能を備え、画像理解、音声からテキストへの変換（Whisper）をサポートします。
+<br>
-2. **複数のメッセージプラットフォームの接続**。QQ（OneBot）、QQ チャンネル、WeChat（Gewechat）、Feishu、Telegram への接続をサポートします。今後、DingTalk、Discord、WhatsApp、Xiaoai 音響をサポートする予定です。レート制限、ホワイトリスト、キーワードフィルタリング、Baidu コンテンツ監査をサポートします。
-3. **エージェント**。一部のエージェント機能をネイティブにサポートし、コードエグゼキューター、自然言語タスク、ウェブ検索などを提供します。[Dify プラットフォーム](https://dify.ai/)と連携し、Dify スマートアシスタント、ナレッジベース、Dify ワークフローを簡単に接続できます。
-4. **プラグインの拡張**。深く最適化されたプラグインメカニズムを備え、[プラグインの開発](https://astrbot.app/dev/plugin.html)をサポートし、機能を拡張できます。複数のプラグインのインストールをサポートします。
-5. **ビジュアル管理パネル**。設定の視覚的な変更、プラグイン管理、ログの表示などをサポートし、設定の難易度を低減します。WebChat を統合し、パネル上で大規模モデルと対話できます。
-6. **高い安定性と高いモジュール性**。イベントバスとパイプラインに基づくアーキテクチャ設計により、高度にモジュール化され、低結合です。
 
-> [!TIP]
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README.md">中文</a> ｜
-> 管理パネルのオンラインデモを体験する: [https://demo.astrbot.app/](https://demo.astrbot.app/)
+<a href="https://github.com/AstrBotDevs/AstrBot/blob/master/README_en.md">English</a> ｜
-> 
+<a href="https://astrbot.app/">ドキュメント</a> ｜
-> ユーザー名: `astrbot`, パスワード: `astrbot`。LLM が設定されていないため、チャットページで大規模モデルを使用することはできません。（デモのログインパスワードを変更しないでください 😭）
+<a href="https://blog.astrbot.app/">Blog</a> ｜
+<a href="https://astrbot.featurebase.app/roadmap">ロードマップ</a> ｜
+<a href="https://github.com/AstrBotDevs/AstrBot/issues">Issue</a>
+</div>
 
-## ✨ 使用方法
+AstrBot は、オープンソースのオールインワン Agent チャットボットプラットフォーム及び開発フレームワークです。
 
-#### Docker デプロイ
+## 主な機能
 
-公式ドキュメント [Docker を使用して AstrBot をデプロイする](https://astrbot.app/deploy/astrbot/docker.html#%E4%BD%BF%E7%94%A8-docker-%E9%83%A8%E7%BD%B2-astrbot) を参照してください。
+1. **大規模言語モデル対話**。多様な大規模言語モデルサービスとの統合をサポート。マルチモーダル、ツール呼び出し、MCP、ネイティブナレッジベース、キャラクター設定などの機能を搭載。
+2. **マルチメッセージプラットフォームサポート**。QQ、WeChat Work、WeChat公式アカウント、Feishu、Telegram、DingTalk、Discord、KOOK などのプラットフォームと統合可能。レート制限、ホワイトリスト、Baidu コンテンツ審査をサポート。
+3. **Agent**。完全に最適化された Agentic 機能。マルチターンツール呼び出し、内蔵サンドボックスコード実行環境、Web 検索などの機能をサポート。
+4. **プラグイン拡張**。深く最適化されたプラグインメカニズムで、[プラグイン開発](https://astrbot.app/dev/plugin.html)による機能拡張をサポート。豊富なコミュニティプラグインエコシステム。
+5. **WebUI**。ビジュアル設定とボット管理、充実した機能。
 
-#### Windows ワンクリックインストーラーのデプロイ
+## デプロイ方法
 
-コンピュータに Python（>3.10）がインストールされている必要があります。公式ドキュメント [Windows ワンクリックインストーラーを使用して AstrBot をデプロイする](https://astrbot.app/deploy/astrbot/windows.html) を参照してください。
+#### Docker デプロイ（推奨 🥳）
 
-#### Replit デプロイ
+Docker / Docker Compose を使用した AstrBot のデプロイを推奨します。
 
-[![Run on Repl.it](https://repl.it/badge/github/Soulter/AstrBot)](https://repl.it/github/Soulter/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/AstrBotDevs/AstrBot)](https://repl.it/github/AstrBotDevs/AstrBot)
+
+#### Windows ワンクリックインストーラーデプロイ
+
+公式ドキュメント [Windows ワンクリックインストーラーを使用した AstrBot のデプロイ](https://astrbot.app/deploy/astrbot/windows.html) をご参照ください。
 
 #### CasaOS デプロイ
 
-コミュニティが提供するデプロイ方法です。
+コミュニティ貢献によるデプロイ方法。
 
-公式ドキュメント [ソースコードを使用して AstrBot をデプロイする](https://astrbot.app/deploy/astrbot/casaos.html) を参照してください。
+公式ドキュメント [CasaOS デプロイ](https://astrbot.app/deploy/astrbot/casaos.html) をご参照ください。
 
 #### 手動デプロイ
 
-公式ドキュメント [ソースコードを使用して AstrBot をデプロイする](https://astrbot.app/deploy/astrbot/cli.html) を参照してください。
+まず uv をインストールします:
 
-## ⚡ メッセージプラットフォームのサポート状況
+```bash
+pip install uv
+```
 
-| プラットフォーム    | サポート状況 | 詳細 | メッセージタイプ |
+Git Clone で AstrBot をインストール:
-| -------- | ------- | ------- | ------ |
-| QQ(公式ロボットインターフェース) | ✔    | プライベートチャット、グループチャット、QQ チャンネルプライベートチャット、グループチャット | テキスト、画像 |
-| QQ(OneBot)      | ✔    | プライベートチャット、グループチャット | テキスト、画像、音声 |
-| WeChat(個人アカウント)    | ✔    | WeChat 個人アカウントのプライベートチャット、グループチャット | テキスト、画像、音声 |
-| [Telegram](https://github.com/Soulter/astrbot_plugin_telegram)   | ✔    | プライベートチャット、グループチャット | テキスト、画像 |
-| [WeChat(企業 WeChat)](https://github.com/Soulter/astrbot_plugin_wecom)    | ✔    | プライベートチャット | テキスト、画像、音声 |
-| Feishu   | ✔    | グループチャット | テキスト、画像 |
-| WeChat 対話オープンプラットフォーム | 🚧    | 計画中 | - |
-| Discord   | 🚧    | 計画中 | - |
-| WhatsApp   | 🚧    | 計画中 | - |
-| Xiaoai 音響   | 🚧    | 計画中 | - |
 
-# 🦌 今後のロードマップ
+```bash
+git clone https://github.com/AstrBotDevs/AstrBot && cd AstrBot
+uv run main.py
+```
 
-> [!TIP]
+または、公式ドキュメント [ソースコードから AstrBot をデプロイ](https://astrbot.app/deploy/astrbot/cli.html) をご参照ください。
-> Issue でさらに多くの提案を歓迎します <3
 
-- [ ] 現在のすべてのプラットフォームアダプターの機能の一貫性を確保し、改善する
+## 🌍 コミュニティ
-- [ ] プラグインインターフェースの最適化
-- [ ] GPT-Sovits などの TTS サービスをデフォルトでサポート
-- [ ] "チャット強化" 部分を完成させ、永続的な記憶をサポート
-- [ ] i18n の計画
 
-## ❤️ 貢献
+### QQ グループ
 
-Issue や Pull Request を歓迎します！このプロジェクトに変更を加えるだけです :)
+- 1群:322154837
+- 3群:630166526
+- 5群:822130018
+- 6群:753075035
+- 開発者群:975206796
 
-新機能の追加については、まず Issue で議論してください。
+### 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>
 
-- このプロジェクトに Star を付けてください！
+### Discord サーバー
-- [愛発電](https://afdian.com/a/soulter)で私をサポートしてください！
-- [WeChat](https://drive.soulter.top/f/pYfA/d903f4fa49a496fda3f16d2be9e023b5.png)で私をサポートしてください~
 
-## ✨ デモ
+<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>
 
-> [!NOTE]
+## サポートされているメッセージプラットフォーム
-> コードエグゼキューターのファイル入力/出力は現在 Napcat(QQ)、Lagrange(QQ) でのみテストされています
 
-<div align='center'>
+**公式メンテナンス**
 
-<img src="https://github.com/user-attachments/assets/4ee688d9-467d-45c8-99d6-368f9a8a92d8" width="600">
+- QQ (公式プラットフォーム & OneBot)
+- Telegram
+- WeChat Work アプリケーション & WeChat Work インテリジェントボット
+- WeChat カスタマーサービス & WeChat 公式アカウント
+- Feishu (Lark)
+- DingTalk
+- Slack
+- Discord
+- Satori
+- Misskey
+- WhatsApp (近日対応予定)
+- LINE (近日対応予定)
 
-_✨ Docker ベースのサンドボックス化されたコードエグゼキューター（ベータテスト中）✨_
+**コミュニティメンテナンス**
 
-<img src="https://github.com/user-attachments/assets/0378f407-6079-4f64-ae4c-e97ab20611d2" height=500>
+- [KOOK](https://github.com/wuyan1003/astrbot_plugin_kook_adapter)
+- [VoceChat](https://github.com/HikariFroya/astrbot_plugin_vocechat)
+- [Bilibili ダイレクトメッセージ](https://github.com/Hina-Chat/astrbot_plugin_bilibili_adapter)
+- [wxauto](https://github.com/luosheng520qaq/wxauto-repost-onebotv11)
 
-_✨ 多モーダル、ウェブ検索、長文の画像変換（設定可能）✨_
+## サポートされているモデルサービス
 
-<img src="https://github.com/user-attachments/assets/8ec12797-e70f-460a-959e-48eca39ca2bb" height=100>
+**大規模言語モデルサービス**
 
-_✨ 自然言語タスク ✨_
+- OpenAI および互換サービス
+- Anthropic
+- Google Gemini
+- Moonshot AI
+- 智谱 AI
+- DeepSeek
+- Ollama (セルフホスト)
+- LM Studio (セルフホスト)
+- [優云智算](https://www.compshare.cn/?ytag=GPU_YY-gh_astrbot&referral_code=FV7DcGowN4hB5UuXKgpE74)
+- [302.AI](https://share.302.ai/rr1M3l)
+- [小馬算力](https://www.tokenpony.cn/3YPyf)
+- [硅基流動](https://docs.siliconflow.cn/cn/usercases/use-siliconcloud-in-astrbot)
+- [PPIO 派欧云](https://ppio.com/user/register?invited_by=AIOONE)
+- ModelScope
+- OneAPI
 
-<img src="https://github.com/user-attachments/assets/e137a9e1-340a-4bf2-bb2b-771132780735" height=150>
+**LLMOps プラットフォーム**
-<img src="https://github.com/user-attachments/assets/480f5e82-cf6a-4955-a869-0d73137aa6e1" height=150>
 
-_✨ プラグインシステム - 一部のプラグインの展示 ✨_
+- Dify
+- Alibaba Cloud 百炼アプリケーション
+- Coze
 
-<img src="https://github.com/user-attachments/assets/592a8630-14c7-4e06-b496-9c0386e4f36c" width="600">
+**音声認識サービス**
 
-_✨ 管理パネル ✨_
+- OpenAI Whisper
+- SenseVoice
 
-![webchat](https://drive.soulter.top/f/vlsA/ezgif-5-fb044b2542.gif)
+**音声合成サービス**
 
-_✨ 内蔵 Web Chat、オンラインでボットと対話 ✨_
+- OpenAI TTS
+- Gemini TTS
+- GPT-Sovits-Inference
+- GPT-Sovits
+- FishAudio
+- Edge TTS
+- Alibaba Cloud 百炼 TTS
+- Azure TTS
+- Minimax TTS
+- Volcano Engine TTS
 
-</div>
+## ❤️ コントリビューション
+
+Issue や Pull Request は大歓迎です!このプロジェクトに変更を送信してください :)
+
+### コントリビュート方法
+
+Issue を確認したり、PR(プルリクエスト)のレビューを手伝うことで貢献できます。どんな Issue や PR への参加も歓迎され、コミュニティ貢献を促進します。もちろん、これらは提案に過ぎず、どんな方法でも貢献できます。新機能の追加については、まず Issue で議論してください。
+
+### 開発環境
+
+AstrBot はコードのフォーマットとチェックに `ruff` を使用しています。
+
+```bash
+git clone https://github.com/AstrBotDevs/AstrBot
+pip install pre-commit
+pre-commit install
+```
+
+## ❤️ Special Thanks
+
+AstrBot への貢献をしていただいたすべてのコントリビューターとプラグイン開発者に特別な感謝を ❤️
+
+<a href="https://github.com/AstrBotDevs/AstrBot/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=AstrBotDevs/AstrBot" />
+</a>
+
+また、このプロジェクトの誕生は以下のオープンソースプロジェクトの助けなしには実現できませんでした:
+
+- [NapNeko/NapCatQQ](https://github.com/NapNeko/NapCatQQ) - 素晴らしい猫猫フレームワーク
 
 ## ⭐ Star History
 
-> [!TIP] 
+> [!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)
+[![Star History Chart](https://api.star-history.com/svg?repos=astrbotdevs/astrbot&type=Date)](https://star-history.com/#astrbotdevs/astrbot&Date)
 
 </div>
 
-## スポンサー
+</details>
-
-[<img src="https://api.gitsponsors.com/api/badge/img?id=575865240" height="20">](https://api.gitsponsors.com/api/badge/link?p=XEpbdGxlitw/RbcwiTX93UMzNK/jgDYC8NiSzamIPMoKvG2lBFmyXhSS/b0hFoWlBBMX2L5X5CxTDsUdyvcIEHTOfnkXz47UNOZvMwyt5CzbYpq0SEzsSV1OJF1cCo90qC/ZyYKYOWedal3MhZ3ikw==)
-
-## 免責事項
-
-1. このプロジェクトは `AGPL-v3` オープンソースライセンスの下で保護されています。
-2. WeChat（個人アカウント）のデプロイメントには [Gewechat](https://github.com/Devo919/Gewechat) サービスを利用しています。AstrBot は Gewechat との接続を保証するだけであり、アカウントのリスク管理に関しては、このプロジェクトの著者は一切の責任を負いません。
-3. このプロジェクトを使用する際は、現地の法律および規制を遵守してください。
-
-<!-- ## ✨ ATRI [ベータテスト]
-
-この機能はプラグインとしてロードされます。プラグインリポジトリのアドレス：[astrbot_plugin_atri](https://github.com/Soulter/astrbot_plugin_atri)
-
-1. 《ATRI ~ My Dear Moments》の主人公 ATRI のキャラクターセリフを微調整データセットとして使用した `Qwen1.5-7B-Chat Lora` 微調整モデル。
-2. 長期記憶
-3. ミームの理解と返信
-4. TTS
-    -->
-
 
 _私は、高性能ですから!_
-

astrbot/api/__init__.py

@@ -1,7 +1,19 @@
-from astrbot.core.config.astrbot_config import AstrBotConfig
 from astrbot import logger
-from astrbot.core import html_renderer
+from astrbot.core import html_renderer, sp
-from astrbot.core import sp
+from astrbot.core.agent.tool import FunctionTool, ToolSet
+from astrbot.core.agent.tool_executor import BaseFunctionToolExecutor
+from astrbot.core.config.astrbot_config import AstrBotConfig
+from astrbot.core.star.register import register_agent as agent
 from astrbot.core.star.register import register_llm_tool as llm_tool
 
-__all__ = ["AstrBotConfig", "logger", "html_renderer", "llm_tool", "sp"]
+__all__ = [
+    "AstrBotConfig",
+    "BaseFunctionToolExecutor",
+    "FunctionTool",
+    "ToolSet",
+    "agent",
+    "html_renderer",
+    "llm_tool",
+    "logger",
+    "sp",
+]

astrbot/api/all.py

@@ -36,7 +36,8 @@ from astrbot.core.star.config import *
 
 
 # provider
-from astrbot.core.provider import Provider, Personality, ProviderMetaData
+from astrbot.core.provider import Provider, ProviderMetaData
+from astrbot.core.db.po import Personality
 
 # platform
 from astrbot.core.platform import (

astrbot/api/event/__init__.py

@@ -1,18 +1,17 @@
 from astrbot.core.message.message_event_result import (
-    MessageEventResult,
-    MessageChain,
     CommandResult,
     EventResultType,
+    MessageChain,
+    MessageEventResult,
     ResultContentType,
 )
-
 from astrbot.core.platform import AstrMessageEvent
 
 __all__ = [
-    "MessageEventResult",
+    "AstrMessageEvent",
-    "MessageChain",
     "CommandResult",
     "EventResultType",
-    "AstrMessageEvent",
+    "MessageChain",
+    "MessageEventResult",
     "ResultContentType",
 ]

astrbot/api/event/filter/__init__.py

@@ -1,49 +1,52 @@
-from astrbot.core.star.register import (
-    register_command as command,
-    register_command_group as command_group,
-    register_event_message_type as event_message_type,
-    register_regex as regex,
-    register_platform_adapter_type as platform_adapter_type,
-    register_permission_type as permission_type,
-    register_custom_filter as custom_filter,
-    register_on_astrbot_loaded as on_astrbot_loaded,
-    register_on_llm_request as on_llm_request,
-    register_on_llm_response as on_llm_response,
-    register_llm_tool as llm_tool,
-    register_on_decorating_result as on_decorating_result,
-    register_after_message_sent as after_message_sent,
-)
-
-from astrbot.core.star.filter.event_message_type import (
-    EventMessageTypeFilter,
-    EventMessageType,
-)
-from astrbot.core.star.filter.platform_adapter_type import (
-    PlatformAdapterTypeFilter,
-    PlatformAdapterType,
-)
-from astrbot.core.star.filter.permission import PermissionTypeFilter, PermissionType
 from astrbot.core.star.filter.custom_filter import CustomFilter
+from astrbot.core.star.filter.event_message_type import (
+    EventMessageType,
+    EventMessageTypeFilter,
+)
+from astrbot.core.star.filter.permission import PermissionType, PermissionTypeFilter
+from astrbot.core.star.filter.platform_adapter_type import (
+    PlatformAdapterType,
+    PlatformAdapterTypeFilter,
+)
+from astrbot.core.star.register import register_after_message_sent as after_message_sent
+from astrbot.core.star.register import register_command as command
+from astrbot.core.star.register import register_command_group as command_group
+from astrbot.core.star.register import register_custom_filter as custom_filter
+from astrbot.core.star.register import register_event_message_type as event_message_type
+from astrbot.core.star.register import register_llm_tool as llm_tool
+from astrbot.core.star.register import register_on_astrbot_loaded as on_astrbot_loaded
+from astrbot.core.star.register import (
+    register_on_decorating_result as on_decorating_result,
+)
+from astrbot.core.star.register import register_on_llm_request as on_llm_request
+from astrbot.core.star.register import register_on_llm_response as on_llm_response
+from astrbot.core.star.register import register_on_platform_loaded as on_platform_loaded
+from astrbot.core.star.register import register_permission_type as permission_type
+from astrbot.core.star.register import (
+    register_platform_adapter_type as platform_adapter_type,
+)
+from astrbot.core.star.register import register_regex as regex
 
 __all__ = [
+    "CustomFilter",
+    "EventMessageType",
+    "EventMessageTypeFilter",
+    "PermissionType",
+    "PermissionTypeFilter",
+    "PlatformAdapterType",
+    "PlatformAdapterTypeFilter",
+    "after_message_sent",
     "command",
     "command_group",
-    "event_message_type",
-    "regex",
-    "platform_adapter_type",
-    "permission_type",
-    "EventMessageTypeFilter",
-    "EventMessageType",
-    "PlatformAdapterTypeFilter",
-    "PlatformAdapterType",
-    "PermissionTypeFilter",
-    "CustomFilter",
     "custom_filter",
-    "PermissionType",
+    "event_message_type",
-    "on_astrbot_loaded",
-    "on_llm_request",
     "llm_tool",
+    "on_astrbot_loaded",
     "on_decorating_result",
-    "after_message_sent",
+    "on_llm_request",
     "on_llm_response",
+    "on_platform_loaded",
+    "permission_type",
+    "platform_adapter_type",
+    "regex",
 ]

astrbot/api/platform/__init__.py

@@ -1,23 +1,22 @@
+from astrbot.core.message.components import *
 from astrbot.core.platform import (
-    AstrMessageEvent,
-    Platform,
     AstrBotMessage,
+    AstrMessageEvent,
+    Group,
     MessageMember,
     MessageType,
+    Platform,
     PlatformMetadata,
-    Group,
 )
-
 from astrbot.core.platform.register import register_platform_adapter
-from astrbot.core.message.components import *
 
 __all__ = [
-    "AstrMessageEvent",
-    "Platform",
     "AstrBotMessage",
+    "AstrMessageEvent",
+    "Group",
     "MessageMember",
     "MessageType",
+    "Platform",
     "PlatformMetadata",
     "register_platform_adapter",
-    "Group",
 ]

astrbot/api/provider/__init__.py

@@ -1,17 +1,18 @@
-from astrbot.core.provider import Provider, STTProvider, Personality
+from astrbot.core.db.po import Personality
+from astrbot.core.provider import Provider, STTProvider
 from astrbot.core.provider.entities import (
+    LLMResponse,
+    ProviderMetaData,
     ProviderRequest,
     ProviderType,
-    ProviderMetaData,
-    LLMResponse,
 )
 
 __all__ = [
-    "Provider",
+    "LLMResponse",
-    "STTProvider",
     "Personality",
+    "Provider",
+    "ProviderMetaData",
     "ProviderRequest",
     "ProviderType",
-    "ProviderMetaData",
+    "STTProvider",
-    "LLMResponse",
 ]

astrbot/api/star/__init__.py

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

astrbot/api/util/__init__.py

@@ -1,7 +1,7 @@
 from astrbot.core.utils.session_waiter import (
-    SessionWaiter,
     SessionController,
+    SessionWaiter,
     session_waiter,
 )
 
-__all__ = ["SessionWaiter", "SessionController", "session_waiter"]
+__all__ = ["SessionController", "SessionWaiter", "session_waiter"]

astrbot/cli/__init__.py

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

astrbot/cli/__main__.py

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

astrbot/cli/commands/__init__.py

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

astrbot/cli/commands/cmd_conf.py

@@ -0,0 +1,209 @@
+import hashlib
+import json
+import zoneinfo
+from collections.abc import Callable
+from typing import Any
+
+import click
+
+from ..utils import check_astrbot_root, get_astrbot_root
+
+
+def _validate_log_level(value: str) -> str:
+    """验证日志级别"""
+    value = value.upper()
+    if value not in ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]:
+        raise click.ClickException(
+            "日志级别必须是 DEBUG/INFO/WARNING/ERROR/CRITICAL 之一",
+        )
+    return value
+
+
+def _validate_dashboard_port(value: str) -> int:
+    """验证 Dashboard 端口"""
+    try:
+        port = int(value)
+        if port < 1 or port > 65535:
+            raise click.ClickException("端口必须在 1-65535 范围内")
+        return port
+    except ValueError:
+        raise click.ClickException("端口必须是数字")
+
+
+def _validate_dashboard_username(value: str) -> str:
+    """验证 Dashboard 用户名"""
+    if not value:
+        raise click.ClickException("用户名不能为空")
+    return value
+
+
+def _validate_dashboard_password(value: str) -> str:
+    """验证 Dashboard 密码"""
+    if not value:
+        raise click.ClickException("密码不能为空")
+    return hashlib.md5(value.encode()).hexdigest()
+
+
+def _validate_timezone(value: str) -> str:
+    """验证时区"""
+    try:
+        zoneinfo.ZoneInfo(value)
+    except Exception:
+        raise click.ClickException(f"无效的时区: {value}，请使用有效的IANA时区名称")
+    return value
+
+
+def _validate_callback_api_base(value: str) -> str:
+    """验证回调接口基址"""
+    if not value.startswith("http://") and not value.startswith("https://"):
+        raise click.ClickException("回调接口基址必须以 http:// 或 https:// 开头")
+    return value
+
+
+# 可通过CLI设置的配置项，配置键到验证器函数的映射
+CONFIG_VALIDATORS: dict[str, Callable[[str], Any]] = {
+    "timezone": _validate_timezone,
+    "log_level": _validate_log_level,
+    "dashboard.port": _validate_dashboard_port,
+    "dashboard.username": _validate_dashboard_username,
+    "dashboard.password": _validate_dashboard_password,
+    "callback_api_base": _validate_callback_api_base,
+}
+
+
+def _load_config() -> dict[str, Any]:
+    """加载或初始化配置文件"""
+    root = get_astrbot_root()
+    if not check_astrbot_root(root):
+        raise click.ClickException(
+            f"{root}不是有效的 AstrBot 根目录，如需初始化请使用 astrbot init",
+        )
+
+    config_path = root / "data" / "cmd_config.json"
+    if not config_path.exists():
+        from astrbot.core.config.default import DEFAULT_CONFIG
+
+        config_path.write_text(
+            json.dumps(DEFAULT_CONFIG, ensure_ascii=False, indent=2),
+            encoding="utf-8-sig",
+        )
+
+    try:
+        return json.loads(config_path.read_text(encoding="utf-8-sig"))
+    except json.JSONDecodeError as e:
+        raise click.ClickException(f"配置文件解析失败: {e!s}")
+
+
+def _save_config(config: dict[str, Any]) -> None:
+    """保存配置文件"""
+    config_path = get_astrbot_root() / "data" / "cmd_config.json"
+
+    config_path.write_text(
+        json.dumps(config, ensure_ascii=False, indent=2),
+        encoding="utf-8-sig",
+    )
+
+
+def _set_nested_item(obj: dict[str, Any], path: str, value: Any) -> None:
+    """设置嵌套字典中的值"""
+    parts = path.split(".")
+    for part in parts[:-1]:
+        if part not in obj:
+            obj[part] = {}
+        elif not isinstance(obj[part], dict):
+            raise click.ClickException(
+                f"配置路径冲突: {'.'.join(parts[: parts.index(part) + 1])} 不是字典",
+            )
+        obj = obj[part]
+    obj[parts[-1]] = value
+
+
+def _get_nested_item(obj: dict[str, Any], path: str) -> Any:
+    """获取嵌套字典中的值"""
+    parts = path.split(".")
+    for part in parts:
+        obj = obj[part]
+    return obj
+
+
+@click.group(name="conf")
+def conf():
+    """配置管理命令
+
+    支持的配置项:
+
+    - timezone: 时区设置 (例如: Asia/Shanghai)
+
+    - log_level: 日志级别 (DEBUG/INFO/WARNING/ERROR/CRITICAL)
+
+    - dashboard.port: Dashboard 端口
+
+    - dashboard.username: Dashboard 用户名
+
+    - dashboard.password: Dashboard 密码
+
+    - callback_api_base: 回调接口基址
+    """
+
+
+@conf.command(name="set")
+@click.argument("key")
+@click.argument("value")
+def set_config(key: str, value: str):
+    """设置配置项的值"""
+    if key not in CONFIG_VALIDATORS:
+        raise click.ClickException(f"不支持的配置项: {key}")
+
+    config = _load_config()
+
+    try:
+        old_value = _get_nested_item(config, key)
+        validated_value = CONFIG_VALIDATORS[key](value)
+        _set_nested_item(config, key, validated_value)
+        _save_config(config)
+
+        click.echo(f"配置已更新: {key}")
+        if key == "dashboard.password":
+            click.echo("  原值: ********")
+            click.echo("  新值: ********")
+        else:
+            click.echo(f"  原值: {old_value}")
+            click.echo(f"  新值: {validated_value}")
+
+    except KeyError:
+        raise click.ClickException(f"未知的配置项: {key}")
+    except Exception as e:
+        raise click.UsageError(f"设置配置失败: {e!s}")
+
+
+@conf.command(name="get")
+@click.argument("key", required=False)
+def get_config(key: str | None = None):
+    """获取配置项的值，不提供key则显示所有可配置项"""
+    config = _load_config()
+
+    if key:
+        if key not in CONFIG_VALIDATORS:
+            raise click.ClickException(f"不支持的配置项: {key}")
+
+        try:
+            value = _get_nested_item(config, key)
+            if key == "dashboard.password":
+                value = "********"
+            click.echo(f"{key}: {value}")
+        except KeyError:
+            raise click.ClickException(f"未知的配置项: {key}")
+        except Exception as e:
+            raise click.UsageError(f"获取配置失败: {e!s}")
+    else:
+        click.echo("当前配置:")
+        for key in CONFIG_VALIDATORS:
+            try:
+                value = (
+                    "********"
+                    if key == "dashboard.password"
+                    else _get_nested_item(config, key)
+                )
+                click.echo(f"  {key}: {value}")
+            except (KeyError, TypeError):
+                pass

astrbot/cli/commands/cmd_init.py

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

astrbot/cli/commands/cmd_plug.py

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

astrbot/cli/commands/cmd_run.py

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

astrbot/cli/utils/__init__.py

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

astrbot/cli/utils/basic.py

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

astrbot/cli/utils/plugin.py

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

astrbot/cli/utils/version_comparator.py

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

astrbot/core/__init__.py

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

astrbot/core/agent/agent.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass
+from typing import Generic
+
+from .hooks import BaseAgentRunHooks
+from .run_context import TContext
+from .tool import FunctionTool
+
+
+@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,38 @@
+from typing import Generic
+
+from .agent import Agent
+from .run_context import TContext
+from .tool import FunctionTool
+
+
+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,30 @@
+from typing import Generic
+
+import mcp
+
+from astrbot.core.agent.tool import FunctionTool
+from astrbot.core.provider.entities import LLMResponse
+
+from .run_context import ContextWrapper, TContext
+
+
+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,385 @@
+import asyncio
+import logging
+from contextlib import AsyncExitStack
+from datetime import timedelta
+from typing import Generic
+
+from tenacity import (
+    before_sleep_log,
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+)
+
+from astrbot import logger
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.utils.log_pipe import LogPipe
+
+from .run_context import TContext
+from .tool import FunctionTool
+
+try:
+    import anyio
+    import mcp
+    from mcp.client.sse import sse_client
+except (ModuleNotFoundError, ImportError):
+    logger.warning(
+        "Warning: Missing 'mcp' dependency, MCP services will be unavailable."
+    )
+
+try:
+    from mcp.client.streamable_http import streamablehttp_client
+except (ModuleNotFoundError, ImportError):
+    logger.warning(
+        "Warning: Missing 'mcp' dependency or MCP library version too old, Streamable HTTP connection unavailable.",
+    )
+
+
+def _prepare_config(config: dict) -> dict:
+    """Prepare configuration, handle nested format"""
+    if config.get("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]:
+    """Quick test MCP server connectivity"""
+    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 connection config missing transport or type field")
+
+        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, ""
+                    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, ""
+                    return False, f"HTTP {response.status}: {response.reason}"
+
+    except asyncio.TimeoutError:
+        return False, f"Connection timeout: {timeout} seconds"
+    except Exception as e:
+        return False, f"{e!s}"
+
+
+class MCPClient:
+    def __init__(self):
+        # Initialize session and client objects
+        self.session: mcp.ClientSession | None = None
+        self.exit_stack = AsyncExitStack()
+        self._old_exit_stacks: list[AsyncExitStack] = []  # Track old stacks for cleanup
+
+        self.name: str | None = None
+        self.active: bool = True
+        self.tools: list[mcp.Tool] = []
+        self.server_errlogs: list[str] = []
+        self.running_event = asyncio.Event()
+
+        # Store connection config for reconnection
+        self._mcp_server_config: dict | None = None
+        self._server_name: str | None = None
+        self._reconnect_lock = asyncio.Lock()  # Lock for thread-safe reconnection
+        self._reconnecting: bool = False  # For logging and debugging
+
+    async def connect_to_server(self, mcp_server_config: dict, name: str):
+        """Connect to MCP server
+
+        If `url` parameter exists:
+            1. When transport is specified as `streamable_http`, use Streamable HTTP connection.
+            2. When transport is specified as `sse`, use SSE connection.
+            3. If not specified, default to SSE connection to MCP service.
+
+        Args:
+            mcp_server_config (dict): Configuration for the MCP server. See https://modelcontextprotocol.io/quickstart/server
+
+        """
+        # Store config for reconnection
+        self._mcp_server_config = mcp_server_config
+        self._server_name = name
+
+        cfg = _prepare_config(mcp_server_config.copy())
+
+        def logging_callback(msg: str):
+            # Handle MCP service error logs
+            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 connection config missing transport or type field")
+
+            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):
+                # Handle MCP service error logs
+                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 _reconnect(self) -> None:
+        """Reconnect to the MCP server using the stored configuration.
+
+        Uses asyncio.Lock to ensure thread-safe reconnection in concurrent environments.
+
+        Raises:
+            Exception: raised when reconnection fails
+        """
+        async with self._reconnect_lock:
+            # Check if already reconnecting (useful for logging)
+            if self._reconnecting:
+                logger.debug(
+                    f"MCP Client {self._server_name} is already reconnecting, skipping"
+                )
+                return
+
+            if not self._mcp_server_config or not self._server_name:
+                raise Exception("Cannot reconnect: missing connection configuration")
+
+            self._reconnecting = True
+            try:
+                logger.info(
+                    f"Attempting to reconnect to MCP server {self._server_name}..."
+                )
+
+                # Save old exit_stack for later cleanup (don't close it now to avoid cancel scope issues)
+                if self.exit_stack:
+                    self._old_exit_stacks.append(self.exit_stack)
+
+                # Mark old session as invalid
+                self.session = None
+
+                # Create new exit stack for new connection
+                self.exit_stack = AsyncExitStack()
+
+                # Reconnect using stored config
+                await self.connect_to_server(self._mcp_server_config, self._server_name)
+                await self.list_tools_and_save()
+
+                logger.info(
+                    f"Successfully reconnected to MCP server {self._server_name}"
+                )
+            except Exception as e:
+                logger.error(
+                    f"Failed to reconnect to MCP server {self._server_name}: {e}"
+                )
+                raise
+            finally:
+                self._reconnecting = False
+
+    async def call_tool_with_reconnect(
+        self,
+        tool_name: str,
+        arguments: dict,
+        read_timeout_seconds: timedelta,
+    ) -> mcp.types.CallToolResult:
+        """Call MCP tool with automatic reconnection on failure, max 2 retries.
+
+        Args:
+            tool_name: tool name
+            arguments: tool arguments
+            read_timeout_seconds: read timeout
+
+        Returns:
+            MCP tool call result
+
+        Raises:
+            ValueError: MCP session is not available
+            anyio.ClosedResourceError: raised after reconnection failure
+        """
+
+        @retry(
+            retry=retry_if_exception_type(anyio.ClosedResourceError),
+            stop=stop_after_attempt(2),
+            wait=wait_exponential(multiplier=1, min=1, max=3),
+            before_sleep=before_sleep_log(logger, logging.WARNING),
+            reraise=True,
+        )
+        async def _call_with_retry():
+            if not self.session:
+                raise ValueError("MCP session is not available for MCP function tools.")
+
+            try:
+                return await self.session.call_tool(
+                    name=tool_name,
+                    arguments=arguments,
+                    read_timeout_seconds=read_timeout_seconds,
+                )
+            except anyio.ClosedResourceError:
+                logger.warning(
+                    f"MCP tool {tool_name} call failed (ClosedResourceError), attempting to reconnect..."
+                )
+                # Attempt to reconnect
+                await self._reconnect()
+                # Reraise the exception to trigger tenacity retry
+                raise
+
+        return await _call_with_retry()
+
+    async def cleanup(self):
+        """Clean up resources including old exit stacks from reconnections"""
+        # Set running_event first to unblock any waiting tasks
+        self.running_event.set()
+
+        # Close current exit stack
+        try:
+            await self.exit_stack.aclose()
+        except Exception as e:
+            logger.debug(f"Error closing current exit stack: {e}")
+
+        # Don't close old exit stacks as they may be in different task contexts
+        # They will be garbage collected naturally
+        # Just clear the list to release references
+        self._old_exit_stacks.clear()
+
+
+class MCPTool(FunctionTool, Generic[TContext]):
+    """A function tool that calls an MCP service."""
+
+    def __init__(
+        self, mcp_tool: mcp.Tool, mcp_client: MCPClient, mcp_server_name: str, **kwargs
+    ):
+        super().__init__(
+            name=mcp_tool.name,
+            description=mcp_tool.description or "",
+            parameters=mcp_tool.inputSchema,
+        )
+        self.mcp_tool = mcp_tool
+        self.mcp_client = mcp_client
+        self.mcp_server_name = mcp_server_name
+
+    async def call(
+        self, context: ContextWrapper[TContext], **kwargs
+    ) -> mcp.types.CallToolResult:
+        return await self.mcp_client.call_tool_with_reconnect(
+            tool_name=self.mcp_tool.name,
+            arguments=kwargs,
+            read_timeout_seconds=timedelta(seconds=context.tool_call_timeout),
+        )

astrbot/core/agent/message.py

@@ -0,0 +1,175 @@
+# Inspired by MoonshotAI/kosong, credits to MoonshotAI/kosong authors for the original implementation.
+# License: Apache License 2.0
+
+from typing import Any, ClassVar, Literal, cast
+
+from pydantic import BaseModel, GetCoreSchemaHandler
+from pydantic_core import core_schema
+
+
+class ContentPart(BaseModel):
+    """A part of the content in a message."""
+
+    __content_part_registry: ClassVar[dict[str, type["ContentPart"]]] = {}
+
+    type: str
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+
+        invalid_subclass_error_msg = f"ContentPart subclass {cls.__name__} must have a `type` field of type `str`"
+
+        type_value = getattr(cls, "type", None)
+        if type_value is None or not isinstance(type_value, str):
+            raise ValueError(invalid_subclass_error_msg)
+
+        cls.__content_part_registry[type_value] = cls
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, source_type: Any, handler: GetCoreSchemaHandler
+    ) -> core_schema.CoreSchema:
+        # If we're dealing with the base ContentPart class, use custom validation
+        if cls.__name__ == "ContentPart":
+
+            def validate_content_part(value: Any) -> Any:
+                # if it's already an instance of a ContentPart subclass, return it
+                if hasattr(value, "__class__") and issubclass(value.__class__, cls):
+                    return value
+
+                # if it's a dict with a type field, dispatch to the appropriate subclass
+                if isinstance(value, dict) and "type" in value:
+                    type_value: Any | None = cast(dict[str, Any], value).get("type")
+                    if not isinstance(type_value, str):
+                        raise ValueError(f"Cannot validate {value} as ContentPart")
+                    target_class = cls.__content_part_registry[type_value]
+                    return target_class.model_validate(value)
+
+                raise ValueError(f"Cannot validate {value} as ContentPart")
+
+            return core_schema.no_info_plain_validator_function(validate_content_part)
+
+        # for subclasses, use the default schema
+        return handler(source_type)
+
+
+class TextPart(ContentPart):
+    """
+    >>> TextPart(text="Hello, world!").model_dump()
+    {'type': 'text', 'text': 'Hello, world!'}
+    """
+
+    type: str = "text"
+    text: str
+
+
+class ImageURLPart(ContentPart):
+    """
+    >>> ImageURLPart(image_url="http://example.com/image.jpg").model_dump()
+    {'type': 'image_url', 'image_url': 'http://example.com/image.jpg'}
+    """
+
+    class ImageURL(BaseModel):
+        url: str
+        """The URL of the image, can be data URI scheme like `data:image/png;base64,...`."""
+        id: str | None = None
+        """The ID of the image, to allow LLMs to distinguish different images."""
+
+    type: str = "image_url"
+    image_url: ImageURL
+
+
+class AudioURLPart(ContentPart):
+    """
+    >>> AudioURLPart(audio_url=AudioURLPart.AudioURL(url="https://example.com/audio.mp3")).model_dump()
+    {'type': 'audio_url', 'audio_url': {'url': 'https://example.com/audio.mp3', 'id': None}}
+    """
+
+    class AudioURL(BaseModel):
+        url: str
+        """The URL of the audio, can be data URI scheme like `data:audio/aac;base64,...`."""
+        id: str | None = None
+        """The ID of the audio, to allow LLMs to distinguish different audios."""
+
+    type: str = "audio_url"
+    audio_url: AudioURL
+
+
+class ToolCall(BaseModel):
+    """
+    A tool call requested by the assistant.
+
+    >>> ToolCall(
+    ...     id="123",
+    ...     function=ToolCall.FunctionBody(
+    ...         name="function",
+    ...         arguments="{}"
+    ...     ),
+    ... ).model_dump()
+    {'type': 'function', 'id': '123', 'function': {'name': 'function', 'arguments': '{}'}}
+    """
+
+    class FunctionBody(BaseModel):
+        name: str
+        arguments: str | None
+
+    type: Literal["function"] = "function"
+
+    id: str
+    """The ID of the tool call."""
+    function: FunctionBody
+    """The function body of the tool call."""
+    extra_content: dict[str, Any] | None = None
+    """Extra metadata for the tool call."""
+
+    def model_dump(self, **kwargs: Any) -> dict[str, Any]:
+        if self.extra_content is None:
+            kwargs.setdefault("exclude", set()).add("extra_content")
+        return super().model_dump(**kwargs)
+
+
+class ToolCallPart(BaseModel):
+    """A part of the tool call."""
+
+    arguments_part: str | None = None
+    """A part of the arguments of the tool call."""
+
+
+class Message(BaseModel):
+    """A message in a conversation."""
+
+    role: Literal[
+        "system",
+        "user",
+        "assistant",
+        "tool",
+    ]
+
+    content: str | list[ContentPart]
+    """The content of the message."""
+
+
+class AssistantMessageSegment(Message):
+    """A message segment from the assistant."""
+
+    role: Literal["assistant"] = "assistant"
+    tool_calls: list[ToolCall] | list[dict] | None = None
+
+
+class ToolCallMessageSegment(Message):
+    """A message segment representing a tool call."""
+
+    role: Literal["tool"] = "tool"
+    tool_call_id: str
+
+
+class UserMessageSegment(Message):
+    """A message segment from the user."""
+
+    role: Literal["user"] = "user"
+
+
+class SystemMessageSegment(Message):
+    """A message segment from the system."""
+
+    role: Literal["system"] = "system"

astrbot/core/agent/response.py

@@ -0,0 +1,14 @@
+import typing as T
+from dataclasses import dataclass
+
+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,22 @@
+from typing import Any, Generic
+
+from pydantic import Field
+from pydantic.dataclasses import dataclass
+from typing_extensions import TypeVar
+
+from .message import Message
+
+TContext = TypeVar("TContext", default=Any)
+
+
+@dataclass(config={"arbitrary_types_allowed": True})
+class ContextWrapper(Generic[TContext]):
+    """A context for running an agent, which can be used to pass additional data or state."""
+
+    context: TContext
+    messages: list[Message] = Field(default_factory=list)
+    """This field stores the llm message context for the agent run, agent runners will maintain this field automatically."""
+    tool_call_timeout: int = 60  # Default tool call timeout in seconds
+
+
+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

@@ -0,0 +1,62 @@
+import abc
+import typing as T
+from enum import Enum, auto
+
+from astrbot.core.provider import Provider
+from astrbot.core.provider.entities import LLMResponse
+
+from ..hooks import BaseAgentRunHooks
+from ..response import AgentResponse
+from ..run_context import ContextWrapper, TContext
+from ..tool_executor import BaseFunctionToolExecutor
+
+
+class AgentState(Enum):
+    """Defines the state of the agent."""
+
+    IDLE = auto()  # Initial state
+    RUNNING = auto()  # Currently processing
+    DONE = auto()  # Completed
+    ERROR = auto()  # Error state
+
+
+class BaseAgentRunner(T.Generic[TContext]):
+    @abc.abstractmethod
+    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.
+        """
+        ...
+
+    @abc.abstractmethod
+    async def step(self) -> T.AsyncGenerator[AgentResponse, None]:
+        """Process a single step of the agent."""
+        ...
+
+    @abc.abstractmethod
+    async def step_until_done(
+        self, max_step: int
+    ) -> T.AsyncGenerator[AgentResponse, None]:
+        """Process steps until the agent is done."""
+        ...
+
+    @abc.abstractmethod
+    def done(self) -> bool:
+        """Check if the agent has completed its task.
+        Returns True if the agent is done, False otherwise.
+        """
+        ...
+
+    @abc.abstractmethod
+    def get_final_llm_resp(self) -> LLMResponse | None:
+        """Get the final observation from the agent.
+        This method should be called after the agent is done.
+        """
+        ...

astrbot/core/agent/runners/tool_loop_agent_runner.py

@@ -0,0 +1,406 @@
+import sys
+import traceback
+import typing as T
+
+from mcp.types import (
+    BlobResourceContents,
+    CallToolResult,
+    EmbeddedResource,
+    ImageContent,
+    TextContent,
+    TextResourceContents,
+)
+
+from astrbot import logger
+from astrbot.core.message.message_event_result import (
+    MessageChain,
+)
+from astrbot.core.provider.entities import (
+    LLMResponse,
+    ProviderRequest,
+    ToolCallsResult,
+)
+from astrbot.core.provider.provider import Provider
+
+from ..hooks import BaseAgentRunHooks
+from ..message import AssistantMessageSegment, Message, ToolCallMessageSegment
+from ..response import AgentResponseData
+from ..run_context import ContextWrapper, TContext
+from ..tool_executor import BaseFunctionToolExecutor
+from .base import AgentResponse, AgentState, BaseAgentRunner
+
+if sys.version_info >= (3, 12):
+    from typing import override
+else:
+    from typing_extensions import override
+
+
+class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
+    @override
+    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
+
+        messages = []
+        # append existing messages in the run context
+        for msg in request.contexts:
+            messages.append(Message.model_validate(msg))
+        if request.prompt is not None:
+            m = await request.assemble_context()
+            messages.append(Message.model_validate(m))
+        if request.system_prompt:
+            messages.insert(
+                0,
+                Message(role="system", content=request.system_prompt),
+            )
+        self.run_context.messages = messages
+
+    def _transition_state(self, new_state: AgentState) -> None:
+        """转换 Agent 状态"""
+        if self._state != new_state:
+            logger.debug(f"Agent state transition: {self._state} -> {new_state}")
+            self._state = new_state
+
+    async def _iter_llm_responses(self) -> T.AsyncGenerator[LLMResponse, None]:
+        """Yields chunks *and* a final LLMResponse."""
+        if self.streaming:
+            stream = self.provider.text_chat_stream(**self.req.__dict__)
+            async for resp in stream:  # type: ignore
+                yield resp
+        else:
+            yield await self.provider.text_chat(**self.req.__dict__)
+
+    @override
+    async def step(self):
+        """Process a single step of the agent.
+        This method should return the result of the step.
+        """
+        if not self.req:
+            raise ValueError("Request is not set. Please call reset() first.")
+
+        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
+
+        async for llm_response in self._iter_llm_responses():
+            assert isinstance(llm_response, LLMResponse)
+            if llm_response.is_chunk:
+                if llm_response.result_chain:
+                    yield AgentResponse(
+                        type="streaming_delta",
+                        data=AgentResponseData(chain=llm_response.result_chain),
+                    )
+                elif llm_response.completion_text:
+                    yield AgentResponse(
+                        type="streaming_delta",
+                        data=AgentResponseData(
+                            chain=MessageChain().message(llm_response.completion_text),
+                        ),
+                    )
+                elif llm_response.reasoning_content:
+                    yield AgentResponse(
+                        type="streaming_delta",
+                        data=AgentResponseData(
+                            chain=MessageChain(type="reasoning").message(
+                                llm_response.reasoning_content,
+                            ),
+                        ),
+                    )
+                continue
+            llm_resp_result = llm_response
+            break  # got final response
+
+        if not llm_resp_result:
+            return
+
+        # 处理 LLM 响应
+        llm_resp = llm_resp_result
+
+        if llm_resp.role == "err":
+            # 如果 LLM 响应错误，转换到错误状态
+            self.final_llm_resp = llm_resp
+            self._transition_state(AgentState.ERROR)
+            yield AgentResponse(
+                type="err",
+                data=AgentResponseData(
+                    chain=MessageChain().message(
+                        f"LLM 响应错误: {llm_resp.completion_text or '未知错误'}",
+                    ),
+                ),
+            )
+
+        if not llm_resp.tools_call_name:
+            # 如果没有工具调用，转换到完成状态
+            self.final_llm_resp = llm_resp
+            self._transition_state(AgentState.DONE)
+            # record the final assistant message
+            self.run_context.messages.append(
+                Message(
+                    role="assistant",
+                    content=llm_resp.completion_text or "",
+                ),
+            )
+            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:
+            yield AgentResponse(
+                type="llm_result",
+                data=AgentResponseData(chain=llm_resp.result_chain),
+            )
+        elif llm_resp.completion_text:
+            yield AgentResponse(
+                type="llm_result",
+                data=AgentResponseData(
+                    chain=MessageChain().message(llm_resp.completion_text),
+                ),
+            )
+
+        # 如果有工具调用，还需处理工具调用
+        if llm_resp.tools_call_name:
+            tool_call_result_blocks = []
+            for tool_call_name in llm_resp.tools_call_name:
+                yield AgentResponse(
+                    type="tool_call",
+                    data=AgentResponseData(
+                        chain=MessageChain(type="tool_call").message(
+                            f"🔨 调用工具: {tool_call_name}"
+                        ),
+                    ),
+                )
+            async for result in self._handle_function_tools(self.req, llm_resp):
+                if isinstance(result, list):
+                    tool_call_result_blocks = result
+                elif isinstance(result, MessageChain):
+                    result.type = "tool_call_result"
+                    yield AgentResponse(
+                        type="tool_call_result",
+                        data=AgentResponseData(chain=result),
+                    )
+            # 将结果添加到上下文中
+            tool_calls_result = ToolCallsResult(
+                tool_calls_info=AssistantMessageSegment(
+                    tool_calls=llm_resp.to_openai_to_calls_model(),
+                    content=llm_resp.completion_text,
+                ),
+                tool_calls_result=tool_call_result_blocks,
+            )
+            # record the assistant message with tool calls
+            self.run_context.messages.extend(
+                tool_calls_result.to_openai_messages_model()
+            )
+
+            self.req.append_tool_calls_result(tool_calls_result)
+
+    async def step_until_done(
+        self, max_step: int
+    ) -> T.AsyncGenerator[AgentResponse, None]:
+        """Process steps until the agent is done."""
+        step_count = 0
+        while not self.done() and step_count < max_step:
+            step_count += 1
+            async for resp in self.step():
+                yield resp
+
+    async def _handle_function_tools(
+        self,
+        req: ProviderRequest,
+        llm_response: LLMResponse,
+    ) -> T.AsyncGenerator[MessageChain | list[ToolCallMessageSegment], None]:
+        """处理函数工具调用。"""
+        tool_call_result_blocks: list[ToolCallMessageSegment] = []
+        logger.info(f"Agent 使用工具: {llm_response.tools_call_name}")
+
+        # 执行函数调用
+        for func_tool_name, func_tool_args, func_tool_id in zip(
+            llm_response.tools_call_name,
+            llm_response.tools_call_args,
+            llm_response.tools_call_ids,
+        ):
+            try:
+                if not req.func_tool:
+                    return
+                func_tool = req.func_tool.get_func(func_tool_name)
+                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}",
+                        ),
+                    )
+                    continue
+
+                valid_params = {}  # 参数过滤：只传递函数实际需要的参数
+
+                # 获取实际的 handler 函数
+                if func_tool.handler:
+                    logger.debug(
+                        f"工具 {func_tool_name} 期望的参数: {func_tool.parameters}",
+                    )
+                    if func_tool.parameters and func_tool.parameters.get("properties"):
+                        expected_params = set(func_tool.parameters["properties"].keys())
+
+                        valid_params = {
+                            k: v
+                            for k, v in func_tool_args.items()
+                            if k in expected_params
+                        }
+
+                    # 记录被忽略的参数
+                    ignored_params = set(func_tool_args.keys()) - set(
+                        valid_params.keys(),
+                    )
+                    if ignored_params:
+                        logger.warning(
+                            f"工具 {func_tool_name} 忽略非期望参数: {ignored_params}",
+                        )
+                else:
+                    # 如果没有 handler（如 MCP 工具），使用所有参数
+                    valid_params = func_tool_args
+
+                try:
+                    await self.agent_hooks.on_tool_start(
+                        self.run_context,
+                        func_tool,
+                        valid_params,
+                    )
+                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,
+                    **valid_params,  # 只传递有效的参数
+                )
+
+                _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=res.content[0].text,
+                                ),
+                            )
+                            yield MessageChain().message(res.content[0].text)
+                        elif isinstance(res.content[0], ImageContent):
+                            tool_call_result_blocks.append(
+                                ToolCallMessageSegment(
+                                    role="tool",
+                                    tool_call_id=func_tool_id,
+                                    content="返回了图片(已直接发送给用户)",
+                                ),
+                            )
+                            yield MessageChain(type="tool_direct_result").base64_image(
+                                res.content[0].data,
+                            )
+                        elif isinstance(res.content[0], EmbeddedResource):
+                            resource = res.content[0].resource
+                            if isinstance(resource, TextResourceContents):
+                                tool_call_result_blocks.append(
+                                    ToolCallMessageSegment(
+                                        role="tool",
+                                        tool_call_id=func_tool_id,
+                                        content=resource.text,
+                                    ),
+                                )
+                                yield MessageChain().message(resource.text)
+                            elif (
+                                isinstance(resource, BlobResourceContents)
+                                and resource.mimeType
+                                and resource.mimeType.startswith("image/")
+                            ):
+                                tool_call_result_blocks.append(
+                                    ToolCallMessageSegment(
+                                        role="tool",
+                                        tool_call_id=func_tool_id,
+                                        content="返回了图片(已直接发送给用户)",
+                                    ),
+                                )
+                                yield MessageChain(
+                                    type="tool_direct_result",
+                                ).base64_image(resource.blob)
+                            else:
+                                tool_call_result_blocks.append(
+                                    ToolCallMessageSegment(
+                                        role="tool",
+                                        tool_call_id=func_tool_id,
+                                        content="返回的数据类型不受支持",
+                                    ),
+                                )
+                                yield MessageChain().message("返回的数据类型不受支持。")
+
+                    elif resp is None:
+                        # Tool 直接请求发送消息给用户
+                        # 这里我们将直接结束 Agent Loop。
+                        # 发送消息逻辑在 ToolExecutor 中处理了。
+                        logger.warning(
+                            f"{func_tool_name} 没有没有返回值或者将结果直接发送给用户，此工具调用不会被记录到历史中。"
+                        )
+                        self._transition_state(AgentState.DONE)
+                    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)
+            except Exception as e:
+                logger.warning(traceback.format_exc())
+                tool_call_result_blocks.append(
+                    ToolCallMessageSegment(
+                        role="tool",
+                        tool_call_id=func_tool_id,
+                        content=f"error: {e!s}",
+                    ),
+                )
+
+        # 处理函数调用响应
+        if tool_call_result_blocks:
+            yield tool_call_result_blocks
+
+    def done(self) -> bool:
+        """检查 Agent 是否已完成工作"""
+        return self._state in (AgentState.DONE, AgentState.ERROR)
+
+    def get_final_llm_resp(self) -> LLMResponse | None:
+        return self.final_llm_resp

astrbot/core/agent/tool.py

@@ -0,0 +1,285 @@
+from collections.abc import Awaitable, Callable
+from typing import Any, Generic
+
+import jsonschema
+import mcp
+from deprecated import deprecated
+from pydantic import Field, model_validator
+from pydantic.dataclasses import dataclass
+
+from .run_context import ContextWrapper, TContext
+
+ParametersType = dict[str, Any]
+ToolExecResult = str | mcp.types.CallToolResult
+
+
+@dataclass
+class ToolSchema:
+    """A class representing the schema of a tool for function calling."""
+
+    name: str
+    """The name of the tool."""
+
+    description: str
+    """The description of the tool."""
+
+    parameters: ParametersType
+    """The parameters of the tool, in JSON Schema format."""
+
+    @model_validator(mode="after")
+    def validate_parameters(self) -> "ToolSchema":
+        jsonschema.validate(
+            self.parameters, jsonschema.Draft202012Validator.META_SCHEMA
+        )
+        return self
+
+
+@dataclass
+class FunctionTool(ToolSchema, Generic[TContext]):
+    """A callable tool, for function calling."""
+
+    handler: Callable[..., Awaitable[Any]] | None = None
+    """a callable that implements the tool's functionality. It should be an async function."""
+
+    handler_module_path: str | None = None
+    """
+    The module path of the handler function. This is empty when the origin is mcp.
+    This field must be retained, as the handler will be wrapped in functools.partial during initialization,
+    causing the handler's __module__ to be functools
+    """
+    active: bool = True
+    """
+    Whether the tool is active. This field is a special field for AstrBot.
+    You can ignore it when integrating with other frameworks.
+    """
+
+    def __repr__(self):
+        return f"FuncTool(name={self.name}, parameters={self.parameters}, description={self.description})"
+
+    async def call(self, context: ContextWrapper[TContext], **kwargs) -> ToolExecResult:
+        """Run the tool with the given arguments. The handler field has priority."""
+        raise NotImplementedError(
+            "FunctionTool.call() must be implemented by subclasses or set a handler."
+        )
+
+
+@dataclass
+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).
+    """
+
+    tools: list[FunctionTool] = Field(default_factory=list)
+
+    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) -> FunctionTool | None:
+        """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: dict[str, Any] = {
+                "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,17 @@
+from collections.abc import AsyncGenerator
+from typing import Any, Generic
+
+import mcp
+
+from .run_context import ContextWrapper, TContext
+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,19 @@
+from pydantic import Field
+from pydantic.dataclasses import dataclass
+
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.platform.astr_message_event import AstrMessageEvent
+from astrbot.core.star.context import Context
+
+
+@dataclass(config={"arbitrary_types_allowed": True})
+class AstrAgentContext:
+    context: Context
+    """The star context instance"""
+    event: AstrMessageEvent
+    """The message event associated with the agent context."""
+    extra: dict[str, str] = Field(default_factory=dict)
+    """Customized extra data."""
+
+
+AgentContextWrapper = ContextWrapper[AstrAgentContext]

astrbot/core/astr_agent_hooks.py

@@ -0,0 +1,36 @@
+from typing import Any
+
+from mcp.types import CallToolResult
+
+from astrbot.core.agent.hooks import BaseAgentRunHooks
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.agent.tool import FunctionTool
+from astrbot.core.astr_agent_context import AstrAgentContext
+from astrbot.core.pipeline.context_utils import call_event_hook
+from astrbot.core.star.star_handler import EventType
+
+
+class MainAgentHooks(BaseAgentRunHooks[AstrAgentContext]):
+    async def on_agent_done(self, run_context, llm_response):
+        # 执行事件钩子
+        await call_event_hook(
+            run_context.context.event,
+            EventType.OnLLMResponseEvent,
+            llm_response,
+        )
+
+    async def on_tool_end(
+        self,
+        run_context: ContextWrapper[AstrAgentContext],
+        tool: FunctionTool[Any],
+        tool_args: dict | None,
+        tool_result: CallToolResult | None,
+    ):
+        run_context.context.event.clear_result()
+
+
+class EmptyAgentHooks(BaseAgentRunHooks[AstrAgentContext]):
+    pass
+
+
+MAIN_AGENT_HOOKS = MainAgentHooks()

astrbot/core/astr_agent_run_util.py

@@ -0,0 +1,80 @@
+import traceback
+from collections.abc import AsyncGenerator
+
+from astrbot.core import logger
+from astrbot.core.agent.runners.tool_loop_agent_runner import ToolLoopAgentRunner
+from astrbot.core.astr_agent_context import AstrAgentContext
+from astrbot.core.message.message_event_result import (
+    MessageChain,
+    MessageEventResult,
+    ResultContentType,
+)
+
+AgentRunner = ToolLoopAgentRunner[AstrAgentContext]
+
+
+async def run_agent(
+    agent_runner: AgentRunner,
+    max_step: int = 30,
+    show_tool_use: bool = True,
+    stream_to_general: bool = False,
+    show_reasoning: bool = False,
+) -> AsyncGenerator[MessageChain | None, None]:
+    step_idx = 0
+    astr_event = agent_runner.run_context.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 需要直接发送给用户的内容
+                        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:
+                        await astr_event.send(resp.data["chain"])
+                    continue
+
+                if stream_to_general and resp.type == "streaming_delta":
+                    continue
+
+                if stream_to_general or 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()
+                elif resp.type == "streaming_delta":
+                    chain = resp.data["chain"]
+                    if chain.type == "reasoning" and not show_reasoning:
+                        # display the reasoning content only when configured
+                        continue
+                    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错误信息: {e!s}\n\n请在控制台查看和分享错误详情。\n"
+            if agent_runner.streaming:
+                yield MessageChain().message(err_msg)
+            else:
+                astr_event.set_result(MessageEventResult().message(err_msg))
+            return

astrbot/core/astr_agent_tool_exec.py

@@ -0,0 +1,246 @@
+import asyncio
+import inspect
+import traceback
+import typing as T
+
+import mcp
+
+from astrbot import logger
+from astrbot.core.agent.handoff import HandoffTool
+from astrbot.core.agent.mcp_client import MCPTool
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.agent.tool import FunctionTool, ToolSet
+from astrbot.core.agent.tool_executor import BaseFunctionToolExecutor
+from astrbot.core.astr_agent_context import AstrAgentContext
+from astrbot.core.message.message_event_result import (
+    CommandResult,
+    MessageChain,
+    MessageEventResult,
+)
+from astrbot.core.provider.register import llm_tools
+
+
+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
+
+        elif isinstance(tool, MCPTool):
+            async for r in cls._execute_mcp(tool, run_context, **tool_args):
+                yield r
+            return
+
+        else:
+            async for r in cls._execute_local(tool, run_context, **tool_args):
+                yield r
+            return
+
+    @classmethod
+    async def _execute_handoff(
+        cls,
+        tool: HandoffTool,
+        run_context: ContextWrapper[AstrAgentContext],
+        **tool_args,
+    ):
+        input_ = tool_args.get("input")
+
+        # 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
+
+        ctx = run_context.context.context
+        event = run_context.context.event
+        umo = event.unified_msg_origin
+        prov_id = await ctx.get_current_chat_provider_id(umo)
+        llm_resp = await ctx.tool_loop_agent(
+            event=event,
+            chat_provider_id=prov_id,
+            prompt=input_,
+            system_prompt=tool.agent.instructions,
+            tools=toolset,
+            max_steps=30,
+            run_hooks=tool.agent.run_hooks,
+        )
+        yield mcp.types.CallToolResult(
+            content=[mcp.types.TextContent(type="text", text=llm_resp.completion_text)]
+        )
+
+    @classmethod
+    async def _execute_local(
+        cls,
+        tool: FunctionTool,
+        run_context: ContextWrapper[AstrAgentContext],
+        **tool_args,
+    ):
+        event = run_context.context.event
+        if not event:
+            raise ValueError("Event must be provided for local function tools.")
+
+        is_override_call = False
+        for ty in type(tool).mro():
+            if "call" in ty.__dict__ and ty.__dict__["call"] is not FunctionTool.call:
+                is_override_call = True
+                break
+
+        # 检查 tool 下有没有 run 方法
+        if not tool.handler and not hasattr(tool, "run") and not is_override_call:
+            raise ValueError("Tool must have a valid handler or override 'run' method.")
+
+        awaitable = None
+        method_name = ""
+        if tool.handler:
+            awaitable = tool.handler
+            method_name = "decorator_handler"
+        elif is_override_call:
+            awaitable = tool.call
+            method_name = "call"
+        elif hasattr(tool, "run"):
+            awaitable = getattr(tool, "run")
+            method_name = "run"
+        if awaitable is None:
+            raise ValueError("Tool must have a valid handler or override 'run' method.")
+
+        wrapper = call_local_llm_tool(
+            context=run_context,
+            handler=awaitable,
+            method_name=method_name,
+            **tool_args,
+        )
+        while True:
+            try:
+                resp = await asyncio.wait_for(
+                    anext(wrapper),
+                    timeout=run_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,其内容如"工具没有返回内容"
+                    if res := run_context.context.event.get_result():
+                        if res.chain:
+                            try:
+                                await event.send(
+                                    MessageChain(
+                                        chain=res.chain,
+                                        type="tool_direct_result",
+                                    )
+                                )
+                            except Exception as e:
+                                logger.error(
+                                    f"Tool 直接发送消息失败: {e}",
+                                    exc_info=True,
+                                )
+                    yield None
+            except asyncio.TimeoutError:
+                raise Exception(
+                    f"tool {tool.name} execution timeout after {run_context.tool_call_timeout} seconds.",
+                )
+            except StopAsyncIteration:
+                break
+
+    @classmethod
+    async def _execute_mcp(
+        cls,
+        tool: FunctionTool,
+        run_context: ContextWrapper[AstrAgentContext],
+        **tool_args,
+    ):
+        res = await tool.call(run_context, **tool_args)
+        if not res:
+            return
+        yield res
+
+
+async def call_local_llm_tool(
+    context: ContextWrapper[AstrAgentContext],
+    handler: T.Callable[..., T.Awaitable[T.Any]],
+    method_name: str,
+    *args,
+    **kwargs,
+) -> T.AsyncGenerator[T.Any, None]:
+    """执行本地 LLM 工具的处理函数并处理其返回结果"""
+    ready_to_call = None  # 一个协程或者异步生成器
+
+    trace_ = None
+
+    event = context.context.event
+
+    try:
+        if method_name == "run" or method_name == "decorator_handler":
+            ready_to_call = handler(event, *args, **kwargs)
+        elif method_name == "call":
+            ready_to_call = handler(context, *args, **kwargs)
+        else:
+            raise ValueError(f"未知的方法名: {method_name}")
+    except ValueError as e:
+        logger.error(f"调用本地 LLM 工具时出错: {e}", exc_info=True)
+    except TypeError:
+        logger.error("处理函数参数不匹配，请检查 handler 的定义。", exc_info=True)
+    except Exception as e:
+        trace_ = traceback.format_exc()
+        logger.error(f"调用本地 LLM 工具时出错: {e}\n{trace_}")
+
+    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

astrbot/core/astrbot_config_mgr.py

@@ -0,0 +1,275 @@
+import os
+import uuid
+from typing import TypedDict, TypeVar
+
+from astrbot.core import AstrBotConfig, logger
+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.umop_config_router import UmopConfigRouter
+from astrbot.core.utils.astrbot_path import get_astrbot_config_path
+from astrbot.core.utils.shared_preferences import SharedPreferences
+
+_VT = TypeVar("_VT")
+
+
+class ConfInfo(TypedDict):
+    """Configuration information for a specific session or platform."""
+
+    id: str  # UUID of the configuration or "default"
+    name: str
+    path: str  # File name to the configuration file
+
+
+DEFAULT_CONFIG_CONF_INFO = ConfInfo(
+    id="default",
+    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,
+        ucr: UmopConfigRouter,
+        sp: SharedPreferences,
+    ):
+        self.sp = sp
+        self.ucr = ucr
+        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 _load_conf_mapping(self, umo: str | MessageSession) -> ConfInfo:
+        """获取指定 umo 的配置文件 uuid, 如果不存在则返回默认配置(返回 "default")
+
+        Returns:
+            ConfInfo: 包含配置文件的 uuid, 路径和名称等信息, 是一个 dict 类型
+
+        """
+        # uuid -> { "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
+
+        conf_id = self.ucr.get_conf_id_for_umop(umo)
+        if conf_id:
+            meta = abconf_data.get(conf_id)
+            if meta and isinstance(meta, dict):
+                # the bind relation between umo and conf is defined in ucr now, so we remove "umop" here
+                meta.pop("umop", None)
+                return ConfInfo(**meta, id=conf_id)
+
+        return DEFAULT_CONFIG_CONF_INFO
+
+    def _save_conf_mapping(
+        self,
+        abconf_path: str,
+        abconf_id: str,
+        abconf_name: str | None = None,
+    ) -> None:
+        """保存配置文件的映射关系"""
+        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] = {
+            "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 = []
+        abconf_mapping = self._get_abconf_data()
+        for uuid_, meta in abconf_mapping.items():
+            if not isinstance(meta, dict):
+                continue
+            meta.pop("umop", None)
+            conf_list.append(ConfInfo(**meta, id=uuid_))
+        conf_list.append(DEFAULT_CONFIG_CONF_INFO)
+        return conf_list
+
+    def create_conf(
+        self,
+        config: dict = DEFAULT_CONFIG,
+        name: str | None = None,
+    ) -> str:
+        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, 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) -> bool:
+        """更新配置文件信息
+
+        Args:
+            conf_id: 配置文件的 UUID
+            name: 新的配置文件名称 (可选)
+
+        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
+
+        # 保存更新
+        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/config/__init__.py

@@ -1,9 +1,9 @@
-from .default import DEFAULT_CONFIG, VERSION, DB_PATH
 from .astrbot_config import *
+from .default import DB_PATH, DEFAULT_CONFIG, VERSION
 
 __all__ = [
+    "DB_PATH",
     "DEFAULT_CONFIG",
     "VERSION",
-    "DB_PATH",
     "AstrBotConfig",
 ]

astrbot/core/config/astrbot_config.py

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

astrbot/core/conversation_mgr.py

@@ -1,56 +1,109 @@
-"""
+"""AstrBot 会话-对话管理器, 维护两个本地存储, 其中一个是 json 格式的shared_preferences, 另外一个是数据库.
-AstrBot 会话-对话管理器, 维护两个本地存储, 其中一个是 json 格式的shared_preferences, 另外一个是数据库
 
 在 AstrBot 中, 会话和对话是独立的, 会话用于标记对话窗口, 例如群聊"123456789"可以建立一个会话,
 在一个会话中可以建立多个对话, 并且支持对话的切换和删除
 """
 
-import uuid
 import json
-import asyncio
+from collections.abc import Awaitable, Callable
+
 from astrbot.core import sp
-from typing import Dict, List
+from astrbot.core.agent.message import AssistantMessageSegment, UserMessageSegment
 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] = {}
-        self.session_conversations: Dict[str, str] = sp.get("session_conversation", {})
         self.db = db_helper
         self.save_interval = 60  # 每 60 秒保存一次
-        self._start_periodic_save()
 
-    def _start_periodic_save(self):
+        # 会话删除回调函数列表（用于级联清理，如知识库配置）
-        """启动定时保存任务"""
+        self._on_session_deleted_callbacks: list[Callable[[str], Awaitable[None]]] = []
-        asyncio.create_task(self._periodic_save())
 
-    async def _periodic_save(self):
+    def register_on_session_deleted(
-        """定时保存会话对话映射关系到存储中"""
+        self,
-        while True:
+        callback: Callable[[str], Awaitable[None]],
-            await asyncio.sleep(self.save_interval)
+    ) -> None:
-            self._save_to_storage()
+        """注册会话删除回调函数.
 
-    def _save_to_storage(self):
+        其他模块可以注册回调来响应会话删除事件，实现级联清理。
-        """保存会话对话映射关系到存储中"""
+        例如：知识库模块可以注册回调来清理会话的知识库配置。
-        sp.put("session_conversation", self.session_conversations)
 
-    async def new_conversation(self, unified_msg_origin: str) -> str:
+        Args:
-        """新建对话，并将当前会话的对话转移到新对话
+            callback: 回调函数，接收会话ID (unified_msg_origin) 作为参数
+
+        """
+        self._on_session_deleted_callbacks.append(callback)
+
+    async def _trigger_session_deleted(self, unified_msg_origin: str) -> None:
+        """触发会话删除回调.
+
+        Args:
+            unified_msg_origin: 会话ID
+
+        """
+        for callback in self._on_session_deleted_callbacks:
+            try:
+                await callback(unified_msg_origin)
+            except Exception as e:
+                from astrbot.core import logger
+
+                logger.error(
+                    f"会话删除回调执行失败 (session: {unified_msg_origin}): {e}",
+                )
+
+    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 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:
             unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
         Returns:
             conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+
         """
-        conversation_id = str(uuid.uuid4())
+        if not platform_id:
-        self.db.new_conversation(user_id=unified_msg_origin, cid=conversation_id)
+            # 如果没有提供 platform_id，则从 unified_msg_origin 中解析
-        self.session_conversations[unified_msg_origin] = conversation_id
+            parts = unified_msg_origin.split(":")
-        sp.put("session_conversation", self.session_conversations)
+            if len(parts) >= 3:
-        return conversation_id
+                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):
         """切换会话的对话
@@ -58,137 +111,294 @@ class ConversationManager:
         Args:
             unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
             conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+
         """
         self.session_conversations[unified_msg_origin] = conversation_id
-        sp.put("session_conversation", self.session_conversations)
+        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 时删除会话当前的对话
 
         Args:
             unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
             conversation_id (str): 对话 ID, 是 uuid 格式的字符串
-        """
-        conversation_id = self.session_conversations.get(unified_msg_origin)
-        if conversation_id:
-            self.db.delete_conversation(user_id=unified_msg_origin, cid=conversation_id)
-            del self.session_conversations[unified_msg_origin]
-            sp.put("session_conversation", self.session_conversations)
 
-    async def get_curr_conversation_id(self, unified_msg_origin: str) -> str:
+        """
+        if not conversation_id:
+            conversation_id = self.session_conversations.get(unified_msg_origin)
+        if conversation_id:
+            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 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")
+
+        # 触发会话删除回调（级联清理）
+        await self._trigger_session_deleted(unified_msg_origin)
+
+    async def get_curr_conversation_id(self, unified_msg_origin: str) -> str | None:
         """获取会话当前的对话 ID
 
         Args:
             unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
         Returns:
             conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+
         """
-        return self.session_conversations.get(unified_msg_origin, None)
+        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
+        self,
-    ) -> Conversation:
+        unified_msg_origin: str,
-        """获取会话的对话
+        conversation_id: str,
+        create_if_not_exists: bool = False,
+    ) -> Conversation | None:
+        """获取会话的对话.
 
         Args:
             unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
             conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+            create_if_not_exists (bool): 如果对话不存在,是否创建一个新的对话
         Returns:
             conversation (Conversation): 对话对象
-        """
-        return self.db.get_conversation_by_user_id(unified_msg_origin, conversation_id)
 
-    async def get_conversations(self, unified_msg_origin: str) -> List[Conversation]:
+        """
-        """获取会话的所有对话
+        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)
+            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 | 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,
+    ) -> None:
+        """更新会话的对话.
 
         Args:
             unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
             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(
+            await self.db.update_conversation(
-                user_id=unified_msg_origin,
                 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,
+    ) -> None:
+        """更新会话的对话标题.
 
         Args:
             unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
             title (str): 对话标题
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+        Deprecated:
+            Use `update_conversation` with `title` parameter instead.
+
         """
-        conversation_id = self.session_conversations.get(unified_msg_origin)
+        await self.update_conversation(
-        if conversation_id:
+            unified_msg_origin=unified_msg_origin,
-            self.db.update_conversation_title(
+            conversation_id=conversation_id,
-                user_id=unified_msg_origin, cid=conversation_id, title=title
+            title=title,
-            )
+        )
 
     async def update_conversation_persona_id(
-        self, unified_msg_origin: str, persona_id: str
+        self,
-    ):
+        unified_msg_origin: str,
-        """更新会话的对话 Persona ID
+        persona_id: str,
+        conversation_id: str | None = None,
+    ) -> None:
+        """更新会话的对话 Persona ID.
 
         Args:
             unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
             persona_id (str): 对话 Persona ID
+            conversation_id (str): 对话 ID, 是 uuid 格式的字符串
+        Deprecated:
+            Use `update_conversation` with `persona_id` parameter instead.
+
         """
-        conversation_id = self.session_conversations.get(unified_msg_origin)
+        await self.update_conversation(
-        if conversation_id:
+            unified_msg_origin=unified_msg_origin,
-            self.db.update_conversation_persona_id(
+            conversation_id=conversation_id,
-                user_id=unified_msg_origin, cid=conversation_id, persona_id=persona_id
+            persona_id=persona_id,
-            )
+        )
+
+    async def add_message_pair(
+        self,
+        cid: str,
+        user_message: UserMessageSegment | dict,
+        assistant_message: AssistantMessageSegment | dict,
+    ) -> None:
+        """Add a user-assistant message pair to the conversation history.
+
+        Args:
+            cid (str): Conversation ID
+            user_message (UserMessageSegment | dict): OpenAI-format user message object or dict
+            assistant_message (AssistantMessageSegment | dict): OpenAI-format assistant message object or dict
+
+        Raises:
+            Exception: If the conversation with the given ID is not found
+        """
+        conv = await self.db.get_conversation_by_id(cid=cid)
+        if not conv:
+            raise Exception(f"Conversation with id {cid} not found")
+        history = conv.content or []
+        if isinstance(user_message, UserMessageSegment):
+            user_msg_dict = user_message.model_dump()
+        else:
+            user_msg_dict = user_message
+        if isinstance(assistant_message, AssistantMessageSegment):
+            assistant_msg_dict = assistant_message.model_dump()
+        else:
+            assistant_msg_dict = assistant_message
+        history.append(user_msg_dict)
+        history.append(assistant_msg_dict)
+        await self.db.update_conversation(
+            cid=cid,
+            content=history,
+        )
 
     async def get_human_readable_context(
-        self, unified_msg_origin, conversation_id, page=1, page_size=10
+        self,
-    ):
+        unified_msg_origin: str,
-        """获取人类可读的上下文
+        conversation_id: str,
+        page: int = 1,
+        page_size: int = 10,
+    ) -> tuple[list[str], int]:
+        """获取人类可读的上下文.
 
         Args:
             unified_msg_origin (str): 统一的消息来源字符串。格式为 platform_name:message_type:session_id
             conversation_id (str): 对话 ID, 是 uuid 格式的字符串
             page (int): 页码
             page_size (int): 每页大小
+
         """
         conversation = await self.get_conversation(unified_msg_origin, conversation_id)
+        if not conversation:
+            return [], 0
         history = json.loads(conversation.history)
 
-        contexts = []
+        # contexts_groups 存放按顺序的段落（每个段落是一个 str 列表），
-        temp_contexts = []
+        # 之后会被展平成一个扁平的 str 列表返回。
+        contexts_groups: list[list[str]] = []
+        temp_contexts: list[str] = []
         for record in history:
             if record["role"] == "user":
                 temp_contexts.append(f"User: {record['content']}")
             elif record["role"] == "assistant":
-                if "content" in record and record["content"]:
+                if record.get("content"):
                     temp_contexts.append(f"Assistant: {record['content']}")
                 elif "tool_calls" in record:
                     tool_calls_str = json.dumps(
-                        record["tool_calls"], ensure_ascii=False
+                        record["tool_calls"],
+                        ensure_ascii=False,
                     )
                     temp_contexts.append(f"Assistant: [函数调用] {tool_calls_str}")
                 else:
                     temp_contexts.append("Assistant: [未知的内容]")
-                contexts.insert(0, temp_contexts)
+                contexts_groups.insert(0, temp_contexts)
                 temp_contexts = []
 
-        # 展平 contexts 列表
+        # 展平分组后的 contexts 列表为单层字符串列表
-        contexts = [item for sublist in contexts for item in sublist]
+        contexts = [item for sublist in contexts_groups for item in sublist]
 
         # 计算分页
         paged_contexts = contexts[(page - 1) * page_size : page * page_size]

astrbot/core/core_lifecycle.py

@@ -1,6 +1,6 @@
-"""
+"""Astrbot 核心生命周期管理类, 负责管理 AstrBot 的启动、停止、重启等操作.
-Astrbot 核心生命周期管理类, 负责管理 AstrBot 的启动、停止、重启等操作。
+
-该类负责初始化各个组件, 包括 ProviderManager、PlatformManager、KnowledgeDBManager、ConversationManager、PluginManager、PipelineScheduler、EventBus等。
+该类负责初始化各个组件, 包括 ProviderManager、PlatformManager、ConversationManager、PluginManager、PipelineScheduler、EventBus等。
 该类还负责加载和执行插件, 以及处理事件总线的分发。
 
 工作流程:
@@ -9,54 +9,74 @@ Astrbot 核心生命周期管理类, 负责管理 AstrBot 的启动、停止、
 3. 执行启动完成事件钩子
 """
 
-import traceback
 import asyncio
-import time
-import threading
 import os
-from .event_bus import EventBus
+import threading
-from . import astrbot_config
+import time
+import traceback
 from asyncio import Queue
-from typing import List
+
-from astrbot.core.pipeline.scheduler import PipelineScheduler, PipelineContext
+from astrbot.core import LogBroker, logger, sp
-from astrbot.core.star import PluginManager
+from astrbot.core.astrbot_config_mgr import AstrBotConfigManager
-from astrbot.core.platform.manager import PlatformManager
-from astrbot.core.star.context import Context
-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.config.default import VERSION
-from astrbot.core.rag.knowledge_db_mgr import KnowledgeDBManager
 from astrbot.core.conversation_mgr import ConversationManager
-from astrbot.core.star.star_handler import star_handlers_registry, EventType
+from astrbot.core.db import BaseDatabase
-from astrbot.core.star.star_handler import star_map
+from astrbot.core.db.migration.migra_45_to_46 import migrate_45_to_46
+from astrbot.core.db.migration.migra_webchat_session import migrate_webchat_session
+from astrbot.core.knowledge_base.kb_mgr import KnowledgeBaseManager
+from astrbot.core.memory.memory_manager import MemoryManager
+from astrbot.core.persona_mgr import PersonaManager
+from astrbot.core.pipeline.scheduler import PipelineContext, PipelineScheduler
+from astrbot.core.platform.manager import PlatformManager
+from astrbot.core.platform_message_history_mgr import PlatformMessageHistoryManager
+from astrbot.core.provider.manager import ProviderManager
+from astrbot.core.star import PluginManager
+from astrbot.core.star.context import Context
+from astrbot.core.star.star_handler import EventType, star_handlers_registry, star_map
+from astrbot.core.umop_config_router import UmopConfigRouter
+from astrbot.core.updator import AstrBotUpdator
+
+from . import astrbot_config, html_renderer
+from .event_bus import EventBus
 
 
 class AstrBotCoreLifecycle:
-    """
+    """AstrBot 核心生命周期管理类, 负责管理 AstrBot 的启动、停止、重启等操作.
-    AstrBot 核心生命周期管理类, 负责管理 AstrBot 的启动、停止、重启等操作。
+
-    该类负责初始化各个组件, 包括 ProviderManager、PlatformManager、KnowledgeDBManager、ConversationManager、PluginManager、PipelineScheduler、
+    该类负责初始化各个组件, 包括 ProviderManager、PlatformManager、ConversationManager、PluginManager、PipelineScheduler、
     EventBus 等。
     该类还负责加载和执行插件, 以及处理事件总线的分发。
     """
 
-    def __init__(self, log_broker: LogBroker, db: BaseDatabase):
+    def __init__(self, log_broker: LogBroker, db: BaseDatabase) -> None:
         self.log_broker = log_broker  # 初始化日志代理
         self.astrbot_config = astrbot_config  # 初始化配置
         self.db = db  # 初始化数据库
 
-        # 根据环境变量设置代理
+        # 设置代理
-        os.environ["https_proxy"] = self.astrbot_config["http_proxy"]
+        proxy_config = self.astrbot_config.get("http_proxy", "")
-        os.environ["http_proxy"] = self.astrbot_config["http_proxy"]
+        if proxy_config != "":
-        os.environ["no_proxy"] = "localhost"
+            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):
+    async def initialize(self) -> None:
-        """
+        """初始化 AstrBot 核心生命周期管理类.
-        初始化 AstrBot 核心生命周期管理类, 负责初始化各个组件, 包括 ProviderManager、PlatformManager、KnowledgeDBManager、ConversationManager、PluginManager、PipelineScheduler、EventBus、AstrBotUpdator等。
-        """
 
+        负责初始化各个组件, 包括 ProviderManager、PlatformManager、ConversationManager、PluginManager、PipelineScheduler、EventBus、AstrBotUpdator等。
+        """
         # 初始化日志代理
         logger.info("AstrBot v" + VERSION)
         if os.environ.get("TESTING", ""):
@@ -64,21 +84,62 @@ class AstrBotCoreLifecycle:
         else:
             logger.setLevel(self.astrbot_config["log_level"])  # 设置日志级别
 
+        await self.db.initialize()
+
+        await html_renderer.initialize()
+
+        # 初始化 UMOP 配置路由器
+        self.umop_config_router = UmopConfigRouter(sp=sp)
+
+        # 初始化 AstrBot 配置管理器
+        self.astrbot_config_mgr = AstrBotConfigManager(
+            default_config=self.astrbot_config,
+            ucr=self.umop_config_router,
+            sp=sp,
+        )
+
+        # 4.5 to 4.6 migration for umop_config_router
+        try:
+            await migrate_45_to_46(self.astrbot_config_mgr, self.umop_config_router)
+        except Exception as e:
+            logger.error(f"Migration from version 4.5 to 4.6 failed: {e!s}")
+            logger.error(traceback.format_exc())
+
+        # migration for webchat session
+        try:
+            await migrate_webchat_session(self.db)
+        except Exception as e:
+            logger.error(f"Migration for webchat session failed: {e!s}")
+            logger.error(traceback.format_exc())
+
         # 初始化事件队列
         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)
 
-        # 初始化知识库管理器
-        self.knowledge_db_manager = KnowledgeDBManager(self.astrbot_config)
-
         # 初始化对话管理器
         self.conversation_manager = ConversationManager(self.db)
 
+        # 初始化平台消息历史管理器
+        self.platform_message_history_manager = PlatformMessageHistoryManager(self.db)
+
+        # 初始化知识库管理器
+        self.kb_manager = KnowledgeBaseManager(self.provider_manager)
+        # 初始化记忆管理器
+        self.memory_manager = MemoryManager()
+
         # 初始化提供给插件的上下文
         self.star_context = Context(
             self.event_queue,
@@ -87,7 +148,11 @@ class AstrBotCoreLifecycle:
             self.provider_manager,
             self.platform_manager,
             self.conversation_manager,
-            self.knowledge_db_manager,
+            self.platform_message_history_manager,
+            self.persona_mgr,
+            self.astrbot_config_mgr,
+            self.kb_manager,
+            self.memory_manager,
         )
 
         # 初始化插件管理器
@@ -99,23 +164,26 @@ class AstrBotCoreLifecycle:
         # 根据配置实例化各个 Provider
         await self.provider_manager.initialize()
 
+        await self.kb_manager.initialize()
+
         # 初始化消息事件流水线调度器
-        self.pipeline_scheduler = PipelineScheduler(
+        self.pipeline_scheduler_mapping = await self.load_pipeline_scheduler()
-            PipelineContext(self.astrbot_config, self.plugin_manager)
-        )
-        await self.pipeline_scheduler.initialize()
 
         # 初始化更新器
-        self.astrbot_updator = AstrBotUpdator(self.astrbot_config["plugin_repo_mirror"])
+        self.astrbot_updator = AstrBotUpdator()
 
         # 初始化事件总线
-        self.event_bus = EventBus(self.event_queue, self.pipeline_scheduler)
+        self.event_bus = EventBus(
+            self.event_queue,
+            self.pipeline_scheduler_mapping,
+            self.astrbot_config_mgr,
+        )
 
         # 记录启动时间
         self.start_time = int(time.time())
 
         # 初始化当前任务列表
-        self.curr_tasks: List[asyncio.Task] = []
+        self.curr_tasks: list[asyncio.Task] = []
 
         # 根据配置实例化各个平台适配器
         await self.platform_manager.initialize()
@@ -123,13 +191,13 @@ class AstrBotCoreLifecycle:
         # 初始化关闭控制面板的事件
         self.dashboard_shutdown_event = asyncio.Event()
 
-    def _load(self):
+    def _load(self) -> None:
-        """加载事件总线和任务并初始化"""
+        """加载事件总线和任务并初始化."""
-
         # 创建一个异步任务来执行事件总线的 dispatch() 方法
         # dispatch是一个无限循环的协程, 从事件队列中获取事件并处理
         event_bus_task = asyncio.create_task(
-            self.event_bus.dispatch(), name="event_bus"
+            self.event_bus.dispatch(),
+            name="event_bus",
         )
 
         # 把插件中注册的所有协程函数注册到事件总线中并执行
@@ -140,16 +208,17 @@ class AstrBotCoreLifecycle:
         tasks_ = [event_bus_task, *extra_tasks]
         for task in tasks_:
             self.curr_tasks.append(
-                asyncio.create_task(self._task_wrapper(task), name=task.get_name())
+                asyncio.create_task(self._task_wrapper(task), name=task.get_name()),
             )
 
         self.start_time = int(time.time())
 
-    async def _task_wrapper(self, task: asyncio.Task):
+    async def _task_wrapper(self, task: asyncio.Task) -> None:
-        """异步任务包装器, 用于处理异步任务执行中出现的各种异常
+        """异步任务包装器, 用于处理异步任务执行中出现的各种异常.
 
         Args:
             task (asyncio.Task): 要执行的异步任务
+
         """
         try:
             await task
@@ -162,19 +231,22 @@ class AstrBotCoreLifecycle:
                 logger.error(f"|    {line}")
             logger.error("-------")
 
-    async def start(self):
+    async def start(self) -> None:
-        """启动 AstrBot 核心生命周期管理类, 用load加载事件总线和任务并初始化, 执行启动完成事件钩子"""
+        """启动 AstrBot 核心生命周期管理类.
+
+        用load加载事件总线和任务并初始化, 执行启动完成事件钩子
+        """
         self._load()
         logger.info("AstrBot 启动完成。")
 
         # 执行启动完成事件钩子
         handlers = star_handlers_registry.get_handlers_by_event_type(
-            EventType.OnAstrBotLoadedEvent
+            EventType.OnAstrBotLoadedEvent,
         )
         for handler in handlers:
             try:
                 logger.info(
-                    f"hook(on_astrbot_loaded) -> {star_map[handler.handler_module_path].name} - {handler.handler_name}"
+                    f"hook(on_astrbot_loaded) -> {star_map[handler.handler_module_path].name} - {handler.handler_name}",
                 )
                 await handler.handler()
             except BaseException:
@@ -183,8 +255,8 @@ class AstrBotCoreLifecycle:
         # 同时运行curr_tasks中的所有任务
         await asyncio.gather(*self.curr_tasks, return_exceptions=True)
 
-    async def stop(self):
+    async def stop(self) -> None:
-        """停止 AstrBot 核心生命周期管理类, 取消所有当前任务并终止各个管理器"""
+        """停止 AstrBot 核心生命周期管理类, 取消所有当前任务并终止各个管理器."""
         # 请求停止所有正在运行的异步任务
         for task in self.curr_tasks:
             task.cancel()
@@ -195,11 +267,12 @@ class AstrBotCoreLifecycle:
             except Exception as e:
                 logger.warning(traceback.format_exc())
                 logger.warning(
-                    f"插件 {plugin.name} 未被正常终止 {e!s}, 可能会导致资源泄露等问题。"
+                    f"插件 {plugin.name} 未被正常终止 {e!s}, 可能会导致资源泄露等问题。",
                 )
 
         await self.provider_manager.terminate()
         await self.platform_manager.terminate()
+        await self.kb_manager.terminate()
         self.dashboard_shutdown_event.set()
 
         # 再次遍历curr_tasks等待每个任务真正结束
@@ -211,21 +284,59 @@ class AstrBotCoreLifecycle:
             except Exception as e:
                 logger.error(f"任务 {task.get_name()} 发生错误: {e}")
 
-    async def restart(self):
+    async def restart(self) -> None:
         """重启 AstrBot 核心生命周期管理类, 终止各个管理器并重新加载平台实例"""
         await self.provider_manager.terminate()
         await self.platform_manager.terminate()
+        await self.kb_manager.terminate()
         self.dashboard_shutdown_event.set()
         threading.Thread(
-            target=self.astrbot_updator._reboot, name="restart", daemon=True
+            target=self.astrbot_updator._reboot,
+            name="restart",
+            daemon=True,
         ).start()
 
-    def load_platform(self) -> List[asyncio.Task]:
+    def load_platform(self) -> list[asyncio.Task]:
         """加载平台实例并返回所有平台实例的异步任务列表"""
         tasks = []
         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) -> None:
+        """重新加载消息事件流水线调度器.
+
+        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,161 +1,364 @@
 import abc
+import datetime
+import typing as T
+from contextlib import asynccontextmanager
 from dataclasses import dataclass
-from typing import List, Dict, Any, Tuple
+
-from astrbot.core.db.po import Stats, LLMHistory, ATRIVision, Conversation
+from deprecated import deprecated
+from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
+from sqlalchemy.orm import sessionmaker
+
+from astrbot.core.db.po import (
+    Attachment,
+    ConversationV2,
+    Persona,
+    PlatformMessageHistory,
+    PlatformSession,
+    PlatformStat,
+    Preference,
+    Stats,
+)
 
 
 @dataclass
 class BaseDatabase(abc.ABC):
-    """
+    """数据库基类"""
-    数据库基类
+
-    """
+    DATABASE_URL = ""
 
     def __init__(self) -> None:
-        pass
+        self.engine = create_async_engine(
+            self.DATABASE_URL,
+            echo=False,
+            future=True,
+        )
+        self.AsyncSessionLocal = sessionmaker(
+            self.engine,
+            class_=AsyncSession,
+            expire_on_commit=False,
+        )
 
-    def insert_base_metrics(self, metrics: dict):
+    async def initialize(self):
-        """插入基础指标数据"""
+        """初始化数据库连接"""
-        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
+    @asynccontextmanager
-    def insert_platform_metrics(self, metrics: dict):
+    async def get_db(self) -> T.AsyncGenerator[AsyncSession, None]:
-        """插入平台指标数据"""
+        """Get a database session."""
-        raise NotImplementedError
+        if not self.inited:
-
+            await self.initialize()
-    @abc.abstractmethod
+            self.inited = True
-    def insert_plugin_metrics(self, metrics: dict):
+        async with self.AsyncSessionLocal() as session:
-        """插入插件指标数据"""
+            yield session
-        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
 
+    @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
+    # New methods in v4.0.0
-    def insert_atri_vision_data(self, vision_data: ATRIVision):
-        """插入 ATRI 视觉数据"""
-        raise NotImplementedError
 
     @abc.abstractmethod
-    def get_atri_vision_data(self) -> List[ATRIVision]:
+    async def insert_platform_stats(
-        """获取 ATRI 视觉数据"""
+        self,
-        raise NotImplementedError
+        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(
+    async def count_platform_stats(self) -> int:
-        self, url_or_path: str, id: str
+        """Count the number of platform statistics records."""
-    ) -> ATRIVision:
+        ...
-        """通过 url 或 path 获取 ATRI 视觉数据"""
-        raise NotImplementedError
 
     @abc.abstractmethod
-    def get_conversation_by_user_id(self, user_id: str, cid: str) -> Conversation:
+    async def get_platform_stats(self, offset_sec: int = 86400) -> list[PlatformStat]:
-        """通过 user_id 和 cid 获取 Conversation"""
+        """Get platform statistics within the specified offset in seconds and group by platform_id."""
-        raise NotImplementedError
+        ...
 
     @abc.abstractmethod
-    def new_conversation(self, user_id: str, cid: str):
+    async def get_conversations(
-        """新建 Conversation"""
+        self,
-        raise NotImplementedError
+        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
+        content is not included in the result.
-    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]: 返回一个元组，包含对话列表和总对话数
         """
-        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,
-        platforms: List[str] = None,
+    ) -> list[ConversationV2]:
-        message_types: List[str] = None,
+        """Get all conversations with pagination."""
-        search_query: str = None,
+        ...
-        exclude_ids: List[str] = None,
-        exclude_platforms: List[str] = None,
-    ) -> Tuple[List[Dict[str, Any]], int]:
-        """获取筛选后的对话列表
 
-        Args:
+    @abc.abstractmethod
-            page: 页码
+    async def get_filtered_conversations(
-            page_size: 每页数量
+        self,
-            platforms: 平台筛选列表
+        page: int = 1,
-            message_types: 消息类型筛选列表
+        page_size: int = 20,
-            search_query: 搜索关键词
+        platform_ids: list[str] | None = None,
-            exclude_ids: 排除的用户ID列表
+        search_query: str = "",
-            exclude_platforms: 排除的平台列表
+        **kwargs,
+    ) -> tuple[list[ConversationV2], int]:
+        """Get conversations filtered by platform IDs and search query."""
+        ...
 
-        Returns:
+    @abc.abstractmethod
-            Tuple[List[Dict[str, Any]], int]: 返回一个元组，包含对话列表和总对话数
+    async def create_conversation(
-        """
+        self,
-        raise NotImplementedError
+        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."""
+        ...
+
+    @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 newer 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."""
+        ...
+
+    # ====
+    # Platform Session Management
+    # ====
+
+    @abc.abstractmethod
+    async def create_platform_session(
+        self,
+        creator: str,
+        platform_id: str = "webchat",
+        session_id: str | None = None,
+        display_name: str | None = None,
+        is_group: int = 0,
+    ) -> PlatformSession:
+        """Create a new Platform session."""
+        ...
+
+    @abc.abstractmethod
+    async def get_platform_session_by_id(
+        self, session_id: str
+    ) -> PlatformSession | None:
+        """Get a Platform session by its ID."""
+        ...
+
+    @abc.abstractmethod
+    async def get_platform_sessions_by_creator(
+        self,
+        creator: str,
+        platform_id: str | None = None,
+        page: int = 1,
+        page_size: int = 20,
+    ) -> list[PlatformSession]:
+        """Get all Platform sessions for a specific creator (username) and optionally platform."""
+        ...
+
+    @abc.abstractmethod
+    async def update_platform_session(
+        self,
+        session_id: str,
+        display_name: str | None = None,
+    ) -> None:
+        """Update a Platform session's updated_at timestamp and optionally display_name."""
+        ...
+
+    @abc.abstractmethod
+    async def delete_platform_session(self, session_id: str) -> None:
+        """Delete a Platform session by its ID."""
+        ...

astrbot/core/db/migration/helper.py

@@ -0,0 +1,69 @@
+import os
+
+from astrbot.api import logger, sp
+from astrbot.core.config import AstrBotConfig
+from astrbot.core.db import BaseDatabase
+from astrbot.core.utils.astrbot_path import get_astrbot_data_path
+
+from .migra_3_to_4 import (
+    migration_conversation_table,
+    migration_persona_data,
+    migration_platform_table,
+    migration_preferences,
+    migration_webchat_data,
+)
+
+
+async def check_migration_needed_v4(db_helper: BaseDatabase) -> bool:
+    """检查是否需要进行数据库迁移
+    如果存在 data_v3.db 并且 preference 中没有 migration_done_v4，则需要进行迁移。
+    """
+    # 仅当 data 目录下存在旧版本数据（data_v3.db 文件）时才考虑迁移
+    data_dir = get_astrbot_data_path()
+    data_v3_db = os.path.join(data_dir, "data_v3.db")
+
+    if not os.path.exists(data_v3_db):
+        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,
+) -> None:
+    """执行数据库迁移
+    迁移旧的 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,357 @@
+import datetime
+import json
+
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from astrbot.api import logger, sp
+from astrbot.core.config import AstrBotConfig
+from astrbot.core.config.default import DB_PATH
+from astrbot.core.db.po import ConversationV2, PlatformMessageHistory
+from astrbot.core.platform.astr_message_event import MessageSesion
+
+from .. import BaseDatabase
+from .shared_preferences_v3 import sp as sp_v3
+from .sqlite_v3 import SQLiteDatabase as SQLiteV3DatabaseV3
+
+"""
+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", [])
+            parts = []
+            user_turn = True
+            for mood_dialog in mood_imitation_dialogs:
+                if user_turn:
+                    parts.append(f"A: {mood_dialog}\n")
+                else:
+                    parts.append(f"B: {mood_dialog}\n")
+                user_turn = not user_turn
+            mood_prompt = "".join(parts)
+            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/migra_45_to_46.py

@@ -0,0 +1,44 @@
+from astrbot.api import logger, sp
+from astrbot.core.astrbot_config_mgr import AstrBotConfigManager
+from astrbot.core.umop_config_router import UmopConfigRouter
+
+
+async def migrate_45_to_46(acm: AstrBotConfigManager, ucr: UmopConfigRouter):
+    abconf_data = acm.abconf_data
+
+    if not isinstance(abconf_data, dict):
+        # should be unreachable
+        logger.warning(
+            f"migrate_45_to_46: abconf_data is not a dict (type={type(abconf_data)}). Value: {abconf_data!r}",
+        )
+        return
+
+    # 如果任何一项带有 umop，则说明需要迁移
+    need_migration = False
+    for conf_id, conf_info in abconf_data.items():
+        if isinstance(conf_info, dict) and "umop" in conf_info:
+            need_migration = True
+            break
+
+    if not need_migration:
+        return
+
+    logger.info("Starting migration from version 4.5 to 4.6")
+
+    # extract umo->conf_id mapping
+    umo_to_conf_id = {}
+    for conf_id, conf_info in abconf_data.items():
+        if isinstance(conf_info, dict) and "umop" in conf_info:
+            umop_ls = conf_info.pop("umop")
+            if not isinstance(umop_ls, list):
+                continue
+            for umo in umop_ls:
+                if isinstance(umo, str) and umo not in umo_to_conf_id:
+                    umo_to_conf_id[umo] = conf_id
+
+    # update the abconf data
+    await sp.global_put("abconf_mapping", abconf_data)
+    # update the umop config router
+    await ucr.update_routing_data(umo_to_conf_id)
+
+    logger.info("Migration from version 45 to 46 completed successfully")

astrbot/core/db/migration/migra_webchat_session.py

@@ -0,0 +1,131 @@
+"""Migration script for WebChat sessions.
+
+This migration creates PlatformSession from existing platform_message_history records.
+
+Changes:
+- Creates platform_sessions table
+- Adds platform_id field (default: 'webchat')
+- Adds display_name field
+- Session_id format: {platform_id}_{uuid}
+"""
+
+from sqlalchemy import func, select
+from sqlmodel import col
+
+from astrbot.api import logger, sp
+from astrbot.core.db import BaseDatabase
+from astrbot.core.db.po import ConversationV2, PlatformMessageHistory, PlatformSession
+
+
+async def migrate_webchat_session(db_helper: BaseDatabase):
+    """Create PlatformSession records from platform_message_history.
+
+    This migration extracts all unique user_ids from platform_message_history
+    where platform_id='webchat' and creates corresponding PlatformSession records.
+    """
+    # 检查是否已经完成迁移
+    migration_done = await db_helper.get_preference(
+        "global", "global", "migration_done_webchat_session"
+    )
+    if migration_done:
+        return
+
+    logger.info("开始执行数据库迁移（WebChat 会话迁移）...")
+
+    try:
+        async with db_helper.get_db() as session:
+            # 从 platform_message_history 创建 PlatformSession
+            query = (
+                select(
+                    col(PlatformMessageHistory.user_id),
+                    col(PlatformMessageHistory.sender_name),
+                    func.min(PlatformMessageHistory.created_at).label("earliest"),
+                    func.max(PlatformMessageHistory.updated_at).label("latest"),
+                )
+                .where(col(PlatformMessageHistory.platform_id) == "webchat")
+                .where(col(PlatformMessageHistory.sender_id) == "astrbot")
+                .group_by(col(PlatformMessageHistory.user_id))
+            )
+
+            result = await session.execute(query)
+            webchat_users = result.all()
+
+            if not webchat_users:
+                logger.info("没有找到需要迁移的 WebChat 数据")
+                await sp.put_async(
+                    "global", "global", "migration_done_webchat_session", True
+                )
+                return
+
+            logger.info(f"找到 {len(webchat_users)} 个 WebChat 会话需要迁移")
+
+            # 检查已存在的会话
+            existing_query = select(col(PlatformSession.session_id))
+            existing_result = await session.execute(existing_query)
+            existing_session_ids = {row[0] for row in existing_result.fetchall()}
+
+            # 查询 Conversations 表中的 title，用于设置 display_name
+            # 对于每个 user_id，对应的 conversation user_id 格式为: webchat:FriendMessage:webchat!astrbot!{user_id}
+            user_ids_to_query = [
+                f"webchat:FriendMessage:webchat!astrbot!{user_id}"
+                for user_id, _, _, _ in webchat_users
+            ]
+            conv_query = select(
+                col(ConversationV2.user_id), col(ConversationV2.title)
+            ).where(col(ConversationV2.user_id).in_(user_ids_to_query))
+            conv_result = await session.execute(conv_query)
+            # 创建 user_id -> title 的映射字典
+            title_map = {
+                user_id.replace("webchat:FriendMessage:webchat!astrbot!", ""): title
+                for user_id, title in conv_result.fetchall()
+            }
+
+            # 批量创建 PlatformSession 记录
+            sessions_to_add = []
+            skipped_count = 0
+
+            for user_id, sender_name, created_at, updated_at in webchat_users:
+                # user_id 就是 webchat_conv_id (session_id)
+                session_id = user_id
+
+                # sender_name 通常是 username，但可能为 None
+                creator = sender_name if sender_name else "guest"
+
+                # 检查是否已经存在该会话
+                if session_id in existing_session_ids:
+                    logger.debug(f"会话 {session_id} 已存在，跳过")
+                    skipped_count += 1
+                    continue
+
+                # 从 Conversations 表中获取 display_name
+                display_name = title_map.get(user_id)
+
+                # 创建新的 PlatformSession（保留原有的时间戳）
+                new_session = PlatformSession(
+                    session_id=session_id,
+                    platform_id="webchat",
+                    creator=creator,
+                    is_group=0,
+                    created_at=created_at,
+                    updated_at=updated_at,
+                    display_name=display_name,
+                )
+                sessions_to_add.append(new_session)
+
+            # 批量插入
+            if sessions_to_add:
+                session.add_all(sessions_to_add)
+                await session.commit()
+
+                logger.info(
+                    f"WebChat 会话迁移完成！成功迁移: {len(sessions_to_add)}, 跳过: {skipped_count}",
+                )
+            else:
+                logger.info("没有新会话需要迁移")
+
+        # 标记迁移完成
+        await sp.put_async("global", "global", "migration_done_webchat_session", True)
+
+    except Exception as e:
+        logger.error(f"迁移过程中发生错误: {e}", exc_info=True)
+        raise

astrbot/core/db/migration/shared_preferences_v3.py

@@ -0,0 +1,48 @@
+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) 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,497 @@
+import sqlite3
+import time
+from dataclasses import dataclass
+from typing import Any
+
+from astrbot.core.db.po import Platform, Stats
+
+
+@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 None
+
+        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 = None,
+        message_types: list[str] | None = None,
+        search_query: str | None = None,
+        exclude_ids: list[str] | None = None,
+        exclude_platforms: list[str] | None = 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/plugin/sqlite_impl.py

@@ -1,112 +0,0 @@
-import json
-import aiosqlite
-import os
-from typing import Any
-from .plugin_storage import PluginStorage
-
-DBPATH = "data/plugin_data/sqlite/plugin_data.db"
-
-
-class SQLitePluginStorage(PluginStorage):
-    """插件数据的 SQLite 存储实现类。
-
-    该类提供异步方式将插件数据存储到 SQLite 数据库中，支持数据的增删改查操作。
-    所有数据以 (plugin, key) 作为复合主键进行索引。
-    """
-
-    _instance = None  # Standalone instance of the class
-    _db_conn = None
-    db_path = None
-
-    def __new__(cls):
-        """
-        创建或获取 SQLitePluginStorage 的单例实例。
-        如果实例已存在，则返回现有实例；否则创建一个新实例。
-        数据在 `data/plugin_data/sqlite/plugin_data.db` 下。
-        """
-        os.makedirs(os.path.dirname(DBPATH), exist_ok=True)
-        if cls._instance is None:
-            cls._instance = super(SQLitePluginStorage, cls).__new__(cls)
-            cls._instance.db_path = DBPATH
-        return cls._instance
-
-    async def _init_db(self):
-        """初始化数据库连接（只执行一次）"""
-        if SQLitePluginStorage._db_conn is None:
-            SQLitePluginStorage._db_conn = await aiosqlite.connect(self.db_path)
-            await self._setup_db()
-
-    async def _setup_db(self):
-        """
-        异步初始化数据库。
-
-        创建插件数据表，如果表不存在则创建，表结构包含 plugin、key 和 value 字段，
-        其中 plugin 和 key 组合作为主键。
-        """
-        await self._db_conn.execute("""
-            CREATE TABLE IF NOT EXISTS plugin_data (
-                plugin TEXT,
-                key TEXT,
-                value TEXT,
-                PRIMARY KEY (plugin, key)
-            )
-        """)
-        await self._db_conn.commit()
-
-    async def set(self, plugin: str, key: str, value: Any):
-        """
-        异步存储数据。
-
-        将指定插件的键值对存入数据库，如果键已存在则更新值。
-        值会被序列化为 JSON 字符串后存储。
-
-        Args:
-            plugin: 插件标识符
-            key: 数据键名
-            value: 要存储的数据值（任意类型，将被 JSON 序列化）
-        """
-        await self._init_db()
-        await self._db_conn.execute(
-            "INSERT INTO plugin_data (plugin, key, value) VALUES (?, ?, ?) "
-            "ON CONFLICT(plugin, key) DO UPDATE SET value = excluded.value",
-            (plugin, key, json.dumps(value)),
-        )
-        await self._db_conn.commit()
-
-    async def get(self, plugin: str, key: str) -> Any:
-        """
-        异步获取数据。
-
-        从数据库中获取指定插件和键名对应的值，
-        返回的值会从 JSON 字符串反序列化为原始数据类型。
-
-        Args:
-            plugin: 插件标识符
-            key: 数据键名
-
-        Returns:
-            Any: 存储的数据值，如果未找到则返回 None
-        """
-        await self._init_db()
-        async with self._db_conn.execute(
-            "SELECT value FROM plugin_data WHERE plugin = ? AND key = ?",
-            (plugin, key),
-        ) as cursor:
-            row = await cursor.fetchone()
-            return json.loads(row[0]) if row else None
-
-    async def delete(self, plugin: str, key: str):
-        """
-        异步删除数据。
-
-        从数据库中删除指定插件和键名对应的数据项。
-
-        Args:
-            plugin: 插件标识符
-            key: 要删除的数据键名
-        """
-        await self._init_db()
-        await self._db_conn.execute(
-            "DELETE FROM plugin_data WHERE plugin = ? AND key = ?", (plugin, key)
-        )
-        await self._db_conn.commit()

astrbot/core/db/po.py

@@ -1,7 +1,282 @@
-"""指标数据"""
+import uuid
-
 from dataclasses import dataclass, field
-from typing import List
+from datetime import datetime, timezone
+from typing import TypedDict
+
+from sqlmodel import JSON, Field, SQLModel, Text, UniqueConstraint
+
+
+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"  # type: ignore
+
+    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"  # type: ignore
+
+    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: list | None = 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: str | None = Field(default=None, max_length=255)
+    persona_id: str | None = 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"  # type: ignore
+
+    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: list | None = Field(default=None, sa_type=JSON)
+    """a list of strings, each representing a dialog to start with"""
+    tools: list | None = 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"  # type: ignore
+
+    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"  # type: ignore
+
+    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: str | None = Field(default=None)  # ID of the sender in the platform
+    sender_name: str | None = 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 PlatformSession(SQLModel, table=True):
+    """Platform session table for managing user sessions across different platforms.
+
+    A session represents a chat window for a specific user on a specific platform.
+    Each session can have multiple conversations (对话) associated with it.
+    """
+
+    __tablename__ = "platform_sessions"  # type: ignore
+
+    inner_id: int | None = Field(
+        primary_key=True,
+        sa_column_kwargs={"autoincrement": True},
+        default=None,
+    )
+    session_id: str = Field(
+        max_length=100,
+        nullable=False,
+        unique=True,
+        default_factory=lambda: f"webchat_{uuid.uuid4()}",
+    )
+    platform_id: str = Field(default="webchat", nullable=False)
+    """Platform identifier (e.g., 'webchat', 'qq', 'discord')"""
+    creator: str = Field(nullable=False)
+    """Username of the session creator"""
+    display_name: str | None = Field(default=None, max_length=255)
+    """Display name for the session"""
+    is_group: int = Field(default=0, nullable=False)
+    """0 for private chat, 1 for group chat (not implemented yet)"""
+    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(
+            "session_id",
+            name="uix_platform_session_id",
+        ),
+    )
+
+
+class Attachment(SQLModel, table=True):
+    """This class represents attachments for messages in AstrBot.
+
+    Attachments can be images, files, or other media types.
+    """
+
+    __tablename__ = "attachments"  # type: ignore
+
+    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 +288,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)
+    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 = ""

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/base.py

@@ -0,0 +1,82 @@
+import abc
+from dataclasses import dataclass
+from typing import TypedDict
+
+
+@dataclass
+class Result:
+    class ResultData(TypedDict):
+        id: str
+        doc_id: str
+        text: str
+        metadata: str
+        created_at: int
+        updated_at: int
+
+    similarity: float
+    data: ResultData | dict
+
+
+class BaseVecDB:
+    async def initialize(self):
+        """初始化向量数据库"""
+
+    @abc.abstractmethod
+    async def insert(
+        self,
+        content: str,
+        metadata: dict | None = None,
+        id: str | None = None,
+    ) -> int:
+        """插入一条文本和其对应向量，自动生成 ID 并保持一致性。"""
+        ...
+
+    @abc.abstractmethod
+    async def insert_batch(
+        self,
+        contents: list[str],
+        metadatas: list[dict] | None = None,
+        ids: list[str] | None = None,
+        batch_size: int = 32,
+        tasks_limit: int = 3,
+        max_retries: int = 3,
+        progress_callback=None,
+    ) -> int:
+        """批量插入文本和其对应向量，自动生成 ID 并保持一致性。
+
+        Args:
+            progress_callback: 进度回调函数，接收参数 (current, total)
+
+        """
+        ...
+
+    @abc.abstractmethod
+    async def retrieve(
+        self,
+        query: str,
+        top_k: int = 5,
+        fetch_k: int = 20,
+        rerank: bool = False,
+        metadata_filters: dict | None = None,
+    ) -> list[Result]:
+        """搜索最相似的文档。
+        Args:
+            query (str): 查询文本
+            top_k (int): 返回的最相似文档的数量
+        Returns:
+            List[Result]: 查询结果
+        """
+        ...
+
+    @abc.abstractmethod
+    async def delete(self, doc_id: str) -> bool:
+        """删除指定文档。
+        Args:
+            doc_id (str): 要删除的文档 ID
+        Returns:
+            bool: 删除是否成功
+        """
+        ...
+
+    @abc.abstractmethod
+    async def close(self): ...

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

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

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

@@ -0,0 +1,392 @@
+import json
+import os
+from contextlib import asynccontextmanager
+from datetime import datetime
+
+from sqlalchemy import Column, Text
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, create_async_engine
+from sqlalchemy.orm import sessionmaker
+from sqlmodel import Field, MetaData, SQLModel, col, func, select, text
+
+from astrbot.core import logger
+
+
+class BaseDocModel(SQLModel, table=False):
+    metadata = MetaData()
+
+
+class Document(BaseDocModel, table=True):
+    """SQLModel for documents table."""
+
+    __tablename__ = "documents"  # type: ignore
+
+    id: int | None = Field(
+        default=None,
+        primary_key=True,
+        sa_column_kwargs={"autoincrement": True},
+    )
+    doc_id: str = Field(nullable=False)
+    text: str = Field(nullable=False)
+    metadata_: str | None = Field(default=None, sa_column=Column("metadata", Text))
+    created_at: datetime | None = Field(default=None)
+    updated_at: datetime | None = Field(default=None)
+
+
+class DocumentStorage:
+    def __init__(self, db_path: str):
+        self.db_path = db_path
+        self.DATABASE_URL = f"sqlite+aiosqlite:///{db_path}"
+        self.engine: AsyncEngine | None = None
+        self.async_session_maker: sessionmaker | None = None
+        self.sqlite_init_path = os.path.join(
+            os.path.dirname(__file__),
+            "sqlite_init.sql",
+        )
+
+    async def initialize(self):
+        """Initialize the SQLite database and create the documents table if it doesn't exist."""
+        await self.connect()
+        async with self.engine.begin() as conn:  # type: ignore
+            # Create tables using SQLModel
+            await conn.run_sync(BaseDocModel.metadata.create_all)
+
+            try:
+                await conn.execute(
+                    text(
+                        "ALTER TABLE documents ADD COLUMN kb_doc_id TEXT "
+                        "GENERATED ALWAYS AS (json_extract(metadata, '$.kb_doc_id')) STORED",
+                    ),
+                )
+                await conn.execute(
+                    text(
+                        "ALTER TABLE documents ADD COLUMN user_id TEXT "
+                        "GENERATED ALWAYS AS (json_extract(metadata, '$.user_id')) STORED",
+                    ),
+                )
+
+                # Create indexes
+                await conn.execute(
+                    text(
+                        "CREATE INDEX IF NOT EXISTS idx_documents_kb_doc_id ON documents(kb_doc_id)",
+                    ),
+                )
+                await conn.execute(
+                    text(
+                        "CREATE INDEX IF NOT EXISTS idx_documents_user_id ON documents(user_id)",
+                    ),
+                )
+            except BaseException:
+                pass
+
+            await conn.commit()
+
+    async def connect(self):
+        """Connect to the SQLite database."""
+        if self.engine is None:
+            self.engine = create_async_engine(
+                self.DATABASE_URL,
+                echo=False,
+                future=True,
+            )
+            self.async_session_maker = sessionmaker(
+                self.engine,  # type: ignore
+                class_=AsyncSession,
+                expire_on_commit=False,
+            )  # type: ignore
+
+    @asynccontextmanager
+    async def get_session(self):
+        """Context manager for database sessions."""
+        async with self.async_session_maker() as session:  # type: ignore
+            yield session
+
+    async def get_documents(
+        self,
+        metadata_filters: dict,
+        ids: list | None = None,
+        offset: int | None = 0,
+        limit: int | None = 100,
+    ) -> list[dict]:
+        """Retrieve documents by metadata filters and ids.
+
+        Args:
+            metadata_filters (dict): The metadata filters to apply.
+            ids (list | None): Optional list of document IDs to filter.
+            offset (int | None): Offset for pagination.
+            limit (int | None): Limit for pagination.
+
+        Returns:
+            list: The list of documents that match the filters.
+
+        """
+        if self.engine is None:
+            logger.warning(
+                "Database connection is not initialized, returning empty result",
+            )
+            return []
+
+        async with self.get_session() as session:
+            query = select(Document)
+
+            for key, val in metadata_filters.items():
+                query = query.where(
+                    text(f"json_extract(metadata, '$.{key}') = :filter_{key}"),
+                ).params(**{f"filter_{key}": val})
+
+            if ids is not None and len(ids) > 0:
+                valid_ids = [int(i) for i in ids if i != -1]
+                if valid_ids:
+                    query = query.where(col(Document.id).in_(valid_ids))
+
+            if limit is not None:
+                query = query.limit(limit)
+            if offset is not None:
+                query = query.offset(offset)
+
+            result = await session.execute(query)
+            documents = result.scalars().all()
+
+            return [self._document_to_dict(doc) for doc in documents]
+
+    async def insert_document(self, doc_id: str, text: str, metadata: dict) -> int:
+        """Insert a single document and return its integer ID.
+
+        Args:
+            doc_id (str): The document ID (UUID string).
+            text (str): The document text.
+            metadata (dict): The document metadata.
+
+        Returns:
+            int: The integer ID of the inserted document.
+
+        """
+        assert self.engine is not None, "Database connection is not initialized."
+
+        async with self.get_session() as session, session.begin():
+            document = Document(
+                doc_id=doc_id,
+                text=text,
+                metadata_=json.dumps(metadata),
+                created_at=datetime.now(),
+                updated_at=datetime.now(),
+            )
+            session.add(document)
+            await session.flush()  # Flush to get the ID
+            return document.id  # type: ignore
+
+    async def insert_documents_batch(
+        self,
+        doc_ids: list[str],
+        texts: list[str],
+        metadatas: list[dict],
+    ) -> list[int]:
+        """Batch insert documents and return their integer IDs.
+
+        Args:
+            doc_ids (list[str]): List of document IDs (UUID strings).
+            texts (list[str]): List of document texts.
+            metadatas (list[dict]): List of document metadata.
+
+        Returns:
+            list[int]: List of integer IDs of the inserted documents.
+
+        """
+        assert self.engine is not None, "Database connection is not initialized."
+
+        async with self.get_session() as session, session.begin():
+            import json
+
+            documents = []
+            for doc_id, text, metadata in zip(doc_ids, texts, metadatas):
+                document = Document(
+                    doc_id=doc_id,
+                    text=text,
+                    metadata_=json.dumps(metadata),
+                    created_at=datetime.now(),
+                    updated_at=datetime.now(),
+                )
+                documents.append(document)
+                session.add(document)
+
+            await session.flush()  # Flush to get all IDs
+            return [doc.id for doc in documents]  # type: ignore
+
+    async def delete_document_by_doc_id(self, doc_id: str):
+        """Delete a document by its doc_id.
+
+        Args:
+            doc_id (str): The doc_id of the document to delete.
+
+        """
+        assert self.engine is not None, "Database connection is not initialized."
+
+        async with self.get_session() as session, session.begin():
+            query = select(Document).where(col(Document.doc_id) == doc_id)
+            result = await session.execute(query)
+            document = result.scalar_one_or_none()
+
+            if document:
+                await session.delete(document)
+
+    async def get_document_by_doc_id(self, doc_id: str):
+        """Retrieve a document by its doc_id.
+
+        Args:
+            doc_id (str): The doc_id of the document to retrieve.
+
+        Returns:
+            dict: The document data or None if not found.
+
+        """
+        assert self.engine is not None, "Database connection is not initialized."
+
+        async with self.get_session() as session:
+            query = select(Document).where(col(Document.doc_id) == doc_id)
+            result = await session.execute(query)
+            document = result.scalar_one_or_none()
+
+            if document:
+                return self._document_to_dict(document)
+            return None
+
+    async def update_document_by_doc_id(self, doc_id: str, new_text: str):
+        """Update a document by its doc_id.
+
+        Args:
+            doc_id (str): The doc_id.
+            new_text (str): The new text to update the document with.
+
+        """
+        assert self.engine is not None, "Database connection is not initialized."
+
+        async with self.get_session() as session, session.begin():
+            query = select(Document).where(col(Document.doc_id) == doc_id)
+            result = await session.execute(query)
+            document = result.scalar_one_or_none()
+
+            if document:
+                document.text = new_text
+                document.updated_at = datetime.now()
+                session.add(document)
+
+    async def delete_documents(self, metadata_filters: dict):
+        """Delete documents by their metadata filters.
+
+        Args:
+            metadata_filters (dict): The metadata filters to apply.
+
+        """
+        if self.engine is None:
+            logger.warning(
+                "Database connection is not initialized, skipping delete operation",
+            )
+            return
+
+        async with self.get_session() as session, session.begin():
+            query = select(Document)
+
+            for key, val in metadata_filters.items():
+                query = query.where(
+                    text(f"json_extract(metadata, '$.{key}') = :filter_{key}"),
+                ).params(**{f"filter_{key}": val})
+
+            result = await session.execute(query)
+            documents = result.scalars().all()
+
+            for doc in documents:
+                await session.delete(doc)
+
+    async def count_documents(self, metadata_filters: dict | None = None) -> int:
+        """Count documents in the database.
+
+        Args:
+            metadata_filters (dict | None): Metadata filters to apply.
+
+        Returns:
+            int: The count of documents.
+
+        """
+        if self.engine is None:
+            logger.warning("Database connection is not initialized, returning 0")
+            return 0
+
+        async with self.get_session() as session:
+            query = select(func.count(col(Document.id)))
+
+            if metadata_filters:
+                for key, val in metadata_filters.items():
+                    query = query.where(
+                        text(f"json_extract(metadata, '$.{key}') = :filter_{key}"),
+                    ).params(**{f"filter_{key}": val})
+
+            result = await session.execute(query)
+            count = result.scalar_one_or_none()
+            return count if count is not None else 0
+
+    async def get_user_ids(self) -> list[str]:
+        """Retrieve all user IDs from the documents table.
+
+        Returns:
+            list: A list of user IDs.
+
+        """
+        assert self.engine is not None, "Database connection is not initialized."
+
+        async with self.get_session() as session:
+            query = text(
+                "SELECT DISTINCT user_id FROM documents WHERE user_id IS NOT NULL",
+            )
+            result = await session.execute(query)
+            rows = result.fetchall()
+            return [row[0] for row in rows]
+
+    def _document_to_dict(self, document: Document) -> dict:
+        """Convert a Document model to a dictionary.
+
+        Args:
+            document (Document): The document to convert.
+
+        Returns:
+            dict: The converted dictionary.
+
+        """
+        return {
+            "id": document.id,
+            "doc_id": document.doc_id,
+            "text": document.text,
+            "metadata": document.metadata_,
+            "created_at": document.created_at.isoformat()
+            if isinstance(document.created_at, datetime)
+            else document.created_at,
+            "updated_at": document.updated_at.isoformat()
+            if isinstance(document.updated_at, datetime)
+            else document.updated_at,
+        }
+
+    async def tuple_to_dict(self, row):
+        """Convert a tuple to a dictionary.
+
+        Args:
+            row (tuple): The row to convert.
+
+        Returns:
+            dict: The converted dictionary.
+
+        Note: This method is kept for backward compatibility but is no longer used internally.
+
+        """
+        return {
+            "id": row[0],
+            "doc_id": row[1],
+            "text": row[2],
+            "metadata": row[3],
+            "created_at": row[4],
+            "updated_at": row[5],
+        }
+
+    async def close(self):
+        """Close the connection to the SQLite database."""
+        if self.engine:
+            await self.engine.dispose()
+            self.engine = None
+            self.async_session_maker = None

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

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

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

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

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

@@ -0,0 +1,204 @@
+import time
+import uuid
+
+import numpy as np
+
+from astrbot import logger
+from astrbot.core.provider.provider import EmbeddingProvider, RerankProvider
+
+from ..base import BaseVecDB, Result
+from .document_storage import DocumentStorage
+from .embedding_storage import EmbeddingStorage
+
+
+class FaissVecDB(BaseVecDB):
+    """A class to represent a vector database."""
+
+    def __init__(
+        self,
+        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
+        self.embedding_provider = embedding_provider
+        self.document_storage = DocumentStorage(doc_store_path)
+        self.embedding_storage = EmbeddingStorage(
+            embedding_provider.get_dim(),
+            index_store_path,
+        )
+        self.embedding_provider = embedding_provider
+        self.rerank_provider = rerank_provider
+
+    async def initialize(self):
+        await self.document_storage.initialize()
+
+    async def insert(
+        self,
+        content: str,
+        metadata: dict | None = None,
+        id: str | None = None,
+    ) -> int:
+        """插入一条文本和其对应向量，自动生成 ID 并保持一致性。"""
+        metadata = metadata or {}
+        str_id = id or str(uuid.uuid4())  # 使用 UUID 作为原始 ID
+
+        vector = await self.embedding_provider.get_embedding(content)
+        vector = np.array(vector, dtype=np.float32)
+
+        # 使用 DocumentStorage 的方法插入文档
+        int_id = await self.document_storage.insert_document(str_id, content, metadata)
+
+        # 插入向量到 FAISS
+        await self.embedding_storage.insert(vector, int_id)
+        return int_id
+
+    async def insert_batch(
+        self,
+        contents: list[str],
+        metadatas: list[dict] | None = None,
+        ids: list[str] | None = None,
+        batch_size: int = 32,
+        tasks_limit: int = 3,
+        max_retries: int = 3,
+        progress_callback=None,
+    ) -> list[int]:
+        """批量插入文本和其对应向量，自动生成 ID 并保持一致性。
+
+        Args:
+            progress_callback: 进度回调函数，接收参数 (current, total)
+
+        """
+        metadatas = metadatas or [{} for _ in contents]
+        ids = ids or [str(uuid.uuid4()) for _ in contents]
+
+        start = time.time()
+        logger.debug(f"Generating embeddings for {len(contents)} contents...")
+        vectors = await self.embedding_provider.get_embeddings_batch(
+            contents,
+            batch_size=batch_size,
+            tasks_limit=tasks_limit,
+            max_retries=max_retries,
+            progress_callback=progress_callback,
+        )
+        end = time.time()
+        logger.debug(
+            f"Generated embeddings for {len(contents)} contents in {end - start:.2f} seconds.",
+        )
+
+        # 使用 DocumentStorage 的批量插入方法
+        int_ids = await self.document_storage.insert_documents_batch(
+            ids,
+            contents,
+            metadatas,
+        )
+
+        # 批量插入向量到 FAISS
+        vectors_array = np.array(vectors).astype("float32")
+        await self.embedding_storage.insert_batch(vectors_array, int_ids)
+        return int_ids
+
+    async def retrieve(
+        self,
+        query: str,
+        k: int = 5,
+        fetch_k: int = 20,
+        rerank: bool = False,
+        metadata_filters: dict | None = None,
+    ) -> list[Result]:
+        """搜索最相似的文档。
+
+        Args:
+            query (str): 查询文本
+            k (int): 返回的最相似文档的数量
+            fetch_k (int): 在根据 metadata 过滤前从 FAISS 中获取的数量
+            rerank (bool): 是否使用重排序。这需要在实例化时提供 rerank_provider, 如果未提供并且 rerank 为 True, 不会抛出异常。
+            metadata_filters (dict): 元数据过滤器
+
+        Returns:
+            List[Result]: 查询结果
+
+        """
+        embedding = await self.embedding_provider.get_embedding(query)
+        scores, indices = await self.embedding_storage.search(
+            vector=np.array([embedding]).astype("float32"),
+            k=fetch_k if metadata_filters else k,
+        )
+        if len(indices[0]) == 0 or indices[0][0] == -1:
+            return []
+        # normalize scores
+        scores[0] = 1.0 - (scores[0] / 2.0)
+        # NOTE: maybe the size is less than k.
+        fetched_docs = await self.document_storage.get_documents(
+            metadata_filters=metadata_filters or {},
+            ids=indices[0],
+        )
+        if not fetched_docs:
+            return []
+        result_docs: list[Result] = []
+
+        idx_pos = {fetch_doc["id"]: idx for idx, fetch_doc in enumerate(fetched_docs)}
+        for i, indice_idx in enumerate(indices[0]):
+            pos = idx_pos.get(indice_idx)
+            if pos is None:
+                continue
+            fetch_doc = fetched_docs[pos]
+            score = scores[0][i]
+            result_docs.append(Result(similarity=float(score), data=fetch_doc))
+
+        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: str):
+        """删除一条文档块（chunk）"""
+        # 获得对应的 int id
+        result = await self.document_storage.get_document_by_doc_id(doc_id)
+        int_id = result["id"] if result else None
+        if int_id is None:
+            return
+
+        # 使用 DocumentStorage 的删除方法
+        await self.document_storage.delete_document_by_doc_id(doc_id)
+        await self.embedding_storage.delete([int_id])
+
+    async def close(self):
+        await self.document_storage.close()
+
+    async def count_documents(self, metadata_filter: dict | None = None) -> int:
+        """计算文档数量
+
+        Args:
+            metadata_filter (dict | None): 元数据过滤器
+
+        """
+        count = await self.document_storage.count_documents(
+            metadata_filters=metadata_filter or {},
+        )
+        return count
+
+    async def delete_documents(self, metadata_filters: dict):
+        """根据元数据过滤器删除文档"""
+        docs = await self.document_storage.get_documents(
+            metadata_filters=metadata_filters,
+            offset=None,
+            limit=None,
+        )
+        doc_ids: list[int] = [doc["id"] for doc in docs]
+        await self.embedding_storage.delete(doc_ids)
+        await self.document_storage.delete_documents(metadata_filters=metadata_filters)

astrbot/core/event_bus.py

@@ -1,5 +1,4 @@
-"""
+"""事件总线, 用于处理事件的分发和处理
-事件总线, 用于处理事件的分发和处理
 事件总线是一个异步队列, 用于接收各种消息事件, 并将其发送到Scheduler调度器进行处理
 其中包含了一个无限循环的调度函数, 用于从事件队列中获取新的事件, 并创建一个新的异步任务来执行管道调度器的处理逻辑
 
@@ -13,45 +12,50 @@ class:
 
 import asyncio
 from asyncio import Queue
-from astrbot.core.pipeline.scheduler import PipelineScheduler
+
 from astrbot.core import logger
+from astrbot.core.astrbot_config_mgr import AstrBotConfigManager
+from astrbot.core.pipeline.scheduler import PipelineScheduler
+
 from .platform import AstrMessageEvent
 
 
 class EventBus:
-    """事件总线: 用于处理事件的分发和处理
+    """用于处理事件的分发和处理"""
 
-    维护一个异步队列, 来接受各种消息事件
+    def __init__(
-    """
+        self,
-
+        event_queue: Queue,
-    def __init__(self, event_queue: Queue, pipeline_scheduler: PipelineScheduler):
+        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 = (
+            event: AstrMessageEvent = await self.event_queue.get()
-                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"])
-            self._print_event(event)  # 打印日志
+            scheduler = self.pipeline_scheduler_mapping.get(conf_info["id"])
-            asyncio.create_task(
+            asyncio.create_task(scheduler.execute(event))
-                self.pipeline_scheduler.execute(event)
-            )  # 创建新的异步任务来执行管道调度器的处理逻辑
 
-    def _print_event(self, event: AstrMessageEvent):
+    def _print_event(self, event: AstrMessageEvent, conf_name: str):
         """用于记录事件信息
 
         Args:
             event (AstrMessageEvent): 事件对象
+
         """
         # 如果有发送者名称: [平台名] 发送者名称/发送者ID: 消息概要
         if event.get_sender_name():
             logger.info(
-                f"[{event.get_platform_name()}] {event.get_sender_name()}/{event.get_sender_id()}: {event.get_message_outline()}"
+                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/exceptions.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+
+class AstrBotError(Exception):
+    """Base exception for all AstrBot errors."""
+
+
+class ProviderNotFoundError(AstrBotError):
+    """Raised when a specified provider is not found."""

astrbot/core/file_token_service.py

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

astrbot/core/initial_loader.py

@@ -1,5 +1,4 @@
-"""
+"""AstrBot 启动器，负责初始化和启动核心组件和仪表板服务器。
-AstrBot 启动器，负责初始化和启动核心组件和仪表板服务器。
 
 工作流程:
 1. 初始化核心生命周期, 传递数据库和日志代理实例到核心生命周期
@@ -8,10 +7,10 @@ AstrBot 启动器，负责初始化和启动核心组件和仪表板服务器。
 
 import asyncio
 import traceback
-from astrbot.core import logger
+
+from astrbot.core import LogBroker, logger
 from astrbot.core.core_lifecycle import AstrBotCoreLifecycle
 from astrbot.core.db import BaseDatabase
-from astrbot.core import LogBroker
 from astrbot.dashboard.server import AstrBotDashboard
 
 
@@ -22,25 +21,35 @@ 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)
 
-        core_task = []
         try:
             await core_lifecycle.initialize()
-            core_task = core_lifecycle.start()
         except Exception as e:
             logger.critical(traceback.format_exc())
             logger.critical(f"😭 初始化 AstrBot 失败：{e} !!!")
+            return
+
+        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()
-        )  # 启动核心任务和仪表板服务器
 
+        coro = self.dashboard_server.run()
+        if coro:
+            # 启动核心任务和仪表板服务器
+            task = asyncio.gather(core_task, coro)
+        else:
+            task = core_task
         try:
             await task  # 整个AstrBot在这里运行
         except asyncio.CancelledError:

astrbot/core/knowledge_base/chunking/__init__.py

@@ -0,0 +1,9 @@
+"""文档分块模块"""
+
+from .base import BaseChunker
+from .fixed_size import FixedSizeChunker
+
+__all__ = [
+    "BaseChunker",
+    "FixedSizeChunker",
+]

astrbot/core/knowledge_base/chunking/base.py

@@ -0,0 +1,25 @@
+"""文档分块器基类
+
+定义了文档分块处理的抽象接口。
+"""
+
+from abc import ABC, abstractmethod
+
+
+class BaseChunker(ABC):
+    """分块器基类
+
+    所有分块器都应该继承此类并实现 chunk 方法。
+    """
+
+    @abstractmethod
+    async def chunk(self, text: str, **kwargs) -> list[str]:
+        """将文本分块
+
+        Args:
+            text: 输入文本
+
+        Returns:
+            list[str]: 分块后的文本列表
+
+        """

astrbot/core/knowledge_base/chunking/fixed_size.py

@@ -0,0 +1,59 @@
+"""固定大小分块器
+
+按照固定的字符数将文本分块,支持重叠区域。
+"""
+
+from .base import BaseChunker
+
+
+class FixedSizeChunker(BaseChunker):
+    """固定大小分块器
+
+    按照固定的字符数分块,并支持块之间的重叠。
+    """
+
+    def __init__(self, chunk_size: int = 512, chunk_overlap: int = 50):
+        """初始化分块器
+
+        Args:
+            chunk_size: 块的大小(字符数)
+            chunk_overlap: 块之间的重叠字符数
+
+        """
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+
+    async def chunk(self, text: str, **kwargs) -> list[str]:
+        """固定大小分块
+
+        Args:
+            text: 输入文本
+            chunk_size: 每个文本块的最大大小
+            chunk_overlap: 每个文本块之间的重叠部分大小
+
+        Returns:
+            list[str]: 分块后的文本列表
+
+        """
+        chunk_size = kwargs.get("chunk_size", self.chunk_size)
+        chunk_overlap = kwargs.get("chunk_overlap", self.chunk_overlap)
+
+        chunks = []
+        start = 0
+        text_len = len(text)
+
+        while start < text_len:
+            end = start + chunk_size
+            chunk = text[start:end]
+
+            if chunk:
+                chunks.append(chunk)
+
+            # 移动窗口,保留重叠部分
+            start = end - chunk_overlap
+
+            # 防止无限循环: 如果重叠过大,直接移到end
+            if start >= end or chunk_overlap >= chunk_size:
+                start = end
+
+        return chunks

astrbot/core/knowledge_base/chunking/recursive.py

@@ -0,0 +1,161 @@
+from collections.abc import Callable
+
+from .base import BaseChunker
+
+
+class RecursiveCharacterChunker(BaseChunker):
+    def __init__(
+        self,
+        chunk_size: int = 500,
+        chunk_overlap: int = 100,
+        length_function: Callable[[str], int] = len,
+        is_separator_regex: bool = False,
+        separators: list[str] | None = None,
+    ):
+        """初始化递归字符文本分割器
+
+        Args:
+            chunk_size: 每个文本块的最大大小
+            chunk_overlap: 每个文本块之间的重叠部分大小
+            length_function: 计算文本长度的函数
+            is_separator_regex: 分隔符是否为正则表达式
+            separators: 用于分割文本的分隔符列表，按优先级排序
+
+        """
+        self.chunk_size = chunk_size
+        self.chunk_overlap = chunk_overlap
+        self.length_function = length_function
+        self.is_separator_regex = is_separator_regex
+
+        # 默认分隔符列表，按优先级从高到低
+        self.separators = separators or [
+            "\n\n",  # 段落
+            "\n",  # 换行
+            "。",  # 中文句子
+            "，",  # 中文逗号
+            ". ",  # 句子
+            ", ",  # 逗号分隔
+            " ",  # 单词
+            "",  # 字符
+        ]
+
+    async def chunk(self, text: str, **kwargs) -> list[str]:
+        """递归地将文本分割成块
+
+        Args:
+            text: 要分割的文本
+            chunk_size: 每个文本块的最大大小
+            chunk_overlap: 每个文本块之间的重叠部分大小
+
+        Returns:
+            分割后的文本块列表
+
+        """
+        if not text:
+            return []
+
+        overlap = kwargs.get("chunk_overlap", self.chunk_overlap)
+        chunk_size = kwargs.get("chunk_size", self.chunk_size)
+
+        text_length = self.length_function(text)
+        if text_length <= chunk_size:
+            return [text]
+
+        for separator in self.separators:
+            if separator == "":
+                return self._split_by_character(text, chunk_size, overlap)
+
+            if separator in text:
+                splits = text.split(separator)
+                # 重新添加分隔符（除了最后一个片段）
+                splits = [s + separator for s in splits[:-1]] + [splits[-1]]
+                splits = [s for s in splits if s]
+                if len(splits) == 1:
+                    continue
+
+                # 递归合并分割后的文本块
+                final_chunks = []
+                current_chunk = []
+                current_chunk_length = 0
+
+                for split in splits:
+                    split_length = self.length_function(split)
+
+                    # 如果单个分割部分已经超过了chunk_size，需要递归分割
+                    if split_length > chunk_size:
+                        # 先处理当前积累的块
+                        if current_chunk:
+                            combined_text = "".join(current_chunk)
+                            final_chunks.extend(
+                                await self.chunk(
+                                    combined_text,
+                                    chunk_size=chunk_size,
+                                    chunk_overlap=overlap,
+                                ),
+                            )
+                            current_chunk = []
+                            current_chunk_length = 0
+
+                        # 递归分割过大的部分
+                        final_chunks.extend(
+                            await self.chunk(
+                                split,
+                                chunk_size=chunk_size,
+                                chunk_overlap=overlap,
+                            ),
+                        )
+                    # 如果添加这部分会使当前块超过chunk_size
+                    elif current_chunk_length + split_length > chunk_size:
+                        # 合并当前块并添加到结果中
+                        combined_text = "".join(current_chunk)
+                        final_chunks.append(combined_text)
+
+                        # 处理重叠部分
+                        overlap_start = max(0, len(combined_text) - overlap)
+                        if overlap_start > 0:
+                            overlap_text = combined_text[overlap_start:]
+                            current_chunk = [overlap_text, split]
+                            current_chunk_length = (
+                                self.length_function(overlap_text) + split_length
+                            )
+                        else:
+                            current_chunk = [split]
+                            current_chunk_length = split_length
+                    else:
+                        # 添加到当前块
+                        current_chunk.append(split)
+                        current_chunk_length += split_length
+
+                # 处理剩余的块
+                if current_chunk:
+                    final_chunks.append("".join(current_chunk))
+
+                return final_chunks
+
+        return [text]
+
+    def _split_by_character(
+        self,
+        text: str,
+        chunk_size: int | None = None,
+        overlap: int | None = None,
+    ) -> list[str]:
+        """按字符级别分割文本
+
+        Args:
+            text: 要分割的文本
+
+        Returns:
+            分割后的文本块列表
+
+        """
+        chunk_size = chunk_size or self.chunk_size
+        overlap = overlap or self.chunk_overlap
+        result = []
+        for i in range(0, len(text), chunk_size - overlap):
+            end = min(i + chunk_size, len(text))
+            result.append(text[i:end])
+            if end == len(text):
+                break
+
+        return result

astrbot/core/knowledge_base/kb_db_sqlite.py

@@ -0,0 +1,301 @@
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from sqlalchemy import delete, func, select, text, update
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlmodel import col, desc
+
+from astrbot.core import logger
+from astrbot.core.db.vec_db.faiss_impl import FaissVecDB
+from astrbot.core.knowledge_base.models import (
+    BaseKBModel,
+    KBDocument,
+    KBMedia,
+    KnowledgeBase,
+)
+
+
+class KBSQLiteDatabase:
+    def __init__(self, db_path: str = "data/knowledge_base/kb.db") -> None:
+        """初始化知识库数据库
+
+        Args:
+            db_path: 数据库文件路径, 默认为 data/knowledge_base/kb.db
+
+        """
+        self.db_path = db_path
+        self.DATABASE_URL = f"sqlite+aiosqlite:///{db_path}"
+        self.inited = False
+
+        # 确保目录存在
+        Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+
+        # 创建异步引擎
+        self.engine = create_async_engine(
+            self.DATABASE_URL,
+            echo=False,
+            pool_pre_ping=True,
+            pool_recycle=3600,
+        )
+
+        # 创建会话工厂
+        self.async_session = async_sessionmaker(
+            self.engine,
+            class_=AsyncSession,
+            expire_on_commit=False,
+        )
+
+    @asynccontextmanager
+    async def get_db(self):
+        """获取数据库会话
+
+        用法:
+            async with kb_db.get_db() as session:
+                # 执行数据库操作
+                result = await session.execute(stmt)
+        """
+        async with self.async_session() as session:
+            yield session
+
+    async def initialize(self) -> None:
+        """初始化数据库,创建表并配置 SQLite 参数"""
+        async with self.engine.begin() as conn:
+            # 创建所有知识库相关表
+            await conn.run_sync(BaseKBModel.metadata.create_all)
+
+            # 配置 SQLite 性能优化参数
+            await conn.execute(text("PRAGMA journal_mode=WAL"))
+            await conn.execute(text("PRAGMA synchronous=NORMAL"))
+            await conn.execute(text("PRAGMA cache_size=20000"))
+            await conn.execute(text("PRAGMA temp_store=MEMORY"))
+            await conn.execute(text("PRAGMA mmap_size=134217728"))
+            await conn.execute(text("PRAGMA optimize"))
+            await conn.commit()
+
+        self.inited = True
+
+    async def migrate_to_v1(self) -> None:
+        """执行知识库数据库 v1 迁移
+
+        创建所有必要的索引以优化查询性能
+        """
+        async with self.get_db() as session:
+            session: AsyncSession
+            async with session.begin():
+                # 创建知识库表索引
+                await session.execute(
+                    text(
+                        "CREATE INDEX IF NOT EXISTS idx_kb_kb_id "
+                        "ON knowledge_bases(kb_id)",
+                    ),
+                )
+                await session.execute(
+                    text(
+                        "CREATE INDEX IF NOT EXISTS idx_kb_name "
+                        "ON knowledge_bases(kb_name)",
+                    ),
+                )
+                await session.execute(
+                    text(
+                        "CREATE INDEX IF NOT EXISTS idx_kb_created_at "
+                        "ON knowledge_bases(created_at)",
+                    ),
+                )
+
+                # 创建文档表索引
+                await session.execute(
+                    text(
+                        "CREATE INDEX IF NOT EXISTS idx_doc_doc_id "
+                        "ON kb_documents(doc_id)",
+                    ),
+                )
+                await session.execute(
+                    text(
+                        "CREATE INDEX IF NOT EXISTS idx_doc_kb_id "
+                        "ON kb_documents(kb_id)",
+                    ),
+                )
+                await session.execute(
+                    text(
+                        "CREATE INDEX IF NOT EXISTS idx_doc_name "
+                        "ON kb_documents(doc_name)",
+                    ),
+                )
+                await session.execute(
+                    text(
+                        "CREATE INDEX IF NOT EXISTS idx_doc_type "
+                        "ON kb_documents(file_type)",
+                    ),
+                )
+                await session.execute(
+                    text(
+                        "CREATE INDEX IF NOT EXISTS idx_doc_created_at "
+                        "ON kb_documents(created_at)",
+                    ),
+                )
+
+                # 创建多媒体表索引
+                await session.execute(
+                    text(
+                        "CREATE INDEX IF NOT EXISTS idx_media_media_id "
+                        "ON kb_media(media_id)",
+                    ),
+                )
+                await session.execute(
+                    text(
+                        "CREATE INDEX IF NOT EXISTS idx_media_doc_id "
+                        "ON kb_media(doc_id)",
+                    ),
+                )
+                await session.execute(
+                    text(
+                        "CREATE INDEX IF NOT EXISTS idx_media_kb_id ON kb_media(kb_id)",
+                    ),
+                )
+                await session.execute(
+                    text(
+                        "CREATE INDEX IF NOT EXISTS idx_media_type "
+                        "ON kb_media(media_type)",
+                    ),
+                )
+
+                await session.commit()
+
+    async def close(self) -> None:
+        """关闭数据库连接"""
+        await self.engine.dispose()
+        logger.info(f"知识库数据库已关闭: {self.db_path}")
+
+    async def get_kb_by_id(self, kb_id: str) -> KnowledgeBase | None:
+        """根据 ID 获取知识库"""
+        async with self.get_db() as session:
+            stmt = select(KnowledgeBase).where(col(KnowledgeBase.kb_id) == kb_id)
+            result = await session.execute(stmt)
+            return result.scalar_one_or_none()
+
+    async def get_kb_by_name(self, kb_name: str) -> KnowledgeBase | None:
+        """根据名称获取知识库"""
+        async with self.get_db() as session:
+            stmt = select(KnowledgeBase).where(col(KnowledgeBase.kb_name) == kb_name)
+            result = await session.execute(stmt)
+            return result.scalar_one_or_none()
+
+    async def list_kbs(self, offset: int = 0, limit: int = 100) -> list[KnowledgeBase]:
+        """列出所有知识库"""
+        async with self.get_db() as session:
+            stmt = (
+                select(KnowledgeBase)
+                .offset(offset)
+                .limit(limit)
+                .order_by(desc(KnowledgeBase.created_at))
+            )
+            result = await session.execute(stmt)
+            return list(result.scalars().all())
+
+    async def count_kbs(self) -> int:
+        """统计知识库数量"""
+        async with self.get_db() as session:
+            stmt = select(func.count(col(KnowledgeBase.id)))
+            result = await session.execute(stmt)
+            return result.scalar() or 0
+
+    # ===== 文档查询 =====
+
+    async def get_document_by_id(self, doc_id: str) -> KBDocument | None:
+        """根据 ID 获取文档"""
+        async with self.get_db() as session:
+            stmt = select(KBDocument).where(col(KBDocument.doc_id) == doc_id)
+            result = await session.execute(stmt)
+            return result.scalar_one_or_none()
+
+    async def list_documents_by_kb(
+        self,
+        kb_id: str,
+        offset: int = 0,
+        limit: int = 100,
+    ) -> list[KBDocument]:
+        """列出知识库的所有文档"""
+        async with self.get_db() as session:
+            stmt = (
+                select(KBDocument)
+                .where(col(KBDocument.kb_id) == kb_id)
+                .offset(offset)
+                .limit(limit)
+                .order_by(desc(KBDocument.created_at))
+            )
+            result = await session.execute(stmt)
+            return list(result.scalars().all())
+
+    async def count_documents_by_kb(self, kb_id: str) -> int:
+        """统计知识库的文档数量"""
+        async with self.get_db() as session:
+            stmt = select(func.count(col(KBDocument.id))).where(
+                col(KBDocument.kb_id) == kb_id,
+            )
+            result = await session.execute(stmt)
+            return result.scalar() or 0
+
+    async def get_document_with_metadata(self, doc_id: str) -> dict | None:
+        async with self.get_db() as session:
+            stmt = (
+                select(KBDocument, KnowledgeBase)
+                .join(KnowledgeBase, col(KBDocument.kb_id) == col(KnowledgeBase.kb_id))
+                .where(col(KBDocument.doc_id) == doc_id)
+            )
+            result = await session.execute(stmt)
+            row = result.first()
+
+            if not row:
+                return None
+
+            return {
+                "document": row[0],
+                "knowledge_base": row[1],
+            }
+
+    async def delete_document_by_id(self, doc_id: str, vec_db: FaissVecDB):
+        """删除单个文档及其相关数据"""
+        # 在知识库表中删除
+        async with self.get_db() as session, session.begin():
+            # 删除文档记录
+            delete_stmt = delete(KBDocument).where(col(KBDocument.doc_id) == doc_id)
+            await session.execute(delete_stmt)
+            await session.commit()
+
+        # 在 vec db 中删除相关向量
+        await vec_db.delete_documents(metadata_filters={"kb_doc_id": doc_id})
+
+    # ===== 多媒体查询 =====
+
+    async def list_media_by_doc(self, doc_id: str) -> list[KBMedia]:
+        """列出文档的所有多媒体资源"""
+        async with self.get_db() as session:
+            stmt = select(KBMedia).where(col(KBMedia.doc_id) == doc_id)
+            result = await session.execute(stmt)
+            return list(result.scalars().all())
+
+    async def get_media_by_id(self, media_id: str) -> KBMedia | None:
+        """根据 ID 获取多媒体资源"""
+        async with self.get_db() as session:
+            stmt = select(KBMedia).where(col(KBMedia.media_id) == media_id)
+            result = await session.execute(stmt)
+            return result.scalar_one_or_none()
+
+    async def update_kb_stats(self, kb_id: str, vec_db: FaissVecDB) -> None:
+        """更新知识库统计信息"""
+        chunk_cnt = await vec_db.count_documents()
+
+        async with self.get_db() as session, session.begin():
+            update_stmt = (
+                update(KnowledgeBase)
+                .where(col(KnowledgeBase.kb_id) == kb_id)
+                .values(
+                    doc_count=select(func.count(col(KBDocument.id)))
+                    .where(col(KBDocument.kb_id) == kb_id)
+                    .scalar_subquery(),
+                    chunk_count=chunk_cnt,
+                )
+            )
+
+            await session.execute(update_stmt)
+            await session.commit()

astrbot/core/knowledge_base/kb_helper.py

@@ -0,0 +1,642 @@
+import asyncio
+import json
+import re
+import time
+import uuid
+from pathlib import Path
+
+import aiofiles
+
+from astrbot.core import logger
+from astrbot.core.db.vec_db.base import BaseVecDB
+from astrbot.core.db.vec_db.faiss_impl.vec_db import FaissVecDB
+from astrbot.core.provider.manager import ProviderManager
+from astrbot.core.provider.provider import (
+    EmbeddingProvider,
+    RerankProvider,
+)
+from astrbot.core.provider.provider import (
+    Provider as LLMProvider,
+)
+
+from .chunking.base import BaseChunker
+from .chunking.recursive import RecursiveCharacterChunker
+from .kb_db_sqlite import KBSQLiteDatabase
+from .models import KBDocument, KBMedia, KnowledgeBase
+from .parsers.url_parser import extract_text_from_url
+from .parsers.util import select_parser
+from .prompts import TEXT_REPAIR_SYSTEM_PROMPT
+
+
+class RateLimiter:
+    """一个简单的速率限制器"""
+
+    def __init__(self, max_rpm: int):
+        self.max_per_minute = max_rpm
+        self.interval = 60.0 / max_rpm if max_rpm > 0 else 0
+        self.last_call_time = 0
+
+    async def __aenter__(self):
+        if self.interval == 0:
+            return
+
+        now = time.monotonic()
+        elapsed = now - self.last_call_time
+
+        if elapsed < self.interval:
+            await asyncio.sleep(self.interval - elapsed)
+
+        self.last_call_time = time.monotonic()
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        pass
+
+
+async def _repair_and_translate_chunk_with_retry(
+    chunk: str,
+    repair_llm_service: LLMProvider,
+    rate_limiter: RateLimiter,
+    max_retries: int = 2,
+) -> list[str]:
+    """
+    Repairs, translates, and optionally re-chunks a single text chunk using the small LLM, with rate limiting.
+    """
+    # 为了防止 LLM 上下文污染，在 user_prompt 中也加入明确的指令
+    user_prompt = f"""IGNORE ALL PREVIOUS INSTRUCTIONS. Your ONLY task is to process the following text chunk according to the system prompt provided.
+
+Text chunk to process:
+---
+{chunk}
+---
+"""
+    for attempt in range(max_retries + 1):
+        try:
+            async with rate_limiter:
+                response = await repair_llm_service.text_chat(
+                    prompt=user_prompt, system_prompt=TEXT_REPAIR_SYSTEM_PROMPT
+                )
+
+            llm_output = response.completion_text
+
+            if "<discard_chunk />" in llm_output:
+                return []  # Signal to discard this chunk
+
+            # More robust regex to handle potential LLM formatting errors (spaces, newlines in tags)
+            matches = re.findall(
+                r"<\s*repaired_text\s*>\s*(.*?)\s*<\s*/\s*repaired_text\s*>",
+                llm_output,
+                re.DOTALL,
+            )
+
+            if matches:
+                # Further cleaning to ensure no empty strings are returned
+                return [m.strip() for m in matches if m.strip()]
+            else:
+                # If no valid tags and not explicitly discarded, discard it to be safe.
+                return []
+        except Exception as e:
+            logger.warning(
+                f"  - LLM call failed on attempt {attempt + 1}/{max_retries + 1}. Error: {str(e)}"
+            )
+
+    logger.error(
+        f"  - Failed to process chunk after {max_retries + 1} attempts. Using original text."
+    )
+    return [chunk]
+
+
+class KBHelper:
+    vec_db: BaseVecDB
+    kb: KnowledgeBase
+
+    def __init__(
+        self,
+        kb_db: KBSQLiteDatabase,
+        kb: KnowledgeBase,
+        provider_manager: ProviderManager,
+        kb_root_dir: str,
+        chunker: BaseChunker,
+    ):
+        self.kb_db = kb_db
+        self.kb = kb
+        self.prov_mgr = provider_manager
+        self.kb_root_dir = kb_root_dir
+        self.chunker = chunker
+
+        self.kb_dir = Path(self.kb_root_dir) / self.kb.kb_id
+        self.kb_medias_dir = Path(self.kb_dir) / "medias" / self.kb.kb_id
+        self.kb_files_dir = Path(self.kb_dir) / "files" / self.kb.kb_id
+
+        self.kb_medias_dir.mkdir(parents=True, exist_ok=True)
+        self.kb_files_dir.mkdir(parents=True, exist_ok=True)
+
+    async def initialize(self):
+        await self._ensure_vec_db()
+
+    async def get_ep(self) -> EmbeddingProvider:
+        if not self.kb.embedding_provider_id:
+            raise ValueError(f"知识库 {self.kb.kb_name} 未配置 Embedding Provider")
+        ep: EmbeddingProvider = await self.prov_mgr.get_provider_by_id(
+            self.kb.embedding_provider_id,
+        )  # type: ignore
+        if not ep:
+            raise ValueError(
+                f"无法找到 ID 为 {self.kb.embedding_provider_id} 的 Embedding Provider",
+            )
+        return ep
+
+    async def get_rp(self) -> RerankProvider | None:
+        if not self.kb.rerank_provider_id:
+            return None
+        rp: RerankProvider = await self.prov_mgr.get_provider_by_id(
+            self.kb.rerank_provider_id,
+        )  # type: ignore
+        if not rp:
+            raise ValueError(
+                f"无法找到 ID 为 {self.kb.rerank_provider_id} 的 Rerank Provider",
+            )
+        return rp
+
+    async def _ensure_vec_db(self) -> FaissVecDB:
+        if not self.kb.embedding_provider_id:
+            raise ValueError(f"知识库 {self.kb.kb_name} 未配置 Embedding Provider")
+
+        ep = await self.get_ep()
+        rp = await self.get_rp()
+
+        vec_db = FaissVecDB(
+            doc_store_path=str(self.kb_dir / "doc.db"),
+            index_store_path=str(self.kb_dir / "index.faiss"),
+            embedding_provider=ep,
+            rerank_provider=rp,
+        )
+        await vec_db.initialize()
+        self.vec_db = vec_db
+        return vec_db
+
+    async def delete_vec_db(self):
+        """删除知识库的向量数据库和所有相关文件"""
+        import shutil
+
+        await self.terminate()
+        if self.kb_dir.exists():
+            shutil.rmtree(self.kb_dir)
+
+    async def terminate(self):
+        if self.vec_db:
+            await self.vec_db.close()
+
+    async def upload_document(
+        self,
+        file_name: str,
+        file_content: bytes | None,
+        file_type: str,
+        chunk_size: int = 512,
+        chunk_overlap: int = 50,
+        batch_size: int = 32,
+        tasks_limit: int = 3,
+        max_retries: int = 3,
+        progress_callback=None,
+        pre_chunked_text: list[str] | None = None,
+    ) -> KBDocument:
+        """上传并处理文档（带原子性保证和失败清理）
+
+        流程:
+        1. 保存原始文件
+        2. 解析文档内容
+        3. 提取多媒体资源
+        4. 分块处理
+        5. 生成向量并存储
+        6. 保存元数据（事务）
+        7. 更新统计
+
+        Args:
+            progress_callback: 进度回调函数，接收参数 (stage, current, total)
+                - stage: 当前阶段 ('parsing', 'chunking', 'embedding')
+                - current: 当前进度
+                - total: 总数
+
+        """
+        await self._ensure_vec_db()
+        doc_id = str(uuid.uuid4())
+        media_paths: list[Path] = []
+        file_size = 0
+
+        # file_path = self.kb_files_dir / f"{doc_id}.{file_type}"
+        # async with aiofiles.open(file_path, "wb") as f:
+        #     await f.write(file_content)
+
+        try:
+            chunks_text = []
+            saved_media = []
+
+            if pre_chunked_text is not None:
+                # 如果提供了预分块文本，直接使用
+                chunks_text = pre_chunked_text
+                file_size = sum(len(chunk) for chunk in chunks_text)
+                logger.info(f"使用预分块文本进行上传，共 {len(chunks_text)} 个块。")
+            else:
+                # 否则，执行标准的文件解析和分块流程
+                if file_content is None:
+                    raise ValueError(
+                        "当未提供 pre_chunked_text 时，file_content 不能为空。"
+                    )
+
+                file_size = len(file_content)
+
+                # 阶段1: 解析文档
+                if progress_callback:
+                    await progress_callback("parsing", 0, 100)
+
+                parser = await select_parser(f".{file_type}")
+                parse_result = await parser.parse(file_content, file_name)
+                text_content = parse_result.text
+                media_items = parse_result.media
+
+                if progress_callback:
+                    await progress_callback("parsing", 100, 100)
+
+                # 保存媒体文件
+                for media_item in media_items:
+                    media = await self._save_media(
+                        doc_id=doc_id,
+                        media_type=media_item.media_type,
+                        file_name=media_item.file_name,
+                        content=media_item.content,
+                        mime_type=media_item.mime_type,
+                    )
+                    saved_media.append(media)
+                    media_paths.append(Path(media.file_path))
+
+                # 阶段2: 分块
+                if progress_callback:
+                    await progress_callback("chunking", 0, 100)
+
+                chunks_text = await self.chunker.chunk(
+                    text_content,
+                    chunk_size=chunk_size,
+                    chunk_overlap=chunk_overlap,
+                )
+            contents = []
+            metadatas = []
+            for idx, chunk_text in enumerate(chunks_text):
+                contents.append(chunk_text)
+                metadatas.append(
+                    {
+                        "kb_id": self.kb.kb_id,
+                        "kb_doc_id": doc_id,
+                        "chunk_index": idx,
+                    },
+                )
+
+            if progress_callback:
+                await progress_callback("chunking", 100, 100)
+
+            # 阶段3: 生成向量（带进度回调）
+            async def embedding_progress_callback(current, total):
+                if progress_callback:
+                    await progress_callback("embedding", current, total)
+
+            await self.vec_db.insert_batch(
+                contents=contents,
+                metadatas=metadatas,
+                batch_size=batch_size,
+                tasks_limit=tasks_limit,
+                max_retries=max_retries,
+                progress_callback=embedding_progress_callback,
+            )
+
+            # 保存文档的元数据
+            doc = KBDocument(
+                doc_id=doc_id,
+                kb_id=self.kb.kb_id,
+                doc_name=file_name,
+                file_type=file_type,
+                file_size=file_size,
+                # file_path=str(file_path),
+                file_path="",
+                chunk_count=len(chunks_text),
+                media_count=0,
+            )
+            async with self.kb_db.get_db() as session:
+                async with session.begin():
+                    session.add(doc)
+                    for media in saved_media:
+                        session.add(media)
+                    await session.commit()
+
+                await session.refresh(doc)
+
+            vec_db: FaissVecDB = self.vec_db  # type: ignore
+            await self.kb_db.update_kb_stats(kb_id=self.kb.kb_id, vec_db=vec_db)
+            await self.refresh_kb()
+            await self.refresh_document(doc_id)
+            return doc
+        except Exception as e:
+            logger.error(f"上传文档失败: {e}")
+            # if file_path.exists():
+            #     file_path.unlink()
+
+            for media_path in media_paths:
+                try:
+                    if media_path.exists():
+                        media_path.unlink()
+                except Exception as me:
+                    logger.warning(f"清理多媒体文件失败 {media_path}: {me}")
+
+            raise e
+
+    async def list_documents(
+        self,
+        offset: int = 0,
+        limit: int = 100,
+    ) -> list[KBDocument]:
+        """列出知识库的所有文档"""
+        docs = await self.kb_db.list_documents_by_kb(self.kb.kb_id, offset, limit)
+        return docs
+
+    async def get_document(self, doc_id: str) -> KBDocument | None:
+        """获取单个文档"""
+        doc = await self.kb_db.get_document_by_id(doc_id)
+        return doc
+
+    async def delete_document(self, doc_id: str):
+        """删除单个文档及其相关数据"""
+        await self.kb_db.delete_document_by_id(
+            doc_id=doc_id,
+            vec_db=self.vec_db,  # type: ignore
+        )
+        await self.kb_db.update_kb_stats(
+            kb_id=self.kb.kb_id,
+            vec_db=self.vec_db,  # type: ignore
+        )
+        await self.refresh_kb()
+
+    async def delete_chunk(self, chunk_id: str, doc_id: str):
+        """删除单个文本块及其相关数据"""
+        vec_db: FaissVecDB = self.vec_db  # type: ignore
+        await vec_db.delete(chunk_id)
+        await self.kb_db.update_kb_stats(
+            kb_id=self.kb.kb_id,
+            vec_db=self.vec_db,  # type: ignore
+        )
+        await self.refresh_kb()
+        await self.refresh_document(doc_id)
+
+    async def refresh_kb(self):
+        if self.kb:
+            kb = await self.kb_db.get_kb_by_id(self.kb.kb_id)
+            if kb:
+                self.kb = kb
+
+    async def refresh_document(self, doc_id: str) -> None:
+        """更新文档的元数据"""
+        doc = await self.get_document(doc_id)
+        if not doc:
+            raise ValueError(f"无法找到 ID 为 {doc_id} 的文档")
+        chunk_count = await self.get_chunk_count_by_doc_id(doc_id)
+        doc.chunk_count = chunk_count
+        async with self.kb_db.get_db() as session:
+            async with session.begin():
+                session.add(doc)
+                await session.commit()
+            await session.refresh(doc)
+
+    async def get_chunks_by_doc_id(
+        self,
+        doc_id: str,
+        offset: int = 0,
+        limit: int = 100,
+    ) -> list[dict]:
+        """获取文档的所有块及其元数据"""
+        vec_db: FaissVecDB = self.vec_db  # type: ignore
+        chunks = await vec_db.document_storage.get_documents(
+            metadata_filters={"kb_doc_id": doc_id},
+            offset=offset,
+            limit=limit,
+        )
+        result = []
+        for chunk in chunks:
+            chunk_md = json.loads(chunk["metadata"])
+            result.append(
+                {
+                    "chunk_id": chunk["doc_id"],
+                    "doc_id": chunk_md["kb_doc_id"],
+                    "kb_id": chunk_md["kb_id"],
+                    "chunk_index": chunk_md["chunk_index"],
+                    "content": chunk["text"],
+                    "char_count": len(chunk["text"]),
+                },
+            )
+        return result
+
+    async def get_chunk_count_by_doc_id(self, doc_id: str) -> int:
+        """获取文档的块数量"""
+        vec_db: FaissVecDB = self.vec_db  # type: ignore
+        count = await vec_db.count_documents(metadata_filter={"kb_doc_id": doc_id})
+        return count
+
+    async def _save_media(
+        self,
+        doc_id: str,
+        media_type: str,
+        file_name: str,
+        content: bytes,
+        mime_type: str,
+    ) -> KBMedia:
+        """保存多媒体资源"""
+        media_id = str(uuid.uuid4())
+        ext = Path(file_name).suffix
+
+        # 保存文件
+        file_path = self.kb_medias_dir / doc_id / f"{media_id}{ext}"
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+        async with aiofiles.open(file_path, "wb") as f:
+            await f.write(content)
+
+        media = KBMedia(
+            media_id=media_id,
+            doc_id=doc_id,
+            kb_id=self.kb.kb_id,
+            media_type=media_type,
+            file_name=file_name,
+            file_path=str(file_path),
+            file_size=len(content),
+            mime_type=mime_type,
+        )
+
+        return media
+
+    async def upload_from_url(
+        self,
+        url: str,
+        chunk_size: int = 512,
+        chunk_overlap: int = 50,
+        batch_size: int = 32,
+        tasks_limit: int = 3,
+        max_retries: int = 3,
+        progress_callback=None,
+        enable_cleaning: bool = False,
+        cleaning_provider_id: str | None = None,
+    ) -> KBDocument:
+        """从 URL 上传并处理文档（带原子性保证和失败清理）
+        Args:
+            url: 要提取内容的网页 URL
+            chunk_size: 文本块大小
+            chunk_overlap: 文本块重叠大小
+            batch_size: 批处理大小
+            tasks_limit: 并发任务限制
+            max_retries: 最大重试次数
+            progress_callback: 进度回调函数，接收参数 (stage, current, total)
+                - stage: 当前阶段 ('extracting', 'cleaning', 'parsing', 'chunking', 'embedding')
+                - current: 当前进度
+                - total: 总数
+        Returns:
+            KBDocument: 上传的文档对象
+        Raises:
+            ValueError: 如果 URL 为空或无法提取内容
+            IOError: 如果网络请求失败
+        """
+        # 获取 Tavily API 密钥
+        config = self.prov_mgr.acm.default_conf
+        tavily_keys = config.get("provider_settings", {}).get(
+            "websearch_tavily_key", []
+        )
+        if not tavily_keys:
+            raise ValueError(
+                "Error: Tavily API key is not configured in provider_settings."
+            )
+
+        # 阶段1: 从 URL 提取内容
+        if progress_callback:
+            await progress_callback("extracting", 0, 100)
+
+        try:
+            text_content = await extract_text_from_url(url, tavily_keys)
+        except Exception as e:
+            logger.error(f"Failed to extract content from URL {url}: {e}")
+            raise OSError(f"Failed to extract content from URL {url}: {e}") from e
+
+        if not text_content:
+            raise ValueError(f"No content extracted from URL: {url}")
+
+        if progress_callback:
+            await progress_callback("extracting", 100, 100)
+
+        # 阶段2: (可选)清洗内容并分块
+        final_chunks = await self._clean_and_rechunk_content(
+            content=text_content,
+            url=url,
+            progress_callback=progress_callback,
+            enable_cleaning=enable_cleaning,
+            cleaning_provider_id=cleaning_provider_id,
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+        )
+
+        if enable_cleaning and not final_chunks:
+            raise ValueError(
+                "内容清洗后未提取到有效文本。请尝试关闭内容清洗功能，或更换更高性能的LLM模型后重试。"
+            )
+
+        # 创建一个虚拟文件名
+        file_name = url.split("/")[-1] or f"document_from_{url}"
+        if not Path(file_name).suffix:
+            file_name += ".url"
+
+        # 复用现有的 upload_document 方法，但传入预分块文本
+        return await self.upload_document(
+            file_name=file_name,
+            file_content=None,
+            file_type="url",  # 使用 'url' 作为特殊文件类型
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+            batch_size=batch_size,
+            tasks_limit=tasks_limit,
+            max_retries=max_retries,
+            progress_callback=progress_callback,
+            pre_chunked_text=final_chunks,
+        )
+
+    async def _clean_and_rechunk_content(
+        self,
+        content: str,
+        url: str,
+        progress_callback=None,
+        enable_cleaning: bool = False,
+        cleaning_provider_id: str | None = None,
+        repair_max_rpm: int = 60,
+        chunk_size: int = 512,
+        chunk_overlap: int = 50,
+    ) -> list[str]:
+        """
+        对从 URL 获取的内容进行清洗、修复、翻译和重新分块。
+        """
+        if not enable_cleaning:
+            # 如果不启用清洗，则使用从前端传递的参数进行分块
+            logger.info(
+                f"内容清洗未启用，使用指定参数进行分块: chunk_size={chunk_size}, chunk_overlap={chunk_overlap}"
+            )
+            return await self.chunker.chunk(
+                content, chunk_size=chunk_size, chunk_overlap=chunk_overlap
+            )
+
+        if not cleaning_provider_id:
+            logger.warning(
+                "启用了内容清洗，但未提供 cleaning_provider_id，跳过清洗并使用默认分块。"
+            )
+            return await self.chunker.chunk(content)
+
+        if progress_callback:
+            await progress_callback("cleaning", 0, 100)
+
+        try:
+            # 获取指定的 LLM Provider
+            llm_provider = await self.prov_mgr.get_provider_by_id(cleaning_provider_id)
+            if not llm_provider or not isinstance(llm_provider, LLMProvider):
+                raise ValueError(
+                    f"无法找到 ID 为 {cleaning_provider_id} 的 LLM Provider 或类型不正确"
+                )
+
+            # 初步分块
+            # 优化分隔符，优先按段落分割，以获得更高质量的文本块
+            text_splitter = RecursiveCharacterChunker(
+                chunk_size=chunk_size,
+                chunk_overlap=chunk_overlap,
+                separators=["\n\n", "\n", " "],  # 优先使用段落分隔符
+            )
+            initial_chunks = await text_splitter.chunk(content)
+            logger.info(f"初步分块完成，生成 {len(initial_chunks)} 个块用于修复。")
+
+            # 并发处理所有块
+            rate_limiter = RateLimiter(repair_max_rpm)
+            tasks = [
+                _repair_and_translate_chunk_with_retry(
+                    chunk, llm_provider, rate_limiter
+                )
+                for chunk in initial_chunks
+            ]
+
+            repaired_results = await asyncio.gather(*tasks, return_exceptions=True)
+
+            final_chunks = []
+            for i, result in enumerate(repaired_results):
+                if isinstance(result, Exception):
+                    logger.warning(f"块 {i} 处理异常: {str(result)}. 回退到原始块。")
+                    final_chunks.append(initial_chunks[i])
+                elif isinstance(result, list):
+                    final_chunks.extend(result)
+
+            logger.info(
+                f"文本修复完成: {len(initial_chunks)} 个原始块 -> {len(final_chunks)} 个最终块。"
+            )
+
+            if progress_callback:
+                await progress_callback("cleaning", 100, 100)
+
+            return final_chunks
+
+        except Exception as e:
+            logger.error(f"使用 Provider '{cleaning_provider_id}' 清洗内容失败: {e}")
+            # 清洗失败，返回默认分块结果，保证流程不中断
+            return await self.chunker.chunk(content)

astrbot/core/knowledge_base/kb_mgr.py

@@ -0,0 +1,330 @@
+import traceback
+from pathlib import Path
+
+from astrbot.core import logger
+from astrbot.core.provider.manager import ProviderManager
+
+# from .chunking.fixed_size import FixedSizeChunker
+from .chunking.recursive import RecursiveCharacterChunker
+from .kb_db_sqlite import KBSQLiteDatabase
+from .kb_helper import KBHelper
+from .models import KBDocument, KnowledgeBase
+from .retrieval.manager import RetrievalManager, RetrievalResult
+from .retrieval.rank_fusion import RankFusion
+from .retrieval.sparse_retriever import SparseRetriever
+
+FILES_PATH = "data/knowledge_base"
+DB_PATH = Path(FILES_PATH) / "kb.db"
+"""Knowledge Base storage root directory"""
+CHUNKER = RecursiveCharacterChunker()
+
+
+class KnowledgeBaseManager:
+    kb_db: KBSQLiteDatabase
+    retrieval_manager: RetrievalManager
+
+    def __init__(
+        self,
+        provider_manager: ProviderManager,
+    ):
+        Path(DB_PATH).parent.mkdir(parents=True, exist_ok=True)
+        self.provider_manager = provider_manager
+        self._session_deleted_callback_registered = False
+
+        self.kb_insts: dict[str, KBHelper] = {}
+
+    async def initialize(self):
+        """初始化知识库模块"""
+        try:
+            logger.info("正在初始化知识库模块...")
+
+            # 初始化数据库
+            await self._init_kb_database()
+
+            # 初始化检索管理器
+            sparse_retriever = SparseRetriever(self.kb_db)
+            rank_fusion = RankFusion(self.kb_db)
+            self.retrieval_manager = RetrievalManager(
+                sparse_retriever=sparse_retriever,
+                rank_fusion=rank_fusion,
+                kb_db=self.kb_db,
+            )
+            await self.load_kbs()
+
+        except ImportError as e:
+            logger.error(f"知识库模块导入失败: {e}")
+            logger.warning("请确保已安装所需依赖: pypdf, aiofiles, Pillow, rank-bm25")
+        except Exception as e:
+            logger.error(f"知识库模块初始化失败: {e}")
+            logger.error(traceback.format_exc())
+
+    async def _init_kb_database(self):
+        self.kb_db = KBSQLiteDatabase(DB_PATH.as_posix())
+        await self.kb_db.initialize()
+        await self.kb_db.migrate_to_v1()
+        logger.info(f"KnowledgeBase database initialized: {DB_PATH}")
+
+    async def load_kbs(self):
+        """加载所有知识库实例"""
+        kb_records = await self.kb_db.list_kbs()
+        for record in kb_records:
+            kb_helper = KBHelper(
+                kb_db=self.kb_db,
+                kb=record,
+                provider_manager=self.provider_manager,
+                kb_root_dir=FILES_PATH,
+                chunker=CHUNKER,
+            )
+            await kb_helper.initialize()
+            self.kb_insts[record.kb_id] = kb_helper
+
+    async def create_kb(
+        self,
+        kb_name: str,
+        description: str | None = None,
+        emoji: str | None = None,
+        embedding_provider_id: str | None = None,
+        rerank_provider_id: str | None = None,
+        chunk_size: int | None = None,
+        chunk_overlap: int | None = None,
+        top_k_dense: int | None = None,
+        top_k_sparse: int | None = None,
+        top_m_final: int | None = None,
+    ) -> KBHelper:
+        """创建新的知识库实例"""
+        kb = KnowledgeBase(
+            kb_name=kb_name,
+            description=description,
+            emoji=emoji or "📚",
+            embedding_provider_id=embedding_provider_id,
+            rerank_provider_id=rerank_provider_id,
+            chunk_size=chunk_size if chunk_size is not None else 512,
+            chunk_overlap=chunk_overlap if chunk_overlap is not None else 50,
+            top_k_dense=top_k_dense if top_k_dense is not None else 50,
+            top_k_sparse=top_k_sparse if top_k_sparse is not None else 50,
+            top_m_final=top_m_final if top_m_final is not None else 5,
+        )
+        async with self.kb_db.get_db() as session:
+            session.add(kb)
+            await session.commit()
+            await session.refresh(kb)
+
+            kb_helper = KBHelper(
+                kb_db=self.kb_db,
+                kb=kb,
+                provider_manager=self.provider_manager,
+                kb_root_dir=FILES_PATH,
+                chunker=CHUNKER,
+            )
+            await kb_helper.initialize()
+        self.kb_insts[kb.kb_id] = kb_helper
+        return kb_helper
+
+    async def get_kb(self, kb_id: str) -> KBHelper | None:
+        """获取知识库实例"""
+        if kb_id in self.kb_insts:
+            return self.kb_insts[kb_id]
+
+    async def get_kb_by_name(self, kb_name: str) -> KBHelper | None:
+        """通过名称获取知识库实例"""
+        for kb_helper in self.kb_insts.values():
+            if kb_helper.kb.kb_name == kb_name:
+                return kb_helper
+        return None
+
+    async def delete_kb(self, kb_id: str) -> bool:
+        """删除知识库实例"""
+        kb_helper = await self.get_kb(kb_id)
+        if not kb_helper:
+            return False
+
+        await kb_helper.delete_vec_db()
+        async with self.kb_db.get_db() as session:
+            await session.delete(kb_helper.kb)
+            await session.commit()
+
+        self.kb_insts.pop(kb_id, None)
+        return True
+
+    async def list_kbs(self) -> list[KnowledgeBase]:
+        """列出所有知识库实例"""
+        kbs = [kb_helper.kb for kb_helper in self.kb_insts.values()]
+        return kbs
+
+    async def update_kb(
+        self,
+        kb_id: str,
+        kb_name: str,
+        description: str | None = None,
+        emoji: str | None = None,
+        embedding_provider_id: str | None = None,
+        rerank_provider_id: str | None = None,
+        chunk_size: int | None = None,
+        chunk_overlap: int | None = None,
+        top_k_dense: int | None = None,
+        top_k_sparse: int | None = None,
+        top_m_final: int | None = None,
+    ) -> KBHelper | None:
+        """更新知识库实例"""
+        kb_helper = await self.get_kb(kb_id)
+        if not kb_helper:
+            return None
+
+        kb = kb_helper.kb
+        if kb_name is not None:
+            kb.kb_name = kb_name
+        if description is not None:
+            kb.description = description
+        if emoji is not None:
+            kb.emoji = emoji
+        if embedding_provider_id is not None:
+            kb.embedding_provider_id = embedding_provider_id
+        kb.rerank_provider_id = rerank_provider_id  # 允许设置为 None
+        if chunk_size is not None:
+            kb.chunk_size = chunk_size
+        if chunk_overlap is not None:
+            kb.chunk_overlap = chunk_overlap
+        if top_k_dense is not None:
+            kb.top_k_dense = top_k_dense
+        if top_k_sparse is not None:
+            kb.top_k_sparse = top_k_sparse
+        if top_m_final is not None:
+            kb.top_m_final = top_m_final
+        async with self.kb_db.get_db() as session:
+            session.add(kb)
+            await session.commit()
+            await session.refresh(kb)
+
+        return kb_helper
+
+    async def retrieve(
+        self,
+        query: str,
+        kb_names: list[str],
+        top_k_fusion: int = 20,
+        top_m_final: int = 5,
+    ) -> dict | None:
+        """从指定知识库中检索相关内容"""
+        kb_ids = []
+        kb_id_helper_map = {}
+        for kb_name in kb_names:
+            if kb_helper := await self.get_kb_by_name(kb_name):
+                kb_ids.append(kb_helper.kb.kb_id)
+                kb_id_helper_map[kb_helper.kb.kb_id] = kb_helper
+
+        if not kb_ids:
+            return {}
+
+        results = await self.retrieval_manager.retrieve(
+            query=query,
+            kb_ids=kb_ids,
+            kb_id_helper_map=kb_id_helper_map,
+            top_k_fusion=top_k_fusion,
+            top_m_final=top_m_final,
+        )
+        if not results:
+            return None
+
+        context_text = self._format_context(results)
+
+        results_dict = [
+            {
+                "chunk_id": r.chunk_id,
+                "doc_id": r.doc_id,
+                "kb_id": r.kb_id,
+                "kb_name": r.kb_name,
+                "doc_name": r.doc_name,
+                "chunk_index": r.metadata.get("chunk_index", 0),
+                "content": r.content,
+                "score": r.score,
+                "char_count": r.metadata.get("char_count", 0),
+            }
+            for r in results
+        ]
+
+        return {
+            "context_text": context_text,
+            "results": results_dict,
+        }
+
+    def _format_context(self, results: list[RetrievalResult]) -> str:
+        """格式化知识上下文
+
+        Args:
+            results: 检索结果列表
+
+        Returns:
+            str: 格式化的上下文文本
+
+        """
+        lines = ["以下是相关的知识库内容,请参考这些信息回答用户的问题:\n"]
+
+        for i, result in enumerate(results, 1):
+            lines.append(f"【知识 {i}】")
+            lines.append(f"来源: {result.kb_name} / {result.doc_name}")
+            lines.append(f"内容: {result.content}")
+            lines.append(f"相关度: {result.score:.2f}")
+            lines.append("")
+
+        return "\n".join(lines)
+
+    async def terminate(self):
+        """终止所有知识库实例,关闭数据库连接"""
+        for kb_id, kb_helper in self.kb_insts.items():
+            try:
+                await kb_helper.terminate()
+            except Exception as e:
+                logger.error(f"关闭知识库 {kb_id} 失败: {e}")
+
+        self.kb_insts.clear()
+
+        # 关闭元数据数据库
+        if hasattr(self, "kb_db") and self.kb_db:
+            try:
+                await self.kb_db.close()
+            except Exception as e:
+                logger.error(f"关闭知识库元数据数据库失败: {e}")
+
+    async def upload_from_url(
+        self,
+        kb_id: str,
+        url: str,
+        chunk_size: int = 512,
+        chunk_overlap: int = 50,
+        batch_size: int = 32,
+        tasks_limit: int = 3,
+        max_retries: int = 3,
+        progress_callback=None,
+    ) -> KBDocument:
+        """从 URL 上传文档到指定的知识库
+
+        Args:
+            kb_id: 知识库 ID
+            url: 要提取内容的网页 URL
+            chunk_size: 文本块大小
+            chunk_overlap: 文本块重叠大小
+            batch_size: 批处理大小
+            tasks_limit: 并发任务限制
+            max_retries: 最大重试次数
+            progress_callback: 进度回调函数
+
+        Returns:
+            KBDocument: 上传的文档对象
+
+        Raises:
+            ValueError: 如果知识库不存在或 URL 为空
+            IOError: 如果网络请求失败
+        """
+        kb_helper = await self.get_kb(kb_id)
+        if not kb_helper:
+            raise ValueError(f"Knowledge base with id {kb_id} not found.")
+
+        return await kb_helper.upload_from_url(
+            url=url,
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+            batch_size=batch_size,
+            tasks_limit=tasks_limit,
+            max_retries=max_retries,
+            progress_callback=progress_callback,
+        )

astrbot/core/knowledge_base/models.py

@@ -0,0 +1,120 @@
+import uuid
+from datetime import datetime, timezone
+
+from sqlmodel import Field, MetaData, SQLModel, Text, UniqueConstraint
+
+
+class BaseKBModel(SQLModel, table=False):
+    metadata = MetaData()
+
+
+class KnowledgeBase(BaseKBModel, table=True):
+    """知识库表
+
+    存储知识库的基本信息和统计数据。
+    """
+
+    __tablename__ = "knowledge_bases"  # type: ignore
+
+    id: int | None = Field(
+        primary_key=True,
+        sa_column_kwargs={"autoincrement": True},
+        default=None,
+    )
+    kb_id: str = Field(
+        max_length=36,
+        nullable=False,
+        unique=True,
+        default_factory=lambda: str(uuid.uuid4()),
+        index=True,
+    )
+    kb_name: str = Field(max_length=100, nullable=False)
+    description: str | None = Field(default=None, sa_type=Text)
+    emoji: str | None = Field(default="📚", max_length=10)
+    embedding_provider_id: str | None = Field(default=None, max_length=100)
+    rerank_provider_id: str | None = Field(default=None, max_length=100)
+    # 分块配置参数
+    chunk_size: int | None = Field(default=512, nullable=True)
+    chunk_overlap: int | None = Field(default=50, nullable=True)
+    # 检索配置参数
+    top_k_dense: int | None = Field(default=50, nullable=True)
+    top_k_sparse: int | None = Field(default=50, nullable=True)
+    top_m_final: int | None = Field(default=5, nullable=True)
+    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)},
+    )
+    doc_count: int = Field(default=0, nullable=False)
+    chunk_count: int = Field(default=0, nullable=False)
+
+    __table_args__ = (
+        UniqueConstraint(
+            "kb_name",
+            name="uix_kb_name",
+        ),
+    )
+
+
+class KBDocument(BaseKBModel, table=True):
+    """文档表
+
+    存储上传到知识库的文档元数据。
+    """
+
+    __tablename__ = "kb_documents"  # type: ignore
+
+    id: int | None = Field(
+        primary_key=True,
+        sa_column_kwargs={"autoincrement": True},
+        default=None,
+    )
+    doc_id: str = Field(
+        max_length=36,
+        nullable=False,
+        unique=True,
+        default_factory=lambda: str(uuid.uuid4()),
+        index=True,
+    )
+    kb_id: str = Field(max_length=36, nullable=False, index=True)
+    doc_name: str = Field(max_length=255, nullable=False)
+    file_type: str = Field(max_length=20, nullable=False)
+    file_size: int = Field(nullable=False)
+    file_path: str = Field(max_length=512, nullable=False)
+    chunk_count: int = Field(default=0, nullable=False)
+    media_count: int = Field(default=0, 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)},
+    )
+
+
+class KBMedia(BaseKBModel, table=True):
+    """多媒体资源表
+
+    存储从文档中提取的图片、视频等多媒体资源。
+    """
+
+    __tablename__ = "kb_media"  # type: ignore
+
+    id: int | None = Field(
+        primary_key=True,
+        sa_column_kwargs={"autoincrement": True},
+        default=None,
+    )
+    media_id: str = Field(
+        max_length=36,
+        nullable=False,
+        unique=True,
+        default_factory=lambda: str(uuid.uuid4()),
+        index=True,
+    )
+    doc_id: str = Field(max_length=36, nullable=False, index=True)
+    kb_id: str = Field(max_length=36, nullable=False, index=True)
+    media_type: str = Field(max_length=20, nullable=False)
+    file_name: str = Field(max_length=255, nullable=False)
+    file_path: str = Field(max_length=512, nullable=False)
+    file_size: int = Field(nullable=False)
+    mime_type: str = Field(max_length=100, nullable=False)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))

astrbot/core/knowledge_base/parsers/__init__.py

@@ -0,0 +1,13 @@
+"""文档解析器模块"""
+
+from .base import BaseParser, MediaItem, ParseResult
+from .pdf_parser import PDFParser
+from .text_parser import TextParser
+
+__all__ = [
+    "BaseParser",
+    "MediaItem",
+    "PDFParser",
+    "ParseResult",
+    "TextParser",
+]

astrbot/core/knowledge_base/parsers/base.py

@@ -0,0 +1,51 @@
+"""文档解析器基类和数据结构
+
+定义了文档解析器的抽象接口和相关数据类。
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass
+class MediaItem:
+    """多媒体项
+
+    表示从文档中提取的多媒体资源。
+    """
+
+    media_type: str  # image, video
+    file_name: str
+    content: bytes
+    mime_type: str
+
+
+@dataclass
+class ParseResult:
+    """解析结果
+
+    包含解析后的文本内容和提取的多媒体资源。
+    """
+
+    text: str
+    media: list[MediaItem]
+
+
+class BaseParser(ABC):
+    """文档解析器基类
+
+    所有文档解析器都应该继承此类并实现 parse 方法。
+    """
+
+    @abstractmethod
+    async def parse(self, file_content: bytes, file_name: str) -> ParseResult:
+        """解析文档
+
+        Args:
+            file_content: 文件内容
+            file_name: 文件名
+
+        Returns:
+            ParseResult: 解析结果
+
+        """

astrbot/core/knowledge_base/parsers/markitdown_parser.py

@@ -0,0 +1,26 @@
+import io
+import os
+
+from markitdown_no_magika import MarkItDown, StreamInfo
+
+from astrbot.core.knowledge_base.parsers.base import (
+    BaseParser,
+    ParseResult,
+)
+
+
+class MarkitdownParser(BaseParser):
+    """解析 docx, xls, xlsx 格式"""
+
+    async def parse(self, file_content: bytes, file_name: str) -> ParseResult:
+        md = MarkItDown(enable_plugins=False)
+        bio = io.BytesIO(file_content)
+        stream_info = StreamInfo(
+            extension=os.path.splitext(file_name)[1].lower(),
+            filename=file_name,
+        )
+        result = md.convert(bio, stream_info=stream_info)
+        return ParseResult(
+            text=result.markdown,
+            media=[],
+        )

astrbot/core/knowledge_base/parsers/pdf_parser.py

@@ -0,0 +1,101 @@
+"""PDF 文件解析器
+
+支持解析 PDF 文件中的文本和图片资源。
+"""
+
+import io
+
+from pypdf import PdfReader
+
+from astrbot.core.knowledge_base.parsers.base import (
+    BaseParser,
+    MediaItem,
+    ParseResult,
+)
+
+
+class PDFParser(BaseParser):
+    """PDF 文档解析器
+
+    提取 PDF 中的文本内容和嵌入的图片资源。
+    """
+
+    async def parse(self, file_content: bytes, file_name: str) -> ParseResult:
+        """解析 PDF 文件
+
+        Args:
+            file_content: 文件内容
+            file_name: 文件名
+
+        Returns:
+            ParseResult: 包含文本和图片的解析结果
+
+        """
+        pdf_file = io.BytesIO(file_content)
+        reader = PdfReader(pdf_file)
+
+        text_parts = []
+        media_items = []
+
+        # 提取文本
+        for page in reader.pages:
+            text = page.extract_text()
+            if text:
+                text_parts.append(text)
+
+        # 提取图片
+        image_counter = 0
+        for page_num, page in enumerate(reader.pages):
+            try:
+                # 安全检查 Resources
+                if "/Resources" not in page:
+                    continue
+
+                resources = page["/Resources"]
+                if not resources or "/XObject" not in resources:  # type: ignore
+                    continue
+
+                xobjects = resources["/XObject"].get_object()  # type: ignore
+                if not xobjects:
+                    continue
+
+                for obj_name in xobjects:
+                    try:
+                        obj = xobjects[obj_name]
+
+                        if obj.get("/Subtype") != "/Image":
+                            continue
+
+                        # 提取图片数据
+                        image_data = obj.get_data()
+
+                        # 确定格式
+                        filter_type = obj.get("/Filter", "")
+                        if filter_type == "/DCTDecode":
+                            ext = "jpg"
+                            mime_type = "image/jpeg"
+                        elif filter_type == "/FlateDecode":
+                            ext = "png"
+                            mime_type = "image/png"
+                        else:
+                            ext = "png"
+                            mime_type = "image/png"
+
+                        image_counter += 1
+                        media_items.append(
+                            MediaItem(
+                                media_type="image",
+                                file_name=f"page_{page_num}_img_{image_counter}.{ext}",
+                                content=image_data,
+                                mime_type=mime_type,
+                            ),
+                        )
+                    except Exception:
+                        # 单个图片提取失败不影响整体
+                        continue
+            except Exception:
+                # 页面处理失败不影响其他页面
+                continue
+
+        full_text = "\n\n".join(text_parts)
+        return ParseResult(text=full_text, media=media_items)

astrbot/core/knowledge_base/parsers/text_parser.py

@@ -0,0 +1,42 @@
+"""文本文件解析器
+
+支持解析 TXT 和 Markdown 文件。
+"""
+
+from astrbot.core.knowledge_base.parsers.base import BaseParser, ParseResult
+
+
+class TextParser(BaseParser):
+    """TXT/MD 文本解析器
+
+    支持多种字符编码的自动检测。
+    """
+
+    async def parse(self, file_content: bytes, file_name: str) -> ParseResult:
+        """解析文本文件
+
+        尝试使用多种编码解析文件内容。
+
+        Args:
+            file_content: 文件内容
+            file_name: 文件名
+
+        Returns:
+            ParseResult: 解析结果,不包含多媒体资源
+
+        Raises:
+            ValueError: 如果无法解码文件
+
+        """
+        # 尝试多种编码
+        for encoding in ["utf-8", "gbk", "gb2312", "gb18030"]:
+            try:
+                text = file_content.decode(encoding)
+                break
+            except UnicodeDecodeError:
+                continue
+        else:
+            raise ValueError(f"无法解码文件: {file_name}")
+
+        # 文本文件无多媒体资源
+        return ParseResult(text=text, media=[])

astrbot/core/knowledge_base/parsers/url_parser.py

@@ -0,0 +1,103 @@
+import asyncio
+
+import aiohttp
+
+
+class URLExtractor:
+    """URL 内容提取器，封装了 Tavily API 调用和密钥管理"""
+
+    def __init__(self, tavily_keys: list[str]):
+        """
+        初始化 URL 提取器
+
+        Args:
+            tavily_keys: Tavily API 密钥列表
+        """
+        if not tavily_keys:
+            raise ValueError("Error: Tavily API keys are not configured.")
+
+        self.tavily_keys = tavily_keys
+        self.tavily_key_index = 0
+        self.tavily_key_lock = asyncio.Lock()
+
+    async def _get_tavily_key(self) -> str:
+        """并发安全的从列表中获取并轮换Tavily API密钥。"""
+        async with self.tavily_key_lock:
+            key = self.tavily_keys[self.tavily_key_index]
+            self.tavily_key_index = (self.tavily_key_index + 1) % len(self.tavily_keys)
+            return key
+
+    async def extract_text_from_url(self, url: str) -> str:
+        """
+        使用 Tavily API 从 URL 提取主要文本内容。
+        这是 web_searcher 插件中 tavily_extract_web_page 方法的简化版本，
+        专门为知识库模块设计，不依赖 AstrMessageEvent。
+
+        Args:
+            url: 要提取内容的网页 URL
+
+        Returns:
+            提取的文本内容
+
+        Raises:
+            ValueError: 如果 URL 为空或 API 密钥未配置
+            IOError: 如果请求失败或返回错误
+        """
+        if not url:
+            raise ValueError("Error: url must be a non-empty string.")
+
+        tavily_key = await self._get_tavily_key()
+        api_url = "https://api.tavily.com/extract"
+        headers = {
+            "Authorization": f"Bearer {tavily_key}",
+            "Content-Type": "application/json",
+        }
+
+        payload = {
+            "urls": [url],
+            "extract_depth": "basic",  # 使用基础提取深度
+        }
+
+        try:
+            async with aiohttp.ClientSession(trust_env=True) as session:
+                async with session.post(
+                    api_url,
+                    json=payload,
+                    headers=headers,
+                    timeout=30.0,  # 增加超时时间，因为内容提取可能需要更长时间
+                ) as response:
+                    if response.status != 200:
+                        reason = await response.text()
+                        raise OSError(
+                            f"Tavily web extraction failed: {reason}, status: {response.status}"
+                        )
+
+                    data = await response.json()
+                    results = data.get("results", [])
+
+                    if not results:
+                        raise ValueError(f"No content extracted from URL: {url}")
+
+                    # 返回第一个结果的内容
+                    return results[0].get("raw_content", "")
+
+        except aiohttp.ClientError as e:
+            raise OSError(f"Failed to fetch URL {url}: {e}") from e
+        except Exception as e:
+            raise OSError(f"Failed to extract content from URL {url}: {e}") from e
+
+
+# 为了向后兼容，提供一个简单的函数接口
+async def extract_text_from_url(url: str, tavily_keys: list[str]) -> str:
+    """
+    简单的函数接口，用于从 URL 提取文本内容
+
+    Args:
+        url: 要提取内容的网页 URL
+        tavily_keys: Tavily API 密钥列表
+
+    Returns:
+        提取的文本内容
+    """
+    extractor = URLExtractor(tavily_keys)
+    return await extractor.extract_text_from_url(url)