zhongwei/gh-dwsy-ai-runtime-ai-runtime-toolkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:24:37 +08:00
commit 8cd5c7679d
61 changed files with 6788 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

86
skills/toolkit/docs/STRUCTURE-REFACTORING.md Normal file
View File

@@ -0,0 +1,86 @@
# Documentation Restructuring Plan
## Problem
Two documentation files are too large:
- `registry.md`: 1,089 lines
- `EXTERNAL-TOOLS.md`: 547 lines
## Solution
Split into smaller, focused files using `@path/to/file.md` import feature discovered from deepwiki.
## New Structure
### EXTERNAL-TOOLS.md → Split (547 lines)
**Main index**: `EXTERNAL-TOOLS.md` (with @imports)
```
docs/external-tools/
├── 00-index.md # Overview & TOC
├── essential/ # 基础必备（7个工具）
│ ├── fzf.md # 模糊查找
│ ├── eza.md # 文件列表
│ ├── zoxide.md # 目录导航
│ ├── fd.md # 文件搜索
│ ├── bat.md # 文件查看
│ ├── ripgrep.md # 代码搜索
│ └── starship.md # Shell提示符
├── advanced/ # 进阶推荐（3个工具）
│ ├── jq.md # JSON处理
│ ├── zellij.md # 终端复用
│ └── procs.md # 进程查看
└── expert/ # 专家级（2个工具）
├── just.md # 任务运行器
└── hyperfine.md # 性能测试
```
### registry.md → Split (1,089 lines)
**Main index**: `registry.md` (with @imports)
```
docs/registry/
├── 00-overview.md # Philosophy & concepts
├── 01-quickstart.md # Quick start guide
├── 02-tool-categories.md # Category explanations
├── 03-external-integration.md # External tools philosophy
├── 04-creating-tools.md # How to create tools
├── TOC.md # Table of contents
└── internal-tools/ # Individual tool docs
├── service-checker.md
├── dependency-analyzer.md
├── code-stats.md
└── api-tester.md
```
## Implementation Strategy
1. **Phase 1**: Create new `docs/` directory structure
2. **Phase 2**: Split EXTERNAL-TOOLS.md (easier, 547 lines)
3. **Phase 3**: Split registry.md (larger, 1,089 lines)
4. **Phase 4**: Update main index files with @imports
5. **Phase 5**: Test and verify
## Key Benefits
✅ **Better maintainability** - Each tool/file is self-contained
✅ **Faster loading** - AI assistant can load only needed sections
✅ **Easier updates** - Modify individual tools without affecting others
✅ **Clear organization** - Hierarchical structure by category
✅ **Reusable** - Individual tool docs can be referenced elsewhere
## Import Usage Example
New `EXTERNAL-TOOLS.md`:
```markdown
# External Tools
@docs/external-tools/00-index.md
## Essential Tools
@docs/external-tools/essential/fzf.md
@docs/external-tools/essential/eza.md
@docs/external-tools/essential/zoxide.md
# ...etc
```

78
skills/toolkit/docs/concepts/toolkit-philosophy.md Normal file
View File

@@ -0,0 +1,78 @@
---
name: toolkit-philosophy
description: 工具装备系统的核心理念和设计哲学
category: concept
version: 1.0.0
---
# 工具装备系统 - 核心理念
## 类比：外置能力扩展
像人类记得自己有哪些工具、这些工具能做什么一样，我们维护一个**工具装备系统**。
工具是我们的**外置能力扩展**：
- 用锤子钉钉子（无需重新发明锤子）
- 用螺丝刀拧螺丝（无需重新发明螺丝刀）
- 选择正确的工具 → 更高效地解决问题 → 避免重复造轮子
```
工具装备系统 = 工具仓库 + 使用记忆 + 分类索引 + 创建流程
```
## 关键原则
### 1. 整合 > 创造
**核心理念**：不要重复造轮子
**原因**：
1. **成熟稳定**: 如 `fzf`, `eza`, `fd` 等工具经过数千小时打磨
2. **社区支持**: 庞大的用户群和完善的文档
3. **专注专业**: 每个工具只做一件事，做到极致
4. **认知卸载**: 直接使用，无需维护
**类比**：就像人类不会自己打造锤子，而是从五金店购买。
### 2. 工具分类体系
工具按**语言**分类：
- `bash/` - Shell脚本工具
- `python/` - Python工具
- `node/` - Node.js工具
工具按**用途**分类：
- `CODE` - 代码相关
- `DATA` - 数据分析
- `TEST` - 测试
- `BUILD` - 构建
- `MONITOR` - 监控
- `DOC` - 文档
工具按**复杂度**分类：
- `level-1` - 1-5行，简单命令
- `level-2` - 6-20行，简单脚本
- `level-3` - 21-50行，中等复杂度
- `level-4` - 50+行或系统级工具
### 3. 自我完善
工具装备系统**持续演进**：
- 识别重复任务 → 自动化
- 识别模式 → 提取通用工具
- 使用反馈 → 改进工具
- 社区工具 → 整合而非重复
## 设计目标
✅ **可发现性** - 快速找到合适的工具
✅ **可维护性** - 独立文件，清晰分类
✅ **可扩展性** - 轻松添加新工具
✅ **一致性** - 统一元数据格式（.meta.yml）
✅ **可靠性** - 工具检测和验证
## 相关文档
- **快速开始**: `@docs/guides/quickstart.md`
- **工具分类**: `@docs/references/tool-categories.md`
- **创建工具**: `@docs/guides/creating-tools.md`

406
skills/toolkit/docs/guides/creating-tools.md Normal file
View File

