***

name: "download-tools"
description: "嵌入式开发工具链下载和管理技能"
version: "2.0.0"
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

# 嵌入式开发工具链下载和管理技能

## 概述

`download-tools` 技能是一个专业的嵌入式开发工具链管理工具，专门用于自动化下载、安装、配置和验证嵌入式开发所需的各种工具链。作为 OpenClaw 集成专家，我深知稳定可靠的开发环境对于嵌入式项目成功至关重要。本技能提供跨平台支持，确保开发工具的一致性和可重复性。

## 核心特性

### 1. 多平台支持
- **Windows**: 支持原生 PowerShell、CMD 和 Git Bash
- **Linux**: 支持 Ubuntu、Debian、Fedora、Arch 等主流发行版
- **macOS**: 支持 Intel 和 Apple Silicon 架构

### 2. 工具链覆盖
- **编译工具链**: ARM GCC、RISC-V GCC、Xtensa GCC、Clang
- **调试工具**: J-Link、OpenOCD、ST-Link、pyOCD
- **烧录工具**: esptool、STM32CubeProgrammer、GD32AllInOne
- **串口工具**: minicom、screen、putty、serial terminal
- **构建系统**: CMake、Make、Ninja、Meson
- **开发环境**: Python 环境、VS Code 扩展、Eclipse 插件

### 3. 智能管理
- **版本锁定**: 确保工具版本一致性
- **依赖解析**: 自动处理工具依赖关系
- **完整性校验**: 下载后验证工具完整性
- **环境配置**: 自动配置 PATH 和环境变量
- **离线支持**: 支持离线安装和本地缓存

## 工作流程

```mermaid
flowchart TD
    A[开始工具链管理] --> B{选择操作模式}
    B --> C[安装模式]
    B --> D[更新模式]
    B --> E[验证模式]
    B --> F[清理模式]
    
    C --> C1[检查系统兼容性]
    C1 --> C2[解析工具依赖]
    C2 --> C3[下载工具文件]
    C3 --> C4[安装和配置]
    C4 --> C5[验证安装结果]
    C5 --> G[完成]
    
    D --> D1[检查可用更新]
    D1 --> D2[备份当前版本]
    D2 --> D3[下载新版本]
    D3 --> D4[更新配置]
    D4 --> C5
    
    E --> E1[检查工具状态]
    E1 --> E2[验证版本兼容性]
    E2 --> E3[测试基本功能]
    E3 --> E4[生成验证报告]
    E4 --> G
    
    F --> F1[清理临时文件]
    F1 --> F2[卸载旧版本]
    F2 --> F3[恢复环境配置]
    F3 --> G
```

## 参数定义

### YAML 配置格式

