参考
运行时与实体契约
`agentkit.studio.runtime/v1` 的 3 种运行时、能力矩阵、实体标识与校验错误码。
契约版本
运行时契约只有一个版本常量:agentkit.studio.runtime/v1。它同时是 Agent 表单、可移植运行包与部署的准入校验依据。
| 常量 | 值 | 说明 |
|---|---|---|
STUDIO_RUNTIME_CONTRACT_VERSION | agentkit.studio.runtime/v1 | 契约版本,同时是准入校验依据 |
STUDIO_RUNTIME_TYPES | dsh-native · harness · codex | 公开可路由的运行时类型 |
STUDIO_CANONICAL_IDENTIFIERS | agentId · revision · buildId · sessionId · runId | 跨实体唯一的标识字段名 |
公开运行时共 3 种:dsh-native、harness、codex。assertStudioRuntimeType() 只接受这些值,其余一律 RUNTIME_UNSUPPORTED。新增运行时只需改 src/runtime-contract.mjs:STUDIO_RUNTIME_TYPES,本页的计数与能力矩阵随之自动更新。见运行时。
能力矩阵
每种运行时声明自己的所有者、执行模型、事件与流式契约。矩阵之外的组合不受支持。
| runtime.type | owner | execution | contract | capabilities | eventOwner | streamOwner |
|---|---|---|---|---|---|---|
dsh-native | dsh | native | agentkit.studio.runtime/v1 | session session-events stream cancel replay persistence build-binding | dsh-session | dsh-agent/assistant-stream |
harness | ksadk-harness | native-kernel | agentkit.native-dsh-turn/v1 | native-run durable-receipts tool-approval cancel resume child-tasks | native-run-store | native-model-port |
codex | studio | codex-app-server | studio.codex.adapter/v1 | session stream cancel replay build-binding | studio-codex-adapter | codex-turn/item |
实体与标识
六个实体共享同一组标识字段名。任何一层缺失都视为身份不合法。
| 实体 | 字段 |
|---|---|
Agent | id→agentId · revision→revision |
Revision | id→revision · parent→agentId |
Build | id→buildId · agent→agentId · revision→revision |
Session | id→sessionId · build→buildId · agent→agentId · revision→revision |
Run | id→runId · session→sessionId · build→buildId · agent→agentId · revision→revision |
校验错误
| 错误码 | 触发条件 | 源码 |
|---|---|---|
RUNTIME_UNSUPPORTED | runtime.type 不在公开或实验列表中 | src/runtime-contract.mjs:67 |
RUN_IDENTITY_INVALID | agentId / sessionId / runId / buildId 缺失,或 revision 不是正整数 | src/runtime-contract.mjs:74 |
RUN_IDENTITY_MISMATCH | 运行身份与绑定的路由不一致 | src/runtime-contract.mjs:88 |
studioRunIdentity() 会先补齐字段再校验,因此空白字符串与缺字段等价;revision 会被强制转成数字。
版本与兼容性
| 项 | 值 | 说明 |
|---|---|---|
| 契约版本 | agentkit.studio.runtime/v1 | 与 Studio 版本同 PR 演进 |
| 公开运行时 | 3 种 | dsh-native / harness / codex |
| 标识字段 | 5 个 | 改名即破坏性变更 |
开发者入口
| 内容 | 源码位置 |
|---|---|
| 运行时契约 | src/runtime-contract.mjs |
| 会话事件词表 | src/host/dsh-session-contract.mjs |
| 原生轮次契约 | packages/harness/src/native/dsh-turn-contract.ts |
相关测试:
| 测试文件 | 位置 |
|---|---|
| runtime-contract.test.mjs | tests/runtime-contract.test.mjs |
| runtime-registry.test.mjs | tests/runtime-registry.test.mjs |