AgentKit Studio
生态与插件

npm 包

我们发布到 npm 的五个包、各自的安装命令、engines 要求、完整性校验,以及装完怎么验证。

Studio 的主分发形态是桌面安装包,npm 包是「装进已有 DSH 环境」的路径。 五个包分两类: 产品插件本体一个,独立 Harness 三个,专家目录一个。

五个包

包版本作用源码
@kingsoftcloud/agentkit-studio0.0.16产品插件本体(DSH plugin)package.json:2-3
@kingsoftcloud/agentkit-harness-core0.0.25独立 Harness 执行内核package.json:133
@kingsoftcloud/agentkit-harness-node0.0.25Node 适配层package.json:134
@kingsoftcloud/agentkit-harness-ui0.0.25Harness 任务 UIpackage.json:135
@kingsoftcloud/agentkit-expert-catalog0.0.1专家模板目录packages/expert-catalog/package.json:2-3

三个 Harness 包是依赖,不是独立安装项

agentkit-harness-* 由 agentkit-studio 的 dependencies 声明(package.json:133-135), 装 Studio 时会一起装上。只有在你需要锁定版本、或在独立仓库里做 Harness 开发时才单独安装。

安装

在 智能体面板 → 插件 → 插件市场 里找到条目点安装,或在 Host 侧手动指定 spec:

AGENTKIT_DSH_HOME=/tmp/isolated-dsh pnpm verify-dsh-plugin-market --execute --all

--execute 会真实写入 profile。必须设置隔离的 AGENTKIT_DSH_HOME 或 DSH_HOME,否则脚本拒绝执行。 源码:scripts/verify-dsh-plugin-market.mjs:21-29。

pnpm add @kingsoftcloud/agentkit-studio@0.0.16

包是 private: false + publishConfig.access: public,走公共 npm registry (package.json:4,160-163)。

直接装安装包即可,插件已内置。macOS 只发 Apple Silicon,Windows 为 NSIS 安装器。 见版本兼容表。

engines 与 peer 要求

声明值位置
enginesnode >=24.9.0、dsh 0.2.2-rc.1package.json:86-89
peerDependencies@deepseek-ai/cordis ^4.1.0package.json:127-129
packageManager / licensepnpm@10.33.2 / Apache-2.0package.json:6,172

专家目录的 engines 与主包不同

@kingsoftcloud/agentkit-expert-catalog 声明 node: "^22.23.4 || >=24.22.1" (packages/expert-catalog/package.json:7),比主包的 >=24.9.0 更严格。 用它自己的 peer @deepseek-ai/cordis ^4.0.4 也比主包低一个次版本。

包内容允许清单

files 决定哪些文件进 npm 包(package.json:25-45)。理解它才能解释「为什么装了却缺东西」:

类别内容
源码src、packages/expert-catalog/src
构建产物dist(含 dist/client.js,由 prepack 生成)
清单与契约studio.plugin.json、dsh-pin.json、cordis.patch.yml
资源与文档assets、third-party/ZCode-LICENSE、THIRD_PARTY_NOTICES.md、README.md、CHANGELOG.md
运维脚本scripts/ 下 6 个:start-agent-bundle、verify-agent-manifest、start-agent-manifest、native-package-pins.json、native-package-integrity、verify-native-dependencies

dist/ 在 .gitignore 里但必须在 files 里——否则装完的包没有浏览器产物。 prepack 会先跑 verify-native-dependencies.mjs && build-client.mjs && build-mcp-client.mjs(package.json:56)。

在 Host 里怎么挂载

包通过两份清单接入 Host,缺一不可:

文件作用关键字段
studio.plugin.json声明身份、Host 基线、能力与贡献id: agentkit-studio、requiredHostApi: dsh-native/0.2.2-rc.1、requiredDsh: 0.2.2-rc.1、requiredHostContract: 1、4 个 capabilities、3 个 contributes
cordis.patch.yml在 DSH 组合图上插入本插件末尾 insert: - id: agentkit-studio, name: '@kingsoftcloud/agentkit-studio'

package.json 里另外三块告诉 DSH 前端怎么加载:dsh.bundle.patch 指向 ./cordis.patch.yml(:123-125)、 dsh.client.inject 声明 13 个 @deepseek-ai/dsh-* 包(:92-105)、dsh.client.external 外部化 14 个依赖(:107-121)。

