dsh-shlr-bilitoolkit 0.1.14 → 0.1.16

package/README.md

@@ -0,0 +1,98 @@
+# dsh-shlr-bilitoolkit
+
+B 站（哔哩哔哩）接口封装的 **TypeScript** 移植版，作为 [dsh](https://dshmp.com)（DeepSeek Harness）插件提供「视频 / 搜索 / 空间 / 专栏 / 动态 / 评论 / 关注 / 消息中心」等读取能力，以及点赞、收藏、投币、关注、评论、私信、三连、发动态等写操作。
+
+> 本项目从原 Python 工具箱（`bili/`）完整移植而来，并作为 dsh（cordis 体系）插件提供上述能力。
+
+## 安装
+
+```bash
+# 已发布到 npm
+dsh plugin --profile <name> add dsh-shlr-bilitoolkit@latest
+
+# 本地开发 / 试运行
+npm install
+npm run build
+```
+
+本地登录（独立获取 Cookie，终端打印 ASCII 二维码）：
+
+```bash
+npm install && npm run login
+# 或指定 Cookie 文件
+BILI_COOKIE_FILE=./my_cookies.json npm run login
+```
+
+## 插件入口
+
+对齐官方 cordis 规范：`src/dsh.ts` 导出 `name` / `inject = ["tools"]` / `apply(ctx)`，在 `apply` 内用官方 `ctx.tools.register(defineTool({ name, description, parameters, output, execute }))` 注册每个工具。`defineTool` 来自 `@deepseek-ai/dsh-tools`，由宿主提供、插件不打包（保证单实例），已在 `peerDependencies` 声明。`cordis.patch.yml` 为组合包配置层（`- insert: - id: bili  name: dsh-shlr-bilitoolkit`，按包名解析到 `main`）。较旧、没有 `ctx.tools` 的 dsh 仍保留 `ctx.registerTool` / `ctx.services.tools.register` 回退。
+
+## 工具清单
+
+同类能力已用参数合并（`type` / `target` / `action` / `list`），**功能未减少**。
+
+- **读取**：
+  `bili_recommend` · `bili_video_detail` · `bili_video_subtitle` · `bili_search` · `bili_space_info` · `bili_space_videos` · `bili_article_view` · `bili_article_list` · `bili_dynamic_feed` · `bili_dynamic_space` · `bili_comment_list` · `bili_relation_list` · `bili_notify_unread` · `bili_notify_list` · `bili_fav_folders` · `bili_video_pagelist` · `bili_video_playurl` · `bili_video_status` · `bili_space_collections` · `bili_space_collection` · `bili_fav_folder_videos` · `bili_dynamic_detail` · `bili_message_unread` · `bili_message_history` · `bili_relation_stat` · `bili_user_following` · `bili_profile_info` · `bili_comment_replies`
+- **写操作**（均会真实修改账号状态，需登录）：
+  `bili_like` · `bili_follow` · `bili_favorite` · `bili_send_message` · `bili_triple` · `bili_dynamic_publish` · `bili_dynamic_repost` · `bili_coin` · `bili_fav_folder_create` · `bili_fav_folder_delete` · `bili_dynamic_like` · `bili_dynamic_delete` · `bili_comment_send` · `bili_comment_reply` · `bili_comment_delete` · `bili_comment_like` · `bili_message_recall` · `bili_profile_update`
+- **辅助**：`bili_login_status`（查登录态）· `bili_gen_qr`（生成登录二维码）· `bili_cache_clear`（清空本地缓存）
+
+合并工具的公共参数约定：
+
+| 工具 | 参数 |
+| --- | --- |
+| `bili_search` | `type=video\|user`，`order`（仅视频） |
+| `bili_relation_list` | `type=followings\|followers` |
+| `bili_notify_list` | `type=replies\|ats\|likes` |
+| `bili_favorite` | `action=add\|remove` |
+| `bili_video_subtitle` | `list=true` 时列字幕轨，否则取正文 |
+| `bili_comment_*` | `target=video\|dynamic\|article`，`id`（bvid / 动态 id / 专栏 cv 号） |
+| `bili_profile_update` | `uname` / `sex` / `birthday` / `sign`（至少一项） |
+
+## 数据目录
+
+Cookie / 缓存 / 二维码 / 设备号统一放在一个目录，默认 `bili_data/`（相对 dsh 工作目录），避免散落污染工作目录：
+
+| 文件 | 用途 |
+| --- | --- |
+| `bili_cookies.json` | 登录 Cookie（`SESSDATA` / `bili_jct`） |
+| `bili_cache.json` | WBI 签名密钥 + `bvid→aid` 缓存（原子写、损坏自愈） |
+| `bili_qrcode.png` | 最近一次生成的登录二维码 |
+| `bili_device.json` | 私信设备号 `dev_id`（跨重启稳定，降低风控） |
+
+可用环境变量：`BILI_DATA_DIR`（改目录）、`BILI_COOKIE_FILE` / `BILI_CACHE_FILE` / `BILI_QR_FILE` / `BILI_DEVICE_FILE`（精确指定单个文件）。兼容旧版：若新目录还没有 Cookie、而旧位置 `./bili_cookies.json` 有，会继续沿用。
+
+## 给 Agent 的约定
+
+仓库根目录的 [`AGENTS.md`](./AGENTS.md) 约定：需要登录时必须调用 `bili_gen_qr` 并把二维码**图片**展示给用户（而非只给链接或 ASCII）。把该 `AGENTS.md` 放到 dsh 工作目录，agent 即会遵守。
+
+## 目录结构
+
+```
+src/
+  client.ts      BiliClient：Session / Cookie / 请求 / 节流 / 重试 / 风控 / 表单编码
+  wbi.ts         WbiSigner：w_rid / wts 签名（官方 mixin_key 算法，密钥落盘缓存 6h）
+  cache.ts       JsonCache：本地 JSON 缓存（TTL / 原子写 / 损坏自愈）
+  errors.ts      BiliApiError / CaptchaRequired / CookieError
+  models.ts      纯数据模型 + toDict()
+  formatting.ts  播放量 / 时长 / HTML 清理等展示格式化
+  pagination.ts  iterPages：统一分页异步生成器
+  endpoints.ts   所有接口 URL 常量
+  apis/          video / search / space / comment / message / interact / dynamic /
+                 article / relation / notify / profile / auth / download
+  dsh.ts         dsh 插件入口：apply(ctx) + 工具清单
+  index.ts       对外导出
+tests/           离线单测（wbi 签名、格式化、缓存、lossless JSON 等）
+cordis.patch.yml dsh 组合包配置层
+scripts/login.ts npm run login 扫码登录脚本
+```
+
+## 与原 Python 版的差异 / 已知限制
+
+- **写接口为表单编码**：`client.post` 默认把对象编码为 `application/x-www-form-urlencoded`，仅动态点赞等少数接口显式走 JSON（`jsonBody=true`）。
+- **动态仅支持纯文字**：带图 / 投票 / 预约的富动态需额外图片上传流程，暂未实现。
+- **下载 / ffmpeg**：`src/apis/download.ts` 为纯工具函数，未接入 dsh 工具。
+
+## 风控说明
+
+内置与原 Python 版一致的基础降风控策略：请求节流（默认 0.6s + 0~0.4s 抖动）、GET 退避重试、写操作不重试、HTTP 412 / `-412` 立即停手、WBI 签名。但单账号操作量上限、避免短时间切 IP/UA 等仍需使用习惯配合。设备号 `dev_id` 已落盘保持稳定。

package/dist/dsh.js

@@ -141,31 +141,38 @@ export const TOOLS = [
     },
     {
         id: "bili_video_subtitle",
-        description: "获取视频字幕纯文本（优先 AI 字幕 / 中文），用于「读取视频内容」。无字幕返回空串。",
+        description: "视频字幕：默认返回字幕纯文本（优先中文）；list=true 时返回可用字幕轨列表。",
         parameters: {
             type: "object",
             properties: {
                 bvid: { type: "string" },
                 lang: { type: "string", default: "zh" },
+                list: { type: "boolean", default: false, description: "true 则只列字幕轨，不取正文" },
             },
             required: ["bvid"],
         },
         handler: async (a) => {
             const c = await getClient();
+            if (Boolean(a.list ?? false)) {
+                const subs = await c.video.subtitles(a.bvid);
+                return subs.map((s) => s.toDict());
+            }
             return { text: await c.video.subtitleText(a.bvid, a.lang ?? "zh") };
         },
     },
     {
-        id: "bili_search_video",
-        description: "搜索 B 站视频。",
+        id: "bili_search",
+        description: "搜索 B 站视频或用户。",
         parameters: {
             type: "object",
             properties: {
                 keyword: { type: "string" },
+                type: { type: "string", enum: ["video", "user"], default: "video" },
                 order: {
                     type: "string",
                     enum: ["totalrank", "click", "pubdate", "dm", "stow", "scores"],
                     default: "totalrank",
+                    description: "排序（仅视频）",
                 },
                 pageSize: { type: "integer", default: 20 },
             },
@@ -173,27 +180,15 @@ export const TOOLS = [
         },
         handler: async (a) => {
             const c = await getClient();
-            const [videos, total] = await c.search.videos(a.keyword, 1, Number(a.pageSize ?? 20), a.order ?? "totalrank");
+            const ps = Number(a.pageSize ?? 20);
+            if (String(a.type ?? "video") === "user") {
+                const [users, total] = await c.search.users(a.keyword, 1, ps);
+                return { total, users: users.map((u) => u.toDict()) };
+            }
+            const [videos, total] = await c.search.videos(a.keyword, 1, ps, a.order ?? "totalrank");
             return { total, videos: videos.map((v) => v.toDict()) };
         },
     },
-    {
-        id: "bili_search_user",
-        description: "搜索 B 站用户。",
-        parameters: {
-            type: "object",
-            properties: {
-                keyword: { type: "string" },
-                pageSize: { type: "integer", default: 20 },
-            },
-            required: ["keyword"],
-        },
-        handler: async (a) => {
-            const c = await getClient();
-            const [users, total] = await c.search.users(a.keyword, 1, Number(a.pageSize ?? 20));
-            return { total, users: users.map((u) => u.toDict()) };
-        },
-    },
     {
         id: "bili_space_info",
         description: "获取 B 站用户空间基本信息（昵称、等级、签名）。",
@@ -291,54 +286,50 @@ export const TOOLS = [
     // ---- 评论 ----
     {
         id: "bili_comment_list",
-        description: "获取视频评论（bvid），返回评论列表与总数。",
+        description: "获取评论列表（视频 / 动态 / 专栏），返回评论列表。",
         parameters: {
             type: "object",
             properties: {
-                bvid: { type: "string" },
+                target: { type: "string", enum: ["video", "dynamic", "article"], default: "video" },
+                id: { type: "string", description: "视频 bvid / 动态 id / 专栏 cv 号" },
                 sort: { type: "string", enum: ["time", "like", "reply"], default: "time" },
                 pageSize: { type: "integer", default: 20 },
             },
-            required: ["bvid"],
+            required: ["id"],
         },
         handler: async (a) => {
             const c = await getClient();
-            const [comments, total] = await c.comment.listVideo(a.bvid, 1, Number(a.pageSize ?? 20), a.sort ?? "time");
-            return { total, comments: comments.map((x) => x.toDict()) };
+            const target = String(a.target ?? "video");
+            const ps = Number(a.pageSize ?? 20);
+            const sort = a.sort ?? "time";
+            let items;
+            if (target === "dynamic")
+                [items] = await c.comment.listDynamic(a.id, 1, ps, sort);
+            else if (target === "article")
+                [items] = await c.comment.listArticle(a.id, 1, ps, sort);
+            else
+                [items] = await c.comment.listVideo(a.id, 1, ps, sort);
+            return { comments: items.map((x) => x.toDict()) };
         },
     },
     // ---- 关注关系 ----
     {
-        id: "bili_relation_followings",
-        description: "获取某用户的关注列表。",
-        parameters: {
-            type: "object",
-            properties: {
-                uid: { type: "integer" },
-                pageSize: { type: "integer", default: 20 },
-            },
-            required: ["uid"],
-        },
-        handler: async (a) => {
-            const c = await getClient();
-            const [users, total] = await c.relation.followings(Number(a.uid), 1, Number(a.pageSize ?? 20));
-            return { total, users: users.map((x) => x.toDict()) };
-        },
-    },
-    {
-        id: "bili_relation_followers",
-        description: "获取某用户的粉丝列表。",
+        id: "bili_relation_list",
+        description: "获取某用户的关注列表或粉丝列表。",
         parameters: {
             type: "object",
             properties: {
                 uid: { type: "integer" },
+                type: { type: "string", enum: ["followings", "followers"], default: "followings" },
                 pageSize: { type: "integer", default: 20 },
             },
             required: ["uid"],
         },
         handler: async (a) => {
             const c = await getClient();
-            const [users, total] = await c.relation.followers(Number(a.uid), 1, Number(a.pageSize ?? 20));
+            const [users, total] = String(a.type ?? "followings") === "followers"
+                ? await c.relation.followers(Number(a.uid), 1, Number(a.pageSize ?? 20))
+                : await c.relation.followings(Number(a.uid), 1, Number(a.pageSize ?? 20));
             return { total, users: users.map((x) => x.toDict()) };
         },
     },
@@ -349,16 +340,6 @@ export const TOOLS = [
         parameters: { type: "object", properties: {} },
         handler: async () => (await getClient()).notify.unread(),
     },
-    {
-        id: "bili_notify_replies",
-        description: "获取「回复我的」消息列表（需登录）。",
-        parameters: { type: "object", properties: {} },
-        handler: async () => {
-            const c = await getClient();
-            const [items, cursor, isEnd] = await c.notify.replies();
-            return { isEnd, cursor, notices: items.map((x) => x.toDict()) };
-        },
-    },
     // ---- 收藏夹（读取） ----
     {
         id: "bili_fav_folders",
@@ -401,35 +382,24 @@ export const TOOLS = [
     },
     {
         id: "bili_favorite",
-        description: "收藏视频到收藏夹（写操作，需登录）。",
+        description: "收藏或取消收藏视频到收藏夹（写操作，需登录）。",
         parameters: {
             type: "object",
             properties: {
                 bvid: { type: "string" },
+                action: { type: "string", enum: ["add", "remove"], default: "add" },
                 folderName: { type: "string" },
             },
             required: ["bvid"],
         },
-        handler: async (a) => {
-            const fid = await (await getClient()).interact.favorite(a.bvid, undefined, a.folderName);
-            return { folderId: fid };
-        },
-    },
-    {
-        id: "bili_send_comment",
-        description: "发表视频评论（写操作，需登录）。",
-        parameters: {
-            type: "object",
-            properties: {
-                bvid: { type: "string" },
-                message: { type: "string" },
-            },
-            required: ["bvid", "message"],
-        },
         handler: async (a) => {
             const c = await getClient();
-            const comment = await c.comment.sendVideo(a.bvid, a.message);
-            return comment.toDict();
+            if (String(a.action ?? "add") === "remove") {
+                const fid = await c.interact.unfavorite(a.bvid, undefined, a.folderName);
+                return { ok: true, folderId: fid };
+            }
+            const fid = await c.interact.favorite(a.bvid, undefined, a.folderName);
+            return { ok: true, folderId: fid };
         },
     },
     {
@@ -522,19 +492,6 @@ export const TOOLS = [
             return pages.map((p) => p.toDict());
         },
     },
-    {
-        id: "bili_video_subtitles",
-        description: "列出视频可用的字幕轨（语言 / 名称 / 链接），不含正文。",
-        parameters: {
-            type: "object",
-            properties: { bvid: { type: "string" } },
-            required: ["bvid"],
-        },
-        handler: async (a) => {
-            const subs = await (await getClient()).video.subtitles(a.bvid);
-            return subs.map((s) => s.toDict());
-        },
-    },
     {
         id: "bili_video_playurl",
         description: "获取视频播放地址信息（清晰度、可用清晰度列表、durl 直链）。高清晰度可能需登录 / 大会员。",
@@ -668,22 +625,6 @@ export const TOOLS = [
             return { ok: true };
         },
     },
-    {
-        id: "bili_unfavorite",
-        description: "把视频从收藏夹移除（写操作，需登录）。",
-        parameters: {
-            type: "object",
-            properties: {
-                bvid: { type: "string" },
-                folderName: { type: "string", description: "收藏夹名（可选，默认取默认收藏夹）" },
-            },
-            required: ["bvid"],
-        },
-        handler: async (a) => {
-            const fid = await (await getClient()).interact.unfavorite(a.bvid, undefined, a.folderName);
-            return { ok: true, folderId: fid };
-        },
-    },
     {
         id: "bili_user_following",
         description: "查询我是否已关注某用户。",
@@ -885,21 +826,25 @@ export const TOOLS = [
     },
     // ---- 消息中心补充 ----
     {
-        id: "bili_notify_ats",
-        description: "获取「@我的」消息列表（需登录）。",
-        parameters: { type: "object", properties: {} },
-        handler: async () => {
-            const [items, , isEnd] = await (await getClient()).notify.ats();
-            return { isEnd, notices: items.map((x) => x.toDict()) };
+        id: "bili_notify_list",
+        description: "消息中心列表：回复我的 / @我的 / 收到的赞（需登录）。",
+        parameters: {
+            type: "object",
+            properties: {
+                type: { type: "string", enum: ["replies", "ats", "likes"], default: "replies" },
+            },
         },
-    },
-    {
-        id: "bili_notify_likes",
-        description: "获取「收到的赞」列表（需登录）。",
-        parameters: { type: "object", properties: {} },
-        handler: async () => {
-            const [items, , isEnd] = await (await getClient()).notify.likes();
-            return { isEnd, notices: items.map((x) => x.toDict()) };
+        handler: async (a) => {
+            const c = await getClient();
+            const t = String(a.type ?? "replies");
+            let items;
+            if (t === "ats")
+                [items] = await c.notify.ats();
+            else if (t === "likes")
+                [items] = await c.notify.likes();
+            else
+                [items] = await c.notify.replies();
+            return { notices: items.map((x) => x.toDict()) };
         },
     },
     // ---- 私信补充 ----
@@ -959,39 +904,36 @@ export const TOOLS = [
         parameters: { type: "object", properties: {} },
         handler: async () => (await getClient()).profile.info(),
     },
-    {
-        id: "bili_profile_update_sign",
-        description: "修改我的个性签名（写操作，需登录，会进入审核）。",
-        parameters: {
-            type: "object",
-            properties: { sign: { type: "string" } },
-            required: ["sign"],
-        },
-        handler: async (a) => {
-            await (await getClient()).profile.updateSign(String(a.sign ?? ""));
-            return { ok: true };
-        },
-    },
     {
         id: "bili_profile_update",
-        description: "修改我的昵称 / 性别 / 生日（写操作，需登录，至少改一项）。",
+        description: "修改我的昵称 / 性别 / 生日 / 签名（写操作，需登录，至少改一项）。",
         parameters: {
             type: "object",
             properties: {
                 uname: { type: "string", description: "新昵称（1~20 字符）" },
                 sex: { type: "string", enum: ["男", "女", "保密"] },
                 birthday: { type: "string", description: "YYYY-MM-DD" },
+                sign: { type: "string", description: "个性签名（≤70 字）" },
             },
         },
         handler: async (a) => {
-            await (await getClient()).profile.updateProfile(a.uname != null ? String(a.uname) : undefined, a.sex != null ? String(a.sex) : undefined, a.birthday != null ? String(a.birthday) : undefined);
+            const c = await getClient();
+            const hasProfile = a.uname != null || a.sex != null || a.birthday != null;
+            if (a.sign == null && !hasProfile) {
+                throw new Error("至少修改一项：uname / sex / birthday / sign");
+            }
+            if (a.sign != null)
+                await c.profile.updateSign(String(a.sign));
+            if (hasProfile) {
+                await c.profile.updateProfile(a.uname != null ? String(a.uname) : undefined, a.sex != null ? String(a.sex) : undefined, a.birthday != null ? String(a.birthday) : undefined);
+            }
             return { ok: true };
         },
     },
     // ---- 登录状态 ----
     {
         id: "bili_login_status",
-        description: "查询当前是否已登录 B 站（返回用户名）。【用户想登录、或任何需登录操作报未登录（-101/CookieError）时，先调用本工具】；若返回未登录，必须立即调用 bili_gen_qr 向用户展示登录二维码图片。若此前调用过 bili_gen_qr，本工具会顺带轮询扫码状态：用户扫码并在手机确认后，返回登录成功并自动保存 Cookie。",
+        description: "查登录态（返回用户名）。想登录或报未登录（-101）时先调本工具；未登录则必须立即调 bili_gen_qr 展示二维码图片。刚调过 bili_gen_qr 时本工具会顺带轮询，用户确认后自动保存 Cookie。",
         parameters: { type: "object", properties: {} },
         handler: async () => {
             const c = await getClient();
@@ -1040,7 +982,7 @@ export const TOOLS = [
     },
     {
         id: "bili_gen_qr",
-        description: "【B 站登录唯一入口】生成 B 站扫码登录二维码图片。调用后必须把返回的二维码图片展示给用户扫码（用 qrDataUrl / qrImageUrl / qrImagePath 渲染成图片），不要只给链接、不要让用户手动跑命令。返回：url（二维码内容链接）、qrcodeKey（轮询用）、qrDataUrl（base64 data URL）、qrImageUrl（file:// 链接）、qrImagePath（本地 PNG 绝对路径）。用户扫码确认后，调用 bili_login_status 完成登录并保存 Cookie。",
+        description: "【登录唯一入口】生成扫码登录二维码。必须把返回的二维码图片展示给用户扫（用 qrDataUrl / qrImageUrl / qrImagePath 渲染成图片），不要只给链接。返回 url / qrcodeKey / qrDataUrl / qrImageUrl / qrImagePath。用户确认后调 bili_login_status 完成登录。",
         parameters: { type: "object", properties: {} },
         handler: async () => {
             const c = await getClient();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-shlr-bilitoolkit",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "深海猎人专用B站接口工具箱 dsh 插件。",
   "type": "module",
   "main": "dist/dsh.js",