market/skills/dev-environment-setup/references/decision-tree.md

环境管理四级降级决策树

python-runtime 与 nodejs-runtime 在执行任何安装/版本切换前必须按本决策树选择路径。

总体流程

                         ┌──────────────────┐
                         │  执行 probe 脚本 │
                         └─────────┬────────┘
                                   ▼
                  ┌─────────────────────────────┐
                  │ desirecore_api 字段非空？    │
                  └────────┬───────────────┬─────┘
                       是 │               │ 否
                          ▼               ▼
                ┌──────────────────┐  ┌──────────────────┐
                │ L1：HTTP API 路径 │  │ hatch_path /      │
                └────────┬─────────┘  │ volta_path 非空？ │
                         │            └────────┬──┬──────┘
                  失败/超时              是   │  │ 否
                         ▼                    ▼  ▼
                ┌──────────────────┐  ┌──────────────────┐
                │ L2：DesireCore CLI │  │ L3：系统包管理器 │
                └────────┬─────────┘  └────────┬─────────┘
                         │                     │
                  二进制损坏 / 安装失败          失败/不可用
                         ▼                     ▼
                ┌─────────────────────────────────────────┐
                │ L4：社区方案（pyenv / nvm / fnm / conda）│
                └─────────────────────────────────────────┘

L1：DesireCore HTTP API（最高优先级）

触发条件

• ${DESIRECORE_ROOT}/agent-service.port 文件存在且可读
• curl -sk --max-time 0.5 https://127.0.0.1:${PORT}/api/runtime/environment 返回 2xx
• 当前会话能订阅 Socket.IO（DesireCore 内部 Agent 默认满足）

典型操作

PORT=$(cat ${DESIRECORE_ROOT}/agent-service.port)
BASE="https://127.0.0.1:${PORT}/api/runtime"

# 1. 拉取快照
curl -sk "${BASE}/environment"

# 2. 触发安装（异步）
curl -sk -X POST "${BASE}/python/install" \
  -H "Content-Type: application/json" \
  -d '{"version":"3.12"}'

# 3. 订阅 runtime:terminal / runtime:complete 事件展示日志

判定失败的信号

• HTTP 状态码 ≥ 500 或 502（远端镜像不可用，详见 runtime-env-routes.ts 130/162 行）
• runtime:complete 事件 success: false
• Socket.IO 连接断开后超过 30 秒未收到 runtime:complete

切换提示：API 失败立即降级到 L2 CLI，不要重试同一接口（可能是镜像被墙）。

L2：DesireCore 内置 CLI（绝对路径）

触发条件

• API 不可达或失败
• probe 脚本中 hatch_path / volta_path 字段非空（即二进制存在）

典型操作（macOS / Linux）

HATCH=${DESIRECORE_ROOT}/runtime/hatch/hatch
VOLTA=${DESIRECORE_ROOT}/runtime/volta/volta

export HATCH_HOME=${DESIRECORE_ROOT}/runtime/hatch
export VOLTA_HOME=${DESIRECORE_ROOT}/runtime/volta

"$HATCH" python install 3.12
"$VOLTA" install node@22

典型操作（Windows PowerShell）

$Hatch = "$env:USERPROFILE\.desirecore\runtime\hatch\hatch.exe"
$Volta = "$env:USERPROFILE\.desirecore\runtime\volta\volta.exe"

$env:HATCH_HOME = "$env:USERPROFILE\.desirecore\runtime\hatch"
$env:VOLTA_HOME = "$env:USERPROFILE\.desirecore\runtime\volta"

& $Hatch python install 3.12
& $Volta install node@22

判定失败的信号

• exit code ≠ 0
• stderr 包含 network、timeout、ENOTFOUND、failed to fetch
• 可执行文件被反病毒软件隔离（macOS Gatekeeper / Windows Defender）

切换提示：失败后才考虑 L3，不要在 L2 内重试。

L3：系统包管理器

触发条件：DesireCore 二进制全部缺失，或用户明确要求"系统级"安装。

平台	Python	Node.js
macOS	brew install python3	brew install node
Debian/Ubuntu	sudo apt install python3 python3-pip python3-venv	NodeSource 仓库或 sudo apt install nodejs npm
Fedora/RHEL	sudo dnf install python3 python3-pip	sudo dnf install nodejs
Arch	sudo pacman -S python python-pip	sudo pacman -S nodejs npm
Windows	winget install Python.Python.3	winget install OpenJS.NodeJS.LTS

判定失败的信号

• command not found（包管理器自身缺失，如 brew 未装）
• PEP 668 报错（Linux 新版发行版 pip install 全局被拒）→ 见 python-runtime troubleshooting
• 权限被拒（缺少 sudo / 非管理员）

切换提示：仅在系统包管理器都失败、并且用户明确希望安装时升级到 L4。

L4：社区方案

仅在以下情况启用：

1. 用户明确指定（"我要 pyenv"、"用 nvm 装"）
2. L1–L3 全部失败
3. 项目已经使用社区方案（存在 .python-version / .nvmrc 文件）

工具	用途	文档
pyenv / pyenv-win	Python 多版本	python-runtime/references/pyenv-fallback.md
nvm / nvm-windows	Node.js 多版本（shell 脚本）	nodejs-runtime/references/nvm-fallback.md
fnm	Rust 实现的 nvm 替代	nodejs-runtime/references/nvm-fallback.md
conda / miniconda	数据科学场景	python-runtime/references/virtualenv.md

何时跳过决策树

skill 直接执行用户原话——不要走决策树——的情况：

• 用户明示路径："用 brew 装 python"、"在 .venv 里 pip install xxx"
• 用户在 skill 之外手工修改了环境（识别到 .python-version、.nvmrc、package.json#volta）
• skill 上下文已经存在激活的虚拟环境（$VIRTUAL_ENV 非空）

每次升级版本后

无论走哪条路径，安装/移除完成后立即调用：

# L1 模式
curl -sk -X POST "${BASE}/environment/refresh"

# L2/L3/L4 模式（强制 probe 输出最新结果）
bash <skill>/scripts/probe-{python,node}.sh

避免后续判断基于陈旧缓存。