QuixoticHeart rule-set: one daily-built rule collection for eight proxy clients

A rule collection aimed at router operators, not app developers

QuixoticHeart/rule-set is not a library and not a proxy core. It is a repository of rule files, gathered from the internet and republished in the formats that specific proxy clients expect to load. The description names the target clients directly: mihomo/clash.meta, surge, loon, stash, shadowrocket, quantumultx, egern and sing-box. The topic list adds nikki, openclash and shellcrash, which are deployment shells around the same cores.

The problem it solves is format fragmentation. A user of mihomo wants mrs or list files with rules typed as domain, ipcidr or classical. A user of surge wants a single list file with a different rule syntax. A user of sing-box wants srs binaries plus JSON, and that client splits its rule schema into numbered versions. Maintaining one hand-written rule set per client is the work this project absorbs, so the operator ends up pointing a config file at a URL and updating it on a schedule instead of editing rules by hand.

The intended audience is therefore whoever configures a proxy: a home user running a router, a self-hosting enthusiast, a maintainer of a shared configuration. The rules themselves are grouped by service category, with names such as abema for a streaming platform, adrules for advertising blocking, ai for a set of AI services, apns for Apple push notifications, apple-cn for locally filed Apple domains, cdn for static asset and large download hosts, cn for mainland China domains, cncidr for mainland China IP ranges, and crypto for exchange domains.

Every category in the README also names its upstream rule sources, which is unusual and useful. Subscribers of these files can see that adrules draws on Cats-Team/AdRules, MetaCubeX/meta-rules-dat, uselibrary/PCDN and LOWERTOP/Shadowrocket-First, while the AI category draws on MetaCubeX/meta-rules-dat, SukkaW/Surge, ConnersHua/RuleGo and ACL4SSR/ACL4SSR. The apns entry is marked as manually maintained by the project itself.

A 7:30 build that regenerates rules from upstream sources

The README states that the rules are built automatically every morning at 7:30 Beijing time, UTC+8, and that the point of that schedule is to keep the rules current. The project describes itself as collected from the internet, which points at a pipeline: upstream lists are pulled, the project's own categorization and naming are applied, and the result is converted into each client's format.

Two repository branches matter here. The default branch is master, and the README badges and link targets point at a branch named ruleset, which is where the generated tree lives. The top-level entries are .github/, LICENSE, README.md, custom/ and scripts/. The scripts/ directory is the automation, and custom/ is where rules that are not mechanically derived are kept, which matches the apns category being described as manually maintained.

Because the pipeline runs on a schedule rather than on a release, there is no GitHub releases page for this repository. That is a design choice with a clear consequence: a subscriber is always consuming the current output, and there is no upstream artifact to pin to. If you need a repeatable configuration across a fleet of devices, you have to snapshot the files yourself.

The primary language of the repository is Shell, consistent with a build driven by shell scripts and scheduled by GitHub Actions in the .github/ directory. Nothing in the visible layout suggests a package registry, a library API or a plugin interface. The unit of delivery is a file in a directory.

One directory per client, with rules split by type where it pays off

The generated tree is organised per client, and within a client by rule type. For mihomo and stash there is a root list file plus domain/, ipcidr/ and classical/ subdirectories, each of which can hold both a binary .mrs file and a plain .list file. Clients that only understand a single list format get a single file.

The meta tree looks like this:

meta/
   ├── dmca.list
   ├── domain/
   │      ├──dmca.mrs
   │      └──dmca.list
   ├── ipcidr/
   │      ├──dmca.mrs
   │      └──dmca.list
   └── classical/
          └──dmca.list

The single-file clients are simpler, with one list each for surge, loon, shadowrocket and quantumultx, while egern gets a yaml file. The sing-box tree is the odd one out because that client has versioned rule schemas, so the project keeps a directory per version with both a binary and a JSON file:

singbox/
   ├── version1/
   │      ├──dmca.srs
   │      └──dmca.json
   ├── version2/
   │      ├──dmca.srs
   │      └──dmca.json
   ├── version3/
   │      ├──dmca.srs
   │      └──dmca.json
   ├── version4/
   │      ├──dmca.srs
   │      └──dmca.json
   └── version5/
          ├──dmca.srs
          └──dmca.json

One rule name, dmca, is used as the example throughout the tree. The category names in the rule catalogue follow the same pattern, so a rule called adrules exists as adrules.list and as adrules.mrs in the relevant directories.

