Управление зависимостями навыков

Скрипты навыков обычно требуют сторонних библиотек. То, как объявлять, устанавливать и фиксировать эти зависимости, — основа надёжной работы навыка.

Файлы объявления зависимостей

Создайте в каталоге scripts/ навыкаrequirements.txt(Python) илиpackage.json(Node.js), чтобы централизованно объявить все зависимости.

Зависимости 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 请求

Зависимости Node.js: package.json

Пример

{
  "name": "my-skill-scripts",
  "version": "1.0.0",
  "description": Зависимости Node.js для скриптов навыков,
  "dependencies": {
    "xlsx": "^0.18.5",
    "puppeteer": "^21.0.0"
  }
}

Объясните способ установки в SKILL.md

## 依赖安装

首次使用前，运行以下命令安装 Python 依赖：

```bash
pip install -r scripts/requirements.txt --break-system-packages
```

若运行环境已预装依赖，可跳过此步骤。

Автоматически устанавливать зависимости в скрипте

Для навыков, которые должны запускаться без конфигурации, можно добавить самопроверку зависимостей и логику автоматической установки в начале скрипта.

Пример

# Путь к файлу: scripts/auto_deps.py
import subprocess
import sys
import importlib

# Определите список зависимостей: (имя для pip install, имя импорта, требование к версии)
ЗАВИСИМОСТИ = [
    ("pandas",         "pandas",    ">=2.0"),
    ("openpyxl",       "openpyxl",  ">=3.0"),
    ("python-docx",    "docx",      None),     # Нет требований к версии
]

def install_if_missing(pip_name: str, import_name: str) -> bool:
    """Проверить и установить пакеты зависимостей при необходимости"""
    try:
        importlib.import_module(import_name)
        return True   # Уже установлено, возвращаем сразу
    except ImportError:
        print(f"Установка: {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"Установка выполнена успешно: {pip_name}")
            return True
        print(f"Установка не удалась: {pip_name}\n{result.stderr}")
        return False

def ensure_all_deps() -> bool:
    """Убедиться, что все зависимости установлены"""
    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"Не удалось установить следующие зависимости: {', '.join(failed)}")
        return False
    return True

if __name__ == "__main__":
    if not ensure_all_deps():
        sys.exit(1)

    # После того как зависимости будут готовы, выполните логику как обычно
    import pandas as pd
    print("Все зависимости готовы, начинаем выполнение...")
正在安装：python-docx...
安装成功：python-docx
所有依赖已就绪，开始执行...

Стратегии разрешения конфликтов версий

Когда требуемая Skill версия пакета конфликтует с существующей системной версией, есть несколько способов решения:

Стратегия Подход Применимый сценарий
Нестрогие требования к версиям Используйте >= вместо ==, чтобы разрешить более высокие версии В большинстве сценариев, хорошая совместимость
Виртуальное окружение Установка в venv, изолированно от системы Строгие требования к версиям
Использовать существующую системную версию Не фиксируйте версию; используйте установленную в системе версию Зависимости — распространённые библиотеки, и различия версий оказывают минимальное влияние

Создание виртуального окружения (необязательно)

Пример

# Создание виртуального окружения в каталоге Skill
python3 -m venv scripts/.venv

# Активация виртуального окружения
source scripts/.venv/bin/activate

# Установка зависимостей в виртуальном окружении
pip install -r scripts/requirements.txt

# Запуск скрипта в виртуальном окружении
python scripts/process.py

В среде выполнения Claude виртуальное окружение обычно не требуется, поскольку каждая сессия относительно изолирована. Виртуальные окружения в основном используются во время локальной разработки, чтобы избежать конфликтов с другими проектами на машине разработчика.

Стандарты документирования зависимостей

В SKILL.md или отдельном README все внешние зависимости должны быть четко перечислены, чтобы пользователи могли понять требования перед установкой.

## 系统要求

### 运行环境
- Python 3.8 或更高版本
- pip（Python 包管理工具）

### Python 依赖
| 包名 | 版本 | 用途 |
|------|------|------|
| pandas | >=2.0 | 数据读取与处理 |
| openpyxl | >=3.0 | Excel 文件读写 |
| python-docx | 任意 | Word 文档生成 |

### 系统工具（可选）
- pandoc：格式转换（apt-get install pandoc）
Другие расширения