wehub-resource-sync
26 KiB
Note
本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
ShellGPT
一款由 AI 大语言模型（LLM）驱动的命令行生产力工具。该命令行工具可高效生成 shell 命令、代码片段、文档，无需借助外部资源（如 Google 搜索）。支持 Linux、macOS、Windows，并兼容 PowerShell、CMD、Bash、Zsh 等所有主流 Shell。
https://github.com/TheR1D/shell_gpt/assets/16740832/721ddb19-97e7-428f-a0ee-107d027ddd59
安装
pip install shell-gpt
默认情况下，ShellGPT 使用 OpenAI 的 API 和 GPT-4 模型。你需要一个 API 密钥，可以在此处. 生成。系统会提示你输入密钥，随后将保存在 ~/.config/shell_gpt/.sgptrc 中。OpenAI API 并非免费，请参阅 OpenAI 定价 了解更多信息。
Tip
或者，你也可以在本地免费运行开源模型。这需要搭建你自己的 LLM 后端，例如 Ollama.。要让 ShellGPT 与 Ollama 配合使用，请按照这份详细的指南 操作。
❗️请注意，ShellGPT 并未针对本地模型进行优化，可能无法按预期工作。
用法
ShellGPT 旨在快速分析和检索信息。它适用于从技术配置到一般常识的各类简单请求。
sgpt "What is the fibonacci sequence"
# -> The Fibonacci sequence is a series of numbers where each number ...
ShellGPT 可同时接受来自 stdin 和命令行参数的提示。无论你希望通过终端管道传入输入，还是直接以参数指定，sgpt 都能满足需求。例如，你可以根据 diff 轻松生成 git 提交信息：
git diff | sgpt "Generate git commit message, for my changes"
# -> Added main feature details into README.md
你还可以通过 stdin 传入日志并附带提示，从而分析来自各种来源的日志。例如，我们可以用它来快速分析日志、识别错误，并获取可能的解决方案建议：
docker logs -n 20 my_app | sgpt "check logs, find errors, provide possible solutions"
Error Detected: Connection timeout at line 7.
Possible Solution: Check network connectivity and firewall settings.
Error Detected: Memory allocation failed at line 12.
Possible Solution: Consider increasing memory allocation or optimizing application memory usage.
你也可以使用各种重定向运算符来传入输入：
sgpt "summarise" < document.txt
# -> The document discusses the impact...
sgpt << EOF
What is the best way to lear Golang?
Provide simple hello world example.
EOF
# -> The best way to learn Golang...
sgpt <<< "What is the best way to learn shell redirects?"
# -> The best way to learn shell redirects is through...
Shell 命令
你是否遇到过忘记常用 shell 命令（例如 find）而需要上网查询语法的情况？借助 --shell 或快捷选项 -s，你可以在终端中快速生成并执行所需命令。
sgpt --shell "find all json files in current folder"
# -> find . -type f -name "*.json"
# -> [E]xecute, [D]escribe, [A]bort: e
Shell GPT 会识别你所使用的操作系统和 $SHELL，并针对你的具体系统提供 shell 命令。例如，如果你让 sgpt 更新系统，它将根据你的操作系统返回相应命令。以下是在 macOS 上的示例：
sgpt -s "update my system"
# -> sudo softwareupdate -i -a
# -> [E]xecute, [D]escribe, [A]bort: e
同样的提示在 Ubuntu 上使用会生成不同的建议：
sgpt -s "update my system"
# -> sudo apt update && sudo apt upgrade -y
# -> [E]xecute, [D]escribe, [A]bort: e
让我们在 Docker 上试试看：
sgpt -s "start nginx container, mount ./index.html"
# -> docker run -d -p 80:80 -v $(pwd)/index.html:/usr/share/nginx/html/index.html nginx
# -> [E]xecute, [D]escribe, [A]bort: e
我们仍可通过管道将输入传给 sgpt 以生成 shell 命令：
sgpt -s "POST localhost with" < data.json
# -> curl -X POST -H "Content-Type: application/json" -d '{"a": 1, "b": 2}' http://localhost
# -> [E]xecute, [D]escribe, [A]bort: e
在提示中运用更多 shell 技巧，本例将文件名传给 ffmpeg：
ls
# -> 1.mp4 2.mp4 3.mp4
sgpt -s "ffmpeg combine $(ls -m) into one video file without audio."
# -> ffmpeg -i 1.mp4 -i 2.mp4 -i 3.mp4 -filter_complex "[0:v] [1:v] [2:v] concat=n=3:v=1 [v]" -map "[v]" out.mp4
# -> [E]xecute, [D]escribe, [A]bort: e
如果你想通过管道传递生成的 shell 命令，可以使用 --no-interaction 选项。这将禁用交互模式，并将生成的命令输出到 stdout。在本例中，我们使用 pbcopy 将生成的命令复制到剪贴板：
sgpt -s "find all json files in current folder" --no-interaction | pbcopy
Shell 集成
这是一项非常实用的功能，让你可以直接在终端中使用 sgpt shell 补全，而无需键入带提示和参数的 sgpt。Shell 集成支持在终端中通过热键使用 ShellGPT，Bash 和 ZSH 均支持。该功能会将 sgpt 补全直接放入终端缓冲区（输入行），便于立即编辑建议的命令。
https://github.com/TheR1D/shell_gpt/assets/16740832/bead0dab-0dd9-436d-88b7-6abfb2c556c1
要安装 shell 集成，请运行 sgpt --install-integration 并重启终端以应用更改。这会在你的 .bashrc 或 .zshrc 文件中添加几行配置。之后，你可以使用 Ctrl+l（默认）调用 ShellGPT。按下 Ctrl+l 时，它会用建议的命令替换你当前的输入行（缓冲区）。你可以随后编辑并按 Enter 执行。
生成代码
使用 --code 或 -c 参数，你可以专门请求纯代码输出，例如：
sgpt --code "solve fizz buzz problem using python"
for i in range(1, 101):
if i % 3 == 0 and i % 5 == 0:
print("FizzBuzz")
elif i % 3 == 0:
print("Fizz")
elif i % 5 == 0:
print("Buzz")
else:
print(i)
由于这是有效的 python 代码，我们可以将输出重定向到文件：
sgpt --code "solve classic fizz buzz problem using Python" > fizz_buzz.py
python fizz_buzz.py
# 1
# 2
# Fizz
# 4
# Buzz
# ...
我们也可以使用管道传入输入：
cat fizz_buzz.py | sgpt --code "Generate comments for each line of my code"
# Loop through numbers 1 to 100
for i in range(1, 101):
# Check if number is divisible by both 3 and 5
if i % 3 == 0 and i % 5 == 0:
# Print "FizzBuzz" if number is divisible by both 3 and 5
print("FizzBuzz")
# Check if number is divisible by 3
elif i % 3 == 0:
# Print "Fizz" if number is divisible by 3
print("Fizz")
# Check if number is divisible by 5
elif i % 5 == 0:
# Print "Buzz" if number is divisible by 5
print("Buzz")
# If number is not divisible by 3 or 5, print the number itself
else:
print(i)
聊天模式
通常，保留并回忆对话很重要。sgpt 会在每次请求的 LLM 补全中创建对话式交流。对话可以逐条展开（chat mode，聊天模式）或在 REPL 循环中交互进行（REPL mode，REPL 模式）。两种方式都依赖同一个底层对象，称为 chat session（聊天会话）。该会话位于可配置的 CHAT_CACHE_PATH。
要开始对话，请使用 --chat 选项，后跟唯一的会话名称和提示。
sgpt --chat conversation_1 "please remember my favorite number: 4"
# -> I will remember that your favorite number is 4.
sgpt --chat conversation_1 "what would be my favorite number + 4?"
# -> Your favorite number is 4, so if we add 4 to it, the result would be 8.
你可以通过 chat session（聊天会话）不断补充细节，迭代改进 GPT 的建议。可使用 --code 或 --shell 选项来启动 --chat：
sgpt --chat conversation_2 --code "make a request to localhost using python"
import requests
response = requests.get('http://localhost')
print(response.text)
为请求添加缓存，可以这样让 LLM 来做：
sgpt --chat conversation_2 --code "add caching"
import requests
from cachecontrol import CacheControl
sess = requests.session()
cached_sess = CacheControl(sess)
response = cached_sess.get('http://localhost')
print(response.text)
Shell 命令同样适用：
sgpt --chat conversation_3 --shell "what is in current folder"
# -> ls
sgpt --chat conversation_3 "Sort by name"
# -> ls | sort
sgpt --chat conversation_3 "Concatenate them using FFMPEG"
# -> ffmpeg -i "concat:$(ls | sort | tr '\n' '|')" -codec copy output.mp4
sgpt --chat conversation_3 "Convert the resulting file into an MP3"
# -> ffmpeg -i output.mp4 -vn -acodec libmp3lame -ac 2 -ab 160k -ar 48000 final_output.mp3
要列出任一对话模式下的所有会话，请使用 --list-chats 或 -lc 选项：
sgpt --list-chats
# .../shell_gpt/chat_cache/conversation_1
# .../shell_gpt/chat_cache/conversation_2
要查看某个会话的全部消息，请使用 --show-chat 选项，后跟会话名称：
sgpt --show-chat conversation_1
# user: please remember my favorite number: 4
# assistant: I will remember that your favorite number is 4.
# user: what would be my favorite number + 4?
# assistant: Your favorite number is 4, so if we add 4 to it, the result would be 8.
REPL 模式
有一种非常方便的 REPL（read–eval–print loop，读-求值-输出循环）模式，可让你与 GPT 模型进行交互式对话。要在 REPL 模式下启动聊天会话，请使用 --repl 选项，后跟唯一的会话名称。你也可以使用 "temp" 作为会话名称来启动临时 REPL 会话。请注意，--chat 与 --repl 使用相同的底层对象，因此你可以用 --chat 启动聊天会话，再用 --repl 在 REPL 模式下继续该对话。
sgpt --repl temp
Entering REPL mode, press Ctrl+C to exit.
>>> What is REPL?
REPL stands for Read-Eval-Print Loop. It is a programming environment ...
>>> How can I use Python with REPL?
To use Python with REPL, you can simply open a terminal or command prompt ...
REPL 模式可与 --shell 和 --code 选项配合使用，非常适合交互式 shell 命令与代码生成：
sgpt --repl temp --shell
Entering shell REPL mode, type [e] to execute commands or press Ctrl+C to exit.
>>> What is in current folder?
ls
>>> Show file sizes
ls -lh
>>> Sort them by file sizes
ls -lhS
>>> e (enter just e to execute commands, or d to describe them)
要提供多行提示，请使用三引号 """：
sgpt --repl temp
Entering REPL mode, press Ctrl+C to exit.
>>> """
... Explain following code:
... import random
... print(random.randint(1, 10))
... """
It is a Python script that uses the random module to generate and print a random integer.
你也可以通过参数、stdin 或同时使用两者传入初始提示来进入 REPL 模式：
sgpt --repl temp < my_app.py
Entering REPL mode, press Ctrl+C to exit.
──────────────────────────────────── Input ────────────────────────────────────
name = input("What is your name?")
print(f"Hello {name}")
───────────────────────────────────────────────────────────────────────────────
>>> What is this code about?
The snippet of code you've provided is written in Python. It prompts the user...
>>> Follow up questions...
Function calling（函数调用）
Function calls 是 OpenAI 提供的一项强大功能。它允许 LLM 在你的系统中执行函数，可用于完成各种任务。要安装 default functions，请运行：
sgpt --install-functions
ShellGPT 提供了便捷的方式来定义和使用函数。要创建自定义函数，请进入 ~/.config/shell_gpt/functions，并以函数名新建一个 .py 文件。在该文件中，可参考此 example. 来定义你的函数。
类内的 docstring 注释会连同 title 属性及参数说明一起，作为函数描述传给 OpenAI API。若 LLM 决定使用你的函数，则会调用 execute 函数。此处我们允许 LLM 在系统中执行任意 Shell 命令。由于我们会返回命令输出，LLM 可以分析该输出并判断是否适合当前提示。以下是 LLM 可能如何执行该函数的示例：
sgpt "What are the files in /tmp folder?"
# -> @FunctionCall execute_shell_command(shell_command="ls /tmp")
# -> The /tmp folder contains the following files and directories:
# -> test.txt
# -> test.json
请注意，若函数 (execute_shell_command) 因某种原因返回错误，LLM 仍可能根据输出尝试完成任务。假设系统中未安装 jq，而我们让 LLM 解析 JSON 文件：
sgpt "parse /tmp/test.json file using jq and return only email value"
# -> @FunctionCall execute_shell_command(shell_command="jq -r '.email' /tmp/test.json")
# -> It appears that jq is not installed on the system. Let me try to install it using brew.
# -> @FunctionCall execute_shell_command(shell_command="brew install jq")
# -> jq has been successfully installed. Let me try to parse the file again.
# -> @FunctionCall execute_shell_command(shell_command="jq -r '.email' /tmp/test.json")
# -> The email value in /tmp/test.json is johndoe@example.
也可以在提示中串联多次 function call（函数调用）：
sgpt "Play music and open hacker news"
# -> @FunctionCall play_music()
# -> @FunctionCall open_url(url="https://news.ycombinator.com")
# -> Music is now playing, and Hacker News has been opened in your browser. Enjoy!
这只是 function call 用法的简单示例。它确实是一项强大功能，可完成各种复杂任务。我们在 GitHub Discussions 设有专门的 category，用于分享和讨论函数。 LLM 可能执行具有破坏性的命令，请自行承担风险❗️
Roles（角色）
ShellGPT 允许你创建自定义角色，可用于生成代码、shell 命令或满足你的特定需求。要创建新角色，请使用 --create-role 选项，后跟角色名称。系统会提示你提供角色描述及其他详细信息。这将在 ~/.config/shell_gpt/roles 中创建一个以角色名命名的 JSON 文件。在该目录中，你也可以编辑默认的 sgpt 角色，例如 shell、code 和 default。使用 --list-roles 选项可列出所有可用角色，使用 --show-role 选项可查看特定角色的详情。以下是自定义角色示例：
sgpt --create-role json_generator
# Enter role description: Provide only valid json as response.
sgpt --role json_generator "random: user, password, email, address"
{
"user": "JohnDoe",
"password": "p@ssw0rd",
"email": "johndoe@example.com",
"address": {
"street": "123 Main St",
"city": "Anytown",
"state": "CA",
"zip": "12345"
}
}
若角色描述中包含 "APPLY MARKDOWN"（区分大小写），则聊天内容将使用 Markdown 格式显示，除非通过 --no-md 显式关闭。
请求缓存
使用 --cache（默认）和 --no-cache 选项来控制缓存。此缓存适用于所有发往 OpenAI API 的 sgpt 请求：
sgpt "what are the colors of a rainbow"
# -> The colors of a rainbow are red, orange, yellow, green, blue, indigo, and violet.
下次遇到完全相同的查询时，将立即从本地缓存获取结果。请注意，sgpt "what are the colors of a rainbow" --temperature 0.5 会发起新请求，因为我们在上一次请求中未提供 --temperature（--top-probability 同理）。
这只是我们使用 OpenAI GPT 模型可以实现的一些示例，相信你能在自己的特定用例中找到它们的用处。
运行时配置文件
你可以在运行时配置文件 ~/.config/shell_gpt/.sgptrc 中设置一些参数：
# API key, also it is possible to define OPENAI_API_KEY env.
OPENAI_API_KEY=your_api_key
# Base URL of the backend server. If "default" URL will be resolved based on --model.
API_BASE_URL=default
# Max amount of cached message per chat session.
CHAT_CACHE_LENGTH=100
# Chat cache folder.
CHAT_CACHE_PATH=/tmp/shell_gpt/chat_cache
# Request cache length (amount).
CACHE_LENGTH=100
# Request cache folder.
CACHE_PATH=/tmp/shell_gpt/cache
# Request timeout in seconds.
REQUEST_TIMEOUT=60
# Default OpenAI model to use.
DEFAULT_MODEL=gpt-5.4-mini
# Default color for shell and code completions.
DEFAULT_COLOR=magenta
# When in --shell mode, default to "Y" for no input.
DEFAULT_EXECUTE_SHELL_CMD=false
# Disable streaming of responses
DISABLE_STREAMING=false
# The pygment theme to view markdown (default/describe role).
CODE_THEME=default
# Path to a directory with functions.
OPENAI_FUNCTIONS_PATH=/Users/user/.config/shell_gpt/functions
# Print output of functions when LLM uses them.
SHOW_FUNCTIONS_OUTPUT=false
# Allows LLM to use functions.
OPENAI_USE_FUNCTIONS=true
# Enforce LiteLLM usage (for local LLMs).
USE_LITELLM=false
# Control how markdown live rendering handles overflow when output exceeds terminal height.
# Possible values: ellipsis, visible, crop
MARKDOWN_LIVE_VERTICAL_OVERFLOW=ellipsis
DEFAULT_COLOR 的可选值：black, red, green, yellow, blue, magenta, cyan, white, bright_black, bright_red, bright_green, bright_yellow, bright_blue, bright_magenta, bright_cyan, bright_white。
CODE_THEME 的可选值：https://pygments.org/styles/
MARKDOWN_LIVE_VERTICAL_OVERFLOW 的可选值：ellipsis、visible、crop。
配置示例
默认行为（省略号）：
MARKDOWN_LIVE_VERTICAL_OVERFLOW=ellipsis
当 Markdown 输出超过终端高度时，仅显示 ...。这是默认行为，可保持向后兼容。
可见模式（推荐用于 REPL 会话）：
MARKDOWN_LIVE_VERTICAL_OVERFLOW=visible
所有生成的 Markdown 内容都会实时可见。这对于长时间运行的 REPL 交互或智能体（agent）工作流尤其有用——你可以观察模型的推理过程、工具调用和中间输出。
sgpt --repl
在 visible 模式下，你可以持续观察生成的 Markdown 输出、工具执行详情和进度更新，而不必盯着 ... 看上好几分钟。
完整参数列表
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────╮
│ prompt [PROMPT] The prompt to generate completions for. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --model TEXT Large language model to use. [default: gpt-5.4-mini] │
│ --temperature FLOAT RANGE [0.0<=x<=2.0] Randomness of generated output. [default: 0.0] │
│ --top-p FLOAT RANGE [0.0<=x<=1.0] Limits highest probable tokens (words). [default: 1.0] │
│ --md --no-md Prettify markdown output. [default: md] │
│ --editor Open $EDITOR to provide a prompt. [default: no-editor] │
│ --cache Cache completion results. [default: cache] │
│ --version Show version. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Assistance Options ─────────────────────────────────────────────────────────────────────────────────────╮
│ --shell -s Generate and execute shell commands. │
│ --interaction --no-interaction Interactive mode for --shell option. [default: interaction] │
│ --describe-shell -d Describe a shell command. │
│ --code -c Generate only code. │
│ --functions --no-functions Allow function calls. [default: functions] │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Chat Options ───────────────────────────────────────────────────────────────────────────────────────────╮
│ --chat TEXT Follow conversation with id, use "temp" for quick session. [default: None] │
│ --repl TEXT Start a REPL (Read–eval–print loop) session. [default: None] │
│ --show-chat TEXT Show all messages from provided chat id. [default: None] │
│ --list-chats -lc List all existing chat ids. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Role Options ───────────────────────────────────────────────────────────────────────────────────────────╮
│ --role TEXT System role for GPT model. [default: None] │
│ --create-role TEXT Create role. [default: None] │
│ --show-role TEXT Show role. [default: None] │
│ --list-roles -lr List roles. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Docker
使用 OPENAI_API_KEY 环境变量运行容器，并用 Docker 卷存储缓存。可根据个人偏好设置环境变量 OS_NAME 和 SHELL_NAME。
docker run --rm \
--env OPENAI_API_KEY=api_key \
--env OS_NAME=$(uname -s) \
--env SHELL_NAME=$(echo $SHELL) \
--volume gpt-cache:/tmp/shell_gpt \
ghcr.io/ther1d/shell_gpt -s "update my system"
使用别名和 OPENAI_API_KEY 环境变量进行对话的示例：
alias sgpt="docker run --rm --volume gpt-cache:/tmp/shell_gpt --env OPENAI_API_KEY --env OS_NAME=$(uname -s) --env SHELL_NAME=$(echo $SHELL) ghcr.io/ther1d/shell_gpt"
export OPENAI_API_KEY="your OPENAI API key"
sgpt --chat rainbow "what are the colors of a rainbow"
sgpt --chat rainbow "inverse the list of your last answer"
sgpt --chat rainbow "translate your last answer in french"
你也可以使用提供的 Dockerfile 来构建自己的镜像：
docker build -t sgpt .