China Mirror Resolver

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.

---

Execution Flow

CODEBLOCK0

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.

---

1. Diagnostic Table

Match error keywords to identify the tool, then check current config:

Error keywords	Tool	Detect current source
INLINECODE0 / PyPI / setup.py / INLINECODE3	pip	INLINECODE4
INLINECODE5 / INLINECODE6

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 |

---

2. Baseline Sources

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.

pip

Provider	URL
Tsinghua TUNA	INLINECODE69
Aliyun

https://mirrors.aliyun.com/pypi/simple/ |

| USTC | https://pypi.mirrors.ustc.edu.cn/simple/ | | Tencent | https://mirrors.cloud.tencent.com/pypi/simple/ |

npm / yarn / pnpm

Provider	URL
npmmirror	INLINECODE73
Huawei

https://repo.huaweicloud.com/repository/npm/ |

conda

Provider	URL
Tsinghua TUNA	INLINECODE75
USTC

https://mirrors.ustc.edu.cn/anaconda/pkgs/main |

| Aliyun | https://mirrors.aliyun.com/anaconda/pkgs/main |

Docker

Provider	URL
1ms.run	INLINECODE78
xuanyuan.me

https://docker.xuanyuan.me |

| DaoCloud | https://docker.m.daocloud.io | | linkedbus | https://docker.linkedbus.com |

Go

Provider	URL
goproxy.cn	INLINECODE82
goproxy.io

https://goproxy.io |

Rust

Provider	cargo registry	rustup server
USTC	INLINECODE84	INLINECODE85
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 |

Maven / Gradle

Provider	URL
Aliyun Public	INLINECODE90
Aliyun Google

https://maven.aliyun.com/repository/google |

| Huawei | https://repo.huaweicloud.com/repository/maven |

Homebrew (macOS / Linuxbrew)

Provider	HOMEBREWBOTTLEDOMAIN
Tsinghua TUNA	INLINECODE93
USTC

https://mirrors.ustc.edu.cn/homebrew-bottles |

apt (Debian / Ubuntu)

Provider	Base URL
Tsinghua TUNA	INLINECODE95
Aliyun

https://mirrors.aliyun.com |

| USTC | https://mirrors.ustc.edu.cn |

yum / dnf (CentOS / RHEL / Fedora)

Provider	Base URL
Tsinghua TUNA	INLINECODE98
Aliyun

https://mirrors.aliyun.com |

| USTC | https://mirrors.ustc.edu.cn |

GitHub Accelerator

Provider	Prefix URL
ghfast.top	INLINECODE101
gh-proxy.com

https://gh-proxy.com/ |

| ghp.ci | https://ghp.ci/ |

Hugging Face

Provider	HF_ENDPOINT
hf-mirror.com	INLINECODE104

---

3. Search Strategy

Capability gate: This section requires web search. If the agent lacks
search capability, skip to Section 5 using only baseline sources.

3.1 Search Query Templates

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	INLINECODE106	INLINECODE107
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> |

3.2 Source Credibility

Prioritize results in this order:

1. 1. Official mirror site docs (mirrors.tuna.tsinghua.edu.cn/help, developer.aliyun.com/mirror)
2. Mirror provider's own site/README (goproxy.cn, npmmirror.com)
3. Recent posts (< 3 months) from reputable tech communities
4. GitHub repos with > 100 stars that aggregate mirror lists

Reject: undated articles, posts > 6 months old, zero-reply forum threads, unverifiable personal blogs.

3.3 Candidate Extraction Rules

Extracted URLs must:

• - Use HTTPS protocol
• Belong to known institutions (.edu.cn, major cloud vendors, well-known OSS orgs) OR be cross-referenced in 2+ independent articles
• Come from articles published within the last 6 months

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.

---

4. Validation

Every candidate must pass validation before being written to config.

4.1 Universal HTTP Check

CODEBLOCK1

CODEBLOCK2

4.2 Tool-Specific Validation

Tool	Command / Check	Success Criteria
pip	INLINECODE130	INLINECODE131 or INLINECODE132
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 |

4.3 Acceptance Criteria

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.

4.4 Batch Validation Scripts

Pre-built scripts in scripts/:

• - scripts/validate.sh — Linux / macOS (bash). Supports --json flag for machine-readable output.
• INLINECODE144 — Windows (PowerShell)

CODEBLOCK3

4.5 Security Notes on Validation

trusted-host warning: Using --trusted-host with 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 require trusted-host.

---

5. Configuration

Core Principles

1. 1. Backup first — Always backup the original config file before modifying
2. Merge, don't overwrite — For JSON configs (Docker daemon.json), read existing content and merge new fields. Never blindly overwrite the entire file
3. Permanent config — Write to config files, not just CLI flags
4. Verify after write — Run a test command to confirm the new source works

Detailed configuration templates for each tool are in
references/config-templates.md.
Below is a quick reference of the key commands.

Quick Reference

pip: INLINECODE149

npm: INLINECODE150

yarn v1: INLINECODE151

yarn v2+: INLINECODE152

pnpm: INLINECODE153

conda: INLINECODE154

Docker: Read existing daemon.json, add/update registry-mirrors array, write back, restart Docker. See references/config-templates.md for merge logic.

Go: INLINECODE158

Rust (cargo): Write [source.crates-io] + [source.mirror] to INLINECODE161

Rust (rustup): Set RUSTUP_DIST_SERVER and RUSTUP_UPDATE_ROOT env vars

Maven: Add <mirror> block to INLINECODE165

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 INLINECODE175

yum/dnf: Backup /etc/yum.repos.d/, replace baseurl in repo files, then INLINECODE178

GitHub: Prepend accelerator prefix: INLINECODE179

HuggingFace: Set HF_ENDPOINT=<URL> env var

---

6. Restore Official Sources

Tool	Restore Command
pip	INLINECODE181
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 |

---

7. Notes

• - Docker & GitHub accelerators have the highest churn rate — always validate before configuring
• If the user has an enterprise Nexus/Artifactory, prefer that over public mirrors
• WSL 1 and WSL 2 have different network stacks; WSL 2 has its own IP and needs separate Docker/apt config
• If HTTP_PROXY / HTTPS_PROXY env vars are set, some tools may bypass mirrors and go through the proxy instead
• On ARM architectures (Apple Silicon, ARM Linux), verify that the mirror hosts packages for your architecture
• When multiple Python/Node versions coexist (pyenv, nvm, conda envs), config may need to target specific environments rather than global settings
• Use scripts/validate.sh or scripts/validate.ps1 for periodic health checks

---

8. Known Unstable Sources

This section is informational. Always validate before use rather than
relying solely on this list, which may itself become outdated.

Source	Status (2026-03)	Notes
INLINECODE202 (pip)	Dead	Connection reset
INLINECODE203 (GitHub)

Dead | SSL certificate untrusted | | mirrors.aliyun.com/goproxy/ (Go) | Unstable | Homepage 404, module downloads intermittent |

---

9. Cross-Agent Adaptation

Capability Requirements

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 |

Platform Adaptation

Claude Code / StepFun: Native support. Place folder in ~/.claude/skills/ or ~/.stepfun/skills/.

Cursor: Create .cursor/rules/china-mirror-resolver.mdc with this content:
CODEBLOCK4

Windsurf: Create .windsurf/rules/china-mirror-resolver.md with this content:
CODEBLOCK5

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.