feedscope 0.1.0__py3-none-any.whl

feedscope/sources/hn/__init__.py

@@ -0,0 +1,66 @@
+"""HN（Hacker News）源（hn）：首页/最新/Ask/Show 四个信息流 + 讨论树详情。
+
+包内分层（全项目统一的源模板）：
+- fetch.py  取数层：Algolia 公开索引 API（免 key 免登录、无登录态）
+- parse.py  解析层：Algolia JSON -> FeedItem / 楼层与评论树，纯函数可测
+- __init__.py 编排层：Source 能力声明与 open_* 分派（楼层/评论翻页走
+  core 的内存切片基类）
+
+结构映射是知乎式三层：story 本体（正文 = 原文一行 + Ask/Show 自述）->
+顶层评论当楼层（unit「评论」）-> 楼层内回复树当评论层（unit「回复」）。
+items/:id 一次给全树，楼层与评论翻页都是内存切片——详情打开后评论层
+零额外请求。无楼层引导（descendants=0 的楼层头不带「N 条回复」）。
+"""
+
+from __future__ import annotations
+
+from feedscope.core.models import FeedItem
+from feedscope.core.i18n import t
+from feedscope.core.registry import register
+from feedscope.core.source import (
+    FeedLoader,
+    SliceDetailLoader,
+    Source,
+    SourceError,
+)
+from feedscope.sources.hn.fetch import HnFeedLoader, fetch_item
+from feedscope.sources.hn.parse import SOURCE_ID, parse_story
+
+
+class HnDetailLoader(SliceDetailLoader):
+    """HN 详情加载器：树已全在内存——楼层翻页与评论层都是切片，零额外请求。
+
+    全部结构在 SliceDetailLoader.from_detail（楼层/评论树成对进切片），
+    本类只声明报错文案里的源标签（楼层页宽用基类默认）。"""
+
+    source_label = "HN"
+
+
+@register
+class HnSource(Source):
+    source_id = SOURCE_ID
+    label = "HN"
+    supports_detail = True
+    supports_comments = True  # 详情屏 Enter 进楼层的回复树（树已全在内存）
+    feeds: list[str] = ["front", "new", "ask", "show"]
+    # ask/show = Ask HN（向社区提问）/ Show HN（展示自己的项目），HN 官方两大
+    # 经典分类；标签与其余源同款两字中文（列表里帖子标题仍带 Ask/Show HN 前缀）
+    feed_labels: dict[str, str] = {
+        "front": "sources.hn.feeds.front",
+        "new": "sources.hn.feeds.new",
+        "ask": "sources.hn.feeds.ask",
+        "show": "sources.hn.feeds.show",
+    }
+    detail_kinds = frozenset({"story", "ask", "show"})  # 全部条目 Enter 都进终端详情
+    detail_unit_label = "units.comment"  # 楼层单位词：顶层评论串（知乎「回答」、X「回复」）
+    comment_unit_label = "units.reply"  # 楼层内的讨论（知乎叫「评论」）
+
+    async def open_feed(self, name: str) -> FeedLoader:
+        label = self.label_of(name)
+        return await self.first_batch(HnFeedLoader(name, label), label)
+
+    async def open_detail(self, item: FeedItem) -> SliceDetailLoader:
+        root = await fetch_item(item.id)
+        if not root.get("id"):
+            raise SourceError(t("errors.hn_no_id"))
+        return HnDetailLoader.from_detail(parse_story(root), fallback_title=item.title)

feedscope/sources/hn/fetch.py

