初始化

.devcontainer/devcontainer.json

@@ -0,0 +1,31 @@
+{
+	"name": "MaiBot-DevContainer",
+	"image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
+	"features": {
+		"ghcr.io/rocker-org/devcontainer-features/apt-packages:1": {
+			"packages": [
+				"tmux"
+			]
+		},
+		"ghcr.io/devcontainers/features/github-cli:1": {}
+	},
+	"forwardPorts": [
+		"8000:8000"
+	],
+	"postCreateCommand": "pip3 install --user -r requirements.txt",
+	"customizations": {
+		"jetbrains": {
+			"backend": "PyCharm"
+		},
+		"vscode": {
+			"extensions": [
+				"tamasfe.even-better-toml",
+				"njpwerner.autodocstring",
+				"ms-python.python",
+				"KevinRose.vsc-python-indent",
+				"ms-python.vscode-pylance",
+				"ms-python.autopep8"
+			]
+		}
+	}
+}

.dockerignore

@@ -0,0 +1,10 @@
+.git
+__pycache__
+*.pyo
+*.pyd
+.DS_Store
+mongodb
+napcat
+docs/
+.github/
+# test

.envrc

@@ -0,0 +1 @@
+use flake

.gitattributes

@@ -0,0 +1,3 @@
+*.bat text eol=crlf
+*.cmd text eol=crlf
+MaiLauncher.bat text eol=crlf working-tree-encoding=GBK

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,63 @@
+name: Bug Report
+description: 提交 Bug
+labels: ["BUG"]
+body:
+- type: checkboxes
+  attributes:
+    label: "检查项"
+    description: "请检查下列项目，并勾选确认。"
+    options:
+    - label: "我确认此问题在所有分支的最新版本中依旧存在"
+      required: true
+    - label: "我确认在 Issues 列表中并无其他人已经提出过与此问题相同或相似的问题"
+      required: true
+    - label: "我使用了 Docker"
+- type: dropdown
+  attributes:
+    label: "使用的分支"
+    description: "请选择您正在使用的版本分支"
+    options:
+      - main
+      - dev
+  validations:
+    required: true
+- type: input
+  attributes:
+    label: "具体版本号"
+    description: "请输入您使用的具体版本号"
+    placeholder: "例如：0.5.11、0.5.8、0.6.0"
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: 遇到的问题
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: 报错信息
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: 如何重现此问题？
+    placeholder: "若不知道请略过此问题"
+- type: textarea
+  attributes:
+    label: 可能造成问题的原因
+    placeholder: "若不知道请略过此问题"
+- type: textarea
+  attributes:
+    label: 系统环境 
+    placeholder: "例如：Windows 11 专业版 64位 24H2 / Debian Bookworm"
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: Python 版本 
+    placeholder: "例如：Python 3.11"
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: 补充信息

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,21 @@
+name: Feature Request
+description: 新功能请求
+labels: ["Feature"]
+body:
+- type: checkboxes
+  attributes:
+    label: "检查项"
+    description: "请检查下列项目，并勾选确认。"
+    options:
+    - label: "我确认在Issues列表中并无其他人已经建议过相似的功能"
+      required: true
+    - label: "这个新功能可以解决目前存在的某个问题或BUG"
+    - label: "你已经更新了最新的dev分支，但是你的问题依然没有被解决"
+- type: textarea
+  attributes:
+    label: 期望的功能描述
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: 补充信息

.github/prompts/chat.prompt.md

@@ -0,0 +1,4 @@
+---
+mode: agent
+---
+记得执行前激活虚拟环境，用的shell是powershell与linux语法有区别

.github/pull_request_template.md

@@ -0,0 +1,17 @@
+<!-- 提交前必读 -->
+- ✅ 接受：与main直接相关的Bug修复：提交到dev分支
+- 新增功能类pr需要经过issue提前讨论，否则不会被合并
+    
+# 请填写以下内容
+（删除掉中括号内的空格，并替换为**小写的x**）
+1. - [ ] `main` 分支 **禁止修改**，请确认本次提交的分支 **不是 `main` 分支**
+2. - [ ] 我确认我阅读了贡献指南
+3. - [ ] 本次更新类型为：BUG修复
+   - [ ] 本次更新类型为：功能新增
+4. - [ ] 本次更新是否经过测试
+5. 请填写破坏性更新的具体内容（如有）:
+6. 请简要说明本次更新的内容和目的：
+# 其他信息
+- **关联 Issue**：Close #
+- **截图/GIF**：
+- **附加信息**:

.github/workflows/docker-image.yml

@@ -0,0 +1,164 @@
+name: Docker Build and Push
+
+on:
+  push:
+    branches:
+      - main
+      - classical
+      - dev
+    tags:
+      - "v*.*.*"
+      - "v*"
+      - "*.*.*"
+      - "*.*.*-*"
+  workflow_dispatch: # 允许手动触发工作流
+
+# Workflow's jobs
+jobs:
+  build-amd64:
+    name: Build AMD64 Image
+    runs-on: ubuntu-24.04
+    outputs:
+      digest: ${{ steps.build.outputs.digest }}
+    steps:
+      - name: Check out git repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # Clone required dependencies
+      - name: Clone maim_message
+        run: git clone https://github.com/MaiM-with-u/maim_message maim_message
+
+      - name: Clone lpmm
+        run: git clone https://github.com/MaiM-with-u/MaiMBot-LPMM.git MaiMBot-LPMM
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          buildkitd-flags: --debug
+
+      # Log in docker hub
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      # Generate metadata for Docker images
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ secrets.DOCKERHUB_USERNAME }}/maibot
+
+      # Build and push AMD64 image by digest
+      - name: Build and push AMD64
+        id: build
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          platforms: linux/amd64
+          labels: ${{ steps.meta.outputs.labels }}
+          file: ./Dockerfile
+          cache-from: type=registry,ref=${{ secrets.DOCKERHUB_USERNAME }}/maibot:amd64-buildcache
+          cache-to: type=registry,ref=${{ secrets.DOCKERHUB_USERNAME }}/maibot:amd64-buildcache,mode=max
+          outputs: type=image,name=${{ secrets.DOCKERHUB_USERNAME }}/maibot,push-by-digest=true,name-canonical=true,push=true
+          build-args: |
+            BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ')
+            VCS_REF=${{ github.sha }}
+
+  build-arm64:
+    name: Build ARM64 Image
+    runs-on: ubuntu-24.04-arm
+    outputs:
+      digest: ${{ steps.build.outputs.digest }}
+    steps:
+      - name: Check out git repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      # Clone required dependencies
+      - name: Clone maim_message
+        run: git clone https://github.com/MaiM-with-u/maim_message maim_message
+
+      - name: Clone lpmm
+        run: git clone https://github.com/MaiM-with-u/MaiMBot-LPMM.git MaiMBot-LPMM
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          buildkitd-flags: --debug
+
+      # Log in docker hub
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      # Generate metadata for Docker images
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ secrets.DOCKERHUB_USERNAME }}/maibot
+
+      # Build and push ARM64 image by digest
+      - name: Build and push ARM64
+        id: build
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          platforms: linux/arm64/v8
+          labels: ${{ steps.meta.outputs.labels }}
+          file: ./Dockerfile
+          cache-from: type=registry,ref=${{ secrets.DOCKERHUB_USERNAME }}/maibot:arm64-buildcache
+          cache-to: type=registry,ref=${{ secrets.DOCKERHUB_USERNAME }}/maibot:arm64-buildcache,mode=max
+          outputs: type=image,name=${{ secrets.DOCKERHUB_USERNAME }}/maibot,push-by-digest=true,name-canonical=true,push=true
+          build-args: |
+            BUILD_DATE=$(date -u +'%Y-%m-%dT%H:%M:%SZ')
+            VCS_REF=${{ github.sha }}
+
+  create-manifest:
+    name: Create Multi-Arch Manifest
+    runs-on: ubuntu-24.04
+    needs:
+      - build-amd64
+      - build-arm64
+    steps:
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      # Log in docker hub
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      # Generate metadata for Docker images
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ secrets.DOCKERHUB_USERNAME }}/maibot
+          tags: |
+            type=ref,event=branch
+            type=ref,event=tag
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=sha,prefix=${{ github.ref_name }}-,enable=${{ github.ref_type == 'branch' }}
+
+      - name: Create and Push Manifest
+        run: |
+          # 为每个标签创建多架构镜像
+          for tag in $(echo "${{ steps.meta.outputs.tags }}" | tr '\n' ' '); do
+            echo "Creating manifest for $tag"
+            docker buildx imagetools create -t $tag \
+              ${{ secrets.DOCKERHUB_USERNAME }}/maibot@${{ needs.build-amd64.outputs.digest }} \
+              ${{ secrets.DOCKERHUB_USERNAME }}/maibot@${{ needs.build-arm64.outputs.digest }}
+          done

.github/workflows/precheck.yml

@@ -0,0 +1,40 @@
+# .github/workflows/precheck.yml
+name: PR Precheck
+on: [pull_request]
+
+jobs:
+  conflict-check:
+    runs-on: [self-hosted, Windows, X64]
+    outputs:
+      conflict: ${{ steps.check-conflicts.outputs.conflict }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Check Conflicts
+        id: check-conflicts
+        run: |
+          git fetch origin main
+          $conflicts = git diff --name-only --diff-filter=U origin/main...HEAD
+          if ($conflicts) {
+            echo "conflict=true" >> $env:GITHUB_OUTPUT
+            Write-Host "Conflicts detected in files: $conflicts"
+          } else {
+            echo "conflict=false" >> $env:GITHUB_OUTPUT
+            Write-Host "No conflicts detected"
+          }
+        shell: pwsh
+  labeler:
+    runs-on: [self-hosted, Windows, X64]
+    needs: conflict-check
+    if: needs.conflict-check.outputs.conflict == 'true'
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              labels: ['🚫冲突需处理']
+            })

.github/workflows/ruff-pr.yml

@@ -0,0 +1,21 @@
+name: Ruff PR Check
+on: [ pull_request ]
+jobs:
+  ruff:
+    runs-on: [self-hosted, Windows, X64]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install Ruff and Run Checks
+        uses: astral-sh/ruff-action@v3
+        with:
+          args: "--version"
+          version: "latest"
+      - name: Run Ruff Check (No Fix)
+        run: ruff check --output-format=github
+        shell: pwsh
+      - name: Run Ruff Format Check
+        run: ruff format --check --diff
+        shell: pwsh
+

.github/workflows/ruff.yml

@@ -0,0 +1,53 @@
+name: Ruff
+
+on:
+  # push:
+  #   branches:
+  #     - main
+  #     - dev
+  #     - dev-refactor # 例如：匹配所有以 feature/ 开头的分支
+  #     # 添加你希望触发此 workflow 的其他分支
+  workflow_dispatch: # 允许手动触发工作流
+    branches:
+      - main
+      - dev
+      - dev-refactor
+
+permissions:
+  contents: write
+
+jobs:
+  ruff:
+    runs-on: [self-hosted, Windows, X64]
+    # 关键修改：添加条件判断
+    # 确保只有在 event_name 是 'push' 且不是由 Pull Request 引起的 push 时才运行
+    if: github.event_name == 'push' && !startsWith(github.ref, 'refs/pull/')
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.head_ref || github.ref_name }}
+      - name: Install Ruff and Run Checks
+        uses: astral-sh/ruff-action@v3
+        with:
+          args: "--version"
+          version: "latest"
+      - name: Run Ruff Fix
+        run: ruff check --fix --unsafe-fixes; if ($LASTEXITCODE -ne 0) { Write-Host "Ruff check completed with warnings" }
+        shell: pwsh
+      - name: Run Ruff Format
+        run: ruff format; if ($LASTEXITCODE -ne 0) { Write-Host "Ruff format completed with warnings" }
+        shell: pwsh
+      - name: 提交更改
+        if: success()
+        run: |
+          git config --local user.email "github-actions[bot]@users.noreply.github.com"
+          git config --local user.name "github-actions[bot]"
+          git add -A
+          $changes = git diff --quiet; $staged = git diff --staged --quiet
+          if (-not ($changes -and $staged)) {
+            git commit -m "🤖 自动格式化代码 [skip ci]"
+            git push
+          }
+        shell: pwsh

.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+repos:
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  # Ruff version.
+  rev: v0.9.10
+  hooks:
+    # Run the linter.
+    - id: ruff
+      args: [ --fix ]
+    # Run the formatter.
+    - id: ruff-format

Dockerfile

@@ -0,0 +1,32 @@
+FROM python:3.13.5-slim-bookworm
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# 工作目录
+WORKDIR /MaiMBot
+
+# 复制依赖列表
+COPY requirements.txt .
+# 同级目录下需要有 maim_message MaiMBot-LPMM
+#COPY maim_message /maim_message
+COPY MaiMBot-LPMM /MaiMBot-LPMM
+
+# 编译器
+RUN apt-get update && apt-get install -y build-essential
+
+# lpmm编译安装
+RUN cd /MaiMBot-LPMM && uv pip install --system -r requirements.txt
+RUN uv pip install --system Cython py-cpuinfo setuptools
+RUN cd /MaiMBot-LPMM/lib/quick_algo && python build_lib.py --cleanup --cythonize --install
+
+
+# 安装依赖
+RUN uv pip install --system --upgrade pip
+#RUN uv pip install --system -e /maim_message
+RUN uv pip install --system -r requirements.txt
+
+# 复制项目代码
+COPY . .
+
+EXPOSE 8000
+
+ENTRYPOINT [ "python","bot.py" ]

EULA.md

@@ -0,0 +1,143 @@
+# **MaiBot最终用户许可协议**  
+**版本：V1.1**  
+**更新日期：2025年7月10日**  
+**生效日期：2025年3月18日**  
+**适用的MaiBot版本号：所有版本**   
+
+**2025© MaiBot项目团队**
+
+---
+
+## 一、一般条款
+
+**1.1** MaiBot项目（包括MaiBot的源代码、可执行文件、文档，以及其它在本协议中所列出的文件）（以下简称“本项目”）是由开发者及贡献者（以下简称“项目团队”）共同维护，为用户提供自动回复功能的机器人代码项目。以下最终用户许可协议（EULA，以下简称“本协议”）是用户（以下简称“您”）与项目团队之间关于使用本项目所订立的合同条件。
+
+**1.2** 在运行或使用本项目之前，您**必须阅读并同意本协议的所有条款**。未成年人或其它无/不完全民事行为能力责任人请**在监护人的陪同下**阅读并同意本协议。如果您不同意，则不得运行或使用本项目。在这种情况下，您应立即从您的设备上卸载或删除本项目及其所有副本。
+
+
+## 二、许可授权
+
+### 源代码许可
+**2.1** 您**了解**本项目的源代码是基于GPLv3（GNU通用公共许可证第三版）开源协议发布的。您**可以自由使用、修改、分发**本项目的源代码，但**必须遵守**GPLv3许可证的要求。详细内容请参阅项目仓库中的LICENSE文件。
+
+**2.2** 您**了解**本项目的源代码中可能包含第三方开源代码，这些代码的许可证可能与GPLv3许可证不同。您**同意**在使用这些代码时**遵守**相应的许可证要求。
+
+
+### 输入输出内容授权
+
+**2.3** 您**了解**本项目是使用您的配置信息、提交的指令（以下简称“输入内容”）和生成的内容（以下简称“输出内容”）构建请求发送到第三方API生成回复的机器人项目。
+
+**2.4** 您**授权**本项目使用您的输入和输出内容按照项目的隐私政策用于以下行为：
+   - 调用第三方API生成回复；
+   - 调用第三方API用于构建本项目专用的存储于您部署或使用的数据库中的知识库和记忆库；
+   - 收集并记录本项目专用的存储于您部署或使用的设备中的日志；
+
+**2.4** 您**了解**本项目的源代码中包含第三方API的调用代码，这些API的使用可能受到第三方的服务条款和隐私政策的约束。在使用这些API时，您**必须遵守**相应的服务条款。
+
+**2.5** 项目团队**不对**第三方API的服务质量、稳定性、准确性、安全性负责，亦**不对**第三方API的服务变更、终止、限制等行为负责。
+
+
+### 插件系统授权和责任免责
+
+**2.6** 您**了解**本项目包含插件系统功能，允许加载和使用由第三方开发者（非MaiBot核心开发组成员）开发的插件。这些第三方插件可能具有独立的许可证条款和使用协议。
+
+**2.7** 您**了解并同意**：
+   - 第三方插件的开发、维护、分发由其各自的开发者负责，**与MaiBot项目团队无关**；
+   - 第三方插件的功能、质量、安全性、合规性**完全由插件开发者负责**；
+   - MaiBot项目团队**仅提供**插件系统的技术框架，**不对**任何第三方插件的内容、行为或后果承担责任；
+   - 您使用任何第三方插件的风险**完全由您自行承担**；
+
+**2.8** 在使用第三方插件前，您**应当**：
+   - 仔细阅读并遵守插件开发者提供的许可证条款和使用协议；
+   - 自行评估插件的安全性、合规性和适用性；
+   - 确保插件的使用符合您所在地区的法律法规要求；
+
+
+## 三、用户行为
+
+**3.1** 您**了解**本项目会将您的配置信息、输入指令和生成内容发送到第三方API，您**不应**在输入指令和生成内容中包含以下内容：
+   - 涉及任何国家或地区秘密、商业秘密或其他可能会对国家或地区安全或者公共利益造成不利影响的数据；
+   - 涉及个人隐私、个人信息或其他敏感信息的数据；
+   - 任何侵犯他人合法权益的内容；
+   - 任何违反国家或地区法律法规、政策规定的内容；
+
+**3.2** 您**不应**将本项目用于以下用途：
+  - 违反任何国家或地区法律法规、政策规定的行为；
+
+**3.3** 您**应当**自行确保您被存储在本项目的知识库、记忆库和日志中的输入和输出内容的合法性与合规性以及存储行为的合法性与合规性。您需**自行承担**由此产生的任何法律责任。
+
+**3.4** 对于第三方插件的使用，您**不应**：
+   - 使用可能存在安全漏洞、恶意代码或违法内容的插件；
+   - 通过插件进行任何违反法律法规的行为；
+   - 将插件用于侵犯他人权益或危害系统安全的用途；
+
+**3.5** 您**承诺**对使用第三方插件的行为及其后果承担**完全责任**，包括但不限于因插件缺陷、恶意行为或不当使用造成的任何损失或法律纠纷。
+
+
+
+## 四、免责条款
+
+**4.1** 本项目的输出内容依赖第三方API，**不受**项目团队控制，亦**不代表**项目团队的观点。
+
+**4.2** 除本协议条目2.4提到的隐私政策之外，项目团队**不会**对您提供任何形式的担保，亦**不对**使用本项目的造成的任何后果负责。
+
+**4.3** 关于第三方插件，项目团队**明确声明**：
+   - 项目团队**不对**任何第三方插件的功能、安全性、稳定性、合规性或适用性提供任何形式的保证或担保；
+   - 项目团队**不对**因使用第三方插件而产生的任何直接或间接损失、数据丢失、系统故障、安全漏洞、法律纠纷或其他后果承担责任；
+   - 第三方插件的质量问题、技术支持、bug修复等事宜应**直接联系插件开发者**，与项目团队无关；
+   - 项目团队**保留**在不另行通知的情况下，对插件系统功能进行修改、限制或移除的权利；
+
+## 五、其他条款
+
+**5.1** 项目团队有权**随时修改本协议的条款**，但**没有**义务通知您。修改后的协议将在本项目的新版本中生效，您应定期检查本协议的最新版本。
+
+**5.2** 项目团队**保留**本协议的最终解释权。
+
+
+## 附录：其他重要须知
+
+### 一、过往版本使用条件追溯
+
+**1.1** 对于本项目此前未配备 EULA 协议的版本，自本协议发布之日起，若用户希望继续使用本项目，应在本协议生效后的合理时间内，通过升级到最新版本并同意本协议全部条款。若在本版协议生效日（2025年3月18日）之后，用户仍使用此前无 EULA 协议的项目版本且未同意本协议，则用户无权继续使用，项目方有权采取措施阻止其使用行为，并保留追究相关法律责任的权利。
+
+
+### 二、风险提示
+
+**2.1 隐私安全风险** 
+
+   - 本项目会将您的配置信息、输入指令和生成内容发送到第三方API，而这些API的服务质量、稳定性、准确性、安全性不受项目团队控制。
+   - 本项目会收集您的输入和输出内容，用于构建本项目专用的知识库和记忆库，以提高回复的准确性和连贯性。
+
+      **因此，为了保障您的隐私信息安全，请注意以下事项：**
+
+   - 避免在涉及个人隐私、个人信息或其他敏感信息的环境中使用本项目；
+   - 避免在不可信的环境中使用本项目；
+
+**2.2 精神健康风险** 
+
+本项目仅为工具型机器人，不具备情感交互能力。建议用户：
+   - 避免过度依赖AI回复处理现实问题或情绪困扰；  
+   - 如感到心理不适，请及时寻求专业心理咨询服务。 
+   - 如遇心理困扰，请寻求专业帮助（全国心理援助热线：12355）。   
+
+**2.3 第三方插件风险**
+
+本项目的插件系统允许加载第三方开发的插件，这可能带来以下风险：
+   - **安全风险**：第三方插件可能包含恶意代码、安全漏洞或未知的安全威胁；
+   - **稳定性风险**：插件可能导致系统崩溃、性能下降或功能异常；
+   - **隐私风险**：插件可能收集、传输或泄露您的个人信息和数据；
+   - **合规风险**：插件的功能或行为可能违反相关法律法规或平台规则；
+   - **兼容性风险**：插件可能与主程序或其他插件产生冲突；
+
+      **因此，在使用第三方插件时，请务必：**
+
+   - 仅从可信来源获取和安装插件；
+   - 在安装前仔细了解插件的功能、权限和开发者信息；
+   - 定期检查和更新已安装的插件；
+   - 如发现插件异常行为，请立即停止使用并卸载；
+   - 对插件的使用后果承担完全责任；   
+
+### 三、其他
+**3.1 争议解决**
+   - 本协议适用中国法律，争议提交相关地区法院管辖；  
+   - 若因GPLv3许可产生纠纷，以许可证官方解释为准。  

LICENSE

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

MaiBot-Napcat-Adapter-dev/.devcontainer/devcontainer.json

@@ -0,0 +1,21 @@
+{
+	"name": "MaiBot-Napcat-Adapter-DevContainer",
+	"image": "mcr.microsoft.com/devcontainers/python:1-3.12-bullseye",
+	"features": {
+		"ghcr.io/rocker-org/devcontainer-features/apt-packages:1": {
+			"packages": [
+				"tmux"
+			]
+		},
+		"ghcr.io/devcontainers/features/github-cli:1": {}
+	},
+	"forwardPorts": [
+		"8095:8095"
+	],
+	"postCreateCommand": "pip3 install --user -r requirements.txt",
+  "customizations" : {
+    "jetbrains" : {
+      "backend" : "PyCharm"
+    }
+  }
+}

MaiBot-Napcat-Adapter-dev/.github/workflows/docker-image.yml

@@ -0,0 +1,54 @@
+name: Docker Image CI
+
+on:
+  push:
+    branches: [ "main", "dev" ]
+  workflow_dispatch: # 允许手动触发工作流
+
+jobs:
+
+  build:
+
+    runs-on: ubuntu-latest
+    env:
+      DOCKERHUB_USER: ${{ secrets.DOCKERHUB_USERNAME }}
+      DATE_TAG: $(date -u +'%Y-%m-%dT%H-%M-%S')
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Login to Docker Hub
+      uses: docker/login-action@v3
+      with:
+        username: ${{ secrets.DOCKERHUB_USERNAME }}
+        password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+    - name: Clone maim_message
+      run: git clone https://github.com/MaiM-with-u/maim_message maim_message
+
+    - name: Determine Image Tags
+      id: tags
+      run: |
+        if [ "${{ github.ref_name }}" == "main" ]; then
+          echo "tags=${{ secrets.DOCKERHUB_USERNAME }}/maimbot-adapter:latest,${{ secrets.DOCKERHUB_USERNAME }}/maimbot-adapter:main-$(date -u +'%Y%m%d%H%M%S')" >> $GITHUB_OUTPUT
+        elif [ "${{ github.ref_name }}" == "dev" ]; then
+          echo "tags=${{ secrets.DOCKERHUB_USERNAME }}/maimbot-adapter:dev,${{ secrets.DOCKERHUB_USERNAME }}/maimbot-adapter:dev-$(date -u +'%Y%m%d%H%M%S')" >> $GITHUB_OUTPUT
+        fi
+
+    - name: Build and Push Docker Image
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        file: ./Dockerfile
+        platforms: linux/amd64,linux/arm64
+        tags: ${{ steps.tags.outputs.tags }}
+        push: true
+        cache-from: type=registry,ref=${{ secrets.DOCKERHUB_USERNAME }}/maimbot-adapter:buildcache-${{ github.ref_name }}
+        cache-to: type=registry,ref=${{ secrets.DOCKERHUB_USERNAME }}/maimbot-adapter:buildcache-${{ github.ref_name }},mode=max
+        labels: |
+          org.opencontainers.image.created=${{ steps.tags.outputs.date_tag }}
+          org.opencontainers.image.revision=${{ github.sha }}

MaiBot-Napcat-Adapter-dev/.gitignore

@@ -0,0 +1,277 @@
+
+log/
+logs/
+out/
+
+.env
+.env.*
+.cursor
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+llm_statistics.txt
+mongodb
+napcat
+run_dev.bat
+elua.confirmed
+# C extensions
+*.so
+/results
+config_backup/
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# PyPI configuration file
+.pypirc
+
+# jieba
+jieba.cache
+
+# .vscode
+!.vscode/settings.json
+
+# direnv
+/.direnv
+
+# JetBrains
+.idea
+*.iml
+*.ipr
+
+# PyEnv
+#  If using PyEnv and configured to use a specific Python version locally
+#  a .local-version file will be created in the root of the project to specify the version.
+.python-version
+
+OtherRes.txt
+
+/eula.confirmed
+/privacy.confirmed
+
+logs
+
+.ruff_cache
+
+.vscode
+
+/config/*
+config/old/bot_config_20250405_212257.toml
+temp/
+
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+config.toml
+config.toml.back
+test
+data/NapcatAdapter.db
+data/NapcatAdapter.db-shm
+data/NapcatAdapter.db-wal

MaiBot-Napcat-Adapter-dev/Dockerfile

@@ -0,0 +1,20 @@
+FROM python:3.13.5-slim
+LABEL authors="infinitycat233"
+
+# Copy uv and maim_message
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+COPY maim_message /maim_message
+COPY requirements.txt /requirements.txt
+
+# Install requirements
+RUN uv pip install --system --upgrade pip
+RUN uv pip install --system -e /maim_message
+RUN uv pip install --system -r /requirements.txt
+
+WORKDIR /adapters
+
+COPY . .
+
+EXPOSE 8095
+
+ENTRYPOINT ["python", "main.py"]

MaiBot-Napcat-Adapter-dev/LICENSE

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

MaiBot-Napcat-Adapter-dev/README.md

@@ -0,0 +1,83 @@
+# MaiBot 与 Napcat 的 Adapter
+运行方式：独立/放在MaiBot本体作为插件
+
+# 使用说明
+请参考[官方文档](https://docs.mai-mai.org/manual/adapters/napcat.html)
+
+# 消息流转过程
+
+```mermaid
+sequenceDiagram
+    participant Napcat as Napcat客户端
+    participant Adapter as MaiBot-Napcat适配器
+    participant Queue as 消息队列
+    participant Handler as 消息处理器
+    participant MaiBot as MaiBot服务
+
+    Note over Napcat,MaiBot: 初始化阶段
+    Napcat->>Adapter: WebSocket连接(ws://localhost:8095)
+    Adapter->>MaiBot: WebSocket连接(ws://localhost:8000)
+    
+    Note over Napcat,MaiBot: 心跳检测
+    loop 每30秒
+        Napcat->>Adapter: 发送心跳包
+        Adapter->>Napcat: 心跳响应
+    end
+
+    Note over Napcat,MaiBot: 消息处理流程
+    Napcat->>Adapter: 发送消息
+    Adapter->>Queue: 消息入队(message_queue)
+    Queue->>Handler: 消息出队处理
+    Handler->>Handler: 解析消息类型
+    alt 文本消息
+        Handler->>MaiBot: 发送文本消息
+    else 图片消息
+        Handler->>MaiBot: 发送图片消息
+    else 混合消息
+        Handler->>MaiBot: 发送混合消息
+    else 转发消息
+        Handler->>MaiBot: 发送转发消息
+    end
+    MaiBot-->>Adapter: 消息响应
+    Adapter-->>Napcat: 消息响应
+
+    Note over Napcat,MaiBot: 优雅关闭
+    Adapter->>MaiBot: 关闭连接
+    Adapter->>Queue: 清空消息队列
+    Adapter->>Napcat: 关闭连接
+```
+
+
+# TO DO List
+- [x] 读取自动心跳测试连接
+- [x] 接受消息解析
+  - [x] 文本解析
+  - [x] 图片解析
+  - [x] 文本与消息混合解析
+  - [x] 转发解析（含图片动态解析）
+  - [ ] 群公告解析
+  - [x] 回复解析
+  - [ ] 群临时消息（可能不做）
+  - [ ] 链接解析
+  - [x] 戳一戳解析
+    - [x] 读取戳一戳的自定义内容
+  - [ ] 语音解析（？）
+  - [ ] 所有的notice类
+    - [x] 撤回（已添加相关指令）
+- [x] 发送消息
+  - [x] 发送文本
+  - [x] 发送图片
+  - [x] 发送表情包
+  - [x] 引用回复（完成但是没测试）
+  - [ ] 戳回去（？）
+  - [x] 发送语音
+- [x] 使用echo与uuid保证消息顺序
+- [x] 执行部分管理员功能
+  - [x] 禁言别人
+  - [x] 全体禁言
+  - [x] 群踢人功能
+
+  # 特别鸣谢
+  特别感谢[@Maple127667](https://github.com/Maple127667)对本项目代码思路的支持
+
+  以及[@墨梓柒](https://github.com/DrSmoothl)对部分代码想法的支持

MaiBot-Napcat-Adapter-dev/command_args.md

@@ -0,0 +1,60 @@
+# Command Arguments
+```python
+Seg.type = "command"
+```
+## 群聊禁言
+```python
+Seg.data: Dict[str, Any] = {
+    "name": "GROUP_BAN",
+    "args": {
+        "qq_id": "用户QQ号",
+        "duration": "禁言时长（秒）"
+    },
+}
+```
+其中，群聊ID将会通过Group_Info.group_id自动获取。
+
+**当`duration`为 0 时相当于解除禁言。**
+## 群聊全体禁言
+```python
+Seg.data: Dict[str, Any] = {
+    "name": "GROUP_WHOLE_BAN",
+    "args": {
+        "enable": "是否开启全体禁言（True/False）"
+    },
+}
+```
+其中，群聊ID将会通过Group_Info.group_id自动获取。
+
+`enable`的参数需要为boolean类型，True表示开启全体禁言，False表示关闭全体禁言。
+## 群聊踢人
+```python
+Seg.data: Dict[str, Any] = {
+    "name": "GROUP_KICK",
+    "args": {
+        "qq_id": "用户QQ号",
+    },
+}
+```
+其中，群聊ID将会通过Group_Info.group_id自动获取。
+
+## 戳一戳
+```python
+Seg.data: Dict[str, Any] = {
+    "name": "SEND_POKE",
+    "args": {
+        "qq_id": "目标QQ号"
+    }
+}
+```
+
+## 撤回消息
+```python
+Seg.data: Dict[str, Any] = {
+    "name": "DELETE_MSG",
+    "args": {
+        "message_id": "消息所对应的message_id"
+    }
+}
+```
+其中message_id是消息的实际qq_id，于新版的mmc中可以从数据库获取（如果工作正常的话）

MaiBot-Napcat-Adapter-dev/main.py

@@ -0,0 +1,90 @@
+import asyncio
+import sys
+import json
+import websockets as Server
+from src.logger import logger
+from src.recv_handler.message_handler import message_handler
+from src.recv_handler.meta_event_handler import meta_event_handler
+from src.recv_handler.notice_handler import notice_handler
+from src.recv_handler.message_sending import message_send_instance
+from src.send_handler import send_handler
+from src.config import global_config
+from src.mmc_com_layer import mmc_start_com, mmc_stop_com, router
+from src.response_pool import put_response, check_timeout_response
+
+message_queue = asyncio.Queue()
+
+
+async def message_recv(server_connection: Server.ServerConnection):
+    await message_handler.set_server_connection(server_connection)
+    asyncio.create_task(notice_handler.set_server_connection(server_connection))
+    await send_handler.set_server_connection(server_connection)
+    async for raw_message in server_connection:
+        logger.debug(f"{raw_message[:1500]}..." if (len(raw_message) > 1500) else raw_message)
+        decoded_raw_message: dict = json.loads(raw_message)
+        post_type = decoded_raw_message.get("post_type")
+        if post_type in ["meta_event", "message", "notice"]:
+            await message_queue.put(decoded_raw_message)
+        elif post_type is None:
+            await put_response(decoded_raw_message)
+
+
+async def message_process():
+    while True:
+        message = await message_queue.get()
+        post_type = message.get("post_type")
+        if post_type == "message":
+            await message_handler.handle_raw_message(message)
+        elif post_type == "meta_event":
+            await meta_event_handler.handle_meta_event(message)
+        elif post_type == "notice":
+            await notice_handler.handle_notice(message)
+        else:
+            logger.warning(f"未知的post_type: {post_type}")
+        message_queue.task_done()
+        await asyncio.sleep(0.05)
+
+
+async def main():
+    message_send_instance.maibot_router = router
+    _ = await asyncio.gather(napcat_server(), mmc_start_com(), message_process(), check_timeout_response())
+
+
+async def napcat_server():
+    logger.info("正在启动adapter...")
+    async with Server.serve(message_recv, global_config.napcat_server.host, global_config.napcat_server.port, max_size=2**26) as server:
+        logger.info(
+            f"Adapter已启动，监听地址: ws://{global_config.napcat_server.host}:{global_config.napcat_server.port}"
+        )
+        await server.serve_forever()
+
+
+async def graceful_shutdown():
+    try:
+        logger.info("正在关闭adapter...")
+        tasks = [t for t in asyncio.all_tasks() if t is not asyncio.current_task()]
+        for task in tasks:
+            if not task.done():
+                task.cancel()
+        await asyncio.wait_for(asyncio.gather(*tasks, return_exceptions=True), 15)
+        await mmc_stop_com()  # 后置避免神秘exception
+        logger.info("Adapter已成功关闭")
+    except Exception as e:
+        logger.error(f"Adapter关闭中出现错误: {e}")
+
+
+if __name__ == "__main__":
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        loop.run_until_complete(main())
+    except KeyboardInterrupt:
+        logger.warning("收到中断信号，正在优雅关闭...")
+        loop.run_until_complete(graceful_shutdown())
+    except Exception as e:
+        logger.exception(f"主程序异常: {str(e)}")
+        sys.exit(1)
+    finally:
+        if loop and not loop.is_closed():
+            loop.close()
+        sys.exit(0)

MaiBot-Napcat-Adapter-dev/notify_args.md

@@ -0,0 +1,44 @@
+# Notify Args
+```python
+Seg.type = "notify"
+```
+## 群聊成员被禁言
+```python
+Seg.data: Dict[str, Any] = {
+    "sub_type": "ban",
+    "duration": "对应的禁言时间，单位为秒",
+    "banned_user_info": "被禁言的用户的信息，为标准UserInfo转换成的字典"
+}
+```
+此时`MessageBase.UserInfo`，即消息的`UserInfo`为操作者(operator)的信息
+
+**注意: `banned_user_info`需要自行调用`UserInfo.from_dict()`函数转换为标准UserInfo对象**
+## 群聊开启全体禁言
+```python
+Seg.data: Dict[str, Any] = {
+    "sub_type": "whole_ban",
+    "duration": -1,
+    "banned_user_info": None
+}
+```
+此时`MessageBase.UserInfo`，即消息的`UserInfo`为操作者(operator)的信息
+## 群聊成员被解除禁言
+```python
+Seg.data: Dict[str, Any] = {
+    "sub_type": "whole_lift_ban",
+    "lifted_user_info": "被解除禁言的用户的信息，为标准UserInfo对象"
+}
+```
+**对于自然禁言解除的情况，此时`MessageBase.UserInfo`为`None`**
+
+对于手动解除禁言的情况，此时`MessageBase.UserInfo`，即消息的`UserInfo`为操作者(operator)的信息
+
+**注意: `lifted_user_info`需要自行调用`UserInfo.from_dict()`函数转换为标准UserInfo对象**
+## 群聊关闭全体禁言
+```python
+Seg.data: Dict[str, Any] = {
+    "sub_type": "whole_lift_ban",
+    "lifted_user_info": None,
+}
+```
+此时`MessageBase.UserInfo`，即消息的`UserInfo`为操作者(operator)的信息

MaiBot-Napcat-Adapter-dev/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "MaiBotNapcatAdapter"
+version = "0.4.7"
+description = "A MaiBot adapter for Napcat"
+
+[tool.ruff]
+
+include = ["*.py"]
+
+# 行长度设置
+line-length = 120
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+unfixable = []
+
+# 启用的规则
+select = [
+    "E", # pycodestyle 错误
+    "F", # pyflakes
+    "B", # flake8-bugbear
+]
+
+ignore = ["E711","E501"]
+
+[tool.ruff.format]
+docstring-code-format = true
+indent-style = "space"
+
+
+# 使用双引号表示字符串
+quote-style = "double"
+
+# 尊重魔法尾随逗号
+# 例如：
+# items = [
+#     "apple",
+#     "banana",
+#     "cherry",
+# ]
+skip-magic-trailing-comma = false
+
+# 自动检测合适的换行符
+line-ending = "auto"

MaiBot-Napcat-Adapter-dev/requirements.txt

@@ -0,0 +1,10 @@
+websockets
+aiohttp
+asyncio
+requests
+maim_message
+loguru
+pillow
+tomlkit
+rich
+sqlmodel

MaiBot-Napcat-Adapter-dev/src/__init__.py

@@ -0,0 +1,24 @@
+from enum import Enum
+import tomlkit
+import os
+from .logger import logger
+
+
+class CommandType(Enum):
+    """命令类型"""
+
+    GROUP_BAN = "set_group_ban"  # 禁言用户
+    GROUP_WHOLE_BAN = "set_group_whole_ban"  # 群全体禁言
+    GROUP_KICK = "set_group_kick"  # 踢出群聊
+    SEND_POKE = "send_poke"  # 戳一戳
+    DELETE_MSG = "delete_msg"  # 撤回消息
+    AI_VOICE_SEND = "send_group_ai_record"  # 发送群AI语音
+
+    def __str__(self) -> str:
+        return self.value
+
+
+pyproject_path = os.path.join(os.path.dirname(os.path.dirname(__file__)), "pyproject.toml")
+toml_data = tomlkit.parse(open(pyproject_path, "r", encoding="utf-8").read())
+version = toml_data["project"]["version"]
+logger.info(f"版本\n\nMaiBot-Napcat-Adapter 版本: {version}\n喜欢的话点个star喵~\n")

MaiBot-Napcat-Adapter-dev/src/config/__init__.py

@@ -0,0 +1,5 @@
+from .config import global_config
+
+__all__ = [
+    "global_config",
+]

MaiBot-Napcat-Adapter-dev/src/config/config.py

@@ -0,0 +1,146 @@
+import os
+from dataclasses import dataclass
+from datetime import datetime
+
+import tomlkit
+import shutil
+
+from tomlkit import TOMLDocument
+from tomlkit.items import Table
+from ..logger import logger
+from rich.traceback import install
+
+from src.config.config_base import ConfigBase
+from src.config.official_configs import (
+    ChatConfig,
+    DebugConfig,
+    MaiBotServerConfig,
+    NapcatServerConfig,
+    NicknameConfig,
+    VoiceConfig,
+)
+
+install(extra_lines=3)
+
+TEMPLATE_DIR = "template"
+
+
+def update_config():
+    # 定义文件路径
+    template_path = f"{TEMPLATE_DIR}/template_config.toml"
+    old_config_path = "config.toml"
+    new_config_path = "config.toml"
+
+    # 检查配置文件是否存在
+    if not os.path.exists(old_config_path):
+        logger.info("配置文件不存在，从模板创建新配置")
+        shutil.copy2(template_path, old_config_path)  # 复制模板文件
+        logger.info(f"已创建新配置文件，请填写后重新运行: {old_config_path}")
+        # 如果是新创建的配置文件,直接返回
+        quit()
+
+    # 读取旧配置文件和模板文件
+    with open(old_config_path, "r", encoding="utf-8") as f:
+        old_config = tomlkit.load(f)
+    with open(template_path, "r", encoding="utf-8") as f:
+        new_config = tomlkit.load(f)
+
+    # 检查version是否相同
+    if old_config and "inner" in old_config and "inner" in new_config:
+        old_version = old_config["inner"].get("version")
+        new_version = new_config["inner"].get("version")
+        if old_version and new_version and old_version == new_version:
+            logger.info(f"检测到配置文件版本号相同 (v{old_version})，跳过更新")
+            return
+        else:
+            logger.info(f"检测到版本号不同: 旧版本 v{old_version} -> 新版本 v{new_version}")
+    else:
+        logger.info("已有配置文件未检测到版本号，可能是旧版本。将进行更新")
+
+    # 创建备份文件夹
+    backup_dir = "config_backup"
+    os.makedirs(backup_dir, exist_ok=True)
+
+    # 备份文件名
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    old_backup_path = os.path.join(backup_dir, f"config.toml.bak.{timestamp}")
+
+    # 备份旧配置文件
+    shutil.copy2(old_config_path, old_backup_path)
+    logger.info(f"已备份旧配置文件到: {old_backup_path}")
+
+    # 复制模板文件到配置目录
+    shutil.copy2(template_path, new_config_path)
+    logger.info(f"已创建新配置文件: {new_config_path}")
+
+    def update_dict(target: TOMLDocument | dict, source: TOMLDocument | dict):
+        """
+        将source字典的值更新到target字典中（如果target中存在相同的键）
+        """
+        for key, value in source.items():
+            # 跳过version字段的更新
+            if key == "version":
+                continue
+            if key in target:
+                if isinstance(value, dict) and isinstance(target[key], (dict, Table)):
+                    update_dict(target[key], value)
+                else:
+                    try:
+                        # 对数组类型进行特殊处理
+                        if isinstance(value, list):
+                            # 如果是空数组，确保它保持为空数组
+                            target[key] = tomlkit.array(str(value)) if value else tomlkit.array()
+                        else:
+                            # 其他类型使用item方法创建新值
+                            target[key] = tomlkit.item(value)
+                    except (TypeError, ValueError):
+                        # 如果转换失败，直接赋值
+                        target[key] = value
+
+    # 将旧配置的值更新到新配置中
+    logger.info("开始合并新旧配置...")
+    update_dict(new_config, old_config)
+
+    # 保存更新后的配置（保留注释和格式）
+    with open(new_config_path, "w", encoding="utf-8") as f:
+        f.write(tomlkit.dumps(new_config))
+    logger.info("配置文件更新完成，建议检查新配置文件中的内容，以免丢失重要信息")
+    quit()
+
+
+@dataclass
+class Config(ConfigBase):
+    """总配置类"""
+
+    nickname: NicknameConfig
+    napcat_server: NapcatServerConfig
+    maibot_server: MaiBotServerConfig
+    chat: ChatConfig
+    voice: VoiceConfig
+    debug: DebugConfig
+
+
+def load_config(config_path: str) -> Config:
+    """
+    加载配置文件
+    :param config_path: 配置文件路径
+    :return: Config对象
+    """
+    # 读取配置文件
+    with open(config_path, "r", encoding="utf-8") as f:
+        config_data = tomlkit.load(f)
+
+    # 创建Config对象
+    try:
+        return Config.from_dict(config_data)
+    except Exception as e:
+        logger.critical("配置文件解析失败")
+        raise e
+
+
+# 更新配置
+update_config()
+
+logger.info("正在品鉴配置文件...")
+global_config = load_config(config_path="config.toml")
+logger.info("非常的新鲜，非常的美味！")

MaiBot-Napcat-Adapter-dev/src/config/config_base.py

@@ -0,0 +1,136 @@
+from dataclasses import dataclass, fields, MISSING
+from typing import TypeVar, Type, Any, get_origin, get_args, Literal, Dict, Union
+
+T = TypeVar("T", bound="ConfigBase")
+
+TOML_DICT_TYPE = {
+    int,
+    float,
+    str,
+    bool,
+    list,
+    dict,
+}
+
+
+@dataclass
+class ConfigBase:
+    """配置类的基类"""
+
+    @classmethod
+    def from_dict(cls: Type[T], data: Dict[str, Any]) -> T:
+        """从字典加载配置字段"""
+        if not isinstance(data, dict):
+            raise TypeError(f"Expected a dictionary, got {type(data).__name__}")
+
+        init_args: Dict[str, Any] = {}
+
+        for f in fields(cls):
+            field_name = f.name
+            field_type = f.type
+            if field_name.startswith("_"):
+                # 跳过以 _ 开头的字段
+                continue
+
+            if field_name not in data:
+                if f.default is not MISSING or f.default_factory is not MISSING:
+                    # 跳过未提供且有默认值/默认构造方法的字段
+                    continue
+                else:
+                    raise ValueError(f"Missing required field: '{field_name}'")
+
+            value = data[field_name]
+            try:
+                init_args[field_name] = cls._convert_field(value, field_type)
+            except TypeError as e:
+                raise TypeError(f"字段 '{field_name}' 出现类型错误: {e}") from e
+            except Exception as e:
+                raise RuntimeError(f"无法将字段 '{field_name}' 转换为目标类型，出现错误: {e}") from e
+
+        return cls(**init_args)
+
+    @classmethod
+    def _convert_field(cls, value: Any, field_type: Type[Any]) -> Any:
+        """
+        转换字段值为指定类型
+
+        1. 对于嵌套的 dataclass，递归调用相应的 from_dict 方法
+        2. 对于泛型集合类型（list, set, tuple），递归转换每个元素
+        3. 对于基础类型（int, str, float, bool），直接转换
+        4. 对于其他类型，尝试直接转换，如果失败则抛出异常
+        """
+        # 如果是嵌套的 dataclass，递归调用 from_dict 方法
+        if isinstance(field_type, type) and issubclass(field_type, ConfigBase):
+            return field_type.from_dict(value)
+
+        field_origin_type = get_origin(field_type)
+        field_args_type = get_args(field_type)
+
+        # 处理泛型集合类型（list, set, tuple）
+        if field_origin_type in {list, set, tuple}:
+            # 检查提供的value是否为list
+            if not isinstance(value, list):
+                raise TypeError(f"Expected an list for {field_type.__name__}, got {type(value).__name__}")
+
+            if field_origin_type is list:
+                return [cls._convert_field(item, field_args_type[0]) for item in value]
+            if field_origin_type is set:
+                return {cls._convert_field(item, field_args_type[0]) for item in value}
+            if field_origin_type is tuple:
+                # 检查提供的value长度是否与类型参数一致
+                if len(value) != len(field_args_type):
+                    raise TypeError(
+                        f"Expected {len(field_args_type)} items for {field_type.__name__}, got {len(value)}"
+                    )
+                return tuple(cls._convert_field(item, arg_type) for item, arg_type in zip(value, field_args_type))
+
+        if field_origin_type is dict:
+            # 检查提供的value是否为dict
+            if not isinstance(value, dict):
+                raise TypeError(f"Expected a dictionary for {field_type.__name__}, got {type(value).__name__}")
+
+            # 检查字典的键值类型
+            if len(field_args_type) != 2:
+                raise TypeError(f"Expected a dictionary with two type arguments for {field_type.__name__}")
+            key_type, value_type = field_args_type
+
+            return {cls._convert_field(k, key_type): cls._convert_field(v, value_type) for k, v in value.items()}
+
+        # 处理Optional类型
+        if field_origin_type is Union:  # assert get_origin(Optional[Any]) is Union
+            if value is None:
+                return None
+            # 如果有数据，检查实际类型
+            if type(value) not in field_args_type:
+                raise TypeError(f"Expected {field_args_type} for {field_type.__name__}, got {type(value).__name__}")
+            return cls._convert_field(value, field_args_type[0])
+
+        # 处理int, str, float, bool等基础类型
+        if field_origin_type is None:
+            if isinstance(value, field_type):
+                return field_type(value)
+            else:
+                raise TypeError(f"Expected {field_type.__name__}, got {type(value).__name__}")
+
+        # 处理Literal类型
+        if field_origin_type is Literal:
+            # 获取Literal的允许值
+            allowed_values = get_args(field_type)
+            if value in allowed_values:
+                return value
+            else:
+                raise TypeError(f"Value '{value}' is not in allowed values {allowed_values} for Literal type")
+
+        # 处理其他类型
+        if field_type is Any:
+            return value
+
+        # 其他类型直接转换
+        try:
+            return field_type(value)
+        except (ValueError, TypeError) as e:
+            raise TypeError(f"无法将 {type(value).__name__} 转换为 {field_type.__name__}") from e
+
+    def __str__(self):
+        """返回配置类的字符串表示"""
+        return f"{self.__class__.__name__}({', '.join(f'{f.name}={getattr(self, f.name)}' for f in fields(self))})"

MaiBot-Napcat-Adapter-dev/src/config/official_configs.py

@@ -0,0 +1,80 @@
+from dataclasses import dataclass, field
+from typing import Literal
+
+from src.config.config_base import ConfigBase
+
+"""
+须知：
+1. 本文件中记录了所有的配置项
+2. 所有新增的class都需要继承自ConfigBase
+3. 所有新增的class都应在config.py中的Config类中添加字段
+4. 对于新增的字段，若为可选项，则应在其后添加field()并设置default_factory或default
+"""
+
+ADAPTER_PLATFORM = "qq"
+
+
+@dataclass
+class NicknameConfig(ConfigBase):
+    nickname: str
+    """机器人昵称"""
+
+
+@dataclass
+class NapcatServerConfig(ConfigBase):
+    host: str = "localhost"
+    """Napcat服务端的主机地址"""
+
+    port: int = 8095
+    """Napcat服务端的端口号"""
+
+    heartbeat_interval: int = 30
+    """Napcat心跳间隔时间，单位为秒"""
+
+
+@dataclass
+class MaiBotServerConfig(ConfigBase):
+    platform_name: str = field(default=ADAPTER_PLATFORM, init=False)
+    """平台名称，“qq”"""
+
+    host: str = "localhost"
+    """MaiMCore的主机地址"""
+
+    port: int = 8000
+    """MaiMCore的端口号"""
+
+
+@dataclass
+class ChatConfig(ConfigBase):
+    group_list_type: Literal["whitelist", "blacklist"] = "whitelist"
+    """群聊列表类型 白名单/黑名单"""
+
+    group_list: list[int] = field(default_factory=[])
+    """群聊列表"""
+
+    private_list_type: Literal["whitelist", "blacklist"] = "whitelist"
+    """私聊列表类型 白名单/黑名单"""
+
+    private_list: list[int] = field(default_factory=[])
+    """私聊列表"""
+
+    ban_user_id: list[int] = field(default_factory=[])
+    """被封禁的用户ID列表，封禁后将无法与其进行交互"""
+
+    ban_qq_bot: bool = False
+    """是否屏蔽QQ官方机器人，若为True，则所有QQ官方机器人将无法与MaiMCore进行交互"""
+
+    enable_poke: bool = True
+    """是否启用戳一戳功能"""
+
+
+@dataclass
+class VoiceConfig(ConfigBase):
+    use_tts: bool = False
+    """是否启用TTS功能"""
+
+
+@dataclass
+class DebugConfig(ConfigBase):
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "INFO"
+    """日志级别，默认为INFO"""

MaiBot-Napcat-Adapter-dev/src/database.py

@@ -0,0 +1,162 @@
+import os
+from typing import Optional, List
+from dataclasses import dataclass
+from sqlmodel import Field, Session, SQLModel, create_engine, select
+
+from src.logger import logger
+
+"""
+表记录的方式：
+| group_id | user_id | lift_time |
+|----------|---------|-----------|
+
+其中使用 user_id == 0 表示群全体禁言
+"""
+
+
+@dataclass
+class BanUser:
+    """
+    程序处理使用的实例
+    """
+
+    user_id: int
+    group_id: int
+    lift_time: Optional[int] = Field(default=-1)
+
+
+class DB_BanUser(SQLModel, table=True):
+    """
+    表示数据库中的用户禁言记录。
+    使用双重主键
+    """
+
+    user_id: int = Field(index=True, primary_key=True)  # 被禁言用户的用户 ID
+    group_id: int = Field(index=True, primary_key=True)  # 用户被禁言的群组 ID
+    lift_time: Optional[int]  # 禁言解除的时间（时间戳）
+
+
+def is_identical(obj1: BanUser, obj2: BanUser) -> bool:
+    """
+    检查两个 BanUser 对象是否相同。
+    """
+    return obj1.user_id == obj2.user_id and obj1.group_id == obj2.group_id
+
+
+class DatabaseManager:
+    """
+    数据库管理类，负责与数据库交互。
+    """
+
+    def __init__(self):
+        os.makedirs(os.path.join(os.path.dirname(__file__), "..", "data"), exist_ok=True)  # 确保数据目录存在
+        DATABASE_FILE = os.path.join(os.path.dirname(__file__), "..", "data", "NapcatAdapter.db")
+        self.sqlite_url = f"sqlite:///{DATABASE_FILE}"  # SQLite 数据库 URL
+        self.engine = create_engine(self.sqlite_url, echo=False)  # 创建数据库引擎
+        self._ensure_database()  # 确保数据库和表已创建
+
+    def _ensure_database(self) -> None:
+        """
+        确保数据库和表已创建。
+        """
+        logger.info("确保数据库文件和表已创建...")
+        SQLModel.metadata.create_all(self.engine)
+        logger.success("数据库和表已创建或已存在")
+
+    def update_ban_record(self, ban_list: List[BanUser]) -> None:
+        # sourcery skip: class-extract-method
+        """
+        更新禁言列表到数据库。
+        支持在不存在时创建新记录，对于多余的项目自动删除。
+        """
+        with Session(self.engine) as session:
+            all_records = session.exec(select(DB_BanUser)).all()
+            for ban_user in ban_list:
+                statement = select(DB_BanUser).where(
+                    DB_BanUser.user_id == ban_user.user_id, DB_BanUser.group_id == ban_user.group_id
+                )
+                if existing_record := session.exec(statement).first():
+                    if existing_record.lift_time == ban_user.lift_time:
+                        logger.debug(f"禁言记录未变更: {existing_record}")
+                        continue
+                    # 更新现有记录的 lift_time
+                    existing_record.lift_time = ban_user.lift_time
+                    session.add(existing_record)
+                    logger.debug(f"更新禁言记录: {existing_record}")
+                else:
+                    # 创建新记录
+                    db_record = DB_BanUser(
+                        user_id=ban_user.user_id, group_id=ban_user.group_id, lift_time=ban_user.lift_time
+                    )
+                    session.add(db_record)
+                    logger.debug(f"创建新禁言记录: {ban_user}")
+            # 删除不在 ban_list 中的记录
+            for db_record in all_records:
+                record = BanUser(user_id=db_record.user_id, group_id=db_record.group_id, lift_time=db_record.lift_time)
+                if not any(is_identical(record, ban_user) for ban_user in ban_list):
+                    statement = select(DB_BanUser).where(
+                        DB_BanUser.user_id == record.user_id, DB_BanUser.group_id == record.group_id
+                    )
+                    if ban_record := session.exec(statement).first():
+                        session.delete(ban_record)
+                        session.commit()
+                        logger.debug(f"删除禁言记录: {ban_record}")
+                    else:
+                        logger.info(f"未找到禁言记录: {ban_record}")
+
+            session.commit()
+            logger.info("禁言记录已更新")
+
+    def get_ban_records(self) -> List[BanUser]:
+        """
+        读取所有禁言记录。
+        """
+        with Session(self.engine) as session:
+            statement = select(DB_BanUser)
+            records = session.exec(statement).all()
+            return [BanUser(user_id=item.user_id, group_id=item.group_id, lift_time=item.lift_time) for item in records]
+
+    def create_ban_record(self, ban_record: BanUser) -> None:
+        """
+        为特定群组中的用户创建禁言记录。
+        一个简化版本的添加方式，防止 update_ban_record 方法的复杂性。
+        其同时还是简化版的更新方式。
+        """
+        with Session(self.engine) as session:
+            # 检查记录是否已存在
+            statement = select(DB_BanUser).where(
+                DB_BanUser.user_id == ban_record.user_id, DB_BanUser.group_id == ban_record.group_id
+            )
+            existing_record = session.exec(statement).first()
+            if existing_record:
+                # 如果记录已存在，更新 lift_time
+                existing_record.lift_time = ban_record.lift_time
+                session.add(existing_record)
+                logger.debug(f"更新禁言记录: {ban_record}")
+            else:
+                # 如果记录不存在，创建新记录
+                db_record = DB_BanUser(
+                    user_id=ban_record.user_id, group_id=ban_record.group_id, lift_time=ban_record.lift_time
+                )
+                session.add(db_record)
+                logger.debug(f"创建新禁言记录: {ban_record}")
+            session.commit()
+
+    def delete_ban_record(self, ban_record: BanUser):
+        """
+        删除特定用户在特定群组中的禁言记录。
+        一个简化版本的删除方式，防止 update_ban_record 方法的复杂性。
+        """
+        user_id = ban_record.user_id
+        group_id = ban_record.group_id
+        with Session(self.engine) as session:
+            statement = select(DB_BanUser).where(DB_BanUser.user_id == user_id, DB_BanUser.group_id == group_id)
+            if ban_record := session.exec(statement).first():
+                session.delete(ban_record)
+                session.commit()
+                logger.debug(f"删除禁言记录: {ban_record}")
+            else:
+                logger.info(f"未找到禁言记录: user_id: {user_id}, group_id: {group_id}")
+
+
+db_manager = DatabaseManager()

MaiBot-Napcat-Adapter-dev/src/logger.py

@@ -0,0 +1,21 @@
+from loguru import logger
+from .config import global_config
+import sys
+
+# 默认 logger
+logger.remove()
+logger.add(
+    sys.stderr,
+    level=global_config.debug.level,
+    format="<blue>{time:YYYY-MM-DD HH:mm:ss}</blue> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
+    filter=lambda record: "name" not in record["extra"] or record["extra"].get("name") != "maim_message",
+)
+logger.add(
+    sys.stderr,
+    level="INFO",
+    format="<red>{time:YYYY-MM-DD HH:mm:ss}</red> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
+    filter=lambda record: record["extra"].get("name") == "maim_message",
+)
+# 创建样式不同的 logger
+custom_logger = logger.bind(name="maim_message")
+logger = logger.bind(name="MaiBot-Napcat-Adapter")

MaiBot-Napcat-Adapter-dev/src/mmc_com_layer.py

@@ -0,0 +1,24 @@
+from maim_message import Router, RouteConfig, TargetConfig
+from .config import global_config
+from .logger import logger, custom_logger
+from .send_handler import send_handler
+
+route_config = RouteConfig(
+    route_config={
+        global_config.maibot_server.platform_name: TargetConfig(
+            url=f"ws://{global_config.maibot_server.host}:{global_config.maibot_server.port}/ws",
+            token=None,
+        )
+    }
+)
+router = Router(route_config, custom_logger)
+
+
+async def mmc_start_com():
+    logger.info("正在连接MaiBot")
+    router.register_class_handler(send_handler.handle_message)
+    await router.run()
+
+
+async def mmc_stop_com():
+    await router.stop()

MaiBot-Napcat-Adapter-dev/src/recv_handler/__init__.py

@@ -0,0 +1,87 @@
+from enum import Enum
+
+
+class MetaEventType:
+    lifecycle = "lifecycle"  # 生命周期
+
+    class Lifecycle:
+        connect = "connect"  # 生命周期 - WebSocket 连接成功
+
+    heartbeat = "heartbeat"  # 心跳
+
+
+class MessageType:  # 接受消息大类
+    private = "private"  # 私聊消息
+
+    class Private:
+        friend = "friend"  # 私聊消息 - 好友
+        group = "group"  # 私聊消息 - 群临时
+        group_self = "group_self"  # 私聊消息 - 群中自身发送
+        other = "other"  # 私聊消息 - 其他
+
+    group = "group"  # 群聊消息
+
+    class Group:
+        normal = "normal"  # 群聊消息 - 普通
+        anonymous = "anonymous"  # 群聊消息 - 匿名消息
+        notice = "notice"  # 群聊消息 - 系统提示
+
+
+class NoticeType:  # 通知事件
+    friend_recall = "friend_recall"  # 私聊消息撤回
+    group_recall = "group_recall"  # 群聊消息撤回
+    notify = "notify"
+    group_ban = "group_ban"  # 群禁言
+
+    class Notify:
+        poke = "poke"  # 戳一戳
+
+    class GroupBan:
+        ban = "ban"  # 禁言
+        lift_ban = "lift_ban"  # 解除禁言
+
+
+class RealMessageType:  # 实际消息分类
+    text = "text"  # 纯文本
+    face = "face"  # qq表情
+    image = "image"  # 图片
+    record = "record"  # 语音
+    video = "video"  # 视频
+    at = "at"  # @某人
+    rps = "rps"  # 猜拳魔法表情
+    dice = "dice"  # 骰子
+    shake = "shake"  # 私聊窗口抖动（只收）
+    poke = "poke"  # 群聊戳一戳
+    share = "share"  # 链接分享（json形式）
+    reply = "reply"  # 回复消息
+    forward = "forward"  # 转发消息
+    node = "node"  # 转发消息节点
+
+
+class MessageSentType:
+    private = "private"
+
+    class Private:
+        friend = "friend"
+        group = "group"
+
+    group = "group"
+
+    class Group:
+        normal = "normal"
+
+
+class CommandType(Enum):
+    """命令类型"""
+
+    GROUP_BAN = "set_group_ban"  # 禁言用户
+    GROUP_WHOLE_BAN = "set_group_whole_ban"  # 群全体禁言
+    GROUP_KICK = "set_group_kick"  # 踢出群聊
+    SEND_POKE = "send_poke"  # 戳一戳
+    DELETE_MSG = "delete_msg"  # 撤回消息
+
+    def __str__(self) -> str:
+        return self.value
+
+
+ACCEPT_FORMAT = ["text", "image", "emoji", "reply", "voice", "command", "voiceurl", "music", "videourl", "file"]

MaiBot-Napcat-Adapter-dev/src/recv_handler/message_handler.py

@@ -0,0 +1,669 @@
+from src.logger import logger
+from src.config import global_config
+from src.utils import (
+    get_group_info,
+    get_member_info,
+    get_image_base64,
+    get_record_detail,
+    get_self_info,
+    get_message_detail,
+)
+from .qq_emoji_list import qq_face
+from .message_sending import message_send_instance
+from . import RealMessageType, MessageType, ACCEPT_FORMAT
+
+import time
+import json
+import websockets as Server
+from typing import List, Tuple, Optional, Dict, Any
+import uuid
+
+from maim_message import (
+    UserInfo,
+    GroupInfo,
+    Seg,
+    BaseMessageInfo,
+    MessageBase,
+    TemplateInfo,
+    FormatInfo,
+)
+
+
+from src.response_pool import get_response
+
+
+class MessageHandler:
+    def __init__(self):
+        self.server_connection: Server.ServerConnection = None
+        self.bot_id_list: Dict[int, bool] = {}
+
+    async def set_server_connection(self, server_connection: Server.ServerConnection) -> None:
+        """设置Napcat连接"""
+        self.server_connection = server_connection
+
+    async def check_allow_to_chat(
+        self,
+        user_id: int,
+        group_id: Optional[int] = None,
+        ignore_bot: Optional[bool] = False,
+        ignore_global_list: Optional[bool] = False,
+    ) -> bool:
+        # sourcery skip: hoist-statement-from-if, merge-else-if-into-elif
+        """
+        检查是否允许聊天
+        Parameters:
+            user_id: int: 用户ID
+            group_id: int: 群ID
+            ignore_bot: bool: 是否忽略机器人检查
+            ignore_global_list: bool: 是否忽略全局黑名单检查
+        Returns:
+            bool: 是否允许聊天
+        """
+        logger.debug(f"群聊id: {group_id}, 用户id: {user_id}")
+        logger.debug("开始检查聊天白名单/黑名单")
+        if group_id:
+            if global_config.chat.group_list_type == "whitelist" and group_id not in global_config.chat.group_list:
+                logger.warning("群聊不在聊天白名单中，消息被丢弃")
+                return False
+            elif global_config.chat.group_list_type == "blacklist" and group_id in global_config.chat.group_list:
+                logger.warning("群聊在聊天黑名单中，消息被丢弃")
+                return False
+        else:
+            if global_config.chat.private_list_type == "whitelist" and user_id not in global_config.chat.private_list:
+                logger.warning("私聊不在聊天白名单中，消息被丢弃")
+                return False
+            elif global_config.chat.private_list_type == "blacklist" and user_id in global_config.chat.private_list:
+                logger.warning("私聊在聊天黑名单中，消息被丢弃")
+                return False
+        if user_id in global_config.chat.ban_user_id and not ignore_global_list:
+            logger.warning("用户在全局黑名单中，消息被丢弃")
+            return False
+
+        if global_config.chat.ban_qq_bot and group_id and not ignore_bot:
+            logger.debug("开始判断是否为机器人")
+            member_info = await get_member_info(self.server_connection, group_id, user_id)
+            if member_info:
+                is_bot = member_info.get("is_robot")
+                if is_bot is None:
+                    logger.warning("无法获取用户是否为机器人，默认为不是但是不进行更新")
+                else:
+                    if is_bot:
+                        logger.warning("QQ官方机器人消息拦截已启用，消息被丢弃，新机器人加入拦截名单")
+                        self.bot_id_list[user_id] = True
+                        return False
+                    else:
+                        self.bot_id_list[user_id] = False
+
+        return True
+
+    async def handle_raw_message(self, raw_message: dict) -> None:
+        # sourcery skip: low-code-quality, remove-unreachable-code
+        """
+        从Napcat接受的原始消息处理
+
+        Parameters:
+            raw_message: dict: 原始消息
+        """
+        message_type: str = raw_message.get("message_type")
+        message_id: int = raw_message.get("message_id")
+        # message_time: int = raw_message.get("time")
+        message_time: float = time.time()  # 应可乐要求，现在是float了
+
+        template_info: TemplateInfo = None  # 模板信息，暂时为空，等待启用
+        format_info: FormatInfo = FormatInfo(
+            content_format=["text", "image", "emoji", "voice"],
+            accept_format=ACCEPT_FORMAT,
+        )  # 格式化信息
+        if message_type == MessageType.private:
+            sub_type = raw_message.get("sub_type")
+            if sub_type == MessageType.Private.friend:
+                sender_info: dict = raw_message.get("sender")
+
+                if not await self.check_allow_to_chat(sender_info.get("user_id"), None):
+                    return None
+
+                # 发送者用户信息
+                user_info: UserInfo = UserInfo(
+                    platform=global_config.maibot_server.platform_name,
+                    user_id=sender_info.get("user_id"),
+                    user_nickname=sender_info.get("nickname"),
+                    user_cardname=sender_info.get("card"),
+                )
+
+                # 不存在群信息
+                group_info: GroupInfo = None
+            elif sub_type == MessageType.Private.group:
+                """
+                本部分暂时不做支持，先放着
+                """
+                logger.warning("群临时消息类型不支持")
+                return None
+
+                sender_info: dict = raw_message.get("sender")
+
+                # 由于临时会话中，Napcat默认不发送成员昵称，所以需要单独获取
+                fetched_member_info: dict = await get_member_info(
+                    self.server_connection,
+                    raw_message.get("group_id"),
+                    sender_info.get("user_id"),
+                )
+                nickname = fetched_member_info.get("nickname") if fetched_member_info else None
+                # 发送者用户信息
+                user_info: UserInfo = UserInfo(
+                    platform=global_config.maibot_server.platform_name,
+                    user_id=sender_info.get("user_id"),
+                    user_nickname=nickname,
+                    user_cardname=None,
+                )
+
+                # -------------------这里需要群信息吗？-------------------
+
+                # 获取群聊相关信息，在此单独处理group_name，因为默认发送的消息中没有
+                fetched_group_info: dict = await get_group_info(self.server_connection, raw_message.get("group_id"))
+                group_name = ""
+                if fetched_group_info.get("group_name"):
+                    group_name = fetched_group_info.get("group_name")
+
+                group_info: GroupInfo = GroupInfo(
+                    platform=global_config.maibot_server.platform_name,
+                    group_id=raw_message.get("group_id"),
+                    group_name=group_name,
+                )
+
+            else:
+                logger.warning(f"私聊消息类型 {sub_type} 不支持")
+                return None
+        elif message_type == MessageType.group:
+            sub_type = raw_message.get("sub_type")
+            if sub_type == MessageType.Group.normal:
+                sender_info: dict = raw_message.get("sender")
+
+                if not await self.check_allow_to_chat(sender_info.get("user_id"), raw_message.get("group_id")):
+                    return None
+
+                # 发送者用户信息
+                user_info: UserInfo = UserInfo(
+                    platform=global_config.maibot_server.platform_name,
+                    user_id=sender_info.get("user_id"),
+                    user_nickname=sender_info.get("nickname"),
+                    user_cardname=sender_info.get("card"),
+                )
+
+                # 获取群聊相关信息，在此单独处理group_name，因为默认发送的消息中没有
+                fetched_group_info = await get_group_info(self.server_connection, raw_message.get("group_id"))
+                group_name: str = None
+                if fetched_group_info:
+                    group_name = fetched_group_info.get("group_name")
+
+                group_info: GroupInfo = GroupInfo(
+                    platform=global_config.maibot_server.platform_name,
+                    group_id=raw_message.get("group_id"),
+                    group_name=group_name,
+                )
+
+            else:
+                logger.warning(f"群聊消息类型 {sub_type} 不支持")
+                return None
+
+        additional_config: dict = {}
+        if global_config.voice.use_tts:
+            additional_config["allow_tts"] = True
+
+        # 消息信息
+        message_info: BaseMessageInfo = BaseMessageInfo(
+            platform=global_config.maibot_server.platform_name,
+            message_id=message_id,
+            time=message_time,
+            user_info=user_info,
+            group_info=group_info,
+            template_info=template_info,
+            format_info=format_info,
+            additional_config=additional_config,
+        )
+
+        # 处理实际信息
+        if not raw_message.get("message"):
+            logger.warning("原始消息内容为空")
+            return None
+
+        # 获取Seg列表
+        seg_message: List[Seg] = await self.handle_real_message(raw_message)
+        if not seg_message:
+            logger.warning("处理后消息内容为空")
+            return None
+        submit_seg: Seg = Seg(
+            type="seglist",
+            data=seg_message,
+        )
+        # MessageBase创建
+        message_base: MessageBase = MessageBase(
+            message_info=message_info,
+            message_segment=submit_seg,
+            raw_message=raw_message.get("raw_message"),
+        )
+
+        logger.info("发送到Maibot处理信息")
+        await message_send_instance.message_send(message_base)
+
+    async def handle_real_message(self, raw_message: dict, in_reply: bool = False) -> List[Seg] | None:
+        # sourcery skip: low-code-quality
+        """
+        处理实际消息
+        Parameters:
+            real_message: dict: 实际消息
+        Returns:
+            seg_message: list[Seg]: 处理后的消息段列表
+        """
+        real_message: list = raw_message.get("message")
+        if not real_message:
+            return None
+        seg_message: List[Seg] = []
+        for sub_message in real_message:
+            sub_message: dict
+            sub_message_type = sub_message.get("type")
+            match sub_message_type:
+                case RealMessageType.text:
+                    ret_seg = await self.handle_text_message(sub_message)
+                    if ret_seg:
+                        seg_message.append(ret_seg)
+                    else:
+                        logger.warning("text处理失败")
+                case RealMessageType.face:
+                    ret_seg = await self.handle_face_message(sub_message)
+                    if ret_seg:
+                        seg_message.append(ret_seg)
+                    else:
+                        logger.warning("face处理失败或不支持")
+                case RealMessageType.reply:
+                    if not in_reply:
+                        ret_seg = await self.handle_reply_message(sub_message)
+                        if ret_seg:
+                            seg_message += ret_seg
+                        else:
+                            logger.warning("reply处理失败")
+                case RealMessageType.image:
+                    ret_seg = await self.handle_image_message(sub_message)
+                    if ret_seg:
+                        seg_message.append(ret_seg)
+                    else:
+                        logger.warning("image处理失败")
+                case RealMessageType.record:
+                    ret_seg = await self.handle_record_message(sub_message)
+                    if ret_seg:
+                        seg_message.clear()
+                        seg_message.append(ret_seg)
+                        break  # 使得消息只有record消息
+                    else:
+                        logger.warning("record处理失败或不支持")
+                case RealMessageType.video:
+                    logger.warning("不支持视频解析")
+                case RealMessageType.at:
+                    ret_seg = await self.handle_at_message(
+                        sub_message,
+                        raw_message.get("self_id"),
+                        raw_message.get("group_id"),
+                    )
+                    if ret_seg:
+                        seg_message.append(ret_seg)
+                    else:
+                        logger.warning("at处理失败")
+                case RealMessageType.rps:
+                    logger.warning("暂时不支持猜拳魔法表情解析")
+                case RealMessageType.dice:
+                    logger.warning("暂时不支持骰子表情解析")
+                case RealMessageType.shake:
+                    # 预计等价于戳一戳
+                    logger.warning("暂时不支持窗口抖动解析")
+                case RealMessageType.share:
+                    logger.warning("暂时不支持链接解析")
+                case RealMessageType.forward:
+                    messages = await self._get_forward_message(sub_message)
+                    if not messages:
+                        logger.warning("转发消息内容为空或获取失败")
+                        return None
+                    ret_seg = await self.handle_forward_message(messages)
+                    if ret_seg:
+                        seg_message.append(ret_seg)
+                    else:
+                        logger.warning("转发消息处理失败")
+                case RealMessageType.node:
+                    logger.warning("不支持转发消息节点解析")
+                case _:
+                    logger.warning(f"未知消息类型: {sub_message_type}")
+        return seg_message
+
+    async def handle_text_message(self, raw_message: dict) -> Seg:
+        """
+        处理纯文本信息
+        Parameters:
+            raw_message: dict: 原始消息
+        Returns:
+            seg_data: Seg: 处理后的消息段
+        """
+        message_data: dict = raw_message.get("data")
+        plain_text: str = message_data.get("text")
+        return Seg(type="text", data=plain_text)
+
+    async def handle_face_message(self, raw_message: dict) -> Seg | None:
+        """
+        处理表情消息
+        Parameters:
+            raw_message: dict: 原始消息
+        Returns:
+            seg_data: Seg: 处理后的消息段
+        """
+        message_data: dict = raw_message.get("data")
+        face_raw_id: str = str(message_data.get("id"))
+        if face_raw_id in qq_face:
+            face_content: str = qq_face.get(face_raw_id)
+            return Seg(type="text", data=face_content)
+        else:
+            logger.warning(f"不支持的表情：{face_raw_id}")
+            return None
+
+    async def handle_image_message(self, raw_message: dict) -> Seg | None:
+        """
+        处理图片消息与表情包消息
+        Parameters:
+            raw_message: dict: 原始消息
+        Returns:
+            seg_data: Seg: 处理后的消息段
+        """
+        message_data: dict = raw_message.get("data")
+        image_sub_type = message_data.get("sub_type")
+        try:
+            image_base64 = await get_image_base64(message_data.get("url"))
+        except Exception as e:
+            logger.error(f"图片消息处理失败: {str(e)}")
+            return None
+        if image_sub_type == 0:
+            """这部分认为是图片"""
+            return Seg(type="image", data=image_base64)
+        elif image_sub_type not in [4, 9]:
+            """这部分认为是表情包"""
+            return Seg(type="emoji", data=image_base64)
+        else:
+            logger.warning(f"不支持的图片子类型：{image_sub_type}")
+            return None
+
+    async def handle_at_message(self, raw_message: dict, self_id: int, group_id: int) -> Seg | None:
+        # sourcery skip: use-named-expression
+        """
+        处理at消息
+        Parameters:
+            raw_message: dict: 原始消息
+            self_id: int: 机器人QQ号
+            group_id: int: 群号
+        Returns:
+            seg_data: Seg: 处理后的消息段
+        """
+        message_data: dict = raw_message.get("data")
+        if message_data:
+            qq_id = message_data.get("qq")
+            if str(self_id) == str(qq_id):
+                logger.debug("机器人被at")
+                self_info: dict = await get_self_info(self.server_connection)
+                if self_info:
+                    return Seg(type="text", data=f"@<{self_info.get('nickname')}:{self_info.get('user_id')}>")
+                else:
+                    return None
+            else:
+                member_info: dict = await get_member_info(self.server_connection, group_id=group_id, user_id=qq_id)
+                if member_info:
+                    return Seg(type="text", data=f"@<{member_info.get('nickname')}:{member_info.get('user_id')}>")
+                else:
+                    return None
+
+    async def handle_record_message(self, raw_message: dict) -> Seg | None:
+        """
+        处理语音消息
+        Parameters:
+            raw_message: dict: 原始消息
+        Returns:
+            seg_data: Seg: 处理后的消息段
+        """
+        message_data: dict = raw_message.get("data")
+        file: str = message_data.get("file")
+        if not file:
+            logger.warning("语音消息缺少文件信息")
+            return None
+        try:
+            record_detail = await get_record_detail(self.server_connection, file)
+            if not record_detail:
+                logger.warning("获取语音消息详情失败")
+                return None
+            audio_base64: str = record_detail.get("base64")
+        except Exception as e:
+            logger.error(f"语音消息处理失败: {str(e)}")
+            return None
+        if not audio_base64:
+            logger.error("语音消息处理失败，未获取到音频数据")
+            return None
+        return Seg(type="voice", data=audio_base64)
+
+    async def handle_reply_message(self, raw_message: dict) -> List[Seg] | None:
+        # sourcery skip: move-assign-in-block, use-named-expression
+        """
+        处理回复消息
+
+        """
+        raw_message_data: dict = raw_message.get("data")
+        message_id: int = None
+        if raw_message_data:
+            message_id = raw_message_data.get("id")
+        else:
+            return None
+        message_detail: dict = await get_message_detail(self.server_connection, message_id)
+        if not message_detail:
+            logger.warning("获取被引用的消息详情失败")
+            return None
+        reply_message = await self.handle_real_message(message_detail, in_reply=True)
+        if reply_message is None:
+            reply_message = "(获取发言内容失败)"
+        sender_info: dict = message_detail.get("sender")
+        sender_nickname: str = sender_info.get("nickname")
+        sender_id: str = sender_info.get("user_id")
+        seg_message: List[Seg] = []
+        if not sender_nickname:
+            logger.warning("无法获取被引用的人的昵称，返回默认值")
+            seg_message.append(Seg(type="text", data="[回复 未知用户："))
+        else:
+            seg_message.append(Seg(type="text", data=f"[回复<{sender_nickname}:{sender_id}>："))
+        seg_message += reply_message
+        seg_message.append(Seg(type="text", data="]，说："))
+        return seg_message
+
+    async def handle_forward_message(self, message_list: list) -> Seg | None:
+        """
+        递归处理转发消息，并按照动态方式确定图片处理方式
+        Parameters:
+            message_list: list: 转发消息列表
+        """
+        handled_message, image_count = await self._handle_forward_message(message_list, 0)
+        handled_message: Seg
+        image_count: int
+        if not handled_message:
+            return None
+        if image_count < 5 and image_count > 0:
+            # 处理图片数量小于5的情况，此时解析图片为base64
+            logger.trace("图片数量小于5，开始解析图片为base64")
+            return await self._recursive_parse_image_seg(handled_message, True)
+        elif image_count > 0:
+            logger.trace("图片数量大于等于5，开始解析图片为占位符")
+            # 处理图片数量大于等于5的情况，此时解析图片为占位符
+            return await self._recursive_parse_image_seg(handled_message, False)
+        else:
+            # 处理没有图片的情况，此时直接返回
+            logger.trace("没有图片，直接返回")
+            return handled_message
+
+    async def _recursive_parse_image_seg(self, seg_data: Seg, to_image: bool) -> Seg:
+        # sourcery skip: merge-else-if-into-elif
+        if to_image:
+            if seg_data.type == "seglist":
+                new_seg_list = []
+                for i_seg in seg_data.data:
+                    parsed_seg = await self._recursive_parse_image_seg(i_seg, to_image)
+                    new_seg_list.append(parsed_seg)
+                return Seg(type="seglist", data=new_seg_list)
+            elif seg_data.type == "image":
+                image_url = seg_data.data
+                try:
+                    encoded_image = await get_image_base64(image_url)
+                except Exception as e:
+                    logger.error(f"图片处理失败: {str(e)}")
+                    return Seg(type="text", data="[图片]")
+                return Seg(type="image", data=encoded_image)
+            elif seg_data.type == "emoji":
+                image_url = seg_data.data
+                try:
+                    encoded_image = await get_image_base64(image_url)
+                except Exception as e:
+                    logger.error(f"图片处理失败: {str(e)}")
+                    return Seg(type="text", data="[表情包]")
+                return Seg(type="emoji", data=encoded_image)
+            else:
+                logger.trace(f"不处理类型: {seg_data.type}")
+                return seg_data
+        else:
+            if seg_data.type == "seglist":
+                new_seg_list = []
+                for i_seg in seg_data.data:
+                    parsed_seg = await self._recursive_parse_image_seg(i_seg, to_image)
+                    new_seg_list.append(parsed_seg)
+                return Seg(type="seglist", data=new_seg_list)
+            elif seg_data.type == "image":
+                return Seg(type="text", data="[图片]")
+            elif seg_data.type == "emoji":
+                return Seg(type="text", data="[动画表情]")
+            else:
+                logger.trace(f"不处理类型: {seg_data.type}")
+                return seg_data
+
+    async def _handle_forward_message(self, message_list: list, layer: int) -> Tuple[Seg, int] | Tuple[None, int]:
+        # sourcery skip: low-code-quality
+        """
+        递归处理实际转发消息
+        Parameters:
+            message_list: list: 转发消息列表，首层对应messages字段，后面对应content字段
+            layer: int: 当前层级
+        Returns:
+            seg_data: Seg: 处理后的消息段
+            image_count: int: 图片数量
+        """
+        seg_list: List[Seg] = []
+        image_count = 0
+        if message_list is None:
+            return None, 0
+        for sub_message in message_list:
+            sub_message: dict
+            sender_info: dict = sub_message.get("sender")
+            user_nickname: str = sender_info.get("nickname", "QQ用户")
+            user_nickname_str = f"【{user_nickname}】:"
+            break_seg = Seg(type="text", data="\n")
+            message_of_sub_message_list: List[Dict[str, Any]] = sub_message.get("message")
+            if not message_of_sub_message_list:
+                logger.warning("转发消息内容为空")
+                continue
+            message_of_sub_message = message_of_sub_message_list[0]
+            if message_of_sub_message.get("type") == RealMessageType.forward:
+                if layer >= 3:
+                    full_seg_data = Seg(
+                        type="text",
+                        data=("--" * layer) + f"【{user_nickname}】:【转发消息】\n",
+                    )
+                else:
+                    sub_message_data = message_of_sub_message.get("data")
+                    if not sub_message_data:
+                        continue
+                    contents = sub_message_data.get("content")
+                    seg_data, count = await self._handle_forward_message(contents, layer + 1)
+                    image_count += count
+                    head_tip = Seg(
+                        type="text",
+                        data=("--" * layer) + f"【{user_nickname}】: 合并转发消息内容：\n",
+                    )
+                    full_seg_data = Seg(type="seglist", data=[head_tip, seg_data])
+                seg_list.append(full_seg_data)
+            elif message_of_sub_message.get("type") == RealMessageType.text:
+                sub_message_data = message_of_sub_message.get("data")
+                if not sub_message_data:
+                    continue
+                text_message = sub_message_data.get("text")
+                seg_data = Seg(type="text", data=text_message)
+                data_list: List[Any] = []
+                if layer > 0:
+                    data_list = [
+                        Seg(type="text", data=("--" * layer) + user_nickname_str),
+                        seg_data,
+                        break_seg,
+                    ]
+                else:
+                    data_list = [
+                        Seg(type="text", data=user_nickname_str),
+                        seg_data,
+                        break_seg,
+                    ]
+                seg_list.append(Seg(type="seglist", data=data_list))
+            elif message_of_sub_message.get("type") == RealMessageType.image:
+                image_count += 1
+                image_data = message_of_sub_message.get("data")
+                sub_type = image_data.get("sub_type")
+                image_url = image_data.get("url")
+                data_list: List[Any] = []
+                if sub_type == 0:
+                    seg_data = Seg(type="image", data=image_url)
+                else:
+                    seg_data = Seg(type="emoji", data=image_url)
+                if layer > 0:
+                    data_list = [
+                        Seg(type="text", data=("--" * layer) + user_nickname_str),
+                        seg_data,
+                        break_seg,
+                    ]
+                else:
+                    data_list = [
+                        Seg(type="text", data=user_nickname_str),
+                        seg_data,
+                        break_seg,
+                    ]
+                full_seg_data = Seg(type="seglist", data=data_list)
+                seg_list.append(full_seg_data)
+        return Seg(type="seglist", data=seg_list), image_count
+
+    async def _get_forward_message(self, raw_message: dict) -> Dict[str, Any] | None:
+        forward_message_data: Dict = raw_message.get("data")
+        if not forward_message_data:
+            logger.warning("转发消息内容为空")
+            return None
+        forward_message_id = forward_message_data.get("id")
+        request_uuid = str(uuid.uuid4())
+        payload = json.dumps(
+            {
+                "action": "get_forward_msg",
+                "params": {"message_id": forward_message_id},
+                "echo": request_uuid,
+            }
+        )
+        try:
+            await self.server_connection.send(payload)
+            response: dict = await get_response(request_uuid)
+        except TimeoutError:
+            logger.error("获取转发消息超时")
+            return None
+        except Exception as e:
+            logger.error(f"获取转发消息失败: {str(e)}")
+            return None
+        logger.debug(
+            f"转发消息原始格式：{json.dumps(response)[:80]}..."
+            if len(json.dumps(response)) > 80
+            else json.dumps(response)
+        )
+        response_data: Dict = response.get("data")
+        if not response_data:
+            logger.warning("转发消息内容为空或获取失败")
+            return None
+        return response_data.get("messages")
+
+
+message_handler = MessageHandler()

MaiBot-Napcat-Adapter-dev/src/recv_handler/message_sending.py

@@ -0,0 +1,31 @@
+from src.logger import logger
+from maim_message import MessageBase, Router
+
+
+class MessageSending:
+    """
+    负责把消息发送到麦麦
+    """
+
+    maibot_router: Router = None
+
+    def __init__(self):
+        pass
+
+    async def message_send(self, message_base: MessageBase) -> bool:
+        """
+        发送消息
+        Parameters:
+            message_base: MessageBase: 消息基类，包含发送目标和消息内容等信息
+        """
+        try:
+            send_status = await self.maibot_router.send_message(message_base)
+            if not send_status:
+                raise RuntimeError("可能是路由未正确配置或连接异常")
+            return send_status
+        except Exception as e:
+            logger.error(f"发送消息失败: {str(e)}")
+            logger.error("请检查与MaiBot之间的连接")
+
+
+message_send_instance = MessageSending()

MaiBot-Napcat-Adapter-dev/src/recv_handler/meta_event_handler.py

@@ -0,0 +1,49 @@
+from src.logger import logger
+from src.config import global_config
+import time
+import asyncio
+
+from . import MetaEventType
+
+
+class MetaEventHandler:
+    """
+    处理Meta事件
+    """
+
+    def __init__(self):
+        self.interval = global_config.napcat_server.heartbeat_interval
+        self._interval_checking = False
+
+    async def handle_meta_event(self, message: dict) -> None:
+        event_type = message.get("meta_event_type")
+        if event_type == MetaEventType.lifecycle:
+            sub_type = message.get("sub_type")
+            if sub_type == MetaEventType.Lifecycle.connect:
+                self_id = message.get("self_id")
+                self.last_heart_beat = time.time()
+                logger.success(f"Bot {self_id} 连接成功")
+                asyncio.create_task(self.check_heartbeat(self_id))
+        elif event_type == MetaEventType.heartbeat:
+            if message["status"].get("online") and message["status"].get("good"):
+                if not self._interval_checking:
+                    asyncio.create_task(self.check_heartbeat())
+                self.last_heart_beat = time.time()
+                self.interval = message.get("interval") / 1000
+            else:
+                self_id = message.get("self_id")
+                logger.warning(f"Bot {self_id} Napcat 端异常！")
+
+    async def check_heartbeat(self, id: int) -> None:
+        self._interval_checking = True
+        while True:
+            now_time = time.time()
+            if now_time - self.last_heart_beat > self.interval * 2:
+                logger.error(f"Bot {id} 可能发生了连接断开，被下线，或者Napcat卡死！")
+                break
+            else:
+                logger.debug("心跳正常")
+            await asyncio.sleep(self.interval)
+
+
+meta_event_handler = MetaEventHandler()

MaiBot-Napcat-Adapter-dev/src/recv_handler/notice_handler.py

@@ -0,0 +1,516 @@
+import time
+import json
+import asyncio
+import websockets as Server
+from typing import Tuple, Optional
+
+from src.logger import logger
+from src.config import global_config
+from src.database import BanUser, db_manager, is_identical
+from . import NoticeType, ACCEPT_FORMAT
+from .message_sending import message_send_instance
+from .message_handler import message_handler
+from maim_message import FormatInfo, UserInfo, GroupInfo, Seg, BaseMessageInfo, MessageBase
+
+from src.utils import (
+    get_group_info,
+    get_member_info,
+    get_self_info,
+    get_stranger_info,
+    read_ban_list,
+)
+
+notice_queue: asyncio.Queue[MessageBase] = asyncio.Queue(maxsize=100)
+unsuccessful_notice_queue: asyncio.Queue[MessageBase] = asyncio.Queue(maxsize=3)
+
+
+class NoticeHandler:
+    banned_list: list[BanUser] = []  # 当前仍在禁言中的用户列表
+    lifted_list: list[BanUser] = []  # 已经自然解除禁言
+
+    def __init__(self):
+        self.server_connection: Server.ServerConnection = None
+
+    async def set_server_connection(self, server_connection: Server.ServerConnection) -> None:
+        """设置Napcat连接"""
+        self.server_connection = server_connection
+
+        while self.server_connection.state != Server.State.OPEN:
+            await asyncio.sleep(0.5)
+        self.banned_list, self.lifted_list = await read_ban_list(self.server_connection)
+
+        asyncio.create_task(self.auto_lift_detect())
+        asyncio.create_task(self.send_notice())
+        asyncio.create_task(self.handle_natural_lift())
+
+    def _ban_operation(self, group_id: int, user_id: Optional[int] = None, lift_time: Optional[int] = None) -> None:
+        """
+        将用户禁言记录添加到self.banned_list中
+        如果是全体禁言，则user_id为0
+        """
+        if user_id is None:
+            user_id = 0  # 使用0表示全体禁言
+            lift_time = -1
+        ban_record = BanUser(user_id=user_id, group_id=group_id, lift_time=lift_time)
+        for record in self.banned_list:
+            if is_identical(record, ban_record):
+                self.banned_list.remove(record)
+                self.banned_list.append(ban_record)
+                db_manager.create_ban_record(ban_record)  # 作为更新
+                return
+        self.banned_list.append(ban_record)
+        db_manager.create_ban_record(ban_record)  # 添加到数据库
+
+    def _lift_operation(self, group_id: int, user_id: Optional[int] = None) -> None:
+        """
+        从self.lifted_group_list中移除已经解除全体禁言的群
+        """
+        if user_id is None:
+            user_id = 0  # 使用0表示全体禁言
+        ban_record = BanUser(user_id=user_id, group_id=group_id, lift_time=-1)
+        self.lifted_list.append(ban_record)
+        db_manager.delete_ban_record(ban_record)  # 删除数据库中的记录
+
+    async def handle_notice(self, raw_message: dict) -> None:
+        notice_type = raw_message.get("notice_type")
+        # message_time: int = raw_message.get("time")
+        message_time: float = time.time()  # 应可乐要求，现在是float了
+
+        group_id = raw_message.get("group_id")
+        user_id = raw_message.get("user_id")
+        target_id = raw_message.get("target_id")
+
+        handled_message: Seg = None
+        user_info: UserInfo = None
+        system_notice: bool = False
+
+        match notice_type:
+            case NoticeType.friend_recall:
+                logger.info("好友撤回一条消息")
+                logger.info(f"撤回消息ID：{raw_message.get('message_id')}, 撤回时间：{raw_message.get('time')}")
+                logger.warning("暂时不支持撤回消息处理")
+            case NoticeType.group_recall:
+                logger.info("群内用户撤回一条消息")
+                logger.info(f"撤回消息ID：{raw_message.get('message_id')}, 撤回时间：{raw_message.get('time')}")
+                logger.warning("暂时不支持撤回消息处理")
+            case NoticeType.notify:
+                sub_type = raw_message.get("sub_type")
+                match sub_type:
+                    case NoticeType.Notify.poke:
+                        if global_config.chat.enable_poke and await message_handler.check_allow_to_chat(
+                            user_id, group_id, False, False
+                        ):
+                            logger.info("处理戳一戳消息")
+                            handled_message, user_info = await self.handle_poke_notify(raw_message, group_id, user_id)
+                        else:
+                            logger.warning("戳一戳消息被禁用，取消戳一戳处理")
+                    case _:
+                        logger.warning(f"不支持的notify类型: {notice_type}.{sub_type}")
+            case NoticeType.group_ban:
+                sub_type = raw_message.get("sub_type")
+                match sub_type:
+                    case NoticeType.GroupBan.ban:
+                        if not await message_handler.check_allow_to_chat(user_id, group_id, True, False):
+                            return None
+                        logger.info("处理群禁言")
+                        handled_message, user_info = await self.handle_ban_notify(raw_message, group_id)
+                        system_notice = True
+                    case NoticeType.GroupBan.lift_ban:
+                        if not await message_handler.check_allow_to_chat(user_id, group_id, True, False):
+                            return None
+                        logger.info("处理解除群禁言")
+                        handled_message, user_info = await self.handle_lift_ban_notify(raw_message, group_id)
+                        system_notice = True
+                    case _:
+                        logger.warning(f"不支持的group_ban类型: {notice_type}.{sub_type}")
+            case _:
+                logger.warning(f"不支持的notice类型: {notice_type}")
+                return None
+        if not handled_message or not user_info:
+            logger.warning("notice处理失败或不支持")
+            return None
+
+        group_info: GroupInfo = None
+        if group_id:
+            fetched_group_info = await get_group_info(self.server_connection, group_id)
+            group_name: str = None
+            if fetched_group_info:
+                group_name = fetched_group_info.get("group_name")
+            else:
+                logger.warning("无法获取notice消息所在群的名称")
+            group_info = GroupInfo(
+                platform=global_config.maibot_server.platform_name,
+                group_id=group_id,
+                group_name=group_name,
+            )
+
+        message_info: BaseMessageInfo = BaseMessageInfo(
+            platform=global_config.maibot_server.platform_name,
+            message_id="notice",
+            time=message_time,
+            user_info=user_info,
+            group_info=group_info,
+            template_info=None,
+            format_info=FormatInfo(
+                content_format=["text", "notify"],
+                accept_format=ACCEPT_FORMAT,
+            ),
+            additional_config={"target_id": target_id},  # 在这里塞了一个target_id，方便mmc那边知道被戳的人是谁
+        )
+
+        message_base: MessageBase = MessageBase(
+            message_info=message_info,
+            message_segment=handled_message,
+            raw_message=json.dumps(raw_message),
+        )
+
+        if system_notice:
+            await self.put_notice(message_base)
+        else:
+            logger.info("发送到Maibot处理通知信息")
+            await message_send_instance.message_send(message_base)
+
+    async def handle_poke_notify(
+        self, raw_message: dict, group_id: int, user_id: int
+    ) -> Tuple[Seg | None, UserInfo | None]:
+        # sourcery skip: merge-comparisons, merge-duplicate-blocks, remove-redundant-if, remove-unnecessary-else, swap-if-else-branches
+        self_info: dict = await get_self_info(self.server_connection)
+
+        if not self_info:
+            logger.error("自身信息获取失败")
+            return None, None
+
+        self_id = raw_message.get("self_id")
+        target_id = raw_message.get("target_id")
+        target_name: str = None
+        raw_info: list = raw_message.get("raw_info")
+
+        if group_id:
+            user_qq_info: dict = await get_member_info(self.server_connection, group_id, user_id)
+        else:
+            user_qq_info: dict = await get_stranger_info(self.server_connection, user_id)
+        if user_qq_info:
+            user_name = user_qq_info.get("nickname")
+            user_cardname = user_qq_info.get("card")
+        else:
+            user_name = "QQ用户"
+            user_cardname = "QQ用户"
+            logger.info("无法获取戳一戳对方的用户昵称")
+
+        # 计算Seg
+        if self_id == target_id:
+            display_name = ""
+            target_name = self_info.get("nickname")
+
+        elif self_id == user_id:
+            # 让ada不发送麦麦戳别人的消息
+            return None, None
+
+        else:
+            # 老实说这一步判定没啥意义，毕竟私聊是没有其他人之间的戳一戳，但是感觉可以有这个判定来强限制群聊环境
+            if group_id:
+                fetched_member_info: dict = await get_member_info(self.server_connection, group_id, target_id)
+                if fetched_member_info:
+                    target_name = fetched_member_info.get("nickname")
+                else:
+                    target_name = "QQ用户"
+                    logger.info("无法获取被戳一戳方的用户昵称")
+                display_name = user_name
+            else:
+                return None, None
+
+        first_txt: str = "戳了戳"
+        second_txt: str = ""
+        try:
+            first_txt = raw_info[2].get("txt", "戳了戳")
+            second_txt = raw_info[4].get("txt", "")
+        except Exception as e:
+            logger.warning(f"解析戳一戳消息失败: {str(e)}，将使用默认文本")
+
+        user_info: UserInfo = UserInfo(
+            platform=global_config.maibot_server.platform_name,
+            user_id=user_id,
+            user_nickname=user_name,
+            user_cardname=user_cardname,
+        )
+
+        seg_data: Seg = Seg(
+            type="text",
+            data=f"{display_name}{first_txt}{target_name}{second_txt}（这是QQ的一个功能，用于提及某人，但没那么明显）",
+        )
+        return seg_data, user_info
+
+    async def handle_ban_notify(self, raw_message: dict, group_id: int) -> Tuple[Seg, UserInfo] | Tuple[None, None]:
+        if not group_id:
+            logger.error("群ID不能为空，无法处理禁言通知")
+            return None, None
+
+        # 计算user_info
+        operator_id = raw_message.get("operator_id")
+        operator_nickname: str = None
+        operator_cardname: str = None
+
+        member_info: dict = await get_member_info(self.server_connection, group_id, operator_id)
+        if member_info:
+            operator_nickname = member_info.get("nickname")
+            operator_cardname = member_info.get("card")
+        else:
+            logger.warning("无法获取禁言执行者的昵称，消息可能会无效")
+            operator_nickname = "QQ用户"
+
+        operator_info: UserInfo = UserInfo(
+            platform=global_config.maibot_server.platform_name,
+            user_id=operator_id,
+            user_nickname=operator_nickname,
+            user_cardname=operator_cardname,
+        )
+
+        # 计算Seg
+        user_id = raw_message.get("user_id")
+        banned_user_info: UserInfo = None
+        user_nickname: str = "QQ用户"
+        user_cardname: str = None
+        sub_type: str = None
+
+        duration = raw_message.get("duration")
+        if duration is None:
+            logger.error("禁言时长不能为空，无法处理禁言通知")
+            return None, None
+
+        if user_id == 0:  # 为全体禁言
+            sub_type: str = "whole_ban"
+            self._ban_operation(group_id)
+        else:  # 为单人禁言
+            # 获取被禁言人的信息
+            sub_type: str = "ban"
+            fetched_member_info: dict = await get_member_info(self.server_connection, group_id, user_id)
+            if fetched_member_info:
+                user_nickname = fetched_member_info.get("nickname")
+                user_cardname = fetched_member_info.get("card")
+            banned_user_info: UserInfo = UserInfo(
+                platform=global_config.maibot_server.platform_name,
+                user_id=user_id,
+                user_nickname=user_nickname,
+                user_cardname=user_cardname,
+            )
+            self._ban_operation(group_id, user_id, int(time.time() + duration))
+
+        seg_data: Seg = Seg(
+            type="notify",
+            data={
+                "sub_type": sub_type,
+                "duration": duration,
+                "banned_user_info": banned_user_info.to_dict() if banned_user_info else None,
+            },
+        )
+
+        return seg_data, operator_info
+
+    async def handle_lift_ban_notify(
+        self, raw_message: dict, group_id: int
+    ) -> Tuple[Seg, UserInfo] | Tuple[None, None]:
+        if not group_id:
+            logger.error("群ID不能为空，无法处理解除禁言通知")
+            return None, None
+
+        # 计算user_info
+        operator_id = raw_message.get("operator_id")
+        operator_nickname: str = None
+        operator_cardname: str = None
+
+        member_info: dict = await get_member_info(self.server_connection, group_id, operator_id)
+        if member_info:
+            operator_nickname = member_info.get("nickname")
+            operator_cardname = member_info.get("card")
+        else:
+            logger.warning("无法获取解除禁言执行者的昵称，消息可能会无效")
+            operator_nickname = "QQ用户"
+
+        operator_info: UserInfo = UserInfo(
+            platform=global_config.maibot_server.platform_name,
+            user_id=operator_id,
+            user_nickname=operator_nickname,
+            user_cardname=operator_cardname,
+        )
+
+        # 计算Seg
+        sub_type: str = None
+        user_nickname: str = "QQ用户"
+        user_cardname: str = None
+        lifted_user_info: UserInfo = None
+
+        user_id = raw_message.get("user_id")
+        if user_id == 0:  # 全体禁言解除
+            sub_type = "whole_lift_ban"
+            self._lift_operation(group_id)
+        else:  # 单人禁言解除
+            sub_type = "lift_ban"
+            # 获取被解除禁言人的信息
+            fetched_member_info: dict = await get_member_info(self.server_connection, group_id, user_id)
+            if fetched_member_info:
+                user_nickname = fetched_member_info.get("nickname")
+                user_cardname = fetched_member_info.get("card")
+            else:
+                logger.warning("无法获取解除禁言消息发送者的昵称，消息可能会无效")
+            lifted_user_info: UserInfo = UserInfo(
+                platform=global_config.maibot_server.platform_name,
+                user_id=user_id,
+                user_nickname=user_nickname,
+                user_cardname=user_cardname,
+            )
+            self._lift_operation(group_id, user_id)
+
+        seg_data: Seg = Seg(
+            type="notify",
+            data={
+                "sub_type": sub_type,
+                "lifted_user_info": lifted_user_info.to_dict() if lifted_user_info else None,
+            },
+        )
+        return seg_data, operator_info
+
+    async def put_notice(self, message_base: MessageBase) -> None:
+        """
+        将处理后的通知消息放入通知队列
+        """
+        if notice_queue.full() or unsuccessful_notice_queue.full():
+            logger.warning("通知队列已满，可能是多次发送失败，消息丢弃")
+        else:
+            await notice_queue.put(message_base)
+
+    async def handle_natural_lift(self) -> None:
+        while True:
+            if len(self.lifted_list) != 0:
+                lift_record = self.lifted_list.pop()
+                group_id = lift_record.group_id
+                user_id = lift_record.user_id
+
+                db_manager.delete_ban_record(lift_record)  # 从数据库中删除禁言记录
+
+                seg_message: Seg = await self.natural_lift(group_id, user_id)
+
+                fetched_group_info = await get_group_info(self.server_connection, group_id)
+                group_name: str = None
+                if fetched_group_info:
+                    group_name = fetched_group_info.get("group_name")
+                else:
+                    logger.warning("无法获取notice消息所在群的名称")
+                group_info = GroupInfo(
+                    platform=global_config.maibot_server.platform_name,
+                    group_id=group_id,
+                    group_name=group_name,
+                )
+
+                message_info: BaseMessageInfo = BaseMessageInfo(
+                    platform=global_config.maibot_server.platform_name,
+                    message_id="notice",
+                    time=time.time(),
+                    user_info=None,  # 自然解除禁言没有操作者
+                    group_info=group_info,
+                    template_info=None,
+                    format_info=None,
+                )
+
+                message_base: MessageBase = MessageBase(
+                    message_info=message_info,
+                    message_segment=seg_message,
+                    raw_message=json.dumps(
+                        {
+                            "post_type": "notice",
+                            "notice_type": "group_ban",
+                            "sub_type": "lift_ban",
+                            "group_id": group_id,
+                            "user_id": user_id,
+                            "operator_id": None,  # 自然解除禁言没有操作者
+                        }
+                    ),
+                )
+
+                await self.put_notice(message_base)
+                await asyncio.sleep(0.5)  # 确保队列处理间隔
+            else:
+                await asyncio.sleep(5)  # 每5秒检查一次
+
+    async def natural_lift(self, group_id: int, user_id: int) -> Seg | None:
+        if not group_id:
+            logger.error("群ID不能为空，无法处理解除禁言通知")
+            return None
+
+        if user_id == 0:  # 理论上永远不会触发
+            return Seg(
+                type="notify",
+                data={
+                    "sub_type": "whole_lift_ban",
+                    "lifted_user_info": None,
+                },
+            )
+
+        user_nickname: str = "QQ用户"
+        user_cardname: str = None
+        fetched_member_info: dict = await get_member_info(self.server_connection, group_id, user_id)
+        if fetched_member_info:
+            user_nickname = fetched_member_info.get("nickname")
+            user_cardname = fetched_member_info.get("card")
+
+        lifted_user_info: UserInfo = UserInfo(
+            platform=global_config.maibot_server.platform_name,
+            user_id=user_id,
+            user_nickname=user_nickname,
+            user_cardname=user_cardname,
+        )
+
+        return Seg(
+            type="notify",
+            data={
+                "sub_type": "lift_ban",
+                "lifted_user_info": lifted_user_info.to_dict(),
+            },
+        )
+
+    async def auto_lift_detect(self) -> None:
+        while True:
+            if len(self.banned_list) == 0:
+                await asyncio.sleep(5)
+                continue
+            for ban_record in self.banned_list:
+                if ban_record.user_id == 0 or ban_record.lift_time == -1:
+                    continue
+                if ban_record.lift_time <= int(time.time()):
+                    # 触发自然解除禁言
+                    logger.info(f"检测到用户 {ban_record.user_id} 在群 {ban_record.group_id} 的禁言已解除")
+                    self.lifted_list.append(ban_record)
+                    self.banned_list.remove(ban_record)
+            await asyncio.sleep(5)
+
+    async def send_notice(self) -> None:
+        """
+        发送通知消息到Napcat
+        """
+        while True:
+            if not unsuccessful_notice_queue.empty():
+                to_be_send: MessageBase = await unsuccessful_notice_queue.get()
+                try:
+                    send_status = await message_send_instance.message_send(to_be_send)
+                    if send_status:
+                        unsuccessful_notice_queue.task_done()
+                    else:
+                        await unsuccessful_notice_queue.put(to_be_send)
+                except Exception as e:
+                    logger.error(f"发送通知消息失败: {str(e)}")
+                    await unsuccessful_notice_queue.put(to_be_send)
+                await asyncio.sleep(1)
+                continue
+            to_be_send: MessageBase = await notice_queue.get()
+            try:
+                send_status = await message_send_instance.message_send(to_be_send)
+                if send_status:
+                    notice_queue.task_done()
+                else:
+                    await unsuccessful_notice_queue.put(to_be_send)
+            except Exception as e:
+                logger.error(f"发送通知消息失败: {str(e)}")
+                await unsuccessful_notice_queue.put(to_be_send)
+            await asyncio.sleep(1)
+
+
+notice_handler = NoticeHandler()

MaiBot-Napcat-Adapter-dev/src/recv_handler/qq_emoji_list.py

@@ -0,0 +1,250 @@
+qq_face: dict = {
+    "0": "[表情：惊讶]",
+    "1": "[表情：撇嘴]",
+    "2": "[表情：色]",
+    "3": "[表情：发呆]",
+    "4": "[表情：得意]",
+    "5": "[表情：流泪]",
+    "6": "[表情：害羞]",
+    "7": "[表情：闭嘴]",
+    "8": "[表情：睡]",
+    "9": "[表情：大哭]",
+    "10": "[表情：尴尬]",
+    "11": "[表情：发怒]",
+    "12": "[表情：调皮]",
+    "13": "[表情：呲牙]",
+    "14": "[表情：微笑]",
+    "15": "[表情：难过]",
+    "16": "[表情：酷]",
+    "18": "[表情：抓狂]",
+    "19": "[表情：吐]",
+    "20": "[表情：偷笑]",
+    "21": "[表情：可爱]",
+    "22": "[表情：白眼]",
+    "23": "[表情：傲慢]",
+    "24": "[表情：饥饿]",
+    "25": "[表情：困]",
+    "26": "[表情：惊恐]",
+    "27": "[表情：流汗]",
+    "28": "[表情：憨笑]",
+    "29": "[表情：悠闲]",
+    "30": "[表情：奋斗]",
+    "31": "[表情：咒骂]",
+    "32": "[表情：疑问]",
+    "33": "[表情： 嘘]",
+    "34": "[表情：晕]",
+    "35": "[表情：折磨]",
+    "36": "[表情：衰]",
+    "37": "[表情：骷髅]",
+    "38": "[表情：敲打]",
+    "39": "[表情：再见]",
+    "41": "[表情：发抖]",
+    "42": "[表情：爱情]",
+    "43": "[表情：跳跳]",
+    "46": "[表情：猪头]",
+    "49": "[表情：拥抱]",
+    "53": "[表情：蛋糕]",
+    "56": "[表情：刀]",
+    "59": "[表情：便便]",
+    "60": "[表情：咖啡]",
+    "63": "[表情：玫瑰]",
+    "64": "[表情：凋谢]",
+    "66": "[表情：爱心]",
+    "67": "[表情：心碎]",
+    "74": "[表情：太阳]",
+    "75": "[表情：月亮]",
+    "76": "[表情：赞]",
+    "77": "[表情：踩]",
+    "78": "[表情：握手]",
+    "79": "[表情：胜利]",
+    "85": "[表情：飞吻]",
+    "86": "[表情：怄火]",
+    "89": "[表情：西瓜]",
+    "96": "[表情：冷汗]",
+    "97": "[表情：擦汗]",
+    "98": "[表情：抠鼻]",
+    "99": "[表情：鼓掌]",
+    "100": "[表情：糗大了]",
+    "101": "[表情：坏笑]",
+    "102": "[表情：左哼哼]",
+    "103": "[表情：右哼哼]",
+    "104": "[表情：哈欠]",
+    "105": "[表情：鄙视]",
+    "106": "[表情：委屈]",
+    "107": "[表情：快哭了]",
+    "108": "[表情：阴险]",
+    "109": "[表情：左亲亲]",
+    "110": "[表情：吓]",
+    "111": "[表情：可怜]",
+    "112": "[表情：菜刀]",
+    "114": "[表情：篮球]",
+    "116": "[表情：示爱]",
+    "118": "[表情：抱拳]",
+    "119": "[表情：勾引]",
+    "120": "[表情：拳头]",
+    "121": "[表情：差劲]",
+    "123": "[表情：NO]",
+    "124": "[表情：OK]",
+    "125": "[表情：转圈]",
+    "129": "[表情：挥手]",
+    "137": "[表情：鞭炮]",
+    "144": "[表情：喝彩]",
+    "146": "[表情：爆筋]",
+    "147": "[表情：棒棒糖]",
+    "169": "[表情：手枪]",
+    "171": "[表情：茶]",
+    "172": "[表情：眨眼睛]",
+    "173": "[表情：泪奔]",
+    "174": "[表情：无奈]",
+    "175": "[表情：卖萌]",
+    "176": "[表情：小纠结]",
+    "177": "[表情：喷血]",
+    "178": "[表情：斜眼笑]",
+    "179": "[表情：doge]",
+    "181": "[表情：戳一戳]",
+    "182": "[表情：笑哭]",
+    "183": "[表情：我最美]",
+    "185": "[表情：羊驼]",
+    "187": "[表情：幽灵]",
+    "201": "[表情：点赞]",
+    "212": "[表情：托腮]",
+    "262": "[表情：脑阔疼]",
+    "263": "[表情：沧桑]",
+    "264": "[表情：捂脸]",
+    "265": "[表情：辣眼睛]",
+    "266": "[表情：哦哟]",
+    "267": "[表情：头秃]",
+    "268": "[表情：问号脸]",
+    "269": "[表情：暗中观察]",
+    "270": "[表情：emm]",
+    "271": "[表情：吃 瓜]",
+    "272": "[表情：呵呵哒]",
+    "273": "[表情：我酸了]",
+    "277": "[表情：汪汪]",
+    "281": "[表情：无眼笑]",
+    "282": "[表情：敬礼]",
+    "283": "[表情：狂笑]",
+    "284": "[表情：面无表情]",
+    "285": "[表情：摸鱼]",
+    "286": "[表情：魔鬼笑]",
+    "287": "[表情：哦]",
+    "289": "[表情：睁眼]",
+    "293": "[表情：摸锦鲤]",
+    "294": "[表情：期待]",
+    "295": "[表情：拿到红包]",
+    "297": "[表情：拜谢]",
+    "298": "[表情：元宝]",
+    "299": "[表情：牛啊]",
+    "300": "[表情：胖三斤]",
+    "302": "[表情：左拜年]",
+    "303": "[表情：右拜年]",
+    "305": "[表情：右亲亲]",
+    "306": "[表情：牛气冲天]",
+    "307": "[表情：喵喵]",
+    "311": "[表情：打call]",
+    "312": "[表情：变形]",
+    "314": "[表情：仔细分析]",
+    "317": "[表情：菜汪]",
+    "318": "[表情：崇拜]",
+    "319": "[表情： 比心]",
+    "320": "[表情：庆祝]",
+    "323": "[表情：嫌弃]",
+    "324": "[表情：吃糖]",
+    "325": "[表情：惊吓]",
+    "326": "[表情：生气]",
+    "332": "[表情：举牌牌]",
+    "333": "[表情：烟花]",
+    "334": "[表情：虎虎生威]",
+    "336": "[表情：豹富]",
+    "337": "[表情：花朵脸]",
+    "338": "[表情：我想开了]",
+    "339": "[表情：舔屏]",
+    "341": "[表情：打招呼]",
+    "342": "[表情：酸Q]",
+    "343": "[表情：我方了]",
+    "344": "[表情：大怨种]",
+    "345": "[表情：红包多多]",
+    "346": "[表情：你真棒棒]",
+    "347": "[表情：大展宏兔]",
+    "349": "[表情：坚强]",
+    "350": "[表情：贴贴]",
+    "351": "[表情：敲敲]",
+    "352": "[表情：咦]",
+    "353": "[表情：拜托]",
+    "354": "[表情：尊嘟假嘟]",
+    "355": "[表情：耶]",
+    "356": "[表情：666]",
+    "357": "[表情：裂开]",
+    "392": "[表情：龙年 快乐]",
+    "393": "[表情：新年中龙]",
+    "394": "[表情：新年大龙]",
+    "395": "[表情：略略略]",
+    "😊": "[表情：嘿嘿]",
+    "😌": "[表情：羞涩]",
+    "😚": "[ 表情：亲亲]",
+    "😓": "[表情：汗]",
+    "😰": "[表情：紧张]",
+    "😝": "[表情：吐舌]",
+    "😁": "[表情：呲牙]",
+    "😜": "[表情：淘气]",
+    "☺": "[表情：可爱]",
+    "😍": "[表情：花痴]",
+    "😔": "[表情：失落]",
+    "😄": "[表情：高兴]",
+    "😏": "[表情：哼哼]",
+    "😒": "[表情：不屑]",
+    "😳": "[表情：瞪眼]",
+    "😘": "[表情：飞吻]",
+    "😭": "[表情：大哭]",
+    "😱": "[表情：害怕]",
+    "😂": "[表情：激动]",
+    "💪": "[表情：肌肉]",
+    "👊": "[表情：拳头]",
+    "👍": "[表情 ：厉害]",
+    "👏": "[表情：鼓掌]",
+    "👎": "[表情：鄙视]",
+    "🙏": "[表情：合十]",
+    "👌": "[表情：好的]",
+    "👆": "[表情：向上]",
+    "👀": "[表情：眼睛]",
+    "🍜": "[表情：拉面]",
+    "🍧": "[表情：刨冰]",
+    "🍞": "[表情：面包]",
+    "🍺": "[表情：啤酒]",
+    "🍻": "[表情：干杯]",
+    "☕": "[表情：咖啡]",
+    "🍎": "[表情：苹果]",
+    "🍓": "[表情：草莓]",
+    "🍉": "[表情：西瓜]",
+    "🚬": "[表情：吸烟]",
+    "🌹": "[表情：玫瑰]",
+    "🎉": "[表情：庆祝]",
+    "💝": "[表情：礼物]",
+    "💣": "[表情：炸弹]",
+    "✨": "[表情：闪光]",
+    "💨": "[表情：吹气]",
+    "💦": "[表情：水]",
+    "🔥": "[表情：火]",
+    "💤": "[表情：睡觉]",
+    "💩": "[表情：便便]",
+    "💉": "[表情：打针]",
+    "📫": "[表情：邮箱]",
+    "🐎": "[表情：骑马]",
+    "👧": "[表情：女孩]",
+    "👦": "[表情：男孩]",
+    "🐵": "[表情：猴]",
+    "🐷": "[表情：猪]",
+    "🐮": "[表情：牛]",
+    "🐔": "[表情：公鸡]",
+    "🐸": "[表情：青蛙]",
+    "👻": "[表情：幽灵]",
+    "🐛": "[表情：虫]",
+    "🐶": "[表情：狗]",
+    "🐳": "[表情：鲸鱼]",
+    "👢": "[表情：靴子]",
+    "☀": "[表情：晴天]",
+    "❔": "[表情：问号]",
+    "🔫": "[表情：手枪]",
+    "💓": "[表情：爱 心]",
+    "🏪": "[表情：便利店]",
+}

MaiBot-Napcat-Adapter-dev/src/response_pool.py

@@ -0,0 +1,44 @@
+import asyncio
+import time
+from typing import Dict
+from .config import global_config
+from .logger import logger
+
+response_dict: Dict = {}
+response_time_dict: Dict = {}
+
+
+async def get_response(request_id: str, timeout: int = 10) -> dict:
+    response = await asyncio.wait_for(_get_response(request_id), timeout)
+    _ = response_time_dict.pop(request_id)
+    logger.trace(f"响应信息id: {request_id} 已从响应字典中取出")
+    return response
+
+async def _get_response(request_id: str) -> dict:
+    """
+    内部使用的获取响应函数，主要用于在需要时获取响应
+    """
+    while request_id not in response_dict:
+        await asyncio.sleep(0.2)
+    return response_dict.pop(request_id)
+
+async def put_response(response: dict):
+    echo_id = response.get("echo")
+    now_time = time.time()
+    response_dict[echo_id] = response
+    response_time_dict[echo_id] = now_time
+    logger.trace(f"响应信息id: {echo_id} 已存入响应字典")
+
+
+async def check_timeout_response() -> None:
+    while True:
+        cleaned_message_count: int = 0
+        now_time = time.time()
+        for echo_id, response_time in list(response_time_dict.items()):
+            if now_time - response_time > global_config.napcat_server.heartbeat_interval:
+                cleaned_message_count += 1
+                response_dict.pop(echo_id)
+                response_time_dict.pop(echo_id)
+                logger.warning(f"响应消息 {echo_id} 超时，已删除")
+        logger.info(f"已删除 {cleaned_message_count} 条超时响应消息")
+        await asyncio.sleep(global_config.napcat_server.heartbeat_interval)

MaiBot-Napcat-Adapter-dev/src/send_handler.py

@@ -0,0 +1,461 @@
+import json
+import websockets as Server
+import uuid
+from maim_message import (
+    UserInfo,
+    GroupInfo,
+    Seg,
+    BaseMessageInfo,
+    MessageBase,
+)
+from typing import Dict, Any, Tuple
+
+from . import CommandType
+from .config import global_config
+from .response_pool import get_response
+from .logger import logger
+from .utils import get_image_format, convert_image_to_gif
+from .recv_handler.message_sending import message_send_instance
+
+
+class SendHandler:
+    def __init__(self):
+        self.server_connection: Server.ServerConnection = None
+
+    async def set_server_connection(self, server_connection: Server.ServerConnection) -> None:
+        """设置Napcat连接"""
+        self.server_connection = server_connection
+
+    async def handle_message(self, raw_message_base_dict: dict) -> None:
+        raw_message_base: MessageBase = MessageBase.from_dict(raw_message_base_dict)
+        message_segment: Seg = raw_message_base.message_segment
+        logger.info("接收到来自MaiBot的消息，处理中")
+        if message_segment.type == "command":
+            return await self.send_command(raw_message_base)
+        else:
+            return await self.send_normal_message(raw_message_base)
+
+    async def send_normal_message(self, raw_message_base: MessageBase) -> None:
+        """
+        处理普通消息发送
+        """
+        logger.info("处理普通信息中")
+        message_info: BaseMessageInfo = raw_message_base.message_info
+        message_segment: Seg = raw_message_base.message_segment
+        group_info: GroupInfo = message_info.group_info
+        user_info: UserInfo = message_info.user_info
+        target_id: int = None
+        action: str = None
+        id_name: str = None
+        processed_message: list = []
+        try:
+            processed_message = await self.handle_seg_recursive(message_segment)
+        except Exception as e:
+            logger.error(f"处理消息时发生错误: {e}")
+            return
+
+        if not processed_message:
+            logger.critical("现在暂时不支持解析此回复！")
+            return None
+
+        if group_info and user_info:
+            logger.debug("发送群聊消息")
+            target_id = group_info.group_id
+            action = "send_group_msg"
+            id_name = "group_id"
+        elif user_info:
+            logger.debug("发送私聊消息")
+            target_id = user_info.user_id
+            action = "send_private_msg"
+            id_name = "user_id"
+        else:
+            logger.error("无法识别的消息类型")
+            return
+        logger.info("尝试发送到napcat")
+        response = await self.send_message_to_napcat(
+            action,
+            {
+                id_name: target_id,
+                "message": processed_message,
+            },
+        )
+        if response.get("status") == "ok":
+            logger.info("消息发送成功")
+            qq_message_id = response.get("data", {}).get("message_id")
+            await self.message_sent_back(raw_message_base, qq_message_id)
+        else:
+            logger.warning(f"消息发送失败，napcat返回：{str(response)}")
+
+    async def send_command(self, raw_message_base: MessageBase) -> None:
+        """
+        处理命令类
+        """
+        logger.info("处理命令中")
+        message_info: BaseMessageInfo = raw_message_base.message_info
+        message_segment: Seg = raw_message_base.message_segment
+        group_info: GroupInfo = message_info.group_info
+        seg_data: Dict[str, Any] = message_segment.data
+        command_name: str = seg_data.get("name")
+        try:
+            match command_name:
+                case CommandType.GROUP_BAN.name:
+                    command, args_dict = self.handle_ban_command(seg_data.get("args"), group_info)
+                case CommandType.GROUP_WHOLE_BAN.name:
+                    command, args_dict = self.handle_whole_ban_command(seg_data.get("args"), group_info)
+                case CommandType.GROUP_KICK.name:
+                    command, args_dict = self.handle_kick_command(seg_data.get("args"), group_info)
+                case CommandType.SEND_POKE.name:
+                    command, args_dict = self.handle_poke_command(seg_data.get("args"), group_info)
+                case CommandType.DELETE_MSG.name:
+                    command, args_dict = self.delete_msg_command(seg_data.get("args"))
+                case CommandType.AI_VOICE_SEND.name:
+                    command, args_dict = self.handle_ai_voice_send_command(seg_data.get("args"), group_info)
+                case _:
+                    logger.error(f"未知命令: {command_name}")
+                    return
+        except Exception as e:
+            logger.error(f"处理命令时发生错误: {e}")
+            return None
+
+        if not command or not args_dict:
+            logger.error("命令或参数缺失")
+            return None
+
+        response = await self.send_message_to_napcat(command, args_dict)
+        if response.get("status") == "ok":
+            logger.info(f"命令 {command_name} 执行成功")
+        else:
+            logger.warning(f"命令 {command_name} 执行失败，napcat返回：{str(response)}")
+
+    def get_level(self, seg_data: Seg) -> int:
+        if seg_data.type == "seglist":
+            return 1 + max(self.get_level(seg) for seg in seg_data.data)
+        else:
+            return 1
+
+    async def handle_seg_recursive(self, seg_data: Seg) -> list:
+        payload: list = []
+        if seg_data.type == "seglist":
+            # level = self.get_level(seg_data)  # 给以后可能的多层嵌套做准备，此处不使用
+            if not seg_data.data:
+                return []
+            for seg in seg_data.data:
+                payload = self.process_message_by_type(seg, payload)
+        else:
+            payload = self.process_message_by_type(seg_data, payload)
+        return payload
+
+    def process_message_by_type(self, seg: Seg, payload: list) -> list:
+        # sourcery skip: reintroduce-else, swap-if-else-branches, use-named-expression
+        new_payload = payload
+        if seg.type == "reply":
+            target_id = seg.data
+            if target_id == "notice":
+                return payload
+            new_payload = self.build_payload(payload, self.handle_reply_message(target_id), True)
+        elif seg.type == "text":
+            text = seg.data
+            if not text:
+                return payload
+            new_payload = self.build_payload(payload, self.handle_text_message(text), False)
+        elif seg.type == "face":
+            logger.warning("MaiBot 发送了qq原生表情，暂时不支持")
+        elif seg.type == "image":
+            image = seg.data
+            new_payload = self.build_payload(payload, self.handle_image_message(image), False)
+        elif seg.type == "emoji":
+            emoji = seg.data
+            new_payload = self.build_payload(payload, self.handle_emoji_message(emoji), False)
+        elif seg.type == "voice":
+            voice = seg.data
+            new_payload = self.build_payload(payload, self.handle_voice_message(voice), False)
+        elif seg.type == "voiceurl":
+            voice_url = seg.data
+            new_payload = self.build_payload(payload, self.handle_voiceurl_message(voice_url), False)
+        elif seg.type == "music":
+            song_id = seg.data
+            new_payload = self.build_payload(payload, self.handle_music_message(song_id), False)
+        elif seg.type == "videourl":
+            video_url = seg.data
+            new_payload = self.build_payload(payload, self.handle_videourl_message(video_url), False)
+        elif seg.type == "file":
+            file_path = seg.data
+            new_payload = self.build_payload(payload, self.handle_file_message(file_path), False)
+        return new_payload
+
+    def build_payload(self, payload: list, addon: dict, is_reply: bool = False) -> list:
+        # sourcery skip: for-append-to-extend, merge-list-append, simplify-generator
+        """构建发送的消息体"""
+        if is_reply:
+            temp_list = []
+            temp_list.append(addon)
+            for i in payload:
+                if i.get("type") == "reply":
+                    logger.debug("检测到多个回复，使用最新的回复")
+                    continue
+                temp_list.append(i)
+            return temp_list
+        else:
+            payload.append(addon)
+            return payload
+
+    def handle_reply_message(self, id: str) -> dict:
+        """处理回复消息"""
+        return {"type": "reply", "data": {"id": id}}
+
+    def handle_text_message(self, message: str) -> dict:
+        """处理文本消息"""
+        return {"type": "text", "data": {"text": message}}
+
+    def handle_image_message(self, encoded_image: str) -> dict:
+        """处理图片消息"""
+        return {
+            "type": "image",
+            "data": {
+                "file": f"base64://{encoded_image}",
+                "subtype": 0,
+            },
+        }  # base64 编码的图片
+
+    def handle_emoji_message(self, encoded_emoji: str) -> dict:
+        """处理表情消息"""
+        encoded_image = encoded_emoji
+        image_format = get_image_format(encoded_emoji)
+        if image_format != "gif":
+            encoded_image = convert_image_to_gif(encoded_emoji)
+        return {
+            "type": "image",
+            "data": {
+                "file": f"base64://{encoded_image}",
+                "subtype": 1,
+                "summary": "[动画表情]",
+            },
+        }
+
+    def handle_voice_message(self, encoded_voice: str) -> dict:
+        """处理语音消息"""
+        if not global_config.voice.use_tts:
+            logger.warning("未启用语音消息处理")
+            return {}
+        if not encoded_voice:
+            return {}
+        return {
+            "type": "record",
+            "data": {"file": f"base64://{encoded_voice}"},
+        }
+
+    def handle_voiceurl_message(self, voice_url: str) -> dict:
+        """处理语音链接消息"""
+        return {
+            "type": "record",
+            "data": {"file": voice_url},
+        }
+
+    def handle_music_message(self, song_id: str) -> dict:
+        """处理音乐消息"""
+        return {
+            "type": "music",
+            "data": {"type": "163", "id": song_id},
+        }
+    def handle_videourl_message(self, video_url: str) -> dict:
+        """处理视频链接消息"""
+        return {
+            "type": "video",
+            "data": {"file": video_url},
+        }
+
+    def handle_file_message(self, file_path: str) -> dict:
+        """处理文件消息"""
+        return {
+            "type": "file",
+            "data": {"file": f"file://{file_path}"},
+        }
+
+    def handle_ban_command(self, args: Dict[str, Any], group_info: GroupInfo) -> Tuple[str, Dict[str, Any]]:
+        """处理封禁命令
+
+        Args:
+            args (Dict[str, Any]): 参数字典
+            group_info (GroupInfo): 群聊信息（对应目标群聊）
+
+        Returns:
+            Tuple[CommandType, Dict[str, Any]]
+        """
+        duration: int = int(args["duration"])
+        user_id: int = int(args["qq_id"])
+        group_id: int = int(group_info.group_id)
+        if duration < 0:
+            raise ValueError("封禁时间必须大于等于0")
+        if not user_id or not group_id:
+            raise ValueError("封禁命令缺少必要参数")
+        if duration > 2592000:
+            raise ValueError("封禁时间不能超过30天")
+        return (
+            CommandType.GROUP_BAN.value,
+            {
+                "group_id": group_id,
+                "user_id": user_id,
+                "duration": duration,
+            },
+        )
+
+    def handle_whole_ban_command(self, args: Dict[str, Any], group_info: GroupInfo) -> Tuple[str, Dict[str, Any]]:
+        """处理全体禁言命令
+
+        Args:
+            args (Dict[str, Any]): 参数字典
+            group_info (GroupInfo): 群聊信息（对应目标群聊）
+
+        Returns:
+            Tuple[CommandType, Dict[str, Any]]
+        """
+        enable = args["enable"]
+        assert isinstance(enable, bool), "enable参数必须是布尔值"
+        group_id: int = int(group_info.group_id)
+        if group_id <= 0:
+            raise ValueError("群组ID无效")
+        return (
+            CommandType.GROUP_WHOLE_BAN.value,
+            {
+                "group_id": group_id,
+                "enable": enable,
+            },
+        )
+
+    def handle_kick_command(self, args: Dict[str, Any], group_info: GroupInfo) -> Tuple[str, Dict[str, Any]]:
+        """处理群成员踢出命令
+
+        Args:
+            args (Dict[str, Any]): 参数字典
+            group_info (GroupInfo): 群聊信息（对应目标群聊）
+
+        Returns:
+            Tuple[CommandType, Dict[str, Any]]
+        """
+        user_id: int = int(args["qq_id"])
+        group_id: int = int(group_info.group_id)
+        if group_id <= 0:
+            raise ValueError("群组ID无效")
+        if user_id <= 0:
+            raise ValueError("用户ID无效")
+        return (
+            CommandType.GROUP_KICK.value,
+            {
+                "group_id": group_id,
+                "user_id": user_id,
+                "reject_add_request": False,  # 不拒绝加群请求
+            },
+        )
+
+    def handle_poke_command(self, args: Dict[str, Any], group_info: GroupInfo) -> Tuple[str, Dict[str, Any]]:
+        """处理戳一戳命令
+
+        Args:
+            args (Dict[str, Any]): 参数字典
+            group_info (GroupInfo): 群聊信息（对应目标群聊）
+
+        Returns:
+            Tuple[CommandType, Dict[str, Any]]
+        """
+        user_id: int = int(args["qq_id"])
+        if group_info is None:
+            group_id = None
+        else:
+            group_id: int = int(group_info.group_id)
+            if group_id <= 0:
+                raise ValueError("群组ID无效")
+        if user_id <= 0:
+            raise ValueError("用户ID无效")
+        return (
+            CommandType.SEND_POKE.value,
+            {
+                "group_id": group_id,
+                "user_id": user_id,
+            },
+        )
+
+    def delete_msg_command(self, args: Dict[str, Any]) -> Tuple[str, Dict[str, Any]]:
+        """处理撤回消息命令
+
+        Args:
+            args (Dict[str, Any]): 参数字典
+
+        Returns:
+            Tuple[CommandType, Dict[str, Any]]
+        """
+        try:
+            message_id = int(args["message_id"])
+            if message_id <= 0:
+                raise ValueError("消息ID无效")
+        except KeyError:
+            raise ValueError("缺少必需参数: message_id") from None
+        except (ValueError, TypeError) as e:
+            raise ValueError(f"消息ID无效: {args['message_id']} - {str(e)}") from None
+
+        return (
+            CommandType.DELETE_MSG.value,
+            {
+                "message_id": message_id,
+            },
+        )
+
+    def handle_ai_voice_send_command(self, args: Dict[str, Any], group_info: GroupInfo) -> Tuple[str, Dict[str, Any]]:
+        """
+        处理AI语音发送命令的逻辑。
+        并返回 NapCat 兼容的 (action, params) 元组。
+        """
+        if not group_info or not group_info.group_id:
+            raise ValueError("AI语音发送命令必须在群聊上下文中使用")
+        if not args:
+            raise ValueError("AI语音发送命令缺少参数")
+
+        group_id: int = int(group_info.group_id)
+        character_id = args.get("character")
+        text_content = args.get("text")
+
+        if not character_id or not text_content:
+            raise ValueError(f"AI语音发送命令参数不完整: character='{character_id}', text='{text_content}'")
+
+        return (
+            CommandType.AI_VOICE_SEND.value,
+            {
+                "group_id": group_id,
+                "text": text_content,
+                "character": character_id,
+            },
+        )
+
+    async def send_message_to_napcat(self, action: str, params: dict) -> dict:
+        request_uuid = str(uuid.uuid4())
+        payload = json.dumps({"action": action, "params": params, "echo": request_uuid})
+        await self.server_connection.send(payload)
+        try:
+            response = await get_response(request_uuid)
+        except TimeoutError:
+            logger.error("发送消息超时，未收到响应")
+            return {"status": "error", "message": "timeout"}
+        except Exception as e:
+            logger.error(f"发送消息失败: {e}")
+            return {"status": "error", "message": str(e)}
+        return response
+
+    async def message_sent_back(self, message_base: MessageBase, qq_message_id: str) -> None:
+        # 修改 additional_config，添加 echo 字段
+        if message_base.message_info.additional_config is None:
+            message_base.message_info.additional_config = {}
+
+        message_base.message_info.additional_config["echo"] = True
+
+        # 获取原始的 mmc_message_id
+        mmc_message_id = message_base.message_info.message_id
+
+        # 修改 message_segment 为 notify 类型
+        message_base.message_segment = Seg(
+            type="notify", data={"sub_type": "echo", "echo": mmc_message_id, "actual_id": qq_message_id}
+        )
+        await message_send_instance.message_send(message_base)
+        logger.debug("已回送消息ID")
+        return
+
+
+send_handler = SendHandler()

MaiBot-Napcat-Adapter-dev/src/utils.py

@@ -0,0 +1,310 @@
+import websockets as Server
+import json
+import base64
+import uuid
+import urllib3
+import ssl
+import io
+
+from src.database import BanUser, db_manager
+from .logger import logger
+from .response_pool import get_response
+
+from PIL import Image
+from typing import Union, List, Tuple, Optional
+
+
+class SSLAdapter(urllib3.PoolManager):
+    def __init__(self, *args, **kwargs):
+        context = ssl.create_default_context()
+        context.set_ciphers("DEFAULT@SECLEVEL=1")
+        context.minimum_version = ssl.TLSVersion.TLSv1_2
+        kwargs["ssl_context"] = context
+        super().__init__(*args, **kwargs)
+
+
+async def get_group_info(websocket: Server.ServerConnection, group_id: int) -> dict | None:
+    """
+    获取群相关信息
+
+    返回值需要处理可能为空的情况
+    """
+    logger.debug("获取群聊信息中")
+    request_uuid = str(uuid.uuid4())
+    payload = json.dumps({"action": "get_group_info", "params": {"group_id": group_id}, "echo": request_uuid})
+    try:
+        await websocket.send(payload)
+        socket_response: dict = await get_response(request_uuid)
+    except TimeoutError:
+        logger.error(f"获取群信息超时，群号: {group_id}")
+        return None
+    except Exception as e:
+        logger.error(f"获取群信息失败: {e}")
+        return None
+    logger.debug(socket_response)
+    return socket_response.get("data")
+
+
+async def get_group_detail_info(websocket: Server.ServerConnection, group_id: int) -> dict | None:
+    """
+    获取群详细信息
+
+    返回值需要处理可能为空的情况
+    """
+    logger.debug("获取群详细信息中")
+    request_uuid = str(uuid.uuid4())
+    payload = json.dumps({"action": "get_group_detail_info", "params": {"group_id": group_id}, "echo": request_uuid})
+    try:
+        await websocket.send(payload)
+        socket_response: dict = await get_response(request_uuid)
+    except TimeoutError:
+        logger.error(f"获取群详细信息超时，群号: {group_id}")
+        return None
+    except Exception as e:
+        logger.error(f"获取群详细信息失败: {e}")
+        return None
+    logger.debug(socket_response)
+    return socket_response.get("data")
+
+
+async def get_member_info(websocket: Server.ServerConnection, group_id: int, user_id: int) -> dict | None:
+    """
+    获取群成员信息
+
+    返回值需要处理可能为空的情况
+    """
+    logger.debug("获取群成员信息中")
+    request_uuid = str(uuid.uuid4())
+    payload = json.dumps(
+        {
+            "action": "get_group_member_info",
+            "params": {"group_id": group_id, "user_id": user_id, "no_cache": True},
+            "echo": request_uuid,
+        }
+    )
+    try:
+        await websocket.send(payload)
+        socket_response: dict = await get_response(request_uuid)
+    except TimeoutError:
+        logger.error(f"获取成员信息超时，群号: {group_id}, 用户ID: {user_id}")
+        return None
+    except Exception as e:
+        logger.error(f"获取成员信息失败: {e}")
+        return None
+    logger.debug(socket_response)
+    return socket_response.get("data")
+
+
+async def get_image_base64(url: str) -> str:
+    # sourcery skip: raise-specific-error
+    """获取图片/表情包的Base64"""
+    logger.debug(f"下载图片: {url}")
+    http = SSLAdapter()
+    try:
+        response = http.request("GET", url, timeout=10)
+        if response.status != 200:
+            raise Exception(f"HTTP Error: {response.status}")
+        image_bytes = response.data
+        return base64.b64encode(image_bytes).decode("utf-8")
+    except Exception as e:
+        logger.error(f"图片下载失败: {str(e)}")
+        raise
+
+
+def convert_image_to_gif(image_base64: str) -> str:
+    # sourcery skip: extract-method
+    """
+    将Base64编码的图片转换为GIF格式
+    Parameters:
+        image_base64: str: Base64编码的图片数据
+    Returns:
+        str: Base64编码的GIF图片数据
+    """
+    logger.debug("转换图片为GIF格式")
+    try:
+        image_bytes = base64.b64decode(image_base64)
+        image = Image.open(io.BytesIO(image_bytes))
+        output_buffer = io.BytesIO()
+        image.save(output_buffer, format="GIF")
+        output_buffer.seek(0)
+        return base64.b64encode(output_buffer.read()).decode("utf-8")
+    except Exception as e:
+        logger.error(f"图片转换为GIF失败: {str(e)}")
+        return image_base64
+
+
+async def get_self_info(websocket: Server.ServerConnection) -> dict | None:
+    """
+    获取自身信息
+    Parameters:
+        websocket: WebSocket连接对象
+    Returns:
+        data: dict: 返回的自身信息
+    """
+    logger.debug("获取自身信息中")
+    request_uuid = str(uuid.uuid4())
+    payload = json.dumps({"action": "get_login_info", "params": {}, "echo": request_uuid})
+    try:
+        await websocket.send(payload)
+        response: dict = await get_response(request_uuid)
+    except TimeoutError:
+        logger.error("获取自身信息超时")
+        return None
+    except Exception as e:
+        logger.error(f"获取自身信息失败: {e}")
+        return None
+    logger.debug(response)
+    return response.get("data")
+
+
+def get_image_format(raw_data: str) -> str:
+    """
+    从Base64编码的数据中确定图片的格式。
+    Parameters:
+        raw_data: str: Base64编码的图片数据。
+    Returns:
+        format: str: 图片的格式（例如 'jpeg', 'png', 'gif'）。
+    """
+    image_bytes = base64.b64decode(raw_data)
+    return Image.open(io.BytesIO(image_bytes)).format.lower()
+
+
+async def get_stranger_info(websocket: Server.ServerConnection, user_id: int) -> dict | None:
+    """
+    获取陌生人信息
+    Parameters:
+        websocket: WebSocket连接对象
+        user_id: 用户ID
+    Returns:
+        dict: 返回的陌生人信息
+    """
+    logger.debug("获取陌生人信息中")
+    request_uuid = str(uuid.uuid4())
+    payload = json.dumps({"action": "get_stranger_info", "params": {"user_id": user_id}, "echo": request_uuid})
+    try:
+        await websocket.send(payload)
+        response: dict = await get_response(request_uuid)
+    except TimeoutError:
+        logger.error(f"获取陌生人信息超时，用户ID: {user_id}")
+        return None
+    except Exception as e:
+        logger.error(f"获取陌生人信息失败: {e}")
+        return None
+    logger.debug(response)
+    return response.get("data")
+
+
+async def get_message_detail(websocket: Server.ServerConnection, message_id: Union[str, int]) -> dict | None:
+    """
+    获取消息详情，可能为空
+    Parameters:
+        websocket: WebSocket连接对象
+        message_id: 消息ID
+    Returns:
+        dict: 返回的消息详情
+    """
+    logger.debug("获取消息详情中")
+    request_uuid = str(uuid.uuid4())
+    payload = json.dumps({"action": "get_msg", "params": {"message_id": message_id}, "echo": request_uuid})
+    try:
+        await websocket.send(payload)
+        response: dict = await get_response(request_uuid, 30)  # 增加超时时间到30秒
+    except TimeoutError:
+        logger.error(f"获取消息详情超时，消息ID: {message_id}")
+        return None
+    except Exception as e:
+        logger.error(f"获取消息详情失败: {e}")
+        return None
+    logger.debug(response)
+    return response.get("data")
+
+
+async def get_record_detail(
+    websocket: Server.ServerConnection, file: str, file_id: Optional[str] = None
+) -> dict | None:
+    """
+    获取语音消息内容
+    Parameters:
+        websocket: WebSocket连接对象
+        file: 文件名
+        file_id: 文件ID
+    Returns:
+        dict: 返回的语音消息详情
+    """
+    logger.debug("获取语音消息详情中")
+    request_uuid = str(uuid.uuid4())
+    payload = json.dumps(
+        {
+            "action": "get_record",
+            "params": {"file": file, "file_id": file_id, "out_format": "wav"},
+            "echo": request_uuid,
+        }
+    )
+    try:
+        await websocket.send(payload)
+        response: dict = await get_response(request_uuid, 30)  # 增加超时时间到30秒
+    except TimeoutError:
+        logger.error(f"获取语音消息详情超时，文件: {file}, 文件ID: {file_id}")
+        return None
+    except Exception as e:
+        logger.error(f"获取语音消息详情失败: {e}")
+        return None
+    logger.debug(f"{str(response)[:200]}...")  # 防止语音的超长base64编码导致日志过长
+    return response.get("data")
+
+
+async def read_ban_list(
+    websocket: Server.ServerConnection,
+) -> Tuple[List[BanUser], List[BanUser]]:
+    """
+    从根目录下的data文件夹中的文件读取禁言列表。
+    同时自动更新已经失效禁言
+    Returns:
+        Tuple[
+            一个仍在禁言中的用户的BanUser列表,
+            一个已经自然解除禁言的用户的BanUser列表,
+            一个仍在全体禁言中的群的BanUser列表,
+            一个已经自然解除全体禁言的群的BanUser列表,
+        ]
+    """
+    try:
+        ban_list = db_manager.get_ban_records()
+        lifted_list: List[BanUser] = []
+        logger.info("已经读取禁言列表")
+        for ban_record in ban_list:
+            if ban_record.user_id == 0:
+                fetched_group_info = await get_group_info(websocket, ban_record.group_id)
+                if fetched_group_info is None:
+                    logger.warning(f"无法获取群信息，群号: {ban_record.group_id}，默认禁言解除")
+                    lifted_list.append(ban_record)
+                    ban_list.remove(ban_record)
+                    continue
+                group_all_shut: int = fetched_group_info.get("group_all_shut")
+                if group_all_shut == 0:
+                    lifted_list.append(ban_record)
+                    ban_list.remove(ban_record)
+                    continue
+            else:
+                fetched_member_info = await get_member_info(websocket, ban_record.group_id, ban_record.user_id)
+                if fetched_member_info is None:
+                    logger.warning(
+                        f"无法获取群成员信息，用户ID: {ban_record.user_id}, 群号: {ban_record.group_id}，默认禁言解除"
+                    )
+                    lifted_list.append(ban_record)
+                    ban_list.remove(ban_record)
+                    continue
+                lift_ban_time: int = fetched_member_info.get("shut_up_timestamp")
+                if lift_ban_time == 0:
+                    lifted_list.append(ban_record)
+                    ban_list.remove(ban_record)
+                else:
+                    ban_record.lift_time = lift_ban_time
+        db_manager.update_ban_record(ban_list)
+        return ban_list, lifted_list
+    except Exception as e:
+        logger.error(f"读取禁言列表失败: {e}")
+        return [], []
+
+
+def save_ban_record(list: List[BanUser]):
+    return db_manager.update_ban_record(list)

MaiBot-Napcat-Adapter-dev/template/template_config.toml

@@ -0,0 +1,34 @@
+[inner]
+version = "0.1.1" # 版本号
+# 请勿修改版本号，除非你知道自己在做什么
+
+[nickname] # 现在没用
+nickname = ""
+
+[napcat_server] # Napcat连接的ws服务设置
+host = "localhost"      # Napcat设定的主机地址
+port = 8095             # Napcat设定的端口 
+heartbeat_interval = 30 # 与Napcat设置的心跳相同（按秒计）
+
+[maibot_server] # 连接麦麦的ws服务设置
+host = "localhost" # 麦麦在.env文件中设置的主机地址，即HOST字段
+port = 8000        # 麦麦在.env文件中设置的端口，即PORT字段
+
+[chat] # 黑白名单功能
+group_list_type = "whitelist" # 群组名单类型，可选为：whitelist, blacklist
+group_list = []               # 群组名单
+# 当group_list_type为whitelist时，只有群组名单中的群组可以聊天
+# 当group_list_type为blacklist时，群组名单中的任何群组无法聊天
+private_list_type = "whitelist" # 私聊名单类型，可选为：whitelist, blacklist
+private_list = []               # 私聊名单
+# 当private_list_type为whitelist时，只有私聊名单中的用户可以聊天
+# 当private_list_type为blacklist时，私聊名单中的任何用户无法聊天
+ban_user_id = []   # 全局禁止名单（全局禁止名单中的用户无法进行任何聊天）
+ban_qq_bot = false # 是否屏蔽QQ官方机器人
+enable_poke = true # 是否启用戳一戳功能
+
+[voice] # 发送语音设置
+use_tts = false # 是否使用tts语音（请确保你配置了tts并有对应的adapter）
+
+[debug]
+level = "INFO" # 日志等级（DEBUG, INFO, WARNING, ERROR, CRITICAL）

PRIVACY.md

@@ -0,0 +1,28 @@
+### MaiBot用户隐私条款
+**版本：V1.1**  
+**更新日期：2025年7月10日**  
+**生效日期：2025年3月18日**  
+**适用的MaiBot版本号：所有版本**  
+
+**2025© MaiBot项目团队**
+
+MaiBot项目团队（以下简称项目团队）**尊重并保护**用户（以下简称您）的隐私。若您选择使用MaiBot项目（以下简称本项目），则您需同意本项目按照以下隐私条款处理您的输入和输出内容：
+
+**1.1** 本项目**会**收集您的输入和输出内容并发送到第三方API，用于生成新的输出内容。因此您的输入和输出内容**会**同时受到本项目和第三方API的隐私政策约束。
+
+**1.2** 本项目**会**收集您的输入和输出内容，用于构建本项目专用的仅存储在您使用的数据库中的知识库和记忆库，以提高回复的准确性和连贯性。
+
+**1.3** 本项目**会**收集您的输入和输出内容，用于生成仅存储于您部署或使用的设备中的不会上传至互联网的日志。但当您向项目团队反馈问题时，项目团队可能需要您提供日志文件以帮助解决问题。
+
+**1.4** 本项目可能**会**收集部分统计信息（如使用频率、基础指令类型）以改进服务，您可在[bot_config.toml]中随时关闭此功能**。
+
+**1.5** 关于第三方插件的隐私处理：
+   - 本项目包含插件系统，允许加载第三方开发者开发的插件；
+   - **第三方插件可能会**收集、处理、存储或传输您的数据，这些行为**完全由插件开发者控制**，与项目团队无关；
+   - 项目团队**无法监控或控制**第三方插件的数据处理行为，亦**无法保证**第三方插件的隐私安全性；
+   - 第三方插件的隐私政策**由插件开发者负责制定和执行**，您应直接向插件开发者了解其隐私处理方式；
+   - 您使用第三方插件时，**需自行评估**插件的隐私风险并**自行承担**相关后果；
+
+**1.6** 由于您的自身行为或不可抗力等情形，导致上述可能涉及您隐私或您认为是私人信息的内容发生被泄露、批漏，或被第三方获取、使用、转让等情形的，均由您**自行承担**不利后果，我们对此**不承担**任何责任。**特别地，因使用第三方插件而导致的任何隐私泄露或数据安全问题，项目团队概不负责。**
+
+**1.7** 项目团队保留在未来更新隐私条款的权利，但没有义务通知您。若您不同意更新后的隐私条款，您应立即停止使用本项目。

README.md

@@ -0,0 +1,135 @@
+<img src="depends-data/maimai.png" alt="MaiBot" title="作者:略nd" width="300">
+
+# 麦麦！MaiCore-MaiBot
+
+![Python Version](https://img.shields.io/badge/Python-3.10+-blue)
+![License](https://img.shields.io/github/license/SengokuCola/MaiMBot?label=协议)
+![Status](https://img.shields.io/badge/状态-开发中-yellow)
+![Contributors](https://img.shields.io/github/contributors/MaiM-with-u/MaiBot.svg?style=flat&label=贡献者)
+![forks](https://img.shields.io/github/forks/MaiM-with-u/MaiBot.svg?style=flat&label=分支数)
+![stars](https://img.shields.io/github/stars/MaiM-with-u/MaiBot?style=flat&label=星标数)
+![issues](https://img.shields.io/github/issues/MaiM-with-u/MaiBot)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/DrSmoothl/MaiBot)
+
+<div style="text-align: center">
+<strong>
+<a href="https://www.bilibili.com/video/BV1amAneGE3P">🌟 演示视频</a> | 
+<a href="#-更新和安装">🚀 快速入门</a> | 
+<a href="#-文档">📃 教程</a> | 
+<a href="#-讨论">💬 讨论</a> | 
+<a href="#-贡献和致谢">🙋 贡献指南</a>
+</strong>
+</div>
+
+## 🎉 介绍
+
+**🍔MaiCore 是一个基于大语言模型的可交互智能体**
+
+- 💭 **智能对话系统**：基于 LLM 的自然语言交互，支持normal和focus统一化处理。
+- 🔌 **强大插件系统**：全面重构的插件架构，支持完整的管理API和权限控制。
+- 🤔 **实时思维系统**：模拟人类思考过程。
+- 🧠 **表达学习功能**：学习群友的说话风格和表达方式
+- 💝 **情感表达系统**：情绪系统和表情包系统。
+- 🧠 **持久记忆系统**：基于图的长期记忆存储。
+- 🔄 **动态人格系统**：自适应的性格特征和表达方式。
+
+<div style="text-align: center">
+<a href="https://www.bilibili.com/video/BV1amAneGE3P" target="_blank">
+    <picture>
+      <source media="(max-width: 600px)" srcset="depends-data/video.png" width="100%">
+      <img src="depends-data/video.png" width="30%" alt="麦麦演示视频">
+    </picture>
+    <br />
+  👆 点击观看麦麦演示视频 👆
+</a>
+</div>
+
+## 🔥 更新和安装
+
+**最新版本: v0.9.1** ([更新日志](changelogs/changelog.md))
+
+可前往 [Release](https://github.com/MaiM-with-u/MaiBot/releases/) 页面下载最新版本
+可前往 [启动器发布页面](https://github.com/MaiM-with-u/mailauncher/releases/)下载最新启动器
+**GitHub 分支说明：**
+- `main`: 稳定发布版本(推荐)
+- `dev`: 开发测试版本(不稳定)
+- `classical`: 旧版本(停止维护)
+
+### 最新版本部署教程
+- [从0.6/0.7升级须知](https://docs.mai-mai.org/faq/maibot/update_to_07.html)
+- [🚀 最新版本部署教程](https://docs.mai-mai.org/manual/deployment/mmc_deploy_windows.html) - 基于 MaiCore 的新版本部署方式(与旧版本不兼容)
+
+> [!WARNING]
+> - 从 0.6.x 旧版本升级前请务必阅读：[升级指南](https://docs.mai-mai.org/faq/maibot/update_to_07.html)
+> - 项目处于活跃开发阶段，功能和 API 可能随时调整。
+> - 文档未完善，有问题可以提交 Issue 或者 Discussion。
+> - QQ 机器人存在被限制风险，请自行了解，谨慎使用。
+> - 由于持续迭代，可能存在一些已知或未知的 bug。
+> - 由于程序处于开发中，可能消耗较多 token。
+
+## 💬 讨论
+
+**技术交流群：**
+- [一群](https://qm.qq.com/q/VQ3XZrWgMs) | 
+  [二群](https://qm.qq.com/q/RzmCiRtHEW) | 
+  [三群](https://qm.qq.com/q/wlH5eT8OmQ) |
+  [四群](https://qm.qq.com/q/wGePTl1UyY)
+
+**聊天吹水群：**
+- [五群](https://qm.qq.com/q/JxvHZnxyec)
+
+**插件开发测试版群：**
+- [插件开发群](https://qm.qq.com/q/1036092828)
+
+## 📚 文档
+
+**部分内容可能更新不够及时，请注意版本对应**
+
+- [📚 核心 Wiki 文档](https://docs.mai-mai.org) - 项目最全面的文档中心，你可以了解麦麦有关的一切。
+
+### 设计理念(原始时代的火花)
+
+> **千石可乐说：**
+> - 这个项目最初只是为了给牛牛 bot 添加一点额外的功能，但是功能越写越多，最后决定重写。其目的是为了创造一个活跃在 QQ 群聊的"生命体"。目的并不是为了写一个功能齐全的机器人，而是一个尽可能让人感知到真实的类人存在。
+> - 程序的功能设计理念基于一个核心的原则："最像而不是好"。
+> - 如果人类真的需要一个 AI 来陪伴自己，并不是所有人都需要一个完美的，能解决所有问题的"helpful assistant"，而是一个会犯错的，拥有自己感知和想法的"生命形式"。
+> - 代码会保持开源和开放，但个人希望 MaiMbot 的运行时数据保持封闭，尽量避免以显式命令来对其进行控制和调试。我认为一个你无法完全掌控的个体才更能让你感觉到它的自主性，而视其成为一个对话机器。
+> - SengokuCola~~纯编程外行，面向 cursor 编程，很多代码写得不好多多包涵~~已得到大脑升级。
+
+## 🙋 贡献和致谢
+你可以阅读[开发文档](https://docs.mai-mai.org/develop/)来更好的了解麦麦!  
+MaiCore 是一个开源项目，我们非常欢迎你的参与。你的贡献，无论是提交 bug 报告、功能需求还是代码 pr，都对项目非常宝贵。我们非常感谢你的支持！🎉  
+但无序的讨论会降低沟通效率，进而影响问题的解决速度，因此在提交任何贡献前，请务必先阅读本项目的[贡献指南](docs/CONTRIBUTE.md)。(待补完)  
+
+### 贡献者
+
+感谢各位大佬！  
+
+<a href="https://github.com/MaiM-with-u/MaiBot/graphs/contributors">
+  <img alt="contributors" src="https://contrib.rocks/image?repo=MaiM-with-u/MaiBot" />
+</a>
+
+### 致谢
+
+- [略nd](https://space.bilibili.com/1344099355): 为麦麦绘制人设。
+- [NapCat](https://github.com/NapNeko/NapCatQQ): 现代化的基于 NTQQ 的 Bot 协议端实现。
+
+**也感谢每一位给麦麦发展提出宝贵意见与建议的用户，感谢陪伴麦麦走到现在的你们！**
+
+## 📌 注意事项
+
+> [!WARNING]
+> 使用本项目前必须阅读和同意[用户协议](EULA.md)和[隐私协议](PRIVACY.md)。  
+> 本应用生成内容来自人工智能模型，由 AI 生成，请仔细甄别，请勿用于违反法律的用途，AI 生成内容不代表本项目团队的观点和立场。
+
+## 麦麦仓库状态
+
+![Alt](https://repobeats.axiom.co/api/embed/9faca9fccfc467931b87dd357b60c6362b5cfae0.svg "麦麦仓库状态")
+
+### Star 趋势
+
+[![Star 趋势](https://starchart.cc/MaiM-with-u/MaiBot.svg?variant=adaptive)](https://starchart.cc/MaiM-with-u/MaiBot)
+
+## License
+
+GPL-3.0

bot.py

@@ -0,0 +1,253 @@
+import asyncio
+import hashlib
+import os
+from dotenv import load_dotenv
+
+if os.path.exists(".env"):
+    load_dotenv(".env", override=True)
+    print("成功加载环境变量配置")
+else:
+    print("未找到.env文件，请确保程序所需的环境变量被正确设置")
+    raise FileNotFoundError(".env 文件不存在，请创建并配置所需的环境变量")
+import sys
+import time
+import platform
+import traceback
+from pathlib import Path
+from rich.traceback import install
+
+# maim_message imports for console input
+
+# 最早期初始化日志系统，确保所有后续模块都使用正确的日志格式
+from src.common.logger import initialize_logging, get_logger, shutdown_logging
+initialize_logging()
+
+from src.main import MainSystem #noqa
+from src.manager.async_task_manager import async_task_manager #noqa
+
+
+
+logger = get_logger("main")
+
+
+install(extra_lines=3)
+
+# 设置工作目录为脚本所在目录
+script_dir = os.path.dirname(os.path.abspath(__file__))
+os.chdir(script_dir)
+logger.info(f"已设置工作目录为: {script_dir}")
+
+
+confirm_logger = get_logger("confirm")
+# 获取没有加载env时的环境变量
+env_mask = {key: os.getenv(key) for key in os.environ}
+
+uvicorn_server = None
+driver = None
+app = None
+loop = None
+
+
+async def request_shutdown() -> bool:
+    """请求关闭程序"""
+    try:
+        if loop and not loop.is_closed():
+            try:
+                loop.run_until_complete(graceful_shutdown())
+            except Exception as ge:  # 捕捉优雅关闭时可能发生的错误
+                logger.error(f"优雅关闭时发生错误: {ge}")
+                return False
+        return True
+    except Exception as e:
+        logger.error(f"请求关闭程序时发生错误: {e}")
+        return False
+
+
+def easter_egg():
+    # 彩蛋
+    from colorama import init, Fore
+
+    init()
+    text = "多年以后，面对AI行刑队，张三将会回想起他2023年在会议上讨论人工智能的那个下午"
+    rainbow_colors = [Fore.RED, Fore.YELLOW, Fore.GREEN, Fore.CYAN, Fore.BLUE, Fore.MAGENTA]
+    rainbow_text = ""
+    for i, char in enumerate(text):
+        rainbow_text += rainbow_colors[i % len(rainbow_colors)] + char
+    print(rainbow_text)
+
+
+
+async def graceful_shutdown():
+    try:
+        logger.info("正在优雅关闭麦麦...")
+
+        # 停止所有异步任务
+        await async_task_manager.stop_and_wait_all_tasks()
+
+        # 获取所有剩余任务，排除当前任务
+        remaining_tasks = [t for t in asyncio.all_tasks() if t is not asyncio.current_task()]
+
+        if remaining_tasks:
+            logger.info(f"正在取消 {len(remaining_tasks)} 个剩余任务...")
+
+            # 取消所有剩余任务
+            for task in remaining_tasks:
+                if not task.done():
+                    task.cancel()
+
+            # 等待所有任务完成，设置超时
+            try:
+                await asyncio.wait_for(asyncio.gather(*remaining_tasks, return_exceptions=True), timeout=15.0)
+                logger.info("所有剩余任务已成功取消")
+            except asyncio.TimeoutError:
+                logger.warning("等待任务取消超时，强制继续关闭")
+            except Exception as e:
+                logger.error(f"等待任务取消时发生异常: {e}")
+
+        logger.info("麦麦优雅关闭完成")
+
+        # 关闭日志系统，释放文件句柄
+        shutdown_logging()
+
+    except Exception as e:
+        logger.error(f"麦麦关闭失败: {e}", exc_info=True)
+
+
+def _calculate_file_hash(file_path: Path, file_type: str) -> str:
+    """计算文件的MD5哈希值"""
+    if not file_path.exists():
+        logger.error(f"{file_type} 文件不存在")
+        raise FileNotFoundError(f"{file_type} 文件不存在")
+
+    with open(file_path, "r", encoding="utf-8") as f:
+        content = f.read()
+    return hashlib.md5(content.encode("utf-8")).hexdigest()
+
+
+def _check_agreement_status(file_hash: str, confirm_file: Path, env_var: str) -> tuple[bool, bool]:
+    """检查协议确认状态
+
+    Returns:
+        tuple[bool, bool]: (已确认, 未更新)
+    """
+    # 检查环境变量确认
+    if file_hash == os.getenv(env_var):
+        return True, False
+
+    # 检查确认文件
+    if confirm_file.exists():
+        with open(confirm_file, "r", encoding="utf-8") as f:
+            confirmed_content = f.read()
+        if file_hash == confirmed_content:
+            return True, False
+
+    return False, True
+
+
+def _prompt_user_confirmation(eula_hash: str, privacy_hash: str) -> None:
+    """提示用户确认协议"""
+    confirm_logger.critical("EULA或隐私条款内容已更新，请在阅读后重新确认，继续运行视为同意更新后的以上两款协议")
+    confirm_logger.critical(
+        f'输入"同意"或"confirmed"或设置环境变量"EULA_AGREE={eula_hash}"和"PRIVACY_AGREE={privacy_hash}"继续运行'
+    )
+
+    while True:
+        user_input = input().strip().lower()
+        if user_input in ["同意", "confirmed"]:
+            return
+        confirm_logger.critical('请输入"同意"或"confirmed"以继续运行')
+
+
+def _save_confirmations(eula_updated: bool, privacy_updated: bool, eula_hash: str, privacy_hash: str) -> None:
+    """保存用户确认结果"""
+    if eula_updated:
+        logger.info(f"更新EULA确认文件{eula_hash}")
+        Path("eula.confirmed").write_text(eula_hash, encoding="utf-8")
+
+    if privacy_updated:
+        logger.info(f"更新隐私条款确认文件{privacy_hash}")
+        Path("privacy.confirmed").write_text(privacy_hash, encoding="utf-8")
+
+
+def check_eula():
+    """检查EULA和隐私条款确认状态"""
+    # 计算文件哈希值
+    eula_hash = _calculate_file_hash(Path("EULA.md"), "EULA.md")
+    privacy_hash = _calculate_file_hash(Path("PRIVACY.md"), "PRIVACY.md")
+
+    # 检查确认状态
+    eula_confirmed, eula_updated = _check_agreement_status(eula_hash, Path("eula.confirmed"), "EULA_AGREE")
+    privacy_confirmed, privacy_updated = _check_agreement_status(
+        privacy_hash, Path("privacy.confirmed"), "PRIVACY_AGREE"
+    )
+
+    # 早期返回：如果都已确认且未更新
+    if eula_confirmed and privacy_confirmed:
+        return
+
+    # 如果有更新，需要重新确认
+    if eula_updated or privacy_updated:
+        _prompt_user_confirmation(eula_hash, privacy_hash)
+        _save_confirmations(eula_updated, privacy_updated, eula_hash, privacy_hash)
+
+
+def raw_main():
+    # 利用 TZ 环境变量设定程序工作的时区
+    if platform.system().lower() != "windows":
+        time.tzset()  # type: ignore
+
+    check_eula()
+    logger.info("检查EULA和隐私条款完成")
+
+    easter_egg()
+
+    # 返回MainSystem实例
+    return MainSystem()
+
+
+if __name__ == "__main__":
+    exit_code = 0  # 用于记录程序最终的退出状态
+    try:
+        # 获取MainSystem实例
+        main_system = raw_main()
+
+        # 创建事件循环
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+
+        try:
+            # 执行初始化和任务调度
+            loop.run_until_complete(main_system.initialize())
+            # Schedule tasks returns a future that runs forever.
+            # We can run console_input_loop concurrently.
+            main_tasks = loop.create_task(main_system.schedule_tasks())
+            loop.run_until_complete(main_tasks)
+
+        except KeyboardInterrupt:
+            # loop.run_until_complete(get_global_api().stop())
+            logger.warning("收到中断信号，正在优雅关闭...")
+            if loop and not loop.is_closed():
+                try:
+                    loop.run_until_complete(graceful_shutdown())
+                except Exception as ge:  # 捕捉优雅关闭时可能发生的错误
+                    logger.error(f"优雅关闭时发生错误: {ge}")
+        # 新增：检测外部请求关闭
+
+    except Exception as e:
+        logger.error(f"主程序发生异常: {str(e)} {str(traceback.format_exc())}")
+        exit_code = 1  # 标记发生错误
+    finally:
+        # 确保 loop 在任何情况下都尝试关闭（如果存在且未关闭）
+        if "loop" in locals() and loop and not loop.is_closed():
+            loop.close()
+            logger.info("事件循环已关闭")
+
+        # 关闭日志系统，释放文件句柄
+        try:
+            shutdown_logging()
+        except Exception as e:
+            print(f"关闭日志系统时出错: {e}")
+
+        # 在程序退出前暂停，让你有机会看到输出
+        # input("按 Enter 键退出...")  # <--- 添加这行
+        sys.exit(exit_code)  # <--- 使用记录的退出码

changelogs/changelog.md

@@ -0,0 +1,736 @@
+# Changelog
+
+## [0.10.0] - 2025-7-1
+### 主要功能更改
+- 工具系统重构，现在合并到了插件系统中
+- 彻底重构了整个LLM Request了，现在支持模型轮询和更多灵活的参数
+  - 同时重构了整个模型配置系统，升级需要重新配置llm配置文件
+- 随着LLM Request的重构，插件系统彻底重构完成。插件系统进入稳定状态，仅增加新的API
+  - 具体相比于之前的更改可以查看[changes.md](./changes.md)
+
+### 细节优化
+- 修复了lint爆炸的问题，代码更加规范了
+- 修改了log的颜色，更加护眼
+
+## [0.9.1] - 2025-7-26
+
+### 主要修复和优化
+
+- 优化回复意愿
+- 优化专注模式回复频率
+- 优化关键词提取
+- 修复部分模型产生的400问题
+
+### 细节优化
+
+- 修复reply导致的planner异常空跳
+- 修复表达方式迁移空目录问题
+- 修复reply_to空字段问题
+- 无可用动作导致的空plan问题
+- 修复人格未压缩导致产生句号分割
+- 将metioned bot 和 at应用到focus prompt中
+- 更好的兴趣度计算
+- 修复部分模型由于enable_thinking导致的400问题
+- 移除dependency_manager
+
+
+## [0.9.0] - 2025-7-24
+
+### 摘要
+MaiBot 0.9.0 重磅升级！本版本带来两大核心突破：**全面重构的插件系统**提供更强大的扩展能力和管理功能；**normal和focus模式统一化处理**大幅简化架构并提升性能。同时新增s4u prompt模式优化、语音消息支持、全新情绪系统和mais4u直播互动功能，为MaiBot带来更自然、更智能的交互体验！
+
+### 🌟 主要功能概览
+
+#### 🔌 插件系统全面重构 - 重点升级
+- **完整管理API**: 全新的插件管理API，支持插件的启用、禁用、重载和卸载操作
+- **权限控制系统**: 为插件管理增加完善的权限控制，确保系统安全性
+- **智能依赖管理**: 优化插件依赖管理和自动注册机制，减少配置复杂度
+
+#### ⚡ Normal和Focus模式统一化处理 - 重点升级
+- **架构统一**: 彻底统一normal和focus聊天模式，消除模式间的差异和复杂性
+- **智能模式切换**: 优化频率控制和模式切换逻辑，normal可以无缝切换到focus
+- **统一LLM激活**: normal模式现在支持LLM激活插件，与focus模式功能对等
+- **一致的关系构建**: normal采用与focus一致的关系构建机制，提升交互质量
+- **统一退出机制**: 为focus提供更合理的退出方法，简化状态管理
+
+#### 🎯 s4u prompt模式
+- **s4u prompt模式**: 新增专门的s4u prompt构建方式，提供更好的交互效果
+- **配置化启用**: 可在配置文件中选择启用s4u prompt模式，灵活控制
+- **兼容性保持**: 与现有系统完全兼容，可随时切换启用或禁用
+
+#### 🎤 语音消息支持
+- **Voice消息处理**: 新增对voice类型消息的支持，麦麦现在可以识别和处理语音消息（需要模型配置）
+
+#### 全新情绪系统
+- **持续情绪**: 麦麦现在拥有持续的情绪状态，情绪会影响回复风格和行为
+
+
+### 💻 更新预览
+
+#### 关系系统优化
+- **prompt优化**: 优化关系prompt和person_info信息展示
+- **构建间隔**: 让关系构建间隔可配置，提升灵活性
+- **关系配置**: 优化关系配置，采用和focus一致的关系构建
+
+#### 表情包系统升级
+- **识别增强**: 加强emoji的识别能力，优化emoji显示
+- **匹配精准**: 更精准的表情包匹配算法
+
+#### 完善mais4u系统（需要amaidesu支持）
+- **直播互动**: 新增mais4u直播功能，支持实时互动和思考状态展示
+- **动作控制**: 支持眨眼、微动作、注视等多种动作适配
+
+#### 日志系统优化
+- **显示优化**: 优化Logger前缀映射、颜色格式和计时信息显示
+- **级别优化**: 优化日志级别和信息过滤，提升调试体验
+- **日志查看器**: 升级logger_viewer，移除无用脚本
+
+#### 配置系统改进
+- **配置简化**: 简化配置文件，让配置更加精简易懂
+- **prompt显示**: 可选打开prompt显示功能
+- **配置更新**: 更好的配置文件更新机制和更新内容显示
+
+#### 问题修复与优化
+
+- 修复normal planner没有超时退出问题，添加回复超时检查
+- 重构no_reply逻辑，不再使用小模型，采用激活度决定
+- 修复图片与文字混合兴趣值为0的情况
+- 适配无兴趣度消息处理
+- 优化Docker镜像构建流程，合并AMD64和ARM64构建步骤
+- 移除vtb插件和take_picture_plugin，功能已由其他系统接管,移除pfc遗留代码和其他过时功能
+- 移除observation和processor等冗余组件，大幅简化focus代码逻辑
+- 修复了LPMM的学习问题
+
+
+## [0.8.1] - 2025-7-5
+
+功能更新:
+
+- normal现在和focus一样支持tool
+- focus现在和normal一样每次调用lpmm
+- 移除人格表达
+
+优化和修复：
+
+- 修复表情包配置无效问题
+- 合并normal和focus的prompt构建
+- 非TTY环境禁用console_input_loop
+- 修复过滤消息仍被存储至数据库的问题
+- 私聊强制开启focus模式
+- 支持解析reply_to和at
+- 修复focus冷却时间导致的固定沉默
+- 移除豆包画图插件，此插件现在插件广场提供
+- 修复表达器无法读取原始文本
+- 修复normal planner没有超时退出问题
+
+## [0.8.0] - 2025-6-27
+
+MaiBot 0.8.0 现已推出！
+
+### **主要升级点：**
+
+1.插件系统正式加入，现已上线插件商店，同时支持normal和focus
+2.大幅降低了token消耗，更省钱
+3.加入人物印象系统，麦麦可以对群友有不同的印象
+4.可以精细化控制不同时段和不同群聊的发言频率
+
+#### 其他升级
+
+日志系统重构使用structlog
+大量稳定性修复和性能优化。
+MMC启动速度加快
+
+### 🔌 插系统正式推出
+**全面重构的插件生态系统，支持强大 的扩展能力**
+
+- **插件API重构**: 全面重构插件系统，统一加载机制，区分内部插件和外部插件
+- **插件仓库**：现可以分享和下载插件
+- **依赖管理**: 新增插件依赖管理系统，支持自动注册和依赖检查
+- **命令支持**: 插件现已支持命令(command)功能，提供更丰富的交互方式
+- **示例插件升级**: 更新禁言插件、豆包绘图插件、TTS插件等示例插件
+- **配置文件管理**: 插件支持自动生成和管理配置文件，支持版本自动更新
+- **文档完善**: 补全插件API文档，提供详细的开发指南
+
+### 👥 人物印象系统
+**麦麦现在能认得群友，记住每个人的特点**
+- **人物侧写功能**: 加入了人物侧写！麦麦现在能认得群友，新增用户侧写功能，将印象拆分为多方面特点
+
+### ⚡ Focus模式大幅优化 - 降低Token消耗与提升速度
+- **Planner架构更新**: 更新planner架构，大大加快速度和表现效果！
+- **处理器重构**: 
+  - 移除冗余处理器
+  - 精简处理器上下文，减少不必要的处理
+  - 后置工具处理器，大大减少token消耗
+- **统计系统**: 提供focus统计功能，可查看详细的no_reply统计信息
+
+
+### ⏰ 聊天频率精细控制
+**支持时段化的精细频率管理，让麦麦在合适的时间说合适的话**
+- **时段化控制**: 添加时段talk_frequency控制，支持不同时间段不同群聊的精细频率管理
+- **严格频率控制**: 实现更加严格和可靠的频率控制机制
+- **Normal模式优化**: 大幅优化normal模式的频率控制逻辑，提升回复的智能性
+
+### 🎭 表达方式系统大幅优化
+**智能学习群友聊天风格，让麦麦的表达更加多样化**
+- **智能学习机制**: 优化表达方式学习算法，支持衰减机制，太久没学的会被自动抛弃
+- **表达方式选择**: 新增表达方式选择器，让表达使用更合理
+- **跨群互通配置**: 表达方式现在可以选择在不同群互通或独立
+- **可视化工具**: 提供表达方式可视化脚本和检查脚本
+
+### 💾 记忆系统改进
+**更快的记忆处理和更好的短期记忆管理**
+- **海马体优化**: 大大优化海马体同步速度，提升记忆处理效率
+- **工作记忆升级**: 精简升级工作记忆模块，提供更好的短期记忆管理
+- **聊天记录构建**: 优化聊天记录构建方式，提升记忆提取效率
+
+### 📊 日志系统重构
+**使用structlog提供更好的结构化日志**
+- **structlog替换**: 使用structlog替代loguru，提供更好的结构化日志
+- **日志查看器**: 新增日志查看脚本，支持更好的日志浏览
+- **可配置日志**: 提供可配置的日志级别和格式，支持不同环境的需求
+
+### 🎯 其他改进
+- **emoji系统**: 移除emoji默认发送模式，优化表情包审查功能
+- **控制台发送**: 添加不完善的控制台发送功能
+- **行为准则**: 添加贡献者契约行为准则
+- **图像清理**: 自动清理images文件夹，优化存储空间使用
+
+
+
+
+## [0.7.0] -2025-6-1
+- 你可以选择normal,focus和auto多种不同的聊天方式。normal提供更少的消耗，更快的回复速度。focus提供更好的聊天理解，更多工具使用和插件能力
+- 现在，你可以自定义麦麦的表达方式，并且麦麦也可以学习群友的聊天风格（需要在配置文件中打开）
+- 不再需要繁琐的安装MongoDB！弃用MongoDB，采用轻量sqlite,无需额外安装（提供数据迁移脚本）
+- focus模式初步支持了插件，我们提供了两个示例插件（需要手动启用），可以让麦麦实现更丰富的操作。禁言插件和豆包绘图插件是示例用插件。
+
+**重构专注聊天(HFC - focus_chat)**
+- 模块化设计，可以自定义不同的部件
+   - 观察器（获取信息）
+   - 信息处理器（处理信息）
+      - 重构：聊天思考（子心流）处理器
+      - 重构：聊天处理器
+      - 重构：聊天元信息处理器
+      - 重构：工具处理器
+      - 新增：工作记忆处理器
+      - 新增：自我认知处理器
+      - 新增：动作处理器
+   - 决策器（选择动作）
+   - 执行器（执行动作）
+      - 回复动作
+      - 不回复动作
+      - 退出HFC动作
+      - 插件：禁言动作
+   - 表达器：装饰语言风格
+- 可通过插件添加和自定义HFC部件（目前只支持action定义）
+- 为专注模式添加关系线索
+- 在专注模式下，麦麦可以决定自行发送语音消息（需要搭配tts适配器）
+- 优化reply，减少复读
+- 可自定义连续回复次数
+- 可自定义处理器超时时间
+
+**优化普通聊天(normal_chat)**
+- 添加可学习的表达方式
+- 增加了talk_frequency参数来有效控制回复频率
+- 优化了进入和离开normal_chat的方式
+- 添加时间信息
+
+**新增表达方式学习**
+- 麦麦配置单独表达方式
+- 自主学习群聊中的表达方式，更贴近群友
+- 可自定义的学习频率和开关
+- 根据人设生成额外的表达方式
+
+**聊天管理**
+- 移除不在线状态
+- 优化自动模式下normal与focus聊天的切换机制
+- 大幅精简聊天状态切换规则，减少复杂度
+- 移除聊天限额数量
+
+**插件系统**
+- 示例插件：禁言插件
+- 示例插件：豆包绘图插件
+
+**人格**
+- 简化了人格身份的配置
+- 优化了在focus模式下人格的表现和稳定性
+
+**数据库重构**
+- 移除了默认使用MongoDB，采用轻量sqlite
+- 无需额外安装数据库
+- 提供迁移脚本
+
+**优化**
+- 移除日程系统，减少幻觉（将会在未来版本回归）
+- 移除主心流思考和LLM进入聊天判定
+- 支持qwen3模型，支持自定义是否思考和思考长度
+- 优化提及和at的判定
+- 添加配置项
+- 添加临时配置文件读取器
+
+
+## [0.6.3-fix-4] - 2025-5-18
+- 0.6.3 的最后一个修复版
+
+### fix1-fix4修复日志
+**聊天状态**
+   - 大幅精简聊天状态切换，提高麦麦说话能力
+   - 移除OFFLINE和ABSENT状态
+   - 移除聊天数量限制
+   - 聊天默认normal_chat
+   - 默认关闭focus_chat
+
+**知识库LPMM**
+   - 增加嵌入模型一致性校验功能
+   - 强化数据导入处理，增加非法文段检测功能
+   - 修正知识获取逻辑，调整相关性输出顺序
+   - 添加数据导入的用户确认删除功能
+
+**专注模式**
+   - 默认提取记忆，优化记忆表现
+   - 添加心流查重
+   - 为复读增加硬限制
+   - 支持获取子心流循环信息和状态的API接口
+   - 优化工具调用的信息获取与缓存
+
+**表情包系统**
+   - 优化表情包识别和处理
+   - 提升表情匹配逻辑
+
+**日志系统**
+   - 优化日志样式配置
+   - 添加丰富的追踪信息以增强调试能力
+
+**API**
+   - 添加GraphQL路由支持
+   - 新增强制停止MAI Bot的API接口
+
+
+## [0.6.3] - 2025-4-15
+
+### 摘要
+- MaiBot 0.6.3 版本发布！核心重构回复逻辑，统一为心流系统管理，智能切换交互模式。
+- 引入全新的 LPMM 知识库系统，大幅提升信息获取能力。
+- 新增昵称系统，改善群聊中的身份识别。
+- 提供独立的桌宠适配器连接程序。
+- 优化日志输出，修复若干问题。
+
+### 🌟 核心功能增强
+#### 统一回复逻辑 (Unified Reply Logic)
+- **核心重构**: 移除了经典 (Reasoning) 与心流 (Heart Flow) 模式的区分，将回复逻辑完全整合到 `SubHeartflow` 中进行统一管理，由主心流统一调控。保留 Heart FC 模式的特色功能。
+- **智能交互模式**: `SubHeartflow` 现在可以根据情境智能选择不同的交互模式：
+    - **普通聊天 (Normal Chat)**: 类似于之前的 Reasoning 模式，进行常规回复（激活逻辑暂未改变）。
+    - **心流聊天 (Heart Flow Chat)**: 基于改进的 PFC 模式，能更好地理解上下文，减少重复和认错人的情况，并支持**工具调用**以获取额外信息。
+    - **离线模式 (Offline/Absent)**: 在特定情况下，麦麦可能会选择暂时不查看或回复群聊消息。
+- **状态管理**: 交互模式的切换由 `SubHeartflow` 内部逻辑和 `SubHeartflowManager` 根据整体状态 (`MaiState`) 和配置进行管理。
+- **流程优化**: 拆分了子心流的思考模块，使整体对话流程更加清晰。
+- **状态判断改进**: 将 CHAT 状态判断交给 LLM 处理，使对话更自然。
+- **回复机制**: 实现更为灵活的概率回复机制，使机器人能够自然地融入群聊环境。
+- **重复性检查**: 加入心流回复重复性检查机制，防止麦麦陷入固定回复模式。
+
+#### 全新知识库系统 (New Knowledge Base System - LPMM)
+- **引入 LPMM**: 新增了 **LPMM (Large Psychology Model Maker)** 知识库系统，具有强大的信息检索能力，能显著提升麦麦获取和利用知识的效率。
+- **功能集成**: 集成了 LPMM 知识库查询功能，进一步扩展信息检索能力。
+- **推荐使用**: 强烈建议使用新的 LPMM 系统以获得最佳体验。旧的知识库系统仍然可用作为备选。
+
+#### 昵称系统 (Nickname System)
+- **自动取名**: 麦麦现在会尝试给群友取昵称，减少对易变的群昵称的依赖，从而降低认错人的概率。
+- **持续完善**: 该系统目前仍处于早期阶段，会持续进行优化。
+
+#### 记忆与上下文增强 (Memory and Context Enhancement)
+- **聊天记录压缩**: 大幅优化聊天记录压缩系统，使机器人能够处理5倍于之前的上下文记忆量。
+- **长消息截断**: 新增了长消息自动截断与模糊化功能，随着时间推移降低超长消息的权重，避免被特定冗余信息干扰。
+- **记忆提取**: 优化记忆提取功能，提高对历史对话的理解和引用能力。
+- **记忆整合**: 为记忆系统加入了合并与整合机制，优化长期记忆的结构与效率。
+- **中期记忆调用**: 完善中期记忆调用机制，使机器人能够更自然地回忆和引用较早前的对话。
+- **Prompt 优化**: 进一步优化了关系系统和记忆系统相关的提示词（prompt）。
+
+#### 私聊 PFC 功能增强 (Private Chat PFC Enhancement)
+- **功能修复与优化**: 修复了私聊 PFC 载入聊天记录缺失的 bug，优化了 prompt 构建，增加了审核机制，调整了重试次数，并将机器人发言存入数据库。
+- **实验性质**: 请注意，PFC 仍然是一个实验性功能，可能在未来版本中被修改或移除，目前不接受相关 Bug 反馈。
+
+#### 情感与互动增强 (Emotion and Interaction Enhancement)
+- **全新表情包系统**: 新的表情包系统上线，表情含义更丰富，发送更快速。
+- **表情包使用优化**: 优化了表情包的选择逻辑，减少重复使用特定表情包的情况，使表达更生动。
+- **提示词优化**: 优化提示词（prompt）构建，增强对话质量和情感表达。
+- **积极性配置**: 优化"让麦麦更愿意说话"的相关配置，使机器人更积极参与对话。
+- **颜文字保护**: 保护颜文字处理机制，确保表情正确显示。
+
+#### 工具与集成 (Tools and Integration)
+- **动态更新**: 使用工具调用来更新关系和心情，取代原先的固定更新机制。
+- **智能调用**: 工具调用时会考虑上下文，使调用更加智能。
+- **知识库依赖**: 添加 LPMM 知识库依赖，扩展知识检索工具。
+
+### 💻 系统架构优化
+#### 日志优化 (Logging Optimization)
+- **输出更清晰**: 优化了日志信息的格式和内容，使其更易于阅读和理解。
+
+#### 模型与消息整合 (Model and Message Integration)
+- **模型合并**: 合并工具调用模型和心流模型，提高整体一致性。
+- **消息规范**: 全面改用 `maim_message`，移除对 `rest` 的支持。
+
+#### (临时) 简易 GUI (Temporary Simple GUI)
+- **运行状态查看**: 提供了一个非常基础的图形用户界面，用于查看麦麦的运行状态。
+- **临时方案**: 这是一个临时性的解决方案，功能简陋，**将在 0.6.4 版本中被全新的 Web UI 所取代**。此 GUI 不会包含在主程序包中，而是通过一键包提供，并且不接受 Bug 反馈。
+
+### 🐛 问题修复
+- **记忆检索优化**: 提高了记忆检索的准确性和效率。
+- 修复了一些其他小问题。
+
+### 🔧 其他改进
+#### 桌宠适配器 (Bug Catcher Adapter)
+- **独立适配器**: 提供了一个"桌宠"独立适配器，用于连接麦麦和桌宠。
+- **获取方式**: 可在 MaiBot 的 GitHub 组织中找到该适配器，不包含在主程序内。
+
+#### 一键包内容 (One-Click Package Contents)
+- **辅助程序**: 一键包中包含了简易 GUI 和 **麦麦帮助配置** 等辅助程序，后者可在配置出现问题时提供帮助。
+
+## [0.6.2] - 2025-4-14
+
+### 摘要
+- MaiBot 0.6.2 版本发布！
+- 优化了心流的观察系统，优化提示词和表现，现在心流表现更好！
+- 新增工具调用能力，可以更好地获取信息
+- 本次更新主要围绕工具系统、心流系统、消息处理和代码优化展开，新增多个工具类，优化了心流系统的逻辑，改进了消息处理流程，并修复了多个问题。
+
+### 🌟 核心功能增强
+#### 工具系统
+- 新增了知识获取工具系统，支持通过心流调用获取多种知识
+- 新增了工具系统使用指南，详细说明工具结构、自动注册机制和添加步骤
+- 新增了多个实用工具类，包括心情调整工具`ChangeMoodTool`、关系查询工具`RelationshipTool`、数值比较工具`CompareNumbersTool`、日程获取工具`GetCurrentTaskTool`、上下文压缩工具`CompressContextTool`和知识获取工具`GetKnowledgeTool`
+- 更新了`ToolUser`类，支持自动获取已注册工具定义并调用`execute`方法
+- 需要配置支持工具调用的模型才能使用完整功能
+
+#### 心流系统
+- 新增了上下文压缩缓存功能，可以有更持久的记忆
+- 新增了心流系统的README.md文件，详细介绍了系统架构、主要功能和工作流程。
+- 优化了心流系统的逻辑，包括子心流自动清理和合理配置更新间隔。
+- 改进了心流观察系统，优化了提示词设计和系统表现，使心流运行更加稳定高效。
+- 更新了`Heartflow`类的方法和属性，支持异步生成提示词并提升生成质量。
+
+#### 消息处理
+- 改进了消息处理流程，包括回复检查、消息生成和发送逻辑。
+- 新增了`ReplyGenerator`类，用于根据观察信息和对话信息生成回复。
+- 优化了消息队列管理系统，支持按时间顺序处理消息。
+
+#### 现在可以启用更好的表情包发送系统
+
+### 💻 系统架构优化
+
+#### 部署支持
+- 更新了Docker部署文档，优化了服务配置和挂载路径。
+- 完善了Linux和Windows脚本支持。
+
+### 🐛 问题修复
+- 修复了消息处理器中的正则表达式匹配问题。
+- 修复了图像处理中的帧大小和拼接问题。
+- 修复了私聊时产生`reply`消息的bug。
+- 修复了配置文件加载时的版本兼容性问题。
+
+### 📚 文档更新
+- 更新了`README.md`文件，包括Python版本要求和协议信息。
+- 新增了工具系统和心流系统的详细文档。
+- 优化了部署相关文档的完整性。
+
+### 🔧 其他改进
+- 新增了崩溃日志记录器，记录崩溃信息到日志文件。
+- 优化了统计信息输出，在控制台显示详细统计信息。
+- 改进了异常处理机制，提升系统稳定性。
+- 现可配置部分模型的temp参数
+
+## [0.6.0] - 2025-4-4
+
+### 摘要
+- MaiBot 0.6.0 重磅升级！ 核心重构为独立智能体MaiCore，新增思维流对话系统，支持拟真思考过程。记忆与关系系统2.0让交互更自然，动态日程引擎实现智能调整。优化部署流程，修复30+稳定性问题，隐私政策同步更新，推荐所有用户升级体验全新AI交互！（V3激烈生成）
+
+### 🌟 核心功能增强
+#### 架构重构
+- 将MaiBot重构为MaiCore独立智能体
+- 移除NoneBot相关代码，改为插件方式与NoneBot对接
+
+#### 思维流系统
+- 提供两种聊天逻辑，思维流（心流）聊天（ThinkFlowChat）和推理聊天（ReasoningChat）
+- 思维流聊天能够在回复前后进行思考
+- 思维流自动启停机制，提升资源利用效率
+- 思维流与日程系统联动，实现动态日程生成
+
+#### 回复系统
+- 更改了回复引用的逻辑，从基于时间改为基于新消息
+- 提供私聊的PFC模式，可以进行有目的，自由多轮对话（实验性）
+
+#### 记忆系统优化
+- 优化记忆抽取策略
+- 优化记忆prompt结构
+- 改进海马体记忆提取机制，提升自然度
+
+#### 关系系统优化
+- 优化关系管理系统，适用于新版本
+- 改进关系值计算方式，提供更丰富的关系接口
+
+#### 表情包系统
+- 可以识别gif表情包
+- 表情包增加存储上限
+- 自动清理缓存图片
+
+## 日程系统优化
+- 日程现在动态更新
+- 日程可以自定义想象力程度
+- 日程会与聊天情况交互（思维流模式下）
+
+### 💻 系统架构优化
+#### 配置系统改进
+- 新增更多项目的配置项
+- 修复配置文件保存问题
+- 优化配置结构：
+  - 调整模型配置组织结构
+  - 优化配置项默认值
+  - 调整配置项顺序
+- 移除冗余配置
+
+#### 部署支持扩展
+- 优化Docker构建流程
+- 完善Windows脚本支持
+- 优化Linux一键安装脚本
+
+### 🐛 问题修复
+#### 功能稳定性
+- 修复表情包审查器问题
+- 修复心跳发送问题
+- 修复拍一拍消息处理异常
+- 修复日程报错问题
+- 修复文件读写编码问题
+- 修复西文字符分割问题
+- 修复自定义API提供商识别问题
+- 修复人格设置保存问题
+- 修复EULA和隐私政策编码问题
+
+### 📚 文档更新
+- 更新README.md内容
+- 优化文档结构
+- 更新EULA和隐私政策
+- 完善部署文档
+
+### 🔧 其他改进
+- 新增详细统计系统
+- 优化表情包审查功能
+- 改进消息转发处理
+- 优化代码风格和格式
+- 完善异常处理机制
+- 可以自定义时区
+- 优化日志输出格式
+- 版本硬编码，新增配置自动更新功能
+- 优化了统计信息，会在控制台显示统计信息
+
+
+## [0.5.15] - 2025-3-17
+### 🌟 核心功能增强
+#### 关系系统升级
+- 新增关系系统构建与启用功能
+- 优化关系管理系统
+- 改进prompt构建器结构
+- 新增手动修改记忆库的脚本功能
+- 增加alter支持功能
+
+#### 启动器优化
+- 新增MaiLauncher.bat 1.0版本
+- 优化Python和Git环境检测逻辑
+- 添加虚拟环境检查功能
+- 改进工具箱菜单选项
+- 新增分支重置功能
+- 添加MongoDB支持
+- 优化脚本逻辑
+- 修复虚拟环境选项闪退和conda激活问题
+- 修复环境检测菜单闪退问题
+- 修复.env文件复制路径错误
+
+#### 日志系统改进
+- 新增GUI日志查看器
+- 重构日志工厂处理机制
+- 优化日志级别配置
+- 支持环境变量配置日志级别
+- 改进控制台日志输出
+- 优化logger输出格式
+
+### 💻 系统架构优化
+#### 配置系统升级
+- 更新配置文件到0.0.10版本
+- 优化配置文件可视化编辑
+- 新增配置文件版本检测功能
+- 改进配置文件保存机制
+- 修复重复保存可能清空list内容的bug
+- 修复人格设置和其他项配置保存问题
+
+#### WebUI改进
+- 优化WebUI界面和功能
+- 支持安装后管理功能
+- 修复部分文字表述错误
+
+#### 部署支持扩展
+- 优化Docker构建流程
+- 改进MongoDB服务启动逻辑
+- 完善Windows脚本支持
+- 优化Linux一键安装脚本
+- 新增Debian 12专用运行脚本
+
+### 🐛 问题修复
+#### 功能稳定性
+- 修复bot无法识别at对象和reply对象的问题
+- 修复每次从数据库读取额外加0.5的问题
+- 修复新版本由于版本判断不能启动的问题
+- 修复配置文件更新和学习知识库的确认逻辑
+- 优化token统计功能
+- 修复EULA和隐私政策处理时的编码兼容问题
+- 修复文件读写编码问题，统一使用UTF-8
+- 修复颜文字分割问题
+- 修复willing模块cfg变量引用问题
+
+### 📚 文档更新
+- 更新CLAUDE.md为高信息密度项目文档
+- 添加mermaid系统架构图和模块依赖图
+- 添加核心文件索引和类功能表格
+- 添加消息处理流程图
+- 优化文档结构
+- 更新EULA和隐私政策文档
+
+### 🔧 其他改进
+- 更新全球在线数量展示功能
+- 优化statistics输出展示
+- 新增手动修改内存脚本（支持添加、删除和查询节点和边）
+
+### 主要改进方向
+1. 完善关系系统功能
+2. 优化启动器和部署流程
+3. 改进日志系统
+4. 提升配置系统稳定性
+5. 加强文档完整性
+
+## [0.5.14] - 2025-3-14
+### 🌟 核心功能增强
+#### 记忆系统优化
+- 修复了构建记忆时重复读取同一段消息导致token消耗暴增的问题
+- 优化了记忆相关的工具模型代码
+
+#### 消息处理升级
+- 新增了不回答已撤回消息的功能
+- 新增每小时自动删除存留超过1小时的撤回消息
+- 优化了戳一戳功能的响应机制
+- 修复了回复消息未正常发送的问题
+- 改进了图片发送错误时的处理机制
+
+#### 日程系统改进
+- 修复了长时间运行的bot在跨天后无法生成新日程的问题
+- 优化了日程文本解析功能
+- 修复了解析日程时遇到markdown代码块等额外内容的处理问题
+
+### 💻 系统架构优化
+#### 日志系统升级
+- 建立了新的日志系统
+- 改进了错误处理机制
+- 优化了代码格式化规范
+
+#### 部署支持扩展
+- 改进了NAS部署指南，增加HOST设置说明
+- 优化了部署文档的完整性
+
+### 🐛 问题修复
+#### 功能稳定性
+- 修复了utils_model.py中的潜在问题
+- 修复了set_reply相关bug
+- 修复了回应所有戳一戳的问题
+- 优化了bot被戳时的判断逻辑
+
+### 📚 文档更新
+- 更新了README.md的内容
+- 完善了NAS部署指南
+- 优化了部署相关文档
+
+### 主要改进方向
+1. 提升记忆系统的效率和稳定性
+2. 完善消息处理机制
+3. 优化日程系统功能
+4. 改进日志和错误处理
+5. 加强部署文档的完整性
+
+## [0.5.13] - 2025-3-12
+### 🌟 核心功能增强
+#### 记忆系统升级
+- 新增了记忆系统的时间戳功能，包括创建时间和最后修改时间
+- 新增了记忆图节点和边的时间追踪功能
+- 新增了自动补充缺失时间字段的功能
+- 新增了记忆遗忘机制，基于时间条件自动遗忘旧记忆
+- 优化了记忆系统的数据同步机制
+- 优化了记忆系统的数据结构，确保所有数据类型的一致性
+
+#### 私聊功能完善
+- 新增了完整的私聊功能支持，包括消息处理和回复
+- 新增了聊天流管理器，支持群聊和私聊的上下文管理
+- 新增了私聊过滤开关功能
+- 优化了关系管理系统，支持跨平台用户关系
+
+#### 消息处理升级
+- 新增了消息队列管理系统，支持按时间顺序处理消息
+- 新增了消息发送控制器，实现人性化的发送速度和间隔
+- 新增了JSON格式分享卡片读取支持
+- 新增了Base64格式表情包CQ码支持
+- 改进了消息处理流程，支持多种消息类型
+
+### 💻 系统架构优化
+#### 配置系统改进
+- 新增了配置文件自动更新和版本检测功能
+- 新增了配置文件热重载API接口
+- 新增了配置文件版本兼容性检查
+- 新增了根据不同环境(dev/prod)显示不同级别的日志功能
+- 优化了配置文件格式和结构
+
+#### 部署支持扩展
+- 新增了Linux系统部署指南
+- 新增了Docker部署支持的详细文档
+- 新增了NixOS环境支持（使用venv方式）
+- 新增了优雅的shutdown机制
+- 优化了Docker部署文档
+
+### 🛠️ 开发体验提升
+#### 工具链升级
+- 新增了ruff代码格式化和检查工具
+- 新增了知识库一键启动脚本
+- 新增了自动保存脚本，定期保存聊天记录和关系数据
+- 新增了表情包自动获取脚本
+- 优化了日志记录（使用logger.debug替代print）
+- 精简了日志输出，禁用了Uvicorn/NoneBot默认日志
+
+#### 安全性强化
+- 新增了API密钥安全管理机制
+- 新增了数据库完整性检查功能
+- 新增了表情包文件完整性自动检查
+- 新增了异常处理和自动恢复机制
+- 优化了安全性检查机制
+
+### 🐛 关键问题修复
+#### 系统稳定性
+- 修复了systemctl强制停止的问题
+- 修复了ENVIRONMENT变量在同一终端下不能被覆盖的问题
+- 修复了libc++.so依赖问题
+- 修复了数据库索引创建失败的问题
+- 修复了MongoDB连接配置相关问题
+- 修复了消息队列溢出问题
+- 修复了配置文件加载时的版本兼容性问题
+
+#### 功能完善性
+- 修复了私聊时产生reply消息的bug
+- 修复了回复消息无法识别的问题
+- 修复了CQ码解析错误
+- 修复了情绪管理器导入问题
+- 修复了小名无效的问题
+- 修复了表情包发送时的参数缺失问题
+- 修复了表情包重复注册问题
+- 修复了变量拼写错误问题
+
+### 主要改进方向
+1. 提升记忆系统的智能性和可靠性
+2. 完善私聊功能的完整生态
+3. 优化系统架构和部署便利性
+4. 提升开发体验和代码质量
+5. 加强系统安全性和稳定性
+
+
+

changelogs/changelog_config.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## [1.0.3] - 2025-3-31
+### Added
+- 新增了心流相关配置项：
+  - `heartflow` 配置项，用于控制心流功能
+
+### Removed
+- 移除了 `response` 配置项中的 `model_r1_probability` 和 `model_v3_probability` 选项
+- 移除了次级推理模型相关配置
+
+## [1.0.1] - 2025-3-30
+### Added
+- 增加了流式输出控制项 `stream`
+- 修复 `LLM_Request` 不会自动为 `payload` 增加流式输出标志的问题
+
+## [1.0.0] - 2025-3-30
+### Added
+- 修复了错误的版本命名
+- 杀掉了所有无关文件
+
+## [0.0.11] - 2025-3-12
+### Added
+- 新增了 `schedule` 配置项，用于配置日程表生成功能
+- 新增了 `response_splitter` 配置项，用于控制回复分割
+- 新增了 `experimental` 配置项，用于实验性功能开关
+- 新增了 `llm_observation` 和 `llm_sub_heartflow` 模型配置
+- 新增了 `llm_heartflow` 模型配置
+- 在 `personality` 配置项中新增了 `prompt_schedule_gen` 参数
+
+### Changed
+- 优化了模型配置的组织结构
+- 调整了部分配置项的默认值
+- 调整了配置项的顺序，将 `groups` 配置项移到了更靠前的位置
+- 在 `message` 配置项中：
+  - 新增了 `model_max_output_length` 参数
+- 在 `willing` 配置项中新增了 `emoji_response_penalty` 参数
+- 将 `personality` 配置项中的 `prompt_schedule` 重命名为 `prompt_schedule_gen`
+
+### Removed
+- 移除了 `min_text_length` 配置项
+- 移除了 `cq_code` 配置项
+- 移除了 `others` 配置项（其功能已整合到 `experimental` 中）
+
+## [0.0.5] - 2025-3-11
+### Added
+- 新增了 `alias_names` 配置项，用于指定麦麦的别名。
+
+## [0.0.4] - 2025-3-9
+### Added
+- 新增了 `memory_ban_words` 配置项，用于指定不希望记忆的词汇。

changelogs/changes.md

@@ -0,0 +1,69 @@
+# 插件API与规范修改
+
+1. 现在`plugin_system`的`__init__.py`文件中包含了所有插件API的导入，用户可以直接使用`from src.plugin_system import *`来导入所有API。
+
+2. register_plugin函数现在转移到了`plugin_system.apis.plugin_register_api`模块中，用户可以通过`from src.plugin_system.apis.plugin_register_api import register_plugin`来导入。
+  - 顺便一提，按照1中说法，你可以这么用：
+    ```python
+    from src.plugin_system import register_plugin
+    ```
+
+3. 现在强制要求的property如下，即你必须覆盖的属性有：
+  - `plugin_name`: 插件名称，必须是唯一的。（与文件夹相同）
+  - `enable_plugin`: 是否启用插件，默认为`True`。
+  - `dependencies`: 插件依赖的其他插件列表，默认为空。**现在并不检查（也许）**
+  - `python_dependencies`: 插件依赖的Python包列表，默认为空。**现在并不检查**
+  - `config_file_name`: 插件配置文件名，默认为`config.toml`。
+  - `config_schema`: 插件配置文件的schema，用于自动生成配置文件。
+4. 部分API的参数类型和返回值进行了调整
+  - `chat_api.py`中获取流的参数中可以使用一个特殊的枚举类型来获得所有平台的 ChatStream 了。
+  - `config_api.py`中的`get_global_config`和`get_plugin_config`方法现在支持嵌套访问的配置键名。
+  - `database_api.py`中的`db_query`方法调整了参数顺序以增强参数限制的同时，保证了typing正确；`db_get`方法增加了`single_result`参数，与`db_query`保持一致。
+5. 增加了`logging_api`，可以用`get_logger`来获取日志记录器。
+6. 增加了插件和组件管理的API。
+7. `BaseCommand`的`execute`方法现在返回一个三元组，包含是否执行成功、可选的回复消息和是否拦截消息。
+  - 这意味着你终于可以动态控制是否继续后续消息的处理了。
+8. 移除了dependency_manager，但是依然保留了`python_dependencies`属性，等待后续重构。
+  - 一并移除了文档有关manager的内容。
+9. 增加了工具的有关api
+
+# 插件系统修改
+1. 现在所有的匹配模式不再是关键字了，而是枚举类。**（可能有遗漏）**
+2. 修复了一下显示插件信息不显示的问题。同时精简了一下显示内容
+3. 修复了插件系统混用了`plugin_name`和`display_name`的问题。现在所有的插件信息都使用`display_name`来显示，而内部标识仍然使用`plugin_name`。
+4. 现在增加了参数类型检查，完善了对应注释
+5. 现在插件抽象出了总基类 `PluginBase`
+  - <del>基于`Action`和`Command`的插件基类现在为`BasePlugin`。</del>
+  - <del>基于`Event`的插件基类现在为`BaseEventPlugin`。</del>
+  - 基于`Action`，`Command`和`Event`的插件基类现在为`BasePlugin`，所有插件都应该继承此基类。
+  - `BasePlugin`继承自`PluginBase`。
+  - 所有的插件类都由`register_plugin`装饰器注册。
+6. 现在我们终于可以让插件有自定义的名字了！
+  - 真正实现了插件的`plugin_name`**不受文件夹名称限制**的功能。（吐槽：可乐你的某个小小细节导致我搞了好久……）
+  - 通过在插件类中定义`plugin_name`属性来指定插件内部标识符。
+  - 由于此更改一个文件中现在可以有多个插件类，但每个插件类必须有**唯一的**`plugin_name`。
+  - 在某些插件加载失败时，现在会显示包名而不是插件内部标识符。
+    - 例如：`MaiMBot.plugins.example_plugin`而不是`example_plugin`。
+    - 仅在插件 import 失败时会如此，正常注册过程中失败的插件不会显示包名，而是显示插件内部标识符。（这是特性，但是基本上不可能出现这个情况）
+7. 现在不支持单文件插件了，加载方式已经完全删除。
+8. 把`BaseEventPlugin`合并到了`BasePlugin`中，所有插件都应该继承自`BasePlugin`。
+9. `BaseEventHandler`现在有了`get_config`方法了。
+10. 修正了`main.py`中的错误输出。
+11. 修正了`command`所编译的`Pattern`注册时的错误输出。
+12. `events_manager`有了task相关逻辑了。
+13. 现在有了插件卸载和重载功能了，也就是热插拔。
+14. 实现了组件的全局启用和禁用功能。
+  - 通过`enable_component`和`disable_component`方法来启用或禁用组件。
+  - 不过这个操作不会保存到配置文件~
+15. 实现了组件的局部禁用，也就是针对某一个聊天禁用的功能。
+  - 通过`disable_specific_chat_action`，`enable_specific_chat_action`，`disable_specific_chat_command`，`enable_specific_chat_command`，`disable_specific_chat_event_handler`，`enable_specific_chat_event_handler`来操作
+  - 同样不保存到配置文件~
+16. 把`BaseTool`一并合并进入了插件系统
+
+# 官方插件修改
+1. `HelloWorld`插件现在有一个样例的`EventHandler`。
+2. 内置插件增加了一个通过`Command`来管理插件的功能。具体是使用`/pm`命令唤起。（需要自行启用）
+3. `HelloWorld`插件现在有一个样例的`CompareNumbersTool`。
+
+### 执笔BGM
+塞壬唱片！

docker-compose.yml

@@ -0,0 +1,91 @@
+services:
+  adapters:
+    container_name: maim-bot-adapters
+    #### prod ####
+    image: unclas/maimbot-adapter:latest
+    # image: infinitycat/maimbot-adapter:latest
+    #### dev ####
+    # image: unclas/maimbot-adapter:dev
+    # image: infinitycat/maimbot-adapter:dev
+    environment:
+      - TZ=Asia/Shanghai
+#    ports:
+#      - "8095:8095"
+    volumes:
+      - ./docker-config/adapters/config.toml:/adapters/config.toml # 持久化adapters配置文件
+      - ./data/adapters:/adapters/data # adapters 数据持久化
+    restart: always
+    networks:
+      - maim_bot
+  core:
+    container_name: maim-bot-core
+    #### prod ####
+    image: sengokucola/maibot:latest
+    # image: infinitycat/maibot:latest
+    #### dev ####
+    # image: sengokucola/maibot:dev
+    # image: infinitycat/maibot:dev
+    environment:
+      - TZ=Asia/Shanghai
+#      - EULA_AGREE=99f08e0cab0190de853cb6af7d64d4de # 同意EULA
+#      - PRIVACY_AGREE=9943b855e72199d0f5016ea39052f1b6 # 同意EULA
+#    ports:
+#      - "8000:8000"
+    volumes:
+      - ./docker-config/mmc/.env:/MaiMBot/.env # 持久化env配置文件
+      - ./docker-config/mmc:/MaiMBot/config # 持久化bot配置文件
+      - ./data/MaiMBot/maibot_statistics.html:/MaiMBot/maibot_statistics.html #统计数据输出
+      - ./data/MaiMBot:/MaiMBot/data # 共享目录
+      - ./data/MaiMBot/plugins:/MaiMBot/plugins # 插件目录
+      - ./data/MaiMBot/logs:/MaiMBot/logs # 日志目录
+      - site-packages:/usr/local/lib/python3.13/site-packages # 持久化Python包
+    restart: always
+    networks:
+      - maim_bot
+  napcat:
+    environment:
+      - NAPCAT_UID=1000
+      - NAPCAT_GID=1000
+      - TZ=Asia/Shanghai
+    ports:
+      - "6099:6099"
+    volumes:
+      - ./docker-config/napcat:/app/napcat/config # 持久化napcat配置文件
+      - ./data/qq:/app/.config/QQ # 持久化QQ本体
+      - ./data/MaiMBot:/MaiMBot/data # 共享目录
+    container_name: maim-bot-napcat
+    restart: always
+    image: mlikiowa/napcat-docker:latest
+    networks:
+      - maim_bot
+  sqlite-web:
+    # 注意：coleifer/sqlite-web 镜像不支持arm64
+    image: coleifer/sqlite-web
+    container_name: sqlite-web
+    restart: always
+    ports:
+      - "8120:8080"
+    volumes:
+      - ./data/MaiMBot:/data/MaiMBot
+    environment:
+      - SQLITE_DATABASE=MaiMBot/MaiBot.db  # 你的数据库文件
+    networks:
+      - maim_bot
+
+  # chat2db占用相对较高但是功能强大
+  # 内存占用约600m，内存充足推荐选此
+  # chat2db:
+  #   image: chat2db/chat2db:latest
+  #   container_name: maim-bot-chat2db
+  #   restart: always
+  #   ports:
+  #     - "10824:10824"
+  #   volumes:
+  #     - ./data/MaiMBot:/data/MaiMBot
+  #   networks:
+  #     - maim_bot
+volumes:
+  site-packages:
+networks:
+  maim_bot:
+    driver: bridge

docs/Bing.md

@@ -0,0 +1,51 @@
+- **参数化与动态调整聊天行为**:
+    - 将 `NormalChatInstance` 和 `HeartFlowChatInstance` 中的关键行为参数（例如：回复概率、思考频率、兴趣度阈值、状态转换条件等）提取出来，使其更易于配置。
+    - 允许每个 `SubHeartflow` (即每个聊天场景) 拥有其独立的参数配置，实现"千群千面"。
+    - 开发机制，使得这些参数能够被动态调整：
+        - 基于外部反馈：例如，根据用户评价（"话太多"或"太冷淡"）调整回复频率。
+        - 基于环境分析：例如，根据群消息的活跃度自动调整参与度。
+        - 基于学习：通过分析历史交互数据，优化特定群聊下的行为模式。
+    - 目标是让 Mai 在不同群聊中展现出更适应环境、更个性化的交互风格。
+
+- **动态 Prompt 生成与人格塑造**:
+    - 当前 Prompt (提示词) 相对静态。计划实现动态或半结构化的 Prompt 生成。
+    - Prompt 内容可根据以下因素调整：
+        - **人格特质**: 通过参数化配置（如友善度、严谨性等），影响 Prompt 的措辞、语气和思考倾向，塑造更稳定和独特的人格。
+        - **当前情绪**: 将实时情绪状态融入 Prompt，使回复更符合当下心境。
+    - 目标：提升 `HeartFlowChatInstance` (HFC) 回复的多样性、一致性和真实感。
+    - 前置：需要重构 Prompt 构建逻辑，可能引入 `PromptBuilder` 并提供标准接口 (认为是必须步骤)。
+
+
+- **增强工具调用能力 (Enhanced Tool Usage)**:
+    - 扩展 `HeartFlowChatInstance` (HFC) 可用的工具集。
+    - 考虑引入"元工具"或分层工具机制，允许 HFC 在需要时（如深度思考）访问更强大的工具，例如：
+        - 修改自身或其他 `SubHeartflow` 的聊天参数。
+        - 请求改变 Mai 的全局状态 (`MaiState`)。
+        - 管理日程或执行更复杂的分析任务。
+    - 目标：提升 HFC 的自主决策和行动能力，即使会增加一定的延迟。
+
+- **标准化人设生成 (Standardized Persona Generation)**:
+    - **目标**: 解决手动配置 `人设` 文件缺乏标准、难以全面描述个性的问题，并生成更丰富、可操作的人格资源。
+    - **方法**: 利用大型语言模型 (LLM) 辅助生成标准化的、结构化的人格**资源包**。
+    - **生成内容**: 不仅生成描述性文本（替代现有 `individual` 配置），还可以同时生成与该人格配套的：
+        - **相关工具 (Tools)**: 该人格倾向于使用的工具或能力。
+        - **初始记忆/知识库 (Memories/Knowledge)**: 定义其背景和知识基础。
+        - **核心行为模式 (Core Behavior Patterns)**: 预置一些典型的行为方式，可作为行为学习的起点。
+    - **实现途径**: 
+        - 通过与 LLM 的交互式对话来定义和细化人格及其配套资源。
+        - 让 LLM 分析提供的文本材料（如小说、背景故事）来提取人格特质和相关信息。
+    - **优势**: 替代易出错且标准不一的手动配置，生成更丰富、一致、包含配套资源且易于系统理解和应用的人格包。
+
+
+- **探索高级记忆检索机制 (GE 系统概念):**
+    - 研究超越简单关键词/近期性检索的记忆模型。
+    - 考虑引入基于事件关联、相对时间线索和绝对时间锚点的检索方式。
+    - 可能涉及设计新的事件表示或记忆结构。
+
+- **基于人格生成预设知识:**
+    - 开发利用 LLM 和人格配置生成背景知识的功能。
+    - 这些知识应符合角色的行为风格和可能的经历。
+    - 作为一种"冷启动"或丰富角色深度的方式。
+
+
+1.更nb的工作记忆，直接开一个play_ground，通过llm进行内容检索，这个play_ground可以容纳巨量信息，并且十分通用化，十分好。

docs/CONTRIBUTE.md

@@ -0,0 +1,88 @@
+# 如何给MaiCore做贡献v1.0
+
+修改时间2025/4/5
+
+如有修改建议或疑问，请在github上建立issue
+
+首先，非常感谢你抽出时间来做贡献！❤️
+
+这份文档是告诉你，当你想向MaiCore提交代码，或者想要以其他形式加入MaiCore的开发，或周边插件的开发，你可以怎么做。
+
+我们鼓励并重视任何形式的贡献，但无序的贡献只会使麦麦的维护与更新变成一团糟。因此，我们建议您在做出贡献之前，先查看本指南。
+
+
+> 另外，如果您喜欢这个项目，但只是没有时间做贡献，那也没关系。还有其他简单的方式来支持本项目并表达您的感激之情，我们也会非常高兴：
+> - 给我们点一颗小星星（Star）
+> - 在您的项目的readme中引用这个项目
+
+## 目录
+
+● [我有问题](#我有问题)
+● [我想做贡献](#我想做贡献)
+● [我想提出建议](#提出建议)
+
+## 我有问题
+
+> 如果你想问一个问题，我们会假设你已经阅读了现有的文档。
+
+在你提问之前，最好先搜索现有的[issue](/issues)，看看是否有助于解决你的问题。如果你找到了匹配的issue，但仍需要追加说明，你可以在该issue下提出你的问题。同时，我们还建议你先在互联网上搜索答案。
+
+如果你仍然觉得有必要提问并需要进行说明，我们建议你：
+
+● 开一个[新Issue](/issues/new)。并尽可能详细地描述你的问题。
+
+● 提供尽可能多的上下文信息，让我们更好地理解你遇到的问题。比如：提供版本信息（哪个分支，版本号是多少，运行环境有哪些等），具体取决于你认为相关的内容。
+
+只要你提出的issue明确且合理，我们都会回复并尝试解决您的问题。
+
+
+## 我想做贡献
+
+> ### 项目所有权与维护
+> MaiMBot项目（现更名为MaiBot，核心为MaiCore）由千石可乐SengokuCola创建，采用GPL3开源协议。
+> MaiBot项目现已移动至MaiM-with-u组织下，目前主要内容由核心开发组维护，整体由核心开发组、reviewer和所有贡献者共同维护（该部分在未来将会明确）。
+> 为了保证设计的统一和节省不必要的精力，以及为了对项目有整体的把控，我们对不同类型的贡献采取不同的审核策略：
+> 
+> #### 功能新增
+> - 定义：涉及新功能添加、架构调整、重要模块重构等
+> - 要求：原则上暂不接收，你可以发布issue提供新功能建议。
+> 
+> #### Bug修复
+> - 定义：修复现有功能中的错误，包括非预期行为（需要发布issue进行确认）和运行错误，不涉及新功能或架构变动
+> - 要求：由核心组成员或2名及以上reviewer同时确认才会被合并
+> - 关闭：包含预期行为改动，新功能，破坏原有功能，数据库破坏性改动等的pr将会被关闭
+> 
+> #### 文档修补
+> - 定义：修复现有文档中的错误，提供新的帮助文档
+> - 要求：现需要提交至组织下docs仓库，由reviewer确认后合并
+
+
+> ### 法律声明
+> 当你为本项目贡献代码/文档时，你必须确认：
+> 1. 你贡献的内容100%是由你创作；
+> 2. 你对这些内容拥有相应的权利；
+> 3. 你贡献的内容将按项目许可协议使用。
+
+
+## 提出建议
+
+这一部分指导您如何为MaiCore/MaiBot提交一个建议，包括全新的功能和对现有功能的小改进。遵循这些指南将有助于维护人员和社区了解您的建议并找到相关的建议。
+
+在提交建议之前
+
+● 请确保您正在使用最新版本（正式版请查看main分支，测试版查看dev分支）。
+
+● 请确保您已经阅读了文档，以确认您的建议是否已经被实现，也许是通过单独的配置。
+
+● 仔细阅读文档并了解项目目前是否支持该功能，也许可以通过单独的配置来实现。
+
+● 进行一番[搜索](/issues)以查看是否已经有人提出了这个建议。如果有，请在现有的issue下添加评论，而不是新开一个issue。
+
+● 请确保您的建议符合项目的范围和目标。你需要提出一个强有力的理由来说服项目的开发者这个功能的优点。请记住，我们希望的功能是对大多数用户有用的，而不仅仅是少数用户。如果你只是针对少数用户，请考虑编写一个插件。
+
+### 附（暂定）：
+核心组成员：@SengokuCola @tcmofashi @Rikki-Zero
+
+reviewer：核心组+MaiBot主仓库合作者/权限者
+
+贡献者：所有提交过贡献的用户

docs/model_configuration_guide.md

@@ -0,0 +1,333 @@
+# 模型配置指南
+
+本文档将指导您如何配置 `model_config.toml` 文件，该文件用于配置 MaiBot 的各种AI模型和API服务提供商。
+
+## 配置文件结构
+
+配置文件主要包含以下几个部分：
+- 版本信息
+- API服务提供商配置
+- 模型配置
+- 模型任务配置
+
+## 1. 版本信息
+
+```toml
+[inner]
+version = "1.1.1"
+```
+
+用于标识配置文件的版本，遵循语义化版本规则。
+
+## 2. API服务提供商配置
+
+### 2.1 基本配置
+
+使用 `[[api_providers]]` 数组配置多个API服务提供商：
+
+```toml
+[[api_providers]]
+name = "DeepSeek"                       # 服务商名称（自定义）
+base_url = "https://api.deepseek.cn/v1" # API服务的基础URL
+api_key = "your-api-key-here"           # API密钥
+client_type = "openai"                  # 客户端类型
+max_retry = 2                           # 最大重试次数
+timeout = 30                            # 超时时间（秒）
+retry_interval = 10                     # 重试间隔（秒）
+```
+
+### 2.2 配置参数说明
+
+| 参数 | 必填 | 说明 | 默认值 |
+|------|------|------|--------|
+| `name` | ✅ | 服务商名称，需要在模型配置中引用 | - |
+| `base_url` | ✅ | API服务的基础URL | - |
+| `api_key` | ✅ | API密钥，请替换为实际密钥 | - |
+| `client_type` | ❌ | 客户端类型：`openai`（OpenAI格式）或 `gemini`（Gemini格式，现在支持不良好） | `openai` |
+| `max_retry` | ❌ | API调用失败时的最大重试次数 | 2 |
+| `timeout` | ❌ | API请求超时时间（秒） | 30 |
+| `retry_interval` | ❌ | 重试间隔时间（秒） | 10 |
+
+**请注意，对于`client_type`为`gemini`的模型，`base_url`字段无效。**
+### 2.3 支持的服务商示例
+
+#### DeepSeek
+```toml
+[[api_providers]]
+name = "DeepSeek"
+base_url = "https://api.deepseek.cn/v1"
+api_key = "your-deepseek-api-key"
+client_type = "openai"
+```
+
+#### SiliconFlow
+```toml
+[[api_providers]]
+name = "SiliconFlow"
+base_url = "https://api.siliconflow.cn/v1"
+api_key = "your-siliconflow-api-key"
+client_type = "openai"
+```
+
+#### Google Gemini
+```toml
+[[api_providers]]
+name = "Google"
+base_url = "https://api.google.com/v1"
+api_key = "your-google-api-key"
+client_type = "gemini"  # 注意：Gemini需要使用特殊客户端
+```
+
+## 3. 模型配置
+
+### 3.1 基本模型配置
+
+使用 `[[models]]` 数组配置多个模型：
+
+```toml
+[[models]]
+model_identifier = "deepseek-chat"  # 模型在API服务商中的标识符
+name = "deepseek-v3"               # 自定义模型名称
+api_provider = "DeepSeek"          # 引用的API服务商名称
+price_in = 2.0                     # 输入价格（元/M token）
+price_out = 8.0                    # 输出价格（元/M token）
+```
+
+### 3.2 高级模型配置
+
+#### 强制流式输出
+对于不支持非流式输出的模型：
+```toml
+[[models]]
+model_identifier = "some-model"
+name = "custom-name"
+api_provider = "Provider"
+force_stream_mode = true  # 启用强制流式输出
+```
+
+#### 额外参数配置`extra_params`
+```toml
+[[models]]
+model_identifier = "Qwen/Qwen3-8B"
+name = "qwen3-8b"
+api_provider = "SiliconFlow"
+[models.extra_params]
+enable_thinking = false # 禁用思考
+```
+这里的 `extra_params` 可以包含任何API服务商支持的额外参数配置，**配置时应参考相应的API文档**。
+
+比如上面就是参考SiliconFlow的文档配置配置的`Qwen3`禁用思考参数。
+
+![SiliconFlow文档截图](image-1.png)
+
+以豆包文档为另一个例子
+
+![豆包文档截图](image.png)
+
+得到豆包`"doubao-seed-1-6-250615"`的禁用思考配置方法为
+```toml
+[[models]]
+# 你的模型
+[models.extra_params]
+thinking = {type = "disabled"} # 禁用思考
+```
+请注意，`extra_params` 的配置应该构成一个合法的TOML字典结构，具体内容取决于API服务商的要求。
+
+**请注意，对于`client_type`为`gemini`的模型，此字段无效。**
+### 3.3 配置参数说明
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `model_identifier` | ✅ | API服务商提供的模型标识符 |
+| `name` | ✅ | 自定义模型名称，用于在任务配置中引用 |
+| `api_provider` | ✅ | 对应的API服务商名称 |
+| `price_in` | ❌ | 输入价格（元/M token），用于成本统计 |
+| `price_out` | ❌ | 输出价格（元/M token），用于成本统计 |
+| `force_stream_mode` | ❌ | 是否强制使用流式输出 |
+| `extra_params` | ❌ | 额外的模型参数配置 |
+
+## 4. 模型任务配置
+
+### utils - 工具模型
+用于表情包模块、取名模块、关系模块等核心功能：
+```toml
+[model_task_config.utils]
+model_list = ["siliconflow-deepseek-v3"]
+temperature = 0.2
+max_tokens = 800
+```
+
+### utils_small - 小型工具模型
+用于高频率调用的场景，建议使用速度快的小模型：
+```toml
+[model_task_config.utils_small]
+model_list = ["qwen3-8b"]
+temperature = 0.7
+max_tokens = 800
+```
+
+### replyer_1 - 主要回复模型
+首要回复模型，也用于表达器和表达方式学习：
+```toml
+[model_task_config.replyer_1]
+model_list = ["siliconflow-deepseek-v3"]
+temperature = 0.2
+max_tokens = 800
+```
+
+### replyer_2 - 次要回复模型
+```toml
+[model_task_config.replyer_2]
+model_list = ["siliconflow-deepseek-v3"]
+temperature = 0.7
+max_tokens = 800
+```
+
+### planner - 决策模型
+负责决定MaiBot该做什么：
+```toml
+[model_task_config.planner]
+model_list = ["siliconflow-deepseek-v3"]
+temperature = 0.3
+max_tokens = 800
+```
+
+### emotion - 情绪模型
+负责MaiBot的情绪变化：
+```toml
+[model_task_config.emotion]
+model_list = ["siliconflow-deepseek-v3"]
+temperature = 0.3
+max_tokens = 800
+```
+
+### memory - 记忆模型
+```toml
+[model_task_config.memory]
+model_list = ["qwen3-30b"]
+temperature = 0.7
+max_tokens = 800
+```
+
+### vlm - 视觉语言模型
+用于图像识别：
+```toml
+[model_task_config.vlm]
+model_list = ["qwen2.5-vl-72b"]
+max_tokens = 800
+```
+
+### voice - 语音识别模型
+```toml
+[model_task_config.voice]
+model_list = ["sensevoice-small"]
+```
+
+### embedding - 嵌入模型
+```toml
+[model_task_config.embedding]
+model_list = ["bge-m3"]
+```
+
+### tool_use - 工具调用模型
+需要使用支持工具调用的模型：
+```toml
+[model_task_config.tool_use]
+model_list = ["qwen3-14b"]
+temperature = 0.7
+max_tokens = 800
+```
+
+### lpmm_entity_extract - 实体提取模型
+```toml
+[model_task_config.lpmm_entity_extract]
+model_list = ["siliconflow-deepseek-v3"]
+temperature = 0.2
+max_tokens = 800
+```
+
+### lpmm_rdf_build - RDF构建模型
+```toml
+[model_task_config.lpmm_rdf_build]
+model_list = ["siliconflow-deepseek-v3"]
+temperature = 0.2
+max_tokens = 800
+```
+
+### lpmm_qa - 问答模型
+```toml
+[model_task_config.lpmm_qa]
+model_list = ["deepseek-r1-distill-qwen-32b"]
+temperature = 0.7
+max_tokens = 800
+```
+
+## 5. 配置建议
+
+### 5.1 Temperature 参数选择
+
+| 任务类型 | 推荐温度 | 说明 |
+|----------|----------|------|
+| 精确任务（工具调用、实体提取） | 0.1-0.3 | 需要准确性和一致性 |
+| 创意任务（对话、记忆） | 0.5-0.8 | 需要多样性和创造性 |
+| 平衡任务（决策、情绪） | 0.3-0.5 | 平衡准确性和灵活性 |
+
+### 5.2 模型选择建议
+
+| 任务类型 | 推荐模型类型 | 示例 |
+|----------|--------------|------|
+| 高精度任务 | 大模型 | DeepSeek-V3, GPT-4 |
+| 高频率任务 | 小模型 | Qwen3-8B |
+| 多模态任务 | 专用模型 | Qwen2.5-VL, SenseVoice |
+| 工具调用 | 支持Function Call的模型 | Qwen3-14B |
+
+### 5.3 成本优化
+
+1. **分层使用**：核心功能使用高质量模型，辅助功能使用经济模型
+2. **合理配置max_tokens**：根据实际需求设置，避免浪费
+3. **选择免费模型**：对于测试环境，优先使用price为0的模型
+
+## 6. 配置验证
+
+### 6.1 必要检查项
+
+1. ✅ API密钥是否正确配置
+2. ✅ 模型标识符是否与API服务商提供的一致
+3. ✅ 任务配置中引用的模型名称是否在models中定义
+4. ✅ 多模态任务是否配置了对应的专用模型
+
+### 6.2 测试配置
+
+建议在正式使用前：
+1. 使用少量测试数据验证配置
+2. 检查API调用是否正常
+3. 确认成本统计功能正常工作
+
+## 7. 故障排除
+
+### 7.1 常见问题
+
+**问题1**: API调用失败
+- 检查API密钥是否正确
+- 确认base_url是否可访问
+- 检查模型标识符是否正确
+
+**问题2**: 模型未找到
+- 确认模型名称在任务配置和模型定义中一致
+- 检查api_provider名称是否匹配
+
+**问题3**: 响应异常
+- 检查温度参数是否合理（0-1之间）
+- 确认max_tokens设置是否合适
+- 验证模型是否支持所需功能
+
+### 7.2 日志查看
+
+查看 `logs/` 目录下的日志文件，寻找相关错误信息。
+
+## 8. 更新和维护
+
+1. **定期更新**: 关注API服务商的模型更新，及时调整配置
+2. **性能监控**: 监控模型调用的成本和性能
+3. **备份配置**: 在修改前备份当前配置文件
+

docs/plugins/action-components.md

@@ -0,0 +1,297 @@
+# ⚡ Action组件详解
+
+## 📖 什么是Action
+
+Action是给麦麦在回复之外提供额外功能的智能组件，**由麦麦的决策系统自主选择是否使用**，具有随机性和拟人化的调用特点。Action不是直接响应用户命令，而是让麦麦根据聊天情境智能地选择合适的动作，使其行为更加自然和真实。
+
+### Action的特点
+
+- 🧠 **智能激活**：麦麦根据多种条件智能判断是否使用
+- 🎲 **可随机性**：可以使用随机数激活，增加行为的不可预测性，更接近真人交流
+- 🤖 **拟人化**：让麦麦的回应更自然、更有个性
+- 🔄 **情境感知**：基于聊天上下文做出合适的反应
+
+---
+
+## 🎯 Action组件的基本结构
+首先，所有的Action都应该继承`BaseAction`类。
+
+其次，每个Action组件都应该实现以下基本信息：
+```python
+class ExampleAction(BaseAction):
+    action_name = "example_action" # 动作的唯一标识符
+    action_description = "这是一个示例动作" # 动作描述
+    activation_type = ActionActivationType.ALWAYS # 这里以 ALWAYS 为例
+    mode_enable = ChatMode.ALL # 一般取ALL，表示在所有聊天模式下都可用
+    associated_types = ["text", "emoji", ...] # 关联类型
+    parallel_action = False # 是否允许与其他Action并行执行
+    action_parameters = {"param1": "参数1的说明", "param2": "参数2的说明", ...}
+    # Action使用场景描述 - 帮助LLM判断何时"选择"使用
+    action_require = ["使用场景描述1", "使用场景描述2", ...]
+
+    async def execute(self) -> Tuple[bool, str]:
+        """
+        执行Action的主要逻辑
+        
+        Returns:
+            Tuple[bool, str]: (是否成功, 执行结果描述)
+        """
+        # ---- 执行动作的逻辑 ----
+        return True, "执行成功"
+```
+#### associated_types: 该Action会发送的消息类型，例如文本、表情等。
+
+这部分由Adapter传递给处理器。
+
+以 MaiBot-Napcat-Adapter 为例，可选项目如下：
+| 类型 | 说明 | 格式 |
+| --- | --- | --- |
+| text | 文本消息 | str |
+| emoji | 表情消息 | str: 表情包的无头base64|
+| image | 图片消息 | str: 图片的无头base64 |
+| reply | 回复消息 | str: 回复的消息ID |
+| voice | 语音消息 | str: wav格式语音的无头base64 |
+| command | 命令消息 | 参见Adapter文档 |
+| voiceurl | 语音URL消息 | str: wav格式语音的URL |
+| music | 音乐消息 | str: 这首歌在网易云音乐的音乐id |
+| videourl | 视频URL消息 | str: 视频的URL |
+| file | 文件消息 | str: 文件的路径 |
+
+**请知悉，对于不同的处理器，其支持的消息类型可能会有所不同。在开发时请注意。**
+
+#### action_parameters: 该Action的参数说明。
+这是一个字典，键为参数名，值为参数说明。这个字段可以帮助LLM理解如何使用这个Action，并由LLM返回对应的参数，最后传递到 Action 的 **`action_data`** 属性中。其格式与你定义的格式完全相同 **（除非LLM哈气了，返回了错误的内容）**。
+
+---
+
+## 🎯 Action 调用的决策机制
+
+Action采用**两层决策机制**来优化性能和决策质量：
+
+> 设计目的：在加载许多插件的时候降低LLM决策压力，避免让麦麦在过多的选项中纠结。
+
+**第一层：激活控制（Activation Control）**
+
+激活决定麦麦是否 **“知道”** 这个Action的存在，即这个Action是否进入决策候选池。不被激活的Action麦麦永远不会选择。
+
+**第二层：使用决策（Usage Decision）**
+
+在Action被激活后，使用条件决定麦麦什么时候会 **“选择”** 使用这个Action。
+
+### 决策参数详解 🔧
+
+#### 第一层：ActivationType 激活类型说明
+
+| 激活类型 | 说明 | 使用场景 |
+| ----------- | ---------------------------------------- | ---------------------- |
+| [`NEVER`](#never-激活)     | 从不激活，Action对麦麦不可见               | 临时禁用某个Action      |
+| [`ALWAYS`](#always-激活)    | 永远激活，Action总是在麦麦的候选池中        | 核心功能，如回复、不回复 |
+| [`LLM_JUDGE`](#llm_judge-激活) | 通过LLM智能判断当前情境是否需要激活此Action | 需要智能判断的复杂场景   |
+| `RANDOM`    | 基于随机概率决定是否激活                   | 增加行为随机性的功能     |
+| `KEYWORD`   | 当检测到特定关键词时激活                   | 明确触发条件的功能       |
+
+#### `NEVER` 激活
+
+`ActionActivationType.NEVER` 会使得 Action 永远不会被激活
+
+```python
+class DisabledAction(BaseAction):
+    activation_type = ActionActivationType.NEVER  # 永远不激活
+    
+    async def execute(self) -> Tuple[bool, str]:
+        # 这个Action永远不会被执行
+        return False, "这个Action被禁用"
+```
+
+#### `ALWAYS` 激活
+
+`ActionActivationType.ALWAYS` 会使得 Action 永远会被激活，即一直在 Action 候选池中
+
+这种激活方式常用于核心功能，如回复或不回复。
+
+```python
+class AlwaysActivatedAction(BaseAction):
+    activation_type = ActionActivationType.ALWAYS  # 永远激活
+    
+    async def execute(self) -> Tuple[bool, str]:
+        # 执行核心功能
+        return True, "执行了核心功能"
+```
+
+#### `LLM_JUDGE` 激活
+
+`ActionActivationType.LLM_JUDGE`会使得这个 Action 根据 LLM 的判断来决定是否加入候选池。
+
+而 LLM 的判断是基于代码中预设的`llm_judge_prompt`和自动提供的聊天上下文进行的。
+
+因此使用此种方法需要实现`llm_judge_prompt`属性。
+
+```python
+class LLMJudgedAction(BaseAction):
+    activation_type = ActionActivationType.LLM_JUDGE  # 通过LLM判断激活
+    # LLM判断提示词
+    llm_judge_prompt = (
+    "判定是否需要使用这个动作的条件：\n"
+    "1. 用户希望调用XXX这个动作\n"
+    "...\n"
+    "请回答\"是\"或\"否\"。\n"
+    )
+
+    async def execute(self) -> Tuple[bool, str]:
+        # 根据LLM判断是否执行
+        return True, "执行了LLM判断功能"
+```
+
+#### `RANDOM` 激活
+
+`ActionActivationType.RANDOM`会使得这个 Action 根据随机概率决定是否加入候选池。
+
+概率则由代码中的`random_activation_probability`控制。在内部实现中我们使用了`random.random()`来生成一个0到1之间的随机数，并与这个概率进行比较。
+
+因此使用这个方法需要实现`random_activation_probability`属性。
+
+```python
+class SurpriseAction(BaseAction):
+    activation_type = ActionActivationType.RANDOM  # 基于随机概率激活
+    # 随机激活概率
+    random_activation_probability = 0.1  # 10%概率激活
+  
+    async def execute(self) -> Tuple[bool, str]:
+        # 执行惊喜动作
+        return True, "发送了惊喜内容"
+```
+
+#### `KEYWORD` 激活
+
+`ActionActivationType.KEYWORD`会使得这个 Action 在检测到特定关键词时激活。
+
+关键词由代码中的`activation_keywords`定义，而`keyword_case_sensitive`则控制关键词匹配时是否区分大小写。在内部实现中，我们使用了`in`操作符来检查消息内容是否包含这些关键词。
+
+因此，使用此种方法需要实现`activation_keywords`和`keyword_case_sensitive`属性。
+
+```python
+class GreetingAction(BaseAction):
+    activation_type = ActionActivationType.KEYWORD  # 关键词激活
+    activation_keywords = ["你好", "hello", "hi", "嗨"] # 关键词配置
+    keyword_case_sensitive = False  # 不区分大小写
+  
+    async def execute(self) -> Tuple[bool, str]:
+        # 执行问候逻辑
+        return True, "发送了问候"
+```
+
+一个完整的使用`ActionActivationType.KEYWORD`的例子请参考`plugins/hello_world_plugin`中的`ByeAction`。
+
+#### 第二层：使用决策
+
+**在Action被激活后，使用条件决定麦麦什么时候会"选择"使用这个Action**。
+
+这一层由以下因素综合决定：
+
+- `action_require`：使用场景描述，帮助LLM判断何时选择
+- `action_parameters`：所需参数，影响Action的可执行性
+- 当前聊天上下文和麦麦的决策逻辑
+
+---
+
+### 决策流程示例
+
+```python
+class EmojiAction(BaseAction):
+    # 第一层：激活控制
+    activation_type = ActionActivationType.RANDOM  # 随机激活
+    random_activation_probability = 0.1  # 10%概率激活
+
+    # 第二层：使用决策
+    action_require = [
+        "表达情绪时可以选择使用",
+        "增加聊天趣味性",
+        "不要连续发送多个表情"
+    ]
+```
+
+**决策流程**：
+
+1. **第一层激活判断**：
+
+    - 使用随机数进行决策，当`random.random() < self.random_activation_probability`时，麦麦才"知道"可以使用这个Action
+2. **第二层使用决策**：
+
+   - 即使Action被激活，麦麦还会根据 `action_require` 中的条件判断是否真正选择使用
+   - 例如：如果刚刚已经发过表情，根据"不要连续发送多个表情"的要求，麦麦可能不会选择这个Action
+
+---
+
+## Action 内置属性说明
+```python
+class BaseAction:
+    def __init__(self):
+        # 消息相关属性
+        self.log_prefix: str          # 日志前缀
+        self.group_id: str            # 群组ID
+        self.group_name: str          # 群组名称
+        self.user_id: str             # 用户ID
+        self.user_nickname: str       # 用户昵称
+        self.platform: str            # 平台类型 (qq, telegram等)
+        self.chat_id: str             # 聊天ID
+        self.chat_stream: ChatStream  # 聊天流对象
+        self.is_group: bool           # 是否群聊
+
+        # 消息体
+        self.action_message: dict     # 消息数据
+
+        # Action相关属性
+        self.action_data: dict        # Action执行时的数据
+        self.thinking_id: str         # 思考ID
+```
+action_message为一个字典，包含的键值对如下（省略了不必要的键值对）
+
+```python
+{
+    "message_id": "1234567890",  # 消息id，str
+    "time": 1627545600.0,  # 时间戳，float
+    "chat_id": "abcdef123456",  # 聊天ID，str
+    "reply_to": None,  # 回复消息id，str或None
+    "interest_value": 0.85,  # 兴趣值，float
+    "is_mentioned": True,  # 是否被提及，bool
+    "chat_info_last_active_time": 1627548600.0,  # 最后活跃时间，float
+    "processed_plain_text": None,  # 处理后的文本，str或None
+    "additional_config": None,  # Adapter传来的additional_config，dict或None
+    "is_emoji": False,  # 是否为表情，bool
+    "is_picid": False,  # 是否为图片ID，bool
+    "is_command": False  # 是否为命令，bool
+}
+```
+
+部分值的格式请自行查询数据库。
+
+---
+
+## Action 内置方法说明
+```python
+class BaseAction:
+    def get_config(self, key: str, default=None):
+        """获取插件配置值，使用嵌套键访问"""
+    
+    async def wait_for_new_message(self, timeout: int = 1200) -> Tuple[bool, str]:
+        """等待新消息或超时"""
+
+    async def send_text(self, content: str, reply_to: str = "", reply_to_platform_id: str = "", typing: bool = False) -> bool:
+        """发送文本消息"""
+
+    async def send_emoji(self, emoji_base64: str) -> bool:
+        """发送表情包"""
+
+    async def send_image(self, image_base64: str) -> bool:
+        """发送图片"""
+
+    async def send_custom(self, message_type: str, content: str, typing: bool = False, reply_to: str = "") -> bool:
+        """发送自定义类型消息"""
+
+    async def store_action_info(self, action_build_into_prompt: bool = False, action_prompt_display: str = "", action_done: bool = True) -> None:
+        """存储动作信息到数据库"""
+
+    async def send_command(self, command_name: str, args: Optional[dict] = None, display_message: str = "", storage_message: bool = True) -> bool:
+        """发送命令消息"""
+```
+具体参数与用法参见`BaseAction`基类的定义。

docs/plugins/api/chat-api.md

@@ -0,0 +1,130 @@
+# 聊天API
+
+聊天API模块专门负责聊天信息的查询和管理，帮助插件获取和管理不同的聊天流。
+
+## 导入方式
+
+```python
+from src.plugin_system import chat_api
+# 或者
+from src.plugin_system.apis import chat_api
+```
+
+一种**Deprecated**方式：
+```python
+from src.plugin_system.apis.chat_api import ChatManager
+```
+
+## 主要功能
+
+### 1. 获取所有的聊天流
+
+```python
+def get_all_streams(platform: Optional[str] | SpecialTypes = "qq") -> List[ChatStream]:
+```
+
+**Args**:
+- `platform`：平台筛选，默认为"qq"，可以使用`SpecialTypes`枚举类中的`SpecialTypes.ALL_PLATFORMS`来获取所有平台的聊天流。
+
+**Returns**:
+- `List[ChatStream]`：聊天流列表
+
+### 2. 获取群聊聊天流
+
+```python
+def get_group_streams(platform: Optional[str] | SpecialTypes = "qq") -> List[ChatStream]:
+```
+
+**Args**:
+- `platform`：平台筛选，默认为"qq"，可以使用`SpecialTypes`枚举类中的`SpecialTypes.ALL_PLATFORMS`来获取所有平台的群聊流。
+
+**Returns**:
+- `List[ChatStream]`：群聊聊天流列表
+
+### 3. 获取私聊聊天流
+
+```python
+def get_private_streams(platform: Optional[str] | SpecialTypes = "qq") -> List[ChatStream]:
+```
+
+**Args**:
+- `platform`：平台筛选，默认为"qq"，可以使用`SpecialTypes`枚举类中的`SpecialTypes.ALL_PLATFORMS`来获取所有平台的私聊流。
+
+**Returns**:
+- `List[ChatStream]`：私聊聊天流列表
+
+### 4. 根据群ID获取聊天流
+
+```python
+def get_stream_by_group_id(group_id: str, platform: Optional[str] | SpecialTypes = "qq") -> Optional[ChatStream]:
+```
+
+**Args**:
+- `group_id`：群聊ID
+- `platform`：平台筛选，默认为"qq"，可以使用`SpecialTypes`枚举类中的`SpecialTypes.ALL_PLATFORMS`来获取所有平台的群聊流。
+
+**Returns**:
+- `Optional[ChatStream]`：聊天流对象，如果未找到返回None
+
+### 5. 根据用户ID获取私聊流
+
+```python
+def get_stream_by_user_id(user_id: str, platform: Optional[str] | SpecialTypes = "qq") -> Optional[ChatStream]:
+```
+
+**Args**:
+- `user_id`：用户ID
+- `platform`：平台筛选，默认为"qq"，可以使用`SpecialTypes`枚举类中的`SpecialTypes.ALL_PLATFORMS`来获取所有平台的私聊流。
+
+**Returns**:
+- `Optional[ChatStream]`：聊天流对象，如果未找到返回None
+
+### 6. 获取聊天流类型
+
+```python
+def get_stream_type(chat_stream: ChatStream) -> str:
+```
+
+**Args**:
+- `chat_stream`：聊天流对象
+
+**Returns**:
+- `str`：聊天流类型，可能的值包括`private`（私聊流），`group`（群聊流）以及`unknown`（未知类型）。
+
+### 7. 获取聊天流信息
+
+```python
+def get_stream_info(chat_stream: ChatStream) -> Dict[str, Any]:
+```
+
+**Args**:
+- `chat_stream`：聊天流对象
+
+**Returns**:
+- `Dict[str, Any]`：聊天流的详细信息，包括但不限于：
+    - `stream_id`：聊天流ID
+    - `platform`：平台名称
+    - `type`：聊天流类型
+    - `group_id`：群聊ID
+    - `group_name`：群聊名称
+    - `user_id`：用户ID
+    - `user_name`：用户名称
+
+### 8. 获取聊天流统计摘要
+
+```python
+def get_streams_summary() -> Dict[str, int]:
+```
+
+**Returns**:
+- `Dict[str, int]`：聊天流统计信息摘要，包含以下键：
+    - `total_streams`：总聊天流数量
+    - `group_streams`：群聊流数量
+    - `private_streams`：私聊流数量
+    - `qq_streams`：QQ平台流数量
+
+
+## 注意事项
+
+1. 大部分函数在参数不合法时候会抛出异常，请确保你的程序进行了捕获。
+2. `ChatStream`对象包含了聊天的完整信息，包括用户信息、群信息等。

docs/plugins/api/component-manage-api.md

@@ -0,0 +1,194 @@
+# 组件管理API
+
+组件管理API模块提供了对插件组件的查询和管理功能，使得插件能够获取和使用组件相关的信息。
+
+## 导入方式
+```python
+from src.plugin_system.apis import component_manage_api
+# 或者
+from src.plugin_system import component_manage_api
+```
+
+## 功能概述
+
+组件管理API主要提供以下功能：
+- **插件信息查询** - 获取所有插件或指定插件的信息。
+- **组件查询** - 按名称或类型查询组件信息。
+- **组件管理** - 启用或禁用组件，支持全局和局部操作。
+
+## 主要功能
+
+### 1. 获取所有插件信息
+```python
+def get_all_plugin_info() -> Dict[str, PluginInfo]:
+```
+获取所有插件的信息。
+
+**Returns:**
+- `Dict[str, PluginInfo]` - 包含所有插件信息的字典，键为插件名称，值为 `PluginInfo` 对象。
+
+### 2. 获取指定插件信息
+```python
+def get_plugin_info(plugin_name: str) -> Optional[PluginInfo]:
+```
+获取指定插件的信息。
+
+**Args:**
+- `plugin_name` (str): 插件名称。
+
+**Returns:**
+- `Optional[PluginInfo]`: 插件信息对象，如果插件不存在则返回 `None`。
+
+### 3. 获取指定组件信息
+```python
+def get_component_info(component_name: str, component_type: ComponentType) -> Optional[Union[CommandInfo, ActionInfo, EventHandlerInfo]]:
+```
+获取指定组件的信息。
+
+**Args:**
+- `component_name` (str): 组件名称。
+- `component_type` (ComponentType): 组件类型。
+
+**Returns:**
+- `Optional[Union[CommandInfo, ActionInfo, EventHandlerInfo]]`: 组件信息对象，如果组件不存在则返回 `None`。
+
+### 4. 获取指定类型的所有组件信息
+```python
+def get_components_info_by_type(component_type: ComponentType) -> Dict[str, Union[CommandInfo, ActionInfo, EventHandlerInfo]]:
+```
+获取指定类型的所有组件信息。
+
+**Args:**
+- `component_type` (ComponentType): 组件类型。
+
+**Returns:**
+- `Dict[str, Union[CommandInfo, ActionInfo, EventHandlerInfo]]`: 包含指定类型组件信息的字典，键为组件名称，值为对应的组件信息对象。
+
+### 5. 获取指定类型的所有启用的组件信息
+```python
+def get_enabled_components_info_by_type(component_type: ComponentType) -> Dict[str, Union[CommandInfo, ActionInfo, EventHandlerInfo]]:
+```
+获取指定类型的所有启用的组件信息。
+
+**Args:**
+- `component_type` (ComponentType): 组件类型。
+
+**Returns:**
+- `Dict[str, Union[CommandInfo, ActionInfo, EventHandlerInfo]]`: 包含指定类型启用组件信息的字典，键为组件名称，值为对应的组件信息对象。
+
+### 6. 获取指定 Action 的注册信息
+```python
+def get_registered_action_info(action_name: str) -> Optional[ActionInfo]:
+```
+获取指定 Action 的注册信息。
+
+**Args:**
+- `action_name` (str): Action 名称。
+
+**Returns:**
+- `Optional[ActionInfo]` - Action 信息对象，如果 Action 不存在则返回 `None`。
+
+### 7. 获取指定 Command 的注册信息
+```python
+def get_registered_command_info(command_name: str) -> Optional[CommandInfo]:
+```
+获取指定 Command 的注册信息。
+
+**Args:**
+- `command_name` (str): Command 名称。
+
+**Returns:**
+- `Optional[CommandInfo]` - Command 信息对象，如果 Command 不存在则返回 `None`。
+
+### 8. 获取指定 Tool 的注册信息
+```python
+def get_registered_tool_info(tool_name: str) -> Optional[ToolInfo]:
+```
+获取指定 Tool 的注册信息。
+
+**Args:**
+- `tool_name` (str): Tool 名称。
+
+**Returns:**
+- `Optional[ToolInfo]` - Tool 信息对象，如果 Tool 不存在则返回 `None`。
+
+### 9. 获取指定 EventHandler 的注册信息
+```python
+def get_registered_event_handler_info(event_handler_name: str) -> Optional[EventHandlerInfo]:
+```
+获取指定 EventHandler 的注册信息。
+
+**Args:**
+- `event_handler_name` (str): EventHandler 名称。
+
+**Returns:**
+- `Optional[EventHandlerInfo]` - EventHandler 信息对象，如果 EventHandler 不存在则返回 `None`。
+
+### 10. 全局启用指定组件
+```python
+def globally_enable_component(component_name: str, component_type: ComponentType) -> bool:
+```
+全局启用指定组件。
+
+**Args:**
+- `component_name` (str): 组件名称。
+- `component_type` (ComponentType): 组件类型。
+
+**Returns:**
+- `bool` - 启用成功返回 `True`，否则返回 `False`。
+
+### 11. 全局禁用指定组件
+```python
+async def globally_disable_component(component_name: str, component_type: ComponentType) -> bool:
+```
+全局禁用指定组件。
+
+**此函数是异步的，确保在异步环境中调用。**
+
+**Args:**
+- `component_name` (str): 组件名称。
+- `component_type` (ComponentType): 组件类型。
+
+**Returns:**
+- `bool` - 禁用成功返回 `True`，否则返回 `False`。
+
+### 12. 局部启用指定组件
+```python
+def locally_enable_component(component_name: str, component_type: ComponentType, stream_id: str) -> bool:
+```
+局部启用指定组件。
+
+**Args:**
+- `component_name` (str): 组件名称。
+- `component_type` (ComponentType): 组件类型。
+- `stream_id` (str): 消息流 ID。
+
+**Returns:**
+- `bool` - 启用成功返回 `True`，否则返回 `False`。
+
+### 13. 局部禁用指定组件
+```python
+def locally_disable_component(component_name: str, component_type: ComponentType, stream_id: str) -> bool:
+```
+局部禁用指定组件。
+
+**Args:**
+- `component_name` (str): 组件名称。
+- `component_type` (ComponentType): 组件类型。
+- `stream_id` (str): 消息流 ID。
+
+**Returns:**
+- `bool` - 禁用成功返回 `True`，否则返回 `False`。
+
+### 14. 获取指定消息流中禁用的组件列表
+```python
+def get_locally_disabled_components(stream_id: str, component_type: ComponentType) -> list[str]:
+```
+获取指定消息流中禁用的组件列表。
+
+**Args:**
+- `stream_id` (str): 消息流 ID。
+- `component_type` (ComponentType): 组件类型。
+
+**Returns:**
+- `list[str]` - 禁用的组件名称列表。

docs/plugins/api/config-api.md

@@ -0,0 +1,52 @@
+# 配置API
+
+配置API模块提供了配置读取功能，让插件能够安全地访问全局配置和插件配置。
+
+## 导入方式
+
+```python
+from src.plugin_system.apis import config_api
+# 或者
+from src.plugin_system import config_api
+```
+
+## 主要功能
+
+### 1. 访问全局配置
+
+```python
+def get_global_config(key: str, default: Any = None) -> Any:
+```
+
+**Args**:
+- `key`: 命名空间式配置键名，使用嵌套访问，如 "section.subsection.key"，大小写敏感
+- `default`: 如果配置不存在时返回的默认值
+
+**Returns**:
+- `Any`: 配置值或默认值
+
+#### 示例：
+获取机器人昵称
+```python
+bot_name = config_api.get_global_config("bot.nickname", "MaiBot")
+```
+
+### 2. 获取插件配置
+
+```python
+def get_plugin_config(plugin_config: dict, key: str, default: Any = None) -> Any:
+```
+**Args**:
+- `plugin_config`: 插件配置字典
+- `key`: 配置键名，支持嵌套访问如 "section.subsection.key"，大小写敏感
+- `default`: 如果配置不存在时返回的默认值
+
+**Returns**:
+- `Any`: 配置值或默认值
+
+## 注意事项
+
+1. **只读访问**：配置API只提供读取功能，插件不能修改全局配置
+2. **错误处理**：所有函数都有错误处理，失败时会记录日志并返回默认值
+3. **安全性**：插件通过此API访问配置是安全和隔离的
+4. **性能**：频繁访问的配置建议在插件初始化时获取并缓存

docs/plugins/api/database-api.md

@@ -0,0 +1,216 @@
+# 数据库API
+
+数据库API模块提供通用的数据库操作功能，支持查询、创建、更新和删除记录，采用Peewee ORM模型。
+
+## 导入方式
+
+```python
+from src.plugin_system.apis import database_api
+# 或者
+from src.plugin_system import database_api
+```
+
+## 主要功能
+
+### 1. 通用数据库操作
+
+```python
+async def db_query(
+    model_class: Type[Model],
+    data: Optional[Dict[str, Any]] = None,
+    query_type: Optional[str] = "get",
+    filters: Optional[Dict[str, Any]] = None,
+    limit: Optional[int] = None,
+    order_by: Optional[List[str]] = None,
+    single_result: Optional[bool] = False,
+) -> Union[List[Dict[str, Any]], Dict[str, Any], None]:
+```
+执行数据库查询操作的通用接口。
+
+**Args:**
+- `model_class`: Peewee模型类。
+    - Peewee模型类可以在`src.common.database.database_model`模块中找到，如`ActionRecords`、`Messages`等。
+- `data`: 用于创建或更新的数据
+- `query_type`: 查询类型
+    - 可选值: `get`, `create`, `update`, `delete`, `count`。
+- `filters`: 过滤条件字典，键为字段名，值为要匹配的值。
+- `limit`: 限制结果数量。
+- `order_by`: 排序字段列表，使用字段名，前缀'-'表示降序。
+    - 排序字段，前缀`-`表示降序，例如`-time`表示按时间字段（即`time`字段）降序
+- `single_result`: 是否只返回单个结果。
+
+**Returns:**
+- 根据查询类型返回不同的结果：
+    - `get`: 返回查询结果列表或单个结果。（如果 `single_result=True`）
+    - `create`: 返回创建的记录。
+    - `update`: 返回受影响的行数。
+    - `delete`: 返回受影响的行数。
+    - `count`: 返回记录数量。
+
+#### 示例
+
+1. 查询最近10条消息
+```python
+messages = await database_api.db_query(
+    Messages,
+    query_type="get",
+    filters={"chat_id": chat_stream.stream_id},
+    limit=10,
+    order_by=["-time"]
+)
+```
+2. 创建一条记录
+```python
+new_record = await database_api.db_query(
+    ActionRecords,
+    data={"action_id": "123", "time": time.time(), "action_name": "TestAction"},
+    query_type="create",
+)
+```
+3. 更新记录
+```python
+updated_count = await database_api.db_query(
+    ActionRecords,
+    data={"action_done": True},
+    query_type="update",
+    filters={"action_id": "123"},
+)
+```
+4. 删除记录
+```python
+deleted_count = await database_api.db_query(
+    ActionRecords,
+    query_type="delete",
+    filters={"action_id": "123"}
+)
+```
+5. 计数
+```python
+count = await database_api.db_query(
+    Messages,
+    query_type="count",
+    filters={"chat_id": chat_stream.stream_id}
+)
+```
+
+### 2. 数据库保存
+```python
+async def db_save(
+    model_class: Type[Model], data: Dict[str, Any], key_field: Optional[str] = None, key_value: Optional[Any] = None
+) -> Optional[Dict[str, Any]]:
+```
+保存数据到数据库（创建或更新）
+
+如果提供了key_field和key_value，会先尝试查找匹配的记录进行更新；
+
+如果没有找到匹配记录，或未提供key_field和key_value，则创建新记录。
+
+**Args:**
+- `model_class`: Peewee模型类。
+- `data`: 要保存的数据字典。
+- `key_field`: 用于查找现有记录的字段名，例如"action_id"。
+- `key_value`: 用于查找现有记录的字段值。
+
+**Returns:**
+- `Optional[Dict[str, Any]]`: 保存后的记录数据，失败时返回None。
+
+#### 示例
+创建或更新一条记录
+```python
+record = await database_api.db_save(
+    ActionRecords,
+    {
+        "action_id": "123",
+        "time": time.time(),
+        "action_name": "TestAction",
+        "action_done": True
+    },
+    key_field="action_id",
+    key_value="123"
+)
+```
+
+### 3. 数据库获取
+```python
+async def db_get(
+    model_class: Type[Model],
+    filters: Optional[Dict[str, Any]] = None,
+    limit: Optional[int] = None,
+    order_by: Optional[str] = None,
+    single_result: Optional[bool] = False,
+) -> Union[List[Dict[str, Any]], Dict[str, Any], None]:
+```
+
+从数据库获取记录
+
+这是db_query方法的简化版本，专注于数据检索操作。
+
+**Args:**
+- `model_class`: Peewee模型类。
+- `filters`: 过滤条件字典，键为字段名，值为要匹配的值。
+- `limit`: 限制结果数量。
+- `order_by`: 排序字段，使用字段名，前缀'-'表示降序。
+- `single_result`: 是否只返回单个结果，如果为True，则返回单个记录字典或None；否则返回记录字典列表或空列表
+
+**Returns:**
+- `Union[List[Dict], Dict, None]`: 查询结果列表或单个结果（如果`single_result=True`），失败时返回None。
+
+#### 示例
+1. 获取单个记录
+```python
+record = await database_api.db_get(
+    ActionRecords,
+    filters={"action_id": "123"},
+    limit=1
+)
+```
+2. 获取最近10条记录
+```python
+records = await database_api.db_get(
+    Messages,
+    filters={"chat_id": chat_stream.stream_id},
+    limit=10,
+    order_by="-time",
+)
+```
+
+### 4. 动作信息存储
+```python
+async def store_action_info(
+    chat_stream=None,
+    action_build_into_prompt: bool = False,
+    action_prompt_display: str = "",
+    action_done: bool = True,
+    thinking_id: str = "",
+    action_data: Optional[dict] = None,
+    action_name: str = "",
+) -> Optional[Dict[str, Any]]:
+```
+存储动作信息到数据库，是一种针对 Action 的 `db_save()` 的封装函数。
+
+将Action执行的相关信息保存到ActionRecords表中，用于后续的记忆和上下文构建。
+
+**Args:**
+- `chat_stream`: 聊天流对象，包含聊天ID等信息。
+- `action_build_into_prompt`: 是否将动作信息构建到提示中。
+- `action_prompt_display`: 动作提示的显示文本。
+- `action_done`: 动作是否完成。
+- `thinking_id`: 思考过程的ID。
+- `action_data`: 动作的数据字典。
+- `action_name`: 动作的名称。
+
+**Returns:**
+- `Optional[Dict[str, Any]]`: 存储后的记录数据，失败时返回None。
+
+#### 示例
+```python
+record = await database_api.store_action_info(
+    chat_stream=chat_stream,
+    action_build_into_prompt=True,
+    action_prompt_display="执行了回复动作",
+    action_done=True,
+    thinking_id="thinking_123",
+    action_data={"content": "Hello"},
+    action_name="reply_action"
+)
+```

docs/plugins/api/emoji-api.md

@@ -0,0 +1,141 @@
+# 表情包API
+
+表情包API模块提供表情包的获取、查询和管理功能，让插件能够智能地选择和使用表情包。
+
+## 导入方式
+
+```python
+from src.plugin_system.apis import emoji_api
+# 或者
+from src.plugin_system import emoji_api
+```
+
+## 二步走识别优化
+
+从新版本开始，表情包识别系统采用了**二步走识别 + 智能缓存**的优化方案：
+
+### **收到表情包时的识别流程**
+1. **第一步**：VLM视觉分析 - 生成详细描述
+2. **第二步**：LLM情感分析 - 基于详细描述提取核心情感标签
+3. **缓存机制**：将情感标签缓存到数据库，详细描述保存到Images表
+
+### **注册表情包时的优化**
+- **智能复用**：优先从Images表获取已有的详细描述
+- **避免重复**：如果表情包之前被收到过，跳过VLM调用
+- **性能提升**：减少不必要的AI调用，降低延时和成本
+
+### **缓存策略**
+- **ImageDescriptions表**：缓存最终的情感标签（用于快速显示）
+- **Images表**：保存详细描述（用于注册时复用）
+- **双重检查**：防止并发情况下的重复生成
+
+## 主要功能
+
+### 1. 表情包获取
+```python
+async def get_by_description(description: str) -> Optional[Tuple[str, str, str]]:
+```
+根据场景描述选择表情包
+
+**Args：**
+- `description`：表情包的描述文本，例如"开心"、"难过"、"愤怒"等
+
+**Returns：**
+- `Optional[Tuple[str, str, str]]`：一个元组: (表情包的base64编码, 描述, 情感标签)，如果未找到匹配的表情包则返回None
+
+#### 示例
+```python
+emoji_result = await emoji_api.get_by_description("大笑")
+if emoji_result:
+    emoji_base64, description, matched_scene = emoji_result
+    print(f"获取到表情包: {description}, 场景: {matched_scene}")
+    # 可以将emoji_base64用于发送表情包
+```
+
+### 2. 随机获取表情包
+```python
+async def get_random(count: Optional[int] = 1) -> List[Tuple[str, str, str]]:
+```
+随机获取指定数量的表情包
+
+**Args：**
+- `count`：要获取的表情包数量，默认为1
+
+**Returns：**
+- `List[Tuple[str, str, str]]`：一个包含多个表情包的列表，每个元素是一个元组: (表情包的base64编码, 描述, 情感标签)，如果未找到或出错则返回空列表
+
+### 3. 根据情感获取表情包
+```python
+async def get_by_emotion(emotion: str) -> Optional[Tuple[str, str, str]]:
+```
+根据情感标签获取表情包
+
+**Args：**
+- `emotion`：情感标签，例如"开心"、"悲伤"、"愤怒"等
+
+**Returns：**
+- `Optional[Tuple[str, str, str]]`：一个元组: (表情包的base64编码, 描述, 情感标签)，如果未找到则返回None
+
+### 4. 获取表情包数量
+```python
+def get_count() -> int:
+```
+获取当前可用表情包的数量
+
+### 5. 获取表情包系统信息
+```python
+def get_info() -> Dict[str, Any]:
+```
+获取表情包系统的基本信息
+
+**Returns：**
+- `Dict[str, Any]`：包含表情包数量、描述等信息的字典，包含以下键：
+    - `current_count`：当前表情包数量
+    - `max_count`：最大表情包数量
+    - `available_emojis`：当前可用的表情包数量
+
+### 6. 获取所有可用的情感标签
+```python
+def get_emotions() -> List[str]:
+```
+获取所有可用的情感标签 **（已经去重）**
+
+### 7. 获取所有表情包描述
+```python
+def get_descriptions() -> List[str]:
+```
+获取所有表情包的描述列表
+
+## 场景描述说明
+
+### 常用场景描述
+表情包系统支持多种具体的场景描述，举例如下：
+
+- **开心类场景**：开心的大笑、满意的微笑、兴奋的手舞足蹈
+- **无奈类场景**：表示无奈和沮丧、轻微的讽刺、无语的摇头
+- **愤怒类场景**：愤怒和不满、生气的瞪视、暴躁的抓狂
+- **惊讶类场景**：震惊的表情、意外的发现、困惑的思考
+- **可爱类场景**：卖萌的表情、撒娇的动作、害羞的样子
+
+### 情感关键词示例
+系统支持的情感关键词举例如下：
+- 大笑、微笑、兴奋、手舞足蹈
+- 无奈、沮丧、讽刺、无语、摇头
+- 愤怒、不满、生气、瞪视、抓狂
+- 震惊、意外、困惑、思考
+- 卖萌、撒娇、害羞、可爱
+
+### 匹配机制
+- **精确匹配**：优先匹配完整的场景描述，如"开心的大笑"
+- **关键词匹配**：如果没有精确匹配，则根据关键词进行模糊匹配
+- **语义匹配**：系统会理解场景的语义含义进行智能匹配
+
+## 注意事项
+
+1. **异步函数**：部分函数是异步的，需要使用 `await`
+2. **返回格式**：表情包以base64编码返回，可直接用于发送
+3. **错误处理**：所有函数都有错误处理，失败时返回None，空列表或默认值
+4. **使用统计**：系统会记录表情包的使用次数
+5. **文件依赖**：表情包依赖于本地文件，确保表情包文件存在
+6. **编码格式**：返回的是base64编码的图片数据，可直接用于网络传输
+7. **场景理解**：系统能理解具体的场景描述，比简单的情感分类更准确

docs/plugins/api/generator-api.md

@@ -0,0 +1,201 @@
+# 回复生成器API
+
+回复生成器API模块提供智能回复生成功能，让插件能够使用系统的回复生成器来产生自然的聊天回复。
+
+## 导入方式
+
+```python
+from src.plugin_system.apis import generator_api
+# 或者
+from src.plugin_system import generator_api
+```
+
+## 主要功能
+
+### 1. 回复器获取
+```python
+def get_replyer(
+    chat_stream: Optional[ChatStream] = None,
+    chat_id: Optional[str] = None,
+    model_set_with_weight: Optional[List[Tuple[TaskConfig, float]]] = None,
+    request_type: str = "replyer",
+) -> Optional[DefaultReplyer]:
+```
+获取回复器对象
+
+优先使用chat_stream，如果没有则使用chat_id直接查找。
+
+使用 ReplyerManager 来管理实例，避免重复创建。
+
+**Args:**
+- `chat_stream`: 聊天流对象
+- `chat_id`: 聊天ID（实际上就是`stream_id`）
+- `model_set_with_weight`: 模型配置列表，每个元素为 `(TaskConfig, weight)` 元组
+- `request_type`: 请求类型，用于记录LLM使用情况，可以不写
+
+**Returns:**
+- `DefaultReplyer`: 回复器对象，如果获取失败则返回None
+
+#### 示例
+```python
+# 使用聊天流获取回复器
+replyer = generator_api.get_replyer(chat_stream=chat_stream)
+
+# 使用平台和ID获取回复器
+replyer = generator_api.get_replyer(chat_id="123456789")
+```
+
+### 2. 回复生成
+```python
+async def generate_reply(
+    chat_stream: Optional[ChatStream] = None,
+    chat_id: Optional[str] = None,
+    action_data: Optional[Dict[str, Any]] = None,
+    reply_to: str = "",
+    extra_info: str = "",
+    available_actions: Optional[Dict[str, ActionInfo]] = None,
+    enable_tool: bool = False,
+    enable_splitter: bool = True,
+    enable_chinese_typo: bool = True,
+    return_prompt: bool = False,
+    model_set_with_weight: Optional[List[Tuple[TaskConfig, float]]] = None,
+    request_type: str = "generator_api",
+) -> Tuple[bool, List[Tuple[str, Any]], Optional[str]]:
+```
+生成回复
+
+优先使用chat_stream，如果没有则使用chat_id直接查找。
+
+**Args:**
+- `chat_stream`: 聊天流对象
+- `chat_id`: 聊天ID（实际上就是`stream_id`）
+- `action_data`: 动作数据（向下兼容，包含`reply_to`和`extra_info`）
+- `reply_to`: 回复目标，格式为 `{发送者的person_name:消息内容}`
+- `extra_info`: 附加信息
+- `available_actions`: 可用动作字典，格式为 `{"action_name": ActionInfo}`
+- `enable_tool`: 是否启用工具
+- `enable_splitter`: 是否启用分割器
+- `enable_chinese_typo`: 是否启用中文错别字
+- `return_prompt`: 是否返回提示词
+- `model_set_with_weight`: 模型配置列表，每个元素为 `(TaskConfig, weight)` 元组
+- `request_type`: 请求类型（可选，记录LLM使用）
+- `request_type`: 请求类型，用于记录LLM使用情况
+
+**Returns:**
+- `Tuple[bool, List[Tuple[str, Any]], Optional[str]]`: (是否成功, 回复集合, 提示词)
+
+#### 示例
+```python
+success, reply_set, prompt = await generator_api.generate_reply(
+    chat_stream=chat_stream,
+    action_data=action_data,
+    reply_to="麦麦:你好",
+    available_actions=action_info,
+    enable_tool=True,
+    return_prompt=True
+)
+if success:
+    for reply_type, reply_content in reply_set:
+        print(f"回复类型: {reply_type}, 内容: {reply_content}")
+    if prompt:
+        print(f"使用的提示词: {prompt}")
+```
+
+### 3. 回复重写
+```python
+async def rewrite_reply(
+    chat_stream: Optional[ChatStream] = None,
+    reply_data: Optional[Dict[str, Any]] = None,
+    chat_id: Optional[str] = None,
+    enable_splitter: bool = True,
+    enable_chinese_typo: bool = True,
+    model_set_with_weight: Optional[List[Tuple[TaskConfig, float]]] = None,
+    raw_reply: str = "",
+    reason: str = "",
+    reply_to: str = "",
+    return_prompt: bool = False,
+) -> Tuple[bool, List[Tuple[str, Any]], Optional[str]]:
+```
+重写回复，使用新的内容替换旧的回复内容。
+
+优先使用chat_stream，如果没有则使用chat_id直接查找。
+
+**Args:**
+- `chat_stream`: 聊天流对象
+- `reply_data`: 回复数据，包含`raw_reply`, `reason`和`reply_to`，**（向下兼容备用，当其他参数缺失时从此获取）**
+- `chat_id`: 聊天ID（实际上就是`stream_id`）
+- `enable_splitter`: 是否启用分割器
+- `enable_chinese_typo`: 是否启用中文错别字
+- `model_set_with_weight`: 模型配置列表，每个元素为 (TaskConfig, weight) 元组
+- `raw_reply`: 原始回复内容
+- `reason`: 重写原因
+- `reply_to`: 回复目标，格式为 `{发送者的person_name:消息内容}`
+
+**Returns:**
+- `Tuple[bool, List[Tuple[str, Any]], Optional[str]]`: (是否成功, 回复集合, 提示词)
+
+#### 示例
+```python
+success, reply_set, prompt = await generator_api.rewrite_reply(
+    chat_stream=chat_stream,
+    raw_reply="原始回复内容",
+    reason="重写原因",
+    reply_to="麦麦:你好",
+    return_prompt=True
+)
+if success:
+    for reply_type, reply_content in reply_set:
+        print(f"回复类型: {reply_type}, 内容: {reply_content}")
+    if prompt:
+        print(f"使用的提示词: {prompt}")
+```
+
+## 回复集合`reply_set`格式
+
+### 回复类型
+生成的回复集合包含多种类型的回复：
+
+- `"text"`：纯文本回复
+- `"emoji"`：表情包回复
+- `"image"`：图片回复
+- `"mixed"`：混合类型回复
+
+### 回复集合结构
+```python
+# 示例回复集合
+reply_set = [
+    ("text", "很高兴见到你！"),
+    ("emoji", "emoji_base64_data"),
+    ("text", "有什么可以帮助你的吗？")
+]
+```
+
+### 4. 自定义提示词回复
+```python
+async def generate_response_custom(
+    chat_stream: Optional[ChatStream] = None,
+    chat_id: Optional[str] = None,
+    model_set_with_weight: Optional[List[Tuple[TaskConfig, float]]] = None,
+    prompt: str = "",
+) -> Optional[str]:
+```
+生成自定义提示词回复
+
+优先使用chat_stream，如果没有则使用chat_id直接查找。
+
+**Args:**
+- `chat_stream`: 聊天流对象
+- `chat_id`: 聊天ID（备用）
+- `model_set_with_weight`: 模型集合配置列表
+- `prompt`: 自定义提示词
+
+**Returns:**
+- `Optional[str]`: 生成的自定义回复内容，如果生成失败则返回None
+
+## 注意事项
+
+1. **异步操作**：部分函数是异步的，须使用`await`
+2. **聊天流依赖**：需要有效的聊天流对象才能正常工作
+3. **性能考虑**：回复生成可能需要一些时间，特别是使用LLM时
+4. **回复格式**：返回的回复集合是元组列表，包含类型和内容
+5. **上下文感知**：生成器会考虑聊天上下文和历史消息，除非你用的是自定义提示词。

docs/plugins/api/llm-api.md

@@ -0,0 +1,65 @@
+# LLM API
+
+LLM API模块提供与大语言模型交互的功能，让插件能够使用系统配置的LLM模型进行内容生成。
+
+## 导入方式
+
+```python
+from src.plugin_system.apis import llm_api
+# 或者
+from src.plugin_system import llm_api
+```
+
+## 主要功能
+
+### 1. 查询可用模型
+```python
+def get_available_models() -> Dict[str, TaskConfig]:
+```
+获取所有可用的模型配置。
+
+**Return：**
+- `Dict[str, TaskConfig]`：模型配置字典，key为模型名称，value为模型配置对象。
+
+### 2. 使用模型生成内容
+```python
+async def generate_with_model(
+    prompt: str,
+    model_config: TaskConfig,
+    request_type: str = "plugin.generate",
+    temperature: Optional[float] = None,
+    max_tokens: Optional[int] = None,
+) -> Tuple[bool, str, str, str]:
+```
+使用指定模型生成内容。
+
+**Args:**
+- `prompt`：提示词。
+- `model_config`：模型配置对象（从 `get_available_models` 获取）。
+- `request_type`：请求类型标识，默认为 `"plugin.generate"`。
+- `temperature`：生成内容的温度设置，影响输出的随机性。
+- `max_tokens`：生成内容的最大token数。
+
+**Return：**
+- `Tuple[bool, str, str, str]`：返回一个元组，包含（是否成功, 生成的内容, 推理过程, 模型名称）。
+
+### 3. 有Tool情况下使用模型生成内容
+```python
+async def generate_with_model_with_tools(
+    prompt: str,
+    model_config: TaskConfig,
+    tool_options: List[Dict[str, Any]] | None = None,
+    request_type: str = "plugin.generate",
+    temperature: Optional[float] = None,
+    max_tokens: Optional[int] = None,
+) -> Tuple[bool, str, str, str, List[ToolCall] | None]:
+```
+使用指定模型生成内容，并支持工具调用。
+
+**Args:**
+- `prompt`：提示词。
+- `model_config`：模型配置对象（从 `get_available_models` 获取）。
+- `tool_options`：工具选项列表，包含可用工具的配置，字典为每一个工具的定义，参见[tool-components.md](../tool-components.md#属性说明)，可用`tool_api.get_llm_available_tool_definitions()`获取并选择。
+- `request_type`：请求类型标识，默认为 `"plugin.generate"`。
+- `temperature`：生成内容的温度设置，影响输出的随机性。
+- `max_tokens`：生成内容的最大token数。

docs/plugins/api/logging-api.md

@@ -0,0 +1,29 @@
+# Logging API
+
+Logging API模块提供了获取本体logger的功能，允许插件记录日志信息。
+
+## 导入方式
+
+```python
+from src.plugin_system.apis import get_logger
+# 或者
+from src.plugin_system import get_logger
+```
+
+## 主要功能
+### 1. 获取本体logger
+```python
+def get_logger(name: str) -> structlog.stdlib.BoundLogger:
+```
+获取本体logger实例。
+
+**Args:**
+- `name` (str): 日志记录器的名称。
+
+**Returns:**
+- 一个logger实例，有以下方法:
+    - `debug`
+    - `info`
+    - `warning`
+    - `error`
+    - `critical`

docs/plugins/api/message-api.md

@@ -0,0 +1,372 @@
+# 消息API
+
+消息API提供了强大的消息查询、计数和格式化功能，让你轻松处理聊天消息数据。
+
+## 导入方式
+
+```python
+from src.plugin_system.apis import message_api
+# 或者
+from src.plugin_system import message_api
+```
+
+## 功能概述
+
+消息API主要提供三大类功能：
+- **消息查询** - 按时间、聊天、用户等条件查询消息
+- **消息计数** - 统计新消息数量
+- **消息格式化** - 将消息转换为可读格式
+
+## 主要功能
+
+### 1. 按照事件查询消息
+```python
+def get_messages_by_time(
+    start_time: float, end_time: float, limit: int = 0, limit_mode: str = "latest", filter_mai: bool = False
+) -> List[Dict[str, Any]]:
+```
+获取指定时间范围内的消息。
+
+**Args:**
+- `start_time` (float): 开始时间戳
+- `end_time` (float): 结束时间戳
+- `limit` (int): 限制返回消息数量，0为不限制
+- `limit_mode` (str): 限制模式，`"earliest"`获取最早记录，`"latest"`获取最新记录
+- `filter_mai` (bool): 是否过滤掉机器人的消息，默认False
+
+**Returns:**
+- `List[Dict[str, Any]]` - 消息列表
+
+消息列表中包含的键与`Messages`类的属性一致。（位于`src.common.database.database_model`）
+
+### 2. 获取指定聊天中指定时间范围内的信息
+```python
+def get_messages_by_time_in_chat(
+    chat_id: str,
+    start_time: float,
+    end_time: float,
+    limit: int = 0,
+    limit_mode: str = "latest",
+    filter_mai: bool = False,
+) -> List[Dict[str, Any]]:
+```
+获取指定聊天中指定时间范围内的消息。
+
+**Args:**
+- `chat_id` (str): 聊天ID
+- `start_time` (float): 开始时间戳
+- `end_time` (float): 结束时间戳
+- `limit` (int): 限制返回消息数量，0为不限制
+- `limit_mode` (str): 限制模式，`"earliest"`获取最早记录，`"latest"`获取最新记录
+- `filter_mai` (bool): 是否过滤掉机器人的消息，默认False
+
+**Returns:**
+- `List[Dict[str, Any]]` - 消息列表
+
+
+### 3. 获取指定聊天中指定时间范围内的信息（包含边界）
+```python
+def get_messages_by_time_in_chat_inclusive(
+    chat_id: str,
+    start_time: float,
+    end_time: float,
+    limit: int = 0,
+    limit_mode: str = "latest",
+    filter_mai: bool = False,
+    filter_command: bool = False,
+) -> List[Dict[str, Any]]:
+```
+获取指定聊天中指定时间范围内的消息（包含边界）。
+
+**Args:**
+- `chat_id` (str): 聊天ID
+- `start_time` (float): 开始时间戳（包含）
+- `end_time` (float): 结束时间戳（包含）
+- `limit` (int): 限制返回消息数量，0为不限制
+- `limit_mode` (str): 限制模式，`"earliest"`获取最早记录，`"latest"`获取最新记录
+- `filter_mai` (bool): 是否过滤掉机器人的消息，默认False
+- `filter_command` (bool): 是否过滤命令消息，默认False
+
+**Returns:**
+- `List[Dict[str, Any]]` - 消息列表
+
+
+### 4. 获取指定聊天中指定用户在指定时间范围内的消息
+```python
+def get_messages_by_time_in_chat_for_users(
+    chat_id: str,
+    start_time: float,
+    end_time: float,
+    person_ids: List[str],
+    limit: int = 0,
+    limit_mode: str = "latest",
+) -> List[Dict[str, Any]]:
+```
+获取指定聊天中指定用户在指定时间范围内的消息。
+
+**Args:**
+- `chat_id` (str): 聊天ID
+- `start_time` (float): 开始时间戳
+- `end_time` (float): 结束时间戳
+- `person_ids` (List[str]): 用户ID列表
+- `limit` (int): 限制返回消息数量，0为不限制
+- `limit_mode` (str): 限制模式，`"earliest"`获取最早记录，`"latest"`获取最新记录
+
+**Returns:**
+- `List[Dict[str, Any]]` - 消息列表
+
+
+### 5. 随机选择一个聊天，返回该聊天在指定时间范围内的消息
+```python
+def get_random_chat_messages(
+    start_time: float,
+    end_time: float,
+    limit: int = 0,
+    limit_mode: str = "latest",
+    filter_mai: bool = False,
+) -> List[Dict[str, Any]]:
+```
+随机选择一个聊天，返回该聊天在指定时间范围内的消息。
+
+**Args:**
+- `start_time` (float): 开始时间戳
+- `end_time` (float): 结束时间戳
+- `limit` (int): 限制返回消息数量，0为不限制
+- `limit_mode` (str): 限制模式，`"earliest"`获取最早记录，`"latest"`获取最新记录
+- `filter_mai` (bool): 是否过滤掉机器人的消息，默认False
+
+**Returns:**
+- `List[Dict[str, Any]]` - 消息列表
+
+
+### 6. 获取指定用户在所有聊天中指定时间范围内的消息
+```python
+def get_messages_by_time_for_users(
+    start_time: float,
+    end_time: float,
+    person_ids: List[str],
+    limit: int = 0,
+    limit_mode: str = "latest",
+) -> List[Dict[str, Any]]:
+```
+获取指定用户在所有聊天中指定时间范围内的消息。
+
+**Args:**
+- `start_time` (float): 开始时间戳
+- `end_time` (float): 结束时间戳
+- `person_ids` (List[str]): 用户ID列表
+- `limit` (int): 限制返回消息数量，0为不限制
+- `limit_mode` (str): 限制模式，`"earliest"`获取最早记录，`"latest"`获取最新记录
+
+**Returns:**
+- `List[Dict[str, Any]]` - 消息列表
+
+
+### 7. 获取指定时间戳之前的消息
+```python
+def get_messages_before_time(
+    timestamp: float,
+    limit: int = 0,
+    filter_mai: bool = False,
+) -> List[Dict[str, Any]]:
+```
+获取指定时间戳之前的消息。
+
+**Args:**
+- `timestamp` (float): 时间戳
+- `limit` (int): 限制返回消息数量，0为不限制
+- `filter_mai` (bool): 是否过滤掉机器人的消息，默认False
+
+**Returns:**
+- `List[Dict[str, Any]]` - 消息列表
+
+
+### 8. 获取指定聊天中指定时间戳之前的消息
+```python
+def get_messages_before_time_in_chat(
+    chat_id: str,
+    timestamp: float,
+    limit: int = 0,
+    filter_mai: bool = False,
+) -> List[Dict[str, Any]]:
+```
+获取指定聊天中指定时间戳之前的消息。
+
+**Args:**
+- `chat_id` (str): 聊天ID
+- `timestamp` (float): 时间戳
+- `limit` (int): 限制返回消息数量，0为不限制
+- `filter_mai` (bool): 是否过滤掉机器人的消息，默认False
+
+**Returns:**
+- `List[Dict[str, Any]]` - 消息列表
+
+
+### 9. 获取指定用户在指定时间戳之前的消息
+```python
+def get_messages_before_time_for_users(
+    timestamp: float,
+    person_ids: List[str],
+    limit: int = 0,
+) -> List[Dict[str, Any]]:
+```
+获取指定用户在指定时间戳之前的消息。
+
+**Args:**
+- `timestamp` (float): 时间戳
+- `person_ids` (List[str]): 用户ID列表
+- `limit` (int): 限制返回消息数量，0为不限制
+
+**Returns:**
+- `List[Dict[str, Any]]` - 消息列表
+
+
+### 10. 获取指定聊天中最近一段时间的消息
+```python
+def get_recent_messages(
+    chat_id: str,
+    hours: float = 24.0,
+    limit: int = 100,
+    limit_mode: str = "latest",
+    filter_mai: bool = False,
+) -> List[Dict[str, Any]]:
+```
+获取指定聊天中最近一段时间的消息。
+
+**Args:**
+- `chat_id` (str): 聊天ID
+- `hours` (float): 最近多少小时，默认24小时
+- `limit` (int): 限制返回消息数量，默认100条
+- `limit_mode` (str): 限制模式，`"earliest"`获取最早记录，`"latest"`获取最新记录
+- `filter_mai` (bool): 是否过滤掉机器人的消息，默认False
+
+**Returns:**
+- `List[Dict[str, Any]]` - 消息列表
+
+
+### 11. 计算指定聊天中从开始时间到结束时间的新消息数量
+```python
+def count_new_messages(
+    chat_id: str,
+    start_time: float = 0.0,
+    end_time: Optional[float] = None,
+) -> int:
+```
+计算指定聊天中从开始时间到结束时间的新消息数量。
+
+**Args:**
+- `chat_id` (str): 聊天ID
+- `start_time` (float): 开始时间戳
+- `end_time` (Optional[float]): 结束时间戳，如果为None则使用当前时间
+
+**Returns:**
+- `int` - 新消息数量
+
+
+### 12. 计算指定聊天中指定用户从开始时间到结束时间的新消息数量
+```python
+def count_new_messages_for_users(
+    chat_id: str,
+    start_time: float,
+    end_time: float,
+    person_ids: List[str],
+) -> int:
+```
+计算指定聊天中指定用户从开始时间到结束时间的新消息数量。
+
+**Args:**
+- `chat_id` (str): 聊天ID
+- `start_time` (float): 开始时间戳
+- `end_time` (float): 结束时间戳
+- `person_ids` (List[str]): 用户ID列表
+
+**Returns:**
+- `int` - 新消息数量
+
+
+### 13. 将消息列表构建成可读的字符串
+```python
+def build_readable_messages_to_str(
+    messages: List[Dict[str, Any]],
+    replace_bot_name: bool = True,
+    merge_messages: bool = False,
+    timestamp_mode: str = "relative",
+    read_mark: float = 0.0,
+    truncate: bool = False,
+    show_actions: bool = False,
+) -> str:
+```
+将消息列表构建成可读的字符串。
+
+**Args:**
+- `messages` (List[Dict[str, Any]]): 消息列表
+- `replace_bot_name` (bool): 是否将机器人的名称替换为"你"
+- `merge_messages` (bool): 是否合并连续消息
+- `timestamp_mode` (str): 时间戳显示模式，`"relative"`或`"absolute"`
+- `read_mark` (float): 已读标记时间戳，用于分割已读和未读消息
+- `truncate` (bool): 是否截断长消息
+- `show_actions` (bool): 是否显示动作记录
+
+**Returns:**
+- `str` - 格式化后的可读字符串
+
+
+### 14. 将消息列表构建成可读的字符串，并返回详细信息
+```python
+async def build_readable_messages_with_details(
+    messages: List[Dict[str, Any]],
+    replace_bot_name: bool = True,
+    merge_messages: bool = False,
+    timestamp_mode: str = "relative",
+    truncate: bool = False,
+) -> Tuple[str, List[Tuple[float, str, str]]]:
+```
+将消息列表构建成可读的字符串，并返回详细信息。
+
+**Args:**
+- `messages` (List[Dict[str, Any]]): 消息列表
+- `replace_bot_name` (bool): 是否将机器人的名称替换为"你"
+- `merge_messages` (bool): 是否合并连续消息
+- `timestamp_mode` (str): 时间戳显示模式，`"relative"`或`"absolute"`
+- `truncate` (bool): 是否截断长消息
+
+**Returns:**
+- `Tuple[str, List[Tuple[float, str, str]]]` - 格式化后的可读字符串和详细信息元组列表(时间戳, 昵称, 内容)
+
+
+### 15. 从消息列表中提取不重复的用户ID列表
+```python
+async def get_person_ids_from_messages(
+    messages: List[Dict[str, Any]],
+) -> List[str]:
+```
+从消息列表中提取不重复的用户ID列表。
+
+**Args:**
+- `messages` (List[Dict[str, Any]]): 消息列表
+
+**Returns:**
+- `List[str]` - 用户ID列表
+
+
+### 16. 从消息列表中移除机器人的消息
+```python
+def filter_mai_messages(
+    messages: List[Dict[str, Any]],
+) -> List[Dict[str, Any]]:
+```
+从消息列表中移除机器人的消息。
+
+**Args:**
+- `messages` (List[Dict[str, Any]]): 消息列表，每个元素是消息字典
+
+**Returns:**
+- `List[Dict[str, Any]]` - 过滤后的消息列表
+
+## 注意事项
+
+1. **时间戳格式**：所有时间参数都使用Unix时间戳（float类型）
+2. **异步函数**：部分函数是异步函数，需要使用 `await`
+3. **性能考虑**：查询大量消息时建议设置合理的 `limit` 参数
+4. **消息格式**：返回的消息是字典格式，包含时间戳、发送者、内容等信息
+5. **用户ID**：`person_ids` 参数接受字符串列表，用于筛选特定用户的消息 

docs/plugins/api/person-api.md

@@ -0,0 +1,119 @@
+# 个人信息API
+
+个人信息API模块提供用户信息查询和管理功能，让插件能够获取和使用用户的相关信息。
+
+## 导入方式
+
+```python
+from src.plugin_system.apis import person_api
+# 或者
+from src.plugin_system import person_api
+```
+
+## 主要功能
+
+### 1. Person ID 获取
+```python
+def get_person_id(platform: str, user_id: int) -> str:
+```
+根据平台和用户ID获取person_id
+
+**Args:**
+- `platform`：平台名称，如 "qq", "telegram" 等
+- `user_id`：用户ID
+
+**Returns:**
+- `str`：唯一的person_id（MD5哈希值）
+
+#### 示例
+```python
+person_id = person_api.get_person_id("qq", 123456)
+```
+
+### 2. 用户信息查询
+```python
+async def get_person_value(person_id: str, field_name: str, default: Any = None) -> Any:
+```
+查询单个用户信息字段值
+
+**Args:**
+- `person_id`：用户的唯一标识ID
+- `field_name`：要获取的字段名
+- `default`：字段值不存在时的默认值
+
+**Returns:**
+- `Any`：字段值或默认值
+
+#### 示例
+```python
+nickname = await person_api.get_person_value(person_id, "nickname", "未知用户")
+impression = await person_api.get_person_value(person_id, "impression")
+```
+
+### 3. 批量用户信息查询
+```python
+async def get_person_values(person_id: str, field_names: list, default_dict: Optional[dict] = None) -> dict:
+```
+批量获取用户信息字段值
+
+**Args:**
+- `person_id`：用户的唯一标识ID
+- `field_names`：要获取的字段名列表
+- `default_dict`：默认值字典，键为字段名，值为默认值
+
+**Returns:**
+- `dict`：字段名到值的映射字典
+
+#### 示例
+```python
+values = await person_api.get_person_values(
+    person_id,
+    ["nickname", "impression", "know_times"],
+    {"nickname": "未知用户", "know_times": 0}
+)
+```
+
+### 4. 判断用户是否已知
+```python
+async def is_person_known(platform: str, user_id: int) -> bool:
+```
+判断是否认识某个用户
+
+**Args:**
+- `platform`：平台名称
+- `user_id`：用户ID
+
+**Returns:**
+- `bool`：是否认识该用户
+
+### 5. 根据用户名获取Person ID
+```python
+def get_person_id_by_name(person_name: str) -> str:
+```
+根据用户名获取person_id
+
+**Args:**
+- `person_name`：用户名
+
+**Returns:**
+- `str`：person_id，如果未找到返回空字符串
+
+## 常用字段说明
+
+### 基础信息字段
+- `nickname`：用户昵称
+- `platform`：平台信息
+- `user_id`：用户ID
+
+### 关系信息字段
+- `impression`：对用户的印象
+- `points`: 用户特征点
+
+其他字段可以参考`PersonInfo`类的属性（位于`src.common.database.database_model`）
+
+## 注意事项
+
+1. **异步操作**：部分查询函数都是异步的，需要使用`await`
+2. **性能考虑**：批量查询优于单个查询
+3. **隐私保护**：确保用户信息的使用符合隐私政策
+4. **数据一致性**：person_id是用户的唯一标识，应妥善保存和使用

docs/plugins/api/plugin-manage-api.md

@@ -0,0 +1,105 @@
+# 插件管理API
+
+插件管理API模块提供了对插件的加载、卸载、重新加载以及目录管理功能。
+
+## 导入方式
+```python
+from src.plugin_system.apis import plugin_manage_api
+# 或者
+from src.plugin_system import plugin_manage_api
+```
+
+## 功能概述
+
+插件管理API主要提供以下功能：
+- **插件查询** - 列出当前加载的插件或已注册的插件。
+- **插件管理** - 加载、卸载、重新加载插件。
+- **插件目录管理** - 添加插件目录并重新扫描。
+
+## 主要功能
+
+### 1. 列出当前加载的插件
+```python
+def list_loaded_plugins() -> List[str]:
+```
+列出所有当前加载的插件。
+
+**Returns:**
+- `List[str]` - 当前加载的插件名称列表。
+
+### 2. 列出所有已注册的插件
+```python
+def list_registered_plugins() -> List[str]:
+```
+列出所有已注册的插件。
+
+**Returns:**
+- `List[str]` - 已注册的插件名称列表。
+
+### 3. 获取插件路径
+```python
+def get_plugin_path(plugin_name: str) -> str:
+```
+获取指定插件的路径。
+
+**Args:**
+- `plugin_name` (str): 要查询的插件名称。
+**Returns:**
+- `str` - 插件的路径，如果插件不存在则 raise ValueError。
+
+### 4. 卸载指定的插件
+```python
+async def remove_plugin(plugin_name: str) -> bool:
+```
+卸载指定的插件。
+
+**Args:**
+- `plugin_name` (str): 要卸载的插件名称。
+
+**Returns:**
+- `bool` - 卸载是否成功。
+
+### 5. 重新加载指定的插件
+```python
+async def reload_plugin(plugin_name: str) -> bool:
+```
+重新加载指定的插件。
+
+**Args:**
+- `plugin_name` (str): 要重新加载的插件名称。
+
+**Returns:**
+- `bool` - 重新加载是否成功。
+
+### 6. 加载指定的插件
+```python
+def load_plugin(plugin_name: str) -> Tuple[bool, int]:
+```
+加载指定的插件。
+
+**Args:**
+- `plugin_name` (str): 要加载的插件名称。
+
+**Returns:**
+- `Tuple[bool, int]` - 加载是否成功，成功或失败的个数。
+
+### 7. 添加插件目录
+```python
+def add_plugin_directory(plugin_directory: str) -> bool:
+```
+添加插件目录。
+
+**Args:**
+- `plugin_directory` (str): 要添加的插件目录路径。
+
+**Returns:**
+- `bool` - 添加是否成功。
+
+### 8. 重新扫描插件目录
+```python
+def rescan_plugin_directory() -> Tuple[int, int]:
+```
+重新扫描插件目录，加载新插件。
+
+**Returns:**
+- `Tuple[int, int]` - 成功加载的插件数量和失败的插件数量。

docs/plugins/api/send-api.md

@@ -0,0 +1,175 @@
+# 消息发送API
+
+消息发送API模块专门负责发送各种类型的消息，支持文本、表情包、图片等多种消息类型。
+
+## 导入方式
+
+```python
+from src.plugin_system.apis import send_api
+# 或者
+from src.plugin_system import send_api
+```
+
+## 主要功能
+
+### 1. 发送文本消息
+```python
+async def text_to_stream(
+    text: str,
+    stream_id: str,
+    typing: bool = False,
+    reply_to: str = "",
+    storage_message: bool = True,
+) -> bool:
+```
+发送文本消息到指定的流
+
+**Args:**
+- `text` (str): 要发送的文本内容
+- `stream_id` (str): 聊天流ID
+- `typing` (bool): 是否显示正在输入
+- `reply_to` (str): 回复消息，格式为"发送者:消息内容"
+- `storage_message` (bool): 是否存储消息到数据库
+
+**Returns:**
+- `bool` - 是否发送成功
+
+### 2. 发送表情包
+```python
+async def emoji_to_stream(emoji_base64: str, stream_id: str, storage_message: bool = True) -> bool:
+```
+向指定流发送表情包。
+
+**Args:**
+- `emoji_base64` (str): 表情包的base64编码
+- `stream_id` (str): 聊天流ID
+- `storage_message` (bool): 是否存储消息到数据库
+
+**Returns:**
+- `bool` - 是否发送成功
+
+### 3. 发送图片
+```python
+async def image_to_stream(image_base64: str, stream_id: str, storage_message: bool = True) -> bool:
+```
+向指定流发送图片。
+
+**Args:**
+- `image_base64` (str): 图片的base64编码
+- `stream_id` (str): 聊天流ID
+- `storage_message` (bool): 是否存储消息到数据库
+
+**Returns:**
+- `bool` - 是否发送成功
+
+### 4. 发送命令
+```python
+async def command_to_stream(command: Union[str, dict], stream_id: str, storage_message: bool = True, display_message: str = "") -> bool:
+```
+向指定流发送命令。
+
+**Args:**
+- `command` (Union[str, dict]): 命令内容
+- `stream_id` (str): 聊天流ID
+- `storage_message` (bool): 是否存储消息到数据库
+- `display_message` (str): 显示消息
+
+**Returns:**
+- `bool` - 是否发送成功
+
+### 5. 发送自定义类型消息
+```python
+async def custom_to_stream(
+    message_type: str,
+    content: str,
+    stream_id: str,
+    display_message: str = "",
+    typing: bool = False,
+    reply_to: str = "",
+    storage_message: bool = True,
+    show_log: bool = True,
+) -> bool:
+```
+向指定流发送自定义类型消息。
+
+**Args:**
+- `message_type` (str): 消息类型，如"text"、"image"、"emoji"、"video"、"file"等
+- `content` (str): 消息内容（通常是base64编码或文本）
+- `stream_id` (str): 聊天流ID
+- `display_message` (str): 显示消息
+- `typing` (bool): 是否显示正在输入
+- `reply_to` (str): 回复消息，格式为"发送者:消息内容"
+- `storage_message` (bool): 是否存储消息到数据库
+- `show_log` (bool): 是否显示日志
+
+**Returns:**
+- `bool` - 是否发送成功
+
+## 使用示例
+
+### 1. 基础文本发送，并回复消息
+
+```python
+from src.plugin_system.apis import send_api
+
+async def send_hello(chat_stream):
+    """发送问候消息"""
+    
+    success = await send_api.text_to_stream(
+        text="Hello, world!",
+        stream_id=chat_stream.stream_id,
+        typing=True,
+        reply_to="User:How are you?",
+        storage_message=True
+    )
+    
+    return success
+```
+
+### 2. 发送表情包
+
+```python
+from src.plugin_system.apis import emoji_api
+async def send_emoji_reaction(chat_stream, emotion):
+    """根据情感发送表情包"""
+    # 获取表情包
+    emoji_result = await emoji_api.get_by_emotion(emotion)
+    if not emoji_result:
+        return False
+    
+    emoji_base64, description, matched_emotion = emoji_result
+    
+    # 发送表情包
+    success = await send_api.emoji_to_stream(
+        emoji_base64=emoji_base64,
+        stream_id=chat_stream.stream_id,
+        storage_message=False # 不存储到数据库
+    )
+    
+    return success
+```
+
+## 消息类型说明
+
+### 支持的消息类型
+- `"text"`：纯文本消息
+- `"emoji"`：表情包消息
+- `"image"`：图片消息
+- `"command"`：命令消息
+- `"video"`：视频消息（如果支持）
+- `"audio"`：音频消息（如果支持）
+
+### 回复格式
+回复消息使用格式：`"发送者:消息内容"` 或 `"发送者：消息内容"`
+
+系统会自动查找匹配的原始消息并进行回复。
+
+## 注意事项
+
+1. **异步操作**：所有发送函数都是异步的，必须使用`await`
+2. **错误处理**：发送失败时返回False，成功时返回True
+3. **发送频率**：注意控制发送频率，避免被平台限制
+4. **内容限制**：注意平台对消息内容和长度的限制
+5. **权限检查**：确保机器人有发送消息的权限
+6. **编码格式**：图片和表情包需要使用base64编码
+7. **存储选项**：可以选择是否将发送的消息存储到数据库 

docs/plugins/api/tool-api.md

@@ -0,0 +1,55 @@
+# 工具API
+
+工具API模块提供了获取和管理工具实例的功能，让插件能够访问系统中注册的工具。
+
+## 导入方式
+
+```python
+from src.plugin_system.apis import tool_api
+# 或者
+from src.plugin_system import tool_api
+```
+
+## 主要功能
+
+### 1. 获取工具实例
+
+```python
+def get_tool_instance(tool_name: str) -> Optional[BaseTool]:
+```
+
+获取指定名称的工具实例。
+
+**Args**:
+- `tool_name`: 工具名称字符串
+
+**Returns**:
+- `Optional[BaseTool]`: 工具实例，如果工具不存在则返回 None
+
+### 2. 获取LLM可用的工具定义
+
+```python
+def get_llm_available_tool_definitions():
+```
+
+获取所有LLM可用的工具定义列表。
+
+**Returns**:
+- `List[Tuple[str, Dict[str, Any]]]`: 工具定义列表，每个元素为 `(工具名称, 工具定义字典)` 的元组
+  - 其具体定义请参照[tool-components.md](../tool-components.md#属性说明)中的工具定义格式。
+#### 示例：
+
+```python
+# 获取所有LLM可用的工具定义
+tools = tool_api.get_llm_available_tool_definitions()
+for tool_name, tool_definition in tools:
+    print(f"工具: {tool_name}")
+    print(f"定义: {tool_definition}")
+```
+
+## 注意事项
+
+1. **工具存在性检查**：使用前请检查工具实例是否为 None
+2. **权限控制**：某些工具可能有使用权限限制
+3. **异步调用**：大多数工具方法是异步的，需要使用 await
+4. **错误处理**：调用工具时请做好异常处理

docs/plugins/command-components.md

@@ -0,0 +1,89 @@
+# 💻 Command组件详解
+
+## 📖 什么是Command
+
+Command是直接响应用户明确指令的组件，与Action不同，Command是**被动触发**的，当用户输入特定格式的命令时立即执行。
+
+Command通过正则表达式匹配用户输入，提供确定性的功能服务。
+
+### 🎯 Command的特点
+
+- 🎯 **确定性执行**：匹配到命令立即执行，无随机性
+- ⚡ **即时响应**：用户主动触发，快速响应
+- 🔍 **正则匹配**：通过正则表达式精确匹配用户输入
+- 🛑 **拦截控制**：可以控制是否阻止消息继续处理
+- 📝 **参数解析**：支持从用户输入中提取参数
+
+---
+
+## 🛠️ Command组件的基本结构
+
+首先，Command组件需要继承自`BaseCommand`类，并实现必要的方法。
+
+```python
+class ExampleCommand(BaseCommand):
+    command_name = "example" # 命令名称，作为唯一标识符
+    command_description = "这是一个示例命令" # 命令描述
+    command_pattern = r"" # 命令匹配的正则表达式
+
+    async def execute(self) -> Tuple[bool, Optional[str], bool]:
+        """
+        执行Command的主要逻辑
+
+        Returns:
+            Tuple[bool, str, bool]: 
+                - 第一个bool表示是否成功执行
+                - 第二个str是执行结果消息
+                - 第三个bool表示是否需要阻止消息继续处理
+        """
+        # ---- 执行命令的逻辑 ----
+        return True, "执行成功", False
+```
+**`command_pattern`**: 该Command匹配的正则表达式，用于精确匹配用户输入。
+
+请注意：如果希望能获取到命令中的参数，请在正则表达式中使用有命名的捕获组，例如`(?P<param_name>pattern)`。
+
+这样在匹配时，内部实现可以使用`re.match.groupdict()`方法获取到所有捕获组的参数，并以字典的形式存储在`self.matched_groups`中。
+
+### 匹配样例
+假设我们有一个命令`/example param1=value1 param2=value2`，对应的正则表达式可以是：
+
+```python
+class ExampleCommand(BaseCommand):
+    command_name = "example"
+    command_description = "这是一个示例命令"
+    command_pattern = r"/example (?P<param1>\w+) (?P<param2>\w+)"
+
+    async def execute(self) -> Tuple[bool, Optional[str], bool]:
+        # 获取匹配的参数
+        param1 = self.matched_groups.get("param1")
+        param2 = self.matched_groups.get("param2")
+        
+        # 执行逻辑
+        return True, f"参数1: {param1}, 参数2: {param2}", False
+```
+
+---
+
+## Command 内置方法说明
+```python
+class BaseCommand:
+    def get_config(self, key: str, default=None):
+        """获取插件配置值，使用嵌套键访问"""
+
+    async def send_text(self, content: str, reply_to: str = "") -> bool:
+        """发送回复消息"""
+
+    async def send_type(self, message_type: str, content: str, display_message: str = "", typing: bool = False, reply_to: str = "") -> bool:
+        """发送指定类型的回复消息到当前聊天环境"""
+
+    async def send_command(self, command_name: str, args: Optional[dict] = None, display_message: str = "", storage_message: bool = True) -> bool:
+        """发送命令消息"""
+
+    async def send_emoji(self, emoji_base64: str) -> bool:
+        """发送表情包"""
+
+    async def send_image(self, image_base64: str) -> bool:
+        """发送图片"""
+```
+具体参数与用法参见`BaseCommand`基类的定义。

docs/plugins/configuration-guide.md

@@ -0,0 +1,347 @@
+# ⚙️ 插件配置完整指南
+
+本文档将全面指导你如何为你的插件**定义配置**和在组件中**访问配置**，帮助你构建一个健壮、规范且自带文档的配置系统。
+
+> **🚨 重要原则：任何时候都不要手动创建 config.toml 文件！**
+>
+> 系统会根据你在代码中定义的 `config_schema` 自动生成配置文件。手动创建配置文件会破坏自动化流程，导致配置不一致、缺失注释和文档等问题。
+
+## 配置版本管理
+
+### 🎯 版本管理概述
+
+插件系统提供了强大的**配置版本管理机制**，可以在插件升级时自动处理配置文件的迁移和更新，确保配置结构始终与代码保持同步。
+
+### 🔄 配置版本管理工作流程
+
+```mermaid
+graph TD
+    A[插件加载] --> B[检查配置文件]
+    B --> C{配置文件存在?}
+    C -->|不存在| D[生成默认配置]
+    C -->|存在| E[读取当前版本]
+    E --> F{有版本信息?}
+    F -->|无版本| G[跳过版本检查<br/>直接加载配置]
+    F -->|有版本| H{版本匹配?}
+    H -->|匹配| I[直接加载配置]
+    H -->|不匹配| J[配置迁移]
+    J --> K[生成新配置结构]
+    K --> L[迁移旧配置值]
+    L --> M[保存迁移后配置]
+    M --> N[配置加载完成]
+    D --> N
+    G --> N
+    I --> N
+    
+    style J fill:#FFB6C1
+    style K fill:#90EE90
+    style G fill:#87CEEB
+    style N fill:#DDA0DD
+```
+
+### 📊 版本管理策略
+
+#### 1. 配置版本定义
+
+在 `config_schema` 的 `plugin` 节中定义 `config_version`：
+
+```python
+config_schema = {
+    "plugin": {
+        "enabled": ConfigField(type=bool, default=False, description="是否启用插件"),
+        "config_version": ConfigField(type=str, default="1.2.0", description="配置文件版本"),
+    },
+    # 其他配置...
+}
+```
+
+#### 2. 版本检查行为
+
+- **无版本信息** (`config_version` 不存在)
+  - 系统会**跳过版本检查**，直接加载现有配置
+  - 适用于旧版本插件的兼容性处理
+  - 日志显示：`配置文件无版本信息，跳过版本检查`
+
+- **有版本信息** (存在 `config_version` 字段)
+  - 比较当前版本与期望版本
+  - 版本不匹配时自动执行配置迁移
+  - 版本匹配时直接加载配置
+
+#### 3. 配置迁移过程
+
+当检测到版本不匹配时，系统会：
+
+1. **生成新配置结构** - 根据最新的 `config_schema` 生成新的配置结构
+2. **迁移配置值** - 将旧配置文件中的值迁移到新结构中
+3. **处理新增字段** - 新增的配置项使用默认值
+4. **更新版本号** - `config_version` 字段自动更新为最新版本
+5. **保存配置文件** - 迁移后的配置直接覆盖原文件**（不保留备份）**
+
+### 🔧 实际使用示例
+
+#### 版本升级场景
+
+假设你的插件从 v1.0 升级到 v1.1，新增了权限管理功能：
+
+**旧版本配置 (v1.0.0):**
+```toml
+[plugin]
+enabled = true
+config_version = "1.0.0"
+
+[mute]
+min_duration = 60
+max_duration = 3600
+```
+
+**新版本Schema (v1.1.0):**
+```python
+config_schema = {
+    "plugin": {
+        "enabled": ConfigField(type=bool, default=False, description="是否启用插件"),
+        "config_version": ConfigField(type=str, default="1.1.0", description="配置文件版本"),
+    },
+    "mute": {
+        "min_duration": ConfigField(type=int, default=60, description="最短禁言时长（秒）"),
+        "max_duration": ConfigField(type=int, default=2592000, description="最长禁言时长（秒）"),
+    },
+    "permissions": {  # 新增的配置节
+        "allowed_users": ConfigField(type=list, default=[], description="允许的用户列表"),
+        "allowed_groups": ConfigField(type=list, default=[], description="允许的群组列表"),
+    }
+}
+```
+
+**迁移后配置 (v1.1.0):**
+```toml
+[plugin]
+enabled = true  # 保留原值
+config_version = "1.1.0"  # 自动更新
+
+[mute]
+min_duration = 60  # 保留原值
+max_duration = 3600  # 保留原值
+
+[permissions]  # 新增节，使用默认值
+allowed_users = []
+allowed_groups = []
+```
+
+#### 无版本配置的兼容性
+
+对于没有版本信息的旧配置文件：
+
+**旧配置文件（无版本）:**
+```toml
+[plugin]
+enabled = true
+# 没有 config_version 字段
+
+[mute]
+min_duration = 120
+```
+
+**系统行为:**
+- 检测到无版本信息
+- 跳过版本检查和迁移
+- 直接加载现有配置
+- 新增的配置项在代码中使用默认值访问
+- 系统会详细记录配置迁移过程。
+
+### ⚠️ 重要注意事项
+
+#### 1. 版本号管理
+- 当你修改 `config_schema` 时，**必须同步更新** `config_version`
+- 请使用语义化版本号 (例如：`1.0.0`, `1.1.0`, `2.0.0`)
+
+#### 2. 迁移策略
+- **保留原值优先**: 迁移时优先保留用户的原有配置值
+- **新增字段默认值**: 新增的配置项使用Schema中定义的默认值
+- **移除字段警告**: 如果某个配置项在新版本中被移除，会在日志中显示警告
+
+#### 3. 兼容性考虑
+- **旧版本兼容**: 无版本信息的配置文件会跳过版本检查
+- **不保留备份**: 迁移后直接覆盖原配置文件，不保留备份
+- **失败安全**: 如果迁移过程中出现错误，会回退到原配置
+
+## 配置定义
+
+配置的定义在你的插件主类（继承自 `BasePlugin`）中完成，主要通过两个类属性：
+
+1.  `config_section_descriptions`: 一个字典，用于描述配置文件的各个区段（`[section]`）。
+2.  `config_schema`: 核心部分，一个嵌套字典，用于定义每个区段下的具体配置项。
+
+### `ConfigField`：配置项的基石
+
+每个配置项都通过一个 `ConfigField` 对象来定义。
+
+```python
+from dataclasses import dataclass
+from src.plugin_system.base.config_types import ConfigField
+
+@dataclass
+class ConfigField:
+    """配置字段定义"""
+    type: type          # 字段类型 (例如 str, int, float, bool, list)
+    default: Any        # 默认值
+    description: str    # 字段描述 (将作为注释生成到配置文件中)
+    example: Optional[str] = None       # 示例值 (可选)
+    required: bool = False              # 是否必需 (可选, 主要用于文档提示)
+    choices: Optional[List[Any]] = None # 可选值列表 (可选)
+```
+
+### 配置示例
+
+让我们以一个功能丰富的 `MutePlugin` 为例，看看如何定义它的配置。
+
+```python
+# src/plugins/built_in/mute_plugin/plugin.py
+
+from src.plugin_system import BasePlugin, register_plugin, ConfigField
+from typing import List, Tuple, Type
+
+@register_plugin
+class MutePlugin(BasePlugin):
+    """禁言插件"""
+
+    # 这里是插件基本信息，略去
+
+    # 步骤1: 定义配置节的描述
+    config_section_descriptions = {
+        "plugin": "插件启用配置",
+        "components": "组件启用控制",
+        "mute": "核心禁言功能配置",
+        "smart_mute": "智能禁言Action的专属配置",
+        "logging": "日志记录相关配置"
+    }
+
+    # 步骤2: 使用ConfigField定义详细的配置Schema
+    config_schema = {
+        "plugin": {
+            "enabled": ConfigField(type=bool, default=False, description="是否启用插件")
+        },
+        "components": {
+            "enable_smart_mute": ConfigField(type=bool, default=True, description="是否启用智能禁言Action"),
+            "enable_mute_command": ConfigField(type=bool, default=False, description="是否启用禁言命令Command")
+        },
+        "mute": {
+            "min_duration": ConfigField(type=int, default=60, description="最短禁言时长（秒）"),
+            "max_duration": ConfigField(type=int, default=2592000, description="最长禁言时长（秒），默认30天"),
+            "templates": ConfigField(
+                type=list,
+                default=["好的，禁言 {target} {duration}，理由：{reason}", "收到，对 {target} 执行禁言 {duration}"],
+                description="成功禁言后发送的随机消息模板"
+            )
+        },
+        "smart_mute": {
+            "keyword_sensitivity": ConfigField(
+                type=str,
+                default="normal",
+                description="关键词激活的敏感度",
+                choices=["low", "normal", "high"] # 定义可选值
+            ),
+        },
+        "logging": {
+            "level": ConfigField(
+                type=str,
+                default="INFO",
+                description="日志记录级别",
+                choices=["DEBUG", "INFO", "WARNING", "ERROR"]
+            ),
+            "prefix": ConfigField(type=str, default="[MutePlugin]", description="日志记录前缀", example="[MyMutePlugin]")
+        }
+    }
+
+    # 这里是插件方法，略去
+```
+
+当 `mute_plugin` 首次加载且其目录中不存在 `config.toml` 时，系统会自动创建以下文件：
+
+```toml
+# mute_plugin - 自动生成的配置文件
+# 群聊禁言管理插件，提供智能禁言功能
+
+# 插件启用配置
+[plugin]
+
+# 是否启用插件
+enabled = false
+
+
+# 组件启用控制
+[components]
+
+# 是否启用智能禁言Action
+enable_smart_mute = true
+
+# 是否启用禁言命令Command
+enable_mute_command = false
+
+
+# 核心禁言功能配置
+[mute]
+
+# 最短禁言时长（秒）
+min_duration = 60
+
+# 最长禁言时长（秒），默认30天
+max_duration = 2592000
+
+# 成功禁言后发送的随机消息模板
+templates = ["好的，禁言 {target} {duration}，理由：{reason}", "收到，对 {target} 执行禁言 {duration}"]
+
+
+# 智能禁言Action的专属配置
+[smart_mute]
+
+# 关键词激活的敏感度
+# 可选值: low, normal, high
+keyword_sensitivity = "normal"
+
+
+# 日志记录相关配置
+[logging]
+
+# 日志记录级别
+# 可选值: DEBUG, INFO, WARNING, ERROR
+level = "INFO"
+
+# 日志记录前缀
+# 示例: [MyMutePlugin]
+prefix = "[MutePlugin]"
+```
+
+---
+
+## 配置访问
+
+如果你想要在你的组件中访问配置，可以通过组件内置的 `get_config()` 方法访问配置。
+
+其参数为一个命名空间化的字符串。以上面的 `MutePlugin` 为例，你可以这样访问配置：
+
+```python
+enable_smart_mute = self.get_config("components.enable_smart_mute", True)
+```
+
+如果尝试访问了一个不存在的配置项，系统会自动返回默认值（你传递的）或者 `None`。
+
+---
+
+## 最佳实践与注意事项
+
+
+**🚨 核心原则：永远不要手动创建 config.toml 文件！**
+
+1.  **🔥 绝不手动创建配置文件**: **任何时候都不要手动创建 `config.toml` 文件**！必须通过在 `plugin.py` 中定义 `config_schema` 让系统自动生成。
+    - ❌ **禁止**：`touch config.toml`、手动编写配置文件
+    - ✅ **正确**：定义 `config_schema`，启动插件，让系统自动生成
+
+2.  **Schema优先**: 所有配置项都必须在 `config_schema` 中声明，包括类型、默认值和描述。
+
+3.  **描述清晰**: 为每个 `ConfigField` 和 `config_section_descriptions` 编写清晰、准确的描述。这会直接成为你的插件文档的一部分。
+
+4.  **提供合理默认值**: 确保你的插件在默认配置下就能正常运行（或处于一个安全禁用的状态）。
+
+5.  **gitignore**: 将 `plugins/*/config.toml` 或 `src/plugins/built_in/*/config.toml` 加入 `.gitignore`，以避免提交个人敏感信息。
+
+6.  **配置文件只供修改**: 自动生成的 `config.toml` 文件只应该被用户**修改**，而不是从零创建。

docs/plugins/dependency-management.md

@@ -0,0 +1,40 @@
+# 📦 插件依赖管理系统
+
+现在的Python依赖包管理依然存在问题，请保留你的`python_dependencies`属性，等待后续重构。
+
+## 📚 详细教程
+
+### PythonDependency 类详解
+
+`PythonDependency`是依赖声明的核心类：
+
+```python
+PythonDependency(
+    package_name="PIL",          # 导入时的包名
+    version=">=11.2.0",          # 版本要求
+    optional=False,              # 是否为可选依赖
+    description="图像处理库",     # 依赖描述
+    install_name="pillow"        # pip安装时的包名（可选）
+)
+```
+
+#### 参数说明
+
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `package_name` | str | ✅ | Python导入时使用的包名（如`requests`） |
+| `version` | str | ❌ | 版本要求，使用pip格式（如`>=1.0.0`, `==2.1.3`） |
+| `optional` | bool | ❌ | 是否为可选依赖，默认`False` |
+| `description` | str | ❌ | 依赖的用途描述 |
+| `install_name` | str | ❌ | pip安装时的包名，默认与`package_name`相同，用于处理安装名称和导入名称不一致的情况 |
+
+#### 版本格式示例
+
+```python
+# 常用版本格式
+PythonDependency("requests", ">=2.25.0")           # 最小版本
+PythonDependency("numpy", ">=1.20.0,<2.0.0")       # 版本范围
+PythonDependency("pillow", "==8.3.2")              # 精确版本
+PythonDependency("scipy", ">=1.7.0,!=1.8.0")       # 排除特定版本
+```
+

docs/plugins/index.md

@@ -0,0 +1,81 @@
+# MaiBot插件开发文档
+
+> 欢迎来到MaiBot插件系统开发文档！这里是你开始插件开发旅程的最佳起点。
+
+## 新手入门
+
+- [📖 快速开始指南](quick-start.md) - 快速创建你的第一个插件
+
+## 组件功能详解
+
+- [🧱 Action组件详解](action-components.md) - 掌握最核心的Action组件
+- [💻 Command组件详解](command-components.md) - 学习直接响应命令的组件
+- [🔧 Tool组件详解](tool-components.md) - 了解如何扩展信息获取能力
+- [⚙️ 配置文件系统指南](configuration-guide.md) - 学会使用自动生成的插件配置文件
+- [📄 Manifest系统指南](manifest-guide.md) - 了解插件元数据管理和配置架构
+
+Command vs Action 选择指南
+
+1. 使用Command的场景
+
+- ✅ 用户需要明确调用特定功能
+- ✅ 需要精确的参数控制
+- ✅ 管理和配置操作
+- ✅ 查询和信息显示
+- ✅ 系统维护命令
+
+2. 使用Action的场景
+
+- ✅ 增强麦麦的智能行为
+- ✅ 根据上下文自动触发
+- ✅ 情绪和表情表达
+- ✅ 智能建议和帮助
+- ✅ 随机化的互动
+
+
+## API浏览
+
+### 消息发送与处理API
+- [📤 发送API](api/send-api.md) - 各种类型消息发送接口
+- [消息API](api/message-api.md) - 消息获取，消息构建，消息查询接口
+- [聊天流API](api/chat-api.md) - 聊天流管理和查询接口
+
+### AI与生成API  
+- [LLM API](api/llm-api.md) - 大语言模型交互接口，可以使用内置LLM生成内容
+- [✨ 回复生成器API](api/generator-api.md) - 智能回复生成接口，可以使用内置风格化生成器
+
+### 表情包API
+- [😊 表情包API](api/emoji-api.md) - 表情包选择和管理接口
+
+### 关系系统API
+- [人物信息API](api/person-api.md) - 用户信息，处理麦麦认识的人和关系的接口
+
+### 数据与配置API
+- [🗄️ 数据库API](api/database-api.md) - 数据库操作接口
+- [⚙️ 配置API](api/config-api.md) - 配置读取和用户信息接口
+
+### 插件和组件管理API
+- [🔌 插件API](api/plugin-manage-api.md) - 插件加载和管理接口
+- [🧩 组件API](api/component-manage-api.md) - 组件注册和管理接口
+
+### 日志API
+- [📜 日志API](api/logging-api.md) - logger实例获取接口
+### 工具API
+- [🔧 工具API](api/tool-api.md) - tool获取接口
+
+
+
+## 支持
+
+> 如果你在文档中发现错误或需要补充，请：
+
+1. 检查最新的文档版本
+2. 查看相关示例代码
+3. 参考其他类似插件
+4. 提交文档仓库issue
+
+## 一个方便的小设计
+
+我们在`__init__.py`中定义了一个`__all__`变量，包含了所有需要导出的类和函数。
+这样在其他地方导入时，可以直接使用 `from src.plugin_system import *` 来导入所有插件相关的类和函数。
+或者你可以直接使用 `from src.plugin_system import BasePlugin, register_plugin, ComponentInfo` 之类的方式来导入你需要的部分。

docs/plugins/manifest-guide.md

@@ -0,0 +1,205 @@
+# 📄 插件Manifest系统指南
+
+## 概述
+
+MaiBot插件系统现在强制要求每个插件都必须包含一个 `_manifest.json` 文件。这个文件描述了插件的基本信息、依赖关系、组件等重要元数据。
+
+### 🔄 配置架构：Manifest与Config的职责分离
+
+为了避免信息重复和提高维护性，我们采用了**双文件架构**：
+
+- **`_manifest.json`** - 插件的**静态元数据**
+  - 插件身份信息（名称、版本、描述）
+  - 开发者信息（作者、许可证、仓库）
+  - 系统信息（兼容性、组件列表、分类）
+  
+- **`config.toml`** - 插件的**运行时配置**
+  - 启用状态 (`enabled`)
+  - 功能参数配置
+  - 用户可调整的行为设置
+
+这种分离确保了：
+- ✅ 元数据信息统一管理
+- ✅ 运行时配置灵活调整  
+- ✅ 避免重复维护
+- ✅ 更清晰的职责划分
+
+## 🔧 Manifest文件结构
+
+### 必需字段
+
+以下字段是必需的，不能为空：
+
+```json
+{
+  "manifest_version": 1,
+  "name": "插件显示名称",
+  "version": "1.0.0",
+  "description": "插件功能描述",
+  "author": {
+    "name": "作者名称"
+  }
+}
+```
+
+### 可选字段
+
+以下字段都是可选的，可以根据需要添加：
+
+```json
+{
+  "license": "MIT",
+  "host_application": {
+    "min_version": "1.0.0",
+    "max_version": "4.0.0"
+  },
+  "homepage_url": "https://github.com/your-repo",
+  "repository_url": "https://github.com/your-repo",
+  "keywords": ["关键词1", "关键词2"],
+  "categories": ["分类1", "分类2"],
+  "default_locale": "zh-CN",
+  "locales_path": "_locales",
+  "plugin_info": {
+    "is_built_in": false,
+    "plugin_type": "general",
+    "components": [
+      {
+        "type": "action",
+        "name": "组件名称",
+        "description": "组件描述"
+      }
+    ]
+  }
+}
+```
+
+## 🛠️ 管理工具
+
+### 使用manifest_tool.py
+
+我们提供了一个命令行工具来帮助管理manifest文件：
+
+```bash
+# 扫描缺少manifest的插件
+python scripts/manifest_tool.py scan src/plugins
+
+# 为插件创建最小化manifest文件
+python scripts/manifest_tool.py create-minimal src/plugins/my_plugin --name "我的插件" --author "作者"
+
+# 为插件创建完整manifest模板
+python scripts/manifest_tool.py create-complete src/plugins/my_plugin --name "我的插件"
+
+# 验证manifest文件
+python scripts/manifest_tool.py validate src/plugins/my_plugin
+```
+
+### 验证示例
+
+验证通过的示例：
+```
+✅ Manifest文件验证通过
+```
+
+验证失败的示例：
+```
+❌ 验证错误:
+  - 缺少必需字段: name
+  - 作者信息缺少name字段或为空
+⚠️ 验证警告:
+  - 建议填写字段: license
+  - 建议填写字段: keywords
+```
+
+## 🔄 迁移指南
+
+### 对于现有插件
+
+1. **检查缺少manifest的插件**：
+   ```bash
+   python scripts/manifest_tool.py scan src/plugins
+   ```
+
+2. **为每个插件创建manifest**：
+   ```bash
+   python scripts/manifest_tool.py create-minimal src/plugins/your_plugin
+   ```
+
+3. **编辑manifest文件**，填写正确的信息。
+
+4. **验证manifest**：
+   ```bash
+   python scripts/manifest_tool.py validate src/plugins/your_plugin
+   ```
+
+### 对于新插件
+
+创建新插件时，建议的步骤：
+
+1. **创建插件目录和基本文件**
+2. **创建完整manifest模板**：
+   ```bash
+   python scripts/manifest_tool.py create-complete src/plugins/new_plugin
+   ```
+3. **根据实际情况修改manifest文件**
+4. **编写插件代码**
+5. **验证manifest文件**
+
+## 📋 字段说明
+
+### 基本信息
+- `manifest_version`: manifest格式版本，当前为1
+- `name`: 插件显示名称（必需）
+- `version`: 插件版本号（必需）
+- `description`: 插件功能描述（必需）
+- `author`: 作者信息（必需）
+  - `name`: 作者名称（必需）
+  - `url`: 作者主页（可选）
+
+### 许可和URL
+- `license`: 插件许可证（可选，建议填写）
+- `homepage_url`: 插件主页（可选）
+- `repository_url`: 源码仓库地址（可选）
+
+### 分类和标签
+- `keywords`: 关键词数组（可选，建议填写）
+- `categories`: 分类数组（可选，建议填写）
+
+### 兼容性
+- `host_application`: 主机应用兼容性（可选，建议填写）
+  - `min_version`: 最低兼容版本
+  - `max_version`: 最高兼容版本
+
+⚠️ 在不填写的情况下，插件将默认支持所有版本。**（由于我们在不同版本对插件系统进行了大量的重构，这种情况几乎不可能。）**
+
+### 国际化
+- `default_locale`: 默认语言（可选）
+- `locales_path`: 语言文件目录（可选）
+
+### 插件特定信息
+- `plugin_info`: 插件详细信息（可选）
+  - `is_built_in`: 是否为内置插件
+  - `plugin_type`: 插件类型
+  - `components`: 组件列表
+
+## ⚠️ 注意事项
+
+1. **强制要求**：所有插件必须包含`_manifest.json`文件，否则无法加载
+2. **编码格式**：manifest文件必须使用UTF-8编码
+3. **JSON格式**：文件必须是有效的JSON格式
+4. **必需字段**：`manifest_version`、`name`、`version`、`description`、`author.name`是必需的
+5. **版本兼容**：当前只支持`manifest_version = 1`
+
+## 🔍 常见问题
+
+### Q: 可以不填写可选字段吗？
+A: 可以。所有标记为"可选"的字段都可以不填写，但建议至少填写`license`和`keywords`。
+
+### Q: manifest验证失败怎么办？
+A: 根据验证器的错误提示修复相应问题。错误会导致插件加载失败，警告不会。
+
+## 📚 参考示例
+
+查看内置插件的manifest文件作为参考：
+- `src/plugins/built_in/core_actions/_manifest.json`
+- `src/plugins/built_in/tts_plugin/_manifest.json`
+- `src/plugins/hello_world_plugin/_manifest.json`

docs/plugins/quick-start.md

@@ -0,0 +1,428 @@
+# 🚀 快速开始指南
+
+本指南将带你从零开始创建一个功能完整的MaiCore插件。
+
+## 📖 概述
+
+这个指南将带你快速创建你的第一个MaiCore插件。我们将创建一个简单的问候插件，展示插件系统的基本概念。
+
+以下代码都在我们的`plugins/hello_world_plugin/`目录下。
+
+### 一个方便的小设计
+
+在开发中，我们在`__init__.py`中定义了一个`__all__`变量，包含了所有需要导出的类和函数。
+这样在其他地方导入时，可以直接使用 `from src.plugin_system import *` 来导入所有插件相关的类和函数。
+或者你可以直接使用 `from src.plugin_system import BasePlugin, register_plugin, ComponentInfo` 之类的方式来导入你需要的部分。
+
+### 📂 准备工作
+
+确保你已经：
+
+1. 克隆了MaiCore项目
+2. 安装了Python依赖
+3. 了解基本的Python语法
+
+## 🏗️ 创建插件
+
+### 1. 创建插件目录
+
+在项目根目录的 `plugins/` 文件夹下创建你的插件目录
+
+这里我们创建一个名为 `hello_world_plugin` 的目录
+
+### 2. 创建`_manifest.json`文件
+
+在插件目录下面创建一个 `_manifest.json` 文件，内容如下：
+
+```json
+{
+  "manifest_version": 1,
+  "name": "Hello World 插件",
+  "version": "1.0.0",
+  "description": "一个简单的 Hello World 插件",
+  "author": {
+    "name": "你的名字"
+  }
+}
+```
+
+有关 `_manifest.json` 的详细说明，请参考 [Manifest文件指南](./manifest-guide.md)。
+
+### 3. 创建最简单的插件
+
+让我们从最基础的开始！创建 `plugin.py` 文件：
+
+```python
+from typing import List, Tuple, Type
+from src.plugin_system import BasePlugin, register_plugin, ComponentInfo
+
+@register_plugin # 注册插件
+class HelloWorldPlugin(BasePlugin):
+    """Hello World插件 - 你的第一个MaiCore插件"""
+
+    # 以下是插件基本信息和方法（必须填写）
+    plugin_name = "hello_world_plugin"
+    enable_plugin = True  # 启用插件
+    dependencies = []  # 插件依赖列表（目前为空）
+    python_dependencies = []  # Python依赖列表（目前为空）
+    config_file_name = "config.toml"  # 配置文件名
+    config_schema = {}  # 配置文件模式（目前为空）
+
+    def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]: # 获取插件组件
+        """返回插件包含的组件列表（目前是空的）"""
+        return []
+```
+
+🎉 恭喜！你刚刚创建了一个最简单但完整的MaiCore插件！
+
+**解释一下这些代码：**
+
+- 首先，我们在`plugin.py`中定义了一个HelloWorldPlugin插件类，继承自 `BasePlugin` ，提供基本功能。
+- 通过给类加上，`@register_plugin` 装饰器，我们告诉系统"这是一个插件"
+- `plugin_name` 等是插件的基本信息，必须填写
+- `get_plugin_components()` 返回插件的功能组件，现在我们没有定义任何 Action, Command 或者 EventHandler，所以返回空列表。
+
+### 4. 测试基础插件
+
+现在就可以测试这个插件了！启动MaiCore：
+
+直接通过启动器运行MaiCore或者 `python bot.py`
+
+在日志中你应该能看到插件被加载的信息。虽然插件还没有任何功能，但它已经成功运行了！
+
+![1750326700269](image/quick-start/1750326700269.png)
+
+### 5. 添加第一个功能：问候Action
+
+现在我们要给插件加入一个有用的功能，我们从最好玩的Action做起
+
+Action是一类可以让MaiCore根据自身意愿选择使用的“动作”，在MaiCore中，不论是“回复”还是“不回复”，或者“发送表情”以及“禁言”等等，都是通过Action实现的。
+
+你可以通过编写动作，来拓展MaiCore的能力，包括发送语音，截图，甚至操作文件，编写代码......
+
+现在让我们给插件添加第一个简单的功能。这个Action可以对用户发送一句问候语。
+
+在 `plugin.py` 文件中添加Action组件，完整代码如下：
+
+```python
+from typing import List, Tuple, Type
+from src.plugin_system import (
+    BasePlugin, register_plugin, BaseAction, 
+    ComponentInfo, ActionActivationType, ChatMode
+)
+
+# ===== Action组件 =====
+
+class HelloAction(BaseAction):
+    """问候Action - 简单的问候动作"""
+
+    # === 基本信息（必须填写）===
+    action_name = "hello_greeting"
+    action_description = "向用户发送问候消息"
+    activation_type = ActionActivationType.ALWAYS  # 始终激活
+
+    # === 功能描述（必须填写）===
+    action_parameters = {"greeting_message": "要发送的问候消息"}
+    action_require = ["需要发送友好问候时使用", "当有人向你问好时使用", "当你遇见没有见过的人时使用"]
+    associated_types = ["text"]
+
+    async def execute(self) -> Tuple[bool, str]:
+        """执行问候动作 - 这是核心功能"""
+        # 发送问候消息
+        greeting_message = self.action_data.get("greeting_message", "")
+        base_message = self.get_config("greeting.message", "嗨！很开心见到你！😊")
+        message = base_message + greeting_message
+        await self.send_text(message)
+
+        return True, "发送了问候消息"
+
+@register_plugin
+class HelloWorldPlugin(BasePlugin):
+    """Hello World插件 - 你的第一个MaiCore插件"""
+
+    # 插件基本信息
+    plugin_name = "hello_world_plugin"
+    enable_plugin = True
+    dependencies = []
+    python_dependencies = []
+    config_file_name = "config.toml"
+    config_schema = {}
+
+    def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
+        """返回插件包含的组件列表"""
+        return [
+            # 添加我们的问候Action
+            (HelloAction.get_action_info(), HelloAction),
+        ]
+```
+
+**解释一下这些代码：**
+
+- `HelloAction` 是我们定义的问候动作类，继承自 `BaseAction`，并实现了核心功能。
+- 在 `HelloWorldPlugin` 中，我们通过 `get_plugin_components()` 方法，通过调用`get_action_info()`这个内置方法将 `HelloAction` 注册为插件的一个组件。
+- 这样一来，当插件被加载时，问候动作也会被一并加载，并可以在MaiCore中使用。
+- `execute()` 函数是Action的核心，定义了当Action被MaiCore选择后，具体要做什么
+- `self.send_text()` 是发送文本消息的便捷方法
+
+Action 组件中有关`activation_type`、`action_parameters`、`action_require`、`associated_types` 等的详细说明请参考 [Action组件指南](./action-components.md)。
+
+### 6. 测试问候Action
+
+重启MaiCore，然后在聊天中发送任意消息，比如：
+
+```
+你好
+```
+
+MaiCore可能会选择使用你的问候Action，发送回复：
+
+```
+嗨！很开心见到你！😊
+```
+
+![1750332508760](image/quick-start/1750332508760.png)
+
+> **💡 小提示**：MaiCore会智能地决定什么时候使用它。如果没有立即看到效果，多试几次不同的消息。
+
+🎉 太棒了！你的插件已经有实际功能了！
+
+### 7. 添加第二个功能：时间查询Command
+
+现在让我们添加一个Command组件。Command和Action不同，它是直接响应用户命令的：
+
+Command是最简单，最直接的响应，不由LLM判断选择使用
+
+```python
+# 在现有代码基础上，添加Command组件
+import datetime
+from src.plugin_system import BaseCommand
+#导入Command基类
+
+class TimeCommand(BaseCommand):
+    """时间查询Command - 响应/time命令"""
+
+    command_name = "time"
+    command_description = "查询当前时间"
+
+    # === 命令设置（必须填写）===
+    command_pattern = r"^/time$"  # 精确匹配 "/time" 命令
+
+    async def execute(self) -> Tuple[bool, Optional[str], bool]:
+        """执行时间查询"""
+        # 获取当前时间
+        time_format: str = "%Y-%m-%d %H:%M:%S"
+        now = datetime.datetime.now()
+        time_str = now.strftime(time_format)
+
+        # 发送时间信息
+        message = f"⏰ 当前时间：{time_str}"
+        await self.send_text(message)
+
+        return True, f"显示了当前时间: {time_str}", True
+
+@register_plugin
+class HelloWorldPlugin(BasePlugin):
+    """Hello World插件 - 你的第一个MaiCore插件"""
+
+    # 插件基本信息
+    plugin_name = "hello_world_plugin"
+    enable_plugin = True
+    dependencies = []
+    python_dependencies = []
+    config_file_name = "config.toml"
+    config_schema = {}
+
+    def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
+        return [
+            (HelloAction.get_action_info(), HelloAction),
+            (TimeCommand.get_command_info(), TimeCommand),
+        ]
+```
+
+同样的，我们通过 `get_plugin_components()` 方法，通过调用`get_action_info()`这个内置方法将 `TimeCommand` 注册为插件的一个组件。
+
+**Command组件解释：**
+
+- `command_pattern` 使用正则表达式匹配用户输入
+- `^/time$` 表示精确匹配 "/time"
+
+有关 Command 组件的更多信息，请参考 [Command组件指南](./command-components.md)。
+
+### 8. 测试时间查询Command
+
+重启MaiCore，发送命令：
+
+```
+/time
+```
+
+你应该会收到回复：
+
+```
+⏰ 当前时间：2024-01-01 12:00:00
+```
+
+🎉 太棒了！现在你已经了解了基本的 Action 和 Command 组件的使用方法。你可以根据自己的需求，继续扩展插件的功能，添加更多的 Action 和 Command 组件，让你的插件更加丰富和强大！
+
+---
+
+## 进阶教程
+
+如果你想让插件更加灵活和强大，可以参考接下来的进阶教程。
+
+### 1. 添加配置文件
+
+想要为插件添加配置文件吗？让我们一起来配置`config_schema`属性！
+
+> **🚨 重要：不要手动创建config.toml文件！**
+>
+> 我们需要在插件代码中定义配置Schema，让系统自动生成配置文件。
+
+首先，在插件类中定义配置Schema：
+
+```python
+from src.plugin_system import ConfigField
+
+@register_plugin
+class HelloWorldPlugin(BasePlugin):
+    """Hello World插件 - 你的第一个MaiCore插件"""
+
+    # 插件基本信息
+    plugin_name: str = "hello_world_plugin"  # 内部标识符
+    enable_plugin: bool = True
+    dependencies: List[str] = []  # 插件依赖列表
+    python_dependencies: List[str] = []  # Python包依赖列表
+    config_file_name: str = "config.toml"  # 配置文件名
+
+    # 配置Schema定义
+    config_schema: dict = {
+        "plugin": {
+            "name": ConfigField(type=str, default="hello_world_plugin", description="插件名称"),
+            "version": ConfigField(type=str, default="1.0.0", description="插件版本"),
+            "enabled": ConfigField(type=bool, default=False, description="是否启用插件"),
+        },
+        "greeting": {
+            "message": ConfigField(type=str, default="嗨！很开心见到你！😊", description="默认问候消息"),
+            "enable_emoji": ConfigField(type=bool, default=True, description="是否启用表情符号"),
+        },
+        "time": {"format": ConfigField(type=str, default="%Y-%m-%d %H:%M:%S", description="时间显示格式")},
+    }
+
+    def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
+        return [
+            (HelloAction.get_action_info(), HelloAction),
+            (TimeCommand.get_command_info(), TimeCommand),
+        ]
+```
+
+这会生成一个如下的 `config.toml` 文件：
+
+```toml
+# hello_world_plugin - 自动生成的配置文件
+# 我的第一个MaiCore插件，包含问候功能和时间查询等基础示例
+
+# 插件基本信息
+[plugin]
+
+# 插件名称
+name = "hello_world_plugin"
+
+# 插件版本
+version = "1.0.0"
+
+# 是否启用插件
+enabled = false
+
+
+# 问候功能配置
+[greeting]
+
+# 默认问候消息
+message = "嗨！很开心见到你！😊"
+
+# 是否启用表情符号
+enable_emoji = true
+
+
+# 时间查询配置
+[time]
+
+# 时间显示格式
+format = "%Y-%m-%d %H:%M:%S"
+```
+
+然后修改Action和Command代码，通过 `get_config()` 方法让它们读取配置（配置的键是命名空间式的）：
+
+```python
+class HelloAction(BaseAction):
+    """问候Action - 简单的问候动作"""
+
+    # === 基本信息（必须填写）===
+    action_name = "hello_greeting"
+    action_description = "向用户发送问候消息"
+    activation_type = ActionActivationType.ALWAYS  # 始终激活
+
+    # === 功能描述（必须填写）===
+    action_parameters = {"greeting_message": "要发送的问候消息"}
+    action_require = ["需要发送友好问候时使用", "当有人向你问好时使用", "当你遇见没有见过的人时使用"]
+    associated_types = ["text"]
+
+    async def execute(self) -> Tuple[bool, str]:
+        """执行问候动作 - 这是核心功能"""
+        # 发送问候消息
+        greeting_message = self.action_data.get("greeting_message", "")
+        base_message = self.get_config("greeting.message", "嗨！很开心见到你！😊")
+        message = base_message + greeting_message
+        await self.send_text(message)
+
+        return True, "发送了问候消息"
+
+class TimeCommand(BaseCommand):
+    """时间查询Command - 响应/time命令"""
+
+    command_name = "time"
+    command_description = "查询当前时间"
+
+    # === 命令设置（必须填写）===
+    command_pattern = r"^/time$"  # 精确匹配 "/time" 命令
+
+    async def execute(self) -> Tuple[bool, str, bool]:
+        """执行时间查询"""
+        import datetime
+
+        # 获取当前时间
+        time_format: str = self.get_config("time.format", "%Y-%m-%d %H:%M:%S")  # type: ignore
+        now = datetime.datetime.now()
+        time_str = now.strftime(time_format)
+
+        # 发送时间信息
+        message = f"⏰ 当前时间：{time_str}"
+        await self.send_text(message)
+
+        return True, f"显示了当前时间: {time_str}", True
+```
+
+**配置系统工作流程：**
+
+1. **定义Schema**: 在插件代码中定义配置结构
+2. **自动生成**: 启动插件时，系统会自动生成 `config.toml` 文件
+3. **用户修改**: 用户可以修改生成的配置文件
+4. **代码读取**: 使用 `self.get_config()` 读取配置值
+
+**绝对不要手动创建 `config.toml` 文件！**
+
+更详细的配置系统介绍请参考 [配置指南](./configuration-guide.md)。
+
+### 2. 创建说明文档
+
+你可以创建一个 `README.md` 文件，描述插件的功能和使用方法。
+
+### 3. 发布到插件市场
+
+如果你想让更多人使用你的插件，可以将它发布到MaiCore的插件市场。
+
+这部分请参考 [plugin-repo](https://github.com/Maim-with-u/plugin-repo) 的文档。
+
+---
+
+🎉 恭喜你！你已经成功的创建了自己的插件了！

docs/plugins/tool-components.md

@@ -0,0 +1,246 @@
+# 🔧 工具组件详解
+
+## 📖 什么是工具
+
+工具是MaiBot的信息获取能力扩展组件。如果说Action组件功能五花八门，可以拓展麦麦能做的事情，那么Tool就是在某个过程中拓宽了麦麦能够获得的信息量。
+
+### 🎯 工具的特点
+
+- 🔍 **信息获取增强**：扩展麦麦获取外部信息的能力
+- 📊 **数据丰富**：帮助麦麦获得更多背景信息和实时数据
+- 🔌 **插件式架构**：支持独立开发和注册新工具
+- ⚡ **自动发现**：工具会被系统自动识别和注册
+
+### 🆚 Tool vs Action vs Command 区别
+
+| 特征 | Action | Command | Tool |
+|-----|-------|---------|------|
+| **主要用途** | 扩展麦麦行为能力 | 响应用户指令 | 扩展麦麦信息获取 |
+| **触发方式** | 麦麦智能决策 | 用户主动触发 | LLM根据需要调用 |
+| **目标** | 让麦麦做更多事情 | 提供具体功能 | 让麦麦知道更多信息 |
+| **使用场景** | 增强交互体验 | 功能服务 | 信息查询和分析 |
+
+## 🏗️ Tool组件的基本结构
+
+每个工具必须继承 `BaseTool` 基类并实现以下属性和方法：
+```python
+from src.plugin_system import BaseTool, ToolParamType
+
+class MyTool(BaseTool):
+    # 工具名称，必须唯一
+    name = "my_tool"
+    
+    # 工具描述，告诉LLM这个工具的用途
+    description = "这个工具用于获取特定类型的信息"
+    
+    # 参数定义，仅定义参数
+    # 比如想要定义一个类似下面的openai格式的参数表，则可以这么定义:
+    # {
+    #     "type": "object",
+    #     "properties": {
+    #         "query": {
+    #             "type": "string",
+    #             "description": "查询参数"
+    #         },
+    #         "limit": {
+    #             "type": "integer", 
+    #             "description": "结果数量限制"
+    #             "enum": [10, 20, 50]  # 可选值
+    #         }
+    #     },
+    #     "required": ["query"]
+    # }
+    parameters = [
+        ("query", ToolParamType.STRING, "查询参数", True, None),  # 必填参数
+        ("limit", ToolParamType.INTEGER, "结果数量限制", False, ["10", "20", "50"])  # 可选参数
+    ]
+
+    available_for_llm = True  # 是否对LLM可用
+    
+    async def execute(self, function_args: Dict[str, Any]):
+        """执行工具逻辑"""
+        # 实现工具功能
+        result = f"查询结果: {function_args.get('query')}"
+        
+        return {
+            "name": self.name,
+            "content": result
+        }
+```
+
+### 属性说明
+
+| 属性 | 类型 | 说明 |
+|-----|------|------|
+| `name` | str | 工具的唯一标识名称 |
+| `description` | str | 工具功能描述，帮助LLM理解用途 |
+| `parameters` | list[tuple] | 参数定义 |
+
+其构造而成的工具定义为:
+```python
+definition: Dict[str, Any] = {"name": cls.name, "description": cls.description, "parameters": cls.parameters}
+```
+
+### 方法说明
+
+| 方法 | 参数 | 返回值 | 说明 |
+|-----|------|--------|------|
+| `execute` | `function_args` | `dict` | 执行工具核心逻辑 |
+
+---
+
+## 🎨 完整工具示例
+
+完成一个天气查询工具
+
+```python
+from src.plugin_system import BaseTool
+import aiohttp
+import json
+
+class WeatherTool(BaseTool):
+    """天气查询工具 - 获取指定城市的实时天气信息"""
+    
+    name = "weather_query"
+    description = "查询指定城市的实时天气信息，包括温度、湿度、天气状况等"
+    available_for_llm = True  # 允许LLM调用此工具
+    parameters = [
+        ("city", ToolParamType.STRING, "要查询天气的城市名称，如：北京、上海、纽约", True, None),
+        ("country", ToolParamType.STRING, "国家代码，如：CN、US，可选参数", False, None)
+    ]
+    
+    async def execute(self, function_args: dict):
+        """执行天气查询"""
+        try:
+            city = function_args.get("city")
+            country = function_args.get("country", "")
+            
+            # 构建查询参数
+            location = f"{city},{country}" if country else city
+            
+            # 调用天气API（示例）
+            weather_data = await self._fetch_weather(location)
+            
+            # 格式化结果
+            result = self._format_weather_data(weather_data)
+            
+            return {
+                "name": self.name,
+                "content": result
+            }
+            
+        except Exception as e:
+            return {
+                "name": self.name,
+                "content": f"天气查询失败: {str(e)}"
+            }
+    
+    async def _fetch_weather(self, location: str) -> dict:
+        """获取天气数据"""
+        # 这里是示例，实际需要接入真实的天气API
+        api_url = f"http://api.weather.com/v1/current?q={location}"
+        
+        async with aiohttp.ClientSession() as session:
+            async with session.get(api_url) as response:
+                return await response.json()
+    
+    def _format_weather_data(self, data: dict) -> str:
+        """格式化天气数据"""
+        if not data:
+            return "暂无天气数据"
+        
+        # 提取关键信息
+        city = data.get("location", {}).get("name", "未知城市")
+        temp = data.get("current", {}).get("temp_c", "未知")
+        condition = data.get("current", {}).get("condition", {}).get("text", "未知")
+        humidity = data.get("current", {}).get("humidity", "未知")
+        
+        # 格式化输出
+        return f"""
+🌤️ {city} 实时天气
+━━━━━━━━━━━━━━━━━━
+🌡️ 温度: {temp}°C
+☁️ 天气: {condition}
+💧 湿度: {humidity}%
+━━━━━━━━━━━━━━━━━━
+        """.strip()
+```
+
+---
+
+## 🚨 注意事项和限制
+
+### 当前限制
+
+1. **适用范围**：主要适用于信息获取场景
+2. **配置要求**：必须开启工具处理器
+
+### 开发建议
+
+1. **功能专一**：每个工具专注单一功能
+2. **参数明确**：清晰定义工具参数和用途
+3. **错误处理**：完善的异常处理和错误反馈
+4. **性能考虑**：避免长时间阻塞操作
+5. **信息准确**：确保获取信息的准确性和时效性
+
+## 🎯 最佳实践
+
+### 1. 工具命名规范
+#### ✅ 好的命名
+```python
+name = "weather_query"        # 清晰表达功能
+name = "knowledge_search"     # 描述性强
+name = "stock_price_check"    # 功能明确
+```
+#### ❌ 避免的命名
+```python
+name = "tool1"               # 无意义
+name = "wq"                  # 过于简短
+name = "weather_and_news"    # 功能过于复杂
+```
+
+### 2. 描述规范
+#### ✅ 良好的描述
+```python
+description = "查询指定城市的实时天气信息，包括温度、湿度、天气状况"
+```
+#### ❌ 避免的描述
+```python
+description = "天气"         # 过于简单
+description = "获取信息"      # 不够具体
+```
+
+### 3. 参数设计
+
+#### ✅ 合理的参数设计
+```python
+parameters = [
+    ("city", ToolParamType.STRING, "城市名称，如：北京、上海", True, None),
+    ("unit", ToolParamType.STRING, "温度单位：celsius 或 fahrenheit", False, ["celsius", "fahrenheit"])
+]
+```
+#### ❌ 避免的参数设计
+```python
+parameters = [
+    ("data", "string", "数据", True)  # 参数过于模糊
+]
+```
+
+### 4. 结果格式化
+#### ✅ 良好的结果格式
+```python
+def _format_result(self, data):
+    return f"""
+🔍 查询结果
+━━━━━━━━━━━━
+📊 数据: {data['value']}
+📅 时间: {data['timestamp']}
+📝 说明: {data['description']}
+━━━━━━━━━━━━
+    """.strip()
+```
+#### ❌ 避免的结果格式
+```python
+def _format_result(self, data):
+    return str(data)  # 直接返回原始数据
+```

flake.lock

@@ -0,0 +1,57 @@
+{
+  "nodes": {
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 0,
+        "narHash": "sha256-nJj8f78AYAxl/zqLiFGXn5Im1qjFKU8yBPKoWEeZN5M=",
+        "path": "/nix/store/f30jn7l0bf7a01qj029fq55i466vmnkh-source",
+        "type": "path"
+      },
+      "original": {
+        "id": "nixpkgs",
+        "type": "indirect"
+      }
+    },
+    "root": {
+      "inputs": {
+        "nixpkgs": "nixpkgs",
+        "utils": "utils"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    },
+    "utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,39 @@
+{
+  description = "MaiMBot Nix Dev Env";
+
+  inputs = {
+    utils.url = "github:numtide/flake-utils";
+  };
+
+  outputs = {
+    self,
+    nixpkgs,
+    utils,
+    ...
+  }:
+    utils.lib.eachDefaultSystem (system: let
+      pkgs = import nixpkgs {inherit system;};
+      pythonPackages = pkgs.python3Packages;
+    in {
+      devShells.default = pkgs.mkShell {
+        name = "python-venv";
+        venvDir = "./.venv";
+        buildInputs = with pythonPackages; [
+          python
+          venvShellHook
+          scipy
+          numpy
+        ];
+
+        postVenvCreation = ''
+          unset SOURCE_DATE_EPOCH
+          pip install -r requirements.txt
+        '';
+
+        postShellHook = ''
+          # allow pip to install wheels
+          unset SOURCE_DATE_EPOCH
+        '';
+      };
+    });
+}

mongodb_to_sqlite.bat

@@ -0,0 +1,72 @@
+@echo off
+CHCP 65001 > nul
+setlocal enabledelayedexpansion
+
+echo 你需要选择启动方式，输入字母来选择:
+echo   V = 不知道什么意思就输入 V
+echo   C = 输入 C 使用 Conda 环境
+echo.
+choice /C CV /N /M "不知道什么意思就输入 V (C/V)?" /T 10 /D V
+
+set "ENV_TYPE="
+if %ERRORLEVEL% == 1 set "ENV_TYPE=CONDA"
+if %ERRORLEVEL% == 2 set "ENV_TYPE=VENV"
+
+if "%ENV_TYPE%" == "CONDA" goto activate_conda
+if "%ENV_TYPE%" == "VENV" goto activate_venv
+
+REM 如果 choice 超时或返回意外值，默认使用 venv
+echo WARN: Invalid selection or timeout from choice. Defaulting to VENV.
+set "ENV_TYPE=VENV"
+goto activate_venv
+
+:activate_conda
+    set /p CONDA_ENV_NAME="请输入要使用的 Conda 环境名称: "
+    if not defined CONDA_ENV_NAME (
+        echo 错误: 未输入 Conda 环境名称.
+        pause
+        exit /b 1
+    )
+    echo 选择: Conda '!CONDA_ENV_NAME!'
+    REM 激活Conda环境
+    call conda activate !CONDA_ENV_NAME!
+    if !ERRORLEVEL! neq 0 (
+        echo 错误: Conda环境 '!CONDA_ENV_NAME!' 激活失败. 请确保Conda已安装并正确配置, 且 '!CONDA_ENV_NAME!' 环境存在.
+        pause
+        exit /b 1
+    )
+    goto env_activated
+
+:activate_venv
+    echo Selected: venv (default or selected)
+    REM 查找venv虚拟环境
+    set "venv_path=%~dp0venv\Scripts\activate.bat"
+    if not exist "%venv_path%" (
+        echo Error: venv not found. Ensure the venv directory exists alongside the script.
+        pause
+        exit /b 1
+    )
+    REM 激活虚拟环境
+    call "%venv_path%"
+    if %ERRORLEVEL% neq 0 (
+        echo Error: Failed to activate venv virtual environment.
+        pause
+        exit /b 1
+    )
+    goto env_activated
+
+:env_activated
+echo Environment activated successfully!
+
+REM --- 后续脚本执行 ---
+
+REM 运行预处理脚本
+python "%~dp0scripts\mongodb_to_sqlite.py"
+if %ERRORLEVEL% neq 0 (
+    echo Error: mongodb_to_sqlite.py execution failed.
+    pause
+    exit /b 1
+)
+
+echo All processing steps completed!
+pause

plugins/hello_world_plugin/_manifest.json

@@ -0,0 +1,53 @@
+{
+  "manifest_version": 1,
+  "name": "Hello World 示例插件 (Hello World Plugin)",
+  "version": "1.0.0",
+  "description": "我的第一个MaiCore插件，包含问候功能和时间查询等基础示例",
+  "author": {
+    "name": "MaiBot开发团队",
+    "url": "https://github.com/MaiM-with-u"
+  },
+  "license": "GPL-v3.0-or-later",
+  
+  "host_application": {
+    "min_version": "0.8.0"
+  },
+  "homepage_url": "https://github.com/MaiM-with-u/maibot",
+  "repository_url": "https://github.com/MaiM-with-u/maibot",
+  "keywords": ["demo", "example", "hello", "greeting", "tutorial"],
+  "categories": ["Examples", "Tutorial"],
+  
+  "default_locale": "zh-CN",
+  "locales_path": "_locales",
+  
+  "plugin_info": {
+    "is_built_in": false,
+    "plugin_type": "example",
+    "components": [
+      {
+        "type": "action",
+        "name": "hello_greeting",
+        "description": "向用户发送问候消息"
+      },
+      {
+        "type": "action",
+        "name": "bye_greeting", 
+        "description": "向用户发送告别消息",
+        "activation_modes": ["keyword"],
+        "keywords": ["再见", "bye", "88", "拜拜"]
+      },
+      {
+        "type": "command",
+        "name": "time",
+        "description": "查询当前时间",
+        "pattern": "/time"
+      }
+    ],
+    "features": [
+      "问候和告别功能",
+      "时间查询命令",
+      "配置文件示例",
+      "新手教程代码"
+    ]
+  }
+}

plugins/hello_world_plugin/plugin.py

@@ -0,0 +1,208 @@
+from typing import List, Tuple, Type, Any
+from src.plugin_system import (
+    BasePlugin,
+    register_plugin,
+    BaseAction,
+    BaseCommand,
+    BaseTool,
+    ComponentInfo,
+    ActionActivationType,
+    ConfigField,
+    ToolParamType
+)
+
+
+class CompareNumbersTool(BaseTool):
+    """比较两个数大小的工具"""
+
+    name = "compare_numbers"
+    description = "使用工具 比较两个数的大小，返回较大的数"
+    parameters = [
+        ("num1", ToolParamType.FLOAT, "第一个数字", True, None),
+        ("num2", ToolParamType.FLOAT, "第二个数字", True, None),
+    ]
+
+    async def execute(self, function_args: dict[str, Any]) -> dict[str, Any]:
+        """执行比较两个数的大小
+
+        Args:
+            function_args: 工具参数
+
+        Returns:
+            dict: 工具执行结果
+        """
+        num1: int | float = function_args.get("num1")  # type: ignore
+        num2: int | float = function_args.get("num2")  # type: ignore
+
+        try:
+            if num1 > num2:
+                result = f"{num1} 大于 {num2}"
+            elif num1 < num2:
+                result = f"{num1} 小于 {num2}"
+            else:
+                result = f"{num1} 等于 {num2}"
+
+            return {"name": self.name, "content": result}
+        except Exception as e:
+            return {"name": self.name, "content": f"比较数字失败，炸了: {str(e)}"}
+
+
+# ===== Action组件 =====
+class HelloAction(BaseAction):
+    """问候Action - 简单的问候动作"""
+
+    # === 基本信息（必须填写）===
+    action_name = "hello_greeting"
+    action_description = "向用户发送问候消息"
+    activation_type = ActionActivationType.ALWAYS  # 始终激活
+
+    # === 功能描述（必须填写）===
+    action_parameters = {"greeting_message": "要发送的问候消息"}
+    action_require = ["需要发送友好问候时使用", "当有人向你问好时使用", "当你遇见没有见过的人时使用"]
+    associated_types = ["text"]
+
+    async def execute(self) -> Tuple[bool, str]:
+        """执行问候动作 - 这是核心功能"""
+        # 发送问候消息
+        greeting_message = self.action_data.get("greeting_message", "")
+        base_message = self.get_config("greeting.message", "嗨！很开心见到你！😊")
+        message = base_message + greeting_message
+        await self.send_text(message)
+
+        return True, "发送了问候消息"
+
+
+class ByeAction(BaseAction):
+    """告别Action - 只在用户说再见时激活"""
+
+    action_name = "bye_greeting"
+    action_description = "向用户发送告别消息"
+
+    # 使用关键词激活
+    activation_type = ActionActivationType.KEYWORD
+
+    # 关键词设置
+    activation_keywords = ["再见", "bye", "88", "拜拜"]
+    keyword_case_sensitive = False
+
+    action_parameters = {"bye_message": "要发送的告别消息"}
+    action_require = [
+        "用户要告别时使用",
+        "当有人要离开时使用",
+        "当有人和你说再见时使用",
+    ]
+    associated_types = ["text"]
+
+    async def execute(self) -> Tuple[bool, str]:
+        bye_message = self.action_data.get("bye_message", "")
+
+        message = f"再见！期待下次聊天！👋{bye_message}"
+        await self.send_text(message)
+        return True, "发送了告别消息"
+
+
+class TimeCommand(BaseCommand):
+    """时间查询Command - 响应/time命令"""
+
+    command_name = "time"
+    command_description = "查询当前时间"
+
+    # === 命令设置（必须填写）===
+    command_pattern = r"^/time$"  # 精确匹配 "/time" 命令
+
+    async def execute(self) -> Tuple[bool, str, bool]:
+        """执行时间查询"""
+        import datetime
+
+        # 获取当前时间
+        time_format: str = self.get_config("time.format", "%Y-%m-%d %H:%M:%S")  # type: ignore
+        now = datetime.datetime.now()
+        time_str = now.strftime(time_format)
+
+        # 发送时间信息
+        message = f"⏰ 当前时间：{time_str}"
+        await self.send_text(message)
+
+        return True, f"显示了当前x时间: {time_str}", True
+
+
+# class PrintMessage(BaseEventHandler):
+#     """打印消息事件处理器 - 处理打印消息事件"""
+#
+#     event_type = EventType.ON_MESSAGE
+#     handler_name = "print_message_handler"
+#     handler_description = "打印接收到的消息"
+#
+#     async def execute(self, message: MaiMessages) -> Tuple[bool, bool, str | None]:
+#         """执行打印消息事件处理"""
+#         # 打印接收到的消息
+#
+#         if self.get_config("print_message.enabled", False):
+#             print(f"接收到消息: {message.raw_message}")
+#         return True, True, "消息已打印1"
+
+
+# ===== 插件注册 =====
+
+
+@register_plugin
+class HelloWorldPlugin(BasePlugin):
+    """Hello World插件 - 你的第一个MaiCore插件"""
+
+    # 插件基本信息
+    plugin_name: str = "hello_world_plugin"  # 内部标识符
+    enable_plugin: bool = True
+    dependencies: List[str] = []  # 插件依赖列表
+    python_dependencies: List[str] = []  # Python包依赖列表
+    config_file_name: str = "config.toml"  # 配置文件名
+
+    # 配置节描述
+    config_section_descriptions = {"plugin": "插件基本信息", "greeting": "问候功能配置", "time": "时间查询配置"}
+
+    # 配置Schema定义
+    config_schema: dict = {
+        "plugin": {
+            "name": ConfigField(type=str, default="hello_world_plugin", description="插件名称"),
+            "version": ConfigField(type=str, default="1.0.0", description="插件版本"),
+            "enabled": ConfigField(type=bool, default=False, description="是否启用插件"),
+        },
+        "greeting": {
+            "message": ConfigField(
+                type=list, default=["嗨！很开心见到你！😊", "Ciallo～(∠・ω< )⌒★"], description="默认问候消息"
+            ),
+            "enable_emoji": ConfigField(type=bool, default=True, description="是否启用表情符号"),
+        },
+        "time": {"format": ConfigField(type=str, default="%Y-%m-%d %H:%M:%S", description="时间显示格式")},
+        "print_message": {"enabled": ConfigField(type=bool, default=True, description="是否启用打印")},
+    }
+
+    def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
+        return [
+            (HelloAction.get_action_info(), HelloAction),
+            (CompareNumbersTool.get_tool_info(), CompareNumbersTool),  # 添加比较数字工具
+            (ByeAction.get_action_info(), ByeAction),  # 添加告别Action
+            (TimeCommand.get_command_info(), TimeCommand),
+            # (PrintMessage.get_handler_info(), PrintMessage),
+        ]
+
+
+# @register_plugin
+# class HelloWorldEventPlugin(BaseEPlugin):
+#     """Hello World事件插件 - 处理问候和告别事件"""
+
+#     plugin_name = "hello_world_event_plugin"
+#     enable_plugin = False
+#     dependencies = []
+#     python_dependencies = []
+#     config_file_name = "event_config.toml"
+
+#     config_schema = {
+#         "plugin": {
+#             "name": ConfigField(type=str, default="hello_world_event_plugin", description="插件名称"),
+#             "version": ConfigField(type=str, default="1.0.0", description="插件版本"),
+#             "enabled": ConfigField(type=bool, default=True, description="是否启用插件"),
+#         },
+#     }
+
+#     def get_plugin_components(self) -> List[Tuple[ComponentInfo, Type]]:
+#         return [(PrintMessage.get_handler_info(), PrintMessage)]

pyproject.toml

@@ -0,0 +1,111 @@
+[project]
+name = "MaiBot"
+version = "0.8.1"
+description = "MaiCore 是一个基于大语言模型的可交互智能体"
+requires-python = ">=3.10"
+dependencies = [
+    "aiohttp>=3.12.14",
+    "aiohttp-cors>=0.8.1",
+    "apscheduler>=3.11.0",
+    "colorama>=0.4.6",
+    "cryptography>=45.0.5",
+    "customtkinter>=5.2.2",
+    "dotenv>=0.9.9",
+    "faiss-cpu>=1.11.0",
+    "fastapi>=0.116.0",
+    "google>=3.0.0",
+    "google-genai>=1.29.0",
+    "jieba>=0.42.1",
+    "json-repair>=0.47.6",
+    "jsonlines>=4.0.0",
+    "maim-message>=0.3.8",
+    "matplotlib>=3.10.3",
+    "networkx>=3.4.2",
+    "numpy>=2.2.6",
+    "openai>=1.95.0",
+    "packaging>=25.0",
+    "pandas>=2.3.1",
+    "pillow>=11.3.0",
+    "psutil>=7.0.0",
+    "pyarrow>=20.0.0",
+    "pydantic>=2.11.7",
+    "pymongo>=4.13.2",
+    "pymysql>=1.1.1",
+    "pypinyin>=0.54.0",
+    "python-dateutil>=2.9.0.post0",
+    "python-dotenv>=1.1.1",
+    "python-igraph>=0.11.9",
+    "quick-algo>=0.1.3",
+    "reportportal-client>=5.6.5",
+    "requests>=2.32.4",
+    "rich>=14.0.0",
+    "ruff>=0.12.2",
+    "scikit-learn>=1.7.0",
+    "scipy>=1.15.3",
+    "seaborn>=0.13.2",
+    "setuptools>=80.9.0",
+    "sqlalchemy>=2.0.42",
+    "strawberry-graphql[fastapi]>=0.275.5",
+    "structlog>=25.4.0",
+    "toml>=0.10.2",
+    "tomli>=2.2.1",
+    "tomli-w>=1.2.0",
+    "tomlkit>=0.13.3",
+    "tqdm>=4.67.1",
+    "urllib3>=2.5.0",
+    "uvicorn>=0.35.0",
+    "watchdog>=6.0.0",
+    "websockets>=15.0.1",
+]
+
+[[tool.uv.index]]
+url = "https://pypi.tuna.tsinghua.edu.cn/simple"
+default = true
+
+[tool.ruff]
+
+include = ["*.py"]
+
+# 行长度设置
+line-length = 120
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+unfixable = []
+
+# 如果一个变量的名称以下划线开头，即使它未被使用，也不应该被视为错误或警告。
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+# 启用的规则
+select = [
+    "E", # pycodestyle 错误
+    "F", # pyflakes
+    "B", # flake8-bugbear
+]
+
+ignore = ["E711","E501"]
+
+[tool.ruff.format]
+docstring-code-format = true
+indent-style = "space"
+
+
+# 使用双引号表示字符串
+quote-style = "double"
+
+# 尊重魔法尾随逗号
+# 例如：
+# items = [
+#     "apple",
+#     "banana",
+#     "cherry",
+# ]
+skip-magic-trailing-comma = false
+
+# 自动检测合适的换行符
+line-ending = "auto"
+
+[dependency-groups]
+lint = [
+    "loguru>=0.7.3",
+]

requirements.lock

@@ -0,0 +1,271 @@
+# This file was autogenerated by uv via the following command:
+#    uv pip compile requirements.txt -o requirements.lock
+aenum==3.1.16
+    # via reportportal-client
+aiohappyeyeballs==2.6.1
+    # via aiohttp
+aiohttp==3.12.14
+    # via
+    #   -r requirements.txt
+    #   maim-message
+    #   reportportal-client
+aiosignal==1.4.0
+    # via aiohttp
+annotated-types==0.7.0
+    # via pydantic
+anyio==4.9.0
+    # via
+    #   httpx
+    #   openai
+    #   starlette
+apscheduler==3.11.0
+    # via -r requirements.txt
+attrs==25.3.0
+    # via
+    #   aiohttp
+    #   jsonlines
+certifi==2025.7.9
+    # via
+    #   httpcore
+    #   httpx
+    #   reportportal-client
+    #   requests
+cffi==1.17.1
+    # via cryptography
+charset-normalizer==3.4.2
+    # via requests
+click==8.2.1
+    # via uvicorn
+colorama==0.4.6
+    # via
+    #   -r requirements.txt
+    #   click
+    #   tqdm
+contourpy==1.3.2
+    # via matplotlib
+cryptography==45.0.5
+    # via
+    #   -r requirements.txt
+    #   maim-message
+customtkinter==5.2.2
+    # via -r requirements.txt
+cycler==0.12.1
+    # via matplotlib
+darkdetect==0.8.0
+    # via customtkinter
+distro==1.9.0
+    # via openai
+dnspython==2.7.0
+    # via pymongo
+dotenv==0.9.9
+    # via -r requirements.txt
+faiss-cpu==1.11.0
+    # via -r requirements.txt
+fastapi==0.116.0
+    # via
+    #   -r requirements.txt
+    #   maim-message
+    #   strawberry-graphql
+fonttools==4.58.5
+    # via matplotlib
+frozenlist==1.7.0
+    # via
+    #   aiohttp
+    #   aiosignal
+graphql-core==3.2.6
+    # via strawberry-graphql
+h11==0.16.0
+    # via
+    #   httpcore
+    #   uvicorn
+httpcore==1.0.9
+    # via httpx
+httpx==0.28.1
+    # via openai
+idna==3.10
+    # via
+    #   anyio
+    #   httpx
+    #   requests
+    #   yarl
+igraph==0.11.9
+    # via python-igraph
+jieba==0.42.1
+    # via -r requirements.txt
+jiter==0.10.0
+    # via openai
+joblib==1.5.1
+    # via scikit-learn
+json-repair==0.47.6
+    # via -r requirements.txt
+jsonlines==4.0.0
+    # via -r requirements.txt
+kiwisolver==1.4.8
+    # via matplotlib
+maim-message==0.3.8
+    # via -r requirements.txt
+markdown-it-py==3.0.0
+    # via rich
+matplotlib==3.10.3
+    # via
+    #   -r requirements.txt
+    #   seaborn
+mdurl==0.1.2
+    # via markdown-it-py
+multidict==6.6.3
+    # via
+    #   aiohttp
+    #   yarl
+networkx==3.5
+    # via -r requirements.txt
+numpy==2.3.1
+    # via
+    #   -r requirements.txt
+    #   contourpy
+    #   faiss-cpu
+    #   matplotlib
+    #   pandas
+    #   scikit-learn
+    #   scipy
+    #   seaborn
+openai==1.95.0
+    # via -r requirements.txt
+packaging==25.0
+    # via
+    #   -r requirements.txt
+    #   customtkinter
+    #   faiss-cpu
+    #   matplotlib
+    #   strawberry-graphql
+pandas==2.3.1
+    # via
+    #   -r requirements.txt
+    #   seaborn
+peewee==3.18.2
+    # via -r requirements.txt
+pillow==11.3.0
+    # via
+    #   -r requirements.txt
+    #   matplotlib
+propcache==0.3.2
+    # via
+    #   aiohttp
+    #   yarl
+psutil==7.0.0
+    # via -r requirements.txt
+pyarrow==20.0.0
+    # via -r requirements.txt
+pycparser==2.22
+    # via cffi
+pydantic==2.11.7
+    # via
+    #   -r requirements.txt
+    #   fastapi
+    #   maim-message
+    #   openai
+pydantic-core==2.33.2
+    # via pydantic
+pygments==2.19.2
+    # via rich
+pymongo==4.13.2
+    # via -r requirements.txt
+pyparsing==3.2.3
+    # via matplotlib
+pypinyin==0.54.0
+    # via -r requirements.txt
+python-dateutil==2.9.0.post0
+    # via
+    #   -r requirements.txt
+    #   matplotlib
+    #   pandas
+    #   strawberry-graphql
+python-dotenv==1.1.1
+    # via
+    #   -r requirements.txt
+    #   dotenv
+python-igraph==0.11.9
+    # via -r requirements.txt
+python-multipart==0.0.20
+    # via strawberry-graphql
+pytz==2025.2
+    # via pandas
+quick-algo==0.1.3
+    # via -r requirements.txt
+reportportal-client==5.6.5
+    # via -r requirements.txt
+requests==2.32.4
+    # via
+    #   -r requirements.txt
+    #   reportportal-client
+rich==14.0.0
+    # via -r requirements.txt
+ruff==0.12.2
+    # via -r requirements.txt
+scikit-learn==1.7.0
+    # via -r requirements.txt
+scipy==1.16.0
+    # via
+    #   -r requirements.txt
+    #   scikit-learn
+seaborn==0.13.2
+    # via -r requirements.txt
+setuptools==80.9.0
+    # via -r requirements.txt
+six==1.17.0
+    # via python-dateutil
+sniffio==1.3.1
+    # via
+    #   anyio
+    #   openai
+starlette==0.46.2
+    # via fastapi
+strawberry-graphql==0.275.5
+    # via -r requirements.txt
+structlog==25.4.0
+    # via -r requirements.txt
+texttable==1.7.0
+    # via igraph
+threadpoolctl==3.6.0
+    # via scikit-learn
+toml==0.10.2
+    # via -r requirements.txt
+tomli==2.2.1
+    # via -r requirements.txt
+tomli-w==1.2.0
+    # via -r requirements.txt
+tomlkit==0.13.3
+    # via -r requirements.txt
+tqdm==4.67.1
+    # via
+    #   -r requirements.txt
+    #   openai
+typing-extensions==4.14.1
+    # via
+    #   fastapi
+    #   openai
+    #   pydantic
+    #   pydantic-core
+    #   strawberry-graphql
+    #   typing-inspection
+typing-inspection==0.4.1
+    # via pydantic
+tzdata==2025.2
+    # via
+    #   pandas
+    #   tzlocal
+tzlocal==5.3.1
+    # via apscheduler
+urllib3==2.5.0
+    # via
+    #   -r requirements.txt
+    #   requests
+uvicorn==0.35.0
+    # via
+    #   -r requirements.txt
+    #   maim-message
+websockets==15.0.1
+    # via
+    #   -r requirements.txt
+    #   maim-message
+yarl==1.20.1
+    # via aiohttp

requirements.txt

@@ -0,0 +1,51 @@
+sqlalchemy
+APScheduler
+Pillow
+aiohttp
+aiohttp-cors
+colorama
+customtkinter
+dotenv
+faiss-cpu
+fastapi
+jieba
+jsonlines
+maim_message
+quick_algo
+matplotlib
+networkx
+numpy
+openai
+google-genai
+pandas
+peewee
+pyarrow
+pydantic
+pypinyin
+python-dateutil
+python-dotenv
+python-igraph
+pymongo
+requests
+ruff
+scipy
+setuptools
+toml
+tomli
+tomli_w
+tomlkit
+tqdm
+urllib3
+uvicorn
+websockets
+strawberry-graphql[fastapi]
+packaging
+rich
+psutil
+cryptography
+json-repair
+reportportal-client
+scikit-learn
+seaborn
+structlog
+watchdog

src/chat/__init__.py

@@ -0,0 +1,13 @@
+"""
+MaiBot模块系统
+包含聊天、情绪、记忆、日程等功能模块
+"""
+
+from src.chat.message_receive.chat_stream import get_chat_manager
+from src.chat.emoji_system.emoji_manager import get_emoji_manager
+
+# 导出主要组件供外部使用
+__all__ = [
+    "get_chat_manager",
+    "get_emoji_manager",
+]

src/chat/chat_loop/heartFC_chat.py

@@ -0,0 +1,929 @@
+import asyncio
+import time
+import traceback
+import random
+from typing import List, Optional, Dict, Any, Tuple
+from rich.traceback import install
+
+from src.config.config import global_config
+from src.common.logger import get_logger
+from src.chat.message_receive.chat_stream import ChatStream, get_chat_manager
+from src.chat.utils.prompt_builder import global_prompt_manager
+from src.chat.utils.timer_calculator import Timer
+from src.chat.planner_actions.planner import ActionPlanner
+from src.chat.planner_actions.action_modifier import ActionModifier
+from src.chat.planner_actions.action_manager import ActionManager
+from src.chat.chat_loop.hfc_utils import CycleDetail
+from src.person_info.relationship_builder_manager import relationship_builder_manager
+from src.chat.express.expression_learner import expression_learner_manager
+from src.person_info.person_info import get_person_info_manager
+from src.plugin_system.base.component_types import ActionInfo, ChatMode, EventType
+from src.plugin_system.core import events_manager
+from src.plugin_system.apis import generator_api, send_api, message_api, database_api
+from src.chat.willing.willing_manager import get_willing_manager
+from src.mais4u.mai_think import mai_thinking_manager
+from src.mais4u.constant_s4u import ENABLE_S4U
+from src.plugins.built_in.core_actions.no_reply import NoReplyAction
+from src.chat.chat_loop.hfc_utils import send_typing, stop_typing
+
+ERROR_LOOP_INFO = {
+    "loop_plan_info": {
+        "action_result": {
+            "action_type": "error",
+            "action_data": {},
+            "reasoning": "循环处理失败",
+        },
+    },
+    "loop_action_info": {
+        "action_taken": False,
+        "reply_text": "",
+        "command": "",
+        "taken_time": time.time(),
+    },
+}
+
+NO_ACTION = {
+    "action_result": {
+        "action_type": "no_action",
+        "action_data": {},
+        "reasoning": "规划器初始化默认",
+        "is_parallel": True,
+    },
+    "chat_context": "",
+    "action_prompt": "",
+}
+
+install(extra_lines=3)
+
+# 注释：原来的动作修改超时常量已移除，因为改为顺序执行
+
+logger = get_logger("hfc")  # Logger Name Changed
+
+
+class HeartFChatting:
+    """
+    管理一个连续的Focus Chat循环
+    用于在特定聊天流中生成回复。
+    其生命周期现在由其关联的 SubHeartflow 的 FOCUSED 状态控制。
+    """
+
+    def __init__(
+        self,
+        chat_id: str,
+    ):
+        """
+        HeartFChatting 初始化函数
+
+        参数:
+            chat_id: 聊天流唯一标识符(如stream_id)
+            on_stop_focus_chat: 当收到stop_focus_chat命令时调用的回调函数
+            performance_version: 性能记录版本号，用于区分不同启动版本
+        """
+        # 基础属性
+        self.stream_id: str = chat_id  # 聊天流ID
+        self.chat_stream: ChatStream = get_chat_manager().get_stream(self.stream_id)  # type: ignore
+        if not self.chat_stream:
+            raise ValueError(f"无法找到聊天流: {self.stream_id}")
+        self.log_prefix = f"[{get_chat_manager().get_stream_name(self.stream_id) or self.stream_id}]"
+
+        self.relationship_builder = relationship_builder_manager.get_or_create_builder(self.stream_id)
+        self.expression_learner = expression_learner_manager.get_expression_learner(self.stream_id)
+
+        self.loop_mode = ChatMode.NORMAL  # 初始循环模式为普通模式
+        
+        self.last_action = "no_action"
+
+        self.action_manager = ActionManager()
+        self.action_planner = ActionPlanner(chat_id=self.stream_id, action_manager=self.action_manager)
+        self.action_modifier = ActionModifier(action_manager=self.action_manager, chat_id=self.stream_id)
+
+        # 循环控制内部状态
+        self.running: bool = False
+        self._loop_task: Optional[asyncio.Task] = None  # 主循环任务
+        self._energy_task: Optional[asyncio.Task] = None
+
+        # 添加循环信息管理相关的属性
+        self.history_loop: List[CycleDetail] = []
+        self._cycle_counter = 0
+        self._current_cycle_detail: CycleDetail = None  # type: ignore
+
+        self.reply_timeout_count = 0
+        self.plan_timeout_count = 0
+
+        self.last_read_time = time.time() - 1
+
+        self.willing_manager = get_willing_manager()
+
+        logger.info(f"{self.log_prefix} HeartFChatting 初始化完成")
+
+        self.energy_value = 5
+        
+        self.focus_energy = 1
+        self.no_reply_consecutive = 0
+
+    async def start(self):
+        """检查是否需要启动主循环，如果未激活则启动。"""
+
+        # 如果循环已经激活，直接返回
+        if self.running:
+            logger.debug(f"{self.log_prefix} HeartFChatting 已激活，无需重复启动")
+            return
+
+        try:
+            # 标记为活动状态，防止重复启动
+            self.running = True
+
+            self._energy_task = asyncio.create_task(self._energy_loop())
+            self._energy_task.add_done_callback(self._handle_energy_completion)
+
+            self._loop_task = asyncio.create_task(self._main_chat_loop())
+            self._loop_task.add_done_callback(self._handle_loop_completion)
+            logger.info(f"{self.log_prefix} HeartFChatting 启动完成")
+
+        except Exception as e:
+            # 启动失败时重置状态
+            self.running = False
+            self._loop_task = None
+            logger.error(f"{self.log_prefix} HeartFChatting 启动失败: {e}")
+            raise
+
+    def _handle_loop_completion(self, task: asyncio.Task):
+        """当 _hfc_loop 任务完成时执行的回调。"""
+        try:
+            if exception := task.exception():
+                logger.error(f"{self.log_prefix} HeartFChatting: 脱离了聊天(异常): {exception}")
+                logger.error(traceback.format_exc())  # Log full traceback for exceptions
+            else:
+                logger.info(f"{self.log_prefix} HeartFChatting: 脱离了聊天 (外部停止)")
+        except asyncio.CancelledError:
+            logger.info(f"{self.log_prefix} HeartFChatting: 结束了聊天")
+
+    def start_cycle(self):
+        self._cycle_counter += 1
+        self._current_cycle_detail = CycleDetail(self._cycle_counter)
+        self._current_cycle_detail.thinking_id = f"tid{str(round(time.time(), 2))}"
+        cycle_timers = {}
+        return cycle_timers, self._current_cycle_detail.thinking_id
+
+    def end_cycle(self, loop_info, cycle_timers):
+        self._current_cycle_detail.set_loop_info(loop_info)
+        self.history_loop.append(self._current_cycle_detail)
+        self._current_cycle_detail.timers = cycle_timers
+        self._current_cycle_detail.end_time = time.time()
+
+    def _handle_energy_completion(self, task: asyncio.Task):
+        if exception := task.exception():
+            logger.error(f"{self.log_prefix} HeartFChatting: 能量循环异常: {exception}")
+            logger.error(traceback.format_exc())
+        else:
+            logger.info(f"{self.log_prefix} HeartFChatting: 能量循环完成")
+
+    async def _energy_loop(self):
+        while self.running:
+            await asyncio.sleep(10)
+            if self.loop_mode == ChatMode.NORMAL:
+                self.energy_value -= 0.3
+                self.energy_value = max(self.energy_value, 0.3)
+            if self.loop_mode == ChatMode.FOCUS:
+                self.energy_value -= 0.6
+                self.energy_value = max(self.energy_value, 0.3)
+
+    def print_cycle_info(self, cycle_timers):
+        # 记录循环信息和计时器结果
+        timer_strings = []
+        for name, elapsed in cycle_timers.items():
+            formatted_time = f"{elapsed * 1000:.2f}毫秒" if elapsed < 1 else f"{elapsed:.2f}秒"
+            timer_strings.append(f"{name}: {formatted_time}")
+
+        logger.info(
+            f"{self.log_prefix} 第{self._current_cycle_detail.cycle_id}次思考,"
+            f"耗时: {self._current_cycle_detail.end_time - self._current_cycle_detail.start_time:.1f}秒, "  # type: ignore
+            f"选择动作: {self._current_cycle_detail.loop_plan_info.get('action_result', {}).get('action_type', '未知动作')}"
+            + (f"\n详情: {'; '.join(timer_strings)}" if timer_strings else "")
+        )
+        
+    def _determine_form_type(self) -> str:
+        """判断使用哪种形式的no_reply"""
+        # 如果连续no_reply次数少于3次，使用waiting形式
+        if self.no_reply_consecutive <= 3:
+            self.focus_energy = 1
+        else:
+            # 计算最近三次记录的兴趣度总和
+            total_recent_interest = sum(NoReplyAction._recent_interest_records)
+        
+            # 获取当前聊天频率和意愿系数
+            talk_frequency = global_config.chat.get_current_talk_frequency(self.stream_id)
+    
+            # 计算调整后的阈值
+            adjusted_threshold = 3 / talk_frequency
+            
+            logger.info(f"{self.log_prefix} 最近三次兴趣度总和: {total_recent_interest:.2f}, 调整后阈值: {adjusted_threshold:.2f}")
+        
+            # 如果兴趣度总和小于阈值，进入breaking形式
+            if total_recent_interest < adjusted_threshold:
+                logger.info(f"{self.log_prefix} 兴趣度不足，进入breaking形式")
+                self.focus_energy = random.randint(3, 6)
+            else:
+                logger.info(f"{self.log_prefix} 兴趣度充足")
+                self.focus_energy = 1      
+            
+    async def _execute_no_reply(self, new_message:List[Dict[str, Any]]) -> Tuple[bool, str]:
+        """执行breaking形式的no_reply（原有逻辑）"""
+        new_message_count = len(new_message)
+        # 检查消息数量是否达到阈值
+        talk_frequency = global_config.chat.get_current_talk_frequency(self.stream_id)
+        modified_exit_count_threshold = self.focus_energy / talk_frequency
+        
+        if new_message_count >= modified_exit_count_threshold:
+            # 记录兴趣度到列表
+            total_interest = 0.0
+            for msg_dict in new_message:
+                interest_value = msg_dict.get("interest_value", 0.0)
+                if msg_dict.get("processed_plain_text", ""):
+                    total_interest += interest_value
+            
+            NoReplyAction._recent_interest_records.append(total_interest)
+            
+            logger.info(
+                f"{self.log_prefix} 累计消息数量达到{new_message_count}条(>{modified_exit_count_threshold})，结束等待"
+            )
+
+            return True
+
+        # 检查累计兴趣值
+        if new_message_count > 0:
+            accumulated_interest = 0.0
+            for msg_dict in new_message:
+                text = msg_dict.get("processed_plain_text", "")
+                interest_value = msg_dict.get("interest_value", 0.0)
+                if text:
+                    accumulated_interest += interest_value
+            
+            # 只在兴趣值变化时输出log
+            if not hasattr(self, "_last_accumulated_interest") or accumulated_interest != self._last_accumulated_interest:
+                logger.info(f"{self.log_prefix} breaking形式当前累计兴趣值: {accumulated_interest:.2f}, 当前聊天频率: {talk_frequency:.2f}")
+                self._last_accumulated_interest = accumulated_interest
+            
+            if accumulated_interest >= 3 / talk_frequency:
+                # 记录兴趣度到列表
+                NoReplyAction._recent_interest_records.append(accumulated_interest)
+                
+                logger.info(
+                    f"{self.log_prefix} 累计兴趣值达到{accumulated_interest:.2f}(>{5 / talk_frequency})，结束等待"
+                )
+                return True
+
+        # 每10秒输出一次等待状态
+        if int(time.time() - self.last_read_time) > 0 and int(time.time() - self.last_read_time) % 10 == 0:
+            logger.info(
+                f"{self.log_prefix} 已等待{time.time() - self.last_read_time:.0f}秒，累计{new_message_count}条消息，继续等待..."
+            )
+
+
+    async def _loopbody(self):
+        recent_messages_dict = message_api.get_messages_by_time_in_chat(
+            chat_id=self.stream_id,
+            start_time=self.last_read_time,
+            end_time=time.time(),
+            limit = 10,
+            limit_mode="latest",
+            filter_mai=True,
+            filter_command=True,
+        )
+        new_message_count = len(recent_messages_dict)
+        
+        
+        if self.loop_mode == ChatMode.FOCUS:
+            
+            if self.last_action == "no_reply":
+                if not await self._execute_no_reply(recent_messages_dict):
+                    self.energy_value -= 0.3 / global_config.chat.focus_value
+                    logger.info(f"{self.log_prefix} 能量值减少，当前能量值：{self.energy_value:.1f}")
+                    await asyncio.sleep(0.5)
+                    return True
+            
+            self.last_read_time = time.time()
+            
+            if await self._observe():
+                self.energy_value += 1 / global_config.chat.focus_value
+                logger.info(f"{self.log_prefix} 能量值增加，当前能量值：{self.energy_value:.1f}")
+
+            if self.energy_value <= 1:
+                self.energy_value = 1
+                self.loop_mode = ChatMode.NORMAL
+                return True
+
+            return True
+        elif self.loop_mode == ChatMode.NORMAL:
+            if global_config.chat.focus_value != 0:
+                if new_message_count > 3 / pow(global_config.chat.focus_value, 0.5):
+                    self.loop_mode = ChatMode.FOCUS
+                    self.energy_value = (
+                        10 + (new_message_count / (3 / pow(global_config.chat.focus_value, 0.5))) * 10
+                    )
+                    return True
+
+                if self.energy_value >= 30:
+                    self.loop_mode = ChatMode.FOCUS
+                    return True
+
+            if new_message_count >= self.focus_energy:
+                earliest_messages_data = recent_messages_dict[0]
+                self.last_read_time = earliest_messages_data.get("time")
+
+                if_think = await self.normal_response(earliest_messages_data)
+                if if_think:
+                    factor = max(global_config.chat.focus_value, 0.1)
+                    self.energy_value *= 1.1 * factor
+                    logger.info(f"{self.log_prefix} 进行了思考，能量值按倍数增加，当前能量值：{self.energy_value:.1f}")
+                else:
+                    self.energy_value += 0.1 * global_config.chat.focus_value
+                    logger.debug(f"{self.log_prefix} 没有进行思考，能量值线性增加，当前能量值：{self.energy_value:.1f}")
+
+                logger.debug(f"{self.log_prefix} 当前能量值：{self.energy_value:.1f}")
+                return True
+
+            await asyncio.sleep(0.5)
+
+            return True
+
+    async def build_reply_to_str(self, message_data: dict):
+        person_info_manager = get_person_info_manager()
+        person_id = person_info_manager.get_person_id(
+            message_data.get("chat_info_platform"),  # type: ignore
+            message_data.get("user_id"),  # type: ignore
+        )
+        person_name = await person_info_manager.get_value(person_id, "person_name")
+        return f"{person_name}:{message_data.get('processed_plain_text')}"
+
+    async def _send_and_store_reply(
+        self,
+        response_set,
+        reply_to_str,
+        loop_start_time,
+        action_message,
+        cycle_timers: Dict[str, float],
+        thinking_id,
+        plan_result,
+    ) -> Tuple[Dict[str, Any], str, Dict[str, float]]:
+        with Timer("回复发送", cycle_timers):
+            reply_text = await self._send_response(response_set, reply_to_str, loop_start_time, action_message)
+
+            # 存储reply action信息
+        person_info_manager = get_person_info_manager()
+        person_id = person_info_manager.get_person_id(
+            action_message.get("chat_info_platform", ""),
+            action_message.get("user_id", ""),
+        )
+        person_name = await person_info_manager.get_value(person_id, "person_name")
+        action_prompt_display = f"你对{person_name}进行了回复：{reply_text}"
+
+        await database_api.store_action_info(
+            chat_stream=self.chat_stream,
+            action_build_into_prompt=False,
+            action_prompt_display=action_prompt_display,
+            action_done=True,
+            thinking_id=thinking_id,
+            action_data={"reply_text": reply_text, "reply_to": reply_to_str},
+            action_name="reply",
+        )
+
+        # 构建循环信息
+        loop_info: Dict[str, Any] = {
+            "loop_plan_info": {
+                "action_result": plan_result.get("action_result", {}),
+            },
+            "loop_action_info": {
+                "action_taken": True,
+                "reply_text": reply_text,
+                "command": "",
+                "taken_time": time.time(),
+            },
+        }
+
+        return loop_info, reply_text, cycle_timers
+
+    async def _observe(self, message_data: Optional[Dict[str, Any]] = None) -> bool:
+        if not message_data:
+            message_data = {}
+        action_type = "no_action"
+        reply_text = ""  # 初始化reply_text变量，避免UnboundLocalError
+        gen_task = None  # 初始化gen_task变量，避免UnboundLocalError
+        reply_to_str = ""  # 初始化reply_to_str变量
+
+        # 创建新的循环信息
+        cycle_timers, thinking_id = self.start_cycle()
+
+        logger.info(f"{self.log_prefix} 开始第{self._cycle_counter}次思考[模式：{self.loop_mode}]")
+
+        if ENABLE_S4U:
+            await send_typing()
+
+        async with global_prompt_manager.async_message_scope(self.chat_stream.context.get_template_name()):
+            loop_start_time = time.time()
+            await self.relationship_builder.build_relation()
+            await self.expression_learner.trigger_learning_for_chat()
+
+            available_actions = {}
+
+            # 第一步：动作修改
+            with Timer("动作修改", cycle_timers):
+                try:
+                    await self.action_modifier.modify_actions()
+                    available_actions = self.action_manager.get_using_actions()
+                except Exception as e:
+                    logger.error(f"{self.log_prefix} 动作修改失败: {e}")
+
+            # 检查是否在normal模式下没有可用动作（除了reply相关动作）
+            skip_planner = False
+            if self.loop_mode == ChatMode.NORMAL:
+                # 过滤掉reply相关的动作，检查是否还有其他动作
+                non_reply_actions = {
+                    k: v for k, v in available_actions.items() if k not in ["reply", "no_reply", "no_action"]
+                }
+
+                if not non_reply_actions:
+                    skip_planner = True
+                    logger.info(f"{self.log_prefix} Normal模式下没有可用动作，直接回复")
+
+                    # 直接设置为reply动作
+                    action_type = "reply"
+                    reasoning = ""
+                    action_data = {"loop_start_time": loop_start_time}
+                    is_parallel = False
+
+                    # 构建plan_result用于后续处理
+                    plan_result = {
+                        "action_result": {
+                            "action_type": action_type,
+                            "action_data": action_data,
+                            "reasoning": reasoning,
+                            "timestamp": time.time(),
+                            "is_parallel": is_parallel,
+                        },
+                        "action_prompt": "",
+                    }
+                    target_message = message_data
+
+                # 如果normal模式且不跳过规划器，开始一个回复生成进程，先准备好回复（其实是和planer同时进行的）
+                if not skip_planner:
+                    reply_to_str = await self.build_reply_to_str(message_data)
+                    gen_task = asyncio.create_task(
+                        self._generate_response(
+                            message_data=message_data,
+                            available_actions=available_actions,
+                            reply_to=reply_to_str,
+                            request_type="chat.replyer.normal",
+                        )
+                    )
+
+            if not skip_planner:
+                planner_info = self.action_planner.get_necessary_info()
+                prompt_info = await self.action_planner.build_planner_prompt(
+                    is_group_chat=planner_info[0],
+                    chat_target_info=planner_info[1],
+                    current_available_actions=planner_info[2],
+                )
+                if not await events_manager.handle_mai_events(
+                    EventType.ON_PLAN, None, prompt_info[0], None, self.chat_stream.stream_id
+                ):
+                    return False
+                with Timer("规划器", cycle_timers):
+                    plan_result, target_message = await self.action_planner.plan(mode=self.loop_mode)
+
+                action_result: Dict[str, Any] = plan_result.get("action_result", {})  # type: ignore
+                action_type, action_data, reasoning, is_parallel = (
+                    action_result.get("action_type", "error"),
+                    action_result.get("action_data", {}),
+                    action_result.get("reasoning", "未提供理由"),
+                    action_result.get("is_parallel", True),
+                )
+
+                action_data["loop_start_time"] = loop_start_time
+
+            if action_type == "reply":
+                logger.info(f"{self.log_prefix}{global_config.bot.nickname} 决定进行回复")
+            elif is_parallel:
+                logger.info(f"{self.log_prefix}{global_config.bot.nickname} 决定进行回复, 同时执行{action_type}动作")
+            else:
+                # 只有在gen_task存在时才进行相关操作
+                if gen_task:
+                    if not gen_task.done():
+                        gen_task.cancel()
+                        logger.debug(f"{self.log_prefix} 已取消预生成的回复任务")
+                        logger.info(
+                            f"{self.log_prefix}{global_config.bot.nickname} 原本想要回复，但选择执行{action_type}，不发表回复"
+                        )
+                    elif generation_result := gen_task.result():
+                        content = " ".join([item[1] for item in generation_result if item[0] == "text"])
+                        logger.debug(f"{self.log_prefix} 预生成的回复任务已完成")
+                        logger.info(
+                            f"{self.log_prefix}{global_config.bot.nickname} 原本想要回复：{content}，但选择执行{action_type}，不发表回复"
+                        )
+                    else:
+                        logger.warning(f"{self.log_prefix} 预生成的回复任务未生成有效内容")
+
+            action_message = message_data or target_message
+            if action_type == "reply":
+                # 等待回复生成完毕
+                if self.loop_mode == ChatMode.NORMAL:
+                    # 只有在gen_task存在时才等待
+                    if not gen_task:
+                        reply_to_str = await self.build_reply_to_str(message_data)
+                        gen_task = asyncio.create_task(
+                            self._generate_response(
+                                message_data=message_data,
+                                available_actions=available_actions,
+                                reply_to=reply_to_str,
+                                request_type="chat.replyer.normal",
+                            )
+                        )
+
+                    gather_timeout = global_config.chat.thinking_timeout
+                    try:
+                        response_set = await asyncio.wait_for(gen_task, timeout=gather_timeout)
+                    except asyncio.TimeoutError:
+                        logger.warning(f"{self.log_prefix} 回复生成超时>{global_config.chat.thinking_timeout}s，已跳过")
+                        response_set = None
+
+                    # 模型炸了或超时，没有回复内容生成
+                    if not response_set:
+                        logger.warning(f"{self.log_prefix}模型未生成回复内容")
+                        return False
+                else:
+                    logger.info(f"{self.log_prefix}{global_config.bot.nickname} 决定进行回复 (focus模式)")
+
+                    # 构建reply_to字符串
+                    reply_to_str = await self.build_reply_to_str(action_message)
+
+                    # 生成回复
+                    with Timer("回复生成", cycle_timers):
+                        response_set = await self._generate_response(
+                            message_data=action_message,
+                            available_actions=available_actions,
+                            reply_to=reply_to_str,
+                            request_type="chat.replyer.focus",
+                        )
+
+                    if not response_set:
+                        logger.warning(f"{self.log_prefix}模型未生成回复内容")
+                        return False
+
+                loop_info, reply_text, cycle_timers = await self._send_and_store_reply(
+                    response_set, reply_to_str, loop_start_time, action_message, cycle_timers, thinking_id, plan_result
+                )
+
+                return True
+
+            else:
+                # 并行执行：同时进行回复发送和动作执行
+                # 先置空防止未定义错误
+                background_reply_task = None
+                background_action_task = None
+                # 如果是并行执行且在normal模式下，需要等待预生成的回复任务完成并发送回复
+                if self.loop_mode == ChatMode.NORMAL and is_parallel and gen_task:
+
+                    async def handle_reply_task() -> Tuple[Optional[Dict[str, Any]], str, Dict[str, float]]:
+                        # 等待预生成的回复任务完成
+                        gather_timeout = global_config.chat.thinking_timeout
+                        try:
+                            response_set = await asyncio.wait_for(gen_task, timeout=gather_timeout)
+
+                        except asyncio.TimeoutError:
+                            logger.warning(
+                                f"{self.log_prefix} 并行执行：回复生成超时>{global_config.chat.thinking_timeout}s，已跳过"
+                            )
+                            return None, "", {}
+                        except asyncio.CancelledError:
+                            logger.debug(f"{self.log_prefix} 并行执行：回复生成任务已被取消")
+                            return None, "", {}
+
+                        if not response_set:
+                            logger.warning(f"{self.log_prefix} 模型超时或生成回复内容为空")
+                            return None, "", {}
+
+                        reply_to_str = await self.build_reply_to_str(action_message)
+                        loop_info, reply_text, cycle_timers_reply = await self._send_and_store_reply(
+                            response_set,
+                            reply_to_str,
+                            loop_start_time,
+                            action_message,
+                            cycle_timers,
+                            thinking_id,
+                            plan_result,
+                        )
+                        return loop_info, reply_text, cycle_timers_reply
+
+                    # 执行回复任务并赋值到变量
+                    background_reply_task = asyncio.create_task(handle_reply_task())
+
+                # 动作执行任务
+                async def handle_action_task():
+                    with Timer("动作执行", cycle_timers):
+                        success, reply_text, command = await self._handle_action(
+                            action_type, reasoning, action_data, cycle_timers, thinking_id, action_message
+                        )
+                    return success, reply_text, command
+
+                # 执行动作任务并赋值到变量
+                background_action_task = asyncio.create_task(handle_action_task())
+
+                reply_loop_info = None
+                reply_text_from_reply = ""
+                action_success = False
+                action_reply_text = ""
+                action_command = ""
+
+                # 并行执行所有任务
+                if background_reply_task:
+                    results = await asyncio.gather(
+                        background_reply_task, background_action_task, return_exceptions=True
+                    )
+                    # 处理回复任务结果
+                    reply_result = results[0]
+                    if isinstance(reply_result, BaseException):
+                        logger.error(f"{self.log_prefix} 回复任务执行异常: {reply_result}")
+                    elif reply_result and reply_result[0] is not None:
+                        reply_loop_info, reply_text_from_reply, _ = reply_result
+
+                    # 处理动作任务结果
+                    action_task_result = results[1]
+                    if isinstance(action_task_result, BaseException):
+                        logger.error(f"{self.log_prefix} 动作任务执行异常: {action_task_result}")
+                    else:
+                        action_success, action_reply_text, action_command = action_task_result
+                else:
+                    results = await asyncio.gather(background_action_task, return_exceptions=True)
+                    # 只有动作任务
+                    action_task_result = results[0]
+                    if isinstance(action_task_result, BaseException):
+                        logger.error(f"{self.log_prefix} 动作任务执行异常: {action_task_result}")
+                    else:
+                        action_success, action_reply_text, action_command = action_task_result
+
+                # 构建最终的循环信息
+                if reply_loop_info:
+                    # 如果有回复信息，使用回复的loop_info作为基础
+                    loop_info = reply_loop_info
+                    # 更新动作执行信息
+                    loop_info["loop_action_info"].update(
+                        {
+                            "action_taken": action_success,
+                            "command": action_command,
+                            "taken_time": time.time(),
+                        }
+                    )
+                    reply_text = reply_text_from_reply
+                else:
+                    # 没有回复信息，构建纯动作的loop_info
+                    loop_info = {
+                        "loop_plan_info": {
+                            "action_result": plan_result.get("action_result", {}),
+                        },
+                        "loop_action_info": {
+                            "action_taken": action_success,
+                            "reply_text": action_reply_text,
+                            "command": action_command,
+                            "taken_time": time.time(),
+                        },
+                    }
+                    reply_text = action_reply_text
+                    
+        self.last_action = action_type
+
+        if ENABLE_S4U:
+            await stop_typing()
+            await mai_thinking_manager.get_mai_think(self.stream_id).do_think_after_response(reply_text)
+
+        self.end_cycle(loop_info, cycle_timers)
+        self.print_cycle_info(cycle_timers)
+
+        if self.loop_mode == ChatMode.NORMAL:
+            await self.willing_manager.after_generate_reply_handle(message_data.get("message_id", ""))
+
+        # 管理no_reply计数器：当执行了非no_reply动作时，重置计数器
+        if action_type != "no_reply" and action_type != "no_action":
+            # 导入NoReplyAction并重置计数器
+            NoReplyAction.reset_consecutive_count()
+            self.no_reply_consecutive = 0
+            logger.info(f"{self.log_prefix} 执行了{action_type}动作，重置no_reply计数器")
+            return True
+        elif action_type == "no_action":
+            # 当执行回复动作时，也重置no_reply计数
+            NoReplyAction.reset_consecutive_count()
+            self.no_reply_consecutive = 0
+            logger.info(f"{self.log_prefix} 执行了回复动作，重置no_reply计数器")
+            
+        if action_type == "no_reply":
+            self.no_reply_consecutive += 1
+            self._determine_form_type()
+
+        return True
+
+    async def _main_chat_loop(self):
+        """主循环，持续进行计划并可能回复消息，直到被外部取消。"""
+        try:
+            while self.running:
+                # 主循环
+                success = await self._loopbody()
+                await asyncio.sleep(0.1)
+                if not success:
+                    break
+        except asyncio.CancelledError:
+            # 设置了关闭标志位后被取消是正常流程
+            logger.info(f"{self.log_prefix} 麦麦已关闭聊天")
+        except Exception:
+            logger.error(f"{self.log_prefix} 麦麦聊天意外错误，将于3s后尝试重新启动")
+            print(traceback.format_exc())
+            await asyncio.sleep(3)
+            self._loop_task = asyncio.create_task(self._main_chat_loop())
+        logger.error(f"{self.log_prefix} 结束了当前聊天循环")
+
+    async def _handle_action(
+        self,
+        action: str,
+        reasoning: str,
+        action_data: dict,
+        cycle_timers: Dict[str, float],
+        thinking_id: str,
+        action_message: dict,
+    ) -> tuple[bool, str, str]:
+        """
+        处理规划动作，使用动作工厂创建相应的动作处理器
+
+        参数:
+            action: 动作类型
+            reasoning: 决策理由
+            action_data: 动作数据，包含不同动作需要的参数
+            cycle_timers: 计时器字典
+            thinking_id: 思考ID
+
+        返回:
+            tuple[bool, str, str]: (是否执行了动作, 思考消息ID, 命令)
+        """
+        try:
+            # 使用工厂创建动作处理器实例
+            try:
+                action_handler = self.action_manager.create_action(
+                    action_name=action,
+                    action_data=action_data,
+                    reasoning=reasoning,
+                    cycle_timers=cycle_timers,
+                    thinking_id=thinking_id,
+                    chat_stream=self.chat_stream,
+                    log_prefix=self.log_prefix,
+                    action_message=action_message,
+                )
+            except Exception as e:
+                logger.error(f"{self.log_prefix} 创建动作处理器时出错: {e}")
+                traceback.print_exc()
+                return False, "", ""
+
+            if not action_handler:
+                logger.warning(f"{self.log_prefix} 未能创建动作处理器: {action}")
+                return False, "", ""
+
+            # 处理动作并获取结果
+            result = await action_handler.handle_action()
+            success, reply_text = result
+            command = ""
+
+            if reply_text == "timeout":
+                self.reply_timeout_count += 1
+                if self.reply_timeout_count > 5:
+                    logger.warning(
+                        f"[{self.log_prefix} ] 连续回复超时次数过多，{global_config.chat.thinking_timeout}秒 内大模型没有返回有效内容，请检查你的api是否速度过慢或配置错误。建议不要使用推理模型，推理模型生成速度过慢。或者尝试拉高thinking_timeout参数，这可能导致回复时间过长。"
+                    )
+                logger.warning(f"{self.log_prefix} 回复生成超时{global_config.chat.thinking_timeout}s，已跳过")
+                return False, "", ""
+
+            return success, reply_text, command
+
+        except Exception as e:
+            logger.error(f"{self.log_prefix} 处理{action}时出错: {e}")
+            traceback.print_exc()
+            return False, "", ""
+
+    async def normal_response(self, message_data: dict) -> bool:
+        """
+        处理接收到的消息。
+        在"兴趣"模式下，判断是否回复并生成内容。
+        """
+
+        interested_rate = message_data.get("interest_value") or 0.0
+
+        self.willing_manager.setup(message_data, self.chat_stream)
+
+        reply_probability = await self.willing_manager.get_reply_probability(message_data.get("message_id", ""))
+
+        talk_frequency = -1.00
+
+        if reply_probability < 1:  # 简化逻辑，如果未提及 (reply_probability 为 0)，则获取意愿概率
+            additional_config = message_data.get("additional_config", {})
+            if additional_config and "maimcore_reply_probability_gain" in additional_config:
+                reply_probability += additional_config["maimcore_reply_probability_gain"]
+                reply_probability = min(max(reply_probability, 0), 1)  # 确保概率在 0-1 之间
+
+        talk_frequency = global_config.chat.get_current_talk_frequency(self.stream_id)
+        reply_probability = talk_frequency * reply_probability
+
+        # 处理表情包
+        if message_data.get("is_emoji") or message_data.get("is_picid"):
+            reply_probability = 0
+
+        # 打印消息信息
+        mes_name = self.chat_stream.group_info.group_name if self.chat_stream.group_info else "私聊"
+
+        # logger.info(f"[{mes_name}] 当前聊天频率: {talk_frequency:.2f},兴趣值: {interested_rate:.2f},回复概率: {reply_probability * 100:.1f}%")
+
+        if reply_probability > 0.05:
+            logger.info(
+                f"[{mes_name}]"
+                f"{message_data.get('user_nickname')}:"
+                f"{message_data.get('processed_plain_text')}[兴趣:{interested_rate:.2f}][回复概率:{reply_probability * 100:.1f}%]"
+            )
+
+        if random.random() < reply_probability:
+            await self.willing_manager.before_generate_reply_handle(message_data.get("message_id", ""))
+            await self._observe(message_data=message_data)
+            return True
+
+        # 意愿管理器：注销当前message信息 (无论是否回复，只要处理过就删除)
+        self.willing_manager.delete(message_data.get("message_id", ""))
+        return False
+
+    async def _generate_response(
+        self,
+        message_data: dict,
+        available_actions: Optional[Dict[str, ActionInfo]],
+        reply_to: str,
+        request_type: str = "chat.replyer.normal",
+    ) -> Optional[list]:
+        """生成普通回复"""
+        try:
+            success, reply_set, _ = await generator_api.generate_reply(
+                chat_stream=self.chat_stream,
+                reply_to=reply_to,
+                available_actions=available_actions,
+                enable_tool=global_config.tool.enable_tool,
+                request_type=request_type,
+                from_plugin=False,
+            )
+
+            if not success or not reply_set:
+                logger.info(f"对 {message_data.get('processed_plain_text')} 的回复生成失败")
+                return None
+
+            return reply_set
+
+        except Exception as e:
+            logger.error(f"{self.log_prefix}回复生成出现错误：{str(e)} {traceback.format_exc()}")
+            return None
+
+    async def _send_response(self, reply_set, reply_to, thinking_start_time, message_data) -> str:
+        current_time = time.time()
+        new_message_count = message_api.count_new_messages(
+            chat_id=self.chat_stream.stream_id, start_time=thinking_start_time, end_time=current_time
+        )
+        platform = message_data.get("user_platform", "")
+        user_id = message_data.get("user_id", "")
+        reply_to_platform_id = f"{platform}:{user_id}"
+
+        need_reply = new_message_count >= random.randint(2, 4)
+
+        if need_reply:
+            logger.info(f"{self.log_prefix} 从思考到回复，共有{new_message_count}条新消息，使用引用回复")
+        else:
+            logger.info(f"{self.log_prefix} 从思考到回复，共有{new_message_count}条新消息，不使用引用回复")
+
+        reply_text = ""
+        first_replied = False
+        for reply_seg in reply_set:
+            data = reply_seg[1]
+            if not first_replied:
+                if need_reply:
+                    await send_api.text_to_stream(
+                        text=data,
+                        stream_id=self.chat_stream.stream_id,
+                        reply_to=reply_to,
+                        reply_to_platform_id=reply_to_platform_id,
+                        typing=False,
+                    )
+                else:
+                    await send_api.text_to_stream(
+                        text=data,
+                        stream_id=self.chat_stream.stream_id,
+                        reply_to_platform_id=reply_to_platform_id,
+                        typing=False,
+                    )
+                first_replied = True
+            else:
+                await send_api.text_to_stream(
+                    text=data,
+                    stream_id=self.chat_stream.stream_id,
+                    reply_to_platform_id=reply_to_platform_id,
+                    typing=True,
+                )
+            reply_text += data
+
+        return reply_text

src/chat/chat_loop/hfc_utils.py

@@ -0,0 +1,138 @@
+import time
+from typing import Optional, Dict, Any
+
+from src.config.config import global_config
+from src.common.logger import get_logger
+from src.chat.message_receive.chat_stream import get_chat_manager
+from src.plugin_system.apis import send_api
+from maim_message.message_base import GroupInfo
+
+from src.common.message_repository import count_messages
+
+logger = get_logger(__name__)
+
+
+class CycleDetail:
+    """循环信息记录类"""
+
+    def __init__(self, cycle_id: int):
+        self.cycle_id = cycle_id
+        self.thinking_id = ""
+        self.start_time = time.time()
+        self.end_time: Optional[float] = None
+        self.timers: Dict[str, float] = {}
+
+        self.loop_plan_info: Dict[str, Any] = {}
+        self.loop_action_info: Dict[str, Any] = {}
+
+    def to_dict(self) -> Dict[str, Any]:
+        """将循环信息转换为字典格式"""
+
+        def convert_to_serializable(obj, depth=0, seen=None):
+            if seen is None:
+                seen = set()
+
+            # 防止递归过深
+            if depth > 5:  # 降低递归深度限制
+                return str(obj)
+
+            # 防止循环引用
+            obj_id = id(obj)
+            if obj_id in seen:
+                return str(obj)
+            seen.add(obj_id)
+
+            try:
+                if hasattr(obj, "to_dict"):
+                    # 对于有to_dict方法的对象，直接调用其to_dict方法
+                    return obj.to_dict()
+                elif isinstance(obj, dict):
+                    # 对于字典，只保留基本类型和可序列化的值
+                    return {
+                        k: convert_to_serializable(v, depth + 1, seen)
+                        for k, v in obj.items()
+                        if isinstance(k, (str, int, float, bool))
+                    }
+                elif isinstance(obj, (list, tuple)):
+                    # 对于列表和元组，只保留可序列化的元素
+                    return [
+                        convert_to_serializable(item, depth + 1, seen)
+                        for item in obj
+                        if not isinstance(item, (dict, list, tuple))
+                        or isinstance(item, (str, int, float, bool, type(None)))
+                    ]
+                elif isinstance(obj, (str, int, float, bool, type(None))):
+                    return obj
+                else:
+                    return str(obj)
+            finally:
+                seen.remove(obj_id)
+
+        return {
+            "cycle_id": self.cycle_id,
+            "start_time": self.start_time,
+            "end_time": self.end_time,
+            "timers": self.timers,
+            "thinking_id": self.thinking_id,
+            "loop_plan_info": convert_to_serializable(self.loop_plan_info),
+            "loop_action_info": convert_to_serializable(self.loop_action_info),
+        }
+
+    def set_loop_info(self, loop_info: Dict[str, Any]):
+        """设置循环信息"""
+        self.loop_plan_info = loop_info["loop_plan_info"]
+        self.loop_action_info = loop_info["loop_action_info"]
+
+
+def get_recent_message_stats(minutes: float = 30, chat_id: Optional[str] = None) -> dict:
+    """
+    Args:
+        minutes (float): 检索的分钟数，默认30分钟
+        chat_id (str, optional): 指定的chat_id，仅统计该chat下的消息。为None时统计全部。
+    Returns:
+        dict: {"bot_reply_count": int, "total_message_count": int}
+    """
+
+    now = time.time()
+    start_time = now - minutes * 60
+    bot_id = global_config.bot.qq_account
+
+    filter_base: Dict[str, Any] = {"time": {"$gte": start_time}}
+    if chat_id is not None:
+        filter_base["chat_id"] = chat_id
+
+    # 总消息数
+    total_message_count = count_messages(filter_base)
+    # bot自身回复数
+    bot_filter = filter_base.copy()
+    bot_filter["user_id"] = bot_id
+    bot_reply_count = count_messages(bot_filter)
+
+    return {"bot_reply_count": bot_reply_count, "total_message_count": total_message_count}
+
+
+async def send_typing():
+    group_info = GroupInfo(platform="amaidesu_default", group_id="114514", group_name="内心")
+
+    chat = await get_chat_manager().get_or_create_stream(
+        platform="amaidesu_default",
+        user_info=None,
+        group_info=group_info,
+    )
+
+    await send_api.custom_to_stream(
+        message_type="state", content="typing", stream_id=chat.stream_id, storage_message=False
+    )
+
+async def stop_typing():
+    group_info = GroupInfo(platform="amaidesu_default", group_id="114514", group_name="内心")
+
+    chat = await get_chat_manager().get_or_create_stream(
+        platform="amaidesu_default",
+        user_info=None,
+        group_info=group_info,
+    )
+
+    await send_api.custom_to_stream(
+        message_type="state", content="stop_typing", stream_id=chat.stream_id, storage_message=False
+    )

src/chat/express/expression_learner.py

@@ -0,0 +1,648 @@
+import time
+import random
+import json
+import os
+from datetime import datetime
+
+from typing import List, Dict, Optional, Any, Tuple
+
+from src.common.logger import get_logger
+from src.common.database.sqlalchemy_database_api import get_session
+from sqlalchemy import select
+from src.common.database.sqlalchemy_models import Expression
+from src.llm_models.utils_model import LLMRequest
+from src.config.config import model_config, global_config
+from src.chat.utils.chat_message_builder import get_raw_msg_by_timestamp_with_chat_inclusive, build_anonymous_messages
+from src.chat.utils.prompt_builder import Prompt, global_prompt_manager
+from src.chat.message_receive.chat_stream import get_chat_manager
+
+
+MAX_EXPRESSION_COUNT = 300
+DECAY_DAYS = 30  # 30天衰减到0.01
+DECAY_MIN = 0.01  # 最小衰减值
+
+logger = get_logger("expressor")
+session = get_session()
+
+def format_create_date(timestamp: float) -> str:
+    """
+    将时间戳格式化为可读的日期字符串
+    """
+    try:
+        return datetime.fromtimestamp(timestamp).strftime("%Y-%m-%d %H:%M:%S")
+    except (ValueError, OSError):
+        return "未知时间"
+
+
+def init_prompt() -> None:
+    learn_style_prompt = """
+{chat_str}
+
+请从上面这段群聊中概括除了人名为"SELF"之外的人的语言风格
+1. 只考虑文字，不要考虑表情包和图片
+2. 不要涉及具体的人名，只考虑语言风格
+3. 语言风格包含特殊内容和情感
+4. 思考有没有特殊的梗，一并总结成语言风格
+5. 例子仅供参考，请严格根据群聊内容总结!!!
+注意：总结成如下格式的规律，总结的内容要详细，但具有概括性：
+例如：当"AAAAA"时，可以"BBBBB", AAAAA代表某个具体的场景，不超过20个字。BBBBB代表对应的语言风格，特定句式或表达方式，不超过20个字。
+
+例如：
+当"对某件事表示十分惊叹，有些意外"时，使用"我嘞个xxxx"
+当"表示讽刺的赞同，不想讲道理"时，使用"对对对"
+当"想说明某个具体的事实观点，但懒得明说，或者不便明说，或表达一种默契"，使用"懂的都懂"
+当"当涉及游戏相关时，表示意外的夸赞，略带戏谑意味"时，使用"这么强！"
+
+请注意：不要总结你自己（SELF）的发言
+现在请你概括
+"""
+    Prompt(learn_style_prompt, "learn_style_prompt")
+
+    learn_grammar_prompt = """
+{chat_str}
+
+请从上面这段群聊中概括除了人名为"SELF"之外的人的语法和句法特点，只考虑纯文字，不要考虑表情包和图片
+1.不要总结【图片】，【动画表情】，[图片]，[动画表情]，不总结 表情符号 at @ 回复 和[回复]
+2.不要涉及具体的人名，只考虑语法和句法特点,
+3.语法和句法特点要包括，句子长短（具体字数），有何种语病，如何拆分句子。
+4. 例子仅供参考，请严格根据群聊内容总结!!!
+总结成如下格式的规律，总结的内容要简洁，不浮夸：
+当"xxx"时，可以"xxx"
+
+例如：
+当"表达观点较复杂"时，使用"省略主语(3-6个字)"的句法
+当"不用详细说明的一般表达"时，使用"非常简洁的句子"的句法
+当"需要单纯简单的确认"时，使用"单字或几个字的肯定(1-2个字)"的句法
+
+注意不要总结你自己（SELF）的发言
+现在请你概括
+"""
+    Prompt(learn_grammar_prompt, "learn_grammar_prompt")
+
+
+class ExpressionLearner:
+    def __init__(self, chat_id: str) -> None:
+        self.express_learn_model: LLMRequest = LLMRequest(
+            model_set=model_config.model_task_config.replyer_1, request_type="expressor.learner"
+        )
+        self.chat_id = chat_id
+        self.chat_name = get_chat_manager().get_stream_name(chat_id) or chat_id
+
+        
+        # 维护每个chat的上次学习时间
+        self.last_learning_time: float = time.time()
+        
+        # 学习参数
+        self.min_messages_for_learning = 25  # 触发学习所需的最少消息数
+        self.min_learning_interval = 300  # 最短学习时间间隔（秒）
+
+
+
+
+    def can_learn_for_chat(self) -> bool:
+        """
+        检查指定聊天流是否允许学习表达
+        
+        Args:
+            chat_id: 聊天流ID
+            
+        Returns:
+            bool: 是否允许学习
+        """
+        try:
+            use_expression, enable_learning, _ = global_config.expression.get_expression_config_for_chat(self.chat_id)
+            return enable_learning
+        except Exception as e:
+            logger.error(f"检查学习权限失败: {e}")
+            return False
+
+    def should_trigger_learning(self) -> bool:
+        """
+        检查是否应该触发学习
+        
+        Args:
+            chat_id: 聊天流ID
+            
+        Returns:
+            bool: 是否应该触发学习
+        """
+        current_time = time.time()
+
+        # 获取该聊天流的学习强度
+        try:
+            use_expression, enable_learning, learning_intensity = global_config.expression.get_expression_config_for_chat(self.chat_id)
+        except Exception as e:
+            logger.error(f"获取聊天流 {self.chat_id} 的学习配置失败: {e}")
+            return False
+            
+        # 检查是否允许学习
+        if not enable_learning:
+            return False
+            
+        # 根据学习强度计算最短学习时间间隔
+        min_interval = self.min_learning_interval / learning_intensity
+        
+        # 检查时间间隔
+        time_diff = current_time - self.last_learning_time
+        if time_diff < min_interval:
+            return False
+            
+        # 检查消息数量（只检查指定聊天流的消息）
+        recent_messages = get_raw_msg_by_timestamp_with_chat_inclusive(
+            chat_id=self.chat_id,
+            timestamp_start=self.last_learning_time,
+            timestamp_end=time.time(),
+        )
+        
+        if not recent_messages or len(recent_messages) < self.min_messages_for_learning:
+            return False
+            
+        return True
+
+    async def trigger_learning_for_chat(self) -> bool:
+        """
+        为指定聊天流触发学习
+        
+        Args:
+            chat_id: 聊天流ID
+            
+        Returns:
+            bool: 是否成功触发学习
+        """
+        if not self.should_trigger_learning():
+            return False
+            
+        try:
+            logger.info(f"为聊天流 {self.chat_name} 触发表达学习")
+            
+            # 学习语言风格
+            learnt_style = await self.learn_and_store(type="style", num=25)
+            
+            # 学习句法特点
+            learnt_grammar = await self.learn_and_store(type="grammar", num=10)
+            
+            # 更新学习时间
+            self.last_learning_time = time.time()
+            
+            if learnt_style or learnt_grammar:
+                logger.info(f"聊天流 {self.chat_name} 表达学习完成")
+                return True
+            else:
+                logger.warning(f"聊天流 {self.chat_name} 表达学习未获得有效结果")
+                return False
+                
+        except Exception as e:
+            logger.error(f"为聊天流 {self.chat_name} 触发学习失败: {e}")
+            return False
+
+    def get_expression_by_chat_id(self) -> Tuple[List[Dict[str, float]], List[Dict[str, float]]]:
+        """
+        获取指定chat_id的style和grammar表达方式
+        返回的每个表达方式字典中都包含了source_id, 用于后续的更新操作
+        """
+        learnt_style_expressions = []
+        learnt_grammar_expressions = []
+
+        # 直接从数据库查询
+        style_query = session.execute(select(Expression).where((Expression.chat_id == self.chat_id) & (Expression.type == "style")))
+        for expr in style_query.scalars():
+            # 确保create_date存在，如果不存在则使用last_active_time
+            create_date = expr.create_date if expr.create_date is not None else expr.last_active_time
+            learnt_style_expressions.append(
+                {
+                    "situation": expr.situation,
+                    "style": expr.style,
+                    "count": expr.count,
+                    "last_active_time": expr.last_active_time,
+                    "source_id": self.chat_id,
+                    "type": "style",
+                    "create_date": create_date,
+                }
+            )
+        grammar_query = session.execute(select(Expression).where((Expression.chat_id == self.chat_id) & (Expression.type == "grammar")))
+        for expr in grammar_query.scalars():
+            # 确保create_date存在，如果不存在则使用last_active_time
+            create_date = expr.create_date if expr.create_date is not None else expr.last_active_time
+            learnt_grammar_expressions.append(
+                {
+                    "situation": expr.situation,
+                    "style": expr.style,
+                    "count": expr.count,
+                    "last_active_time": expr.last_active_time,
+                    "source_id": self.chat_id,
+                    "type": "grammar",
+                    "create_date": create_date,
+                }
+            )
+        return learnt_style_expressions, learnt_grammar_expressions
+
+
+
+
+
+
+
+    def _apply_global_decay_to_database(self, current_time: float) -> None:
+        """
+        对数据库中的所有表达方式应用全局衰减
+        """
+        try:
+            # 获取所有表达方式
+            all_expressions = session.execute(select(Expression)).scalars()
+
+            updated_count = 0
+            deleted_count = 0
+
+            for expr in all_expressions:
+                # 计算时间差
+                last_active = expr.last_active_time
+                time_diff_days = (current_time - last_active) / (24 * 3600)  # 转换为天
+
+                # 计算衰减值
+                decay_value = self.calculate_decay_factor(time_diff_days)
+                new_count = max(0.01, expr.count - decay_value)
+
+                if new_count <= 0.01:
+                    # 如果count太小，删除这个表达方式
+                    session.delete(expr)
+                    deleted_count += 1
+                else:
+                    # 更新count
+                    expr.count = new_count
+                    updated_count += 1
+
+            session.commit()
+
+            if updated_count > 0 or deleted_count > 0:
+                logger.info(f"全局衰减完成：更新了 {updated_count} 个表达方式，删除了 {deleted_count} 个表达方式")
+
+        except Exception as e:
+            session.rollback()
+            logger.error(f"数据库全局衰减失败: {e}")
+
+    def calculate_decay_factor(self, time_diff_days: float) -> float:
+        """
+        计算衰减值
+        当时间差为0天时，衰减值为0（最近活跃的不衰减）
+        当时间差为7天时，衰减值为0.002（中等衰减）
+        当时间差为30天或更长时，衰减值为0.01（高衰减）
+        使用二次函数进行曲线插值
+        """
+        if time_diff_days <= 0:
+            return 0.0  # 刚激活的表达式不衰减
+
+        if time_diff_days >= DECAY_DAYS:
+            return 0.01  # 长时间未活跃的表达式大幅衰减
+
+        # 使用二次函数插值：在0-30天之间从0衰减到0.01
+        # 使用简单的二次函数：y = a * x^2
+        # 当x=30时，y=0.01，所以 a = 0.01 / (30^2) = 0.01 / 900
+        a = 0.01 / (DECAY_DAYS**2)
+        decay = a * (time_diff_days**2)
+
+        return min(0.01, decay)
+
+    async def learn_and_store(self, type: str, num: int = 10) -> List[Tuple[str, str, str]]:
+        # sourcery skip: use-join
+        """
+        学习并存储表达方式
+        type: "style" or "grammar"
+        """
+        if type == "style":
+            type_str = "语言风格"
+        elif type == "grammar":
+            type_str = "句法特点"
+        else:
+            raise ValueError(f"Invalid type: {type}")
+
+        # 检查是否允许在此聊天流中学习（在函数最前面检查）
+        if not self.can_learn_for_chat():
+            logger.debug(f"聊天流 {self.chat_name} 不允许学习表达，跳过学习")
+            return []
+
+        res = await self.learn_expression(type, num)
+
+        if res is None:
+            return []
+        learnt_expressions, chat_id = res
+
+        chat_stream = get_chat_manager().get_stream(chat_id)
+        if chat_stream is None:
+            group_name = f"聊天流 {chat_id}"
+        elif chat_stream.group_info:
+            group_name = chat_stream.group_info.group_name
+        else:
+            group_name = f"{chat_stream.user_info.user_nickname}的私聊"
+        learnt_expressions_str = ""
+        for _chat_id, situation, style in learnt_expressions:
+            learnt_expressions_str += f"{situation}->{style}\n"
+        logger.info(f"在 {group_name} 学习到{type_str}:\n{learnt_expressions_str}")
+
+        if not learnt_expressions:
+            logger.info(f"没有学习到{type_str}")
+            return []
+
+        # 按chat_id分组
+        chat_dict: Dict[str, List[Dict[str, Any]]] = {}
+        for chat_id, situation, style in learnt_expressions:
+            if chat_id not in chat_dict:
+                chat_dict[chat_id] = []
+            chat_dict[chat_id].append({"situation": situation, "style": style})
+
+        current_time = time.time()
+
+        # 存储到数据库 Expression 表
+        for chat_id, expr_list in chat_dict.items():
+            for new_expr in expr_list:
+                # 查找是否已存在相似表达方式
+                query = session.execute(select(Expression).where(
+                    (Expression.chat_id == chat_id)
+                    & (Expression.type == type)
+                    & (Expression.situation == new_expr["situation"])
+                    & (Expression.style == new_expr["style"])
+                )).scalar()
+                if query:
+                    expr_obj = query
+                    # 50%概率替换内容
+                    if random.random() < 0.5:
+                        expr_obj.situation = new_expr["situation"]
+                        expr_obj.style = new_expr["style"]
+                    expr_obj.count = expr_obj.count + 1
+                    expr_obj.last_active_time = current_time
+                else:
+                    new_expression = Expression(
+                        situation=new_expr["situation"],
+                        style=new_expr["style"],
+                        count=1,
+                        last_active_time=current_time,
+                        chat_id=chat_id,
+                        type=type,
+                        create_date=current_time,  # 手动设置创建日期
+                    )
+                    session.add(new_expression)
+            # 限制最大数量
+            exprs = list(
+                session.execute(select(Expression)
+                .where((Expression.chat_id == chat_id) & (Expression.type == type))
+                .order_by(Expression.count.asc())).scalars()
+            )
+            if len(exprs) > MAX_EXPRESSION_COUNT:
+                # 删除count最小的多余表达方式
+                for expr in exprs[: len(exprs) - MAX_EXPRESSION_COUNT]:
+                    session.delete(expr)
+            session.commit()
+        return learnt_expressions
+
+    async def learn_expression(self, type: str, num: int = 10) -> Optional[Tuple[List[Tuple[str, str, str]], str]]:
+        """从指定聊天流学习表达方式
+
+        Args:
+            type: "style" or "grammar"
+        """
+        if type == "style":
+            type_str = "语言风格"
+            prompt = "learn_style_prompt"
+        elif type == "grammar":
+            type_str = "句法特点"
+            prompt = "learn_grammar_prompt"
+        else:
+            raise ValueError(f"Invalid type: {type}")
+
+        current_time = time.time()
+        
+        # 获取上次学习时间
+        random_msg: Optional[List[Dict[str, Any]]] = get_raw_msg_by_timestamp_with_chat_inclusive(
+            chat_id=self.chat_id,
+            timestamp_start=self.last_learning_time,
+            timestamp_end=current_time,
+            limit=num,
+        )
+            
+        # print(random_msg)
+        if not random_msg or random_msg == []:
+            return None
+        # 转化成str
+        chat_id: str = random_msg[0]["chat_id"]
+        # random_msg_str: str = build_readable_messages(random_msg, timestamp_mode="normal")
+        random_msg_str: str = await build_anonymous_messages(random_msg)
+        # print(f"random_msg_str:{random_msg_str}")
+
+        prompt: str = await global_prompt_manager.format_prompt(
+            prompt,
+            chat_str=random_msg_str,
+        )
+
+        logger.debug(f"学习{type_str}的prompt: {prompt}")
+
+        try:
+            response, _ = await self.express_learn_model.generate_response_async(prompt, temperature=0.3)
+        except Exception as e:
+            logger.error(f"学习{type_str}失败: {e}")
+            return None
+
+        logger.debug(f"学习{type_str}的response: {response}")
+
+        expressions: List[Tuple[str, str, str]] = self.parse_expression_response(response, chat_id)
+
+        return expressions, chat_id
+
+    def parse_expression_response(self, response: str, chat_id: str) -> List[Tuple[str, str, str]]:
+        """
+        解析LLM返回的表达风格总结，每一行提取"当"和"使用"之间的内容，存储为(situation, style)元组
+        """
+        expressions: List[Tuple[str, str, str]] = []
+        for line in response.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            # 查找"当"和下一个引号
+            idx_when = line.find('当"')
+            if idx_when == -1:
+                continue
+            idx_quote1 = idx_when + 1
+            idx_quote2 = line.find('"', idx_quote1 + 1)
+            if idx_quote2 == -1:
+                continue
+            situation = line[idx_quote1 + 1 : idx_quote2]
+            # 查找"使用"
+            idx_use = line.find('使用"', idx_quote2)
+            if idx_use == -1:
+                continue
+            idx_quote3 = idx_use + 2
+            idx_quote4 = line.find('"', idx_quote3 + 1)
+            if idx_quote4 == -1:
+                continue
+            style = line[idx_quote3 + 1 : idx_quote4]
+            expressions.append((chat_id, situation, style))
+        return expressions
+
+
+init_prompt()
+
+class ExpressionLearnerManager:
+    def __init__(self):
+        self.expression_learners = {}
+        
+        self._ensure_expression_directories()
+        self._auto_migrate_json_to_db()
+        self._migrate_old_data_create_date()
+        
+    def get_expression_learner(self, chat_id: str) -> ExpressionLearner:
+        if chat_id not in self.expression_learners:
+            self.expression_learners[chat_id] = ExpressionLearner(chat_id)
+        return self.expression_learners[chat_id]
+    
+    def _ensure_expression_directories(self):
+        """
+        确保表达方式相关的目录结构存在
+        """
+        base_dir = os.path.join("data", "expression")
+        directories_to_create = [
+            base_dir,
+            os.path.join(base_dir, "learnt_style"),
+            os.path.join(base_dir, "learnt_grammar"),
+        ]
+
+        for directory in directories_to_create:
+            try:
+                os.makedirs(directory, exist_ok=True)
+                logger.debug(f"确保目录存在: {directory}")
+            except Exception as e:
+                logger.error(f"创建目录失败 {directory}: {e}")
+
+
+    def _auto_migrate_json_to_db(self):
+        """
+        自动将/data/expression/learnt_style 和 learnt_grammar 下所有expressions.json迁移到数据库。
+        迁移完成后在/data/expression/done.done写入标记文件，存在则跳过。
+        """
+        base_dir = os.path.join("data", "expression")
+        done_flag = os.path.join(base_dir, "done.done")
+
+        # 确保基础目录存在
+        try:
+            os.makedirs(base_dir, exist_ok=True)
+            logger.debug(f"确保目录存在: {base_dir}")
+        except Exception as e:
+            logger.error(f"创建表达方式目录失败: {e}")
+            return
+
+        if os.path.exists(done_flag):
+            logger.info("表达方式JSON已迁移，无需重复迁移。")
+            return
+
+        logger.info("开始迁移表达方式JSON到数据库...")
+        migrated_count = 0
+
+        for type in ["learnt_style", "learnt_grammar"]:
+            type_str = "style" if type == "learnt_style" else "grammar"
+            type_dir = os.path.join(base_dir, type)
+            if not os.path.exists(type_dir):
+                logger.debug(f"目录不存在，跳过: {type_dir}")
+                continue
+
+            try:
+                chat_ids = os.listdir(type_dir)
+                logger.debug(f"在 {type_dir} 中找到 {len(chat_ids)} 个聊天ID目录")
+            except Exception as e:
+                logger.error(f"读取目录失败 {type_dir}: {e}")
+                continue
+
+            for chat_id in chat_ids:
+                expr_file = os.path.join(type_dir, chat_id, "expressions.json")
+                if not os.path.exists(expr_file):
+                    continue
+                try:
+                    with open(expr_file, "r", encoding="utf-8") as f:
+                        expressions = json.load(f)
+
+                    if not isinstance(expressions, list):
+                        logger.warning(f"表达方式文件格式错误，跳过: {expr_file}")
+                        continue
+
+                    for expr in expressions:
+                        if not isinstance(expr, dict):
+                            continue
+
+                        situation = expr.get("situation")
+                        style_val = expr.get("style")
+                        count = expr.get("count", 1)
+                        last_active_time = expr.get("last_active_time", time.time())
+
+                        if not situation or not style_val:
+                            logger.warning(f"表达方式缺少必要字段，跳过: {expr}")
+                            continue
+
+                        # 查重：同chat_id+type+situation+style
+
+                        query = session.execute(select(Expression).where(
+                            (Expression.chat_id == chat_id)
+                            & (Expression.type == type_str)
+                            & (Expression.situation == situation)
+                            & (Expression.style == style_val)
+                        )).scalar()
+                        if query:
+                            expr_obj = query
+                            expr_obj.count = max(expr_obj.count, count)
+                            expr_obj.last_active_time = max(expr_obj.last_active_time, last_active_time)
+                        else:
+                            new_expression = Expression(
+                                situation=situation,
+                                style=style_val,
+                                count=count,
+                                last_active_time=last_active_time,
+                                chat_id=chat_id,
+                                type=type_str,
+                                create_date=last_active_time,  # 迁移时使用last_active_time作为创建时间
+                            )
+                            session.add(new_expression)
+                            migrated_count += 1
+                    logger.info(f"已迁移 {expr_file} 到数据库，包含 {len(expressions)} 个表达方式")
+                except json.JSONDecodeError as e:
+                    logger.error(f"JSON解析失败 {expr_file}: {e}")
+                except Exception as e:
+                    logger.error(f"迁移表达方式 {expr_file} 失败: {e}")
+
+        # 标记迁移完成
+        try:
+            # 确保done.done文件的父目录存在
+            done_parent_dir = os.path.dirname(done_flag)
+            if not os.path.exists(done_parent_dir):
+                os.makedirs(done_parent_dir, exist_ok=True)
+                logger.debug(f"为done.done创建父目录: {done_parent_dir}")
+
+            with open(done_flag, "w", encoding="utf-8") as f:
+                f.write("done\n")
+            logger.info(f"表达方式JSON迁移已完成，共迁移 {migrated_count} 个表达方式，已写入done.done标记文件")
+        except PermissionError as e:
+            logger.error(f"权限不足，无法写入done.done标记文件: {e}")
+        except OSError as e:
+            logger.error(f"文件系统错误，无法写入done.done标记文件: {e}")
+        except Exception as e:
+            logger.error(f"写入done.done标记文件失败: {e}")
+
+    def _migrate_old_data_create_date(self):
+        """
+        为没有create_date的老数据设置创建日期
+        使用last_active_time作为create_date的默认值
+        """
+        try:
+            # 查找所有create_date为空的表达方式
+            old_expressions = session.execute(select(Expression).where(Expression.create_date.is_(None))).scalars()
+            updated_count = 0
+
+            for expr in old_expressions:
+                # 使用last_active_time作为create_date
+                expr.create_date = expr.last_active_time
+                updated_count += 1
+
+            session.commit()
+
+            if updated_count > 0:
+                logger.info(f"已为 {updated_count} 个老的表达方式设置创建日期")
+        except Exception as e:
+            session.rollback()
+            logger.error(f"迁移老数据创建日期失败: {e}")
+
+
+expression_learner_manager = ExpressionLearnerManager()

src/chat/express/expression_selector.py

@@ -0,0 +1,339 @@
+import json
+import time
+import random
+import hashlib
+
+from typing import List, Dict, Tuple, Optional, Any
+from json_repair import repair_json
+
+from src.llm_models.utils_model import LLMRequest
+from src.config.config import global_config, model_config
+from src.common.logger import get_logger
+from sqlalchemy import select
+from src.common.database.sqlalchemy_models import Expression
+from src.chat.utils.prompt_builder import Prompt, global_prompt_manager
+from src.common.database.sqlalchemy_database_api import get_session
+session = get_session()
+
+logger = get_logger("expression_selector")
+
+
+def init_prompt():
+    expression_evaluation_prompt = """
+以下是正在进行的聊天内容：
+{chat_observe_info}
+
+你的名字是{bot_name}{target_message}
+
+以下是可选的表达情境：
+{all_situations}
+
+请你分析聊天内容的语境、情绪、话题类型，从上述情境中选择最适合当前聊天情境的{min_num}-{max_num}个情境。
+考虑因素包括：
+1. 聊天的情绪氛围（轻松、严肃、幽默等）
+2. 话题类型（日常、技术、游戏、情感等）
+3. 情境与当前语境的匹配度
+{target_message_extra_block}
+
+请以JSON格式输出，只需要输出选中的情境编号：
+例如：
+{{
+    "selected_situations": [2, 3, 5, 7, 19, 22, 25, 38, 39, 45, 48, 64]
+}}
+
+请严格按照JSON格式输出，不要包含其他内容：
+"""
+    Prompt(expression_evaluation_prompt, "expression_evaluation_prompt")
+
+
+def weighted_sample(population: List[Dict], weights: List[float], k: int) -> List[Dict]:
+    """按权重随机抽样"""
+    if not population or not weights or k <= 0:
+        return []
+
+    if len(population) <= k:
+        return population.copy()
+
+    # 使用累积权重的方法进行加权抽样
+    selected = []
+    population_copy = population.copy()
+    weights_copy = weights.copy()
+
+    for _ in range(k):
+        if not population_copy:
+            break
+
+        # 选择一个元素
+        chosen_idx = random.choices(range(len(population_copy)), weights=weights_copy)[0]
+        selected.append(population_copy.pop(chosen_idx))
+        weights_copy.pop(chosen_idx)
+
+    return selected
+
+
+class ExpressionSelector:
+    def __init__(self):
+        self.llm_model = LLMRequest(
+            model_set=model_config.model_task_config.utils_small, request_type="expression.selector"
+        )
+
+    def can_use_expression_for_chat(self, chat_id: str) -> bool:
+        """
+        检查指定聊天流是否允许使用表达
+        
+        Args:
+            chat_id: 聊天流ID
+            
+        Returns:
+            bool: 是否允许使用表达
+        """
+        try:
+            use_expression, _, _ = global_config.expression.get_expression_config_for_chat(chat_id)
+            return use_expression
+        except Exception as e:
+            logger.error(f"检查表达使用权限失败: {e}")
+            return False
+
+    @staticmethod
+    def _parse_stream_config_to_chat_id(stream_config_str: str) -> Optional[str]:
+        """解析'platform:id:type'为chat_id（与get_stream_id一致）"""
+        try:
+            parts = stream_config_str.split(":")
+            if len(parts) != 3:
+                return None
+            platform = parts[0]
+            id_str = parts[1]
+            stream_type = parts[2]
+            is_group = stream_type == "group"
+            if is_group:
+                components = [platform, str(id_str)]
+            else:
+                components = [platform, str(id_str), "private"]
+            key = "_".join(components)
+            return hashlib.md5(key.encode()).hexdigest()
+        except Exception:
+            return None
+
+    def get_related_chat_ids(self, chat_id: str) -> List[str]:
+        """根据expression_groups配置，获取与当前chat_id相关的所有chat_id（包括自身）"""
+        groups = global_config.expression.expression_groups
+        for group in groups:
+            group_chat_ids = []
+            for stream_config_str in group:
+                if chat_id_candidate := self._parse_stream_config_to_chat_id(stream_config_str):
+                    group_chat_ids.append(chat_id_candidate)
+            if chat_id in group_chat_ids:
+                return group_chat_ids
+        return [chat_id]
+
+    def get_random_expressions(
+        self, chat_id: str, total_num: int, style_percentage: float, grammar_percentage: float
+    ) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+        # sourcery skip: extract-duplicate-method, move-assign
+        # 支持多chat_id合并抽选
+        related_chat_ids = self.get_related_chat_ids(chat_id)
+
+        # 优化：一次性查询所有相关chat_id的表达方式
+        style_query = session.execute(select(Expression).where(
+            (Expression.chat_id.in_(related_chat_ids)) & (Expression.type == "style")
+        ))
+        grammar_query = session.execute(select(Expression).where(
+            (Expression.chat_id.in_(related_chat_ids)) & (Expression.type == "grammar")
+        ))
+
+        style_exprs = [
+            {
+                "situation": expr.situation,
+                "style": expr.style,
+                "count": expr.count,
+                "last_active_time": expr.last_active_time,
+                "source_id": expr.chat_id,
+                "type": "style",
+                "create_date": expr.create_date if expr.create_date is not None else expr.last_active_time,
+            }
+            for expr in style_query.scalars()
+        ]
+
+        grammar_exprs = [
+            {
+                "situation": expr.situation,
+                "style": expr.style,
+                "count": expr.count,
+                "last_active_time": expr.last_active_time,
+                "source_id": expr.chat_id,
+                "type": "grammar",
+                "create_date": expr.create_date if expr.create_date is not None else expr.last_active_time,
+            }
+            for expr in grammar_query.scalars()
+        ]
+
+        style_num = int(total_num * style_percentage)
+        grammar_num = int(total_num * grammar_percentage)
+        # 按权重抽样（使用count作为权重）
+        if style_exprs:
+            style_weights = [expr.get("count", 1) for expr in style_exprs]
+            selected_style = weighted_sample(style_exprs, style_weights, style_num)
+        else:
+            selected_style = []
+        if grammar_exprs:
+            grammar_weights = [expr.get("count", 1) for expr in grammar_exprs]
+            selected_grammar = weighted_sample(grammar_exprs, grammar_weights, grammar_num)
+        else:
+            selected_grammar = []
+        return selected_style, selected_grammar
+
+    def update_expressions_count_batch(self, expressions_to_update: List[Dict[str, Any]], increment: float = 0.1):
+        """对一批表达方式更新count值，按chat_id+type分组后一次性写入数据库"""
+        if not expressions_to_update:
+            return
+        updates_by_key = {}
+        for expr in expressions_to_update:
+            source_id: str = expr.get("source_id")  # type: ignore
+            expr_type: str = expr.get("type", "style")
+            situation: str = expr.get("situation")  # type: ignore
+            style: str = expr.get("style")  # type: ignore
+            if not source_id or not situation or not style:
+                logger.warning(f"表达方式缺少必要字段，无法更新: {expr}")
+                continue
+            key = (source_id, expr_type, situation, style)
+            if key not in updates_by_key:
+                updates_by_key[key] = expr
+        for chat_id, expr_type, situation, style in updates_by_key:
+            query = session.execute(select(Expression).where(
+                (Expression.chat_id == chat_id)
+                & (Expression.type == expr_type)
+                & (Expression.situation == situation)
+                & (Expression.style == style)
+            )).scalar()
+            if query:
+                expr_obj = query
+                current_count = expr_obj.count
+                new_count = min(current_count + increment, 5.0)
+                expr_obj.count = new_count
+                expr_obj.last_active_time = time.time()
+                session.commit()
+                logger.debug(
+                    f"表达方式激活: 原count={current_count:.3f}, 增量={increment}, 新count={new_count:.3f} in db"
+                )
+
+    async def select_suitable_expressions_llm(
+        self,
+        chat_id: str,
+        chat_info: str,
+        max_num: int = 10,
+        min_num: int = 5,
+        target_message: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        # sourcery skip: inline-variable, list-comprehension
+        """使用LLM选择适合的表达方式"""
+        
+        # 检查是否允许在此聊天流中使用表达
+        if not self.can_use_expression_for_chat(chat_id):
+            logger.debug(f"聊天流 {chat_id} 不允许使用表达，返回空列表")
+            return []
+
+        # 1. 获取35个随机表达方式（现在按权重抽取）
+        style_exprs, grammar_exprs = self.get_random_expressions(chat_id, 30, 0.5, 0.5)
+
+        # 2. 构建所有表达方式的索引和情境列表
+        all_expressions = []
+        all_situations = []
+
+        # 添加style表达方式
+        for expr in style_exprs:
+            if isinstance(expr, dict) and "situation" in expr and "style" in expr:
+                expr_with_type = expr.copy()
+                expr_with_type["type"] = "style"
+                all_expressions.append(expr_with_type)
+                all_situations.append(f"{len(all_expressions)}.{expr['situation']}")
+
+        # 添加grammar表达方式
+        for expr in grammar_exprs:
+            if isinstance(expr, dict) and "situation" in expr and "style" in expr:
+                expr_with_type = expr.copy()
+                expr_with_type["type"] = "grammar"
+                all_expressions.append(expr_with_type)
+                all_situations.append(f"{len(all_expressions)}.{expr['situation']}")
+
+        if not all_expressions:
+            logger.warning("没有找到可用的表达方式")
+            return []
+
+        all_situations_str = "\n".join(all_situations)
+
+        if target_message:
+            target_message_str = f"，现在你想要回复消息：{target_message}"
+            target_message_extra_block = "4.考虑你要回复的目标消息"
+        else:
+            target_message_str = ""
+            target_message_extra_block = ""
+
+        # 3. 构建prompt（只包含情境，不包含完整的表达方式）
+        prompt = (await global_prompt_manager.get_prompt_async("expression_evaluation_prompt")).format(
+            bot_name=global_config.bot.nickname,
+            chat_observe_info=chat_info,
+            all_situations=all_situations_str,
+            min_num=min_num,
+            max_num=max_num,
+            target_message=target_message_str,
+            target_message_extra_block=target_message_extra_block,
+        )
+
+        # print(prompt)
+
+        # 4. 调用LLM
+        try:
+            
+            # start_time = time.time()
+            content, (reasoning_content, model_name, _) = await self.llm_model.generate_response_async(prompt=prompt)
+            # logger.info(f"LLM请求时间: {model_name}  {time.time() - start_time} \n{prompt}")
+
+            # logger.info(f"模型名称: {model_name}")
+            # logger.info(f"LLM返回结果: {content}")
+            # if reasoning_content:
+            #     logger.info(f"LLM推理: {reasoning_content}")
+            # else:
+            #     logger.info(f"LLM推理: 无")
+
+            if not content:
+                logger.warning("LLM返回空结果")
+                return []
+
+            # 5. 解析结果
+            result = repair_json(content)
+            if isinstance(result, str):
+                result = json.loads(result)
+
+            if not isinstance(result, dict) or "selected_situations" not in result:
+                logger.error("LLM返回格式错误")
+                logger.info(f"LLM返回结果: \n{content}")
+                return []
+
+            selected_indices = result["selected_situations"]
+
+            # 根据索引获取完整的表达方式
+            valid_expressions = []
+            for idx in selected_indices:
+                if isinstance(idx, int) and 1 <= idx <= len(all_expressions):
+                    expression = all_expressions[idx - 1]  # 索引从1开始
+                    valid_expressions.append(expression)
+
+            # 对选中的所有表达方式，一次性更新count数
+            if valid_expressions:
+                self.update_expressions_count_batch(valid_expressions, 0.006)
+
+            # logger.info(f"LLM从{len(all_expressions)}个情境中选择了{len(valid_expressions)}个")
+            return valid_expressions
+
+        except Exception as e:
+            logger.error(f"LLM处理表达方式选择时出错: {e}")
+            return []
+    
+
+
+init_prompt()
+
+try:
+    expression_selector = ExpressionSelector()
+except Exception as e:
+    print(f"ExpressionSelector初始化失败: {e}")

src/chat/heart_flow/heartflow.py

@@ -0,0 +1,40 @@
+import traceback
+from typing import Any, Optional, Dict
+
+from src.common.logger import get_logger
+from src.chat.heart_flow.sub_heartflow import SubHeartflow
+from src.chat.message_receive.chat_stream import get_chat_manager
+
+logger = get_logger("heartflow")
+
+
+class Heartflow:
+    """主心流协调器，负责初始化并协调聊天"""
+
+    def __init__(self):
+        self.subheartflows: Dict[Any, "SubHeartflow"] = {}
+
+    async def get_or_create_subheartflow(self, subheartflow_id: Any) -> Optional["SubHeartflow"]:
+        """获取或创建一个新的SubHeartflow实例"""
+        if subheartflow_id in self.subheartflows:
+            if subflow := self.subheartflows.get(subheartflow_id):
+                return subflow
+
+        try:
+            new_subflow = SubHeartflow(subheartflow_id)
+
+            await new_subflow.initialize()
+
+            # 注册子心流
+            self.subheartflows[subheartflow_id] = new_subflow
+            heartflow_name = get_chat_manager().get_stream_name(subheartflow_id) or subheartflow_id
+            logger.info(f"[{heartflow_name}] 开始接收消息")
+
+            return new_subflow
+        except Exception as e:
+            logger.error(f"创建子心流 {subheartflow_id} 失败: {e}", exc_info=True)
+            traceback.print_exc()
+            return None
+
+
+heartflow = Heartflow()