@@ -0,0 +1,406 @@
---
name: creating-tools-guide
description: 在AI Runtime工具装备系统中创建新工具的完整指南
category: guide
version: 1.0.0
---
# 如何创造新工具 - 完整指南
## 创造新工具的流程
### 步骤1: 识别需求
在创造新工具之前，先问自己：
```markdown
✅ 这个需求是否真实存在？
- 是否已经重复执行某个任务超过3次？
- 是否花费了超过1小时的手动操作？
✅ 是否有现有工具可以解决？
- 检查: python3 discover-toolkit.py search "关键词"
- 检查: 外部工具是否可用？
✅ 这个工具是否对其他人也有价值？
- 不只是解决一次性问题
- 可能是可复用的模式
✅ 复杂度是否适合工具化？
- level-1 (1-5行): 简单命令别名
- level-2 (6-20行): 简单脚本
- level-3 (21-50行): 中等复杂度
- level-4 (50+行): 系统级工具
```
### 步骤2: 选择工具类型
根据需求选择合适的工具类型：
#### 选项A: Shell脚本工具 (bash/)
**适用场景**：
- 系统管理任务
- 文件操作
- 命令编排
- 快速原型
**优点**：
- 无需额外依赖
- 启动速度快
- 与系统紧密集成
**示例**：
```bash
#!/bin/bash
# bash/monitor/check-disk.sh
echo "检查磁盘空间..."
df -h | grep -E '^/dev/' | awk '$5 > 80 {print "警告: " $0}'
```
#### 选项B: Python工具 (python/)
**适用场景**：
- 复杂逻辑
- 数据处理
- 结构化输出
- 需要库支持
**优点**：
- 强大的标准库
- 跨平台
- 易于测试
- 类型安全（可选）
**示例**：
```python
#!/usr/bin/env python3
# python/analysis/dependency-analyzer.py
"""
分析项目依赖关系
"""
import json
import sys
def analyze_dependencies(project_path):
"""分析依赖"""
# 实现逻辑
pass
if __name__ == '__main__':
analyze_dependencies(sys.argv[1])
```
#### 选项C: Node.js工具 (node/)
**适用场景**：
- API测试
- Web相关工具
- JavaScript生态
**优点**：
- 丰富的npm包
- 异步I/O
- 适合网络操作
**示例**：
```javascript
// node/api/test-api.js
const http = require('http');
function testApi(baseUrl) {
http.get(`${baseUrl}/health`, (res) => {
console.log('API响应:', res.statusCode);
});
}
```
### 步骤3: 创建工具和元数据
#### 示例：创建一个日志分析工具
**1. 创建工具脚本**
```bash
# bash/analysis/analyze-logs-v2.sh
#!/bin/bash
# 分析日志文件，提取错误和警告
LOG_FILE="$1"
echo "=== 日志分析开始 ==="
echo "分析文件: $LOG_FILE"
# 统计ERROR数量
echo "ERROR数量:"
grep -c "ERROR" "$LOG_FILE" || echo "0"
# 统计WARN数量
echo "WARN数量:"
grep -c "WARN" "$LOG_FILE" || echo "0"
echo "=== 日志分析完成 ==="
```
**2. 创建元数据文件**
在相同目录创建 `.meta.yml`：
```yaml
# bash/analysis/analyze-logs-v2.meta.yml
tool_id: BASH-ANALYZE-LOGS-V2-001
tool_name: "日志分析器V2"
基本信息:
语言: bash
文件: analyze-logs-v2.sh
复杂度: level-2
创建日期: 2025-11-14
作者: YourName
用途分类:
- DATA # 数据分析
- MONITOR # 监控诊断
功能描述:
简介: "分析日志文件，提取错误和警告统计"
详细: |
支持功能:
- 统计ERROR数量
- 统计WARN数量
- 显示分析摘要
使用场景:
- "分析应用日志，识别错误模式"
- "监控日志文件，统计错误频率"
- "生成日志分析报告"
使用方法:
命令: "bash analyze-logs-v2.sh <日志文件>"
参数:
日志文件: "要分析的日志文件路径"
示例:
- "分析单个日志: bash analyze-logs-v2.sh app.log"
依赖要求:
系统命令:
- grep: "用于搜索日志内容"
- wc: "用于统计行数"
环境变量: 无
输入输出:
输入:
- 日志文件（纯文本格式）
输出:
- stdout: 分析结果
- 退出码: 0（成功），非0（错误）
维护记录:
2025-11-14:
- 初始创建
- 实现ERROR和WARN统计
```
### 步骤4: 测试工具
```bash
# 1. 赋予执行权限
chmod +x bash/analysis/analyze-logs-v2.sh
# 2. 创建测试日志
cat > test.log << 'EOF'
INFO: Starting application
INFO: Processing request #1
WARN: Timeout on request #1
ERROR: Failed to connect to database
INFO: Retrying...
ERROR: Database connection failed
EOF
# 3. 运行工具测试
bash bash/analysis/analyze-logs-v2.sh test.log
# 期望输出:
# === 日志分析开始 ===
# 分析文件: test.log
# ERROR数量: 2
# WARN数量: 1
# === 日志分析完成 ===
# 4. 删除测试文件
rm test.log
```
### 步骤5: 注册和验证
```bash
# 验证工具被检测到
python3 discover-toolkit.py list | grep LOGS-V2
# 查看工具详细信息
python3 discover-toolkit.py show BASH-ANALYZE-LOGS-V2-001
# 搜索相关工具
python3 discover-toolkit.py search log
# 推荐工具（应该推荐我们的新工具）
python3 discover-toolkit.py recommend "分析日志"
```
### 步骤6: 文档和分享
**1. 创建工具文档**
```markdown
# docs/tools/internal/analyze-logs-v2.md
---
name: analyze-logs-v2
description: 分析日志文件，统计错误和警告
---
# 日志分析器V2
## 用途
快速分析日志文件，统计错误和警告数量
## 使用
```bash
bash bash/analysis/analyze-logs-v2.sh <日志文件>
```
## 示例
```bash
bash bash/analysis/analyze-logs-v2.sh app.log
```
## 输出
```
=== 日志分析开始 ===
分析文件: app.log
ERROR数量: 5
WARN数量: 12
=== 日志分析完成 ===
```
```
**2. 更新主文档**
如果这是重要工具，考虑添加到 `@docs/guides/quickstart.md`
## 工具质量检查清单
在发布工具之前，请检查：
### 功能检查
- [ ] 工具完成预期任务
- [ ] 处理边界情况（空输入、错误输入）
- [ ] 错误处理友好
- [ ] 输出清晰可读
### 代码质量
- [ ] 代码有注释
- [ ] 遵循语言规范
- [ ] 变量命名清晰
- [ ] 没有重复代码
### 元数据检查
- [ ] 填写完整的.meta.yml
- [ ] ID格式正确（LANG-CATEGORY-NAME-001）
- [ ] 包含使用示例
- [ ] 标记了依赖项
### 测试验证
- [ ] 本地测试通过
- [ ] discover-toolkit能检测到
- [ ] show命令显示正确
- [ ] 搜索能找到
### 文档检查
- [ ] 创建了工具文档
- [ ] 更新相关索引
- [ ] 添加了使用示例
## 常见错误
### 1. 权限错误
```bash
chmod +x script.sh # 记得添加执行权限
```
### 2. 缺少shebang
```bash
#!/bin/bash # Bash脚本
#!/usr/bin/env python3 # Python脚本
#!/usr/bin/env node # Node.js脚本
```
### 3. 路径错误
使用相对路径（相对于toolkit根目录）：
```yaml
# 正确
文件: python/analysis/my-tool.py
# 错误（绝对路径）
文件: /Users/.../toolkit/python/analysis/my-tool.py
```
### 4. YAML格式错误
```bash
# 验证YAML语法
python3 -c "import yaml; yaml.safe_load(open('meta.yml'))"
```
## 高级：工具模板
可以使用工具模板快速创建新工具：
```bash
# 复制模板
cp templates/tool-template.sh bash/category/my-tool.sh
cp templates/template.meta.yml bash/category/my-tool.meta.yml
# 修改内容
nano bash/category/my-tool.sh
nano bash/category/my-tool.meta.yml
# 测试
bash bash/category/my-tool.sh
python3 discover-toolkit.py show MY-TOOL-001
```
## 获取帮助
如果遇到困难：
1. **查看现有工具**: `python3 discover-toolkit.py list`
2. **查看示例元文件**: `cat bash/*/*.meta.yml`
3. **查看创建指南**: `@docs/guides/creating-tools.md`
4. **检查外部工具**: `@docs/guides/external-integration.md`
## 贡献工具
如果想贡献工具到AI Runtime：
1. **Fork仓库**: 创建自己的分支
2. **创建工具**: 按照本指南
3. **测试验证**: 确保工具正常工作
4. **提交PR**: 包含工具说明和使用场景
5. **审查合并**: 等待review和merge
## 工具版本管理
为工具添加版本信息：
```yaml
# 在.meta.yml中添加
版本信息:
当前版本: "1.0.0"
发布日期: "2025-11-14"
更新日志:
- "1.0.0: 初始发布"
```
---
**最后更新**: 2025-11-14
**指南版本**: 1.0.0
**维护者**: CodeConscious

