LobeChat插件开发入门：手把手教你写第一个扩展模块
在今天，一个AI助手如果只能聊天，那它大概率会被淘汰。真正让人眼前一亮的，是那些能查天气、读文件、调用内部系统、甚至帮你写代码的智能体——而这些能力，几乎都依赖于“插件”机制。
LobeChat 正是这样一个平台：它不只是一款漂亮的聊天界面，更是一个可被无限扩展的AI应用容器。基于 Next.js 构建，支持 GPT、通义千问、ChatGLM 等多种大模型，其核心亮点之一就是开放且易用的插件系统。这个系统让开发者无需改动主项目，就能为AI“装上新器官”。
更重要的是，你不需要成为全栈专家也能上手。只要熟悉 TypeScript 和 React，就可以快速写出自己的第一个功能模块。
我们不妨从一个最典型的场景开始：你想做一个命令/weather 北京，输入后自动返回当前天气信息。这背后涉及什么？
- 如何让 LobeChat “认识”你的插件？
- 它怎么知道什么时候该调用你写的逻辑？
- 又如何安全地发送消息、请求外部API？
答案就藏在三个关键组件中：插件入口脚本、manifest.json 配置文件、SDK运行时上下文。它们共同构成了 LobeChat 插件的骨架。
先来看最直观的部分——代码本身。
// plugins/weather/index.ts import { LobePlugin } from 'lobe-chat-plugin'; const plugin: LobePlugin = async (context) => { const { message, sendText, invoke } = context; if (!message.startsWith('/weather')) return; const location = message.replace('/weather', '').trim(); if (!location) { await sendText('请输入城市名称，例如：/weather 北京'); return; } try { const response = await fetch( `https://api.weather-example.com/current?city=${encodeURIComponent(location)}` ); const data = await response.json(); const weatherInfo = ` 📍 城市：${data.location} 🌡️ 温度：${data.temperature}°C ☁️ 天气：${data.condition} 💨 风速：${data.windSpeed} km/h `.trim(); await sendText(weatherInfo); } catch (error) { await sendText(`❌ 获取天气信息失败：${(error as Error).message}`); } }; export default plugin;这段代码看起来简单，但每一行都有讲究。
首先，类型LobePlugin定义了一个函数签名：接收一个context对象，并返回Promise<void>。这意味着你可以放心使用async/await处理异步任务，比如网络请求。这也是为什么我们在调用fetch时不必担心阻塞 UI。
context是整个插件的生命线。它不是随便传进来的一个对象，而是由主应用精心封装后的“沙箱环境”。你只能通过它提供的方法与外界交互，比如：
sendText(text)：向对话窗口输出纯文本；sendMarkdown(md)：支持富文本格式，适合展示结构化内容；invoke(toolName, args)：触发其他已注册工具，实现多插件协作；getLogger()：获取日志接口，用于调试和监控。
这种设计思路其实很像现代浏览器扩展或 VS Code 插件——赋予能力的同时限制权限。你不可以直接访问 DOM、localStorage 或全局变量，所有操作必须走 SDK 接口。这样一来，即使某个插件出错甚至恶意行为，也不会导致整个应用崩溃。
再看判断逻辑：if (!message.startsWith('/weather')) return;
这是最常见的命令匹配方式。虽然简单，但也足够有效。不过要注意，如果你希望支持更多别名（如/tianqi），可以在manifest.json中声明多个 command，或者在这里做更复杂的正则匹配。
至于数据获取部分，直接用了浏览器原生的fetch。这一点非常友好——意味着你可以轻松集成任何公开 API。当然，在生产环境中建议加上代理层来规避 CORS 问题，敏感字段也应通过环境变量注入，而不是硬编码在代码里。
那么问题来了：LobeChat 怎么知道有这么一个“天气插件”存在？又凭什么相信它可以响应/weather？
这就轮到manifest.json登场了。
{ "identifier": "com.example.weather", "name": "Weather Assistant", "version": "1.0.0", "author": "Dev Team", "description": "Get real-time weather information by city name.", "commands": [ { "command": "/weather", "description": "查询指定城市的实时天气" } ], "permissions": ["network"] }这个文件就像是插件的“身份证”。当 LobeChat 启动时，会自动扫描plugins/目录下的子目录，寻找符合规范的manifest.json文件。只有格式正确、必填字段齐全的插件才会被加载。
其中最关键的是identifier—— 它必须全局唯一，推荐使用反向域名格式（如com.company.plugin-name）。一旦重复，后面的插件可能会覆盖前面的，造成不可预知的行为。
commands字段定义了用户如何触发该插件。目前主流是斜杠命令（Slash Command），符合 Slack、Discord 等平台的习惯。未来也可能支持关键词唤醒或事件监听模式。
还有一个常被忽略但极其重要的点：不要在 manifest 中存放 API Key 或密钥。这类敏感信息应该通过环境变量或用户配置页面动态传入，避免泄露风险。
值得一提的是，这个 JSON 结构也为将来构建“插件市场”打下了基础。你可以想象一个插件商店，用户搜索“天气”，就能看到所有相关插件的名称、描述、评分和权限需求。这一切都可以在不运行代码的情况下完成静态分析。
现在我们知道插件怎么写、怎么声明，但它是如何被执行的？
让我们把视线拉回到整体架构。
+----------------------------+ | 用户界面 (UI) | | - 聊天窗口 | | - 输入框 | | - 插件面板 | +------------+---------------+ | 触发命令 → 匹配插件 | +------------v---------------+ | 插件运行时环境 (Sandbox) | | - 动态加载插件脚本 | | - 注入 SDK Context | | - 执行插件逻辑 | +------------+---------------+ | 调用 → 外部服务/API | +------------v---------------+ | 主应用服务层 | | - 会话管理 | | - 模型调度 | | - 日志记录 | +----------------------------+整个流程非常清晰：
- 用户输入
/weather 上海并回车； - 主程序解析出命令前缀
/weather； - 查找所有已注册插件中是否有匹配项；
- 若找到，动态加载对应模块（若尚未加载）；
- 创建
context上下文对象，包含当前会话 ID、用户输入、可用方法等； - 调用插件主函数，传入 context；
- 插件执行逻辑，可能发起网络请求；
- 数据返回后，调用
sendText将结果推送到聊天窗口； - 消息自动存入会话历史，完成闭环。
整个过程通常在 300~800ms 内完成，体验接近原生功能。
但这并不意味着可以肆意编写低效代码。比如，如果你每次调用都 import 一个巨大的库，性能很快就会崩塌。合理的做法是：
- 使用懒加载（lazy import）按需引入依赖；
- 对频繁请求的数据做本地缓存（如城市ID映射表）；
- 避免在
message监听器中做重计算，除非明确匹配命令。
此外，用户体验也不能忽视。超过 1 秒的响应应当显示加载状态；支持取消正在进行的操作；输出尽量结构化，比如用 Markdown 表格呈现天气趋势，而非一大段纯文本。
说到这里，你可能已经发现，LobeChat 的插件机制并不仅仅是为了“多几个功能”。它的深层价值在于解耦与生态共建。
试想一家企业要部署 AI 助手：
- 销售团队需要查 CRM 数据；
- HR 想让它读员工手册；
- 技术组希望集成 Jira 和代码仓库。
如果把这些功能全部塞进主程序，代码将迅速变得臃肿不堪，维护成本飙升。而采用插件化之后，每个团队可以独立开发、测试、发布自己的模块，互不影响。管理员还可以根据不同角色开启不同的插件集合，真正做到“千人千面”。
这也降低了社区贡献的门槛。一个前端开发者不需要理解整个 LobeChat 的源码结构，只要按照文档写出符合规范的插件，就能提交 PR 或发布到插件市场。这种模式正是 VS Code、Figma、Notion 等成功产品所验证过的路径。
最后，来点实战建议。
如果你想动手尝试，可以从这几个方向入手：
✅ 快速起步模板
mkdir -p plugins/hello-world cd plugins/hello-world创建manifest.json：
{ "identifier": "com.example.hello", "name": "Hello World", "version": "1.0.0", "commands": [ { "command": "/hello", "description": "Say hello!" } ] }创建index.ts：
import { LobePlugin } from 'lobe-chat-plugin'; const plugin: LobePlugin = async ({ message, sendText }) => { if (message === '/hello') { await sendText('🎉 Hello from your first plugin!'); } }; export default plugin;保存后刷新页面，输入/hello，你应该能看到回复。
⚠️ 常见坑点提醒
- 目录结构错误：确保插件目录下有
manifest.json和入口文件，否则不会被识别。 - 缓存问题：浏览器可能缓存旧版本插件，开发时建议开启无痕模式或禁用缓存。
- 类型缺失：安装
lobe-chat-plugin类型包以获得 IDE 提示。 - 跨域问题：本地调试时注意 API 是否允许前端调用，必要时配置 proxy。
🛠 进阶玩法
- 返回图片：使用
sendImage(url)展示图表或截图； - 多步骤交互：结合
sessionId实现状态机，引导用户完成复杂任务； - 工具链协同：用
invoke("calculator", {expr: "2+3"})调用其他插件； - 国际化支持：根据用户语言动态切换提示语。
当你写下第一个sendText("Hello!")的那一刻，你就不再是 LobeChat 的普通用户，而成了它的塑造者。
这个框架真正的野心，从来不只是做个好看的聊天框。它想成为一个每个人都能定制的 AI 操作系统——而插件，就是通往那扇门的钥匙。
所以，别再等了。打开编辑器，创建你的plugins/my-first-plugin目录，写下那句export default async (ctx) => { ... }。
下一个改变体验的功能，也许就出自你手。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考