From e743d44e860ca14dc152917f1a33fbe1395bef26 Mon Sep 17 00:00:00 2001
From: Gingiris <iris103195@gmail.com>
Date: Sat, 23 May 2026 06:11:15 +0300
Subject: [PATCH] docs: refresh README with overview, quick start, and usage

---
 README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 56 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index cde7a9f..c50b90f 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,68 @@
-# SystemProxy - Free Clash Subscribe
+# SystemProxy
 
-Update Manually or Automatically by using crontab.
+![License](https://img.shields.io/github/license/SnapdragonLee/SystemProxy)
+![Python](https://img.shields.io/badge/Python-3-blue)
+![Stars](https://img.shields.io/github/stars/SnapdragonLee/SystemProxy?style=social)
 
-All Proxies Are Collected From Public Content On The Internet.
+SystemProxy aggregates publicly available Clash proxy subscriptions, removes duplicates and blacklisted nodes, and writes ready-to-use YAML configs into `dist/`.
 
+## What it does
+- fetches Clash subscription sources from public feeds and extra proxy pools
+- merges proxies into a single config based on `clash.config.template.yaml`
+- skips duplicate nodes and entries listed in `blacklists.txt`
+- generates standard and extra variants, including a US-focused config in `clash_extra.py`
+- works for one-off runs or scheduled refreshes with cron
 
+## Table of Contents
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [Generated Files](#generated-files)
+- [Project Structure](#project-structure)
+- [Customization](#customization)
+- [Disclaimer](#disclaimer)
 
-### Clash Subscribing URL:
+## Requirements
+- Python 3
+- `pip`
+- network access to the upstream subscription sources
 
-- `https://raw.githubusercontent.com/SnapdragonLee/SystemProxy/master/dist/clash_config.yaml`
-- `https://raw.githubusercontent.com/SnapdragonLee/SystemProxy/master/dist/clash_config_extra.yaml` (Not recommended)
-- `https://raw.githubusercontent.com/SnapdragonLee/SystemProxy/master/dist/clash_config_extra_US.yaml`
+## Quick Start
+```bash
+git clone https://github.com/SnapdragonLee/SystemProxy.git
+cd SystemProxy
+pip install -r requirements.txt
+python clash.py
+python clash_extra.py
+```
+
+Generated configs are written to `dist/`.
 
+## Generated Files
+- `dist/clash_config.yaml`: config merged from the RSS-discovered sources in `clash.py`
+- `dist/clash_config_extra.yaml`: config merged from the extra source list in `clash_extra.py`
+- `dist/clash_config_extra_US.yaml`: US-filtered variant generated by `clash_extra.py`
 
+## Project Structure
+```text
+.
+├── clash.py                    # fetch RSS-based subscription sources
+├── clash_extra.py              # fetch extra subscription sources concurrently
+├── clash.config.template.yaml  # base template used for output
+├── blacklists.txt              # nodes to exclude by server:port
+├── dist/                       # generated Clash configs
+└── requirements.txt            # Python dependencies
+```
 
-### Manually Run
+## Customization
+- update `blacklists.txt` to exclude specific endpoints
+- edit `clash.config.template.yaml` to change proxy groups or routing rules
+- adjust the `clash_extra` source list in `clash_extra.py` if you want different upstream pools
+- use cron to refresh the generated configs automatically
 
-```shell
-pip install -r reqirements.txt
-python clash.py / clash_extra_xx.py
+Example cron job:
+```cron
+0 */6 * * * cd /path/to/SystemProxy && /usr/bin/python3 clash.py && /usr/bin/python3 clash_extra.py
 ```
 
-After having done these steps, import yaml file from `./dist/` into Clash Clients, then enjoy!
+## Disclaimer
+All proxies are collected from public internet sources. Review the generated endpoints before use and make sure your usage complies with local laws, service terms, and security requirements.