feedscope 0.1.0__py3-none-any.whl

feedscope/core/text.py

@@ -0,0 +1,54 @@
+"""终端文本工具：显示宽度、按宽截断与零宽字符清理，渲染层与解析层共用。
+
+显示宽度 = 全宽(F/W)字符 2 列、其余 1 列；中文网页文本里到处是 U+200B
+零宽字符，进终端前清掉。这些是「终端显示」的通用算术，既不属于 ui（渲染）
+也不属于某个源（个性化解析），放 core 让两侧都能 import——parse 层不许依赖
+ui（sources/x/parse.py 曾为此本地复制这两行），core 是它唯一能共享的地方。
+"""
+
+from __future__ import annotations
+
+import unicodedata
+
+# 源码里用转义、别放字面量：字面零宽字符在源码里不可见，极易漏改
+_ZWSP = "\u200b"
+
+
+def char_width(ch: str) -> int:
+    """终端显示宽度：全宽（F/W）字符 2 列，其余 1 列。"""
+    return 2 if unicodedata.east_asian_width(ch) in "FW" else 1
+
+
+def display_width(text: str) -> int:
+    """整串的终端显示宽度（逐字符求和）。"""
+    return sum(char_width(c) for c in text)
+
+
+def truncate_display(text: str, limit: int) -> str:
+    """按显示宽度截断（超长补省略号「…」）；不超长原样返回。"""
+    if display_width(text) <= limit:
+        return text
+    out: list[str] = []
+    used = 0
+    for ch in text:
+        w = char_width(ch)
+        if used + w > limit:
+            break
+        out.append(ch)
+        used += w
+    return "".join(out) + "…"
+
+
+def strip_zwsp(text: str) -> str:
+    """清掉零宽字符（U+200B）并 strip，中文网页文本进终端前的统一清洗。"""
+    return (text or "").replace(_ZWSP, "").strip()
+
+
+def is_cjk(ch: str) -> bool:
+    """是否中日韩字符（表意文字 / 中文标点 / 全角形式）：输入法上屏内容的判定范围。"""
+    return (
+        "\u4e00" <= ch <= "\u9fff"
+        or "\u3400" <= ch <= "\u4dbf"
+        or "\u3000" <= ch <= "\u303f"
+        or "\uff00" <= ch <= "\uffef"
+    )

feedscope/core/timefmt.py

