Imported from xinetzone/SpecWeave (
apps/docker-images/devcontainer-base/variants/AGENTS.md). Install upstream withnpx skills add xinetzone/SpecWeave --skill variants. Copyright stays with the author.
devcontainer-base/variants - 镜像变体系列 AI协作者入口 (AGENTS Manifest)
启动协议（PRIORITY ZERO — 所有智能体必须遵循）
步骤 1：读取本文件全文 步骤 2：确认父级工作区 — 本子系统是 devcontainer-base 的变体管理子目录，规则继承自 ../AGENTS.md 步骤 3：按上下文路由表加载变体管理特有规范（.agents/rules/ 下对应文件） 步骤 3.5：自检 — 确认已理解父级规则与本系统特有约束 步骤 4：在规范指导下执行任务本文件是 devcontainer-base 镜像变体系列的 AI 协作者入口。本子系统管理基于 devcontainer-base 基础镜像的 特殊功能镜像变体（如 conda、conda-llvm），提供统一构建脚本、依赖拓扑排序、分层验证和模板化新增能力。 所有全局规则和 devcontainer-base 项目规则继承自父级，本文件仅定义变体管理子系统特有的上下文路由与约束。 子系统详细规范已原子化到 .agents/ 目录。
子系统概述
- 子系统类型：Docker 镜像变体管理系统（"基础继承+配置化"模式）
- 父级工作区：devcontainer-base（../AGENTS.md）
- 核心功能：多变体统一构建（拓扑排序）、构建阶段计时、逐条验证、国内镜像源支持、模板化新增
- 共享组件：
shared/lib/logging.sh（结构化日志库，双格式text+JSON）、shared/lib/container-engine.sh（容器引擎抽象库，docker/podman 自动检测） - 可用变体：
conda-llvm：基础镜像 + LLVM 22.1.8/clang/cmake/ninja 编译工具链（直接基于 devcontainer-base:latest，镜像源已内置于基础镜像）onnx-dev：conda-llvm + 纯 ONNX 生态（onnx/onnxruntime/onnx-simplifier/onnxscript，安装于 main 环境，不含 PyTorch，onnxoptimizer 因 free-threading 不兼容而排除，基于 conda-llvm 变体）onnx-pytorch：conda-llvm + PyTorch CPU + ONNX 生态全工具链（torch 一等公民，base 环境 GIL 启用，含 onnxoptimizer，基于 conda-llvm 变体）onnx-quantized：onnx-dev + onnxruntime.quantization 量化工具链（INT8/FP16动态/静态量化，纯 ONNX 无 PyTorch，free-threading main 环境，基于 onnx-dev 变体）torch-dev：onnx-quantized + free-threading PyTorch CUDA（cp314t，无 GIL，CUDA cu130/cu128/cpu，torch 一等公民；ai-dev 的直接基础，基于 onnx-quantized 变体）ai-dev：torch-dev + 完整 AI/ML/NLP 全栈生态（50+ 包）+ JupyterLab 4.x + 通用 AI 内核（基于 torch-dev 变体）
- 新增变体模板：
_template/目录（复制→替换占位符→注册→验证） - AI资产容器：
.agents/目录（本子系统特有规则）
嵌套路由关系
SpecWeave 根 AGENTS.md（全局规则、Skill、角色）
└─ apps/AGENTS.md（应用区入口路由）
└─ devcontainer-base/AGENTS.md（项目路由入口）
├─ .agents/ ← 项目AI资产容器
│ └─ rules/ ← 项目特有规则（Dockerfile/entrypoint/services/build-test）
├─ Dockerfile ← 基础镜像定义
├─ scripts/ ← 项目辅助脚本
└─ variants/ ← 镜像变体系列（本子系统）
├─ AGENTS.md ← 本文件（变体系列路由入口）
├─ .agents/ ← 本子系统AI资产容器
│ ├─ README.md ← .agents 目录索引
│ └─ rules/ ← 变体管理子系统规则
│ ├─ build-orchestration.md ← 构建编排规范
│ ├─ variant-conventions.md ← 变体Dockerfile共享约定
│ ├─ testing.md ← 测试规范
│ └─ new-variant-guide.md ← 新增变体操南
├─ build.sh ← 统一构建脚本（拓扑排序+依赖处理+计时+验证）
├─ shared/ ← 变体间共享组件
│ ├─ lib/logging.sh ← 共享结构化日志库
│ ├─ lib/container-engine.sh ← 容器引擎抽象库（docker/podman）
│ └─ scripts/conda-mirror-setup.sh ← conda/pip镜像源配置脚本
├─ scripts/ ← 单变体辅助脚本
│ ├─ build-conda-llvm.sh ← conda-llvm一键构建脚本
│ ├─ build-onnx-dev.sh ← onnx-dev一键构建脚本（依赖链 base→conda-llvm→onnx-dev）
│ ├─ build-onnx-pytorch.sh ← onnx-pytorch一键构建脚本
│ ├─ test-conda-llvm.sh ← conda-llvm单元测试
│ ├─ test-conda-llvm-smoke.sh ← conda-llvm冒烟测试
│ ├─ test-onnx-dev.sh ← onnx-dev单元测试（23项，含torch缺席负向验证）
│ ├─ test-onnx-pytorch.sh ← onnx-pytorch单元测试（23项，含GIL启用守卫）
│ ├─ test-onnx-quantized.sh ← onnx-quantized单元测试
│ ├─ test-torch-dev.sh ← torch-dev单元测试
│ └─ test-timer-parser.sh ← [TIMER]日志解析单元测试
├─ _template/ ← 新变体模板
│ ├─ Dockerfile
│ ├─ .env.example
│ ├─ README.md
│ └─ .agents/rules/dockerfile.md
├─ conda-llvm/ ← 基础镜像+LLVM 变体（镜像源已内置）
│ ├─ Dockerfile
│ ├─ .env.example
│ ├─ README.md
│ ├─ DEPENDENCIES.md
│ ├─ RELEASE.md
│ ├─ RELEASE-GUIDE.md
│ └─ .agents/rules/dockerfile.md
├─ onnx-dev/ ← 纯ONNX生态变体（无PyTorch，main环境）
│ ├─ AGENTS.md ← 变体级智能体入口（嵌套优先）
│ ├─ Dockerfile
│ ├─ .env.example
│ ├─ README.md
│ └─ .agents/rules/dockerfile.md
├─ onnx-pytorch/ ← PyTorch CPU+ONNX Runtime 变体
│ ├─ Dockerfile
│ ├─ .env.example
│ ├─ README.md
│ └─ .agents/rules/dockerfile.md
├─ onnx-quantized/ ← ONNX量化工具链变体（INT8/FP16）
│ ├─ AGENTS.md ← 变体级智能体入口（嵌套优先）
│ ├─ Dockerfile
│ ├─ .env.example
│ ├─ README.md
│ ├─ ADVANCED-QUANTIZATION-GUIDE.md
│ ├─ QUANTIZATION-BEST-PRACTICES.md
│ └─ .agents/rules/dockerfile.md
├─ torch-dev/ ← Free-Threading PyTorch CUDA变体（cp314t, 无GIL）
│ ├─ AGENTS.md ← 变体级智能体入口（嵌套优先）
│ ├─ Dockerfile
│ ├─ .env.example
│ ├─ README.md
│ ├─ docker-compose.torch.yml ← Compose配置（DinD/DooD/SSH-only）
│ ├─ examples/test_torch.py ← PyTorch+CUDA综合验证脚本
│ ├─ scripts/start-torch-dev.sh ← 一键启动脚本（自动端口冲突处理）
│ └─ .agents/rules/dockerfile.md
└─ ai-dev/ ← AI全栈变体（50+包 + JupyterLab4.x + AI内核）
├─ Dockerfile
├─ .env.example
├─ README.md
└─ .agents/rules/dockerfile.md
嵌套优先原则：进入本目录后优先读取本文件；变体管理子系统规范在 .agents/rules/ 下；单个变体的特有规则在各变体目录 .agents/rules/dockerfile.md 中；本文件和 .agents/ 未覆盖的规则回退到 devcontainer-base 父级。
上下文路由表
| 任务类型 | 必读入口 | 说明 |
|---|---|---|
| 修改/理解 build.sh 构建逻辑 | .agents/rules/build-orchestration.md | VARIANTS数组格式（` |
| 编写/修改变体 Dockerfile | .agents/rules/variant-conventions.md | FROM继承模式、SHELL重置、禁止覆盖项、PATH优先级、缓存挂载规范、[VALIDATION CHECKPOINT] |
| conda-llvm 变体 Dockerfile | conda-llvm/.agents/rules/dockerfile.md | LLVM安装、clang/cmake/ninja、PATH配置（镜像源已内置基础镜像） |
| onnx-dev 变体 Dockerfile | onnx-dev/.agents/rules/dockerfile.md | 纯ONNX生态（main环境安装）、PyTorch一等排除约束（双重负向验证）、free-threading防线、4追加阶段 |
| onnx-pytorch 变体 Dockerfile | onnx-pytorch/.agents/rules/dockerfile.md | PyTorch CPU安装、ONNX生态、PATH优先级（/opt/conda/bin最前）、4追加阶段 |
| onnx-quantized 变体 Dockerfile | onnx-quantized/.agents/rules/dockerfile.md | onnxruntime.quantization量化工具链、FP16/INT8、neural-compressor可选、共享脚本COPY模式 |
| torch-dev 变体 Dockerfile | torch-dev/.agents/rules/dockerfile.md | Free-Threading PyTorch CUDA（cp314t）、3追加阶段、冒烟6项算子、triton GIL兼容 |
| torch-dev 启动/容器管理 | torch-dev/AGENTS.md | 一键启动脚本、三模式（DinD/DooD/SSH-only）、自动端口冲突处理、test_torch.py验证 |
| ai-dev 变体 Dockerfile | ai-dev/.agents/rules/dockerfile.md | 完整AI/ML/NLP全栈（50+包，base环境安装）、torch继承自torch-dev、JupyterLab4.x+通用AI内核（base python注册于main环境kernels）、PIP_USER构建/运行时分离 |
| 编写/运行测试脚本 | .agents/rules/testing.md | L1-L6六层测试策略、脚本模板、pass/fail辅助函数、冒烟验证vs完整测试对比 |
| 新增镜像变体 | .agents/rules/new-variant-guide.md | 7步流程：复制模板→替换占位符→更新配置→创建规则→注册到build.sh→创建测试→更新README |
| 共享日志库使用 | shared/lib/logging.sh | log_info/log_ok/log_error/log_step/log_metric/log_event/log_summary API |
| 基础镜像构建规范 | ../.agents/rules/dockerfile.md | 回退到父级 devcontainer-base Dockerfile规范 |
| 全局规则（提交/代码风格） | ../../../AGENTS.md | 回退到 SpecWeave 根工作区 |
| Skill使用 | ../../../.agents/skills/ | 所有SpecWeave全局Skill可用 |
核心规范入口
| 规范 | 入口 | 说明 |
|---|---|---|
| 父级项目规则 | ../AGENTS.md | devcontainer-base 项目路由（启动协议必经之路） |
| 本文件入口 | AGENTS.md（本文件） | 镜像变体系列路由 |
| AI资产目录 | .agents/README.md | .agents目录索引和加载顺序 |
| 构建编排规范 | .agents/rules/build-orchestration.md | build.sh用法、VARIANTS格式、拓扑排序、镜像源、计时、验证 |
| 变体共享约定 | .agents/rules/variant-conventions.md | FROM模式、禁止覆盖项、PATH优先级、缓存挂载、验证检查点 |
| 测试规范 | .agents/rules/testing.md | 6层测试策略、脚本模板、快速验证vs完整测试 |
| 新增变体操南 | .agents/rules/new-variant-guide.md | 7步新增流程、模板占位符、注册检查清单 |
| conda-llvm变体规范 | conda-llvm/.agents/rules/dockerfile.md | LLVM/clang变体特有Dockerfile规则 |
| onnx-dev变体规范 | onnx-dev/.agents/rules/dockerfile.md | 纯ONNX生态变体特有规则（无PyTorch，main环境） |
| onnx-pytorch变体规范 | onnx-pytorch/.agents/rules/dockerfile.md | PyTorch CPU+ONNX Runtime变体特有规则 |
| onnx-quantized变体规范 | onnx-quantized/.agents/rules/dockerfile.md | ONNX量化工具链变体特有规则 |
| torch-dev变体规范 | torch-dev/.agents/rules/dockerfile.md | Free-Threading PyTorch CUDA变体特有规则（cp314t无GIL） |
| torch-dev变体入口 | torch-dev/AGENTS.md | torch-dev变体智能体路由（启动脚本/Compose/验证/三模式） |
| ai-dev变体规范 | ai-dev/.agents/rules/dockerfile.md | 完整AI/ML/NLP全栈变体特有规则（base环境安装，Jupyter内核注册main环境，torch继承自torch-dev） |
| 共享性能配置脚本 | shared/scripts/conda-perf-setup.sh | conda性能参数配置（线程、超时、solver）；镜像源已内置基础镜像 |
| 新变体模板 | _template/ | 复制模板创建新变体 |
| 人类可读文档 | README.md | 变体列表和快速开始（面向人类用户） |
约束速览
详细约束已按主题拆分到 .agents/rules/ 下各文件，以下是核心约束索引：
| 约束主题 | 所在文件 |
|---|---|
| VARIANTS数组字段分隔符（` | 而非:`） |
| FROM后必须重置SHELL指令 | variant-conventions.md |
| 禁止覆盖ENTRYPOINT/CMD/WORKDIR | variant-conventions.md |
| PATH优先级：/opt/venv/bin 必须高于变体路径 | variant-conventions.md |
| Dockerfile必须输出[TIMER]阶段标记 | variant-conventions.md |
| 末尾必须有[VALIDATION CHECKPOINT] | variant-conventions.md |
| 测试6层覆盖（L1工具链→L6配置） | testing.md |
| 新变体7步注册流程 | new-variant-guide.md |
| 镜像命名：devcontainer-base:<variant>-<TAG> | build-orchestration.md |
快速开始
# 列出可用变体
bash build.sh --list
# 构建单个变体（国内源）
bash build.sh --variant conda-llvm --cn
bash build.sh --variant onnx-pytorch --cn
bash build.sh --variant onnx-dev --cn
bash build.sh --variant onnx-quantized --cn
bash build.sh --variant torch-dev --cn
bash build.sh --variant ai-dev --cn
# 构建所有变体（按依赖顺序：conda-llvm → onnx-dev/onnx-pytorch → onnx-quantized → torch-dev → ai-dev → llm-agent）
bash build.sh --all --cn
# 一键构建+测试 onnx-pytorch
bash scripts/build-onnx-pytorch.sh
# 一键启动 torch-dev 开发容器（自动端口冲突检测+健康等待+验证）
bash torch-dev/scripts/start-torch-dev.sh
# 仅运行测试（镜像已存在）
bash scripts/test-conda-llvm.sh
bash scripts/test-onnx-pytorch.sh
bash scripts/test-onnx-quantized.sh
bash scripts/test-torch-dev.sh
bash scripts/test-ai-dev.sh
# 新增变体（7步流程）
cp -r _template <new-variant>
# 详见 .agents/rules/new-variant-guide.md引用父级规范
本目录完全遵循 SpecWeave 工作区发现协议和嵌套路由原则：
- AGENTS.md 包含「启动协议」关键词
- 正确引用父级
../AGENTS.md - 遵循嵌套优先原则，未覆盖的规则回退到父级（devcontainer-base → SpecWeave 根）
- 子系统详细规范原子化到
.agents/rules/目录，遵循单一职责原则 - 单个变体通过各自
.agents/rules/dockerfile.md定义变体特有规则
变更日志
- 2026-08-16 | feat | 新增 torch-dev 变体能级入口（AGENTS.md）；torch-dev 变体：onnx-quantized + free-threading PyTorch CUDA（cp314t无GIL），提供 docker-compose.torch.yml（DinD/DooD/SSH-only三模式）、examples/test_torch.py（综合验证脚本）、scripts/start-torch-dev.sh（一键启动+自动端口冲突处理）；ai-dev 依赖链更新为 onnx-quantized→torch-dev→ai-dev
- 2026-08-15 | docs | ai-dev 变体同步 onnx-quantized v2.0.0 架构：继承链更新为 devcontainer-base→conda-llvm→onnx-dev→onnx-quantized→ai-dev，补齐 ai-dev 治理登记（可用变体/路由图/路由表/快速开始），明确 torch 非继承（经 onnx2torch/open_clip_torch 传递引入 base 环境）
- 2026-08-14 | refactor | onnx-quantized v2.0.0：基础镜像从 onnx-pytorch 迁移至 onnx-dev（纯 ONNX 无 PyTorch，main 环境 free-threading cp314t），量化测试模型全部改用 onnx.helper 纯构建（make_tensor 传 bytes 必须显式 raw=True，onnx 1.22 不再自动识别）
- 2026-08-09 | feat | 新增 onnx-quantized 变体（onnxruntime.quantization 量化工具链），注册到 build.sh VARIANTS 数组
- 2026-08-08 | feat | 新增 onnx-pytorch 变体（PyTorch CPU + ONNX Runtime 深度学习运行时），添加 build-onnx-pytorch.sh/test-onnx-pytorch.sh 脚本
- 2026-08-08 | feat | 新增 shared/scripts/conda-mirror-setup.sh 共享镜像源配置脚本，变体通过环境变量驱动
- 2026-08-07 | feat | 初始化 variants/AGENTS.md + .agents/ 目录，原子化4个规则文件（build-orchestration/variant-conventions/testing/new-variant-guide）
