dsh-bili-scroll 2.0.2 → 2.1.0

package/vendor/bilibili-mcp/mcp_server.py

@@ -14,14 +14,18 @@ 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 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
@@ -53,6 +57,17 @@ def tool():
     return deco
 
 
+# ⭐⭐ 2026-10-23 安全加固（issue #39）：**白名单以前只挡"注册"，不挡"直接调用"** ——
+#    agent 手里有 python/shell，可以自己写脚本 import 这个文件再调函数 ⇒ 闸门形同虚设。
+#    ⇒ 每个"会往 B站 写东西"的函数入口都过一遍 _guard()；没开就直接返回、什么都不做 ✓
+def _guard(name: str) -> str:
+    """没开这个工具就返回一句提示；开着返回空串。"""
+    if _ALLOWED and name not in _ALLOWED:
+        print(f"[bili-mcp] 拒绝调用 {name}（不在 BILI_MCP_TOOLS 白名单里）", file=sys.stderr)
+        return f"这个工具没开：{name}"
+    return ""
+
+
 def load_credential() -> Credential:
     """从文件加载凭证"""
     if not CRED_FILE.exists():
@@ -523,6 +538,8 @@ async def bili_reply(bvid: str, text: str, rpid: int = 0, root: int = 0) -> str:
     Returns:
         发表结果
     """
+    _deny = _guard("bili_reply")
+    if _deny: return _deny
     cred = get_cred()
     v = video.Video(bvid=bvid, credential=cred)
     info = await v.get_info()
@@ -670,316 +687,6 @@ def _extract_cover_from_video(video_path: str) -> Picture:
             os.remove(tmp_cover2)
     raise RuntimeError(f"无法从视频截取封面: {video_path}")
 
-
-
-
-@tool()
-async def bili_send_dynamic(
-    text: str,
-    images: list[str] | None = None,
-    topic_id: int = 0,
-    schedule_time: int = 0,
-) -> str:
-    """
-    发布B站图文动态
-
-    Args:
-        text: 动态文本内容，支持@和表情（如 [doge]）
-        images: 图片列表，每项可以是本地文件路径或图片URL，最多9张。为空则发布纯文字动态
-        topic_id: 话题ID（可选，0表示不关联话题）
-        schedule_time: 定时发布的Unix时间戳（可选，0表示立即发布）
-
-    Returns:
-        发布结果，包含动态ID
-    """
-    if not text or not text.strip():
-        return json.dumps({"success": False, "error": "text 不能为空"}, ensure_ascii=False)
-
-    cred = get_cred()
-
-    dyn = dynamic.BuildDynamic.empty()
-    dyn.add_plain_text(text.strip())
-    # 上传图片
-    if images:
-        for img_path in images[:9]:
-            try:
-                if not img_path or not img_path.strip():
-                    continue
-                img_path = img_path.strip()
-                if img_path.startswith(("http://", "https://")):
-                    pic = await Picture.async_from_url(img_path)
-                else:
-                    if not os.path.isfile(img_path):
-                        return json.dumps({"success": False, "error": f"图片文件不存在: {img_path}"}, ensure_ascii=False)
-                    pic = Picture.from_file(img_path)
-                dyn.add_image(pic)
-            except Exception as e:
-                return json.dumps({"success": False, "error": f"图片处理失败: {img_path} - {str(e)}"}, ensure_ascii=False)
-
-    if topic_id:
-        dyn.set_topic(topic_id)
-
-    if schedule_time > 0:
-        dyn.set_send_time(schedule_time)
-
-    try:
-        result = await dynamic.send_dynamic(info=dyn, credential=cred)
-        return json.dumps({
-            "success": True,
-            "message": "动态发布成功",
-            "data": result if isinstance(result, dict) else str(result),
-        }, ensure_ascii=False)
-    except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, ensure_ascii=False)
-
-
-# ========== Tool 9: 上传视频 ==========
-
-@tool()
-async def bili_upload_video(
-    video_path: str,
-    title: str,
-    desc: str = "",
-    tid: int = 124,
-    tags: str = "AI",
-    cover_path: str = "",
-    source: str = "",
-    dynamic_text: str = "",
-    no_reprint: bool = True,
-) -> str:
-    """
-    上传视频到B站
-
-    Args:
-        video_path: 视频文件的本地路径
-        title: 视频标题（最多80字）
-        desc: 视频简介描述
-        tid: 分区ID，默认124（趣味科普人文-社科·法律·心理）。
-             常用分区：17=单机游戏 21=日常 95=数码 122=野生技术协会
-             124=社科 160=生活记录 171=电子竞技 183=影视杂谈
-             188=科技资讯 201=科学 207=财经商业 208=科技 209=手工
-             230=其他(生活) 231=美食 234=健身 32=完结动画
-        tags: 标签，逗号分隔，如"AI,教程,编程"（至少1个标签）
-        cover_path: 封面图片路径（可选，不填则B站自动截取）
-        source: 转载来源URL（非原创时必填）
-        dynamic_text: 粉丝动态文本（可选，投稿时同步发布的动态内容）
-        no_reprint: 是否启用未经作者授权禁止转载，默认True
-
-    Returns:
-        上传结果，包含BV号
-    """
-    # ---- 参数校验 ----
-    if not video_path or not video_path.strip():
-        return json.dumps({"success": False, "error": "video_path 不能为空，请提供视频文件的本地路径"}, ensure_ascii=False)
-
-    video_path = video_path.strip()
-    if not os.path.isfile(video_path):
-        return json.dumps({"success": False, "error": f"视频文件不存在: {video_path}"}, ensure_ascii=False)
-
-    if not title or not title.strip():
-        return json.dumps({"success": False, "error": "title 不能为空"}, ensure_ascii=False)
-
-    cred = get_cred()
-
-    try:
-        # 准备分P
-        page = VideoUploaderPage(
-            path=video_path,
-            title=title.strip()[:80],
-            description=(desc or "")[:250],
-        )
-
-        # 标签处理
-        tag_list = [t.strip() for t in (tags or "").split(",") if t.strip()]
-        if not tag_list:
-            tag_list = ["视频"]
-
-        # 判断原创/转载
-        is_original = not bool(source and source.strip())
-
-        # 封面：用户提供 > 自动从视频截取
-        if cover_path and cover_path.strip() and os.path.isfile(cover_path.strip()):
-            cover_pic = Picture.from_file(cover_path.strip())
-        else:
-            cover_pic = _extract_cover_from_video(video_path)
-
-        meta = VideoMeta(
-            tid=tid,
-            title=title.strip()[:80],
-            desc=desc or "",
-            cover=cover_pic,
-            tags=tag_list,
-            original=is_original,
-            source=source.strip() if source and source.strip() else None,
-            no_reprint=no_reprint if is_original else False,
-            dynamic=dynamic_text.strip() if dynamic_text and dynamic_text.strip() else None,
-        )
-
-        uploader = VideoUploader(
-            pages=[page],
-            meta=meta,
-            credential=cred,
-        )
-
-        # 上传事件回调（记录进度）
-        progress_info = {"phase": "初始化"}
-
-        @uploader.on("__ALL__")
-        async def on_event(data: dict):
-            progress_info["phase"] = str(data)
-
-        result = await uploader.start()
-        return json.dumps({
-            "success": True,
-            "message": "视频上传成功",
-            "data": result if isinstance(result, dict) else str(result),
-        }, ensure_ascii=False)
-    except Exception as e:
-        return json.dumps({
-            "success": False,
-            "error": str(e),
-            "last_phase": progress_info.get("phase", "unknown") if "progress_info" in dir() else "init",
-        }, ensure_ascii=False)
-
-
-# ========== Tool 10: 上传多P视频 ==========
-
-@tool()
-async def bili_upload_video_multi(
-    video_paths: list[str],
-    page_titles: list[str],
-    title: str,
-    desc: str = "",
-    tid: int = 124,
-    tags: str = "AI",
-    cover_path: str = "",
-    source: str = "",
-) -> str:
-    """
-    上传多P视频到B站（多个分P合并为一个投稿）
-
-    Args:
-        video_paths: 视频文件路径列表，如["/path/p1.mp4", "/path/p2.mp4"]
-        page_titles: 各分P标题列表，与video_paths一一对应
-        title: 视频总标题
-        desc: 视频简介
-        tid: 分区ID，默认124
-        tags: 标签，逗号分隔
-        cover_path: 封面图片路径（可选）
-        source: 转载来源URL（非原创时必填）
-
-    Returns:
-        上传结果
-    """
-    cred = get_cred()
-
-    if not video_paths:
-        return json.dumps({"success": False, "error": "video_paths 不能为空"}, ensure_ascii=False)
-    if not page_titles:
-        return json.dumps({"success": False, "error": "page_titles 不能为空"}, ensure_ascii=False)
-    if len(video_paths) != len(page_titles):
-        return json.dumps({"success": False, "error": "video_paths 和 page_titles 数量必须一致"}, ensure_ascii=False)
-
-    try:
-        pages = []
-        for i, vp in enumerate(video_paths):
-            vp = (vp or "").strip()
-            if not vp or not os.path.isfile(vp):
-                return json.dumps({"success": False, "error": f"文件不存在: {vp}"}, ensure_ascii=False)
-            pages.append(VideoUploaderPage(
-                path=vp,
-                title=(page_titles[i] or "").strip()[:80] or f"P{i+1}",
-                description="",
-            ))
-
-        tag_list = [t.strip() for t in (tags or "").split(",") if t.strip()] or ["视频"]
-        is_original = not bool(source and source.strip())
-
-        # 封面：用户提供 > 从第一个视频自动截取
-        if cover_path and cover_path.strip() and os.path.isfile(cover_path.strip()):
-            cover_pic = Picture.from_file(cover_path.strip())
-        else:
-            cover_pic = _extract_cover_from_video(pages[0].path)
-
-        meta = VideoMeta(
-            tid=tid,
-            title=(title or "").strip()[:80],
-            desc=desc or "",
-            cover=cover_pic,
-            tags=tag_list,
-            original=is_original,
-            source=source.strip() if source and source.strip() else None,
-        )
-
-        uploader = VideoUploader(pages=pages, meta=meta, credential=cred)
-
-        result = await uploader.start()
-        return json.dumps({
-            "success": True,
-            "message": f"多P视频上传成功（共{len(pages)}P）",
-            "data": result if isinstance(result, dict) else str(result),
-        }, ensure_ascii=False)
-    except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, ensure_ascii=False)
-
-
-# ========== Tool 11: 发布专栏文章 (Opus) ==========
-
-@tool()
-async def bili_send_opus(
-    title: str,
-    content: str,
-    images: list[str] | None = None,
-    category_id: int = 0,
-) -> str:
-    """
-    发布B站图文（Opus，新版专栏）
-
-    Args:
-        title: 文章标题
-        content: 文章正文内容（纯文本，段落用换行分隔）
-        images: 文章中插入的图片路径或URL列表（可选）
-        category_id: 分类ID（可选，0表示不指定）
-
-    Returns:
-        发布结果
-    """
-    cred = get_cred()
-
-    dyn = dynamic.BuildDynamic.empty()
-
-    # 专栏动态以纯文本+图片方式构建
-    # 标题作为第一行加粗
-    full_text = f"【{title}】\n\n{content}"
-    dyn.add_plain_text(full_text)
-
-    if images:
-        for img_path in images:
-            try:
-                if not img_path or not img_path.strip():
-                    continue
-                img_path = img_path.strip()
-                if img_path.startswith(("http://", "https://")):
-                    pic = await Picture.async_from_url(img_path)
-                else:
-                    pic = Picture.from_file(img_path)
-                dyn.add_image(pic)
-            except Exception as e:
-                pass  # 图片失败不阻断发布
-
-    try:
-        result = await dynamic.send_dynamic(info=dyn, credential=cred)
-        return json.dumps({
-            "success": True,
-            "message": "图文发布成功",
-            "data": result if isinstance(result, dict) else str(result),
-        }, ensure_ascii=False)
-    except Exception as e:
-        return json.dumps({"success": False, "error": str(e)}, ensure_ascii=False)
-
-
-# ========== Tool 12: 查询分区列表 ==========
-
 @tool()
 async def bili_video_zones() -> str:
     """
