插件开发流程

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 加页面产物构建脚本)

「类型检查」与「构建」是两个独立环节、分别报告结果;平台安装准备与开发模式自动构建执行的正是这两条脚本。

安装与启用

  1. 打开主导航「插件中心」→「安装插件」;
  2. 选择来源:本地工程目录、.zip/.tgz 插件包、npm 包名加精确版本,或 Git HTTPS 地址加完整 40 位提交 SHA;
  3. 已含完整 JS 与页面产物的包直接安装;源码工程勾选「准备依赖、类型检查并构建」,需要工程提供 package-lock.json,准备过程执行真实 npm 安装脚本;
  4. 阅读并勾选代码信任说明后安装,在「运行与安装记录」查看进度与构建日志;
  5. 完成后在插件列表启用、打开或停用;展开「详情」查看页面、命令、适用位置与自动事件。

用外部 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 工具开发(可选)

接入外部编程工具后推荐按顺序执行:

  1. 让 AI 先读 plugin_sdk 与 get_app_guide(section:"plugins"),了解清单、SDK 类型、页面桥接与保存契约;
  2. plugin_project_create 创建工程;
  3. plugin_project_run 依次执行 lock/install/typecheck/build/test 脚本,plugin_task 读取结果;
  4. plugin_install 开发模式安装,plugin_enable 启用,plugin_open_view 预览;
  5. 修改源码后靠开发模式自动重建刷新,诊断问题用 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 上手」。