```yaml
# tools-config.yaml
version: "2.0.0"
platform: "auto"  # auto, windows, linux, macos

tools:
  # 编译工具链
  arm_gcc:
    enabled: true
    version: "12.3.rel1"
    variant: "arm-none-eabi"
    sources:
      windows: "https://developer.arm.com/-/media/Files/downloads/gnu/12.3.rel1/binrel/arm-gnu-toolchain-12.3.rel1-mingw-w64-i686-arm-none-eabi.zip"
      linux: "https://developer.arm.com/-/media/Files/downloads/gnu/12.3.rel1/binrel/arm-gnu-toolchain-12.3.rel1-x86_64-arm-none-eabi.tar.xz"
      macos: "https://developer.arm.com/-/media/Files/downloads/gnu/12.3.rel1/binrel/arm-gnu-toolchain-12.3.rel1-darwin-x86_64-arm-none-eabi.tar.xz"
    install_path: "${TOOLS_DIR}/gcc-arm"
    env_vars:
      PATH: "${install_path}/bin"
      ARM_GCC_PATH: "${install_path}"
    verification:
      command: "arm-none-eabi-gcc --version"
      expected_output: "12.3.1"
      
  # 调试工具
  jlink:
    enabled: true
    version: "v7.96"
    sources:
      windows: "https://www.segger.com/downloads/jlink/JLink_Windows_V796.exe"
      linux: "https://www.segger.com/downloads/jlink/JLink_Linux_V796_x86_64.deb"
      macos: "https://www.segger.com/downloads/jlink/JLink_MacOSX_V796.pkg"
    install_path: "${TOOLS_DIR}/jlink"
    env_vars:
      PATH: "${install_path}"
    verification:
      command: "JLinkExe --version"
      
  # 构建工具
  cmake:
    enabled: true
    version: "3.28.3"
    sources:
      windows: "https://github.com/Kitware/CMake/releases/download/v3.28.3/cmake-3.28.3-windows-x86_64.zip"
      linux: "https://github.com/Kitware/CMake/releases/download/v3.28.3/cmake-3.28.3-linux-x86_64.tar.gz"
      macos: "https://github.com/Kitware/CMake/releases/download/v3.28.3/cmake-3.28.3-macos-universal.tar.gz"
    install_path: "${TOOLS_DIR}/cmake"
    env_vars:
      PATH: "${install_path}/bin"
      
  # Python 环境
  python:
    enabled: true
    version: "3.11.0"
    packages:
      - "pyserial==3.5"
      - "pyocd==0.36.0"
      - "esptool==4.6.2"
      - "cmsis-pack-manager==0.5.1"
    install_path: "${TOOLS_DIR}/python"
    env_vars:
      PATH: "${install_path}/Scripts:${install_path}/bin"
      PYTHONPATH: "${install_path}/Lib/site-packages"

# 配置选项
config:
  download_timeout: 300  # 秒
  retry_count: 3
  verify_ssl: true
  offline_mode: false
  cache_dir: "${HOME}/.cache/embedded-tools"
  tools_dir: "${PROJECT_ROOT}/tools"
  
# 芯片特定配置
chip_profiles:
  gd32:
    required_tools: ["arm_gcc", "cmake", "python"]
    recommended_tools: ["jlink", "openocd"]
    
  stm32:
    required_tools: ["arm_gcc", "cmake", "python", "stlink"]
    recommended_tools: ["stm32cubeprogrammer"]
    
  ch32:
    required_tools: ["riscv_gcc", "cmake", "python"]
    recommended_tools: ["wch-link", "openocd"]
```

### 命令行参数

```bash
# 基本用法
download-tools --config tools-config.yaml
download-tools --profile gd32 --install-path ./tools

# 特定操作
download-tools --install arm_gcc cmake python
download-tools --update --tools jlink openocd
download-tools --verify --report-format json
download-tools --clean --keep-versions 3

# 配置选项
download-tools --offline --cache-dir ./local-cache
download-tools --platform windows --arch x86_64
download-tools --timeout 600 --retry 5

# 信息查询
download-tools --list-available
download-tools --check-updates
download-tools --version-info
```

## 工具配置详情

### 1. ARM GCC 工具链
- **官方源**: Arm Developer 网站
- **镜像源**: 清华大学 TUNA、中科大 USTC
- **版本策略**: 支持 LTS 版本和最新版本
- **架构支持**: arm-none-eabi、arm-eabi、aarch64-none-elf

### 2. J-Link 调试工具
- **许可证管理**: 自动处理个人/商业许可证
- **驱动安装**: 自动安装 USB 驱动程序
- **配置生成**: 自动生成 J-Link 配置文件
- **脚本支持**: 集成 J-Link 脚本功能

### 3. OpenOCD
- **芯片支持**: STM32、GD32、ESP32、RISC-V
- **接口支持**: J-Link、ST-Link、CMSIS-DAP、FTDI
- **配置模板**: 预定义目标板配置文件
- **服务管理**: 系统服务/守护进程配置

