Peach: Local-first video metadata scraper and media manager.
docs(adr): 订阅源错峰的决策改号为 ADR-0134
longmeidao51d2bb5579cb
diff --git a/docs/REUSE.md b/docs/REUSE.mdindex 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.mdindex 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.mdsimilarity index 99%rename from docs/adr/0132-feed-and-follow-checks-stagger-by-source.mdrename to docs/adr/0134-feed-and-follow-checks-stagger-by-source.mdindex 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-03diff --git a/src/peach/api.py b/src/peach/api.pyindex 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.pyindex 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.pyindex 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.pyindex 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_minutesself.unavailable_message = unavailable_messageself.store = FollowScheduleStore(state_root, filename, default)@@ -223,7 +223,7 @@ class FollowUpdateScheduler:self._last_started_at = started_beforereturnif result.get("idle"):- # 这一跳没有到期的来源(订阅源每半小时一跳,ADR-0132):什么也没做,+ # 这一跳没有到期的来源(订阅源每半小时一跳,ADR-0134):什么也没做,# 上一轮的结论原样留着。按成功结算的话,一次真实失败半小时后就从界面上消失,# 而失败的那几个源还要等到下一次到期才重拉。skipped = Truediff --git a/src/peach/web_feeds.py b/src/peach/web_feeds.pyindex df10ec17b..9bfbb24ac 100644--- a/src/peach/web_feeds.py+++ b/src/peach/web_feeds.py@@ -34,7 +34,7 @@ FETCH_MAX_BYTES = 2 * 1024 * 1024MAX_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.pyindex 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 = 0def 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 = Noneif (body.get("automatic") and source_id is None and "sources" not in body and not olderdiff --git a/tests/test_feeds.py b/tests/test_feeds.pyindex 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.pyindex 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_accessfirst, *rest = self._sources_named("Smp2", "Smp3")served = self.transportdiff --git a/tests/test_follow_check.py b/tests/test_follow_check.pyindex 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.pyindex 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.pyindex 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 FollowMediaResolverself._seed(ref='first')self._seed(ref='second')