From 1a50969b93d5a77a565859c62f84bd2a377dfe24 Mon Sep 17 00:00:00 2001 From: yi-ge Date: Sat, 2 May 2026 13:30:23 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=8B=86=E5=88=86=20environment-setup?= =?UTF-8?q?=20=E4=B8=BA=20Python/Node.js=20=E8=BF=90=E8=A1=8C=E6=97=B6?= =?UTF-8?q?=E5=8F=8C=E6=A0=B8=E5=BF=83=20+=20=E7=88=B6=E7=BA=A7=E8=B7=AF?= =?UTF-8?q?=E7=94=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增双核心 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) --- builtin-skills.json | 4 +- manifest.json | 4 +- skills/dev-environment-setup/SKILL.md | 159 ++ .../references/container.md | 193 +++ .../references/decision-tree.md | 163 ++ .../references/desirecore-runtime.md | 169 ++ .../references/office-deps.md | 175 +++ .../references/probe-snapshot.md | 118 ++ .../references/system-tools.md | 224 +++ .../dev-environment-setup/references/wsl.md | 138 ++ .../dev-environment-setup/scripts/probe.ps1 | 66 + skills/dev-environment-setup/scripts/probe.sh | 77 + skills/docx/SKILL.md | 3 +- skills/environment-setup/SKILL.md | 1379 ----------------- skills/nodejs-runtime/SKILL.md | 193 +++ .../nodejs-runtime/references/nvm-fallback.md | 140 ++ .../references/package-managers.md | 160 ++ .../references/troubleshooting.md | 173 +++ .../references/volta-desirecore.md | 165 ++ skills/nodejs-runtime/scripts/probe-node.sh | 119 ++ skills/pdf/SKILL.md | 3 +- skills/pptx/SKILL.md | 4 +- skills/python-runtime/SKILL.md | 194 +++ .../references/hatch-desirecore.md | 147 ++ .../references/pyenv-fallback.md | 97 ++ .../references/troubleshooting.md | 178 +++ .../python-runtime/references/virtualenv.md | 145 ++ skills/python-runtime/scripts/probe-python.sh | 103 ++ skills/xlsx/SKILL.md | 3 +- 29 files changed, 3310 insertions(+), 1386 deletions(-) create mode 100644 skills/dev-environment-setup/SKILL.md create mode 100644 skills/dev-environment-setup/references/container.md create mode 100644 skills/dev-environment-setup/references/decision-tree.md create mode 100644 skills/dev-environment-setup/references/desirecore-runtime.md create mode 100644 skills/dev-environment-setup/references/office-deps.md create mode 100644 skills/dev-environment-setup/references/probe-snapshot.md create mode 100644 skills/dev-environment-setup/references/system-tools.md create mode 100644 skills/dev-environment-setup/references/wsl.md create mode 100644 skills/dev-environment-setup/scripts/probe.ps1 create mode 100755 skills/dev-environment-setup/scripts/probe.sh delete mode 100644 skills/environment-setup/SKILL.md create mode 100644 skills/nodejs-runtime/SKILL.md create mode 100644 skills/nodejs-runtime/references/nvm-fallback.md create mode 100644 skills/nodejs-runtime/references/package-managers.md create mode 100644 skills/nodejs-runtime/references/troubleshooting.md create mode 100644 skills/nodejs-runtime/references/volta-desirecore.md create mode 100755 skills/nodejs-runtime/scripts/probe-node.sh create mode 100644 skills/python-runtime/SKILL.md create mode 100644 skills/python-runtime/references/hatch-desirecore.md create mode 100644 skills/python-runtime/references/pyenv-fallback.md create mode 100644 skills/python-runtime/references/troubleshooting.md create mode 100644 skills/python-runtime/references/virtualenv.md create mode 100755 skills/python-runtime/scripts/probe-python.sh diff --git a/builtin-skills.json b/builtin-skills.json index f4780e3..8a4ddc6 100644 --- a/builtin-skills.json +++ b/builtin-skills.json @@ -2,9 +2,9 @@ "skills": [ "create-agent", "delete-agent", + "dev-environment-setup", "discover-agent", "docx", - "environment-setup", "frontend-design", "mail-operations", "manage-skills", @@ -12,8 +12,10 @@ "minimax-image-gen", "minimax-tts", "minimax-video-gen", + "nodejs-runtime", "pdf", "pptx", + "python-runtime", "s3-storage-operations", "skill-creator", "update-agent", diff --git a/manifest.json b/manifest.json index 6be7615..7a9e1ce 100644 --- a/manifest.json +++ b/manifest.json @@ -15,8 +15,8 @@ }, "stats": { "totalAgents": 1, - "totalSkills": 19, - "lastUpdated": "2026-05-01" + "totalSkills": 21, + "lastUpdated": "2026-05-02" }, "features": [ "verified-only", diff --git a/skills/dev-environment-setup/SKILL.md b/skills/dev-environment-setup/SKILL.md new file mode 100644 index 0000000..85dae1b --- /dev/null +++ b/skills/dev-environment-setup/SKILL.md @@ -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: >- + + 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"。 diff --git a/skills/dev-environment-setup/references/container.md b/skills/dev-environment-setup/references/container.md new file mode 100644 index 0000000..f8cf71f --- /dev/null +++ b/skills/dev-environment-setup/references/container.md @@ -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 </scripts/probe-{python,node}.sh +``` + +避免后续判断基于陈旧缓存。 diff --git a/skills/dev-environment-setup/references/desirecore-runtime.md b/skills/dev-environment-setup/references/desirecore-runtime.md new file mode 100644 index 0000000..12f683e --- /dev/null +++ b/skills/dev-environment-setup/references/desirecore-runtime.md @@ -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//`，包管理器在 `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 启动时写入 | diff --git a/skills/dev-environment-setup/references/office-deps.md b/skills/dev-environment-setup/references/office-deps.md new file mode 100644 index 0000000..a8a0673 --- /dev/null +++ b/skills/dev-environment-setup/references/office-deps.md @@ -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 +``` diff --git a/skills/dev-environment-setup/references/probe-snapshot.md b/skills/dev-environment-setup/references/probe-snapshot.md new file mode 100644 index 0000000..167451c --- /dev/null +++ b/skills/dev-environment-setup/references/probe-snapshot.md @@ -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` 来自 ` 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) { ... } +``` diff --git a/skills/dev-environment-setup/references/system-tools.md b/skills/dev-environment-setup/references/system-tools.md new file mode 100644 index 0000000..15482d3 --- /dev/null +++ b/skills/dev-environment-setup/references/system-tools.md @@ -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 +``` diff --git a/skills/dev-environment-setup/references/wsl.md b/skills/dev-environment-setup/references/wsl.md new file mode 100644 index 0000000..591af4e --- /dev/null +++ b/skills/dev-environment-setup/references/wsl.md @@ -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//`），不要放 `/mnt/c/`——后者跨文件系统 IO 极慢 +- 编辑器：VS Code + Remote-WSL 扩展，自动跨边界 +- Docker：使用 Docker Desktop 的 WSL2 后端，避免 WSL2 内独立 Docker 守护进程 diff --git a/skills/dev-environment-setup/scripts/probe.ps1 b/skills/dev-environment-setup/scripts/probe.ps1 new file mode 100644 index 0000000..23253e0 --- /dev/null +++ b/skills/dev-environment-setup/scripts/probe.ps1 @@ -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 diff --git a/skills/dev-environment-setup/scripts/probe.sh b/skills/dev-environment-setup/scripts/probe.sh new file mode 100755 index 0000000..086d2a1 --- /dev/null +++ b/skills/dev-environment-setup/scripts/probe.sh @@ -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 </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 包依赖 diff --git a/skills/environment-setup/SKILL.md b/skills/environment-setup/SKILL.md deleted file mode 100644 index c77479f..0000000 --- a/skills/environment-setup/SKILL.md +++ /dev/null @@ -1,1379 +0,0 @@ ---- -name: 开发环境配置 -description: >- - Use this skill when the user needs help setting up a development environment. - Covers three pillars: (1) Python/Node.js runtime installation and multi-version - management (Hatch, Volta, pyenv, nvm); (2) Docker/Podman container runtime - detection, installation, and usage; (3) WSL2 setup on Windows for Linux - compatibility. Triggers include: "install python", "install node", "install - docker", "setup environment", "virtual environment", "venv", "nvm", "pyenv", - "pip not found", "python not found", "node not found", "npm not found", - "docker not found", "container", "podman", "WSL", "WSL2", "PATH issues", - "version manager", or any error message indicating a missing runtime, package - manager, or container engine. Also use when other skills (docx, pdf, xlsx, - pptx) report that Python or Node.js is not available and the user needs - guidance. Use when 用户提到 安装Python、安装Node、安装Docker、容器、Podman、 - WSL、WSL2、环境配置、虚拟环境、版本管理、PATH问题、pip找不到、python找不到、 - docker找不到、容器运行环境。 -version: 1.1.2 -type: procedural -risk_level: low -status: enabled -disable-model-invocation: true -tags: - - environment - - python - - nodejs - - docker - - container - - wsl - - setup - - troubleshooting -metadata: - author: desirecore - updated_at: '2026-04-13' -market: - icon: >- - - short_desc: Python / Node.js / Docker 环境安装、版本管理与问题排查 - category: productivity - maintainer: - name: DesireCore Official - verified: true - channel: latest ---- - -# environment-setup 技能 - -## L0：一句话摘要 - -检测、安装和排查 Python / Node.js / Docker 开发环境，覆盖多版本管理与容器运行时。 - -## L1：概述与使用场景 - -### 能力描述 - -environment-setup 是一个**流程型技能（Procedural Skill）**，提供开发环境的完整配置指南，涵盖三大支柱：运行时环境（Python / Node.js）、容器环境（Docker / Podman）、Windows 子系统（WSL2）。 - -### 使用场景 - -- 用户需要安装 Python、Node.js 或 Docker -- 用户遇到 "python not found"、"npm not found"、"docker not found" 等环境问题 -- 用户需要配置多版本管理（Hatch、Volta、pyenv、nvm） -- 其他技能（docx、pdf、xlsx、pptx）报告 Python 或 Node.js 不可用时 -- Windows 用户需要配置 WSL2 - -### 核心价值 - -- **全平台覆盖**：macOS / Windows / Linux 全面支持 -- **多方案对比**：DesireCore 内置方案（Hatch/Volta）与社区方案（pyenv/nvm）对比 -- **故障排查**：常见错误的诊断步骤和解决方案 - -## L2：详细规范 - -## 快速诊断 - -在进行任何安装之前，先运行以下命令检查当前环境状态： - -```bash -echo "=== OS ===" && uname -a -echo "=== Python ===" && python3 --version 2>/dev/null || python --version 2>/dev/null || echo "NOT FOUND" -echo "=== pip ===" && pip3 --version 2>/dev/null || pip --version 2>/dev/null || echo "NOT FOUND" -echo "=== Node.js ===" && node --version 2>/dev/null || echo "NOT FOUND" -echo "=== npm ===" && npm --version 2>/dev/null || echo "NOT FOUND" -echo "=== Docker ===" && docker --version 2>/dev/null || echo "NOT FOUND" -echo "=== Podman ===" && podman --version 2>/dev/null || echo "NOT FOUND" -echo "=== PATH ===" && echo "$PATH" | tr ':' '\n' -``` - -**Windows 额外检测**（在 PowerShell 中运行）： - -```powershell -Write-Host "=== WSL ===" ; wsl --status 2>&1 -Write-Host "=== Docker ===" ; docker --version 2>$null ; if (-not $?) { Write-Host "NOT FOUND" } -``` - -根据输出结果，跳转到对应章节。 - ---- - -## Python 安装 - -### macOS - -#### 方式 1：Homebrew（推荐） - -```bash -# 安装 Homebrew（如果尚未安装） -/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" - -# 安装 Python 3 -brew install python3 - -# 验证安装 -python3 --version -pip3 --version -``` - -Homebrew 安装的 Python 位于 `/opt/homebrew/bin/python3`（Apple Silicon）或 `/usr/local/bin/python3`（Intel）。 - -#### 方式 2：官方安装包 - -1. 访问 https://www.python.org/downloads/ -2. 下载最新的 macOS 安装包（.pkg） -3. 双击运行安装程序，按照向导完成安装 -4. 安装完成后打开新终端窗口验证： - -```bash -python3 --version -``` - -#### macOS 注意事项 - -- macOS 自带的 `/usr/bin/python3` 是 Apple 提供的精简版，缺少 `pip`，**不建议用于开发** -- 如果运行 `pip3` 提示 "No module named pip"，说明在使用系统自带 Python，请安装 Homebrew 或官方版本 -- Xcode Command Line Tools 安装：`xcode-select --install`（部分 Python 包编译时需要） - -### Windows - -#### 方式 1：winget（推荐） - -```powershell -winget install Python.Python.3 -``` - -安装后**重启终端**，验证： - -```powershell -python --version -pip --version -``` - -#### 方式 2：官方安装包 - -1. 访问 https://www.python.org/downloads/ -2. 下载 Windows installer（.exe） -3. **务必勾选 "Add Python to PATH"**（安装界面底部的复选框） -4. 点击 "Install Now" -5. 安装完成后打开新的 CMD 或 PowerShell 验证 - -#### Windows 注意事项 - -- Windows 10/11 自带的 `python` 命令可能指向 Microsoft Store 的占位符，会弹出商店页面而非执行 Python。安装官方 Python 后此行为会被覆盖 -- 如果安装后 `python` 仍指向 Store，在系统设置 > 应用 > 高级应用设置 > 应用执行别名中关闭 "python.exe" 和 "python3.exe" 的 Store 别名 -- PowerShell 执行策略可能阻止脚本运行：`Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` - -### Linux (Debian/Ubuntu) - -```bash -sudo apt update -sudo apt install python3 python3-pip python3-venv -python3 --version -pip3 --version -``` - -### Linux (Fedora/RHEL/CentOS) - -```bash -sudo dnf install python3 python3-pip -python3 --version -pip3 --version -``` - -### Linux (Arch) - -```bash -sudo pacman -S python python-pip -python --version -pip --version -``` - -### Linux 注意事项 - -- 部分发行版（如 Debian 12+、Ubuntu 23.04+）启用了 PEP 668 "externally managed environment" 策略，`pip install` 全局安装会被拒绝。解决方法见下方"虚拟环境"章节，或使用 `pipx` -- 如果系统同时存在 Python 2 和 Python 3，确保使用 `python3` 和 `pip3` 而非 `python` 和 `pip` - ---- - -## Python 多版本管理（Hatch — DesireCore 内置） - -DesireCore 内置了 [Hatch](https://hatch.pypa.io/) v1.16.5 作为 Python 项目管理器和版本管理器。Hatch 二进制随应用打包在 `static/hatch/` 中，**无需用户单独安装**。 - -> **与系统 Python 的关系**：Hatch 管理的 Python 版本安装在 `~/.desirecore/runtime/hatch/local/` 中，与系统 Python 完全隔离，不会影响系统环境。 - -### 查看可安装的 Python 版本 - -```bash -# Hatch 二进制位置（DesireCore 自动管理，通常无需手动调用） -# macOS / Linux: -~/.desirecore/runtime/hatch/hatch python show - -# 输出示例： -# ┌──────────┬─────────┐ -# │ Name │ Version │ -# ├──────────┼─────────┤ -# │ 3.8 │ 3.8.20 │ -# │ 3.9 │ 3.9.21 │ -# │ 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 │ -# └──────────┴─────────┘ -``` - -### 安装 Python 版本 - -```bash -# 安装指定版本（下载到 ~/.desirecore/runtime/hatch/local/） -hatch python install 3.12 -hatch python install 3.11 - -# 安装多个版本 -hatch python install 3.12 3.11 3.10 -``` - -### 查看已安装版本 - -```bash -# 查看 ~/.desirecore/runtime/hatch/local/ 下的目录 -ls ~/.desirecore/runtime/hatch/local/ -# 输出：3.11 3.12 -``` - -### 移除 Python 版本 - -```bash -hatch python remove 3.11 -``` - -### 使用 Hatch 管理的 Python - -```bash -# 直接使用安装的 Python -~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 --version - -# 创建虚拟环境 -~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 -m venv .venv -source .venv/bin/activate -``` - -### 可视化管理 - -打开 DesireCore 应用 → 资源管理器（侧边栏文件夹图标）→ 计算资源 → **运行环境** Tab，可以可视化地查看、安装、删除 Python 版本。 - -### Hatch vs pyenv - -| 特性 | Hatch (DesireCore 内置) | pyenv (社区) | -|------|------------------------|-------------| -| 安装方式 | 随 DesireCore 自动内置 | 需手动安装 | -| Python 存放位置 | `~/.desirecore/runtime/hatch/local/` | `~/.pyenv/versions/` | -| 版本切换 | 通过绝对路径或 venv | `pyenv global/local` | -| 系统影响 | 完全隔离 | 修改 shell PATH | -| GUI 管理 | DesireCore 运行环境 Tab | 无 | -| 适用场景 | DesireCore 技能执行环境 | 日常开发多版本管理 | - ---- - -## Python 多版本管理（pyenv — 社区方案） - -当需要在系统级别管理多个 Python 版本时，pyenv 是社区中最流行的方案。 - -### 安装 pyenv - -#### macOS / Linux - -```bash -# 安装 pyenv -curl https://pyenv.run | bash - -# 添加到 shell 配置（zsh） -echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.zshrc -echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.zshrc -echo 'eval "$(pyenv init -)"' >> ~/.zshrc - -# 添加到 shell 配置（bash） -echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc -echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc -echo 'eval "$(pyenv init -)"' >> ~/.bashrc - -# 重新加载 shell -exec "$SHELL" -``` - -#### macOS 编译依赖 - -```bash -brew install openssl readline sqlite3 xz zlib tcl-tk -``` - -#### Ubuntu/Debian 编译依赖 - -```bash -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 编译依赖 - -```bash -sudo dnf install gcc make zlib-devel bzip2 bzip2-devel \ - readline-devel sqlite sqlite-devel openssl-devel tk-devel \ - libffi-devel xz-devel -``` - -#### Windows - -Windows 上推荐使用 [pyenv-win](https://github.com/pyenv-win/pyenv-win)： - -```powershell -# 通过 pip 安装 -pip install pyenv-win --target "$HOME\.pyenv" - -# 或通过 PowerShell 脚本安装 -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 profile）： - -```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 版本 -pyenv local 3.11.9 # 创建 .python-version 文件 - -# 查看已安装的版本 -pyenv versions - -# 查看当前激活的版本 -pyenv version - -# 卸载版本 -pyenv uninstall 3.10.14 -``` - ---- - -## Python 虚拟环境 - -虚拟环境隔离项目依赖，避免全局污染。**强烈建议每个项目使用独立的虚拟环境。** - -### venv（内置，推荐） - -```bash -# 创建虚拟环境 -python3 -m venv .venv - -# 激活虚拟环境 -# macOS / Linux: -source .venv/bin/activate -# Windows CMD: -.venv\Scripts\activate.bat -# Windows PowerShell: -.venv\Scripts\Activate.ps1 - -# 验证（应显示 .venv 中的 python） -which python # macOS/Linux -where python # Windows - -# 安装依赖 -pip install -r requirements.txt - -# 退出虚拟环境 -deactivate -``` - -### pipx（安装全局 CLI 工具） - -当需要全局安装命令行工具（如 `black`、`ruff`、`markitdown`）但不想污染系统 Python 环境时： - -```bash -# 安装 pipx -# macOS: -brew install pipx -pipx ensurepath - -# Linux (Debian/Ubuntu): -sudo apt install pipx -pipx ensurepath - -# Windows: -pip install --user pipx -pipx ensurepath - -# 使用 pipx 安装工具 -pipx install black -pipx install ruff -pipx install markitdown -``` - -### conda / miniconda - -适用于数据科学和需要非 Python 依赖（如 BLAS、CUDA）的场景： - -```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)" - -# 创建环境 -conda create -n myproject python=3.12 -conda activate myproject - -# 安装包 -conda install numpy pandas scikit-learn -pip install some-pypi-only-package # conda 没有的包用 pip - -# 退出 -conda deactivate -``` - ---- - -## Node.js 安装 - -### macOS - -#### 方式 1：Homebrew - -```bash -brew install node -node --version -npm --version -``` - -#### 方式 2：官方安装包 - -1. 访问 https://nodejs.org/ -2. 下载 LTS 版本的 macOS 安装包（.pkg） -3. 运行安装程序 - -### Windows - -#### 方式 1：winget - -```powershell -winget install OpenJS.NodeJS.LTS -``` - -#### 方式 2：官方安装包 - -1. 访问 https://nodejs.org/ -2. 下载 Windows LTS 安装包（.msi） -3. 运行安装程序（默认选项即可，会自动添加到 PATH） - -### Linux (Debian/Ubuntu) - -使用 NodeSource 官方仓库获取最新 LTS： - -```bash -# 安装 Node.js 22.x LTS（根据需要替换版本号） -curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - -sudo apt install -y nodejs - -node --version -npm --version -``` - -或使用系统仓库（版本可能较旧）： - -```bash -sudo apt install nodejs npm -``` - -### Linux (Fedora/RHEL) - -```bash -curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash - -sudo dnf install -y nodejs -``` - -### Linux (Arch) - -```bash -sudo pacman -S nodejs npm -``` - ---- - -## Node.js 多版本管理（Volta — DesireCore 内置） - -DesireCore 内置了 [Volta](https://volta.sh/) v2.0.2 作为 Node.js 工具链管理器。Volta 二进制随应用打包在 `static/volta/` 中，**无需用户单独安装**。 - -> **与系统 Node.js 的关系**：Volta 管理的 Node.js 和包管理器安装在 `~/.desirecore/runtime/volta/` 中，与系统 Node.js 完全隔离。 - -### 安装 Node.js 版本 - -```bash -# Volta 二进制位置（DesireCore 自动管理） -# 安装最新 LTS -volta install node@22 - -# 安装指定版本 -volta install node@20.11.0 - -# 安装特定大版本的最新版 -volta install node@18 -``` - -### 安装包管理器 - -```bash -# 安装 pnpm -volta install pnpm@latest - -# 安装 yarn -volta install yarn@latest - -# 安装指定版本的 npm -volta install npm@10 -``` - -### 查看已安装版本 - -```bash -# 查看已安装的 Node.js 版本 -volta list node - -# 查看已安装的所有工具 -volta list all -``` - -### 固定项目版本 - -```bash -# 在项目目录下，固定 Node.js 和包管理器版本到 package.json -volta pin node@22 -volta pin pnpm@9 - -# package.json 中会自动添加： -# "volta": { -# "node": "22.x.x", -# "pnpm": "9.x.x" -# } -``` - -### 版本自动切换 - -Volta 的核心优势：当你 `cd` 进入一个项目目录时，如果 `package.json` 中包含 `volta` 配置，Volta 会**自动切换**到指定版本，无需手动 `use`。 - -### 移除版本 - -```bash -# 移除 Node.js 版本 -# 通过 DesireCore 运行环境 Tab 管理，或手动删除： -rm -rf ~/.desirecore/runtime/volta/tools/image/node/ -``` - -### 可视化管理 - -打开 DesireCore 应用 → 资源管理器 → 计算资源 → **运行环境** Tab，可以可视化地查看、安装、删除 Node.js 版本和包管理器。 - -### Volta vs nvm - -| 特性 | Volta (DesireCore 内置) | nvm (社区) | -|------|------------------------|-----------| -| 安装方式 | 随 DesireCore 自动内置 | 需手动安装 | -| 版本切换 | 自动（基于 package.json） | 手动 `nvm use` 或 `.nvmrc` | -| 包管理器管理 | 支持（pnpm/yarn/npm） | 不支持 | -| Windows 支持 | 原生支持 | 需用 nvm-windows | -| 速度 | 极快（Rust 实现） | 较慢（shell 脚本） | -| 系统影响 | 完全隔离 | 修改 shell PATH | -| GUI 管理 | DesireCore 运行环境 Tab | 无 | -| 适用场景 | DesireCore 技能执行环境 | 日常开发多版本管理 | - ---- - -## Node.js 多版本管理（nvm — 社区方案） - -### 安装 nvm - -#### macOS / Linux - -```bash -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash - -# 重新加载 shell 配置 -source ~/.zshrc # 或 source ~/.bashrc -``` - -#### Windows - -Windows 上使用 [nvm-windows](https://github.com/coreybutler/nvm-windows)： - -1. 从 https://github.com/coreybutler/nvm-windows/releases 下载安装包 -2. 运行安装程序 -3. 重启终端 - -### 使用 nvm - -```bash -# 查看可安装的 LTS 版本 -nvm ls-remote --lts - -# 安装指定版本 -nvm install 22 # 安装最新 22.x -nvm install 20 # 安装最新 20.x -nvm install --lts # 安装最新 LTS - -# 切换版本 -nvm use 22 -nvm use 20 - -# 设置默认版本 -nvm alias default 22 - -# 查看已安装版本 -nvm ls - -# 在项目中固定版本（创建 .nvmrc 文件） -echo "22" > .nvmrc -nvm use # 自动读取 .nvmrc -``` - -### 使用 fnm（社区替代品，Rust 实现） - -[fnm](https://github.com/Schniz/fnm) 是用 Rust 编写的 Node.js 版本管理器，比 nvm 快得多： - -```bash -# 安装 fnm -# macOS: -brew install fnm -# Linux: -curl -fsSL https://fnm.vercel.app/install | bash -# Windows: -winget install Schniz.fnm - -# 添加到 shell（zsh） -echo 'eval "$(fnm env --use-on-cd --shell zsh)"' >> ~/.zshrc - -# 添加到 shell（bash） -echo 'eval "$(fnm env --use-on-cd --shell bash)"' >> ~/.bashrc - -# 使用方式与 nvm 类似 -fnm install 22 -fnm use 22 -fnm default 22 -fnm ls -``` - ---- - -## npm 全局包管理 - -```bash -# 查看全局安装的包 -npm ls -g --depth=0 - -# 安装全局包 -npm install -g pptxgenjs -npm install -g docx - -# 查看全局包安装位置 -npm root -g - -# 如果全局安装报权限错误（Linux/macOS），不要用 sudo -# 而是更改 npm 全局目录： -mkdir -p ~/.npm-global -npm config set prefix '~/.npm-global' -echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc # 或 ~/.bashrc -source ~/.zshrc -``` - ---- - -## 常见问题排查 - -### "python: command not found" 或 "python3: command not found" - -**原因**：Python 未安装或未添加到 PATH。 - -**排查步骤**： - -```bash -# 1. 检查是否安装了 Python -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 -# macOS (Apple Silicon): -export PATH="/opt/homebrew/bin:$PATH" -# macOS (Intel): -export PATH="/usr/local/bin:$PATH" -``` - -**解决方案**：按照上方"Python 安装"章节安装，或修复 PATH 配置。 - -### "pip: command not found" - -**原因**：pip 未安装，或 Python 是系统自带的精简版。 - -```bash -# 尝试使用 python -m pip -python3 -m pip --version - -# 如果也失败，手动安装 pip -curl -fsSL https://bootstrap.pypa.io/get-pip.py -o get-pip.py -python3 get-pip.py --user -rm get-pip.py - -# 确保 ~/.local/bin 在 PATH 中 -echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc # 或 ~/.bashrc -source ~/.zshrc -``` - -### "externally-managed-environment" 错误（PEP 668） - -**现象**：`pip install` 报错 "This environment is externally managed"。 - -**原因**：Debian 12+、Ubuntu 23.04+、Fedora 38+ 等新版发行版限制全局 pip 安装以保护系统 Python。 - -**解决方案（推荐优先级从高到低）**： - -```bash -# 方案 1（推荐）：使用虚拟环境 -python3 -m venv .venv -source .venv/bin/activate -pip install package-name - -# 方案 2：使用 pipx 安装 CLI 工具 -pipx install package-name - -# 方案 3：使用 --user 标志安装到用户目录 -pip install --user package-name - -# 方案 4（不推荐）：强制覆盖（可能破坏系统） -pip install --break-system-packages package-name -``` - -### "node: command not found" - -**排查步骤**： - -```bash -# 检查是否安装 -which node 2>/dev/null -ls /usr/bin/node /usr/local/bin/node 2>/dev/null - -# 检查 nvm 是否已安装但未加载 -[ -s "$HOME/.nvm/nvm.sh" ] && echo "nvm installed but not loaded" - -# 加载 nvm -export NVM_DIR="$HOME/.nvm" -[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" -node --version -``` - -### npm 全局安装权限错误（EACCES） - -**现象**：`npm install -g` 报 "EACCES: permission denied"。 - -**解决方案**（**不要使用 sudo npm**）： - -```bash -# 更改 npm 全局安装目录到用户目录 -mkdir -p ~/.npm-global -npm config set prefix '~/.npm-global' - -# 添加到 PATH -echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc # 或 ~/.bashrc -source ~/.zshrc - -# 现在可以正常全局安装 -npm install -g pptxgenjs -``` - -### SSL/TLS 证书错误 - -**现象**：pip 或 npm 报 SSL 证书验证失败。 - -```bash -# pip：升级 certifi -pip install --upgrade certifi - -# 临时绕过（仅限调试，不要用于生产） -pip install --trusted-host pypi.org --trusted-host pypi.python.org package-name - -# npm：检查代理设置 -npm config get proxy -npm config get https-proxy -npm config delete proxy -npm config delete https-proxy -``` - -### Python 包安装后 import 失败 - -**常见原因和排查**： - -```bash -# 1. 检查是否安装在正确的 Python 版本下 -python3 -c "import sys; print(sys.executable)" -pip3 show package-name - -# 2. 检查是否在虚拟环境中 -echo "$VIRTUAL_ENV" - -# 3. 检查包名与 import 名不一致 -# 安装名 → import 名（常见差异）： -# Pillow → PIL -# python-dateutil → dateutil -# beautifulsoup4 → bs4 -# scikit-learn → sklearn -# markitdown → markitdown -# pypdf → pypdf - -# 4. 重新安装 -pip install --force-reinstall package-name -``` - -### macOS "xcrun: error" 或编译失败 - -**现象**：安装需要 C 扩展的包（如 lxml、numpy）时编译失败。 - -```bash -# 安装 Xcode Command Line Tools -xcode-select --install - -# 如果已安装但仍报错，重置 -sudo xcode-select --reset - -# 对于特定包，安装系统依赖 -# lxml: -brew install libxml2 libxslt -# Pillow: -brew install libjpeg zlib -``` - -### Windows PowerShell 执行策略阻止脚本 - -**现象**：无法激活虚拟环境或运行 npm 脚本。 - -```powershell -# 查看当前策略 -Get-ExecutionPolicy - -# 设置为 RemoteSigned（推荐） -Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -``` - -### 代理环境下的配置 - -```bash -# pip 代理配置 -pip install --proxy http://proxy:port package-name -# 或永久配置 -pip config set global.proxy http://proxy:port - -# npm 代理配置 -npm config set proxy http://proxy:port -npm config set https-proxy http://proxy:port - -# Git 代理（部分安装脚本需要 Git） -git config --global http.proxy http://proxy:port -git config --global https.proxy http://proxy:port -``` - ---- - -## 办公技能依赖速查 - -以下是 DesireCore 办公四件套技能所需的依赖汇总： - -### 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 转图片 -``` - -### 一键安装所有办公技能依赖 - -```bash -# Python 包（全部） -pip install lxml defusedxml pypdf pdfplumber Pillow reportlab openpyxl pandas "markitdown[pptx]" - -# Node.js 包（全部） -npm install -g docx pptxgenjs -``` - ---- - -## 容器运行环境（Docker / Podman） - -容器环境在开发中越来越常见，许多工具和服务（数据库、消息队列、AI 推理服务等）通过容器部署最为便捷。 - -### 检测容器环境 - -```bash -# Docker -docker --version 2>/dev/null && docker info --format '{{.OperatingSystem}}' 2>/dev/null || echo "Docker NOT FOUND or not running" - -# Podman（Docker 的无守护进程替代品） -podman --version 2>/dev/null || echo "Podman NOT FOUND" -``` - -### Docker 安装 - -#### macOS - -推荐使用 Docker Desktop（包含 Docker Engine + Docker Compose + GUI）： - -```bash -# 方式 1：Homebrew Cask（推荐） -brew install --cask docker - -# 安装后启动 Docker Desktop 应用 -# 首次启动需要授权特权访问 - -# 方式 2：从官网下载 -# https://www.docker.com/products/docker-desktop/ -# 选择 Apple Silicon (M1/M2/M3) 或 Intel 版本 -``` - -安装后验证： -```bash -docker --version -docker run hello-world -``` - -#### Windows - -**推荐 Docker Desktop + WSL2 后端**（需要先安装 WSL2，见下方 WSL2 章节）： - -1. 下载 [Docker Desktop for Windows](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 安装 -winget install Docker.DockerDesktop -``` - -验证： -```powershell -docker --version -docker run hello-world -``` - -**不需要 Docker Desktop 的轻量方案**（仅 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 使用 Docker -sudo usermod -aG docker $USER -newgrp docker - -# 验证 -docker --version -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 替代品，无守护进程） - -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 几乎一致（将 `docker` 替换为 `podman`）： -```bash -podman run hello-world -podman ps -podman images -``` - -### Docker 常见问题 - -**"Cannot connect to the Docker daemon"**： -```bash -# Linux：启动 Docker 服务 -sudo systemctl start docker - -# macOS/Windows：确保 Docker Desktop 正在运行 - -# WSL2：可能需要重启 Docker Desktop -``` - -**"permission denied while trying to connect to the Docker daemon socket"**： -```bash -# 将当前用户加入 docker 组 -sudo usermod -aG docker $USER -# 重新登录（或执行 newgrp docker） -``` - -**Docker Desktop 占用资源过高**： -在 Docker Desktop Settings → Resources 中调整 CPU 和内存限制。WSL2 后端用户也可编辑 `~/.wslconfig`： -```ini -[wsl2] -memory=4GB -processors=2 -``` - ---- - -## WSL2 安装与配置（仅 Windows） - -WSL2（Windows Subsystem for Linux 2）让 Windows 用户可以原生运行 Linux 环境，是运行 Python 脚本、Docker、以及各种开发工具的最佳方式。 - -### 检测 WSL2 - -```powershell -# 检查 WSL 是否已安装 -wsl --status - -# 查看已安装的 Linux 发行版 -wsl --list --verbose -``` - -### 系统要求 - -- Windows 11（21H2 或更高）或 Windows 10（版本 2004，Build 19041 或更高） -- CPU 虚拟化已启用（BIOS 中的 Intel VT-x / AMD-V） - -### 安装 WSL2 - -```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（而非 WSL1） - -```powershell -# 查看当前版本 -wsl --list --verbose -# 输出中 VERSION 列应为 2 - -# 如果显示为 1，升级到 WSL2 -wsl --set-version Ubuntu 2 - -# 将 WSL2 设为未来安装的默认版本 -wsl --set-default-version 2 -``` - -### WSL2 中配置开发环境 - -进入 WSL2 后，按 Linux 方式配置即可（参考上方的 Python/Node.js/Docker Linux 安装章节）： - -```bash -# 进入 WSL2 -wsl - -# 更新系统 -sudo apt update && sudo apt upgrade -y - -# 安装 Python -sudo apt install python3 python3-pip python3-venv - -# 安装 Node.js -curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - -sudo apt install nodejs - -# 安装 Docker（推荐使用 Docker Desktop 的 WSL2 后端，而非在 WSL2 内安装） -``` - -### WSL2 与 Windows 文件互访 - -```bash -# 在 WSL2 中访问 Windows 文件 -ls /mnt/c/Users/你的用户名/Desktop/ - -# 在 Windows 中访问 WSL2 文件（资源管理器地址栏） -# \\wsl$\Ubuntu\home\你的用户名\ - -# 在 Windows Terminal 中打开 WSL2 -wsl ~ -``` - -### WSL2 常见问题 - -**"WslRegisterDistribution failed with error: 0x80370102"**： -CPU 虚拟化未启用。重启计算机进入 BIOS，启用 Intel VT-x 或 AMD-V。 - -**WSL2 网络问题（无法访问互联网）**： -```bash -# 在 WSL2 中 -echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf -``` - -**WSL2 磁盘空间不足**： -```powershell -# 压缩 WSL2 虚拟磁盘 -wsl --shutdown -# 使用 diskpart 压缩 ext4.vhdx（高级操作，请备份后再执行） -``` - -**DesireCore Windows 用户建议**：DesireCore 的环境检查功能（设置 → 环境检查）可以自动检测 Windows 版本、CPU 虚拟化、WSL2 安装状态，并提供一键修复。 - ---- - -## 系统工具安装 - -### LibreOffice - -办公技能用于文档格式转换和公式重算。 - -```bash -# macOS -brew install --cask libreoffice - -# Ubuntu/Debian -sudo apt install libreoffice - -# Fedora/RHEL -sudo dnf install libreoffice - -# Windows -winget install TheDocumentFoundation.LibreOffice -``` - -### Poppler（PDF 工具集） - -提供 `pdftotext`、`pdftoppm`、`pdfimages` 等命令。 - -```bash -# macOS -brew install poppler - -# Ubuntu/Debian -sudo apt install poppler-utils - -# Fedora/RHEL -sudo dnf install poppler-utils - -# Windows（通过 conda 或手动下载） -conda install -c conda-forge poppler -``` - -### Pandoc（文档格式转换） - -```bash -# macOS -brew install pandoc - -# Ubuntu/Debian -sudo apt install pandoc - -# Fedora/RHEL -sudo dnf install pandoc - -# Windows -winget install JohnMacFarlane.Pandoc -``` - -### Tesseract（OCR 引擎） - -```bash -# macOS -brew install tesseract - -# Ubuntu/Debian -sudo apt install tesseract-ocr - -# Fedora/RHEL -sudo dnf install tesseract - -# 安装中文语言包 -# macOS: -brew install tesseract-lang -# Ubuntu/Debian: -sudo apt install tesseract-ocr-chi-sim tesseract-ocr-chi-tra -``` - ---- - -## 环境验证脚本 - -一键检查所有办公技能所需的环境是否就绪： - -```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 -c " -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}') -" 2>/dev/null || echo "Cannot check packages (Python not available)" - -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 -``` - -将上述脚本保存为 `check-env.sh`，运行 `bash check-env.sh` 即可查看完整的环境状态。 diff --git a/skills/nodejs-runtime/SKILL.md b/skills/nodejs-runtime/SKILL.md new file mode 100644 index 0000000..91106ea --- /dev/null +++ b/skills/nodejs-runtime/SKILL.md @@ -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: >- + + 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` diff --git a/skills/nodejs-runtime/references/nvm-fallback.md b/skills/nodejs-runtime/references/nvm-fallback.md new file mode 100644 index 0000000..4c01308 --- /dev/null +++ b/skills/nodejs-runtime/references/nvm-fallback.md @@ -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 安装包 | diff --git a/skills/nodejs-runtime/references/package-managers.md b/skills/nodejs-runtime/references/package-managers.md new file mode 100644 index 0000000..a85d1d0 --- /dev/null +++ b/skills/nodejs-runtime/references/package-managers.md @@ -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 即可判断是否需要切换镜像。 diff --git a/skills/nodejs-runtime/references/troubleshooting.md b/skills/nodejs-runtime/references/troubleshooting.md new file mode 100644 index 0000000..2af1429 --- /dev/null +++ b/skills/nodejs-runtime/references/troubleshooting.md @@ -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 ` 报 `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/ 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 +``` diff --git a/skills/nodejs-runtime/references/volta-desirecore.md b/skills/nodejs-runtime/references/volta-desirecore.md new file mode 100644 index 0000000..f7cf642 --- /dev/null +++ b/skills/nodejs-runtime/references/volta-desirecore.md @@ -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/ +``` + +或： +```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 在最前 | diff --git a/skills/nodejs-runtime/scripts/probe-node.sh b/skills/nodejs-runtime/scripts/probe-node.sh new file mode 100755 index 0000000..2cecc63 --- /dev/null +++ b/skills/nodejs-runtime/scripts/probe-node.sh @@ -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 </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 包依赖 diff --git a/skills/pptx/SKILL.md b/skills/pptx/SKILL.md index 940c6c5..c089ef6 100644 --- a/skills/pptx/SKILL.md +++ b/skills/pptx/SKILL.md @@ -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 包依赖 diff --git a/skills/python-runtime/SKILL.md b/skills/python-runtime/SKILL.md new file mode 100644 index 0000000..a0832c8 --- /dev/null +++ b/skills/python-runtime/SKILL.md @@ -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: >- + + 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` diff --git a/skills/python-runtime/references/hatch-desirecore.md b/skills/python-runtime/references/hatch-desirecore.md new file mode 100644 index 0000000..41d5402 --- /dev/null +++ b/skills/python-runtime/references/hatch-desirecore.md @@ -0,0 +1,147 @@ +# DesireCore 内置 Hatch（L1 / L2 主路径） + +DesireCore 内置 [Hatch](https://hatch.pypa.io/) v1.16.5。Hatch 二进制随应用打包于 `static/hatch/`，运行时位于 `~/.desirecore/runtime/hatch/`，**用户无需单独安装**。 + +> 与系统 Python 完全隔离：Hatch 安装的 Python 位于 `~/.desirecore/runtime/hatch/local//`，不修改系统 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` | diff --git a/skills/python-runtime/references/pyenv-fallback.md b/skills/python-runtime/references/pyenv-fallback.md new file mode 100644 index 0000000..479dfcd --- /dev/null +++ b/skills/python-runtime/references/pyenv-fallback.md @@ -0,0 +1,97 @@ +# pyenv（L4 社区方案） + +仅在以下情况启用： +1. 用户明确要求 pyenv（"用 pyenv 装"） +2. 项目根目录已有 `.python-version` 文件 +3. L1 (HTTP API) / L2 (Hatch CLI) / L3 (系统包管理器) 全部失败 + +如条件不满足，**不要**主动建议 pyenv——优先 DesireCore Hatch。 + +## 安装 pyenv + +### macOS / Linux + +```bash +curl https://pyenv.run | bash + +# zsh +cat >> ~/.zshrc <<'EOF' +export PYENV_ROOT="$HOME/.pyenv" +[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH" +eval "$(pyenv init -)" +EOF + +# bash +cat >> ~/.bashrc <<'EOF' +export PYENV_ROOT="$HOME/.pyenv" +[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH" +eval "$(pyenv init -)" +EOF + +exec "$SHELL" +``` + +#### 编译依赖 + +| 平台 | 命令 | +|------|------| +| macOS | `brew install openssl readline sqlite3 xz zlib tcl-tk` | +| Ubuntu/Debian | `sudo apt install build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev curl git libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev` | +| Fedora/RHEL | `sudo dnf install gcc make zlib-devel bzip2 bzip2-devel readline-devel sqlite sqlite-devel openssl-devel tk-devel libffi-devel xz-devel` | + +### Windows（pyenv-win） + +```powershell +pip install pyenv-win --target "$HOME\.pyenv" +# 或 +Invoke-WebRequest -UseBasicParsing -Uri "https://raw.githubusercontent.com/pyenv-win/pyenv-win/master/pyenv-win/install-pyenv-win.ps1" -OutFile "./install-pyenv-win.ps1"; & "./install-pyenv-win.ps1" +``` + +环境变量： +```powershell +[System.Environment]::SetEnvironmentVariable('PYENV', "$HOME\.pyenv\pyenv-win", 'User') +[System.Environment]::SetEnvironmentVariable('PYENV_HOME', "$HOME\.pyenv\pyenv-win", 'User') +# 然后把 %PYENV%\bin 和 %PYENV%\shims 加入 PATH +``` + +## 使用 pyenv + +```bash +# 列出可装版本 +pyenv install --list | grep "^ 3\." + +# 安装 +pyenv install 3.12.4 +pyenv install 3.11.9 + +# 全局默认 +pyenv global 3.12.4 + +# 项目级（生成 .python-version） +pyenv local 3.11.9 + +# 已装版本 +pyenv versions + +# 当前激活 +pyenv version + +# 卸载 +pyenv uninstall 3.10.14 +``` + +## 镜像加速 + +```bash +export PYTHON_BUILD_MIRROR_URL="https://npmmirror.com/mirrors/python/" +pyenv install 3.12.4 +``` + +## pyenv 常见问题 + +| 现象 | 排查 | +|------|------| +| `pyenv: command not found` | shell 配置未加载，`exec "$SHELL"` 或重启终端 | +| 编译时 `ModuleNotFoundError: _ssl` | 缺 `libssl-dev` / `openssl`，按上方编译依赖安装 | +| macOS Big Sur 编译失败 | `LDFLAGS="-L$(brew --prefix openssl)/lib" CPPFLAGS="-I$(brew --prefix openssl)/include" pyenv install 3.12.4` | +| Windows pyenv 切换无效 | 检查 PATH 中 `%PYENV%\shims` 是否在系统 Python 之前 | diff --git a/skills/python-runtime/references/troubleshooting.md b/skills/python-runtime/references/troubleshooting.md new file mode 100644 index 0000000..a1cd732 --- /dev/null +++ b/skills/python-runtime/references/troubleshooting.md @@ -0,0 +1,178 @@ +# Python 故障排查 + +## "python: command not found" / "python3: command not found" + +**原因**：未安装或未加入 PATH。 + +```bash +# 1. 找一下二进制 +which python3 2>/dev/null; which python 2>/dev/null +ls /usr/bin/python* /usr/local/bin/python* /opt/homebrew/bin/python* 2>/dev/null + +# 2. 查 PATH +echo "$PATH" | tr ':' '\n' | head -20 + +# 3. macOS：检查 Homebrew Python +brew list python 2>/dev/null && echo "Homebrew Python installed" + +# 4. 修复 PATH +# Apple Silicon +export PATH="/opt/homebrew/bin:$PATH" +# Intel mac / Linux 常见 +export PATH="/usr/local/bin:$PATH" +``` + +**根治**：按主 SKILL.md 决策树重新执行 L1–L3 安装路径。 + +## "pip: command not found" + +```bash +# 用 module 模式调用 +python3 -m pip --version + +# 仍失败：手动 bootstrap +curl -fsSL https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py +python3 /tmp/get-pip.py --user +rm /tmp/get-pip.py + +# 把 ~/.local/bin 加入 PATH（zsh / bash） +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc +source ~/.zshrc +``` + +## "externally-managed-environment"（PEP 668） + +**触发系统**：Debian 12+、Ubuntu 23.04+、Fedora 38+、Arch（部分）。 + +**优先级从高到低**： + +```bash +# 方案 1（推荐）：虚拟环境 +python3 -m venv .venv +source .venv/bin/activate +pip install package-name + +# 方案 2：pipx 装 CLI 工具 +pipx install package-name + +# 方案 3：用户目录 +pip install --user package-name + +# 方案 4（不推荐，可能破坏系统） +pip install --break-system-packages package-name +``` + +## SSL / TLS 证书错误 + +```bash +# pip：升级 certifi +pip install --upgrade certifi + +# 临时绕过（仅调试） +pip install --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org package-name + +# 永久信任（不推荐） +pip config set global.trusted-host "pypi.org files.pythonhosted.org" +``` + +macOS 系统时间偏差也会导致 SSL 失败：`sudo sntp -sS time.apple.com`。 + +## import 失败 + +包名 ≠ import 名是最常见原因： + +| 安装名 (pip install) | import 名 | +|----------------------|-----------| +| Pillow | PIL | +| python-dateutil | dateutil | +| beautifulsoup4 | bs4 | +| scikit-learn | sklearn | +| PyYAML | yaml | +| pytorch | torch | + +```bash +# 1. 确认安装到了正确的 Python +python3 -c "import sys; print(sys.executable)" +pip3 show package-name + +# 2. 是否在虚拟环境 +echo "$VIRTUAL_ENV" + +# 3. 强制重装 +pip install --force-reinstall --no-cache-dir package-name +``` + +## macOS "xcrun: error" / 编译失败 + +安装 lxml / numpy / Pillow 等需要 C 扩展的包时： + +```bash +# 安装 / 重置 Xcode CLI +xcode-select --install +sudo xcode-select --reset + +# 包级依赖 +brew install libxml2 libxslt # lxml +brew install libjpeg zlib # Pillow +brew install openssl readline # cryptography 类 +``` + +## Windows PowerShell 执行策略 + +```powershell +Get-ExecutionPolicy +Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser +``` + +之后才能 `.\.venv\Scripts\Activate.ps1`。 + +## Windows Store 占位符 + +`python --version` 弹出 Store 页面： + +1. 设置 → 应用 → 高级应用设置 → 应用执行别名 +2. 关闭 `python.exe` / `python3.exe` 的 Store 别名 +3. 重启终端 + +## 代理环境配置 + +```bash +# pip +pip install --proxy http://proxy:port package-name +pip config set global.proxy http://proxy:port + +# 取消 +pip config unset global.proxy + +# 系统级（zsh / bash） +export http_proxy=http://proxy:port +export https_proxy=http://proxy:port +``` + +## EnvironmentSnapshot 信号速查 + +probe-python.sh 输出后，按字段快速判断： + +| 字段 | 期望 | 失败原因 | +|------|------|----------| +| `system_python.version` | 非空且 ≥ 3.8 | 未装 Python 或版本太低 | +| `system_pip.version` | 非空 | pip 未装（macOS Apple 自带 Python 没有 pip） | +| `hatch_path` | 非空 | DesireCore Hatch 未释放，调 `POST /api/runtime/hatch/install` | +| `pep668: true` | — | 系统 Python 受保护，必须 venv/pipx | +| `active_venv` | 操作前为空，激活后非空 | venv 未生效，重新 `source .venv/bin/activate` | + +## 重置整个 Python 环境（最后手段） + +```bash +# 1. 退出所有虚拟环境 +deactivate 2>/dev/null +conda deactivate 2>/dev/null + +# 2. 删除可疑虚拟环境 +rm -rf .venv venv + +# 3. 重新探测 +bash skills/python-runtime/scripts/probe-python.sh + +# 4. 按主 SKILL.md 决策树重新安装 +``` diff --git a/skills/python-runtime/references/virtualenv.md b/skills/python-runtime/references/virtualenv.md new file mode 100644 index 0000000..f9d866c --- /dev/null +++ b/skills/python-runtime/references/virtualenv.md @@ -0,0 +1,145 @@ +# Python 虚拟环境 + +虚拟环境隔离项目依赖，避免污染全局环境。**强烈建议每个项目独立 venv**。 + +## venv（标准库，首选） + +```bash +# 创建（Python 3.3+ 自带） +python3 -m venv .venv + +# 激活 +# macOS / Linux: +source .venv/bin/activate +# Windows CMD: +.venv\Scripts\activate.bat +# Windows PowerShell: +.venv\Scripts\Activate.ps1 + +# 验证（路径应指向 .venv） +which python # macOS / Linux +where python # Windows + +# 安装依赖 +pip install -r requirements.txt + +# 退出 +deactivate +``` + +### 用 Hatch 安装的 Python 创建 venv + +```bash +~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 -m venv .venv +source .venv/bin/activate +``` + +## pipx（全局 CLI 工具） + +`pipx` 把每个 CLI 工具装在独立 venv 里，对外暴露 shim，不污染系统/项目 Python。 + +```bash +# 安装 pipx +brew install pipx # macOS +sudo apt install pipx # Ubuntu/Debian +pip install --user pipx # 通用兜底 +pipx ensurepath +exec "$SHELL" + +# 安装 CLI 工具 +pipx install black +pipx install ruff +pipx install markitdown +pipx install poetry +pipx install uv + +# 升级 +pipx upgrade-all + +# 卸载 +pipx uninstall black + +# 列表 +pipx list +``` + +适用场景：black / ruff / mypy / poetry / uv / markitdown 等命令行工具。 + +## conda / miniconda（数据科学） + +适用于：需要 BLAS / CUDA / 非 Python 依赖（科学计算）。 + +```bash +# 安装 miniconda（macOS / Linux） +curl -fsSL "https://repo.anaconda.com/miniconda/Miniconda3-latest-$(uname -s)-$(uname -m).sh" -o miniconda.sh +bash miniconda.sh -b -p "$HOME/miniconda3" +eval "$("$HOME/miniconda3/bin/conda" shell.$(basename $SHELL) hook)" + +# Windows: 下载 https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe 安装 + +# 创建环境 +conda create -n myproject python=3.12 +conda activate myproject + +# 装包（conda 优先，pip 兜底） +conda install numpy pandas scikit-learn +pip install some-pypi-only-package + +# 导出 / 还原 +conda env export > environment.yml +conda env create -f environment.yml + +# 退出 +conda deactivate +``` + +### conda 与 DesireCore Hatch 共存 + +两者都把 Python 装在用户目录，互不影响。规则： +- 数据科学项目（涉及 numpy/pandas/jupyter/CUDA）→ conda +- 普通 Web/CLI/办公技能 → Hatch + venv + +## requirements.txt 与 pyproject.toml + +### requirements.txt（简单） + +``` +fastapi==0.111.0 +pydantic>=2.0,<3.0 +markitdown +``` + +### pyproject.toml（现代） + +```toml +[project] +name = "myproj" +version = "0.1.0" +requires-python = ">=3.10" +dependencies = [ + "fastapi>=0.111", + "pydantic>=2.0,<3.0", +] + +[project.optional-dependencies] +dev = ["pytest", "ruff", "mypy"] +``` + +安装：`pip install -e .` 或 `pip install -e ".[dev]"`。 + +## 何时用哪个 + +| 场景 | 工具 | +|------|------| +| 普通 Python 项目 | venv + pip | +| 全局 CLI 工具（black/ruff/markitdown） | pipx | +| 数据科学 / Jupyter / CUDA | conda | +| 现代项目管理（含构建发布） | Hatch（自带项目管理）或 uv | +| 严格隔离 / 多 Python 版本快速切换 | DesireCore Hatch + venv | + +## 常见误区 + +- ❌ `sudo pip install` —— 永远不要这样做 +- ❌ 在系统 Python 上直接 `pip install` —— PEP 668 会拒绝 +- ❌ 多个虚拟环境工具同时激活（venv + conda 嵌套）—— 路径会乱 +- ❌ 把 venv 加入 git —— `.venv/` 应该在 `.gitignore` 里 diff --git a/skills/python-runtime/scripts/probe-python.sh b/skills/python-runtime/scripts/probe-python.sh new file mode 100755 index 0000000..bd58700 --- /dev/null +++ b/skills/python-runtime/scripts/probe-python.sh @@ -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 </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 包依赖