AgentKit Studio
生态与插件

DSH 插件作者指南

写一个能被 DSH 宿主加载、被 Studio 插件市场发现的插件包:清单字段、能力声明、发布与自检。

一个 DSH 插件 = 一个 npm 包 + 一份清单。 清单声明它要求宿主提供什么,包本身提供实现。 DSH 侧负责加载、依赖解析与生命周期;Studio 侧只负责让它在市场里可被发现。

插件包的最小形状

你要提供说明Studio 自己的例子
包名必须能通过 PACKAGE_SPEC 校验,支持 scope@kingsoftcloud/agentkit-studio
版本semver0.0.16
exports 入口至少一个,指向 ESM 模块14 个入口,见 package.json#exports
清单文件DSH 用来判断能否加载studio.plugin.json
keywords市场靠它检索dsh-plugin

包名不是随便起的

id 与 installSpec 都要匹配 DSH 索引规范的 npm 包名校验 ^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:@[A-Za-z0-9.^~<>=*+-]+)?$。 大小写、下划线以外的符号都会让条目被静默丢弃——市场不会报错,只是看不到你。

清单字段

{
  "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"]
}
字段类型必填作用不满足时
idstring✅插件身份,全局唯一加载失败
versionsemver✅与 package.json 必须一致打包门禁失败
requiredHostApistring✅要求的 Host API 命名空间拒绝加载
requiredDshstring✅要求的 DSH 版本,必须精确相等STUDIO_HOST_INCOMPATIBLE
requiredHostContractnumber✅兼容契约版本号同上
capabilitiesstring[]✅你对外提供的能力名下游探针失败
contributesstring[]✅你向宿主贡献的扩展点类型扩展点不挂载

requiredDsh 是精确相等比较,不是 >=。写 0.2.2 拿不到 0.2.2-rc.1 的授权。 源码:src/host/compatibility.mjs:25。

四个 capability 与三个 contribute

capability含义探针
studio.agent.catalog提供 Agent 目录agentPresets.register / pluginsFor
studio.runtime.capabilities提供运行时能力查询见 Host 兼容性
studio.session.adapter提供会话适配sessionController.create 等 6 个方法
studio.workspace.dock提供工作区停靠挂载时检查
contribute你注册什么宿主怎么用
route控制协议路由通过 /agentkit 通道分发 operation
resource资源种类进入资源目录与绑定选择器
command命令进入 Host 命令表

源码:studio.plugin.json:7-17。

模块入口

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

export async function apply(ctx) {
  // 在这里挂载 Host 服务、注册路由、注入文档
}

inject 声明你依赖的宿主服务。不要在 apply 之前 ctx.get()——Cordis 只在提供该服务的插件激活后才暴露它。 拿到服务要延迟到真正使用的时刻。源码:src/index.mjs:16-43。

让市场能发现你

渠道机制来源
内置社区索引包 keywords 含 dsh-plugin,且进入随包索引(按下载量取前 80 个)assets/plugin-market/index.json
自己的索引源发布一份 format: 1 静态 JSON,在「发现」页添加该 URLsrc/plugin-market.mjs
默认启用Studio 默认启用的 bundle 清单(仅限第一方)src/host/default-bundles.mjs

精选清单只有第一方条目能声明 expectedEntries / service / readinessNote。 第三方插件由索引描述,市场会显示「Host 已加载该插件;Studio 没有它的能力探针」。 源码:src/host/default-bundles.mjs、src/plugin-market.mjs。

发布前自检

版本一致性

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

两者必须相同。make release-check 会校验这一点。

exports 可解析

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

每个相对入口都必须真实存在——DSH 会逐个解析。

清单可加载

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

清单必须是合法 JSON,requiredDsh 必须等于你实际验证过的 Host 版本。

包内容干净

make public-gate

public-gate 会跑源码审计、密钥扫描、补丁格式与包内容检查。

插件边界:只依赖公开契约

Studio 把自己定义成一个通用 DSH 产品插件,边界刻意做小。写插件时同样适用:

规则含义
只 import 公开契约只依赖 DSH / AgentEngine 的公开契约与你自己的产品代码,不 import 别的产品的私有模块
跨插件走注册与准入通过 DSH 注册、连接准入和带版本的 wire 契约通信,不用私有服务名
云访问走 agentkitHostCloud需要宿主侧云配置与凭证时,只拿这个窄能力;它不发放凭证,消费者自己构造适配器
运行时镜像只报不透明标签镜像声明能力标签,插件在核对 DSH 内核兼容后解释自己那部分
// 宿主提供:只读配置 + 客户端工厂,不含凭证值
const cloud = await ctx.get('agentkitHostCloud');
const client = await cloud.getClient();      // AgentEngine 客户端

studio.agent.catalog / studio.runtime.capabilities / studio.session.adapter / studio.workspace.dock 是 Studio 作为插件声明的能力;agentkitHostCloud 是 Studio 作为宿主提供给其他插件的服务。两者方向相反,不要混用。

仓库用 scripts/check-dsh-plugin-purity.mjs 扫描 src/、tests/、scripts/ 与打包配置,发现产品私有 import、服务名或包引用就失败(src/host/bootstrap.mjs:193-200、scripts/check-dsh-plugin-purity.mjs:8-23)。

就绪状态

装好之后,市场会给出六种之一的状态:

状态含义你要做什么
not-installed尚未安装点安装
disabled已安装但未启用点启用
loadedHost 已加载,但没有能力探针无(第三方插件的正常状态)
ready能力行与服务探针全部通过无
failed加载失败或探针失败看 note 里的具体方法名
not-configured未配置能力验证清单无

源码:src/host/default-bundles.mjs、src/plugin-market.mjs。

常见错误

错误码原因处理
STUDIO_HOST_INCOMPATIBLErequiredDsh 与运行中的 DSH 不相等升级 Host 或改清单
DSH_PLUGIN_NOT_FOUND包名解析不到检查包名与 registry
DSH_PLUGIN_NOT_USABLE已安装但无法加载看 Host 日志里的加载错误
DSH_PLUGIN_INSPECTION_REFUSED检查快照被拒绝减小快照体积,见 CHANGELOG 0.0.14
DSH_PLUGIN_OPERATION_FAILED变更未生效读 details.error.diagnostic
SERVICE_UNAVAILABLE宿主服务不存在确认 Host 版本 ≥ 清单要求

相关

索引字段与示例见插件市场,能力协商细节见 Host 兼容性,全部错误码见错误码参考。

本页导航