AgentKit Studio
生态与插件

专家模板

用 agentkit.studio.team-template/v1 定义专家团:字段表、角色蓝图约束、校验失败的错误码对照、发布与召唤流程。

专家模板是 JSON,不是代码。 一个专家团模板描述「谁组成这个团队、每个角色有什么指令、能绑什么资源」, 由 Studio 校验后交给 DSH Agent Teams 运行。

概念是什么契约
专家模板单个预置 Agent 的配置快照走 Agent 的 Revision 语义,见核心概念
专家团模板多角色协作单元agentkit.studio.team-template/v1(本页)

本页只讲专家团模板——它是唯一有独立 schema 契约的模板类型。

顶层字段

字段类型必填约束源码
kindstring✅必须严格等于 "team"team-template-contract.mjs:52
idstring✅/^[a-z][a-z0-9-]*$/,≤128 字符:53-54
versionstring✅严格 \d+\.\d+\.\d+(不允许 -rc 后缀):54
namestring✅≤120 字符:55
instructionsstring✅≤16000 字符,专家团级协作指令:56
rolesarray✅2–9 个,且 roles[0].name 必须是 lead:57-58
defaultModel / modelstring—≤256 字符;不能是占位模型:80
contractstring—缺省填 agentkit.studio.team-template/v1:83
catalogIdstring—目录归属,可选:48

专家团必须是 2 个角色起步

roles.length < 2 直接失败。只有一个角色时不需要专家团——用普通专家模板。 源码:team-template-contract.mjs:58。

角色字段

字段类型必填约束源码
namestring✅/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/,≤64 字符,团队内唯一:61-62
labelstring—≤80 字符,缺省等于 name:65
instructionsstring—≤8000 字符:66-67
agentPreset / agentPresetIdstring—≤256 字符:68
model / modelId / modelProfileIdstring—≤256 字符;不能是占位模型:69
template.idstring✅≤256 字符,指向不可变模板:40
template.versionstring✅semver,≤64;省略时回落到专家团 version:45-47
template.digeststring✅≤256 字符,内容锁:46
template.catalogIdstring—缺省回落到专家团 catalogId:48

角色名的两条硬规则

规则违反时源码
只有第一个角色可以叫 leadTEAM_TEMPLATE_ROLE_INVALID:62
角色名不能重复TEAM_TEMPLATE_ROLE_INVALID:62

角色不能引用普通 Agent

{
  "name": "writer",
  "agentId": "ar-12345"
}

这样写会失败:TEAM_TEMPLATE_ROLE_INVALID,消息是 「角色「writer」不能引用普通 Agent,请改用不可变的 template 引用」。

为什么? 普通 Agent 是可变的——它的 Revision 会前进。专家团需要一个内容可复现的成员, 所以只能引用带 digest 的不可变模板。源码:team-template-contract.mjs:63。

角色蓝图(role spec)

专家团模板里的 template 指向一个 Agent 定义;那个定义的 spec 由 validateTeamRoleSpec 再校验一遍:

字段约束违反时
runtime.type只允许 dsh-native 或 harnessTEAM_TEMPLATE_RUNTIME_UNSUPPORTED
subAgents / sub_agents禁止声明TEAM_TEMPLATE_NESTED_TEAM_UNSUPPORTED
instructions.system必须是非空字符串TEAM_TEMPLATE_ROLE_SPEC_INVALID
bindings必须是对象(不能是数组)TEAM_TEMPLATE_ROLE_SPEC_INVALID
bindings.modelProfileId / modelProfileIds[]不能是占位模型TEAM_TEMPLATE_MODEL_INVALID

Codex 不在专家团支持范围内

TEAM_TEMPLATE_RUNTIMES 只有两个值:dsh-native 和 harness。 即使 Studio 的 Agent 表单提供 codex,专家团角色也用不了它。 源码:team-template-contract.mjs:4,9,94。

占位模型

模板里不允许残留占位符,否则召唤出来的团队会拿假模型去跑:

