AgentKit Studio
生态与插件

Host 兼容性

Studio 如何判断当前 DSH 宿主能否执行能力:5 个能力探针、3 个功能闸门、基线比较与被拒绝时的错误码。

Studio 在执行任何原生能力之前先问一次宿主「你是谁」。 问不到就拒绝,不猜、不降级。

兼容性判定有三个维度,全部通过才放行:

维度比什么变量
基线运行中的 DSH 版本是否精确等于清单声明requiredDsh
契约兼容契约版本号是否相等requiredHostContract
能力宿主服务上是否存在约定的方法capabilities

源码:src/host/compatibility.mjs:15-33。

清单声明

{
  "requiredDsh": "0.2.2-rc.1",
  "requiredHostContract": 1,
  "capabilities": [
    "studio.agent.catalog",
    "studio.runtime.capabilities",
    "studio.session.adapter",
    "studio.workspace.dock"
  ]
}

基线来自 studio.plugin.json,实际版本来自 DSH 的公开启动 API getDshRuntimeVersion()。 源码:src/host/compatibility.mjs:53-71。

显示版本不能授权执行

AGENTKIT_STUDIO_DSH_VERSION 只影响界面展示。把它改成期望值不会让能力通过—— 真实版本只能从运行中的 DSH 包读取。读不到就按不兼容处理。 源码:src/host/compatibility.mjs:55-62。

五个能力探针

能力 id探测什么通过条件
preset-compositionAgent 预设注册表agentPresets.register 与 agentPresets.pluginsFor 都是函数
agent-loop-origin请求来源判定isAgentLoopRequest 是函数
session-controller会话控制器create/selectModel/resolveAgent/prompt/page/projections 六个方法齐全
automation-policy自动化策略闸门agents.withoutInitiator + permissionPresets.set + approval.setPolicy
request-fingerprint请求指纹promptFingerprintVersion === 1 且 prompt 是函数

每个探针返回 1(通过)或 0(缺失)。 源码:src/host/compatibility.mjs:18-24。

探针不创建会话

inspect() 只读服务形状,不调用 create、不发请求、不写磁盘。 重复调用是安全的——而且必须重复调用:上一代 Host 或注册表的检查结果不能替新宿主背书。 源码:src/host/compatibility.mjs:12-14。

三个功能闸门

功能需要的能力用在哪
agent-presetspreset-composition + agent-loop-origin选择 Agent 预设、把预设组合进会话
automation上面两个 + session-controller + automation-policy自动化与调度
frozen-runtime上面四个 + request-fingerprint冻结运行时的请求预算与重放

功能是能力的累积:frozen-runtime 需要全部五个。 源码:src/host/compatibility.mjs:5-9。

判定结果

const report = hostCompatibility.inspect();
// {
//   baseline: { required: '0.2.2-rc.1', actual: '0.2.2-rc.1', compatible: true },
//   contract: { required: 1, actual: 1, compatible: true },
//   capabilities: { 'preset-composition': 1, 'agent-loop-origin': 1, ... },
//   features: {
//     'agent-presets': { available: true, requiredCapabilities: {...}, missingCapabilities: [] },
//     ...
//   }
// }
字段含义
baseline.compatible字符串相等比较的结果;actual 为 null 即不兼容
contract.compatible契约号相等
features[x].available基线 且 契约 且 无缺失能力
features[x].missingCapabilities缺哪些能力 id

源码:src/host/compatibility.mjs:25-32。

被拒绝时

任何功能闸门失败都抛同一个错误:

{
  "code": "STUDIO_HOST_INCOMPATIBLE",
  "status": 503,
  "message": "Studio frozen-runtime is unavailable: request-fingerprint. Install the compatible Studio Host.",
  "details": {
    "status": 503,
    "feature": "frozen-runtime",
    "baseline": { "required": "0.2.2-rc.1", "actual": "0.2.1-rc.2", "compatible": false },
    "contract": { "required": 1, "actual": 1, "compatible": true },
    "missingCapabilities": []
  }
}

三条拒绝原因

message 里出现的片段含义处理
DSH baseline版本不相等把 DSH 升到 requiredDsh 声明的版本
compatibility contract契约号不相等升级 Studio 插件到匹配契约号的版本
逗号分隔的能力 id 列表服务方法缺失宿主版本对但服务没挂载——检查插件是否全部加载

源码:src/host/compatibility.mjs:34-43。

从外部查询

入口说明
host/compatibility operation返回当前检查结果,需要认证
window.__AGENTKIT_STUDIO__.hostCompatibility浏览器文档里注入的同一份结果
hostCompatibility.inspect()Host 进程内直接调用

两个外部入口都不暴露凭证、文件系统路径或会话内容。 源码:src/index.mjs:31-45、docs/host-compatibility.md。

启动时 vs 执行时

时机行为
Host 启动计算一次兼容性,注入到浏览器文档
原生执行前每个功能各自再查一次(require(feature));Host 可能重启服务或换注册表,启动时的结论会过期
未知功能名抛 TypeError: Unknown Studio Host feature: <name>

源码:src/host/compatibility.mjs:34-37。

排查清单

node -p "require('./studio.plugin.json').requiredDsh"   # 清单声明的基线
node -p "require('./dsh-pin.json').version"             # 打包时固定的版本
node -e "import('@deepseek-ai/dsh-app-boot').then(m => console.log(m.getDshRuntimeVersion?.()))"
现象原因处理
前两行不一致打包时用了错误的清单重新对齐 studio.plugin.json 与 dsh-pin.json
第三行输出 undefined运行环境里没有 DSH 启动包所有原生能力都不可用,修复 DSH 安装
missingCapabilities 非空宿主版本对但服务没挂载对照「五个能力探针」表找到缺的方法,检查官方插件是否启用
显示版本正确但检查失败只改了 AGENTKIT_STUDIO_DSH_VERSION显示版本不参与授权,见上方 Callout

相关

DSH 基线与其他版本号见版本兼容表,插件清单字段见 DSH 插件作者指南,全部错误码见错误码参考。

本页导航