dsh-shlr-bilitoolkit 0.1.9 → 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

@@ -75,10 +75,12 @@ const [ups, _] = await client.space.videos(574115689, 1, 10);
   - 写操作：`bili_like` / `bili_follow` / `bili_favorite` / `bili_send_comment` / `bili_send_message` / `bili_triple` / `bili_dynamic_publish` / `bili_dynamic_repost` / `bili_coin` / `bili_unfavorite` / `bili_fav_folder_create` / `bili_fav_folder_delete` / `bili_dynamic_like` / `bili_dynamic_delete` / `bili_comment_send` / `bili_comment_reply` / `bili_comment_delete` / `bili_message_recall` / `bili_profile_update_sign` / `bili_profile_update`（均会真实修改账号状态，需登录）
   - 辅助：`bili_login_status`（查登录态）/ `bili_gen_qr`（生成扫码登录二维码）/ `bili_cache_clear`（清空本地缓存）
 - 工具读取 `BILI_COOKIE_FILE`（默认 `bili_data/bili_cookies.json`）作为登录态。
-- **数据目录**：Cookie / 缓存 / 二维码统一放在一个目录里，默认 `bili_data/`（相对 dsh 工作目录），避免散落污染工作目录。可用 `BILI_DATA_DIR` 改目录；`BILI_COOKIE_FILE` / `BILI_CACHE_FILE` / `BILI_QR_FILE` 可精确指定单个文件。兼容旧版：若新目录还没有 Cookie、而旧位置（`./bili_cookies.json`）有，会继续沿用旧的。
+- **数据目录**：Cookie / 缓存 / 二维码 / 设备号统一放在一个目录里，默认 `bili_data/`（相对 dsh 工作目录），避免散落污染工作目录。可用 `BILI_DATA_DIR` 改目录；`BILI_COOKIE_FILE` / `BILI_CACHE_FILE` / `BILI_QR_FILE` / `BILI_DEVICE_FILE` 可精确指定单个文件。设备号（私信 `dev_id`）会落盘到 `bili_data/bili_device.json`，跨重启保持稳定，避免被 B 站当成新设备触发风控。兼容旧版：若新目录还没有 Cookie、而旧位置（`./bili_cookies.json`）有，会继续沿用旧的。
 - **扫码登录（独立获取 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/apis/message.d.ts

@@ -6,6 +6,13 @@ web 端私信要求带一个 UUID 形式的 msg[dev_id]；同一 client 实例
 import type { BiliClient } from "../client.js";
 import { PrivateMessage } from "../models.js";
 export declare function generateDevId(): string;
+/** 读取或生成一个稳定的设备号（dev_id）并落盘。
+ *
+ * B 站私信要求带设备号；同一设备应保持稳定，频繁变化易被判定为异常 / 触发风控。
+ * 传入文件路径时：存在则读取（JSON `{ devId }` 或 JSON 字符串），否则生成并写入；
+ * 读取 / 解析失败则重新生成并覆盖。不传路径时退化为内存生成（不落盘）。
+ */
+export declare function resolveDevId(file?: string): string;
 export declare class MessageAPI {
     private client;
     constructor(client: BiliClient, devId?: string);

package/dist/apis/message.js

@@ -4,6 +4,8 @@ web 端私信要求带一个 UUID 形式的 msg[dev_id]；同一 client 实例
 避免每次都被当成新设备。dev_id 生成本次会话内稳定即可（不落盘）。
 */
 import { randomInt } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import * as endpoints from "../endpoints.js";
 import { BiliApiError, CookieError } from "../errors.js";
 import { PrivateMessage } from "../models.js";
@@ -28,6 +30,39 @@ export function generateDevId() {
     }
     return out;
 }
+/** 读取或生成一个稳定的设备号（dev_id）并落盘。
+ *
+ * B 站私信要求带设备号；同一设备应保持稳定，频繁变化易被判定为异常 / 触发风控。
+ * 传入文件路径时：存在则读取（JSON `{ devId }` 或 JSON 字符串），否则生成并写入；
+ * 读取 / 解析失败则重新生成并覆盖。不传路径时退化为内存生成（不落盘）。
+ */
+export function resolveDevId(file) {
+    if (!file)
+        return generateDevId();
+    try {
+        if (existsSync(file)) {
+            const text = readFileSync(file, "utf-8").trim();
+            if (text) {
+                const parsed = JSON.parse(text);
+                const id = typeof parsed === "string" ? parsed : parsed?.devId;
+                if (typeof id === "string" && id.trim())
+                    return id.trim();
+            }
+        }
+    }
+    catch {
+        // 读取 / 解析失败 → 重新生成并覆盖
+    }
+    const id = generateDevId();
+    try {
+        mkdirSync(dirname(resolve(file)), { recursive: true });
+        writeFileSync(file, JSON.stringify({ devId: id }, null, 2), "utf-8");
+    }
+    catch {
+        // 只读 / 无权限：忽略，仍返回内存 id
+    }
+    return id;
+}
 export class MessageAPI {
     client;
     constructor(client, devId) {

package/dist/client.d.ts

@@ -28,6 +28,7 @@ export declare const DEFAULT_HEADERS: Record<string, string>;
 export interface BiliClientOptions {
     cookieFile?: string;
     cacheFile?: string;
+    deviceFile?: string;
     timeout?: number;
     minInterval?: number;
     jitter?: number;

package/dist/client.js

@@ -18,7 +18,7 @@ import { VideoAPI } from "./apis/video.js";
 import { SearchAPI } from "./apis/search.js";
 import { SpaceAPI } from "./apis/space.js";
 import { CommentAPI } from "./apis/comment.js";
-import { MessageAPI } from "./apis/message.js";
+import { MessageAPI, resolveDevId } from "./apis/message.js";
 import { NotifyAPI } from "./apis/notify.js";
 import { InteractAPI } from "./apis/interact.js";
 import { RelationAPI } from "./apis/relation.js";
@@ -77,7 +77,7 @@ export class BiliClient {
         this.search = new SearchAPI(this);
         this.space = new SpaceAPI(this);
         this.comment = new CommentAPI(this);
-        this.message = new MessageAPI(this);
+        this.message = new MessageAPI(this, resolveDevId(opts.deviceFile ?? "bili_device.json"));
         this.notify = new NotifyAPI(this);
         this.interact = new InteractAPI(this);
         this.relation = new RelationAPI(this);

package/dist/dsh.js

@@ -43,6 +43,7 @@ async function getClient() {
         cached = new BiliClient({
             cookieFile: resolveCookieFile(),
             cacheFile: process.env.BILI_CACHE_FILE ?? resolve(dataDir(), "bili_cache.json"),
+            deviceFile: process.env.BILI_DEVICE_FILE ?? resolve(dataDir(), "bili_device.json"),
         });
         // 没有 Cookie 文件（或为空 / 损坏）= 未登录（匿名）。
         // 不能因此让所有工具崩掉——公开接口、以及最关键的扫码登录入口都依赖这里。
@@ -961,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();
@@ -1010,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.9",
+  "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",