Initial commit

skills/toolkit/docs/guides/creating-tools.md

@@ -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

skills/toolkit/docs/guides/external-integration.md

@@ -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`

skills/toolkit/docs/guides/quickstart.md

@@ -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`