通过

编写技能清单

  • 项目

适用于：SDK v4

“技能清单”是一个 JSON 文件，用于描述技能可以执行的操作、其输入和输出参数以及技能的终结点。 清单包含开发人员可用于从其他机器人访问技能的机器可读信息。

本文介绍支持版本的 Bot Framework 技能清单架构。

版本 备注
版本 2.2 更新了一些 URI 属性以接受 URI 引用。
版本 2.1 增加了描述技能可以发送的主动活动以及技能使用的分派模型的功能。
版本 2.0 初始版本。

Bot Framework 技能清单架构使用 JSON 架构词汇的第 7 稿。

先决条件

技能清单

技能清单包含不同类别的信息：

  • 描述一般级别的技能的元数据。
  • 技能提供的终结点的列表。
  • 技能可以接收并主动发送的活动的可选列表。
  • 包含文档其他部分引用对象的架构的可选定义对象。
  • 技能支持的调度模型的可选列表。

下表介绍了 Bot Framework 技能清单 v2.2 的完整架构。

类别/字段 类型/格式 必须 描述
元数据
$id 字符串 必选 技能清单的标识符。
$schema 字符串/URI 必须 描述清单格式的 JSON 架构资源的 HTTPS URI。 对于版本 2.2，URI 为 https://schemas.botframework.azure.cn/schemas/skills/v2.2/skill-manifest.json。
copyright 字符串 可选 技能的版权声明。
description 字符串 可选 用户可理解的技能说明。
iconUrl 字符串/URI-参考 可选 所显示的技能相关图标的 URI。
license 字符串 可选 技能的许可协议。
name 字符串 必选 技能的名称。
privacyUrl 字符串/URI-参考 可选 技能的隐私说明的 URI。
publisherName 字符串 必选 技能发布者的姓名。
标记 字符串数组 可选 一组用于技能的标记。 如果存在，每个标记都必须唯一。
版本 字符串 必选 清单描述的技能版本。
终结点
终结点 终结点数组 必选 技能支持的终结点列表。 必须定义至少一个终结点。 每个终结点必须唯一。
活动
活动 包含名为活动对象的对象 可选 技能接受的初始活动集。
activitiesSent 包含名为活动对象的对象 可选 描述技能可以发送的主动活动。
定义
定义 Object 可选 一个对象，包含清单中使用的对象的子架构。
调度模型
dispatchModels dispatchModels 对象 可选 描述技能支持的语言模型和顶级意向。 参阅发货模型了解此对象的架构。

终结点

每个终结点对象描述技能支持的终结点。

此示例列出了技能的两个终结点。

"endpoints": [
    {
        "name": "americas",
        "protocol": "BotFrameworkV3",
        "description": "Production endpoint for SkillBot in the Americas",
        "endpointUrl": "http://myskill.contoso.com/api/messages",
        "msAppId": "00000000-0000-0000-0000-000000000000"
    },
    {
        "name": "eu",
        "protocol": "BotFrameworkV3",
        "description": "Production endpoint for SkillBot in Europe",
        "endpointUrl": "http://myskill.contoso.com/api/messages",
        "msAppId": "11111111-0000-0000-0000-000000000000"
    }
],

终结点对象

描述技能支持的终结点。

字段 类型/格式 必须 说明
description 字符串 可选 终结点的说明。
endpointUrl 字符串/URI 必须 技能的 URI 终结点。
msAppId 字符串 必选 技能的 Microsoft AppId (GUID)，用于验证请求。 必须与以下正则表达式匹配：^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$。
name 字符串 必选 终结点的唯一名称。
protocol 字符串 可选 支持的机器人协议。 默认值为“BotFrameworkV3”，表示 Bot Connector API 版本 3。 除非技能特意使用不同的协议，否则请使用默认值。

活动

每个活动对象描述技能接受的活动。 技能将根据收到的初始活动开启操作或任务。 与活动对象关联的名称指示技能将执行的操作或任务。