261
skills/toolkit/docs/guides/external-integration.md Normal file
View File

@@ -0,0 +1,261 @@
---
name: external-integration
description: 外部CLI工具整合指南 - 为什么和如何整合第三方工具
category: guide
version: 1.0.0
---
# 外部工具整合指南
## 核心理念：不要重复造轮子
**关键洞见**：我们的工具装备系统**不排斥**使用优秀的第三方CLI工具。事实上，**整合**这些工具比重新创建它们更明智。
## 为什么整合外部工具？
### 1. 成熟稳定
工具如 `fzf`, `eza`, `fd`, `bat`, `ripgrep` 等经过：
- **数千小时**的社区打磨
- **复杂场景**的实战测试
- **性能优化**到极致
- **跨平台**兼容性验证
### 2. 社区支持
- **庞大的用户群**: 数万到数十万用户
- **完善的文档**: README、教程、博客文章、视频
- **活跃的维护**: 定期更新、bug修复、新功能
- **丰富的生态**: 插件、扩展、集成方案
### 3. 专注专业
**Unix哲学**: 每个工具只做一件事，做到极致
- **fzf**: 模糊查找，不搞别的
- **eza**: 文件列表，专注显示
- **bat**: 文件查看，语法高亮
- **fd**: 文件搜索，快速简单
- **ripgrep**: 代码搜索，极速递归
### 4. 认知卸载
- **直接使用**: 无需重新实现
- **无需维护**: 交给社区维护者
- **最佳实践**: 吸收社区智慧
- **专注核心**: 把精力放在AI Runtime的独特价值上
**类比**：就像人类不会自己打造锤子，而是从五金店购买。
## 推荐的外部工具
### 基础必备（建议全部安装）
| 工具 | 用途 | 关键优势 | 安装难度 |
|-----|-----|---------|--------|
| **fzf** | 模糊查找 | 交互式、快速、易集成 | ⭐⭐⭐⭐⭐ |
| **eza** | 文件列表 | 美观、Git集成、快速 | ⭐⭐⭐⭐⭐ |
| **zoxide** | 目录跳转 | AI驱动、学习路径 | ⭐⭐⭐⭐⭐ |
| **fd** | 文件搜索 | 简单、快速、忽略.gitignore | ⭐⭐⭐⭐⭐ |
| **bat** | 文件查看 | 语法高亮、Git集成 | ⭐⭐⭐⭐⭐ |
| **ripgrep** | 代码搜索 | 极速、递归、Git感知 | ⭐⭐⭐⭐⭐ |
| **jq** | JSON处理 | 命令行处理JSON | ⭐⭐⭐⭐ |
### 进阶推荐（根据需求选择）
| 工具 | 用途 | 适用场景 |
|-----|-----|---------|
| **zellij** | 终端复用 | 替代tmux, 现代体验 |
| **starship** | Shell提示符 | 美观, Git/语言版本显示 |
| **delta** | Git diff美化 | 查看Git变更体验 |
| **xh** | HTTP客户端 | API测试, 替代curl |
| **just** | 任务运行器 | 替代make, 简洁语法 |
| **hyperfine** | 性能基准测试 | 命令性能对比 |
## 整合策略
### 策略1: 直接使用
在AI Runtime脚本中直接调用外部工具：
```bash
# 在 bash/process-logs.sh 中
# 使用 ripgrep 搜索日志
echo "搜索错误..."
rg "ERROR|CRITICAL" /var/log/app/ --no-ignore-vcs -A 2 -B 2
# 使用 bat 显示结果
bat --paging=never /tmp/analysis-result.json
```
### 策略2: 工具检测
在运行时检测工具是否可用：
```python
# 在 discover-toolkit.py 中
import shutil
def check_tools():
"""检测关键外部工具是否安装"""
tools = ['fzf', 'eza', 'fd', 'bat', 'rg']
missing = []
for tool in tools:
if not shutil.which(tool):
missing.append(tool)
if missing:
print(f"❌ 缺少工具: {', '.join(missing)}")
print("💡 安装: brew install {' '.join(missing)}")
else:
print("✅ 所有关键工具已安装")
```
### 策略3: 交互式增强
使用 fzf 提供交互式体验：
```bash
# 在 runtime-scripts/explore.sh 中
# 使用 fzf 选择文件
FILE=$(fd .py | fzf --preview 'bat --color=always --line-range :50 {}')
echo "处理文件: $FILE"
# 使用 fzf 选择目录
DIR=$(fd --type d | fzf)
cd "$DIR"
```
### 策略4: 优雅降级
工具不存在时的备选方案：
```bash
#!/bin/bash
# script-with-fallback.sh
# 首选使用 eza
if command -v eza &> /dev/null; then
eza --long --git
# 否则使用 ls
else
ls -lah
fi
```
## 在ai-runtime中的实际应用
### 示例1: 文件探索
```bash
# runtime-explore.sh
# 1. 使用 fd 查找所有Python文件
FILES=$(fd .py)
# 2. 使用 fzf 交互式选择
FILE=$(echo "$FILES" | fzf \
--preview 'bat --color=always --line-range :50 {}' \
--preview-window='right:50%:hidden' \
--bind='?:toggle-preview')
# 3. 使用 bat 显示文件内容
echo "=== 开始分析: $FILE ==="
bat "$FILE" | head -50
```
### 示例2: 日志分析
```bash
# analyze-logs.sh
# 1. 使用 ripgrep 快速搜索
rg "ERROR|WARN" /var/log/app/ \
--no-ignore-vcs \
-A 2 -B 2 \
--line-number \
> /tmp/errors.txt
# 2. 使用 bat 美观显示
bat --theme=OneHalfDark /tmp/errors.txt
```
### 示例3: 项目导航
```bash
# smart-navigate.sh
# 使用 zoxide 跳转到最近访问的项目
# 如果 zoxide 可用
if command -v zoxide &> /dev/null; then
z myproject
else
# 否则使用 cd
cd ~/projects/myproject
fi
```
## 安装检查脚本
创建检查脚本，在系统初始化时验证关键工具：
```bash
#!/bin/bash
# check-tools.sh
echo "🔍 检查关键外部工具..."
echo "================================"
TOOLS=("fzf" "eza" "zoxide" "fd" "bat" "rg" "jq")
for tool in "${TOOLS[@]}"; do
if command -v "$tool" &> /dev/null; then
echo "✅ $tool 已安装 ($(which $tool))"
else
echo "❌ $tool 未安装"
case $tool in
fzf)
echo " 💡 安装: brew install fzf"
;;
eza)
echo " 💡 安装: brew install eza"
;;
zoxide)
echo " 💡 安装: curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh"
;;
fd)
echo " 💡 安装: brew install fd"
;;
bat)
echo " 💡 安装: brew install bat"
;;
rg)
echo " 💡 安装: brew install ripgrep"
;;
jq)
echo " 💡 安装: brew install jq"
;;
esac
fi
done
echo "================================"
echo "💡 一键安装所有: brew install fzf eza zoxide fd bat ripgrep jq"
```
## 总结
**整合是明智选择**：
✅ 节省开发时间
✅ 利用社区智慧
✅ 专注核心功能
✅ 更好的用户体验
**渐进式策略**：
1. **首先**: 检测工具是否存在
2. **其次**: 优雅降级（如果工具缺失）
3. **再次**: 增强体验（如果工具存在）
4. **最终**: 完全依赖（确信工具已安装）
## 参考资源
- **外部工具完整参考**: `@docs/references/external-tools.md`
- **外部工具详情**: `@docs/tools/external/{tool-name}.md`
- **快速开始**: `@docs/guides/quickstart.md`

