Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 0 additions & 18 deletions .github/dependabot.yml

This file was deleted.

48 changes: 0 additions & 48 deletions .github/pull_request_template.md

This file was deleted.

75 changes: 2 additions & 73 deletions .github/workflows/pull-request.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,76 +28,5 @@ jobs:
- name: Prepare scripts
run: find scripts -type f \( -name '*.sh' -o -name '*.py' \) -exec chmod +x {} +

- name: Run preflight validation and text build
run: REQUIRE_SHELLCHECK=1 make preflight

release-candidate:
if: github.base_ref == 'main'
runs-on: ubuntu-latest
timeout-minutes: 45
steps:
- name: Checkout
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
with:
fetch-depth: 0
persist-credentials: false

- name: Set up Python
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
with:
python-version: '3.11'

- name: Select release candidate scope
id: scope
env:
EVENT_NAME: pull_request
BEFORE_SHA: ${{ github.event.pull_request.base.sha }}
CURRENT_SHA: ${{ github.sha }}
run: ./scripts/commands/select-build-scope.sh

- name: Show selected release candidate scope
run: echo "${{ steps.scope.outputs.scope }} - ${{ steps.scope.outputs.reason }}"

- name: Prepare scripts
if: steps.scope.outputs.scope != 'none'
run: find scripts -type f \( -name '*.sh' -o -name '*.py' \) -exec chmod +x {} +

- name: Resolve tool versions
if: steps.scope.outputs.scope != 'none'
id: core_versions
run: bash ./scripts/commands/resolve-tool-versions.sh

- name: Restore verified tool cache
if: steps.scope.outputs.scope != 'none'
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: .bin
key: rules-tools-v3-${{ steps.core_versions.outputs.sing_box_version }}-${{ steps.core_versions.outputs.mihomo_version }}-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('config/tools-lock.json') }}

- name: Build and verify release candidate
if: steps.scope.outputs.scope != 'none'
env:
RULES_BUILD_SCOPE: ${{ steps.scope.outputs.scope }}
RULES_CONFLICT_BASE_SHA: ${{ steps.scope.outputs.base_sha }}
ARTIFACT_GENERATION_ID: pr-${{ github.event.pull_request.number }}-${{ github.run_attempt }}
ARTIFACT_BUILD_ID: ${{ github.run_id }}
ARTIFACT_SOURCE_SHA: ${{ github.sha }}
run: ./scripts/commands/build-artifacts-transaction.sh

- name: Show release candidate summary
if: steps.scope.outputs.scope != 'none'
run: |
cat .output/build-summary.json
if [ -f .output/upstream-summary.json ]; then
cat .output/upstream-summary.json
fi

- name: Upload failure diagnostics
if: failure() && steps.scope.outputs.scope != 'none'
uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
with:
name: release-candidate-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}
path: .artifacts/diagnostics/
include-hidden-files: true
if-no-files-found: warn
retention-days: 7
- name: Quick check
run: REQUIRE_SHELLCHECK=1 make lint
87 changes: 14 additions & 73 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,96 +1,37 @@
# 贡献指南
# 贡献说明

本文件规定提交与评审要求。开发命令见 [开发指南](docs/DEVELOPMENT.md),实现边界见 [仓库结构](docs/STRUCTURE.md)。

## 开始之前

日常变更从临时分支向 `main` 提交 Pull Request,验证通过并合并后发布。提交第三方规则、数据或派生内容时,提供原始来源及可核验的许可、条款或授权;无法确认时明确写“未知”,并由维护者在合并和发布前人工决定处置。

许可审查不是自动检查。CI 不解析 `NOTICE` 或 `THIRD_PARTY_NOTICES.md`,也不会因“未知”状态自动失败。公开 URL、官方来源、`trust` 分类和 CI 通过都不能替代人工许可评审。
本仓库以个人使用为主,主要维护自定义规则并整合上游数据。提交规则时保持内容清晰、可生成即可,不设置复杂审批流程。

## 自定义规则

域名规则位于 `sources/custom/domain/*.list`:
- 域名规则:`sources/custom/domain/*.list`
- IP 规则:`sources/custom/ip/*.list`
- 文件名使用小写字母、数字和连字符。
- 规则类型和值保持规范格式,例如:

```text
DOMAIN,api.example.com
DOMAIN-SUFFIX,example.com
DOMAIN-KEYWORD,example
DOMAIN-REGEX,^(.+\.)?example\.com$
```

IP 规则约定放在 `sources/custom/ip/*.list`:

```text
IP-CIDR,1.2.3.0/24
IP-CIDR,192.0.2.0/24
IP-CIDR6,2001:db8::/32
```