某些活动类型具有可用于向技能提供额外输入的值属性。 当技能结束（完成操作）时，它可以在关联的对话结束活动的值属性中提供返回值。

允许的活动类型是：消息、事件、调用和“其他”活动。 技能可以接收调用活动，但不能发送。

这是一个示例活动说明。

"bookFlight": {
    "description": "Books a flight",
    "type": "event",
    "name": "BookFlight",
    "value": {
        "$ref": "#/definitions/bookingInfo"
    },
    "resultValue": {
        "$ref": "#/definitions/bookingInfo"
    }
},

eventActivity 对象

描述技能接受或发送的事件活动。 事件活动的含义是由其名称字段定义的，该字段在技能范围内有意义。

字段 类型 必需 说明
description 字符串 可选 事件应启动的操作的说明。
name 字符串 必选 事件活动的“名称”属性值。
resultValue Object 可选 操作可以返回的对象类型的 JSON 架构定义。
type 字符串 必选 活动类型。 必须是“事件 (event)”。
值 Object 可选 此操作要求为输入的对象类型的 JSON 架构定义。

invokeActivity 对象

描述技能接受的调用活动。 调用活动的含义是由其名称字段定义的，该字段在技能范围内有意义。

字段 类型 必需 说明
description 字符串 可选 调用应启动的操作的说明。
name 字符串 必选 调用活动的“名称”属性值。
resultValue Object 可选 关联操作可以返回的对象类型的 JSON 架构定义。
type 字符串 必选 活动类型。 必须是“调用 (invoke)”。
值 Object 可选 此操作要求为输入的对象类型的 JSON 架构定义。

messageActivity 对象

描述技能接受或发送的消息活动。 消息活动的文本属性包含用户或机器人的言语。

字段 类型 必需 说明
description 字符串 可选 操作的说明。
resultValue Object 可选 关联操作可以返回的对象类型的 JSON 架构定义。
type 字符串 必选 活动类型。 必须是“消息 (message)”。
值 Object 可选 此操作要求为输入的对象类型的 JSON 架构定义。

otherActivities 对象

描述技能接受或发送的任何其他活动类型。

字段 类型 必需 说明
type 字符串 必选 活动类型。 必须是其他某个 Bot Framework 活动类型：“contactRelationUpdate”、“conversationUpdate”、“deleteUserData”、“endOfConversation”、“handoff”、“installationUpdate”、“messageDelete”、“messageReaction”、“messageUpdate”、“suggestion”、“trace”或“typing”。

otherActivities 对象可以包括其他属性，但技能清单架构不定义其含义。

定义

每个定义描述一个子架构，可由文档的其他部分使用。

这是航班预订信息的示例子架构。

"bookingInfo": {
    "type": "object",
    "required": [
        "origin"
    ],
    "properties": {
        "origin": {
            "type": "string",
            "description": "this is the origin city for the flight"
        },
        "destination": {
            "type": "string",
            "description": "this is the destination city for the flight"
        },
        "date": {
            "type": "string",
            "description": "The date for the flight in YYYY-MM-DD format"
        }
    }
},

调度模型

调度模型包含语言模型列表和技能支持的顶级意向列表。 这是一个高级功能，使技能使用者的开发人员能够组成一个结合了使用者和技能机器人功能的语言模型。

每个语言模型都使用 .lu 或 .qna 文件格式。 有关这些格式的详细信息，请参阅 .lu 文件格式 和 .qna 文件格式。

区域设置名称是与语言关联的 ISO 639 双字母小写区域性代码和与国家或地区关联的可选 ISO 3166 双字母大写子区域性代码的组合，如“en”或“en-US”。

字段 类型 必需 说明
意向 字符串数组 可选 技能支持的顶级意向的列表。 每个意向必须唯一。
语言 包含名为 languageModel 数组的对象 可选 技能支持的语言模型的列表。 每个名称都是语言模型所针对的区域设置，数组包含该区域设置的语言模型。 调度模型必须至少支持一个区域设置。 语言字段中的每个区域设置都必须唯一。

