#Plugin Development

SciLaxy plugins connect an immutable capability declaration to an explicitly selected Desktop or Runner. The server is the control plane; executable code, operational credentials, provider processes, tool calls, and plugin-accessed local files remain on that device.

This section documents the current implementation for developers extending the catalog, building local providers, operating the runtime, or diagnosing a connection.

#Mental Model

A usable plugin is not a single database row or binary. It is the intersection of six authorities:

flowchart LR
  Catalog[Plugin release] --> Install[User installation]
  Install --> Connection[Provider connection]
  Install --> Permission[Permission policy]
  Connection --> Device[Selected Desktop / Runner]
  Device --> Runtime[Local runtime or provider]
  Permission --> Call[Authorized call]
  Runtime --> Call

The server stores enough evidence to decide and audit an invocation. It does not receive a Feishu App Secret, GitHub token, local executable path, or a copy of the provider process.

The current model is account-scoped. Older migrations and historical documents may mention plugin_session_snapshot, plugin_session_capability, or agent_plugin_binding; migration 00093 removed them. Runtime sessions and external effects now pin the direct authority they actually use.

#Capabilities

A release declares one or more closed capability types:

Each capability has a stable key, strict configuration JSON, configuration digest, declared permissions, and deterministic ordering. Unknown fields or undeclared capability types are rejected rather than ignored.

#Builtin Plugins

The builtin catalog currently contains:

service/pkg/core/plugin/builtin/catalog.json is the single product source for this catalog. Deployment origins, release channels, signing keys, and environment secrets do not belong in plugin executables.

#Lifecycle

The normal path from catalog entry to a callable plugin is:

1. Install an immutable release. This creates an installation, not a provider login.
2. Select a device with a valid enrollment and lease.
3. Configure a connection. Device-local profiles use a signed device action and an isolated Desktop credential window.
4. Approve permissions for the release's declared capabilities.
5. Enable the installation. A Worker recomputes readiness before committing the state.
6. Invoke a tool, Channel, or runtime. The request pins current revisions and is signed for one device generation.
7. Audit and reconcile external effects without blindly replaying ambiguous writes.

Installation lifecycle commands are asynchronous. The API reserves an idempotent plugin_installation_operation, queues plugin:lifecycle:execute, and the Worker moves it through pending, running, and a terminal state.

#Understanding Enable

Enable is the final readiness gate; it is not a setup wizard. A disabled installation can still be missing its connection, permission policy, device lease, runtime, or trusted release.

The Worker reports requirements_unmet when any readiness requirement is absent. The health projection carries the actionable blocker, such as:

• connection_required
• permission_required
• device_offline
• runtime_incompatible
• release_revoked
• policy_changed

For a new Feishu installation, owning an App ID and App Secret is not enough. The developer must first create a named profile on the selected Desktop, complete the secure credential prompt so the connection becomes ready, approve the requested permissions, and only then enable the installation.

The current UI may allow Enable to be submitted before these steps are complete. In that case the asynchronous rejection is expected backend behavior, while the missing preflight guidance is a product UX issue—not a lease, signing, or credential-validation result.

#Continue Reading

• Data model explains all 23 current plugin tables.
• Runtime and security covers the server/device boundary, trust chain, credential storage, effects, Channel delivery, and webhook relay.
• Development and debugging provides routes, local setup, readiness errors, SQL diagnostics, and an extension checklist.