@@ -0,0 +1,53 @@
+"""时间展示格式化：源的原始时间形态 -> 北京时间（UTC+8）「YYYY-MM-DD HH:MM」。
+
+各源原始形态不同（X 是英文 Twitter 串、知乎是页面上的 DOM 文本、HN 是
+UTC 的 ISO 串），统一在这里转成同一展示文本。一律折算成固定的北京时间而非本机时区：
+跨时区设备（服务器/海外机器）不该看到不一样的时间。解析失败
+回空串——时间只是元信息，缺了不致命，别让一行脏数据炸掉整版内容。
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+
+_FMT = "%Y-%m-%d %H:%M"
+_BJT = timezone(timedelta(hours=8))  # 北京时间：固定 UTC+8，无夏令时
+
+
+def _bj(dt: datetime) -> str:
+    try:
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=_BJT)  # 无时区标记的串：当作北京时间（中文站源）
+        return dt.astimezone(_BJT).strftime(_FMT)
+    except (OverflowError, OSError, ValueError):
+        return ""
+
+
+def fmt_twitter(s: str | None) -> str:
+    """X 的 created_at（"Wed Oct 15 08:23:11 +0000 2025"，UTC）-> 北京时间展示文本。"""
+    if not s:
+        return ""
+    try:
+        return _bj(datetime.strptime(s, "%a %b %d %H:%M:%S %z %Y"))
+    except ValueError:
+        return ""
+
+
+def fmt_unix(seconds: float | None) -> str:
+    """unix 秒时间戳（知乎 initialData 的 created 等）-> 北京时间展示文本。"""
+    if not seconds:
+        return ""
+    try:
+        return _bj(datetime.fromtimestamp(int(seconds), tz=_BJT))
+    except (OverflowError, OSError, ValueError):
+        return ""
+
+
+def fmt_iso(s: str | None) -> str:
+    """ISO 8601 串（HN Algolia 的 created_at，UTC 带 Z）-> 北京时间展示文本。"""
+    if not s:
+        return ""
+    try:
+        return _bj(datetime.fromisoformat(s))
+    except (OverflowError, OSError, ValueError):
+        return ""

feedscope/core/tree.py

@@ -0,0 +1,134 @@
+"""讨论树拍平共用件：深层嵌套 -> Comment 模型的两层（顶层 + replies）。
+
+Comment 只有两层而讨论站常嵌四五层（HN / Reddit）：楼层的直接子回复做
+顶层 Comment、更深的后代拍平进它的 replies。「拍成两层」与 @「父作者」
+前缀的规则在这里唯一实现，两站的观感由同一份代码保证：
+
+- 紧贴上一条的那层不加 @（回复对象视觉相邻，@ 冗余）；隔层起加（被拍平
+  后父不一定相邻，@ 是唯一指向）
+- 父已删不给前缀（@ 不到人）；本尊已删有内容照常保留（作者栏是删除占位）
+- 空壳节点（无正文也无孩子，典型是被删且无回复）整支跳过
+
+节点形态各站不同（Algolia 的 dict / HTML 重建的 _CNode），差异经
+TreeAccessors 四件套注入（keep / kids_of / author_of / comment_of；后者
+产本体 Comment，@ 前缀由本模块按上述规则统一拼装，源内不再自拼）。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Generic, TypeVar
+
+from feedscope.core.i18n import t
+from feedscope.core.models import Answer, Comment, Floor
+
+_N = TypeVar("_N")
+
+# 删除态占位词（作者栏 / 正文），HN 与 Reddit 同形，UI 不特判。按调用解析：
+# 常量在 import 期求值会冻住语言；@ 规则靠「同语言的相等比较」辨认删除态，
+# 进程内语言固定（见 core/i18n 模块头），调用点各自解析即自洽
+def deleted_author() -> str:
+    return t("words.deleted_author")
+
+
+def deleted_body() -> str:
+    return t("words.deleted_body")
+
+
+@dataclass(frozen=True)
+class TreeAccessors(Generic[_N]):
+    """站点树节点 -> 通用树遍历的四件套注入（节点形态差异的收口）。
+
+    - keep：空壳判定（整支跳过的规则见模块 docstring）
+    - kids_of：直接子节点序列
+    - author_of：作者名（删除态给 DELETED_AUTHOR，@ 规则靠它辨认）
+    - comment_of：节点 -> Comment 本体（@ 前缀由本模块统一拼装，不自拼）
+    """
+
+    keep: Callable[[_N], bool]
+    kids_of: Callable[[_N], Sequence[_N]]
+    author_of: Callable[[_N], str]
+    comment_of: Callable[[_N], Comment]
+
+
+def _at(parent_author: str, *, direct: bool) -> str:
+    """这层回复的 @ 前缀：direct（紧贴楼上）/ 父缺席 / 父已删 → 不加。"""
+    if direct or not parent_author or parent_author == deleted_author():
+        return ""
+    return f"@{parent_author}"
+
+
+def flatten_comments(
+    nodes: Sequence[_N],
+    acc: TreeAccessors[_N],
+    *,
+    parent_author: str = "",
+    direct: bool = False,
+) -> list[Comment]:
+    """nodes 的全部后代拍平成一串 Comment（@ 前缀标出回复对象，规则见模块 docstring）。"""
+    flat: list[Comment] = []
+    for node in nodes:
+        if not acc.keep(node):
+            continue
+        who = acc.author_of(node)
+        c = acc.comment_of(node)
+        if at := _at(parent_author, direct=direct):
+            c.content_md = f"{at}：{c.content_md}"
+        flat.append(c)
+        flat.extend(
+            flatten_comments(acc.kids_of(node), acc, parent_author=who)
+        )
+    return flat
+
+
+def floor_comments(nodes: Sequence[_N], acc: TreeAccessors[_N]) -> list[Comment]:
+    """楼层（顶层评论）的直接子回复 -> 顶层 Comment；各自更深的后代拍平进 replies。
+
+    直接子回复不加 @：楼层作者就在屏首（与知乎「回答下的评论」同观感）；
+    replies 里第一层（紧贴楼上那条）也不加，@ 从隔层起才有指向价值。
+    """
+    out: list[Comment] = []
+    for node in nodes:
+        if not acc.keep(node):
+            continue
+        c = acc.comment_of(node)
+        c.replies = flatten_comments(
+            acc.kids_of(node), acc, parent_author=acc.author_of(node), direct=True
+        )
+        out.append(c)
+    return out
+
+
+def count_kept(node: _N, acc: TreeAccessors[_N]) -> int:
+    """node 子树内保留下来的评论总数（楼层头「N 条回复」与 meta 评论数用）。
+
+    只用 acc 的 keep/kids_of 两件；与拍平共用同一个注入对象（HN/Reddit
+    的 _ACC 即此），不另造两件套。"""
+    return sum(1 + count_kept(c, acc) for c in acc.kids_of(node) if acc.keep(c))
+
+
+def build_floors(
+    nodes: Sequence[_N],
+    acc: TreeAccessors[_N],
+    *,
+    answer_of: Callable[[_N, int], Answer],
+) -> list[Floor]:
+    """顶层节点序列 -> Floor 列表（HN / Reddit 的「详情一次拉全树」共用）。
+
+    骨架：keep 过滤 → count_kept 数子树 → answer_of(node, n) 造楼层本体
+    （字段来源与 comment_count 引导词是站差异，n 为该层回复数）→
+    floor_comments 拍平该层的回复树。
+    """
+    floors: list[Floor] = []
+    for node in nodes:
+        if not acc.keep(node):
+            continue
+        n = count_kept(node, acc)
+        floors.append(
+            Floor(
+                answer=answer_of(node, n),
+                comments=floor_comments(acc.kids_of(node), acc),
+            )
+        )
+    return floors

