Plugin Development Process
2026-11-15
Plugins are extensions that run inside the 大懒猫创作平台 desktop app: they can provide standalone pages, commands, menu entries, custom file editors, background scheduled tasks, and services for other plugins to call. The official "WeChat publishing" and "Typeset export" features are themselves plugins. A plugin runs in its own process with the current user's permissions and may use standard Node file, network and subprocess capabilities; process isolation guards against ordinary faults, it is not a security sandbox — only develop and install code you trust. For interface details see Plugin SDK Overview.
Prepare the runtime
The plugin backend runs on Node 22 (22.23.3 or newer, below 23; npm 10.9.9 or newer). The installer does not bundle Node/npm. Before developing, open "Settings → Runtime" and pick one:
- Local install: install Node yourself and click "Detect and use local runtime"; point to the Node executable manually if it is not on PATH;
- App-managed version: click "Download the managed version" — the app fetches the build for your system architecture from Node.js official servers, verifies SHA-256 and stores it in the app data directory without touching system settings; it works offline after download.
No restart is needed after configuration; before switching runtimes, stop plugin backgrounds and tasks.
Create a project
Any of the three routes yields an ordinary npm project:
- Template repo (recommended): open biglazycat-writer/blc-plugin-template and click "Use this template", or run
gh repo create my-plugin --template biglazycat-writer/blc-plugin-template --private --clone. The template ships background commands, a browser page, state saving, packaging scripts and tests — rename a few things per its README checklist and start coding (details in Plugin Template); - External coding tools: enable the connection under System settings → MCP services and tick the "plugin development & management" tools so Codex, Claude Code etc. can attach via the app's
--mcp-stdio(setup at MCP & External AI), then callplugin_project_createto generate a standard TypeScript project in an empty directory; editing and version control stay in your own tools; - Manual: create an npm project and depend on the public npm package
blc-plugin-sdk— no vendored copy or global install needed.
The biglazycat field in package.json is the single plugin manifest:
{
"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": "My plugin",
"main": "dist/main.js",
"platforms": ["windows/amd64", "darwin/arm64", "linux/amd64"],
"contributes": {
"commands": [{ "id": "hello", "title": "Run example", "aiCallable": true }]
}
}
}
Field-by-field notes live in SDK Manifest Schema; the authoritative signatures are manifest.schema.json and index.d.ts shipped with the SDK. The host delivers new capabilities by API revision (document export = revision 1, color scheme & user entries = revision 2, document navigation = revision 3); declare minimumApiRevision when you rely on one. Commit sources, build scripts, tests and package-lock.json; exclude node_modules.
Implement the entry
The main backend entry exports a definePlugin call. Register every command and service during activation, matching the manifest — never register lazily on first call. The activate function may return a cleanup function that runs when the plugin is deactivated.
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, 'Working')
return { message: 'Hello, 大懒猫 Creator!' }
})
return async () => {
// release connections, listeners, etc.
}
})
A page-only plugin may omit main; a background-only plugin needs no page. ESM/CJS, dynamic imports and standard Node APIs all work; native modules must match the target OS, architecture and Node ABI. A page entry points to a plain HTML file in the build output — build pages with Vite, React, Vue or any browser toolchain, and talk to the host with connect() from blc-plugin-sdk/browser; importing Node modules in the browser is not allowed.
Typecheck and build
TypeScript must be compiled by real project scripts; running TS directly on Node (type stripping) does not count:
npm run typecheck # tsc --noEmit
npm run build # tsc (plus your page bundler)
"Typecheck" and "build" are separate steps reported separately; install preparation and development-mode auto-builds run exactly these two scripts.
Install and enable
- Open the main navigation "Plugin center" → "Install plugin";
- Pick a source: a local project directory, a
.zip/.tgzpackage, an npm name with an exact version, or a Git HTTPS URL plus a full 40-character commit SHA; - Packages that already ship JS and page artifacts install directly; source projects tick "prepare dependencies, typecheck and build", which requires
package-lock.jsonand runs real npm scripts; - Review and accept the code-trust notice, then watch progress and build logs under "runs & install history";
- Enable, open or stop the plugin from the list; expand "details" to see pages, commands, entry points and automatic events.
When developing with external AI tools everything can also run over MCP: plugin_install with a local directory plus development:true, prepare:false, trusted:true and a unique requestId returns a task; then plugin_enable and plugin_open_view to preview inside the app.
Development mode
A local directory installed in development mode gets auto-refresh: the app watches the sources every second, and after two stable reads runs typecheck & build in an isolated directory, swaps in the successful artifacts and reopens the same page instance with its saved state; dist, node_modules, .git, .cache and coverage never trigger builds.
- When a build fails the last working page stays; inspect
plugin_diagnosticsandplugin_task(or the diagnostics panel in plugin details) for logs; - Refresh is postponed while tasks are running or pages are unsaved;
- Install dependencies in the external project first — development mode never installs them for you; stopping the plugin stops the watcher, uninstalling keeps the sources;
- Credentials belong in the backend credentials store only — never in the manifest, sources or page state.
Developing with external AI tools (optional)
After attaching a coding tool, a good sequence is:
- Let the AI read
plugin_sdkandget_app_guide(section:"plugins")first — manifest, SDK types, page bridge and save contract; plugin_project_createto scaffold;plugin_project_runfor lock/install/typecheck/build/test in order, reading results withplugin_task;plugin_installin development mode, thenplugin_enable, thenplugin_open_viewto preview;- After edits, development mode rebuilds automatically; diagnose with
plugin_diagnosticsandplugin_task.
MCP write operations must carry a unique requestId — reuse it when retrying the same action, use a new one per action; installing and running scripts require trusted:true. Only commands marked aiCallable:true in the manifest are exposed to external AI, and external models cannot inject workspace identity.
Package and distribute
The install center accepts four sources:
- Plugin package:
.zipor.tgzcontaining build artifacts (JS, page HTML and dependencies); the template'snpm run packageproducesdist-package/<name>-<version>.tgzplus a SHA-256 file in one step; native modules must cover every target platform; - npm package: publish to the npm registry; installers enter the package name with an exact version;
- Git: HTTPS URL plus a full 40-character commit SHA; never put credentials or tokens in the URL — the plugin center rejects URLs with userinfo, query strings or fragments;
- Local directory: for internal tools and in-development distribution.
The manifest's platforms declares supported systems and architectures and the host enforces it. For the full interface, limits and error codes see Plugin SDK Overview.