插件开发流程
2026-11-15
插件是运行在大懒猫创作平台桌面端里的扩展程序:可以提供独立页面、命令、菜单入口、自定义文件编辑器、后台自动任务,以及供其他插件调用的服务。官方的「微信公众号发布」「排版导出」本身就是插件。插件在独立进程中以当前用户权限运行,可以使用标准 Node 的文件、网络与子进程能力;进程隔离用于隔离普通故障,不是安全沙箱,只开发与安装自己信任的代码。接口细节见「插件 SDK 上手」。
准备运行环境
插件后台运行在 Node 22 上(22.23.3 及以上、23 以下;npm 10.9.9 及以上)。安装包不携带 Node/npm,首次开发前打开「设置 → 运行环境」二选一:
- 本机安装:自行安装后点「检测并使用本机环境」,未加入 PATH 时手动指定 Node 可执行文件;
- 应用专用版本:点「下载并使用专用版本」,应用从 Node.js 官方下载对应系统架构的版本,校验 SHA-256 后保存在应用数据目录,不改系统环境,下载后可离线使用。
配置成功后无须重启应用即可使用插件;切换运行环境前,先停用插件后台并停止任务。
创建工程
三种方式任选,得到的都是普通 npm 工程:
- 模板仓库(推荐):打开 biglazycat-writer/blc-plugin-template,点「Use this template」生成自己的仓库,或命令行执行
gh repo create my-plugin --template biglazycat-writer/blc-plugin-template --private --clone。模板自带后台命令、浏览器页面、状态保存、打包脚本与测试,按其 README 的「必改清单」改好包名与命令前缀即可开发(详细介绍见「插件模板工程」); - 外部编程工具:在系统设置 → MCP 服务启用连接并勾选「插件开发与管理」工具,让 Codex、Claude Code 等通过应用的
--mcp-stdio接入(接入方法见「MCP 与外部 AI」),然后调用plugin_project_create在指定空目录生成标准 TypeScript 工程,源码编辑与版本管理由外部工具负责; - 手工创建:自行建立 npm 工程,直接依赖公开 npm 包
blc-plugin-sdk,无需本地副本或全局安装。
package.json 的 biglazycat 字段是插件唯一清单:
{
"name": "my-plugin",
"version": "0.1.0",
"type": "module",
"engines": { "node": ">=22.23.3 <23.0.0" },
"dependencies": { "blc-plugin-sdk": "^1.3.0" },
"scripts": { "typecheck": "tsc --noEmit", "build": "tsc" },
"biglazycat": {
"apiVersion": 1,
"displayName": "我的插件",
"main": "dist/main.js",
"platforms": ["windows/amd64", "darwin/arm64", "linux/amd64"],
"contributes": {
"commands": [{ "id": "hello", "title": "运行示例", "aiCallable": true }]
}
}
}
清单逐字段说明见「SDK 清单 Schema」;完整签名以随 SDK 提供的 manifest.schema.json 与 index.d.ts 为准。宿主按 API 修订递进提供新能力(文档导出为修订 1,明暗模式与用户入口为修订 2,文稿导航为修订 3),插件用到对应能力时在清单写 minimumApiRevision 声明最低要求。提交工程时保留源码、构建脚本、测试与 package-lock.json,排除 node_modules。
实现入口代码
后台入口 main 导出一个 definePlugin 调用。所有命令与服务必须在激活时一次注册齐,与清单声明一致,不要等首次调用再补注册;激活函数可返回清理函数,停用插件时释放自己创建的连接与监听器。
import { definePlugin } from 'blc-plugin-sdk'
export default definePlugin(ctx => {
ctx.commands.register('hello', async (_args, invocation) => {
invocation.signal.throwIfAborted()
await invocation.progress(0.5, '正在处理')
return { message: '你好,大懒猫创作平台!' }
})
return async () => {
// 释放自己创建的连接、监听器等
}
})
纯页面插件可省略 main;纯后台插件不必创建页面。ESM/CJS、动态导入与标准 Node API 均可使用;原生模块必须匹配目标系统、架构与 Node ABI。页面 entry 指向构建产物中的普通 HTML 文件,页面代码可用 Vite、React、Vue 等任意浏览器工具链构建,页面里用 blc-plugin-sdk/browser 的 connect() 与宿主通信,禁止在浏览器直接导入 Node 模块。
类型检查与构建
TypeScript 必须用工程脚本真实编译,Node 直接运行 TS(类型擦除)不算通过编译:
npm run typecheck # tsc --noEmit
npm run build # tsc(或 tsc 加页面产物构建脚本)
「类型检查」与「构建」是两个独立环节、分别报告结果;平台安装准备与开发模式自动构建执行的正是这两条脚本。
安装与启用
- 打开主导航「插件中心」→「安装插件」;
- 选择来源:本地工程目录、
.zip/.tgz插件包、npm 包名加精确版本,或 Git HTTPS 地址加完整 40 位提交 SHA; - 已含完整 JS 与页面产物的包直接安装;源码工程勾选「准备依赖、类型检查并构建」,需要工程提供
package-lock.json,准备过程执行真实 npm 安装脚本; - 阅读并勾选代码信任说明后安装,在「运行与安装记录」查看进度与构建日志;
- 完成后在插件列表启用、打开或停用;展开「详情」查看页面、命令、适用位置与自动事件。
用外部 AI 工具开发时也可全程走 MCP:plugin_install 指定本地目录并带 development:true、prepare:false、trusted:true 与唯一 requestId,返回任务;成功后 plugin_enable 启用、plugin_open_view 在产品内预览页面。
开发模式调试
以开发模式安装的本地目录进入自动刷新:应用每秒检测源码,连续两次稳定后在隔离目录执行类型检查与构建,成功后切换产物并重新打开同一页面实例,保留实例与已保存的恢复状态;dist、node_modules、.git、.cache、coverage 不触发构建。
- 构建失败保留最后成功的页面,用
plugin_diagnostics、plugin_task(或插件详情的诊断面板)查看日志; - 有未结束任务或未保存页面时刷新推迟;
- 依赖先在外部工程安装,开发模式不代装依赖;停用插件即停止开发监听,卸载保留开发源码;
- 凭据只放后台 credentials 存储,不能写进清单、源码或页面恢复状态。
用外部 AI 工具开发(可选)
接入外部编程工具后推荐按顺序执行:
- 让 AI 先读
plugin_sdk与get_app_guide(section:"plugins"),了解清单、SDK 类型、页面桥接与保存契约; plugin_project_create创建工程;plugin_project_run依次执行 lock/install/typecheck/build/test 脚本,plugin_task读取结果;plugin_install开发模式安装,plugin_enable启用,plugin_open_view预览;- 修改源码后靠开发模式自动重建刷新,诊断问题用
plugin_diagnostics与plugin_task。
MCP 写操作必须携带唯一 requestId,重试同一动作复用该值、不同动作用不同值;安装与脚本运行需要明确 trusted:true。插件命令只向外部 AI 开放清单中 aiCallable:true 的项目,外部模型不能注入宿主工作区身份。
打包与分发
安装中心支持四种来源,按受众任选:
- 插件包:
.zip或.tgz,内含构建产物(JS、页面 HTML 与依赖);模板工程用npm run package一键生成dist-package/<名称>-<版本>.tgz与 SHA-256 校验文件;含原生模块时需覆盖全部目标平台; - npm 包:发布到 npm 仓库,安装时填包名与精确版本;
- Git:HTTPS 地址加完整 40 位提交 SHA;不要把账号或令牌写进 URL,插件中心拒绝带身份信息、查询参数或片段的地址;
- 本地目录:适合内部工具与开发期分发。
清单 platforms 声明支持的系统与架构,宿主按其校验。接口、限制与错误码的完整列表见「插件 SDK 上手」。