Surge Tools and Conversion

Relevant source files

The following files were used as context for generating this wiki page: - [Tool/Surge转acl工具/shortcuts.xml](https://github.com/happy-endless/Self-Rule/blob/HEAD/Tool/Surge%E8%BD%ACacl%E5%B7%A5%E5%85%B7/shortcuts.xml) - [Tool/Surge转acl工具/acl自定义语言格式文件.xml](https://github.com/happy-endless/Self-Rule/blob/HEAD/Tool/Surge%E8%BD%ACacl%E5%B7%A5%E5%85%B7/acl%E8%87%AA%E5%AE%9A%E4%B9%89%E8%AF%AD%E8%A8%80%E6%A0%BC%E5%BC%8F%E6%96%87%E4%BB%B6.xml) - [Tool/New.md](https://github.com/happy-endless/Self-Rule/blob/HEAD/Tool/New.md) - [Clash/Providers/Ruleset/AI.yaml](https://github.com/happy-endless/Self-Rule/blob/HEAD/Clash/Providers/Ruleset/AI.yaml) - [update_sing_box.py](https://github.com/happy-endless/Self-Rule/blob/HEAD/update_sing_box.py) - [Clash/GeneralClashConfig.yml](https://github.com/happy-endless/Self-Rule/blob/HEAD/Clash/GeneralClashConfig.yml) - [README.md](https://github.com/happy-endless/Self-Rule/blob/HEAD/README.md)

The Self-Rule repository provides a collection of tools and configurations for managing and converting proxy rule lists between different formats. The primary focus is on converting rules from formats used by applications like Surge and Clash into a custom ACL (Access Control List) format, which appears to be based on the ACL4SSR project. This conversion is facilitated by a set of Notepad++ macros that perform text transformations using regular expressions.

Beyond the Surge-to-ACL conversion, the repository also includes a Python script (update_sing_box.py) for converting Clash-style rule lists into the JSON format required by the sing-box proxy client. This demonstrates a broader theme of rule format interoperability and maintenance, allowing the user to maintain a central set of rules and adapt them for various proxy applications.

Sources: Tool/Surge转acl工具/shortcuts.xml, update_sing_box.py, README.md

ACL File Format

The target format for conversion is a custom .acl file, for which syntax highlighting is defined in a Notepad++ User Defined Language (UDL) file.

Sources: Tool/Surge转acl工具/acl自定义语言格式文件.xml

Structure

An .acl file is structured into sections, each denoted by a keyword in square brackets. Comments are lines beginning with a # character.

The primary sections defined are:

Section	Description
[proxy_all]	Rules to force all traffic through a proxy.
[bypass_all]	Rules to force all traffic to bypass the proxy.
[outbound_block_list]	A blocklist for outbound connections.
[bypass_list]	A list of rules for traffic that should bypass the proxy (direct connection).
[proxy_list]	A list of rules for traffic that should be routed through the proxy.

Sources: Tool/Surge转acl工具/acl自定义语言格式文件.xml:23

Rule Syntax

The rules within these sections are primarily regular expressions that match domain names or IP addresses. The conversion macros are designed to transform standard proxy rule formats (e.g., DOMAIN-SUFFIX,example.com) into these regular expressions.

Sources: Tool/Surge转acl工具/shortcuts.xml:4-19

Notepad++ Conversion Macros

The core of the conversion tooling is a set of macros for the Notepad++ editor, defined in shortcuts.xml. These macros automate the process of transforming rule formats through a series of find-and-replace operations.

Sources: Tool/Surge转acl工具/shortcuts.xml

网址转acl (URL to ACL) Conversion

This macro converts domain-based rules (like DOMAIN-SUFFIX or DOMAIN) from Surge/Clash format into a regular expression for an ACL file.

The following diagram illustrates the conversion process for a rule like DOMAIN-SUFFIX,example.com,REJECT.

关键词转acl (Keyword to ACL) Conversion

This macro handles DOMAIN-KEYWORD rules, converting them into a regular expression that matches the keyword anywhere within a domain.

The conversion process for a rule like DOMAIN-KEYWORD,google,REJECT is as follows:

1. Comment Conversion: Replaces // with #.
2. Dot Escaping: Replaces literal . with \..
3. Suffix/Policy Replacement: The policy part (e.g., ,REJECT) is replaced with the regex \w*\.\.*$.
4. Prefix Conversion: The DOMAIN-KEYWORD, prefix is replaced with the regex (^|\.)\w*.

The resulting rule is a complex regular expression intended to match the keyword.

*Sources: Tool/Surge转acl工具/shortcuts.xml:20-35_

ip转acl (IP to ACL) Conversion

This macro converts IP-CIDR rules by stripping the prefix and the policy declaration, leaving only the IP address and subnet mask.

The following diagram shows the conversion flow for a rule like IP-CIDR,8.8.8.0/24,REJECT.

acl转surge (ACL to Surge) Conversion

A macro for the reverse conversion is also provided. It transforms a list of domains in ACL format back into Surge's DOMAIN-SUFFIX format by prepending DOMAIN-SUFFIX, and appending ,REJECT.

Sources: Tool/Surge转acl工具/shortcuts.xml:67-79

Broader Conversion Ecosystem

The repository contains other scripts that contribute to the overall goal of rule management and conversion, such as update_sing-box.py.

update_sing_box.py Workflow

This Python script converts Clash-style .list files into sing-box compatible .json rule-sets. It demonstrates a more programmatic approach to rule conversion.

The script's workflow is as follows:

The script defines a HeadlessRule data class to structure the parsed rules before serializing them to JSON. This class accommodates various rule types found in the source files.

# Source: update_sing_box.py:12-32
@dataclass
class HeadlessRule:
    # query_type: list of int or str
    query_type: typing.List[typing.Union[int, str]] = None
    network: list[str] = None
    domain: list[str] = None
    domain_suffix: list[str] = None
    domain_keyword: list[str] = None
    domain_regex: list[str] = None
    source_ip_cidr: list[str] = None
    ip_cidr: list[str] = None
    source_port: list[int] = None
    source_port_range: list[str] = None
    port: list[int] = None
    port_range: list[str] = None
    process_name: list[str] = None
    process_path: list[str] = None
    package_name: list[str] = None
    wifi_ssid: list[str] = None
    wifi_bssid: list[str] = None
    invert: bool = None

This script, along with the various .yaml rule files, shows that the repository is a hub for maintaining rules for multiple proxy clients, not just Surge and ACL.

Sources: update_sing_box.py, Clash/Providers/Ruleset/AI.yaml, Clash/GeneralClashConfig.yml

Conclusion

The "Surge Tools and Conversion" feature within the Self-Rule repository is a practical, developer-focused toolset for managing proxy rules. It relies on a series of text-based transformations, primarily executed via Notepad++ macros, to convert rules between Surge/Clash syntax and a custom ACL regular-expression format. The inclusion of other scripts, like update_sing_box.py, broadens this scope, establishing the repository as a versatile system for maintaining and distributing custom rule sets across multiple proxy platforms.