install-missing-tool

安装缺失的工具

核心规则：绝不自动安装软件。始终先征求用户许可。

当命令因“command not found”“not recognized”或类似错误而失败时，Agent 必须尝试通过包管理器安装缺失的工具，但只能在获得用户明确批准后进行。

适用情形

• Shell 对所需命令返回 command not found / not recognized / no such file or directory
• 脚本或工具需要尚未安装的依赖项
• 缺少某项实用工具导致任务无法执行

以下情况无需使用： 项目中的 Python/Node.js 导入项（应添加到 requirements.txt、package.json 等文件中）。

操作步骤

1. 确定缺失的工具

运行失败的命令，或检查错误消息，以确定所需的确切二进制文件名称。

2. 将工具映射到包名称

使用下表查找正确的软件包。如果未列出该工具，请使用首选包管理器搜索（brew search <tool>、apt search <tool> 等）。

命令	Homebrew	apt（Debian/Ubuntu）	dnf（Fedora/RHEL）	pacman（Arch）	winget（Windows）
jq	jq	jq	jq	jq	jqlang.jq
fzf	fzf	fzf	fzf	fzf	junegunn.fzf
rg (ripgrep)	ripgrep	ripgrep	ripgrep	ripgrep	BurntSushi.ripgrep
fd	fd	fd-find	fd-find	fd	sharkdp.fd
bat	bat	bat	bat	bat	sharkdp.bat
tree	tree	tree	tree	tree	GNUWin32.Tree
httpie	httpie	httpie	httpie	httpie	httpie.httpie
curl	curl	curl	curl	curl	curl.curl
wget	wget	wget	wget	wget	GNU.Wget
tmux	tmux	tmux	tmux	tmux	tmux.tmux
neofetch	neofetch	neofetch	neofetch	neofetch	—
htop	htop	htop	htop	htop	—
yq	yq	yq	yq	yq	—
diff-so-fancy	diff-so-fancy	—	—	—	—
shellcheck	shellcheck	shellcheck	ShellCheck	shellcheck	—
pandoc	pandoc	pandoc	pandoc	pandoc	—

语言专用工具：

工具	包 / 命令
Python 包	uv tool install <package>（首选），或使用 uv add <package> 安装到项目本地
Node.js 包	npm install -g <package>
Rust 工具	cargo install <package>
Go 工具	go install <package>@latest

3. 确定可用的包管理器

按优先顺序检查：

1. Homebrew（brew --version）— macOS 和 Linux
2. 操作系统原生包管理器：
   • Debian/Ubuntu：dpkg --version → apt / apt-get
   • Fedora/RHEL/CentOS：rpm --version → dnf 或 yum
   • Arch/Manjaro：pacman --version → pacman
   • openSUSE：zypper --version → zypper
   • Alpine：apk --version → apk
   • Windows：winget --version → winget，或 choco --version → chocolatey
3. 语言专用： uv --version、npm --version、cargo --version、go version

4. 征求用户许可

此步骤为强制要求，没有例外。

向用户说明：

• 工具名称和包管理器
• 将要运行的确切命令
• 是否需要提升权限（sudo、管理员权限）

I need to install `<tool>` to continue. The command is:
  brew install <package>

This requires user privileges. May I proceed?

如果需要 sudo：

• 请用户自行运行该命令，或
• 询问用户是否愿意提供密码，由你代为运行

未经明确批准，绝不运行安装命令。即使工具看起来“显而易见”，也不行。即使使用 --yes 标志，也不行。

5. 安装工具

获得用户批准后，运行安装命令：

# Homebrew (macOS/Linux)
brew install <package>

# apt (Debian/Ubuntu) — requires sudo
sudo apt install -y <package>

# dnf (Fedora/RHEL) — requires sudo
sudo dnf install -y <package>

# pacman (Arch) — requires sudo
sudo pacman -S <package>

# apk (Alpine) — requires root
apk add <package>

# winget (Windows)
winget install <package>

# chocolatey (Windows, admin)
choco install <package> -y

# Python tools — uv preferred over pip
uv tool install <package>        # global tool (e.g. uv tool install ruff)
uv add <package>                 # project-local dependency

# Node.js tools
npm install -g <package>

# Rust tools
cargo install <package>

# Go tools
go install <package>@latest

6. 验证安装

安装完成后，验证工具是否可用：

<tool> --version
# or
which <tool>

如果验证失败，请检查 PATH 问题或安装错误。

后备方案：自定义脚本

仅当没有包管理器能够提供该工具时：

1. 向用户说明未找到相应的软件包
2. 提议使用自定义安装脚本（下载 + 解压 + 设置 PATH）
3. 运行任何下载或脚本前，先征求用户的明确许可
4. 未经用户审查，绝不运行下载的脚本

注意事项

• 自动安装： 绝不未经询问就安装。务必先询问。
• 优先使用 uv 而非 Pip： 安装 Python 工具时必须优先使用 uv。全局工具使用 uv tool install，项目依赖使用 uv add。只有在 uv 不可用时，才使用 pip install。
• 包名错误： 二进制文件名和包名往往不同（fd-find 与 fd、ripgrep 与 rg）。务必先核实包名。
• 未经询问使用 Sudo： 如果安装需要 sudo，用户必须自行运行，或明确授权你运行。
• 静默失败： 有些包管理器会静默失败，或将软件安装到不在 PATH 中的位置。务必使用 which 或 <tool> --version 进行验证。
• 安装不完整： 如果安装中断，请重新运行安装命令——包管理器会妥善处理这种情况。

验证

安装任何工具后：

which <tool> && <tool> --version

• 工具路径位于用户的 $PATH 中
• 版本命令能正常输出（无错误）
• 工具可在同一 shell 会话中使用