hm/lishanpi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
lishanpi/.trae/skills/download-tools/SKILL.md
T

718 lines
21 KiB
Markdown
Raw Permalink Normal View History

Initial commit: LSPi (LiangShanPi) project
2026-04-26 16:24:42 +08:00
***
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 集成专家团队*
Reference in New Issue Copy Permalink