dsh-deepmoyu 2.7.1 → 2.8.0

package/vendor/bilibili-mcp/mcp_server.py

@@ -131,16 +131,17 @@ def _guard_blocked(reservation, kind="send", why=""):
         return json.dumps(out, ensure_ascii=False)
     if kind == "read":
         if status == "pending":
-            message = "另一个进程正在读这条字幕 —— 这一轮先换别的视频"
+            message = "另一个进程正在取这条字幕，先看其他候选，完成后可从缓存补查"
         else:
             message = "这条已经刷过了（永久账本里有，重启也不会丢）—— 换一条"
         out = {
-            "already_seen": True,
+            "already_seen": status == "seen",
             "seen_recorded": False,
             "seen_at": at,
             "guard_status": status,
             "message": message,
-            "hint": "already_seen=true ⇒ 直接换别的视频；确实要重读，就在 bili_say 里说清为什么",
+            "hint": "已读标记用于选片去重，不禁止补查原文。读取正在进行时先处理其他候选，不要连续轮询。",
+            "next_action": "read-another-candidate",
         }
         if reservation.get("title"):
             out["title"] = reservation.get("title")
@@ -149,8 +150,10 @@ def _guard_blocked(reservation, kind="send", why=""):
         return json.dumps({
             "success": False, "already_replied": True, "retry_blocked": True,
             "guard_status": "unknown", "seen_at": at,
+            "slot_key": reservation.get("key", ""),
             "error": "上一次发出去的结果不确定（超时 / 回执不明）—— 不许自动重发",
-            "hint": "先自己去评论区 / 私信里看一眼到底发出去没有；确认没有，再手工重试",
+            "hint": ("先自己去评论区 / 私信里看一眼到底发出去没有；**确认没发出去**后，用 "
+                     "bili_guard_status(release=['这条的 slot_key']) 人工解除 unknown 槽位（P1-2），再重试"),
         }, ensure_ascii=False)
     if status == "pending":
         return json.dumps({
@@ -167,6 +170,18 @@ def _guard_blocked(reservation, kind="send", why=""):
     }, ensure_ascii=False)
 
 
