feedscope 0.1.0__py3-none-any.whl

feedscope/sources/reddit/parse.py

@@ -0,0 +1,318 @@
+"""解析层：Reddit 网页 HTML（shreddit SSR / faceplate partial）-> FeedItem /
+帖子与评论树，纯函数不碰网络。
+
+2026-11 起 www 的 .json 遗留端点对第三方全线 403，本源改吃网站自己的
+HTML 通道（请求由常驻 reddit.com 通道页签的真 Chrome 发出，见 fetch.py）：
+- 列表：流页面 SSR（首页 / 热门 r/popular / 订阅 r/{sub}）+ 翻页跟随
+  faceplate-partial slot="load-after" 的 src 链（feeds/*-feed 与
+  community-more-posts 两族，src 里带全参数不用自己拼）
+- 详情：帖子 permalink 页 SSR 自带整棵评论树（1.5MB 级，深度大的树被
+  服务端截断，用「另有 N 条未展开」诚实提示，不续拉）
+
+结构映射是 HN 式三层（词汇重映射，UI 零特判），语义与旧 JSON 版一致：
+- <shreddit-post> 开标签属性即帖子全部元数据（id/post-title/score/
+  comment-count/subreddit-name/permalink/post-type/content-href）
+- 顶层评论 -> 楼层（Answer，unit「评论」）；楼层内回复树按 depth 属性
+  重建 -> 评论层（Comment，unit「回复」）。Comment 模型只有两层而
+  Reddit 常嵌四五层：照 HN 拍平——直接子回复做顶层，更深的拍平进
+  replies；隔层回复加「@父作者」前缀
+- 正文是结构化 HTML（rtjson 渲染产物），统一走 html_to_md（同 Telegram）
+
+Reddit 特有语义：
+- score：楼层与评论都有值
+- [deleted]/[removed]：作者/正文的删除占位（作者栏 [已删除]、正文
+  「（已删除）」；有回复的删除评论保留树形）
+- 广告：promoted 帖不带 t3_ id（或 class 带 promoted），静默跳过
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from urllib.parse import urljoin
+
+from feedscope.core.const import safe_int
+from feedscope.core.display import fmt_count, votes_text
+from feedscope.core.media import attrs as tag_attrs
+from feedscope.core.media import html_to_md, mark
+from feedscope.core.models import Answer, Comment, FeedItem, Floor
+from feedscope.core.timefmt import fmt_iso
+from feedscope.core.i18n import t
+from feedscope.core.tree import deleted_author, deleted_body, TreeAccessors, build_floors
+
+SOURCE_ID = "reddit"
+
+_SITE = "https://www.reddit.com"
+
+_DELETED_BODIES = {"[deleted]", "[removed]"}  # Reddit 原生删除态（作者/正文两栏的判定源）
+
+# subreddit 名域（字母数字下划线）：下限放宽到 2——校验过严拒掉真订阅的
+# 代价（加不上），比过松收进一个假名（页面校验会拦住）更高
+_NAME_RE = re.compile(r"^[A-Za-z0-9_]{2,21}$")
+
+# 站内地址里的 /r/<名>/ 段（起点或前面是 / . = 才认，避免误吃普通词）
+_R_PATH_RE = re.compile(r"(?:^|[/=.])r/([A-Za-z0-9_]+)/?")
+
+# shreddit 开标签（自闭合形态不出现；\s 排除 shreddit-post-xxx 同前缀标签）
+_POST_TAG_RE = re.compile(r"<shreddit-post\s[^>]*>")
+_COMMENT_TAG_RE = re.compile(r"<shreddit-comment\s[^>]*>")
+_PARTIAL_TAG_RE = re.compile(r"<faceplate-partial\s[^>]*>")
+
+_SELF_TYPES = {"text", "self"}  # post-type -> kind 的两类映射（其余一律 link）
+_MEDIA_TYPES = {"image", "video", "gallery"}
+
+
+# ---- 列表 ----
+
+
+def _post_meta(a: dict[str, str], *, with_author: bool = False) -> str:
+    """帖子元信息列「N 点 · N 评 · r/版块（· u/作者）」：列表与详情共用。"""
+    parts = [
+        t("words.points", n=fmt_count(safe_int(a.get('score')))),
+        t("words.comments_short", n=fmt_count(safe_int(a.get('comment-count')))),
+    ]
+    if subreddit := str(a.get("subreddit-name") or ""):
+        parts.append(f"r/{subreddit}")
+    if with_author and (author := str(a.get("author") or "")):
+        parts.append(f"u/{author}")
+    return " · ".join(parts)
+
+
+def parse_posts_html(html: str) -> list[FeedItem]:
+    """页面/片段 HTML -> FeedItem 列表（保持文档序，广告与残条逐条防御跳过）。"""
+    items: list[FeedItem] = []
+    for m in _POST_TAG_RE.finditer(html):
+        a = tag_attrs(m.group(0))
+        pid = str(a.get("id") or "")
+        title = str(a.get("post-title") or "").strip()
+        if not pid.startswith("t3_") or not title:
+            continue  # 广告（无 t3 id）或残条：跳条不跳流
+        if "promoted" in str(a.get("class") or ""):
+            continue
+        subreddit = str(a.get("subreddit-name") or "")
+        permalink = str(a.get("permalink") or "")
+        items.append(
+            FeedItem(
+                source=SOURCE_ID,
+                id=pid[3:],
+                title=title,
+                url=urljoin(_SITE, permalink) if permalink else f"{_SITE}/comments/{pid[3:]}",
+                kind="self" if str(a.get("post-type") or "") in _SELF_TYPES else "link",
+                meta=_post_meta(a),
+                extra={"subreddit": subreddit},
+            )
+        )
+    return items
+
+
+def parse_next_html(html: str) -> str | None:
+    """HTML -> 下一页 partial 的绝对 URL（faceplate-partial slot="load-after" 的 src）。
+
+    没有该元素 = 服务端说到底了。src 自带全参数（after/distance/sort/...），
+    直接整串跟走，不重新拼。
+    """
+    for m in _PARTIAL_TAG_RE.finditer(html):
+        a = tag_attrs(m.group(0))
+        if a.get("slot") == "load-after" and a.get("src"):
+            return urljoin(_SITE, a["src"])
+    return None
+
+
+# ---- 帖子与评论树 ----
+
+
+@dataclass
+class ThreadDetail:
+    """帖子 permalink 页的解析结果：帖子本体 + 全部楼层（含各自的回复树）。"""
+
+    title: str
+    meta: str
+    time: str
+    description_md: str
+    floors: list[Floor] = field(default_factory=list)
+
+
+@dataclass
+class _CNode:
+    """评论树的工作节点：属性 + 正文 + 子节点（depth 属性重建嵌套）。"""
+
+    attrs: dict[str, str]
+    body: str
+    children: list[_CNode] = field(default_factory=list)
+
+    @property
+    def author(self) -> str:
+        a = str(self.attrs.get("author") or "")
+        return a if a and a not in _DELETED_BODIES else deleted_author()
+
+    @property
+    def votes(self) -> str:
+        return votes_text(safe_int(self.attrs.get("score")))
+
+
+_DIV_TOKEN_RE = re.compile(r"<div\b|</div>")
+
+
+def _slot_inner(segment: str, slot: str) -> str:
+    """segment 里第一个 slot=<slot> 的 div 的内层 HTML（按 div 配平找闭合）。
+
+    shreddit 的正文容器是 slot="comment" / slot="text-body" 的 div，内层
+    是结构化 HTML（rtjson 产物）；嵌套 div 靠配平而不是非贪婪匹配。
+    """
+    m = re.search(rf'<div[^>]*slot="{slot}"[^>]*>', segment)
+    if not m:
+        return ""
+    depth = 1
+    for tok in _DIV_TOKEN_RE.finditer(segment, m.end()):
+        depth += 1 if tok.group(0) == "<div" else -1
+        if depth == 0:
+            return segment[m.end() : tok.start()]
+    return ""
+
+
+def _content(node: _CNode) -> str:
+    """一条评论的正文：删除占位的兜底（@ 前缀由 core.tree 统一拼装）。"""
+    return node.body or deleted_body()
+
+
+def _comment_of(node: _CNode) -> Comment:
+    return Comment(
+        author=node.author,
+        votes=node.votes,
+        content_md=_content(node),
+        time=fmt_iso(str(node.attrs.get("created") or "") or None),
+        raw_id=str(node.attrs.get("thingid") or "").removeprefix("t1_"),
+    )
+
+
+def _keep(node: _CNode) -> bool:
+    """空壳节点（被删且无回复的评论）整支跳过（规则见 core.tree）。"""
+    return bool(node.body or node.children)
+
+
+def _kids_of(node: _CNode) -> list[_CNode]:
+    return node.children
+
+
+def _author_of(node: _CNode) -> str:
+    return node.author
+
+
+# 差异注入：Reddit 的树是 HTML 按 depth 重建的 _CNode（拍平与 @ 规则在 core.tree）
+_ACC = TreeAccessors(keep=_keep, kids_of=_kids_of, author_of=_author_of, comment_of=_comment_of)
+
+
+def _answer_of(node: _CNode, n: int) -> Answer:
+    """楼层本体（core.tree.build_floors 注入）：字段来源是站差异，n 为回复数。"""
+    cp = str(node.attrs.get("permalink") or "")
+    return Answer(
+        author=node.author,
+        votes=node.votes,
+        content_md=_content(node),
+        time=fmt_iso(str(node.attrs.get("created") or "") or None),
+        url=urljoin(_SITE, cp) if cp.startswith("/") else "",
+        comment_count=t("display.replies_n", n=n) if n else "",  # 0 条不引导 Enter
+    )
+
+
+def _post_body(attrs: dict[str, str], html: str) -> str:
+    """帖子正文：自述帖 HTML 转 markdown；媒体帖记号直达原物；链接帖一行原文。"""
+    ptype = str(attrs.get("post-type") or "")
+    if ptype in _SELF_TYPES:
+        md = html_to_md(_slot_inner(html, "text-body"))
+        return md or t("words.no_body")
+    href = str(attrs.get("content-href") or "")
+    if ptype in _MEDIA_TYPES:
+        label = {
+            "image": t("media.image"), "video": t("media.video"),
+            "gallery": t("media.gallery"),
+        }.get(ptype, t("media.generic"))
+        target = (
+            urljoin(_SITE, href)
+            if href
+            else urljoin(_SITE, str(attrs.get("permalink") or ""))
+        )
+        return mark(label, target) if target else ""
+    return mark(t("words.original"), urljoin(_SITE, href)) if href else ""
+
+
+def parse_thread_html(html: str, fallback_title: str = "") -> ThreadDetail:
+    """帖子 permalink 页 HTML -> ThreadDetail（野数据防御；评论缺失给空楼层）。"""
+    post: dict[str, str] = {}
+    m = _POST_TAG_RE.search(html)
+    if m:
+        post = tag_attrs(m.group(0))
+
+    # 评论树：开标签按文档序拿属性与正文，depth 属性重建嵌套
+    roots: list[_CNode] = []
+    stack: list[tuple[int, list[_CNode]]] = []
+    tags = list(_COMMENT_TAG_RE.finditer(html))
+    for i, tag in enumerate(tags):
+        # 末条评论的正文区上界：200KB 足够容纳一条评论的 rtjson（再大只会
+        # 白扫），配平逻辑保证越界内容也只是被丢弃而不是误吞
+        end = tags[i + 1].start() if i + 1 < len(tags) else min(tag.end() + 200_000, len(html))
+        node = _CNode(
+            attrs=tag_attrs(tag.group(0)),
+            body=html_to_md(_slot_inner(html[tag.end() : end], "comment")),
+        )
+        depth = max(0, safe_int(node.attrs.get("depth")))
+        while stack and stack[-1][0] >= depth:
+            stack.pop()
+        (stack[-1][1] if stack else roots).append(node)
+        stack.append((depth, node.children))
+
+    # 顶层节点 -> 楼层（keep 过滤 / 计数 / 拍平的骨架在 core.tree.build_floors）
+    floors = build_floors(roots, _ACC, answer_of=_answer_of)
+    # 截断口：服务端只渲染了前一部分楼层（大帖常见），按 comment-count 诚实提示
+    total = safe_int(post.get("comment-count"))
+    loaded = sum(1 + len(f.comments) + sum(len(c.replies) for c in f.comments) for f in floors)
+    if floors and total > loaded:
+        last = floors[-1].answer
+        last.comment_count = " · ".join(
+            x
+            for x in (
+                last.comment_count,
+                t("words.more_unexpanded", n=fmt_count(total - loaded)),
+            )
+            if x
+        )
+    return ThreadDetail(
+        title=str(post.get("post-title") or "").strip() or fallback_title,
+        meta=_post_meta(post, with_author=True),
+        time=fmt_iso(str(post.get("created-timestamp") or "") or None),
+        description_md=_post_body(post, html),
+        floors=floors,
+    )
+
+
+# ---- 订阅校验 ----
+
+
+def parse_subreddit_page(html: str) -> str | None:
+    """版块页 HTML -> subreddit 名（校验存在性用）；不存在（壳页）回 None。
+
+    subreddit-name 首次出现可能在 400KB+ 深处（页首是大量 head/CSS），
+    全量搜索——600KB 级页面的单次正则扫描代价可忽略。
+    """
+    m = re.search(r'subreddit-name="([A-Za-z0-9_]+)"', html)
+    if m:
+        return m.group(1)
+    m = re.search(r'subreddit-prefixed-name="r/([A-Za-z0-9_]+)"', html)
+    return m.group(1) if m else None
+
+
+# ---- 订阅输入归一 ----
+
+
+def parse_subreddit_input(text: str) -> str:
+    """四形态归一成裸 subreddit 名（小写）：rust / r/rust / /r/rust/ / 站点地址。
+
+    认不出回空串（调用方给「没认出」反馈，不在这里猜）。
+    """
+    s = (text or "").strip()
+    if not s:
+        return ""
+    if m := _R_PATH_RE.search(s):
+        return m.group(1).lower()
+    s = s.rstrip("/")
+    return s.lower() if _NAME_RE.match(s) else ""

feedscope/sources/rss/__init__.py

@@ -0,0 +1,64 @@
+"""RSS 源（rss）：通用订阅聚合——「全部」合并时间线 + 每订阅一个信息流。
+
+包内分层（全项目统一的源模板）：
+- fetch.py  取数层：httpx 条件请求（ETag/Last-Modified）+ 聚合流的并发编排
+- parse.py  解析层：feedparser -> FeedItem / 详情 markdown，纯函数可测
+- __init__.py 编排层：Source 能力声明与 open_* 分派（订阅型骨架走
+  core.SubscribedSource，本文件只剩 RSS 的差异）
+
+与 zhihu/x 的本质差异：feeds 不是代码写死的内置流，而是用户在 sources.toml
+[rss.feeds] 里的订阅表（数据驱动的加法合成）；无登录、无评论层；详情读
+feed 自带正文（content 优先、summary 兜底），摘要型源正文短，Ctrl+O 跳浏
+览器补全。
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from feedscope.core.config import Subscription
+from feedscope.core.media import html_to_md
+from feedscope.core.models import FeedItem
+from feedscope.core.registry import register
+from feedscope.core.source import FeedLoader, SubscribedSource
+from feedscope.core.timefmt import fmt_unix
+from feedscope.sources.rss.fetch import fetch_body, fetch_merged
+from feedscope.sources.rss.parse import SOURCE_ID, parse_feed
+
+
+@register
+class RssSource(SubscribedSource):
+    source_id = SOURCE_ID
+    label = "RSS"
+    supports_detail = True
+    subscribable = True  # feeds 来自用户订阅：F2 里 → 进订阅管理屏
+    detail_kinds = frozenset({""})  # 全部条目（kind 空）Enter 都进终端详情
+    detail_unit_label = "units.body"  # 无楼层，详情屏尾行与 probe 用这个词
+
+    all_feed: ClassVar[str] = "all"  # 聚合流名（「全部」），feeds 首位
+    sub_noun: ClassVar[str] = "units.subscription"
+    reserved_feed_keys = (all_feed,)
+    _meta_extra_key = "feed_label"  # 详情元信息首段 = 订阅显示名
+
+    async def _fetch_merged(
+        self, feeds: list[Subscription]
+    ) -> tuple[list[FeedItem], list[str]]:
+        return await fetch_merged(feeds)
+
+    async def _open_one(self, feed: Subscription) -> FeedLoader:
+        items = parse_feed(
+            await fetch_body(feed),
+            feed_key=feed.key,
+            feed_label=feed.label,
+            all_view=False,
+            fallback_url=feed.url,
+        )
+        # 0 条 = 大概率源坏了（改版/地址失效），切片出口统一报；单个
+        # feed 也可能几百条，切片上屏防一次性挂载冻结
+        return self.sliced_feed(items, feed.label)
+
+    def _detail_time(self, extra: dict[str, Any]) -> str:
+        return fmt_unix(extra.get("published") or None)
+
+    def _detail_body(self, extra: dict[str, Any]) -> str:
+        return html_to_md(str(extra.get("content_html") or ""))

