Codex CLI - 自然语言命令行界面

该项目使用 GPT-3 Codex 将自然语言命令转换为 PowerShell、Z shell 和 Bash 中的命令。

命令行界面（CLI）是我们最早用于与机器交互的主要用户界面。它功能强大，几乎可以完成任何任务，但要求用户以极其精确的方式表达意图。用户需要 掌握计算机的语言。

随着大型语言模型（LLMs）的出现，尤其是那些经过代码训练的模型，现在可以使用自然语言（NL）与命令行界面进行交互。实际上，这些模型对自然语言和代码的理解都足够好，能够实现两者之间的翻译。

本项目旨在提供跨 Shell 的自然语言到代码的体验，让用户能够用自然语言与他们喜欢的命令行界面互动。用户输入一个命令，比如“我的 IP 地址是多少”，然后按下 Ctrl + G，就会得到一条针对当前 Shell 的惯用命令建议。该项目直接使用了 GPT-3 Codex 模型，这意味着该模型并未专门针对此任务进行过训练。相反，我们依靠一种称为提示工程的技术（见下文 [提示工程与上下文文件] 部分），来引导 Codex 生成正确的命令。

注意：该模型仍可能出错！如果您不理解某个命令，请不要执行它。如果您不确定某个命令的作用，请按 Ctrl + C 取消执行。

该项目在技术上受到了 zsh_codex 项目的启发，并扩展了其功能，使其能够支持多种 Shell，同时还可以自定义传递给模型的提示（详见下方的提示工程部分）。

项目目的

本仓库旨在通过提供一个实现示例以及相关参考资料，帮助大家更好地理解如何在应用程序中使用 Codex，并为 2022 年微软 Build 大会 提供支持。本项目并非计划发布的正式产品。因此，本仓库不用于讨论 OpenAI API 或请求新功能。

系统要求

• Python 3.7.1+
  • [Windows]: Python 已添加到系统 PATH。
• 一个 OpenAI 账户
  • OpenAI API 密钥。
  • OpenAI 组织 ID。如果您有多个组织，请在获取组织 ID 之前，将您的 默认组织 设置为拥有 Codex 引擎访问权限的组织。
  • OpenAI 引擎 ID。它提供了对特定模型的访问权限。例如，code-davinci-002 或 code-cushman-001。有关可用引擎的信息，请参阅 此处。

安装

请按照 此处 的说明，为 PowerShell、Bash 或 Z shell 进行安装。

使用方法

配置好您偏好的 Shell 后，您可以通过在 Shell 中输入以 # 开头的注释，然后按下 Ctrl + G 来使用 Codex CLI。

Codex CLI 支持两种主要模式：单轮对话和多轮对话。

默认情况下，多轮对话模式是关闭的。您可以通过输入 # start multi-turn 和 # stop multi-turn 命令来切换该模式。

如果启用多轮对话模式，Codex CLI 会“记住”与模型之前的交互记录，允许您引用之前的操作和实体。例如，如果您让 Codex CLI 将时区更改为山地时间，然后又说“把它改回太平洋时间”，模型会根据之前的交互内容知道这里的“它”指的是用户的时区：

# 将我的时区更改为山地时间
tzutil /s "Mountain Standard Time"

# 把它改回太平洋时间
tzutil /s "Pacific Standard Time"

该工具会创建一个 current_context.txt 文件来记录过去的交互，并在每次后续命令时将其传递给模型。

当多轮对话模式关闭时，该工具不会保留交互历史。使用多轮模式有利有弊——虽然它可以实现强大的上下文解析能力，但也增加了额外的开销。例如，如果模型生成了错误的脚本，用户就需要从上下文中移除该脚本，否则未来的对话很可能会再次生成错误的脚本。而在多轮模式关闭的情况下，模型的行为将是完全确定性的——相同的命令总是会产生相同的结果。

每当模型似乎持续输出错误的命令时，您可以使用 # stop multi-turn 命令来停止模型记住之前的交互，并加载默认的上下文。或者，您也可以使用 # default context 命令，在保持多轮模式开启的同时达到同样的效果。

命令列表

命令	描述
start multi-turn	开启多轮对话模式
stop multi-turn	关闭多轮对话模式并加载默认上下文
load context <filename>	从 contexts 文件夹加载指定的上下文文件
default context	加载默认的 Shell 上下文
view context	在文本编辑器中打开上下文文件
save context <filename>	将上下文文件保存到 contexts 文件夹；若未指定文件名，则使用当前日期和时间作为文件名
show config	显示当前与模型交互的配置
set <config-key> <config-value>	设置与模型交互的配置

