AgentKit Studio
运行时与部署

Star Harness

Star Harness 作为 npm 插件的执行模型、安装升级与工作区绑定的完整生命周期,以及它为什么必须先装好才能被选中。

Star Harness(harness)把整个 turn 交给 Harness 原生内核,DSH 不再自己跑模型与工具循环。 它只有一种发布形态:从 npm 安装 @kingsoftcloud/agentkit-harness-node。没有独立进程,也没有需要你手写的引擎地址——你在插件页装好、启用、绑定工作区之后,Agent 表单才会出现 Star Harness 这个选项。

执行模型

环节归属依据
模型 / 工具循环Harness 原生内核owner: 'ksadk-harness'、execution: 'native-kernel'
Studio 与它的契约agentkit.native-dsh-turn/v1contract
事件源native-run-storeeventOwner
流式native-model-portstreamOwner
能力集native-run、durable-receipts、tool-approval、cancel、resume、child-taskscapabilities

依据:src/runtime-contract.mjs:25-29。

DSH 侧提供整轮端口(宿主契约 dsh.external-turn-host/v1),每轮由它把控制权交给 Harness 引擎(dsh.external-turn/v1)。Harness 包在接管前会校验宿主具备 claim、pending、resume 三个方法(@kingsoftcloud/agentkit-harness-node 的 native/dsh-turn-ownership.mjs:47-52)。

不能走普通流式接缝

harness 在本地模式下经过 DSH 的流式适配器会直接抛 STUDIO_NATIVE_TURN_REQUIRED(「Native Harness requires the whole-turn execution port.」)。它必须由整轮端口承接,不能被当成「一条普通的模型流」(src/providers/dsh-runtime.mjs:591)。

依赖方向

Studio 单向依赖 Harness 的 npm 包,版本精确锁定:

包版本用途
@kingsoftcloud/agentkit-harness-core0.0.25规范值、不变量、内核原语
@kingsoftcloud/agentkit-harness-node0.0.25整轮 turn 契约、Run 归属、包完整性校验
@kingsoftcloud/agentkit-harness-ui0.0.25引擎视图适配器

依据:package.json:133-135(三个包都精确锁定,不用 ^ 或 ~)。

Harness 不依赖 Studio。 三个包的 dependencies 里没有任何 @kingsoftcloud/agentkit-studio* 条目——依赖是单向的,所以升级 Harness 不需要 Studio 一起发版。

安装与生命周期

Star Harness 由**插件页里的「Star Harness 管理」**驱动,五个操作对应五个控制端点:

操作端点界面文案
读取状态star-harness/status已安装 <version> / 未安装,附「已启用 / 已停用」
安装 / 升级star-harness/install「安装」「升级」「重新安装」
启停star-harness/enable「启用」「停用」
绑定工作区star-harness/bind「绑定工作区」
解除绑定star-harness/unbind「解除绑定」

依据:src/host/routes/star-harness.mjs:7-11、src/remote/control-client.mjs:469-473、src/client/pages/star-harness.mjs:64-112。

版本规则

规则表现依据
版本格式必须是 x.y.z 三段数字src/host/services/star-harness-release.mjs:14-15
只能升或回退想切到既不是「更新」也不是「上一版」的版本 → STAR_HARNESS_VERSION_UNSUPPORTEDsrc/host/services/star-harness.mjs:186-191
回退有 previousVersion 时出现「回退到 <版本>」按钮src/client/pages/star-harness.mjs:88
出厂校验只接受当前 Studio 已核验的版本,否则 STAR_HARNESS_RELEASE_UNREVIEWEDsrc/host/services/star-harness-release.mjs:22-28
包完整性逐文件核对摘要,依赖解析不得逃出安装目录:32-59
注册表固定 https://registry.npmjs.org:12

为什么版本要校验

Studio 会先确认这个 Harness 版本被当前 Studio 核验过,再安装。换 Harness 版本改的是依赖版本号,不涉及 Studio 源码——但没被核验的版本会明确拒绝,而不是装上再炸。

工作区绑定

一个工作区对应一个模型配置和一份独立的运行状态:

