env-sync

跨平台 conda Python 虚拟环境管理/迁移工具。

本仓库附带一份现成的 AI/ML 开发 conda 环境（Python 3.12，覆盖 LLM 编排、数据科学、Web 服务、文档处理等常用包）。工具也可以导出和迁移任意 conda 环境；AI 只是默认环境名，不是 Go CLI 逻辑的前提。

项目当前稳定入口是统一 Go CLI，代码位于 cmd/env-sync 和 internal/。Linux、Windows、macOS 共用同一套迁移编排逻辑，平台差异通过 Go 模块中的检测和兼容规则处理。

前置条件

• 普通使用不要求安装 Go，可直接从 GitHub Release 下载对应系统的可执行文件。
• 如需执行真实环境迁移，需要本机可用的 conda。
• 如果还没有 conda，可以运行 env-sync --install-miniconda 安装或更新 Miniconda。
• 命令应在 environment-*.yml 和 requirements-*.txt 所在目录运行；Go CLI 会从当前工作目录读取和写入这些配置文件。
• 只有从源码运行或本地构建时才需要安装 Go。

快速开始

从 GitHub Release 下载当前系统对应的可执行文件：

系统	文件
Linux x86_64	env-sync-linux-amd64
Linux arm64	env-sync-linux-arm64
macOS Intel	env-sync-macos-amd64
macOS Apple Silicon	env-sync-macos-arm64
Windows x86_64	env-sync-windows-amd64.exe

macOS / Linux：

# 以 Apple Silicon Mac 为例，其他平台替换为对应文件名
mv env-sync-macos-arm64 env-sync
chmod +x env-sync
./env-sync --new AI --from ai

# 激活环境
conda activate AI

Windows PowerShell：

Rename-Item .\env-sync-windows-amd64.exe env-sync.exe
.\env-sync.exe --new AI --from ai

# 激活环境
conda activate AI

如果需要从源码运行或本地构建：

# 从源码直接运行
go run ./cmd/env-sync --new AI --from ai

# 或先构建二进制，再运行
go build -o env-sync ./cmd/env-sync
./env-sync --new AI --from ai

使用方式

Go CLI 支持交互模式和命令行模式，可部署仓库自带的 AI 环境，也可用来迁移、导出任意 conda 环境。

交互模式

env-sync

菜单提供：

• [0] 安装或更新 Miniconda
• [1] 创建新的 conda 环境
• [2] 安装到已有 conda 环境
• [3] 导出 conda 环境配置
• [q] 退出

交互模式会先询问本次运行使用的镜像源。默认是官方源自动模式；也可以选择清华源或自定义 pip/conda 镜像源。

命令行模式

命令	说明
env-sync --new	创建默认 AI 环境
env-sync --new my-env	创建名为 my-env 的环境
env-sync --new my-env --from source	从 environment-source.yml / requirements-source.txt 创建
env-sync --existing my-env --from source	安装到指定已有环境
env-sync --fresh --new my-env --from source	删除已有环境后重建
env-sync --export my-env	导出指定环境配置
env-sync --install-miniconda	安装或更新 Miniconda

如果从源码运行，可将示例中的 env-sync 替换为 go run ./cmd/env-sync。如果使用本地构建产物，可在 macOS / Linux 下使用 ./env-sync，在 Windows PowerShell 下使用 .\env-sync.exe。

迁移机制

--export 会生成：

• environment-{name}.yml：conda 环境定义，去除本机 prefix
• requirements-{name}.txt：pip 包清单

在目标机器上可通过 --from <name> 使用这些文件重建环境。默认行为是续装：环境已存在时跳过已安装 pip 包，缺失包继续安装；--fresh 才会删除重建或全量重装。

--existing 必须显式传入 --from <name>，避免误把旧的内置示例环境安装到当前环境。

跨平台适配

Go CLI 的目标是迁移任意 conda 环境，而不是硬编码某个 AI 环境。Linux、Windows、macOS 共用同一套安装和记录流程，只有确实受目标平台、硬件或包分发影响的项目才进入兼容规则。