feedscope/doctor.py

@@ -0,0 +1,54 @@
+"""`feedscope doctor`：环境自检。逐项检查、逐项打印，退出码 0 = 全部通过。"""
+
+from __future__ import annotations
+
+import sys
+
+from feedscope import __version__
+from feedscope.core.browser import PROFILE_DIR
+from feedscope.core.const import find_chrome
+from feedscope.report import line
+from feedscope.core.i18n import t
+
+
+def _check(label: str, ok: bool, detail: str = "") -> bool:
+    return line("OK" if ok else "FAIL", label, detail)
+
+
+def run_checks() -> int:
+    print(t("doctor.title", version=__version__))
+    print()
+
+    py_ok = sys.version_info >= (3, 11)
+    ok = _check(
+        f"Python {sys.version_info.major}.{sys.version_info.minor}",
+        py_ok,
+        "" if py_ok else t("doctor.need_py"),
+    )
+
+    chrome = find_chrome()
+    ok &= _check(
+        "Google Chrome",
+        bool(chrome),
+        chrome or t("doctor.chrome_missing"),
+    )
+
+    try:
+        import playwright  # noqa: F401
+        import textual  # noqa: F401
+
+        ok &= _check(t("doctor.deps_label"), True, t("doctor.importable"))
+    except ImportError as exc:
+        ok &= _check(t("doctor.deps_label"), False, t("doctor.import_failed", error=exc))
+
+    # 信息项：不算失败
+    state = t("doctor.profile_exists") if PROFILE_DIR.exists() else t("doctor.profile_will_create")
+    _check(t("doctor.profile_label"), True, f"{PROFILE_DIR}（{state}）")
+
+    from feedscope.core.config import config_path, describe
+
+    _check(t("doctor.config_label"), True, f"{config_path()} - {describe()}")
+
+    print()
+    print(t("doctor.all_ok") if ok else t("doctor.has_failures"))
+    return 0 if ok else 1

feedscope/login.py