### 4. ST-Link
- **工具集**: ST-Link CLI、ST-Link Server、STM32CubeProgrammer
- **固件更新**: 自动检测和更新 ST-Link 固件
- **多平台**: Windows、Linux、macOS 统一接口

### 5. Python 环境
- **虚拟环境**: 自动创建隔离的 Python 环境
- **包管理**: 自动安装嵌入式开发相关包
- **路径隔离**: 避免与系统 Python 冲突
- **版本兼容**: 确保与工具链的兼容性

## 平台特定实现

### Windows 实现
```powershell
# PowerShell 实现示例
function Install-ArmGcc {
    param(
        [string]$Version = "12.3.rel1",
        [string]$InstallPath = "$env:USERPROFILE\.embedded-tools\gcc-arm"
    )
    
    # 下载和安装逻辑
    $url = "https://developer.arm.com/-/media/Files/downloads/gnu/$Version/binrel/arm-gnu-toolchain-$Version-mingw-w64-i686-arm-none-eabi.zip"
    $tempFile = "$env:TEMP\arm-gcc-$Version.zip"
    
    # 下载
    Invoke-WebRequest -Uri $url -OutFile $tempFile
    
    # 解压
    Expand-Archive -Path $tempFile -DestinationPath $InstallPath -Force
    
    # 环境配置
    $binPath = "$InstallPath\bin"
    $currentPath = [Environment]::GetEnvironmentVariable("PATH", "User")
    if ($currentPath -notlike "*$binPath*") {
        [Environment]::SetEnvironmentVariable("PATH", "$binPath;$currentPath", "User")
    }
    
    # 验证
    & "$binPath\arm-none-eabi-gcc.exe" --version
}
```

### Linux 实现
```bash
#!/bin/bash
# Bash 实现示例
install_arm_gcc() {
    local version="${1:-12.3.rel1}"
    local install_path="${2:-$HOME/.embedded-tools/gcc-arm}"
    
    # 检测架构
    local arch=$(uname -m)
    local url=""
    
    case $arch in
        x86_64)
            url="https://developer.arm.com/-/media/Files/downloads/gnu/$version/binrel/arm-gnu-toolchain-$version-x86_64-arm-none-eabi.tar.xz"
            ;;
        aarch64)
            url="https://developer.arm.com/-/media/Files/downloads/gnu/$version/binrel/arm-gnu-toolchain-$version-aarch64-arm-none-eabi.tar.xz"
            ;;
        *)
            echo "Unsupported architecture: $arch"
            return 1
            ;;
    esac
    
    # 下载和安装
    mkdir -p "$install_path"
    wget -q "$url" -O /tmp/arm-gcc.tar.xz
    tar -xf /tmp/arm-gcc.tar.xz -C "$install_path" --strip-components=1
    
    # 环境配置
    echo "export PATH=\"$install_path/bin:\$PATH\"" >> ~/.bashrc
    echo "export ARM_GCC_PATH=\"$install_path\"" >> ~/.bashrc
    
    # 验证
    "$install_path/bin/arm-none-eabi-gcc" --version
}
```

### macOS 实现
```bash
#!/bin/bash
# macOS 实现示例
install_arm_gcc_macos() {
    local version="${1:-12.3.rel1}"
    local install_path="${2:-$HOME/Library/EmbeddedTools/gcc-arm}"
    
    # 检测芯片架构
    local chip=$(uname -m)
    local url=""
    
    if [[ "$chip" == "arm64" ]]; then
        url="https://developer.arm.com/-/media/Files/downloads/gnu/$version/binrel/arm-gnu-toolchain-$version-darwin-arm64-arm-none-eabi.tar.xz"
    else
        url="https://developer.arm.com/-/media/Files/downloads/gnu/$version/binrel/arm-gnu-toolchain-$version-darwin-x86_64-arm-none-eabi.tar.xz"
    fi
    
    # 使用 Homebrew 风格安装
    mkdir -p "$install_path"
    curl -L "$url" | tar -xJ -C "$install_path" --strip-components=1
    
    # 环境配置
    echo "export PATH=\"$install_path/bin:\$PATH\"" >> ~/.zshrc
    echo "export ARM_GCC_PATH=\"$install_path\"" >> ~/.zshrc
    
    # 验证
    "$install_path/bin/arm-none-eabi-gcc" --version
}
```

