venvstacks

任务目标

• 本 Skill 用于：掌握 venvstacks 分层 Python 虚拟环境打包和发布技术
• 能力包含：三层环境架构定义、依赖锁定、环境构建、本地导出、归档发布
• 触发条件：当用户需要打包 Python ML/AI 应用并独立分发运行时环境时

前置准备

• 环境安装：

  pipx install venvstacks
  # 或
  pip install --user venvstacks
  

• 依赖要求：uv>=0.5.0

操作步骤

标准流程

1. 定义环境栈 (venvstacks.toml)

[[runtimes]]
name = "cpython@3.11"
fully_versioned_name = "cpython@3.11.10"
requirements = [
    "numpy",
]

[[frameworks]]
name = "sklearn"
runtime = "cpython@3.11"
requirements = [
    "scikit-learn",
]

[[applications]]
name = "classification-demo"
launch_module = "launch_modules/sklearn_classification.py"
frameworks = ["sklearn"]
requirements = [
    "scikit-learn",
]

2. 锁定层依赖

venvstacks lock sklearn_demo/venvstacks.toml

• 生成 requirements 文件夹
• 使用 pylock.toml 格式存储锁定的依赖
• 生成层锁定元数据文件

3. 构建环境栈

venvstacks build sklearn_demo/venvstacks.toml

• 创建 venv 环境
• 安装指定包
• 注入 sitecustomize.py 实现层链接
• 注入 postinstall.py 环境配置脚本

4. 本地导出（快速测试）

venvstacks local-export --output-dir demo_export sklearn_demo/venvstacks.toml

• 复制环境到指定目录
• 执行 postinstall.py

5. 发布归档

venvstacks publish --tag-outputs --output-dir demo_artifacts sklearn_demo/venvstacks.toml

• 生成可重现二进制归档
• 生成元数据文件

可选分支

当需要完整流水线时

# 一步完成锁定、构建、发布
venvstacks build --publish --tag-outputs --output-dir artifacts stack.toml

当需要多平台支持时

# 锁定（跨平台）
venvstacks lock stack.toml

# 分平台构建
venvstacks build --target linux-x64 stack.toml
venvstacks build --target win32-x64 stack.toml
venvstacks build --target darwin-arm64 stack.toml

# 发布
venvstacks publish --tag-outputs --output-dir artifacts stack.toml

资源索引

必要脚本

无（CLI 工具为主）

领域参考

• references/architecture.md

  • 何时读取：需要理解三层架构时
  • 内容：Runtime、Framework、Application 层详解

• references/stack-definition.md

  • 何时读取：需要编写 venvstacks.toml 时
  • 内容：TOML 配置格式、层定义规范

• references/cli-commands.md

  • 何时读取：需要了解 CLI 用法时
  • 内容：lock、build、publish、local-export 详解

注意事项

三层架构

• Runtime：Python 解释器环境
• Framework：共享框架（如 PyTorch、scikit-learn）
• Application：独立应用组件

依赖锁定

• 使用 uv 进行联合依赖解析
• 跨平台锁定（pylock.toml 格式）
• 仅允许从二进制包安装

sitecustomize.py

• 实现层间依赖共享
• 允许代码导入下层包的模块

可重现构建

• 相同输入产生字节级相同的归档
• 记录完整的输入哈希和输出哈希