From aa9b1edf832c93c46dff4a63e4b9f25415cbd12a Mon Sep 17 00:00:00 2001 From: yi-ge Date: Wed, 8 Apr 2026 23:00:14 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E5=8A=9E=E5=85=AC=E6=8A=80=E8=83=BD?= =?UTF-8?q?=E5=A2=9E=E5=8A=A0=20Prerequisites=20+=20=E6=96=B0=E5=A2=9E=20e?= =?UTF-8?q?nvironment-setup=20=E6=8A=80=E8=83=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docx/pdf/xlsx/pptx: 添加 Python 3 检测和包依赖 Prerequisites 段落 - 新增 environment-setup 技能：完整的 Python/Node.js 安装、多版本管理、常见问题排查指引 - builtin-skills.json: 添加 environment-setup 到内置技能清单 --- builtin-skills.json | 1 + skills/docx/SKILL.md | 33 ++ skills/environment-setup/SKILL.md | 901 ++++++++++++++++++++++++++++++ skills/pdf/SKILL.md | 36 ++ skills/pptx/SKILL.md | 35 ++ skills/xlsx/SKILL.md | 33 ++ 6 files changed, 1039 insertions(+) create mode 100644 skills/environment-setup/SKILL.md diff --git a/builtin-skills.json b/builtin-skills.json index aafe861..16dc6a0 100644 --- a/builtin-skills.json +++ b/builtin-skills.json @@ -4,6 +4,7 @@ "delete-agent", "discover-agent", "docx", + "environment-setup", "frontend-design", "manage-skills", "manage-teams", diff --git a/skills/docx/SKILL.md b/skills/docx/SKILL.md index b82f630..fc8e8f5 100644 --- a/skills/docx/SKILL.md +++ b/skills/docx/SKILL.md @@ -49,6 +49,39 @@ market: # DOCX creation, editing, and analysis +## Prerequisites + +### Python 3（必需） + +在执行任何 Python 脚本之前，先检测 Python 是否可用： + +```bash +python3 --version 2>/dev/null || python --version 2>/dev/null +``` + +如果命令失败（Python 不可用），**必须停止并告知用户安装 Python 3**： + +- **macOS**: `brew install python3` 或从 https://www.python.org/downloads/ 下载 +- **Windows**: `winget install Python.Python.3` 或从 python.org 下载（安装时勾选 "Add Python to PATH"） +- **Linux (Debian/Ubuntu)**: `sudo apt install python3 python3-pip` +- **Linux (Fedora/RHEL)**: `sudo dnf install python3 python3-pip` + +如需更详细的环境配置帮助，加载 `environment-setup` 技能。 + +### Python 包依赖 + +本技能的 Python 脚本依赖以下包（按需检测，仅在实际调用相关脚本时检查）： + +- `lxml` — XML schema 验证（validate.py） +- `defusedxml` — 安全 XML 解析（unpack.py） + +检测方法： +```bash +python3 -c "import lxml; import defusedxml" 2>/dev/null || echo "MISSING" +``` + +缺失时告知用户安装：`pip install lxml defusedxml` + ## Output Rule When you create or modify a .docx file, you **MUST** tell the user the absolute path of the output file in your response. Example: "文件已保存到：`/path/to/output.docx`" diff --git a/skills/environment-setup/SKILL.md b/skills/environment-setup/SKILL.md new file mode 100644 index 0000000..dc4d37e --- /dev/null +++ b/skills/environment-setup/SKILL.md @@ -0,0 +1,901 @@ +--- +name: 开发环境配置 +description: >- + Use this skill when the user needs help setting up a development environment, + installing Python, Node.js, or their package managers, managing multiple + runtime versions, creating virtual environments, or troubleshooting + environment-related issues. Triggers include: "install python", "install + node", "setup environment", "virtual environment", "venv", "nvm", "pyenv", + "pip not found", "python not found", "node not found", "npm not found", + "PATH issues", "version manager", or any error message indicating a missing + runtime or package manager. 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、环境配置、虚拟环境、 + 版本管理、PATH问题、pip找不到、python找不到。 +version: 1.0.0 +type: procedural +risk_level: low +status: enabled +disable-model-invocation: false +tags: + - environment + - python + - nodejs + - setup + - troubleshooting +metadata: + author: desirecore + updated_at: '2026-04-08' +market: + icon: >- + + short_desc: Python / Node.js 环境安装、版本管理与问题排查 + category: productivity + maintainer: + name: DesireCore Official + verified: true + channel: latest +--- + +# Environment Setup Guide + +本技能提供 Python 和 Node.js 开发环境的完整安装、多版本管理、虚拟环境配置以及常见问题排查指南。 + +--- + +## 快速诊断 + +在进行任何安装之前，先运行以下命令检查当前环境状态： + +```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 "=== PATH ===" && echo "$PATH" | tr ':' '\n' +``` + +根据输出结果，跳转到对应章节。 + +--- + +## 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 多版本管理（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 多版本管理（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（更快的替代品） + +[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 +``` + +--- + +## 系统工具安装 + +### 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/pdf/SKILL.md b/skills/pdf/SKILL.md index 0516a8a..b264863 100644 --- a/skills/pdf/SKILL.md +++ b/skills/pdf/SKILL.md @@ -45,6 +45,42 @@ market: # PDF Processing Guide +## Prerequisites + +### Python 3（必需） + +在执行任何 Python 操作之前，先检测 Python 是否可用： + +```bash +python3 --version 2>/dev/null || python --version 2>/dev/null +``` + +如果命令失败（Python 不可用），**必须停止并告知用户安装 Python 3**： + +- **macOS**: `brew install python3` 或从 https://www.python.org/downloads/ 下载 +- **Windows**: `winget install Python.Python.3` 或从 python.org 下载（安装时勾选 "Add Python to PATH"） +- **Linux (Debian/Ubuntu)**: `sudo apt install python3 python3-pip` +- **Linux (Fedora/RHEL)**: `sudo dnf install python3 python3-pip` + +如需更详细的环境配置帮助，加载 `environment-setup` 技能。 + +### Python 包依赖 + +本技能依赖以下 Python 包（按需检测）： + +- `pypdf` — PDF 基础操作（读取、合并、拆分、旋转） +- `pdfplumber` — 表格提取、带布局的文本提取 +- `Pillow` — 图片处理（水印、验证图等） +- `reportlab` — PDF 创建（可选，按需安装） +- `pdf2image` — PDF 转图片（可选，需要 poppler） + +核心包检测： +```bash +python3 -c "import pypdf; import pdfplumber; import PIL" 2>/dev/null || echo "MISSING" +``` + +缺失时告知用户安装：`pip install pypdf pdfplumber Pillow` + ## Output Rule When you create or modify a .pdf file, you **MUST** tell the user the absolute path of the output file in your response. Example: "文件已保存到：`/path/to/output.pdf`" diff --git a/skills/pptx/SKILL.md b/skills/pptx/SKILL.md index 8e8b308..566b06b 100644 --- a/skills/pptx/SKILL.md +++ b/skills/pptx/SKILL.md @@ -50,6 +50,41 @@ market: # PPTX Skill +## Prerequisites + +### Python 3（必需 — 读取和编辑现有 PPTX 时需要） + +在执行任何 Python 脚本之前，先检测 Python 是否可用： + +```bash +python3 --version 2>/dev/null || python --version 2>/dev/null +``` + +如果命令失败（Python 不可用），**必须停止并告知用户安装 Python 3**： + +- **macOS**: `brew install python3` 或从 https://www.python.org/downloads/ 下载 +- **Windows**: `winget install Python.Python.3` 或从 python.org 下载（安装时勾选 "Add Python to PATH"） +- **Linux (Debian/Ubuntu)**: `sudo apt install python3 python3-pip` +- **Linux (Fedora/RHEL)**: `sudo dnf install python3 python3-pip` + +注意：从零创建 PPTX 使用 pptxgenjs（Node.js），不需要 Python。 + +如需更详细的环境配置帮助，加载 `environment-setup` 技能。 + +### Python 包依赖 + +本技能的 Python 操作依赖以下包（按需检测）： + +- `markitdown[pptx]` — PPTX 内容读取 +- `Pillow` — 缩略图生成 + +检测方法： +```bash +python3 -c "import markitdown; import PIL" 2>/dev/null || echo "MISSING" +``` + +缺失时告知用户安装：`pip install "markitdown[pptx]" Pillow` + ## Output Rule When you create or modify a .pptx file, you **MUST** tell the user the absolute path of the output file in your response. Example: "文件已保存到：`/path/to/output.pptx`" diff --git a/skills/xlsx/SKILL.md b/skills/xlsx/SKILL.md index f6f4622..324df1c 100644 --- a/skills/xlsx/SKILL.md +++ b/skills/xlsx/SKILL.md @@ -50,6 +50,39 @@ market: channel: latest --- +## Prerequisites + +### Python 3（必需） + +在执行任何 Python 操作之前，先检测 Python 是否可用： + +```bash +python3 --version 2>/dev/null || python --version 2>/dev/null +``` + +如果命令失败（Python 不可用），**必须停止并告知用户安装 Python 3**： + +- **macOS**: `brew install python3` 或从 https://www.python.org/downloads/ 下载 +- **Windows**: `winget install Python.Python.3` 或从 python.org 下载（安装时勾选 "Add Python to PATH"） +- **Linux (Debian/Ubuntu)**: `sudo apt install python3 python3-pip` +- **Linux (Fedora/RHEL)**: `sudo dnf install python3 python3-pip` + +如需更详细的环境配置帮助，加载 `environment-setup` 技能。 + +### Python 包依赖 + +本技能依赖以下 Python 包（按需检测）： + +- `openpyxl` — Excel 文件创建和编辑（公式、格式） +- `pandas` — 数据分析和读写 + +检测方法： +```bash +python3 -c "import openpyxl; import pandas" 2>/dev/null || echo "MISSING" +``` + +缺失时告知用户安装：`pip install openpyxl pandas` + # Requirements for Outputs ## Output Rule