Gestión de dependencias de Skills
Los scripts de Skill suelen requerir librerías de terceros. Cómo declarar, instalar y fijar estas dependencias es la base para garantizar el funcionamiento fiable de un Skill.
Archivo de declaración de dependencias
Crear en el directorio scripts/ del Skillrequirements.txt(Python) opackage.json(Node.js) para declarar todas las dependencias de forma centralizada.
Dependencias de Python: requirements.txt
# 文件路径:scripts/requirements.txt # 格式:包名==版本号(锁定版本,确保可重复安装) pandas==2.1.4 # 数据处理 openpyxl==3.1.2 # Excel 读写 pypdf==3.17.0 # PDF 处理 python-docx==1.1.0 # Word 文档处理 requests==2.31.0 # HTTP 请求
Dependencias de Node.js: package.json
Ejemplo
"name": "my-skill-scripts",
"version": "1.0.0",
"description": "Dependencias de Node.js para scripts de Skill",
"dependencies": {
"xlsx": "^0.18.5",
"puppeteer": "^21.0.0"
}
}
Explicar el método de instalación en SKILL.md
## 依赖安装 首次使用前,运行以下命令安装 Python 依赖: ```bash pip install -r scripts/requirements.txt --break-system-packages ``` 若运行环境已预装依赖,可跳过此步骤。
Instalar dependencias automáticamente en el script
Para Skills que necesitan ejecutarse con configuración cero, se puede añadir lógica de autocomprobación e instalación automática de dependencias al inicio del script.
Ejemplo
import subprocess
import sys
import importlib
# Definir lista de dependencias: (nombre de instalación pip, nombre de import, requisito de versión)
DEPENDENCIES = [
("pandas", "pandas", ">=2.0"),
("openpyxl", "openpyxl", ">=3.0"),
("python-docx", "docx", None), # Sin requisito de versión
]
def install_if_missing(pip_name: str, import_name: str) -> bool:
"""Comprobar e instalar los paquetes de dependencias según sea necesario"""
try:
importlib.import_module(import_name)
return True # Ya está instalado, devolver directamente
except ImportError:
print(f"Instalando: {pip_name}...")
result = subprocess.run(
[sys.executable, "-m", "pip", "install", pip_name,
"--break-system-packages", "--quiet"],
capture_output=True, text=True
)
if result.returncode == 0:
print(f"Instalación exitosa: {pip_name}")
return True
print(f"Fallo en la instalación: {pip_name}"\n{result.stderr}")
return False
def ensure_all_deps() -> bool:
"""Asegurarse de que todas las dependencias estén instaladas"""
failed = []
for pip_name, import_name, _ in DEPENDENCIES:
if not install_if_missing(pip_name, import_name):
failed.append(pip_name)
if failed:
print(f"Las siguientes dependencias fallaron al instalarse: {', '.join(failed)}")
return False
return True
if __name__ == "__main__":
if not ensure_all_deps():
sys.exit(1)
# Cuando las dependencias estén listas, ejecutar la lógica normalmente
import pandas as pd
print("Todas las dependencias están listas, comenzando la ejecución...")
正在安装:python-docx... 安装成功:python-docx 所有依赖已就绪,开始执行...
Estrategias para manejar conflictos de versiones
Cuando la versión de un paquete del que depende un Skill entra en conflicto con la versión ya existente en el sistema, se pueden seguir los siguientes enfoques:
| Estrategia | Método | Escenario aplicable |
|---|---|---|
| Requisito de versión flexible | Usar >= en lugar de ==, permitir versiones superiores | La mayoría de los escenarios, buena compatibilidad |
| Entorno virtual | Instalar en venv, aislado del sistema | Requisitos estrictos de versión |
| Usar la versión ya existente en el sistema | No fijar la versión, usar la versión instalada en el sistema | La dependencia es una librería común y las diferencias de versión tienen poco impacto |
Crear un entorno virtual (opcional)
Ejemplo
python3 -m venv scripts/.venv
# Activar el entorno virtual
source scripts/.venv/bin/activate
# Instalar dependencias en el entorno virtual
pip install -r scripts/requirements.txt
# Ejecutar el script en el entorno virtual
python scripts/process.py
En el entorno de ejecución de Claude, generalmente no se necesita un entorno virtual, porque cada sesión está relativamente aislada. El entorno virtual se utiliza principalmente en la etapa de desarrollo local, para evitar conflictos con otros proyectos en la máquina de desarrollo.
Normas de documentación de dependencias
En SKILL.md o en un README independiente, se deben enumerar claramente todas las dependencias externas, para que los usuarios puedan conocer los requisitos antes de la instalación.
## 系统要求 ### 运行环境 - Python 3.8 或更高版本 - pip(Python 包管理工具) ### Python 依赖 | 包名 | 版本 | 用途 | |------|------|------| | pandas | >=2.0 | 数据读取与处理 | | openpyxl | >=3.0 | Excel 文件读写 | | python-docx | 任意 | Word 文档生成 | ### 系统工具(可选) - pandoc:格式转换(apt-get install pandoc)Otras extensiones