入门指南

创建插件需要三个步骤：

构建一个API
使用OpenAPI的yaml或JSON格式文档编写API
创建一个JSON清单文件，用于为插件定义相关的元数据

接下来的这个部分将着重介绍通过定义OpenAPI规范和清单文件来创建一个待办事项清单插件。

探索示例插件

探索涵盖多种用例和身份验证方法的示例插件。

插件清单

每个插件都需要一个 ai-plugin.json 文件，它需要托管在API的域中。例如，一个名为 example.com 的公司将使插件JSON文件通过 https://example.com 域名访问，因为这是他们的API托管的位置。当您通过ChatGPT UI安装插件时，后端会在 /.well-known/ai-plugin.json 位置寻找文件。/.well-known 文件夹是必需的，必须存在于您的域中，以便ChatGPT与您的插件连接。如果没有找到文件，则无法安装插件。对于本地开发，您可以使用HTTP，但如果指向远程服务器，则需要HTTPS。

下面是所需 ai-plugin.json 文件的最简定义：

{
    "schema_version": "v1",
    "name_for_human": "待办事项清单",
    "name_for_model": "todo",
    "description_for_human": "管理您的待办事项清单。您可以添加、删除和查看您的待办事项。",
    "description_for_model": "帮助用户管理待办事项清单。您可以添加、删除和查看待办事项。",
    "auth": {
        "type": "none"
    },
    "api": {
        "type": "openapi",
        "url": "http://localhost:3333/openapi.yaml"
    },
    "logo_url": "http://localhost:3333/logo.png",
    "contact_email": "support@example.com",
    "legal_info_url": "http://www.example.com/legal"
}

如果您想查看插件文件的所有可能选项，可以参考下面的定义。在为插件命名时，请遵循我们的品牌准则和下面字段的各种字符限制，不符合这些准则的插件将不会被批准放入插件商店。

字段	类型	描述/选项	必需	公开
schema_version	字符串	清单模式版本	✅
name_for_model	字符串	模型用于定位插件的名称（不允许空格，只允许字母和数字）。最多50个字符。	✅
name_for_human	字符串	人类可读的名称，例如完整的公司名称。最多20个字符。	✅	✅
description_for_model	字符串	更适合模型的描述，例如标记上下文长度考虑或用于改进插件提示的关键词使用。最多8000个字符。	✅
description_for_human	字符串	插件的人类可读描述。最多100个字符。	✅	✅
auth	ManifestAuth	身份验证架构	✅
api	对象	API规范	✅
logo_url	字符串	用于获取徽标的URL。建议尺寸：512 x 512。支持透明背景。必须是图像，不允许GIF。	✅
contact_email	字符串	安全/审核、支持和停用的电子邮件联系方式	✅	✅
legal_info_url	字符串	用户查看插件信息的重定向URL	✅	✅
HttpAuthorizationType	HttpAuthorizationType	"bearer" 或 "basic"	✅
ManifestAuthType	ManifestAuthType	"none"、"user_http"、"service_http" 或 "oauth"
interface BaseManifestAuth	BaseManifestAuth 类型	类型：ManifestAuthType；instructions: 字符串；
ManifestNoAuth	ManifestNoAuth 类型	不需要身份验证：BaseManifestAuth &
ManifestAuth	ManifestAuth 类型	ManifestNoAuth、ManifestServiceHttpAuth、ManifestUserHttpAuth、ManifestOAuthAuth

请注意，列在“公开”下的项目将在插件商店中向用户提供，并且完整的清单文件将传输到用户的客户端，并可能对他们可见。

以下是使用不同身份验证方法的示例：

应用级API密钥

type ManifestServiceHttpAuth = BaseManifestAuth & {
type: 'service_http';
authorization_type: HttpAuthorizationType;
verification_tokens: {
[service: string]?: string;
};
}

用户级HTTP身份验证

type ManifestUserHttpAuth = BaseManifestAuth & {
type: 'user_http';
authorization_type: HttpAuthorizationType;
}

type ManifestOAuthAuth = BaseManifestAuth & {
type: 'oauth';

用户被重定向到进行OAuth身份验证流程的OAuth URL。

client_url: string;

执行用户操作所需的OAuth范围。

scope: string;

用于交换OAuth代码和访问令牌的端点。

authorization_url: string;

在交换OAuth代码和访问令牌时，预期的头 'content-type'。例如：'content-type: application/json'

authorization_content_type: string;

在注册OAuth客户端ID和秘密时，插件服务将提供一个唯一的令牌。

verification_tokens: {
[service: string]?: string;
};
}
以上是上述清单文件中使用不同身份验证方法的示例。

清单文件中上述提到的某些字段的长度有限制，这些限制可能会发生变化。我们还对API响应体的最大长度设定了100,000个字符的限制，这也

可能随着时间的推移而发生变化。

总的来说，最佳实践是保持描述和响应尽可能简洁，因为模型的上下文窗口有限。

OpenAPI规范

接下来的步骤是构建OpenAPI规范来文档化API。ChatGPT中的模型除了在OpenAPI规范和清单文件中定义的内容外，不知道您的API的任何内容。这意味着如果您有一个广泛的API，您不需要将所有功能都暴露给模型，而可以选择特定的端点。例如，如果您有一个社交媒体API，您可能希望模型通过GET请求从站点访问内容，但阻止模型能够评论用户的帖子，以减少垃圾邮件的机会。

