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>
This commit is contained in:
2026-05-02 13:30:23 +08:00
parent 5472359814
commit 1a50969b93
29 changed files with 3310 additions and 1386 deletions

View File

@@ -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
# 安装 minicondamacOS / 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`