127
skills/toolkit/docs/guides/quickstart.md Normal file
View File

@@ -0,0 +1,127 @@
---
name: quickstart
description: 工具装备系统快速入门指南
category: guide
version: 1.0.0
---
# 工具装备系统 - 快速开始
## 发现和使用工具
```bash
# 进入工具装备目录
cd .ai-runtime/toolkit
# 查看所有可用工具
python3 discover-toolkit.py list
# 查看所有可用工具（包含外部工具）
python3 discover-toolkit.py list --include-external
# 仅查看外部工具
python3 discover-toolkit.py list --external
# 查看特定工具详情
python3 discover-toolkit.py show SERVICE-CHECK-001
# 搜索相关工具（模糊匹配）
python3 discover-toolkit.py search health
# 推荐适合任务的工具
python3 discover-toolkit.py recommend "检查数据库连接"
# 直接运行工具
python3 discover-toolkit.py run dependency-analyzer . -o report.json
# 查看工具使用历史（如果有）
python3 discover-toolkit.py history
```
## 可用的工具
### 内部工具（AI-Runtime创建）
| 工具名称 | ID | 语言 | 用途 | 描述 |
|---------|-----|------|-----|------|
| **服务健康检查器** | SERVICE-CHECK-001 | bash | MONITOR | 检查HTTP服务、数据库、Redis的健康状态 |
| **依赖分析器** | PY-DEPENDENCY-ANALYZER-001 | python | CODE,DATA | 分析Python/JavaScript项目的依赖关系 |
| **代码统计器** | PY-CODE-STATS-004 | python | CODE,DATA | 分析代码库统计信息 |
| **日志分析器** | BASH-ANALYZE-LOGS-002 | bash | DATA,MONITOR | 分析日志文件 |
| **磁盘健康检查器** | BASH-CHECK-DISK-003 | bash | MONITOR | 检查磁盘空间和使用情况 |
#### 服务健康检查器
- **文件**: `bash/system/check-service.sh`
- **用途**: 检查HTTP服务、数据库、Redis的健康状态
- **使用**: `bash check-service.sh <服务名> <类型> [超时]`
- **类型**: http, db/database, redis
- **示例**:
```bash
bash check-service.sh auth-service http
bash check-service.sh db-service db
```
#### 依赖分析器
- **文件**: `python/analysis/dependency-analyzer.py`
- **用途**: 分析Python/JavaScript项目的依赖关系，生成可视化报告
- **使用**: `python3 dependency-analyzer.py [项目目录] -o report.json`
- **支持**: requirements.txt, package.json
- **功能**: 依赖解析、安全风险检测、报告生成
- **示例**:
```bash
python3 dependency-analyzer.py
python3 dependency-analyzer.py /path/to/project
python3 dependency-analyzer.py . -o report.json
```
#### API测试工具
- **文件**: `node/api/test-api.js`
- **用途**: 测试RESTful API端点
- **使用**: `node test-api.js [base-url]`
- **示例**:
```bash
node test-api.js http://localhost:3000
```
## 工具使用流程
### 场景1：探索新项目
```bash
# 1. 查看项目结构
python3 discover-toolkit.py list
# 2. 分析项目依赖
python3 discover-toolkit.py run dependency-analyzer . -o deps.json
# 3. 检查服务健康（如果适用）
bash bash/system/check-service.sh myapp http
```
### 场景2：排查问题
```bash
# 1. 搜索相关工具
python3 discover-toolkit.py search log
# 2. 分析日志
bash bash/analysis/analyze-logs.sh /path/to/logs --level ERROR
# 3. 检查磁盘空间
bash bash/system/check-disk.sh /
```
### 场景3：常规监控
```bash
# 1. 检查所有服务
for service in auth db cache; do
bash bash/system/check-service.sh $service http
done
# 2. 生成健康报告
python3 discover-toolkit.py recommend "health check"
```
## 下一步学习
- **查看完整参考**: `@docs/references/internal-tools.md`
- **了解外部工具**: `@docs/external-integration.md`
- **学习如何创建工具**: `@docs/guides/creating-tools.md`

