feedscope 0.1.0__py3-none-any.whl

feedscope/core/config.py

@@ -0,0 +1,367 @@
+"""用户配置：sources.toml 选启用的源 + 隐藏不想看的内置信息流 + 各源订阅表。
+
+- 路径：FEEDSCOPE_CONFIG 环境变量（测试、多套配置切换），缺省用户配置目录下
+  sources.toml（platformdirs，Linux 为 ~/.config/feedscope/sources.toml）
+- 容错哲学：配置问题绝不挡启动——文件不存在 = 全默认；TOML 语法错 / 结构
+  不符 = 警告日志 + 当作不存在（feedscope doctor 可诊断）。
+- 写入走 save_enabled（首启引导 / F2 管理界面）、update_feeds（订阅管理
+  屏 / rss 子命令）与 save_language（语言选择屏）：保留各源 hide 段与
+  feeds 订阅表（订阅是用户数据，覆写丢段 = 丢订阅；rss 的 feed、reddit
+  的 subreddit、telegram 的频道同款）与顶层 language，无法识别的键丢弃；
+  原子落盘（临时文件 + os.replace），不留半截文件。
+- 本模块对「源」只认 id 字符串，不认识任何具体源：订阅 key 的保留字
+  （聚合流名 / 内置流名）由各源自己声明（Source.reserved_feed_keys），
+  读取侧的过滤在 SubscribedSource、添加侧的拒收在 subscriptions。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from platformdirs import user_config_path
+
+from feedscope.core.i18n import t
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class Subscription:
+    """一条订阅（rss 的 feed / reddit 的 subreddit / telegram 的频道同形）：
+    key 即信息流名（侧栏与 open_feed 的寻址键）。"""
+
+    key: str
+    label: str  # 侧栏显示名；配置缺省 = key 本身
+    url: str
+
+
+def config_path() -> Path:
+    if p := os.environ.get("FEEDSCOPE_CONFIG"):
+        return Path(p)
+    return user_config_path("feedscope") / "sources.toml"
+
+
+def _read() -> tuple[dict, str]:
+    """读配置返回 (数据, 状态描述)；不存在 / 坏 = ({}, 原因)，不抛异常。"""
+    path = config_path()
+    try:
+        with path.open("rb") as f:
+            return tomllib.load(f), ""
+    except FileNotFoundError:
+        return {}, t("config.describe_not_created")
+    except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError) as exc:
+        # 非 UTF-8 字节（手编/别的工具写坏）也是「坏配置」：容错哲学要求
+        # 绝不挡启动，不能让它以 UnicodeDecodeError 逃出 _read
+        logger.warning("用户配置 %s 无法解析，已忽略：%s", path, exc)
+        return {}, t("config.describe_unparsable", error=exc)
+
+
+def hidden_feeds(source_id: str) -> list[str]:
+    """读某源要隐藏的流名列表。
+
+    期望结构（本源的结构不符 = 警告并当全默认，不波及其他源）：
+
+        [zhihu]
+        hide = ["follow"]
+    """
+    section = _read()[0].get(source_id)
+    if not isinstance(section, dict):
+        return []
+    hidden = section.get("hide")
+    if hidden is not None and (
+        not isinstance(hidden, list) or not all(isinstance(n, str) for n in hidden)
+    ):
+        logger.warning("配置 [%s] hide 应为流名列表，已忽略", source_id)
+        hidden = []
+    return list(hidden or [])
+
+
+def feeds_for(source_id: str) -> list[Subscription]:
+    """读某源的订阅表（书写顺序即侧栏顺序），结构与坏条目逐条容错。
+
+    期望结构（label 缺省用 key；url 必填）：
+
+        [rss.feeds]
+        ruanyq = { label = "阮一峰周刊", url = "https://….com/atom.xml" }
+        hn = { url = "https://hnrss.org/frontpage" }
+
+        [reddit.feeds]            # url 存 subreddit 站内地址，自解释
+        rust = { url = "https://www.reddit.com/r/rust/" }
+
+        [telegram.feeds]
+        durov = { url = "https://t.me/durov/" }
+
+    条目不是表 / 缺 url = 警告并跳过该条，不波及其他订阅（同一容错粒度：
+    文件级坏 = 全默认已在上层 _read，这里是条目级）。保留字（聚合流名 /
+    内置流名）撞名的 key 原样返回——过滤在各源的 SubscribedSource（读取
+    侧会跳过并警告），拒收在 subscriptions 的添加入口，本模块不认识源。
+    """
+    section = _read()[0].get(source_id)
+    feeds_raw = section.get("feeds") if isinstance(section, dict) else None
+    if feeds_raw is None:
+        return []
+    if not isinstance(feeds_raw, dict):
+        logger.warning("配置 [%s] feeds 应为订阅表，已忽略", source_id)
+        return []
+    feeds: list[Subscription] = []
+    for key, entry in feeds_raw.items():
+        feed = _subscription_from_entry(key, entry)
+        if feed is not None:
+            feeds.append(feed)
+    return feeds
+
+
+def _subscription_from_entry(
+    key: str, entry: object, *, context: str = ""
+) -> Subscription | None:
+    """订阅表条目 -> Subscription；坏条目记警告并跳过。
+
+    读路径（feeds_for）与写路径（_valid_feeds）共用同一条校验规则——
+    「读得进来、写得回去」不再靠两处各自维护。
+    """
+    prefix = f"{context}：" if context else ""
+    if not isinstance(entry, dict) or not isinstance(entry.get("url"), str) or not entry["url"]:
+        logger.warning("%s订阅 %r 应为含非空 url 的表，已跳过", prefix, key)
+        return None
+    label = entry.get("label")
+    if label is not None and not isinstance(label, str):
+        logger.warning("%s订阅 %r 的 label 应为字符串，已回退用 key", prefix, key)
+        label = None
+    return Subscription(key=key, label=label or key, url=entry["url"])
+
+
+def rss_feeds() -> list[Subscription]:
+    """rss 源的订阅表（feeds_for 的 rss 特例，保留既有调用名）。"""
+    return feeds_for("rss")
+
+
+def enabled_ids() -> list[str] | None:
+    """读顶层启用的源 id 列表；None = 未配置（默认全部启用，老文件只有 hide 的用户不受影响）。
+
+    期望结构：
+
+        enabled = ["zhihu", "x"]
+
+    列表里的未知 id 不在此报错——注册表过滤在调用方（新装/卸载源后残留条目无害）。
+    手编重复 id 按首次出现去重：重复项会让主屏建出重复 tab（DuplicateIds），
+    顺序语义也只剩第一份有意义。
+    """
+    enabled = _read()[0].get("enabled")
+    if enabled is None:
+        return None
+    if not isinstance(enabled, list) or not all(isinstance(i, str) for i in enabled):
+        logger.warning("配置 enabled 应为源 id 列表，已忽略（默认全部启用）")
+        return None
+    return list(dict.fromkeys(enabled))
+
+
+def is_configured() -> bool:
+    """是否已完成首次设置（配置文件存在）。
+
+    只看文件存在与否：TOML 坏文件是 doctor 的职责，不重新引导——
+    引导保存会覆写，坏文件里可能还有用户手写的其他内容。
+    """
+    return config_path().exists()
+
+
+def get_language() -> str | None:
+    """读顶层语言设置（i18n 语言代码，如 "zh-CN" / "en"）；None = 未设置。
+
+    未设置不是错误：读侧缺省在 core.i18n（回退基准语言），未设置的用户
+    会在下次启动被语言选择屏询问（首启流程见 ui/screens/language.py）。
+    """
+    lang = _read()[0].get("language")
+    if lang is None:
+        return None
+    if not isinstance(lang, str) or not lang:
+        logger.warning("配置 language 应为语言代码字符串，已忽略")
+        return None
+    return lang
+
+
+def save_language(code: str) -> None:
+    """保存语言设置（语言选择屏的落盘路径）；enabled / hide / feeds 原样保留。"""
+    data = _read()[0]
+    data["language"] = code
+    _write_config(_render_config(_enabled_from_data(data), data))
+
+
+def _toml_str(s: str) -> str:
+    # json 字符串即合法 TOML 基本串（转义规则同源），不为此引入写库
+    return json.dumps(s, ensure_ascii=False)
+
+
+_BARE_KEY = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+def _toml_key(s: str) -> str:
+    """键/段名：能裸写就裸写（[rss.feeds] 好读），含特殊字符才引用 _toml_str。"""
+    return s if _BARE_KEY.match(s) else _toml_str(s)
+
+
+def _toml_array(values: list[str]) -> str:
+    return "[" + ", ".join(_toml_str(v) for v in values) + "]"
+
+
+def _valid_feeds(raw: object) -> list[tuple[str, str, str]]:
+    """feeds 表的写前校验：留 (key, label, url)，坏条目丢弃记日志。
+
+    与 feeds_for 共用 _subscription_from_entry（表 + 非空 str url、label
+    只收 str），读写往返规则只有一处。
+    """
+    if raw is None:
+        return []
+    if not isinstance(raw, dict):
+        logger.warning("覆写配置：feeds 应为订阅表，已丢弃 %r", raw)
+        return []
+    out: list[tuple[str, str, str]] = []
+    for key, entry in raw.items():
+        feed = _subscription_from_entry(key, entry, context="覆写配置")
+        if feed is not None:
+            out.append((feed.key, feed.label, feed.url))
+    return out
+
+
+def _enabled_from_data(data: dict) -> list[str] | None:
+    """从配置数据里取出规范化的 enabled（坏值按未配置；空列表是合法的零启用）。"""
+    raw = data.get("enabled")
+    if not isinstance(raw, list):
+        return None
+    kept = list(dict.fromkeys(x for x in raw if isinstance(x, str)))
+    return kept if kept or not raw else None
+
+
+def _render_config(ids: list[str] | None, data: dict) -> list[str]:
+    """配置全量渲染为 TOML 行；ids 为 None = 不写 enabled 行（缺省 = 全启用）。
+
+    只写本工具认识的键：language + enabled + 各源非空 hide 段 + feeds 订阅表
+    （其余丢弃，记 info——这里的「重新生成」与手改文件的自由度是此消彼长，
+    注释头已说明归属）。feeds 是用户数据（不是工具生成的状态），必须原样
+    保留——丢段等于丢订阅；language 同理（i18n 的落盘键，漏写 = 丢语言设置）。
+    """
+    lines = [f"# {line}" for line in t("config.file_header").splitlines()]
+    language = data.get("language")
+    if isinstance(language, str) and language:
+        lines += ["", f"language = {_toml_str(language)}"]
+    if ids is not None:
+        lines += ["", f"enabled = {_toml_array(ids)}"]
+    for sid, section in data.items():
+        if sid in ("enabled", "language"):
+            continue  # 已由参数 ids / language 行统一重写，不是「无法识别的顶层键」
+        if not isinstance(section, dict):
+            logger.info("覆写配置：忽略无法识别的顶层键 %r", sid)
+            continue
+        if set(section) - {"hide", "feeds"}:
+            logger.info(
+                "覆写配置：[%s] 里除 hide/feeds 外的键不被保留 %r",
+                sid, sorted(set(section) - {"hide", "feeds"}),
+            )
+        hide = section.get("hide")
+        feeds = _valid_feeds(section.get("feeds"))
+        if (isinstance(hide, list) and hide) or feeds:
+            lines += ["", f"[{_toml_key(sid)}]"]
+            if isinstance(hide, list) and hide:
+                lines.append(f"hide = {_toml_array(hide)}")
+            if feeds:
+                # 订阅行用内联表：一行一条，手编/比对都清爽；键引用字符串形式
+                # （json 串即合法 TOML），key 带空格等字符也不会写出坏文件
+                lines.append(f"[{_toml_key(sid)}.feeds]")
+                lines += [
+                    f"{_toml_key(key)} = {{ url = {_toml_str(url)}, label = {_toml_str(label)} }}"
+                    for key, label, url in feeds
+                ]
+    return lines
+
+
+def _write_config(lines: list[str]) -> None:
+    """原子落盘（临时文件 + os.replace）：读者要么旧文件要么新文件，没有半截。"""
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def save_enabled(ids: list[str]) -> None:
+    """保存启用的源列表（首启引导 / F2 管理界面的落盘路径）。"""
+    _write_config(_render_config(list(dict.fromkeys(ids)), _read()[0]))
+
+
+def update_feeds(
+    source_id: str, feeds: list[Subscription], *, drop_enabled_when_empty: bool = False
+) -> None:
+    """整体替换某源的订阅表（订阅管理屏 / rss 子命令的落盘路径）；enabled / hide 原样保留。
+
+    enabled 联动让「加订阅」一步到位：订阅非空且 enabled 已配置但缺该源
+    → 自动补上（加订阅显然是想用，省掉再开 TUI 勾一次）。删到空是否摘
+    enabled 由 drop_enabled_when_empty 决定：rss / telegram 摘（feeds 全
+    来自订阅，没订阅就没有任何流）；reddit 不摘（还有首页/热门内置流）。
+    enabled 未配置不动——缺省本就是全启用，写了反而丢失「未配置」语义。
+    """
+    data = _read()[0]
+    section = data.get(source_id)
+    if not isinstance(section, dict):
+        section = {}
+    if feeds:
+        section["feeds"] = {f.key: {"label": f.label, "url": f.url} for f in feeds}
+    else:
+        section.pop("feeds", None)
+    if section:
+        data[source_id] = section
+    elif source_id in data:
+        del data[source_id]
+    # 坏 enabled（字符串/表/全是非 str）按「未配置」处理：既不参与联动，
+    # 也不把畸形值原样写回去——读侧本来就是当默认全启用；空列表是
+    # 合法状态（零启用），保留
+    enabled = _enabled_from_data(data)
+    if enabled is not None:
+        if feeds and source_id not in enabled:
+            enabled.append(source_id)
+        if not feeds and drop_enabled_when_empty and source_id in enabled:
+            enabled.remove(source_id)
+    _write_config(_render_config(enabled, data))
+
+
+def update_rss_feeds(feeds: list[Subscription]) -> None:
+    """整体替换 rss 订阅表（update_feeds 的 rss 特例，保留既有调用名）。"""
+    update_feeds("rss", feeds, drop_enabled_when_empty=True)
+
+
+def describe() -> str:
+    """doctor 用的一句话状态：未创建 / 解析失败原因 / 语言、启用与隐藏概况。"""
+    data, reason = _read()
+    if reason:
+        return reason
+    parts: list[str] = []
+    lang = data.get("language")
+    if isinstance(lang, str) and lang:
+        parts.append(t("config.describe_language", lang=lang))
+    enabled = data.get("enabled")
+    if isinstance(enabled, list):
+        joiner = t("common.enum_comma")
+        ids = joiner.join(str(i) for i in enabled)
+        parts.append(
+            t("config.describe_enabled_with_ids", n=len(enabled), ids=ids)
+            if enabled
+            else t("config.describe_enabled", n=len(enabled))
+        )
+    n_hidden = n_sources = n_feeds = 0
+    for section in data.values():
+        if not isinstance(section, dict):
+            continue
+        n_sources += 1
+        hide = section.get("hide") or []
+        n_hidden += len(hide) if isinstance(hide, list) else 0
+        feeds = section.get("feeds")
+        n_feeds += len(feeds) if isinstance(feeds, dict) else 0
+    if n_sources:
+        parts.append(t("config.describe_overrides", n=n_sources, hidden=n_hidden))
+    if n_feeds:
+        parts.append(t("config.describe_feeds", n=n_feeds))
+    return " · ".join(parts) if parts else t("config.describe_not_created")

feedscope/core/const.py

@@ -0,0 +1,64 @@
+"""跨源共享常量与小工具：改这里即改全部源。
+
+站点特有调参（滚动步长、选择器、httpx 之外的取数细节）仍留在各源文件--
+只有「多源复制粘贴且必须同步变」的值才收进来。
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import html2text
+
+# 桌面 UA 与请求超时：core/http 共享客户端的默认头（友好源的请求全走它）
+DESKTOP_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
+HTTP_TIMEOUT = 20  # 秒
+
+# Playwright 页面导航超时（毫秒）
+PAGE_TIMEOUT_MS = 30_000
+
+# channel="chrome" 硬编码依赖的标准安装位置（macOS）与 PATH 候选名（Linux）
+CHROME_PATH = Path("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome")
+CHROME_BINS = ("google-chrome", "google-chrome-stable", "chrome", "google-chrome-beta")
+
+
+def find_chrome() -> str:
+    """Chrome 可执行文件路径；找不到回空串（doctor 自检与截图脚本共用的唯一实现）。"""
+    if CHROME_PATH.exists():
+        return str(CHROME_PATH)
+    return next((p for name in CHROME_BINS if (p := shutil.which(name))), "")
+
+
+def safe_int(value: object) -> int:
+    """野数据防御的整数化：None/空/非数字/无穷大回 0（解析层对 API 野值的统一口径）。"""
+    if not isinstance(value, (int, float, str)):
+        return 0  # 非数字类型（None/bool 之外的对象）原也走 except -> 0
+    try:
+        return int(value or 0)
+    except (TypeError, ValueError, OverflowError):
+        return 0
+
+
+def new_h2t() -> html2text.HTML2Text:
+    """HTML2Text 统一配置：不硬换行（body_width 会把中文撕碎）；img/video 在进它
+    之前已换成记号（见各源 _md），ignore_images 兜底丢掉漏网残片。
+    """
+    h2t = html2text.HTML2Text()
+    h2t.body_width = 0
+    h2t.ignore_images = True
+    return h2t
+
+
+def chrome_launch_kwargs() -> dict:
+    """Chrome persistent context 公共启动参数（channel 固定本机 Chrome，无开关）。
+
+    browser.py（TUI 内无头）与 login.py（手动登录有头）共用；headless 由调用方给。
+    """
+    return {
+        "channel": "chrome",
+        "viewport": {"width": 1280, "height": 900},  # 桌面布局，避免命中移动端 DOM
+        "locale": "zh-CN",
+        "timezone_id": "Asia/Shanghai",
+        "args": ["--disable-blink-features=AutomationControlled"],
+    }

