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:
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 决策树重新安装
|
||||
```
|
||||
Reference in New Issue
Block a user