90 lines
3.9 KiB
Markdown
90 lines
3.9 KiB
Markdown
# 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 |