外部工具装备目录 (External Toolkit)

目录结构

external/
├── search/              # 搜索工具
│   └── fzf.meta.yml     # 模糊查找器
├── navigation/          # 导航工具
│   └── zoxide.meta.yml  # 智能目录跳转
├── file-search/         # 文件搜索工具
│   └── fd.meta.yml      # find替代品
├── code-search/         # 代码搜索工具
│   └── ripgrep.meta.yml # 极速代码搜索
├── file-listing/        # 文件列表工具
│   └── eza.meta.yml     # 现代化ls
├── file-viewer/         # 文件查看工具
│   └── bat.meta.yml     # 语法高亮cat
├── data-processing/     # 数据处理工具
│   └── jq.meta.yml      # JSON处理器
├── api-testing/         # API测试工具
│   └── xh.meta.yml      # HTTP客户端
├── git-tools/           # Git工具
│   └── delta.meta.yml   # diff美化
└── shell-enhancement/   # Shell增强工具
    └── starship.meta.yml # Shell提示符

设计理念

简化元数据

外部工具（如fzf, ripgrep, bat等）是广为人知的CLI工具，它们：

已预训练 - 大语言模型通常已了解这些常用工具，无需详细文档
动态帮助 - 可使用 command --help 或 man command 获取最新信息
避免重复 - 不重复官方文档，保持元数据简洁

元数据结构

每个外部工具仅需一个 .meta.yml 文件，包含：

tool_id: EXT-FZF-001
tool_name: "fzf (Fuzzy Finder)"

基本信息:
  类型: external
  命令: fzf
  类别: search

功能描述:
  简介: "命令行模糊查找器，用于交互式选择"
  详细: "常用工具，支持交互式模糊搜索。使用 'fzf --help' 获取详细信息。"

使用场景:
  - 文件名模糊查找
  - 历史命令搜索

快速开始:
  安装: "brew install fzf"
  帮助命令: "fzf --help"
  常用示例:
    - "find . -type f | fzf"

检测状态:
  已安装: true

与内部工具的区别

特性	内部工具 (Internal)	外部工具 (External)
位置	`bash/`, `python/`, `node/`	`external/`
实现	AI Runtime创建的工具脚本	系统级CLI工具
元数据	详细（包含完整描述、参数、示例）	简化（模型已知工具）
检测	检查工具文件exists	使用 `shutil.which()`
示例	`dependency-analyzer.py`	`fzf`, `ripgrep`, `bat`

检测机制

ExternalToolDetector 扫描 external/ 目录：

递归扫描 - 查找所有 .meta.yml 文件
类型过滤 - 只处理 基本信息.类型 == "external"
安装检测 - 使用 shutil.which() 检查命令是否可用
运行时检测 - 每次运行都重新检测，获取最新状态

使用方式

cd .ai-runtime/toolkit

# 列出所有外部工具
python3 discover-toolkit.py list --external

# 显示外部工具详情
python3 discover-toolkit.py show fzf

# 搜索包含'search'的外部工具
python3 discover-toolkit.py search search --external

# 查看所有工具（内部 + 外部）
python3 discover-toolkit.py list

新增外部工具

添加新外部工具只需：

在 external/<category>/ 创建 tool-name.meta.yml
填写基本信息（ID、名称、命令、类别）
提供使用场景和快速开始
（可选）添加检测状态占位符

无需修改代码，自动检测加载。

已安装的外部工具

当前检测到的外部CLI工具（9个）：

✅ fzf - 模糊查找
✅ eza - 现代化ls
✅ zoxide - 智能cd
✅ fd - 文件搜索
✅ ripgrep (rg) - 代码搜索
✅ bat - 语法高亮查看器
✅ jq - JSON处理器
✅ xh - HTTP客户端
✅ delta - Git diff美化
❌ starship - Shell提示符（未安装）

优势

✅ 统一结构 - 内部/外部工具都使用 .meta.yml 文件 ✅ 简化维护 - 外部工具不重复文档 ✅ 动态检测 - 实时检测安装状态 ✅ 分类清晰 - 按功能分类，便于查找 ✅ 易于扩展 - 添加新工具只需创建元文件

4.1 KiB Raw Permalink Blame History Unescape Escape