Skill: cn-big-cabbage/fzf (version 0.1.0)

--- name: fzf description: fzf - 通用命令行模糊查找器 version: 0.1.0 metadata: openclaw: requires: - fzf emoji: 🔍 homepage: https://github.com/junegunn/fzf --- # fzf 通用命令行模糊查找器 ## 技能概述 本技能帮助用户在命令行中高效使用 fzf 进行模糊查找，适用于以下场景： - **文件查找**: 快速模糊搜索目录树中的文件并打开 - **历史命令**: 交互式搜索并重用 Shell 历史命令 - **进程管理**: 模糊搜索并终止进程 - **Git 工作流**: 交互式选择分支、提交、文件差异 - **目录跳转**: 快速切换工作目录 - **管道集成**: 与任何产生文本输出的命令组合使用 **主要特点**: 极速模糊匹配、交互式预览、键绑定丰富、与 Shell 深度集成、可嵌入任意脚本 ## 使用流程 AI 助手将引导你完成以下步骤： 1. 安装 fzf（如未安装） 2. 配置 Shell 集成（键绑定与补全） 3. 学习核心用法与快捷键 4. 结合常用命令构建高效工作流 ## 关键章节导航 - [安装指南](./guides/01-installation.md) - [快速开始](./guides/02-quickstart.md) - [高级用法](./guides/03-advanced-usage.md) - [常见问题](./troubleshooting.md) ## AI 助手能力 当你向 AI 描述查找需求时，AI 会： - 自动检测系统环境并安装 fzf - 根据需求生成最优的 fzf 命令组合 - 配置 Shell 集成以启用快捷键 - 构建带预览的交互式文件/内容浏览器 - 生成可复用的 fzf 函数放入 Shell 配置文件 - 集成 fzf 到 Git、Docker、kubectl 等工作流 - 诊断并修复 fzf 配置问题 ## 核心功能 - 极速模糊匹配（基于 Smith-Waterman 算法的改进） - 支持精确模式（`'word`）、前缀匹配（`^word`）、后缀匹配（`word$`） - 多选模式（`--multi`，Tab 键选择） - 实时预览窗口（`--preview`） - 支持 ANSI 颜色代码 - Shell 集成：`CTRL-T`（文件）、`CTRL-R`（历史）、`ALT-C`（目录） - 自定义按键绑定与动作 - 支持 `fd`、`ripgrep`、`bat` 等现代工具联动 - 支持 Vim/Neovim 插件集成 ## 命令速查表 ### 基础用法 ```bash # 启动交互式文件选择（当前目录递归） fzf # 从标准输入选择 echo -e "foo\nbar\nbaz" | fzf # 选中后执行命令 vim $(fzf) # 多选（Tab 选择，Enter 确认） cat $(fzf --multi) ``` ### 搜索语法 ```bash # 精确匹配（不做模糊） fzf --query "'exact-word" # 多词搜索（空格分隔，AND 逻辑） fzf --query "foo bar" # OR 逻辑 fzf --query "foo | bar" # 前缀匹配 fzf --query "^prefix" # 后缀匹配 fzf --query "suffix$" # 排除匹配（! 取反） fzf --query "!unwanted" ``` ### 预览窗口 ```bash # 预览文件内容 fzf --preview 'cat {}' # 用 bat 高亮预览（推荐） fzf --preview 'bat --color=always {}' # 预览窗口位置与大小 fzf --preview 'cat {}' --preview-window=right:50% # 预览当前行内容 fzf --preview 'echo {}' ``` ### Shell 快捷键（安装 Shell 集成后） ```bash # CTRL-T ：在命令行插入选中的文件路径 # CTRL-R ：搜索并重用历史命令 # ALT-C ：cd 进入选中目录 ``` ### 常用参数 ```bash # 指定初始查询 fzf --query "initial" # 反向显示（列表在上，输入框在下） fzf --reverse # 显示边框 fzf --border # 高度模式（不占满全屏） fzf --height=40% # 不排序（保持输入顺序） fzf --no-sort # 退出码为 0 时清空输出 fzf --exit-0 # 指定分隔符和字段 echo "foo:bar:baz" | fzf --delimiter=: --with-nth=2 ``` ## 安装要求 - macOS / Linux / Windows（WSL 或 Git Bash） - 可选：`fd`（更快的文件查找）、`bat`（语法高亮预览）、`ripgrep`（内容搜索） ## 许可证 MIT License ## 项目链接 - GitHub: https://github.com/junegunn/fzf - Wiki: https://github.com/junegunn/fzf/wiki - 示例脚本: https://github.com/junegunn/fzf/wiki/examples

path: guides/01-installation.md
content: # 安装指南

**适用场景**: 首次使用 fzf，需要在系统上安装并配置 Shell 集成

---

## 一、安装前准备

### 目标

确保系统满足安装条件，并了解安装后的功能范围

### 前置条件

- macOS / Linux / Windows（WSL 或 Git Bash）
- 终端模拟器（Terminal、iTerm2、Windows Terminal 等）
- Shell：bash 3.2+、zsh 5.0+、fish 2.3+、PowerShell 5.1+

### 检查是否已安装

**AI 执行说明**: AI 将自动检查 fzf 是否已存在于系统中

```bash
# 检查 fzf 是否已安装
fzf --version

# 检查 fzf 位置
which fzf
```

