Initial commit

skills/toolkit/references/core/toolkit-philosophy.md

@@ -0,0 +1,187 @@
+# 工具装备系统设计哲学
+
+## 核心理念
+
+### 整合优于创造 (Integration over Creation)
+
+**为什么选择整合？**
+1. **成熟稳定**: 经过数千小时的社区打磨和实际使用验证
+2. **社区支持**: 庞大的用户群、完善的文档和活跃的维护
+3. **专注专业**: 每个工具只做一件事，并做到极致
+4. **认知卸载**: 无需重复实现，直接使用成熟解决方案
+
+**实际案例**:
+- 使用 `ripgrep` 而非重新实现代码搜索
+- 使用 `jq` 而非创建自定义JSON处理器
+- 使用 `fzf` 而非开发模糊查找界面
+
+### 元数据驱动架构
+
+**设计原则**:
+- **声明式配置**: 通过 `.meta.yml` 文件描述工具能力
+- **自动发现**: 基于文件系统结构自动注册工具
+- **类型安全**: 明确的工具分类、版本和依赖管理
+
+**元数据标准**:
+```yaml
+name: SERVICE-CHECK-001
+description: HTTP服务健康检查工具
+language: bash
+category: MONITOR
+complexity: level-2
+dependencies: [curl]
+parameters:
+  - name: url
+    type: string
+    required: true
+    description: 要检查的服务URL
+```
+
+### 渐进式披露设计
+
+受 anthropics/skills 项目启发，采用分层文档结构：
+
+1. **SKILL.md**: 核心入口，包含基本概念和快速开始
+2. **references/**: 详细参考文档，按需加载
+3. **README.md**: 索引和导航，指向具体文档
+
+## 工具分类体系
+
+### 复杂度分层
+
+| 级别 | 代码行数 | 特点 | 示例 |
+|-----|---------|------|------|
+| Level-1 | 1-5行 | 简单命令封装 | 基础系统调用 |
+| Level-2 | 6-20行 | 参数处理和错误处理 | 服务检查、文件操作 |
+| Level-3 | 21-50行 | 复杂逻辑和数据处理 | 依赖分析、报告生成 |
+| Level-4 | 50+行 | 完整应用程序 | API测试框架 |
+
+### 功能分类
+
+| 分类 | 用途 | 示例工具 |
+|-----|-----|---------|
+| **CODE** | 代码处理和分析 | 依赖分析器、代码统计器 |
+| **DATA** | 数据处理和转换 | 依赖分析器、JSON处理器 |
+| **TEST** | 测试和验证 | API测试工具、数据验证器 |
+| **BUILD** | 构建和部署 | 构建脚本、部署检查器 |
+| **MONITOR** | 监控和诊断 | 服务检查器、日志分析器 |
+| **DOC** | 文档处理 | 文档生成器、格式转换器 |
+
+### 语言选择策略
+
+**Bash工具**:
+- 系统级操作（文件、进程、网络）
+- 轻量级文本处理
+- 调用现有CLI工具的胶水代码
+
+**Python工具**:
+- 复杂数据处理和分析
+- 需要丰富标准库的功能
+- 跨平台兼容性要求
+
+**Node.js工具**:
+- Web/API相关操作
+- 需要npm生态系统的工具
+- 现代JavaScript开发栈集成
+
+## 开发工作流
+
+### 工具创建流程
+
+1. **需求识别**: 识别重复3次以上的任务
+2. **复杂度评估**: 确定合适的复杂度级别
+3. **语言选择**: 根据任务特点选择编程语言
+4. **模板应用**: 使用相应模板快速创建
+5. **元数据编写**: 创建 `.meta.yml` 描述文件
+6. **测试验证**: 通过 `discover-toolkit.py` 测试
+7. **文档编写**: 添加使用说明和示例
+
+### 质量保证
+
+**代码质量**:
+- 错误处理和边界情况覆盖
+- 输入验证和参数检查
+- 清晰的错误消息和退出码
+
+**文档质量**:
+- 完整的参数说明
+- 实际使用示例
+- 常见问题和故障排除
+
+**集成质量**:
+- 正确的元数据格式
+- 合理的依赖声明
+- 向后兼容性保证
+
+## 生态系统扩展
+
+### 外部工具整合策略
+
+**选择标准**:
+- **社区活跃度**: GitHub stars、最近提交频率
+- **跨平台支持**: 支持主流操作系统
+- **许可证兼容**: MIT/BSD/Apache等宽松许可证
+- **维护状态**: 积极维护，无重大安全问题
+
+**整合深度**:
+- **Level-1**: 简单命令别名和参数传递
+- **Level-2**: 错误处理和输出格式化
+- **Level-3**: 高级功能封装和定制选项
+
+### 版本管理和兼容性
+
+**语义版本**: 遵循 SemVer 规范
+- **MAJOR**: 不兼容的API变更
+- **MINOR**: 向后兼容的新功能
+- **PATCH**: 向后兼容的bug修复
+
+**兼容性保证**:
+- 工具接口的向后兼容
+- 元数据格式的稳定性
+- 升级路径的明确说明
+
+## 性能和效率
+
+### 资源使用优化
+
+**启动时间**: 工具应该在2秒内启动
+**内存使用**: 避免不必要的内存占用
+**磁盘I/O**: 合理使用缓存和临时文件
+
+### 并发和并行
+
+**设计考虑**:
+- 工具是否支持并发执行
+- 共享资源的正确处理
+- 输出的线程安全性
+
+**实现策略**:
+- 无状态设计优先
+- 显式的并发控制
+- 资源锁的合理使用
+
+## 监控和维护
+
+### 健康检查
+
+**自动监控**:
+- 工具可用性检查
+- 性能指标收集
+- 错误率统计
+
+**维护任务**:
+- 定期更新外部工具
+- 清理过时工具
+- 优化性能瓶颈
+
+### 演进策略
+
+**持续改进**:
+- 用户反馈收集和分析
+- 性能指标监控
+- 新需求和功能的评估
+
+**弃用管理**:
+- 明确的弃用时间表
+- 迁移路径说明
+- 向后兼容性保证

skills/toolkit/references/guides/quickstart.md

@@ -0,0 +1,295 @@
+# 工具装备系统快速开始指南
+
+## 10分钟上手工具装备系统
+
+### 前置条件
+
+**系统要求**:
+- Python 3.8+
+- Bash shell
+- 基本CLI工具（curl, grep, find等）
+
+**推荐安装**:
+```bash
+# macOS
+brew install fzf eza zoxide fd bat ripgrep jq
+
+# Ubuntu/Debian
+sudo apt-get install fzf ripgrep jq bat
+```
+
+### 第一步：环境检查
+
+```bash
+# 进入工具装备目录
+cd .ai-runtime/toolkit
+
+# 检查Python环境
+python3 --version
+
+# 检查discover-toolkit工具
+python3 discover-toolkit.py --help
+```
+
+### 第二步：查看可用工具
+
+```bash
+# 查看所有工具概览
+python3 discover-toolkit.py list
+
+# 查看内部工具
+python3 discover-toolkit.py list --internal
+
+# 查看外部工具
+python3 discover-toolkit.py list --external
+```
+
+### 第三步：使用工具
+
+#### 基础用法
+
+```bash
+# 查看工具详情
+python3 discover-toolkit.py show SERVICE-CHECK-001
+
+# 运行服务健康检查
+python3 discover-toolkit.py run service-check http://localhost:3000
+
+# 运行依赖分析
+python3 discover-toolkit.py run dependency-analyzer . -o deps.json
+```
+
+#### 实际场景示例
+
+**场景1: 项目代码分析**
+```bash
+# 分析当前项目的依赖关系
+python3 discover-toolkit.py run dependency-analyzer . -o project-deps.json
+
+# 查看结果
+cat project-deps.json | jq '.summary'
+```
+
+**场景2: 日志文件分析**
+```bash
+# 分析应用日志，查找错误
+python3 discover-toolkit.py run log-analyzer /var/log/app.log --level ERROR --since "1 hour ago"
+
+# 生成错误统计报告
+python3 discover-toolkit.py run log-analyzer /var/log/app.log --stats --output error-stats.json
+```
+
+**场景3: API测试**
+```bash
+# 测试REST API端点
+python3 discover-toolkit.py run api-test http://api.example.com/users --method GET
+
+# 测试POST请求
+python3 discover-toolkit.py run api-test http://api.example.com/users \
+  --method POST \
+  --data '{"name": "test user"}' \
+  --headers "Content-Type: application/json"
+```
+
+### 第四步：外部工具集成
+
+#### 安装检查
+
+```bash
+# 检查外部工具安装状态
+python3 discover-toolkit.py check-external
+
+# 安装缺失的工具（macOS示例）
+brew install fzf eza bat ripgrep
+```
+
+#### 实际使用
+
+```bash
+# 使用ripgrep搜索代码（比grep快10倍以上）
+rg "TODO|FIXME" src/
+
+# 使用fzf进行交互式选择
+find src/ -name "*.py" | fzf
+
+# 使用bat查看带语法高亮的代码
+bat src/main.py
+
+# 使用eza美化文件列表
+eza -la src/
+
+# 使用jq处理JSON数据
+cat package.json | jq '.dependencies'
+```
+
+### 第五步：创建自定义工具
+
+#### 快速创建Bash工具
+
+```bash
+# 使用模板创建新工具
+cp templates/tool-template.sh bash/custom/my-tool.sh
+cp templates/meta-template.yml bash/custom/my-tool.meta.yml
+
+# 编辑工具脚本
+nano bash/custom/my-tool.sh
+
+# 编辑元数据
+nano bash/custom/my-tool.meta.yml
+```
+
+#### 元数据示例
+
+```yaml
+name: MY-TOOL-001
+description: 我的自定义工具
+language: bash
+category: UTILITY
+complexity: level-2
+version: 1.0.0
+
+parameters:
+  - name: input
+    type: string
+    required: true
+    description: 输入文件路径
+
+  - name: output
+    type: string
+    required: false
+    description: 输出文件路径（可选）
+
+examples:
+  - description: 基本用法
+    command: python3 discover-toolkit.py run my-tool input.txt
+
+  - description: 指定输出
+    command: python3 discover-toolkit.py run my-tool input.txt -o output.txt
+```
+
+#### 测试新工具
+
+```bash
+# 验证工具注册
+python3 discover-toolkit.py show MY-TOOL-001
+
+# 测试运行
+python3 discover-toolkit.py run my-tool test-input.txt
+
+# 查看帮助
+python3 discover-toolkit.py help MY-TOOL-001
+```
+
+### 第六步：高级用法
+
+#### 批量操作
+
+```bash
+# 批量检查多个服务
+echo "http://api1.example.com
+http://api2.example.com
+http://db.example.com:5432" | \
+while read url; do
+  echo "Checking $url..."
+  python3 discover-toolkit.py run service-check "$url"
+done
+```
+
+#### 脚本集成
+
+```bash
+#!/bin/bash
+# CI/CD 集成脚本示例
+
+PROJECT_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TOOLKIT_DIR="$PROJECT_ROOT/.ai-runtime/toolkit"
+
+cd "$TOOLKIT_DIR"
+
+# 代码质量检查
+echo "=== 代码质量检查 ==="
+python3 discover-toolkit.py run code-stats src/ --format json > code-stats.json
+
+# 依赖安全检查
+echo "=== 依赖安全检查 ==="
+python3 discover-toolkit.py run dependency-analyzer . --security-check > security-report.json
+
+# 生成综合报告
+echo "=== 生成报告 ==="
+python3 discover-toolkit.py run report-generator \
+  --code-stats code-stats.json \
+  --security security-report.json \
+  --output ci-report.html
+```
+
+#### 监控和告警
+
+```bash
+# 定期健康检查
+while true; do
+  echo "$(date): Health check..."
+  python3 discover-toolkit.py run service-check http://localhost:3000 > /dev/null
+  if [ $? -ne 0 ]; then
+    echo "Service down! Sending alert..."
+    # 发送告警逻辑
+  fi
+  sleep 300  # 5分钟检查一次
+done
+```
+
+## 故障排除
+
+### 常见问题
+
+**工具未找到**
+```bash
+# 检查工具是否存在
+python3 discover-toolkit.py list | grep <tool-name>
+
+# 检查元数据文件
+find . -name "*.meta.yml" | xargs grep <tool-name>
+```
+
+**运行时错误**
+```bash
+# 查看详细错误信息
+python3 discover-toolkit.py run <tool-name> --verbose
+
+# 检查依赖
+python3 discover-toolkit.py show <tool-name>
+```
+
+**外部工具不可用**
+```bash
+# 检查安装
+which <external-tool>
+
+# 重新检测
+python3 discover-toolkit.py check-external
+```
+
+### 获取帮助
+
+```bash
+# 通用帮助
+python3 discover-toolkit.py --help
+
+# 工具特定帮助
+python3 discover-toolkit.py help <tool-name>
+
+# 搜索相关工具
+python3 discover-toolkit.py search <keyword>
+```
+
+## 下一步
+
+完成这个快速开始指南后，你可以：
+
+1. **深入学习**: 查看 [references/internal-tools.md](internal-tools.md) 了解所有内部工具
+2. **扩展技能**: 阅读 [references/external-tools.md](external-tools.md) 掌握更多CLI工具
+3. **开发工具**: 参考 [references/creating-tools.md](creating-tools.md) 创建自己的工具
+4. **优化工作流**: 将工具集成到你的开发和部署流程中
+
+---
+
+*这个指南应该在10分钟内完成。如果遇到问题，请查看详细文档或寻求帮助。*