mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-06-06 08:10:48 +08:00
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:
194
skills/python-runtime/SKILL.md
Normal file
194
skills/python-runtime/SKILL.md
Normal file
@@ -0,0 +1,194 @@
|
||||
---
|
||||
name: Python 运行时管理
|
||||
description: >-
|
||||
Use this skill when the user needs to install, upgrade, or troubleshoot
|
||||
Python and pip environments. Covers four-tier fallback strategy: (1)
|
||||
DesireCore HTTP API for in-app installation, (2) DesireCore built-in Hatch
|
||||
CLI for Python version management, (3) system package managers
|
||||
(brew/apt/dnf/winget), (4) community pyenv as last resort. Also covers
|
||||
virtual environments (venv/pipx/conda), PEP 668 externally-managed errors,
|
||||
and import / PATH troubleshooting. Triggers include: "install python", "pip
|
||||
not found", "python not found", "PEP 668", "externally-managed", "venv",
|
||||
"virtualenv", "pipx", "conda", "miniconda", "pyenv", "hatch", "python
|
||||
version", "pip command not found", or any Python-related runtime error.
|
||||
使用场景：用户需要 安装 Python、安装 pip、配置虚拟环境、管理多版本、
|
||||
解决 PEP 668、import 失败、PATH 问题、SSL 证书错误等。
|
||||
version: 1.0.1
|
||||
type: procedural
|
||||
risk_level: low
|
||||
status: enabled
|
||||
disable-model-invocation: true
|
||||
tags:
|
||||
- python
|
||||
- pip
|
||||
- hatch
|
||||
- pyenv
|
||||
- venv
|
||||
- virtualenv
|
||||
- pipx
|
||||
- conda
|
||||
- environment
|
||||
metadata:
|
||||
author: desirecore
|
||||
updated_at: '2026-05-02'
|
||||
market:
|
||||
icon: >-
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0
|
||||
24 24" fill="none"><defs><linearGradient id="py-a" x1="3" y1="3" x2="21"
|
||||
y2="21" gradientUnits="userSpaceOnUse"><stop
|
||||
stop-color="#306998"/><stop offset="1"
|
||||
stop-color="#FFD43B"/></linearGradient></defs><rect x="3" y="3" width="18"
|
||||
height="18" rx="3" fill="url(#py-a)" fill-opacity="0.12"
|
||||
stroke="url(#py-a)" stroke-width="1.5"/><path d="M9 8.5h4.5a1.5 1.5 0 011.5
|
||||
1.5v3a1.5 1.5 0 01-1.5 1.5H9.5A1.5 1.5 0 008 16v.5" stroke="url(#py-a)"
|
||||
stroke-width="1.4" stroke-linecap="round" fill="none"/><path d="M15
|
||||
15.5h-4.5a1.5 1.5 0 01-1.5-1.5v-3a1.5 1.5 0 011.5-1.5H14.5A1.5 1.5 0 0016
|
||||
8v-.5" stroke="url(#py-a)" stroke-width="1.4" stroke-linecap="round"
|
||||
fill="none"/><circle cx="10.5" cy="10" r="0.6" fill="url(#py-a)"/><circle
|
||||
cx="13.5" cy="14" r="0.6" fill="url(#py-a)"/></svg>
|
||||
short_desc: Python 安装、多版本与虚拟环境（DesireCore Hatch 优先）
|
||||
category: development
|
||||
maintainer:
|
||||
name: DesireCore Official
|
||||
verified: true
|
||||
channel: latest
|
||||
---
|
||||
|
||||
# python-runtime 技能
|
||||
|
||||
## L0：一句话摘要
|
||||
|
||||
**何时使用**：用户需要 安装 Python / 升级 Python / 切换 Python 多版本 / 配置
|
||||
pip / 创建虚拟环境（venv / pipx / conda）/ 排查 `python: command not found`、
|
||||
`pip: command not found`、PEP 668 "externally-managed"、SSL 证书、import 失败、
|
||||
PATH 异常 等 Python 运行时问题，或其他 skill（docx / pdf / xlsx / pptx）报告
|
||||
"Python 不可用" 时。
|
||||
|
||||
**怎么做**：优先使用 DesireCore 内置 Hatch，按四级降级（HTTP API → Hatch CLI →
|
||||
系统包管理器 brew/apt/dnf/winget → 社区方案 pyenv）执行。
|
||||
|
||||
## L1：概述与使用场景
|
||||
|
||||
### 能力描述
|
||||
|
||||
procedural skill。每次执行 Python 环境操作前，先运行 `scripts/probe-python.sh` 取 JSON 快照，再按 `references/decision-tree`（→ `../dev-environment-setup/references/decision-tree.md`）四级降级选择路径。
|
||||
|
||||
### 使用场景
|
||||
|
||||
- "python not found" / "pip not found"
|
||||
- 用户要求安装/升级 Python
|
||||
- 用户要求多版本管理（3.10/3.11/3.12 切换）
|
||||
- 创建/激活/调试虚拟环境（venv/pipx/conda）
|
||||
- "externally-managed-environment"（PEP 668）报错
|
||||
- import 失败、PATH 问题、SSL 证书错误
|
||||
- 其他 skill（docx/pdf/xlsx/pptx）报告 Python 不可用
|
||||
|
||||
### 核心价值
|
||||
|
||||
- **DesireCore 优先**：Hatch + HTTP API 作为强制 L1/L2，避免污染系统 Python
|
||||
- **JSON 决策**：probe 脚本输出结构化数据，Claude 可直接解析
|
||||
- **跨平台一致**：macOS / Linux / Windows 统一 4 级降级
|
||||
|
||||
## L2：详细规范
|
||||
|
||||
### 第一步：环境探测（必须）
|
||||
|
||||
```bash
|
||||
bash skills/python-runtime/scripts/probe-python.sh > /tmp/py-probe.json
|
||||
cat /tmp/py-probe.json | jq .
|
||||
```
|
||||
|
||||
输出字段含义见 `../dev-environment-setup/references/probe-snapshot.md`。
|
||||
|
||||
### 第二步：选择执行路径
|
||||
|
||||
按 `../dev-environment-setup/references/decision-tree.md` 判断：
|
||||
|
||||
| 条件 | 路径 |
|
||||
|------|------|
|
||||
| `desirecore_api` 非空 | **L1** HTTP API |
|
||||
| `desirecore_api` 空，`hatch_path` 非空 | **L2** Hatch CLI |
|
||||
| 上述都不满足 | **L3** 系统包管理器（brew/apt/dnf/winget） |
|
||||
| L1–L3 全部失败或用户明示 | **L4** 社区方案（pyenv） |
|
||||
|
||||
### 第三步：执行（仅展示主路径，详见各 references）
|
||||
|
||||
#### L1：HTTP API（→ `references/hatch-desirecore.md`）
|
||||
|
||||
```bash
|
||||
PORT=$(cat ~/.desirecore/agent-service.port)
|
||||
BASE="https://127.0.0.1:${PORT}/api/runtime"
|
||||
|
||||
# 列出可装版本
|
||||
curl -sk "${BASE}/python/available"
|
||||
|
||||
# 触发安装（异步，订阅 runtime:terminal 看进度）
|
||||
curl -sk -X POST "${BASE}/python/install" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"version":"3.12"}'
|
||||
|
||||
# 安装完成后强制刷新缓存
|
||||
curl -sk -X POST "${BASE}/environment/refresh"
|
||||
```
|
||||
|
||||
#### L2：Hatch CLI 绝对路径（→ `references/hatch-desirecore.md`）
|
||||
|
||||
```bash
|
||||
HATCH=~/.desirecore/runtime/hatch/hatch
|
||||
export HATCH_HOME=~/.desirecore/runtime/hatch
|
||||
|
||||
"$HATCH" python install 3.12
|
||||
"$HATCH" python show # 列出已安装/可装版本
|
||||
|
||||
# 直接使用 Hatch 安装的 Python
|
||||
~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 -m venv .venv
|
||||
```
|
||||
|
||||
Windows：`%USERPROFILE%\.desirecore\runtime\hatch\hatch.exe`。
|
||||
|
||||
#### L3：系统包管理器
|
||||
|
||||
| 平台 | 命令 |
|
||||
|------|------|
|
||||
| macOS | `brew install python3` |
|
||||
| Debian/Ubuntu | `sudo apt install python3 python3-pip python3-venv` |
|
||||
| Fedora/RHEL | `sudo dnf install python3 python3-pip` |
|
||||
| Arch | `sudo pacman -S python python-pip` |
|
||||
| Windows | `winget install Python.Python.3` |
|
||||
|
||||
#### L4：pyenv（→ `references/pyenv-fallback.md`）
|
||||
|
||||
仅在用户明示或上述失败时启用。
|
||||
|
||||
### 第四步：虚拟环境
|
||||
|
||||
虚拟环境策略详见 `references/virtualenv.md`：
|
||||
- venv（推荐，标准库）
|
||||
- pipx（全局 CLI 工具如 black/ruff/markitdown）
|
||||
- conda / miniconda（数据科学场景）
|
||||
|
||||
### 第五步：故障排查
|
||||
|
||||
报错时按 `references/troubleshooting.md` 查表：
|
||||
- "python: command not found" / "pip: command not found"
|
||||
- PEP 668 "externally-managed-environment"
|
||||
- SSL/TLS 证书错误
|
||||
- import 失败（包名 vs import 名差异）
|
||||
- macOS xcrun / Xcode CLI 缺失
|
||||
- Windows PowerShell 执行策略阻止脚本
|
||||
- 代理环境配置
|
||||
|
||||
## 重要约束
|
||||
|
||||
1. **绝不 `sudo pip install`**：始终用虚拟环境或 `pipx`。
|
||||
2. **修改了环境后必须刷新**：L1 调 `POST /api/runtime/environment/refresh`；L2/L3/L4 重新跑 probe。
|
||||
3. **跨 skill 协作**：`docx` / `pdf` / `xlsx` / `pptx` 报"Python 不可用"时，进入 L1/L2 安装；办公依赖速查见 `../dev-environment-setup/references/office-deps.md`。
|
||||
4. **不污染系统 Python**：项目级别一律使用 venv，全局 CLI 用 pipx。
|
||||
|
||||
## 引用关系
|
||||
|
||||
- 决策树：`../dev-environment-setup/references/decision-tree.md`
|
||||
- DesireCore 底座：`../dev-environment-setup/references/desirecore-runtime.md`
|
||||
- 探测协议：`../dev-environment-setup/references/probe-snapshot.md`
|
||||
- 办公依赖：`../dev-environment-setup/references/office-deps.md`
|
||||
- 系统工具：`../dev-environment-setup/references/system-tools.md`
|
||||
147
skills/python-runtime/references/hatch-desirecore.md
Normal file
147
skills/python-runtime/references/hatch-desirecore.md
Normal file
@@ -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` |
|
||||
97
skills/python-runtime/references/pyenv-fallback.md
Normal file
97
skills/python-runtime/references/pyenv-fallback.md
Normal file
@@ -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 之前 |
|
||||
178
skills/python-runtime/references/troubleshooting.md
Normal file
178
skills/python-runtime/references/troubleshooting.md
Normal file
@@ -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 决策树重新安装
|
||||
```
|
||||
145
skills/python-runtime/references/virtualenv.md
Normal file
145
skills/python-runtime/references/virtualenv.md
Normal 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
|
||||
# 安装 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` 里
|
||||
103
skills/python-runtime/scripts/probe-python.sh
Executable file
103
skills/python-runtime/scripts/probe-python.sh
Executable file
@@ -0,0 +1,103 @@
|
||||
#!/usr/bin/env bash
|
||||
# python-runtime probe: 输出 Python 环境快照（JSON）
|
||||
# 协议：见 ../../dev-environment-setup/references/probe-snapshot.md
|
||||
|
||||
set +e
|
||||
|
||||
detect_tool() {
|
||||
local name="$1"
|
||||
local path
|
||||
path=$(command -v "$name" 2>/dev/null)
|
||||
if [ -z "$path" ]; then
|
||||
printf '{"path":"","version":""}'
|
||||
return
|
||||
fi
|
||||
local version
|
||||
version=$("$name" --version 2>&1 | head -n1 | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -n1)
|
||||
printf '{"path":"%s","version":"%s"}' "$path" "${version:-}"
|
||||
}
|
||||
|
||||
# ── 平台 ────────────────────────────────
|
||||
case "$(uname -s)" in
|
||||
Darwin) PLATFORM="darwin" ;;
|
||||
Linux) PLATFORM="linux" ;;
|
||||
*) PLATFORM="other" ;;
|
||||
esac
|
||||
ARCH=$(uname -m)
|
||||
case "$ARCH" in
|
||||
arm64|aarch64) ARCH="arm64" ;;
|
||||
x86_64|amd64) ARCH="x64" ;;
|
||||
esac
|
||||
|
||||
# ── DesireCore API ──────────────────────
|
||||
DESIRECORE_API=""
|
||||
PORT_FILE="$HOME/.desirecore/agent-service.port"
|
||||
if [ -r "$PORT_FILE" ]; then
|
||||
PORT=$(cat "$PORT_FILE" 2>/dev/null | tr -d '[:space:]')
|
||||
if [ -n "$PORT" ]; then
|
||||
if curl -sk --max-time 0.5 "https://127.0.0.1:${PORT}/api/runtime/environment" >/dev/null 2>&1; then
|
||||
DESIRECORE_API="https://127.0.0.1:${PORT}"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# ── 系统 Python / pip ───────────────────
|
||||
SYS_PY=$(detect_tool python3)
|
||||
[ "$(echo "$SYS_PY" | grep -c '"path":""')" = "1" ] && SYS_PY=$(detect_tool python)
|
||||
SYS_PIP=$(detect_tool pip3)
|
||||
[ "$(echo "$SYS_PIP" | grep -c '"path":""')" = "1" ] && SYS_PIP=$(detect_tool pip)
|
||||
|
||||
# ── DesireCore Hatch ────────────────────
|
||||
HATCH_BIN="$HOME/.desirecore/runtime/hatch/hatch"
|
||||
HATCH_PATH=""
|
||||
HATCH_VERSION=""
|
||||
if [ -x "$HATCH_BIN" ]; then
|
||||
HATCH_PATH="$HATCH_BIN"
|
||||
HATCH_VERSION=$("$HATCH_BIN" --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -n1)
|
||||
fi
|
||||
|
||||
# Hatch 已安装的 Python 版本（直接读 local/ 目录，避免依赖 hatch 命令）
|
||||
HATCH_LOCAL="$HOME/.desirecore/runtime/hatch/local"
|
||||
HATCH_VERSIONS="[]"
|
||||
if [ -d "$HATCH_LOCAL" ]; then
|
||||
versions=$(ls -1 "$HATCH_LOCAL" 2>/dev/null | sort -V | tr '\n' ',' | sed 's/,$//')
|
||||
if [ -n "$versions" ]; then
|
||||
HATCH_VERSIONS="[\"$(echo "$versions" | sed 's/,/","/g')\"]"
|
||||
fi
|
||||
fi
|
||||
|
||||
# ── 虚拟环境 ────────────────────────────
|
||||
ACTIVE_VENV="${VIRTUAL_ENV:-}"
|
||||
|
||||
# ── PEP 668 ────────────────────────────
|
||||
PEP668="false"
|
||||
for marker in /usr/lib/python*/EXTERNALLY-MANAGED /usr/lib/python3/EXTERNALLY-MANAGED /usr/lib/python3*/EXTERNALLY-MANAGED; do
|
||||
if [ -e "$marker" ]; then
|
||||
PEP668="true"
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
# ── 社区方案 ────────────────────────────
|
||||
PYENV_PATH=$(command -v pyenv 2>/dev/null)
|
||||
[ -z "$PYENV_PATH" ] && [ -d "$HOME/.pyenv/bin" ] && PYENV_PATH="$HOME/.pyenv/bin/pyenv"
|
||||
CONDA_PATH=$(command -v conda 2>/dev/null)
|
||||
[ -z "$CONDA_PATH" ] && [ -x "$HOME/miniconda3/bin/conda" ] && CONDA_PATH="$HOME/miniconda3/bin/conda"
|
||||
|
||||
# ── 输出 JSON ───────────────────────────
|
||||
cat <<EOF
|
||||
{
|
||||
"platform": "${PLATFORM}",
|
||||
"arch": "${ARCH}",
|
||||
"desirecore_api": "${DESIRECORE_API}",
|
||||
"system_python": ${SYS_PY},
|
||||
"system_pip": ${SYS_PIP},
|
||||
"hatch_path": "${HATCH_PATH}",
|
||||
"hatch_version": "${HATCH_VERSION}",
|
||||
"hatch_versions": ${HATCH_VERSIONS},
|
||||
"active_venv": "${ACTIVE_VENV}",
|
||||
"pep668": ${PEP668},
|
||||
"pyenv_path": "${PYENV_PATH:-}",
|
||||
"conda_path": "${CONDA_PATH:-}"
|
||||
}
|
||||
EOF
|
||||
Reference in New Issue
Block a user