• 普通 pip 包：先按 requirements 原始版本安装；失败后尝试未固定版本；仍失败则写入失败日志。
• 平台不兼容包：已知只适用于特定平台的包会在其他平台跳过，并记录为 skipped-platform，例如 pywin32 在非 Windows 平台跳过。
• 硬件和 wheel variant：PyTorch 会根据目标系统、NVIDIA GPU 和驱动 CUDA 版本选择 CPU 或 CUDA wheel；macOS 使用普通 wheel/MPS 路径，不安装 CUDA wheel。
• 兼容替换：当原包在目标平台不可用且已有明确替代包时，会安装替代包并记录原因，例如 macOS 上的 faiss 可替换为 faiss-cpu。
• 导入检查建议：工具不默认安装系统级运行时；如果常见包导入时报缺少运行时，例如 macOS 上缺少 libomp.dylib，失败日志会给出 conda install -n <env> -c conda-forge llvm-openmp 或 brew install libomp 的建议。

安装结束后，Go CLI 会运行 pip check，并对常见风险包（如 torch、faiss、xgboost）做导入检查。不存在的包不会被当作错误。

失败日志

无法自动处理的项目会写入：

env-sync-failed-<env>.log

该文件名在 Linux、Windows、macOS 上保持一致；如由测试或调用方注入日志路径，则使用注入路径。

日志前缀含义：

前缀	含义
failed-pip:	pip 安装失败
skipped-platform:	当前平台不适用，已跳过
failed-import:	安装后导入检查失败
suggestion:	可选人工修复建议

镜像源

Go CLI 支持命令行参数和环境变量配置镜像源。

参数或变量	说明
--mirror auto	默认策略，先使用官方源；conda 源失败后自动切换清华源重试
--mirror official	只使用官方源
--mirror tsinghua	使用清华 pip index 和 conda channels
--mirror custom	使用自定义镜像源，需同时提供 pip index 和 conda channels
--pip-index-url <url>	自定义 pip index URL
--conda-channels <列表>	自定义 conda channels，使用逗号分隔
ENV_SYNC_MIRROR	环境变量形式的镜像策略
ENV_SYNC_PIP_INDEX_URL	环境变量形式的 pip index URL
ENV_SYNC_CONDA_CHANNELS	环境变量形式的 conda channels
USE_TSINGHUA=true	兼容旧环境变量，等价于 --mirror tsinghua

示例：

env-sync --new AI --from ai --mirror tsinghua

ENV_SYNC_MIRROR=custom \
ENV_SYNC_PIP_INDEX_URL=https://pip.example/simple \
ENV_SYNC_CONDA_CHANNELS=https://conda.example/main,https://conda.example/forge \
env-sync --new AI --from ai

附带的 AI/ML 环境预置包

environment-ai.yml 和 requirements-ai.txt 是一份现成的 AI/ML 开发环境快照。包含以下主要包：

类别	包
LLM / AI	langchain, langgraph, openai, dashscope, qwen-agent, chromadb, faiss-cpu, tiktoken, tokenizers, huggingface-hub
模型服务	fastapi, flask, gradio, uvicorn, sse-starlette
机器学习	scikit-learn, xgboost, catboost, onnxruntime, scipy, statsmodels
数据处理	pandas, numpy, openpyxl, xlrd, python-docx, python-pptx, pdfplumber, pymupdf
数据库	sqlalchemy, mysql-connector-python, pymysql
开发工具	pytest, ruff, basedpyright, ipykernel
工具	playwright, mcp, beautifulsoup4

完整列表见 requirements-ai.txt。

文件结构

├── cmd/env-sync/               # 统一 Go CLI 入口
├── internal/                   # Go CLI 的 cli/core/compat/manifest/platform 等模块
├── spec/                       # 专题规格文档
├── environment-ai.yml          # 附带的 AI 环境 conda 定义
├── requirements-ai.txt         # 附带的 AI 环境 pip 依赖清单
├── SPEC.md                     # 项目总览规格
├── AGENTS.md                   # coding agent 开发约束
├── go.mod
└── README.md

注意事项

• macOS / Linux 直接下载的二进制文件可能需要先执行 chmod +x env-sync 才能运行；macOS 首次运行可能遇到系统安全提示，按系统提示允许后再执行。
• 不建议安装到 base 环境；Go CLI 会阻止写入 base。
• 跨平台迁移不保证每个包版本完全一致，尤其是 GPU、系统 API、编译扩展相关包。
• 安装中断后可重新运行同一命令，工具会按续装逻辑继续。
• 缺少 environment-{name}.yml 或 requirements-{name}.txt 时，Go CLI 会直接报错提示原因，不会创建隐式最小环境。