这是一个示例调度模型，其中包含跨三个区域设置的两种语言模型。 它还描述了技能可以识别的两个顶级意向。

"dispatchModels": {
    "languages": {
        "en": [
            {
                "name": "SkillBot LU (English)",
                "contentType": "application/lu",
                "url": "http://sample.com/SkillBot-en.lu",
                "description": "English language model for the skill"
            },
            {
                "name": "SkillBot QnA LU (English)",
                "contentType": "application/qna",
                "url": "http://sample.com/SkillBot-QnA-en.qna",
                "description": "English language model for the skill (QnAMaker)"
            }
        ],
        "es-ES": [
            {
                "name": "SkillBot LU (Spanish-Spain)",
                "contentType": "application/lu",
                "url": "http://sample.com/SkillBot-es-ES.lu",
                "description": "Spanish (Spain) language model for the skill"
            },
            {
                "name": "SkillBot QnA LU (Spanish-Spain)",
                "contentType": "application/qna",
                "url": "http://sample.com/SkillBot-QnA-es-ES.qna",
                "description": "Spanish (Spain) language model for the skill (QnAMaker)"
            }
        ],
        "es-MX": [
            {
                "name": "SkillBot LU (Spanish-Mexico)",
                "contentType": "application/lu",
                "url": "http://sample.com/SkillBot-es-MX.lu",
                "description": "Spanish (Mexico) language model for the skill"
            },
            {
                "name": "SkillBot QnA LU (Spanish-Mexico)",
                "contentType": "application/qna",
                "url": "http://sample.com/SkillBot-QnA-es-MX.qna",
                "description": "Spanish (Mexico) language model for the skill (QnAMaker)"
            }
        ]
    },
    "intents": [
        "bookFlight",
        "getWeather"
    ]
},

languageModel 对象

描述给定区域性的语言模型。 该名称是一个区域设置名称。

字段 类型/格式 必须 说明
contentType 字符串 必选 语言模型的类型。
description 字符串 可选 语言的详细说明。
name 字符串 必选 语言模型的名称。
url 字符串/URI-参考 必须 语言模型的 URL。

示例清单

这是公开多个活动的技能的完整示例 v2.2 清单。

