LobeChat插件开发入门：手把手教你写第一个AI扩展
在今天，一个智能助手能不能“真正办事”，已经成了用户判断它是否好用的核心标准。我们不再满足于AI只会聊天、讲笑话或写诗——我们希望它能查天气、看股价、发邮件，甚至操作公司内部系统。但大模型本身是静态的，它的知识有截止日期，也无法直接访问外部服务。
于是，插件（Plugin）机制应运而生。它是连接“语言理解”与“真实世界操作”的桥梁。而在众多开源AI聊天平台中，LobeChat 凭借其优雅的设计和强大的可扩展性，正迅速成为开发者构建定制化AI助手的首选。
本文不走寻常路——不会一上来就堆概念、列优势。我们直接动手，从零开始为 LobeChat 写一个能用的插件，过程中自然带出它的设计哲学和技术细节。你会发现，这不仅是“加个功能”，更是一种全新的AI交互范式。
从一个问题开始：AI怎么知道今天的天气？
假设你在使用 LobeChat，输入了一句：“北京现在几度？”
你期待的回答不是“我不知道”，而是类似：“北京当前气温26°C，晴。”
但问题来了：大模型训练数据里哪来的实时气温？答案是——它自己不知道，但它可以“打电话问”。
这个“打电话”的过程，就是插件在背后完成的。LobeChat 并不会把所有功能都写死在核心代码里，而是留出接口，让外部模块来响应特定请求。这种“平台+插件”的架构，正是现代AI应用灵活扩展的关键。
那么，我们要做的第一件事，就是教会 LobeChat 如何识别“查天气”这个意图，并调用一个独立模块去获取结果。
插件长什么样？两个文件搞定
在 LobeChat 中，一个最简单的插件只需要两个文件：
manifest.ts：描述插件的基本信息和能力index.ts：定义插件的实际执行逻辑
就这么简单。不需要注册路由、不用配置中间件，也不用重启主服务——只要放对位置，LobeChat 启动时就会自动加载。
第一步：告诉系统“我能干什么”
// plugins/weather-plugin/manifest.ts import { PluginManifest } from 'lobe-chat-plugin'; const manifest: PluginManifest = { id: 'com.example.weather', version: '0.1.0', name: '天气查询', description: '根据城市名称获取当前天气状况', icon: 'https://example.com/icons/weather.png', api: { url: 'https://api.weather-example.com/v1/current', method: 'GET', parameters: [ { name: 'city', type: 'string', required: true, description: '城市名称，如北京、New York', }, ], }, }; export default manifest;这段代码看起来像一份“简历”：我叫什么、我能做什么、需要什么参数。其中最关键的是parameters字段——它让 LobeChat 知道用户说“上海天气如何”时，应该提取出city: 上海这个结构化参数。
有意思的是，这里的url和method并非强制发起请求的位置，而是一种声明式提示。你可以完全忽略它，在index.ts里自由实现逻辑。但它对调试和可视化非常有用，比如未来可能支持自动生成 API 文档或表单输入界面。
第二步：真正去“查天气”
// plugins/weather-plugin/index.ts import { PluginAction } from 'lobe-chat-plugin'; const action: PluginAction = async ({ params }) => { const { city } = params; if (!city) { return { error: { type: 'user_error', message: '请提供城市名称。', }, }; } try { const response = await fetch( `https://api.weather-example.com/v1/current?city=${encodeURIComponent(city)}` ); if (!response.ok) { throw new Error(`天气服务返回错误: ${response.status}`); } const data = await response.json(); return { result: { temperature: data.current.temp_c, condition: text, city: data.location.name, unit: 'Celsius', }, }; } catch (err: any) { return { error: { type: 'system_error', message: `无法获取天气数据：${err.message}`, }, }; } }; export default action;这才是真正的“行动派”。当系统决定调用这个插件时，就会执行这个异步函数。注意几个关键点：
- 输入是结构化后的
params，不再是原始文本，省去了大量 NLU 解析工作； - 返回值必须是
{ result: ... }或{ error: ... }格式，框架会自动处理后续渲染； - 整个执行过程运行在沙箱环境中，即使出错也不会导致主应用崩溃。
更重要的是，你完全可以在这里做任何事：调用 gRPC 接口、查询数据库、生成 PDF 文件……只要最终返回一个 JSON 对象，LobeChat 就能把它变成自然语言输出。
它是怎么被发现并调用的？
很多人以为插件调用依赖复杂的意图识别模型，其实不然。LobeChat 的做法更轻量也更实用：基于规则匹配 + 轻量级语义辅助。
当你输入“上海现在的天气怎么样？”，系统会：
- 扫描所有已启用插件的
name和description； - 使用关键词匹配（如“天气”）初步筛选候选插件；
- 调用内置的小型 NLU 模块提取参数（
city: 上海）； - 验证参数是否符合插件声明的要求；
- 如果通过，则触发对应插件的
action函数。
整个过程毫秒级完成，用户毫无感知。就像 AI “突然想起来”它可以查天气一样。
这也意味着，插件命名和描述的质量直接影响可用性。如果你把插件叫做“气象服务v1”，系统很可能无法关联到“查天气”这个日常表达。建议使用贴近用户语言的词汇，例如“查天气”、“搜订单”、“发邮件”等。
插件不只是“工具”，更是AI的认知延伸
别小看这两个文件，它们代表了一种新的软件组织方式。
传统上，我们要给聊天机器人增加功能，往往需要修改核心逻辑，重新部署整个应用。而现在，每个插件都是独立的 npm 包，可以由不同团队维护，独立测试、发布和更新。
想象一下这样的场景：
- 客服团队开发了一个
ticket-query插件，用于查询工单状态； - HR 团队写了
leave-balance插件，员工可以直接问“我还有几天年假”； - 运维组做了
server-status插件，值班人员只需说“看看线上服务是否正常”。
这些功能彼此隔离，互不影响，却又通过统一的对话界面呈现给用户。这就是微服务思想在AI层面的体现。
而且，由于所有插件遵循相同的返回格式，LobeChat 可以自动将结构化数据美化成卡片、表格或语音播报，无需开发者关心 UI 实现。
开发体验：像写前端一样写AI扩展
LobeChat 基于 TypeScript + Next.js 构建，这意味着插件开发拥有完整的类型安全支持。
举个例子，当你写下params.时，IDE 会立刻提示你有哪些可用字段：
params.city // string | undefined params.unit // 'celsius' | 'fahrenheit' | undefined这是因为PluginAction类型自带泛型约束，你可以这样写：
interface WeatherParams { city: string; unit?: 'celsius' | 'fahrenheit'; } const action: PluginAction<WeatherParams> = async ({ params }) => { // params 类型自动推导 };编译时就能发现拼写错误、缺失必填参数等问题，大大降低调试成本。
再加上本地开发支持热重载，改完代码刷新页面即可看到效果，几乎没有任何等待时间。这种“即时反馈”极大地提升了开发效率。
安全与工程实践：别让插件变成漏洞入口
虽然插件带来了灵活性，但也引入了新的风险。毕竟，第三方代码一旦被执行，就可能读取环境变量、发起网络请求，甚至尝试攻击主系统。
为此，LobeChat 在设计上做了多层防护：
- 沙箱执行：插件运行在受限的 JavaScript 上下文中，无法访问
require、process等危险对象； - 权限控制：未来计划支持细粒度权限配置，例如“仅允许调用指定域名的API”；
- 敏感信息保护：建议通过环境变量注入 API Key，并禁止在日志中打印参数；
- 超时机制：默认设置 5 秒超时，防止慢请求阻塞对话流程。
此外，还有一些值得遵循的最佳实践：
✅ 推荐做法
# .env.local WEATHER_API_KEY=your-secret-key LOBE_PLUGIN_LOCAL_PATH=./plugins// index.ts const apiKey = process.env.WEATHER_API_KEY; const response = await fetch(`${url}?city=${city}&key=${apiKey}`);❌ 绝对禁止
// 千万不要硬编码密钥！ const apiKey = 'sk-live-xxxxxx'; // 不要随意打印用户输入 console.log('params:', params); // 可能泄露隐私同时，建议为高频接口添加缓存。比如天气数据每10分钟更新一次就够了，没必要每次查询都打到第三方API。可以用内存缓存或 Redis 实现：
const cache = new Map<string, any>(); if (cache.has(cacheKey) && Date.now() - cache.get(cacheKey).timestamp < 600000) { return { result: cache.get(cacheKey).data }; }既节省资源，又提升响应速度。
更进一步：不只是“问答”，还能“做事”
目前我们做的还是“查询类”插件，但 LobeChat 的潜力远不止于此。
设想这样一个插件：create-meeting，用户说“明天上午10点和张经理开会”，AI 自动：
- 查询双方日历空闲时段；
- 发送会议邀请；
- 创建待办事项；
- 回复：“已为您安排明天10:00-11:00的会议，会议室A302已预留。”
这类“动作型”插件才是真正意义上的“AI代理”。它们不仅能回答问题，还能替你完成任务。
要实现这一点，关键在于：
- 插件之间可以组合调用（未来可能支持）；
- 支持多轮对话上下文管理；
- 允许异步执行长时间任务并通知结果。
虽然当前版本还在演进中，但架构上已经预留了这些可能性。这也是为什么我说 LobeChat 不只是一个聊天界面，而是一个可编程的 AI 扩展平台。
最后一点思考：为什么我们需要开源的插件生态？
市面上不乏带有插件功能的商业产品，但大多封闭、昂贵且绑定厂商。而 LobeChat 的意义在于：
- 技术自主可控：企业可以在内网部署，对接私有系统，无需担心数据外泄；
- 低成本创新：一个小团队花半天时间就能验证一个新想法；
- 社区共建共享：开发者可以把通用插件贡献出来，形成公共能力库；
- 避免 vendor lock-in：所有插件都是标准 npm 包，迁移成本极低。
当你看到越来越多的人开始分享“快递查询”、“股票行情”、“翻译助手”这类通用插件时，你会发现，一个真正的 AI 工具生态正在形成。
结语：下一个爆款AI功能，也许就藏在你的一个插件里
回到最初的问题：AI 怎么知道今天的天气？
答案已经很清楚了：它不知道，但它会“问”。而谁来回答？是你我这样的开发者，用一个个小小的插件，一点点扩展它的能力边界。
LobeChat 的设计理念很朴素：把复杂留给框架，把简单留给创造。你不需要懂深度学习，也能做出有用的 AI 功能；你不必重构整个系统，就能让它变得更聪明。
所以，别再等了。现在就去创建你的第一个插件吧。无论是查天气、算房贷，还是连上家里的智能灯泡，每一步都在推动 AI 真正走进生活。
说不定，下一个人人使用的 AI 功能，就始于你写的那两行代码。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