IP 目录可不存在或为空。文件名只使用小写字母、数字和连字符。

新增名称检查有明确边界:`build-custom.sh` 只对相对构建基准新加入的自定义源执行冲突判断,并只检查同一 `domain` 或 `ip` 类型在五个平台 `.output/` 中的目标路径。既有自定义源修改不经过同一新增名称判断,domain 与 ip 可同名。提交者仍应人工检查目标发布分支,避免语义混淆。

### `emby-cn` 与 `emby`

两份规则存在三条经审核的精确覆盖关系,逐条记录在 `config/custom-rule-conflicts.json`。采用首条命中的客户端必须先加载 `emby-cn`,再加载 `emby`。修改时说明重叠变化;失效、重复或只指定文件对而不指定双方规则的宽泛豁免会被拒绝。

## 质量要求

`make lint` 使用与构建相同的严格域名解析器及严格 IP 解析器,要求规则类型和值已经是规范形式,并在所有自定义文件合并后检查 domain 精确项/后缀覆盖和 IP 重复/包含。除精确审核的关系外,跨文件冲突与同文件冲突都会失败。`build-custom.sh` 会在创建构建目录、检查已有产物或准备工具前先执行该校验。不要通过删除测试、扩大豁免、降低阈值或跳过守卫掩盖原因。
不同文件可以有意重叠,以便分别绑定不同策略;同一文件内不应保留重复或被更宽规则覆盖的条目。使用首条命中的客户端时,细分规则应放在宽泛规则之前,例如先加载 `emby-cn`,再加载 `emby`。

配置校验只验证结构和实现约束,例如支持的枚举、HTTPS URL、阈值及必需项目;配置通过不代表许可确认。修改 `config/upstreams.json` 时必须同步更新 `THIRD_PARTY_NOTICES.md`。
## 修改与验证

## 审计信息的使用

完整主上游同步生成 `.output/upstream-summary.json` 和域名 `rule-manifest.json`。前者记录健康结果与输入摘要,但不覆盖本仓库维护的自定义源(包括 `sources/custom/domain/fakeip-filter.list`)、完整转换链或 HTTP 响应身份,不能称为完整来源追溯记录。`fakeip-filter` 与其他自定义规则一起生成各平台产物,不得引入独立预编译文件或下载步骤。

成功的 `build-artifacts-transaction.sh` 在产物守卫之后、manifest 之前生成 `.output/build-summary.json`;manifest 绑定其文件摘要与嵌入内容。独立运行 `make build-custom*` 不生成该文件。所有摘要都不是许可证明。

## 本地验证
日常修改可直接提交,也可通过 Pull Request 合并。建议至少运行:

```bash
make validate
make preflight
```

涉及二进制格式或编译器时再运行
需要预览自定义文本产物时运行

```bash
make build-custom
make build-custom-text
```

`make preflight` 只组合 `make validate` 与文本自定义构建,不执行完整同步、产物守卫(artifact guard)或发布。本地缺少 ShellCheck 时可能跳过,CI 则设置 `REQUIRE_SHELLCHECK=1`。

完整支持环境与工具下载边界见 [开发指南](docs/DEVELOPMENT.md)。不要提交 `.output/`、`.tmp/`、`.artifacts/`、`.bin/`、凭据或本机缓存。

## 修改实现

修改生成逻辑时:

- 为有意输出变化更新 `tests/fixtures/`;
- 新增或调整 `scripts/tests/test-*.sh`;
- 运行适用的验证和构建命令;
- 说明五平台产物及降级行为变化。

测试运行器会自动发现 `test-*.sh`,无需为此修改 Makefile。

## Pull Request 评审清单

- 说明目的、范围和用户可见影响;
- 提供来源及许可、条款、授权或“未知”状态;
- 由维护者人工确认第三方内容是否可合并与发布;
- 说明预期的平台产物和审计摘要变化;
- 记录已运行命令与结果;
- 涉及 `emby-cn` / `emby` 时确认细分规则优先;
- 不绕过严格校验、产物守卫(artifact guard)或发布树检查。

## 文档导航
涉及完整上游同步或二进制格式时,由 `main` 分支的发布工作流统一构建。不要提交 `.output/`、`.tmp/`、`.artifacts/`、`.bin/`、凭据或本机缓存。

