Plugin Development

Plugins provide instructions, tools, incoming messages, agent runtimes and Capsule views. Operational programs, credentials and file access stay on the selected Desktop / Runner; declared UI modules execute in the current client. The service manages accounts, installations, permissions and routing.

Where to Start

Third-party local tools can be developed, validated, packed, and imported on the selected device through common configuration and execution. This flow requires no PR, host integration, official catalog entry, or official CI. Feishu provides a business-tool reference; science-data provides installed Capsule client modules. The Quickstart distinguishes package validation, activation confirmation, and actual calls. Public download publication, new platform message adapters, and new Agent Runtimes remain future work.

Basic Concepts

For a plugin that reads GitHub issues, the author declares a tool. The user installs a version, configures a GitHub identity on their Desktop, and permits reads. LiyanLabs checks these conditions and sends calls to that device.

ConceptMeaningExample
PluginA stable plugin identityThe GitHub plugin
ReleasePublished files, manifest, and capability declarationsThe installed version; published content stays fixed
CapabilityWhat the author says the plugin providesAn issue-reading tool or instructions
InstallationAn account's selected version and deviceThis version installed on the work computer
ConnectionA provider identity or named device configurationA work GitHub token stored only on the device
PermissionWhat the user allowsReads allowed; comments require approval
DeviceThe Desktop / Runner that executesThe selected online work computer

Releases and capabilities are author declarations; permissions are user grants. Declaring a tool does not authorize its use. Local providers without external accounts still need a real empty profile saved natively; never invent an account, connection or configuration version.

A digest is a SHA-256 content checksum. A revision tracks state changes. A device generation rejects requests from old connections. A receipt records which operation the device completed. These checks are not additional categories of user permission.

Name, Identity, and Icon

Authors declare presentation in plugin.json. Import reads it from the project directory or package.tar.gz; users do not enter an identity or name, or upload a separate icon in the installation form.

FieldExamplePurpose
namecom.liyanlabs.team-feishuStable identity, retained across updates
extensions["com.liyanlabs"].displayNameTeam FeishuName in lists, details, and setup
extensions["com.liyanlabs"].iconassets/icon.pngPublic presentation image inside the package

Names and icons belong to a release. An omitted display name shows the identity; an omitted icon uses the builtin brand or generic mark. Increment the version and repack after changing them. See Quickstart for image and path limits.

Capability Types

TypeAuthor suppliesCurrent limitation
skillDeclared skills/<key>/SKILL.md with setup / usage purposesDiscovered and read under installation permissions after confirmation; the new CLI template includes both
local_providerTools served by a local processPackage-relative stdio, tool catalogs, and configuration run through the common host
mcpAn MCP server declarationGeneral plugin MCP execution in chat is not connected
inbound_transportAn incoming-message adapterDevice routing, authentication, and deduplication required
channelA two-way external conversation integrationCurrent Feishu/GitHub-specific contracts
agent_runtimeA local agent execution adapterLimited to builtin adapters
client_moduleclientModules, Web/native factories and Capsule viewsDirect installation-graph loading with declared dependencies; business queries execute on the selected Runner

Local providers have no language allowlist, but must implement private bootstrap, stdio MCP initialization, complete discovery and calls. Go is the supplied template. Bare Python/Node.js scripts have no automatic interpreter/dependency packaging; deliver a directly executable artifact. Names, input schemas and read-only classifications must match declarations. Provider labels may repeat across installations, but must be unique within a package.

Plugin chat currently uses the local-provider connector. A root mcp.json HTTP declaration can be parsed, but this does not establish working remote MCP calls. Channels support existing Feishu/GitHub contracts; External runtime declarations retain builtin Claude Agent, OpenClaw and Hermes adapters, but chat takeover is not connected. Codex exposes ordinary asynchronous coding tools through a local provider. New platforms still require host implementation.

Science-data ships its provider and Web/native Capsule entries as one plugin. UI executes directly in the client JavaScript realm, without an isolation sandbox. apply(ctx, config) registers views and shared resources; business calls use only the installation's authorized read-only tools. See plugins/science-data/client/.

OpenSDL also ships as one complete plugin: its native runtime, official icon, Simulation, Laboratory devices and Experiment workflow Capsule views, with separate Web/Desktop and native mobile entries. The closed nativeRuntime: "opensdl/2" declaration retains its dedicated CLI/gRPC adapter; it does not fabricate a stdio provider or open arbitrary runtime protocols to third-party authors. General third-party tools use the ordinary local-provider contract. UI loads only for a confirmed, enabled, authorized installation on its selected online device. Without it, no Capsule view registers, polls devices or acquires scene assets. General computers/sandboxes management remains in the host.

Modules read declared resources through ctx.files.read, using 256 KiB ranges and a complete digest check. Each module allows at most 128 files, 8 MiB per file and 32 MiB total. OpenSDL configuration, runtime, device and camera calls use its exact installation's closed interface; writes follow permissions and host confirmation. See plugins/opensdl/README.md for build and acceptance.