@@ -0,0 +1,82 @@
+"""取数层：HN 走 Algolia 公开索引 API（免 key 免登录）——search 列表 + items/:id 整树。
+
+两个端点都是单请求水合 JSON：列表一次 30 条全字段；详情一次给全评论树
+（楼层/评论层的翻页全在内存切片，见 __init__ 的内存 Loader），fetch 层只有
+两个无状态 GET 与一个翻页 Loader。索引有分钟级延迟、列表按 points 排序
+（非官方榜序）——接受这两点换零解析成本（官方 Firebase 逐条取、官方
+HTML 要解析 DOM）；真在意榜序时只换本文件的列表通道，树端点不动。
+"""
+
+from __future__ import annotations
+
+from feedscope.core import http
+from feedscope.core.models import FeedItem
+from feedscope.core.source import FeedLoader, SourceError, dedup_append
+from feedscope.core.i18n import t
+from feedscope.sources.hn.parse import parse_search
+
+_API = "https://hn.algolia.com/api/v1"
+
+# 各内置流的 (search 端点, 过滤参数)（feeds 词汇表与顺序见 __init__）：
+# front_page 是「当前首页」快照（30 条）；ask/show 按 tag 过滤；new 按时间倒序
+FEEDS: dict[str, tuple[str, dict[str, str]]] = {
+    "front": (f"{_API}/search", {"tags": "front_page"}),
+    "new": (f"{_API}/search_by_date", {"tags": "story"}),
+    "ask": (f"{_API}/search", {"tags": "ask_hn"}),
+    "show": (f"{_API}/search", {"tags": "show_hn"}),
+}
+
+HITS_PER_PAGE = 30  # 与 HN 官方首页同宽（front_page 恰好 30 条，一页装下）
+
+
+async def fetch_feed(name: str, label: str, page: int) -> dict:
+    """一个信息流的一页 search 结果（原始 JSON dict；解析/校验见 http.get_json）。"""
+    url, base_params = FEEDS[name]
+    return await http.get_json(
+        url,
+        source=f"HN「{label}」",
+        params={**base_params, "hitsPerPage": HITS_PER_PAGE, "page": page},
+        expect=dict,
+    )
+
+
+async def fetch_item(object_id: str) -> dict:
+    """一条 story 的 items/:id 整棵评论树（原始 JSON dict；解析/校验见 http.get_json）。"""
+    return await http.get_json(
+        f"{_API}/items/{object_id}", source=t("sources.hn.detail"), expect=dict
+    )
+
+
+class HnFeedLoader(FeedLoader):
+    """信息流加载器：search 按页翻（page 0 起、nbPages 到头），id 去重。
+
+    索引重排会让跨页撞见已见条目（分数涨跌挤进挤出），dedup_append 与
+    各源共用「同一 id 只出现一次」的不变量；无资源可释（连接池进程级共享）。
+    """
+
+    def __init__(self, name: str, label: str) -> None:
+        self.items: list[FeedItem] = []
+        self._name = name
+        self._label = label
+        self._seen: set[str] = set()
+        self._page = 0  # 下一页页号（Algolia 0 起）
+        self._nb_pages = 1
+
+    @property
+    def done(self) -> bool:
+        return self._page >= self._nb_pages
+
+    async def load_more(self) -> list[FeedItem]:
+        if self.done:
+            return []
+        data = await fetch_feed(self._name, self._label, self._page)
+        hits = data.get("hits")
+        if not isinstance(hits, list):
+            raise SourceError(t("errors.hn_no_hits", label=self._label))
+        new = dedup_append(self.items, self._seen, parse_search(hits))
+        self._page += 1
+        try:
+            self._nb_pages = max(1, int(data.get("nbPages") or 1))
+        except (TypeError, ValueError):
+            self._nb_pages = 1
+        return new

feedscope/sources/hn/parse.py

