AssistantAI

A Sublime Text 插件，用于与 HTTP API 接口交互，并对响应进行文字处理。AssistantAI 内置 OpenAI，以便与 ChatGPT 或 Codex 交互，直接从选中代码创建 Gitea 的问题，并通过 Python 提示自动添加 Docstrings 等。用户可以在 Sublime 设置 JSON 文件中定义服务器端点和自定义提示来扩展其功能。

AssistantAI 提供了一个通用的 HTTP API 客户端实现，它允许对基于选文本和可选用户输入的请求进行远程 API 响应的文字处理。它可以由用户或其他包扩展，提供服务器、端点、提示模板和凭证占位符，这些都在 Sublime 设置JSON文件中定义。

一个常见的用例是消费类似 ChatGPT 或 OpenAI Codex 的生成性 AI 的 API，以完成、编辑、评论或解释选定的代码块。另一个例子是消费 GitHub、Gitea 或类似 VCS 服务器的 API，以便在不离开 Sublime Text 的情况下直接从选定的代码添加问题。

隐私警告

选定的代码、文件路径、名称、文件大小和符号可能会被发送到远程第三方 API 服务器进行处理（例如：OpenAI，见下文），因此请确保您有执行此类操作所需的必要权限。

安装

此插件可在 Package Control 中使用。

通过 Package Control 安装插件是推荐选项

• 调用命令面板（Cmd + Shift + P）
• 搜索“Package Control：安装包”
• 搜索“AssistantAI”并安装它

安装完成后，请在设置 > 包设置 > AssistantAI中检查设置菜单，其中包括

• 设置：通用AssistantAI插件设置。添加自定义提示和服务器的地方。
• 键盘快捷键：用于调用AssistantAI提示选择面板等示例键绑定。

此外，您还可以配置插件附带的以下内容

• OpenAI服务器设置：为ChatGPT完成API端点和通用提示定义。
• Gitea服务器设置：为Gitea Issue创建端点定义。
• Python提示：定义Python特定提示（即使用OpenAI向所选代码添加Doctring）。

当您配置了一个服务器或更多（见下文）时

• 命令面板中的AssistantAI命令。

设置

AssistantAI使用Sublime JSON设置文件进行配置和扩展。插件为每个服务或特定语法定义提供了几个文件（例如，一个用于OpenAI，另一个用于Gitea、Python等），其中每个文件都遵循相同的结构

• credentials：默认为空。您应按以下说明覆盖此条目以提供该服务器的凭证。
• prompts：默认为空。覆盖它以添加（或导入和改进）您自定义的提示。
• servers：默认为空。覆盖它以添加（或导入和改进）您自定义的服务器。
• default_prompts：由包提供的提示。您不应覆盖此条目。
• default_servers：由包提供的服务器。您不应覆盖此条目。

您的自定义设置文件可能包括credentials以启用服务器，从而使所有依赖于它的提示在您调用AssistantAI命令时可用。如果您添加了自定义提示或服务器，则prompts和servers可能也在您的自定义文件中。

您的自定义文件中不应始终存在default_prompts和default_servers。如果您想基于默认服务器创建一个服务器，可以使用高级主题中或设置文件中的示例中描述的import。

文件命名遵循以下约定

• assitant_ai.sublime-settings用于一般设置。
• assitant_ai_{NAME}.sublime-settings用于服务或特定语法的设置文件。

目前，您至少应配置OpenAI的API密钥或Gitea的API令牌，以便与插件一起使用。

所有内容都可以使用Sublime JSON设置以非常灵活的方式进行配置。

键盘快捷键和命令

提供了一个键盘快捷键文件示例，用于将键盘快捷键绑定到AssistantAI命令，因此您可以根据当前上下文快速获取可用的提示列表或直接调用提示。

您可以使用键盘快捷键调用两个命令

• AssistnatAI提示：标识为assistant_ai_prompt。此命令也存在于命令面板中。在不带参数调用时，显示可以使用提示的列表，给定配置的服务器、所选文本、缓冲区语法等（即上下文）。要直接调用提示，可以传递参数

  • pid：提示ID
  • eid：端点ID
  • ...：提示所需的任何其他输入参数。

• AssistnatAI导出：标识为assistant_ai_dump。用于调试。导出所有加载的设置并在新缓冲区中显示，以便您可以检查正在加载的内容。当您开始使用服务器和提示的import时，可能需要知道AsistantAI已处理的内容。

