Skills 依赖管理
Skill 脚本通常需要第三方库，如何声明、安装和锁定这些依赖，是保证 Skill 可靠运行的基础。
依赖声明文件
在 Skill 的 scripts/ 目录下创建 requirements.txt（Python）或 package.json（Node.js），集中声明所有依赖。
Python 依赖：requirements.txt
bash
# 文件路径：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
实例
json
{
"name": "my-skill-scripts",
"version": "1.0.0",
"description": "Skill 脚本的 Node.js 依赖",
"dependencies": {
"xlsx": "^0.18.5",
"puppeteer": "^21.0.0"
}
}在 SKILL.md 中说明安装方式
bash
## 依赖安装
首次使用前，运行以下命令安装 Python 依赖：
```bash
pip install -r scripts/requirements.txt --break-system-packages
```
若运行环境已预装依赖，可跳过此步骤。在脚本中自动安装依赖
对于需要零配置运行的 Skill，可以在脚本开头加入依赖自检和自动安装逻辑。
实例
python
# 文件路径：scripts/auto_deps.py
import subprocess
import sys
import importlib
# 定义依赖列表：(pip安装名, import名称, 版本要求)
DEPENDENCIES = [
("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("所有依赖已就绪，开始执行...")bash
正在安装：python-docx...
安装成功：python-docx
所有依赖已就绪，开始执行...版本冲突的处理策略
当 Skill 依赖的包版本与系统已有版本冲突时，有以下几种处理方式：
| 策略 | 做法 | 适用场景 |
|---|---|---|
| 宽松版本要求 | 使用 >=而非==，允许更高版本 | 大多数场景，兼容性好 |
| 虚拟环境 | 在 venv 中安装，与系统隔离 | 对版本有严格要求 |
| 使用系统已有版本 | 不锁定版本，使用系统安装的版本 | 依赖为常用库且版本差异影响小 |
创建虚拟环境（可选）
实例
bash
# 在 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 中，应清晰列出所有外部依赖，便于用户在安装前了解要求。
bash
## 系统要求
### 运行环境
- Python 3.8 或更高版本
- pip（Python 包管理工具）
### Python 依赖
| 包名 | 版本 | 用途 |
|------|------|------|
| pandas | >=2.0 | 数据读取与处理 |
| openpyxl | >=3.0 | Excel 文件读写 |
| python-docx | 任意 | Word 文档生成 |
### 系统工具（可选）
- pandoc：格式转换（apt-get install pandoc）AI 思考中...