@@ -0,0 +1,154 @@
+"""解析层：Algolia JSON -> FeedItem / 楼层与评论树，纯函数不碰网络。
+
+HN 的结构映射是知乎式三层（词汇重映射，UI 零特判）：
+- 列表 search hit -> FeedItem（objectID 即条目 id，tag 分 kind）
+- items/:id 根 -> story 本体（链接帖正文 = 原文一行；Ask/Show 自述全文）
+- 顶层评论 -> 楼层（Answer，unit「评论」）；楼层的回复树 -> 评论层
+  （Comment，unit「回复」）。Comment 模型只有两层而 HN 常嵌四五层：
+  直接子回复做顶层，更深的拍平进 replies；隔层的回复加「@父作者」
+  前缀保住「在回复谁」的指向（紧贴楼上的不加，同知乎观感）。整棵树
+  一次已在内存，翻页是切片不是请求（见 __init__ 的内存 Loader）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from feedscope.core.const import safe_int
+from feedscope.core.display import fmt_count
+from feedscope.core.i18n import t
+from feedscope.core.media import text_to_md
+from feedscope.core.models import Answer, Comment, FeedItem, Floor
+from feedscope.core.timefmt import fmt_iso
+from feedscope.core.tree import (
+    deleted_author,
+    deleted_body,
+    TreeAccessors,
+    build_floors,
+    count_kept,
+)
+
+SOURCE_ID = "hn"
+
+# HN 原生条目页：自帖的兜底 url 与楼层直达链接（评论 permalink 也是 item 页）
+_ITEM_URL = "https://news.ycombinator.com/item?id="
+
+
+def _md(html: object) -> str:
+    """HN 受限 HTML（p/a/i/code）-> markdown；非 str / 空回空串（管线见 core.media）。"""
+    return text_to_md(html) if isinstance(html, str) else ""
+
+
+def _kids(node: dict) -> list[dict]:
+    kids = node.get("children")
+    return [c for c in kids if isinstance(c, dict)] if isinstance(kids, list) else []
+
+
+def _keep(node: dict) -> bool:
+    """空壳节点（无正文也无孩子，典型是被删且无回复的评论）整支跳过。"""
+    return bool(_md(node.get("text")) or _kids(node))
+
+
+def _author(node: dict) -> str:
+    return str(node.get("author") or "") or deleted_author()
+
+
+def _time(node: dict) -> str:
+    created = node.get("created_at")
+    return fmt_iso(created if isinstance(created, str) else None)
+
+
+def _comment_of(node: dict) -> Comment:
+    """Algolia 节点 -> Comment 本体（@ 前缀由 core.tree 统一拼装）。"""
+    return Comment(
+        author=_author(node),
+        votes="",  # Algolia 树节点不带分值，HN 评论也无赞数语义
+        content_md=_md(node.get("text")) or deleted_body(),
+        time=_time(node),
+        raw_id=str(node.get("id") or ""),
+    )
+
+
+def _answer_of(node: dict, n: int) -> Answer:
+    """楼层本体（core.tree.build_floors 注入）：字段来源是站差异，n 为回复数。"""
+    cid = str(node.get("id") or "")
+    return Answer(
+        author=_author(node),
+        votes="",
+        content_md=_md(node.get("text")) or deleted_body(),
+        time=_time(node),
+        url=f"{_ITEM_URL}{cid}" if cid else "",
+        comment_count=t("display.replies_n", n=n) if n else "",  # 0 条不引导 Enter
+    )
+
+
+# 差异注入：HN 的树是 Algolia dict（结构见各 accessor；拍平骨架在 core.tree）
+_ACC = TreeAccessors(keep=_keep, kids_of=_kids, author_of=_author, comment_of=_comment_of)
+
+
+def _meta(points: int, comments: int, author: str) -> str:
+    """元信息列「N 点 · N 评 · 作者」：列表 hit 与详情 root 共用。"""
+    parts = [
+        t("words.points", n=fmt_count(points)),
+        t("words.comments_short", n=fmt_count(comments)),
+    ]
+    if author:
+        parts.append(author)
+    return " · ".join(parts)
+
+
+def parse_search(hits: list[dict]) -> list[FeedItem]:
+    """search hits -> FeedItem 列表（保持返回序，野数据逐条防御）。"""
+    items: list[FeedItem] = []
+    for hit in hits:
+        oid = str(hit.get("objectID") or "")
+        if not oid.isdigit():
+            continue  # 无 id 无法寻址，跳条不跳流
+        tags = hit.get("_tags")
+        tags = tags if isinstance(tags, list) else []
+        kind = "ask" if "ask_hn" in tags else "show" if "show_hn" in tags else "story"
+        items.append(
+            FeedItem(
+                source=SOURCE_ID,
+                id=oid,
+                title=str(hit.get("title") or "").strip() or t("words.no_title"),
+                url=str(hit.get("url") or "") or f"{_ITEM_URL}{oid}",  # 自帖无外链，兜底条目页
+                kind=kind,
+                meta=_meta(
+                    safe_int(hit.get("points")), safe_int(hit.get("num_comments")),
+                    str(hit.get("author") or ""),
+                ),
+            )
+        )
+    return items
+
+
+@dataclass
+class StoryDetail:
+    """items/:id 的解析结果：story 本体 + 全部楼层（含各自的回复树）。"""
+
+    title: str
+    meta: str
+    time: str
+    description_md: str
+    floors: list[Floor] = field(default_factory=list)
+
+
+def parse_story(root: dict) -> StoryDetail:
+    """items/:id 根 -> StoryDetail（story 本体 + 顶层评论楼层与各自回复树）。"""
+    blocks = []
+    if url := str(root.get("url") or ""):
+        blocks.append(f"{t('words.original')}({url})")  # 链接帖正文就是外链一行，Ctrl+O 直达
+    if text_md := _md(root.get("text")):
+        blocks.append(text_md)  # Ask/Show 的自述全文
+    # 顶层节点 -> 楼层（keep 过滤 / 计数 / 拍平的骨架在 core.tree.build_floors）
+    return StoryDetail(
+        title=str(root.get("title") or "").strip(),
+        meta=_meta(
+            safe_int(root.get("points")), count_kept(root, _ACC),
+            str(root.get("author") or ""),
+        ),
+        time=_time(root),
+        description_md="\n\n".join(blocks),
+        floors=build_floors(_kids(root), _ACC, answer_of=_answer_of),
+    )

feedscope/sources/reddit/__init__.py

@@ -0,0 +1,178 @@
+"""Reddit 源（reddit）：首页/热门两个内置流 + subreddit 订阅表 + 帖子详情（评论树）。
+
+包内分层（全项目统一的源模板）：
+- fetch.py  取数层：网站自己的 HTML 通道（shreddit SSR 页面 + faceplate
+  partial 翻页），由常驻 reddit.com 通道页签的真 Chrome 发出（知乎同款，
+  TLS/头序/cookie 与登录会话自洽；.json 遗留端点已全线 403）
+- parse.py  解析层：shreddit HTML -> FeedItem / 帖子与评论树，纯函数可测
+- __init__.py 编排层：Source 能力声明与 open_* 分派 + 内存分页 Loader
+
+结构映射是 HN 式三层：帖子（自述帖 HTML 转 markdown / 链接帖原文一行 /
+媒体记号）-> 顶层评论当楼层（unit「评论」）-> 楼层内回复树当评论层
+（unit「回复」）。permalink 页单请求 SSR 自带整树，楼层与评论翻页全在
+内存切片——详情打开后评论层零额外请求（同 HN）。
+
+feeds 是混形合成（介于知乎减法与 RSS 加法之间）：内置流 home=首页 /
+popular=r/popular 走 hide 减法，[reddit.feeds] 订阅表（subreddit 名即
+key，url 存站内地址自解释）走加法——零订阅仍有内置流（与 RSS 的纯订阅
+合成不同）。subscribable=True：F2 里 → 进订阅管理屏（与 RSS 共用一屏，
+按源分派见 ui/screens/subscriptions.py 的 store）。
+
+登录：本源必须登录。`feedscope login reddit` 弹 Chrome 手动输账号密码
+（+2FA）。判据一律是 token_v2 的 JWT 本地解码（登录态 sub="user"、
+匿名态 sub="loid"，见 _token_logged_in）——Reddit 的判登 cookie 全不可
+信：reddit_session 匿名流量也发、token_v2 光看在不在更不行；解码零网络
+零请求，匿名流量伪造不出。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json as _json
+from typing import ClassVar
+
+from feedscope.core import config
+from feedscope.core.i18n import t
+from feedscope.core.models import FeedItem
+from feedscope.core.registry import register
+from feedscope.core.source import (
+    FeedLoader,
+    SliceDetailLoader,
+    Source,
+    SourceError,
+    login_gate,
+    require_feed_items,
+)
+from feedscope.sources.reddit.fetch import RedditFeedLoader, fetch_thread_html
+from feedscope.sources.reddit.parse import SOURCE_ID, parse_thread_html
+
+
+class RedditDetailLoader(SliceDetailLoader):
+    """Reddit 详情加载器：树已全在内存——楼层翻页与评论层都是切片，零额外请求。
+
+    全部结构在 SliceDetailLoader.from_detail（楼层/评论树成对进切片），
+    本类只声明报错文案里的源标签（楼层页宽用基类默认）。"""
+
+    source_label = "Reddit"
+
+
+def _token_logged_in(token_v2: str | None) -> bool:
+    """token_v2 的 JWT claims 是登录的本地铁证：登录态 sub="user"（匿名态 sub="loid"）。
+
+    Reddit 的判登 cookie 全都不可信：reddit_session 匿名流量也发（实测打开
+    登录页即出现）、token_v2 光看在不在更不行——但 token_v2 本体是 JWT，
+    登录后 Reddit 重签的版本 claims 里 sub 从 "loid"（Logged-Out ID）变成
+    "user" 且带 at=1/aid=账号id（2026-11 实测两种形态各解码一次）。本地
+    解码零请求、匿名流量伪造不出，是判登/登录轮询的地面真值。
+    """
+    if not token_v2:
+        return False
+    try:
+        payload = token_v2.split(".")[1]
+        payload += "=" * (-len(payload) % 4)
+        claims = _json.loads(base64.urlsafe_b64decode(payload))
+        return claims.get("sub") == "user"
+    except (IndexError, ValueError):
+        return False
+
+
+async def _login_verified(ctx) -> bool:
+    """登录成功的浏览器级判据（login.py 轮询 login_verify）：token_v2 解码出登录态。
+
+    读登录窗口上下文的 cookie、本地解码 JWT（见 _token_logged_in）——零网络
+    （这台网络 www 的 me.json 连登录会话都 403，问不了服务端）、零页面
+    依赖（登录中途跳 accounts 域也不影响）。登录完成 Reddit 重签 token_v2
+    的瞬间即可检出。
+    """
+    cookies = await ctx.cookies("https://www.reddit.com")
+    jar = {c["name"]: c["value"] for c in cookies}
+    return _token_logged_in(jar.get("token_v2"))
+
+
+async def require_login(what: str) -> None:
+    """判登门：token_v2 JWT 过门（通道页签的 cookie 由浏览器自带，无需另建会话）。
+
+    公共 API：subscriptions 的 subreddit 添加入口也过这道门（订阅管理屏
+    没有账号动线，LoginRequired 的消息自带指引）。cookie 读取与消息模板
+    在 core.source.login_gate，判据（JWT 解码）是本源差异。
+    """
+    await login_gate(
+        "https://www.reddit.com",
+        lambda c: _token_logged_in(c.get("token_v2")),
+        label="Reddit",
+        what=what,
+    )
+
+
+@register
+class RedditSource(Source):
+    source_id = SOURCE_ID
+    label = "Reddit"
+    supports_detail = True
+    supports_comments = True  # 详情屏 Enter 进楼层的回复树（树已全在内存）
+    subscribable = True  # feeds 除内置流外还来自 [reddit.feeds] 订阅表：F2 里 → 进订阅管理
+    detail_kinds = frozenset({"link", "self"})  # 全部条目 Enter 都进终端详情
+    detail_unit_label = "units.comment"  # 楼层单位词：顶层评论串（同 HN）
+    comment_unit_label = "units.reply"  # 楼层内的讨论（同 HN）
+    login_url = "https://www.reddit.com/login"
+    login_cookie = "token_v2"  # 兜底显示用（真实判据是 login_verify 的 JWT 解码）
+    login_verify = staticmethod(
+        _login_verified
+    )  # 登录成功 = token_v2 解码出登录态（cookie 出现不算数）
+    logout_cookies: ClassVar[list[str]] = ["reddit_session", "token_v2"]  # 登出两枚都清
+
+    # 内置流：流名 -> 列表页 URL（订阅流的页面是 https://www.reddit.com/r/{key}/）
+    _BUILTIN: ClassVar[dict[str, str]] = {
+        "home": "https://www.reddit.com/",
+        "popular": "https://www.reddit.com/r/popular/",
+    }
+    _BUILTIN_LABELS: ClassVar[dict[str, str]] = {
+        "home": "sources.reddit.feeds.home", "popular": "sources.reddit.feeds.popular",
+    }
+    # 订阅 key 不得撞内置流名（/r/home、/r/popular 真实存在，撞名会遮住内置流）：
+    # 从 _BUILTIN 派生，新增内置流时保留字自动跟上（subscriptions 的拒收读这里）
+    reserved_feed_keys = tuple(_BUILTIN)
+
+    def __init__(self) -> None:
+        """混形合成：内置流剔 hide（减法）+ 订阅表各成一流（加法，RSS 同款）。
+
+        不调 super().__init__()——它的合成规则只对类默认流做减法；这里 feeds
+        还要拼 [reddit.feeds] 的订阅 key。订阅 key 与内置流撞名（/r/home、
+        /r/popular 真实存在）在添加入口已拦，手编配置漏网的在这里静默跳过。
+        """
+        hidden = set(config.hidden_feeds(self.source_id))
+        subs = [
+            f
+            for f in config.feeds_for(self.source_id)
+            if f.key not in hidden and f.key not in self._BUILTIN
+        ]
+        self._subs = {f.key: f for f in subs}
+        self.feeds = [f for f in self._BUILTIN if f not in hidden] + list(self._subs)
+        self.feed_labels = {f: self._BUILTIN_LABELS[f] for f in self._BUILTIN if f not in hidden}
+        self.feed_labels.update({k: f.label for k, f in self._subs.items()})
+
+    async def open_feed(self, name: str) -> FeedLoader:
+        label = self.label_of(name)
+        page = (
+            self._BUILTIN.get(name) or f"https://www.reddit.com/r/{name}/"
+        )  # 订阅 key 即 subreddit 名
+        await require_login(t("errors.what_feed", label=label))
+        loader = RedditFeedLoader(page, label)
+        await loader.load_more()  # 首批（判登在此抛 LoginRequired）
+        if name == "home" and not loader.items:
+            # 首页是账号在 Reddit 站内「关注版块」的聚合：账号没关注任何版块
+            # 就是真空（实测新号如此），不是改版——通用 0 条守卫会误导
+            raise SourceError(t("errors.reddit_home_empty"))
+        require_feed_items(loader.items, self.label_text, label)  # 0 条 = 大概率改版
+        return loader
+
+    async def open_detail(self, item: FeedItem) -> SliceDetailLoader:
+        await require_login(t("errors.what_post_detail"))
+        html = await fetch_thread_html(item.url)  # 列表给的绝对 permalink（slug 全）
+        # 1.5MB 级 SSR 页的解析 ~160ms：放工作线程跑，不卡事件循环（解析是
+        # 纯函数；HTML2Text 已线程本地化，见 core.media.h2t）。换篇取消的是
+        # await——线程会把旧结果跑完但协程已死、结果自然丢弃（线程无法取消，
+        # 白算一次是换篇的既有代价）
+        detail = await asyncio.to_thread(parse_thread_html, html, fallback_title=item.title)
+        return RedditDetailLoader.from_detail(detail)

