关于

fish-ai 为 Fish 添加了 AI 功能。 它非常棒！我构建它是为了简化我的生活，也希望它能简化你的生活。 以下是完整的功能介绍：

• 它可以将注释转换为 Shell 命令，反之亦然，这意味着减少了阅读 manpages（手册页）、Google 搜索以及从 Stack Overflow 复制粘贴的时间。在处理 git、kubectl、curl 和其他拥有大量参数和开关的工具时非常有用。
• 打错字了吗？它也可以修复错误的命令（类似于 thefuck）。
• 不确定接下来该输入什么或者只是懒得打字？让 LLM（大型语言模型）配合内置的模糊查找器自动补全你的命令。
• 所有操作均通过两个（可配置的）键盘快捷键完成，无需鼠标！
• 它可以连接到您选择的 LLM（甚至是自托管的！）。
• 整个项目是开源的，希望能做到易于阅读，代码量约 2000 行，这意味着你可以在一个下午内自行审计代码。
• 使用 fisher 轻松安装和更新。
• 已在 macOS 和最常见的 Linux 发行版上测试。
• 不会干扰 fzf.fish、tide 或你正在使用的任何其他插件！
• 不会包装你的 Shell，不会安装遥测，也不会强迫你切换到专有终端模拟器。

此插件最初基于 Tom Dörr 的 fish.codex 仓库。 没有 Tom，这个仓库就不会存在！

如果你喜欢它，请添加一颗 ⭐。

欢迎提交 Bug 修复！我认为该项目已基本功能完备。 在针对功能请求打开 PR 之前，建议先打开一个 Issue，说明你想添加什么以及为什么，我们可以先讨论一下。

🎥 演示

👨‍🔧 如何安装

安装 fish-ai

确保已安装 git 以及 uv，或者支持版本的 Python 以及 pip（包管理器）和 venv（虚拟环境）。 然后使用 fisher 获取插件：

fisher install realiserad/fish-ai

创建配置

创建一个配置文件 $XDG_CONFIG_HOME/fish-ai.ini（如果未设置 $XDG_CONFIG_HOME，则使用 ~/.config/fish-ai.ini），在其中指定 fish-ai 应该与哪个 LLM 通信。 如果你不确定，请使用 GitHub Models。

Anthropic

要使用 Anthropic：

[anthropic]
provider = anthropic
api_key = <your API key>
model = claude-sonnet-4-6

Azure OpenAI

要使用 Azure OpenAI：

[fish-ai]
configuration = azure

[azure]
provider = azure
server = https://<your instance>.openai.azure.com
model = <your deployment name>
api_key = <your API key>

Bedrock

要通过 OpenAI 兼容 API 使用 AWS Bedrock 上的模型：

[fish-ai]
configuration = bedrock

[bedrock]
provider = bedrock
aws_region = us-east-1

如果未配置 api_key，将自动从您的 AWS 凭证（SSO（单点登录）、IAM（身份和访问管理）角色、环境变量等）生成短期令牌。 如果您更喜欢使用 Bedrock API 密钥，也可以直接指定 api_key。

这使用了支持 Bedrock 上所有可用模型的 Bedrock Mantle 网关。 请参阅 支持的区域 以查看可用区域。

Cohere

要使用 Cohere：

[cohere]
provider = cohere
api_key = <your API key>
model = command-a-03-2025

DeepSeek

要使用 DeepSeek：

[deepseek]
provider = deepseek
api_key = <your API key>
model = deepseek-chat

GitHub Models

要使用 GitHub Models：

[fish-ai]
configuration = github

[github]
provider = self-hosted
server = https://models.github.ai/inference
api_key = <paste GitHub PAT here>
model = gpt-4o-mini

你可以在此处创建个人访问令牌 (PAT)。 PAT 不需要任何权限。

Google

要使用来自 Google 的 Gemini：

[google]
provider = google
api_key = <your API key>
model = gemini-3.1-pro-preview

Groq

要使用 Groq：

[groq]
provider = groq
api_key = <your API key>

Mistral

要使用 Mistral：

[fish-ai]
configuration = mistral

[mistral]
provider = mistral
api_key = <your API key>

OpenAI

要使用 OpenAI：

[fish-ai]
configuration = openai