@@ -0,0 +1,168 @@
+"""登录流程：有头 Chrome 手动登录（知乎扫码、X/Reddit 账号密码），检测到源声明的判据即成功。
+
+为什么有头：二维码在手机上、账号密码要手输，窗口必须可见。
+为什么独立命令：persistent profile 同一时刻只允许一个实例；`feedscope login`
+子命令仍保留（纯命令行场景），但 TUI 内现在也能登录了（见下）。
+哪些源需要登录、登录页在哪、拿什么判登，全部由 Source 的 ClassVar 声明
+（login_url / login_cookie / login_verify / logout_cookies），本文件不认识
+任何具体源——新增需要登录的源只改它自己的包，不动这里。判据优先级：
+login_verify（浏览器级钩子，如 Reddit 的 JWT 解码）> logout_cookies 全集
+（如 X 的 auth_token+ct0）> login_cookie 单枚兜底。
+
+本文件也承载 TUI 内的登录 / 登出：
+- `is_logged_in` / `logout` 复用同一份源声明判据，TUI 撞登录墙后无需退出
+  即可弹浏览器登录、或一键登出换账号。
+- `login(quiet=True)` 供 TUI 调用：抑制 stdout 打印（Textual 会捕获 stdout，
+  落进退出时的刷屏），反馈改由 UI 层自己弹。
+"""
+
+from __future__ import annotations
+
+import asyncio
+from urllib.parse import urlparse
+
+from feedscope.core.browser import PROFILE_DIR, close_session, drop_stale_locks
+from feedscope.core.const import PAGE_TIMEOUT_MS, chrome_launch_kwargs
+from feedscope.core.i18n import t
+
+LOGIN_TIMEOUT = 180  # 秒；3 分钟没扫上就退出
+POLL_INTERVAL = 2
+
+
+async def login(source_id: str = "zhihu", *, quiet: bool = False) -> bool:
+    import feedscope.sources  # noqa: F401  import 即注册
+    from feedscope.core.registry import all_sources, get_source
+
+    try:
+        source = get_source(source_id)
+    except KeyError:
+        ids = ", ".join(s.source_id for s in all_sources())
+        _say(quiet, t("login.unknown_source", source=source_id, ids=ids))
+        return False
+    if not source.login_url:
+        _say(quiet, t("login.not_needed", label=source.label_text))
+        return False
+
+    from playwright.async_api import async_playwright
+
+    _say(quiet, t("login.starting", dir=PROFILE_DIR))
+    _say(quiet, t("login.prompt", label=source.label_text))
+    drop_stale_locks()
+    try:
+        async with async_playwright() as pw:
+            context = await pw.chromium.launch_persistent_context(
+                user_data_dir=str(PROFILE_DIR),
+                headless=False,  # 登录窗口必须可见（扫码/手输密码）
+                **chrome_launch_kwargs(),  # channel/viewport/locale 等，与 browser.py 共用
+            )
+            try:
+                page = context.pages[0] if context.pages else await context.new_page()
+                await page.goto(
+                    source.login_url, wait_until="domcontentloaded", timeout=PAGE_TIMEOUT_MS
+                )
+                # 轮询单独兜底：判据钩子抛错报「登录检测出错」，不被外层误标成
+                # 「浏览器启动失败」（浏览器明明活着，误导排障）
+                try:
+                    if await _await_login(context, source, quiet):
+                        return True
+                except Exception as exc:
+                    _say(quiet, t("login.check_error", error=exc))
+                    return False
+            finally:
+                await context.close()
+    except Exception as exc:  # 浏览器没装/起不来/导航超时：给中文出口，不裸栈
+        _say(quiet, t("login.browser_failed", error=exc))
+        return False
+    _say(quiet, t("login.timeout", seconds=LOGIN_TIMEOUT))
+    return False
+
+
+async def _await_login(context, source, quiet: bool) -> bool:
+    """轮询源声明的判据（口径见 _logged_in）直到成功（True，已报喜）或超时（False）。"""
+    deadline = asyncio.get_running_loop().time() + LOGIN_TIMEOUT
+    while asyncio.get_running_loop().time() < deadline:
+        if await _logged_in(context, source):
+            if source.login_verify is not None:
+                how = t("login.success_state")
+            else:
+                joiner = t("common.enum_comma")
+                how = t("login.success_cookies", cookies=joiner.join(source.judging_cookies))
+            _say(quiet, t("login.success", how=how))
+            return True
+        await asyncio.sleep(POLL_INTERVAL)
+    return False
+
+
+async def yield_profile() -> None:
+    """关掉无头会话让出 profile 锁（有头登录前必经；TUI 账号动线调用）。
+
+    persistent profile 同一时刻只允许一个实例：无头取数会话不先关掉，
+    有头登录窗口会撞锁起不来。登录完成后取数按需自然重开（get_session
+    惰性启动）。调用方还要先释放各自持有的活页签（TUI 的列表 loader）。
+    """
+    await close_session()
+
+
+async def _present_cookies(context, source) -> list[dict]:
+    """读某源登录域下的全部 cookie（本地操作，不导航、不触发反爬）。"""
+    domain = urlparse(source.login_url).netloc
+    return await context.cookies(f"https://{domain}")
+
+
+async def _logged_in(context, source) -> bool:
+    """源声明的判据：login_verify 优先，否则判登 cookie 全集都在。
+
+    cookie 全集口径与 login() 轮询一致（Source.judging_cookies：X 要
+    auth_token+ct0 成对，未声明全集才退单枚 login_cookie）；Reddit 这类
+    匿名访客也发 cookie 的源由 login_verify 做 JWT 解码。
+    """
+    if source.login_verify is not None:
+        return bool(await source.login_verify(context))
+    needed = source.judging_cookies
+    if not needed:
+        return False
+    names = {c["name"] for c in await _present_cookies(context, source)}
+    return set(needed) <= names
+
+
+async def _clear_cookies(context, source) -> bool:
+    """清掉源声明的登录 cookie；返回是否确有登录态被清掉。
+
+    「确有」与判登共用 _logged_in（login_verify 优先）；半套 cookie
+    （如只剩 auth_token 没有 ct0）本就不算已登录，登出反馈「本就未登录」；
+    cookie 照样全清，不留脏状态。"""
+
+    had = await _logged_in(context, source)
+    for name in source.judging_cookies:
+        await context.clear_cookies(name=name)
+    return had
+
+
+async def is_logged_in(source_id: str = "zhihu") -> bool:
+    """当前 profile 是否已登录某源；无任何判据（login_verify / cookie）的源恒为 False。"""
+    from feedscope.core.registry import get_source
+
+    source = get_source(source_id)
+    if source.login_verify is None and not source.judging_cookies:
+        return False
+    from feedscope.core.browser import get_session
+
+    return await get_session().run(_logged_in, source)
+
+
+async def logout(source_id: str = "zhihu") -> bool:
+    """登出某源：清掉判登 cookie；返回是否确有登录态被清掉。"""
+    from feedscope.core.registry import get_source
+
+    source = get_source(source_id)
+    if not source.judging_cookies:
+        return False
+    from feedscope.core.browser import get_session
+
+    return await get_session().run(_clear_cookies, source)
+
+
+def _say(quiet: bool, msg: str) -> None:
+    """CLI 入口打印；TUI（quiet=True）由 UI 层自行反馈，不在 stdout 落字。"""
+    if not quiet:
+        print(msg)

