AgentKit Studio
Ecosystem and plugins

DSH plugin authoring

Build a plugin package a DSH host can load and the Studio market can discover — manifest fields, capability declarations, publishing, and self-checks.

A DSH plugin is an npm package plus a manifest. The manifest declares what it needs from the host; the package provides the implementation. DSH owns loading, dependency resolution, and lifecycle. Studio only makes the plugin discoverable.

Minimum shape of a plugin package

You provideNotesStudio's own example
Package nameMust pass PACKAGE_SPEC; scopes allowed@kingsoftcloud/agentkit-studio
Versionsemver0.0.16
exports entriesAt least one, pointing at an ESM module14 entries, see package.json#exports
Manifest fileWhat DSH uses to admit the pluginstudio.plugin.json
keywordsWhat the market searchesdsh-plugin

The package name is not free-form

Both id and installSpec must match ^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:@[A-Za-z0-9.^~<>=*+-]+)?$ from the npm package-name rules of the DSH index format. Uppercase or unusual symbols make the row get silently dropped — the market will not error, you simply will not appear.

Manifest fields

{
  "id": "agentkit-studio",
  "version": "0.0.16",
  "requiredHostApi": "dsh-native/0.2.2-rc.1",
  "requiredDsh": "0.2.2-rc.1",
  "requiredHostContract": 1,
  "capabilities": [
    "studio.agent.catalog",
    "studio.runtime.capabilities",
    "studio.session.adapter",
    "studio.workspace.dock"
  ],
  "contributes": ["route", "resource", "command"]
}
FieldTypeRequiredPurposeWhen unmet
idstring✅Plugin identity, globally uniqueLoad fails
versionsemver✅Must equal package.jsonPackaging gate fails
requiredHostApistring✅Host API namespace you needLoad refused
requiredDshstring✅DSH version — exact equalitySTUDIO_HOST_INCOMPATIBLE
requiredHostContractnumber✅Compatibility contract versionSame
capabilitiesstring[]✅Capability names you provideDownstream probes fail
contributesstring[]✅Extension point kinds you contributeExtension does not mount

requiredDsh is compared for exact equality, not >=. Writing 0.2.2 does not authorize 0.2.2-rc.1. Source: src/host/compatibility.mjs:25.

The four capabilities and three contributions

CapabilityMeaningProbe
studio.agent.catalogExposes an agent catalogagentPresets.register / pluginsFor
studio.runtime.capabilitiesExposes runtime capability queriesSee host compatibility
studio.session.adapterExposes session adaptationsessionController.create and five more
studio.workspace.dockExposes workspace dockingChecked at mount time
ContributionWhat you registerHow the host uses it
routeControl protocol routesDispatched over the /agentkit channel
resourceResource kindsEnters the resource catalog and binding pickers
commandCommandsEnters the Host command table

Source: studio.plugin.json:7-17.

Module entry

// src/index.mjs
export const name = 'agentkit-studio';
export const inject = ['connection', 'webServer', 'credentials'];

export async function apply(ctx) {
  // Mount Host services, register routes, inject documents here.
}

inject declares the host services you depend on. Do not call ctx.get() before apply — Cordis only exposes a service after the plugin providing it is active. Resolve services at the moment you actually use them. Source: src/index.mjs:16-43.

Making the market discover you

ChannelMechanismSource
Bundled community indexPackage keywords contains dsh-plugin and it ranks into the shipped index (top 80 by downloads)assets/plugin-market/index.json
Your own index sourcePublish a format: 1 static JSON and add its URL on the Discover pagesrc/plugin-market.mjs
Default-enabled bundlesStudio's first-party default listsrc/host/default-bundles.mjs

Only first-party entries in the built-in catalog may declare expectedEntries / service / readinessNote. Third-party plugins are discovered via npm or GitHub, and the market reports "Host loaded this plugin; Studio has no capability probe for it." Source: src/host/default-bundles.mjs, src/plugin-market.mjs.

Pre-publish checklist

Version consistency

node -p "require('./package.json').version"
node -p "require('./studio.plugin.json').version"

Both must match. make release-check enforces this.

Exports resolve

node -e "for (const [k,v] of Object.entries(require('./package.json').exports)) console.log(k, '->', v)"

Every relative entry must actually exist — DSH resolves each one.

Manifest loads

node -e "console.log(require('./studio.plugin.json'))"

The manifest must be valid JSON, and requiredDsh must equal the Host version you actually verified against.

Package contents are clean

make public-gate

public-gate runs the source audit, secret scan, patch format, and package content checks.

Plugin boundary: depend only on public contracts

Studio defines itself as a generic DSH product plugin with a deliberately small boundary. The same applies when you write a plugin:

RuleMeaning
Import public contracts onlyDepend on public DSH / AgentEngine contracts and your own product code; never import another product's private modules
Cross-plugin traffic goes through registration and admissionCommunicate via DSH registration, connection admission and versioned wire contracts, not private service names
Cloud access goes through agentkitHostCloudWhen you need host-side cloud configuration and credentials, take only this narrow capability; it does not hand out credentials, and consumers build their own adapters
Runtime images advertise opaque labelsAn image declares capability labels; each plugin interprets the ones it owns after checking DSH kernel compatibility
// Host-provided: read-only configuration plus client factories, no credential values
const cloud = await ctx.get('agentkitHostCloud');
const client = await cloud.getClient();      // AgentEngine client

studio.agent.catalog, studio.runtime.capabilities, studio.session.adapter and studio.workspace.dock are capabilities Studio declares as a plugin; agentkitHostCloud is the service Studio provides as a host to other plugins. The directions are opposite — do not mix them up.

The repository gates this with scripts/check-dsh-plugin-purity.mjs, which scans src/, tests/, scripts/ and the packaging config and fails on product-specific imports, service names or package references (src/host/bootstrap.mjs:193-200, scripts/check-dsh-plugin-purity.mjs:8-23).

Readiness states

After install, the market reports one of six states:

StateMeaningWhat to do
not-installedNot installedClick install
disabledInstalled but not enabledClick enable
loadedHost loaded it; no capability probe existsNothing (normal for third-party plugins)
readyCapability rows and service probes all passNothing
failedLoad or probe failureRead the method name in note
not-configuredNo capability verification list configuredNothing

Source: src/studio-plugins.mjs:96-115.

Common errors

Error codeCauseFix
STUDIO_HOST_INCOMPATIBLErequiredDsh differs from the running DSHUpgrade the Host or edit the manifest
DSH_PLUGIN_NOT_FOUNDPackage name does not resolveCheck the name and registry
DSH_PLUGIN_NOT_USABLEInstalled but cannot loadRead the load error in the Host log
DSH_PLUGIN_INSPECTION_REFUSEDInspection snapshot refusedShrink the snapshot, see CHANGELOG 0.0.14
DSH_PLUGIN_OPERATION_FAILEDChange did not take effectRead details.error.diagnostic
SERVICE_UNAVAILABLEHost service missingConfirm the Host meets the manifest requirement

Remote index fields and examples live in plugin market, negotiation details in host compatibility, and every error code in the error reference.

On this page