140 lines
4.1 KiB
Markdown
140 lines
4.1 KiB
Markdown
# 外部工具装备目录 (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工具，它们：
|
||
|
||
1. **已预训练** - 大语言模型通常已了解这些常用工具，无需详细文档
|
||
2. **动态帮助** - 可使用 `command --help` 或 `man command` 获取最新信息
|
||
3. **避免重复** - 不重复官方文档，保持元数据简洁
|
||
|
||
### 元数据结构
|
||
|
||
每个外部工具仅需一个 `.meta.yml` 文件，包含：
|
||
|
||
```yaml
|
||
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/` 目录：
|
||
|
||
1. **递归扫描** - 查找所有 `.meta.yml` 文件
|
||
2. **类型过滤** - 只处理 `基本信息.类型 == "external"`
|
||
3. **安装检测** - 使用 `shutil.which()` 检查命令是否可用
|
||
4. **运行时检测** - 每次运行都重新检测，获取最新状态
|
||
|
||
## 使用方式
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
## 新增外部工具
|
||
|
||
添加新外部工具只需：
|
||
|
||
1. 在 `external/<category>/` 创建 `tool-name.meta.yml`
|
||
2. 填写基本信息（ID、名称、命令、类别）
|
||
3. 提供使用场景和快速开始
|
||
4. （可选）添加检测状态占位符
|
||
|
||
无需修改代码，自动检测加载。
|
||
|
||
## 已安装的外部工具
|
||
|
||
当前检测到的外部CLI工具（9个）：
|
||
|
||
- ✅ **fzf** - 模糊查找
|
||
- ✅ **eza** - 现代化ls
|
||
- ✅ **zoxide** - 智能cd
|
||
- ✅ **fd** - 文件搜索
|
||
- ✅ **ripgrep (rg)** - 代码搜索
|
||
- ✅ **bat** - 语法高亮查看器
|
||
- ✅ **jq** - JSON处理器
|
||
- ✅ **xh** - HTTP客户端
|
||
- ✅ **delta** - Git diff美化
|
||
- ❌ **starship** - Shell提示符（未安装）
|
||
|
||
## 优势
|
||
|
||
✅ **统一结构** - 内部/外部工具都使用 `.meta.yml` 文件
|
||
✅ **简化维护** - 外部工具不重复文档
|
||
✅ **动态检测** - 实时检测安装状态
|
||
✅ **分类清晰** - 按功能分类，便于查找
|
||
✅ **易于扩展** - 添加新工具只需创建元文件
|