mirror of https://git.openapi.site/https://github.com/desirecore/market.git synced 2026-04-21 14:50:49 +08:00

Files

yi-ge 8aac4a588b fix: environment-setup 和 web-access 也改为 disable-model-invocation: true

- environment-setup 1.1.1→1.1.2
- web-access 1.1.1→1.1.2

2026-04-13 16:30:13 +08:00

33 KiB

Raw Permalink Blame History

name, description, version, type, risk_level, status, disable-model-invocation, tags, metadata, market

name

description

version

type

risk_level

status

disable-model-invocation

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：详细规范

快速诊断

在进行任何安装之前，先运行以下命令检查当前环境状态：

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 中运行）：

Write-Host "=== WSL ===" ; wsl --status 2>&1
Write-Host "=== Docker ===" ; docker --version 2>$null ; if (-not $?) { Write-Host "NOT FOUND" }

根据输出结果，跳转到对应章节。

Python 安装

macOS

方式 1：Homebrew（推荐）

# 安装 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：官方安装包

访问 https://www.python.org/downloads/
下载最新的 macOS 安装包（.pkg）
双击运行安装程序，按照向导完成安装
安装完成后打开新终端窗口验证：

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（推荐）

winget install Python.Python.3

安装后重启终端，验证：

python --version
pip --version

方式 2：官方安装包

访问 https://www.python.org/downloads/
下载 Windows installer（.exe）
务必勾选 "Add Python to PATH"（安装界面底部的复选框）
点击 "Install Now"
安装完成后打开新的 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)

sudo apt update
sudo apt install python3 python3-pip python3-venv
python3 --version
pip3 --version

Linux (Fedora/RHEL/CentOS)

sudo dnf install python3 python3-pip
python3 --version
pip3 --version

Linux (Arch)

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 v1.16.5 作为 Python 项目管理器和版本管理器。Hatch 二进制随应用打包在 static/hatch/ 中，无需用户单独安装。

与系统 Python 的关系：Hatch 管理的 Python 版本安装在 ~/.desirecore/runtime/hatch/local/ 中，与系统 Python 完全隔离，不会影响系统环境。

查看可安装的 Python 版本

# 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 版本

# 安装指定版本（下载到 ~/.desirecore/runtime/hatch/local/）
hatch python install 3.12
hatch python install 3.11

# 安装多个版本
hatch python install 3.12 3.11 3.10

查看已安装版本

# 查看 ~/.desirecore/runtime/hatch/local/ 下的目录
ls ~/.desirecore/runtime/hatch/local/
# 输出：3.11  3.12

移除 Python 版本

hatch python remove 3.11

使用 Hatch 管理的 Python

# 直接使用安装的 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

# 安装 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 编译依赖

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

Windows 上推荐使用 pyenv-win：

# 通过 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）：

