lishanpi/.trae/skills/download-lib/SKILL.md

***
name: "download-lib"
description: "下载嵌入式开发所需的库文件（STM32/GD32/CH32等）。在创建新工程、更新库版本、切换芯片平台或需要确保团队库版本一致时调用此技能。"
version: 1.1.0
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

# DOWNLOAD-LIB 技能

该技能用于自动化下载嵌入式开发所需的硬件库文件，支持多种微控制器平台，并提供完整的工程集成方案。

## 技能概述

`download-lib` 技能是一个嵌入式开发辅助工具，专门用于管理和下载微控制器硬件外设库。它解决了嵌入式开发中常见的库文件管理问题：
- 不同芯片平台的库文件获取
- 库版本管理和一致性
- 工程集成自动化
- 团队协作中的库同步

## 功能特点

### 支持的平台
- **STM32系列**：STM32F0/F1/F2/F3/F4/F7/H7等全系列
- **GD32系列**：GD32F1/F2/F3/F4/F5等全系列
- **CH32系列**：CH32V/V3/F1/F2等全系列
- **其他ARM Cortex-M系列MCU**

### 核心功能
1. **智能下载**：自动识别芯片型号并下载对应的库文件
2. **版本管理**：支持特定版本、最新版本和版本锁定
3. **完整性校验**：下载后验证文件完整性（MD5/SHA256）
4. **工程集成**：自动更新构建系统（CMake/Makefile）
5. **离线支持**：支持本地缓存和离线安装模式

## 调用时机

在以下情况下调用此技能：

### 1. 新工程创建
- 创建基于STM32/GD32/CH32的新嵌入式项目时
- 需要快速建立工程框架和依赖库时

### 2. 库版本更新
- 需要更新现有工程的外设库到新版本时
- 修复已知bug或使用新特性时

### 3. 平台迁移
- 项目从一种MCU迁移到另一种MCU时
- 需要同时支持多种芯片平台时

### 4. 团队协作
- 确保团队成员使用相同的库版本时
- 新成员快速搭建开发环境时

### 5. 离线开发准备
- 准备离线开发环境，预先下载所有依赖库
- 为无网络环境准备开发包时

## 工作流程

### 完整工作流程
```mermaid
graph TD
    A[用户请求下载库文件] --> B{芯片类型选择}
    B --> C[STM32]
    B --> D[GD32]
    B --> E[CH32]
    C --> F[选择具体系列]
    D --> F
    E --> F
    F --> G[选择版本号]
    G --> H[选择下载源]
    H --> I[执行下载]
    I --> J[完整性校验]
    J --> K[工程集成]
    K --> L[生成报告]
    L --> M[完成]
```

### 详细步骤

#### 步骤1：参数收集
1. **芯片类型**：用户选择目标芯片平台（STM32/GD32/CH32）
2. **芯片系列**：指定具体芯片系列（如GD32F450、STM32F407等）
3. **库版本**：选择库版本号（如v1.0.0、latest等）
4. **下载源**：选择下载来源（官方GitHub、厂商网站、镜像站等）
5. **目标目录**：指定库文件存放位置（默认：`项目根目录/libs/`）

#### 步骤2：库文件下载
1. **源地址解析**：根据芯片类型和版本构建下载URL
   - STM32：`https://github.com/STMicroelectronics/STM32CubeF4`
   - GD32：`https://github.com/GigaDevice/GD32F4xx_Standard_Peripheral_Lib`
   - CH32：`https://github.com/openwch/ch32`（示例）
2. **下载方式**：
   - Git clone（推荐，支持版本管理）
   - 直接下载ZIP包
   - 使用wget/curl命令行工具
3. **进度显示**：实时显示下载进度和状态

#### 步骤3：文件处理
1. **解压与整理**：如有需要，解压文件并整理目录结构
2. **文件筛选**：只保留必要的库文件，移除示例、文档等非必需文件
3. **目录规范化**：按照标准目录结构组织文件
   ```
   libs/
   ├── CMSIS/               # ARM CMSIS核心库
   ├── thirdparty/
   │   └── GD32F4xx/        # 具体芯片的外设库
   │       ├── Include/
   │       ├── Source/
   │       └── README.md
   └── version.txt          # 版本信息文件
   ```

#### 步骤4：完整性校验
1. **哈希校验**：计算下载文件的MD5或SHA256值
2. **大小验证**：检查文件大小是否符合预期
3. **结构验证**：验证目录结构是否完整
4. **关键文件检查**：确保核心头文件和源文件存在

#### 步骤5：工程集成
1. **构建系统更新**：
   - **CMake**：更新`CMakeLists.txt`，添加库文件路径
   - **Makefile**：更新编译规则和包含路径
   - **Keil/IAR**：生成对应的工程文件（可选）
