Contributing to the Project
Relevant source files
The following files were used as context for generating this wiki page:This project maintains a set of custom proxy routing rules for applications like Clash and sing-box. The rules are based on the ACL4SSR project and are organized into various categories to manage network traffic effectively. Contributions primarily involve adding, updating, or refining these routing rules.
The core of the contribution process involves editing source .list files and then running Python scripts to generate the final configuration files for different proxy clients. This ensures consistency and automates the creation of provider and ruleset files.
Sources: README.md
Rule File Structure and Formats
The repository uses two primary file formats for rules: .list files as the source and .yaml files as the generated output for Clash providers.
Sources: update_providers.py, update_sing_box.py, Clash/Providers/Ruleset/AI.yaml
Source .list Files
The source of truth for most rule sets are .list files located throughout the Clash/ directory (but not within Clash/Providers/ or Clash/config/). These are plain text files where each line represents a single rule.
- Format:
RULE-TYPE,VALUE - Comments: Lines starting with
#are treated as comments. - Supported Rule Types: The update scripts parse specific rule types.
The following diagram shows how a .list file is parsed by the update scripts.
Generated .yaml Provider Files
The update_providers.py script generates .yaml files, which are used as rule providers in Clash. These files are placed in the Clash/Providers/ directory, mirroring the structure of the source .list files.
- Structure: Each file contains a top-level
payload:key, followed by a list of rule strings. - Example:
payload: # 内容：内容：AI平台-国外 # 数量：39条 - DOMAIN-KEYWORD,anthropic - DOMAIN-KEYWORD,claude - DOMAIN-KEYWORD,openai - DOMAIN,ai.google.dev
Sources: Clash/Providers/Ruleset/AI.yaml:1-7, update_providers.py:28-30
Contribution Workflow
Contributing new rules or modifying existing ones involves editing the source .list files and running scripts to propagate the changes to the generated .yaml and .srs files.
Automated Generation Process
The repository contains two main scripts to automate the generation of rule files for Clash and sing-box.
The overall workflow is as follows:
Sources: update_providers.py, update_sing_box.py
Clash Provider Generation (update_providers.py)
This script walks the Clash/ directory, finds all .list files, and converts them into .yaml rule-set providers for Clash.
The process is as follows:
- Scan the
Clash/directory for.listfiles, ignoringClash/configandClash/Providers. - For each
.listfile, create a corresponding.yamlfile inClash/Providers/. - Read each line from the
.listfile. - Write the line into the
.yamlfile under thepayload:key. - Lines starting with
USER-AGENT,URL-REGEX, orPROCESS-NAMEare commented out in the final.yamlfile.
Sources: update_providers.py
sing-box Ruleset Generation (update_sing_box.py)
This script converts .list files into compiled .srs rulesets for sing-box.
The process is more complex:
- Scan the
Clash/directory for.listfiles, ignoring the same directories as the other script. - Parse each line and map the ACL rule type to the corresponding sing-box JSON rule type (e.g.,
DOMAIN-SUFFIXtodomain_suffix). - The parsed rules are collected into a
HeadlessRuleobject. - A
Ruleobject is created, which is then serialized into a temporary.jsonfile. - The
sing-box rule-set compilecommand is executed on the.jsonfile to create the final.srsfile. - The temporary
.jsonfile is deleted.
The following data classes are used to structure the JSON file:
# Source: update_sing_box.py:14-41
@dataclass
class HeadlessRule:
query_type: typing.List[typing.Union[int, str]] = None
domain: list[str] = None
domain_suffix: list[str] = None
# ... other rule types
@dataclass
class Rule:
version: int = 2
rules: list[HeadlessRule] = None
This diagram illustrates the conversion and compilation flow:
Sources: update_sing_box.py
Rule Categories
The repository organizes rules into logical categories, primarily found within Clash/Providers/Ruleset/. This allows for modular management of different services and types of traffic.
| Category | File | Description |
|---|---|---|
| AI Tools | AI.yaml | Rules for various AI platforms like OpenAI, Claude, and Google Gemini. |
| Developer | Developer.yaml | Common websites, mirrors, and forums for developers, such as Docker, GitLab, and Stack Overflow. |
| Academic | Scholar.yaml | A comprehensive list of domestic and international academic websites. |
| GitHub | Github.yaml | Specific rules for GitHub domains and services. |
| Cryptocurrency | Crypto.yaml | Domains related to cryptocurrency exchanges, forums, and analysis tools. |
| GFW List | ProxyGFWlist.yaml | An extensive list of domains that are typically blocked, requiring a proxy. |
Sources: Clash/Providers/Ruleset/AI.yaml, Clash/Providers/Ruleset/Developer.yaml, Clash/Providers/Ruleset/Scholar.yaml, Clash/Providers/Ruleset/Github.yaml, Clash/Providers/Ruleset/Crypto.yaml, Clash/Providers/ProxyGFWlist.yaml
Tooling for Rule Conversion
The Tool/ directory contains utilities for converting rules from other formats. The Surge转acl工具 provides Notepad++ macros to convert Surge rules into the ACL format used by this project's .list files.
This suggests that contributors can import rules from other sources, but they must be converted to the standard format before being added to the .list files. The macros automate search-and-replace operations to reformat the rules.
Sources: Tool/Surge转acl工具/shortcuts.xml
Documenting Changes
After making rule modifications and regenerating the provider files, contributors should document their work in the changelog. The file Tool/New.md serves as the project's update history. Entries should include the date and a brief summary of the changes, such as additions, removals, or optimizations.
Example Entry:
# 3.16
# 2017年3月16日00:01:08 81
去重
合并中国IP段
完善百度、letv、金立手机
添加UC浏览器广告过滤
Sources: Tool/New.md:4-10