Initial commit

skills/toolkit/external/README.md

@@ -0,0 +1,139 @@
+# 外部工具装备目录 (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` 文件
+✅ **简化维护** - 外部工具不重复文档
+✅ **动态检测** - 实时检测安装状态
+✅ **分类清晰** - 按功能分类，便于查找
+✅ **易于扩展** - 添加新工具只需创建元文件