mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-06-06 05:50:41 +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:
159
skills/dev-environment-setup/SKILL.md
Normal file
159
skills/dev-environment-setup/SKILL.md
Normal file
@@ -0,0 +1,159 @@
|
||||
---
|
||||
name: 开发环境综合配置
|
||||
description: >-
|
||||
Use this skill as a router/index when the user faces a development
|
||||
environment question that spans multiple domains: containers
|
||||
(Docker/Podman), WSL2 on Windows, office-skill dependencies (DOCX/PDF/XLSX/
|
||||
PPTX), or system tools (LibreOffice/Poppler/Pandoc/Tesseract). For pure
|
||||
Python issues use python-runtime skill; for pure Node.js issues use
|
||||
nodejs-runtime skill. Triggers include: "setup environment", "PATH",
|
||||
"WSL", "WSL2", "docker not found", "podman", "container", "office
|
||||
dependency", "LibreOffice", "poppler", "pandoc", "tesseract", or any
|
||||
cross-cutting environment question. 使用场景：用户提到 环境配置、PATH、
|
||||
容器、Docker、Podman、WSL、WSL2、办公依赖、系统工具，或不确定属于 Python /
|
||||
Node.js 时的入口指引。
|
||||
version: 2.0.1
|
||||
type: procedural
|
||||
risk_level: low
|
||||
status: enabled
|
||||
disable-model-invocation: true
|
||||
tags:
|
||||
- environment
|
||||
- docker
|
||||
- container
|
||||
- wsl
|
||||
- office
|
||||
- system-tools
|
||||
- router
|
||||
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="env-a" x1="3" y1="3" x2="21"
|
||||
y2="21" gradientUnits="userSpaceOnUse"><stop stop-color="#34C759"/><stop
|
||||
offset="1" stop-color="#007AFF"/></linearGradient></defs><rect x="3" y="3"
|
||||
width="18" height="18" rx="3" fill="url(#env-a)" fill-opacity="0.1"
|
||||
stroke="url(#env-a)" stroke-width="1.5"/><path d="M7 8l3 3-3 3"
|
||||
stroke="url(#env-a)" stroke-width="1.5" stroke-linecap="round"
|
||||
stroke-linejoin="round"/><path d="M13 16h4" stroke="url(#env-a)"
|
||||
stroke-width="1.5" stroke-linecap="round"/></svg>
|
||||
short_desc: 开发环境综合入口（容器 / WSL / 办公依赖 / 系统工具）
|
||||
category: productivity
|
||||
maintainer:
|
||||
name: DesireCore Official
|
||||
verified: true
|
||||
channel: latest
|
||||
---
|
||||
|
||||
# dev-environment-setup 技能（v2.0.0 router）
|
||||
|
||||
## L0：一句话摘要
|
||||
|
||||
**何时使用**：用户需要
|
||||
|
||||
- 安装 / 排查 **Docker** 或 **Podman** 容器（"docker not found"、daemon 启动、镜像加速等）
|
||||
- 在 Windows 上配置 **WSL2**（Linux 子系统）
|
||||
- 一次性安装 **办公技能依赖**（DOCX / PDF / XLSX / PPTX 所需的 Python 包 + npm 包 + 系统工具）
|
||||
- 安装 **系统工具**：LibreOffice / Poppler / Pandoc / Tesseract / qpdf / ImageMagick / Ghostscript / Git
|
||||
- **不确定** 问题属于 Python 还是 Node.js，需要先做综合诊断
|
||||
|
||||
**何时不要用**：纯 Python 问题用 `python-runtime`，纯 Node.js 问题用 `nodejs-runtime`。
|
||||
|
||||
**怎么做**：先跑 `scripts/probe.sh`（Windows 用 `probe.ps1`）取系统快照 JSON，
|
||||
按结果路由到对应 references 或子 skill；同时也是 DesireCore 内置 Hatch / Volta /
|
||||
HTTP API / Socket.IO 集成的事实源（`references/desirecore-runtime.md`）。
|
||||
|
||||
## L1：路由规则
|
||||
|
||||
按用户问题的关键字直接转到对应 skill 或文档：
|
||||
|
||||
| 关键字 / 场景 | 路径 |
|
||||
|--------------|------|
|
||||
| python / pip / venv / pyenv / hatch / virtualenv / PEP 668 | `python-runtime` skill |
|
||||
| node / npm / pnpm / yarn / volta / nvm / fnm / EACCES | `nodejs-runtime` skill |
|
||||
| docker / podman / container / 容器守护进程 | `references/container.md` |
|
||||
| WSL / WSL2 / Windows Linux 子系统 | `references/wsl.md` |
|
||||
| DOCX / PDF / XLSX / PPTX 依赖 / 办公技能依赖 | `references/office-deps.md` |
|
||||
| LibreOffice / poppler / pandoc / tesseract / qpdf | `references/system-tools.md` |
|
||||
| 不确定属于哪类、想要快速诊断 | 先跑 `scripts/probe.sh` 看 JSON |
|
||||
| DesireCore Hatch / Volta / HTTP API / Socket.IO | `references/desirecore-runtime.md` |
|
||||
| 四级降级决策（API → CLI → 包管理器 → 社区方案） | `references/decision-tree.md` |
|
||||
|
||||
## L2：详细规范
|
||||
|
||||
### 第一步：快速诊断
|
||||
|
||||
```bash
|
||||
bash skills/dev-environment-setup/scripts/probe.sh > /tmp/env-probe.json
|
||||
cat /tmp/env-probe.json | jq .
|
||||
```
|
||||
|
||||
输出字段含义：见 `references/probe-snapshot.md`。Windows 用 `scripts/probe.ps1`。
|
||||
|
||||
### 第二步：按结果路由
|
||||
|
||||
- `desirecore_api` 非空 → 走 HTTP API 路径（`references/desirecore-runtime.md`）
|
||||
- `tools.python3.available = false` 或 `tools.node.available = false` → 进入对应子 skill
|
||||
- `tools.docker.available = false` 且用户需容器 → `references/container.md`
|
||||
- `wsl.installed = false` 且 Windows 用户 → `references/wsl.md`
|
||||
|
||||
### 第三步：执行子 skill 决策树
|
||||
|
||||
`python-runtime` 与 `nodejs-runtime` 都有自己的四级降级（L1 API → L2 内置 CLI → L3 系统包管理器 → L4 社区方案），定义在共享的 `references/decision-tree.md`。
|
||||
|
||||
### 第四步：办公技能依赖
|
||||
|
||||
办公四件套（DOCX / PDF / XLSX / PPTX）依赖速查：`references/office-deps.md`。包含 Python 包、npm 包、系统工具的一键安装命令。
|
||||
|
||||
### 第五步：系统工具
|
||||
|
||||
LibreOffice / Poppler / Pandoc / Tesseract / qpdf / ImageMagick / Ghostscript 安装与故障排查：`references/system-tools.md`。
|
||||
|
||||
## DesireCore 内置环境管理底座
|
||||
|
||||
DesireCore 内置 Hatch（Python）和 Volta（Node.js），通过 HTTP API + Socket.IO 提供完整的环境管理能力。本 skill 与子 skill（python/nodejs）都依赖：
|
||||
|
||||
| 文档 | 内容 |
|
||||
|------|------|
|
||||
| `references/desirecore-runtime.md` | 二进制路径表、HTTP API 速查、Socket.IO 事件契约、`EnvironmentSnapshot` 数据结构 |
|
||||
| `references/decision-tree.md` | 四级降级流程图、判定失败的具体信号、切换提示 |
|
||||
| `references/probe-snapshot.md` | 探测脚本 JSON 输出协议 |
|
||||
|
||||
## 重要约束
|
||||
|
||||
1. **不要把 python / node / pip / npm 强关键词写入本 skill description**——这些归属各自的子 skill，避免触发冲突。
|
||||
2. **API 优先**：`scripts/probe.sh` 第一步检测 `~/.desirecore/agent-service.port`；存在则推荐 HTTP API 路径。
|
||||
3. **缓存协同**：任何安装/移除完成后，调 `POST /api/runtime/environment/refresh` 失效缓存，再发后续 GET。
|
||||
4. **跨平台**：所有命令模板提供 macOS / Linux + Windows（PowerShell）双版本。
|
||||
|
||||
## 子 skill 与文档清单
|
||||
|
||||
```
|
||||
skills/
|
||||
├── python-runtime/ # Python 环境（Hatch 优先）
|
||||
├── nodejs-runtime/ # Node.js 环境（Volta 优先）
|
||||
└── dev-environment-setup/ # 本 skill（综合入口）
|
||||
├── references/
|
||||
│ ├── desirecore-runtime.md
|
||||
│ ├── decision-tree.md
|
||||
│ ├── probe-snapshot.md
|
||||
│ ├── container.md
|
||||
│ ├── wsl.md
|
||||
│ ├── office-deps.md
|
||||
│ └── system-tools.md
|
||||
└── scripts/
|
||||
├── probe.sh
|
||||
└── probe.ps1
|
||||
```
|
||||
|
||||
## 升级说明（v1.x → v2.0.0）
|
||||
|
||||
- v1.x 是单文件 1380 行的全能手册，已拆分。
|
||||
- Python 相关 → `python-runtime`
|
||||
- Node.js 相关 → `nodejs-runtime`
|
||||
- Docker / WSL / 办公依赖 / 系统工具 → 本 skill 的 `references/`
|
||||
- DesireCore Hatch / Volta 从"可选社区方案"升级为强制 L1/L2 主路径
|
||||
|
||||
下游 skill（docx / pdf / xlsx / pptx）应将 "Python 环境问题请参考 dev-environment-setup" 改写为 "Python 环境问题请参考 python-runtime / Node.js 环境问题请参考 nodejs-runtime"。
|
||||
193
skills/dev-environment-setup/references/container.md
Normal file
193
skills/dev-environment-setup/references/container.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# 容器运行环境（Docker / Podman）
|
||||
|
||||
容器在开发中越来越常见——数据库、消息队列、AI 推理服务等多通过容器部署。
|
||||
|
||||
## 检测
|
||||
|
||||
```bash
|
||||
docker --version 2>/dev/null && docker info --format '{{.OperatingSystem}}' 2>/dev/null \
|
||||
|| echo "Docker NOT FOUND or daemon not running"
|
||||
|
||||
podman --version 2>/dev/null || echo "Podman NOT FOUND"
|
||||
```
|
||||
|
||||
## Docker 安装
|
||||
|
||||
### macOS
|
||||
|
||||
推荐 Docker Desktop（含 Docker Engine + Compose + GUI）：
|
||||
|
||||
```bash
|
||||
# 方式 1：Homebrew Cask（推荐）
|
||||
brew install --cask docker
|
||||
|
||||
# 方式 2：官网下载
|
||||
# https://www.docker.com/products/docker-desktop/
|
||||
# 选择 Apple Silicon 或 Intel
|
||||
|
||||
# 验证
|
||||
docker --version
|
||||
docker run hello-world
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
**推荐 Docker Desktop + WSL2 后端**（先装 WSL2，见 `wsl.md`）：
|
||||
|
||||
1. 下载 [Docker Desktop](https://www.docker.com/products/docker-desktop/)
|
||||
2. 安装时勾选 "Use WSL 2 instead of Hyper-V"
|
||||
3. Settings → General 确认 "Use the WSL 2 based engine" 已启用
|
||||
|
||||
```powershell
|
||||
winget install Docker.DockerDesktop
|
||||
docker --version
|
||||
docker run hello-world
|
||||
```
|
||||
|
||||
**轻量替代（仅 CLI，通过 WSL2 内）**：
|
||||
|
||||
```bash
|
||||
# 在 WSL2 Ubuntu 中
|
||||
sudo apt update
|
||||
sudo apt install docker.io docker-compose-v2
|
||||
sudo usermod -aG docker $USER
|
||||
# 重新登录 WSL2 后生效
|
||||
```
|
||||
|
||||
### Linux（Debian / Ubuntu）
|
||||
|
||||
```bash
|
||||
# 安装 Docker Engine（官方仓库）
|
||||
sudo apt update
|
||||
sudo apt install ca-certificates curl
|
||||
sudo install -m 0755 -d /etc/apt/keyrings
|
||||
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
|
||||
sudo chmod a+r /etc/apt/keyrings/docker.asc
|
||||
|
||||
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
|
||||
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
|
||||
|
||||
sudo apt update
|
||||
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin
|
||||
|
||||
# 免 sudo
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
|
||||
docker run hello-world
|
||||
```
|
||||
|
||||
### Linux（Fedora / RHEL）
|
||||
|
||||
```bash
|
||||
sudo dnf install dnf-plugins-core
|
||||
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
|
||||
sudo dnf install docker-ce docker-ce-cli containerd.io docker-compose-plugin
|
||||
sudo systemctl start docker
|
||||
sudo systemctl enable docker
|
||||
sudo usermod -aG docker $USER
|
||||
```
|
||||
|
||||
## Podman（无守护进程替代）
|
||||
|
||||
兼容 Docker CLI，无后台守护进程，更轻量。
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install podman
|
||||
podman machine init
|
||||
podman machine start
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install podman
|
||||
|
||||
# Fedora（预装）
|
||||
podman --version
|
||||
|
||||
# Windows
|
||||
winget install RedHat.Podman
|
||||
```
|
||||
|
||||
使用方式与 Docker 一致：
|
||||
```bash
|
||||
podman run hello-world
|
||||
podman ps
|
||||
podman images
|
||||
```
|
||||
|
||||
### Docker → Podman 别名
|
||||
|
||||
```bash
|
||||
echo 'alias docker=podman' >> ~/.zshrc
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### "Cannot connect to the Docker daemon"
|
||||
|
||||
```bash
|
||||
# Linux
|
||||
sudo systemctl start docker
|
||||
sudo systemctl enable docker
|
||||
|
||||
# macOS / Windows
|
||||
# 启动 Docker Desktop 应用（系统托盘应有鲸鱼图标）
|
||||
|
||||
# WSL2
|
||||
# 在 Windows 端重启 Docker Desktop
|
||||
```
|
||||
|
||||
### "permission denied while trying to connect to the Docker daemon socket"
|
||||
|
||||
```bash
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker # 当前 shell 立即生效
|
||||
# 或重新登录
|
||||
```
|
||||
|
||||
### Docker Desktop 占用资源过高
|
||||
|
||||
Docker Desktop Settings → Resources 调 CPU / Memory。WSL2 后端可编辑 `~/.wslconfig`：
|
||||
|
||||
```ini
|
||||
[wsl2]
|
||||
memory=4GB
|
||||
processors=2
|
||||
swap=2GB
|
||||
```
|
||||
|
||||
### 镜像下载慢（中国大陆）
|
||||
|
||||
```bash
|
||||
# 编辑 /etc/docker/daemon.json
|
||||
sudo tee /etc/docker/daemon.json <<EOF
|
||||
{
|
||||
"registry-mirrors": [
|
||||
"https://mirror.ccs.tencentyun.com",
|
||||
"https://docker.m.daocloud.io"
|
||||
]
|
||||
}
|
||||
EOF
|
||||
sudo systemctl restart docker
|
||||
```
|
||||
|
||||
macOS / Windows 在 Docker Desktop Settings → Docker Engine 中编辑 JSON。
|
||||
|
||||
### 磁盘空间被吃光
|
||||
|
||||
```bash
|
||||
docker system df # 查用量
|
||||
docker system prune -a # 清未用镜像/容器/网络
|
||||
docker volume prune # 清未挂载 volume（小心！数据会丢）
|
||||
```
|
||||
|
||||
## 容器场景速查
|
||||
|
||||
| 场景 | 镜像 | 启动 |
|
||||
|------|------|------|
|
||||
| Postgres 测试 | `postgres:16` | `docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=test postgres:16` |
|
||||
| Redis | `redis:7` | `docker run -d -p 6379:6379 redis:7` |
|
||||
| MySQL | `mysql:8` | `docker run -d -p 3306:3306 -e MYSQL_ROOT_PASSWORD=test mysql:8` |
|
||||
| MinIO（S3 兼容） | `minio/minio` | `docker run -d -p 9000:9000 -p 9001:9001 minio/minio server /data --console-address :9001` |
|
||||
|
||||
更复杂的场景使用 `docker compose up -d`。
|
||||
163
skills/dev-environment-setup/references/decision-tree.md
Normal file
163
skills/dev-environment-setup/references/decision-tree.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# 环境管理四级降级决策树
|
||||
|
||||
`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/agent-service.port` 文件存在且可读
|
||||
- `curl -sk --max-time 0.5 https://127.0.0.1:${PORT}/api/runtime/environment` 返回 2xx
|
||||
- 当前会话能订阅 Socket.IO（DesireCore 内部 Agent 默认满足）
|
||||
|
||||
**典型操作**
|
||||
|
||||
```bash
|
||||
PORT=$(cat ~/.desirecore/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）**
|
||||
|
||||
```bash
|
||||
HATCH=~/.desirecore/runtime/hatch/hatch
|
||||
VOLTA=~/.desirecore/runtime/volta/volta
|
||||
|
||||
export HATCH_HOME=~/.desirecore/runtime/hatch
|
||||
export VOLTA_HOME=~/.desirecore/runtime/volta
|
||||
|
||||
"$HATCH" python install 3.12
|
||||
"$VOLTA" install node@22
|
||||
```
|
||||
|
||||
**典型操作（Windows PowerShell）**
|
||||
|
||||
```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` 非空）
|
||||
|
||||
## 每次升级版本后
|
||||
|
||||
无论走哪条路径，**安装/移除完成后立即调用**：
|
||||
|
||||
```bash
|
||||
# L1 模式
|
||||
curl -sk -X POST "${BASE}/environment/refresh"
|
||||
|
||||
# L2/L3/L4 模式（强制 probe 输出最新结果）
|
||||
bash <skill>/scripts/probe-{python,node}.sh
|
||||
```
|
||||
|
||||
避免后续判断基于陈旧缓存。
|
||||
169
skills/dev-environment-setup/references/desirecore-runtime.md
Normal file
169
skills/dev-environment-setup/references/desirecore-runtime.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# DesireCore 内置环境管理底座
|
||||
|
||||
DesireCore 内置了完整的开发环境管理基础设施。`python-runtime` 和 `nodejs-runtime` 两个 skill 共用本文档作为事实源。
|
||||
|
||||
## 一、内置工具二进制
|
||||
|
||||
### Hatch（Python 项目与版本管理器，v1.16.5）
|
||||
|
||||
| 平台 | 运行时绝对路径（用户安装版，优先） | 静态打包兜底 |
|
||||
|------|----------------------------------|--------------|
|
||||
| macOS / Linux | `~/.desirecore/runtime/hatch/hatch` | 应用包内 `static/hatch/hatch` |
|
||||
| Windows | `%USERPROFILE%\.desirecore\runtime\hatch\hatch.exe` | 应用包内 `static/hatch/hatch.exe` |
|
||||
|
||||
**Python 版本安装目录**：`~/.desirecore/runtime/hatch/local/<版本>/python/bin/python3`（macOS/Linux），Windows 为 `python.exe`。
|
||||
|
||||
### Volta（Node.js 工具链管理器，v2.0.2）
|
||||
|
||||
| 平台 | 运行时绝对路径 | 静态打包兜底 |
|
||||
|------|----------------|--------------|
|
||||
| macOS / Linux | `~/.desirecore/runtime/volta/volta` | 应用包内 `static/volta/volta` |
|
||||
| Windows | `%USERPROFILE%\.desirecore\runtime\volta\volta.exe` | 应用包内 `static/volta/volta.exe` |
|
||||
|
||||
**Node.js 安装目录**：`~/.desirecore/runtime/volta/tools/image/node/<version>/`，包管理器在 `tools/image/{packages,pnpm,yarn,npm}/`。
|
||||
|
||||
### 优先级规则
|
||||
|
||||
`runtime/` 目录优先于 `static/`。当用户更新过 Hatch/Volta 时，新版本写入 `runtime/`，DesireCore 优先调用之。
|
||||
|
||||
## 二、关键环境变量
|
||||
|
||||
| 变量 | 作用 | 默认/示例 |
|
||||
|------|------|----------|
|
||||
| `HATCH_HOME` | Hatch 工作目录 | `~/.desirecore/runtime/hatch` |
|
||||
| `HATCH_PYTHON_MIRROR_URL` | Python 下载镜像 | 加速节点（中国大陆） |
|
||||
| `VOLTA_HOME` | Volta 工作目录 | `~/.desirecore/runtime/volta` |
|
||||
| `VOLTA_NODE_MIRROR` | Node.js 下载镜像 | `https://npmmirror.com/mirrors/node` |
|
||||
| `VOLTA_FEATURE_PNPM` | 启用 pnpm 管理 | `1` |
|
||||
|
||||
DesireCore 在启动子进程时会自动注入这些变量；外部直接调用绝对路径 CLI 时需手动 export。
|
||||
|
||||
## 三、HTTP API 速查表
|
||||
|
||||
DesireCore agent-service 启动后将端口写入 `~/.desirecore/agent-service.port`。全部接口走 **HTTPS + 自签名证书**（curl 需要 `-k`）。
|
||||
|
||||
```bash
|
||||
PORT=$(cat ~/.desirecore/agent-service.port)
|
||||
BASE="https://127.0.0.1:${PORT}/api/runtime"
|
||||
```
|
||||
|
||||
### 环境检测
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/environment` | 返回完整 `EnvironmentSnapshot`（platform/arch/tools/wsl） |
|
||||
| POST | `/environment/refresh` | 清除进程级缓存并重新检测，返回新快照 |
|
||||
|
||||
### 工具链状态与安装
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/hatch/status` | 检查 Hatch 是否就绪（runtime/static 任一存在即可） |
|
||||
| POST | `/hatch/install` | 下载并安装 Hatch 到 `runtime/hatch/`（同步返回成功/失败） |
|
||||
| GET | `/volta/status` | 检查 Volta 是否就绪 |
|
||||
| POST | `/volta/install` | 下载并安装 Volta 到 `runtime/volta/` |
|
||||
|
||||
### Python 版本管理
|
||||
|
||||
| 方法 | 路径 | 请求体 / 返回 |
|
||||
|------|------|--------------|
|
||||
| GET | `/python/installed` | 返回已安装版本列表（`["3.11", "3.12"]`） |
|
||||
| GET | `/python/available` | 返回可安装版本（依赖 Hatch 元数据） |
|
||||
| POST | `/python/install` | `{ "version": "3.12" }` → `{ "taskId": "uuid" }`，订阅 `runtime:terminal` 流 |
|
||||
| POST | `/python/remove` | `{ "version": "3.11" }` → `{ "taskId": "uuid" }` |
|
||||
|
||||
### Node.js 版本管理
|
||||
|
||||
| 方法 | 路径 | 请求体 / 返回 |
|
||||
|------|------|--------------|
|
||||
| GET | `/node/installed` | 返回已安装版本 |
|
||||
| GET | `/node/available` | 返回可安装版本（远端 nodejs.org/dist 或 GitHub Releases，2h 缓存）；网络失败返回 502 |
|
||||
| POST | `/node/install` | `{ "version": "22" }` → `{ "taskId": "uuid" }` |
|
||||
| POST | `/node/remove` | `{ "version": "22.11.0" }` → `{ "taskId": "uuid" }` |
|
||||
|
||||
### 包管理器（pnpm / yarn / npm）
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/pkg/{tool}/installed` | tool ∈ {pnpm, yarn, npm} |
|
||||
| GET | `/pkg/{tool}/available` | 失败返回 502 |
|
||||
| POST | `/pkg/{tool}/install` | `{ "version": "9" }` → `{ "taskId": "uuid" }` |
|
||||
| POST | `/pkg/{tool}/remove` | `{ "version": "9.0.0" }` → `{ "taskId": "uuid" }` |
|
||||
|
||||
## 四、Socket.IO 实时输出契约
|
||||
|
||||
耗时操作（`*/install`、`*/remove`）立即返回 `{ taskId }`，真正的执行延迟 100ms 启动，期间通过 Socket.IO 推送：
|
||||
|
||||
| 事件 | Payload | 触发时机 |
|
||||
|------|---------|----------|
|
||||
| `runtime:terminal` | `{ taskId, data }` | 每行 stdout/stderr 输出 + 操作开始/结束的状态行 |
|
||||
| `runtime:complete` | `{ taskId, success }` | 任务结束（成功 / 失败 / 异常） |
|
||||
|
||||
**前端订阅时序**：先 HTTP POST 拿 taskId → 再连 Socket.IO 监听该 taskId → 服务端 100ms 后开工。Skill 在无 Socket.IO 客户端时不要走异步 HTTP API（无法收到日志），改用绝对路径 CLI 同步执行。
|
||||
|
||||
## 五、API 可用性探测
|
||||
|
||||
skill 必须先判定 API 是否可达，再决定走 HTTP 还是 CLI：
|
||||
|
||||
```bash
|
||||
PORT_FILE="$HOME/.desirecore/agent-service.port"
|
||||
if [ -r "$PORT_FILE" ]; then
|
||||
PORT=$(cat "$PORT_FILE")
|
||||
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
|
||||
```
|
||||
|
||||
无 `agent-service.port` 文件、curl 超时（0.5s）、HTTP 非 2xx 一律视为不可达，立即降级到 CLI 路径。
|
||||
|
||||
## 六、EnvironmentSnapshot 数据结构
|
||||
|
||||
`GET /api/runtime/environment` 返回结构（详见 `lib/agent-service/environment-detection.ts`）：
|
||||
|
||||
```ts
|
||||
type ToolDetection = {
|
||||
available: boolean
|
||||
command?: string // 实际命令名（python3 / python）
|
||||
version?: string // 提取后的版本号
|
||||
path?: string // which/where 解析的绝对路径
|
||||
}
|
||||
|
||||
type EnvironmentSnapshot = {
|
||||
platform: 'darwin' | 'win32' | 'linux'
|
||||
arch: string
|
||||
tools: {
|
||||
python: ToolDetection
|
||||
pip: ToolDetection
|
||||
node: ToolDetection
|
||||
npm: ToolDetection
|
||||
docker: ToolDetection
|
||||
podman: ToolDetection
|
||||
git: ToolDetection
|
||||
}
|
||||
wsl?: {
|
||||
installed: boolean
|
||||
version?: string
|
||||
defaultDistro?: string
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 七、缓存与失效
|
||||
|
||||
`detectRuntimeEnvironment()` 使用进程级缓存。当 skill 触发了安装/移除操作后，应立即调用：
|
||||
|
||||
```bash
|
||||
curl -sk -X POST "${DESIRECORE_API}/api/runtime/environment/refresh"
|
||||
```
|
||||
|
||||
强制刷新；否则后续 GET `/environment` 仍返回旧快照。
|
||||
|
||||
## 八、参考源代码
|
||||
|
||||
| 模块 | 文件 | 行数（仓库 ~/Project/desirecore） |
|
||||
|------|------|----------------------------------|
|
||||
| 工具检测 | `lib/agent-service/environment-detection.ts` | 1–310 |
|
||||
| 工具链管理（Hatch/Volta + 版本安装） | `lib/agent-service/runtime-manager.ts` | 1–1165 |
|
||||
| HTTP 路由 | `lib/agent-service/routes/runtime-env-routes.ts` | 1–186 |
|
||||
| 端口文件 | `~/.desirecore/agent-service.port` | DesireCore 启动时写入 |
|
||||
175
skills/dev-environment-setup/references/office-deps.md
Normal file
175
skills/dev-environment-setup/references/office-deps.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# 办公技能依赖速查
|
||||
|
||||
DesireCore 办公四件套（DOCX / PDF / XLSX / PPTX）所需依赖汇总。Python 包通过 `python-runtime` skill 决策树安装；Node.js 包通过 `nodejs-runtime` skill；系统工具见 `system-tools.md`。
|
||||
|
||||
## DOCX（Word 文档）
|
||||
|
||||
```bash
|
||||
# Python 包
|
||||
pip install lxml defusedxml
|
||||
|
||||
# Node.js 包
|
||||
npm install -g docx
|
||||
|
||||
# 系统工具
|
||||
# pandoc —— 文本提取
|
||||
# LibreOffice —— PDF 转换
|
||||
```
|
||||
|
||||
## PDF（PDF 文档）
|
||||
|
||||
```bash
|
||||
# Python 核心
|
||||
pip install pypdf pdfplumber Pillow
|
||||
|
||||
# Python 可选
|
||||
pip install reportlab # PDF 创建
|
||||
pip install pdf2image # PDF 转图片（需 poppler）
|
||||
pip install pytesseract # OCR（需 tesseract）
|
||||
|
||||
# 系统工具
|
||||
# poppler-utils —— pdftotext / pdftoppm / pdfimages
|
||||
# qpdf —— 合并 / 拆分 / 解密
|
||||
# tesseract —— OCR 引擎
|
||||
```
|
||||
|
||||
## XLSX（电子表格）
|
||||
|
||||
```bash
|
||||
# Python
|
||||
pip install openpyxl pandas
|
||||
|
||||
# 系统工具
|
||||
# LibreOffice —— 公式重算
|
||||
```
|
||||
|
||||
## PPTX（演示文稿）
|
||||
|
||||
```bash
|
||||
# Python
|
||||
pip install "markitdown[pptx]" Pillow
|
||||
|
||||
# Node.js
|
||||
npm install -g pptxgenjs
|
||||
|
||||
# 系统工具
|
||||
# LibreOffice —— PDF 转换
|
||||
# poppler-utils —— PDF 转图片
|
||||
```
|
||||
|
||||
## 一键安装四件套全部依赖
|
||||
|
||||
### macOS / Linux
|
||||
|
||||
```bash
|
||||
# Python（在虚拟环境中，或用 pipx 安装 CLI 工具）
|
||||
pip install lxml defusedxml pypdf pdfplumber Pillow reportlab openpyxl pandas "markitdown[pptx]"
|
||||
|
||||
# Node.js（用户级 prefix，避免 sudo）
|
||||
npm install -g docx pptxgenjs
|
||||
|
||||
# 系统工具（macOS）
|
||||
brew install --cask libreoffice
|
||||
brew install poppler qpdf pandoc tesseract tesseract-lang
|
||||
|
||||
# 系统工具（Ubuntu/Debian）
|
||||
sudo apt install libreoffice poppler-utils qpdf pandoc tesseract-ocr tesseract-ocr-chi-sim
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
```powershell
|
||||
# Python
|
||||
pip install lxml defusedxml pypdf pdfplumber Pillow reportlab openpyxl pandas "markitdown[pptx]"
|
||||
|
||||
# Node.js
|
||||
npm install -g docx pptxgenjs
|
||||
|
||||
# 系统工具
|
||||
winget install TheDocumentFoundation.LibreOffice
|
||||
winget install JohnMacFarlane.Pandoc
|
||||
# poppler / qpdf / tesseract 见 system-tools.md
|
||||
```
|
||||
|
||||
## 包名 vs import 名
|
||||
|
||||
| 安装名（pip） | import 名 |
|
||||
|---------------|-----------|
|
||||
| Pillow | PIL |
|
||||
| beautifulsoup4 | bs4 |
|
||||
| python-dateutil | dateutil |
|
||||
| markitdown | markitdown |
|
||||
| pypdf | pypdf |
|
||||
|
||||
## 环境验证脚本
|
||||
|
||||
四件套依赖速查（保存为 `check-office.sh`）：
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
echo "=== Python ==="
|
||||
python3 --version 2>/dev/null || echo "MISSING: python3"
|
||||
|
||||
echo "=== pip ==="
|
||||
pip3 --version 2>/dev/null || echo "MISSING: pip3"
|
||||
|
||||
echo "=== Node.js ==="
|
||||
node --version 2>/dev/null || echo "MISSING: node"
|
||||
|
||||
echo "=== npm ==="
|
||||
npm --version 2>/dev/null || echo "MISSING: npm"
|
||||
|
||||
echo "=== Python Packages ==="
|
||||
python3 - <<'PY'
|
||||
packages = {
|
||||
'lxml': 'lxml',
|
||||
'defusedxml': 'defusedxml',
|
||||
'pypdf': 'pypdf',
|
||||
'pdfplumber': 'pdfplumber',
|
||||
'PIL': 'Pillow',
|
||||
'openpyxl': 'openpyxl',
|
||||
'pandas': 'pandas',
|
||||
'markitdown': 'markitdown',
|
||||
'reportlab': 'reportlab',
|
||||
}
|
||||
for mod, pkg in packages.items():
|
||||
try:
|
||||
__import__(mod)
|
||||
print(f' OK: {pkg}')
|
||||
except ImportError:
|
||||
print(f' MISSING: {pkg}')
|
||||
PY
|
||||
|
||||
echo "=== Node.js Global Packages ==="
|
||||
for pkg in docx pptxgenjs; do
|
||||
node -e "require('$pkg')" 2>/dev/null && echo " OK: $pkg" || echo " MISSING: $pkg"
|
||||
done
|
||||
|
||||
echo "=== System Tools ==="
|
||||
for cmd in soffice pandoc pdftoppm pdftotext qpdf tesseract; do
|
||||
command -v "$cmd" >/dev/null 2>&1 && echo " OK: $cmd" || echo " MISSING: $cmd"
|
||||
done
|
||||
```
|
||||
|
||||
## 跨 skill 协作
|
||||
|
||||
办公技能（docx / pdf / xlsx / pptx）报告依赖缺失时，按以下顺序：
|
||||
|
||||
1. **Python 缺失** → 触发 `python-runtime` skill 决策树
|
||||
2. **Node.js 缺失** → 触发 `nodejs-runtime` skill 决策树
|
||||
3. **Python/Node.js 包缺失** → 上方一键命令
|
||||
4. **系统工具缺失** → `system-tools.md`
|
||||
|
||||
## 在 DesireCore 应用内通过 API 装包
|
||||
|
||||
DesireCore 内置 Hatch/Volta，但**不直接管理 pip / npm 包安装**——只管理 Python / Node 自身版本。包安装仍走 `pip install` / `npm install`。
|
||||
|
||||
如果使用 Hatch 创建的 Python：
|
||||
```bash
|
||||
~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 -m pip install lxml defusedxml
|
||||
```
|
||||
|
||||
如果使用 Volta 安装的 Node：
|
||||
```bash
|
||||
~/.desirecore/runtime/volta/bin/npm install -g docx pptxgenjs
|
||||
```
|
||||
118
skills/dev-environment-setup/references/probe-snapshot.md
Normal file
118
skills/dev-environment-setup/references/probe-snapshot.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# 环境探测 JSON 协议
|
||||
|
||||
`probe.sh` / `probe.ps1` / `probe-python.sh` / `probe-node.sh` 输出统一 JSON。Skill 解析 JSON 后再决策，避免逐条 grep。
|
||||
|
||||
## 通用字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `platform` | `"darwin" \| "linux" \| "win32"` | 操作系统标识 |
|
||||
| `arch` | `"arm64" \| "x64" \| ...` | CPU 架构 |
|
||||
| `desirecore_api` | `string` | 探测到的 DesireCore agent-service URL，不可达时为 `""` |
|
||||
| `desirecore_port_file` | `string` | `~/.desirecore/agent-service.port` 是否存在 |
|
||||
|
||||
## probe.sh / probe.ps1（父级 dev-environment-setup）
|
||||
|
||||
输出系统级总览：
|
||||
|
||||
```json
|
||||
{
|
||||
"platform": "darwin",
|
||||
"arch": "arm64",
|
||||
"desirecore_api": "https://127.0.0.1:38291",
|
||||
"desirecore_port_file": true,
|
||||
"tools": {
|
||||
"python3": { "available": true, "path": "/opt/homebrew/bin/python3", "version": "3.12.4" },
|
||||
"pip3": { "available": true, "path": "/opt/homebrew/bin/pip3", "version": "24.0" },
|
||||
"node": { "available": true, "path": "/opt/homebrew/bin/node", "version": "22.4.1" },
|
||||
"npm": { "available": true, "path": "/opt/homebrew/bin/npm", "version": "10.8.1" },
|
||||
"docker": { "available": false },
|
||||
"podman": { "available": false },
|
||||
"git": { "available": true, "path": "/usr/bin/git", "version": "2.43.0" }
|
||||
},
|
||||
"wsl": null
|
||||
}
|
||||
```
|
||||
|
||||
Windows 上 `wsl` 字段值类似 `{ "installed": true, "version": "2", "defaultDistro": "Ubuntu" }`。
|
||||
|
||||
## probe-python.sh（python-runtime 专用）
|
||||
|
||||
```json
|
||||
{
|
||||
"platform": "darwin",
|
||||
"arch": "arm64",
|
||||
"desirecore_api": "https://127.0.0.1:38291",
|
||||
"system_python": { "path": "/opt/homebrew/bin/python3", "version": "3.12.4" },
|
||||
"system_pip": { "path": "/opt/homebrew/bin/pip3", "version": "24.0" },
|
||||
"hatch_path": "/Users/wangyi/.desirecore/runtime/hatch/hatch",
|
||||
"hatch_version": "1.16.5",
|
||||
"hatch_versions": ["3.11", "3.12"],
|
||||
"active_venv": "/Users/wangyi/proj/.venv",
|
||||
"pep668": false,
|
||||
"pyenv_path": "",
|
||||
"conda_path": ""
|
||||
}
|
||||
```
|
||||
|
||||
字段语义：
|
||||
- `hatch_path` 空字符串表示二进制不存在
|
||||
- `hatch_versions` 是 `~/.desirecore/runtime/hatch/local/` 下的目录列表（即已通过 Hatch 安装的 Python 版本）
|
||||
- `active_venv` 取自 `$VIRTUAL_ENV` 环境变量
|
||||
- `pep668` 检测 `/usr/lib/python*/EXTERNALLY-MANAGED` 是否存在（Debian 12+/Ubuntu 23.04+ 启用）
|
||||
|
||||
## probe-node.sh（nodejs-runtime 专用）
|
||||
|
||||
```json
|
||||
{
|
||||
"platform": "darwin",
|
||||
"arch": "arm64",
|
||||
"desirecore_api": "https://127.0.0.1:38291",
|
||||
"system_node": { "path": "/opt/homebrew/bin/node", "version": "22.4.1" },
|
||||
"system_npm": { "path": "/opt/homebrew/bin/npm", "version": "10.8.1" },
|
||||
"volta_path": "/Users/wangyi/.desirecore/runtime/volta/volta",
|
||||
"volta_version": "2.0.2",
|
||||
"volta_tools": {
|
||||
"node": ["22.4.1"],
|
||||
"pnpm": ["9.5.0"],
|
||||
"yarn": [],
|
||||
"npm": []
|
||||
},
|
||||
"package_json_volta": null,
|
||||
"nvm_path": "",
|
||||
"fnm_path": "",
|
||||
"registry": "https://registry.npmmirror.com/",
|
||||
"proxy": ""
|
||||
}
|
||||
```
|
||||
|
||||
字段语义：
|
||||
- `volta_tools` 来自 `<volta> list --format=plain`，按工具分类
|
||||
- `package_json_volta` 若当前目录存在 `package.json` 且其中有 `"volta"` 字段，填入对象；否则 `null`
|
||||
- `registry` / `proxy` 来自 `npm config get registry` / `npm config get https-proxy`
|
||||
|
||||
## 设计约定
|
||||
|
||||
1. **JSON 必合法**：缺字段也保留键并赋空字符串/`null`，避免 Claude 解析失败。
|
||||
2. **不阻塞**：每个外部命令都加 `2>/dev/null`，失败用空值，不让脚本中途退出。
|
||||
3. **超时控制**：HTTP 探测 0.5s 超时；CLI 调用最长 5s。
|
||||
4. **跨平台**：`probe.sh` / `probe-python.sh` / `probe-node.sh` 共用 POSIX 子集；Windows 同等功能由 `probe.ps1` 提供（仅父级提供，python/nodejs 子 skill 可由 PowerShell 直接 invoke 父级或自行实现）。
|
||||
5. **路径展开**：所有 `~` 在 JSON 中展开为绝对路径，避免下游解析歧义。
|
||||
|
||||
## 调用约定
|
||||
|
||||
```bash
|
||||
SNAPSHOT=$(bash skills/python-runtime/scripts/probe-python.sh)
|
||||
echo "$SNAPSHOT" | jq .
|
||||
|
||||
# 关键字段判定
|
||||
HATCH=$(echo "$SNAPSHOT" | jq -r .hatch_path)
|
||||
[ -n "$HATCH" ] && [ "$HATCH" != "null" ] && echo "Hatch 可用"
|
||||
```
|
||||
|
||||
PowerShell 等价：
|
||||
|
||||
```powershell
|
||||
$snapshot = & "$PWD\skills\dev-environment-setup\scripts\probe.ps1" | ConvertFrom-Json
|
||||
if ($snapshot.tools.node.available) { ... }
|
||||
```
|
||||
224
skills/dev-environment-setup/references/system-tools.md
Normal file
224
skills/dev-environment-setup/references/system-tools.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# 系统工具安装
|
||||
|
||||
办公技能、PDF/OCR、文档转换会用到的系统级二进制工具。
|
||||
|
||||
## LibreOffice（文档转换 / 公式重算）
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install --cask libreoffice
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install libreoffice
|
||||
|
||||
# Fedora / RHEL
|
||||
sudo dnf install libreoffice
|
||||
|
||||
# Arch
|
||||
sudo pacman -S libreoffice-fresh
|
||||
|
||||
# Windows
|
||||
winget install TheDocumentFoundation.LibreOffice
|
||||
```
|
||||
|
||||
无头转换（CLI）：
|
||||
```bash
|
||||
soffice --headless --convert-to pdf input.docx
|
||||
soffice --headless --calc --convert-to xlsx input.csv
|
||||
```
|
||||
|
||||
## Poppler（PDF 工具集）
|
||||
|
||||
提供 `pdftotext` / `pdftoppm` / `pdfimages` / `pdftohtml` 等。
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install poppler
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install poppler-utils
|
||||
|
||||
# Fedora / RHEL
|
||||
sudo dnf install poppler-utils
|
||||
|
||||
# Arch
|
||||
sudo pacman -S poppler
|
||||
|
||||
# Windows（通过 conda 或手动）
|
||||
conda install -c conda-forge poppler
|
||||
# 或下载 https://github.com/oschwartz10612/poppler-windows/releases，将 bin/ 加入 PATH
|
||||
```
|
||||
|
||||
常用：
|
||||
```bash
|
||||
pdftotext input.pdf output.txt
|
||||
pdftoppm -png input.pdf prefix # 每页一张 PNG
|
||||
pdfimages -png input.pdf prefix # 提取嵌入图片
|
||||
```
|
||||
|
||||
## qpdf（PDF 操作）
|
||||
|
||||
合并 / 拆分 / 解密 / 加密。
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install qpdf
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install qpdf
|
||||
|
||||
# Fedora / RHEL
|
||||
sudo dnf install qpdf
|
||||
|
||||
# Windows
|
||||
winget install QPDF.QPDF
|
||||
```
|
||||
|
||||
常用：
|
||||
```bash
|
||||
qpdf --decrypt --password=secret input.pdf output.pdf
|
||||
qpdf --split-pages input.pdf output-%d.pdf
|
||||
qpdf --empty --pages a.pdf b.pdf -- merged.pdf
|
||||
```
|
||||
|
||||
## Pandoc（文档格式互转）
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install pandoc
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install pandoc
|
||||
|
||||
# Fedora / RHEL
|
||||
sudo dnf install pandoc
|
||||
|
||||
# Arch
|
||||
sudo pacman -S pandoc
|
||||
|
||||
# Windows
|
||||
winget install JohnMacFarlane.Pandoc
|
||||
```
|
||||
|
||||
常用：
|
||||
```bash
|
||||
pandoc input.docx -o output.md
|
||||
pandoc input.md -o output.pdf --pdf-engine=xelatex
|
||||
pandoc input.html -o output.docx
|
||||
```
|
||||
|
||||
## Tesseract（OCR 引擎）
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install tesseract
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install tesseract-ocr
|
||||
|
||||
# Fedora / RHEL
|
||||
sudo dnf install tesseract
|
||||
|
||||
# Arch
|
||||
sudo pacman -S tesseract
|
||||
|
||||
# Windows
|
||||
winget install UB-Mannheim.TesseractOCR
|
||||
```
|
||||
|
||||
### 中文语言包
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install tesseract-lang
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install tesseract-ocr-chi-sim tesseract-ocr-chi-tra
|
||||
|
||||
# Fedora
|
||||
sudo dnf install tesseract-langpack-chi_sim tesseract-langpack-chi_tra
|
||||
```
|
||||
|
||||
使用：
|
||||
```bash
|
||||
tesseract image.png output -l chi_sim # 简体
|
||||
tesseract image.png output -l chi_sim+eng # 中英混合
|
||||
```
|
||||
|
||||
## ImageMagick（图像处理，可选）
|
||||
|
||||
```bash
|
||||
brew install imagemagick # macOS
|
||||
sudo apt install imagemagick # Ubuntu / Debian
|
||||
sudo dnf install ImageMagick # Fedora
|
||||
winget install ImageMagick.ImageMagick # Windows
|
||||
```
|
||||
|
||||
## Ghostscript（PDF / PostScript 渲染）
|
||||
|
||||
```bash
|
||||
brew install ghostscript # macOS
|
||||
sudo apt install ghostscript # Ubuntu / Debian
|
||||
sudo dnf install ghostscript # Fedora
|
||||
winget install ArtifexSoftware.GhostScript # Windows
|
||||
```
|
||||
|
||||
## Git（版本控制，必备）
|
||||
|
||||
```bash
|
||||
brew install git # macOS
|
||||
sudo apt install git # Ubuntu / Debian
|
||||
sudo dnf install git # Fedora
|
||||
sudo pacman -S git # Arch
|
||||
winget install Git.Git # Windows
|
||||
```
|
||||
|
||||
macOS 上 `xcode-select --install` 也会带 git。
|
||||
|
||||
## 跨平台一键检查脚本
|
||||
|
||||
```bash
|
||||
for cmd in soffice pandoc pdftoppm pdftotext pdfimages qpdf tesseract magick gs git; do
|
||||
command -v "$cmd" >/dev/null 2>&1 \
|
||||
&& echo " OK: $cmd ($(command -v "$cmd"))" \
|
||||
|| echo " MISSING: $cmd"
|
||||
done
|
||||
```
|
||||
|
||||
## 故障排查
|
||||
|
||||
### macOS: "soffice: command not found"
|
||||
|
||||
`/Applications/LibreOffice.app/Contents/MacOS/soffice` 是真实路径。建立软链：
|
||||
```bash
|
||||
ln -s /Applications/LibreOffice.app/Contents/MacOS/soffice /usr/local/bin/soffice
|
||||
```
|
||||
|
||||
### Tesseract 找不到中文语言包
|
||||
|
||||
```bash
|
||||
tesseract --list-langs # 检查已安装语言
|
||||
# 找到语言数据目录
|
||||
tesseract --print-parameters | grep tessdata
|
||||
# macOS Apple Silicon: /opt/homebrew/share/tessdata
|
||||
# 把缺失的 chi_sim.traineddata 放进去
|
||||
```
|
||||
|
||||
下载链接：https://github.com/tesseract-ocr/tessdata_fast
|
||||
|
||||
### Windows 工具未在 PATH
|
||||
|
||||
winget 安装后通常自动加入 PATH，重启终端即生效。手动安装的（如 poppler-windows）需要把 `<安装目录>\bin` 加入系统 PATH：
|
||||
|
||||
```powershell
|
||||
[Environment]::SetEnvironmentVariable(
|
||||
"Path",
|
||||
$env:Path + ";C:\poppler\bin",
|
||||
[EnvironmentVariableTarget]::User
|
||||
)
|
||||
```
|
||||
|
||||
重启终端验证：
|
||||
```powershell
|
||||
pdftotext --version
|
||||
```
|
||||
138
skills/dev-environment-setup/references/wsl.md
Normal file
138
skills/dev-environment-setup/references/wsl.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# WSL2 安装与配置（Windows）
|
||||
|
||||
WSL2（Windows Subsystem for Linux 2）让 Windows 用户原生运行 Linux 环境，是运行 Python 脚本、Docker、各种开发工具的最佳方式。
|
||||
|
||||
## 检测
|
||||
|
||||
```powershell
|
||||
wsl --status # 已安装时显示版本与默认发行版
|
||||
wsl --list --verbose # 已安装的发行版及版本
|
||||
```
|
||||
|
||||
## 系统要求
|
||||
|
||||
- Windows 11（21H2+）或 Windows 10（版本 2004，Build 19041+）
|
||||
- BIOS 启用 CPU 虚拟化（Intel VT-x / AMD-V）
|
||||
|
||||
## 安装
|
||||
|
||||
```powershell
|
||||
# 以管理员身份打开 PowerShell
|
||||
|
||||
# 一键安装（含 WSL2 内核 + 默认 Ubuntu）
|
||||
wsl --install
|
||||
|
||||
# 重启计算机后 Ubuntu 窗口自动打开，提示设置用户名密码
|
||||
```
|
||||
|
||||
## 安装指定发行版
|
||||
|
||||
```powershell
|
||||
wsl --list --online # 可选发行版
|
||||
wsl --install -d Ubuntu-24.04
|
||||
wsl --install -d Debian
|
||||
wsl --set-default Ubuntu-24.04
|
||||
```
|
||||
|
||||
## 确保使用 WSL2
|
||||
|
||||
```powershell
|
||||
wsl --list --verbose
|
||||
# VERSION 列应为 2
|
||||
|
||||
# 升级到 WSL2
|
||||
wsl --set-version Ubuntu 2
|
||||
|
||||
# 默认 WSL2
|
||||
wsl --set-default-version 2
|
||||
```
|
||||
|
||||
## 进入 WSL2 后配置开发环境
|
||||
|
||||
按 Linux 方式配置即可：
|
||||
|
||||
```bash
|
||||
# 进入
|
||||
wsl
|
||||
|
||||
# 系统更新
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
|
||||
# Python（推荐用 python-runtime skill 走完整决策树）
|
||||
sudo apt install python3 python3-pip python3-venv
|
||||
|
||||
# Node.js（推荐用 nodejs-runtime skill）
|
||||
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
|
||||
sudo apt install nodejs
|
||||
|
||||
# Docker（推荐 Docker Desktop 的 WSL2 后端，而非在 WSL2 内独立装）
|
||||
```
|
||||
|
||||
## 文件互访
|
||||
|
||||
```bash
|
||||
# WSL2 → Windows
|
||||
ls /mnt/c/Users/<用户名>/Desktop/
|
||||
|
||||
# Windows → WSL2（资源管理器地址栏）
|
||||
\\wsl$\Ubuntu\home\<用户名>\
|
||||
|
||||
# Windows Terminal 打开 WSL2
|
||||
wsl ~
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### "WslRegisterDistribution failed with error: 0x80370102"
|
||||
|
||||
CPU 虚拟化未启用。重启进 BIOS，启用 Intel VT-x / AMD-V。
|
||||
|
||||
### 网络无法访问互联网
|
||||
|
||||
```bash
|
||||
# 在 WSL2 内
|
||||
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
|
||||
|
||||
# 或 Windows 端关闭 Hyper-V 网卡的 DNS 自动管理
|
||||
```
|
||||
|
||||
如果是公司 VPN 干扰，在 Windows 端 `wsl --shutdown` 后重启 VPN。
|
||||
|
||||
### 磁盘空间不足
|
||||
|
||||
```powershell
|
||||
# 压缩 WSL2 虚拟磁盘
|
||||
wsl --shutdown
|
||||
# 然后用 diskpart 压缩 ext4.vhdx（高级操作，备份后再做）
|
||||
```
|
||||
|
||||
或在 `~/.wslconfig` 限制大小：
|
||||
|
||||
```ini
|
||||
[wsl2]
|
||||
memory=4GB
|
||||
processors=2
|
||||
swap=2GB
|
||||
```
|
||||
|
||||
### Windows 与 WSL2 时间不同步
|
||||
|
||||
```bash
|
||||
sudo hwclock -s
|
||||
```
|
||||
|
||||
或：
|
||||
```bash
|
||||
sudo apt install ntpdate
|
||||
sudo ntpdate -s time.windows.com
|
||||
```
|
||||
|
||||
### DesireCore 在 WSL2 中使用
|
||||
|
||||
DesireCore 是 Windows 桌面应用，运行在 Windows 端而非 WSL2 内。但 DesireCore 的环境检查（设置 → 环境检查）可以自动检测 Windows 版本、CPU 虚拟化、WSL2 状态，并提供一键修复入口。
|
||||
|
||||
## 性能建议
|
||||
|
||||
- 项目文件放在 WSL2 的 Linux 文件系统（`/home/<user>/`），不要放 `/mnt/c/`——后者跨文件系统 IO 极慢
|
||||
- 编辑器：VS Code + Remote-WSL 扩展，自动跨边界
|
||||
- Docker：使用 Docker Desktop 的 WSL2 后端，避免 WSL2 内独立 Docker 守护进程
|
||||
66
skills/dev-environment-setup/scripts/probe.ps1
Normal file
66
skills/dev-environment-setup/scripts/probe.ps1
Normal file
@@ -0,0 +1,66 @@
|
||||
# dev-environment-setup probe (Windows)
|
||||
# 协议：见 ..\references\probe-snapshot.md
|
||||
|
||||
$ErrorActionPreference = 'SilentlyContinue'
|
||||
|
||||
function Test-Tool {
|
||||
param([string]$Name, [string]$VersionFlag = '--version')
|
||||
$cmd = Get-Command $Name -ErrorAction SilentlyContinue
|
||||
if (-not $cmd) {
|
||||
return @{ available = $false }
|
||||
}
|
||||
$output = & $Name $VersionFlag 2>&1 | Select-Object -First 1
|
||||
$version = ''
|
||||
if ($output -match '(\d+\.\d+(?:\.\d+)?)') { $version = $Matches[1] }
|
||||
return @{ available = $true; path = $cmd.Source; version = $version }
|
||||
}
|
||||
|
||||
# DesireCore API 探测
|
||||
$portFile = Join-Path $env:USERPROFILE '.desirecore\agent-service.port'
|
||||
$desirecoreApi = ''
|
||||
$portFileExists = Test-Path $portFile
|
||||
if ($portFileExists) {
|
||||
$port = (Get-Content $portFile -Raw).Trim()
|
||||
if ($port) {
|
||||
try {
|
||||
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }
|
||||
$resp = Invoke-WebRequest -Uri "https://127.0.0.1:$port/api/runtime/environment" `
|
||||
-TimeoutSec 1 -UseBasicParsing -ErrorAction Stop
|
||||
if ($resp.StatusCode -eq 200) { $desirecoreApi = "https://127.0.0.1:$port" }
|
||||
} catch { }
|
||||
}
|
||||
}
|
||||
|
||||
# WSL 检测
|
||||
$wsl = $null
|
||||
$wslOut = wsl --status 2>&1
|
||||
if ($LASTEXITCODE -eq 0) {
|
||||
$version = ''
|
||||
$defaultDistro = ''
|
||||
if ($wslOut -match '(\d+)') { $version = $Matches[1] }
|
||||
$wsl = @{ installed = $true; version = $version; defaultDistro = $defaultDistro }
|
||||
} else {
|
||||
$wsl = @{ installed = $false }
|
||||
}
|
||||
|
||||
$arch = if ([Environment]::Is64BitOperatingSystem) { 'x64' } else { 'x86' }
|
||||
if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { $arch = 'arm64' }
|
||||
|
||||
$result = @{
|
||||
platform = 'win32'
|
||||
arch = $arch
|
||||
desirecore_api = $desirecoreApi
|
||||
desirecore_port_file = $portFileExists
|
||||
tools = @{
|
||||
python3 = (Test-Tool python)
|
||||
pip3 = (Test-Tool pip)
|
||||
node = (Test-Tool node)
|
||||
npm = (Test-Tool npm)
|
||||
docker = (Test-Tool docker)
|
||||
podman = (Test-Tool podman)
|
||||
git = (Test-Tool git)
|
||||
}
|
||||
wsl = $wsl
|
||||
}
|
||||
|
||||
$result | ConvertTo-Json -Depth 5 -Compress:$false
|
||||
77
skills/dev-environment-setup/scripts/probe.sh
Executable file
77
skills/dev-environment-setup/scripts/probe.sh
Executable file
@@ -0,0 +1,77 @@
|
||||
#!/usr/bin/env bash
|
||||
# dev-environment-setup probe: 输出系统级环境快照（JSON）
|
||||
# 协议：见 ../references/probe-snapshot.md
|
||||
|
||||
set +e
|
||||
|
||||
# ── 工具检测 ─────────────────────────────
|
||||
detect_tool() {
|
||||
local name="$1"
|
||||
local version_flag="${2:---version}"
|
||||
local path
|
||||
path=$(command -v "$name" 2>/dev/null)
|
||||
if [ -z "$path" ]; then
|
||||
printf '{"available":false}'
|
||||
return
|
||||
fi
|
||||
local version
|
||||
version=$("$name" $version_flag 2>&1 | head -n1 | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -n1)
|
||||
printf '{"available":true,"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 探测 ─────────────────
|
||||
PORT_FILE="$HOME/.desirecore/agent-service.port"
|
||||
DESIRECORE_API=""
|
||||
PORT_FILE_EXISTS="false"
|
||||
if [ -r "$PORT_FILE" ]; then
|
||||
PORT_FILE_EXISTS="true"
|
||||
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
|
||||
|
||||
# ── 工具检测结果 ────────────────────────
|
||||
PY=$(detect_tool python3)
|
||||
[ "$(echo "$PY" | grep -o false)" = "false" ] && PY=$(detect_tool python)
|
||||
PIP=$(detect_tool pip3)
|
||||
[ "$(echo "$PIP" | grep -o false)" = "false" ] && PIP=$(detect_tool pip)
|
||||
NODE=$(detect_tool node)
|
||||
NPM=$(detect_tool npm)
|
||||
DOCKER=$(detect_tool docker)
|
||||
PODMAN=$(detect_tool podman)
|
||||
GIT=$(detect_tool git)
|
||||
|
||||
# ── 输出 JSON ───────────────────────────
|
||||
cat <<EOF
|
||||
{
|
||||
"platform": "${PLATFORM}",
|
||||
"arch": "${ARCH}",
|
||||
"desirecore_api": "${DESIRECORE_API}",
|
||||
"desirecore_port_file": ${PORT_FILE_EXISTS},
|
||||
"tools": {
|
||||
"python3": ${PY},
|
||||
"pip3": ${PIP},
|
||||
"node": ${NODE},
|
||||
"npm": ${NPM},
|
||||
"docker": ${DOCKER},
|
||||
"podman": ${PODMAN},
|
||||
"git": ${GIT}
|
||||
},
|
||||
"wsl": null
|
||||
}
|
||||
EOF
|
||||
@@ -85,7 +85,8 @@ python3 --version 2>/dev/null || python --version 2>/dev/null
|
||||
- **Linux (Debian/Ubuntu)**: `sudo apt install python3 python3-pip`
|
||||
- **Linux (Fedora/RHEL)**: `sudo dnf install python3 python3-pip`
|
||||
|
||||
如需更详细的环境配置帮助，加载 `environment-setup` 技能。
|
||||
如需更详细的环境配置帮助：Python 相关问题加载 `python-runtime` 技能；
|
||||
其他（容器 / WSL / 系统工具）加载 `dev-environment-setup` 技能。
|
||||
|
||||
### Python 包依赖
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
193
skills/nodejs-runtime/SKILL.md
Normal file
193
skills/nodejs-runtime/SKILL.md
Normal file
@@ -0,0 +1,193 @@
|
||||
---
|
||||
name: Node.js 运行时管理
|
||||
description: >-
|
||||
Use this skill when the user needs to install, upgrade, or troubleshoot
|
||||
Node.js, npm, pnpm, yarn, and JavaScript/TypeScript runtime environments.
|
||||
Covers four-tier fallback strategy: (1) DesireCore HTTP API for in-app
|
||||
installation, (2) DesireCore built-in Volta CLI for Node.js + package
|
||||
manager version management, (3) system package managers
|
||||
(brew/apt/dnf/winget/NodeSource), (4) community nvm/fnm as last resort.
|
||||
Also covers global package management, npm registry/proxy configuration,
|
||||
EACCES permission errors, and PATH troubleshooting. Triggers include:
|
||||
"install node", "node not found", "npm not found", "npm EACCES", "pnpm",
|
||||
"yarn", "volta", "nvm", "fnm", "nodejs version", "package-lock", or any
|
||||
Node.js / npm runtime error. 使用场景：用户需要 安装 Node.js、安装 npm、
|
||||
pnpm、yarn、配置全局包、解决 EACCES、PATH 问题、镜像/代理配置。
|
||||
version: 1.0.1
|
||||
type: procedural
|
||||
risk_level: low
|
||||
status: enabled
|
||||
disable-model-invocation: true
|
||||
tags:
|
||||
- nodejs
|
||||
- npm
|
||||
- pnpm
|
||||
- yarn
|
||||
- volta
|
||||
- nvm
|
||||
- fnm
|
||||
- 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="node-a" x1="3" y1="3" x2="21"
|
||||
y2="21" gradientUnits="userSpaceOnUse"><stop
|
||||
stop-color="#68A063"/><stop offset="1"
|
||||
stop-color="#3C873A"/></linearGradient></defs><rect x="3" y="3" width="18"
|
||||
height="18" rx="3" fill="url(#node-a)" fill-opacity="0.12"
|
||||
stroke="url(#node-a)" stroke-width="1.5"/><path d="M12 6.5L17 9.25v5.5L12
|
||||
17.5L7 14.75v-5.5z" stroke="url(#node-a)" stroke-width="1.4"
|
||||
stroke-linejoin="round" fill="none"/><path d="M12 11.5v3M10 12.5l2 1l2-1"
|
||||
stroke="url(#node-a)" stroke-width="1.4" stroke-linecap="round"
|
||||
fill="none"/></svg>
|
||||
short_desc: Node.js / npm / pnpm / yarn 安装与多版本（DesireCore Volta 优先）
|
||||
category: development
|
||||
maintainer:
|
||||
name: DesireCore Official
|
||||
verified: true
|
||||
channel: latest
|
||||
---
|
||||
|
||||
# nodejs-runtime 技能
|
||||
|
||||
## L0：一句话摘要
|
||||
|
||||
**何时使用**：用户需要 安装 Node.js / 升级 Node / 切换 Node 多版本 / 安装或配置
|
||||
npm / pnpm / yarn / 排查 `node: command not found`、`npm: command not found`、
|
||||
EACCES 全局安装权限错误、node-gyp 编译失败、registry 镜像 / proxy 问题 等
|
||||
Node.js 运行时问题，或其他 skill（pptx 用 pptxgenjs 等）报告 "Node.js 不可用" 时。
|
||||
|
||||
**怎么做**：优先使用 DesireCore 内置 Volta，按四级降级（HTTP API → Volta CLI →
|
||||
系统包管理器 brew/apt/NodeSource/winget → 社区方案 nvm/fnm）执行。
|
||||
|
||||
## L1：概述与使用场景
|
||||
|
||||
### 能力描述
|
||||
|
||||
procedural skill。每次执行 Node.js 环境操作前，先运行 `scripts/probe-node.sh` 取 JSON 快照，再按 `../dev-environment-setup/references/decision-tree.md` 四级降级选择路径。
|
||||
|
||||
### 使用场景
|
||||
|
||||
- "node not found" / "npm not found"
|
||||
- 用户要求安装/升级 Node.js
|
||||
- 多版本切换（基于 `package.json#volta` 或 `.nvmrc`）
|
||||
- 安装/管理 pnpm / yarn / npm
|
||||
- "EACCES: permission denied"（npm 全局安装权限错误）
|
||||
- 配置 registry / proxy
|
||||
- 其他 skill（pptx 等）报告 Node.js 不可用
|
||||
|
||||
### 核心价值
|
||||
|
||||
- **DesireCore 优先**：Volta + HTTP API 作为 L1/L2，避免污染系统 Node
|
||||
- **JSON 决策**：probe 脚本输出结构化数据，Claude 可直接解析
|
||||
- **package.json#volta 兼容**：Volta 自动按项目切换版本
|
||||
|
||||
## L2：详细规范
|
||||
|
||||
### 第一步：环境探测（必须）
|
||||
|
||||
```bash
|
||||
bash skills/nodejs-runtime/scripts/probe-node.sh > /tmp/node-probe.json
|
||||
cat /tmp/node-probe.json | jq .
|
||||
```
|
||||
|
||||
字段含义见 `../dev-environment-setup/references/probe-snapshot.md`。
|
||||
|
||||
### 第二步：选择执行路径
|
||||
|
||||
| 条件 | 路径 |
|
||||
|------|------|
|
||||
| `desirecore_api` 非空 | **L1** HTTP API |
|
||||
| `desirecore_api` 空，`volta_path` 非空 | **L2** Volta CLI |
|
||||
| 上述都不满足 | **L3** 系统包管理器（brew / apt / NodeSource / winget） |
|
||||
| L1–L3 全部失败或用户明示 | **L4** 社区方案（nvm / fnm） |
|
||||
|
||||
### 第三步：执行（仅展示主路径，详见各 references）
|
||||
|
||||
#### L1：HTTP API（→ `references/volta-desirecore.md`）
|
||||
|
||||
```bash
|
||||
PORT=$(cat ~/.desirecore/agent-service.port)
|
||||
BASE="https://127.0.0.1:${PORT}/api/runtime"
|
||||
|
||||
# 列出可装版本
|
||||
curl -sk "${BASE}/node/available"
|
||||
|
||||
# 触发安装（异步）
|
||||
curl -sk -X POST "${BASE}/node/install" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"version":"22"}'
|
||||
|
||||
# 安装包管理器
|
||||
curl -sk -X POST "${BASE}/pkg/pnpm/install" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"version":"latest"}'
|
||||
|
||||
# 完成后刷新缓存
|
||||
curl -sk -X POST "${BASE}/environment/refresh"
|
||||
```
|
||||
|
||||
#### L2：Volta CLI 绝对路径（→ `references/volta-desirecore.md`）
|
||||
|
||||
```bash
|
||||
VOLTA=~/.desirecore/runtime/volta/volta
|
||||
export VOLTA_HOME=~/.desirecore/runtime/volta
|
||||
export VOLTA_FEATURE_PNPM=1
|
||||
|
||||
"$VOLTA" install node@22
|
||||
"$VOLTA" install pnpm@latest
|
||||
"$VOLTA" install yarn@latest
|
||||
"$VOLTA" list all
|
||||
|
||||
# 项目级固定（修改 package.json#volta）
|
||||
"$VOLTA" pin node@22 pnpm@9
|
||||
```
|
||||
|
||||
Windows：`%USERPROFILE%\.desirecore\runtime\volta\volta.exe`。
|
||||
|
||||
#### L3：系统包管理器
|
||||
|
||||
| 平台 | 命令 |
|
||||
|------|------|
|
||||
| macOS | `brew install node` |
|
||||
| Debian/Ubuntu | NodeSource：`curl -fsSL https://deb.nodesource.com/setup_22.x \| sudo -E bash - && sudo apt install nodejs` |
|
||||
| Fedora/RHEL | `curl -fsSL https://rpm.nodesource.com/setup_22.x \| sudo bash - && sudo dnf install nodejs` |
|
||||
| Arch | `sudo pacman -S nodejs npm` |
|
||||
| Windows | `winget install OpenJS.NodeJS.LTS` |
|
||||
|
||||
#### L4：nvm / fnm（→ `references/nvm-fallback.md`）
|
||||
|
||||
仅在用户明示或上述失败时启用。
|
||||
|
||||
### 第四步：包管理器策略
|
||||
|
||||
详见 `references/package-managers.md`：
|
||||
- pnpm（推荐，磁盘高效、严格依赖）
|
||||
- yarn（Berry / Classic）
|
||||
- npm（默认，Node.js 自带）
|
||||
- 项目级 `package.json#volta` 自动切换
|
||||
|
||||
### 第五步：故障排查
|
||||
|
||||
详见 `references/troubleshooting.md`：
|
||||
- npm EACCES 权限错误（**不要用 sudo npm**）
|
||||
- registry / proxy 配置
|
||||
- node-gyp 编译失败
|
||||
- "node: command not found" 在 nvm 已装时
|
||||
|
||||
## 重要约束
|
||||
|
||||
1. **绝不 `sudo npm install -g`**：用户级 prefix 或 Volta/nvm。
|
||||
2. **修改环境后必须刷新**：L1 调 `POST /api/runtime/environment/refresh`；其它路径重跑 probe。
|
||||
3. **跨 skill 协作**：`pptx` 等需要 Node.js 时，按本 skill 主路径安装；npm 包速查见 `../dev-environment-setup/references/office-deps.md`。
|
||||
4. **package.json#volta 必须尊重**：检测到该字段时优先 Volta，不要切到 nvm。
|
||||
|
||||
## 引用关系
|
||||
|
||||
- 决策树：`../dev-environment-setup/references/decision-tree.md`
|
||||
- DesireCore 底座：`../dev-environment-setup/references/desirecore-runtime.md`
|
||||
- 探测协议：`../dev-environment-setup/references/probe-snapshot.md`
|
||||
- 办公依赖（npm 包）：`../dev-environment-setup/references/office-deps.md`
|
||||
140
skills/nodejs-runtime/references/nvm-fallback.md
Normal file
140
skills/nodejs-runtime/references/nvm-fallback.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# nvm / fnm（L4 社区方案）
|
||||
|
||||
仅在以下情况启用：
|
||||
1. 用户明确要求 nvm / fnm
|
||||
2. 项目根目录已有 `.nvmrc` 文件且不存在 `package.json#volta`
|
||||
3. L1 (HTTP API) / L2 (Volta CLI) / L3 (系统包管理器) 全部失败
|
||||
|
||||
如条件不满足，**不要**主动建议 nvm——优先 DesireCore Volta。
|
||||
|
||||
## nvm（POSIX shell）
|
||||
|
||||
### 安装
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
|
||||
|
||||
source ~/.zshrc # 或 ~/.bashrc
|
||||
|
||||
# 验证
|
||||
command -v nvm # 应返回 "nvm"（函数）
|
||||
```
|
||||
|
||||
`install.sh` 会自动追加加载片段到 `~/.zshrc` / `~/.bashrc`：
|
||||
```bash
|
||||
export NVM_DIR="$HOME/.nvm"
|
||||
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
|
||||
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
|
||||
```
|
||||
|
||||
### 使用
|
||||
|
||||
```bash
|
||||
# 列出可装 LTS
|
||||
nvm ls-remote --lts
|
||||
|
||||
# 安装
|
||||
nvm install 22 # 最新 22.x
|
||||
nvm install --lts # 最新 LTS
|
||||
nvm install 20.10.0 # 精确版本
|
||||
|
||||
# 切换
|
||||
nvm use 22
|
||||
nvm use --lts
|
||||
|
||||
# 默认
|
||||
nvm alias default 22
|
||||
|
||||
# 项目级（.nvmrc）
|
||||
echo "22" > .nvmrc
|
||||
nvm use # 读取 .nvmrc
|
||||
|
||||
# 已装
|
||||
nvm ls
|
||||
|
||||
# 卸载
|
||||
nvm uninstall 18
|
||||
```
|
||||
|
||||
### Windows（nvm-windows，独立项目）
|
||||
|
||||
```
|
||||
https://github.com/coreybutler/nvm-windows/releases
|
||||
```
|
||||
|
||||
下载安装包安装，重启终端。命令略有差异（无 `.nvmrc` 支持，需用 `nvm-windows-bridge` 之类的扩展）。
|
||||
|
||||
## fnm（Rust 实现，比 nvm 快）
|
||||
|
||||
### 安装
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install fnm
|
||||
|
||||
# Linux
|
||||
curl -fsSL https://fnm.vercel.app/install | bash
|
||||
|
||||
# Windows
|
||||
winget install Schniz.fnm
|
||||
```
|
||||
|
||||
### 配置自动切换
|
||||
|
||||
```bash
|
||||
# zsh
|
||||
echo 'eval "$(fnm env --use-on-cd --shell zsh)"' >> ~/.zshrc
|
||||
|
||||
# bash
|
||||
echo 'eval "$(fnm env --use-on-cd --shell bash)"' >> ~/.bashrc
|
||||
|
||||
# fish
|
||||
fnm env --use-on-cd --shell fish | source
|
||||
```
|
||||
|
||||
`--use-on-cd` 让 `cd` 进入有 `.nvmrc` 的目录时自动切换。
|
||||
|
||||
### 使用
|
||||
|
||||
```bash
|
||||
fnm install 22
|
||||
fnm install --lts
|
||||
fnm use 22
|
||||
fnm default 22
|
||||
fnm ls
|
||||
fnm uninstall 18
|
||||
```
|
||||
|
||||
## .nvmrc / .node-version 约定
|
||||
|
||||
| 文件 | 工具支持 |
|
||||
|------|----------|
|
||||
| `.nvmrc` | nvm、fnm（默认） |
|
||||
| `.node-version` | fnm（默认）、nodenv |
|
||||
| `package.json#engines.node` | npm 安装时校验，不切换 |
|
||||
| `package.json#volta` | Volta（自动切换） |
|
||||
|
||||
存在 `package.json#volta` 时**优先尊重**它，不要让用户改用 nvm。
|
||||
|
||||
## 镜像加速
|
||||
|
||||
```bash
|
||||
# nvm
|
||||
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node/
|
||||
|
||||
# fnm
|
||||
fnm install --node-dist-mirror https://npmmirror.com/mirrors/node/ 22
|
||||
# 或全局
|
||||
export FNM_NODE_DIST_MIRROR=https://npmmirror.com/mirrors/node/
|
||||
```
|
||||
|
||||
## 故障排查
|
||||
|
||||
| 现象 | 排查 |
|
||||
|------|------|
|
||||
| `nvm: command not found` | shell 未 source nvm.sh，重启终端或 `source ~/.zshrc` |
|
||||
| `nvm` 在脚本里失效 | nvm 是 shell function 不是命令；脚本里需先 `source ~/.nvm/nvm.sh` |
|
||||
| `node: command not found`（nvm 已装） | 切换了 shell 但 nvm 没在新 shell 加载，添加加载片段 |
|
||||
| nvm 编译 Node 时网络超时 | 设镜像 `NVM_NODEJS_ORG_MIRROR` |
|
||||
| Windows nvm 切换无效 | 以管理员重新运行 nvm 安装包 |
|
||||
160
skills/nodejs-runtime/references/package-managers.md
Normal file
160
skills/nodejs-runtime/references/package-managers.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 包管理器策略（npm / pnpm / yarn）
|
||||
|
||||
## 选型建议
|
||||
|
||||
| 场景 | 推荐 |
|
||||
|------|------|
|
||||
| 默认（Node.js 自带） | npm |
|
||||
| 磁盘高效 / 严格依赖 / monorepo | **pnpm**（推荐） |
|
||||
| 项目已用 yarn | yarn classic / berry |
|
||||
| DesireCore 应用内 | Volta 管理任何之上 |
|
||||
|
||||
## 通过 DesireCore Volta 安装
|
||||
|
||||
```bash
|
||||
VOLTA=~/.desirecore/runtime/volta/volta
|
||||
export VOLTA_FEATURE_PNPM=1
|
||||
|
||||
"$VOLTA" install pnpm@latest
|
||||
"$VOLTA" install yarn@latest
|
||||
"$VOLTA" install npm@10
|
||||
```
|
||||
|
||||
或 HTTP API：
|
||||
|
||||
```bash
|
||||
BASE="https://127.0.0.1:$(cat ~/.desirecore/agent-service.port)/api/runtime"
|
||||
curl -sk -X POST "${BASE}/pkg/pnpm/install" -H "Content-Type: application/json" -d '{"version":"latest"}'
|
||||
```
|
||||
|
||||
## 项目级固定版本
|
||||
|
||||
### package.json#volta（首选）
|
||||
|
||||
```json
|
||||
{
|
||||
"volta": {
|
||||
"node": "22.11.0",
|
||||
"pnpm": "9.5.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
在装了 Volta 的环境中 `cd` 进项目即自动切换。
|
||||
|
||||
### packageManager 字段（Corepack 标准）
|
||||
|
||||
```json
|
||||
{
|
||||
"packageManager": "pnpm@9.5.0"
|
||||
}
|
||||
```
|
||||
|
||||
由 Corepack（Node 16.10+ 自带）解析，被 npm/pnpm/yarn 自身识别。可与 Volta 共存。
|
||||
|
||||
## npm 全局安装
|
||||
|
||||
### 不要用 sudo
|
||||
|
||||
错误：
|
||||
```bash
|
||||
sudo npm install -g pkg # ❌ 文件 owner 变成 root，后续维护麻烦
|
||||
```
|
||||
|
||||
正确：改 npm 全局目录到用户目录。
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.npm-global
|
||||
npm config set prefix '~/.npm-global'
|
||||
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
|
||||
source ~/.zshrc
|
||||
|
||||
npm install -g pptxgenjs docx
|
||||
```
|
||||
|
||||
或用 Volta（自动隔离，无权限问题）：
|
||||
```bash
|
||||
volta install pptxgenjs # ❌ Volta 不直接装库；只能装 CLI 工具
|
||||
# 库依赖应通过项目 package.json 管理
|
||||
```
|
||||
|
||||
## pnpm 配置
|
||||
|
||||
```bash
|
||||
# 全局存储位置（pnpm 单存储多链接的核心）
|
||||
pnpm config get store-dir
|
||||
# 默认 ~/.local/share/pnpm/store/v3
|
||||
|
||||
# 改 registry
|
||||
pnpm config set registry https://registry.npmmirror.com/
|
||||
|
||||
# 全局安装路径（独立于 npm）
|
||||
pnpm config get global-bin-dir
|
||||
```
|
||||
|
||||
## yarn 配置
|
||||
|
||||
```bash
|
||||
# yarn classic
|
||||
yarn config set registry https://registry.npmmirror.com/
|
||||
|
||||
# yarn berry
|
||||
yarn config set npmRegistryServer https://registry.npmmirror.com/
|
||||
```
|
||||
|
||||
## 镜像 / 代理
|
||||
|
||||
### 中国大陆加速
|
||||
|
||||
```bash
|
||||
npm config set registry https://registry.npmmirror.com/
|
||||
pnpm config set registry https://registry.npmmirror.com/
|
||||
yarn config set registry https://registry.npmmirror.com/
|
||||
```
|
||||
|
||||
恢复官方：
|
||||
```bash
|
||||
npm config set registry https://registry.npmjs.org/
|
||||
```
|
||||
|
||||
### 公司代理
|
||||
|
||||
```bash
|
||||
npm config set proxy http://proxy:port
|
||||
npm config set https-proxy http://proxy:port
|
||||
|
||||
# 取消
|
||||
npm config delete proxy
|
||||
npm config delete https-proxy
|
||||
```
|
||||
|
||||
### 私有 registry（Verdaccio / Nexus）
|
||||
|
||||
```bash
|
||||
# 项目级（.npmrc）
|
||||
@scope:registry=https://npm.company.com/
|
||||
//npm.company.com/:_authToken=${NPM_TOKEN}
|
||||
```
|
||||
|
||||
## 卸载与清理
|
||||
|
||||
```bash
|
||||
# 全局列表
|
||||
npm ls -g --depth=0
|
||||
pnpm list -g --depth=0
|
||||
yarn global list
|
||||
|
||||
# 卸载
|
||||
npm uninstall -g pkg
|
||||
pnpm uninstall -g pkg
|
||||
yarn global remove pkg
|
||||
|
||||
# 清缓存
|
||||
npm cache clean --force
|
||||
pnpm store prune
|
||||
yarn cache clean
|
||||
```
|
||||
|
||||
## 环境快照
|
||||
|
||||
probe-node.sh 输出 `volta_tools.{node,pnpm,yarn,npm}` 列出所有 Volta 管理的版本，`registry` / `proxy` 来自 npm 配置。Skill 解析 JSON 即可判断是否需要切换镜像。
|
||||
173
skills/nodejs-runtime/references/troubleshooting.md
Normal file
173
skills/nodejs-runtime/references/troubleshooting.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# Node.js 故障排查
|
||||
|
||||
## "node: command not found" / "npm: command not found"
|
||||
|
||||
```bash
|
||||
# 1. 找一下二进制
|
||||
which node 2>/dev/null
|
||||
ls /usr/bin/node /usr/local/bin/node /opt/homebrew/bin/node 2>/dev/null
|
||||
|
||||
# 2. nvm 已装但未加载？
|
||||
[ -s "$HOME/.nvm/nvm.sh" ] && echo "nvm installed but not loaded"
|
||||
export NVM_DIR="$HOME/.nvm"
|
||||
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
|
||||
node --version
|
||||
|
||||
# 3. Volta 已装但未在 PATH？
|
||||
ls ~/.desirecore/runtime/volta/volta 2>/dev/null && \
|
||||
echo "运行 ~/.desirecore/runtime/volta/volta 直接调用，无需 PATH"
|
||||
```
|
||||
|
||||
**根治**：按主 SKILL.md 决策树重新执行 L1–L3 安装路径。
|
||||
|
||||
## npm EACCES（全局安装权限错误）
|
||||
|
||||
**症状**：`npm install -g <pkg>` 报 `EACCES: permission denied, mkdir '/usr/local/lib/node_modules'`。
|
||||
|
||||
**原因**：npm 默认全局目录是系统目录，无写权限。
|
||||
|
||||
**修复（推荐：改 npm prefix 到用户目录）**
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.npm-global
|
||||
npm config set prefix '~/.npm-global'
|
||||
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc # 或 ~/.bashrc
|
||||
source ~/.zshrc
|
||||
|
||||
# 现在可以正常全局安装
|
||||
npm install -g pkg
|
||||
```
|
||||
|
||||
**禁忌**：`sudo npm install -g` ——会把文件 owner 改成 root，后续 npm 升级/卸载报错。
|
||||
|
||||
## node-gyp 编译失败
|
||||
|
||||
**症状**：安装包含原生扩展的依赖（sqlite3 / sharp / canvas）时报 `node-gyp rebuild failed`。
|
||||
|
||||
| 平台 | 修复 |
|
||||
|------|------|
|
||||
| macOS | `xcode-select --install` |
|
||||
| Ubuntu/Debian | `sudo apt install build-essential python3` |
|
||||
| Fedora/RHEL | `sudo dnf groupinstall "Development Tools" && sudo dnf install python3` |
|
||||
| Windows | `npm install --global windows-build-tools`（管理员）或装 Visual Studio Build Tools |
|
||||
|
||||
某些包提供预编译版本：检查 `package.json` 是否有 `prebuild-install` 钩子，没有再编译。
|
||||
|
||||
## SSL / TLS 错误
|
||||
|
||||
```bash
|
||||
# 临时不验证（仅调试）
|
||||
npm config set strict-ssl false
|
||||
|
||||
# 永久（不推荐）
|
||||
npm config set ca null
|
||||
|
||||
# 公司证书 / Zscaler
|
||||
npm config set cafile /path/to/company-ca.pem
|
||||
```
|
||||
|
||||
## 代理环境
|
||||
|
||||
```bash
|
||||
# 设置
|
||||
npm config set proxy http://proxy:port
|
||||
npm config set https-proxy http://proxy:port
|
||||
|
||||
# 检查
|
||||
npm config get proxy
|
||||
npm config get https-proxy
|
||||
|
||||
# 取消
|
||||
npm config delete proxy
|
||||
npm config delete https-proxy
|
||||
```
|
||||
|
||||
注意：HTTP_PROXY / HTTPS_PROXY 环境变量也会被 npm 识别。
|
||||
|
||||
## "Cannot find module" 错误
|
||||
|
||||
```bash
|
||||
# 1. 是否在正确目录
|
||||
pwd
|
||||
ls package.json
|
||||
|
||||
# 2. node_modules 是否安装
|
||||
ls node_modules/<missing-module> 2>/dev/null
|
||||
|
||||
# 3. 是否在虚拟切换中（nvm/Volta 没切对）
|
||||
node -e "console.log(process.execPath)"
|
||||
|
||||
# 4. 重装
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
```
|
||||
|
||||
## 版本冲突
|
||||
|
||||
`package.json#engines` 限制 Node 版本：
|
||||
|
||||
```json
|
||||
{
|
||||
"engines": { "node": ">=20" }
|
||||
}
|
||||
```
|
||||
|
||||
Volta 会强制使用 `volta` 字段；nvm/fnm 用 `.nvmrc`。检查冲突：
|
||||
|
||||
```bash
|
||||
node --version
|
||||
cat package.json | grep -A2 '"volta"\|"engines"'
|
||||
cat .nvmrc 2>/dev/null
|
||||
```
|
||||
|
||||
## Windows PowerShell 执行策略
|
||||
|
||||
```powershell
|
||||
Get-ExecutionPolicy
|
||||
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||||
```
|
||||
|
||||
之后才能运行 npm / pnpm / yarn 脚本。
|
||||
|
||||
## 镜像与 CDN 慢
|
||||
|
||||
```bash
|
||||
# 切换到淘宝镜像
|
||||
npm config set registry https://registry.npmmirror.com/
|
||||
pnpm config set registry https://registry.npmmirror.com/
|
||||
|
||||
# 部分二进制（sharp / puppeteer）有独立 CDN
|
||||
export SHARP_DIST_BASE_URL=https://npmmirror.com/mirrors/sharp/
|
||||
export PUPPETEER_DOWNLOAD_HOST=https://npmmirror.com/mirrors/
|
||||
```
|
||||
|
||||
## EnvironmentSnapshot 信号速查
|
||||
|
||||
probe-node.sh 输出后，按字段快速判断：
|
||||
|
||||
| 字段 | 期望 | 失败原因 |
|
||||
|------|------|----------|
|
||||
| `system_node.version` | 非空且 ≥ 18 | 未装或版本太低 |
|
||||
| `system_npm.version` | 非空 | 应随 Node 自带 |
|
||||
| `volta_path` | 非空 | DesireCore Volta 未释放，调 `POST /api/runtime/volta/install` |
|
||||
| `volta_tools.node` | 非空数组 | 还未装任何 Volta 管理的 Node 版本 |
|
||||
| `package_json_volta` | 项目用 Volta | 优先 Volta，不要切到 nvm |
|
||||
| `registry` | `*.npmmirror.com` | 已加速；空字符串可能是 npm 未装 |
|
||||
| `proxy` | 非空 | 公司代理已设；如有问题先查代理 |
|
||||
|
||||
## 重置整个 Node.js 环境（最后手段）
|
||||
|
||||
```bash
|
||||
# 1. 删除全局缓存
|
||||
npm cache clean --force
|
||||
pnpm store prune
|
||||
yarn cache clean
|
||||
|
||||
# 2. 删除项目锁文件 + node_modules
|
||||
rm -rf node_modules package-lock.json pnpm-lock.yaml yarn.lock
|
||||
|
||||
# 3. 重新探测
|
||||
bash skills/nodejs-runtime/scripts/probe-node.sh
|
||||
|
||||
# 4. 按主 SKILL.md 决策树重新安装并 install
|
||||
```
|
||||
165
skills/nodejs-runtime/references/volta-desirecore.md
Normal file
165
skills/nodejs-runtime/references/volta-desirecore.md
Normal file
@@ -0,0 +1,165 @@
|
||||
# DesireCore 内置 Volta（L1 / L2 主路径）
|
||||
|
||||
DesireCore 内置 [Volta](https://volta.sh/) v2.0.2（Rust 实现的 Node.js 工具链管理器）。Volta 二进制随应用打包于 `static/volta/`，运行时位于 `~/.desirecore/runtime/volta/`，**用户无需单独安装**。
|
||||
|
||||
> 与系统 Node.js 完全隔离：Volta 安装的工具位于 `~/.desirecore/runtime/volta/tools/image/`，不修改系统 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; }
|
||||
```
|
||||
|
||||
### Volta 自身
|
||||
|
||||
```bash
|
||||
curl -sk "${BASE}/volta/status"
|
||||
curl -sk -X POST "${BASE}/volta/install" # 自动下载到 runtime/
|
||||
```
|
||||
|
||||
### Node.js 版本
|
||||
|
||||
```bash
|
||||
# 已装版本
|
||||
curl -sk "${BASE}/node/installed"
|
||||
|
||||
# 可装版本（远端 nodejs.org/dist 或 GitHub Releases）
|
||||
curl -sk "${BASE}/node/available"
|
||||
# ❗ 若返回 502，说明远端 / 镜像不可达，立即降级到 L2
|
||||
|
||||
# 安装（异步，立即返回 taskId）
|
||||
curl -sk -X POST "${BASE}/node/install" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"version":"22"}'
|
||||
|
||||
# 移除
|
||||
curl -sk -X POST "${BASE}/node/remove" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"version":"20.10.0"}'
|
||||
```
|
||||
|
||||
### 包管理器（pnpm / yarn / npm）
|
||||
|
||||
```bash
|
||||
TOOL="pnpm" # 或 yarn / npm
|
||||
|
||||
curl -sk "${BASE}/pkg/${TOOL}/installed"
|
||||
curl -sk "${BASE}/pkg/${TOOL}/available"
|
||||
|
||||
curl -sk -X POST "${BASE}/pkg/${TOOL}/install" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"version":"latest"}'
|
||||
|
||||
curl -sk -X POST "${BASE}/pkg/${TOOL}/remove" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"version":"9.0.0"}'
|
||||
```
|
||||
|
||||
### 实时输出 / 缓存刷新
|
||||
|
||||
异步任务：监听 Socket.IO 事件 `runtime:terminal` / `runtime:complete`，按 taskId 过滤。
|
||||
|
||||
```bash
|
||||
curl -sk -X POST "${BASE}/environment/refresh" # 安装结束后刷新
|
||||
```
|
||||
|
||||
## L2：直接调用 Volta CLI 绝对路径
|
||||
|
||||
### macOS / Linux
|
||||
|
||||
```bash
|
||||
VOLTA=~/.desirecore/runtime/volta/volta
|
||||
export VOLTA_HOME=~/.desirecore/runtime/volta
|
||||
export VOLTA_FEATURE_PNPM=1
|
||||
# export VOLTA_NODE_MIRROR=https://npmmirror.com/mirrors/node # 中国大陆加速
|
||||
|
||||
# 安装
|
||||
"$VOLTA" install node@22 # 最新 22.x
|
||||
"$VOLTA" install node@20.11.0 # 精确版本
|
||||
"$VOLTA" install pnpm@latest
|
||||
"$VOLTA" install yarn@latest
|
||||
"$VOLTA" install npm@10
|
||||
|
||||
# 列表
|
||||
"$VOLTA" list all
|
||||
"$VOLTA" list node
|
||||
|
||||
# 项目级固定（写入 package.json#volta）
|
||||
"$VOLTA" pin node@22 pnpm@9
|
||||
```
|
||||
|
||||
`volta pin` 后 `package.json` 中会自动追加：
|
||||
```json
|
||||
"volta": {
|
||||
"node": "22.11.0",
|
||||
"pnpm": "9.5.0"
|
||||
}
|
||||
```
|
||||
|
||||
后续 `cd` 进项目目录时 Volta 自动激活对应版本。
|
||||
|
||||
### Windows PowerShell
|
||||
|
||||
```powershell
|
||||
$Volta = "$env:USERPROFILE\.desirecore\runtime\volta\volta.exe"
|
||||
$env:VOLTA_HOME = "$env:USERPROFILE\.desirecore\runtime\volta"
|
||||
$env:VOLTA_FEATURE_PNPM = "1"
|
||||
|
||||
& $Volta install node@22
|
||||
& $Volta install pnpm@latest
|
||||
& $Volta list all
|
||||
```
|
||||
|
||||
### 移除
|
||||
|
||||
Volta 没有 `volta uninstall node`，直接删目录或用 HTTP API：
|
||||
|
||||
```bash
|
||||
rm -rf ~/.desirecore/runtime/volta/tools/image/node/<version>
|
||||
```
|
||||
|
||||
或：
|
||||
```bash
|
||||
curl -sk -X POST "${BASE}/node/remove" -H "Content-Type: application/json" -d '{"version":"22.11.0"}'
|
||||
```
|
||||
|
||||
## 可视化管理
|
||||
|
||||
DesireCore 应用 → 资源管理器 → 计算资源 → **运行环境** Tab，GUI 安装/删除 Node.js 与包管理器。
|
||||
|
||||
## 版本自动切换（核心优势）
|
||||
|
||||
只要 `package.json` 中有 `volta` 字段，Volta 会在 `cd` 进入目录时**自动激活**对应版本。无需手动 `volta use`，也无需 `.nvmrc`。
|
||||
|
||||
## Volta vs nvm
|
||||
|
||||
| 维度 | Volta（DesireCore 内置） | nvm（社区） |
|
||||
|------|--------------------------|-------------|
|
||||
| 安装方式 | 随 DesireCore 内置 | 用户手动 |
|
||||
| 版本切换 | **自动**（基于 package.json） | 手动 `nvm use` 或 `.nvmrc` |
|
||||
| 包管理器 | 支持（pnpm/yarn/npm 都可固定版本） | 不支持 |
|
||||
| Windows 原生 | ✅ | 需 nvm-windows（功能受限） |
|
||||
| 速度 | 极快（Rust 实现） | 较慢（shell 脚本） |
|
||||
| 系统 PATH | 不污染 | 修改 PATH |
|
||||
| GUI | DesireCore 运行环境 Tab | 无 |
|
||||
| 镜像加速 | `VOLTA_NODE_MIRROR` | 无内建支持 |
|
||||
|
||||
**结论**：DesireCore 应用内、有 Volta 时永远首选 Volta；外部脚本可考虑 nvm/fnm。
|
||||
|
||||
## 故障排查（Volta 专属）
|
||||
|
||||
| 现象 | 排查 |
|
||||
|------|------|
|
||||
| `volta: not found` | 二进制未释放，调 `POST /api/runtime/volta/install` |
|
||||
| `Volta error: Could not download node v22.x.x` | 网络或镜像问题，设 `VOLTA_NODE_MIRROR` |
|
||||
| `volta install pnpm` 报错 | 检查 `VOLTA_FEATURE_PNPM=1` 是否设置 |
|
||||
| Windows Defender 隔离 volta.exe | 信任 `~\.desirecore\runtime\volta\` 目录 |
|
||||
| `cd` 进项目后版本未切换 | 确认 `package.json` 中 `volta` 字段且 PATH 中 Volta shim 在最前 |
|
||||
119
skills/nodejs-runtime/scripts/probe-node.sh
Executable file
119
skills/nodejs-runtime/scripts/probe-node.sh
Executable file
@@ -0,0 +1,119 @@
|
||||
#!/usr/bin/env bash
|
||||
# nodejs-runtime probe: 输出 Node.js 环境快照（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
|
||||
|
||||
# ── 系统 Node / npm ─────────────────────
|
||||
SYS_NODE=$(detect_tool node)
|
||||
SYS_NPM=$(detect_tool npm)
|
||||
|
||||
# ── DesireCore Volta ────────────────────
|
||||
VOLTA_BIN="$HOME/.desirecore/runtime/volta/volta"
|
||||
VOLTA_PATH=""
|
||||
VOLTA_VERSION=""
|
||||
if [ -x "$VOLTA_BIN" ]; then
|
||||
VOLTA_PATH="$VOLTA_BIN"
|
||||
VOLTA_VERSION=$("$VOLTA_BIN" --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -n1)
|
||||
fi
|
||||
|
||||
# Volta 已装工具（直接读 image 目录最稳）
|
||||
VOLTA_IMG="$HOME/.desirecore/runtime/volta/tools/image"
|
||||
list_dir() {
|
||||
local dir="$1"
|
||||
if [ -d "$dir" ]; then
|
||||
local items
|
||||
items=$(ls -1 "$dir" 2>/dev/null | sort -V | tr '\n' ',' | sed 's/,$//')
|
||||
if [ -n "$items" ]; then
|
||||
echo "[\"$(echo "$items" | sed 's/,/","/g')\"]"
|
||||
return
|
||||
fi
|
||||
fi
|
||||
echo "[]"
|
||||
}
|
||||
NODE_VERSIONS=$(list_dir "$VOLTA_IMG/node")
|
||||
PNPM_VERSIONS=$(list_dir "$VOLTA_IMG/pnpm")
|
||||
YARN_VERSIONS=$(list_dir "$VOLTA_IMG/yarn")
|
||||
NPM_VERSIONS=$(list_dir "$VOLTA_IMG/npm")
|
||||
|
||||
# ── package.json#volta ──────────────────
|
||||
PKG_VOLTA="null"
|
||||
if [ -f "package.json" ]; then
|
||||
PKG_VOLTA=$(python3 -c "import json,sys; d=json.load(open('package.json')); print(json.dumps(d.get('volta')))" 2>/dev/null || echo "null")
|
||||
[ -z "$PKG_VOLTA" ] && PKG_VOLTA="null"
|
||||
fi
|
||||
|
||||
# ── 社区方案 ────────────────────────────
|
||||
NVM_PATH=""
|
||||
[ -s "$HOME/.nvm/nvm.sh" ] && NVM_PATH="$HOME/.nvm/nvm.sh"
|
||||
FNM_PATH=$(command -v fnm 2>/dev/null)
|
||||
|
||||
# ── npm config ──────────────────────────
|
||||
REGISTRY=""
|
||||
PROXY=""
|
||||
if command -v npm >/dev/null 2>&1; then
|
||||
REGISTRY=$(npm config get registry 2>/dev/null | tr -d '\r\n')
|
||||
PROXY=$(npm config get https-proxy 2>/dev/null | tr -d '\r\n')
|
||||
[ "$PROXY" = "null" ] && PROXY=""
|
||||
fi
|
||||
|
||||
# ── 输出 JSON ───────────────────────────
|
||||
cat <<EOF
|
||||
{
|
||||
"platform": "${PLATFORM}",
|
||||
"arch": "${ARCH}",
|
||||
"desirecore_api": "${DESIRECORE_API}",
|
||||
"system_node": ${SYS_NODE},
|
||||
"system_npm": ${SYS_NPM},
|
||||
"volta_path": "${VOLTA_PATH}",
|
||||
"volta_version": "${VOLTA_VERSION}",
|
||||
"volta_tools": {
|
||||
"node": ${NODE_VERSIONS},
|
||||
"pnpm": ${PNPM_VERSIONS},
|
||||
"yarn": ${YARN_VERSIONS},
|
||||
"npm": ${NPM_VERSIONS}
|
||||
},
|
||||
"package_json_volta": ${PKG_VOLTA},
|
||||
"nvm_path": "${NVM_PATH}",
|
||||
"fnm_path": "${FNM_PATH:-}",
|
||||
"registry": "${REGISTRY}",
|
||||
"proxy": "${PROXY}"
|
||||
}
|
||||
EOF
|
||||
@@ -81,7 +81,8 @@ python3 --version 2>/dev/null || python --version 2>/dev/null
|
||||
- **Linux (Debian/Ubuntu)**: `sudo apt install python3 python3-pip`
|
||||
- **Linux (Fedora/RHEL)**: `sudo dnf install python3 python3-pip`
|
||||
|
||||
如需更详细的环境配置帮助，加载 `environment-setup` 技能。
|
||||
如需更详细的环境配置帮助：Python 相关问题加载 `python-runtime` 技能；
|
||||
其他（系统工具如 poppler / tesseract、容器 / WSL）加载 `dev-environment-setup` 技能。
|
||||
|
||||
### Python 包依赖
|
||||
|
||||
|
||||
@@ -88,7 +88,9 @@ python3 --version 2>/dev/null || python --version 2>/dev/null
|
||||
|
||||
注意：从零创建 PPTX 使用 pptxgenjs（Node.js），不需要 Python。
|
||||
|
||||
如需更详细的环境配置帮助，加载 `environment-setup` 技能。
|
||||
如需更详细的环境配置帮助：Python 相关问题加载 `python-runtime` 技能；
|
||||
Node.js（pptxgenjs）相关问题加载 `nodejs-runtime` 技能；其他（系统工具 /
|
||||
容器 / WSL）加载 `dev-environment-setup` 技能。
|
||||
|
||||
### Python 包依赖
|
||||
|
||||
|
||||
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
|
||||
@@ -88,7 +88,8 @@ python3 --version 2>/dev/null || python --version 2>/dev/null
|
||||
- **Linux (Debian/Ubuntu)**: `sudo apt install python3 python3-pip`
|
||||
- **Linux (Fedora/RHEL)**: `sudo dnf install python3 python3-pip`
|
||||
|
||||
如需更详细的环境配置帮助，加载 `environment-setup` 技能。
|
||||
如需更详细的环境配置帮助：Python 相关问题加载 `python-runtime` 技能；
|
||||
其他（LibreOffice / 容器 / WSL）加载 `dev-environment-setup` 技能。
|
||||
|
||||
### Python 包依赖
|
||||
|
||||
|
||||
Reference in New Issue
Block a user