Initial commit
This commit is contained in:
Zhongwei Li
261
skills/toolkit/docs/guides/external-integration.md
Normal file
261
skills/toolkit/docs/guides/external-integration.md
Normal file
@@ -0,0 +1,261 @@
|
||||
---
|
||||
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`
|
||||
Reference in New Issue
Block a user