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:

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

npm / yarn / pnpm

conda

Docker

Go

Rust

Maven / Gradle

Homebrew (macOS / Linuxbrew)

apt (Debian / Ubuntu)

yum / dnf (CentOS / RHEL / Fedora)

GitHub Accelerator

Hugging Face

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:

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

# 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: $_" }

4.2 Tool-Specific Validation

4.3 Acceptance Criteria

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 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.

> 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

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.

9. Cross-Agent Adaptation

Capability Requirements

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.