## 安装验证

### 验证脚本示例
```python
#!/usr/bin/env python3
# verification.py
import subprocess
import sys
import json
from pathlib import Path

def verify_tool(tool_name, command, expected_output=None):
    print(f"验证工具: {tool_name}")
    print(f"命令: {command}")
    
    try:
        result = subprocess.run(
            command,
            shell=True,
            capture_output=True,
            text=True,
            timeout=30
        )
        
        if result.returncode == 0:
            print(f"✓ {tool_name} 验证成功")
            
            if expected_output:
                if expected_output in result.stdout:
                    print(f"✓ 版本匹配: {expected_output}")
                else:
                    print(f"✗ 版本不匹配")
                    print(f"  期望: {expected_output}")
                    print(f"  实际: {result.stdout[:100]}...")
                    return False
            return True
        else:
            print(f"✗ {tool_name} 验证失败")
            print(f"  错误: {result.stderr}")
            return False
            
    except subprocess.TimeoutExpired:
        print(f"✗ {tool_name} 验证超时")
        return False
    except Exception as e:
        print(f"✗ {tool_name} 验证异常: {e}")
        return False

def main():
    verification_spec = {
        "arm_gcc": {
            "command": "arm-none-eabi-gcc --version",
            "expected": "12.3.1"
        },
        "cmake": {
            "command": "cmake --version",
            "expected": "3.28"
        },
        "python": {
            "command": "python --version",
            "expected": "Python 3.11"
        },
        "jlink": {
            "command": "JLinkExe --version",
            "expected": None  # 不检查具体版本
        }
    }
    
    results = {}
    for tool, spec in verification_spec.items():
        success = verify_tool(tool, spec["command"], spec.get("expected"))
        results[tool] = "PASS" if success else "FAIL"
    
    # 生成报告
    report = {
        "timestamp": datetime.datetime.now().isoformat(),
        "platform": sys.platform,
        "results": results
    }
    
    report_file = Path("tools_verification_report.json")
    with open(report_file, "w") as f:
        json.dump(report, f, indent=2)
    
    print(f"\n验证报告已保存: {report_file}")
    
    if all(status == "PASS" for status in results.values()):
        print("✅ 所有工具验证通过")
        return 0
    else:
        print("❌ 部分工具验证失败")
        return 1

if __name__ == "__main__":
    import datetime
    sys.exit(main())
```

## 错误处理和故障排除

### 常见错误及解决方案

#### 1. 下载失败
```yaml
错误: "下载超时或网络连接失败"
解决方案:
  - 检查网络连接
  - 使用 --offline 模式（如果已有缓存）
  - 更换下载源（--source mirror）
  - 增加超时时间（--timeout 600）
  - 使用代理服务器
```

#### 2. 安装权限问题
```yaml
错误: "权限被拒绝" 或 "需要管理员权限"
解决方案:
  - Windows: 以管理员身份运行
  - Linux/macOS: 使用 sudo 或修改安装路径到用户目录
  - 使用 --install-path 指定用户可写目录
```

#### 3. 版本兼容性问题
```yaml
错误: "工具版本不兼容"
解决方案:
  - 使用 --version 指定兼容版本
  - 查看版本兼容性矩阵
  - 更新相关依赖工具
  - 使用虚拟环境隔离
```

#### 4. 环境配置问题
```yaml
错误: "命令未找到" 或 "PATH 配置错误"
解决方案:
  - 重新运行环境配置（--configure-env）
  - 手动添加工具路径到 PATH
  - 重启终端或 IDE
  - 检查 shell 配置文件（.bashrc, .zshrc）
```

