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 包依赖