- [`README.md`](README.md):用户入口、平台示例和关键边界
- [`CONTRIBUTING.md`](CONTRIBUTING.md):贡献规则与人工评审清单
- [`docs/README.md`](docs/README.md):文档职责与阅读路径
- [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md):环境、命令和开发流程
- [`docs/STRUCTURE.md`](docs/STRUCTURE.md):构建、产物、守卫和发布结构
- [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md):常见失败与定位步骤
- [`SECURITY.md`](SECURITY.md):安全支持范围和私密报告
- [`NOTICE`](NOTICE) / [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md):许可范围与第三方状态
新增上游时,在 `config/upstreams.json` 中填写来源和健康阈值,并按实际情况更新第三方来源说明。仓库代码使用 MIT 许可证;上游数据仍遵循各自条款。
5 changes: 4 additions & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,11 @@ REQUIRE_SHELLCHECK ?= 0
SHELL_SCRIPTS := $(shell find scripts -type f -name '*.sh' | sort)
PYTHON_TOOLS := $(shell find scripts/tools -type f -name '*.py' | sort)

.PHONY: help check-runtime lint lint-shell lint-python lint-config lint-rules test validate preflight build-custom build-custom-text clean
.PHONY: help check check-runtime lint lint-shell lint-python lint-config lint-rules test validate preflight build-custom build-custom-text clean

help:
@echo "Available targets:"
@echo " make check Quick syntax, config, and rule checks"
@echo " make check-runtime Verify the supported Bash and Python runtimes"
@echo " make lint Run shell, Python, and custom rule lint checks"
@echo " make test Run all repository test scripts"
Expand All @@ -17,6 +18,8 @@ help:
@echo " make build-custom-text Build custom text artifacts without downloading binary compilers"
@echo " make clean Remove generated artifacts and temporary files"

check: lint

check-runtime:
@./scripts/commands/check-runtime.sh

Expand Down
11 changes: 6 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
<img alt="Repository code license" src="https://img.shields.io/badge/repository%20code-MIT-4b5563">
</p>

本仓库从配置的上游和本地维护源生成 Surge、Quantumult X、Egern、sing-box 与 mihomo 规则。`main` 保存构建源码、配置和工作流;可直接使用的文件位于对应平台分支。
本仓库用于个人维护自定义规则并整合上游数据,生成 Surge、Quantumult X、Egern、sing-box 与 mihomo 规则。`main` 保存源码、配置和工作流;可直接使用的文件位于对应平台分支。

> [!IMPORTANT]
> 客户端不要引用 `main`。规则名称和区域分类沿用上游定义,不构成准确性、完整性或适用性保证。第三方内容不因格式转换而自动适用本仓库的 MIT 许可,详见 [`NOTICE`](NOTICE) 与 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。
Expand Down Expand Up @@ -76,14 +76,15 @@ https://raw.githubusercontent.com/KuGouGo/Rules/mihomo/ip/google.mrs
本地命令要求 Bash 5+、Python 3.11+、GNU Make 和 Git。macOS 可使用 Homebrew Bash 与 Python 运行检查和文本构建;需要下载 sing-box 或 mihomo 的二进制构建只支持 lock 文件声明的 Linux 平台。

```bash
make check-runtime
make check
make validate
make build-custom-text
make preflight
make clean
```

- `make validate`:运行 Shell、Python、配置、自定义规则和测试检查。
- `make check`:快速检查脚本语法、配置和自定义规则,适合日常改规则。
- `make validate`:在快速检查基础上运行完整测试。
- `make build-custom-text`:生成自定义文本产物,不下载二进制工具。
- `make preflight`:执行 `make validate` 和自定义文本构建;不执行上游完整同步、二进制构建或发布。
- `make clean`:删除生成产物和临时文件,保留已校验的工具缓存。
Expand All @@ -93,9 +94,9 @@ make clean
## 仓库边界

- 长期分支只保留 `main` 与 `surge`、`quanx`、`egern`、`sing-box`、`mihomo` 五个产物分支。
- 变更通过临时分支向 `main` 提交 Pull Request;PR 始终运行静态检查,并按改动路径选择跳过、custom 或 full 候选构建,临时分支在合并后删除
- 日常变更可直接提交,也可通过 Pull Request;PR 只运行基础校验,完整生成和发布由 `main` 工作流负责
- `main` 在构建相关路径变化、定时任务运行或人工触发时执行发布工作流;产物内容没有变化时不会创建新的产物分支提交。
- Dependabot 每周向 `main` 集中提交一个 GitHub Actions minor/patch 更新 PR;major 与安全更新保持独立,逐项评估
- 不启用自动依赖 PR;GitHub Actions 版本按需手工更新
- `fakeip-filter` 是本仓库维护的文本源,不下载第三方预编译文件。
- 构建摘要、manifest 和 CI 通过都不是第三方许可证明。
- 规则按现状提供。使用者需自行判断策略、顺序和更新带来的影响,并保留可回退版本。
Expand Down
38 changes: 0 additions & 38 deletions config/custom-rule-conflicts.json

This file was deleted.

Loading