+# P3-46: 守卫库被锁（SQLite busy>15s）时的统一 fail-closed 话术，措辞对齐 bili_subtitle
+# 的「判重账本不可用」兜底回执 —— 原始 traceback 绝不能直接漏给模型。
+_GUARD_LOCKED_ERROR = "判重账本暂不可用（可能被锁），先别重发；稍后用 bili_guard_status 核对坑位状态"
+
+
+def _guard_unavailable(exc) -> str:
+    """占坑阶段守卫异常 → JSON 错误回执（此时还没发任何东西，可以稍后重试）。"""
+    return json.dumps({"success": False, "error": _GUARD_LOCKED_ERROR,
+                       "detail": f"{type(exc).__name__}: {exc}",
+                       "guard_status": "not_sent", "retry_blocked": False}, ensure_ascii=False)
+
+
 async def _guarded_send(guard, reservation, runner, record=None):
     """在**已经占好坑**的前提下真正发出去，并如实落账。
 
@@ -196,7 +211,13 @@ async def _guarded_send(guard, reservation, runner, record=None):
             return None
 
     def _rejected(error, result, code):
-        pace = guard.reject_send(reservation, code)
+        try:
+            pace = guard.reject_send(reservation, code)
+        except Exception as exc:
+            # P3-46: 拒绝落账失败（库被锁）不能裸抛 —— 事务已回滚、坑位留在 pending 正好挡重发，
+            # 回执转 fail-closed（guard_status=unknown ⇒ 调用方会回「别自动重发」的话术）。
+            return {"guard_status": "unknown", "error": _GUARD_LOCKED_ERROR, "retry_blocked": True,
+                    "result": result, "code": code, "ledger_detail": f"{type(exc).__name__}: {exc}"}
         out = {"guard_status": "rejected", "error": error, "retry_blocked": False,
                "result": result, "code": code}
         if code == 49044:
@@ -232,8 +253,15 @@ async def _guarded_send(guard, reservation, runner, record=None):
         return {"guard_status": "unknown", "error": str(result.get("error") or "没有确定的回执"),
                 "retry_blocked": True, "result": result, "code": code}
 
-    guard.commit_send(reservation, record)
-    return {"guard_status": "sent", "error": "", "retry_blocked": False, "result": result, "code": None}
+    try:
+        guard.commit_send(reservation, record)
+    except Exception as exc:
+        # P3-46: 落账失败（库被锁 >15s）不能裸抛 —— 发送本身可能已成功，坑位留在 pending
+        # 挡住重发；回执转 fail-closed JSON 并指引去 bili_guard_status 核对，而不是 traceback。
+        return {"guard_status": "unknown", "error": _GUARD_LOCKED_ERROR, "retry_blocked": True,
+                "result": result, "code": None, "ledger_detail": f"{type(exc).__name__}: {exc}"}
+    return {"guard_status": "sent", "error": "", "retry_blocked": False, "result": result, "code": None,
+            "pace_token": reservation.get("token", "")}
 
 
 def ts_to_day(ts) -> str:
@@ -407,10 +435,13 @@ async def bili_login_check() -> str:
 
     elif state == QrCodeLoginEvents.TIMEOUT:
         _login_session = None
-        # 清理二维码文件
+        # 清理二维码文件（P3-47: Windows 下 PNG 被看图程序占用会 PermissionError，别让它炸回执）
         qr_file = Path(__file__).parent / "qrcode_login.png"
         if qr_file.exists():
-            qr_file.unlink()
+            try:
+                qr_file.unlink()
+            except OSError as e:
+                print(f"[bili-mcp] 二维码文件删不掉（{type(e).__name__}: {e}）：{qr_file}", file=sys.stderr)
         return json.dumps({
             "status": "timeout",
             "message": "二维码已过期，请重新调用 bili_login 生成新二维码",
@@ -431,10 +462,13 @@ async def bili_login_check() -> str:
             }, f)
         os.replace(tmp_cred, CRED_FILE)
         _login_session = None
-        # 清理二维码文件
+        # 清理二维码文件（P3-47: 删失败只记 stderr —— DONE 分支反复重入比带着孤儿 PNG 重坏了）
         qr_file = Path(__file__).parent / "qrcode_login.png"
         if qr_file.exists():
-            qr_file.unlink()
+            try:
+                qr_file.unlink()
+            except OSError as e:
+                print(f"[bili-mcp] 二维码文件删不掉（{type(e).__name__}: {e}）：{qr_file}", file=sys.stderr)
         return json.dumps({
             "status": "done",
             "message": "登录成功！凭证已保存，现在可以使用所有B站功能了",
@@ -484,7 +518,7 @@ async def bili_check_credential() -> str:
 # ========== Tool 1: 搜索视频 ==========
 
 @tool()
-async def bili_search(keyword: str, num: int = 10, order: str = "totalrank", days: int = 0) -> str:
+async def bili_search(keyword: str, num: int = 10, order: str = "totalrank", days: int = 0, page: StrictInt = 1) -> str:
     """
     搜索B站视频
 
