feedscope 0.1.0__py3-none-any.whl

feedscope/sources/zhihu/fetch.py

@@ -0,0 +1,402 @@
+"""知乎取数层：信息流走免签 API（常驻页签的页面 fetch，统一原语见
+core/browser.ChannelTab.fetch），详情纯 API。
+
+热榜/推荐/关注 2026-11 实测都有免签接口（只认 cookie，推荐/关注就是页面
+自己在调的），请求由常驻 zhihu.com 通道页签的 fetch 发出——真 Chrome 的
+TLS/自动头/cookie 与浏览器会话完全自洽（风控一致性优先，比 httpx 直调
+安全）。回答翻页走 feeds API、评论走 comment_v5（同通道 fetch）。浏览器
+页签约定：长活页签由 Loader 持有，close() 幂等关闭。raw dict / JSON ->
+模型在 parse.py，编排在包 __init__。
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from feedscope.core.browser import ChannelTab
+from feedscope.core.models import Answer, Comment, DetailDoc, FeedItem
+from feedscope.core.i18n import raw, t
+from feedscope.core.source import (
+    CommentLoader,
+    DetailLoader,
+    FeedLoader,
+    LoginRequired,
+    SourceError,
+    dedup_append,
+    dedup_by,
+)
+from feedscope.sources.zhihu.parse import (
+    _api_comments,
+    _api_question_doc,
+    _feed_api_item,
+    _feeds_answers,
+    _hot_api_items,
+)
+
+# ---- 页面上下文 fetch（通道页签里执行的 JS：API 请求由真 Chrome 发出）----
+# 不模拟点按钮/开浮层/滚屏：DOM 交互无法完整触发分页（2026-11 实测触底
+# 不发分页请求），API 有标准游标分页（paging.next），同源 fetch 带 cookie。
+# x-zse-93 是客户端版本声明（静态常量、页面每个 API 请求都带），但按端点
+# 区别对待（2026-11 实测矩阵）：v4/questions 元信息端点必须带（否则 403
+# 版本门禁 code 10003）；其余端点带上无害；唯独 feeds 无 cursor 入口反而
+# 拒绝它——故按调用方显式传入，不全局统一。x-zse-96 签名一律不需要。
+_X_ZSE_93 = "101_3_3.0"  # 知乎客户端版本声明（静态常量；三处使用：_headers 与两条复合 JS）
+
+# 「N 条评论」= 根评论 + 子回复总数：root_comment 只带每根的热门子回复
+# （1-2 条），其余靠 comment/{id}/child_comment 游标分页补全。
+_CM_FIRST_URL = "https://www.zhihu.com/api/v4/comment_v5/answers/{aid}/root_comment?order_by=score&limit=20&offset="
+
+# 子回复补全（一条根评论一串游标翻页，根与根之间 Promise.all 并发——
+# 串行 fetch 时热门楼层几十条子回复能把首页拖到 20s+）。offset 为空 =
+# 从头拉（与 root 首页同语义）；seen 过滤已带出的热门子回复防重复。
+_COMPLETE_CHILDREN_JS = """
+async (roots) => {
+  const out = {};
+  await Promise.all(roots.map(async (r) => {
+    const seen = new Set(r.seen || []);
+    const kids = [];
+    let url = `https://www.zhihu.com/api/v4/comment_v5/comment/${r.id}/child_comment?limit=50&offset=${r.offset}`;
+    for (let i = 0; i < 6; i++) {  // limit=50 一页基本到底；留翻页余地
+      try {
+        const resp = await fetch(url, {
+          headers: { "x-requested-with": "fetch", "x-zse-93": "__ZSE__" },
+          credentials: "include",
+        });
+        if (!resp.ok) break;
+        const d = await resp.json();
+        kids.push(...(d.data || []).filter((k) => !k.is_delete && !seen.has(String(k.id))));
+        url = d.paging && d.paging.next;
+        if (!url || d.paging.is_end) break;
+      } catch (e) { break; }
+    }
+    out[r.id] = kids;
+  }));
+  return out;
+}
+""".replace("__ZSE__", _X_ZSE_93)
+
+
+def _raise_compound_error(data: Any) -> None:
+    """复合脚本（一次 evaluate 多请求）的返回自检：__status/__error 键转 SourceError。
+
+    单请求已走 ChannelTab.fetch 的统一解包；这里只剩 _OPEN_QUESTION_JS 的
+    嵌套形态（{meta: {...}, feeds: {...}}，各自的 __status 分开查）。
+    """
+    if not isinstance(data, dict):
+        raise SourceError(t("errors.zhihu_api_bad_data", kind=type(data).__name__))
+    if status := data.get("__status"):
+        raise SourceError(t("errors.zhihu_api_status", status=status))
+    if err := data.get("__error"):
+        raise SourceError(t("errors.zhihu_api_failed", error=err))
+
+
+def _headers(zse93: bool) -> dict[str, str]:
+    """知乎 API 的手动头（浏览器不会自动带的）：x-zse-93 按端点区别对待，见上注释。"""
+    h = {"x-requested-with": "fetch"}
+    if zse93:
+        h["x-zse-93"] = _X_ZSE_93
+    return h
+
+
+async def _fetch_json(url: str, referrer: str | None = None, zse93: bool = False) -> dict:
+    """通道页签里 fetch JSON API -> JSON body（dict）；网络/结构失败转 SourceError。
+
+    取数原语与解包约定见 ChannelTab.fetch（知乎/Reddit/X 三源共用）。referrer
+    不传 = 页签自然 referer（评论用：通道页 URL）；信息流传对应页面 URL，
+    与页面请求同形。401/403 的语义转译归 _api_json/调用方。
+    """
+    status, body = await _tab.fetch(
+        url, source=t("sources.zhihu.label"), headers=_headers(zse93), referrer=referrer
+    )
+    if status:
+        raise SourceError(t("errors.zhihu_api_status", status=status))
+    # 顶层不是 JSON 对象（登录墙 HTML 等）由 ChannelTab.fetch 统一报结构异常
+    return body or {}
+
+
+async def _comment_page(url: str) -> tuple[list[Comment], str, bool]:
+    """拉一页根评论（先把带隐藏子回复的根并发补全）；返回 (评论, next_url, is_end)。
+
+    「还有没有子评论可拉」没有现成标识（2026-11 实测）：can_unfold 在
+    root_comment 列表响应里恒 False（不是这个语义）；child_comment_next_offset
+    只在「已带出>=1 条且后面还有」时给值，覆盖不了「一条没带但 count>0」
+    的形态——缺口只能用 child_comment_count - len(child_comments) 算，
+    这两个字段是服务端维护的准确记录。
+
+    无缺口（count<=带出数：无子评论/子评论已全带出）不发请求，有缺口
+    就拉全（并发下一次请求，留着「另有 1 条回复」的尾巴比多花一次请求
+    更伤阅读）；补全失败（限流/风控）时静默保留接口已带出的热门子回复。
+    """
+    data = await _fetch_json(url)
+
+    def _gap(r: dict) -> int:
+        if r.get("is_delete"):
+            return 0
+        return (r.get("child_comment_count") or 0) - len(r.get("child_comments") or [])
+
+    pending = [
+        {
+            "id": r.get("id"),
+            "offset": r.get("child_comment_next_offset") or "",  # 空 = 从头拉
+            "seen": [str(k.get("id")) for k in r.get("child_comments") or []],
+        }
+        for r in data.get("data") or []
+        if _gap(r) >= 1
+    ]
+    if pending:
+        try:
+            filled: dict = await _tab.eval(_COMPLETE_CHILDREN_JS, pending) or {}
+            for r in data.get("data") or []:
+                kids = filled.get(str(r.get("id"))) or filled.get(r.get("id"))
+                if kids:
+                    r.setdefault("child_comments", []).extend(kids)
+        except Exception:
+            pass  # 补全失败：热门子集兜底
+    paging = data.get("paging") or {}
+    return _api_comments(data), paging.get("next") or "", bool(paging.get("is_end"))
+
+
+# ---- 信息流 API（热榜/推荐/关注：v3 免签接口，只认 cookie）----
+# 2026-11 实测：这几个接口不查 x-zse-96 签名（那是 v4 的要求），页面自己
+# 首请求打的正是推荐/关注这两个 URL（limit=10&desktop=true 逐字相同），
+# 有 paging.next 游标。热榜页是 SSR 不发列表请求——全部流量统一走 www 网关
+# （api.zhihu.com/topstory/hot-list 是同一份数据的 App 域孪生门，已弃），
+# 30 条上限无翻页（limit 参数无效，www/api.zhihu.com 两门实测等价）。热榜
+# 元信息列放 detail_text 热度——提问人拿不到（DOM 无作者节点，API 的
+# author 也是 id=0 占位），维持「放热度不放人名」的形态。
+HOT_API = "https://www.zhihu.com/api/v3/feed/topstory/hot-lists/total?limit=50"
+RECOMMEND_API = "https://www.zhihu.com/api/v3/feed/topstory/recommend?limit=10&desktop=true"
+FOLLOW_API = "https://www.zhihu.com/api/v3/moments?limit=10&desktop=true"
+
+# 各流的 referer = 页面自己发该请求时所在页面（fetch 的 referrer 选项指定）。
+_CHANNEL_URL = "https://www.zhihu.com/"  # 通道页签停在 www 源上（cookie/CORS 的前提）
+
+
+def _answer_count_pattern() -> str:
+    """meta 里回读回答总数的正则：由 meta.zhihu_n_answers 模板生成（占位符
+    换捕获组），与 parse 层写入同键同语言，回读永远对得上。"""
+    return re.escape(raw("words.zhihu_n_answers")).replace(re.escape("{n}"), r"(\d+)")
+
+
+async def _login_wall(page: Any) -> None:
+    """通道页签开页校验：goto 后确认没撞上登录墙（2026 起热榜也在墙后）。"""
+    if "signin" in page.url:
+        raise LoginRequired(t("errors.zhihu_login_wall", label=t("sources.zhihu.label")))
+
+
+_tab = ChannelTab(
+    _CHANNEL_URL, check=_login_wall, name="zhihu"
+)  # 单例/重建/在途跳转重试见 core.browser
+
+
+async def _api_json(url: str, referer: str, zse93: bool = False) -> dict:
+    """API 一次通道页签 fetch -> JSON；401 = 会话过期转 LoginRequired（403 可能是风控，不并入）。"""
+    try:
+        return await _fetch_json(url, referrer=referer, zse93=zse93)
+    except SourceError as exc:
+        if "HTTP 401" in str(exc):
+            raise LoginRequired(
+                t("errors.zhihu_session_expired", label=t("sources.zhihu.label"))
+            ) from exc
+        raise
+
+
+async def fetch_hot_list(referer: str) -> list[FeedItem]:
+    """热榜一次 API 调用拿全量（30 条上限，无翻页）。"""
+    return _hot_api_items(await _api_json(HOT_API, referer))
+
+
+# ---- 问题详情（纯 API，全程不加载页面）----
+# 元信息：v4/questions/{qid}（include 把 detail/author/answer_count 等全带出，
+# 2026-11 实测）。该端点的 403 是客户端版本门禁（err code 10003「请升级
+# 客户端」），不是签名门禁：带 x-zse-93（_X_ZSE_93 静态常量，页面每个
+# API 请求都带，已在 _headers / 复合 JS 统一注入）即放行，x-zse-96 不需要。
+# 回答：questions/{qid}/feeds 无 cursor 从头拉（与 SSR 首批一致，实测），
+# 之后一路 paging.next；include 是页面请求原文（勿手改，改版失效时重新
+# 抓包替换）。
+QUESTION_API = (
+    "https://www.zhihu.com/api/v4/questions/{qid}"
+    "?include=detail%2Cexcerpt%2Canswer_count%2Cfollower_count%2Cvisit_count%2Cauthor%2Ccreated"
+)
+# 回答：feeds 无 cursor 从头拉（与 SSR 首批一致，实测）。注意无 cursor 入口
+# 只吃这个精简 include 集——页面原文的完整 include 不带 cursor 会 403
+# （2026-11 实测）；翻页跟服务端 paging.next（自带全套参数），无需长串。
+_ANSWERS_FEEDS_TOP = (
+    "https://www.zhihu.com/api/v4/questions/{qid}/feeds"
+    "?include=data%5B%2A%5D.is_normal%2Ccomment_count%2Ccan_comment%2Ccontent%2Cvoteup_count%2C"
+    "comment_permission%2Ccreated_time%2Cupdated_time%2Cquestion%2Cexcerpt%3B"
+    "data%5B%2A%5D.author.follower_count%2Cvip_info"
+    "&limit=5&order=default&platform=desktop"
+)
+
+# 开题一次 evaluate 并行拉元信息 + 首批回答（两请求独立，串行白等一个 RTT）；
+# 版本头按端点契约：元信息带 x-zse-93（否则 403），feeds 无 cursor 入口不带（带了反而 403）
+_OPEN_QUESTION_JS = """
+async ([metaUrl, feedsUrl, referer]) => {
+  const go = async (u, with93) => {
+    try {
+      const headers = { "x-requested-with": "fetch" };
+      if (with93) headers["x-zse-93"] = "__ZSE__";
+      const r = await fetch(u, { headers, credentials: "include", referrer: referer });
+      if (!r.ok) return { __status: r.status };
+      return await r.json();
+    } catch (e) { return { __error: String(e) }; }
+  };
+  const [meta, feeds] = await Promise.all([go(metaUrl, true), go(feedsUrl, false)]);
+  return { meta, feeds };
+}
+""".replace("__ZSE__", _X_ZSE_93)
+
+
+# ---- 页面操作 ----
+
+
+async def open_question(qid: str) -> DetailLoader:
+    """问题详情纯 API：元信息 questions API + 首批回答 feeds 无 cursor 从头拉。
+
+    全程不加载问题页面——通道页签发两个请求即得（提问人/描述/计数 + 完整
+    内容的前 5 条回答），之后 load_more 沿 paging.next 翻。
+    """
+    referer = f"https://www.zhihu.com/question/{qid}"
+    args = [QUESTION_API.format(qid=qid), _ANSWERS_FEEDS_TOP.format(qid=qid), referer]
+    r = await _tab.eval(_OPEN_QUESTION_JS, args)  # 页签失效重建重试见 ChannelTab.eval
+    if not isinstance(r, dict) or "meta" not in r or "feeds" not in r:
+        raise SourceError(t("errors.zhihu_api_structure", label=t("sources.zhihu.label")))
+    try:
+        _raise_compound_error(r["meta"])
+    except SourceError as exc:
+        if "404" in str(exc):  # 元信息端点 404 = 问题本身没了，别让用户看 HTTP 码猜
+            raise SourceError(
+                t("errors.zhihu_question_gone", label=t("sources.zhihu.label"))
+            ) from exc
+        raise
+    _raise_compound_error(r["feeds"])
+    doc = _api_question_doc(r["meta"], _feeds_answers(r["feeds"], qid))
+    paging = r["feeds"].get("paging") or {}
+    return ZhihuQuestionLoader(doc, paging.get("next") or None, referer, qid)
+
+
+# ---- 增量 Loader（持活页签，close() 幂等）----
+
+
+class ZhihuApiFeedLoader(FeedLoader):
+    """游标分页 API 的信息流 Loader（推荐/关注）：请求走常驻通道页签。
+
+    不持有页签（通道是进程级单例，随会话生灭）；done 只在响应明示没有下一页
+    （is_end / next 空）时为真——拉空可能只是抖动，n 可再试；按 question id
+    去重与首批共用 dedup_append。
+    """
+
+    def __init__(self, first_url: str, referer: str) -> None:
+        self.items: list[FeedItem] = []
+        self._seen: set[str] = set()
+        self._next = first_url
+        self._referer = referer  # 与页面请求同形：按所在页面指定 referer
+        self._done = False
+
+    @property
+    def done(self) -> bool:
+        return self._done
+
+    async def load_more(self) -> list[FeedItem]:
+        if self._done or not self._next:
+            self._done = True
+            return []
+        data = await _api_json(self._next, self._referer)
+        paging = data.get("paging") or {}
+        self._next = paging.get("next") or ""
+        if not self._next or paging.get("is_end"):
+            self._done = True
+        return dedup_append(
+            self.items, self._seen, (_feed_api_item(r) for r in data.get("data") or [])
+        )
+
+
+class ZhihuQuestionLoader(DetailLoader):
+    """问题详情：纯 API（元信息 + 回答 feeds 游标翻页），不持有任何页签。
+
+    回答按 url 去重防排序抖动；done 由 is_end/无 next/总数（meta 里的
+    「N 个回答」）判定——拉空可能只是抖动，n 可再试。评论层共享通道页签。
+    """
+
+    def __init__(self, doc: DetailDoc, next_url: str | None, referer: str, qid: str) -> None:
+        self.doc = doc
+        self._next = next_url
+        self._referer = referer
+        self._qid = qid  # 翻页 URL 只带游标，回答里的 question 链接要本问题的 id
+        self._seen_urls = {a.url for a in doc.answers if a.url}
+        self._done = not next_url
+        m = re.search(_answer_count_pattern(), doc.meta or "")
+        self._total = int(m.group(1)) if m else None
+
+    @property
+    def done(self) -> bool:
+        return self._done
+
+    async def load_more(self) -> list[Answer]:
+        if self._done or self._next is None:
+            self._done = True
+            return []
+        data = await _api_json(self._next, self._referer)
+        # 回答按 url 去重防排序抖动（dedup_by：空 url 不去重直接放行）
+        new = dedup_by(_feeds_answers(data, self._qid), self._seen_urls, key=lambda a: a.url)
+        self.doc.answers.extend(new)  # 维持「doc = 已加载全部」的不变量
+        paging = data.get("paging") or {}
+        self._next = paging.get("next") or None
+        if (
+            not self._next
+            or paging.get("is_end")
+            or self._total is not None
+            and len(self.doc.answers) >= self._total
+        ):
+            self._done = True
+        return new
+
+    async def open_comments(self, index: int) -> ZhihuCommentsLoader:
+        """按需抓第 index 个回答的评论首页（进评论层才调，走通道页签）。"""
+        if not 0 <= index < len(self.doc.answers):
+            raise SourceError(t("errors.zhihu_answer_out_of_range", label=t("sources.zhihu.label")))
+        m = re.search(r"/answer/(\d+)", self.doc.answers[index].url or "")
+        if not m:
+            raise SourceError(t("errors.zhihu_answer_no_id", label=t("sources.zhihu.label")))
+        try:
+            comments, next_url, _ = await _comment_page(_CM_FIRST_URL.format(aid=m.group(1)))
+            return ZhihuCommentsLoader(comments, next_url)
+        except SourceError:
+            raise
+        except Exception as exc:  # 评论打不开不算灾难：给出口让 UI 提示
+            raise SourceError(
+                t("errors.zhihu_comments_failed", label=t("sources.zhihu.label"), error=exc)
+            ) from exc
+
+
+class ZhihuCommentsLoader(CommentLoader):
+    """单条回答的评论加载器：纯 comment_v5 API 游标翻页（root_comment 每页
+    limit=20 条 + 子回复补全），n 一路按到 is_end。不持有页签（通道现取）。
+    """
+
+    def __init__(self, comments: list[Comment], next_url: str) -> None:
+        self.comments = comments
+        self._next = next_url
+        self._ids = {c.raw_id for c in comments}
+        self._done = not next_url  # 没有下一页 = is_end
+
+    @property
+    def done(self) -> bool:
+        return self._done
+
+    async def load_more(self) -> list[Comment]:
+        if self._done or not self._next:
+            self._done = True
+            return []
+        try:
+            comments, next_url, is_end = await _comment_page(self._next)
+        except SourceError:
+            return []  # 单页失败不判死：可以再按 Ctrl+N 重试
+        new = dedup_by(comments, self._ids, key=lambda c: c.raw_id)
+        self.comments.extend(new)
+        self._next = next_url
+        if is_end or not next_url:
+            self._done = True
+        return new

feedscope/sources/zhihu/parse.py

@@ -0,0 +1,235 @@
+"""知乎解析层：DOM 提取结果 / API JSON / HTML -> 统一模型，纯函数，不碰网络与浏览器。
+
+本层只做「脏数据 -> FeedItem/Answer/markdown」的转换与清洗；取数在 fetch.py，
+编排在包 __init__。所有函数可直接用 fixture 测试。
+"""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import parse_qs, urlparse
+
+from feedscope.core.media import h2t as _h2t
+from feedscope.core.display import fmt_count, view_count_text, votes_text
+from feedscope.core.i18n import t
+from feedscope.core.media import VIDEO_RE, Tokens, attrs, mark, pick_url, video_url
+from feedscope.core.models import Answer, Comment, DetailDoc, FeedItem
+from feedscope.core.text import strip_zwsp
+from feedscope.core.timefmt import fmt_unix
+
+# html2text 统一配置见 core/const.py（不硬换行；img/video 进它之前已换成记号）
+# HTML2Text 实例经 media.h2t() 取（线程本地，见其 docstring），源内不自建
+
+_NOSCRIPT_RE = re.compile(r"<noscript>.*?</noscript>", re.IGNORECASE | re.DOTALL)
+# 表情贴纸（class="sticker"）不是内容图：换成 alt 文本（如 "[大哭]"），
+# 走 _IMG_RE 会变 [图片]+地址，那是看图不是看表情
+_STICKER_RE = re.compile(r'<img[^>]*class="[^"]*\bsticker\b[^"]*"[^>]*>', re.IGNORECASE)
+_ALT_RE = re.compile(r'alt="([^"]*)"')
+_IMG_RE = re.compile(r"<img[^>]*>", re.IGNORECASE)
+# img 地址按尺寸优先（2026-08 实测标记形态）：data-original 原图 > data-actualsrc
+# 显示图 > src（src 常是 data:image/svg+xml 懒加载占位，pick_url 会跳过 data:）。
+# 2026-11 实测 data-original 整 URL 属性已没了（只剩 data-original-token），多数落到 src
+_IMG_URL_ATTRS = ("data-original", "data-actualsrc", "src")
+# 视频卡（2026-11 实测）：content 里没有 <video> 标签，视频是 <a class="video-box">
+# 卡片——href 是 link.zhihu.com 跳板，data-lens-id 是视频页 id，内部包封面缩略图
+_VIDEO_BOX_RE = re.compile(r'<a\b[^>]*class="video-box"[^>]*>.*?</a>', re.IGNORECASE | re.DOTALL)
+# zhimg 的 /50/ 是缩略代理路径（同 hash 内容更小），剥掉直达显示图
+_ZHIMG_50_RE = re.compile(r"^(https://pic[\da-z]*\.zhimg\.com)/50/")
+
+
+def _upgrade_img_url(url: str) -> str:
+    """图片地址微升级：剥 /50/ 缩略代理（实测同 hash 直连内容更大）。
+
+    不猜原图尺寸：_r 原尺寸版 / 80/…_1440w 都只对部分 hash 存在（2026-11
+    实测多数 405），盲改写会产出死链；src 的 _720w 本就是网页显示图。
+    """
+    return _ZHIMG_50_RE.sub(r"\1/", url)
+
+
+def _video_box_md(block: str) -> str:
+    """video-box 卡片 -> [视频](视频页)。优先 data-lens-id 构造（跳板不参与，
+    最稳）；缺了才 decode href 跳板的 target 参数。封面缩略图随整卡吃掉。"""
+    m = re.match(r"<a\b[^>]*>", block)
+    a = attrs(m.group(0)) if m else {}
+    if lens := a.get("data-lens-id", ""):
+        return mark(t("media.video"), f"https://www.zhihu.com/video/{lens}")
+    href = a.get("href", "")
+    target = parse_qs(urlparse(href).query).get("target")
+    return mark(t("media.video"), target[0] if target else href)
+
+
+def _md(html: str) -> str:
+    """HTML -> markdown：图片/视频换 [图片]/[视频] 链接（TUI 显示不了媒体，
+    链接点击直达原图 / 视频页）、清零宽字符。"""
+    if not html:
+        return ""
+    html = _NOSCRIPT_RE.sub("", html)  # noscript 里是 img 的重复副本
+
+    def _sticker_text(m: re.Match[str]) -> str:
+        a = _ALT_RE.search(m.group(0))
+        return a.group(1) if a else ""
+
+    html = _STICKER_RE.sub(_sticker_text, html)  # 表情贴纸 -> "[大笑]" 文本
+    tok = Tokens()
+    html = _VIDEO_BOX_RE.sub(  # 先于 img：整卡吃掉，封面缩略图不单独出 [图片]
+        lambda m: tok.stash(_video_box_md(m.group(0))), html
+    )
+    html = _IMG_RE.sub(
+        lambda m: tok.stash(
+            mark(t("media.image"), _upgrade_img_url(pick_url(m.group(0), _IMG_URL_ATTRS)))
+        ),
+        html,
+    )
+    html = VIDEO_RE.sub(lambda m: tok.stash(mark(t("media.video"), video_url(m.group(0)))), html)
+    text = strip_zwsp(tok.expand(_h2t().handle(html)))
+    # 相邻同图合并（懒加载双标记会把同一张图渲染两次）；不同图各自保留。
+    # 链接形式 [图片](url) 整体比对；纯记号合并的 (?!\() 断言防止把带地址的
+    # [图片](…) 误吞成纯 [图片] 丢掉链接
+    img = re.escape(t("media.image"))  # 记号随语言：正则由当前文案生成，回读永远对得上
+    text = re.sub(rf"({img}\([^)]*\))(?:[ \t]*\1)+", r"\1", text)
+    return re.sub(rf"({img}(?!\())(?:[ \t]*{img}(?!\())+", r"\1", text)
+
+
+def _hot_api_items(data: dict) -> list[FeedItem]:
+    """热榜 API（www/api/v3/feed/topstory/hot-lists/total）响应 -> FeedItem 列表。
+
+    target.url 是 api.zhihu.com/questions/{id}（浏览器不可达的内部形态），
+    统一重写为 www 问题页；元信息列放 detail_text（「2606 万热度」），与
+    页面头部形态一致。接口上限 30 条且无翻页（limit 参数无效，2026-11 实测）。
+    注意：本接口的 target.id 是未加引号的大整数（超 JS 安全整数 2^53），
+    浏览器 r.json() 解析会丢精度（实测 …1699522 -> …1699500，进详情即 404）；
+    target.url 是字符串、精确——id 一律从 url 提取，id 字段仅作兜底。
+    """
+    out: list[FeedItem] = []
+    for r in data.get("data") or []:
+        tgt = r.get("target") or {}
+        m = re.search(r"/questions?/(\d+)", tgt.get("url") or "")
+        qid = m.group(1) if m else str(tgt.get("id") or "")
+        title = strip_zwsp(tgt.get("title") or "")
+        if tgt.get("type") != "question" or not qid or not title:
+            continue
+        out.append(
+            FeedItem(
+                source="zhihu",
+                id=f"question/{qid}",
+                title=title,
+                url=f"https://www.zhihu.com/question/{qid}",
+                kind="question",
+                meta=strip_zwsp(r.get("detail_text") or ""),
+            )
+        )
+    return out
+
+
+def _feed_api_item(r: dict) -> FeedItem | None:
+    """推荐/关注 feed API 条目 -> FeedItem；None = 丢弃。
+
+    只留能进终端详情的问题卡（详情只支持问题页，文章/想法/视频等不展示）：
+    - answer 卡（推荐 TOPIC_ACKNOWLEDGED_* / 关注 MEMBER_[VOTEUP_|ANSWER_]）：
+      标题取所属问题，作者取回答作者（与站方卡片展示的信息同源）
+    - question 卡（关注 MEMBER_ASK_QUESTION）：标题直接在 target 上
+    - 其余（feed_group 分组卡、文章/想法/视频/广告）不进列表
+    """
+    t = r.get("target") or {}
+    if t.get("type") == "answer":
+        q = t.get("question") or {}
+        qid, title = str(q.get("id") or ""), strip_zwsp(q.get("title") or "")
+        author = strip_zwsp((t.get("author") or {}).get("name") or "")
+    elif t.get("type") == "question":
+        qid, title = str(t.get("id") or ""), strip_zwsp(t.get("title") or "")
+        author = strip_zwsp((t.get("author") or {}).get("name") or "")
+    else:
+        return None
+    if not qid or not title:
+        return None
+    return FeedItem(
+        source="zhihu",
+        id=f"question/{qid}",
+        title=title,
+        url=f"https://www.zhihu.com/question/{qid}",
+        kind="question",
+        meta=author,  # 信息流元信息列放作者全名；列宽截断统一在 UI
+    )
+
+
+def _api_question_doc(q: dict, answers: list[Answer]) -> DetailDoc:
+    """问题元信息 API（v4/questions/{qid}?include=…，2026-11 实测）-> DetailDoc。
+
+    meta 行「提问人 提问 · N 个回答 · N 万浏览」对齐页面头部形态；时间裸
+    展示文本（与 X 详情同形，不带「提问于」前缀——各源元信息行/楼层头的
+    时间统一裸时间，词汇归 core/timefmt 一处）；描述 detail 是 HTML，走 _md。
+    """
+    asker = strip_zwsp((q.get("author") or {}).get("name") or t("words.anonymous"))
+    meta = t("words.zhihu_asked", asker=asker)
+    if n := q.get("answer_count"):
+        meta += t("words.zhihu_n_answers", n=n)
+    if visit := q.get("visit_count"):
+        meta += view_count_text(visit)  # 万浏览/浏览的分支拼写收在 core.display
+    created = q.get("created") or 0
+    return DetailDoc(
+        title=strip_zwsp(q.get("title") or ""),
+        meta=meta,
+        time=fmt_unix(created),
+        description_md=_md(q.get("detail") or ""),
+        answers=answers,
+    )
+
+
+def _api_comment(c: dict) -> Comment:
+    """comment_v5 JSON -> Comment（评论层数据全走 API，不碰 DOM）。"""
+    kids = c.get("child_comments") or []
+    likes = c.get("like_count") or 0
+    created = c.get("created_time") or 0
+    # root 接口 content 是纯文本，child 接口带 <p> 等 HTML：有标签才过 _md，
+    # 纯文本直用（_md 对纯文本可能做不必要的转义）
+    text = c.get("content") or ""
+    content_md = _md(text) if re.search(r"<[a-zA-Z]", text) else strip_zwsp(text)
+    return Comment(
+        author=strip_zwsp((c.get("author") or {}).get("name") or t("words.anonymous")),
+        votes=votes_text(likes),
+        content_md=content_md,
+        time=fmt_unix(created) if created else "",
+        replies=[_api_comment(r) for r in kids],
+        raw_id=str(c.get("id") or ""),
+    )
+
+
+def _api_comments(data: dict) -> list[Comment]:
+    """root_comment 一页 -> 顶层评论列表（删掉的/仅自己可见的不算数）。"""
+    roots = [
+        c
+        for c in data.get("data") or []
+        if not c.get("is_delete") and not c.get("is_visible_only_to_myself")
+    ]
+    return [_api_comment(c) for c in roots]
+
+
+def _feeds_answers(data: dict, qid: str) -> list[Answer]:
+    """回答 feeds API（questions/{qid}/feeds，2026-11 实测免签）一页 -> Answer 批次。
+
+    展示词汇全 app 统一（core/display 唯一出处，与 X 回复楼层同形）：
+    votes「赞 N」、time 裸北京时间、comment_count「N 条评论」；非 answer 卡
+    （罕见混入）跳过。
+    """
+    out: list[Answer] = []
+    for a in data.get("data") or []:
+        tgt = a.get("target") or {}
+        aid = str(tgt.get("id") or "")
+        if tgt.get("type") != "answer" or not aid:
+            continue
+        votes = tgt.get("voteup_count") or 0
+        cc = tgt.get("comment_count") or 0
+        created = tgt.get("created_time") or 0
+        out.append(
+            Answer(
+                author=strip_zwsp((tgt.get("author") or {}).get("name") or t("words.anonymous")),
+                votes=votes_text(votes),
+                content_md=_md(tgt.get("content") or ""),
+                time=fmt_unix(created),
+                url=f"https://www.zhihu.com/question/{qid}/answer/{aid}",
+                comment_count=t("display.comments_n", n=fmt_count(cc)) if cc else "",
+            )
+        )
+    return out
+
+