2. **头文件路径配置**：自动添加必要的头文件搜索路径
3. **依赖关系配置**：设置库文件之间的依赖关系

#### 步骤6：报告生成
1. **下载摘要**：显示下载的文件数量、大小和时间
2. **版本信息**：记录下载的库版本和芯片信息
3. **集成状态**：显示工程集成是否成功
4. **问题提示**：如有问题，提供解决方案建议

## 参数定义

### 输入参数
```yaml
# 必选参数
chip_type:          # 芯片类型
  type: enum
  values: [stm32, gd32, ch32, other]
  required: true
  
chip_series:        # 芯片系列
  type: string
  examples: ["GD32F450", "STM32F407", "CH32V307"]
  required: true

# 可选参数
library_version:    # 库版本
  type: string
  default: "latest"
  examples: ["v1.0.0", "v2.1.3", "latest"]

download_source:    # 下载源
  type: enum
  values: [github, official, custom]
  default: "github"

target_directory:   # 目标目录
  type: string
  default: "./libs/"

skip_integration:   # 跳过工程集成
  type: boolean
  default: false

offline_mode:       # 离线模式
  type: boolean
  default: false
  description: "从本地缓存安装，无需网络"
```

### 输出结果
```yaml
success: true/false
message: "操作结果描述"
downloaded_files:
  count: 42
  total_size: "15.7MB"
  duration: "45秒"
library_info:
  name: "GD32F4xx Standard Peripheral Library"
  version: "v1.0.0"
  chip: "GD32F450VG"
  release_date: "2023-06-15"
integration_status:
  cmake_updated: true
  include_paths_added: ["libs/thirdparty/GD32F4xx/Include"]
  source_files_added: ["libs/thirdparty/GD32F4xx/Source/*.c"]
```

## 示例和模板

### 示例1：下载GD32F4xx库
```bash
# 通过技能调用下载GD32F4xx最新版本
download-lib --chip-type gd32 --chip-series GD32F450 --version latest
```

**执行结果**：
```
✅ 开始下载GD32F4xx库...
📦 下载源：https://github.com/GigaDevice/GD32F4xx_Standard_Peripheral_Lib
🔍 选择版本：latest (v1.0.0)
⬇️ 下载中：15.7MB [██████████] 100%
✅ 下载完成：42个文件，耗时45秒
🔒 完整性校验：通过（SHA256匹配）
📁 文件组织：libs/thirdparty/GD32F4xx/
🛠️  工程集成：CMakeLists.txt已更新
📊 报告生成：download_report_20250409_142356.json
🎉 完成！GD32F450库已就绪。
```

### 示例2：下载特定版本的STM32库
```bash
# 下载STM32F4xx v1.27.0版本
download-lib \
  --chip-type stm32 \
  --chip-series STM32F407 \
  --version v1.27.0 \
  --target-directory ./vendor/stm32 \
  --skip-integration
```

### 示例3：离线模式（从缓存安装）
```bash
# 从本地缓存安装，无需网络连接
download-lib \
  --chip-type gd32 \
  --chip-series GD32F450 \
  --offline-mode \
  --cache-directory ~/.cache/embedded-libs
```

### 模板1：Bash下载脚本
```bash
#!/bin/bash
# download_library.sh - 库文件下载脚本模板

set -e  # 出错时退出

# 配置参数
CHIP_TYPE=${1:-gd32}
CHIP_SERIES=${2:-GD32F450}
VERSION=${3:-latest}
TARGET_DIR=${4:-./libs}
CACHE_DIR="${HOME}/.cache/embedded-libs"

# 下载URL映射
declare -A LIBRARY_URLS=(
  ["gd32"]="https://github.com/GigaDevice/GD32F4xx_Standard_Peripheral_Lib"
  ["stm32_f4"]="https://github.com/STMicroelectronics/STM32CubeF4"
  ["ch32_v"]="https://github.com/openwch/ch32"
)

# 获取下载URL
get_download_url() {
  local chip=$1
  local series=$2
  
  case $chip in
    "gd32")
      echo "${LIBRARY_URLS[gd32]}"
      ;;
    "stm32")
      # 根据系列选择具体的STM32库
      if [[ $series == STM32F4* ]]; then
        echo "${LIBRARY_URLS[stm32_f4]}"
      else
        echo "错误：不支持的STM32系列: $series" >&2
        exit 1
      fi
      ;;
    *)
      echo "错误：不支持的芯片类型: $chip" >&2
      exit 1
      ;;
  esac
}

# 主函数
main() {
  echo "🔍 芯片: $CHIP_TYPE $CHIP_SERIES"
  echo "📦 版本: $VERSION"
  
  # 创建目标目录
  mkdir -p "$TARGET_DIR"
  
  # 获取下载URL
  DOWNLOAD_URL=$(get_download_url "$CHIP_TYPE" "$CHIP_SERIES")
  echo "🌐 下载源: $DOWNLOAD_URL"
  
  # 执行下载
  if [[ "$VERSION" == "latest" ]]; then
    git clone --depth 1 "$DOWNLOAD_URL" "${TARGET_DIR}/temp"
  else
    git clone --branch "$VERSION" --depth 1 "$DOWNLOAD_URL" "${TARGET_DIR}/temp"
  fi
  
  # 整理文件
  organize_files
  
  # 清理临时文件
  rm -rf "${TARGET_DIR}/temp"
  
  echo "✅ 下载完成"
}

# 文件整理函数
organize_files() {
  local temp_dir="${TARGET_DIR}/temp"
  
  # GD32库的特殊处理
  if [[ "$CHIP_TYPE" == "gd32" ]]; then
    # 复制必要的文件
    mkdir -p "${TARGET_DIR}/thirdparty/GD32F4xx"
    cp -r "${temp_dir}/Firmware/GD32F4xx_standard_peripheral/Include" \
      "${TARGET_DIR}/thirdparty/GD32F4xx/"
    cp -r "${temp_dir}/Firmware/GD32F4xx_standard_peripheral/Source" \
      "${TARGET_DIR}/thirdparty/GD32F4xx/"
  fi
  
  # 添加其他芯片类型的处理逻辑...
}

# 执行主函数
main "$@"
```

