---
title: "迁移指南"
---

本教程高亮了某些注意事项，请各位插件开发者在已阅读现版本插件教程后，再以此文档作为参考进行插件迁移。

## 从 3.x 支持的异步插件迁移

<Info title="插件特征：">
- 主要时间段：2024.2 ~ 2025.8
- 注册方式：`main.py` 中的插件类中使用 `@handler` 装饰器注册事件监听器、使用 `@llm_func` 装饰器注册内容函数（工具）；处理函数均为异步函数(async def)
</Info>

- 插件和组件注册方式：已由以往的单一插件类中的装饰器注册方式，改为了清单文件注册方式，参阅[清单文件](/zh/plugin/dev/basic-info)；并将各个不同类型的组件独立出来，详细请见[添加组件](/zh/plugin/dev/components/add)。
- 消息链实体：现已重构，每个消息链元素的构造方法现在需要显式传入**具名参数**，参阅[消息平台实体](/zh/plugin/dev/apis/messages)。
- 事件监听器：提供向后兼容性，但不再于上下文中提供`query: Query`对象，详细请参阅[流水线事件](/zh/plugin/dev/apis/pipeline-events)。
- 命令组件：现已重构，请参阅[命令组件](/zh/plugin/dev/components/command)。

## 从 2.x 和 3.x 支持的同步插件迁移

<Info title="插件特征：">
- 主要时间段：2023.1 ~ 2024.2
- 注册方式：`main.py` 中的插件类中使用 `@on` 装饰器注册事件监听器、使用 `@func` 装饰器注册内容函数（工具）；处理函数均为同步函数(def)
</Info>

- 同步改异步：插件运行时现已改为全异步（基于asyncio），请将插件所有涉及 IO 操作的代码改为异步写法。
- 详细内容请参阅上述 3.x 异步插件迁移指南。