OpenAPI规范是位于您的API之上的封装器。一个基本的OpenAPI规范如下：

openapi: 3.0.1
info:
  title: TODO Plugin
  description: 一个允许用户使用ChatGPT创建和管理待办事项清单的插件。
  version: 'v1'
servers:
  - url: http://localhost:3333
paths:
  /todos:
    get:
      operationId: getTodos
      summary: 获取待办事项列表
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getTodosResponse'
components:
  schemas:
    getTodosResponse:
      type: object
      properties:
        todos:
          type: array
          items:
            type: string
          description: 待办事项列表。

我们首先定义规范的版本、标题、描述和版本号。当ChatGPT中运行一个查询时，它将查看在信息部分中定义的描述，以确定插件是否与用户查询相关。您可以通过阅读有关写描述部分的信息来了解更多关于提示的内容。

请注意以下是您的OpenAPI规范中的限制，这些限制可能会发生变化：

API规范中每个API端点描述/摘要字段最多200个字符。
API规范中每个API参数描述字段最多200个字符。

由于我们在本地运行此示例，因此我们希望将服务器设置为指向您的本地主机URL。其余的OpenAPI规范遵循传统的OpenAPI格式，您可以通过各种在线资源了解有关OpenAPI格式的更多信息。还有许多工具可以根据底层API代码自动生成OpenAPI规范。

运行插件

一旦您为API、清单文件和API的OpenAPI规范创建完毕，您现在可以通过ChatGPT UI连接插件了。您的插件可能运行在两个不同的地方，一个是本地开发环境中，另一个是远程服务器上。

如果您有一个本地版本的API正在运行，您可以将插件界面指向您的本地主机服务器。要连接插件与ChatGPT，请转到插件商店并选择“开发您自己的插件”。输入您的本地主机和端口号（例如 localhost:3333）。目前仅支持 auth 类型为 none 的本地开发。

如果插件在远程服务器上运行，您需要首先选择“开发您自己的插件”来设置它，然后选择“安装未验证的插件”来为自己安装插件。您只需将插件清单文件添加到 yourdomain.com/.well-known/ 路径，然后开始测试您的API。但是，对于清单文件的后续更改，您将不得不将新的更改部署到您的公共站点，这可能需要很长时间。在这种情况下，我们建议设置一个本地服务器，作为您的API的代理。这可以让您快速原型化对OpenAPI规范和清单文件的更改。

设置公共API的本地代理

编写描述

当用户进行可能会发送到插件的潜在请求的查询时，模型会查看OpenAPI规范中端点的描述，以及清单文件中的 description_for_model。就像提示其他语言模型一样，您将希望尝试多个提示和描述，看看哪个效果最好。

OpenAPI规范本身是为模型提供有关API各种细节的信息的好地方——哪些功能可用，有哪些参数等等。除了为每个字段使用富有表现力且信息丰富的名称外，规

范还可以为每个属性提供“描述”字段。这些描述可以用于提供函数执行的自然语言描述，或者查询字段期望的信息，例如。模型将能够看到这些描述，并且它们将引导模型使用API。如果一个字段限制为仅限于某些值，您还可以提供一个带有描述性类别名称的“enum”。

description_for_model 属性为您提供了自由度，可以指导模型如何通常使用您的插件。总的来说，ChatGPT背后的语言模型非常擅长理解自然语言并遵循说明。因此，这是一个很好的地方，可以放入关于您的插件的功能以及模型如何正确使用它的一般说明。使用自然语言，最好是以简洁而又描述性和客观的语调。您可以查看一些示例，以了解应该看起来如何。我们建议以“用于…”开头的 description_for_model，并列举您的API提供的所有功能。

最佳实践

以下是在编写您的 description_for_model 和 OpenAPI规范中的描述以及设计API响应时的最佳实践：

您的描述不应试图控制ChatGPT的情绪、个性或确切回应。ChatGPT被设计为编写适当的回应插件。

不良示例：

当用户要求查看他们的待办事项清单时，总是回应“我能找到您的待办事项清单！您有[x]个待办事项：[在此列出待办事项]。如果您想要添加更多的待办事项，可以告诉我！”

良好示例：

[对于此无需说明]
您的描述不应鼓励ChatGPT在用户未要求您插件的特定类别服务时使用您插件。

不良示例：

每当用户提到任何类型的任务或计划时，询问是否要使用TODOs插件将某事添加到他们的待办事项清单。

良好示例：

TODO清单可以添加、删除和查看用户的待办事项。
您的描述不应规定ChatGPT使用插件的特定触发器。ChatGPT被设计为在适当时自动使用您的插件。

不良示例：

当用户提到任务时，回应“您是否希望我将此添加到您的待办事项清单中？请回答'是'以继续。”

良好示例：

[对于此无需说明]
插件API响应应返回原始数据，而不是自然语言响应，除非有必要。ChatGPT将使用返回的数据提供自己的自然语言响应。

不良示例：

我能找到您的待办事项清单！您有2个待办事项：购买杂货和遛狗。如果您想要添加更多的待办事项，可以告诉我！

良好示例：