您可以使用 set 命令调整令牌限制、引擎 ID 和温度等参数，以优化使用体验。例如，# set engine cushman-codex、# set temperature 0.5、# set max_tokens 50。

提示工程与上下文文件

本项目采用一种称为“提示工程”的技术，引导 GPT-3 Codex 根据自然语言生成命令。具体来说，我们会向模型提供一系列自然语言到命令的示例，以便它了解应该生成哪种类型的代码，并促使它生成符合您当前 Shell 习惯的命令。这些示例存储在 contexts 目录中。以下是 PowerShell 上下文的一个片段：

# 纽约的天气怎么样？
(Invoke-WebRequest -uri "wttr.in/NewYork").Content

# 创建一个包含 node_modules 和 src 的 .gitignore 文件
"node_modules
src" | Out-File .gitignore

# 在记事本中打开它
notepad .gitignore

请注意，该项目将自然语言命令建模为注释，并提供了我们期望模型编写的 PowerShell 脚本示例。这些示例包括单行补全、多行补全以及多轮补全（“在记事本中打开它”的例子指的是上一轮生成的 .gitignore 文件）。

当用户输入一条新命令（例如“我的 IP 地址是多少”）时，我们会简单地将该命令作为注释追加到上下文中，并让 Codex 生成接下来应该执行的代码。通过查看上述示例，Codex 就会知道应该编写一段满足该注释要求的简短 PowerShell 脚本。

构建您自己的上下文

本项目预装了适用于每种 Shell 的上下文，以及一些具有其他功能的附加上下文。除此之外，您还可以构建自己的上下文，以引导模型产生您期望的行为。例如，如果您希望 Codex CLI 生成 Kubernetes 脚本，您可以创建一个新的上下文，其中包含命令示例以及模型可能生成的 kubectl 脚本：

# 创建一个名为 my-cs 的 K8s 集群 IP，运行在 5678:8080 端口
kubectl create service clusterip my-cs --tcp=5678:8080

将您的上下文添加到 contexts 文件夹中，并运行 load context <filename> 来加载它。您也可以在 src\prompt_file.py 中更改默认上下文文件。

需要注意的是，Codex 经常能够在没有任何示例的情况下生成正确的脚本。由于它接受了大量代码语料的训练，通常能够知道如何生成特定的命令。不过，构建您自己的上下文有助于引导模型生成您所期望的特定类型脚本——无论是长脚本还是短脚本，是否声明变量，是否引用之前的命令等。您还可以提供自己 CLI 命令和脚本的示例，以向 Codex 展示它应该考虑使用的其他工具。

需要特别注意的一点是，如果您添加了一个新的上下文，请保持多轮模式开启，以避免自动回退到默认设置（这一机制是为了防止错误的上下文破坏您的使用体验而引入的）。

我们还添加了一个 认知服务上下文，该上下文使用认知服务 API 提供文本转语音类型的响应作为示例。

故障排除

使用 DEBUG_MODE 可以使用终端输入代替标准输入，并调试代码。这在添加新命令以及理解工具为何无响应时非常有用。

有时，openai 包会抛出工具无法捕获的错误。您可以在 codex_query.py 文件末尾添加一个捕获块来处理此类异常，并打印自定义错误信息。

常见问题解答

我可以使用哪些 OpenAI 引擎？

根据您的 OpenAI 组织，您可能可以访问不同的 OpenAI 引擎。要检查您可用的引擎，可以查询 列出引擎的 API 获取可用引擎列表。以下是相关命令：

• Shell

  curl https://api.openai.com/v1/engines \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'OpenAI-Organization: YOUR_ORG_ID'
  

