dsh-bili-scroll 2.0.4 → 2.2.0

package/vendor/bilibili-mcp/mcp_server.py

@@ -14,17 +14,23 @@ B站数据采集 MCP 服务，支持 OpenClaw / Claude Code / Cursor / Cline
 #      ③ 登录成功后凭证**原子写**（先写 .tmp 再 os.replace）
 #      ④ `bili_comments` 把抓取异常带进返回（风控 -412 不再伪装成"这条视频 0 条评论"）
 #      ⑤ `bili_reply` 回执带上 `rpid` / `rpid_str` / `root` / `parent`（判重表与评论复核要用）
+#      ⑥ `bili_cover` / `bili_frames`：封面和画面帧**作为图片**返回（上游没有；
+#         图能不能进模型上下文由宿主判断）
 import asyncio
 import json
+import re
 import base64
 import os
+import struct
 import sys
 import tempfile
 from pathlib import Path
 from mcp.server.fastmcp import FastMCP
+from mcp.types import ImageContent, TextContent
 
 from bilibili_api import video, search, comment, Credential, dynamic, opus
 from bilibili_api import hot, rank, user, session, favorite_list
+from bilibili_api import homepage
 from bilibili_api.video_uploader import (
     VideoUploader, VideoUploaderPage, VideoMeta, Lines,
 )
@@ -64,6 +70,112 @@ def _guard(name: str) -> str:
     return ""
 
 
+# ⭐⭐ 语感闸门（治"鱼八股"）：**发评论之前，先在函数里拦一道**
+#   背景：章程里写"要有具体细节、别客套"，模型照样写"这条我认""值得一看" ——
+#         禁令没有范例有效、自觉没有拦截可靠 ⇒ 在执行层做最后一道检查（跟 _guard 同一思路）。
+#   三道检查（便宜、纯本地 / 一次轻请求）：
+#     ① 开头八股黑名单（正则）
+#     ② 跟**自己以前发过的评论**太像（bigram 相似度）—— 治"每条一个味"
+#     ③ 跟**这条视频现有热评**太像 —— 治"跟别的鱼撞车"
+#   ⚠️ 撞了就**不发**，把原因和改法返回给模型，让它重写一句。
+#   ⚠️ 关掉：`BILI_STYLE_OFF=1`。
+_STYLE_OFF = os.environ.get("BILI_STYLE_OFF", "") in ("1", "true", "yes")
+_STYLE_LEAD = re.compile(
+    r"^\s*(?:"
+    r"这条(?:我认|我记下了|值得)|我记下了|值得一看|确实值得|不得不说|"
+    r"好家伙|这个(?:必须|真的要)|强烈推荐|感谢分享|学到了|受教了|"
+    r"作为一个|总之|综上"
+    r")"
+)
+
+
+def _bigrams(s: str) -> set:
+    t = re.sub(r"[^\w\u4e00-\u9fff]", "", "".join(ch for ch in str(s or "") if not ch.isspace()))
+    if len(t) < 2:
+        return set(t)
+    return {t[i:i + 2] for i in range(len(t) - 1)}
+
+
+def _sim(a: str, b: str) -> float:
+    """bigram Jaccard —— 够用、够快、零依赖"""
+    x, y = _bigrams(a), _bigrams(b)
+    if not x or not y:
+        return 0.0
+    return len(x & y) / max(1, len(x | y))
+
+
+def _ledger_path():
+    try:
+        return DUTY_HOME / "comments.md"
+    except Exception:
+        return Path(__file__).parent / "comments.md"
+
+
+def _ledger_recent(n: int = 30):
+    """最近 n 条"自己发过的评论"正文（台账一行：`- 日期 BVID rpid=… · 正文`）"""
+    try:
+        p = _ledger_path()
+        if not p.exists():
+            return []
+        out = []
+        for ln in p.read_text(encoding="utf-8").splitlines():
+            ln = ln.strip()
+            if not ln.startswith("- "):
+                continue
+            body = ln.split("·", 1)[1].strip() if "·" in ln else ln[2:].strip()
+            if body:
+                out.append(body)
+        return out[-n:]
+    except Exception:
+        return []
+
+
+def _ledger_append(text: str, bvid: str, rpid=None):
+    try:
+        p = _ledger_path()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        with open(p, "a", encoding="utf-8") as f:
+            f.write(f"- {_dt.datetime.now().strftime('%Y-%m-%d %H:%M')} {bvid} rpid={rpid or 0} · {' '.join(str(text).split())}\n")
+    except Exception:
+        pass
+
+
+async def _style_reason(text: str, bvid: str, cred) -> str:
+    """返回"为什么这句不能发"；空串 = 可以发"""
+    if _STYLE_OFF:
+        return ""
+    body = " ".join(str(text or "").split())
+    if not body:
+        return "评论是空的。"
+    m = _STYLE_LEAD.match(body)
+    if m:
+        return (f"开头「{m.group(0).strip()}」是鱼八股。直接说这条视频里的具体东西："
+                "「这期讲了什么 + 一个只有看了才说得出的细节」，开头别用套话。")
+    for old in _ledger_recent(30):
+        s = _sim(body, old)
+        if s >= 0.55:
+            return (f"这句跟你以前发过的「{old[:18]}…」太像了（相似度 {s:.2f}）。"
+                    "换开头、换关注点，别套同一个句式。")
+    try:
+        v = video.Video(bvid=bvid, credential=cred)
+        aid = (await v.get_info())["aid"]
+        resp = await comment.get_comments(
+            oid=aid, type_=comment.CommentResourceType.VIDEO, page_index=1,
+            order=comment.OrderType.LIKE, credential=cred,
+        )
+        for c in (resp.get("replies") or [])[:20]:
+            other = " ".join(str((c.get("content") or {}).get("message", "")).split())
+            if not other:
+                continue
+            s = _sim(body, other)
+            if s >= 0.5:
+                return (f"这条视频底下已经有一句很像的（相似度 {s:.2f}）：{other[:24]}… "
+                        "撞车了 —— 换个角度写，或者这一轮不发。")
+    except Exception:
+        pass  # 读不到热评就不做这道检查（不能因为读不到就不让发）
+    return ""
+
+
 def load_credential() -> Credential:
     """从文件加载凭证"""
     if not CRED_FILE.exists():
