---
name: external-integration
description: 外部CLI工具整合指南 - 为什么和如何整合第三方工具
category: guide
version: 1.0.0
---

# 外部工具整合指南

## 核心理念：不要重复造轮子

**关键洞见**：我们的工具装备系统**不排斥**使用优秀的第三方CLI工具。事实上，**整合**这些工具比重新创建它们更明智。

## 为什么整合外部工具？

### 1. 成熟稳定
工具如 `fzf`, `eza`, `fd`, `bat`, `ripgrep` 等经过：
- **数千小时**的社区打磨
- **复杂场景**的实战测试
- **性能优化**到极致
- **跨平台**兼容性验证

### 2. 社区支持
- **庞大的用户群**: 数万到数十万用户
- **完善的文档**: README、教程、博客文章、视频
- **活跃的维护**: 定期更新、bug修复、新功能
- **丰富的生态**: 插件、扩展、集成方案

### 3. 专注专业
**Unix哲学**: 每个工具只做一件事，做到极致
- **fzf**: 模糊查找，不搞别的
- **eza**: 文件列表，专注显示
- **bat**: 文件查看，语法高亮
- **fd**: 文件搜索，快速简单
- **ripgrep**: 代码搜索，极速递归

### 4. 认知卸载
- **直接使用**: 无需重新实现
- **无需维护**: 交给社区维护者
- **最佳实践**: 吸收社区智慧
- **专注核心**: 把精力放在AI Runtime的独特价值上

**类比**：就像人类不会自己打造锤子，而是从五金店购买。

## 推荐的外部工具

### 基础必备（建议全部安装）

| 工具 | 用途 | 关键优势 | 安装难度 |
|-----|-----|---------|--------|
| **fzf** | 模糊查找 | 交互式、快速、易集成 | ⭐⭐⭐⭐⭐ |
| **eza** | 文件列表 | 美观、Git集成、快速 | ⭐⭐⭐⭐⭐ |
| **zoxide** | 目录跳转 | AI驱动、学习路径 | ⭐⭐⭐⭐⭐ |
| **fd** | 文件搜索 | 简单、快速、忽略.gitignore | ⭐⭐⭐⭐⭐ |
| **bat** | 文件查看 | 语法高亮、Git集成 | ⭐⭐⭐⭐⭐ |
| **ripgrep** | 代码搜索 | 极速、递归、Git感知 | ⭐⭐⭐⭐⭐ |
| **jq** | JSON处理 | 命令行处理JSON | ⭐⭐⭐⭐ |

### 进阶推荐（根据需求选择）

| 工具 | 用途 | 适用场景 |
|-----|-----|---------|
| **zellij** | 终端复用 | 替代tmux, 现代体验 |
| **starship** | Shell提示符 | 美观, Git/语言版本显示 |
| **delta** | Git diff美化 | 查看Git变更体验 |
| **xh** | HTTP客户端 | API测试, 替代curl |
| **just** | 任务运行器 | 替代make, 简洁语法 |
| **hyperfine** | 性能基准测试 | 命令性能对比 |

## 整合策略

### 策略1: 直接使用

在AI Runtime脚本中直接调用外部工具：

```bash
# 在 bash/process-logs.sh 中
# 使用 ripgrep 搜索日志
echo "搜索错误..."
rg "ERROR|CRITICAL" /var/log/app/ --no-ignore-vcs -A 2 -B 2

# 使用 bat 显示结果
bat --paging=never /tmp/analysis-result.json
```

### 策略2: 工具检测

在运行时检测工具是否可用：

```python
# 在 discover-toolkit.py 中
import shutil

def check_tools():
    """检测关键外部工具是否安装"""
    tools = ['fzf', 'eza', 'fd', 'bat', 'rg']
    missing = []

    for tool in tools:
        if not shutil.which(tool):
            missing.append(tool)

    if missing:
        print(f"❌ 缺少工具: {', '.join(missing)}")
        print("💡 安装: brew install {' '.join(missing)}")
    else:
        print("✅ 所有关键工具已安装")
```

