Skip to content

armgit / peach

Public Imported from GitHub
0

Peach: Local-first video metadata scraper and media manager.

docs(adr): 订阅源错峰的决策改号为 ADR-0134

longmeidao51d2bb5579cb
diff --git a/docs/REUSE.md b/docs/REUSE.md
index 2904f2118..4e11dc0ad 100644
--- a/docs/REUSE.md
+++ b/docs/REUSE.md
@@ -872,7 +872,7 @@ A 盘垃圾隔离使用短名称 `peach-purge-<32 位 UUID>.peach-quarantine`,
- Iwara 视频作者订阅复用 [yt-dlp 的 Iwara 提取器](https://github.com/yt-dlp/yt-dlp/blob/9b58cb33d0cd3e823c8d8732f6adce8faa1f37e3/yt_dlp/extractor/iwara.py)(Unlicense,固定 revision `9b58cb33d0cd3e823c8d8732f6adce8faa1f37e3`)的 profile→用户 ID→videos 分页模型与 `X-Version` 文件接口签名;[gallery-dl 的 Iwara 提取器](https://github.com/mikf/gallery-dl/blob/882c8d0bb5c5a3ed4e88726d2f42a1cb7db59bf2/gallery_dl/extractor/iwara.py)(GPL-2.0,固定 revision `882c8d0bb5c5a3ed4e88726d2f42a1cb7db59bf2`)用于交叉核对 `apiq.iwara.tv`、视频文件字段与格式清单,不复制其实现。两者在 2026-10-23 获取时均维护中,Python 客户端可跨平台运行;完整下载器包含 Peach 不使用的下载、账户缓存与大量站点能力,因此只复用公开协议模型和 Unlicense 签名算法,不新增依赖。HTTP 复用现有 `curl_cffi`:匿名只读 POC 中普通 HTTP 对 API 返回 403,Chrome 传输取得作者资料、视频列表两页、详情与三档格式,五次请求约 4.9 KB、4.7 秒,未读取凭据或下载媒体。Peach 保留 DTO、关注状态、历史游标、凭据隔离及媒体代理;可选 `access_token` 仅发送到固定 API,不同步。列表只保存稳定视频页地址,短效文件地址与清晰度仅在播放缓存中保留;外部播放器、权限不足、空历史页、限流与结构错误分别处理。用法见 [Iwara 视频作者订阅](SOURCING.md#iwara-视频作者订阅)。
- Iwara 封面复用 `/follow-image` 的同源缓存,官方缩略图经正式 HTTPX 传输实测取得 200 `image/jpeg`;来源图标采用官网声明且实测为 PNG 的 `/logo.png`。官方头像专用解析路径未取得,作者头像沿用首字母回退;作者主页的用户名与署名复用既有官方别名学习。部分迁移视频没有可用时长或原画分辨率,字段保留未知,播放仍优先选择 `Source` 原画。标签模型另核对 [IwaraTool API 字段说明](https://github.com/Moeary/IwaraTool/blob/1e98c96c422a169699c0d16bcab49b8a7f5238d5/docs/API_zh.md)(MIT,固定 revision `1e98c96c422a169699c0d16bcab49b8a7f5238d5`,仅核对协议,不复制代码);匿名 `/tags` 与八条视频的 28 个标签均为 `id/type/sensitive` 模型。仅 `type=general` 明确进入 Peach 的通用词表,其他类型与缺少类型的原词保留,原始类型另存 `source_tag_types`,不按词形推断。
- 关注检查分两阶段:列表阶段落 partial 行,详情补全按 provider 额度只补新行和未补齐行。「补齐过」由连接器的 `ENRICHED_MARK` 声明、判据登记在 `follow_store._ENRICHED_PREDICATES`。
-- 定时关注检查只查到期的来源,按已有的 `last_checked_at` 与条目时间现算(`follow_check.due_for_check`),不加列、不起第二套调度;订阅源复用同一个 `FollowUpdateScheduler`,只多一个 `tick_minutes`(ADR-0132)。
+- 定时关注检查只查到期的来源,按已有的 `last_checked_at` 与条目时间现算(`follow_check.due_for_check`),不加列、不起第二套调度;订阅源复用同一个 `FollowUpdateScheduler`,只多一个 `tick_minutes`(ADR-0134)。
- 关注原始证据复用 Python 标准库 `hashlib.sha256` 与既有 `write_immutable`。快照文件名由检查时间和完整说明的摘要组成;说明含正文 SHA-256、脱敏请求地址及候选数量,因此相同正文的不同游标或筛选结果各有独立证据。相同快照可重复保存,已有文件内容冲突仍拒绝覆盖;历史证据按账本保存的相对路径读取,无迁移或新增依赖。临时账本回归遍历登记表中的全部追更来源,覆盖正文、地址及候选数量的独立变化,并经 FANBOX 连接器验证相同正文的历史补足和重复检查。
- 单来源失败边界覆盖取回、整页存储和历史补足;证据内容冲突保留错误,已提交的条目继续保留,其他来源继续检查。Web 与 CLI 共用 `follow_check.run_check` 的失败结果,不把证据冲突记成成功。
- 关注检查失败在本机 `follow-check` 事件中保留来源、来源编号、失败阶段、请求页及异常链;只记录登记来源键与技术状态,不复制作者名称或来源地址。单来源错误仍按既有任务结果返回。
diff --git a/docs/SOURCING.md b/docs/SOURCING.md
index 36d3ee889..8c6f0f10c 100644
--- a/docs/SOURCING.md
+++ b/docs/SOURCING.md
@@ -1367,7 +1367,7 @@ Feed 只回答一个问题:**最近出了哪些番号**。它不下载、不
- 限流照库内采集:主机间隔 3 秒、403 就整源停下,冷却判据在 `scraping_access`,见「javdb、AVBase 与 JavBus 的限流与封禁」。
不要因为 Feed 是后台任务就另开一套。
- 定时拉取每 30 分钟看一次谁到期,每个源按 id 在 6 小时窗口里占一个相位(`feeds.next_fetch`)。撞上冷却时整轮只记一条失败,
- 其余源不再请求、顺延到冷却结束(ADR-0132)。
+ 其余源不再请求、顺延到冷却结束(ADR-0134)。
- **加 `?sort_type=4` 拿到的页面一条作品都解不出**,同一轮里不带参数的请求仍是完整页。所以演员页伪 Feed 一律用不带查询串的地址。
- 标题栏 `<span class="actor-section-name">` 是这一页挂的名字,常把几种写法用逗号连成一串(`涼森玲夢, 涼森れむ`);
另一个 `section-meta` 写着「N 部影片」。一位女优常有两页,
diff --git a/docs/adr/0132-feed-and-follow-checks-stagger-by-source.md b/docs/adr/0134-feed-and-follow-checks-stagger-by-source.md
similarity index 99%
rename from docs/adr/0132-feed-and-follow-checks-stagger-by-source.md
rename to docs/adr/0134-feed-and-follow-checks-stagger-by-source.md
index 3dd768018..ab111d373 100644
--- a/docs/adr/0132-feed-and-follow-checks-stagger-by-source.md
+++ b/docs/adr/0134-feed-and-follow-checks-stagger-by-source.md
@@ -1,4 +1,4 @@
-# ADR-0132:订阅源与追更检查按源到期,来源冷却只记一次
+# ADR-0134:订阅源与追更检查按源到期,来源冷却只记一次
- 状态:已采纳
- 日期:2026-11-03
diff --git a/src/peach/api.py b/src/peach/api.py
index 625d52826..413671b1b 100644
--- a/src/peach/api.py
+++ b/src/peach/api.py
@@ -459,7 +459,7 @@ def create_app(
# 订阅源拉取(ADR-0042)用同一个调度实现,只换 job id、状态文件与默认间隔。
# 默认 6 小时:一位女优的 JavDB 演员页一天更新几条,比这更密只是把 JavDB 的配额
# 花在一张没变的页面上。6 小时是每个源的周期;调度每半小时看一次谁到期,各源按
- # 自己的相位错开(ADR-0132)。
+ # 自己的相位错开(ADR-0134)。
feed_scheduler = FollowUpdateScheduler(
settings.follow_state_root,
lambda: web_feeds.w_feed_check(contract, {"automatic": True}),
diff --git a/src/peach/feeds.py b/src/peach/feeds.py
index 1fd97f06b..727d113b5 100644
--- a/src/peach/feeds.py
+++ b/src/peach/feeds.py
@@ -30,7 +30,7 @@ KIND_LABELS = {KIND_JAVDB_ACTOR: "JAV 订阅"}
#: 拉取间隔。JavDB 按出口 IP 计配额,一张一天才更新几条的页面拉得再密也只是花配额。
DEFAULT_INTERVAL_MINUTES = 360
-#: 定时拉取多久看一次有没有到期的源(ADR-0132)。每个源仍按自己的间隔拉,这一档只决定
+#: 定时拉取多久看一次有没有到期的源(ADR-0134)。每个源仍按自己的间隔拉,这一档只决定
#: 到期之后最多再等多久;源在间隔窗口里各占一个相位,一跳只拉落在这半小时里的那几个。
TICK_MINUTES = 30
@@ -343,7 +343,7 @@ def due_sources(connection: sqlite3.Connection, now: str | None = None) -> list[
def next_fetch(source_id: int, moment: datetime, interval_minutes: int) -> datetime:
- """这个源下一次该拉的时刻:「现在 + 间隔」附近、落在它自己相位上的那一刻(ADR-0132)。
+ """这个源下一次该拉的时刻:「现在 + 间隔」附近、落在它自己相位上的那一刻(ADR-0134)。
不直接取「现在 + 间隔」:调度每跳之间隔着 `TICK_MINUTES`,拉完那一刻总比到期晚一点,
按它往后排会一轮轮漂,同一时刻加的源也永远在同一跳一起到期。相位由 id 定,过渡那一轮
diff --git a/src/peach/follow_check.py b/src/peach/follow_check.py
index 91e5d102b..06fe26703 100644
--- a/src/peach/follow_check.py
+++ b/src/peach/follow_check.py
@@ -90,7 +90,7 @@ def plan_check(store, credentials, *, source_id: int | None = None,
return rows
-#: 定时检查按来源活跃度放慢(ADR-0132):最近一条距今不到这么久,就按基础间隔的这个倍数查。
+#: 定时检查按来源活跃度放慢(ADR-0134):最近一条距今不到这么久,就按基础间隔的这个倍数查。
#: 基础间隔是设置里的「自动检查间隔」。越过最后一档的、一条都没有的,一天查一次。
ACTIVITY_TIERS = ((timedelta(days=7), 1), (timedelta(days=30), 3), (timedelta(days=90), 12))
DORMANT_INTERVAL = timedelta(days=1)
diff --git a/src/peach/follow_scheduler.py b/src/peach/follow_scheduler.py
index e99299eff..55f1f67a2 100644
--- a/src/peach/follow_scheduler.py
+++ b/src/peach/follow_scheduler.py
@@ -93,7 +93,7 @@ class FollowUpdateScheduler:
"automatic follow updates are available only on the ledger writer"):
self.job_id = job_id
#: 多久跑一次。不给就等于设置里的间隔;订阅源给的是 `feeds.TICK_MINUTES`:
- #: 那边设置里的间隔是每个源的周期,到期由源自己判(ADR-0132)。
+ #: 那边设置里的间隔是每个源的周期,到期由源自己判(ADR-0134)。
self.tick_minutes = tick_minutes
self.unavailable_message = unavailable_message
self.store = FollowScheduleStore(state_root, filename, default)
@@ -223,7 +223,7 @@ class FollowUpdateScheduler:
self._last_started_at = started_before
return
if result.get("idle"):
- # 这一跳没有到期的来源(订阅源每半小时一跳,ADR-0132):什么也没做,
+ # 这一跳没有到期的来源(订阅源每半小时一跳,ADR-0134):什么也没做,
# 上一轮的结论原样留着。按成功结算的话,一次真实失败半小时后就从界面上消失,
# 而失败的那几个源还要等到下一次到期才重拉。
skipped = True
diff --git a/src/peach/web_feeds.py b/src/peach/web_feeds.py
index df10ec17b..9bfbb24ac 100644
--- a/src/peach/web_feeds.py
+++ b/src/peach/web_feeds.py
@@ -34,7 +34,7 @@ FETCH_MAX_BYTES = 2 * 1024 * 1024
MAX_SOURCES_PER_RUN = 20
#: 定时那几轮多久派一次存量后继:旧壳重试、补封面、缺头像的存量女优与想要作品重试
-#: (ADR-0132)。定时拉取每 `feeds.TICK_MINUTES` 一跳,存量跟着每跳派一次就成了原来的十几倍;
+#: (ADR-0134)。定时拉取每 `feeds.TICK_MINUTES` 一跳,存量跟着每跳派一次就成了原来的十几倍;
#: 本轮新发现的番号不受它管,照旧当场派取资料。
STOCK_INTERVAL = timedelta(hours=6)
@@ -276,7 +276,7 @@ def _execute_check(contract, body, job_id: str) -> dict:
def _defer_round(contract, pending, until: datetime, results: list) -> tuple[list, int]:
- """来源在冷却:这一轮剩下的源都顺延到冷却结束,整轮只记一条失败(ADR-0132)。
+ """来源在冷却:这一轮剩下的源都顺延到冷却结束,整轮只记一条失败(ADR-0134)。
冷却是整个来源的状态,不是哪个订阅的毛病;每个源各记一条「正在冷却」只会把真正的
原因淹掉。本轮撞上 403 的那一行已经写了原因,就在它后面补一句顺延了几个;本轮一开始
diff --git a/src/peach/web_follow.py b/src/peach/web_follow.py
index a35ee5228..5bc8c05fe 100644
--- a/src/peach/web_follow.py
+++ b/src/peach/web_follow.py
@@ -2357,7 +2357,7 @@ class _FollowCheckSession:
self.initial_days = follow_initial_days(contract.database)
self.cooldown = getattr(contract, 'follow_media_resolver', None)
#: 站点限流冷却中、这一轮没问的来源数。它们不进结果:没问就谈不上成败,
- #: 下一跳照常到期(ADR-0132)。
+ #: 下一跳照常到期(ADR-0134)。
self.deferred = 0
def checkpoint(self, **fields):
@@ -2419,7 +2419,7 @@ def _run_follow_check(contract, body, job_id=None) -> dict:
# 不会因为重走而倒退。补齐标记缺键的行在重走时各自重探一次详情。
rewind = bool(body.get("rewind"))
credentials = _credential_store(contract)
- # 定时那一跳只查到期的来源,久没更新的按档放慢(ADR-0132);点名的、往回翻的、
+ # 定时那一跳只查到期的来源,久没更新的按档放慢(ADR-0134);点名的、往回翻的、
# 手动「检查全部」和续跑冻结下来的那一批都不按到期筛。
scheduled = None
if (body.get("automatic") and source_id is None and "sources" not in body and not older
diff --git a/tests/test_feeds.py b/tests/test_feeds.py
index 6dd38b3cc..96518a111 100644
--- a/tests/test_feeds.py
+++ b/tests/test_feeds.py
@@ -164,7 +164,7 @@ class CompilationTest(unittest.TestCase):
class FeedPhaseTest(unittest.TestCase):
- """下次拉取按源的相位排(ADR-0132):同时加的源错开,跳与跳之间的延迟不累积。"""
+ """下次拉取按源的相位排(ADR-0134):同时加的源错开,跳与跳之间的延迟不累积。"""
MOMENT = datetime(2026, 11, 3, 3, 28, 57, tzinfo=timezone.utc)
PERIOD = timedelta(minutes=feeds.DEFAULT_INTERVAL_MINUTES)
diff --git a/tests/test_feeds_web.py b/tests/test_feeds_web.py
index 4236103b3..d8df3dd6f 100644
--- a/tests/test_feeds_web.py
+++ b/tests/test_feeds_web.py
@@ -444,7 +444,7 @@ class FeedWebTest(FeedWebFixture):
return {int(row["id"]): dict(row) for row in connection.execute("SELECT * FROM feed_source")}
def test_a_refused_round_records_one_failure_and_defers_the_rest_to_the_cooldown_end(self):
- """一轮里撞上 403:只记撞上的那一条,其余源不再问、顺延到冷却结束(ADR-0132)。"""
+ """一轮里撞上 403:只记撞上的那一条,其余源不再问、顺延到冷却结束(ADR-0134)。"""
from peach import scraping_access
first, *rest = self._sources_named("Smp2", "Smp3")
served = self.transport
diff --git a/tests/test_follow_check.py b/tests/test_follow_check.py
index a2a8ed2ae..a6c965c13 100644
--- a/tests/test_follow_check.py
+++ b/tests/test_follow_check.py
@@ -323,7 +323,7 @@ class PlanCheckTests(_CheckCase):
class ScheduledCheckTests(_CheckCase):
- """定时检查按来源活跃度放慢;手动检查照旧全查(ADR-0132)。"""
+ """定时检查按来源活跃度放慢;手动检查照旧全查(ADR-0134)。"""
def _checked_with_latest(self, ref, age):
source_id = self._register(ref=ref, url=f"https://{ref}.fanbox.cc/")
diff --git a/tests/test_follow_scheduler.py b/tests/test_follow_scheduler.py
index 8af1dc352..7800dc864 100644
--- a/tests/test_follow_scheduler.py
+++ b/tests/test_follow_scheduler.py
@@ -197,7 +197,7 @@ class FollowUpdateSchedulerTests(unittest.TestCase):
"连续失败后应当推后,而不是照原间隔继续敲上游")
def test_a_tick_shorter_than_the_period_runs_often_and_backs_off_from_the_tick(self):
- """订阅源:设置里的间隔是每个源的周期,调度按更短的一跳看谁到期(ADR-0132)。"""
+ """订阅源:设置里的间隔是每个源的周期,调度按更短的一跳看谁到期(ADR-0134)。"""
with tempfile.TemporaryDirectory() as temporary:
scheduler = FollowUpdateScheduler(
Path(temporary), lambda: {"ok": True, "checked": 0, "results": []},
diff --git a/tests/test_follow_web.py b/tests/test_follow_web.py
index fee9b55bd..07399022a 100644
--- a/tests/test_follow_web.py
+++ b/tests/test_follow_web.py
@@ -175,7 +175,7 @@ class FollowContractTests(unittest.TestCase):
self.assertEqual(factory.call_count, 1)
def test_sources_skipped_for_a_site_cooldown_are_not_reported_as_failures(self):
- """站点限流冷却中:同站的来源这一轮不问,也不进失败清单(ADR-0132)。"""
+ """站点限流冷却中:同站的来源这一轮不问,也不进失败清单(ADR-0134)。"""
from peach.follow_stream import FollowMediaResolver
self._seed(ref='first')
self._seed(ref='second')