wiki

shell-buddy 安装、使用与配置

更新于

以 v0.1.0 为基准，整理 shell-buddy 的平台要求、Shell 初始化、本地与云端模型配置、排错方式及数据边界。

目录

shell-buddy 在原生 Shell 中把自然语言转换成命令建议：行首输入 //，第一次 Enter 回填命令，第二次 Enter 执行。执行前可以继续编辑，命令最终在当前 Shell 中运行。

文中两次回车指普通 Enter 操作；配置终端快捷键后，另有直接接受并提交的路径。

Shell Buddy 吉祥物：芒果黄色的吐舌鬣蜥，带石墨灰背刺和卷尾

本文以 v0.1.0 为基准，核对日期为 2026-10-24。示例和限制对应这一版本，不把之后的 main 分支变化视为已发布能力。

平台与前置条件

  • 发布包：macOS Apple Silicon、macOS Intel、Linux x86_64、Windows x86_64。
  • Shell：Zsh 5.8+；Bash 5+；或 PowerShell 7.4+ 搭配 PSReadLine 2.3.6+。
  • macOS 系统自带的 Bash 版本过旧，需要另外准备 Bash 5+，或直接使用符合要求的 Zsh。
  • 使用发布包不需要 Zig、Python 或 Node.js。使用本地模型则仍需另外准备并启动模型服务。

首版包没有代码签名或公证。安装器会核对同一 Release 的 SHA256SUMS，但这不能替代发布者签名。请从项目仓库下载，并先检查安装脚本；出现系统安全提示时，应先核对来源。安装文档

安装 v0.1.0

macOS 与 Linux

先下载固定版本的脚本，审阅 /tmp/shell-buddy-install.sh 后再运行第二条命令：

curl -fsSL https://raw.githubusercontent.com/zhanbodev/shell-buddy/v0.1.0/install.sh -o /tmp/shell-buddy-install.sh
sh /tmp/shell-buddy-install.sh --version v0.1.0
export PATH="$HOME/.local/bin:$PATH"

可执行文件默认安装到 ~/.local/bin。上面的 PATH 设置只影响当前会话；要长期生效，将对应设置加入所用 Shell 的启动文件，已有相同配置时不要重复添加。

Windows

在 PowerShell 7.4+ 中下载脚本，先审阅 $installer 指向的文件，再运行 pwsh -File：

$installer = Join-Path ([IO.Path]::GetTempPath()) 'shell-buddy-install.ps1'
Invoke-WebRequest https://raw.githubusercontent.com/zhanbodev/shell-buddy/v0.1.0/install.ps1 -OutFile $installer
pwsh -File $installer -Version v0.1.0
$env:PATH = "$env:LOCALAPPDATA\Programs\ShellBuddy\bin;$env:PATH"

默认安装目录为 %LOCALAPPDATA%\Programs\ShellBuddy\bin。这条 PATH 设置同样只影响当前会话；按需在用户 PATH 中保留该目录。

安装器不需要管理员权限，默认还会安装项目字体，但不会修改 PATH、Shell 启动文件、终端设置或模型配置。安装字体也不等于已启用蜥蜴图标。安装脚本说明

接入当前 Shell

只运行与当前 Shell 对应的一条：

Zsh：

eval "$(shell-buddy init zsh)"

Bash：

eval "$(shell-buddy init bash)"

PowerShell：

shell-buddy init powershell | Out-String | Invoke-Expression

确认当前会话正常后，把相应初始化语句放入 ~/.zshrc、交互式 Bash 实际加载的启动文件（通常为 ~/.bashrc）或 PowerShell 的 $PROFILE。不要把其他 Shell 的初始化语句一并复制进去。

这里带 Shell 名称的 init 用于加载集成。下面不带参数的 shell-buddy init 才是模型配置向导。Shell 集成

配置本地或云端模型

运行：

shell-buddy init

向导依次选择 local 或 cloud 配置、Base URL、模型名、API key 和图标。API key 使用隐藏输入，不要把真实密钥写进共享的命令示例、截图或公开配置。

本地模板的 Base URL 是 http://localhost:11434/v1，模型名 YOUR_LOCAL_MODEL 只是占位符，必须换成服务实际提供的模型。向导不会安装或下载模型，也不会启动服务或发出连通性测试请求。没有鉴权的本地服务可留空 API key；已有密钥时，直接回车会保留它。