占位值检查位置错误码
one-team-model专家团 defaultModel / modelTEAM_TEMPLATE_MODEL_INVALID
one-team-model角色 model 等字段TEAM_TEMPLATE_MODEL_INVALID
one-team-model目录审计时递归扫描任意含 model 的键TEAM_TEMPLATE_PLACEHOLDER_MODEL

源码:team-template-contract.mjs:16,30-34、team-template-audit.mjs:20-35,56。

完整示例

{
  "kind": "team",
  "id": "release-crew",
  "version": "1.2.0",
  "name": "发布小队",
  "instructions": "lead 拆解发布清单;writer 产出发布说明;reviewer 在合入前复核。",
  "defaultModel": "model-profile-prod",
  "roles": [
    { "name": "lead", "label": "队长", "instructions": "拆解任务并分派,最终汇总。",
      "template": { "id": "agent/team-lead", "version": "1.0.0", "digest": "sha256:9f2c…" } },
    { "name": "writer", "label": "撰写", "instructions": "根据变更生成发布说明。",
      "template": { "id": "agent/tech-writer", "version": "1.0.0", "digest": "sha256:4ab7…" } },
    { "name": "reviewer", "label": "复核", "instructions": "检查事实与链接。",
      "template": { "id": "agent/reviewer", "version": "1.0.0", "digest": "sha256:77e1…" } }
  ]
}

校验失败错误码对照

错误码触发条件处理
TEAM_TEMPLATE_INVALIDkind !== "team";id / version / name / instructions 为空或超长对照顶层字段表逐项修正
TEAM_TEMPLATE_ROLE_INVALID角色数不在 2–9;lead 不在首位;角色名重复或不合法;角色引用了普通 Agent调整 roles 数组
TEAM_TEMPLATE_ROLE_SOURCE_INVALIDtemplate 缺失、不是对象、缺 id 或 digest、version 非 semver补全 template.id / .version / .digest
TEAM_TEMPLATE_MODEL_INVALID模型字段是占位模型换成真实模型档案 id
TEAM_TEMPLATE_ROLE_SPEC_INVALID角色蓝图不是对象;缺 instructions.system;bindings 不是对象修正角色定义
TEAM_TEMPLATE_RUNTIME_UNSUPPORTEDruntime.type 不是 dsh-native / harness改运行时
TEAM_TEMPLATE_NESTED_TEAM_UNSUPPORTED角色声明了 subAgents / sub_agents删掉嵌套声明
TEAM_TEMPLATE_PLACEHOLDER_MODEL目录审计发现残留占位模型替换全部模型字段
TEAM_ROLE_DEFINITION_MISSING找不到角色模板定义(requireRoleDefinitions 时为 error,否则 warning)先发布角色模板
TEAM_ROLE_DEFINITION_KIND_INVALID角色模板的 kind 不是 agent换成 Agent 定义
TEAM_ROLE_NOT_TEAM_ONLY角色模板未标记 teamRoleOnly: true补标记
TEAM_TEMPLATE_NONE(warning)目录里没有任何 kind=team 的模板不是错误,仅提示

源码:team-template-contract.mjs、team-template-audit.mjs:51-74。

审计

发布前必须跑一次目录审计,它不修改输入,只返回报告:

import { auditTeamTemplateCatalog } from './src/team-template-audit.mjs';
const report = auditTeamTemplateCatalog({
  items,                        // 目录列表项
  definitions,                  // 角色模板定义(Map 或普通对象)
  requireRoleDefinitions: true, // 缺定义时升级为 error
});
// report: { ok, teamCount, errors[], warnings[] },每条问题 { code, message, path? }

源码:team-template-audit.mjs:42-74。

发布与召唤

operation作用
team-templates/list / team-templates/detail列出与读取专家团模板
templates/summon-plan / templates/summon生成召唤计划(不落库)与执行召唤
template-workflows/{start,status,cancel,detail,cache,clearCache}长任务的进度、取消与缓存管理

召唤状态:running → succeeded / failed / cancelled;进程中断后读取会得到 interrupted。 源码:src/template-workflows.mjs:17-35。

相关

专家与团队的运行语义见专家与本地团队,机器可读的字段定义见模板 Schema 参考,全部错误码见错误码参考。

本页导航