**期望结果**:
- 如显示版本号（如 `0.54.0`）则已安装，可跳至 [Shell 集成配置](#四配置-shell-集成)
- 如提示 `command not found`，则继续下面的安装步骤

---

## 二、安装 fzf

### 方法1: 使用 Homebrew 安装（macOS / Linux，推荐）

**AI 执行说明**: AI 可直接执行以下命令完成安装

```bash
# macOS 或 Linux（需先安装 Homebrew）
brew install fzf

# 验证安装
fzf --version
```

**期望结果**:
```
0.54.0 (brew)
```

---

### 方法2: 使用 git 克隆安装（Linux / macOS 通用）

**AI 执行说明**: AI 可自动完成克隆与安装脚本执行

```bash
# 克隆到 ~/.fzf 目录
git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf

# 运行安装脚本（会询问是否配置 Shell 集成）
~/.fzf/install
```

安装脚本会询问三个问题：
- `Do you want to enable fuzzy auto-completion?` → 输入 `y`
- `Do you want to enable key bindings?` → 输入 `y`
- `Do you want to update your shell configuration files?` → 输入 `y`

---

### 方法3: 下载预编译二进制文件

**AI 执行说明**: AI 会根据系统架构自动选择正确版本

```bash
# 查询最新版本
# 访问 https://github.com/junegunn/fzf/releases 下载对应平台的压缩包

# Linux x86_64 示例
curl -LO https://github.com/junegunn/fzf/releases/latest/download/fzf-linux_amd64.tar.gz
tar -xzf fzf-linux_amd64.tar.gz
sudo mv fzf /usr/local/bin/

# macOS Apple Silicon 示例
curl -LO https://github.com/junegunn/fzf/releases/latest/download/fzf-darwin_arm64.tar.gz
tar -xzf fzf-darwin_arm64.tar.gz
sudo mv fzf /usr/local/bin/
```

---

### 方法4: 包管理器安装（Linux 各发行版）

**AI 执行说明**: AI 根据检测到的 Linux 发行版自动选择命令

```bash
# Ubuntu / Debian
sudo apt install fzf

# Fedora / RHEL / CentOS
sudo dnf install fzf

# Arch Linux / Manjaro
sudo pacman -S fzf

# openSUSE
sudo zypper install fzf

# Alpine Linux
sudo apk add fzf

# Nix
nix-env -iA nixpkgs.fzf
```

---

### 方法5: Windows 安装

**Scoop（推荐）**:
```powershell
scoop install fzf
```

**Chocolatey**:
```powershell
choco install fzf
```

**winget**:
```powershell
winget install fzf
```

---

## 三、升级 fzf

```bash
# Homebrew 升级
brew upgrade fzf

# git 安装方式升级
cd ~/.fzf && git pull && ./install

# 查看当前版本
fzf --version
```

---

## 四、配置 Shell 集成

Shell 集成是 fzf 最强大的特性之一，启用后可获得以下快捷键：

| 快捷键 | 功能 |
|--------|------|
| `CTRL-T` | 在命令行光标处插入选中的文件路径 |
| `CTRL-R` | 搜索历史命令并粘贴到命令行 |
| `ALT-C` | cd 进入选中的目录 |

### Bash 配置

**AI 执行说明**: AI 将自动添加以下内容到 ~/.bashrc

```bash
# 添加到 ~/.bashrc
eval "$(fzf --bash)"
```

使配置生效：
```bash
source ~/.bashrc
```

---

### Zsh 配置

**AI 执行说明**: AI 将自动添加以下内容到 ~/.zshrc

```bash
# 添加到 ~/.zshrc
eval "$(fzf --zsh)"
```

使配置生效：
```bash
source ~/.zshrc
```

---

### Fish 配置

```bash
# Fish shell 使用独立脚本方式
# 将以下内容加入 ~/.config/fish/config.fish
fzf --fish | source
```

---

### PowerShell 配置

```powershell
# 添加到 $PROFILE
# PSFzf 模块提供更完整的集成
Install-Module PSFzf -Scope CurrentUser
Import-Module PSFzf
```

---

## 五、安装推荐搭配工具

fzf 与以下工具搭配使用效果更佳：

### bat（带语法高亮的 cat）

```bash
# macOS
brew install bat

# Ubuntu/Debian
sudo apt install bat

# 用于 fzf 预览
fzf --preview 'bat --color=always {}'
```

### fd（更快的 find 替代品）

```bash
# macOS
brew install fd

# Ubuntu/Debian
sudo apt install fd-find

# 设置 fzf 使用 fd 作为文件来源
export FZF_DEFAULT_COMMAND='fd --type f --hidden --follow --exclude .git'
```

### ripgrep（更快的 grep）

```bash
# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# 结合 fzf 实时搜索文件内容
fzf --ansi --disabled --query "" \
    --bind "change:reload:rg --line-number --color=always {q} || true" \
    --delimiter : --preview 'bat --color=always {1} --highlight-line {2}'
```

---

## 六、验证安装

**AI 执行说明**: AI 将依次执行以下验证命令

```bash
# 验证 fzf 版本
fzf --version

# 验证基础功能（按 Esc 退出）
echo -e "apple\nbanana\norange" | fzf

# 验证 Shell 集成（按 CTRL-R 应弹出历史搜索）
# 需要重新打开终端或 source 配置文件

# 测试文件选择（CTRL-T）
# 在命令提示符下按 CTRL-T
```

**成功标志**:
- fzf 版本号正确显示
- 基础模糊查找界面弹出
- CTRL-R 历史搜索可用
- CTRL-T 文件选择可用

---

## 七、常见安装问题

### 问题1: Homebrew 安装后命令未找到

```bash
# 检查 PATH 是否包含 Homebrew bin 目录
echo $PATH | tr ':' '\n' | grep brew

# 手动添加到 PATH（macOS Apple Silicon）
export PATH="/opt/homebrew/bin:$PATH"
```

### 问题2: Shell 集成未生效

```bash
# 检查配置文件是否包含 fzf 初始化
grep -n "fzf" ~/.bashrc ~/.zshrc 2>/dev/null

# 重新加载配置
source ~/.zshrc  # 或 source ~/.bashrc
```

### 问题3: CTRL-T / CTRL-R 无响应

```bash
# 确认 fzf 版本支持 --bash / --zsh 参数（需 0.48.0+）
fzf --version

# 旧版安装方式检查
ls ~/.fzf/shell/
```

---

## 完成确认

### 检查清单

- [ ] fzf 已安装并可执行
- [ ] `fzf --version` 显示正确版本
- [ ] Shell 集成已配置（eval "$(fzf --bash/--zsh)"）
- [ ] CTRL-R 历史搜索可用
- [ ] CTRL-T 文件选择可用
- [ ] （可选）bat、fd、ripgrep 已安装

### 下一步

继续阅读 [快速开始](02-quickstart.md) 学习 fzf 的核心用法


path: guides/02-quickstart.md
content: # 快速开始

**适用场景**: 已安装 fzf，开始学习核心用法，掌握日常工作中最常用的操作

---

## 一、基础交互操作

### 目标

掌握 fzf 的基本界面操作与搜索语法

### 启动 fzf

**AI 执行说明**: AI 可演示 fzf 的基础交互

```bash
# 最简单的启动方式（递归列出当前目录文件）
fzf

# 从标准输入读取候选项
ls /usr/bin | fzf

# 将选中结果传递给命令
cat $(fzf)
vim $(fzf)
```

### 界面说明

fzf 界面由两部分组成：
- **候选列表**（上方）：显示所有候选项，当前选中项高亮
- **输入框**（下方）：实时输入过滤条件

**键盘操作**:

| 按键 | 功能 |
|------|------|
| `↑` / `↓` 或 `CTRL-P` / `CTRL-N` | 上下移动光标 |
| `Enter` | 确认选中 |
| `Esc` 或 `CTRL-C` | 取消退出 |
| `Tab` | 多选模式下切换选中状态 |
| `CTRL-A` | 全选（多选模式） |
| `CTRL-D` | 向下翻页 |
| `CTRL-U` | 向上翻页 |
| `CTRL-/` | 切换预览窗口 |

---

## 二、搜索语法

### 目标

掌握 fzf 的各种搜索模式，精准定位目标

**AI 执行说明**: AI 会根据用户描述自动构建正确的搜索语法

### 模糊搜索（默认）

```bash
# 直接输入字符，fzf 会模糊匹配
# 例如：输入 "vimrc" 可匹配 ".vimrc"、"vim-config" 等
echo -e ".vimrc\nvim-config\nneovim.conf\nbashrc" | fzf
```

### 精确匹配模式

```bash
# 在查询前加单引号 '，强制精确匹配
echo -e "foobar\nfoo bar\nfoo_bar" | fzf --query "'foo bar"
```

### 前缀与后缀匹配

```bash
# ^ 前缀匹配：只匹配以 "foo" 开头的项
echo -e "foobar\nbarfoo\nfoo123" | fzf --query "^foo"

# $ 后缀匹配：只匹配以 ".go" 结尾的项
find . -type f | fzf --query ".go$"
```

### 组合搜索

```bash
# 空格分隔 = AND（必须同时满足）
find . -type f | fzf --query "src .go"

# 管道符 | = OR（满足其一即可）
find . -type f | fzf --query ".go | .ts"

# ! 取反（排除匹配项）
find . -type f | fzf --query "!test"

# 组合示例：在 src 目录下的 Go 文件，但排除测试文件
find . -type f | fzf --query "src .go !_test"
```

---

## 三、Shell 快捷键实战

### CTRL-T：文件路径插入

**场景**: 在命令中需要指定文件路径，但不记得确切路径

```bash
# 在命令提示符下，输入 vim 后按 CTRL-T
vim <CTRL-T>
# → fzf 弹出文件选择界面，选中后路径自动插入命令行
# → 最终变成：vim /path/to/selected/file.txt
```

**AI 执行说明**: AI 会模拟此操作并建议合适的文件

---

### CTRL-R：历史命令搜索

**场景**: 记得曾经执行过某个命令，但不记得完整命令

```bash
# 在命令提示符下按 CTRL-R
# → fzf 弹出历史命令搜索界面
# → 输入关键词（如 "docker run"）筛选历史
# → 选中后命令自动填入命令行
```

**对比默认 CTRL-R**:
- 默认 Shell：只显示最近一条匹配
- fzf 增强：显示所有匹配历史，可交互选择

---

### ALT-C：目录跳转

**场景**: 快速 cd 进入深层目录

```bash
# 在命令提示符下按 ALT-C（macOS 需按 ESC+C 或配置 Option 为 Meta 键）
# → fzf 弹出目录选择界面（仅显示目录）
# → 选中后自动执行 cd 命令
```

---

## 四、常用工作流示例

### 打开文件

```bash
# 在当前目录模糊查找并用 vim 打开
vim $(fzf)

# 使用 bat 预览，用 vim 打开
vim $(fzf --preview 'bat --color=always {}')

# 忽略 .gitignore，搜索所有文件
vim $(git ls-files | fzf)
```

### 查找并 cd 进入目录

```bash
# 查找目录并进入
cd $(find . -type d | fzf)

# 使用 fd 列出目录
cd $(fd --type d | fzf)
```

### 杀死进程

```bash
# 查找进程并 kill
kill -9 $(ps aux | fzf | awk '{print $2}')

# 更友好的版本（只显示进程名和 PID）
kill -9 $(ps -ef | fzf --header-lines=1 | awk '{print $2}')
```

### 搜索并查看 Git 提交

```bash
# 交互式查看 git log
git log --oneline | fzf --preview 'git show --stat $(echo {} | cut -d" " -f1)'

# 签出分支
git branch | fzf | xargs git checkout

# 交互式 git add
git diff --name-only | fzf --multi | xargs git add
```

### 切换 Docker 容器

```bash
# 进入运行中的 Docker 容器
docker exec -it $(docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}' | fzf --header-lines=1 | awk '{print $1}') bash
```

---

## 五、基础参数速查

**AI 执行说明**: AI 会根据使用场景自动选择合适的参数组合

### 显示与布局

```bash
# 反向布局（输入框在上）
fzf --reverse

# 显示边框
fzf --border

# 占用屏幕高度的 40%（而不是全屏）
fzf --height=40%

# 设置提示文字
fzf --prompt="选择文件: "

# 显示匹配信息
fzf --info=inline
```

### 预览窗口

```bash
# 右侧预览，占 50% 宽度
fzf --preview 'cat {}' --preview-window=right:50%

# 下方预览，占 40% 高度
fzf --preview 'cat {}' --preview-window=down:40%

# 预览时显示行号
fzf --preview 'cat -n {}'

# 使用 bat 高亮预览
fzf --preview 'bat --color=always --style=numbers {}'

# 切换预览（按 CTRL-/）
fzf --preview 'bat --color=always {}' --bind 'ctrl-/:toggle-preview'
```

### 初始查询与默认选项

```bash
# 设置初始查询字符串
fzf --query "main.go"

# 设置初始选中项（选中包含 main 的第一项）
fzf --select-1 --query "main"

# 多选模式
fzf --multi

# 设置最多可选数量
fzf --multi=5
```

---

## 六、自定义键绑定入门

**AI 执行说明**: AI 会根据个人工作流定制键绑定

```bash
# 按 CTRL-Y 将选中项复制到剪贴板（macOS）
fzf --bind 'ctrl-y:execute-silent(echo {} | pbcopy)'

# 按 CTRL-E 在编辑器中打开
fzf --bind 'ctrl-e:execute(vim {})'

# 按 Enter 在新 tmux 窗口中打开
fzf --bind 'enter:execute(tmux new-window vim {})'

# F2 切换预览开关
fzf --preview 'cat {}' --bind 'f2:toggle-preview'
```

---

## 七、配置 FZF_DEFAULT_OPTS

通过环境变量持久化默认选项，避免每次手动指定：

**AI 执行说明**: AI 会将以下内容添加到 Shell 配置文件

```bash
# 添加到 ~/.bashrc 或 ~/.zshrc
export FZF_DEFAULT_OPTS='
  --height=40%
  --layout=reverse
  --border
  --info=inline
  --preview "bat --color=always {} 2>/dev/null || cat {}"
  --preview-window=right:50%:hidden
  --bind "ctrl-/:toggle-preview"
  --bind "ctrl-a:select-all"
  --bind "ctrl-d:deselect-all"
'

# 使用 fd 替代 find（更快、尊重 .gitignore）
export FZF_DEFAULT_COMMAND='fd --type f --hidden --follow --exclude .git'

# CTRL-T 使用 fd
export FZF_CTRL_T_COMMAND="$FZF_DEFAULT_COMMAND"

# ALT-C 只列出目录
export FZF_ALT_C_COMMAND='fd --type d --hidden --follow --exclude .git'
```

---

## 完成确认

### 检查清单

- [ ] 能够运行 `fzf` 并使用基础模糊搜索
- [ ] 理解搜索语法（模糊、精确、前/后缀、AND/OR/NOT）
- [ ] 能使用 CTRL-T、CTRL-R、ALT-C 快捷键
- [ ] 能使用 `--preview` 显示文件预览
- [ ] 已配置 `FZF_DEFAULT_OPTS` 优化默认行为

### 下一步

继续阅读 [高级用法](03-advanced-usage.md) 学习脚本集成、自定义函数等进阶技巧


path: guides/03-advanced-usage.md
content: # 高级用法

**适用场景**: 已掌握 fzf 基础操作，希望构建定制化工作流、集成到脚本与工具链

---

## 一、自定义 Shell 函数

### 目标

将常用 fzf 命令封装为 Shell 函数，提升重用性

**AI 执行说明**: AI 可将以下函数自动添加到用户的 Shell 配置文件

### fo：模糊打开文件

```bash
# 模糊搜索文件，用默认编辑器打开
fo() {
  local file
  file=$(fzf --query="$1" --select-1 --exit-0 \
    --preview 'bat --color=always {} 2>/dev/null || cat {}')
  [[ -n "$file" ]] && ${EDITOR:-vim} "$file"
}

# 用法
fo            # 搜索当前目录所有文件
fo "main.go"  # 初始查询为 main.go
```

### fcd：模糊跳转目录

```bash
# 模糊搜索目录并 cd 进入
fcd() {
  local dir
  dir=$(fd --type d --hidden --exclude .git 2>/dev/null | \
    fzf --preview 'ls -la {}' --query="$1") && cd "$dir"
}
```

### fh：增强历史命令搜索

```bash
# 搜索历史命令并执行（而非粘贴到命令行）
fh() {
  local cmd
  cmd=$(history | awk '{$1=""; print $0}' | sort -u | \
    fzf --tac --no-sort --query="$1")
  [[ -n "$cmd" ]] && eval "$cmd"
}
```

### fkill：交互式杀死进程

```bash
# 模糊搜索进程并发送 kill 信号
fkill() {
  local pid
  pid=$(ps -ef | \
    fzf --header-lines=1 --multi \
        --preview 'echo {}' --preview-window=down:3:wrap | \
    awk '{print $2}')
  [[ -n "$pid" ]] && echo "$pid" | xargs kill -${1:-9}
}
```

### fe：在编辑器中打开近期文件

```bash
# 打开最近修改的文件
fe() {
  local file
  file=$(find . -type f -newer ~/.bashrc 2>/dev/null | \
    fzf --preview 'bat --color=always {}')
  [[ -n "$file" ]] && ${EDITOR:-vim} "$file"
}
```

---

## 二、Git 工作流集成

**AI 执行说明**: AI 会将以下 Git 相关函数集成到 Shell 配置文件

### fbr：交互式切换 Git 分支

```bash
# 列出本地分支，预览该分支最近提交，切换选中分支
fbr() {
  local branches branch
  branches=$(git branch -vv) &&
  branch=$(echo "$branches" | \
    fzf --ansi --preview 'git log --oneline --graph --color=always $(echo {} | awk "{print \$1}")' | \
    awk '{print $1}')
  git checkout "$branch"
}

# 包含远程分支
fbrr() {
  local branches branch
  branches=$(git branch --all | grep -v HEAD) &&
  branch=$(echo "$branches" | \
    fzf --preview 'git log --oneline --graph --color=always $(echo {} | sed "s/.* //" | sed "s#remotes/[^/]*/##")' | \
    sed "s/.* //" | sed "s#remotes/[^/]*/##")
  git checkout "$branch"
}
```

### fco：交互式 git checkout 文件

```bash
# 交互式选择已修改文件执行 checkout（撤销修改）
fco() {
  local files
  files=$(git diff --name-only | \
    fzf --multi --preview 'git diff --color=always {}')
  [[ -n "$files" ]] && echo "$files" | xargs git checkout
}
```

### fadd：交互式 git add

```bash
# 交互式选择文件执行 git add
fadd() {
  local files
  files=$(git diff --name-only | \
    fzf --multi \
        --preview 'git diff --color=always {}' \
        --bind 'ctrl-a:select-all')
  [[ -n "$files" ]] && echo "$files" | xargs git add
  git status -s
}
```

### fshow：交互式查看 Git 提交

```bash
# 交互式浏览提交历史，预览 diff
fshow() {
  git log --graph --color=always \
      --format="%C(auto)%h%d %s %C(black)%C(bold)%cr" "$@" |
  fzf --ansi --no-sort --reverse --tiebreak=index \
      --bind "ctrl-m:execute:
                (grep -o '[a-f0-9]\{7\}' | head -1 |
                xargs -I % sh -c 'git show --color=always % | less -R') << 'FZF-EOF'
                {}
FZF-EOF"
}
```

### fstash：交互式 Git Stash 管理

```bash
# 查看 stash 列表，预览内容，弹出选中 stash
fstash() {
  local out q k sha
  while out=$(
    git stash list --pretty="%C(yellow)%h %>(14)%Cgreen%cr %C(blue)%gs" |
    fzf --ansi --no-sort --query="$q" --print-query \
        --expect=ctrl-d,ctrl-b \
        --preview 'git stash show --color=always -p $(echo {} | cut -d" " -f1)'
  ); do
    mapfile -t out <<< "$out"
    q="${out[0]}"
    k="${out[1]}"
    sha="${out[-1]}"
    sha="${sha%% *}"
    [[ -z "$sha" ]] && continue
    if [[ "$k" == 'ctrl-d' ]]; then
      git stash drop "$sha"
    elif [[ "$k" == 'ctrl-b' ]]; then
      git stash branch "stash-$sha" "$sha"
      break
    else
      git stash pop "$sha"
      break
    fi
  done
}
```

---

## 三、实时内容搜索（与 ripgrep 集成）

**AI 执行说明**: AI 会根据搜索需求自动构建 rg+fzf 联动命令

### 实时搜索文件内容

```bash
# 实时搜索文件内容，预览匹配行上下文
# 输入变化时自动重新执行 rg
rg_fzf() {
  fzf --ansi \
      --disabled \
      --query "" \
      --bind "start:reload:rg --line-number --no-heading --color=always --smart-case '' || true" \
      --bind "change:reload:rg --line-number --no-heading --color=always --smart-case {q} || true" \
      --delimiter : \
      --preview 'bat --color=always {1} --highlight-line {2}' \
      --preview-window 'up,60%,border-bottom,+{2}+3/3,~3' \
      --bind "enter:become(${EDITOR:-vim} {1} +{2})"
}
```

### 搜索并跳转到指定行

```bash
# 搜索内容，用 vim 打开并跳转到匹配行
rgf() {
  local result
  result=$(rg --line-number --no-heading --color=always "${1:-.}" |
    fzf --ansi \
        --delimiter : \
        --preview 'bat --color=always {1} --highlight-line {2}' \
        --preview-window 'right:50%,+{2}+3/3')
  if [[ -n "$result" ]]; then
    local file line
    file=$(echo "$result" | cut -d: -f1)
    line=$(echo "$result" | cut -d: -f2)
    ${EDITOR:-vim} "+$line" "$file"
  fi
}
```

---

## 四、Docker 工作流集成

**AI 执行说明**: AI 可生成 Docker + fzf 的便捷函数

### 进入容器

```bash
# 选择运行中的容器并进入
dexec() {
  local cid
  cid=$(docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Image}}\t{{.Status}}" |
    fzf --header-lines=1 \
        --preview 'docker inspect $(echo {} | awk "{print \$1}") | bat -l json --color=always' |
    awk '{print $1}')
  [[ -n "$cid" ]] && docker exec -it "$cid" "${1:-bash}"
}
```

### 查看容器日志

```bash
# 选择容器并实时查看日志
dlogs() {
  local cid
  cid=$(docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Image}}" |
    fzf --header-lines=1 | awk '{print $1}')
  [[ -n "$cid" ]] && docker logs -f "$cid"
}
```

### 停止/删除容器

```bash
# 多选容器并停止
dstop() {
  docker ps --format "table {{.ID}}\t{{.Names}}\t{{.Image}}" |
    fzf --header-lines=1 --multi |
    awk '{print $1}' |
    xargs -r docker stop
}
```

---

## 五、高级界面定制

### 颜色主题配置

```bash
# Catppuccin Mocha 主题
export FZF_DEFAULT_OPTS="$FZF_DEFAULT_OPTS \
  --color=bg+:#313244,bg:#1e1e2e,spinner:#f5e0dc,hl:#f38ba8 \
  --color=fg:#cdd6f4,header:#f38ba8,info:#cba6f7,pointer:#f5e0dc \
  --color=marker:#b4befe,fg+:#cdd6f4,prompt:#cba6f7,hl+:#f38ba8 \
  --color=selected-bg:#45475a"

# Dracula 主题
export FZF_DEFAULT_OPTS="$FZF_DEFAULT_OPTS \
  --color=fg:#f8f8f2,bg:#282a36,hl:#bd93f9 \
  --color=fg+:#f8f8f2,bg+:#44475a,hl+:#bd93f9 \
  --color=info:#ffb86c,prompt:#50fa7b,pointer:#ff79c6 \
  --color=marker:#ff79c6,spinner:#ffb86c,header:#6272a4"
```

### 高级键绑定

```bash
export FZF_DEFAULT_OPTS="$FZF_DEFAULT_OPTS \
  --bind='ctrl-a:select-all' \
  --bind='ctrl-d:deselect-all' \
  --bind='ctrl-/:toggle-preview' \
  --bind='ctrl-y:execute-silent(echo {} | pbcopy)+abort' \
  --bind='ctrl-e:execute(${EDITOR:-vim} {})' \
  --bind='alt-up:preview-page-up' \
  --bind='alt-down:preview-page-down'"
```

### 分隔符与字段选择

```bash
# 只显示第 2、3 字段，但传递完整行
# 适用于处理有结构的输入（如 CSV、日志）
echo -e "id:name:email\n1:alice:[REDACTED_SECRET]\n2:bob:[REDACTED_SECRET]" | \
  fzf --header-lines=1 \
      --delimiter=: \
      --with-nth=2,3

# 自定义显示字段（仅展示，不影响输出）
ps -ef | fzf --header-lines=1 --delimiter=' ' --with-nth=1,8..
```

---

## 六、在脚本中嵌入 fzf

**AI 执行说明**: AI 可根据脚本需求生成对应的 fzf 调用代码

### 返回值处理

```bash
#!/usr/bin/env bash
# 基础选择脚本
select_option() {
  local selected
  selected=$(printf '%s\n' "$@" | fzf --prompt="选择: " --height=10)
  if [[ $? -eq 0 && -n "$selected" ]]; then
    echo "$selected"
    return 0
  fi
  return 1
}

# 使用
choice=$(select_option "option1" "option2" "option3")
if [[ $? -eq 0 ]]; then
  echo "您选择了: $choice"
fi
```

### 批量处理选中文件

```bash
#!/usr/bin/env bash
# 选择多个文件并批量处理
process_files() {
  local files
  mapfile -t files < <(fzf --multi --preview 'cat {}')
  
  if [[ ${#files[@]} -eq 0 ]]; then
    echo "未选择任何文件"
    return 1
  fi
  
  for file in "${files[@]}"; do
    echo "处理: $file"
    # 在此添加处理逻辑
  done
}
```

### 带确认的危险操作

```bash
#!/usr/bin/env bash
# 选择文件后二次确认再删除
safe_delete() {
  local files
  mapfile -t files < <(fzf --multi --prompt="选择要删除的文件: ")
  
  [[ ${#files[@]} -eq 0 ]] && return 0
  
  echo "将删除以下文件："
  printf '  %s\n' "${files[@]}"
  
  local confirm
  confirm=$(echo -e "取消\n确认删除" | fzf --prompt="操作: ")
  
  if [[ "$confirm" == "确认删除" ]]; then
    rm -v "${files[@]}"
  else
    echo "已取消"
  fi
}
```

---

## 七、fzf 与 tmux 集成

```bash
# 使用 fzf-tmux 在 tmux 弹出窗口中打开 fzf（需要 fzf 0.29+）
fzf-tmux -p 80%,80%

# 配置 CTRL-T 使用 tmux 弹出窗口
export FZF_TMUX_OPTS='-p80%,60%'
```

---

## 八、Vim/Neovim 集成

### 使用 fzf.vim 插件

```vim
" 安装（vim-plug 示例）
Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
Plug 'junegunn/fzf.vim'

" 常用命令
:Files          " 模糊查找文件
:GFiles         " git ls-files 查找
:Buffers        " 切换 Buffer
:Lines          " 搜索所有 Buffer 的行
:BLines         " 搜索当前 Buffer 的行
:Rg <pattern>   " 实时内容搜索
:History        " 最近文件/命令历史
:Maps           " 搜索快捷键
:Commands       " 搜索命令
```

---

## 完成确认

### 检查清单

- [ ] 已编写并测试至少 2 个自定义 fzf 函数
- [ ] Git 工作流中能使用 fzf 交互式选择
- [ ] 了解 rg + fzf 实时内容搜索用法
- [ ] 已配置颜色主题和高级键绑定
- [ ] 能在 Shell 脚本中正确嵌入 fzf 并处理返回值

### 参考资源

- [官方 Wiki 示例集合](https://github.com/junegunn/fzf/wiki/examples)
- [fzf.vim 插件文档](https://github.com/junegunn/fzf.vim)
- [awesome-fzf 精选列表](https://github.com/unixorn/fzf-zsh-plugin)


path: troubleshooting.md
content: # 常见问题与解决方案

---

## 问题分类说明

**简单问题（1-2步排查）**：安装配置、基础用法等
**中等问题（3-5步排查）**：Shell 集成、性能优化等
**复杂问题（5-10步排查）**：自定义脚本、环境冲突等

---

## 安装问题

### 1. fzf 安装后命令找不到【简单问题】

**问题描述**: 安装 fzf 后终端提示 command not found

**排查步骤**:
```bash
# 检查 fzf 是否已安装
which fzf
fzf --version

# 检查 PATH
echo $PATH
```

**常见原因**:
- 未将安装目录加入 PATH (40%)
- 使用 git clone 安装但未运行 install 脚本 (35%)
- 终端未重新加载配置 (25%)

**解决方案**:

**方案A（推荐）**: 使用包管理器安装
```bash
# macOS
brew install fzf

# Ubuntu/Debian
sudo apt install fzf

# Arch Linux
sudo pacman -S fzf
```

**方案B**: git clone 安装后运行 install
```bash
git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf
~/.fzf/install
source ~/.bashrc  # 或 source ~/.zshrc
```

---

### 2. Shell 快捷键（Ctrl+R/Ctrl+T）不生效【中等问题】

**问题描述**: 安装 fzf 后 Ctrl+R（历史搜索）和 Ctrl+T（文件搜索）无响应

**排查步骤**:
```bash
# 检查 shell 配置中是否加载了 fzf 绑定
grep -r "fzf" ~/.bashrc ~/.zshrc ~/.config/fish/config.fish 2>/dev/null

# 检查 fzf 快捷键绑定文件是否存在
ls ~/.fzf/shell/ 2>/dev/null || ls /usr/share/fzf/ 2>/dev/null
```

**常见原因**:
- 未 source fzf 的 shell 配置 (40%)
- 安装时选择了不启用快捷键 (30%)
- 与其他插件快捷键冲突 (20%)
- shell 类型不匹配 (10%)

**解决方案**:

**方案A（bash）**: 添加到 .bashrc
```bash
# 将以下行添加到 ~/.bashrc
eval "$(fzf --bash)"
source ~/.bashrc
```

**方案B（zsh）**: 添加到 .zshrc
```bash
# 将以下行添加到 ~/.zshrc
eval "$(fzf --zsh)"
source ~/.zshrc
```

**方案C（fish）**: 添加到 fish config
```fish
# ~/.config/fish/config.fish
fzf --fish | source
```

---

### 3. 安装后 Tab 补全不工作【简单问题】

**问题描述**: fzf 的 `**` Tab 触发补全功能不生效

**排查步骤**:
```bash
# 测试 Tab 补全
cd **<TAB>
vim **<TAB>

# 检查补全脚本是否加载
```

**常见原因**:
- 补全脚本未加载 (50%)
- 使用的 shell 不支持 (25%)
- fzf-completion 文件缺失 (25%)

**解决方案**:

```bash
# 确保 shell 配置中包含补全加载
# bash: eval "$(fzf --bash)" 已包含补全
# zsh: eval "$(fzf --zsh)" 已包含补全

# 重新运行安装脚本并确认启用补全
~/.fzf/install --completion --key-bindings
```

---

## 使用问题

### 4. 中文文件名显示乱码【中等问题】

**问题描述**: fzf 搜索结果中的中文文件名显示为乱码

**排查步骤**:
```bash
# 检查终端编码
echo $LANG
locale

# 检查文件名实际编码
ls | xxd | head
```

**常见原因**:
- 终端编码不是 UTF-8 (50%)
- LANG/LC_ALL 环境变量未设置 (30%)
- 终端模拟器字体不支持中文 (20%)

**解决方案**:

**方案A**: 设置 UTF-8 编码
```bash
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
```

**方案B**: 使用支持 Unicode 的终端
```bash
# 确认终端支持 UTF-8
echo "测试中文" | fzf
```

---

### 5. fzf 搜索速度慢（大目录）【中等问题】

**问题描述**: 在大型项目目录中 fzf 搜索响应缓慢

**排查步骤**:
```bash
# 检查默认搜索命令
echo $FZF_DEFAULT_COMMAND

# 测试文件数量
find . -type f | wc -l

# 检查是否忽略了 .git 等目录
```

**常见原因**:
- 默认 find 命令遍历了 .git/node_modules 等大目录 (45%)
- 未使用更快的搜索工具 (35%)
- 预览功能消耗资源 (20%)

**解决方案**:

**方案A（推荐）**: 使用 fd 替代默认搜索
```bash
# 安装 fd
brew install fd  # macOS

# 设置 FZF_DEFAULT_COMMAND
export FZF_DEFAULT_COMMAND='fd --type f --hidden --follow --exclude .git'
export FZF_CTRL_T_COMMAND="$FZF_DEFAULT_COMMAND"
```

**方案B**: 使用 ripgrep 搜索
```bash
export FZF_DEFAULT_COMMAND='rg --files --hidden --follow --glob "!.git/*"'
```

**方案C**: 配置 .gitignore 过滤
```bash
# fzf 默认会尊重 .gitignore（使用 fd/rg 时）
echo "node_modules/" >> .gitignore
echo ".git/" >> .gitignore
```

---

### 6. 预览窗口不显示内容【中等问题】

**问题描述**: 使用 --preview 选项时预览窗口为空

**排查步骤**:
```bash
# 测试预览命令是否独立可用
bat --version 2>/dev/null || cat --version

# 测试基本预览
fzf --preview 'cat {}'

# 检查预览命令路径
which bat
```

**常见原因**:
- 预览命令（如 bat）未安装 (40%)
- 预览命令路径不在 PATH 中 (25%)
- 文件类型不支持预览 (20%)
- 预览窗口尺寸太小 (15%)

**解决方案**:

**方案A**: 使用 cat 作为基础预览
```bash
fzf --preview 'cat -n {}'
```

**方案B（推荐）**: 安装 bat 实现语法高亮预览
```bash
brew install bat  # macOS
fzf --preview 'bat --style=numbers --color=always {}'
```

**方案C**: 调整预览窗口
```bash
fzf --preview 'cat {}' --preview-window=right:60%:wrap
```

---

## 集成问题

### 7. 与 vim/neovim 集成不生效【中等问题】

**问题描述**: 在 vim 中使用 fzf.vim 插件时报错或无响应

**排查步骤**:
```bash
# 检查 fzf 是否在 vim 的 runtimepath 中
vim -c "echo &rtp" -c "q"

# 检查 fzf.vim 插件是否安装
ls ~/.vim/plugged/fzf.vim 2>/dev/null
```

**常见原因**:
- fzf 未添加到 vim runtimepath (40%)
- fzf.vim 插件未安装 (30%)
- vim 版本过低 (20%)
- 终端不支持 (10%)

**解决方案**:

**方案A（vim-plug）**:
```vim
" ~/.vimrc
Plug 'junegunn/fzf', { 'do': { -> fzf#install() } }
Plug 'junegunn/fzf.vim'
```

**方案B（手动配置）**:
```vim
" 如果使用 Homebrew 安装
set rtp+=/opt/homebrew/opt/fzf
```

---

### 8. tmux 中 fzf 弹出窗口不工作【中等问题】

**问题描述**: 在 tmux 中使用 fzf 的 tmux popup 模式失败

**排查步骤**:
```bash
# 检查 tmux 版本（需要 3.2+）
tmux -V

# 测试 tmux popup
tmux display-popup -E "echo test"
```

**常见原因**:
- tmux 版本低于 3.2 (50%)
- 未设置 FZF_TMUX_OPTS (30%)
- tmux 配置冲突 (20%)

**解决方案**:

**方案A**: 升级 tmux
```bash
brew install tmux  # macOS，确保 >= 3.2
```

**方案B**: 使用 fzf-tmux 脚本
```bash
# 使用 fzf-tmux 替代直接 fzf
echo "hello\nworld" | fzf-tmux -p 80%,60%
```

---

### 9. FZF_DEFAULT_OPTS 配置不生效【简单问题】

**问题描述**: 设置的 FZF_DEFAULT_OPTS 环境变量未被 fzf 读取

**排查步骤**:
```bash
# 检查环境变量是否设置
echo $FZF_DEFAULT_OPTS

# 检查是否在正确的 shell 配置文件中
grep FZF_DEFAULT_OPTS ~/.bashrc ~/.zshrc 2>/dev/null
```

**常见原因**:
- 设置在错误的 shell 配置文件中 (40%)
- 语法错误（引号不匹配）(30%)
- 终端未重新加载配置 (30%)

**解决方案**:

```bash
# 在 ~/.zshrc 或 ~/.bashrc 中设置
export FZF_DEFAULT_OPTS='
  --height=40%
  --layout=reverse
  --border
  --info=inline
  --color=fg:#c0caf5,bg:#1a1b26,hl:#bb9af7
'

# 重新加载
source ~/.zshrc
```

---

### 10. Alt 键快捷键在 macOS 终端不工作【简单问题】

**问题描述**: fzf 的 Alt-C（cd 到目录）在 macOS 默认终端无响应

**排查步骤**:
```bash
# 测试 Alt 键是否发送 ESC 序列
cat -v  # 然后按 Alt+C，查看输出
```

**常见原因**:
- macOS Terminal.app 默认不将 Option 键作为 Meta/Alt (70%)
- iTerm2 未配置 Option as Meta (20%)
- 键位被系统占用 (10%)

**解决方案**:

**方案A（Terminal.app）**: 设置 Option 为 Meta 键
```
终端 → 设置 → 描述文件 → 键盘 → 勾选"将 Option 键用作 Meta 键"
```

**方案B（iTerm2）**: 配置 Option 键
```
iTerm2 → Settings → Profiles → Keys → General → Left Option key → Esc+
```

**方案C**: 使用 ESC 替代 Alt
```bash
# 按 ESC 然后按 C（而非 Alt+C）
```


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)