# 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
```bash
# 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
```json
[{
    "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

1. Load subscription configurations from `subscribe.json`
2. Fetch and decode Base64 subscription content for each provider
3. Save individual subscriptions as YAML files in `temp/` directory
4. Process each temp file to extract and filter proxy nodes
5. Extract traffic information from subscription nodes using regex patterns
6. Categorize nodes by region and resolve naming conflicts
7. Merge all data using `temp.yaml` as template
8. 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