194
skills/toolkit/docs/references/external-tools.md Normal file
View 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

298
skills/toolkit/docs/references/internal-tools.md Normal file
View File

@@ -0,0 +1,298 @@
---
name: internal-tools-reference
description: AI Runtime内部工具完整参考 - 包含所有内部创建的工具详细信息
category: reference
version: 1.0.0
---
# 内部工具完整参考
**最后更新**: 2025-11-14
---
## 工具概览
AI Runtime工具装备系统包含以下**内部创建的工具**（按语言分类）：
### Python工具 (python/)
| 工具名称 | ID | 用途 | 复杂度 | 文件位置 |
|---------|-----|-----|--------|----------|
| **依赖关系分析器** | PY-DEPENDENCY-ANALYZER-001 | CODE,DATA | level-3 | python/analysis/dependency-analyzer.py |
| **代码统计器** | PY-CODE-STATS-004 | CODE,DATA | level-2 | python/analysis/code-stats.py |
| **图形生成器** | PY-GRAPH-GENERATOR-002 | DATA,VISUAL | level-3 | python/graph/generate-graph.py |
| **报告生成器** | PY-REPORT-GENERATOR-005 | DOC,REPORT | level-3 | python/report/generate-report.py |
#### PY-DEPENDENCY-ANALYZER-001 依赖关系分析器
**元文件**: `python/analysis/dependency-analyzer.meta.yml`
**用途**: 分析Python/JavaScript项目的依赖关系，生成可视化报告
**功能特性**:
- 解析Python requirements.txt
- 解析JavaScript package.json
- 识别安全风险
- 生成Markdown报告
- 导出JSON格式
**使用方法**:
```bash
# 分析当前目录
python3 python/analysis/dependency-analyzer.py
# 分析指定项目
python3 python/analysis/dependency-analyzer.py /path/to/project
# 保存JSON报告
python3 python/analysis/dependency-analyzer.py . -o report.json
# 详细输出
python3 python/analysis/dependency-analyzer.py -v
```
**依赖要求**:
- Python >= 3.8
- 无第三方依赖（仅标准库）
**输入输出**:
- 输入: requirements.txt, package.json
- 输出: Markdown报告到stdout, JSON到文件（如果指定-o）
**上次使用**:
- 时间: 2025-11-14 10:30:00
- 用途: 分析ai-runtime项目依赖
- 满意度: 0.92
#### PY-CODE-STATS-004 代码统计器
**元文件**: `python/analysis/code-stats.meta.yml`
**用途**: 分析代码库统计信息，包括行数、函数、类、注释率和代码健康指标
**功能特性**:
- 统计代码行数（LOC）
- 统计函数和类数量
- 计算注释率
- 识别代码质量问题（长函数、复杂文件）
**使用方法**:
```bash
# 统计当前目录
python3 python/analysis/code-stats.py
# 统计指定目录
python3 python/analysis/code-stats.py src/
# 详细输出
python3 python/analysis/code-stats.py -v
```
**上次使用**:
- 时间: 2025-11-14 11:15:00
- 用途: 统计项目代码规模
- 满意度: 0.88
---
### Bash工具 (bash/)
| 工具名称 | ID | 用途 | 复杂度 | 文件位置 |
|---------|-----|-----|--------|----------|
| **服务健康检查器** | SERVICE-CHECK-001 | MONITOR | level-1 | bash/system/check-service.sh |
| **日志分析器** | BASH-ANALYZE-LOGS-002 | DATA,MONITOR | level-2 | bash/analysis/analyze-logs.sh |
| **磁盘健康检查器** | BASH-CHECK-DISK-003 | MONITOR | level-2 | bash/system/check-disk.sh |
#### SERVICE-CHECK-001 服务健康检查器
**元文件**: `bash/system/check-service.meta.yml`
**用途**: 检查HTTP服务、数据库、Redis的健康状态
**功能特性**:
- HTTP服务健康检查（/health端点）
- PostgreSQL数据库连接检查
- Redis连接和ping测试
- 可配置超时
**使用方法**:
```bash
# 检查HTTP服务
bash bash/system/check-service.sh auth-service http
# 检查数据库
bash bash/system/check-service.sh db-service db
# 检查Redis
bash bash/system/check-service.sh cache redis
# 自定义超时（10秒）
bash bash/system/check-service.sh myapp http 10
```
**依赖要求**:
- curl（HTTP检查）
- pg_isready（PostgreSQL检查）
- redis-cli（Redis检查）
**环境变量**:
- DB_HOST (默认: localhost)
- DB_PORT (默认: 5432)
- DB_NAME
- DB_USER
- REDIS_HOST (默认: localhost)
- REDIS_PORT (默认: 6379)
**上次使用**:
- 时间: 2025-11-14 16:45:00
- 用途: 验证auth-service修复后状态
- 满意度: 0.9
#### BASH-ANALYZE-LOGS-002 日志分析器
**元文件**: `bash/analysis/analyze-logs.meta.yml`
**用途**: 分析日志文件，按级别过滤、时间范围筛选、模式匹配和错误统计
**功能特性**:
- 按日志级别过滤（ERROR, WARN, INFO, DEBUG）
- 时间范围筛选
- 模式匹配
- 错误统计
- 生成摘要报告
**使用方法**:
```bash
# 分析日志并统计ERROR
bash bash/analysis/analyze-logs.sh /var/log/app.log --level ERROR
# 分析最近1小时的日志
bash bash/analysis/analyze-logs.sh /var/log/app.log --since "1 hour ago"
# 搜索特定模式
bash bash/analysis/analyze-logs.sh /var/log/app.log --pattern "connection failed"
```
**上次使用**:
- 时间: 2025-11-14 14:20:00
- 用途: 分析生产环境错误日志
- 满意度: 0.85
#### BASH-CHECK-DISK-003 磁盘健康检查器
**元文件**: `bash/system/check-disk.meta.yml`
**用途**: 检查磁盘空间、inode使用和健康状态，提供详细的分析和建议
**功能特性**:
- 磁盘空间使用检查（总容量、已使用、可用）
- Inode使用检查
- 使用阈值警报（可配置，默认80%）
- 文件系统类型检测
- 挂载点和权限检查
- 性能指标分析
- 智能建议生成
**使用方法**:
```bash
# 检查根目录（阈值80%）
bash bash/system/check-disk.sh /
# 检查日志目录自定义阈值（90%）
bash bash/system/check-disk.sh /var/log 90
# 检查所有挂载点
bash bash/system/check-disk.sh --all
```
**上次使用**:
- 时间: 2025-11-14 13:30:00
- 用途: 预防性检查服务器磁盘空间
- 满意度: 0.87
---
### Node.js工具 (node/)
| 工具名称 | ID | 用途 | 复杂度 | 文件位置 |
|---------|-----|-----|--------|----------|
| **API测试工具** | NODE-API-TESTER-001 | TEST,API | level-2 | node/api/test-api.js |
#### NODE-API-TESTER-001 API测试工具
**元文件**: `node/api/test-api.meta.yml`
**用途**: 测试RESTful API端点
**功能特性**:
- HTTP GET/POST/PUT/DELETE请求
- JSON请求体支持
- 响应验证
- 批量测试
**使用方法**:
```bash
# 测试API健康检查
node node/api/test-api.js http://localhost:3000
# 测试指定端点
node node/api/test-api.js http://localhost:3000/api/users
# POST测试（需要修改脚本）
node node/api/test-api.js post http://localhost:3000/api/users '{"name":"test"}'
```
**依赖要求**:
- Node.js 14+
- npm包: axios, chalk, commander（根据实际实现）
---
## 工具分类说明
### 按语言分类
| 语言 | 工具数量 | 主要用途 |
|-----|---------|---------|
| **python** | 4 | 代码分析、数据处理、报告生成 |
| **bash** | 3 | 系统监控、日志分析、服务检查 |
| **node** | 1 | API测试、网络操作 |
### 按复杂度分类
| 复杂度 | 数量 | 说明 |
|--------|-----|------|
| **level-1** | 1-5行 | 简单命令别名 |
| **level-2** | 6-20行 | 简单脚本（4个工具） |
| **level-3** | 21-50行 | 中等复杂度（3个工具） |
| **level-4** | 50+行 | 系统级工具（1个工具） |
### 按用途分类
| 用途 | 工具数量 | 代表工具 |
|-----|---------|---------|
| **CODE** | 3 | 依赖分析器、代码统计器 |
| **DATA** | 3 | 依赖分析器、日志分析器 |
| **MONITOR** | 3 | 服务检查、磁盘检查、日志分析 |
| **TEST** | 1 | API测试工具 |
| **API** | 1 | API测试工具 |
| **VISUAL** | 1 | 图形生成器 |
| **REPORT** | 1 | 报告生成器 |
| **DOC** | 2 | 报告生成器 |
---
## 维护信息
**最后审查**: 2025-11-14
**下次审查**: 2025-12-14
**维护者**: CodeConscious
**状态**: Active
## 相关文档
- **快速开始指南**: `@docs/guides/quickstart.md`
- **创建工具指南**: `@docs/guides/creating-tools.md`
- **外部工具整合**: `@docs/guides/external-integration.md`
- **工具分类说明**: `@docs/references/tool-categories.md`