规则表现依据
必须绝对路径非规范绝对路径 → STAR_HARNESS_INVALID_REQUESTsrc/host/services/star-harness.mjs:212-217
不得重叠与已有绑定、Star Harness 状态目录或外部 Harness 路由重叠 → STAR_HARNESS_WORKSPACE_CONFLICT:71-72、:214-215
模型必须可用选择的模型配置必须存在且启用:216-217
模型漂移绑定后模型变了 → STAR_HARNESS_MODEL_CHANGED,需重新绑定:61-64
目录失效工作区被删后显示「目录已失效」,且不再参与路由src/client/pages/star-harness.mjs:97、src/host/services/star-harness.mjs:132

什么时候选它

  • 需要跨进程续跑(resume):三条运行时里只有 Star Harness 具备。
  • 需要子任务(child-tasks)与持久回执(durable-receipts):多角色任务分解依赖这两项。
  • 需要工具审批作为运行时一等能力(tool-approval)。
  • 你已经在用 DeepSeek Harness,希望整轮交给 Harness 内核而不是 DSH 原生循环。

不需要这些时选 DSH Native 更省事(见三运行时对照)。

限制

限制表现依据
必须先装好才能选只有「已安装 + 已启用 + 至少一个工作区」才允许新建 Agentsrc/client/pages/agent-form.mjs:79、src/host/services/star-harness.mjs:162、:174
未安装安装或启用前抛 STAR_HARNESS_NOT_INSTALLEDsrc/host/services/star-harness.mjs:14
未绑定工作区启用时若无可用工作区 → NATIVE_ENGINE_WORKSPACE_UNAVAILABLE:15
忙时不可变更有任务运行或正在变更 → STAR_HARNESS_BUSY:11
一次只允许一个写入者新 worker 必须在旧 worker 停止后接管;切换失败回滚原版本:95-125
版本精确锁定三个包均为 0.0.25,不接受浮动范围package.json:133-135
无独立 persistence 项持久化以 durable-receipts 形态提供,与 DSH 的 persistence 不是同一实现src/runtime-contract.mjs:27

Star Harness 与 DSH Native 的 Run 账本不同

切换运行时不迁移已有的 Run 历史:旧会话仍按原运行时打开。Star Harness 的 Run 由 Harness 账本拥有,DSH Native 的 Run 由 DSH 会话拥有。

失败形态

错误码触发条件你能做什么
STAR_HARNESS_NOT_INSTALLED尚未安装就启用或绑定先安装一个已核验的版本
STAR_HARNESS_RELEASE_UNREVIEWED指定版本未被当前 Studio 核验升级 Studio,或改成已核验版本
STAR_HARNESS_VERSION_UNSUPPORTED目标版本既不是新版也不是上一版选择更新版本,或回退到上一版
STAR_HARNESS_WORKSPACE_CONFLICT工作区与已有绑定或状态目录重叠换一个不重叠的绝对路径
STAR_HARNESS_MODEL_CHANGED绑定的模型配置已变化重新绑定该工作区
STAR_HARNESS_BUSY有任务在跑或正在变更等任务结束再改版本或绑定
STAR_HARNESS_CONFIG_INVALID本地设置文件无法读取检查 Star Harness 状态目录的 settings.json
NATIVE_ENGINE_WORKSPACE_UNAVAILABLE该工作区未绑定或未启用先绑定并启用工作区
STUDIO_NATIVE_TURN_REQUIREDharness 走进了普通流式接缝检查 Host 是否提供整轮端口;通常是 DSH 基线不匹配
STAR_HARNESS_UNSUPPORTED该部署由管理员托管,不提供本机管理联系管理员

资源不可用时的降级与重试见降级与重试。

源码依据

结论位置
能力矩阵与归属src/runtime-contract.mjs:25-29
整轮端口要求src/providers/dsh-runtime.mjs:591
宿主能力校验agentkit-harness-node 的 native/dsh-turn-ownership.mjs:47-52
管理服务与状态机src/host/services/star-harness.mjs:21-251
版本核验与包完整性src/host/services/star-harness-release.mjs:14-61
控制端点src/host/routes/star-harness.mjs:7-11
客户端交互src/client/pages/star-harness.mjs:64-112
可创建门控src/client/pages/agent-form.mjs:61-79
三个包精确锁定package.json:133-135

本页导航