### 调试模式
```bash
# 启用详细日志
download-tools --verbose --debug --log-file install.log

# 仅模拟运行
download-tools --dry-run --config tools-config.yaml

# 生成诊断报告
download-tools --diagnose --output diagnose.json
```

## 集成示例

### 与 CMake 集成
```cmake
# CMakeLists.txt 中的工具检查
find_program(ARM_GCC arm-none-eabi-gcc)
if(NOT ARM_GCC)
    message(WARNING "ARM GCC 工具链未找到")
    message(STATUS "运行以下命令安装:")
    message(STATUS "  download-tools --install arm_gcc")
    message(STATUS "或使用系统包管理器:")
    message(STATUS "  # Ubuntu/Debian")
    message(STATUS "  sudo apt-get install gcc-arm-none-eabi")
    message(STATUS "  # macOS")
    message(STATUS "  brew install arm-none-eabi-gcc")
endif()

find_program(CMAKE_EXE cmake)
if(NOT CMAKE_EXE)
    message(WARNING "CMake 未找到")
    message(STATUS "运行以下命令安装:")
    message(STATUS "  download-tools --install cmake")
endif()

# 自定义目标：安装开发工具
add_custom_target(install-tools
    COMMAND download-tools --profile ${PROJECT_CHIP} --install-path ${CMAKE_SOURCE_DIR}/tools
    COMMENT "安装嵌入式开发工具链"
)
```

### 与 CI/CD 集成
```yaml
# .github/workflows/build.yml
name: Embedded Build

on: [push, pull_request]

jobs:
  setup-tools:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Embedded Tools
        run: |
          download-tools --profile stm32 \
            --install-path ./tools \
            --cache-dir ./cache \
            --no-interactive
          
      - name: Verify Installation
        run: |
          download-tools --verify --report-format github
          
      - name: Build Project
        run: |
          source ./tools/env.sh
          cmake -B build -S .
          cmake --build build
          
      - name: Upload Tools Cache
        uses: actions/cache@v3
        with:
          path: ./cache
          key: ${{ runner.os }}-embedded-tools-${{ hashFiles('tools-config.yaml') }}
```

### 与 VS Code 集成
```json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Install Development Tools",
      "type": "shell",
      "command": "download-tools",
      "args": [
        "--profile",
        "gd32",
        "--install-path",
        "${workspaceFolder}/.vscode/tools",
        "--quiet"
      ],
      "problemMatcher": []
    },
    {
      "label": "Setup Environment",
      "type": "shell",
      "command": "${workspaceFolder}/.vscode/tools/env.bat",
      "windows": {
        "command": "${workspaceFolder}/.vscode/tools/env.bat"
      },
      "linux": {
        "command": "source ${workspaceFolder}/.vscode/tools/env.sh"
      },
      "macos": {
        "command": "source ${workspaceFolder}/.vscode/tools/env.sh"
      }
    }
  ],
  "settings": {
    "terminal.integrated.env.windows": {
      "PATH": "${workspaceFolder}/.vscode/tools/gcc-arm/bin;${env:PATH}"
    },
    "terminal.integrated.env.linux": {
      "PATH": "${workspaceFolder}/.vscode/tools/gcc-arm/bin:${env:PATH}"
    },
    "terminal.integrated.env.osx": {
      "PATH": "${workspaceFolder}/.vscode/tools/gcc-arm/bin:${env:PATH}"
    }
  }
}
```

## 维护指南

### 版本管理策略
1. **LTS 版本**: 生产环境使用长期支持版本
2. **最新版本**: 开发环境可尝试最新功能
3. **版本锁定**: 通过配置文件锁定特定版本
4. **平滑升级**: 支持渐进式版本升级