如果没有可用的提示，则AssistantAI命令除了在状态栏中显示警告消息外不执行其他操作。

用法

安装和配置后，从命令面板调用AssistantAI，从显示的列表中选择一个提示并按照其流程操作。

根据上下文（配置的服务器、选中文本、缓冲区语法、可用内容等）提供提示，并按照提示本身提供的规范。

如果没有配置服务器，将没有可用提示。

一般的流程很简单。比如：

• 选择一个文本区域（例如：代码函数或Markdown部分）。
• 命令面板 > AssistantAI（或您设置的快捷键）。
• 选择一个提示。
• 如果提示需要额外的输入，将通过UI请求这些输入。
• 当多个具有有效端点的服务器符合选定的提示时，会呈现一个端点列表。

AssistantAI获取提示、所有需要的输入和选定的目标端点后，基于此构建HTTP有效载荷并执行网络请求。

根据端点规范进行解析，并执行其指定的命令。

提示可以指定其他操作而不是文本操作（替换、追加、预加、插入），例如在输出面板中显示响应或新缓冲区。

例如，在编辑Python文件时使用捆绑的OpenAI服务器端点定义插件（需要凭证）：

• 选择一个Python函数。
• 请求AssistantAI的提示“添加Python文档字符串”。
• 由于只有一个端点符合条件，将直接使用OpenAI进行请求而无需进一步输入。
• Python文档字符串作为ChatGPT返回的添加到所选函数。

此插件包含什么？

插件实现了设置文件的解析器，其中配置了服务器、提示和凭证（由本包、其他包或用户）。管理给定上下文中可用的提示的过滤，并负责API请求、构建有效载荷、解析响应和执行文本操作。

除了插件实现之外，AssistantAI还包括以下服务器和提示的定义。

服务器

服务器是可以使用HTTP请求消费的网络资源定义。包括URL、超时和描述。

每个服务器必须指定一个或多个端点，这些端点包括可能的请求有效载荷结构以及基于提示用户输入（例如：选定的文本或用户请求的其他输入）构建的声明性指令。

AssistantAI在读取配置时寻找服务器定义。当用户配置了所有必需的凭证（例如：API密钥）时，认为该服务器是可用的。

AssistantAI目前包括以下服务器和端点定义。

OpenAI

OpenAI 服务器定义，允许使用三个端点消耗API

• 编辑
• 完成
• 聊天完成（为ChatGPT提供动力）

请注意，OpenAI是一项付费服务，您将需要API密钥和足够的信用才能使用该插件。

一旦您有了API密钥，请转到设置 > 包设置 > AssistantAI > OpenAI服务器设置并添加凭证

{
  "credentials": {
    // you must specify the Server ID ('openai' in this case) which this credential is for 
    "openai": {
      // OpenAI requires only one credential named 'api_key'
      "api_key": "sk-..."

      // Other servers may require more tokens, identification, etc.

      // For custom TLS: you can specify `verify` for a custom CA and `cert` for a Client Cert
      // "verify": "~/.tls/my_ca.pem"
      // "cert": "~/.tls/my_cert.pem" // must include unencrypted key 
    }
  }
}

Gitea

Gitea是GitHub的开源替代品，功能较少、体积较小，您可以在自己的基础设施中部署它。它提供了一个API来与之交互，允许许多其他工作流程，例如检索存储库信息，创建问题单和PR。

此服务器定义包含两个端点

• 获取存储库
• 向特定存储库创建问题单

由于您可能有权访问多个Gitea实例（例如：个人和使用场所的），您可以定义自己的自定义服务器，方法是导入默认的存储库

"servers": [
    {
      "id": "gitea_personal",
      "import": "gitea", // this is provided in 'default_servers'
      "name": "Gitea Kanutron",
      "url": "https://CUSTOM_URL:443", // the default points to https://localhost:3000
    },
    {
      "id": "gitea_work",
      "import": "gitea",
      "name": "Gitea Work",
      "url": "https://CUSTOM_URL:443",
    },
  ],

并为它们每个提供凭证，凭证由其id标识

{
  "credentials": {
    "gitea_personal": {
      "token": "...",
    },
    "gitea_work": {
      "token": "...",
      "verify": "~/.gitea/secrets/rootca.pem",
      "cert": "~/.gitea/secrets/user.pem",
    },
  }
}

提示

