Self-healing China mirror source resolver. Automatically discovers, validates, and configures domestic mirror sources for pip/npm/yarn/pnpm/conda/Docker/Go/...
Mirror URLs break frequently. This skill teaches the agent a self-healing workflow: discover → validate → configure the best available source. A baseline table provides offline fallback; web search enables self-repair.
User error / request
│
▼
1. Identify tool type (Section 1)
│
▼
2. Detect current source config
│
▼
3. Try ALL baseline sources for that tool (Section 2)
Validate each with Section 4 thresholds (< 3s = good, 3–10s = acceptable)
├─ At least one source < 10s → pick fastest → go to step 6
└─ All sources > 10s or failed ↓
▼
4. [IF search capable] Search for latest sources (Section 3)
├─ Found candidates → go to step 5
└─ No candidates found → report to user with baseline table as reference
[IF no search] Report baseline failure to user, suggest manual URL
│
▼
5. Validate ALL candidates (Section 4), pick fastest passing one
├─ At least one passes → go to step 6
└─ All fail → report failure to user, suggest checking network/proxy
│
▼
6. Backup original config → write new config → verify with test command
│
▼
7. Confirm result to user (show old source → new source, response time)
Graceful degradation: If the agent has no web search capability, skip step 4 and use only the baseline table. The skill remains functional with reduced self-healing ability.
Speed selection: When multiple sources pass validation, always select the one with the lowest response time. Test all candidates, not just the first.
Match error keywords to identify the tool, then check current config:
| Error keywords | Tool | Detect current source |
|---|---|---|
pip / PyPI / setup.py / No matching distribution | pip | pip config get global.index-url |
npm ERR / FETCH_ERROR | npm | npm config get registry |
yarn / ESOCKETTIMEDOUT | yarn | yarn config get registry (v1) / yarn config get npmRegistryServer (v2+) |
pnpm / ERR_PNPM | pnpm | pnpm config get registry |
conda / CondaHTTPError / PackagesNotFoundError | conda | conda config --show channels |
docker / pull / manifest / toomanyrequests | Docker | Linux/macOS: docker info | grep -A5 "Registry Mirrors" / Win: Docker Desktop → Settings → Docker Engine |
go: downloading / GOPROXY / dial tcp | Go | go env GOPROXY |
cargo / crates.io / Blocking waiting | Rust (cargo) | check ~/.cargo/config.toml (Linux/macOS) or %USERPROFILE%\.cargo\config.toml (Win) |
rustup / could not download | Rust (rustup) | echo $RUSTUP_DIST_SERVER / $env:RUSTUP_DIST_SERVER |
maven / pom.xml / BUILD FAILURE / Could not resolve | Maven | check ~/.m2/settings.xml or C:\Users\<user>\.m2\settings.xml |
gradle / Could not resolve / build.gradle | Gradle | check build.gradle / build.gradle.kts or ~/.gradle/init.gradle |
brew / Homebrew / Fetching | Homebrew | echo $HOMEBREW_BOTTLE_DOMAIN |
apt / dpkg / E: Failed to fetch | apt (Debian/Ubuntu) | check /etc/apt/sources.list |
yum / dnf / Cannot find a valid baseurl | yum/dnf (CentOS/RHEL/Fedora) | check /etc/yum.repos.d/ |
git clone / github.com / RPC failed | GitHub accelerator | N/A |
huggingface / hf_hub / ConnectionError | Hugging Face | echo $HF_ENDPOINT / $env:HF_ENDPOINT |
High-stability institutional mirrors. Try these first. If all fail or are too slow (> 10s), proceed to Section 3 (search). Agents without search capability stop here.
| Provider | URL |
|---|---|
| Tsinghua TUNA | https://pypi.tuna.tsinghua.edu.cn/simple |
| Aliyun | https://mirrors.aliyun.com/pypi/simple/ |
| USTC | https://pypi.mirrors.ustc.edu.cn/simple/ |
| Tencent | https://mirrors.cloud.tencent.com/pypi/simple/ |
| Provider | URL |
|---|---|
| npmmirror | https://registry.npmmirror.com |
| Huawei | https://repo.huaweicloud.com/repository/npm/ |
| Provider | URL |
|---|---|
| Tsinghua TUNA | https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main |
| USTC | https://mirrors.ustc.edu.cn/anaconda/pkgs/main |
| Aliyun | https://mirrors.aliyun.com/anaconda/pkgs/main |
| Provider | URL |
|---|---|
| 1ms.run | https://docker.1ms.run |
| xuanyuan.me | https://docker.xuanyuan.me |
| DaoCloud | https://docker.m.daocloud.io |
| linkedbus | https://docker.linkedbus.com |
| Provider | URL |
|---|---|
| goproxy.cn | https://goproxy.cn |
| goproxy.io | https://goproxy.io |
| Provider | cargo registry | rustup server |
|---|---|---|
| USTC | sparse+https://mirrors.ustc.edu.cn/crates.io-index/ | https://mirrors.ustc.edu.cn/rustup |
| Tsinghua TUNA | sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/ | https://mirrors.tuna.tsinghua.edu.cn/rustup |
| RsProxy.cn | sparse+https://rsproxy.cn/crates.io-index/ | https://rsproxy.cn/rustup |
| Provider | URL |
|---|---|
| Aliyun Public | https://maven.aliyun.com/repository/public |
| Aliyun Google | https://maven.aliyun.com/repository/google |
| Huawei | https://repo.huaweicloud.com/repository/maven |
| Provider | HOMEBREW_BOTTLE_DOMAIN |
|---|---|
| Tsinghua TUNA | https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles |
| USTC | https://mirrors.ustc.edu.cn/homebrew-bottles |
| Provider | Base URL |
|---|---|
| Tsinghua TUNA | https://mirrors.tuna.tsinghua.edu.cn |
| Aliyun | https://mirrors.aliyun.com |
| USTC | https://mirrors.ustc.edu.cn |
| Provider | Base URL |
|---|---|
| Tsinghua TUNA | https://mirrors.tuna.tsinghua.edu.cn |
| Aliyun | https://mirrors.aliyun.com |
| USTC | https://mirrors.ustc.edu.cn |
| Provider | Prefix URL |
|---|---|
| ghfast.top | https://ghfast.top/ |
| gh-proxy.com | https://gh-proxy.com/ |
| ghp.ci | https://ghp.ci/ |
| Provider | HF_ENDPOINT |
|---|---|
| hf-mirror.com | https://hf-mirror.com |
Capability gate: This section requires web search. If the agent lacks search capability, skip to Section 5 using only baseline sources.
Replace <YEAR> with current year. Use the agent's available search mechanism.
Provide both Chinese and English queries for better coverage:
| Tool | Chinese query | English query |
|---|---|---|
| pip | pip 国内镜像源 <YEAR> 可用 | pip china mirror source <YEAR> working |
| npm | npm 国内镜像 registry <YEAR> | npm china registry mirror <YEAR> |
| conda | conda 国内镜像源 channels <YEAR> | conda china mirror channel <YEAR> |
| Docker | docker 镜像加速源 <YEAR> 可用 | docker registry mirror china <YEAR> working |
| Go | GOPROXY 国内代理 <YEAR> | GOPROXY china proxy <YEAR> |
| Rust | cargo crates 国内镜像 <YEAR> | cargo crates china mirror <YEAR> |
| Maven | maven 国内镜像 仓库地址 <YEAR> | maven china mirror repository <YEAR> |
| Homebrew | homebrew 国内镜像 <YEAR> | homebrew china mirror <YEAR> |
| apt | ubuntu apt 国内源 <YEAR> | ubuntu apt china mirror <YEAR> |
| yum/dnf | centos yum 国内镜像源 <YEAR> | centos yum china mirror <YEAR> |
| GitHub | github 加速 代理 镜像站 <YEAR> | github proxy accelerator china <YEAR> |
| HuggingFace | huggingface 国内镜像 下载加速 <YEAR> | huggingface china mirror download <YEAR> |
Prioritize results in this order:
Reject: undated articles, posts > 6 months old, zero-reply forum threads, unverifiable personal blogs.
Extracted URLs must:
Security warning: Never use mirror sources from unknown individuals or unverifiable personal servers. Malicious mirrors can inject tampered packages. Especially for Docker and pip, only use sources from recognized institutions.
Every candidate must pass validation before being written to config.
# Linux / macOS
start=$(date +%s%N 2>/dev/null || perl -MTime::HiRes=time -e 'printf "%d\n",time()*1e9')
code=$(curl -o /dev/null -s -w "%{http_code}" --max-time 10 "<URL>")
end=$(date +%s%N 2>/dev/null || perl -MTime::HiRes=time -e 'printf "%d\n",time()*1e9')
echo "HTTP $code | $(( (end - start) / 1000000 ))ms"
# Windows PowerShell
$sw = [System.Diagnostics.Stopwatch]::StartNew()
try { $r = Invoke-WebRequest -Uri "<URL>" -TimeoutSec 10 -UseBasicParsing -ErrorAction Stop
$sw.Stop(); "OK: HTTP $($r.StatusCode) | $($sw.ElapsedMilliseconds)ms"
} catch { $sw.Stop(); "FAIL: $_" }
| Tool | Command / Check | Success Criteria |
|---|---|---|
| pip | pip install --dry-run requests -i <URL> --trusted-host <HOST> | Would install or already satisfied |
| npm | npm view lodash version --registry <URL> | Returns version number |
| yarn v1 | yarn info lodash version --registry <URL> | Returns version number |
| pnpm | pnpm view lodash version --registry <URL> | Returns version number |
| conda | conda search numpy -c <URL> --override-channels | Returns package list |
| Docker | HTTP GET <URL>/v2/ | HTTP 401 (auth required = service alive) |
| Go | HTTP GET <URL>/github.com/gin-gonic/gin/@v/list | Returns version list |
| Rust | HTTP GET the sparse index URL | HTTP 200 |
| Maven | HTTP GET <URL>/org/apache/commons/commons-lang3/maven-metadata.xml | Returns XML content |
| HuggingFace | HTTP GET <URL>/api/models?limit=1 | Returns JSON |
| Response Time | Rating | Action |
|---|---|---|
| < 3000ms | Excellent | Use this source |
| 3000–10000ms | Acceptable | Use if no faster alternative found |
| > 10000ms or timeout | Unusable | Try next candidate |
Selection rule: Test ALL available candidates (baseline + search-discovered), then select the one with the lowest response time that passes validation.
Pre-built scripts in scripts/:
scripts/validate.sh — Linux / macOS (bash). Supports --json flag for machine-readable output.scripts/validate.ps1 — Windows (PowerShell)bash scripts/validate.sh # test all, colored output
bash scripts/validate.sh pip # test pip only
bash scripts/validate.sh all --json # machine-readable JSON output
trusted-hostwarning: Using--trusted-hostwith pip disables SSL certificate verification for that host. This is a security trade-off. Only use it when the mirror is a known institution (e.g., .edu.cn, major cloud vendor) and the connection is within a trusted network. Prefer mirrors that have valid SSL certificates and do not requiretrusted-host.
Detailed configuration templates for each tool are in
references/config-templates.md. Below is a quick reference of the key commands.
pip: pip config set global.index-url <URL>
npm: npm config set registry <URL>
yarn v1: yarn config set registry <URL>
yarn v2+: yarn config set npmRegistryServer <URL>
pnpm: pnpm config set registry <URL>
conda: conda config --add channels <URL> && conda config --set show_channel_urls yes
Docker: Read existing daemon.json, add/update registry-mirrors array, write back, restart Docker. See references/config-templates.md for merge logic.
Go: go env -w GOPROXY=<URL>,direct && go env -w GOSUMDB=sum.golang.google.cn
Rust (cargo): Write [source.crates-io] + [source.mirror] to ~/.cargo/config.toml
Rust (rustup): Set RUSTUP_DIST_SERVER and RUSTUP_UPDATE_ROOT env vars
Maven: Add <mirror> block to ~/.m2/settings.xml
Gradle (Groovy): Add maven { url '<URL>' } to repositories block
Gradle (Kotlin): Add maven(url = "<URL>") to repositories block
Homebrew: Set HOMEBREW_BREW_GIT_REMOTE, HOMEBREW_CORE_GIT_REMOTE, HOMEBREW_BOTTLE_DOMAIN env vars
apt: Replace archive.ubuntu.com with mirror host in /etc/apt/sources.list, then sudo apt update
yum/dnf: Backup /etc/yum.repos.d/, replace baseurl in repo files, then sudo yum makecache
GitHub: Prepend accelerator prefix: git clone <PREFIX>https://github.com/<owner>/<repo>.git
HuggingFace: Set HF_ENDPOINT=<URL> env var
| Tool | Restore Command |
|---|---|
| pip | pip config unset global.index-url |
| npm | npm config set registry https://registry.npmjs.org |
| yarn v1 | yarn config set registry https://registry.yarnpkg.com |
| yarn v2+ | yarn config set npmRegistryServer https://registry.yarnpkg.com |
| pnpm | pnpm config set registry https://registry.npmjs.org |
| conda | conda config --remove-key channels |
| Go | go env -w GOPROXY=https://proxy.golang.org,direct |
| Docker | Remove registry-mirrors from daemon.json (keep other fields), restart |
| Rust (cargo) | Remove [source.*] sections from config.toml |
| Rust (rustup) | unset RUSTUP_DIST_SERVER RUSTUP_UPDATE_ROOT |
| Maven | Remove <mirror> block from settings.xml |
| Homebrew | unset HOMEBREW_BREW_GIT_REMOTE HOMEBREW_CORE_GIT_REMOTE HOMEBREW_BOTTLE_DOMAIN |
| apt | Restore /etc/apt/sources.list from backup, sudo apt update |
| yum/dnf | Restore /etc/yum.repos.d/ from backup, sudo yum makecache |
| HuggingFace | unset HF_ENDPOINT |
HTTP_PROXY / HTTPS_PROXY env vars are set, some tools may bypass mirrors and go through the proxy insteadscripts/validate.sh or scripts/validate.ps1 for periodic health checksThis section is informational. Always validate before use rather than relying solely on this list, which may itself become outdated.
| Source | Status (2026-03) | Notes |
|---|---|---|
pypi.douban.com (pip) | Dead | Connection reset |
ghproxy.cc (GitHub) | Dead | SSL certificate untrusted |
mirrors.aliyun.com/goproxy/ (Go) | Unstable | Homepage 404, module downloads intermittent |
| Capability | Required? | Used in | If absent |
|---|---|---|---|
| Terminal/shell | Required | Steps 2, 4, 5, 6 | Cannot function |
| File read/write | Required | Steps 5, 6 | Cannot write config |
| Web search | Optional | Step 4 | Use baseline table only (Section 2) |
| Web fetch | Optional | Step 4 | Use curl / Invoke-WebRequest via terminal |
Claude Code / StepFun: Native support. Place folder in ~/.claude/skills/ or ~/.stepfun/skills/.
Cursor: Create .cursor/rules/china-mirror-resolver.mdc with this content:
---
description: Resolve slow package downloads in China by switching to domestic mirrors. Triggers on: timeout, mirror, 换源, 镜像源, 下载慢
globs:
alwaysApply: false
---
[Paste the content of this SKILL.md here, excluding the YAML frontmatter]
Windsurf: Create .windsurf/rules/china-mirror-resolver.md with this content:
---
trigger: auto
---
[Paste the content of this SKILL.md here, excluding the YAML frontmatter]
Generic LLM (no skill system): Include Section 2 (baseline table) and Section 5 (config quick reference) in the system prompt. Skip Section 3 (search) if the LLM has no search tool.
ZIP package — ready to use