dsh-shlr-bilitoolkit 0.1.10 → 0.1.11

package/AGENTS.md

@@ -0,0 +1,43 @@
+# AGENTS.md — dsh-bili-toolkit 使用约定（Agent 必读）
+
+> 本文件面向使用本插件的 agent。**处理任何「B 站登录」相关请求前，必须先读这里，并按下面的规则执行。**
+
+## 登录（最重要，务必遵守）
+
+当用户说「登录 B 站」「扫码登录」「登陆一下」，或任何需要登录的操作返回未登录
+（业务码 `-101` / `CookieError` / 提示「未登录 / 请先登录」）时，按顺序做：
+
+1. **必须调用 `bili_gen_qr`** —— 这是登录 B 站的唯一入口。它会返回二维码图片：
+   `qrDataUrl`（base64 data URL）、`qrImageUrl`（`file://` 链接）、`qrImagePath`（本地 PNG 绝对路径）。
+2. **必须把二维码图片原样展示给用户**：用 Markdown 图片 `![B站登录二维码](<qrDataUrl>)`
+   （或引用 `qrImageUrl` / `qrImagePath`），让用户能直接扫。
+3. 提示用户用「哔哩哔哩」App 扫描该二维码，并在手机上点「确认登录」。
+4. 用户确认后，调用 `bili_login_status` 轮询确认——成功后会自动把 Cookie 保存到
+   `bili_data/bili_cookies.json`。
+
+**禁止事项：**
+- 不要用 ASCII / 文本二维码代替图片。
+- 不要只扔一个链接给用户、不展示图片。
+- 不要让用户自己去终端跑 `npm run login`（除非明确处于终端 / CLI 环境）。
+- 不要在未展示二维码的情况下就回复「请登录」。
+
+## 数据位置
+
+统一放在数据目录（默认 `bili_data/`，相对 dsh 工作目录，可用 `BILI_DATA_DIR` 改）：
+
+| 文件 | 用途 |
+| --- | --- |
+| `bili_cookies.json` | 登录 Cookie（SESSDATA / bili_jct） |
+| `bili_cache.json` | WBI 签名密钥 + bvid→aid 缓存 |
+| `bili_qrcode.png` | 最近一次生成的登录二维码 |
+| `bili_device.json` | 私信设备号 dev_id（跨重启稳定，勿频繁变动） |
+
+## 写操作需确认
+
+点赞 / 收藏 / 投币 / 关注 / 评论 / 私信 / 三连 / 发动态 / 改资料等会**真实修改账号状态**，
+执行前应先与用户确认。投币不可退回。
+
+## 遇到签名失效
+
+若请求报 `-403` / `-352`（WBI 签名失效），可调用 `bili_cache_clear` 清空缓存后重试；
+不影响 Cookie / 登录态。

package/README.md

@@ -79,6 +79,8 @@ const [ups, _] = await client.space.videos(574115689, 1, 10);
 - **扫码登录（独立获取 Cookie）**：运行 `npm run login`，终端会打印 ASCII 二维码，用「哔哩哔哩」App 扫码并确认后，Cookie 自动写入 `bili_data/bili_cookies.json`。也可在对话里先调 `bili_login_status` 查登录态、调 `bili_gen_qr` 拿二维码链接与可直接展示的 `ascii` 二维码。写操作（点赞 / 收藏 / 投币 / 关注 / 评论 / 私信 / 三连）都依赖该 Cookie 中的 `SESSDATA` / `bili_jct`。
 - **缓存持久化**：除 Cookie 外，客户端还会把 WBI 签名密钥（`B 站每天轮换`）、`bvid→aid` 映射这类稳定 / 带 TTL 的数据写入本地 JSON 缓存（`BILI_CACHE_FILE`，默认 `bili_data/bili_cache.json`），用临时文件 + 原子替换落盘、文件损坏会自动自愈。冷启动或跨进程时直接复用，避免每次都请求 `nav` 接口；密钥过期或失效时 `refresh()` 会重新拉取并覆盖缓存。若签名反复报 `-403/-352`，可调用 `bili_cache_clear` 强制清空缓存后重试（不影响 Cookie / 登录态）。
 
+> **给 Agent 的约定**：仓库根目录的 [`AGENTS.md`](./AGENTS.md) 写明了登录流程——需要登录时必须调用 `bili_gen_qr` 并把二维码**图片**展示给用户，而不是只给链接或 ASCII。把这份 `AGENTS.md` 放到 dsh 的工作目录（或确保你的 dsh 会读取它），agent 就会按约定输出登录二维码。
+
 安装到 dsh（任选其一，取决于你的发行方式）：
 
 ```bash

package/dist/dsh.js

@@ -962,7 +962,7 @@ export const TOOLS = [
     // ---- 登录状态 ----
     {
         id: "bili_login_status",
-        description: "查询当前是否已登录 B 站（返回用户名）。若此前调用过 bili_gen_qr，本工具会顺带轮询扫码状态：用户扫码并在手机确认后，这里返回登录成功并自动保存 Cookie。",
+        description: "查询当前是否已登录 B 站（返回用户名）。【用户想登录、或任何需登录操作报未登录（-101/CookieError）时，先调用本工具】；若返回未登录，必须立即调用 bili_gen_qr 向用户展示登录二维码图片。若此前调用过 bili_gen_qr，本工具会顺带轮询扫码状态：用户扫码并在手机确认后，返回登录成功并自动保存 Cookie。",
         parameters: { type: "object", properties: {} },
         handler: async () => {
             const c = await getClient();
@@ -1011,7 +1011,7 @@ export const TOOLS = [
     },
     {
         id: "bili_gen_qr",
-        description: "生成 B 站扫码登录二维码图片。返回二维码内容链接 url、轮询用的 qrcodeKey，以及可供 dsh 自行获取/渲染的二维码图片：qrDataUrl（base64 data URL）、qrImageUrl（file:// 链接）、qrImagePath（本地 PNG 绝对路径）。用户扫码确认后，调用 bili_login_status 完成登录并保存 Cookie。",
+        description: "【B 站登录唯一入口】生成 B 站扫码登录二维码图片。调用后必须把返回的二维码图片展示给用户扫码（用 qrDataUrl / qrImageUrl / qrImagePath 渲染成图片），不要只给链接、不要让用户手动跑命令。返回：url（二维码内容链接）、qrcodeKey（轮询用）、qrDataUrl（base64 data URL）、qrImageUrl（file:// 链接）、qrImagePath（本地 PNG 绝对路径）。用户扫码确认后，调用 bili_login_status 完成登录并保存 Cookie。",
         parameters: { type: "object", properties: {} },
         handler: async () => {
             const c = await getClient();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-shlr-bilitoolkit",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "深海猎人专用B站接口工具箱 dsh 插件。",
   "type": "module",
   "main": "dist/dsh.js",
@@ -11,7 +11,8 @@
   },
   "files": [
     "dist",
-    "cordis.patch.yml"
+    "cordis.patch.yml",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",