LobeChat插件开发入门：手把手教你写第一个扩展模块-平芜编程栈

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，你应该能看到回复。