pip-mirror — 国内镜像加速 Python 包安装

核心：三个内置脚本

本技能捆绑了三个可直接运行的 Python 脚本。执行 pip 相关任务时，优先使用这些脚本，而不是自己手动构造命令。 这些脚本已经涵盖了镜像选择、速度测试、错误恢复、包名纠错等全部逻辑。

执行方式： 所有脚本使用技能的 scripts/ 目录。

# Windows
python scripts/auto_install.py <包名>

# macOS / Linux
python scripts/auto_install.py <包名>

脚本 1: auto_install.py — 自动安装（核心）

python scripts/auto_install.py <包名> [额外pip参数]

• 自动遍历 6 面镜像链（清华→阿里→中科大→豆瓣→腾讯→官方PyPI）
• 每个镜像失败自动切换到下一个
• 自动检测错误类型（NETWORK / NOT_FOUND / SSL / CONFLICT / PERMISSION）
• SSL 错误自动追加 --trusted-host 重试
• 常见包名纠错：opencv → opencv-python，sklearn → scikit-learn 等
• 安装成功会输出 JSON 摘要（包名、使用的镜像、耗时、尝试次数）
• 全部失败输出诊断报告（包不存在 vs 网络问题）

脚本 2: speed_test.py — 测速最快镜像

python scripts/speed_test.py              # 测试所有镜像
python scripts/speed_test.py --top 3      # 只显示前三快的
python scripts/speed_test.py --json       # JSON 格式输出

• 测试每个镜像的下载速度
• 按速度排序，推荐最快的和永久配置命令
• 当用户问"哪个镜像最快"、"pip 很慢"时使用

脚本 3: check_mirrors.py — 在线检测

python scripts/check_mirrors.py           # 检测所有镜像连通性
python scripts/check_mirrors.py --json    # JSON 输出

• 快速检测每个镜像是否可达
• 额外检测 SSL 证书是否有效
• 当用户遇到连接错误或镜像不可用时使用

工作流程

场景 A：安装包

用户: 帮我装一下 requests

1. 直接运行 python scripts/auto_install.py <包名>
2. 等待脚本完成
3. 验证：python -c "import <包名>; print(<包名>.__version__)"
4. 把脚本输出的 summary 读给用户听（用了哪个镜像、耗时多长）

场景 B：pip 很慢 / 找最快镜像

用户: pip 下载好慢

1. 运行 python scripts/speed_test.py --top 3
2. 用最快的镜像配置用户环境
3. 可选的：python -m pip config set global.index-url <最快镜像URL>
4. 告知用户速度对比结果

场景 C：配置永久镜像

用户: 帮我配置成清华源

直接使用 python -m pip config set 命令：

python -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
python -m pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

场景 D：安装失败 / 错误恢复

用户: 装不上，报错了

1. 先执行 python scripts/auto_install.py <包名> —— 脚本会自动处理大多数错误恢复
2. 如果 auto_install.py 也失败：
   - 关注脚本输出中的 error_type
   - NOT_FOUND：包名可能拼错，询问用户
   - TIMEOUT/NETWORK：建议检查代理或网络
   - SSL：脚本已自动重试，若仍失败提示更新 certifi
   - PERMISSION：建议创建新的虚拟环境

场景化决策树

用户请求安装/配置pip
        │
        ▼
   ┌─ 安装包 ──────────────────────────────────────────┐
   │  使用 python scripts/auto_install.py <包>        │
   │  成功 → 展示结果 + 验证                            │
   │  失败 → 读取脚本诊断 → 根据 error_type 处理        │
   └────────────────────────────────────────────────────┘

   ┌─ pip 慢 / 找最快镜像 ─────────────────────────────┐
   │  使用 python scripts/speed_test.py --top 3       │
   │  展示排名 → 推荐最快的 → 可选永久配置              │
   └────────────────────────────────────────────────────┘

   ┌─ 配置永久镜像 ────────────────────────────────────┐
   │  python -m pip config set global.index-url <URL>          │
   │  python -m pip config set global.trusted-host <HOST>      │
   └────────────────────────────────────────────────────┘

   ┌─ 检查镜像连通性 ──────────────────────────────────┐
   │  使用 python scripts/check_mirrors.py            │
   └────────────────────────────────────────────────────┘

为什么用脚本而不是手动操作

auto_install.py 做了这些手动操作做不到或容易遗漏的事：
1. 错误类型智能分类 — 自动区分包不存在 vs 网络问题 vs SSL 问题
2. 内置包名纠正 — opencv→opencv-python、sklearn→scikit-learn
3. 自动 SSL 重试 — SSL 证书问题自动追加 --trusted-host
4. 结构化 JSON 输出 — 方便读取错误原因和成功信息
5. 准确的 timeouts — 每个镜像 120s 超时，手动操作容易忘记

镜像回退链（供脚本和手动操作参考）

永久配置（不用脚本时手动执行）

python -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
python -m pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn

配置文件位置

• Windows: %APPDATA%\pip\pip.ini → 内容：
  ini [global] index-url = https://pypi.tuna.tsinghua.edu.cn/simple trusted-host = pypi.tuna.tsinghua.edu.cn
• Linux/macOS: ~/.pip/pip.conf

通用原则

• 脚本优先：scripts/ 目录下的脚本比手动操作更快、更可靠。subagent 必须优先使用它们。
• 不要重复造轮子：auto_install.py 已经处理了镜像轮询、错误分类、包名纠错。不要自己写一个二次循环。
• 非脚本情况：只有配置永久镜像（pip config set）这种极简操作不需要脚本。
• 验证：安装完成后总是用 import 验证。
• 报告：用脚本输出的结构化数据告诉用户结果，而不是模糊的"装好了"。