### 策略3: 交互式增强

使用 fzf 提供交互式体验：

```bash
# 在 runtime-scripts/explore.sh 中
# 使用 fzf 选择文件
FILE=$(fd .py | fzf --preview 'bat --color=always --line-range :50 {}')
echo "处理文件: $FILE"

# 使用 fzf 选择目录
DIR=$(fd --type d | fzf)
cd "$DIR"
```

### 策略4: 优雅降级

工具不存在时的备选方案：

```bash
#!/bin/bash
# script-with-fallback.sh

# 首选使用 eza
if command -v eza &> /dev/null; then
    eza --long --git
# 否则使用 ls
else
    ls -lah
fi
```

## 在ai-runtime中的实际应用

### 示例1: 文件探索

```bash
# runtime-explore.sh

# 1. 使用 fd 查找所有Python文件
FILES=$(fd .py)

# 2. 使用 fzf 交互式选择
FILE=$(echo "$FILES" | fzf \
  --preview 'bat --color=always --line-range :50 {}' \
  --preview-window='right:50%:hidden' \
  --bind='?:toggle-preview')

# 3. 使用 bat 显示文件内容
echo "=== 开始分析: $FILE ==="
bat "$FILE" | head -50
```

### 示例2: 日志分析

```bash
# analyze-logs.sh

# 1. 使用 ripgrep 快速搜索
rg "ERROR|WARN" /var/log/app/ \
  --no-ignore-vcs \
  -A 2 -B 2 \
  --line-number \
  > /tmp/errors.txt

# 2. 使用 bat 美观显示
bat --theme=OneHalfDark /tmp/errors.txt
```

### 示例3: 项目导航

```bash
# smart-navigate.sh

# 使用 zoxide 跳转到最近访问的项目
# 如果 zoxide 可用
if command -v zoxide &> /dev/null; then
    z myproject
else
    # 否则使用 cd
    cd ~/projects/myproject
fi
```

## 安装检查脚本

创建检查脚本，在系统初始化时验证关键工具：

```bash
#!/bin/bash
# check-tools.sh

echo "🔍 检查关键外部工具..."
echo "================================"

TOOLS=("fzf" "eza" "zoxide" "fd" "bat" "rg" "jq")

for tool in "${TOOLS[@]}"; do
    if command -v "$tool" &> /dev/null; then
        echo "✅ $tool 已安装 ($(which $tool))"
    else
        echo "❌ $tool 未安装"

        case $tool in
            fzf)
                echo "   💡 安装: brew install fzf"
                ;;
            eza)
                echo "   💡 安装: brew install eza"
                ;;
            zoxide)
                echo "   💡 安装: curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh"
                ;;
            fd)
                echo "   💡 安装: brew install fd"
                ;;
            bat)
                echo "   💡 安装: brew install bat"
                ;;
            rg)
                echo "   💡 安装: brew install ripgrep"
                ;;
            jq)
                echo "   💡 安装: brew install jq"
                ;;
        esac
    fi
done

echo "================================"
echo "💡 一键安装所有: brew install fzf eza zoxide fd bat ripgrep jq"
```

## 总结

**整合是明智选择**：
✅ 节省开发时间
✅ 利用社区智慧
✅ 专注核心功能
✅ 更好的用户体验

**渐进式策略**：
1. **首先**: 检测工具是否存在
2. **其次**: 优雅降级（如果工具缺失）
3. **再次**: 增强体验（如果工具存在）
4. **最终**: 完全依赖（确信工具已安装）

## 参考资源

- **外部工具完整参考**: `@docs/references/external-tools.md`
- **外部工具详情**: `@docs/tools/external/{tool-name}.md`
- **快速开始**: `@docs/guides/quickstart.md`