QClaw依赖缺失修复：pip install报错解决方案

执行 pip install qclaw 时若遭遇 ModuleNotFoundError: No module named 'xxx' 或 error: subprocess-exited-with-error，不应急于归咎于 QClaw 本身。此类故障通常源自底层依赖问题——pyarrow、numpy、scipy、pillow 等库缺失或版本冲突，尤其在 Windows 平台，缺少 VC++ 运行时或编译工具链会直接导致 wheel 构建失败。以下步骤可精准定位并解决。

验证 Python 环境纯净度与版本兼容性

第一步：启动终端，执行 python -c "import sys; print(sys.executable)"，确认当前激活的 Python 解释器路径——此步不可或缺，否则后续 pip install 可能部署至错误环境。

第二步：验证 pip 状态，运行 python -m pip --version。若返回 No module named pip，请跳至「重装 pip 组件」章节；若显示版本号（例如 pip 24.1.1），则继续执行后续步骤。

第三步：核对 Python 版本是否处于 QClaw 官方支持列表。参考其 GitHub README 或 PyPI 页面，截至 2026 年中，QClaw 仅兼容 Python 3.8～3.12。若当前环境为 Python 3.13 或 ≤3.7，务必降级或升级至指定范围，强行安装将引发 setup.py 编译错误。

重建 pip 组件（应对 ModuleNotFoundError: No module named 'pip'）

方法一：使用 ensurepip 强制重建（推荐）
在终端运行：python -m ensurepip --upgrade --default-pip。
此操作将从 Python 内置模块中恢复 pip 及其依赖（setuptools、wheel），无需网络下载，版本自动匹配当前 Python 发行版。

方法二：手动修复（仅当方法一触发 No module named ensurepip 时采用）
这表明您正在使用 Alpine Linux 的 python3-minimal 或其他嵌入式精简版 Python——此时应彻底卸载当前 Python，改从官网获取完整安装包重新部署，否则无法满足 QClaw 对编译型依赖的要求。

部署核心依赖并避免编译报错

① 优先安装预编译 Wheel 友好型基础库：
python -m pip install --prefer-binary numpy scipy pandas
--prefer-binary 参数强制跳过源码编译，仅下载预构建的二进制 Wheel，显著降低因 GCC/MSVC 缺失而引发 subprocess-exited-with-error 的风险。

② 安装图像处理库（QClaw 频繁调用 PIL 接口）：
python -m pip install Pillow
注意：切勿使用 pip install PIL，该包已停止维护；导入时依旧使用 from PIL import Image 而非 import pillow。

③ 安装 Arrow 加速引擎（QClaw 高频依赖）：
Windows 用户：直接执行 python -m pip install pyarrow，官方已提供完整 Wheel。
Linux/macOS 用户：若遇到 failed building wheel for pyarrow，先运行 sudo apt-get install libarrow-dev libparquet-dev（Ubuntu/Debian）或 brew install apache-arrow（macOS），随后重试安装。

更换国内镜像源并清除缓存

临时设置（单次安装生效）：
python -m pip install qclaw -i https://pypi.tuna.tsinghua.edu.cn/simple/

永久配置（避免每次附加参数）：
Windows：于 %APPDATA%\pip\pip.ini 中添加：
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple/
trusted-host = pypi.tuna.tsinghua.edu.cn

Linux/macOS：将相同内容写入 ~/.pip/pip.conf。
配置完成后，务必执行 python -m pip cache purge 清除陈旧缓存——缓存损坏是导致 egg_info failed 的隐蔽诱因，不清除则极易复现错误。

检验安装成果

执行：python -c "import qclaw; print(qclaw.__version__)"。
若返回版本号（如 0.4.2），则安装成功。若依旧报错，请复制完整错误信息，关注最后一行是否包含 ImportError 或 ModuleNotFoundError，然后针对性运行 python -m pip install 模块名 补齐缺失模块。