• PowerShell

  PowerShell v5（Windows 自带的默认版本）

  (Invoke-WebRequest -Uri https://api.openai.com/v1/engines -Headers @{"Authorization" = "Bearer YOUR_API_KEY"; "OpenAI-Organization" = "YOUR_ORG_ID"}).Content
  

  PowerShell v7

  (Invoke-WebRequest -Uri https://api.openai.com/v1/engines -Authentication Bearer -Token (ConvertTo-SecureString "YOUR_API_KEY" -AsPlainText -Force) -Headers @{"OpenAI-Organization" = "YOUR_ORG_ID"}).Content
  

我能在 Azure 上运行这个示例吗？

目前，该示例代码可以与 OpenAI 的 API 上的 Codex 一起使用。在未来几个月内，该示例将会更新，以便您也可以将其与 Azure OpenAI 服务 一起使用。

Codex-CLI 快速上手指南

Codex-CLI 是一个基于 GPT-3 Codex 模型的命令行工具，允许用户使用自然语言（如中文或英文描述）生成 PowerShell、Zsh 或 Bash 命令。它通过提示工程（Prompt Engineering）将用户的意图转化为对应 Shell 的标准命令。

⚠️ 重要安全提示：模型生成的命令可能出错。在执行任何命令前，请务必确认其含义。若不确定，请按 Ctrl + C 取消执行。

环境准备

在开始之前，请确保您的系统满足以下要求：

1. 系统依赖

• Python: 版本需为 3.7.1 或更高。
  • Windows 用户：安装时请勾选 "Add Python to PATH"。
• Shell 环境: 支持 PowerShell、Bash 或 Zsh。

2. OpenAI 账号配置

您需要拥有访问 Codex 模型的 OpenAI 账号，并准备以下信息：

• OpenAI API Key: 获取地址
• Organization ID: 获取地址
  • 注意：如果您有多个组织，请确保默认组织已启用 Codex 引擎访问权限。
• Engine ID: 模型引擎标识符（例如 code-davinci-002 或 code-cushman-001）。
  • 检查可用引擎：可使用以下命令查看您账号下可用的引擎：

  curl https://api.openai.com/v1/engines \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'OpenAI-Organization: YOUR_ORG_ID'
  

安装步骤

本项目未直接提供 PyPI 包，需从源码安装并配置特定 Shell。

1. 克隆项目代码

   git clone <repository-url>
   cd <repository-directory>
   

   (注：请将 <repository-url> 替换为实际的项目仓库地址)

2. 安装 Python 依赖

   pip install -r requirements.txt
   

   (国内用户如遇下载慢，可添加镜像源：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple)

3. 配置 Shell 根据您使用的 Shell 类型，运行对应的安装脚本（具体脚本名称请参考项目根目录下的 Installation.md 文件）：

   • PowerShell: 运行安装脚本以注册快捷键和函数。
   • Bash/Zsh: 运行安装脚本并将配置添加到 ~/.bashrc 或 ~/.zshrc。

4. 配置凭证 在项目目录或指定配置文件中填入您的 API_KEY、ORG_ID 和 ENGINE_ID。

基本使用

配置完成后，重启终端即可使用。Codex-CLI 的核心交互逻辑是：输入注释 -> 触发转换 -> 审查执行。

1. 基础命令生成

在命令行中输入以 # 开头的自然语言描述，然后按下 Ctrl + G。

示例场景：查询本机 IP 地址

1. 在终端输入：

   # what's my IP address
   

2. 按下 Ctrl + G。
3. 工具会自动调用 Codex 模型，并在下方生成对应的 Shell 命令（例如）：

   # what's my IP address
   ip addr show | grep inet | grep -v inet6
   

4. 审查生成的命令，确认无误后按 Enter 执行；若不想执行，可按 Ctrl + C 清除。

2. 多轮对话模式（Multi-turn Mode）

默认情况下，多轮模式关闭。开启后，工具会记住上下文，允许您使用代词（如“它”）进行连续操作。

• 开启多轮模式：

  # start multi-turn
  

• 使用示例：

  # change my timezone to mountain
  tzutil /s "Mountain Standard Time"
  
  # change it back to pacific
  tzutil /s "Pacific Standard Time"
  

  (在第二句中，模型能理解 "it" 指的是时区设置)

• 关闭多轮模式（重置上下文）：

  # stop multi-turn
  

3. 常用控制命令

您可以在注释中使用以下命令管理上下文和配置：

命令	说明
# start multi-turn	开启多轮对话上下文记忆
# stop multi-turn	关闭多轮对话并加载默认上下文
# default context	重新加载默认 Shell 上下文（保留多轮模式状态）
# set engine <id>	切换模型引擎，例如 # set engine code-cushman-001
# set temperature <val>	调整生成随机性 (0-1)，例如 # set temperature 0.5

4. 自定义上下文 (进阶)

您可以创建自己的上下文文件来引导模型生成特定风格的代码（如 Kubernetes 脚本）。

1. 在 contexts 文件夹中创建新文件，包含自然语言到代码的示例对。
2. 加载自定义上下文：

   # load context <filename>