提示是用户在使用 Sublime Text 编辑时必须填充变量的模板。这是一个简单的流程。

必要的变量相当灵活，通常包括表示所选文本的 text。

一旦用户调用了提示，它必须解决所有必要输入，如果尚未自动解决。

然后将请求构建并发送到可用的端点，或者用户选择的端点（如果有多个可用）。

例如，如果提示仅需要 text，则用户必须选择文本，以便提示可用。

如果提示仅限于 语法（即：Python），则当前缓冲区必须来自所需的语法。

AssistantAI 内置的可用提示如下。

OpenAI

如果启用了 OpenAI 服务器（即：已配置凭据），则提供一系列通用提示

• 从选择的末尾继续文本
• 询问是否对选择进行更改
• 使用 Chat 端点询问是否对选择进行更改

这些提示至少需要一个接受 text 作为输入的端点，或 text + 。

Python

AssistantAI 中捆绑了一组在编辑 Python 代码时常用的提示。

• 添加文档字符串：选择一个 Python 函数并调用此提示，将请求 Python 函数填充 docstring。
• 添加注释：逐行注释所选的 Python 代码。
• 解释所选文本：将输出面板打开，提供所选代码的详细解释。

这些提示至少需要一个接受 text 作为输入的端点。如果您已启用 OpenAI 服务器，则可以将这些提示发送到其中。

设置文件中有一个示例提示被注释。这是一个通过微调提示可以实现示例。

{
  // imported or created prompts specifications
  "prompts": [
    {
      // Importing from another prompt
      "import": "python_add_comments",
      // Replacing name, icon and description
      "name": "Add funny comments",
      "icon": "🤣",
      "description": "Add funny comments to selected ${syntax} code.",
      // The generated text now adds an instruction to get funny
      "vars": {
        "text": [
          "Comment the lines to the following ${syntax} code following theses rules:",
          "* Return only the edited ${syntax} code.",
          "* Do not alter the code.",
          "* All comments must be written in a funny style, addressed to my future me.",
          "",
          "${text}",
        ],
      },
    },
  ]
}

Gitea

提供了两个由 Gitea 规范提供的带有（提示链）的提示

• 获取存储库数据：它设置为 可见：false，因为它是用来收集可用存储库列表的。
• 发布问题：这个提示需要一个作为将要创建问题的存储库全名的输入。为了选择存储库，首先调用了之前的提示。这演示了提示如何链接起来。

主要用途是选择一个文本并调用 AssitantAI 创建 Gitea 的问题。然后提供一系列存储库。在选择了目标存储库后，会要求用户提供标题和正文，然后创建问题。

由于 Gitea 的 API 与 GitHub、GitLab 以及类似的服务相似，因此现在为其他提供者实施相同的流程应相对容易。欢迎贡献力量！

添加服务器和提示

您可以使用 JSON 设置添加自己的服务器（例如： 设置 > … > AssistantAI > 设置），但预期用途是安装提供复杂且可重用服务器和提示规范的 Sublime Text 插件。

应该编写更好的文档以支持潜在的贡献者。

理解概念

此插件使用 3 种类型的规范。

• 服务器，包含嵌套端点
• 凭据
• 提示，包含嵌套提示输入

服务器

服务器是一个 JSON 规范，其中包括 URL、所需的头和所需的凭据键，以及一组端点。

{
  "id": "openai",
  "name": "OpenAI",
  "url": "https://api.openai.com:443",
  "timeout": 60,
  "required_credentials": ["api_key"],
  "headers": {
    "Authorization": "Bearer ${api_key}",
    "Content-Type": "application/json",
    "cache-control": "no-cache",
  },
  "endpoints": { ... }
},

如果服务器指定了一个所需的凭据（如本例中的 api_key），而这个凭据未被用户配置，服务器将不可用。任何明确要求此服务器端点的提示都将不可用。

发送到服务器可能包括用户配置的凭据。它们将在 Sublime Text 创建 HTTP 请求时被展开。

服务器端点

请求规范和期望的响应。它包含在服务器规范中的 endpoints 键中。

每个服务器可能提供一个或多个端点。

request 键提供了 AssistantAI 构建并发送到服务器端点的 JSON 对象。

response 指定两个键

• error：用于获取任何错误的键
• output：获取文本的位置（以反斜杠 / 作为分隔符）

