ChatGPT插件开发指南

创建一个chatgpt插件需要3个步骤：

1. 构建一个API
2. 使用OpenAPI的yaml或JSON格式对API进行文档化
3. 创建一个JSON清单文件，定义插件的相关元数据

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

浏览示例插件

浏览涵盖多个用例和身份验证方法的示例插件。

插件清单

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

ai-plugin.json 文件的最小定义如下：

{
    "schema_version": "v1",
    "name_for_human": "TODO Plugin",
    "name_for_model": "todo",
    "description_for_human": "Plugin for managing a TODO list. You can add, remove and view your TODOs.",
    "description_for_model": "Plugin for managing a TODO list. You can add, remove and view your TODOs.",
    "auth": {
        "type": "none"
    },
    "api": {
        "type": "openapi",
        "url": "http://localhost:3333/openapi.yaml",
        "is_user_authenticated": false
    },
    "logo_url": "http://localhost:3333/logo.png",
    "contact_email": "support@example.com",
    "legal_info_url": "http://www.example.com/legal"
}

如果您想查看插件文件的所有可能选项，可以参考以下定义。在命名插件时，请记住我们的品牌指南，不遵守这些指南的插件将不会获得批准进入插件商店。

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

# App-level API keys
type ManifestServiceHttpAuth  = BaseManifestAuth & {
  type: 'service_http';
  authorization_type: HttpAuthorizationType;
  verification_tokens: {
    [service: string]?: string;
  };
}

# User-level HTTP authentication
type ManifestUserHttpAuth  = BaseManifestAuth & {
  type: 'user_http';
  authorization_type: HttpAuthorizationType;
}

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

  # OAuth URL where a user is directed to for the OAuth authentication flow to begin.
  client_url: string;

  # OAuth scopes required to accomplish operations on the user's behalf.
  scope: string;

  # Endpoint used to exchange OAuth code with access token.
  authorization_url: string;

  # When exchanging OAuth code with access token, the expected header 'content-type'. For example: 'content-type: application/json'
  authorization_content_type: string;

  # When registering the OAuth client ID and secrets, the plugin service will surface a unique token.
  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: A plugin that allows the user to create and manage a TODO list using ChatGPT.
  version: 'v1'
servers:
  - url: http://localhost:3333
paths:
  /todos:
    get:
      operationId: getTodos
      summary: Get the list of todos
      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: The list of todos.

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

请记住，您的 OpenAPI 规范有以下限制，这些限制可能会发生更改:

• API 规范中每个 API 端点描述/摘要字段的最大长度为 200 个字符
• API 规范中每个 API 参数描述字段的最大长度为 200 个字符

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

运行插件

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

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

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