使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。当用户说"下载镜像"、"拉取镜像"、"pull xxx"、"帮我下载 nginx 镜像"等触发此技能。支持 SOCKS5 代理直连下载(推荐)和国内镜像站加速两种模式。
---
name: docker-image-puller
description: 使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。当用户说"下载镜像"、"拉取镜像"、"pull xxx"、"帮我下载 nginx 镜像"等触发此技能。支持 SOCKS5 代理直连下载(推荐)和国内镜像站加速两种模式。
---
# Docker 镜像拉取工具
从任意 Docker Registry 拉取镜像,打包为 `.tar` 文件供离线 `docker load` 使用。
## 资源文件
- 脚本:`scripts/docker_image_puller.py`
- 配置:`config.json`(首次运行时引导生成)
## 首次使用 — 配置引导
检查 `config.json` 中 `arch` 字段:
- 若为空(`""` 或不存在),引导用户完成首次配置:
1. **下载方式** — 代理下载(推荐,最稳定)或镜像加速
2. **代理地址**(代理模式)— 默认 `127.0.0.1:7890`
3. **镜像站地址**(镜像模式)— 或让脚本运行时显示推荐列表
4. **目标架构** — `amd64`(x86 服务器,默认)或 `arm64v8`(ARM 服务器)
- 若 `arch` 已有值,跳过引导,直接使用该配置
`script_dir` 自动解析为技能自带的 `scripts/` 目录。
### config.json 结构
```json
{
"mode": "proxy",
"proxy_address": "127.0.0.1:7890",
"mirror_url": "",
"arch": "",
"script_dir": "",
"version": 1
}
```
`arch` 为空时触发首次引导。
## 执行流程
### 1. 读取配置,构建命令(安全执行)
读取 `config.json`,根据 mode 构建命令。使用 `exec` 的 `shell=false`(参数数组)方式调用,避免 shell 注入。
**代理模式:**
```python
exec(
command="python3 docker_image_puller.py -i '<image>' --socks5 --socks5-proxy '<proxy>' -a '<arch>'",
workdir="<script_dir>"
)
```
**镜像加速模式:**
```python
exec(
command="printf 'y\\ny\\n<mirror>' | python3 docker_image_puller.py -i '<image>' -a '<arch>'",
workdir="<script_dir>"
)
```
> ⚠️ 镜像名必须为合法 Docker 镜像引用(仅含字母、数字、`/`、`:`、`-`、`.`、`_`),包含其他字符时先向用户确认。
### 2. Sub-Agent 后台下载
使用 `sessions_spawn` 启动隔离子任务,不阻塞主会话:
```
sessions_spawn(
task="读取 <skill-dir>/config.json 获取配置。为镜像 '<镜像名>' 构建下载命令。用 exec 执行(background=true, timeout=600)。每 30 秒用 process 轮询进度。完成后报告 tar 路径和 docker load 命令。失败则报告具体原因。",
mode="run",
runtime="subagent",
timeoutSeconds=900
)
```
立即回复用户:
> 📥 已启动后台下载 `<镜像名>`(架构:<架构>)... 完成后会通知你,可继续其他操作。
### 3. 结果报告
| 结果 | 处理方式 |
|------|---------|
| ✅ 成功 | 报告 tar 文件路径 + `docker load -i <路径>` |
| ⏱ 超时 | "下载超时,请检查网络或代理" |
| 🔒 认证失败 401 | 请用户提供仓库用户名/密码 |
| 🌐 网络错误 | 报告具体 HTTP 错误码和失败 URL |
| 💾 磁盘不足 | 提醒用户清理磁盘空间 |
## 补充说明
- **安全**:脚本启用 HTTPS 证书校验(`verify=True`),不再禁用 TLS 验证。执行镜像下载时使用参数数组而非 shell 拼接,防止命令注入。
- 输出路径:`<script_dir>/images/<仓库>_<标签>_<架构>.tar`
- 脚本运行完毕后自动清理 `tmp/` 临时目录,无需手动处理
- `config.json` 跨次复用,用户可随时要求切换下载模式或指定架构
don't have the plugin yet? install it then click "run inline in claude" again.