@@ -536,6 +648,10 @@ async def bili_reply(bvid: str, text: str, rpid: int = 0, root: int = 0) -> str:
     """
     _deny = _guard("bili_reply")
     if _deny: return _deny
+    # ⭐ 语感闸门：撞八股 / 撞自己以前的 / 撞这条视频的热评 ⇒ 不发，把改法告诉模型
+    _style = await _style_reason(text, bvid, get_cred())
+    if _style:
+        return json.dumps({"ok": False, "sent": False, "blocked_by": "style", "error": _style}, ensure_ascii=False)
     cred = get_cred()
     v = video.Video(bvid=bvid, credential=cred)
     info = await v.get_info()
@@ -568,6 +684,7 @@ async def bili_reply(bvid: str, text: str, rpid: int = 0, root: int = 0) -> str:
         #    （lib/verify.mjs）也要拿它去 B站 查公开可见性。只回 success 的话那条链是断的。
         #（2026-10-16 审查修：原实现把上面的 result 丢掉了）
         out = {"success": True, "message": "评论发送成功"}
+        _ledger_append(text, bvid, result.get("rpid") if isinstance(result, dict) else None)
         if isinstance(result, dict):
             for key in ("rpid", "rpid_str", "root", "parent"):
                 val = result.get(key)
@@ -1134,6 +1251,595 @@ async def bili_received_at_and_likes() -> str:
     return json.dumps(result, ensure_ascii=False)
 
 
+# ========== 值班轮窄口 IO（2026-10-24 · issue #96 安全加固）==========
+# ⭐ 值班轮现在跑在「最小权限 profile」上：**没有文件系统、没有 shell、没有 web**。
+#    但它还得写日报 / 判重表 / 归档、还得能转写 —— 所以这几件事做成**固定路径的窄口工具**：
+#    · 只写 <家>/out/<日期>.md、<家>/seen.md、<家>/digest/<年-月>.md
+#    · **不接受任何路径参数**（想写别处也写不了）✓
+#    · 输入里的竖线会被转义，标题带 | 也不会把表格弄坏
+import datetime as _dt
+
+DUTY_HOME = Path(os.environ.get("BILI_DUTY_HOME") or (Path.home() / ".dsh" / "bili-duty"))
+
+
+def _duty_today() -> str:
+    return _dt.datetime.now().strftime("%Y-%m-%d")
+
+
+def _cell(s: str, limit: int = 60) -> str:
+    """表格单元格：去换行、转义竖线、截断。"""
+    t = " ".join(str(s or "").split())
+    return t.replace("|", "\\|")[:limit]
+
+
+def _append(path: Path, text: str) -> str:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "a", encoding="utf-8", newline="\n") as f:
+        f.write(text)
+    return str(path)
+
+
+@tool()
+def duty_paths() -> str:
+    """
+    这一轮允许写的三个位置（绝对路径）—— 想写东西只能通过这些 duty_* 工具，不要找别的路。
+
+    Returns:
+        报告 / 判重表 / 归档 的绝对路径
+    """
+    out = {
+        "home": str(DUTY_HOME),
+        "report": str(DUTY_HOME / "out" / (_duty_today() + ".md")),
+        "seen": str(DUTY_HOME / "seen.md"),
+        "digest": str(DUTY_HOME / "digest" / (_dt.datetime.now().strftime("%Y-%m") + ".md")),
+    }
+    return json.dumps(out, ensure_ascii=False)
+
+
+@tool()
+def duty_report_append(text: str) -> str:
+    """
+    往**今天的日报**末尾追加一段（文件不存在会自动建）。
+
+    Args:
+        text: 要追加的内容（markdown 纯文本）
+
+    Returns:
+        写到了哪个文件
+    """
+    body = str(text or "").replace("\r\n", "\n").strip()
+    if not body:
+        return "没写：内容是空的"
+    p = DUTY_HOME / "out" / (_duty_today() + ".md")
+    fresh = not p.exists()
+    payload = body + "\n"
+    if fresh:
+        payload = "# 刷B站日报 " + _duty_today() + "\n\n" + payload
+    return "已追加到 " + _append(p, payload)
+
+
+@tool()
+def duty_seen_append(bvid: str, title: str, up: str, status: str, date: str = "") -> str:
+    """
+    往判重表追加一行（「挑了」= 进过报告 / 「跳过」= 看过但没进 / 「评论」= 本轮 @ 过）。
+
+    Args:
+        bvid: BV 号
+        title: 标题
+        up: UP 主
+        status: 挑了 / 跳过 / 评论
+        date: 日期（YYYY-MM-DD，留空=今天）
+
+    Returns:
+        写到了哪个文件
+    """
+    bv = str(bvid or "").strip()
+    if not bv:
+        return "没写：bvid 是空的"
+    d = (str(date or "").strip() or _duty_today())[:10]
+    row = f"| {_cell(d, 10)} | {_cell(bv, 16)} | {_cell(title)} | {_cell(up, 30)} | {_cell(status, 8)} |\n"
+    return "已追加到 " + _append(DUTY_HOME / "seen.md", row)
+
+
+@tool()
+def duty_seen_recent(limit: int = 40, bvid: str = "") -> str:
+    """
+    读判重表的最近若干行（只读，只读插件自己那份 seen.md）。
+
+    Args:
+        limit: 取最近多少行（默认 40，上限 200）
+        bvid: 只查某个 BV（留空=看全部）
+
+    Returns:
+        表格行（日期 | BV | 标题 | UP | 状态）；空 = 这份表还没内容
+    """
+    f = DUTY_HOME / "seen.md"
+    if not f.exists():
+        return "（判重表还不存在）"
+    try:
+        lines = f.read_text(encoding="utf-8", errors="replace").splitlines()
+    except Exception as e:
+        return "读不到判重表：" + str(e)
+    rows = [ln for ln in lines if ln.strip().startswith("|") and "---" not in ln and not ln.strip().startswith("| 日期")]
+    if bvid:
+        bv = str(bvid).strip()
+        rows = [ln for ln in rows if bv in ln]
+    n = max(1, min(int(limit or 40), 200))
+    tail = rows[-n:]
+    if not tail:
+        return "（最近没有记录）"
+    return "共 " + str(len(rows)) + " 行，最近 " + str(len(tail)) + " 行：\n" + "\n".join(tail)
+
+
+@tool()
+def duty_digest_append(text: str) -> str:
+    """
+    往**本月归档**末尾追加一段（「digest/<年-月>.md」，给"后来翻旧账"用的）。
+
+    Args:
+        text: 要追加的内容
+
+    Returns:
+        写到了哪个文件
+    """
+    body = str(text or "").replace("\r\n", "\n").strip()
+    if not body:
+        return "没写：内容是空的"
+    p = DUTY_HOME / "digest" / (_dt.datetime.now().strftime("%Y-%m") + ".md")
+    return "已追加到 " + _append(p, body + "\n")
+
+
+@tool()
+def bili_transcribe(bvid: str) -> str:
+    """
+    用本地 ASR（家目录里的独立环境）把一条**没有字幕**的视频转成文字。慢（几分钟）。
+
+    Args:
+        bvid: BV 号
+
+    Returns:
+        转写出来的文字（截断到 12000 字）；空的 / 只有署名 ⇒ 当作这条没有语音
+    """
+    import subprocess
+
+    bv = str(bvid or "").strip()
+    if not bv.startswith("BV"):
+        return "参数不对：要给 BV 号"
+    py_candidates = [
+        DUTY_HOME / ".venv-asr" / "Scripts" / "python.exe",
+        DUTY_HOME / ".venv-asr" / "bin" / "python",
+    ]
+    py = next((str(p) for p in py_candidates if p.exists()), "")
+    if not py:
+        return "转写环境没装好（设置页里有「装转写依赖」）"
+    script = DUTY_HOME / "asr.py"
+    if not script.exists():
+        return "找不到 asr.py（家目录里没有转写脚本）"
+    out = DUTY_HOME / "tmp" / (bv + ".txt")
+    out.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        r = subprocess.run(
+            [py, str(script), bv, "-o", str(out)],
+            capture_output=True, timeout=1800,
+            env={**os.environ, "PYTHONUTF8": "1", "PYTHONIOENCODING": "utf-8"},
+        )
+    except subprocess.TimeoutExpired:
+        return "转写超时（30 分钟）—— 这条按「读不到」处理，跳过它"
+    except Exception as e:
+        return "转写启动失败：" + str(e)
+    if not out.exists():
+        tail = (r.stderr or b"")[-400:].decode("utf-8", "replace")
+        return "转写没产出文件（exit " + str(r.returncode) + "）：" + tail
+    text = out.read_text(encoding="utf-8", errors="replace").strip()
+    if not text:
+        return "（空）—— 这条没有语音，跳过它"
+    if len(text) <= 40 and ("字幕by" in text or "字幕BY" in text):
+        return "（只有署名「" + text[:40] + "」）—— 当没有语音处理，跳过"
+    return text[:12000]
+
+# ========== Tool 25: 看画面（封面） ==========
+#
+# 图作为 MCP image content 返回，由宿主决定能否进模型上下文。
+# 缩图交给 B 站图片 CDN（URL 后缀 @512w.jpg），不引 Pillow、不落临时文件。
+
+_WEB_UA = (
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/124.0 Safari/537.36"
+)
+_COVER_WIDTH = 512
+_HTTP_TIMEOUT = 25               # 图床 / 快照下载统一超时（秒）
+# 防御性上限：实测封面 23–36KB、帧 2.6–29KB，正常走不到这一行
+_MAX_IMAGE_BYTES = 1_500_000
+
+
+def _https(url: str) -> str:
+    """把 B 站的图片/资源地址统一成 https。
+
+    view 接口给的 `pic` 实测 10/10 都是 `http://`，而 http 不会跳转 https；
+    图床请求再带上 SESSDATA 就等于把登录凭据明文发出去。
+    """
+    u = str(url or "")
+    if u.startswith("//"):
+        return "https:" + u
+    if u.startswith("http://"):
+        return "https://" + u[len("http://"):]
+    return u
+
+
+def _cover_url(pic: str, width: int = _COVER_WIDTH) -> str:
+    """封面原图地址 → 带 CDN 缩放后缀（@<宽>w.jpg）的地址，等比不裁切。"""
+    base = _https(str(pic).split("@", 1)[0])
+    return f"{base}@{width}w.jpg"
+
+
+def _image_headers() -> dict:
+    """图床请求头：只给 UA + Referer，**不带 Cookie**（图床不需要登录态）。"""
+    return {"User-Agent": _WEB_UA, "Referer": "https://www.bilibili.com/"}
+
+
+def _text_only(payload: dict) -> list:
+    return [TextContent(type="text", text=json.dumps(payload, ensure_ascii=False))]
+
+
+@tool()
+async def bili_cover(bvid: str) -> list:
+    """
+    看这个视频的封面（等比缩到 512px 宽）
+
+    最便宜的一档"看一眼"：能看出风格、标题美术、大致题材，但看不出具体发生了什么。
+
+    Args:
+        bvid: 视频BV号，如"BV1uNk1YxEJQ"
+
+    Returns:
+        封面图 + 一句说明（标题、时长、图多大）。
+        图能不能真被看见取决于当前模型是否支持图片输入；不支持时会被降级成文字。
+    """
+    import aiohttp
+
+    cred = load_credential()          # 封面是公开的，没登录也取得到
+    try:
+        v = video.Video(bvid=bvid, credential=cred)   # 格式不对时**构造时就抛**
+        info = await v.get_info()
+    except Exception as e:
+        # ⚠️ 2026-10-23 实测两种失败：`62002 稿件不可见`（BV 不存在）
+        #    和 `ArgsException`（格式不对，构造时就抛）。都收成 ok:false。
+        return _text_only({"bvid": bvid, "ok": False, "error": f"取视频信息失败：{e}"})
+
+    pic = str(info.get("pic") or "")
+    if not pic:
+        return _text_only({"bvid": bvid, "ok": False, "error": "这个视频没有封面地址"})
+
+    url = _cover_url(pic)
+    try:
+        timeout = aiohttp.ClientTimeout(total=_HTTP_TIMEOUT)
+        async with aiohttp.ClientSession(timeout=timeout) as s:
+            async with s.get(url, headers=_image_headers()) as resp:
+                if resp.status != 200:
+                    raise RuntimeError(f"HTTP {resp.status}")
+                raw = await resp.read()
+                mime = (resp.headers.get("Content-Type") or "image/jpeg").split(";")[0].strip()
+    except Exception as e:
+        return _text_only({"bvid": bvid, "ok": False, "error": f"下载封面失败：{e}"})
+
+    allowed = ("image/jpeg", "image/png", "image/webp", "image/gif")
+    if mime not in allowed:
+        return _text_only({"bvid": bvid, "ok": False, "error": f"封面不是可用的图片类型：{mime}"})
+    if len(raw) > _MAX_IMAGE_BYTES:
+        return _text_only({
+            "bvid": bvid, "ok": False,
+            "error": f"封面太大（{len(raw) // 1024}KB），没放进来",
+        })
+
+    return [
+        TextContent(type="text", text=json.dumps({
+            "bvid": bvid,
+            "ok": True,
+            "title": info.get("title"),
+            "duration": info.get("duration"),
+            "cover_kb": round(len(raw) / 1024, 1),
+        }, ensure_ascii=False)),
+        ImageContent(
+            type="image",
+            data=base64.b64encode(raw).decode("ascii"),
+            mimeType=mime,
+        ),
+    ]
+
+
+# ========== Tool 26: 看画面（画面帧） ==========
+#
+# 画面来自 B 站自带的故事板（x/player/videoshot），不解码视频、不用 ffmpeg。
+# Video.get_video_snapshot() 有封装，但 pvideo 默认 True 会走老接口，必须传 False。
+# 裁切用 Pillow（requirements 里的 qrcode[pil] 已经带进来）。
+
+_FRAME_MAX = 6
+_TILE_W_DEFAULT = 480
+_TILE_H_DEFAULT = 270
+
+
+def _snapshot_entries(data: dict, duration: float = 0.0) -> list:
+    """把 videoshot 的 index 归一成 [(秒, 块序号), ...]。
+
+    时间单位实测两种都出现过（秒 / 毫秒），只能靠和时长比较来判断：
+    超过时长 1.5 倍才当毫秒。⚠️ 别再加"绝对值大于某个数就当毫秒"这类判据 ——
+    6 小时视频的秒数（22163）会被误判成毫秒，三帧全塌到同一块、时间缩小 1000 倍。
+    """
+    raws = []
+    for i, item in enumerate(data.get("index") or []):
+        ts = item.get("timestamp") if isinstance(item, dict) else item
+        try:
+            raws.append((float(ts), i))
+        except (TypeError, ValueError):
+            continue
+    if not raws:
+        return []
+
+    biggest = max(v for v, _ in raws)
+    looks_ms = duration > 0 and biggest > duration * 1.5
+    scale = 1000.0 if looks_ms else 1.0
+    return [(v / scale, i) for v, i in raws]
+
+
+async def _entries_from_pvdata(data: dict) -> list:
+    """index 为空时的兜底：pvdata 指向一个大端 uint16 秒数数组，与 index 逐项相同。"""
+    url = _https(data.get("pvdata") or "")
+    if not url:
+        return []
+    try:
+        raw = await _fetch_bytes(url, _image_headers())
+    except Exception:
+        return []
+    if not raw or len(raw) % 2:
+        return []
+    count = len(raw) // 2
+    if count > 20000:            # 明显不对，别乱解
+        return []
+    return [(float(sec), i) for i, sec in enumerate(struct.unpack(f">{count}H", raw))]
+
+
+async def _fetch_bytes(url: str, headers: dict) -> bytes:
+    import aiohttp
+
+    timeout = aiohttp.ClientTimeout(total=_HTTP_TIMEOUT)
+    async with aiohttp.ClientSession(timeout=timeout) as s:
+        async with s.get(_https(url), headers=headers) as resp:
+            if resp.status != 200:
+                raise RuntimeError(f"HTTP {resp.status}")
+            return await resp.read()
+
+
+def _crop_tile(sheet: bytes, tile_index: int, tw: int, th: int) -> bytes:
+    """从拼图里裁出第 tile_index 块，返回 jpeg 字节。"""
+    import io
+
+    from PIL import Image
+
+    img = Image.open(io.BytesIO(sheet))
+    cols = max(1, img.width // tw)
+    rows = max(1, img.height // th)
+    if tile_index >= cols * rows:
+        raise RuntimeError(f"第 {tile_index} 块超出拼图（只有 {cols}×{rows}）")
+    col, row = tile_index % cols, tile_index // cols
+    tile = img.crop((col * tw, row * th, (col + 1) * tw, (row + 1) * th)).convert("RGB")
+    buf = io.BytesIO()
+    tile.save(buf, format="JPEG", quality=85)
+    return buf.getvalue()
+
+
+@tool()
+async def bili_frames(bvid: str, num: int = 3, at: list | None = None) -> list:
+    """
+    看这个视频里的画面（从 B 站自带的故事板里裁几帧）
+
+    想看"它到底拍了什么"就用它。默认按时长均匀取 3 帧；
+    想盯某个时刻（比如字幕里提到的那一段）就传 at（单位：秒），会取**最接近的那一块**。
+
+    Args:
+        bvid: 视频BV号，如"BV1uNk1YxEJQ"
+        num: 取几帧，1-6，默认 3
+        at: 指定时间点（秒）的列表；传了就以它为准，忽略 num
+
+    Returns:
+        若干张 480×270 的画面 + 一句说明（时长、实际取到的那一刻、哪几帧失败）。
+        失败会写进 failed。**多P 视频的故事板通常只覆盖第 1P**，返回里会用
+        covered_sec / pages 标明实际覆盖范围。图能否被看见取决于模型是否支持图片输入。
+    """
+    cred = load_credential()          # 故事板不登录也能取
+    try:
+        v = video.Video(bvid=bvid, credential=cred)
+        info = await v.get_info()
+    except Exception as e:
+        return _text_only({"bvid": bvid, "ok": False, "error": f"取视频信息失败：{e}"})
+    duration = float(info.get("duration") or 0)
+    pages = info.get("pages") or []
+    cid = info.get("cid") or ((pages or [{}])[0].get("cid") or 0)
+    if not cid:
+        return _text_only({"bvid": bvid, "ok": False, "error": "拿不到 cid"})
+
+    # 故事板只覆盖第 1P：目标时间点按"实际覆盖的长度"算，别落到没采样的 P2 上
+    covered = float(pages[0].get("duration") or duration) if pages else duration
+    covered = covered or duration
+
+    # index 会偶发返回空（实测约 25%）：先用 pvdata 兜底，两个都空才重试
+    snap = {}
+    entries = []
+    last_err = None
+    for attempt in range(2):
+        try:
+            snap = await v.get_video_snapshot(cid=cid, json_index=True, pvideo=False) or {}
+            last_err = None
+        except Exception as e:
+            snap, last_err = {}, e
+        entries = _snapshot_entries(snap, covered)
+        if not entries:
+            entries = await _entries_from_pvdata(snap)
+        if entries and (snap.get("image") or []):
+            break
+        if attempt < 1:
+            await asyncio.sleep(1.0)
+
+    sheets = snap.get("image") or []
+    if not entries or not sheets:
+        err = f"（最后一次错误：{last_err}）" if last_err is not None else ""
+        return _text_only({
+            "bvid": bvid, "ok": False,
+            "error": f"取不到画面快照（试了 2 次）{err}",
+        })
+
+    # 覆盖长度以**故事板实测到的那一刻**为准（比 P1 的标称时长保守，通常短 1–10%）
+    story_max = max((e[0] for e in entries), default=0.0)
+    if story_max > 0:
+        covered = min(covered, story_max)
+
+    # 目标时间点：传了 at 就用它；否则按"覆盖长度"均分
+    if at:
+        targets = [min(max(0.0, float(t)), max(0.0, covered - 0.1)) for t in at][:_FRAME_MAX]
+    else:
+        n = max(1, min(int(num or 3), _FRAME_MAX))
+        targets = [covered * (i + 1) / (n + 1) for i in range(n)]
+
+    picked = []
+    for t in targets:
+        ts, tile = min(entries, key=lambda e: abs(e[0] - t))
+        picked.append((round(t, 1), round(ts, 1), tile))
+
+    tw = int(snap.get("img_x_size") or _TILE_W_DEFAULT)
+    th = int(snap.get("img_y_size") or _TILE_H_DEFAULT)
+    headers = _image_headers()
+
+    cache = {}
+
+    async def get_sheet(no: int) -> bytes:
+        if no not in cache:
+            if no >= len(sheets):
+                raise RuntimeError(f"拼图 {no} 不存在（共 {len(sheets)} 张）")
+            cache[no] = await _fetch_bytes(str(sheets[no]), headers)
+        return cache[no]
+
+    # 每张拼图装几块要等第一张下来才知道（列数 = 宽 // 块宽）
+    blocks, frames, failed = [], [], []
+    cap = None
+    for i, (want, got, tile) in enumerate(picked):
+        try:
+            if cap is None:
+                first = await get_sheet(0)
+                import io
+
+                from PIL import Image
+
+                im = Image.open(io.BytesIO(first))
+                cap = max(1, (im.width // tw) * (im.height // th))
+            sheet_no, pos = tile // cap, tile % cap
+            raw = _crop_tile(await get_sheet(sheet_no), pos, tw, th)
+            if len(raw) > _MAX_IMAGE_BYTES:
+                raise RuntimeError(f"这一帧太大（{len(raw) // 1024}KB）")
+            blocks.append(ImageContent(
+                type="image",
+                data=base64.b64encode(raw).decode("ascii"),
+                mimeType="image/jpeg",
+            ))
+            frames.append({"index": i, "want_sec": want, "got_sec": got,
+                           "kb": round(len(raw) / 1024, 1)})
+        except Exception as e:
+            failed.append({"index": i, "want_sec": want, "got_sec": got, "reason": str(e)})
+
+    if not blocks:
+        return _text_only({
+            "bvid": bvid, "ok": False,
+            "error": "一帧都没取到", "failed": failed,
+        })
+
+    return [
+        TextContent(type="text", text=json.dumps({
+            "bvid": bvid,
+            "ok": True,
+            "title": info.get("title"),
+            "duration": duration,
+            "covered_sec": round(covered, 1),
+            "pages": max(1, len(pages)),
+            "tile": f"{tw}x{th}",
+            "frames": frames,
+            "failed": failed,        # 空列表 = 全成
+            "note": "want_sec 是想要的时刻，got_sec 是实际取到的那一块（故事板按固定间隔切）；"
+                    "多P 视频只覆盖第 1P，看 covered_sec",
+        }, ensure_ascii=False)),
+        *blocks,
+    ]
+
+
+# ========== Tool: 首页推荐流（不填关键词时用它，替代固定关键词搜索） ==========
+# ⭐ 为什么要它（2026-10-23 主人拍板）：
+#    以前不填关键词就用内置那几组（DeepSeek Harness / DSH 插件 …）⇒ **所有装了插件的人刷的是同一批视频**
+#    ⇒ 相关视频的评论区必然堆成一片"同款插件在互相报到" ✗
+#    推荐流按各自账号画像推，天然散开 ✓ —— 这是结构性解法，比"每轮少发几条"靠谱得多。
+#
+# ⚠️ 它需要登录凭证（匿名也能拿到一部分，但带凭证才是"这个账号的推荐"），
+#    所以这里用 load_credential()；拿不到就退成匿名（仍然能用，只是不那么"散"）。
+@tool()
+async def bili_recommend(ps: int = 20) -> str:
+    """
+    获取「首页推荐流」的视频（按当前登录账号的画像）
+
+    Args:
+        ps: 返回几条，默认 20，最多 40
+
+    Returns:
+        JSON 格式的视频列表，字段与 bili_search 对齐（bvid / title / author / play / danmaku / duration…）
+    """
+    denied = _guard("bili_recommend")
+    if denied:
+        return json.dumps({"ok": False, "error": denied}, ensure_ascii=False)
+
+    cred = None
+    try:
+        cred = load_credential()
+    except Exception:
+        cred = None
+
+    try:
+        data = await homepage.get_videos(credential=cred)
+    except Exception as e:  # noqa: BLE001 - 统一收成 ok:false，别把原始异常甩给模型
+        return json.dumps({"ok": False, "error": f"取推荐流失败：{e}"}, ensure_ascii=False)
+
+    items = []
+    if isinstance(data, dict):
+        items = data.get("item") or data.get("data") or []
+    elif isinstance(data, list):
+        items = data
+
+    videos = []
+    for it in items[: max(1, min(int(ps), 40))]:
+        if not isinstance(it, dict):
+            continue
+        # 只留视频（推荐流里会混进直播 / 番剧 / 广告卡片）
+        if it.get("goto") and it.get("goto") != "av":
+            continue
+        if not it.get("bvid"):
+            continue
+        owner = it.get("owner") or {}
+        stat = it.get("stat") or {}
+        dur = it.get("duration")
+        videos.append({
+            "bvid": it.get("bvid", ""),
+            "title": str(it.get("title", "")).strip(),
+            "author": owner.get("name", ""),
+            "play": stat.get("view", 0),
+            "danmaku": stat.get("danmaku", 0),
+            "like": stat.get("like", 0),
+            "duration": f"{int(dur) // 60}:{int(dur) % 60:02d}" if isinstance(dur, (int, float)) else str(dur or ""),
+            "pubdate": it.get("pubdate", 0),
+            "reason": (it.get("rcmd_reason") or {}).get("content", "") if isinstance(it.get("rcmd_reason"), dict) else "",
+        })
+
+    return json.dumps({
+        "ok": True,
+        "source": "recommend",
+        "count": len(videos),
+        "videos": videos,
+    }, ensure_ascii=False)
+
+
 # ========== 启动 ==========
 
 if __name__ == "__main__":