--- name: china-mirror-resolver description: > Self-healing China mirror source resolver. Automatically discovers, validates, and configures domestic mirror sources for pip/npm/yarn/pnpm/conda/Docker/Go/ Rust/Maven/Gradle/Homebrew/apt/yum/GitHub/HuggingFace when downloads are slow or timing out in mainland China. Trigger keywords: "换源", "镜像源", "下载慢", "超时", "timeout", "mirror", "registry", "proxy", "connection refused", "SSL error", "443", "ETIMEDOUT", "CondaHTTPError", "pip install failed". version: 2.1.0 license: MIT homepage: https://github.com/The-Ladder-of-Rrogress/china-mirror-resolver compatibility: > Requires terminal/shell access and internet connectivity. Works on Windows (PowerShell), macOS (bash/zsh), and Linux (bash). Designed for Claude Code, StepFun, and similar agentic coding assistants. Adaptable to Cursor (.mdc rules) and Windsurf (.md rules) — see Section 9. Agents without web search capability can still use baseline sources (Section 2). metadata: author: community category: devtools region: china-mainland last-verified: "2026-03-08" clawdbot: emoji: "🪞" files: ["scripts/*", "references/*"] allowed-tools: WebSearch WebFetch terminal file-read file-write --- # 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 ``` 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. --- ## 1. Diagnostic Table 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\\.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 | `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/` | ### npm / yarn / pnpm | Provider | URL | |---|---| | npmmirror | `https://registry.npmmirror.com` | | Huawei | `https://repo.huaweicloud.com/repository/npm/` | ### conda | 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` | ### Docker | 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` | ### Go | Provider | URL | |---|---| | goproxy.cn | `https://goproxy.cn` | | goproxy.io | `https://goproxy.io` | ### Rust | 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` | ### Maven / Gradle | 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` | ### Homebrew (macOS / Linuxbrew) | Provider | HOMEBREW_BOTTLE_DOMAIN | |---|---| | Tsinghua TUNA | `https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles` | | USTC | `https://mirrors.ustc.edu.cn/homebrew-bottles` | ### apt (Debian / Ubuntu) | Provider | Base URL | |---|---| | Tsinghua TUNA | `https://mirrors.tuna.tsinghua.edu.cn` | | Aliyun | `https://mirrors.aliyun.com` | | USTC | `https://mirrors.ustc.edu.cn` | ### yum / dnf (CentOS / RHEL / Fedora) | Provider | Base URL | |---|---| | Tsinghua TUNA | `https://mirrors.tuna.tsinghua.edu.cn` | | Aliyun | `https://mirrors.aliyun.com` | | USTC | `https://mirrors.ustc.edu.cn` | ### GitHub Accelerator | Provider | Prefix URL | |---|---| | ghfast.top | `https://ghfast.top/` | | gh-proxy.com | `https://gh-proxy.com/` | | ghp.ci | `https://ghp.ci/` | ### Hugging Face | Provider | HF_ENDPOINT | |---|---| | hf-mirror.com | `https://hf-mirror.com` | --- ## 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 `` 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 国内镜像源可用` | `pip china mirror source working` | | npm | `npm 国内镜像 registry ` | `npm china registry mirror ` | | conda | `conda 国内镜像源 channels ` | `conda china mirror channel ` | | Docker | `docker 镜像加速源可用` | `docker registry mirror china working` | | Go | `GOPROXY 国内代理 ` | `GOPROXY china proxy ` | | Rust | `cargo crates 国内镜像 ` | `cargo crates china mirror ` | | Maven | `maven 国内镜像仓库地址 ` | `maven china mirror repository ` | | Homebrew | `homebrew 国内镜像 ` | `homebrew china mirror ` | | apt | `ubuntu apt 国内源 ` | `ubuntu apt china mirror ` | | yum/dnf | `centos yum 国内镜像源 ` | `centos yum china mirror ` | | GitHub | `github 加速代理镜像站 ` | `github proxy accelerator china ` | | HuggingFace | `huggingface 国内镜像下载加速 ` | `huggingface china mirror download ` | ### 3.2 Source Credibility Prioritize results in this order: 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 ```bash # 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 "") end=$(date +%s%N 2>/dev/null || perl -MTime::HiRes=time -e 'printf "%d\n",time()*1e9') echo "HTTP $code | $(( (end - start) / 1000000 ))ms" ``` ```powershell # Windows PowerShell $sw = [System.Diagnostics.Stopwatch]::StartNew() try { $r = Invoke-WebRequest -Uri "" -TimeoutSec 10 -UseBasicParsing -ErrorAction Stop $sw.Stop(); "OK: HTTP $($r.StatusCode) | $($sw.ElapsedMilliseconds)ms" } catch { $sw.Stop(); "FAIL: $_" } ``` ### 4.2 Tool-Specific Validation | Tool | Command / Check | Success Criteria | |---|---|---| | pip | `pip install --dry-run requests -i --trusted-host ` | `Would install` or `already satisfied` | | npm | `npm view lodash version --registry ` | Returns version number | | yarn v1 | `yarn info lodash version --registry ` | Returns version number | | pnpm | `pnpm view lodash version --registry ` | Returns version number | | conda | `conda search numpy -c --override-channels` | Returns package list | | Docker | HTTP GET `/v2/` | HTTP 401 (auth required = service alive) | | Go | HTTP GET `/github.com/gin-gonic/gin/@v/list` | Returns version list | | Rust | HTTP GET the sparse index URL | HTTP 200 | | Maven | HTTP GET `/org/apache/commons/commons-lang3/maven-metadata.xml` | Returns XML content | | HuggingFace | HTTP GET `/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. - `scripts/validate.ps1` — Windows (PowerShell) ```bash 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 ``` ### 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. **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`](references/config-templates.md). > Below is a quick reference of the key commands. ### Quick Reference **pip**: `pip config set global.index-url ` **npm**: `npm config set registry ` **yarn v1**: `yarn config set registry ` **yarn v2+**: `yarn config set npmRegistryServer ` **pnpm**: `pnpm config set registry ` **conda**: `conda config --add channels && 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=,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 `` block to `~/.m2/settings.xml` **Gradle (Groovy)**: Add `maven { url '' }` to `repositories` block **Gradle (Kotlin)**: Add `maven(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 https://github.com//.git` **HuggingFace**: Set `HF_ENDPOINT=` env var --- ## 6. Restore Official Sources | 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 `` 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 | |---|---|---| | `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 | --- ## 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: ``` --- 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.

China Mirror Resolver

Description

Latest Changes

Install China Mirror Resolver with One Click