262 lines
6.6 KiB
Markdown
262 lines
6.6 KiB
Markdown
---
|
||
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`
|