# CLAUDE.md

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

## 项目简介

pymrf4 是一个 BitTorrent tracker announce 流量修改工具，通过 SOCKS5 代理拦截 BT 客户端（qBittorrent）的 announce 请求，根据策略虚拟上传数据以提升分享比。附带 Flask Web UI 用于监控和文件转移管理。

## 常用命令

```bash
# 安装依赖
pip install -r requirements.txt

# 启动服务（SOCKS5 代理 + Web UI）
python -m pymrf4 --host 0.0.0.0 --port 9050
```

目前没有测试套件、lint 配置或构建系统。

## 架构概览

### 启动流程

`cli.py` → `MRFContext` → 启动两个守护线程（SOCKS5 代理 + Flask Web UI）+ 定时器同步 BT 客户端种子数据。

### 核心模块

- **mrf_context.py** — 主协调器，加载 `config.yml`，初始化 BT 客户端、数据库、代理和 Web 服务
- **mrf_proxy.py** — 核心业务逻辑，`do_modify_3()` 是流量修改的主函数，包含修改策略决策树和速度生成算法
- **socks5_proxy.py** — SOCKS5 协议实现，拦截 HTTP/HTTPS 流量，识别 `/announce` 和 `/scrape` 请求
- **bt_client.py** — qBittorrent WebAPI 客户端封装
- **models.py** — Peewee ORM 模型：`Torrent`（种子元数据+统计）和 `Announce`（单次 announce 记录），一对多关系
- **harvestor.py** — 文件转移线程池（FileCopyQueue + FileCopyWorker），32MB 缓冲区复制
- **web_ui.py** — Flask REST API，端点以 `/api/` 开头
- **web/static/** — 前端 Vue.js 应用（app.js + index.html）

### 修改策略决策树

```
新种子:
  started → zero_upload() | 其他 → original_upload()
既有种子:
  started → start_new_session()
  completed → original_upload()
  progress:
    force_mod = True → mod_upload()
    leechers ≤ 1 → zero_delta_upload()
    1 < leechers < min_leachers_to_mod → min_speed_upload()
    leechers ≥ min_leachers_to_mod → mod_upload()
  stopped → stop_session()
```

### 关键设计

- **配置驱动**：`config.yml` 支持全局默认值 + 站点级覆盖（速度范围、leecher 阈值等）
- **Session 概念**：每次 `started` 事件开始新会话，累计实际上传（reported）与虚拟上传（modified），`stopped` 时合并入总统计
- **速度模拟**：`generate_exponential_speed()` 使用指数分布 + 随机减免系数，使上传速度波动更自然
- **线程模型**：SOCKS5 代理线程 + Web UI 线程 + 文件复制工作线程池 + 定时器线程，`NamespaceLock` 提供按 info_hash 的细粒度锁
- **数据库**：SQLite WAL 模式，Peewee ORM，10 秒超时

### 主要依赖

Flask（Web）、Peewee（ORM）、PyYAML（配置）、requests（HTTP）、bcoding/bencoding（BT 编解码）、smbprotocol（SMB 文件共享）、numpy（速度计算）
