CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Clash subscription merger script that processes multiple VPN subscription links and merges them into a unified configuration file. The project downloads Base64-encoded Clash configurations from various VPN providers, filters out informational nodes, and organizes proxies by region (Hong Kong, Singapore, USA).

Architecture

merger.py: Main script implementing the ClashSubscriptionMerger class
demo.py: Creates sample data for testing the merger functionality
subscribe.json: Configuration file containing subscription group names and URLs
temp.yaml: Template file with base Clash configuration (DNS, rules, proxy groups)
temp/: Directory storing individual subscription files as YAML
merge.yaml: Final output file with merged proxy configurations

Core Components

ClashSubscriptionMerger: Main class handling subscription fetching, parsing, and merging
Subscription Processing: Downloads and decodes Base64-encoded subscription content
Node Filtering: Removes nodes containing flow/expiry information keywords
Region Classification: Automatically categorizes nodes by geographic regions
Name Conflict Resolution: Handles duplicate proxy names using _Num suffix pattern
Traffic Information Extraction: Extracts traffic data from subscription nodes and adds to proxy group names

Development Commands

Running the Application

# Install dependencies
uv sync

# Run the merger script
python merger.py

# Create demo data for testing
python demo.py

Dependencies Management

Uses uv for Python package management. Dependencies defined in pyproject.toml:

requests>=2.31.0 (HTTP requests)
pyyaml>=6.0.1 (YAML processing)

Key Configuration

subscribe.json Format

[{
    "group_name": "Provider_Name",
    "url": "https://subscription.url"
}]

Regional Node Classification

Hong Kong: HKG, 🇭🇰, HongKong, Hong Kong, HK
Singapore: Singapore, 🇸🇬, SGP, SG
USA: USA, 🇺🇸, United States, US, America

Filtering Rules

Proxy Nodes: Removes nodes with "剩余流量", "套餐到期", "未到期" (保留"距离下次重置剩余"节点)
Proxy Groups: Filters out nodes starting with "Auto", "剩余流量", "套餐到期", "未到期"

Traffic Information Extraction

Pattern Matching: Uses regex patterns to extract traffic data from node names
Supported Formats: 剩余流量: XX.XX GB, 流量: XX.XX GB, 总流量: XX.XX GB
Group Name Enhancement: Automatically appends traffic info to proxy group names (e.g., TrustedAccessPath(183.54 GB))
Days Extraction: Extracts remaining days from patterns like 距离下次重置剩余：XX 天
Daily Average Calculation: Calculates average daily remaining traffic (GB/day) for intelligent sorting
AutoProxy Smart Sorting: New proxy groups are sorted by daily average traffic (highest first) in AutoProxy group

File Processing Workflow

Load subscription configurations from subscribe.json
Fetch and decode Base64 subscription content for each provider
Save individual subscriptions as YAML files in temp/ directory
Process each temp file to extract and filter proxy nodes
Extract traffic information from subscription nodes using regex patterns
Categorize nodes by region and resolve naming conflicts
Merge all data using temp.yaml as template
Generate final merge.yaml with organized proxy groups including traffic info in names

Template Structure

The temp.yaml serves as the base configuration containing:

Network settings (mixed-port: 7890, DNS configuration)
Regional proxy groups (Auto-香港, Auto-新加坡, Auto-USA)
Comprehensive routing rules for Chinese and international domains
Ad-blocking rules and private network handling

3.9 KiB Raw Blame History Unescape Escape