feedscope/sources/reddit/fetch.py

@@ -0,0 +1,181 @@
+"""取数层：Reddit 走通道页签（知乎同款）——常驻 reddit.com 页签的页面 fetch。
+
+2026 年起边缘对 .json 遗留端点全线 403（第三方通道关闭的一部分），且对
+非浏览器画像（TLS/头序/HTTP2 指纹）的检查随时可能收紧——取数全部改由
+常驻页签里的真 Chrome 发出（fetch credentials include）：TLS、头序、
+cookie 与登录会话完全自洽，httpx 侧的头画像维护整体退役。网站自己的
+HTML 全放行：页面（SSR，帖子/评论树直接织在 HTML 里）与翻页 partial
+（text/vnd.reddit.partial+html）页签里都拿得到。
+
+- 通道：进程级单例页签停在 www.reddit.com 上（同源 fetch 与 cookie 的
+  前提，生命周期见 core/browser.ChannelTab），evaluate 撞上在途跳转/页签
+  被关都重建重试一次；判登门在编排层（token_v2 JWT 解码，见
+  __init__.py），门没过到不了这层
+- 列表：流页面起步（首页 / 、热门 /r/popular/ 、订阅 /r/{sub}/ ），翻页
+  跟随页面/片段里 faceplate-partial slot="load-after" 的 src 链（服务端
+  给全参 URL，feeds/*-feed 与 community-more-posts 两族不用自己认）
+- 详情：帖子 permalink 页 SSR 自带整棵评论树（1.5MB 级；深度大的树被
+  服务端截断，解析层给「另有 N 条未展开」）
+- x-reddit-client-version：随 Reddit 部署轮换，且浏览器不会自动带
+  （SPA 自定义头）——照旧收割，但比 httpx 时代更便宜：服务端把版本织
+  进每个页面 HTML，每个页面响应顺手正则一次（进程内缓存，首批 partial
+  通常零额外请求），partial 403 时再专割一次自愈（版本确实轮换过才重试）
+- 401/403 且重割无效时给「登录态可能已过期或被风控」的指引——绝不自动
+  清 cookie（历史教训：误清即登录死循环）
+- 样本落盘在 ChannelTab.fetch 里统一做（probe 巡检对着真实 HTML 修
+  parse）
+
+请求画像：刷流 1 页面 + N-1 片段（每片段 50-90 帖）、开帖 1 请求，远在
+Reddit 登录态限流（约 100 次/分）之下。
+"""
+
+from __future__ import annotations
+
+import re
+
+from feedscope.core.browser import ChannelTab
+from feedscope.core.models import FeedItem
+from feedscope.core.source import FeedLoader, SourceError, dedup_append
+from feedscope.core.i18n import t
+from feedscope.sources.reddit.parse import (
+    parse_next_html,
+    parse_posts_html,
+    parse_subreddit_page,
+)
+
+_API = "https://www.reddit.com"
+
+_tab = ChannelTab(
+    f"{_API}/", name="reddit"
+)  # 停靠 www.reddit.com/：同源 fetch（referer/cookie）的前提
+
+# 一次 load_more 至少攒够的条数：SSR 页面只嵌 3-10 帖（站点首屏后自己
+# 也会续拉一批），不足就顺着 load-after 链补齐——「一屏上下、翻页有货」
+# （HN 30、X 20 的同款折中）
+_MIN_BATCH = 20
+
+# x-reddit-client-version 的形态（如 2026-11-04T13:46Z~456d6f1d）：部署时
+# 轮换，服务端织进每个页面的 HTML
+_VERSION_RE = re.compile(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}Z~[0-9a-f]{6,8}")
+
+# partial 翻页的请求头（与 SPA 自己发的同形）；页面请求只需要 Accept html。
+# referer 不手设：页签停在 www.reddit.com/ 上，同源 fetch 的自然 referer
+# 就是它（2026-11 实测矩阵里 referer 在场即可，同站即同形）
+_PARTIAL_ACCEPT = "text/vnd.reddit.partial+html, text/html;q=0.9"
+_HTML_ACCEPT = "text/html,application/xhtml+xml,application/xml;q=0.9"
+
+_version: str | None = None  # 进程级缓存（页面响应顺手更新，403 自愈时重割）
+
+
+async def _raw_fetch(
+    url: str, accept: str, version: str | None, *, source: str
+) -> tuple[int | None, str]:
+    """一次通道 fetch -> (HTTP 状态码或 None, HTML 正文)；解包/报错/样本落盘见 ChannelTab.fetch。
+
+    状态码原样上交（403 的自愈决策在 _get_html），成功时正文连同状态码
+    一起返回——收割路径要 403 页不炸，取数路径才转错误。手动头只有
+    Accept 与 partial 的版本头/retry 头（浏览器不会自动带的）。
+    """
+    headers = {"Accept": accept}
+    if version:
+        headers["x-reddit-client-version"] = version
+        headers["x-reddit-retry"] = "attempt=0, max=2"
+    status, body = await _tab.fetch(url, source=source, headers=headers, as_text=True)
+    return status, (body or "")
+
+
+async def _harvest_version() -> None:
+    """专割一次版本头（从热门页 HTML）；失败保留旧值。
+
+    页面响应的顺手收割（见 _get_html）让这条路通常只剩 403 自愈在走：
+    partial 首用且缓存为空、或版本轮换后的重割。
+    """
+    global _version
+    try:
+        _, body = await _raw_fetch(f"{_API}/r/popular/", _HTML_ACCEPT, None, source="Reddit")
+    except SourceError:
+        return  # 收割失败保留旧值（可能是网络抖动，不是版本问题）
+    if m := _VERSION_RE.search(body):
+        _version = m.group(0)
+
+
+async def _get_html(url: str, *, source: str, partial: bool = False) -> str:
+    """一次通道 fetch -> HTML 文本；partial 首用前收割版本头，403 时重割自愈一次。"""
+    global _version
+    if partial and not _version:
+        await _harvest_version()  # partial 必须带版本头：先割再用（空头发必 403）
+    accept = _PARTIAL_ACCEPT if partial else _HTML_ACCEPT
+    status, body = await _raw_fetch(url, accept, _version if partial else None, source=source)
+    if status in (401, 403):
+        if partial:  # 版本头是 partial 独有的变量：轮换过就新头原址重试一次
+            saved = _version
+            await _harvest_version()
+            if _version and _version != saved:
+                status, body = await _raw_fetch(url, accept, _version, source=source)
+        if status:
+            raise SourceError(
+                t("errors.reddit_status_login", source=source, status=status)
+            ) from None
+    if not partial and (m := _VERSION_RE.search(body)):
+        _version = m.group(0)  # 服务端把版本织进每个页面：顺手收割，首批 partial 免一次专割
+    return body
+
+
+async def fetch_listing(url: str, *, source: str = "Reddit") -> tuple[list[FeedItem], str | None]:
+    """一页列表（页面或片段 URL）-> (FeedItem, 下一页 URL)；None = 到底。"""
+    html = await _get_html(url, source=source, partial="/svc/" in url)
+    return parse_posts_html(html), parse_next_html(html)
+
+
+async def fetch_thread_html(permalink: str, *, source: str = "") -> str:
+    """帖子 permalink 页的 SSR HTML（解析见 parse.parse_thread_html）。"""
+    return await _get_html(permalink, source=source or t("sources.reddit.post"))
+
+
+async def fetch_subreddit(name: str) -> str:
+    """r/{name}/ 页面校验存在性；返回页面自述的 subreddit 名（订阅添加用）。"""
+
+    html = await _get_html(f"{_API}/r/{name}/", source=f"Reddit r/{name}")
+    real = parse_subreddit_page(html)
+    if not real:
+        raise SourceError(t("errors.reddit_subreddit_gone", name=name))
+    return real
+
+
+class RedditFeedLoader(FeedLoader):
+    """列表翻页：页面起步、跟随 load-after partial 链；链尽即到底。
+
+    SSR 页面只内嵌 3-10 帖（站点自己也这样：首屏渲染几帖，余下靠前端
+    续拉），一批不足 _MIN_BATCH 就顺着链继续拉到够——用户视角「首屏即
+    一屏」，稀疏首屏只在链尽（真没更多）时出现。不持有页签（通道是
+    进程级单例，随会话生灭）。
+    """
+
+    def __init__(self, page_url: str, label: str) -> None:
+        self._page_url = page_url
+        self._label = label
+        self.items: list[FeedItem] = []
+        self._seen: set[str] = set()
+        self._next: str | None = None
+        self._started = False
+        self._done = False
+
+    @property
+    def done(self) -> bool:
+        return self._done
+
+    async def load_more(self) -> list[FeedItem]:
+        if self._done:
+            return []
+        added: list[FeedItem] = []
+        while not self._done and len(added) < _MIN_BATCH:
+            url = self._page_url if not self._started else (self._next or "")
+            if not url:
+                self._done = True
+                break
+            self._started = True
+            items, nxt = await fetch_listing(url, source=f"Reddit「{self._label}」")
+            self._next = nxt
+            self._done = nxt is None
+            added.extend(dedup_append(self.items, self._seen, items))
+        return added