DSH 插件作者指南
写一个能被 DSH 宿主加载、被 Studio 插件市场发现的插件包:清单字段、能力声明、发布与自检。
一个 DSH 插件 = 一个 npm 包 + 一份清单。 清单声明它要求宿主提供什么,包本身提供实现。 DSH 侧负责加载、依赖解析与生命周期;Studio 侧只负责让它在市场里可被发现。
插件包的最小形状
| 你要提供 | 说明 | Studio 自己的例子 |
|---|---|---|
| 包名 | 必须能通过 PACKAGE_SPEC 校验,支持 scope | @kingsoftcloud/agentkit-studio |
| 版本 | semver | 0.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"]
}| 字段 | 类型 | 必填 | 作用 | 不满足时 |
|---|---|---|---|---|
id | string | ✅ | 插件身份,全局唯一 | 加载失败 |
version | semver | ✅ | 与 package.json 必须一致 | 打包门禁失败 |
requiredHostApi | string | ✅ | 要求的 Host API 命名空间 | 拒绝加载 |
requiredDsh | string | ✅ | 要求的 DSH 版本,必须精确相等 | STUDIO_HOST_INCOMPATIBLE |
requiredHostContract | number | ✅ | 兼容契约版本号 | 同上 |
capabilities | string[] | ✅ | 你对外提供的能力名 | 下游探针失败 |
contributes | string[] | ✅ | 你向宿主贡献的扩展点类型 | 扩展点不挂载 |
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,在「发现」页添加该 URL | src/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 版本。
插件边界:只依赖公开契约
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 | 已安装但未启用 | 点启用 |
loaded | Host 已加载,但没有能力探针 | 无(第三方插件的正常状态) |
ready | 能力行与服务探针全部通过 | 无 |
failed | 加载失败或探针失败 | 看 note 里的具体方法名 |
not-configured | 未配置能力验证清单 | 无 |
源码:src/host/default-bundles.mjs、src/plugin-market.mjs。
常见错误
| 错误码 | 原因 | 处理 |
|---|---|---|
STUDIO_HOST_INCOMPATIBLE | requiredDsh 与运行中的 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 版本 ≥ 清单要求 |