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**: 合理使用缓存和临时文件
+
+### 并发和并行
+
+**设计考虑**:
+- 工具是否支持并发执行
+- 共享资源的正确处理
+- 输出的线程安全性
+
+**实现策略**:
+- 无状态设计优先
+- 显式的并发控制
+- 资源锁的合理使用
+
+## 监控和维护
+
+### 健康检查
+
+**自动监控**:
+- 工具可用性检查
+- 性能指标收集
+- 错误率统计
+
+**维护任务**:
+- 定期更新外部工具
+- 清理过时工具
+- 优化性能瓶颈
+
+### 演进策略
+
+**持续改进**:
+- 用户反馈收集和分析
+- 性能指标监控
+- 新需求和功能的评估
+
+**弃用管理**:
+- 明确的弃用时间表
+- 迁移路径说明
+- 向后兼容性保证