M-Team Seed Recommender

基于 M-Team 官方种子魔力公式和 /torrent/search API，生成 TOP50 感知的保种推荐计划。前端只负责参数和结果展示，M-Team 密钥、Cookie、qB 连接信息都放在后端 .env。

参考：

• 官方时魔公式：https://wiki.m-team.cc/zh-tw/official-torrent-bonus
• Swagger 文档：https://test2.m-team.cc/api/swagger-ui/index.html

后端配置

复制环境模板：

Copy-Item .env.example .env

核心字段：

MTEAM_API_KEY=your_api_key
# MTEAM_COOKIE=optional_cookie
MTEAM_BASE_URL=https://api.m-team.cc/api

QBITTORRENT_URL=http://127.0.0.1:8080
QBITTORRENT_USERNAME=your_qb_user
QBITTORRENT_PASSWORD=your_qb_password
# QBITTORRENT_ADD_PAUSED=true
# QBITTORRENT_CATEGORY=
# QBITTORRENT_TAGS=mteam,recommend
# QBITTORRENT_SAVE_PATH=

CURRENT_HOURLY_BONUS=0
DISK_RESERVE_GB=200
DEFAULT_DISK_LIMIT_GB=5000

说明：

• MTEAM_BASE_URL 默认保持正式 API：https://api.m-team.cc/api。
• Web 前端不会接收或保存 API key。
• qB 可用时，推荐预算优先使用 qB Web API 的 free_space_on_disk。
• qB 不可用时，后端回退到 DISK_FREE_GB 或 DEFAULT_DISK_LIMIT_GB。
• CURRENT_HOURLY_BONUS 用作当前每小时时魔基线，推荐结果会输出预计提升和预期时魔。
• Web 面板可以把勾选的种子推送到 qB；后端会先调用 /torrent/genDlToken 生成临时下载 URL，再通过 qB Web API 添加任务。
• 推送默认暂停添加，除非在面板关闭“暂停添加”，或设置 QBITTORRENT_ADD_PAUSED=false。

qB 推送

生成推荐后，表格会默认勾选 TOP50 推荐。你可以：

TOP50      重新只选择 TOP50 推荐
当前页     选择当前筛选区域可见种子
清空       清空待推送列表
推送至 qB  将勾选种子添加到 qB

推送时可选字段：

分类       对应 qB category，留空则不设置
标签       对应 qB tags，默认 mteam,recommend
暂停添加   默认开启，避免任务推送后立即开始下载

Web 应用

生产模式：

$env:PYTHONUTF8 = '1'
$env:PYTHONIOENCODING = 'utf-8'
cd web
npm install
npm run build
cd ..
uv run mteam-seed-web

打开：

http://127.0.0.1:8765

开发模式需要两个终端。

后端：

$env:PYTHONUTF8 = '1'
$env:PYTHONIOENCODING = 'utf-8'
uv run mteam-seed-web

前端：

cd web
npm install
npm run dev

打开：

http://127.0.0.1:5173

评分逻辑

每个种子先归一化为：

S = 体积 GB
C = 实际新增磁盘占用 GB，默认等于 S
T = 存活时间，单位周
N = 当前做种人数
official = 是否官方种

计算：

time = 1 - 10^(-T / 4)
rare = 1 + sqrt(2) * 10^(-(N - 1) / 6)

base_value = time * rare * S
official_value = time * rare * S^1.5   # 非官方为 0

TOP50 内评分默认权重：

top50_score =
    0.50 * normalize(base_value / C)
  + 0.35 * normalize(official_value / C)
  + 0.05 * rarity_score
  + 0.05 * age_score
  + 0.05 * disk_score

TOP50 外评分：

outside_score = normalize(official_value / C)  # 仅官方种有效

推荐结果会额外计算每个种子的边际时魔：从当前推荐计划中移除该种子后重新估算，差值就是该种子的预计提升。

下载量影响也会参与推荐：

download_cost = size * discount_multiplier
FREE         -> 0
PERCENT_50   -> 0.5
PERCENT_70   -> 0.7
NORMAL       -> 1

Web 面板支持设置 最大下载 GB 和 最低分享率。如果设置了最低分享率，后端会用当前账号的已上传/已下载推导可承受新增下载量，并优先推荐 FREE / 折扣下载量低的种子。

命令行

.env 会被自动读取，也可以用环境变量覆盖：

$env:PYTHONUTF8 = '1'
$env:PYTHONIOENCODING = 'utf-8'
uv run mteam-seed-rank --pages 3 --disk-limit-gb 4000 --output-json recommendations.json

离线评分：

uv run mteam-seed-rank --input-json raw-search-response.json --disk-limit-gb 4000

保存原始响应：

uv run mteam-seed-rank --pages 2 --raw-output-json raw.json --output-csv recommendations.csv

常用参数：

--top-n 50                  基础 A 计入的 TOP 数，默认 50
--outside-limit 100          TOP50 外额外保留的官方种数量
--disk-limit-gb 4000         总磁盘预算
--official-only              只推荐官方种
--min-size-gb 1              过滤小于 1GB 的种子
--max-seeders 20             过滤做种人数超过 20 的种子
--numeric-size-unit bytes    如果 API 数字 size 明确是 bytes

权重可以直接调：

uv run mteam-seed-rank `
  --base-weight 0.45 `
  --official-weight 0.40 `
  --rarity-weight 0.05 `
  --age-weight 0.05 `
  --disk-weight 0.05

默认会用三组排序拉候选池并去重：

SEEDERS:ASC
SIZE:DESC
CREATED_DATE:ASC

你可以覆盖或增加：

uv run mteam-seed-rank --strategy SEEDERS:ASC --strategy SIZE:DESC --pages 5

输出解释

zone = TOP50    进入基础 A + 官方 P 核心区
zone = OUTSIDE  TOP50 外，只靠官方 P 继续产生价值
estimated_hourly_gain   当前推荐计划中的边际每小时时魔
resource_impact         预计磁盘占用和预算占比
download_cost_gb        按促销折扣估算的计入下载量
projectedShareRate      当前下载量叠加推荐计划后的预计分享率
currentHourlyBonus      .env 中的当前每小时时魔基线
estimatedHourlyGain     推荐计划预计新增每小时时魔
projectedHourlyBonus    当前基线 + 预计提升

如果 API 返回字段名和当前归一化规则不匹配，先用：

uv run mteam-seed-rank --raw-output-json raw.json --pages 1

再检查 raw.json 里体积、做种人数、发布时间、官方标签字段名。