feedscope/probe.py

@@ -0,0 +1,131 @@
+"""`feedscope probe`：源巡检——每个源的每个信息流拉一次首批，改版当天一条命令定位。
+
+- 每流一行：[OK] N 条 / [SKIP] 未登录（LoginRequired，feedscope login 后可测）/
+  [FAIL] 错误消息（含首屏 0 条守卫的「可能已改版」）
+- 首个成功流里挑一条可进详情的再测 open_detail：标题/正文/楼层全空才算坏
+  （0 回复的帖子是正常数据，不算）
+- 默认开样本落盘（FEEDSCOPE_SAMPLE_DIR 未设时设到 ~/.cache/feedscope/samples/）：
+  站点改版后对着真实样本修 parse.py、补 fixture，或把样本交给 AI 重新生成解析器
+- 退出码：有 FAIL = 1（可挂 CI 定时跑，改版当天就知道哪个源坏了）；未知源 id = 2
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from collections.abc import Sequence
+from typing import Literal
+
+from platformdirs import user_cache_path
+
+import feedscope.sources  # noqa: F401  import 即注册，否则巡检不到任何源
+from feedscope.core import http
+from feedscope.core.browser import close_session
+from feedscope.core.models import FeedItem
+from feedscope.core.registry import all_sources
+from feedscope.core.source import FeedLoader, LoginRequired, Source, SourceError
+from feedscope.report import line as _line
+from feedscope.core.i18n import t
+
+
+def _classify(exc: BaseException) -> tuple[Literal["SKIP", "FAIL"], str]:
+    """异常 -> (状态, 消息)：LoginRequired=SKIP、SourceError=FAIL、其余兜住也算 FAIL。
+
+    巡检要兜住一切——崩溃也是发现（取数/详情两处共用同一套分类）。"""
+    if isinstance(exc, LoginRequired):
+        return "SKIP", str(exc)
+    if isinstance(exc, SourceError):
+        return "FAIL", str(exc)
+    return "FAIL", t("probe.unexpected", exc=repr(exc))
+
+
+async def _try_open_feed(
+    source: Source, name: str
+) -> tuple[Literal["OK", "SKIP", "FAIL"], FeedLoader | None, str]:
+    """打开一个流，返回 (状态, loader, 消息)；异常一律兜住转成状态行。"""
+    label = f"{source.label_text} {name}"
+    try:
+        return "OK", await source.open_feed(name), label
+    except Exception as exc:
+        state, msg = _classify(exc)
+        return state, None, f"{label} - {msg}"
+
+
+async def _probe_source(source: Source, stats: dict[str, int]) -> None:
+    """测一个源的全部信息流 + 一条详情；统计写进 stats。"""
+    detail_item: FeedItem | None = None
+    for name in source.feeds:
+        state, loader, line = await _try_open_feed(source, name)
+        if loader is None:
+            _line(state, line)
+            stats[state.lower()] += 1
+            continue
+        try:
+            _line("OK", line, t("probe.n_items", n=len(loader.items)))
+            stats["ok"] += 1
+            if detail_item is None:  # 挑一条可进详情屏的条目测 open_detail
+                detail_item = next(
+                    (it for it in loader.items if it.kind in source.detail_kinds), None
+                )
+        finally:
+            await loader.close()
+
+    if source.supports_detail and detail_item is not None:
+        await _probe_detail(source, detail_item, stats)
+
+
+async def _probe_detail(source: Source, item: FeedItem, stats: dict[str, int]) -> None:
+    label = t("probe.detail_label", label=source.label_text)
+    try:
+        loader = await source.open_detail(item)
+    except Exception as exc:
+        state, msg = _classify(exc)
+        _line(state, label, msg)
+        stats[state.lower()] += 1
+        return
+    try:
+        doc = loader.doc
+        if not (doc.title or doc.description_md or doc.answers):
+            _line("FAIL", label, t("probe.detail_empty"))
+            stats["fail"] += 1
+        else:
+            title = doc.title[:24] + ("…" if len(doc.title) > 24 else "")
+            _line(
+                "OK", label,
+                t("probe.detail_ok", title=title, n=len(doc.answers), unit=source.detail_unit),
+            )
+            stats["ok"] += 1
+    finally:
+        await loader.close()
+
+
+async def _run(only: Sequence[str]) -> int:
+    known = {s.source_id for s in all_sources()}
+    if unknown := [i for i in only if i not in known]:
+        joiner = t("common.enum_comma")
+        print(
+            t("probe.unknown_ids", unknown=joiner.join(unknown), known=joiner.join(sorted(known)))
+        )
+        return 2
+    sample_dir = os.environ.setdefault(
+        "FEEDSCOPE_SAMPLE_DIR", str(user_cache_path("feedscope") / "samples")
+    )
+    print(t("probe.title", dir=sample_dir))
+    print()
+    stats = {"ok": 0, "fail": 0, "skip": 0}
+    try:
+        for source in (s for s in all_sources() if not only or s.source_id in only):
+            await _probe_source(source, stats)
+    finally:
+        await http.close()
+        await close_session()
+    print()
+    print(t("probe.summary", ok=stats['ok'], fail=stats['fail'], skip=stats['skip']))
+    if stats["fail"]:
+        print(t("probe.fail_hint", dir=sample_dir))
+    return 1 if stats["fail"] else 0
+
+
+def run_probes(only: Sequence[str] = ()) -> int:
+    """同步入口（cli 用）：巡检全部源或指定源，返回进程退出码。"""
+    return asyncio.run(_run(only))

feedscope/report.py

@@ -0,0 +1,19 @@
+"""行式检查输出：doctor / probe 共用的 [OK]/[FAIL]/[SKIP] 状态行。
+
+标记的宽度与配色取向只在这里定义一次——两个子命令的输出永远同形，
+用户在一个工具里认得的标记在另一个里不用重学。
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+State = Literal["OK", "FAIL", "SKIP"]  # 状态行三态（doctor / probe 共用）
+
+MARKS: dict[str, str] = {"OK": "[OK]  ", "FAIL": "[FAIL]", "SKIP": "[SKIP]"}  # OK 补空格对齐三态
+
+
+def line(state: State, label: str, detail: str = "") -> bool:
+    """打一行状态；返回是否 OK（调用方累计通过项用）。"""
+    print(f"{MARKS[state]} {label}" + (f" - {detail}" if detail else ""))
+    return state == "OK"

