System Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• update_providers.py
• update_sing_box.py
• Clash/GeneralClashConfig.yml
• Clash/Providers/ProxyGFWlist.yaml
• Clash/Providers/Ruleset/AI.yaml
• Clash/Providers/Ruleset/Scholar.yaml
• Clash/Providers/ProxyLite.yaml

The Self-Rule repository provides a set of personal, self-use proxy shunting rules based on the ACL4SSR project. The system is designed to automate the generation and maintenance of rule configurations for multiple proxy clients, specifically Clash and sing-box. The core of the architecture is a set of master .list files that serve as the single source of truth for domain and IP rules. Python scripts then process these lists to generate client-specific configuration files.

The primary goal is to maintain a consistent and up-to-date set of rules across different platforms from a centralized source. The system automates the conversion of a simple, universal rule format (.list files) into the more complex, client-specific formats required by Clash (.yaml providers) and sing-box (.srs compiled rule-sets). This ensures that any update to a master list is propagated to all target configurations automatically.

Sources: README.md, update_providers.py, update_sing_box.py

Core Components

The system is composed of rule source files, client configurations, and automation scripts.

• .list Files: These are the master source files containing the raw rule data. They are located throughout the Clash/ directory (but not in Clash/Providers/ or Clash/config/). Each line represents a rule, such as DOMAIN-SUFFIX,example.com or IP-CIDR,1.1.1.1/32. These files are the single source of truth.
• .yaml Provider Files: These are generated for Clash. The update_providers.py script converts .list files into .yaml files and places them in the Clash/Providers/ directory. They follow the Clash provider format, starting with a payload: key.
• .json and .srs Rule-Set Files: These are generated for sing-box. The update_sing_box.py script converts .list files into a temporary .json format, which is then compiled into a binary .srs file using the sing-box command-line tool. The intermediate .json file is deleted after compilation.
• Python Scripts: update_providers.py and update_sing_box.py are the automation engines that drive the conversion and generation process.
• Clash Configuration: Clash/GeneralClashConfig.yml is a comprehensive template configuration file for a Clash client, demonstrating how the generated providers can be used. It also includes extensive bypass lists.

Sources: update_providers.py:11-13, update_sing_box.py:70-72, Clash/GeneralClashConfig.yml, Clash/Providers/ProxyGFWlist.yaml

The following diagram illustrates the relationship between the different file types in the repository.

Rule Generation and Conversion Flow

The entire system is built around the automated conversion of .list files into formats usable by Clash and sing-box. Two separate Python scripts handle this process.

Clash Provider Generation (update_providers.py)

This script generates .yaml files for Clash.

1. Scan for Source Files: The script walks through the Clash/ directory, ignoring the Clash/config and Clash/Providers subdirectories. It looks for any file ending with .list.
2. Parse and Convert: For each .list file found, it reads the content line by line.
   • It creates a corresponding output path in the Clash/Providers/ directory with a .yaml extension.
   • It writes the payload: header to the new .yaml file.
   • Each line from the .list file is processed:
     • Empty lines are skipped.
     • Lines starting with # are treated as comments.
     • Lines for USER-AGENT, URL-REGEX, and PROCESS-NAME are commented out in the output YAML.
     • All other lines are prefixed with - to create a YAML list item.
3. File Creation: The resulting content is written to the target .yaml file. If the destination directory doesn't exist, it is created.

The following diagram shows the process flow for update_providers.py.

Sing-box Rule-Set Generation (update_sing_box.py)

This script generates compiled .srs files for sing-box.

1. Scan for Source Files: Similar to the provider script, it scans the Clash/ directory for .list files, ignoring the same subdirectories.
2. Parse and Structure Data: For each .list file, it instantiates a HeadlessRule object. It then parses each line of the file and populates the HeadlessRule object based on the rule type. For example, a line DOMAIN-SUFFIX,google.com will append "google.com" to the domain_suffix list within the object.
3. Generate JSON: The populated HeadlessRule is wrapped in a Rule object, which is then serialized into a JSON string.
4. Compile Rule-Set:
   • The JSON string is written to a temporary .json file in the sing-box/ directory.
   • The script executes an external command: sing-box rule-set compile <file-name>.json. This command creates a compiled .srs file.
   • The temporary .json file is deleted.

