创建自定义列表
重要
本文中的某些信息与预发行的产品有关，该产品在商业发布之前可能有重大修改。 Microsoft 对此处所提供的信息不作任何明示或默示的保证。
提示
如果需要有关非 Microsoft 插件的帮助，请参阅其文档和技术支持。
正在创建新插件
根据管理员配置安全 Copilot 的操作方式，可以通过执行以下步骤来创建新插件:
从支持的插件列表生成插件。
创建 YAML 或 JSON 插件清单文件，该文件描述有关插件的元数据以及如何调用它。
将插件清单发布到安全 Copilot。
插件要求
每个安全 Copilot 插件都需要一个 YAML 或 JSON 格式的清单文件(例如: plugin.yaml 或 plugin.json)，用于描述有关技能集的元数据以及如何调用技能。
清单必需由两个高级别的密钥组成，即 Descriptor 和 SkillGroups，每个密钥都具有子键或值对，以及必需/可选字段，具体取决于技能格式。
有关 OpenAI 插件的信息，请参阅 入门。
描述符字段摘要
| 字段 | 类型 | 说明 | 必需 |
|---|---|---|---|
Name |
string | 插件的内部名称。 不允许 / \ ? # @。 |
是 |
DisplayName |
string | 插件的用户可读名称。 | 建议 |
Description |
string | 插件的用户可读说明。 | 是 |
DescriptionDisplay |
string | 如果未指定说明，则替代插件的用户可读说明。 | 否 |
Category |
string | 注意:此值当前在自定义插件上传过程中强制执行 Plugin。 |
否 |
Prerequisites |
string | 否 | |
Icon |
string | 用于提取 Skillset 主图标的 URL。 | 建议 |
SkillGroups 字段摘要
由技能组的列表组成，包括 Format、Settings 和 Skills。
| 字段 | 类型 | 说明 | 必需 |
|---|---|---|---|
Format |
string | 有关可用选项，请参阅“格式”部分。 | 是 |
Settings |
object | 请参阅对象结构的“设置”部分。 | 是，适用于格式: API、DOTNET、CONTAINER |
Skills |
object | 请参阅对象结构的“技能”部分。 | 是，适用于格式: GPT、DOTNET、KQL、LogicApp |
格式 (SkillGroups 字段)
字段 Format 的选项:
API
GPT
KQL
设置 (SkillGroups 字段)
字段 Settings 的对象结构。
| 字段 | 类型 | 说明 | 必需 |
|---|---|---|---|
OpenApiSpecUrl |
string | 公共 OpenAPI 规范的 URL。 | 是 |
EndpointUrl |
string | 公共终结点的 URL。 | 否 |
技能 (SkillGroups 字段)
字段 Skills 的对象结构。
| 字段 | 类型 | 说明 | 必需 |
|---|---|---|---|
Description |
string | 此技能的用户可读说明。 | 建议 |
DescriptionForModel |
string | 用于技能选择的技能详细说明 | 否 |
Inputs |
object | 用于用户输入技能的对象列表 Name、Description、Required 和 DefaultValue (可选)。 |
|
Settings |
object | 基于技能 格式 的自定义设置。 |
OpenAI 和安全 Copilot 清单之间的差异
遵循 ChatGPT 插件文档 生成的 OpenAI 插件通常使用与 Microsoft 安全 Copilot 不同的清单格式。 安全 Copilot 支持两种格式。
上传时，OpenAI 插件 清单 将转换为安全 Copilot 清单。
注意
映射详细信息(尤其是笔记中的限制)可能会在将来发生更改。 目前，平台仅支持 OpenAPI 版本 3.0 或 3.0.1 中的插件。
插件字段映射
| 插件字段 | 类型 | 描述符字段 | 必需 | 注意 |
|---|---|---|---|---|
schema_version |
string | 否 | 它是 OpenAI 清单架构版本，例如“v1”。 目前尚未使用。 | |
name_for_model |
string | 名称 | 是 | 限制为长度为 100 个字符。 技能集的内部名称。 不允许 / \ ? #。 |
name_for_human |
string | DisplayName | 是 | 插件的用户可读名称。 限制长度为 40 个字符。 |
description_for_model |
string | 说明 | 是 | 限制长度为 16,000 个字符。 与 LLM 一起使用的内部说明。 |
description_for_human |
string | DescriptionDisplay | 是 | 插件的用户可读说明。 限制长度为 200 个字符。 |
logo_url |
string | 图标 | 建议 | 用于提取插件的主图标的 URL。 |
contact_email |
string | 否 | 插件的电子邮件联系人。 目前尚未使用。 | |
legal_info_url |
string | 否 | 插件信息链接。 目前尚未使用。 | |
api |
object | 请参阅对象结构的 插件 API 部分 | 是 | |
auth |
object | 是 |
authorization_type 限制为 bearer。 有关支持不同身份验证 type (例如 none、oauth、api_key、aad、aad_delegated) 的详细信息。 |
插件 (API 字段)
字段 api 的对象结构
| 字段 | 类型 | 说明 | 必需 |
|---|---|---|---|
type |
string | 当前唯一支持的类型是 openapi。 |
是 |
url |
string | 链接到 API 的 OpenAPI 规范 文档。 | 是 |
插件创作指南
有关插件创作的许多注意事项。 本文档旨在记录编写 Microsoft 安全 Copilot 插件的一些准则和最佳做法。
注意
当 Microsoft 安全 Copilot 无法准确区分两种不同的技能时，会发生“技能冲突”。
并非拥有多个返回相同类型响应的技能，只是根据输入的不同而有所区别；定义技能，让技能采用多个输入，然后在内部确定获取数据的方法。
- 例如，具有单个技能
GetDevices，该技能采用设备 ID、用户 ID 或用户名，而不是单独的GetDeviceById、GetDeviceByUserId和GetDeviceByUserName
- 例如，具有单个技能
安全 Copilot 支持
Description和DescriptionForModel字段。Description在 UX 中使用(如果DescriptionForModel未设置，则用于技能选择)，并且DescriptionForModel仅用于技能选择。- 例如，假设我们有一个技能 GetSslCertsByHostname，其中包含“返回与主机名关联的 SSL 证书”的说明。 详细描述 ForModel 可以是“检索 DNS 主机名或域名的 SSL 证书(也称为 TLS 证书)。 返回 SSL 证书列表以及证书详细信息，例如颁发者、使用者、序列号、sha1 和日期”。
技能说明应言简意赅，措辞应适合有一定知识但可能不是问题领域专家的人。 它不仅应该描述技能的作用，还应描述为什么有人想要使用它。
- 例如，好的描述应是“获取 IP 地址的信誉信息。 使用户能够确定 IP 地址是否存在风险”。