Third parties deliver a target-matched directory or package.tar.gz. Import registers a private release; installation, confirmation, configuration and a real call remain separate steps. First-party downloadable runtimes are build-pinned and acquired on demand, rather than preinstalled in Desktop. Public marketplaces, self-service remote publication and automatic device migration are unavailable and are not local-development prerequisites.

Inspect Tools Provided to AI

Open a plugin's details on Web, Desktop, or mobile and select Tools provided to AI → View tool list to expand or collapse the tools declared by that release. The badge counts individual tools, rather than provider processes or capabilities; one provider can supply several tools.

Each entry shows its original name, purpose, and either “Declared read-only” or “May make changes.” The unchanged CLI template, for example, declares plugin.ping. These fields come from the author's toolCatalog; a read-only declaration does not replace user permission or a real invocation check.

Published declarations can be previewed before installation and while the selected device is offline. Opening the list reads release metadata without starting a provider, contacting Runner, or granting permissions. Actual AI calls still require an enabled installation, completed configuration, the bound online device, and current permission.

Details load on demand and reuse the account-and-release query cache. A failed load offers Retry. An undeclared catalog shows “Count not declared” and an explanation; it must not be treated as one tool or zero tools. This preview is not a live list of tools authorized in the current conversation.

First-party Plugins

PluginPurposeLocal configuration
com.liyanlabs.codexAsynchronous coding tools: start, status, cancelOn-demand pinned CLI and an explicitly authorized profile
com.liyanlabs.claudeLocal agent runtimeOn-demand runtime and claude-code profile
com.liyanlabs.openclawExternal agent serviceopenclaw profile
com.liyanlabs.hermesExternal agent servicehermes profile
com.liyanlabs.zoteroLocal reference serviceLocal Zotero API
com.liyanlabs.feishuFeishu tools and messagesDesktop registration or existing app configuration
com.liyanlabs.githubGitHub tools and webhookDevice-local token
com.liyanlabs.science-dataScientific queries, structure images and Capsule UISaved empty device profile and permission review
com.liyanlabs.opensdlSimulation, laboratory devices, cameras and Capsule UIConfigure and start the native runtime on its bound device

The catalog comes from service/pkg/core/plugin/builtin/catalog.json; OpenSDL has its release definition in service/pkg/core/plugin/packageartifact/opensdl.json. Downloadable first-party capabilities share the desktop/scripts/plugin-release-registry.mjs build path. Catalog visibility does not establish installation or device readiness. The selected Runner acquires the pinned Codex CLI and helpers on demand; the user explicitly authorizes its login directory. OpenClaw, Hermes and Zotero use existing services. Catalog installation and local package import share the same device authorization and execution boundary.

Install and Run

  1. Select an online Desktop and release. Desktop uses its own Runner; Web / Mobile select an online Desktop.
  2. Install. Runner verifies local files, the service saves its receipt, then confirms enablement.
  3. Save a real device profile for local providers, including empty configurations, and review permissions. A packaged setup Skill guides AI assistance; the user completes native confirmation. Initial install retains enable intent; choosing Later does not disable it.
  4. Check configuration completion and live device/provider health.
  5. Invoke. LiyanLabs rechecks version, permissions, and device status before the bound Runner executes.

Enabled means the package has execution permission. Setup complete means required configuration and permissions are saved. Healthy means the device or provider is available now. Check each separately. Update and repair require re-enabling.

An offline selected device makes the capability unavailable. There is no automatic device switch, server execution, or queue waiting for reconnection. See development and debugging for recovery.

Source Basis

Implementation checked on 2026-10-17, including OpenSDL 0.5.0's installed native runtime and client modules. This chapter describes current source contracts rather than availability in older installers; Quickstart checks CLI commands and generated template files first. The OpenSDL package pins its upstream source in service/pkg/core/plugin/packageartifact/opensdl.json.

  • Author contracts and CLI: runner/crates/liyanlabs-plugin/, runner/crates/liyanlabs-cli/src/plugin.rs.
  • Installation and model tools: service/pkg/core/plugin/packagecommand/, service/pkg/worker/wire_toolprep_plugin.go, service/pkg/worker/chatdriver/pluginsurface/.
  • Tool previews: service/pkg/web/views/plugins/projection.go, frontend/shared/src/hooks/usePluginToolDetails.ts, Web's PluginToolsCard.tsx, and mobile's PluginToolsNative.tsx.
  • Configuration and processes: desktop/electron/src/plugins/device/, runner/crates/liyanlabs-runner/src/plugins/provider/.
  • Capsule: service/pkg/core/plugin/clientmodule/, frontend/shared/src/core/pluginClientModules/.
  • First-party releases: desktop/scripts/plugin-release-registry.mjs, .github/workflows/plugins.yaml. See the complete source map.