Note the caveat the README attaches to the classical directories for mihomo and stash: they hold the remaining rule types after domain and ipcidr are removed, and they are not created when they are not needed. So the presence of a classical directory is not guaranteed, and a config that references a classical file unconditionally may point at something that does not exist.

Why classical rules are treated as a cost on small routers

The project background section makes an explicit performance argument. It states that mihomo/clash.meta and stash optimise the domain and ipcidr rule types better, especially for performance-constrained devices such as hardware routers, and that classical type rule sets should be avoided when using clash-family software on such devices.

The mechanism behind that advice is the split itself. A classical rule set is a mixed list where a domain, an IP range and other criteria live in one file that the core has to evaluate in order. Splitting by type lets the core apply domain matching and CIDR matching through the cheaper path, and it lets the operator point the client at only the files a given policy needs.

Binary formats extend the same idea to startup cost. The README notes that the mrs binary format unique to mihomo/clash.meta and the srs binary format unique to sing-box reduce the hardware resource usage when the core starts, and cut the rule file size by more than half, which the project describes as friendly to devices with limited resources.

There is a deliberate exception for the iOS clients. For surge and loon and the other tools that support DOMAIN-SET, the README argues that performance and memory use no longer differ noticeably between RULE-SET and DOMAIN-SET, so the finer split is no longer necessary and using RULE-SET makes rule set management more convenient. The project does not apply its most granular layout everywhere, and it explains why.

The no-resolve default and the -resolve suffix convention

There is one behavioural convention that changes how a rule behaves at request time rather than at load time. For proxy tools that support the no-resolve parameter, the generated rules carry no-resolve by default. Rules whose file name ends in -resolve have that parameter removed.

The catalogue demonstrates the pattern with a pair. The cncidr rule covers mainland China IP addresses, sourced from NobyDa/geoip, and cncidr-resolve covers the same IP address scope with the no-resolve parameter removed. So the same data set exists in two behavioural variants and the suffix alone tells the client which one to load.

Why it matters: no-resolve tells the client not to perform a DNS lookup to turn the matched address into an IP for further matching. Removing it makes the client resolve the domain itself, which is what you want when a rule needs to match against resolved addresses, and which costs an extra lookup. The naming convention therefore encodes a routing decision, and mixing up the two variants changes matching behaviour rather than merely changing a file name.

One gap worth naming: the README does not document a rollback procedure for a bad build, and there are no releases to fall back to. Since a build runs every morning and the output is overwritten, an accidental bad regeneration leaves you with the current tree until the next run fixes it.

Where this rule collection is the wrong tool

The first limitation is simple: this is a data repository, not a client. Nothing here configures a proxy, manages subscriptions, resolves conflicts between policies or tells you which rule should win. It hands you files in several formats and leaves policy decisions to the tool that consumes them.

The second is that the rule catalogue is a moving target with no version history. Subscriptions that point at the live tree will change content without notice, and there is no release archive to compare against. For a personal device that is a feature, since the rules stay fresh. For a shared configuration in an organisation, an unpinned rule set means a behavioural change can arrive on any morning without a changelog entry.

The third is the licensing and distribution question. The repository is licensed GPL-3.0, and the README carries a caution notice that explicitly forbids any form of reprinting or publication within mainland China. A GPL-3.0 licence also carries copyleft obligations, and the repository includes a separate LICENSE file at the top level. Anyone redistributing the generated rules inside a product or a bundled configuration needs to read that licence carefully. This article does not interpret it, but it is a factor in the adoption decision rather than a footnote.

A fourth point: the source attribution in the catalogue is per rule category, not per entry. Upstream projects change their own lists and their own licences, and this repository rebuilds daily from them. Nothing in the visible layout pins an upstream commit, so traceability of a specific line back to a specific upstream revision is not provided.

Editorial conclusion

Adopt QuixoticHeart rule-set if you run a hardware router or an iOS proxy client and want daily-updated rules in the format your client actually reads, especially if your device chokes on classical rule sets. Do not adopt it if you need versioned releases, a documented install path, or a licence that suits a commercial redistribution. Verify first that the ruleset branch carries the files you expect, that your client can load the mrs or srs binary format, and that the GPL-3.0 terms fit your deployment, since the repository publishes no GitHub releases and the last push was on 2026-10-20.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. QuixoticHeart/rule-set on GitHub
4. README