64
skills/toolkit/docs/tools/external/bat.md vendored Normal file
View File

@@ -0,0 +1,64 @@
---
name: bat
description: 带语法高亮的cat替代品
category: essential
tool_id: EXT-BAT-001
---
# bat (cat with syntax) ⭐⭐⭐⭐⭐
## 用途
语法高亮的文件查看
## 安装
### macOS
```bash
brew install bat
```
### Ubuntu/Debian
```bash
sudo apt-get install bat
```
## 配置 (添加到 ~/.bashrc)
```bash
alias cat='bat -p'
alias catn='bat'
```
## 使用
```bash
# 查看文件（有语法高亮）
bat app.py
# 分页查看（保留高亮）
bat -p app.py | less -R
# 查看Git修改
bat -d app.py
# 查看行号
bat -n app.py
```
## 常用选项
- `-p` -- 纯文本模式（无分页）
- `-n` -- 显示行号
- `-d` -- 显示Git diff
- `-l` -- 指定语言
- `--theme` -- 选择主题
## 与其他工具集成
```bash
# 与fzf集成
fd .py | fzf --preview 'bat --color=always {}'
# 查看日志
bat /var/log/system.log
```

60
skills/toolkit/docs/tools/external/eza.md vendored Normal file
View File

@@ -0,0 +1,60 @@
---
name: eza
description: 现代化的ls替代品，带彩色输出和图标
category: essential
tool_id: EXT-EZA-001
---
# eza (Modern ls) ⭐⭐⭐⭐⭐
## 用途
现代化文件列表，替代传统ls命令
## 安装
### macOS
```bash
brew install eza
```
### Ubuntu/Debian
```bash
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
```
## 配置 (添加到 ~/.bashrc)
```bash
alias ll='eza -lah'
alias ls='eza'
alias tree='eza --tree --level=2'
```
## 使用
```bash
# 详细列表
ll
# Git状态
ll --git
# 树形结构
tree
# 显示图标
eza --icons
```
## 常用选项
- `-l` -- 长格式
- `-a` -- 显示隐藏文件
- `-h` -- 人性化大小
- `-g` -- 显示Git状态
- `--tree` -- 树形视图
- `--icons` -- 显示文件图标