### 模板2：CMake集成配置
```cmake
# CMakeLists.txt - 库集成模板
cmake_minimum_required(VERSION 3.16)

# 检测库文件是否存在
macro(check_required_library lib_name lib_path)
  if(NOT EXISTS ${lib_path})
    message(WARNING "缺少库文件: ${lib_name}")
    message(STATUS "请运行: download-lib --chip-type gd32 --chip-series GD32F450")
    set(${lib_name}_FOUND FALSE)
  else()
    set(${lib_name}_FOUND TRUE)
    message(STATUS "找到库: ${lib_name}")
  endif()
endmacro()

# 检查GD32库
check_required_library(GD32F4XX_LIB "${CMAKE_SOURCE_DIR}/libs/thirdparty/GD32F4xx")

if(GD32F4XX_LIB_FOUND)
  # 添加包含路径
  include_directories(
    ${CMAKE_SOURCE_DIR}/libs/thirdparty/GD32F4xx/Include
    ${CMAKE_SOURCE_DIR}/libs/CMSIS/Core/Include
    ${CMAKE_SOURCE_DIR}/libs/CMSIS/GD/GD32F4xx/Include
  )
  
  # 添加源文件
  file(GLOB GD32_SOURCES
    ${CMAKE_SOURCE_DIR}/libs/thirdparty/GD32F4xx/Source/*.c
  )
  
  # 添加到工程源文件列表
  list(APPEND PROJECT_SOURCES ${GD32_SOURCES})
endif()

# 类似的，可以添加其他库的检查
```

### 模板3：Python下载脚本
```python
#!/usr/bin/env python3
# download_lib.py - Python版本库下载器

import os
import sys
import requests
import hashlib
import zipfile
import json
from pathlib import Path

class LibraryDownloader:
    """库文件下载器"""
    
    def __init__(self, chip_type, chip_series, version="latest"):
        self.chip_type = chip_type
        self.chip_series = chip_series
        self.version = version
        self.base_urls = {
            "gd32": "https://api.github.com/repos/GigaDevice/GD32F4xx_Standard_Peripheral_Lib",
            "stm32": "https://api.github.com/repos/STMicroelectronics/STM32CubeF4",
        }
    
    def download(self, target_dir="libs"):
        """执行下载"""
        print(f"下载 {self.chip_type} {self.chip_series} 库...")
        
        # 获取下载信息
        download_info = self.get_download_info()
        
        # 创建目标目录
        target_path = Path(target_dir)
        target_path.mkdir(parents=True, exist_ok=True)
        
        # 下载文件
        self.download_file(download_info['url'], target_path)
        
        # 验证完整性
        if self.verify_integrity(target_path, download_info.get('checksum')):
            print("✅ 完整性验证通过")
        else:
            print("⚠️  完整性验证失败")
        
        # 生成版本文件
        self.generate_version_file(target_path, download_info)
        
        return True
    
    def get_download_info(self):
        """获取下载信息"""
        # 这里实现具体的API调用逻辑
        # 返回包含url、version、checksum等信息的字典
        pass
    
    # 其他方法实现...

if __name__ == "__main__":
    # 使用示例
    downloader = LibraryDownloader("gd32", "GD32F450", "latest")
    downloader.download()
```

## 错误处理

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

#### 错误1：网络连接失败
```
❌ 错误：无法连接到下载服务器
```
**可能原因**：
- 网络连接问题
- 下载源URL变更
- 防火墙或代理限制

