gh-dwsy-ai-runtime-ai-runtime-toolkit/skills/toolkit/docs/references/external-tools.md

name, description

name	description
external-tools-reference	完整的外部CLI工具参考指南 - 包含所有工具的安装、配置和使用示例

外部工具完整参考指南

核心理念: 整合 > 创造

外部CLI工具是成熟的、社区验证的工具，我们不应重新实现，而应直接集成到ai-runtime工具装备系统中。

工具分类

基础必备（所有用户都应安装）

这些工具提供日常开发的核心功能，建议优先安装。

工具	ID	用途	安装难度	推荐度
fzf	EXT-FZF-001	模糊查找和交互	⭐ 简单	⭐⭐⭐⭐⭐
eza	EXT-EZA-001	文件列表（替代ls）	⭐ 简单	⭐⭐⭐⭐⭐
zoxide	EXT-ZOXIDE-001	智能目录跳转	⭐ 简单	⭐⭐⭐⭐⭐
fd	EXT-FD-001	文件搜索（替代find）	⭐ 简单	⭐⭐⭐⭐⭐
bat	EXT-BAT-001	文件查看（替代cat）	⭐ 简单	⭐⭐⭐⭐⭐
ripgrep	EXT-RG-001	代码搜索（替代grep）	⭐ 简单	⭐⭐⭐⭐⭐
starship	EXT-STEAMSHIP-001	Shell提示符	⭐ 简单	⭐⭐⭐⭐

进阶推荐（提升效率）

工具	ID	用途	推荐度
jq	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)

brew install fzf eza zoxide fd bat ripgrep jq just hyperfine git-delta xh

Ubuntu/Debian

# 基础工具
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个）⭐

适合新手，提供基础文件和导航功能：

fzf + eza + zoxide + fd

完整工具箱（10个）⭐⭐

适合日常开发，覆盖90%场景：

fzf + eza + zoxide + fd + bat + ripgrep + starship + jq + xh + delta

终极工具箱（15+个）⭐⭐⭐

适合高级用户和工具链爱好者：

所有上面工具 + zellij + just + hyperfine + procs + ...

整合到ai-runtime

1. 在discover-toolkit.py中添加检测

扩展discover-toolkit.py，使其能够检测系统已安装的CLI工具：

# 在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中

# 使用fzf选择文件
FILE=$(fd .py | fzf --preview 'bat -n --color=always {}')
read_file_content "$FILE"

3. 配置检查

在系统初始化时检查关键工具是否安装：

# 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文档
• eza文档
• zoxide文档
• bat文档
• ripgrep文档
• jq文档

相关文档

• 查看工具详情: @docs/tools/external/fzf.md
• 查看创建工具指南: @docs/guides/creating-tools.md
• 查看工具分类说明: @docs/references/tool-categories.md

---

最后更新: 2025-11-14 下次审查: 2025-12-14 维护者: CodeConscious 状态: Active