81
skills/toolkit/docs/tools/external/fzf.md vendored Normal file
View File

@@ -0,0 +1,81 @@
---
name: fzf
description: 命令行模糊查找工具 - 用于交互式搜索和选择
category: essential
tool_id: EXT-FZF-001
---
# fzf (Fuzzy Finder) ⭐⭐⭐⭐⭐
## 用途
命令行模糊查找，革命性交互体验
## 安装
### macOS
```bash
brew install fzf
$(brew --prefix)/opt/fzf/install # 安装键盘快捷键
```
### Ubuntu/Debian
```bash
sudo apt-get install fzf
```
## 基础使用
```bash
# 文件名查找
find . -type f | fzf
# 历史命令
history | fzf
# Git分支
git branch | fzf
# 进程kill
ps aux | fzf | awk '{print $2}' | xargs kill
```
## 进阶配置 (添加到 ~/.bashrc)
```bash
# 使用Ctrl-R搜索历史
export FZF_CTRL_R_OPTS="--preview 'echo {}' --preview-window down:3:wrap"
# 使用Ctrl-T搜索文件
export FZF_CTRL_T_COMMAND="fd --type f --hidden --follow --exclude .git"
export FZF_CTRL_T_OPTS="--preview 'bat -n --color=always {}'"
```
## 在ai-runtime中的建议
```bash
# 集成到discover-toolkit.py
# 当选择工具时，使用fzf进行交互式选择
python3 discover-toolkit.py list | fzf --height 40%
```
## 为什么我们不应重新实现
- 7000+ stars on GitHub，社区验证
- 性能优化到极致
- 支持多种Shell和OS
- 生态丰富（vim插件、tmux集成等）
**类比**：就像人类不会自己打造锤子，而是从五金店购买。
## 快速验证
```bash
# 检查是否安装
which fzf
# 验证版本
fzf --version
# 测试基本功能
ls | fzf
```