{
  "chat_completions": {
    "name": "Chat Completions",
    "method": "POST",
    "resource": "/v1/chat/completions",
    "required_vars": ["text"],
    "valid_params": {
      "model": "string",
      "messages": "string",
      ...
      "user": "string",
    },
    "request": {
      "model": "gpt-3.5-turbo",
      "messages": [
        {
          "role": "user",
          "content": "${text}",
        }
      ],
    },
    "response": {
      "error": "error",
      "output": "choices/0/message/content",
    },
  }
}

凭据

这是端点使用的关键值对。在每个插件设置文件中配置。

如果您安装了 AssistantAI 并打算使用 OpenAI API，您将需要设置此

{
  "credentials": {
    "server_id": {
      "api_key": "sk-..."
    }
  },
}

键 api_key 将在稍后由具有指定 id 的服务器用作变量，该变量将在 HTTP 标头中展开。

每个服务器规范都要求用户在其自定义设置中设置凭据以启用服务器。

提示

提示是配置输入和变量的一组，用于根据用户文本选择和附加输入构建请求。

提示是上下文感知的，考虑了所选文本、可用的前文本和后文本、当前缓冲区的语法以及配置的服务器端点。

如果提示声明需要端点，则只有在该端点可用时才显示该提示。

同样，如果提示声明适用于 python 语法，则只有在编辑 Python 文件时才显示。

当提示需要 text 输入而没有做出选择时，此提示将不会显示。

{
  "id": "continue_selected_text",
  "name": "Continue selected text",
  "description": "Given a selected text, continue writing from there.",
  "required_inputs": ["text"],
  "required_endpoints": [
    "openai/completions",
    "openai/chat_completions"
  ],
  "params": {
    "temperature": 1.0,
    "max_tokens": 1800,
  },
  "command": "append",
}

提示命令

执行提示并获得响应后，将根据提示规范执行命令。

命令可以是：

• replace 替换整个选择
• append 在选择末尾追加
• prepend 在选择开头追加
• insert 替换占位符
• output 向新的输出（底部）面板
• create 使用响应创建新的缓冲区

贡献

如果您想贡献，请随意打开一个 Issue 或发送您的 PR。

有四种类型的宝贵贡献

• 通过打开包含错误报告和功能请求的 Issues 来分享您的经验和创造力。
• 发送 PR 来改进或修复代码。理想情况下，作为对开放问题的响应。
• 添加服务器、提示，提供特定的和可工作的 assistant_ai_{NAME}.sublime-settings 文件。理想情况下使用 PR。
• 开发 Sublime Text 插件（或更新您当前的插件），该插件提供 assistant_ai_{NAME}.sublime-settings。

例如，assistant_ai_{NAME}.sublime-settings 的文件请检查 OpenAI 设置 和 Gitea 设置，这些文件包括提示和服务器端点规范，消耗了 AssistantAI 实现的几乎所有 API。

代码现在非常整洁。但还有一些缺少的功能，如

• 为 AssistantAI 插件开发者提供适当的文档
• 测试除 4143 macOS 之外的其他 Sublime Text 版本
• 实现 Markdown、Java、Rust 等... 的超级酷提示
• 支持多选择
• 在提示上下文中提供当前 Git 仓库信息
• 添加对 Todoist API 的支持以根据所选文本创建任务
• 添加对 GitHub 的支持
• 添加对 GitLab 的支持
• 添加对 Dalai 的支持
• 添加对 🤗 Hugginface 的支持
• 实现其他插件如 Gitea 和类似的插件以与其 API 交互。（已完成）
• 服务器规范中的导入语句（已完成）
• 改进快速面板输入（已完成）
• 服务器和提示的 JSON 模式（已忽略）

许可

本软件遵循MIT许可协议发布。

免责声明

这是我的第一个Sublime Text插件，可能充满了bug。

此插件的设置比较复杂。一旦正确设置，使用方式就非常直接。良好的文档对于提高接受度至关重要。

联系方式

我的Twitter账号是@kanutron，尽管我那里不是特别活跃，但我仍然会在私信中收到通知。

鸣谢

我通过以下方式学习编写Sublime Text插件：

• 阅读来自CodexAI插件的代码（来自OpenAI）
• 阅读https://github.com/yaroslavyaroslav/OpenAI-sublime-text/tree/master的代码
• 与ChatGPT交互（使用这个插件！）
• 阅读来自Sublime API参考和Package Control文档的文档。