LobeChat自定义插件需创建含manifest.json和index.ts的目录结构，编写继承Plugin类的逻辑代码，配置settings.ts启用插件ID，调试验证触发与返回，最后打包为ESM模块部署。

☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

如果您希望为LobeChat添加特定功能，例如集成内部API、增强对话上下文处理或连接第三方服务，则需要通过自定义插件实现。LobeChat支持基于插件系统扩展行为，以下是开发与配置自定义插件的具体步骤：

一、创建插件基础结构

LobeChat插件需遵循固定目录结构和文件规范，以确保被主程序识别并加载。插件根目录必须包含manifest.json和index.ts两个核心文件，且需置于plugins子目录下。

1、在LobeChat项目根目录下，确认存在plugins文件夹；若不存在，则手动创建。

2、在plugins目录中新建子文件夹，命名为具有语义的插件标识符，例如my-internal-api。

3、在该子文件夹内创建manifest.json文件，写入插件元信息，其中id字段必须为唯一字符串，name和description为必填项。

4、在同一目录下创建index.ts文件，导出默认插件类，该类须继承Plugin基类并实现onMessage等必要生命周期方法。

二、编写插件逻辑代码

插件功能逻辑封装在index.ts中，通过监听消息事件、调用外部接口或修改上下文数据完成扩展。所有异步操作需返回Promise，且不可阻塞主线程。

1、在index.ts顶部导入所需依赖：import { Plugin, type Message } from '@lobehub/chat-plugin-sdk';

2、定义插件类，例如class MyInternalAPIPlugin extends Plugin，并在构造函数中初始化配置参数。

3、重写onMessage方法，在其中判断用户消息是否触发插件响应，例如检测到特定关键词/fetch-data时发起HTTP请求。

4、使用this.fetch方法（SDK内置封装）调用后端接口，并将响应结果格式化为Message对象返回给对话流。

三、配置插件启用状态

LobeChat不会自动启用所有插件，需在全局配置中显式声明已安装插件的ID列表，否则插件代码不会被实例化或监听事件。

1、打开app/config/settings.ts文件（或对应环境的配置入口）。

2、定位到plugins字段，将其值修改为包含目标插件ID的字符串数组，例如['my-internal-api', 'weather-plugin']。

3、确保插件ID与manifest.json中定义的id字段完全一致，包括大小写和连字符。

4、保存文件后重启LobeChat开发服务器，使配置生效。

四、调试插件运行行为

插件在运行时可通过控制台日志和消息拦截机制进行验证，避免因未捕获异常或错误返回格式导致静默失败。

1、在插件类的onMessage方法开头添加console.log('MyInternalAPIPlugin triggered:', message)用于确认触发。

2、在HTTP请求后使用.catch捕获错误，并调用this.notifyError向UI推送提示，例如this.notifyError('API调用失败，请检查网络')。

3、在LobeChat界面中发送匹配触发条件的消息，观察开发者工具Console面板是否有预期日志输出。

4、检查聊天窗口是否正确渲染插件返回的Message内容，特别注意content字段是否为字符串类型，非字符串内容将被忽略。

五、打包并部署插件

本地开发完成后，插件需以独立模块形式发布，以便在不同LobeChat实例中复用。打包产物应保持零依赖、ESM兼容性，并提供类型声明。

1、在插件目录下初始化package.json，设置"type": "module"和"exports"字段指向./index.ts。

2、使用tsc --build或Vite构建工具生成dist/index.js和dist/index.d.ts。

3、将dist目录整体复制至目标LobeChat部署环境的plugins/my-internal-api/路径下。

4、确认manifest.json仍位于plugins/my-internal-api/根级，且dist/index.js被manifest.json中的main字段引用，路径必须为相对dist的相对路径。