managing-environments

管理开发环境

关于使用 Python 虚拟环境（venv）和 conda 环境的指南。此技能通过在操作前始终检查并确认当前活动环境，确保安全、有序地安装软件包。

此目录中的支持文件：

• installation-patterns.md - venv 和 conda 的安装命令、通道优先级及 TOS 错误处理
• best-practices-and-scenarios.md - 常见场景、最佳实践、可恢复的数据获取模式
• troubleshooting-and-examples.md - 常见问题排查及完整示例

何时使用此技能

在以下情况启用此技能：

• 安装 Python 软件包或工具
• 用户要求安装依赖项
• 设置新的 Python 项目
• 调试导入或软件包问题
• 进行任何 Python 开发工作

核心原则

1. 安装前始终检查环境状态
2. 始终确认用户要使用哪个环境
3. 未经确认，绝不安装
4. 没有活动环境时发出警告
5. 帮助用户选择合适的环境类型

---

环境检测工作流

步骤 1：检查环境状态

执行任何安装命令之前，先运行以下检查：

# Check for active venv
echo "Python executable: $(which python)"
echo "Virtual environment: $VIRTUAL_ENV"

# Check for conda environment
echo "Conda environment: $CONDA_DEFAULT_ENV"
conda info --envs 2>/dev/null || echo "Conda not available"

步骤 2：解读结果

场景 A：venv 已激活

Python executable: /path/to/project/.venv/bin/python
Virtual environment: /path/to/project/.venv
Conda environment:

-> Python venv 已激活

场景 B：conda 环境已激活

Python executable: /path/to/miniconda3/envs/myenv/bin/python
Virtual environment:
Conda environment: myenv

-> Conda 环境已激活

场景 C：没有环境（系统 Python）

Python executable: /usr/bin/python
Virtual environment:
Conda environment:

-> 当前没有活动环境！警告用户。

场景 D：检测到两个环境（少见）

Virtual environment: /path/to/.venv
Conda environment: base

-> 两个环境均已激活，优先采用 which python 显示的环境，但要向用户确认

步骤 3：向用户确认

继续操作前务必询问：

I've detected the following environment:
- Environment type: [venv/conda/none]
- Location: [path]
- Python version: [version]

Is this the environment you want me to use for installing [package/tool]?

继续操作前等待用户确认。

有关不同环境类型对应的安装命令，请参阅 installation-patterns.md。

---

没有活动环境——警告与规划

如果未检测到环境，请勿继续安装。应改为：

步骤 1：警告用户

WARNING: No Python environment detected!

You're currently using system Python:
- Location: [path to python]
- Version: [version]

Installing packages to system Python can:
- Cause conflicts with system packages
- Require sudo/admin privileges
- Make projects difficult to reproduce
- Break system tools that depend on specific versions

I recommend creating a virtual environment first.

步骤 2：帮助选择环境类型

决策树：

Question: What type of project are you working on?

A. Pure Python project (web dev, scripting, etc.)
   -> Recommend: Python venv
   -> Fast, lightweight, standard Python tool

B. Data science / Scientific computing
   -> Ask: Do you need non-Python dependencies? (R, C libraries, etc.)

   B1. Yes (or using packages like numpy, scipy, pandas, etc.)
       -> Recommend: Conda
       -> Better binary dependency management

   B2. No, only Python packages
       -> Recommend: Python venv
       -> Simpler and faster

C. Bioinformatics / Genomics
   -> Recommend: Conda (with bioconda channel)
   -> Most tools available via bioconda
   -> Manages complex dependencies well

D. Galaxy tool development
   -> Recommend: Conda
   -> Galaxy uses conda for tool dependencies
   -> Direct compatibility

步骤 3：提出创建环境

使用 venv：

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
which python

使用 conda：

conda create -n project-name python=3.11
conda activate project-name
conda info --envs
which python

---

环境选择指南

以下情况使用 Python venv：

• 纯 Python 项目
• 依赖项简单（均可在 PyPI 上获取）
• 标准 Web 开发（Django、Flask、FastAPI）
• 不使用编译扩展或 C 库
• 希望尽快创建环境
• 使用 Python 3.3 或更高版本

**优点：**轻量、快速、内置于 Python，适用于所有平台。 **缺点：**较难管理非 Python 依赖项；二进制软件包可能需要系统库。

以下情况使用 Conda 环境：

• 数据科学 / 机器学习
• 科学计算（numpy、scipy、pandas）
• 生物信息学 / 基因组学
• 需要特定的 Python 版本
• 跨语言依赖项（R、C++ 等）
• Galaxy 工具开发
• 复杂的二进制依赖项

**优点：**可管理二进制依赖项，支持跨语言，更适合科学计算软件包，也可管理 Python 版本。 **缺点：**比 venv 慢、占用更多磁盘空间，且需要安装 conda。

---

快速参考

环境检测命令

# Check what's active
which python
echo $VIRTUAL_ENV
echo $CONDA_DEFAULT_ENV

# Python version
python --version

# Installed packages
pip list          # for pip
conda list        # for conda

# Environment location
pip show package-name  # shows where package is installed

激活命令

# venv
source .venv/bin/activate                    # Linux/Mac
.venv\Scripts\activate                       # Windows

# conda
conda activate environment-name

# Deactivation
deactivate                                   # venv
conda deactivate                             # conda

有关常见场景、最佳实践、问题排查及完整示例，请参阅此目录中的支持文件。

---

总结

请始终牢记：

1. 安装前检查环境
2. 向用户展示当前活动环境
3. 继续操作前向用户确认
4. 没有活动环境时发出警告
5. 帮助选择合适的环境类型
6. 记录环境设置以确保可复现

切勿：

• 不检查环境就安装
• 假定用户想使用系统 Python
• 未经用户确认就安装
• 忽略有关 conda base 环境的警告

此技能可确保所有项目都拥有干净、可复现且无冲突的 Python 环境。