30 KiB
30 KiB
Emby刷新演员头像脚本
1. 脚本总结
- 用 PersonId 直接请求图片 → 触发Emby下载，不用模拟点击
- 智能生成搜索关键词 → 中文取前1-2个字，英文取前2个字母
- 进度持久化 → 中断后可以继续，不会重复处理
- 限流保护 → 429/403/网络500自动停止
- 只处理有 Primary 标记的 → 避免无效请求
- 适用范围: Emby 4.8.x / 4.9.x 通用
- 需要科学上网的环境（脚本走系统代理）
- 大批量补全演员头像
说明: 整个补齐脚本分为两个阶段:
第一阶段: 补齐打开影片页就可以自动刷新的演员头像;
第二阶段: 补齐需要打开演员详情页才能刷新的演员头像.
脚本需要使用python，请自行安装。
2. 第一阶段脚本
import requests
import time
import json
import os
import sys
import re
# =========================
# 你需要修改的配置
# =========================
EMBY_URL = ""
API_KEY = ""
USER_ID = ""
# 每个搜索词之间等待多少秒
SEARCH_TERM_DELAY_SECONDS = 5
# 同一个搜索词下，每个演员头像之间等待多少秒
IMAGE_DELAY_SECONDS = 4
# 每个搜索词最多请求多少个带头像标记的演员
# 先保守一点，避免一个关键词返回太多人
MAX_IMAGES_PER_TERM = 50
# 每次搜索最多返回多少个演员
SEARCH_LIMIT = 200
# 读取媒体库分页间隔
PAGE_DELAY_SECONDS = 1
# 进度文件：记录已经搜索过的关键词、已经处理过的人物头像
PROGRESS_FILE = r"D:\emby_person_image_warmer_progress.json"
# 只从媒体库中收集演员
TARGET_PERSON_TYPES = {"Actor"}
# =========================
# 以下一般不用修改
# =========================
session = requests.Session()
session.headers.update({
"X-Emby-Token": API_KEY,
"User-Agent": "Mozilla/5.0 Emby-Web-Person-Image-Warmer/1.0"
})
def load_progress():
if not os.path.exists(PROGRESS_FILE):
return {
"terms": {},
"persons": {}
}
try:
with open(PROGRESS_FILE, "r", encoding="utf-8") as f:
data = json.load(f)
if "terms" not in data:
data["terms"] = {}
if "persons" not in data:
data["persons"] = {}
return data
except Exception:
return {
"terms": {},
"persons": {}
}
def save_progress(progress):
with open(PROGRESS_FILE, "w", encoding="utf-8") as f:
json.dump(progress, f, ensure_ascii=False, indent=2)
def wait_seconds(seconds, reason):
print(f"{reason}，等待 {seconds} 秒...")
time.sleep(seconds)
def get_all_media_items():
"""
获取所有电影和电视剧，用来收集演员名字。
这里只读取 People，不刷新元数据，不替换图片。
"""
items = []
start = 0
limit = 100
while True:
r = session.get(
f"{EMBY_URL}/emby/Users/{USER_ID}/Items",
params={
"UserId": USER_ID,
"Recursive": "true",
"IncludeItemTypes": "Movie,Series",
"Fields": "People",
"StartIndex": start,
"Limit": limit
},
timeout=60
)
r.raise_for_status()
data = r.json()
batch = data.get("Items", [])
items.extend(batch)
print(f"已读取媒体条目：{len(items)} / {data.get('TotalRecordCount', '?')}")
if len(batch) < limit:
break
start += limit
wait_seconds(PAGE_DELAY_SECONDS, "读取下一批媒体前")
return items
def collect_actor_names(items):
"""
从媒体条目中收集演员名字。
"""
names = set()
for item in items:
for p in item.get("People", []) or []:
if p.get("Type") not in TARGET_PERSON_TYPES:
continue
name = p.get("Name")
if not name:
continue
name = name.strip()
if name:
names.add(name)
return sorted(names)
def is_cjk_char(ch):
"""
判断是否中日韩字符。
"""
return (
"\u4e00" <= ch <= "\u9fff" or
"\u3040" <= ch <= "\u30ff" or
"\uac00" <= ch <= "\ud7af"
)
def make_search_terms_from_name(name):
"""
从演员名字生成搜索关键词。
例：
刘若英 -> 刘, 刘若
刘诗诗 -> 刘, 刘诗
Li Ying -> li, yi
Liu Shishi -> li, sh
Aoi Tsukasa -> ao, ts
葵司 -> 葵, 葵司
"""
terms = set()
clean = name.strip()
if not clean:
return terms
# 中日韩名字：取第一个字、前两个字
cjk_chars = [ch for ch in clean if is_cjk_char(ch)]
if cjk_chars:
terms.add(cjk_chars[0])
if len(cjk_chars) >= 2:
terms.add("".join(cjk_chars[:2]))
# 拉丁字母名字：每个单词取前两个字母
words = re.findall(r"[A-Za-zÀ-ÖØ-öø-ÿ]+", clean)
for w in words:
w = w.lower()
if len(w) >= 2:
terms.add(w[:2])
elif len(w) == 1:
terms.add(w)
return terms
def build_search_terms(actor_names):
"""
根据所有演员名字生成搜索词列表。
"""
terms = set()
for name in actor_names:
terms.update(make_search_terms_from_name(name))
# 去掉太短且可能结果太杂的英文单字母
cleaned = set()
for t in terms:
t = t.strip()
if not t:
continue
# 英文单字母容易返回太多，跳过
if re.fullmatch(r"[a-zA-Z]", t):
continue
cleaned.add(t)
return sorted(cleaned)
def search_persons(term):
"""
模拟 Emby 搜索演员。
"""
try:
r = session.get(
f"{EMBY_URL}/emby/Users/{USER_ID}/Items",
params={
"UserId": USER_ID,
"Recursive": "true",
"IncludeItemTypes": "Person",
"SearchTerm": term,
"Fields": "ImageTags,PrimaryImageAspectRatio,ProviderIds",
"Limit": SEARCH_LIMIT
},
timeout=90
)
if r.status_code == 200:
data = r.json()
items = data.get("Items", [])
total = data.get("TotalRecordCount", len(items))
print(f"[搜索OK] 关键词={term} | 返回={len(items)} / 总数={total}")
return "ok", items, total
if r.status_code == 429:
retry_after = r.headers.get("Retry-After")
print(f"[429 限流] 关键词={term}")
if retry_after:
print(f"服务端要求等待 {retry_after} 秒。现在停止脚本。")
else:
print("检测到限流。现在停止脚本，建议稍后再跑。")
return "rate_limited", [], 0
if r.status_code == 403:
print(f"[403 禁止访问] 关键词={term}")
print("检测到可能的封锁/权限问题。现在停止脚本。")
return "blocked", [], 0
if r.status_code == 500:
print(f"[搜索500] 关键词={term} | {r.text[:200]}")
return "server_error_500", [], 0
print(f"[搜索{r.status_code}] 关键词={term} | {r.text[:200]}")
return "fail", [], 0
except requests.exceptions.Timeout:
print(f"[搜索超时] 关键词={term}")
return "timeout", [], 0
except Exception as e:
print(f"[搜索错误] 关键词={term}: {e}")
return "fail", [], 0
def request_person_image(person):
"""
请求搜索结果里带 ImageTags.Primary 的演员头像。
这是关键：
/emby/Items/{PersonId}/Images/Primary?tag=xxx
不刷新元数据。
不替换图片。
不删除图片。
"""
name = person.get("Name")
person_id = str(person.get("Id"))
image_tags = person.get("ImageTags") or {}
primary_tag = image_tags.get("Primary")
if not primary_tag:
print(f" [跳过无头像标记] {name} | PersonId={person_id}")
return "skip_no_tag"
url = f"{EMBY_URL}/emby/Items/{person_id}/Images/Primary"
params = {
"maxWidth": 400,
"quality": 90,
"tag": primary_tag
}
try:
r = session.get(url, params=params, timeout=90)
content_type = r.headers.get("Content-Type", "")
if r.status_code == 200:
print(f" [图片OK] {name} | PersonId={person_id} | {len(r.content)} bytes | {content_type}")
return "ok"
if r.status_code == 404:
print(f" [图片404] {name} | PersonId={person_id}")
return "not_found"
if r.status_code == 429:
print(f" [429 限流] {name} | PersonId={person_id}")
return "rate_limited"
if r.status_code == 403:
print(f" [403 禁止访问] {name} | PersonId={person_id}")
return "blocked"
if r.status_code == 500:
text = r.text[:300]
print(f" [图片500] {name} | PersonId={person_id} | {text}")
# 网络/代理/上游超时类 500，不记为成功，后面可以重试
lower_text = text.lower()
if (
"ssl connection" in lower_text or
"previous timeout" in lower_text or
"timeout" in lower_text or
"connection" in lower_text
):
return "network_500"
# Emby内部空引用一类，记录但不终止
if "object reference" in lower_text:
return "server_error_500"
return "server_error_500"
print(f" [图片{r.status_code}] {name} | PersonId={person_id} | {r.text[:200]}")
return "fail"
except requests.exceptions.Timeout:
print(f" [图片超时] {name} | PersonId={person_id}")
return "timeout"
except Exception as e:
print(f" [图片请求错误] {name} | PersonId={person_id} | {e}")
return "fail"
if __name__ == "__main__":
progress = load_progress()
print("开始读取媒体库，用来收集演员名字...")
items = get_all_media_items()
print("\n开始收集演员名字...")
actor_names = collect_actor_names(items)
print(f"共收集到演员数量：{len(actor_names)}")
search_terms = build_search_terms(actor_names)
print(f"生成搜索关键词数量：{len(search_terms)}")
print("前 50 个搜索关键词预览：")
for t in search_terms[:50]:
print("-", t)
print("\n开始正式处理演员头像...\n")
for term_index, term in enumerate(search_terms, 1):
if term in progress["terms"]:
old_status = progress["terms"][term].get("status")
print(f"{term_index}/{len(search_terms)} 跳过关键词：{term} | 已处理状态={old_status}")
continue
print("=" * 70)
print(f"{term_index}/{len(search_terms)} 搜索关键词：{term}")
search_status, people, total = search_persons(term)
if search_status in {"rate_limited", "blocked"}:
save_progress(progress)
print("\n检测到限流/封锁风险，脚本停止。")
sys.exit(1)
if search_status != "ok":
print("本关键词搜索失败，不写入关键词进度，下次会重试。")
wait_seconds(SEARCH_TERM_DELAY_SECONDS, "搜索词之间间隔")
continue
# 只处理带 Primary 图片标记的人
people_with_primary = []
skipped_no_tag = 0
skipped_done = 0
for p in people:
person_id = str(p.get("Id"))
image_tags = p.get("ImageTags") or {}
primary_tag = image_tags.get("Primary")
if not primary_tag:
skipped_no_tag += 1
continue
# 已经处理过这个人物头像，跳过
if person_id in progress["persons"]:
skipped_done += 1
continue
people_with_primary.append(p)
print(f"本关键词返回人物：{len(people)}")
print(f"无头像标记跳过：{skipped_no_tag}")
print(f"已处理人物跳过：{skipped_done}")
print(f"本次需要请求头像：{len(people_with_primary)}")
processed_count = 0
ok_count = 0
fail_count = 0
network_500_count = 0
server_500_count = 0
for idx, person in enumerate(people_with_primary[:MAX_IMAGES_PER_TERM], 1):
person_id = str(person.get("Id"))
name = person.get("Name")
print(f" {idx}/{min(len(people_with_primary), MAX_IMAGES_PER_TERM)} 请求头像：{name} | PersonId={person_id}")
result = request_person_image(person)
processed_count += 1
if result == "ok":
ok_count += 1
progress["persons"][person_id] = {
"name": name,
"status": "ok",
"term": term,
"time": time.strftime("%Y-%m-%d %H:%M:%S")
}
save_progress(progress)
elif result in {"not_found", "skip_no_tag", "server_error_500"}:
if result == "server_error_500":
server_500_count += 1
else:
fail_count += 1
# 这类不是网络临时问题，可以记录，避免反复请求
progress["persons"][person_id] = {
"name": name,
"status": result,
"term": term,
"time": time.strftime("%Y-%m-%d %H:%M:%S")
}
save_progress(progress)
elif result == "network_500":
network_500_count += 1
print(" 检测到网络/SSL/timeout 类 500，本人物不写入进度，下次可重试。")
# 连续/多次网络失败时，建议停止，不要继续刺激上游
if network_500_count >= 3:
save_progress(progress)
print("\n本关键词内出现 3 次网络类 500，脚本停止。请确认代理/Emby网络后再运行。")
sys.exit(1)
elif result in {"rate_limited", "blocked"}:
save_progress(progress)
print("\n检测到限流/封锁风险，脚本停止。")
sys.exit(1)
else:
fail_count += 1
print(" 本次失败，不写入人物进度，下次会重试。")
if idx < min(len(people_with_primary), MAX_IMAGES_PER_TERM):
wait_seconds(IMAGE_DELAY_SECONDS, "同一关键词下演员头像之间间隔")
# 这个关键词已经搜索并处理过一轮，记录关键词进度
progress["terms"][term] = {
"status": "done",
"returned": len(people),
"total": total,
"processed_images": processed_count,
"ok": ok_count,
"network_500": network_500_count,
"server_500": server_500_count,
"time": time.strftime("%Y-%m-%d %H:%M:%S")
}
save_progress(progress)
print(f"关键词 {term} 完成：图片OK={ok_count}，网络500={network_500_count}，服务端500={server_500_count}")
if term_index < len(search_terms):
wait_seconds(SEARCH_TERM_DELAY_SECONDS, "搜索词之间间隔")
print("\n全部处理完成。")
print(f"进度文件已保存：{PROGRESS_FILE}")
3. 第二阶段脚本
import requests
import time
import json
import os
import sys
# =========================
# 你需要修改的配置
# =========================
EMBY_URL = ""
API_KEY = ""
USER_ID = ""
# 第一阶段脚本的进度文件（如果存在，就会跳过已经成功的人）
PHASE1_PROGRESS_FILE = r"D:\emby_person_image_warmer_progress.json"
# 第二阶段自己的进度文件
PHASE2_PROGRESS_FILE = r"D:\emby_person_detail_warmer_phase2_progress.json"
# 每次拉取多少个人物
PAGE_LIMIT = 200
# 打开人物详情页后，等几秒再重新检查
DETAIL_RECHECK_DELAY_SECONDS = 2
# 每处理一个人物后等待几秒
PERSON_DELAY_SECONDS = 3
# 每处理多少个人物，休息一下
BATCH_SIZE = 100
BATCH_REST_SECONDS = 60
# =========================
# 以下一般不用修改
# =========================
session = requests.Session()
session.headers.update({
"X-Emby-Token": API_KEY,
"User-Agent": "Mozilla/5.0 Emby-Person-Detail-Warmer-Phase2/1.0"
})
def load_json_file(path, default_value):
if not os.path.exists(path):
return default_value
try:
with open(path, "r", encoding="utf-8") as f:
return json.load(f)
except Exception:
return default_value
def save_json_file(path, data):
with open(path, "w", encoding="utf-8") as f:
json.dump(data, f, ensure_ascii=False, indent=2)
def load_phase1_ok_persons():
"""
读取第一阶段已成功的人物，避免重复处理。
"""
data = load_json_file(PHASE1_PROGRESS_FILE, {"terms": {}, "persons": {}})
ok_persons = set()
persons = data.get("persons", {})
for person_id, info in persons.items():
if info.get("status") == "ok":
ok_persons.add(str(person_id))
return ok_persons
def load_phase2_progress():
data = load_json_file(PHASE2_PROGRESS_FILE, {"persons": {}})
if "persons" not in data:
data["persons"] = {}
return data
def save_phase2_progress(progress):
save_json_file(PHASE2_PROGRESS_FILE, progress)
def wait_seconds(seconds, reason):
print(f"{reason}，等待 {seconds} 秒...")
time.sleep(seconds)
def get_all_persons():
"""
直接读取 Emby 全部 Person 条目。
"""
persons = []
start = 0
while True:
r = session.get(
f"{EMBY_URL}/emby/Users/{USER_ID}/Items",
params={
"UserId": USER_ID,
"Recursive": "true",
"IncludeItemTypes": "Person",
"Fields": "ImageTags,PrimaryImageAspectRatio,ProviderIds",
"StartIndex": start,
"Limit": PAGE_LIMIT
},
timeout=90
)
r.raise_for_status()
data = r.json()
batch = data.get("Items", [])
total = data.get("TotalRecordCount", "?")
persons.extend(batch)
print(f"已读取人物：{len(persons)} / {total}")
if len(batch) < PAGE_LIMIT:
break
start += PAGE_LIMIT
time.sleep(0.5)
return persons
def get_person_detail(person_id):
"""
模拟打开人物详情页。
"""
try:
r = session.get(
f"{EMBY_URL}/emby/Users/{USER_ID}/Items/{person_id}",
params={
"Fields": "ProviderIds,ImageTags,PrimaryImageAspectRatio,Overview"
},
timeout=90
)
if r.status_code == 200:
return "ok", r.json()
if r.status_code == 429:
return "rate_limited", None
if r.status_code == 403:
return "blocked", None
if r.status_code == 500:
text = r.text[:300].lower()
if (
"ssl connection" in text or
"previous timeout" in text or
"timeout" in text or
"connection" in text
):
return "network_500", None
return "server_error_500", None
return "fail", None
except requests.exceptions.Timeout:
return "timeout", None
except Exception:
return "fail", None
def request_person_image(person_id, name, primary_tag):
"""
请求人物头像：
/emby/Items/{PersonId}/Images/Primary?tag=xxx
"""
try:
r = session.get(
f"{EMBY_URL}/emby/Items/{person_id}/Images/Primary",
params={
"maxWidth": 400,
"quality": 90,
"tag": primary_tag
},
timeout=90
)
if r.status_code == 200:
print(f" [图片OK] {name} | PersonId={person_id} | {len(r.content)} bytes")
return "ok"
if r.status_code == 404:
print(f" [图片404] {name} | PersonId={person_id}")
return "not_found"
if r.status_code == 429:
print(f" [429 限流] {name} | PersonId={person_id}")
return "rate_limited"
if r.status_code == 403:
print(f" [403 禁止访问] {name} | PersonId={person_id}")
return "blocked"
if r.status_code == 500:
text = r.text[:300]
print(f" [图片500] {name} | PersonId={person_id} | {text}")
lower_text = text.lower()
if (
"ssl connection" in lower_text or
"previous timeout" in lower_text or
"timeout" in lower_text or
"connection" in lower_text
):
return "network_500"
if "object reference" in lower_text:
return "server_error_500"
return "server_error_500"
print(f" [图片{r.status_code}] {name} | PersonId={person_id} | {r.text[:200]}")
return "fail"
except requests.exceptions.Timeout:
print(f" [图片超时] {name} | PersonId={person_id}")
return "timeout"
except Exception as e:
print(f" [图片请求错误] {name} | PersonId={person_id} | {e}")
return "fail"
if __name__ == "__main__":
print("当前运行目录:", os.getcwd())
print("第一阶段进度文件:", PHASE1_PROGRESS_FILE)
print("第二阶段进度文件:", PHASE2_PROGRESS_FILE)
phase1_ok_persons = load_phase1_ok_persons()
phase2_progress = load_phase2_progress()
print(f"\n第一阶段已成功人物数量：{len(phase1_ok_persons)}")
print("\n开始读取 Emby 全部人物...")
persons = get_all_persons()
print(f"\n共读取到人物数量：{len(persons)}")
need_process = []
skipped_phase1_ok = 0
skipped_phase2_done = 0
skipped_already_has_primary = 0
for p in persons:
person_id = str(p.get("Id"))
name = p.get("Name", "")
image_tags = p.get("ImageTags") or {}
primary_tag = image_tags.get("Primary")
# 第一阶段已经成功刷过
if person_id in phase1_ok_persons:
skipped_phase1_ok += 1
continue
# 第二阶段已经处理过
if person_id in phase2_progress["persons"]:
skipped_phase2_done += 1
continue
# 当前列表里已经有头像标记的，也先跳过
# 因为第二阶段目标就是补“没有头像标记但点详情会出来”的人
if primary_tag:
skipped_already_has_primary += 1
continue
need_process.append({
"Id": person_id,
"Name": name
})
print(f"第一阶段已成功，跳过：{skipped_phase1_ok}")
print(f"第二阶段已处理，跳过：{skipped_phase2_done}")
print(f"当前本身已有头像标记，跳过：{skipped_already_has_primary}")
print(f"第二阶段需要处理：{len(need_process)}\n")
processed = 0
detail_success_count = 0
image_ok_count = 0
still_no_primary_count = 0
network_500_count = 0
server_500_count = 0
fail_count = 0
for idx, person in enumerate(need_process, 1):
person_id = person["Id"]
name = person["Name"]
print("=" * 70)
print(f"{idx}/{len(need_process)} 处理人物：{name} | PersonId={person_id}")
# 第一次打开人物详情
status1, detail1 = get_person_detail(person_id)
if status1 in {"rate_limited", "blocked"}:
save_phase2_progress(phase2_progress)
print("\n检测到限流/封锁风险，脚本停止。")
sys.exit(1)
if status1 == "network_500":
network_500_count += 1
print(" 打开人物详情时发生网络类 500，本次不写进度，下次重试。")
if network_500_count >= 3:
save_phase2_progress(phase2_progress)
print("\n连续出现 3 次网络类 500，脚本停止。请确认代理/Emby 后再运行。")
sys.exit(1)
if idx < len(need_process):
wait_seconds(PERSON_DELAY_SECONDS, "人物之间间隔")
continue
if status1 == "server_error_500":
server_500_count += 1
print(" 打开人物详情时发生服务端 500，记录后跳过。")
phase2_progress["persons"][person_id] = {
"name": name,
"status": "server_error_500_on_detail",
"time": time.strftime("%Y-%m-%d %H:%M:%S")
}
save_phase2_progress(phase2_progress)
if idx < len(need_process):
wait_seconds(PERSON_DELAY_SECONDS, "人物之间间隔")
continue
if status1 != "ok":
fail_count += 1
print(" 打开人物详情失败，本次不写进度，下次重试。")
if idx < len(need_process):
wait_seconds(PERSON_DELAY_SECONDS, "人物之间间隔")
continue
detail_success_count += 1
# 打开详情页后，等一会儿再重新读取一次详情
wait_seconds(DETAIL_RECHECK_DELAY_SECONDS, "已打开人物详情，重新检查头像标记前")
status2, detail2 = get_person_detail(person_id)
if status2 in {"rate_limited", "blocked"}:
save_phase2_progress(phase2_progress)
print("\n检测到限流/封锁风险，脚本停止。")
sys.exit(1)
if status2 == "network_500":
network_500_count += 1
print(" 二次读取人物详情时发生网络类 500，本次不写进度，下次重试。")
if network_500_count >= 3:
save_phase2_progress(phase2_progress)
print("\n连续出现 3 次网络类 500，脚本停止。请确认代理/Emby 后再运行。")
sys.exit(1)
if idx < len(need_process):
wait_seconds(PERSON_DELAY_SECONDS, "人物之间间隔")
continue
if status2 == "server_error_500":
server_500_count += 1
print(" 二次读取人物详情时发生服务端 500，记录后跳过。")
phase2_progress["persons"][person_id] = {
"name": name,
"status": "server_error_500_on_recheck",
"time": time.strftime("%Y-%m-%d %H:%M:%S")
}
save_phase2_progress(phase2_progress)
if idx < len(need_process):
wait_seconds(PERSON_DELAY_SECONDS, "人物之间间隔")
continue
if status2 != "ok":
fail_count += 1
print(" 二次读取人物详情失败，本次不写进度，下次重试。")
if idx < len(need_process):
wait_seconds(PERSON_DELAY_SECONDS, "人物之间间隔")
continue
image_tags = detail2.get("ImageTags") or {}
primary_tag = image_tags.get("Primary")
if not primary_tag:
still_no_primary_count += 1
print(" 打开人物详情后仍然没有头像标记，记录为 still_no_primary。")
phase2_progress["persons"][person_id] = {
"name": name,
"status": "still_no_primary",
"time": time.strftime("%Y-%m-%d %H:%M:%S")
}
save_phase2_progress(phase2_progress)
if idx < len(need_process):
wait_seconds(PERSON_DELAY_SECONDS, "人物之间间隔")
continue
# 已经拿到头像标记，正式请求头像
print(f" 详情补全成功，发现头像标记：{primary_tag}")
image_result = request_person_image(person_id, name, primary_tag)
if image_result == "ok":
image_ok_count += 1
phase2_progress["persons"][person_id] = {
"name": name,
"status": "ok",
"primary_tag": primary_tag,
"time": time.strftime("%Y-%m-%d %H:%M:%S")
}
save_phase2_progress(phase2_progress)
elif image_result == "network_500":
network_500_count += 1
print(" 请求头像时发生网络类 500，不写进度，下次重试。")
if network_500_count >= 3:
save_phase2_progress(phase2_progress)
print("\n连续出现 3 次网络类 500，脚本停止。请确认代理/Emby 后再运行。")
sys.exit(1)
elif image_result == "server_error_500":
server_500_count += 1
phase2_progress["persons"][person_id] = {
"name": name,
"status": "server_error_500_on_image",
"primary_tag": primary_tag,
"time": time.strftime("%Y-%m-%d %H:%M:%S")
}
save_phase2_progress(phase2_progress)
elif image_result in {"not_found"}:
phase2_progress["persons"][person_id] = {
"name": name,
"status": image_result,
"primary_tag": primary_tag,
"time": time.strftime("%Y-%m-%d %H:%M:%S")
}
save_phase2_progress(phase2_progress)
elif image_result in {"rate_limited", "blocked"}:
save_phase2_progress(phase2_progress)
print("\n检测到限流/封锁风险，脚本停止。")
sys.exit(1)
else:
fail_count += 1
print(" 请求头像失败，本次不写进度，下次重试。")
processed += 1
if idx < len(need_process):
wait_seconds(PERSON_DELAY_SECONDS, "人物之间间隔")
if processed > 0 and processed % BATCH_SIZE == 0:
save_phase2_progress(phase2_progress)
wait_seconds(BATCH_REST_SECONDS, f"已处理 {processed} 个人物，本批休息")
save_phase2_progress(phase2_progress)
print("\n全部处理完成。")
print(f"成功打开详情：{detail_success_count}")
print(f"成功刷出头像：{image_ok_count}")
print(f"打开详情后仍无头像标记：{still_no_primary_count}")
print(f"网络类500：{network_500_count}")
print(f"服务端500：{server_500_count}")
print(f"其他失败：{fail_count}")
print(f"第二阶段进度文件：{PHASE2_PROGRESS_FILE}")