Sources: update_sing_box.py:70-134

Data Structures for Sing-box

The update_sing_box.py script uses dataclasses to model the structure of a sing-box rule-set JSON file.

The table below shows the mapping from the .list file rule types to the HeadlessRule class attributes.

.list Rule Type	HeadlessRule Attribute
DOMAIN	domain
DOMAIN-SUFFIX	domain_suffix
DOMAIN-KEYWORD	domain_keyword
DOMAIN-REGEX	domain_regex
IP-CIDR, IP-CIDR6	ip_cidr
SOURCE-IP-CIDR	source_ip_cidr
SRC-PORT	source_port, source_port_range
DST-PORT	port, port_range
PROCESS-NAME	process_name
PROCESS-PATH	process_path

Sources: update_sing_box.py:96-127

File Cleanup and Synchronization

Both automation scripts include a cleanup mechanism. They iterate through the generated files (.yaml for update_providers.py) and check if a corresponding source .list file still exists. If the source file is missing, the generated file is deleted. This ensures that the generated provider/rule-set directories remain synchronized with the master .list files.

Sources: update_providers.py:45-54, update_sing_box.py:137-146

Clash Configuration (GeneralClashConfig.yml)

The Clash/GeneralClashConfig.yml file serves as a master template for configuring a Clash client. It defines general settings, DNS behavior, and an extensive system proxy bypass list.

Key configuration parameters are summarized below:

Parameter	Value	Description
mixed-port	7890	Sets a single port for both HTTP and SOCKS5 proxy services.
allow-lan	true	Allows connections from other devices on the local network.
bind-address	*	Binds to all IP addresses when allow-lan is true.
log-level	info	Sets the logging level to "info".
external-controller	127.0.0.1:9090	Defines the address for the Clash RESTful API.
cfw-bypass	(list)	A very large list of domains and IP ranges to bypass the system proxy.

The cfw-bypass list is particularly notable for its size and detail, containing hundreds of entries for common Chinese domains, services, and CDNs to ensure they are connected to directly, avoiding the proxy. This includes major providers like Alibaba, Baidu, Tencent, and Bilibili.

Sources: Clash/GeneralClashConfig.yml:5-20, 208-766

Provider Rule Sets

The generated .yaml files in Clash/Providers/ and Clash/Providers/Ruleset/ are designed to be used as rule-providers in a Clash configuration. They all share a simple structure: a top-level payload: key followed by a list of rule strings.

For example, Clash/Providers/Ruleset/AI.yaml contains rules for AI-related services:

payload:
  # 内容：内容：AI平台-国外
  # 数量：39条
  - DOMAIN-KEYWORD,anthropic
  - DOMAIN-KEYWORD,claude
  - DOMAIN-KEYWORD,openai
  - DOMAIN,ai.google.dev
  - DOMAIN,api.githubcopilot.com
  - DOMAIN-SUFFIX,chatgpt.com
  ...

Sources: Clash/Providers/Ruleset/AI.yaml:1-12

Similarly, files like ProxyGFWlist.yaml and ProxyLite.yaml aggregate numerous rules from the GFW list and other sources, categorized by service (e.g., Google, Facebook, Telegram) or type. These files use rule types like DOMAIN-SUFFIX, DOMAIN-KEYWORD, and IP-CIDR.

Sources: Clash/Providers/ProxyGFWlist.yaml, Clash/Providers/ProxyLite.yaml

Conclusion

The architecture of the Self-Rule repository is a well-defined, automation-centric system for managing proxy rules. By using simple .list files as a single source of truth and employing Python scripts for conversion, it efficiently generates and synchronizes configurations for both Clash and sing-box clients. This approach simplifies rule maintenance, ensures consistency, and provides a robust foundation for personal proxy management. The inclusion of a detailed general Clash configuration and categorized rule providers makes the repository a comprehensive solution for users of these tools.