[openai]
provider = openai
model = gpt-4o
api_key = <your API key>
organization = <your organization>

OpenRouter

要使用 OpenRouter：

[fish-ai]
configuration = openrouter

[openrouter]
provider = self-hosted
server = https://openrouter.ai/api/v1
model = google/gemini-3-flash-preview
api_key = <your API key>
extra_body = {"reasoning": {"effort": "minimal", "exclude": true}}

自托管

要使用自托管的 LLM（位于 OpenAI 兼容 API 之后）：

[fish-ai]
configuration = self-hosted

[self-hosted]
provider = self-hosted
server = https://<your server>:<port>/v1
model = <your model>
api_key = <your API key>

如果您选择自托管，我建议使用 Ollama 搭配 Llama 3.3 70B。 运行在 localhost 上的开箱即用配置可能如下所示：

[fish-ai]
configuration = local-llama

[local-llama]
provider = self-hosted
model = llama3.3
server = http://localhost:11434/v1

可用模型列于 此处。

将 API key（API 密钥）放入你的 keyring（密钥环）

不要将 API key 放在配置文件中，你可以让 fish-ai 从你的 keyring 中加载它。要保存新的 API key 或将现有的 API key 转移到你的 keyring，请运行 fish_ai_put_api_key。

🙉 如何使用

将注释转换为命令，反之亦然

输入一个注释（任何以 # 开头的内容），然后按 Ctrl + P 将其转换为 shell 命令！注意，如果你的注释非常简短或模糊，LLM（大型语言模型）可能会决定改进注释而不是提供 shell 命令。这时你需要再次按 Ctrl + P。

你也可以反向操作。输入一个命令并按 Ctrl + P 将其转换为解释该命令作用的注释。

自动补全命令

开始输入你的命令或注释，然后按 Ctrl + Space 在 fzf 中显示补全列表（它随插件捆绑在一起，无需单独安装）。

为了优化结果，在 fzf 内输入一些指令并按 Ctrl + P。

建议修复方案

如果命令失败，你可以在命令提示符处立即按 Ctrl + Space，让 fish-ai 建议修复方案！

🤸 其他选项

你可以通过在 fish-ai.ini 配置文件中添加额外选项来调整 fish-ai 的行为。

更改默认键盘绑定

默认情况下，fish-ai 绑定到 Ctrl + P 和 Ctrl + Space。如果你的系统上存在任何现有键盘绑定的干扰，你可能想要更改此设置。

要更改键盘绑定，请将 keymap_1（默认为 Ctrl + P）和 keymap_2（默认为 Ctrl + Space）设置为你要使用的键盘绑定的转义序列。

要获取正确的键盘绑定转义序列，请使用 fish_key_reader。

例如，如果你有来自 fish_key_reader 的以下输出：

$ fish_key_reader
Press a key:
bind ctrl-p 'do something'
$ fish_key_reader
Press a key:
bind ctrl-space 'do something'

然后将以下内容放入你的配置文件中：

[fish-ai]
keymap_1 = 'ctrl-p'
keymap_2 = 'ctrl-space'

重启 shell 以使更改生效。

用不同语言解释

要用不同的语言解释 shell 命令，请将 language 选项设置为该语言的名称。例如：

[fish-ai]
language = Swedish

只有当你使用的 LLM 是在包含所选语言的数据集上训练时，这才能良好工作。

补全数量

要更改按下 Ctrl + Space 时 LLM 建议的补全数量，请设置 completions 选项。默认值为 5。

以下是如何将补全数量增加到 10 的示例：

[fish-ai]
completions = 10

要更改在 fzf 中按 Ctrl + P 时 LLM 建议的精修补全数量，请设置 refined_completions 选项。默认值为 3。

[fish-ai]
refined_completions = 5

使用命令行历史个性化补全

你可以通过发送命令行历史的片段来个性化 LLM 建议的补全。

要启用它，请使用 history_size 选项指定要从历史记录中发送给 LLM 的最大命令数。默认值为 0（不发送任何命令行历史）。

[fish-ai]
history_size = 5

如果你启用此选项，请考虑使用 sponge 自动从你的命令行历史中删除损坏的命令。

预览管道

要在补全命令时将管道的输出发送给 LLM，请使用 preview_pipe 选项。