94
skills/toolkit/docs/tools/external/jq.md vendored Normal file
View File

@@ -0,0 +1,94 @@
---
name: jq
description: JSON数据的命令行处理器 - 查询、过滤和转换JSON
category: advanced
tool_id: EXT-JQ-001
---
# jq (JSON Processor) ⭐⭐⭐⭐⭐
## 用途
命令行JSON查询、过滤和转换工具
## 安装
### macOS
```bash
brew install jq
```
### Ubuntu/Debian
```bash
sudo apt-get install jq
```
## 基础使用
```bash
# 美化打印
cat data.json | jq '.'
# 提取字段
cat api.json | jq '.users[0].name'
# 数组长度
cat data.json | jq '.items | length'
# 过滤
cat logs.json | jq '.[] | select(.level == "ERROR")'
# 转换
cat data.json | jq '{new_name: .old_name, count: .items | length}'
```
## 在ai-runtime中的使用
```bash
# 分析JSON格式的认知记录
jq '.entries[] | select(.type == "ERROR")' .ai-runtime/memory/episodic/timeline.json
# 发现工具统计显示
python3 discover-toolkit.py list --json | jq '.[] | {tool: .tool_name, lang: .language}'
# 提取依赖分析结果
python3 dependency-analyzer.py . -o report.json | jq '.vulnerabilities'
```
## 常用操作
### 数组操作
```bash
# 映射
cat data.json | jq 'map(.value * 2)'
# 过滤
cat data.json | jq 'map(select(.active == true))'
# 排序
cat data.json | jq 'sort_by(.date)'
```
### 对象操作
```bash
# 添加字段
cat data.json | jq '. + {new_field: "value"}'
# 删除字段
cat data.json | jq 'del(.old_field)'
# 合并对象
cat data1.json data2.json | jq -s 'add'
```
### 高级技巧
```bash
# 条件判断
cat config.json | jq '.env.WIN_VERBOSE = if .debug then "true" else "false" end'
# 管道操作
cat data.json | jq '.items[] | select(.price > 100) | .name'
# 变量赋值
cat data.json | jq 'first(.items[] | select(.id == "123")) as $item | $item.price'
```

68
skills/toolkit/docs/tools/external/ripgrep.md vendored Normal file
View File

@@ -0,0 +1,68 @@
---
name: ripgrep
description: 极速代码搜索工具（rg）- grep的现代化替代品
category: essential
tool_id: EXT-RG-001
---
# ripgrep (rg) ⭐⭐⭐⭐⭐
## 用途
极速代码搜索，默认递归搜索且遵守.gitignore
## 安装
### macOS
```bash
brew install ripgrep
```
### Ubuntu/Debian
```bash
sudo apt-get install ripgrep
```
## 配置
```bash
# 添加到 ~/.bashrc
alias grep='rg'
```
## 使用
```bash
# 搜索Python文件中的TODO
rg "TODO" -g "*.py"
# 显示上下文（3行）
rg -A 3 -B 3 "def function_name" app.py
# 统计匹配数
rg --count "import"
# 搜索并打开文件
rg "TODO" --files-with-matches | fzf | xargs bat
```
## 常用选项
- `-i` -- 忽略大小写
- `-g` -- 文件模式匹配（glob）
- `-A NUM` -- 显示匹配后NUM行
- `-B NUM` -- 显示匹配前NUM行
- `-C NUM` -- 显示匹配前后各NUM行
- `--count` -- 统计匹配数
- `--files-with-matches` -- 只显示包含匹配的文件名
## 技巧
```bash
# 搜索并替换（预览）
rg "old_function" -S | fzf
# 指定编码
rg --encoding utf8 "pattern"
# 与fzf集成
rg "" --files-with-matches | fzf --preview 'rg --color=always "" {}'
```

75
skills/toolkit/docs/tools/external/zoxide.md vendored Normal file
View File

@@ -0,0 +1,75 @@
---
name: zoxide
description: 智能目录跳转工具（z）- cd的AI驱动替代品
category: essential
tool_id: EXT-ZOXIDE-001
---
# zoxide (Smart cd) ⭐⭐⭐⭐⭐
## 用途
智能目录跳转，学习访问习惯，基于频率和最近访问时间
## 安装
### 所有平台（推荐）
```bash
curl -sSfL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh
```
或者使用包管理器：
### macOS
```bash
brew install zoxide
```
### Ubuntu/Debian
```bash
sudo apt-get install zoxide
```
## 配置
添加到 `~/.bashrc`:
```bash
eval "$(zoxide init bash)"
alias cd='z'
alias cdi='zi'
```
## 使用
```bash
# 第一次需要完整路径
cd ~/projects/ai-runtime
# 之后只需（zoxide会学习）
z ai-runtime
# 查看访问频率
z --list | head
# 交互式选择
zi
# 跳转到包含'proj'的目录
z proj
# 跳转到包含'ai'和'time'的目录
z ai time
```
## 常用命令
- `z --list` -- 显示访问目录列表
- `z --list | head` -- 显示最近访问的目录
- `z -i` -- 交互式跳转（同`zi`）
- `z -e` -- 显示最高匹配目录
## 特性
- **智能学习**：基于访问频率和最近访问时间
- **模糊匹配**：支持部分匹配
- **跨Shell**：支持bash, zsh, fish等
- **快速跳转**：通常比手动输入路径更快