@@ -493,12 +527,16 @@ async def bili_search(keyword: str, num: int = 10, order: str = "totalrank", day
         num: 返回视频数量，默认10，最大50
         order: 排序方式 totalrank=综合 click=播放量 pubdate=最新 dm=弹幕
         days: 只看最近几天发布的（0=不限）
+        page: 搜索页码，1至50，默认1；同一关键词可翻下一页找新候选
     
     Returns:
         JSON格式的视频列表，包含标题、BV号、播放量、评论数、UP主、发布时间等
     """
     from datetime import datetime
 
+    if type(page) is not int or not 1 <= page <= 50:
+        return json.dumps({"ok": False, "error": "page 需要1至50之间的整数"}, ensure_ascii=False)
+
     def _pubdate_str(ts) -> str:
         """unix 秒 → 本地时区 YYYY-MM-DD；拿不到给空串。"""
         try:
@@ -517,7 +555,7 @@ async def bili_search(keyword: str, num: int = 10, order: str = "totalrank", day
     result = await search.search_by_type(
         keyword=keyword,
         search_type=search.SearchObjectType.VIDEO,
-        page=1,
+        page=page,
         order_type=order_enum,
     )
 
@@ -558,7 +596,29 @@ async def bili_search(keyword: str, num: int = 10, order: str = "totalrank", day
             videos = videos[:min(num, 5)]
             hint = f"近 {days} 天没有匹配的，下面是综合排序的兜底结果"
 
-    out = {"keyword": keyword, "count": len(videos), "days": days, "videos": videos}
+    def _count(value):
+        if isinstance(value, bool):
+            return None
+        if isinstance(value, int) and value >= 0:
+            return value
+        if isinstance(value, str) and value.isdigit():
+            return int(value)
+        return None
+
+    # Do not infer exhaustion from our num/date filtering or a short result list.
+    # Unknown platform pagination remains null rather than claiming another page exists.
+    total_pages = _count(result.get("numPages"))
+    total_results = _count(result.get("numResults"))
+    page_size = _count(result.get("pagesize", result.get("page_size")))
+    has_more = None
+    if total_pages is not None:
+        has_more = page < min(total_pages, 50)
+    elif total_results == 0:
+        has_more = False
+    elif total_results is not None and page_size:
+        has_more = page < 50 and page * page_size < total_results
+    out = {"keyword": keyword, "count": len(videos), "days": days, "page": page,
+           "has_more": has_more, "videos": videos}
     if filtered_out_all:
         out["filtered_out_all"] = True
         out["hint"] = hint
@@ -758,6 +818,31 @@ async def _fetch_subtitle(bvid: str, with_time: bool = False) -> str:
     return json.dumps(stringify_ids(out), ensure_ascii=False)
 
 
+def _subtitle_view(payload, with_time, *, cached=False):
+    """Render both timestamp modes from the same cached, public source snapshot."""
+    out = dict(payload)
+    segments = payload.get("segments_detail")
+    if isinstance(segments, list) and segments:
+        text = []
+        for item in segments:
+            content = str(item.get("s") or "") if isinstance(item, dict) else ""
+            if not content.strip():
+                continue
+            try:
+                second = max(0.0, float(item.get("t") or 0))
+            except (TypeError, ValueError):
+                second = 0.0
+            prefix = f"[{int(second // 60):02d}:{second % 60:04.1f}] " if with_time else ""
+            text.append(prefix + content)
+        out["text"] = "\n".join(text)
+    if not with_time:
+        out.pop("segments_detail", None)
+    out.update(cached=cached, seen_recorded=not cached, already_seen=cached)
+    if cached:
+        out["hint"] = "这是上次实际取得的字幕快照，可补查时间点；不会重复抓取或增加新看片数。"
+    return out
+
+
 @tool()
 async def bili_subtitle(bvid: str, with_time: bool = False) -> str:
     """
@@ -769,18 +854,28 @@ async def bili_subtitle(bvid: str, with_time: bool = False) -> str:
 
     Returns:
         视频的完整字幕文本（含 duration；with_time=True 时含时间戳与分段时间轴）。
-        ⭐ 永久账本里已有这条 ⇒ 直接返回 already_seen=true，**不再花一次网络请求**。
+        已读视频优先返回本地字幕快照，可补查时间点；缺少快照时取一次原文。
+        永久历史只用于选片去重，读请求仍有跨进程单飞租约。
     """
     guard = _get_runtime_guard()
     try:
-        reservation = guard.reserve_read(bvid)
+        cached = guard.cached_subtitle(bvid)
+        if cached is not None:
+            return json.dumps(_subtitle_view(cached, with_time, cached=True), ensure_ascii=False)
+        reservation = guard.reserve_subtitle(bvid)
     except Exception as e:
         return json.dumps({"error": f"判重账本不可用，先不抓字幕：{e}"}, ensure_ascii=False)
     if not reservation.get("allowed"):
         return _guard_blocked(reservation, "read")
 
     try:
-        raw = await asyncio.wait_for(_fetch_subtitle(bvid, with_time), timeout=READ_TIMEOUT_SECONDS)
+        # Another reader may have published between our first cache lookup and this lease.
+        cached = guard.cached_subtitle(bvid)
+        if cached is not None:
+            guard.release(reservation)
+            return json.dumps(_subtitle_view(cached, with_time, cached=True), ensure_ascii=False)
+        # Always keep the timeline so a later with_time=True needs no second network read.
+        raw = await asyncio.wait_for(_fetch_subtitle(bvid, True), timeout=READ_TIMEOUT_SECONDS)
     except BaseException:
         # 读是幂等的：超时 / 出错都该把坑退掉，下次还能重试
         guard.release(reservation)
@@ -805,9 +900,15 @@ async def bili_subtitle(bvid: str, with_time: bool = False) -> str:
         guard.release(reservation)
         return json.dumps(payload, ensure_ascii=False)
 
-    guard.commit_read(reservation, {"bvid": bvid, "title": payload.get("title", "")})
-    payload["seen_recorded"] = True
-    return json.dumps(payload, ensure_ascii=False)
+    payload["bvid"] = bvid
+    try:
+        stored = guard.commit_subtitle(reservation, payload)
+    except Exception:
+        guard.release(reservation)
+        raise
+    out = _subtitle_view(payload, with_time)
+    out["cache_stored"] = stored
+    return json.dumps(out, ensure_ascii=False)
 
 
 # ========== Tool 4: 获取弹幕 ==========
@@ -992,13 +1093,17 @@ async def bili_reply(bvid: str, text: str, rpid: IdInput = "0", root: IdInput =
                            "guard_status": "not_sent", "retry_blocked": False}, ensure_ascii=False)
 
     # ② 占坑：同一条评论（rpid）全机器只允许发一次；新评论按 BV 也只允许留一条
-    guard = _get_runtime_guard()
     try:
         key = key_video_reply(bvid, rpid)
     except Exception as e:
         return json.dumps({"success": False, "error": str(e),
                            "guard_status": "not_sent", "retry_blocked": False}, ensure_ascii=False)
-    reservation = guard.reserve_send(key, cross_channel_keys(rpid))
+    try:
+        guard = _get_runtime_guard()
+        # P3-46: SQLite busy>15s 的原始异常不能外泄 —— 包成 fail-closed JSON 回执
+        reservation = guard.reserve_send(key, cross_channel_keys(rpid))
+    except Exception as e:
+        return _guard_unavailable(e)
     if not reservation.get("allowed"):
         return _guard_blocked(reservation, "send",
                               "这条评论已经回过了" if rpid != "0" else "这条视频已经留过一条评论了")
@@ -1052,7 +1157,7 @@ async def bili_reply(bvid: str, text: str, rpid: IdInput = "0", root: IdInput =
     # ④ 把回执里的 rpid 带回去：判重表要靠它记「我们发过哪条」，宿主的评论复核
     #    （lib/verify.mjs）也要拿它去 B站 查公开可见性。只回 success 的话那条链是断的。
     result = outcome["result"]
-    out = {"success": True, "message": "评论发送成功", "guard_status": "sent"}
+    out = {"success": True, "message": "评论发送成功", "guard_status": "sent", "pace_token": outcome["pace_token"]}
     if isinstance(result, dict):
         for name in ("rpid", "rpid_str", "root", "parent"):
             val = result.get(name)
@@ -1193,10 +1298,14 @@ async def bili_send_dynamic(
 
     text = text.strip()
     image_paths = [str(path).strip() for path in (images or [])[:9] if str(path or "").strip()]
-    guard = _get_runtime_guard()
-    reservation = guard.reserve_send(key_moment("dynamic", {
-        "text": text, "images": image_paths, "topic_id": str(topic_id), "schedule_time": schedule_time,
-    }))
+    try:
+        guard = _get_runtime_guard()
+        # P3-46: 占坑异常包成 fail-closed JSON，原始 traceback 不外泄
+        reservation = guard.reserve_send(key_moment("dynamic", {
+            "text": text, "images": image_paths, "topic_id": str(topic_id), "schedule_time": schedule_time,
+        }))
+    except Exception as exc:
+        return _guard_unavailable(exc)
     if not reservation["allowed"]:
         return _guard_blocked(reservation)
     try:
@@ -1235,6 +1344,7 @@ async def bili_send_dynamic(
         return json.dumps(payload, ensure_ascii=False)
     result = outcome["result"]
     return json.dumps({"success": True, "message": "动态发布成功", "guard_status": "sent",
+                       "pace_token": outcome["pace_token"],
                        "data": stringify_ids(result) if isinstance(result, dict) else str(result)}, ensure_ascii=False)
 
 
@@ -1272,6 +1382,7 @@ async def bili_upload_video(
 
     Returns:
         上传结果，包含BV号
+    ⚠️ 直跑无判重账本与节奏闸——仅限手动运行，自动化请走插件的 bili_pv（P2-17）
     """
     # ---- 参数校验 ----
     if not video_path or not video_path.strip():
@@ -1333,12 +1444,20 @@ async def bili_upload_video(
         async def on_event(data: dict):
             progress_info["phase"] = str(data)
 
-        result = await uploader.start()
+        # P2-17: uploader.start() 没有超时的话，挂死的上传在客户端超时后仍在后台继续，
+        # 公开投稿完成却无任何记录 —— 这里给 15 分钟墙钟，超时明确报错。
+        result = await asyncio.wait_for(uploader.start(), timeout=900)
         return json.dumps({
             "success": True,
             "message": "视频上传成功",
             "data": result if isinstance(result, dict) else str(result),
         }, ensure_ascii=False)
+    except asyncio.TimeoutError:
+        return json.dumps({
+            "success": False,
+            "error": "投稿上传超时（15 分钟）——网络或 B站 分片接口卡住；注意客户端超时后上传可能仍在后台进行，重试前先到创作中心确认有没有半截投稿",
+            "last_phase": progress_info.get("phase", "unknown") if "progress_info" in dir() else "init",
+        }, ensure_ascii=False)
     except Exception as e:
         return json.dumps({
             "success": False,
@@ -1375,6 +1494,7 @@ async def bili_upload_video_multi(
 
     Returns:
         上传结果
+    ⚠️ 直跑无判重账本与节奏闸——仅限手动运行，自动化请走插件的 bili_pv（P2-17）
     """
     cred = get_cred()
 
@@ -1418,12 +1538,18 @@ async def bili_upload_video_multi(
 
         uploader = VideoUploader(pages=pages, meta=meta, credential=cred)
 
-        result = await uploader.start()
+        # P2-17: 同 bili_upload_video —— 15 分钟墙钟，挂死的上传不能在后台无人知晓地继续
+        result = await asyncio.wait_for(uploader.start(), timeout=900)
         return json.dumps({
             "success": True,
             "message": f"多P视频上传成功（共{len(pages)}P）",
             "data": result if isinstance(result, dict) else str(result),
         }, ensure_ascii=False)
+    except asyncio.TimeoutError:
+        return json.dumps({
+            "success": False,
+            "error": "投稿上传超时（15 分钟）——网络或 B站 分片接口卡住；注意客户端超时后上传可能仍在后台进行，重试前先到创作中心确认有没有半截投稿",
+        }, ensure_ascii=False)
     except Exception as e:
         return json.dumps({"success": False, "error": str(e)}, ensure_ascii=False)
 
@@ -1450,10 +1576,14 @@ async def bili_send_opus(
         发布结果
     """
     image_paths = [str(path).strip() for path in (images or []) if str(path or "").strip()]
-    guard = _get_runtime_guard()
-    reservation = guard.reserve_send(key_moment("opus", {
-        "title": title, "content": content, "images": image_paths, "category_id": str(category_id),
-    }))
+    try:
+        guard = _get_runtime_guard()
+        # P3-46: 占坑异常包成 fail-closed JSON，原始 traceback 不外泄
+        reservation = guard.reserve_send(key_moment("opus", {
+            "title": title, "content": content, "images": image_paths, "category_id": str(category_id),
+        }))
+    except Exception as exc:
+        return _guard_unavailable(exc)
     if not reservation["allowed"]:
         return _guard_blocked(reservation)
     try:
@@ -1487,6 +1617,7 @@ async def bili_send_opus(
         return json.dumps(payload, ensure_ascii=False)
     result = outcome["result"]
     return json.dumps({"success": True, "message": "图文发布成功", "guard_status": "sent",
+                       "pace_token": outcome["pace_token"],
                        "data": stringify_ids(result) if isinstance(result, dict) else str(result)}, ensure_ascii=False)
 
 
@@ -1798,11 +1929,14 @@ async def bili_favorite_lists(uid: int = 0) -> str:
     """
     cred = get_cred()
     if uid == 0:
-        # 从凭证获取自己的UID
-        import json as _json
-        with open(CRED_FILE) as f:
-            data = _json.load(f)
-        uid = int(data.get("dedeuserid", 0))
+        # 从凭证获取自己的UID（P3-43: 改走硬化的 load_credential —— 原来裸 open 读凭证文件，
+        # dedeuserid 空串 → ValueError、文件中途被删 → FileNotFoundError，整工具裸 traceback）
+        own = load_credential()
+        dede = str(own.dedeuserid).strip() if own else ""
+        if not dede.isdigit():
+            return json.dumps({"error": "未登录或凭证不可读：拿不到自己的 UID（dedeuserid 为空或缺失），"
+                                        "请先调用 bili_login 重新扫码登录"}, ensure_ascii=False)
+        uid = int(dede)
 
     result = await favorite_list.get_video_favorite_list(uid=uid, credential=cred)
     fav_lists = []
@@ -1890,13 +2024,17 @@ async def bili_send_message(receiver_uid: IdInput, text: str, msg_seqno: IdInput
         return json.dumps({"success": False, "error": str(e),
                            "guard_status": "not_sent", "retry_blocked": False}, ensure_ascii=False)
 
-    guard = _get_runtime_guard()
     try:
         key = key_dm_reply(receiver_uid, body, msg_seqno)
     except Exception as e:
         return json.dumps({"success": False, "error": str(e),
                            "guard_status": "not_sent", "retry_blocked": False}, ensure_ascii=False)
-    reservation = guard.reserve_send(key, legacy_dm_keys(msg_seqno))
+    try:
+        guard = _get_runtime_guard()
+        # P3-46: 占坑异常（含账本库打不开）包成 fail-closed JSON，原始 traceback 不外泄
+        reservation = guard.reserve_send(key, legacy_dm_keys(msg_seqno))
+    except Exception as e:
+        return _guard_unavailable(e)
     if not reservation.get("allowed"):
         return _guard_blocked(reservation, "send", f"这条私信已经回过了（UID:{receiver_uid}）")
 
@@ -1929,6 +2067,7 @@ async def bili_send_message(receiver_uid: IdInput, text: str, msg_seqno: IdInput
         "success": True,
         "message": f"私信已发送给UID:{receiver_uid}",
         "guard_status": "sent",
+        "pace_token": outcome["pace_token"],
         "data": result if isinstance(result, dict) else str(result),
     }, ensure_ascii=False)
 
@@ -2483,7 +2622,6 @@ async def bili_reply_opus(opus_id: IdInput, text: str, rpid: IdInput = "0", root
         return json.dumps({"success": False, "error": f"取不到这条动态的评论区：{e}",
                            "guard_status": "not_sent", "retry_blocked": False}, ensure_ascii=False)
 
-    guard = _get_runtime_guard()
     try:
         key = key_opus_reply(oid_str, rpid)
     except Exception as e:
@@ -2493,7 +2631,12 @@ async def bili_reply_opus(opus_id: IdInput, text: str, rpid: IdInput = "0", root
     # 否则升级那一刻，昨天回过的那些今天会再回一遍。
     # 🔁 2026-10-25（使用者报「回一个人一条评论两条消息」）：**视频通道回过的同号 rpid 也认**
     #    —— 同一条评论只回一次，不管上一次走的是 bili_reply 还是 bili_reply_opus。
-    reservation = guard.reserve_send(key, [*legacy_opus_keys(rpid, root), *cross_channel_keys(rpid)])
+    try:
+        guard = _get_runtime_guard()
+        # P3-46: 占坑异常（含账本库打不开）包成 fail-closed JSON，原始 traceback 不外泄
+        reservation = guard.reserve_send(key, [*legacy_opus_keys(rpid, root), *cross_channel_keys(rpid)])
+    except Exception as e:
+        return _guard_unavailable(e)
     if not reservation.get("allowed"):
         return _guard_blocked(reservation, "send", "这条动态评论已经回过了")
 
@@ -2527,6 +2670,7 @@ async def bili_reply_opus(opus_id: IdInput, text: str, rpid: IdInput = "0", root
     # ⭐ opus_id 一律回字符串（JS 侧 1e18 这一档 number 必掉精度，账本键会错）
     result = outcome["result"]
     out = {"success": True, "message": "动态评论回复成功", "guard_status": "sent",
+           "pace_token": outcome["pace_token"],
            "opus_id": oid_str, "oid": str(tgt["oid"]), "ctype": tgt["ctype"]}
     if isinstance(result, dict):
         for name in ("rpid", "rpid_str", "root", "parent"):
@@ -2689,27 +2833,40 @@ async def bili_my_video_comments(num: int = 10, videos: int = 3) -> str:
 # ========== Tool: 判重账本状态（只读） ==========
 
 @tool()
-async def bili_guard_status(bvids: list = None, limit: int = 200) -> str:
+async def bili_guard_status(bvids: list = None, limit: int = 200, release: list = None) -> str:
     """
     看一眼**永久判重账本**（SQLite，重启不丢、跨进程共用）
 
     Args:
         bvids: 想核对的 BV 号列表（给了就只查这几条；不给就返回最近刷过的一批）
         limit: 最多返回几条（默认 200，上限 500）
+        release: 【unknown 槽位的人工解除入口】要解除的坑位 key 列表。只在人工核实
+                 「那次结果不明的发送确实没发出去」之后才用 —— 只有 status='unknown'
+                 的行会被删（pending/sent 绝不碰）；非空时本工具不再纯只读。
 
     Returns:
         counts（seen / sent / pending / unknown 各多少）、seenVideos（已刷过的 BV）、
-        activeReads（正在读的）、recentSends（最近发过什么 —— 只有键和元信息，**不含正文**）
+        activeReads（正在读的）、recentSends（最近发过什么 —— 只有键和元信息，**不含正文**）；
+        传了 release 时额外带 released：每个 key 是否真的解除了一行
     """
     guard = _get_runtime_guard()
+    released = []
+    if release:
+        # P1-2: unknown 槽位的人工解除入口 —— release_unknown 只删 unknown 行，
+        # 误传 pending/sent 的 key 时返回 false 并原样保留那行，绝不误删。
+        for key in release:
+            try:
+                released.append({"key": str(key), "released": bool(guard.release_unknown(str(key)))})
+            except Exception as e:
+                released.append({"key": str(key), "released": False, "error": str(e)})
     try:
         data = guard.snapshot(bvids=bvids, limit=limit)
     except Exception as e:
-        return json.dumps({"ok": False, "error": str(e)}, ensure_ascii=False)
-    return json.dumps({"ok": True, **data}, ensure_ascii=False)
+        return json.dumps({"ok": False, "error": str(e), "released": released}, ensure_ascii=False)
+    return json.dumps({"ok": True, "released": released, **data}, ensure_ascii=False)
 
 
 # ========== 启动 ==========
 
 if __name__ == "__main__":
-    mcp.run(transport="stdio")
+    mcp.run(transport="stdio")