mirror of
https://git.openapi.site/https://github.com/desirecore/market.git
synced 2026-06-06 09:10:41 +08:00
feat: 拆分 environment-setup 为 Python/Node.js 运行时双核心 + 父级路由
新增双核心 skill（深度集成 DesireCore Hatch/Volta + HTTP API + Socket.IO）： - python-runtime v1.0.1：Python 运行时管理 · 四级降级：HTTP API → Hatch CLI 绝对路径 → 系统包管理器 → pyenv · references：hatch-desirecore / pyenv-fallback / virtualenv / troubleshooting · scripts/probe-python.sh：输出 JSON 快照供 Claude 解析决策 - nodejs-runtime v1.0.1：Node.js 运行时管理 · 四级降级：HTTP API → Volta CLI → 系统包管理器/NodeSource → nvm/fnm · references：volta-desirecore / nvm-fallback / package-managers / troubleshooting · scripts/probe-node.sh：输出 JSON 快照（含 volta_tools / package_json_volta 等） environment-setup → dev-environment-setup v2.0.1（重命名 + 重写为 router）： - 从 1380 行手册瘦身为 ~150 行索引 - 仅负责容器（Docker/Podman）/ WSL2 / 办公依赖速查 / 系统工具 - references/desirecore-runtime.md 沉淀 Hatch/Volta 路径表 + HTTP API 速查 + Socket.IO 事件契约，作为两个核心 skill 的共享底座 - references/decision-tree.md 定义四级降级决策树 - scripts/probe.sh + probe.ps1 系统级 JSON 探测 三个 SKILL.md 的 L0 改为场景驱动结构（何时使用 / 何时不要用 / 怎么做）， 让 AI 凭名字与 L0 即可判断匹配场景。 注册更新： - builtin-skills.json：新增 python-runtime / nodejs-runtime / dev-environment-setup （原 environment-setup 移除），按字母序，共 21 个 skill - manifest.json：totalSkills 19→21，lastUpdated 2026-05-02 下游同步： - docx / pdf / xlsx / pptx 中的环境引用从 environment-setup 拆分为 python-runtime / nodejs-runtime / dev-environment-setup 三向指引 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
159
skills/dev-environment-setup/SKILL.md
Normal file
159
skills/dev-environment-setup/SKILL.md
Normal file
@@ -0,0 +1,159 @@
|
||||
---
|
||||
name: 开发环境综合配置
|
||||
description: >-
|
||||
Use this skill as a router/index when the user faces a development
|
||||
environment question that spans multiple domains: containers
|
||||
(Docker/Podman), WSL2 on Windows, office-skill dependencies (DOCX/PDF/XLSX/
|
||||
PPTX), or system tools (LibreOffice/Poppler/Pandoc/Tesseract). For pure
|
||||
Python issues use python-runtime skill; for pure Node.js issues use
|
||||
nodejs-runtime skill. Triggers include: "setup environment", "PATH",
|
||||
"WSL", "WSL2", "docker not found", "podman", "container", "office
|
||||
dependency", "LibreOffice", "poppler", "pandoc", "tesseract", or any
|
||||
cross-cutting environment question. 使用场景：用户提到 环境配置、PATH、
|
||||
容器、Docker、Podman、WSL、WSL2、办公依赖、系统工具，或不确定属于 Python /
|
||||
Node.js 时的入口指引。
|
||||
version: 2.0.1
|
||||
type: procedural
|
||||
risk_level: low
|
||||
status: enabled
|
||||
disable-model-invocation: true
|
||||
tags:
|
||||
- environment
|
||||
- docker
|
||||
- container
|
||||
- wsl
|
||||
- office
|
||||
- system-tools
|
||||
- router
|
||||
metadata:
|
||||
author: desirecore
|
||||
updated_at: '2026-05-02'
|
||||
market:
|
||||
icon: >-
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0
|
||||
24 24" fill="none"><defs><linearGradient id="env-a" x1="3" y1="3" x2="21"
|
||||
y2="21" gradientUnits="userSpaceOnUse"><stop stop-color="#34C759"/><stop
|
||||
offset="1" stop-color="#007AFF"/></linearGradient></defs><rect x="3" y="3"
|
||||
width="18" height="18" rx="3" fill="url(#env-a)" fill-opacity="0.1"
|
||||
stroke="url(#env-a)" stroke-width="1.5"/><path d="M7 8l3 3-3 3"
|
||||
stroke="url(#env-a)" stroke-width="1.5" stroke-linecap="round"
|
||||
stroke-linejoin="round"/><path d="M13 16h4" stroke="url(#env-a)"
|
||||
stroke-width="1.5" stroke-linecap="round"/></svg>
|
||||
short_desc: 开发环境综合入口（容器 / WSL / 办公依赖 / 系统工具）
|
||||
category: productivity
|
||||
maintainer:
|
||||
name: DesireCore Official
|
||||
verified: true
|
||||
channel: latest
|
||||
---
|
||||
|
||||
# dev-environment-setup 技能（v2.0.0 router）
|
||||
|
||||
## L0：一句话摘要
|
||||
|
||||
**何时使用**：用户需要
|
||||
|
||||
- 安装 / 排查 **Docker** 或 **Podman** 容器（"docker not found"、daemon 启动、镜像加速等）
|
||||
- 在 Windows 上配置 **WSL2**（Linux 子系统）
|
||||
- 一次性安装 **办公技能依赖**（DOCX / PDF / XLSX / PPTX 所需的 Python 包 + npm 包 + 系统工具）
|
||||
- 安装 **系统工具**：LibreOffice / Poppler / Pandoc / Tesseract / qpdf / ImageMagick / Ghostscript / Git
|
||||
- **不确定** 问题属于 Python 还是 Node.js，需要先做综合诊断
|
||||
|
||||
**何时不要用**：纯 Python 问题用 `python-runtime`，纯 Node.js 问题用 `nodejs-runtime`。
|
||||
|
||||
**怎么做**：先跑 `scripts/probe.sh`（Windows 用 `probe.ps1`）取系统快照 JSON，
|
||||
按结果路由到对应 references 或子 skill；同时也是 DesireCore 内置 Hatch / Volta /
|
||||
HTTP API / Socket.IO 集成的事实源（`references/desirecore-runtime.md`）。
|
||||
|
||||
## L1：路由规则
|
||||
|
||||
按用户问题的关键字直接转到对应 skill 或文档：
|
||||
|
||||
| 关键字 / 场景 | 路径 |
|
||||
|--------------|------|
|
||||
| python / pip / venv / pyenv / hatch / virtualenv / PEP 668 | `python-runtime` skill |
|
||||
| node / npm / pnpm / yarn / volta / nvm / fnm / EACCES | `nodejs-runtime` skill |
|
||||
| docker / podman / container / 容器守护进程 | `references/container.md` |
|
||||
| WSL / WSL2 / Windows Linux 子系统 | `references/wsl.md` |
|
||||
| DOCX / PDF / XLSX / PPTX 依赖 / 办公技能依赖 | `references/office-deps.md` |
|
||||
| LibreOffice / poppler / pandoc / tesseract / qpdf | `references/system-tools.md` |
|
||||
| 不确定属于哪类、想要快速诊断 | 先跑 `scripts/probe.sh` 看 JSON |
|
||||
| DesireCore Hatch / Volta / HTTP API / Socket.IO | `references/desirecore-runtime.md` |
|
||||
| 四级降级决策（API → CLI → 包管理器 → 社区方案） | `references/decision-tree.md` |
|
||||
|
||||
## L2：详细规范
|
||||
|
||||
### 第一步：快速诊断
|
||||
|
||||
```bash
|
||||
bash skills/dev-environment-setup/scripts/probe.sh > /tmp/env-probe.json
|
||||
cat /tmp/env-probe.json | jq .
|
||||
```
|
||||
|
||||
输出字段含义：见 `references/probe-snapshot.md`。Windows 用 `scripts/probe.ps1`。
|
||||
|
||||
### 第二步：按结果路由
|
||||
|
||||
- `desirecore_api` 非空 → 走 HTTP API 路径（`references/desirecore-runtime.md`）
|
||||
- `tools.python3.available = false` 或 `tools.node.available = false` → 进入对应子 skill
|
||||
- `tools.docker.available = false` 且用户需容器 → `references/container.md`
|
||||
- `wsl.installed = false` 且 Windows 用户 → `references/wsl.md`
|
||||
|
||||
### 第三步：执行子 skill 决策树
|
||||
|
||||
`python-runtime` 与 `nodejs-runtime` 都有自己的四级降级（L1 API → L2 内置 CLI → L3 系统包管理器 → L4 社区方案），定义在共享的 `references/decision-tree.md`。
|
||||
|
||||
### 第四步：办公技能依赖
|
||||
|
||||
办公四件套（DOCX / PDF / XLSX / PPTX）依赖速查：`references/office-deps.md`。包含 Python 包、npm 包、系统工具的一键安装命令。
|
||||
|
||||
### 第五步：系统工具
|
||||
|
||||
LibreOffice / Poppler / Pandoc / Tesseract / qpdf / ImageMagick / Ghostscript 安装与故障排查：`references/system-tools.md`。
|
||||
|
||||
## DesireCore 内置环境管理底座
|
||||
|
||||
DesireCore 内置 Hatch（Python）和 Volta（Node.js），通过 HTTP API + Socket.IO 提供完整的环境管理能力。本 skill 与子 skill（python/nodejs）都依赖：
|
||||
|
||||
| 文档 | 内容 |
|
||||
|------|------|
|
||||
| `references/desirecore-runtime.md` | 二进制路径表、HTTP API 速查、Socket.IO 事件契约、`EnvironmentSnapshot` 数据结构 |
|
||||
| `references/decision-tree.md` | 四级降级流程图、判定失败的具体信号、切换提示 |
|
||||
| `references/probe-snapshot.md` | 探测脚本 JSON 输出协议 |
|
||||
|
||||
## 重要约束
|
||||
|
||||
1. **不要把 python / node / pip / npm 强关键词写入本 skill description**——这些归属各自的子 skill，避免触发冲突。
|
||||
2. **API 优先**：`scripts/probe.sh` 第一步检测 `~/.desirecore/agent-service.port`；存在则推荐 HTTP API 路径。
|
||||
3. **缓存协同**：任何安装/移除完成后，调 `POST /api/runtime/environment/refresh` 失效缓存，再发后续 GET。
|
||||
4. **跨平台**：所有命令模板提供 macOS / Linux + Windows（PowerShell）双版本。
|
||||
|
||||
## 子 skill 与文档清单
|
||||
|
||||
```
|
||||
skills/
|
||||
├── python-runtime/ # Python 环境（Hatch 优先）
|
||||
├── nodejs-runtime/ # Node.js 环境（Volta 优先）
|
||||
└── dev-environment-setup/ # 本 skill（综合入口）
|
||||
├── references/
|
||||
│ ├── desirecore-runtime.md
|
||||
│ ├── decision-tree.md
|
||||
│ ├── probe-snapshot.md
|
||||
│ ├── container.md
|
||||
│ ├── wsl.md
|
||||
│ ├── office-deps.md
|
||||
│ └── system-tools.md
|
||||
└── scripts/
|
||||
├── probe.sh
|
||||
└── probe.ps1
|
||||
```
|
||||
|
||||
## 升级说明（v1.x → v2.0.0）
|
||||
|
||||
- v1.x 是单文件 1380 行的全能手册，已拆分。
|
||||
- Python 相关 → `python-runtime`
|
||||
- Node.js 相关 → `nodejs-runtime`
|
||||
- Docker / WSL / 办公依赖 / 系统工具 → 本 skill 的 `references/`
|
||||
- DesireCore Hatch / Volta 从"可选社区方案"升级为强制 L1/L2 主路径
|
||||
|
||||
下游 skill（docx / pdf / xlsx / pptx）应将 "Python 环境问题请参考 dev-environment-setup" 改写为 "Python 环境问题请参考 python-runtime / Node.js 环境问题请参考 nodejs-runtime"。
|
||||
193
skills/dev-environment-setup/references/container.md
Normal file
193
skills/dev-environment-setup/references/container.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# 容器运行环境（Docker / Podman）
|
||||
|
||||
容器在开发中越来越常见——数据库、消息队列、AI 推理服务等多通过容器部署。
|
||||
|
||||
## 检测
|
||||
|
||||
```bash
|
||||
docker --version 2>/dev/null && docker info --format '{{.OperatingSystem}}' 2>/dev/null \
|
||||
|| echo "Docker NOT FOUND or daemon not running"
|
||||
|
||||
podman --version 2>/dev/null || echo "Podman NOT FOUND"
|
||||
```
|
||||
|
||||
## Docker 安装
|
||||
|
||||
### macOS
|
||||
|
||||
推荐 Docker Desktop（含 Docker Engine + Compose + GUI）：
|
||||
|
||||
```bash
|
||||
# 方式 1：Homebrew Cask（推荐）
|
||||
brew install --cask docker
|
||||
|
||||
# 方式 2：官网下载
|
||||
# https://www.docker.com/products/docker-desktop/
|
||||
# 选择 Apple Silicon 或 Intel
|
||||
|
||||
# 验证
|
||||
docker --version
|
||||
docker run hello-world
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
**推荐 Docker Desktop + WSL2 后端**（先装 WSL2，见 `wsl.md`）：
|
||||
|
||||
1. 下载 [Docker Desktop](https://www.docker.com/products/docker-desktop/)
|
||||
2. 安装时勾选 "Use WSL 2 instead of Hyper-V"
|
||||
3. Settings → General 确认 "Use the WSL 2 based engine" 已启用
|
||||
|
||||
```powershell
|
||||
winget install Docker.DockerDesktop
|
||||
docker --version
|
||||
docker run hello-world
|
||||
```
|
||||
|
||||
**轻量替代（仅 CLI，通过 WSL2 内）**：
|
||||
|
||||
```bash
|
||||
# 在 WSL2 Ubuntu 中
|
||||
sudo apt update
|
||||
sudo apt install docker.io docker-compose-v2
|
||||
sudo usermod -aG docker $USER
|
||||
# 重新登录 WSL2 后生效
|
||||
```
|
||||
|
||||
### Linux（Debian / Ubuntu）
|
||||
|
||||
```bash
|
||||
# 安装 Docker Engine（官方仓库）
|
||||
sudo apt update
|
||||
sudo apt install ca-certificates curl
|
||||
sudo install -m 0755 -d /etc/apt/keyrings
|
||||
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
|
||||
sudo chmod a+r /etc/apt/keyrings/docker.asc
|
||||
|
||||
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
|
||||
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
|
||||
|
||||
sudo apt update
|
||||
sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin
|
||||
|
||||
# 免 sudo
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
|
||||
docker run hello-world
|
||||
```
|
||||
|
||||
### Linux（Fedora / RHEL）
|
||||
|
||||
```bash
|
||||
sudo dnf install dnf-plugins-core
|
||||
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
|
||||
sudo dnf install docker-ce docker-ce-cli containerd.io docker-compose-plugin
|
||||
sudo systemctl start docker
|
||||
sudo systemctl enable docker
|
||||
sudo usermod -aG docker $USER
|
||||
```
|
||||
|
||||
## Podman（无守护进程替代）
|
||||
|
||||
兼容 Docker CLI，无后台守护进程，更轻量。
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install podman
|
||||
podman machine init
|
||||
podman machine start
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install podman
|
||||
|
||||
# Fedora（预装）
|
||||
podman --version
|
||||
|
||||
# Windows
|
||||
winget install RedHat.Podman
|
||||
```
|
||||
|
||||
使用方式与 Docker 一致：
|
||||
```bash
|
||||
podman run hello-world
|
||||
podman ps
|
||||
podman images
|
||||
```
|
||||
|
||||
### Docker → Podman 别名
|
||||
|
||||
```bash
|
||||
echo 'alias docker=podman' >> ~/.zshrc
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### "Cannot connect to the Docker daemon"
|
||||
|
||||
```bash
|
||||
# Linux
|
||||
sudo systemctl start docker
|
||||
sudo systemctl enable docker
|
||||
|
||||
# macOS / Windows
|
||||
# 启动 Docker Desktop 应用（系统托盘应有鲸鱼图标）
|
||||
|
||||
# WSL2
|
||||
# 在 Windows 端重启 Docker Desktop
|
||||
```
|
||||
|
||||
### "permission denied while trying to connect to the Docker daemon socket"
|
||||
|
||||
```bash
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker # 当前 shell 立即生效
|
||||
# 或重新登录
|
||||
```
|
||||
|
||||
### Docker Desktop 占用资源过高
|
||||
|
||||
Docker Desktop Settings → Resources 调 CPU / Memory。WSL2 后端可编辑 `~/.wslconfig`：
|
||||
|
||||
```ini
|
||||
[wsl2]
|
||||
memory=4GB
|
||||
processors=2
|
||||
swap=2GB
|
||||
```
|
||||
|
||||
### 镜像下载慢（中国大陆）
|
||||
|
||||
```bash
|
||||
# 编辑 /etc/docker/daemon.json
|
||||
sudo tee /etc/docker/daemon.json <<EOF
|
||||
{
|
||||
"registry-mirrors": [
|
||||
"https://mirror.ccs.tencentyun.com",
|
||||
"https://docker.m.daocloud.io"
|
||||
]
|
||||
}
|
||||
EOF
|
||||
sudo systemctl restart docker
|
||||
```
|
||||
|
||||
macOS / Windows 在 Docker Desktop Settings → Docker Engine 中编辑 JSON。
|
||||
|
||||
### 磁盘空间被吃光
|
||||
|
||||
```bash
|
||||
docker system df # 查用量
|
||||
docker system prune -a # 清未用镜像/容器/网络
|
||||
docker volume prune # 清未挂载 volume（小心！数据会丢）
|
||||
```
|
||||
|
||||
## 容器场景速查
|
||||
|
||||
| 场景 | 镜像 | 启动 |
|
||||
|------|------|------|
|
||||
| Postgres 测试 | `postgres:16` | `docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=test postgres:16` |
|
||||
| Redis | `redis:7` | `docker run -d -p 6379:6379 redis:7` |
|
||||
| MySQL | `mysql:8` | `docker run -d -p 3306:3306 -e MYSQL_ROOT_PASSWORD=test mysql:8` |
|
||||
| MinIO（S3 兼容） | `minio/minio` | `docker run -d -p 9000:9000 -p 9001:9001 minio/minio server /data --console-address :9001` |
|
||||
|
||||
更复杂的场景使用 `docker compose up -d`。
|
||||
163
skills/dev-environment-setup/references/decision-tree.md
Normal file
163
skills/dev-environment-setup/references/decision-tree.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# 环境管理四级降级决策树
|
||||
|
||||
`python-runtime` 与 `nodejs-runtime` 在执行任何安装/版本切换前必须按本决策树选择路径。
|
||||
|
||||
## 总体流程
|
||||
|
||||
```
|
||||
┌──────────────────┐
|
||||
│ 执行 probe 脚本 │
|
||||
└─────────┬────────┘
|
||||
▼
|
||||
┌─────────────────────────────┐
|
||||
│ desirecore_api 字段非空？ │
|
||||
└────────┬───────────────┬─────┘
|
||||
是 │ │ 否
|
||||
▼ ▼
|
||||
┌──────────────────┐ ┌──────────────────┐
|
||||
│ L1：HTTP API 路径 │ │ hatch_path / │
|
||||
└────────┬─────────┘ │ volta_path 非空？ │
|
||||
│ └────────┬──┬──────┘
|
||||
失败/超时 是 │ │ 否
|
||||
▼ ▼ ▼
|
||||
┌──────────────────┐ ┌──────────────────┐
|
||||
│ L2：DesireCore CLI │ │ L3：系统包管理器 │
|
||||
└────────┬─────────┘ └────────┬─────────┘
|
||||
│ │
|
||||
二进制损坏 / 安装失败 失败/不可用
|
||||
▼ ▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ L4：社区方案（pyenv / nvm / fnm / conda）│
|
||||
└─────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## L1：DesireCore HTTP API（最高优先级）
|
||||
|
||||
**触发条件**
|
||||
|
||||
- `~/.desirecore/agent-service.port` 文件存在且可读
|
||||
- `curl -sk --max-time 0.5 https://127.0.0.1:${PORT}/api/runtime/environment` 返回 2xx
|
||||
- 当前会话能订阅 Socket.IO（DesireCore 内部 Agent 默认满足）
|
||||
|
||||
**典型操作**
|
||||
|
||||
```bash
|
||||
PORT=$(cat ~/.desirecore/agent-service.port)
|
||||
BASE="https://127.0.0.1:${PORT}/api/runtime"
|
||||
|
||||
# 1. 拉取快照
|
||||
curl -sk "${BASE}/environment"
|
||||
|
||||
# 2. 触发安装（异步）
|
||||
curl -sk -X POST "${BASE}/python/install" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"version":"3.12"}'
|
||||
|
||||
# 3. 订阅 runtime:terminal / runtime:complete 事件展示日志
|
||||
```
|
||||
|
||||
**判定失败的信号**
|
||||
|
||||
- HTTP 状态码 ≥ 500 或 502（远端镜像不可用，详见 runtime-env-routes.ts 130/162 行）
|
||||
- `runtime:complete` 事件 `success: false`
|
||||
- Socket.IO 连接断开后超过 30 秒未收到 `runtime:complete`
|
||||
|
||||
**切换提示**：API 失败立即降级到 L2 CLI，不要重试同一接口（可能是镜像被墙）。
|
||||
|
||||
## L2：DesireCore 内置 CLI（绝对路径）
|
||||
|
||||
**触发条件**
|
||||
|
||||
- API 不可达或失败
|
||||
- probe 脚本中 `hatch_path` / `volta_path` 字段非空（即二进制存在）
|
||||
|
||||
**典型操作（macOS / Linux）**
|
||||
|
||||
```bash
|
||||
HATCH=~/.desirecore/runtime/hatch/hatch
|
||||
VOLTA=~/.desirecore/runtime/volta/volta
|
||||
|
||||
export HATCH_HOME=~/.desirecore/runtime/hatch
|
||||
export VOLTA_HOME=~/.desirecore/runtime/volta
|
||||
|
||||
"$HATCH" python install 3.12
|
||||
"$VOLTA" install node@22
|
||||
```
|
||||
|
||||
**典型操作（Windows PowerShell）**
|
||||
|
||||
```powershell
|
||||
$Hatch = "$env:USERPROFILE\.desirecore\runtime\hatch\hatch.exe"
|
||||
$Volta = "$env:USERPROFILE\.desirecore\runtime\volta\volta.exe"
|
||||
|
||||
$env:HATCH_HOME = "$env:USERPROFILE\.desirecore\runtime\hatch"
|
||||
$env:VOLTA_HOME = "$env:USERPROFILE\.desirecore\runtime\volta"
|
||||
|
||||
& $Hatch python install 3.12
|
||||
& $Volta install node@22
|
||||
```
|
||||
|
||||
**判定失败的信号**
|
||||
|
||||
- exit code ≠ 0
|
||||
- stderr 包含 `network`、`timeout`、`ENOTFOUND`、`failed to fetch`
|
||||
- 可执行文件被反病毒软件隔离（macOS Gatekeeper / Windows Defender）
|
||||
|
||||
**切换提示**：失败后才考虑 L3，不要在 L2 内重试。
|
||||
|
||||
## L3：系统包管理器
|
||||
|
||||
**触发条件**：DesireCore 二进制全部缺失，或用户明确要求"系统级"安装。
|
||||
|
||||
| 平台 | Python | Node.js |
|
||||
|------|--------|---------|
|
||||
| macOS | `brew install python3` | `brew install node` |
|
||||
| Debian/Ubuntu | `sudo apt install python3 python3-pip python3-venv` | NodeSource 仓库或 `sudo apt install nodejs npm` |
|
||||
| Fedora/RHEL | `sudo dnf install python3 python3-pip` | `sudo dnf install nodejs` |
|
||||
| Arch | `sudo pacman -S python python-pip` | `sudo pacman -S nodejs npm` |
|
||||
| Windows | `winget install Python.Python.3` | `winget install OpenJS.NodeJS.LTS` |
|
||||
|
||||
**判定失败的信号**
|
||||
|
||||
- `command not found`（包管理器自身缺失，如 `brew` 未装）
|
||||
- PEP 668 报错（Linux 新版发行版 `pip install` 全局被拒）→ 见 python-runtime troubleshooting
|
||||
- 权限被拒（缺少 sudo / 非管理员）
|
||||
|
||||
**切换提示**：仅在系统包管理器都失败、并且用户明确希望安装时升级到 L4。
|
||||
|
||||
## L4：社区方案
|
||||
|
||||
仅在以下情况启用：
|
||||
|
||||
1. 用户明确指定（"我要 pyenv"、"用 nvm 装"）
|
||||
2. L1–L3 全部失败
|
||||
3. 项目已经使用社区方案（存在 `.python-version` / `.nvmrc` 文件）
|
||||
|
||||
| 工具 | 用途 | 文档 |
|
||||
|------|------|------|
|
||||
| pyenv / pyenv-win | Python 多版本 | python-runtime/references/pyenv-fallback.md |
|
||||
| nvm / nvm-windows | Node.js 多版本（shell 脚本） | nodejs-runtime/references/nvm-fallback.md |
|
||||
| fnm | Rust 实现的 nvm 替代 | nodejs-runtime/references/nvm-fallback.md |
|
||||
| conda / miniconda | 数据科学场景 | python-runtime/references/virtualenv.md |
|
||||
|
||||
## 何时跳过决策树
|
||||
|
||||
skill 直接执行用户原话——不要走决策树——的情况：
|
||||
|
||||
- 用户明示路径："用 brew 装 python"、"在 .venv 里 pip install xxx"
|
||||
- 用户在 skill 之外手工修改了环境（识别到 `.python-version`、`.nvmrc`、`package.json#volta`）
|
||||
- skill 上下文已经存在激活的虚拟环境（`$VIRTUAL_ENV` 非空）
|
||||
|
||||
## 每次升级版本后
|
||||
|
||||
无论走哪条路径，**安装/移除完成后立即调用**：
|
||||
|
||||
```bash
|
||||
# L1 模式
|
||||
curl -sk -X POST "${BASE}/environment/refresh"
|
||||
|
||||
# L2/L3/L4 模式（强制 probe 输出最新结果）
|
||||
bash <skill>/scripts/probe-{python,node}.sh
|
||||
```
|
||||
|
||||
避免后续判断基于陈旧缓存。
|
||||
169
skills/dev-environment-setup/references/desirecore-runtime.md
Normal file
169
skills/dev-environment-setup/references/desirecore-runtime.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# DesireCore 内置环境管理底座
|
||||
|
||||
DesireCore 内置了完整的开发环境管理基础设施。`python-runtime` 和 `nodejs-runtime` 两个 skill 共用本文档作为事实源。
|
||||
|
||||
## 一、内置工具二进制
|
||||
|
||||
### Hatch（Python 项目与版本管理器，v1.16.5）
|
||||
|
||||
| 平台 | 运行时绝对路径（用户安装版，优先） | 静态打包兜底 |
|
||||
|------|----------------------------------|--------------|
|
||||
| macOS / Linux | `~/.desirecore/runtime/hatch/hatch` | 应用包内 `static/hatch/hatch` |
|
||||
| Windows | `%USERPROFILE%\.desirecore\runtime\hatch\hatch.exe` | 应用包内 `static/hatch/hatch.exe` |
|
||||
|
||||
**Python 版本安装目录**：`~/.desirecore/runtime/hatch/local/<版本>/python/bin/python3`（macOS/Linux），Windows 为 `python.exe`。
|
||||
|
||||
### Volta（Node.js 工具链管理器，v2.0.2）
|
||||
|
||||
| 平台 | 运行时绝对路径 | 静态打包兜底 |
|
||||
|------|----------------|--------------|
|
||||
| macOS / Linux | `~/.desirecore/runtime/volta/volta` | 应用包内 `static/volta/volta` |
|
||||
| Windows | `%USERPROFILE%\.desirecore\runtime\volta\volta.exe` | 应用包内 `static/volta/volta.exe` |
|
||||
|
||||
**Node.js 安装目录**：`~/.desirecore/runtime/volta/tools/image/node/<version>/`，包管理器在 `tools/image/{packages,pnpm,yarn,npm}/`。
|
||||
|
||||
### 优先级规则
|
||||
|
||||
`runtime/` 目录优先于 `static/`。当用户更新过 Hatch/Volta 时，新版本写入 `runtime/`，DesireCore 优先调用之。
|
||||
|
||||
## 二、关键环境变量
|
||||
|
||||
| 变量 | 作用 | 默认/示例 |
|
||||
|------|------|----------|
|
||||
| `HATCH_HOME` | Hatch 工作目录 | `~/.desirecore/runtime/hatch` |
|
||||
| `HATCH_PYTHON_MIRROR_URL` | Python 下载镜像 | 加速节点（中国大陆） |
|
||||
| `VOLTA_HOME` | Volta 工作目录 | `~/.desirecore/runtime/volta` |
|
||||
| `VOLTA_NODE_MIRROR` | Node.js 下载镜像 | `https://npmmirror.com/mirrors/node` |
|
||||
| `VOLTA_FEATURE_PNPM` | 启用 pnpm 管理 | `1` |
|
||||
|
||||
DesireCore 在启动子进程时会自动注入这些变量；外部直接调用绝对路径 CLI 时需手动 export。
|
||||
|
||||
## 三、HTTP API 速查表
|
||||
|
||||
DesireCore agent-service 启动后将端口写入 `~/.desirecore/agent-service.port`。全部接口走 **HTTPS + 自签名证书**（curl 需要 `-k`）。
|
||||
|
||||
```bash
|
||||
PORT=$(cat ~/.desirecore/agent-service.port)
|
||||
BASE="https://127.0.0.1:${PORT}/api/runtime"
|
||||
```
|
||||
|
||||
### 环境检测
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/environment` | 返回完整 `EnvironmentSnapshot`（platform/arch/tools/wsl） |
|
||||
| POST | `/environment/refresh` | 清除进程级缓存并重新检测，返回新快照 |
|
||||
|
||||
### 工具链状态与安装
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/hatch/status` | 检查 Hatch 是否就绪（runtime/static 任一存在即可） |
|
||||
| POST | `/hatch/install` | 下载并安装 Hatch 到 `runtime/hatch/`（同步返回成功/失败） |
|
||||
| GET | `/volta/status` | 检查 Volta 是否就绪 |
|
||||
| POST | `/volta/install` | 下载并安装 Volta 到 `runtime/volta/` |
|
||||
|
||||
### Python 版本管理
|
||||
|
||||
| 方法 | 路径 | 请求体 / 返回 |
|
||||
|------|------|--------------|
|
||||
| GET | `/python/installed` | 返回已安装版本列表（`["3.11", "3.12"]`） |
|
||||
| GET | `/python/available` | 返回可安装版本（依赖 Hatch 元数据） |
|
||||
| POST | `/python/install` | `{ "version": "3.12" }` → `{ "taskId": "uuid" }`，订阅 `runtime:terminal` 流 |
|
||||
| POST | `/python/remove` | `{ "version": "3.11" }` → `{ "taskId": "uuid" }` |
|
||||
|
||||
### Node.js 版本管理
|
||||
|
||||
| 方法 | 路径 | 请求体 / 返回 |
|
||||
|------|------|--------------|
|
||||
| GET | `/node/installed` | 返回已安装版本 |
|
||||
| GET | `/node/available` | 返回可安装版本（远端 nodejs.org/dist 或 GitHub Releases，2h 缓存）；网络失败返回 502 |
|
||||
| POST | `/node/install` | `{ "version": "22" }` → `{ "taskId": "uuid" }` |
|
||||
| POST | `/node/remove` | `{ "version": "22.11.0" }` → `{ "taskId": "uuid" }` |
|
||||
|
||||
### 包管理器（pnpm / yarn / npm）
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/pkg/{tool}/installed` | tool ∈ {pnpm, yarn, npm} |
|
||||
| GET | `/pkg/{tool}/available` | 失败返回 502 |
|
||||
| POST | `/pkg/{tool}/install` | `{ "version": "9" }` → `{ "taskId": "uuid" }` |
|
||||
| POST | `/pkg/{tool}/remove` | `{ "version": "9.0.0" }` → `{ "taskId": "uuid" }` |
|
||||
|
||||
## 四、Socket.IO 实时输出契约
|
||||
|
||||
耗时操作（`*/install`、`*/remove`）立即返回 `{ taskId }`，真正的执行延迟 100ms 启动，期间通过 Socket.IO 推送：
|
||||
|
||||
| 事件 | Payload | 触发时机 |
|
||||
|------|---------|----------|
|
||||
| `runtime:terminal` | `{ taskId, data }` | 每行 stdout/stderr 输出 + 操作开始/结束的状态行 |
|
||||
| `runtime:complete` | `{ taskId, success }` | 任务结束（成功 / 失败 / 异常） |
|
||||
|
||||
**前端订阅时序**：先 HTTP POST 拿 taskId → 再连 Socket.IO 监听该 taskId → 服务端 100ms 后开工。Skill 在无 Socket.IO 客户端时不要走异步 HTTP API（无法收到日志），改用绝对路径 CLI 同步执行。
|
||||
|
||||
## 五、API 可用性探测
|
||||
|
||||
skill 必须先判定 API 是否可达，再决定走 HTTP 还是 CLI：
|
||||
|
||||
```bash
|
||||
PORT_FILE="$HOME/.desirecore/agent-service.port"
|
||||
if [ -r "$PORT_FILE" ]; then
|
||||
PORT=$(cat "$PORT_FILE")
|
||||
if curl -sk --max-time 0.5 "https://127.0.0.1:${PORT}/api/runtime/environment" >/dev/null 2>&1; then
|
||||
DESIRECORE_API="https://127.0.0.1:${PORT}"
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
无 `agent-service.port` 文件、curl 超时（0.5s）、HTTP 非 2xx 一律视为不可达，立即降级到 CLI 路径。
|
||||
|
||||
## 六、EnvironmentSnapshot 数据结构
|
||||
|
||||
`GET /api/runtime/environment` 返回结构（详见 `lib/agent-service/environment-detection.ts`）：
|
||||
|
||||
```ts
|
||||
type ToolDetection = {
|
||||
available: boolean
|
||||
command?: string // 实际命令名（python3 / python）
|
||||
version?: string // 提取后的版本号
|
||||
path?: string // which/where 解析的绝对路径
|
||||
}
|
||||
|
||||
type EnvironmentSnapshot = {
|
||||
platform: 'darwin' | 'win32' | 'linux'
|
||||
arch: string
|
||||
tools: {
|
||||
python: ToolDetection
|
||||
pip: ToolDetection
|
||||
node: ToolDetection
|
||||
npm: ToolDetection
|
||||
docker: ToolDetection
|
||||
podman: ToolDetection
|
||||
git: ToolDetection
|
||||
}
|
||||
wsl?: {
|
||||
installed: boolean
|
||||
version?: string
|
||||
defaultDistro?: string
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 七、缓存与失效
|
||||
|
||||
`detectRuntimeEnvironment()` 使用进程级缓存。当 skill 触发了安装/移除操作后，应立即调用：
|
||||
|
||||
```bash
|
||||
curl -sk -X POST "${DESIRECORE_API}/api/runtime/environment/refresh"
|
||||
```
|
||||
|
||||
强制刷新；否则后续 GET `/environment` 仍返回旧快照。
|
||||
|
||||
## 八、参考源代码
|
||||
|
||||
| 模块 | 文件 | 行数（仓库 ~/Project/desirecore） |
|
||||
|------|------|----------------------------------|
|
||||
| 工具检测 | `lib/agent-service/environment-detection.ts` | 1–310 |
|
||||
| 工具链管理（Hatch/Volta + 版本安装） | `lib/agent-service/runtime-manager.ts` | 1–1165 |
|
||||
| HTTP 路由 | `lib/agent-service/routes/runtime-env-routes.ts` | 1–186 |
|
||||
| 端口文件 | `~/.desirecore/agent-service.port` | DesireCore 启动时写入 |
|
||||
175
skills/dev-environment-setup/references/office-deps.md
Normal file
175
skills/dev-environment-setup/references/office-deps.md
Normal file
@@ -0,0 +1,175 @@
|
||||
# 办公技能依赖速查
|
||||
|
||||
DesireCore 办公四件套（DOCX / PDF / XLSX / PPTX）所需依赖汇总。Python 包通过 `python-runtime` skill 决策树安装；Node.js 包通过 `nodejs-runtime` skill；系统工具见 `system-tools.md`。
|
||||
|
||||
## DOCX（Word 文档）
|
||||
|
||||
```bash
|
||||
# Python 包
|
||||
pip install lxml defusedxml
|
||||
|
||||
# Node.js 包
|
||||
npm install -g docx
|
||||
|
||||
# 系统工具
|
||||
# pandoc —— 文本提取
|
||||
# LibreOffice —— PDF 转换
|
||||
```
|
||||
|
||||
## PDF（PDF 文档）
|
||||
|
||||
```bash
|
||||
# Python 核心
|
||||
pip install pypdf pdfplumber Pillow
|
||||
|
||||
# Python 可选
|
||||
pip install reportlab # PDF 创建
|
||||
pip install pdf2image # PDF 转图片（需 poppler）
|
||||
pip install pytesseract # OCR（需 tesseract）
|
||||
|
||||
# 系统工具
|
||||
# poppler-utils —— pdftotext / pdftoppm / pdfimages
|
||||
# qpdf —— 合并 / 拆分 / 解密
|
||||
# tesseract —— OCR 引擎
|
||||
```
|
||||
|
||||
## XLSX（电子表格）
|
||||
|
||||
```bash
|
||||
# Python
|
||||
pip install openpyxl pandas
|
||||
|
||||
# 系统工具
|
||||
# LibreOffice —— 公式重算
|
||||
```
|
||||
|
||||
## PPTX（演示文稿）
|
||||
|
||||
```bash
|
||||
# Python
|
||||
pip install "markitdown[pptx]" Pillow
|
||||
|
||||
# Node.js
|
||||
npm install -g pptxgenjs
|
||||
|
||||
# 系统工具
|
||||
# LibreOffice —— PDF 转换
|
||||
# poppler-utils —— PDF 转图片
|
||||
```
|
||||
|
||||
## 一键安装四件套全部依赖
|
||||
|
||||
### macOS / Linux
|
||||
|
||||
```bash
|
||||
# Python（在虚拟环境中，或用 pipx 安装 CLI 工具）
|
||||
pip install lxml defusedxml pypdf pdfplumber Pillow reportlab openpyxl pandas "markitdown[pptx]"
|
||||
|
||||
# Node.js（用户级 prefix，避免 sudo）
|
||||
npm install -g docx pptxgenjs
|
||||
|
||||
# 系统工具（macOS）
|
||||
brew install --cask libreoffice
|
||||
brew install poppler qpdf pandoc tesseract tesseract-lang
|
||||
|
||||
# 系统工具（Ubuntu/Debian）
|
||||
sudo apt install libreoffice poppler-utils qpdf pandoc tesseract-ocr tesseract-ocr-chi-sim
|
||||
```
|
||||
|
||||
### Windows
|
||||
|
||||
```powershell
|
||||
# Python
|
||||
pip install lxml defusedxml pypdf pdfplumber Pillow reportlab openpyxl pandas "markitdown[pptx]"
|
||||
|
||||
# Node.js
|
||||
npm install -g docx pptxgenjs
|
||||
|
||||
# 系统工具
|
||||
winget install TheDocumentFoundation.LibreOffice
|
||||
winget install JohnMacFarlane.Pandoc
|
||||
# poppler / qpdf / tesseract 见 system-tools.md
|
||||
```
|
||||
|
||||
## 包名 vs import 名
|
||||
|
||||
| 安装名（pip） | import 名 |
|
||||
|---------------|-----------|
|
||||
| Pillow | PIL |
|
||||
| beautifulsoup4 | bs4 |
|
||||
| python-dateutil | dateutil |
|
||||
| markitdown | markitdown |
|
||||
| pypdf | pypdf |
|
||||
|
||||
## 环境验证脚本
|
||||
|
||||
四件套依赖速查（保存为 `check-office.sh`）：
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
echo "=== Python ==="
|
||||
python3 --version 2>/dev/null || echo "MISSING: python3"
|
||||
|
||||
echo "=== pip ==="
|
||||
pip3 --version 2>/dev/null || echo "MISSING: pip3"
|
||||
|
||||
echo "=== Node.js ==="
|
||||
node --version 2>/dev/null || echo "MISSING: node"
|
||||
|
||||
echo "=== npm ==="
|
||||
npm --version 2>/dev/null || echo "MISSING: npm"
|
||||
|
||||
echo "=== Python Packages ==="
|
||||
python3 - <<'PY'
|
||||
packages = {
|
||||
'lxml': 'lxml',
|
||||
'defusedxml': 'defusedxml',
|
||||
'pypdf': 'pypdf',
|
||||
'pdfplumber': 'pdfplumber',
|
||||
'PIL': 'Pillow',
|
||||
'openpyxl': 'openpyxl',
|
||||
'pandas': 'pandas',
|
||||
'markitdown': 'markitdown',
|
||||
'reportlab': 'reportlab',
|
||||
}
|
||||
for mod, pkg in packages.items():
|
||||
try:
|
||||
__import__(mod)
|
||||
print(f' OK: {pkg}')
|
||||
except ImportError:
|
||||
print(f' MISSING: {pkg}')
|
||||
PY
|
||||
|
||||
echo "=== Node.js Global Packages ==="
|
||||
for pkg in docx pptxgenjs; do
|
||||
node -e "require('$pkg')" 2>/dev/null && echo " OK: $pkg" || echo " MISSING: $pkg"
|
||||
done
|
||||
|
||||
echo "=== System Tools ==="
|
||||
for cmd in soffice pandoc pdftoppm pdftotext qpdf tesseract; do
|
||||
command -v "$cmd" >/dev/null 2>&1 && echo " OK: $cmd" || echo " MISSING: $cmd"
|
||||
done
|
||||
```
|
||||
|
||||
## 跨 skill 协作
|
||||
|
||||
办公技能（docx / pdf / xlsx / pptx）报告依赖缺失时，按以下顺序：
|
||||
|
||||
1. **Python 缺失** → 触发 `python-runtime` skill 决策树
|
||||
2. **Node.js 缺失** → 触发 `nodejs-runtime` skill 决策树
|
||||
3. **Python/Node.js 包缺失** → 上方一键命令
|
||||
4. **系统工具缺失** → `system-tools.md`
|
||||
|
||||
## 在 DesireCore 应用内通过 API 装包
|
||||
|
||||
DesireCore 内置 Hatch/Volta，但**不直接管理 pip / npm 包安装**——只管理 Python / Node 自身版本。包安装仍走 `pip install` / `npm install`。
|
||||
|
||||
如果使用 Hatch 创建的 Python：
|
||||
```bash
|
||||
~/.desirecore/runtime/hatch/local/3.12/python/bin/python3 -m pip install lxml defusedxml
|
||||
```
|
||||
|
||||
如果使用 Volta 安装的 Node：
|
||||
```bash
|
||||
~/.desirecore/runtime/volta/bin/npm install -g docx pptxgenjs
|
||||
```
|
||||
118
skills/dev-environment-setup/references/probe-snapshot.md
Normal file
118
skills/dev-environment-setup/references/probe-snapshot.md
Normal file
@@ -0,0 +1,118 @@
|
||||
# 环境探测 JSON 协议
|
||||
|
||||
`probe.sh` / `probe.ps1` / `probe-python.sh` / `probe-node.sh` 输出统一 JSON。Skill 解析 JSON 后再决策，避免逐条 grep。
|
||||
|
||||
## 通用字段
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `platform` | `"darwin" \| "linux" \| "win32"` | 操作系统标识 |
|
||||
| `arch` | `"arm64" \| "x64" \| ...` | CPU 架构 |
|
||||
| `desirecore_api` | `string` | 探测到的 DesireCore agent-service URL，不可达时为 `""` |
|
||||
| `desirecore_port_file` | `string` | `~/.desirecore/agent-service.port` 是否存在 |
|
||||
|
||||
## probe.sh / probe.ps1（父级 dev-environment-setup）
|
||||
|
||||
输出系统级总览：
|
||||
|
||||
```json
|
||||
{
|
||||
"platform": "darwin",
|
||||
"arch": "arm64",
|
||||
"desirecore_api": "https://127.0.0.1:38291",
|
||||
"desirecore_port_file": true,
|
||||
"tools": {
|
||||
"python3": { "available": true, "path": "/opt/homebrew/bin/python3", "version": "3.12.4" },
|
||||
"pip3": { "available": true, "path": "/opt/homebrew/bin/pip3", "version": "24.0" },
|
||||
"node": { "available": true, "path": "/opt/homebrew/bin/node", "version": "22.4.1" },
|
||||
"npm": { "available": true, "path": "/opt/homebrew/bin/npm", "version": "10.8.1" },
|
||||
"docker": { "available": false },
|
||||
"podman": { "available": false },
|
||||
"git": { "available": true, "path": "/usr/bin/git", "version": "2.43.0" }
|
||||
},
|
||||
"wsl": null
|
||||
}
|
||||
```
|
||||
|
||||
Windows 上 `wsl` 字段值类似 `{ "installed": true, "version": "2", "defaultDistro": "Ubuntu" }`。
|
||||
|
||||
## probe-python.sh（python-runtime 专用）
|
||||
|
||||
```json
|
||||
{
|
||||
"platform": "darwin",
|
||||
"arch": "arm64",
|
||||
"desirecore_api": "https://127.0.0.1:38291",
|
||||
"system_python": { "path": "/opt/homebrew/bin/python3", "version": "3.12.4" },
|
||||
"system_pip": { "path": "/opt/homebrew/bin/pip3", "version": "24.0" },
|
||||
"hatch_path": "/Users/wangyi/.desirecore/runtime/hatch/hatch",
|
||||
"hatch_version": "1.16.5",
|
||||
"hatch_versions": ["3.11", "3.12"],
|
||||
"active_venv": "/Users/wangyi/proj/.venv",
|
||||
"pep668": false,
|
||||
"pyenv_path": "",
|
||||
"conda_path": ""
|
||||
}
|
||||
```
|
||||
|
||||
字段语义：
|
||||
- `hatch_path` 空字符串表示二进制不存在
|
||||
- `hatch_versions` 是 `~/.desirecore/runtime/hatch/local/` 下的目录列表（即已通过 Hatch 安装的 Python 版本）
|
||||
- `active_venv` 取自 `$VIRTUAL_ENV` 环境变量
|
||||
- `pep668` 检测 `/usr/lib/python*/EXTERNALLY-MANAGED` 是否存在（Debian 12+/Ubuntu 23.04+ 启用）
|
||||
|
||||
## probe-node.sh（nodejs-runtime 专用）
|
||||
|
||||
```json
|
||||
{
|
||||
"platform": "darwin",
|
||||
"arch": "arm64",
|
||||
"desirecore_api": "https://127.0.0.1:38291",
|
||||
"system_node": { "path": "/opt/homebrew/bin/node", "version": "22.4.1" },
|
||||
"system_npm": { "path": "/opt/homebrew/bin/npm", "version": "10.8.1" },
|
||||
"volta_path": "/Users/wangyi/.desirecore/runtime/volta/volta",
|
||||
"volta_version": "2.0.2",
|
||||
"volta_tools": {
|
||||
"node": ["22.4.1"],
|
||||
"pnpm": ["9.5.0"],
|
||||
"yarn": [],
|
||||
"npm": []
|
||||
},
|
||||
"package_json_volta": null,
|
||||
"nvm_path": "",
|
||||
"fnm_path": "",
|
||||
"registry": "https://registry.npmmirror.com/",
|
||||
"proxy": ""
|
||||
}
|
||||
```
|
||||
|
||||
字段语义：
|
||||
- `volta_tools` 来自 `<volta> list --format=plain`，按工具分类
|
||||
- `package_json_volta` 若当前目录存在 `package.json` 且其中有 `"volta"` 字段，填入对象；否则 `null`
|
||||
- `registry` / `proxy` 来自 `npm config get registry` / `npm config get https-proxy`
|
||||
|
||||
## 设计约定
|
||||
|
||||
1. **JSON 必合法**：缺字段也保留键并赋空字符串/`null`，避免 Claude 解析失败。
|
||||
2. **不阻塞**：每个外部命令都加 `2>/dev/null`，失败用空值，不让脚本中途退出。
|
||||
3. **超时控制**：HTTP 探测 0.5s 超时；CLI 调用最长 5s。
|
||||
4. **跨平台**：`probe.sh` / `probe-python.sh` / `probe-node.sh` 共用 POSIX 子集；Windows 同等功能由 `probe.ps1` 提供（仅父级提供，python/nodejs 子 skill 可由 PowerShell 直接 invoke 父级或自行实现）。
|
||||
5. **路径展开**：所有 `~` 在 JSON 中展开为绝对路径，避免下游解析歧义。
|
||||
|
||||
## 调用约定
|
||||
|
||||
```bash
|
||||
SNAPSHOT=$(bash skills/python-runtime/scripts/probe-python.sh)
|
||||
echo "$SNAPSHOT" | jq .
|
||||
|
||||
# 关键字段判定
|
||||
HATCH=$(echo "$SNAPSHOT" | jq -r .hatch_path)
|
||||
[ -n "$HATCH" ] && [ "$HATCH" != "null" ] && echo "Hatch 可用"
|
||||
```
|
||||
|
||||
PowerShell 等价：
|
||||
|
||||
```powershell
|
||||
$snapshot = & "$PWD\skills\dev-environment-setup\scripts\probe.ps1" | ConvertFrom-Json
|
||||
if ($snapshot.tools.node.available) { ... }
|
||||
```
|
||||
224
skills/dev-environment-setup/references/system-tools.md
Normal file
224
skills/dev-environment-setup/references/system-tools.md
Normal file
@@ -0,0 +1,224 @@
|
||||
# 系统工具安装
|
||||
|
||||
办公技能、PDF/OCR、文档转换会用到的系统级二进制工具。
|
||||
|
||||
## LibreOffice（文档转换 / 公式重算）
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install --cask libreoffice
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install libreoffice
|
||||
|
||||
# Fedora / RHEL
|
||||
sudo dnf install libreoffice
|
||||
|
||||
# Arch
|
||||
sudo pacman -S libreoffice-fresh
|
||||
|
||||
# Windows
|
||||
winget install TheDocumentFoundation.LibreOffice
|
||||
```
|
||||
|
||||
无头转换（CLI）：
|
||||
```bash
|
||||
soffice --headless --convert-to pdf input.docx
|
||||
soffice --headless --calc --convert-to xlsx input.csv
|
||||
```
|
||||
|
||||
## Poppler（PDF 工具集）
|
||||
|
||||
提供 `pdftotext` / `pdftoppm` / `pdfimages` / `pdftohtml` 等。
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install poppler
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install poppler-utils
|
||||
|
||||
# Fedora / RHEL
|
||||
sudo dnf install poppler-utils
|
||||
|
||||
# Arch
|
||||
sudo pacman -S poppler
|
||||
|
||||
# Windows（通过 conda 或手动）
|
||||
conda install -c conda-forge poppler
|
||||
# 或下载 https://github.com/oschwartz10612/poppler-windows/releases，将 bin/ 加入 PATH
|
||||
```
|
||||
|
||||
常用：
|
||||
```bash
|
||||
pdftotext input.pdf output.txt
|
||||
pdftoppm -png input.pdf prefix # 每页一张 PNG
|
||||
pdfimages -png input.pdf prefix # 提取嵌入图片
|
||||
```
|
||||
|
||||
## qpdf（PDF 操作）
|
||||
|
||||
合并 / 拆分 / 解密 / 加密。
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install qpdf
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install qpdf
|
||||
|
||||
# Fedora / RHEL
|
||||
sudo dnf install qpdf
|
||||
|
||||
# Windows
|
||||
winget install QPDF.QPDF
|
||||
```
|
||||
|
||||
常用：
|
||||
```bash
|
||||
qpdf --decrypt --password=secret input.pdf output.pdf
|
||||
qpdf --split-pages input.pdf output-%d.pdf
|
||||
qpdf --empty --pages a.pdf b.pdf -- merged.pdf
|
||||
```
|
||||
|
||||
## Pandoc（文档格式互转）
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install pandoc
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install pandoc
|
||||
|
||||
# Fedora / RHEL
|
||||
sudo dnf install pandoc
|
||||
|
||||
# Arch
|
||||
sudo pacman -S pandoc
|
||||
|
||||
# Windows
|
||||
winget install JohnMacFarlane.Pandoc
|
||||
```
|
||||
|
||||
常用：
|
||||
```bash
|
||||
pandoc input.docx -o output.md
|
||||
pandoc input.md -o output.pdf --pdf-engine=xelatex
|
||||
pandoc input.html -o output.docx
|
||||
```
|
||||
|
||||
## Tesseract（OCR 引擎）
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install tesseract
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install tesseract-ocr
|
||||
|
||||
# Fedora / RHEL
|
||||
sudo dnf install tesseract
|
||||
|
||||
# Arch
|
||||
sudo pacman -S tesseract
|
||||
|
||||
# Windows
|
||||
winget install UB-Mannheim.TesseractOCR
|
||||
```
|
||||
|
||||
### 中文语言包
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install tesseract-lang
|
||||
|
||||
# Ubuntu / Debian
|
||||
sudo apt install tesseract-ocr-chi-sim tesseract-ocr-chi-tra
|
||||
|
||||
# Fedora
|
||||
sudo dnf install tesseract-langpack-chi_sim tesseract-langpack-chi_tra
|
||||
```
|
||||
|
||||
使用：
|
||||
```bash
|
||||
tesseract image.png output -l chi_sim # 简体
|
||||
tesseract image.png output -l chi_sim+eng # 中英混合
|
||||
```
|
||||
|
||||
## ImageMagick（图像处理，可选）
|
||||
|
||||
```bash
|
||||
brew install imagemagick # macOS
|
||||
sudo apt install imagemagick # Ubuntu / Debian
|
||||
sudo dnf install ImageMagick # Fedora
|
||||
winget install ImageMagick.ImageMagick # Windows
|
||||
```
|
||||
|
||||
## Ghostscript（PDF / PostScript 渲染）
|
||||
|
||||
```bash
|
||||
brew install ghostscript # macOS
|
||||
sudo apt install ghostscript # Ubuntu / Debian
|
||||
sudo dnf install ghostscript # Fedora
|
||||
winget install ArtifexSoftware.GhostScript # Windows
|
||||
```
|
||||
|
||||
## Git（版本控制，必备）
|
||||
|
||||
```bash
|
||||
brew install git # macOS
|
||||
sudo apt install git # Ubuntu / Debian
|
||||
sudo dnf install git # Fedora
|
||||
sudo pacman -S git # Arch
|
||||
winget install Git.Git # Windows
|
||||
```
|
||||
|
||||
macOS 上 `xcode-select --install` 也会带 git。
|
||||
|
||||
## 跨平台一键检查脚本
|
||||
|
||||
```bash
|
||||
for cmd in soffice pandoc pdftoppm pdftotext pdfimages qpdf tesseract magick gs git; do
|
||||
command -v "$cmd" >/dev/null 2>&1 \
|
||||
&& echo " OK: $cmd ($(command -v "$cmd"))" \
|
||||
|| echo " MISSING: $cmd"
|
||||
done
|
||||
```
|
||||
|
||||
## 故障排查
|
||||
|
||||
### macOS: "soffice: command not found"
|
||||
|
||||
`/Applications/LibreOffice.app/Contents/MacOS/soffice` 是真实路径。建立软链：
|
||||
```bash
|
||||
ln -s /Applications/LibreOffice.app/Contents/MacOS/soffice /usr/local/bin/soffice
|
||||
```
|
||||
|
||||
### Tesseract 找不到中文语言包
|
||||
|
||||
```bash
|
||||
tesseract --list-langs # 检查已安装语言
|
||||
# 找到语言数据目录
|
||||
tesseract --print-parameters | grep tessdata
|
||||
# macOS Apple Silicon: /opt/homebrew/share/tessdata
|
||||
# 把缺失的 chi_sim.traineddata 放进去
|
||||
```
|
||||
|
||||
下载链接：https://github.com/tesseract-ocr/tessdata_fast
|
||||
|
||||
### Windows 工具未在 PATH
|
||||
|
||||
winget 安装后通常自动加入 PATH，重启终端即生效。手动安装的（如 poppler-windows）需要把 `<安装目录>\bin` 加入系统 PATH：
|
||||
|
||||
```powershell
|
||||
[Environment]::SetEnvironmentVariable(
|
||||
"Path",
|
||||
$env:Path + ";C:\poppler\bin",
|
||||
[EnvironmentVariableTarget]::User
|
||||
)
|
||||
```
|
||||
|
||||
重启终端验证：
|
||||
```powershell
|
||||
pdftotext --version
|
||||
```
|
||||
138
skills/dev-environment-setup/references/wsl.md
Normal file
138
skills/dev-environment-setup/references/wsl.md
Normal file
@@ -0,0 +1,138 @@
|
||||
# WSL2 安装与配置（Windows）
|
||||
|
||||
WSL2（Windows Subsystem for Linux 2）让 Windows 用户原生运行 Linux 环境，是运行 Python 脚本、Docker、各种开发工具的最佳方式。
|
||||
|
||||
## 检测
|
||||
|
||||
```powershell
|
||||
wsl --status # 已安装时显示版本与默认发行版
|
||||
wsl --list --verbose # 已安装的发行版及版本
|
||||
```
|
||||
|
||||
## 系统要求
|
||||
|
||||
- Windows 11（21H2+）或 Windows 10（版本 2004，Build 19041+）
|
||||
- BIOS 启用 CPU 虚拟化（Intel VT-x / AMD-V）
|
||||
|
||||
## 安装
|
||||
|
||||
```powershell
|
||||
# 以管理员身份打开 PowerShell
|
||||
|
||||
# 一键安装（含 WSL2 内核 + 默认 Ubuntu）
|
||||
wsl --install
|
||||
|
||||
# 重启计算机后 Ubuntu 窗口自动打开，提示设置用户名密码
|
||||
```
|
||||
|
||||
## 安装指定发行版
|
||||
|
||||
```powershell
|
||||
wsl --list --online # 可选发行版
|
||||
wsl --install -d Ubuntu-24.04
|
||||
wsl --install -d Debian
|
||||
wsl --set-default Ubuntu-24.04
|
||||
```
|
||||
|
||||
## 确保使用 WSL2
|
||||
|
||||
```powershell
|
||||
wsl --list --verbose
|
||||
# VERSION 列应为 2
|
||||
|
||||
# 升级到 WSL2
|
||||
wsl --set-version Ubuntu 2
|
||||
|
||||
# 默认 WSL2
|
||||
wsl --set-default-version 2
|
||||
```
|
||||
|
||||
## 进入 WSL2 后配置开发环境
|
||||
|
||||
按 Linux 方式配置即可：
|
||||
|
||||
```bash
|
||||
# 进入
|
||||
wsl
|
||||
|
||||
# 系统更新
|
||||
sudo apt update && sudo apt upgrade -y
|
||||
|
||||
# Python（推荐用 python-runtime skill 走完整决策树）
|
||||
sudo apt install python3 python3-pip python3-venv
|
||||
|
||||
# Node.js（推荐用 nodejs-runtime skill）
|
||||
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
|
||||
sudo apt install nodejs
|
||||
|
||||
# Docker（推荐 Docker Desktop 的 WSL2 后端，而非在 WSL2 内独立装）
|
||||
```
|
||||
|
||||
## 文件互访
|
||||
|
||||
```bash
|
||||
# WSL2 → Windows
|
||||
ls /mnt/c/Users/<用户名>/Desktop/
|
||||
|
||||
# Windows → WSL2（资源管理器地址栏）
|
||||
\\wsl$\Ubuntu\home\<用户名>\
|
||||
|
||||
# Windows Terminal 打开 WSL2
|
||||
wsl ~
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### "WslRegisterDistribution failed with error: 0x80370102"
|
||||
|
||||
CPU 虚拟化未启用。重启进 BIOS，启用 Intel VT-x / AMD-V。
|
||||
|
||||
### 网络无法访问互联网
|
||||
|
||||
```bash
|
||||
# 在 WSL2 内
|
||||
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
|
||||
|
||||
# 或 Windows 端关闭 Hyper-V 网卡的 DNS 自动管理
|
||||
```
|
||||
|
||||
如果是公司 VPN 干扰，在 Windows 端 `wsl --shutdown` 后重启 VPN。
|
||||
|
||||
### 磁盘空间不足
|
||||
|
||||
```powershell
|
||||
# 压缩 WSL2 虚拟磁盘
|
||||
wsl --shutdown
|
||||
# 然后用 diskpart 压缩 ext4.vhdx（高级操作，备份后再做）
|
||||
```
|
||||
|
||||
或在 `~/.wslconfig` 限制大小：
|
||||
|
||||
```ini
|
||||
[wsl2]
|
||||
memory=4GB
|
||||
processors=2
|
||||
swap=2GB
|
||||
```
|
||||
|
||||
### Windows 与 WSL2 时间不同步
|
||||
|
||||
```bash
|
||||
sudo hwclock -s
|
||||
```
|
||||
|
||||
或：
|
||||
```bash
|
||||
sudo apt install ntpdate
|
||||
sudo ntpdate -s time.windows.com
|
||||
```
|
||||
|
||||
### DesireCore 在 WSL2 中使用
|
||||
|
||||
DesireCore 是 Windows 桌面应用，运行在 Windows 端而非 WSL2 内。但 DesireCore 的环境检查（设置 → 环境检查）可以自动检测 Windows 版本、CPU 虚拟化、WSL2 状态，并提供一键修复入口。
|
||||
|
||||
## 性能建议
|
||||
|
||||
- 项目文件放在 WSL2 的 Linux 文件系统（`/home/<user>/`），不要放 `/mnt/c/`——后者跨文件系统 IO 极慢
|
||||
- 编辑器：VS Code + Remote-WSL 扩展，自动跨边界
|
||||
- Docker：使用 Docker Desktop 的 WSL2 后端，避免 WSL2 内独立 Docker 守护进程
|
||||
66
skills/dev-environment-setup/scripts/probe.ps1
Normal file
66
skills/dev-environment-setup/scripts/probe.ps1
Normal file
@@ -0,0 +1,66 @@
|
||||
# dev-environment-setup probe (Windows)
|
||||
# 协议：见 ..\references\probe-snapshot.md
|
||||
|
||||
$ErrorActionPreference = 'SilentlyContinue'
|
||||
|
||||
function Test-Tool {
|
||||
param([string]$Name, [string]$VersionFlag = '--version')
|
||||
$cmd = Get-Command $Name -ErrorAction SilentlyContinue
|
||||
if (-not $cmd) {
|
||||
return @{ available = $false }
|
||||
}
|
||||
$output = & $Name $VersionFlag 2>&1 | Select-Object -First 1
|
||||
$version = ''
|
||||
if ($output -match '(\d+\.\d+(?:\.\d+)?)') { $version = $Matches[1] }
|
||||
return @{ available = $true; path = $cmd.Source; version = $version }
|
||||
}
|
||||
|
||||
# DesireCore API 探测
|
||||
$portFile = Join-Path $env:USERPROFILE '.desirecore\agent-service.port'
|
||||
$desirecoreApi = ''
|
||||
$portFileExists = Test-Path $portFile
|
||||
if ($portFileExists) {
|
||||
$port = (Get-Content $portFile -Raw).Trim()
|
||||
if ($port) {
|
||||
try {
|
||||
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }
|
||||
$resp = Invoke-WebRequest -Uri "https://127.0.0.1:$port/api/runtime/environment" `
|
||||
-TimeoutSec 1 -UseBasicParsing -ErrorAction Stop
|
||||
if ($resp.StatusCode -eq 200) { $desirecoreApi = "https://127.0.0.1:$port" }
|
||||
} catch { }
|
||||
}
|
||||
}
|
||||
|
||||
# WSL 检测
|
||||
$wsl = $null
|
||||
$wslOut = wsl --status 2>&1
|
||||
if ($LASTEXITCODE -eq 0) {
|
||||
$version = ''
|
||||
$defaultDistro = ''
|
||||
if ($wslOut -match '(\d+)') { $version = $Matches[1] }
|
||||
$wsl = @{ installed = $true; version = $version; defaultDistro = $defaultDistro }
|
||||
} else {
|
||||
$wsl = @{ installed = $false }
|
||||
}
|
||||
|
||||
$arch = if ([Environment]::Is64BitOperatingSystem) { 'x64' } else { 'x86' }
|
||||
if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { $arch = 'arm64' }
|
||||
|
||||
$result = @{
|
||||
platform = 'win32'
|
||||
arch = $arch
|
||||
desirecore_api = $desirecoreApi
|
||||
desirecore_port_file = $portFileExists
|
||||
tools = @{
|
||||
python3 = (Test-Tool python)
|
||||
pip3 = (Test-Tool pip)
|
||||
node = (Test-Tool node)
|
||||
npm = (Test-Tool npm)
|
||||
docker = (Test-Tool docker)
|
||||
podman = (Test-Tool podman)
|
||||
git = (Test-Tool git)
|
||||
}
|
||||
wsl = $wsl
|
||||
}
|
||||
|
||||
$result | ConvertTo-Json -Depth 5 -Compress:$false
|
||||
77
skills/dev-environment-setup/scripts/probe.sh
Executable file
77
skills/dev-environment-setup/scripts/probe.sh
Executable file
@@ -0,0 +1,77 @@
|
||||
#!/usr/bin/env bash
|
||||
# dev-environment-setup probe: 输出系统级环境快照（JSON）
|
||||
# 协议：见 ../references/probe-snapshot.md
|
||||
|
||||
set +e
|
||||
|
||||
# ── 工具检测 ─────────────────────────────
|
||||
detect_tool() {
|
||||
local name="$1"
|
||||
local version_flag="${2:---version}"
|
||||
local path
|
||||
path=$(command -v "$name" 2>/dev/null)
|
||||
if [ -z "$path" ]; then
|
||||
printf '{"available":false}'
|
||||
return
|
||||
fi
|
||||
local version
|
||||
version=$("$name" $version_flag 2>&1 | head -n1 | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -n1)
|
||||
printf '{"available":true,"path":"%s","version":"%s"}' "$path" "${version:-}"
|
||||
}
|
||||
|
||||
# ── 平台 ────────────────────────────────
|
||||
case "$(uname -s)" in
|
||||
Darwin) PLATFORM="darwin" ;;
|
||||
Linux) PLATFORM="linux" ;;
|
||||
*) PLATFORM="other" ;;
|
||||
esac
|
||||
ARCH=$(uname -m)
|
||||
case "$ARCH" in
|
||||
arm64|aarch64) ARCH="arm64" ;;
|
||||
x86_64|amd64) ARCH="x64" ;;
|
||||
esac
|
||||
|
||||
# ── DesireCore API 探测 ─────────────────
|
||||
PORT_FILE="$HOME/.desirecore/agent-service.port"
|
||||
DESIRECORE_API=""
|
||||
PORT_FILE_EXISTS="false"
|
||||
if [ -r "$PORT_FILE" ]; then
|
||||
PORT_FILE_EXISTS="true"
|
||||
PORT=$(cat "$PORT_FILE" 2>/dev/null | tr -d '[:space:]')
|
||||
if [ -n "$PORT" ]; then
|
||||
if curl -sk --max-time 0.5 "https://127.0.0.1:${PORT}/api/runtime/environment" >/dev/null 2>&1; then
|
||||
DESIRECORE_API="https://127.0.0.1:${PORT}"
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# ── 工具检测结果 ────────────────────────
|
||||
PY=$(detect_tool python3)
|
||||
[ "$(echo "$PY" | grep -o false)" = "false" ] && PY=$(detect_tool python)
|
||||
PIP=$(detect_tool pip3)
|
||||
[ "$(echo "$PIP" | grep -o false)" = "false" ] && PIP=$(detect_tool pip)
|
||||
NODE=$(detect_tool node)
|
||||
NPM=$(detect_tool npm)
|
||||
DOCKER=$(detect_tool docker)
|
||||
PODMAN=$(detect_tool podman)
|
||||
GIT=$(detect_tool git)
|
||||
|
||||
# ── 输出 JSON ───────────────────────────
|
||||
cat <<EOF
|
||||
{
|
||||
"platform": "${PLATFORM}",
|
||||
"arch": "${ARCH}",
|
||||
"desirecore_api": "${DESIRECORE_API}",
|
||||
"desirecore_port_file": ${PORT_FILE_EXISTS},
|
||||
"tools": {
|
||||
"python3": ${PY},
|
||||
"pip3": ${PIP},
|
||||
"node": ${NODE},
|
||||
"npm": ${NPM},
|
||||
"docker": ${DOCKER},
|
||||
"podman": ${PODMAN},
|
||||
"git": ${GIT}
|
||||
},
|
||||
"wsl": null
|
||||
}
|
||||
EOF
|
||||
Reference in New Issue
Block a user