源码:studio.plugin.json:1-18、cordis.patch.yml:58-60。

完整性校验

三个 Harness 包带逐文件 SHA-256 摘要,不止顶层 integrity:

{
  "schemaVersion": "agentkit.native-registry-pins/v2",
  "packages": {
    "@kingsoftcloud/agentkit-harness-core": {
      "version": "0.0.25",
      "integrity": "sha512-HGoNIYgN4gRo8M3RUXzEFRGf+Atpg/rYFdI4+WFfcwZhAbQCEc0D2MYtmeeE2nOJsFs5yLZKtWWz+edQYThxQw==",
      "files": { "dist/capability-profile.mjs": "d9c394b03a34d0032d829e3f13f58d87f5132db5a3a02bdbc2281c4af9a2f5fc" }
    }
  }
}

结构:schemaVersion + packages(3 个包)+ dependencyPackages(传递依赖)。 每个包有 version、integrity(sha512)与 files(逐文件 sha256)。 源码:scripts/native-package-pins.json:1-3。

# 校验已安装的依赖与摘要一致
pnpm build:harness        # = node scripts/verify-native-dependencies.mjs

摘要不一致说明包被替换或版本漂移——不要绕过,重新安装。

装完怎么验证

node -e "console.log(require('@kingsoftcloud/agentkit-studio/package.json').version)"  # 1. 清单可解析
pnpm verify-dsh-plugin-market --execute --all   # 2. Host 兼容 + 三个精选插件的能力探针
pnpm verify-studio-plugin-lifecycle             # 3. 安装/启用/停用/更新/卸载五个动作
make check && make release-check                # 4. 全量门禁
步骤验证什么源码
1包版本号与预期一致package.json:3
2启动真实 DSH Host、加载 Studio 适配器,对三个精选插件逐个跑 expectedEntries + service 探针scripts/verify-dsh-plugin-market.mjs:15-40
3五个插件生命周期动作在真实 Host 上生效package.json:61
4DSH pin、Node 版本、契约类型、可移植性与完整测试package.json:49

个人助理插件是独立发布的

@kingsoftcloud/agentkit-personal-assistant 不在 Studio 的依赖里,也不是内置能力。

它在 scripts/check-dsh-plugin-purity.mjs:13 里作为禁止依赖出现——这条规则的作用是保证 Studio 回归成通用 DSH 插件,不把个人助理运行时塞回主包。

事实含义
不在 package.json 的 dependencies装 Studio 不会带上它
出现在纯度门禁的 forbidden 列表任何引入它的 PR 都会失败
需要单独安装从它自己的发布渠道装,且要自己跟随 DSH 基线

源码:scripts/check-dsh-plugin-purity.mjs:9-17。

发布流程

npm 包由 GitHub Actions 用 Trusted Publishing(OIDC) 发布,仓库里不存 token:

步骤内容
触发 / Runnerrelease: published 或手动 workflow_dispatch;ubuntu-24.04、Node 22、pnpm 10.33.2
前置 / 构建pnpm install --frozen-lockfile → pnpm test → npm run prepack
幂等版本已存在则跳过退出
发布用 GitHub OIDC token 换短期 npm token,pnpm publish --access public --no-git-checks --ignore-scripts

源码:.github/workflows/publish-npm.yml:1-65。

常见失败

症状原因处理
EBADENGINE / 启动即退出Node 低于 24.9.0升级 Node,见版本兼容表
STUDIO_HOST_INCOMPATIBLEDSH 不是 0.2.2-rc.1精确对齐 DSH 版本
装完没有界面 / 插件加载失败dist/client.js 缺失,或 cordis.patch.yml 未生效确认 files 含 dist、dsh.bundle.patch 指向该文件,重装触发 prepack
摘要校验失败包被替换或版本漂移重新安装,不要改 native-package-pins.json 绕过
Cannot find module '@deepseek-ai/cordis'peer 未满足装 ^4.1.0(专家目录为 ^4.0.4)
个人助理功能缺失它是独立包单独安装,见上一节

相关

插件清单字段逐项说明见 DSH 插件作者指南,市场里的精选插件见插件市场,Host 版本协商见 Host 兼容性。

本页导航