feedscope/sources/__init__.py

@@ -0,0 +1,38 @@
+"""源插件包：import 即注册（类装饰器 @register），import 顺序 = 列表顺序。
+
+import 按 source_id 字母正序书写 = 源选择列表与未配置时的默认 Tab 序（该
+不变量由 test_source_caps 钉住：新增源插错位置测试即红）。
+
+新增一个源 = 按下面的模板建一个包 + 在这里挂一行 import，UI 与 core 零改动
+（用户侧隐藏内置流走 sources.toml，见 core/config.py，不动这里；可订阅源
+另在 subscriptions 登记一个 SubsStore，test_source_caps 会查漏）：
+
+    sources/<id>/
+      fetch.py      取数层：拿原始数据（httpx / 通道页签 fetch / DOM 提取），
+                    持资源的增量 Loader 也放这里；不碰 UI。
+      parse.py      解析层：raw dict/HTML -> FeedItem/Answer/DetailDoc/markdown，
+                    纯函数，直接可写 fixture 测试；不碰网络。
+      __init__.py   编排层：@register 的 Source 子类，做能力声明与 open_* 分派
+                    （出口统一过 require_feed_items 首屏守卫）、判登门
+                    （core.source.login_gate，判据是源差异）。
+
+编排层按源形态直接继承共享骨架，别重写机械件（详情骨架 / 批次去重 /
+判登 cookie 读取都已收口）：
+- 纯订阅聚合（RSS / Telegram 形）：继承 core.source.SubscribedSource——
+  feeds 加法合成、「全部」流的四级错误出口全在基类，子类只注入
+  _fetch_merged / _open_one 两个差异
+- 详情一次拉全树（HN / Reddit / V2EX 形）：楼层/评论 loader 继承
+  core.source.SliceDetailLoader，翻页切片零代码
+- 正文随列表带回（RSS / Telegram 形）：详情用 core.source.StaticDetailLoader，
+  进详情零请求
+- 讨论树深层拍平：core.tree（@ 父作者前缀规则全库唯一实现）
+
+依赖方向只允许 __init__ -> fetch -> parse -> core（parse 永远是最底层叶子）。
+"""
+from feedscope.sources import hn  # noqa: F401
+from feedscope.sources import reddit  # noqa: F401
+from feedscope.sources import rss  # noqa: F401
+from feedscope.sources import telegram  # noqa: F401
+from feedscope.sources import v2ex  # noqa: F401
+from feedscope.sources import x  # noqa: F401
+from feedscope.sources import zhihu  # noqa: F401