AgentKit Studio
发布与迁移

版本兼容表

插件版本 × DSH 基线 × 最低 Node × 支持平台四维对照,以及 macOS 只发布 Apple Silicon 的原因。

先确认三件事再升级:插件版本对得上、DSH 基线精确相等、Node 满足安全补丁。 三者任一不满足都会在启动时被拒绝。

四维对照表

插件版本DSH 基线requiredHostApiHost 契约最低 Node(运行时)macOSWindows浏览器
0.0.16(当前)0.2.2-rc.1dsh-native/0.2.2-rc.11>=24.9.0✅ arm64✅ x64✅
0.0.150.2.2-rc.1dsh-native/0.2.2-rc.11>=24.9.0✅ arm64✅ x64✅
0.0.140.2.2-rc.1dsh-native/0.2.2-rc.11>=24.9.0✅ arm64✅ x64✅
0.0.130.2.2-rc.1dsh-native/0.2.2-rc.11>=24.9.0✅ arm64✅ x64✅
0.0.20.2.0-rc.2dsh-native/0.2.0-rc.2未声明>=22.19.0✅ arm64✅ x64✅

源码:studio.plugin.json:4-6、package.json#engines、dsh-pin.json:9。

为什么 0.0.3–0.0.12 不在表里

Git 只有 v0.0.2、v0.0.13、v0.0.14、v0.0.15、v0.0.16 五个标签。 中间版本的基线无法从源码核对,所以不写——宁可缺,不要猜。 这些版本可以从 版本说明 看到用户可感知的变化。

三个必查项

1. 插件版本

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

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

2. DSH 基线(精确相等)

requiredDsh 是字符串相等比较,不是版本范围:

你的 DSHrequiredDsh结果
0.2.2-rc.10.2.2-rc.1✅ 通过
0.2.20.2.2-rc.1❌ STUDIO_HOST_INCOMPATIBLE
0.2.1-rc.20.2.2-rc.1❌ 同上
读不到0.2.2-rc.1❌ 同上(actual: null)

源码:src/host/compatibility.mjs:25。判定细节见 Host 兼容性。

3. Node 版本

这里有两套不同的门槛,容易混:

门槛值谁在用不满足时
运行时最低版本>=24.9.0package.json#engines、dsh-pin.json#nodeRange安装/启动失败
安全补丁基线22.23.4+ / 24.22.1+ / 26.12.1+scripts/node-version.mjs、make check:node门禁失败
仓库默认版本24.22.1.node-versionnvm/fnm 会切到它

两套门槛都满足才算通过

engines 说 >=24.9.0,但安全基线要求 24.x 至少到 24.22.1。 从源码开发时两个都会检查:>=24.9.0 过不了 make check:node。 安全基线来自 2026 年 10 月的 Node.js 安全版本(Brotli 解码 RCE 与 TLS 主机名校验修复)。 源码:scripts/node-version.mjs:1-14。

支持平台

平台架构安装包状态更新 feed 目标
macOSApple Silicon(arm64).dmg✅ 支持mac-arm64
macOSIntel(x64)—❌ 不支持—
Windowsx64.exe(NSIS)✅ 支持win-x64
浏览器—npm 包✅ 支持—

文档里不要出现 Intel Mac 的安装包文件名。它曾经出现在历史文档里,是错误信息。

为什么 macOS 只发 arm64

原因说明
Feed 目标只有两个RELEASE_FEED_TARGETS = ['mac-arm64', 'win-x64'],没有第三个目标
图标配置仍有三项product.json 的 platforms 还保留了第二个 macOS 架构的图标路径,但那只用于打包输入校验
签名与公证成本每个架构都要独立签名与公证,当前只对 arm64 做验收

源码:src/desktop-release-channels.mjs:49、src/product.json:34-38、scripts/product-config.mjs:50-54。

有图标 ≠ 有安装包

product.json 里能看到第二个 macOS 架构的图标配置,但没有对应的更新 feed。 如果你在发布产物里找不到该架构的 .dmg,那是预期行为。

版本号之间的关系

版本0.0.16 时的值变化频率
插件 semver0.0.16每次发布
DSH 基线0.2.2-rc.1跟随 DSH 升级,低频
Host 契约号1只在能力面变更时递增
桌面版本0.2.2-rc.1.<YYYYMMDD>.<序号>每天可分多次构建

桌面版本继承 DSH 版本,所以它天然带 -rc 后缀——这就是默认通道必须是 nightly 的原因, 见桌面更新通道。

兼容性排查顺序

先看错误码

STUDIO_HOST_INCOMPATIBLE 的 details 里直接给出 baseline、contract、missingCapabilities 三组值。

再看基线

node -e "import('@deepseek-ai/dsh-app-boot').then(m => console.log(m.getDshRuntimeVersion?.()))"

输出必须等于 requiredDsh。undefined 表示 DSH 启动包不在环境里。

然后看契约号

details.contract.required 与 details.contract.actual 必须相等。

最后看能力

details.missingCapabilities 非空说明宿主版本对但服务没挂载——检查所有官方插件是否加载。

相关

本页导航