feedscope/sources/rss/fetch.py

@@ -0,0 +1,94 @@
+"""取数层：订阅抓取（httpx 条件请求）+「全部」聚合流（共享编排）。
+
+- 条件请求（ETag / Last-Modified）：模块级缓存按 URL 记验证器与上次响应体，
+  304 直接回放缓存正文——F5 反复刷新对源友好，也省流量。缓存只在进程内：
+  重启后第一次仍是无条件 GET，语义最简单也够用（阅读器不是离线仓库）。
+- 聚合编排（并发/失败隔离/倒序合并）见 core.source.merge_feeds；RSS 的差异
+  是聚合视图解析、跨订阅 URL 去重、按发布时间（unix 秒）倒序。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from feedscope.core import http
+from feedscope.core.config import Subscription
+from feedscope.core.models import FeedItem
+from feedscope.core.source import SourceError, merge_feeds
+from feedscope.core.i18n import t
+from feedscope.sources.rss.parse import parse_feed
+
+# RSS 专用 Accept：部分源对浏览器 UA + */* 的组合反而回 HTML 页，声明清楚要 feed
+_ACCEPT = (
+    "application/rss+xml, application/atom+xml, application/feed+json, "
+    "application/xml, text/xml, */*"
+)
+
+
+@dataclass
+class _CondEntry:
+    """一个订阅的条件请求缓存（验证器 + 上次响应体）。"""
+
+    etag: str | None
+    last_modified: str | None
+    body: bytes
+
+
+_CACHE: dict[str, _CondEntry] = {}
+
+
+def _conditional_headers(cached: _CondEntry | None) -> dict[str, str]:
+    headers = {"Accept": _ACCEPT}
+    if cached is not None:
+        if cached.etag:
+            headers["If-None-Match"] = cached.etag
+        if cached.last_modified:
+            headers["If-Modified-Since"] = cached.last_modified
+    return headers
+
+
+async def fetch_body(feed: Subscription) -> bytes:
+    """抓一个订阅的 XML 字节；304 回放缓存体，200 记验证器并更新缓存。"""
+    cached = _CACHE.get(feed.url)
+    r = await http.get(
+        feed.url,
+        source=t("sources.rss.with_label", label=feed.label),
+        headers=_conditional_headers(cached),
+        allow_304=True,
+    )
+    if r.status_code == 304:
+        if cached is not None:
+            return cached.body
+        # 无缓存却 304（服务器不合规）：去掉条件头再来一次，还 304 才是真没辙
+        r = await http.get(
+            feed.url,
+            source=t("sources.rss.with_label", label=feed.label),
+            headers={"Accept": _ACCEPT},
+        )
+        if r.status_code == 304:
+            raise SourceError(t("errors.rss_304_no_cache", label=feed.label))
+    _CACHE[feed.url] = _CondEntry(
+        etag=r.headers.get("ETag"), last_modified=r.headers.get("Last-Modified"), body=r.content
+    )
+    return r.content
+
+
+async def fetch_merged(feeds: list[Subscription]) -> tuple[list[FeedItem], list[str]]:
+    """全部订阅并发拉取并聚合成一条时间线：(合并条目, 失败订阅的短消息列表)。
+
+    编排（并发/失败隔离/倒序合并）见 core.source.merge_feeds；RSS 的差异：
+    聚合视图解析（all_view，订阅名进元信息列）、跨订阅 URL 去重（同一 URL
+    多源覆盖只留书写顺序靠前的一份）、按发布时间（unix 秒）倒序。
+    """
+
+    async def one(feed: Subscription) -> list[FeedItem]:
+        body = await fetch_body(feed)
+        return parse_feed(body, feed_key=feed.key, feed_label=feed.label, all_view=True)
+
+    return await merge_feeds(
+        feeds,
+        one,
+        error_label=lambda f: f.label,
+        sort_key=lambda it: float(it.extra.get("published") or 0.0),
+        dedup_urls=True,
+    )

feedscope/sources/rss/parse.py

@@ -0,0 +1,116 @@
+"""解析层：feedparser 结果 -> FeedItem / 详情 markdown，纯函数不碰网络。
+
+RSS/Atom 野源格式千奇百怪，容错原则「能救则救、救不了就丢条不丢流」：
+标题带 HTML、缺 author、缺发布时间都只是字段级缺失；guid 与 link 双缺才
+整条跳过（无法寻址，进详情 / 跳浏览器都没有落点）。
+"""
+
+from __future__ import annotations
+
+import calendar
+import html as html_mod
+import re
+from time import struct_time
+from urllib.parse import urljoin
+
+import feedparser
+
+from feedscope.core.models import FeedItem
+from feedscope.core.i18n import t
+from feedscope.core.text import strip_zwsp
+
+SOURCE_ID = "rss"
+
+# 标题/作者里的残余标签（<b>标题</b>、署名 <a> 之类），清理成纯文本
+_TAGS = re.compile(r"<[^>]*>")
+# 首页 HTML 里的 <link> 声明（自动发现 feed 用）
+_LINK_TAG = re.compile(r"<link\b[^>]*>", re.IGNORECASE)
+_HREF = re.compile(r"""href=(["'])(.*?)\1""", re.IGNORECASE)
+_FEED_TYPES = ("rss+xml", "atom+xml", "feed+json", "feed+xml")
+
+
+def _clean(text: object) -> str:
+    """字段级清洗：去标签、还原实体、去零宽；None / 非 str 回空串。"""
+    if not isinstance(text, str):
+        return ""
+    return strip_zwsp(html_mod.unescape(_TAGS.sub("", text)))
+
+
+def _epoch(st: object) -> float:
+    """feedparser 的 *_parsed（struct_time，UTC）-> unix 秒；缺省 0（排序沉底）。"""
+    return float(calendar.timegm(st)) if isinstance(st, struct_time) and st.tm_year > 1 else 0.0
+
+
+def _content_html(entry: dict) -> str:
+    """正文 HTML：优先 content（多为全文），退 summary（多为摘要）。"""
+    content = entry.get("content")
+    if isinstance(content, list) and content:
+        first = content[0]
+        if isinstance(first, dict) and isinstance(first.get("value"), str):
+            return first["value"]
+    summary = entry.get("summary")
+    return summary if isinstance(summary, str) else ""
+
+
+def probe(body: bytes | str) -> tuple[str, int]:
+    """(feed 自述标题, 条目数)：订阅管理判断「这是不是 feed」与取默认显示名。"""
+    parsed = feedparser.parse(body)
+    title = _clean(parsed.feed.get("title")) if getattr(parsed, "feed", None) else ""
+    return title, len(parsed.entries)
+
+
+def discover_feed_link(html: str, base_url: str) -> str:
+    """首页 HTML -> feed 地址：<link rel="alternate" type="…rss/atom…">，
+    相对 href 以 base_url 绝对化；找不到回空串。"""
+    for tag in _LINK_TAG.findall(html):
+        low = tag.lower()
+        if "alternate" not in low or not any(t in low for t in _FEED_TYPES):
+            continue
+        m = _HREF.search(tag)
+        if m and m.group(2):
+            return urljoin(base_url, m.group(2))
+    return ""
+
+
+def parse_feed(
+    body: bytes | str,
+    *,
+    feed_key: str,
+    feed_label: str,
+    all_view: bool,
+    fallback_url: str = "",
+) -> list[FeedItem]:
+    """一个订阅的 XML -> FeedItem 列表（保持源内顺序，通常已是倒序）。
+
+    all_view 决定元信息列内容：聚合「全部」里必须能认出条目来自哪个订阅
+    （订阅名打头），单订阅视图里订阅名是噪音、只留作者。extra 带 detail
+    所需的全部字段（feed 自带正文，进详情不重新抓）。
+    """
+    parsed = feedparser.parse(body)
+    items: list[FeedItem] = []
+    for entry in parsed.entries:
+        link = entry.get("link") or fallback_url
+        guid = entry.get("id")
+        if not guid and not link:
+            continue  # 双缺无法寻址
+        author = _clean(entry.get("author"))
+        meta_parts = ([feed_label] if all_view else []) + ([author] if author else [])
+        items.append(
+            FeedItem(
+                source=SOURCE_ID,
+                id=f"{feed_key}/{guid or link}",
+                title=_clean(entry.get("title")) or t("words.no_title"),
+                url=link,
+                meta=" · ".join(meta_parts),
+                extra={
+                    "feed_key": feed_key,
+                    "feed_label": feed_label,
+                    "author": author,
+                    "published": _epoch(
+                        entry.get("published_parsed") or entry.get("updated_parsed")
+                    ),
+                    "content_html": _content_html(entry),
+                },
+            )
+        )
+    return items

feedscope/sources/telegram/__init__.py

@@ -0,0 +1,61 @@
+"""Telegram 频道源（telegram）：纯订阅聚合——「全部」合并时间线 + 每频道一流。
+
+包内分层（全项目统一的源模板）：
+- fetch.py  取数层：t.me/s 预览页（免登录 SSR HTML）+ 聚合流的并发编排
+- parse.py  解析层：预览 HTML -> FeedItem / 正文 markdown，纯函数可测
+- __init__.py 编排层：Source 能力声明与 open_* 分派（订阅型骨架走
+  core.SubscribedSource，本文件只剩 Telegram 的差异）
+
+与 RSS 完全同形（代码级近亲）：feeds 来自 [telegram.feeds] 订阅表（加法
+合成），无登录、无评论层；详情读列表自带正文（extra 透传），进详情零请求，
+摘要外没有的部分 Ctrl+O 跳浏览器。频道帖的正文是行内 HTML，走 html_to_md
+共用管线；图片/视频换 [图片]/[视频] 记号。翻页走 ?before= 游标（单频道流）；
+「全部」聚合流一次并发拉全、内存切片上屏（SliceFeedLoader）。
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from feedscope.core.config import Subscription
+from feedscope.core.i18n import t
+from feedscope.core.models import FeedItem
+from feedscope.core.registry import register
+from feedscope.core.source import FeedLoader, SourceError, SubscribedSource
+from feedscope.sources.telegram.fetch import TelegramFeedLoader, fetch_merged
+from feedscope.sources.telegram.parse import SOURCE_ID, display_time
+
+
+@register
+class TelegramSource(SubscribedSource):
+    source_id = SOURCE_ID
+    label = "Telegram"
+    supports_detail = True
+    subscribable = True  # feeds 来自用户订阅：F2 里 → 进订阅管理屏
+    supports_comments = False  # 频道无评论层（讨论组在另一维度，预览页拿不到）
+    detail_kinds = frozenset({""})  # 全部条目（kind 空）Enter 都进终端详情
+    detail_unit_label = "units.body"  # 无楼层，详情屏尾行与 probe 用这个词（同 RSS）
+
+    all_feed: ClassVar[str] = "all"  # 聚合流名（「全部」），保留字：订阅 key 与它同名会遮住聚合流
+    sub_noun: ClassVar[str] = "units.channel"
+    reserved_feed_keys = (all_feed,)
+    _meta_extra_key = "channel"  # 详情元信息首段 = 频道名
+
+    async def _fetch_merged(
+        self, feeds: list[Subscription]
+    ) -> tuple[list[FeedItem], list[str]]:
+        return await fetch_merged(feeds)
+
+    async def _open_one(self, feed: Subscription) -> FeedLoader:
+        loader = TelegramFeedLoader(feed.key, feed.label)
+        await loader.load_more()  # 首批
+        # 0 条大概率是频道不存在/为空/关闭了 Web 预览，不是站点改版——给专属指引
+        if not loader.items:
+            raise SourceError(t("errors.telegram_no_items", key=feed.key))
+        return loader
+
+    def _detail_time(self, extra: dict[str, Any]) -> str:
+        return display_time(str(extra.get("published") or ""))
+
+    def _detail_body(self, extra: dict[str, Any]) -> str:
+        return str(extra.get("content_md") or "")