[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

# 查看可安装的版本
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（内置，推荐）

# 创建虚拟环境
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 环境时：

# 安装 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）的场景：

# 安装 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

brew install node
node --version
npm --version

方式 2：官方安装包

访问 https://nodejs.org/
下载 LTS 版本的 macOS 安装包（.pkg）
运行安装程序

Windows

方式 1：winget

winget install OpenJS.NodeJS.LTS

方式 2：官方安装包

访问 https://nodejs.org/
下载 Windows LTS 安装包（.msi）
运行安装程序（默认选项即可，会自动添加到 PATH）

Linux (Debian/Ubuntu)

使用 NodeSource 官方仓库获取最新 LTS：

# 安装 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

或使用系统仓库（版本可能较旧）：

sudo apt install nodejs npm

Linux (Fedora/RHEL)

curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo dnf install -y nodejs

Linux (Arch)

sudo pacman -S nodejs npm

Node.js 多版本管理（Volta — DesireCore 内置）

DesireCore 内置了 Volta v2.0.2 作为 Node.js 工具链管理器。Volta 二进制随应用打包在 static/volta/ 中，无需用户单独安装。

与系统 Node.js 的关系：Volta 管理的 Node.js 和包管理器安装在 ~/.desirecore/runtime/volta/ 中，与系统 Node.js 完全隔离。

安装 Node.js 版本

# Volta 二进制位置（DesireCore 自动管理）
# 安装最新 LTS
volta install node@22

# 安装指定版本
volta install node@20.11.0

# 安装特定大版本的最新版
volta install node@18

安装包管理器

# 安装 pnpm
volta install pnpm@latest

# 安装 yarn
volta install yarn@latest

# 安装指定版本的 npm
volta install npm@10

查看已安装版本

# 查看已安装的 Node.js 版本
volta list node

# 查看已安装的所有工具
volta list all

固定项目版本

# 在项目目录下，固定 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。

移除版本

# 移除 Node.js 版本
# 通过 DesireCore 运行环境 Tab 管理，或手动删除：
rm -rf ~/.desirecore/runtime/volta/tools/image/node/<version>

可视化管理

打开 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

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/releases 下载安装包
运行安装程序
重启终端

使用 nvm

# 查看可安装的 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 是用 Rust 编写的 Node.js 版本管理器，比 nvm 快得多：

# 安装 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 全局包管理

# 查看全局安装的包
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。

排查步骤：

# 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 是系统自带的精简版。

# 尝试使用 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。

解决方案（推荐优先级从高到低）：

# 方案 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"

排查步骤：

# 检查是否安装
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）：

# 更改 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 证书验证失败。

# 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 失败

常见原因和排查：

# 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）时编译失败。

# 安装 Xcode Command Line Tools
xcode-select --install

# 如果已安装但仍报错，重置
sudo xcode-select --reset

# 对于特定包，安装系统依赖
# lxml:
brew install libxml2 libxslt
# Pillow:
brew install libjpeg zlib

Windows PowerShell 执行策略阻止脚本

现象：无法激活虚拟环境或运行 npm 脚本。

# 查看当前策略
Get-ExecutionPolicy

# 设置为 RemoteSigned（推荐）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

代理环境下的配置

# 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 文档处理）

# Python 包
pip install lxml defusedxml

# Node.js 包
npm install -g docx

# 系统工具
# pandoc — 文本提取
# LibreOffice — PDF 转换

PDF（PDF 文档处理）

# 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（电子表格处理）

# Python 包
pip install openpyxl pandas

# 系统工具
# LibreOffice — 公式重算

PPTX（演示文稿处理）

# Python 包
pip install "markitdown[pptx]" Pillow

# Node.js 包
npm install -g pptxgenjs

# 系统工具
# LibreOffice — PDF 转换
# poppler-utils — PDF 转图片

一键安装所有办公技能依赖

# Python 包（全部）
pip install lxml defusedxml pypdf pdfplumber Pillow reportlab openpyxl pandas "markitdown[pptx]"

# Node.js 包（全部）
npm install -g docx pptxgenjs

容器运行环境（Docker / Podman）

容器环境在开发中越来越常见，许多工具和服务（数据库、消息队列、AI 推理服务等）通过容器部署最为便捷。

检测容器环境

# 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）：

# 方式 1：Homebrew Cask（推荐）
brew install --cask docker

# 安装后启动 Docker Desktop 应用
# 首次启动需要授权特权访问

# 方式 2：从官网下载
# https://www.docker.com/products/docker-desktop/
# 选择 Apple Silicon (M1/M2/M3) 或 Intel 版本

安装后验证：

docker --version
docker run hello-world

Windows

推荐 Docker Desktop + WSL2 后端（需要先安装 WSL2，见下方 WSL2 章节）：

下载 Docker Desktop for Windows
安装时勾选 "Use WSL 2 instead of Hyper-V"
安装后在 Settings → General 中确认 "Use the WSL 2 based engine" 已启用

# 或通过 winget 安装
winget install Docker.DockerDesktop

验证：

docker --version
docker run hello-world

不需要 Docker Desktop 的轻量方案（仅 CLI，通过 WSL2）：

# 在 WSL2 Ubuntu 中：
sudo apt update
sudo apt install docker.io docker-compose-v2
sudo usermod -aG docker $USER
# 重新登录 WSL2 后生效

Linux (Debian/Ubuntu)

# 安装 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)

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 命令，但不需要后台守护进程，更轻量：

# 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）：

podman run hello-world
podman ps
podman images

Docker 常见问题

"Cannot connect to the Docker daemon"：

# Linux：启动 Docker 服务
sudo systemctl start docker

# macOS/Windows：确保 Docker Desktop 正在运行

# WSL2：可能需要重启 Docker Desktop

"permission denied while trying to connect to the Docker daemon socket"：

# 将当前用户加入 docker 组
sudo usermod -aG docker $USER
# 重新登录（或执行 newgrp docker）

Docker Desktop 占用资源过高：在 Docker Desktop Settings → Resources 中调整 CPU 和内存限制。WSL2 后端用户也可编辑 ~/.wslconfig：

[wsl2]
memory=4GB
processors=2

WSL2 安装与配置（仅 Windows）

WSL2（Windows Subsystem for Linux 2）让 Windows 用户可以原生运行 Linux 环境，是运行 Python 脚本、Docker、以及各种开发工具的最佳方式。

检测 WSL2

# 检查 WSL 是否已安装
wsl --status

# 查看已安装的 Linux 发行版
wsl --list --verbose

系统要求

Windows 11（21H2 或更高）或 Windows 10（版本 2004，Build 19041 或更高）
CPU 虚拟化已启用（BIOS 中的 Intel VT-x / AMD-V）

安装 WSL2

# 以管理员权限运行 PowerShell

# 一键安装（包括 WSL2 内核 + Ubuntu 默认发行版）
wsl --install

# 安装完成后需要重启计算机
# 重启后 Ubuntu 窗口会自动打开，提示设置用户名和密码

安装指定发行版

# 查看可用发行版
wsl --list --online

# 安装指定发行版
wsl --install -d Ubuntu-24.04
wsl --install -d Debian

# 设置默认发行版
wsl --set-default Ubuntu-24.04

确保使用 WSL2（而非 WSL1）

# 查看当前版本
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 安装章节）：

# 进入 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 文件互访

# 在 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 网络问题（无法访问互联网）：

# 在 WSL2 中
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

WSL2 磁盘空间不足：

# 压缩 WSL2 虚拟磁盘
wsl --shutdown
# 使用 diskpart 压缩 ext4.vhdx（高级操作，请备份后再执行）

DesireCore Windows 用户建议：DesireCore 的环境检查功能（设置 → 环境检查）可以自动检测 Windows 版本、CPU 虚拟化、WSL2 安装状态，并提供一键修复。

系统工具安装

LibreOffice

办公技能用于文档格式转换和公式重算。

# 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 等命令。

# 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（文档格式转换）

# macOS
brew install pandoc

# Ubuntu/Debian
sudo apt install pandoc

# Fedora/RHEL
sudo dnf install pandoc

# Windows
winget install JohnMacFarlane.Pandoc

Tesseract（OCR 引擎）

# 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

环境验证脚本

一键检查所有办公技能所需的环境是否就绪：

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 即可查看完整的环境状态。

33 KiB Raw Permalink Blame History Unescape Escape

environment-setup 技能

L0：一句话摘要

L1：概述与使用场景

能力描述

使用场景

核心价值

L2：详细规范

快速诊断

Python 安装

macOS

方式 1：Homebrew（推荐）

方式 2：官方安装包

macOS 注意事项

Windows

方式 1：winget（推荐）

方式 2：官方安装包

Windows 注意事项

Linux (Debian/Ubuntu)

Linux (Fedora/RHEL/CentOS)

Linux (Arch)

Linux 注意事项

Python 多版本管理（Hatch — DesireCore 内置）

查看可安装的 Python 版本

安装 Python 版本

查看已安装版本

移除 Python 版本

使用 Hatch 管理的 Python

可视化管理

Hatch vs pyenv

Python 多版本管理（pyenv — 社区方案）

安装 pyenv

macOS / Linux

macOS 编译依赖

Ubuntu/Debian 编译依赖

Fedora/RHEL 编译依赖

Windows

使用 pyenv

Python 虚拟环境

venv（内置，推荐）

pipx（安装全局 CLI 工具）

conda / miniconda

Node.js 安装

macOS

方式 1：Homebrew

方式 2：官方安装包

Windows

方式 1：winget

方式 2：官方安装包

Linux (Debian/Ubuntu)

Linux (Fedora/RHEL)

Linux (Arch)

Node.js 多版本管理（Volta — DesireCore 内置）

安装 Node.js 版本

安装包管理器

查看已安装版本

固定项目版本

版本自动切换

移除版本

可视化管理

Volta vs nvm

Node.js 多版本管理（nvm — 社区方案）

安装 nvm

macOS / Linux

Windows

使用 nvm

使用 fnm（社区替代品，Rust 实现）

npm 全局包管理

常见问题排查

"python: command not found" 或 "python3: command not found"

"pip: command not found"

"externally-managed-environment" 错误（PEP 668）

"node: command not found"

npm 全局安装权限错误（EACCES）

SSL/TLS 证书错误

Python 包安装后 import 失败

macOS "xcrun: error" 或编译失败

Windows PowerShell 执行策略阻止脚本

代理环境下的配置

办公技能依赖速查

33 KiB

Raw Permalink Blame History