feedscope/core/display.py

@@ -0,0 +1,62 @@
+"""全 app 展示词汇的唯一出处：署名、计数、赞文本。
+
+各源数据形态不同（X 的 GraphQL、知乎的 API JSON），但上屏词汇必须同形——
+用户在源之间的体验是同一个软件，不是 N 个爬虫的拼接。源的 parse 层只把
+原始数值/字段传进来，拼接规则全部收口在这里；新增源照用，别自拼。
+
+词汇表（与 UI 层的既定形态对齐；各源行为见 README 的站点说明）：
+- 署名 signature(name, handle)：「名字 @handle」——账号体系双要素的源
+  （X/论坛）两样都露；没有 @ 账号惯例的源（知乎，站方 @ 提及用姓名）只传
+  name，不硬造站方没有的形态。各语言形态一致，不经 i18n
+- 计数 fmt_count：随语言二形——中文过万折「万」保留一位小数（45000 ->
+  4.5 万），其余语言按千分位 K/M 折（45000 -> 45K、1234000 -> 1.2M）。
+  折法是书写惯例不是文案，代码分支按语言族收在这里（zh* 用万，其余
+  K/M——新语言默认进 K/M 形）
+- 赞 votes_text：「赞 4.5 万」/「45K likes」；0 赞空文本（与站方按钮同
+  形态，楼层头不占位）
+"""
+
+from __future__ import annotations
+
+from feedscope.core import i18n
+from feedscope.core.i18n import t
+
+
+def signature(name: str = "", handle: str = "") -> str:
+    """作者署名「名字 @handle」：两样都露，缺谁剩谁，全缺空串。"""
+    if name and handle:
+        return f"{name} @{handle}"
+    return f"@{handle}" if handle else name
+
+
+def _use_wan() -> bool:
+    """计数折法用「万」还是 K/M：中文书写惯例用万，其余按 K/M。"""
+    return i18n.language().startswith("zh")
+
+
+def fmt_count(n: int) -> str:
+    """整数计数 -> 展示文本（随语言二形，见模块头词汇表）。"""
+    if _use_wan():
+        return f"{n / 10000:.1f} {t('display.wan')}".replace(".0 ", " ") if n >= 10000 else str(n)
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.1f}M".replace(".0M", "M")
+    if n >= 1000:
+        return f"{n / 1000:.1f}K".replace(".0K", "K")
+    return str(n)
+
+
+def votes_text(n: int) -> str:
+    """赞数 -> 楼层头赞文本；0 赞空文本（无赞不占位）。"""
+    return t("display.votes", n=fmt_count(n)) if n else ""
+
+
+def view_count_text(n: int) -> str:
+    """知乎详情 meta 的浏览数段（带前导「 · 」分隔符）：「 · 1234 万浏览」。
+
+    「万浏览」是站方复合词（fmt_count 出「1234 万」会多个空格），中文分支
+    拼写与站方同形；其余语言走 K/M 计数一条模板。分隔符进模板：语种想换
+    分隔形态改文件即可。
+    """
+    if _use_wan():
+        return t("display.visits_wan", n=n // 10000) if n >= 10000 else t("display.visits", n=n)
+    return t("display.visits", n=fmt_count(n))

feedscope/core/http.py

@@ -0,0 +1,104 @@
+"""共享 HTTP 客户端池：httpx 源的统一取数通道与错误出口。
+
+- 进程级单例 AsyncClient：同 host 连接复用（翻页时省掉每次的 TCP/TLS 握手）
+- httpx 异常统一在边界包成 SourceError（中文、含源标签，UI 可直接展示）
+- 惰性创建：只有真正发请求才建（测试/脚本不碰网络就不建）
+- FEEDSCOPE_SAMPLE_DIR 设定时把响应体落盘（feedscope probe 巡检用，平时零开销）
+
+友好源（RSS/HN/V2EX/Telegram）走这里；敌意源（知乎/Reddit/X）的数据
+通道走 core/browser.ChannelTab——但边界按请求定不按源定：敌意源里的公开
+请求（X 收割的 CDN chunk 下载）也走这里。
+"""
+
+from __future__ import annotations
+
+from typing import Any, TypeVar
+
+import httpx
+
+from feedscope.core import samples
+from feedscope.core.const import DESKTOP_UA, HTTP_TIMEOUT
+from feedscope.core.i18n import t
+from feedscope.core.source import SourceError
+
+_J = TypeVar("_J", dict, list)  # get_json 的期望顶层形状（dict / list）
+
+_client: httpx.AsyncClient | None = None
+
+
+def get_client() -> httpx.AsyncClient:
+    global _client
+    if _client is None:
+        _client = httpx.AsyncClient(
+            headers={"User-Agent": DESKTOP_UA},
+            timeout=HTTP_TIMEOUT,
+            follow_redirects=True,
+        )
+    return _client
+
+
+async def get(
+    url: str,
+    *,
+    source: str,
+    params: dict[str, Any] | None = None,
+    headers: dict[str, str] | None = None,
+    allow_304: bool = False,
+    sample: bool = True,
+) -> httpx.Response:
+    """GET 并校验状态码；httpx 异常统一包成 SourceError。
+
+    source 是展示标签（如 "X"），只进错误消息；params / headers 原样透传
+    （headers 供带鉴权头的源用，如 X 的 Bearer/Cookie）。allow_304 给条件
+    请求的源用（rss 的 ETag/Last-Modified 协商）：304 是「内容没变」的正
+    常语义而非失败，放行给调用方自己回放缓存；其余状态码照常校验。sample
+    关掉样本落盘（X 收割 chunk 下载的 JS bundle 不是 API 响应，留着只占地方）。
+    """
+    try:
+        r = await get_client().get(url, params=params, headers=headers)
+        if not (allow_304 and r.status_code == 304):
+            r.raise_for_status()  # httpx 新版对 3xx 也抛，304 必须先放行
+    except httpx.TimeoutException:
+        raise SourceError(
+            t("errors.http_timeout", source=source, seconds=HTTP_TIMEOUT, url=url)
+        ) from None
+    except httpx.HTTPStatusError as exc:
+        raise SourceError(
+            t("errors.http_status", source=source, code=exc.response.status_code, url=url)
+        ) from None
+    except httpx.HTTPError as exc:
+        raise SourceError(t("errors.http_failed", source=source, error=exc)) from exc
+    if sample:
+        samples.save(samples.url_name(source, str(r.url)), r.content)
+    return r
+
+
+async def get_json(
+    url: str,
+    *,
+    source: str,
+    params: dict[str, Any] | None = None,
+    expect: type[_J],
+) -> _J:
+    """GET 并按 JSON 解析 + 形状校验：JSON API 源（HN/V2EX）共用的小原语。
+
+    两种失败分开报：「返回的不是 JSON」是网络/代理层问题，「返回结构异常，
+    接口可能已变」是改版信号（probe 巡检据此定位）。expect 是期望的顶层
+    形状（dict / list），形状不对视为改版而非崩溃。
+    """
+    r = await get(url, source=source, params=params)
+    try:
+        data = r.json()
+    except ValueError:
+        raise SourceError(t("errors.not_json", source=source)) from None
+    if not isinstance(data, expect):
+        raise SourceError(t("errors.bad_structure", source=source)) from None
+    return data
+
+
+async def close() -> None:
+    """退出前释放连接池；幂等，未创建则无事发生。"""
+    global _client
+    if _client is not None:
+        await _client.aclose()
+        _client = None