{
    "$schema": "https://schemas.botframework.com/schemas/skills/v2.2/skill-manifest.json",
    "$id": "SkillBot",
    "name": "Sample skill definition that can handle multiple types of activities",
    "version": "1.0",
    "description": "This is a sample skill definition for multiple activity types",
    "publisherName": "Microsoft",
    "privacyUrl": "https://myskill.contoso.com/privacy.html",
    "copyright": "Copyright (c) Microsoft Corporation. All rights reserved.",
    "license": "",
    "iconUrl": "skillIcon.png",
    "tags": [
        "sample",
        "travel",
        "weather"
    ],
    "endpoints": [
        {
            "name": "americas",
            "protocol": "BotFrameworkV3",
            "description": "Production endpoint for SkillBot in the Americas",
            "endpointUrl": "http://myskill.contoso.com/api/messages",
            "msAppId": "00000000-0000-0000-0000-000000000000"
        },
        {
            "name": "eu",
            "protocol": "BotFrameworkV3",
            "description": "Production endpoint for SkillBot in Europe",
            "endpointUrl": "http://myskill.contoso.com/api/messages",
            "msAppId": "11111111-0000-0000-0000-000000000000"
        }
    ],
    "dispatchModels": {
        "languages": {
            "en": [
                {
                    "name": "SkillBot LU (English)",
                    "contentType": "application/lu",
                    "url": "http://sample.com/SkillBot-en.lu",
                    "description": "English language model for the skill"
                },
                {
                    "name": "SkillBot QnA LU (English)",
                    "contentType": "application/qna",
                    "url": "http://sample.com/SkillBot-QnA-en.qna",
                    "description": "English language model for the skill (QnAMaker)"
                }
            ],
            "es-ES": [
                {
                    "name": "SkillBot LU (Spanish-Spain)",
                    "contentType": "application/lu",
                    "url": "http://sample.com/SkillBot-es-ES.lu",
                    "description": "Spanish (Spain) language model for the skill"
                },
                {
                    "name": "SkillBot QnA LU (Spanish-Spain)",
                    "contentType": "application/qna",
                    "url": "http://sample.com/SkillBot-QnA-es-ES.qna",
                    "description": "Spanish (Spain) language model for the skill (QnAMaker)"
                }
            ],
            "es-MX": [
                {
                    "name": "SkillBot LU (Spanish-Mexico)",
                    "contentType": "application/lu",
                    "url": "http://sample.com/SkillBot-es-MX.lu",
                    "description": "Spanish (Mexico) language model for the skill"
                },
                {
                    "name": "SkillBot QnA LU (Spanish-Mexico)",
                    "contentType": "application/qna",
                    "url": "http://sample.com/SkillBot-QnA-es-MX.qna",
                    "description": "Spanish (Mexico) language model for the skill (QnAMaker)"
                }
            ]
        },
        "intents": [
            "bookFlight",
            "getWeather"
        ]
    },
    "activities": {
        "bookFlight": {
            "description": "Books a flight",
            "type": "event",
            "name": "BookFlight",
            "value": {
                "$ref": "#/definitions/bookingInfo"
            },
            "resultValue": {
                "$ref": "#/definitions/bookingInfo"
            }
        },
        "getWeather": {
            "description": "Retrieves and returns the weather for the user's location",
            "type": "invoke",
            "name": "GetWeather",
            "value": {
                "$ref": "#/definitions/location"
            },
            "resultValue": {
                "$ref": "#/definitions/weatherReport"
            }
        },
        "message": {
            "type": "message",
            "description": "Receives the user's' utterance and attempts to resolve it using the skill's LU models"
        },
        "typing": {
            "type": "typing"
        },
        "conversationUpdate": {
            "type": "conversationUpdate"
        }
    },
    "definitions": {
        "localeValue": {
            "type": "object",
            "properties": {
                "locale": {
                    "type": "string",
                    "description": "The current user's locale ISO code"
                }
            }
        },
        "bookingInfo": {
            "type": "object",
            "required": [
                "origin"
            ],
            "properties": {
                "origin": {
                    "type": "string",
                    "description": "this is the origin city for the flight"
                },
                "destination": {
                    "type": "string",
                    "description": "this is the destination city for the flight"
                },
                "date": {
                    "type": "string",
                    "description": "The date for the flight in YYYY-MM-DD format"
                }
            }
        },
        "weatherReport": {
            "type": "array",
            "description": "Array of forecasts for the next week.",
            "items": [
                {
                    "type": "string"
                }
            ]
        },
        "location": {
            "type": "object",
            "description": "Location metadata",
            "properties": {
                "latitude": {
                    "type": "number",
                    "title": "Latitude"
                },
                "longitude": {
                    "type": "number",
                    "title": "Longitude"
                },
                "postalCode": {
                    "type": "string",
                    "title": "Postal code"
                }
            }
        }
    },
    "activitiesSent": {
        "flightUpdated": {
            "type": "event",
            "name": "FlightUpdated",
            "description": "Event which is sent by the skill when there is an update in flight info",
            "value": {
                "type": "object",
                "description": "Flight update information",
                "properties": {
                    "flightNumber": {
                        "type": "string"
                    },
                    "departureDate": {
                        "type": "string",
                        "description": "The departure date for the flight in YYYY-MM-DD format"
                    },
                    "departureTime": {
                        "type": "string",
                        "description": "The departure time for the flight in HH-MM format"
                    }
                }
            }
        }
    }
}

后续步骤