云端配置同样填写服务商实际提供的 Base URL 和模型名。当前实现要求兼容流式 /chat/completions，会在 Base URL 后追加这一接口路径，并固定发送 reasoning_effort: “none”；服务需要接受这些参数，不能只凭“OpenAI 兼容”就假设一定可用。

查看或切换已配置的模型：

shell-buddy llm
shell-buddy llm local
shell-buddy llm cloud

后两条用于选择对应配置，不是连续运行的安装步骤。切换会通知活跃编辑器，但不会自动从失败的本地服务回退到云端，或反过来回退。配置参考

检查配置与首次生成

先检查程序识别到的配置和集成状态：

shell-buddy doctor

doctor 不等于已经验证模型连通性。可以再做一次显式生成测试，以下示例面向 Zsh：

shell-buddy suggest --shell zsh --intent '查找当前目录的大文件' --generate --timings

使用 Bash 或 PowerShell 时，把 zsh 换成对应的 bash 或 powershell。这条命令只输出建议，不执行，也不写入接受缓存；它会向当前选择的模型服务发送生成请求。

随后在已加载集成的 Shell 行首输入 // 和意图描述。建议完整生成后，先按 Enter 回填，再检查路径、参数和影响范围，确认后第二次按 Enter 执行。命令参考

配置文件、凭据与缓存

配置文件默认位置：

  • macOS/Linux：$XDG_CONFIG_HOME/shell-buddy/config.json；未设置 XDG 路径时为 ~/.config/shell-buddy/config.json。
  • Windows：%USERPROFILE%.config\shell-buddy\config.json，也支持 XDG_CONFIG_HOME。
  • SHELL_BUDDY_CONFIG 可以覆盖配置路径。credentials.json 和 state.json 跟随实际配置目录。

缓存默认位置：

  • macOS/Linux：$XDG_CACHE_HOME/shell-buddy/cache.json，默认 ~/.cache/shell-buddy/cache.json。
  • Windows：%LOCALAPPDATA%\shell-buddy\cache.json。
  • SHELL_BUDDY_CACHE 可以覆盖缓存路径。

凭据保存在明文文件中，不是系统钥匙串。POSIX 使用专用目录 0700 和配置/凭据文件 0600 权限，Windows 使用当前用户 ACL。不要把整个配置目录提交到代码仓库或共享网盘。

配置中的 api_key_env 填环境变量名称，不填密钥内容。该变量优先于已保存密钥；如果显式配置的变量为空或无效，程序会报错，不会悄悄退回保存的密钥。

缓存只收录用户接受的命令，最多 256 条，并按意图、系统、Shell、工作目录、模型配置和输出预算区分。接受只代表回填过命令，不代表命令已执行或执行成功。清理缓存使用：

shell-buddy cache-clear

路径、凭据与缓存参考

常见问题与使用边界

  • 找不到 shell-buddy：先检查安装目录是否进入当前会话 PATH，再重新加载 Shell 集成。
  • // 没有进入建议流程：检查 Shell 版本、对应初始化语句，以及 PowerShell 的 PSReadLine 版本。
  • 模型没有返回：检查所选配置、服务是否运行、模型名、API key 和接口参数支持情况。默认请求超时为 8,000 ms；doctor 通过不等于模型测试通过。
  • 想调整响应：默认输入防抖为 150 ms，max_tokens 默认 2,048，允许 1–32,768。最终命令为单行，最多 4,096 字节；未完成或失败的流式输出不能接受。
  • 图标显示异常：v0.1.0 的 icon 只接受 star 和 lizard，默认 star（✦）。蜥蜴图标需要终端能显示字体中的 U+F5000 字形。此版本没有关闭动画或完全隐藏图标的配置。
  • 没有模型也能使用吗：已有缓存和明确的本地规则仍可命中，但不能据此期待通用离线自然语言生成。

模型请求包含意图描述、操作系统、Shell 类型、当前目录；切换候选时还会带上已有候选。它不会读取并上传项目文件、目录清单、Shell 历史或其他环境变量的值，但使用云端模型时，描述和路径仍会发往所选服务。避免在意图中放入秘密或不适合发给该服务的信息。

shell-buddy 没有安全沙箱，也没有对危险命令进行语义安全审查。两次 Enter 是人工检查的交互安排，不是安全认证。对删除、覆盖、权限和远程操作，仍应先理解命令再执行。这也涉及 使用 AI 时需要保留的工程判断。

以上设置与限制以 v0.1.0 配置参考 和 命令生成实现 为准。