### 配置文件更新
```bash
# 检查配置更新
download-tools --check-config-updates

# 应用配置更新
download-tools --update-config --backup

# 迁移旧配置
download-tools --migrate-config --from-version 1.0.0
```

### 缓存管理
```bash
# 清理缓存
download-tools --clean-cache --keep-versions 3

# 导出缓存（用于离线安装）
download-tools --export-cache ./offline-cache.tar.gz

# 导入缓存
download-tools --import-cache ./offline-cache.tar.gz
```

### 性能优化
1. **并行下载**: 支持多工具并行下载
2. **断点续传**: 支持下载中断后恢复
3. **增量更新**: 仅下载变化的文件
4. **本地镜像**: 支持搭建本地工具镜像服务器

## 安全考虑

### 安全最佳实践
1. **完整性验证**: 所有下载文件必须进行 SHA256 校验
2. **来源验证**: 优先使用官方源和可信镜像
3. **权限最小化**: 工具安装使用最小必要权限
4. **隔离运行**: 高风险工具在沙箱或容器中运行
5. **审计日志**: 记录所有安装和配置操作

### 安全配置示例
```yaml
security:
  checksum_verification: true
  allowed_sources:
    - "https://developer.arm.com"
    - "https://github.com/Kitware/CMake/releases"
    - "https://www.segger.com/downloads/jlink"
  forbidden_sources:
    - "http://"  # 禁止非加密连接
  require_signed: false  # 未来可启用签名验证
  sandbox_mode: true  # 在隔离环境中运行安装脚本
```

## 扩展开发

### 添加新工具支持
```python
# 新工具插件示例
from download_tools.core import ToolPlugin

class NewToolPlugin(ToolPlugin):
    name = "new_tool"
    description = "新工具支持插件"
    
    def get_download_url(self, platform, version):
        # 返回平台特定的下载URL
        urls = {
            "windows": f"https://example.com/new-tool-{version}-windows.zip",
            "linux": f"https://example.com/new-tool-{version}-linux.tar.gz",
            "macos": f"https://example.com/new-tool-{version}-macos.pkg"
        }
        return urls.get(platform)
    
    def install(self, install_path, downloaded_file):
        # 实现安装逻辑
        import shutil
        import zipfile
        
        if downloaded_file.endswith('.zip'):
            with zipfile.ZipFile(downloaded_file, 'r') as zip_ref:
                zip_ref.extractall(install_path)
        elif downloaded_file.endswith('.tar.gz'):
            import tarfile
            with tarfile.open(downloaded_file, 'r:gz') as tar_ref:
                tar_ref.extractall(install_path)
        
        # 设置执行权限（Linux/macOS）
        if platform.system() != "Windows":
            bin_file = os.path.join(install_path, "bin", "new-tool")
            os.chmod(bin_file, 0o755)
    
    def verify(self, install_path):
        # 实现验证逻辑
        import subprocess
        result = subprocess.run(
            [os.path.join(install_path, "bin", "new-tool"), "--version"],
            capture_output=True,
            text=True
        )
        return result.returncode == 0

# 注册插件
ToolRegistry.register(NewToolPlugin())
```

## 总结

`download-tools` 技能为嵌入式开发提供了一套完整的工具链管理解决方案。通过自动化工具下载、安装、配置和验证，显著提高了开发环境的搭建效率和一致性。无论是个人开发者还是团队协作，都能从中受益：

1. **一致性**: 确保团队成员使用相同的工具版本
2. **可重复性**: 开发环境可以快速重建和复制
3. **可维护性**: 工具更新和迁移更加容易
4. **安全性**: 通过验证和审计保障工具安全
5. **生产力**: 减少环境配置时间，专注开发工作

作为 OpenClaw 集成专家，我强烈推荐在嵌入式项目中采用此技能管理开发工具链，这将为项目的长期维护和团队协作奠定坚实基础。

---

*最后更新: 2024-01-15*  
*版本: 2.0.0*  
*作者: OpenClaw 集成专家团队*