@@ -1330,6 +1037,8 @@ async def bili_send_message(receiver_uid: int, text: str) -> str:
     Returns:
         发送结果
     """
+    _deny = _guard("bili_send_message")
+    if _deny: return _deny
     cred = get_cred()
 
     if not text or not text.strip():
@@ -1342,10 +1051,29 @@ async def bili_send_message(receiver_uid: int, text: str) -> str:
             msg_type=session.EventType.TEXT,
             content=text.strip(),
         )
+        # ⭐ 2.0.4（issue #35）：**接口没抛异常 ≠ 真的送到了** ——
+        #    以前只要不抛就报 success: True，而 B站 可能出现 code=0 却没给投递回执（msg_key）的情况 ✗
+        #    回执就在返回值里：有 msg_key 才算发出去；code 非 0 直接算失败 ✓
+        data = result if isinstance(result, dict) else {}
+        code = data.get("code", 0)
+        inner = data.get("data")
+        msg_key = data.get("msg_key") or (inner.get("msg_key") if isinstance(inner, dict) else None)
+        if code not in (0, None):
+            return json.dumps({
+                "success": False,
+                "error": f"接口拒绝（code={code}）：{data.get('message') or data.get('msg') or '未知原因'}",
+                "data": data,
+            }, ensure_ascii=False)
+        if not msg_key:
+            return json.dumps({
+                "success": False,
+                "error": "接口回了成功，但**没有投递回执（msg_key）** ⇒ 可能没真正送到（常见于：对方不接受陌生人私信 / 被风控）",
+                "data": data,
+            }, ensure_ascii=False)
         return json.dumps({
             "success": True,
-            "message": f"私信已发送给UID:{receiver_uid}",
-            "data": result if isinstance(result, dict) else str(result),
+            "message": f"私信已投递（回执 {str(msg_key)[:12]}…）",
+            "data": data,
         }, ensure_ascii=False)
     except Exception as e:
         return json.dumps({"success": False, "error": str(e)}, ensure_ascii=False)
@@ -1410,6 +1138,523 @@ 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,
+    ]
+
+
 # ========== 启动 ==========
 
 if __name__ == "__main__":