[fish-ai]
preview_pipe = True

这将发送光标前最后一个未闭合括号之后最长的连续管道的输出。例如，如果你自动补全 az vm list | jq，az vm list 的输出将被发送给 LLM。

此行为默认禁用，因为它可能会减慢补全过程并导致命令被执行两次。

配置进度指示器

你可以更改插件等待 LLM 响应时显示的进度指示器（默认为 ⏳）。

要更改默认值，请将 progress_indicator 选项设置为零个或多个字符。

[fish-ai]
progress_indicator = wait...

使用自定义标头

你可以使用 headers 选项发送自定义 HTTP 标头。使用逗号分隔的 Key: Value 对指定一个或多个标头。例如：

[fish-ai]
headers = Header-1: value1, Header-2: value2

🎭 在不同上下文之间切换

你可以使用 fish_ai_switch_context 命令在配置的不同部分之间切换。

🐾 数据隐私

使用插件时，fish-ai 会将你的操作系统名称和命令行缓冲区提交给 LLM。

当你将命令代码化或补全命令时，它还会发送你提到的任何文件的内容（只要文件可读），当你解释或补全命令时，<command> --help 的输出会被提供给 LLM 作为参考。

fish-ai 还可以在补全命令时发送你命令行历史的片段。默认情况下这是禁用的。

最后，为了修复之前的命令，之前的命令行缓冲区，以及任何终端输出和相应的退出码都会被发送到 LLM。

如果你关心数据隐私，你应该使用自托管的 LLM。当本地托管时，没有任何数据会离开你的机器。

敏感信息脱敏

插件尝试在向 LLM 提交之前从提示中删除敏感信息。敏感信息会被替换为 <REDACTED> 占位符。

以下信息会被删除：

• 作为命令行参数提供的密码和 API 密钥
• 存储在文件中的 PEM 编码私钥
• 提供给例如 cURL 的 Bearer 令牌

如果你信任 LLM 提供商（例如因为你正在本地托管），你可以使用 redact = False 选项禁用删除功能。

fish-ai 快速上手指南

fish-ai 是一款为 Fish Shell 打造的 AI 功能插件，支持将注释转换为命令、自动补全及修复错误命令。它通过键盘快捷键操作，无需鼠标，并支持多种大语言模型（LLM）。

环境准备

在开始之前，请确保您的系统已安装以下依赖：

• Fish Shell: 必须使用 Fish 作为默认 Shell。
• Git: 用于获取插件代码。
• Python 环境: 需安装 uv 或 Python 3.x 配合 pip 和 venv。
• Fisher: Fish 的插件管理工具。

如果您尚未安装 fisher，请先运行：

curl -sL https://git.io/fisher | source && fisher install jorgebucaran/fisher

安装步骤

1. 安装插件

使用 fisher 安装 fish-ai：

fisher install realiserad/fish-ai

2. 配置 API

创建配置文件以指定使用的 LLM 服务。文件路径通常为 ~/.config/fish-ai.ini（若未设置 $XDG_CONFIG_HOME）。

示例：使用 GitHub Models 如果您不确定使用哪个模型，推荐使用 GitHub Models。请在配置文件中填入您的 Personal Access Token (PAT)：

[fish-ai]
configuration = github

[github]
provider = self-hosted
server = https://models.github.ai/inference
api_key = <paste GitHub PAT here>
model = gpt-4o-mini

注意：您也可以使用 fish_ai_put_api_key 命令将密钥保存到系统钥匙环中，避免明文存储。

基本使用

安装并配置完成后，重启 Fish Shell 即可生效。主要功能通过两个快捷键触发：

1. 注释与命令互转

• 注释转命令：输入一行以 # 开头的注释，按 Ctrl + P。
• 命令转注释：输入一条命令，按 Ctrl + P 生成解释该命令的注释。

2. 智能补全与修复

• 命令补全：输入部分命令或注释后，按 Ctrl + Space 调出补全列表（基于 fzf）。
• 错误修复：当命令执行失败时，直接在提示符下按 Ctrl + Space，AI 将提供修复建议。

---

隐私提示：使用该插件时，您的操作系统名称、命令行缓冲区内容、相关帮助输出及部分历史命令可能会发送至所选的 LLM 服务提供商。