feat: 拆分 environment-setup 为 Python/Node.js 运行时双核心 + 父级路由

新增双核心 skill（深度集成 DesireCore Hatch/Volta + HTTP API + Socket.IO）： - python-runtime v1.0.1：Python 运行时管理 · 四级降级：HTTP API → Hatch CLI 绝对路径 → 系统包管理器 → pyenv · references：hatch-desirecore / pyenv-fallback / virtualenv / troubleshooting · scripts/probe-python.sh：输出 JSON 快照供 Claude 解析决策 - nodejs-runtime v1.0.1：Node.js 运行时管理 · 四级降级：HTTP API → Volta CLI → 系统包管理器/NodeSource → nvm/fnm · references：volta-desirecore / nvm-fallback / package-managers / troubleshooting · scripts/probe-node.sh：输出 JSON 快照（含 volta_tools / package_json_volta 等） environment-setup → dev-environment-setup v2.0.1（重命名 + 重写为 router）： - 从 1380 行手册瘦身为 ~150 行索引 - 仅负责容器（Docker/Podman）/ WSL2 / 办公依赖速查 / 系统工具 - references/desirecore-runtime.md 沉淀 Hatch/Volta 路径表 + HTTP API 速查 + Socket.IO 事件契约，作为两个核心 skill 的共享底座 - references/decision-tree.md 定义四级降级决策树 - scripts/probe.sh + probe.ps1 系统级 JSON 探测三个 SKILL.md 的 L0 改为场景驱动结构（何时使用 / 何时不要用 / 怎么做），让 AI 凭名字与 L0 即可判断匹配场景。注册更新： - builtin-skills.json：新增 python-runtime / nodejs-runtime / dev-environment-setup （原 environment-setup 移除），按字母序，共 21 个 skill - manifest.json：totalSkills 19→21，lastUpdated 2026-05-02 下游同步： - docx / pdf / xlsx / pptx 中的环境引用从 environment-setup 拆分为 python-runtime / nodejs-runtime / dev-environment-setup 三向指引 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-06 09:10:41 +08:00 · 2026-05-02 13:30:23 +08:00
parent 5472359814
commit 1a50969b93
29 changed files with 3310 additions and 1386 deletions
--- a/skills/python-runtime/references/hatch-desirecore.md
+++ b/skills/python-runtime/references/hatch-desirecore.md
@@ -0,0 +1,147 @@
+# DesireCore 内置 Hatch（L1 / L2 主路径）
+
+DesireCore 内置 [Hatch](https://hatch.pypa.io/) v1.16.5。Hatch 二进制随应用打包于 `static/hatch/`，运行时位于 `~/.desirecore/runtime/hatch/`，**用户无需单独安装**。
+
+> 与系统 Python 完全隔离：Hatch 安装的 Python 位于 `~/.desirecore/runtime/hatch/local/<version>/`，不修改系统 PATH。
+
+## L1：通过 HTTP API 操作（推荐，DesireCore 应用内）
+
+### 探测 API 可用性
+
+```bash
+PORT_FILE="$HOME/.desirecore/agent-service.port"
+[ -r "$PORT_FILE" ] || { echo "API 不可用，降级到 L2"; exit 1; }
+PORT=$(cat "$PORT_FILE")
+BASE="https://127.0.0.1:${PORT}/api/runtime"
+
+curl -sk --max-time 0.5 "${BASE}/environment" >/dev/null \
+  || { echo "API 超时，降级到 L2"; exit 1; }
+```
+
+### 检查 Hatch 状态 / 安装
+
+```bash
+# 状态：runtime/static 任一存在即 ready
+curl -sk "${BASE}/hatch/status"
+
+# 若未就绪，触发自动下载
+curl -sk -X POST "${BASE}/hatch/install"
+```
+
+### Python 版本管理
+
+```bash
+# 已安装版本
+curl -sk "${BASE}/python/installed"
+# → ["3.11", "3.12"]
+
+# 可安装版本（来自 Hatch python show）
+curl -sk "${BASE}/python/available"
+
+# 安装（异步，立即返回 taskId）
+curl -sk -X POST "${BASE}/python/install" \
+  -H "Content-Type: application/json" \
+  -d '{"version":"3.12"}'
+# → { "taskId": "uuid" }
+
+# 移除
+curl -sk -X POST "${BASE}/python/remove" \
+  -H "Content-Type: application/json" \
+  -d '{"version":"3.10"}'
+```
+
+### 订阅实时输出
+
+DesireCore 内部 Agent 默认连了 Socket.IO；外部脚本若未连，则 100ms 后任务静默执行。要看进度：
+
+- 监听事件 `runtime:terminal`，payload `{ taskId, data }`，按 taskId 过滤
+- 任务结束事件 `runtime:complete`，payload `{ taskId, success }`
+
+### 强制刷新缓存
+
+```bash
+curl -sk -X POST "${BASE}/environment/refresh"
+```
+
+## L2：直接调用 Hatch CLI 绝对路径
+
+### macOS / Linux
+
+```bash
+HATCH=~/.desirecore/runtime/hatch/hatch
+export HATCH_HOME=~/.desirecore/runtime/hatch
+# export HATCH_PYTHON_MIRROR_URL=...   # 中国大陆加速可选
+
+# 列出版本表
+"$HATCH" python show
+# ┌──────────┬─────────┐
+# │ Name     │ Version │
+# ├──────────┼─────────┤
+# │ 3.10     │ 3.10.16 │
+# │ 3.11     │ 3.11.11 │
+# │ 3.12     │ 3.12.8  │
+# │ 3.13     │ 3.13.1  │
+# │ pypy3.10 │ 7.3.17  │
+# └──────────┴─────────┘
+
+# 安装
+"$HATCH" python install 3.12
+"$HATCH" python install 3.12 3.11 3.10   # 批量
+
+# 已装版本（直接读目录最稳）
+ls ~/.desirecore/runtime/hatch/local/
+
+# 移除
+"$HATCH" python remove 3.11
+```
+
+### Windows PowerShell
+
+```powershell
+$Hatch = "$env:USERPROFILE\.desirecore\runtime\hatch\hatch.exe"
+$env:HATCH_HOME = "$env:USERPROFILE\.desirecore\runtime\hatch"
+
+& $Hatch python show
+& $Hatch python install 3.12
+```
+
+### 使用 Hatch 安装的 Python
+
+```bash
+# 直接用绝对路径
+~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 --version
+
+# 创建项目级虚拟环境（venv 推荐）
+~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Windows：`%USERPROFILE%\.desirecore\runtime\hatch\local\3.12\python\python.exe`。
+
+## 可视化管理
+
+DesireCore 应用 → 资源管理器（侧边栏文件夹图标）→ 计算资源 → **运行环境** Tab，GUI 安装 / 删除 Python 版本。
+
+## Hatch vs pyenv
+
+| 维度 | Hatch（DesireCore 内置） | pyenv（社区） |
+|------|--------------------------|---------------|
+| 安装方式 | 随应用自动内置 | 用户手动安装 |
+| Python 存放 | `~/.desirecore/runtime/hatch/local/` | `~/.pyenv/versions/` |
+| 版本切换 | 绝对路径 / venv | shell PATH (`pyenv global/local`) |
+| 系统影响 | 完全隔离 | 修改 shell 启动脚本 |
+| GUI | DesireCore 运行环境 Tab | 无 |
+| 镜像加速 | `HATCH_PYTHON_MIRROR_URL` 环境变量 | `PYTHON_BUILD_MIRROR_URL` |
+| 适用 | 技能执行环境（强隔离） | 系统级日常开发 |
+
+**结论**：DesireCore 应用内、有 Hatch 时永远首选 Hatch；外部脚本/独立项目可考虑 pyenv。
+
+## 故障排查（Hatch 专属）
+
+| 现象 | 排查 |
+|------|------|
+| `~/.desirecore/runtime/hatch/hatch: not found` | 二进制未释放。先 `POST /api/runtime/hatch/install` 触发下载 |
+| Hatch 安装 Python 时网络超时 | 设置 `HATCH_PYTHON_MIRROR_URL` 镜像 |
+| 多版本共存路径混乱 | Hatch 永远绝对路径调用，**不要**写入 PATH |
+| macOS Gatekeeper 阻止运行 | `xattr -d com.apple.quarantine ~/.desirecore/runtime/hatch/hatch` |
--- a/skills/python-runtime/references/pyenv-fallback.md
+++ b/skills/python-runtime/references/pyenv-fallback.md
@@ -0,0 +1,97 @@
+# pyenv（L4 社区方案）
+
+仅在以下情况启用：
+1. 用户明确要求 pyenv（"用 pyenv 装"）
+2. 项目根目录已有 `.python-version` 文件
+3. L1 (HTTP API) / L2 (Hatch CLI) / L3 (系统包管理器) 全部失败
+
+如条件不满足，**不要**主动建议 pyenv——优先 DesireCore Hatch。
+
+## 安装 pyenv
+
+### macOS / Linux
+
+```bash
+curl https://pyenv.run | bash
+
+# zsh
+cat >> ~/.zshrc <<'EOF'
+export PYENV_ROOT="$HOME/.pyenv"
+[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
+eval "$(pyenv init -)"
+EOF
+
+# bash
+cat >> ~/.bashrc <<'EOF'
+export PYENV_ROOT="$HOME/.pyenv"
+[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
+eval "$(pyenv init -)"
+EOF
+
+exec "$SHELL"
+```
+
+#### 编译依赖
+
+| 平台 | 命令 |
+|------|------|
+| macOS | `brew install openssl readline sqlite3 xz zlib tcl-tk` |
+| Ubuntu/Debian | `sudo apt install build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev curl git libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev` |
+| Fedora/RHEL | `sudo dnf install gcc make zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel tk-devel libffi-devel xz-devel` |
+
+### Windows（pyenv-win）
+
+```powershell
+pip install pyenv-win --target "$HOME\.pyenv"
+# 或
+Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; & "./install-pyenv-win.ps1"
+```
+
+环境变量：
+```powershell
+[System.Environment]::SetEnvironmentVariable('PYENV', "$HOME\.pyenv\pyenv-win", 'User')
+[System.Environment]::SetEnvironmentVariable('PYENV_HOME', "$HOME\.pyenv\pyenv-win", 'User')
+# 然后把 %PYENV%\bin 和 %PYENV%\shims 加入 PATH
+```
+
+## 使用 pyenv
+
+```bash
+# 列出可装版本
+pyenv install --list | grep "^  3\."
+
+# 安装
+pyenv install 3.12.4
+pyenv install 3.11.9
+
+# 全局默认
+pyenv global 3.12.4
+
+# 项目级（生成 .python-version）
+pyenv local 3.11.9
+
+# 已装版本
+pyenv versions
+
+# 当前激活
+pyenv version
+
+# 卸载
+pyenv uninstall 3.10.14
+```
+
+## 镜像加速
+
+```bash
+export PYTHON_BUILD_MIRROR_URL="https://npmmirror.com/mirrors/python/"
+pyenv install 3.12.4
+```
+
+## pyenv 常见问题
+
+| 现象 | 排查 |
+|------|------|
+| `pyenv: command not found` | shell 配置未加载，`exec "$SHELL"` 或重启终端 |
+| 编译时 `ModuleNotFoundError: _ssl` | 缺 `libssl-dev` / `openssl`，按上方编译依赖安装 |
+| macOS Big Sur 编译失败 | `LDFLAGS="-L$(brew --prefix openssl)/lib" CPPFLAGS="-I$(brew --prefix openssl)/include" pyenv install 3.12.4` |
+| Windows pyenv 切换无效 | 检查 PATH 中 `%PYENV%\shims` 是否在系统 Python 之前 |
--- a/skills/python-runtime/references/troubleshooting.md
+++ b/skills/python-runtime/references/troubleshooting.md
@@ -0,0 +1,178 @@
+# Python 故障排查
+
+## "python: command not found" / "python3: command not found"
+
+**原因**：未安装或未加入 PATH。
+
+```bash
+# 1. 找一下二进制
+which python3 2>/dev/null; which python 2>/dev/null
+ls /usr/bin/python* /usr/local/bin/python* /opt/homebrew/bin/python* 2>/dev/null
+
+# 2. 查 PATH
+echo "$PATH" | tr ':' '\n' | head -20
+
+# 3. macOS：检查 Homebrew Python
+brew list python 2>/dev/null && echo "Homebrew Python installed"
+
+# 4. 修复 PATH
+# Apple Silicon
+export PATH="/opt/homebrew/bin:$PATH"
+# Intel mac / Linux 常见
+export PATH="/usr/local/bin:$PATH"
+```
+
+**根治**：按主 SKILL.md 决策树重新执行 L1–L3 安装路径。
+
+## "pip: command not found"
+
+```bash
+# 用 module 模式调用
+python3 -m pip --version
+
+# 仍失败：手动 bootstrap
+curl -fsSL https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py
+python3 /tmp/get-pip.py --user
+rm /tmp/get-pip.py
+
+# 把 ~/.local/bin 加入 PATH（zsh / bash）
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+## "externally-managed-environment"（PEP 668）
+
+**触发系统**：Debian 12+、Ubuntu 23.04+、Fedora 38+、Arch（部分）。
+
+**优先级从高到低**：
+
+```bash
+# 方案 1（推荐）：虚拟环境
+python3 -m venv .venv
+source .venv/bin/activate
+pip install package-name
+
+# 方案 2：pipx 装 CLI 工具
+pipx install package-name
+
+# 方案 3：用户目录
+pip install --user package-name
+
+# 方案 4（不推荐，可能破坏系统）
+pip install --break-system-packages package-name
+```
+
+## SSL / TLS 证书错误
+
+```bash
+# pip：升级 certifi
+pip install --upgrade certifi
+
+# 临时绕过（仅调试）
+pip install --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org package-name
+
+# 永久信任（不推荐）
+pip config set global.trusted-host "pypi.org files.pythonhosted.org"
+```
+
+macOS 系统时间偏差也会导致 SSL 失败：`sudo sntp -sS time.apple.com`。
+
+## import 失败
+
+包名 ≠ import 名是最常见原因：
+
+| 安装名 (pip install) | import 名 |
+|----------------------|-----------|
+| Pillow | PIL |
+| python-dateutil | dateutil |
+| beautifulsoup4 | bs4 |
+| scikit-learn | sklearn |
+| PyYAML | yaml |
+| pytorch | torch |
+
+```bash
+# 1. 确认安装到了正确的 Python
+python3 -c "import sys; print(sys.executable)"
+pip3 show package-name
+
+# 2. 是否在虚拟环境
+echo "$VIRTUAL_ENV"
+
+# 3. 强制重装
+pip install --force-reinstall --no-cache-dir package-name
+```
+
+## macOS "xcrun: error" / 编译失败
+
+安装 lxml / numpy / Pillow 等需要 C 扩展的包时：
+
+```bash
+# 安装 / 重置 Xcode CLI
+xcode-select --install
+sudo xcode-select --reset
+
+# 包级依赖
+brew install libxml2 libxslt    # lxml
+brew install libjpeg zlib       # Pillow
+brew install openssl readline   # cryptography 类
+```
+
+## Windows PowerShell 执行策略
+
+```powershell
+Get-ExecutionPolicy
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+之后才能 `.\.venv\Scripts\Activate.ps1`。
+
+## Windows Store 占位符
+
+`python --version` 弹出 Store 页面：
+
+1. 设置 → 应用 → 高级应用设置 → 应用执行别名
+2. 关闭 `python.exe` / `python3.exe` 的 Store 别名
+3. 重启终端
+
+## 代理环境配置
+
+```bash
+# pip
+pip install --proxy http://proxy:port package-name
+pip config set global.proxy http://proxy:port
+
+# 取消
+pip config unset global.proxy
+
+# 系统级（zsh / bash）
+export http_proxy=http://proxy:port
+export https_proxy=http://proxy:port
+```
+
+## EnvironmentSnapshot 信号速查
+
+probe-python.sh 输出后，按字段快速判断：
+
+| 字段 | 期望 | 失败原因 |
+|------|------|----------|
+| `system_python.version` | 非空且 ≥ 3.8 | 未装 Python 或版本太低 |
+| `system_pip.version` | 非空 | pip 未装（macOS Apple 自带 Python 没有 pip） |
+| `hatch_path` | 非空 | DesireCore Hatch 未释放，调 `POST /api/runtime/hatch/install` |
+| `pep668: true` | — | 系统 Python 受保护，必须 venv/pipx |
+| `active_venv` | 操作前为空，激活后非空 | venv 未生效，重新 `source .venv/bin/activate` |
+
+## 重置整个 Python 环境（最后手段）
+
+```bash
+# 1. 退出所有虚拟环境
+deactivate 2>/dev/null
+conda deactivate 2>/dev/null
+
+# 2. 删除可疑虚拟环境
+rm -rf .venv venv
+
+# 3. 重新探测
+bash skills/python-runtime/scripts/probe-python.sh
+
+# 4. 按主 SKILL.md 决策树重新安装
+```
--- a/skills/python-runtime/references/virtualenv.md
+++ b/skills/python-runtime/references/virtualenv.md
@@ -0,0 +1,145 @@
+# Python 虚拟环境
+
+虚拟环境隔离项目依赖，避免污染全局环境。**强烈建议每个项目独立 venv**。
+
+## venv（标准库，首选）
+
+```bash
+# 创建（Python 3.3+ 自带）
+python3 -m venv .venv
+
+# 激活
+# macOS / Linux:
+source .venv/bin/activate
+# Windows CMD:
+.venv\Scripts\activate.bat
+# Windows PowerShell:
+.venv\Scripts\Activate.ps1
+
+# 验证（路径应指向 .venv）
+which python    # macOS / Linux
+where python    # Windows
+
+# 安装依赖
+pip install -r requirements.txt
+
+# 退出
+deactivate
+```
+
+### 用 Hatch 安装的 Python 创建 venv
+
+```bash
+~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 -m venv .venv
+source .venv/bin/activate
+```
+
+## pipx（全局 CLI 工具）
+
+`pipx` 把每个 CLI 工具装在独立 venv 里，对外暴露 shim，不污染系统/项目 Python。
+
+```bash
+# 安装 pipx
+brew install pipx                # macOS
+sudo apt install pipx            # Ubuntu/Debian
+pip install --user pipx          # 通用兜底
+pipx ensurepath
+exec "$SHELL"
+
+# 安装 CLI 工具
+pipx install black
+pipx install ruff
+pipx install markitdown
+pipx install poetry
+pipx install uv
+
+# 升级
+pipx upgrade-all
+
+# 卸载
+pipx uninstall black
+
+# 列表
+pipx list
+```
+
+适用场景：black / ruff / mypy / poetry / uv / markitdown 等命令行工具。
+
+## conda / miniconda（数据科学）
+
+适用于：需要 BLAS / CUDA / 非 Python 依赖（科学计算）。
+
+```bash
+# 安装 miniconda（macOS / Linux）
+curl -fsSL "https://repo.anaconda.com/miniconda/Miniconda3-latest-$(uname -s)-$(uname -m).sh" -o miniconda.sh
+bash miniconda.sh -b -p "$HOME/miniconda3"
+eval "$("$HOME/miniconda3/bin/conda" shell.$(basename $SHELL) hook)"
+
+# Windows: 下载 https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe 安装
+
+# 创建环境
+conda create -n myproject python=3.12
+conda activate myproject
+
+# 装包（conda 优先，pip 兜底）
+conda install numpy pandas scikit-learn
+pip install some-pypi-only-package
+
+# 导出 / 还原
+conda env export > environment.yml
+conda env create -f environment.yml
+
+# 退出
+conda deactivate
+```
+
+### conda 与 DesireCore Hatch 共存
+
+两者都把 Python 装在用户目录，互不影响。规则：
+- 数据科学项目（涉及 numpy/pandas/jupyter/CUDA）→ conda
+- 普通 Web/CLI/办公技能 → Hatch + venv
+
+## requirements.txt 与 pyproject.toml
+
+### requirements.txt（简单）
+
+```
+fastapi==0.111.0
+pydantic>=2.0,<3.0
+markitdown
+```
+
+### pyproject.toml（现代）
+
+```toml
+[project]
+name = "myproj"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+  "fastapi>=0.111",
+  "pydantic>=2.0,<3.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff", "mypy"]
+```
+
+安装：`pip install -e .` 或 `pip install -e ".[dev]"`。
+
+## 何时用哪个
+
+| 场景 | 工具 |
+|------|------|
+| 普通 Python 项目 | venv + pip |
+| 全局 CLI 工具（black/ruff/markitdown） | pipx |
+| 数据科学 / Jupyter / CUDA | conda |
+| 现代项目管理（含构建发布） | Hatch（自带项目管理）或 uv |
+| 严格隔离 / 多 Python 版本快速切换 | DesireCore Hatch + venv |
+
+## 常见误区
+
+- ❌ `sudo pip install` —— 永远不要这样做
+- ❌ 在系统 Python 上直接 `pip install` —— PEP 668 会拒绝
+- ❌ 多个虚拟环境工具同时激活（venv + conda 嵌套）—— 路径会乱
+- ❌ 把 venv 加入 git —— `.venv/` 应该在 `.gitignore` 里