Initial commit
This commit is contained in:
Zhongwei Li
194
skills/toolkit/docs/references/external-tools.md
Normal file
194
skills/toolkit/docs/references/external-tools.md
Normal file
@@ -0,0 +1,194 @@
|
||||
---
|
||||
name: external-tools-reference
|
||||
description: 完整的外部CLI工具参考指南 - 包含所有工具的安装、配置和使用示例
|
||||
---
|
||||
|
||||
# 外部工具完整参考指南
|
||||
|
||||
**核心理念**: **整合 > 创造**
|
||||
|
||||
外部CLI工具是**成熟的、社区验证的**工具，我们**不应重新实现**，而应直接集成到ai-runtime工具装备系统中。
|
||||
|
||||
## 工具分类
|
||||
|
||||
### 基础必备（所有用户都应安装）
|
||||
|
||||
这些工具提供**日常开发**的核心功能，建议**优先安装**。
|
||||
|
||||
| 工具 | ID | 用途 | 安装难度 | 推荐度 |
|
||||
|-----|-----|-----|---------|-------|
|
||||
| [fzf](../tools/external/fzf.md) | EXT-FZF-001 | 模糊查找和交互 | ⭐ 简单 | ⭐⭐⭐⭐⭐ |
|
||||
| [eza](../tools/external/eza.md) | EXT-EZA-001 | 文件列表（替代ls） | ⭐ 简单 | ⭐⭐⭐⭐⭐ |
|
||||
| [zoxide](../tools/external/zoxide.md) | EXT-ZOXIDE-001 | 智能目录跳转 | ⭐ 简单 | ⭐⭐⭐⭐⭐ |
|
||||
| [fd](../tools/external/fd.md) | EXT-FD-001 | 文件搜索（替代find） | ⭐ 简单 | ⭐⭐⭐⭐⭐ |
|
||||
| [bat](../tools/external/bat.md) | EXT-BAT-001 | 文件查看（替代cat） | ⭐ 简单 | ⭐⭐⭐⭐⭐ |
|
||||
| [ripgrep](../tools/external/ripgrep.md) | EXT-RG-001 | 代码搜索（替代grep） | ⭐ 简单 | ⭐⭐⭐⭐⭐ |
|
||||
| starship | EXT-STEAMSHIP-001 | Shell提示符 | ⭐ 简单 | ⭐⭐⭐⭐ |
|
||||
|
||||
### 进阶推荐（提升效率）
|
||||
|
||||
| 工具 | ID | 用途 | 推荐度 |
|
||||
|-----|-----|-----|-------|
|
||||
| [jq](../tools/external/jq.md) | EXT-JQ-001 | JSON查询和处理 | ⭐⭐⭐⭐⭐ |
|
||||
| zellij | EXT-ZELLIJ-001 | 终端复用（替代tmux） | ⭐⭐⭐⭐ |
|
||||
| procs | EXT-PROCS-001 | 进程查看（替代ps） | ⭐⭐⭐⭐ |
|
||||
|
||||
### 专家级（特定场景）
|
||||
|
||||
| 工具 | ID | 用途 | 推荐度 |
|
||||
|-----|-----|-----|-------|
|
||||
| just | EXT-JUST-001 | 任务运行器（替代make） | ⭐⭐⭐⭐ |
|
||||
| hyperfine | EXT-HYPERFINE-001 | 性能基准测试 | ⭐⭐⭐⭐ |
|
||||
| delta | EXT-DELTA-001 | Git diff美化 | ⭐⭐⭐⭐ |
|
||||
| xh | EXT-XH-001 | HTTP客户端（替代curl） | ⭐⭐⭐⭐ |
|
||||
|
||||
## 一键安装脚本
|
||||
|
||||
### macOS (使用Homebrew)
|
||||
```bash
|
||||
brew install fzf eza zoxide fd bat ripgrep jq just hyperfine git-delta xh
|
||||
```
|
||||
|
||||
### Ubuntu/Debian
|
||||
```bash
|
||||
# 基础工具
|
||||
sudo apt-get install fzf ripgrep jq
|
||||
|
||||
# eza（需要添加源）
|
||||
sudo apt-get install -y gpg wget
|
||||
wget -qO- https://raw.githubusercontent.com/eza-community/eza/main/deb.asc | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/gierens.gpg
|
||||
echo "deb http://deb.gierens.de stable main" | sudo tee /etc/apt/sources.list.d/gierens.list
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y eza
|
||||
|
||||
# zoxide
|
||||
curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh
|
||||
|
||||
# fd
|
||||
sudo apt-get install fd-find
|
||||
ln -s $(which fdfind) ~/.local/bin/fd
|
||||
|
||||
# bat
|
||||
sudo apt-get install bat
|
||||
|
||||
# just
|
||||
cargo install just
|
||||
|
||||
# hyperfine
|
||||
cargo install hyperfine
|
||||
```
|
||||
|
||||
## 个人工具箱建议
|
||||
|
||||
### 最小工具箱（4个）⭐
|
||||
适合新手，提供基础文件和导航功能：
|
||||
```bash
|
||||
fzf + eza + zoxide + fd
|
||||
```
|
||||
|
||||
### 完整工具箱（10个）⭐⭐
|
||||
适合日常开发，覆盖90%场景：
|
||||
```bash
|
||||
fzf + eza + zoxide + fd + bat + ripgrep + starship + jq + xh + delta
|
||||
```
|
||||
|
||||
### 终极工具箱（15+个）⭐⭐⭐
|
||||
适合高级用户和工具链爱好者：
|
||||
```bash
|
||||
所有上面工具 + zellij + just + hyperfine + procs + ...
|
||||
```
|
||||
|
||||
## 整合到ai-runtime
|
||||
|
||||
### 1. 在discover-toolkit.py中添加检测
|
||||
|
||||
扩展discover-toolkit.py，使其能够检测系统已安装的CLI工具：
|
||||
|
||||
```python
|
||||
# 在discover-toolkit.py中添加
|
||||
EXTERNAL_TOOLS = {
|
||||
'fzf': {'category': 'search', 'priority': 'essential'},
|
||||
'eza': {'category': 'file-listing', 'priority': 'essential'},
|
||||
'zoxide': {'category': 'navigation', 'priority': 'essential'},
|
||||
# ...
|
||||
}
|
||||
|
||||
def detect_external_tools():
|
||||
"""检测已安装的外部工具"""
|
||||
installed = []
|
||||
for tool, meta in EXTERNAL_TOOLS.items():
|
||||
if shutil.which(tool):
|
||||
installed.append({
|
||||
'name': tool,
|
||||
'category': meta['category'],
|
||||
'priority': meta['priority'],
|
||||
'installed': True
|
||||
})
|
||||
return installed
|
||||
```
|
||||
|
||||
### 2. 在脚本中使用
|
||||
|
||||
示例：在runtime-explore.sh中
|
||||
```bash
|
||||
# 使用fzf选择文件
|
||||
FILE=$(fd .py | fzf --preview 'bat -n --color=always {}')
|
||||
read_file_content "$FILE"
|
||||
```
|
||||
|
||||
### 3. 配置检查
|
||||
|
||||
在系统初始化时检查关键工具是否安装：
|
||||
|
||||
```bash
|
||||
# check-tools.sh
|
||||
for tool in fzf eza zoxide fd bat rg jq; do
|
||||
if ! command -v $tool &> /dev/null; then
|
||||
echo "❌ $tool 未安装 - 运行: brew install $tool"
|
||||
else
|
||||
echo "✅ $tool 已安装 ($(which $tool))"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
## 维护策略
|
||||
|
||||
### 定期检查
|
||||
建议**每月**检查一次：
|
||||
- 工具是否有新版本发布
|
||||
- 安全漏洞通告
|
||||
- 社区推荐变化
|
||||
|
||||
### 更新策略
|
||||
|
||||
- **基础工具**（fzf, eza, zoxide, fd）: 建议**始终使用最新版**
|
||||
- **进阶工具**（jq, bat, ripgrep）: 根据**需求更新**
|
||||
- **专家工具**（zellij, just）: 有**新功能**时再更新
|
||||
|
||||
### 废弃管理
|
||||
|
||||
- 记录工具替代关系（如ripgrep → grep）
|
||||
- 在元数据中标记"replaced_by"
|
||||
- 保持向后兼容
|
||||
|
||||
## 参考资源
|
||||
|
||||
- [fzf文档](https://github.com/junegunn/fzf)
|
||||
- [eza文档](https://github.com/eza-community/eza)
|
||||
- [zoxide文档](https://github.com/ajeetdsouza/zoxide)
|
||||
- [bat文档](https://github.com/sharkdp/bat)
|
||||
- [ripgrep文档](https://github.com/BurntSushi/ripgrep)
|
||||
- [jq文档](https://github.com/jqlang/jq)
|
||||
|
||||
## 相关文档
|
||||
|
||||
- 查看工具详情: `@docs/tools/external/fzf.md`
|
||||
- 查看创建工具指南: `@docs/guides/creating-tools.md`
|
||||
- 查看工具分类说明: `@docs/references/tool-categories.md`
|
||||
|
||||
---
|
||||
|
||||
**最后更新**: 2025-11-14
|
||||
**下次审查**: 2025-12-14
|
||||
**维护者**: CodeConscious
|
||||
**状态**: Active
|
||||
Reference in New Issue
Block a user