**解决方案**：
1. 检查网络连接
2. 使用镜像源：`--download-source mirror`
3. 离线模式：`--offline-mode --cache-dir /path/to/cache`
4. 手动下载并指定本地路径

#### 错误2：版本不存在
```
❌ 错误：版本 v2.5.0 不存在
```
**可能原因**：
- 版本号输入错误
- 该版本已被删除
- 芯片系列不支持该版本

**解决方案**：
1. 查看可用版本：`download-lib --list-versions gd32 GD32F450`
2. 使用最新版本：`--version latest`
3. 指定正确的版本格式

#### 错误3：磁盘空间不足
```
❌ 错误：磁盘空间不足，需要 200MB，可用 50MB
```
**解决方案**：
1. 清理磁盘空间
2. 指定其他存储位置：`--target-directory /mnt/external/libs`
3. 仅下载必要文件：`--minimal`（只下载核心库文件）

#### 错误4：权限不足
```
❌ 错误：无法创建目录 /usr/local/libs，权限被拒绝
```
**解决方案**：
1. 使用用户目录：`--target-directory ~/projects/libs`
2. 使用sudo权限（谨慎）
3. 更改目录权限

### 错误恢复机制

#### 断点续传
```bash
# 支持断点续传
download-lib --resume --partial-dir ./download-tmp
```

#### 完整性恢复
```bash
# 如果下载中断，可以恢复完整性检查
download-lib --verify-only --repair
```

## 最佳实践

### 1. 版本锁定
```bash
# 在生产环境中使用固定版本
download-lib --chip-type gd32 --chip-series GD32F450 --version v1.0.0
```

### 2. 团队一致性
```bash
# 创建版本锁定文件
download-lib --generate-lockfile > library-lock.json

# 其他成员使用锁文件恢复
download-lib --from-lockfile library-lock.json
```

### 3. CI/CD集成
```yaml
# .gitlab-ci.yml 示例
stages:
  - setup
  
setup_libraries:
  stage: setup
  script:
    - download-lib --chip-type gd32 --chip-series GD32F450 --version latest
    - download-lib --chip-type stm32 --chip-series STM32F103 --version v1.8.0
  artifacts:
    paths:
      - libs/
    expire_in: 30 days
```

### 4. 离线开发环境
```bash
# 在可联网环境中准备离线包
download-lib --chip-type gd32 --chip-series GD32F450 --bundle --output gd32-bundle.tar.gz

# 在离线环境中安装
download-lib --install-bundle gd32-bundle.tar.gz
```

## 扩展功能

### 插件系统
支持通过插件扩展新的芯片平台：

```bash
# 注册新的芯片支持
download-lib --register-chip \
  --name AT32 \
  --url-template "https://github.com/ArteryTek/AT32F4xx_Library" \
  --file-structure "Firmware/AT32F4xx_standard_peripheral"
```

### 自定义下载源
```bash
# 使用自定义的下载源
download-lib \
  --chip-type gd32 \
  --download-source custom \
  --custom-url "http://internal-mirror.company.com/gd32-libs"
```

### 批量操作
```bash
# 批量下载多个库
download-lib --batch libraries.json
```

**libraries.json**:
```json
{
  "libraries": [
    {
      "chip_type": "gd32",
      "chip_series": "GD32F450",
      "version": "latest"
    },
    {
      "chip_type": "stm32", 
      "chip_series": "STM32F103",
      "version": "v1.8.0"
    }
  ]
}
```

## 与当前工程的集成示例

### ServoTest工程集成
对于您的`ServoTest`工程（基于GD32F450VG），技能可以：

1. **确保库版本一致**：
   ```bash
   # 检查当前库版本
   download-lib --check-version --chip-type gd32 --chip-series GD32F450
   
   # 更新到指定版本
   download-lib --chip-type gd32 --chip-series GD32F450 --version v1.0.0
   ```

2. **多平台支持**：
   ```bash
   # 如果需要支持STM32作为备选平台
   download-lib --chip-type stm32 --chip-series STM32F407 --target-directory ./libs/stm32-backup
   ```

3. **依赖管理**：
   ```bash
   # 生成依赖报告
   download-lib --dependencies --output deps.html
   ```

## 更新日志

### v1.1.0 (2024-04-09)
- 完全重写技能文档
- 添加详细的工作流程和参数定义
- 提供多个示例脚本和模板
- 完善错误处理和最佳实践
- 添加与ServoTest工程的集成示例

### v1.0.0 (初始版本)
- 基础技能框架
- 支持STM32/GD32/CH32芯片
- 基本的下载功能

---

**技能维护者**：嵌入式系统开发团队  
**最后更新**：2024-04-09  
**技能状态**：✅ 生产就绪